# 成果交付与本地下载设计 日期：2026-06-30 ## 背景 当前“结果提取”页面同时承载了两个不同概念： 1. 生产结果入库：从 LandSAR/ENVI/Gamma 等生产目录提取结果并登记到 catalog。 2. 成果交付导出：用户从已登记 catalog 中选择成果，下载或复制到本地使用。 现有 `POST /api/dinsar-results/export` 是同步文件复制接口，并且要求 admin。这个模型不适合普通用户下载大体量成果：请求容易超时，目标路径由用户输入也不利于审计和权限控制。 ## 目标 - 所有登录用户都可以申请成果交付。 - D-InSAR 已登记成果接入真实交付下载。 - LT-1 正射与 GF3 正射接入真实交付下载。 - SBAS 与 Sentinel-1 正射在页面和接口中保留清晰占位，不暴露假执行能力。 - 大文件交付改为后台任务，不再由 HTTP 请求同步复制。 - 用户最终可以把成果下载到本地；服务器交付区只是临时缓存。 - 每次交付可审计、可过期清理、可校验。 - 数据库变更必须接入现有自维护机制。 ## 非目标 - 本阶段不实现 Sentinel-1 正射生产。 - 本阶段不实现 SBAS 成果交付打包，只显示目录已接入但交付未接入。 - 本阶段不触发 GF3 生产；GF3 交付只面向已经登记的 SARscape 标准化正射成品。 - 本阶段不做跨节点对象存储或外部网盘。 - 本阶段不把普通用户开放到任意服务器路径写入。 ## 权限模型 当前系统只有 `admin` 和 `viewer`。本阶段不强制新增角色，采用能力约定： - 登录用户：可查看已授权 catalog，可创建自己的成果交付任务，可查看和下载自己的交付包。 - admin：除普通用户能力外，可查看所有交付任务，可配置交付根目录，可清理或取消交付任务。 后续如果拆角色，建议增加： - `exporter`：可创建成果交付任务。 - `operator`：可做生产、入库和成果交付。 - `admin`：用户、系统配置和全局清理。 ## 交付模式 ## 正射成果口径 - LT-1 正射：由服务器侧单景正射流水线生产，登记在 `sar_scene_geo`，主交付物是 `analysis_ready.tif`，随包包含预览、manifest、quality 等 sidecar 文件。 - GF3 正射：系统拿到的就是外部 SARscape 已生产成品，当前可登记为 `GF3_SARSCAPE_NATIVE_PREVIEW`，标准化后也可登记为 `GF3_SARSCAPE_L2`；交付阶段只做受控打包和下载，不触发 GF3 生产。 - Sentinel-1 正射：生产链尚未接入，结果提取页面保留占位，避免用户误操作。 - SBAS-InSAR：成果目录可查，但交付打包尚未接入。 ### 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`。 - `source_radar_data_id` / `source_scene_geo_id`：用于 LT-1/GF3 单景正射资产追踪。 - `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`: `ready` - `s1_ortho`: `placeholder` - `gf3_ortho`: `ready` ### 获取可交付目录 ```http GET /api/result-deliveries/catalog/{channel} ``` 第一版支持： - `dinsar`：兼容已有 D-InSAR catalog。 - `lt1_ortho`：读取 `sar_scene_geo` 中 `lt_gamma / lt1_gamma_geocoded_mli` 且 `DONE` 的分析就绪 GeoTIFF。 - `gf3_ortho`：读取 `radar_data.source_format in (GF3_SARSCAPE_NATIVE_PREVIEW, GF3_SARSCAPE_L2)` 且 `geocoded_flag = true` 的 SARscape 正射成品。 返回统一字段包括 `item_id`、`source_kind`、`product_id`、`display_name`、`primary_asset_path`、`publish_dir`、`radar_data_id`、`scene_geo_id`。 ### 创建交付任务 ```http POST /api/result-deliveries ``` 请求： ```json { "channel": "dinsar", "product_ids": ["..."], "compat_result_ids": [1, 2, 3], "item_ids": [101, 102], "package_mode": "directory", "include_manifest": true, "include_checksums": true } ``` 约束： - 普通用户只创建自己的任务。 - `dinsar` 使用 `compat_result_ids` 或 `product_ids`。 - `lt1_ortho` 使用 `item_ids = sar_scene_geo.id`。 - `gf3_ortho` 使用 `item_ids = radar_data.id`。 - 每次最大数量由 `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. 按 channel 解析可交付源文件路径。 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、LT-1 正射、GF3 正射可用；SBAS/Sentinel-1 显示未接入交付。 - 成果选择区：D-InSAR 复用现有 catalog 列表，LT-1/GF3 使用统一交付 catalog 查询。 - 交付选项：目录交付 / 压缩包交付。 - 我的交付包：状态、大小、文件数、过期时间、下载入口。 交互约束： - 不再让普通用户输入服务器路径。 - 创建后显示任务 ID 和交付 ID。 - 对大文件提示“建议使用逐文件下载或共享目录复制”。 - 下载入口只在 `READY` 状态显示。 ## 与用户管理联动 第一版： - `viewer` 也可以创建自己的成果交付任务。 - 前端不再用 `readOnly` 禁用成果交付下载。 - 生产结果入库、删除、系统配置仍要求 admin。 后续： - 增加 `exporter/operator` 角色后，前端用户管理页需要增加角色选项。 - 后端新增能力级依赖，例如 `require_capability("result.delivery.create")`。 ## 风险与防护 - 大文件复制拖慢生产盘：限制 worker 并发，交付任务可单独限流。 - 用户重复申请导致空间膨胀：按用户限制未过期交付包数量和总大小。 - 任意路径写入风险：只允许系统配置的交付根目录。 - HTTP 下载超时：优先 Nginx Range，后端只负责授权。 - catalog 文件被移动：任务记录 item 失败，不影响其他文件。 ## 实施阶段 ### 阶段 1 - 文档落地。 - 数据表和自维护 migration。 - D-InSAR、LT-1 正射、GF3 正射目录交付后台任务。 - 我的交付包列表和详情。 ### 阶段 2 - zip 打包阈值和下载。 - manifest/checksum 下载。 - Nginx 静态交付路径或 `X-Accel-Redirect`。 ### 阶段 3 - SBAS 交付接入。 - Sentinel-1 正射在生产 catalog 完成后接入。 - exporter/operator 角色拆分。 ## 验收标准 - 普通登录用户能创建 D-InSAR、LT-1 正射、GF3 正射成果交付任务。 - HTTP 请求只排队任务，不再同步复制大文件。 - 交付完成后用户能下载到本地。 - 普通用户不能指定任意服务器目录。 - admin 能看到所有交付任务。 - 数据库重启自维护能创建交付相关表和索引。 - Sentinel-1 正射通道显示占位，不可误点击执行。