Refactor Cesium material export contract

.trellis/tasks/08-03-material-export-contract/prd.md

@@ -0,0 +1,82 @@
+# Material export contract
+
+**类型**：refactor · **范围**：`blender` · **创建**：2026-08-03
+
+---
+
+## Goal
+
+把 Cesium 导出调色/覆盖规则从 `blender/export_cesium.py` 里的材质名字符串表迁移到
+`blender/osmassets/catalog.py` 的材质声明中，让 Blender 场景材质自己携带 Cesium
+导出契约，降低改材质名时静默断开导出效果的风险。
+
+用户价值：后续新增或重命名材质时，只需要维护 `catalog.MATERIALS` 附近的材质定义；
+Cesium 导出器消费 `.blend` 中保存的契约，而不是靠另一份易漂移的字符串表猜测。
+
+## Background
+
+当前实际状态由代码和 spec 共同确认：
+
+- `blender/osmassets/catalog.py:56` 的 `MATERIALS` 是材质声明源；`materials.py:198`
+  的 `from_spec()` 把 spec 构造成真实 Blender 材质。
+- `blender/export_cesium.py:68,80,86,95` 仍维护四张以 `material.name` 为 key 的导出覆盖表：
+  `EXPORT_TINTS`、`EXPORT_METALLIC_OVERRIDES`、`EXPORT_BASE_COLOR_OVERRIDES`、
+  `EXPORT_EMISSION_OVERRIDES`。
+- `blender/osmassets/catalog.py:142` 已有 `CESIUM_EXPORT`，但 `.trellis/spec/blender/module-structure.md`
+  记录它是死代码，当前导出器不会读取。
+- `"Office White Metal Facade"` 仍出现在 `export_cesium.py:74,82,91,100`，但当前
+  `catalog.MATERIALS` 已无对应材质；这是 `docs/refactor-plan.md` / spec 记录的 D1。
+- `.trellis/spec/guides/artifact-parity-guide.md` 记录 P3 未做：材质契约化仍缺失。
+
+## Requirements
+
+1. `catalog.MATERIALS` 中需要 Cesium 特殊导出的材质必须就地携带 `cesium` 子契约。
+   该契约覆盖现有四张表的有效行为，包括 `tint`、`metallic`、`base_color`、`emission`。
+2. `materials.from_spec()` 必须在创建材质时把 `spec["cesium"]` 序列化写入材质自定义属性
+   `material["cesium_export"]`，使 `.blend` 能保存该契约。
+3. `export_cesium.py` 必须优先读取 `material["cesium_export"]` 并据此导出；只有旧 `.blend`
+   或缺失属性的材质才回退到现有四张表。
+4. 旧 `.blend` 兼容性必须保留：没有 `cesium_export` 自定义属性时，导出行为不应比当前更少。
+5. alpha cut-out foliage 的特殊路径保持现状：`FOLIAGE_ALBEDO_GAIN`、`FOLIAGE_SATURATION`、
+   `FOLIAGE_EMISSION`、`alpha_dilated_image()` 和 diffuse-as-emissive texture 逻辑不在本任务重构。
+6. 本任务是契约迁移，不是视觉调参；目标是新生成产物的结构摘要尽量与迁移前一致。
+7. 本任务不得把 `bpy` 引入 `catalog.py`，不得把 `export_cesium.py` 改成直接 import
+   `catalog` 再按材质名反查。
+8. 任务完成后需要更新 `.trellis/spec/blender/` 中关于当前材质名字符串对接、`catalog.CESIUM_EXPORT`
+   死代码、P3 未完成状态的说明。
+
+## Out of Scope
+
+- 不修 `docs/refactor-plan.md` 的 D2：`scene-layers.js` 与 `catalog.py` 颜色不同步已经被 spec
+  定性为刻意设计。
+- 不清理 `generate_scene.py` 的 `tuft_density_wave` 注释 D3。
+- 不做 P2 features 注册表重构。
+- 不改变道路图层顺序、`MATERIALS` 创建顺序、stage stdout 标记或 Cesium preview 运行时。
+- 不新增依赖、lint/type 工具链或 CI。
+
+## Acceptance Criteria
+
+- [ ] 新生成的 `.blend` 材质中，已有 Cesium 覆盖规则的 catalog 材质带有
+      `cesium_export` 自定义属性。
+- [ ] `export_cesium.py` 对带 `cesium_export` 的材质优先使用该属性；对缺失属性的旧材质仍走
+      旧四张表回退。
+- [ ] `"Office White Metal Facade"` 不再出现在新契约源中；若旧表保留它，只能作为旧 `.blend`
+      回退兼容存在，并在代码注释中说明。
+- [ ] `catalog.CESIUM_EXPORT` 不再是死代码：要么被移除并迁入 `MATERIALS[*]["cesium"]`，
+      要么被真实读取；最终 spec 与代码描述一致。
+- [ ] `python3 -m unittest discover blender/tests` 通过。
+- [ ] 对默认 parity 样本执行改动前/改动后 capture + compare；如果结构摘要差异存在，
+      必须逐条解释为预期差异或修复到全绿。
+- [ ] `.trellis/spec/blender/module-structure.md` 与 `.trellis/spec/blender/asset-generation.md`
+      更新为新的材质导出契约，不再把“改 `catalog.CESIUM_EXPORT` 不会生效”描述为当前事实。
+
+## Key Decisions
+
+- 采用材质自定义属性 `cesium_export` 作为跨 `.blend` 的契约载体，而不是让导出器 import
+  `catalog`。原因：旧 `.blend` 没有当前 Python catalog 上下文也应该能导出；契约必须跟着场景文件走。
+- 回退旧四张表作为兼容层保留到本任务结束，不在同一任务里删除兼容路径。
+- 不触碰 foliage alpha 特殊路径，避免把高风险贴图处理与 contract 迁移混在一起。
+
+## Open Questions
+
+无阻塞开放问题。实现前仍需要用户确认本规划摘要并允许进入 `in_progress`。