# Implementation Plan: System Enhancements

## Overview

本实现计划将在现有工作统计系统基础上添加：JWT认证、管理员管理、工作记录月份筛选、北京时间显示、仪表盘月报功能。实现顺序为：后端认证 → 管理员管理 → 月份筛选 → 月报API → 前端认证 → 前端功能增强。

## Tasks

- [x] 1. 后端认证基础设施
  - [x] 1.1 添加认证相关依赖到requirements.txt
    - 添加 PyJWT、Flask-Bcrypt 依赖
    - _Requirements: 1.2, 2.9_
  - [x] 1.2 创建Admin模型
    - 在 backend/app/models/admin.py 创建Admin模型
    - 包含 id、username、password_hash、created_at、updated_at 字段
    - username 设置为唯一索引
    - _Requirements: 2.1_
  - [x] 1.3 更新配置文件添加JWT设置
    - 在 backend/app/config.py 添加 JWT_SECRET_KEY、JWT_EXPIRATION_DAYS、JWT_ALGORITHM
    - _Requirements: 1.8_
  - [x] 1.4 创建认证服务
    - 在 backend/app/services/auth_service.py 实现 JWT 生成和验证
    - 实现 generate_token(admin) 和 verify_token(token) 方法
    - _Requirements: 1.2, 1.8, 1.10_
  - [x] 1.5 创建认证装饰器
    - 在 backend/app/utils/auth_decorator.py 创建 @require_auth 装饰器
    - 验证 Authorization header 中的 JWT token
    - 返回 401 状态码对于无效/过期/缺失的 token
    - _Requirements: 1.5, 1.6, 1.7_

- [x] 2. 后端认证API
  - [x] 2.1 创建认证路由
    - 在 backend/app/routes/auth.py 创建登录端点 POST /api/auth/login
    - 实现 GET /api/auth/me 获取当前管理员信息
    - _Requirements: 1.2, 1.3_
  - [ ]* 2.2 编写认证属性测试
    - **Property 1: JWT Authentication Round-Trip**
    - **Property 2: Invalid Credentials Rejection**
    - **Property 3: Protected Endpoint Authentication**
    - **Validates: Requirements 1.2, 1.3, 1.5, 1.6, 1.8, 1.10**

- [x] 3. 后端管理员管理
  - [x] 3.1 创建管理员服务
    - 在 backend/app/services/admin_service.py 实现管理员 CRUD
    - 实现密码哈希存储（bcrypt）
    - 实现用户名唯一性检查
    - 实现密码长度验证（>=6字符）
    - 实现最后一个管理员删除保护
    - _Requirements: 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9_
  - [x] 3.2 创建管理员路由
    - 在 backend/app/routes/admin.py 创建管理员 CRUD 端点
    - 所有端点使用 @require_auth 装饰器保护
    - 列表接口不返回 password_hash
    - _Requirements: 2.2, 2.3, 2.4, 2.5_
  - [ ]* 3.3 编写管理员属性测试
    - **Property 4: Admin CRUD Round-Trip**
    - **Property 5: Admin Username Uniqueness**
    - **Property 6: Admin Password Validation**
    - **Property 7: Password Secure Hashing**
    - **Validates: Requirements 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.9**

- [x] 4. 保护现有API端点
  - [x] 4.1 为所有现有路由添加认证装饰器
    - 修改 person.py、item.py、work_record.py、export.py 路由
    - 为所有端点添加 @require_auth 装饰器
    - _Requirements: 1.6_

- [x] 5. Checkpoint - 后端认证功能验证
  - 确保所有测试通过，如有问题请询问用户

- [x] 6. 后端月份筛选和月报
  - [x] 6.1 扩展工作记录服务支持月份筛选
    - 修改 backend/app/services/work_record_service.py
    - 添加 year 和 month 参数支持
    - 实现月份范围过滤逻辑
    - _Requirements: 3.1, 3.2, 3.5_
  - [x] 6.2 扩展工作记录路由支持月份筛选
    - 修改 GET /api/work-records 支持 year 和 month 查询参数
    - _Requirements: 3.2_
  - [x] 6.3 创建月度汇总API
    - 在 work_record_service.py 添加 get_monthly_summary 方法
    - 在 work_record.py 路由添加 GET /api/work-records/monthly-summary
    - 返回 total_records、total_earnings、top_performers、item_breakdown
    - _Requirements: 5.2, 5.3, 5.4, 5.5_
  - [ ]* 6.4 编写月份筛选和月报属性测试
    - **Property 8: Work Record Month Filter Consistency**
    - **Property 10: Monthly Summary Consistency**
    - **Validates: Requirements 3.1, 3.2, 3.5, 5.2, 5.3, 5.4, 5.5**

- [x] 7. Checkpoint - 后端功能完成验证
  - 确保所有后端测试通过，如有问题请询问用户

- [x] 8. 前端认证基础设施
  - [x] 8.1 安装前端依赖
    - 添加 dayjs 依赖用于时间处理
    - _Requirements: 4.1_
  - [x] 8.2 创建时间工具函数
    - 在 frontend/src/utils/timeUtils.js 创建北京时间转换函数
    - 实现 toBeijingDateTime 和 toBeijingDate 函数
    - _Requirements: 4.1, 4.2, 4.4_
  - [x] 8.3 创建认证上下文
    - 在 frontend/src/contexts/AuthContext.jsx 创建 AuthProvider
    - 实现 login、logout、isAuthenticated 状态管理
    - 从 localStorage 读取/存储 token
    - _Requirements: 1.2, 1.4, 1.9_
  - [x] 8.4 修改API服务添加JWT头
    - 修改 frontend/src/services/api.js
    - 添加 axios 拦截器自动附加 Authorization header
    - 处理 401 响应自动跳转登录页
    - _Requirements: 1.5, 1.9_

- [x] 9. 前端登录页面
  - [x] 9.1 创建登录页面组件
    - 在 frontend/src/components/Login.jsx 创建登录表单
    - 使用 Ant Design Form 组件
    - 显示登录错误信息
    - _Requirements: 1.2, 1.3_
  - [x] 9.2 创建受保护路由组件
    - 在 frontend/src/components/ProtectedRoute.jsx 创建路由守卫
    - 未认证时重定向到登录页
    - _Requirements: 1.1_
  - [x] 9.3 更新App.jsx添加认证路由
    - 修改 frontend/src/App.jsx
    - 添加 AuthProvider 包装
    - 添加 /login 路由
    - 使用 ProtectedRoute 保护其他路由
    - _Requirements: 1.1_

- [x] 10. 前端管理员管理页面
  - [x] 10.1 创建管理员列表组件
    - 在 frontend/src/components/AdminList.jsx 创建管理员列表
    - 使用 Ant Design Table 组件
    - 支持新增、编辑、删除操作
    - _Requirements: 2.2, 2.3, 2.4, 2.5_
  - [x] 10.2 创建管理员表单组件
    - 在 frontend/src/components/AdminForm.jsx 创建管理员表单
    - 使用 Modal + Form 组件
    - 显示验证错误信息
    - _Requirements: 2.2, 2.4, 2.6, 2.7_
  - [x] 10.3 添加管理员管理路由和导航
    - 修改 App.jsx 添加 /admins 路由
    - 修改 Layout.jsx 添加管理员管理菜单项
    - _Requirements: 2.2_

- [x] 11. 前端时间格式化更新
  - [x] 11.1 更新所有组件使用北京时间格式
    - 修改 PersonList.jsx、ItemList.jsx、WorkRecordList.jsx
    - 使用 toBeijingDateTime 格式化 created_at、updated_at
    - 使用 toBeijingDate 格式化 work_date
    - _Requirements: 4.1, 4.2, 4.3, 4.4_
  - [ ]* 11.2 编写时间格式化单元测试
    - **Property 9: DateTime Beijing Time Formatting**
    - **Validates: Requirements 4.1, 4.2, 4.4**

- [x] 12. 前端工作记录月份筛选
  - [x] 12.1 更新工作记录列表添加月份筛选
    - 修改 frontend/src/components/WorkRecordList.jsx
    - 添加 MonthPicker 组件
    - 调用 API 时传递 year 和 month 参数
    - _Requirements: 3.1, 3.3, 3.4, 3.5_

- [x] 13. 前端仪表盘月报
  - [x] 13.1 更新仪表盘添加月报功能
    - 修改 frontend/src/components/Dashboard.jsx
    - 添加月份选择器
    - 显示月度统计：总记录数、总收入
    - 显示业绩排名表格
    - 显示物品收入明细
    - _Requirements: 5.1, 5.2, 5.3, 5.4, 5.5, 5.6, 5.7_

- [x] 14. 前端登出功能
  - [x] 14.1 添加登出按钮和功能
    - 修改 Layout.jsx 添加登出按钮
    - 点击登出清除 token 并跳转登录页
    - _Requirements: 1.4_

- [x] 15. 创建默认管理员
  - [x] 15.1 添加数据库初始化脚本
    - 创建默认管理员账户（如 admin/admin123）
    - 在应用启动时检查并创建
    - _Requirements: 2.1_

- [x] 16. Final Checkpoint - 完整功能验证
  - 确保所有测试通过
  - 验证前后端集成正常
  - 如有问题请询问用户

## Notes

- Tasks marked with `*` are optional and can be skipped for faster MVP
- 实现顺序：后端认证 → 管理员管理 → 月份筛选 → 前端认证 → 前端功能
- 每个阶段完成后进行 checkpoint 验证
- 属性测试验证核心业务逻辑的正确性