# Implementation Plan: Supplier Management

## Overview

本实现计划将供应商管理功能分解为可执行的编码任务，按照数据库迁移 → 后端模型 → API → 前端的顺序实现。

## Tasks

- [x] 1. 数据库迁移脚本
  - [x] 1.1 创建迁移脚本文件 `backend/migrations/add_supplier_and_settlement.py`
    - 创建 suppliers 表（id, name, created_at, updated_at）
    - 为 suppliers.name 添加唯一索引
    - 为 persons.name 添加唯一索引
    - 为 items.name 添加唯一索引
    - 为 items 表添加 supplier_id 外键字段
    - 为 work_records 表添加 is_settled 字段（默认 False）
    - 确保兼容 PostgreSQL 和 SQLite
    - _Requirements: 10.1, 10.2, 10.3, 10.4, 10.5, 10.6, 10.7_

- [x] 2. 后端 Supplier 模型和 API
  - [x] 2.1 创建 Supplier 模型 `backend/app/models/supplier.py`
    - 定义 Supplier 类，包含 id, name, created_at, updated_at
    - 添加 to_dict() 方法
    - 在 `__init__.py` 中注册模型
    - _Requirements: 3.1, 3.6_
  - [x] 2.2 创建 Supplier 路由 `backend/app/routes/supplier.py`
    - GET /api/suppliers - 获取所有供应商
    - GET /api/suppliers/:id - 获取单个供应商
    - POST /api/suppliers - 创建供应商（验证名称唯一性）
    - PUT /api/suppliers/:id - 更新供应商（验证名称唯一性）
    - DELETE /api/suppliers/:id - 删除供应商
    - 在 `__init__.py` 中注册蓝图
    - _Requirements: 3.2, 3.3, 3.4_
  - [ ]* 2.3 编写 Supplier 单元测试 `backend/tests/test_supplier.py`
    - 测试 CRUD 操作
    - 测试名称唯一性约束
    - _Requirements: 3.2, 3.3, 3.4_
  - [ ]* 2.4 编写供应商名称唯一性属性测试
    - **Property 3: Supplier Name Uniqueness**
    - **Validates: Requirements 3.2, 3.3, 3.6**

- [x] 3. 更新 Person 模型和 API
  - [x] 3.1 更新 Person 模型添加唯一约束验证
    - 在创建和更新时验证名称唯一性
    - _Requirements: 1.1, 1.2, 1.3_
  - [x] 3.2 更新 Person 路由添加唯一性错误处理
    - POST /api/persons - 验证名称唯一性
    - PUT /api/persons/:id - 验证名称唯一性
    - _Requirements: 1.1, 1.2_
  - [ ]* 3.3 编写人员名称唯一性属性测试
    - **Property 1: Person Name Uniqueness**
    - **Validates: Requirements 1.1, 1.2, 1.3**

- [x] 4. 更新 Item 模型和 API
  - [x] 4.1 更新 Item 模型
    - 添加 supplier_id 外键字段
    - 添加 supplier 关系
    - 更新 to_dict() 返回 supplier_name（无供应商时为空字符串）
    - 添加唯一约束验证
    - _Requirements: 2.1, 2.2, 2.3, 4.1, 4.2_
  - [x] 4.2 更新 Item 路由
    - POST /api/items - 支持 supplier_id，验证名称唯一性
    - PUT /api/items/:id - 支持 supplier_id，验证名称唯一性
    - _Requirements: 2.1, 2.2, 4.1_
  - [ ]* 4.3 编写物品名称唯一性属性测试
    - **Property 2: Item Name Uniqueness**
    - **Validates: Requirements 2.1, 2.2, 2.3**
  - [ ]* 4.4 编写空供应商显示属性测试
    - **Property 4: Empty Supplier Name Display**
    - **Validates: Requirements 4.2, 6.4, 7.3, 8.2**

- [x] 5. Checkpoint - 确保所有测试通过
  - 运行所有后端测试
  - 确保迁移脚本正确执行
  - 如有问题请询问用户

- [x] 6. 更新 WorkRecord 模型和 API
  - [x] 6.1 更新 WorkRecord 模型
    - 添加 is_settled 字段（默认 False）
    - 更新 to_dict() 返回 is_settled 和 supplier_name
    - _Requirements: 5.1, 5.2_
  - [x] 6.2 添加结算状态 API
    - PUT /api/work-records/:id/settlement - 切换单条记录结算状态
    - POST /api/work-records/batch-settlement - 批量更新结算状态
      - 参数：person_id（可选）, year, month, supplier_id（可选）, is_settled
    - _Requirements: 5.3, 5.7, 5.8_
  - [ ]* 6.3 编写结算状态属性测试
    - **Property 5: Work Record Settlement Default**
    - **Property 6: Settlement Status Toggle**
    - **Validates: Requirements 5.1, 5.3**
  - [ ]* 6.4 编写批量结算筛选属性测试
    - **Property 7: Batch Settlement Filter Intersection**
    - **Validates: Requirements 5.5, 5.7**

- [x] 7. 更新导出服务
  - [x] 7.1 更新 ExportService 明细表
    - 修改 DETAIL_HEADERS 为 ['人员', '日期', '供应商', '物品', '单价', '数量', '总价']
    - 更新 _create_detail_sheet() 添加供应商列
    - _Requirements: 6.1, 6.4_
  - [x] 7.2 更新 ExportService 月度汇总表
    - 修改 _create_monthly_summary_sheet() 按人员+供应商分组
    - Headers: ['人员', '供应商', '总金额']
    - _Requirements: 6.2_
  - [ ]* 7.3 编写导出服务单元测试
    - 测试明细表包含供应商列
    - 测试月度汇总按人员+供应商分组
    - 测试无供应商时显示空字符串
    - _Requirements: 6.1, 6.2, 6.3, 6.4_

- [x] 8. 更新仪表盘 API
  - [x] 8.1 更新月度统计 API
    - 修改 item_breakdown 返回 supplier_name
    - 添加 supplier_breakdown 返回人员按供应商的收入明细
    - _Requirements: 7.1, 7.2, 7.3_
  - [x] 8.2 更新日统计 API
    - 修改 summary 返回 supplier_name
    - _Requirements: 8.1, 8.2_
  - [ ]* 8.3 编写仪表盘 API 单元测试
    - 测试月度统计包含供应商数据
    - 测试日统计包含供应商数据
    - _Requirements: 7.1, 7.2, 8.1_

- [x] 9. Checkpoint - 确保后端功能完整
  - 运行所有后端测试
  - 验证 API 响应格式正确
  - 如有问题请询问用户

- [x] 10. 前端 Supplier 管理页面
  - [x] 10.1 创建 Supplier API 服务 `frontend/src/services/api.js`
    - 添加 supplierApi 对象（getAll, getById, create, update, delete）
    - _Requirements: 3.4_
  - [x] 10.2 创建 SupplierManagement 组件 `frontend/src/components/SupplierManagement.jsx`
    - 供应商列表表格
    - 新增/编辑模态框
    - 删除确认对话框
    - 名称唯一性错误提示
    - _Requirements: 3.5_
  - [x] 10.3 更新路由配置添加供应商管理页面
    - 在 App.jsx 添加 /suppliers 路由
    - 在导航菜单添加供应商管理入口
    - _Requirements: 3.5_

- [x] 11. 前端 Item 管理页面更新
  - [x] 11.1 更新 ItemManagement 组件
    - 物品表单添加供应商下拉选择
    - 物品列表添加供应商列
    - _Requirements: 4.3, 4.4_

- [x] 12. 前端 WorkRecord 管理页面更新
  - [x] 12.1 更新 WorkRecordManagement 组件
    - 工作记录列表添加结算状态列
    - 添加单条记录结算状态切换按钮
    - _Requirements: 5.2, 5.3_
  - [x] 12.2 添加批量结算操作模态框
    - 人员选择器
    - 月份选择器
    - 供应商选择器
    - "设为已结算"和"设为未结算"按钮
    - _Requirements: 5.4, 5.5, 5.6, 5.7_

- [x] 13. 前端 Dashboard 更新
  - [x] 13.1 更新月度报告部分
    - 物品收入明细表格添加供应商列
    - 添加人员按供应商收入明细表格
    - _Requirements: 7.1, 7.2_
  - [x] 13.2 更新工作统计详情
    - 表格添加供应商列
    - _Requirements: 8.1_
  - [x] 13.3 更新系统统计卡片
    - 修改标题为"系统人员/物品/供应商"
    - 显示供应商总数
    - _Requirements: 9.1, 9.2_

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

## Notes

- 任务标记 `*` 为可选测试任务，可跳过以加快 MVP 开发
- 每个任务引用具体的需求编号以便追溯
- Checkpoint 任务用于阶段性验证
- 属性测试验证核心正确性属性