docs: add board substrate and finish library design spec

furniture-3d-system/docs/superpowers/specs/2026-04-08-board-substrate-finish-library-design.md

@@ -0,0 +1,397 @@
+# 板材库基材库与花色库增强设计
+
+日期：2026-04-08  
+适用分支：`codex/xuxiake-packaging`  
+目标模块：`src/app/asset-center` 及其板材相关接口/服务
+
+## 1. 本次只处理什么
+
+本次只处理资产中心里“板材”相关资料的第一版增强，目标是把现有的“基材库”和“饰面 / 花色库”补成可用于板材自动测算的资料底座。
+
+本次范围内包括：
+
+- 在不改大结构的前提下，继续沿用当前 `资产中心` 页面里的板材入口
+- 把 `基材库` 定义为板材主规则库
+- 把 `花色库` 定义为颜色名称同步库
+- 明确板材价格、重量、面积的计算口径
+- 支持新建资产族时按所选板材规则自动带出板材重量和板材成本
+- 支持一个资产族挂多条板材明细
+- 首批只录入用户已提供明确价格与重量的数据
+
+## 2. 本次不处理什么
+
+本次明确不处理以下内容：
+
+- 不改资产中心的大页面结构，不新增新的板材独立工作台
+- 不处理损耗、开料利用率、整张板采购优化
+- 不处理供应商、采购单、历史报价版本
+- 不让花色库单独维护价格或重量
+- 不处理用户尚未提供价格的板材厚度或特殊颜色
+- 不扩到包装、仓库、 intake、draft-group 等其他主链模块
+
+## 3. 当前问题
+
+当前资产中心里已经有 `基材库` 和 `饰面 / 花色库` 的入口，但能力偏轻，主要问题是：
+
+- 基材库当前更像最小资料卡，只能录基础名称、编码、描述、密度
+- 花色库当前更像独立材质库，没有和板材报价规则形成稳定关联
+- 新建资产族时，板材成本和板材重量不能按用户的真实报价规则自动带出
+- 用户真实业务数据不是按“每平方米统一报价”维护，而是按“1220 × 2440 整张大板价格 + 整张大板重量”维护
+- 同一资产族可能同时使用多种板材规则，不能简化成“只选一种板材”
+
+结论：
+
+- 第一版需要把板材资料从“基础资料”升级为“可计算规则”
+
+## 4. 用户已确认的业务口径
+
+### 4.1 价格口径
+
+用户提供的报价全部按整张大板维护：
+
+- 默认大板规格：`1220 × 2440`
+- 录入价格：`整张大板价格`
+
+系统自动换算：
+
+- `大板面积 = 大板长 × 大板宽 ÷ 1000000`
+- `每平方米单价 = 整张大板价格 ÷ 大板面积`
+
+说明：
+
+- 默认标准板面积为 `2.9768`
+- 首版保留大板长宽字段，默认值分别为 `2440` 与 `1220`
+- 默认值允许人工修改，但首版以默认标准板为主
+
+### 4.2 重量口径
+
+用户提供的重量也按整张大板维护：
+
+- 录入重量：`整张板重量(kg)`
+
+系统自动换算：
+
+- `每平方米重量 = 整张板重量 ÷ 大板面积`
+
+### 4.3 资产族测算口径
+
+资产族里板材成本和板材重量都按净尺寸算，不算损耗：
+
+- `板材面积 = 长 × 宽 ÷ 1000000 × 数量`
+- `板材成本 = 面积 × 每平方米单价`
+- `板材重量 = 面积 × 每平方米重量`
+
+一个资产族可同时包含多条板材明细，最终按全部明细汇总：
+
+- `资产族板材总成本`
+- `资产族板材总重量`
+
+### 4.4 尺寸来源
+
+资产族板材面积来源支持两种方式：
+
+- 上传 CAD 后，由系统自动拉取板件尺寸
+- 手动录入 `长 × 宽 × 数量`
+
+两种方式最终都归一到同一套面积、成本、重量计算逻辑
+
+## 5. 推荐方案
+
+推荐方案：`基材库做主规则库，花色库做同步名称库`
+
+原因：
+
+- 最贴合用户当前的 Excel 数据结构
+- 既能支持“常规颜色同价”，也能支持“某个特殊颜色单独报价”
+- 后续新增数据时，只需要新增板材规则，不需要同时维护两套价格库
+- 可以在尽量少改现有大结构的前提下，把自动测算接进资产族
+
+不推荐把所有颜色完全展开成大量重复明细，也不推荐把价格规则拆到花色库单独维护
+
+## 6. 基材库设计
+
+### 6.1 核心定义
+
+`基材库 1 条记录 = 1 条可直接用于成本和重量测算的板材规则`
+
+它不是单纯的材质大类，而是一个组合规则。至少包含：
+
+- 材质
+- 环保等级
+- 厚度(mm)
+- 贴面
+- 花色规则
+- 整张大板价格
+- 整张板重量
+- 系统名称
+
+### 6.2 字段分组
+
+建议将基材库字段分成以下几组。
+
+基础识别字段：
+
+- 编码
+- 系统名称
+- 材质
+- 环保等级
+- 厚度(mm)
+- 贴面
+
+规则字段：
+
+- 花色适用方式
+- 花色范围说明
+
+原始报价字段：
+
+- 大板长(mm)，默认 `2440`
+- 大板宽(mm)，默认 `1220`
+- 整张采购价
+- 整张板重量(kg)
+
+系统换算字段：
+
+- 每平方米单价
+- 每平方米重量
+
+说明：
+
+- 第一版允许系统自动生成/自动换算后展示
+- 首版重点是“你来选，系统带数”，不是让用户逐个手填公式
+
+### 6.3 花色规则类型
+
+基材库里的花色规则建议支持以下几种类型：
+
+- `常规颜色`
+- `所有颜色`
+- `指定花色`
+
+含义如下：
+
+- `常规颜色`：表示使用该板种的默认常规颜色组，整组同价
+- `所有颜色`：表示该板种对其适用颜色池全部同价
+- `指定花色`：表示某个真实花色单独报价，例如 `冰川白石纹色`
+
+说明：
+
+- `常规颜色`、`所有颜色` 是规则，不是花色名称
+- `冰川白石纹色` 这类是真实花色名，需要同步进入花色库
+
+## 7. 花色库设计
+
+### 7.1 核心定义
+
+`花色库` 不再承担价格和重量维护，它只做统一的颜色名称池。
+
+花色库主要负责：
+
+- 统一颜色名称
+- 作为下拉选择来源
+- 标识适用材质范围
+- 由基材库新增规则时自动同步新花色
+
+### 7.2 花色库建议展示字段
+
+- 花色名称
+- 花色归属类型：常规 / 特殊
+- 适用材质范围
+- 是否启用
+
+### 7.3 同步规则
+
+同步规则建议如下：
+
+- 如果基材库中出现新的真实花色名，而花色库中不存在，则自动新增同名花色
+- 如果花色库已存在，则直接复用，不重复新增
+- `冰川白石纹色` 这类特殊花色必须自动进入花色库
+- 花色库不单独维护价格、重量、贴面或厚度
+
+### 7.4 首版默认花色池
+
+首版预置两组默认颜色池。
+
+常规颜色组，适用于：
+
+- 密度板
+- 刨花板
+- 生态板
+- 三合板
+
+颜色列表：
+
+- 胡桃木色
+- 北美原木纹色
+- 经典北美黑胡桃色
+- 大象灰色
+- 荷花白色
+- 烟熏黑色
+- 石墨灰色
+- 云霜灰色
+- 珍珠白色
+- 炭黑色
+- 榆木黑色
+- 浅黄橡木色
+- 莫兰橡木色
+- 柚木色
+
+橡胶木颜色组，适用于：
+
+- 橡胶木
+
+颜色列表：
+
+- 柚木色
+- 胡桃色
+- 原木色
+- 黑色
+
+## 8. 首版基材规则范围
+
+首版只录入用户已经提供明确价格和重量的数据。
+
+### 8.1 密度板
+
+- 环保等级：`E2`
+- 厚度：`12 / 15`
+- 贴面：`单 / 双`
+- 花色规则：
+  - `常规颜色`
+  - `冰川白石纹色`
+
+### 8.2 刨花板
+
+- 环保等级：`E1`
+- 厚度：`12 / 15`
+- 贴面：`单 / 双`
+- 花色规则：
+  - `常规颜色`
+  - `冰川白石纹色`
+
+### 8.3 生态板
+
+- 环保等级：`E1`
+- 厚度：`12 / 15`
+- 贴面：`双`
+- 花色规则：`所有颜色`
+
+### 8.4 三合板
+
+- 环保等级：`E1`
+- 厚度：`2.2`
+- 贴面：`双`
+- 花色规则：`所有颜色`
+
+### 8.5 橡胶木
+
+- 环保等级：`ENF`
+- 厚度：`12 / 15 / 18 / 20 / 25 / 30`
+- 贴面：`双`
+- 花色规则：
+  - `柚木色`
+  - `胡桃色`
+  - `原木色`
+  - `黑色`
+
+### 8.6 首版暂不录入
+
+- 密度板 / 刨花板 / 生态板尚未提供价格的 `18 / 25` 等其他厚度
+- 尚未提供价格的其他特殊颜色
+- 未确认口径的新增材种
+
+## 9. 资产族自动测算设计
+
+### 9.1 一条板材明细的录入顺序
+
+新建资产族时，每条板材明细推荐按以下顺序操作：
+
+1. 选择材质
+2. 选择环保等级
+3. 选择厚度
+4. 选择贴面
+5. 选择颜色
+6. 系统自动匹配一条基材规则
+7. 自动带出价格与重量
+8. 接收 CAD 拉取的板件尺寸，或手动录入 `长 × 宽 × 数量`
+9. 自动汇总这一条明细的面积、成本和重量
+
+### 9.2 多条板材明细
+
+一个资产族中允许存在多条板材明细，例如：
+
+- 台面使用一种板材规则
+- 侧板使用另一种板材规则
+- 背板使用第三种板材规则
+
+系统最终汇总所有板材明细的小计，得到资产族总成本与总重量
+
+### 9.3 匹配规则
+
+当用户在资产族中选择板材条件后，系统按以下顺序匹配：
+
+- 材质
+- 环保等级
+- 厚度
+- 贴面
+- 花色
+
+花色匹配规则：
+
+- 如果所选颜色属于常规颜色组，则优先匹配 `常规颜色` 规则
+- 如果所选颜色存在单独报价规则，例如 `冰川白石纹色`，则优先匹配该真实花色规则
+- 橡胶木只在自己的 4 个颜色里匹配
+- 如果没有匹配到规则，明确提示“基材库暂无这条资料”，不允许乱带价格
+
+## 10. 后续新增资料的维护方式
+
+第一版之后，资料维护建议收敛为一条线：
+
+- 新增一个已有逻辑下的新规格时，只在基材库新增一条规则
+- 新增一个新的特殊颜色时，也先在基材库新增对应规则
+- 如果花色库里没有该真实颜色名，系统自动同步新增
+
+首版不做复杂报价历史，价格变更先按“修改当前规则”处理
+
+这样可以先保证：
+
+- 录得清楚
+- 选得稳定
+- 算得出来
+
+等真实使用一段时间后，再决定是否继续扩更复杂的报价版本或供应商维度
+
+## 11. 建议的实现方向
+
+为了尽量少动现有结构，第一版建议优先沿用当前已有的：
+
+- `substrate` 作为板材主规则承载对象
+- `metadata` 作为板材扩展规则字段承载区
+- `material / material category` 作为花色名称池和分类来源
+
+实现方向优先考虑：
+
+- 先补齐基材库录入/展示字段
+- 再补齐花色同步逻辑
+- 再把资产族里的板材选择和自动测算接通
+
+如果现有 `substrate` 表达能力不足，再决定是否补新的接口或更新能力，但首轮应尽量避免大规模重构
+
+## 12. 验收标准
+
+本次方案实现完成后，应满足以下验收标准：
+
+1. 用户能在现有资产中心结构里管理首版板材规则
+2. 用户能看到并选择首版已确认的基材、厚度、贴面、颜色组合
+3. 选择后系统能自动带出整张价格、整张重量、每平方米价格、每平方米重量
+4. `冰川白石纹色` 等真实特殊花色会自动进入花色库
+5. 新建资产族时，可按 CAD 尺寸或手动 `长 × 宽 × 数量` 自动测算板材成本和板材重量
+6. 一个资产族能同时挂多条板材明细并自动汇总
+
+## 13. 风险与待确认
+
+当前已确认的业务口径足够支持第一版，但实现时需注意：
+
+- 现有 `asset-center` 属于共享主线区域，实现前后要尽量把改动收敛在板材相关界面和接口
+- 现有 `substrate`、`material` 的字段语义需要保持兼容，避免影响现有资产中心其他功能
+- 如果后续要引入板件级 BOM 明细或开料优化，建议在第一版稳定后单独开下一轮设计