WorkCamera/.kiro/specs/work-camera-2.0/requirements.md

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