SOMS/.kiro/specs/yearly-statistics-display-logic/requirements.md

# Requirements Document

## Introduction

This specification defines the enhanced display logic for the `GetYearlyStatisticsByMonthAsync` method in the Secondary Circuit Inspection Result Statistics service. The enhancement modifies how historical and predicted monthly data is displayed based on the current month, ensuring users see relevant historical context and future predictions in a rolling 15-month window.

## Glossary

- **System**: The Secondary Circuit Inspection Result Statistics Service
- **Historical_Data**: Actual inspection statistics data from past months stored in the database
- **Predicted_Data**: Forecasted inspection statistics data for future months calculated using prediction algorithms
- **Current_Month**: The month in which the API request is made (DateTime.Now.Month)
- **Display_Window**: The 15-month period of data shown to the user (3 months historical + current month + 11 months future/zero)
- **Zero_Data**: Monthly statistics with all count values set to 0 (used for months beyond prediction range)
- **Rolling_Window**: A time-based view that shifts based on the current month to always show relevant data

## Requirements

### Requirement 1: Historical Data Display

**User Story:** As a system user, I want to see the previous 3 months of historical data before the current month, so that I can understand recent trends leading up to the present.

#### Acceptance Criteria

1. WHEN the current month is April or later, THE System SHALL include the 3 months immediately preceding the current month in the display window
2. WHEN the current month is January, THE System SHALL include October, November, and December of the previous year in the display window
3. WHEN the current month is February, THE System SHALL include November and December of the previous year plus January of the current year in the display window
4. WHEN the current month is March, THE System SHALL include December of the previous year plus January and February of the current year in the display window
5. FOR ALL historical months in the display window, THE System SHALL retrieve actual statistics data from the database

### Requirement 2: Current Month Data Display

**User Story:** As a system user, I want to see statistics for the current month, so that I can monitor ongoing inspection activities.

#### Acceptance Criteria

1. THE System SHALL include the current month in the display window
2. THE System SHALL retrieve actual statistics data for the current month from the database
3. THE System SHALL mark the current month data as historical (IsPredicted = false)

### Requirement 3: Predicted Data Display

**User Story:** As a system user, I want to see predicted statistics for the next 3 months after the current month, so that I can plan for future inspection activities.

#### Acceptance Criteria

1. THE System SHALL generate predicted statistics for the 3 months immediately following the current month
2. THE System SHALL use the prediction algorithm to calculate predicted values based on historical data
3. THE System SHALL mark predicted month data with IsPredicted = true
4. WHEN the predicted months span across year boundaries, THE System SHALL correctly handle the year transition

### Requirement 4: Zero Data Display

**User Story:** As a system user, I want months beyond the prediction window to show zero values, so that I understand no predictions are available for those periods.

#### Acceptance Criteria

1. FOR ALL months in the display window beyond the 3-month prediction range, THE System SHALL set all count values to 0
2. THE System SHALL set TotalCount, NormalCount, AbnormalCount, and ErrorCount to 0 for zero data months
3. THE System SHALL mark zero data months with IsPredicted = false
4. THE System SHALL include empty StatisticsByModule lists for zero data months

### Requirement 5: Display Window Calculation for September

**User Story:** As a system user viewing data in September, I want to see January through December of the current year, so that I have a complete calendar year view.

#### Acceptance Criteria

1. WHEN the current month is September, THE System SHALL display months from January to December of the current year
2. THE System SHALL include June, July, and August as the 3 historical months before September
3. THE System SHALL include September as the current month
4. THE System SHALL predict October, November, and December
5. THE System SHALL NOT include any months from the next year

### Requirement 6: Display Window Calculation for October

**User Story:** As a system user viewing data in October, I want to see January of the current year through January of the next year, so that I can see the transition period.

#### Acceptance Criteria

1. WHEN the current month is October, THE System SHALL display months from January of the current year through January of the next year
2. THE System SHALL include July, August, and September as the 3 historical months before October
3. THE System SHALL include October as the current month
4. THE System SHALL predict November and December of the current year, and January of the next year
5. THE System SHALL set February through December of the next year to zero data

### Requirement 7: Display Window Calculation for November

**User Story:** As a system user viewing data in November, I want to see February of the current year through February of the next year, so that I can see the transition period.

#### Acceptance Criteria

1. WHEN the current month is November, THE System SHALL display months from February of the current year through February of the next year
2. THE System SHALL include August, September, and October as the 3 historical months before November
3. THE System SHALL include November as the current month
4. THE System SHALL predict December of the current year, and January and February of the next year
5. THE System SHALL set March through December of the next year to zero data

### Requirement 8: Display Window Calculation for December

**User Story:** As a system user viewing data in December, I want to see March of the current year through March of the next year, so that I can see the transition period.

#### Acceptance Criteria

1. WHEN the current month is December, THE System SHALL display months from March of the current year through March of the next year
2. THE System SHALL include September, October, and November as the 3 historical months before December
3. THE System SHALL include December as the current month
4. THE System SHALL predict January, February, and March of the next year
5. THE System SHALL set April through December of the next year to zero data

### Requirement 9: Display Window Calculation for January

**User Story:** As a system user viewing data in January, I want to see October through December of the previous year and January through December of the current year, so that I can see the year transition.

#### Acceptance Criteria

1. WHEN the current month is January, THE System SHALL display October, November, and December of the previous year
2. THE System SHALL display January through December of the current year
3. THE System SHALL include October, November, and December of the previous year as the 3 historical months
4. THE System SHALL include January as the current month
5. THE System SHALL predict February, March, and April of the current year
6. THE System SHALL set May through December of the current year to zero data

### Requirement 10: Display Window Calculation for February through August

**User Story:** As a system user viewing data in months February through August, I want to see a rolling 15-month window, so that I always have relevant context.

#### Acceptance Criteria

1. WHEN the current month is February through August, THE System SHALL calculate the display window starting from 3 months before the current month
2. THE System SHALL include exactly 15 months in the display window
3. THE System SHALL include 3 historical months before the current month
4. THE System SHALL include the current month
5. THE System SHALL predict the 3 months after the current month
6. THE System SHALL set the remaining 8 months to zero data

### Requirement 11: Data Consistency

**User Story:** As a system user, I want all displayed data to be consistent and accurate, so that I can make reliable decisions.

#### Acceptance Criteria

1. THE System SHALL ensure all month numbers are in the range 1-12
2. THE System SHALL ensure year values are valid four-digit years
3. THE System SHALL maintain the correct sequence of months across year boundaries
4. WHEN retrieving historical data, THE System SHALL use the existing GetStatisticsAsync method with proper date ranges
5. WHEN generating predicted data, THE System SHALL use the existing PredictMonthlyStatisticsWithModuleDetails method

### Requirement 12: Response Structure

**User Story:** As a system developer, I want the response structure to remain consistent, so that client applications continue to work correctly.

#### Acceptance Criteria

1. THE System SHALL return a YearlyStatisticsByMonthOutput object
2. THE System SHALL populate the MonthlyStatistics list with exactly 15 MonthlyStatisticsItem objects
3. EACH MonthlyStatisticsItem SHALL contain Year, Month, Statistics, and IsPredicted properties
4. THE System SHALL order MonthlyStatistics chronologically from earliest to latest month
5. THE System SHALL set the Year property of YearlyStatisticsByMonthOutput to the current year