diff --git a/.kiro/specs/work-camera-2.0/design.md b/.kiro/specs/work-camera-2.0/design.md new file mode 100644 index 0000000..0c41ba7 --- /dev/null +++ b/.kiro/specs/work-camera-2.0/design.md @@ -0,0 +1,480 @@ +# Design Document + +## Overview + +随工水印相机 2.0 系统升级设计,主要包含四个核心模块: +1. **图片上传改造** - 将图片存储从服务器本地迁移到腾讯云 COS,实现客户端直传 +2. **数据导出 API** - 提供分页查询接口供 CS 客户端调用 +3. **CS 客户端** - Windows 桌面应用,实现本地 Excel 导出 +4. **历史数据迁移** - 将服务器本地图片迁移到 COS + +## Architecture + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ System Architecture │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │ +│ │ UniApp │ │ CS Client │ │ 腾讯云 COS │ │ +│ │ (Mobile) │ │ (Windows) │ │ (ap-shanghai) │ │ +│ └──────┬───────┘ └──────┬───────┘ └────────────┬─────────────┘ │ +│ │ │ │ │ +│ │ 1.获取预签名URL │ │ │ +│ ├────────────────────┼──────────────────────────┤ │ +│ │ │ │ │ +│ │ 2.直传图片 ────────┼──────────────────────────► │ +│ │ │ │ │ +│ │ 3.保存记录 │ 4.查询/导出 │ │ +│ ├────────────────────┼──────────────────────────┤ │ +│ │ │ │ │ +│ ▼ ▼ │ │ +│ ┌──────────────────────────────────────────────────────┤ │ +│ │ .NET API Server │ │ +│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ +│ │ │ CosService │ │ WorkRecord │ │ Migration │ │ │ +│ │ │ │ │ Service │ │ Service │ │ │ +│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌──────────────────┐ │ +│ │ SQL Server │ │ +│ │ Database │ │ +│ └──────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +## Components and Interfaces + +### 1. COS Service (后端) + +负责腾讯云 COS 相关操作,包括生成预签名 URL 和临时密钥。 + +```csharp +public interface ICosService +{ + /// + /// 生成批量上传预签名URL + /// + /// 上传请求参数 + /// 预签名URL列表 + CosUploadUrlsResponse GetUploadUrls(CosUploadUrlsRequest request); + + /// + /// 获取临时密钥(用于迁移) + /// + /// 临时密钥信息 + CosTempCredentials GetTempCredentials(); +} +``` + +### 2. COS Controller (后端) + +提供 COS 相关的 HTTP 接口。 + +```csharp +[Route("api/cos")] +public class CosController : BaseController +{ + /// + /// 获取上传预签名URL + /// POST /api/cos/getUploadUrls + /// + Task GetUploadUrls([FromBody] CosUploadUrlsRequest request); + + /// + /// 获取临时密钥 + /// GET /api/cos/getTempCredentials + /// + Task GetTempCredentials(); +} +``` + +### 3. WorkRecord V3 接口 (后端) + +新增支持 COS URL 的工作记录保存接口。 + +```csharp +/// +/// 添加工作记录(COS直传 v3) +/// POST /addworkrecordv3 +/// +Task AddCamWorkRecordV3([FromBody] CamRecordWorkV3Dto parm); +``` + +### 4. Export API (后端) + +提供数据导出查询接口。 + +```csharp +[Route("api/workrecord/export")] +public class WorkRecordExportController : BaseController +{ + /// + /// 分页查询工作记录(导出用) + /// GET /api/workrecord/export/list + /// + Task GetExportList([FromQuery] WorkRecordExportQueryDto query); +} +``` + +### 5. Migration API (后端) + +提供历史数据迁移相关接口。 + +```csharp +[Route("api/workrecord/migration")] +public class WorkRecordMigrationController : BaseController +{ + /// + /// 获取待迁移记录列表 + /// GET /api/workrecord/migration/list + /// + Task GetMigrationList([FromQuery] MigrationQueryDto query); + + /// + /// 更新迁移后的URL + /// POST /api/workrecord/migration/update + /// + Task UpdateMigrationUrls([FromBody] MigrationUpdateDto dto); +} +``` + +### 6. CS Client Architecture + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ CS Client (WinForms) │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ +│ │ MainForm │ │ MigrationForm │ │ LoginForm │ │ +│ │ (导出界面) │ │ (迁移界面) │ │ (登录界面) │ │ +│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │ +│ │ │ │ │ +│ ▼ ▼ ▼ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ Services Layer │ │ +│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │ │ +│ │ │ ApiService │ │ CosService │ │ ExcelService │ │ │ +│ │ │ (HTTP调用) │ │ (COS上传) │ │ (Excel生成) │ │ │ +│ │ └─────────────┘ └─────────────┘ └─────────────────┘ │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +## Data Models + +### 1. COS 上传请求/响应 DTO + +```csharp +/// +/// COS上传URL请求 +/// +public class CosUploadUrlsRequest +{ + public DateTime RecordTime { get; set; } + public string DeptName { get; set; } + public string Content { get; set; } + public List Workers { get; set; } + public string FileExt { get; set; } = ".jpg"; + public int ImageCount { get; set; } +} + +/// +/// COS上传URL响应 +/// +public class CosUploadUrlsResponse +{ + public List Images { get; set; } +} + +/// +/// 单张图片上传信息 +/// +public class CosImageUploadInfo +{ + public string ImageId { get; set; } + public string FileName { get; set; } + public CosUploadUrls UploadUrls { get; set; } + public string AccessUrl { get; set; } +} + +/// +/// 各分类目录的上传URL +/// +public class CosUploadUrls +{ + public string Daily { get; set; } + public Dictionary Workers { get; set; } + public string Content { get; set; } + public string Dept { get; set; } +} +``` + +### 2. 工作记录 V3 DTO + +```csharp +/// +/// 工作记录V3请求(COS直传) +/// +public class CamRecordWorkV3Dto +{ + public int? Id { get; set; } + public string DeptName { get; set; } + public DateTime? RecordTime { get; set; } + public string Longitude { get; set; } + public string Latitude { get; set; } + public string Address { get; set; } + public string Content { get; set; } + public string StatusName { get; set; } + public string Remarks { get; set; } + public List Workers { get; set; } + /// + /// COS图片URL列表(替代Base64) + /// + public List ImageUrls { get; set; } +} +``` + +### 3. 导出查询 DTO + +```csharp +/// +/// 导出查询请求 +/// +public class WorkRecordExportQueryDto +{ + public int PageNum { get; set; } = 1; + public int PageSize { get; set; } = 50; + public DateTime? StartDate { get; set; } + public DateTime? EndDate { get; set; } + public string DeptName { get; set; } + public string WorkerName { get; set; } + public string Content { get; set; } +} + +/// +/// 导出记录响应 +/// +public class WorkRecordExportDto +{ + public int Id { get; set; } + public string DeptName { get; set; } + public DateTime? RecordTime { get; set; } + public string Longitude { get; set; } + public string Latitude { get; set; } + public string Address { get; set; } + public string Content { get; set; } + public string StatusName { get; set; } + public List Workers { get; set; } + public List Images { get; set; } + public DateTime? CreateTime { get; set; } + public DateTime? UpdateTime { get; set; } +} +``` + +### 4. 迁移相关 DTO + +```csharp +/// +/// 迁移查询请求 +/// +public class MigrationQueryDto +{ + public int PageNum { get; set; } = 1; + public int PageSize { get; set; } = 50; + public DateTime? StartDate { get; set; } + public DateTime? EndDate { get; set; } + public int? Status { get; set; } // 0-未迁移 1-已迁移 2-失败 +} + +/// +/// 迁移记录响应 +/// +public class MigrationRecordDto +{ + public int Id { get; set; } + public DateTime? RecordTime { get; set; } + public string DeptName { get; set; } + public string Content { get; set; } + public int ImageCount { get; set; } + public List Images { get; set; } + public int MigrationStatus { get; set; } +} + +/// +/// 迁移URL更新请求 +/// +public class MigrationUpdateDto +{ + public int RecordId { get; set; } + public List ImageUrls { get; set; } +} + +public class MigrationUrlPair +{ + public string OldUrl { get; set; } + public string NewUrl { get; set; } +} +``` + +## COS Configuration + +腾讯云 COS 配置将存储在 `appsettings.json` 中: + +```json +{ + "TencentCOS": { + "AppId": "1308826010", + "Region": "ap-shanghai", + "SecretId": "AKIDVyMfzKZdZP8zkNyOdsFuSsBJDB7EScs0", + "SecretKey": "89GWr7JPWYTL8ueHlAYowGZnvzKZjqs9", + "BucketName": "miaoyu", + "DomainUrl": "https://miaoyu-1308826010.cos.ap-shanghai.myqcloud.com", + "MaxSize": 100, + "DurationSecond": 600, + "Prefixes": "workfiles" + } +} +``` + +## COS Directory Structure + +保持与现有本地存储一致的目录结构: + +``` +/workfiles/{yyyyMM}/{yyyyMMdd}/ + ├── 当日照片/{timestamp}_{random}.jpg + ├── 参与人员/{人员姓名}/{timestamp}_{random}.jpg + ├── 工作内容/{工作内容}/{timestamp}_{random}.jpg + └── 部门/{部门名称}/{timestamp}_{random}.jpg +``` + +## Correctness Properties + +*A property is a characteristic or behavior that should hold true across all valid executions of a system-essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.* + +### Property 1: Pre-signed URL Generation Completeness +*For any* valid upload request with N images and M workers, the API SHALL return exactly N image entries, each containing: +- 1 daily photo URL +- M worker directory URLs (one per worker) +- 1 content directory URL +- 1 department directory URL +- All URLs following the pattern `/workfiles/{yyyyMM}/{yyyyMMdd}/{category}/{subcategory}/{timestamp}_{random}.{ext}` + +**Validates: Requirements 1.1, 1.2, 1.4, 1.5** + +### Property 2: COS URL Validation +*For any* URL submitted to the V3 interface, the system SHALL accept only URLs matching the COS domain pattern `https://miaoyu-1308826010.cos.ap-shanghai.myqcloud.com/workfiles/...` and reject all other URLs. + +**Validates: Requirements 3.3** + +### Property 3: V3 Record Save Integrity +*For any* valid V3 save request with N image URLs, the system SHALL: +- Create exactly one work record in database +- Store all N image URLs in the image table +- Return the created record ID and image count = N + +**Validates: Requirements 3.1, 3.4** + +### Property 4: Export Pagination Consistency +*For any* export query with total N records and page size P, iterating through all ceil(N/P) pages SHALL return exactly N unique records with no duplicates or missing entries. Page size SHALL be capped at 50 regardless of requested value. + +**Validates: Requirements 4.1, 4.2, 4.4** + +### Property 5: Export Filter Accuracy +*For any* export query with filters (date range, department, worker, content), all returned records SHALL match ALL specified filter criteria. + +**Validates: Requirements 4.3** + +### Property 6: Migration List Filter +*For any* migration list query with status filter, all returned records SHALL have the specified migration status (0-unmigrated, 1-migrated, 2-failed). + +**Validates: Requirements 10.1, 10.2** + +### Property 7: Migration URL Update Integrity +*For any* migration update request with N URL pairs, the system SHALL: +- Validate all new URLs are valid COS URLs +- Update all N URLs atomically (all succeed or all fail) +- Preserve the mapping between old and new URLs + +**Validates: Requirements 10.3, 10.4** + +## Error Handling + +### API Error Responses + +| 错误码 | 说明 | 处理方式 | +|--------|------|----------| +| 400 | 参数错误 | 返回具体错误字段 | +| 401 | 未授权 | 要求重新登录 | +| 403 | 无权限 | 提示权限不足 | +| 500 | 服务器错误 | 记录日志,返回友好提示 | + +### COS 上传错误处理 + +1. **预签名 URL 过期** - 客户端重新获取 URL +2. **上传失败** - 客户端重试最多 3 次 +3. **部分上传成功** - 记录失败的目录,允许重试 + +### CS 客户端错误处理 + +1. **网络超时** - 自动重试,显示重试进度 +2. **下载失败** - 跳过失败图片,记录日志 +3. **Excel 生成失败** - 保存已下载数据,允许重新生成 + +## Testing Strategy + +### Unit Tests + +使用 xUnit 进行单元测试: + +1. **CosService Tests** + - 测试预签名 URL 生成逻辑 + - 测试目录路径生成 + - 测试文件名生成 + +2. **WorkRecordService Tests** + - 测试 V3 接口数据保存 + - 测试查询过滤逻辑 + - 测试分页逻辑 + +3. **MigrationService Tests** + - 测试迁移状态判断 + - 测试 URL 更新逻辑 + +### Property-Based Tests + +使用 FsCheck 进行属性测试: + +1. **Property 1: Pre-signed URL Generation Completeness** + - 生成随机的上传请求参数 + - 验证返回的 URL 数量和结构 + +2. **Property 4: Pagination Consistency** + - 生成随机数量的测试数据 + - 验证分页遍历的完整性 + +### Integration Tests + +1. **COS 集成测试** + - 测试实际上传到 COS + - 测试预签名 URL 有效性 + +2. **API 集成测试** + - 测试完整的上传流程 + - 测试导出 API 响应 + +### CS Client Tests + +1. **API 调用测试** + - Mock API 响应测试 + - 错误处理测试 + +2. **Excel 生成测试** + - 测试 Excel 格式正确性 + - 测试图片嵌入功能 diff --git a/.kiro/specs/work-camera-2.0/requirements.md b/.kiro/specs/work-camera-2.0/requirements.md new file mode 100644 index 0000000..577e84a --- /dev/null +++ b/.kiro/specs/work-camera-2.0/requirements.md @@ -0,0 +1,151 @@ +# Requirements Document + +## Introduction + +随工水印相机 2.0 系统升级,主要解决服务器资源瓶颈问题。通过将图片存储迁移到腾讯云 COS、开发 CS 客户端本地导出 Excel,释放服务器带宽和存储压力。 + +## Glossary + +- **COS**: 腾讯云对象存储服务 (Cloud Object Storage) +- **Pre-signed_URL**: 预签名URL,允许客户端直接上传文件到 COS 而无需暴露密钥 +- **UniApp_Client**: 基于 UniApp 框架的移动端应用 +- **CS_Client**: Windows 桌面客户端 (Client-Server) +- **Work_Record**: 工作记录,包含拍照时间、位置、工作内容、参与人员和图片等信息 +- **Image_Migration**: 图片迁移,将服务器本地图片迁移到 COS 的过程 +- **API_Server**: 基于 .NET 的后端服务器 + +## COS Configuration + +腾讯云 COS 配置信息: + +| 配置项 | 值 | 说明 | +|--------|-----|------| +| AppId | 1308826010 | 腾讯云 AppId | +| Region | ap-shanghai | 存储区域(上海) | +| SecretId | AKIDVyMfzKZdZP8zkNyOdsFuSsBJDB7EScs0 | 访问密钥 ID | +| SecretKey | 89GWr7JPWYTL8ueHlAYowGZnvzKZjqs9 | 访问密钥 Secret | +| BucketName | miaoyu | 存储桶名称 | +| DomainUrl | https://miaoyu-1308826010.cos.ap-shanghai.myqcloud.com | 访问资源域名 | +| MaxSize | 100 | 上传文件大小限制 (MB) | +| DurationSecond | 600 | 签名有效期(秒) | +| Prefixes | file | 路径前缀 | + +## Requirements + +### Requirement 1: COS 预签名 URL 生成 + +**User Story:** As a UniApp_Client user, I want to get pre-signed URLs for uploading images, so that I can upload images directly to COS without going through the server. + +#### Acceptance Criteria + +1. WHEN the UniApp_Client requests upload URLs with record time, department name, content, workers list, file extension and image count, THE API_Server SHALL return pre-signed URLs for each image +2. THE API_Server SHALL generate URLs for four directory categories: daily photos, workers, content, and department +3. WHEN generating pre-signed URLs, THE API_Server SHALL set URL expiration time to 30 minutes +4. THE API_Server SHALL generate file names using timestamp and random number format: `{timestamp}_{random}.{ext}` +5. THE API_Server SHALL organize COS paths following the structure: `/workfiles/{yyyyMM}/{yyyyMMdd}/{category}/{subcategory}/{filename}` + +### Requirement 2: COS 直传上传 + +**User Story:** As a UniApp_Client user, I want to upload images directly to COS, so that server bandwidth is not consumed during upload. + +#### Acceptance Criteria + +1. WHEN the UniApp_Client receives pre-signed URLs, THE UniApp_Client SHALL upload images directly to COS using PUT method +2. THE UniApp_Client SHALL upload each image to all four directory categories (daily, workers, content, department) +3. THE UniApp_Client SHALL support concurrent uploads with maximum 3 parallel requests +4. IF an upload fails, THEN THE UniApp_Client SHALL retry up to 3 times before reporting failure + +### Requirement 3: 工作记录保存 (v3 接口) + +**User Story:** As a UniApp_Client user, I want to save work records with COS image URLs, so that my work records are persisted with the new storage system. + +#### Acceptance Criteria + +1. WHEN the UniApp_Client submits a work record with COS image URLs, THE API_Server SHALL save the record to database +2. THE API_Server SHALL accept imageUrls array containing COS URLs instead of Base64 encoded images +3. THE API_Server SHALL validate that all provided image URLs are valid COS URLs +4. THE API_Server SHALL return the created record ID and image count on success +5. THE API_Server SHALL maintain backward compatibility by keeping v1 and v2 interfaces unchanged + +### Requirement 4: 工作记录导出查询 + +**User Story:** As a CS_Client user, I want to query work records with pagination, so that I can export data to Excel locally. + +#### Acceptance Criteria + +1. WHEN the CS_Client requests work records with pagination parameters, THE API_Server SHALL return paginated results +2. THE API_Server SHALL limit page size to maximum 50 records per request +3. THE API_Server SHALL support filtering by date range, department name, worker name, and content +4. THE API_Server SHALL return complete record data including all image URLs +5. THE API_Server SHALL require authentication for export API access + +### Requirement 5: CS 客户端登录 + +**User Story:** As a CS_Client user, I want to login with my credentials, so that I can access the export functionality. + +#### Acceptance Criteria + +1. WHEN the user enters server address, username and password, THE CS_Client SHALL authenticate against the API_Server +2. WHEN login succeeds, THE CS_Client SHALL store the authentication token locally +3. THE CS_Client SHALL support "remember me" functionality to persist login state +4. IF login fails, THEN THE CS_Client SHALL display appropriate error message + +### Requirement 6: CS 客户端数据预览 + +**User Story:** As a CS_Client user, I want to preview query results before exporting, so that I can verify the data selection. + +#### Acceptance Criteria + +1. WHEN the user sets query conditions and clicks preview, THE CS_Client SHALL display total record count and estimated image count +2. THE CS_Client SHALL display a preview list showing first N records with basic information +3. THE CS_Client SHALL show record number, date, department, content, and image count in preview + +### Requirement 7: CS 客户端 Excel 导出 + +**User Story:** As a CS_Client user, I want to export work records to Excel with embedded images, so that I can have offline access to the data. + +#### Acceptance Criteria + +1. WHEN the user clicks export, THE CS_Client SHALL fetch all matching records via paginated API calls +2. THE CS_Client SHALL download images concurrently with maximum 5 parallel downloads +3. THE CS_Client SHALL generate Excel file with columns: 序号, 部门名称, 拍照时间, 经度, 纬度, 位置, 工作内容, 施工人员, 状态, 施工图片, 创建时间, 更新时间 +4. THE CS_Client SHALL embed images in cells with size 100x60 pixels, compressed to 50% quality +5. THE CS_Client SHALL display export progress showing processed records and downloaded images +6. THE CS_Client SHALL support canceling export operation +7. WHEN export completes, THE CS_Client SHALL open the containing folder automatically + +### Requirement 8: 历史数据迁移查询 + +**User Story:** As a CS_Client user, I want to view records pending migration, so that I can select which records to migrate. + +#### Acceptance Criteria + +1. WHEN the user opens migration window, THE CS_Client SHALL fetch records with old server URLs +2. THE CS_Client SHALL support filtering by date range, department, and migration status +3. THE CS_Client SHALL display migration status: unmigrated, migrated, or failed +4. THE CS_Client SHALL support selecting individual records or batch selection + +### Requirement 9: 历史数据迁移执行 + +**User Story:** As a CS_Client user, I want to migrate selected records to COS, so that historical data uses the new storage system. + +#### Acceptance Criteria + +1. WHEN the user selects records and clicks migrate, THE CS_Client SHALL download images from old server +2. THE CS_Client SHALL upload downloaded images to COS maintaining directory structure +3. THE CS_Client SHALL call API to update image URLs in database after successful upload +4. THE CS_Client SHALL display migration progress showing processed records and uploaded images +5. THE CS_Client SHALL support canceling migration operation +6. IF migration fails for a record, THEN THE CS_Client SHALL mark it as failed and continue with next record +7. THE CS_Client SHALL support retrying failed migrations + +### Requirement 10: 迁移 API 支持 + +**User Story:** As a CS_Client, I want API endpoints for migration operations, so that I can query and update migration data. + +#### Acceptance Criteria + +1. WHEN the CS_Client requests migration list, THE API_Server SHALL return records with old server URLs +2. THE API_Server SHALL support filtering by migration status (0-unmigrated, 1-migrated, 2-failed) +3. WHEN the CS_Client submits URL updates, THE API_Server SHALL update image URLs in database +4. THE API_Server SHALL validate that new URLs are valid COS URLs before updating diff --git a/.kiro/specs/work-camera-2.0/tasks.md b/.kiro/specs/work-camera-2.0/tasks.md new file mode 100644 index 0000000..bec8eb1 --- /dev/null +++ b/.kiro/specs/work-camera-2.0/tasks.md @@ -0,0 +1,216 @@ +# Implementation Plan: 随工水印相机 2.0 + +## Overview + +本实现计划分为五个阶段:后端 COS 集成、前端上传改造、导出 API 开发、CS 客户端开发、历史数据迁移。采用增量开发方式,每个阶段完成后进行验证。 + +## Tasks + +- [ ] 1. 后端 COS 集成与配置 + - [ ] 1.1 添加腾讯云 COS SDK 依赖 + - 在 `ZR.Common` 项目中添加 `Tencent.QCloud.Cos.Sdk` NuGet 包 + - _Requirements: 1.1_ + - [ ] 1.2 创建 COS 配置模型 + - 在 `Infrastructure/Model/OptionsSetting.cs` 中添加 `TencentCOS` 配置类 + - 包含 AppId, Region, SecretId, SecretKey, BucketName, DomainUrl, MaxSize, DurationSecond, Prefixes + - _Requirements: 1.1_ + - [ ] 1.3 更新 appsettings.json 配置 + - 添加 TencentCOS 配置节 + - _Requirements: 1.1_ + - [ ] 1.4 创建 CosService 服务类 + - 创建 `ZR.Common/CosService.cs` + - 实现 `GetUploadUrls` 方法生成预签名 URL + - 实现 `GetTempCredentials` 方法获取临时密钥 + - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5_ + - [ ] 1.5 编写 CosService 单元测试 + - 测试 URL 生成逻辑 + - 测试目录路径格式 + - _Requirements: 1.1, 1.2, 1.4, 1.5_ + +- [ ] 2. COS 预签名 URL 接口 + - [ ] 2.1 创建 COS 相关 DTO + - 在 `ZR.Model/Business/Dto` 中创建 `CosUploadUrlsRequest.cs` + - 创建 `CosUploadUrlsResponse.cs` + - _Requirements: 1.1, 1.2_ + - [ ] 2.2 创建 CosController + - 在 `ZR.Admin.WebApi/Controllers` 中创建 `CosController.cs` + - 实现 `POST /api/cos/getUploadUrls` 接口 + - 实现 `GET /api/cos/getTempCredentials` 接口 + - _Requirements: 1.1, 1.2, 1.3_ + - [ ] 2.3 编写属性测试 - URL 生成完整性 + - **Property 1: Pre-signed URL Generation Completeness** + - **Validates: Requirements 1.1, 1.2, 1.4, 1.5** + +- [ ] 3. Checkpoint - COS 集成验证 + - 确保 COS 配置正确加载 + - 确保预签名 URL 接口可正常调用 + - 确保所有测试通过,如有问题请询问用户 + +- [ ] 4. 工作记录 V3 接口 + - [ ] 4.1 创建 V3 DTO + - 在 `ZR.Model/Business/Dto` 中创建 `CamRecordWorkV3Dto.cs` + - 包含 ImageUrls 字段替代 Image/Images + - _Requirements: 3.1, 3.2_ + - [ ] 4.2 实现 V3 保存接口 + - 在 `CommonController.cs` 中添加 `AddCamWorkRecordV3` 方法 + - 路由: `POST /addworkrecordv3` + - 验证 COS URL 格式 + - 复用现有数据库存储逻辑 + - _Requirements: 3.1, 3.2, 3.3, 3.4, 3.5_ + - [ ] 4.3 编写属性测试 - COS URL 验证 + - **Property 2: COS URL Validation** + - **Validates: Requirements 3.3** + - [ ] 4.4 编写属性测试 - V3 记录保存完整性 + - **Property 3: V3 Record Save Integrity** + - **Validates: Requirements 3.1, 3.4** + +- [ ] 5. Checkpoint - V3 接口验证 + - 确保 V3 接口可正常保存记录 + - 确保图片 URL 正确存储 + - 确保所有测试通过,如有问题请询问用户 + +- [ ] 6. 数据导出 API + - [ ] 6.1 创建导出查询 DTO + - 在 `ZR.Model/Business/Dto` 中创建 `WorkRecordExportQueryDto.cs` + - 创建 `WorkRecordExportDto.cs` + - _Requirements: 4.1, 4.3, 4.4_ + - [ ] 6.2 创建导出 Service + - 在 `ZR.Service/Business` 中创建 `WorkRecordExportService.cs` + - 实现分页查询逻辑 + - 实现过滤逻辑(日期、部门、人员、内容) + - _Requirements: 4.1, 4.2, 4.3, 4.4_ + - [ ] 6.3 创建导出 Controller + - 在 `ZR.Admin.WebApi/Controllers` 中创建 `WorkRecordExportController.cs` + - 实现 `GET /api/workrecord/export/list` 接口 + - 添加认证要求 + - _Requirements: 4.1, 4.2, 4.3, 4.4, 4.5_ + - [ ] 6.4 编写属性测试 - 分页一致性 + - **Property 4: Export Pagination Consistency** + - **Validates: Requirements 4.1, 4.2, 4.4** + - [ ] 6.5 编写属性测试 - 过滤准确性 + - **Property 5: Export Filter Accuracy** + - **Validates: Requirements 4.3** + +- [ ] 7. Checkpoint - 导出 API 验证 + - 确保分页查询正常工作 + - 确保过滤条件正确应用 + - 确保所有测试通过,如有问题请询问用户 + +- [ ] 8. 历史数据迁移 API + - [ ] 8.1 创建迁移相关 DTO + - 在 `ZR.Model/Business/Dto` 中创建 `MigrationQueryDto.cs` + - 创建 `MigrationRecordDto.cs` + - 创建 `MigrationUpdateDto.cs` + - _Requirements: 10.1, 10.2, 10.3_ + - [ ] 8.2 创建迁移 Service + - 在 `ZR.Service/Business` 中创建 `WorkRecordMigrationService.cs` + - 实现待迁移记录查询(根据 URL 域名判断) + - 实现 URL 更新逻辑 + - _Requirements: 10.1, 10.2, 10.3, 10.4_ + - [ ] 8.3 创建迁移 Controller + - 在 `ZR.Admin.WebApi/Controllers` 中创建 `WorkRecordMigrationController.cs` + - 实现 `GET /api/workrecord/migration/list` 接口 + - 实现 `POST /api/workrecord/migration/update` 接口 + - _Requirements: 10.1, 10.2, 10.3, 10.4_ + - [ ] 8.4 编写属性测试 - 迁移列表过滤 + - **Property 6: Migration List Filter** + - **Validates: Requirements 10.1, 10.2** + - [ ] 8.5 编写属性测试 - 迁移 URL 更新完整性 + - **Property 7: Migration URL Update Integrity** + - **Validates: Requirements 10.3, 10.4** + +- [ ] 9. Checkpoint - 后端 API 完成验证 + - 确保所有后端 API 正常工作 + - 确保所有测试通过,如有问题请询问用户 + +- [ ] 10. 前端 UniApp 上传改造 + - [ ] 10.1 创建 COS 上传服务 + - 在 `uniapp/WorkCameraf/common` 中创建 `cosUpload.js` + - 实现获取预签名 URL 方法 + - 实现直传 COS 方法(PUT 请求) + - _Requirements: 2.1, 2.2, 2.3, 2.4_ + - [ ] 10.2 修改 server.js 添加 V3 接口调用 + - 添加 `addWatermarkRecordV3` 方法 + - 调用 `/addworkrecordv3` 接口 + - _Requirements: 3.1, 3.2_ + - [ ] 10.3 修改上传流程 + - 修改拍照后的上传逻辑 + - 先获取预签名 URL + - 并发上传到 COS(最多 3 个并发) + - 上传成功后调用 V3 接口保存记录 + - _Requirements: 2.1, 2.2, 2.3, 2.4, 3.1_ + +- [ ] 11. Checkpoint - 前端上传验证 + - 确保前端可正常上传图片到 COS + - 确保工作记录正确保存 + - 如有问题请询问用户 + +- [ ] 12. CS 客户端项目搭建 + - [ ] 12.1 创建 WinForms 项目 + - 创建 `WorkCameraExport` 解决方案 + - 配置 .NET 8 AOT 单文件发布 + - 添加 EPPlus、SixLabors.ImageSharp 依赖 + - _Requirements: 5.1, 7.3, 7.4_ + - [ ] 12.2 创建 API 服务类 + - 创建 `Services/ApiService.cs` + - 实现登录、查询、迁移等 API 调用 + - _Requirements: 5.1, 5.2, 4.1_ + - [ ] 12.3 创建 COS 服务类 + - 创建 `Services/CosService.cs` + - 实现图片上传到 COS + - _Requirements: 9.2_ + +- [ ] 13. CS 客户端登录模块 + - [ ] 13.1 创建登录窗体 + - 创建 `Forms/LoginForm.cs` + - 包含服务器地址、用户名、密码输入 + - 实现记住登录状态功能 + - _Requirements: 5.1, 5.2, 5.3, 5.4_ + +- [ ] 14. CS 客户端导出模块 + - [ ] 14.1 创建主窗体 + - 创建 `Forms/MainForm.cs` + - 包含查询条件区域(日期、部门、人员、内容) + - 包含数据预览区域 + - 包含导出进度区域 + - _Requirements: 6.1, 6.2, 6.3, 7.5_ + - [ ] 14.2 创建 Excel 服务类 + - 创建 `Services/ExcelService.cs` + - 实现 Excel 生成逻辑 + - 实现图片嵌入逻辑(100x60 像素,50% 压缩) + - _Requirements: 7.3, 7.4_ + - [ ] 14.3 实现导出功能 + - 实现分页获取数据 + - 实现并发下载图片(最多 5 个并发) + - 实现进度显示 + - 实现取消功能 + - _Requirements: 7.1, 7.2, 7.5, 7.6, 7.7_ + +- [ ] 15. CS 客户端迁移模块 + - [ ] 15.1 创建迁移窗体 + - 创建 `Forms/MigrationForm.cs` + - 包含筛选条件区域 + - 包含待迁移记录列表 + - 包含迁移进度区域 + - _Requirements: 8.1, 8.2, 8.3, 8.4_ + - [ ] 15.2 实现迁移功能 + - 实现下载原图片 + - 实现上传到 COS + - 实现调用 API 更新 URL + - 实现进度显示和取消功能 + - _Requirements: 9.1, 9.2, 9.3, 9.4, 9.5, 9.6, 9.7_ + +- [ ] 16. Final Checkpoint - 全功能验证 + - 确保所有功能正常工作 + - 确保所有测试通过 + - 如有问题请询问用户 + +## Notes + +- All tasks are required for complete implementation +- Each task references specific requirements for traceability +- Checkpoints ensure incremental validation +- Property tests validate universal correctness properties +- 后端使用 C# / .NET 8 +- 前端使用 UniApp (Vue.js) +- CS 客户端使用 WinForms + .NET 8 AOT