docs(assets): document reusable asset package contract

This commit is contained in:
que01 committed 2026-08-12 09:06:04 +08:00
1 parent f2b8d79f5d
commit 0102ffbb3c
4 files changed
+182 -56

No files matched your search

+19 -7
View File
@@ -68,11 +68,14 @@ cp config/examples/template.json config/areas/my-area.json
| `intermediates` | `true` | 旧名 `qgis` 仍被接受 |
| `blender` | `true` | |
| `cesium` | `true` | |
| `compress` | `true` | 压缩 staged GLB,供随后发布使用 |
| `package` | `true` | 将通过校验的静态模型原子发布到 `package/` |
| `preview` | `true` | 基于已发布 package 写验证预览及 `_preview/` 动态资源 |
`reimport` 和 `preview` **在这里配也没用**——`normalizeAreaConfig` 把它们
硬编码为 `false`,只能靠 `--stages` 显式请求。`compress` 始终默认开启。
`reimport` **在这里配也没用**——`normalizeAreaConfig` 把它硬编码为 `false`,只能靠
`--stages` 显式请求。`compress`、`package` 和 `preview` 始终默认开启。
> 恢复动作(reimport)和补丁动作(preview)不该被一份配置文件变成默认行为;压缩是标准交付链的一部分。
> 恢复动作(reimport)不该被一份配置文件变成默认行为;压缩、发布和验证预览是标准交付链的一部分。
`--stages` 会整体覆盖这里的默认值。
@@ -133,7 +136,8 @@ cp config/examples/template.json config/areas/my-area.json
### `compress`
完整构建和显式 `--stages compress` 都使用此配置。默认压缩链是 texture resize + WebP
transcode,成功后覆盖标准 `<area-id>.glb`、`.json` 和预览 HTML;未压缩源只保留在构建临时目录。
transcode,成功后替换**package staging** 中的主 GLB 与 manifest;未压缩源只保留在构建临时目录。
只有随后的 `package` 阶段才会原子发布到 `package/`。
| 字段 | 默认 | 说明 |
|---|---|---|
@@ -161,14 +165,16 @@ transcode,成功后覆盖标准 `<area-id>.glb`、`.json` 和预览 HTML;未
### `outputs`(逃生舱)
默认全部从 `id` 推导为 `<outputRoot>/<id>/<fileStem>.<ext>`。需要定制时逐项覆盖:
默认全部从 `id` 推导。发布给下游的静态资产固定在
`<outputRoot>/<id>/package/`,临时静态资产在 `_pipeline/package-staging/`,预览专用动态资源在
`<outputRoot>/<id>/_preview/`。需要定制时逐项覆盖:
```json
{
"outputs": {
"areaDir": "/absolute/path/to/custom-area",
"blend": "/absolute/path/to/custom.blend",
"glb": "/absolute/path/to/custom.glb",
"packageDir": "/absolute/path/to/custom-package",
"cesiumPreview": "/absolute/path/to/custom-preview.html"
}
}
@@ -178,6 +184,11 @@ transcode,成功后覆盖标准 `<area-id>.glb`、`.json` 和预览 HTML;未
`qgisProject`、`qgisPreview`、`blend`、`render`、`glb`、`metadata`、`cesiumPreview`、
`vehicleRoute`、`vehicleModel`、`pipelineDir`、`stageManifestDir`。
静态发布路径另有 `packageDir`、`packageStagingDir`、`packageManifest`、
`packageStagingManifest`、`packageModelDir`、`packageStagingModelDir` 与
`packagePrimaryGlb`;预览路径另有 `previewDir` 与 `previewDescriptor`。除非在迁移旧调用,
不要覆盖 `glb` / `metadata`:它们是 staging 内部路径,不是下游资产入口。
**优先改 `fileStem` 或 `areaDir`**——它们能一次性影响全部派生路径。逐个覆盖容易漏。
---
@@ -219,7 +230,8 @@ transcode,成功后覆盖标准 `<area-id>.glb`、`.json` 和预览 HTML;未
| 布尔字段用 `\|\|` 兜底 | `false` 被翻转 |
| 给新字段造顶层平铺别名 | 扩大历史包袱 |
| 逐个覆盖 `outputs` 而不用 `fileStem` | 漏掉某个产物路径 |
| 在 `stages` 里配 `reimport` / `preview` | 无效,被硬编码为 false |
| 将 `glb` / `metadata` 当作下游入口 | 它们位于 staging;应只读取 `package/manifest.json` |
| 在 `stages` 里配 `reimport` | 无效,被硬编码为 false |
| 加数值字段不做范围校验 | 错配置在中途才崩,输出已被破坏 |
---