WorkCamera/.kiro/specs/work-camera-2.0.1/requirements.md

Requirements Document

Introduction

随工水印相机 2.0.1 版本主要针对 CS 客户端进行功能增强，增加主页界面、完善数据管理功能、新增月报表导出功能。核心原则是所有导出功能（Excel、ZIP）均在客户端本地执行，减轻服务器压力。

Glossary

• CS_Client: Windows 桌面客户端应用程序，使用 WinForms + .NET 8 开发
• Work_Record: 工作记录，包含部门、时间、位置、工作内容、施工人员、图片等信息
• Monthly_Report: 月报表，按月统计每个施工人员的工作天数
• Image_Viewer: 图片查看器，支持缩放、拖拽、轮播的图片预览组件
• Export_Service: 导出服务，负责在客户端本地生成 Excel 和 ZIP 文件
• API_Service: API 服务，负责与后端服务器通信获取数据

Requirements

Requirement 1: 客户端主页界面

User Story: As a 管理员, I want 在客户端看到统计信息和功能入口, so that 我可以快速了解系统状态并进入各功能模块。

Acceptance Criteria

1. WHEN 用户登录成功后进入主页 THEN THE CS_Client SHALL 显示统计信息面板，包含本月工作记录数、本月图片数、本月施工人员数、今日新增数、数据总量、待迁移数据数
2. WHEN 主页加载时 THEN THE CS_Client SHALL 调用统计接口获取最新数据并显示
3. WHEN 用户点击"工作记录"按钮 THEN THE CS_Client SHALL 跳转到工作记录管理界面
4. WHEN 用户点击"月报表"按钮 THEN THE CS_Client SHALL 跳转到月报表界面
5. WHEN 用户点击"历史数据迁移"按钮 THEN THE CS_Client SHALL 跳转到数据迁移界面
6. WHEN 统计接口请求失败 THEN THE CS_Client SHALL 显示错误提示并允许用户重试

Requirement 2: 工作记录列表查询

User Story: As a 管理员, I want 按条件查询工作记录, so that 我可以快速找到需要的数据。

Acceptance Criteria

1. WHEN 用户进入工作记录管理界面 THEN THE CS_Client SHALL 显示查询条件面板，包含拍照时间范围、部门名称、拍照地址、工作内容、施工人员、状态筛选
2. WHEN 用户设置查询条件并点击"查询"按钮 THEN THE CS_Client SHALL 调用 API 获取符合条件的工作记录列表
3. WHEN 用户点击"重置"按钮 THEN THE CS_Client SHALL 清空所有查询条件并重新加载数据
4. WHEN 数据列表加载时 THEN THE CS_Client SHALL 显示分页控件，支持翻页操作
5. WHEN 数据列表显示时 THEN THE CS_Client SHALL 显示所有字段：主键、部门名称、图片、地址信息、工作内容、施工人员、状态、时间信息、其它信息、操作按钮

Requirement 3: 工作记录多图显示与预览

User Story: As a 管理员, I want 在列表中预览多张图片并放大查看, so that 我可以快速浏览工作记录的图片内容。

Acceptance Criteria

1. WHEN 工作记录包含多张图片 THEN THE CS_Client SHALL 在列表中最多显示 3 张缩略图
2. WHEN 工作记录图片超过 3 张 THEN THE CS_Client SHALL 显示 "+N" 徽章表示剩余图片数量
3. WHEN 用户点击缩略图 THEN THE Image_Viewer SHALL 打开图片放大查看窗口
4. WHEN 图片放大查看时 THEN THE Image_Viewer SHALL 支持鼠标滚轮缩放图片
5. WHEN 图片放大查看时 THEN THE Image_Viewer SHALL 支持鼠标拖拽移动图片
6. WHEN 工作记录有多张图片时 THEN THE Image_Viewer SHALL 支持左右箭头切换图片

Requirement 4: 工作记录新增与编辑

User Story: As a 管理员, I want 新增和编辑工作记录, so that 我可以管理工作记录数据。

Acceptance Criteria

1. WHEN 用户点击"新增"按钮 THEN THE CS_Client SHALL 打开新增工作记录弹窗
2. WHEN 用户点击"编辑"按钮 THEN THE CS_Client SHALL 打开编辑工作记录弹窗并加载现有数据
3. WHEN 编辑弹窗打开时 THEN THE CS_Client SHALL 显示所有可编辑字段：部门名称、图片、拍照时间、经度、纬度、拍照地址、工作内容、状态、施工人员、备注
4. WHEN 用户上传图片时 THEN THE CS_Client SHALL 支持拖拽上传和点击选择多个文件
5. WHEN 用户上传图片时 THEN THE CS_Client SHALL 限制最多 15 张图片，单张不超过 10MB
6. WHEN 用户点击图片上的删除按钮 THEN THE CS_Client SHALL 从上传列表中移除该图片
7. WHEN 用户点击"提交"按钮 THEN THE CS_Client SHALL 调用 API 保存数据并刷新列表
8. IF 提交失败 THEN THE CS_Client SHALL 显示错误信息并保持弹窗打开

Requirement 5: 工作记录删除

User Story: As a 管理员, I want 删除工作记录, so that 我可以清理无效数据。

Acceptance Criteria

1. WHEN 用户点击"删除"按钮 THEN THE CS_Client SHALL 显示确认删除对话框
2. WHEN 用户确认删除 THEN THE CS_Client SHALL 调用 API 删除记录并刷新列表
3. IF 删除失败 THEN THE CS_Client SHALL 显示错误信息

Requirement 6: 工作记录导出 Excel（本地执行）

User Story: As a 管理员, I want 导出工作记录到 Excel 文件, so that 我可以离线查看和分享数据。

Acceptance Criteria

1. WHEN 用户点击"导出"按钮 THEN THE CS_Client SHALL 按当前查询条件导出所有数据
2. WHEN 用户选择数据后点击"导出所选"按钮 THEN THE CS_Client SHALL 仅导出选中的数据
3. WHEN 导出开始时 THEN THE Export_Service SHALL 分页调用 API 获取数据（每页 50 条）
4. WHEN 获取数据后 THEN THE Export_Service SHALL 并发下载图片到本地临时目录（并发数 5）
5. WHEN 所有数据和图片下载完成后 THEN THE Export_Service SHALL 在本地生成 Excel 文件
6. WHEN 生成 Excel 时 THEN THE Export_Service SHALL 将图片嵌入对应单元格，多图水平排列，间距 5 像素
7. WHEN 生成 Excel 时 THEN THE Export_Service SHALL 设置图片尺寸为宽 100 像素、高 60 像素，压缩质量 50%
8. WHEN 导出进行中 THEN THE CS_Client SHALL 显示进度条，包含已处理记录数和已下载图片数
9. WHEN 用户点击"取消"按钮 THEN THE Export_Service SHALL 停止导出并清理临时文件
10. WHEN 导出完成 THEN THE CS_Client SHALL 提示用户并可选择打开文件夹

Requirement 7: 月报表查询与显示

User Story: As a 管理员, I want 查看月度工作统计报表, so that 我可以了解每个施工人员的工作情况。

Acceptance Criteria

1. WHEN 用户进入月报表界面 THEN THE CS_Client SHALL 显示查询条件面板，包含人员名称和月份选择
2. WHEN 用户设置查询条件并点击"查询"按钮 THEN THE CS_Client SHALL 调用 API 获取月报表数据
3. WHEN 数据列表显示时 THEN THE CS_Client SHALL 显示字段：时间（YYYY-MM）、部门名称、人员名称、工作天数

Requirement 8: 月报表 Excel 导出（本地执行）

User Story: As a 管理员, I want 导出月报表到 Excel 文件, so that 我可以离线查看和分享统计数据。

Acceptance Criteria

1. WHEN 用户点击"导出 Excel"按钮 THEN THE Export_Service SHALL 获取当前查询结果数据
2. WHEN 导出时 THEN THE Export_Service SHALL 在本地生成 Excel 文件，包含序号、时间、部门名称、人员名称、工作天数列
3. WHEN 导出完成 THEN THE CS_Client SHALL 提示用户并可选择打开文件夹

Requirement 9: 月报表照片 ZIP 下载（本地执行）

User Story: As a 管理员, I want 下载指定月份的所有工作照片打包成 ZIP, so that 我可以批量获取照片存档。

Acceptance Criteria

1. WHEN 用户选择月份并点击"下载照片 ZIP"按钮 THEN THE CS_Client SHALL 调用 API 获取该月份所有工作记录及图片 URL
2. WHEN 获取图片列表后 THEN THE Export_Service SHALL 按目录结构下载图片到本地临时目录
3. WHEN 下载图片时 THEN THE Export_Service SHALL 保持目录结构：/workfiles/{yyyyMM}/{yyyyMMdd}/当日照片/、参与人员/{人员姓名}/、工作内容/{工作内容}/、部门/{部门名称}/
4. WHEN 所有图片下载完成后 THEN THE Export_Service SHALL 将临时目录打包成 ZIP 文件
5. WHEN 下载进行中 THEN THE CS_Client SHALL 显示进度条，包含总图片数和已下载图片数
6. WHEN 用户点击"取消"按钮 THEN THE Export_Service SHALL 停止下载并清理临时文件
7. WHEN 下载完成 THEN THE CS_Client SHALL 提示用户并可选择打开文件夹

Requirement 10: 通用功能 - 登录状态管理

User Story: As a 用户, I want 客户端记住我的登录状态, so that 我不需要每次都重新登录。

Acceptance Criteria

1. WHEN 用户勾选"记住登录"并登录成功 THEN THE CS_Client SHALL 保存登录凭证到本地
2. WHEN 客户端启动时 THEN THE CS_Client SHALL 自动加载保存的登录凭证并尝试登录
3. WHEN Token 即将过期时 THEN THE API_Service SHALL 自动刷新 Token
4. WHEN Token 刷新失败或登录失效 THEN THE CS_Client SHALL 提示用户重新登录

Requirement 11: 通用功能 - 网络异常处理

User Story: As a 用户, I want 客户端能处理网络异常, so that 我的操作不会因网络问题丢失。

Acceptance Criteria

1. WHEN 网络断开时 THEN THE CS_Client SHALL 显示网络断开提示
2. WHEN API 请求超时 THEN THE API_Service SHALL 自动重试（最多 3 次）
3. WHEN 导出/下载中断 THEN THE Export_Service SHALL 支持断点续传

Requirement 12: 通用功能 - 设置与日志

User Story: As a 用户, I want 自定义客户端设置并查看操作日志, so that 我可以按需配置客户端并排查问题。

Acceptance Criteria

1. WHEN 用户打开设置界面 THEN THE CS_Client SHALL 显示可配置项：默认保存路径、图片下载并发数（1-10）、图片压缩质量（30%-100%）、自动清理临时文件
2. WHEN 用户修改设置并保存 THEN THE CS_Client SHALL 持久化设置到本地配置文件
3. WHEN 用户执行操作时 THEN THE CS_Client SHALL 记录操作日志和错误日志
4. WHEN 用户需要排查问题时 THEN THE CS_Client SHALL 支持导出日志文件