admin-web/src/modules/loading-lists/AGENTS.md

Admin 装柜清单模块指引

路径基准与读取顺序

• 本文件适用于 src/modules/loading-lists/，代码路径相对本目录；应用公共规则见 ../../../AGENTS.md，页面/接口细则见 ../../../docs/business-index.md。
• 预装清单与正式装柜清单是两条链路：loading-plans 为预装，loading-lists 为装柜清单；改前先确认当前页面属于哪条。
• 后端只查 firstleg/（LoadingListService、split/ 预装、loading/）与 print/（托盘标、单据）；纯页面与文案不读后端。

页面与入口

目标	页面/路由	API 与后端
预装清单列表	pages/PreloadPlansView.vue（列表主体在 components/LoadingListsView.vue）；loading-plans	请求在 components/LoadingListsView.vue → api/platformLoadingLists.ts；firstleg/split/
预装清单详情、生命周期、真实柜号补录	pages/PreloadPlanDetailView.vue；loading-plans/:planId	/loading-plans/{planId}/lifecycle；firstleg/service/LoadingListService.java
装柜清单列表	pages/ConfirmedLoadingListsView.vue、components/LoadingListsView.vue；loading-lists	api/platformLoadingLists.ts
装柜清单详情、摘要、明细、历史与单据打印	pages/ConfirmedLoadingListDetailView.vue、components/LoadingListDetailDrawer.vue；loading-lists/:planId	单据打印走 printLoadingList.ts（详情页带 ?print=1 时触发）；列表数据 api/platformLoadingLists.ts；模板归 print/
柜级公共费用创建、审核、分摊与作废	components/ContainerFeesPanel.vue	api/containerFees.ts；firstleg/ 柜费来源、finance/
散货托盘码打印	components/PalletLabelPrintDialog.vue	api/platformLoadingLists.ts 的 /pallet-labels/prepare、/pallet-labels/print；print/

关键边界

• 预装详情进入后先调 /loading-plans/{planId}/lifecycle，再按返回状态决定可操作项；不自行推断生命周期阶段。
• 托盘码格式为“柜次号-FBA 地址内部编号-三位序号”，清单只取服务端按 FBA 仓分组的冻结结果，前端不生成、不改码、不重新编号；一件代发托盘不进入该清单。
• 确认预装和创建 PDA 任务前必须补齐真实集装箱号；历史上已建缺号任务可在预装详情首次补录，保存后恢复 PDA 可进入状态。
• 柜级公共费用只按服务端柜内客户/订单事实分摊，创建、审核、驳回、调整、作废均整组原子，金额必须守恒；待确认时禁止调整或重复作废。
• 独立清单详情与货柜详情页签共用同一套清单 API 与详情组件；改展示或打印时同步检查 container-loading 的装柜清单页签。

验证

• 定向：pnpm test src/modules/loading-lists/<目标测试>；container-loading 页签相关变更同时跑该模块测试。
• 本文件或索引变更后，从后端根运行 ./scripts/agents-index-contract.ps1。