# Requirements Document

## Introduction

本功能为工作统计系统增加供应商管理模块，并对现有功能进行增强：确保人员和物品名称唯一性、物品关联供应商、工作记录增加结算状态、导出报表增加供应商信息、仪表盘增加供应商相关统计。

## Glossary

- **System**: 工作统计系统
- **Supplier**: 供应商实体，包含唯一名称
- **Person**: 人员实体，名称必须唯一
- **Item**: 物品实体，名称必须唯一，可关联供应商
- **WorkRecord**: 工作记录实体，包含结算状态
- **Settlement_Status**: 工作记录的结算状态（已结算/未结算）
- **Export_Service**: 导出报表服务
- **Dashboard**: 仪表盘组件
- **Migration_Script**: 数据库迁移脚本

## Requirements

### Requirement 1: 人员名称唯一性

**User Story:** As a 系统管理员, I want 人员名称是唯一的, so that 导入数据时可以通过名称准确匹配人员。

#### Acceptance Criteria

1. WHEN 创建人员时输入的名称已存在, THEN THE System SHALL 拒绝创建并返回错误信息
2. WHEN 更新人员名称为已存在的名称, THEN THE System SHALL 拒绝更新并返回错误信息
3. THE Person 数据库表 SHALL 对 name 字段添加唯一约束

### Requirement 2: 物品名称唯一性

**User Story:** As a 系统管理员, I want 物品名称是唯一的, so that 导入数据时可以通过名称准确匹配物品。

#### Acceptance Criteria

1. WHEN 创建物品时输入的名称已存在, THEN THE System SHALL 拒绝创建并返回错误信息
2. WHEN 更新物品名称为已存在的名称, THEN THE System SHALL 拒绝更新并返回错误信息
3. THE Item 数据库表 SHALL 对 name 字段添加唯一约束

### Requirement 3: 供应商管理模块

**User Story:** As a 系统管理员, I want 管理供应商信息, so that 可以追踪物品来源。

#### Acceptance Criteria

1. THE Supplier SHALL 包含以下属性：id（主键）、name（供应商名称，唯一）、created_at、updated_at
2. WHEN 创建供应商时输入的名称已存在, THEN THE System SHALL 拒绝创建并返回错误信息
3. WHEN 更新供应商名称为已存在的名称, THEN THE System SHALL 拒绝更新并返回错误信息
4. THE System SHALL 提供供应商的增删改查 API 接口
5. THE System SHALL 提供供应商管理的前端界面，包含列表展示、新增、编辑、删除功能
6. THE Supplier 数据库表 SHALL 对 name 字段添加唯一约束

### Requirement 4: 物品关联供应商

**User Story:** As a 系统管理员, I want 为物品设置供应商, so that 可以追踪物品来源。

#### Acceptance Criteria

1. THE Item SHALL 增加 supplier_id 字段，可为空（nullable）
2. WHEN 物品未设置供应商, THEN THE System SHALL 将供应商相关字段保持为空字符串
3. THE System SHALL 在物品表单中提供供应商选择下拉框
4. THE System SHALL 在物品列表中显示供应商名称

### Requirement 5: 工作记录结算状态

**User Story:** As a 系统管理员, I want 管理工作记录的结算状态, so that 可以追踪哪些记录已结算。

#### Acceptance Criteria

1. THE WorkRecord SHALL 增加 is_settled 字段，类型为布尔值，默认为 False
2. WHEN 查看工作记录列表, THEN THE System SHALL 显示每条记录的结算状态
3. WHEN 用户点击单条记录的结算按钮, THEN THE System SHALL 切换该记录的结算状态
4. THE System SHALL 提供批量操作窗口，包含人员选择器、月份选择器和供应商选择器
5. WHEN 用户在批量操作窗口选择人员、月份和供应商, THEN THE System SHALL 筛选出符合所有条件（取交集）的工作记录
6. THE System 批量操作窗口 SHALL 提供"设为已结算"和"设为未结算"两个操作按钮
7. WHEN 用户点击批量操作按钮, THEN THE System SHALL 将筛选出的所有记录统一设置为对应的结算状态
8. THE System SHALL 提供按人员、月份和供应商批量更新结算状态的 API 接口

### Requirement 6: 导出报表增加供应商

**User Story:** As a 系统管理员, I want 导出的报表包含供应商信息, so that 可以按供应商分析数据。

#### Acceptance Criteria

1. THE Export_Service 明细表 SHALL 包含以下列：人员、日期、供应商、物品、单价、数量、总价
2. THE Export_Service 月度汇总表 SHALL 包含以下列：人员、供应商、总金额
3. THE Export_Service 年度汇总表 SHALL 保持现有格式不变
4. WHEN 物品未设置供应商, THEN THE Export_Service SHALL 在供应商列显示空字符串

### Requirement 7: 仪表盘月度报告增强

**User Story:** As a 用户, I want 在月度报告中看到供应商相关统计, so that 可以了解各供应商的业绩情况。

#### Acceptance Criteria

1. THE Dashboard 月度报告物品收入明细 SHALL 增加供应商列
2. THE Dashboard 月度报告 SHALL 增加人员按供应商的收入明细表格
3. WHEN 物品未设置供应商, THEN THE Dashboard SHALL 在供应商列显示空字符串

### Requirement 8: 仪表盘工作统计详情增强

**User Story:** As a 用户, I want 在工作统计详情中看到供应商信息, so that 可以了解当日各供应商的工作情况。

#### Acceptance Criteria

1. THE Dashboard 工作统计详情表格 SHALL 增加供应商列
2. WHEN 物品未设置供应商, THEN THE Dashboard SHALL 在供应商列显示空字符串

### Requirement 9: 仪表盘系统统计增强

**User Story:** As a 用户, I want 在仪表盘看到供应商数量统计, so that 可以了解系统中的供应商规模。

#### Acceptance Criteria

1. THE Dashboard 系统统计卡片 SHALL 将"系统人员/物品"修改为"系统人员/物品/供应商"
2. THE Dashboard SHALL 显示供应商总数

### Requirement 10: 数据库迁移

**User Story:** As a 开发者, I want 有数据库迁移脚本, so that 可以安全地升级现有数据库。

#### Acceptance Criteria

1. THE Migration_Script SHALL 创建 suppliers 表
2. THE Migration_Script SHALL 为 persons 表的 name 字段添加唯一约束
3. THE Migration_Script SHALL 为 items 表的 name 字段添加唯一约束
4. THE Migration_Script SHALL 为 items 表添加 supplier_id 外键字段
5. THE Migration_Script SHALL 为 work_records 表添加 is_settled 字段，默认值为 False
6. THE Migration_Script SHALL 兼容 PostgreSQL 和 SQLite 数据库
7. WHEN 执行迁移脚本, THEN THE System SHALL 保留现有数据不丢失