Add result delivery workflow
This commit is contained in:
@@ -33,6 +33,8 @@
|
||||
缁熶竴缁撴灉鐩綍銆佹爣鍑嗕骇鍝佸寘銆乧atalog 涓庡寮曟搸缁撴灉鍏卞瓨绾﹀畾銆?
|
||||
- [RESULT_EXTRACTION_ACCESS_CONTROL_AUDIT_20260630.md](RESULT_EXTRACTION_ACCESS_CONTROL_AUDIT_20260630.md)
|
||||
Result extraction and access-control audit: current D-InSAR export/registration boundaries, placeholder channels, admin/viewer limitations, and recommended exporter/operator/admin permission model.
|
||||
- [RESULT_DELIVERY_DOWNLOAD_DESIGN_20260630.md](RESULT_DELIVERY_DOWNLOAD_DESIGN_20260630.md)
|
||||
Result delivery/download design: asynchronous delivery packages, user-owned downloads, temporary delivery root, DB maintenance, and placeholder boundaries for SBAS/LT-1/Sentinel-1/GF3 ortho.
|
||||
- [DINSAR_TASK_POOL_THREE_ENGINE_REFACTOR_20260614.md](DINSAR_TASK_POOL_THREE_ENGINE_REFACTOR_20260614.md)
|
||||
D-InSAR 淇濈暀 ENVI/SARscape銆丩andSAR銆丟amma/PyINT 涓夊紩鎿庯紝閫€鍑?ISCE2锛岀粺涓€ Task_Pool銆佺粨鏋滆仛鍚堝拰涓棿鏂囦欢娓呯悊鐨勫綋鍓嶈璁°€?
|
||||
- [LANDSAR_DEM_PREPARATION_CONTRACT_20260618.md](LANDSAR_DEM_PREPARATION_CONTRACT_20260618.md)
|
||||
|
||||
@@ -0,0 +1,309 @@
|
||||
# 成果交付与本地下载设计
|
||||
|
||||
日期：2026-06-30
|
||||
|
||||
## 背景
|
||||
|
||||
当前“结果提取”页面同时承载了两个不同概念：
|
||||
|
||||
1. 生产结果入库：从 LandSAR/ENVI/Gamma 等生产目录提取结果并登记到 catalog。
|
||||
2. 成果交付导出：用户从已登记 catalog 中选择成果，下载或复制到本地使用。
|
||||
|
||||
现有 `POST /api/dinsar-results/export` 是同步文件复制接口，并且要求 admin。这个模型不适合普通用户下载大体量成果：请求容易超时，目标路径由用户输入也不利于审计和权限控制。
|
||||
|
||||
## 目标
|
||||
|
||||
- 所有登录用户都可以申请成果交付。
|
||||
- D-InSAR 已登记成果先接入真实交付下载。
|
||||
- SBAS、LT-1 正射、Sentinel-1 正射、GF3 正射在页面和接口中保留清晰占位，不暴露假执行能力。
|
||||
- 大文件交付改为后台任务，不再由 HTTP 请求同步复制。
|
||||
- 用户最终可以把成果下载到本地；服务器交付区只是临时缓存。
|
||||
- 每次交付可审计、可过期清理、可校验。
|
||||
- 数据库变更必须接入现有自维护机制。
|
||||
|
||||
## 非目标
|
||||
|
||||
- 本阶段不实现 Sentinel-1 正射生产。
|
||||
- 本阶段不实现 SBAS 成果交付打包，只显示目录已接入但交付未接入。
|
||||
- 本阶段不做跨节点对象存储或外部网盘。
|
||||
- 本阶段不把普通用户开放到任意服务器路径写入。
|
||||
|
||||
## 权限模型
|
||||
|
||||
当前系统只有 `admin` 和 `viewer`。本阶段不强制新增角色，采用能力约定：
|
||||
|
||||
- 登录用户：可查看已授权 catalog，可创建自己的成果交付任务，可查看和下载自己的交付包。
|
||||
- admin：除普通用户能力外，可查看所有交付任务，可配置交付根目录，可清理或取消交付任务。
|
||||
|
||||
后续如果拆角色，建议增加：
|
||||
|
||||
- `exporter`：可创建成果交付任务。
|
||||
- `operator`：可做生产、入库和成果交付。
|
||||
- `admin`：用户、系统配置和全局清理。
|
||||
|
||||
## 交付模式
|
||||
|
||||
### 1. 目录交付
|
||||
|
||||
默认模式。后台将选中的结果文件复制到：
|
||||
|
||||
```text
|
||||
{RESULT_DELIVERY_ROOT}/{username}/{delivery_id}/
|
||||
```
|
||||
|
||||
目录内包含：
|
||||
|
||||
- `manifest.json`
|
||||
- `checksums.sha256`
|
||||
- 结果文件或结果子目录
|
||||
|
||||
适合几十 GB 到 TB 级数据。用户可以通过共享目录或逐文件 HTTP 下载到本地。
|
||||
|
||||
### 2. 压缩包交付
|
||||
|
||||
可选模式。只允许低于阈值的交付包生成 zip：
|
||||
|
||||
```text
|
||||
{RESULT_DELIVERY_ROOT}/{username}/{delivery_id}.zip
|
||||
```
|
||||
|
||||
阈值由环境变量控制，例如 `RESULT_DELIVERY_ZIP_MAX_BYTES`。超过阈值时，接口返回明确错误，要求使用目录交付或逐文件下载。
|
||||
|
||||
### 3. HTTP 下载
|
||||
|
||||
下载不由 FastAPI 直接流式传大文件。推荐 Nginx 静态服务交付区，并支持 Range 断点续传。
|
||||
|
||||
第一版接口可以返回文件下载 URL，由后端验证交付归属后通过 `FileResponse` 交付；后续切到 Nginx `X-Accel-Redirect` 或专门静态路径。
|
||||
|
||||
## 数据模型
|
||||
|
||||
新增两张表：
|
||||
|
||||
### `result_delivery_requests`
|
||||
|
||||
- `delivery_id`：业务 ID。
|
||||
- `owner_user_id` / `owner_username`：申请人。
|
||||
- `channel`：`dinsar`、`sbas`、`lt1_ortho`、`s1_ortho`、`gf3_ortho`。
|
||||
- `status`：`PENDING`、`RUNNING`、`READY`、`FAILED`、`CANCELLED`、`EXPIRED`。
|
||||
- `package_mode`：`directory`、`zip`。
|
||||
- `item_count`、`total_bytes`、`copied_bytes`。
|
||||
- `delivery_root`、`delivery_dir`、`zip_path`、`manifest_path`。
|
||||
- `expires_at`。
|
||||
- `task_id`、`job_id`。
|
||||
- `error_message`。
|
||||
- `request_json`、`summary_json`。
|
||||
|
||||
### `result_delivery_items`
|
||||
|
||||
- `delivery_id`。
|
||||
- `source_product_id` / `source_result_id`。
|
||||
- `display_name`。
|
||||
- `source_path`。
|
||||
- `relative_path`。
|
||||
- `file_size`。
|
||||
- `checksum_sha256`。
|
||||
- `status`：`PENDING`、`COPIED`、`FAILED`、`SKIPPED`。
|
||||
- `error_message`。
|
||||
|
||||
## 数据库自维护
|
||||
|
||||
新增 migration：
|
||||
|
||||
```text
|
||||
backend/migrations/013_result_delivery_requests.sql
|
||||
```
|
||||
|
||||
并加入 `backend/app/db_maintenance.py` 的维护文件列表。迁移必须幂等：
|
||||
|
||||
- `CREATE TABLE IF NOT EXISTS`
|
||||
- `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`
|
||||
- `CREATE INDEX IF NOT EXISTS`
|
||||
|
||||
ORM 同步也要定义对应模型，避免启动时 metadata 检查缺表。
|
||||
|
||||
## API 设计
|
||||
|
||||
### 获取通道能力
|
||||
|
||||
```http
|
||||
GET /api/result-deliveries/channels
|
||||
```
|
||||
|
||||
返回：
|
||||
|
||||
- `dinsar`: `ready`
|
||||
- `sbas`: `planned`
|
||||
- `lt1_ortho`: `planned`
|
||||
- `s1_ortho`: `placeholder`
|
||||
- `gf3_ortho`: `placeholder`
|
||||
|
||||
### 创建交付任务
|
||||
|
||||
```http
|
||||
POST /api/result-deliveries
|
||||
```
|
||||
|
||||
请求：
|
||||
|
||||
```json
|
||||
{
|
||||
"channel": "dinsar",
|
||||
"product_ids": ["..."],
|
||||
"compat_result_ids": [1, 2, 3],
|
||||
"package_mode": "directory",
|
||||
"include_manifest": true,
|
||||
"include_checksums": true
|
||||
}
|
||||
```
|
||||
|
||||
约束：
|
||||
|
||||
- 普通用户只创建自己的任务。
|
||||
- `channel != dinsar` 时第一版返回 409 或 422，提示“通道尚未接入交付”。
|
||||
- 每次最大数量由 `RESULT_DELIVERY_MAX_ITEMS` 控制。
|
||||
- 不允许传入任意服务器输出路径。
|
||||
|
||||
### 列出交付任务
|
||||
|
||||
```http
|
||||
GET /api/result-deliveries?mine=true
|
||||
```
|
||||
|
||||
普通用户只能看到自己的任务，admin 可查看全部。
|
||||
|
||||
### 查看交付详情
|
||||
|
||||
```http
|
||||
GET /api/result-deliveries/{delivery_id}
|
||||
```
|
||||
|
||||
返回交付状态、文件清单、下载 URL、过期时间。
|
||||
|
||||
### 下载文件
|
||||
|
||||
```http
|
||||
GET /api/result-deliveries/{delivery_id}/files/{item_id}/download
|
||||
GET /api/result-deliveries/{delivery_id}/archive/download
|
||||
GET /api/result-deliveries/{delivery_id}/manifest
|
||||
```
|
||||
|
||||
第一版由后端验证权限后返回文件。后续可迁移到 Nginx token 或 `X-Accel-Redirect`。
|
||||
|
||||
## 后台任务
|
||||
|
||||
新增 job type：
|
||||
|
||||
```text
|
||||
RESULT_DELIVERY_BUILD
|
||||
```
|
||||
|
||||
处理流程：
|
||||
|
||||
1. 将 delivery 标记为 `RUNNING`。
|
||||
2. 解析 D-InSAR catalog 中的文件路径。
|
||||
3. 复制到交付目录。
|
||||
4. 生成 `manifest.json`。
|
||||
5. 可选计算 checksum。
|
||||
6. 可选生成 zip。
|
||||
7. 更新状态为 `READY` 或 `FAILED`。
|
||||
|
||||
任务日志应写清：
|
||||
|
||||
- 总项目数。
|
||||
- 已复制数量。
|
||||
- 总大小。
|
||||
- 失败项和原因。
|
||||
- 交付目录。
|
||||
- 过期时间。
|
||||
|
||||
## 存储与清理
|
||||
|
||||
环境变量建议：
|
||||
|
||||
```text
|
||||
RESULT_DELIVERY_ROOT=D:\Result_Delivery
|
||||
RESULT_DELIVERY_PUBLIC_BASE_URL=/deliveries
|
||||
RESULT_DELIVERY_RETENTION_DAYS=7
|
||||
RESULT_DELIVERY_MAX_ITEMS=500
|
||||
RESULT_DELIVERY_ZIP_MAX_BYTES=21474836480
|
||||
RESULT_DELIVERY_CHECKSUM_ENABLED=true
|
||||
```
|
||||
|
||||
清理策略：
|
||||
|
||||
- `expires_at < now` 的 `READY/FAILED/CANCELLED` 交付包可清理。
|
||||
- 清理后状态改为 `EXPIRED`，保留数据库审计记录。
|
||||
- 正式成果 catalog 原文件绝不能被清理任务删除。
|
||||
|
||||
## 前端设计
|
||||
|
||||
结果提取页面改名语义：
|
||||
|
||||
- “生产结果入库”：保留现有 D-InSAR 入库入口，admin 可用。
|
||||
- “成果交付下载”：所有登录用户可用。
|
||||
|
||||
页面结构：
|
||||
|
||||
- 通道栏：D-InSAR 可用，SBAS/LT-1/Sentinel-1/GF3 明确显示“未接入交付”。
|
||||
- 成果选择区：复用现有 D-InSAR catalog 列表。
|
||||
- 交付选项：目录交付 / 压缩包交付。
|
||||
- 我的交付包：状态、大小、文件数、过期时间、下载入口。
|
||||
|
||||
交互约束：
|
||||
|
||||
- 不再让普通用户输入服务器路径。
|
||||
- 创建后显示任务 ID 和交付 ID。
|
||||
- 对大文件提示“建议使用逐文件下载或共享目录复制”。
|
||||
- 下载入口只在 `READY` 状态显示。
|
||||
|
||||
## 与用户管理联动
|
||||
|
||||
第一版：
|
||||
|
||||
- `viewer` 也可以创建自己的成果交付任务。
|
||||
- 前端不再用 `readOnly` 禁用成果交付下载。
|
||||
- 生产结果入库、删除、系统配置仍要求 admin。
|
||||
|
||||
后续：
|
||||
|
||||
- 增加 `exporter/operator` 角色后，前端用户管理页需要增加角色选项。
|
||||
- 后端新增能力级依赖，例如 `require_capability("result.delivery.create")`。
|
||||
|
||||
## 风险与防护
|
||||
|
||||
- 大文件复制拖慢生产盘：限制 worker 并发，交付任务可单独限流。
|
||||
- 用户重复申请导致空间膨胀：按用户限制未过期交付包数量和总大小。
|
||||
- 任意路径写入风险：只允许系统配置的交付根目录。
|
||||
- HTTP 下载超时：优先 Nginx Range，后端只负责授权。
|
||||
- catalog 文件被移动：任务记录 item 失败，不影响其他文件。
|
||||
|
||||
## 实施阶段
|
||||
|
||||
### 阶段 1
|
||||
|
||||
- 文档落地。
|
||||
- 数据表和自维护 migration。
|
||||
- D-InSAR 目录交付后台任务。
|
||||
- 我的交付包列表和详情。
|
||||
|
||||
### 阶段 2
|
||||
|
||||
- zip 打包阈值和下载。
|
||||
- manifest/checksum 下载。
|
||||
- Nginx 静态交付路径或 `X-Accel-Redirect`。
|
||||
|
||||
### 阶段 3
|
||||
|
||||
- SBAS 交付接入。
|
||||
- LT-1 正射、Sentinel-1 正射、GF3 正射在生产 catalog 完成后接入。
|
||||
- exporter/operator 角色拆分。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- 普通登录用户能创建 D-InSAR 成果交付任务。
|
||||
- HTTP 请求只排队任务，不再同步复制大文件。
|
||||
- 交付完成后用户能下载到本地。
|
||||
- 普通用户不能指定任意服务器目录。
|
||||
- admin 能看到所有交付任务。
|
||||
- 数据库重启自维护能创建交付相关表和索引。
|
||||
- Sentinel-1 正射通道显示占位，不可误点击执行。
|
||||
Reference in New Issue
Block a user