furniture-3d-system-Wu/docs/开发指南/包装方案增强/包装方案增强-同事交接说明.md

包装方案增强同事交接说明（新平台一期版）

1. 先说结论

这份文档是给接手「包装方案增强」任务的同事看的。

如果仓库里已经明确给了专用分支，就在那个分支上继续做。

如果分支名和这份文档不一样，以仓库当前实际分支安排为准。

你这次负责的，不再是旧口径里的「产品详情页包装小增强」，而是：

• 以新平台一期主链为准，把包装能力接到「草稿组 -> 准 SKU」这一层。
• 让每个准 SKU 都能单独保存包装结果。
• 同时保留旧产品详情页里的包装能力，不把历史链路改坏。
• 给「工艺图组合」留接口位置和页面位置，但这期不要求做完整业务实现。

一句人话总结：

• 你这次是做「新平台包装子工作区 + 旧链兼容 + 工艺图组合预留」。
• 你不是去做完整仓库系统，也不是去做整个新平台主线。

---

2. 你这次到底负责什么

2.1 你必须完成的内容

这次必须完成下面 7 件事：

1. 以 DraftGroup -> PreSku 为主入口，补强包装结果的保存和编辑能力。
2. 包装结果必须按「每个准 SKU」分别保存，不能整组共用一套。
3. 包装结果里要能表达：
   • 箱体信息
   • 箱内装载项
   • 包装材料 / 规格款选择
   • 成本相关摘要
4. 继续保留旧产品详情页里的包装方案能力，至少不要把现有查看、编辑、删除、设默认改坏。
5. 为未来挂接 DraftGroup / PreSku / Product 三种来源保留统一来源字段。
6. 为「工艺图组合」留接口位置或占位区，明确它不是本期完整实现，但后面能接上。
7. 补最小测试，至少覆盖：
   • 包装结果保存 API
   • 包装 Service
   • 关键页面回显

2.2 你这次不要做的内容

这次不要碰下面这些范围：

• 独立仓库系统
• 库存流水
• 仓位策略
• 复杂出入库
• 自动组合主链
• 资产中心主链
• 正式 Product / SKU 自动生成规则
• CAD 导入主链
• 装配编辑器主链

只要开始写到这些内容，就说明已经越界。

---

3. 现在系统的真实边界

3.1 新平台主链是什么

新平台一期主链已经固定为：

资产中心 -> 自动组合 -> 草稿组 -> 包装方案 -> 成品展示 -> 正式入库 -> 轻仓库

这里面和你直接有关的是中间这一段：

• 草稿组详情页
• 准 SKU 包装结果
• 正式入库时对包装结果的承接

3.2 旧链还在，但不是主入口

旧链里的产品详情页包装方案还在。

它的意义是：

• 兼容历史产品
• 保持现在已上线页面不坏
• 为后面正式产品域继续复用包装结果做准备

但它已经不是这次工作的主入口。

这次你做事时，默认顺序应该是：

1. 先看新平台 DraftGroup / PreSku
2. 再补旧产品详情页兼容

---

4. 你应该从哪些代码开始看

建议按这个顺序看，不要一上来全仓库乱翻。

第 1 组：先看新平台主入口

1. src/app/draft-groups/[id]/page.tsx
2. src/app/draft-groups/[id]/DraftGroupDetailClient.tsx
3. src/app/api/pre-skus/[id]/packaging/route.ts
4. src/server/services/draft-group.service.ts
5. src/server/services/draft-group.service.types.ts
6. src/server/services/intake.service.ts
7. src/app/intake/IntakeClient.tsx

这组文件决定了：

• 包装结果现在从哪里进
• 保存到哪里
• 正式入库时怎么继续用

第 2 组：再看旧链兼容

1. src/app/products/[id]/ProductDetailClient.workspace.tsx
2. src/components/packaging/PackagingEditor.tsx
3. src/app/api/products/[id]/packaging/route.ts
4. src/server/services/packaging.service.ts
5. src/server/repositories/packaging.repository.ts

这组文件决定了：

• 旧产品详情页包装能力还能不能继续正常工作

第 3 组：最后看数据模型

1. prisma/schema.prisma
2. src/server/repositories/draft-group.repository.ts
3. src/server/repositories/warehouse.repository.ts

这组文件决定了：

• PreSkuPackagingPlan
• PackagedItem
• WarehouseLocation

这些对象后面是不是能顺利串起来

---

4.1 这份文档怎么给 Codex 看

如果你本人不想自己拆任务，可以直接把下面这段话发给 Codex。

给 Codex 的任务提示词

请在当前仓库根目录内工作，不要假设固定的本地磁盘路径。

目标：
- 以新平台一期主链为准，把包装能力接到 `DraftGroup -> PreSku` 这一层
- 让每个 PreSku 单独保存包装结果
- 保留旧产品详情页包装能力不坏
- 给工艺图组合留接口位置或占位区，但本期不做完整实现

边界：
- 不要改自动组合主链
- 不要改资产中心主链
- 不要改 CAD 导入主链
- 不要顺手扩成仓库系统

优先检查这些文件：
- src/app/draft-groups/[id]/page.tsx
- src/app/draft-groups/[id]/DraftGroupDetailClient.tsx
- src/app/api/pre-skus/[id]/packaging/route.ts
- src/server/services/draft-group.service.ts
- src/server/services/draft-group.service.types.ts
- src/server/services/intake.service.ts
- src/components/packaging/PackagingEditor.tsx
- src/app/products/[id]/ProductDetailClient.workspace.tsx
- src/app/api/products/[id]/packaging/route.ts
- src/server/services/packaging.service.ts
- prisma/schema.prisma

交付要求：
- 先说明准备改什么
- 只做与包装增强直接相关的改动
- 改完跑最小必要验证
- 最后明确说：完成了什么、没完成什么、风险是什么

给 Codex 的回报格式

也可以要求 Codex 按下面格式回报：

本次只处理新平台包装子工作区增强、旧包装链兼容、工艺图组合预留。

已修改：
- 列出实际改过的文件

本次结果：
- 包装结果是否已按 PreSku 独立保存
- 箱内项是否已从 panelIds 升级为 items
- 包装材料 / 规格选择是否可保存
- 工艺图组合是否已预留位置
- 旧产品详情页包装能力是否仍可打开

验证：
- 列出实际执行过的命令
- 列出手工验证结果

风险：
- 还没做完的内容
- 仍需人工确认的内容

---

5. 你这次要把包装结果升级成什么样

5.1 粒度先锁死

这期包装结果的粒度必须锁死为：

• 一条 PreSku
• 对应一套包装结果

不能做成：

• 一个草稿组共用一套包装
• 一个正式产品共用一套包装

原因很简单：

• 同一草稿组里有多个准 SKU，它们尺寸、重量、材料都可能不同。
• 包装方案如果不按准 SKU 分开，后面成本和入库都会错。

5.2 数据表达至少要覆盖这几类信息

这次建议你按“职责”理解，不要死记字段名。

A. 包装来源信息

至少要能表达：

• 这条包装结果是从哪来的
• 当前挂的是 PreSku、DraftGroup，还是旧 Product

建议保留统一结构：

interface PackagingSourceRef {
  sourceType: 'preSku' | 'draftGroup' | 'product'
  sourceRefId: string
}

B. 箱体信息

至少要有：

• 箱号
• 长宽高
• 重量
• 备注

C. 箱内装载项

不能再只存 panelIds，必须升级成通用项结构。

建议表达成：

type PackagingItemType =
  | 'panel'
  | 'component'
  | 'hardware'
  | 'accessory'

interface PackagingBoxItem {
  itemType: PackagingItemType
  refId?: string
  refCode?: string
  name: string
  quantity: number
  notes?: string
}

D. 包装材料与规格

这块是你这次很重要的一部分。

因为后面产品同事会按：

• 纸箱
• 泡沫
• 护角
• 珍珠棉
• 套袋

这些材料去选不同规格，并比较成本。

所以包装结果里至少要能保存：

• 材料类型
• 规格款或规格编码
• 数量
• 估算成本

字段名你可以按实现调整，但这个能力不能丢。

E. 成本摘要

至少要有一层结果摘要，能给前端回显：

• 预计材料成本
• 总体积
• 总重量
• 方案备注

---

6. 工艺图组合这次怎么处理

这块不要做成完整系统，但也不要完全不管。

6.1 这次要做到什么程度

这次只要求：

1. 在包装相关工作区里，预留一个明确的位置给「工艺图组合」。
2. Service / DTO 层预留一个可以挂接结果的位置。
3. 页面上明确写清楚：
   • 这是预留能力
   • 本期不做完整实现

6.2 这次不要做到什么程度

这次不要做：

• 真正的工艺图生成引擎
• 完整工艺图管理系统
• 工艺图审批流程

一句话：

• 这次只留位置，不做整套业务。

---

7. 推荐落地顺序

请按这个顺序做，不要倒着来。

第 1 步：先改数据模型和类型

优先改：

• prisma/schema.prisma
• draft-group.service.types.ts
• packaging.service.ts 相关 DTO

先把这几个问题定下来：

1. 包装结果到底挂在哪个对象上
2. 箱内项是不是统一改成 items[]
3. 包装材料怎么表达
4. 工艺图组合预留放哪里

第 2 步：再改 Service

优先改：

• draft-group.service.ts
• packaging.service.ts
• intake.service.ts

Service 层要保证三件事：

1. 新平台能按准 SKU 保存包装结果
2. 旧链仍能读取旧包装数据
3. 正式入库时能继续承接包装结果

第 3 步：然后改 API

重点看：

• src/app/api/pre-skus/[id]/packaging/route.ts
• src/app/api/products/[id]/packaging/route.ts

要求只有一条：

• Route 只做入口，不要把复杂转换逻辑塞进去

第 4 步：最后再改页面

页面优先级是：

1. DraftGroupDetailClient.tsx
2. 旧 PackagingEditor.tsx

页面上要做到：

• 可以按准 SKU 切换包装结果
• 切不同准 SKU 时，不会串数据
• 能录入包装材料和规格选择
• 能看到工艺图组合预留位

---

8. 这次改完后，产品上应该看到什么效果

改完以后，至少应该达到下面这些效果。

8.1 新平台里

在 草稿组详情页 里：

1. 可以切换不同准 SKU
2. 每个准 SKU 都能单独编辑包装结果
3. 每个准 SKU 都能单独保存
4. 包装结果里能表达箱体、装载项、包装材料、成本摘要
5. 页面上能看到工艺图组合预留位

8.2 正式入库里

正式入库时：

1. 还能继续读取该准 SKU 的包装结果
2. 包装成品对象还能继续往后承接

8.3 旧产品详情页里

旧页面至少要做到：

1. 还能打开
2. 还能看已有包装数据
3. 不因为新结构就直接报错

---

9. 最小验收标准

你提测前，最少自己确认下面这些事。

9.1 页面验收

• 能进入 DraftGroup 详情页
• 能切换不同准 SKU
• 修改 A 准 SKU 的包装，不会影响 B 准 SKU
• 包装结果保存后，刷新还能回来
• 页面上有工艺图组合预留位

9.2 数据验收

• 包装结果按 PreSku 独立保存
• 不再只靠 panelIds
• 包装材料 / 规格选择能保存
• 来源字段能表达 preSku / draftGroup / product

9.3 回归验收

• 旧产品详情页包装能力不崩
• 正式入库流程不崩
• PackagedItem 承接不崩

---

10. 推荐你至少补的测试

最少建议覆盖下面这些测试：

• src/app/api/pre-skus/[id]/packaging/route 相关测试
• src/server/services/__tests__/draft-group.service.test.ts
• src/server/services/__tests__/packaging.service.test.ts
• src/components/packaging/__tests__/PackagingEditor.test.tsx

如果时间不够，最低底线是：

• API 测试有
• Service 测试有
• 手工验证有记录

---

11. 你交付时要怎么回报

不要只说「我改好了」。

请按这个格式回报：

这次我只处理了新平台包装子工作区增强、旧包装链兼容、工艺图组合预留，
没有碰自动组合主链、仓库主链、CAD 导入主链。

已修改：
- 列出你实际改过的文件

本次结果：
- 包装结果已按 PreSku 独立保存
- 箱内项已从 panelIds 升级为 items
- 包装材料 / 规格选择可保存
- 工艺图组合已预留接口或页面位置
- 旧产品详情页包装能力仍可打开

验证：
- 写你实际跑过的命令
- 写你实际做过的手工验证

未处理：
- 写你明确没做的内容

这是自审，不是独立复审。
规范审查结论：passed / passed with warnings / rejected

---

12. 最容易踩坑的地方

坑 1：把旧产品详情页当主入口

不要这样做。

这次主入口已经变成：

• DraftGroup -> PreSku

旧产品详情页只是兼容入口。

坑 2：把整组草稿共用一套包装

不要这样做。

包装结果必须按准 SKU 分开。

坑 3：只改页面，不改 Service

不要这样做。

真正的边界在 Service 和 DTO，不在页面表面。

坑 4：顺手做仓库系统

不要这样做。

这次的目标只是把包装结果正确承接到后面的入库和包装成品对象。

坑 5：把工艺图组合做成大需求

不要这样做。

这期只留接口和位置，不做完整实现。

---

13. 一句话总结

你这次不是做「旧包装模块小修小补」。

你这次是在把包装能力，真正挂到新平台一期主链里，并且顺手把旧链和后续工艺图位置一起收好。