Refactor Cesium material export contract

.trellis/spec/blender/module-structure.md

@@ -135,31 +135,52 @@ argv = sys.argv[sys.argv.index("--") + 1:] if "--" in sys.argv else []
 
 ---
 
-## ⚠️ 已知现状：两个入口靠材质名字符串对接
+## 材质名对接：新场景靠自定义属性，旧场景靠回退表
 
-**这是当前实际状态，不是设计目标。改动材质名之前必读。**
+`export_cesium.py` **不 import `catalog`**，这是刻意边界：导出器消费 `.blend`
+里保存的材质事实，而不是用当前源码里的 catalog 按材质名反查。
 
-`export_cesium.py` **不 import `catalog`**（它只 import
-`from osmassets.materials import link_alpha_clip`）。它自己维护四张以**材质名字符串**
-为键的覆盖表：
+新生成场景的数据流是：
+
+```
+catalog.MATERIALS[*]["cesium"]   # 纯 Python 数据，无 bpy
+        ↓
+materials.from_spec()            # 写 material["cesium_export"] JSON 字符串
+        ↓
+<area>.blend                     # 契约随场景文件保存
+        ↓
+export_cesium.py                 # 优先读 material custom property
+```
+
+`cesium` 子契约可携带：
+
+| 字段 | 作用 |
+|---|---|
+| `tint` | diffuse 贴图导出前往目标颜色混合 |
+| `metallic` | 覆盖导出 PBR metallic |
+| `base_color` | 直接覆盖导出材质 base color，并禁用 diffuse/normal 图 |
+| `emission` | 设置导出材质自发光 |
+
+为了兼容旧 `.blend`，`export_cesium.py` 仍保留四张以**材质名字符串**为键的回退表：
 
 | 表 | 位置 |
 |---|---|
-| `EXPORT_TINTS` | `export_cesium.py:68` |
-| `EXPORT_METALLIC_OVERRIDES` | `:80` |
-| `EXPORT_BASE_COLOR_OVERRIDES` | `:86` |
-| `EXPORT_EMISSION_OVERRIDES` | `:95` |
+| `EXPORT_TINTS` | `export_cesium.py` |
+| `EXPORT_METALLIC_OVERRIDES` | `export_cesium.py` |
+| `EXPORT_BASE_COLOR_OVERRIDES` | `export_cesium.py` |
+| `EXPORT_EMISSION_OVERRIDES` | `export_cesium.py` |
 
-后果：
+约束：
 
-- **改 `catalog.MATERIALS` 里的 `name` 会静默断开这些覆盖**。没有任何校验，
-  材质只是悄悄退回未调过的样子
-- `catalog.CESIUM_EXPORT`（`catalog.py:142`）**是死代码**——定义了但全仓无人引用。
-  它是一次未完成的迁移，不要以为改它会生效
+- **新材质的 Cesium 调色写在 `catalog.MATERIALS[*]["cesium"]`，不要只加到四张回退表**。
+  否则新生成的 `.blend` 不会自带契约
+- `catalog.py` 仍属纯 Python 层，不能 import `bpy`；序列化发生在 `materials.py`
 - `"Office White Metal Facade"` 在四张表里都有，但 `catalog` 里**已无此材质**
-  （`docs/refactor-plan.md` 记为缺陷 D1，本轮只记录不修）
+  （`docs/refactor-plan.md` 记为缺陷 D1）。它只能作为旧 `.blend` 回退兼容存在，
+  不要迁回新契约源
 
-**改材质名时**：四张表 + `catalog.MATERIALS` + `catalog.ROAD_LAYERS` 全部 grep 一遍。
+**改材质名时**：`catalog.MATERIALS` + `catalog.ROAD_LAYERS` + 四张旧回退表全部
+grep 一遍；新生成场景靠 `cesium_export` 属性，旧场景仍靠回退表。
 
 ---
 
@@ -172,8 +193,8 @@ argv = sys.argv[sys.argv.index("--") + 1:] if "--" in sys.argv else []
 | 删掉 `sys.path.insert` 样板或 `# noqa: E402` | Blender 里 import 不到 osmassets |
 | 要素模块假设 ring 已裁剪 | 越界几何进场景 |
 | 要素模块对退化输入抛异常 | 一个坏多边形中断整片区域 |
-| 改材质名只改一处 | Cesium 侧调色静默失效 |
-| 以为改 `catalog.CESIUM_EXPORT` 会影响导出 | 它是死代码 |
+| 改材质名只改一处 | 旧 `.blend` 的 Cesium 回退调色可能静默失效 |
+| 只改四张旧回退表，不改 `MATERIALS[*]["cesium"]` | 新 `.blend` 不会携带 Cesium 导出契约 |
 
 ---