# 开放平台下载接口（`work-api`）

数据的第三种拿法：Work 没有声明、本地也没有的全景图、模型或点云，经项目 BFF 调用「开放平台 API」的项目资源下载接口获取。对应 `capabilities.data.sourceClass = work-api`。

> 区分：如视制作平台的「附加产物—全景图」（2:1 整图 JPG）是**手动下载**后作为本地数据包（`work-local`）使用，不经过本接口；本接口的 `panorama` 是 `vr_package` 打包的六面图压缩包，需本地 c2e 转换。

## 什么时候用

- **计费由用户选择**。先列出资源码、缺项、拟提交的产物与格式、计费方式及可行的替代方案。通常可选 API 下载、补充本地素材、使用仍可用的精简档或暂缓。`pipeline.py all` 用 `choice.apiDownload` 提示这条路径。用户明确同意本次计费后才传入 `--yes --confirm-billing`。`--yes` 单独只确认下载清单。价格或扣费结果未知时标明未知。
- **续查和新建任务分开**。查看计划、轮询已提交任务和继续取同一任务的文件无需再确认提交费用。换格式后新建任务、失败或过期后重提都可能再次计费，应先告知用户并等其明确选择。
- 典型场景：Work 的 `model` 只有旧版 `.at3d`（`LEGACY_AT3D_MODEL`），或根本没有网格 / 全景，完整档因此做不了。接口导出的 OBJ 可以补上网格。
- 额外取 E57 点云（带每站扫描原点，能做遮挡过滤与 A3 对齐）：`--api-products point_cloud`。完整档本来就能跑时不会自动取点云。
- Work 或本地已经有的，不经接口重复取；本地已有同类数据直接使用，不覆盖。

## 调用链

资源下载处于本机试用阶段。OBJ 链路已有真实网关验收记录；全景与点云的 API 下载目前只有模拟验证，尚未在真实网关走完。只有回环开发 BFF 支持显式启用；生产服务不注册下载路由。操作者在 BFF 进程和脚本终端为同一个项目设置相同的随机 `BFF_DOWNLOAD_ACCESS_TOKEN`（至少 32 个 URL 安全字符），再重启 BFF。该令牌仅供本机脚本使用，和 Work 页面令牌独立。

```
download_center.py → 项目 BFF（回环 + 独立下载令牌）→ 开放平台 /open/v1/download/*
```

脚本自动发送下载令牌。AK/SK 与开放平台 access token 保存在 BFF。新版 BFF 在 `GET /api/download` 返回 `authorizationRequired: true` 和 `billingConfirmationRequired: true`。计费确认后，脚本再为提交请求加 `X-Realsee-Confirm-Billing: yes`。旧工程先升级并重启，定制过的 BFF 按升级提示手动合并安全接线。

## 命令

```bash
# 只读：是否可用、将要提交/续查什么（不提交）
python <skill-dir>/scripts/download_center.py --check
python <skill-dir>/scripts/download_center.py --resource-code <RC> --out <资源父目录> --work-json <work.json> --products model
# 续查已有任务用 --yes。用户同意本次新建任务时追加 --confirm-billing。

# 经 all 一步走完（默认 BFF 地址 `http://127.0.0.1:8087` 是 `npm run dev` 的 Vite 入口，转发到 BFF；只起 BFF 时用 `--base-url` 指向它的端口）
#（计划 → 确认 → 提交/续查 → 放置 → 分析 → 交付）
python <skill-dir>/scripts/pipeline.py all --resource-code <RC> --api-download                            # 先出计划，等确认
python <skill-dir>/scripts/pipeline.py all --resource-code <RC> --api-download --yes --confirm-billing      # 用户同意计费后提交并继续
python <skill-dir>/scripts/pipeline.py all --resource-code <RC> --api-products point_cloud --yes --confirm-billing
```

`--api-download` 单独使用时只补完整档缺的东西：Work 没有网格且无本地网格时可取 `model`；Work 六面 URL 无法补齐缺图、且全景点位索引与位姿可核对时可取 `panorama`。完全缺少索引时请补充能够核对的本地全景和位姿。`--api-products model,panorama,point_cloud` 显式指定产物。点云默认请求 E57。用户选择 PLY 时用 `--api-cloud-format ply`，并说明 PLY 没有站点扫描原点。**E57/PLY 点云仅支持伽罗华项目**，非伽罗华项目提交会失败。`--base-url` 指定 BFF 地址（默认 `http://127.0.0.1:8087`）。

## 产物与放置

首次取数时自动创建工程内的 `resources/<RC>/`。Work、可选平面图、全景、模型、点云及下载任务记录按资源码分目录保存，后续分析和续跑复用。独立运行 `download_center.py` 时可省略 `--out`；显式指定的 `--out` 作为资源父目录。
| 产物 | 请求参数 | 放到 `resources/<RC>/` |
| --- | --- | --- |
| `point_cloud` | `target_format: e57` 或用户确认的 `ply` | `point_cloud/data.e57`（或 `data.ply`），核对 E57 扫描名与 Work 点位一致 |
| `model` | `target_format: obj` | 合并分块后放 `basic_model/output_00.obj`，核对包围盒包含 Work 点位 |
| `panorama` | `all_indexes: true`；只补缺口时 `all_indexes: false, indexes: [...]` | 六面图转 2:1 等距全景，沿用已有位姿；位姿由 Work observers 生成 |

本机 BFF 只开放表中的三类产物。点云的保留字段 `source_version` 不在参数白名单中。按点位取全景时，`all_indexes: false` 须搭配非空 `indexes`，避免空列表将计费范围扩大为全部点位。

下载接口导出的模型是基础网格，不是高精度模型：引擎用它做射线与测量，A6 不可用。接口还提供捆绑包、静态包与 RAW，本流程不使用（RAW 不进入分析）。

## 任务与计费规则

- 同一资源目录一次只执行一个下载流程。脚本在发请求前记录提交中状态，拿到任务号后更新 `resources/<RC>/.download-center/state.json`。续查使用原任务号与请求范围，间隔默认 7 秒。期间本地新增全景时，原任务覆盖剩余点位就继续原任务；范围有歧义则暂停。
- 提交超时、中途中断或结果未知（`submit-uncertain`）时，任务可能已建立并计费。先到如视下载中心核对。已有任务可在下载中心继续取素材，确认没有任务后才向用户询问是否重提。
- 失败、过期或拒绝的任务应先按提示处理。用户同意重新下单时才加 `--resubmit --yes --confirm-billing`。换成 PLY 也是一笔新任务，需向用户单独确认。
- 全景必须能匹配已有点位和位姿。发现无法匹配时会在提交前停下，提示提供本地全景或使用可用的精简分析。
- 预签名下载链接只在内存里使用，不打印、不写盘、不写日志；任务成功时 `file_size` 可能为 0，以实际下载为准。

## 错误归类与用户反馈

用一句话说明发生在哪个阶段、哪个资源或产物、这次还能做什么。保留网关原始 `code` 与脱敏后的 `status` 供排查，区分业务码、HTTP 状态和脚本退出码。已知任务号可一并给出。用户反馈不包含凭据、签名链接或未经筛查的网关响应。

| 上游码 | 反馈给用户 | 下一步 |
| --- | --- | --- |
| `-1`、`-3` | 网关包装的通用失败。真实业务码在 `business_code` 或 `status` 文本里 | 核对任务状态、账户、参数或产品能力。提交结果未知时先查下载中心 |
| `51` | 下载参数不合法 | 核对产物选项、必填字段及类型 |
| `10001` | 调用方身份或 source 创建人解析失败 | 请管理员核对租户与创建人配置 |
| `60008` | 资源归属拒绝：`resource_code` 不属于调用方租户 | 核对资源码与调用租户 |
| `60014` | 所传 VR 副本标识无法解析或对应 VR 不存在 | 核对 `resource_code` 和副本标识 |
| `60019` | 资源不存在，或不归属当前调用租户。该错误码无法区分两者 | 请核对资源码和当前租户，或由拥有资源的租户操作 |
| `10202` | 计费项不存在（非法 `task_type` 也会命中） | 请管理员核对该产物的计费项配置 |
| `10204` | 下载任务提交失败。可能涉及产物可下载性或计费状态 | 核对该 VR 的产物和计费状态。再次提交前请用户确认 |
| `23020` | 资源下载包余额不足 | 联系客服或租户管理员处理余额。可选择用已有数据继续可用档位 |

示例：「模型下载未能开始（`60019`）。资源可能不存在，或不属于当前租户。请核对资源码和所选租户，也可以先用现有点位完成精简分析。」仅在精简档确实可用时提供后一项。

## 退出码（`download_center.py`）

| 码 | 含义 |
| --- | --- |
| 0 | 完成或只出了计划 |
| 2 | 参数或 BFF 错误 |
| 3 | 下载接口不可用（BFF 没启动、没有路由、被拒绝） |
| 4 | 任务失败 / 过期 / 提交结果未知，需要用户决定 |
| 5 | 仍在打包，稍后同一命令重跑续查 |
| 6 | 压缩包无法识别或核对不通过，文件未放入资源目录 |
