outsource/WorkCamera
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

需求文档

Browse Source
This commit is contained in:
zpc 2026-01-05 08:35:18 +08:00
parent e3882d7366
commit f011301873
1 changed files with 562 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

562
docs/2.0.0/需求文档.md Normal file
View File

@ -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 个工作日**