work-statistics/.kiro/specs/work-statistics-system/requirements.md

Requirements Document

Introduction

工作统计系统是一个用于记录和管理人员工作产出的应用。系统支持管理人员信息、物品信息，记录每日工作量，并提供按月/年导出Excel报表的功能。后端使用Python，前端使用React，数据存储使用PostgreSQL（测试使用SQLite）。

Glossary

• System: 工作统计系统的整体应用
• Person: 被记录工作的人员实体
• Item: 物品实体，包含名称和单价
• Work_Record: 人员工作记录，记录某人在某天做了某物品多少件
• API_Server: 后端RESTful API服务
• Frontend: React前端应用
• Export_Service: Excel导出服务

Requirements

Requirement 1: Person Management

User Story: As a manager, I want to manage person information, so that I can track who is doing the work.

Acceptance Criteria

1. WHEN a manager submits a person name via POST request, THE System SHALL create a new person record and return the created person data
2. WHEN a manager requests the person list via GET request, THE System SHALL return all person records with their IDs and names
3. WHEN a manager submits an update for a person via POST request, THE System SHALL update the person's name and return the updated data
4. WHEN a manager submits a delete request for a person via POST request, THE System SHALL remove the person record from the system
5. IF a person name is empty or whitespace only, THEN THE System SHALL reject the request and return a validation error

Requirement 2: Item Management

User Story: As a manager, I want to manage item information with prices, so that I can calculate work value.

Acceptance Criteria

1. WHEN a manager submits item data (name, unit_price) via POST request, THE System SHALL create a new item record and return the created item data
2. WHEN a manager requests the item list via GET request, THE System SHALL return all item records with their IDs, names, and unit prices
3. WHEN a manager submits an update for an item via POST request, THE System SHALL update the item's name and/or unit_price and return the updated data
4. WHEN a manager submits a delete request for an item via POST request, THE System SHALL remove the item record from the system
5. IF an item name is empty or unit_price is not a positive number, THEN THE System SHALL reject the request and return a validation error

Requirement 3: Work Record Management

User Story: As a manager, I want to record daily work output for each person, so that I can track productivity.

Acceptance Criteria

1. WHEN a manager submits work record data (person_id, item_id, date, quantity) via POST request, THE System SHALL create a new work record and return the created record with calculated total_price
2. WHEN a manager requests work records via GET request with optional filters (person_id, date_range), THE System SHALL return matching work records with person name, item name, unit_price, quantity, and total_price
3. WHEN a manager submits an update for a work record via POST request, THE System SHALL update the record and recalculate total_price
4. WHEN a manager submits a delete request for a work record via POST request, THE System SHALL remove the work record from the system
5. IF the quantity is not a positive integer, THEN THE System SHALL reject the request and return a validation error
6. IF the referenced person_id or item_id does not exist, THEN THE System SHALL reject the request and return a reference error

Requirement 4: Daily Summary

User Story: As a manager, I want to view daily summaries, so that I can see each person's daily output.

Acceptance Criteria

1. WHEN a manager requests daily summary via GET request with a date, THE System SHALL return aggregated work data grouped by person showing total items and total value for that day
2. WHEN a manager requests daily summary for a person via GET request, THE System SHALL return that person's work records for the specified date with item breakdown

Requirement 5: Excel Export - Monthly

User Story: As a manager, I want to export monthly reports to Excel, so that I can share and archive work statistics.

Acceptance Criteria

1. WHEN a manager requests monthly export via GET request with year and month parameters, THE System SHALL generate an Excel file containing all work records for that month
2. THE Export_Service SHALL format the Excel with columns: Person, Date, Item, Unit_Price, Quantity, Total_Price
3. THE Export_Service SHALL include a summary sheet showing each person's monthly total earnings
4. THE Export_Service SHALL return the Excel file as a downloadable attachment

Requirement 6: Excel Export - Yearly

User Story: As a manager, I want to export yearly reports to Excel, so that I can review annual performance.

Acceptance Criteria

1. WHEN a manager requests yearly export via GET request with year parameter, THE System SHALL generate an Excel file containing all work records for that year
2. THE Export_Service SHALL format the Excel with columns: Person, Date, Item, Unit_Price, Quantity, Total_Price
3. THE Export_Service SHALL include a summary sheet showing each person's yearly total earnings broken down by month
4. THE Export_Service SHALL return the Excel file as a downloadable attachment

Requirement 7: Data Persistence

User Story: As a system administrator, I want data to be persisted reliably, so that work records are not lost.

Acceptance Criteria

1. THE System SHALL store all data in PostgreSQL for production environment
2. THE System SHALL support SQLite for testing environment
3. WHEN data is saved, THE System SHALL persist it immediately to the database
4. THE System SHALL maintain referential integrity between Person, Item, and Work_Record entities

Requirement 8: API Design

User Story: As a developer, I want RESTful APIs using only GET and POST methods, so that the system is easy to integrate.

Acceptance Criteria

1. THE API_Server SHALL use GET method for all read operations (list, retrieve, export)
2. THE API_Server SHALL use POST method for all write operations (create, update, delete)
3. THE API_Server SHALL return JSON responses with consistent structure for all endpoints
4. THE API_Server SHALL return appropriate HTTP status codes (200 for success, 400 for validation errors, 404 for not found, 500 for server errors)

Requirement 9: Frontend Interface

User Story: As a manager, I want a user-friendly web interface, so that I can easily manage work statistics.

Acceptance Criteria

1. THE Frontend SHALL provide pages for Person management (list, add, edit, delete)
2. THE Frontend SHALL provide pages for Item management (list, add, edit, delete)
3. THE Frontend SHALL provide pages for Work Record management (list, add, edit, delete, filter by person/date)
4. THE Frontend SHALL provide a dashboard showing daily summaries
5. THE Frontend SHALL provide export buttons for monthly and yearly Excel reports
6. THE Frontend SHALL display validation errors returned from the API