12 KiB
12 KiB
包装方案增强操作手册（非程序员版，新平台一期）
1. 先看结论
你这次要做的事情只有一条：
- 把「包装方案」接到新平台的
草稿组 -> 准 SKU这一层，并保留旧产品详情页包装能力不坏。
你不用先理解整个系统。
你只要记住下面这句话：
- 新入口看
草稿组详情页 - 旧入口只做兼容
2. 你这次不要碰什么
这次不要碰下面这些内容：
- 自动组合主链
- 资产中心主链
- CAD 导入
- 装配编辑器
- 仓库系统
- 库存流水
- 仓位策略
如果你发现自己已经开始改这些内容，请先停下来。
3. 你电脑里要准备什么
请先确认电脑里至少有这些：
- Node.js
- npm
- Docker Desktop
项目根目录指的是：
- 当前这个仓库最里面、真正有
package.json和prisma/的那一层目录
你不用假设它一定在某个固定磁盘路径里。
只要记住：
- 所有命令都在“当前仓库根目录”执行
- 不要在外层父目录执行前端命令
4. 第一次打开项目怎么做
第 1 步：打开终端
可以是：
- PowerShell
- Windows Terminal
- Codex 内置终端
第 2 步：进入项目根目录
不要复制固定磁盘路径。
正确做法是：
- 先找到当前仓库根目录
- 再进入这个目录
如果你已经在 Codex 里打开了正确仓库，这一步通常可以跳过。
第 3 步：看一下当前状态
git status
如果你看到很多不是你改的文件，不要慌。
原则只有两个：
- 不删除看不懂的改动
- 不回退不是你负责的内容
第 4 步：拉最新代码
git pull origin main
第 5 步：切到分配给你的分支
这里不要死记固定分支名。
正确做法是：
- 如果仓库里已经告诉你分支名，就切到那个分支
- 如果没有，就先问主线同事
常见命令还是：
git fetch origin
git checkout <分支名>
5. 本地环境怎么启动
方案 A：直接启动
npm install
npm run dev
启动后，开发地址以终端输出为准。
通常会是：
http://localhost:<端口>
但不要把 3000 当成固定值。
方案 B：如果数据库连不上
先打开 Docker Desktop，然后执行：
docker-compose -f docker-compose.dev.yml up -d
如果你改了 schema.prisma，还要执行：
npm run prisma:generate
npm run prisma:push
npm run prisma:push 只允许本地开发库使用。生产或准生产数据库必须走 npx prisma migrate deploy，并在迁移后执行 npm run db:verify-master-data:all:strict。
方案 C：如果本地几乎没有演示数据
可以先试：
npm run demo:setup
这一步的目的是：
- 让你本地先有可点的基础数据
- 不然你后面很难进入
草稿组详情页
6. 先打开哪些页面
这次你最重要的不是旧产品详情页，而是新平台主链页面。
6.1 首页
地址：
- 当前开发地址的
/
现在首页是流程导航页，不是旧产品列表页。
6.2 草稿组列表
地址：
- 当前开发地址的
/draft-groups
你要先从这里找到一条有准 SKU 的草稿组。
6.3 草稿组详情页
地址格式：
- 当前开发地址的
/draft-groups/<草稿组ID>
这就是你这次主要开发和验证的页面。
包装相关内容现在挂在这里。
6.4 正式入库页
地址：
- 当前开发地址的
/intake
这页用于确认：
- 你的包装结果后面能不能继续承接
6.5 旧产品详情页
地址格式：
- 当前开发地址的
/products/<产品ID>
这页现在不是主入口。
但你最后仍然要回来看一眼，确认旧包装能力没被你改坏。
7. 你应该先看哪些代码文件
不要一上来全仓库搜索。
按这个顺序看就够了。
第 1 组：先看新平台入口
src/app/draft-groups/[id]/page.tsxsrc/app/draft-groups/[id]/DraftGroupDetailClient.tsxsrc/app/api/pre-skus/[id]/packaging/route.tssrc/server/services/draft-group.service.tssrc/server/services/draft-group.service.types.tssrc/server/services/intake.service.ts
第 2 组：再看旧链兼容
src/components/packaging/PackagingEditor.tsxsrc/app/products/[id]/ProductDetailClient.workspace.tsxsrc/app/api/products/[id]/packaging/route.tssrc/server/services/packaging.service.ts
第 3 组：最后看数据模型
prisma/schema.prismasrc/server/repositories/draft-group.repository.tssrc/server/repositories/warehouse.repository.ts
7.1 如果你是用 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 自己继续排查，也可以追加一句：
如果当前仓库数据不够，请先说明缺什么，不要自己猜业务数据。
8. 这次你到底要改什么
你可以把这次工作拆成 4 件事。
第 1 件：包装结果按准 SKU 单独保存
现在你要保证：
- 一个草稿组里有多个准 SKU 时
- 每个准 SKU 都有自己的包装结果
- 改 A，不会影响 B
第 2 件：箱内装载项不能再只靠板件
以前更像：
panelIds: ['P001', 'P002']
这次要升级成更通用的思路：
items: [
{ itemType: 'panel', name: '左侧板', quantity: 1 },
{ itemType: 'hardware', name: '连接片', quantity: 4 }
]
简单理解就是：
- 一个箱子里，不再只记录板件
- 一个箱子里，可以记录板件、组件、五金、附件
第 3 件：包装材料和规格要能保存
后面产品同事会关心：
- 纸箱
- 泡沫
- 护角
- 珍珠棉
- 套袋
这些包装材料的规格和成本。
所以这次至少要让系统能保存：
- 用了什么材料
- 选了什么规格
- 大概多少成本
第 4 件：工艺图组合留位置
这期不要做完整工艺图系统。
你只要做到：
- 页面上给它留位置
- 数据结构里给它留位置
- 文案上明确这是预留能力
9. 推荐你怎么改
请按这个顺序来。
第 1 步：先改数据模型和类型
优先改：
prisma/schema.prismadraft-group.service.types.tspackaging.service.ts相关类型
先把这些问题想清楚：
- 包装结果挂在哪个对象上
- 箱内项是不是统一改成
items[] - 包装材料怎么保存
- 工艺图组合预留放哪里
第 2 步：再改 Service
优先看：
draft-group.service.tspackaging.service.tsintake.service.ts
你的目标是：
- 新平台能保存
- 正式入库能承接
- 旧产品详情页还能读
第 3 步：再改 API
重点看：
src/app/api/pre-skus/[id]/packaging/route.tssrc/app/api/products/[id]/packaging/route.ts
记住：
- Route 只做入口
- 不要把复杂转换逻辑堆在 Route 里
第 4 步：最后改页面
优先改：
DraftGroupDetailClient.tsxPackagingEditor.tsx
页面层这次最重要的是：
- 能切准 SKU
- 能各自保存
- 能录包装材料和规格
- 能看见工艺图组合预留位
10. 改完后你怎么自己验证
请按这个顺序来。
第 1 步：先跑类型检查
npm run type-check
第 2 步：跑你改到的测试
例如：
npm test -- src/server/services/__tests__/draft-group.service.test.ts
npm test -- src/app/api/products/[id]/packaging/route.test.ts
如果你新增了测试，也一起跑。
第 3 步：手工验证新平台主入口
打开：
- 当前开发地址的
/draft-groups
然后做下面这些动作：
- 进入一条有准 SKU 的草稿组
- 选中准 SKU A
- 改包装结果并保存
- 切到准 SKU B
- 确认 A 的数据没有串到 B
- 给 B 也保存一套不同的包装结果
- 刷新页面
- 再进来确认 A 和 B 各自的数据还在
- 看工艺图组合预留位是否还在
第 4 步：验证正式入库承接
打开：
- 当前开发地址的
/intake
确认：
- 你保存过的包装结果，后面流程还能继续承接
第 5 步：回头看旧产品详情页
打开任意旧产品详情页，确认：
- 包装方案页还能打开
- 旧数据不会直接报错
- 旧链基本交互没坏
11. 常见问题怎么处理
情况 1：数据库连不上
报错类似：
Can't reach database server at 127.0.0.1:5432
先执行：
docker-compose -f docker-compose.dev.yml up -d
情况 2：改了 Prisma 但页面还是报字段错误
执行：
npm run prisma:generate
npm run prisma:push
这里的 npm run prisma:push 仍然只用于本地开发库；如果你面对的是服务器、生产库或准生产库，停下来改用迁移流程，不要直接推 schema。
然后重启 npm run dev。
情况 3：页面没变化
按顺序做：
- 刷新浏览器
- 重启
npm run dev - 删除
.next后再重启
情况 4：你本地根本没有草稿组数据
先试：
npm run demo:setup
如果还没有，就找主线同事要一条现成的草稿组数据，不要自己硬猜。
情况 5：你不知道当前开发地址是什么
不要死记 http://localhost:<端口>。
正确做法是：
- 以
npm run dev启动后的终端输出为准 - 如果 Codex 已经帮你启动了服务，就看它回报的地址
12. 交付前请逐条打勾
- 我这次主改的是
草稿组 -> 准 SKU包装结果 - 我没有把旧产品详情页包装能力改坏
- 我没有碰自动组合主链
- 我没有碰 CAD 导入主链
- 我没有碰仓库主链
- 我跑了
npm run type-check - 我跑了我改到的测试
- 我自己手工验证了准 SKU A / B 分开保存
- 我看过正式入库承接有没有坏
- 我给工艺图组合留了位置或接口
13. 交付时怎么说
不要只发一句「改好了」。
请直接照下面这个模板回报：
这次我只处理了新平台包装子工作区增强、旧包装链兼容、工艺图组合预留，
没有碰自动组合主链、仓库主链、CAD 导入主链。
已修改：
- 列出你实际改过的文件
本次结果：
- 包装结果已按 PreSku 独立保存
- 箱内项已升级为 items
- 包装材料 / 规格选择可保存
- 工艺图组合已预留位置
- 旧产品详情页包装能力仍可打开
验证：
- 写你实际跑过的命令
- 写你做过的手工验证
未处理：
- 写你明确没做的内容
这是自审，不是独立复审。
规范审查结论：passed / passed with warnings / rejected
14. 最后一句提醒
你这次不是在修一个旧页面。
你这次是在帮新平台把包装这条链真正接上，同时保证旧链不掉。