# 随工水印相机 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 图片功能要求

1. **缩略图显示**
   - 列表中每条记录最多显示 3 张缩略图
   - 超过 3 张显示 "+N" 徽章
   - 显示图片总数

2. **图片放大查看**
   - 点击缩略图可放大查看
   - 支持图片轮播切换
   - 支持缩放、拖拽

3. **多图上传**
   - 新增/编辑时支持上传多张图片
   - 最多支持 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}/
  ├── 当日照片/          # 按日期分类的所有照片
  ├── 参与人员/{人员姓名}/  # 按施工人员分类
  ├── 工作内容/{工作内容}/  # 按工作内容分类
  └── 部门/{部门名称}/     # 按部门分类
```

客户端下载时需要：
1. 获取该月份所有工作记录
2. 根据记录中的图片 URL 解析出目录结构
3. 下载图片并保持相同的目录结构
4. 打包成 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
```

**响应：**
```json
{
  "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 |

**响应：**
```json
{
  "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 个工作日**