155 lines
5.4 KiB
Markdown
155 lines
5.4 KiB
Markdown
# 执行计划：Trellis spec 重建
|
||
|
||
> 对应 `prd.md` / `design.md`。按序执行，每步带验证命令。
|
||
|
||
---
|
||
|
||
## 前置校验
|
||
|
||
```bash
|
||
# 确认当前 spec layers 是错的（预期输出含 frontend）
|
||
python3 ./.trellis/scripts/get_context.py --mode packages
|
||
|
||
# 确认纯 Python 测试基线是绿的（本任务不该改代码，收尾要复验）
|
||
python3 -m unittest discover blender/tests -v 2>&1 | tail -5
|
||
```
|
||
|
||
记录测试基线的用例数，收尾时比对。
|
||
|
||
---
|
||
|
||
## Step 1 — 删除错配脚手架
|
||
|
||
- [ ] 删除 `.trellis/spec/frontend/`（7 个文件：index + 6 个模板）
|
||
|
||
**只删这一个目录**，`guides/` 必须保留。
|
||
|
||
```bash
|
||
rm -rf .trellis/spec/frontend
|
||
python3 ./.trellis/scripts/get_context.py --mode packages # Spec layers 应为空
|
||
```
|
||
|
||
---
|
||
|
||
## Step 2 — `pipeline/` 包（4 个文件）
|
||
|
||
按依赖顺序写，`layer-registry.md` 是核心，先写它。
|
||
|
||
- [ ] 2.1 `pipeline/layer-registry.md` — 取材 `scene-layers.js` 全文 + `catalog.py:1-19,25-47,162-195`
|
||
- [ ] 2.2 `pipeline/external-tools.md` — 取材 `reimport-gpkg.js` 全文 + `build-area.js:237-311`
|
||
- [ ] 2.3 `pipeline/cli-and-stages.md` — 取材 `build-area.js:1-50,74-215`
|
||
- [ ] 2.4 `pipeline/index.md` — 包索引 + 五个 stage 的数据流全景
|
||
|
||
**写 2.3 前需补读**：`build-osm2streets-qgis.js`（1468 行，尚未通读）确认 stage 内部
|
||
细节与 `normalize-lane-arrows.py` 的调用方式。
|
||
|
||
验证：
|
||
```bash
|
||
grep -c "scripts/" .trellis/spec/pipeline/*.md # 每个文件应 >= 2
|
||
grep -rn "To fill\|TODO\|待填" .trellis/spec/pipeline/ ; echo "exit=$?" # 应为 1（无匹配）
|
||
```
|
||
|
||
---
|
||
|
||
## Step 3 — `blender/` 包（4 个文件）
|
||
|
||
- [ ] 3.1 `blender/module-structure.md` — 取材 `osmassets/__init__.py` + 各模块 docstring
|
||
- [ ] 3.2 `blender/testing.md` — 取材 `test_pure.py:1-11` + 各 `test_degenerate_*`
|
||
- [ ] 3.3 `blender/asset-generation.md` — 取材 `mesh.py`, `materials.py`, `tree.py`, `catalog.py` + changelog 2026-07-31
|
||
- [ ] 3.4 `blender/index.md` — 包索引 + 依赖分层图（纯 Python / bpy 两层）
|
||
|
||
**写 3.3 前需补读**：`generate_scene.py`（999 行）与 `export_cesium.py`（624 行）的
|
||
结构，确认材质名跨文件对接的实际方式。
|
||
|
||
验证：
|
||
```bash
|
||
grep -c "blender/" .trellis/spec/blender/*.md
|
||
grep -rn "To fill\|TODO\|待填" .trellis/spec/blender/ ; echo "exit=$?"
|
||
```
|
||
|
||
---
|
||
|
||
## Step 4 — `preview/` 与 `config/`（各 1 个文件）
|
||
|
||
- [ ] 4.1 `preview/index.md` — 取材 `cesium-preview.js` + `build-area.js:697-767`
|
||
- [ ] 4.2 `config/index.md` — 取材 `config/examples/template.json` + `build-area.js:74-142` + README 配置节
|
||
|
||
**写 4.1 前需补读**：`cesium-preview.js`（672 行）主体，目前只读了前 30 行。
|
||
|
||
---
|
||
|
||
## Step 5 — `guides/` 本地化 + 新增
|
||
|
||
- [ ] 5.1 新增 `guides/artifact-parity-guide.md` — 取材 `docs/refactor-plan.md` + `parity.js` + `glb-digest.js` + `scene_digest.py`
|
||
- [ ] 5.2 更新 `guides/cross-layer-thinking-guide.md` 的触发点清单（保留通用内容）
|
||
- [ ] 5.3 更新 `guides/code-reuse-thinking-guide.md` 的触发点清单
|
||
- [ ] 5.4 更新 `guides/index.md` 的指南表格，加入新指南
|
||
|
||
---
|
||
|
||
## Step 6 — 顶层索引与任务元数据
|
||
|
||
- [ ] 6.1 新增 `.trellis/spec/index.md` — 四包路由表
|
||
- [ ] 6.2 修正 `task.json`：`relatedFiles` 改为四个新包目录，`notes` 去掉 "(frontend project)"
|
||
|
||
```bash
|
||
python3 ./.trellis/scripts/task.py set-meta ... # 或直接编辑 task.json
|
||
```
|
||
|
||
---
|
||
|
||
## Step 7 — 全量验收
|
||
|
||
对照 `prd.md` 验收标准逐条过：
|
||
|
||
```bash
|
||
# 1. spec layers 正确
|
||
python3 ./.trellis/scripts/get_context.py --mode packages
|
||
# 预期：Spec layers: blender, config, pipeline, preview
|
||
|
||
# 2. 无占位文本
|
||
grep -rn "To fill\|TODO\|待填\|FIXME\|<!-- fill" .trellis/spec/ ; echo "exit=$? (1=clean)"
|
||
|
||
# 3. frontend 已清除
|
||
test -d .trellis/spec/frontend && echo "FAIL: still exists" || echo "OK: removed"
|
||
|
||
# 4. 每个包有 index.md
|
||
for d in pipeline blender preview config; do
|
||
test -f ".trellis/spec/$d/index.md" && echo "OK $d" || echo "FAIL $d"
|
||
done
|
||
|
||
# 5. 关键约定可 grep 定位（8 条）
|
||
grep -rl "COORDINATE_PRECISION" .trellis/spec/ # 约定 3
|
||
grep -rl "check_layers" .trellis/spec/ # 约定 1
|
||
grep -rl "PROJ_LIB\|GDAL_DATA" .trellis/spec/ # 约定 4 相关
|
||
grep -rl "互斥" .trellis/spec/ # 约定 5
|
||
grep -rl "bpy" .trellis/spec/blender/ # 约定 6
|
||
grep -rl "parity" .trellis/spec/ # 约定 8
|
||
|
||
# 6. 代码未被误改
|
||
git status --porcelain -- scripts/ blender/ config/ # 应为空
|
||
python3 -m unittest discover blender/tests 2>&1 | tail -3
|
||
```
|
||
|
||
---
|
||
|
||
## 回滚点
|
||
|
||
本任务只新增/删除 `.trellis/spec/` 下的文件，且删除的 `frontend/` 是**未提交的
|
||
未跟踪文件**（`.trellis/` 整体尚未入库）。
|
||
|
||
回滚代价：`frontend/` 的 7 个空模板删掉后无法从 git 恢复。但它们是 `trellis init`
|
||
生成的、内容为纯占位符，可用 `trellis init` 重新生成，或直接接受丢失——PRD 已确认
|
||
它们对本项目无价值。
|
||
|
||
**保险起见**：Step 1 执行前先把 `.trellis/spec/frontend/` 打包到
|
||
`/tmp/trellis-frontend-backup.tar.gz`，任务归档后再删。
|
||
|
||
---
|
||
|
||
## 审查门
|
||
|
||
- Step 2 完成后暂停，让用户看 `pipeline/layer-registry.md`——这篇最能反映
|
||
spec 的目标风格。风格若不对，后面 7 个文件不必按同样方式写完再返工。
|
||
- Step 7 全部通过后再报告完成。
|