work-statistics/.kiro/specs/yearly-dashboard-summary/requirements.md

Requirements Document

Introduction

在仪表盘中添加年度汇总功能，展示与导出Excel年度报表相似的数据视图。用户可以在仪表盘中直接查看每人按月的收入统计和年度合计，无需导出Excel文件即可获得年度数据概览。

Glossary

• Dashboard: 仪表盘，系统的主页面，展示工作统计数据
• Yearly_Summary: 年度汇总，按年份统计每个人员每月的收入数据
• Person: 人员，系统中的工作人员
• Work_Record: 工作记录，记录人员的工作内容和收入
• Monthly_Breakdown: 月度明细，将年度数据按12个月份分别展示

Requirements

Requirement 1: 年度汇总数据展示

User Story: As a user, I want to view yearly summary data in the dashboard, so that I can see each person's monthly earnings and yearly totals without exporting to Excel.

Acceptance Criteria

1. WHEN a user selects a year in the dashboard, THE Dashboard SHALL display a yearly summary table showing each person's earnings by month
2. THE Yearly_Summary table SHALL display columns for: person name, earnings for each month (1-12), and yearly total
3. THE Yearly_Summary table SHALL display a grand total row showing the sum of all persons' earnings for each month and the overall yearly total
4. WHEN there are no work records for the selected year, THE Dashboard SHALL display an empty state message

Requirement 2: 年度选择器

User Story: As a user, I want to select different years to view their summaries, so that I can compare data across years.

Acceptance Criteria

1. THE Dashboard SHALL provide a year picker control for selecting the year to display
2. WHEN the year picker value changes, THE Dashboard SHALL fetch and display the yearly summary for the selected year
3. THE year picker SHALL default to the current year when the dashboard loads

Requirement 3: 年度汇总API

User Story: As a developer, I want a backend API endpoint that returns yearly summary data, so that the frontend can display the yearly summary table.

Acceptance Criteria

1. WHEN a GET request is made to the yearly summary endpoint with a year parameter, THE API SHALL return yearly summary data grouped by person with monthly breakdown
2. THE API response SHALL include: person_id, person_name, monthly earnings array (12 values), and yearly_total for each person
3. THE API response SHALL include grand totals for each month and the overall yearly total
4. IF the year parameter is invalid, THEN THE API SHALL return an appropriate error response with status code 400

Requirement 4: 数据格式一致性

User Story: As a user, I want the dashboard yearly summary to match the exported Excel format, so that I can trust the data consistency.

Acceptance Criteria

1. THE Yearly_Summary data calculation logic SHALL use the same algorithm as the Excel export yearly summary
2. THE monetary values SHALL be displayed with 2 decimal places precision
3. THE person names SHALL be sorted alphabetically in the summary table