furniture-3d-system-Wu/furniture-3d-system/docs/架构设计/新平台一期-资产中心与自动拼装实施计划-20260331.md

新平台一期资产中心与自动拼装实施计划

面向 AI 代理的工作者： 推荐使用 subagent-driven-development 或 executing-plans 逐任务执行此计划。步骤使用复选框（- [ ]）语法跟踪进度。
适用范围： furniture-3d-system/

目标： 把新平台一期最关键的两块地基一次打稳：资产中心准入体系 与 自动静态拼装引擎，让后续自动组合、包装、成品展示、正式入库、轻仓库都建立在可追溯且可信的资产数据之上。

架构： 新平台主链固定为 资产中心 -> 自动组合 -> 自动静态拼装 -> 草稿组 / PreSku -> 包装 -> 成品展示 -> 正式入库 -> 轻仓库。旧 CAD -> 装配步骤 链保留为历史兼容链，不再作为新主链。自动拼装采用 模板主控 + 槽位制 + 资产能力声明 + 孔位语义 + 五金兼容规则 的组合模型，系统负责生成正确的静态成品，不负责自动决定安装顺序。

技术栈： Next.js 16、Prisma、PostgreSQL、现有 AssetFamily / AssetVariant / SeriesTemplate / DraftGroup / PreSku 主链。

---

一、已锁定的业务决策

1. 资产中心

• 资产对象分为两层：资产族 与 规格款。
• 资产族与规格款都要走状态流转，但规格款校验更严格。
• 统一状态机固定为：
  • 草稿
  • 待确认
  • 已驳回
  • 可用
  • 停用
• 可用 不允许系统自动放行，必须满足：
  • 系统校验通过
  • 另一位有权限的人确认
• 录入人不能自己确认可用。
• 资产被驳回后，在原记录上继续修改，再次提审。
• 规格款进入 可用 后，如果以下关键信息发生变更，必须新建规格款，不能覆盖原记录：
  • 尺寸
  • 基材
  • 饰面 / 花色
  • 模型文件
  • 挂载点
  • 拼装基准
  • 兼容关系
• 旧规格款必须继续保留，用于保证已生成 PreSku、包装结果、正式 SKU 的引用稳定。
• 编码规则固定为：系统生成默认编码，允许人工修改。
• 统一责任字段固定为：
  • 录入人
  • 设计师 / 责任人
  • 开发日期
  • 确认人
  • 最后修改人
• 统一供应链 / 成本字段固定为：
  • 供应商
  • 成本
  • 重量
• 统一检索字段固定为：
  • 适用品类
  • 适用系列
  • 标签 / 关键词
  • 状态
• 颜色不作为统一底线字段，只在需要颜色语义的资产类型里维护。

2. 自动拼装

• 用户不做手工拖拽拼装，只在列表里选资产，由系统自动拼成完整产品。
• 自动拼装只负责生成正确的静态 3D 成品，不负责自动决定安装顺序。
• 自动拼装主线固定为：槽位制。
• 槽位命名采用业务命名，不采用纯几何编号。
• 模板定义槽位结构，资产声明可进入哪些槽位。
• 槽位负责业务语义，模板装配规则负责最终 3D 空间位置。
• 资产是否能进入某个槽位，不能靠系统猜，必须由资产资料明确声明。
• 孔位固定分两层：
  • 结构孔位
  • 业务孔位语义
• 孔位语义由资产族给默认值，规格款可覆盖，最终以规格款为准。
• 五金匹配必须同时看：
  • 槽位
  • 孔位语义
  • 资产兼容清单
  • 模板规则
• 自动拼装结果固定只有三种：
  • 可自动拼装
  • 可拼装但有警告
  • 不可拼装，必须人工处理

3. 单板桌一期模板

• 一期先只做 单板桌。
• 桌面板 为固定必选槽位。
• 四条腿在 SKU / 准 SKU 层必须拆成独立腿位：
  • 前左腿
  • 前右腿
  • 后左腿
  • 后右腿
• 资产库里可以仍然是同一个腿资产，但落到 PreSku 时要按 4 个位置角色分别展开。
• 四个腿位允许不同，但要支持一键同步。
• 连接件采用“系统推荐 + 人工覆盖”。

---

二、一期推荐技术策略

1. 真实列与结构化 JSON 的边界

本期不建议把新平台一次性拆成大量细表。推荐策略如下：

• 强流程、强审计、强检索字段用真实列。
  • 例如：状态、提审人、确认人、驳回原因、责任人、开发日期、最后修改人。
• 高复杂度、仍在演化的装配语义用版本化结构化 JSON。
  • 例如：槽位能力、装配基准、孔位语义、五金兼容规则、模板装配规则。
• 高频引用对象继续保持主表稳定。
  • 例如：AssetFamily、AssetVariant、SeriesTemplate、DraftGroup、PreSku。

2. 执行前置条件与下游约束

• 执行前先补环境地基。
  • 先应用当前仓库里已经存在的开放平台相关 migration，再开始本计划开发与联调。
  • 如果数据库还停留在旧状态，资产中心、自动组合、草稿组、包装、入库这条新主链无法可靠验证。
• 本计划是在现有一期代码骨架上收敛，不另起第二套主链。
  • 当前代码里已经有 AssetFamily / AssetVariant / SeriesTemplate / DraftGroup / PreSku 的基础对象。
  • 本计划的目标是把这些对象从“一期单板桌可跑通雏形”提升为“可持续扩展的正式契约”，不是平行再造一套新模型。
• 槽位身份不能在下游链路中丢失。
  • 只要某个部件在模板层有明确槽位身份，例如 frontLeftLeg / frontRightLeg / rearLeftLeg / rearRightLeg，则在 PreSku 快照、包装输入、包装结果、资料输出中都要保留结构化 slotKey / role。
  • 不能把这类信息只降级写进 notes，也不能简单合并成 quantity: 4 后丢失来源位置。
• 自动拼装与安装顺序继续严格分层。
  • 自动拼装负责生成静态正确成品。
  • 安装顺序、安装步骤演示仍由产品人员在后续步骤链中主控，不在本计划内由系统自动决定。

3. 推荐的数据真相位置

主题	真相位置	说明
资产审批状态	AssetFamily / AssetVariant 真字段	要支持筛选、权限、留痕
统一底线字段	AssetFamily / AssetVariant 真字段 + businessData	先放核心真字段，不足部分补在结构化业务 JSON
模板槽位定义	SeriesTemplate.slotSchema	先用结构化 JSON 契约，不急着新建大量表
模板装配规则	SeriesTemplate.previewRule / recommendationRule	一期先在模板 JSON 内稳定契约
资产槽位能力	AssetFamily.metadata 或专用 compatibilityRules 契约	资产族默认能力声明
规格款装配覆盖	AssetVariant.assemblyBasis / compatibilityRules	规格款覆盖默认语义
孔位语义	AssetVariant.businessData 中的结构化块	资产族默认 + 规格款覆盖
自动拼装结果	PreSku.variantSelection / previewNodes / bomPreview / notes	包装、展示、入库继续消费

---

三、文件边界与职责

1. 需要新增或重构的重点文件

• 新增：src/lib/open-product/asset-review.ts
  • 负责统一状态机、提审、确认、驳回规则。
• 新增：src/lib/open-product/asset-validation.ts
  • 负责统一底线校验与按类型专属校验。
• 新增：src/lib/open-product/assembly-contract.ts
  • 定义模板槽位、资产能力、孔位语义、五金兼容规则的结构化契约。
• 新增：src/lib/open-product/assembly-engine.ts
  • 负责根据模板、资产能力、规格款覆盖生成静态拼装结果。
• 新增：src/lib/open-product/__tests__/asset-validation.test.ts
• 新增：src/lib/open-product/__tests__/assembly-engine.test.ts
• 新增：src/server/services/__tests__/asset-review.service.test.ts

2. 需要修改的现有文件

• 修改：prisma/schema.prisma
  • 补资产审批状态与审批留痕字段。
  • 补模板 / 规格款所需的结构化字段契约注释。
• 修改：src/server/services/asset-center.service.types.ts
  • 扩展统一底线字段、审批字段、类型专属字段。
• 修改：src/server/services/asset-center.service.ts
  • 引入统一校验、提审、确认、驳回逻辑。
• 修改：src/lib/open-product/asset-identity.ts
  • 从“只校验模型 / 挂载点 / 尺寸”升级成“统一底线 + 类型专属”入口。
• 修改：src/app/api/platform/schemas.ts
  • 扩展资产族 / 规格款提审与审批相关 schema。
• 修改：src/app/api/asset-center/families/route.ts
• 修改：src/app/api/asset-center/variants/route.ts
  • 新增提审、确认、驳回接口，或扩展现有 route。
• 修改：src/app/asset-center/AssetCenterClient.tsx
  • 从轻表单升级为“录入 -> 校验 -> 提审 -> 确认”工作流。
• 修改：src/server/services/series-template.service.ts
  • 把 single-board-desk 模板升级成正式槽位契约。
• 修改：src/server/services/combination.service.ts
  • 从“桌面族 + 腿组族 + 连接件族”升级为“模板槽位驱动候选生成”。
• 修改：src/lib/open-product/single-board-desk.ts
  • 逐步收敛到调用通用装配引擎，而不是继续堆单品类特例。
• 修改：src/server/services/draft-group.service.ts
  • 让 PreSku 真正承接静态拼装引擎结果与告警分级。

---

四、统一底线与类型专属字段设计

任务 1：资产审批状态机与留痕

文件：

• 修改：prisma/schema.prisma

• 修改：src/server/services/asset-center.service.types.ts

• 修改：src/server/services/asset-center.service.ts

• 新增：src/lib/open-product/asset-review.ts

• 测试：src/server/services/__tests__/asset-review.service.test.ts

• 定义资产族 / 规格款的统一审批状态与流转规则。

• 给资产族 / 规格款补齐提审、驳回、确认、最后修改等留痕字段。

• 明确“录入人不能自己确认”的服务层权限边界。

• 明确驳回后原记录继续修改，再次提审。

• 增加状态流转测试：

  • 录入人提审成功
  • 自己确认被拒绝
  • 他人确认通过
  • 驳回成功
  • 驳回后再次提审成功

任务 2：统一底线校验引擎

文件：

• 新增：src/lib/open-product/asset-validation.ts

• 修改：src/lib/open-product/asset-identity.ts

• 修改：src/server/services/asset-center.service.ts

• 测试：src/lib/open-product/__tests__/asset-validation.test.ts

• 抽离统一底线校验：

  • 编码
  • 名称
  • 责任链
  • 供应商
  • 成本
  • 重量
  • 模型
  • 尺寸
  • 挂载点
  • 适用品类
  • 适用系列
  • 标签

• 抽离按类型专属校验入口。

• 统一约定：只有当状态准备进入 待确认 或 可用 时，才执行强校验。

• 为每类资产补齐失败测试与通过测试。

任务 3：四类资产专属清单

文件：

• 修改：src/server/services/asset-center.service.types.ts

• 修改：src/app/api/platform/schemas.ts

• 修改：src/app/asset-center/AssetCenterClient.tsx

• 测试：src/lib/open-product/__tests__/asset-validation.test.ts

• 给板材补齐专属字段契约：

  • 基材
  • 饰面 / 花色
  • 长宽厚
  • 纹理方向
  • 边处理
  • 拼装基准
  • 孔位语义模板
  • 工艺资料 / 图纸

• 给组件补齐专属字段契约：

  • 可进入槽位
  • 依附父件规则
  • 配套件规则
  • 兼容五金规则

• 给五金补齐专属字段契约：

  • 安装方向
  • 适配孔位语义
  • 配件关系
  • 数量限制

• 给包装材料补齐专属字段契约：

  • 规格
  • 承重 / 保护等级
  • 适用对象

• 资产中心表单按类型切换专属录入区，不再只有一套轻表单。

---

五、自动拼装模型设计

任务 4：模板槽位契约

文件：

• 新增：src/lib/open-product/assembly-contract.ts

• 修改：src/server/services/series-template.service.ts

• 修改：src/server/services/combination.service.ts

• 测试：src/lib/open-product/__tests__/assembly-engine.test.ts

• 定义 SlotDefinition 契约，至少包含：

  • slotKey
  • label
  • slotType
  • required
  • allowDisable
  • minCount
  • maxCount
  • parentSlotKey
  • defaultRole
  • acceptedAssetTypes

• 定义 SlotPlacementRule 契约，至少包含：

  • 相对父槽位或父挂载点的偏移
  • 默认朝向
  • 镜像 / 复制关系

• 把 single-board-desk 模板升级成正式槽位结构：

  • desktop
  • frontLeftLeg
  • frontRightLeg
  • rearLeftLeg
  • rearRightLeg
  • connectorGroup

• 保留前端“一键同步四条腿”的交互能力，但后端存储必须是 4 个独立腿位。

任务 5：资产能力声明与孔位语义

文件：

• 新增：src/lib/open-product/assembly-contract.ts

• 修改：src/server/services/asset-center.service.types.ts

• 修改：src/server/services/asset-center.service.ts

• 测试：src/lib/open-product/__tests__/assembly-engine.test.ts

• 定义资产族默认能力契约：

  • 可进入哪些槽位
  • 默认角色
  • 默认朝向
  • 默认孔位语义
  • 默认五金兼容规则

• 定义规格款覆盖契约：

  • 具体挂载点
  • 具体装配基准
  • 孔位语义覆盖
  • 五金兼容覆盖

• 把孔位语义拆成两层：

  • 结构孔位
  • 业务孔位语义

• 明确“规格款优先覆盖资产族默认值”的合并顺序。

任务 6：自动静态拼装引擎

文件：

• 新增：src/lib/open-product/assembly-engine.ts

• 修改：src/server/services/combination.service.ts

• 修改：src/server/services/draft-group.service.ts

• 修改：src/lib/open-product/single-board-desk.ts

• 测试：src/lib/open-product/__tests__/assembly-engine.test.ts

• 测试：src/server/services/__tests__/draft-group.service.test.ts

• 把自动拼装输入固定为：

  • 模板槽位定义
  • 模板装配规则
  • 用户选择的资产族 / 规格款
  • 资产能力声明
  • 孔位语义
  • 五金兼容规则

• 引擎输出固定为：

  • resultStatus
  • warnings
  • selectedSlots
  • selectedHardware
  • previewNodes
  • bom
  • componentCodes

• 结果状态严格限定为：

  • ASSEMBLABLE
  • ASSEMBLABLE_WITH_WARNINGS
  • BLOCKED

• 明确“失败不生成半成品”的规则。

• PreSku 继续作为真相对象，承接引擎快照。

任务 7：五金匹配与连接件推荐

文件：

• 修改：src/lib/open-product/assembly-engine.ts

• 修改：src/server/services/draft-group.service.ts

• 测试：src/lib/open-product/__tests__/assembly-engine.test.ts

• 五金推荐不再只靠孔径或资产类型。

• 推荐时同时判断：

  • 当前槽位
  • 当前规格款孔位语义
  • 资产兼容清单
  • 模板规则

• 保留“系统推荐 + 人工覆盖”边界。

• 支持配套件关系，例如主连接件自动带出配套小五金。

---

六、前端工作流设计

任务 8：资产中心工作流升级

文件：

• 修改：src/app/asset-center/AssetCenterClient.tsx

• 可拆分：src/components/platform/asset-center/*

• 测试：后续页面行为测试

• 录入界面拆成：

  • 统一底线区
  • 类型专属区
  • 校验结果区
  • 提审 / 驳回 / 确认区

• 在 UI 中明确显示：

  • 当前状态
  • 缺失字段
  • 驳回原因
  • 谁提交、谁确认、最后谁改过

• 对 可用 规格款的关键信息改动，不再直接编辑，改为“另存为新规格款”。

任务 9：自动组合页升级

文件：

• 修改：src/app/auto-combinations/AutoCombinationsClient.tsx

• 修改：src/server/services/combination.service.ts

• 页面仍然保持“先选，再自动生成候选”的模式。

• 但候选摘要要显示清楚：

  • 哪些槽位已填
  • 四条腿是否混搭
  • 是否带推荐连接件
  • 是否有警告

• 不在候选列表阶段批量渲染 3D。

• 进入草稿组后才展示完整静态拼装结果。

---

七、实施顺序建议

第一阶段：把资产中心准入体系打牢

• 完成资产审批状态机
• 完成统一底线校验
• 完成四类资产专属字段契约
• 完成资产中心 UI 流程升级

第二阶段：把单板桌模板与自动拼装打通

• 完成 single-board-desk 正式槽位契约
• 完成资产能力声明
• 完成孔位语义默认 / 覆盖体系
• 完成静态拼装引擎
• 完成 PreSku 承接

第三阶段：把五金、包装、入库对齐

• 完成五金推荐与覆盖
• 完成包装输入完全消费装配快照
• 完成正式入库对新装配结果的承接
• 完成轻仓库读取正式 SKU 与包装成品

---

八、测试与验收

1. 资产中心验收

• 资产族与规格款能正确走完 草稿 -> 待确认 -> 已驳回 -> 可用 -> 停用
• 录入人不能自己确认
• 缺少统一底线字段时不能提审
• 缺少类型专属字段时不能进入可用
• 可用规格款修改关键信息时，会生成新规格款，不覆盖旧数据

2. 自动拼装验收

• 用户在自动组合页面只做选择，不做手工拼装
• 系统能自动生成拼好的静态产品
• 单板桌四个腿位能独立展开并支持混搭
• 五金推荐不会只靠孔径猜
• 失败时不会生成半成品

3. 下游链路验收

• PreSku 能承接静态拼装结果
• 包装接口能读取完整装配快照
• 正式入库能继续消费 PreSku
• 轻仓库能读取正式 SKU 与包装成品结果

---

九、重要假设

• 一期暂不把模板槽位、孔位语义、五金兼容全部拆成独立细表，优先采用“主表稳定 + 结构化 JSON 契约”。
• 一期先只把 单板桌 做透，不在同一轮并行扩茶几、边几等复杂模板。
• 一期自动拼装只做静态正确装配，不重构完整装配动画。
• 供应商本期先以结构化字段存储，不新建独立供应商主数据域。
• 后续如果包装算法或仓库策略需要更强约束，再基于这套真相模型继续拆细。