25 KiB
25 KiB
随工水印相机 2.0.1 需求文档
版本说明
本版本主要针对 CS 客户端进行功能增强，增加主页界面、完善数据管理功能、新增月报表导出功能。
核心原则：所有导出功能（Excel、ZIP）均在客户端本地执行，减轻服务器压力。
模块一：客户端主页界面
1.1 功能描述
新增客户端主页界面，展示统计信息和功能入口。
1.2 界面设计
┌─────────────────────────────────────────────────────────────────────┐
│ 随工水印相机 - 数据管理工具 [—][□][×] │
├─────────────────────────────────────────────────────────────────────┤
│ 服务器: [https://xxx.com ] 用户名: [admin] [登录] │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─ 统计信息 ─────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 📊 本月工作记录 📷 本月图片数 👷 本月施工人员 │ │
│ │ 256 条 512 张 15 人 │ │
│ │ │ │
│ │ 📅 今日新增 💾 数据总量 🔄 待迁移数据 │ │
│ │ 12 条 3,456 条 500 条 │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─ 功能入口 ─────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ 📋 │ │ 📊 │ │ 🔄 │ │ │
│ │ │ 工作记录 │ │ 月报表 │ │ 历史数据迁移 │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ 查看、导出 │ │ 查看、导出 │ │ 迁移到COS │ │ │
│ │ │ 工作记录数据 │ │ 月度统计报表 │ │ │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
1.3 统计信息
| 统计项 | 说明 | 数据来源 |
|---|---|---|
| 本月工作记录 | 当月工作记录总数 | API 查询 |
| 本月图片数 | 当月上传图片总数 | API 查询 |
| 本月施工人员 | 当月参与施工的人员数 | API 查询 |
| 今日新增 | 今日新增记录数 | API 查询 |
| 数据总量 | 系统工作记录总数 | API 查询 |
| 待迁移数据 | 未迁移到 COS 的记录数 | API 查询 |
1.4 功能按钮
| 按钮 | 功能 | 跳转页面 |
|---|---|---|
| 工作记录 | 查看、管理、导出工作记录 | 工作记录管理界面 |
| 月报表 | 查看、导出月度统计报表 | 月报表界面 |
| 历史数据迁移 | 将旧数据迁移到 COS | 数据迁移界面 |
模块二：工作记录管理界面
2.1 功能描述
完整实现 Web 端工作记录管理的所有功能，包括数据查看、编辑、删除、导出。
2.2 功能对照（参考 CamWorkrecord.vue）
| Web 功能 | 客户端实现 | 说明 |
|---|---|---|
| 查询筛选 | ✅ 实现 | 拍照时间、部门名称、拍照地址、工作内容、施工人员、状态 |
| 数据列表 | ✅ 实现 | 显示所有字段，支持多图预览 |
| 新增记录 | ✅ 实现 | 弹窗表单，支持多图上传 |
| 编辑记录 | ✅ 实现 | 弹窗表单，支持修改所有字段 |
| 删除记录 | ✅ 实现 | 单条删除，确认提示 |
| 查看详情 | ✅ 实现 | 弹窗查看完整信息 |
| 导出全部 | ✅ 实现 | 按查询条件导出 Excel（本地生成） |
| 导出所选 | ✅ 实现 | 多选后导出选中数据（本地生成） |
| 分页 | ✅ 实现 | 分页加载数据 |
2.3 数据列表字段
| 列名 | 字段 | 说明 |
|---|---|---|
| 选择框 | - | 多选框，用于批量操作 |
| 主键 | id | 记录 ID |
| 部门名称 | deptName | |
| 图片 | images | 多图显示，最多显示3张缩略图，超出显示"+N"，点击可放大查看 |
| 地址信息 | - | 包含拍照时间、经度、纬度、位置 |
| 工作内容 | content | |
| 施工人员 | workers | 多人用逗号分隔 |
| 状态 | statusName | 字典值显示 |
| 时间信息 | - | 包含拍照时间、创建时间、修改时间 |
| 其它信息 | remarks | WGS84/GCJ02 坐标信息 |
| 操作 | - | 详情、编辑、删除按钮 |
2.4 图片功能要求
-
缩略图显示
- 列表中每条记录最多显示 3 张缩略图
- 超过 3 张显示 "+N" 徽章
- 显示图片总数
-
图片放大查看
- 点击缩略图可放大查看
- 支持图片轮播切换
- 支持缩放、拖拽
-
多图上传
- 新增/编辑时支持上传多张图片
- 最多支持 15 张图片
- 单张图片不超过 10MB
- 支持拖拽上传
- 支持删除已上传图片
2.5 导出功能（本地执行）
2.5.1 导出流程
1. 用户设置查询条件或选择数据，点击"导出"
2. 客户端分页调用 API 获取数据（每页 50 条）
3. 解析每条记录的图片 URL
4. 并发下载图片到本地临时目录（控制并发数 5 个）
5. 全部数据获取完成后，在本地生成 Excel 文件
6. 将图片嵌入 Excel 对应单元格
7. 保存 Excel 文件到用户指定路径
8. 清理临时文件
9. 提示导出完成，可选择打开文件夹
2.5.2 Excel 格式（与 Web 端一致）
| 列号 | 列名 | 说明 |
|---|---|---|
| A | 序号 | 自增序号 |
| B | 部门名称 | |
| C | 拍照时间 | 格式：yyyy-MM-dd HH:mm:ss |
| D | 经度 | |
| E | 纬度 | |
| F | 位置 | 地址信息 |
| G | 工作内容 | |
| H | 施工人员 | 多人用逗号分隔 |
| I | 状态 | |
| J | 施工图片 | 嵌入图片，多图水平排列 |
| K | 创建时间 | 格式：yyyy-MM-dd HH:mm:ss |
| L | 更新时间 | 格式：yyyy-MM-dd HH:mm:ss |
图片处理规则：
- 图片嵌入到单元格内
- 多张图片水平排列，间距 5 像素
- 单张图片尺寸：宽 100 像素，高 60 像素
- 图片压缩质量：50%
- 行高：60 像素
2.6 界面草图
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 工作记录管理 [返回主页] │
├─────────────────────────────────────────────────────────────────────────────────┤
│ ┌─ 查询条件 ─────────────────────────────────────────────────────────────────┐ │
│ │ 拍照时间: [2025-01-01] 至 [2025-01-31] │ │
│ │ 部门名称: [ ] 拍照地址: [ ] 工作内容: [ ] │ │
│ │ 施工人员: [ ] 状态: [全部 ▼] │ │
│ │ [查询] [重置] │ │
│ └────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ [新增] [编辑] [导出] [导出所选] │
│ │
│ ┌────┬────┬────────┬─────────────────┬────────────┬──────────┬────────┬──────┐ │
│ │ ☑ │ ID │ 部门 │ 图片 │ 地址信息 │ 工作内容 │ 状态 │ 操作 │ │
│ ├────┼────┼────────┼─────────────────┼────────────┼──────────┼────────┼──────┤ │
│ │ ☐ │ 1 │ 工程部 │ [📷][📷][📷]+2 │ 北京市xxx │ 日常巡检 │ 进行中 │ 👁✏🗑│ │
│ │ ☐ │ 2 │ 工程部 │ [📷][📷] │ 北京市xxx │ 设备维护 │ 已完成 │ 👁✏🗑│ │
│ │ ☐ │ 3 │ 技术部 │ [📷] │ 上海市xxx │ 系统检查 │ 进行中 │ 👁✏🗑│ │
│ └────┴────┴────────┴─────────────────┴────────────┴──────────┴────────┴──────┘ │
│ [上一页] 1/10 [下一页] │
│ │
│ ┌────────────────────────────────────────────────────────────────────────────┐ │
│ │ ████████████████████░░░░░░░░░░░░░░░░░░░░ 45% │ │
│ │ 正在导出: 已处理 45/100 条，已下载图片 120/256 张 │ │
│ └────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
2.7 编辑/新增弹窗
┌─────────────────────────────────────────────────────────────────┐
│ 编辑工作记录 [×] │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 部门名称: [工程部 ] │
│ │
│ 图片: │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ 将文件拖到此处，或点击上传 ││
│ │ 支持上传多张图片，最多15张，单张不超过10MB ││
│ └─────────────────────────────────────────────────────────────┘│
│ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │
│ │ 📷 ❌│ │ 📷 ❌│ │ 📷 ❌│ │ 📷 ❌│ │ 📷 ❌│ │
│ │ 1 │ │ 2 │ │ 3 │ │ 4 │ │ 5 │ │
│ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ │
│ │
│ 拍照时间: [2025-01-05 10:30:00 ] │
│ 经度: [116.397470 ] │
│ 纬度: [39.908823 ] │
│ 拍照地址: [北京市东城区xxx ] │
│ 工作内容: [日常巡检 ] │
│ 状态: [进行中 ▼] │
│ 施工人员: [张三,李四 ] │
│ 备注: [ ] │
│ │
│ [取消] [提交] │
└─────────────────────────────────────────────────────────────────┘
模块三：月报表界面
3.1 功能描述
完整实现 Web 端月报表的所有功能（参考 CamWorkers.vue），所有导出操作在客户端本地执行。
3.2 功能对照
| Web 功能 | 客户端实现 | 说明 |
|---|---|---|
| 查询筛选 | ✅ 实现 | 人员名称、月份 |
| 数据列表 | ✅ 实现 | 时间、部门名称、人员名称、工作天数 |
| 导出 Excel | ✅ 实现 | 本地生成月报表 Excel |
| 下载照片 ZIP | ✅ 实现 | 本地下载并打包照片 |
3.3 数据列表字段
| 列名 | 字段 | 说明 |
|---|---|---|
| 时间 | yearMonth | 格式：YYYY-MM |
| 部门名称 | deptName | |
| 人员名称 | workerName | |
| 工作天数 | workDays |
3.4 月报表 Excel 导出（本地执行）
3.4.1 导出流程
1. 用户选择月份，点击"导出 Excel"
2. 客户端调用 API 获取月报表数据
3. 在本地生成 Excel 文件
4. 保存到用户指定路径
5. 提示导出完成
3.4.2 Excel 格式
| 列号 | 列名 | 说明 |
|---|---|---|
| A | 序号 | 自增序号 |
| B | 时间 | 格式：YYYY-MM |
| C | 部门名称 | |
| D | 人员名称 | |
| E | 工作天数 |
3.5 照片 ZIP 下载（本地执行）
3.5.1 功能说明
下载指定月份的所有工作照片，按目录结构打包成 ZIP 文件。
3.5.2 下载流程
1. 用户选择月份，点击"下载照片 ZIP"
2. 客户端调用 API 获取该月份所有工作记录及图片 URL
3. 按目录结构下载图片到本地临时目录：
/workfiles/{yyyyMM}/{yyyyMMdd}/
├── 当日照片/{图片文件名}.jpg
├── 参与人员/{人员姓名}/{图片文件名}.jpg
├── 工作内容/{工作内容}/{图片文件名}.jpg
└── 部门/{部门名称}/{图片文件名}.jpg
4. 将临时目录打包成 ZIP 文件
5. 保存到用户指定路径
6. 清理临时文件
7. 提示下载完成
3.5.3 目录结构说明
服务器端 COS 存储的目录结构：
/workfiles/{yyyyMM}/{yyyyMMdd}/
├── 当日照片/ # 按日期分类的所有照片
├── 参与人员/{人员姓名}/ # 按施工人员分类
├── 工作内容/{工作内容}/ # 按工作内容分类
└── 部门/{部门名称}/ # 按部门分类
客户端下载时需要：
- 获取该月份所有工作记录
- 根据记录中的图片 URL 解析出目录结构
- 下载图片并保持相同的目录结构
- 打包成 ZIP
3.5.4 进度显示
- 显示总图片数
- 显示已下载图片数
- 显示下载进度百分比
- 支持取消下载
3.6 界面草图
┌─────────────────────────────────────────────────────────────────────┐
│ 月报表 [返回主页] │
├─────────────────────────────────────────────────────────────────────┤
│ ┌─ 查询条件 ─────────────────────────────────────────────────────┐ │
│ │ 人员名称: [ ] 月份: [2025-01 ▼] │ │
│ │ [查询] [重置] │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │
│ [导出 Excel] [下载照片 ZIP] │
│ │
│ ┌──────────┬────────────┬────────────┬────────────┐ │
│ │ 时间 │ 部门名称 │ 人员名称 │ 工作天数 │ │
│ ├──────────┼────────────┼────────────┼────────────┤ │
│ │ 2025-01 │ 工程部 │ 张三 │ 22 │ │
│ │ 2025-01 │ 工程部 │ 李四 │ 20 │ │
│ │ 2025-01 │ 技术部 │ 王五 │ 18 │ │
│ │ 2025-01 │ 技术部 │ 赵六 │ 21 │ │
│ └──────────┴────────────┴────────────┴────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ ████████████████████░░░░░░░░░░░░░░░░░░░░ 45% │ │
│ │ 正在下载照片: 540/1200 张 │ │
│ └────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
模块四：历史数据迁移界面
此模块功能与 2.0.0 版本保持一致，详见 2.0.0 需求文档。
模块五：通用功能增强
5.1 登录状态保持
- 支持记住登录状态
- Token 过期自动刷新
- 登录失效时提示重新登录
5.2 网络异常处理
- 网络断开时提示用户
- 支持断点续传（导出/下载中断后可继续）
- 请求超时自动重试（最多 3 次）
5.3 导出任务管理
- 支持后台导出（不阻塞界面操作）
- 显示导出任务列表
- 支持取消正在进行的导出任务
- 导出完成后桌面通知
5.4 设置功能
- 默认保存路径设置
- 图片下载并发数设置（1-10）
- 图片压缩质量设置（30%-100%）
- 自动清理临时文件设置
5.5 日志功能
- 记录操作日志
- 记录错误日志
- 支持导出日志文件（用于问题排查）
后端 API 支持
6.1 新增统计接口
请求：
GET /api/workrecord/statistics
响应：
{
"code": 200,
"data": {
"monthRecordCount": 256,
"monthImageCount": 512,
"monthWorkerCount": 15,
"todayRecordCount": 12,
"totalRecordCount": 3456,
"pendingMigrationCount": 500
}
}
6.2 新增月报表图片列表接口
用于客户端下载 ZIP 时获取图片列表
请求：
GET /api/workrecord/monthImages
请求参数：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| yearMonth | string | 是 | 月份，格式 YYYY-MM |
响应：
{
"code": 200,
"data": {
"total": 1200,
"images": [
{
"recordId": 1,
"recordTime": "2025-01-05 10:30:00",
"deptName": "工程部",
"content": "日常巡检",
"workers": ["张三", "李四"],
"imageUrl": "https://xxx.cos.ap-xxx.myqcloud.com/workfiles/202501/20250105/当日照片/xxx.jpg"
}
]
}
}
6.3 复用现有接口
| 功能 | 接口 | 说明 |
|---|---|---|
| 工作记录列表 | GET /business/CamWorkrecord/list | 分页查询 |
| 工作记录详情 | GET /business/CamWorkrecord/{id} | 获取单条记录 |
| 新增工作记录 | POST /business/CamWorkrecord | |
| 修改工作记录 | PUT /business/CamWorkrecord | |
| 删除工作记录 | DELETE /business/CamWorkrecord/{id} | |
| 月报表列表 | GET /business/CamWorkers/list |
技术实现要点
7.1 图片查看器
- 使用 WinForms PictureBox 或第三方图片查看控件
- 支持图片缩放（鼠标滚轮）
- 支持图片拖拽移动
- 支持多图轮播切换（左右箭头）
7.2 多图上传
- 支持拖拽文件到上传区域
- 支持点击选择多个文件
- 实时显示上传预览
- 支持删除已选图片
7.3 数据表格
- 使用 DataGridView 控件
- 支持多选（CheckBox 列）
- 支持列宽自适应
- 支持排序
7.4 Excel 生成
- 使用 EPPlus 库生成 Excel
- 使用 SixLabors.ImageSharp 处理图片压缩
- 图片嵌入使用 EPPlus 的 Pictures.Add 方法
7.5 ZIP 打包
- 使用 System.IO.Compression.ZipFile
- 保持目录结构
- 支持大文件分块处理
7.6 并发下载
- 使用 SemaphoreSlim 控制并发数
- 使用 HttpClient 下载图片
- 支持进度回调
开发计划
| 阶段 | 内容 | 预计工时 |
|---|---|---|
| 第一阶段 | 主页界面 + 统计接口 | 1 天 |
| 第二阶段 | 工作记录管理界面（列表、查询、分页） | 1 天 |
| 第三阶段 | 工作记录管理界面（新增、编辑、删除、图片功能） | 2 天 |
| 第四阶段 | 工作记录导出功能（本地 Excel 生成） | 1 天 |
| 第五阶段 | 月报表界面 + Excel 导出 | 1 天 |
| 第六阶段 | 月报表照片 ZIP 下载 | 1 天 |
| 第七阶段 | 通用功能（设置、日志、异常处理） | 1 天 |
| 第八阶段 | 测试 + 优化 | 1 天 |
总计：约 9 个工作日