# 执行计划：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 全部通过后再报告完成。