WuYongJie af601ddb01 feat(intake): 完善 AI 白底图材质方案工作区

2026-06-17 17:35:43 +08:00

10 KiB

Raw Permalink Blame History

新平台包装底座对接说明（给同事的 Codex）

适用对象：接手「新平台包装子工作区」的 Codex。
目标：让你直接在现有后端底座上继续做包装 UI、算料和最低成本方案，不要再重定 DTO、数据表和入库规则。

当前状态：包装专项历史交接。本文仍可用于理解包装底座，但分支、主线、视觉、共享接缝和路径判断必须先看仓库根目录 AGENTS.md、docs/workflow/团队协作模式.md、docs/workflow/模块边界说明.md、docs/workflow/主线同步操作手册.md，再核对当前代码。不要把本文里的固定包装分支或旧协作口径当成当前唯一规则。

1. 先说结论

新平台包装底座这一轮已经收口到可联调状态了。

你现在不需要再做下面这些事情：

不需要再定义新的包装 DTO
不需要再决定 PreSkuPackagingPlan 长什么样
不需要再决定包装结果怎么被正式入库承接
不需要再反推规格款、BOM 或自己猜默认规格款

你现在只需要在现有正式结构上继续做：

包装子工作区 UI
包装材料 / 规格选择
自动算料
最低成本方案生成
工艺图组合占位

固定协作分支口径：

日常开发默认先同步 origin/codex/xuxiake-mainline
长期包装分支使用 codex/<负责人>-packaging
临时小任务使用 codex/<负责人>-packaging-<任务简称>
不要使用 dev 这种泛分支名
不要直接 push main

一句人话：

后端底座我已经铺好，你现在直接在这个底座上继续做包装业务层。

2. 这轮已经完成了什么

2.1 `PreSku` 已经不是模糊结果了

PreSku.variantSelection 现在已经升级成精确规格款快照，不再只是旧的 componentCodes。

当前规则已经锁死：

自动组合阶段仍然只选资产族
一旦准备落成 PreSku
如果某个已选资产族下不是「唯一一个 AVAILABLE 规格款」
就直接拦截，不允许系统偷猜默认规格款

也就是说：

你后面拿到的 PreSku，已经是可被信任的精确规格款快照

2.2 新包装正式结构已经定下来了

PreSkuPackagingPlan 现在的正式字段是：

sourceType
sourceRefId
status
boxes
costSummary
processDraft
notes

旧的：

items
resultSummary

已经不再是新平台主入口的标准。

2.3 包装接口已经可直接联调

已经准备好的接口：

`GET /api/pre-skus/[id]/packaging`

packagingPlan
packagingInput

其中：

packagingPlan 是当前已保存的包装结果
packagingInput 是服务层根据精确规格款快照派生出来的包装输入

你前端不要自己重新拼包装输入。

`PUT /api/pre-skus/[id]/packaging`

只接受新正式结构：

boxes
costSummary
processDraft
notes

如果你还按旧的 items / resultSummary 发，会被直接拦截。

2.4 正式入库已经改成消费 `boxes[]`

现在正式入库不是按旧的占位 items 生成包装成品了，而是：

每个 boxes[] 生成一个 PackagedItem

并且 SKU attributes 里已经会保留：

preSkuId
skuName
variantSelectionSummary
packagingSummary

所以你后面只要把包装结果填对，入库链会继续承接。

2.5 包装材料读取入口已经补好

你后面做包装材料选择时，直接用这两个接口：

GET /api/asset-center/families?type=PACKAGING&status=AVAILABLE
GET /api/asset-center/variants?familyId=...&status=AVAILABLE

也就是说：

包装材料已经按资产中心正式资产来读
不需要你再自己发明一套包装材料假数据结构

3. 你现在应该从哪里开始看

先按这个顺序读代码，不要全仓库乱翻。

第 1 组：先看新底座

src/server/services/draft-group.service.ts
src/server/services/draft-group.service.types.ts
src/server/services/intake.service.ts
src/server/repositories/draft-group.repository.ts
prisma/schema.prisma

第 2 组：再看接口

src/app/api/pre-skus/[id]/packaging/route.ts
src/app/api/platform/schemas.ts
src/app/api/asset-center/families/route.ts
src/app/api/asset-center/variants/route.ts

第 3 组：最后看当前前端接法

src/app/draft-groups/[id]/DraftGroupDetailClient.tsx
src/lib/open-product/platform-api.ts

注意：

这份前端接法只是“最小联通版本”
不是最终包装工作区 UI
src/app/draft-groups/[id]/DraftGroupDetailClient.tsx 当前的包装区只是主线占位入口，用来验证 PreSkuPackagingPlan 能读、能写、能被正式入库承接
不要把这个占位区当成最终包装系统，然后顺手重写 DraftGroup / Intake / schema.prisma 共享契约

你后续可以重做包装子工作区，但不要改坏底层契约。

4. 新正式结构怎么理解

4.1 `variantSelection`

结构分成两块：

slots
hardwareSelections

你可以把它理解成：

slots 是真正装进这条准 SKU 的规格款板件 / 组件
hardwareSelections 是当前已确认的五金规格款与数量

这份快照已经能直接支撑：

包装输入
展示摘要
正式入库固化

4.2 `packagingInput`

这是给包装模块直接消费的输入，不需要前端自己猜。

核心意义：

这条 PreSku 到底有哪些要装箱的业务对象
每个对象的数量、重量、成本、尺寸是什么

你可以直接拿它做：

默认箱内项
估算基础重量
估算基础成本
生成包装方案初稿

4.3 `boxes[]`

这是包装结果的真相对象。

每个箱至少表达：

箱号
名称
外箱尺寸
箱内装载项
包装材料
预估重量
预估成本
备注

一句话：

以后你所有包装结果都应该往 boxes[] 里落，不要再想旧 items。

4.4 `costSummary`

这是整条包装方案的摘要，不是单箱明细。

当前至少支持：

materialCost
totalCost
totalWeightKg
totalVolumeM3
notes

后面你做最低成本方案时，直接往这层汇总即可。

4.5 `processDraft`

这层现在只是预留，不需要你这一轮做真实工艺图生成。

但要求是：

保留这个字段
包装 UI 里给工艺图组合留位置
不要把它删掉

5. 你现在只负责什么

你现在只负责下面这些：

包装子工作区 UI
包装材料与规格选择
成本计算
自动生成最低成本方案
工艺图组合占位

6. 你不要碰什么

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

PreSku 唯一规格款判定规则
DraftGroup 主链规则
正式入库规则
旧产品级 PackagingPlan 重构
自动组合主链
资产中心主链
CAD 导入主链
仓库主链

这些共享接缝如果确实必须改，先停下来和主线负责人确认：

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

如果你发现自己已经开始改这些，就说明越界了。

7. 建议你的实现顺序

第 1 步：先把包装 UI 接到新接口

目标：

草稿组详情页里，按 PreSku 切换包装结果
读取 GET /api/pre-skus/[id]/packaging
保存到 PUT /api/pre-skus/[id]/packaging

第 2 步：接包装材料资产选择

目标：

用资产中心接口读 PACKAGING 资产族和规格款
让用户能选择包装材料规格款

第 3 步：补成本与自动方案

目标：

先根据 packagingInput + 材料规格 做基础算料
再把结果汇总到 boxes + costSummary
再做最低成本方案

第 4 步：补工艺图组合占位

目标：

只留位置和结构
不做完整实现

8. 最低验收标准

你提测前至少自己确认：

不同 PreSku 的包装结果不会串数据
包装结果保存后，刷新还能回来
包装材料规格款能从资产中心读出来
保存结果里已经有 boxes[]
costSummary 会跟着一起保存
processDraft 还保留着
正式入库页不因为你的改动报错

9. 直接发给同事 Codex 的提示词

下面这段你可以直接复制给 Codex：

请接手当前仓库里的“新平台包装子工作区”任务，不要扩范围。

当前固定工作分支：
- 长期分支：`codex/<负责人>-packaging`
- 临时任务分支：`codex/<负责人>-packaging-<任务简称>`
- 不要继续使用 `codex/xuxiake-dev`
- 不要使用 `feature/packaging`

这轮后端底座已经完成，你不要再重定 DTO、Prisma 结构或入库承接规则。你要基于现有正式结构继续做包装业务层。

你现在只负责：
- 包装子工作区 UI
- 包装材料 / 规格选择
- 成本计算
- 自动生成最低成本方案
- 工艺图组合占位

不要改这些：
- PreSku 唯一规格款判定规则
- DraftGroup 主链规则
- 正式入库规则
- 旧产品级 PackagingPlan 重构
- 自动组合主链
- 资产中心主链
- CAD 导入主链
- 仓库主链

先看这些文件：
- src/server/services/draft-group.service.ts
- src/server/services/draft-group.service.types.ts
- src/server/services/intake.service.ts
- src/server/repositories/draft-group.repository.ts
- prisma/schema.prisma
- src/app/api/pre-skus/[id]/packaging/route.ts
- src/app/api/platform/schemas.ts
- src/app/api/asset-center/families/route.ts
- src/app/api/asset-center/variants/route.ts
- src/app/draft-groups/[id]/DraftGroupDetailClient.tsx
- src/lib/open-product/platform-api.ts

当前正式契约：
- GET /api/pre-skus/[id]/packaging 返回 packagingPlan + packagingInput
- PUT /api/pre-skus/[id]/packaging 只接受 boxes / costSummary / processDraft / notes
- PreSku.variantSelection 已是精确规格款快照
- 正式入库已按 boxes[] 生成 PackagedItem
- 包装材料从 asset-center 的 PACKAGING + AVAILABLE 接口读取

要求：
- 先说明准备改什么
- 改动保持聚焦
- 不要把旧结构 items / resultSummary 当成新入口标准
- 改完至少跑 npm run type-check
- 按需跑相关测试
- 能跑就跑 npm run build

最后请按下面格式回报：
1. 现在你要做什么
2. 是否完成
3. 还有没有风险

10. 一句话总结

你现在不是来搭包装底座的。

你现在是在已经定好的新底座上，继续把包装工作区、包装材料选择和最低成本方案做出来。

10 KiB Raw Permalink Blame History Unescape Escape