work-statistics/.kiro/specs/mobile-and-import/requirements.md

Requirements Document

Introduction

本文档描述工作统计系统的两个新增功能需求：手机端适配（包含禁止用户缩放）和数据导入功能（支持XLSX格式模板）。这些功能将提升系统的移动端用户体验，并支持批量数据导入以提高工作效率。

Glossary

• System: 工作统计系统的整体应用
• Frontend: 前端应用，基于React和Ant Design构建
• Mobile_View: 移动端视图，针对手机屏幕优化的界面
• Viewport: 浏览器视口，控制页面显示区域和缩放行为
• Import_Service: 导入服务，负责解析和处理导入的数据文件
• Import_Template: 导入模板，预定义格式的XLSX文件
• Work_Record: 工作记录实体
• XLSX: Excel文件格式，用于数据导入导出

Requirements

Requirement 1: Mobile Responsive Design

User Story: As a mobile user, I want to use the system on my phone with a properly adapted interface, so that I can manage work records conveniently on mobile devices.

Acceptance Criteria

1. THE Frontend SHALL adapt layout responsively for mobile screens (width < 768px)
2. THE Frontend SHALL use single-column layout for forms and lists on mobile devices
3. THE Frontend SHALL adjust navigation menu to mobile-friendly format (collapsible menu or bottom navigation)
4. THE Frontend SHALL ensure all buttons and interactive elements have minimum touch target size of 44x44 pixels
5. THE Frontend SHALL optimize table displays for mobile by using card-based layouts or horizontal scrolling
6. THE Frontend SHALL ensure all text remains readable without horizontal scrolling on mobile devices
7. WHEN displaying forms on mobile, THE Frontend SHALL stack form fields vertically
8. WHEN displaying the dashboard on mobile, THE Frontend SHALL reorganize statistics cards into single-column layout

Requirement 2: Disable User Zoom

User Story: As a system administrator, I want to prevent users from zooming the page on mobile devices, so that the interface maintains consistent appearance and usability.

Acceptance Criteria

1. THE Frontend SHALL set viewport meta tag to disable user scaling
2. THE Viewport SHALL include user-scalable=no attribute
3. THE Viewport SHALL set maximum-scale=1.0 to prevent zoom
4. THE Viewport SHALL set minimum-scale=1.0 to prevent zoom out
5. THE Frontend SHALL maintain initial-scale at 1.0 for proper rendering

Requirement 3: Data Import Template Download

User Story: As a manager, I want to download an import template, so that I can prepare data in the correct format for batch import.

Acceptance Criteria

1. THE System SHALL provide a downloadable XLSX import template
2. THE Import_Template SHALL contain columns: person_name, item_name, work_date, quantity
3. THE Import_Template SHALL include a header row with column names in Chinese (人员姓名, 物品名称, 工作日期, 数量)
4. THE Import_Template SHALL include example data rows demonstrating correct format
5. THE Import_Template SHALL specify date format as YYYY-MM-DD in the example
6. WHEN a user clicks the download template button, THE System SHALL download the template file named "import_template.xlsx"
7. THE Frontend SHALL display the template download button prominently in the import section

Requirement 4: Work Record Import

User Story: As a manager, I want to import work records from an XLSX file, so that I can batch create multiple records efficiently.

Acceptance Criteria

1. WHEN a user uploads an XLSX file, THE Import_Service SHALL parse the file content
2. THE Import_Service SHALL validate that uploaded file is in XLSX format
3. THE Import_Service SHALL validate that all required columns exist in the uploaded file
4. THE Import_Service SHALL validate each row's data:
   • person_name must match an existing person in the system
   • item_name must match an existing item in the system
   • work_date must be a valid date in YYYY-MM-DD format
   • quantity must be a positive number
5. IF any row contains invalid data, THEN THE Import_Service SHALL return detailed error messages indicating row number and error reason
6. IF all rows are valid, THEN THE Import_Service SHALL create work records for each row
7. WHEN import succeeds, THE System SHALL return the count of successfully imported records
8. WHEN import fails validation, THE System SHALL NOT create any records (atomic operation)
9. THE Frontend SHALL display a file upload component for selecting XLSX files
10. THE Frontend SHALL show import progress and results (success count or error details)
11. THE Frontend SHALL limit file size to 5MB maximum
12. IF file size exceeds limit, THEN THE System SHALL reject the upload with appropriate error message

Requirement 5: Import Error Handling

User Story: As a manager, I want clear error messages when import fails, so that I can correct the data and retry.

Acceptance Criteria

1. WHEN person_name does not match any existing person, THE Import_Service SHALL report "第X行: 人员 'xxx' 不存在"
2. WHEN item_name does not match any existing item, THE Import_Service SHALL report "第X行: 物品 'xxx' 不存在"
3. WHEN work_date format is invalid, THE Import_Service SHALL report "第X行: 日期格式错误，应为 YYYY-MM-DD"
4. WHEN quantity is not a positive number, THE Import_Service SHALL report "第X行: 数量必须为正数"
5. WHEN required field is empty, THE Import_Service SHALL report "第X行: 'xxx' 不能为空"
6. THE Frontend SHALL display all validation errors in a scrollable list
7. THE Frontend SHALL highlight the first error for user attention