# 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`。