WuYongJie/furniture-3d-system-Wu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
furniture-3d-system-Wu/furniture-3d-system/docs/workflow/模块边界说明.md

8.8 KiB
Raw Blame History

模块边界说明

目标：让人和 AI 在开工前先知道“哪里是新平台主链，哪里是旧兼容链，哪里不能乱碰”。

配套入口：

  • 先读 docs/workflow/团队协作模式.md，确认你属于哪个工作域、该用什么分支名
  • 再读 docs/workflow/主线同步操作手册.md，确认你当前分支该用 merge main 还是 rebase main
  • 这份文档只负责讲边界，不额外创造新的角色体系或新的协作入口
  • 这份文档只固定系统边界，不固定当前负责人；具体任务归属以当前任务单、交接摘要和已确认协作信息为准

1. 页面与入口边界

新平台主链入口

  • /：新平台首页导航
  • /asset-center：资产中心
  • /assisted-assembly：辅助装配（手动拼装工作台入口）
  • /draft-groups：草稿组列表
  • /draft-groups/[id]：草稿组详情
  • /intake：正式入库
  • /warehouse：轻仓库

旧兼容链入口

  • /products
  • /products/[id]
  • /products/[id]/assembly
  • /products/[id]/skus/[skuId]
  • /products/[id]/skus/[skuId]/assembly

不要混的原则

  • 新平台入口负责“资产准备、辅助装配、草稿组承接、入库前整理”。
  • 旧兼容链负责“历史产品、CAD 导入、板件/孔位/五金/装配步骤”。
  • 不要把旧产品详情页重新改成新平台首页。

2. 新平台主链边界

前端目录

  • src/app/page.tsx
  • src/app/asset-center
  • src/app/assisted-assembly
  • src/app/draft-groups
  • src/app/intake
  • src/app/warehouse
  • src/components/platform

API 目录

  • src/app/api/asset-center
  • src/app/api/assisted-assembly
  • src/app/api/draft-groups
  • src/app/api/intake
  • src/app/api/planning
  • src/app/api/pre-skus
  • src/app/api/series-templates
  • src/app/api/warehouse

服务与仓库

  • src/server/services/asset-center.service.ts
  • src/server/services/draft-group.service.ts
  • src/server/services/intake.service.ts
  • src/server/services/planning.service.ts
  • src/server/services/series-template.service.ts
  • src/server/services/warehouse.service.ts
  • src/server/repositories/asset-center.repository.ts
  • src/server/repositories/draft-group.repository.ts
  • src/server/repositories/planning.repository.ts
  • src/server/repositories/series-template.repository.ts
  • src/server/repositories/warehouse.repository.ts

纯规则与类型

  • src/lib/open-product
  • src/lib/planning

这里的业务真相是什么

  • 资产族：AssetFamily
  • 规格款：AssetVariant
  • 草稿组：DraftGroup
  • 准 SKU：PreSku
  • 入库结果：正式 Product / SKU

不要做的事

  • 不直接从辅助装配跳过草稿组生成正式产品。
  • 不把历史 auto-combinations 旧链重新带回当前主线。
  • 不把旧 Product / SKU 当作新平台组合阶段的数据真相。
  • 不把包装做成绕过草稿组的独立系统。

3. 包装与仓库协作边界

当前包装与仓库主要入口分四条

  • 轻仓库页面：src/app/warehouse
  • 轻仓库接口：src/app/api/warehouse
  • 新平台承接口：src/app/api/pre-skus/[id]/packaging/route.ts
  • 旧正式产品口：src/app/api/products/[id]/packaging

主要服务与仓库

  • src/server/services/warehouse.service.ts
  • src/server/repositories/warehouse.repository.ts
  • src/server/services/packaging.service.ts
  • src/server/repositories/packaging.repository.ts

当前约定

  • 包装结果最终按单个 PreSku 保存。
  • 正式产品包装链保留，作为兼容与发布后使用。
  • 轻仓库工作区可以独立协作推进，但轻仓库承接的正式 Product / SKU 仍然属于主线真相，不在仓库侧重复造数。
  • 工艺图组合本期只预留接口，不在主线里单独展开。
  • 草稿组详情页里的包装区只负责主线最小联通版占位，不是最终包装工作区。
  • 轻仓库可以增强包装成品、库存、库位和展示交互，但不能绕过正式入库单独制造主链结果。

包装/仓库线可读但不默认直改的共享接缝

  • src/server/services/draft-group.service.ts
  • src/server/repositories/draft-group.repository.ts
  • src/server/services/intake.service.ts
  • src/app/intake
  • prisma/schema.prisma
  • src/app/draft-groups/[id]

这些文件不是包装/仓库线的默认自由修改区。 如果任务必须改这里，先在任务单里写清原因、影响范围，再由主线负责人确认后再动。

白话理解：

  • 可以看，可以评估，可以提出接缝需求
  • 不能在没有对齐的情况下直接开改
  • 特别是 draft-group、intake、schema.prisma 这几处，本阶段只允许做边界说明，不允许顺手把实现也改掉
  • 如果只是为了补包装 UI、材料选择器、最低成本方案，或补轻仓库展示与交互，不应默认落在这些共享接缝里完成
  • 主线收口人检查同事分支时，如果这些共享接缝被改了，默认不要直接整支 merge；优先确认是否该 cherry-pick 或手工整合

包装与仓库负责人不要乱碰的地方

  • 辅助装配主链规则（含手动拼装工作台保存口径）
  • 草稿组转正式 SKU 的规则
  • 正式入库的核心落库规则
  • 旧 CAD 的板件/孔位/五金推导链

4. 旧 CAD 兼容链边界

页面目录

  • src/app/products/[id]
  • src/app/products/[id]/assembly
  • src/app/products/[id]/skus/[skuId]
  • src/app/products/[id]/skus/[skuId]/assembly
  • src/components/assembly
  • src/components/3d

API 目录

  • src/app/api/products/[id]/assembly
  • src/app/api/products/[id]/panels
  • src/app/api/products/[id]/holes
  • src/app/api/products/[id]/import-hardware
  • src/app/api/holes
  • src/app/api/hardware
  • src/app/api/product-hardware

服务与库

  • src/server/services/assembly.service.ts
  • src/server/services/panel.service.ts
  • src/server/services/hole.service.ts
  • src/server/services/hardware.service.ts
  • src/server/services/sku-cad-import.helper.ts
  • src/server/repositories/panel.repository.ts
  • src/server/repositories/hole.repository.ts
  • src/server/repositories/hardware.repository.ts
  • src/server/repositories/product-hardware.repository.ts

纯规则与共享链路

  • src/lib/assembly-generator.ts
  • src/lib/panel-assembly-semantic.ts
  • src/lib/sku-cad-data.ts
  • src/lib/3d/engine.ts

当前约定

  • 装配语义是旧链增强能力，不是新平台主数据源。
  • 旧链可以继续生成安装步骤和预览，但不要反向主导新平台资产模型。

5. 共享层边界

所有人都可能会碰到，但不要随手改

  • prisma/schema.prisma
  • prisma/migrations
  • src/server/services/index.ts
  • src/server/repositories/index.ts
  • src/app/layout.tsx
  • src/app/api/platform/schemas.ts

共享层边界的意思是：

  • 这些地方一改，通常会同时影响主链、包装线或兼容链
  • 所以默认先对齐影响面，再决定谁来改，不是谁先看到谁就顺手动

共享层规则

  • 任何 Prisma 模型调整，都必须带迁移。
  • 任何新接口，都要有明确输入输出 DTO。
  • 任何跨模块字段变更，都要先同步文档，再改代码。
  • 没有明确任务授权时，不要顺手扩写到 draft-group、intake、schema.prisma 这些敏感接缝实现。

6. 看到这些情况要先停一下

  • 一个任务同时改新平台主链和旧兼容链，但任务单里没写原因。
  • 包装任务直接改共享接缝文件，但没先和主线负责人对齐。
  • Route 里开始直接写 Prisma 查询。
  • 包装开始自己造一套 Product / SKU。
  • 页面样式开始绕开 src/components/platform 和既有视觉标准。
  • 改动影响命名、BOM、包装、安装步骤，但没说明数据来源。
  • 分支改动会影响 intake / warehouse / Product / SKU 承接链，但交接里没说明对正式入库或轻仓库的影响。

7. 开工前最少要看什么

做新平台主链

先看：

  • docs/workflow/团队协作模式.md
  • src/components/platform/platform-navigation.ts
  • src/lib/open-product/types.ts
  • src/lib/open-product/assembly-workspace.ts
  • src/lib/open-product/manual-assembly-launch.ts
  • src/server/services/draft-group.service.ts

做包装或仓库协作

先看：

  • docs/workflow/团队协作模式.md
  • docs/开发指南/包装方案增强/包装方案增强-同事交接说明.md
  • src/app/warehouse
  • src/app/api/warehouse
  • src/app/api/pre-skus/[id]/packaging/route.ts
  • src/server/services/packaging.service.ts
  • src/server/services/draft-group.service.ts

做旧 CAD 兼容链

先看：

  • docs/solutions/workflow-issues/CAD插件装配语义导出改造说明-20260325.md
  • src/app/products/[id]/assembly/AssemblyEditorWorkspace.tsx
  • src/components/assembly/AssemblyEditorClient.tsx
  • src/server/services/assembly.service.ts
  • src/lib/assembly-generator.ts