From 68829214fb7e2fd16951b0a1a20beb01bce220d7 Mon Sep 17 00:00:00 2001 From: que01 Date: Mon, 3 Aug 2026 12:12:49 +0800 Subject: [PATCH] docs: Archive osmassets refactor plan --- .trellis/spec/blender/module-structure.md | 4 +- .trellis/spec/guides/artifact-parity-guide.md | 8 +- .../08-03-archive-refactor-plan/check.jsonl | 2 + .../implement.jsonl | 2 + .../tasks/08-03-archive-refactor-plan/prd.md | 35 ++++++ .../08-03-archive-refactor-plan/task.json | 30 +++++ docs/changelog.md | 15 +++ docs/refactor-plan.md | 112 ------------------ 8 files changed, 90 insertions(+), 118 deletions(-) create mode 100644 .trellis/tasks/08-03-archive-refactor-plan/check.jsonl create mode 100644 .trellis/tasks/08-03-archive-refactor-plan/implement.jsonl create mode 100644 .trellis/tasks/08-03-archive-refactor-plan/prd.md create mode 100644 .trellis/tasks/08-03-archive-refactor-plan/task.json delete mode 100644 docs/refactor-plan.md diff --git a/.trellis/spec/blender/module-structure.md b/.trellis/spec/blender/module-structure.md index 0ea978c..e842853 100644 --- a/.trellis/spec/blender/module-structure.md +++ b/.trellis/spec/blender/module-structure.md @@ -85,7 +85,7 @@ def assemble(ring, [way_id,] scene_xmin, scene_xmax, scene_ymin, scene_ymax, ### 加一种新 OSM 要素 -目标形态（`docs/refactor-plan.md`）：**新增一个模块 + 注册一行，不改 `build()`**。 +目标形态：**新增一个模块 + 注册一行，不改 `build()`**。 1. 新建 `osmassets/.py`，写 `assemble(...)`，签名照抄上面 2. 只 import 需要的：`from osmassets.geom import clip_polygon`、 @@ -176,7 +176,7 @@ export_cesium.py # 优先读 material custom property 否则新生成的 `.blend` 不会自带契约 - `catalog.py` 仍属纯 Python 层，不能 import `bpy`；序列化发生在 `materials.py` - `"Office White Metal Facade"` 在四张表里都有，但 `catalog` 里**已无此材质** - （`docs/refactor-plan.md` 记为缺陷 D1）。它只能作为旧 `.blend` 回退兼容存在， + （历史上记为缺陷 D1）。它只能作为旧 `.blend` 回退兼容存在， 不要迁回新契约源 **改材质名时**：`catalog.MATERIALS` + `catalog.ROAD_LAYERS` + 四张旧回退表全部 diff --git a/.trellis/spec/guides/artifact-parity-guide.md b/.trellis/spec/guides/artifact-parity-guide.md index 519c68e..49bf966 100644 --- a/.trellis/spec/guides/artifact-parity-guide.md +++ b/.trellis/spec/guides/artifact-parity-guide.md @@ -57,7 +57,7 @@ node scripts/parity.js compare control-1 control-2 # 必须全绿 没做这步就开始改代码，你会分不清一个差异是"重构引入的 bug"还是"本来就每次都不一样"。 -已完成的 control 结论（`docs/refactor-plan.md`）： +已完成的 control 结论： - `.blend` **结构摘要两次完全一致** ← 这是主校验信号，可信 - `.blend` 文件 sha256 不一致 @@ -147,7 +147,7 @@ capturedAt / durationMs / label ## 风险高的改动要分次提交 -`docs/refactor-plan.md` 对风险最高的一期写着： +要素注册表这类高风险重构必须按要素分次提交： > 逐要素分次提交，每次单独跑 parity。 @@ -155,9 +155,9 @@ capturedAt / durationMs / label --- -## 当前重构进度（`docs/refactor-plan.md`） +## 当前重构进度 -那份计划是**临时工作文档**，P3 收尾后会并入 changelog 并删除。当前状态： +临时施工计划已删除；长期状态以本指南和 `docs/changelog.md` 为准： | 期 | 内容 | 状态 | |---|---|---| diff --git a/.trellis/tasks/08-03-archive-refactor-plan/check.jsonl b/.trellis/tasks/08-03-archive-refactor-plan/check.jsonl new file mode 100644 index 0000000..c7c96a8 --- /dev/null +++ b/.trellis/tasks/08-03-archive-refactor-plan/check.jsonl @@ -0,0 +1,2 @@ +{"file": ".trellis/spec/guides/artifact-parity-guide.md", "reason": "Check that parity/control knowledge survives after deleting the temporary refactor plan."} +{"file": ".trellis/spec/guides/index.md", "reason": "Check guide references remain accurate and no stale refactor-plan links remain."} diff --git a/.trellis/tasks/08-03-archive-refactor-plan/implement.jsonl b/.trellis/tasks/08-03-archive-refactor-plan/implement.jsonl new file mode 100644 index 0000000..7327bb1 --- /dev/null +++ b/.trellis/tasks/08-03-archive-refactor-plan/implement.jsonl @@ -0,0 +1,2 @@ +{"file": ".trellis/spec/guides/artifact-parity-guide.md", "reason": "Contains refactor-plan status and references that must be preserved without linking to the deleted temporary file."} +{"file": ".trellis/spec/guides/index.md", "reason": "Shared guide routing for cross-layer and parity documentation changes."} diff --git a/.trellis/tasks/08-03-archive-refactor-plan/prd.md b/.trellis/tasks/08-03-archive-refactor-plan/prd.md new file mode 100644 index 0000000..2688c7b --- /dev/null +++ b/.trellis/tasks/08-03-archive-refactor-plan/prd.md @@ -0,0 +1,35 @@ +# Archive refactor plan + +**类型**：docs · **范围**：docs/spec · **创建**：2026-08-03 + +--- + +## Goal + +收尾临时文档 `docs/refactor-plan.md`：把仍有价值的 P0-P3 重构结论并入长期文档， +然后删除这份已过期的临时计划，避免后续 AI 或开发者读到 P3 未做、旧行号、旧 `CESIUM_EXPORT` +状态等过期事实。 + +## Requirements + +1. `docs/changelog.md` 必须新增一条 2026-08-03 记录，总结材质导出契约化、Trellis + spec 初始化，以及 `docs/refactor-plan.md` 的收尾处理。 +2. 删除 `docs/refactor-plan.md`，因为它开头已声明 P3 收尾后应并入 changelog 并删除。 +3. 更新 `.trellis/spec/guides/artifact-parity-guide.md` 中对 `docs/refactor-plan.md` 的 + 直接依赖，保留 parity/control 结论和 P0-P3 当前状态，但不引用已删除文件。 +4. 不改业务代码，不改 Blender/Cesium 产物，不修 D1-D3。 +5. 删除后不得留下指向 `docs/refactor-plan.md` 的断链引用。 + +## Acceptance Criteria + +- [ ] `docs/refactor-plan.md` 不存在。 +- [ ] `docs/changelog.md` 顶部有 2026-08-03 条目，记录 P3 完成和临时计划归档。 +- [ ] `rg "docs/refactor-plan.md|refactor-plan" docs .trellis/spec README.md` 不再发现活文档引用。 +- [ ] `git diff --check` 通过。 +- [ ] 工作范围只包含 docs、`.trellis/spec` 和当前 Trellis task 文件。 + +## Out of Scope + +- P2 要素注册表补完。 +- D1/D2/D3 修复。 +- 任何 `blender/`、`scripts/`、`config/` 业务代码改动。 diff --git a/.trellis/tasks/08-03-archive-refactor-plan/task.json b/.trellis/tasks/08-03-archive-refactor-plan/task.json new file mode 100644 index 0000000..1b2b238 --- /dev/null +++ b/.trellis/tasks/08-03-archive-refactor-plan/task.json @@ -0,0 +1,30 @@ +{ + "id": "archive-refactor-plan", + "name": "archive-refactor-plan", + "title": "Archive refactor plan", + "description": "Move completed osmassets refactor-plan conclusions into changelog and remove the stale temporary plan.", + "status": "in_progress", + "dev_type": "docs", + "scope": "docs/spec", + "package": null, + "priority": "P2", + "creator": "dingkang", + "assignee": "dingkang", + "createdAt": "2026-08-03", + "completedAt": null, + "branch": null, + "base_branch": "main", + "worktree_path": null, + "commit": null, + "pr_url": null, + "subtasks": [], + "children": [], + "parent": null, + "relatedFiles": [ + "docs/changelog.md", + "docs/refactor-plan.md", + ".trellis/spec/guides/artifact-parity-guide.md" + ], + "notes": "Lightweight docs cleanup. Remove stale temporary refactor plan after merging durable conclusions into changelog/spec.", + "meta": {} +} \ No newline at end of file diff --git a/docs/changelog.md b/docs/changelog.md index 22ed5c1..86101ad 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -1,5 +1,20 @@ # Changelog +## 2026-08-03 + +- 初始化 Trellis 项目规范，把 `trellis init` 误生成的 frontend spec 替换为本项目真实的 + `pipeline` / `blender` / `preview` / `config` 四层规范，并把跨层 parity、图层顺序、 + 外部工具 staging、纯 Python / bpy 边界等反直觉约定固化到 `.trellis/spec/`。 +- 完成 Cesium 材质导出契约化：`catalog.MATERIALS[*]["cesium"]` 现在由 + `materials.from_spec()` 写入 `.blend` 材质自定义属性 `material["cesium_export"]`， + `export_cesium.py` 优先读取该属性；旧四张材质名表仅保留为旧 `.blend` 回退路径。 + parity before/after 只有 `.blend` 新增 `props.cesium_export` 与 `.blend` bytes 变化， + 无 GLB/material/metadata 结构漂移。 +- 收尾临时 `osmassets` 重构施工计划：P0/P1/P3 的长期知识已经进入 changelog 和 Trellis spec； + P2 仍是后续重构方向（`building` / `fountain` / `roads` 仍在 `generate_scene.py` 里， + 尚未形成完整 `features/` 注册表）。删除临时计划文件，避免继续传播旧行号和 + `catalog.CESIUM_EXPORT` 死代码等过期事实。 + ## 2026-07-31（三）远看发黑的真正原因：反照率没被提亮 （二）里加的 emissive 提到 0.8 仍然发黑。原因是 emissive 乘的是本来就很暗的 diff --git a/docs/refactor-plan.md b/docs/refactor-plan.md deleted file mode 100644 index 35e86b3..0000000 --- a/docs/refactor-plan.md +++ /dev/null @@ -1,112 +0,0 @@ -# 重构施工计划：`osmassets` 包化（P0–P3） - -> 临时工作文档。P3 收尾后把结论并入 `docs/changelog.md`，本文件删除。 - -## 目标 - -把「从 OSM 生成 Blender / Cesium 资产」的逻辑从两个单体脚本里拆成可复用的库，使得： - -- 新增一种 OSM 要素 = 新增一个 `features/*.py` + 注册一行，不改 `build()` -- 道路图层表、材质规格只有一份定义，JS 侧与 Python 侧不再各存一份 -- `export_cesium.py` 不再靠材质名字符串跟 `generate_scene.py` 对接 -- 纯几何 / 解析逻辑脱离 `bpy`，可用系统 python 直接测 - -## 硬约束：严格产物一致 - -P0–P3 全程 **不改变任何输出**。每期结束必须通过 parity 校验，任何差异都要么消除、要么在本文件里逐条记录原因。 - -已知缺陷（本轮**只记录、不修**）： - -| # | 位置 | 现象 | -|---|---|---| -| D1 | `export_cesium.py:26,34,40,52` | `"Office White Metal Facade"` 四张表里都有，`generate_scene.py` 里已无此材质——死条目 | -| D2 | `scene-layers.js:15` vs `generate_scene.py:1017` | 同一批图层的颜色两侧各自手调，无一致性保证 | -| D3 | `generate_scene.py:788` | `tuft_density_wave` 注释仍在跟已删除的 hedge banding 作对比 | - -## Parity 工具与基线 - -`outputs/` 已在 `.gitignore` 中，基线快照放 `outputs/_refactor-baseline/`，不入库。 - -| 工具 | 位置 | 作用 | -|---|---|---| -| 场景摘要 | `blender/tools/scene_digest.py` | 在 Blender 内打开 `.blend`，输出稳定 JSON：对象名/顶点数/面数/材质槽/自定义属性、材质参数、场景属性 | -| GLB 摘要 | `scripts/glb-digest.js` | 纯 Node 读 GLB 的 JSON chunk，输出 node/mesh/material 清单与 PBR 参数，附 buffer 字节长度 | -| 驱动 | `scripts/parity.sh