152 lines
8.0 KiB
Markdown
152 lines
8.0 KiB
Markdown
# 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
|