# 最少需要什么数据（开工前先判定档位）

回答一个问题：**客户只给了这些数据，究竟能出哪一档结论。** 判定发生在下载与推理之前，结论写在
`prepare_work_assets.py --dry-run --json` 的 `capabilities` 里，`pipeline.py all` 会先打印再决定走哪档。

## 数据从哪来：只有三种拿法

先分清「数据怎么到手」，再谈「能算到哪一档」。`capabilities.data.sourceClass` 给的就是这个：

| `sourceClass` | 数据怎么到手 | 典型情况 |
| --- | --- | --- |
| `work-declared` | 只有 Work：按 `work.json` 声明的 URL 下载全景与网格 | 客户只给了一个空间号；`model.layers[].tileset_url` 可下载（能算完整档），或只有旧版 `model.file_url`（`.at3d`，不解码） |
| `work-local` | Work + 你自己准备好的数据包（`resources/<RC>/` 下的 `panorama/`、`basic_model/*.obj` / `high_resolution_model/*.obj`、`point_cloud/*.ply`、`floorplan.json`） | 客户给了导出文件，或上一轮已经物化过 |
| `work-api` | Work + 开放平台 API 数据包：经项目 BFF 的资源下载接口取全景 / 模型 / 点云，放进 `resources/<RC>/` | Work 没有网格或全景（如只有旧版 `.at3d`）又不想自备数据时；**计费，须用户同意**，见 [download-api.md](download-api.md) |

只有 Work 时再看 `capabilities.data.downloadable`（`panorama` / `mesh` / `pointCloud`）：三个都是 `false`
表示 Work 没有提供可直接下载的素材。根据已有数据，可选择补充本地素材、经已授权的本机接口补齐可匹配产物，或使用可用的 work-only。

## 户型依据：有平面图以平面图为准

`capabilities.data.floorplanBasis` 说明房间/墙/门窗/面积从哪来，优先级固定：

| `floorplanBasis` | 依据 | 口径 |
| --- | --- | --- |
| `work` | Work 信封的 `capabilities.modelFloorplan.data.computed_data` | 房间、墙、门窗、面积都按图纸；点位归属按图纸 |
| `local` | `resources/<RC>/floorplan.json` | 同上，但来源是本机文件 |
| `geometry` | 网格推算（`overview.rooms[].source` = `geometry`） | 房间由几何切分，报告与交付说明必须写「户型依据：几何推算」 |
| `null` | 无平面图也无几何 | work-only 只能出点位，`rooms` 恒为 `[]` |

有平面图就不要用几何去覆盖它；没有平面图也不要把几何推出来的房间说成图纸房间。

## 两档的最少数据

档位只有两个：`full` 与 `work-only`。`work-only` 出到什么程度，取决于手上有没有平面图——
有平面图出房间（`mode: "rooms"`），没有平面图只出点位（`mode: "positions"`，旧版 `.at3d` 的典型情形）。

| 档位 | 最少需要 | 能算出来 | 算不出来 | 出口 |
| --- | --- | --- | --- | --- |
| `full` | Work + 扫描位姿 + 全景图 + 三角网格（type=mesh 的 `model.layers[].tileset_url` 或本地 OBJ）+ 检测权重约 620 MB；点云为可选补充，不能代替网格 | 房间边界、墙距、层高、门窗尺寸、家具尺寸与摆放、物体清单、导航图 | 深度图/3DGS 相关指标（D1、G1） | `run` 默认 |
| `work-only`（有平面图） | Work + 可解析平面图（`capabilities.modelFloorplan.data.computed_data`）+ `observers`（位置、站立位置、四元数、可达节点）；不要求 `panorama.list` / `derived_id` | 房间面积与形状、门的位置、点位归属房间、A4 尺度校验、点位间距 | 家具尺寸、物体、层高、墙厚 | `--inputs work-only` |
| `work-only`（没有平面图，只有点位） | 只要 `work.json` 里的 `observers[]`：每个点位至少 `index` 与 `position`；`quaternion` 可选（有才算得出朝向） | 点位数、两两间距与最近邻、空间包络范围、相对朝向、同点位可见性 | 房间边界、墙距、家具尺寸、层高、门宽、地理北（除非用户指定方位） | `--inputs work-only`；缺数据时由用户选（不自动降档）；连 `observers` 都没有才 exit 6 `NO_BUILTIN_TIER` |

老 Work 的 `model.file_url`（`*.at3d`）只是兼容入口：本套件不下载也不解码它，不能当成网格。这种 Work 若没有
平面图，能到的最高档就是 `work-only`（只有点位），`capabilities.blockers` 会给出 `LEGACY_AT3D_MODEL` / `NO_GEOMETRY` / `NO_FLOORPLAN`。

## 缺数据时怎么办：三出口，由用户决定

缺数据不是错误，也不是可以替用户猜的事：报告少一间房、少一档尺寸，用户有权先知道再决定。

| 出口 | 做法 | 命令 |
| --- | --- | --- |
| A 用 work-only | 用 work-only 出交付（有平面图出房间，没有平面图出点位），报告开头写明缺什么、哪些结论不可用 | `pipeline.py all --resource-code <RC> --inputs work-only` |
| B 补数据再跑 | 按缺项的补法补齐，重跑同一条命令 | 见下表「缺什么 → 怎么补」 |
| C 停下 | 保持现状，不动任何文件，稍后再定 | 什么都不加（交互里选 C / 回车跳过） |

- 不传 `--inputs` 时：最高档齐就直接跑；缺数据就输出 `mode: "choose"`（`awaitingChoice: true`、`steps: []`），
  列出每一档的 `available` / `missing` / `supply` / `command`。只有点位档可用时也要把选项交给用户，本轮停在预检，收到选档回复后再执行。
- `--inputs full`：明确要求完整档，缺数据直接 exit 6 `FULL_TIER_UNAVAILABLE`，并列出缺项与补法。
- `run` 也一样：不传 `--inputs` 时如果本地只有点位，它不会以 `RESOURCE_NOT_READY` 退出，而是打印三条路并输出
  `mode: "choose"`（`awaitingChoice: true`、`steps: []`，退出码 0）；连 `observers` 都没有才照旧 exit 6。
- 下载或物化失败同样不自动改档：保留已完成的阶段，提示「修好重试」或「用本地数据显式降档」。
- 缺数据的 `choose` 里，`choice.apiDownload` 是出口 B 的一种做法（经开放平台下载接口取，计费）：只在 BFF 可用时给命令，用户同意后才加 `--api-download`；`all` 不会自己提交下载任务。
- 决策写进 `analysis-decisions.json` 与 `delivery-manifest.json` 的 `tierDecision`（`state` / `chosen` / `missing` / `decidedBy`），交付说明补一行「降档原因：缺 …」。

| 缺什么 | 怎么补 |
| --- | --- |
| 网格 | 让 Work 声明 type=mesh 的 `model.layers[].tileset_url`；或把 `.obj` 放进 `resources/<RC>/basic_model/` / `high_resolution_model/`；或经开放平台下载接口导出 OBJ（`pipeline.py all --api-download`，计费）。点云 `.ply` 不能替代网格。旧版 `.at3d` 的 `file_url` 不解码，不能当几何用 |
| 点云 | Work 声明 `type=point_cloud` 的 tileset；或经开放平台下载接口取 E57（`--api-products point_cloud`，计费，带站点扫描原点） |
| 平面图 | 让 Work 信封带上 `capabilities.modelFloorplan.data`，或把 `floorplan.json` 放进 `resources/<RC>/` |
| 位姿 / 全景 | 起项目 BFF 后跑一次 `all`（会下载 `panorama.list` 声明的全景并生成 `poses.json`），或把已有全景放进 `resources/<RC>/panorama/`；缺完整六面 URL 且点位索引可核对时，可经本机开放平台下载接口试取（计费） |
| `observers` | 换一份带点位的 Work（没有点位时 work-only 也跑不了） |

## 本地数据的快速发现与校验

`resources/<RC>/` 内的文件名和目录层级可以变化。预检、编排与引擎共用发现器：读取位姿 JSON 的 scans/变换、OBJ 头尾采样、点云头，以及位姿引用的全景图片头和 2:1 比例。平面图也可按 computed_data 结构从嵌套 JSON 识别，再核对 Work 身份与点位。标准目录名可声明基础/高精角色，但文件名不作为数据有效的证明；多个不同的有效位姿、同角色网格或全景候选会报告歧义，需要明确关联。

扫描限于所选资源目录，最多 8 层、20,000 个条目，JSON 合计最多 64 MiB，单个 OBJ 头尾最多 512 KiB；扫描不完整不会判为就绪。快速校验不能替代引擎的全量几何、坐标与精度校验，也不会重命名或移动原始数据。

## work-only（没有平面图）的字段契约

```json
{
  "work": {
    "observers": [
      { "index": 0, "position": [1.2, 1.6, -0.4], "quaternion": [0, 0, 0, 1] }
    ]
  }
}
```

- `index`：整数点位号，唯一；文档里的 `frame.observers[].panoIndex` 就是它。
- `position`：Five Local（Y-up）坐标，单位米。
- `quaternion`：可选；缺了不影响出文档，只是朝向为 `null`、方位标注无法计算。
- 全景图文件不是只有点位时的必需项：没有图也能算间距与包络，只是不能做图像类分析。

## 方位：确认一次首点位的初始视角

模型坐标没有地理北。风水的八方位、“进门朝西”这类结论必须有一个外部锚点，做法是**只问一句**：
「首点位（0 号，Work observers 按 index 升序的第一个）打开全景时的初始视角，对着现实哪个方向？」
用户答一个八方位或罗盘角即可，其余点位与房间按各自朝向自动换算，不必逐点描述。

```bash
# 首点位初始视角对着西（270°）；不给 --pano-index 就是首点位
python <skill-dir>/scripts/orientation.py --workspace <输出目录> --compass-deg 270 --kind entrance
python <skill-dir>/scripts/pipeline.py all --resource-code <RC> --compass-deg 270   # 一步到位
```

- 罗盘角 `0=北 90=东 180=南 270=西`，区间 `[0,360)`；八方位精度即可（引擎按 ±22.5° 归桶）。
- 落盘 `<workspace>/inputs/orientation.json`，引擎用 `--orientation-json` 读取，写进文档的
  `frame.orientation`（含 `northOffsetDeg` 与 `caveat`）以及每个点位/房间的 `compassDeg`、`sector`。
- 报告里必须保留 `caveat`：这是**用户确认的相对朝向**，不是实测地理北。
- 用户不确认时不要猜：报告会写「方位（未指定）」并说明影响——角度只相对首点位视角、没有地理北、
  **房间朝南/朝北、采光判断与户型图对齐都不可用**；此时不得写“坐北朝南”之类的绝对结论。
- 确认错了可以重跑 `orientation.py --force`；`--check` 只读回显。
- `--pano-index` 缺省 0 = 首点位；要换参考点位时才给（**分析文档里的点位号**，`frame.observers[].panoIndex`，从 0 起）；原始 Work 的 `index` 不连续时会被重编号，报告 §2 的「原始 index」列是两者的对照表。
- 朝向口径两档同源：前向 = `quaternion` 把全景相机坐标系的 `+Z`（全景中心）转到 Five 坐标；点位报告里的 `yaw` 以 `+Z` 为 0°、向 `+X` 增大（区间 `(−180,180]`），`compassDeg` 是 `[0,360)` 的罗盘角，两者只差用户给的北偏移。
- 完整档报告、`report.work-only.zh-CN.md` 与 `交付说明.md` 会多出一节「方位（用户指定）」，逐点列出朝向与八方位；没确认时改写「方位（未指定）」说清限制，`sector` 一律为 `null`，不要自己补。

## 判定顺序（照做就不会下错结论）

1. `pipeline.py inspect` 看 `declaredNotLocal`（Work 声明了什么、本地有没有）。
2. `prepare_work_assets.py --dry-run --json` 看 `capabilities.availableTiers` 与 `blockers`。
3. `check_env.py` 判断本机能否跑完整档（`fullOk`）与 work-only（`workOnlyOk`）；两者都不代表权重已就绪。
4. 结论写进报告开头：走的是哪档、缺什么、因此哪些指标不做。**不得把“环境缺依赖”写成“数据不支持”，也不得用 work-only 冒充完整结论。**
