From f0113018734ad75d80f559399f7ed31814e1c3b6 Mon Sep 17 00:00:00 2001 From: zpc Date: Mon, 5 Jan 2026 08:35:18 +0800 Subject: [PATCH] =?UTF-8?q?=E9=9C=80=E6=B1=82=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/2.0.0/需求文档.md | 562 +++++++++++++++++++++++++++++++++++++ 1 file changed, 562 insertions(+) create mode 100644 docs/2.0.0/需求文档.md diff --git a/docs/2.0.0/需求文档.md b/docs/2.0.0/需求文档.md new file mode 100644 index 0000000..3b1a972 --- /dev/null +++ b/docs/2.0.0/需求文档.md @@ -0,0 +1,562 @@ +# 随工水印相机 2.0 需求文档 + +## 项目背景 + +当前系统存在以下问题： +- 服务器配置较低（2H4G 6M带宽），无法支撑大量图片上传和下载 +- 图片存储在服务器本地，占用服务器磁盘和带宽资源 +- Excel 导出功能在服务器端执行，大量图片嵌入时会占用大量内存和带宽 + +## 优化目标 + +1. 将图片存储迁移到腾讯云 COS，释放服务器带宽和存储压力 +2. 开发 CS 客户端，将 Excel 导出功能移至客户端本地执行 +3. 保持现有的目录分类结构，方便用户直接在 COS 打包下载 + +--- + +## 模块一：图片上传改造 + +### 1.1 功能描述 + +将图片上传方式从"上传到服务器"改为"客户端直传腾讯云 COS"。 + +### 1.2 业务流程 + +``` +┌─────────┐ 1.请求上传签名 ┌─────────┐ +│ 前端 │ ──────────────────▶ │ 服务器 │ +│ UniApp │ ◀────────────────── │ .NET │ +└─────────┘ 2.返回预签名URL └─────────┘ + │ + │ 3.直接上传图片（PUT） + ▼ +┌─────────┐ +│ 腾讯云 │ +│ COS │ +└─────────┘ + │ + │ 4.上传成功，前端回调服务器保存记录 + ▼ +┌─────────┐ +│ 服务器 │ +└─────────┘ +``` + +### 1.3 COS 目录结构 + +保持现有分类结构，便于用户直接打包下载： + +``` +/workfiles/{yyyyMM}/{yyyyMMdd}/ + ├── 当日照片/{图片文件名}.jpg + ├── 参与人员/{人员姓名}/{图片文件名}.jpg + ├── 工作内容/{工作内容}/{图片文件名}.jpg + └── 部门/{部门名称}/{图片文件名}.jpg +``` + +### 1.4 接口设计 + +#### 1.4.1 获取上传预签名 URL + +**请求：** +``` +POST /api/cos/getUploadUrls +``` + +**请求参数：** +```json +{ + "recordTime": "2025-01-05 10:30:00", + "deptName": "工程部", + "content": "日常巡检", + "workers": ["张三", "李四"], + "fileExt": ".jpg", + "imageCount": 3 +} +``` + +**响应：** +```json +{ + "code": 200, + "data": { + "images": [ + { + "imageId": "uuid-1", + "fileName": "1736051400_1234.jpg", + "uploadUrls": { + "daily": "https://xxx.cos.ap-xxx.myqcloud.com/workfiles/202501/20250105/当日照片/1736051400_1234.jpg?sign=xxx", + "workers": { + "张三": "https://xxx.cos.ap-xxx.myqcloud.com/workfiles/202501/20250105/参与人员/张三/1736051400_1234.jpg?sign=xxx", + "李四": "https://xxx.cos.ap-xxx.myqcloud.com/workfiles/202501/20250105/参与人员/李四/1736051400_1234.jpg?sign=xxx" + }, + "content": "https://xxx.cos.ap-xxx.myqcloud.com/workfiles/202501/20250105/工作内容/日常巡检/1736051400_1234.jpg?sign=xxx", + "dept": "https://xxx.cos.ap-xxx.myqcloud.com/workfiles/202501/20250105/部门/工程部/1736051400_1234.jpg?sign=xxx" + }, + "accessUrl": "https://xxx.cos.ap-xxx.myqcloud.com/workfiles/202501/20250105/当日照片/1736051400_1234.jpg" + } + ] + } +} +``` + +#### 1.4.2 保存工作记录（v3 新接口） + +> ⚠️ **重要说明**：原有 `/addworkrecord` (v1) 和 `/addworkrecordv2` (v2) 接口保持不变，不做任何修改。新增 v3 接口用于 COS 直传场景。 + +**请求：** +``` +POST /addworkrecordv3 +``` + +**请求参数：** +```json +{ + "deptName": "工程部", + "recordTime": "2025-01-05 10:30:00", + "longitude": "116.397470", + "latitude": "39.908823", + "address": "北京市东城区xxx", + "content": "日常巡检", + "statusName": "进行中", + "remarks": "", + "workers": ["张三", "李四"], + "imageUrls": [ + "https://xxx.cos.ap-xxx.myqcloud.com/workfiles/202501/20250105/当日照片/1736051400_1234.jpg", + "https://xxx.cos.ap-xxx.myqcloud.com/workfiles/202501/20250105/当日照片/1736051400_5678.jpg" + ] +} +``` + +**与 v2 接口的区别：** +| 字段 | v2 接口 | v3 接口 | +|------|---------|---------| +| Image | Base64 字符串 | 无 | +| Images | Base64 字符串数组 | 无 | +| imageUrls | 无 | COS URL 数组 | + +**响应：** +```json +{ + "code": 200, + "data": { + "id": 123, + "imageCount": 2 + } +} +``` + +### 1.5 前端改造要点 + +1. 拍照加水印后，先调用接口获取预签名 URL +2. 使用 `uni.uploadFile` 或 `fetch PUT` 直接上传到 COS +3. 同一张图片需要上传到多个目录（当日照片、参与人员、工作内容、部门） +4. 全部上传成功后，调用保存接口记录数据 + +### 1.6 后端改造要点 + +1. 新增腾讯云 COS SDK 依赖 +2. 配置 COS 密钥（SecretId、SecretKey、Bucket、Region） +3. 实现预签名 URL 生成逻辑 +4. **新增 v3 接口**（`/addworkrecordv3`），接收 COS URL 而非 Base64 +5. **保留 v1、v2 接口不变**，确保已发布版本兼容性 +6. v3 接口复用现有的数据库存储逻辑，仅修改图片处理部分 + +--- + +## 模块二：数据导出 API + +### 2.1 功能描述 + +提供分页查询接口，供 CS 客户端调用获取工作记录数据。 + +### 2.2 接口设计 + +#### 2.2.1 分页查询工作记录 + +**请求：** +``` +GET /api/workrecord/export/list +``` + +**请求参数：** +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| pageNum | int | 是 | 页码，从 1 开始 | +| pageSize | int | 是 | 每页条数，最大 50 | +| startDate | string | 否 | 开始日期 yyyy-MM-dd | +| endDate | string | 否 | 结束日期 yyyy-MM-dd | +| deptName | string | 否 | 部门名称 | +| workerName | string | 否 | 人员姓名 | +| content | string | 否 | 工作内容（模糊匹配） | + +**响应：** +```json +{ + "code": 200, + "data": { + "total": 1000, + "pageNum": 1, + "pageSize": 50, + "pages": 20, + "list": [ + { + "id": 1, + "deptName": "工程部", + "recordTime": "2025-01-05 10:30:00", + "longitude": "116.397470", + "latitude": "39.908823", + "address": "北京市东城区xxx", + "content": "日常巡检", + "statusName": "进行中", + "workers": ["张三", "李四"], + "images": [ + "https://xxx.cos.ap-xxx.myqcloud.com/workfiles/202501/20250105/当日照片/1736051400_1234.jpg", + "https://xxx.cos.ap-xxx.myqcloud.com/workfiles/202501/20250105/当日照片/1736051400_5678.jpg" + ], + "createTime": "2025-01-05 10:35:00", + "updateTime": "2025-01-05 10:35:00" + } + ] + } +} +``` + +### 2.3 注意事项 + +- 单页最大 50 条，防止一次性拉取过多数据 +- 接口需要登录认证 +- 客户端每次请求间隔 100ms，避免频繁请求 + +--- + +## 模块三：CS 客户端（Excel 导出工具） + +### 3.1 功能描述 + +开发一个 Windows 桌面客户端，用于导出带图片的 Excel 文件。 + +### 3.2 技术选型 + +- 框架：WinForms + .NET 8 +- 发布方式：AOT 单文件发布，双击即可运行，无需安装 +- Excel 库：MiniExcel 或 EPPlus + +### 3.3 功能模块 + +#### 3.3.1 登录模块 + +- 输入服务器地址、用户名、密码 +- 登录成功后保存 token +- 支持记住登录状态 + +#### 3.3.2 查询条件模块 + +- 日期范围选择（开始日期、结束日期） +- 部门筛选（下拉选择） +- 人员筛选（输入框） +- 工作内容筛选（输入框） + +#### 3.3.3 数据预览模块 + +- 显示符合条件的记录总数 +- 列表预览前 N 条数据 +- 显示预计导出图片数量 + +#### 3.3.4 导出模块 + +- 选择保存路径 +- 显示导出进度（已处理 X/Y 条，已下载 X/Y 张图片） +- 支持取消导出 +- 导出完成后自动打开文件夹 + +### 3.4 导出流程 + +``` +1. 用户设置查询条件，点击"开始导出" +2. 分页调用 API 获取数据（每页 50 条） +3. 解析每条记录的图片 URL +4. 并发下载图片到本地临时目录（控制并发数，如 5 个） +5. 全部数据获取完成后，生成 Excel 文件 +6. 将图片嵌入 Excel 对应单元格 +7. 保存 Excel 文件 +8. 清理临时文件 +9. 提示导出完成 +``` + +### 3.5 Excel 格式 + +> ⚠️ **重要说明**：导出的 Excel 格式必须与现有服务端导出保持一致。 + +**Excel 列定义（与现有格式一致）：** + +| 列号 | 列名 | 说明 | +|------|------|------| +| 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 像素（与图片高度一致） + +**示例效果：** +``` +┌────┬────────┬─────────────────────┬───────────┬──────────┬────────────┬──────────┬──────────┬────────┬─────────────────────┬─────────────────────┬─────────────────────┐ +│序号│部门名称│拍照时间 │经度 │纬度 │位置 │工作内容 │施工人员 │状态 │施工图片 │创建时间 │更新时间 │ +├────┼────────┼─────────────────────┼───────────┼──────────┼────────────┼──────────┼──────────┼────────┼─────────────────────┼─────────────────────┼─────────────────────┤ +│ 1 │工程部 │2025-01-05 10:30:00 │116.397470 │39.908823 │北京市xxx │日常巡检 │张三,李四 │进行中 │[图1][图2][图3] │2025-01-05 10:35:00 │2025-01-05 10:35:00 │ +│ 2 │工程部 │2025-01-05 11:00:00 │116.397470 │39.908823 │北京市xxx │设备维护 │王五 │已完成 │[图1][图2] │2025-01-05 11:05:00 │2025-01-05 11:05:00 │ +└────┴────────┴─────────────────────┴───────────┴──────────┴────────────┴──────────┴──────────┴────────┴─────────────────────┴─────────────────────┴─────────────────────┘ +``` + +**技术实现：** +- 使用 EPPlus 库生成 Excel（与服务端一致） +- 使用 SixLabors.ImageSharp 处理图片压缩 + +### 3.6 界面草图 + +``` +┌─────────────────────────────────────────────────────────┐ +│ 随工水印相机 - Excel 导出工具 [—][□][×] │ +├─────────────────────────────────────────────────────────┤ +│ 服务器: [https://xxx.com ] 用户名: [admin] [登录] │ +├─────────────────────────────────────────────────────────┤ +│ ┌─ 查询条件 ─────────────────────────────────────────┐ │ +│ │ 日期范围: [2025-01-01] 至 [2025-01-31] │ │ +│ │ 部门: [全部 ▼] 人员: [ ] │ │ +│ │ 工作内容: [ ] │ │ +│ │ [查询预览] │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ 查询结果: 共 256 条记录，约 512 张图片 │ +│ │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ 序号 │ 日期 │ 部门 │ 工作内容 │ 图片数 │ │ │ +│ │ 1 │ 2025-01-05 │ 工程部 │ 日常巡检 │ 3 │ │ │ +│ │ 2 │ 2025-01-05 │ 工程部 │ 设备维护 │ 2 │ │ │ +│ │ ... │ │ │ │ │ │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ 保存路径: [C:\Users\xxx\Desktop\导出.xlsx] [浏览...] │ +│ │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ ████████████████████░░░░░░░░░░░░░░░░░░░░ 45% │ │ +│ │ 正在下载图片: 230/512 │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ [取消] [开始导出] │ +└─────────────────────────────────────────────────────────┘ +``` + +--- + +## 模块四：历史数据迁移 + +### 4.1 功能描述 + +在 CS 客户端中集成历史数据迁移功能，将服务器本地的图片迁移到腾讯云 COS。 + +### 4.2 迁移方案 + +在 CS 客户端中新增"历史数据迁移"功能模块，通过可视化界面操作迁移。 + +### 4.3 功能设计 + +#### 4.3.1 入口 + +- 在客户端主界面增加"历史数据迁移"按钮 +- 点击后弹出迁移窗口 + +#### 4.3.2 迁移窗口功能 + +1. **数据列表展示** + - 调用 API 获取所有未迁移的记录（ImageUrl 包含旧域名的记录） + - 列表显示：序号、日期、部门、工作内容、图片数量、迁移状态 + - 支持分页加载 + +2. **筛选条件** + - 日期范围 + - 部门 + - 迁移状态（未迁移/已迁移/迁移失败） + +3. **选择操作** + - 全选/取消全选 + - 单条勾选 + - 按页全选 + +4. **迁移操作** + - 点击"开始迁移"按钮 + - 显示迁移进度（已处理 X/Y 条，已上传 X/Y 张图片） + - 支持取消迁移 + - 迁移完成后刷新列表状态 + +### 4.4 迁移流程 + +``` +1. 客户端调用 API 获取待迁移记录列表 +2. 用户选择要迁移的记录（或全选） +3. 点击"开始迁移" +4. 对于每条记录： + a. 下载原图片到本地临时目录 + b. 上传图片到 COS（保持目录结构） + c. 调用 API 更新数据库中的 ImageUrl + d. 更新迁移状态 +5. 迁移完成，显示结果统计 +``` + +### 4.5 后端 API 支持 + +#### 4.5.1 获取待迁移记录列表 + +**请求：** +``` +GET /api/workrecord/migration/list +``` + +**请求参数：** +| 参数 | 类型 | 必填 | 说明 | +|------|------|------|------| +| pageNum | int | 是 | 页码 | +| pageSize | int | 是 | 每页条数，最大 50 | +| startDate | string | 否 | 开始日期 | +| endDate | string | 否 | 结束日期 | +| status | int | 否 | 0-未迁移 1-已迁移 2-失败 | + +**响应：** +```json +{ + "code": 200, + "data": { + "total": 500, + "list": [ + { + "id": 1, + "recordTime": "2025-01-05 10:30:00", + "deptName": "工程部", + "content": "日常巡检", + "imageCount": 3, + "images": [ + { + "id": 101, + "imageUrl": "https://camera.api.suigongxj.top/workfiles/202501/20250105/当日照片/xxx.jpg" + } + ], + "migrationStatus": 0 + } + ] + } +} +``` + +#### 4.5.2 更新迁移后的 URL + +**请求：** +``` +POST /api/workrecord/migration/update +``` + +**请求参数：** +```json +{ + "recordId": 1, + "imageUrls": [ + { + "oldUrl": "https://camera.api.suigongxj.top/workfiles/xxx.jpg", + "newUrl": "https://xxx.cos.ap-xxx.myqcloud.com/workfiles/xxx.jpg" + } + ] +} +``` + +### 4.6 界面草图 + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ 历史数据迁移 [×] │ +├─────────────────────────────────────────────────────────────────────┤ +│ ┌─ 筛选条件 ─────────────────────────────────────────────────────┐ │ +│ │ 日期范围: [2024-01-01] 至 [2025-01-05] │ │ +│ │ 部门: [全部 ▼] 状态: [未迁移 ▼] [查询] │ │ +│ └────────────────────────────────────────────────────────────────┘ │ +│ │ +│ 共 500 条待迁移记录，约 1200 张图片 │ +│ │ +│ [☑] 全选当页 │ +│ ┌────┬────┬────────────┬────────┬──────────┬────────┬────────────┐ │ +│ │ ☑ │序号│ 日期 │ 部门 │ 工作内容 │ 图片数 │ 状态 │ │ +│ ├────┼────┼────────────┼────────┼──────────┼────────┼────────────┤ │ +│ │ ☑ │ 1 │ 2025-01-05 │ 工程部 │ 日常巡检 │ 3 │ 未迁移 │ │ +│ │ ☑ │ 2 │ 2025-01-05 │ 工程部 │ 设备维护 │ 2 │ 未迁移 │ │ +│ │ ☐ │ 3 │ 2025-01-04 │ 技术部 │ 系统检查 │ 5 │ 已迁移 │ │ +│ │ ☑ │ 4 │ 2025-01-04 │ 工程部 │ 管道维修 │ 4 │ 迁移失败 │ │ +│ │ ...│ │ │ │ │ │ │ │ +│ └────┴────┴────────────┴────────┴──────────┴────────┴────────────┘ │ +│ [上一页] 1/10 [下一页] │ +│ │ +│ ┌────────────────────────────────────────────────────────────────┐ │ +│ │ ████████████████████░░░░░░░░░░░░░░░░░░░░ 45% │ │ +│ │ 正在迁移: 225/500 条，已上传图片: 540/1200 张 │ │ +│ └────────────────────────────────────────────────────────────────┘ │ +│ │ +│ 已选择 450 条记录 [取消迁移] [开始迁移] │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +### 4.7 注意事项 + +- 迁移过程中客户端需要有 COS 上传权限（通过 API 获取临时密钥） +- 支持断点续传，迁移失败的记录可以重新选择迁移 +- 迁移完成后原图片仍保留在服务器，需要手动清理 +- 建议在业务低峰期执行大批量迁移 +- 客户端需要处理网络异常，支持重试机制 + +--- + +## 非功能需求 + +### 安全性 + +- COS 预签名 URL 有效期设置为 30 分钟 +- 导出 API 需要登录认证 +- COS Bucket 设置为私有读写 + +### 性能 + +- 前端上传支持并发（建议 3 个并发） +- 客户端下载图片支持并发（建议 5 个并发） +- API 分页查询单页最大 50 条 +- 客户端请求间隔 100ms + +### 兼容性 + +- CS 客户端支持 Windows 10/11 +- 前端兼容现有 UniApp 多端（H5、App、小程序） + +--- + +## 开发计划 + +| 阶段 | 内容 | 预计工时 | +|------|------|----------| +| 第一阶段 | 后端 COS 集成 + 上传接口改造 | 2 天 | +| 第二阶段 | 前端上传逻辑改造 | 2 天 | +| 第三阶段 | 导出 API 开发 | 1 天 | +| 第四阶段 | CS 客户端开发 | 3 天 | +| 第五阶段 | 历史数据迁移 | 1 天 | +| 第六阶段 | 测试 + 上线 | 1 天 | + +**总计：约 10 个工作日**