diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 00000000..b59e8c23
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,8 @@
+.git
+.playwright-cli
+dist
+node_modules
+node_modules.broken-by-path
+.env.local
+npm-debug.log*
+pnpm-debug.log*
diff --git a/.env.example b/.env.example
index a39d43e3..ffaf65f9 100644
--- a/.env.example
+++ b/.env.example
@@ -1,2 +1,13 @@
 VITE_API_BASE_URL=/api
+# 按本机联调环境填写国内 Gateway origin，不提交真实环境地址。
 API_PROXY_TARGET=http://localhost:9000
+# 可选：本地分别直连 Auth、IAM、Warehouse；未设置时复用 API_PROXY_TARGET。
+# AUTH_API_PROXY_TARGET=http://localhost:9001
+# IAM_API_PROXY_TARGET=http://localhost:9002
+# WAREHOUSE_API_PROXY_TARGET=http://localhost:9003
+# 海外业务浏览器请求使用独立代理，代理会将 /overseas-api 重写为海外 Gateway 的 /api。
+VITE_OVERSEAS_API_BASE_URL=/overseas-api
+# 按本机联调环境填写海外 Gateway origin，不提交真实环境地址。
+OVERSEAS_API_PROXY_TARGET=http://localhost:9300
+# Local Vite fallback. Container deployments should use CLIENT_WEB_URL instead.
+VITE_CLIENT_WEB_URL=http://localhost:5174
diff --git a/.gitignore b/.gitignore
index e2bc4c31..5bcdd98b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,13 +7,16 @@ dist/
 !.env.example
 
 .playwright-cli/
+.idea/
 .impeccable/
 .codex-temp/
 .codex-tmp/
 .logs/
 outputs/
+reports/
+components.d.ts
+auto-imports.d.ts
 
 *.log
 .DS_Store
 Thumbs.db
-
diff --git a/AGENTS.md b/AGENTS.md
index baddfbda..47159940 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,50 +1,115 @@
 # Admin Web Instructions
 
-## 项目定位
+## 快速读取顺序
 
-- 本项目是虫虫出海内部运营与管理后台，仅服务平台员工。
-- 当前范围包括工作台、客户管理、头程订单、内部用户、角色管理和菜单权限。
-- 不在本项目承载企业客户自助流程、品牌官网、微信小程序、独立 APP 或仓库 PDA 作业。
+1. 用“模块快速路由”选择最小业务模块，进入后读取该目录最近的 `AGENTS.md`；按 `routes.ts → pages/ → api/types/stores/composables` 下钻，不先扫描全部 `src/`。
+2. 页面、布局或交互任务同时读取 `../../docs/Admin-Client前端原型还原验收规则.md` 和后台原型 `../../docs/悦/货代SAAS平台后台/AGENTS.md`。
+   Admin 样式优化还须读取 `../../docs/Admin高密度界面规范.md` 的“样式维护边界”和“新模块接入规则”；以已确认密度与彩色页签为视觉基线，逐操作保留业务语义和承载方式。国内仓、客户管理是样板；新增菜单按本轮范围显式接入，货柜管理入口见 `../../docs/Admin货柜管理样式核对记录.md`。
+3. 标准列表或公共组件任务读取 `src/shared/components/AGENTS.md`；国内/海外 HTTP、Token 或刷新任务读取 `src/shared/api/AGENTS.md`；Finance 任务读取 `src/modules/finance/AGENTS.md`；海外仓全流程任务先读 `../../docs/海外仓业务/README.md`。
+4. 平台/客户层级与权限公共语义读取 `../../docs/平台客户层级与权限契约.md`；双区域 API、海外 Token 和跨区事件读取 `../../docs/跨区域认证与服务通信契约.md`。
 
-## 技术基线
+## 项目定位与技术基线
 
-- 使用 Vue 3、TypeScript、Vite、Vue Router、Pinia、Element Plus、Axios 和 Lucide Vue。
-- TypeScript 保持严格模式；不要使用 `any` 绕过业务模型，优先从 `@chongchong/shared` 复用跨项目类型。
-- 使用现有 `@` 别名引用 `src/`。保持 ES Module 和现有无分号代码风格。
-- Element Plus 组件使用现有自动导入配置；`ref`、`computed` 等 Vue API 必须显式导入。`src/auto-imports.d.ts` 与 `src/components.d.ts` 属于生成声明，不手工维护业务内容。
+- 本项目是虫虫出海内部运营后台，仅服务平台员工；不承载企业客户自助、官网、小程序、独立 APP 或 PDA 作业。
+- 使用 Vue 3、TypeScript 严格模式、Vite、Vue Router、Pinia、Element Plus、Axios 和 Lucide Vue；保持 ES Module、现有无分号风格和 `@` 对 `src/` 的别名。
+- 不用 `any` 绕过业务模型。模块专属类型留在模块，本应用多模块稳定复用的类型放 `src/shared/`；服务端契约以 Controller/OpenAPI 为准。
+- Element Plus 使用现有自动导入；Vue API 显式导入。`src/auto-imports.d.ts`、`src/components.d.ts` 是生成声明，不手工维护业务内容。
 - 不更换框架、路由、状态管理、组件库或构建工具，除非任务明确要求并完成影响评估。
 
-## 目录与职责
+## 目录与依赖方向
 
-- `src/views/`：路由级页面和业务编排；复杂、可复用的展示或交互下沉到组件。
-- `src/components/`：无路由依赖的复用组件，输入输出应有明确类型。
-- `src/layouts/`：应用壳层、导航和全局页面结构。
-- `src/router/`：路由、标题、登录保护和权限元数据；新增模块时同步维护导航与路由配置。
-- `src/stores/`：跨页面状态和业务动作；仅页面局部使用的状态留在组件内。
-- `src/api/`：HTTP 客户端和接口适配；页面与组件不得散落创建 Axios 实例。
-- `VITE_API_BASE_URL` 控制浏览器请求前缀，`API_PROXY_TARGET` 控制 Vite 开发代理上游；后者只由开发服务器读取，不进入客户端构建。新增或变更环境变量时同步更新 `.env.example`，不得提交真实密钥或环境专属凭据。
-- `src/types/`：后台专属类型；跨应用共享的稳定契约放到 `packages/shared`。
-- `src/styles/`：设计令牌和全局样式；优先复用现有 `--cc-*` 变量和组件样式。
+| 目录 | 职责 |
+|---|---|
+| `src/app/` | 应用装配、布局、根路由、全局守卫和启动；不承载业务 |
+| `src/core/` | 认证、访问控制、导航、路由安全等全应用能力；不得依赖业务模块 |
+| `src/modules/` | 稳定业务领域的页面、API、类型、组件和模块路由；新增业务页面不放根级 `views/` |
+| `src/shared/` | 无业务归属的 HTTP、组件和工具；只有真实跨模块复用才上移 |
+| `src/prototype/` | 未纳入当前迭代的原型实现；正式模块不得依赖 |
+| `src/styles/` | 设计令牌和全局样式，优先复用 `--cc-*` 变量 |
 
-## 业务与安全约束
+- 依赖方向为 `app → modules/core/shared`、`modules → core/shared`、`core → shared`、`shared → 无上层依赖`。模块间只通过对方公开入口或契约协作，不引用其他模块的页面和内部目录。
+- 路由级页面放 `modules/*/pages/`，模块路由放 `modules/*/routes.ts` 并由 `app/router/index.ts` 装配；新增模块同步维护 `core/navigation/adminNavigation.ts`。
+- 领域接口放 `modules/*/api/`；国内、海外公共客户端分别为 `shared/api/http.ts`、`shared/api/overseasHttp.ts`，具体 Token 与刷新规则见 `shared/api/AGENTS.md`。
+- `VITE_API_BASE_URL`、`VITE_OVERSEAS_API_BASE_URL` 分别控制国内、海外浏览器前缀；开发代理上游只由 Vite 读取。环境变量变化同步 `.env.example`，不提交真实地址或凭据。
 
-- 菜单隐藏和前端路由守卫只改善体验，不能替代服务端鉴权。新增操作必须使用稳定的权限编码，并与 API 权限保持一致。
-- 认证统一经过 `src/stores/auth.ts` 和 `src/api/http.ts`；不要在页面中复制令牌读写或手工拼装 `Authorization`。
-- 当前登录和部分数据仍可能是模拟实现。接入 `services/api` 时删除对应模拟路径，不允许让生产逻辑静默回退到假数据。
-- 删除、停用、改权限等高风险操作必须有明确确认、处理中、成功和失败反馈；失败时保留用户上下文，避免误以为已生效。
-- 日志、提示和示例数据不得包含真实账号、令牌、客户隐私或生产数据。
+## 模块快速路由
 
-## UI 与交互
+表中 `modules/`、`core/`、`shared/`、`app/` 和 `main.ts` 均相对 `src/`；裸文件名沿用同一单元格最近目录。模块细节只在最近指引维护，应用层保留入口。
 
-- 延续现有后台视觉体系：克制的企业级界面、清晰的信息层级和高密度但可扫描的数据展示。
-- 优先使用 Element Plus 与现有复用组件；图标使用 Lucide，不用表情符号充当功能图标。
-- 表格、筛选、抽屉和表单应按实际语义覆盖适用的加载、空数据、错误、禁用和无权限状态，不为不适用的组件机械增加状态。
-- 保持键盘可操作、可见焦点、表单标签和足够的颜色对比度；不要只用颜色表达状态。
-- 新页面至少适配现有 320px 最小宽度策略，并检查侧栏、表格、抽屉和表单在窄屏下的退化方式。
+| 业务 | Admin 入口 | 联查 |
+|---|---|---|
+| 登录、会话与双区域 Token | `modules/auth/`、`core/auth/` | 国内 `auth/`、`iam/`；海外请求客户端再读 `shared/api/AGENTS.md` |
+| 启动与懒加载资源恢复 | `main.ts`、`core/routing/navigationRecovery.ts` | 仅识别动态模块/Chunk 资源过期；30 秒内同目标最多自动恢复一次，存在未保存编辑时必须先确认 |
+| 工作台与指标 | `modules/dashboard/` | 指标所属模块与服务端，不复制领域契约 |
+| 客户、企业审核、客户统计 | `modules/customers/` | `iam/`、`auth/`、`file/`、`firstleg/customerstatistics/`；公司联系电话只作企业联系信息，不修改管理员/成员登录手机号且不要求跨企业唯一。审核必填资质仅营业执照与统一社会信用代码；法人身份证选填，可随资质包提交，也可在已有营业执照后单独补传或替换 |
+| 供应商、国内整柜 | `modules/suppliers/`、`modules/domestic-containers/` | Backend `warehouse/` 及对应 OpenAPI |
+| 平台仓库与仓储资源 | 仓库主档 `modules/warehouses/`，国内资源 `modules/warehouse-resources/` | 全部仓库 ID、类型、状态、地址和能力归国内 `warehouse/`；海外 `warehouse-overseas-service/` 只维护引用同一 warehouseId 的库位、托盘和锁 |
+| 平台用户、RBAC、导航 | `modules/iam/`、`core/access/`、`core/navigation/` | `auth/`、`iam/`、平台权限契约 |
+| 国内/海外 PDA 独立人员与海外仓绑定 | `modules/iam/pages/InternalUsersView.vue`、`modules/iam/api/platformIam.ts` | 国内 `CN_FIRSTLEG_PDA_OPERATOR` 与海外 `OVERSEAS_WAREHOUSE_PDA_OPERATOR` 互斥；只有海外角色必须且只能绑定一个 `overseasWarehouseId`，候选来自国内 Warehouse 平台仓库 API 的公共 `OVERSEAS + ACTIVE + RECEIVING` 收货仓 |
+| 消息中心 | `modules/notifications/` | Backend `iam/.../notification/`；仅顶部消息中心，不进入左侧菜单 |
+| 订单列表、批量审核预览、详情、商品图片与入库费用 | `modules/unified-orders/`、`modules/first-leg-orders/`；平台商品图片由 `modules/unified-orders/api/unifiedOrders.ts` 按客户与 fileId 下载 | `order/`、`firstleg/`、Finance；图片读取归 `file/` 的 `PlatformProductImageController`。Order 状态为 `SUBMITTED` 时统一列表必须保持 `PENDING_REVIEW/APPROVE_ORDER`，不得被已存在的 Firstleg 准备中入库投影覆盖。批量审核弹框通过 `unifiedOrders.ts` 的 `/orders/first-leg/batch-review-preview` 一次取回全部预览，按服务端 `canApprove/blockReason` 展示，不逐票请求详情或用内部 ID 作标题 |
+| 客户原始申报资料编辑与渠道变更 | `modules/unified-orders/components/OrderDeclarationEditorDialog.vue`、`api/unifiedOrders.ts`、`pages/UnifiedOrdersView.vue` | 使用订单版本和货物 `itemNo` 整体提交，不允许增删货物行；只编辑客户申报快照，不覆盖仓库/PDA 实测、测量审核或计费事实。渠道变化需二次确认并由 Backend `order/` 联查 `firstleg/` 的分柜、同柜、装柜与重新计价门禁；国内收货仓或中转仓变化必须重新下单 |
+| 入库扣货、解除与凭证历史 | `modules/unified-orders/pages/UnifiedOrdersView.vue`、`modules/inbounds/core/api.ts`、`types.ts` | 页面只消费服务端 `holdFlag/currentHoldReason/canHold/canRelease/actionBlockReason/history`；扣货与解除提交当前入库版本、幂等键、必填原因和可选凭证，凭证下载只走 Firstleg 授权入口。Backend `firstleg/` 的 `InboundHoldService`、`InboundHoldGuard`、`InboundHoldEvidenceService`，文件归 `file/` |
+| 入库、测量、称重库位状态、客户箱规策略与计价主数据 | 测量弹框/工作区 `modules/inbounds/measurement/InboundMeasurementDialog.vue`、`InboundMeasurementPanel.vue`，称重 `modules/inbounds/weight/components/WeightOcrPanel.vue`；主数据 `modules/fba-pricing/`、`modules/dimension-config/`、`modules/customers/components/CustomerBillingRulesPanel.vue`、`modules/fee-items/` | 客户固定四档箱规，默认计算方式为 `ADD/MULTIPLY`；测量行可选实际尺寸、箱规尺寸策略或客户默认尺寸系数，保存后以 Backend `firstleg/` 返回的外箱尺寸、体积重和计费基数为准，不在页面独立重算。费用确认的实际箱数、毛重和体积优先汇总当前 `actualMeasurementRows`，不得用可能滞后的工作区顶层合计覆盖明细。称重页在每张图片卡片只展示服务端 `locationCode/slotStatus/sharedOverflow`，不渲染或自行推导整票预留引导；删除图片须提示槽位仍归本票保留，不得按图片数组下标推导托盘或库位 |
+| 一件代发托盘打印 | `modules/unified-orders/pages/UnifiedOrdersView.vue` 的“托盘打印”页签、`modules/inbounds/core/DropshipPalletPrintPanel.vue`、`core/api.ts` | 仅一件代发订单展示；测量审核预生成托盘码后由 Admin 电脑端打印，支持本票全部托盘合并打印和单托补打。PDA 只扫码组托，不承担 PDF 下载或打印机连接 |
+| 入库单扣货、解除、凭证与历史 | `modules/inbounds/pages/InboundOrdersView.vue`、详情工作区、`modules/inbounds/core/api.ts` | 列表展示服务端 `holdFlag/currentHoldReason` 并支持筛选；详情只按 `canHold/canRelease/actionBlockReason` 开放操作。扣货与解除提交当前 `version`、原因和独立幂等键，可选凭证先按明确客户与入库单上传；历史文件只调用专用下载入口，不把上传成功但未提交命令的文件冒充扣货证据 |
+| 客户专属价格簿、柜级阶梯运费与受控调价 | 列表/上传 `modules/fba-pricing/carrier-rates/pages/CarrierRatesView.vue`，版本详情/仓库映射/确认 `modules/fba-pricing/carrier-rates/pages/CarrierRateDetailView.vue`，路由 `modules/fba-pricing/routes.ts`；`modules/inbounds/fee/`、`modules/unified-orders/components/InboundFeeDetailManager.vue` | 列表与上传后按 `versionId` 进入 `fba-carrier-rate-detail` 独立详情页，价格行只读；回归入口 `modules/fba-pricing/carrier-rates/pages/CarrierRatesView.test.ts`。价格簿页面显式选择公共报价或具体客户；列表、上传、确认只作用于该 `customerId`，不得混合版本。计价优先消费客户专属 ACTIVE 版本，无专属版本才回退公共 ACTIVE；柜级阶梯金额和各客户分摊只展示服务端结果。调整计费量只能在服务端返回的上下 10% 范围内并提交当前费用版本、原因与二次确认；私人仓尾程派送费使用稳定 `PRIVATE_LAST_MILE_DELIVERY` 代码且只对 `PRIVATE` 目的地开放；一件代发须在预装确认前完成试算，计价后保持服务端 `WAIT_PALLETIZE` 状态 |
+| 财务、客户资金账户与柜级公共费用分摊 | `modules/finance/`，继续读该目录 `AGENTS.md`；客户账户 `pages/FinanceCustomerAccountsView.vue`，柜费 `modules/loading-lists/components/ContainerFeesPanel.vue`、`api/containerFees.ts` | `finance/`、`firstleg/`、`file/`、`docs/财务管理/`；实际、冻结、可用余额、授信与流水只消费 Finance 权威结果，充值审核和手工充扣携带版本与幂等键。跨客户公共柜费只按服务端柜内客户/订单事实分摊，金额必须守恒，创建与审核、驳回、调整、作废均整组原子处理 |
+| 货柜双工作台、排柜、预装/装柜清单、真实柜号后补与整柜报关 | 国内 `modules/container-loading/pages/DomesticContainersView.vue`、海外 `OverseasContainersView.vue`，共享详情实现 `ContainerDetailView.vue`；预装详情 `modules/loading-lists/pages/PreloadPlanDetailView.vue`，资料/PDA 证据 `components/ContainerOverviewPanel.vue`，报关 `components/ContainerCustomsPanel.vue` | 国内“送柜报关”只消费 `/containers/domestic` 与服务端 `allowedActions`，承载模拟柜、订舱关联、智能装柜；模拟柜创建选择与智能装柜一致的 9 类计划渠道，未关联订舱前实际渠道为空，订舱关联候选按计划渠道组匹配、装柜清单页签、出口报关和国内出仓；创建柜次时自动生成唯一预装计划，预装详情先调用 `/loading-plans/{planId}/lifecycle`，完成后深链进入国内货柜详情的装柜清单页签，不再注册独立正式清单导航和路由。订舱关联允许真实集装箱号为空，但确认预装和创建 PDA 任务前必须补齐；历史已建但缺号的任务仍可在预装详情首次补录，保存后恢复 PDA 可进入状态；全买单柜继续使用 `complete-all-buy`。海外“清关提柜”只消费 `/containers/overseas`，承载船节点、目的港清关、DO/PU、码头车队和还空；原预约/实际提柜展示位改为整柜预计/实际到仓，预计到仓在列表内人工快捷维护并经海外接口同步整柜尾程订单，实际到仓只读海外 PDA 首次开始收货时间。还空截止事实由服务端基于卸柜完成时间加 72 小时计算，前端不重算。两端统一使用 `containerBookingId`，列表范围由服务端 `scope=ACTIVE/HISTORY` 分页，禁止浏览器筛选或本地推导写资格。后端为 `LoadingListService`、`firstleg/customs/container/`、`firstleg/terminaldrayage/` 和 `lastleg-service/`，文件归 `file/` |
+| 合柜报关 / 同柜不可拆组 | `modules/unified-orders/api/coLoadGroups.ts`、`pages/UnifiedOrdersView.vue`；装柜消费 `modules/container-loading/pages/SmartLoadingWorkbenchView.vue` | 前端只提交订单 ID；Backend `firstleg/loading/coload/` 展开并冻结每票全部可用入仓片段。成员数是入仓片段数，不等于订单票数；只要求同国内仓、同渠道，允许跨客户及不同目的仓港；分配、移除、取消均整组处理 |
+| 全局智能装柜工作台、入仓码候选与箱数分配 | `modules/container-loading/components/SmartLoadingDialog.vue` 内嵌 `pages/GlobalSmartLoadingView.vue`，柜次页 `SmartLoadingWorkbenchView.vue`，以及 `smartLoadingChannelGroups.ts`、`smartLoadingItems.ts`、`api/platformContainerLoading.ts`；全局页当前不注册独立路由 | Backend `firstleg/` 的 `/inbound-candidates`、`/containers`、`/inbound-assignments`、`/plans/{planId}/pending-review-assignments`、`/group-assignments`、`/unpicked-items`。`orderStatuses` 最多四项且未传表示全部未完成状态；候选状态多选覆盖待审核、待测量、待分柜、装柜中，状态只用于筛选展示，按钮资格以服务端 `canAssign` 为准；待审核/待测量可提前占位但不得提前确认预装或启动 PDA。计划箱数编辑上限、已用和未用展示只消费服务端 `totalPackageCount/remainingPackageCount`，不得从候选页或本地规格重新拼算。人工加入允许跨渠道，智能推荐仍按柜次渠道。柜次容量和限重取服务端字段；同柜组作为单卡整组分页、分配和移除，任一成员已拣时整组保留 |
+| 国内货柜履约订舱资料、打印、关联候选与出仓前船期 | `modules/ocean-bookings/` 的 `components/OceanBookingDocumentsPanel.vue`、`OceanBookingPrintDialog.vue`，以及 `modules/container-loading/`、`modules/port-schedules/` | 订舱草稿按当前版本维护资料，放舱后资料与表单只读；打印对草稿与已放舱订舱均开放，按当前已保存资料生成，未填写字段显示“—”。`platformOceanBookings.ts` 的 `/link-candidates` 只消费服务端分页，`containerCount` 是柜型需求 `quantity` 总和；Backend `firstleg/oceanbooking/`、`file/`、`print/`、`firstleg/portschedule/` |
+| 订舱级拖车预约 | `modules/trucking/api/platformTrucking.ts` 的 `/candidates`、`components/TruckAppointmentForm.vue`、`pages/TruckAppointmentCreateView.vue`、`TruckAppointmentsView.vue` | 表单只选择服务端返回的 `RELEASED` 订舱与 `TRUCKING + truckingScope=DOMESTIC` 国内拖车供应商，不选择或提交客户、柜次、装柜计划或真实集装箱号；清关提柜固定选择 `OVERSEAS` 海外车队，类型在供应商主档单选维护；提单号和仓库由订舱冻结事实带入。一个订舱最多一张非终态拖车单，重复创建转入现有单继续编辑；PDA 完成不自动推进拖车。附件为平台作用域且不重复提单文件；Backend `TruckAppointmentService`、`truck-appointments-v1.yaml` |
+| 目的港码头拖车与还空预警 | 海外清关提柜工作台/详情 `modules/container-loading/pages/OverseasContainersView.vue`、`OverseasContainerDetailView.vue`，API `modules/container-loading/api/terminalDrayages.ts`、`containerArrivalTimes.ts` | 与订舱级拖车预约是不同生命周期；按 `containerBookingId` 读取服务端状态、`allowedActions` 和历史，不能复用订舱级拖车表单或自行推进状态。列表“预计到仓”列直接提供人工日期时间选择器，保存时通过 Lastleg 柜级版本和幂等键原子更新该柜全部尾程订单，已有入库计划后禁止修改；“实际到仓”只读 `ll_receiving_container_session.receiving_at`，即海外 PDA 首次开始收货时间。还空截止、超时天/小时只展示服务端基于权威卸柜完成时间加 72 小时计算的结果；Backend `firstleg/terminaldrayage/`、`lastleg-service/`，邮件记录通过 `terminalDrayages.ts` 查询与重试。 |
+| 历史报关协同与国内出仓 | `modules/customs/`、`modules/outbound-dispatch/` | `modules/customs/` 是历史报关案件/清单/代理提交与回执入口；装柜完成后的整柜退税/买单资料从货柜详情进入，不在旧模块复制；Backend `firstleg/outbound/dispatch/`、`firstleg/customs/`、`file/` |
+| 主数据、下载、退避任务重试、审计 | `modules/master-data/`、`modules/downloads/pages/DownloadCenterView.vue`、`modules/audit/` | File 导出任务返回 `attemptCount/maxAttempts/nextRetryAt`；仅失败或已进入自动退避的等待任务显示重试，等待任务重试用于立即执行当前投递，不创建新任务；联查 `warehouse/`、`file/`、`audit-service/` |
+| 海外接柜、入库、库存与库内服务 | `modules/overseas-warehouse/` | `gateway-overseas/`、`lastleg-service/`、`warehouse-overseas-service/`；与排车、出库、派送、异常退回和一件代发共同组成海外仓全流程 |
+| 海外采购、卡车、散板 | `modules/overseas-business/` | `gateway-overseas/`、`lastleg-service/` |
+| 海外仓业务合作仓与通用资料 | 合作仓 `modules/warehouses/`；报价/汇率/车辆 `modules/overseas-master-data/` | 国内 `warehouse/`、海外实际资源与服务 |
+| 海外仓业务国内出仓后船节点 | `modules/port-schedules/`、`modules/ocean-bookings/`、货柜详情 | `firstleg/portschedule/`、`integration-service/`；预计节点只展示不推进实际进度，手工实际节点必须严格向后追加并防重复，十节点标准见 `../../docs/海外仓业务/船节点标准化契约.md` |
+| 海外排车、出库与派送 | `modules/overseas-warehouse/AGENTS.md` | 按模块表定位排车、出库、派送页面及 API；履约边界在模块内维护 |
+| 海外异常退回与客户回访 | `modules/overseas-warehouse/AGENTS.md` | 派送异常退回区别于退货库存；页面、API 与原子推进约束见模块指引 |
 
-## 本地命令与质量门禁
+全量验收按业务从 `../../docs/订单与客户/`、`入库测量与计费/`、`国内货柜履约/`、`财务管理/` 选择最小契约；海外仓业务开发先读 `../../docs/海外仓业务/README.md`。进度、排期或验收状态问题再读取进度表和报告。
 
-在 `apps/admin-web` 目录执行：
+散货托盘码打印：`modules/loading-lists/components/PalletLabelPrintDialog.vue`、`modules/loading-lists/api/platformLoadingLists.ts`，由货柜详情与装柜清单详情进入；先调用 `/pallet-labels/prepare` 获取服务端按 FBA 仓分组的冻结清单，再通过 `/pallet-labels/print` 下载 PDF。托盘码使用“真实柜号-FBA 地址内部编号-三位序号”，页面同时展示 FBA 仓码和内部编号；支持全部打印或按仓指定张数补打，一件代发托盘不在该清单，前端不生成或重新编号托盘码。
+
+## 海外模块内部快速索引（海外仓全流程）
+
+- 海外仓的尾程订单控制与柜级入仓计划转换、退货库存、排车出库、异常回访：读取 `src/modules/overseas-warehouse/AGENTS.md`，字段与流程仅在该模块维护。
+
+| 关键词 | 页面/路由入口 | API 与联查 |
+|---|---|---|
+| 海外采购 | `modules/overseas-business/pages/PurchaseOrdersView.vue`、详情/编辑页 | `modules/overseas-business/api/platformOverseasBusiness.ts` 的 purchase 方法；Backend `lastleg-service/procurement/` |
+| 美国卡车、本土散板 | `modules/overseas-business/pages/TransportOrdersView.vue`、`TransportOrderFormView.vue` | 同一 API 的 us-truck/looseboard 方法；Backend `lastleg-service/trucking/`、`looseboard/` |
+| 海外报价、月度汇率、车辆 | `modules/overseas-master-data/pages/OverseasQuotesView.vue`、`ExchangeRatesView.vue`、`VehiclesView.vue` | `modules/overseas-master-data/api/overseasMasterData.ts`；Backend `lastleg-service/masterdata/` |
+
+## 业务、安全与共享装配
+
+- 当前只有平台、客户两级；Admin 不显示“租户”。平台仓库是公共主数据，不与客户绑定；客户筛选不得缩小仓库候选。完整语义见平台客户层级与权限契约。
+- 新建客户时，公司联系电话同时初始化首个管理员登录手机号；创建后公司联系电话只属于企业资料，与首个管理员、成员及平台用户登录手机号独立。编辑客户资料不得提交账号手机号变更，账号手机号改动统一走用户管理并由 IAM/Auth 撤销对应会话。
+- 菜单、列表路由和详情只读统一使用 `*:list`，写操作使用独立权限；前端守卫不能替代服务端鉴权。供应商固定使用 `platform:supplier:list`。
+- 平台用户选择 `OVERSEAS_WAREHOUSE_PDA_OPERATOR` 时必须选择唯一实际海外收货仓，其他角色不得提交 `overseasWarehouseId`；编辑时保留已绑定仓库并按字符串透传长整型 ID，前端校验不能替代 IAM 服务端约束。
+- 国内出仓以真实货柜为原子边界：货柜详情只在装柜完成、全部入仓绑定门禁通过且有写权限时显示确认离仓；成功后由服务端同事务推进全部技术行并幂等创建船节点查询。前端不得逐入仓确认、把拖车状态当阻断门禁或重复追加实际船节点。
+- `core/navigation/adminNavigation.ts`、`app/router/index.ts` 和模块 `routes.ts` 是共享装配文件；并行任务不得覆盖总控已确认语义，重叠时保留现有改动并回传总控。
+- `core/routing/navigationRecovery.ts` 只处理已识别的动态 import/Chunk 资源过期；普通路由错误直接提示。自动恢复前保护未保存表单，同一目标 30 秒内不得重复刷新或形成重载循环。
+- 认证统一经过 `core/auth/auth.ts`、`shared/api/http.ts` 和 `shared/api/overseasHttp.ts`。登录/刷新原子替换国内、海外 Token，海外 401 统一刷新并最多重放一次；页面不读写 Token 或手工拼 `Authorization`。
+- 接入真实接口时删除对应模拟路径，不允许生产逻辑静默回退假数据。客户专属写操作显式选择客户，长整型 ID 按字符串透传，不从本地存储推断。
+- 订舱代理、拖车承运商和报关代理提交服务端供应商 ID，从公共供应商列表选择 `ACTIVE` 且类别/范围匹配的记录；参数变化同步检查 API、类型、表单、展示、Mock/Fixture、测试和 OpenAPI。
+- 删除、停用、改权限等高风险操作必须有确认、处理中、成功和失败反馈；失败保留用户上下文。日志、提示和示例不得包含真实账号、Token、隐私或生产数据。
+- 页面和交互必须服从对应原型及验收规则；Admin 当前只验收 `1920×1080`、`100%` 缩放。标准列表和共享组件实现继续读 `src/shared/components/AGENTS.md`。
+
+## 开发验收身份
+
+- 开发环境人工验收身份为 `platform_admin`。密码从未提交的 `CHONGCHONG_ADMIN_ACCEPTANCE_PASSWORD` 或 `C:/Users/BY-OY/.codex/chongchong-global-dev-acceptance.env` 读取；缺失时再向用户索取，不写入仓库、日志或快照。
+- 由人工操作真实页面并截图，AI 核对加载、空态、错误态、权限和桌面布局；缺少截图时标记“待人工截图确认”，不自行批量取证。
+
+## 命令与质量门禁
+
+- 国内仓、客户管理密度默认值统一维护在 `src/styles/adminDensityTokens.css`，通用按钮/页签/描述表/弹框规则统一维护在 `adminDensity.css`；页面只选择公共类与语义参数、保留业务布局，不复制通用外观或在页面重新定义 `--admin-*` 默认值。修改前沿实际引用读取模块 CSS，接管后删除冲突旧声明。
+- 修改密度样式或接入消费者时更新并运行 `src/styles/adminDensity.test.ts` 维护合同；不得为通过检查删除权限、业务提交或错误处理断言。未接入菜单通过显式密度类隔离。
+
+在 `apps/admin-web` 执行：
 
 ```bash
 pnpm install
@@ -54,6 +119,7 @@ pnpm typecheck
 pnpm build
 ```
 
-- 日常变更至少运行 `pnpm typecheck` 和受影响测试；交付前运行 `pnpm test` 与 `pnpm build`，后者也会执行类型检查。
-- 当前项目未声明 lint 脚本，不要声称 lint 已通过。若任务新增或变更质量脚本，应同时更新 `package.json`、`README.md` 和本文件。
-- 不手工修改 `dist/` 或 `node_modules/`；依赖变更必须同步当前项目的 `package.json` 与锁文件。
+- 普通变更至少运行 `pnpm typecheck` 和受影响测试；交付前运行 `pnpm test` 与 `pnpm build`。当前没有 lint 脚本，不声称 lint 通过。
+- 不手工修改 `dist/`、`node_modules/` 或生成声明；依赖变化同步 `package.json` 与锁文件。
+- 测试环境全量验收入口为 `../../baiyue-firstleg/scripts/admin-test-env-acceptance.mjs`，模块说明见同仓库 `scripts/admin-test-env-modules/README.md`；它会写入或停用测试数据，只有本轮明确授权才能运行。
+- `pnpm test/typecheck` 和本地回归脚本不代表真实服务验收完成；HTTP 验收后仍由人工完成页面和截图确认。
diff --git a/DESIGN.md b/DESIGN.md
new file mode 100644
index 00000000..8fb8fa52
--- /dev/null
+++ b/DESIGN.md
@@ -0,0 +1,261 @@
+---
+name: "虫虫出海 Admin"
+description: "克制、清晰且高密度可扫描的企业级运营工作台"
+colors:
+  primary: "#667eea"
+  primary-hover: "#5366c8"
+  primary-soft: "#eaf1ff"
+  work-canvas: "#f4f6f8"
+  surface: "#ffffff"
+  surface-muted: "#f8fafc"
+  text: "#172033"
+  text-secondary: "#475467"
+  muted: "#667085"
+  muted-light: "#98a2b3"
+  border: "#e3e8ef"
+  border-subtle: "#edf0f4"
+  success: "#067647"
+  success-soft: "#ecfdf3"
+  warning: "#b54708"
+  warning-soft: "#fffaeb"
+  danger: "#b42318"
+  danger-soft: "#fef3f2"
+  info: "#3538cd"
+  info-soft: "#eff4ff"
+typography:
+  headline:
+    fontFamily: '"PingFang SC", "Microsoft YaHei", "Segoe UI", sans-serif'
+    fontSize: "20px"
+    fontWeight: 700
+    lineHeight: 1.35
+    letterSpacing: "0"
+  title:
+    fontFamily: '"PingFang SC", "Microsoft YaHei", "Segoe UI", sans-serif'
+    fontSize: "16px"
+    fontWeight: 700
+    lineHeight: 1.4
+    letterSpacing: "0"
+  body:
+    fontFamily: '"PingFang SC", "Microsoft YaHei", "Segoe UI", sans-serif'
+    fontSize: "13px"
+    fontWeight: 400
+    lineHeight: 1.5
+    letterSpacing: "0"
+  label:
+    fontFamily: '"PingFang SC", "Microsoft YaHei", "Segoe UI", sans-serif'
+    fontSize: "12px"
+    fontWeight: 650
+    lineHeight: 1.5
+    letterSpacing: "0"
+  supporting:
+    fontFamily: '"PingFang SC", "Microsoft YaHei", "Segoe UI", sans-serif'
+    fontSize: "11px"
+    fontWeight: 400
+    lineHeight: 1.5
+    letterSpacing: "0"
+rounded:
+  xs: "3px"
+  sm: "4px"
+  md: "6px"
+  panel: "8px"
+  nav: "10px"
+  accent: "12px"
+  pill: "999px"
+  circle: "50%"
+spacing:
+  xxs: "4px"
+  xs: "8px"
+  sm: "10px"
+  md: "12px"
+  lg: "16px"
+  xl: "20px"
+  xxl: "24px"
+  xxxl: "32px"
+components:
+  dashboard-tab-selected:
+    backgroundColor: "{colors.primary}"
+    textColor: "{colors.surface}"
+    typography: "{typography.label}"
+    rounded: "{rounded.panel}"
+    padding: "0 12px"
+    height: "36px"
+  dashboard-button-outline:
+    backgroundColor: "{colors.surface}"
+    textColor: "{colors.text-secondary}"
+    typography: "{typography.label}"
+    rounded: "{rounded.panel}"
+    padding: "0 13px"
+    height: "36px"
+  surface-panel:
+    backgroundColor: "{colors.surface}"
+    textColor: "{colors.text}"
+    rounded: "{rounded.panel}"
+    padding: "20px"
+  status-badge:
+    backgroundColor: "{colors.success-soft}"
+    textColor: "{colors.success}"
+    typography: "{typography.supporting}"
+    rounded: "{rounded.pill}"
+    padding: "2px 8px"
+    height: "24px"
+---
+
+# Design System: 虫虫出海 Admin
+
+## Overview
+
+**Creative North Star: "冷静的运营工作面"**
+
+虫虫出海 Admin 是面向平台员工的高密度运营工作台。界面以冷灰工作面承接连续任务，以白色边框面板划分可操作区域，以柏悦蓝标记主操作、焦点和当前选中项；视觉表达克制，优先让字段、状态和操作顺序一眼可扫。
+
+系统不依赖装饰性大色块制造层级。面板边界、浅层级色、紧凑字号和稳定间距共同组织信息；状态色只承担分类、进度、告警和错误反馈，不替代文字标签。壳层可以建立明确品牌存在感，业务内容区保持安静、可复用、可扩展。
+
+**Key Characteristics:**
+
+- 冷灰画布与白色面板构成稳定工作面。
+- 柏悦蓝只承载主操作、焦点和选中态。
+- 12–13px 信息层与 16–20px 标题层形成紧凑层级。
+- 边框和浅色填充负责大多数深度，阴影保持稀缺。
+- 桌面端追求密度，窄屏端保证 44px 级触控与可横向退化的数据表格。
+
+## Colors
+
+主色清晰但不过量；中性冷灰负责内容秩序，语义色只在需要判断状态时出现。
+
+### Primary
+
+- **柏悦蓝**：用于主操作、当前导航、页内选中态、关键链接和可见焦点。
+- **柏悦蓝悬停色**：用于白底描边操作的悬停文字与边框反馈。
+- **柏悦蓝浅底**：用于图标容器、头像底和弱强调背景，不作为大面积业务面板底色。
+
+### Neutral
+
+- **冷灰工作面**：应用画布与全屏看板背景，使白色业务面板保持清晰边界。
+- **白色业务面**：卡片、表格、筛选栏、抽屉和控件的默认承载面。
+- **浅层级灰**：表头、说明块和次级区域背景。
+- **墨色正文**：标题、主值和核心业务文本。
+- **次级墨灰**：表头、次级数据和操作文案。
+- **说明灰**：帮助文本、辅助标签、时间与空值提示。
+- **冷灰边线**：面板、分区和表格结构的主要深度手段。
+
+### Secondary
+
+- **成功绿 / 浅成功绿**：已完成、启用和正向状态。
+- **告警橙 / 浅告警橙**：待处理、临近期限和需关注状态。
+- **危险红 / 浅危险红**：错误、失败、停用和高风险状态。
+- **信息靛蓝 / 浅信息靛蓝**：信息型状态和非主操作分类。
+
+### Named Rules
+
+**The One Primary Rule.** 柏悦蓝是唯一的全局交互主色；图表分类色和语义色不得升级为第二主色。
+
+**The Status Has Words Rule.** 状态色必须与状态文字、图标或结构共同出现，绝不只靠颜色传达业务含义。
+
+## Typography
+
+**Display Font:** PingFang SC（回退至 Microsoft YaHei、Segoe UI、sans-serif）  
+**Body Font:** PingFang SC（回退至 Microsoft YaHei、Segoe UI、sans-serif）  
+**Label/Mono Font:** 业务标签沿用正文栈；权限码与接口值使用 Cascadia Code（回退至 Consolas、monospace）
+
+**Character:** 统一的系统无衬线字栈保证中文字段紧凑清晰，不使用展示型字体制造品牌感。层级主要来自字号、字重和颜色，而不是大幅字距或全大写。
+
+### Hierarchy
+
+- **Headline**（700，20px，1.35）：页面级标题、详情页标题和空状态主标题。
+- **Title**（700，16px，1.4）：面板标题、表格区标题和主要分区标题。
+- **Body**（400，13px，1.5）：业务内容、表单值和操作说明。
+- **Label**（650，12px，1.5）：表头、筛选标签、按钮和强调型元数据。
+- **Supporting**（400，11px，1.5）：帮助文本、时间、附注、次级值和状态胶囊。
+
+### Named Rules
+
+**The Scan Before Drama Rule.** 业务页标题不以超大字号争夺空间；20px 页面标题、16px 分区标题与 12–13px 内容层已经构成完整层级。
+
+## Layout
+
+应用壳层在桌面端使用固定 240px 侧栏、64px 顶部栏和 20px 内容边距；折叠侧栏为 76px。业务页面以 16px 垂直节奏堆叠，数据看板使用 14–18px 卡片间距，面板常用 16–24px 内边距。筛选栏、指标条、表格面板和抽屉分区通过一致边框对齐，避免每个模块自行发明容器结构。
+
+960px 以下优先减少多列网格；720px 以下侧栏变为遮罩抽屉，页面边距收至 14–18px，筛选控件纵向铺满，抽屉占满宽度，操作按钮保证可触控高度；420px 以下指标条转为单列或受控双列。表格保留语义列和首列操作，通过水平滚动退化，不把关键操作固定到最右侧。最低 320px 宽度下仍保持内容可访问。
+
+**The Operation First Rule.** 业务数据表格的“操作”列始终是第一列；布局收窄时保留该顺序。
+
+## Elevation & Depth
+
+系统采用“平面为主、壳层有深度”的混合策略。业务面板默认依靠冷灰画布、白色表面、1px 边框和浅层级填充建立关系；常驻阴影集中在固定侧栏、粘性顶部栏、头像与粘性操作区，卡片阴影只在明确悬停状态出现。
+
+### Shadow Vocabulary
+
+- **侧栏壳层**（`4px 0 32px rgba(0,0,0,.08)`）：固定侧栏与内容工作面的分界。
+- **顶部栏壳层**（`0 8px 32px rgba(0,0,0,.15), 0 2px 8px rgba(0,0,0,.1)`）：粘性顶部栏的结构性悬浮。
+- **头像状态**（`0 4px 12px rgba(0,0,0,.15)`）：顶部栏内小面积实体的清晰分离。
+- **卡片悬停**（`0 6px 16px rgba(23,42,70,.08)`）：仅用于可点击卡片的悬停反馈。
+- **粘性底栏**（`0 -8px 22px rgba(15,23,42,.05)`）：需要在长表单中保持可见的操作区。
+
+### Named Rules
+
+**The Flat Business Surface Rule.** 普通卡片、表格和筛选面板静止时不加阴影；边框与层级色已经足够。
+
+## Shapes
+
+业务面板和主要交互以轻度圆角为主：8px 是卡片、面板、页内按钮和多数复合控件的主轮廓；6px 用于说明块和紧凑内部容器，10–12px 只用于导航或更具身份感的壳层元素。状态胶囊使用完全圆角，头像、数据图例点和进度点使用圆形。结构边线保持 1px，不使用厚描边装饰内容区。
+
+## Components
+
+### Buttons
+
+- **Shape:** 页内按钮和分段选择使用轻度圆角（8px）；Element Plus 通用按钮保留其既有组件轮廓。
+- **Primary:** 柏悦蓝底配白字，用于查询、提交和当前选中项；同一区域避免并列多个主按钮。
+- **Hover / Focus:** 描边按钮悬停时转为柏悦蓝系边框与文字；全局键盘焦点使用 3px 半透明蓝色轮廓并保留外偏移。
+- **Secondary / Ghost:** 白底冷灰描边承载重置、返回、全屏和低优先级操作；禁用态使用浅灰底、浅灰字并移除可点击光标。
+
+### Chips
+
+- **Style:** 状态胶囊最小高度 24px，左右 8px 内边距，11px 半粗文字；默认使用中性灰，成功、告警、危险与信息状态使用各自的浅底深字组合。
+- **State:** 胶囊用于呈现状态，不替代按钮；可筛选标签的选中态仍回到柏悦蓝交互语义。
+
+### Cards / Containers
+
+- **Corner Style:** 白色业务面板采用 8px 圆角。
+- **Background:** 业务内容用白色，表头和内部次级区域用浅层级灰。
+- **Shadow Strategy:** 默认无阴影，遵守 Elevation & Depth 中的平面业务面规则。
+- **Border:** 1px 冷灰边线；表格内部使用更浅的分隔线。
+- **Internal Padding:** 常规面板 20px，紧凑工具栏 14–16px，抽屉分区 22–24px。
+
+### Inputs / Fields
+
+- **Style:** 复用 Element Plus 输入、选择和日期控件；筛选字段桌面端常用 260–360px，白底、细边框、紧凑高度。
+- **Focus:** 使用柏悦蓝焦点边框和全局可见焦点轮廓，不以阴影替代键盘焦点。
+- **Error / Disabled:** 错误保留具体文案与请求元信息；禁用态降低对比并保持不可操作语义。
+
+### Navigation
+
+- **Style:** 桌面侧栏 240px，折叠为 76px；一级项高 46px，子项高 42px。默认文字为中性灰，悬停以浅蓝渐变和轻微横移反馈，当前项使用柏悦蓝文字、加粗字重与左侧内嵌标记。720px 以下转换为遮罩式侧栏，不压缩正文到不可读宽度。
+
+### Data Tables
+
+- **Style:** 表头高 44px，12px 半粗文字与浅灰底；单元格垂直内边距 12px，主值 13px、次值 11px。
+- **Structure:** 操作列在第一列；表格面板裁切外轮廓，表尾用顶边线连接分页和结果统计。
+- **Responsive:** 窄屏保留水平滚动与 44px 操作触控高度，不隐藏关键字段而制造上下文丢失。
+
+### Dashboard Panels
+
+- **Style:** 指标卡和图表面板沿用 8px 白色边框面板。图表分类色只在图形、图例点和数据标记中出现；面板标题、轴标签和说明仍使用全局中性色层级。
+- **State:** 全屏模式回到冷灰工作面；数据未接入时必须明确标注为静态演示，不把占位数据伪装为实时数据。
+
+## Do's and Don'ts
+
+### Do:
+
+- **Do** 优先复用 `--cc-primary`、`--cc-border`、`--cc-muted` 和既有白色面板结构。
+- **Do** 用 1px 边线、浅层级灰和稳定间距组织密集数据。
+- **Do** 为加载、空数据、错误、禁用和无权限状态保留清晰文字与可恢复操作。
+- **Do** 在 720px 以下检查侧栏、筛选栏、表格、抽屉与按钮的触控和滚动退化。
+- **Do** 使用 Lucide 图标，并为纯图形操作提供文本或无障碍名称。
+
+### Don't:
+
+- **Don't** 在普通业务面板上批量添加阴影、玻璃效果或装饰渐变。
+- **Don't** 把图表分类色或状态色用于主操作、导航选中态或大面积背景。
+- **Don't** 用表情符号充当功能图标，也不要只靠颜色表达状态。
+- **Don't** 用超大标题、宽字距或低密度留白牺牲运营页面的扫描效率。
+- **Don't** 把核心操作放到表格末列或右侧固定列。
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 00000000..8c6e73e1
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,37 @@
+# 构建 Vue 静态文件。CI 通过构建参数切换到内网基础镜像，
+# 本地开发仍可使用 Docker Hub 默认值。
+ARG NODE_IMAGE=node:22-alpine
+ARG NGINX_IMAGE=nginx:1.27-alpine
+FROM ${NODE_IMAGE} AS build
+
+WORKDIR /app
+
+# Corepack 与 pnpm 依赖均通过 npmmirror 下载，避免构建时访问 npm 官方源过慢。
+ENV COREPACK_NPM_REGISTRY=https://registry.npmmirror.com
+ENV NPM_CONFIG_REGISTRY=https://registry.npmmirror.com
+RUN corepack enable
+
+COPY package.json pnpm-lock.yaml ./
+COPY shared/package.json ./shared/package.json
+# package.json 和 lock 文件未变化时，这一层会由 Docker 自动复用，
+# 因此不会重复下载 pnpm 依赖。
+RUN pnpm config set registry https://registry.npmmirror.com && \
+    pnpm install --frozen-lockfile
+
+COPY . .
+ARG VITE_CLIENT_WEB_URL
+ENV VITE_CLIENT_WEB_URL=${VITE_CLIENT_WEB_URL}
+# Docker 构建时同机还会运行多项服务，限制 Vitest 并发以避免测试超时。
+# pnpm 会直接把脚本名后的参数传给 Vitest；额外的 `--` 会让 Vitest
+# 把 maxWorkers 当作位置参数，导致并发限制不生效。
+RUN pnpm build
+
+# 运行阶段：仅保留构建产物和 Nginx，不包含源码或 node_modules。
+FROM ${NGINX_IMAGE}
+
+COPY nginx/default.conf.template /etc/nginx/templates/default.conf.template
+COPY docker/runtime-config.sh /docker-entrypoint.d/40-runtime-config.sh
+RUN chmod +x /docker-entrypoint.d/40-runtime-config.sh
+COPY --from=build /app/dist /usr/share/nginx/html
+
+EXPOSE 80
diff --git a/Jenkinsfile b/Jenkinsfile
new file mode 100644
index 00000000..0dec6ca3
--- /dev/null
+++ b/Jenkinsfile
@@ -0,0 +1,176 @@
+pipeline {
+  agent {
+    label "${env.JOB_BASE_NAME?.endsWith('-prod') ? 'java-builder' : (env.JOB_BASE_NAME?.endsWith('-dev') ? 'java-dev' : 'java-test')}"
+  }
+
+  environment {
+    DEVELOPMENT_COMPOSE_FILE = 'docker-compose.development.yml'
+    DEVELOPMENT_COMPOSE_PROJECT = 'admin-web'
+    REGISTRY_HOST = '172.31.198.7:10082'
+    REGISTRY_CREDENTIALS = 'gitea-registry-token'
+    NODE_BASE_IMAGE = '172.31.198.7:10082/java-project/node:22-alpine'
+    NGINX_BASE_IMAGE = '172.31.198.7:10082/java-project/nginx:1.27-alpine'
+    PRODUCTION_IMAGE_REPOSITORY = 'git.buggoglobal.com/html/admin-web'
+  }
+
+  options {
+    timestamps()
+    disableConcurrentBuilds()
+  }
+
+  stages {
+    stage('确认提交版本') {
+      steps {
+        script {
+          env.IS_DEVELOPMENT = env.JOB_BASE_NAME?.endsWith('-dev') ? 'true' : 'false'
+          env.IS_PRODUCTION = env.JOB_BASE_NAME?.endsWith('-prod') ? 'true' : 'false'
+          if (env.IS_PRODUCTION == 'true') {
+            sh '''
+              set -eu
+              git fetch --no-tags origin +refs/heads/main:refs/remotes/origin/main
+              test "$(git rev-parse HEAD)" = "$(git rev-parse origin/main)" || {
+                echo "生产部署只允许 origin/main 当前提交；请先合并代码到 main" >&2
+                exit 1
+              }
+            '''
+          }
+          env.SOURCE_TAG = sh(script: 'git rev-parse --short=12 HEAD', returnStdout: true).trim()
+        }
+        sh 'git log -1 --oneline'
+      }
+    }
+
+    stage('构建并部署测试前端') {
+      when { expression { env.IS_DEVELOPMENT != 'true' && env.IS_PRODUCTION != 'true' } }
+      steps {
+        withCredentials([usernamePassword(credentialsId: env.REGISTRY_CREDENTIALS, usernameVariable: 'REGISTRY_USER', passwordVariable: 'REGISTRY_PASSWORD')]) {
+          sh '''
+            set -eu
+            export DOCKER_CONFIG="${WORKSPACE}@tmp/docker-auth"
+            rm -rf "$DOCKER_CONFIG"
+            mkdir -p "$DOCKER_CONFIG"
+            cleanup_registry() {
+              docker logout "$REGISTRY_HOST" >/dev/null 2>&1 || true
+              rm -rf "$DOCKER_CONFIG"
+            }
+            trap cleanup_registry EXIT HUP INT TERM
+            printf %s "$REGISTRY_PASSWORD" | docker login -u "$REGISTRY_USER" --password-stdin "$REGISTRY_HOST"
+            docker compose -f docker-compose.test.yml build --pull=false
+            docker compose -f docker-compose.test.yml up -d --remove-orphans
+          '''
+        }
+      }
+    }
+
+    stage('构建并发布生产镜像') {
+      when { expression { env.IS_PRODUCTION == 'true' } }
+      steps {
+        withCredentials([usernamePassword(credentialsId: env.REGISTRY_CREDENTIALS, usernameVariable: 'REGISTRY_USER', passwordVariable: 'REGISTRY_PASSWORD')]) {
+          sh '''
+            set -eu
+            export DOCKER_CONFIG="${WORKSPACE}@tmp/docker-auth"
+            rm -rf "$DOCKER_CONFIG"
+            mkdir -p "$DOCKER_CONFIG"
+            cleanup_registry() {
+              docker logout git.buggoglobal.com >/dev/null 2>&1 || true
+              rm -rf "$DOCKER_CONFIG"
+            }
+            trap cleanup_registry EXIT HUP INT TERM
+            printf %s "$REGISTRY_PASSWORD" | docker login -u "$REGISTRY_USER" --password-stdin git.buggoglobal.com
+            image="$PRODUCTION_IMAGE_REPOSITORY:$SOURCE_TAG"
+            docker build \
+              --build-arg NODE_IMAGE="$NODE_BASE_IMAGE" \
+              --build-arg NGINX_IMAGE="$NGINX_BASE_IMAGE" \
+              --build-arg VITE_CLIENT_WEB_URL=https://app.buggoglobal.com/ \
+              -t "$image" .
+            docker push "$image"
+          '''
+        }
+      }
+    }
+
+    stage('确认部署生产前端') {
+      when { expression { env.IS_PRODUCTION == 'true' } }
+      steps {
+        input message: "确认将 main 提交 ${env.SOURCE_TAG} 部署到 admin.buggoglobal.com？", ok: '确认部署'
+      }
+    }
+
+    stage('部署生产前端') {
+      when { expression { env.IS_PRODUCTION == 'true' } }
+      steps {
+        lock(resource: 'firstleg-production-admin-web-deploy', inversePrecedence: true) {
+          withCredentials([
+            usernamePassword(credentialsId: 'gitea-production-pull-token', usernameVariable: 'REGISTRY_USER', passwordVariable: 'REGISTRY_PASSWORD'),
+            sshUserPrivateKey(credentialsId: 'firstleg-production-ssh', keyFileVariable: 'TARGET_SSH_KEY', usernameVariable: 'TARGET_SSH_USER'),
+            string(credentialsId: 'firstleg-production-host', variable: 'TARGET_SSH_HOST'),
+            file(credentialsId: 'firstleg-production-known-hosts', variable: 'TARGET_SSH_KNOWN_HOSTS')
+          ]) {
+            withEnv([
+              'TARGET_DEPLOY_DIR=/data/firstleg/deploy/frontend',
+              'TARGET_SSH_TARGET=' + env.TARGET_SSH_USER + '@' + env.TARGET_SSH_HOST
+            ]) {
+              sh "sh scripts/deploy-production.sh admin-web '${env.PRODUCTION_IMAGE_REPOSITORY}' '${env.SOURCE_TAG}' docker-compose.production.yml"
+            }
+          }
+        }
+      }
+    }
+
+    stage('构建并部署开发前端') {
+      when { expression { env.IS_DEVELOPMENT == 'true' } }
+      steps {
+        withCredentials([usernamePassword(credentialsId: env.REGISTRY_CREDENTIALS, usernameVariable: 'REGISTRY_USER', passwordVariable: 'REGISTRY_PASSWORD')]) {
+          sh '''
+            set -eu
+            export DOCKER_CONFIG="${WORKSPACE}@tmp/docker-auth"
+            rm -rf "$DOCKER_CONFIG"
+            mkdir -p "$DOCKER_CONFIG"
+            cleanup_registry() {
+              docker logout "$REGISTRY_HOST" >/dev/null 2>&1 || true
+              rm -rf "$DOCKER_CONFIG"
+            }
+            trap cleanup_registry EXIT HUP INT TERM
+            printf %s "$REGISTRY_PASSWORD" | docker login -u "$REGISTRY_USER" --password-stdin "$REGISTRY_HOST"
+            image="admin-web-development:${SOURCE_TAG}"
+
+            docker build \
+              --build-arg NODE_IMAGE="$NODE_BASE_IMAGE" \
+              --build-arg NGINX_IMAGE="$NGINX_BASE_IMAGE" \
+              --build-arg VITE_CLIENT_WEB_URL="${CLIENT_WEB_URL:-https://dev-app.buggoglobal.com/}" \
+              -t "$image" .
+            export IMAGE_TAG="$SOURCE_TAG"
+            docker compose -p "$DEVELOPMENT_COMPOSE_PROJECT" -f "$DEVELOPMENT_COMPOSE_FILE" up -d --remove-orphans --pull never
+            docker compose -p "$DEVELOPMENT_COMPOSE_PROJECT" -f "$DEVELOPMENT_COMPOSE_FILE" ps
+            docker compose -p "$DEVELOPMENT_COMPOSE_PROJECT" -f "$DEVELOPMENT_COMPOSE_FILE" exec -T admin-web wget -qO- http://127.0.0.1/healthz
+          '''
+        }
+      }
+    }
+
+    stage('部署检查') {
+      when { expression { env.IS_DEVELOPMENT != 'true' && env.IS_PRODUCTION != 'true' } }
+      steps {
+        sh '''
+          set -eu
+          docker compose -f docker-compose.test.yml ps
+          docker compose -f docker-compose.test.yml exec -T admin-web wget -qO- http://127.0.0.1/healthz
+        '''
+      }
+    }
+  }
+
+  post {
+    failure {
+      sh '''
+        if [ "${IS_PRODUCTION:-false}" = "true" ]; then
+          echo "生产部署失败，请查看上方远程部署日志"
+        elif [ "${IS_DEVELOPMENT:-false}" = "true" ]; then
+          docker logs --tail=100 admin-web-development || true
+        else
+          docker compose -f docker-compose.test.yml logs --tail=100 || true
+        fi
+      '''
+    }
+  }
+}
diff --git a/README.md b/README.md
index be666787..ab44a2fa 100644
--- a/README.md
+++ b/README.md
@@ -23,11 +23,21 @@ pnpm build
 pnpm test
 ```
 
+## 源码结构
+
+- `src/app/`：应用壳层、根路由和启动装配。
+- `src/core/`：认证、权限、导航、未保存工作保护等全应用基础能力。
+- `src/modules/`：按业务领域组织页面、接口、组件、类型和模块路由。
+- `src/shared/`：不依赖具体业务的 HTTP、基础组件和工具。
+- `src/prototype/`：尚未进入当前迭代的原型页面与路由，和正式业务代码隔离。
+
+新增业务页面时，在对应 `src/modules/<domain>/` 中就近放置页面、测试和领域能力，并从模块 `routes.ts` 导出路由片段；根路由只负责装配，菜单仍由 `src/core/navigation/adminNavigation.ts` 集中维护。跨模块调用必须经过模块根入口公开的 API，不能引用对方内部目录。
+
 依赖和 `pnpm-lock.yaml` 均保存在当前前端项目中，不需要在仓库根目录安装 Node 依赖。
 
-工作台已从一期路由与菜单移除；登录后按当前角色进入第一个有权限的业务页面。一期 Admin 路由聚焦登录、客户及注册审核、平台收货仓、快递公司、往来单位、头程订单、内部用户、角色管理和菜单权限。
+首页数据看板已作为无权限门槛的默认入口恢复，当前按照后台原型展示明确标注的静态演示数据，不请求业务接口；后续接入真实统计契约时应整体替换演示数据。历史通用占位页仍保留在 `src/prototype/`，但看板本身已迁入正式业务模块。订单与客户 Admin 其他正式路由聚焦登录、客户及注册审核、平台收货仓、快递公司、往来单位、头程订单、内部用户、角色管理和菜单权限；企业注册审核已合并到客户列表，不再保留独立菜单。
 
-后台菜单按“业务管理”和“系统管理”分组。企业审核、平台角色、菜单及按钮权限资源已接入真实 IAM 接口；客户档案、基础资料和部分系统管理页面仍使用 Pinia 模拟数据，不请求尚未确定的 Java 业务接口。
+后台一级菜单及原型内子菜单严格按最新版原型排序；原型未定义位置的现有功能统一归入“通用”。未接入的原型菜单保留为隐藏节点，待对应业务契约和权限码接入后再恢复展示。企业审核、仓库、头程订单、平台角色、菜单及按钮权限资源均接入真实接口；内部用户管理只维护平台员工账号，企业租户成员由商户成员边界管理。运行时不再提供本地演示业务数据或静态角色预览。
 
 ## 本地 Gateway 联调
 
@@ -35,26 +45,24 @@ pnpm test
 
 ```dotenv
 VITE_API_BASE_URL=/api
-API_PROXY_TARGET=http://192.168.110.149:9000
+API_PROXY_TARGET=http://localhost:9000
+VITE_OVERSEAS_API_BASE_URL=/overseas-api
+OVERSEAS_API_PROXY_TARGET=http://localhost:9300
+VITE_CLIENT_WEB_URL=http://localhost:5174
 ```
 
-认证请求使用 `/api/auth/**`，平台 IAM 请求使用 `/api/platform/v1/iam/**`。登录后从 JWT 读取平台身份和授权快照，再与 IAM 返回的启用权限资源取交集。企业审核调用 `/reviews`，打开审核详情后按租户调用 `/tenants/{tenantId}/qualifications`；营业执照通过 `/api/platform/v1/files/qualifications/{tenantId}/{fileName}` 携带平台 Token 临时读取，关闭预览后释放本地对象地址。平台角色调用 `/roles`，权限资源调用 `/permissions`；接口未提供的编辑、删除、启停和已有授权回显不会模拟成功。一期真实权限资源只创建 `MENU` 与 `BUTTON`，不创建 `PAGE` 或 `API` 类型。其余业务页面需在对应服务契约确认后逐项替换，生产逻辑不得静默回退到模拟数据。
+国内业务继续使用 `http` 和 `/api` 代理；海外业务统一使用 `overseasHttp` 和 `/overseas-api` 代理。Vite 会把 `/overseas-api/platform/...` 重写为海外 Gateway 的 `/api/platform/...`。海外 Token 的签发、缓存和会话刷新由统一认证层维护，业务模块不得读取 Token、手拼 `Authorization` 或复用国内 `http`。
 
-仓库管理当前维护义乌、深圳、青岛、上海、宁波、厦门等平台国内收货仓，支持筛选、新增、编辑和启停。停用仓库保留历史数据，但不再提供给客户新建头程订单选择；订单详情使用下单时保存的仓库编码、名称和地址快照，仓库主数据后续修改不改变历史展示。本阶段不包含 FBA/海外目的仓、库存、库位或出入库作业，快照仍为 Pinia 模拟数据，服务端持久化待接入。
+切换开发或测试环境时，只修改未提交的 `.env.local` 中 `API_PROXY_TARGET`、`OVERSEAS_API_PROXY_TARGET` 和 `VITE_CLIENT_WEB_URL`，然后重启 `pnpm dev`；无需修改业务代码。真实环境地址不写入受版本控制的配置模板或说明。
 
-快递公司和往来单位一期静态维护已完成：支持筛选、详情、新增、编辑、启停、唯一校验、标准模板下载和导入文件基础检查；往来单位支持六类多选角色、联系人和完整地址。两类主数据只导入不导出，导入只新增，任一行错误整批失败。工作表内容、模板版本、重复数据和整批事务必须由后端解析校验；接口提供前，前端不模拟校验或导入成功。头程订单可维护一组快递公司和快递单号；订单不设“已驳回”，后台修改待审核订单后仍保持待审核并写入审计。上述业务数据仍使用 Pinia，等待后端新架构明确契约后接入。
+客户代登录打开的工作台地址是运行时配置，不需要为每个环境重新构建镜像。Docker 部署时为 Admin 容器设置当前环境的 `CLIENT_WEB_URL`；容器启动时会生成 `/runtime-config.js`。开发、测试和生产分别在各自部署任务中注入自己的 Client 根地址，禁止复用其他环境的域名。本地 Vite 开发使用 `VITE_CLIENT_WEB_URL` 作为兜底。部署后可读取 `/runtime-config.js` 核对最终生效值。
+
+认证请求使用 `/api/auth/**`，平台 IAM 请求使用 `/api/platform/v1/iam/**`。登录后只从 JWT 读取平台身份，菜单和操作权限通过当前用户授权接口实时加载，不从 JWT 携带或解析角色权限。企业审核调用 `/reviews`，打开审核详情后按租户调用 `/tenants/{tenantId}/qualifications`；营业执照通过 `/api/platform/v1/files/qualifications/{tenantId}/{fileName}` 携带平台 Token 临时读取，关闭预览后释放本地对象地址。客户端自主注册企业审核通过后继续使用注册账号作为管理员，不展示新凭据；Admin 代建企业并由后端创建管理员时，页面必须展示不可通过遮罩、Esc 或关闭按钮跳过的一次性凭据弹窗，运营人员确认保存后才清除账号密码。平台角色查询、新增、编辑、启停、删除和权限全量保存均已按 `RbacController` 接入真实 `/roles` 契约，角色返回的 `permissionIds` 用于授权回显；系统内置角色及仍被成员使用的角色继续由服务端保护。权限资源查询和新增调用 `/permissions`，尚未提供的权限编辑、删除和启停不会模拟成功。订单与客户真实权限资源只创建 `MENU` 与 `BUTTON`，不创建 `PAGE` 或 `API` 类型。其余业务页面需在对应服务契约确认后逐项替换，生产逻辑不得静默回退到模拟数据。
+
+仓库管理已接入真实平台 Warehouse API，统一维护国内收货仓、FBA 仓和海外仓，支持按租户筛选、详情、新增、编辑和启停，并在更新时保留后端返回的地址、能力和截单时间等完整字段。停用仓库保留历史数据，但不再提供给新业务选择；订单详情使用下单时保存的仓库编码、名称和地址快照，仓库主数据后续修改不改变历史展示。库存和出入库作业由对应业务模块管理，不在仓库主数据页面中模拟。
+
+头程订单列表、详情、状态历史、内部备注和快递信息已经接入真实平台 Order API；订单不设“已驳回”，后台修改待审核订单后仍保持待审核并写入审计。快递公司已经接入 Warehouse Service 的真实分页查询、详情、新增、编辑、启停、标准模板下载和 XLSX 整批导入接口，按租户与平台权限访问；订单履约接口当前仍按公司名称和快递单号保存。平台往来单位已经接入 Warehouse Service 的真实分页、新增、编辑和启停接口，当前后端类型契约为客户、供应商及客户/供应商双重类型；批量导入接口尚未提供，不模拟导入成功。内部用户管理仅维护平台员工账号，已接入服务端分页查询、关键词与状态筛选、新增、编辑、平台角色调整、启停、最后登录展示和密码重置接口；账号凭据仍由 Auth Service 独占保存。
 
 真实接口错误会保留后端返回的业务错误码、`requestId` 和 `traceId`。登录、企业审核、平台角色及权限资源的主要失败态支持直接复制追踪标识，便于与后端日志关联。
 
-平台联调账号和密码只在 Vite 开发模式下预填，联调提示也只在开发模式显示。生产登录表单默认留空；生产构建产物不得包含本地联调账号、密码或开发提示文案。
-
-## 静态权限预览
-
-管理后台支持在顶栏切换本地角色，预览该角色可见的菜单、可访问页面和可用操作。预览角色保存在浏览器本地，刷新后继续保留；退出登录时清除，下次登录重新使用默认角色。
-
-该功能仅用于静态页面和交互验收：
-
-- 预览角色和演示业务数据来自本地 Pinia；真实登录会切换到服务端权限，并让已接入页面调用 Java 业务 API。
-- 当前不模拟角色的 `dataScope` 数据范围。
-- 菜单隐藏、页面拦截和操作禁用不能替代服务端鉴权。
-- 后续接入 Java 服务时，接口仍须独立校验登录身份、角色权限和数据范围。
+登录表单在开发和生产环境均默认留空，不包含联调账号、密码或演示提示。菜单、路由和操作权限只使用真实登录会话返回的服务端权限快照；前端控制仅改善体验，服务端仍须独立校验身份、角色权限和数据范围。接口失败时页面展示真实错误及追踪标识，不回退到假数据或模拟成功。
diff --git a/docker-compose.development.yml b/docker-compose.development.yml
new file mode 100644
index 00000000..a677b495
--- /dev/null
+++ b/docker-compose.development.yml
@@ -0,0 +1,22 @@
+services:
+  admin-web:
+    image: admin-web-development:${IMAGE_TAG:?IMAGE_TAG is required}
+    container_name: admin-web-development
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:9001:80"
+    environment:
+      CLIENT_WEB_URL: "${CLIENT_WEB_URL:-https://dev-app.buggoglobal.com/}"
+      API_UPSTREAM: "http://firstleg-development-gateway:9000"
+      OVERSEAS_API_UPSTREAM: "http://firstleg-development-gateway-overseas:9300"
+    networks:
+      - development-backend
+      - development-overseas-backend
+
+networks:
+  development-backend:
+    external: true
+    name: firstleg-development-network
+  development-overseas-backend:
+    external: true
+    name: firstleg-development-overseas-network
diff --git a/docker-compose.production.yml b/docker-compose.production.yml
new file mode 100644
index 00000000..580f3a59
--- /dev/null
+++ b/docker-compose.production.yml
@@ -0,0 +1,20 @@
+name: firstleg-prod-admin-web
+
+services:
+  admin-web:
+    image: ${IMAGE_REPOSITORY:?IMAGE_REPOSITORY is required}:${IMAGE_TAG:?IMAGE_TAG is required}
+    container_name: firstleg-prod-admin-web
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:${HOST_PORT:-9001}:80"
+    environment:
+      CLIENT_WEB_URL: "https://app.buggoglobal.com/"
+      API_UPSTREAM: "http://gateway:9000"
+      OVERSEAS_API_UPSTREAM: "http://gateway-overseas:9300"
+    networks:
+      - infra-network
+
+networks:
+  infra-network:
+    external: true
+    name: firstleg-prod-infra-network
diff --git a/docker-compose.test.yml b/docker-compose.test.yml
new file mode 100644
index 00000000..f522117c
--- /dev/null
+++ b/docker-compose.test.yml
@@ -0,0 +1,19 @@
+services:
+  admin-web:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      args:
+        NODE_IMAGE: "${NODE_BASE_IMAGE:-node:22-alpine}"
+        NGINX_IMAGE: "${NGINX_BASE_IMAGE:-nginx:1.27-alpine}"
+    image: admin-web-test:local
+    container_name: admin-web-test
+    restart: unless-stopped
+    ports:
+      - "${HOST_PORT:-9001}:80"
+    environment:
+      # Runtime URL used by the secure customer-workbench handoff. Each
+      # environment may override it without rebuilding the Admin image.
+      CLIENT_WEB_URL: "${CLIENT_WEB_URL:-https://test-app.buggoglobal.com/}"
+      API_UPSTREAM: "http://test-api-cn.buggoglobal.com"
+      OVERSEAS_API_UPSTREAM: "http://test-api-global.buggoglobal.com"
diff --git a/docker/runtime-config.sh b/docker/runtime-config.sh
new file mode 100644
index 00000000..9b699f84
--- /dev/null
+++ b/docker/runtime-config.sh
@@ -0,0 +1,7 @@
+#!/bin/sh
+set -eu
+
+runtime_file=/usr/share/nginx/html/runtime-config.js
+client_web_url=${CLIENT_WEB_URL:-}
+escaped_url=$(printf '%s' "$client_web_url" | sed 's/\\/\\\\/g; s/"/\\"/g; s/\r/\\r/g; s/\n/\\n/g')
+printf "window.__CHONGCHONG_RUNTIME_CONFIG__ = { clientWebUrl: \"%s\" }\n" "$escaped_url" > "$runtime_file"
diff --git a/index.html b/index.html
index 02879339..be740a3a 100644
--- a/index.html
+++ b/index.html
@@ -3,8 +3,10 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <meta name="description" content="虫虫出海管理后台" />
-    <title>虫虫出海管理后台</title>
+    <meta name="description" content="柏悦物流管理后台" />
+    <link rel="icon" type="image/png" href="/src/assets/brand/baiyue-favicon.png" />
+    <title>柏悦物流管理后台</title>
+    <script src="/runtime-config.js"></script>
   </head>
   <body>
     <div id="app"></div>
@@ -12,3 +14,4 @@
   </body>
 </html>
 
+
diff --git a/nginx/default.conf.template b/nginx/default.conf.template
new file mode 100644
index 00000000..3688b5f7
--- /dev/null
+++ b/nginx/default.conf.template
@@ -0,0 +1,65 @@
+server {
+    listen 80;
+    listen [::]:80;
+    server_name _;
+
+    root /usr/share/nginx/html;
+    index index.html;
+
+    # Docker 容器运行正常的检查地址，供 Jenkins 使用。
+    location = /healthz {
+        default_type text/plain;
+        return 200 "ok\n";
+    }
+
+    location = /runtime-config.js {
+        add_header Cache-Control "no-cache, no-store, must-revalidate" always;
+        add_header Pragma "no-cache" always;
+        add_header Expires "0" always;
+        try_files $uri =404;
+    }
+
+    # 前端代码中的 API 前缀为 /api；保持原始路径转给 Gateway。
+    location /api/ {
+        client_max_body_size 55m;
+        proxy_pass ${API_UPSTREAM};
+        proxy_http_version 1.1;
+        proxy_set_header Host $proxy_host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    # 海外业务使用独立 Gateway；将浏览器前缀改写为 Gateway 的 /api 前缀。
+    location /overseas-api/ {
+        client_max_body_size 55m;
+        rewrite ^/overseas-api/(.*)$ /api/$1 break;
+        proxy_pass ${OVERSEAS_API_UPSTREAM};
+        proxy_http_version 1.1;
+        proxy_set_header Host $proxy_host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    # HTML must be revalidated on every visit so a new deployment cannot keep
+    # referencing hashed chunks that were removed with the previous image.
+    location = /index.html {
+        add_header Cache-Control "no-cache, no-store, must-revalidate" always;
+        add_header Pragma "no-cache" always;
+        add_header Expires "0" always;
+    }
+
+    # Vite assets are content-hashed and safe to cache permanently. Missing
+    # chunks must remain a real 404 instead of falling back to index.html.
+    location /assets/ {
+        try_files $uri =404;
+        add_header Cache-Control "public, max-age=31536000, immutable" always;
+    }
+
+    # Vue Router 的 history 路由刷新时仍返回 index.html。
+    location / {
+        try_files $uri $uri/ /index.html;
+        add_header Cache-Control "no-cache" always;
+    }
+}
diff --git a/package.json b/package.json
index 00477f9f..c5494404 100644
--- a/package.json
+++ b/package.json
@@ -8,19 +8,23 @@
     "build": "vue-tsc --noEmit && vite build",
     "typecheck": "vue-tsc --noEmit",
     "test": "vitest run",
+    "test:phase4:development": "node scripts/phase4-development-frontend-acceptance.mjs",
     "preview": "vite preview --port 4173"
   },
   "dependencies": {
-    "@chongchong/shared": "link:../../packages/shared",
+    "@chongchong/shared": "link:./shared",
     "@lucide/vue": "^1.27.0",
     "axios": "^1.18.1",
+    "dayjs": "^1.11.21",
     "element-plus": "^2.14.3",
     "pinia": "^4.0.2",
+    "sortablejs": "^1.15.7",
     "vue": "^3.5.40",
     "vue-router": "^5.2.0"
   },
   "devDependencies": {
     "@types/node": "^24.10.0",
+    "@types/sortablejs": "^1.15.9",
     "@vitejs/plugin-vue": "^6.0.8",
     "@vue/test-utils": "^2.4.11",
     "jsdom": "^29.1.1",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index cb5157c9..88a48763 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -9,20 +9,26 @@ importers:
   .:
     dependencies:
       '@chongchong/shared':
-        specifier: link:../../packages/shared
-        version: link:../../packages/shared
+        specifier: link:./shared
+        version: link:./shared
       '@lucide/vue':
         specifier: ^1.27.0
         version: 1.27.0(vue@3.5.40(typescript@5.9.3))
       axios:
         specifier: ^1.18.1
         version: 1.18.1(debug@4.4.3)
+      dayjs:
+        specifier: ^1.11.21
+        version: 1.11.21
       element-plus:
         specifier: ^2.14.3
         version: 2.14.3(vue@3.5.40(typescript@5.9.3))
       pinia:
         specifier: ^4.0.2
         version: 4.0.2(@vue/devtools-api@8.2.1)(typescript@5.9.3)(vue@3.5.40(typescript@5.9.3))
+      sortablejs:
+        specifier: ^1.15.7
+        version: 1.15.7
       vue:
         specifier: ^3.5.40
         version: 3.5.40(typescript@5.9.3)
@@ -33,6 +39,9 @@ importers:
       '@types/node':
         specifier: ^24.10.0
         version: 24.13.3
+      '@types/sortablejs':
+        specifier: ^1.15.9
+        version: 1.15.9
       '@vitejs/plugin-vue':
         specifier: ^6.0.8
         version: 6.0.8(vite@8.1.5(@types/node@24.13.3)(yaml@2.9.0))(vue@3.5.40(typescript@5.9.3))
@@ -361,6 +370,9 @@ packages:
   '@types/node@24.13.3':
     resolution: {integrity: sha512-Dh8vAsV36ig5wa9OX4pXvMc9D3Veibfw2wix0CUwYODLD8nkj9UsLjASr49nPg+2eKzxhBV+v7L8pXvT4e639Q==}
 
+  '@types/sortablejs@1.15.9':
+    resolution: {integrity: sha512-7HP+rZGE2p886PKV9c9OJzLBI6BBJu1O7lJGYnPyG3fS4/duUCcngkNCjsLwIMV+WMqANe3tt4irrXHSIe68OQ==}
+
   '@types/web-bluetooth@0.0.21':
     resolution: {integrity: sha512-oIQLCGWtcFZy2JW77j9k8nHzAOpqMHLQejDA48XXMWH6tjCQHz5RCFz1bzsmROyL6PUm+LLnUiI4BCn221inxA==}
 
@@ -1073,6 +1085,9 @@ packages:
     resolution: {integrity: sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==}
     engines: {node: '>=14'}
 
+  sortablejs@1.15.7:
+    resolution: {integrity: sha512-Kk8wLQPlS+yi1ZEf48a4+fzHa4yxjC30M/Sr2AnQu+f/MPwvvX9XjZ6OWejiz8crBsLwSq8GHqaxaET7u6ux0A==}
+
   source-map-js@1.2.1:
     resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==}
     engines: {node: '>=0.10.0'}
@@ -1638,6 +1653,8 @@ snapshots:
     dependencies:
       undici-types: 7.18.2
 
+  '@types/sortablejs@1.15.9': {}
+
   '@types/web-bluetooth@0.0.21': {}
 
   '@vitejs/plugin-vue@6.0.8(vite@8.1.5(@types/node@24.13.3)(yaml@2.9.0))(vue@3.5.40(typescript@5.9.3))':
@@ -2360,6 +2377,8 @@ snapshots:
 
   signal-exit@4.1.0: {}
 
+  sortablejs@1.15.7: {}
+
   source-map-js@1.2.1: {}
 
   stackback@0.0.2: {}
diff --git a/public/runtime-config.js b/public/runtime-config.js
new file mode 100644
index 00000000..9a482f5d
--- /dev/null
+++ b/public/runtime-config.js
@@ -0,0 +1 @@
+window.__CHONGCHONG_RUNTIME_CONFIG__ = window.__CHONGCHONG_RUNTIME_CONFIG__ || { clientWebUrl: '' }
diff --git a/public/templates/counterparties-import-template.xlsx b/public/templates/counterparties-import-template.xlsx
deleted file mode 100644
index 3e5a8bc9..00000000
Binary files a/public/templates/counterparties-import-template.xlsx and /dev/null differ
diff --git a/public/templates/express-companies-import-template.xlsx b/public/templates/express-companies-import-template.xlsx
deleted file mode 100644
index 5b2d267f..00000000
Binary files a/public/templates/express-companies-import-template.xlsx and /dev/null differ
diff --git a/scripts/deploy-production.sh b/scripts/deploy-production.sh
new file mode 100644
index 00000000..821a7116
--- /dev/null
+++ b/scripts/deploy-production.sh
@@ -0,0 +1,93 @@
+#!/usr/bin/env sh
+set -eu
+
+if [ "$#" -ne 4 ]; then
+  echo "用法: $0 <服务名> <镜像仓库> <镜像标签> <Compose 文件>" >&2
+  exit 2
+fi
+
+SERVICE="$1"
+IMAGE_REPOSITORY="$2"
+IMAGE_TAG="$3"
+COMPOSE_FILE="$4"
+IMAGE="$IMAGE_REPOSITORY:$IMAGE_TAG"
+REGISTRY_HOST="${IMAGE_REPOSITORY%%/*}"
+SSH_TARGET="${TARGET_SSH_TARGET:?TARGET_SSH_TARGET 未设置}"
+SSH_KEY="${TARGET_SSH_KEY:?TARGET_SSH_KEY 未设置}"
+SSH_KNOWN_HOSTS="${TARGET_SSH_KNOWN_HOSTS:?TARGET_SSH_KNOWN_HOSTS 未设置}"
+REMOTE_DIR="${TARGET_DEPLOY_DIR:?TARGET_DEPLOY_DIR 未设置}"
+: "${REGISTRY_USER:?REGISTRY_USER 未设置}"
+: "${REGISTRY_PASSWORD:?REGISTRY_PASSWORD 未设置}"
+
+run_ssh() {
+  ssh -i "$SSH_KEY" -o BatchMode=yes -o StrictHostKeyChecking=yes \
+    -o UserKnownHostsFile="$SSH_KNOWN_HOSTS" -o ConnectTimeout=10 "$SSH_TARGET" "$@"
+}
+
+run_scp() {
+  scp -i "$SSH_KEY" -o BatchMode=yes -o StrictHostKeyChecking=yes \
+    -o UserKnownHostsFile="$SSH_KNOWN_HOSTS" -o ConnectTimeout=10 "$@"
+}
+
+run_ssh install -d -m 750 "$REMOTE_DIR"
+REMOTE_COMPOSE="$REMOTE_DIR/docker-compose.$SERVICE.yml"
+run_scp "$COMPOSE_FILE" "$SSH_TARGET:$REMOTE_COMPOSE.tmp"
+run_ssh sh -s -- "$REMOTE_COMPOSE.tmp" "$REMOTE_COMPOSE" <<'REMOTE_PREPARE'
+set -eu
+compose_tmp="$1"
+compose_target="$2"
+chmod 644 "$compose_tmp"
+mv -f "$compose_tmp" "$compose_target"
+REMOTE_PREPARE
+
+printf '%s' "$REGISTRY_PASSWORD" | run_ssh docker login -u "$REGISTRY_USER" --password-stdin "$REGISTRY_HOST"
+trap 'run_ssh docker logout "$REGISTRY_HOST" >/dev/null 2>&1 || true' EXIT HUP INT TERM
+run_ssh docker pull "$IMAGE"
+
+run_ssh sh -s -- "$REMOTE_DIR" "$SERVICE" "$IMAGE_REPOSITORY" "$IMAGE_TAG" <<'REMOTE_DEPLOY'
+set -eu
+remote_dir="$1"
+service="$2"
+image_repository="$3"
+image_tag="$4"
+compose_file="docker-compose.$service.yml"
+project_name="firstleg-prod-$service"
+cd "$remote_dir"
+export IMAGE_REPOSITORY="$image_repository" IMAGE_TAG="$image_tag"
+
+compose() {
+  docker compose --project-name "$project_name" -f "$compose_file" "$@"
+}
+
+container_id="$(compose ps --all --quiet "$service" | head -n 1)"
+previous_image=""
+if [ -n "$container_id" ]; then
+  previous_image="$(docker inspect --format '{{.Config.Image}}' "$container_id")"
+fi
+
+if compose up -d --no-deps --pull never "$service" && \
+   compose exec -T "$service" wget -qO- http://127.0.0.1/healthz >/dev/null; then
+  echo "生产前端部署成功: $image_repository:$image_tag"
+  compose ps "$service"
+  exit 0
+fi
+
+echo "生产前端健康检查失败，准备回滚" >&2
+compose logs --tail=100 "$service" >&2 || true
+case "$previous_image" in
+  "$image_repository:"*) ;;
+  '') echo "首次部署无旧镜像可回滚" >&2; exit 1 ;;
+  *) echo "旧镜像不属于当前应用，拒绝回滚: $previous_image" >&2; exit 1 ;;
+esac
+previous_tag="${previous_image#"$image_repository:"}"
+if [ "$previous_tag" = "$image_tag" ]; then
+  echo "旧镜像与新镜像一致，无法回滚" >&2
+  exit 1
+fi
+docker pull "$previous_image"
+export IMAGE_TAG="$previous_tag"
+compose up -d --no-deps --pull never "$service"
+compose exec -T "$service" wget -qO- http://127.0.0.1/healthz >/dev/null || true
+echo "已回滚至: $previous_image" >&2
+exit 1
+REMOTE_DEPLOY
diff --git a/scripts/phase4-development-frontend-acceptance.mjs b/scripts/phase4-development-frontend-acceptance.mjs
new file mode 100644
index 00000000..7321b557
--- /dev/null
+++ b/scripts/phase4-development-frontend-acceptance.mjs
@@ -0,0 +1,49 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+
+function option(name) {
+  const index = process.argv.indexOf(name)
+  return index >= 0 ? process.argv[index + 1] : ''
+}
+
+function normalizeOrigin(value, name) {
+  if (!value) throw new Error(`缺少 ${name}`)
+  const url = new URL(value)
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.pathname !== '/') {
+    throw new Error(`${name} 必须是无账号、无路径的 HTTP(S) origin`)
+  }
+  return url.origin
+}
+
+function acceptancePassword() {
+  if (process.env.CHONGCHONG_ADMIN_ACCEPTANCE_PASSWORD) return process.env.CHONGCHONG_ADMIN_ACCEPTANCE_PASSWORD
+  const file = 'C:/Users/BY-OY/.codex/chongchong-global-dev-acceptance.env'
+  if (!existsSync(file)) return ''
+  const match = readFileSync(file, 'utf8').match(/^CHONGCHONG_ADMIN_ACCEPTANCE_PASSWORD=(.*)$/m)
+  return match?.[1]?.trim() || ''
+}
+
+const environment = option('--environment')
+if (environment !== 'development') throw new Error('本入口仅允许显式指定 --environment development')
+const gateway = normalizeOrigin(option('--gateway') || process.env.ADMIN_DEVELOPMENT_GATEWAY, '--gateway')
+const overseasGateway = normalizeOrigin(option('--overseas-gateway') || process.env.ADMIN_DEVELOPMENT_OVERSEAS_GATEWAY, '--overseas-gateway')
+const password = acceptancePassword()
+if (!password) throw new Error('缺少 CHONGCHONG_ADMIN_ACCEPTANCE_PASSWORD 或本机开发验收凭据文件')
+
+const result = spawnSync('pnpm', ['exec', 'vitest', 'run', '--config', 'vitest.phase4-development.config.ts'], {
+  cwd: process.cwd(),
+  stdio: 'inherit',
+  shell: process.platform === 'win32',
+  env: {
+    ...process.env,
+    ADMIN_PHASE4_LIVE: '1',
+    ADMIN_ACCEPTANCE_USERNAME: process.env.ADMIN_ACCEPTANCE_USERNAME || 'platform_admin',
+    ADMIN_ACCEPTANCE_PASSWORD: password,
+    ADMIN_DEVELOPMENT_GATEWAY: gateway,
+    ADMIN_DEVELOPMENT_OVERSEAS_GATEWAY: overseasGateway,
+    VITE_API_BASE_URL: `${gateway}/api`,
+    VITE_OVERSEAS_API_BASE_URL: `${overseasGateway}/api`,
+  },
+})
+if (result.error) throw result.error
+process.exit(result.status ?? 1)
diff --git a/scripts/phase4-development-frontend-contract.test.mjs b/scripts/phase4-development-frontend-contract.test.mjs
new file mode 100644
index 00000000..04f14f9e
--- /dev/null
+++ b/scripts/phase4-development-frontend-contract.test.mjs
@@ -0,0 +1,34 @@
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import test from 'node:test'
+
+const runner = readFileSync(new URL('./phase4-development-frontend-acceptance.mjs', import.meta.url), 'utf8')
+const suite = readFileSync(new URL('./phase4-development-frontend.acceptance.ts', import.meta.url), 'utf8')
+
+test('development runner requires an explicit development environment and gateways', () => {
+  assert.match(runner, /--environment/)
+  assert.match(runner, /environment !== 'development'/)
+  assert.match(runner, /--gateway/)
+  assert.match(runner, /--overseas-gateway/)
+  assert.match(runner, /shell: process\.platform === 'win32'/)
+  assert.match(runner, /if \(result\.error\) throw result\.error/)
+  assert.doesNotMatch(runner, /ADMIN_ACCEPTANCE_PASSWORD\s*[:=]\s*['"][^'"]+['"]/)
+})
+
+test('live suite uses production auth clients and domain adapters', () => {
+  assert.match(suite, /useAuthStore/)
+  assert.match(suite, /clearOverseasAccessToken/)
+  assert.match(suite, /createQuote/)
+  assert.match(suite, /createUsTruckOrder/)
+  assert.match(suite, /createLocalLooseboardOrder/)
+  assert.match(suite, /listLastMileOrders/)
+  assert.match(suite, /listDispatchCandidates/)
+  assert.match(suite, /listCarrierScheduleQueries/)
+})
+
+test('live suite owns marker resources and redacts credentials from trace reports', () => {
+  assert.match(suite, /ADMIN-FRONT-P4-/)
+  assert.match(suite, /password\|token\|authorization/i)
+  assert.match(suite, /createdResources/)
+  assert.match(suite, /coverageGaps/)
+})
diff --git a/scripts/phase4-development-frontend.acceptance.ts b/scripts/phase4-development-frontend.acceptance.ts
new file mode 100644
index 00000000..2a9bb088
--- /dev/null
+++ b/scripts/phase4-development-frontend.acceptance.ts
@@ -0,0 +1,395 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import axios, { type AxiosInstance, type InternalAxiosRequestConfig } from 'axios'
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { createPinia, setActivePinia } from 'pinia'
+import { createMemoryHistory, createRouter } from 'vue-router'
+import { defineComponent, nextTick } from 'vue'
+import { mount, type VueWrapper } from '@vue/test-utils'
+import ElementPlus from 'element-plus'
+import { http, ApiResponseError } from '@/shared/api/http'
+import { clearOverseasAccessToken, overseasHttp } from '@/shared/api/overseasHttp'
+import { useAuthStore } from '@/core/auth/auth'
+import { listPlatformTenants } from '@/modules/iam/api/platformIam'
+import {
+  changeExchangeRateStatus, changeQuoteStatus, changeVehicleStatus, createExchangeRate, createQuote, createVehicle,
+  exportExchangeRates, exportQuotes, exportVehicles, getExchangeRate, getQuote, getVehicle, listExchangeRates,
+  listQuoteWarehouseOptions, listQuotes, listVehicles, updateExchangeRate, updateQuote, updateVehicle,
+} from '@/modules/overseas-master-data/api/overseasMasterData'
+import {
+  createLocalLooseboardOrder, createUsTruckOrder, getLocalLooseboardOrder, getUsTruckOrder,
+  listLocalLooseboardOrders, listOverseasPurchaseCustomerOptions, listOverseasPurchases,
+  listOverseasPurchaseWarehouseOptions, listUsTruckOrders, updateLocalLooseboardOrder, updateUsTruckOrder,
+} from '@/modules/overseas-business/api/platformOverseasBusiness'
+import { listLastMileOrders, getLastMileOrder } from '@/modules/overseas-warehouse/api/lastMileOrders'
+import { listInboundOrders } from '@/modules/overseas-warehouse/api/inboundOrders'
+import { getInboundPlan } from '@/modules/overseas-warehouse/api/inboundPlans'
+import { listDispatchCandidates, listDispatchDrafts, listDispatches } from '@/modules/overseas-warehouse/api/dispatches'
+import { getInventorySummary, listInventoryBalances, listInventoryLedger, listInventoryPositions } from '@/modules/overseas-warehouse/api/inventory'
+import { createPallet, getPallet, listCustomerWarehouses, listPallets, updatePallet } from '@/modules/overseas-warehouse/api/pallets'
+import { listRelabelOrders } from '@/modules/overseas-warehouse/api/relabelOrders'
+import { getCarrierScheduleQuery, listCarrierScheduleQueries } from '@/modules/port-schedules/api/platformCarrierScheduleQueries'
+import OverseasQuotesView from '@/modules/overseas-master-data/pages/OverseasQuotesView.vue'
+import PurchaseOrdersView from '@/modules/overseas-business/pages/PurchaseOrdersView.vue'
+import TransportOrdersView from '@/modules/overseas-business/pages/TransportOrdersView.vue'
+import LastMileOrdersView from '@/modules/overseas-warehouse/pages/LastMileOrdersView.vue'
+import InboundOrdersView from '@/modules/overseas-warehouse/pages/InboundOrdersView.vue'
+import InventoryView from '@/modules/overseas-warehouse/pages/InventoryView.vue'
+import DispatchesView from '@/modules/overseas-warehouse/pages/DispatchesView.vue'
+import RelabelOrdersView from '@/modules/overseas-warehouse/pages/RelabelOrdersView.vue'
+import OutboundsView from '@/modules/overseas-warehouse/pages/OutboundsView.vue'
+import DeliveryOrdersView from '@/modules/overseas-warehouse/pages/DeliveryOrdersView.vue'
+import ExceptionOrdersView from '@/modules/overseas-warehouse/pages/ExceptionOrdersView.vue'
+import CustomerVisitsView from '@/modules/overseas-warehouse/pages/CustomerVisitsView.vue'
+import InventoryTransactionsView from '@/modules/overseas-warehouse/pages/InventoryTransactionsView.vue'
+import PalletsView from '@/modules/overseas-warehouse/pages/PalletsView.vue'
+import QueryToolbar from '@/shared/components/QueryToolbar.vue'
+
+type Region = 'domestic' | 'overseas'
+interface TraceStep { region: Region; method: string; path: string; params: unknown; body: unknown; httpStatus: number; code?: string; requestId?: string; traceId?: string; authorization: boolean }
+interface CoverageGap { area: string; reason: string }
+
+const enabled = process.env.ADMIN_PHASE4_LIVE === '1'
+const marker = `ADMIN-FRONT-P4-${new Date().toISOString().replace(/\D/g, '').slice(0, 14)}`
+const traces: TraceStep[] = []
+const coverageGaps: CoverageGap[] = []
+const createdResources: Record<string, unknown> = {}
+const wrappers: VueWrapper[] = []
+
+function redact(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(redact)
+  if (!value || typeof value !== 'object') return value
+  return Object.fromEntries(Object.entries(value as Record<string, unknown>).map(([key, item]) => [key, /password|token|authorization/i.test(key) ? '[REDACTED]' : redact(item)]))
+}
+function parsed(value: unknown) {
+  if (typeof value !== 'string') return value
+  try { return JSON.parse(value) } catch { return value }
+}
+function envelope(value: unknown) {
+  const body = parsed(value) as { code?: unknown; requestId?: unknown; traceId?: unknown } | null
+  return body && typeof body === 'object' ? body : null
+}
+function installTracingAdapter(client: AxiosInstance, region: Region) {
+  const nodeAdapter = axios.getAdapter('http')
+  client.defaults.adapter = async (config: InternalAxiosRequestConfig) => {
+    try {
+      const response = await nodeAdapter(config)
+      const body = envelope(response.data)
+      traces.push({ region, method: String(config.method || 'GET').toUpperCase(), path: String(config.url || ''), params: redact(config.params), body: redact(parsed(config.data)), httpStatus: response.status, code: body?.code == null ? undefined : String(body.code), requestId: body?.requestId == null ? undefined : String(body.requestId), traceId: body?.traceId == null ? undefined : String(body.traceId), authorization: Boolean(config.headers?.Authorization) })
+      return response
+    } catch (error) {
+      if (axios.isAxiosError(error)) {
+        const body = envelope(error.response?.data)
+        traces.push({ region, method: String(config.method || 'GET').toUpperCase(), path: String(config.url || ''), params: redact(config.params), body: redact(parsed(config.data)), httpStatus: error.response?.status || 0, code: body?.code == null ? undefined : String(body.code), requestId: body?.requestId == null ? undefined : String(body.requestId), traceId: body?.traceId == null ? undefined : String(body.traceId), authorization: Boolean(config.headers?.Authorization) })
+      }
+      throw error
+    }
+  }
+}
+function gap(area: string, reason: string) { coverageGaps.push({ area, reason }) }
+function numericId(value: unknown) { return /^[1-9]\d*$/.test(String(value ?? '')) }
+function expectPage(value: { records: unknown[]; page: number; size: number; total: number; pages: number }) {
+  expect(Array.isArray(value.records)).toBe(true); expect(value.page).toBeGreaterThanOrEqual(1); expect(value.size).toBeGreaterThan(0); expect(value.total).toBeGreaterThanOrEqual(value.records.length); expect(value.pages).toBeGreaterThanOrEqual(0)
+}
+async function expectConflict(action: () => Promise<unknown>) {
+  await expect(action()).rejects.toSatisfy((error: unknown) => {
+    if (error instanceof ApiResponseError) return error.code.endsWith('409')
+    if (!axios.isAxiosError(error)) return false
+    const response = parsed(error.response?.data) as { code?: unknown } | undefined
+    return error.response?.status === 409 || String(response?.code || '').endsWith('409')
+  })
+}
+function futureDate(days: number) { return new Date(Date.now() + days * 86_400_000).toISOString().slice(0, 10) }
+
+async function masterDataLifecycle() {
+  const options = await listQuoteWarehouseOptions()
+  const quotePage = await listQuotes({ page: 1, size: 20 })
+  expectPage(quotePage)
+  if (options.length) {
+    const quote = await createQuote({ name: `${marker} 报价`, warehouseId: options[0].warehouseId, providerName: `${marker} Provider`, currency: 'USD', effectiveStart: '2098-01-01', effectiveEnd: '2098-12-31', versionCode: marker.slice(-32), warehouseFees: [{ item: 'Storage QA', billingUnit: 'PALLET', unitPrice: 1.25, minimumCharge: 2.5, remark: marker }], transitPrices: [], remark: marker })
+    const id = quote.summary.id
+    createdResources.quote = id
+    let detail = await getQuote(id)
+    const stale = detail.summary.recordVersion
+    detail = await updateQuote(id, { recordVersion: stale, name: `${marker} 报价-编辑`, providerName: detail.summary.providerName, currency: detail.summary.currency, effectiveStart: detail.summary.effectiveStart, effectiveEnd: detail.summary.effectiveEnd || '2098-12-31', warehouseFees: detail.warehouseFees, transitPrices: detail.transitPrices, remark: `${marker} edited` })
+    await expectConflict(() => updateQuote(id, { recordVersion: stale, name: 'STALE', providerName: detail.summary.providerName, currency: detail.summary.currency, effectiveStart: detail.summary.effectiveStart, effectiveEnd: detail.summary.effectiveEnd || '2098-12-31', warehouseFees: detail.warehouseFees, transitPrices: detail.transitPrices, remark: marker }))
+    detail = await changeQuoteStatus(id, 'ACTIVE', detail.summary.recordVersion)
+    expect(detail.summary.status).toBe('ACTIVE')
+    expect((await exportQuotes({ keyword: marker })).size).toBeGreaterThan(0)
+    detail = await changeQuoteStatus(id, 'INACTIVE', detail.summary.recordVersion)
+    expect(detail.summary.status).toBe('INACTIVE')
+  } else gap('海外报价', 'warehouse-options 为空，未猜测仓库 ID，跳过报价写生命周期')
+
+  let exchangeMonth = ''
+  for (let index = 0; index < 24 && !exchangeMonth; index += 1) {
+    const month = `${2097 + Math.floor(index / 12)}-${String(index % 12 + 1).padStart(2, '0')}`
+    const page = await listExchangeRates({ page: 1, size: 20, monthFrom: month, monthTo: month })
+    if (!page.total) exchangeMonth = month
+  }
+  if (!exchangeMonth) throw new Error('安全汇率月份池已占满')
+  let rate = await createExchangeRate({ month: exchangeMonth, usdToCnyAverage: 7.123456, remark: marker })
+  createdResources.exchangeRate = exchangeMonth
+  const staleRate = rate.recordVersion
+  rate = await updateExchangeRate(exchangeMonth, { recordVersion: staleRate, usdToCnyAverage: 7.234567, remark: `${marker} edited` })
+  await expectConflict(() => updateExchangeRate(exchangeMonth, { recordVersion: staleRate, usdToCnyAverage: 7.9, remark: 'STALE' }))
+  rate = await getExchangeRate(exchangeMonth)
+  rate = await changeExchangeRateStatus(exchangeMonth, 'INACTIVE', rate.recordVersion, `${marker} cleanup`)
+  expect(rate.status).toBe('INACTIVE')
+  expect((await exportExchangeRates({ monthFrom: exchangeMonth, monthTo: exchangeMonth })).size).toBeGreaterThan(0)
+
+  let vehicle = await createVehicle({ plateNumber: `QA-${marker.slice(-18)}`, model: 'Phase4 Front QA', fuelConsumptionPer100Km: 18.5, mileageKm: 100, driverOrDispatchCompany: marker, phone: '+1-213-555-0188', region: 'OVERSEAS', ownership: 'OWNED', status: 'IN_SERVICE', remark: marker })
+  createdResources.vehicle = vehicle.id
+  const staleVehicle = vehicle.recordVersion
+  vehicle = await updateVehicle(vehicle.id, { recordVersion: staleVehicle, plateNumber: vehicle.plateNumber, model: 'Phase4 Front QA Edited', fuelConsumptionPer100Km: 18.75, mileageKm: 101, driverOrDispatchCompany: marker, phone: vehicle.phone, region: vehicle.region, ownership: vehicle.ownership, remark: `${marker} edited` })
+  await expectConflict(() => updateVehicle(vehicle.id, { recordVersion: staleVehicle, plateNumber: vehicle.plateNumber, model: 'STALE', fuelConsumptionPer100Km: 19, mileageKm: 102, driverOrDispatchCompany: marker, phone: vehicle.phone, region: vehicle.region, ownership: vehicle.ownership, remark: 'STALE' }))
+  vehicle = await getVehicle(vehicle.id)
+  vehicle = await changeVehicleStatus(vehicle.id, 'INACTIVE', vehicle.recordVersion)
+  expect(vehicle.status).toBe('INACTIVE')
+  expect((await exportVehicles({ keyword: vehicle.plateNumber })).size).toBeGreaterThan(0)
+  expectPage(await listVehicles({ page: 1, size: 20, keyword: marker }))
+}
+
+async function cleanupTransport(path: string, customerId: string, version: number) {
+  await overseasHttp.patch(`${path}/status`, { version, status: 'CANCELLED', remark: `${marker} cleanup` }, { params: { customerId } })
+}
+async function overseasBusinessLifecycle() {
+  const customers = (await listPlatformTenants({ page: 1, size: 200, status: 'ACTIVE' })).records.filter(item => item.status === 'ACTIVE')
+  const active = customers.find(item => numericId(item.id))
+  if (!active) { gap('卡车/散板', 'IAM 无 ACTIVE 客户'); return }
+  const customerId = String(active.id)
+  expect(Array.isArray(await listOverseasPurchaseCustomerOptions())).toBe(true)
+  expect(Array.isArray(await listOverseasPurchaseWarehouseOptions())).toBe(true)
+  expectPage(await listOverseasPurchases({ page: 1, size: 20 }))
+  const common = { origin: `${marker}-ORIGIN`, originAddress: 'Long Beach', destination: `${marker}-DEST`, destinationAddress: 'Ontario', containerType: '40HQ', packageCount: 2, totalWeightKg: 100, totalVolumeCbm: 2.5, budgetAmount: 88, currency: 'USD', contactName: '四期前端验收', contactInfo: '13800000000', requestedDate: futureDate(7), remark: marker }
+  let truck = await createUsTruckOrder(customerId, { ...common, transportType: 'PORT_PICKUP', palletCount: 1, idempotencyKey: `${marker}-truck` })
+  createdResources.truck = truck.orderNo
+  try {
+    truck = await getUsTruckOrder(truck.orderNo, customerId)
+    const stale = truck.version
+    truck = await updateUsTruckOrder(truck.orderNo, customerId, { ...common, transportType: 'PORT_PICKUP', palletCount: 1, destination: `${marker}-DEST-EDIT`, version: stale })
+    await expectConflict(() => updateUsTruckOrder(truck.orderNo, customerId, { ...common, transportType: 'PORT_PICKUP', palletCount: 1, destination: 'STALE', version: stale }))
+  } finally {
+    truck = await getUsTruckOrder(truck.orderNo, customerId)
+    if (truck.status === 'PENDING_REVIEW') await cleanupTransport(`/platform/v1/last-leg/us-truck-orders/${encodeURIComponent(truck.orderNo)}`, customerId, truck.version)
+  }
+  expectPage(await listUsTruckOrders({ page: 1, size: 20, customerId }))
+
+  let loose = await createLocalLooseboardOrder(customerId, { transportMode: 'SHARED_TRUCK', palletRequired: 'YES', transportType: 'WAREHOUSE_TO_WAREHOUSE', ...common, idempotencyKey: `${marker}-looseboard` })
+  createdResources.looseboard = loose.orderNo
+  try {
+    loose = await getLocalLooseboardOrder(loose.orderNo, customerId)
+    const stale = loose.version
+    loose = await updateLocalLooseboardOrder(loose.orderNo, customerId, { transportMode: loose.transportMode, palletRequired: loose.palletRequired, transportType: loose.transportType, ...common, destination: `${marker}-DEST-EDIT`, version: stale })
+    await expectConflict(() => updateLocalLooseboardOrder(loose.orderNo, customerId, { transportMode: loose.transportMode, palletRequired: loose.palletRequired, transportType: loose.transportType, ...common, destination: 'STALE', version: stale }))
+  } finally {
+    loose = await getLocalLooseboardOrder(loose.orderNo, customerId)
+    if (loose.status === 'PENDING_ACCEPTANCE') await cleanupTransport(`/platform/v1/last-leg/local-looseboard-orders/${encodeURIComponent(loose.orderNo)}`, customerId, loose.version)
+  }
+  expectPage(await listLocalLooseboardOrders({ page: 1, size: 20, customerId }))
+}
+
+async function overseasWarehouseCoverage() {
+  const lastMile = await listLastMileOrders({ page: 1, size: 20 }); expectPage(lastMile)
+  if (lastMile.records[0]) await getLastMileOrder(String(lastMile.records[0].id))
+  const inbound = await listInboundOrders({ page: 1, size: 20 }); expectPage(inbound)
+  if (inbound.records[0]) await getInboundPlan(inbound.records[0].planNo, inbound.records[0].customerId)
+  expectPage(await listDispatches({ page: 1, size: 20 }))
+  expect(Array.isArray(await listDispatchCandidates({}))).toBe(true)
+  expect(Array.isArray(await listDispatchDrafts())).toBe(true)
+  const inventoryQuery = { page: 1, size: 20 }
+  const balances = await listInventoryBalances(inventoryQuery); expectPage(balances)
+  await getInventorySummary(inventoryQuery)
+  await listInventoryLedger({ page: 1, size: 20 })
+  if (balances.records[0]) await listInventoryPositions(String(balances.records[0].id), 1, 20)
+  expectPage(await listRelabelOrders({ page: 1, size: 20 }))
+  const warehouses = (await listCustomerWarehouses()).records.filter(item => item.status === 'ACTIVE')
+  if (!warehouses.length) { gap('公共托盘', '实际海外仓为空，跳过前端托盘写生命周期'); return }
+  const warehouse = warehouses[0]
+  const payload = { palletCode: `QA-${marker.slice(-20)}`, palletType: 'STANDARD', fbaWarehouseCode: 'ONT8', capacityCbm: 2.5, unitPrice: 10, status: 'IDLE', remark: marker }
+  const palletId = await createPallet(warehouse.id, payload)
+  createdResources.pallet = palletId
+  try {
+    const pallet = await getPallet(warehouse.id, palletId)
+    await updatePallet(warehouse.id, palletId, { ...payload, capacityCbm: 2.75, remark: `${marker} edited`, version: pallet.version })
+    await expectConflict(() => updatePallet(warehouse.id, palletId, { ...payload, capacityCbm: 3, remark: 'STALE', version: pallet.version }))
+    expectPage(await listPallets(warehouse.id, { page: 1, size: 20, keyword: payload.palletCode }))
+  }
+  finally {
+    const current = await getPallet(warehouse.id, palletId)
+    if (current.status !== 'SCRAPPED') await updatePallet(warehouse.id, palletId, { ...payload, status: 'SCRAPPED', remark: `${marker} cleanup`, version: current.version })
+  }
+  gap('FBA预约/智能预排/换标新增', '没有本轮 marker 入仓计划和托盘候选；为避免操作历史数据，本轮只自动覆盖列表、详情、候选和草稿查询')
+}
+
+async function carrierCoverage() {
+  const page = await listCarrierScheduleQueries({ page: 1, size: 20 })
+  expectPage(page)
+  if (page.records[0]) await getCarrierScheduleQuery(page.records[0].query.id)
+  else gap('船节点人工补录', '环境无真实查询任务；未创建或修改历史任务')
+}
+
+async function waitForTrace(method: string, path: string, start: number) {
+  const deadline = Date.now() + 20_000
+  while (Date.now() < deadline) {
+    if (traces.slice(start).some(item => item.method === method && item.path.startsWith(path))) return
+    await new Promise(resolve => setTimeout(resolve, 50))
+  }
+  throw new Error(`页面未发出 ${method} ${path}`)
+}
+async function mountPage(component: Parameters<typeof mount>[0], method: string, path: string, props?: Record<string, unknown>) {
+  const start = traces.length
+  const router = createRouter({ history: createMemoryHistory(), routes: [{ path: '/:pathMatch(.*)*', component: defineComponent({ template: '<div />' }) }] })
+  await router.push('/'); await router.isReady()
+  const wrapper = mount(component, { attachTo: document.body, props, global: { plugins: [ElementPlus, router, setActivePinia(createPinia())] } })
+  wrappers.push(wrapper)
+  await waitForTrace(method, path, start)
+  await nextTick()
+  expect(wrapper.text()).not.toContain('服务暂时不可用')
+  return wrapper
+}
+async function exerciseListSearch(
+  wrapper: VueWrapper,
+  path: string,
+  model: Record<string, unknown>,
+  expectedParams: Record<string, unknown>,
+) {
+  const toolbar = wrapper.findComponent(QueryToolbar)
+  expect(toolbar.exists()).toBe(true)
+  toolbar.vm.$emit('update:modelValue', { ...model })
+  await nextTick()
+  let start = traces.length
+  toolbar.vm.$emit('search', { ...model })
+  await waitForTrace('GET', path, start)
+  const searchRequests = traces.slice(start).filter(item => item.method === 'GET' && item.path === path)
+  expect(searchRequests).toHaveLength(1)
+  expect(searchRequests[0]?.httpStatus).toBe(200)
+  expect(searchRequests[0]?.params).toMatchObject(expectedParams)
+  expect(wrapper.text()).not.toContain('加载失败')
+
+  start = traces.length
+  ;(toolbar.vm as unknown as { reset(): void }).reset()
+  await waitForTrace('GET', path, start)
+  const resetRequests = traces.slice(start).filter(item => item.method === 'GET' && item.path === path)
+  expect(resetRequests).toHaveLength(1)
+  expect(resetRequests[0]?.httpStatus).toBe(200)
+  const resetParams = resetRequests[0]?.params as Record<string, unknown> | undefined
+  for (const key of Object.keys(expectedParams)) expect(resetParams?.[key] == null || resetParams[key] === '').toBe(true)
+ }
+async function pageRequestCoverage() {
+  const quotes = await mountPage(OverseasQuotesView, 'GET', '/platform/v1/last-leg/master-data/overseas-quotes')
+  await exerciseListSearch(quotes, '/platform/v1/last-leg/master-data/overseas-quotes',
+    { keyword: `${marker}-NO-MATCH`, warehouseId: '', providerName: `${marker}-PROVIDER`, currency: 'USD', status: 'INACTIVE' },
+    { keyword: `${marker}-NO-MATCH`, providerName: `${marker}-PROVIDER`, currency: 'USD', status: 'INACTIVE' })
+
+  const purchases = await mountPage(PurchaseOrdersView, 'GET', '/platform/v1/last-leg/overseas-procurements')
+  await exerciseListSearch(purchases, '/platform/v1/last-leg/overseas-procurements',
+    { orderNo: `${marker}-NO-MATCH`, customerId: '', purchaseCategory: `${marker}-CATEGORY`, productName: `${marker}-PRODUCT` },
+    { orderNo: `${marker}-NO-MATCH`, purchaseCategory: `${marker}-CATEGORY`, productName: `${marker}-PRODUCT` })
+
+  const trucks = await mountPage(TransportOrdersView, 'GET', '/platform/v1/last-leg/us-truck-orders', { domain: 'truck' })
+  await exerciseListSearch(trucks, '/platform/v1/last-leg/us-truck-orders',
+    { status: 'CANCELLED', routeKeyword: `${marker}-NO-MATCH` },
+    { status: 'CANCELLED', routeKeyword: `${marker}-NO-MATCH` })
+
+  const looseboards = await mountPage(TransportOrdersView, 'GET', '/platform/v1/last-leg/local-looseboard-orders', { domain: 'looseboard' })
+  await exerciseListSearch(looseboards, '/platform/v1/last-leg/local-looseboard-orders',
+    { status: 'CANCELLED', routeKeyword: `${marker}-NO-MATCH` },
+    { status: 'CANCELLED', routeKeyword: `${marker}-NO-MATCH` })
+
+  const lastMile = await mountPage(LastMileOrdersView, 'GET', '/platform/v1/last-leg/orders')
+  await exerciseListSearch(lastMile, '/platform/v1/last-leg/orders',
+    { orderNo: `${marker}-ORDER`, inboundCode: `${marker}-INBOUND`, lxCode: `${marker}-LX`, orderType: 'FIRST_LEG', warehouse: `${marker}-WAREHOUSE`, sourceOrderNo: `${marker}-SOURCE`, containerNo: `${marker}-CONTAINER`, transferWarehouseCode: `${marker}-TRANSFER`, status: 'DELIVERED', abnormal: 'true', detained: 'false', createdAt: ['2098-01-01', '2098-01-02'] },
+    { orderNo: `${marker}-ORDER`, inboundCode: `${marker}-INBOUND`, lxCode: `${marker}-LX`, orderType: 'FIRST_LEG', warehouse: `${marker}-WAREHOUSE`, sourceOrderNo: `${marker}-SOURCE`, containerNo: `${marker}-CONTAINER`, transferWarehouseCode: `${marker}-TRANSFER`, currentStatus: 'DELIVERED', abnormal: true, detained: false, createdFrom: '2098-01-01T00:00:00', createdTo: '2098-01-02T23:59:59' })
+  let start = traces.length
+  await lastMile.findAll('.el-radio-button').find(item => item.text() === '待分配')!.trigger('click')
+  await waitForTrace('GET', '/platform/v1/last-leg/orders', start)
+  start = traces.length
+  await lastMile.findAll('.el-radio-button').find(item => item.text().startsWith('柜子'))!.trigger('click')
+  await waitForTrace('GET', '/platform/v1/last-leg/orders/container-summaries', start)
+  start = traces.length
+  await lastMile.findAll('.el-radio-button').find(item => item.text() === '全部')!.trigger('click')
+  await waitForTrace('GET', '/platform/v1/last-leg/orders', start)
+
+  const inbounds = await mountPage(InboundOrdersView, 'GET', '/platform/v1/last-leg/inbound-plans')
+  await exerciseListSearch(inbounds, '/platform/v1/last-leg/inbound-plans',
+    { orderNo: `${marker}-PLAN`, inboundCode: `${marker}-INBOUND`, lxCode: `${marker}-LX`, status: 'COMPLETED', warehouse: `${marker}-WAREHOUSE`, fbaWarehouse: `${marker}-FBA`, appointmentStatus: 'CANCELLED', dispatchStatus: 'SCHEDULED', inboundDate: ['2098-01-01', '2098-01-02'] },
+    { planNo: `${marker}-PLAN`, inboundCode: `${marker}-INBOUND`, lxCode: `${marker}-LX`, status: 'COMPLETED', warehouse: `${marker}-WAREHOUSE`, fbaWarehouseCode: `${marker}-FBA`, appointmentStatus: 'CANCELLED', dispatchStatus: 'SCHEDULED', createdFrom: '2098-01-01T00:00:00', createdTo: '2098-01-02T23:59:59' })
+
+  const inventory = await mountPage(InventoryView, 'GET', '/platform/v1/last-leg/inventory/balances')
+  await exerciseListSearch(inventory, '/platform/v1/last-leg/inventory/balances',
+    { warehouseId: '', owner: `${marker}-OWNER`, sku: `${marker}-SKU`, productName: `${marker}-PRODUCT`, batchNo: `${marker}-BATCH`, location: `${marker}-LOCATION`, status: 'AVAILABLE' },
+    { customerName: `${marker}-OWNER`, skuCode: `${marker}-SKU`, productName: `${marker}-PRODUCT`, batchNo: `${marker}-BATCH`, warehouseLocationCode: `${marker}-LOCATION`, inventoryStatus: 'AVAILABLE' })
+
+  const dispatches = await mountPage(DispatchesView, 'GET', '/platform/v1/last-leg/dispatches')
+  await exerciseListSearch(dispatches, '/platform/v1/last-leg/dispatches',
+    { dispatchNo: `${marker}-DISPATCH`, vehiclePlate: `${marker}-PLATE`, status: 'CANCELLED', fbaAppointmentNo: `${marker}-APPOINTMENT` },
+    { dispatchNo: `${marker}-DISPATCH`, vehiclePlate: `${marker}-PLATE`, status: 'CANCELLED', fbaAppointmentNo: `${marker}-APPOINTMENT` })
+
+  const relabels = await mountPage(RelabelOrdersView, 'GET', '/platform/v1/last-leg/relabel-applications')
+  await exerciseListSearch(relabels, '/platform/v1/last-leg/relabel-applications',
+    { relabelNo: `${marker}-RELABEL`, sku: `${marker}-SKU`, status: 'CANCELLED' },
+    { relabelNo: `${marker}-RELABEL`, skuCode: `${marker}-SKU`, status: 'CANCELLED' })
+
+  const outbounds = await mountPage(OutboundsView, 'GET', '/platform/v1/last-leg/outbound-orders')
+  await exerciseListSearch(outbounds, '/platform/v1/last-leg/outbound-orders',
+    { documentNo: `${marker}-OUTBOUND`, lxCode: `${marker}-LX`, warehouseId: `${marker}-WAREHOUSE`, status: 'OUTBOUNDED' },
+    { documentNo: `${marker}-OUTBOUND`, lxCode: `${marker}-LX`, warehouseId: `${marker}-WAREHOUSE`, status: 'OUTBOUNDED' })
+
+  const deliveries = await mountPage(DeliveryOrdersView, 'GET', '/platform/v1/last-leg/delivery-orders')
+  await exerciseListSearch(deliveries, '/platform/v1/last-leg/delivery-orders',
+    { documentNo: `${marker}-DELIVERY`, dispatchNo: `${marker}-DISPATCH`, waybillNo: `${marker}-WAYBILL`, warehouseId: '', status: 'CANCELLED', vehiclePlate: `${marker}-PLATE`, driverName: `${marker}-DRIVER`, deliveryMethod: 'EXPRESS', plannedAt: ['2098-01-01', '2098-01-02'] },
+    { documentNo: `${marker}-DELIVERY`, dispatchNo: `${marker}-DISPATCH`, waybillNo: `${marker}-WAYBILL`, status: 'CANCELLED', vehiclePlate: `${marker}-PLATE`, driverName: `${marker}-DRIVER`, deliveryMethod: 'EXPRESS', plannedFrom: '2098-01-01T00:00:00', plannedTo: '2098-01-02T23:59:59' })
+
+  const exceptions = await mountPage(ExceptionOrdersView, 'GET', '/platform/v1/last-leg/exception-orders')
+  await exerciseListSearch(exceptions, '/platform/v1/last-leg/exception-orders',
+    { keyword: `${marker}-EXCEPTION`, exceptionType: 'OTHER', status: 'COMPLETED' },
+    { keyword: `${marker}-EXCEPTION`, exceptionType: 'OTHER', status: 'COMPLETED' })
+
+  const visits = await mountPage(CustomerVisitsView, 'GET', '/platform/v1/last-leg/customer-visits')
+  await exerciseListSearch(visits, '/platform/v1/last-leg/customer-visits',
+    { keyword: `${marker}-VISIT`, status: 'COMPLETED', completedAt: ['2098-01-01', '2098-01-02'] },
+    { keyword: `${marker}-VISIT`, status: 'COMPLETED', completedFrom: '2098-01-01T00:00:00', completedTo: '2098-01-02T23:59:59' })
+
+  const ledger = await mountPage(InventoryTransactionsView, 'GET', '/platform/v1/last-leg/inventory/ledger')
+  await exerciseListSearch(ledger, '/platform/v1/last-leg/inventory/ledger',
+    { occurredDate: ['2098-01-01', '2098-01-02'], customerName: `${marker}-CUSTOMER`, warehouse: `${marker}-WAREHOUSE`, sku: `${marker}-SKU`, businessType: 'ADJUST', businessOrderNo: `${marker}-BUSINESS`, inboundCode: `${marker}-INBOUND`, inboundOrderNo: `${marker}-INBOUND-ORDER`, outboundOrderNo: `${marker}-OUTBOUND` },
+    { customerName: `${marker}-CUSTOMER`, destinationWarehouseCode: `${marker}-WAREHOUSE`, skuCode: `${marker}-SKU`, businessType: 'ADJUST', businessOrderNo: `${marker}-BUSINESS`, inboundCode: `${marker}-INBOUND`, inboundOrderNo: `${marker}-INBOUND-ORDER`, outboundOrderNo: `${marker}-OUTBOUND`, occurredFrom: '2098-01-01T00:00:00', occurredTo: '2098-01-02T23:59:59' })
+
+  const pallets = await mountPage(PalletsView, 'GET', '/platform/v1/warehouse-admin/pallets')
+  await exerciseListSearch(pallets, '/platform/v1/warehouse-admin/pallets',
+    { warehouseId: '', code: `${marker}-PALLET`, type: 'WOOD', status: 'IDLE' },
+    { keyword: `${marker}-PALLET`, palletType: 'WOOD', status: 'IDLE' })
+}
+
+describe.skipIf(!enabled).sequential('phase4 development frontend acceptance', () => {
+  beforeAll(async () => {
+    Object.defineProperty(window, 'matchMedia', { writable: true, value: () => ({ matches: false, addEventListener() {}, removeEventListener() {} }) })
+    globalThis.ResizeObserver = class { observe() {}; unobserve() {}; disconnect() {} }
+    installTracingAdapter(http, 'domestic'); installTracingAdapter(overseasHttp, 'overseas')
+    const pinia = createPinia(); setActivePinia(pinia)
+    const auth = useAuthStore(pinia)
+    await auth.login(process.env.ADMIN_ACCEPTANCE_USERNAME || 'platform_admin', process.env.ADMIN_ACCEPTANCE_PASSWORD || '')
+    expect(localStorage.getItem('cc-admin-token')).toBeTruthy()
+    clearOverseasAccessToken()
+    await listVehicles({ page: 1, size: 1 })
+    expect(traces.some(item => item.region === 'domestic' && item.path === '/auth/refresh')).toBe(true)
+    expect(traces.some(item => item.region === 'overseas' && item.authorization)).toBe(true)
+  })
+  it('runs marker-owned adapter lifecycles and real page requests', async () => {
+    await masterDataLifecycle()
+    await overseasBusinessLifecycle()
+    await overseasWarehouseCoverage()
+    await carrierCoverage()
+    await pageRequestCoverage()
+    expect(traces.length).toBeGreaterThan(20)
+  })
+  afterAll(() => {
+    wrappers.splice(0).forEach(wrapper => wrapper.unmount())
+    const reportDir = resolve(process.cwd(), 'reports')
+    mkdirSync(reportDir, { recursive: true })
+    const report = { generatedAt: new Date().toISOString(), marker, summary: { requests: traces.length, coverageGaps: coverageGaps.length }, traces, coverageGaps, createdResources }
+    const file = resolve(reportDir, `phase4-frontend-development-${marker.replace(/[^A-Za-z0-9-]/g, '')}.json`)
+    writeFileSync(file, `${JSON.stringify(report, null, 2)}\n`, 'utf8')
+    console.info(`PHASE4_FRONTEND_REPORT=${file}`)
+  })
+})
diff --git a/shared/AGENTS.md b/shared/AGENTS.md
new file mode 100644
index 00000000..2421437e
--- /dev/null
+++ b/shared/AGENTS.md
@@ -0,0 +1,30 @@
+# 应用内 Shared Package Instructions
+
+## 项目定位
+
+- 本包只服务当前前端应用，提供多个业务模块共同使用的 TypeScript 类型、常量和轻量工具。
+- 依赖保持为 `@chongchong/shared: link:./shared`，确保当前应用目录可作为独立容器构建上下文。
+- 不承担 Admin、Client 之间的源码复用；跨应用字段需要分别映射同一份 Java Controller/OpenAPI 契约，不能通过目录外链接耦合两个部署单元。
+
+## 公共 API 与依赖边界
+
+- `src/index.ts` 是当前唯一公共入口；模块专属页面状态、UI 组件和临时业务逻辑留在对应模块。
+- 共享类型保持前端平台无关，不编码鉴权结论；租户隔离、权限、状态机和数据合法性由 `baiyue-firstleg` Java 服务端最终保证。
+- 服务端字段变化先核对 Controller、DTO 和 OpenAPI，再更新本应用的类型、API 适配层和测试；本包不反向定义服务端行为。
+- 避免建立宽泛的万能类型或引入重量级依赖。
+
+## 订单与客户/入库测量与计费/国内货柜履约共享模型索引
+
+- 订单与客户共享消费者：`customers`、`iam`、`warehouses`、`master-data`、`first-leg-orders`；稳定导出集中在 `src/index.ts`（用户、导航、响应、仓库摘要、订单状态）。
+- 入库测量与计费共享消费者：`inbounds`、`warehouse-resources`、`fba-pricing`、`dimension-config`、`unified-orders`；单模块使用的测量、费用、托盘、库位类型留在模块内，只有真实跨模块复用才新增导出。
+- 国内货柜履约仅在服务端字段、权限和 OpenAPI 已稳定，且确有多个 Admin 模块复用时才新增共享导出；先读 `../../../docs/国内货柜履约/国内货柜履约开工门禁.md`。订单、柜次、证据和报关的单模块类型仍留在所属模块，不在 shared 预留猜测字段。
+
+定位规则：先在 `src/index.ts` 确认公共导出，再搜索 `src/` 消费者；后端字段或状态有疑问时回到对应 Controller/DTO/OpenAPI，不在 shared 中猜测业务规则。
+
+阶段依据（路径相对本文件所在目录）：订单与客户 `../../../docs/订单与客户/`，入库测量与计费 `../../../docs/入库测量与计费/`，国内货柜履约 `../../../docs/国内货柜履约/`；共享包不保存阶段进度，也不承载跨应用（Client）源码复用。
+
+## 契约与验证
+
+- 修改导出名称、字段类型、枚举值或常量语义前，搜索当前应用内全部消费者。
+- 当前开发阶段按目标模型直接修改；破坏性修改必须同步更新当前应用全部消费者、测试和接口映射，不保留旧模型兼容分支。
+- 本包没有独立质量脚本；变更后运行父应用声明的类型检查、测试或构建命令。
diff --git a/shared/README.md b/shared/README.md
new file mode 100644
index 00000000..fdc627de
--- /dev/null
+++ b/shared/README.md
@@ -0,0 +1,5 @@
+# 应用内共享模块
+
+本目录存放当前前端应用多个业务模块共同使用的 TypeScript 类型、常量和轻量工具，通过 `@chongchong/shared: link:./shared` 引用。
+
+该目录必须保留在应用内部，以支持 Admin、Client 分别使用自身目录作为容器构建上下文。它不作为 Java 服务端契约来源；接口字段、状态机、权限和业务规则以 `baiyue-firstleg` Controller、DTO 和 OpenAPI 为准。
diff --git a/shared/package.json b/shared/package.json
new file mode 100644
index 00000000..5e802c2d
--- /dev/null
+++ b/shared/package.json
@@ -0,0 +1,11 @@
+{
+  "name": "@chongchong/shared",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "types": "./src/index.ts"
+}
+
diff --git a/shared/src/index.ts b/shared/src/index.ts
new file mode 100644
index 00000000..5bf0aef9
--- /dev/null
+++ b/shared/src/index.ts
@@ -0,0 +1,155 @@
+export const PRODUCT_NAME = '虫虫出海'
+
+const MAX_SAFE_INTEGER = BigInt(Number.MAX_SAFE_INTEGER)
+
+function quoteUnsafeIntegerTokens(source: string) {
+  let output = ''
+  let index = 0
+  let inString = false
+  let escaped = false
+
+  while (index < source.length) {
+    const character = source[index]
+
+    if (inString) {
+      output += character
+      if (escaped) escaped = false
+      else if (character === '\\') escaped = true
+      else if (character === '"') inString = false
+      index += 1
+      continue
+    }
+
+    if (character === '"') {
+      inString = true
+      output += character
+      index += 1
+      continue
+    }
+
+    if (character === '-' || (character >= '0' && character <= '9')) {
+      const token = source.slice(index).match(/^-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/)?.[0]
+      if (token) {
+        const isInteger = !token.includes('.') && !/[eE]/.test(token)
+        if (isInteger && (BigInt(token) > MAX_SAFE_INTEGER || BigInt(token) < -MAX_SAFE_INTEGER)) output += JSON.stringify(token)
+        else output += token
+        index += token.length
+        continue
+      }
+    }
+
+    output += character
+    index += 1
+  }
+
+  return output
+}
+
+export function parseJsonWithSafeIntegers(source: string) {
+  return JSON.parse(quoteUnsafeIntegerTokens(source)) as unknown
+}
+
+export function parseApiJsonResponse(data: unknown) {
+  if (typeof data !== 'string') return data
+  const trimmed = data.trim()
+  if (!trimmed || (!trimmed.startsWith('{') && !trimmed.startsWith('['))) return data
+  try {
+    return parseJsonWithSafeIntegers(data)
+  } catch {
+    return data
+  }
+}
+
+export type AppCode = 'admin' | 'client'
+
+export interface CurrentUser {
+  id: string
+  name: string
+  account: string
+  tenantName?: string
+  roles: string[]
+}
+
+export interface NavigationItem {
+  path: string
+  title: string
+  permission?: string
+}
+
+export interface ApiResponse<T> {
+  code: number
+  message: string
+  data: T
+}
+
+export const FIRST_LEG_ORDER_STATUSES = [
+  { code: 'DRAFT', label: '草稿' },
+  { code: 'PENDING_REVIEW', label: '待审核' },
+  { code: 'ACCEPTED', label: '已受理' },
+  { code: 'BOOKED', label: '已订舱' },
+  { code: 'IN_TRANSIT', label: '运输中' },
+  { code: 'COMPLETED', label: '已完成' },
+  { code: 'CANCELLED', label: '已取消' },
+] as const
+
+export type FirstLegOrderStatus = (typeof FIRST_LEG_ORDER_STATUSES)[number]['code']
+export type FirstLegOrderStatusLabel = (typeof FIRST_LEG_ORDER_STATUSES)[number]['label']
+
+export const FIRST_LEG_TRANSPORT_MODES = [
+  { code: 'FCL', label: '海运整箱 FCL' },
+  { code: 'LCL', label: '海运拼箱 LCL' },
+  { code: 'AIR', label: '空运' },
+  { code: 'ROAD', label: '陆运' },
+] as const
+
+export type FirstLegTransportMode = (typeof FIRST_LEG_TRANSPORT_MODES)[number]['code']
+export type FirstLegTransportModeLabel = (typeof FIRST_LEG_TRANSPORT_MODES)[number]['label']
+
+export type PlatformWarehouseStatus = 'ACTIVE' | 'INACTIVE'
+
+export interface PlatformReceivingWarehouse {
+  id: string
+  code: string
+  name: string
+  province: string
+  city: string
+  address: string
+  contactName: string
+  contactPhone: string
+  businessHours: string
+  status: PlatformWarehouseStatus
+  remark: string
+  updatedAt: string
+}
+
+export interface PlatformReceivingWarehouseSnapshot {
+  id: string
+  code: string
+  name: string
+  province: string
+  city: string
+  address: string
+}
+
+export function createPlatformReceivingWarehouseSnapshot(
+  warehouse: PlatformReceivingWarehouse,
+): PlatformReceivingWarehouseSnapshot {
+  return {
+    id: warehouse.id,
+    code: warehouse.code,
+    name: warehouse.name,
+    province: warehouse.province,
+    city: warehouse.city,
+    address: warehouse.address,
+  }
+}
+
+// API 接入前供 Admin 与 Client 静态原型共用，不能作为服务端真实仓库数据。
+export const DEMO_PLATFORM_RECEIVING_WAREHOUSES: readonly PlatformReceivingWarehouse[] = [
+  { id: 'WH001', code: 'CN-YW-01', name: '义乌仓', province: '浙江省', city: '义乌市', address: '北苑街道演示物流园 1 号库', contactName: '仓库客服', contactPhone: '0579-****001', businessHours: '周一至周六 08:30-18:00', status: 'ACTIVE', remark: '支持普通货物收货。', updatedAt: '2026-07-28 10:20' },
+  { id: 'WH002', code: 'CN-SZ-01', name: '深圳仓', province: '广东省', city: '深圳市', address: '盐田区演示物流园 2 号库', contactName: '仓库客服', contactPhone: '0755-****002', businessHours: '周一至周六 08:30-18:00', status: 'ACTIVE', remark: '华南区域主要收货仓。', updatedAt: '2026-07-28 10:20' },
+  { id: 'WH003', code: 'CN-QD-01', name: '青岛仓', province: '山东省', city: '青岛市', address: '黄岛区演示物流园 3 号库', contactName: '仓库客服', contactPhone: '0532-****003', businessHours: '周一至周五 09:00-17:30', status: 'ACTIVE', remark: '', updatedAt: '2026-07-28 10:20' },
+  { id: 'WH004', code: 'CN-SH-01', name: '上海仓', province: '上海市', city: '上海市', address: '浦东新区演示物流园 4 号库', contactName: '仓库客服', contactPhone: '021-****004', businessHours: '周一至周六 08:30-18:00', status: 'ACTIVE', remark: '华东区域综合收货仓。', updatedAt: '2026-07-28 10:20' },
+  { id: 'WH005', code: 'CN-NB-01', name: '宁波仓', province: '浙江省', city: '宁波市', address: '北仑区演示物流园 5 号库', contactName: '仓库客服', contactPhone: '0574-****005', businessHours: '周一至周六 08:30-18:00', status: 'ACTIVE', remark: '临近宁波港。', updatedAt: '2026-07-28 10:20' },
+  { id: 'WH006', code: 'CN-XM-01', name: '厦门仓', province: '福建省', city: '厦门市', address: '湖里区演示物流园 6 号库', contactName: '仓库客服', contactPhone: '0592-****006', businessHours: '周一至周五 09:00-17:30', status: 'INACTIVE', remark: '静态演示：暂停接收新订单。', updatedAt: '2026-07-28 10:20' },
+]
diff --git a/src/App.test.ts b/src/App.test.ts
new file mode 100644
index 00000000..7f423a1d
--- /dev/null
+++ b/src/App.test.ts
@@ -0,0 +1,15 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import zhCn from 'element-plus/es/locale/lang/zh-cn'
+
+describe('Admin Element Plus locale', () => {
+  it('provides simplified Chinese globally', () => {
+    const source = readFileSync(join(process.cwd(), 'src/App.vue'), 'utf8')
+
+    expect(zhCn.name).toBe('zh-cn')
+    expect(source).toContain("import zhCn from 'element-plus/es/locale/lang/zh-cn'")
+    expect(source).toContain('<ElConfigProvider :locale="zhCn">')
+    expect(source).toMatch(/<ElConfigProvider[\s\S]*<RouterView \/>[\s\S]*<\/ElConfigProvider>/)
+  })
+})
diff --git a/src/App.vue b/src/App.vue
index 4be89653..1210025e 100644
--- a/src/App.vue
+++ b/src/App.vue
@@ -1,4 +1,10 @@
-<template>
-  <RouterView />
-</template>
+<script setup lang="ts">
+import { ElConfigProvider } from 'element-plus'
+import zhCn from 'element-plus/es/locale/lang/zh-cn'
+</script>
 
+<template>
+  <ElConfigProvider :locale="zhCn">
+    <RouterView />
+  </ElConfigProvider>
+</template>
diff --git a/src/api/http.test.ts b/src/api/http.test.ts
deleted file mode 100644
index cbee3a30..00000000
--- a/src/api/http.test.ts
+++ /dev/null
@@ -1,43 +0,0 @@
-import axios, { AxiosHeaders } from 'axios'
-import { describe, expect, it } from 'vitest'
-import { ApiResponseError, getApiErrorDetails, unwrapApiResponse } from './http'
-
-describe('API error diagnostics', () => {
-  it('keeps business request and trace identifiers when unwrapping fails', () => {
-    expect(() => unwrapApiResponse({
-      code: 'A0403',
-      message: '无权限',
-      data: null,
-      requestId: 'request-1',
-      traceId: 'trace-1',
-    })).toThrow(ApiResponseError)
-
-    try {
-      unwrapApiResponse({ code: 'A0403', message: '无权限', data: null, requestId: 'request-1', traceId: 'trace-1' })
-    } catch (error) {
-      expect(getApiErrorDetails(error)).toEqual({
-        message: '无权限',
-        code: 'A0403',
-        requestId: 'request-1',
-        traceId: 'trace-1',
-      })
-    }
-  })
-
-  it('extracts identifiers from an HTTP error envelope', () => {
-    const error = new axios.AxiosError('Request failed', 'ERR_BAD_RESPONSE', undefined, undefined, {
-      status: 503,
-      statusText: 'Service Unavailable',
-      headers: {},
-      config: { headers: new AxiosHeaders() },
-      data: { code: 'S0503', message: '服务不可用', requestId: 'request-2', traceId: 'trace-2' },
-    })
-
-    expect(getApiErrorDetails(error)).toEqual({
-      message: '服务不可用',
-      code: 'S0503',
-      requestId: 'request-2',
-      traceId: 'trace-2',
-    })
-  })
-})
diff --git a/src/api/http.ts b/src/api/http.ts
deleted file mode 100644
index 87552097..00000000
--- a/src/api/http.ts
+++ /dev/null
@@ -1,121 +0,0 @@
-import axios, { type InternalAxiosRequestConfig } from 'axios'
-
-export interface ApiEnvelope<T> {
-  code: string
-  message: string
-  data: T
-  requestId?: string | null
-  traceId?: string | null
-  timestamp?: string
-}
-
-export class ApiResponseError extends Error {
-  readonly code: string
-  readonly status?: number
-  readonly details?: unknown
-  readonly requestId?: string
-  readonly traceId?: string
-
-  constructor(message: string, code: string, status?: number, details?: unknown, requestId?: string | null, traceId?: string | null) {
-    super(message)
-    this.name = 'ApiResponseError'
-    this.code = code
-    this.status = status
-    this.details = details
-    this.requestId = requestId || undefined
-    this.traceId = traceId || undefined
-  }
-}
-
-export interface ApiErrorDetails {
-  message: string
-  code?: string
-  requestId?: string
-  traceId?: string
-}
-
-export const http = axios.create({
-  baseURL: import.meta.env.VITE_API_BASE_URL || '/api',
-  timeout: 15_000,
-})
-
-type RetryableRequestConfig = InternalAxiosRequestConfig & { _authRetry?: boolean }
-type AuthRefreshHandler = () => Promise<string>
-
-let authRefreshHandler: AuthRefreshHandler | null = null
-let activeRefresh: Promise<string> | null = null
-
-export function registerAuthRefreshHandler(handler: AuthRefreshHandler) {
-  authRefreshHandler = handler
-}
-
-http.interceptors.request.use((config) => {
-  const token = localStorage.getItem('cc-admin-token')
-  if (token) {
-    config.headers.Authorization = `Bearer ${token}`
-  }
-  return config
-})
-
-http.interceptors.response.use(
-  (response) => response.data,
-  async (error) => {
-    const config = error.config as RetryableRequestConfig | undefined
-    const isAuthEndpoint = typeof config?.url === 'string' && config.url.startsWith('/auth/')
-    if (error.response?.status !== 401 || !config || config._authRetry || isAuthEndpoint || !authRefreshHandler) {
-      return Promise.reject(error)
-    }
-
-    config._authRetry = true
-    try {
-      if (!activeRefresh) {
-        activeRefresh = authRefreshHandler().finally(() => { activeRefresh = null })
-      }
-      const nextToken = await activeRefresh
-      config.headers.Authorization = `Bearer ${nextToken}`
-      return http.request(config)
-    } catch {
-      return Promise.reject(error)
-    }
-  },
-)
-
-export function unwrapApiResponse<T>(response: ApiEnvelope<T>): T {
-  if (response?.code !== '0') {
-    throw new ApiResponseError(
-      response?.message || '接口请求失败',
-      response?.code || 'UNKNOWN',
-      undefined,
-      response?.data,
-      response?.requestId,
-      response?.traceId,
-    )
-  }
-  return response.data
-}
-
-export function getApiErrorDetails(error: unknown, fallback = '接口请求失败'): ApiErrorDetails {
-  if (error instanceof ApiResponseError) {
-    return { message: error.message, code: error.code, requestId: error.requestId, traceId: error.traceId }
-  }
-  if (axios.isAxiosError(error)) {
-    const response = error.response?.data as {
-      code?: string
-      message?: string
-      error?: string
-      requestId?: string | null
-      traceId?: string | null
-    } | undefined
-    return {
-      message: response?.message || response?.error || fallback,
-      code: response?.code || (error.response?.status ? `HTTP_${error.response.status}` : undefined),
-      requestId: response?.requestId || undefined,
-      traceId: response?.traceId || undefined,
-    }
-  }
-  return { message: error instanceof Error ? error.message : fallback }
-}
-
-export function getApiErrorMessage(error: unknown, fallback = '接口请求失败'): string {
-  return getApiErrorDetails(error, fallback).message
-}
diff --git a/src/api/platformIam.test.ts b/src/api/platformIam.test.ts
deleted file mode 100644
index f76601d8..00000000
--- a/src/api/platformIam.test.ts
+++ /dev/null
@@ -1,117 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-import { http } from '@/api/http'
-import {
-  createPlatformPermission,
-  createPlatformRole,
-  downloadTenantQualification,
-  listTenantQualifications,
-  listPlatformPermissions,
-  listPlatformRoles,
-  qualificationFileName,
-  type PlatformPermissionResource,
-  type PlatformRoleResource,
-} from './platformIam'
-
-vi.mock('@/api/http', () => ({
-  http: { get: vi.fn(), post: vi.fn() },
-  unwrapApiResponse: <T>(response: { data: T }) => response.data,
-}))
-
-const role: PlatformRoleResource = {
-  id: 4000002,
-  tenantId: 0,
-  appCode: 'PLATFORM',
-  roleCode: 'CUSTOMER_REVIEWER',
-  roleName: '企业审核员',
-  roleType: 'SYSTEM',
-  status: 'ACTIVE',
-  description: '企业资料与入驻审核',
-}
-
-const permission: PlatformPermissionResource = {
-  id: 5100010,
-  tenantId: 0,
-  appCode: 'PLATFORM',
-  permissionType: 'MENU',
-  parentId: 5100000,
-  permissionCode: 'platform:customer:list',
-  permissionName: '企业客户',
-  routePath: '/customers',
-  httpMethod: null,
-  sortNo: 10,
-  status: 'ACTIVE',
-}
-
-describe('platform IAM roles', () => {
-  beforeEach(() => {
-    vi.mocked(http.get).mockReset()
-    vi.mocked(http.post).mockReset()
-  })
-
-  it('loads roles from the platform IAM prefix', async () => {
-    vi.mocked(http.get).mockResolvedValue({ code: '0', message: 'success', data: [role] })
-
-    await expect(listPlatformRoles()).resolves.toEqual([role])
-    expect(http.get).toHaveBeenCalledWith('/platform/v1/iam/roles')
-  })
-
-  it('creates a platform role with the documented payload', async () => {
-    const payload = {
-      roleCode: 'CUSTOMER_REVIEWER',
-      roleName: '企业审核员',
-      description: '企业资料与入驻审核',
-    }
-    vi.mocked(http.post).mockResolvedValue({ code: '0', message: 'success', data: role })
-
-    await expect(createPlatformRole(payload)).resolves.toEqual(role)
-    expect(http.post).toHaveBeenCalledWith('/platform/v1/iam/roles', payload)
-  })
-
-  it('loads and creates permission resources under the platform IAM prefix', async () => {
-    vi.mocked(http.get).mockResolvedValue({ code: '0', message: 'success', data: [permission] })
-    vi.mocked(http.post).mockResolvedValue({ code: '0', message: 'success', data: permission })
-    const payload = {
-      type: 'MENU' as const,
-      code: permission.permissionCode,
-      name: permission.permissionName,
-      parentId: permission.parentId,
-      routePath: permission.routePath,
-      httpMethod: null,
-      sortNo: permission.sortNo,
-    }
-
-    await expect(listPlatformPermissions()).resolves.toEqual([permission])
-    await expect(createPlatformPermission(payload)).resolves.toEqual(permission)
-    expect(http.get).toHaveBeenCalledWith('/platform/v1/iam/permissions')
-    expect(http.post).toHaveBeenCalledWith('/platform/v1/iam/permissions', payload)
-  })
-
-  it('loads qualifications for the selected tenant', async () => {
-    const qualification = {
-      id: 12,
-      tenantId: 8,
-      qualificationType: 'BUSINESS_LICENSE',
-      certificateNo: '91440300XXXXXXXXXX',
-      documentUrl: '/api/merchant/v1/files/qualifications/license.png',
-      status: 'PENDING' as const,
-      reviewComment: null,
-    }
-    vi.mocked(http.get).mockResolvedValue({ code: '0', message: 'success', data: [qualification] })
-
-    await expect(listTenantQualifications(8)).resolves.toEqual([qualification])
-    expect(http.get).toHaveBeenCalledWith('/platform/v1/iam/tenants/8/qualifications')
-  })
-
-  it('downloads a qualification with the platform file endpoint and a safe filename', async () => {
-    const blob = new Blob(['image'], { type: 'image/png' })
-    vi.mocked(http.get).mockResolvedValue(blob)
-
-    expect(qualificationFileName('/api/merchant/v1/files/qualifications/%E8%90%A5%E4%B8%9A%E6%89%A7%E7%85%A7.png?token=ignored')).toBe('营业执照.png')
-    await expect(downloadTenantQualification(8, '/api/merchant/v1/files/qualifications/%E8%90%A5%E4%B8%9A%E6%89%A7%E7%85%A7.png')).resolves.toBe(blob)
-    expect(http.get).toHaveBeenCalledWith(
-      '/platform/v1/files/qualifications/8/%E8%90%A5%E4%B8%9A%E6%89%A7%E7%85%A7.png',
-      { responseType: 'blob' },
-    )
-    expect(() => qualificationFileName('/api/merchant/v1/files/qualifications/%2Fetc%2Fpasswd')).toThrow('资质文件地址无效')
-  })
-})
diff --git a/src/api/platformIam.ts b/src/api/platformIam.ts
deleted file mode 100644
index 96fcaeeb..00000000
--- a/src/api/platformIam.ts
+++ /dev/null
@@ -1,136 +0,0 @@
-import { http, unwrapApiResponse, type ApiEnvelope } from '@/api/http'
-
-export interface PlatformPermissionResource {
-  id: number
-  tenantId: number
-  appCode: 'PLATFORM'
-  permissionType: 'MENU' | 'BUTTON'
-  parentId: number
-  permissionCode: string
-  permissionName: string
-  routePath: string | null
-  httpMethod: string | null
-  sortNo: number
-  status: 'ACTIVE' | 'INACTIVE'
-}
-
-export interface EnterpriseReview {
-  id: number
-  tenantId: number
-  status: 'PENDING' | 'APPROVED' | 'REJECTED'
-  tenantName?: string | null
-  tenantCode?: string | null
-  qualificationId?: number | null
-  qualificationType?: string | null
-  certificateNo?: string | null
-  documentUrl?: string | null
-  contactName?: string | null
-  contactPhone?: string | null
-  contactEmail?: string | null
-  submittedAt?: string | null
-  createdAt?: string | null
-  reviewComment?: string | null
-  [key: string]: unknown
-}
-
-export interface PlatformTenantQualification {
-  id: number | string
-  tenantId: number | string
-  qualificationType: 'BUSINESS_LICENSE' | string
-  certificateNo: string | null
-  documentUrl: string
-  status: 'PENDING' | 'APPROVED' | 'REJECTED'
-  reviewComment: string | null
-}
-
-export interface PlatformRoleResource {
-  id: number
-  tenantId: number
-  appCode: 'PLATFORM'
-  roleCode: string
-  roleName: string
-  roleType: 'SYSTEM' | 'CUSTOM' | string
-  status: 'ACTIVE' | 'INACTIVE' | string
-  description: string | null
-}
-
-export interface CreatePlatformRoleRequest {
-  roleCode: string
-  roleName: string
-  description: string
-}
-
-export interface CreatePlatformPermissionRequest {
-  type: 'MENU' | 'BUTTON'
-  code: string
-  name: string
-  parentId: number
-  routePath: string | null
-  httpMethod: null
-  sortNo: number
-}
-
-async function getData<T>(path: string): Promise<T> {
-  const response = await http.get<ApiEnvelope<T>, ApiEnvelope<T>>(path)
-  return unwrapApiResponse(response)
-}
-
-async function postData<T>(path: string, body: unknown): Promise<T> {
-  const response = await http.post<ApiEnvelope<T>, ApiEnvelope<T>>(path, body)
-  return unwrapApiResponse(response)
-}
-
-export function listPlatformPermissions() {
-  return getData<PlatformPermissionResource[]>('/platform/v1/iam/permissions')
-}
-
-export function listEnterpriseReviews() {
-  return getData<EnterpriseReview[]>('/platform/v1/iam/reviews')
-}
-
-export function listTenantQualifications(tenantId: number | string) {
-  return getData<PlatformTenantQualification[]>(`/platform/v1/iam/tenants/${tenantId}/qualifications`)
-}
-
-export function qualificationFileName(documentUrl: string) {
-  const path = documentUrl.split(/[?#]/, 1)[0]
-  const encodedName = path.split('/').filter(Boolean).at(-1)
-  if (!encodedName) throw new Error('资质文件地址无效')
-  let fileName: string
-  try {
-    fileName = decodeURIComponent(encodedName)
-  } catch {
-    throw new Error('资质文件地址无效')
-  }
-  if (!fileName || fileName === '.' || fileName === '..' || /[\\/]/.test(fileName)) {
-    throw new Error('资质文件地址无效')
-  }
-  return fileName
-}
-
-export function downloadTenantQualification(tenantId: number | string, documentUrl: string) {
-  const fileName = qualificationFileName(documentUrl)
-  return http.get<Blob, Blob>(`/platform/v1/files/qualifications/${tenantId}/${encodeURIComponent(fileName)}`, {
-    responseType: 'blob',
-  })
-}
-
-export function listPlatformRoles() {
-  return getData<PlatformRoleResource[]>('/platform/v1/iam/roles')
-}
-
-export function createPlatformRole(payload: CreatePlatformRoleRequest) {
-  return postData<PlatformRoleResource>('/platform/v1/iam/roles', payload)
-}
-
-export function createPlatformPermission(payload: CreatePlatformPermissionRequest) {
-  return postData<PlatformPermissionResource>('/platform/v1/iam/permissions', payload)
-}
-
-export function approveEnterpriseReview(reviewId: number, comment: string) {
-  return postData<unknown>(`/platform/v1/iam/reviews/${reviewId}/approve`, { comment })
-}
-
-export function rejectEnterpriseReview(reviewId: number, comment: string) {
-  return postData<unknown>(`/platform/v1/iam/reviews/${reviewId}/reject`, { comment })
-}
diff --git a/src/app/DomesticOutboundListLayout.test.ts b/src/app/DomesticOutboundListLayout.test.ts
new file mode 100644
index 00000000..56b5c209
--- /dev/null
+++ b/src/app/DomesticOutboundListLayout.test.ts
@@ -0,0 +1,53 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const pages = [
+  ['src/modules/container-loading/pages/ContainersView.vue', "key: 'cabinetNo'"],
+  ['src/modules/loading-lists/components/LoadingListsView.vue', "key: 'preloadNo'"],
+  ['src/modules/ocean-bookings/pages/OceanBookingsView.vue', "prop: 'bookingNo'"],
+  ['src/modules/port-schedules/pages/PortSchedulesView.vue', "prop: 'schedule.scheduleNo'"],
+  ['src/modules/trucking/pages/TruckAppointmentsView.vue', "key: 'appointmentNo'"],
+  ['src/modules/customs/pages/CustomsCasesView.vue', "prop: 'customsNo'"],
+  ['src/modules/outbound-dispatch/pages/OutboundDispatchesView.vue', "prop: 'inboundCode'"],
+] as const
+
+function source(path: string) {
+  return readFileSync(resolve(process.cwd(), path), 'utf8')
+}
+
+describe('domestic outbound list responsive contracts', () => {
+  it.each(pages)('%s keeps the operation column first and fixed left', (path, firstBusinessColumn) => {
+    const content = source(path)
+    const firstAction = content.indexOf("label: '操作'")
+    expect(firstAction).toBeGreaterThan(-1)
+    expect(firstAction).toBeLessThan(content.indexOf(firstBusinessColumn, firstAction))
+    const actionObjects = [...content.matchAll(/\{[^{}]*label: '操作'[^{}]*\}/g)].map((match) => match[0])
+    expect(actionObjects.length).toBeGreaterThan(0)
+    for (const column of actionObjects) expect(column).toContain("fixed: 'left'")
+  })
+
+  it.each(pages)('%s gives every business column a stable width constraint', (path) => {
+    const content = source(path)
+    const columns = [...content.matchAll(/\{[^{}]*(?:key|prop): '[^']+'[^{}]*label: '[^']+'[^{}]*\}/g)]
+      .map((match) => match[0])
+      .filter((column) => !column.includes("type: 'input'") && !column.includes("type: 'select'") && !column.includes("type: 'daterange'"))
+    expect(columns.length).toBeGreaterThan(1)
+    for (const column of columns) expect(column).toMatch(/\b(?:width|minWidth):\s*\d+/)
+  })
+
+  it('keeps shared 320px degradation rules for filters, actions and pagination', () => {
+    const queryToolbar = source('src/shared/components/QueryToolbar.vue')
+    const dataTable = source('src/shared/components/DataTable.vue')
+    const listLayout = source('src/shared/components/ListPageLayout.vue')
+
+    expect(queryToolbar).toContain('@media (max-width: 720px)')
+    expect(queryToolbar).toContain('.query-toolbar__field { width: 100%; flex: 0 0 auto; }')
+    expect(queryToolbar).toContain('.query-toolbar__control { width: 100%; flex: 0 0 auto; }')
+    expect(queryToolbar).toContain('grid-template-columns: repeat(auto-fit, minmax(120px, 1fr))')
+    expect(dataTable).toContain('@media (max-width: 720px)')
+    expect(dataTable).toContain('flex-direction: column')
+    expect(dataTable).toContain('.data-table__page-buttons { flex-wrap: wrap; }')
+    expect(listLayout).toContain('min-width: 0')
+  })
+})
diff --git a/src/app/DomesticOutboundListStates.test.ts b/src/app/DomesticOutboundListStates.test.ts
new file mode 100644
index 00000000..360dc95b
--- /dev/null
+++ b/src/app/DomesticOutboundListStates.test.ts
@@ -0,0 +1,37 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const pages = [
+  ['src/modules/container-loading/pages/ContainersView.vue', ':loading="loading"', 'LoadErrorState', 'empty-text="暂无货柜"', 'statusText(row.planStatus)', 'platform:firstleg:container:list', '@retry="loadRows"'],
+  ['src/modules/loading-lists/components/LoadingListsView.vue', ':loading="loading"', 'LoadErrorState', ':empty-text="`暂无符合筛选条件的${title}`"', 'loadingListStatusLabel(row.status)', 'canView', '@retry="load"'],
+  ['src/modules/ocean-bookings/pages/OceanBookingsView.vue', ':loading="loading"', 'LoadErrorState', 'empty-text="暂无符合筛选条件的订舱"', 'oceanBookingStatusLabel(row.status)', "{{ row.status === 'DRAFT' ? '编辑' : '查看' }}", '@retry="load"'],
+  ['src/modules/trucking/pages/TruckAppointmentsView.vue', ':loading="loading"', 'LoadErrorState', 'empty-text="暂无符合筛选条件的拖车预约"', 'statusLabel(row.status)', '@click="openDetail(row as TruckAppointmentResource)">详情</el-button>', '@retry="load"'],
+] as const
+
+function source(path: string) {
+  return readFileSync(resolve(process.cwd(), path), 'utf8')
+}
+
+describe('domestic outbound list state contracts', () => {
+  it.each(pages)('%s exposes loading, error, empty, translated status, detail action and retry states', (path, loading, error, empty, status, detailAction, retry) => {
+    const content = source(path)
+    expect(content).toContain(loading)
+    expect(content).toContain(error)
+    expect(content).toContain(empty)
+    expect(content).toContain(status)
+    expect(content).toContain(detailAction)
+    expect(content).toContain(retry)
+  })
+
+  it('keeps list component state when route details return to the cached workspace list', () => {
+    const layout = source('src/app/layouts/AppLayout.vue')
+    const oceanDetail = source('src/modules/ocean-bookings/pages/OceanBookingDetailView.vue')
+    const truckingDetail = source('src/modules/trucking/pages/TruckAppointmentDetailView.vue')
+
+    expect(layout).toContain('<KeepAlive :max="MAX_CACHED_WORKSPACE_VIEWS">')
+    expect(layout).toContain(':key="workspace.cacheKey(workspaceRouteId(renderedRoute)) + \':\' + JSON.stringify(renderedRoute.params)"')
+    expect(oceanDetail).toContain("router.push('/ocean-bookings')")
+    expect(truckingDetail).toContain("router.push({ name: 'trucking' })")
+  })
+})
diff --git a/src/app/components/AdminSidebarMenu.test.ts b/src/app/components/AdminSidebarMenu.test.ts
new file mode 100644
index 00000000..0c1babf0
--- /dev/null
+++ b/src/app/components/AdminSidebarMenu.test.ts
@@ -0,0 +1,150 @@
+import { flushPromises, mount } from '@vue/test-utils'
+import { defineComponent } from 'vue'
+import { createMemoryHistory, createRouter } from 'vue-router'
+import { describe, expect, it } from 'vitest'
+import { adminNavigation, filterAdminNavigation, type AdminNavigationNode } from '@/core/navigation/adminNavigation'
+import AdminSidebarMenu from './AdminSidebarMenu.vue'
+
+const visibleNavigation = filterAdminNavigation(adminNavigation, new Set([
+  'platform:customer:list',
+  'platform:warehouse:list',
+  'platform:firstleg:inbound:list',
+  'platform:location:list',
+  'platform:pallet:list',
+  'firstleg:fba-pricing:rate:view',
+  'platform:express:list',
+  'platform:counterparty:list',
+  'platform:download:list',
+  'platform:user:list',
+  'platform:role:list',
+  'platform:permission:list',
+]))
+
+const stubs = {
+  'el-menu': defineComponent({
+    props: ['defaultActive', 'defaultOpeneds', 'collapse'],
+    emits: ['select'],
+    methods: { updateActiveIndex() {} },
+    template: '<nav :data-active="defaultActive" :data-openeds="JSON.stringify(defaultOpeneds)" :data-collapsed="String(collapse)" @click="$emit(\'select\', \'/warehouses\')"><slot /></nav>',
+  }),
+  'el-sub-menu': {
+    props: ['index'],
+    template: '<section data-kind="group" :data-index="index"><header><slot name="title" /></header><slot /></section>',
+  },
+  'el-menu-item': {
+    props: ['index'],
+    template: '<a data-kind="item" :data-index="index"><slot name="title" /><slot /></a>',
+  },
+}
+
+describe('AdminSidebarMenu', () => {
+  function routerPlugin() {
+    return createRouter({
+      history: createMemoryHistory(),
+      routes: [
+        { path: '/', component: { template: '<p />' } },
+        { path: '/warehouses', component: { template: '<p />' } },
+      ],
+    })
+  }
+
+  it('renders the visible phase-one modules and forwards the active route', () => {
+    const wrapper = mount(AdminSidebarMenu, {
+      props: { items: visibleNavigation, activePath: '/system/users', collapsed: false },
+      global: { stubs, plugins: [routerPlugin()] },
+    })
+
+    expect(wrapper.get('nav').attributes('data-active')).toBe('/system/users')
+    expect(wrapper.get('nav').attributes('data-openeds')).toBe('[]')
+    const groupTitles = wrapper.findAll('[data-kind="group"] header').map((node) => node.text())
+    const paths = wrapper.findAll('[data-kind="item"]').map((node) => node.attributes('data-index'))
+
+    expect(groupTitles).toContain('客户管理')
+    expect(groupTitles).not.toContain('供应商中心')
+    expect(groupTitles).toContain('通用')
+    expect(groupTitles).toContain('系统管理')
+    expect(groupTitles).not.toContain('财务管理')
+    expect(paths).toContain('/dashboard')
+    expect(paths).toContain('/orders')
+    expect(paths).toContain('/master-data/express-companies')
+    expect(paths).not.toContain('/orders/first-leg')
+    expect(paths).not.toContain('/first-leg-pricing/customer-rules')
+    expect(paths).toContain('/downloads')
+    expect(paths).not.toContain('/prototype/reports/overview')
+    expect(paths).toContain('/system/permissions')
+  })
+
+  it('forwards desktop collapse state to Element Plus', () => {
+    const wrapper = mount(AdminSidebarMenu, {
+      props: { items: visibleNavigation, activePath: '/', collapsed: true },
+      global: { stubs, plugins: [routerPlugin()] },
+    })
+
+    expect(wrapper.get('nav').attributes('data-collapsed')).toBe('true')
+  })
+
+  it('renders only entries included in the filtered navigation input', () => {
+    const items = filterAdminNavigation(adminNavigation, new Set(['platform:permission:list']))
+    const wrapper = mount(AdminSidebarMenu, {
+      props: { items, activePath: '/', collapsed: false },
+      global: { stubs, plugins: [routerPlugin()] },
+    })
+
+    expect(wrapper.text()).toContain('菜单权限')
+    expect(wrapper.text()).toContain('首页数据看板')
+    expect(wrapper.text()).not.toContain('客户列表')
+  })
+
+  it('recursively renders three navigation levels', () => {
+    const items: AdminNavigationNode[] = [{
+      key: 'operations',
+      title: '运营管理',
+      icon: adminNavigation[0].icon,
+      children: [{
+        key: 'shipment',
+        title: '运输管理',
+        icon: adminNavigation[0].icon,
+        children: [{
+          key: 'tracking',
+          title: '轨迹管理',
+          icon: adminNavigation[0].icon,
+          path: '/tracking',
+          permission: 'tracking:list',
+        }],
+      }],
+    }]
+    const wrapper = mount(AdminSidebarMenu, {
+      props: { items, activePath: '/tracking', collapsed: false },
+      global: { stubs, plugins: [routerPlugin()] },
+    })
+
+    expect(wrapper.findAll('[data-kind="group"]')).toHaveLength(2)
+    expect(wrapper.get('[data-kind="item"]').attributes('data-index')).toBe('/tracking')
+  })
+
+  it('recreates the menu when asynchronously loaded groups change', async () => {
+    const wrapper = mount(AdminSidebarMenu, {
+      props: { items: [adminNavigation[0]], activePath: '/dashboard', collapsed: false },
+      global: { stubs, plugins: [routerPlugin()] },
+    })
+    const initialMenu = wrapper.get('nav').element
+
+    await wrapper.setProps({ items: visibleNavigation })
+
+    expect(wrapper.get('nav').element).not.toBe(initialMenu)
+    expect(wrapper.text()).toContain('系统管理')
+  })
+
+  it('navigates explicitly when a leaf menu item is selected', async () => {
+    const router = routerPlugin()
+    await router.push('/')
+    const wrapper = mount(AdminSidebarMenu, {
+      props: { items: visibleNavigation, activePath: '/', collapsed: false },
+      global: { stubs, plugins: [router] },
+    })
+
+    await wrapper.get('nav').trigger('click')
+    await flushPromises()
+    expect(router.currentRoute.value.path).toBe('/warehouses')
+  })
+})
diff --git a/src/app/components/AdminSidebarMenu.vue b/src/app/components/AdminSidebarMenu.vue
new file mode 100644
index 00000000..b34e9ec6
--- /dev/null
+++ b/src/app/components/AdminSidebarMenu.vue
@@ -0,0 +1,58 @@
+<script setup lang="ts">
+import { computed, nextTick, ref, watch } from 'vue'
+import { useRouter, type NavigationFailure } from 'vue-router'
+import type { MenuInstance } from 'element-plus'
+import type { AdminNavigationNode } from '@/core/navigation/adminNavigation'
+import AdminSidebarMenuNode from './AdminSidebarMenuNode.vue'
+
+const props = defineProps<{
+  items: AdminNavigationNode[]
+  activePath: string
+  collapsed: boolean
+}>()
+const router = useRouter()
+const menuRef = ref<MenuInstance>()
+
+function getGroupKeys(nodes: AdminNavigationNode[]): string[] {
+  return nodes.flatMap((node) => node.children?.length
+    ? [node.key, ...getGroupKeys(node.children)]
+    : [])
+}
+
+const groupKeys = computed(() => getGroupKeys(props.items))
+const defaultOpeneds: string[] = []
+const menuInstanceKey = computed(() => `${props.collapsed ? 'collapsed' : 'expanded'}:${groupKeys.value.join('|')}`)
+
+async function restoreActivePath() {
+  await nextTick()
+  menuRef.value?.updateActiveIndex(props.activePath)
+}
+
+async function navigate(path: string) {
+  if (!path.startsWith('/') || path === props.activePath) return
+  let failure: NavigationFailure | void
+  try {
+    failure = await router.push(path)
+  } catch {
+    await restoreActivePath()
+    return
+  }
+  if (failure) await restoreActivePath()
+}
+
+watch(() => props.activePath, restoreActivePath)
+</script>
+
+<template>
+  <el-menu
+    ref="menuRef"
+    :key="menuInstanceKey"
+    class="side-nav-menu"
+    :default-active="activePath"
+    :collapse="collapsed"
+    :default-openeds="defaultOpeneds"
+    @select="navigate"
+  >
+    <AdminSidebarMenuNode v-for="item in items" :key="item.key" :node="item" :level="0" />
+  </el-menu>
+</template>
diff --git a/src/app/components/AdminSidebarMenuNode.vue b/src/app/components/AdminSidebarMenuNode.vue
new file mode 100644
index 00000000..ab50c0da
--- /dev/null
+++ b/src/app/components/AdminSidebarMenuNode.vue
@@ -0,0 +1,40 @@
+<script setup lang="ts">
+import type { AdminNavigationNode } from '@/core/navigation/adminNavigation'
+
+defineOptions({ name: 'AdminSidebarMenuNode' })
+
+defineProps<{
+  node: AdminNavigationNode
+  level?: number
+}>()
+</script>
+
+<template>
+  <el-sub-menu v-if="node.children?.length" :index="node.key">
+    <template #title>
+      <component
+        v-if="!level"
+        :is="node.icon"
+        class="menu-icon"
+        :style="{ color: node.iconColor }"
+        :size="20"
+        :stroke-width="1.9"
+      />
+      <span>{{ node.title }}</span>
+    </template>
+
+    <AdminSidebarMenuNode v-for="child in node.children" :key="child.key" :node="child" :level="(level ?? 0) + 1" />
+  </el-sub-menu>
+
+  <el-menu-item v-else :index="node.path || node.key">
+    <component
+      v-if="!level"
+      :is="node.icon"
+      class="menu-icon"
+      :style="{ color: node.iconColor }"
+      :size="20"
+      :stroke-width="1.9"
+    />
+    <template #title>{{ node.title }}</template>
+  </el-menu-item>
+</template>
diff --git a/src/app/components/WorkspaceTabs.test.ts b/src/app/components/WorkspaceTabs.test.ts
new file mode 100644
index 00000000..5b663870
--- /dev/null
+++ b/src/app/components/WorkspaceTabs.test.ts
@@ -0,0 +1,84 @@
+import ElementPlus, { ElMessageBox } from 'element-plus'
+import { createPinia, setActivePinia } from 'pinia'
+import { flushPromises, mount } from '@vue/test-utils'
+import { createMemoryHistory, createRouter } from 'vue-router'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { useAuthStore } from '@/core/auth/auth'
+import { useUnsavedWorkStore } from '@/core/unsaved-work/unsavedWork'
+import { useWorkspaceTabsStore } from '@/core/workspace-tabs/workspaceTabs'
+import WorkspaceTabs from './WorkspaceTabs.vue'
+
+vi.mock('element-plus', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('element-plus')>()
+  return { ...actual, ElMessage: { error: vi.fn() }, ElMessageBox: { confirm: vi.fn() } }
+})
+
+async function mountTabs() {
+  const pinia = createPinia()
+  setActivePinia(pinia)
+  const auth = useAuthStore()
+  auth.token = 'token'
+  auth.user = { id: '1', name: '平台管理员', account: 'admin', roles: ['PLATFORM_ADMIN'] }
+  auth.permissions = ['platform:customer:list', 'platform:warehouse:list']
+  const router = createRouter({
+    history: createMemoryHistory(),
+    routes: [
+      { path: '/customers', name: 'customers', component: { template: '<p />' }, meta: { requiresAuth: true, title: '客户管理' } },
+      { path: '/warehouses', name: 'warehouses', component: { template: '<p />' }, meta: { requiresAuth: true, title: '仓库管理' } },
+    ],
+  })
+  await router.push('/customers')
+  await router.isReady()
+  const workspace = useWorkspaceTabsStore()
+  workspace.initialize('1')
+  workspace.open({ id: 'warehouses', title: '仓库管理', path: '/warehouses' })
+  workspace.open({ id: 'customers', title: '客户管理', path: '/customers' })
+  const wrapper = mount(WorkspaceTabs, { attachTo: document.body, global: { plugins: [pinia, router, ElementPlus] } })
+  return { wrapper, router, workspace, unsaved: useUnsavedWorkStore() }
+}
+
+describe('WorkspaceTabs', () => {
+  beforeEach(() => {
+    sessionStorage.clear()
+    vi.mocked(ElMessageBox.confirm).mockReset()
+  })
+  afterEach(() => { document.body.innerHTML = '' })
+
+  it('keeps a dirty tab open when discard confirmation is cancelled', async () => {
+    const { wrapper, workspace, unsaved } = await mountTabs()
+    unsaved.upsert({ key: 'customer-form', label: '客户资料', dirty: true, requiredPermission: null, workspaceTabId: 'customers' })
+    vi.mocked(ElMessageBox.confirm).mockRejectedValueOnce('cancel')
+
+    await wrapper.get('[aria-label="关闭页签：客户管理"]').trigger('click')
+    await flushPromises()
+
+    expect(workspace.tabs.map((tab) => tab.id)).toContain('customers')
+    expect(wrapper.find('.workspace-tab.is-dirty').exists()).toBe(true)
+  })
+
+  it('closes confirmed dirty work and activates the most recent remaining tab', async () => {
+    const { wrapper, router, workspace, unsaved } = await mountTabs()
+    unsaved.upsert({ key: 'customer-form', label: '客户资料', dirty: true, requiredPermission: null, workspaceTabId: 'customers' })
+    vi.mocked(ElMessageBox.confirm).mockResolvedValueOnce({} as never)
+
+    await wrapper.get('[aria-label="关闭页签：客户管理"]').trigger('click')
+    await flushPromises()
+
+    expect(workspace.tabs.map((tab) => tab.id)).toEqual(['warehouses'])
+    expect(router.currentRoute.value.path).toBe('/warehouses')
+    expect(unsaved.findForWorkspace('customers')).toEqual([])
+  })
+
+  it('uses the mouse wheel to scroll an overflowing tab list horizontally', async () => {
+    const { wrapper } = await mountTabs()
+    const tabList = wrapper.get<HTMLElement>('.workspace-tab-list')
+    Object.defineProperties(tabList.element, {
+      clientWidth: { configurable: true, value: 320 },
+      scrollWidth: { configurable: true, value: 720 },
+    })
+
+    await tabList.trigger('wheel', { deltaY: 120 })
+
+    expect(tabList.element.scrollLeft).toBe(120)
+  })
+})
diff --git a/src/app/components/WorkspaceTabs.vue b/src/app/components/WorkspaceTabs.vue
new file mode 100644
index 00000000..1dc761e1
--- /dev/null
+++ b/src/app/components/WorkspaceTabs.vue
@@ -0,0 +1,262 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, nextTick, ref, watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import { MoreHorizontal, X } from '@lucide/vue'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useUnsavedWorkStore } from '@/core/unsaved-work/unsavedWork'
+import { workspaceTabCandidate } from '@/core/workspace-tabs/routeWorkspace'
+import { useWorkspaceTabsStore } from '@/core/workspace-tabs/workspaceTabs'
+
+type CloseCommand = 'current' | 'others' | 'right' | 'all'
+
+const route = useRoute()
+const router = useRouter()
+const access = useAccessPreviewStore()
+const unsaved = useUnsavedWorkStore()
+const workspace = useWorkspaceTabsStore()
+const tabListRef = ref<HTMLElement>()
+
+const activeIndex = computed(() => workspace.tabs.findIndex((tab) => tab.id === workspace.activeId))
+const hasRightTabs = computed(() => activeIndex.value >= 0 && activeIndex.value < workspace.tabs.length - 1)
+
+function blockingEntries(tabIds: readonly string[]) {
+  return tabIds.flatMap((tabId) => unsaved.findForWorkspace(tabId))
+}
+
+async function confirmDiscard(tabIds: readonly string[]) {
+  const blocking = blockingEntries(tabIds)
+  if (blocking.length === 0) return true
+  const labels = [...new Set(blocking.map((entry) => entry.label))]
+  try {
+    await ElMessageBox.confirm(
+      `以下内容尚未保存：${labels.join('、')}。关闭页签后将放弃这些修改。`,
+      '放弃未保存的修改？',
+      { confirmButtonText: '放弃并关闭', cancelButtonText: '继续编辑', type: 'warning', customClass: 'admin-density-confirm' },
+    )
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function focusActiveTab() {
+  await nextTick()
+  const active = tabListRef.value?.querySelector<HTMLElement>('[role="tab"][aria-selected="true"]')
+  active?.focus({ preventScroll: true })
+  active?.scrollIntoView?.({ block: 'nearest', inline: 'nearest' })
+}
+
+async function navigateToFallback(path: string | null) {
+  const destination = path || access.firstAccessiblePath
+  if (!destination) {
+    await router.push('/403')
+    return
+  }
+  if (destination === route.fullPath) {
+    const candidate = workspaceTabCandidate(route)
+    if (candidate) workspace.open(candidate, unsaved.dirtyWorkspaceIds)
+    await focusActiveTab()
+    return
+  }
+  await router.push(destination)
+}
+
+async function closeTabs(tabIds: readonly string[]) {
+  const uniqueIds = [...new Set(tabIds)].filter((id) => workspace.tabs.some((tab) => tab.id === id))
+  if (uniqueIds.length === 0 || !await confirmDiscard(uniqueIds)) return
+  const activeWillClose = workspace.activeId !== null && uniqueIds.includes(workspace.activeId)
+  unsaved.removeWorkspaces(uniqueIds)
+  const fallback = workspace.removeByIds(uniqueIds)
+  if (activeWillClose) await navigateToFallback(fallback?.path ?? null)
+  else await focusActiveTab()
+}
+
+async function activateTab(path: string) {
+  if (path === route.fullPath) return
+  try {
+    await router.push(path)
+  } catch {
+    ElMessage.error('页签切换失败，请重试')
+  }
+}
+
+function idsForCommand(command: CloseCommand) {
+  if (command === 'all') return workspace.tabs.map((tab) => tab.id)
+  if (command === 'others') return workspace.tabs.filter((tab) => tab.id !== workspace.activeId).map((tab) => tab.id)
+  if (command === 'right') return workspace.tabs.slice(activeIndex.value + 1).map((tab) => tab.id)
+  return workspace.activeId ? [workspace.activeId] : []
+}
+
+function handleCommand(command: CloseCommand) {
+  void closeTabs(idsForCommand(command))
+}
+
+function handleTabKeydown(event: KeyboardEvent, index: number) {
+  if (event.key !== 'ArrowLeft' && event.key !== 'ArrowRight') return
+  event.preventDefault()
+  const buttons = [...(tabListRef.value?.querySelectorAll<HTMLElement>('[role="tab"]') ?? [])]
+  if (buttons.length === 0) return
+  const direction = event.key === 'ArrowRight' ? 1 : -1
+  buttons[(index + direction + buttons.length) % buttons.length]?.focus()
+}
+
+function handleTabWheel(event: WheelEvent) {
+  const tabList = tabListRef.value
+  if (!tabList || tabList.scrollWidth <= tabList.clientWidth) return
+  const delta = Math.abs(event.deltaX) > Math.abs(event.deltaY) ? event.deltaX : event.deltaY
+  if (delta === 0) return
+  const maxScrollLeft = tabList.scrollWidth - tabList.clientWidth
+  const canScroll = delta < 0 ? tabList.scrollLeft > 0 : tabList.scrollLeft < maxScrollLeft
+  if (!canScroll) return
+  event.preventDefault()
+  tabList.scrollLeft = Math.max(0, Math.min(maxScrollLeft, tabList.scrollLeft + delta))
+}
+
+watch(
+  () => workspace.activeId,
+  async () => {
+    await nextTick()
+    const active = tabListRef.value?.querySelector<HTMLElement>('[aria-selected="true"]')
+    active?.scrollIntoView?.({ block: 'nearest', inline: 'nearest' })
+  },
+)
+</script>
+
+<template>
+  <section class="workspace-tabs" aria-label="页面工作区">
+    <div ref="tabListRef" class="workspace-tab-list" role="tablist" aria-label="已打开页面" @wheel="handleTabWheel">
+      <div
+        v-for="(tab, index) in workspace.tabs"
+        :key="tab.id"
+        class="workspace-tab"
+        :class="{ 'is-active': tab.id === workspace.activeId, 'is-dirty': unsaved.dirtyWorkspaceIds.has(tab.id) }"
+      >
+        <button
+          class="workspace-tab-activate"
+          type="button"
+          role="tab"
+          :aria-selected="tab.id === workspace.activeId"
+          :tabindex="tab.id === workspace.activeId ? 0 : -1"
+          :title="tab.title"
+          @click="activateTab(tab.path)"
+          @keydown="handleTabKeydown($event, index)"
+        >
+          <span class="workspace-tab-label">{{ tab.title }}</span>
+          <span v-if="unsaved.dirtyWorkspaceIds.has(tab.id)" class="workspace-tab-dirty" aria-label="有未保存修改" />
+        </button>
+        <button
+          class="workspace-tab-close"
+          type="button"
+          :aria-label="`关闭页签：${tab.title}`"
+          :title="`关闭 ${tab.title}`"
+          @click="closeTabs([tab.id])"
+        ><X :size="14" aria-hidden="true" /></button>
+      </div>
+    </div>
+
+    <el-dropdown trigger="click" placement="bottom-end" @command="handleCommand">
+      <el-button class="workspace-tab-more" text aria-label="页签管理" title="页签管理">
+        <MoreHorizontal :size="18" aria-hidden="true" />
+      </el-button>
+      <template #dropdown>
+        <el-dropdown-menu>
+          <el-dropdown-item command="current" :disabled="!workspace.activeId">关闭当前</el-dropdown-item>
+          <el-dropdown-item command="others" :disabled="workspace.tabs.length <= 1">关闭其他</el-dropdown-item>
+          <el-dropdown-item command="right" :disabled="!hasRightTabs">关闭右侧</el-dropdown-item>
+          <el-dropdown-item command="all" :disabled="workspace.tabs.length === 0" divided>关闭全部</el-dropdown-item>
+        </el-dropdown-menu>
+      </template>
+    </el-dropdown>
+  </section>
+</template>
+
+<style scoped>
+.workspace-tabs {
+  position: sticky;
+  top: 64px;
+  z-index: 14;
+  display: flex;
+  min-width: 0;
+  height: 44px;
+  align-items: stretch;
+  border-bottom: 1px solid var(--cc-border);
+  background: #f7f9fc;
+  box-shadow: 0 5px 14px rgba(23, 42, 70, .045);
+}
+.workspace-tab-list {
+  display: flex;
+  min-width: 0;
+  flex: 1;
+  align-items: flex-end;
+  gap: 4px;
+  overflow-x: auto;
+  padding: 6px 8px 0;
+  overscroll-behavior-inline: contain;
+  scrollbar-width: none;
+  -ms-overflow-style: none;
+}
+.workspace-tab-list::-webkit-scrollbar { display: none; width: 0; height: 0; }
+.workspace-tab {
+  display: flex;
+  min-width: 126px;
+  max-width: 220px;
+  height: 38px;
+  flex: 0 0 auto;
+  align-items: center;
+  border: 1px solid transparent;
+  border-bottom: 0;
+  border-radius: 8px 8px 0 0;
+  color: #526178;
+}
+.workspace-tab:hover { background: #eef3fa; color: #24344d; }
+.workspace-tab.is-active { border-color: var(--cc-border); background: #fff; color: #172033; }
+.workspace-tab-activate {
+  display: flex;
+  min-width: 0;
+  height: 100%;
+  flex: 1;
+  align-items: center;
+  gap: 7px;
+  padding: 0 4px 0 12px;
+  border: 0;
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+  font: inherit;
+  text-align: left;
+}
+.workspace-tab-label { overflow: hidden; font-size: 12px; font-weight: 620; text-overflow: ellipsis; white-space: nowrap; }
+.workspace-tab-dirty { width: 6px; height: 6px; flex: 0 0 auto; border-radius: 50%; background: #d97706; }
+.workspace-tab-close {
+  display: grid;
+  width: 30px;
+  height: 30px;
+  flex: 0 0 30px;
+  place-items: center;
+  margin-right: 3px;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  color: #7b8799;
+  cursor: pointer;
+}
+.workspace-tab-close:hover { background: #dde6f2; color: #26364d; }
+.workspace-tab-activate:focus-visible,
+.workspace-tab-close:focus-visible { outline: 2px solid var(--cc-primary); outline-offset: -2px; }
+.workspace-tab-more { width: 44px; height: 44px; flex: 0 0 44px; border-radius: 0; border-left: 1px solid var(--cc-border); color: #526178; }
+
+@media (max-width: 720px) {
+  .workspace-tabs { top: 64px; height: 48px; }
+  .workspace-tab-list { align-items: center; padding: 4px 6px; }
+  .workspace-tab { min-width: 140px; height: 40px; border-bottom: 1px solid transparent; border-radius: 8px; }
+  .workspace-tab.is-active { border-color: #cbd7e7; }
+  .workspace-tab-close { width: 34px; height: 34px; flex-basis: 34px; }
+  .workspace-tab-more { height: 48px; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .workspace-tab-list { scroll-behavior: auto; }
+}
+</style>
diff --git a/src/app/layouts/AppLayout.test.ts b/src/app/layouts/AppLayout.test.ts
new file mode 100644
index 00000000..8a3f58f6
--- /dev/null
+++ b/src/app/layouts/AppLayout.test.ts
@@ -0,0 +1,160 @@
+import { createPinia, setActivePinia } from 'pinia'
+import { flushPromises, mount } from '@vue/test-utils'
+import { defineComponent, ref } from 'vue'
+import { createMemoryHistory, createRouter } from 'vue-router'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { ElMessageBox } from 'element-plus'
+import { useAuthStore } from '@/core/auth/auth'
+import AppLayout from './AppLayout.vue'
+
+const CachedPage = defineComponent({
+  setup() {
+    const count = ref(0)
+    return { count }
+  },
+  template: '<button class="cached-count" @click="count += 1">{{ count }}</button>',
+})
+
+vi.mock('element-plus', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('element-plus')>()
+  return { ...actual, ElMessage: { warning: vi.fn(), error: vi.fn() }, ElMessageBox: { confirm: vi.fn() } }
+})
+
+async function mountLayout(path = '/') {
+  const pinia = createPinia()
+  setActivePinia(pinia)
+  const auth = useAuthStore()
+  auth.token = 'token'
+  auth.user = { id: '1', name: '平台管理员', account: 'admin', roles: ['PLATFORM_ADMIN'] }
+  auth.permissions = ['platform:warehouse:list', 'platform:notification:task:list', 'platform:notification:template:list']
+  const router = createRouter({
+    history: createMemoryHistory(),
+    routes: [
+      { path: '/', name: 'home', component: { template: '<p>page</p>' }, meta: { requiresAuth: true, workspaceTab: false, keepAlive: false } },
+      { path: '/customers', name: 'customers', component: CachedPage, meta: { title: '客户管理', showPageHeading: false, requiresAuth: true } },
+      { path: '/warehouses', name: 'warehouses', component: { template: '<p>warehouses</p>' }, meta: { title: '仓库管理', requiresAuth: true } },
+      { path: '/login', component: { template: '<p>login</p>' } },
+    ],
+  })
+  await router.push(path)
+  await router.isReady()
+  const wrapper = mount(AppLayout, {
+    global: { plugins: [pinia, router], stubs: { AdminSidebarMenu: { template: '<nav />' }, WorkspaceTabs: { template: '<div class="workspace-tabs-stub" />' }, 'el-dropdown': { template: '<div><slot /><slot name="dropdown" /></div>' }, 'el-dropdown-menu': { template: '<div><slot /></div>' }, 'el-dropdown-item': { emits: ['click'], template: '<button @click="$emit(\'click\')"><slot /></button>' }, 'el-button': { emits: ['click'], template: '<button @click="$emit(\'click\')"><slot /></button>' } } },
+  })
+  return { wrapper, router }
+}
+
+function mockViewport(isMobile: boolean) {
+  const mediaQuery = {
+    matches: isMobile,
+    media: '(max-width: 720px)',
+    onchange: null,
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+    dispatchEvent: vi.fn(),
+  } as unknown as MediaQueryList
+  vi.stubGlobal('matchMedia', vi.fn(() => mediaQuery))
+}
+
+describe('AppLayout', () => {
+  beforeEach(() => {
+    window.localStorage.clear()
+    vi.mocked(ElMessageBox.confirm).mockReset()
+    mockViewport(false)
+  })
+  afterEach(() => vi.unstubAllGlobals())
+
+  it('reports the desktop navigation expanded and collapsed states', async () => {
+    const { wrapper } = await mountLayout()
+    const menuButton = wrapper.get('.shell-menu-button')
+
+    expect(menuButton.attributes('aria-label')).toBe('收起导航')
+    expect(menuButton.attributes('aria-expanded')).toBe('true')
+
+    await menuButton.trigger('click')
+
+    expect(menuButton.attributes('aria-label')).toBe('展开导航')
+    expect(menuButton.attributes('aria-expanded')).toBe('false')
+  })
+
+  it('reports the mobile menu closed and open states', async () => {
+    mockViewport(true)
+    const { wrapper } = await mountLayout()
+    const menuButton = wrapper.get('.shell-menu-button')
+
+    expect(menuButton.attributes('aria-label')).toBe('打开菜单')
+    expect(menuButton.attributes('aria-expanded')).toBe('false')
+
+    await menuButton.trigger('click')
+
+    expect(menuButton.attributes('aria-label')).toBe('关闭菜单')
+    expect(menuButton.attributes('aria-expanded')).toBe('true')
+  })
+
+  it('closes the mobile menu when returning to the desktop breakpoint and removes the listener', async () => {
+    mockViewport(true)
+    const { wrapper } = await mountLayout()
+    const menuButton = wrapper.get('.shell-menu-button')
+    const mediaQuery = vi.mocked(window.matchMedia).mock.results[0]?.value as MediaQueryList
+    const changeHandler = vi.mocked(mediaQuery.addEventListener).mock.calls[0]?.[1] as ((event: MediaQueryListEvent) => void)
+
+    await menuButton.trigger('click')
+    expect(menuButton.attributes('aria-expanded')).toBe('true')
+
+    changeHandler({ matches: false } as MediaQueryListEvent)
+    await wrapper.vm.$nextTick()
+    expect(menuButton.attributes('aria-label')).toBe('收起导航')
+    expect(menuButton.attributes('aria-expanded')).toBe('true')
+
+    wrapper.unmount()
+    expect(mediaQuery.removeEventListener).toHaveBeenCalledWith('change', changeHandler)
+  })
+
+  it('shows the authenticated identity and the localhost full-access control', async () => {
+    const { wrapper } = await mountLayout()
+    expect(wrapper.text()).toContain('登录身份：平台管理员（admin）')
+    const accessToggle = wrapper.get('[role="switch"]')
+    expect(accessToggle.text()).toContain('本地全权限')
+    expect(accessToggle.text()).toContain('已关闭')
+    expect(accessToggle.attributes('aria-checked')).toBe('false')
+    await accessToggle.trigger('click')
+    expect(accessToggle.text()).toContain('已开启')
+    expect(accessToggle.attributes('aria-checked')).toBe('true')
+    expect(wrapper.get('[aria-label="消息中心"]').attributes('disabled')).toBeUndefined()
+    expect(wrapper.text()).toContain('消息管理')
+    expect(wrapper.text()).toContain('模板管理')
+    expect(wrapper.text()).toContain('我的消息')
+    const notificationTrigger = wrapper.get('.notification-trigger')
+    expect(notificationTrigger.find('.notification-count').exists()).toBe(false)
+  })
+
+  it('hides the shell heading when the route opts out', async () => {
+    const { wrapper } = await mountLayout('/customers')
+    expect(wrapper.find('.page-heading').exists()).toBe(false)
+    expect(wrapper.text()).toContain('登录身份：平台管理员（admin）')
+  })
+
+  it('logs out after confirmation', async () => {
+    vi.mocked(ElMessageBox.confirm).mockResolvedValueOnce({} as never)
+    const { wrapper, router } = await mountLayout()
+    await wrapper.get('[aria-label="退出登录"]').trigger('click')
+    await flushPromises()
+    expect(router.currentRoute.value.path).toBe('/login')
+  })
+
+  it('opens business routes as workspace tabs and keeps route component state while switching', async () => {
+    const { wrapper, router } = await mountLayout('/customers')
+    expect(wrapper.find('.workspace-tabs-stub').exists()).toBe(true)
+    await wrapper.get('.cached-count').trigger('click')
+    expect(wrapper.get('.cached-count').text()).toBe('1')
+
+    await router.push('/warehouses')
+    await flushPromises()
+    await router.push('/customers')
+    await flushPromises()
+
+    expect(wrapper.get('.cached-count').text()).toBe('1')
+  })
+})
diff --git a/src/app/layouts/AppLayout.vue b/src/app/layouts/AppLayout.vue
new file mode 100644
index 00000000..ee9b3196
--- /dev/null
+++ b/src/app/layouts/AppLayout.vue
@@ -0,0 +1,222 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import { Bell, FileText, LogOut, Mail, Menu, ShieldCheck } from '@lucide/vue'
+import { getApiErrorDetails } from '@/shared/api/http'
+import baiyueLogoWhite from '@/assets/brand/baiyue-logo-white.png'
+import baiyueMarkWhite from '@/assets/brand/baiyue-mark-white.png'
+import AdminSidebarMenu from '@/app/components/AdminSidebarMenu.vue'
+import WorkspaceTabs from '@/app/components/WorkspaceTabs.vue'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+import { useUnsavedWorkStore } from '@/core/unsaved-work/unsavedWork'
+import { canAccessWorkspaceRoute, workspaceRouteId, workspaceTabCandidate } from '@/core/workspace-tabs/routeWorkspace'
+import { MAX_CACHED_WORKSPACE_VIEWS, useWorkspaceTabsStore } from '@/core/workspace-tabs/workspaceTabs'
+
+const route = useRoute()
+const router = useRouter()
+const auth = useAuthStore()
+const access = useAccessPreviewStore()
+const unsaved = useUnsavedWorkStore()
+const workspace = useWorkspaceTabsStore()
+const mobileViewportQuery = '(max-width: 720px)'
+const collapsed = ref(false)
+const mobileMenuOpen = ref(false)
+const isMobileViewport = ref(false)
+let mobileViewportMedia: MediaQueryList | undefined
+const pageTitle = computed(() => route.meta.title || '管理后台')
+const pageDescription = computed(() => route.meta.description || '')
+const showPageHeading = computed(() => route.meta.showPageHeading !== false)
+const menuCollapsed = computed(() => collapsed.value && !mobileMenuOpen.value)
+const menuButtonLabel = computed(() => {
+  if (isMobileViewport.value) return mobileMenuOpen.value ? '关闭菜单' : '打开菜单'
+  return collapsed.value ? '展开导航' : '收起导航'
+})
+const menuExpanded = computed(() => (
+  isMobileViewport.value ? mobileMenuOpen.value : !collapsed.value
+))
+const canOpenNotificationManagement = computed(() => (
+  access.can('platform:notification:view')
+  || access.can('platform:notification:task:list')
+  || access.can('platform:notification:template:list')
+))
+
+access.initializeAfterLogin()
+workspace.initialize(auth.user?.id || auth.user?.account || '')
+
+function syncCurrentRoute() {
+  const candidate = workspaceTabCandidate(route)
+  if (candidate) workspace.open(candidate, unsaved.dirtyWorkspaceIds)
+}
+
+async function pruneInaccessibleTabs() {
+  const inaccessible = workspace.tabs.filter((tab) => !canAccessWorkspaceRoute(router.resolve(tab.path), access.permissionCodes))
+  const discardedDirtyWork = inaccessible.flatMap((tab) => unsaved.findForWorkspace(tab.id))
+  if (discardedDirtyWork.length) {
+    await ElMessageBox.alert(
+      `账号权限已变化，以下未保存内容无法继续编辑：${[...new Set(discardedDirtyWork.map((entry) => entry.label))].join('、')}。相关页签将关闭。`,
+      '权限已变化',
+      { confirmButtonText: '知道了', type: 'warning', customClass: 'admin-density-confirm' },
+    ).catch(() => undefined)
+  }
+  const previousActiveId = workspace.activeId
+  const result = workspace.prune((tab) => canAccessWorkspaceRoute(router.resolve(tab.path), access.permissionCodes))
+  if (result.removedIds.length === 0) return
+  unsaved.removeWorkspaces(result.removedIds)
+  if (!previousActiveId || !result.removedIds.includes(previousActiveId)) return
+  const destination = result.fallback?.path || access.firstAccessiblePath || '/403'
+  if (destination !== route.fullPath) await router.replace(destination)
+  else syncCurrentRoute()
+}
+
+async function handleLogout() {
+  try {
+    const dirtyLabels = unsaved.entries.filter((entry) => entry.dirty).map((entry) => entry.label)
+    const dirtyNotice = dirtyLabels.length ? ` 当前还有未保存内容：${[...new Set(dirtyLabels)].join('、')}，退出后将丢失。` : ''
+    await ElMessageBox.confirm(`确定退出管理后台吗？${dirtyNotice}`, '退出登录', {
+      confirmButtonText: '退出',
+      customClass: 'admin-density-confirm',
+      cancelButtonText: '取消',
+    })
+  } catch {
+    return
+  }
+
+  access.reset()
+  unsaved.clear()
+  workspace.reset(true)
+  try {
+    await auth.logout()
+  } catch (error) {
+    const details = getApiErrorDetails(error, '服务器会话撤销失败')
+    const trackingId = details.requestId || details.traceId
+    ElMessage.warning(`本地已退出，但服务器会话撤销失败${trackingId ? `（追踪标识：${trackingId}）` : ''}`)
+  }
+  try {
+    await router.replace('/login')
+  } catch {
+    ElMessage.error('已退出登录，但登录页跳转失败，请刷新页面')
+  }
+}
+
+function handleMenuToggle() {
+  if (isMobileViewport.value) {
+    mobileMenuOpen.value = !mobileMenuOpen.value
+    return
+  }
+  collapsed.value = !collapsed.value
+}
+
+function syncMobileViewport(event: MediaQueryList | MediaQueryListEvent) {
+  isMobileViewport.value = event.matches
+  if (!event.matches) mobileMenuOpen.value = false
+}
+
+function openNotificationPage(path: string) { void router.push(path) }
+
+onMounted(() => {
+  mobileViewportMedia = window.matchMedia(mobileViewportQuery)
+  syncMobileViewport(mobileViewportMedia)
+  mobileViewportMedia.addEventListener('change', syncMobileViewport)
+})
+onBeforeUnmount(() => mobileViewportMedia?.removeEventListener('change', syncMobileViewport))
+
+watch(() => route.fullPath, () => {
+  mobileMenuOpen.value = false
+  syncCurrentRoute()
+}, { immediate: true })
+watch(() => access.permissionSignature, () => { void pruneInaccessibleTabs() }, { immediate: true })
+watch(() => auth.user?.id || auth.user?.account || '', (userId, previousUserId) => {
+  if (!userId || userId === previousUserId) return
+  workspace.reset(false)
+  workspace.initialize(userId)
+  void pruneInaccessibleTabs().then(syncCurrentRoute)
+})
+</script>
+
+<template>
+  <div class="app-shell" :class="{ 'is-collapsed': collapsed, 'is-mobile-open': mobileMenuOpen }">
+    <button v-if="mobileMenuOpen" class="sidebar-scrim" type="button" aria-label="关闭菜单" @click="mobileMenuOpen = false" />
+    <aside class="app-sidebar">
+      <div class="brand-block">
+        <img class="brand-logo brand-logo-full" :src="baiyueLogoWhite" alt="柏悦物流" />
+        <img class="brand-logo brand-logo-mark" :src="baiyueMarkWhite" alt="柏悦物流" />
+      </div>
+      <nav class="side-nav" aria-label="主导航">
+        <AdminSidebarMenu :items="access.filteredNavigation" :active-path="route.path" :collapsed="menuCollapsed" />
+      </nav>
+    </aside>
+
+    <div class="app-main">
+      <header class="app-header" :class="{ 'app-header--without-page-heading': !showPageHeading }">
+        <button
+          class="shell-menu-button"
+          type="button"
+          :aria-label="menuButtonLabel"
+          :aria-expanded="menuExpanded"
+          @click="handleMenuToggle"
+        ><Menu :size="22" /></button>
+        <div v-if="showPageHeading" class="page-heading">
+          <!-- <h1>{{ pageTitle }}</h1><p v-if="pageDescription">{{ pageDescription }}</p> -->
+        </div>
+        <div class="header-user">
+          <button
+            v-if="access.localFullAccessAvailable"
+            class="local-full-access-toggle"
+            type="button"
+            role="switch"
+            :aria-checked="access.localFullAccessEnabled"
+            :title="access.localFullAccessEnabled ? '关闭后恢复服务端权限' : '开启后显示全部前端页面和按钮'"
+            @click="access.toggleLocalFullAccess"
+          >
+            <ShieldCheck :size="17" />
+            <span>本地全权限</span>
+            <strong>{{ access.localFullAccessEnabled ? '已开启' : '已关闭' }}</strong>
+          </button>
+          <el-dropdown v-if="canOpenNotificationManagement" trigger="click" placement="bottom-end">
+            <button class="notification-trigger" type="button" aria-label="消息中心">
+              <Bell :size="18" /><span>消息中心</span>
+            </button>
+            <template #dropdown><el-dropdown-menu>
+              <el-dropdown-item v-if="access.can('platform:notification:view')" @click="openNotificationPage('/notifications')"><Bell :size="15" />我的消息</el-dropdown-item>
+              <el-dropdown-item v-if="access.can('platform:notification:task:list')" @click="openNotificationPage('/notifications/messages')"><Mail :size="15" />消息管理</el-dropdown-item>
+              <el-dropdown-item v-if="access.can('platform:notification:template:list')" @click="openNotificationPage('/notifications/templates')"><FileText :size="15" />模板管理</el-dropdown-item>
+            </el-dropdown-menu></template>
+          </el-dropdown>
+          <div class="user-avatar">{{ auth.user?.name.slice(0, 1) }}</div>
+          <div class="user-copy" :aria-label="`登录身份：${auth.user?.name ?? '-'}（${auth.user?.account ?? '-'}）`"><strong>登录身份：{{ auth.user?.name }}（{{ auth.user?.account }}）</strong></div>
+          <el-button text aria-label="退出登录" @click="handleLogout"><LogOut :size="18" /></el-button>
+        </div>
+      </header>
+      <WorkspaceTabs v-if="workspace.tabs.length" />
+      <main class="page-container">
+        <RouterView v-slot="{ Component, route: renderedRoute }">
+          <KeepAlive :max="MAX_CACHED_WORKSPACE_VIEWS">
+            <component
+              :is="Component"
+              v-if="renderedRoute.meta.keepAlive !== false"
+              :key="workspace.cacheKey(workspaceRouteId(renderedRoute)) + ':' + JSON.stringify(renderedRoute.params)"
+            />
+          </KeepAlive>
+          <component :is="Component" v-if="renderedRoute.meta.keepAlive === false" />
+        </RouterView>
+      </main>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.app-header--without-page-heading .header-user { margin-left: auto; }
+.local-full-access-toggle { display: inline-flex; height: 38px; align-items: center; gap: 7px; padding: 0 11px; border: 1px solid rgba(255, 255, 255, .3); border-radius: 10px; background: rgba(255, 255, 255, .12); color: #fff; font: inherit; font-size: 13px; cursor: pointer; transition: background .2s ease, border-color .2s ease; }
+.local-full-access-toggle:hover { border-color: rgba(255, 255, 255, .55); background: rgba(255, 255, 255, .22); }
+.local-full-access-toggle:focus-visible { outline: 2px solid rgba(255, 255, 255, .9); outline-offset: 2px; }
+.local-full-access-toggle[aria-checked="true"] { border-color: #86efac; background: rgba(22, 163, 74, .3); }
+.local-full-access-toggle strong { color: #dcfce7; font-size: 12px; }
+.notification-trigger { display: inline-flex; height: 38px; align-items: center; gap: 7px; padding: 0 12px; border: 1px solid rgba(255, 255, 255, .28); border-radius: 10px; background: rgba(255, 255, 255, .12); color: #fff; font: inherit; font-size: 13px; font-weight: 600; cursor: pointer; transition: background .2s ease, border-color .2s ease, transform .2s ease; }
+.notification-trigger:hover { border-color: rgba(255, 255, 255, .48); background: rgba(255, 255, 255, .24); transform: translateY(-1px); }
+.notification-trigger:focus-visible { outline: 2px solid rgba(255, 255, 255, .9); outline-offset: 2px; }
+.notification-trigger > svg { flex: 0 0 auto; }
+@media (max-width: 720px) { .local-full-access-toggle > span { display: none; } .notification-trigger { width: 44px; height: 44px; justify-content: center; padding: 0; } .notification-trigger > span { display: none; } }
+</style>
diff --git a/src/app/pages/ForbiddenView.test.ts b/src/app/pages/ForbiddenView.test.ts
new file mode 100644
index 00000000..25c4892d
--- /dev/null
+++ b/src/app/pages/ForbiddenView.test.ts
@@ -0,0 +1,19 @@
+import { createPinia, setActivePinia } from 'pinia'
+import { mount } from '@vue/test-utils'
+import { createMemoryHistory, createRouter } from 'vue-router'
+import { describe, expect, it } from 'vitest'
+import ForbiddenView from './ForbiddenView.vue'
+
+describe('ForbiddenView', () => {
+  it('shows server-account guidance and sanitizes the source path', async () => {
+    const pinia = createPinia()
+    setActivePinia(pinia)
+    const router = createRouter({ history: createMemoryHistory(), routes: [{ path: '/403', component: ForbiddenView }] })
+    await router.push({ path: '/403', query: { from: '//example.com' } })
+    await router.isReady()
+    const wrapper = mount(ForbiddenView, { global: { plugins: [pinia, router] } })
+    expect(wrapper.text()).toContain('当前登录账号无法访问此页面')
+    expect(wrapper.text()).toContain('来源页面：/')
+    expect(wrapper.text()).not.toContain('权限预览')
+  })
+})
diff --git a/src/app/pages/ForbiddenView.vue b/src/app/pages/ForbiddenView.vue
new file mode 100644
index 00000000..51c1ad56
--- /dev/null
+++ b/src/app/pages/ForbiddenView.vue
@@ -0,0 +1,28 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { ShieldX } from '@lucide/vue'
+import { useRoute, useRouter } from 'vue-router'
+import { sanitizeInternalPath } from '@/core/routing/accessDecision'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+
+const route = useRoute()
+const router = useRouter()
+const access = useAccessPreviewStore()
+const sourcePath = computed(() => sanitizeInternalPath(route.query.from))
+
+async function returnToAccessiblePage() {
+  if (access.firstAccessiblePath) await router.replace(access.firstAccessiblePath)
+}
+</script>
+
+<template>
+  <section class="forbidden-page" aria-labelledby="forbidden-title">
+    <div class="forbidden-icon" aria-hidden="true"><ShieldX :size="32" /></div>
+    <p class="section-kicker">403 · 权限不足</p>
+    <h2 id="forbidden-title">当前登录账号无法访问此页面</h2>
+    <p>请联系平台管理员核对账号角色和权限配置。</p>
+    <p class="forbidden-source">来源页面：{{ sourcePath }}</p>
+    <el-button v-if="access.firstAccessiblePath" type="primary" @click="returnToAccessiblePage">返回可访问页面</el-button>
+    <p v-else>当前账号暂无可访问的业务菜单。</p>
+  </section>
+</template>
diff --git a/src/app/pages/IntegrationUnavailableView.vue b/src/app/pages/IntegrationUnavailableView.vue
new file mode 100644
index 00000000..ee880eea
--- /dev/null
+++ b/src/app/pages/IntegrationUnavailableView.vue
@@ -0,0 +1,33 @@
+<script setup lang="ts">
+import { Cable } from '@lucide/vue'
+
+defineProps<{
+  moduleName: string
+  description: string
+}>()
+</script>
+
+<template>
+  <section class="surface-panel unavailable-panel" role="status" aria-live="polite">
+    <Cable :size="30" aria-hidden="true" />
+    <p class="section-kicker">接口尚未开放</p>
+    <h2>{{ moduleName }}暂不可用</h2>
+    <p>{{ description }}</p>
+    <p class="secondary-text">为避免产生误导，本页面不会展示演示数据，也不会模拟新增、编辑或导入成功。</p>
+  </section>
+</template>
+
+<style scoped>
+.unavailable-panel {
+  display: grid;
+  justify-items: start;
+  gap: 10px;
+  max-width: 720px;
+  padding: 32px;
+}
+
+.unavailable-panel h2,
+.unavailable-panel p {
+  margin: 0;
+}
+</style>
diff --git a/src/views/ModuleView.vue b/src/app/pages/ModuleView.vue
similarity index 100%
rename from src/views/ModuleView.vue
rename to src/app/pages/ModuleView.vue
diff --git a/src/app/router/index.test.ts b/src/app/router/index.test.ts
new file mode 100644
index 00000000..e936bc4e
--- /dev/null
+++ b/src/app/router/index.test.ts
@@ -0,0 +1,154 @@
+import { describe, expect, it } from 'vitest'
+import { adminNavigation, getNavigationLeaves } from '@/core/navigation/adminNavigation'
+import router from './index'
+
+describe('admin router access metadata', () => {
+  it('uses the root route as a permission-aware entry point and registers the formal dashboard', () => {
+    const home = router.getRoutes().find((route) => route.name === 'home')
+
+    expect(home?.path).toBe('/')
+    expect(home?.meta.permission).toBeUndefined()
+    const dashboard = router.getRoutes().find((route) => route.name === 'dashboard')
+    expect(dashboard?.path).toBe('/dashboard')
+    expect(dashboard?.meta.permission).toBeUndefined()
+  })
+
+  it('protects warehouse management with its stable list permission', () => {
+    const warehouseRoute = router.getRoutes().find((route) => route.name === 'warehouses')
+
+    expect(warehouseRoute?.path).toBe('/warehouses')
+    expect(warehouseRoute?.meta.permission).toBe('platform:warehouse:list')
+  })
+
+  it('protects phase-two inbound operations and master data with deployed permissions', () => {
+    const expected = [
+      ['inbound-orders', '/inbounds', 'platform:firstleg:inbound:list'],
+      ['fba-carrier-rates', '/first-leg-pricing/carrier-rates', 'firstleg:fba-pricing:rate:view'],
+      ['locations', '/master-data/locations', 'platform:location:list'],
+      ['pallets', '/master-data/pallets', 'platform:pallet:list'],
+    ]
+
+    for (const [name, path, permission] of expected) {
+      const route = router.getRoutes().find((item) => item.name === name)
+      expect(route?.path).toBe(path)
+      expect(route?.meta.permission).toBe(permission)
+    }
+  })
+
+  it('does not register removed duplicate pricing and FBA placeholder pages', () => {
+    const removedRouteNames = ['inbound-order-detail', 'fba-customer-rules', 'general-fba', 'general-voyage']
+
+    for (const name of removedRouteNames) {
+      expect(router.getRoutes().some((route) => route.name === name)).toBe(false)
+    }
+  })
+
+  it('protects express company records with a stable master-data permission', () => {
+    const route = router.getRoutes().find((item) => item.name === 'express-companies')
+
+    expect(route?.path).toBe('/master-data/express-companies')
+    expect(route?.meta.permission).toBe('platform:express:list')
+  })
+
+  it('keeps smart loading as an order dialog while retaining the single-container deep link', () => {
+    expect(router.getRoutes().some((item) => item.name === 'global-smart-loading-workbench')).toBe(false)
+    const detail = router.getRoutes().find((item) => item.name === 'smart-loading-workbench')
+    expect(detail?.path).toBe('/container-loading/domestic/:containerId/smart-loading')
+    expect(detail?.meta.permission).toBe('platform:firstleg:smart-loading:list')
+  })
+
+  it('registers the retained phase-three service center routes with stable permissions', () => {
+    const expected = [
+      ['ocean-bookings', '/ocean-bookings', 'platform:firstleg:ocean-booking:list'],
+      ['trucking', '/trucking', 'platform:firstleg:truck-appointment:list'],
+    ]
+
+    for (const [name, path, permission] of expected) {
+      const route = router.getRoutes().find((item) => item.name === name)
+      expect(route?.path).toBe(path)
+      expect(route?.meta.permission).toBe(permission)
+    }
+
+    expect(router.getRoutes().find((item) => item.name === 'port-schedules')).toBeUndefined()
+    expect(router.getRoutes().find((item) => item.name === 'outbound-dispatches')).toBeUndefined()
+  })
+
+  it('protects counterparty records with a stable master-data permission', () => {
+    const route = router.getRoutes().find((item) => item.name === 'counterparties')
+    expect(route?.path).toBe('/master-data/counterparties')
+    expect(route?.meta.permission).toBe('platform:counterparty:list')
+  })
+
+  it('registers the confirmed phase-four routes with stable list permissions', () => {
+    const expected = [
+      ['overseas-last-mile-orders', '/overseas-warehouse/last-mile-orders', 'platform:overseas-warehouse:last-mile-order:list'],
+      ['overseas-inbound-orders', '/overseas-warehouse/inbound-orders', 'platform:overseas-warehouse:inbound-order:list'],
+      ['overseas-dispatches', '/overseas-warehouse/dispatches', 'platform:overseas-warehouse:dispatch:list'],
+      ['overseas-relabel-orders', '/overseas-warehouse/relabel-orders', 'platform:overseas-warehouse:relabel-order:list'],
+      ['overseas-pallets', '/overseas-warehouse/pallets', 'platform:overseas-warehouse:pallet:list'],
+      ['overseas-inventory', '/overseas-warehouse/inventory', 'platform:overseas-warehouse:inventory:list'],
+      ['overseas-business-purchases', '/overseas-business/purchases', 'platform:overseas-business:purchase:list'],
+      ['overseas-business-trucks', '/overseas-business/trucks', 'platform:overseas-business:truck:list'],
+      ['overseas-business-looseboards', '/overseas-business/looseboards', 'platform:overseas-business:looseboard:list'],
+      ['overseas-master-data-quotes', '/overseas-master-data/quotes', 'platform:overseas-master-data:quote:list'],
+      ['overseas-master-data-exchange-rates', '/overseas-master-data/exchange-rates', 'platform:overseas-master-data:exchange-rate:list'],
+      ['overseas-master-data-vehicles', '/overseas-master-data/vehicles', 'platform:overseas-master-data:vehicle:list'],
+    ]
+
+    for (const [name, path, permission] of expected) {
+      const route = router.getRoutes().find((item) => item.name === name)
+      expect(route?.path).toBe(path)
+      expect(route?.meta.permission).toBe(permission)
+    }
+  })
+
+  it('protects the download center with its stable list permission', () => {
+    const route = router.getRoutes().find((item) => item.name === 'download-center')
+    expect(route?.path).toBe('/downloads')
+    expect(route?.meta.permission).toBe('platform:download:list')
+  })
+
+  it('registers message-center routes with the frozen IAM permissions', () => {
+    const expected = [
+      ['notification-inbox', '/notifications', 'platform:notification:view'],
+      ['notification-messages', '/notifications/messages', 'platform:notification:task:list'],
+      ['notification-templates', '/notifications/templates', 'platform:notification:template:list'],
+    ]
+    for (const [name, path, permission] of expected) {
+      const route = router.getRoutes().find((item) => item.name === name)
+      expect(route?.path).toBe(path)
+      expect(route?.meta.permission).toBe(permission)
+    }
+    expect(router.getRoutes().find((item) => item.name === 'my-notifications')).toBeUndefined()
+  })
+
+  it('redirects the removed enterprise review route to the protected customer list', () => {
+    const route = router.getRoutes().find((item) => item.name === 'enterprise-reviews')
+
+    expect(route?.path).toBe('/customers/reviews')
+    expect(route?.redirect).toBe('/customers')
+    expect(route?.meta.permission).toBe('platform:customer:list')
+    expect(route?.meta.permissionAnyOf).toContain('platform:customer:review')
+  })
+
+  it('keeps forbidden inside the authenticated layout without a business permission', () => {
+    const authenticatedLayout = router.options.routes.find((route) => route.path === '/')
+    const forbidden = authenticatedLayout?.children?.find((route) => route.name === 'forbidden')
+    const resolved = router.resolve('/403')
+
+    expect(authenticatedLayout?.meta?.requiresAuth).toBe(true)
+    expect(forbidden?.path).toBe('403')
+    expect(forbidden?.meta?.permission).toBeUndefined()
+    expect(resolved.matched.some((record) => record.meta.requiresAuth)).toBe(true)
+  })
+
+  it('keeps every registered navigation path and permission aligned with routes', () => {
+    for (const item of getNavigationLeaves(adminNavigation)) {
+      const resolved = router.resolve(item.path)
+      const pageRoute = resolved.matched.at(-1)
+
+      expect(pageRoute, `missing route for ${item.path}`).toBeDefined()
+      expect(pageRoute?.meta.permission, `permission mismatch for ${item.path}`).toBe(item.permission)
+    }
+  })
+})
diff --git a/src/app/router/index.ts b/src/app/router/index.ts
new file mode 100644
index 00000000..53cfc762
--- /dev/null
+++ b/src/app/router/index.ts
@@ -0,0 +1,158 @@
+import '@/styles/adminDensity.css'
+import { createRouter, createWebHistory } from 'vue-router'
+import { ElMessageBox } from 'element-plus'
+import AppLayout from '@/app/layouts/AppLayout.vue'
+import { decideRouteAccess } from '@/core/routing/accessDecision'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { downloadRoutes } from '@/modules/downloads/routes'
+import { inboundRoutes } from '@/modules/inbounds/routes'
+import { unifiedOrderRoutes } from '@/modules/unified-orders/routes'
+import { fbaPricingRoutes } from '@/modules/fba-pricing/routes'
+import { iamRoutes } from '@/modules/iam/routes'
+import { masterDataRoutes } from '@/modules/master-data/routes'
+import { warehouseResourceRoutes } from '@/modules/warehouse-resources/routes'
+import { useAuthStore } from '@/core/auth/auth'
+import { useUnsavedWorkStore } from '@/core/unsaved-work/unsavedWork'
+import { canAccessWorkspaceRoute, isWorkspaceRoute, workspaceRouteId } from '@/core/workspace-tabs/routeWorkspace'
+import { readStoredActiveWorkspacePath, useWorkspaceTabsStore } from '@/core/workspace-tabs/workspaceTabs'
+import { customerRoutes } from '@/modules/customers/routes'
+import { dashboardRoutes } from '@/modules/dashboard/routes'
+import { warehouseRoutes } from '@/modules/warehouses/routes'
+import { prototypeModuleRoutes } from '@/prototype/routes'
+import { oceanBookingRoutes } from '@/modules/ocean-bookings/routes'
+import { truckingRoutes } from '@/modules/trucking/routes'
+import { feeItemRoutes } from '@/modules/fee-items/routes'
+import { containerLoadingRoutes } from '@/modules/container-loading/routes'
+import { loadingListRoutes } from '@/modules/loading-lists/routes'
+import { financeRoutes } from '@/modules/finance/routes'
+import { notificationRoutes } from '@/modules/notifications/routes'
+import { domesticContainerRoutes } from '@/modules/domestic-containers/routes'
+import { supplierRoutes } from '@/modules/suppliers/routes'
+import { overseasWarehouseRoutes } from '@/modules/overseas-warehouse/routes'
+import { overseasBusinessRoutes } from '@/modules/overseas-business/routes'
+import { overseasMasterDataRoutes } from '@/modules/overseas-master-data/routes'
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [
+    {
+      path: '/login',
+      name: 'login',
+      component: () => import('@/modules/auth/pages/LoginView.vue'),
+      meta: { title: '登录' },
+    },
+    {
+      path: '/',
+      component: AppLayout,
+      meta: { requiresAuth: true },
+      children: [
+        {
+          path: '',
+          name: 'home',
+          component: () => import('@/app/pages/ModuleView.vue'),
+          meta: { title: '进入管理后台', description: '正在进入当前角色可访问的业务页面', workspaceTab: false, keepAlive: false },
+        },
+        ...dashboardRoutes,
+        ...prototypeModuleRoutes,
+        ...oceanBookingRoutes,
+        ...truckingRoutes,
+        ...containerLoadingRoutes,
+        ...loadingListRoutes,
+        ...financeRoutes,
+        ...notificationRoutes,
+        ...domesticContainerRoutes,
+        ...supplierRoutes,
+        ...overseasWarehouseRoutes,
+        ...overseasBusinessRoutes,
+        ...overseasMasterDataRoutes,
+        ...customerRoutes,
+        ...warehouseRoutes,
+        ...unifiedOrderRoutes,
+        ...inboundRoutes,
+        ...fbaPricingRoutes,
+        ...warehouseResourceRoutes,
+        ...feeItemRoutes,
+        ...masterDataRoutes,
+        ...downloadRoutes,
+        ...iamRoutes,
+        {
+          path: '403',
+          name: 'forbidden',
+          component: () => import('@/app/pages/ForbiddenView.vue'),
+          meta: { title: '权限不足', description: '当前登录账号没有访问此页面的权限', workspaceTab: false, keepAlive: false },
+        },
+      ],
+    },
+    { path: '/:pathMatch(.*)*', redirect: '/' },
+  ],
+})
+
+router.beforeEach(async (to, from) => {
+  const fromId = workspaceRouteId(from)
+  if (!fromId || to.fullPath === from.fullPath) return true
+  const isNonDestructiveWorkspaceSwitch = isWorkspaceRoute(to) && workspaceRouteId(to) !== fromId
+  if (isNonDestructiveWorkspaceSwitch) return true
+
+  const unsaved = useUnsavedWorkStore()
+  const blocking = unsaved.findForWorkspace(fromId)
+  if (blocking.length === 0) return true
+  try {
+    await ElMessageBox.confirm(
+      `当前页面还有未保存内容：${[...new Set(blocking.map((entry) => entry.label))].join('、')}。继续后将放弃这些修改。`,
+      '放弃未保存的修改？',
+      { confirmButtonText: '放弃并继续', cancelButtonText: '继续编辑', type: 'warning', customClass: 'admin-density-confirm' },
+    )
+    unsaved.removeWorkspaces([fromId])
+    useWorkspaceTabsStore().bumpCacheEpoch(fromId)
+    return true
+  } catch {
+    return false
+  }
+})
+
+router.beforeEach((to) => {
+  document.title = to.meta.title ? `${to.meta.title} - 柏悦物流管理后台` : '柏悦物流管理后台'
+  const auth = useAuthStore()
+  if (to.name === 'login' && auth.isAuthenticated) {
+    return { name: 'home' }
+  }
+  if (!auth.isAuthenticated && !to.meta.requiresAuth) return true
+
+  const access = useAccessPreviewStore()
+  if (auth.isAuthenticated) access.initializeAfterLogin()
+  const alternativePermissions = to.meta.permissionAnyOf ?? []
+  const requiresRoutePermission = Boolean(to.meta.permission || alternativePermissions.length)
+  const hasRoutePermission = !requiresRoutePermission || Boolean(
+    (to.meta.permission && access.can(to.meta.permission))
+    || alternativePermissions.some((permission) => access.can(permission)),
+  )
+  const decision = decideRouteAccess({
+    requiresAuth: to.meta.requiresAuth,
+    isAuthenticated: auth.isAuthenticated,
+    fullPath: to.fullPath,
+    permission: to.meta.permission ?? alternativePermissions[0],
+    hasPermission: hasRoutePermission,
+  })
+
+  if (decision.type === 'login') {
+    return { name: 'login', query: { redirect: decision.redirect } }
+  }
+  if (decision.type === 'forbidden') {
+    return { name: 'forbidden', query: { from: decision.from }, replace: true }
+  }
+  if (to.name === 'home') {
+    const restoredPath = auth.user?.id ? readStoredActiveWorkspacePath(auth.user.id) : null
+    if (restoredPath) {
+      const restoredRoute = router.resolve(restoredPath)
+      if (canAccessWorkspaceRoute(restoredRoute, access.permissionCodes)) {
+        return { path: restoredPath, replace: true }
+      }
+    }
+    return access.firstAccessiblePath
+      ? { path: access.firstAccessiblePath, replace: true }
+      : { name: 'forbidden', replace: true }
+  }
+  return true
+})
+
+export default router
diff --git a/src/router/meta.d.ts b/src/app/router/meta.d.ts
similarity index 74%
rename from src/router/meta.d.ts
rename to src/app/router/meta.d.ts
index af6661fd..e96e7dc2 100644
--- a/src/router/meta.d.ts
+++ b/src/app/router/meta.d.ts
@@ -4,7 +4,9 @@ declare module 'vue-router' {
   interface RouteMeta {
     title?: string
     description?: string
+    showPageHeading?: boolean
     requiresAuth?: boolean
     permission?: string
+    permissionAnyOf?: string[]
   }
 }
diff --git a/src/assets/brand/baiyue-favicon.png b/src/assets/brand/baiyue-favicon.png
new file mode 100644
index 00000000..e6151c88
Binary files /dev/null and b/src/assets/brand/baiyue-favicon.png differ
diff --git a/src/assets/brand/baiyue-logo-white.png b/src/assets/brand/baiyue-logo-white.png
new file mode 100644
index 00000000..efa7cf17
Binary files /dev/null and b/src/assets/brand/baiyue-logo-white.png differ
diff --git a/src/assets/brand/baiyue-mark-white.png b/src/assets/brand/baiyue-mark-white.png
new file mode 100644
index 00000000..f5dfbcf9
Binary files /dev/null and b/src/assets/brand/baiyue-mark-white.png differ
diff --git a/src/auto-imports.d.ts b/src/auto-imports.d.ts
deleted file mode 100644
index 9d240079..00000000
--- a/src/auto-imports.d.ts
+++ /dev/null
@@ -1,10 +0,0 @@
-/* eslint-disable */
-/* prettier-ignore */
-// @ts-nocheck
-// noinspection JSUnusedGlobalSymbols
-// Generated by unplugin-auto-import
-// biome-ignore lint: disable
-export {}
-declare global {
-
-}
diff --git a/src/components.d.ts b/src/components.d.ts
deleted file mode 100644
index c9d95df8..00000000
--- a/src/components.d.ts
+++ /dev/null
@@ -1,58 +0,0 @@
-/* eslint-disable */
-// @ts-nocheck
-// biome-ignore lint: disable
-// oxlint-disable
-// ------
-// Generated by unplugin-vue-components
-// Read more: https://github.com/vuejs/core/pull/3399
-
-export {}
-
-/* prettier-ignore */
-declare module 'vue' {
-  export interface GlobalComponents {
-    AdminSidebarMenu: typeof import('./components/AdminSidebarMenu.vue')['default']
-    AdminSidebarMenuNode: typeof import('./components/AdminSidebarMenuNode.vue')['default']
-    ApiErrorMeta: typeof import('./components/ApiErrorMeta.vue')['default']
-    ElAlert: typeof import('element-plus/es')['ElAlert']
-    ElButton: typeof import('element-plus/es')['ElButton']
-    ElDatePicker: typeof import('element-plus/es')['ElDatePicker']
-    ElDescriptions: typeof import('element-plus/es')['ElDescriptions']
-    ElDescriptionsItem: typeof import('element-plus/es')['ElDescriptionsItem']
-    ElDialog: typeof import('element-plus/es')['ElDialog']
-    ElDrawer: typeof import('element-plus/es')['ElDrawer']
-    ElDropdown: typeof import('element-plus/es')['ElDropdown']
-    ElDropdownItem: typeof import('element-plus/es')['ElDropdownItem']
-    ElDropdownMenu: typeof import('element-plus/es')['ElDropdownMenu']
-    ElEmpty: typeof import('element-plus/es')['ElEmpty']
-    ElForm: typeof import('element-plus/es')['ElForm']
-    ElFormItem: typeof import('element-plus/es')['ElFormItem']
-    ElInput: typeof import('element-plus/es')['ElInput']
-    ElInputNumber: typeof import('element-plus/es')['ElInputNumber']
-    ElMenu: typeof import('element-plus/es')['ElMenu']
-    ElMenuItem: typeof import('element-plus/es')['ElMenuItem']
-    ElOption: typeof import('element-plus/es')['ElOption']
-    ElPagination: typeof import('element-plus/es')['ElPagination']
-    ElRadioButton: typeof import('element-plus/es')['ElRadioButton']
-    ElRadioGroup: typeof import('element-plus/es')['ElRadioGroup']
-    ElSelect: typeof import('element-plus/es')['ElSelect']
-    ElStep: typeof import('element-plus/es')['ElStep']
-    ElSteps: typeof import('element-plus/es')['ElSteps']
-    ElSubMenu: typeof import('element-plus/es')['ElSubMenu']
-    ElTable: typeof import('element-plus/es')['ElTable']
-    ElTableColumn: typeof import('element-plus/es')['ElTableColumn']
-    ElTag: typeof import('element-plus/es')['ElTag']
-    ElTimeline: typeof import('element-plus/es')['ElTimeline']
-    ElTimelineItem: typeof import('element-plus/es')['ElTimelineItem']
-    ElTree: typeof import('element-plus/es')['ElTree']
-    MetricStrip: typeof import('./components/MetricStrip.vue')['default']
-    RolePreviewSwitcher: typeof import('./components/RolePreviewSwitcher.vue')['default']
-    RouterLink: typeof import('vue-router')['RouterLink']
-    RouterView: typeof import('vue-router')['RouterView']
-    StaticBatchImportDialog: typeof import('./components/StaticBatchImportDialog.vue')['default']
-    StatusBadge: typeof import('./components/StatusBadge.vue')['default']
-  }
-  export interface GlobalDirectives {
-    vLoading: typeof import('element-plus/es')['ElLoadingDirective']
-  }
-}
diff --git a/src/components/AdminSidebarMenu.test.ts b/src/components/AdminSidebarMenu.test.ts
deleted file mode 100644
index 9bab1fc2..00000000
--- a/src/components/AdminSidebarMenu.test.ts
+++ /dev/null
@@ -1,93 +0,0 @@
-import { mount } from '@vue/test-utils'
-import { describe, expect, it } from 'vitest'
-import { adminNavigation, filterAdminNavigation, type AdminNavigationNode } from '@/navigation/adminNavigation'
-import AdminSidebarMenu from './AdminSidebarMenu.vue'
-
-const stubs = {
-  'el-menu': {
-    props: ['defaultActive', 'collapse'],
-    template: '<nav :data-active="defaultActive" :data-collapsed="String(collapse)"><slot /></nav>',
-  },
-  'el-sub-menu': {
-    props: ['index'],
-    template: '<section data-kind="group" :data-index="index"><header><slot name="title" /></header><slot /></section>',
-  },
-  'el-menu-item': {
-    props: ['index'],
-    template: '<a data-kind="item" :data-index="index"><slot name="title" /><slot /></a>',
-  },
-}
-
-describe('AdminSidebarMenu', () => {
-  it('renders grouped page entries and forwards the active route', () => {
-    const wrapper = mount(AdminSidebarMenu, {
-      props: { items: adminNavigation, activePath: '/system/users', collapsed: false },
-      global: { stubs },
-    })
-
-    expect(wrapper.get('nav').attributes('data-active')).toBe('/system/users')
-    expect(wrapper.findAll('[data-kind="group"] header').map((node) => node.text())).toEqual([
-      '业务管理',
-      '基础资料',
-      '系统管理',
-    ])
-    expect(wrapper.findAll('[data-kind="item"]').map((node) => node.attributes('data-index'))).toEqual([
-      '/customers',
-      '/customers/reviews',
-      '/warehouses',
-      '/orders/first-leg',
-      '/master-data/express-companies',
-      '/master-data/counterparties',
-      '/system/users',
-      '/system/roles',
-      '/system/permissions',
-    ])
-  })
-
-  it('forwards desktop collapse state to Element Plus', () => {
-    const wrapper = mount(AdminSidebarMenu, {
-      props: { items: adminNavigation, activePath: '/', collapsed: true },
-      global: { stubs },
-    })
-
-    expect(wrapper.get('nav').attributes('data-collapsed')).toBe('true')
-  })
-
-  it('renders only entries included in the filtered navigation input', () => {
-    const items = filterAdminNavigation(adminNavigation, new Set(['platform:permission:list']))
-    const wrapper = mount(AdminSidebarMenu, {
-      props: { items, activePath: '/', collapsed: false },
-      global: { stubs },
-    })
-
-    expect(wrapper.text()).toContain('菜单权限')
-    expect(wrapper.text()).not.toContain('客户管理')
-  })
-
-  it('recursively renders three navigation levels', () => {
-    const items: AdminNavigationNode[] = [{
-      key: 'operations',
-      title: '运营管理',
-      icon: adminNavigation[0].icon,
-      children: [{
-        key: 'shipment',
-        title: '运输管理',
-        icon: adminNavigation[0].icon,
-        children: [{
-          key: 'tracking',
-          title: '轨迹管理',
-          icon: adminNavigation[0].icon,
-          path: '/tracking',
-          permission: 'tracking:list',
-        }],
-      }],
-    }]
-    const wrapper = mount(AdminSidebarMenu, {
-      props: { items, activePath: '/tracking', collapsed: false },
-      global: { stubs },
-    })
-
-    expect(wrapper.findAll('[data-kind="group"]')).toHaveLength(2)
-    expect(wrapper.get('[data-kind="item"]').attributes('data-index')).toBe('/tracking')
-  })
-})
diff --git a/src/components/AdminSidebarMenu.vue b/src/components/AdminSidebarMenu.vue
deleted file mode 100644
index 86d121b0..00000000
--- a/src/components/AdminSidebarMenu.vue
+++ /dev/null
@@ -1,31 +0,0 @@
-<script setup lang="ts">
-import { computed } from 'vue'
-import type { AdminNavigationNode } from '@/navigation/adminNavigation'
-import AdminSidebarMenuNode from './AdminSidebarMenuNode.vue'
-
-const props = defineProps<{
-  items: AdminNavigationNode[]
-  activePath: string
-  collapsed: boolean
-}>()
-
-function getGroupKeys(nodes: AdminNavigationNode[]): string[] {
-  return nodes.flatMap((node) => node.children?.length
-    ? [node.key, ...getGroupKeys(node.children)]
-    : [])
-}
-
-const defaultOpeneds = computed(() => getGroupKeys(props.items))
-</script>
-
-<template>
-  <el-menu
-    class="side-nav-menu"
-    :default-active="activePath"
-    :collapse="collapsed"
-    :default-openeds="defaultOpeneds"
-    router
-  >
-    <AdminSidebarMenuNode v-for="item in items" :key="item.key" :node="item" />
-  </el-menu>
-</template>
diff --git a/src/components/AdminSidebarMenuNode.vue b/src/components/AdminSidebarMenuNode.vue
deleted file mode 100644
index 548c7044..00000000
--- a/src/components/AdminSidebarMenuNode.vue
+++ /dev/null
@@ -1,25 +0,0 @@
-<script setup lang="ts">
-import type { AdminNavigationNode } from '@/navigation/adminNavigation'
-
-defineOptions({ name: 'AdminSidebarMenuNode' })
-
-defineProps<{
-  node: AdminNavigationNode
-}>()
-</script>
-
-<template>
-  <el-sub-menu v-if="node.children?.length" :index="node.key">
-    <template #title>
-      <component :is="node.icon" :size="19" :stroke-width="1.8" />
-      <span>{{ node.title }}</span>
-    </template>
-
-    <AdminSidebarMenuNode v-for="child in node.children" :key="child.key" :node="child" />
-  </el-sub-menu>
-
-  <el-menu-item v-else :index="node.path || node.key">
-    <component :is="node.icon" :size="19" :stroke-width="1.8" />
-    <template #title>{{ node.title }}</template>
-  </el-menu-item>
-</template>
diff --git a/src/components/ApiErrorMeta.vue b/src/components/ApiErrorMeta.vue
deleted file mode 100644
index 296fc001..00000000
--- a/src/components/ApiErrorMeta.vue
+++ /dev/null
@@ -1,38 +0,0 @@
-<script setup lang="ts">
-import { ElMessage } from 'element-plus'
-import { Copy } from '@lucide/vue'
-import type { ApiErrorDetails } from '@/api/http'
-
-const props = defineProps<{ details: ApiErrorDetails }>()
-
-async function copyIdentifier(value: string, label: string) {
-  try {
-    await navigator.clipboard.writeText(value)
-    ElMessage.success(`${label} 已复制`)
-  } catch {
-    ElMessage.error(`${label} 复制失败，请手动选择复制`)
-  }
-}
-</script>
-
-<template>
-  <div v-if="details.code || details.requestId || details.traceId" class="api-error-meta" aria-label="接口错误追踪信息">
-    <span v-if="details.code" class="api-error-code">{{ details.code }}</span>
-    <button v-if="details.requestId" type="button" :title="`复制请求 ID：${props.details.requestId}`" @click="copyIdentifier(props.details.requestId!, '请求 ID')">
-      <span>请求 ID</span><code>{{ props.details.requestId }}</code><Copy :size="13" />
-    </button>
-    <button v-if="details.traceId" type="button" :title="`复制 Trace ID：${props.details.traceId}`" @click="copyIdentifier(props.details.traceId!, 'Trace ID')">
-      <span>Trace ID</span><code>{{ props.details.traceId }}</code><Copy :size="13" />
-    </button>
-  </div>
-</template>
-
-<style scoped>
-.api-error-meta { display: flex; min-width: 0; flex-wrap: wrap; align-items: center; gap: 6px; margin-top: 8px; }
-.api-error-code { padding: 3px 7px; border-radius: 4px; background: #fee4e2; color: #912018; font-size: 10px; font-weight: 750; }
-.api-error-meta button { display: inline-flex; min-width: 0; max-width: 100%; min-height: 30px; align-items: center; gap: 6px; padding: 4px 7px; border: 1px solid #fecdca; border-radius: 4px; background: #fff; color: #7a271a; cursor: pointer; }
-.api-error-meta button:hover { background: #fff5f4; }
-.api-error-meta button span { flex: 0 0 auto; font-size: 10px; font-weight: 700; }
-.api-error-meta code { min-width: 0; overflow: hidden; color: #b42318; font-family: "Cascadia Code", Consolas, monospace; font-size: 10px; text-overflow: ellipsis; white-space: nowrap; }
-.api-error-meta svg { flex: 0 0 auto; }
-</style>
diff --git a/src/components/RolePreviewSwitcher.test.ts b/src/components/RolePreviewSwitcher.test.ts
deleted file mode 100644
index 6a221d8a..00000000
--- a/src/components/RolePreviewSwitcher.test.ts
+++ /dev/null
@@ -1,63 +0,0 @@
-import { mount } from '@vue/test-utils'
-import { describe, expect, it } from 'vitest'
-import type { Role } from '@/types/admin'
-import RolePreviewSwitcher from './RolePreviewSwitcher.vue'
-
-const roles: Role[] = [
-  { id: 'R001', name: '超级管理员', code: 'SUPER_ADMIN', description: '', userCount: 1, dataScope: '全部数据', status: '启用', permissionIds: [] },
-  { id: 'R003', name: '操作员', code: 'OPERATOR', description: '', userCount: 2, dataScope: '本部门数据', status: '启用', permissionIds: [] },
-]
-
-const stubs = {
-  'el-dropdown': {
-    name: 'ElDropdownStub',
-    emits: ['command'],
-    template: '<section data-dropdown><slot /><slot name="dropdown" /></section>',
-  },
-  'el-dropdown-menu': { template: '<div data-menu><slot /></div>' },
-  'el-dropdown-item': {
-    props: ['command', 'disabled'],
-    template: '<button data-role :data-command="command" :disabled="disabled"><slot /></button>',
-  },
-}
-
-describe('RolePreviewSwitcher', () => {
-  it('announces the active role and explains the static preview boundary', () => {
-    const wrapper = mount(RolePreviewSwitcher, {
-      props: { roles, currentRole: roles[0] },
-      global: { stubs },
-    })
-
-    const trigger = wrapper.get('button[aria-label]')
-    expect(trigger.attributes('aria-label')).toBe('权限预览：超级管理员，数据范围未模拟')
-    expect(trigger.attributes('title')).toBe('权限预览：超级管理员，数据范围未模拟')
-    expect(wrapper.text()).toContain('权限预览：超级管理员')
-    expect(wrapper.text()).toContain('仅预览菜单、页面和操作；数据范围未模拟')
-    expect(wrapper.find('svg.lucide-user-round-cog').exists()).toBe(true)
-  })
-
-  it('disables the current role and emits a string role id for another selection', async () => {
-    const wrapper = mount(RolePreviewSwitcher, {
-      props: { roles, currentRole: roles[0] },
-      global: { stubs },
-    })
-
-    const items = wrapper.findAll('[data-role]')
-    expect(items[0].attributes('disabled')).toBeDefined()
-    expect(items[1].attributes('disabled')).toBeUndefined()
-    wrapper.getComponent({ name: 'ElDropdownStub' }).vm.$emit('command', 3)
-
-    expect(wrapper.emitted('select')).toEqual([['3']])
-  })
-
-  it('labels the trigger when no enabled role is available', () => {
-    const wrapper = mount(RolePreviewSwitcher, {
-      props: { roles: [], currentRole: null },
-      global: { stubs },
-    })
-
-    expect(wrapper.get('button[aria-label]').attributes('aria-label'))
-      .toBe('权限预览：无可用角色，数据范围未模拟')
-  })
-})
-
diff --git a/src/components/RolePreviewSwitcher.vue b/src/components/RolePreviewSwitcher.vue
deleted file mode 100644
index b0f677cd..00000000
--- a/src/components/RolePreviewSwitcher.vue
+++ /dev/null
@@ -1,52 +0,0 @@
-<script setup lang="ts">
-import { computed } from 'vue'
-import { ChevronDown, UserRoundCog } from '@lucide/vue'
-import type { Role } from '@/types/admin'
-
-const props = defineProps<{
-  roles: Role[]
-  currentRole: Role | null
-}>()
-
-const emit = defineEmits<{
-  select: [roleId: string]
-}>()
-
-const roleName = computed(() => props.currentRole?.name ?? '无可用角色')
-const accessibleLabel = computed(() => `权限预览：${roleName.value}，数据范围未模拟`)
-
-function handleCommand(command: string | number) {
-  emit('select', String(command))
-}
-</script>
-
-<template>
-  <el-dropdown :disabled="roles.length === 0" trigger="click" @command="handleCommand">
-    <button
-      class="role-preview-trigger"
-      type="button"
-      :aria-label="accessibleLabel"
-      :title="accessibleLabel"
-    >
-      <UserRoundCog :size="18" aria-hidden="true" />
-      <span class="role-preview-copy">
-        <strong>权限预览：{{ roleName }}</strong>
-        <small>仅预览菜单、页面和操作；数据范围未模拟</small>
-      </span>
-      <ChevronDown :size="15" aria-hidden="true" />
-    </button>
-
-    <template #dropdown>
-      <el-dropdown-menu>
-        <el-dropdown-item
-          v-for="role in roles"
-          :key="role.id"
-          :command="role.id"
-          :disabled="role.id === currentRole?.id"
-        >
-          {{ role.name }}
-        </el-dropdown-item>
-      </el-dropdown-menu>
-    </template>
-  </el-dropdown>
-</template>
diff --git a/src/components/StaticBatchImportDialog.test.ts b/src/components/StaticBatchImportDialog.test.ts
deleted file mode 100644
index b56a95dc..00000000
--- a/src/components/StaticBatchImportDialog.test.ts
+++ /dev/null
@@ -1,19 +0,0 @@
-import { readFileSync } from 'node:fs'
-import { describe, expect, it } from 'vitest'
-
-const source = readFileSync('src/components/StaticBatchImportDialog.vue', 'utf8')
-
-describe('StaticBatchImportDialog source contract', () => {
-  it('only performs safe client-side file checks before the backend endpoint exists', () => {
-    expect(source).toContain("fileName.endsWith('.xlsx')")
-    expect(source).toContain('10 * 1024 * 1024')
-    expect(source).toContain('前端不会解析工作表内容')
-    expect(source).toContain('等待后端导入接口')
-  })
-
-  it('does not simulate server validation or a successful import', () => {
-    expect(source).not.toContain('demonstratesFailure')
-    expect(source).not.toContain('静态演示')
-    expect(source).not.toContain("emit('imported'")
-  })
-})
diff --git a/src/components/StaticBatchImportDialog.vue b/src/components/StaticBatchImportDialog.vue
deleted file mode 100644
index 2e14e890..00000000
--- a/src/components/StaticBatchImportDialog.vue
+++ /dev/null
@@ -1,118 +0,0 @@
-<script setup lang="ts">
-import { computed, ref, watch } from 'vue'
-import { Download, FileCheck2, FileSpreadsheet, Upload, XCircle } from '@lucide/vue'
-
-const props = defineProps<{
-  modelValue: boolean
-  entityLabel: string
-  templateUrl: string
-  templateFileName: string
-}>()
-
-const emit = defineEmits<{
-  'update:modelValue': [value: boolean]
-}>()
-
-type ValidationState = 'idle' | 'pending' | 'ready' | 'invalid'
-
-const inputRef = ref<HTMLInputElement | null>(null)
-const selectedFile = ref<File | null>(null)
-const validationState = ref<ValidationState>('idle')
-const validationMessage = ref('')
-const dialogOpen = computed({ get: () => props.modelValue, set: (value) => emit('update:modelValue', value) })
-
-watch(() => props.modelValue, (open) => {
-  if (open) return
-  selectedFile.value = null
-  validationState.value = 'idle'
-  validationMessage.value = ''
-})
-
-function chooseFile() {
-  inputRef.value?.click()
-}
-
-function handleFile(event: Event) {
-  const input = event.target as HTMLInputElement
-  selectedFile.value = input.files?.[0] ?? null
-  validationState.value = selectedFile.value ? 'pending' : 'idle'
-  validationMessage.value = ''
-  input.value = ''
-}
-
-function validateFile() {
-  const file = selectedFile.value
-  if (!file) return
-  const fileName = file.name.toLowerCase()
-  if (!fileName.endsWith('.xlsx')) {
-    validationMessage.value = '仅支持标准模板 .xlsx 文件'
-    validationState.value = 'invalid'
-    return
-  }
-  if (file.size > 10 * 1024 * 1024) {
-    validationMessage.value = '文件超过上传上限 10MB'
-    validationState.value = 'invalid'
-    return
-  }
-  validationMessage.value = '扩展名和文件大小符合上传要求'
-  validationState.value = 'ready'
-}
-</script>
-
-<template>
-  <el-dialog v-model="dialogOpen" :title="`${entityLabel}批量导入`" width="min(680px, 94vw)" class="batch-import-dialog" :close-on-click-modal="false">
-    <div class="import-guidance">
-      <FileSpreadsheet :size="22" />
-      <div><strong>只新增，不更新或覆盖已有档案</strong><span>前端只检查文件类型和大小；模板内容、重复数据及整批事务由后端校验。</span></div>
-      <a :href="templateUrl" :download="templateFileName"><Download :size="15" />下载标准模板</a>
-    </div>
-
-    <input ref="inputRef" class="visually-hidden" type="file" accept=".xlsx" @change="handleFile" />
-    <button type="button" class="import-dropzone" @click="chooseFile">
-      <Upload :size="24" />
-      <strong>{{ selectedFile ? selectedFile.name : '选择 .xlsx 导入文件' }}</strong>
-      <span>{{ selectedFile ? `${(selectedFile.size / 1024).toFixed(1)} KB · 点击重新选择` : '仅支持 .xlsx，最大 10MB' }}</span>
-    </button>
-
-    <div v-if="validationState === 'pending'" class="import-result is-pending">
-      <FileSpreadsheet :size="20" /><div><strong>文件已选择，等待基础检查</strong><span>点击“检查文件”确认扩展名和文件大小；前端不会解析工作表内容。</span></div>
-    </div>
-    <div v-else-if="validationState === 'ready'" class="import-result is-passed" role="status">
-      <FileCheck2 :size="20" /><div><strong>文件基础检查通过</strong><span>{{ validationMessage }}。后端导入接口尚未提供，文件没有上传，也没有写入任何业务数据。</span></div>
-    </div>
-    <div v-else-if="validationState === 'invalid'" class="import-result is-failed" role="alert">
-      <XCircle :size="20" /><div><strong>文件基础检查未通过</strong><span>{{ validationMessage }}；当前文件没有上传。</span></div>
-    </div>
-
-    <p class="server-boundary">后端接口接入后，此处将展示上传进度、整批校验结果、逐行错误和错误报告下载；任一行错误时后端必须保证 0 行写入。</p>
-
-    <template #footer>
-      <el-button @click="dialogOpen = false">取消</el-button>
-      <el-button :disabled="!selectedFile" @click="validateFile">检查文件</el-button>
-      <el-button type="primary" disabled>等待后端导入接口</el-button>
-    </template>
-  </el-dialog>
-</template>
-
-<style scoped>
-.import-guidance { display: grid; grid-template-columns: auto minmax(0, 1fr) auto; align-items: center; gap: 12px; padding: 14px 16px; background: #f6f8fb; color: var(--cc-primary); }
-.import-guidance > div { display: flex; min-width: 0; flex-direction: column; gap: 3px; }
-.import-guidance strong { color: #172033; font-size: 13px; }
-.import-guidance span { color: var(--cc-muted); font-size: 11px; line-height: 1.55; }
-.import-guidance a { display: inline-flex; align-items: center; gap: 5px; color: var(--cc-primary); font-size: 12px; font-weight: 700; text-decoration: none; }
-.import-dropzone { display: flex; width: 100%; min-height: 132px; margin-top: 16px; align-items: center; justify-content: center; border: 1px dashed #aab6c8; background: #fff; color: var(--cc-primary); cursor: pointer; flex-direction: column; gap: 8px; }
-.import-dropzone:hover { border-color: var(--cc-primary); background: #f8faff; }
-.import-dropzone:focus-visible { outline: 3px solid rgba(21, 94, 239, .2); outline-offset: 2px; }
-.import-dropzone strong { color: #172033; font-size: 13px; }
-.import-dropzone span { color: var(--cc-muted); font-size: 11px; }
-.import-result { display: flex; align-items: center; gap: 10px; margin-top: 14px; padding: 13px 14px; }
-.import-result > div { display: flex; min-width: 0; flex: 1; flex-direction: column; gap: 3px; }
-.import-result strong { font-size: 13px; }
-.import-result span { font-size: 11px; line-height: 1.5; }
-.import-result.is-pending { background: #f5f7fa; color: #475467; }
-.import-result.is-passed { background: #ecf8f2; color: #137a4b; }
-.import-result.is-failed { background: #fff1f1; color: #b42318; }
-.server-boundary { margin: 14px 0 0; color: var(--cc-muted); font-size: 11px; line-height: 1.65; }
-.visually-hidden { position: fixed; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); clip-path: inset(50%); white-space: nowrap; }
-@media (max-width: 600px) { .import-guidance { grid-template-columns: auto 1fr; } .import-guidance a { grid-column: 2; justify-self: start; } }
-</style>
diff --git a/src/components/StatusBadge.vue b/src/components/StatusBadge.vue
deleted file mode 100644
index 1fa0a4e1..00000000
--- a/src/components/StatusBadge.vue
+++ /dev/null
@@ -1,18 +0,0 @@
-<script setup lang="ts">
-import { computed } from 'vue'
-
-const props = defineProps<{ status: string }>()
-
-const tone = computed(() => {
-  if (['正常', '启用', '已完成'].includes(props.status)) return 'success'
-  if (['待审核', '草稿', '待处理'].includes(props.status)) return 'warning'
-  if (['已受理', '已订舱', '运输中', '处理中'].includes(props.status)) return 'info'
-  if (['停用', '已取消', '已驳回', '失败'].includes(props.status)) return 'danger'
-  return 'neutral'
-})
-</script>
-
-<template>
-  <span class="status-badge" :class="`is-${tone}`"><i aria-hidden="true" />{{ status }}</span>
-</template>
-
diff --git a/src/core/access/accessPreview.test.ts b/src/core/access/accessPreview.test.ts
new file mode 100644
index 00000000..4b7c5433
--- /dev/null
+++ b/src/core/access/accessPreview.test.ts
@@ -0,0 +1,55 @@
+import { createPinia, setActivePinia } from 'pinia'
+import { beforeEach, describe, expect, it } from 'vitest'
+import { isLocalFullAccessHost, useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+
+describe('server access store', () => {
+  beforeEach(() => {
+    window.localStorage.clear()
+    setActivePinia(createPinia())
+  })
+
+  it('uses only the authenticated permission snapshot', () => {
+    const auth = useAuthStore()
+    auth.token = 'token'
+    auth.permissions = ['platform:warehouse:list']
+    const access = useAccessPreviewStore()
+    access.initializeAfterLogin()
+
+    expect(access.can('platform:warehouse:list')).toBe(true)
+    expect(access.can('platform:user:list')).toBe(false)
+    expect(access.firstAccessiblePath).toBe('/dashboard')
+  })
+
+  it('keeps only the unprotected dashboard when the server snapshot is empty', () => {
+    const access = useAccessPreviewStore()
+    expect(access.permissionCodes.size).toBe(0)
+    expect(access.filteredNavigation).toHaveLength(1)
+    expect(access.firstAccessiblePath).toBe('/dashboard')
+  })
+
+  it('allows every frontend permission only while the localhost control is enabled', () => {
+    const access = useAccessPreviewStore()
+
+    expect(access.localFullAccessAvailable).toBe(true)
+    expect(access.can('platform:anything:create')).toBe(false)
+
+    access.setLocalFullAccessEnabled(true)
+
+    expect(access.can('platform:anything:create')).toBe(true)
+    expect(access.permissionCodes.has('platform:anything:edit')).toBe(true)
+    expect(access.filteredNavigation.length).toBeGreaterThan(1)
+    expect(window.localStorage.getItem('baiyue-admin-local-full-access')).toBe('true')
+
+    access.setLocalFullAccessEnabled(false)
+    expect(access.can('platform:anything:create')).toBe(false)
+    expect(window.localStorage.getItem('baiyue-admin-local-full-access')).toBeNull()
+  })
+
+  it('recognizes only local preview hosts', () => {
+    expect(isLocalFullAccessHost('localhost')).toBe(true)
+    expect(isLocalFullAccessHost('127.0.0.1')).toBe(true)
+    expect(isLocalFullAccessHost('::1')).toBe(true)
+    expect(isLocalFullAccessHost('admin.example.com')).toBe(false)
+  })
+})
diff --git a/src/core/access/accessPreview.ts b/src/core/access/accessPreview.ts
new file mode 100644
index 00000000..80feb912
--- /dev/null
+++ b/src/core/access/accessPreview.ts
@@ -0,0 +1,82 @@
+import { computed, ref } from 'vue'
+import { defineStore } from 'pinia'
+import {
+  adminNavigation,
+  filterAdminNavigation,
+  getFirstNavigationLeaf,
+} from '@/core/navigation/adminNavigation'
+import { useAuthStore } from '@/core/auth/auth'
+
+const LOCAL_FULL_ACCESS_STORAGE_KEY = 'baiyue-admin-local-full-access'
+
+class LocalFullAccessPermissionSet extends Set<string> {
+  override has(_permissionCode: string): boolean {
+    return true
+  }
+}
+
+export function isLocalFullAccessHost(hostname: string): boolean {
+  return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1'
+}
+
+export const useAccessPreviewStore = defineStore('access-preview', () => {
+  const auth = useAuthStore()
+  const initialized = ref(false)
+  const localFullAccessAvailable = import.meta.env.DEV
+    && typeof window !== 'undefined'
+    && isLocalFullAccessHost(window.location.hostname)
+  const localFullAccessEnabled = ref(
+    localFullAccessAvailable
+    && window.localStorage.getItem(LOCAL_FULL_ACCESS_STORAGE_KEY) === 'true',
+  )
+  const permissionCodes = computed<ReadonlySet<string>>(() => (
+    localFullAccessEnabled.value
+      ? new LocalFullAccessPermissionSet(auth.permissionCodes)
+      : auth.permissionCodes
+  ))
+  const permissionSignature = computed(() => (
+    localFullAccessEnabled.value
+      ? '__LOCAL_FULL_ACCESS__'
+      : [...permissionCodes.value].sort().join('|')
+  ))
+  const filteredNavigation = computed(() => filterAdminNavigation(adminNavigation, permissionCodes.value))
+  const firstAccessiblePath = computed(() => getFirstNavigationLeaf(filteredNavigation.value)?.path ?? null)
+
+  function initializeAfterLogin() {
+    initialized.value = auth.isAuthenticated
+  }
+
+  function can(permissionCode: string): boolean {
+    return permissionCodes.value.has(permissionCode)
+  }
+
+  function setLocalFullAccessEnabled(enabled: boolean) {
+    if (!localFullAccessAvailable) return
+    localFullAccessEnabled.value = enabled
+    if (enabled) window.localStorage.setItem(LOCAL_FULL_ACCESS_STORAGE_KEY, 'true')
+    else window.localStorage.removeItem(LOCAL_FULL_ACCESS_STORAGE_KEY)
+  }
+
+  function toggleLocalFullAccess() {
+    setLocalFullAccessEnabled(!localFullAccessEnabled.value)
+  }
+
+  function reset() {
+    initialized.value = false
+  }
+
+  return {
+    initialized,
+    localFullAccessAvailable,
+    localFullAccessEnabled,
+    permissionCodes,
+    permissionSignature,
+    filteredNavigation,
+    firstAccessiblePath,
+    initializeAfterLogin,
+    can,
+    setLocalFullAccessEnabled,
+    toggleLocalFullAccess,
+    reset,
+  }
+})
diff --git a/src/core/auth/auth.test.ts b/src/core/auth/auth.test.ts
new file mode 100644
index 00000000..ee88a86c
--- /dev/null
+++ b/src/core/auth/auth.test.ts
@@ -0,0 +1,260 @@
+import { createPinia, setActivePinia } from 'pinia'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  post: vi.fn(),
+  listCurrentPlatformPermissionCodes: vi.fn(),
+  refreshHandler: null as null | (() => Promise<string>),
+}))
+
+vi.mock('@/shared/api/http', () => ({
+  http: { post: mocks.post },
+  registerAuthRefreshHandler: (handler: () => Promise<string>) => { mocks.refreshHandler = handler },
+  unwrapApiResponse: <T>(response: { code: string; message: string; data: T }) => {
+    if (response.code !== '200') throw new Error(response.message)
+    return response.data
+  },
+  getApiErrorDetails: (error: { code?: string; message?: string }) => ({
+    message: error.message || '接口请求失败',
+    code: error.code,
+  }),
+}))
+
+vi.mock('./platformAuthorization', () => ({
+  listCurrentPlatformPermissionCodes: mocks.listCurrentPlatformPermissionCodes,
+}))
+
+import { useAuthStore } from './auth'
+
+function createMemoryStorage(): Storage {
+  const values = new Map<string, string>()
+  return {
+    get length() { return values.size },
+    clear: () => values.clear(),
+    getItem: (key) => values.get(key) ?? null,
+    key: (index) => [...values.keys()][index] ?? null,
+    removeItem: (key) => values.delete(key),
+    setItem: (key, value) => values.set(key, value),
+  }
+}
+
+function token(overrides: Record<string, unknown> = {}) {
+  const claims = {
+    user_id: '1000001',
+    username: 'platform_admin',
+    app_code: 'PLATFORM',
+    exp: Math.floor(Date.now() / 1000) + 1800,
+    ...overrides,
+  }
+  const payload = Buffer.from(JSON.stringify(claims)).toString('base64url')
+  return `header.${payload}.signature`
+}
+
+function loginResponse(accessToken = token(), refreshToken = 'refresh-next') {
+  return {
+    code: '200',
+    message: 'success',
+    data: {
+      tokenType: 'Bearer',
+      accessToken,
+      expiresIn: 1800,
+      refreshToken,
+      refreshExpiresIn: 604800,
+      overseasAccessToken: 'overseas-token',
+      overseasExpiresIn: 900,
+    },
+  }
+}
+
+function domesticOnlyLoginResponse() {
+  return {
+    code: '200',
+    message: 'success',
+    data: {
+      tokenType: 'Bearer',
+      accessToken: token(),
+      expiresIn: 1800,
+      refreshToken: 'refresh-domestic',
+      refreshExpiresIn: 604800,
+    },
+  }
+}
+
+describe('admin auth session', () => {
+  beforeEach(() => {
+    vi.stubGlobal('localStorage', createMemoryStorage())
+    setActivePinia(createPinia())
+    mocks.post.mockReset()
+    mocks.listCurrentPlatformPermissionCodes.mockReset()
+    mocks.refreshHandler = null
+  })
+
+  afterEach(() => vi.unstubAllGlobals())
+
+  it('accepts a domestic-only token response when the test environment has no overseas services', async () => {
+    mocks.post.mockResolvedValue(domesticOnlyLoginResponse())
+    mocks.listCurrentPlatformPermissionCodes.mockResolvedValue(['platform:warehouse:list'])
+    const auth = useAuthStore()
+
+    await auth.login('platform_admin', 'password')
+
+    expect(mocks.post).toHaveBeenCalledWith('/auth/login', {
+      loginId: 'platform_admin',
+      password: 'password',
+    })
+    expect(auth.isAuthenticated).toBe(true)
+    expect(auth.refreshToken).toBe('refresh-domestic')
+  })
+
+  it('accepts serialized long lifetimes from the real authentication response', async () => {
+    mocks.post.mockResolvedValue({
+      code: '200',
+      message: 'success',
+      data: {
+        tokenType: 'Bearer',
+        accessToken: token(),
+        expiresIn: '7200',
+        refreshToken: 'refresh-serialized',
+        refreshExpiresIn: '604800',
+        overseasAccessToken: null,
+        overseasExpiresIn: '0',
+      },
+    })
+    mocks.listCurrentPlatformPermissionCodes.mockResolvedValue(['platform:warehouse:list'])
+    const auth = useAuthStore()
+
+    await auth.login('platform_admin', 'password')
+
+    expect(auth.isAuthenticated).toBe(true)
+    expect(auth.refreshToken).toBe('refresh-serialized')
+    expect([...auth.permissionCodes]).toEqual(['platform:warehouse:list'])
+  })
+
+  it('loads permissions from the current authorization endpoint when the JWT only contains identity', async () => {
+    mocks.post.mockResolvedValue(loginResponse())
+    mocks.listCurrentPlatformPermissionCodes.mockResolvedValue(['platform:warehouse:list'])
+    const auth = useAuthStore()
+
+    await auth.login('warehouse_operator', 'password')
+
+    expect(auth.isAuthenticated).toBe(true)
+    expect([...auth.permissionCodes]).toEqual(['platform:warehouse:list'])
+    expect(auth.permissionResources).toEqual([])
+    expect(localStorage.getItem('cc-admin-permission-codes'))
+      .toBe('["platform:warehouse:list"]')
+  })
+
+  it('rejects login and clears the session when the current permission snapshot is unavailable', async () => {
+    mocks.post.mockResolvedValue(loginResponse())
+    mocks.listCurrentPlatformPermissionCodes.mockRejectedValue({ code: 'S0503', message: 'IAM 服务不可用' })
+    const auth = useAuthStore()
+
+    await expect(auth.login('platform_admin', 'password')).rejects.toMatchObject({ code: 'S0503' })
+    expect(auth.isAuthenticated).toBe(false)
+    expect(localStorage.getItem('cc-admin-token')).toBeNull()
+    expect(localStorage.getItem('cc-admin-refresh-token')).toBeNull()
+  })
+
+  it('revokes an issued token pair when the permission snapshot prevents login completion', async () => {
+    mocks.post
+      .mockResolvedValueOnce(loginResponse())
+      .mockResolvedValueOnce({ code: '200', message: 'success', data: null })
+    mocks.listCurrentPlatformPermissionCodes.mockRejectedValue({ code: 'S0503', message: 'IAM 服务不可用' })
+    const auth = useAuthStore()
+
+    await expect(auth.login('platform_admin', 'password')).rejects.toMatchObject({ code: 'S0503' })
+    await Promise.resolve()
+
+    expect(mocks.post).toHaveBeenNthCalledWith(2, '/auth/logout', { refreshToken: 'refresh-next' }, {
+      headers: { Authorization: expect.stringContaining('Bearer header.') },
+    })
+  })
+
+  it('restores an expired access session with the persisted refresh token', async () => {
+    localStorage.setItem('cc-admin-token', token({ exp: Math.floor(Date.now() / 1000) - 30 }))
+    localStorage.setItem('cc-admin-refresh-token', 'refresh-old')
+    mocks.post.mockResolvedValue(loginResponse(token(), 'refresh-rotated'))
+    mocks.listCurrentPlatformPermissionCodes.mockResolvedValue(['platform:warehouse:list'])
+    const auth = useAuthStore()
+
+    await expect(auth.restoreSession()).resolves.toBe(true)
+
+    expect(mocks.post).toHaveBeenCalledWith('/auth/refresh', { refreshToken: 'refresh-old' })
+    expect(auth.refreshToken).toBe('refresh-rotated')
+    expect(auth.isAuthenticated).toBe(true)
+  })
+
+  it('refreshes a valid persisted session so newly granted permissions appear after reload', async () => {
+    localStorage.setItem('cc-admin-token', token())
+    localStorage.setItem('cc-admin-refresh-token', 'refresh-old')
+    localStorage.setItem('cc-admin-permission-codes', '["platform:warehouse:list"]')
+    const refreshedToken = token({
+      token_version: 2,
+    })
+    mocks.post.mockResolvedValue(loginResponse(refreshedToken, 'refresh-rotated'))
+    mocks.listCurrentPlatformPermissionCodes.mockResolvedValue([
+      'platform:warehouse:list',
+      'platform:firstleg:inbound:list',
+    ])
+    const auth = useAuthStore()
+
+    await expect(auth.restoreSession()).resolves.toBe(true)
+
+    expect(mocks.post).toHaveBeenCalledWith('/auth/refresh', { refreshToken: 'refresh-old' })
+    expect([...auth.permissionCodes]).toEqual([
+      'platform:warehouse:list',
+      'platform:firstleg:inbound:list',
+    ])
+    expect(localStorage.getItem('cc-admin-permission-codes'))
+      .toBe('["platform:warehouse:list","platform:firstleg:inbound:list"]')
+  })
+
+  it('reuses a session rotated by another tab without refreshing it again', async () => {
+    const previousToken = token({ token_version: 1 })
+    const rotatedToken = token({ token_version: 2 })
+    localStorage.setItem('cc-admin-token', previousToken)
+    localStorage.setItem('cc-admin-refresh-token', 'refresh-old')
+    localStorage.setItem('cc-admin-permission-codes', '["platform:warehouse:list"]')
+    vi.stubGlobal('navigator', {
+      locks: {
+        request: vi.fn(async (_name: string, _options: LockOptions, callback: () => Promise<void>) => {
+          localStorage.setItem('cc-admin-token', rotatedToken)
+          localStorage.setItem('cc-admin-refresh-token', 'refresh-rotated')
+          localStorage.setItem('cc-admin-permission-codes', '["platform:firstleg:inbound:list"]')
+          return callback()
+        }),
+      },
+    })
+    const auth = useAuthStore()
+
+    await expect(auth.refreshSession()).resolves.toBeUndefined()
+
+    expect(mocks.post).not.toHaveBeenCalled()
+    expect(auth.token).toBe(rotatedToken)
+    expect(auth.refreshToken).toBe('refresh-rotated')
+    expect([...auth.permissionCodes]).toEqual(['platform:firstleg:inbound:list'])
+  })
+
+  it('does not let an in-flight refresh restore a session after logout', async () => {
+    localStorage.setItem('cc-admin-token', token())
+    localStorage.setItem('cc-admin-refresh-token', 'refresh-old')
+    let resolveRefresh: ((value: ReturnType<typeof loginResponse>) => void) | undefined
+    mocks.post.mockImplementation((url: string) => {
+      if (url === '/auth/refresh') {
+        return new Promise((resolve) => { resolveRefresh = resolve })
+      }
+      return Promise.resolve({ code: '200', message: 'success', data: null })
+    })
+    const auth = useAuthStore()
+
+    const refreshing = auth.refreshSession()
+    await Promise.resolve()
+    await auth.logout()
+    resolveRefresh?.(loginResponse(token(), 'refresh-rotated'))
+
+    await expect(refreshing).rejects.toThrow('登录会话已被后续操作替代')
+    expect(auth.isAuthenticated).toBe(false)
+    expect(auth.refreshToken).toBe('')
+    expect(localStorage.getItem('cc-admin-token')).toBeNull()
+  })
+})
diff --git a/src/core/auth/auth.ts b/src/core/auth/auth.ts
new file mode 100644
index 00000000..6d995ae4
--- /dev/null
+++ b/src/core/auth/auth.ts
@@ -0,0 +1,280 @@
+import { computed, ref } from 'vue'
+import { defineStore } from 'pinia'
+import type { CurrentUser } from '@chongchong/shared'
+import {
+  http,
+  registerAuthRefreshHandler,
+  unwrapApiResponse,
+  type ApiEnvelope,
+} from '@/shared/api/http'
+import type { PlatformPermissionResource } from '@/shared/types/platformPermission'
+import { clearOverseasAccessToken, replaceOverseasAccessToken } from '@/shared/api/overseasHttp'
+import { decodeJwtClaims } from './jwt'
+import { listCurrentPlatformPermissionCodes } from './platformAuthorization'
+import { coordinateCrossTabRefresh } from './crossTabRefresh'
+
+const TOKEN_KEY = 'cc-admin-token'
+const REFRESH_TOKEN_KEY = 'cc-admin-refresh-token'
+const PERMISSION_CODES_KEY = 'cc-admin-permission-codes'
+const REFRESH_LOCK_NAME = 'cc-admin-auth-refresh'
+
+interface LoginResponse {
+  tokenType: string
+  accessToken: string
+  expiresIn: number | string
+  refreshToken: string
+  refreshExpiresIn: number | string
+  overseasAccessToken?: string | null
+  overseasExpiresIn?: number | string
+}
+
+class ExpiredAccessTokenError extends Error {}
+class SupersededSessionError extends Error {}
+
+function parseLifetimeSeconds(value: number | string, field: string) {
+  const normalized = typeof value === 'number'
+    ? value
+    : /^\d+$/.test(value.trim()) ? Number(value) : Number.NaN
+  if (!Number.isSafeInteger(normalized) || normalized < 0) {
+    throw new Error(`登录响应中的 ${field} 格式无效`)
+  }
+  return normalized
+}
+
+function sessionFromToken(token: string) {
+  const claims = decodeJwtClaims(token)
+  if (claims.app_code !== 'PLATFORM') throw new Error('账号不属于当前应用端')
+  if (claims.exp && claims.exp * 1000 <= Date.now()) throw new ExpiredAccessTokenError('登录状态已过期')
+  return {
+    user: {
+      id: String(claims.user_id ?? ''),
+      name: claims.username || '平台用户',
+      account: claims.username || '',
+      roles: claims.roles ?? [],
+    } satisfies CurrentUser,
+  }
+}
+
+export const useAuthStore = defineStore('admin-auth', () => {
+  const token = ref(localStorage.getItem(TOKEN_KEY) || '')
+  const refreshToken = ref(localStorage.getItem(REFRESH_TOKEN_KEY) || '')
+  const user = ref<CurrentUser | null>(null)
+  const permissions = ref<string[]>([])
+  const permissionResources = ref<PlatformPermissionResource[]>([])
+  const isServerSession = ref(false)
+  let sessionGeneration = 0
+
+  if (token.value) {
+    try {
+      const session = sessionFromToken(token.value)
+      const cachedPermissions = JSON.parse(localStorage.getItem(PERMISSION_CODES_KEY) || '[]') as unknown
+      if (!Array.isArray(cachedPermissions)) throw new Error('权限缓存格式无效')
+      user.value = session.user
+      permissions.value = cachedPermissions.filter((code): code is string => typeof code === 'string')
+      isServerSession.value = true
+    } catch (error) {
+      token.value = ''
+      localStorage.removeItem(TOKEN_KEY)
+      localStorage.removeItem(PERMISSION_CODES_KEY)
+      if (!(error instanceof ExpiredAccessTokenError) || !refreshToken.value) {
+        refreshToken.value = ''
+        localStorage.removeItem(REFRESH_TOKEN_KEY)
+      }
+    }
+  }
+
+  const isAuthenticated = computed(() => Boolean(token.value))
+  const permissionCodes = computed<ReadonlySet<string>>(() => new Set(permissions.value))
+
+  function ensureCurrentGeneration(expectedGeneration: number) {
+    if (expectedGeneration !== sessionGeneration) {
+      throw new SupersededSessionError('登录会话已被后续操作替代')
+    }
+  }
+
+  function applyPermissionCodes(codes: string[]) {
+    permissions.value = codes
+    localStorage.setItem(PERMISSION_CODES_KEY, JSON.stringify(codes))
+  }
+
+  async function applySession(result: LoginResponse, expectedGeneration: number) {
+    const session = sessionFromToken(result.accessToken)
+    ensureCurrentGeneration(expectedGeneration)
+    replaceOverseasAccessToken(
+      result.overseasAccessToken ?? null,
+      parseLifetimeSeconds(result.overseasExpiresIn ?? 0, 'overseasExpiresIn'),
+    )
+    token.value = result.accessToken
+    refreshToken.value = result.refreshToken
+    user.value = session.user
+    isServerSession.value = true
+    localStorage.setItem(TOKEN_KEY, token.value)
+    localStorage.setItem(REFRESH_TOKEN_KEY, refreshToken.value)
+    try {
+      const activePermissionCodes = await listCurrentPlatformPermissionCodes()
+      ensureCurrentGeneration(expectedGeneration)
+      permissionResources.value = []
+      applyPermissionCodes(activePermissionCodes)
+    } catch (error) {
+      ensureCurrentGeneration(expectedGeneration)
+      throw error
+    }
+  }
+
+  function clearSession() {
+    sessionGeneration += 1
+    clearOverseasAccessToken()
+    token.value = ''
+    refreshToken.value = ''
+    user.value = null
+    permissions.value = []
+    permissionResources.value = []
+    isServerSession.value = false
+    localStorage.removeItem(TOKEN_KEY)
+    localStorage.removeItem(REFRESH_TOKEN_KEY)
+    localStorage.removeItem(PERMISSION_CODES_KEY)
+  }
+
+  function applyStoredSession() {
+    const storedToken = localStorage.getItem(TOKEN_KEY) || ''
+    const storedRefreshToken = localStorage.getItem(REFRESH_TOKEN_KEY) || ''
+    if (!storedToken) {
+      sessionGeneration += 1
+      token.value = ''
+      refreshToken.value = ''
+      user.value = null
+      permissions.value = []
+      permissionResources.value = []
+      isServerSession.value = false
+      return
+    }
+    try {
+      const session = sessionFromToken(storedToken)
+      const cachedPermissions = JSON.parse(localStorage.getItem(PERMISSION_CODES_KEY) || '[]') as unknown
+      if (token.value !== storedToken) clearOverseasAccessToken()
+      token.value = storedToken
+      refreshToken.value = storedRefreshToken
+      user.value = session.user
+      permissions.value = Array.isArray(cachedPermissions)
+        ? cachedPermissions.filter((code): code is string => typeof code === 'string')
+        : []
+      permissionResources.value = []
+      isServerSession.value = true
+    } catch {
+      clearSession()
+    }
+  }
+
+  async function revokeTokenPair(accessToken: string, refreshTokenToRevoke: string) {
+    await http.post('/auth/logout', { refreshToken: refreshTokenToRevoke }, {
+      headers: { Authorization: `Bearer ${accessToken}` },
+    })
+  }
+
+  async function login(account: string, password: string) {
+    const expectedGeneration = ++sessionGeneration
+    try {
+      const response = await http.post<ApiEnvelope<LoginResponse>, ApiEnvelope<LoginResponse>>(
+        '/auth/login',
+        { loginId: account, password },
+      )
+      const result = unwrapApiResponse<LoginResponse>(response)
+      await applySession(result, expectedGeneration)
+    } catch (error) {
+      if (expectedGeneration === sessionGeneration) {
+        const issuedAccessToken = token.value
+        const issuedRefreshToken = refreshToken.value
+        clearSession()
+        if (issuedAccessToken && issuedRefreshToken) {
+          void revokeTokenPair(issuedAccessToken, issuedRefreshToken).catch(() => undefined)
+        }
+      }
+      throw error
+    }
+  }
+
+  async function refreshSession() {
+    const observedRefreshToken = localStorage.getItem(REFRESH_TOKEN_KEY) || refreshToken.value
+    if (!observedRefreshToken) throw new Error('刷新令牌不存在，请重新登录')
+    const expectedGeneration = sessionGeneration
+    try {
+      await coordinateCrossTabRefresh({
+        lockName: REFRESH_LOCK_NAME,
+        observedRefreshToken,
+        currentRefreshToken: () => localStorage.getItem(REFRESH_TOKEN_KEY) || '',
+        reuseCurrentSession: async () => {
+          applyStoredSession()
+          ensureCurrentGeneration(expectedGeneration)
+          if (!token.value || !refreshToken.value) throw new Error('登录状态已过期')
+        },
+        refresh: async (currentRefreshToken) => {
+          const response = await http.post<ApiEnvelope<LoginResponse>, ApiEnvelope<LoginResponse>>(
+            '/auth/refresh',
+            { refreshToken: currentRefreshToken },
+          )
+          ensureCurrentGeneration(expectedGeneration)
+          if (!localStorage.getItem(REFRESH_TOKEN_KEY)) throw new SupersededSessionError('登录会话已在其他标签页退出')
+          await applySession(unwrapApiResponse<LoginResponse>(response), expectedGeneration)
+        },
+      })
+    } catch (error) {
+      if (expectedGeneration === sessionGeneration) clearSession()
+      throw error
+    }
+  }
+
+  async function restoreSession() {
+    if (isAuthenticated.value) {
+      if (!refreshToken.value) return true
+      try {
+        await refreshSession()
+        return true
+      } catch {
+        return false
+      }
+    }
+    if (!refreshToken.value) return false
+    try {
+      await refreshSession()
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  registerAuthRefreshHandler(async () => {
+    await refreshSession()
+    if (!token.value) throw new Error('登录状态刷新失败')
+    return token.value
+  })
+
+  if (typeof window !== 'undefined') {
+    window.addEventListener('storage', (event) => {
+      if ([TOKEN_KEY, REFRESH_TOKEN_KEY, PERMISSION_CODES_KEY].includes(event.key || '')) applyStoredSession()
+    })
+  }
+
+  async function logout() {
+    const accessToken = token.value
+    const tokenToRevoke = refreshToken.value
+    clearSession()
+    if (accessToken && tokenToRevoke) {
+      await revokeTokenPair(accessToken, tokenToRevoke)
+    }
+  }
+
+  return {
+    token,
+    refreshToken,
+    user,
+    permissions,
+    permissionResources,
+    isServerSession,
+    permissionCodes,
+    isAuthenticated,
+    login,
+    refreshSession,
+    restoreSession,
+    logout,
+  }
+})
diff --git a/src/core/auth/crossTabRefresh.test.ts b/src/core/auth/crossTabRefresh.test.ts
new file mode 100644
index 00000000..5aeee799
--- /dev/null
+++ b/src/core/auth/crossTabRefresh.test.ts
@@ -0,0 +1,83 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { coordinateCrossTabRefresh, CrossTabRefreshTimeoutError } from './crossTabRefresh'
+
+afterEach(() => vi.unstubAllGlobals())
+
+describe('cross-tab refresh coordination', () => {
+  it('reuses the rotated session after waiting for another tab', async () => {
+    let currentRefreshToken = 'refresh-old'
+    const refresh = vi.fn()
+    const reuseCurrentSession = vi.fn(async () => 'access-new')
+    vi.stubGlobal('navigator', {
+      locks: {
+        request: vi.fn(async (_name: string, _options: LockOptions, callback: () => Promise<string>) => {
+          currentRefreshToken = 'refresh-new'
+          return callback()
+        }),
+      },
+    })
+
+    await expect(coordinateCrossTabRefresh({
+      lockName: 'admin-refresh',
+      observedRefreshToken: 'refresh-old',
+      currentRefreshToken: () => currentRefreshToken,
+      reuseCurrentSession,
+      refresh,
+    })).resolves.toBe('access-new')
+
+    expect(reuseCurrentSession).toHaveBeenCalledOnce()
+    expect(refresh).not.toHaveBeenCalled()
+  })
+
+  it('performs the refresh when the token has not changed', async () => {
+    const refresh = vi.fn(async () => 'access-new')
+    vi.stubGlobal('navigator', {
+      locks: { request: vi.fn(async (_name: string, _options: LockOptions, callback: () => Promise<string>) => callback()) },
+    })
+
+    await expect(coordinateCrossTabRefresh({
+      lockName: 'admin-refresh',
+      observedRefreshToken: 'refresh-old',
+      currentRefreshToken: () => 'refresh-old',
+      reuseCurrentSession: vi.fn(),
+      refresh,
+    })).resolves.toBe('access-new')
+
+    expect(refresh).toHaveBeenCalledWith('refresh-old')
+  })
+
+  it('does not wait for rotation after the shared session was removed', async () => {
+    const refreshError = new Error('session removed')
+    const refresh = vi.fn(async () => { throw refreshError })
+    vi.stubGlobal('navigator', {})
+
+    await expect(coordinateCrossTabRefresh({
+      lockName: 'admin-refresh',
+      observedRefreshToken: 'refresh-old',
+      currentRefreshToken: () => '',
+      reuseCurrentSession: vi.fn(),
+      refresh,
+    })).rejects.toBe(refreshError)
+
+    expect(refresh).toHaveBeenCalledWith('refresh-old')
+  })
+
+  it('aborts a refresh lock that cannot be acquired', async () => {
+    vi.stubGlobal('navigator', {
+      locks: {
+        request: vi.fn((_name: string, options: LockOptions) => new Promise((_resolve, reject) => {
+          options.signal?.addEventListener('abort', () => reject(options.signal?.reason), { once: true })
+        })),
+      },
+    })
+
+    await expect(coordinateCrossTabRefresh({
+      lockName: 'admin-refresh',
+      lockTimeoutMs: 5,
+      observedRefreshToken: 'refresh-old',
+      currentRefreshToken: () => 'refresh-old',
+      reuseCurrentSession: vi.fn(),
+      refresh: vi.fn(),
+    })).rejects.toBeInstanceOf(CrossTabRefreshTimeoutError)
+  })
+})
diff --git a/src/core/auth/crossTabRefresh.ts b/src/core/auth/crossTabRefresh.ts
new file mode 100644
index 00000000..11252f2a
--- /dev/null
+++ b/src/core/auth/crossTabRefresh.ts
@@ -0,0 +1,56 @@
+export interface CrossTabRefreshOptions<T> {
+  lockName: string
+  lockTimeoutMs?: number
+  observedRefreshToken: string
+  currentRefreshToken: () => string
+  reuseCurrentSession: () => Promise<T>
+  refresh: (refreshToken: string) => Promise<T>
+}
+
+export class CrossTabRefreshTimeoutError extends Error {
+  constructor() {
+    super('登录状态刷新等待超时，请重新登录')
+    this.name = 'CrossTabRefreshTimeoutError'
+  }
+}
+
+const DEFAULT_LOCK_TIMEOUT_MS = 20_000
+
+export async function coordinateCrossTabRefresh<T>(options: CrossTabRefreshOptions<T>): Promise<T> {
+  const run = async () => {
+    const currentRefreshToken = options.currentRefreshToken()
+    if (currentRefreshToken && currentRefreshToken !== options.observedRefreshToken) {
+      return options.reuseCurrentSession()
+    }
+    return options.refresh(currentRefreshToken || options.observedRefreshToken)
+  }
+
+  if (typeof navigator === 'undefined' || !navigator.locks) {
+    try {
+      return await run()
+    } catch (error) {
+      if (!options.currentRefreshToken()) throw error
+      // Web Locks requires a secure context. On plain HTTP, briefly allow another tab's
+      // successful rotation to reach shared storage before treating this session as expired.
+      for (let attempt = 0; attempt < 20; attempt += 1) {
+        await new Promise((resolve) => setTimeout(resolve, 50))
+        const currentRefreshToken = options.currentRefreshToken()
+        if (!currentRefreshToken) throw error
+        if (currentRefreshToken && currentRefreshToken !== options.observedRefreshToken) {
+          return options.reuseCurrentSession()
+        }
+      }
+      throw error
+    }
+  }
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), options.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS)
+  try {
+    return await navigator.locks.request(options.lockName, { signal: controller.signal }, run)
+  } catch (error) {
+    if (controller.signal.aborted) throw new CrossTabRefreshTimeoutError()
+    throw error
+  } finally {
+    clearTimeout(timeout)
+  }
+}
diff --git a/src/utils/jwt.ts b/src/core/auth/jwt.ts
similarity index 100%
rename from src/utils/jwt.ts
rename to src/core/auth/jwt.ts
diff --git a/src/core/auth/platformAuthorization.test.ts b/src/core/auth/platformAuthorization.test.ts
new file mode 100644
index 00000000..396754a9
--- /dev/null
+++ b/src/core/auth/platformAuthorization.test.ts
@@ -0,0 +1,19 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import { listCurrentPlatformPermissionCodes } from './platformAuthorization'
+
+vi.mock('@/shared/api/http', () => ({
+  http: { get: vi.fn() },
+  unwrapApiResponse: <T>(response: { data: T }) => response.data,
+}))
+
+describe('platformAuthorization', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it('loads the current user permission snapshot', async () => {
+    vi.mocked(http.get).mockResolvedValue({ code: '200', message: 'success', data: ['platform:warehouse:list'] })
+
+    await expect(listCurrentPlatformPermissionCodes()).resolves.toEqual(['platform:warehouse:list'])
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/iam/authorization/permissions')
+  })
+})
diff --git a/src/core/auth/platformAuthorization.ts b/src/core/auth/platformAuthorization.ts
new file mode 100644
index 00000000..a7d8ac99
--- /dev/null
+++ b/src/core/auth/platformAuthorization.ts
@@ -0,0 +1,8 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+
+export async function listCurrentPlatformPermissionCodes() {
+  const response = await http.get<ApiEnvelope<string[]>, ApiEnvelope<string[]>>(
+    '/platform/v1/iam/authorization/permissions',
+  )
+  return unwrapApiResponse(response)
+}
diff --git a/src/core/config/runtimeConfig.ts b/src/core/config/runtimeConfig.ts
new file mode 100644
index 00000000..004704d4
--- /dev/null
+++ b/src/core/config/runtimeConfig.ts
@@ -0,0 +1,14 @@
+export type AdminRuntimeConfig = {
+  clientWebUrl?: string
+}
+
+declare global {
+  interface Window {
+    __CHONGCHONG_RUNTIME_CONFIG__?: AdminRuntimeConfig
+  }
+}
+
+export function getClientWebUrl(): string {
+  const runtimeUrl = window.__CHONGCHONG_RUNTIME_CONFIG__?.clientWebUrl
+  return String(runtimeUrl || import.meta.env.VITE_CLIENT_WEB_URL || '').trim()
+}
diff --git a/src/core/dependencyBoundaries.test.ts b/src/core/dependencyBoundaries.test.ts
new file mode 100644
index 00000000..00fcc01a
--- /dev/null
+++ b/src/core/dependencyBoundaries.test.ts
@@ -0,0 +1,48 @@
+import { readdirSync, readFileSync } from 'node:fs'
+import { relative, resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const sourceRoot = resolve(process.cwd(), 'src')
+
+function sourceFiles(directory: string): string[] {
+  return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    const path = resolve(directory, entry.name)
+    if (entry.isDirectory()) return sourceFiles(path)
+    return /\.(ts|vue)$/.test(entry.name) ? [path] : []
+  })
+}
+
+function aliasImports(path: string): string[] {
+  const source = readFileSync(path, 'utf8')
+  return [...source.matchAll(/['"](@\/[^'"]+)['"]/g)].map((match) => match[1])
+}
+
+describe('source dependency boundaries', () => {
+  it('keeps app, core, modules and shared dependencies pointing inward', () => {
+    const violations: string[] = []
+
+    for (const path of sourceFiles(sourceRoot)) {
+      const sourcePath = relative(sourceRoot, path).replaceAll('\\', '/')
+      const sourceModule = sourcePath.match(/^modules\/([^/]+)\//)?.[1]
+
+      for (const dependency of aliasImports(path)) {
+        if (sourcePath.startsWith('shared/') && /^@\/(app|core|modules|prototype)\//.test(dependency)) {
+          violations.push(`${sourcePath} -> ${dependency}`)
+        }
+        if (sourcePath.startsWith('core/') && /^@\/(app|modules|prototype)\//.test(dependency)) {
+          violations.push(`${sourcePath} -> ${dependency}`)
+        }
+        if (sourceModule && /^@\/(app|prototype)\//.test(dependency)) {
+          violations.push(`${sourcePath} -> ${dependency}`)
+        }
+
+        const targetModule = dependency.match(/^@\/modules\/([^/]+)(\/.*)?$/)
+        if (sourceModule && targetModule && targetModule[1] !== sourceModule && targetModule[2]) {
+          violations.push(`${sourcePath} -> ${dependency}`)
+        }
+      }
+    }
+
+    expect(violations).toEqual([])
+  })
+})
diff --git a/src/core/navigation/adminNavigation.test.ts b/src/core/navigation/adminNavigation.test.ts
new file mode 100644
index 00000000..eec419ae
--- /dev/null
+++ b/src/core/navigation/adminNavigation.test.ts
@@ -0,0 +1,332 @@
+import { describe, expect, it } from 'vitest'
+import {
+  adminNavigation,
+  filterAdminNavigation,
+  getFirstNavigationLeaf,
+  getNavigationLeaves,
+  type AdminNavigationNode,
+} from './adminNavigation'
+
+describe('adminNavigation', () => {
+  it('keeps the latest prototype menu skeleton in source order and groups additions under general', () => {
+    expect(adminNavigation.map((item) => item.title)).toEqual([
+      '首页数据看板',
+      '客户管理',
+      '国内仓',
+      '海外派送',
+      '货柜管理',
+      '海外业务',
+      '海外仓',
+      '客户服务',
+      '财务管理',
+      '销售管理',
+      '通用',
+      '系统管理',
+    ])
+    expect(adminNavigation.find((item) => item.key === 'customers')?.children?.map((item) => item.title)).toEqual([
+      '客户列表',
+      '海外仓阶梯费用',
+    ])
+    expect(adminNavigation.find((item) => item.key === 'domestic-warehouse')?.children?.map((item) => item.title)).toEqual([
+      '订单列表',
+      '订单测量',
+      '测量数据审核',
+      '预装清单',
+      '库位管理',
+      '托盘管理',
+      '整柜业务',
+    ])
+    expect(adminNavigation.find((item) => item.key === 'customer-service')?.children?.map((item) => item.title)).toEqual(['异常订单', '客户回访'])
+    expect(adminNavigation.find((item) => item.key === 'supplier-center')).toBeUndefined()
+    expect(adminNavigation.find((item) => item.key === 'container-management')?.children?.map((item) => item.title)).toEqual([
+      '订舱列表',
+      '拖车列表',
+      '送柜报关',
+      '清关提柜',
+    ])
+    expect(adminNavigation.find((item) => item.key === 'overseas-inventory')?.children?.map((item) => item.title)).toEqual([
+      '尾程订单',
+      '入库单',
+      '排车列表',
+      '出库单',
+      '派送单列表',
+      '换标单',
+      '托盘管理',
+      '库存管理',
+      '退货库存管理',
+      '退货箱号管理',
+    ])
+    expect(adminNavigation.find((item) => item.key === 'general')?.children?.map((item) => item.title)).toEqual([
+      '产品信息',
+      '供应商列表',
+      '快递公司',
+      '往来单位',
+      '费用项目',
+      '汇率管理',
+      '仓库管理',
+      '海外仓报价',
+      '船期价格表',
+      '车辆列表',
+      '下载中心',
+    ])
+    expect(adminNavigation.find((item) => item.key === 'notifications')).toBeUndefined()
+    expect(adminNavigation.find((item) => item.key === 'system')?.children?.map((item) => item.title)).toEqual([
+      '用户管理',
+      '角色权限',
+      '租户管理',
+      '品牌设置',
+      '菜单权限',
+    ])
+  })
+
+  it('assigns every page a unique path and only shares permissions backed by the API contract', () => {
+    const leaves = getNavigationLeaves(adminNavigation)
+    const paths = leaves.map((item) => item.path)
+    const permissions = leaves.flatMap((item) => item.permission ? [item.permission] : [])
+
+    expect(paths).toContain('/dashboard')
+    expect(paths).toContain('/orders')
+    expect(paths).not.toContain('/orders/first-leg')
+    expect(paths).not.toContain('/inbounds')
+    expect(paths).not.toContain('/first-leg-pricing/customer-rules')
+    expect(paths).toContain('/downloads')
+    expect(paths).not.toEqual(expect.arrayContaining(['/notifications/messages', '/notifications/templates', '/notifications/mine']))
+    expect(paths).toContain('/master-data/fee-items')
+    expect(paths).toContain('/container-loading/domestic')
+    expect(paths).toContain('/container-loading/overseas')
+    expect(paths).not.toContain('/container-loading/smart-loading')
+    expect(paths).toContain('/loading-plans')
+    expect(paths).not.toContain('/loading-lists')
+    expect(paths).not.toContain('/port-schedules')
+    expect(paths).not.toContain('/customs')
+    expect(paths).not.toContain('/outbound-dispatches')
+    expect(paths).not.toContain('/prototype/container-management/container-list')
+    expect(paths).not.toContain('/prototype/container-management/preload-list')
+    expect(paths).not.toContain('/prototype/container-management/manifest')
+    expect(paths).not.toContain('/prototype/general/fee-items')
+    expect(paths).toEqual(expect.arrayContaining([
+      '/finance/customer-accounts',
+      '/finance/customer-arap',
+      '/finance/receivable-statistics',
+      '/finance/customer-statements',
+      '/finance/settlement-receivables',
+      '/finance/settlement-payables',
+    ]))
+    expect(paths).not.toEqual(expect.arrayContaining(['/finance/bills', '/finance/receipts', '/finance/costs']))
+    expect(paths).toContain('/prototype/system-management/brand-settings')
+    expect(paths).toContain('/system/permissions')
+    expect(new Set(paths).size).toBe(paths.length)
+    const duplicatedPermissions = permissions.filter((permission, index) => permissions.indexOf(permission) !== index)
+    expect(new Set(duplicatedPermissions)).toEqual(new Set())
+    expect(leaves.every((item) => Boolean(item.icon))).toBe(true)
+  })
+
+  it('shows the five formal finance pages plus receivable statistics with real backend permissions', () => {
+    const filtered = filterAdminNavigation(adminNavigation, new Set([
+      'platform:finance:customer-account:list',
+      'platform:finance:customer-arap:list',
+      'platform:finance:receivable-statistics:list',
+      'platform:finance:customer-statement:list',
+      'platform:finance:settlement-ar:list',
+      'platform:finance:settlement-ap:list',
+    ]))
+
+    expect(getNavigationLeaves(filtered).map((item) => item.path).filter((path) => path.startsWith('/finance/'))).toEqual([
+      '/finance/customer-accounts',
+      '/finance/customer-arap',
+      '/finance/receivable-statistics',
+      '/finance/customer-statements',
+      '/finance/settlement-receivables',
+      '/finance/settlement-payables',
+    ])
+  })
+
+  it('shows only the confirmed phase-four pages with their list permissions', () => {
+    const filtered = filterAdminNavigation(adminNavigation, new Set([
+      'platform:overseas-warehouse:last-mile-order:list',
+      'platform:overseas-warehouse:inbound-order:list',
+      'platform:overseas-warehouse:dispatch:list',
+      'platform:overseas-warehouse:outbound:list',
+      'platform:overseas-warehouse:delivery:list',
+      'platform:overseas-warehouse:exception-order:list',
+      'platform:overseas-warehouse:customer-visit:list',
+      'platform:overseas-warehouse:relabel-order:list',
+      'platform:overseas-warehouse:pallet:list',
+      'platform:overseas-warehouse:inventory:list',
+      'platform:overseas-business:purchase:list',
+      'platform:overseas-business:truck:list',
+      'platform:overseas-business:looseboard:list',
+      'platform:overseas-master-data:exchange-rate:list',
+      'platform:overseas-master-data:quote:list',
+      'platform:overseas-master-data:vehicle:list',
+    ]))
+    const paths = getNavigationLeaves(filtered).map((item) => item.path)
+
+    expect(paths).toEqual(expect.arrayContaining([
+      '/overseas-warehouse/last-mile-orders',
+      '/overseas-warehouse/inbound-orders',
+      '/overseas-warehouse/dispatches',
+      '/overseas-warehouse/outbounds',
+      '/overseas-warehouse/delivery-orders',
+      '/overseas-warehouse/exception-orders',
+      '/overseas-warehouse/customer-visits',
+      '/overseas-warehouse/relabel-orders',
+      '/overseas-warehouse/pallets',
+      '/overseas-warehouse/inventory',
+      '/overseas-business/purchases',
+      '/overseas-business/trucks',
+      '/overseas-business/looseboards',
+      '/overseas-master-data/exchange-rates',
+      '/overseas-master-data/quotes',
+      '/overseas-master-data/vehicles',
+    ]))
+    expect(paths).not.toContain('/overseas-warehouse/cartons')
+    expect(paths).not.toContain('/overseas-warehouse/products')
+    expect(paths).toEqual(expect.arrayContaining(['/overseas-warehouse/outbounds', '/overseas-warehouse/delivery-orders']))
+  })
+
+  it('filters protected pages without mutating the source tree', () => {
+    const sourceSnapshot = JSON.stringify(adminNavigation, (key, value) => key === 'icon' ? '[icon]' : value)
+    const filtered = filterAdminNavigation(adminNavigation, new Set(['platform:permission:list']))
+
+    const paths = getNavigationLeaves(filtered).map((item) => item.path)
+    expect(paths).toContain('/system/permissions')
+    expect(paths).not.toContain('/prototype/finance/profit-report')
+    expect(paths).not.toContain('/notifications/messages')
+    expect(paths).not.toContain('/customers')
+    expect(filtered.map((item) => item.title)).toEqual(['首页数据看板', '系统管理'])
+    expect(filtered).not.toBe(adminNavigation)
+    expect(filtered[0]).not.toBe(adminNavigation.find((item) => item.key === 'system'))
+    expect(JSON.stringify(adminNavigation, (key, value) => key === 'icon' ? '[icon]' : value)).toBe(sourceSnapshot)
+  })
+
+  it('keeps hidden prototype nodes out of the live menu while preserving implemented placements', () => {
+    const filtered = filterAdminNavigation(adminNavigation, new Set([
+      'platform:firstleg:inbound:list',
+      'platform:express:list',
+      'platform:counterparty:list',
+      'platform:warehouse:list',
+    ]))
+    const paths = getNavigationLeaves(filtered).map((item) => item.path)
+
+    expect(filtered.map((item) => item.title)).toEqual(['首页数据看板', '国内仓', '通用'])
+    expect(paths).toEqual([
+      '/dashboard',
+      '/orders',
+      '/master-data/express-companies',
+      '/master-data/counterparties',
+      '/warehouses',
+    ])
+    expect(paths).toContain('/dashboard')
+    expect(paths).not.toContain('/orders/first-leg')
+    expect(paths).not.toContain('/prototype/finance/profit-report')
+  })
+
+  it('keeps the merged customer entry for existing review-only roles', () => {
+    const filtered = filterAdminNavigation(adminNavigation, new Set(['platform:customer:review']))
+
+    expect(getNavigationLeaves(filtered).map((item) => item.path)).toContain('/customers')
+  })
+
+  it('shows the formal fee item page only with its view permission', () => {
+    const filtered = filterAdminNavigation(adminNavigation, new Set(['firstleg:fee-item:view']))
+
+    expect(getNavigationLeaves(filtered).map((item) => item.path)).toEqual(['/dashboard', '/master-data/fee-items'])
+  })
+
+  it('shows the public supplier list only with the list permission', () => {
+    const visible = filterAdminNavigation(adminNavigation, new Set(['platform:supplier:list']))
+    const missing = filterAdminNavigation(adminNavigation, new Set())
+
+    expect(getNavigationLeaves(visible).map((item) => item.path)).toEqual(['/dashboard', '/suppliers'])
+    expect(getNavigationLeaves(missing).map((item) => item.path)).toEqual(['/dashboard'])
+  })
+
+  it('shows split container workbenches without a standalone smart-loading menu', () => {
+    const filtered = filterAdminNavigation(adminNavigation, new Set([
+      'platform:firstleg:container:list',
+      'platform:firstleg:preload:list',
+      'platform:firstleg:loading-list:list',
+      'platform:firstleg:terminal-drayage:list',
+    ]))
+
+    expect(getNavigationLeaves(filtered).map((item) => item.path)).toEqual([
+      '/dashboard',
+      '/loading-plans',
+      '/container-loading/domestic',
+      '/container-loading/overseas',
+    ])
+  })
+
+  it('shows only the prototype-backed phase-three service center entries', () => {
+    const filtered = filterAdminNavigation(adminNavigation, new Set([
+      'platform:firstleg:ocean-booking:list',
+      'platform:firstleg:port-schedule:list',
+      'platform:firstleg:truck-appointment:list',
+      'platform:firstleg:customs:list',
+      'platform:firstleg:outbound-dispatch:list',
+    ]))
+
+    expect(getNavigationLeaves(filtered).map((item) => item.path)).toEqual([
+      '/dashboard',
+      '/ocean-bookings',
+      '/trucking',
+    ])
+  })
+
+  it('supports manually hiding a module without removing its route definition', () => {
+    const filtered = filterAdminNavigation([{ key: 'hidden', title: '隐藏模块', icon: adminNavigation[0].icon, path: '/hidden', hidden: true }], new Set())
+
+    expect(filtered).toEqual([])
+  })
+
+  it('keeps directories based on accessible descendants instead of a directory permission', () => {
+    const nodes: AdminNavigationNode[] = [{
+      key: 'operations',
+      title: '运营管理',
+      icon: adminNavigation[0].icon,
+      permission: 'directory:denied',
+      children: [{
+        key: 'tracking',
+        title: '轨迹管理',
+        icon: adminNavigation[0].icon,
+        path: '/tracking',
+        permission: 'tracking:list',
+      }],
+    }]
+
+    const filtered = filterAdminNavigation(nodes, new Set(['tracking:list']))
+
+    expect(filtered).toHaveLength(1)
+    expect(filtered[0].children?.[0].path).toBe('/tracking')
+  })
+
+  it('selects the first fallback leaf in strict depth-first configuration order', () => {
+    const nodes: AdminNavigationNode[] = [{
+      key: 'level-one',
+      title: '一级目录',
+      icon: adminNavigation[0].icon,
+      children: [{
+        key: 'level-two',
+        title: '二级目录',
+        icon: adminNavigation[0].icon,
+        children: [{
+          key: 'tracking',
+          title: '轨迹管理',
+          icon: adminNavigation[0].icon,
+          path: '/tracking',
+          permission: 'tracking:list',
+        }],
+      }, {
+        key: 'reports',
+        title: '报表管理',
+        icon: adminNavigation[0].icon,
+        path: '/reports',
+        permission: 'reports:list',
+      }],
+    }]
+
+    expect(getNavigationLeaves(nodes).map((item) => item.path)).toEqual(['/tracking', '/reports'])
+    expect(getFirstNavigationLeaf(nodes)?.path).toBe('/tracking')
+  })
+})
diff --git a/src/core/navigation/adminNavigation.ts b/src/core/navigation/adminNavigation.ts
new file mode 100644
index 00000000..e4c2b908
--- /dev/null
+++ b/src/core/navigation/adminNavigation.ts
@@ -0,0 +1,220 @@
+import type { Component } from 'vue'
+import {
+  Building2,
+  ContactRound,
+  ClipboardList,
+  CircleDollarSign,
+  Database,
+  Download,
+  FileCheck2,
+  KeyRound,
+  Settings,
+  ShieldCheck,
+  Truck,
+  Users,
+  Warehouse as WarehouseIcon,
+} from '@lucide/vue'
+import {
+  PrototypeContainerIcon,
+  PrototypeCustomerIcon,
+  PrototypeDashboardIcon,
+  PrototypeDeliveryIcon,
+  PrototypeDomesticWarehouseIcon,
+  PrototypeFinanceIcon,
+  PrototypeGeneralIcon,
+  PrototypeOverseasBusinessIcon,
+  PrototypeOverseasWarehouseIcon,
+  PrototypeSalesIcon,
+  PrototypeSystemIcon,
+} from './prototypeMenuIcons'
+
+export interface AdminNavigationNode {
+  key: string
+  title: string
+  icon: Component
+  iconColor?: string
+  path?: string
+  permission?: string
+  permissionAnyOf?: string[]
+  /** Set to true to remove a registered entry from the sidebar without deleting its route. */
+  hidden?: boolean
+  children?: AdminNavigationNode[]
+}
+
+export interface AdminNavigationLeaf extends AdminNavigationNode {
+  path: string
+  permission?: string
+  children?: never
+}
+
+export const adminNavigation: AdminNavigationNode[] = [
+  { key: 'dashboard', title: '首页数据看板', icon: PrototypeDashboardIcon, path: '/dashboard' },
+  {
+    key: 'customers',
+    title: '客户管理',
+    icon: PrototypeCustomerIcon,
+    children: [
+      { key: 'customers-list', title: '客户列表', icon: Building2, path: '/customers', permission: 'platform:customer:list', permissionAnyOf: ['platform:customer:review'] },
+      { key: 'warehouse-tier-fee', title: '海外仓阶梯费用', icon: Building2, path: '/customers/overseas-storage-fees', permission: 'platform:overseas-storage-fee:list' },
+    ],
+  },
+  {
+    key: 'domestic-warehouse',
+    title: '国内仓',
+    icon: PrototypeDomesticWarehouseIcon,
+    children: [
+      { key: 'order-list', title: '订单列表', icon: ClipboardList, path: '/orders', permission: 'platform:order:list', permissionAnyOf: ['platform:firstleg:inbound:list'] },
+      { key: 'inbound-dedup', title: '订单测量', icon: ClipboardList, path: '/inbounds/measurements', permission: 'platform:firstleg:inbound:measure:view' },
+      { key: 'inbound-measure', title: '测量数据审核', icon: FileCheck2, path: '/inbounds/measurement-reviews', permission: 'firstleg:inbound:measurement-review' },
+      { key: 'container-preload', title: '预装清单', icon: ClipboardList, path: '/loading-plans', permission: 'platform:firstleg:preload:list' },
+      { key: 'locations', title: '库位管理', icon: WarehouseIcon, path: '/master-data/locations', permission: 'platform:location:list' },
+      { key: 'pallets', title: '托盘管理', icon: WarehouseIcon, path: '/master-data/pallets', permission: 'platform:pallet:list' },
+      { key: 'domestic-containers', title: '整柜业务', icon: WarehouseIcon, path: '/domestic-containers', permission: 'platform:domestic-container:list' },
+    ],
+  },
+  {
+    key: 'overseas-delivery',
+    title: '海外派送',
+    icon: PrototypeDeliveryIcon,
+    hidden: true,
+    children: [
+      { key: 'outbound-dispatch', title: '派送单列表', icon: Truck, path: '/prototype/overseas-delivery/dispatch-list' },
+      { key: 'outbound-vehicle', title: '排车列表', icon: Truck, path: '/prototype/overseas-delivery/vehicle-scheduling' },
+      { key: 'outbound-bol', title: 'BOL', icon: FileCheck2, path: '/prototype/overseas-delivery/bol' },
+      { key: 'outbound-selfpick', title: '自提单', icon: ClipboardList, path: '/prototype/overseas-delivery/self-pickup' },
+    ],
+  },
+  {
+    key: 'container-management',
+    title: '货柜管理',
+    icon: PrototypeContainerIcon,
+    children: [
+      { key: 'booking-list', title: '订舱列表', icon: ClipboardList, path: '/ocean-bookings', permission: 'platform:firstleg:ocean-booking:list' },
+      { key: 'truck-list', title: '拖车列表', icon: Truck, path: '/trucking', permission: 'platform:firstleg:truck-appointment:list' },
+      { key: 'domestic-container-workbench', title: '送柜报关', icon: WarehouseIcon, path: '/container-loading/domestic', permission: 'platform:firstleg:container:list' },
+      { key: 'overseas-container-workbench', title: '清关提柜', icon: ClipboardList, path: '/container-loading/overseas', permission: 'platform:firstleg:terminal-drayage:list' },
+    ],
+  },
+  {
+    key: 'overseas-business',
+    title: '海外业务',
+    icon: PrototypeOverseasBusinessIcon,
+    children: [
+      { key: 'overseas-purchase', title: '采购订单', icon: ClipboardList, path: '/overseas-business/purchases', permission: 'platform:overseas-business:purchase:list' },
+      { key: 'overseas-truck', title: '本土卡车', icon: Truck, path: '/overseas-business/trucks', permission: 'platform:overseas-business:truck:list' },
+      { key: 'overseas-looseboard', title: '本土散板', icon: ClipboardList, path: '/overseas-business/looseboards', permission: 'platform:overseas-business:looseboard:list' },
+    ],
+  },
+  {
+    key: 'overseas-inventory',
+    title: '海外仓',
+    icon: PrototypeOverseasWarehouseIcon,
+    children: [
+      { key: 'last-mile-orders', title: '尾程订单', icon: ClipboardList, path: '/overseas-warehouse/last-mile-orders', permission: 'platform:overseas-warehouse:last-mile-order:list' },
+      { key: 'fba-inbound-order', title: '入库单', icon: ClipboardList, path: '/overseas-warehouse/inbound-orders', permission: 'platform:overseas-warehouse:inbound-order:list' },
+      { key: 'fba-dispatch', title: '排车列表', icon: Truck, path: '/overseas-warehouse/dispatches', permission: 'platform:overseas-warehouse:dispatch:list' },
+      { key: 'fba-outbound', title: '出库单', icon: ClipboardList, path: '/overseas-warehouse/outbounds', permission: 'platform:overseas-warehouse:outbound:list' },
+      { key: 'fba-delivery', title: '派送单列表', icon: Truck, path: '/overseas-warehouse/delivery-orders', permission: 'platform:overseas-warehouse:delivery:list' },
+      { key: 'fba-relabel-order', title: '换标单', icon: ClipboardList, path: '/overseas-warehouse/relabel-orders', permission: 'platform:overseas-warehouse:relabel-order:list' },
+      { key: 'fba-pallet', title: '托盘管理', icon: WarehouseIcon, path: '/overseas-warehouse/pallets', permission: 'platform:overseas-warehouse:pallet:list' },
+      { key: 'overseas-inventory-list', title: '库存管理', icon: WarehouseIcon, path: '/overseas-warehouse/inventory', permission: 'platform:overseas-warehouse:inventory:list' },
+      { key: 'return-inventory-list', title: '退货库存管理', icon: WarehouseIcon, path: '/overseas-warehouse/return-inventory', permission: 'platform:overseas-warehouse:return-inventory:list' },
+      { key: 'return-cartons-list', title: '退货箱号管理', icon: WarehouseIcon, path: '/overseas-warehouse/return-cartons', permission: 'platform:overseas-warehouse:return-cartons:list' },
+    ],
+  },
+  {
+    key: 'customer-service',
+    title: '客户服务',
+    icon: ContactRound,
+    children: [
+      { key: 'exception-orders', title: '异常订单', icon: ClipboardList, path: '/overseas-warehouse/exception-orders', permission: 'platform:overseas-warehouse:exception-order:list' },
+      { key: 'customer-visits', title: '客户回访', icon: ContactRound, path: '/overseas-warehouse/customer-visits', permission: 'platform:overseas-warehouse:customer-visit:list' },
+    ],
+  },
+  {
+    key: 'finance',
+    title: '财务管理',
+    icon: PrototypeFinanceIcon,
+    children: [
+      { key: 'finance-customer-accounts', title: '客户账户', icon: CircleDollarSign, path: '/finance/customer-accounts', permission: 'platform:finance:customer-account:list' },
+      { key: 'finance-customer-arap', title: '客户应收应付', icon: Database, path: '/finance/customer-arap', permission: 'platform:finance:customer-arap:list' },
+      { key: 'finance-receivable-statistics', title: '应收款统计表', icon: CircleDollarSign, path: '/finance/receivable-statistics', permission: 'platform:finance:receivable-statistics:list' },
+      { key: 'finance-customer-statements', title: '客户对账单', icon: FileCheck2, path: '/finance/customer-statements', permission: 'platform:finance:customer-statement:list' },
+      { key: 'finance-settlement-receivables', title: '结算单应收', icon: CircleDollarSign, path: '/finance/settlement-receivables', permission: 'platform:finance:settlement-ar:list' },
+      { key: 'finance-settlement-payables', title: '结算单应付', icon: Database, path: '/finance/settlement-payables', permission: 'platform:finance:settlement-ap:list' },
+    ],
+  },
+  {
+    key: 'sales',
+    title: '销售管理',
+    icon: PrototypeSalesIcon,
+    hidden: true,
+    children: [
+      { key: 'sales-visits', title: '拜访记录', icon: Users, path: '/prototype/sales/visit-records' },
+      { key: 'sales-commission', title: '销售提成', icon: Database, path: '/prototype/sales/commission' },
+    ],
+  },
+  {
+    key: 'general',
+    title: '通用',
+    icon: PrototypeGeneralIcon,
+    children: [
+      { key: 'general-product', title: '产品信息', icon: Database, path: '/prototype/general/product-information', hidden: true },
+      { key: 'supplier-list', title: '供应商列表', icon: ContactRound, path: '/suppliers', permission: 'platform:supplier:list' },
+      { key: 'express-companies', title: '快递公司', icon: Truck, path: '/master-data/express-companies', permission: 'platform:express:list' },
+      { key: 'counterparties', title: '往来单位', icon: ContactRound, path: '/master-data/counterparties', permission: 'platform:counterparty:list' },
+      { key: 'general-fee', title: '费用项目', icon: Database, path: '/master-data/fee-items', permission: 'firstleg:fee-item:view' },
+      { key: 'exchange-rates', title: '汇率管理', icon: CircleDollarSign, path: '/overseas-master-data/exchange-rates', permission: 'platform:overseas-master-data:exchange-rate:list' },
+      { key: 'warehouses', title: '仓库管理', icon: WarehouseIcon, path: '/warehouses', permission: 'platform:warehouse:list' },
+      { key: 'overseas-quotes', title: '海外仓报价', icon: CircleDollarSign, path: '/overseas-master-data/quotes', permission: 'platform:overseas-master-data:quote:list' },
+      { key: 'fba-carrier-rates', title: '船期价格表', icon: CircleDollarSign, path: '/first-leg-pricing/carrier-rates', permission: 'firstleg:fba-pricing:rate:view' },
+      { key: 'vehicle-list', title: '车辆列表', icon: Truck, path: '/overseas-master-data/vehicles', permission: 'platform:overseas-master-data:vehicle:list' },
+      { key: 'download-center', title: '下载中心', icon: Download, path: '/downloads', permission: 'platform:download:list' },
+    ],
+  },
+  {
+    key: 'system',
+    title: '系统管理',
+    icon: PrototypeSystemIcon,
+    children: [
+      { key: 'internal-users', title: '用户管理', icon: Users, path: '/system/users', permission: 'platform:user:list' },
+      { key: 'roles', title: '角色权限', icon: ShieldCheck, path: '/system/roles', permission: 'platform:role:list' },
+      { key: 'tenant-management', title: '租户管理', icon: Building2, path: '/prototype/system-management/tenant-management', hidden: true },
+      { key: 'brand-settings', title: '品牌设置', icon: Settings, path: '/prototype/system-management/brand-settings', hidden: true },
+      { key: 'permissions', title: '菜单权限', icon: KeyRound, path: '/system/permissions', permission: 'platform:permission:list' },
+    ],
+  },
+]
+
+export function getNavigationLeaves(nodes: AdminNavigationNode[]): AdminNavigationLeaf[] {
+  return nodes.flatMap((node) => {
+    if (node.children?.length) return getNavigationLeaves(node.children)
+    if (!node.path) return []
+    return [node as AdminNavigationLeaf]
+  })
+}
+
+export function filterAdminNavigation(
+  nodes: AdminNavigationNode[],
+  permissionCodes: ReadonlySet<string>,
+): AdminNavigationNode[] {
+  return nodes.flatMap((node) => {
+    if (node.hidden) return []
+    if (node.children?.length) {
+      const children = filterAdminNavigation(node.children, permissionCodes)
+      return children.length ? [{ ...node, children }] : []
+    }
+    const alternativePermissions = node.permissionAnyOf ?? []
+    const requiresPermission = Boolean(node.permission || alternativePermissions.length)
+    const hasPermission = !requiresPermission || Boolean(
+      (node.permission && permissionCodes.has(node.permission))
+      || alternativePermissions.some((permission) => permissionCodes.has(permission)),
+    )
+    if (!node.path || !hasPermission) return []
+    return [{ ...node }]
+  })
+}
+
+export function getFirstNavigationLeaf(nodes: AdminNavigationNode[]): AdminNavigationLeaf | null {
+  return getNavigationLeaves(nodes)[0] ?? null
+}
diff --git a/src/core/navigation/prototypeMenuIcons.test.ts b/src/core/navigation/prototypeMenuIcons.test.ts
new file mode 100644
index 00000000..c8ce5a2e
--- /dev/null
+++ b/src/core/navigation/prototypeMenuIcons.test.ts
@@ -0,0 +1,32 @@
+import { mount } from '@vue/test-utils'
+import { describe, expect, it } from 'vitest'
+import {
+  PrototypeCustomerIcon,
+  PrototypeDashboardIcon,
+  PrototypeFinanceIcon,
+} from './prototypeMenuIcons'
+
+describe('prototype menu icons', () => {
+  it('renders the prototype shapes at the requested size', () => {
+    const wrapper = mount(PrototypeDashboardIcon, { props: { size: 22 } })
+
+    expect(wrapper.attributes()).toMatchObject({
+      width: '22',
+      height: '22',
+      viewBox: '0 0 24 24',
+      'aria-hidden': 'true',
+    })
+    expect(wrapper.findAll('rect')).toHaveLength(4)
+    expect(wrapper.findAll('rect').map((node) => node.attributes('fill'))).toEqual([
+      '#1677ff',
+      '#1677ff',
+      '#1677ff',
+      '#1677ff',
+    ])
+  })
+
+  it('preserves the original menu colors', () => {
+    expect(mount(PrototypeCustomerIcon).find('path').attributes('fill')).toBe('#52c41a')
+    expect(mount(PrototypeFinanceIcon).find('circle').attributes('stroke')).toBe('#f5a623')
+  })
+})
diff --git a/src/core/navigation/prototypeMenuIcons.ts b/src/core/navigation/prototypeMenuIcons.ts
new file mode 100644
index 00000000..20f85ce4
--- /dev/null
+++ b/src/core/navigation/prototypeMenuIcons.ts
@@ -0,0 +1,142 @@
+import { defineComponent, h, type Component, type SVGAttributes } from 'vue'
+
+type SvgChild = ReturnType<typeof h>
+
+function createPrototypeMenuIcon(name: string, children: SvgChild[]): Component {
+  return defineComponent({
+    name,
+    inheritAttrs: false,
+    props: {
+      size: { type: [Number, String], default: 20 },
+    },
+    setup(props, { attrs }) {
+      return () => h('svg', {
+        ...attrs,
+        width: props.size,
+        height: props.size,
+        viewBox: '0 0 24 24',
+        fill: 'none',
+        'aria-hidden': 'true',
+      } satisfies SVGAttributes, children)
+    },
+  })
+}
+
+function createOrderDetailIcon(name: string, children: SvgChild[]): Component {
+  return defineComponent({
+    name,
+    inheritAttrs: false,
+    props: { size: { type: [Number, String], default: 20 } },
+    setup(props, { attrs }) {
+      return () => h('svg', {
+        ...attrs,
+        width: props.size,
+        height: props.size,
+        viewBox: '0 0 24 24',
+        fill: 'none',
+        stroke: 'currentColor',
+        'stroke-width': 1.8,
+        'stroke-linecap': 'round',
+        'stroke-linejoin': 'round',
+        'aria-hidden': 'true',
+      } satisfies SVGAttributes, children)
+    },
+  })
+}
+
+export const OrderBasicInfoIcon = createOrderDetailIcon('OrderBasicInfoIcon', [
+  h('path', { d: 'm12 3 8 4.5v9L12 21l-8-4.5v-9L12 3Z' }),
+  h('path', { d: 'm4 7.5 8 4.5 8-4.5M12 12v9' }),
+])
+export const OrderCargoInfoIcon = createOrderDetailIcon('OrderCargoInfoIcon', [
+  h('path', { d: 'm12 3 8 4.5v9L12 21l-8-4.5v-9L12 3Z' }),
+  h('path', { d: 'm4 7.5 8 4.5 8-4.5M12 12v9' }),
+  h('path', { d: 'M8 5.25 16 9.75' }),
+])
+export const OrderFeeInfoIcon = createOrderDetailIcon('OrderFeeInfoIcon', [
+  h('rect', { x: 3, y: 5, width: 18, height: 14, rx: 2 }),
+  h('path', { d: 'M3 9h18M7 14h4' }),
+])
+export const OrderHistoryIcon = createOrderDetailIcon('OrderHistoryIcon', [
+  h('path', { d: 'M3 12a9 9 0 1 0 3-6.7' }),
+  h('path', { d: 'M3 4v5h5M12 7v5l3 2' }),
+])
+export const OrderMeasurementIcon = createOrderDetailIcon('OrderMeasurementIcon', [
+  h('path', { d: 'm4 17 13-13 3 3L7 20H4v-3Z' }),
+  h('path', { d: 'm13 8 3 3M7 17l-1 1M10 14l-1 1M13 11l-1 1' }),
+])
+export const OrderOtherIcon = createOrderDetailIcon('OrderOtherIcon', [
+  h('path', { d: 'M6 3h9l4 4v14H6a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2Z' }),
+  h('path', { d: 'M14 3v5h5' }),
+])
+export const OrderFulfillmentIcon = createOrderDetailIcon('OrderFulfillmentIcon', [
+  h('path', { d: 'M4 6h2M4 12h2M4 18h2M9 6h11M9 12h11M9 18h11' }),
+  h('path', { d: 'm7 11 1.5 1.5L11 10M7 17l1.5 1.5L11 16' }),
+])
+
+export const PrototypeDashboardIcon = createPrototypeMenuIcon('PrototypeDashboardIcon', [
+  h('rect', { x: 3, y: 3, width: 7, height: 8, rx: 1.5, fill: '#1677ff' }),
+  h('rect', { x: 14, y: 3, width: 7, height: 5, rx: 1.5, fill: '#1677ff', opacity: 0.6 }),
+  h('rect', { x: 3, y: 14, width: 7, height: 7, rx: 1.5, fill: '#1677ff', opacity: 0.3 }),
+  h('rect', { x: 14, y: 11, width: 7, height: 10, rx: 1.5, fill: '#1677ff', opacity: 0.8 }),
+])
+
+export const PrototypeCustomerIcon = createPrototypeMenuIcon('PrototypeCustomerIcon', [
+  h('path', { d: 'M3 21h7v-7H3v7zm0-9h7V3H3v9zm11 9h7v-5h-7v5zm0-9h7V3h-7v9z', fill: '#52c41a' }),
+])
+
+export const PrototypeDomesticWarehouseIcon = createPrototypeMenuIcon('PrototypeDomesticWarehouseIcon', [
+  h('path', { d: 'M9 5H7a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2V7a2 2 0 00-2-2h-2M9 5a2 2 0 002 2h2a2 2 0 002-2M9 5a2 2 0 012-2h2a2 2 0 012 2', stroke: '#52c41a', 'stroke-width': 2, 'stroke-linecap': 'round' }),
+  h('path', { d: 'M9 14l2 2 4-4', stroke: '#52c41a', 'stroke-width': 2, 'stroke-linecap': 'round', 'stroke-linejoin': 'round' }),
+])
+
+export const PrototypeOverseasWarehouseIcon = createPrototypeMenuIcon('PrototypeOverseasWarehouseIcon', [
+  h('path', { d: 'M4 12a8 8 0 112.34 5.6', stroke: '#eb2f96', 'stroke-width': 2, 'stroke-linecap': 'round' }),
+  h('path', { d: 'M4 12V7M4 12h5', stroke: '#eb2f96', 'stroke-width': 2, 'stroke-linecap': 'round' }),
+  h('circle', { cx: 12, cy: 12, r: 2.4, fill: '#eb2f96' }),
+])
+
+export const PrototypeDeliveryIcon = createPrototypeMenuIcon('PrototypeDeliveryIcon', [
+  h('path', { d: 'M20 8h-3V4H3c-1.1 0-2 .9-2 2v11h2c0 1.66 1.34 3 3 3s3-1.34 3-3h6c0 1.66 1.34 3 3 3s3-1.34 3-3h2v-5l-3-4zM6 18.5c-.83 0-1.5-.67-1.5-1.5s.67-1.5 1.5-1.5 1.5.67 1.5 1.5-.67 1.5-1.5 1.5zm13.5-9l1.96 2.5H17V9.5h2.5zm-1.5 9c-.83 0-1.5-.67-1.5-1.5s.67-1.5 1.5-1.5 1.5.67 1.5 1.5-.67 1.5-1.5 1.5z', fill: '#1890ff' }),
+])
+
+export const PrototypeServiceIcon = createPrototypeMenuIcon('PrototypeServiceIcon', [
+  h('path', { d: 'M4 6h16v12H4z', stroke: '#722ed1', 'stroke-width': 2 }),
+  h('path', { d: 'M4 10h16M8 14h3', stroke: '#722ed1', 'stroke-width': 2, 'stroke-linecap': 'round' }),
+])
+
+export const PrototypeSupplierIcon = createPrototypeMenuIcon('PrototypeSupplierIcon', [
+  h('path', { d: 'M3 21V9l9-6 9 6v12', stroke: '#eb2f96', 'stroke-width': 2, 'stroke-linejoin': 'round' }),
+  h('path', { d: 'M9 21v-6h6v6', stroke: '#eb2f96', 'stroke-width': 2, 'stroke-linejoin': 'round' }),
+])
+
+export const PrototypeContainerIcon = createPrototypeMenuIcon('PrototypeContainerIcon', [
+  h('rect', { x: 2, y: 3, width: 20, height: 18, rx: 1, stroke: '#52c41a', 'stroke-width': 2 }),
+  h('path', { d: 'M2 8h20M8 3v5M16 3v5', stroke: '#52c41a', 'stroke-width': 2, 'stroke-linecap': 'round' }),
+])
+
+export const PrototypeOverseasBusinessIcon = createPrototypeMenuIcon('PrototypeOverseasBusinessIcon', [
+  h('circle', { cx: 12, cy: 12, r: 9, stroke: '#8c8c8c', 'stroke-width': 1.5 }),
+  h('path', { d: 'M3 12h18M12 3c3 3 3 15 0 18M12 3c-3 3-3 15 0 18', stroke: '#8c8c8c', 'stroke-width': 1.5, 'stroke-linecap': 'round' }),
+])
+
+export const PrototypeFinanceIcon = createPrototypeMenuIcon('PrototypeFinanceIcon', [
+  h('circle', { cx: 12, cy: 12, r: 10, stroke: '#f5a623', 'stroke-width': 2 }),
+  h('path', { d: 'M12 6v6l4 2', stroke: '#f5a623', 'stroke-width': 2, 'stroke-linecap': 'round' }),
+  h('circle', { cx: 12, cy: 12, r: 2, fill: '#f5a623' }),
+])
+
+export const PrototypeSalesIcon = createPrototypeMenuIcon('PrototypeSalesIcon', [
+  h('circle', { cx: 12, cy: 12, r: 10, stroke: '#1677ff', 'stroke-width': 2 }),
+  h('path', { d: 'M12 6v12M6 12h12', stroke: '#1677ff', 'stroke-width': 2, 'stroke-linecap': 'round' }),
+])
+
+export const PrototypeGeneralIcon = createPrototypeMenuIcon('PrototypeGeneralIcon', [
+  h('rect', { x: 3, y: 3, width: 18, height: 18, rx: 2, stroke: '#722ed1', 'stroke-width': 2 }),
+  h('path', { d: 'M8 12h8M12 8v8', stroke: '#722ed1', 'stroke-width': 2, 'stroke-linecap': 'round' }),
+])
+
+export const PrototypeSystemIcon = createPrototypeMenuIcon('PrototypeSystemIcon', [
+  h('circle', { cx: 12, cy: 12, r: 3, fill: '#8c8c8c' }),
+  h('path', { d: 'M12 1v4M12 19v4M4.22 4.22l2.83 2.83M16.95 16.95l2.83 2.83M1 12h4M19 12h4M4.22 19.78l2.83-2.83M16.95 7.05l2.83-2.83', stroke: '#8c8c8c', 'stroke-width': 1.5, 'stroke-linecap': 'round' }),
+])
diff --git a/src/router/accessDecision.test.ts b/src/core/routing/accessDecision.test.ts
similarity index 100%
rename from src/router/accessDecision.test.ts
rename to src/core/routing/accessDecision.test.ts
diff --git a/src/router/accessDecision.ts b/src/core/routing/accessDecision.ts
similarity index 100%
rename from src/router/accessDecision.ts
rename to src/core/routing/accessDecision.ts
diff --git a/src/core/routing/navigationRecovery.test.ts b/src/core/routing/navigationRecovery.test.ts
new file mode 100644
index 00000000..fac05a03
--- /dev/null
+++ b/src/core/routing/navigationRecovery.test.ts
@@ -0,0 +1,80 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+  clearNavigationRecoveryAttempt,
+  isStaleRouteAssetError,
+  recoverNavigationError,
+  type NavigationRecoveryDependencies,
+} from './navigationRecovery'
+
+function memoryStorage() {
+  const values = new Map<string, string>()
+  return {
+    getItem: (key: string) => values.get(key) ?? null,
+    setItem: (key: string, value: string) => values.set(key, value),
+    removeItem: (key: string) => values.delete(key),
+  }
+}
+
+function dependencies(overrides: Partial<NavigationRecoveryDependencies> = {}) {
+  return {
+    storage: memoryStorage(),
+    now: () => 1_000,
+    hasUnsavedWork: () => false,
+    confirmDiscard: vi.fn(async () => true),
+    discardUnsavedWork: vi.fn(),
+    navigate: vi.fn(),
+    showError: vi.fn(),
+    ...overrides,
+  } satisfies NavigationRecoveryDependencies
+}
+
+describe('navigationRecovery', () => {
+  it.each([
+    'Failed to fetch dynamically imported module: /assets/page.js',
+    'Importing a module script failed',
+    'ChunkLoadError: Loading chunk 42 failed',
+    'Loading CSS chunk page failed',
+  ])('recognizes stale deployed route assets: %s', (message) => {
+    expect(isStaleRouteAssetError(new TypeError(message))).toBe(true)
+  })
+
+  it('navigates once to the intended route after a stale lazy chunk fails', async () => {
+    const deps = dependencies()
+    await expect(recoverNavigationError(
+      new TypeError('Failed to fetch dynamically imported module'),
+      '/overseas-warehouse/inventory',
+      deps,
+    )).resolves.toBe(true)
+    expect(deps.discardUnsavedWork).toHaveBeenCalledOnce()
+    expect(deps.navigate).toHaveBeenCalledWith('/overseas-warehouse/inventory')
+    expect(deps.showError).not.toHaveBeenCalled()
+  })
+
+  it('asks before discarding dirty work and stays put when the user cancels', async () => {
+    const deps = dependencies({ hasUnsavedWork: () => true, confirmDiscard: vi.fn(async () => false) })
+    await recoverNavigationError(new Error('Importing a module script failed'), '/system/users', deps)
+    expect(deps.confirmDiscard).toHaveBeenCalledOnce()
+    expect(deps.discardUnsavedWork).not.toHaveBeenCalled()
+    expect(deps.navigate).not.toHaveBeenCalled()
+  })
+
+  it('prevents reload loops and clears the recovery marker after navigation succeeds', async () => {
+    const storage = memoryStorage()
+    const deps = dependencies({ storage })
+    const error = new Error('ChunkLoadError: Loading chunk page failed')
+    await recoverNavigationError(error, '/system/users', deps)
+    await recoverNavigationError(error, '/system/users', deps)
+    expect(deps.navigate).toHaveBeenCalledOnce()
+    expect(deps.showError).toHaveBeenCalledWith('页面资源加载失败，请稍后重试或手动刷新')
+    clearNavigationRecoveryAttempt(storage)
+    await recoverNavigationError(error, '/system/users', deps)
+    expect(deps.navigate).toHaveBeenCalledTimes(2)
+  })
+
+  it('reports ordinary router failures without reloading the application', async () => {
+    const deps = dependencies()
+    await expect(recoverNavigationError(new Error('Unexpected guard failure'), '/customers', deps)).resolves.toBe(false)
+    expect(deps.navigate).not.toHaveBeenCalled()
+    expect(deps.showError).toHaveBeenCalledWith('页面切换失败，请重试')
+  })
+})
diff --git a/src/core/routing/navigationRecovery.ts b/src/core/routing/navigationRecovery.ts
new file mode 100644
index 00000000..9852ab18
--- /dev/null
+++ b/src/core/routing/navigationRecovery.ts
@@ -0,0 +1,74 @@
+const RECOVERY_STORAGE_KEY = 'cc-admin-route-asset-recovery:v1'
+const RECOVERY_WINDOW_MS = 30_000
+
+const staleAssetErrorPatterns = [
+  /failed to fetch dynamically imported module/i,
+  /error loading dynamically imported module/i,
+  /importing a module script failed/i,
+  /chunkloaderror/i,
+  /loading (css )?chunk [\w-]+ failed/i,
+]
+
+export interface NavigationRecoveryDependencies {
+  storage: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>
+  now: () => number
+  hasUnsavedWork: () => boolean
+  confirmDiscard: () => Promise<boolean>
+  discardUnsavedWork: () => void
+  navigate: (target: string) => void
+  showError: (message: string) => void
+}
+
+interface RecoveryAttempt {
+  target: string
+  attemptedAt: number
+}
+
+function errorMessage(error: unknown) {
+  if (error instanceof Error) return error.message
+  return typeof error === 'string' ? error : ''
+}
+
+export function isStaleRouteAssetError(error: unknown) {
+  const message = errorMessage(error)
+  return staleAssetErrorPatterns.some((pattern) => pattern.test(message))
+}
+
+function recentAttempt(dependencies: NavigationRecoveryDependencies, target: string) {
+  try {
+    const parsed = JSON.parse(dependencies.storage.getItem(RECOVERY_STORAGE_KEY) || 'null') as RecoveryAttempt | null
+    return Boolean(parsed
+      && parsed.target === target
+      && dependencies.now() - parsed.attemptedAt < RECOVERY_WINDOW_MS)
+  } catch {
+    return false
+  }
+}
+
+export async function recoverNavigationError(
+  error: unknown,
+  target: string,
+  dependencies: NavigationRecoveryDependencies,
+) {
+  if (!isStaleRouteAssetError(error)) {
+    dependencies.showError('页面切换失败，请重试')
+    return false
+  }
+  if (recentAttempt(dependencies, target)) {
+    dependencies.showError('页面资源加载失败，请稍后重试或手动刷新')
+    return false
+  }
+  if (dependencies.hasUnsavedWork() && !await dependencies.confirmDiscard()) return true
+
+  dependencies.storage.setItem(RECOVERY_STORAGE_KEY, JSON.stringify({
+    target,
+    attemptedAt: dependencies.now(),
+  } satisfies RecoveryAttempt))
+  dependencies.discardUnsavedWork()
+  dependencies.navigate(target)
+  return true
+}
+
+export function clearNavigationRecoveryAttempt(storage: Pick<Storage, 'removeItem'>) {
+  storage.removeItem(RECOVERY_STORAGE_KEY)
+}
diff --git a/src/stores/unsavedWork.test.ts b/src/core/unsaved-work/unsavedWork.test.ts
similarity index 60%
rename from src/stores/unsavedWork.test.ts
rename to src/core/unsaved-work/unsavedWork.test.ts
index a68c7343..921eab07 100644
--- a/src/stores/unsavedWork.test.ts
+++ b/src/core/unsaved-work/unsavedWork.test.ts
@@ -1,6 +1,6 @@
 import { beforeEach, describe, expect, it } from 'vitest'
 import { createPinia, setActivePinia } from 'pinia'
-import { useUnsavedWorkStore } from '@/stores/unsavedWork'
+import { useUnsavedWorkStore } from '@/core/unsaved-work/unsavedWork'
 
 describe('unsaved work store', () => {
   beforeEach(() => {
@@ -71,6 +71,27 @@ describe('unsaved work store', () => {
     }])
   })
 
+  it('does not let an obsolete component remove or overwrite a reclaimed registration', () => {
+    const store = useUnsavedWorkStore()
+    const oldOwner = Symbol('old')
+    const newOwner = Symbol('new')
+    store.claim('customer-form', oldOwner)
+    store.upsert({ key: 'customer-form', label: '旧页面', dirty: true, requiredPermission: null }, oldOwner)
+
+    store.claim('customer-form', newOwner)
+    store.upsert({ key: 'customer-form', label: '新页面', dirty: true, requiredPermission: null }, newOwner)
+    store.remove('customer-form', oldOwner)
+    store.release('customer-form', oldOwner)
+    store.upsert({ key: 'customer-form', label: '过期页面', dirty: false, requiredPermission: null }, oldOwner)
+
+    expect(store.entries).toEqual([{
+      key: 'customer-form',
+      label: '新页面',
+      dirty: true,
+      requiredPermission: null,
+    }])
+  })
+
   it('clears every registered entry', () => {
     const store = useUnsavedWorkStore()
     store.upsert({ key: 'customer-form', label: '客户资料', dirty: true, requiredPermission: null })
@@ -80,4 +101,16 @@ describe('unsaved work store', () => {
 
     expect(store.entries).toEqual([])
   })
+
+  it('finds and removes dirty work owned by a workspace tab', () => {
+    const store = useUnsavedWorkStore()
+    store.upsert({ key: 'customer-form', label: '客户资料', dirty: true, requiredPermission: null, workspaceTabId: 'customers' })
+    store.upsert({ key: 'warehouse-form', label: '仓库资料', dirty: true, requiredPermission: null, workspaceTabId: 'warehouses' })
+
+    expect(store.findForWorkspace('customers').map((entry) => entry.key)).toEqual(['customer-form'])
+    expect(store.dirtyWorkspaceIds).toEqual(new Set(['customers', 'warehouses']))
+
+    store.removeWorkspaces(['customers'])
+    expect(store.entries.map((entry) => entry.key)).toEqual(['warehouse-form'])
+  })
 })
diff --git a/src/core/unsaved-work/unsavedWork.ts b/src/core/unsaved-work/unsavedWork.ts
new file mode 100644
index 00000000..e8e8e0a0
--- /dev/null
+++ b/src/core/unsaved-work/unsavedWork.ts
@@ -0,0 +1,75 @@
+import { computed, ref } from 'vue'
+import { defineStore } from 'pinia'
+
+export interface UnsavedWorkEntry {
+  key: string
+  label: string
+  dirty: boolean
+  requiredPermission: string | null
+  workspaceTabId?: string | null
+}
+
+export const useUnsavedWorkStore = defineStore('unsaved-work', () => {
+  const entries = ref<UnsavedWorkEntry[]>([])
+  const owners = new Map<string, symbol>()
+
+  function claim(key: string, owner: symbol) {
+    owners.set(key, owner)
+  }
+
+  function upsert(entry: UnsavedWorkEntry, owner?: symbol) {
+    if (owner && owners.get(entry.key) !== owner) return
+    const index = entries.value.findIndex((item) => item.key === entry.key)
+    if (index === -1) {
+      entries.value.push(entry)
+      return
+    }
+    entries.value[index] = entry
+  }
+
+  function remove(key: string, owner?: symbol) {
+    if (owner && owners.get(key) !== owner) return
+    if (!owner) owners.delete(key)
+    const index = entries.value.findIndex((item) => item.key === key)
+    if (index !== -1) entries.value.splice(index, 1)
+  }
+
+  function release(key: string, owner: symbol) {
+    if (owners.get(key) !== owner) return
+    owners.delete(key)
+    const index = entries.value.findIndex((item) => item.key === key)
+    if (index !== -1) entries.value.splice(index, 1)
+  }
+
+  function findBlocking(candidatePermissions: ReadonlySet<string>, willLeave: boolean) {
+    return entries.value.filter((entry) => entry.dirty && (
+      willLeave
+      || (entry.requiredPermission !== null && !candidatePermissions.has(entry.requiredPermission))
+    ))
+  }
+
+  function findForWorkspace(workspaceTabId: string) {
+    return entries.value.filter((entry) => entry.dirty && entry.workspaceTabId === workspaceTabId)
+  }
+
+  function removeWorkspaces(workspaceTabIds: readonly string[]) {
+    const ids = new Set(workspaceTabIds)
+    entries.value
+      .filter((entry) => entry.workspaceTabId && ids.has(entry.workspaceTabId))
+      .forEach((entry) => owners.delete(entry.key))
+    entries.value = entries.value.filter((entry) => !entry.workspaceTabId || !ids.has(entry.workspaceTabId))
+  }
+
+  function clear() {
+    owners.clear()
+    entries.value = []
+  }
+
+  const dirtyWorkspaceIds = computed<ReadonlySet<string>>(() => new Set(
+    entries.value
+      .filter((entry) => entry.dirty && entry.workspaceTabId)
+      .map((entry) => entry.workspaceTabId as string),
+  ))
+
+  return { entries, dirtyWorkspaceIds, claim, upsert, remove, release, findBlocking, findForWorkspace, removeWorkspaces, clear }
+})
diff --git a/src/composables/useUnsavedWorkRegistration.test.ts b/src/core/unsaved-work/useUnsavedWorkRegistration.test.ts
similarity index 93%
rename from src/composables/useUnsavedWorkRegistration.test.ts
rename to src/core/unsaved-work/useUnsavedWorkRegistration.test.ts
index acdfb15d..463283a7 100644
--- a/src/composables/useUnsavedWorkRegistration.test.ts
+++ b/src/core/unsaved-work/useUnsavedWorkRegistration.test.ts
@@ -2,8 +2,8 @@ import { computed, defineComponent, nextTick, reactive, ref } from 'vue'
 import { mount } from '@vue/test-utils'
 import { beforeEach, describe, expect, it } from 'vitest'
 import { createPinia, setActivePinia } from 'pinia'
-import { useUnsavedWorkRegistration } from '@/composables/useUnsavedWorkRegistration'
-import { useUnsavedWorkStore } from '@/stores/unsavedWork'
+import { useUnsavedWorkRegistration } from '@/core/unsaved-work/useUnsavedWorkRegistration'
+import { useUnsavedWorkStore } from '@/core/unsaved-work/unsavedWork'
 
 interface HarnessModel {
   name: string
@@ -76,6 +76,7 @@ describe('useUnsavedWorkRegistration', () => {
       label: '新增客户',
       dirty: true,
       requiredPermission: 'customer:update',
+      workspaceTabId: null,
     })
 
     harness.model.name = ''
diff --git a/src/composables/useUnsavedWorkRegistration.ts b/src/core/unsaved-work/useUnsavedWorkRegistration.ts
similarity index 62%
rename from src/composables/useUnsavedWorkRegistration.ts
rename to src/core/unsaved-work/useUnsavedWorkRegistration.ts
index ccd7c389..1c7e7e96 100644
--- a/src/composables/useUnsavedWorkRegistration.ts
+++ b/src/core/unsaved-work/useUnsavedWorkRegistration.ts
@@ -1,5 +1,5 @@
-import { computed, onScopeDispose, ref, watch, type ComputedRef, type Ref } from 'vue'
-import { useUnsavedWorkStore } from '@/stores/unsavedWork'
+import { computed, getCurrentInstance, onActivated, onScopeDispose, ref, watch, type ComputedRef, type Ref } from 'vue'
+import { useUnsavedWorkStore } from '@/core/unsaved-work/unsavedWork'
 
 interface UnsavedWorkRegistrationOptions<T extends object> {
   key: string
@@ -13,12 +13,16 @@ export function useUnsavedWorkRegistration<T extends object>(
   options: UnsavedWorkRegistrationOptions<T>,
 ) {
   const store = useUnsavedWorkStore()
+  const routeName = getCurrentInstance()?.proxy?.$route?.name
+  const workspaceTabId = routeName === undefined || routeName === null ? null : String(routeName)
+  const owner = Symbol(options.key)
   const snapshot = computed(() => JSON.stringify(options.model))
   const baseline = ref(snapshot.value)
+  store.claim(options.key, owner)
 
   function sync() {
     if (!options.isOpen.value) {
-      store.remove(options.key)
+      store.remove(options.key, owner)
       return
     }
 
@@ -27,7 +31,8 @@ export function useUnsavedWorkRegistration<T extends object>(
       label: options.label.value,
       dirty: snapshot.value !== baseline.value,
       requiredPermission: options.requiredPermission.value,
-    })
+      workspaceTabId,
+    }, owner)
   }
 
   function captureBaseline() {
@@ -41,7 +46,8 @@ export function useUnsavedWorkRegistration<T extends object>(
     { flush: 'sync' },
   )
   sync()
-  onScopeDispose(() => store.remove(options.key))
+  onActivated(sync)
+  onScopeDispose(() => store.release(options.key, owner))
 
   return { captureBaseline }
 }
diff --git a/src/core/workspace-tabs/routeMeta.d.ts b/src/core/workspace-tabs/routeMeta.d.ts
new file mode 100644
index 00000000..c00c84c3
--- /dev/null
+++ b/src/core/workspace-tabs/routeMeta.d.ts
@@ -0,0 +1,16 @@
+import 'vue-router'
+
+declare module 'vue-router' {
+  interface RouteMeta {
+    title?: string
+    description?: string
+    requiresAuth?: boolean
+    permission?: string
+    permissionAnyOf?: string[]
+    showPageHeading?: boolean
+    workspaceTab?: boolean
+    keepAlive?: boolean
+  }
+}
+
+export {}
diff --git a/src/core/workspace-tabs/routeWorkspace.ts b/src/core/workspace-tabs/routeWorkspace.ts
new file mode 100644
index 00000000..a22a5612
--- /dev/null
+++ b/src/core/workspace-tabs/routeWorkspace.ts
@@ -0,0 +1,37 @@
+import type { RouteLocationNormalizedLoaded, RouteLocationResolved } from 'vue-router'
+import type { WorkspaceTabCandidate } from './types'
+
+type WorkspaceRoute = RouteLocationNormalizedLoaded | RouteLocationResolved
+
+export function workspaceRouteId(route: WorkspaceRoute) {
+  return route.name === undefined || route.name === null ? null : String(route.name)
+}
+
+export function isWorkspaceRoute(route: WorkspaceRoute) {
+  return Boolean(
+    workspaceRouteId(route)
+    && route.meta.workspaceTab !== false
+    && route.matched.some((record) => record.meta.requiresAuth),
+  )
+}
+
+export function canAccessWorkspaceRoute(route: WorkspaceRoute, permissions: ReadonlySet<string>) {
+  if (!isWorkspaceRoute(route)) return false
+  const permission = typeof route.meta.permission === 'string' ? route.meta.permission : undefined
+  const alternatives = route.meta.permissionAnyOf ?? []
+  if (!permission && alternatives.length === 0) return true
+  return Boolean(
+    (permission && permissions.has(permission))
+    || alternatives.some((code) => permissions.has(code)),
+  )
+}
+
+export function workspaceTabCandidate(route: WorkspaceRoute): WorkspaceTabCandidate | null {
+  const id = workspaceRouteId(route)
+  if (!id || !isWorkspaceRoute(route)) return null
+  return {
+    id,
+    title: typeof route.meta.title === 'string' && route.meta.title.trim() ? route.meta.title.trim() : '未命名页面',
+    path: route.fullPath,
+  }
+}
diff --git a/src/core/workspace-tabs/types.ts b/src/core/workspace-tabs/types.ts
new file mode 100644
index 00000000..b98d9b73
--- /dev/null
+++ b/src/core/workspace-tabs/types.ts
@@ -0,0 +1,17 @@
+export interface WorkspaceTab {
+  id: string
+  title: string
+  path: string
+  lastVisitedAt: number
+}
+
+export interface WorkspaceTabCandidate {
+  id: string
+  title: string
+  path: string
+}
+
+export interface WorkspaceTabsSnapshot {
+  tabs: WorkspaceTab[]
+  activeId: string | null
+}
diff --git a/src/core/workspace-tabs/workspaceTabs.test.ts b/src/core/workspace-tabs/workspaceTabs.test.ts
new file mode 100644
index 00000000..28f13a71
--- /dev/null
+++ b/src/core/workspace-tabs/workspaceTabs.test.ts
@@ -0,0 +1,61 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { createPinia, setActivePinia } from 'pinia'
+import { WORKSPACE_TAB_LIMIT, readWorkspaceTabsSnapshot, useWorkspaceTabsStore } from './workspaceTabs'
+
+describe('workspace tabs store', () => {
+  beforeEach(() => {
+    sessionStorage.clear()
+    setActivePinia(createPinia())
+    vi.restoreAllMocks()
+  })
+
+  it('keeps one tab per route name and restores it only for the same account', () => {
+    vi.spyOn(Date, 'now').mockReturnValueOnce(10).mockReturnValueOnce(20)
+    const store = useWorkspaceTabsStore()
+    store.initialize('user-a')
+    store.open({ id: 'customers', title: '客户管理', path: '/customers' })
+    store.open({ id: 'customers', title: '客户详情', path: '/customers/10001' })
+
+    expect(store.tabs).toEqual([{ id: 'customers', title: '客户详情', path: '/customers/10001', lastVisitedAt: 20 }])
+    expect(readWorkspaceTabsSnapshot('user-a').activeId).toBe('customers')
+    expect(readWorkspaceTabsSnapshot('user-b').tabs).toEqual([])
+  })
+
+  it('evicts the least recently used clean inactive tab at the soft limit', () => {
+    let now = 0
+    vi.spyOn(Date, 'now').mockImplementation(() => ++now)
+    const store = useWorkspaceTabsStore()
+    store.initialize('user-a')
+    for (let index = 0; index < WORKSPACE_TAB_LIMIT; index += 1) {
+      store.open({ id: `route-${index}`, title: `页面 ${index}`, path: `/route-${index}` })
+    }
+
+    store.open({ id: 'route-new', title: '新页面', path: '/route-new' }, new Set(['route-0']))
+
+    expect(store.tabs).toHaveLength(WORKSPACE_TAB_LIMIT)
+    expect(store.tabs.some((tab) => tab.id === 'route-0')).toBe(true)
+    expect(store.tabs.some((tab) => tab.id === 'route-1')).toBe(false)
+    expect(store.activeId).toBe('route-new')
+  })
+
+  it('falls back to the most recently visited remaining tab and rotates the closed cache key', () => {
+    vi.spyOn(Date, 'now').mockReturnValueOnce(10).mockReturnValueOnce(20).mockReturnValueOnce(30)
+    const store = useWorkspaceTabsStore()
+    store.initialize('user-a')
+    store.open({ id: 'customers', title: '客户', path: '/customers' })
+    store.open({ id: 'warehouses', title: '仓库', path: '/warehouses' })
+    store.open({ id: 'pallets', title: '托盘', path: '/pallets' })
+    const previousKey = store.cacheKey('pallets')
+
+    const fallback = store.removeByIds(['pallets'])
+
+    expect(fallback?.id).toBe('warehouses')
+    expect(store.activeId).toBe('warehouses')
+    expect(store.cacheKey('pallets')).not.toBe(previousKey)
+  })
+
+  it('drops corrupt persisted data instead of breaking application startup', () => {
+    sessionStorage.setItem('cc-admin-workspace-tabs:v1:user-a', '{broken')
+    expect(readWorkspaceTabsSnapshot('user-a')).toEqual({ tabs: [], activeId: null })
+  })
+})
diff --git a/src/core/workspace-tabs/workspaceTabs.ts b/src/core/workspace-tabs/workspaceTabs.ts
new file mode 100644
index 00000000..dc89a8ea
--- /dev/null
+++ b/src/core/workspace-tabs/workspaceTabs.ts
@@ -0,0 +1,147 @@
+import { computed, ref } from 'vue'
+import { defineStore } from 'pinia'
+import type { WorkspaceTab, WorkspaceTabCandidate, WorkspaceTabsSnapshot } from './types'
+
+const STORAGE_PREFIX = 'cc-admin-workspace-tabs:v1'
+export const WORKSPACE_TAB_LIMIT = 12
+export const MAX_CACHED_WORKSPACE_VIEWS = 24
+
+function storageKey(userId: string) {
+  return `${STORAGE_PREFIX}:${userId}`
+}
+
+function validTab(value: unknown): value is WorkspaceTab {
+  if (!value || typeof value !== 'object') return false
+  const tab = value as Partial<WorkspaceTab>
+  return typeof tab.id === 'string'
+    && Boolean(tab.id)
+    && typeof tab.title === 'string'
+    && typeof tab.path === 'string'
+    && tab.path.startsWith('/')
+    && typeof tab.lastVisitedAt === 'number'
+    && Number.isFinite(tab.lastVisitedAt)
+}
+
+export function readWorkspaceTabsSnapshot(userId: string): WorkspaceTabsSnapshot {
+  if (!userId) return { tabs: [], activeId: null }
+  try {
+    const parsed = JSON.parse(sessionStorage.getItem(storageKey(userId)) || 'null') as Partial<WorkspaceTabsSnapshot> | null
+    if (!parsed || !Array.isArray(parsed.tabs)) return { tabs: [], activeId: null }
+    const tabs = parsed.tabs.filter(validTab)
+    const activeId = typeof parsed.activeId === 'string' && tabs.some((tab) => tab.id === parsed.activeId)
+      ? parsed.activeId
+      : null
+    return { tabs, activeId }
+  } catch {
+    return { tabs: [], activeId: null }
+  }
+}
+
+export function readStoredActiveWorkspacePath(userId: string) {
+  const snapshot = readWorkspaceTabsSnapshot(userId)
+  return snapshot.tabs.find((tab) => tab.id === snapshot.activeId)?.path ?? null
+}
+
+export const useWorkspaceTabsStore = defineStore('workspace-tabs', () => {
+  const tabs = ref<WorkspaceTab[]>([])
+  const activeId = ref<string | null>(null)
+  const initializedUserId = ref('')
+  const cacheEpochs = ref<Record<string, number>>({})
+
+  const activeTab = computed(() => tabs.value.find((tab) => tab.id === activeId.value) ?? null)
+
+  function persist() {
+    if (!initializedUserId.value) return
+    sessionStorage.setItem(storageKey(initializedUserId.value), JSON.stringify({
+      tabs: tabs.value,
+      activeId: activeId.value,
+    } satisfies WorkspaceTabsSnapshot))
+  }
+
+  function initialize(userId: string) {
+    if (!userId || initializedUserId.value === userId) return
+    initializedUserId.value = userId
+    const snapshot = readWorkspaceTabsSnapshot(userId)
+    tabs.value = snapshot.tabs
+    activeId.value = snapshot.activeId
+  }
+
+  function bumpCacheEpoch(tabId: string) {
+    cacheEpochs.value = {
+      ...cacheEpochs.value,
+      [tabId]: (cacheEpochs.value[tabId] ?? 0) + 1,
+    }
+  }
+
+  function removeByIds(ids: readonly string[]) {
+    const idSet = new Set(ids)
+    if (idSet.size === 0) return activeTab.value
+    const activeWasRemoved = activeId.value !== null && idSet.has(activeId.value)
+    for (const id of idSet) bumpCacheEpoch(id)
+    tabs.value = tabs.value.filter((tab) => !idSet.has(tab.id))
+    if (activeWasRemoved) {
+      activeId.value = [...tabs.value].sort((left, right) => right.lastVisitedAt - left.lastVisitedAt)[0]?.id ?? null
+    } else if (activeId.value && !tabs.value.some((tab) => tab.id === activeId.value)) {
+      activeId.value = null
+    }
+    persist()
+    return activeTab.value
+  }
+
+  function enforceLimit(dirtyTabIds: ReadonlySet<string>) {
+    while (tabs.value.length > WORKSPACE_TAB_LIMIT) {
+      const candidate = tabs.value
+        .filter((tab) => tab.id !== activeId.value && !dirtyTabIds.has(tab.id))
+        .sort((left, right) => left.lastVisitedAt - right.lastVisitedAt)[0]
+      if (!candidate) break
+      removeByIds([candidate.id])
+    }
+  }
+
+  function open(candidate: WorkspaceTabCandidate, dirtyTabIds: ReadonlySet<string> = new Set()) {
+    const now = Date.now()
+    const existing = tabs.value.find((tab) => tab.id === candidate.id)
+    if (existing) {
+      existing.title = candidate.title
+      existing.path = candidate.path
+      existing.lastVisitedAt = now
+    } else {
+      tabs.value.push({ ...candidate, lastVisitedAt: now })
+    }
+    activeId.value = candidate.id
+    enforceLimit(dirtyTabIds)
+    persist()
+  }
+
+  function prune(keep: (tab: WorkspaceTab) => boolean) {
+    const removedIds = tabs.value.filter((tab) => !keep(tab)).map((tab) => tab.id)
+    return { removedIds, fallback: removeByIds(removedIds) }
+  }
+
+  function cacheKey(tabId: string | null) {
+    if (!tabId) return 'workspace-route'
+    return `${tabId}:${cacheEpochs.value[tabId] ?? 0}`
+  }
+
+  function reset(removePersisted = false) {
+    if (removePersisted && initializedUserId.value) sessionStorage.removeItem(storageKey(initializedUserId.value))
+    tabs.value = []
+    activeId.value = null
+    cacheEpochs.value = {}
+    initializedUserId.value = ''
+  }
+
+  return {
+    tabs,
+    activeId,
+    activeTab,
+    initializedUserId,
+    initialize,
+    open,
+    removeByIds,
+    prune,
+    cacheKey,
+    bumpCacheEpoch,
+    reset,
+  }
+})
diff --git a/src/deployment/nginxConfig.test.ts b/src/deployment/nginxConfig.test.ts
new file mode 100644
index 00000000..a296661a
--- /dev/null
+++ b/src/deployment/nginxConfig.test.ts
@@ -0,0 +1,75 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const config = readFileSync(resolve(process.cwd(), 'nginx/default.conf.template'), 'utf8')
+const testCompose = readFileSync(resolve(process.cwd(), 'docker-compose.test.yml'), 'utf8')
+const developmentCompose = readFileSync(resolve(process.cwd(), 'docker-compose.development.yml'), 'utf8')
+const productionCompose = readFileSync(resolve(process.cwd(), 'docker-compose.production.yml'), 'utf8')
+const jenkinsfile = readFileSync(resolve(process.cwd(), 'Jenkinsfile'), 'utf8')
+const dockerfile = readFileSync(resolve(process.cwd(), 'Dockerfile'), 'utf8')
+
+describe('admin nginx deployment config', () => {
+  it('allows 50 MiB files plus multipart overhead through both bounded API proxies', () => {
+    expect(config.match(/client_max_body_size 55m;/g)).toHaveLength(2)
+    expect(config).not.toContain('client_max_body_size 12m;')
+    expect(config).not.toContain('client_max_body_size 0;')
+  })
+
+  it('prevents the application shell from retaining stale chunk references', () => {
+    expect(config).toContain('location = /index.html')
+    expect(config).toContain('Cache-Control "no-cache, no-store, must-revalidate"')
+  })
+
+  it('serves hashed assets immutably and never falls back missing chunks to HTML', () => {
+    expect(config).toContain('location /assets/')
+    expect(config).toContain('try_files $uri =404;')
+    expect(config).toContain('Cache-Control "public, max-age=31536000, immutable"')
+  })
+
+  it('keeps Vue history routes on the application shell without caching them', () => {
+    expect(config).toContain('try_files $uri $uri/ /index.html;')
+    expect(config).toContain('Cache-Control "no-cache"')
+  })
+
+  it('proxies overseas API requests to the gateway API prefix', () => {
+    expect(config).toContain('location /overseas-api/')
+    expect(config).toContain('rewrite ^/overseas-api/(.*)$ /api/$1 break;')
+    expect(config).toContain('proxy_pass ${OVERSEAS_API_UPSTREAM};')
+  })
+
+  it('declares an explicit overseas gateway upstream in container deployments', () => {
+    expect(testCompose).toContain('API_UPSTREAM: "http://test-api-cn.buggoglobal.com"')
+    expect(testCompose).toContain('OVERSEAS_API_UPSTREAM: "http://test-api-global.buggoglobal.com"')
+    expect(testCompose).toContain('CLIENT_WEB_URL: "${CLIENT_WEB_URL:-https://test-app.buggoglobal.com/}"')
+    expect(testCompose).not.toContain('CLIENT_WEB_URL: "http://8.163.')
+    expect(developmentCompose).toContain('CLIENT_WEB_URL: "${CLIENT_WEB_URL:-https://dev-app.buggoglobal.com/}"')
+    expect(developmentCompose).toContain('OVERSEAS_API_UPSTREAM: "http://firstleg-development-gateway-overseas:9300"')
+    expect(config).toContain('proxy_set_header Host $proxy_host;')
+  })
+
+  it('keeps local environments on target nodes and uses credential-managed SSH for production', () => {
+    expect(jenkinsfile).toContain("env.JOB_BASE_NAME?.endsWith('-prod') ? 'java-builder'")
+    expect(jenkinsfile).toContain("DEVELOPMENT_COMPOSE_PROJECT = 'admin-web'")
+    expect(jenkinsfile).toContain('docker compose -p "$DEVELOPMENT_COMPOSE_PROJECT" -f "$DEVELOPMENT_COMPOSE_FILE" up -d')
+    expect(jenkinsfile).not.toContain('/var/jenkins_home/.ssh')
+    expect(jenkinsfile).not.toContain('docker save')
+    expect(jenkinsfile).toContain("credentialsId: 'firstleg-production-ssh'")
+    expect(jenkinsfile).toContain('git rev-parse origin/main')
+    expect(productionCompose).toContain('127.0.0.1:${HOST_PORT:-9001}:80')
+    expect(productionCompose).toContain('API_UPSTREAM: "http://gateway:9000"')
+    expect(productionCompose).toContain('name: firstleg-prod-infra-network')
+  })
+
+  it('uses authenticated internal base images in CI instead of pulling from Docker Hub', () => {
+    expect(dockerfile).toContain('ARG NODE_IMAGE=node:22-alpine')
+    expect(dockerfile).toContain('ARG NGINX_IMAGE=nginx:1.27-alpine')
+    expect(dockerfile).toContain('FROM ${NODE_IMAGE} AS build')
+    expect(dockerfile).toContain('FROM ${NGINX_IMAGE}')
+    expect(jenkinsfile).toContain("NODE_BASE_IMAGE = '172.31.198.7:10082/java-project/node:22-alpine'")
+    expect(jenkinsfile).toContain("NGINX_BASE_IMAGE = '172.31.198.7:10082/java-project/nginx:1.27-alpine'")
+    expect(jenkinsfile).toContain('withCredentials([usernamePassword(')
+    expect(jenkinsfile).toContain('export DOCKER_CONFIG="${WORKSPACE}@tmp/docker-auth"')
+    expect(jenkinsfile).toContain('--build-arg VITE_CLIENT_WEB_URL="${CLIENT_WEB_URL:-https://dev-app.buggoglobal.com/}"')
+  })
+})
diff --git a/src/deployment/viteConfig.test.ts b/src/deployment/viteConfig.test.ts
new file mode 100644
index 00000000..cbbf3d10
--- /dev/null
+++ b/src/deployment/viteConfig.test.ts
@@ -0,0 +1,11 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const configSource = readFileSync(resolve(process.cwd(), 'vite.config.ts'), 'utf8')
+
+describe('Vite development server', () => {
+  it('fails fast when the dedicated admin development port is occupied', () => {
+    expect(configSource).toMatch(/server:\s*\{\s*strictPort: true,/)
+  })
+})
diff --git a/src/env.d.ts b/src/env.d.ts
index f5c051ec..d6141d96 100644
--- a/src/env.d.ts
+++ b/src/env.d.ts
@@ -8,8 +8,8 @@ declare module 'vue-router' {
   interface RouteMeta {
     title?: string
     description?: string
+    showPageHeading?: boolean
     requiresAuth?: boolean
     permission?: string
   }
 }
-
diff --git a/src/layouts/AppLayout.test.ts b/src/layouts/AppLayout.test.ts
deleted file mode 100644
index cfa83d1f..00000000
--- a/src/layouts/AppLayout.test.ts
+++ /dev/null
@@ -1,323 +0,0 @@
-import { createPinia, setActivePinia } from 'pinia'
-import { flushPromises, mount } from '@vue/test-utils'
-import { createMemoryHistory, createRouter } from 'vue-router'
-import { nextTick } from 'vue'
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-import { ElMessage, ElMessageBox } from 'element-plus'
-import { useAccessPreviewStore } from '@/stores/accessPreview'
-import { useAdminDataStore } from '@/stores/adminData'
-import { useAuthStore } from '@/stores/auth'
-import { useUnsavedWorkStore } from '@/stores/unsavedWork'
-import AppLayout from './AppLayout.vue'
-
-vi.mock('element-plus', async (importOriginal) => {
-  const actual = await importOriginal<typeof import('element-plus')>()
-  return {
-    ...actual,
-    ElMessage: { success: vi.fn(), error: vi.fn() },
-    ElMessageBox: { confirm: vi.fn() },
-  }
-})
-
-const page = { template: '<p>page</p>' }
-
-function createMemoryStorage(): Storage {
-  const values = new Map<string, string>()
-  return {
-    get length() { return values.size },
-    clear: () => values.clear(),
-    getItem: (key) => values.get(key) ?? null,
-    key: (index) => [...values.keys()][index] ?? null,
-    removeItem: (key) => values.delete(key),
-    setItem: (key, value) => values.set(key, value),
-  }
-}
-
-async function mountLayout(path: string) {
-  const pinia = createPinia()
-  setActivePinia(pinia)
-  const auth = useAuthStore()
-  auth.token = 'test-access-token'
-  auth.user = { id: '1', name: '平台管理员', account: 'platform_admin', roles: ['PLATFORM_ADMIN'] }
-  localStorage.setItem('cc-admin-token', auth.token)
-  const router = createRouter({
-    history: createMemoryHistory(),
-    routes: [
-      { path: '/', component: page, meta: { title: '管理后台' } },
-      { path: '/customers', component: page, meta: { title: '客户管理', permission: 'platform:customer:list' } },
-      { path: '/warehouses', component: page, meta: { title: '仓库管理', permission: 'platform:warehouse:list' } },
-      { path: '/orders/first-leg', component: page, meta: { title: '头程订单', permission: 'platform:order:list' } },
-      { path: '/system/users', component: page, meta: { title: '内部用户', permission: 'platform:user:list' } },
-      { path: '/403', component: page, meta: { title: '权限不足' } },
-      { path: '/login', component: page, meta: { title: '登录' } },
-    ],
-  })
-  await router.push(path)
-  await router.isReady()
-
-  const wrapper = mount(AppLayout, {
-    attachTo: document.body,
-    global: {
-      plugins: [pinia, router],
-      stubs: {
-        AdminSidebarMenu: { props: ['items'], template: '<nav data-sidebar :data-count="items.length" />' },
-        RolePreviewSwitcher: {
-          props: ['roles', 'currentRole'],
-          emits: ['select'],
-          template: '<div><span data-preview>{{ currentRole?.name }}</span><button data-switch-r003 @click="$emit(\'select\', \'R003\')">switch R003</button><button data-switch-r005 @click="$emit(\'select\', \'R005\')">switch R005</button></div>',
-        },
-        'el-button': { emits: ['click'], template: '<button type="button" @click="$emit(\'click\')"><slot /></button>' },
-      },
-    },
-  })
-  await nextTick()
-  return {
-    wrapper,
-    router,
-    auth,
-    access: useAccessPreviewStore(),
-    data: useAdminDataStore(),
-    unsaved: useUnsavedWorkStore(),
-  }
-}
-
-describe('AppLayout role preview coordination', () => {
-  beforeEach(() => {
-    vi.stubGlobal('localStorage', createMemoryStorage())
-    vi.mocked(ElMessageBox.confirm).mockReset()
-    vi.mocked(ElMessage.success).mockReset()
-    vi.mocked(ElMessage.error).mockReset()
-    document.body.innerHTML = ''
-  })
-
-  it('keeps the login identity visibly separate from the preview role', async () => {
-    const { wrapper } = await mountLayout('/')
-
-    expect(wrapper.get('[aria-label="登录身份：平台管理员（platform_admin）"]').text())
-      .toBe('登录身份：平台管理员（platform_admin）')
-    expect(wrapper.get('[data-preview]').text()).toBe('超级管理员')
-  })
-
-  it('commits a role and replaces an inaccessible system route with its first leaf', async () => {
-    const { wrapper, router, access } = await mountLayout('/system/users')
-    const replace = vi.spyOn(router, 'replace')
-
-    await wrapper.get('[data-switch-r003]').trigger('click')
-    await flushPromises()
-
-    expect(access.currentRole?.id).toBe('R003')
-    expect(replace).toHaveBeenCalledWith('/warehouses')
-    expect(router.currentRoute.value.path).toBe('/warehouses')
-    expect(wrapper.get('[aria-live="polite"]').text()).toContain('操作员')
-    expect(wrapper.get('[aria-live="polite"]').text()).toContain('仓库管理')
-    expect(ElMessage.success).toHaveBeenCalledWith('已切换至“操作员”，当前仅为静态权限预览')
-    expect(document.activeElement).toBe(wrapper.get('h1').element)
-    expect(wrapper.get('[data-sidebar]').attributes('data-count'))
-      .toBe(String(access.filteredNavigation.length))
-    expect(access.filteredNavigation).toHaveLength(1)
-  })
-
-  it('recovers from 403 to the first accessible leaf after a role change', async () => {
-    const { wrapper, router, access } = await mountLayout('/403')
-    const replace = vi.spyOn(router, 'replace')
-
-    await wrapper.get('[data-switch-r003]').trigger('click')
-    await flushPromises()
-
-    expect(access.currentRole?.id).toBe('R003')
-    expect(replace).toHaveBeenCalledWith('/warehouses')
-  })
-
-  it('keeps a queried 403 route when the candidate role has no accessible page', async () => {
-    const { wrapper, router, access, data } = await mountLayout('/403?from=/system/users')
-    data.roles.find((role) => role.id === 'R003')!.permissionIds = []
-    const replace = vi.spyOn(router, 'replace')
-
-    await wrapper.get('[data-switch-r003]').trigger('click')
-    await flushPromises()
-
-    expect(access.currentRole?.id).toBe('R003')
-    expect(router.currentRoute.value.fullPath).toBe('/403?from=/system/users')
-    expect(replace).not.toHaveBeenCalled()
-    expect(wrapper.get('[aria-live="polite"]').text()).toBe('权限预览已切换为操作员')
-  })
-
-  it('keeps role, route and dirty entry unchanged when role switching is cancelled', async () => {
-    vi.mocked(ElMessageBox.confirm).mockRejectedValueOnce('cancel')
-    const { wrapper, router, access, unsaved } = await mountLayout('/system/users')
-    unsaved.upsert({ key: 'user-form', label: '内部用户编辑表单', dirty: true, requiredPermission: 'system:user:write' })
-
-    await wrapper.get('[data-switch-r003]').trigger('click')
-    await flushPromises()
-
-    expect(ElMessageBox.confirm).toHaveBeenCalledWith(
-      expect.stringMatching(/切换到操作员.*将离开内部用户.*内部用户编辑表单/),
-      expect.any(String),
-      expect.any(Object),
-    )
-    expect(access.currentRole?.id).toBe('R001')
-    expect(router.currentRoute.value.path).toBe('/system/users')
-    expect(unsaved.entries).toHaveLength(1)
-  })
-
-  it('warns that same-page forms will lose save permission without claiming navigation', async () => {
-    vi.mocked(ElMessageBox.confirm).mockRejectedValueOnce('cancel')
-    const { wrapper, router, access, unsaved } = await mountLayout('/orders/first-leg')
-    unsaved.upsert({ key: 'restricted-form', label: '受限订单表单', dirty: true, requiredPermission: 'system:user:write' })
-
-    await wrapper.get('[data-switch-r003]').trigger('click')
-    await flushPromises()
-
-    const message = String(vi.mocked(ElMessageBox.confirm).mock.calls[0]?.[0])
-    expect(message).toContain('切换到操作员')
-    expect(message).toContain('头程订单')
-    expect(message).toContain('将失去保存权限')
-    expect(message).toContain('受限订单表单')
-    expect(message).not.toContain('将离开头程订单')
-    expect(access.currentRole?.id).toBe('R001')
-    expect(router.currentRoute.value.path).toBe('/orders/first-leg')
-  })
-
-  it('commits only after dirty-work confirmation succeeds', async () => {
-    let resolveConfirmation: (() => void) | undefined
-    vi.mocked(ElMessageBox.confirm).mockReturnValueOnce(new Promise((resolve) => {
-      resolveConfirmation = () => resolve({} as never)
-    }))
-    const { wrapper, access, unsaved } = await mountLayout('/system/users')
-    unsaved.upsert({ key: 'user-form', label: '内部用户编辑表单', dirty: true, requiredPermission: 'system:user:write' })
-
-    await wrapper.get('[data-switch-r003]').trigger('click')
-    await nextTick()
-    expect(access.currentRole?.id).toBe('R001')
-
-    resolveConfirmation?.()
-    await flushPromises()
-    expect(access.currentRole?.id).toBe('R003')
-  })
-
-  it('ignores another role selection while the first confirmation is pending', async () => {
-    let resolveConfirmation: (() => void) | undefined
-    vi.mocked(ElMessageBox.confirm).mockReturnValueOnce(new Promise((resolve) => {
-      resolveConfirmation = () => resolve({} as never)
-    }))
-    const { wrapper, access, unsaved } = await mountLayout('/system/users')
-    unsaved.upsert({ key: 'user-form', label: '内部用户编辑表单', dirty: true, requiredPermission: 'system:user:write' })
-
-    await wrapper.get('[data-switch-r003]').trigger('click')
-    await wrapper.get('[data-switch-r005]').trigger('click')
-    await nextTick()
-
-    expect(ElMessageBox.confirm).toHaveBeenCalledTimes(1)
-    expect(access.currentRole?.id).toBe('R001')
-    resolveConfirmation?.()
-    await flushPromises()
-    expect(access.currentRole?.id).toBe('R003')
-  })
-
-  it('reconfirms when a new blocker appears while the first confirmation is pending', async () => {
-    let resolveFirst: (() => void) | undefined
-    let resolveSecond: (() => void) | undefined
-    vi.mocked(ElMessageBox.confirm)
-      .mockReturnValueOnce(new Promise((resolve) => { resolveFirst = () => resolve({} as never) }))
-      .mockReturnValueOnce(new Promise((resolve) => { resolveSecond = () => resolve({} as never) }))
-    const { wrapper, access, unsaved } = await mountLayout('/orders/first-leg')
-    unsaved.upsert({ key: 'first-form', label: '第一张表单', dirty: true, requiredPermission: 'system:user:write' })
-
-    await wrapper.get('[data-switch-r003]').trigger('click')
-    await nextTick()
-    unsaved.upsert({ key: 'second-form', label: '新增表单', dirty: true, requiredPermission: 'customer:create' })
-    resolveFirst?.()
-    await flushPromises()
-
-    expect(ElMessageBox.confirm).toHaveBeenCalledTimes(2)
-    expect(String(vi.mocked(ElMessageBox.confirm).mock.calls[1]?.[0])).toContain('新增表单')
-    expect(access.currentRole?.id).toBe('R001')
-    resolveSecond?.()
-    await flushPromises()
-    expect(access.currentRole?.id).toBe('R003')
-  })
-
-  it('replaces the route when live permission changes make the current page inaccessible', async () => {
-    const { router, access, data } = await mountLayout('/system/users')
-    const replace = vi.spyOn(router, 'replace')
-    const permission = data.permissions.find((item) => item.code === 'platform:user:list')
-    if (!permission) throw new Error('fixture permission missing')
-
-    permission.status = '停用'
-    await nextTick()
-    await flushPromises()
-
-    expect(access.currentRole?.id).toBe('R001')
-    expect(replace).toHaveBeenCalledWith('/customers')
-    expect(document.activeElement).toBe(document.querySelector('h1'))
-    expect(document.querySelector('[aria-live="polite"]')?.textContent)
-      .toBe('当前页面权限已变化，已前往客户管理')
-  })
-
-  it('does not replace or announce navigation when live access remains on queried 403', async () => {
-    const { router, data } = await mountLayout('/403?from=/system/users')
-    const replace = vi.spyOn(router, 'replace')
-
-    data.permissions.forEach((permission) => { permission.status = '停用' })
-    await nextTick()
-    await flushPromises()
-
-    expect(router.currentRoute.value.fullPath).toBe('/403?from=/system/users')
-    expect(replace).not.toHaveBeenCalled()
-    expect(document.querySelector('[aria-live="polite"]')?.textContent).toBe('')
-  })
-
-  it('rolls back the role and reports an error when correction navigation fails', async () => {
-    const { wrapper, router, access } = await mountLayout('/system/users')
-    vi.spyOn(router, 'replace').mockRejectedValueOnce(new Error('navigation failed'))
-
-    await wrapper.get('[data-switch-r003]').trigger('click')
-    await flushPromises()
-
-    expect(access.currentRole?.id).toBe('R001')
-    expect(router.currentRoute.value.path).toBe('/system/users')
-    expect(ElMessage.error).toHaveBeenCalledWith('权限预览切换失败，已恢复原角色')
-    expect(ElMessage.success).not.toHaveBeenCalled()
-
-    await wrapper.get('[data-switch-r003]').trigger('click')
-    await flushPromises()
-    expect(access.currentRole?.id).toBe('R003')
-  })
-
-  it('clears preview and unsaved state before logging out and replacing with login', async () => {
-    vi.mocked(ElMessageBox.confirm).mockResolvedValueOnce({} as never)
-    const { wrapper, router, auth, access, unsaved } = await mountLayout('/')
-    unsaved.upsert({ key: 'draft', label: '草稿', dirty: true, requiredPermission: null })
-    const calls: string[] = []
-    const resetAccess = access.reset
-    const clearUnsaved = unsaved.clear
-    const logout = auth.logout
-    vi.spyOn(access, 'reset').mockImplementation(() => { calls.push('access'); resetAccess() })
-    vi.spyOn(unsaved, 'clear').mockImplementation(() => { calls.push('unsaved'); clearUnsaved() })
-    vi.spyOn(auth, 'logout').mockImplementation(() => { calls.push('auth'); logout() })
-    const replace = vi.spyOn(router, 'replace')
-
-    await wrapper.get('[aria-label="退出登录"]').trigger('click')
-    await flushPromises()
-
-    expect(calls).toEqual(['access', 'unsaved', 'auth'])
-    expect(replace).toHaveBeenCalledWith('/login')
-  })
-
-  it('keeps cleared logout state and reports a login navigation failure', async () => {
-    vi.mocked(ElMessageBox.confirm).mockResolvedValueOnce({} as never)
-    const { wrapper, router, auth, access, unsaved } = await mountLayout('/')
-    unsaved.upsert({ key: 'draft', label: '草稿', dirty: true, requiredPermission: null })
-    vi.spyOn(router, 'replace').mockRejectedValueOnce(new Error('navigation failed'))
-
-    await wrapper.get('[aria-label="退出登录"]').trigger('click')
-    await flushPromises()
-
-    expect(auth.isAuthenticated).toBe(false)
-    expect(access.currentRole).toBeNull()
-    expect(unsaved.entries).toHaveLength(0)
-    expect(ElMessage.error).toHaveBeenCalledWith('已退出登录，但登录页跳转失败，请刷新页面')
-    expect(router.currentRoute.value.path).toBe('/')
-    expect(router.replace).toHaveBeenCalledTimes(1)
-  })
-})
diff --git a/src/layouts/AppLayout.vue b/src/layouts/AppLayout.vue
deleted file mode 100644
index 6e11027e..00000000
--- a/src/layouts/AppLayout.vue
+++ /dev/null
@@ -1,265 +0,0 @@
-<script setup lang="ts">
-import { computed, nextTick, ref, watch } from 'vue'
-import { useRoute, useRouter } from 'vue-router'
-import { ElMessage, ElMessageBox } from 'element-plus'
-import {
-  ChevronLeft,
-  ChevronRight,
-  LogOut,
-  Menu,
-} from '@lucide/vue'
-import { PRODUCT_NAME } from '@chongchong/shared'
-import AdminSidebarMenu from '@/components/AdminSidebarMenu.vue'
-import RolePreviewSwitcher from '@/components/RolePreviewSwitcher.vue'
-import { resolvePreviewTarget } from '@/router/accessDecision'
-import { useAccessPreviewStore } from '@/stores/accessPreview'
-import { useAuthStore } from '@/stores/auth'
-import { useUnsavedWorkStore } from '@/stores/unsavedWork'
-
-const route = useRoute()
-const router = useRouter()
-const auth = useAuthStore()
-const access = useAccessPreviewStore()
-const unsaved = useUnsavedWorkStore()
-const collapsed = ref(false)
-const mobileMenuOpen = ref(false)
-const correctingRoute = ref(false)
-const roleSwitchPending = ref(false)
-const loggingOut = ref(false)
-const pageHeading = ref<HTMLHeadingElement | null>(null)
-const announcement = ref('')
-
-access.initializeAfterLogin()
-
-const menuCollapsed = computed(() => collapsed.value && !mobileMenuOpen.value)
-const pageTitle = computed(() => route.meta.title || '管理后台')
-const pageDescription = computed(() => route.meta.description || '')
-
-function currentPermission(): string | undefined {
-  return typeof route.meta.permission === 'string' ? route.meta.permission : undefined
-}
-
-async function replaceAndFocus(path: string) {
-  await router.replace(path)
-  await nextTick()
-  pageHeading.value?.focus()
-}
-
-function getRoleSwitchDecision(roleId: string) {
-  const candidateRole = access.enabledRoles.find((role) => role.id === roleId)
-  if (!candidateRole) return null
-  const candidate = access.previewRole(roleId)
-  const target = resolvePreviewTarget({
-    currentPath: route.path,
-    currentPermission: currentPermission(),
-    candidateCodes: candidate.codes,
-    firstPath: candidate.firstPath,
-  })
-  const willLeave = target !== null && target !== route.path
-  const blockers = unsaved.findBlocking(candidate.codes, willLeave)
-  const blockerSignature = blockers
-    .map((entry) => `${entry.key}:${entry.label}:${entry.requiredPermission ?? ''}`)
-    .sort()
-    .join('|')
-
-  return {
-    candidateRole,
-    target,
-    willLeave,
-    blockers,
-    signature: `${target ?? ''}:${willLeave}:${blockerSignature}`,
-  }
-}
-
-async function confirmRoleSwitch(decision: NonNullable<ReturnType<typeof getRoleSwitchDecision>>) {
-  const labels = decision.blockers.map((entry) => entry.label).join('、')
-  const currentPage = typeof route.meta.title === 'string' ? route.meta.title : '当前页面'
-  const message = decision.willLeave
-    ? `切换到${decision.candidateRole.name}后，将离开${currentPage}，并放弃以下未保存内容：${labels}。是否继续？`
-    : `切换到${decision.candidateRole.name}后，${currentPage}中的以下表单将失去保存权限：${labels}。是否继续？`
-  try {
-    await ElMessageBox.confirm(
-      message,
-      '未保存内容',
-      { confirmButtonText: '放弃并切换', cancelButtonText: '取消', type: 'warning' },
-    )
-    return true
-  } catch {
-    return false
-  }
-}
-
-async function requestRoleSwitch(roleId: string) {
-  if (access.currentRole?.id === roleId || roleSwitchPending.value) return
-  roleSwitchPending.value = true
-
-  try {
-    let decision: NonNullable<ReturnType<typeof getRoleSwitchDecision>>
-    let confirmedSignature: string | null = null
-
-    while (true) {
-      const refreshedDecision = getRoleSwitchDecision(roleId)
-      if (!refreshedDecision) return
-      decision = refreshedDecision
-
-      if (decision.blockers.length && decision.signature !== confirmedSignature) {
-        if (!await confirmRoleSwitch(decision)) return
-        confirmedSignature = decision.signature
-        continue
-      }
-      break
-    }
-
-    correctingRoute.value = true
-    const currentPage = typeof route.meta.title === 'string' ? route.meta.title : '当前页面'
-    const previousRoleId = access.currentRole?.id ?? null
-    try {
-      if (!access.commitRole(roleId)) return
-      const navigated = Boolean(decision.target && decision.target !== route.path)
-      if (navigated && decision.target) {
-        try {
-          await replaceAndFocus(decision.target)
-        } catch {
-          const rolledBack = previousRoleId ? access.commitRole(previousRoleId) : false
-          if (rolledBack) {
-            ElMessage.error('权限预览切换失败，已恢复原角色')
-            return
-          }
-
-          const reconciliationTarget = resolvePreviewTarget({
-            currentPath: route.path,
-            currentPermission: currentPermission(),
-            candidateCodes: access.permissionCodes,
-            firstPath: access.firstAccessiblePath,
-          })
-          if (reconciliationTarget && reconciliationTarget !== route.path) {
-            try {
-              await replaceAndFocus(reconciliationTarget)
-            } catch {
-              // 保留当前路由，错误提示要求用户刷新以重新进入一致状态。
-            }
-          }
-          ElMessage.error('权限预览切换失败，当前权限状态可能已变化，请刷新页面')
-          return
-        }
-      }
-      const roleName = access.currentRole?.name ?? decision.candidateRole.name
-      announcement.value = navigated
-        ? `权限预览已切换为${roleName}，当前页面：${String(route.meta.title ?? currentPage)}`
-        : `权限预览已切换为${roleName}`
-      ElMessage.success(`已切换至“${roleName}”，当前仅为静态权限预览`)
-    } finally {
-      correctingRoute.value = false
-    }
-  } finally {
-    roleSwitchPending.value = false
-  }
-}
-
-async function handleLogout() {
-  try {
-    await ElMessageBox.confirm('确定退出管理后台吗？', '退出登录', {
-      confirmButtonText: '退出',
-      cancelButtonText: '取消',
-    })
-  } catch {
-    return
-  }
-
-  loggingOut.value = true
-  access.reset()
-  unsaved.clear()
-  auth.logout()
-  try {
-    await router.replace('/login')
-  } catch {
-    ElMessage.error('已退出登录，但登录页跳转失败，请刷新页面')
-  }
-}
-
-watch(() => route.fullPath, () => { mobileMenuOpen.value = false })
-watch(
-  () => `${access.currentRole?.id ?? ''}:${access.permissionSignature}`,
-  async () => {
-    if (correctingRoute.value || loggingOut.value) return
-    const target = resolvePreviewTarget({
-      currentPath: route.path,
-      currentPermission: currentPermission(),
-      candidateCodes: access.permissionCodes,
-      firstPath: access.firstAccessiblePath,
-    })
-    if (!target || target === route.path) return
-
-    correctingRoute.value = true
-    try {
-      await replaceAndFocus(target)
-      const targetTitle = String(route.meta.title ?? '可访问页面')
-      announcement.value = target === '/403'
-        ? `当前权限预览角色没有可访问页面，已前往${targetTitle}`
-        : `当前页面权限已变化，已前往${targetTitle}`
-    } finally {
-      correctingRoute.value = false
-    }
-  },
-)
-</script>
-
-<template>
-  <div class="app-shell" :class="{ 'is-collapsed': collapsed, 'is-mobile-open': mobileMenuOpen }">
-    <button v-if="mobileMenuOpen" class="sidebar-scrim" type="button" aria-label="关闭菜单" @click="mobileMenuOpen = false" />
-    <aside class="app-sidebar">
-      <div class="brand-block">
-        <div class="brand-mark">CC</div>
-        <div v-if="!collapsed" class="brand-copy">
-          <strong>{{ PRODUCT_NAME }}</strong>
-          <span>管理后台</span>
-        </div>
-      </div>
-
-      <nav class="side-nav" aria-label="主导航">
-        <AdminSidebarMenu :items="access.filteredNavigation" :active-path="route.path" :collapsed="menuCollapsed" />
-      </nav>
-
-      <button class="sidebar-toggle" type="button" @click="collapsed = !collapsed">
-        <ChevronRight v-if="collapsed" :size="18" />
-        <ChevronLeft v-else :size="18" />
-        <span v-if="!collapsed">收起导航</span>
-      </button>
-    </aside>
-
-    <div class="app-main">
-      <header class="app-header">
-        <button class="mobile-menu-button" type="button" aria-label="打开菜单" :aria-expanded="mobileMenuOpen" @click="mobileMenuOpen = true">
-          <Menu :size="20" />
-        </button>
-        <div class="page-heading">
-          <h1 ref="pageHeading" tabindex="-1">{{ pageTitle }}</h1>
-          <p v-if="pageDescription">{{ pageDescription }}</p>
-        </div>
-        <RolePreviewSwitcher
-          v-if="!access.usesServerPermissions"
-          :roles="access.enabledRoles"
-          :current-role="access.currentRole"
-          @select="requestRoleSwitch"
-        />
-        <div class="header-user">
-          <div class="user-avatar">{{ auth.user?.name.slice(0, 1) }}</div>
-          <div
-            class="user-copy"
-            :aria-label="`登录身份：${auth.user?.name ?? '-'}（${auth.user?.account ?? '-'}）`"
-          >
-            <strong>登录身份：{{ auth.user?.name }}（{{ auth.user?.account }}）</strong>
-          </div>
-          <el-button text aria-label="退出登录" @click="handleLogout">
-            <LogOut :size="18" />
-          </el-button>
-        </div>
-        <p class="sr-only" aria-live="polite" aria-atomic="true">{{ announcement }}</p>
-      </header>
-
-      <main class="page-container">
-        <RouterView />
-      </main>
-    </div>
-  </div>
-</template>
diff --git a/src/main.ts b/src/main.ts
index fc69d59c..cf229788 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -1,9 +1,76 @@
-import { createApp } from 'vue'
+import '@/styles/adminDensity.css'
+import { computed, createApp } from 'vue'
+import 'dayjs/locale/zh-cn'
 import { createPinia } from 'pinia'
+import { ElMessage, ElMessageBox } from 'element-plus'
 import 'element-plus/es/components/message/style/css'
 import 'element-plus/es/components/message-box/style/css'
 import App from './App.vue'
-import router from './router'
+import router from '@/app/router'
+import { sanitizeInternalPath } from '@/core/routing/accessDecision'
+import { clearNavigationRecoveryAttempt, recoverNavigationError } from '@/core/routing/navigationRecovery'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useUnsavedWorkStore } from '@/core/unsaved-work/unsavedWork'
+import { useWorkspaceTabsStore } from '@/core/workspace-tabs/workspaceTabs'
+import { useAuthStore } from '@/core/auth/auth'
+import { registerAuthSessionExpiredHandler } from '@/shared/api/http'
+import { UI_PREFERENCE_SCOPE } from '@/shared/utils/uiLayoutPreference'
 import './styles/index.css'
 
-createApp(App).use(createPinia()).use(router).mount('#app')
+const pinia = createPinia()
+const auth = useAuthStore(pinia)
+const unsaved = useUnsavedWorkStore(pinia)
+const workspace = useWorkspaceTabsStore(pinia)
+
+await auth.restoreSession()
+
+registerAuthSessionExpiredHandler(async () => {
+  const currentRoute = router.currentRoute.value
+  if (currentRoute.name === 'login') return
+
+  useAccessPreviewStore(pinia).reset()
+  unsaved.clear()
+  workspace.reset(true)
+  const redirect = sanitizeInternalPath(currentRoute.fullPath)
+  ElMessage.warning('登录状态已过期，请重新登录')
+  await router.replace({
+    name: 'login',
+    query: redirect === '/' ? undefined : { redirect },
+  })
+})
+
+router.onError((error, to) => {
+  void recoverNavigationError(error, to.fullPath, {
+    storage: sessionStorage,
+    now: Date.now,
+    hasUnsavedWork: () => unsaved.entries.some((entry) => entry.dirty),
+    confirmDiscard: async () => {
+      try {
+        await ElMessageBox.confirm(
+          '检测到后台已发布新版本，需要重新加载页面。继续后将放弃当前未保存内容。',
+          '重新加载页面？',
+          { confirmButtonText: '重新加载', cancelButtonText: '继续编辑', type: 'warning', customClass: 'admin-density-confirm' },
+        )
+        return true
+      } catch {
+        return false
+      }
+    },
+    discardUnsavedWork: () => unsaved.clear(),
+    navigate: (target) => window.location.assign(target),
+    showError: (message) => ElMessage.error(message),
+  })
+})
+router.afterEach((_to, _from, failure) => {
+  if (!failure) clearNavigationRecoveryAttempt(sessionStorage)
+})
+
+window.addEventListener('beforeunload', (event) => {
+  if (!unsaved.entries.some((entry) => entry.dirty)) return
+  event.preventDefault()
+  event.returnValue = ''
+})
+
+const app = createApp(App)
+app.provide(UI_PREFERENCE_SCOPE, computed(() => auth.user?.id || 'anonymous'))
+app.use(pinia).use(router).mount('#app')
diff --git a/src/modules/audit/api/platformAudit.test.ts b/src/modules/audit/api/platformAudit.test.ts
new file mode 100644
index 00000000..acee3e0e
--- /dev/null
+++ b/src/modules/audit/api/platformAudit.test.ts
@@ -0,0 +1,60 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import { getPlatformAuditLog, listPlatformAuditLogs } from './platformAudit'
+
+vi.mock('@/shared/api/http', () => ({
+  http: { get: vi.fn() },
+  unwrapApiResponse: <T>(response: { data: T }) => response.data,
+}))
+
+describe('platform audit api', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it('queries the selected customer and preserves long ids as strings', async () => {
+    vi.mocked(http.get).mockResolvedValue({ data: { records: [{ id: '2082813911786024961', accountId: '8', operatorTenantId: '0', userId: '9', resourceId: '8', eventId: 'evt', eventType: 'PLATFORM_TENANT_UPDATE', resourceType: 'TENANT', description: '编辑客户', username: 'admin', appCode: 'ADMIN', clientType: 'WEB', clientIp: '127.0.0.1', requestId: null, traceId: null, serviceName: 'iam-service', success: true, errorCode: null, errorMessage: null, occurredAt: '2026-08-13T01:00:00Z', createdAt: '2026-08-13T09:00:00' }], page: 1, size: 20, total: 1, pages: 1 } })
+
+    const result = await listPlatformAuditLogs({ accountId: '8', page: 1, size: 20 })
+
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/audit/logs', { params: { accountId: '8', page: 1, size: 20 } })
+    expect(result.records[0].id).toBe('2082813911786024961')
+    expect(result.records[0].clientIp).toBe('127.0.0.1')
+    expect(result.total).toBe(1)
+    expect(result.pages).toBe(1)
+  })
+
+  it('preserves the server total when the current page has fewer records', async () => {
+    vi.mocked(http.get).mockResolvedValue({ data: {
+      records: [{ id: '1', accountId: '8', operatorTenantId: '0', userId: '9', resourceId: '8', eventId: 'evt', eventType: 'PLATFORM_TENANT_UPDATE', resourceType: 'TENANT', description: '编辑客户', username: 'admin', appCode: 'ADMIN', clientType: 'WEB', clientIp: '127.0.0.1', requestId: null, traceId: null, serviceName: 'iam-service', success: true, errorCode: null, errorMessage: null, occurredAt: '2026-08-13T01:00:00Z', createdAt: '2026-08-13T09:00:00' }],
+      page: 1, size: 20, total: 13, pages: 1,
+    } })
+
+    const result = await listPlatformAuditLogs({ accountId: '8', page: 1, size: 20 })
+
+    expect(result.records).toHaveLength(1)
+    expect(result.total).toBe(13)
+    expect(result.pages).toBe(1)
+  })
+
+  it('maps audit filters and omits empty query values', async () => {
+    vi.mocked(http.get).mockResolvedValue({ data: { records: [], page: 1, size: 20, total: 0, pages: 0 } })
+
+    await listPlatformAuditLogs({
+      accountId: '8', page: 1, size: 20, keyword: 'admin', success: false,
+      occurredFrom: '2026-08-01T00:00:00.000Z', occurredTo: '2026-08-13T23:59:59.999Z',
+      eventType: '', resourceType: undefined,
+    })
+
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/audit/logs', { params: {
+      accountId: '8', page: 1, size: 20, keyword: 'admin', success: false,
+      occurredFrom: '2026-08-01T00:00:00.000Z', occurredTo: '2026-08-13T23:59:59.999Z',
+    } })
+  })
+
+  it('loads one audit detail', async () => {
+    vi.mocked(http.get).mockResolvedValue({ data: { id: '1', accountId: '8', operatorTenantId: '0', userId: '9', resourceId: '8', eventId: 'evt', eventType: 'PLATFORM_TENANT_UPDATE', resourceType: 'TENANT', description: '编辑客户', username: 'admin', appCode: 'ADMIN', clientType: 'WEB', clientIp: '127.0.0.1', requestId: null, traceId: null, serviceName: 'iam-service', success: true, errorCode: null, errorMessage: null, occurredAt: '2026-08-13T01:00:00Z', createdAt: '2026-08-13T09:00:00', httpMethod: 'PUT', requestUri: '/tenants/8', durationMs: 12, beforeData: '{}', afterData: '{"name":"new"}' } })
+
+    const result = await getPlatformAuditLog('1')
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/audit/logs/1')
+    expect(result.afterData).toBe('{"name":"new"}')
+  })
+})
diff --git a/src/modules/audit/api/platformAudit.ts b/src/modules/audit/api/platformAudit.ts
new file mode 100644
index 00000000..6f61c222
--- /dev/null
+++ b/src/modules/audit/api/platformAudit.ts
@@ -0,0 +1,107 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+
+export interface PlatformAuditLogListItem {
+  id: string
+  eventId: string
+  eventType: string
+  resourceType: string
+  resourceId: string | null
+  description: string | null
+  accountId: string
+  operatorTenantId: string
+  userId: string
+  username: string | null
+  appCode: string | null
+  clientType: string | null
+  clientIp: string | null
+  requestId: string | null
+  traceId: string | null
+  serviceName: string | null
+  success: boolean
+  errorCode: string | null
+  errorMessage: string | null
+  occurredAt: string
+  createdAt: string
+}
+
+export interface PlatformAuditLogDetail extends PlatformAuditLogListItem {
+  httpMethod: string | null
+  requestUri: string | null
+  clientIp: string | null
+  durationMs: number | null
+  beforeData: string | null
+  afterData: string | null
+}
+
+export interface PlatformAuditLogPage {
+  records: PlatformAuditLogListItem[]
+  page: number
+  size: number
+  total: number
+  pages: number
+}
+
+export interface PlatformAuditLogQuery {
+  accountId: string
+  page?: number
+  size?: number
+  operatorUserId?: string
+  eventType?: string
+  resourceType?: string
+  resourceId?: string
+  success?: boolean
+  occurredFrom?: string
+  occurredTo?: string
+  keyword?: string
+}
+
+type RawId = string | number | null
+type RawListItem = Omit<PlatformAuditLogListItem, 'id' | 'accountId' | 'operatorTenantId' | 'userId' | 'resourceId'> & {
+  id: RawId
+  accountId: RawId
+  operatorTenantId: RawId
+  userId: RawId
+  resourceId: RawId
+}
+type RawDetail = Omit<PlatformAuditLogDetail, keyof PlatformAuditLogListItem> & RawListItem
+type RawPage = Omit<PlatformAuditLogPage, 'records' | 'page' | 'size' | 'total' | 'pages'> & {
+  records?: RawListItem[]
+  page: number | string
+  size: number | string
+  total: number | string
+  pages?: number | string
+}
+
+const basePath = '/platform/v1/audit/logs'
+const id = (value: RawId) => value == null ? '' : String(value)
+
+function normalizeListItem(item: RawListItem): PlatformAuditLogListItem {
+  return {
+    ...item,
+    id: id(item.id),
+    accountId: id(item.accountId),
+    operatorTenantId: id(item.operatorTenantId),
+    userId: id(item.userId),
+    resourceId: item.resourceId == null ? null : String(item.resourceId),
+  }
+}
+
+export async function listPlatformAuditLogs(query: PlatformAuditLogQuery) {
+  const params = Object.fromEntries(Object.entries(query).filter(([, value]) => value !== '' && value !== null && value !== undefined))
+  const response = await http.get<ApiEnvelope<RawPage>, ApiEnvelope<RawPage>>(basePath, { params })
+  const data = unwrapApiResponse(response)
+  const size = Number(data.size || query.size || 20)
+  const total = Number(data.total || 0)
+  return {
+    records: (data.records || []).map(normalizeListItem),
+    page: Number(data.page || query.page || 1),
+    size,
+    total,
+    pages: Number(data.pages ?? (total > 0 ? Math.ceil(total / size) : 0)),
+  } satisfies PlatformAuditLogPage
+}
+
+export async function getPlatformAuditLog(idValue: string) {
+  const response = await http.get<ApiEnvelope<RawDetail>, ApiEnvelope<RawDetail>>(`${basePath}/${encodeURIComponent(idValue)}`)
+  return normalizeListItem(unwrapApiResponse(response)) as PlatformAuditLogDetail
+}
diff --git a/src/modules/audit/components/CustomerAuditLogsPanel.test.ts b/src/modules/audit/components/CustomerAuditLogsPanel.test.ts
new file mode 100644
index 00000000..45c54c40
--- /dev/null
+++ b/src/modules/audit/components/CustomerAuditLogsPanel.test.ts
@@ -0,0 +1,134 @@
+import ElementPlus from 'element-plus'
+import { createPinia, setActivePinia } from 'pinia'
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+import QueryToolbar from '@/shared/components/QueryToolbar.vue'
+import { getPlatformAuditLog, listPlatformAuditLogs } from '../api/platformAudit'
+import CustomerAuditLogsPanel from './CustomerAuditLogsPanel.vue'
+
+vi.mock('../api/platformAudit', () => ({ getPlatformAuditLog: vi.fn(), listPlatformAuditLogs: vi.fn() }))
+
+const row = { id: '1', eventId: 'evt', eventType: 'PLATFORM_TENANT_UPDATE', resourceType: 'TENANT', resourceId: '8', description: '编辑客户', accountId: '8', operatorTenantId: '0', userId: '9', username: 'platform_admin', appCode: 'ADMIN', clientType: 'WEB', clientIp: '127.0.0.1', requestId: 'req', traceId: 'trace', serviceName: 'iam-service', success: true, errorCode: null, errorMessage: null, occurredAt: '2026-08-13T01:00:00Z', createdAt: '2026-08-13T09:00:00' }
+
+function mountPanel(permissions: string[]) {
+  const pinia = createPinia(); setActivePinia(pinia)
+  const auth = useAuthStore(); auth.token = 'token'; auth.permissions = permissions
+  useAccessPreviewStore().initializeAfterLogin()
+  return mount(CustomerAuditLogsPanel, { props: { customerId: '8', customerName: '柏悦物流' }, global: { plugins: [pinia, ElementPlus] } })
+}
+
+describe('CustomerAuditLogsPanel', () => {
+  beforeEach(() => { vi.clearAllMocks(); vi.mocked(listPlatformAuditLogs).mockResolvedValue({ records: [row], page: 1, size: 20, total: 1, pages: 1 }) })
+
+  it('queries logs with the current customer id', async () => {
+    const wrapper = mountPanel(['platform:audit:list']); await flushPromises()
+    expect(listPlatformAuditLogs).toHaveBeenCalledWith({ accountId: '8', page: 1, size: 20 })
+    expect(wrapper.text()).toContain('编辑客户')
+    expect(wrapper.text()).toContain('127.0.0.1')
+    expect(wrapper.text()).toContain('编辑客户档案')
+    expect(wrapper.text()).not.toContain('PLATFORM_TENANT_UPDATE')
+    expect(wrapper.text()).toContain('平台管理员')
+    expect(wrapper.text()).toContain('客户与权限服务')
+  })
+
+  it('shows inbound audit events in Chinese without wrapping technical codes into the table', async () => {
+    vi.mocked(listPlatformAuditLogs).mockResolvedValue({ records: [{ ...row, eventType: 'INBOUND_MEASURE_APPROVE', description: '测量审核通过', serviceName: 'firstleg-service' }], page: 1, size: 20, total: 1, pages: 1 })
+    const wrapper = mountPanel(['platform:audit:list']); await flushPromises()
+
+    expect(wrapper.text()).toContain('入库测量审核通过')
+    expect(wrapper.text()).toContain('头程履约服务')
+    expect(wrapper.text()).not.toContain('INBOUND_MEASURE_APPROVE')
+  })
+
+  it('shows the server total instead of the current page row count', async () => {
+    vi.mocked(listPlatformAuditLogs).mockResolvedValue({ records: [row], page: 1, size: 20, total: 13, pages: 1 })
+    const wrapper = mountPanel(['platform:audit:list']); await flushPromises()
+
+    expect(wrapper.text()).toContain('共 13 条客户操作记录')
+  })
+
+  it('applies keyword, result and local date range only after search', async () => {
+    const wrapper = mountPanel(['platform:audit:list']); await flushPromises()
+    vi.mocked(listPlatformAuditLogs).mockClear()
+    const toolbar = wrapper.findComponent(QueryToolbar)
+    toolbar.vm.$emit('update:modelValue', { keyword: '  admin  ', success: false, occurredRange: ['2026-08-01', '2026-08-13'] })
+    await wrapper.vm.$nextTick()
+    expect(listPlatformAuditLogs).not.toHaveBeenCalled()
+
+    toolbar.vm.$emit('search', { keyword: '  admin  ', success: false, occurredRange: ['2026-08-01', '2026-08-13'] })
+    await flushPromises()
+
+    expect(listPlatformAuditLogs).toHaveBeenCalledTimes(1)
+    expect(listPlatformAuditLogs).toHaveBeenCalledWith({
+      accountId: '8', page: 1, size: 20, keyword: 'admin', success: false,
+      occurredFrom: new Date(2026, 7, 1, 0, 0, 0, 0).toISOString(),
+      occurredTo: new Date(2026, 7, 13, 23, 59, 59, 999).toISOString(),
+    })
+  })
+
+  it('resets to all logs and requests once on the first page', async () => {
+    const wrapper = mountPanel(['platform:audit:list']); await flushPromises()
+    const toolbar = wrapper.findComponent(QueryToolbar)
+    toolbar.vm.$emit('update:modelValue', { keyword: 'admin', success: true, occurredRange: ['2026-08-01', '2026-08-13'] })
+    toolbar.vm.$emit('search', { keyword: 'admin', success: true, occurredRange: ['2026-08-01', '2026-08-13'] })
+    await flushPromises()
+    vi.mocked(listPlatformAuditLogs).mockClear()
+
+    ;(toolbar.vm as unknown as { reset: () => void }).reset()
+    await flushPromises()
+
+    expect(listPlatformAuditLogs).toHaveBeenCalledTimes(1)
+    expect(wrapper.findComponent(QueryToolbar).props('modelValue')).toEqual({ keyword: '', success: '', occurredRange: [] })
+    expect(listPlatformAuditLogs).toHaveBeenCalledWith({ accountId: '8', page: 1, size: 20, keyword: undefined, success: undefined, occurredFrom: undefined, occurredTo: undefined })
+  })
+
+  it('does not query without audit permission', async () => {
+    const wrapper = mountPanel([]); await flushPromises()
+    expect(listPlatformAuditLogs).not.toHaveBeenCalled()
+    expect(wrapper.text()).toContain('暂无操作日志查看权限')
+  })
+
+  it('loads detail and formats json snapshots', async () => {
+    vi.mocked(getPlatformAuditLog).mockResolvedValue({ ...row, eventType: 'INBOUND_MEASURE_APPROVE', resourceType: 'INBOUND_MEASUREMENT', serviceName: 'firstleg-service', httpMethod: 'PUT', requestUri: '/tenants/8', clientIp: '127.0.0.1', durationMs: 12, beforeData: '{"name":"旧名称"}', afterData: '{"name":"新名称"}' })
+    const wrapper = mountPanel(['platform:audit:list']); await flushPromises()
+    await wrapper.get('button[aria-label="查看操作日志1详情"]').trigger('click'); await flushPromises()
+    expect(getPlatformAuditLog).toHaveBeenCalledWith('1')
+    expect(wrapper.text()).toContain('旧名称')
+    expect(wrapper.text()).toContain('新名称')
+    expect(wrapper.text()).toContain('入库测量审核通过')
+    expect(wrapper.text()).toContain('入库测量')
+    expect(wrapper.text()).toContain('头程履约服务')
+    expect(wrapper.text()).toContain('更新')
+    expect(wrapper.find('.audit-detail-grid').exists()).toBe(true)
+  })
+
+  it('loads the selected audit page', async () => {
+    const wrapper = mountPanel(['platform:audit:list']); await flushPromises()
+    wrapper.findComponent(QueryToolbar).vm.$emit('search', { keyword: 'tenant', success: true, occurredRange: [] })
+    await flushPromises()
+    vi.mocked(listPlatformAuditLogs).mockClear()
+
+    ;(wrapper.vm as unknown as { page: number }).page = 2
+    await flushPromises()
+
+    expect(listPlatformAuditLogs).toHaveBeenCalledWith({ accountId: '8', page: 2, size: 20, keyword: 'tenant', success: true, occurredFrom: undefined, occurredTo: undefined })
+  })
+
+  it('clears draft and applied filters when switching customers', async () => {
+    const wrapper = mountPanel(['platform:audit:list']); await flushPromises()
+    const toolbar = wrapper.findComponent(QueryToolbar)
+    toolbar.vm.$emit('update:modelValue', { keyword: 'draft', success: false, occurredRange: [] })
+    toolbar.vm.$emit('search', { keyword: 'applied', success: true, occurredRange: [] })
+    await flushPromises()
+    vi.mocked(listPlatformAuditLogs).mockClear()
+
+    await wrapper.setProps({ customerId: '9' })
+    await flushPromises()
+
+    expect(wrapper.findComponent(QueryToolbar).props('modelValue')).toEqual({ keyword: '', success: '', occurredRange: [] })
+    expect(listPlatformAuditLogs).toHaveBeenCalledTimes(1)
+    expect(listPlatformAuditLogs).toHaveBeenCalledWith({ accountId: '9', page: 1, size: 20, keyword: undefined, success: undefined, occurredFrom: undefined, occurredTo: undefined })
+  })
+})
diff --git a/src/modules/audit/components/CustomerAuditLogsPanel.vue b/src/modules/audit/components/CustomerAuditLogsPanel.vue
new file mode 100644
index 00000000..e17c1d43
--- /dev/null
+++ b/src/modules/audit/components/CustomerAuditLogsPanel.vue
@@ -0,0 +1,185 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { ref, watch } from 'vue'
+import { CircleCheck, CircleX, ScrollText } from '@lucide/vue'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AppDrawer from '@/shared/components/AppDrawer.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import { getPlatformAuditLog, listPlatformAuditLogs, type PlatformAuditLogDetail, type PlatformAuditLogListItem, type PlatformAuditLogQuery } from '../api/platformAudit'
+import { auditDescriptionLabel, auditEventLabel, auditHttpMethodLabel, auditOperatorLabel, auditResourceLabel, auditServiceLabel } from '../presentation'
+
+const props = defineProps<{ customerId: string; customerName: string }>()
+const access = useAccessPreviewStore()
+const rows = ref<PlatformAuditLogListItem[]>([])
+const page = ref(1)
+const pageSize = ref(20)
+const total = ref(0)
+const loading = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const detailOpen = ref(false)
+const detailLoading = ref(false)
+const detail = ref<PlatformAuditLogDetail | null>(null)
+const detailError = ref<ApiErrorDetails | null>(null)
+const emptyFilters = (): QueryModel => ({ keyword: '', success: '', occurredRange: [] })
+const filters = ref<QueryModel>(emptyFilters())
+const appliedFilters = ref<QueryModel>(emptyFilters())
+let requestSerial = 0
+
+const queryFields: QueryField[] = [
+  { key: 'keyword', type: 'input', label: '关键词', width: 260, placeholder: '操作内容/操作人/资源或请求标识' },
+  { key: 'success', type: 'select', label: '结果', width: 150, options: [{ label: '成功', value: true }, { label: '失败', value: false }] },
+  { key: 'occurredRange', type: 'daterange', label: '发生日期', width: 280 },
+]
+
+const columns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 92, fixed: 'left', slotName: 'actions' },
+  { key: 'description', label: '操作内容', minWidth: 220, slotName: 'description' },
+  { key: 'clientIp', label: 'IP 地址', width: 140, slotName: 'clientIp' },
+  { key: 'eventType', label: '事件类型', minWidth: 180, slotName: 'eventType' },
+  { key: 'username', label: '操作人', width: 130, slotName: 'username' },
+  { key: 'serviceName', label: '来源服务', width: 145, slotName: 'serviceName' },
+  { key: 'success', label: '结果', width: 90, slotName: 'success' },
+  { key: 'occurredAt', label: '发生时间', width: 170, slotName: 'occurredAt' },
+]
+
+const display = (value?: string | null) => value?.trim() || '—'
+const formatDate = (value?: string | null) => value ? new Date(value).toLocaleString('zh-CN', { hour12: false }) : '—'
+function formatSnapshot(value?: string | null) {
+  if (!value?.trim()) return '无'
+  try { return JSON.stringify(JSON.parse(value), null, 2) }
+  catch { return value }
+}
+
+function localDayIso(value: string, end: boolean) {
+  const [year, month, day] = value.split('-').map(Number)
+  if (!year || !month || !day) return undefined
+  return new Date(year, month - 1, day, end ? 23 : 0, end ? 59 : 0, end ? 59 : 0, end ? 999 : 0).toISOString()
+}
+
+function toQuery(customerId: string): PlatformAuditLogQuery {
+  const range = Array.isArray(appliedFilters.value.occurredRange) ? appliedFilters.value.occurredRange.map(String) : []
+  const success = appliedFilters.value.success
+  return {
+    accountId: customerId,
+    page: page.value,
+    size: pageSize.value,
+    keyword: String(appliedFilters.value.keyword || '').trim() || undefined,
+    success: typeof success === 'boolean' ? success : undefined,
+    occurredFrom: range[0] ? localDayIso(range[0], false) : undefined,
+    occurredTo: range[1] ? localDayIso(range[1], true) : undefined,
+  }
+}
+
+async function load() {
+  const customerId = props.customerId.trim()
+  const serial = ++requestSerial
+  rows.value = []
+  total.value = 0
+  loadError.value = null
+  if (!customerId || !access.can('platform:audit:list')) return
+  loading.value = true
+  try {
+    const result = await listPlatformAuditLogs(toQuery(customerId))
+    if (serial !== requestSerial || customerId !== props.customerId.trim()) return
+    rows.value = result.records
+    total.value = result.total
+  } catch (error) {
+    if (serial === requestSerial) loadError.value = getApiErrorDetails(error, '客户操作日志加载失败，请稍后重试')
+  } finally {
+    if (serial === requestSerial) loading.value = false
+  }
+}
+
+function applyFilters(model: QueryModel) {
+  appliedFilters.value = {
+    keyword: String(model.keyword || '').trim(),
+    success: typeof model.success === 'boolean' ? model.success : '',
+    occurredRange: Array.isArray(model.occurredRange) ? model.occurredRange.map(String) : [],
+  }
+  if (page.value === 1) void load()
+  else page.value = 1
+}
+
+async function openDetail(row: PlatformAuditLogListItem) {
+  detailOpen.value = true
+  detailLoading.value = true
+  detail.value = null
+  detailError.value = null
+  try { detail.value = await getPlatformAuditLog(row.id) }
+  catch (error) { detailError.value = getApiErrorDetails(error, '操作日志详情加载失败，请稍后重试') }
+  finally { detailLoading.value = false }
+}
+
+watch(() => props.customerId, () => {
+  filters.value = emptyFilters()
+  appliedFilters.value = emptyFilters()
+  if (page.value === 1) void load()
+  else page.value = 1
+}, { immediate: true })
+watch([page, pageSize], ([nextPage, nextSize], [previousPage, previousSize]) => {
+  if (nextPage !== previousPage || nextSize !== previousSize) void load()
+})
+</script>
+
+<template>
+  <section class="customer-audit-panel admin-density">
+    <div class="panel-title"><div><h2>操作日志</h2><p>{{ customerName }}已归属当前客户的档案与业务操作记录</p></div><ScrollText :size="19" /></div>
+    <div v-if="!access.can('platform:audit:list')" class="module-empty"><ScrollText :size="30" /><strong>暂无操作日志查看权限</strong><p>请联系管理员开通平台操作日志查看权限。</p></div>
+    <template v-else>
+      <QueryToolbar v-model="filters" class="audit-query" ariaLabel="客户操作日志筛选" :fields="queryFields" preference-key="customer-audit-logs-query" @search="applyFilters" />
+      <LoadErrorState v-if="loadError" title="客户操作日志加载失败" :message="loadError.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="loadError" /></template></LoadErrorState>
+    <DataTable v-else v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :loading="loading" :total="total" row-key="id" aria-label="客户操作日志列表" empty-text="当前客户暂无操作日志" preference-key="customer-audit-logs" border stripe>
+      <template #actions="{ row }"><el-button class="density-action" size="small" :aria-label="`查看操作日志${(row as PlatformAuditLogListItem).id}详情`" @click="openDetail(row as PlatformAuditLogListItem)">详情</el-button></template>
+      <template #description="{ row }"><el-tooltip :content="auditDescriptionLabel((row as PlatformAuditLogListItem).description)" placement="top" :show-after="400"><span class="cell-clamp">{{ auditDescriptionLabel((row as PlatformAuditLogListItem).description) }}</span></el-tooltip></template>
+      <template #clientIp="{ row }">{{ display((row as PlatformAuditLogListItem).clientIp) }}</template>
+      <template #eventType="{ row }"><el-tooltip :content="(row as PlatformAuditLogListItem).eventType" placement="top" :show-after="500"><span class="event-label">{{ auditEventLabel((row as PlatformAuditLogListItem).eventType) }}</span></el-tooltip></template>
+      <template #username="{ row }">{{ auditOperatorLabel((row as PlatformAuditLogListItem).username) }}</template>
+      <template #serviceName="{ row }"><el-tooltip :content="display((row as PlatformAuditLogListItem).serviceName)" placement="top" :show-after="500"><span class="service-label">{{ auditServiceLabel((row as PlatformAuditLogListItem).serviceName) }}</span></el-tooltip></template>
+      <template #success="{ row }"><el-tag :type="(row as PlatformAuditLogListItem).success ? 'success' : 'danger'">{{ (row as PlatformAuditLogListItem).success ? '成功' : '失败' }}</el-tag></template>
+      <template #occurredAt="{ row }">{{ formatDate((row as PlatformAuditLogListItem).occurredAt) }}</template>
+      <template #pagination-left>共 {{ total }} 条客户操作记录</template>
+    </DataTable>
+    </template>
+
+    <AppDrawer class="customer-audit-drawer admin-density-drawer" v-model="detailOpen" title="操作日志详情" size="min(920px, 96vw)" :loading="detailLoading" :show-footer="false">
+      <LoadErrorState v-if="detailError" title="详情加载失败" :message="detailError.message" :loading="detailLoading"><template #details><ApiErrorMeta :details="detailError" /></template></LoadErrorState>
+      <template v-else-if="detail">
+        <section class="audit-detail-hero" :class="detail.success ? 'is-success' : 'is-failed'">
+          <span class="result-icon" aria-hidden="true"><CircleCheck v-if="detail.success" :size="22" /><CircleX v-else :size="22" /></span>
+          <div class="hero-copy"><span>事件类型</span><h3>{{ auditEventLabel(detail.eventType) }}</h3><p>{{ auditDescriptionLabel(detail.description) }}</p></div>
+          <el-tag :type="detail.success ? 'success' : 'danger'" effect="light">{{ detail.success ? '操作成功' : '操作失败' }}</el-tag>
+        </section>
+
+        <section class="audit-detail-grid" aria-label="操作日志基础信息">
+          <div><span>操作人</span><strong>{{ auditOperatorLabel(detail.username) }}</strong></div>
+          <div><span>发生时间</span><strong>{{ formatDate(detail.occurredAt) }}</strong></div>
+          <div><span>来源服务</span><strong>{{ auditServiceLabel(detail.serviceName) }}</strong><small>{{ display(detail.serviceName) }}</small></div>
+          <div><span>客户端 IP</span><strong>{{ display(detail.clientIp) }}</strong></div>
+          <div><span>业务资源</span><strong>{{ auditResourceLabel(detail.resourceType) }}</strong><small>{{ display(detail.resourceId) }}</small></div>
+          <div><span>处理耗时</span><strong>{{ detail.durationMs == null ? '—' : `${detail.durationMs} ms` }}</strong></div>
+          <div class="wide request-cell"><span>请求地址</span><div><el-tag size="small" effect="plain">{{ auditHttpMethodLabel(detail.httpMethod) }}</el-tag><code>{{ display(detail.requestUri) }}</code></div></div>
+          <div class="wide identity-cell"><span>请求标识</span><strong>{{ display(detail.requestId) }}</strong><small v-if="detail.traceId">链路标识：{{ detail.traceId }}</small></div>
+        </section>
+
+        <el-alert v-if="!detail.success" class="failure-alert" type="error" :closable="false" show-icon :title="display(detail.errorMessage || detail.errorCode)" />
+        <div class="snapshot-grid"><section><h3>操作前快照</h3><p>操作执行前保留的业务数据</p><pre>{{ formatSnapshot(detail.beforeData) }}</pre></section><section><h3>操作结果快照</h3><p>操作执行后返回或保存的业务数据</p><pre>{{ formatSnapshot(detail.afterData) }}</pre></section></div>
+      </template>
+    </AppDrawer>
+  </section>
+</template>
+
+<style scoped>
+
+
+
+.customer-audit-panel { min-width:0; }.panel-title { display:flex; align-items:flex-start; justify-content:space-between; gap:var(--admin-space-6, 16px); margin-bottom:var(--admin-space-3, 8px); padding-bottom:var(--admin-space-3, 8px); border-bottom:1px solid var(--cc-border); }.panel-title h2 { margin:0; color:#344054; font-size:var(--admin-font-section, 14px); }.panel-title p { margin:5px 0 0; color:var(--cc-muted); font-size:var(--admin-font-caption, 12px); }.panel-title > svg { color:var(--cc-primary); }.audit-query { margin-bottom:var(--admin-space-5, 12px); }.module-empty { display:flex; min-height:var(--admin-empty-height, 64px); align-items:center; justify-content:center; flex-direction:column; gap:7px; color:#98a2b3; text-align:center; }.module-empty strong { color:#475467; font-size:var(--admin-font-body, 13px); }.module-empty p { margin:0; color:var(--cc-muted); font-size:var(--admin-font-caption, 12px); }
+.cell-clamp { display:-webkit-box; overflow:hidden; -webkit-box-orient:vertical; -webkit-line-clamp:2; line-height:1.45; overflow-wrap:anywhere; }.event-label { display:inline-flex; max-width:100%; padding:3px 9px; overflow:hidden; border:1px solid #dbeafe; border-radius:999px; background:#eff6ff; color:#1d4ed8; font-size:var(--admin-font-caption, 12px); line-height:1.35; text-overflow:ellipsis; white-space:nowrap; }.service-label { display:block; overflow:hidden; color:#475467; text-overflow:ellipsis; white-space:nowrap; }
+.audit-detail-hero { display:flex; align-items:flex-start; gap:13px; padding:var(--admin-space-3, 8px) var(--admin-space-4, 10px); border:1px solid #d1fadf; border-radius:0; background:#f6fef9; }.audit-detail-hero.is-failed { border-color:#fee4e2; background:#fff7f6; }.result-icon { display:grid; width:38px; height:var(--admin-tab-height, 38px); flex:0 0 auto; place-items:center; border-radius:50%; background:#dcfae6; color:#079455; }.is-failed .result-icon { background:#fee4e2; color:#d92d20; }.hero-copy { min-width:0; flex:1; }.hero-copy > span { color:#667085; font-size:var(--admin-font-caption, 12px); }.hero-copy h3 { margin:3px 0 var(--admin-space-1, 4px); color:#101828; font-size:var(--admin-font-section, 14px); }.hero-copy p { margin:0; color:#475467; font-size:var(--admin-font-body, 13px); line-height:1.55; }
+.audit-detail-grid { display:grid; grid-template-columns:repeat(3,minmax(0,1fr)); margin-top:var(--admin-space-6, 16px); overflow:hidden; border:1px solid #e4e7ec; border-radius:0; background:var(--admin-surface, #fff); }.audit-detail-grid > div { display:flex; min-width:0; min-height:var(--admin-row-height, 36px); flex-direction:column; justify-content:center; gap:5px; padding:var(--admin-space-2, 6px) var(--admin-space-4, 10px); border-right:1px solid #eaecf0; border-bottom:1px solid #eaecf0; }.audit-detail-grid > div:nth-child(3n) { border-right:0; }.audit-detail-grid > div.wide { grid-column:1/-1; border-right:0; }.audit-detail-grid > div:last-child { border-bottom:0; }.audit-detail-grid span { color:#667085; font-size:var(--admin-font-caption, 12px); }.audit-detail-grid strong { overflow-wrap:anywhere; color:#1d2939; font-size:var(--admin-font-section, 14px); font-weight:600; }.audit-detail-grid small { overflow-wrap:anywhere; color:#98a2b3; font-size:var(--admin-font-caption, 12px); }.request-cell > div { display:flex; min-width:0; align-items:center; gap:9px; }.request-cell code { min-width:0; overflow-wrap:anywhere; color:#344054; font:12px/1.55 ui-monospace,SFMono-Regular,Consolas,monospace; }.failure-alert { margin-top:var(--admin-space-6, 16px); }
+.snapshot-grid { display:grid; grid-template-columns:repeat(2,minmax(0,1fr)); gap:var(--admin-space-6, 16px); margin-top:18px; }.snapshot-grid section { min-width:0; padding:var(--admin-space-4, 10px); border:1px solid #e4e7ec; border-radius:0; background:var(--admin-surface, #fff); }.snapshot-grid h3 { margin:0; color:#344054; font-size:var(--admin-font-section, 14px); }.snapshot-grid p { margin:var(--admin-space-1, 4px) 0 var(--admin-space-4, 10px); color:#98a2b3; font-size:var(--admin-font-caption, 12px); }.snapshot-grid pre { min-height:160px; max-height:360px; margin:0; padding:14px; overflow:auto; border:1px solid #eaecf0; border-radius:8px; background:var(--admin-label-bg, #f8fafc); color:#344054; font:12px/1.65 ui-monospace,SFMono-Regular,Consolas,monospace; white-space:pre-wrap; overflow-wrap:anywhere; }
+@media(max-width:720px){.audit-detail-grid{grid-template-columns:1fr}.audit-detail-grid>div,.audit-detail-grid>div:nth-child(3n){border-right:0}.audit-detail-grid>div.wide{grid-column:auto}.snapshot-grid{grid-template-columns:1fr}.audit-detail-hero{align-items:flex-start}.audit-detail-hero>.el-tag{flex:0 0 auto}}
+</style>
diff --git a/src/modules/audit/index.ts b/src/modules/audit/index.ts
new file mode 100644
index 00000000..7695cf5a
--- /dev/null
+++ b/src/modules/audit/index.ts
@@ -0,0 +1 @@
+export { default as CustomerAuditLogsPanel } from './components/CustomerAuditLogsPanel.vue'
diff --git a/src/modules/audit/presentation.test.ts b/src/modules/audit/presentation.test.ts
new file mode 100644
index 00000000..be518f33
--- /dev/null
+++ b/src/modules/audit/presentation.test.ts
@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest'
+import { auditDescriptionLabel, auditEventLabel, auditHttpMethodLabel, auditOperatorLabel, auditResourceLabel, auditServiceLabel } from './presentation'
+
+describe('audit event presentation', () => {
+  it('uses customer-facing labels for known event codes', () => {
+    expect(auditEventLabel('PLATFORM_TENANT_UPDATE')).toBe('编辑客户档案')
+    expect(auditEventLabel('TENANT_REVIEW')).toBe('客户入驻审核')
+    expect(auditEventLabel('INBOUND_MEASURE_APPROVE')).toBe('入库测量审核通过')
+    expect(auditEventLabel('INBOUND_WEIGHT_OCR_CONFIRM')).toBe('确认 OCR 重量')
+  })
+
+  it('uses a Chinese fallback instead of exposing an unknown technical code', () => {
+    expect(auditEventLabel('INBOUND_CARTON_CREATE')).toBe('入库箱码创建')
+    expect(auditEventLabel('FUTURE_CUSTOMER_EVENT')).toBe('客户')
+    expect(auditEventLabel('')).toBe('—')
+  })
+
+  it('localizes service, resource, operator and request method values', () => {
+    expect(auditServiceLabel('firstleg-service')).toBe('头程履约服务')
+    expect(auditResourceLabel('INBOUND_MEASUREMENT')).toBe('入库测量')
+    expect(auditOperatorLabel('platform_admin')).toBe('平台管理员')
+    expect(auditHttpMethodLabel('POST')).toBe('提交')
+  })
+
+  it('prefers the Chinese half of a bilingual audit description', () => {
+    expect(auditDescriptionLabel('Approve order / 审核通过')).toBe('审核通过')
+    expect(auditDescriptionLabel('测量审核通过')).toBe('测量审核通过')
+  })
+})
diff --git a/src/modules/audit/presentation.ts b/src/modules/audit/presentation.ts
new file mode 100644
index 00000000..2a7d89bb
--- /dev/null
+++ b/src/modules/audit/presentation.ts
@@ -0,0 +1,129 @@
+const auditEventLabels: Record<string, string> = {
+  TENANT_REGISTER: '客户注册',
+  TENANT_REVIEW: '客户入驻审核',
+  PLATFORM_TENANT_UPDATE: '编辑客户档案',
+  PLATFORM_TENANT_STATUS_CHANGE: '启停客户',
+  PLATFORM_TENANT_SUBMIT_REVIEW: '提交客户审核',
+  TENANT_PROFILE_UPDATE: '编辑企业资料',
+  PLATFORM_CUSTOMER_ARCHIVE: '归档客户',
+  PLATFORM_CUSTOMER_OWNER_PASSWORD_RESET: '重置企业管理员密码',
+  PLATFORM_CUSTOMER_IMPERSONATION_TICKET_CREATE: '创建客户代登录授权',
+  TENANT_ADDRESS_CREATE: '新增客户地址',
+  TENANT_QUALIFICATION_UPLOAD: '上传企业资质',
+  PLATFORM_TENANT_QUALIFICATION_UPLOAD: '平台上传企业资质',
+  TENANT_REQUIRED_QUALIFICATION_PACKAGE_UPLOAD: '上传必填资质包',
+  PLATFORM_REQUIRED_QUALIFICATION_PACKAGE_UPLOAD: '平台上传必填资质包',
+  INBOUND_MEASURE_APPROVE: '入库测量审核通过',
+  INBOUND_MEASURE_REJECT: '驳回入库测量',
+  INBOUND_MEASURE_EXCEPTION_RELEASE: '解除测量异常',
+  INBOUND_CARTON_SCAN: '扫描入库箱码',
+  INBOUND_CARTON_MANUAL_ENTRY: '手工录入箱码',
+  INBOUND_CARTON_MEASUREMENT_COUNT_CONFIRM: '确认测量箱数',
+  INBOUND_MEASUREMENT_DRAFT_SAVE: '保存入库测量草稿',
+  INBOUND_MEASUREMENT_SUBMIT: '提交入库测量审核',
+  INBOUND_WEIGHT_IMAGE_DELETE: '删除称重图片',
+  INBOUND_WEIGHT_OCR_RECORD: '登记称重图片 OCR 原值',
+  INBOUND_WEIGHT_OCR_CORRECT: '修正 OCR 重量',
+  INBOUND_WEIGHT_OCR_CONFIRM: '确认 OCR 重量',
+  INBOUND_SMART_SPLIT: '执行智能分柜',
+  INBOUND_START_PICKING: '开始拣货',
+  INBOUND_COMPLETE_PICKING: '完成拣货',
+  INBOUND_COMPLETE_LOADING: '完成装柜',
+  INBOUND_LOADING_EVIDENCE_UPSERT: '保存装柜证据',
+  INBOUND_LOADING_EVIDENCE_VOID: '作废装柜证据',
+  ORDER_CREATE: '创建运单',
+  ORDER_UPDATE: '编辑运单',
+  ORDER_SUBMIT: '提交运单',
+  ORDER_APPROVE: '审核通过运单',
+  ORDER_REJECT: '驳回运单',
+  ORDER_CANCEL: '取消运单',
+  ORDER_ACCEPT: '受理运单',
+  ORDER_START: '开始处理运单',
+  ORDER_COMPLETE: '完成运单',
+  OCEAN_BOOKING_CREATE: '创建海运订舱',
+  OCEAN_BOOKING_RELEASE: '确认放舱',
+  OCEAN_BOOKING_CANCEL: '取消海运订舱',
+  CONTAINER_CREATE: '创建柜次',
+  CONTAINER_UPDATE: '编辑柜次',
+  CONTAINER_TRANSPORT_UPDATE: '更新柜次运输信息',
+  OUTBOUND_CONFIRM_DISPATCH: '确认国内出仓',
+  OUTBOUND_REVERSE_DISPATCH: '撤销国内出仓',
+  PDA_COMPLETE_LOADING: 'PDA 完成装柜',
+}
+
+const serviceLabels: Record<string, string> = {
+  'iam-service': '客户与权限服务',
+  'auth-service': '认证服务',
+  'order-service': '订单服务',
+  'firstleg-service': '头程履约服务',
+  'finance-service': '财务服务',
+  'warehouse-service': '仓储服务',
+  'file-service': '文件服务',
+  'audit-service': '审计服务',
+  'integration-service': '外部集成服务',
+  'event-bridge-service': '事件桥接服务',
+  gateway: '网关服务',
+}
+
+const resourceLabels: Record<string, string> = {
+  TENANT: '客户',
+  CUSTOMER: '客户',
+  FIRST_LEG_ORDER: '头程运单',
+  INBOUND: '入库单',
+  INBOUND_MEASUREMENT: '入库测量',
+  CONTAINER: '柜次',
+  OCEAN_BOOKING: '海运订舱',
+  LOADING_PLAN: '装柜计划',
+  OUTBOUND_DISPATCH: '国内出仓',
+  QUALIFICATION: '企业资质',
+  MEMBER: '企业成员',
+}
+
+const eventTokenLabels: Record<string, string> = {
+  TENANT: '客户', CUSTOMER: '客户', ORDER: '运单', FIRSTLEG: '头程履约', INBOUND: '入库',
+  MEASURE: '测量', MEASUREMENT: '测量', WEIGHT: '重量', OCR: 'OCR', CARTON: '箱码',
+  CONTAINER: '柜次', OCEAN: '海运', BOOKING: '订舱', OUTBOUND: '出仓', LOADING: '装柜',
+  CREATE: '创建', UPDATE: '更新', SUBMIT: '提交', APPROVE: '审核通过', REJECT: '驳回',
+  CANCEL: '取消', CONFIRM: '确认', COMPLETE: '完成', START: '开始', SAVE: '保存',
+  DELETE: '删除', UPLOAD: '上传', ATTACH: '关联', RELEASE: '放行', RECORD: '记录',
+  CORRECT: '修正', DRAFT: '草稿', SCAN: '扫描', MANUAL: '手工', ENTRY: '录入',
+}
+
+export function auditEventLabel(value?: string | null) {
+  const code = value?.trim()
+  if (!code) return '—'
+  if (auditEventLabels[code]) return auditEventLabels[code]
+  const translated = code.split('_').map((token) => eventTokenLabels[token]).filter(Boolean).join('')
+  return translated || '其他业务操作'
+}
+
+export function auditDescriptionLabel(value?: string | null) {
+  const text = value?.trim()
+  if (!text) return '—'
+  const chinesePart = text.split(/\s*\/\s*/).find((part) => /[\u3400-\u9fff]/.test(part))
+  return chinesePart?.trim() || text
+}
+
+export function auditServiceLabel(value?: string | null) {
+  const code = value?.trim()
+  if (!code) return '—'
+  return serviceLabels[code] ?? code.replace(/-service$/i, '服务')
+}
+
+export function auditResourceLabel(value?: string | null) {
+  const code = value?.trim()
+  if (!code) return '—'
+  return resourceLabels[code] ?? code
+}
+
+export function auditOperatorLabel(value?: string | null) {
+  const code = value?.trim()
+  if (!code) return '—'
+  return code === 'platform_admin' ? '平台管理员' : code
+}
+
+export function auditHttpMethodLabel(value?: string | null) {
+  const code = value?.trim().toUpperCase()
+  if (!code) return '—'
+  return ({ GET: '查询', POST: '提交', PUT: '更新', PATCH: '变更', DELETE: '删除' } as Record<string, string>)[code] ?? code
+}
diff --git a/src/modules/auth/pages/LoginView.test.ts b/src/modules/auth/pages/LoginView.test.ts
new file mode 100644
index 00000000..755736f1
--- /dev/null
+++ b/src/modules/auth/pages/LoginView.test.ts
@@ -0,0 +1,227 @@
+import { createPinia, setActivePinia } from 'pinia'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { flushPromises, mount } from '@vue/test-utils'
+import { createMemoryHistory, createRouter } from 'vue-router'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+import { ApiResponseError } from '@/shared/api/http'
+import LoginView from './LoginView.vue'
+
+const loginSource = readFileSync(resolve(process.cwd(), 'src/modules/auth/pages/LoginView.vue'), 'utf8')
+const formStub = {
+  template: '<form><slot /></form>',
+  setup(_: unknown, { expose }: { expose: (exposed: { validate: () => Promise<boolean> }) => void }) {
+    expose({ validate: async () => true })
+  },
+}
+
+function createMemoryStorage(): Storage {
+  const values = new Map<string, string>()
+  return {
+    get length() { return values.size },
+    clear: () => values.clear(),
+    getItem: (key) => values.get(key) ?? null,
+    key: (index) => [...values.keys()][index] ?? null,
+    removeItem: (key) => values.delete(key),
+    setItem: (key, value) => values.set(key, value),
+  }
+}
+
+describe('LoginView authentication lifecycle', () => {
+  beforeEach(() => {
+    vi.stubGlobal('localStorage', createMemoryStorage())
+  })
+
+  it('always renders a blank login form without demo credentials or hints', () => {
+    expect(loginSource).toContain("account: ''")
+    expect(loginSource).toContain("password: ''")
+    expect(loginSource).not.toContain('import.meta.env.DEV')
+    expect(loginSource).not.toContain('platform_admin')
+    expect(loginSource).not.toContain('ChangeMe123!')
+    expect(loginSource).not.toContain('demo-tip')
+  })
+
+  it('uses the admin design tokens and keeps the brand visible at 320px', () => {
+    expect(loginSource).toContain('<h1>柏悦物流管理后台</h1>')
+    expect(loginSource).toContain('class="login-mobile-brand"')
+    expect(loginSource).toContain('aria-label="平台员工登录"')
+    expect(loginSource).toContain('autocomplete="username" maxlength="100" autofocus')
+    expect(loginSource).toContain('aria-live="polite"')
+    expect(loginSource).toContain('background: var(--cc-surface-muted)')
+    expect(loginSource).toContain('border-radius: var(--cc-radius-lg)')
+    expect(loginSource).toContain('@media (max-width: 360px)')
+    expect(loginSource).not.toContain('让跨境物流管理')
+  })
+
+  it('initializes preview access after login and before redirecting', async () => {
+    const pinia = createPinia()
+    setActivePinia(pinia)
+    const auth = useAuthStore()
+    const access = useAccessPreviewStore()
+    const router = createRouter({
+      history: createMemoryHistory(),
+      routes: [
+        { path: '/login', component: LoginView },
+        { path: '/', component: { template: '<p>home</p>' } },
+      ],
+    })
+    await router.push('/login')
+    await router.isReady()
+
+    const calls: string[] = []
+    vi.spyOn(auth, 'login').mockImplementation(async () => { calls.push('login') })
+    vi.spyOn(access, 'initializeAfterLogin').mockImplementation(() => { calls.push('access') })
+    vi.spyOn(router, 'replace').mockImplementation(async () => { calls.push('replace') })
+    const wrapper = mount(LoginView, {
+      global: {
+        plugins: [pinia, router],
+        stubs: {
+          'el-form': formStub,
+          'el-form-item': { template: '<label><slot /></label>' },
+          'el-input': { props: ['modelValue'], emits: ['update:modelValue'], template: '<input :value="modelValue" @input="$emit(\'update:modelValue\', $event.target.value)" />' },
+          'el-button': { emits: ['click'], template: '<button type="button" @click="$emit(\'click\')"><slot /></button>' },
+        },
+      },
+    })
+
+    const inputs = wrapper.findAll('input')
+    await inputs[0]!.setValue('test_admin')
+    await inputs[1]!.setValue('password')
+    await wrapper.get('form').trigger('submit')
+    await flushPromises()
+
+    expect(calls).toEqual(['login', 'access', 'replace'])
+  })
+
+  it.each([
+    ['/customers?page=2', '/customers?page=2'],
+    ['/customers/reviews', '/customers/reviews'],
+    ['//example.com', '/dashboard'],
+    ['https://example.com', '/dashboard'],
+    [['/customers', '/orders/first-leg'], '/dashboard'],
+    [null, '/dashboard'],
+  ])('sanitizes the post-login redirect %j to %s', async (redirect, expected) => {
+    const pinia = createPinia()
+    setActivePinia(pinia)
+    const auth = useAuthStore()
+    const router = createRouter({
+      history: createMemoryHistory(),
+      routes: [
+        { path: '/login', component: LoginView },
+        { path: '/', component: { template: '<p>home</p>' } },
+      ],
+    })
+    await router.push({ path: '/login', query: { redirect } })
+    await router.isReady()
+    vi.spyOn(auth, 'login').mockResolvedValue()
+    const replace = vi.spyOn(router, 'replace').mockResolvedValue()
+    const wrapper = mount(LoginView, {
+      global: {
+        plugins: [pinia, router],
+        stubs: {
+          'el-form': formStub,
+          'el-form-item': { template: '<label><slot /></label>' },
+          'el-input': { props: ['modelValue'], emits: ['update:modelValue'], template: '<input :value="modelValue" @input="$emit(\'update:modelValue\', $event.target.value)" />' },
+          'el-button': { emits: ['click'], template: '<button type="button" @click="$emit(\'click\')"><slot /></button>' },
+        },
+      },
+    })
+
+    const inputs = wrapper.findAll('input')
+    await inputs[0]!.setValue('test_admin')
+    await inputs[1]!.setValue('password')
+    await wrapper.get('form').trigger('submit')
+    await flushPromises()
+
+    expect(replace).toHaveBeenCalledWith(expected)
+  })
+
+  it('preserves the form and reports a recoverable error when login fails', async () => {
+    const pinia = createPinia()
+    setActivePinia(pinia)
+    const auth = useAuthStore()
+    const access = useAccessPreviewStore()
+    const router = createRouter({
+      history: createMemoryHistory(),
+      routes: [
+        { path: '/login', component: LoginView },
+        { path: '/customers', component: { template: '<p>customers</p>' } },
+      ],
+    })
+    await router.push('/login')
+    await router.isReady()
+    vi.spyOn(auth, 'login').mockRejectedValue(new Error('network unavailable'))
+    const initialize = vi.spyOn(access, 'initializeAfterLogin')
+    const replace = vi.spyOn(router, 'replace')
+    const wrapper = mount(LoginView, {
+      global: {
+        plugins: [pinia, router],
+        stubs: {
+          'el-form': formStub,
+          'el-form-item': { template: '<label><slot /></label>' },
+          'el-input': { props: ['modelValue'], emits: ['update:modelValue'], template: '<input :value="modelValue" @input="$emit(\'update:modelValue\', $event.target.value)" />' },
+          'el-button': { emits: ['click'], template: '<button type="button" @click="$emit(\'click\')"><slot /></button>' },
+        },
+      },
+    })
+
+    const inputs = wrapper.findAll('input')
+    await inputs[0]!.setValue('test_admin')
+    await inputs[1]!.setValue('password')
+    await wrapper.get('form').trigger('submit')
+    await flushPromises()
+
+    expect(wrapper.get('[role="alert"]').text()).toContain('登录失败，请检查账号和密码后重试')
+    expect(wrapper.get('[role="alert"]').text()).not.toContain('network unavailable')
+    expect(initialize).not.toHaveBeenCalled()
+    expect(replace).not.toHaveBeenCalled()
+  })
+
+  it('shows the backend credential error and diagnostic identifiers', async () => {
+    const pinia = createPinia()
+    setActivePinia(pinia)
+    const auth = useAuthStore()
+    const router = createRouter({
+      history: createMemoryHistory(),
+      routes: [
+        { path: '/login', component: LoginView },
+        { path: '/', component: { template: '<p>home</p>' } },
+      ],
+    })
+    await router.push('/login')
+    await router.isReady()
+    vi.spyOn(auth, 'login').mockRejectedValue(new ApiResponseError(
+      '用户名或密码错误',
+      'A0401',
+      undefined,
+      null,
+      'request-login',
+      'trace-login',
+    ))
+    const wrapper = mount(LoginView, {
+      global: {
+        plugins: [pinia, router],
+        stubs: {
+          'el-form': formStub,
+          'el-form-item': { template: '<label><slot /></label>' },
+          'el-input': { props: ['modelValue'], emits: ['update:modelValue'], template: '<input :value="modelValue" @input="$emit(\'update:modelValue\', $event.target.value)" />' },
+          'el-button': { emits: ['click'], template: '<button type="button" @click="$emit(\'click\')"><slot /></button>' },
+        },
+      },
+    })
+
+    const inputs = wrapper.findAll('input')
+    await inputs[0]!.setValue('platform_admin')
+    await inputs[1]!.setValue('incorrect-password')
+    await wrapper.get('form').trigger('submit')
+    await flushPromises()
+
+    const alert = wrapper.get('[role="alert"]').text()
+    expect(alert).toContain('用户名或密码错误')
+    expect(alert).toContain('request-login')
+    expect(alert).toContain('trace-login')
+    expect(alert).not.toContain('登录状态已失效')
+  })
+})
diff --git a/src/modules/auth/pages/LoginView.vue b/src/modules/auth/pages/LoginView.vue
new file mode 100644
index 00000000..a520e614
--- /dev/null
+++ b/src/modules/auth/pages/LoginView.vue
@@ -0,0 +1,121 @@
+<script setup lang="ts">
+import { reactive, ref } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { ElMessage, type FormInstance, type FormRules } from 'element-plus'
+import { ArrowRight, LockKeyhole, ShieldCheck, UserRound } from '@lucide/vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import baiyueLogoWhite from '@/assets/brand/baiyue-logo-white.png'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import { sanitizeInternalPath } from '@/core/routing/accessDecision'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+
+const route = useRoute()
+const router = useRouter()
+const auth = useAuthStore()
+const access = useAccessPreviewStore()
+const loading = ref(false)
+const loginError = ref<ApiErrorDetails | null>(null)
+const formRef = ref<FormInstance>()
+const form = reactive({
+  account: '',
+  password: '',
+})
+const rules: FormRules<typeof form> = {
+  account: [{ required: true, message: '请输入账号', trigger: 'blur' }],
+  password: [{ required: true, message: '请输入密码', trigger: 'blur' }],
+}
+
+async function submit() {
+  loginError.value = null
+  const isValid = await formRef.value?.validate().catch(() => false)
+  if (!isValid) return
+  loading.value = true
+  try {
+    await auth.login(form.account, form.password)
+    access.initializeAfterLogin()
+    ElMessage.success('登录成功')
+    const requestedPath = sanitizeInternalPath(route.query.redirect)
+    const targetPath = requestedPath === '/'
+      ? access.firstAccessiblePath ?? '/403'
+      : requestedPath
+    await router.replace(targetPath)
+  } catch (error) {
+    loginError.value = getApiErrorDetails(
+      error,
+      '登录失败，请检查账号和密码后重试',
+      { preserveAuthenticationMessage: true },
+    )
+    ElMessage.error(loginError.value.message)
+  } finally {
+    loading.value = false
+  }
+}
+</script>
+
+<template>
+  <div class="login-page">
+    <section class="login-intro">
+      <div class="login-brand"><img class="login-brand-logo" :src="baiyueLogoWhite" alt="柏悦物流" /></div>
+      <div>
+        <h1>柏悦物流管理后台</h1>
+        <p class="intro-copy">平台内部运营与管理系统</p>
+      </div>
+      <div class="security-note">
+        <ShieldCheck :size="22" />
+        <span>平台内部系统，请使用授权账号登录</span>
+      </div>
+    </section>
+
+    <section class="login-panel">
+      <div class="login-card">
+        <div class="login-mobile-brand"><img :src="baiyueLogoWhite" alt="柏悦物流" /></div>
+        <div class="login-card-icon"><LockKeyhole :size="24" /></div>
+        <h2>登录管理后台</h2>
+        <p>使用平台内部员工账号登录</p>
+        <el-form ref="formRef" :model="form" :rules="rules" label-position="top" size="large" aria-label="平台员工登录" @submit.prevent="submit">
+          <el-form-item label="账号" prop="account" required>
+            <el-input v-model.trim="form.account" placeholder="请输入账号" :prefix-icon="UserRound" autocomplete="username" maxlength="100" autofocus />
+          </el-form-item>
+          <el-form-item label="密码" prop="password" required>
+            <el-input v-model="form.password" type="password" show-password placeholder="请输入密码" :prefix-icon="LockKeyhole" autocomplete="current-password" maxlength="128" />
+          </el-form-item>
+          <el-button class="login-submit" native-type="submit" type="primary" :loading="loading">
+            登录 <ArrowRight :size="17" />
+          </el-button>
+        </el-form>
+        <div v-if="loginError" class="login-error" role="alert" aria-live="polite"><p>{{ loginError.message }}</p><ApiErrorMeta :details="loginError" /></div>
+      </div>
+    </section>
+  </div>
+</template>
+
+<style scoped>
+.login-page { min-width: 0; min-height: 100svh; background: var(--cc-surface); color: var(--cc-text); }
+.login-intro { min-width: 0; background: var(--cc-navy); }
+.login-intro h1 { max-width: 560px; margin: 16px 0 14px; font-size: 40px; line-height: 1.2; overflow-wrap: anywhere; }
+.intro-copy { margin: 0; color: #cbd5e1; font-size: 15px; line-height: 1.7; overflow-wrap: anywhere; }
+.login-panel { min-width: 0; background: var(--cc-surface-muted); }
+.login-card { min-width: 0; padding: 32px; border: 1px solid var(--cc-border); border-radius: var(--cc-radius-lg); background: var(--cc-surface); box-shadow: var(--cc-shadow-md); }
+.login-card-icon { border-radius: var(--cc-radius-lg); background: var(--cc-primary-soft); }
+.login-card h2, .login-card > p { overflow-wrap: anywhere; }
+.login-mobile-brand { display: none; }
+.login-submit { min-height: 44px; }
+.login-error { min-width: 0; padding: 12px 14px; border: 1px solid #fecdca; border-radius: var(--cc-radius-md); background: var(--cc-danger-soft); color: var(--cc-danger); overflow-wrap: anywhere; }
+.login-error :deep(*) { max-width: 100%; overflow-wrap: anywhere; }
+.login-card :deep(.el-input__wrapper:focus-within) { box-shadow: 0 0 0 1px var(--cc-primary) inset, 0 0 0 3px var(--cc-primary-soft); }
+
+@media (max-width: 960px) {
+  .login-panel { align-items: start; padding: 24px; }
+  .login-card { width: min(440px, 100%); margin: auto; padding: 28px; }
+  .login-mobile-brand { display: flex; min-height: 52px; align-items: center; margin: -28px -28px 28px; padding: 12px 20px; border-radius: var(--cc-radius-lg) var(--cc-radius-lg) 0 0; background: var(--cc-navy); }
+  .login-mobile-brand img { display: block; width: 154px; height: 48px; object-fit: contain; object-position: left center; }
+}
+
+@media (max-width: 360px) {
+  .login-panel { padding: 12px; }
+  .login-card { padding: 20px; }
+  .login-mobile-brand { margin: -20px -20px 24px; padding-inline: 16px; }
+  .login-card h2 { font-size: 24px; }
+}
+</style>
diff --git a/src/modules/container-loading/api/containerArrivalTimes.test.ts b/src/modules/container-loading/api/containerArrivalTimes.test.ts
new file mode 100644
index 00000000..c2fe6c21
--- /dev/null
+++ b/src/modules/container-loading/api/containerArrivalTimes.test.ts
@@ -0,0 +1,20 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { listContainerArrivalTimes, updateContainerExpectedArrival } from './containerArrivalTimes'
+
+vi.mock('@/shared/api/overseasHttp', () => ({ overseasHttp: { post: vi.fn(), put: vi.fn() } }))
+
+describe('container arrival-time overseas API', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it('queries visible containers and updates the whole-container expected arrival', async () => {
+    vi.mocked(overseasHttp.post).mockResolvedValue({ code: '200', data: [{ sourceContainerBookingId: '9001', estimatedWarehouseArrivalAt: null, actualWarehouseArrivalAt: null, version: 0 }] })
+    vi.mocked(overseasHttp.put).mockResolvedValue({ code: '200', data: { sourceContainerBookingId: '9001', estimatedWarehouseArrivalAt: '2026-09-25T15:31:00', actualWarehouseArrivalAt: null, version: 1 } } as never)
+
+    await listContainerArrivalTimes(['9001'])
+    await updateContainerExpectedArrival('9001', { estimatedWarehouseArrivalAt: '2026-09-25T15:31:00', expectedVersion: 0 })
+
+    expect(overseasHttp.post).toHaveBeenCalledWith('/platform/v1/last-leg/orders/container-arrival-times/query', { sourceContainerBookingIds: ['9001'] })
+    expect(overseasHttp.put).toHaveBeenCalledWith('/platform/v1/last-leg/orders/container-summaries/9001/expected-arrival', { estimatedWarehouseArrivalAt: '2026-09-25T15:31:00', expectedVersion: 0 }, { headers: { 'Idempotency-Key': expect.stringContaining('container-expected-arrival-9001-') } })
+  })
+})
diff --git a/src/modules/container-loading/api/containerArrivalTimes.ts b/src/modules/container-loading/api/containerArrivalTimes.ts
new file mode 100644
index 00000000..be5a29c1
--- /dev/null
+++ b/src/modules/container-loading/api/containerArrivalTimes.ts
@@ -0,0 +1,37 @@
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+
+export interface ContainerArrivalTime {
+  sourceContainerBookingId: string
+  estimatedWarehouseArrivalAt: string | null
+  actualWarehouseArrivalAt: string | null
+  version: number
+}
+
+const queryPath = '/platform/v1/last-leg/orders/container-arrival-times/query'
+
+function operationId(containerBookingId: string) {
+  return `container-expected-arrival-${containerBookingId}-${Date.now()}-${crypto.randomUUID()}`
+}
+
+export async function listContainerArrivalTimes(sourceContainerBookingIds: string[]) {
+  if (!sourceContainerBookingIds.length) return []
+  const response = await overseasHttp.post<ApiEnvelope<ContainerArrivalTime[]>, ApiEnvelope<ContainerArrivalTime[]>>(
+    queryPath,
+    { sourceContainerBookingIds },
+  )
+  return (unwrapApiResponse(response) || []).map((item) => ({ ...item, version: Number(item.version || 0) }))
+}
+
+export async function updateContainerExpectedArrival(
+  sourceContainerBookingId: string,
+  body: { estimatedWarehouseArrivalAt: string; expectedVersion: number; remark?: string },
+) {
+  const response = await overseasHttp.put<ApiEnvelope<ContainerArrivalTime>, ApiEnvelope<ContainerArrivalTime>>(
+    `/platform/v1/last-leg/orders/container-summaries/${encodeURIComponent(sourceContainerBookingId)}/expected-arrival`,
+    body,
+    { headers: { 'Idempotency-Key': operationId(sourceContainerBookingId) } },
+  )
+  const result = unwrapApiResponse(response)
+  return { ...result, version: Number(result.version || 0) }
+}
diff --git a/src/modules/container-loading/api/overseasContainerFees.test.ts b/src/modules/container-loading/api/overseasContainerFees.test.ts
new file mode 100644
index 00000000..6920c5a7
--- /dev/null
+++ b/src/modules/container-loading/api/overseasContainerFees.test.ts
@@ -0,0 +1,25 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { adjustOverseasContainerFee, createOverseasContainerFee, listOverseasContainerCustomers, listOverseasContainerFees, reviewOverseasContainerFee, submitOverseasContainerFee, voidOverseasContainerFee, type OverseasContainerFeeSaveRequest } from './overseasContainerFees'
+
+const raw = { id: 91, sourceFeeId: 81, sourceVersion: 2, customerId: 11, customerName: '客户A', sourceType: 'OVERSEAS_CONTAINER_FEE', businessType: 'OVERSEAS_CONTAINER', businessId: 99, businessNo: 'CONT-99', containerBookingId: 99, containerNo: 'CONT-99', feeItemCode: 'PORT_FEE', feeItemName: '港口费', direction: 'PAYABLE', amount: 300, currency: 'CNY', reviewStatus: 'DRAFT', sourceStatus: 'ACTIVE', businessDate: '2026-09-08' }
+const fee: OverseasContainerFeeSaveRequest = { customerId: '11', customerName: '客户A', sourceType: 'OVERSEAS_CONTAINER_FEE', businessType: 'OVERSEAS_CONTAINER', businessId: '99', businessNo: 'CONT-99', orderId: null, inboundId: null, inboundCode: null, containerId: null, containerBookingId: '99', containerNo: 'CONT-99', warehouseId: null, feeItemCode: 'PORT_FEE', feeItemName: '港口费', direction: 'PAYABLE', supplierId: '71', supplierName: '港口服务商', supplierCategory: 'TRUCKING', settlementMode: 'ON_ACCOUNT', paidAt: null, paymentMethod: null, paymentReferenceNo: null, paymentVoucherFileIds: null, businessDate: '2026-09-08', currency: 'CNY', amount: 300 }
+describe('overseas container fees API', () => {
+  beforeEach(() => vi.restoreAllMocks())
+  it('loads all fees and customers with two container aggregate requests', async () => {
+    const get = vi.spyOn(overseasHttp, 'get').mockResolvedValueOnce({ code: '200', data: [raw] }).mockResolvedValueOnce({ code: '200', data: [{ customerId: 11, customerName: '客户A' }] })
+    await expect(listOverseasContainerFees('99')).resolves.toMatchObject([{ sourceFeeId: '81', containerBookingId: '99', feeItemCode: 'PORT_FEE' }])
+    await expect(listOverseasContainerCustomers('99')).resolves.toEqual([{ customerId: '11', customerName: '客户A' }])
+    expect(get).toHaveBeenNthCalledWith(1, '/platform/v1/last-leg/finance-fee-sources', { params: { containerBookingId: '99', businessType: 'OVERSEAS_CONTAINER' } })
+    expect(get).toHaveBeenNthCalledWith(2, '/platform/v1/last-leg/finance-fee-sources/container-customers', { params: { containerBookingId: '99' } })
+  })
+  it('uses the exact create and lifecycle action contracts', async () => {
+    const post = vi.spyOn(overseasHttp, 'post').mockResolvedValue({ code: '200', data: raw })
+    await createOverseasContainerFee(fee, 'create-1'); await submitOverseasContainerFee('81', 'submit-1'); await reviewOverseasContainerFee('81', 'APPROVE', null, 'review-1'); await adjustOverseasContainerFee('81', 2, fee, 'adjust-1'); await voidOverseasContainerFee('81', 2, '重复费用', 'void-1')
+    expect(post).toHaveBeenCalledWith('/platform/v1/last-leg/finance-fee-sources', fee, { headers: { 'Idempotency-Key': 'create-1' } })
+    expect(post).toHaveBeenCalledWith('/platform/v1/last-leg/finance-fee-sources/81/submit', { idempotencyKey: 'submit-1' })
+    expect(post).toHaveBeenCalledWith('/platform/v1/last-leg/finance-fee-sources/81/review', { decision: 'APPROVE', reason: null, idempotencyKey: 'review-1' })
+    expect(post).toHaveBeenCalledWith('/platform/v1/last-leg/finance-fee-sources/81/adjust', { expectedVersion: 2, fee, idempotencyKey: 'adjust-1' })
+    expect(post).toHaveBeenCalledWith('/platform/v1/last-leg/finance-fee-sources/81/void', { expectedVersion: 2, reason: '重复费用', idempotencyKey: 'void-1' })
+  })
+})
diff --git a/src/modules/container-loading/api/overseasContainerFees.ts b/src/modules/container-loading/api/overseasContainerFees.ts
new file mode 100644
index 00000000..57f5641d
--- /dev/null
+++ b/src/modules/container-loading/api/overseasContainerFees.ts
@@ -0,0 +1,66 @@
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+
+const basePath = '/platform/v1/last-leg/finance-fee-sources'
+type RawResource = Record<string, unknown>
+
+export type OverseasContainerFeeItem = 'PORT_FEE' | 'STORAGE_FEE' | 'CONTAINER_REPAIR_FEE' | 'CRANE_FEE' | 'TERMINAL_DRAYAGE_FEE' | 'OTHER'
+export type OverseasContainerFeeDirection = 'RECEIVABLE' | 'PAYABLE'
+
+export interface OverseasContainerCustomer { customerId: string; customerName: string | null }
+export interface OverseasContainerFeeSource {
+  id: string; sourceFeeId: string; sourceVersion: number; customerId: string; customerName: string | null
+  sourceType: 'OVERSEAS_CONTAINER_FEE'; businessType: 'OVERSEAS_CONTAINER'; businessId: string; businessNo: string
+  containerBookingId: string; containerNo: string; feeItemCode: OverseasContainerFeeItem; feeItemName: string
+  direction: OverseasContainerFeeDirection; supplierId: string | null; supplierName: string | null; supplierCategory: string | null
+  settlementMode: string | null; paidAt: string | null; paymentMethod: string | null; paymentReferenceNo: string | null
+  paymentVoucherFileIds: string[]; businessDate: string; currency: 'CNY'; amount: number
+  reviewStatus: 'DRAFT' | 'PENDING' | 'APPROVED' | 'REJECTED'; sourceStatus: 'ACTIVE' | 'SUPERSEDED' | 'VOIDED'
+  reviewReason: string | null; reviewedAt: string | null
+}
+export interface OverseasContainerFeeSaveRequest {
+  customerId: string; customerName: string | null; sourceType: 'OVERSEAS_CONTAINER_FEE'; businessType: 'OVERSEAS_CONTAINER'
+  businessId: string; businessNo: string; orderId: null; inboundId: null; inboundCode: null; containerId: null
+  containerBookingId: string; containerNo: string; warehouseId: null; feeItemCode: OverseasContainerFeeItem; feeItemName: string
+  direction: OverseasContainerFeeDirection; supplierId: string | null; supplierName: string | null; supplierCategory: string | null
+  settlementMode: 'ON_ACCOUNT' | 'DIRECT_PAID' | null; paidAt: string | null
+  paymentMethod: 'ONLINE' | 'BANK_TRANSFER' | 'CASH' | 'OTHER' | null; paymentReferenceNo: string | null; paymentVoucherFileIds: string[] | null
+  businessDate: string; currency: 'CNY'; amount: number
+}
+
+const text = (value: unknown) => value == null || value === '' ? null : String(value)
+const requiredText = (value: unknown) => String(value ?? '')
+const numberValue = (value: unknown) => Number.isFinite(Number(value)) ? Number(value) : 0
+function normalizeFee(raw: RawResource): OverseasContainerFeeSource {
+  return {
+    id: requiredText(raw.id), sourceFeeId: requiredText(raw.sourceFeeId), sourceVersion: numberValue(raw.sourceVersion), customerId: requiredText(raw.customerId), customerName: text(raw.customerName),
+    sourceType: 'OVERSEAS_CONTAINER_FEE', businessType: 'OVERSEAS_CONTAINER', businessId: requiredText(raw.businessId), businessNo: requiredText(raw.businessNo), containerBookingId: requiredText(raw.containerBookingId), containerNo: requiredText(raw.containerNo),
+    feeItemCode: raw.feeItemCode as OverseasContainerFeeItem, feeItemName: requiredText(raw.feeItemName), direction: raw.direction as OverseasContainerFeeDirection,
+    supplierId: text(raw.supplierId), supplierName: text(raw.supplierName), supplierCategory: text(raw.supplierCategory), settlementMode: text(raw.settlementMode), paidAt: text(raw.paidAt), paymentMethod: text(raw.paymentMethod), paymentReferenceNo: text(raw.paymentReferenceNo),
+    paymentVoucherFileIds: Array.isArray(raw.paymentVoucherFileIds) ? raw.paymentVoucherFileIds.map(String) : [], businessDate: requiredText(raw.businessDate), currency: 'CNY', amount: numberValue(raw.amount),
+    reviewStatus: raw.reviewStatus as OverseasContainerFeeSource['reviewStatus'], sourceStatus: raw.sourceStatus as OverseasContainerFeeSource['sourceStatus'], reviewReason: text(raw.reviewReason), reviewedAt: text(raw.reviewedAt),
+  }
+}
+export async function listOverseasContainerFees(containerBookingId: string) {
+  const response = await overseasHttp.get<ApiEnvelope<RawResource[]>, ApiEnvelope<RawResource[]>>(basePath, { params: { containerBookingId, businessType: 'OVERSEAS_CONTAINER' } })
+  return unwrapApiResponse(response).map(normalizeFee)
+}
+export async function listOverseasContainerCustomers(containerBookingId: string) {
+  const response = await overseasHttp.get<ApiEnvelope<Array<{ customerId: unknown; customerName?: unknown }>>, ApiEnvelope<Array<{ customerId: unknown; customerName?: unknown }>>>(`${basePath}/container-customers`, { params: { containerBookingId } })
+  return unwrapApiResponse(response).map((item) => ({ customerId: requiredText(item.customerId), customerName: text(item.customerName) }))
+}
+export async function createOverseasContainerFee(payload: OverseasContainerFeeSaveRequest, idempotencyKey: string) {
+  return normalizeFee(unwrapApiResponse(await overseasHttp.post<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(basePath, payload, { headers: { 'Idempotency-Key': idempotencyKey } })))
+}
+export async function submitOverseasContainerFee(sourceFeeId: string, idempotencyKey: string) {
+  return normalizeFee(unwrapApiResponse(await overseasHttp.post<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/${encodeURIComponent(sourceFeeId)}/submit`, { idempotencyKey })))
+}
+export async function reviewOverseasContainerFee(sourceFeeId: string, decision: 'APPROVE' | 'REJECT', reason: string | null, idempotencyKey: string) {
+  return normalizeFee(unwrapApiResponse(await overseasHttp.post<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/${encodeURIComponent(sourceFeeId)}/review`, { decision, reason, idempotencyKey })))
+}
+export async function adjustOverseasContainerFee(sourceFeeId: string, expectedVersion: number, fee: OverseasContainerFeeSaveRequest, idempotencyKey: string) {
+  return normalizeFee(unwrapApiResponse(await overseasHttp.post<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/${encodeURIComponent(sourceFeeId)}/adjust`, { expectedVersion, fee, idempotencyKey })))
+}
+export async function voidOverseasContainerFee(sourceFeeId: string, expectedVersion: number, reason: string, idempotencyKey: string) {
+  return normalizeFee(unwrapApiResponse(await overseasHttp.post<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/${encodeURIComponent(sourceFeeId)}/void`, { expectedVersion, reason, idempotencyKey })))
+}
diff --git a/src/modules/container-loading/api/platformContainerCustoms.test.ts b/src/modules/container-loading/api/platformContainerCustoms.test.ts
new file mode 100644
index 00000000..199831eb
--- /dev/null
+++ b/src/modules/container-loading/api/platformContainerCustoms.test.ts
@@ -0,0 +1,66 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import { completeAllBuyContainerCustoms, downloadContainerCustomsCompletion, downloadContainerCustomsDocument, getContainerCustoms, startContainerCustoms, uploadContainerCustomsCompletion } from './platformContainerCustoms'
+
+const customs = {
+  aggregateId: 2092438843630391401n, loadingPlanId: 2092438843630391402n, containerBookingId: 2092438843630391403n,
+  planNo: 'LP-1', cabinetNo: 'CB-1', containerNo: 'MSCU-1', status: 'READY_TO_START', hasActualCargo: true, version: '3', taxRefundCount: 1, coveredTaxRefundCount: 1,
+  inbounds: [{ inboundId: 2092438843630391404n, orderId: 2092438843630391405n, orderNo: 'O-1', inboundCode: 'RK-1', tenantId: 2092438843630391406n, customerName: '客户一', taxMode: 'TAX_REFUND', covered: true }],
+  documents: [{ documentId: 2092438843630391407n, tenantId: 2092438843630391406n, source: { fileId: '2092438843630391408', fileName: 'source.pdf', fileHash: 'hash', sizeBytes: 1, version: 2, uploadedAt: '2026-08-28T10:00:00' }, inboundIds: ['2092438843630391404'], inboundCodes: ['RK-1'], frozen: true, completion: null }],
+  startedAt: null, completedAt: null,
+}
+
+describe('platform container customs API', () => {
+  beforeEach(() => vi.restoreAllMocks())
+
+  it('uses the frozen customs-v1 paths and preserves long ids as strings', async () => {
+    const get = vi.spyOn(http, 'get').mockResolvedValue({ code: '200', message: 'ok', data: customs })
+    const result = await getContainerCustoms('2092438843630391402')
+    expect(result).not.toBeNull()
+    if (!result) throw new Error('expected completed loading plan customs view')
+    expect(get).toHaveBeenCalledWith('/platform/v1/customs/loading-plans/2092438843630391402')
+    expect(result).toMatchObject({ aggregateId: '2092438843630391401', loadingPlanId: '2092438843630391402', containerBookingId: '2092438843630391403' })
+    expect(result.inbounds[0]).toMatchObject({ inboundId: '2092438843630391404', orderId: '2092438843630391405', tenantId: '2092438843630391406' })
+    expect(result.documents[0]?.documentId).toBe('2092438843630391407')
+  })
+
+  it('returns null while the loading plan is not completed', async () => {
+    vi.spyOn(http, 'get').mockResolvedValue({ code: '200', message: 'ok', data: null })
+
+    await expect(getContainerCustoms('2097922185010147329')).resolves.toBeNull()
+  })
+
+  it('sends confirmed start and all-buy completion with optimistic version and idempotency', async () => {
+    const post = vi.spyOn(http, 'post').mockResolvedValue({ code: '200', message: 'ok', data: customs })
+    await startContainerCustoms('2092438843630391402', 3)
+    await completeAllBuyContainerCustoms('2092438843630391402', 4)
+    expect(post.mock.calls[0]?.slice(0, 2)).toEqual(['/platform/v1/customs/loading-plans/2092438843630391402/start', { expectedVersion: 3, confirm: true, remark: null }])
+    expect(post.mock.calls[1]?.slice(0, 2)).toEqual(['/platform/v1/customs/loading-plans/2092438843630391402/complete-all-buy', { expectedVersion: 4, confirm: true, remark: null }])
+    expect(post.mock.calls[0]?.[2]).toMatchObject({ headers: { 'Idempotency-Key': expect.any(String) } })
+  })
+
+  it('uploads one completion file with final-confirmation query parameters', async () => {
+    const document = { ...customs.documents[0], documentId: '2092438843630391407', tenantId: '2092438843630391406' }
+    const post = vi.spyOn(http, 'post').mockResolvedValue({ code: '200', message: 'ok', data: document })
+    const completion = new File(['done'], 'done.pdf')
+    await uploadContainerCustomsCompletion('2092438843630391407', completion, 0, true)
+    expect(post.mock.calls[0]?.[0]).toBe('/platform/v1/customs/loading-plans/documents/2092438843630391407/completion/upload')
+    expect((post.mock.calls[0]?.[1] as FormData).get('file')).toBe(completion)
+    expect(post.mock.calls[0]?.[2]).toMatchObject({ params: { expectedVersion: 0, finalConfirmation: true }, headers: { 'Content-Type': 'multipart/form-data', 'Idempotency-Key': expect.any(String) } })
+  })
+
+  it('keeps source and completion downloads isolated on the long document id', async () => {
+    const source = new Blob(['source'])
+    const completion = new Blob(['completion'])
+    const get = vi.spyOn(http, 'get').mockResolvedValueOnce(source).mockResolvedValueOnce(completion)
+    const documentId = '2092438843630391407'
+
+    await expect(downloadContainerCustomsDocument(documentId)).resolves.toBe(source)
+    await expect(downloadContainerCustomsCompletion(documentId)).resolves.toBe(completion)
+
+    expect(get.mock.calls).toEqual([
+      [`/platform/v1/customs/loading-plans/documents/${documentId}/download`, { responseType: 'blob' }],
+      [`/platform/v1/customs/loading-plans/documents/${documentId}/completion/download`, { responseType: 'blob' }],
+    ])
+  })
+})
diff --git a/src/modules/container-loading/api/platformContainerCustoms.ts b/src/modules/container-loading/api/platformContainerCustoms.ts
new file mode 100644
index 00000000..ccfaa157
--- /dev/null
+++ b/src/modules/container-loading/api/platformContainerCustoms.ts
@@ -0,0 +1,118 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+
+export type ContainerCustomsStatus = 'WAITING_CUSTOMER_DOCUMENTS' | 'READY_TO_START' | 'DECLARING' | 'COMPLETED'
+export type ContainerCustomsTaxMode = 'TAX_REFUND' | 'BUY_DECLARATION'
+
+export interface ContainerCustomsFile {
+  fileId: string
+  fileName: string
+  fileHash: string
+  sizeBytes: number
+  version: number
+  uploadedAt: string
+}
+
+export interface ContainerCustomsInbound {
+  inboundId: string
+  orderId: string
+  orderNo: string
+  inboundCode: string
+  tenantId: string
+  customerName: string
+  taxMode: ContainerCustomsTaxMode
+  covered: boolean
+}
+
+export interface ContainerCustomsDocument {
+  documentId: string
+  tenantId: string
+  source: ContainerCustomsFile
+  inboundIds: string[]
+  inboundCodes: string[]
+  frozen: boolean
+  completion: ContainerCustomsFile | null
+}
+
+export interface ContainerCustomsView {
+  aggregateId: string
+  loadingPlanId: string
+  containerBookingId: string
+  planNo: string
+  cabinetNo: string
+  containerNo: string | null
+  status: ContainerCustomsStatus
+  hasActualCargo: boolean
+  version: number
+  taxRefundCount: number
+  coveredTaxRefundCount: number
+  inbounds: ContainerCustomsInbound[]
+  documents: ContainerCustomsDocument[]
+  startedAt: string | null
+  completedAt: string | null
+}
+
+interface RawContainerCustomsView extends Omit<ContainerCustomsView, 'aggregateId' | 'loadingPlanId' | 'containerBookingId' | 'version' | 'inbounds' | 'documents'> {
+  aggregateId: string | number
+  loadingPlanId: string | number
+  containerBookingId: string | number
+  version: string | number
+  inbounds: Array<Omit<ContainerCustomsInbound, 'inboundId' | 'orderId' | 'tenantId'> & { inboundId: string | number; orderId: string | number; tenantId: string | number }>
+  documents: Array<Omit<ContainerCustomsDocument, 'documentId' | 'tenantId' | 'source' | 'completion'> & { documentId: string | number; tenantId: string | number; source: ContainerCustomsFile; completion: ContainerCustomsFile | null }>
+}
+
+const basePath = '/platform/v1/customs/loading-plans'
+function operationId(prefix: string) { return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2)}` }
+function file(value: ContainerCustomsFile | null): ContainerCustomsFile | null {
+  return value ? { ...value, fileId: String(value.fileId), sizeBytes: Number(value.sizeBytes), version: Number(value.version) } : null
+}
+function normalize(value: RawContainerCustomsView): ContainerCustomsView {
+  return {
+    ...value,
+    aggregateId: String(value.aggregateId), loadingPlanId: String(value.loadingPlanId), containerBookingId: String(value.containerBookingId), version: Number(value.version),
+    inbounds: value.inbounds.map((item) => ({ ...item, inboundId: String(item.inboundId), orderId: String(item.orderId), tenantId: String(item.tenantId) })),
+    documents: value.documents.map((item) => ({ ...item, documentId: String(item.documentId), tenantId: String(item.tenantId), source: file(item.source)!, completion: file(item.completion) })),
+  }
+}
+
+export async function getContainerCustoms(loadingPlanId: string) {
+  const response = await http.get<ApiEnvelope<RawContainerCustomsView | null>, ApiEnvelope<RawContainerCustomsView | null>>(`${basePath}/${encodeURIComponent(loadingPlanId)}`)
+  const value = unwrapApiResponse(response)
+  return value ? normalize(value) : null
+}
+
+export function downloadContainerCustomsDocument(documentId: string) {
+  return http.get<Blob, Blob>(`${basePath}/documents/${encodeURIComponent(documentId)}/download`, { responseType: 'blob' })
+}
+
+export function downloadContainerCustomsCompletion(documentId: string) {
+  return http.get<Blob, Blob>(`${basePath}/documents/${encodeURIComponent(documentId)}/completion/download`, { responseType: 'blob' })
+}
+
+async function action(loadingPlanId: string, name: 'start' | 'complete-all-buy', expectedVersion: number, remark?: string) {
+  const response = await http.post<ApiEnvelope<RawContainerCustomsView>, ApiEnvelope<RawContainerCustomsView>>(
+    `${basePath}/${encodeURIComponent(loadingPlanId)}/${name}`,
+    { expectedVersion, confirm: true, remark: remark?.trim() || null },
+    { headers: { 'Idempotency-Key': operationId(`container-customs-${name}`) } },
+  )
+  return normalize(unwrapApiResponse(response))
+}
+
+export function startContainerCustoms(loadingPlanId: string, expectedVersion: number) {
+  return action(loadingPlanId, 'start', expectedVersion)
+}
+
+export function completeAllBuyContainerCustoms(loadingPlanId: string, expectedVersion: number) {
+  return action(loadingPlanId, 'complete-all-buy', expectedVersion)
+}
+
+export async function uploadContainerCustomsCompletion(documentId: string, fileValue: File, expectedVersion: number, finalConfirmation: boolean) {
+  const body = new FormData()
+  body.append('file', fileValue)
+  const response = await http.post<ApiEnvelope<ContainerCustomsDocument>, ApiEnvelope<ContainerCustomsDocument>>(
+    `${basePath}/documents/${encodeURIComponent(documentId)}/completion/upload`,
+    body,
+    { params: { expectedVersion, finalConfirmation }, headers: { 'Content-Type': 'multipart/form-data', 'Idempotency-Key': operationId('container-customs-completion') } },
+  )
+  const result = unwrapApiResponse(response)
+  return { ...result, documentId: String(result.documentId), tenantId: String(result.tenantId), source: file(result.source)!, completion: file(result.completion) }
+}
diff --git a/src/modules/container-loading/api/platformContainerLoading.test.ts b/src/modules/container-loading/api/platformContainerLoading.test.ts
new file mode 100644
index 00000000..fcba101b
--- /dev/null
+++ b/src/modules/container-loading/api/platformContainerLoading.test.ts
@@ -0,0 +1,306 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { http } from '@/shared/api/http'
+import {
+  adjustSmartLoadingItem, assignPendingReviewSmartLoadingOrder, assignSmartLoadingGroup, assignSmartLoadingItem, assignSmartLoadingPallet, getContainer,
+  listContainers, listSmartLoadingCandidates, listSmartLoadingWorkbenchContainers, removeAllUnpickedSmartLoadingItems, removeSmartLoadingGroup, removeSmartLoadingItem, removeSmartLoadingPallet,
+  recommendSmartLoading,
+  getContainerClearance, downloadContainerClearance, uploadContainerClearance, completeContainerClearance,
+  getContainerOverview, updateContainerPickupCode, markContainerException, cancelContainerException, uploadContainerDocument, downloadContainerDocument, downloadContainerPdaPhoto,
+  getCustomerContainerTransitSummary,
+  createContainerSimulation, linkContainerOceanBooking, unlinkContainerOceanBooking,
+  updateContainer,
+} from './platformContainerLoading'
+
+vi.mock('@/shared/api/http', () => ({
+  http: { get: vi.fn(), post: vi.fn(), put: vi.fn(), patch: vi.fn(), delete: vi.fn() },
+  unwrapApiResponse: <T>(response: { data: T }) => response.data,
+}))
+
+const container = { id: 9007199254740993, planId: 9007199254740994, planNo: 'LP-001', warehouseId: 9007199254740995, shippingCompanyId: 9007199254740996, terminalTruckingCompanyId: '9007199254740998', terminalTruckingCompany: '测试拖车供应商', sourceType: 'SIMULATION', recordStatus: 'ACTIVE', mergedIntoContainerBookingId: null, channelGroupCode: 'EXX', channelCode: 'NY_EXX', channelName: '纽约EXX海铁', exceptionActive: true, destinationClearanceDocumentStatus: 'COMPLETED', customsDeclarationDocumentStatus: 'UPLOADED', deliveryOrderDocumentStatus: 'UPLOADED', pickupCode: '00123456', pickupCodeUpdatedBy: 9007199254740999, unloadingCompletedAt: '2026-08-20T10:00:00', unloadingPhotoUploadedAt: '2026-08-20T10:15:00', estimatedEmptyReportedAt: '2026-08-21T09:00:00', actualEmptyReportedAt: null, emptyReportSourceVersion: '9007199254740997', version: '2', capacityCbm: '68', maxWeightKg: '19500' }
+const plan = {
+  id: 9007199254740993, bookingId: 9007199254740994, version: '3', status: 'LOADING',
+  canAssign: true, canEdit: true, blockedReason: null, finalCompletionStatus: 'NOT_STARTED',
+  pdaTaskId: 9007199254740996, pdaTaskStatus: 'LOADING', pdaTaskVersion: '4',
+  items: [{ id: 9007199254740995, loadingPlanId: 9007199254740993, accountId: 1, inboundId: 2, inboundDetailId: 3, orderId: 4, destinationWarehouseId: 5, packageCount: '6', version: '1', pickedPackageCount: '2', minPackageCount: '2', canAdjust: true, canRemove: false }],
+}
+
+describe('platform container loading API', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it('uses the customer transit summary and preserves fractional TEU', async () => {
+    vi.mocked(http.get).mockResolvedValueOnce({ code: '200', data: { customerId: '9007199254740993', containerCount: 2, totalTeu: '2.25', unknownContainerCount: 0, asOf: '2026-08-13T12:00:00', definition: '已开船未到仓' } })
+
+    const result = await getCustomerContainerTransitSummary('9007199254740993')
+
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/customers/9007199254740993/container-transit-summary')
+    expect(result).toMatchObject({ customerId: '9007199254740993', containerCount: 2, totalTeu: '2.25', unknownContainerCount: 0 })
+  })
+
+  it('normalizes paged container ids and numeric metadata', async () => {
+    vi.mocked(http.get).mockResolvedValueOnce({ code: '200', data: { records: [{ container, workbenchStage: 'PRE_LOADING', statusSummary: { loadingStatus: 'WAIT_LOADING' }, allowedActions: ['EDIT_CONTAINER'], actualFacts: {}, terminalDrayage: null }], page: '1', size: '20', total: '1', pages: '1' } })
+    const result = await listContainers({ page: 1, size: 20 })
+    expect(result.records[0]).toMatchObject({ id: String(container.id), planId: String(container.planId), planNo: 'LP-001', warehouseId: String(container.warehouseId), terminalTruckingCompanyId: String(container.terminalTruckingCompanyId), terminalTruckingCompany: '测试拖车供应商', channelCode: 'NY_EXX', channelName: '纽约EXX海铁', exceptionActive: true, destinationClearanceDocumentStatus: 'COMPLETED', customsDeclarationDocumentStatus: 'UPLOADED', deliveryOrderDocumentStatus: 'UPLOADED', pickupCode: '00123456', pickupCodeUpdatedBy: String(container.pickupCodeUpdatedBy), unloadingCompletedAt: '2026-08-20T10:00:00', unloadingPhotoUploadedAt: '2026-08-20T10:15:00', estimatedEmptyReportedAt: '2026-08-21T09:00:00', actualEmptyReportedAt: null, emptyReportSourceVersion: '9007199254740997', version: 2, capacityCbm: 68 })
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/containers/domestic', { params: { page: 1, size: 20, scope: 'ACTIVE' } })
+  })
+
+  it('uses the full-edit request shape without retaining the retired container transport endpoint', async () => {
+    vi.mocked(http.put).mockResolvedValue({ code: '200', data: container })
+    const data = { warehouseId: '8', warehouseName: '义乌仓', containerType: '40HQ', containerNo: null, billOfLadingNo: null, vesselName: null, voyageNo: null, shippingCompanyId: null, shippingCompanyName: null, departurePortCode: null, departurePortName: null, destinationPortCode: null, destinationPortName: null, destinationWarehouseCode: null, destinationWarehouseName: null, capacityCbm: 68, maxWeightKg: 19500, terminalTruckingCompanyId: null, terminalTruckingCompany: null, loadingAt: null, estimatedSailingAt: null, actualSailingAt: null, estimatedPortArrivalAt: null, actualPortArrivalAt: null, estimatedWarehouseArrivalAt: null, actualWarehouseArrivalAt: null }
+    await updateContainer('7', 2, data)
+    expect(http.put).toHaveBeenCalledWith('/platform/v1/containers/7', { version: 2, data })
+    expect(readFileSync(resolve(process.cwd(), 'src/modules/container-loading/api/platformContainerLoading.ts'), 'utf8')).not.toContain('/transport')
+  })
+
+  it.each(['DOMESTIC', 'OVERSEAS'] as const)('reads the %s detail envelope and exact long identifiers in one request', async (workbench) => {
+    vi.mocked(http.get).mockResolvedValueOnce({ code: '200', data: {
+      container: { ...container, id: '9007199254740993', planId: '9007199254740995' },
+      workbenchStage: 'PRE_LOADING', allowedActions: ['EDIT_CONTAINER'], statusSummary: {}, actualFacts: null, terminalDrayage: null,
+    } })
+    expect(await getContainer('9007199254740993', workbench)).toMatchObject({ id: '9007199254740993', planId: '9007199254740995', allowedActions: ['EDIT_CONTAINER'] })
+    expect(http.get).toHaveBeenCalledExactlyOnceWith(`/platform/v1/containers/${workbench.toLowerCase()}/9007199254740993`)
+  })
+
+  it('keeps empty overseas history pages and query filters without fetching individual details', async () => {
+    vi.mocked(http.get).mockResolvedValueOnce({ code: '200', data: { records: [], page: 2, size: 20, total: 0, pages: 0 } })
+    const query = { page: 2, size: 20, warehouseId: '9007199254740993', cabinetNo: 'CB-TEST', scope: 'HISTORY' as const }
+    expect(await listContainers(query, 'OVERSEAS')).toEqual({ records: [], page: 2, size: 20, total: 0, pages: 0 })
+    expect(http.get).toHaveBeenCalledExactlyOnceWith('/platform/v1/containers/overseas', { params: query })
+  })
+
+  it('propagates a failed workbench request without retrying retired routes', async () => {
+    const failure = new Error('workbench unavailable')
+    vi.mocked(http.get).mockRejectedValueOnce(failure)
+    await expect(listContainers({ page: 1, size: 20 })).rejects.toBe(failure)
+    expect(http.get).toHaveBeenCalledTimes(1)
+  })
+
+  it('rejects a retired flat response instead of rendering incorrect container rows', async () => {
+    vi.mocked(http.get).mockResolvedValueOnce({ code: '200', data: { records: [container], page: 1, size: 20, total: 1, pages: 1 } })
+    await expect(listContainers({ page: 1, size: 20 })).rejects.toThrow()
+    expect(http.get).toHaveBeenCalledTimes(1)
+  })
+
+  it('uses the frozen simulation create and ocean booking link contracts', async () => {
+    vi.mocked(http.post).mockResolvedValue({ code: '200', data: { ...container, oceanBookingId: 101, oceanBookingRequirementId: 202 } })
+    vi.mocked(http.delete).mockResolvedValue({ code: '200', data: { ...container, oceanBookingId: null, oceanBookingRequirementId: null } })
+    await createContainerSimulation({ channelGroupCode: 'EXX', warehouseId: '8', containerType: '40HQ', capacityCbm: 68, maxWeightKg: 19500 })
+    await linkContainerOceanBooking('7', { oceanBookingId: '101', requirementId: '202', containerNo: 'MSCU1234567', expectedVersion: 3 })
+    await unlinkContainerOceanBooking('7', 4, '空柜改配')
+    expect(http.post).toHaveBeenNthCalledWith(1, '/platform/v1/containers', { channelGroupCode: 'EXX', warehouseId: '8', containerType: '40HQ', capacityCbm: 68, maxWeightKg: 19500 })
+    expect(http.post).toHaveBeenNthCalledWith(2, '/platform/v1/containers/7/ocean-booking-link', { oceanBookingId: '101', requirementId: '202', containerNo: 'MSCU1234567', expectedVersion: 3 })
+    expect(http.delete).toHaveBeenCalledWith('/platform/v1/containers/7/ocean-booking-link', { data: { expectedVersion: 4, reason: '空柜改配' } })
+  })
+
+  it('normalizes every long id in candidates and plans', async () => {
+    vi.mocked(http.get)
+      .mockResolvedValueOnce({ code: '200', data: { container, workbenchStage: 'PRE_LOADING', statusSummary: {}, allowedActions: [], actualFacts: {}, terminalDrayage: null } })
+      .mockResolvedValueOnce({ code: '200', data: { records: [{ accountId: 1, inboundId: 2, orderId: 4, orderNo: 'ORD-1', inboundCode: 'IN-1', orderStatusSnapshot: 'WAIT_SPLIT', expectedArrivalAt: '2026-09-10T09:30:00', warehouseId: 5, destinationWarehouseId: 6, channelCode: 'NY_EXX', channelName: '纽约EXX海铁', customerName: '示例企业', goodsSummary: '服装、鞋类', availablePackageCount: '7', unitGrossWeightKg: '12.5', unitNetWeightKg: '11.8', averageUnitVolumeCbm: '0.187', availableVolumeCbm: '1.309', estimatedVolumeCbm: '2.5', coLoadGroupId: 9007199254740999n, groupNo: 'CLG-9007199254740999', memberCount: '3', groupTotalBoxes: '21', locked: false, blockReason: null, groupMembers: [] }], page: '1', size: '20', total: '1', pages: '1' } })
+    expect((await getContainer('9')).id).toBe(String(container.id))
+    expect(await listSmartLoadingCandidates({ channelGroupCodes: ['EXX', 'HEDE'], warehouseId: '5', orderStatuses: ['PENDING_REVIEW', 'WAIT_MEASURE'], page: 1, size: 20 })).toMatchObject({ records: [{ accountId: '1', customerId: '1', inboundId: '2', inboundCode: 'IN-1', orderStatusSnapshot: 'WAIT_SPLIT', expectedArrivalAt: '2026-09-10T09:30:00', destinationWarehouseId: '6', channelCode: 'NY_EXX', channelName: '纽约EXX海铁', goodsSummary: '服装、鞋类', availablePackageCount: 7, unitGrossWeightKg: 12.5, unitNetWeightKg: 11.8, averageUnitVolumeCbm: 0.187, availableVolumeCbm: 1.309, estimatedVolumeCbm: 2.5, coLoadGroupId: '9007199254740999', groupNo: 'CLG-9007199254740999', memberCount: 3, groupTotalBoxes: 21, locked: false, blockReason: null }], total: 1 })
+    const candidateParams = vi.mocked(http.get).mock.calls.at(-1)?.[1]?.params as URLSearchParams
+    expect(candidateParams.getAll('orderStatuses')).toEqual(['PENDING_REVIEW', 'WAIT_MEASURE'])
+    expect(candidateParams.has('orderStatus')).toBe(false)
+    const params = vi.mocked(http.get).mock.calls.at(-1)?.[1]?.params as URLSearchParams
+    expect(params.getAll('channelGroupCodes')).toEqual(['EXX', 'HEDE'])
+    expect(params.get('warehouseId')).toBe('5')
+    expect(params.has('bookingId')).toBe(false)
+  })
+
+  it('sends plan and item versions plus operation identifiers', async () => {
+    vi.mocked(http.post).mockResolvedValue({ code: '200', data: plan })
+    vi.mocked(http.patch).mockResolvedValue({ code: '200', data: plan })
+    vi.mocked(http.delete).mockResolvedValue({ code: '200', data: plan })
+    await assignSmartLoadingItem('10', { inboundId: '2', packageCount: 4, expectedVersion: 5 })
+    await adjustSmartLoadingItem('10', '11', 6, 7, 8)
+    await removeSmartLoadingItem('10', '11', 9, 10)
+    expect(vi.mocked(http.post).mock.calls[0]?.[0]).toBe('/platform/v1/first-leg/smart-loading/plans/10/inbound-assignments')
+    expect(vi.mocked(http.post).mock.calls[0]?.[1]).toMatchObject({ expectedVersion: 5, operationId: expect.stringContaining('assign-inbound-') })
+    expect(vi.mocked(http.patch).mock.calls[0]?.[1]).toMatchObject({ expectedPlanVersion: 7, expectedItemVersion: 8, operationId: expect.stringContaining('adjust-') })
+    expect(vi.mocked(http.delete).mock.calls[0]?.[1]).toMatchObject({ data: { expectedPlanVersion: 9, expectedItemVersion: 10, operationId: expect.stringContaining('remove-') } })
+  })
+
+  it('assigns a sealed pallet through the whole-pallet command', async () => {
+    vi.mocked(http.post).mockResolvedValue({ code: '200', data: plan })
+
+    await assignSmartLoadingPallet('10', { palletId: '9007199254740998', expectedVersion: 5 })
+
+    expect(http.post).toHaveBeenCalledWith(
+      '/platform/v1/first-leg/smart-loading/plans/10/pallet-assignments',
+      { palletId: '9007199254740998', expectedVersion: 5, operationId: expect.stringContaining('assign-pallet-') },
+    )
+  })
+
+  it('limits smart recommendation to the current customer and inbound filters', async () => {
+    vi.mocked(http.post).mockResolvedValue({ code: '200', data: plan })
+
+    await recommendSmartLoading('10', 5, {
+      customerId: '9007199254740998',
+      inboundCode: ' EXXHWK2609140162 ',
+    })
+
+    expect(http.post).toHaveBeenCalledWith(
+      '/platform/v1/first-leg/smart-loading/plans/10/recommend',
+      expect.objectContaining({
+        expectedVersion: 5,
+        customerId: '9007199254740998',
+        inboundCode: 'EXXHWK2609140162',
+        operationId: expect.stringContaining('recommend-'),
+      }),
+    )
+  })
+
+  it('removes a sealed pallet through the whole-pallet command', async () => {
+    vi.mocked(http.delete).mockResolvedValue({ code: '200', data: plan })
+
+    await removeSmartLoadingPallet('10', '9007199254740998', 6)
+
+    expect(http.delete).toHaveBeenCalledWith(
+      '/platform/v1/first-leg/smart-loading/plans/10/pallet-assignments/9007199254740998',
+      { data: { expectedPlanVersion: 6, operationId: expect.stringContaining('remove-pallet-') } },
+    )
+  })
+
+  it('uses the dedicated provisional assignment command for a pending-review order', async () => {
+    vi.mocked(http.post).mockResolvedValue({ code: '200', data: plan })
+
+    await assignPendingReviewSmartLoadingOrder('10', {
+      customerId: '21', orderId: '31', inboundCode: 'EXXHK2609020361',
+      packageCount: 100, expectedVersion: 5,
+    })
+
+    expect(http.post).toHaveBeenCalledWith(
+      '/platform/v1/first-leg/smart-loading/plans/10/pending-review-assignments',
+      expect.objectContaining({
+        customerId: '21', orderId: '31', inboundCode: 'EXXHK2609020361',
+        packageCount: 100, expectedVersion: 5,
+        operationId: expect.stringContaining('assign-pending-review-'),
+      }),
+    )
+  })
+
+  it('queries workbench containers with the same global filters and excludes the retired booking parameter', async () => {
+    vi.mocked(http.get).mockResolvedValueOnce({ code: '200', data: {
+      records: [{ bookingId: 9007199254740993n, bookingNo: 'BK-1', cabinetNo: 'CAB-1', containerNo: null, warehouseId: 8, warehouseName: '义乌仓', channelCode: 'MATSON_CLX_TRUCK', channelName: '美森正班海卡', containerType: '40HQ', planId: 9007199254740994n, planNo: 'LP-1', planStatus: 'EDITING', version: '2' }],
+      page: '1', size: '200', total: '1', pages: '1',
+    } })
+
+    const result = await listSmartLoadingWorkbenchContainers({ channelGroupCodes: ['MATSON_CLX', 'EXX'], customerId: '12', inboundCode: 'IN-1', createdStart: '2026-09-01', createdEnd: '2026-09-03', expectedArrivalStart: '2026-09-04', expectedArrivalEnd: '2026-09-06', orderStatuses: ['WAIT_SPLIT'], page: 1, size: 200 })
+
+    expect(result).toMatchObject({ records: [{ bookingId: '9007199254740993', warehouseId: '8', planId: '9007199254740994', version: 2 }], total: 1 })
+    const params = vi.mocked(http.get).mock.calls.at(-1)?.[1]?.params as URLSearchParams
+    expect(params.getAll('channelGroupCodes')).toEqual(['MATSON_CLX', 'EXX'])
+    expect(params.get('customerId')).toBe('12')
+    expect(params.get('inboundCode')).toBe('IN-1')
+    expect(params.get('createdStart')).toBe('2026-09-01')
+    expect(params.get('createdEnd')).toBe('2026-09-03')
+    expect(params.get('expectedArrivalStart')).toBe('2026-09-04')
+    expect(params.get('expectedArrivalEnd')).toBe('2026-09-06')
+    expect(params.has('orderStatus')).toBe(false)
+    expect(params.has('orderStatuses')).toBe(false)
+    expect(params.has('bookingId')).toBe(false)
+  })
+
+  it('uses only the atomic group assign and whole-group remove endpoints for co-load groups', async () => {
+    vi.mocked(http.post).mockResolvedValue({ code: '200', data: plan })
+    vi.mocked(http.delete).mockResolvedValue({ code: '200', data: plan })
+    await assignSmartLoadingGroup('10', '2093000000000000006', 5)
+    await removeSmartLoadingGroup('10', '2093000000000000001', 6)
+    expect(http.post).toHaveBeenCalledWith(
+      '/platform/v1/first-leg/smart-loading/plans/10/group-assignments',
+      { inboundId: '2093000000000000006', expectedVersion: 5, operationId: expect.stringContaining('assign-coload-group-') },
+    )
+    expect(http.delete).toHaveBeenCalledWith(
+      '/platform/v1/first-leg/smart-loading/plans/10/group-assignments/2093000000000000001',
+      { data: { expectedPlanVersion: 6, operationId: expect.stringContaining('remove-coload-group-') } },
+    )
+  })
+
+  it('uses one endpoint to remove all unpicked plan items', async () => {
+    vi.mocked(http.delete).mockResolvedValue({ code: '200', data: plan })
+
+    await removeAllUnpickedSmartLoadingItems('10', 6)
+
+    expect(http.delete).toHaveBeenCalledWith(
+      '/platform/v1/first-leg/smart-loading/plans/10/unpicked-items',
+      { data: { expectedPlanVersion: 6, operationId: expect.stringContaining('remove-unpicked-') } },
+    )
+  })
+
+  it('uses stable container id and versioned clearance document actions', async () => {
+    vi.spyOn(http, 'get').mockResolvedValue({ code: '200', data: { id: 4, documentType: 'CUSTOMS_CLEARANCE', fileId: 8, fileName: 'clearance.pdf', version: 2 } })
+    vi.spyOn(http, 'post').mockResolvedValue({ code: '200', data: { id: 4, documentType: 'CUSTOMS_CLEARANCE', fileId: 8, fileName: 'clearance.pdf', version: 3 } })
+    expect((await getContainerClearance('7'))?.fileId).toBe('8')
+    const file = new File(['clearance'], 'clearance.pdf', { type: 'application/pdf' })
+    await uploadContainerClearance('7', file, 2, '上传资料')
+    await completeContainerClearance('7', 3, '完成清关')
+    expect(vi.mocked(http.get)).toHaveBeenCalledWith('/platform/v1/containers/7/clearance')
+    expect(vi.mocked(http.post).mock.calls[0]?.[0]).toBe('/platform/v1/containers/7/clearance/document/upload')
+    const body = vi.mocked(http.post).mock.calls[0]?.[1] as FormData
+    expect(body.get('file')).toBe(file)
+    expect(body.get('expectedVersion')).toBe('2')
+    expect(body.get('operationReason')).toBe('上传资料')
+    expect(vi.mocked(http.post).mock.calls[0]?.[2]).toMatchObject({ headers: { 'Content-Type': 'multipart/form-data', 'Idempotency-Key': expect.any(String) } })
+    expect(vi.mocked(http.post).mock.calls[1]?.[0]).toBe('/platform/v1/containers/7/clearance/complete')
+  })
+
+  it('normalizes aggregate ids and uses the frozen overview and exception contracts', async () => {
+    vi.mocked(http.get).mockResolvedValueOnce({ code: '200', data: {
+      container: { id: 9007199254740993, warehouseId: 9007199254740994, version: '4' }, loadingPlanId: 9007199254740995,
+      pda: { taskId: 9007199254740996, loadingPlanId: 9007199254740995, containerBookingId: 9007199254740993, taskVersion: '2', itemCount: '4', completedItemCount: '3', unresolvedItemCount: '1', photoCounts: [{ evidenceType: 'EMPTY_CONTAINER', count: '2' }], photos: [{ evidenceId: 20, tenantId: 21, inboundId: 22, fileId: 23, downloadPath: '/api/platform/v1/containers/9007199254740993/pda/photos/23/download' }], exceptionReasons: [] },
+      documents: [{ id: 9007199254740997, documentType: 'DELIVERY_ORDER', fileId: 9007199254740998, uploadedBy: 9, version: '2' }],
+      exception: { active: false, markedBy: null }, exceptionHistory: [{ id: 10, operatorId: 11 }], timeline: [{ id: '2092438843630397001', eventId: '2092438843630397002', idempotencyKey: '2092438843630397003', operatorId: 12, eventType: 'PUSH_PRELOAD', detail: '推送预装清单' }],
+    } })
+    const result = await getContainerOverview('7')
+    expect(result).toMatchObject({ container: { id: expect.any(String), warehouseId: expect.any(String), version: 4 }, loadingPlanId: expect.any(String), pda: { taskId: expect.any(String), itemCount: 4, photoCounts: [{ count: 2 }] }, documents: [{ fileId: expect.any(String), version: 2 }], timeline: [{ id: '2092438843630397001', eventId: '2092438843630397002', idempotencyKey: '2092438843630397003', operatorId: '12' }] })
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/containers/7/overview')
+
+    vi.mocked(http.post).mockResolvedValueOnce({ code: '200', data: null })
+    vi.mocked(http.delete).mockResolvedValueOnce({ code: '200', data: null })
+    await markContainerException('7', 2, '查验')
+    await cancelContainerException('7', 3, '已解除')
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/containers/7/exception', { expectedVersion: 2, reason: '查验' }, { headers: { 'Idempotency-Key': expect.stringContaining('container-exception-mark-') } })
+    expect(http.delete).toHaveBeenCalledWith('/platform/v1/containers/7/exception', { data: { expectedVersion: 3, reason: '已解除' }, headers: { 'Idempotency-Key': expect.stringContaining('container-exception-cancel-') } })
+  })
+
+  it('uploads only DO or PU through the logistics endpoint and downloads through the protected proxy', async () => {
+    vi.mocked(http.post).mockResolvedValueOnce({ code: '200', data: { id: 1, documentType: 'DELIVERY_ORDER', fileId: 2, fileName: 'do.pdf', version: 1 } })
+    vi.mocked(http.get).mockResolvedValueOnce(new Blob(['do']))
+    const file = new File(['do'], 'do.pdf')
+    await uploadContainerDocument('7', 'DELIVERY_ORDER', file, 0, '上传DO')
+    await downloadContainerDocument('7', 'DELIVERY_ORDER', '2')
+    expect(vi.mocked(http.post).mock.calls[0]?.[0]).toBe('/platform/v1/containers/7/documents/DELIVERY_ORDER/upload')
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/containers/7/documents/DELIVERY_ORDER/2/download', { responseType: 'blob' })
+  })
+
+  it('saves the PU numeric code as a string with the container version', async () => {
+    vi.mocked(http.put).mockResolvedValueOnce({ code: '200', data: { container: { id: 7, warehouseId: 8, pickupCode: '00123456', pickupCodeUpdatedBy: 9, version: 3 }, documents: [], exception: {}, exceptionHistory: [], timeline: [] } })
+    const result = await updateContainerPickupCode('7', '00123456', 2)
+    expect(http.put).toHaveBeenCalledWith('/platform/v1/containers/7/pickup-code', { pickupCode: '00123456', expectedVersion: 2 })
+    expect(result.container).toMatchObject({ pickupCode: '00123456', pickupCodeUpdatedBy: '9', version: 3 })
+  })
+
+  it('normalizes the gateway /api prefix once and accepts only exact protected container photo paths', async () => {
+    vi.mocked(http.get).mockResolvedValue(new Blob(['photo']))
+    const longPath = '/api/platform/v1/containers/2092437461590446082/pda/photos/2092439032600797185/download'
+    await downloadContainerPdaPhoto(longPath)
+    await downloadContainerPdaPhoto('/platform/v1/containers/2092437461590446082/pda/photos/2092439032600797185/download')
+    expect(http.get).toHaveBeenNthCalledWith(1, '/platform/v1/containers/2092437461590446082/pda/photos/2092439032600797185/download', { responseType: 'blob' })
+    expect(http.get).toHaveBeenNthCalledWith(2, '/platform/v1/containers/2092437461590446082/pda/photos/2092439032600797185/download', { responseType: 'blob' })
+    expect(vi.mocked(http.get).mock.calls.every((call) => !String(call[0]).includes('/api/api/'))).toBe(true)
+    for (const path of [
+      '/api/platform/v1/files/loading-evidence/21/22/23', 'https://example.com/photo.jpg',
+      '//example.com/platform/v1/containers/7/pda/photos/23/download', '/platform/v1/containers/7/pda/photos/23/download?token=x',
+      '/platform/v1/containers/7/pda/photos/../23/download', '/api/api/platform/v1/containers/7/pda/photos/23/download',
+    ]) expect(() => downloadContainerPdaPhoto(path)).toThrow('invalid container photo path')
+  })
+
+  it('downloads destination clearance through its exact protected endpoint with string ids', async () => {
+    const blob = new Blob(['clearance'])
+    vi.mocked(http.get).mockResolvedValueOnce(blob)
+    const result = await downloadContainerClearance('2092438843630391297', '2092438843630393502')
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/containers/2092438843630391297/clearance/document/2092438843630393502/download', { responseType: 'blob' })
+    expect(result).toBe(blob)
+  })
+})
diff --git a/src/modules/container-loading/api/platformContainerLoading.ts b/src/modules/container-loading/api/platformContainerLoading.ts
new file mode 100644
index 00000000..1f8bef5d
--- /dev/null
+++ b/src/modules/container-loading/api/platformContainerLoading.ts
@@ -0,0 +1,441 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+
+export interface CustomerContainerTransitSummary {
+  customerId: string
+  containerCount: number
+  totalTeu: number | string
+  unknownContainerCount: number
+  asOf: string
+  definition: string
+}
+import type {
+  ContainerBookingResource,
+  ContainerPage,
+  ContainerQuery,
+  ContainerSaveRequest,
+  ContainerSimulationCreateRequest,
+  ContainerOceanBookingLinkRequest,
+  SmartLoadingCandidate,
+  SmartLoadingCandidatePage,
+  SmartLoadingCandidateQuery,
+  SmartLoadingWorkbenchContainerPage,
+  SmartLoadingItem,
+  SmartLoadingPlan,
+  BusinessDocument,
+  ContainerDocumentType,
+  ContainerOverview,
+  ContainerOverviewDocument,
+  ContainerWorkbenchKind,
+  ContainerWorkbenchRow,
+  ContainerWorkbenchItem,
+  ContainerWorkbenchPage,
+} from '../types'
+
+const containerPath = '/platform/v1/containers'
+const smartLoadingPath = '/platform/v1/first-leg/smart-loading'
+
+function id(value: unknown): string { return value == null ? '' : String(value) }
+function optionalId(value: unknown): string | null { return value == null ? null : String(value) }
+function numberValue(value: unknown, fallback = 0): number {
+  const parsed = Number(value)
+  return Number.isFinite(parsed) ? parsed : fallback
+}
+function operationId(prefix: string) { return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2)}` }
+function document(raw: BusinessDocument | null | undefined): BusinessDocument | null {
+  if (!raw) return null
+  return { ...raw, id: raw.id == null ? null : id(raw.id), fileId: id(raw.fileId), uploadedBy: raw.uploadedBy == null ? null : id(raw.uploadedBy), completedBy: raw.completedBy == null ? null : id(raw.completedBy), version: numberValue(raw.version) }
+}
+
+function overviewDocument(raw: ContainerOverviewDocument): ContainerOverviewDocument {
+  return { ...raw, id: id(raw.id), fileId: id(raw.fileId), uploadedBy: optionalId(raw.uploadedBy), version: numberValue(raw.version) }
+}
+
+function overview(raw: ContainerOverview): ContainerOverview {
+  return {
+    ...raw,
+    container: { ...raw.container, id: id(raw.container.id), warehouseId: id(raw.container.warehouseId), pickupCodeUpdatedBy: optionalId(raw.container.pickupCodeUpdatedBy), version: numberValue(raw.container.version) },
+    loadingPlanId: optionalId(raw.loadingPlanId),
+    pda: raw.pda ? {
+      ...raw.pda, taskId: id(raw.pda.taskId), loadingPlanId: id(raw.pda.loadingPlanId),
+      containerBookingId: id(raw.pda.containerBookingId), taskVersion: numberValue(raw.pda.taskVersion),
+      itemCount: numberValue(raw.pda.itemCount), completedItemCount: numberValue(raw.pda.completedItemCount),
+      unresolvedItemCount: numberValue(raw.pda.unresolvedItemCount),
+      photoCounts: (raw.pda.photoCounts || []).map((item) => ({ ...item, count: numberValue(item.count) })),
+      photos: (raw.pda.photos || []).map((item) => ({ ...item, evidenceId: id(item.evidenceId), tenantId: id(item.tenantId), inboundId: id(item.inboundId), fileId: id(item.fileId) })),
+      exceptionReasons: raw.pda.exceptionReasons || [],
+    } : null,
+    documents: (raw.documents || []).map(overviewDocument),
+    exception: { ...raw.exception, markedBy: optionalId(raw.exception?.markedBy) },
+    exceptionHistory: (raw.exceptionHistory || []).map((entry) => ({ ...entry, id: id(entry.id), operatorId: optionalId(entry.operatorId) })),
+    timeline: (raw.timeline || []).map((entry) => ({
+      ...entry,
+      id: optionalId(entry.id),
+      eventId: optionalId(entry.eventId),
+      idempotencyKey: optionalId(entry.idempotencyKey),
+      operatorId: optionalId(entry.operatorId),
+    })),
+  }
+}
+
+function container(raw: ContainerBookingResource): ContainerBookingResource {
+  return {
+    ...raw,
+    id: id(raw.id),
+    planId: optionalId(raw.planId),
+    planNo: raw.planNo || null,
+    mergedIntoContainerBookingId: optionalId(raw.mergedIntoContainerBookingId),
+    warehouseId: id(raw.warehouseId),
+    oceanBookingId: optionalId(raw.oceanBookingId),
+    oceanBookingRequirementId: optionalId(raw.oceanBookingRequirementId),
+    customerId: optionalId(raw.customerId),
+    shippingCompanyId: optionalId(raw.shippingCompanyId),
+    terminalTruckingCompanyId: optionalId(raw.terminalTruckingCompanyId),
+    emptyReportSourceVersion: optionalId(raw.emptyReportSourceVersion),
+    pickupCodeUpdatedBy: optionalId(raw.pickupCodeUpdatedBy),
+    version: numberValue(raw.version),
+    capacityCbm: raw.capacityCbm == null ? null : numberValue(raw.capacityCbm),
+    maxWeightKg: raw.maxWeightKg == null ? null : numberValue(raw.maxWeightKg),
+    exceptionActive: Boolean(raw.exceptionActive),
+    clearanceDocument: document(raw.clearanceDocument),
+  }
+}
+
+function normalizeWorkbenchRow(raw: ContainerWorkbenchItem): ContainerWorkbenchRow {
+  const drayage = raw.terminalDrayage
+  return {
+    ...container(raw.container),
+    workbenchStage: raw.workbenchStage || null,
+    statusSummary: raw.statusSummary || {},
+    allowedActions: raw.allowedActions || [],
+    actualFacts: raw.actualFacts || {},
+    terminalDrayage: drayage ? {
+      ...drayage,
+      containerBookingId: id(drayage.containerBookingId),
+      version: numberValue(drayage.version),
+      fleetSupplierId: optionalId(drayage.fleetSupplierId),
+      emptyReturnWarning: {
+        ...drayage.emptyReturnWarning,
+        overdueHours: numberValue(drayage.emptyReturnWarning?.overdueHours),
+        overdueDays: numberValue(drayage.emptyReturnWarning?.overdueDays),
+      },
+      allowedActions: drayage.allowedActions || [],
+    } : null,
+  }
+}
+
+function item(raw: SmartLoadingItem): SmartLoadingItem {
+  return {
+    ...raw,
+    id: id(raw.id), loadingPlanId: id(raw.loadingPlanId), accountId: id(raw.accountId),
+    inboundId: id(raw.inboundId), inboundDetailId: id(raw.inboundDetailId), orderId: id(raw.orderId),
+    destinationWarehouseId: optionalId(raw.destinationWarehouseId), version: numberValue(raw.version),
+    palletId: optionalId(raw.palletId), palletNo: raw.palletNo || null,
+    unitType: raw.unitType, indivisible: Boolean(raw.indivisible),
+    packageCount: numberValue(raw.packageCount),
+    pickedPackageCount: numberValue(raw.pickedPackageCount),
+    minPackageCount: numberValue(raw.minPackageCount, 1),
+    totalPackageCount: numberValue(raw.totalPackageCount, raw.packageCount),
+    remainingPackageCount: numberValue(raw.remainingPackageCount),
+    canAdjust: Boolean(raw.canAdjust), canRemove: Boolean(raw.canRemove),
+    productQuantity: raw.productQuantity == null ? null : numberValue(raw.productQuantity),
+    grossWeightKg: raw.grossWeightKg == null ? null : numberValue(raw.grossWeightKg),
+    volumeCbm: raw.volumeCbm == null ? null : numberValue(raw.volumeCbm),
+  }
+}
+
+function plan(raw: SmartLoadingPlan): SmartLoadingPlan {
+  return {
+    ...raw,
+    id: id(raw.id), bookingId: id(raw.bookingId), version: numberValue(raw.version),
+    canAssign: Boolean(raw.canAssign), canEdit: Boolean(raw.canEdit),
+    blockedReason: raw.blockedReason || null,
+    pdaTaskId: optionalId(raw.pdaTaskId),
+    pdaTaskVersion: raw.pdaTaskVersion == null ? null : numberValue(raw.pdaTaskVersion),
+    coLoadGroups: (raw.coLoadGroups || []).map((group) => ({
+      ...group,
+      groupId: id(group.groupId), lockedPlanId: optionalId(group.lockedPlanId),
+      memberOrderCount: numberValue(group.memberOrderCount),
+      inboundFragmentCount: numberValue(group.inboundFragmentCount),
+      fullPackageCount: numberValue(group.fullPackageCount),
+      memberInboundIds: (group.memberInboundIds || []).map(id),
+    })),
+    palletMembers: (raw.palletMembers || []).map((pallet) => ({
+      palletId: id(pallet.palletId),
+      members: (pallet.members || []).map((member) => ({
+        ...member,
+        accountId: id(member.accountId), inboundId: id(member.inboundId), orderId: id(member.orderId),
+        availablePackageCount: numberValue(member.availablePackageCount),
+      })),
+    })),
+    items: (raw.items || []).map(item),
+  }
+}
+
+export async function listContainers(query: ContainerQuery, workbench: ContainerWorkbenchKind = 'DOMESTIC'): Promise<ContainerPage> {
+  const params = { ...query, scope: query.scope || 'ACTIVE' }
+  const response = await http.get<ApiEnvelope<ContainerWorkbenchPage>, ApiEnvelope<ContainerWorkbenchPage>>(`${containerPath}/${workbench.toLowerCase()}`, { params })
+  const result = unwrapApiResponse(response)
+  return { ...result, records: result.records.map(normalizeWorkbenchRow), page: numberValue(result.page, query.page), size: numberValue(result.size, query.size), total: numberValue(result.total), pages: numberValue(result.pages) }
+}
+
+export async function getCustomerContainerTransitSummary(customerId: string): Promise<CustomerContainerTransitSummary> {
+  const response = await http.get<ApiEnvelope<Record<string, unknown>>, ApiEnvelope<Record<string, unknown>>>(
+    `/platform/v1/customers/${encodeURIComponent(customerId)}/container-transit-summary`,
+  )
+  const result = unwrapApiResponse(response)
+  return {
+    customerId: id(result.customerId), containerCount: numberValue(result.containerCount),
+    totalTeu: String(result.totalTeu ?? '0'), unknownContainerCount: numberValue(result.unknownContainerCount),
+    asOf: id(result.asOf), definition: id(result.definition),
+  }
+}
+
+export async function getContainer(containerId: string, workbench: ContainerWorkbenchKind = 'DOMESTIC'): Promise<ContainerWorkbenchRow> {
+  const response = await http.get<ApiEnvelope<ContainerWorkbenchItem>, ApiEnvelope<ContainerWorkbenchItem>>(`${containerPath}/${workbench.toLowerCase()}/${encodeURIComponent(containerId)}`)
+  return normalizeWorkbenchRow(unwrapApiResponse(response))
+}
+
+export async function getContainerOverview(containerId: string) {
+  const response = await http.get<ApiEnvelope<ContainerOverview>, ApiEnvelope<ContainerOverview>>(`${containerPath}/${encodeURIComponent(containerId)}/overview`)
+  return overview(unwrapApiResponse(response))
+}
+
+export async function updateContainerPickupCode(containerId: string, pickupCode: string, expectedVersion: number) {
+  const response = await http.put<ApiEnvelope<ContainerOverview>, ApiEnvelope<ContainerOverview>>(
+    `${containerPath}/${encodeURIComponent(containerId)}/pickup-code`,
+    { pickupCode, expectedVersion },
+  )
+  return overview(unwrapApiResponse(response))
+}
+
+export async function markContainerException(containerId: string, expectedVersion: number, reason: string) {
+  const response = await http.post<ApiEnvelope<null>, ApiEnvelope<null>>(`${containerPath}/${encodeURIComponent(containerId)}/exception`, { expectedVersion, reason }, { headers: { 'Idempotency-Key': operationId('container-exception-mark') } })
+  unwrapApiResponse(response)
+}
+
+export async function cancelContainerException(containerId: string, expectedVersion: number, reason: string) {
+  const response = await http.delete<ApiEnvelope<null>, ApiEnvelope<null>>(`${containerPath}/${encodeURIComponent(containerId)}/exception`, { data: { expectedVersion, reason }, headers: { 'Idempotency-Key': operationId('container-exception-cancel') } })
+  unwrapApiResponse(response)
+}
+
+export async function uploadContainerDocument(containerId: string, documentType: Extract<ContainerDocumentType, 'DELIVERY_ORDER'>, file: File, expectedVersion: number, operationReason?: string | null) {
+  const body = new FormData()
+  body.append('file', file)
+  body.append('expectedVersion', String(expectedVersion))
+  if (operationReason) body.append('operationReason', operationReason)
+  const response = await http.post<ApiEnvelope<BusinessDocument>, ApiEnvelope<BusinessDocument>>(`${containerPath}/${encodeURIComponent(containerId)}/documents/${documentType}/upload`, body, { headers: { 'Content-Type': 'multipart/form-data', 'Idempotency-Key': operationId(`container-${documentType.toLowerCase()}-upload`) } })
+  return document(unwrapApiResponse(response))
+}
+
+export function downloadContainerDocument(containerId: string, documentType: Extract<ContainerDocumentType, 'DELIVERY_ORDER'>, fileId: string) {
+  return http.get<Blob, Blob>(`${containerPath}/${encodeURIComponent(containerId)}/documents/${documentType}/${encodeURIComponent(fileId)}/download`, { responseType: 'blob' })
+}
+
+function normalizeContainerPhotoDownloadPath(downloadPath: string) {
+  if (typeof downloadPath !== 'string' || !downloadPath.startsWith('/')) throw new Error('invalid container photo path')
+  const normalized = downloadPath.startsWith('/api/') ? downloadPath.slice(4) : downloadPath
+  if (!/^\/platform\/v1\/containers\/[1-9][0-9]*\/pda\/photos\/[1-9][0-9]*\/download$/.test(normalized)) throw new Error('invalid container photo path')
+  return normalized
+}
+
+export function downloadContainerPdaPhoto(downloadPath: string) {
+  return http.get<Blob, Blob>(normalizeContainerPhotoDownloadPath(downloadPath), { responseType: 'blob' })
+}
+
+export async function createContainerSimulation(payload: ContainerSimulationCreateRequest) {
+  const response = await http.post<ApiEnvelope<ContainerBookingResource>, ApiEnvelope<ContainerBookingResource>>(containerPath, payload)
+  return container(unwrapApiResponse(response))
+}
+
+export async function linkContainerOceanBooking(containerId: string, payload: ContainerOceanBookingLinkRequest) {
+  const response = await http.post<ApiEnvelope<ContainerBookingResource>, ApiEnvelope<ContainerBookingResource>>(`${containerPath}/${encodeURIComponent(containerId)}/ocean-booking-link`, payload)
+  return container(unwrapApiResponse(response))
+}
+
+export async function unlinkContainerOceanBooking(containerId: string, expectedVersion: number, reason: string) {
+  const response = await http.delete<ApiEnvelope<ContainerBookingResource>, ApiEnvelope<ContainerBookingResource>>(`${containerPath}/${encodeURIComponent(containerId)}/ocean-booking-link`, { data: { expectedVersion, reason } })
+  return container(unwrapApiResponse(response))
+}
+
+export async function updateContainer(containerId: string, version: number, data: ContainerSaveRequest) {
+  const response = await http.put<ApiEnvelope<ContainerBookingResource>, ApiEnvelope<ContainerBookingResource>>(`${containerPath}/${encodeURIComponent(containerId)}`, { version, data })
+  return container(unwrapApiResponse(response))
+}
+
+export async function getContainerClearance(containerId: string) {
+  const response = await http.get<ApiEnvelope<BusinessDocument | null>, ApiEnvelope<BusinessDocument | null>>(`${containerPath}/${encodeURIComponent(containerId)}/clearance`)
+  return document(unwrapApiResponse(response))
+}
+
+export function downloadContainerClearance(containerId: string, fileId: string) {
+  return http.get<Blob, Blob>(`${containerPath}/${encodeURIComponent(containerId)}/clearance/document/${encodeURIComponent(fileId)}/download`, { responseType: 'blob' })
+}
+
+export async function uploadContainerClearance(containerId: string, file: File, expectedVersion: number, operationReason?: string | null) {
+  const body = new FormData()
+  body.append('file', file)
+  body.append('expectedVersion', String(expectedVersion))
+  if (operationReason) body.append('operationReason', operationReason)
+  const response = await http.post<ApiEnvelope<BusinessDocument>, ApiEnvelope<BusinessDocument>>(`${containerPath}/${encodeURIComponent(containerId)}/clearance/document/upload`, body, { headers: { 'Content-Type': 'multipart/form-data', 'Idempotency-Key': operationId('container-clearance-upload') } })
+  return document(unwrapApiResponse(response))
+}
+
+export async function completeContainerClearance(containerId: string, expectedVersion: number, operationReason?: string | null) {
+  const response = await http.post<ApiEnvelope<BusinessDocument>, ApiEnvelope<BusinessDocument>>(`${containerPath}/${encodeURIComponent(containerId)}/clearance/complete`, { expectedVersion, operationReason }, { headers: { 'Idempotency-Key': operationId('container-clearance-complete') } })
+  return document(unwrapApiResponse(response))
+}
+
+function smartLoadingQueryParams(query: SmartLoadingCandidateQuery, includeOrderStatuses = false) {
+  const params = new URLSearchParams()
+  for (const channelGroupCode of query.channelGroupCodes) params.append('channelGroupCodes', channelGroupCode)
+  if (includeOrderStatuses) {
+    for (const orderStatus of query.orderStatuses || []) params.append('orderStatuses', orderStatus)
+  }
+  const optionalParams: Array<[string, string | number | undefined]> = [
+    ['warehouseId', query.warehouseId], ['customerId', query.customerId], ['inboundCode', query.inboundCode],
+    ['createdStart', query.createdStart], ['createdEnd', query.createdEnd],
+    ['expectedArrivalStart', query.expectedArrivalStart], ['expectedArrivalEnd', query.expectedArrivalEnd],
+    ['page', query.page], ['size', query.size],
+  ]
+  for (const [key, value] of optionalParams) if (value !== undefined && value !== '') params.append(key, String(value))
+  return params
+}
+
+export async function listSmartLoadingCandidates(query: SmartLoadingCandidateQuery) {
+  const params = smartLoadingQueryParams(query, true)
+  const response = await http.get<ApiEnvelope<SmartLoadingCandidatePage>, ApiEnvelope<SmartLoadingCandidatePage>>(`${smartLoadingPath}/inbound-candidates`, { params })
+  const result = unwrapApiResponse(response)
+  return {
+    ...result,
+    page: numberValue(result.page, query.page), size: numberValue(result.size, query.size),
+    total: numberValue(result.total), pages: numberValue(result.pages),
+    records: result.records.map((raw) => {
+      const accountId = id(raw.accountId)
+      return {
+        ...raw, accountId, customerId: accountId, inboundId: optionalId(raw.inboundId),
+        orderId: id(raw.orderId), warehouseId: id(raw.warehouseId), destinationWarehouseId: optionalId(raw.destinationWarehouseId),
+        coLoadGroupId: optionalId(raw.coLoadGroupId), palletId: optionalId(raw.palletId), palletNo: raw.palletNo || null,
+        unitType: raw.unitType, indivisible: Boolean(raw.indivisible),
+        memberCount: raw.memberCount == null ? null : numberValue(raw.memberCount),
+        groupTotalBoxes: raw.groupTotalBoxes == null ? null : numberValue(raw.groupTotalBoxes),
+        locked: raw.locked == null ? null : Boolean(raw.locked),
+        availablePackageCount: numberValue(raw.availablePackageCount),
+        unitGrossWeightKg: raw.unitGrossWeightKg == null ? null : numberValue(raw.unitGrossWeightKg),
+        unitNetWeightKg: raw.unitNetWeightKg == null ? null : numberValue(raw.unitNetWeightKg),
+        averageUnitVolumeCbm: raw.averageUnitVolumeCbm == null ? null : numberValue(raw.averageUnitVolumeCbm),
+        availableVolumeCbm: raw.availableVolumeCbm == null ? null : numberValue(raw.availableVolumeCbm),
+        estimatedVolumeCbm: raw.estimatedVolumeCbm == null ? null : numberValue(raw.estimatedVolumeCbm),
+        groupMembers: raw.groupMembers.map((member) => ({
+          ...member, accountId: id(member.accountId), inboundId: id(member.inboundId), orderId: id(member.orderId),
+          availablePackageCount: numberValue(member.availablePackageCount),
+        })),
+      }
+    }),
+  }
+}
+
+export async function listSmartLoadingWorkbenchContainers(query: SmartLoadingCandidateQuery) {
+  const response = await http.get<ApiEnvelope<SmartLoadingWorkbenchContainerPage>, ApiEnvelope<SmartLoadingWorkbenchContainerPage>>(`${smartLoadingPath}/containers`, { params: smartLoadingQueryParams(query) })
+  const result = unwrapApiResponse(response)
+  return {
+    ...result,
+    page: numberValue(result.page, query.page), size: numberValue(result.size, query.size),
+    total: numberValue(result.total), pages: numberValue(result.pages),
+    records: result.records.map((raw) => ({
+      ...raw, bookingId: id(raw.bookingId), warehouseId: id(raw.warehouseId), planId: optionalId(raw.planId),
+      capacityCbm: raw.capacityCbm == null ? null : numberValue(raw.capacityCbm),
+      maxWeightKg: raw.maxWeightKg == null ? null : numberValue(raw.maxWeightKg),
+      version: numberValue(raw.version),
+    })),
+  }
+}
+
+export async function getSmartLoadingPlanByBooking(bookingId: string) {
+  const response = await http.get<ApiEnvelope<SmartLoadingPlan>, ApiEnvelope<SmartLoadingPlan>>(`${smartLoadingPath}/plans/by-booking/${encodeURIComponent(bookingId)}`)
+  return plan(unwrapApiResponse(response))
+}
+
+export async function getSmartLoadingPlan(planId: string) {
+  const response = await http.get<ApiEnvelope<SmartLoadingPlan>, ApiEnvelope<SmartLoadingPlan>>(`${smartLoadingPath}/plans/${encodeURIComponent(planId)}`)
+  return plan(unwrapApiResponse(response))
+}
+
+export async function assignSmartLoadingItem(planId: string, payload: { inboundId: string; packageCount: number; expectedVersion: number }) {
+  const response = await http.post<ApiEnvelope<SmartLoadingPlan>, ApiEnvelope<SmartLoadingPlan>>(`${smartLoadingPath}/plans/${encodeURIComponent(planId)}/inbound-assignments`, { ...payload, operationId: operationId('assign-inbound') })
+  return plan(unwrapApiResponse(response))
+}
+
+export async function assignSmartLoadingPallet(planId: string, payload: { palletId: string; expectedVersion: number }) {
+  const response = await http.post<ApiEnvelope<SmartLoadingPlan>, ApiEnvelope<SmartLoadingPlan>>(
+    `${smartLoadingPath}/plans/${encodeURIComponent(planId)}/pallet-assignments`,
+    { ...payload, operationId: operationId('assign-pallet') },
+  )
+  return plan(unwrapApiResponse(response))
+}
+
+export async function assignPendingReviewSmartLoadingOrder(planId: string, payload: { customerId: string; orderId: string; inboundCode: string; packageCount: number; expectedVersion: number }) {
+  const response = await http.post<ApiEnvelope<SmartLoadingPlan>, ApiEnvelope<SmartLoadingPlan>>(
+    `${smartLoadingPath}/plans/${encodeURIComponent(planId)}/pending-review-assignments`,
+    { ...payload, operationId: operationId('assign-pending-review') },
+  )
+  return plan(unwrapApiResponse(response))
+}
+
+export async function assignSmartLoadingGroup(planId: string, inboundId: string, expectedVersion: number) {
+  const response = await http.post<ApiEnvelope<SmartLoadingPlan>, ApiEnvelope<SmartLoadingPlan>>(
+    `${smartLoadingPath}/plans/${encodeURIComponent(planId)}/group-assignments`,
+    { inboundId, expectedVersion, operationId: operationId('assign-coload-group') },
+  )
+  return plan(unwrapApiResponse(response))
+}
+export async function recommendSmartLoading(
+  planId: string,
+  expectedVersion: number,
+  scope: { customerId?: string; inboundCode?: string } = {},
+) {
+  const response = await http.post<ApiEnvelope<SmartLoadingPlan>, ApiEnvelope<SmartLoadingPlan>>(
+    `${smartLoadingPath}/plans/${encodeURIComponent(planId)}/recommend`,
+    {
+      expectedVersion,
+      operationId: operationId('recommend'),
+      ...(scope.customerId ? { customerId: scope.customerId } : {}),
+      ...(scope.inboundCode?.trim() ? { inboundCode: scope.inboundCode.trim() } : {}),
+    },
+  )
+  return plan(unwrapApiResponse(response))
+}
+
+export async function adjustSmartLoadingItem(planId: string, itemId: string, packageCount: number, expectedPlanVersion: number, expectedItemVersion: number) {
+  const response = await http.patch<ApiEnvelope<SmartLoadingPlan>, ApiEnvelope<SmartLoadingPlan>>(`${smartLoadingPath}/plans/${encodeURIComponent(planId)}/items/${encodeURIComponent(itemId)}`, { packageCount, expectedPlanVersion, expectedItemVersion, operationId: operationId('adjust') })
+  return plan(unwrapApiResponse(response))
+}
+
+export async function removeSmartLoadingItem(planId: string, itemId: string, expectedPlanVersion: number, expectedItemVersion: number) {
+  const response = await http.delete<ApiEnvelope<SmartLoadingPlan>, ApiEnvelope<SmartLoadingPlan>>(`${smartLoadingPath}/plans/${encodeURIComponent(planId)}/items/${encodeURIComponent(itemId)}`, { data: { expectedPlanVersion, expectedItemVersion, operationId: operationId('remove') } })
+  return plan(unwrapApiResponse(response))
+}
+
+export async function removeSmartLoadingPallet(planId: string, palletId: string, expectedPlanVersion: number) {
+  const response = await http.delete<ApiEnvelope<SmartLoadingPlan>, ApiEnvelope<SmartLoadingPlan>>(
+    `${smartLoadingPath}/plans/${encodeURIComponent(planId)}/pallet-assignments/${encodeURIComponent(palletId)}`,
+    { data: { expectedPlanVersion, operationId: operationId('remove-pallet') } },
+  )
+  return plan(unwrapApiResponse(response))
+}
+
+export async function removeSmartLoadingGroup(planId: string, groupId: string, expectedPlanVersion: number) {
+  const response = await http.delete<ApiEnvelope<SmartLoadingPlan>, ApiEnvelope<SmartLoadingPlan>>(
+    `${smartLoadingPath}/plans/${encodeURIComponent(planId)}/group-assignments/${encodeURIComponent(groupId)}`,
+    { data: { expectedPlanVersion, operationId: operationId('remove-coload-group') } },
+  )
+  return plan(unwrapApiResponse(response))
+}
+
+export async function removeAllUnpickedSmartLoadingItems(planId: string, expectedPlanVersion: number) {
+  const response = await http.delete<ApiEnvelope<SmartLoadingPlan>, ApiEnvelope<SmartLoadingPlan>>(
+    `${smartLoadingPath}/plans/${encodeURIComponent(planId)}/unpicked-items`,
+    { data: { expectedPlanVersion, operationId: operationId('remove-unpicked') } },
+  )
+  return plan(unwrapApiResponse(response))
+}
+
diff --git a/src/modules/container-loading/api/terminalDrayages.test.ts b/src/modules/container-loading/api/terminalDrayages.test.ts
new file mode 100644
index 00000000..041c9e50
--- /dev/null
+++ b/src/modules/container-loading/api/terminalDrayages.test.ts
@@ -0,0 +1,68 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import {
+  sendTerminalDrayageEmail,
+  getTerminalDrayageEmails,
+  retryTerminalDrayageEmail,
+  getTerminalDrayageHistory,
+  listTerminalDrayages,
+  recordTerminalDrayageEmptyReturn,
+  scheduleTerminalDrayagePickup,
+  selectTerminalDrayageFleet,
+} from './terminalDrayages'
+
+vi.mock('@/shared/api/http', () => ({
+  http: { get: vi.fn(), post: vi.fn() },
+  unwrapApiResponse: <T>(response: { data: T }) => response.data,
+}))
+
+const view = {
+  containerBookingId: '9007199254740993', containerNo: 'MSCU1234567', oceanBookingId: '9007199254740994',
+  status: 'UNLOADED', version: '3', fleetSupplierId: '9007199254740995', fleetSupplierName: '港运车队',
+  pickupAppointmentAt: '2026-09-07T08:00:00', actualPickupAt: '2026-09-07T09:00:00', estimatedEmptyReturnAt: '2026-09-10T10:00:00',
+  actualEmptyReturnAt: null, unloadingCompletedAt: '2026-09-07T10:00:00',
+  emptyReturnWarning: { status: 'OVERDUE', deadlineAt: '2026-09-10T10:00:00', overdueHours: '26', overdueDays: '1' },
+  allowedActions: ['SELECT_FLEET', 'RECORD_EMPTY_RETURN'], updatedAt: '2026-09-11T12:00:00',
+}
+
+describe('terminal drayages API', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it('queues pickup email with version and idempotency and scopes retries to the container', async () => {
+    vi.mocked(http.post).mockResolvedValueOnce({ data: view })
+    await sendTerminalDrayageEmail('9007199254740993', 3)
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/terminal-drayages/9007199254740993/pickup-email',
+      { expectedVersion: 3 }, { headers: { 'Idempotency-Key': expect.any(String) } })
+    vi.mocked(http.get).mockResolvedValueOnce({ data: { deliveryEnabled: false, records: [{ id: '9007199254740999', status: 'FAILED' }] } })
+    expect((await getTerminalDrayageEmails('9007199254740993')).records[0].id).toBe('9007199254740999')
+    vi.mocked(http.post).mockResolvedValueOnce({ data: null })
+    await retryTerminalDrayageEmail('9007199254740993', '9007199254740999')
+    expect(http.post).toHaveBeenLastCalledWith('/platform/v1/terminal-drayages/9007199254740993/emails/9007199254740999/retry')
+  })
+
+  it('sends repeated container ids and preserves long identifiers as strings', async () => {
+    vi.mocked(http.get).mockResolvedValueOnce({ data: [view] })
+    const result = await listTerminalDrayages(['9007199254740993', '9007199254740994'])
+    const config = vi.mocked(http.get).mock.calls[0][1] as { params: URLSearchParams }
+    expect(config.params.getAll('containerBookingIds')).toEqual(['9007199254740993', '9007199254740994'])
+    expect(result[0]).toMatchObject({ containerBookingId: '9007199254740993', oceanBookingId: '9007199254740994', fleetSupplierId: '9007199254740995', version: 3 })
+    expect(result[0].emptyReturnWarning).toMatchObject({ overdueHours: 26, overdueDays: 1 })
+  })
+
+  it('uses frozen command paths, versions and idempotency keys', async () => {
+    vi.mocked(http.post).mockResolvedValue({ data: view })
+    await selectTerminalDrayageFleet('101', { expectedVersion: 3, fleetSupplierId: '501', fleetSupplierName: '港运车队' })
+    await scheduleTerminalDrayagePickup('101', { expectedVersion: 4, pickupAppointmentAt: '2026-09-07T08:00:00' })
+    await recordTerminalDrayageEmptyReturn('101', { expectedVersion: 5, actualAt: '2026-09-10T09:00:00', remark: '实际还柜' })
+    expect(http.post).toHaveBeenNthCalledWith(1, '/platform/v1/terminal-drayages/101/fleet', expect.objectContaining({ expectedVersion: 3, fleetSupplierId: '501' }), expect.objectContaining({ headers: { 'Idempotency-Key': expect.stringContaining('terminal-drayage-fleet-') } }))
+    expect(http.post).toHaveBeenNthCalledWith(2, '/platform/v1/terminal-drayages/101/pickup-appointment', expect.objectContaining({ expectedVersion: 4 }), expect.any(Object))
+    expect(http.post).toHaveBeenNthCalledWith(3, '/platform/v1/terminal-drayages/101/empty-return', expect.objectContaining({ expectedVersion: 5, remark: '实际还柜' }), expect.objectContaining({ headers: { 'Idempotency-Key': expect.stringContaining('terminal-drayage-empty-return-') } }))
+  })
+
+  it('loads operation history from the container business id', async () => {
+    vi.mocked(http.get).mockResolvedValueOnce({ data: [{ action: 'SELECT_FLEET', fromStatus: 'ARRIVED', toStatus: 'ARRIVED', fromVersion: 0, toVersion: 1, reason: null, operatorId: '9007199254740993', operatorName: '平台管理员', createdAt: '2026-09-07T08:00:00' }] })
+    const result = await getTerminalDrayageHistory('101')
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/terminal-drayages/101/history')
+    expect(result[0].operatorId).toBe('9007199254740993')
+  })
+})
diff --git a/src/modules/container-loading/api/terminalDrayages.ts b/src/modules/container-loading/api/terminalDrayages.ts
new file mode 100644
index 00000000..78555ad7
--- /dev/null
+++ b/src/modules/container-loading/api/terminalDrayages.ts
@@ -0,0 +1,128 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+
+export type TerminalDrayageStatus = 'WAITING_FOR_ARRIVAL' | 'ARRIVED' | 'PICKUP_SCHEDULED' | 'PICKED_UP' | 'UNLOADED' | 'EMPTY_RETURNED'
+export type TerminalDrayageAction = 'SELECT_FLEET' | 'SCHEDULE_PICKUP' | 'RECORD_EMPTY_RETURN' | 'SEND_PICKUP_EMAIL'
+
+export interface TerminalDrayageEmail {
+  id: string
+  fleetName: string
+  recipient: string
+  kind: 'REQUEST_PICKUP' | 'CANCEL_PICKUP'
+  subject: string
+  body: string
+  status: 'PENDING' | 'SENDING' | 'SENT' | 'FAILED'
+  attempts: number
+  failureReason: string | null
+  createdAt: string
+  sentAt: string | null
+}
+
+export async function getTerminalDrayageEmails(containerId: string) {
+  type Mailbox = { deliveryEnabled: boolean; records: TerminalDrayageEmail[] }
+  const response = await http.get<ApiEnvelope<Mailbox>, ApiEnvelope<Mailbox>>(`${path}/${encodeURIComponent(containerId)}/emails`)
+  const result = unwrapApiResponse(response)
+  return { ...result, records: result.records.map((mail) => ({ ...mail, id: String(mail.id) })) }
+}
+
+export function sendTerminalDrayageEmail(containerId: string, expectedVersion: number) {
+  return command(containerId, 'pickup-email', { expectedVersion })
+}
+
+export async function retryTerminalDrayageEmail(containerId: string, mailId: string) {
+  const response = await http.post<ApiEnvelope<null>, ApiEnvelope<null>>(`${path}/${encodeURIComponent(containerId)}/emails/${encodeURIComponent(mailId)}/retry`)
+  unwrapApiResponse(response)
+}
+export type EmptyReturnWarningStatus = 'NOT_APPLICABLE' | 'PENDING' | 'OVERDUE' | 'RESOLVED'
+
+export interface EmptyReturnWarning {
+  status: EmptyReturnWarningStatus
+  deadlineAt: string | null
+  overdueHours: number
+  overdueDays: number
+}
+
+export interface TerminalDrayageView {
+  containerBookingId: string
+  containerNo: string | null
+  oceanBookingId: string | null
+  status: TerminalDrayageStatus
+  version: number
+  fleetSupplierId: string | null
+  fleetSupplierName: string | null
+  pickupAppointmentAt: string | null
+  actualPickupAt: string | null
+  estimatedEmptyReturnAt: string | null
+  actualEmptyReturnAt: string | null
+  unloadingCompletedAt: string | null
+  emptyReturnWarning: EmptyReturnWarning
+  allowedActions: TerminalDrayageAction[]
+  updatedAt: string | null
+}
+
+export interface TerminalDrayageHistory {
+  action: TerminalDrayageAction
+  fromStatus: string
+  toStatus: string
+  fromVersion: number
+  toVersion: number
+  reason: string | null
+  operatorId: string
+  operatorName: string | null
+  createdAt: string
+}
+
+const path = '/platform/v1/terminal-drayages'
+function operationId(action: string) { return `terminal-drayage-${action}-${Date.now()}-${Math.random().toString(36).slice(2)}` }
+function id(value: unknown): string { return value == null ? '' : String(value) }
+function optionalId(value: unknown): string | null { return value == null ? null : String(value) }
+function normalize(raw: TerminalDrayageView): TerminalDrayageView {
+  return {
+    ...raw,
+    containerBookingId: id(raw.containerBookingId),
+    oceanBookingId: optionalId(raw.oceanBookingId),
+    fleetSupplierId: optionalId(raw.fleetSupplierId),
+    version: Number(raw.version || 0),
+    allowedActions: raw.allowedActions || [],
+    emptyReturnWarning: {
+      ...raw.emptyReturnWarning,
+      overdueHours: Number(raw.emptyReturnWarning?.overdueHours || 0),
+      overdueDays: Number(raw.emptyReturnWarning?.overdueDays || 0),
+    },
+  }
+}
+
+export async function listTerminalDrayages(containerBookingIds: string[]) {
+  const params = new URLSearchParams()
+  containerBookingIds.forEach((containerBookingId) => params.append('containerBookingIds', containerBookingId))
+  const response = await http.get<ApiEnvelope<TerminalDrayageView[]>, ApiEnvelope<TerminalDrayageView[]>>(path, { params })
+  return (unwrapApiResponse(response) || []).map(normalize)
+}
+
+export async function getTerminalDrayage(containerBookingId: string) {
+  const response = await http.get<ApiEnvelope<TerminalDrayageView>, ApiEnvelope<TerminalDrayageView>>(`${path}/${encodeURIComponent(containerBookingId)}`)
+  return normalize(unwrapApiResponse(response))
+}
+
+export async function getTerminalDrayageHistory(containerBookingId: string) {
+  const response = await http.get<ApiEnvelope<TerminalDrayageHistory[]>, ApiEnvelope<TerminalDrayageHistory[]>>(`${path}/${encodeURIComponent(containerBookingId)}/history`)
+  return (unwrapApiResponse(response) || []).map((item) => ({ ...item, operatorId: id(item.operatorId) }))
+}
+
+async function command(containerBookingId: string, action: string, body: object) {
+  const response = await http.post<ApiEnvelope<TerminalDrayageView>, ApiEnvelope<TerminalDrayageView>>(
+    `${path}/${encodeURIComponent(containerBookingId)}/${action}`,
+    body,
+    { headers: { 'Idempotency-Key': operationId(action) } },
+  )
+  return normalize(unwrapApiResponse(response))
+}
+
+export function selectTerminalDrayageFleet(containerBookingId: string, body: { expectedVersion: number; fleetSupplierId: string; fleetSupplierName?: string; reason?: string }) {
+  return command(containerBookingId, 'fleet', body)
+}
+export function scheduleTerminalDrayagePickup(containerBookingId: string, body: { expectedVersion: number; pickupAppointmentAt: string; reason?: string }) {
+  return command(containerBookingId, 'pickup-appointment', body)
+}
+export function recordTerminalDrayageEmptyReturn(containerBookingId: string, body: { expectedVersion: number; actualAt: string; remark?: string }) {
+  return command(containerBookingId, 'empty-return', body)
+}
diff --git a/src/modules/container-loading/components/ContainerCustomsPanel.test.ts b/src/modules/container-loading/components/ContainerCustomsPanel.test.ts
new file mode 100644
index 00000000..2e63b4d2
--- /dev/null
+++ b/src/modules/container-loading/components/ContainerCustomsPanel.test.ts
@@ -0,0 +1,163 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { flushPromises, mount } from '@vue/test-utils'
+import ElementPlus from 'element-plus'
+import { ApiResponseError } from '@/shared/api/http'
+import type { ContainerCustomsStatus, ContainerCustomsView } from '../api/platformContainerCustoms'
+
+const api = vi.hoisted(() => ({
+  get: vi.fn(),
+  start: vi.fn(),
+  completeAllBuy: vi.fn(),
+  upload: vi.fn(),
+  downloadSource: vi.fn(),
+  downloadCompletion: vi.fn(),
+}))
+
+vi.mock('../api/platformContainerCustoms', () => ({
+  getContainerCustoms: api.get,
+  startContainerCustoms: api.start,
+  completeAllBuyContainerCustoms: api.completeAllBuy,
+  uploadContainerCustomsCompletion: api.upload,
+  downloadContainerCustomsDocument: api.downloadSource,
+  downloadContainerCustomsCompletion: api.downloadCompletion,
+}))
+vi.mock('@/modules/downloads', () => ({ createPlatformExportTask: vi.fn() }))
+
+import ContainerCustomsPanel from './ContainerCustomsPanel.vue'
+
+function customs(status: ContainerCustomsStatus, hasCompletion = false): ContainerCustomsView {
+  return {
+    aggregateId: '2092438843630391401', loadingPlanId: '2092438843630391402', containerBookingId: '2092438843630391403',
+    planNo: 'LP-1', cabinetNo: 'MCR08290001', containerNo: 'MSCU-1', status, hasActualCargo: true, version: 3, taxRefundCount: 1, coveredTaxRefundCount: 1,
+    inbounds: [{ inboundId: '2092438843630391404', orderId: '2092438843630391405', orderNo: 'O-1', inboundCode: 'RK-1', tenantId: '2092438843630391406', customerName: '客户一', taxMode: 'TAX_REFUND', covered: true }],
+    documents: [{
+      documentId: '2092438843630391407', tenantId: '2092438843630391406',
+      source: { fileId: '2092438843630391408', fileName: '客户退税资料.pdf', fileHash: 'source-hash', sizeBytes: 12, version: 2, uploadedAt: '2026-08-29T10:00:00' },
+      inboundIds: ['2092438843630391404'], inboundCodes: ['RK-1'], frozen: true,
+      completion: hasCompletion ? { fileId: '2092438843630391409', fileName: '报关完成文件.pdf', fileHash: 'completion-hash', sizeBytes: 13, version: 1, uploadedAt: '2026-08-29T11:00:00' } : null,
+    }],
+    startedAt: status === 'DECLARING' || status === 'COMPLETED' ? '2026-08-29T10:30:00' : null,
+    completedAt: status === 'COMPLETED' ? '2026-08-29T11:30:00' : null,
+  }
+}
+
+async function render(status: ContainerCustomsStatus, canManage = true, hasCompletion = false) {
+  api.get.mockResolvedValue(customs(status, hasCompletion))
+  const wrapper = mount(ContainerCustomsPanel, {
+    props: { loadingPlanId: '2092438843630391402', canList: true, canManage, departureState: 'WAITING_OTHER_GATES' },
+    global: { plugins: [ElementPlus] },
+  })
+  await flushPromises()
+  return wrapper
+}
+
+function buttonTexts(wrapper: Awaited<ReturnType<typeof render>>) {
+  return wrapper.findAll('button').map((button) => button.text())
+}
+
+describe('ContainerCustomsPanel', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    api.downloadSource.mockResolvedValue(new Blob(['source']))
+    api.downloadCompletion.mockResolvedValue(new Blob(['completion']))
+    Object.defineProperty(URL, 'createObjectURL', { configurable: true, value: vi.fn(() => 'blob:customs-file') })
+    Object.defineProperty(URL, 'revokeObjectURL', { configurable: true, value: vi.fn() })
+    vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(() => undefined)
+  })
+
+  it('keeps READY_TO_START read-only while exposing source file name and download', async () => {
+    const wrapper = await render('READY_TO_START')
+    expect(wrapper.text()).toContain('开始报关')
+    expect(wrapper.text()).toContain('客户退税资料.pdf')
+    expect(wrapper.text()).toContain('客户退税资料')
+    expect(wrapper.text()).toContain('报关完成文件')
+    expect(wrapper.text()).not.toContain('客户报关资料')
+    expect(wrapper.find('[aria-label="下载客户退税资料 客户退税资料.pdf"]').exists()).toBe(true)
+    expect(buttonTexts(wrapper)).not.toContain('上传报关完成文件')
+    expect(buttonTexts(wrapper)).not.toContain('覆盖报关完成文件')
+    expect(buttonTexts(wrapper)).not.toContain('提交')
+  })
+
+  it('shows a successful empty state and hides customs actions when the completed plan has no actual cargo', async () => {
+    api.get.mockResolvedValue({ ...customs('READY_TO_START'), hasActualCargo: false, taxRefundCount: 0, coveredTaxRefundCount: 0, inbounds: [], documents: [] })
+    const wrapper = mount(ContainerCustomsPanel, {
+      props: { loadingPlanId: '2092438843630391402', canList: true, canManage: true, departureState: 'WAITING_OTHER_GATES' },
+      global: { plugins: [ElementPlus] },
+    })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('当前装柜计划没有实际装柜货物，无需报关')
+    expect(wrapper.text()).toContain('无需报关')
+    expect(buttonTexts(wrapper)).not.toContain('开始报关')
+    expect(buttonTexts(wrapper)).not.toContain('导出买单 XLSX')
+  })
+
+  it('shows a pending state instead of an error before loading is completed', async () => {
+    api.get.mockResolvedValue(null)
+    const wrapper = mount(ContainerCustomsPanel, {
+      props: { loadingPlanId: '2097922185010147329', canList: true, canManage: false, departureState: 'WAITING_OTHER_GATES' },
+      global: { plugins: [ElementPlus] },
+    })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('当前装柜计划尚未完成，完成装柜后可处理报关')
+    expect(wrapper.text()).not.toContain('整柜报关加载失败')
+  })
+
+  it('allows completion upload and overwrite only while DECLARING with manage permission', async () => {
+    let wrapper = await render('DECLARING', true, false)
+    expect(wrapper.text()).toContain('上传报关完成文件')
+    expect(wrapper.text()).toContain('提交')
+    wrapper.unmount()
+
+    wrapper = await render('DECLARING', true, true)
+    expect(wrapper.text()).toContain('覆盖报关完成文件')
+    expect(wrapper.text()).toContain('报关完成文件.pdf')
+    wrapper.unmount()
+
+    wrapper = await render('DECLARING', false, true)
+    expect(wrapper.text()).toContain('只读')
+    expect(buttonTexts(wrapper)).not.toContain('上传报关完成文件')
+    expect(buttonTexts(wrapper)).not.toContain('覆盖报关完成文件')
+    expect(buttonTexts(wrapper)).not.toContain('提交')
+  })
+
+  it('keeps COMPLETED strictly read-only with both files visible and downloadable', async () => {
+    const wrapper = await render('COMPLETED', true, true)
+    expect(wrapper.text()).toContain('客户退税资料.pdf')
+    expect(wrapper.text()).toContain('报关完成文件.pdf')
+    expect(wrapper.text()).toContain('报关已完成，待其他离仓条件')
+    expect(buttonTexts(wrapper)).not.toContain('上传报关完成文件')
+    expect(buttonTexts(wrapper)).not.toContain('覆盖报关完成文件')
+    expect(buttonTexts(wrapper)).not.toContain('提交')
+  })
+
+  it('routes source and completion downloads independently by the long document id and original names', async () => {
+    const wrapper = await render('COMPLETED', false, true)
+    await wrapper.get('[aria-label="下载客户退税资料 客户退税资料.pdf"]').trigger('click')
+    await flushPromises()
+    expect(api.downloadSource).toHaveBeenCalledWith('2092438843630391407')
+    expect(api.downloadCompletion).not.toHaveBeenCalled()
+
+    await wrapper.get('[aria-label="下载报关完成文件 报关完成文件.pdf"]').trigger('click')
+    await flushPromises()
+    expect(api.downloadCompletion).toHaveBeenCalledWith('2092438843630391407')
+    expect(HTMLAnchorElement.prototype.click).toHaveBeenCalledTimes(2)
+    expect(URL.createObjectURL).toHaveBeenCalledTimes(2)
+    expect(URL.revokeObjectURL).toHaveBeenCalledWith('blob:customs-file')
+  })
+
+  it('preserves backend error code, request id and trace id when one download fails', async () => {
+    api.downloadSource.mockRejectedValueOnce(new ApiResponseError('文件不可用', 'CUSTOMS_FILE_404', 404, undefined, 'request-customs-download', 'trace-customs-download'))
+    const wrapper = await render('COMPLETED', false, true)
+
+    await wrapper.get('[aria-label="下载客户退税资料 客户退税资料.pdf"]').trigger('click')
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('文件不可用')
+    expect(wrapper.text()).toContain('CUSTOMS_FILE_404')
+    expect(wrapper.text()).toContain('request-customs-download')
+    expect(wrapper.text()).toContain('trace-customs-download')
+    expect(api.downloadCompletion).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/modules/container-loading/components/ContainerCustomsPanel.vue b/src/modules/container-loading/components/ContainerCustomsPanel.vue
new file mode 100644
index 00000000..312ceb4b
--- /dev/null
+++ b/src/modules/container-loading/components/ContainerCustomsPanel.vue
@@ -0,0 +1,196 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, reactive, ref, watch } from 'vue'
+import { ElMessage, ElMessageBox, type UploadFile } from 'element-plus'
+import { createPlatformExportTask } from '@/modules/downloads'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import OperationErrorToast from '@/shared/components/OperationErrorToast.vue'
+import {
+  completeAllBuyContainerCustoms,
+  downloadContainerCustomsCompletion,
+  downloadContainerCustomsDocument,
+  getContainerCustoms,
+  startContainerCustoms,
+  uploadContainerCustomsCompletion,
+  type ContainerCustomsDocument,
+  type ContainerCustomsStatus,
+  type ContainerCustomsView,
+} from '../api/platformContainerCustoms'
+
+const props = defineProps<{
+  loadingPlanId: string
+  canList: boolean
+  canManage: boolean
+  departureState: 'DEPARTED' | 'WAITING_OTHER_GATES' | 'UNKNOWN'
+}>()
+const emit = defineEmits<{ refreshed: [] }>()
+
+const customs = ref<ContainerCustomsView | null>(null)
+const loading = ref(false)
+const actionLoading = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const actionError = ref<ApiErrorDetails | null>(null)
+const downloadingKey = ref('')
+const completionFiles = reactive<Record<string, File | null>>({})
+
+const missingInbounds = computed(() => customs.value?.inbounds.filter((item) => item.taxMode === 'TAX_REFUND' && !item.covered) || [])
+const missingCoverageCount = computed(() => Math.max(0, (customs.value?.taxRefundCount || 0) - (customs.value?.coveredTaxRefundCount || 0)))
+const allBuy = computed(() => customs.value?.hasActualCargo === true && customs.value.taxRefundCount === 0)
+const missingCompletionCount = computed(() => customs.value?.documents.filter((item) => !item.completion).length || 0)
+const statusText: Record<ContainerCustomsStatus, string> = {
+  WAITING_CUSTOMER_DOCUMENTS: '待客户补齐退税资料', READY_TO_START: '可开始报关', DECLARING: '报关中', COMPLETED: '报关已完成',
+}
+
+function documentCustomers(document: ContainerCustomsDocument) {
+  return [...new Set((customs.value?.inbounds || []).filter((item) => document.inboundIds.includes(item.inboundId)).map((item) => item.customerName))].join('、') || '—'
+}
+function selectCompletion(documentId: string, upload: UploadFile) {
+  if (!props.canManage || customs.value?.status !== 'DECLARING') return
+  completionFiles[documentId] = upload.raw || null
+  actionError.value = null
+}
+
+async function load() {
+  if (!props.canList || !props.loadingPlanId) return
+  loading.value = true
+  loadError.value = null
+  try { customs.value = await getContainerCustoms(props.loadingPlanId) }
+  catch (error) { customs.value = null; loadError.value = getApiErrorDetails(error, '整柜报关状态加载失败') }
+  finally { loading.value = false }
+}
+
+async function start() {
+  if (!customs.value || customs.value.status !== 'READY_TO_START') return
+  try {
+    await ElMessageBox.confirm('开始后将冻结客户当前退税资料版本、关联入仓码覆盖范围及平台买单准备事实，确认开始整柜报关？', '开始整柜报关', { customClass: 'admin-density-confirm', type: 'warning', confirmButtonText: '确认开始' })
+  } catch { return }
+  actionLoading.value = true; actionError.value = null
+  try { customs.value = await startContainerCustoms(props.loadingPlanId, customs.value.version); ElMessage.success('整柜报关已开始') }
+  catch (error) { actionError.value = getApiErrorDetails(error, '开始整柜报关失败') }
+  finally { actionLoading.value = false }
+}
+
+async function uploadCompletion(document: ContainerCustomsDocument) {
+  if (!props.canManage || customs.value?.status !== 'DECLARING') return
+  const selected = completionFiles[document.documentId]
+  if (!selected) { ElMessage.warning('请选择对应的报关完成文件'); return }
+  const finalConfirmation = !document.completion && missingCompletionCount.value === 1
+  if (finalConfirmation) {
+    try {
+      await ElMessageBox.confirm('这是最后一份待上传的报关完成文件；确认后系统将自动完成当前混合/退税柜报关。是否继续？', '完成整柜报关', { customClass: 'admin-density-confirm', type: 'warning', confirmButtonText: '确认上传并完成' })
+    } catch { return }
+  }
+  actionLoading.value = true; actionError.value = null
+  try {
+    await uploadContainerCustomsCompletion(document.documentId, selected, document.completion?.version || 0, finalConfirmation)
+    completionFiles[document.documentId] = null
+    await load()
+    emit('refreshed')
+    ElMessage.success(finalConfirmation ? '报关完成文件已上传，整柜报关已完成' : '报关完成文件已上传')
+  } catch (error) { actionError.value = getApiErrorDetails(error, '报关完成文件上传失败') }
+  finally { actionLoading.value = false }
+}
+
+function saveBlob(blob: Blob, fileName: string) {
+  const url = URL.createObjectURL(blob)
+  const anchor = document.createElement('a')
+  anchor.href = url
+  anchor.download = fileName
+  anchor.click()
+  URL.revokeObjectURL(url)
+}
+
+async function downloadFile(document: ContainerCustomsDocument, kind: 'source' | 'completion') {
+  const target = kind === 'source' ? document.source : document.completion
+  if (!target) return
+  const key = `${kind}:${document.documentId}`
+  downloadingKey.value = key
+  actionError.value = null
+  try {
+    const blob = kind === 'source'
+      ? await downloadContainerCustomsDocument(document.documentId)
+      : await downloadContainerCustomsCompletion(document.documentId)
+    saveBlob(blob, target.fileName)
+    ElMessage.success(`${kind === 'source' ? '客户退税资料' : '报关完成文件'}下载已开始`)
+  } catch (error) {
+    actionError.value = getApiErrorDetails(error, `${kind === 'source' ? '客户退税资料' : '报关完成文件'}下载失败`)
+  } finally {
+    downloadingKey.value = ''
+  }
+}
+
+async function completeAllBuy() {
+  if (!customs.value || customs.value.status !== 'DECLARING' || !allBuy.value) return
+  try { await ElMessageBox.confirm('确认全买单柜报关已经完成？报关完成不等同于国内离仓。', '完成全买单柜报关', { customClass: 'admin-density-confirm', type: 'warning', confirmButtonText: '确认完成' }) }
+  catch { return }
+  actionLoading.value = true; actionError.value = null
+  try {
+    customs.value = await completeAllBuyContainerCustoms(props.loadingPlanId, customs.value.version)
+    emit('refreshed')
+    ElMessage.success('全买单柜报关已完成')
+  } catch (error) { actionError.value = getApiErrorDetails(error, '完成全买单柜报关失败') }
+  finally { actionLoading.value = false }
+}
+
+async function exportAllBuy() {
+  actionLoading.value = true; actionError.value = null
+  try {
+    const task = await createPlatformExportTask({
+      exportType: 'LOADING_LIST_BUY_DECLARATION_ITEMS', format: 'XLSX', taskName: `买单报关-${customs.value?.planNo || '柜级明细'}`,
+      parameters: { loadingPlanId: String(props.loadingPlanId) },
+    })
+    ElMessage.success(`买单报关导出任务已创建：${task.taskNo}`)
+  } catch (error) { actionError.value = getApiErrorDetails(error, '买单报关导出任务创建失败') }
+  finally { actionLoading.value = false }
+}
+
+watch(() => props.loadingPlanId, () => { void load() })
+onMounted(load)
+</script>
+
+<template>
+  <section class="container-customs surface-panel admin-density" aria-label="整柜报关">
+    <OperationErrorToast :details="actionError" />
+    <header class="customs-header">
+      <div><h2>整柜报关</h2><p>客户退税资料与平台买单事实按柜冻结；报关完成和国内离仓分别展示。</p></div>
+      <div v-if="customs" class="customs-actions">
+        <el-tag :type="!customs.hasActualCargo ? 'info' : customs.status === 'COMPLETED' ? 'success' : customs.status === 'WAITING_CUSTOMER_DOCUMENTS' ? 'danger' : 'warning'">{{ customs.hasActualCargo ? statusText[customs.status] : '无需报关' }}</el-tag>
+        <el-button v-if="canManage && allBuy" plain :loading="actionLoading" @click="exportAllBuy">导出买单 XLSX</el-button>
+        <el-button v-if="canManage && customs.hasActualCargo && customs.status === 'READY_TO_START'" type="primary" :loading="actionLoading" @click="start">开始报关</el-button>
+        <el-button v-if="canManage && allBuy && customs.status === 'DECLARING'" type="primary" :loading="actionLoading" @click="completeAllBuy">确认报关完成</el-button>
+      </div>
+    </header>
+    <div v-if="actionError" class="action-error" role="alert"><span>{{ actionError.message }}</span><ApiErrorMeta :details="actionError" /></div>
+    <LoadErrorState v-if="loadError" compact title="整柜报关加载失败" :message="loadError.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="loadError" /></template></LoadErrorState>
+    <div v-else-if="loading"><el-skeleton :rows="3" animated /></div>
+    <template v-else-if="customs">
+      <el-empty v-if="!customs.hasActualCargo" description="当前装柜计划没有实际装柜货物，无需报关" :image-size="56" />
+      <template v-else>
+      <div class="customs-metrics"><span>退税总票 <strong>{{ customs.taxRefundCount }}</strong></span><span>已覆盖 <strong>{{ customs.coveredTaxRefundCount }}</strong></span><span :class="{ danger: missingCoverageCount }">缺失 <strong>{{ missingCoverageCount }}</strong></span></div>
+      <div v-if="missingInbounds.length" class="compact-table-wrap">
+        <h3>缺退税资料清单</h3>
+        <table class="compact-table density-table"><thead><tr><th>客户</th><th>订单号</th><th>入仓码</th></tr></thead><tbody><tr v-for="item in missingInbounds" :key="item.inboundId"><td>{{ item.customerName }}</td><td>{{ item.orderNo }}</td><td>{{ item.inboundCode }}</td></tr></tbody></table>
+      </div>
+      <div v-if="customs.documents.length" class="compact-table-wrap">
+        <h3>已冻结退税资料与报关完成文件</h3>
+        <table class="compact-table document-table density-table"><thead><tr><th>操作</th><th>客户退税资料</th><th>报关完成文件</th><th>关联入仓码</th><th>版本</th><th>客户</th><th>完成情况</th></tr></thead><tbody>
+          <tr v-for="document in customs.documents" :key="document.documentId">
+            <td><div v-if="canManage && customs.status === 'DECLARING'" class="document-actions density-actions"><el-upload :auto-upload="false" :limit="1" :show-file-list="false" :on-change="(upload: UploadFile) => selectCompletion(document.documentId, upload)"><el-button class="density-action" size="small">{{ document.completion ? '覆盖报关完成文件' : '上传报关完成文件' }}</el-button></el-upload><el-button data-tone="primary" class="density-action" size="small" type="primary" :disabled="!completionFiles[document.documentId]" :loading="actionLoading" @click="uploadCompletion(document)">提交</el-button></div><span v-else class="readonly-label">只读</span></td>
+            <td><div class="file-cell"><span :title="document.source.fileName">{{ document.source.fileName }}</span><el-button class="density-action" type="primary" :loading="downloadingKey === `source:${document.documentId}`" :aria-label="`下载客户退税资料 ${document.source.fileName}`" @click="downloadFile(document, 'source')">下载</el-button></div></td>
+            <td><div v-if="document.completion" class="file-cell"><span :title="document.completion.fileName">{{ document.completion.fileName }}</span><el-button class="density-action" type="primary" :loading="downloadingKey === `completion:${document.documentId}`" :aria-label="`下载报关完成文件 ${document.completion.fileName}`" @click="downloadFile(document, 'completion')">下载</el-button></div><span v-else>未上传</span></td>
+            <td>{{ document.inboundCodes.join('、') || '—' }}</td><td>退税资料 v{{ document.source.version }}<span v-if="document.completion"> / 报关完成 v{{ document.completion.version }}</span></td><td>{{ documentCustomers(document) }}</td><td>{{ document.completion ? '已上传报关完成文件' : '待上传报关完成文件' }}</td>
+          </tr>
+        </tbody></table>
+      </div>
+      </template>
+      <div v-if="customs.status === 'COMPLETED'" class="departure-state"><strong>国内离仓状态：</strong><el-tag :type="departureState === 'DEPARTED' ? 'success' : 'warning'">{{ departureState === 'DEPARTED' ? '已自动离仓' : departureState === 'UNKNOWN' ? '离仓状态尚未读取' : '报关已完成，待其他离仓条件' }}</el-tag></div>
+    </template>
+    <el-empty v-else-if="canList" description="当前装柜计划尚未完成，完成装柜后可处理报关" :image-size="56" />
+  </section>
+</template>
+
+<style scoped>
+.container-customs{padding:0;border:0}.customs-header{display:flex;align-items:center;justify-content:space-between;gap:var(--admin-space-5)}.customs-header h2,.compact-table-wrap h3{margin:0;font-size:var(--admin-font-section)}.customs-header p{margin:3px 0 0;color:var(--cc-muted);font-size:var(--admin-font-caption)}.customs-actions{display:flex;align-items:center;gap:var(--admin-space-3)}.action-error{margin-top:var(--admin-space-3);padding:var(--admin-space-3) var(--admin-space-4);border:1px solid var(--el-color-danger-light-5);border-radius:var(--admin-radius);background:var(--el-color-danger-light-9);color:var(--el-color-danger);font-size:var(--admin-font-caption)}.action-error :deep(.api-error-meta){margin-top:5px}.customs-metrics{display:flex;gap:var(--admin-space-6);margin-top:var(--admin-space-4);padding:var(--admin-space-3) var(--admin-space-4);background:var(--cc-surface-muted);font-size:var(--admin-font-caption)}.customs-metrics strong{margin-left:var(--admin-space-1);font-size:var(--admin-font-body)}.customs-metrics .danger strong{color:var(--el-color-danger)}.compact-table-wrap{margin-top:var(--admin-space-4)}.compact-table-wrap h3{margin-bottom:var(--admin-space-2)}.compact-table{width:100%}.document-table th:first-child{width:270px}.document-actions,.file-cell{display:flex;align-items:center;gap:var(--admin-space-2)}.file-cell span{display:block;max-width:210px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.readonly-label{color:var(--cc-muted)}.departure-state{display:flex;align-items:center;gap:var(--admin-space-3);margin-top:var(--admin-space-4);padding-top:var(--admin-space-4);border-top:1px solid var(--cc-border);font-size:var(--admin-font-body)}
+</style>
diff --git a/src/modules/container-loading/components/ContainerLastLegFeesPanel.test.ts b/src/modules/container-loading/components/ContainerLastLegFeesPanel.test.ts
new file mode 100644
index 00000000..f00836f6
--- /dev/null
+++ b/src/modules/container-loading/components/ContainerLastLegFeesPanel.test.ts
@@ -0,0 +1,87 @@
+import { mount, flushPromises } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import ElementPlus from 'element-plus'
+import ContainerLastLegFeesPanel from './ContainerLastLegFeesPanel.vue'
+
+const mocks = vi.hoisted(() => ({ upload: vi.fn(), metadata: vi.fn(), download: vi.fn(), create: vi.fn(), fees: vi.fn() }))
+vi.mock('@/core/access/accessPreview', () => ({ useAccessPreviewStore: () => ({ can: () => true }) }))
+vi.mock('@/modules/finance', () => ({ getFinancePaymentVoucher: mocks.metadata, downloadFinancePaymentVoucher: mocks.download }))
+vi.mock('@/modules/loading-lists', () => ({ uploadContainerFeePaymentVoucher: mocks.upload, listContainerFeeSupplierOptions: async () => [] }))
+vi.mock('../api/overseasContainerFees', () => ({
+  listOverseasContainerFees: mocks.fees, listOverseasContainerCustomers: async () => [{ customerId: '11', customerName: '客户甲' }],
+  createOverseasContainerFee: mocks.create, adjustOverseasContainerFee: vi.fn(), reviewOverseasContainerFee: vi.fn(), submitOverseasContainerFee: vi.fn(), voidOverseasContainerFee: vi.fn(),
+}))
+
+async function setup(readonly = false) {
+  const wrapper = mount(ContainerLastLegFeesPanel, { props: { containerBookingId: '99', containerNo: 'CONT-99', readonly }, global: { plugins: [ElementPlus], stubs: {
+    AppDialog: { props: ['modelValue', 'title', 'confirmDisabled'], template: '<section v-if="modelValue"><h3>{{ title }}</h3><slot /><button :disabled="confirmDisabled" @click="$emit(\'confirm\')">保存</button></section>' },
+  } } })
+  await flushPromises()
+  return wrapper
+}
+type FormState = { form: { customerId: string; settlementMode: string }; dialogOpen: boolean }
+async function upload(wrapper: Awaited<ReturnType<typeof setup>>, name: string) {
+  const input = wrapper.get('input[type="file"]')
+  Object.defineProperty(input.element, 'files', { configurable: true, value: [new File(['image'], name, { type: 'image/png' })] })
+  await input.trigger('change')
+  await flushPromises()
+}
+describe('尾程付款凭证', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mocks.fees.mockResolvedValue([])
+    vi.stubGlobal('ResizeObserver', class { observe() {} unobserve() {} disconnect() {} })
+    URL.createObjectURL = vi.fn(() => 'blob:voucher')
+    URL.revokeObjectURL = vi.fn()
+    mocks.metadata.mockResolvedValue({ fileId: '91', fileName: '付款.png', contentType: 'image/png' })
+    mocks.download.mockResolvedValue(new Blob(['image']))
+  })
+
+  it('显示上传文件名，允许再次上传替换和移除', async () => {
+    const wrapper = await setup()
+    await wrapper.get('button').trigger('click')
+    const state = (wrapper.vm.$ as unknown as { setupState: FormState }).setupState
+    state.form.settlementMode = 'DIRECT_PAID'
+    await flushPromises()
+    mocks.upload.mockResolvedValueOnce({ fileId: '91', fileName: '付款.png' }).mockResolvedValueOnce({ fileId: '92', fileName: '新凭证.png' })
+    await upload(wrapper, '付款.png')
+    expect(mocks.upload).toHaveBeenCalledWith('11', expect.any(File))
+    expect(wrapper.text()).toContain('付款.png')
+    await upload(wrapper, '新凭证.png')
+    expect(wrapper.text()).toContain('新凭证.png')
+    expect(wrapper.text()).not.toContain('付款.png')
+    await wrapper.findAll('button').find(b => b.text() === '移除')!.trigger('click')
+    expect(wrapper.text()).not.toContain('新凭证.png')
+    wrapper.unmount()
+  })
+
+  it('上传中禁止保存，客户切换后忽略旧客户上传结果', async () => {
+    const wrapper = await setup()
+    await wrapper.get('button').trigger('click')
+    const state = (wrapper.vm.$ as unknown as { setupState: FormState }).setupState
+    state.form.settlementMode = 'DIRECT_PAID'
+    await flushPromises()
+    let complete!: (file: { fileId: string; fileName: string }) => void
+    mocks.upload.mockReturnValue(new Promise(resolve => { complete = resolve }))
+    await upload(wrapper, '旧客户.png')
+    expect(wrapper.findAll('button').find(b => b.text() === '保存')!.attributes('disabled')).toBeDefined()
+    state.form.customerId = '12'
+    complete({ fileId: '91', fileName: '旧客户.png' })
+    await flushPromises()
+    expect(wrapper.text()).not.toContain('旧客户.png')
+    wrapper.unmount()
+  })
+
+  it('只读列表能查看已保存的待审核凭证，并在关闭时释放预览资源', async () => {
+    mocks.fees.mockResolvedValue([{ sourceFeeId: '81', customerId: '11', amount: 10, reviewStatus: 'PENDING', paymentVoucherFileIds: ['91'] }])
+    const wrapper = await setup(true)
+    await wrapper.findAll('button').find(b => b.text() === '付款凭证 1')!.trigger('click')
+    await flushPromises()
+    expect(mocks.metadata).toHaveBeenCalledWith('11', '91')
+    expect(mocks.download).toHaveBeenCalledWith('11', '91')
+    expect(wrapper.get('img').attributes('src')).toBe('blob:voucher')
+    expect(wrapper.get('a[download]').attributes('download')).toBe('付款.png')
+    wrapper.unmount()
+    expect(URL.revokeObjectURL).toHaveBeenCalledWith('blob:voucher')
+  })
+})
diff --git a/src/modules/container-loading/components/ContainerLastLegFeesPanel.vue b/src/modules/container-loading/components/ContainerLastLegFeesPanel.vue
new file mode 100644
index 00000000..bd0e05d7
--- /dev/null
+++ b/src/modules/container-loading/components/ContainerLastLegFeesPanel.vue
@@ -0,0 +1,207 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, onBeforeUnmount, reactive, ref, watch } from 'vue'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import { getFinancePaymentVoucher, downloadFinancePaymentVoucher } from '@/modules/finance'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { getApiErrorDetails, getApiErrorMessage, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { listContainerFeeSupplierOptions, uploadContainerFeePaymentVoucher, type ContainerFeePaymentMethod, type ContainerFeeSettlementMode, type ContainerFeeSupplierOption } from '@/modules/loading-lists'
+import { adjustOverseasContainerFee, createOverseasContainerFee, listOverseasContainerCustomers, listOverseasContainerFees, reviewOverseasContainerFee, submitOverseasContainerFee, voidOverseasContainerFee, type OverseasContainerCustomer, type OverseasContainerFeeDirection, type OverseasContainerFeeItem, type OverseasContainerFeeSaveRequest, type OverseasContainerFeeSource } from '../api/overseasContainerFees'
+
+const props = withDefaults(defineProps<{ title?: string; containerBookingId: string; containerNo: string | null; readonly?: boolean }>(), { title: '目的港及海外段费用（尾程）', readonly: false })
+const access = useAccessPreviewStore()
+const rows = ref<OverseasContainerFeeSource[]>([])
+const customers = ref<OverseasContainerCustomer[]>([])
+const suppliers = ref<ContainerFeeSupplierOption[]>([])
+const loading = ref(false)
+const actionLoading = ref(false)
+const voucherUploading = ref(false)
+const voucherInput = ref<HTMLInputElement | null>(null)
+const voucherNames = reactive<Record<string, string>>({})
+let uploadSequence = 0
+let previewSequence = 0
+const previewOpen = ref(false)
+const previewLoading = ref(false)
+const previewError = ref<ApiErrorDetails | null>(null)
+const previewUrl = ref('')
+const previewName = ref('付款凭证')
+const previewIsImage = ref(false)
+function clearPreview() {
+  previewSequence++
+  if (previewUrl.value) URL.revokeObjectURL(previewUrl.value)
+  previewUrl.value = ''
+}
+async function previewVoucher(customerId: string, fileId: string) {
+  clearPreview()
+  const sequence = previewSequence
+  previewOpen.value = true; previewLoading.value = true; previewError.value = null
+  previewName.value = voucherNames[fileId] || '付款凭证'
+  try {
+    const metadata = await getFinancePaymentVoucher(customerId, fileId)
+    const blob = await downloadFinancePaymentVoucher(customerId, fileId)
+    if (sequence !== previewSequence) return
+    previewName.value = metadata.fileName || '付款凭证'
+    voucherNames[fileId] = previewName.value
+    previewIsImage.value = ['image/jpeg', 'image/png', 'image/gif', 'image/webp', 'image/bmp'].includes(metadata.contentType)
+    previewUrl.value = URL.createObjectURL(new Blob([blob], { type: previewIsImage.value ? metadata.contentType : 'application/octet-stream' }))
+  } catch (cause) {
+    if (sequence === previewSequence) previewError.value = getApiErrorDetails(cause, '付款凭证读取失败')
+  } finally {
+    if (sequence === previewSequence) previewLoading.value = false
+  }
+}
+watch(previewOpen, (open) => { if (!open) clearPreview() })
+onBeforeUnmount(() => { uploadSequence++; clearPreview() })
+const error = ref<ApiErrorDetails | null>(null)
+const dialogOpen = ref(false)
+const editing = ref<OverseasContainerFeeSource | null>(null)
+const canView = computed(() => access.can('platform:finance:customer-arap:list'))
+const canEdit = computed(() => !props.readonly && access.can('platform:finance:fee-source:edit'))
+const canReview = computed(() => !props.readonly && access.can('platform:finance:fee-source:review'))
+const feeItems: Array<{ value: OverseasContainerFeeItem; label: string }> = [
+  { value: 'PORT_FEE', label: '港口费' }, { value: 'STORAGE_FEE', label: '堆存费' },
+  { value: 'CONTAINER_REPAIR_FEE', label: '修箱费' }, { value: 'CRANE_FEE', label: '吊机费' },
+  { value: 'TERMINAL_DRAYAGE_FEE', label: '码头拖车费' }, { value: 'OTHER', label: '其他' },
+]
+const feeItemLabel = (value: string) => feeItems.find((item) => item.value === value)?.label || value
+const reviewLabels: Record<string, string> = { DRAFT: '草稿', PENDING: '待审核', APPROVED: '已审核', REJECTED: '已驳回' }
+const form = reactive<{ customerId: string; feeItemCode: OverseasContainerFeeItem; direction: OverseasContainerFeeDirection; businessDate: string; amount: number | null; supplierId: string; settlementMode: ContainerFeeSettlementMode; paidAt: string; paymentMethod: ContainerFeePaymentMethod; paymentReferenceNo: string; paymentVoucherFileIds: string[] }>({ customerId: '', feeItemCode: 'PORT_FEE', direction: 'PAYABLE', businessDate: new Date().toISOString().slice(0, 10), amount: null, supplierId: '', settlementMode: 'ON_ACCOUNT', paidAt: '', paymentMethod: 'BANK_TRANSFER', paymentReferenceNo: '', paymentVoucherFileIds: [] })
+
+watch(() => form.customerId, () => { uploadSequence++; voucherUploading.value = false; form.paymentVoucherFileIds = [] }, { flush: 'sync' })
+watch(dialogOpen, (open) => { if (!open) { uploadSequence++; voucherUploading.value = false } }, { flush: 'sync' })
+function key(scope: string) { return `${scope}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}` }
+function customerName(customerId: string) { return customers.value.find((item) => item.customerId === customerId)?.customerName || null }
+function selectedSupplier() { return suppliers.value.find((item) => item.id === form.supplierId) || null }
+function saveRequest(row?: OverseasContainerFeeSource): OverseasContainerFeeSaveRequest {
+  const item = feeItems.find((option) => option.value === form.feeItemCode)
+  return {
+    customerId: form.customerId, customerName: customerName(form.customerId), sourceType: 'OVERSEAS_CONTAINER_FEE', businessType: 'OVERSEAS_CONTAINER',
+    businessId: props.containerBookingId, businessNo: props.containerNo || '', orderId: null, inboundId: null, inboundCode: null, containerId: null,
+    containerBookingId: props.containerBookingId, containerNo: props.containerNo || '', warehouseId: null,
+    feeItemCode: form.feeItemCode, feeItemName: item?.label || row?.feeItemName || form.feeItemCode, direction: form.direction,
+    supplierId: form.direction === 'PAYABLE' ? selectedSupplier()?.id || null : null,
+    supplierName: form.direction === 'PAYABLE' ? selectedSupplier()?.supplierName || null : null,
+    supplierCategory: form.direction === 'PAYABLE' ? selectedSupplier()?.category || null : null,
+    settlementMode: form.direction === 'PAYABLE' ? form.settlementMode : null,
+    paidAt: form.direction === 'PAYABLE' && form.settlementMode === 'DIRECT_PAID' ? form.paidAt || null : null,
+    paymentMethod: form.direction === 'PAYABLE' && form.settlementMode === 'DIRECT_PAID' ? form.paymentMethod : null,
+    paymentReferenceNo: form.direction === 'PAYABLE' && form.settlementMode === 'DIRECT_PAID' ? form.paymentReferenceNo.trim() || null : null,
+    paymentVoucherFileIds: form.direction === 'PAYABLE' && form.settlementMode === 'DIRECT_PAID' && form.paymentVoucherFileIds.length ? form.paymentVoucherFileIds : null,
+    businessDate: form.businessDate, currency: 'CNY', amount: Number(form.amount),
+  }
+}
+async function load() {
+  if (!canView.value) return
+  loading.value = true; error.value = null
+  try { [rows.value, customers.value, suppliers.value] = await Promise.all([listOverseasContainerFees(props.containerBookingId), listOverseasContainerCustomers(props.containerBookingId), canEdit.value && access.can('platform:supplier:list') ? listContainerFeeSupplierOptions(null) : Promise.resolve([])]) }
+  catch (cause) { error.value = getApiErrorDetails(cause, '尾程计费加载失败') }
+  finally { loading.value = false }
+}
+function openCreate() {
+  editing.value = null; form.customerId = customers.value[0]?.customerId || ''; form.feeItemCode = 'PORT_FEE'; form.direction = 'PAYABLE'; form.businessDate = new Date().toISOString().slice(0, 10); form.amount = null; form.supplierId = ''; form.settlementMode = 'ON_ACCOUNT'; form.paidAt = ''; form.paymentMethod = 'BANK_TRANSFER'; form.paymentReferenceNo = ''; form.paymentVoucherFileIds = []; dialogOpen.value = true
+}
+function openAdjust(row: OverseasContainerFeeSource) {
+  editing.value = row; form.customerId = row.customerId; form.feeItemCode = row.feeItemCode; form.direction = row.direction; form.businessDate = row.businessDate; form.amount = row.amount; form.supplierId = row.supplierId || ''; form.settlementMode = row.settlementMode === 'DIRECT_PAID' ? 'DIRECT_PAID' : 'ON_ACCOUNT'; form.paidAt = row.paidAt || ''; form.paymentMethod = (row.paymentMethod as ContainerFeePaymentMethod) || 'BANK_TRANSFER'; form.paymentReferenceNo = row.paymentReferenceNo || ''; form.paymentVoucherFileIds = [...row.paymentVoucherFileIds]; dialogOpen.value = true
+}
+async function mutate(task: () => Promise<unknown>, success: string) {
+  actionLoading.value = true
+  try { await task(); ElMessage.success(success); dialogOpen.value = false; await load() }
+  catch (cause) { ElMessage.error(getApiErrorMessage(cause, '尾程计费操作失败')) }
+  finally { actionLoading.value = false }
+}
+async function save() {
+  if (voucherUploading.value || actionLoading.value) return
+  if (!form.customerId || !form.businessDate || !form.amount || form.amount <= 0) return ElMessage.warning('请完整填写客户、业务日期和大于 0 的金额')
+  if (!props.containerNo) return ElMessage.warning('请先补录真实集装箱号后再维护尾程费用')
+  if (form.direction === 'PAYABLE' && !selectedSupplier()) return ElMessage.warning('应付费用必须选择供应商')
+  if (form.direction === 'PAYABLE' && form.settlementMode === 'DIRECT_PAID' && (!form.paidAt || !form.paymentMethod || (!form.paymentReferenceNo.trim() && form.paymentVoucherFileIds.length === 0))) return ElMessage.warning('直接已付必须填写付款时间、方式，并提供流水号或付款凭证')
+  const payload = saveRequest(editing.value || undefined)
+  if (editing.value) await mutate(() => adjustOverseasContainerFee(editing.value!.sourceFeeId, editing.value!.sourceVersion, payload, key('container-fee-adjust')), '费用调整已提交审核')
+  else await mutate(() => createOverseasContainerFee(payload, key('container-fee-create')), '费用草稿已创建')
+}
+async function uploadVoucher(event: Event) {
+  const input = event.target as HTMLInputElement
+  const file = input.files?.[0]
+  input.value = ''
+  if (!file || voucherUploading.value) return
+  if (!form.customerId) { ElMessage.warning('请先选择费用所属客户'); return }
+  const customerId = form.customerId
+  const sequence = ++uploadSequence
+  voucherUploading.value = true
+  try {
+    const uploaded = await uploadContainerFeePaymentVoucher(customerId, file)
+    if (sequence !== uploadSequence) return
+    form.paymentVoucherFileIds = [uploaded.fileId]
+    voucherNames[uploaded.fileId] = uploaded.fileName || file.name
+    ElMessage.success('付款凭证已上传')
+  } catch (cause) {
+    if (sequence === uploadSequence) ElMessage.error(getApiErrorMessage(cause, '付款凭证上传失败'))
+  } finally {
+    if (sequence === uploadSequence) voucherUploading.value = false
+  }
+}
+async function submit(row: OverseasContainerFeeSource) {
+  await ElMessageBox.confirm(`确认提交“${row.feeItemName}”审核？`, '提交费用', { customClass: 'admin-density-confirm', type: 'warning' })
+  await mutate(() => submitOverseasContainerFee(row.sourceFeeId, key('container-fee-submit')), '费用已提交审核')
+}
+async function review(row: OverseasContainerFeeSource, decision: 'APPROVE' | 'REJECT') {
+  let reason: string | null = null
+  if (decision === 'REJECT') { const result = await ElMessageBox.prompt('请输入驳回原因', '驳回费用', { customClass: 'admin-density-confirm', inputPattern: /\S+/, inputErrorMessage: '请输入驳回原因', type: 'warning' }); reason = result.value.trim() }
+  else await ElMessageBox.confirm(`确认审核通过“${row.feeItemName}”？`, '审核费用', { customClass: 'admin-density-confirm', type: 'warning' })
+  await mutate(() => reviewOverseasContainerFee(row.sourceFeeId, decision, reason, key('container-fee-review')), decision === 'APPROVE' ? '费用已审核通过' : '费用已驳回')
+}
+async function voidFee(row: OverseasContainerFeeSource) {
+  const result = await ElMessageBox.prompt('请输入作废原因', '作废费用', { customClass: 'admin-density-confirm', inputPattern: /\S+/, inputErrorMessage: '请输入作废原因', type: 'warning' })
+  await mutate(() => voidOverseasContainerFee(row.sourceFeeId, row.sourceVersion, result.value.trim(), key('container-fee-void')), '费用已作废')
+}
+onMounted(load)
+</script>
+
+<template>
+  <div class="last-leg-fees admin-density">
+    <header class="last-leg-fees__header"><div><h2>{{ title }}</h2><p>按真实货柜展示港口、堆存、修箱、吊机和码头拖车费用，金额按币种分别列示。</p></div><el-button v-if="canEdit" type="primary" :disabled="!containerNo || customers.length === 0" @click="openCreate">新增费用</el-button></header>
+    <el-alert v-if="canView && !canEdit && !canReview" type="info" :closable="false" title="当前账号仅有海外段费用查看权限。" />
+    <el-alert v-if="!containerNo" type="warning" :closable="false" title="当前货柜尚未补录真实集装箱号，暂不能新增尾程费用。" />
+    <el-alert v-if="!canView" type="warning" :closable="false" title="当前账号无权查看尾程计费。" />
+    <LoadErrorState v-else-if="error" title="尾程计费加载失败" :message="error.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="error" /></template></LoadErrorState>
+    <el-table v-else v-loading="loading" :data="rows" empty-text="当前货柜暂无尾程费用">
+      <el-table-column label="操作" fixed="left" width="240"><template #default="{ row }"><div class="row-actions density-actions"><el-button data-tone="primary" class="density-action" v-if="canEdit && row.sourceStatus === 'ACTIVE' && ['DRAFT', 'REJECTED'].includes(row.reviewStatus)" type="primary" @click="submit(row as OverseasContainerFeeSource)">提交</el-button><el-button data-tone="warning" class="density-action" v-if="canReview && row.sourceStatus === 'ACTIVE' && row.reviewStatus === 'PENDING'" type="success" @click="review(row as OverseasContainerFeeSource, 'APPROVE')">通过</el-button><el-button data-tone="danger" class="density-action" v-if="canReview && row.sourceStatus === 'ACTIVE' && row.reviewStatus === 'PENDING'" type="danger" @click="review(row as OverseasContainerFeeSource, 'REJECT')">驳回</el-button><el-button class="density-action" v-if="canEdit && row.sourceStatus === 'ACTIVE' && row.reviewStatus === 'APPROVED'" type="primary" @click="openAdjust(row as OverseasContainerFeeSource)">调整</el-button><el-button data-tone="danger" class="density-action" v-if="canReview && row.sourceStatus === 'ACTIVE' && row.reviewStatus === 'APPROVED'" type="danger" @click="voidFee(row as OverseasContainerFeeSource)">作废</el-button><span v-if="row.sourceStatus !== 'ACTIVE' || (!canEdit && !canReview)">—</span></div></template></el-table-column>
+      <el-table-column prop="customerName" label="客户" min-width="160" show-overflow-tooltip><template #default="{ row }">{{ row.customerName || '—' }}</template></el-table-column>
+      <el-table-column prop="feeItemCode" label="费用项目" min-width="140" show-overflow-tooltip><template #default="{ row }">{{ feeItemLabel(row.feeItemCode) }}</template></el-table-column>
+      <el-table-column prop="direction" label="方向" width="100"><template #default="{ row }">{{ row.direction === 'RECEIVABLE' ? '应收' : '应付' }}</template></el-table-column>
+      <el-table-column prop="supplierName" label="供应商" min-width="150" show-overflow-tooltip><template #default="{ row }">{{ row.supplierName || '—' }}</template></el-table-column>
+      <el-table-column prop="amount" label="金额" min-width="130" align="right"><template #default="{ row }">¥{{ row.amount.toFixed(2) }}</template></el-table-column>
+      <el-table-column label="付款凭证" min-width="180"><template #default="{ row }"><div v-if="row.paymentVoucherFileIds.length" class="voucher-list"><el-button v-for="(fileId, index) in (row.paymentVoucherFileIds as string[])" :key="fileId" link type="primary" @click="previewVoucher(row.customerId, fileId)">{{ voucherNames[fileId] || `付款凭证 ${index + 1}` }}</el-button></div><span v-else>—</span></template></el-table-column>
+      <el-table-column prop="businessDate" label="业务日期" width="120" />
+      <el-table-column prop="reviewStatus" label="审核状态" width="110"><template #default="{ row }"><el-tag>{{ reviewLabels[row.reviewStatus] || row.reviewStatus }}</el-tag></template></el-table-column>
+      <el-table-column prop="reviewReason" label="审核说明" min-width="180" show-overflow-tooltip><template #default="{ row }">{{ row.reviewReason || '—' }}</template></el-table-column>
+    </el-table>
+    <AppDialog class="admin-density-dialog" v-model="dialogOpen" :title="editing ? '调整尾程费用' : '新增尾程费用'" width="min(620px, calc(100vw - 28px))" confirm-text="保存" :confirm-loading="actionLoading" :confirm-disabled="voucherUploading" @confirm="save">
+      <el-form class="density-form" label-position="top"><div class="fee-form-grid"><el-form-item label="客户" required><el-select v-model="form.customerId" :disabled="Boolean(editing) || voucherUploading" placeholder="请选择柜内客户"><el-option v-for="customer in customers" :key="customer.customerId" :label="customer.customerName || '未命名客户'" :value="customer.customerId" /></el-select></el-form-item><el-form-item label="费用项目" required><el-select v-model="form.feeItemCode"><el-option v-for="item in feeItems" :key="item.value" :label="item.label" :value="item.value" /></el-select></el-form-item><el-form-item label="费用方向" required><el-select v-model="form.direction"><el-option label="应收" value="RECEIVABLE" /><el-option label="应付" value="PAYABLE" /></el-select></el-form-item><el-form-item label="业务日期" required><el-date-picker v-model="form.businessDate" type="date" value-format="YYYY-MM-DD" /></el-form-item><el-form-item label="金额（CNY）" required><el-input-number v-model="form.amount" :min="0.01" :precision="2" :step="10" placeholder="请输入费用金额" /></el-form-item><template v-if="form.direction === 'PAYABLE'"><el-form-item label="供应商" required><el-select v-model="form.supplierId" filterable placeholder="请选择有效供应商"><el-option v-for="supplier in suppliers" :key="supplier.id" :label="supplier.supplierName" :value="supplier.id" /></el-select></el-form-item><el-form-item label="结算方式" required><el-select v-model="form.settlementMode"><el-option label="账期结算" value="ON_ACCOUNT" /><el-option label="直接已付" value="DIRECT_PAID" /></el-select></el-form-item><template v-if="form.settlementMode === 'DIRECT_PAID'"><el-form-item label="付款时间" required><el-date-picker v-model="form.paidAt" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" /></el-form-item><el-form-item label="付款方式" required><el-select v-model="form.paymentMethod"><el-option label="线上支付" value="ONLINE" /><el-option label="银行转账" value="BANK_TRANSFER" /><el-option label="现金" value="CASH" /><el-option label="其他" value="OTHER" /></el-select></el-form-item><el-form-item label="付款流水号"><el-input v-model="form.paymentReferenceNo" maxlength="128" placeholder="请输入付款流水号（可选）" /></el-form-item><el-form-item label="付款凭证"><div class="voucher-list"><input ref="voucherInput" type="file" accept="image/*" hidden @change="uploadVoucher" /><el-button :loading="voucherUploading" :disabled="!form.customerId || actionLoading" @click="voucherInput?.click()">{{ form.paymentVoucherFileIds.length ? '重新上传凭证' : '上传付款凭证' }}</el-button><div v-for="(fileId, index) in form.paymentVoucherFileIds" :key="fileId" class="voucher-item"><el-button link type="primary" @click="previewVoucher(form.customerId, fileId)">{{ voucherNames[fileId] || `付款凭证 ${index + 1}` }}</el-button><el-button link type="danger" :disabled="voucherUploading || actionLoading" @click="form.paymentVoucherFileIds = form.paymentVoucherFileIds.filter((id) => id !== fileId)">移除</el-button></div></div></el-form-item></template></template></div></el-form>
+    </AppDialog>
+    <AppDialog class="admin-density-dialog" v-model="previewOpen" :title="previewName" width="min(900px, calc(100vw - 28px))" :show-confirm="false" cancel-text="关闭" append-to-body>
+      <p v-if="previewLoading">正在读取付款凭证…</p>
+      <div v-else-if="previewError"><el-alert type="error" :closable="false" :title="previewError.message" /><ApiErrorMeta :details="previewError" /></div>
+      <div v-else-if="previewUrl" class="voucher-preview"><img v-if="previewIsImage" :src="previewUrl" :alt="previewName" /><p v-else>此文件暂不支持预览，请下载后查看。</p><a :href="previewUrl" :download="previewName">下载付款凭证</a></div>
+    </AppDialog>
+  </div>
+</template>
+
+<style scoped>
+.last-leg-fees { display: grid; gap: var(--admin-space-5); min-width: 0; }
+.last-leg-fees__header { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-6); }
+.last-leg-fees__header h2 { margin: 0; color: #253553; font-size: var(--admin-font-section); }
+.last-leg-fees__header p { margin: var(--admin-space-2) 0 0; color: #77839b; }
+.voucher-list { display: flex; flex-direction: column; align-items: flex-start; gap: var(--admin-space-3); min-width: 0; }
+.voucher-item { display: flex; gap: var(--admin-space-3); max-width: 100%; }
+.voucher-list :deep(.el-button) { white-space: normal; overflow-wrap: anywhere; margin-left: 0; }
+.voucher-preview { display: grid; gap: var(--admin-space-5); }
+.voucher-preview img { max-width: 100%; max-height: 65vh; object-fit: contain; margin: auto; }
+.row-actions { white-space: nowrap; }
+.fee-form-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 0 var(--admin-space-5); }
+.fee-form-grid :deep(.el-select), .fee-form-grid :deep(.el-date-editor), .fee-form-grid :deep(.el-input-number) { width: 100%; }
+@media (max-width: 760px) { .last-leg-fees__header { align-items: flex-start; flex-direction: column; } .fee-form-grid { grid-template-columns: 1fr; } }
+</style>
diff --git a/src/modules/container-loading/components/ContainerOverviewPanel.test.ts b/src/modules/container-loading/components/ContainerOverviewPanel.test.ts
new file mode 100644
index 00000000..4f06b632
--- /dev/null
+++ b/src/modules/container-loading/components/ContainerOverviewPanel.test.ts
@@ -0,0 +1,175 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { flushPromises, mount } from '@vue/test-utils'
+import ElementPlus from 'element-plus'
+import ContainerOverviewPanel from './ContainerOverviewPanel.vue'
+import type { ContainerOverview } from '../types'
+import { downloadContainerPdaPhoto } from '../api/platformContainerLoading'
+
+vi.mock('../api/platformContainerLoading', () => ({ downloadContainerPdaPhoto: vi.fn() }))
+
+const overview: ContainerOverview = {
+  container: { id: '7', bookingNo: 'BK-1', cabinetNo: 'CB-1', containerNo: 'MSCU-1', status: 'LOADING', warehouseId: '8', warehouseName: '义乌仓', voyageNo: 'V1', vesselName: '船一', pickupCode: '00123456', pickupCodeUpdatedBy: '13', pickupCodeUpdatedByName: '操作员', pickupCodeUpdatedAt: '2026-08-13T10:30:00', version: 2 },
+  loadingPlanId: '9',
+  pda: { taskId: '10', loadingPlanId: '9', containerBookingId: '7', taskStatus: 'IN_PROGRESS', workflowStatus: 'AWAITING_REVIEW', taskVersion: 2, itemCount: 4, completedItemCount: 4, unresolvedItemCount: 0, photoCounts: [{ evidenceType: 'PHOTO_STEP_EMPTY_CONTAINER', count: 2 }], photos: [{ evidenceId: '20', tenantId: '21', inboundId: '22', evidenceType: 'PHOTO_STEP_EMPTY_CONTAINER', fileId: '23', fileName: 'empty.jpg', status: 'ACTIVE', downloadPath: '/api/platform/v1/containers/7/pda/photos/23/download', uploadedAt: '2026-08-13T12:30:00' }], exceptionReasons: ['一项待复核'] },
+  documents: [{ id: '11', documentType: 'DELIVERY_ORDER', fileId: '9007199254740999', fileName: 'do.pdf', fileHash: null, uploadedBy: '13', uploadedByName: '操作员', uploadedAt: '2026-08-13T10:00:00', version: 1, completed: false }],
+  exception: { active: true, reason: '码头查验', markedBy: '13', markedByName: '操作员', markedAt: '2026-08-13T11:00:00' },
+  exceptionHistory: [{ id: '14', action: 'MARK', reason: '码头查验', operatorId: '13', operatorName: '操作员', occurredAt: '2026-08-13T11:00:00' }],
+  timeline: [{ eventType: 'TRANSPORT_UPDATE', detail: '更新预计到港时间', operatorId: '13', operatorName: '操作员', occurredAt: '2026-08-13T12:00:00' }],
+}
+
+describe('ContainerOverviewPanel', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.mocked(downloadContainerPdaPhoto).mockResolvedValue(new Blob(['photo']))
+    Object.defineProperty(URL, 'createObjectURL', { configurable: true, value: vi.fn(() => 'blob:container-photo') })
+    Object.defineProperty(URL, 'revokeObjectURL', { configurable: true, value: vi.fn() })
+  })
+
+  it('renders documents, PDA progress, exception history and timeline from the aggregate DTO', async () => {
+    const wrapper = mount(ContainerOverviewPanel, { props: { overview, canManageDocuments: true, canManageCustoms: true, canManageException: true }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(wrapper.text()).toContain('DO 资料')
+    expect(wrapper.text()).toContain('do.pdf')
+    expect(wrapper.text()).toContain('PDA 作业进度')
+    expect(wrapper.text()).toContain('待人工复核')
+    expect(wrapper.text()).toContain('空柜照片')
+    expect(wrapper.text()).not.toContain('PHOTO_STEP_EMPTY_CONTAINER')
+    expect(wrapper.text()).toContain('一项待复核')
+    expect(wrapper.text()).toContain('码头查验')
+    expect(wrapper.text()).not.toContain('更新预计到港时间')
+  })
+
+  it('emits stable document types and does not expose file ids in visible text', async () => {
+    const wrapper = mount(ContainerOverviewPanel, { props: { overview, canManageDocuments: true, canManageCustoms: true, canManageException: true }, global: { plugins: [ElementPlus] } })
+    const updateButton = wrapper.findAll('button').find((button) => button.text().includes('更新'))!
+    await updateButton.trigger('click')
+    expect(wrapper.emitted('uploadDocument')?.[0]).toEqual(['DELIVERY_ORDER'])
+    expect(wrapper.text()).not.toContain('9007199254740999')
+  })
+
+  it('shows the channel restriction and suppresses DO uploads when the document is not applicable', () => {
+    const withoutDo = { ...overview, documents: overview.documents.filter((item) => item.documentType !== 'DELIVERY_ORDER') }
+    const wrapper = mount(ContainerOverviewPanel, { props: { overview: withoutDo, canManageDocuments: true, canManageCustoms: true, canManageException: true, deliveryOrderBlockedReason: '海铁渠道不适用 DO 资料' }, global: { plugins: [ElementPlus] } })
+    const deliveryRow = wrapper.findAll('.document-table tbody tr').find((row) => row.text().includes('DO 资料'))!
+    expect(deliveryRow.text()).toContain('海铁渠道不适用 DO 资料')
+    expect(deliveryRow.find('button').exists()).toBe(false)
+  })
+
+  it('renders two file rows and one inline PU code row without a nested heading', async () => {
+    const wrapper = mount(ContainerOverviewPanel, { props: { overview, canManageDocuments: true, canManageCustoms: true, canManageException: true }, global: { plugins: [ElementPlus] } })
+    const headers = wrapper.findAll('.document-table thead th').map((cell) => cell.text())
+    expect(headers).toEqual(['操作', '资料类型', '资料内容', '更新人', '更新时间', '状态'])
+    expect(wrapper.findAll('.document-table tbody tr')).toHaveLength(3)
+    expect(wrapper.findAll('.document-item')).toHaveLength(0)
+    expect(wrapper.find('.document-table-wrap').exists()).toBe(true)
+    expect(wrapper.text()).not.toContain('业务资料')
+    const pickupInput = wrapper.find('input[aria-label="PU码"]')
+    expect((pickupInput.element as HTMLInputElement).value).toBe('00123456')
+    await pickupInput.setValue('998877')
+    await wrapper.find('.pickup-code-row button').trigger('click')
+    expect(wrapper.emitted('savePickupCode')?.[0]).toEqual(['998877'])
+    const deliveryRow = wrapper.findAll('.document-table tbody tr').find((row) => row.text().includes('DO 资料'))!
+    expect(deliveryRow.text()).toContain('do.pdf')
+    expect(deliveryRow.text()).toContain('操作员')
+    expect(deliveryRow.text()).toContain('2026-08-13 10:00')
+    expect(deliveryRow.text()).toContain('已上传')
+    expect(deliveryRow.find('.document-file-name').attributes('title')).toBe('do.pdf')
+  })
+
+  it('renders one compact normal exception section with a single-line empty history', () => {
+    const normal = { ...overview, exception: { active: false, reason: null, markedBy: null, markedByName: null, markedAt: null }, exceptionHistory: [] }
+    const wrapper = mount(ContainerOverviewPanel, { props: { overview: normal, canManageDocuments: true, canManageCustoms: true, canManageException: true }, global: { plugins: [ElementPlus] } })
+    const section = wrapper.find('.exception-management')
+    expect(section.text()).toContain('异常管理')
+    expect(section.text()).toContain('正常')
+    expect(section.text()).toContain('标记异常')
+    expect(section.text()).toContain('暂无异常处理记录')
+    expect(section.find('.el-empty').exists()).toBe(false)
+    expect(wrapper.findAll('[aria-label="异常管理"]')).toHaveLength(1)
+  })
+
+  it('keeps current exception summary and multiple history rows together without mixing transport logs', () => {
+    const histories = [
+      ...overview.exceptionHistory,
+      { id: '15', action: 'CANCEL', reason: '查验解除', operatorId: '16', operatorName: '复核员', occurredAt: '2026-08-13T11:30:00' },
+    ]
+    const wrapper = mount(ContainerOverviewPanel, { props: { overview: { ...overview, exceptionHistory: histories }, canManageDocuments: true, canManageCustoms: true, canManageException: true }, global: { plugins: [ElementPlus] } })
+    const section = wrapper.find('.exception-management')
+    expect(section.text()).toContain('异常')
+    expect(section.text()).toContain('码头查验')
+    expect(section.text()).toContain('操作员 · 2026-08-13 11:00')
+    expect(section.findAll('.exception-history li')).toHaveLength(2)
+    expect(section.text()).toContain('取消异常')
+    expect(section.text()).toContain('复核员')
+    expect(section.text()).toContain('查验解除')
+    expect(section.text()).not.toContain('更新预计到港时间')
+    expect(wrapper.find('[aria-label="运输轨迹和操作日志"]').exists()).toBe(false)
+  })
+
+  it('emits the unchanged manage action for mark and cancel buttons', async () => {
+    let wrapper = mount(ContainerOverviewPanel, { props: { overview: { ...overview, exception: { active: false, reason: null, markedBy: null, markedByName: null, markedAt: null } }, canManageDocuments: true, canManageCustoms: true, canManageException: true }, global: { plugins: [ElementPlus] } })
+    await wrapper.find('.exception-management button').trigger('click')
+    expect(wrapper.emitted('manageException')).toHaveLength(1)
+    wrapper.unmount()
+    wrapper = mount(ContainerOverviewPanel, { props: { overview, canManageDocuments: true, canManageCustoms: true, canManageException: true }, global: { plugins: [ElementPlus] } })
+    await wrapper.find('.exception-management button').trigger('click')
+    expect(wrapper.emitted('manageException')).toHaveLength(1)
+    expect(wrapper.find('.exception-management button').text()).toContain('取消异常')
+    wrapper.unmount()
+  })
+
+  it('loads protected photos into direct thumbnails, opens them and revokes object URLs', async () => {
+    const open = vi.spyOn(window, 'open').mockImplementation(() => null)
+    const wrapper = mount(ContainerOverviewPanel, { props: { overview, canManageDocuments: true, canManageCustoms: true, canManageException: true }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(downloadContainerPdaPhoto).toHaveBeenCalledWith('/api/platform/v1/containers/7/pda/photos/23/download')
+    expect(wrapper.find('img[src="blob:container-photo"]').exists()).toBe(true)
+    await wrapper.find('button[aria-label="预览装柜照片 empty.jpg"]').trigger('click')
+    expect(open).toHaveBeenCalledWith('blob:container-photo', '_blank', 'noopener,noreferrer')
+    wrapper.unmount()
+    expect(URL.revokeObjectURL).toHaveBeenCalledWith('blob:container-photo')
+  })
+
+  it('revokes old thumbnail URLs when the overview photos change', async () => {
+    const wrapper = mount(ContainerOverviewPanel, { props: { overview, canManageDocuments: true, canManageCustoms: true, canManageException: true }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    const changed = { ...overview.pda!.photos[0], evidenceId: '22', fileId: '25', fileName: 'next.jpg', downloadPath: '/api/platform/v1/containers/7/pda/photos/25/download' }
+    await wrapper.setProps({ overview: { ...overview, pda: { ...overview.pda!, photos: [changed] } } })
+    await flushPromises()
+    expect(URL.revokeObjectURL).toHaveBeenCalledWith('blob:container-photo')
+    expect(downloadContainerPdaPhoto).toHaveBeenCalledWith('/api/platform/v1/containers/7/pda/photos/25/download')
+    wrapper.unmount()
+  })
+
+  it('isolates one thumbnail failure without blocking other photos', async () => {
+    const second = { ...overview.pda!.photos[0], evidenceId: '21', fileId: '24', fileName: 'seal.jpg', evidenceType: 'SEAL', downloadPath: '/api/platform/v1/containers/7/pda/photos/24/download' }
+    vi.mocked(downloadContainerPdaPhoto).mockResolvedValueOnce(new Blob(['photo'])).mockRejectedValueOnce(new Error('photo unavailable'))
+    const wrapper = mount(ContainerOverviewPanel, { props: { overview: { ...overview, pda: { ...overview.pda!, photos: [...overview.pda!.photos, second] } }, canManageDocuments: true, canManageCustoms: true, canManageException: true }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(wrapper.find('img[src="blob:container-photo"]').exists()).toBe(true)
+    expect(wrapper.text()).toContain('照片加载失败')
+    wrapper.unmount()
+  })
+
+  it('delegates warehouse events to the unified fulfillment timeline without exposing technical keys here', () => {
+    const longKey = 'pda-submit-1000001-2092438843630391297-2092437496092790785--0c642e80891d76a4-m9428-76'
+    const timeline = [
+      { eventType: 'PDA_CLAIM', detail: `claim-${longKey}`, operatorId: '1', operatorName: 'platform_admin', occurredAt: '2026-08-26T10:28:00' },
+      { eventType: 'PDA_BATCH', detail: longKey, operatorId: '1', operatorName: 'platform_admin', occurredAt: '2026-08-26T10:28:00' },
+      { eventType: 'PDA_COMPLETE_LOADING', detail: `complete-${longKey}`, operatorId: '1', operatorName: 'platform_admin', occurredAt: '2026-08-26T10:29:00' },
+    ]
+    const wrapper = mount(ContainerOverviewPanel, { props: { overview: { ...overview, pda: null, timeline }, canManageDocuments: true, canManageCustoms: true, canManageException: true }, global: { plugins: [ElementPlus] } })
+    expect(wrapper.text()).not.toContain('领取 PDA 任务')
+    expect(wrapper.text()).not.toContain('提交拣货结果')
+    expect(wrapper.text()).not.toContain('完成装柜')
+    expect(wrapper.text()).not.toContain(longKey)
+  })
+
+  it('renders a compact empty photo state without exposing credentials', () => {
+    const withoutPhotos = { ...overview, pda: overview.pda ? { ...overview.pda, photos: [] } : null }
+    const wrapper = mount(ContainerOverviewPanel, { props: { overview: withoutPhotos, canManageDocuments: false, canManageCustoms: false, canManageException: false }, global: { plugins: [ElementPlus] } })
+    expect(wrapper.text()).toContain('暂无可查看的有效照片')
+    expect(wrapper.text()).not.toContain('Authorization')
+  })
+
+})
diff --git a/src/modules/container-loading/components/ContainerOverviewPanel.vue b/src/modules/container-loading/components/ContainerOverviewPanel.vue
new file mode 100644
index 00000000..457e3ea5
--- /dev/null
+++ b/src/modules/container-loading/components/ContainerOverviewPanel.vue
@@ -0,0 +1,179 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onBeforeUnmount, reactive, ref, watch } from 'vue'
+import { TriangleAlert } from '@lucide/vue'
+import { getApiErrorDetails } from '@/shared/api/http'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import type { ContainerOverview, ContainerOverviewDocument, ContainerPdaPhoto } from '../types'
+import { downloadContainerPdaPhoto } from '../api/platformContainerLoading'
+
+const props = defineProps<{
+  overview: ContainerOverview
+  canManageDocuments: boolean
+  canManageCustoms: boolean
+  canManageException: boolean
+  documentBusy?: boolean
+  pickupCodeBusy?: boolean
+  deliveryOrderBlockedReason?: string | null
+  sections?: Array<'exception' | 'documents' | 'pda'>
+}>()
+
+const emit = defineEmits<{
+  uploadDocument: [documentType: string]
+  downloadDocument: [document: ContainerOverviewDocument]
+  savePickupCode: [pickupCode: string]
+  manageException: []
+}>()
+
+const documentTypes = [
+  { type: 'DESTINATION_CLEARANCE', label: '目的港清关资料' },
+  { type: 'DELIVERY_ORDER', label: 'DO 资料' },
+] as const
+
+const documentsByType = computed(() => new Map(props.overview.documents.map((item) => [item.documentType, item])))
+const containerDownloadableTypes = new Set(['DELIVERY_ORDER'])
+const pickupCodeInput = ref('')
+watch(() => props.overview.container.pickupCode, (value) => { pickupCodeInput.value = value || '' }, { immediate: true })
+const pickupCodeValid = computed(() => /^[0-9]{1,64}$/.test(pickupCodeInput.value))
+function canDownloadDocument(documentType: string) {
+  return containerDownloadableTypes.has(documentType)
+    || (documentType === 'DESTINATION_CLEARANCE' && props.canManageCustoms)
+}
+function canUploadDocument(documentType: string) {
+  if (documentType === 'DELIVERY_ORDER' && props.deliveryOrderBlockedReason) return false
+  return containerDownloadableTypes.has(documentType) ? props.canManageDocuments : documentType === 'DESTINATION_CLEARANCE' && props.canManageCustoms
+}
+function hasDocumentAction(documentType: string) {
+  const document = documentsByType.value.get(documentType)
+  return Boolean((document && canDownloadDocument(documentType)) || (canUploadDocument(documentType) && !document?.completed))
+}
+function documentStatusText(documentType: string) {
+  const document = documentsByType.value.get(documentType)
+  return document ? formatTime(document.uploadedAt) : '等待上传'
+}
+function documentStatusLabel(documentType: string) {
+  const document = documentsByType.value.get(documentType)
+  if (!document) return '未上传'
+  return document.completed ? '已完成' : '已上传'
+}
+function documentStatusType(documentType: string) {
+  const document = documentsByType.value.get(documentType)
+  if (!document) return 'info'
+  return document.completed ? 'success' : 'primary'
+}
+const pdaProgress = computed(() => {
+  const pda = props.overview.pda
+  if (!pda || pda.itemCount <= 0) return 0
+  return Math.min(100, Math.round((pda.completedItemCount / pda.itemCount) * 100))
+})
+const visibleSections = computed(() => new Set(props.sections || ['exception', 'documents', 'pda']))
+const activePhotos = computed(() => visibleSections.value.has('pda')
+  ? (props.overview.pda?.photos || []).filter((item) => item.status === 'ACTIVE' && item.downloadPath)
+  : [])
+const photoStates = reactive<Record<string, { loading: boolean; url: string | null; error: string | null }>>({})
+let photoGeneration = 0
+const workflowStatusLabels: Record<string, string> = {
+  LOADING: '作业中', AWAITING_REVIEW: '待人工复核', COMPLETED: '已完成',
+}
+const evidenceTypeLabels: Record<string, string> = {
+  PHOTO_STEP_EMPTY_CONTAINER: '空柜照片', PHOTO_STEP_HALF_LOADED: '半柜照片', PHOTO_STEP_FULL_CONTAINER: '满柜照片',
+  EMPTY_CONTAINER: '空柜照片', HALF_LOADED: '半柜照片', FULL_CONTAINER: '满柜照片', SEAL: '封条照片',
+}
+function workflowStatusLabel(workflowStatus: string | null | undefined, taskStatus: string) { return workflowStatusLabels[workflowStatus || taskStatus] || '作业状态待同步' }
+function evidenceTypeLabel(value: string) { return evidenceTypeLabels[value] || '装柜照片' }
+
+function formatTime(value: string | null | undefined) {
+  return value?.replace('T', ' ').slice(0, 16) || '—'
+}
+
+function eventLabel(value: string) {
+  return ({
+    MARK: '标记异常', CANCEL: '取消异常', TRANSPORT_UPDATE: '更新运输信息',
+    PDA_CLAIM: '领取 PDA 任务', PDA_BATCH: '提交拣货结果', PDA_COMPLETE_LOADING: '完成装柜',
+  } as Record<string, string>)[value] || value || '状态更新'
+}
+function revokePhotoUrls() {
+  Object.values(photoStates).forEach((state) => { if (state.url) URL.revokeObjectURL(state.url) })
+  Object.keys(photoStates).forEach((key) => delete photoStates[key])
+}
+async function loadPhotoThumbnails() {
+  const generation = ++photoGeneration
+  revokePhotoUrls()
+  await Promise.all(activePhotos.value.map(async (photo) => {
+    photoStates[photo.evidenceId] = { loading: true, url: null, error: null }
+    try {
+      const blob = await downloadContainerPdaPhoto(photo.downloadPath)
+      if (generation !== photoGeneration) return
+      photoStates[photo.evidenceId] = { loading: false, url: URL.createObjectURL(blob), error: null }
+    } catch (cause) {
+      if (generation !== photoGeneration) return
+      photoStates[photo.evidenceId] = { loading: false, url: null, error: getApiErrorDetails(cause, '照片加载失败').message }
+    }
+  }))
+}
+function openPhoto(photo: ContainerPdaPhoto) {
+  const url = photoStates[photo.evidenceId]?.url
+  if (url) window.open(url, '_blank', 'noopener,noreferrer')
+}
+watch(() => activePhotos.value.map((photo) => `${photo.evidenceId}:${photo.downloadPath}`).join('|'), () => void loadPhotoThumbnails(), { immediate: true })
+onBeforeUnmount(() => { photoGeneration += 1; revokePhotoUrls() })
+</script>
+
+<template>
+  <div class="overview-panel admin-density">
+    <section v-if="visibleSections.has('exception')" class="overview-section exception-management" aria-label="异常管理">
+      <header class="exception-management__header"><div><h3>异常管理</h3><p v-if="overview.exception.active" class="exception-current"><strong>{{ overview.exception.reason || '未填写异常原因' }}</strong><span>{{ overview.exception.markedByName || '操作人信息缺失' }} · {{ formatTime(overview.exception.markedAt) }}</span></p></div><div class="exception-management__actions"><StatusBadge :status="overview.exception.active ? '异常' : '正常'" /><el-button v-if="canManageException" :type="overview.exception.active ? 'primary' : 'danger'" plain @click="emit('manageException')"><TriangleAlert :size="16" />{{ overview.exception.active ? '取消异常' : '标记异常' }}</el-button></div></header>
+      <div class="exception-history"><div class="exception-history__head"><span>时间</span><span>动作</span><span>操作人</span><span>原因</span></div><p v-if="overview.exceptionHistory.length === 0" class="exception-history__empty">暂无异常处理记录</p><ol v-else><li v-for="history in overview.exceptionHistory" :key="history.id"><time>{{ formatTime(history.occurredAt) }}</time><strong>{{ eventLabel(history.action) }}</strong><span>{{ history.operatorName || '操作人信息缺失' }}</span><span :title="history.reason">{{ history.reason }}</span></li></ol></div>
+    </section>
+
+    <section v-if="visibleSections.has('documents')" class="overview-section overview-section--documents" aria-label="报关清关资料">
+      <div class="document-table-wrap">
+        <table class="document-table density-table">
+          <thead><tr><th class="document-table__actions">操作</th><th>资料类型</th><th>资料内容</th><th>更新人</th><th>更新时间</th><th>状态</th></tr></thead>
+          <tbody><tr v-for="item in documentTypes" :key="item.type">
+            <td class="document-table__actions"><div class="document-actions density-actions"><el-button class="density-action" v-if="documentsByType.get(item.type) && canDownloadDocument(item.type)" size="small" :loading="documentBusy" @click="emit('downloadDocument', documentsByType.get(item.type)!)">下载</el-button><el-button class="density-action" v-if="canUploadDocument(item.type) && !documentsByType.get(item.type)?.completed" size="small" @click="emit('uploadDocument', item.type)">{{ documentsByType.get(item.type) ? '更新附件' : '上传附件' }}</el-button><span v-if="!hasDocumentAction(item.type)" class="no-action">—</span></div></td>
+            <td><strong>{{ item.label }}</strong></td>
+            <td><span class="document-file-name" :title="documentsByType.get(item.type)?.fileName || undefined">{{ documentsByType.get(item.type)?.fileName || '—' }}</span><small v-if="item.type === 'DELIVERY_ORDER' && deliveryOrderBlockedReason" class="document-blocked-reason">{{ deliveryOrderBlockedReason }}</small></td>
+            <td>{{ documentsByType.get(item.type)?.uploadedByName || '—' }}</td>
+            <td>{{ documentsByType.get(item.type) ? formatTime(documentsByType.get(item.type)?.uploadedAt) : '—' }}</td>
+            <td><el-tag size="small" :type="documentStatusType(item.type)">{{ documentStatusLabel(item.type) }}</el-tag></td>
+          </tr><tr class="pickup-code-row">
+            <td class="document-table__actions"><el-button data-tone="primary" class="density-action" v-if="canManageDocuments" size="small" type="primary" :loading="pickupCodeBusy" :disabled="!pickupCodeValid || pickupCodeInput === (overview.container.pickupCode || '')" @click="emit('savePickupCode', pickupCodeInput)">保存</el-button><span v-else class="no-action">—</span></td>
+            <td><strong>PU 资料</strong></td>
+            <td><el-input v-model="pickupCodeInput" :disabled="!canManageDocuments" maxlength="64" inputmode="numeric" placeholder="请输入数字 PU 码" aria-label="PU码" @input="pickupCodeInput = pickupCodeInput.replace(/\D/g, '')" /></td>
+            <td>{{ overview.container.pickupCodeUpdatedByName || '—' }}</td>
+            <td>{{ formatTime(overview.container.pickupCodeUpdatedAt) }}</td>
+            <td><el-tag size="small" :type="overview.container.pickupCode ? 'success' : 'info'">{{ overview.container.pickupCode ? '已填写' : '未填写' }}</el-tag></td>
+          </tr></tbody>
+        </table>
+      </div>
+    </section>
+
+    <section v-if="visibleSections.has('pda')" class="overview-section" aria-label="PDA作业摘要">
+      <header><h3>PDA 作业进度</h3><StatusBadge v-if="overview.pda" :status="workflowStatusLabel(overview.pda.workflowStatus, overview.pda.taskStatus)" /></header>
+      <el-empty v-if="!overview.pda" description="尚未生成 PDA 作业任务" :image-size="64" />
+      <template v-else><div class="pda-summary"><el-progress :percentage="pdaProgress" :status="overview.pda.unresolvedItemCount ? 'exception' : undefined" /><div class="metric-grid"><div><span>任务明细</span><strong>{{ overview.pda.itemCount }}</strong></div><div><span>已处理</span><strong>{{ overview.pda.completedItemCount }}</strong></div><div><span>未解决</span><strong>{{ overview.pda.unresolvedItemCount }}</strong></div><div><span>有效照片</span><strong>{{ overview.pda.photoCounts.reduce((sum, item) => sum + item.count, 0) }}</strong></div></div></div><el-alert v-if="workflowStatusLabel(overview.pda.workflowStatus, overview.pda.taskStatus) === '待人工复核'" type="warning" :closable="false" title="PDA 作业已完成，等待人工复核后才能完成装柜。" /><el-alert v-else-if="workflowStatusLabel(overview.pda.workflowStatus, overview.pda.taskStatus) === '作业中'" type="info" :closable="false" title="请继续在 PDA 完成拣货、拍照和封条登记。" /><div v-if="activePhotos.length" class="photo-gallery"><button v-for="photo in activePhotos" :key="photo.evidenceId" type="button" class="photo-thumb" :aria-label="`预览装柜照片 ${photo.fileName}`" :disabled="!photoStates[photo.evidenceId]?.url" @click="openPhoto(photo)"><span v-if="photoStates[photo.evidenceId]?.loading" class="photo-placeholder">加载中</span><span v-else-if="photoStates[photo.evidenceId]?.error" class="photo-placeholder photo-placeholder--error">{{ photoStates[photo.evidenceId]?.error }}</span><img v-else-if="photoStates[photo.evidenceId]?.url" :src="photoStates[photo.evidenceId]?.url || ''" :alt="`${evidenceTypeLabel(photo.evidenceType)} ${photo.fileName}`" /><span class="photo-caption"><strong>{{ evidenceTypeLabel(photo.evidenceType) }}</strong><small>{{ formatTime(photo.uploadedAt) }}</small></span></button></div><p v-else class="compact-empty">暂无可查看的有效照片</p><el-alert v-if="overview.pda.exceptionReasons.length" type="warning" :closable="false" :title="overview.pda.exceptionReasons.join('；')" /></template>
+    </section>
+
+
+  </div>
+</template>
+
+<style scoped>
+.overview-panel { display: grid; gap: var(--admin-space-5); }
+.overview-section { min-width: 0; background: var(--admin-surface); border: 0; padding: 0; }
+.overview-section--documents{padding:0;border:0}
+.overview-section > header { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-5); margin-bottom: var(--admin-space-5); }
+.overview-section h3 { margin: 0; font-size: var(--admin-font-section); }
+.overview-section header > span, .overview-section small { color: var(--cc-muted); font-size: var(--admin-font-caption); }
+.overview-section p { margin: 5px 0; color: var(--cc-muted); font-size: var(--admin-font-body); }
+.exception-management{padding-top:var(--admin-space-4);padding-bottom:var(--admin-space-4)}.exception-management__header{margin-bottom:7px!important}.exception-management__header>div:first-child{display:flex;min-width:0;align-items:center;gap:var(--admin-space-5)}.exception-current{display:flex;min-width:0;align-items:center;gap:9px;margin:0!important}.exception-current strong,.exception-current span{max-width:360px;white-space: normal;overflow-wrap: anywhere}.exception-current strong{color:var(--el-color-danger)}.exception-current span{font-size:var(--admin-font-caption)}.exception-management__actions{display:flex;align-items:center;gap:var(--admin-space-3)}.exception-history{overflow-x:auto;border-top:1px solid var(--cc-border);font-size:var(--admin-font-caption)}.exception-history__head,.exception-history li{display:grid;grid-template-columns:145px 120px 130px minmax(220px,1fr);gap:var(--admin-space-3);align-items:center;min-width:680px;padding:var(--admin-space-2) var(--admin-space-1)}.exception-history__head{color:var(--cc-muted);font-weight:650}.exception-history ol{margin:0;padding:0;list-style:none}.exception-history li{border-top:1px solid var(--cc-border)}.exception-history li time,.exception-history li span{color:var(--cc-muted);white-space: normal;overflow-wrap: anywhere}.exception-history__empty{margin:0!important;padding:7px var(--admin-space-1);border-top:1px solid var(--cc-border);font-size:var(--admin-font-caption)!important}
+.document-table-wrap{width:100%;overflow-x:auto;border:1px solid var(--cc-border)}.document-table{width:100%;min-width:940px;table-layout:fixed}.document-table tbody tr:last-child td{border-bottom:0}.document-table th:nth-child(1){width:260px}.document-table th:nth-child(2){width:180px}.document-table th:nth-child(3){width:210px}.document-table th:nth-child(4){width:120px}.document-table th:nth-child(5){width:150px}.document-table th:nth-child(6){width:90px}.document-table__actions{position:sticky;left:0;z-index:1;box-shadow:1px 0 0 var(--cc-border)}.document-table th.document-table__actions{z-index:2}.document-table td strong{font-size:var(--admin-font-body)}.document-table td small{display:block;overflow:hidden;max-width:170px;margin-top:2px;text-overflow:ellipsis;white-space:nowrap}.document-file-name{display:block;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.document-blocked-reason{color:var(--cc-muted)}.document-actions{white-space:nowrap}.document-actions :deep(.el-button){margin-left:0}.no-action{color:var(--cc-muted)}.pickup-code-row :deep(.el-input){max-width:260px}.pickup-code-row :deep(.el-input__inner){font-variant-numeric:tabular-nums}
+.pda-summary{display:grid;grid-template-columns:minmax(220px,1fr) minmax(0,2fr);align-items:center;gap:var(--admin-space-5);margin-bottom:var(--admin-space-4)}.metric-grid { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: var(--admin-space-2); margin:0; }
+.metric-grid > div { display: flex; align-items: baseline; gap: var(--admin-space-2); padding: 0; background: transparent; }
+.metric-grid span { color: var(--cc-muted); font-size: var(--admin-font-caption); }
+.metric-grid strong { font-size: var(--admin-font-body); }
+.photo-gallery{display:grid;grid-template-columns:repeat(5,minmax(0,1fr));gap:var(--admin-space-3);margin:var(--admin-space-4) 0}.photo-thumb{display:grid;min-width:0;overflow:hidden;padding:0;border:1px solid var(--cc-border);background:var(--admin-surface);color:inherit;text-align:left;cursor:pointer}.photo-thumb:disabled{cursor:default}.photo-thumb img,.photo-placeholder{width:100%;aspect-ratio:4/3;object-fit:cover;background:var(--cc-bg-subtle,#f7f8fa)}.photo-placeholder{display:grid;place-items:center;padding:var(--admin-space-3);color:var(--cc-muted);font-size:var(--admin-font-caption)}.photo-placeholder--error{color:var(--el-color-danger)}.photo-caption{display:flex;align-items:center;justify-content:space-between;gap:var(--admin-space-2);padding:var(--admin-space-2) var(--admin-space-3)}.photo-caption small{white-space:nowrap}.compact-empty{margin:var(--admin-space-2) 0;color:var(--cc-muted);font-size:var(--admin-font-caption)}.compact-timeline{display:grid;margin:0;padding:0;list-style:none}.compact-timeline li{display:grid;grid-template-columns:130px 130px 110px minmax(0,1fr);gap:var(--admin-space-3);padding:var(--admin-space-2) 0;border-top:1px solid var(--cc-border);font-size:var(--admin-font-caption)}.compact-timeline li:first-child{border-top:0}.compact-timeline time,.compact-timeline span,.compact-timeline small{overflow:hidden;color:var(--cc-muted);text-overflow:ellipsis;white-space:nowrap}
+@media (max-width: 1200px){.photo-gallery{grid-template-columns:repeat(4,minmax(0,1fr))}.pda-summary{grid-template-columns:1fr}.compact-timeline li{grid-template-columns:120px 120px minmax(0,1fr)}.compact-timeline small{grid-column:2/-1}}
+@media (max-width: 720px) { .exception-management__header{align-items:flex-start;flex-direction:column}.exception-management__header>div:first-child{align-items:flex-start;flex-direction:column;gap:3px}.exception-current{align-items:flex-start;flex-direction:column;gap:2px}.metric-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }.photo-gallery{grid-template-columns:repeat(2,minmax(0,1fr))}.compact-timeline li{grid-template-columns:1fr 1fr}.compact-timeline span,.compact-timeline small{grid-column:auto;white-space:normal} }
+</style>
diff --git a/src/modules/container-loading/components/ContainerSimulationCreate.vue b/src/modules/container-loading/components/ContainerSimulationCreate.vue
new file mode 100644
index 00000000..e9ec050e
--- /dev/null
+++ b/src/modules/container-loading/components/ContainerSimulationCreate.vue
@@ -0,0 +1,113 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, reactive, ref } from 'vue'
+import { Plus } from '@lucide/vue'
+import { ElMessage, type FormInstance, type FormRules } from 'element-plus'
+import { listAllPlatformWarehouses, type PlatformWarehouseSummaryResource } from '@/modules/warehouses'
+import { listWarehouseLogisticsChannels, type OceanLogisticsChannel } from '@/modules/ocean-bookings'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { CONTAINER_SPECIFICATIONS, DEFAULT_CONTAINER_TYPE, applyContainerSpecification, containerSpecification } from '@/shared/domain/containerSpecifications'
+import { createContainerSimulation } from '../api/platformContainerLoading'
+import type { ContainerSimulationCreateRequest } from '../types'
+import { SMART_LOADING_CHANNEL_GROUPS } from '../smartLoadingChannelGroups'
+
+const props = withDefaults(defineProps<{
+  loadWarehouseOptions?: () => Promise<PlatformWarehouseSummaryResource[]>
+  successMessage?: string
+  dense?: boolean
+}>(), { successMessage: '模拟柜已创建，可先排货后关联真实订舱柜' })
+const emit = defineEmits<{ created: [] }>()
+const warehouses = ref<PlatformWarehouseSummaryResource[]>([])
+const warehouseLoading = ref(false)
+let warehousesLoaded = false
+let channelSequence = 0
+const simulationOpen = ref(false)
+const simulationSaving = ref(false)
+const simulationError = ref<ApiErrorDetails | null>(null)
+const simulationChannels = ref<OceanLogisticsChannel[]>([])
+const simulationChannelsLoading = ref(false)
+const simulationFormRef = ref<FormInstance>()
+const simulationForm = reactive<ContainerSimulationCreateRequest>({ channelGroupCode: '', warehouseId: '', containerType: DEFAULT_CONTAINER_TYPE, capacityCbm: 68, maxWeightKg: 19500 })
+const simulationChannelGroups = computed(() => {
+  const activeCodes = new Set(simulationChannels.value.map((channel) => channel.channelCode))
+  return SMART_LOADING_CHANNEL_GROUPS.filter((group) => group.channelCodes.some((code) => activeCodes.has(code)))
+})
+const simulationRules: FormRules<ContainerSimulationCreateRequest> = {
+  warehouseId: [{ required: true, message: '请选择装柜仓库', trigger: 'change' }],
+  channelGroupCode: [{ required: true, message: '请选择物流渠道', trigger: 'change' }],
+  containerType: [{ required: true, message: '请选择柜型', trigger: 'change' }],
+}
+
+async function openSimulation() {
+  Object.assign(simulationForm, { channelGroupCode: '', warehouseId: '', containerType: DEFAULT_CONTAINER_TYPE, capacityCbm: 68, maxWeightKg: 19500 })
+  simulationChannels.value = []
+  simulationError.value = null
+  simulationOpen.value = true
+  channelSequence++
+  simulationChannelsLoading.value = false
+  simulationFormRef.value?.clearValidate()
+  if (warehousesLoaded) return
+  warehouseLoading.value = true
+  try {
+    warehouses.value = props.loadWarehouseOptions
+      ? await props.loadWarehouseOptions()
+      : (await listAllPlatformWarehouses({ status: 'ACTIVE' })).filter((warehouse) => warehouse.warehouseType === 'DOMESTIC')
+    warehousesLoaded = true
+  } catch (error) { simulationError.value = getApiErrorDetails(error, '装柜仓库加载失败') }
+  finally { warehouseLoading.value = false }
+}
+function selectSimulationContainerType(containerType: string) {
+  applyContainerSpecification(simulationForm, containerType)
+}
+async function selectSimulationWarehouse(value: unknown) {
+  const sequence = ++channelSequence
+  simulationChannelsLoading.value = false
+  simulationForm.warehouseId = String(value || '')
+  simulationForm.channelGroupCode = ''
+  simulationChannels.value = []
+  simulationError.value = null
+  if (!simulationForm.warehouseId) return
+  simulationChannelsLoading.value = true
+  try {
+    const channels = await listWarehouseLogisticsChannels(simulationForm.warehouseId)
+    if (sequence === channelSequence) simulationChannels.value = channels
+  }
+  catch (error) { if (sequence === channelSequence) simulationError.value = getApiErrorDetails(error, '物流渠道加载失败') }
+  finally { if (sequence === channelSequence) simulationChannelsLoading.value = false }
+}
+async function saveSimulation() {
+  if (simulationSaving.value || warehouseLoading.value || simulationChannelsLoading.value) return
+  if (!(await simulationFormRef.value?.validate().catch(() => false))) return
+  simulationSaving.value = true
+  simulationError.value = null
+  try {
+    await createContainerSimulation({ ...simulationForm })
+    simulationOpen.value = false
+    ElMessage.success(props.successMessage)
+    emit('created')
+  } catch (error) { simulationError.value = getApiErrorDetails(error, '模拟柜创建失败') }
+  finally { simulationSaving.value = false }
+}
+</script>
+
+<template>
+  <el-button type="primary" @click="openSimulation"><Plus :size="16" />新增模拟柜</el-button>
+    <AppDialog :class="{ 'admin-density-dialog': dense }" v-model="simulationOpen" title="新增模拟柜" width="min(560px, calc(100vw - 28px))" confirm-text="创建模拟柜" cancel-text="取消" :confirm-loading="simulationSaving" @confirm="saveSimulation">
+      <el-alert title="模拟柜用于先排货，服务端会生成稳定的柜次号；此处不填写集装箱号和船期。" type="info" :closable="false" />
+      <el-form ref="simulationFormRef" :model="simulationForm" :rules="simulationRules" label-position="top" class="simulation-form">
+        <el-form-item label="装柜仓库" prop="warehouseId"><el-select :model-value="simulationForm.warehouseId" filterable placeholder="请选择国内装柜仓库" :loading="warehouseLoading" @update:model-value="selectSimulationWarehouse"><el-option v-for="warehouse in warehouses" :key="String(warehouse.id)" :label="warehouse.warehouseName" :value="String(warehouse.id)" /></el-select></el-form-item>
+        <el-form-item label="物流渠道" prop="channelGroupCode"><el-select v-model="simulationForm.channelGroupCode" filterable :disabled="!simulationForm.warehouseId || simulationChannelsLoading" :loading="simulationChannelsLoading" :placeholder="simulationForm.warehouseId ? '请选择物流渠道' : '请先选择装柜仓库'" no-data-text="当前仓库暂无有效渠道"><el-option v-for="group in simulationChannelGroups" :key="group.code" :label="group.name" :value="group.code" /></el-select></el-form-item>
+        <el-form-item label="柜型" prop="containerType"><el-select :model-value="simulationForm.containerType" @update:model-value="selectSimulationContainerType(String($event || ''))"><el-option v-for="item in CONTAINER_SPECIFICATIONS" :key="item.type" :label="item.type" :value="item.type" /></el-select></el-form-item>
+        <el-form-item label="统一规格"><el-input :model-value="`${containerSpecification(simulationForm.containerType)?.recommendedMinCbm || '—'}–${containerSpecification(simulationForm.containerType)?.capacityCbm || '—'} m³ / 货重 ≤ ${containerSpecification(simulationForm.containerType)?.maxWeightKg || '—'} kg`" disabled /><small>{{ containerSpecification(simulationForm.containerType)?.description }}</small></el-form-item>
+      </el-form>
+      <LoadErrorState v-if="simulationError" compact title="模拟柜创建失败" :message="simulationError.message" :show-retry="false"><template #details><ApiErrorMeta :details="simulationError" /></template></LoadErrorState>
+    </AppDialog>
+
+</template>
+
+<style scoped>
+.simulation-form :deep(.el-select), .simulation-form :deep(.el-input-number) { width: 100%; }
+</style>
diff --git a/src/modules/container-loading/components/OceanBookingLinkDialog.test.ts b/src/modules/container-loading/components/OceanBookingLinkDialog.test.ts
new file mode 100644
index 00000000..2f04920a
--- /dev/null
+++ b/src/modules/container-loading/components/OceanBookingLinkDialog.test.ts
@@ -0,0 +1,79 @@
+import ElementPlus from 'element-plus'
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { listOceanBookingLinkCandidates } from '@/modules/ocean-bookings'
+import { linkContainerOceanBooking } from '../api/platformContainerLoading'
+import type { ContainerBookingResource } from '../types'
+import OceanBookingLinkDialog from './OceanBookingLinkDialog.vue'
+
+vi.mock('@/modules/ocean-bookings', () => ({ listOceanBookingLinkCandidates: vi.fn() }))
+vi.mock('../api/platformContainerLoading', () => ({ linkContainerOceanBooking: vi.fn() }))
+
+const container = {
+  id: '9001', cabinetNo: 'CAB-1', bookingNo: 'CB-1', containerNo: null, planId: '7001', planStatus: 'EDITING',
+  sourceType: 'SIMULATION', warehouseId: '8', warehouseName: '义乌仓', channelGroupCode: 'MATSON_CLX', channelCode: null, channelName: null,
+  oceanBookingId: null, billOfLadingNo: null, vesselName: null, voyageNo: null, containerType: '40HQ',
+  shippingCompanyId: null, shippingCompanyName: null, departurePortCode: null, departurePortName: null,
+  destinationPortCode: null, destinationPortName: null, destinationWarehouseCode: null, destinationWarehouseName: null,
+  capacityCbm: 68, maxWeightKg: 19500, terminalTruckingCompanyId: null, terminalTruckingCompany: null,
+  loadingAt: null, estimatedSailingAt: null, actualSailingAt: null, estimatedPortArrivalAt: null,
+  actualPortArrivalAt: null, estimatedWarehouseArrivalAt: null, actualWarehouseArrivalAt: null, version: 7,
+} satisfies ContainerBookingResource
+
+const candidate = {
+  oceanBookingId: '101', bookingNo: 'OB-101', requirementId: '202', containerType: '40HQ', capacityCbm: 68,
+  maxWeightKg: 19500, requiredQuantity: 2, allocatedQuantity: 1, remainingQuantity: 1,
+  customerName: '测试客户', warehouseName: '义乌仓', channelName: '美森正班',
+}
+
+describe('OceanBookingLinkDialog', () => {
+  beforeEach(() => {
+    vi.mocked(listOceanBookingLinkCandidates).mockReset().mockResolvedValue({ records: [candidate], page: 1, size: 200, total: 1, pages: 1 })
+    vi.mocked(linkContainerOceanBooking).mockReset().mockResolvedValue({ ...container, oceanBookingId: '101', oceanBookingRequirementId: '202', version: 8 } as never)
+  })
+
+  it('loads matching released-booking requirements when opened', async () => {
+    const wrapper = mount(OceanBookingLinkDialog, { props: { modelValue: true, container }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(listOceanBookingLinkCandidates).toHaveBeenCalledExactlyOnceWith({ warehouseId: '8', channelGroupCode: 'MATSON_CLX', containerType: '40HQ', page: 1, size: 200 })
+    expect((wrapper.vm as unknown as { candidates: Array<{ label: string }> }).candidates[0]?.label).toContain('OB-101 · 40HQ × 1')
+    wrapper.unmount()
+  })
+
+  it.each([
+    ['  mscu1234567  ', 'MSCU1234567'],
+    ['', null],
+  ])('normalizes and submits the optional real container number %#', async (input, expected) => {
+    const wrapper = mount(OceanBookingLinkDialog, { props: { modelValue: true, container }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    const vm = wrapper.vm as unknown as { candidateKey: string; containerNo: string; save: () => Promise<void> }
+    vm.candidateKey = '101:202'
+    vm.containerNo = input
+    await vm.save()
+    expect(linkContainerOceanBooking).toHaveBeenCalledExactlyOnceWith('9001', {
+      oceanBookingId: '101', requirementId: '202', containerNo: expected, expectedVersion: 7,
+    })
+    expect(wrapper.emitted('update:modelValue')?.at(-1)).toEqual([false])
+    expect(wrapper.emitted('linked')).toHaveLength(1)
+    wrapper.unmount()
+  })
+
+  it('prefills and preserves a real container number recorded before booking linkage', async () => {
+    const existingContainer = { ...container, containerNo: 'MSCU6639870' }
+    const wrapper = mount(OceanBookingLinkDialog, {
+      props: { modelValue: true, container: existingContainer },
+      global: { plugins: [ElementPlus] },
+    })
+    await flushPromises()
+    const vm = wrapper.vm as unknown as { candidateKey: string; containerNo: string; save: () => Promise<void> }
+    expect(vm.containerNo).toBe('MSCU6639870')
+
+    vm.candidateKey = '101:202'
+    await vm.save()
+
+    expect(linkContainerOceanBooking).toHaveBeenCalledExactlyOnceWith('9001', {
+      oceanBookingId: '101', requirementId: '202', containerNo: 'MSCU6639870', expectedVersion: 7,
+    })
+    wrapper.unmount()
+  })
+})
diff --git a/src/modules/container-loading/components/OceanBookingLinkDialog.vue b/src/modules/container-loading/components/OceanBookingLinkDialog.vue
new file mode 100644
index 00000000..91633f8b
--- /dev/null
+++ b/src/modules/container-loading/components/OceanBookingLinkDialog.vue
@@ -0,0 +1,115 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { ref, watch } from 'vue'
+import { ElMessage } from 'element-plus'
+import { listOceanBookingLinkCandidates } from '@/modules/ocean-bookings'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { linkContainerOceanBooking } from '../api/platformContainerLoading'
+import type { ContainerBookingResource } from '../types'
+
+const props = defineProps<{ modelValue: boolean; container: ContainerBookingResource | null }>()
+const emit = defineEmits<{
+  'update:modelValue': [value: boolean]
+  linked: [container: ContainerBookingResource]
+}>()
+
+const loading = ref(false)
+const saving = ref(false)
+const error = ref<ApiErrorDetails | null>(null)
+const candidateKey = ref('')
+const containerNo = ref('')
+const candidates = ref<Array<{ key: string; oceanBookingId: string; requirementId: string; label: string }>>([])
+let requestSequence = 0
+
+function optional(value: string | null | undefined) { return value?.trim() || null }
+function normalizeContainerNo(value: string | null | undefined) { return String(value || '').trim().toUpperCase() }
+function close() { emit('update:modelValue', false) }
+
+async function loadCandidates() {
+  const target = props.container
+  candidateKey.value = ''
+  containerNo.value = normalizeContainerNo(target?.containerNo)
+  candidates.value = []
+  error.value = null
+  if (!target) return
+  const warehouseId = optional(target.warehouseId)
+  const channelGroupCode = optional(target.channelGroupCode)
+  const containerType = optional(target.containerType)
+  if (!warehouseId || !channelGroupCode || !containerType) {
+    error.value = { message: '当前模拟柜缺少仓库、计划渠道或柜型，无法查询可关联订舱' }
+    return
+  }
+  const sequence = ++requestSequence
+  loading.value = true
+  try {
+    const result = await listOceanBookingLinkCandidates({ warehouseId, channelGroupCode, containerType, page: 1, size: 200 })
+    if (sequence !== requestSequence || !props.modelValue || props.container?.id !== target.id) return
+    candidates.value = result.records.map((candidate) => ({
+      key: `${candidate.oceanBookingId}:${candidate.requirementId}`,
+      oceanBookingId: candidate.oceanBookingId,
+      requirementId: candidate.requirementId,
+      label: `${candidate.bookingNo} · ${candidate.containerType} × ${candidate.remainingQuantity} · ${candidate.customerName?.trim() || '未关联客户'} · ${candidate.warehouseName} · ${candidate.channelName}`,
+    }))
+  } catch (cause) {
+    if (sequence === requestSequence) error.value = getApiErrorDetails(cause, '已放舱订舱候选加载失败')
+  } finally {
+    if (sequence === requestSequence) loading.value = false
+  }
+}
+
+async function save() {
+  const target = props.container
+  const candidate = candidates.value.find((item) => item.key === candidateKey.value)
+  const normalized = normalizeContainerNo(containerNo.value)
+  containerNo.value = normalized
+  if (!target || !candidate) {
+    error.value = { message: '请选择规格一致且仍有剩余数量的柜型需求' }
+    return
+  }
+  saving.value = true
+  error.value = null
+  try {
+    const linked = await linkContainerOceanBooking(target.id, {
+      oceanBookingId: candidate.oceanBookingId,
+      requirementId: candidate.requirementId,
+      containerNo: normalized || null,
+      expectedVersion: target.version,
+    })
+    close()
+    ElMessage.success(normalized ? '订舱与真实集装箱号已关联，柜次号、装柜计划和明细保持不变' : '订舱已关联，真实集装箱号待司机提柜时录入')
+    emit('linked', linked)
+  } catch (cause) {
+    error.value = getApiErrorDetails(cause, '关联真实订舱柜失败')
+  } finally { saving.value = false }
+}
+
+watch(() => props.modelValue, (open) => {
+  if (open) void loadCandidates()
+  else {
+    requestSequence += 1
+    loading.value = false
+  }
+}, { immediate: true })
+
+defineExpose({ candidates, candidateKey, containerNo, save })
+</script>
+
+<template>
+  <AppDialog class="admin-density-dialog" :model-value="modelValue" title="关联已放舱订舱" width="min(680px, calc(100vw - 28px))" confirm-text="确认关联" cancel-text="取消" :confirm-loading="saving" :confirm-disabled="!candidateKey" @update:model-value="emit('update:modelValue', $event)" @confirm="save">
+    <!-- <el-alert title="关联后保留当前柜次号、装柜计划和明细，并补充订舱快照；真实集装箱号可待司机提柜时录入。" type="info" :closable="false" /> -->
+    <el-form class="density-form" label-position="top">
+      <el-form-item label="柜次号"><el-input :model-value="container?.cabinetNo || ''" disabled /></el-form-item>
+      <el-form-item label="已放舱订舱及柜型需求" required><el-select v-model="candidateKey" filterable :loading="loading" placeholder="请选择仍有剩余数量的柜型需求" no-data-text="暂无符合当前装柜仓库、物流渠道和柜型的已放舱需求"><el-option v-for="candidate in candidates" :key="candidate.key" :label="candidate.label" :value="candidate.key" /></el-select></el-form-item>
+      <el-form-item label="真实集装箱号（可选）"><el-input v-model="containerNo" maxlength="64" placeholder="如未取得可留空，后续显示待补录" @blur="containerNo = normalizeContainerNo(containerNo)" /></el-form-item>
+    </el-form>
+    <!-- <p class="dialog-hint">仓库、渠道和柜型必须与当前模拟柜一致；容量和限重仅展示柜型固定快照，不影响关联资格。</p> -->
+    <LoadErrorState v-if="error" compact title="关联失败" :message="error.message" :show-retry="false"><template #details><ApiErrorMeta :details="error" /></template></LoadErrorState>
+  </AppDialog>
+</template>
+
+<style scoped>
+.dialog-hint { margin: var(--admin-space-1) 0 0; color: var(--cc-muted); font-size: var(--admin-font-caption); line-height: 1.6; }
+</style>
diff --git a/src/modules/container-loading/components/SmartLoadingCandidateInbounds.test.ts b/src/modules/container-loading/components/SmartLoadingCandidateInbounds.test.ts
new file mode 100644
index 00000000..b47c956c
--- /dev/null
+++ b/src/modules/container-loading/components/SmartLoadingCandidateInbounds.test.ts
@@ -0,0 +1,32 @@
+import { mount } from '@vue/test-utils'
+import { describe, expect, it } from 'vitest'
+import SmartLoadingCandidateInbounds from './SmartLoadingCandidateInbounds.vue'
+import type { SmartLoadingCandidate } from '../types'
+
+describe('sealed pallet composition', () => {
+  it('shows the two inbound portions, not the whole pallet count twice', async () => {
+    const candidate = { unitType: 'SEALED_PALLET', inboundCode: 'I180', availablePackageCount: 13,
+      groupMembers: [{ accountId: '1', inboundId: '180', inboundCode: 'I180', availablePackageCount: 3 },
+        { accountId: '1', inboundId: '181', inboundCode: 'I181', availablePackageCount: 10 }] } as SmartLoadingCandidate
+    const wrapper = mount(SmartLoadingCandidateInbounds, { props: { candidate } })
+    expect(wrapper.get('summary').text()).toBe('2 个入仓码 · 展开')
+    expect(wrapper.text()).toContain('I180：3 箱')
+    expect(wrapper.text()).toContain('I181：10 箱')
+    expect(wrapper.text()).not.toContain('13 箱')
+    expect(wrapper.findAll('button')).toHaveLength(0)
+  })
+
+  it('renders the same composition when it comes from an assigned plan pallet', () => {
+    const wrapper = mount(SmartLoadingCandidateInbounds, { props: {
+      sealedPallet: true,
+      fallbackInboundCode: 'I180',
+      members: [
+        { accountId: '1', inboundId: '180', orderId: '280', orderNo: 'O180', inboundCode: 'I180', customerName: '客户', availablePackageCount: 6, orderStatusSnapshot: null, expectedArrivalAt: null },
+        { accountId: '1', inboundId: '181', orderId: '281', orderNo: 'O181', inboundCode: 'I181', customerName: '客户', availablePackageCount: 5, orderStatusSnapshot: null, expectedArrivalAt: null },
+      ],
+    } })
+    expect(wrapper.get('summary').text()).toBe('2 个入仓码 · 展开')
+    expect(wrapper.text()).toContain('I180：6 箱')
+    expect(wrapper.text()).toContain('I181：5 箱')
+  })
+})
diff --git a/src/modules/container-loading/components/SmartLoadingCandidateInbounds.vue b/src/modules/container-loading/components/SmartLoadingCandidateInbounds.vue
new file mode 100644
index 00000000..9c624d88
--- /dev/null
+++ b/src/modules/container-loading/components/SmartLoadingCandidateInbounds.vue
@@ -0,0 +1,26 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import type { SmartLoadingCandidate, SmartLoadingCandidateGroupMember } from '../types'
+
+const props = defineProps<{
+  candidate?: SmartLoadingCandidate
+  members?: SmartLoadingCandidateGroupMember[]
+  sealedPallet?: boolean
+  fallbackInboundCode?: string | null
+}>()
+const displayedMembers = computed(() => props.members || props.candidate?.groupMembers || [])
+const isSealedPallet = computed(() => props.candidate
+  ? props.candidate.unitType === 'SEALED_PALLET'
+  : props.sealedPallet === true)
+const inboundCode = computed(() => props.fallbackInboundCode ?? props.candidate?.inboundCode)
+</script>
+
+<template>
+  <details v-if="isSealedPallet && displayedMembers.length">
+    <summary>{{ displayedMembers.length }} 个入仓码 · 展开</summary>
+    <div v-for="member in displayedMembers" :key="`${member.accountId}:${member.inboundId}`">
+      {{ member.inboundCode || '—' }}：{{ member.availablePackageCount }} 箱
+    </div>
+  </details>
+  <span v-else>{{ inboundCode || '—' }}</span>
+</template>
diff --git a/src/modules/container-loading/components/SmartLoadingDialog.test.ts b/src/modules/container-loading/components/SmartLoadingDialog.test.ts
new file mode 100644
index 00000000..8ad28fed
--- /dev/null
+++ b/src/modules/container-loading/components/SmartLoadingDialog.test.ts
@@ -0,0 +1,51 @@
+import ElementPlus from 'element-plus'
+import { flushPromises, mount } from '@vue/test-utils'
+import { afterEach, describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import SmartLoadingDialog from './SmartLoadingDialog.vue'
+
+describe('SmartLoadingDialog', () => {
+  afterEach(() => { document.body.innerHTML = '' })
+
+  it('opens fullscreen by default, can return to normal size, and reopens fullscreen', async () => {
+    const wrapper = mount(SmartLoadingDialog, {
+      attachTo: document.body,
+      props: { modelValue: true },
+      global: {
+        plugins: [ElementPlus],
+        stubs: { GlobalSmartLoadingView: { template: '<div>智能装柜工作台</div>' } },
+      },
+    })
+    await flushPromises()
+
+    expect(wrapper.find('.smart-loading-dialog__warehouses').exists()).toBe(false)
+    expect(document.querySelector('.smart-loading-dialog .el-dialog__body')?.classList.contains('el-dialog__body')).toBe(true)
+    expect(document.querySelector('.smart-loading-dialog.is-fullscreen')).not.toBeNull()
+    expect(wrapper.find('button[aria-label="退出全屏"]').exists()).toBe(true)
+
+    await wrapper.get('button[aria-label="退出全屏"]').trigger('click')
+    expect(document.querySelector('.smart-loading-dialog.is-fullscreen')).toBeNull()
+    expect(wrapper.find('button[aria-label="展开全屏"]').exists()).toBe(true)
+
+    await wrapper.setProps({ modelValue: false })
+    await flushPromises()
+    await wrapper.setProps({ modelValue: true })
+    await flushPromises()
+    expect(document.querySelector('.smart-loading-dialog.is-fullscreen')).not.toBeNull()
+    expect(wrapper.find('button[aria-label="退出全屏"]').exists()).toBe(true)
+  })
+
+  it('keeps the outer dialog fixed so only workbench data panes scroll', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/components/SmartLoadingDialog.vue'), 'utf8')
+    expect(source).toContain('fullscreenable')
+    expect(source).toContain('default-fullscreen')
+    expect(source).not.toContain('Maximize2')
+    expect(source).not.toContain('const fullscreen')
+    expect(source).toContain('.smart-loading-dialog.app-dialog.el-dialog:not(.is-fullscreen)')
+    expect(source).toContain('height: 94vh; max-height: 94vh;')
+    expect(source).not.toContain('.smart-loading-dialog.app-dialog.el-dialog) { width: min(1600px, 98vw)')
+    expect(source).toContain('flex: 1; padding: 0; overflow: hidden;')
+    expect(source).toContain('min-height: 0; flex: 1; overflow: hidden;')
+  })
+})
diff --git a/src/modules/container-loading/components/SmartLoadingDialog.vue b/src/modules/container-loading/components/SmartLoadingDialog.vue
new file mode 100644
index 00000000..fc4b3eba
--- /dev/null
+++ b/src/modules/container-loading/components/SmartLoadingDialog.vue
@@ -0,0 +1,31 @@
+<script setup lang="ts">
+import AppDialog from '@/shared/components/AppDialog.vue'
+import GlobalSmartLoadingView from '../pages/GlobalSmartLoadingView.vue'
+
+const open = defineModel<boolean>({ default: false })
+</script>
+
+<template>
+  <AppDialog
+    v-model="open"
+    class="smart-loading-dialog"
+    title="智能装柜"
+    width="min(1600px, 98vw)"
+    fullscreenable
+    default-fullscreen
+    cancel-text="关闭"
+    :show-confirm="false"
+    destroy-on-close
+  >
+    <GlobalSmartLoadingView embedded />
+  </AppDialog>
+</template>
+
+<style scoped>
+:global(.smart-loading-dialog.app-dialog.el-dialog:not(.is-fullscreen)) { width: min(1600px, 98vw); height: 94vh; max-height: 94vh; margin-block: 3vh !important; }
+:global(.smart-loading-dialog .el-dialog__body) { display: flex; min-height: 0; flex: 1; padding: 0; overflow: hidden; }
+:global(.smart-loading-dialog .app-dialog__body) { display: flex; min-width: 0; min-height: 0; flex: 1; overflow: hidden; }
+@media (max-width: 720px) {
+  :global(.smart-loading-dialog.app-dialog.el-dialog:not(.is-fullscreen)) { width: calc(100vw - 12px); height: calc(100svh - 12px); max-height: calc(100svh - 12px); margin-block: 6px !important; }
+}
+</style>
diff --git a/src/modules/container-loading/index.ts b/src/modules/container-loading/index.ts
new file mode 100644
index 00000000..da4036f4
--- /dev/null
+++ b/src/modules/container-loading/index.ts
@@ -0,0 +1,4 @@
+export * from './api/platformContainerLoading'
+export * from './types'
+export { default as SmartLoadingDialog } from './components/SmartLoadingDialog.vue'
+export { default as ContainerSimulationCreate } from './components/ContainerSimulationCreate.vue'
diff --git a/src/modules/container-loading/pages/ContainerDetailView.emptyReturn.behavior.test.ts b/src/modules/container-loading/pages/ContainerDetailView.emptyReturn.behavior.test.ts
new file mode 100644
index 00000000..f297b23f
--- /dev/null
+++ b/src/modules/container-loading/pages/ContainerDetailView.emptyReturn.behavior.test.ts
@@ -0,0 +1,293 @@
+import ElementPlus from 'element-plus'
+import { createPinia } from 'pinia'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import ContainerDetailView from './ContainerDetailView.vue'
+import { getContainer, getContainerOverview, linkContainerOceanBooking } from '../api/platformContainerLoading'
+import { listOceanBookingLinkCandidates } from '@/modules/ocean-bookings'
+import { recordTerminalDrayageEmptyReturn } from '../api/terminalDrayages'
+import { listContainerArrivalTimes } from '../api/containerArrivalTimes'
+import { getContainerOutboundDispatch } from '@/modules/outbound-dispatch'
+import { ref } from 'vue'
+import { getConfirmedLoadingList, getPreloadPlan } from '@/modules/loading-lists'
+import DomesticContainerDetailView from './DomesticContainerDetailView.vue'
+
+const canAccess = vi.hoisted(() => vi.fn<(code: string) => boolean>(() => true))
+const routeState = vi.hoisted(() => ({ params: { containerId: '9001' }, query: {} as Record<string, string> }))
+const routerPush = vi.hoisted(() => vi.fn())
+vi.mock('@/core/access/accessPreview', () => ({ useAccessPreviewStore: () => ({ can: canAccess }) }))
+vi.mock('vue-router', () => ({ useRoute: () => routeState, useRouter: () => ({ push: routerPush }) }))
+vi.mock('@/modules/loading-lists', () => ({ ContainerFeesPanel: { template: '<div />' }, LoadingListDetailDrawer: { name: 'LoadingListDetailDrawer', props: ['detail', 'error', 'loading', 'mode', 'embedded'], template: '<div data-testid="loading-detail">{{ detail?.planNo }}</div>' }, PalletLabelPrintDialog: { template: '<div />' }, getConfirmedLoadingList: vi.fn(), getPreloadPlan: vi.fn() }))
+vi.mock('@/modules/ocean-bookings', () => ({ listOceanBookingLinkCandidates: vi.fn() }))
+vi.mock('@/modules/outbound-dispatch', () => ({ confirmContainerOutboundDispatch: vi.fn(), getContainerOutboundDispatch: vi.fn() }))
+vi.mock('@/modules/port-schedules', () => ({ CarrierScheduleQueryPanel: { template: '<div />' } }))
+vi.mock('../api/platformContainerLoading', () => ({ getContainer: vi.fn(), getContainerOverview: vi.fn(), linkContainerOceanBooking: vi.fn(), cancelContainerException: vi.fn(), completeContainerClearance: vi.fn(), downloadContainerClearance: vi.fn(), downloadContainerDocument: vi.fn(), getContainerClearance: vi.fn(), markContainerException: vi.fn(), uploadContainerClearance: vi.fn(), uploadContainerDocument: vi.fn(), updateContainerPickupCode: vi.fn() }))
+vi.mock('../api/terminalDrayages', () => ({ recordTerminalDrayageEmptyReturn: vi.fn() }))
+vi.mock('../api/containerArrivalTimes', () => ({ listContainerArrivalTimes: vi.fn() }))
+
+const base = { id: '9001', cabinetNo: 'CB-1', containerNo: 'MSCU-1', planNo: 'LP-1', planStatus: 'COMPLETED', warehouseName: '义乌仓', destinationWarehouseCode: 'LAX01', destinationWarehouseName: '洛杉矶接柜仓', workbenchStage: 'UNLOADED', statusSummary: { terminalDrayageStatus: 'UNLOADED' }, allowedActions: ['RECORD_EMPTY_RETURN'], terminalDrayage: { containerBookingId: '9001', status: 'UNLOADED', version: 3, fleetSupplierId: '501', fleetSupplierName: '港运车队', pickupAppointmentAt: '2026-09-07T08:00:00', actualPickupAt: '2026-09-07T09:00:00', estimatedEmptyReturnAt: '2026-09-10T10:00:00', actualEmptyReturnAt: null, unloadingCompletedAt: '2026-09-07T10:00:00', emptyReturnWarning: { status: 'PENDING', deadlineAt: '2026-09-10T10:00:00', overdueHours: 0, overdueDays: 0 }, allowedActions: ['RECORD_EMPTY_RETURN'], updatedAt: '2026-09-09T10:00:00' }, actualFacts: { unloadingCompletedAt: '2026-09-07T10:00:00' } }
+const overview = { container: { id: '9001', version: 1 }, loadingPlanId: null, documents: [], exception: { active: false }, timeline: [] }
+
+enableAutoUnmount(afterEach)
+
+async function mountDetail(workbench: 'DOMESTIC' | 'OVERSEAS' = 'OVERSEAS') {
+  const wrapper = mount(ContainerDetailView, { props: { workbench }, attachTo: document.body, global: { plugins: [createPinia(), ElementPlus], stubs: { ContainerOverviewPanel: true, ContainerCustomsPanel: true, ContainerLastLegFeesPanel: true } } })
+  await flushPromises()
+  return wrapper
+}
+
+function accessibleText(wrapper: { element: Element } | undefined) {
+  if (!wrapper) return undefined
+  const element = wrapper.element.cloneNode(true) as Element
+  element.querySelectorAll('[aria-hidden="true"]').forEach(node => node.remove())
+  return element.textContent?.trim()
+}
+
+describe('ContainerDetailView empty return', () => {
+  beforeEach(() => {
+    routeState.query = {}
+    routerPush.mockReset()
+    canAccess.mockReset().mockReturnValue(true)
+    vi.mocked(getContainerOutboundDispatch).mockReset().mockResolvedValue({ aggregate: { dispatchStatus: 'WAITING_FOR_LOADING', gate: { inbounds: [] } }, timeline: [] } as never)
+    vi.mocked(getContainer).mockReset().mockResolvedValue(base as never)
+    vi.mocked(getContainerOverview).mockReset().mockResolvedValue(overview as never)
+    vi.mocked(getConfirmedLoadingList).mockReset().mockResolvedValue({ planNo: 'LP-1', items: [] } as never)
+    vi.mocked(recordTerminalDrayageEmptyReturn).mockReset().mockResolvedValue({ ...base.terminalDrayage, status: 'EMPTY_RETURNED', version: 4, actualEmptyReturnAt: '2026-09-09T12:00:00', allowedActions: [] } as never)
+    vi.mocked(listContainerArrivalTimes).mockReset().mockResolvedValue([{ sourceContainerBookingId: '9001', estimatedWarehouseArrivalAt: '2026-09-25T15:31:00', actualWarehouseArrivalAt: '2026-09-26T09:00:00', version: 0 }])
+  })
+
+  it('loads departed gates exactly once when read permission arrives after the container detail', async () => {
+    const granted = ref(false)
+    canAccess.mockImplementation((code) => code === 'platform:firstleg:outbound-dispatch:view' ? granted.value : true)
+    const wrapper = await mountDetail('DOMESTIC')
+    expect(getContainerOutboundDispatch).not.toHaveBeenCalled()
+    granted.value = true
+    await flushPromises()
+    expect(getContainerOutboundDispatch).toHaveBeenCalledTimes(1)
+    expect(wrapper.text()).toContain('已确认离仓')
+    expect(wrapper.text()).toContain('整柜已确认离仓；')
+    expect(wrapper.text()).not.toContain('全部门禁已通过，可确认整柜离仓')
+  })
+
+  it('reloads authoritative departure state once on each newly opened domestic detail', async () => {
+    const first = await mountDetail('DOMESTIC')
+    expect(first.text()).toContain('已确认离仓')
+    first.unmount()
+    const reopened = await mountDetail('DOMESTIC')
+    expect(reopened.text()).toContain('已确认离仓')
+    expect(getContainerOutboundDispatch).toHaveBeenCalledTimes(2)
+  })
+
+  it.each(['DOMESTIC', 'OVERSEAS'] as const)('gates fee tabs by granted permissions in %s', async (workbench) => {
+    for (const [firstLeg, lastLeg] of [[true, false], [false, true], [true, true], [false, false]]) {
+      canAccess.mockImplementation((code) => code === 'firstleg:inbound:fee-detail:view' ? firstLeg! : code === 'platform:finance:customer-arap:list' ? lastLeg! : false)
+      const wrapper = await mountDetail(workbench)
+      const labels = wrapper.findAll('[role="tab"]').map((tab) => accessibleText(tab))
+      expect(labels.includes('国内段费用（头程）')).toBe(firstLeg)
+      expect(labels.includes('目的港及海外段费用（尾程）')).toBe(lastLeg)
+      if (lastLeg) {
+        await wrapper.findAll('[role="tab"]').find((tab) => accessibleText(tab) === '目的港及海外段费用（尾程）')!.trigger('click')
+        await flushPromises()
+        expect(wrapper.findComponent({ name: 'ContainerLastLegFeesPanel' }).props('readonly')).toBe(false)
+      }
+      wrapper.unmount()
+    }
+  })
+
+  it('uses the overseas stage, submits one versioned command and refreshes to returned state', async () => {
+    vi.mocked(getContainer).mockResolvedValueOnce(base as never).mockResolvedValue({ ...base, workbenchStage: 'EMPTY_RETURNED', statusSummary: { terminalDrayageStatus: 'EMPTY_RETURNED' }, allowedActions: [], terminalDrayage: { ...base.terminalDrayage, status: 'EMPTY_RETURNED', version: 4, actualEmptyReturnAt: '2026-09-09T12:00:00', allowedActions: [] } } as never)
+    const wrapper = await mountDetail()
+    expect(wrapper.text()).toContain('待还柜')
+    expect(wrapper.text()).not.toContain('装柜完成')
+    await wrapper.findAll('button').find((item) => item.text() === '确认还柜')!.trigger('click')
+    await flushPromises()
+    const confirm = [...document.body.querySelectorAll('button')].filter((item) => item.textContent?.trim() === '确认还柜').at(-1) as HTMLButtonElement
+    confirm.click()
+    await flushPromises()
+    expect(recordTerminalDrayageEmptyReturn).toHaveBeenCalledTimes(1)
+    expect(recordTerminalDrayageEmptyReturn).toHaveBeenCalledWith('9001', expect.objectContaining({ expectedVersion: 3, actualAt: expect.any(String), remark: undefined }))
+    expect(getContainer).toHaveBeenCalledTimes(2)
+    expect(wrapper.text()).toContain('已还柜')
+    expect(wrapper.find('.detail-section__heading').findAll('button').some((item) => item.text() === '确认还柜')).toBe(false)
+  })
+
+  it('falls back to confirmed loading facts for destination and terminal drayage for unloading time', async () => {
+    vi.mocked(getContainer).mockResolvedValue({
+      ...base,
+      destinationWarehouseCode: null,
+      destinationWarehouseName: null,
+      warehouseId: '8',
+      terminalTruckingCompany: null,
+      actualFacts: {},
+    } as never)
+    vi.mocked(getContainerOverview).mockResolvedValue({ ...overview, loadingPlanId: '7001' } as never)
+    vi.mocked(getConfirmedLoadingList).mockResolvedValue({
+      planNo: 'LP-1',
+      items: [{ destinationWarehouse: 'ABE4' }, { destinationWarehouse: 'ABE4' }],
+    } as never)
+
+    const wrapper = await mountDetail()
+
+    expect(getConfirmedLoadingList).toHaveBeenCalledExactlyOnceWith('7001', '8')
+    expect(wrapper.text()).toContain('ABE4')
+    expect(wrapper.text()).toContain('港运车队')
+    expect(wrapper.text()).toContain('2026-09-07 10:00')
+  })
+
+  it.each([
+    ['缺权限', false, ['RECORD_EMPTY_RETURN'], ['RECORD_EMPTY_RETURN'], 'UNLOADED'],
+    ['缺服务端动作', true, [], [], 'UNLOADED'],
+    ['已还柜', true, [], [], 'EMPTY_RETURNED'],
+  ])('%s时不提供确认还柜', async (_name, allowed, rowActions, drayageActions, status) => {
+    canAccess.mockImplementation((code) => code !== 'platform:firstleg:terminal-drayage:empty-return:confirm' || allowed)
+    vi.mocked(getContainer).mockResolvedValue({ ...base, workbenchStage: status, statusSummary: { terminalDrayageStatus: status }, allowedActions: rowActions, terminalDrayage: { ...base.terminalDrayage, status, allowedActions: drayageActions } } as never)
+    const wrapper = await mountDetail()
+    expect(wrapper.findAll('button').some((item) => item.text() === '确认还柜')).toBe(false)
+  })
+})
+
+describe('domestic container loading list and booking link', () => {
+  const domestic = { ...base, containerNo: null, warehouseId: '8', channelCode: 'ZBYHK', sourceType: 'SIMULATION', oceanBookingId: null, planId: '7001', planStatus: 'EDITING', version: 1, allowedActions: ['EDIT_CONTAINER'], terminalDrayage: null }
+  const loadingDetail = { planNo: 'LP-1', items: [] }
+
+  beforeEach(() => {
+    routeState.query = {}
+    routerPush.mockReset()
+    canAccess.mockReset().mockImplementation((code) => ['platform:firstleg:container:list', 'platform:firstleg:container:edit', 'platform:firstleg:preload:list', 'platform:firstleg:loading-list:list'].includes(code))
+    vi.mocked(getContainer).mockReset().mockResolvedValue(domestic as never)
+    vi.mocked(getContainerOverview).mockReset().mockResolvedValue({ ...overview, loadingPlanId: '7001' } as never)
+    vi.mocked(getPreloadPlan).mockReset().mockResolvedValue(loadingDetail as never)
+    vi.mocked(getConfirmedLoadingList).mockReset().mockResolvedValue(loadingDetail as never)
+    vi.mocked(listOceanBookingLinkCandidates).mockReset().mockResolvedValue({ records: [], page: 1, size: 200, total: 0, pages: 0 })
+    vi.mocked(linkContainerOceanBooking).mockReset()
+  })
+
+  async function mountDomestic() {
+    const wrapper = mount(DomesticContainerDetailView, { attachTo: document.body, global: { plugins: [createPinia(), ElementPlus], stubs: { ContainerOverviewPanel: true, ContainerCustomsPanel: true, ContainerLastLegFeesPanel: true } } })
+    await flushPromises()
+    expect(getContainer).toHaveBeenLastCalledWith('9001', 'DOMESTIC')
+    return wrapper
+  }
+
+  it.each(['WAIT_LOADING', 'EDITING', 'LOADING', 'COMPLETED'])('opens the loading-list tab using the correct API for %s', async (planStatus) => {
+    vi.mocked(getContainer).mockResolvedValue({ ...domestic, planStatus } as never)
+    const wrapper = await mountDomestic()
+    expect(getPreloadPlan).not.toHaveBeenCalled()
+    expect(getConfirmedLoadingList).not.toHaveBeenCalled()
+    const tab = wrapper.findAll('[role="tab"]').find((item) => accessibleText(item) === '装柜清单')!
+    expect(tab).toBeDefined()
+    await tab.trigger('click')
+    await flushPromises()
+    expect(tab.attributes('aria-selected')).toBe('true')
+    expect(wrapper.get('[data-testid="loading-detail"]').text()).toBe('LP-1')
+    expect(planStatus === 'COMPLETED' ? getConfirmedLoadingList : getPreloadPlan).toHaveBeenCalledExactlyOnceWith('7001', '8')
+    expect(planStatus === 'COMPLETED' ? getPreloadPlan : getConfirmedLoadingList).not.toHaveBeenCalled()
+  })
+
+  it.each(['WAIT_LOADING', 'EDITING', 'LOADING', 'COMPLETED'])('enforces the matching read permission for a %s deep link', async (planStatus) => {
+    for (const preload of [false, true]) {
+      for (const confirmed of [false, true]) {
+        vi.mocked(getPreloadPlan).mockClear()
+        vi.mocked(getConfirmedLoadingList).mockClear()
+        routeState.query = { tab: 'loading-list' }
+        canAccess.mockImplementation((code) => code === 'platform:firstleg:preload:list' ? preload : code === 'platform:firstleg:loading-list:list' ? confirmed : code === 'platform:firstleg:container:list')
+        vi.mocked(getContainer).mockResolvedValue({ ...domestic, planStatus } as never)
+        const wrapper = await mountDomestic()
+        const permitted = planStatus === 'COMPLETED' ? confirmed : preload
+        const tabs = wrapper.findAll('[role="tab"]')
+        expect(tabs.some((tab) => accessibleText(tab) === '装柜清单')).toBe(permitted)
+        expect(accessibleText(tabs.find((tab) => tab.attributes('aria-selected') === 'true'))).toBe(permitted ? '装柜清单' : '送柜报关')
+        expect(getPreloadPlan).toHaveBeenCalledTimes(permitted && planStatus !== 'COMPLETED' ? 1 : 0)
+        expect(getConfirmedLoadingList).toHaveBeenCalledTimes(permitted && planStatus === 'COMPLETED' ? 1 : 0)
+        if (permitted) {
+          const drawer = wrapper.findComponent({ name: 'LoadingListDetailDrawer' })
+          expect(drawer.props('mode')).toBe(planStatus === 'COMPLETED' ? 'confirmed' : 'preload')
+          expect(drawer.props('embedded')).not.toBeUndefined()
+        }
+        wrapper.unmount()
+      }
+    }
+  })
+
+  it('does not expose the domestic loading-list deep link in the overseas workbench', async () => {
+    routeState.query = { tab: 'loading-list' }
+    vi.mocked(getContainer).mockResolvedValue(base as never)
+    const wrapper = await mountDetail('OVERSEAS')
+    expect(wrapper.findAll('[role="tab"]').map((tab) => accessibleText(tab))).not.toContain('装柜清单')
+    expect(accessibleText(wrapper.findAll('[role="tab"]').find((tab) => tab.attributes('aria-selected') === 'true'))).toBe('清关提柜')
+    expect(getPreloadPlan).not.toHaveBeenCalled()
+    expect(getConfirmedLoadingList).not.toHaveBeenCalled()
+  })
+
+  it('keeps the tab and reports a loading failure without inventing a successful list', async () => {
+    routeState.query = { tab: 'loading-list' }
+    vi.mocked(getPreloadPlan).mockRejectedValue(new Error('清单读取失败'))
+    const wrapper = await mountDomestic()
+    const list = wrapper.findComponent({ name: 'LoadingListDetailDrawer' })
+    expect(list.props('detail')).toBeNull()
+    expect(list.props('error')).toMatchObject({ message: '装柜清单加载失败' })
+    expect(list.props('loading')).toBe(false)
+    expect(accessibleText(wrapper.findAll('[role="tab"]').find((tab) => tab.attributes('aria-selected') === 'true'))).toBe('装柜清单')
+  })
+
+  it.each(['WAIT_LOADING', 'EDITING'])('retains the unlinked booking entry with an existing plan in %s', async (planStatus) => {
+    vi.mocked(getContainer).mockResolvedValue({ ...domestic, planStatus, version: 2 } as never)
+    const wrapper = await mountDomestic()
+    const link = wrapper.findAll('button').find((button) => button.text() === '关联已放舱订舱')!
+    expect(link).toBeDefined()
+    await link.trigger('click')
+    await flushPromises()
+    expect(routerPush).not.toHaveBeenCalled()
+    expect(wrapper.findComponent({ name: 'OceanBookingLinkDialog' }).props('modelValue')).toBe(true)
+  })
+
+  it('refreshes the routed detail after the shared link dialog succeeds', async () => {
+    const linked = { ...domestic, oceanBookingId: '101', billOfLadingNo: 'BL-101', version: 2 }
+    vi.mocked(getContainer).mockResolvedValueOnce(domestic as never).mockResolvedValueOnce(linked as never)
+    const wrapper = await mountDomestic()
+    await wrapper.findAll('button').find((button) => button.text() === '关联已放舱订舱')!.trigger('click')
+    await flushPromises()
+    const dialog = wrapper.findComponent({ name: 'OceanBookingLinkDialog' })
+    expect(dialog.props('modelValue')).toBe(true)
+    dialog.vm.$emit('linked', linked)
+    await flushPromises()
+    expect(getContainer).toHaveBeenCalledTimes(2)
+    expect(wrapper.text()).toContain('BL-101')
+    expect(wrapper.findAll('button').some((button) => button.text() === '关联已放舱订舱')).toBe(false)
+  })
+
+  it('keeps the same cabinet link before and after an inbound assignment snapshot refresh', async () => {
+    // Assignment changes the version and plan items, not the booking association or EDITING status.
+    for (const [version, items] of [[1, []], [2, [{ inboundCode: 'IN-001' }]]] as const) {
+      routeState.query = { tab: 'loading-list' }
+      vi.mocked(getContainer).mockResolvedValue({ ...domestic, version } as never)
+      vi.mocked(getPreloadPlan).mockResolvedValue({ ...loadingDetail, items } as never)
+      const wrapper = await mountDomestic()
+      expect(wrapper.findComponent({ name: 'LoadingListDetailDrawer' }).props('detail').items).toEqual(items)
+      await wrapper.findAll('[role="tab"]').find((tab) => accessibleText(tab) === '送柜报关')!.trigger('click')
+      await flushPromises()
+      const link = wrapper.findAll('button').find((button) => button.text() === '关联已放舱订舱')!
+      expect(link.isVisible()).toBe(true)
+      routerPush.mockClear()
+      await link.trigger('click')
+      await flushPromises()
+      expect(routerPush).not.toHaveBeenCalled()
+      expect(wrapper.findComponent({ name: 'OceanBookingLinkDialog' }).props('modelValue')).toBe(true)
+      wrapper.unmount()
+    }
+  })
+
+  it.each([
+    { label: 'already linked simulation', patch: { oceanBookingId: '8001' }, edit: true },
+    { label: 'picking started', patch: { planStatus: 'LOADING' }, edit: true },
+    { label: 'completed', patch: { planStatus: 'COMPLETED' }, edit: true },
+    { label: 'server denies editing', patch: { allowedActions: [] }, edit: true },
+    { label: 'account lacks edit permission', patch: {}, edit: false },
+  ])('hides the booking link when $label', async ({ patch, edit }) => {
+    canAccess.mockImplementation((code) => code === 'platform:firstleg:container:list' || (edit && code === 'platform:firstleg:container:edit'))
+    vi.mocked(getContainer).mockResolvedValue({ ...domestic, ...patch } as never)
+    const wrapper = await mountDomestic()
+    expect(wrapper.findAll('button').some((button) => button.text() === '关联已放舱订舱')).toBe(false)
+    expect(routerPush).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/modules/container-loading/pages/ContainerDetailView.test.ts b/src/modules/container-loading/pages/ContainerDetailView.test.ts
new file mode 100644
index 00000000..0b5c40d0
--- /dev/null
+++ b/src/modules/container-loading/pages/ContainerDetailView.test.ts
@@ -0,0 +1,138 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/pages/ContainerDetailView.vue'), 'utf8')
+const overviewSource = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/components/ContainerOverviewPanel.vue'), 'utf8')
+const routeSource = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/routes.ts'), 'utf8')
+const loadingRouteSource = readFileSync(resolve(process.cwd(), 'src/modules/loading-lists/routes.ts'), 'utf8')
+const navigationSource = readFileSync(resolve(process.cwd(), 'src/core/navigation/adminNavigation.ts'), 'utf8')
+const lastLegFeesSource = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/components/ContainerLastLegFeesPanel.vue'), 'utf8')
+
+describe('ContainerDetailView customs integration', () => {
+  it('renders the requested detail sections in the confirmed business order', () => {
+    const headings = [
+      'container-information-heading">货柜信息',
+      'container-voyage-heading">船名航次信息',
+      'container-customs-heading">{{ isDomestic',
+      'container-receiving-heading">装柜作业与国内出仓',
+    ]
+    let previous = -1
+    for (const heading of headings) {
+      const current = source.indexOf(heading)
+      expect(current, heading).toBeGreaterThan(previous)
+      previous = current
+    }
+  })
+
+  it('reuses the current schedule, customs, receipt and container-fee capabilities', () => {
+    expect(source).toContain('<CarrierScheduleQueryPanel')
+    expect(source).toContain(':sections="[\'documents\']"')
+    expect(source).toContain(':sections="[\'pda\']"')
+    expect(source).toContain('<LoadingListDetailDrawer')
+    expect(source).toContain('getConfirmedLoadingList')
+    expect(source).toContain('getPreloadPlan')
+    expect(source).toContain('label="装柜清单"')
+    expect(source).toContain('打印装柜清单')
+    expect(source).toContain("const loadingListMode = computed<LoadingListMode>(() => detail.value?.planStatus === 'COMPLETED' ? 'confirmed' : 'preload')")
+    expect(source).toContain('<LoadingListDetailDrawer dense :mode="loadingListMode" embedded')
+    expect(source).toContain(':sections="[\'pda\']"')
+  })
+
+  it('keeps the confirmed loading list inside the domestic container detail only', () => {
+    expect(routeSource).toContain("name: 'domestic-container-detail'")
+    expect(routeSource).toContain("name: 'overseas-container-detail'")
+    expect(loadingRouteSource).not.toContain("name: 'loading-lists'")
+    expect(navigationSource).not.toContain("title: '装柜清单'")
+    expect(source).toContain('<el-tabs v-model="activeTab"')
+    expect(source).toContain("v-if=\"isDomestic && activeTab === 'loading-list'\"")
+    expect(source).toContain("loadingDetail.value = await getConfirmedLoadingList(aggregate.loadingPlanId, resource.warehouseId)")
+    expect(source).toContain("getContainer(containerId.value, props.workbench), getContainerOverview(containerId.value)")
+    expect(source).toContain(':can-edit="false"')
+  })
+
+  it('keeps the loaded overview mounted while switching fee tabs', () => {
+    expect(source).toContain("v-show=\"activeTab === 'overview'\" class=\"detail-section surface-panel\" aria-labelledby=\"container-voyage-heading\"")
+    expect(source).toContain("v-if=\"isOverseas\" v-show=\"activeTab === 'overview'\"")
+    expect(source).not.toContain("v-if=\"activeTab === 'overview'\" class=\"detail-section surface-panel\"")
+  })
+
+  it('exposes empty return directly in overseas detail only when permission and server action both allow it', () => {
+    expect(source).toContain("access.can('platform:firstleg:terminal-drayage:empty-return:confirm')")
+    expect(source).toContain("hasAction('RECORD_EMPTY_RETURN')")
+    expect(source).toContain("terminalDrayage?.allowedActions.includes('RECORD_EMPTY_RETURN')")
+    expect(source).toContain('v-if="canRecordEmptyReturn" type="primary"')
+    expect(source).toContain('>确认还柜</el-button>')
+    expect(source).toContain('expectedVersion: current.version')
+    expect(source).toContain('actualAt: emptyReturnAt.value')
+    expect(source).toContain('remark: emptyReturnReason.value.trim() || undefined')
+    expect(source).toContain('await load()')
+  })
+
+  it('separates domestic first-leg fees and connects the overseas fee lifecycle lazily', () => {
+    expect(source).toContain('label="国内段费用（头程）" name="first-leg-fees"')
+    expect(source).toContain('label="目的港及海外段费用（尾程）" name="last-leg-fees"')
+    expect(source).toContain('v-if="canViewFirstLegFees && firstLegFeesOpened"')
+    expect(source).toContain('v-show="activeTab === \'first-leg-fees\'"')
+    expect(source).toContain('title="国内段费用（头程）" :plan-id="overview.loadingPlanId" :container-booking-id="detail.id"')
+    expect(source).not.toContain(':readonly="isOverseas"')
+    expect(source).toContain('v-if="canViewLastLegFees && lastLegFeesOpened"')
+    expect(source).toContain('title="目的港及海外段费用（尾程）"')
+    expect(source).not.toContain(':readonly="isDomestic"')
+    expect(source).toContain("if (isDomestic.value && activeTab.value === 'loading-list') await loadLoadingDetail(resource, aggregate)")
+    expect(source).toContain("const needsLoadingDetail = tabName === 'first-leg-fees' || (isDomestic.value && tabName === 'loading-list')")
+    expect(lastLegFeesSource.indexOf('label="操作"')).toBeLessThan(lastLegFeesSource.indexOf('label="客户"'))
+    expect(lastLegFeesSource).toContain('show-overflow-tooltip')
+    expect(lastLegFeesSource).toContain('尾程计费加载失败')
+    expect(lastLegFeesSource).toContain('empty-text="当前货柜暂无尾程费用"')
+    expect(lastLegFeesSource).toContain('v-loading="loading"')
+    expect(lastLegFeesSource).toContain("canEdit.value && access.can('platform:supplier:list') ? listContainerFeeSupplierOptions(null) : Promise.resolve([])")
+    expect(lastLegFeesSource).toContain("sourceType: 'OVERSEAS_CONTAINER_FEE', businessType: 'OVERSEAS_CONTAINER'")
+    expect(lastLegFeesSource).toContain("form.settlementMode === 'DIRECT_PAID'")
+    expect(lastLegFeesSource).toContain("access.can('platform:finance:fee-source:edit')")
+    expect(lastLegFeesSource).toContain("access.can('platform:finance:fee-source:review')")
+    expect(source).toContain("if (!overview.value?.loadingPlanId) return '当前货柜尚未关联装柜计划，暂无头程计费归属。'")
+    expect(source).toContain(':description="firstLegFeesEmptyReason"')
+    expect(source).toContain("const needsLoadingDetail = tabName === 'first-leg-fees' || (isDomestic.value && tabName === 'loading-list')")
+  })
+
+  it('uses domestic and overseas route-specific primary status and summary labels', () => {
+    expect(source).toContain("const primaryStatusText = computed(() => isDomestic.value ? statusText(detail.value?.planStatus) : overseasStageText.value)")
+    expect(source).toContain("UNLOADED: '待还柜'")
+    expect(source).toContain("EMPTY_RETURNED: '已还柜'")
+    expect(source).toContain("{{ isDomestic ? '装柜清单号' : '当前海外阶段' }}")
+    expect(source).toContain("{{ isDomestic ? '装柜仓库' : '目的仓 / 接柜仓' }}")
+    expect(source).toContain('emptyReturnWarningText')
+  })
+
+  it('mounts the new container customs panel only after loading completes', () => {
+    expect(source).toContain("detail.planStatus === 'COMPLETED' && overview?.loadingPlanId && canListCustoms")
+    expect(source).toContain('<ContainerCustomsPanel')
+    expect(source).toContain(':loading-plan-id="overview.loadingPlanId"')
+    expect(source).toContain(':can-manage="canManageCustoms"')
+  })
+
+  it('allows the overview panel to render only the section owned by each detail group', () => {
+    expect(overviewSource).toContain("sections?: Array<'exception' | 'documents' | 'pda'>")
+    expect(overviewSource).toContain("visibleSections.has('exception')")
+    expect(overviewSource).toContain("visibleSections.has('documents')")
+    expect(overviewSource).toContain("visibleSections.has('pda')")
+  })
+
+  it('removes the retired loading-list customs UI and calls', () => {
+    for (const retired of ['getLoadingDeclaration', 'uploadLoadingDeclaration', 'completeLoadingDeclaration', 'downloadLoadingDeclaration', 'CUSTOMS_DECLARATION']) {
+      expect(source).not.toContain(retired)
+      expect(overviewSource).not.toContain(retired)
+    }
+  })
+
+  it('offers the released-booking link workflow only for an eligible unlinked simulation container', () => {
+    expect(source).toContain("detail.value?.sourceType === 'SIMULATION'")
+    expect(source).toContain("!detail.value.oceanBookingId")
+    expect(source).toContain("['WAIT_LOADING', 'EDITING'].includes(detail.value.planStatus)")
+    expect(source).toContain('关联已放舱订舱')
+    expect(source).toContain('oceanBookingLinkOpen.value = true')
+    expect(source).toContain('<OceanBookingLinkDialog v-model="oceanBookingLinkOpen" :container="detail" @linked="load" />')
+    expect(source).not.toContain('linkContainerId')
+  })
+})
diff --git a/src/modules/container-loading/pages/ContainerDetailView.vue b/src/modules/container-loading/pages/ContainerDetailView.vue
new file mode 100644
index 00000000..82ccf5c7
--- /dev/null
+++ b/src/modules/container-loading/pages/ContainerDetailView.vue
@@ -0,0 +1,620 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, ref, watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { ArrowLeft, FileUp } from '@lucide/vue'
+import { ElMessage, ElMessageBox, type UploadFile } from 'element-plus'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import { CarrierScheduleQueryPanel } from '@/modules/port-schedules'
+import { ContainerFeesPanel, getConfirmedLoadingList, getPreloadPlan, LoadingListDetailDrawer, PalletLabelPrintDialog, type LoadingDetail, type LoadingListMode } from '@/modules/loading-lists'
+import {
+  confirmContainerOutboundDispatch,
+  getContainerOutboundDispatch,
+  type ContainerOutboundDispatchDetail,
+  type ContainerOutboundGateItem,
+} from '@/modules/outbound-dispatch'
+import ContainerCustomsPanel from '../components/ContainerCustomsPanel.vue'
+import ContainerLastLegFeesPanel from '../components/ContainerLastLegFeesPanel.vue'
+import ContainerOverviewPanel from '../components/ContainerOverviewPanel.vue'
+import OceanBookingLinkDialog from '../components/OceanBookingLinkDialog.vue'
+import { getSmartLoadingChannelGroup, isSeaRailChannel } from '../smartLoadingChannelGroups'
+import {
+  cancelContainerException,
+  completeContainerClearance,
+  downloadContainerClearance,
+  downloadContainerDocument,
+  getContainer,
+  getContainerClearance,
+  getContainerOverview,
+  markContainerException,
+  uploadContainerClearance,
+  uploadContainerDocument,
+  updateContainerPickupCode,
+} from '../api/platformContainerLoading'
+import { recordTerminalDrayageEmptyReturn } from '../api/terminalDrayages'
+import { listContainerArrivalTimes, type ContainerArrivalTime } from '../api/containerArrivalTimes'
+import type { BusinessDocument, ContainerBookingResource, ContainerOverview, ContainerOverviewDocument, ContainerPlanStatus, ContainerWorkbenchAction, ContainerWorkbenchRow } from '../types'
+
+const props = withDefaults(defineProps<{ workbench?: 'DOMESTIC' | 'OVERSEAS' }>(), { workbench: 'DOMESTIC' })
+
+const route = useRoute()
+const router = useRouter()
+const access = useAccessPreviewStore()
+const containerId = computed(() => String(route.params.containerId || ''))
+const isDomestic = computed(() => props.workbench === 'DOMESTIC')
+const isOverseas = computed(() => props.workbench === 'OVERSEAS')
+const activeTab = ref(route.query.tab === 'loading-list' ? 'loading-list' : 'overview')
+const canViewFirstLegFees = computed(() => access.can('firstleg:inbound:fee-detail:view'))
+const canViewLastLegFees = computed(() => access.can('platform:finance:customer-arap:list'))
+const firstLegFeesOpened = ref(false)
+const lastLegFeesOpened = ref(false)
+const feeCustomers = computed(() => {
+  const customers = new Map<string, string | null>()
+  for (const item of loadingDetail.value?.items || []) if (item.accountId) customers.set(item.accountId, item.customerName)
+  return [...customers].map(([accountId, customerName]) => ({ accountId, customerName }))
+})
+const feeBusinessReferences = computed(() => (loadingDetail.value?.items || []).map((item) => ({
+  accountId: item.accountId, customerName: item.customerName, orderId: item.orderId, orderNo: item.orderNo,
+  inboundId: item.inboundId, inboundCode: item.inboundCode,
+})))
+const firstLegFeesEmptyReason = computed(() => {
+  if (!overview.value?.loadingPlanId) return '当前货柜尚未关联装柜计划，暂无头程计费归属。'
+  if (!detail.value?.warehouseId) return '当前货柜尚未关联装柜仓库，无法加载头程计费归属。'
+  if (detail.value.planStatus === 'COMPLETED' && !canViewLoadingList.value) return '当前账号无权读取已确认装柜清单，无法查看头程计费。'
+  if (detail.value.planStatus !== 'COMPLETED' && !canViewPreload.value) return '当前账号无权读取预装计划，无法查看头程计费。'
+  return '当前柜次暂无可用费用归属明细。'
+})
+async function rememberWorkbenchTab(tabName: string | number) {
+  if ((tabName === 'first-leg-fees' && !canViewFirstLegFees.value) || (tabName === 'last-leg-fees' && !canViewLastLegFees.value)) {
+    activeTab.value = 'overview'
+    return
+  }
+  if (tabName === 'first-leg-fees') firstLegFeesOpened.value = true
+  if (tabName === 'last-leg-fees') lastLegFeesOpened.value = true
+  const needsLoadingDetail = tabName === 'first-leg-fees' || (isDomestic.value && tabName === 'loading-list')
+  if (needsLoadingDetail && detail.value && overview.value) {
+    await loadLoadingDetail(detail.value, overview.value)
+  }
+}
+const workbenchDetail = ref<ContainerWorkbenchRow | null>(null)
+const arrivalTime = ref<ContainerArrivalTime | null>(null)
+const hasAction = (action: ContainerWorkbenchAction) => Boolean(workbenchDetail.value?.allowedActions?.includes(action))
+const canEdit = computed(() => isDomestic.value && access.can('platform:firstleg:container:edit') && hasAction('EDIT_CONTAINER'))
+const canManageCustoms = computed(() => isDomestic.value && access.can('platform:firstleg:customs:manage') && hasAction('MANAGE_CUSTOMS'))
+const canManageDestinationDocuments = computed(() => isOverseas.value && access.can('platform:firstleg:terminal-drayage:document:edit') && hasAction('MANAGE_DESTINATION_DOCUMENTS'))
+const deliveryOrderBlockedReason = computed(() => {
+  if (isSeaRailChannel(detail.value?.channelCode)) return '海铁渠道不适用 DO 资料'
+  if (detail.value?.planStatus !== 'COMPLETED' || !detail.value?.outboundConfirmedAt) return '货柜进入海外履约后才可上传'
+  if (detail.value?.actualEmptyReportedAt) return '货柜已还柜，不可再上传'
+  return null
+})
+const canRecordEmptyReturn = computed(() => isOverseas.value
+  && access.can('platform:firstleg:terminal-drayage:empty-return:confirm')
+  && hasAction('RECORD_EMPTY_RETURN')
+  && Boolean(workbenchDetail.value?.terminalDrayage?.allowedActions.includes('RECORD_EMPTY_RETURN')))
+const canListCustoms = computed(() => access.can('platform:firstleg:customs:list'))
+const canViewOutboundDispatch = computed(() => access.can('platform:firstleg:outbound-dispatch:view'))
+const canConfirmOutboundDispatch = computed(() => access.can('platform:firstleg:outbound-dispatch:confirm'))
+const canViewPreload = computed(() => access.can('platform:firstleg:preload:list'))
+const canViewLoadingList = computed(() => access.can('platform:firstleg:loading-list:list'))
+const canViewCurrentLoadingList = computed(() => {
+  if (!isDomestic.value || !detail.value) return false
+  if (detail.value.planStatus === 'COMPLETED') return canViewLoadingList.value
+  return ['WAIT_LOADING', 'EDITING', 'LOADING'].includes(detail.value.planStatus) && canViewPreload.value
+})
+const canLinkOceanBooking = computed(() => Boolean(canEdit.value
+  && detail.value?.sourceType === 'SIMULATION'
+  && !detail.value.oceanBookingId
+  && ['WAIT_LOADING', 'EDITING'].includes(detail.value.planStatus)))
+const loading = ref(false)
+const detail = ref<ContainerBookingResource | null>(null)
+const overview = ref<ContainerOverview | null>(null)
+const error = ref<ApiErrorDetails | null>(null)
+const overviewError = ref<ApiErrorDetails | null>(null)
+const documentOpen = ref(false)
+type UploadDocumentType = 'DELIVERY_ORDER'
+const documentType = ref<UploadDocumentType>('DELIVERY_ORDER')
+const documentFile = ref<File | null>(null)
+const documentUploadKey = ref(0)
+const documentSaving = ref(false)
+const documentDownloading = ref(false)
+const documentError = ref<ApiErrorDetails | null>(null)
+const documentRefreshWarning = ref<ApiErrorDetails | null>(null)
+const pickupCodeSaving = ref(false)
+const clearanceOpen = ref(false)
+const clearanceDocument = ref<BusinessDocument | null>(null)
+const clearanceFile = ref<File | null>(null)
+const clearanceLoading = ref(false)
+const clearanceSaving = ref(false)
+const clearanceError = ref<ApiErrorDetails | null>(null)
+const exceptionOpen = ref(false)
+const exceptionReason = ref('')
+const exceptionSaving = ref(false)
+const exceptionError = ref<ApiErrorDetails | null>(null)
+const outboundLoading = ref(false)
+const outboundConfirming = ref(false)
+const outboundDetail = ref<ContainerOutboundDispatchDetail | null>(null)
+const outboundError = ref<ApiErrorDetails | null>(null)
+const showPassedGates = ref(false)
+const carrierRefreshKey = ref(0)
+const loadingDetail = ref<LoadingDetail | null>(null)
+const loadingDetailLoading = ref(false)
+const loadingDetailError = ref<ApiErrorDetails | null>(null)
+const emptyReturnOpen = ref(false)
+const emptyReturnAt = ref('')
+const emptyReturnReason = ref('')
+const emptyReturnSaving = ref(false)
+const emptyReturnError = ref<ApiErrorDetails | null>(null)
+const oceanBookingLinkOpen = ref(false)
+
+const selectedDocument = computed(() => overview.value?.documents.find((item) => item.documentType === documentType.value) || null)
+const documentTitle = computed(() => 'DO 资料')
+const title = computed(() => detail.value?.containerNo || detail.value?.cabinetNo || '货柜详情')
+const overseasStageText = computed(() => {
+  const status = workbenchDetail.value?.statusSummary?.terminalDrayageStatus
+    || workbenchDetail.value?.terminalDrayage?.status
+    || workbenchDetail.value?.workbenchStage
+  return ({
+    WAIT_LOADING: '待装柜', LOADING: '装柜中', WAIT_CUSTOMS: '待出口报关', WAIT_OUTBOUND: '待国内出仓',
+    DEPARTED_WAREHOUSE: '已从国内仓出仓', IN_TRANSIT: '海运在途', ARRIVED_DESTINATION_PORT: '已到目的港',
+    WAITING_FOR_ARRIVAL: '待到港', ARRIVED: '已到港', PICKUP_READY: '可安排提柜', PICKUP_SCHEDULED: '已预约提柜',
+    PICKED_UP: '已提柜', UNLOADED: '待还柜', EMPTY_RETURNED: '已还柜',
+  } as Record<string, string>)[status || ''] || '海外履约中'
+})
+const primaryStatusText = computed(() => isDomestic.value ? statusText(detail.value?.planStatus) : overseasStageText.value)
+const loadingListMode = computed<LoadingListMode>(() => detail.value?.planStatus === 'COMPLETED' ? 'confirmed' : 'preload')
+const loadingListHeading = computed(() => loadingListMode.value === 'confirmed' ? '装柜清单' : '预装清单')
+const loadingListDescription = computed(() => loadingListMode.value === 'confirmed'
+  ? '装柜明细、PDA 证据与报关关联均以当前柜次为边界。'
+  : '核对预装明细与 PDA 作业准备情况，装柜完成后再处理整柜报关。')
+const overseasDestinationText = computed(() => {
+  const bookingDestination = [detail.value?.destinationWarehouseCode, detail.value?.destinationWarehouseName]
+    .filter(Boolean).join(' / ')
+  if (bookingDestination) return bookingDestination
+  const destinations = new Set((loadingDetail.value?.items || [])
+    .map((item) => String(item.destinationWarehouse || '').trim()).filter(Boolean))
+  return [...destinations].join('、') || '—'
+})
+const plannedChannelName = computed(() => getSmartLoadingChannelGroup(detail.value?.channelGroupCode)?.name || '—')
+const emptyReturnWarningText = computed(() => {
+  const warning = workbenchDetail.value?.terminalDrayage?.emptyReturnWarning
+  if (!warning || warning.status === 'NOT_APPLICABLE') return '当前暂无还空预警'
+  if (warning.status === 'RESOLVED') return `已完成还柜${warning.deadlineAt ? ` · 截止 ${formatTime(warning.deadlineAt)}` : ''}`
+  const overdue = warning.status === 'OVERDUE' ? (warning.overdueDays > 0 ? `已超时 ${warning.overdueDays} 天` : `已超时 ${warning.overdueHours} 小时`) : '待还柜'
+  return `${overdue}${warning.deadlineAt ? ` · 截止 ${formatTime(warning.deadlineAt)}` : ''}`
+})
+const exceptionTitle = computed(() => overview.value?.exception.active ? '取消货柜异常' : '标记货柜异常')
+type AggregatedGateRow = ContainerOutboundGateItem & { key: string; inboundCodes: string[] }
+const referenceOnlyGateCodes = new Set(['TRUCK_DEPARTED', 'SAILING_SCHEDULE'])
+const outboundGateRows = computed<AggregatedGateRow[]>(() => {
+  const grouped = new Map<string, AggregatedGateRow>()
+  for (const inbound of outboundDetail.value?.aggregate.gate.inbounds || []) {
+    for (const item of inbound.gate.items || []) {
+      if (referenceOnlyGateCodes.has(item.code)) continue
+      const key = JSON.stringify([item.code, item.passed, item.actual ?? null, item.requirement ?? null, item.name])
+      const existing = grouped.get(key)
+      if (existing) {
+        if (!existing.inboundCodes.includes(inbound.inboundCode)) existing.inboundCodes.push(inbound.inboundCode)
+      } else grouped.set(key, { ...item, key, inboundCodes: [inbound.inboundCode] })
+    }
+  }
+  return [...grouped.values()]
+})
+const visibleOutboundGateRows = computed(() => showPassedGates.value ? outboundGateRows.value : outboundGateRows.value.filter((row) => !row.passed))
+const outboundGateSummary = computed(() => ({
+  total: outboundGateRows.value.length,
+  passed: outboundGateRows.value.filter((row) => row.passed).length,
+  blocked: outboundGateRows.value.filter((row) => !row.passed).length,
+}))
+const canConfirmDeparture = computed(() => canConfirmOutboundDispatch.value
+  && hasAction('CONFIRM_OUTBOUND')
+  && outboundDetail.value?.aggregate.dispatchStatus === 'READY_FOR_DISPATCH'
+  && outboundGateSummary.value.blocked === 0)
+const customsDepartureState = computed<'DEPARTED' | 'WAITING_OTHER_GATES' | 'UNKNOWN'>(() =>
+  !outboundDetail.value ? 'UNKNOWN'
+    : outboundDetail.value.aggregate.dispatchStatus === 'WAITING_FOR_LOADING' ? 'DEPARTED' : 'WAITING_OTHER_GATES')
+function openOceanBookingLink() {
+  if (!detail.value || !canLinkOceanBooking.value) return
+  oceanBookingLinkOpen.value = true
+}
+
+function toOverviewDocument(document: BusinessDocument, documentType: string, fallback?: ContainerOverviewDocument | null): ContainerOverviewDocument {
+  return {
+    id: document.id || fallback?.id || document.fileId,
+    documentType, fileId: document.fileId, fileName: document.fileName, fileHash: document.fileHash,
+    uploadedBy: document.uploadedBy, uploadedByName: document.uploadedByName, uploadedAt: document.uploadedAt,
+    version: document.version, completed: Boolean(document.completedAt),
+  }
+}
+function replaceOverviewDocument(document: ContainerOverviewDocument) {
+  if (!overview.value) return
+  overview.value = { ...overview.value, documents: [...overview.value.documents.filter((item) => item.documentType !== document.documentType), document] }
+}
+async function refreshOverviewDocument(documentType: 'DESTINATION_CLEARANCE') {
+  let refreshCause: unknown
+  let refreshed: ContainerOverview | null = null
+  try { refreshed = await getContainerOverview(containerId.value) } catch (cause) { refreshCause = cause }
+  let current = refreshed?.documents.find((item) => item.documentType === documentType) || null
+  if (!current) {
+    try {
+      const business = await getContainerClearance(containerId.value)
+      if (business) {
+        if (documentType === 'DESTINATION_CLEARANCE') clearanceDocument.value = business
+        current = toOverviewDocument(business, documentType, overview.value?.documents.find((item) => item.documentType === documentType))
+      }
+    } catch (cause) { if (!refreshCause) refreshCause = cause }
+  }
+  if (refreshed) overview.value = current && !refreshed.documents.some((item) => item.documentType === documentType)
+    ? { ...refreshed, documents: [...refreshed.documents, current] }
+    : refreshed
+  else if (current) replaceOverviewDocument(current)
+  else if (refreshCause) throw refreshCause
+  return current
+}
+
+function statusText(status?: ContainerPlanStatus | null) { return status ? ({ WAIT_LOADING: '待装柜', EDITING: '预装柜中', LOADING: '拣货中', COMPLETED: '装柜完成' })[status] : '—' }
+function formatTime(value?: string | null) { return value?.replace('T', ' ').slice(0, 16) || '—' }
+function localDateTimeValue() {
+  const now = new Date(Date.now() - new Date().getTimezoneOffset() * 60_000)
+  return now.toISOString().slice(0, 19)
+}
+function openEmptyReturn() {
+  if (!canRecordEmptyReturn.value || emptyReturnSaving.value) return
+  emptyReturnAt.value = localDateTimeValue()
+  emptyReturnReason.value = ''
+  emptyReturnError.value = null
+  emptyReturnOpen.value = true
+}
+async function confirmEmptyReturn() {
+  const current = workbenchDetail.value?.terminalDrayage
+  if (!current || !canRecordEmptyReturn.value || !emptyReturnAt.value || emptyReturnSaving.value) return
+  emptyReturnSaving.value = true
+  emptyReturnError.value = null
+  try {
+    await recordTerminalDrayageEmptyReturn(containerId.value, {
+      expectedVersion: current.version,
+      actualAt: emptyReturnAt.value,
+      remark: emptyReturnReason.value.trim() || undefined,
+    })
+    emptyReturnOpen.value = false
+    ElMessage.success('还柜已确认')
+    await load()
+  } catch (cause) {
+    const details = getApiErrorDetails(cause, '确认还柜失败')
+    if (details.code === 'A0409') await load()
+    emptyReturnError.value = details
+  } finally { emptyReturnSaving.value = false }
+}
+
+async function load() {
+  if (!containerId.value) return
+  loading.value = true; error.value = null; overviewError.value = null
+  try {
+    const [resource, aggregate, arrivals] = await Promise.all([
+      getContainer(containerId.value, props.workbench),
+      getContainerOverview(containerId.value),
+      isOverseas.value ? listContainerArrivalTimes([containerId.value]) : Promise.resolve([]),
+    ])
+    workbenchDetail.value = resource; detail.value = resource; overview.value = aggregate
+    arrivalTime.value = arrivals[0] || null
+    if (activeTab.value === 'loading-list' && !canViewCurrentLoadingList.value) activeTab.value = 'overview'
+    if (isDomestic.value && activeTab.value === 'loading-list') await loadLoadingDetail(resource, aggregate)
+    if (isOverseas.value && resource.planStatus === 'COMPLETED' && canViewLoadingList.value) {
+      await loadLoadingDetail(resource, aggregate)
+    }
+  } catch (cause) { error.value = getApiErrorDetails(cause, '货柜详情加载失败') }
+  finally { loading.value = false }
+}
+
+watch(
+  () => !loading.value && isDomestic.value && detail.value?.planStatus === 'COMPLETED'
+    && canViewOutboundDispatch.value ? containerId.value : null,
+  (eligibleContainerId) => {
+    if (eligibleContainerId) void loadOutboundDispatch()
+    else { outboundDetail.value = null; outboundError.value = null }
+  },
+)
+
+async function loadOutboundDispatch() {
+  if (!containerId.value || !canViewOutboundDispatch.value) return
+  outboundLoading.value = true; outboundError.value = null; showPassedGates.value = false
+  try { outboundDetail.value = await getContainerOutboundDispatch(containerId.value) }
+  catch (cause) { outboundDetail.value = null; outboundError.value = getApiErrorDetails(cause, '国内出仓门禁加载失败') }
+  finally { outboundLoading.value = false }
+}
+
+async function loadLoadingDetail(resource: ContainerBookingResource, aggregate: ContainerOverview) {
+  if (loadingDetail.value || loadingDetailLoading.value) return
+  loadingDetail.value = null; loadingDetailError.value = null
+  if (!aggregate.loadingPlanId || !resource.warehouseId) return
+  loadingDetailLoading.value = true
+  try {
+    if (resource.planStatus === 'COMPLETED') {
+      if (!canViewLoadingList.value) return
+      loadingDetail.value = await getConfirmedLoadingList(aggregate.loadingPlanId, resource.warehouseId)
+      return
+    }
+    if (!canViewPreload.value) return
+    loadingDetail.value = await getPreloadPlan(aggregate.loadingPlanId, resource.warehouseId)
+  } catch (cause) {
+    loadingDetailError.value = getApiErrorDetails(cause, '装柜清单加载失败')
+  } finally {
+    loadingDetailLoading.value = false
+  }
+}
+async function refreshAfterCustoms() {
+  if (canViewOutboundDispatch.value) await loadOutboundDispatch()
+  try { overview.value = await getContainerOverview(containerId.value) } catch { /* 报关操作已成功，保留组件返回事实 */ }
+}
+
+async function confirmDeparture() {
+  const aggregate = outboundDetail.value?.aggregate
+  if (!aggregate || !canConfirmDeparture.value || outboundConfirming.value) return
+  outboundConfirming.value = true
+  try {
+    await ElMessageBox.confirm('确认整柜已离开国内仓？系统将再次校验柜内全部入库绑定，成功后自动创建船节点查询任务。', '确认国内出仓', { customClass: 'admin-density-confirm', type: 'warning', confirmButtonText: '确认离仓' })
+  } catch { outboundConfirming.value = false; return }
+  outboundError.value = null
+  try {
+    outboundDetail.value = await confirmContainerOutboundDispatch(containerId.value, {
+      expectedVersion: aggregate.version,
+      remark: '货柜详情确认国内出仓',
+    })
+    carrierRefreshKey.value += 1
+    ElMessage.success('整柜国内出仓已确认，船节点查询任务正在刷新')
+    try { overview.value = await getContainerOverview(containerId.value) }
+    catch (cause) { outboundError.value = getApiErrorDetails(cause, '离仓已确认，但货柜履约摘要刷新失败') }
+  } catch (cause) {
+    const details = getApiErrorDetails(cause, '确认国内出仓失败')
+    if (details.code === 'A0409') await loadOutboundDispatch()
+    outboundError.value = details
+  } finally { outboundConfirming.value = false }
+}
+
+function outboundStatusText(status?: string | null) {
+  return ({ READY_FOR_DISPATCH: '待确认离仓', WAITING_FOR_LOADING: '已确认离仓' } as Record<string, string>)[status || ''] || status || '—'
+}
+function truckReferenceText(status?: string | null) {
+  return ({ SCHEDULED: '已预约', ARRIVED: '已到仓', DEPARTED: '已离仓', COMPLETED: '已完成' } as Record<string, string>)[status || ''] || status || '未关联'
+}
+
+function openDocument(type: string) {
+  if (type === 'DESTINATION_CLEARANCE') { if (canManageDestinationDocuments.value) void openClearance(); return }
+  if (type !== 'DELIVERY_ORDER' || !canManageDestinationDocuments.value) return
+  if (deliveryOrderBlockedReason.value) { ElMessage.warning(deliveryOrderBlockedReason.value); return }
+  documentType.value = type as UploadDocumentType
+  documentFile.value = null; documentError.value = null; documentRefreshWarning.value = null; documentUploadKey.value += 1; documentOpen.value = true
+}
+function selectDocumentFile(file: UploadFile) { documentFile.value = file.raw || null; documentError.value = null }
+function removeDocumentFile() { documentFile.value = null }
+async function saveDocument() {
+  if (!documentFile.value || !overview.value || !detail.value) { documentError.value = { code: 'FILE_REQUIRED', message: '请选择需要上传的资料文件' }; return }
+  documentSaving.value = true; documentError.value = null; documentRefreshWarning.value = null
+  try {
+    const expectedVersion = selectedDocument.value?.version || 0
+    const targetType = documentType.value
+    const targetTitle = documentTitle.value
+    const uploaded = await uploadContainerDocument(containerId.value, targetType, documentFile.value, expectedVersion, `上传${targetTitle}`)
+    if (!uploaded) throw new Error(`${targetTitle}上传成功但未返回附件信息`)
+    const optimistic = toOverviewDocument(uploaded, targetType, selectedDocument.value)
+    replaceOverviewDocument(optimistic)
+    documentOpen.value = false; documentFile.value = null; documentError.value = null; documentUploadKey.value += 1
+    ElMessage.success(`${targetTitle}已上传`)
+    try {
+      const refreshed = await getContainerOverview(containerId.value)
+      const current = refreshed.documents.find((item) => item.documentType === targetType)
+      if (current && (current.fileId === optimistic.fileId || current.version > optimistic.version)) overview.value = refreshed
+      else {
+        overview.value = { ...refreshed, documents: [...refreshed.documents.filter((item) => item.documentType !== targetType), optimistic] }
+        documentRefreshWarning.value = { code: 'DOCUMENT_OVERVIEW_STALE', message: `${targetTitle}已上传，但资料汇总尚未同步；当前已保留本次上传结果` }
+      }
+    } catch (cause) { documentRefreshWarning.value = getApiErrorDetails(cause, `${targetTitle}已上传，但最新资料刷新失败；当前已保留本次上传结果`) }
+  } catch (cause) {
+    const details = getApiErrorDetails(cause, `${documentTitle.value}上传失败`)
+    if (details.code === 'A0409') try { overview.value = await getContainerOverview(containerId.value) } catch { /* 保留原并发错误证据 */ }
+    documentError.value = details
+  }
+  finally { documentSaving.value = false }
+}
+async function saveBlob(blob: Blob, fileName: string) { const url = URL.createObjectURL(blob); const anchor = document.createElement('a'); anchor.href = url; anchor.download = fileName || '货柜资料'; anchor.click(); URL.revokeObjectURL(url) }
+async function downloadDocument(item: ContainerOverviewDocument) {
+  if (!['DELIVERY_ORDER', 'DESTINATION_CLEARANCE'].includes(item.documentType)) return
+  documentDownloading.value = true
+  try {
+    const blob = item.documentType === 'DESTINATION_CLEARANCE'
+        ? await downloadContainerClearance(containerId.value, item.fileId)
+        : await downloadContainerDocument(containerId.value, 'DELIVERY_ORDER', item.fileId)
+    await saveBlob(blob, item.fileName); ElMessage.success('资料下载已开始')
+  } catch (cause) {
+    const details = getApiErrorDetails(cause, '资料下载失败')
+    if (item.documentType === 'DESTINATION_CLEARANCE') clearanceError.value = details
+    ElMessage.error(details.message)
+  }
+  finally { documentDownloading.value = false }
+}
+async function savePickupCode(pickupCode: string) {
+  if (!overview.value || !canManageDestinationDocuments.value || !/^[0-9]{1,64}$/.test(pickupCode)) return
+  pickupCodeSaving.value = true; documentRefreshWarning.value = null
+  try {
+    const refreshed = await updateContainerPickupCode(containerId.value, pickupCode, overview.value.container.version)
+    overview.value = refreshed
+    if (detail.value) detail.value = { ...detail.value, pickupCode: refreshed.container.pickupCode, pickupCodeUpdatedBy: refreshed.container.pickupCodeUpdatedBy, pickupCodeUpdatedByName: refreshed.container.pickupCodeUpdatedByName, pickupCodeUpdatedAt: refreshed.container.pickupCodeUpdatedAt, version: refreshed.container.version }
+    ElMessage.success('PU 码已保存')
+  } catch (cause) {
+    const details = getApiErrorDetails(cause, 'PU 码保存失败')
+    documentRefreshWarning.value = details
+    if (details.code === 'A0409') try { overview.value = await getContainerOverview(containerId.value) } catch { /* 保留并发错误证据 */ }
+  } finally { pickupCodeSaving.value = false }
+}
+function openException() { exceptionReason.value = ''; exceptionError.value = null; exceptionOpen.value = true }
+async function saveException() {
+  if (!overview.value || !exceptionReason.value.trim()) { exceptionError.value = { code: 'REASON_REQUIRED', message: '请输入异常原因或取消备注' }; return }
+  exceptionSaving.value = true; exceptionError.value = null
+  try {
+    const action = overview.value.exception.active ? cancelContainerException : markContainerException
+    await action(containerId.value, overview.value.container.version, exceptionReason.value.trim())
+    overview.value = await getContainerOverview(containerId.value)
+    exceptionOpen.value = false; ElMessage.success(overview.value.exception.active ? '货柜已标记异常' : '货柜异常已取消')
+  } catch (cause) { exceptionError.value = getApiErrorDetails(cause, '货柜异常处理失败') }
+  finally { exceptionSaving.value = false }
+}
+
+async function openClearance() {
+  clearanceOpen.value = true; clearanceDocument.value = null; clearanceFile.value = null; clearanceError.value = null; documentRefreshWarning.value = null; clearanceLoading.value = true
+  try { clearanceDocument.value = await getContainerClearance(containerId.value) }
+  catch (cause) { const details = getApiErrorDetails(cause); if (details.code !== 'A0404') clearanceError.value = details }
+  finally { clearanceLoading.value = false }
+}
+function selectClearanceFile(file: UploadFile) { clearanceFile.value = file.raw || null; clearanceError.value = null }
+function removeClearanceFile() { clearanceFile.value = null }
+async function uploadClearance() {
+  if (!clearanceFile.value) { clearanceError.value = { code: 'FILE_REQUIRED', message: '请选择目的港清关资料文件' }; return }
+  clearanceSaving.value = true; clearanceError.value = null; documentRefreshWarning.value = null
+  try {
+    const uploaded = await uploadContainerClearance(containerId.value, clearanceFile.value, clearanceDocument.value?.version || 0, '上传目的港清关资料')
+    if (!uploaded) throw new Error('目的港清关资料上传成功但未返回附件信息')
+    clearanceDocument.value = uploaded
+    replaceOverviewDocument(toOverviewDocument(uploaded, 'DESTINATION_CLEARANCE', overview.value?.documents.find((item) => item.documentType === 'DESTINATION_CLEARANCE')))
+    clearanceOpen.value = false; clearanceFile.value = null; clearanceError.value = null
+    ElMessage.success('目的港清关资料已上传')
+    try {
+      const refreshed = await getContainerOverview(containerId.value)
+      overview.value = refreshed.documents.some((item) => item.documentType === 'DESTINATION_CLEARANCE') ? refreshed : { ...refreshed, documents: [...refreshed.documents, toOverviewDocument(uploaded, 'DESTINATION_CLEARANCE')] }
+    } catch (cause) { documentRefreshWarning.value = getApiErrorDetails(cause, '目的港清关资料已上传，但最新资料刷新失败；当前已保留本次上传结果') }
+  } catch (cause) {
+    const details = getApiErrorDetails(cause, '目的港清关资料上传失败')
+    if (details.code === 'A0409') {
+      try { await refreshOverviewDocument('DESTINATION_CLEARANCE') } catch { /* 保留原并发错误证据 */ }
+    }
+    clearanceError.value = details
+  }
+  finally { clearanceSaving.value = false }
+}
+async function completeClearance() {
+  if (!clearanceDocument.value) return
+  clearanceSaving.value = true; clearanceError.value = null; documentRefreshWarning.value = null
+  try {
+    const completed = await completeContainerClearance(containerId.value, clearanceDocument.value.version, '确认目的港清关完成')
+    if (!completed) throw new Error('确认清关完成但未返回附件信息')
+    clearanceDocument.value = completed
+    const optimistic = toOverviewDocument(completed, 'DESTINATION_CLEARANCE')
+    replaceOverviewDocument(optimistic)
+    clearanceOpen.value = false; clearanceFile.value = null; clearanceError.value = null
+    ElMessage.success('已完成清关')
+    try {
+      const refreshed = await getContainerOverview(containerId.value)
+      overview.value = refreshed.documents.some((item) => item.documentType === 'DESTINATION_CLEARANCE') ? refreshed : { ...refreshed, documents: [...refreshed.documents, optimistic] }
+    } catch (cause) { documentRefreshWarning.value = getApiErrorDetails(cause, '目的港清关已完成，但最新资料刷新失败；当前已保留完成事实') }
+  }
+  catch (cause) { clearanceError.value = getApiErrorDetails(cause, '清关完成失败') }
+  finally { clearanceSaving.value = false }
+}
+
+function goBack() { void router.push({ name: isDomestic.value ? 'domestic-container-workbench' : 'overseas-container-workbench' }) }
+function printLoadingList() { window.print() }
+
+onMounted(async () => { await load(); if (isOverseas.value && route.query.action === 'documents') openDocument('DELIVERY_ORDER') })
+</script>
+
+<template>
+  <AdminPage class="container-detail-page admin-density">
+    <section class="container-overview surface-panel">
+      <header class="container-overview__header"><el-button link class="density-back" type="primary" @click="goBack"><ArrowLeft :size="16" />返回列表</el-button><div><h1>{{ title }}</h1>
+        <!-- <p>{{ isDomestic ? '送柜、装柜、出口报关与国内出仓' : '海运节点、目的港清关、提柜与还空' }}</p> -->
+      </div><StatusBadge v-if="detail" :status="primaryStatusText" /></header>
+      <div v-if="detail" class="container-overview__summary"><div><span>柜次号</span><strong>{{ detail.cabinetNo || '—' }}</strong></div><div><span>集装箱号</span><strong>{{ detail.containerNo || '待补录' }}</strong></div><div><span>{{ isDomestic ? '装柜清单号' : '当前海外阶段' }}</span><strong>{{ isDomestic ? (detail.planNo || '—') : primaryStatusText }}</strong></div><div><span>{{ isDomestic ? '柜型' : '起运仓' }}</span><strong>{{ isDomestic ? (detail.containerType || '—') : (detail.warehouseName || '—') }}</strong></div><div><span>{{ isDomestic ? '装柜仓库' : '目的仓 / 接柜仓' }}</span><strong :title="isDomestic ? detail.warehouseName || '—' : overseasDestinationText">{{ isDomestic ? (detail.warehouseName || '—') : overseasDestinationText }}</strong></div></div>
+      <div v-if="isOverseas && detail" class="overseas-stage-strip" :class="{ 'is-overdue': workbenchDetail?.terminalDrayage?.emptyReturnWarning.status === 'OVERDUE' }"><div><span>当前海外履约状态</span><strong>{{ primaryStatusText }}</strong></div><p>{{ emptyReturnWarningText }}</p></div>
+    </section>
+    <LoadErrorState v-if="error" title="货柜详情加载失败" :message="error.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="error" /></template></LoadErrorState>
+    <template v-else-if="detail">
+      <el-tabs v-model="activeTab" class="workbench-tabs density-element-tabs" @tab-change="rememberWorkbenchTab">
+        <el-tab-pane :label="isDomestic ? '送柜报关' : '清关提柜'" name="overview"><template #label><span class="workbench-tab-label"><span class="density-tab-icon" aria-hidden="true">📋</span><span>{{ isDomestic ? '送柜报关' : '清关提柜' }}</span></span></template></el-tab-pane>
+        <el-tab-pane v-if="canViewCurrentLoadingList" label="装柜清单" name="loading-list"><template #label><span class="workbench-tab-label"><span class="density-tab-icon" aria-hidden="true">📦</span><span>装柜清单</span></span></template></el-tab-pane>
+        <el-tab-pane v-if="canViewFirstLegFees" label="国内段费用（头程）" name="first-leg-fees"><template #label><span class="workbench-tab-label"><span class="density-tab-icon" aria-hidden="true">💰</span><span>国内段费用（头程）</span></span></template></el-tab-pane>
+        <el-tab-pane v-if="canViewLastLegFees" label="目的港及海外段费用（尾程）" name="last-leg-fees"><template #label><span class="workbench-tab-label"><span class="density-tab-icon" aria-hidden="true">💰</span><span>目的港及海外段费用（尾程）</span></span></template></el-tab-pane>
+      </el-tabs>
+      <LoadErrorState v-if="overviewError" compact title="履约摘要加载失败" :message="overviewError.message" :show-retry="false" />
+      <section v-show="activeTab === 'overview'" class="detail-section surface-panel" aria-labelledby="container-information-heading">
+        <header class="detail-section__heading"><h2 id="container-information-heading">货柜信息</h2><PalletLabelPrintDialog dense v-if="overview?.loadingPlanId && detail.warehouseId" :plan-id="overview.loadingPlanId" :warehouse-id="detail.warehouseId" :disabled="!detail.containerNo || detail.planStatus === 'EDITING'" /></header>
+        <div class="detail-fields"><dl class="density-fields"><div><dt>真实订舱</dt><dd><span>{{ detail.oceanBookingId ? (detail.billOfLadingNo || '已关联') : '未关联' }}</span><el-button v-if="canLinkOceanBooking" class="density-action" data-tone="primary" @click="openOceanBookingLink">关联已放舱订舱</el-button></dd></div><div><dt>计划渠道</dt><dd>{{ plannedChannelName }}</dd></div><div><dt>实际渠道</dt><dd>{{ detail.channelName || '待关联订舱' }}</dd></div><div><dt>异常状态</dt><dd>{{ detail.exceptionActive ? '异常' : '正常' }}</dd></div><div><dt>目的仓</dt><dd>{{ overseasDestinationText }}</dd></div><div><dt>拖车公司</dt><dd>{{ detail.terminalTruckingCompany || workbenchDetail?.terminalDrayage?.fleetSupplierName || '—' }}</dd></div></dl></div>
+        <ContainerOverviewPanel v-if="isDomestic && overview" :overview="overview" :sections="['exception']" :can-manage-documents="canEdit" :can-manage-customs="canManageCustoms" :can-manage-exception="canEdit" @manage-exception="openException" />
+      </section>
+
+      <section v-show="activeTab === 'overview'" class="detail-section surface-panel" aria-labelledby="container-voyage-heading">
+        <h2 id="container-voyage-heading">船名航次信息</h2>
+        <div class="detail-fields"><dl class="density-fields"><div><dt>船公司</dt><dd>{{ detail.shippingCompanyName || '—' }}</dd></div><div><dt>船名 / 航次</dt><dd>{{ [detail.vesselName, detail.voyageNo].filter(Boolean).join(' / ') || '—' }}</dd></div><div><dt>预计开船</dt><dd>{{ formatTime(detail.estimatedSailingAt) }}</dd></div><div><dt>预计到港</dt><dd>{{ formatTime(detail.estimatedPortArrivalAt) }}</dd></div></dl></div>
+        <div class="carrier-panel"><CarrierScheduleQueryPanel dense :key="carrierRefreshKey" :ocean-booking-id="detail.oceanBookingId" :container-booking-id="detail.id" :warehouse-timeline="overview?.timeline || []" /></div>
+      </section>
+
+      <section v-show="activeTab === 'overview'" class="detail-section surface-panel" aria-labelledby="container-customs-heading">
+        <h2 id="container-customs-heading">{{ isDomestic ? '出口报关信息' : '目的港清关与提柜资料' }}</h2>
+        <ContainerOverviewPanel v-if="isOverseas && overview" :overview="overview" :sections="['documents']" :can-manage-documents="canManageDestinationDocuments" :can-manage-customs="canManageDestinationDocuments" :can-manage-exception="false" :document-busy="documentDownloading" :pickup-code-busy="pickupCodeSaving" :delivery-order-blocked-reason="deliveryOrderBlockedReason" @upload-document="openDocument" @download-document="downloadDocument" @save-pickup-code="savePickupCode" />
+        <el-alert v-if="documentRefreshWarning" type="warning" :closable="false" :title="documentRefreshWarning.message"><template #default><ApiErrorMeta :details="documentRefreshWarning" /></template></el-alert>
+        <ContainerCustomsPanel v-if="isDomestic && detail.planStatus === 'COMPLETED' && overview?.loadingPlanId && canListCustoms" :loading-plan-id="overview.loadingPlanId" :can-list="canListCustoms" :can-manage="canManageCustoms" :departure-state="customsDepartureState" @refreshed="refreshAfterCustoms" />
+      </section>
+
+      <section v-if="isDomestic" v-show="activeTab === 'overview'" class="detail-section surface-panel" aria-labelledby="container-receiving-heading">
+        <h2 id="container-receiving-heading">装柜作业与国内出仓</h2>
+        <ContainerOverviewPanel v-if="overview" :overview="overview" :sections="['pda']" :can-manage-documents="canEdit" :can-manage-customs="canManageCustoms" :can-manage-exception="canEdit" />
+        <div v-if="detail.planStatus === 'COMPLETED' && canViewOutboundDispatch" class="outbound-panel" aria-label="国内出仓门禁">
+        <header class="outbound-panel__header"><div><h2>国内出仓门禁</h2><p>按整柜核验全部入库绑定，仅确认一次离仓。</p></div><div v-if="outboundDetail" class="outbound-panel__actions"><el-tag :type="outboundGateSummary.blocked === 0 ? 'success' : 'danger'">{{ outboundGateSummary.blocked === 0 ? '门禁通过' : '门禁阻断' }}</el-tag><StatusBadge :status="outboundStatusText(outboundDetail.aggregate.dispatchStatus)" /><el-button v-if="canConfirmDeparture" type="primary" :loading="outboundConfirming" @click="confirmDeparture">确认离仓</el-button></div></header>
+        <LoadErrorState v-if="outboundError" compact title="国内出仓操作失败" :message="outboundError.message" :loading="outboundLoading" @retry="loadOutboundDispatch"><template #details><ApiErrorMeta :details="outboundError" /></template></LoadErrorState>
+        <div v-else-if="outboundLoading" class="outbound-panel__loading"><el-skeleton :rows="2" animated /></div>
+        <template v-else-if="outboundDetail">
+          <div class="gate-summary"><span>总门禁 <strong>{{ outboundGateSummary.total }}</strong></span><span class="gate-summary__passed">已通过 <strong>{{ outboundGateSummary.passed }}</strong></span><span :class="{ 'gate-summary__blocked': outboundGateSummary.blocked }">阻断 <strong>{{ outboundGateSummary.blocked }}</strong></span><span class="gate-summary__reference">拖车状态（参考）：{{ truckReferenceText(outboundDetail.aggregate.truckAppointmentStatus) }}</span><el-button v-if="outboundGateSummary.passed" link type="primary" @click="showPassedGates = !showPassedGates">{{ showPassedGates ? '收起已通过项' : `查看全部门禁（${outboundGateSummary.total}）` }}</el-button></div>
+          <p v-if="outboundGateSummary.blocked" class="outbound-panel__hint">默认仅展示阻断项；处理完成后重新加载门禁即可确认离仓。</p>
+          <p v-else-if="!showPassedGates" class="outbound-panel__hint outbound-panel__hint--success">{{ customsDepartureState === 'DEPARTED' ? '整柜已确认离仓；展开可查看去重后的完整门禁。' : '全部门禁已通过，可确认整柜离仓；展开可查看去重后的完整门禁。' }}</p>
+          <div class="gate-list">
+            <article v-for="row in visibleOutboundGateRows" :key="row.key" class="gate-row">
+              <el-tag size="small" :type="row.passed ? 'success' : 'danger'">{{ row.passed ? '通过' : '阻断' }}</el-tag><strong>{{ row.name }}</strong><span class="gate-row__actual">{{ row.actual || '暂无事实' }}</span><small>要求：{{ row.requirement || '—' }}</small>
+              <div class="gate-row__coverage"><span>{{ row.passed ? '覆盖' : '影响' }} {{ row.inboundCodes.length }} 个入库码</span><el-tag v-for="code in row.inboundCodes.slice(0, 3)" :key="code" size="small" effect="plain">{{ code }}</el-tag><span v-if="row.inboundCodes.length > 3">+{{ row.inboundCodes.length - 3 }}</span></div>
+            </article>
+          </div>
+        </template>
+        </div>
+      </section>
+
+      <section v-if="isOverseas" v-show="activeTab === 'overview'" class="detail-section surface-panel" aria-labelledby="container-overseas-receiving-heading">
+        <header class="detail-section__heading"><h2 id="container-overseas-receiving-heading">提柜、卸柜与还空</h2><el-button v-if="canRecordEmptyReturn" type="primary" :loading="emptyReturnSaving" @click="openEmptyReturn">确认还柜</el-button></header>
+        <div class="detail-fields"><dl class="density-fields"><div><dt>码头拖车状态</dt><dd>{{ workbenchDetail?.statusSummary?.terminalDrayageStatus || '—' }}</dd></div><div><dt>码头车队</dt><dd>{{ workbenchDetail?.terminalDrayage?.fleetSupplierName || '—' }}</dd></div><div><dt>预计到仓</dt><dd>{{ formatTime(arrivalTime?.estimatedWarehouseArrivalAt) }}</dd></div><div><dt>实际到仓</dt><dd>{{ formatTime(arrivalTime?.actualWarehouseArrivalAt) }}</dd></div><div><dt>卸柜完成</dt><dd>{{ formatTime((workbenchDetail?.actualFacts?.unloadingCompletedAt || workbenchDetail?.terminalDrayage?.unloadingCompletedAt) as string | null) }}</dd></div><div><dt>实际还柜</dt><dd>{{ formatTime(workbenchDetail?.terminalDrayage?.actualEmptyReturnAt) }}</dd></div></dl></div>
+      </section>
+
+      <section v-if="isDomestic && activeTab === 'loading-list'" class="detail-section surface-panel" aria-labelledby="container-loading-list-heading">
+        <header class="loading-list-heading"><div><h2 id="container-loading-list-heading">{{ loadingListHeading }}</h2><p>{{ loadingListDescription }}</p></div><el-button v-if="loadingDetail && loadingListMode === 'confirmed'" @click="printLoadingList">打印装柜清单</el-button></header>
+        <ContainerOverviewPanel v-if="overview" :overview="overview" :sections="['pda']" :can-manage-documents="false" :can-manage-customs="false" :can-manage-exception="false" />
+        <ContainerCustomsPanel v-if="overview?.loadingPlanId && canListCustoms" :loading-plan-id="overview.loadingPlanId" :can-list="canListCustoms" :can-manage="canManageCustoms" :departure-state="customsDepartureState" @refreshed="refreshAfterCustoms" />
+        <LoadingListDetailDrawer dense :mode="loadingListMode" embedded :loading="loadingDetailLoading" :detail="loadingDetail" :error="loadingDetailError" :can-edit="false" @back="activeTab = 'overview'" @retry="overview && loadLoadingDetail(detail, overview)" />
+      </section>
+
+      <section v-if="canViewFirstLegFees && firstLegFeesOpened" v-show="activeTab === 'first-leg-fees'" v-loading="loadingDetailLoading" class="detail-section surface-panel" aria-label="头程计费">
+        <LoadErrorState v-if="loadingDetailError" compact title="头程计费归属明细加载失败" :message="loadingDetailError.message" :loading="loadingDetailLoading" @retry="overview && loadLoadingDetail(detail, overview)"><template #details><ApiErrorMeta :details="loadingDetailError" /></template></LoadErrorState>
+        <ContainerFeesPanel v-else-if="overview?.loadingPlanId && loadingDetail" title="国内段费用（头程）" :plan-id="overview.loadingPlanId" :container-booking-id="detail.id" :customers="feeCustomers" :business-references="feeBusinessReferences" />
+        <el-empty v-else-if="!loadingDetailLoading" :description="firstLegFeesEmptyReason" :image-size="72" />
+      </section>
+
+      <section v-if="canViewLastLegFees && lastLegFeesOpened" v-show="activeTab === 'last-leg-fees'" class="detail-section surface-panel" aria-label="尾程计费">
+        <ContainerLastLegFeesPanel title="目的港及海外段费用（尾程）" :container-booking-id="detail.id" :container-no="detail.containerNo" />
+      </section>
+    </template>
+
+    <OceanBookingLinkDialog v-model="oceanBookingLinkOpen" :container="detail" @linked="load" />
+    <AppDialog class="admin-density-dialog" v-model="emptyReturnOpen" title="确认还柜" width="min(520px, calc(100vw - 28px))" confirm-text="确认还柜" :confirm-loading="emptyReturnSaving" :confirm-disabled="!emptyReturnAt || !canRecordEmptyReturn" @confirm="confirmEmptyReturn"><el-alert title="提交后货柜将进入已还柜状态，请核对实际还柜时间。" type="warning" :closable="false" show-icon /><el-form class="density-form" label-position="top"><el-form-item label="实际还柜时间" required><el-date-picker v-model="emptyReturnAt" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" placeholder="请选择实际还柜时间" /></el-form-item><el-form-item label="备注"><el-input v-model="emptyReturnReason" type="textarea" :rows="3" maxlength="500" show-word-limit placeholder="请输入备注（选填）" /></el-form-item></el-form><LoadErrorState v-if="emptyReturnError" compact title="确认还柜失败" :message="emptyReturnError.message" :show-retry="false"><template #details><ApiErrorMeta :details="emptyReturnError" /></template></LoadErrorState></AppDialog>
+    <AppDialog class="admin-density-dialog" v-model="documentOpen" :title="documentTitle" width="min(520px, calc(100vw - 28px))" confirm-text="上传资料" :confirm-loading="documentSaving" :confirm-disabled="!documentFile" @confirm="saveDocument"><el-form class="density-form" label-position="top"><el-form-item :label="documentTitle"><el-upload :key="documentUploadKey" :auto-upload="false" :limit="1" :on-change="selectDocumentFile" :on-remove="removeDocumentFile"><el-button><FileUp :size="16" />选择文件</el-button><template #tip><div class="el-upload__tip">{{ selectedDocument ? '上传新文件将替换当前资料并保留历史。' : `请选择需要提交的${documentTitle}。` }}</div></template></el-upload></el-form-item></el-form><LoadErrorState v-if="documentError" compact title="资料上传失败" :message="documentError.message" :show-retry="false"><template #details><ApiErrorMeta :details="documentError" /></template></LoadErrorState></AppDialog>
+    <AppDialog class="admin-density-dialog" v-model="exceptionOpen" :title="exceptionTitle" width="min(520px, calc(100vw - 28px))" :confirm-text="overview?.exception.active ? '确认取消' : '确认标记'" :confirm-loading="exceptionSaving" :confirm-disabled="!exceptionReason.trim()" @confirm="saveException"><el-alert :title="overview?.exception.active ? '取消备注为必填项，提交后将保留历史记录。' : '异常原因将同步记录在货柜详情和操作日志中。'" :type="overview?.exception.active ? 'warning' : 'error'" :closable="false" /><el-form class="density-form" label-position="top"><el-form-item :label="overview?.exception.active ? '取消备注' : '异常原因'" required><el-input v-model="exceptionReason" type="textarea" :rows="4" maxlength="500" show-word-limit placeholder="请输入异常原因或取消备注" /></el-form-item></el-form><LoadErrorState v-if="exceptionError" compact title="异常处理失败" :message="exceptionError.message" :show-retry="false" /></AppDialog>
+    <AppDialog class="admin-density-dialog" v-model="clearanceOpen" title="目的港清关资料" width="min(520px, calc(100vw - 28px))" :loading="clearanceLoading" :show-confirm="!clearanceDocument?.completedAt" confirm-text="上传资料" :confirm-loading="clearanceSaving" :confirm-disabled="!clearanceFile" @confirm="uploadClearance"><el-alert v-if="clearanceDocument?.completedAt" type="success" :closable="false" :title="`目的港清关已完成：${clearanceDocument.fileName}`" /><template v-else><el-form class="density-form" label-position="top"><el-form-item label="目的港清关资料"><el-upload :auto-upload="false" :limit="1" :on-change="selectClearanceFile" :on-remove="removeClearanceFile"><el-button><FileUp :size="16" />选择文件</el-button></el-upload></el-form-item></el-form><el-button v-if="clearanceDocument" type="success" plain :loading="clearanceSaving" @click="completeClearance">确认目的港清关完成</el-button></template><LoadErrorState v-if="clearanceError" compact title="目的港清关资料操作失败" :message="clearanceError.message" :show-retry="false"><template #details><ApiErrorMeta :details="clearanceError" /></template></LoadErrorState></AppDialog>
+  </AdminPage>
+</template>
+
+<style scoped>
+.workbench-tab-label { display:inline-flex; align-items:center; justify-content:center; gap:var(--admin-space-3); white-space:nowrap; }
+.container-detail-page { display:grid; min-width:0; gap:var(--admin-space-5); }.container-overview { overflow:hidden; }.container-overview__header { display:grid; grid-template-columns:auto minmax(0,1fr) auto; align-items:center; gap:var(--admin-space-5); padding:var(--admin-space-4) var(--admin-space-5); }.container-overview__header h1 { margin:0; font-size:var(--admin-font-title); }.container-overview__header p { margin:2px 0 0; color:var(--cc-muted); font-size:var(--admin-font-caption); }.container-overview__summary { border-top:1px solid var(--cc-border); display:flex; flex-wrap:wrap; }.container-overview__summary>div { display:flex; min-width:0; padding:var(--admin-space-3) var(--admin-space-5); border-right:1px solid var(--cc-border); align-items:baseline; gap:var(--admin-space-2); }.container-overview__summary>div:last-child { border-right:0; }.container-overview__summary span,dt { color:var(--cc-muted); font-size:var(--admin-font-caption); }.container-overview__summary strong,dd { margin:0; white-space:normal; overflow-wrap:anywhere; }.detail-section{display:grid;min-width:0;gap:var(--admin-space-5);padding:var(--admin-space-5) var(--admin-space-5)}.detail-section>h2{margin:0;font-size:var(--admin-font-section)}.detail-fields { padding:0; }.outbound-panel{padding:var(--admin-space-5) 0 0;border-top:1px solid var(--cc-border)}.outbound-panel__header{display:flex;align-items:center;justify-content:space-between;gap:var(--admin-space-5)}.outbound-panel__header h2{margin:0;font-size:var(--admin-font-section)}.outbound-panel__header p,.outbound-panel__hint{margin:3px 0 0;color:var(--cc-muted);font-size:var(--admin-font-caption)}.outbound-panel__hint--success{color:var(--el-color-success)}.outbound-panel__actions{display:flex;align-items:center;gap:var(--admin-space-3)}.outbound-panel__loading{padding:var(--admin-space-3) 0}.gate-summary{display:flex;align-items:center;gap:var(--admin-space-5);margin-top:var(--admin-space-3);color:var(--cc-muted);font-size:var(--admin-font-caption)}.gate-summary__passed strong{color:var(--el-color-success)}.gate-summary__blocked strong{color:var(--el-color-danger)}.gate-summary__reference{margin-left:auto;padding-left:var(--admin-space-4);border-left:1px solid var(--cc-border)}.gate-list{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:var(--admin-space-2) var(--admin-space-5);margin-top:7px}.gate-row{display:grid;grid-template-columns:auto minmax(130px,.9fr) minmax(100px,1fr);align-items:center;gap:var(--admin-space-2) var(--admin-space-3);min-width:0;padding:var(--admin-space-2) var(--admin-space-3);border:1px solid var(--cc-border);border-radius:var(--admin-radius);background:var(--cc-surface-muted)}.gate-row__actual,.gate-row small{color:var(--cc-muted);font-size:var(--admin-font-caption);white-space:normal;overflow-wrap:anywhere}.gate-row small{grid-column:2/-1}.gate-row__coverage{display:flex;grid-column:2/-1;min-width:0;align-items:center;gap:5px;overflow:hidden}.gate-row__coverage>span{flex:0 0 auto;color:var(--cc-muted);font-size:var(--admin-font-caption)}.gate-row__coverage :deep(.el-tag){max-width:120px;overflow:hidden;text-overflow:ellipsis}.carrier-panel{padding-top:var(--admin-space-1)}@media(max-width:1200px){.gate-list{grid-template-columns:1fr}}@media(max-width:720px){.container-overview__header{grid-template-columns:auto minmax(0,1fr)}.container-overview__header>:last-child{grid-column:2}.container-overview__summary,.detail-fields dl{grid-template-columns:repeat(2,minmax(0,1fr))}.outbound-panel__header{align-items:flex-start;flex-direction:column}.outbound-panel__actions,.gate-summary{flex-wrap:wrap}.gate-summary__reference{width:100%;margin-left:0;padding-left:0;border-left:0}.gate-row{grid-template-columns:auto minmax(0,1fr)}.gate-row__actual,.gate-row small,.gate-row__coverage{grid-column:2}}
+.detail-section__heading { display:flex; align-items:center; justify-content:space-between; gap:var(--admin-space-5); }
+.detail-section__heading h2 { margin:0; font-size:var(--admin-font-section); }
+.overseas-stage-strip{display:flex;align-items:center;justify-content:space-between;gap:var(--admin-space-6);padding:9px var(--admin-space-5);border-top:1px solid var(--cc-border);background:#f5f8ff}.overseas-stage-strip>div{display:flex;align-items:baseline;gap:var(--admin-space-4)}.overseas-stage-strip span,.overseas-stage-strip p{color:var(--cc-muted);font-size:var(--admin-font-caption)}.overseas-stage-strip strong{color:var(--cc-primary);font-size:var(--admin-font-section)}.overseas-stage-strip p{margin:0}.overseas-stage-strip.is-overdue{background:#fff7ed}.overseas-stage-strip.is-overdue strong,.overseas-stage-strip.is-overdue p{color:#c2410c}.container-overview__header h1 { overflow-wrap:anywhere; }.workbench-tab-label { gap:var(--admin-space-2); }
+</style>
diff --git a/src/modules/container-loading/pages/ContainersView.test.ts b/src/modules/container-loading/pages/ContainersView.test.ts
new file mode 100644
index 00000000..490ac617
--- /dev/null
+++ b/src/modules/container-loading/pages/ContainersView.test.ts
@@ -0,0 +1,834 @@
+import ElementPlus from 'element-plus'
+import { createPinia, setActivePinia } from 'pinia'
+import { createMemoryHistory, createRouter, RouterView } from 'vue-router'
+import { defineComponent } from 'vue'
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import ContainersView from './ContainersView.vue'
+import { listAllPlatformWarehouses } from '@/modules/warehouses'
+import { listPlatformPartners } from '@/modules/master-data'
+import { listSuppliers } from '@/modules/suppliers'
+import { getOceanBooking, listOceanBookingLinkCandidates, listOceanBookings } from '@/modules/ocean-bookings'
+import { getContainer, getContainerOverview, listContainers, updateContainer } from '../api/platformContainerLoading'
+import OceanBookingLinkDialog from '../components/OceanBookingLinkDialog.vue'
+import { getTerminalDrayage, getTerminalDrayageHistory, recordTerminalDrayageEmptyReturn, selectTerminalDrayageFleet, sendTerminalDrayageEmail, getTerminalDrayageEmails } from '../api/terminalDrayages'
+import { listContainerArrivalTimes, updateContainerExpectedArrival } from '../api/containerArrivalTimes'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import { containerLoadingRoutes } from '../routes'
+
+vi.mock('@/modules/warehouses', () => ({ listAllPlatformWarehouses: vi.fn() }))
+vi.mock('@/modules/master-data', () => ({ listPlatformPartners: vi.fn() }))
+vi.mock('@/modules/suppliers', () => ({ listSuppliers: vi.fn() }))
+vi.mock('@/modules/ocean-bookings', () => ({ getOceanBooking: vi.fn(), listOceanBookingLinkCandidates: vi.fn(), listOceanBookings: vi.fn(), listWarehouseLogisticsChannels: vi.fn() }))
+vi.mock('@/modules/iam', () => ({ listPlatformTenants: vi.fn().mockResolvedValue({ records: [], page: 1, size: 200, total: 0, pages: 0 }) }))
+const accessCan = vi.hoisted(() => vi.fn())
+vi.mock('@/core/access/accessPreview', () => ({ useAccessPreviewStore: () => ({ can: accessCan }) }))
+vi.mock('../api/platformContainerLoading', () => ({ listContainers: vi.fn(), getContainer: vi.fn(), getContainerOverview: vi.fn(), getContainerClearance: vi.fn(), uploadContainerClearance: vi.fn(), completeContainerClearance: vi.fn(), uploadContainerDocument: vi.fn(), downloadContainerDocument: vi.fn(), downloadContainerPdaPhoto: vi.fn(), markContainerException: vi.fn(), cancelContainerException: vi.fn(), createContainerSimulation: vi.fn(), linkContainerOceanBooking: vi.fn(), unlinkContainerOceanBooking: vi.fn(), updateContainer: vi.fn() }))
+vi.mock('../api/terminalDrayages', () => ({ sendTerminalDrayageEmail: vi.fn(), getTerminalDrayageEmails: vi.fn(), retryTerminalDrayageEmail: vi.fn(), listTerminalDrayages: vi.fn(), getTerminalDrayage: vi.fn(), getTerminalDrayageHistory: vi.fn(), selectTerminalDrayageFleet: vi.fn(), scheduleTerminalDrayagePickup: vi.fn(), recordTerminalDrayageEmptyReturn: vi.fn() }))
+vi.mock('../api/containerArrivalTimes', () => ({ listContainerArrivalTimes: vi.fn(), updateContainerExpectedArrival: vi.fn() }))
+
+const drayage = {
+  containerBookingId: '9001', containerNo: 'MSCU-1', oceanBookingId: '101', status: 'UNLOADED' as const, version: 3,
+  fleetSupplierId: '501', fleetSupplierName: '港运车队', pickupAppointmentAt: '2026-09-07T08:00:00', actualPickupAt: '2026-09-07T09:00:00',
+  estimatedEmptyReturnAt: '2026-09-10T10:00:00', actualEmptyReturnAt: null, unloadingCompletedAt: '2026-09-07T10:00:00',
+  emptyReturnWarning: { status: 'OVERDUE' as const, deadlineAt: '2026-09-10T10:00:00', overdueHours: 26, overdueDays: 1 },
+  allowedActions: ['SELECT_FLEET', 'RECORD_EMPTY_RETURN'] as const, updatedAt: '2026-09-11T12:00:00',
+}
+
+function createTestRouter() {
+  return createRouter({ history: createMemoryHistory(), routes: [
+    { path: '/', name: 'domestic-container-workbench', component: ContainersView },
+    { path: '/container-loading/domestic/:containerId/smart-loading', name: 'smart-loading-workbench', component: { template: '<div />' } },
+    { path: '/loading-plans', name: 'loading-plans', component: { template: '<div />' } },
+    { path: '/container-loading/domestic/:containerId', name: 'domestic-container-detail', component: { template: '<div />' } },
+    { path: '/container-loading/overseas/:containerId', name: 'overseas-container-detail', component: { template: '<div />' } },
+  ] })
+}
+
+async function mountOverseasRoute() {
+  const router = createRouter({
+    history: createMemoryHistory(),
+    routes: containerLoadingRoutes.map((route) => ({ ...route, path: `/${route.path}` })),
+  })
+  await router.push('/container-loading/overseas')
+  await router.isReady()
+  const wrapper = mount(RouterView, { attachTo: document.body, global: { plugins: [ElementPlus, router] } })
+  await flushPromises()
+  return wrapper
+}
+
+describe('ContainersView', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    accessCan.mockReset(); accessCan.mockReturnValue(true)
+    vi.mocked(listAllPlatformWarehouses).mockResolvedValue([])
+    vi.mocked(listPlatformPartners).mockResolvedValue({ records: [], page: 1, size: 200, total: 0, pages: 1 })
+    vi.mocked(listSuppliers).mockResolvedValue({ records: [], page: 1, size: 200, total: 0, pages: 1 })
+    vi.mocked(listOceanBookings).mockResolvedValue({ records: [], page: 1, size: 200, total: 0, pages: 1 })
+    vi.mocked(listOceanBookingLinkCandidates).mockResolvedValue({ records: [], page: 1, size: 200, total: 0, pages: 0 })
+    vi.mocked(getOceanBooking).mockResolvedValue({} as never)
+    vi.mocked(getTerminalDrayage).mockResolvedValue({ ...drayage, allowedActions: [...drayage.allowedActions] })
+    vi.mocked(getTerminalDrayageHistory).mockResolvedValue([])
+    vi.mocked(selectTerminalDrayageFleet).mockResolvedValue({ ...drayage, fleetSupplierId: '502', fleetSupplierName: '新车队', version: 4, allowedActions: [...drayage.allowedActions] })
+    vi.mocked(recordTerminalDrayageEmptyReturn).mockReset().mockResolvedValue({ ...drayage, status: 'EMPTY_RETURNED', actualEmptyReturnAt: '2026-09-11T13:00:00', version: 4, emptyReturnWarning: { status: 'RESOLVED', deadlineAt: '2026-09-10T10:00:00', overdueHours: 0, overdueDays: 0 }, allowedActions: ['SELECT_FLEET'] })
+    vi.mocked(listContainerArrivalTimes).mockReset().mockResolvedValue([{ sourceContainerBookingId: '9001', estimatedWarehouseArrivalAt: '2026-09-25T15:31:00', actualWarehouseArrivalAt: '2026-09-26T09:00:00', version: 0 }])
+    vi.mocked(updateContainerExpectedArrival).mockReset().mockResolvedValue({ sourceContainerBookingId: '9001', estimatedWarehouseArrivalAt: '2026-09-25T16:00:00', actualWarehouseArrivalAt: '2026-09-26T09:00:00', version: 1 })
+    vi.mocked(listContainers).mockResolvedValue({ records: [{ id: '9001', planId: null, bookingNo: 'BK-1', cabinetNo: 'CB-1', containerNo: 'MSCU-1', sourceType: 'SIMULATION', allowedActions: ['EDIT_CONTAINER', 'SELECT_FLEET', 'SCHEDULE_PICKUP', 'RECORD_EMPTY_RETURN'], terminalDrayage: drayage, oceanBookingId: null, warehouseId: '8', warehouseName: '义乌仓', channelGroupCode: 'MATSON_CLX', channelCode: null, channelName: null, containerType: '40HQ', planStatus: 'WAIT_LOADING', version: 0, billOfLadingNo: null, vesselName: null, voyageNo: null, shippingCompanyId: null, shippingCompanyName: null, departurePortCode: null, departurePortName: '宁波', destinationPortCode: null, destinationPortName: '长滩', destinationWarehouseCode: null, destinationWarehouseName: null, capacityCbm: 68, maxWeightKg: 19500, terminalTruckingCompanyId: null, terminalTruckingCompany: null, loadingAt: null, estimatedSailingAt: null, actualSailingAt: null, estimatedPortArrivalAt: null, actualPortArrivalAt: null, estimatedWarehouseArrivalAt: null, actualWarehouseArrivalAt: null }], page: 1, size: 20, total: 1, pages: 1 })
+    vi.mocked(getContainer).mockResolvedValue({ id: '9001', planId: null, bookingNo: 'BK-1', cabinetNo: 'CB-1', containerNo: 'MSCU-1', sourceType: 'SIMULATION', allowedActions: ['EDIT_CONTAINER'], oceanBookingId: null, warehouseId: '8', warehouseName: '义乌仓', channelGroupCode: 'MATSON_CLX', channelCode: null, channelName: null, containerType: '40HQ', planStatus: 'WAIT_LOADING', version: 0, billOfLadingNo: null, vesselName: null, voyageNo: null, shippingCompanyId: null, shippingCompanyName: null, departurePortCode: null, departurePortName: '宁波', destinationPortCode: null, destinationPortName: '长滩', destinationWarehouseCode: null, destinationWarehouseName: null, capacityCbm: 68, maxWeightKg: 19500, terminalTruckingCompanyId: null, terminalTruckingCompany: null, loadingAt: null, estimatedSailingAt: null, actualSailingAt: null, estimatedPortArrivalAt: null, actualPortArrivalAt: null, estimatedWarehouseArrivalAt: null, actualWarehouseArrivalAt: null })
+    vi.mocked(getContainerOverview).mockResolvedValue({ container: { id: '9001', bookingNo: 'BK-1', cabinetNo: 'CB-1', containerNo: 'MSCU-1', status: 'WAIT_LOADING', warehouseId: '8', warehouseName: '义乌仓', voyageNo: null, vesselName: null, version: 0 }, loadingPlanId: null, pda: null, documents: [], exception: { active: false, reason: null, markedBy: null, markedByName: null, markedAt: null }, exceptionHistory: [], timeline: [] })
+  })
+
+  it('loads the real paged contract and renders core container fields', async () => {
+    const router = createTestRouter()
+    await router.push('/'); await router.isReady()
+    const wrapper = mount(ContainersView, { global: { plugins: [ElementPlus, router] } })
+    await flushPromises()
+    expect(listContainers).toHaveBeenCalledWith(expect.objectContaining({ page: 1, size: 20, scope: 'ACTIVE' }), 'DOMESTIC')
+    expect(wrapper.text()).toContain('待装柜')
+    expect(wrapper.text()).toContain('CB-1')
+    expect(wrapper.text()).toContain('MSCU-1')
+    expect(wrapper.text()).toContain('宁波 → 长滩')
+    expect(wrapper.find('button[aria-label="查看 CB-1"]').exists()).toBe(true)
+    expect(wrapper.text()).not.toContain('报空预警')
+  })
+
+  it('sends pickup mail from the list once while pending and shows disabled delivery in history', async () => {
+    const original = await listContainers({ page: 1, size: 20 }, 'OVERSEAS')
+    vi.mocked(listContainers).mockResolvedValue({ ...original, records: original.records.map((row) => ({
+      ...row, allowedActions: ['SEND_PICKUP_EMAIL'], terminalDrayage: { ...drayage, allowedActions: ['SEND_PICKUP_EMAIL'] },
+    })) })
+    let resolveSend!: (value: Awaited<ReturnType<typeof sendTerminalDrayageEmail>>) => void
+    vi.mocked(sendTerminalDrayageEmail).mockReset().mockReturnValue(new Promise((resolve) => { resolveSend = resolve }))
+    vi.mocked(getTerminalDrayageEmails).mockResolvedValue({ deliveryEnabled: false, records: [] })
+    const wrapper = await mountOverseasRoute()
+    const button = wrapper.findAll('.row-actions button').find((item) => item.text().includes('发送邮件'))!
+    expect(button.exists()).toBe(true)
+    await button.trigger('click'); await button.trigger('click')
+    expect(sendTerminalDrayageEmail).toHaveBeenCalledTimes(1)
+    expect(sendTerminalDrayageEmail).toHaveBeenCalledWith('9001', 3)
+    resolveSend({ ...drayage, version: 4, allowedActions: ['SEND_PICKUP_EMAIL'] })
+    await flushPromises()
+    await wrapper.find('.el-table__body button[aria-label="更多货柜操作"]').trigger('click')
+    await flushPromises()
+    Array.from(document.body.querySelectorAll<HTMLElement>('.el-dropdown-menu__item')).filter((item) => item.textContent?.includes('邮件记录')).at(-1)!.click()
+    await flushPromises()
+    expect(getTerminalDrayageEmails).toHaveBeenCalledWith('9001')
+    expect(document.body.textContent).toContain('发信尚未启用')
+    wrapper.unmount()
+  })
+
+  it.each([3, 0])('submits direct empty return with server version %s, including unload without pickup', async (version) => {
+    const original = await listContainers({ page: 1, size: 20 }, 'OVERSEAS')
+    vi.mocked(listContainers).mockClear().mockResolvedValue({ ...original, records: original.records.map((row) => ({
+      ...row,
+      terminalDrayage: { ...drayage, version, actualPickupAt: version ? drayage.actualPickupAt : null,
+        fleetSupplierId: version ? drayage.fleetSupplierId : null, allowedActions: ['RECORD_EMPTY_RETURN'],
+        emptyReturnWarning: { status: 'PENDING', deadlineAt: drayage.estimatedEmptyReturnAt, overdueHours: 0, overdueDays: 0 } },
+    })) })
+    const wrapper = await mountOverseasRoute()
+    expect(listContainers).toHaveBeenCalledWith(expect.objectContaining({ scope: 'ACTIVE' }), 'OVERSEAS')
+    const buttons = wrapper.findAll('button').filter((item) => item.text().includes('确认还柜'))
+    expect(buttons).toHaveLength(1)
+    await buttons[0].trigger('click')
+    await flushPromises()
+    const returnDialog = wrapper.findAllComponents(AppDialog).find((dialog) => dialog.props('title') === '确认还柜')!
+    returnDialog.findComponent({ name: 'ElDatePicker' }).vm.$emit('update:modelValue', '2026-09-11T13:00:00')
+    await returnDialog.find('textarea').setValue('还柜凭证已核对')
+    const callsBefore = vi.mocked(listContainers).mock.calls.length
+    const page: Awaited<ReturnType<typeof listContainers>> = await vi.mocked(listContainers).mock.results.at(-1)!.value
+    vi.mocked(listContainers).mockResolvedValueOnce({ ...page, records: page.records.map((row) => ({ ...row, allowedActions: [], terminalDrayage: { ...drayage, status: 'EMPTY_RETURNED', version: 4, allowedActions: [], emptyReturnWarning: { status: 'RESOLVED', deadlineAt: null, overdueHours: 0, overdueDays: 0 } } })) })
+    const confirm = [...document.body.querySelectorAll('button')].filter((item) => item.textContent?.includes('确认还柜')).at(-1) as HTMLButtonElement
+    confirm.click()
+    await flushPromises()
+    expect(recordTerminalDrayageEmptyReturn).toHaveBeenCalledTimes(1)
+    expect(recordTerminalDrayageEmptyReturn).toHaveBeenCalledWith('9001', { expectedVersion: version, actualAt: '2026-09-11T13:00:00', remark: '还柜凭证已核对' })
+    expect(wrapper.text()).toContain('已还柜')
+    expect(listContainers).toHaveBeenCalledTimes(callsBefore + 1)
+    expect(wrapper.findAll('.row-actions button').some((button) => button.text() === '确认还柜')).toBe(false)
+    wrapper.unmount()
+  })
+
+  it.each(['permission', 'row action', 'nested action', 'nested object', 'already returned', 'historical unloaded snapshot'] as const)(
+    'keeps empty return unavailable on the real overseas route: %s',
+    async (missing) => {
+      const page = await listContainers({ page: 1, size: 20 }, 'OVERSEAS')
+      vi.mocked(listContainers).mockClear()
+      const nested = missing === 'nested object' ? null : {
+        ...drayage,
+        allowedActions: missing === 'nested action' || missing === 'already returned' ? [] : [...drayage.allowedActions],
+        ...(missing === 'already returned' ? { status: 'EMPTY_RETURNED' as const, actualEmptyReturnAt: '2026-09-11T13:00:00' } : {}),
+        ...(missing === 'historical unloaded snapshot' ? { status: 'ARRIVED' as const, version: 0, actualPickupAt: null, fleetSupplierId: null, fleetSupplierName: null, allowedActions: ['SELECT_FLEET' as const] } : {}),
+      }
+      vi.mocked(listContainers).mockResolvedValue({ ...page, records: page.records.map((row) => ({
+        ...row,
+        allowedActions: missing === 'row action' || missing === 'already returned' ? [] : ['RECORD_EMPTY_RETURN'],
+        terminalDrayage: nested,
+        ...(missing === 'historical unloaded snapshot' ? { workbenchStage: 'UNLOADED', allowedActions: ['MANAGE_DESTINATION_DOCUMENTS' as const, 'SELECT_FLEET' as const] } : {}),
+      })) })
+      if (missing === 'permission') {
+        accessCan.mockImplementation((code) => code !== 'platform:firstleg:terminal-drayage:empty-return:confirm')
+      }
+      const wrapper = await mountOverseasRoute()
+      try {
+        expect(listContainers).toHaveBeenCalledTimes(1)
+        expect(listContainers).toHaveBeenCalledWith(expect.objectContaining({ scope: 'ACTIVE' }), 'OVERSEAS')
+        expect(wrapper.text()).toContain('MSCU-1')
+        expect(wrapper.findAll('.row-actions button').some((button) => button.text() === '确认还柜')).toBe(false)
+        expect(wrapper.findAllComponents(AppDialog).some((dialog) => dialog.props('title') === '确认还柜' && dialog.props('modelValue'))).toBe(false)
+        expect(recordTerminalDrayageEmptyReturn).not.toHaveBeenCalled()
+        expect(getTerminalDrayage).not.toHaveBeenCalled()
+        if (missing === 'historical unloaded snapshot') {
+          const fleet = wrapper.findAllComponents({ name: 'ElSelect' }).find((select) =>
+            select.props('placeholder') === '输入车队名称或联系人搜索' && select.element.closest('.el-table__body'),
+          )
+          expect(fleet).toBeDefined()
+          expect(fleet!.props('disabled')).toBe(false)
+        }
+      } finally {
+        wrapper.unmount()
+      }
+    },
+  )
+
+  it('cancels empty return without writing and preserves input on failure while preventing duplicate requests', async () => {
+    const router = createTestRouter()
+    await router.push('/'); await router.isReady()
+    const wrapper = mount(ContainersView, { props: { workbench: 'OVERSEAS' }, attachTo: document.body, global: { plugins: [ElementPlus, router] } })
+    await flushPromises()
+    const open = async () => {
+      await wrapper.findAll('.row-actions button').find((button) => button.text() === '确认还柜')!.trigger('click')
+      await flushPromises()
+      return wrapper.findAllComponents(AppDialog).find((dialog) => dialog.props('title') === '确认还柜')!
+    }
+    const first = await open()
+    first.vm.$emit('update:modelValue', false)
+    await flushPromises()
+    expect(recordTerminalDrayageEmptyReturn).not.toHaveBeenCalled()
+    const dialog = await open()
+    const state = wrapper.vm as unknown as { drayageActionAt: string; drayageReason: string; drayageActionOpen: boolean; drayageActionError: { message: string } | null }
+    state.drayageActionAt = '2026-09-11T13:00:00'
+    state.drayageReason = '还柜凭证已核对'
+    let reject!: (reason: Error) => void
+    vi.mocked(recordTerminalDrayageEmptyReturn).mockReturnValueOnce(new Promise((_resolve, rejectRequest) => { reject = rejectRequest }))
+    dialog.vm.$emit('confirm')
+    dialog.vm.$emit('confirm')
+    expect(recordTerminalDrayageEmptyReturn).toHaveBeenCalledTimes(1)
+    expect(recordTerminalDrayageEmptyReturn).toHaveBeenCalledWith('9001', { expectedVersion: 3, actualAt: '2026-09-11T13:00:00', remark: '还柜凭证已核对' })
+    reject(new Error('还柜时间不符合业务要求'))
+    await flushPromises()
+    expect(state.drayageActionOpen).toBe(true)
+    expect(state.drayageActionAt).toBe('2026-09-11T13:00:00')
+    expect(state.drayageReason).toBe('还柜凭证已核对')
+    expect(state.drayageActionError).not.toBeNull()
+    wrapper.unmount()
+  })
+
+  it('hides the direct empty-return action without permission or without the server action', async () => {
+    const router = createTestRouter()
+    await router.push('/'); await router.isReady()
+    accessCan.mockImplementation((code) => code !== 'platform:firstleg:terminal-drayage:empty-return:confirm')
+    const wrapper = mount(ContainersView, { props: { workbench: 'OVERSEAS' }, global: { plugins: [ElementPlus, router] } })
+    await flushPromises()
+    expect(wrapper.findAll('button').some((item) => item.text().includes('确认还柜'))).toBe(false)
+    wrapper.unmount()
+    accessCan.mockReturnValue(true)
+    const allowedWrapper = mount(ContainersView, { props: { workbench: 'OVERSEAS' }, global: { plugins: [ElementPlus, router] } })
+    await flushPromises()
+    const vm = allowedWrapper.vm as unknown as { rows: Array<{ allowedActions?: string[] }> }
+    vm.rows[0].allowedActions = vm.rows[0].allowedActions?.filter((action) => action !== 'RECORD_EMPTY_RETURN')
+    await allowedWrapper.vm.$nextTick()
+    expect(allowedWrapper.findAll('button').some((item) => item.text().includes('确认还柜'))).toBe(false)
+  })
+
+  it('defers form options until their dialogs open and caches successful loads', async () => {
+    const router = createTestRouter()
+    await router.push('/'); await router.isReady()
+    const wrapper = mount(ContainersView, { attachTo: document.body, global: { plugins: [ElementPlus, router] } })
+    await flushPromises()
+
+    expect(listAllPlatformWarehouses).not.toHaveBeenCalled()
+    expect(listPlatformPartners).not.toHaveBeenCalled()
+    expect(listSuppliers).not.toHaveBeenCalled()
+    expect(listOceanBookings).not.toHaveBeenCalled()
+
+    await wrapper.findAll('button').find((button) => button.text().includes('新增模拟柜'))!.trigger('click')
+    await flushPromises()
+    expect(listAllPlatformWarehouses).toHaveBeenCalledTimes(1)
+    expect(listPlatformPartners).not.toHaveBeenCalled()
+    expect(listSuppliers).not.toHaveBeenCalled()
+    expect(listOceanBookings).not.toHaveBeenCalled()
+    wrapper.findAllComponents(AppDialog).find((dialog) => dialog.props('title') === '新增模拟柜')!.vm.$emit('update:modelValue', false)
+    await wrapper.findAll('button').find((button) => button.text().includes('新增模拟柜'))!.trigger('click')
+    await flushPromises()
+    expect(listAllPlatformWarehouses).toHaveBeenCalledTimes(1)
+
+    await wrapper.findAll('button').find((button) => button.text().trim() === '编辑')!.trigger('click')
+    await flushPromises()
+    expect(listAllPlatformWarehouses).toHaveBeenCalledTimes(1)
+    expect(listPlatformPartners).toHaveBeenCalledTimes(1)
+    expect(listSuppliers).toHaveBeenCalledTimes(1)
+    expect(listOceanBookings).toHaveBeenCalledTimes(1)
+    wrapper.findAllComponents(AppDialog).find((dialog) => dialog.props('title') === '编辑')!.vm.$emit('update:modelValue', false)
+    await wrapper.findAll('button').find((button) => button.text().trim() === '编辑')!.trigger('click')
+    await flushPromises()
+    expect(listPlatformPartners).toHaveBeenCalledTimes(1)
+    expect(listSuppliers).toHaveBeenCalledTimes(1)
+    expect(listOceanBookings).toHaveBeenCalledTimes(1)
+    wrapper.unmount()
+  })
+
+  it('keeps the cross-warehouse list usable when lazy warehouse form options fail', async () => {
+    vi.mocked(listAllPlatformWarehouses).mockRejectedValueOnce(new Error('warehouse unavailable'))
+    const router = createTestRouter()
+    await router.push('/'); await router.isReady()
+    const wrapper = mount(ContainersView, { global: { plugins: [ElementPlus, router] } })
+    await flushPromises()
+
+    expect(listAllPlatformWarehouses).not.toHaveBeenCalled()
+    expect(wrapper.text()).toContain('CB-1')
+    expect(wrapper.find('button[aria-label="查看 CB-1"]').exists()).toBe(true)
+    await wrapper.findAll('button').find((button) => button.text().includes('新增模拟柜'))!.trigger('click')
+    await flushPromises()
+    expect(wrapper.text()).toContain('装柜仓库加载失败')
+  })
+
+  it('uses stable view labels when cabinetNo is missing', async () => {
+    const base = {
+      id: '9001', planId: null, bookingNo: 'BK-1', cabinetNo: 'CB-1', containerNo: 'MSCU-1', warehouseId: '8', warehouseName: '义乌仓', containerType: '40HQ', planStatus: 'WAIT_LOADING' as const, version: 0,
+      billOfLadingNo: null, vesselName: null, voyageNo: null, shippingCompanyId: null, shippingCompanyName: null,
+      departurePortCode: null, departurePortName: '宁波', destinationPortCode: null, destinationPortName: '长滩',
+      destinationWarehouseCode: null, destinationWarehouseName: null, capacityCbm: 68, maxWeightKg: 19500,
+      terminalTruckingCompanyId: null, terminalTruckingCompany: null, loadingAt: null, estimatedSailingAt: null, actualSailingAt: null,
+      estimatedPortArrivalAt: null, actualPortArrivalAt: null, estimatedWarehouseArrivalAt: null, actualWarehouseArrivalAt: null,
+    }
+    vi.mocked(listContainers).mockResolvedValueOnce({
+      records: [
+        { ...base, id: '9002', cabinetNo: undefined, containerNo: 'MSCU-2', bookingNo: 'BK-2' },
+        { ...base, id: '9003', cabinetNo: '', containerNo: null, bookingNo: 'BK-3' },
+        { ...base, id: '9004', cabinetNo: null, containerNo: null, bookingNo: '' },
+      ],
+      page: 1, size: 20, total: 3, pages: 1,
+    } as never)
+    const router = createTestRouter()
+    await router.push('/'); await router.isReady()
+    const wrapper = mount(ContainersView, { global: { plugins: [ElementPlus, router] } })
+    await flushPromises()
+
+    const labels = wrapper.findAll('.el-table__body button')
+      .map((button) => button.attributes('aria-label'))
+      .filter((label): label is string => Boolean(label))
+    expect(labels).toEqual(expect.arrayContaining(['查看 MSCU-2', '查看 BK-3', '查看货柜详情']))
+    expect(labels.every((label) => !/undefined|null/.test(label))).toBe(true)
+  })
+
+  it('routes each plan status to its owning workflow without reopening pushed drafts', async () => {
+    const base = {
+      id: '9001', planId: '9101', bookingNo: 'BK-1', cabinetNo: 'CB-1', containerNo: 'MSCU-1', warehouseId: '8', warehouseName: '义乌仓', channelGroupCode: 'MATSON_CLX', channelCode: null, channelName: null, containerType: '40HQ', version: 0,
+      billOfLadingNo: null, vesselName: null, voyageNo: null, shippingCompanyId: null, shippingCompanyName: null,
+      departurePortCode: null, departurePortName: '宁波', destinationPortCode: null, destinationPortName: '长滩',
+      destinationWarehouseCode: null, destinationWarehouseName: null, capacityCbm: 68, maxWeightKg: 19500,
+      terminalTruckingCompanyId: null, terminalTruckingCompany: null, loadingAt: null, estimatedSailingAt: null, actualSailingAt: null,
+      estimatedPortArrivalAt: null, actualPortArrivalAt: null, estimatedWarehouseArrivalAt: null, actualWarehouseArrivalAt: null,
+    }
+    vi.mocked(listContainers).mockResolvedValueOnce({
+      records: [
+        { ...base, planStatus: 'EDITING' as const },
+        { ...base, id: '9002', planId: '9102', cabinetNo: 'CB-2', planStatus: 'LOADING' as const },
+        { ...base, id: '9003', planId: '9103', cabinetNo: 'CB-3', planStatus: 'COMPLETED' as const },
+      ],
+      page: 1, size: 20, total: 3, pages: 1,
+    })
+    const router = createTestRouter()
+    await router.push('/'); await router.isReady()
+    const push = vi.spyOn(router, 'push').mockResolvedValue(undefined as never)
+    const wrapper = mount(ContainersView, { global: { plugins: [ElementPlus, router] } })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('装柜')
+    expect(wrapper.text()).toContain('预装清单')
+    expect(wrapper.text()).toContain('装柜清单')
+
+    await wrapper.findAll('button').find((button) => button.text().trim() === '装柜')!.trigger('click')
+    await wrapper.findAll('button').find((button) => button.text().includes('预装清单'))!.trigger('click')
+    await wrapper.findAll('button').find((button) => button.text().includes('装柜清单'))!.trigger('click')
+    expect(push).toHaveBeenNthCalledWith(1, { name: 'smart-loading-workbench', params: { containerId: '9001' } })
+    expect(push).toHaveBeenNthCalledWith(2, { name: 'loading-plans', query: { planId: '9102', warehouseId: '8' } })
+    expect(push).toHaveBeenNthCalledWith(3, { name: 'domestic-container-detail', params: { containerId: '9003' }, query: { tab: 'loading-list' } })
+  })
+
+  it('uses active customer names and sends the stable customerId filter', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/pages/ContainersView.vue'), 'utf8')
+    expect(source).toContain("listPlatformTenants({ page: 1, size: 200, status: 'ACTIVE' })")
+    expect(source).toContain("label: customer.tenantName")
+    expect(source).toContain('customerId: applied.value.customerId || undefined')
+    expect(source).not.toContain('customer.tenantCode')
+  })
+
+  it('uses the list permission for detail while keeping edit independent', async () => {
+    accessCan.mockImplementation((permission: string) => permission === 'platform:firstleg:container:list')
+    const router = createTestRouter()
+    await router.push('/'); await router.isReady()
+    const wrapper = mount(ContainersView, { global: { plugins: [ElementPlus, router] } })
+    await flushPromises()
+
+    expect(wrapper.find('button[aria-label="查看 CB-1"]').exists()).toBe(true)
+    expect(wrapper.find('.el-table__body button[aria-label="更多货柜操作"]').exists()).toBe(true)
+    expect(wrapper.findAll('button').some((button) => button.text().trim() === '编辑')).toBe(false)
+  })
+
+  it('does not accept the removed standalone view permission', async () => {
+    accessCan.mockReturnValue(false)
+    const router = createTestRouter()
+    await router.push('/'); await router.isReady()
+    const wrapper = mount(ContainersView, { global: { plugins: [ElementPlus, router] } })
+    await flushPromises()
+
+    expect(wrapper.find('button[aria-label="查看 CB-1"]').exists()).toBe(false)
+    expect(wrapper.find('.el-table__body button[aria-label="更多货柜操作"]').exists()).toBe(false)
+    expect(wrapper.findAll('button').some((button) => button.text().trim() === '编辑')).toBe(false)
+  })
+
+  it('uses business selectors and keeps code/name pairs internal', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/pages/ContainersView.vue'), 'utf8')
+    expect(source).toContain('placeholder="请选择船公司"')
+    expect(source).toContain('placeholder="请选择起运港"')
+    expect(source).toContain('placeholder="请选择目的港"')
+    expect(source).toContain('placeholder="请选择目的仓"')
+    expect(source).toContain("selectPort('departure'")
+    expect(source).toContain('selectDestinationWarehouse')
+    expect(source).toContain('重新加载业务选项')
+    expect(source).not.toContain('label="起运港代码"')
+    expect(source).not.toContain('label="起运港名称"')
+    expect(source).not.toContain('label="目的仓代码"')
+    expect(source).not.toContain('label="目的仓名称"')
+  })
+
+  it('keeps query and pagination on a single list request path', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/pages/ContainersView.vue'), 'utf8')
+    expect(source).toContain("if (page.value === 1) void loadRows(); else page.value = 1")
+    expect(source).toContain("if (nextPage !== previousPage || nextSize !== previousSize) void loadRows()")
+    expect(source).not.toContain('@reset=')
+  })
+
+  it('opens container detail as an independent route while keeping create and edit dialogs', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/pages/ContainersView.vue'), 'utf8')
+    expect(source).toContain("'domestic-container-detail' : 'overseas-container-detail'")
+    expect(source).not.toContain('<AppDialog v-model="detailOpen"')
+    expect(source).toContain('<AppDialog v-model="editorOpen" class="container-editor-dialog admin-density-dialog"')
+    expect(source).toContain('width="min(820px, calc(100vw - 28px))"')
+    expect(source).toContain('admin-density-dialog')
+    expect(source).toContain('grid-template-columns: repeat(2, minmax(0, 1fr))')
+    expect(source).not.toContain('AppDrawer')
+    expect(source).not.toContain('<AppDrawer v-model="editorOpen"')
+  })
+
+  it('registers a list-authorized independent container detail page', () => {
+    const routes = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/routes.ts'), 'utf8')
+    const detail = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/pages/ContainerDetailView.vue'), 'utf8')
+    expect(routes).toContain("path: 'container-loading/domestic/:containerId'")
+    expect(routes).toContain("name: 'domestic-container-detail'")
+    expect(routes).toContain("name: 'overseas-container-detail'")
+    expect(routes).toContain("permission: 'platform:firstleg:container:list'")
+    expect(detail).toContain('getContainer(containerId.value, props.workbench)')
+    expect(detail).toContain('getContainerOverview(containerId.value)')
+    expect(detail).toContain('<ContainerOverviewPanel')
+    expect(detail).toContain("@upload-document=\"openDocument\"")
+    expect(detail).toContain("@manage-exception=\"openException\"")
+    expect(detail).not.toContain("@preview-photo=\"previewPhoto\"")
+    expect(detail).toContain('<ContainerOverviewPanel')
+  })
+
+  it('keeps the prototype field sequence ahead of contract-only supplemental fields', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/pages/ContainersView.vue'), 'utf8')
+    const labels = ['真实集装箱号', '柜次号', '装柜仓库', '提单号', '船名', '航次', '箱型（货柜类型）', '船公司', '起运港', '目的港', '目的仓', '货柜容量（m³）']
+    let previous = -1
+    for (const label of labels) {
+      const current = source.indexOf(`label="${label}"`, previous + 1)
+      expect(current, label).toBeGreaterThan(previous)
+      previous = current
+    }
+  })
+
+  it('renders container business actions as buttons without changing the transport gate', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/pages/ContainersView.vue'), 'utf8')
+    expect(source).toContain('size="small" type="primary" plain :aria-label="containerViewLabel')
+    expect(source).toContain("hasAction(row as ContainerWorkbenchRow, 'EDIT_CONTAINER')")
+    expect(source).not.toContain("row.containerNo ? '修改集装箱号' : '录入集装箱号'")
+    expect(source).toContain('货柜基础资料不提供柜号写入')
+    expect(source).toContain('containerNo: optional(detail.value?.containerNo || null)')
+    expect(source).not.toContain('containerNo: optional(form.containerNo)')
+    expect(source).not.toContain('updateContainerTransport')
+    expect(source).toContain("row.planStatus === 'EDITING' && canSmartLoading")
+    expect(source).not.toContain('canSmartLoading && row.containerNo')
+    expect(source).not.toContain('link type="primary" :aria-label="containerViewLabel')
+    expect(source).toContain(':loading="loading" stripe preference-key="container-loading-table"')
+  })
+
+  it('updates an ACTIVE TRUCKING fleet inline and records actual empty return once', async () => {
+    vi.mocked(listSuppliers).mockResolvedValue({ records: [{ id: '502', name: '新车队', category: 'TRUCKING', truckingScope: 'OVERSEAS', status: 'ACTIVE' } as never], page: 1, size: 200, total: 1, pages: 1 })
+    const router = createTestRouter()
+    await router.push('/'); await router.isReady()
+    const wrapper = mount(ContainersView, { props: { workbench: 'OVERSEAS' }, global: { plugins: [ElementPlus, router] } })
+    await flushPromises()
+
+    const vm = wrapper.vm as unknown as {
+      rows: Array<Record<string, unknown>>
+      searchTerminalFleets: (keyword?: string) => Promise<void>
+      selectRowFleet: (row: Record<string, unknown>, supplierId: string) => Promise<void>
+      openDrayageAction: (row: Record<string, unknown>, action: 'RECORD_EMPTY_RETURN') => void
+      drayageActionAt: string
+      saveDrayageAction: () => Promise<void>
+    }
+    const beforeFleet = await listContainers({ page: 1, size: 20 }, 'OVERSEAS')
+    vi.mocked(listContainers).mockResolvedValueOnce({ ...beforeFleet, records: beforeFleet.records.map((row) => ({ ...row, terminalDrayage: { ...drayage, version: 4, fleetSupplierId: '502', allowedActions: [...drayage.allowedActions] } })) })
+    await vm.searchTerminalFleets('新车队')
+    await vm.selectRowFleet(vm.rows[0], '502')
+    expect(selectTerminalDrayageFleet).toHaveBeenCalledWith('9001', { expectedVersion: 3, fleetSupplierId: '502', fleetSupplierName: '新车队' })
+
+    vm.openDrayageAction(vm.rows[0], 'RECORD_EMPTY_RETURN')
+    vm.drayageActionAt = '2026-09-11T13:00:00'
+    const page: Awaited<ReturnType<typeof listContainers>> = await vi.mocked(listContainers).mock.results.at(-1)!.value
+    vi.mocked(listContainers).mockResolvedValueOnce({ ...page, records: page.records.map((row) => ({ ...row, allowedActions: [], terminalDrayage: { ...drayage, status: 'EMPTY_RETURNED', version: 5, allowedActions: [], emptyReturnWarning: { status: 'RESOLVED', deadlineAt: null, overdueHours: 0, overdueDays: 0 } } })) })
+    await vm.saveDrayageAction()
+    expect(recordTerminalDrayageEmptyReturn).toHaveBeenCalledWith('9001', { expectedVersion: 4, actualAt: '2026-09-11T13:00:00', remark: undefined })
+    expect(wrapper.text()).toContain('已还柜')
+    wrapper.unmount()
+  })
+
+  it('searches active terminal fleets remotely and ignores an older response', async () => {
+    const router = createTestRouter()
+    await router.push('/'); await router.isReady()
+    const wrapper = mount(ContainersView, { props: { workbench: 'OVERSEAS' }, global: { plugins: [ElementPlus, router] } })
+    await flushPromises()
+    let resolveOld!: (value: Awaited<ReturnType<typeof listSuppliers>>) => void
+    let resolveLatest!: (value: Awaited<ReturnType<typeof listSuppliers>>) => void
+    vi.mocked(listSuppliers).mockReset()
+      .mockReturnValueOnce(new Promise((resolve) => { resolveOld = resolve }))
+      .mockReturnValueOnce(new Promise((resolve) => { resolveLatest = resolve }))
+    const vm = wrapper.vm as unknown as {
+      terminalFleetOptions: Array<{ id: string; name: string }>
+      searchTerminalFleets: (keyword?: string) => Promise<void>
+    }
+
+    const oldSearch = vm.searchTerminalFleets('旧关键词')
+    const latestSearch = vm.searchTerminalFleets('新车队')
+    expect(listSuppliers).toHaveBeenNthCalledWith(1, { page: 1, size: 20, category: 'TRUCKING', truckingScope: 'OVERSEAS', status: 'ACTIVE', keyword: '旧关键词' })
+    expect(listSuppliers).toHaveBeenNthCalledWith(2, { page: 1, size: 20, category: 'TRUCKING', truckingScope: 'OVERSEAS', status: 'ACTIVE', keyword: '新车队' })
+    resolveLatest({ records: [{ id: '503', name: '新车队', category: 'TRUCKING', truckingScope: 'OVERSEAS', status: 'ACTIVE' } as never, { id: '504', name: '国内车队', category: 'TRUCKING', truckingScope: 'DOMESTIC', status: 'ACTIVE' } as never], page: 1, size: 20, total: 2, pages: 1 })
+    await latestSearch
+    resolveOld({ records: [{ id: '502', name: '旧车队', category: 'TRUCKING', truckingScope: 'OVERSEAS', status: 'ACTIVE' } as never], page: 1, size: 20, total: 1, pages: 1 })
+    await oldSearch
+    expect(vm.terminalFleetOptions).toEqual([expect.objectContaining({ id: '503', name: '新车队' })])
+    wrapper.unmount()
+  })
+
+  it('loads terminal drayage detail and history only when requested', async () => {
+    vi.mocked(getTerminalDrayageHistory).mockResolvedValueOnce([{ action: 'SELECT_FLEET', fromStatus: 'ARRIVED', toStatus: 'ARRIVED', fromVersion: 0, toVersion: 1, reason: '到港安排', operatorId: '88', operatorName: '管理员', createdAt: '2026-09-07T08:00:00' }])
+    const router = createTestRouter()
+    await router.push('/'); await router.isReady()
+    const wrapper = mount(ContainersView, { global: { plugins: [ElementPlus, router] } })
+    await flushPromises()
+    const vm = wrapper.vm as unknown as { rows: Array<Record<string, unknown>>; openDrayageHistory: (row: Record<string, unknown>) => Promise<void> }
+    await vm.openDrayageHistory(vm.rows[0])
+    await flushPromises()
+    expect(getTerminalDrayage).toHaveBeenCalledWith('9001')
+    expect(getTerminalDrayageHistory).toHaveBeenCalledWith('9001')
+    expect(wrapper.text()).toContain('到港安排')
+    wrapper.unmount()
+  })
+
+  it('owns the released-booking entry through the shared dialog without a detail redirect query', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/pages/ContainersView.vue'), 'utf8')
+    expect(source).toContain('<OceanBookingLinkDialog v-model="linkOpen" :container="linkTarget" @linked="loadRows" />')
+    expect(source).not.toContain('linkContainerId')
+  })
+
+  it('edits the whole-container expected arrival inline and shows PDA receiving start as actual arrival', async () => {
+    const wrapper = await mountOverseasRoute()
+    expect(wrapper.text()).toContain('预计到仓')
+    expect(wrapper.text()).toContain('实际到仓')
+    expect(wrapper.text()).toContain('2026-09-26 09:00')
+    const picker = wrapper.findAllComponents({ name: 'ElDatePicker' })
+      .find((item) => item.props('placeholder') === '选择预计到仓')
+    expect(picker).toBeDefined()
+
+    const vm = wrapper.findComponent(ContainersView).vm as unknown as {
+      rows: Array<Record<string, unknown>>
+      saveExpectedArrival: (row: Record<string, unknown>, value: string) => Promise<void>
+    }
+    await vm.saveExpectedArrival(vm.rows[0], '2026-09-25T16:00:00')
+    await flushPromises()
+
+    expect(updateContainerExpectedArrival).toHaveBeenCalledWith('9001', {
+      estimatedWarehouseArrivalAt: '2026-09-25T16:00:00', expectedVersion: 0,
+    })
+  })
+
+  it.each(['EDITING', 'LOADING', 'COMPLETED'] as const)('keeps released-booking linking reachable alongside the %s process action', async (planStatus) => {
+    const page = await listContainers({ page: 1, size: 20 }, 'DOMESTIC')
+    vi.mocked(listContainers).mockResolvedValue({ ...page, records: page.records.map((row) => ({
+      ...row, planStatus, containerNo: null, allowedActions: ['EDIT_CONTAINER'],
+    })) })
+    const router = createTestRouter()
+    await router.push('/'); await router.isReady()
+    const wrapper = mount(ContainersView, { attachTo: document.body, global: { plugins: [ElementPlus, router] } })
+    try {
+      await flushPromises()
+      const actions = wrapper.find('.el-table__body .row-actions')
+      expect(actions.findAll('button').map((button) => button.text())).toEqual(['查看', '编辑', ({ EDITING: '装柜', LOADING: '预装清单', COMPLETED: '装柜清单' })[planStatus], ''])
+      await actions.find('button[aria-label="更多货柜操作"]').trigger('click')
+      await flushPromises()
+      const link = Array.from(document.body.querySelectorAll<HTMLElement>('.el-dropdown-menu__item'))
+        .filter((item) => item.textContent?.includes('关联已放舱订舱')).at(-1)!
+      expect(link).toBeDefined()
+      link.click()
+      await flushPromises()
+      expect(wrapper.findAllComponents(AppDialog).find((dialog) => dialog.props('title') === '关联已放舱订舱')?.props('modelValue')).toBe(true)
+      expect(listOceanBookingLinkCandidates).toHaveBeenCalledWith({ warehouseId: '8', channelGroupCode: 'MATSON_CLX', containerType: '40HQ', page: 1, size: 200 })
+    } finally {
+      wrapper.unmount()
+    }
+  })
+
+  it('keeps document uploads on the routed detail page without duplicate list implementations', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/pages/ContainersView.vue'), 'utf8')
+    const detailSource = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/pages/ContainerDetailView.vue'), 'utf8')
+    expect(source).not.toContain('uploadLoadingDeclaration')
+    expect(source).not.toContain('uploadContainerClearance')
+    expect(source).not.toContain('uploadContainerDocument')
+    expect(detailSource).not.toContain('uploadLoadingDeclaration')
+    expect(detailSource).toContain('ContainerCustomsPanel')
+    expect(detailSource).toContain('uploadContainerClearance')
+    expect(detailSource).toContain('uploadContainerDocument')
+  })
+
+  it('creates an internal simulation without asking for real booking transport facts', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/pages/ContainersView.vue'), 'utf8')
+    const simulationSource = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/components/ContainerSimulationCreate.vue'), 'utf8')
+    expect(source).toContain('ContainerSimulationCreate')
+    expect(source).not.toContain('新增货柜')
+    expect(simulationSource).toContain('新增模拟柜')
+    expect(simulationSource).toContain('createContainerSimulation({ ...simulationForm })')
+    expect(simulationSource).toContain("channelGroupCode: '', warehouseId: '', containerType: DEFAULT_CONTAINER_TYPE, capacityCbm: 68, maxWeightKg: 19500")
+    expect(source).toContain('CONTAINER_SPECIFICATIONS')
+    expect(simulationSource).toContain('selectSimulationContainerType')
+    expect(simulationSource).toContain('服务端会生成稳定的柜次号')
+    expect(source).toContain(':model-value="form.cabinetNo" disabled placeholder="系统生成"')
+    expect(source).not.toContain('v-model="form.cabinetNo"')
+    expect(source).not.toContain('cabinetNo: form.cabinetNo.trim()')
+    expect(source).not.toContain('openCreate')
+    expect(source).not.toContain('20GP')
+    expect(source).not.toContain('40HC')
+    expect(source).not.toContain('40NR')
+    expect(source).not.toContain('45HC')
+    expect(source).not.toContain('v-model="form.capacityCbm"')
+    expect(source).not.toContain('v-model="form.maxWeightKg"')
+  })
+
+  it('filters OB-260825-0183 for CAB-260825-0215 because the real warehouses differ', async () => {
+    vi.mocked(listContainers).mockResolvedValue({ records: [{
+      id: '215', planId: null, bookingNo: 'CB-260825-0215', cabinetNo: 'CAB-260825-0215', containerNo: null,
+      sourceType: 'SIMULATION', allowedActions: ['EDIT_CONTAINER'], oceanBookingId: null, warehouseId: '193000000000200002', warehouseName: '东莞仓',
+      channelGroupCode: 'EXX', channelCode: null, channelName: null, containerType: '45HQ', planStatus: 'EDITING',
+      capacityCbm: 86, maxWeightKg: 29000, version: 7,
+    }], page: 1, size: 20, total: 1, pages: 1 } as never)
+    vi.mocked(listOceanBookingLinkCandidates).mockResolvedValueOnce({ records: [], page: 1, size: 200, total: 0, pages: 0 })
+    const router = createTestRouter()
+    await router.push('/'); await router.isReady()
+    const wrapper = mount(ContainersView, { attachTo: document.body, global: { plugins: [ElementPlus, router] } })
+    await flushPromises()
+    await wrapper.find('.el-table__body button[aria-label="更多货柜操作"]').trigger('click')
+    await flushPromises()
+    Array.from(document.body.querySelectorAll<HTMLElement>('.el-dropdown-menu__item'))
+      .filter((item) => item.textContent?.includes('关联已放舱订舱')).at(-1)!.click()
+    await flushPromises()
+
+    expect(listOceanBookingLinkCandidates).toHaveBeenCalledWith({ warehouseId: '193000000000200002', channelGroupCode: 'EXX', containerType: '45HQ', page: 1, size: 200 })
+    expect((wrapper.findComponent(OceanBookingLinkDialog).vm as unknown as { candidates: unknown[] }).candidates).toEqual([])
+    expect(readFileSync(resolve(process.cwd(), 'src/modules/container-loading/components/OceanBookingLinkDialog.vue'), 'utf8'))
+      .toContain('暂无符合当前装柜仓库、物流渠道和柜型的已放舱需求')
+    expect(getOceanBooking).not.toHaveBeenCalled()
+    wrapper.unmount()
+  })
+
+  it.each([undefined, null, '', '客户一'])('renders optional booking customer %s without leaking a missing value', async (customerName) => {
+    vi.mocked(listOceanBookingLinkCandidates).mockResolvedValueOnce({ records: [{
+      oceanBookingId: '315', bookingNo: 'OB-OPTIONAL-CUSTOMER', requirementId: '45315',
+      containerType: '40HQ', remainingQuantity: 1, customerName, warehouseName: '义乌仓', channelName: 'EXX海卡',
+    }], page: 1, size: 200, total: 1, pages: 1 } as never)
+    const router = createTestRouter()
+    await router.push('/'); await router.isReady()
+    const wrapper = mount(ContainersView, { attachTo: document.body, global: { plugins: [ElementPlus, router] } })
+    await flushPromises()
+    await wrapper.find('button[aria-label="更多货柜操作"]').trigger('click')
+    await flushPromises()
+    Array.from(document.body.querySelectorAll<HTMLElement>('.el-dropdown-menu__item'))
+      .filter((item) => item.textContent?.includes('关联已放舱订舱')).at(-1)!.click()
+    await flushPromises()
+    const label = `OB-OPTIONAL-CUSTOMER · 40HQ × 1 · ${customerName || '未关联客户'} · 义乌仓 · EXX海卡`
+    expect(document.body.textContent).toContain(label)
+    expect((wrapper.findComponent(OceanBookingLinkDialog).vm as unknown as { candidates: Array<{ label: string }> }).candidates[0]?.label).toBe(label)
+    wrapper.unmount()
+  })
+
+  it('keeps a three-field match selectable when only capacity snapshots differ and blocks duplicate waves', async () => {
+    let resolveCandidates!: (value: Awaited<ReturnType<typeof listOceanBookingLinkCandidates>>) => void
+    vi.mocked(listContainers).mockResolvedValue({ records: [{
+      id: '315', planId: null, bookingNo: 'CB-CAPACITY-SNAPSHOT', cabinetNo: 'CAB-CAPACITY-SNAPSHOT', containerNo: null,
+      sourceType: 'SIMULATION', allowedActions: ['EDIT_CONTAINER'], oceanBookingId: null, warehouseId: '193000000000200002', warehouseName: '东莞仓',
+      channelGroupCode: 'EXX', channelCode: null, channelName: null, containerType: '45HQ', planStatus: 'WAIT_LOADING',
+      capacityCbm: 86, maxWeightKg: 29000, version: 7,
+    }], page: 1, size: 20, total: 1, pages: 1 } as never)
+    vi.mocked(listOceanBookingLinkCandidates).mockReturnValueOnce(new Promise((resolve) => { resolveCandidates = resolve }))
+    const router = createTestRouter()
+    await router.push('/'); await router.isReady()
+    const wrapper = mount(ContainersView, { attachTo: document.body, global: { plugins: [ElementPlus, router] } })
+    await flushPromises()
+    await wrapper.find('.el-table__body button[aria-label="更多货柜操作"]').trigger('click')
+    await flushPromises()
+    const linkAction = Array.from(document.body.querySelectorAll<HTMLElement>('.el-dropdown-menu__item'))
+      .filter((item) => item.textContent?.includes('关联已放舱订舱')).at(-1)!
+
+    linkAction.click()
+    await flushPromises()
+    linkAction.click()
+
+    expect(listOceanBookingLinkCandidates).toHaveBeenCalledTimes(1)
+    expect(listOceanBookingLinkCandidates).toHaveBeenCalledWith({ warehouseId: '193000000000200002', channelGroupCode: 'EXX', containerType: '45HQ', page: 1, size: 200 })
+    expect(getOceanBooking).not.toHaveBeenCalled()
+    resolveCandidates({ records: [{ oceanBookingId: '315', bookingNo: 'OB-CAPACITY-SNAPSHOT', requirementId: '45315', containerType: '45HQ', capacityCbm: 85, maxWeightKg: 28500, requiredQuantity: 1, allocatedQuantity: 0, remainingQuantity: 1, customerName: '客户', warehouseName: '东莞仓', channelName: '纽约铁路' }], page: 1, size: 200, total: 1, pages: 1 })
+    await flushPromises()
+    expect(document.body.textContent).toContain('OB-CAPACITY-SNAPSHOT · 45HQ × 1')
+    expect((wrapper.findComponent(OceanBookingLinkDialog).vm as unknown as { candidates: Array<{ key: string }> }).candidates[0]?.key).toBe('315:45315')
+    wrapper.unmount()
+  })
+
+  it('discards a candidate response from a closed link session', async () => {
+    let resolveFirst!: (value: Awaited<ReturnType<typeof listOceanBookingLinkCandidates>>) => void
+    let resolveSecond!: (value: Awaited<ReturnType<typeof listOceanBookingLinkCandidates>>) => void
+    vi.mocked(listOceanBookingLinkCandidates)
+      .mockReturnValueOnce(new Promise((resolve) => { resolveFirst = resolve }))
+      .mockReturnValueOnce(new Promise((resolve) => { resolveSecond = resolve }))
+    const router = createTestRouter()
+    await router.push('/'); await router.isReady()
+    const wrapper = mount(ContainersView, { attachTo: document.body, global: { plugins: [ElementPlus, router] } })
+    await flushPromises()
+
+    await wrapper.find('.el-table__body button[aria-label="更多货柜操作"]').trigger('click')
+    await flushPromises()
+    Array.from(document.body.querySelectorAll<HTMLElement>('.el-dropdown-menu__item'))
+      .filter((item) => item.textContent?.includes('关联已放舱订舱')).at(-1)!.click()
+    await flushPromises()
+    wrapper.findAllComponents(AppDialog)
+      .find((dialog) => dialog.props('title') === '关联已放舱订舱')!.vm.$emit('update:modelValue', false)
+    await flushPromises()
+
+    await wrapper.find('.el-table__body button[aria-label="更多货柜操作"]').trigger('click')
+    await flushPromises()
+    Array.from(document.body.querySelectorAll<HTMLElement>('.el-dropdown-menu__item'))
+      .filter((item) => item.textContent?.includes('关联已放舱订舱')).at(-1)!.click()
+    resolveSecond({ records: [{ oceanBookingId: '303', bookingNo: 'OB-LATEST', requirementId: '404', containerType: '40HQ', capacityCbm: 68, maxWeightKg: 19500, requiredQuantity: 1, allocatedQuantity: 0, remainingQuantity: 1, customerName: '客户', warehouseName: '义乌仓', channelName: '美森正班海卡包税' }], page: 1, size: 200, total: 1, pages: 1 })
+    await flushPromises()
+    resolveFirst({ records: [{ oceanBookingId: '101', bookingNo: 'OB-STALE', requirementId: '202', containerType: '40HQ', capacityCbm: 68, maxWeightKg: 19500, requiredQuantity: 1, allocatedQuantity: 0, remainingQuantity: 1, customerName: '客户', warehouseName: '义乌仓', channelName: '美森正班海卡包税' }], page: 1, size: 200, total: 1, pages: 1 })
+    await flushPromises()
+
+    expect(listOceanBookingLinkCandidates).toHaveBeenCalledTimes(2)
+    const candidateLabels = (wrapper.findComponent(OceanBookingLinkDialog).vm as unknown as { candidates: Array<{ label: string }> }).candidates.map((candidate) => candidate.label)
+    expect(candidateLabels.some((label) => label.includes('OB-LATEST'))).toBe(true)
+    expect(candidateLabels.some((label) => label.includes('OB-STALE'))).toBe(false)
+    wrapper.unmount()
+  })
+
+  it('backfills a legacy trucking supplier name and submits the frozen id-name pair', async () => {
+    vi.mocked(listSuppliers).mockResolvedValue({ records: [{ id: '9007199254740998', tenantId: '1', name: '测试拖车供应商', category: 'TRUCKING', truckingScope: 'OVERSEAS', carrierCodes: [], region: 'CN', legalRepresentative: '张三', contactName: '李四', phone: '13800000000', email: null, address: null, businessLicenseNo: null, licenseFileId: null, status: 'ACTIVE', settlementPeriod: 'MONTHLY_30', remark: null, createdBy: null, createdAt: '2026-08-25T10:00:00', updatedBy: null, updatedAt: '2026-08-25T10:00:00', deleted: false, version: 0 }], page: 1, size: 200, total: 1, pages: 1 })
+    vi.mocked(getContainer).mockResolvedValueOnce({ id: '9001', allowedActions: ['EDIT_CONTAINER'], planStatus: 'WAIT_LOADING', containerType: '40HQ', warehouseId: '8', terminalTruckingCompanyId: null, terminalTruckingCompany: '测试拖车供应商' } as never)
+    vi.mocked(updateContainer).mockResolvedValue({} as never)
+    const router = createTestRouter()
+    await router.push('/'); await router.isReady()
+    const wrapper = mount(ContainersView, { global: { plugins: [ElementPlus, router] } })
+    await flushPromises()
+
+    await wrapper.findAll('button').find((button) => button.text().trim() === '编辑')!.trigger('click')
+    await flushPromises()
+    await wrapper.findAll('button').find((button) => button.text().trim() === '确定')!.trigger('click')
+    await flushPromises()
+
+    expect(updateContainer).toHaveBeenCalledWith('9001', 0, expect.objectContaining({
+      terminalTruckingCompanyId: '9007199254740998',
+      terminalTruckingCompany: '测试拖车供应商',
+    }))
+  })
+
+  it('clears the trucking supplier id and name together', async () => {
+    vi.mocked(listSuppliers).mockResolvedValue({ records: [{ id: '9007199254740998', tenantId: '1', name: '测试拖车供应商', category: 'TRUCKING', truckingScope: 'OVERSEAS', carrierCodes: [], region: 'CN', legalRepresentative: '张三', contactName: '李四', phone: '13800000000', email: null, address: null, businessLicenseNo: null, licenseFileId: null, status: 'ACTIVE', settlementPeriod: 'MONTHLY_30', remark: null, createdBy: null, createdAt: '2026-08-25T10:00:00', updatedBy: null, updatedAt: '2026-08-25T10:00:00', deleted: false, version: 0 }], page: 1, size: 200, total: 1, pages: 1 })
+    vi.mocked(getContainer).mockResolvedValueOnce({ id: '9001', allowedActions: ['EDIT_CONTAINER'], planStatus: 'WAIT_LOADING', containerType: '40HQ', warehouseId: '8', terminalTruckingCompanyId: '9007199254740998', terminalTruckingCompany: '测试拖车供应商' } as never)
+    vi.mocked(updateContainer).mockResolvedValue({} as never)
+    const router = createTestRouter()
+    await router.push('/'); await router.isReady()
+    const wrapper = mount(ContainersView, { global: { plugins: [ElementPlus, router] } })
+    await flushPromises()
+
+    await wrapper.findAll('button').find((button) => button.text().trim() === '编辑')!.trigger('click')
+    await flushPromises()
+    const truckingSelect = wrapper.findAllComponents({ name: 'ElSelect' }).find((select) => select.props('placeholder') === '请选择拖车供应商')
+    truckingSelect!.vm.$emit('update:modelValue', '')
+    await flushPromises()
+    await wrapper.findAll('button').find((button) => button.text().trim() === '确定')!.trigger('click')
+    await flushPromises()
+
+    expect(updateContainer).toHaveBeenCalledWith('9001', 0, expect.objectContaining({
+      terminalTruckingCompanyId: null,
+      terminalTruckingCompany: null,
+    }))
+  })
+
+  it('blocks saving a legacy trucking supplier name that no longer matches an active option', async () => {
+    vi.mocked(getContainer).mockResolvedValueOnce({ id: '9001', allowedActions: ['EDIT_CONTAINER'], planStatus: 'WAIT_LOADING', containerType: '40HQ', warehouseId: '8', terminalTruckingCompanyId: null, terminalTruckingCompany: '已停用拖车供应商' } as never)
+    vi.mocked(updateContainer).mockClear()
+    const router = createTestRouter()
+    await router.push('/'); await router.isReady()
+    const wrapper = mount(ContainersView, { global: { plugins: [ElementPlus, router] } })
+    await flushPromises()
+
+    await wrapper.findAll('button').find((button) => button.text().trim() === '编辑')!.trigger('click')
+    await flushPromises()
+    const truckingSelect = wrapper.findAllComponents({ name: 'ElSelect' }).find((select) => select.props('placeholder') === '请选择拖车供应商')
+    expect(truckingSelect?.props('modelValue')).toBe('')
+    await wrapper.findAll('button').find((button) => button.text().trim() === '确定')!.trigger('click')
+    await flushPromises()
+
+    expect(updateContainer).not.toHaveBeenCalled()
+    expect(wrapper.text()).toContain('原拖车供应商已不可用，请重新选择合作中的拖车供应商')
+  })
+})
+
+describe('ContainersView trucking supplier contract', () => {
+  it('shows the frozen plan, exception and document aggregates without deriving them client-side', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/pages/ContainersView.vue'), 'utf8')
+    const fields = ['containerNo', 'planNo', 'planStatus', 'exceptionActive', 'cabinetNo', 'destinationClearanceDocumentStatus', 'deliveryOrderDocumentStatus', 'pickupCode']
+    let previous = source.indexOf("key: 'actions'")
+    for (const field of fields) {
+      const current = source.indexOf(`key: '${field}'`, previous + 1)
+      expect(current, field).toBeGreaterThan(previous)
+      previous = current
+    }
+    expect(source).toContain("MISSING: '未上传', UPLOADED: '已上传', COMPLETED: '已完成'")
+    const detail = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/pages/ContainerDetailView.vue'), 'utf8')
+    expect(detail).toContain("detail.planNo || '—'")
+    expect(detail).toContain("detail.exceptionActive ? '异常' : '正常'")
+  })
+
+  it('uses active TRUCKING suppliers without allowing free-text carrier names', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/pages/ContainersView.vue'), 'utf8')
+    expect(source).toContain("listSuppliers({ page: 1, size: 200, category: 'TRUCKING', truckingScope: 'OVERSEAS', status: 'ACTIVE' })")
+    expect(source).toContain("page: 1, size: 20, category: 'TRUCKING', truckingScope: 'OVERSEAS', status: 'ACTIVE', keyword: keyword.trim() || undefined")
+    expect(source).toContain("supplier.category === 'TRUCKING' && supplier.truckingScope === 'OVERSEAS' && supplier.status === 'ACTIVE'")
+    expect(source).toContain('filterable remote reserve-keyword remote-show-suffix')
+    expect(source).toContain(':remote-method="searchTerminalFleets"')
+    expect(source).toContain('selectTruckingSupplier')
+    expect(source).toContain('请选择有效的合作中拖车供应商')
+    expect(source).not.toContain('allow-create')
+  })
+})
diff --git a/src/modules/container-loading/pages/ContainersView.vue b/src/modules/container-loading/pages/ContainersView.vue
new file mode 100644
index 00000000..d9c9283d
--- /dev/null
+++ b/src/modules/container-loading/pages/ContainersView.vue
@@ -0,0 +1,804 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, reactive, ref, watch } from 'vue'
+import ContainerSimulationCreate from '../components/ContainerSimulationCreate.vue'
+import { useRouter } from 'vue-router'
+import { MoreHorizontal } from '@lucide/vue'
+import { ElMessage, ElMessageBox, type FormInstance, type FormRules } from 'element-plus'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { listPlatformTenants, type PlatformTenantResource } from '@/modules/iam'
+import { listAllPlatformWarehouses, type PlatformWarehouseSummaryResource } from '@/modules/warehouses'
+import { listPlatformPartners, type PlatformPartnerResource } from '@/modules/master-data'
+import { listSuppliers, type Supplier } from '@/modules/suppliers'
+import { listOceanBookings, type OceanBookingResource } from '@/modules/ocean-bookings'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import { CONTAINER_SPECIFICATIONS, DEFAULT_CONTAINER_TYPE, applyContainerSpecification, containerSpecification } from '@/shared/domain/containerSpecifications'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { getContainer, listContainers, updateContainer } from '../api/platformContainerLoading'
+import OceanBookingLinkDialog from '../components/OceanBookingLinkDialog.vue'
+import { getSmartLoadingChannelGroup } from '../smartLoadingChannelGroups'
+import {
+  getTerminalDrayageEmails,
+  sendTerminalDrayageEmail,
+  retryTerminalDrayageEmail,
+  type TerminalDrayageEmail,
+  getTerminalDrayage,
+  getTerminalDrayageHistory,
+  recordTerminalDrayageEmptyReturn,
+  selectTerminalDrayageFleet,
+  type TerminalDrayageAction,
+  type TerminalDrayageHistory,
+  type TerminalDrayageView,
+} from '../api/terminalDrayages'
+import { listContainerArrivalTimes, updateContainerExpectedArrival, type ContainerArrivalTime } from '../api/containerArrivalTimes'
+import type { ContainerBookingResource, ContainerDocumentStatus, ContainerPlanStatus, ContainerSaveRequest, ContainerWorkbenchAction, ContainerWorkbenchRow } from '../types'
+
+type Filters = QueryModel & { customerId: string; keyword: string; containerType: string; status: ContainerPlanStatus | ''; sailingRange: string[] }
+type ContainerForm = ContainerSaveRequest & Pick<ContainerBookingResource, 'cabinetNo'> & { id: string; version: number }
+
+const props = withDefaults(defineProps<{ workbench?: 'DOMESTIC' | 'OVERSEAS' }>(), { workbench: 'DOMESTIC' })
+
+const router = useRouter()
+const access = useAccessPreviewStore()
+const rows = ref<ContainerWorkbenchRow[]>([])
+const customers = ref<PlatformTenantResource[]>([])
+const customersLoading = ref(false)
+const warehouses = ref<PlatformWarehouseSummaryResource[]>([])
+const destinationWarehouses = ref<PlatformWarehouseSummaryResource[]>([])
+const partners = ref<PlatformPartnerResource[]>([])
+const truckingSuppliers = ref<Supplier[]>([])
+const terminalFleetOptions = ref<Supplier[]>([])
+const terminalFleetLoading = ref(false)
+const oceanBookings = ref<OceanBookingResource[]>([])
+const loading = ref(false)
+const warehouseLoading = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const warehouseError = ref<ApiErrorDetails | null>(null)
+const businessOptionsLoading = ref(false)
+const businessOptionsError = ref('')
+const page = ref(1)
+const pageSize = ref(20)
+const total = ref(0)
+const scope = ref<'ACTIVE' | 'HISTORY'>('ACTIVE')
+const filters = ref<Filters>({ customerId: '', keyword: '', containerType: '', status: '', sailingRange: [] })
+const applied = ref<Filters>({ ...filters.value })
+const detail = ref<ContainerBookingResource | null>(null)
+const editorOpen = ref(false)
+const editorError = ref<ApiErrorDetails | null>(null)
+const saving = ref(false)
+const formRef = ref<FormInstance>()
+const linkOpen = ref(false)
+const linkTarget = ref<ContainerBookingResource | null>(null)
+const selectedTruckingSupplierId = ref('')
+const unresolvedTruckingSupplierName = ref<string | null>(null)
+const drayages = ref<Record<string, TerminalDrayageView>>({})
+const arrivalTimes = ref<Record<string, ContainerArrivalTime>>({})
+const arrivalInputs = ref<Record<string, string>>({})
+const arrivalSavingIds = ref<string[]>([])
+const drayageSavingIds = ref<string[]>([])
+const drayageActionOpen = ref(false)
+const drayageAction = ref<Exclude<TerminalDrayageAction, 'SELECT_FLEET' | 'SEND_PICKUP_EMAIL'>>('SCHEDULE_PICKUP')
+const drayageTarget = ref<ContainerBookingResource | null>(null)
+const drayageActionAt = ref('')
+const drayageReason = ref('')
+const drayageActionSaving = ref(false)
+const drayageActionError = ref<ApiErrorDetails | null>(null)
+const drayageHistoryOpen = ref(false)
+const drayageHistory = ref<TerminalDrayageHistory[]>([])
+const drayageHistoryLoading = ref(false)
+const drayageHistoryError = ref<ApiErrorDetails | null>(null)
+const emailHistoryOpen = ref(false)
+const emailTarget = ref<ContainerBookingResource | null>(null)
+const emails = ref<TerminalDrayageEmail[]>([])
+const emailsLoading = ref(false)
+const emailsError = ref<ApiErrorDetails | null>(null)
+const emailDeliveryEnabled = ref(false)
+const retryingEmail = ref('')
+let emailSequence = 0
+const emailColumns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 90, fixed: 'left', slotName: 'emailActions' },
+  { key: 'kind', label: '类型', width: 100, formatter: (row: TerminalDrayageEmail) => row.kind === 'CANCEL_PICKUP' ? '取消提柜' : '请求提柜' },
+  { key: 'fleetName', label: '车队', minWidth: 130 },
+  { key: 'recipient', label: '收件邮箱', minWidth: 210 },
+  { key: 'status', label: '发送状态', width: 100, formatter: (row: TerminalDrayageEmail) => ({ PENDING: '待发送', SENDING: '发送中', SENT: '已发送', FAILED: '失败待核对' })[row.status] },
+  { key: 'content', label: '邮件内容', minWidth: 270, slotName: 'emailContent' },
+  { key: 'failureReason', label: '失败说明', minWidth: 200 },
+  { key: 'createdAt', label: '创建时间', width: 165, formatter: (row: TerminalDrayageEmail) => formatTime(row.createdAt) },
+  { key: 'sentAt', label: '发送时间', width: 165, formatter: (row: TerminalDrayageEmail) => formatTime(row.sentAt) },
+]
+
+async function sendPickupEmail(row: ContainerWorkbenchRow) {
+  const current = drayageFor(row.id)
+  if (!current || !canDrayage(row, 'SEND_PICKUP_EMAIL') || drayageSavingIds.value.includes(row.id)) return
+  drayageSavingIds.value.push(row.id)
+  try {
+    replaceDrayage(await sendTerminalDrayageEmail(row.id, current.version))
+    ElMessage.success('提柜邮件已加入发送队列，可在邮件记录中查看结果')
+    await loadRows()
+  } catch (error) {
+    ElMessage.error(getApiErrorDetails(error, '提交提柜邮件失败').message)
+    await loadRows()
+  } finally { drayageSavingIds.value = drayageSavingIds.value.filter((id) => id !== row.id) }
+}
+
+async function openEmailHistory(row: ContainerBookingResource) {
+  const sequence = ++emailSequence
+  emailTarget.value = row; emailHistoryOpen.value = true; emailsLoading.value = true
+  emailsError.value = null; emails.value = []
+  try {
+    const result = await getTerminalDrayageEmails(row.id)
+    if (sequence !== emailSequence) return
+    emails.value = result.records; emailDeliveryEnabled.value = result.deliveryEnabled
+  } catch (error) {
+    if (sequence === emailSequence) emailsError.value = getApiErrorDetails(error, '邮件记录加载失败')
+  } finally { if (sequence === emailSequence) emailsLoading.value = false }
+}
+
+async function retryEmail(mail: TerminalDrayageEmail) {
+  const target = emailTarget.value
+  if (!target || !canFleetEdit.value || retryingEmail.value || mail.status !== 'FAILED') return
+  retryingEmail.value = mail.id
+  try {
+    await ElMessageBox.confirm('发送失败时邮件仍可能已送达。请先核对车队未收到，再确认重试；同柜后续邮件会等待本邮件发送成功。', '重试邮件', { customClass: 'admin-density-confirm', confirmButtonText: '确认重试', cancelButtonText: '取消', type: 'warning' })
+    await retryTerminalDrayageEmail(target.id, mail.id)
+    ElMessage.success('邮件已重新加入发送队列')
+    await openEmailHistory(target)
+  } catch (error) {
+    if (error !== 'cancel' && error !== 'close') ElMessage.error(getApiErrorDetails(error, '重试邮件失败').message)
+  } finally { retryingEmail.value = '' }
+}
+let listSequence = 0
+let detailSequence = 0
+let warehousesLoaded = false
+let warehouseOptionsPromise: Promise<void> | null = null
+let partnersLoaded = false
+let truckingSuppliersLoaded = false
+let truckingSuppliersPromise: Promise<Supplier[]> | null = null
+let terminalFleetSearchSequence = 0
+let oceanBookingsLoaded = false
+let businessOptionsPromise: Promise<void> | null = null
+
+function emptyForm(): ContainerForm {
+  return {
+    id: '', version: 0, containerNo: null, cabinetNo: '', warehouseId: '', warehouseName: null,
+    billOfLadingNo: null, vesselName: null, voyageNo: null, containerType: DEFAULT_CONTAINER_TYPE, shippingCompanyId: null,
+    shippingCompanyName: null, departurePortCode: null, departurePortName: null, destinationPortCode: null,
+    destinationPortName: null, destinationWarehouseCode: null, destinationWarehouseName: null,
+    capacityCbm: 68, maxWeightKg: 19500, terminalTruckingCompanyId: null, terminalTruckingCompany: null, loadingAt: null,
+    estimatedSailingAt: null, actualSailingAt: null, estimatedPortArrivalAt: null, actualPortArrivalAt: null,
+    estimatedWarehouseArrivalAt: null, actualWarehouseArrivalAt: null,
+  }
+}
+const form = reactive<ContainerForm>(emptyForm())
+const rules: FormRules<ContainerForm> = {
+  warehouseId: [{ required: true, message: '请选择装柜仓库', trigger: 'change' }],
+  containerType: [{ required: true, message: '请选择柜型', trigger: 'change' }],
+  terminalTruckingCompany: [{ validator: (_rule, value, callback) => callback(unresolvedTruckingSupplierName.value || (value && !selectedTruckingSupplierId.value) ? new Error('请选择有效的合作中拖车供应商') : undefined), trigger: 'change' }],
+}
+
+const isDomestic = computed(() => props.workbench === 'DOMESTIC')
+const isOverseas = computed(() => props.workbench === 'OVERSEAS')
+const canView = computed(() => isDomestic.value ? access.can('platform:firstleg:container:list') : access.can('platform:firstleg:terminal-drayage:list'))
+const canEdit = computed(() => access.can('platform:firstleg:container:edit'))
+const canCreate = computed(() => access.can('platform:firstleg:container:create'))
+const canOverseasDocumentEdit = computed(() => access.can('platform:firstleg:terminal-drayage:document:edit'))
+const canFleetEdit = computed(() => access.can('platform:firstleg:terminal-drayage:fleet:edit'))
+const canPickupAppointmentEdit = computed(() => access.can('platform:firstleg:terminal-drayage:pickup-appointment:edit'))
+const canExpectedArrivalEdit = computed(() => access.can('platform:overseas-warehouse:last-mile-order:edit'))
+const canEmptyReturnConfirm = computed(() => access.can('platform:firstleg:terminal-drayage:empty-return:confirm'))
+const canSmartLoading = computed(() => access.can('platform:firstleg:smart-loading:list'))
+const canViewPreload = computed(() => access.can('platform:firstleg:preload:list'))
+const canViewLoadingList = computed(() => access.can('platform:firstleg:loading-list:list'))
+const editorTitle = computed(() => form.id ? '编辑' : '新增')
+const shippingCompanies = computed(() => partners.value.filter((partner) => partner.status === 'ACTIVE' && partner.types.includes('CARRIER')))
+const truckingCompanies = computed(() => truckingSuppliers.value.filter((supplier) => supplier.status === 'ACTIVE' && supplier.category === 'TRUCKING' && supplier.truckingScope === 'OVERSEAS'))
+interface PortOption { value: string; code: string | null; name: string | null }
+function portValue(code: string | null | undefined, name: string | null | undefined) { return code || name ? JSON.stringify([code || '', name || '']) : '' }
+function collectPorts(direction: 'departure' | 'destination'): PortOption[] {
+  const entries = oceanBookings.value.map((booking) => direction === 'departure'
+    ? { code: booking.departurePortCode, name: booking.departurePortName }
+    : { code: booking.destinationPortCode, name: booking.destinationPortName })
+  const current = direction === 'departure'
+    ? { code: form.departurePortCode, name: form.departurePortName }
+    : { code: form.destinationPortCode, name: form.destinationPortName }
+  entries.push(current)
+  const options = new Map<string, PortOption>()
+  for (const entry of entries) {
+    if (!entry.code && !entry.name) continue
+    const value = portValue(entry.code, entry.name)
+    options.set(value, { value, code: entry.code || null, name: entry.name || null })
+  }
+  return [...options.values()].sort((left, right) => (left.name || left.code || '').localeCompare(right.name || right.code || '', 'zh-CN'))
+}
+const departurePorts = computed(() => collectPorts('departure'))
+const destinationPorts = computed(() => collectPorts('destination'))
+const departurePortValue = computed(() => portValue(form.departurePortCode, form.departurePortName))
+const destinationPortValue = computed(() => portValue(form.destinationPortCode, form.destinationPortName))
+const shippingCompanyValue = computed(() => form.shippingCompanyId || (form.shippingCompanyName ? `name:${form.shippingCompanyName}` : ''))
+const destinationWarehouseValue = computed(() => form.destinationWarehouseCode || (form.destinationWarehouseName ? `name:${form.destinationWarehouseName}` : ''))
+
+const queryFields = computed<QueryField[]>(() => [
+  { key: 'customerId', type: 'select', label: '客户', width: 220, placeholder: '全部客户', options: customers.value.filter((customer) => customer.status === 'ACTIVE').map((customer) => ({ label: customer.tenantName, value: String(customer.id) })), props: { filterable: true, loading: customersLoading.value } },
+  { key: 'keyword', type: 'input', label: '关键词', width: 220, placeholder: '柜次号、集装箱号或提单号', props: { 'aria-label': '关键词', maxlength: 128 } },
+  { key: 'containerType', type: 'select', label: '柜型', width: 140, placeholder: '请选择箱型', options: CONTAINER_SPECIFICATIONS.map((item) => ({ label: item.type, value: item.type })), props: { 'aria-label': '柜型' } },
+  { key: 'status', type: 'select', label: '装柜状态', width: 150, placeholder: '请选择货柜状态', options: [{ label: '待装柜', value: 'WAIT_LOADING' }, { label: '预装柜中', value: 'EDITING' }, { label: '拣货中', value: 'LOADING' }, { label: '装柜完成', value: 'COMPLETED' }], props: { 'aria-label': '装柜状态' } },
+  { key: 'sailingRange', type: 'daterange', label: '预计开船', width: 260, props: { 'aria-label': '预计开船日期范围' } },
+])
+const allColumns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 240, fixed: 'left', slotName: 'actions' },
+  { key: 'emptyReturnWarning', label: '报空预警', width: 120, slotName: 'emptyReturnWarning' },
+  { key: 'containerNo', label: '集装箱号', minWidth: 150, slotName: 'containerNo' },
+  { key: 'planNo', prop: 'planNo', label: '装柜清单号', minWidth: 165, formatter: (row: ContainerBookingResource) => row.planNo || '—' },
+  { key: 'planStatus', label: '状态', width: 110, slotName: 'status' },
+  { key: 'exceptionActive', label: '异常', width: 90, formatter: (row: ContainerBookingResource) => row.exceptionActive ? '异常' : '正常' },
+  { key: 'cabinetNo', label: '柜次号', minWidth: 180, slotName: 'cabinet' },
+  { key: 'destinationClearanceDocumentStatus', label: '清关资料', width: 110, formatter: (row: ContainerBookingResource) => documentStatusText(row.destinationClearanceDocumentStatus) },
+  { key: 'deliveryOrderDocumentStatus', label: 'DO资料', width: 100, formatter: (row: ContainerBookingResource) => documentStatusText(row.deliveryOrderDocumentStatus) },
+  { key: 'pickupCode', label: 'PU码', minWidth: 140, formatter: (row: ContainerBookingResource) => row.pickupCode || '—' },
+  { key: 'oceanBooking', label: '真实订舱', minWidth: 170, slotName: 'oceanBooking' },
+  { key: 'warehouseName', prop: 'warehouseName', label: '装柜仓库', minWidth: 160 },
+  { key: 'channelGroupCode', label: '计划渠道', minWidth: 140, formatter: (row: ContainerBookingResource) => getSmartLoadingChannelGroup(row.channelGroupCode)?.name || '—' },
+  { key: 'channelName', label: '实际渠道', minWidth: 160, formatter: (row: ContainerBookingResource) => row.channelName || '待关联订舱' },
+  { key: 'terminalTruckingCompany', label: '码头车队', width: 190, slotName: 'terminalTruckingCompany' },
+  { key: 'pickupAppointmentAt', label: '预计到仓', width: 210, slotName: 'pickupAppointmentAt' },
+  { key: 'actualPickupAt', label: '实际到仓', width: 165, slotName: 'actualPickupAt' },
+  { key: 'estimatedEmptyReturnAt', label: '预计还柜', width: 165, slotName: 'estimatedEmptyReturnAt' },
+  { key: 'actualEmptyReturnAt', label: '实际还柜', width: 165, slotName: 'actualEmptyReturnAt' },
+  { key: 'billOfLadingNo', prop: 'billOfLadingNo', label: '提单号', minWidth: 150 },
+  { key: 'route', label: '航线', minWidth: 220, slotName: 'route' },
+  { key: 'containerType', prop: 'containerType', label: '柜型', width: 100 },
+  { key: 'capacity', label: '容量上限', minWidth: 150, slotName: 'capacity' },
+  { key: 'vessel', label: '船名/航次', minWidth: 180, slotName: 'vessel' },
+  { key: 'shippingCompanyName', prop: 'shippingCompanyName', label: '船公司', minWidth: 150 },
+  { key: 'loadingAt', label: '装柜时间', minWidth: 160, slotName: 'loadingAt' },
+  { key: 'estimatedSailingAt', label: '预计开船', minWidth: 160, slotName: 'estimatedSailingAt' },
+  { key: 'actualSailingAt', label: '实际开船', minWidth: 160, slotName: 'actualSailingAt' },
+  { key: 'estimatedPortArrivalAt', label: '预计到港', minWidth: 160, slotName: 'estimatedPortArrivalAt' },
+  { key: 'actualPortArrivalAt', label: '实际到港', minWidth: 160, slotName: 'actualPortArrivalAt' },
+]
+const domesticColumnKeys = new Set(['actions', 'containerNo', 'planNo', 'planStatus', 'exceptionActive', 'cabinetNo', 'oceanBooking', 'warehouseName', 'channelGroupCode', 'channelName', 'billOfLadingNo', 'route', 'containerType', 'capacity', 'vessel', 'shippingCompanyName', 'loadingAt', 'estimatedSailingAt'])
+const overseasColumnKeys = new Set(['actions', 'emptyReturnWarning', 'containerNo', 'cabinetNo', 'destinationClearanceDocumentStatus', 'deliveryOrderDocumentStatus', 'pickupCode', 'terminalTruckingCompany', 'pickupAppointmentAt', 'actualPickupAt', 'estimatedEmptyReturnAt', 'actualEmptyReturnAt', 'billOfLadingNo', 'route', 'vessel', 'actualSailingAt', 'estimatedPortArrivalAt', 'actualPortArrivalAt'])
+const columns = computed(() => allColumns
+  .filter((column) => (isDomestic.value ? domesticColumnKeys : overseasColumnKeys).has(String(column.key)))
+  // 国内同时展示查看、运输信息、装柜流程和更多菜单，须为四个入口预留空间。
+  .map((column) => isDomestic.value && column.key === 'actions' ? { ...column, width: 290 } : column))
+const drayageHistoryColumns: DataTableColumn[] = [
+  { key: 'action', label: '动作', width: 130, formatter: (row: TerminalDrayageHistory) => drayageActionText(row.action) },
+  { key: 'status', label: '状态变化', minWidth: 180, formatter: (row: TerminalDrayageHistory) => `${drayageStatusText(row.fromStatus)} → ${drayageStatusText(row.toStatus)}` },
+  { key: 'version', label: '版本', width: 100, formatter: (row: TerminalDrayageHistory) => `${row.fromVersion} → ${row.toVersion}` },
+  { key: 'operatorName', label: '操作人', width: 130, formatter: (row: TerminalDrayageHistory) => row.operatorName || '—' },
+  { key: 'createdAt', label: '操作时间', width: 170, formatter: (row: TerminalDrayageHistory) => formatTime(row.createdAt) },
+  { key: 'reason', label: '原因', minWidth: 200 },
+]
+
+function optional(value: string | null) { return value?.trim() || null }
+function statusText(status: ContainerPlanStatus) { return ({ WAIT_LOADING: '待装柜', EDITING: '预装柜中', LOADING: '拣货中', COMPLETED: '装柜完成' })[status] }
+function documentStatusText(status: ContainerDocumentStatus | null | undefined) { return status ? ({ MISSING: '未上传', UPLOADED: '已上传', COMPLETED: '已完成' })[status] : '—' }
+function formatTime(value: string | null | undefined) { return value?.replace('T', ' ').slice(0, 16) || '—' }
+function drayageFor(containerBookingId: string) { return drayages.value[containerBookingId] }
+function drayageStatusText(status?: string | null) { return ({ WAITING_FOR_ARRIVAL: '待到港', ARRIVED: '已到港', PICKUP_SCHEDULED: '已设置预计到仓', PICKED_UP: '已实际到仓', UNLOADED: '已卸柜', EMPTY_RETURNED: '已还柜' } as Record<string, string>)[status || ''] || status || '—' }
+function drayageActionText(action: TerminalDrayageAction) { return ({ SELECT_FLEET: '选择码头车队', SCHEDULE_PICKUP: '修改预计到仓', RECORD_EMPTY_RETURN: '确认还柜', SEND_PICKUP_EMAIL: '发送提柜邮件' } as Record<TerminalDrayageAction, string>)[action] }
+function hasAction(row: ContainerWorkbenchRow, action: ContainerWorkbenchAction) { return Boolean(row.allowedActions?.includes(action)) }
+function canDrayage(row: ContainerWorkbenchRow, action: TerminalDrayageAction) {
+  const permission = action === 'SELECT_FLEET' || action === 'SEND_PICKUP_EMAIL' ? canFleetEdit.value : action === 'SCHEDULE_PICKUP' ? canPickupAppointmentEdit.value : canEmptyReturnConfirm.value
+  return Boolean(isOverseas.value && permission && hasAction(row, action) && drayageFor(row.id)?.allowedActions.includes(action))
+}
+function drayageWarningText(row: ContainerBookingResource) {
+  const warning = drayageFor(row.id)?.emptyReturnWarning
+  if (!warning || warning.status === 'NOT_APPLICABLE') return '—'
+  if (warning.status === 'RESOLVED') return '已还柜'
+  if (warning.status === 'OVERDUE') return warning.overdueDays > 0 ? `超时 ${warning.overdueDays} 天` : `超时 ${warning.overdueHours} 小时`
+  return '待还柜'
+}
+function drayageWarningType(row: ContainerBookingResource) {
+  const status = drayageFor(row.id)?.emptyReturnWarning.status
+  return status === 'OVERDUE' ? 'danger' : status === 'RESOLVED' ? 'success' : status === 'PENDING' ? 'warning' : 'info'
+}
+function drayageWarningTitle(row: ContainerBookingResource) {
+  const warning = drayageFor(row.id)?.emptyReturnWarning
+  if (!warning) return ''
+  const deadline = warning.deadlineAt ? `还柜截止：${formatTime(warning.deadlineAt)}` : ''
+  return [drayageWarningText(row), deadline].filter(Boolean).join('；')
+}
+function localDateTimeValue() {
+  const now = new Date(Date.now() - new Date().getTimezoneOffset() * 60_000)
+  return now.toISOString().slice(0, 19)
+}
+function containerViewLabel(row: ContainerBookingResource) {
+  const reference = [row.cabinetNo, row.containerNo, row.bookingNo]
+    .find((value) => typeof value === 'string' && value.trim())
+  return reference ? `查看 ${reference}` : '查看货柜详情'
+}
+function replaceForm(source: ContainerBookingResource | null) {
+  Object.assign(form, emptyForm(), source || {})
+  const specification = containerSpecification(form.containerType)
+  if (specification) applyContainerSpecification(form, specification.type)
+  reconcileTruckingSupplier()
+}
+function reconcileTruckingSupplier() {
+  const supplierId = optional(form.terminalTruckingCompanyId)
+  const supplierName = optional(form.terminalTruckingCompany) || unresolvedTruckingSupplierName.value
+  const supplier = supplierId
+    ? truckingCompanies.value.find((item) => item.id === supplierId)
+    : truckingCompanies.value.find((item) => item.name === supplierName)
+  selectedTruckingSupplierId.value = supplier?.id || ''
+  unresolvedTruckingSupplierName.value = supplier ? null : supplierName
+  if (supplier) {
+    form.terminalTruckingCompanyId = supplier.id
+    form.terminalTruckingCompany = supplier.name
+  } else if (!supplierName) {
+    form.terminalTruckingCompanyId = null
+    form.terminalTruckingCompany = null
+  } else {
+    form.terminalTruckingCompanyId = null
+    form.terminalTruckingCompany = supplierName
+  }
+}
+function payload(): ContainerSaveRequest {
+  const selectedWarehouse = warehouses.value.find((warehouse) => String(warehouse.id) === form.warehouseId)
+  const selectedTruckingSupplier = truckingCompanies.value.find((supplier) => supplier.id === selectedTruckingSupplierId.value)
+  return {
+    containerNo: optional(detail.value?.containerNo || null),
+    warehouseId: form.warehouseId,
+    warehouseName: selectedWarehouse?.warehouseName || optional(form.warehouseName),
+    billOfLadingNo: optional(form.billOfLadingNo), vesselName: optional(form.vesselName), voyageNo: optional(form.voyageNo),
+    containerType: form.containerType,
+    shippingCompanyId: optional(form.shippingCompanyId), shippingCompanyName: optional(form.shippingCompanyName),
+    departurePortCode: optional(form.departurePortCode), departurePortName: optional(form.departurePortName),
+    destinationPortCode: optional(form.destinationPortCode), destinationPortName: optional(form.destinationPortName),
+    destinationWarehouseCode: optional(form.destinationWarehouseCode), destinationWarehouseName: optional(form.destinationWarehouseName),
+    capacityCbm: form.capacityCbm, maxWeightKg: form.maxWeightKg,
+    terminalTruckingCompanyId: selectedTruckingSupplier?.id || null,
+    terminalTruckingCompany: selectedTruckingSupplier?.name || null,
+    loadingAt: form.loadingAt, estimatedSailingAt: form.estimatedSailingAt, actualSailingAt: form.actualSailingAt,
+    estimatedPortArrivalAt: form.estimatedPortArrivalAt, actualPortArrivalAt: form.actualPortArrivalAt,
+    estimatedWarehouseArrivalAt: form.estimatedWarehouseArrivalAt, actualWarehouseArrivalAt: form.actualWarehouseArrivalAt,
+  }
+}
+
+function partnerLabel(partner: PlatformPartnerResource) {
+  return `${partner.partnerName}${partner.partnerCode ? `（${partner.partnerCode}）` : ''}`
+}
+function selectTruckingSupplier(supplierId: string) {
+  if (!supplierId && unresolvedTruckingSupplierName.value) return
+  const supplier = truckingCompanies.value.find((item) => item.id === supplierId)
+  selectedTruckingSupplierId.value = supplier?.id || ''
+  unresolvedTruckingSupplierName.value = null
+  form.terminalTruckingCompanyId = supplier?.id || null
+  form.terminalTruckingCompany = supplier?.name || null
+}
+function portLabel(port: PortOption) {
+  return port.name && port.code ? `${port.name}（${port.code}）` : port.name || port.code || '未命名港口'
+}
+function selectShippingCompany(partnerId: string) {
+  if (partnerId.startsWith('name:')) {
+    form.shippingCompanyId = null
+    form.shippingCompanyName = partnerId.slice(5) || null
+    return
+  }
+  const partner = partners.value.find((item) => String(item.id) === partnerId)
+  form.shippingCompanyId = partnerId || null
+  form.shippingCompanyName = partner?.partnerName || null
+}
+function selectPort(direction: 'departure' | 'destination', value: string) {
+  const option = (direction === 'departure' ? departurePorts.value : destinationPorts.value).find((item) => item.value === value)
+  if (direction === 'departure') {
+    form.departurePortCode = option?.code || null
+    form.departurePortName = option?.name || null
+  } else {
+    form.destinationPortCode = option?.code || null
+    form.destinationPortName = option?.name || null
+  }
+}
+function selectDestinationWarehouse(warehouseCode: string) {
+  if (warehouseCode.startsWith('name:')) {
+    form.destinationWarehouseCode = null
+    form.destinationWarehouseName = warehouseCode.slice(5) || null
+    return
+  }
+  const warehouse = destinationWarehouses.value.find((item) => item.warehouseCode === warehouseCode)
+  form.destinationWarehouseCode = warehouseCode || null
+  form.destinationWarehouseName = warehouse?.warehouseName || null
+}
+
+async function loadWarehouses() {
+  if (warehousesLoaded) return
+  if (warehouseOptionsPromise) return warehouseOptionsPromise
+  warehouseOptionsPromise = (async () => {
+    warehouseLoading.value = true; warehouseError.value = null
+    try {
+      const records = await listAllPlatformWarehouses({ status: 'ACTIVE' })
+      warehouses.value = records.filter((warehouse) => warehouse.warehouseType === 'DOMESTIC')
+      destinationWarehouses.value = records.filter((warehouse) => warehouse.warehouseType !== 'DOMESTIC')
+      warehousesLoaded = true
+    }
+    catch (error) { warehouseError.value = getApiErrorDetails(error, '装柜仓库加载失败') }
+    finally { warehouseLoading.value = false }
+  })()
+  try { await warehouseOptionsPromise }
+  finally { warehouseOptionsPromise = null }
+}
+async function loadCustomers() {
+  customersLoading.value = true
+  try {
+    const result = await listPlatformTenants({ page: 1, size: 200, status: 'ACTIVE' })
+    customers.value = result.records.filter((customer) => customer.status === 'ACTIVE')
+  } catch {
+    customers.value = []
+  } finally {
+    customersLoading.value = false
+  }
+}
+async function loadBusinessOptions() {
+  if (partnersLoaded && truckingSuppliersLoaded && oceanBookingsLoaded) return
+  if (businessOptionsPromise) return businessOptionsPromise
+  businessOptionsPromise = (async () => {
+    businessOptionsLoading.value = true
+    businessOptionsError.value = ''
+    const errors: string[] = []
+    const [partnerResult, supplierResult, bookingResult] = await Promise.allSettled([
+      partnersLoaded ? Promise.resolve(partners.value) : loadAllPartners(),
+      loadTruckingSuppliers(),
+      oceanBookingsLoaded ? Promise.resolve(oceanBookings.value) : loadAllOceanBookings(),
+    ])
+    if (partnerResult.status === 'fulfilled') { partners.value = partnerResult.value; partnersLoaded = true }
+    else errors.push(getApiErrorDetails(partnerResult.reason, '船公司与拖车公司加载失败').message)
+    if (supplierResult.status === 'fulfilled') {
+      if (form.id) reconcileTruckingSupplier()
+    }
+    else errors.push(getApiErrorDetails(supplierResult.reason, '拖车供应商加载失败').message)
+    if (bookingResult.status === 'fulfilled') { oceanBookings.value = bookingResult.value; oceanBookingsLoaded = true }
+    else errors.push(getApiErrorDetails(bookingResult.reason, '港口候选加载失败').message)
+    businessOptionsError.value = errors.join('；')
+    businessOptionsLoading.value = false
+  })()
+  try { await businessOptionsPromise }
+  finally { businessOptionsPromise = null }
+}
+async function loadTruckingSuppliers(): Promise<Supplier[]> {
+  if (truckingSuppliersLoaded) return truckingSuppliers.value
+  if (truckingSuppliersPromise) return truckingSuppliersPromise
+  truckingSuppliersPromise = (async () => {
+    const result = await listSuppliers({ page: 1, size: 200, category: 'TRUCKING', truckingScope: 'OVERSEAS', status: 'ACTIVE' })
+    const records = result.records.filter((supplier) => supplier.category === 'TRUCKING' && supplier.truckingScope === 'OVERSEAS' && supplier.status === 'ACTIVE')
+    truckingSuppliers.value = records
+    truckingSuppliersLoaded = true
+    return records
+  })()
+  try { return await truckingSuppliersPromise }
+  finally { truckingSuppliersPromise = null }
+}
+async function searchTerminalFleets(keyword = '') {
+  const sequence = ++terminalFleetSearchSequence
+  terminalFleetLoading.value = true
+  try {
+    const result = await listSuppliers({
+      page: 1, size: 20, category: 'TRUCKING', truckingScope: 'OVERSEAS', status: 'ACTIVE', keyword: keyword.trim() || undefined,
+    })
+    if (sequence !== terminalFleetSearchSequence) return
+    terminalFleetOptions.value = result.records.filter((supplier) => supplier.category === 'TRUCKING' && supplier.truckingScope === 'OVERSEAS' && supplier.status === 'ACTIVE')
+  } catch (error) {
+    if (sequence !== terminalFleetSearchSequence) return
+    terminalFleetOptions.value = []
+    ElMessage.error(getApiErrorDetails(error, '码头车队搜索失败').message)
+  } finally {
+    if (sequence === terminalFleetSearchSequence) terminalFleetLoading.value = false
+  }
+}
+function handleTerminalFleetVisible(open: boolean) {
+  if (open) void searchTerminalFleets()
+  else { terminalFleetSearchSequence++; terminalFleetLoading.value = false }
+}
+async function loadAllPartners() {
+  const firstPage = await listPlatformPartners({ page: 1, size: 200, status: 'ACTIVE' })
+  if (firstPage.pages <= 1) return firstPage.records
+  const remaining = await Promise.all(Array.from({ length: firstPage.pages - 1 }, (_, index) => listPlatformPartners({ page: index + 2, size: 200, status: 'ACTIVE' })))
+  return [firstPage, ...remaining].flatMap((pageResult) => pageResult.records)
+}
+async function loadAllOceanBookings() {
+  const firstPage = await listOceanBookings({ page: 1, size: 200 })
+  if (firstPage.pages <= 1) return firstPage.records
+  const remaining = await Promise.all(Array.from({ length: firstPage.pages - 1 }, (_, index) => listOceanBookings({ page: index + 2, size: 200 })))
+  return [firstPage, ...remaining].flatMap((pageResult) => pageResult.records)
+}
+async function loadSimulationWarehouses() {
+  await loadWarehouses()
+  if (warehouseError.value) throw warehouseError.value
+  return warehouses.value
+}
+function openLink(source: object) {
+  const row = source as ContainerBookingResource
+  linkTarget.value = row
+  linkOpen.value = true
+}
+function replaceDrayage(value: TerminalDrayageView) {
+  drayages.value = { ...drayages.value, [value.containerBookingId]: value }
+}
+async function refreshDrayage(containerBookingId: string) {
+  const value = await getTerminalDrayage(containerBookingId)
+  replaceDrayage(value)
+  return value
+}
+async function selectRowFleet(source: object, supplierIdValue: unknown) {
+  const row = source as ContainerBookingResource
+  const current = drayageFor(row.id)
+  const supplierId = String(supplierIdValue || '')
+  const supplier = terminalFleetOptions.value.find((item) => item.id === supplierId)
+    || truckingCompanies.value.find((item) => item.id === supplierId)
+  if (!current || !supplier || !canDrayage(row, 'SELECT_FLEET') || drayageSavingIds.value.includes(row.id)) return
+  drayageSavingIds.value = [...drayageSavingIds.value, row.id]
+  try {
+    replaceDrayage(await selectTerminalDrayageFleet(row.id, { expectedVersion: current.version, fleetSupplierId: supplier.id, fleetSupplierName: supplier.name }))
+    ElMessage.success(current.fleetSupplierId && current.fleetSupplierId !== supplier.id
+      ? '码头车队已更新，新车队提柜邮件已入队；原车队已下发过邮件时同时加入取消邮件'
+      : '码头车队已更新')
+    await loadRows()
+  } catch (error) {
+    const details = getApiErrorDetails(error, '码头车队更新失败')
+    if (details.code === 'A0409') {
+      try { await refreshDrayage(row.id) } catch { /* 保留原始冲突证据 */ }
+      ElMessage.warning('运输信息已被其他人修改，已刷新当前柜最新状态')
+    } else ElMessage.error(details.message)
+  } finally { drayageSavingIds.value = drayageSavingIds.value.filter((id) => id !== row.id) }
+}
+function openDrayageAction(row: ContainerBookingResource, action: Exclude<TerminalDrayageAction, 'SELECT_FLEET' | 'SEND_PICKUP_EMAIL'>) {
+  if (!canDrayage(row, action)) return
+  drayageTarget.value = row; drayageAction.value = action; drayageActionAt.value = localDateTimeValue(); drayageReason.value = ''
+  drayageActionError.value = null; drayageActionOpen.value = true
+}
+async function saveDrayageAction() {
+  const row = drayageTarget.value
+  const current = row ? drayageFor(row.id) : null
+  if (!row || !current || !drayageActionAt.value || !canDrayage(row, drayageAction.value) || drayageActionSaving.value) return
+  drayageActionSaving.value = true; drayageActionError.value = null
+  try {
+    const reason = drayageReason.value.trim() || undefined
+    const next = await recordTerminalDrayageEmptyReturn(row.id, { expectedVersion: current.version, actualAt: drayageActionAt.value, remark: reason })
+    replaceDrayage(next); drayageActionOpen.value = false
+    ElMessage.success(`${drayageActionText(drayageAction.value)}成功`)
+    await loadRows()
+  } catch (error) {
+    const details = getApiErrorDetails(error, `${drayageActionText(drayageAction.value)}失败`)
+    if (details.code === 'A0409') {
+      try { await refreshDrayage(row.id) } catch { /* 保留原始冲突证据 */ }
+      drayageActionError.value = { ...details, message: '运输信息已被其他人修改，已刷新最新状态；请重新确认后提交' }
+    } else drayageActionError.value = details
+  } finally { drayageActionSaving.value = false }
+}
+async function saveExpectedArrival(row: ContainerBookingResource, value: string | null) {
+  const current = arrivalTimes.value[row.id]
+  if (!value || !current || current.version < 0 || arrivalSavingIds.value.includes(row.id)) return
+  arrivalSavingIds.value.push(row.id)
+  try {
+    const updated = await updateContainerExpectedArrival(row.id, {
+      estimatedWarehouseArrivalAt: value,
+      expectedVersion: current.version,
+    })
+    arrivalTimes.value = { ...arrivalTimes.value, [row.id]: updated }
+    arrivalInputs.value = { ...arrivalInputs.value, [row.id]: updated.estimatedWarehouseArrivalAt || '' }
+    ElMessage.success('预计到仓时间已同步整柜，后续入库计划将自动带出')
+  } catch (error) {
+    ElMessage.error(getApiErrorDetails(error, '预计到仓时间保存失败').message)
+    const latest = await listContainerArrivalTimes([row.id]).catch(() => [])
+    if (latest[0]) {
+      arrivalTimes.value = { ...arrivalTimes.value, [row.id]: latest[0] }
+      arrivalInputs.value = { ...arrivalInputs.value, [row.id]: latest[0].estimatedWarehouseArrivalAt || '' }
+    }
+  } finally { arrivalSavingIds.value = arrivalSavingIds.value.filter((id) => id !== row.id) }
+}
+async function openDrayageHistory(row: ContainerBookingResource) {
+  drayageTarget.value = row; drayageHistory.value = []; drayageHistoryError.value = null; drayageHistoryOpen.value = true; drayageHistoryLoading.value = true
+  try {
+    const [current, history] = await Promise.all([getTerminalDrayage(row.id), getTerminalDrayageHistory(row.id)])
+    if (drayageTarget.value?.id !== row.id) return
+    replaceDrayage(current); drayageHistory.value = history
+  } catch (error) { if (drayageTarget.value?.id === row.id) drayageHistoryError.value = getApiErrorDetails(error, '码头拖车记录加载失败') }
+  finally { if (drayageTarget.value?.id === row.id) drayageHistoryLoading.value = false }
+}
+async function loadRows() {
+  const sequence = ++listSequence
+  loading.value = true; loadError.value = null
+  const [from, to] = applied.value.sailingRange || []
+  try {
+    const result = await listContainers({
+      page: page.value, size: pageSize.value, customerId: applied.value.customerId || undefined, keyword: applied.value.keyword.trim() || undefined,
+      containerType: applied.value.containerType || undefined,
+      status: applied.value.status, estimatedSailingFrom: from ? `${from}T00:00:00` : undefined,
+      estimatedSailingTo: to ? `${to}T23:59:59` : undefined, scope: scope.value,
+    }, props.workbench)
+    if (sequence !== listSequence) return
+    rows.value = result.records as ContainerWorkbenchRow[]; total.value = result.total
+    drayages.value = Object.fromEntries(rows.value.flatMap((row) => row.terminalDrayage ? [[row.id, row.terminalDrayage as TerminalDrayageView]] : []))
+    const arrivalValues = isOverseas.value ? await listContainerArrivalTimes(rows.value.map((row) => row.id)) : []
+    if (sequence !== listSequence) return
+    arrivalTimes.value = Object.fromEntries(arrivalValues.map((item) => [item.sourceContainerBookingId, item]))
+    arrivalInputs.value = Object.fromEntries(arrivalValues.map((item) => [item.sourceContainerBookingId, item.estimatedWarehouseArrivalAt || '']))
+  } catch (error) {
+    if (sequence !== listSequence) return
+    rows.value = []; total.value = 0; loadError.value = getApiErrorDetails(error, '货柜列表加载失败，请稍后重试')
+  } finally { if (sequence === listSequence) loading.value = false }
+}
+function search() { applied.value = { ...filters.value, sailingRange: [...filters.value.sailingRange] }; if (page.value === 1) void loadRows(); else page.value = 1 }
+function openDetail(source: object) {
+  const row = source as ContainerBookingResource
+  void router.push({ name: props.workbench === 'DOMESTIC' ? 'domestic-container-detail' : 'overseas-container-detail', params: { containerId: row.id } })
+}
+function handleMoreAction(command: string, source: object) {
+  const row = source as ContainerBookingResource
+  if (command === 'link') { void openLink(row); return }
+  if (command === 'overview') { openDetail(row); return }
+  if (command === 'email-history') { void openEmailHistory(row); return }
+  if (command === 'drayage-history') { void openDrayageHistory(row); return }
+  if (command.startsWith('drayage:')) { openDrayageAction(row, command.slice('drayage:'.length) as Exclude<TerminalDrayageAction, 'SELECT_FLEET' | 'SEND_PICKUP_EMAIL'>); return }
+  if (command === 'documents' && isOverseas.value && hasAction(row as ContainerWorkbenchRow, 'MANAGE_DESTINATION_DOCUMENTS')) void router.push({ name: 'overseas-container-detail', params: { containerId: row.id }, query: { action: command } })
+}
+async function openEdit(source: object) {
+  const row = source as ContainerBookingResource
+  editorError.value = null
+  try {
+    const [latest] = await Promise.all([getContainer(row.id, props.workbench), loadWarehouses(), loadBusinessOptions()])
+    if (!isDomestic.value || !hasAction(latest, 'EDIT_CONTAINER')) return
+    detail.value = latest
+    replaceForm(latest)
+    editorOpen.value = true
+  }
+  catch (error) { ElMessage.error(getApiErrorDetails(error, '货柜详情加载失败').message) }
+}
+async function save() {
+  if (unresolvedTruckingSupplierName.value) {
+    editorError.value = { message: '原拖车供应商已不可用，请重新选择合作中的拖车供应商' }
+    return
+  }
+  if (!(await formRef.value?.validate().catch(() => false))) return
+  saving.value = true
+  editorError.value = null
+  try {
+    await updateContainer(form.id, form.version, payload())
+    ElMessage.success('货柜已更新'); editorOpen.value = false; await loadRows()
+  } catch (error) {
+    const details = getApiErrorDetails(error, '保存失败')
+    if (details.code === 'A0409' && form.id) {
+      const submitted = { ...form }
+      try {
+        const latest = await getContainer(form.id, props.workbench)
+        detail.value = latest
+        replaceForm(latest)
+        Object.assign(form, submitted, { id: latest.id, version: latest.version })
+        editorError.value = { ...details, message: '数据已被其他人修改，已刷新最新版本并保留本次输入，请重新确认后提交' }
+        ElMessage.warning(editorError.value.message)
+      } catch (refreshError) {
+        editorError.value = getApiErrorDetails(refreshError, '数据已被其他人修改，且最新数据刷新失败，请稍后重试')
+        ElMessage.error(editorError.value.message)
+      }
+    } else {
+      editorError.value = details
+      ElMessage.error(details.message)
+    }
+  } finally { saving.value = false }
+}
+function goContainerProcess(source: object) {
+  const row = source as ContainerBookingResource
+  if (row.planStatus === 'EDITING') {
+    void router.push({ name: 'smart-loading-workbench', params: { containerId: row.id } })
+    return
+  }
+  void router.push({
+    name: row.planStatus === 'LOADING' ? 'loading-plans' : 'domestic-container-detail',
+    params: row.planStatus === 'COMPLETED' ? { containerId: row.id } : undefined,
+    query: row.planStatus === 'COMPLETED' ? { tab: 'loading-list' } : { planId: row.planId || undefined, warehouseId: row.warehouseId },
+  })
+}
+
+watch([page, pageSize], ([nextPage, nextSize], [previousPage, previousSize]) => {
+  if (nextPage !== previousPage || nextSize !== previousSize) void loadRows()
+})
+watch(scope, () => { if (page.value === 1) void loadRows(); else page.value = 1 })
+onMounted(async () => { await Promise.all([loadCustomers(), loadRows()]) })
+</script>
+
+<template>
+  <AdminPage class="admin-density" as="div">
+    <section class="container-page">
+      <ListPageLayout :ariaLabel="isDomestic ? '送柜报关工作台' : '清关提柜工作台'">
+      <template #toolbar>
+        <div class="container-query-panel">
+          <div class="container-scope-tabs density-tabs" role="tablist" aria-label="货柜完结状态">
+            <button type="button" role="tab" aria-controls="container-workbench-results" :aria-selected="scope === 'ACTIVE'" :tabindex="scope === 'ACTIVE' ? 0 : -1" :class="['container-scope-tab', { active: scope === 'ACTIVE' }]" @click="scope = 'ACTIVE'">未完结</button>
+            <button type="button" role="tab" aria-controls="container-workbench-results" :aria-selected="scope === 'HISTORY'" :tabindex="scope === 'HISTORY' ? 0 : -1" :class="['container-scope-tab', { active: scope === 'HISTORY' }]" @click="scope = 'HISTORY'">已完结</button>
+          </div>
+          <QueryToolbar v-model="filters" class="container-query-toolbar" ariaLabel="货柜筛选" :fields="queryFields" preference-key="container-loading-query" @search="search" />
+        </div>
+      </template>
+      <template v-if="loadError" #state>
+        <LoadErrorState title="货柜列表加载失败" :message="loadError.message" :loading="loading" @retry="loadRows"><template #details><ApiErrorMeta :details="loadError" /></template></LoadErrorState>
+      </template>
+        <section v-if="!loadError" id="container-workbench-results" class="surface-panel table-panel">
+          <DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :total="total" :loading="loading" stripe preference-key="container-loading-table" empty-text="暂无货柜">
+            <template #toolbar-actions><ContainerSimulationCreate dense v-if="isDomestic && canCreate" :load-warehouse-options="loadSimulationWarehouses" @created="loadRows" /></template>
+            <template #actions="{ row }"><div class="row-actions density-actions"><el-button class="density-action" v-if="canView" size="small" type="primary" plain :aria-label="containerViewLabel(row as ContainerBookingResource)" @click="openDetail(row)">查看</el-button><template v-if="isDomestic"><el-button class="density-action" v-if="canEdit && hasAction(row as ContainerWorkbenchRow, 'EDIT_CONTAINER')" size="small" @click="openEdit(row)">编辑</el-button><el-button data-tone="primary" class="density-action" v-if="row.planStatus === 'EDITING' && canSmartLoading" size="small" type="primary" @click="goContainerProcess(row)">装柜</el-button><el-button class="density-action" v-else-if="row.planStatus === 'LOADING' && canViewPreload" size="small" type="primary" plain @click="goContainerProcess(row)">预装清单</el-button><el-button class="density-action" v-else-if="row.planStatus === 'COMPLETED' && canViewLoadingList" size="small" type="primary" plain @click="goContainerProcess(row)">装柜清单</el-button></template><el-button data-tone="primary" class="density-action" v-if="canDrayage(row as ContainerWorkbenchRow, 'RECORD_EMPTY_RETURN')" size="small" type="primary" @click="openDrayageAction(row as ContainerBookingResource, 'RECORD_EMPTY_RETURN')">确认还柜</el-button><el-button data-tone="primary" class="density-action" v-if="canDrayage(row as ContainerWorkbenchRow, 'SEND_PICKUP_EMAIL')" size="small" type="primary" :loading="drayageSavingIds.includes(row.id)" @click="sendPickupEmail(row as ContainerWorkbenchRow)">发送邮件</el-button><el-dropdown v-if="canView" trigger="click" @command="handleMoreAction($event, row)"><el-button class="density-action" size="small" plain aria-label="更多货柜操作" title="更多货柜操作"><MoreHorizontal :size="16" /></el-button><template #dropdown><el-dropdown-menu><el-dropdown-item command="overview">轨迹与日志</el-dropdown-item><template v-if="isOverseas"><el-dropdown-item command="email-history">邮件记录</el-dropdown-item><el-dropdown-item command="drayage-history">码头拖车记录</el-dropdown-item><el-dropdown-item v-if="canOverseasDocumentEdit && hasAction(row as ContainerWorkbenchRow, 'MANAGE_DESTINATION_DOCUMENTS')" command="documents">清关 / DO / PU</el-dropdown-item></template><el-dropdown-item v-if="isDomestic && canEdit && hasAction(row as ContainerWorkbenchRow, 'EDIT_CONTAINER') && row.sourceType === 'SIMULATION' && !row.oceanBookingId" command="link">关联已放舱订舱</el-dropdown-item></el-dropdown-menu></template></el-dropdown></div></template>
+            <template #emptyReturnWarning="{ row }"><el-tag :type="drayageWarningType(row as ContainerBookingResource)" effect="light" :title="drayageWarningTitle(row as ContainerBookingResource)">{{ drayageWarningText(row as ContainerBookingResource) }}</el-tag></template>
+            <template #cabinet="{ row }"><strong>{{ row.cabinetNo }}</strong><small>系统生成</small></template>
+            <template #oceanBooking="{ row }"><span v-if="row.oceanBookingId"><strong>{{ row.billOfLadingNo || '已关联订舱' }}</strong><small>{{ row.containerNo ? `集装箱号：${row.containerNo}` : '集装箱号：待补录' }}</small></span><span v-else>未关联</span></template>
+            <template #containerNo="{ row }">{{ row.containerNo || '待补录' }}</template>
+            <template #terminalTruckingCompany="{ row }"><el-select class="fleet-select" :model-value="drayageFor(row.id)?.fleetSupplierId || ''" filterable remote reserve-keyword remote-show-suffix placeholder="输入车队名称或联系人搜索" :remote-method="searchTerminalFleets" :loading="terminalFleetLoading || drayageSavingIds.includes(row.id)" :disabled="!canDrayage(row as ContainerBookingResource, 'SELECT_FLEET') || drayageSavingIds.includes(row.id)" no-data-text="未找到合作中的码头车队" @visible-change="handleTerminalFleetVisible" @update:model-value="selectRowFleet(row, $event)"><el-option v-if="drayageFor(row.id)?.fleetSupplierName && !terminalFleetOptions.some((item) => item.id === drayageFor(row.id)?.fleetSupplierId)" :label="drayageFor(row.id)?.fleetSupplierName || '原码头车队'" :value="drayageFor(row.id)?.fleetSupplierId || ''" disabled /><el-option v-for="supplier in terminalFleetOptions" :key="supplier.id" :label="supplier.name" :value="supplier.id" /></el-select></template>
+            <template #pickupAppointmentAt="{ row }"><div class="arrival-time-cell"><el-date-picker v-model="arrivalInputs[row.id]" class="arrival-time-picker" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" format="YYYY-MM-DD HH:mm" placeholder="选择预计到仓" :disabled="!canExpectedArrivalEdit || !arrivalTimes[row.id] || arrivalTimes[row.id].version < 0 || arrivalSavingIds.includes(row.id)" @change="saveExpectedArrival(row as ContainerBookingResource, $event as string | null)" /></div></template>
+            <template #actualPickupAt="{ row }">{{ formatTime(arrivalTimes[row.id]?.actualWarehouseArrivalAt) }}</template>
+            <template #estimatedEmptyReturnAt="{ row }">{{ formatTime(drayageFor(row.id)?.estimatedEmptyReturnAt) }}</template>
+            <template #actualEmptyReturnAt="{ row }">{{ formatTime(drayageFor(row.id)?.actualEmptyReturnAt) }}</template>
+            <template #status="{ row }"><el-tag :type="row.planStatus === 'COMPLETED' ? 'success' : row.planStatus === 'LOADING' ? 'warning' : 'info'">{{ statusText(row.planStatus) }}</el-tag></template>
+            <template #route="{ row }">{{ row.departurePortName || row.departurePortCode || '—' }} → {{ row.destinationPortName || row.destinationPortCode || '—' }}</template>
+            <template #capacity="{ row }">{{ row.capacityCbm ? `${row.capacityCbm} m³` : '—' }} / {{ row.maxWeightKg ? `${row.maxWeightKg} kg` : '—' }}</template>
+            <template #vessel="{ row }">{{ [row.vesselName, row.voyageNo].filter(Boolean).join(' / ') || '—' }}</template>
+            <template #loadingAt="{ row }">{{ formatTime(row.loadingAt) }}</template>
+            <template #estimatedSailingAt="{ row }">{{ formatTime(row.estimatedSailingAt) }}</template>
+            <template #actualSailingAt="{ row }">{{ formatTime(row.actualFacts?.actualSailingAt) }}</template>
+            <template #estimatedPortArrivalAt="{ row }">{{ formatTime(row.estimatedPortArrivalAt) }}</template>
+            <template #actualPortArrivalAt="{ row }">{{ formatTime(row.actualFacts?.actualPortArrivalAt) }}</template>
+          </DataTable>
+        </section>
+      </ListPageLayout>
+
+    <OceanBookingLinkDialog v-model="linkOpen" :container="linkTarget" @linked="loadRows" />
+
+    <AppDialog v-model="editorOpen" class="container-editor-dialog admin-density-dialog" :title="editorTitle" width="min(820px, calc(100vw - 28px))" :confirm-loading="saving" :confirm-disabled="Boolean(warehouseError)" confirm-text="确定" cancel-text="关闭" @confirm="save">
+      <LoadErrorState v-if="editorError" title="货柜保存失败" :message="editorError.message" compact :retry-text="form.id ? '刷新最新数据' : '重试保存'" @retry="form.id ? openEdit({ id: form.id }) : save()"><template #details><ApiErrorMeta :details="editorError" /></template></LoadErrorState>
+      <LoadErrorState v-if="warehouseError" title="装柜仓库加载失败" :message="warehouseError.message" compact @retry="loadWarehouses"><template #details><ApiErrorMeta :details="warehouseError" /></template></LoadErrorState>
+      <el-alert v-if="businessOptionsError" type="warning" :closable="false" show-icon :title="businessOptionsError"><el-button link type="warning" :loading="businessOptionsLoading" @click="loadBusinessOptions">重新加载业务选项</el-button></el-alert>
+      <el-form v-if="!warehouseError" ref="formRef" :model="form" :rules="rules" label-position="top" class="form-grid density-form">
+        <el-form-item label="真实集装箱号"><el-input :model-value="form.containerNo || '待补录'" disabled /><small>货柜基础资料不提供柜号写入；请在拖车提柜或预装详情中补录，后续纠错也在预装详情完成。</small></el-form-item>
+        <el-form-item label="柜次号"><el-input :model-value="form.cabinetNo" disabled placeholder="系统生成" /></el-form-item>
+        <el-form-item label="装柜仓库" prop="warehouseId"><el-select v-model="form.warehouseId" filterable placeholder="请选择装柜仓库" :loading="warehouseLoading" loading-text="仓库加载中" no-data-text="暂无可用国内仓库"><el-option v-for="warehouse in warehouses" :key="String(warehouse.id)" :label="`${warehouse.warehouseName}（${warehouse.warehouseCode}）`" :value="String(warehouse.id)" /></el-select></el-form-item>
+        <el-form-item label="提单号"><el-input v-model="form.billOfLadingNo" maxlength="128" placeholder="请输入提单号（可选）" /></el-form-item>
+        <el-form-item label="船名"><el-input v-model="form.vesselName" maxlength="128" placeholder="请输入船名" /></el-form-item>
+        <el-form-item label="航次"><el-input v-model="form.voyageNo" maxlength="64" placeholder="请输入航次" /></el-form-item>
+        <el-form-item label="箱型（货柜类型）" prop="containerType"><el-select :model-value="form.containerType" placeholder="请选择箱型" @update:model-value="applyContainerSpecification(form, String($event || ''))"><el-option v-for="item in CONTAINER_SPECIFICATIONS" :key="item.type" :label="item.type" :value="item.type" /></el-select></el-form-item>
+        <el-form-item label="船公司"><el-select :model-value="shippingCompanyValue" filterable clearable placeholder="请选择船公司" :loading="businessOptionsLoading" loading-text="船公司加载中" no-data-text="暂无可用船公司" @update:model-value="selectShippingCompany(String($event || ''))"><el-option v-if="shippingCompanyValue && !shippingCompanies.some((partner) => String(partner.id) === shippingCompanyValue)" :label="form.shippingCompanyName || '原船公司'" :value="shippingCompanyValue" /><el-option v-for="partner in shippingCompanies" :key="String(partner.id)" :label="partnerLabel(partner)" :value="String(partner.id)" /></el-select></el-form-item>
+        <el-form-item label="起运港"><el-select :model-value="departurePortValue" filterable clearable placeholder="请选择起运港" :loading="businessOptionsLoading" loading-text="港口加载中" no-data-text="暂无订舱港口数据" @update:model-value="selectPort('departure', String($event || ''))"><el-option v-for="port in departurePorts" :key="port.value" :label="portLabel(port)" :value="port.value" /></el-select></el-form-item>
+        <el-form-item label="目的港"><el-select :model-value="destinationPortValue" filterable clearable placeholder="请选择目的港" :loading="businessOptionsLoading" loading-text="港口加载中" no-data-text="暂无订舱港口数据" @update:model-value="selectPort('destination', String($event || ''))"><el-option v-for="port in destinationPorts" :key="port.value" :label="portLabel(port)" :value="port.value" /></el-select></el-form-item>
+        <el-form-item label="目的仓"><el-select :model-value="destinationWarehouseValue" filterable clearable placeholder="请选择目的仓" :loading="warehouseLoading" loading-text="目的仓加载中" no-data-text="暂无可用海外/FBA仓库" @update:model-value="selectDestinationWarehouse(String($event || ''))"><el-option v-if="destinationWarehouseValue && !destinationWarehouses.some((warehouse) => warehouse.warehouseCode === destinationWarehouseValue)" :label="form.destinationWarehouseName || form.destinationWarehouseCode || '原目的仓'" :value="destinationWarehouseValue" /><el-option v-for="warehouse in destinationWarehouses" :key="String(warehouse.id)" :label="`${warehouse.warehouseName}（${warehouse.warehouseCode}）`" :value="warehouse.warehouseCode" /></el-select></el-form-item>
+        <el-form-item label="货柜容量（m³）"><el-input :model-value="form.capacityCbm == null ? '—' : `${form.capacityCbm} m³`" disabled /></el-form-item>
+        <el-form-item label="重量上限（kg）"><el-input :model-value="form.maxWeightKg == null ? '—' : `${form.maxWeightKg} kg`" disabled /></el-form-item>
+        <el-form-item label="拖车公司" prop="terminalTruckingCompany"><el-select :model-value="selectedTruckingSupplierId" filterable clearable placeholder="请选择拖车供应商" :loading="businessOptionsLoading" loading-text="拖车供应商加载中" no-data-text="暂无可用拖车供应商" @update:model-value="selectTruckingSupplier(String($event || ''))"><el-option v-if="form.terminalTruckingCompany && !selectedTruckingSupplierId" :label="`${form.terminalTruckingCompany}（需重新选择）`" value="" disabled /><el-option v-for="supplier in truckingCompanies" :key="supplier.id" :label="supplier.name" :value="supplier.id" /></el-select></el-form-item>
+        <el-form-item label="计划装柜时间"><el-date-picker v-model="form.loadingAt" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" placeholder="请选择计划装柜时间" /></el-form-item>
+        <el-form-item label="预计开船时间"><el-date-picker v-model="form.estimatedSailingAt" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" placeholder="请选择预计开船时间" /></el-form-item>
+        <el-form-item label="预计到港时间"><el-date-picker v-model="form.estimatedPortArrivalAt" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" placeholder="请选择预计到港时间" /></el-form-item>
+      </el-form>
+    </AppDialog>
+
+    <AppDialog class="admin-density-dialog" v-model="drayageActionOpen" :title="drayageActionText(drayageAction)" width="min(520px, calc(100vw - 28px))" :confirm-text="drayageActionText(drayageAction)" cancel-text="取消" :confirm-loading="drayageActionSaving" :confirm-disabled="!drayageActionAt" @confirm="saveDrayageAction">
+      <el-form class="density-form" label-position="top"><el-form-item label="实际还柜时间" required><el-date-picker v-model="drayageActionAt" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" placeholder="请选择时间" /></el-form-item><el-form-item label="原因/备注"><el-input v-model="drayageReason" type="textarea" :rows="3" maxlength="500" show-word-limit placeholder="选填" /></el-form-item></el-form>
+      <LoadErrorState v-if="drayageActionError" compact :title="`${drayageActionText(drayageAction)}失败`" :message="drayageActionError.message" :show-retry="false"><template #details><ApiErrorMeta :details="drayageActionError" /></template></LoadErrorState>
+    </AppDialog>
+
+    <AppDialog class="admin-density-dialog" v-model="emailHistoryOpen" title="车队邮件记录" width="min(1100px, calc(100vw - 28px))" :show-footer="false">
+      <p>集装箱号：{{ emailTarget?.containerNo || '—' }} · 显示最近 100 封邮件</p>
+      <el-alert v-if="!emailsLoading && !emailsError && !emailDeliveryEnabled" title="发信尚未启用，邮件保留在待发送队列中" type="warning" :closable="false" />
+      <LoadErrorState v-if="emailsError" compact title="邮件记录加载失败" :message="emailsError.message" @retry="emailTarget && openEmailHistory(emailTarget)"><template #details><ApiErrorMeta :details="emailsError" /></template></LoadErrorState>
+      <DataTable v-else :data="emails" :columns="emailColumns" :loading="emailsLoading" column-settings-mode="hide" empty-text="暂无邮件记录">
+        <template #toolbar-actions><el-button :loading="emailsLoading" @click="emailTarget && openEmailHistory(emailTarget)">刷新记录</el-button></template>
+        <template #emailActions="{ row }"><el-button class="density-action" v-if="canFleetEdit && row.status === 'FAILED'" size="small" :loading="retryingEmail === row.id" :disabled="Boolean(retryingEmail)" @click="retryEmail(row as TerminalDrayageEmail)">重试</el-button><span v-else>—</span></template>
+        <template #emailContent="{ row }"><details><summary>{{ row.subject }}</summary><p style="white-space: pre-wrap">{{ row.body }}</p></details></template>
+      </DataTable>
+    </AppDialog>
+    <AppDialog class="admin-density-dialog" v-model="drayageHistoryOpen" title="码头拖车记录" width="min(980px, calc(100vw - 28px))" :show-footer="false">
+      <LoadErrorState v-if="drayageHistoryError" compact title="码头拖车记录加载失败" :message="drayageHistoryError.message" :loading="drayageHistoryLoading" @retry="drayageTarget && openDrayageHistory(drayageTarget)"><template #details><ApiErrorMeta :details="drayageHistoryError" /></template></LoadErrorState>
+      <template v-else><el-descriptions v-if="drayageTarget && drayageFor(drayageTarget.id)" :column="4" border class="drayage-summary"><el-descriptions-item label="当前状态">{{ drayageStatusText(drayageFor(drayageTarget.id)?.status) }}</el-descriptions-item><el-descriptions-item label="码头车队">{{ drayageFor(drayageTarget.id)?.fleetSupplierName || '—' }}</el-descriptions-item><el-descriptions-item label="预计还柜">{{ formatTime(drayageFor(drayageTarget.id)?.estimatedEmptyReturnAt) }}</el-descriptions-item><el-descriptions-item label="实际还柜">{{ formatTime(drayageFor(drayageTarget.id)?.actualEmptyReturnAt) }}</el-descriptions-item></el-descriptions><DataTable :data="drayageHistory" :columns="drayageHistoryColumns" :loading="drayageHistoryLoading" stripe column-settings-mode="hide" empty-text="暂无码头拖车操作记录" /></template>
+    </AppDialog>
+    </section>
+  </AdminPage>
+</template>
+
+<style scoped>
+.container-page { display: grid; gap: var(--admin-space-5); min-width: 0; }.container-page small { display: block; margin-top: var(--admin-space-1); color: var(--cc-muted); }.container-query-panel { overflow: hidden; border: 1px solid var(--cc-border); border-radius: var(--admin-radius); background: var(--admin-surface); }.container-scope-tabs { display: flex; max-width: 100%; overflow-x: auto; margin-bottom: 0; border-bottom: 1px solid #e5e7eb; scrollbar-width: thin; }.container-query-toolbar { border: 0; }.row-actions { flex-wrap: nowrap; white-space: nowrap; }.row-actions :deep(.el-button + .el-button) { margin-left: 0; }.form-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 0 var(--admin-space-5); }.form-grid :deep(.el-select),.form-grid :deep(.el-date-editor),.form-grid :deep(.el-input-number),.simulation-form :deep(.el-select),.simulation-form :deep(.el-input-number),.fleet-select { width: 100%; }.arrival-time-cell { display: flex; align-items: center; width: 100%; min-width: 0; padding-right: var(--admin-space-1); box-sizing: border-box; }.arrival-time-picker { width: 200px !important; max-width: 100%; min-width: 0; box-sizing: border-box; }.details :deep(.el-descriptions__label) { width: 120px; }.drayage-load-alert { margin-bottom: var(--admin-space-5); }.drayage-summary { margin-bottom: var(--admin-space-5); }
+.container-query-panel { width: 100%; max-width: 100%; min-width: 0; box-sizing: border-box; }
+.container-query-toolbar :deep(.query-toolbar__tail) { width: 100%; flex: 0 0 100%; }
+.container-page .table-panel { width: 100%; max-width: 100%; min-width: 0; }
+@media(max-width:720px){.details :deep(.el-descriptions__body table),.details :deep(tbody),.details :deep(tr),.details :deep(td){display:block;width:100%!important}.row-actions { min-width: 180px; }}
+@media(max-width:720px){.form-grid{grid-template-columns:1fr}}
+</style>
diff --git a/src/modules/container-loading/pages/DomesticContainerDetailView.vue b/src/modules/container-loading/pages/DomesticContainerDetailView.vue
new file mode 100644
index 00000000..474cc2b7
--- /dev/null
+++ b/src/modules/container-loading/pages/DomesticContainerDetailView.vue
@@ -0,0 +1,5 @@
+<script setup lang="ts">
+import ContainerDetailView from './ContainerDetailView.vue'
+</script>
+
+<template><ContainerDetailView workbench="DOMESTIC" /></template>
diff --git a/src/modules/container-loading/pages/DomesticContainersView.vue b/src/modules/container-loading/pages/DomesticContainersView.vue
new file mode 100644
index 00000000..e0529579
--- /dev/null
+++ b/src/modules/container-loading/pages/DomesticContainersView.vue
@@ -0,0 +1,5 @@
+<script setup lang="ts">
+import ContainersView from './ContainersView.vue'
+</script>
+
+<template><ContainersView workbench="DOMESTIC" /></template>
diff --git a/src/modules/container-loading/pages/GlobalSmartLoadingView.test.ts b/src/modules/container-loading/pages/GlobalSmartLoadingView.test.ts
new file mode 100644
index 00000000..6985904f
--- /dev/null
+++ b/src/modules/container-loading/pages/GlobalSmartLoadingView.test.ts
@@ -0,0 +1,1079 @@
+import ElementPlus, { ElCheckboxButton, ElInputNumber, ElMessage, ElMessageBox } from 'element-plus'
+import { AxiosError } from 'axios'
+import { createPinia, setActivePinia } from 'pinia'
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import QueryToolbar from '@/shared/components/QueryToolbar.vue'
+import GlobalSmartLoadingView from './GlobalSmartLoadingView.vue'
+import type { ContainerBookingResource } from '../types'
+import {
+  assignPendingReviewSmartLoadingOrder,
+  assignSmartLoadingGroup,
+  assignSmartLoadingItem,
+  assignSmartLoadingPallet,
+  getSmartLoadingPlanByBooking,
+  listContainers,
+  listSmartLoadingCandidates,
+  listSmartLoadingWorkbenchContainers,
+  recommendSmartLoading,
+  adjustSmartLoadingItem,
+  removeAllUnpickedSmartLoadingItems,
+  removeSmartLoadingGroup,
+  removeSmartLoadingItem,
+  removeSmartLoadingPallet,
+} from '../api/platformContainerLoading'
+
+const { routerPush } = vi.hoisted(() => ({ routerPush: vi.fn() }))
+
+vi.mock('vue-router', () => ({
+  useRouter: () => ({ push: routerPush }),
+}))
+
+vi.mock('@/core/access/accessPreview', () => ({
+  useAccessPreviewStore: () => ({ can: () => true }),
+}))
+vi.mock('@/modules/iam', () => ({
+  listPlatformTenants: vi.fn().mockResolvedValue({ records: [], page: 1, size: 200, total: 0, pages: 0 }),
+}))
+vi.mock('../api/platformContainerLoading', () => ({
+  listContainers: vi.fn(),
+  getSmartLoadingPlanByBooking: vi.fn(),
+  listSmartLoadingCandidates: vi.fn(),
+  listSmartLoadingWorkbenchContainers: vi.fn(),
+  createSmartLoadingPlan: vi.fn(),
+  assignSmartLoadingItem: vi.fn(),
+  assignSmartLoadingPallet: vi.fn(),
+  assignPendingReviewSmartLoadingOrder: vi.fn(),
+  assignSmartLoadingGroup: vi.fn(),
+  recommendSmartLoading: vi.fn(),
+  adjustSmartLoadingItem: vi.fn(),
+  removeSmartLoadingItem: vi.fn(),
+  removeSmartLoadingGroup: vi.fn(),
+  removeSmartLoadingPallet: vi.fn(),
+  removeAllUnpickedSmartLoadingItems: vi.fn(),
+  pushSmartLoadingPreload: vi.fn(),
+}))
+vi.mock('@/modules/warehouses', () => ({
+  listAllPlatformWarehouses: vi.fn().mockResolvedValue([
+    { id: '8', warehouseName: '义乌仓', warehouseType: 'DOMESTIC', status: 'ACTIVE' },
+    { id: '18', warehouseName: '东莞仓', warehouseType: 'DOMESTIC', status: 'ACTIVE' },
+  ]),
+}))
+vi.mock('../smartLoadingPlanGroups', () => ({ loadSmartLoadingPlanCoLoadGroups: vi.fn().mockReturnValue(new Map()) }))
+
+const container = {
+  id: '9007199254740993', planId: '9007199254740994', bookingNo: 'BK-1', cabinetNo: 'CB-1', containerNo: 'MSCU-1',
+  warehouseId: '8', warehouseName: '义乌仓', channelGroupCode: 'MATSON_CLX', channelCode: 'ZBYHK', channelName: '美森正班海卡包税', containerType: '40HQ', planStatus: 'EDITING' as const, version: 1,
+  billOfLadingNo: null, vesselName: null, voyageNo: null, shippingCompanyId: '31', shippingCompanyName: '美森轮船',
+  departurePortCode: null, departurePortName: null, destinationPortCode: null, destinationPortName: null,
+  destinationWarehouseCode: 'LAX9', destinationWarehouseName: 'LAX9', capacityCbm: 68, maxWeightKg: 19500,
+  terminalTruckingCompanyId: null, terminalTruckingCompany: null, loadingAt: null, estimatedSailingAt: null, actualSailingAt: null,
+  estimatedPortArrivalAt: null, actualPortArrivalAt: null, estimatedWarehouseArrivalAt: null, actualWarehouseArrivalAt: null,
+}
+const plan = {
+  id: '99', bookingId: container.id, planNo: 'LP-99', status: 'EDITING' as const, containerNo: 'MSCU-1', voyageNo: null, version: 2,
+  canAssign: true, canEdit: true, blockedReason: null, finalCompletionStatus: 'NOT_STARTED' as const,
+  pdaTaskId: null, pdaTaskStatus: null, pdaTaskVersion: null,
+  coLoadGroups: [],
+  palletMembers: [],
+  items: [{ id: '101', loadingPlanId: '99', accountId: '1', inboundId: '2', inboundDetailId: '3', orderId: '4', orderNo: 'ORD-1', inboundCode: 'IN-1', customerName: '示例企业', destinationWarehouseId: '9', destinationWarehouseCode: 'LAX9', destinationWarehouseName: 'LAX9', skuCode: 'SKU-1', productNameZh: '服装', unitType: 'PACKAGE' as const, palletId: null, palletNo: null, indivisible: false, packageCount: 6, productQuantity: 6, grossWeightKg: 60, volumeCbm: 1.2, loadSequence: 1, version: 1, pickedPackageCount: 0, minPackageCount: 1, canAdjust: true, canRemove: true }],
+}
+const candidate = {
+  accountId: '1', inboundId: '5', orderId: '7', orderNo: 'ORD-2', inboundCode: 'IN-2',
+  orderStatusSnapshot: 'WAIT_SPLIT', expectedArrivalAt: '2026-09-10T09:30:00',
+  warehouseId: '8', channelCode: 'ZBYHK', channelName: '美森正班海卡包税', destinationWarehouseId: '9',
+  destinationWarehouseCode: 'LAX9', destinationWarehouseName: 'LAX9', customerName: '另一企业', goodsSummary: '鞋类',
+  availablePackageCount: 12, unitGrossWeightKg: 10, unitNetWeightKg: 9, averageUnitVolumeCbm: 0.2,
+  availableVolumeCbm: 2.4, estimatedVolumeCbm: 3.5, coLoadGroupId: null, groupNo: null, memberCount: null, groupTotalBoxes: null,
+  locked: null, blockReason: null,
+}
+function candidatePage(records: unknown[], page = 1, size = 20, total = records.length) {
+  return {
+    records: records.map((record) => {
+      const candidate = record as { accountId?: string; customerId?: string; groupMembers?: unknown[] }
+      return { customerId: candidate.customerId || candidate.accountId || '', groupMembers: [], unitType: 'PACKAGE', palletId: null, palletNo: null, indivisible: false, ...candidate }
+    }),
+    page, size, total, pages: total ? Math.ceil(total / size) : 0,
+  } as Awaited<ReturnType<typeof listSmartLoadingCandidates>>
+}
+function containerPage(records: ContainerBookingResource[] = [container]) {
+  return {
+    records: records.map((item) => ({
+      bookingId: item.id, bookingNo: item.bookingNo, cabinetNo: item.cabinetNo, containerNo: item.containerNo,
+      warehouseId: item.warehouseId, warehouseName: item.warehouseName || '', channelGroupCode: item.channelGroupCode,
+      channelCode: item.channelCode, channelName: item.channelName,
+      containerType: item.containerType, capacityCbm: item.capacityCbm, maxWeightKg: item.maxWeightKg,
+      planId: item.planId, planNo: null, planStatus: item.planStatus, version: item.version,
+    })),
+    page: 1, size: 200, total: records.length, pages: records.length ? 1 : 0,
+  } as Awaited<ReturnType<typeof listSmartLoadingWorkbenchContainers>>
+}
+function mockContainerSearch(records: ContainerBookingResource[]) {
+  vi.mocked(listSmartLoadingWorkbenchContainers).mockImplementation(async (query) => containerPage(records.filter((item) => (
+    item.planStatus !== 'COMPLETED'
+    && query.channelGroupCodes.includes(item.channelGroupCode)
+  ))))
+}
+
+describe('GlobalSmartLoadingView', () => {
+  it('uses one-line shared text clamps for co-load and assigned-count summaries', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/pages/GlobalSmartLoadingView.vue'), 'utf8')
+    expect(source).toContain('<LineClampText :content="row.memberOrderSummaries.join(\'；\')" />')
+    expect(source).toContain('<LineClampText v-else-if="row.coLoadGroup" :content="`${row.packageCount} 箱（整组固定）`" />')
+    expect(source).toContain("row.unitType === 'SEALED_PALLET'")
+    expect(source).toContain('.candidate-group { display: grid; width: 100%; min-width: 0;')
+    expect(source).toContain('.candidate-group :deep(.line-clamp-text) { width: 100%; }')
+    expect(source).not.toContain('<span v-for="summary in row.memberOrderSummaries"')
+  })
+
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    vi.clearAllMocks()
+    mockContainerSearch([container])
+    vi.mocked(getSmartLoadingPlanByBooking).mockResolvedValue(plan)
+    vi.mocked(listSmartLoadingCandidates).mockResolvedValue(candidatePage([candidate]))
+  })
+
+  it('loads real containers, candidates and the selected plan into the three-column workbench', async () => {
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    expect(getSmartLoadingPlanByBooking).toHaveBeenCalledWith(container.id)
+    expect(listSmartLoadingCandidates).toHaveBeenCalledWith({ channelGroupCodes: ['MATSON_CLX'], page: 1, size: 20 })
+    expect(wrapper.text()).toContain('候选装柜明细')
+    expect(wrapper.text()).toContain('美森正班')
+    expect(wrapper.findAll('.channel-tags .el-checkbox-button')).toHaveLength(9)
+    expect(wrapper.text()).not.toContain('美森正班海卡包税')
+    expect(wrapper.text()).toContain('另一企业')
+    expect(wrapper.text()).toContain('MSCU-1 装柜方案')
+    expect(wrapper.text()).not.toContain('LP-99')
+    expect(wrapper.text()).toContain('示例企业')
+    expect(wrapper.text()).not.toContain('服装')
+    expect(wrapper.text()).not.toContain('鞋类')
+    expect(wrapper.text()).not.toContain('SKU-1')
+    expect(wrapper.text()).toContain('IN-1')
+    expect(wrapper.text()).toContain('IN-2')
+    expect(wrapper.text()).toContain('预估体积')
+    expect(wrapper.text()).toContain('3.5 m³')
+    expect(wrapper.text()).not.toContain('ORD-1')
+    expect(wrapper.text()).not.toContain('ORD-2')
+    expect(wrapper.get('.candidate-pane').text()).toContain('120 kg')
+    expect(wrapper.get('.candidate-pane').text()).toContain('2.4 m³')
+  })
+
+  it('uses the top-level container channel snapshot without expecting a nested snapshot', async () => {
+    vi.mocked(listContainers).mockResolvedValue({
+      records: [{ ...container, shippingCompanyId: '32', shippingCompanyName: 'EXX', channelCode: 'EXX_RAIL_NY', channelName: '纽约EXX海铁' }],
+      page: 1,
+      size: 100,
+      total: 1,
+      pages: 1,
+    })
+    mockContainerSearch([container])
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('美森正班')
+    expect(wrapper.text()).not.toContain('美森正班海卡包税')
+    expect(wrapper.text()).not.toContain('缺少渠道快照')
+    expect(getSmartLoadingPlanByBooking).toHaveBeenCalledWith(container.id)
+  })
+
+  it('shows one user-facing container number and hides internal manual or split references', async () => {
+    vi.mocked(listContainers).mockResolvedValue({
+      records: [{ ...container, cabinetNo: 'CAB-260814-0001', containerNo: 'SPLIT-814022117898chain1' }],
+      page: 1,
+      size: 100,
+      total: 1,
+      pages: 1,
+    })
+    mockContainerSearch([{ ...container, cabinetNo: 'CAB-260814-0001', containerNo: 'SPLIT-814022117898chain1' }])
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('CAB-260814-0001')
+    expect(wrapper.text()).not.toContain('SPLIT-814022117898chain1')
+    expect(wrapper.text()).not.toContain('LP-99')
+  })
+
+  it('explains simulated empty cabinets instead of presenting an internal id as a container number', async () => {
+    vi.mocked(listContainers).mockResolvedValue({
+      records: [{
+        ...container,
+        cabinetNo: '2088475410134773762',
+        containerNo: null,
+        channelName: '美森正班海卡包税',
+        warehouseName: '义乌国内仓',
+        containerType: '40HQ',
+      }],
+      page: 1,
+      size: 100,
+      total: 1,
+      pages: 1,
+    })
+    mockContainerSearch([{ ...container, cabinetNo: '2088475410134773762', containerNo: null, channelName: '美森正班海卡包税', warehouseName: '义乌国内仓', containerType: '40HQ' }])
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    const option = wrapper.find('.container-option')
+    expect(option.text()).toContain('模拟柜次')
+    expect(option.text()).toContain('柜次号：待生成')
+    expect(option.text()).toContain('集装箱号：待补录')
+    expect(option.text()).not.toContain('开始装柜前录入集装箱号')
+    expect(option.text()).toContain('渠道：美森正班')
+    expect(option.text()).toContain('仓库：义乌国内仓')
+    expect(option.text()).toContain('柜型：40HQ')
+    expect(option.text()).not.toContain('2088475410134773762')
+    expect(wrapper.text()).not.toContain('真实柜号')
+  })
+
+  it('keeps nine fixed channel tags and allows selecting multiple channels', async () => {
+    const other = {
+      ...container,
+      id: '9007199254740998',
+      planId: '9007199254740999',
+      cabinetNo: 'CB-2',
+      containerNo: 'MSCU-2',
+      channelGroupCode: 'HEDE',
+      channelCode: 'HDHK',
+      channelName: '合德海卡包税',
+    }
+    vi.mocked(listContainers).mockResolvedValue({ records: [container, other], page: 1, size: 100, total: 2, pages: 1 })
+    mockContainerSearch([container, other])
+    vi.mocked(getSmartLoadingPlanByBooking).mockImplementation(async (bookingId) => ({ ...plan, bookingId }))
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    expect(wrapper.findAll('.container-option')).toHaveLength(1)
+    expect(wrapper.text()).toContain('MSCU-1')
+    expect(wrapper.text()).not.toContain('MSCU-2')
+    expect(wrapper.text()).toContain('柜子数量1 个')
+
+    expect(wrapper.findAll('.channel-tags .el-checkbox-button').map((item) => item.text())).toEqual([
+      '美森正班', '美森加班', 'EXX', '合德', '洛杉矶普船', '芝加哥普船', '休斯顿普船', '萨凡纳普船', '纽约普船海卡',
+    ])
+    const hedeChannel = wrapper.findAllComponents(ElCheckboxButton).find((item) => item.text() === '合德')!
+    await hedeChannel.find('input').setValue(true)
+    await flushPromises()
+
+    expect(wrapper.findAll('.container-option')).toHaveLength(2)
+    expect(wrapper.text()).toContain('MSCU-1')
+    expect(wrapper.text()).toContain('MSCU-2')
+    expect(wrapper.text()).toContain('柜子数量2 个')
+  })
+
+  it('selects only the double-clicked channel as a shortcut', async () => {
+    const other = {
+      ...container,
+      id: '9007199254740998',
+      planId: '9007199254740999',
+      cabinetNo: 'CB-2',
+      containerNo: 'MSCU-2',
+      channelGroupCode: 'HEDE',
+      channelCode: 'HDHK',
+      channelName: '合德海卡包税',
+    }
+    vi.mocked(listContainers).mockResolvedValue({ records: [container, other], page: 1, size: 100, total: 2, pages: 1 })
+    mockContainerSearch([container, other])
+    vi.mocked(getSmartLoadingPlanByBooking).mockImplementation(async (bookingId) => ({ ...plan, bookingId }))
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    const hedeChannel = wrapper.findAllComponents(ElCheckboxButton).find((item) => item.text() === '合德')!
+    await hedeChannel.find('input').setValue(true)
+    await flushPromises()
+    expect(wrapper.findAll('.channel-tags .el-checkbox-button.is-checked')).toHaveLength(2)
+
+    await hedeChannel.trigger('dblclick')
+    await flushPromises()
+
+    expect(wrapper.findAll('.channel-tags .el-checkbox-button.is-checked').map((item) => item.text())).toEqual(['合德'])
+    expect(listSmartLoadingCandidates).toHaveBeenLastCalledWith(expect.objectContaining({ channelGroupCodes: ['HEDE'] }))
+    expect(listSmartLoadingWorkbenchContainers).toHaveBeenLastCalledWith({ channelGroupCodes: ['HEDE'], page: 1, size: 200 })
+    expect(wrapper.text()).toContain('MSCU-2')
+    expect(wrapper.text()).not.toContain('MSCU-1')
+  })
+
+  it('merges detailed pricing channels into the same confirmed display group', async () => {
+    const parcelContainer = {
+      ...container,
+      id: '9007199254740998',
+      planId: '9007199254740999',
+      cabinetNo: 'CB-2',
+      containerNo: 'MSCU-2',
+      channelCode: 'MATSON_CLX_PARCEL',
+      channelName: '美森正班海派',
+    }
+    vi.mocked(listContainers).mockResolvedValue({ records: [container, parcelContainer], page: 1, size: 100, total: 2, pages: 1 })
+    mockContainerSearch([container, parcelContainer])
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    expect(wrapper.findAll('.container-option')).toHaveLength(2)
+    expect(wrapper.text()).toContain('MSCU-1')
+    expect(wrapper.text()).toContain('MSCU-2')
+    expect(wrapper.text()).not.toContain('美森正班海卡包税')
+    expect(wrapper.text()).not.toContain('美森正班海派')
+  })
+
+  it('keeps the shipping warehouse as a candidate-only query filter', async () => {
+    const dongguanContainer = {
+      ...container,
+      id: '9007199254740998',
+      planId: '9007199254740999',
+      cabinetNo: 'CB-DG',
+      containerNo: 'MSCU-DG',
+      warehouseId: '18',
+      warehouseName: '东莞仓',
+    }
+    vi.mocked(listContainers).mockResolvedValue({ records: [container, dongguanContainer], page: 1, size: 100, total: 2, pages: 1 })
+    mockContainerSearch([container, dongguanContainer])
+    vi.mocked(getSmartLoadingPlanByBooking).mockImplementation(async (bookingId) => ({ ...plan, bookingId }))
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('MSCU-1')
+    expect(wrapper.text()).toContain('MSCU-DG')
+    const containerRequestCount = vi.mocked(listSmartLoadingWorkbenchContainers).mock.calls.length
+
+    wrapper.findComponent(QueryToolbar).vm.$emit('search', { warehouseId: '18', customerId: '', inboundCode: '', createdRange: [], orderStatuses: [] })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('MSCU-DG')
+    expect(wrapper.text()).toContain('MSCU-1')
+    expect(listSmartLoadingCandidates).toHaveBeenLastCalledWith({ channelGroupCodes: ['MATSON_CLX'], warehouseId: dongguanContainer.warehouseId, page: 1, size: 20 })
+    expect(listSmartLoadingWorkbenchContainers).toHaveBeenCalledTimes(containerRequestCount)
+  })
+
+  it('keeps channel cabinets unchanged when another search field has no matching cabinet', async () => {
+    const dongguanOvertimeContainer = {
+      ...container,
+      id: '9007199254740998',
+      planId: '9007199254740999',
+      cabinetNo: 'CB-DG-MAX',
+      containerNo: 'MSCU-DG-MAX',
+      warehouseId: '18',
+      warehouseName: '东莞仓',
+      channelGroupCode: 'MATSON_MAX',
+      channelCode: 'MATSON_MAX_TRUCK',
+      channelName: '美森加班海卡',
+    }
+    vi.mocked(listContainers).mockResolvedValue({ records: [container, dongguanOvertimeContainer], page: 1, size: 100, total: 2, pages: 1 })
+    mockContainerSearch([container, dongguanOvertimeContainer])
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    const containerRequestCount = vi.mocked(listSmartLoadingWorkbenchContainers).mock.calls.length
+
+    wrapper.findComponent(QueryToolbar).vm.$emit('search', { warehouseId: '18', customerId: '', inboundCode: '', createdRange: [], orderStatuses: [] })
+    await flushPromises()
+
+    expect(wrapper.find('.channel-tags .el-checkbox-button.is-checked').text()).toBe('美森正班')
+    expect(wrapper.findAll('.container-option')).toHaveLength(1)
+    expect(wrapper.text()).toContain('MSCU-1')
+    expect(wrapper.text()).not.toContain('MSCU-DG-MAX')
+    expect(listSmartLoadingCandidates).toHaveBeenCalledTimes(2)
+    expect(listSmartLoadingCandidates).toHaveBeenLastCalledWith({ channelGroupCodes: ['MATSON_CLX'], warehouseId: '18', page: 1, size: 20 })
+    expect(listSmartLoadingWorkbenchContainers).toHaveBeenCalledTimes(containerRequestCount)
+  })
+
+  it('filters candidate details by inbound code without filtering channel cabinets', async () => {
+    const secondContainer = {
+      ...container,
+      id: '9007199254740998',
+      planId: '9007199254740999',
+      cabinetNo: 'CB-2',
+      containerNo: 'MSCU-2',
+    }
+    vi.mocked(listContainers).mockResolvedValue({ records: [container, secondContainer], page: 1, size: 100, total: 2, pages: 1 })
+    mockContainerSearch([container, secondContainer])
+    vi.mocked(getSmartLoadingPlanByBooking).mockImplementation(async (bookingId) => ({ ...plan, bookingId }))
+    vi.mocked(listSmartLoadingCandidates)
+      .mockResolvedValueOnce(candidatePage([candidate]))
+      .mockResolvedValueOnce(candidatePage([{ ...candidate, inboundCode: 'NYEXX2609030002' }]))
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    const containerRequestCount = vi.mocked(listSmartLoadingWorkbenchContainers).mock.calls.length
+
+    wrapper.findComponent(QueryToolbar).vm.$emit('search', {
+      warehouseId: '', customerId: '', inboundCode: 'NYEXX2609030002', createdRange: [], orderStatuses: [],
+    })
+    await flushPromises()
+
+    expect(wrapper.get('.candidate-pane').text()).toContain('NYEXX2609030002')
+    expect(wrapper.findAll('.container-option')).toHaveLength(2)
+    expect(wrapper.text()).toContain('MSCU-1')
+    expect(wrapper.text()).toContain('MSCU-2')
+    expect(listSmartLoadingCandidates).toHaveBeenLastCalledWith({ channelGroupCodes: ['MATSON_CLX'], inboundCode: 'NYEXX2609030002', page: 1, size: 20 })
+    expect(listSmartLoadingWorkbenchContainers).toHaveBeenCalledTimes(containerRequestCount)
+  })
+
+  it('sends the active name-only customer selector to the server candidate query', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/pages/GlobalSmartLoadingView.vue'), 'utf8')
+    expect(source).toContain("listPlatformTenants({ page: 1, size: 200, status: 'ACTIVE' })")
+    expect(source).toContain("label: customer.tenantName")
+    expect(source).toContain('params.customerId = customerId')
+    expect(source).not.toContain('customer.tenantCode')
+  })
+
+  it('defaults ordinary candidate assignment to all available boxes', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/pages/GlobalSmartLoadingView.vue'), 'utf8')
+    expect(source).toContain(': candidate.availablePackageCount')
+  })
+
+  it('filters candidates by creation, expected-arrival range and multiple order statuses', async () => {
+    vi.mocked(listSmartLoadingCandidates)
+      .mockResolvedValueOnce(candidatePage([
+      { ...candidate, inboundId: '51', inboundCode: 'IN-MATCH', orderStatusSnapshot: 'WAIT_SPLIT', expectedArrivalAt: '2026-09-11T08:00:00' },
+      { ...candidate, inboundId: '52', inboundCode: 'IN-WRONG-STATUS', orderStatusSnapshot: 'LOADING', expectedArrivalAt: '2026-09-11T08:00:00' },
+      { ...candidate, inboundId: '53', inboundCode: 'IN-WRONG-DATE', orderStatusSnapshot: 'WAIT_SPLIT', expectedArrivalAt: '2026-09-20T08:00:00' },
+      ]))
+      .mockResolvedValueOnce(candidatePage([{ ...candidate, inboundId: '51', inboundCode: 'IN-MATCH', orderStatusSnapshot: 'WAIT_SPLIT', expectedArrivalAt: '2026-09-11T08:00:00' }]))
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    const containerRequestCount = vi.mocked(listSmartLoadingWorkbenchContainers).mock.calls.length
+
+    wrapper.getComponent(QueryToolbar).vm.$emit('search', {
+      customerId: '', inboundCode: '', orderStatuses: ['WAIT_SPLIT', 'LOADING'], createdRange: ['2026-09-10', '2026-09-12'],
+      expectedArrivalRange: ['2026-09-11', '2026-09-15'],
+    })
+    await flushPromises()
+
+    const candidates = wrapper.get('.candidate-pane').text()
+    expect(candidates).toContain('IN-MATCH')
+    expect(candidates).not.toContain('IN-WRONG-STATUS')
+    expect(candidates).not.toContain('IN-WRONG-DATE')
+    expect(listSmartLoadingCandidates).toHaveBeenLastCalledWith({ channelGroupCodes: ['MATSON_CLX'], createdStart: '2026-09-10', createdEnd: '2026-09-12', expectedArrivalStart: '2026-09-11', expectedArrivalEnd: '2026-09-15', orderStatuses: ['WAIT_SPLIT', 'LOADING'], page: 1, size: 20 })
+    expect(listSmartLoadingWorkbenchContainers).toHaveBeenCalledTimes(containerRequestCount)
+    expect(listSmartLoadingWorkbenchContainers).toHaveBeenLastCalledWith({ channelGroupCodes: ['MATSON_CLX'], page: 1, size: 200 })
+  })
+
+  it('paginates large inbound candidate results with twenty rows by default', async () => {
+    vi.mocked(listSmartLoadingCandidates)
+      .mockResolvedValueOnce(candidatePage(Array.from({ length: 20 }, (_, index) => ({
+        ...candidate,
+        inboundId: String(100 + index),
+        orderId: String(200 + index),
+        inboundCode: `IN-${String(index + 1).padStart(3, '0')}`,
+      })), 1, 20, 25))
+      .mockResolvedValueOnce(candidatePage(Array.from({ length: 5 }, (_, index) => ({
+        ...candidate,
+        inboundId: String(120 + index),
+        orderId: String(220 + index),
+        inboundCode: `IN-${String(index + 21).padStart(3, '0')}`,
+      })), 2, 20, 25))
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    const pane = wrapper.get('.candidate-pane')
+    expect(pane.text()).toContain('IN-020')
+    expect(pane.text()).not.toContain('IN-021')
+    expect(pane.text()).toContain('共 25 条 · 1/2 页')
+
+    await pane.findAll('button').find((button) => button.attributes('aria-label') === '下一页')!.trigger('click')
+    await flushPromises()
+    expect(pane.text()).toContain('IN-021')
+    expect(pane.text()).not.toContain('IN-001')
+  })
+
+  it('aggregates a two-order candidate group and calls only whole-group assignment', async () => {
+    vi.mocked(listSmartLoadingCandidates).mockResolvedValue(candidatePage([{
+      accountId: '1', inboundId: '201', orderId: '301', orderNo: 'ORD-201', inboundCode: 'NYEXX2608290051', warehouseId: '8', channelCode: 'ZBYHK', channelName: '美森正班海卡包税', destinationWarehouseId: '9', destinationWarehouseCode: 'LAX9', destinationWarehouseName: 'LAX9', customerName: '客户一、客户二', goodsSummary: '货物一、货物二', availablePackageCount: 12, unitGrossWeightKg: 10, unitNetWeightKg: 9, averageUnitVolumeCbm: 0.2, availableVolumeCbm: 2.4, coLoadGroupId: '2093539779795795969', groupNo: 'CLG-2093539779795795969', memberCount: 3, groupTotalBoxes: 12, locked: false, blockReason: null,
+      groupMembers: [
+        { accountId: '1', inboundId: '201', orderId: '301', orderNo: 'ORD-201', inboundCode: 'NYEXX2608290051', customerName: '客户一', availablePackageCount: 4, orderStatusSnapshot: 'WAIT_SPLIT', expectedArrivalAt: null },
+        { accountId: '1', inboundId: '203', orderId: '301', orderNo: 'ORD-201', inboundCode: 'NYEXX2608290051-B', customerName: '客户一', availablePackageCount: 2, orderStatusSnapshot: 'WAIT_SPLIT', expectedArrivalAt: null },
+        { accountId: '2', inboundId: '202', orderId: '302', orderNo: 'ORD-202', inboundCode: 'NYEXX2608290052', customerName: '客户二', availablePackageCount: 6, orderStatusSnapshot: 'WAIT_SPLIT', expectedArrivalAt: null },
+      ],
+    }]))
+    vi.mocked(assignSmartLoadingGroup).mockResolvedValue(plan)
+    const wrapper = mount(GlobalSmartLoadingView, { attachTo: document.body, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('CLG-2093539779795795969 · 2 票')
+    expect(wrapper.text()).toContain('3 个入仓片段')
+    expect(wrapper.text()).toContain('ORD-201：NYEXX2608290051、NYEXX2608290051-B')
+    const buttons = wrapper.findAll('.el-table__body-wrapper button').filter((button) => button.text() === '加入')
+    expect(buttons).toHaveLength(1)
+    await buttons[0].trigger('click')
+    await flushPromises()
+    expect(document.body.textContent).toContain('不能部分输入、单独分配或单独移除')
+    expect(document.body.textContent).toContain('目标柜次：CB-1 · 集装箱号：MSCU-1')
+    expect(document.body.textContent).toContain('发货仓：义乌仓 · 柜次渠道：美森正班')
+    expect(document.body.textContent).not.toContain('本次分配箱数')
+    ;([...document.body.querySelectorAll('button')].find((button) => button.textContent?.includes('确认整组分配')) as HTMLButtonElement).click()
+    await flushPromises()
+
+    expect(assignSmartLoadingGroup).toHaveBeenCalledWith(plan.id, '201', plan.version)
+    expect(assignSmartLoadingItem).not.toHaveBeenCalled()
+    wrapper.unmount()
+  })
+
+  it('allows a pending-review order to join through the provisional assignment command', async () => {
+    vi.mocked(listSmartLoadingCandidates).mockResolvedValue(candidatePage([{
+      ...candidate,
+      customerId: '',
+      inboundId: null,
+      orderStatusSnapshot: 'PENDING_REVIEW',
+      inboundCode: 'EXXHK2609020361',
+      channelCode: 'HEDE_TRUCK',
+      channelName: '合德海卡',
+      unitGrossWeightKg: null,
+      averageUnitVolumeCbm: null,
+      availableVolumeCbm: null,
+      blockReason: null,
+    }]))
+    vi.mocked(assignPendingReviewSmartLoadingOrder).mockResolvedValue(plan)
+    const wrapper = mount(GlobalSmartLoadingView, { attachTo: document.body, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    expect(wrapper.get('.candidate-pane').text()).toContain('待审核')
+    const add = wrapper.get('.candidate-pane .el-table__body-wrapper').findAll('button')
+      .find((button) => button.text().includes('加入'))!
+    expect(add.classes()).not.toContain('is-disabled')
+    await add.trigger('click')
+    await flushPromises()
+    expect(document.body.textContent).toContain('平均单箱毛重 待测量')
+    expect(document.body.textContent).toContain('平均单箱体积 待测量')
+    expect(document.body.textContent).not.toContain('平均单箱毛重 0 kg')
+    expect(document.body.textContent).toContain('订单渠道：合德海卡')
+    expect(document.body.textContent).toContain('这是人工装柜分配，确认后仍会加入')
+    expect(document.body.textContent).toContain('智能推荐不会跨渠道')
+    ;([...document.body.querySelectorAll('button')]
+      .find((button) => button.textContent?.includes('确认加入')) as HTMLButtonElement).click()
+    await flushPromises()
+
+    expect(assignPendingReviewSmartLoadingOrder).toHaveBeenCalledWith(plan.id, {
+      customerId: '1', orderId: '7', inboundCode: 'EXXHK2609020361',
+      packageCount: 12, expectedVersion: plan.version,
+    })
+    expect(assignSmartLoadingItem).not.toHaveBeenCalled()
+    wrapper.unmount()
+  })
+
+  it('blocks an incomplete three-member candidate group without exposing member assignment', async () => {
+    const members = ['401', '402', '403'].map((inboundId, index) => ({ accountId: `${index + 1}`, inboundId, orderId: `50${index}`, orderNo: `ORD-${index}`, inboundCode: `IN-${inboundId}`, customerName: `客户${index}`, availablePackageCount: 6, orderStatusSnapshot: 'WAIT_SPLIT', expectedArrivalAt: null }))
+    vi.mocked(listSmartLoadingCandidates).mockResolvedValue(candidatePage([{
+      ...candidate, inboundId: '401', orderId: '500', inboundCode: 'IN-401', coLoadGroupId: '9900', groupNo: 'CLG-9900', memberCount: 3, groupTotalBoxes: 18, availablePackageCount: 18, locked: false, blockReason: '同柜不可拆组成员候选不齐，缺少 1 票', groupMembers: members,
+    }]))
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('CLG-9900 · 3 票')
+    expect(wrapper.text()).toContain('同柜不可拆组成员候选不齐，缺少 1 票')
+    const button = wrapper.findAll('.el-table__body-wrapper button').find((item) => item.text() === '加入')!
+    expect(button.attributes('disabled')).toBeDefined()
+    expect(assignSmartLoadingGroup).not.toHaveBeenCalled()
+  })
+
+  it('shows the package summary first and opens the editor from an icon', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/pages/GlobalSmartLoadingView.vue'), 'utf8')
+    expect(source).toContain('class="package-count-summary"')
+    expect(source).toContain('aria-label="调整箱数"')
+    expect(source).toContain('v-if="(row.remainingPackageCount ?? 0) > 0"')
+    expect(source).toContain('v-if="editingQuantityId === row.id"')
+    expect(source).toContain(':controls="false"')
+    expect(source).toContain('@blur="adjust(row)" @keyup.enter="adjust(row)"')
+    expect(source).not.toContain('<Save')
+    expect(source).toContain('.plan-pane :deep(.package-count-editor .el-input-number) { width: 100%; min-width: 0; }')
+  })
+
+  it('saves a typed package count through the adjustment API when editing finishes', async () => {
+    vi.mocked(adjustSmartLoadingItem).mockResolvedValue({
+      ...plan,
+      version: 3,
+      items: [{ ...plan.items[0], packageCount: 4, version: 2 }],
+    })
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    await wrapper.find('[aria-label="调整箱数"]').trigger('click')
+    await flushPromises()
+    const quantityInput = wrapper.findAllComponents(ElInputNumber).find((input) => input.props('modelValue') === 6)
+    expect(quantityInput?.props('controls')).toBe(false)
+    quantityInput?.vm.$emit('update:modelValue', 4)
+    await flushPromises()
+    quantityInput?.vm.$emit('blur')
+    await flushPromises()
+
+    expect(adjustSmartLoadingItem).toHaveBeenCalledTimes(1)
+    expect(adjustSmartLoadingItem).toHaveBeenCalledWith(plan.id, plan.items[0].id, 4, plan.version, plan.items[0].version)
+  })
+
+  it('shows a shared pallet once with exact members and a text-only join action', async () => {
+    vi.mocked(listSmartLoadingCandidates).mockResolvedValue(candidatePage([{
+      ...candidate, unitType: 'SEALED_PALLET', palletId: '801', palletNo: 'DP-0025', indivisible: true,
+      availablePackageCount: 13, unitGrossWeightKg: 10,
+      groupMembers: [
+        { accountId: '1', inboundId: '180', orderId: '180', orderNo: 'O180', inboundCode: 'I180', customerName: '客户', availablePackageCount: 3, orderStatusSnapshot: 'WAIT_SPLIT', expectedArrivalAt: null },
+        { accountId: '1', inboundId: '181', orderId: '181', orderNo: 'O181', inboundCode: 'I181', customerName: '客户', availablePackageCount: 10, orderStatusSnapshot: 'WAIT_SPLIT', expectedArrivalAt: null },
+      ],
+    }]))
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    const buttons = wrapper.findAll('.el-table__body-wrapper button').filter(button => button.text() === '加入')
+    expect(buttons).toHaveLength(1)
+    expect(buttons[0].find('svg').exists()).toBe(false)
+    expect(wrapper.text()).toContain('I180：3 箱')
+    expect(wrapper.text()).toContain('I181：10 箱')
+    expect(wrapper.text()).toContain('130 kg')
+    expect(wrapper.get('.candidate-pane').text()).toContain('整托加入 · 不可拆')
+    expect(wrapper.get('.plan-pane').text()).toContain('按箱加入')
+    expect(wrapper.text()).toContain('装柜规则')
+    expect(wrapper.text()).not.toContain('分配单位')
+    wrapper.unmount()
+  })
+
+  it('uses one loading-rule column and expandable group details in both workbenches', () => {
+    for (const page of ['GlobalSmartLoadingView.vue', 'SmartLoadingWorkbenchView.vue']) {
+      const source = readFileSync(resolve(process.cwd(), `src/modules/container-loading/pages/${page}`), 'utf8')
+      expect(source.match(/label: '装柜规则'/g)).toHaveLength(2)
+      expect(source).not.toContain("label: '分配单位'")
+      expect(source).not.toContain('<template #unitType=')
+      expect(source.match(/<summary>整组加入 · 不可拆<\/summary>/g)).toHaveLength(2)
+      expect(source.match(/'整托加入 · 不可拆' : '按箱加入'/g)).toHaveLength(2)
+      expect(source).toContain("row.memberOrderSummaries.join('；')")
+    }
+  })
+
+  it('searches any shared-pallet inbound, retains its complete composition across pages, and resets the search', async () => {
+    const sharedPallet = {
+      ...candidate, inboundId: '180', inboundCode: 'I180', unitType: 'SEALED_PALLET' as const,
+      palletId: '801', palletNo: 'DP-0025', indivisible: true, availablePackageCount: 13,
+      groupMembers: [
+        { accountId: '1', inboundId: '180', orderId: '180', orderNo: 'O180', inboundCode: 'I180', customerName: '客户', availablePackageCount: 3, orderStatusSnapshot: 'WAIT_SPLIT', expectedArrivalAt: null },
+        { accountId: '1', inboundId: '181', orderId: '181', orderNo: 'O181', inboundCode: 'I181', customerName: '客户', availablePackageCount: 10, orderStatusSnapshot: 'WAIT_SPLIT', expectedArrivalAt: null },
+      ],
+    }
+    vi.mocked(listSmartLoadingCandidates).mockResolvedValue(candidatePage([sharedPallet], 1, 20, 21))
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    const filters = { warehouseId: '', customerId: '', inboundCode: '  I181  ', createdRange: [], expectedArrivalRange: [], orderStatuses: [] }
+    wrapper.getComponent(QueryToolbar).vm.$emit('search', filters)
+    await flushPromises()
+    expect(listSmartLoadingCandidates).toHaveBeenLastCalledWith({ channelGroupCodes: ['MATSON_CLX'], inboundCode: 'I181', page: 1, size: 20 })
+    const pane = wrapper.get('.candidate-pane')
+    expect(pane.text()).toContain('I180：3 箱')
+    expect(pane.text()).toContain('I181：10 箱')
+    expect(pane.findAll('.el-table__body-wrapper button').filter(button => button.text() === '加入')).toHaveLength(1)
+
+    await pane.get('button[aria-label="下一页"]').trigger('click')
+    await flushPromises()
+    expect(listSmartLoadingCandidates).toHaveBeenLastCalledWith({ channelGroupCodes: ['MATSON_CLX'], inboundCode: 'I181', page: 2, size: 20 })
+
+    wrapper.getComponent(QueryToolbar).vm.$emit('reset', { ...filters, inboundCode: '' })
+    await flushPromises()
+    expect(listSmartLoadingCandidates).toHaveBeenLastCalledWith({ channelGroupCodes: ['MATSON_CLX'], page: 1, size: 20 })
+    wrapper.unmount()
+  })
+
+  it('rounds capacity percentages and hides column settings in embedded tables', async () => {
+    vi.mocked(getSmartLoadingPlanByBooking).mockResolvedValue({
+      ...plan,
+      items: [{ ...plan.items[0], volumeCbm: 0.187, grossWeightKg: 13.6 }],
+    })
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('0.18%')
+    expect(wrapper.text()).toContain('0.05%')
+    expect(wrapper.text()).not.toContain('0.169999999')
+    expect(wrapper.findAll('button[aria-label="列设置"]')).toHaveLength(0)
+  })
+
+  it('keeps the confirmed candidate filters without unrelated customs fields', async () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/pages/GlobalSmartLoadingView.vue'), 'utf8')
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    const fields = wrapper.findComponent(QueryToolbar).props('fields') as Array<{ key: string; options?: Array<{ label: string; value: string }>; props?: Record<string, unknown> }>
+    expect(fields.map((field) => field.key)).toEqual(['warehouseId', 'customerId', 'inboundCode', 'createdRange', 'expectedArrivalRange', 'orderStatuses'])
+    expect(fields.find((field) => field.key === 'warehouseId')?.options).toEqual([
+      { label: '义乌仓', value: '8' },
+      { label: '东莞仓', value: '18' },
+    ])
+    expect(fields.find((field) => field.key === 'orderStatuses')?.options).toEqual([
+      { value: 'PENDING_REVIEW', label: '待审核' },
+      { value: 'WAIT_MEASURE', label: '待测量数据' },
+      { value: 'WAIT_SPLIT', label: '待分柜' },
+      { value: 'LOADING', label: '装柜中' },
+    ])
+    expect(fields.find((field) => field.key === 'orderStatuses')?.props).toMatchObject({ multiple: true, collapseTags: true, maxCollapseTags: 2 })
+    expect(source).not.toContain('目的仓')
+
+    expect(wrapper.text()).not.toContain('税率')
+    expect(wrapper.text()).not.toContain('是否退税')
+  })
+
+  it('relies on the server contract to exclude completed candidates', async () => {
+    vi.mocked(listSmartLoadingCandidates).mockResolvedValue(candidatePage([candidate]))
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    expect(wrapper.get('.candidate-pane').text()).toContain('IN-2')
+    expect(wrapper.get('.candidate-pane').text()).not.toContain('IN-LOADED')
+    expect(wrapper.get('.candidate-pane').text()).not.toContain('IN-COMPLETED')
+    expect(listSmartLoadingCandidates).toHaveBeenCalledWith({ channelGroupCodes: ['MATSON_CLX'], page: 1, size: 20 })
+  })
+
+  it('prefers an editing container on first load while keeping loading containers available', async () => {
+    const pushed = { ...container, id: '9007199254740995', planStatus: 'LOADING' as const }
+    vi.mocked(listContainers).mockResolvedValue({ records: [pushed, container], page: 1, size: 100, total: 2, pages: 1 })
+    mockContainerSearch([pushed, container])
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    expect(getSmartLoadingPlanByBooking).toHaveBeenCalledWith(container.id)
+    expect(wrapper.text()).toContain('MSCU-1 装柜方案')
+  })
+
+  it('keeps waiting and editing empty containers without exposing their status labels', async () => {
+    const waiting = { ...container, id: '9007199254740995', planId: '9007199254740996', cabinetNo: 'CB-WAIT', containerNo: null, planStatus: 'WAIT_LOADING' as const }
+    vi.mocked(listContainers).mockResolvedValue({ records: [container, waiting], page: 1, size: 100, total: 2, pages: 1 })
+    mockContainerSearch([container, waiting])
+    vi.mocked(getSmartLoadingPlanByBooking).mockImplementation(async (bookingId) => (
+      bookingId === waiting.id
+        ? { ...plan, bookingId: waiting.id, status: 'LOADING' as const }
+        : plan
+    ))
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    const waitingOption = wrapper.findAll('.container-option').find((item) => item.text().includes('CB-WAIT'))!
+    expect(waitingOption.text()).toContain('CB-WAIT')
+    expect(waitingOption.text()).not.toContain('待装柜')
+
+    const candidateCalls = vi.mocked(listSmartLoadingCandidates).mock.calls.length
+    await waitingOption.trigger('click')
+    await flushPromises()
+
+    expect(getSmartLoadingPlanByBooking).toHaveBeenCalledWith(waiting.id)
+    expect(listSmartLoadingCandidates).toHaveBeenCalledTimes(candidateCalls)
+    expect(waitingOption.text()).toContain('CB-WAIT')
+    expect(waitingOption.text()).not.toContain('拣货中')
+  })
+
+  it('keeps picking containers available when the plan capability allows increments', async () => {
+    const pushed = { ...container, id: '9007199254740995', planId: '9007199254740996', cabinetNo: 'CB-2', planStatus: 'LOADING' as const }
+    vi.mocked(listContainers).mockResolvedValue({ records: [pushed], page: 1, size: 100, total: 1, pages: 1 })
+    mockContainerSearch([pushed])
+    vi.mocked(getSmartLoadingPlanByBooking).mockResolvedValue({ ...plan, bookingId: pushed.id, status: 'LOADING', pdaTaskId: '700', pdaTaskStatus: 'LOADING', pdaTaskVersion: 4 })
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    expect(getSmartLoadingPlanByBooking).toHaveBeenCalledWith(pushed.id)
+    expect(listSmartLoadingCandidates).toHaveBeenCalledWith({ channelGroupCodes: ['MATSON_CLX'], page: 1, size: 20 })
+    expect(wrapper.findAll('.container-option')).toHaveLength(1)
+    expect(wrapper.text()).toContain('CB-2')
+    expect(wrapper.text()).not.toContain('已下发 PDA，仍可维护未完成的装柜明细')
+    expect(wrapper.text()).not.toContain('刷新 PDA 明细与版本')
+    expect(wrapper.text()).toContain('示例企业')
+  })
+
+  it('hides completed containers from the smart loading workbench', async () => {
+    const completed = { ...container, id: '9007199254740997', planId: '9007199254740998', cabinetNo: 'CB-3', planStatus: 'COMPLETED' as const }
+    vi.mocked(listContainers).mockResolvedValue({ records: [completed], page: 1, size: 100, total: 1, pages: 1 })
+    mockContainerSearch([completed])
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    expect(getSmartLoadingPlanByBooking).not.toHaveBeenCalled()
+    expect(wrapper.text()).not.toContain('CB-3')
+    expect(wrapper.text()).toContain('暂无符合条件的货柜')
+    expect(wrapper.text()).not.toContain('缺少渠道快照')
+  })
+
+  it('isolates a missing-channel row without hiding another valid container', async () => {
+    const missingChannel = { ...container, id: '9007199254740997', cabinetNo: 'CB-MISSING', channelGroupCode: '', channelCode: null, channelName: null }
+    vi.mocked(listContainers).mockResolvedValue({ records: [missingChannel, container], page: 1, size: 100, total: 2, pages: 1 })
+    mockContainerSearch([missingChannel, container])
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    expect(wrapper.findAll('.container-option')).toHaveLength(1)
+    expect(wrapper.text()).toContain('CB-1')
+    expect(wrapper.text()).not.toContain('CB-MISSING')
+    expect(wrapper.text()).not.toContain('缺少渠道快照')
+    expect(getSmartLoadingPlanByBooking).toHaveBeenCalledWith(container.id)
+  })
+
+  it('renders the channel-filtered candidate page returned by the server', async () => {
+    vi.mocked(listSmartLoadingCandidates).mockResolvedValue(candidatePage([
+      { accountId: '1', inboundId: '5', orderId: '7', orderNo: 'ORD-2', inboundCode: 'IN-MATCH', warehouseId: '8', channelCode: 'ZBYHK', channelName: '美森正班海卡包税', destinationWarehouseId: '9', destinationWarehouseCode: 'LAX9', destinationWarehouseName: 'LAX9', customerName: '匹配企业', goodsSummary: '匹配货物', availablePackageCount: 12, unitGrossWeightKg: 10, unitNetWeightKg: 9, averageUnitVolumeCbm: 0.2, availableVolumeCbm: 2.4, coLoadGroupId: null, groupNo: null, memberCount: null, groupTotalBoxes: null, locked: null, blockReason: null },
+    ]))
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('匹配企业')
+    expect(wrapper.text()).not.toContain('IN-OTHER')
+    expect(wrapper.text()).not.toContain('其他货物')
+    expect(listSmartLoadingCandidates).toHaveBeenCalledWith({ channelGroupCodes: ['MATSON_CLX'], page: 1, size: 20 })
+  })
+
+  it('refreshes the latest plan after A0409 without losing the selected container', async () => {
+    const warningMessage = vi.spyOn(ElMessage, 'warning').mockImplementation(() => undefined as never)
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    vi.mocked(getSmartLoadingPlanByBooking).mockResolvedValue({ ...plan, version: 3 })
+    vi.mocked(recommendSmartLoading).mockRejectedValueOnce(new AxiosError(
+      'conflict',
+      'ERR_BAD_REQUEST',
+      undefined,
+      undefined,
+      { data: { code: 'A0409', message: '数据已被修改', requestId: 'request-1', traceId: 'trace-1' }, status: 200, statusText: 'OK', headers: {}, config: {} as never },
+    )).mockResolvedValueOnce({ ...plan, version: 4 })
+
+    const button = wrapper.findAll('button').find((item) => item.text().includes('智能推荐'))
+    expect(button).toBeDefined()
+    await button!.trigger('click')
+    await flushPromises()
+
+    expect(recommendSmartLoading).toHaveBeenCalledWith(plan.id, 2, { customerId: '', inboundCode: '' })
+    expect(recommendSmartLoading).toHaveBeenCalledWith(plan.id, 3, { customerId: '', inboundCode: '' })
+    expect(getSmartLoadingPlanByBooking).toHaveBeenCalledTimes(2)
+    expect(warningMessage).not.toHaveBeenCalled()
+    expect(wrapper.text()).not.toContain('装柜操作失败')
+    expect(wrapper.text()).not.toContain('request-1')
+  })
+
+  it('shows a picking-specific message when a picked order cannot be removed', async () => {
+    vi.mocked(removeSmartLoadingItem).mockRejectedValue(new AxiosError(
+      'conflict',
+      'ERR_BAD_REQUEST',
+      undefined,
+      undefined,
+      { data: { code: 'A0409', message: '已有拣货记录的明细不能删除', requestId: 'request-remove-1', traceId: 'trace-remove-1' }, status: 200, statusText: 'OK', headers: {}, config: {} as never },
+    ))
+    vi.spyOn(ElMessageBox, 'confirm').mockResolvedValue('confirm' as never)
+    const errorMessage = vi.spyOn(ElMessage, 'error').mockImplementation(() => undefined as never)
+
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    const removeButton = wrapper.find('.row-actions .el-button--danger')
+    expect(removeButton.exists()).toBe(true)
+    await removeButton.trigger('click')
+    await flushPromises()
+
+    expect(removeSmartLoadingItem).toHaveBeenCalled()
+    expect(errorMessage).toHaveBeenCalledWith('该订单在拣货中不许删除')
+    expect(wrapper.text()).toContain('装柜操作失败')
+    expect(wrapper.text()).toContain('request-remove-1')
+    expect(wrapper.text()).toContain('trace-remove-1')
+  })
+
+  it('removes every unpicked item with one bulk request', async () => {
+    const secondItem = { ...plan.items[0], id: '102', inboundDetailId: '4', inboundCode: 'IN-2' }
+    const initialPlan = { ...plan, items: [plan.items[0], secondItem] }
+    const emptyPlan = { ...plan, version: 4, items: [] }
+    vi.mocked(getSmartLoadingPlanByBooking).mockResolvedValueOnce(initialPlan).mockResolvedValue(emptyPlan)
+    vi.mocked(removeAllUnpickedSmartLoadingItems).mockResolvedValueOnce(emptyPlan)
+    vi.spyOn(ElMessageBox, 'confirm').mockResolvedValue('confirm' as never)
+
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    const removeAllButton = wrapper.findAll('button').find((button) => button.text().includes('移除未拣'))
+    expect(removeAllButton).toBeDefined()
+    await removeAllButton!.trigger('click')
+    await flushPromises()
+
+    expect(removeAllUnpickedSmartLoadingItems).toHaveBeenCalledTimes(1)
+    expect(removeAllUnpickedSmartLoadingItems).toHaveBeenCalledWith(plan.id, 2)
+    expect(removeSmartLoadingItem).not.toHaveBeenCalled()
+    expect(wrapper.text()).toContain('当前柜次暂无装柜明细')
+  })
+
+  it('shows one row per inbound code and removes all internal specification rows', async () => {
+    const secondDetail = {
+      ...plan.items[0], id: '102', inboundDetailId: '4', skuCode: 'SKU-2', productNameZh: '鞋类',
+      packageCount: 4, grossWeightKg: 40, volumeCbm: 0.8, loadSequence: 2,
+    }
+    const groupedPlan = { ...plan, items: [plan.items[0], secondDetail] }
+    const afterFirst = { ...plan, version: 3, items: [secondDetail] }
+    const emptyPlan = { ...plan, version: 4, items: [] }
+    vi.mocked(getSmartLoadingPlanByBooking).mockResolvedValueOnce(groupedPlan).mockResolvedValue(emptyPlan)
+    vi.mocked(removeSmartLoadingItem).mockResolvedValueOnce(afterFirst).mockResolvedValueOnce(emptyPlan)
+    vi.spyOn(ElMessageBox, 'confirm').mockResolvedValue('confirm' as never)
+
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    const inboundRows = wrapper.findAll('tr').filter((row) => row.text().includes('IN-1'))
+    expect(inboundRows).toHaveLength(1)
+    expect(inboundRows[0].text()).toContain('多规格，需删除后重加')
+    expect(inboundRows[0].text()).toContain('100 kg')
+    expect(inboundRows[0].text()).toContain('2 m³')
+
+    await inboundRows[0].find('.el-button--danger').trigger('click')
+    await flushPromises()
+
+    expect(removeSmartLoadingItem).toHaveBeenNthCalledWith(1, plan.id, plan.items[0].id, 2, 1)
+    expect(removeSmartLoadingItem).toHaveBeenNthCalledWith(2, plan.id, secondDetail.id, 3, 1)
+  })
+
+  it('uses item capabilities to protect picked quantities and removal', async () => {
+    vi.mocked(getSmartLoadingPlanByBooking).mockResolvedValue({
+      ...plan,
+      status: 'LOADING',
+      pdaTaskId: '700',
+      pdaTaskStatus: 'LOADING',
+      pdaTaskVersion: 4,
+      items: [{ ...plan.items[0], pickedPackageCount: 3, minPackageCount: 3, canAdjust: true, canRemove: false }],
+    })
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('已拣 3 箱')
+    expect(wrapper.findAll('.row-actions .el-button--danger')).toHaveLength(0)
+    await wrapper.find('[aria-label="调整箱数"]').trigger('click')
+    await flushPromises()
+    const quantityInput = wrapper.findAllComponents(ElInputNumber).find((input) => input.props('modelValue') === 6)
+    expect(quantityInput?.props('min')).toBe(3)
+    expect(wrapper.findAll('button').some((button) => button.text().includes('移除未拣'))).toBe(false)
+  })
+
+  it('removes a sealed pallet row through the whole-pallet command', async () => {
+    const palletItem = {
+      ...plan.items[0], unitType: 'SEALED_PALLET' as const, palletId: '801', palletNo: 'DP-260914-0021',
+      indivisible: true, packageCount: 10, pickedPackageCount: 0, minPackageCount: 10,
+      canAdjust: false, canRemove: true,
+    }
+    const palletPlan = { ...plan, items: [palletItem] }
+    const emptyPlan = { ...palletPlan, version: 3, items: [] }
+    vi.mocked(getSmartLoadingPlanByBooking).mockResolvedValue(palletPlan)
+    vi.mocked(removeSmartLoadingPallet).mockResolvedValue(emptyPlan)
+
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    const row = wrapper.findAll('tr').find((candidateRow) => candidateRow.text().includes('DP-260914-0021'))
+    expect(row).toBeDefined()
+
+    await row!.find('.el-button--danger').trigger('click')
+    await flushPromises()
+
+    expect(removeSmartLoadingPallet).toHaveBeenCalledWith(plan.id, '801', 2)
+    expect(removeSmartLoadingItem).not.toHaveBeenCalled()
+  })
+
+  it('shows every inbound code and its box count for an assigned sealed pallet', async () => {
+    const palletItem = {
+      ...plan.items[0], inboundId: '180', inboundCode: 'I180', unitType: 'SEALED_PALLET' as const,
+      palletId: '801', palletNo: 'DP-260914-0025', indivisible: true, packageCount: 11,
+      pickedPackageCount: 0, minPackageCount: 11, canAdjust: false, canRemove: true,
+    }
+    vi.mocked(getSmartLoadingPlanByBooking).mockResolvedValue({
+      ...plan,
+      items: [palletItem],
+      palletMembers: [{ palletId: '801', members: [
+        { accountId: '1', inboundId: '180', orderId: '280', orderNo: 'O180', inboundCode: 'I180', customerName: '客户', availablePackageCount: 6, orderStatusSnapshot: null, expectedArrivalAt: null },
+        { accountId: '1', inboundId: '181', orderId: '281', orderNo: 'O181', inboundCode: 'I181', customerName: '客户', availablePackageCount: 5, orderStatusSnapshot: null, expectedArrivalAt: null },
+      ] }],
+    })
+
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    const row = wrapper.findAll('.plan-pane .el-table__body-wrapper tr').find((candidateRow) => candidateRow.text().includes('DP-260914-0025'))
+    expect(row).toBeDefined()
+    expect(row!.text()).toContain('2 个入仓码 · 展开')
+    expect(row!.text()).toContain('I180：6 箱')
+    expect(row!.text()).toContain('I181：5 箱')
+  })
+
+  it('renders final completion capability as read-only with the server reason', async () => {
+    vi.mocked(getSmartLoadingPlanByBooking).mockResolvedValue({
+      ...plan,
+      canAssign: false,
+      canEdit: false,
+      blockedReason: '正在校验装柜证据',
+      finalCompletionStatus: 'IN_PROGRESS',
+    })
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('正在最终确认，装柜方案暂时只读')
+    expect(wrapper.text()).toContain('正在校验装柜证据')
+    expect(wrapper.text()).not.toContain('请先完成拖车')
+    expect(wrapper.findAll('.row-actions button')).toHaveLength(0)
+    expect(wrapper.findAll('button').some((button) => button.text().includes('加入'))).toBe(false)
+  })
+
+  it('uses the server supplied total package count as the adjustment maximum', async () => {
+    vi.mocked(listSmartLoadingCandidates).mockResolvedValue(candidatePage([{ accountId: '1', inboundId: '2', orderId: '4', orderNo: 'ORD-1', inboundCode: 'IN-1', warehouseId: '8', channelCode: 'ZBYHK', channelName: '美森正班海卡包税', destinationWarehouseId: '9', destinationWarehouseCode: 'LAX9', destinationWarehouseName: 'LAX9', customerName: '示例企业', goodsSummary: '服装', availablePackageCount: 4, unitGrossWeightKg: 10, unitNetWeightKg: 9, averageUnitVolumeCbm: 0.2, availableVolumeCbm: 0.8, coLoadGroupId: null, groupNo: null, memberCount: null, groupTotalBoxes: null, locked: null, blockReason: null }]))
+    vi.mocked(getSmartLoadingPlanByBooking).mockResolvedValue({
+      ...plan,
+      items: [{ ...plan.items[0], totalPackageCount: 10, remainingPackageCount: 4 }],
+    })
+    const wrapper = mount(GlobalSmartLoadingView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('使用：6')
+    expect(wrapper.text()).toContain('未用：4')
+    expect(wrapper.text()).not.toContain('共 10 箱')
+    await wrapper.find('[aria-label="调整箱数"]').trigger('click')
+    await flushPromises()
+    const maxima = wrapper.findAllComponents(ElInputNumber).map((input) => input.props('max'))
+    expect(maxima).toContain(10)
+  })
+
+  it('uses bordered assignment and adjustment actions at narrow widths', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/pages/GlobalSmartLoadingView.vue'), 'utf8')
+    expect(source).toContain('size="small"')
+    expect(source).toContain('type="danger" plain')
+    expect(source).toContain(':max="adjustmentMax(row)"')
+    expect(source).toContain("{ key: 'customerName', prop: 'customerName', label: '客户', minWidth: 70, slotName: 'customerName' }")
+    expect(source).not.toContain('link type="danger"')
+    expect(source).toContain('@media (max-width: 720px)')
+    expect(source.match(/<DataTable[\s\S]*?\bstripe\b/g)).toHaveLength(2)
+  })
+
+  it('bounds all three workbench panes and keeps their content independently scrollable', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/pages/GlobalSmartLoadingView.vue'), 'utf8')
+
+    expect(source).toContain('height: clamp(520px, 68vh, 720px); min-height: 0;')
+    expect(source).toContain('grid-template-columns: minmax(0, 5fr) minmax(0, 2fr) minmax(0, 3fr);')
+    expect(source).toContain('.dispatch-pane { display: flex; min-width: 0; min-height: 0; flex-direction: column; }')
+    expect(source).toContain('.candidate-pane :deep(.data-table),.plan-pane :deep(.data-table) { min-height: 0; flex: 1; }')
+    expect(source).toContain(".candidate-pane :deep(.data-table__page-button[aria-label^='第']),.candidate-pane :deep(.data-table__page-ellipsis) { display: none; }")
+    expect(source).toContain('.candidate-pane :deep(.data-table__page-size .el-select) { width: 68px; }')
+    expect(source).toContain('.container-list { display: grid; min-height: 0; flex: 1;')
+    expect(source).toContain('grid-auto-rows: max-content;')
+    expect(source).toContain('overflow-wrap: anywhere;')
+    expect(source).toContain('.candidate-pane,.plan-pane { height: min(68vh, 560px); min-height: 420px; }')
+    expect(source).toContain('.container-pane { max-height: min(58vh, 460px); }')
+    expect(source).toContain('min-height: 112px')
+    expect(source).toContain("label: '创建日期'")
+    expect(source).toContain("label: '预计到货时间'")
+    expect(source).toContain("label: '订单状态'")
+    expect(source).toContain('.smart-loading-query .query-toolbar__filters) { flex-wrap: nowrap; gap: 8px; overflow-x: auto; }')
+    expect(source).toContain('.smart-loading-query .query-toolbar__actions) { flex-wrap: nowrap; gap: 6px; }')
+    expect(source).toContain(':page-sizes="[20, 50, 100]"')
+  })
+
+  it('uses nine fixed multi-select channel tags with a compact right-aligned summary', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/pages/GlobalSmartLoadingView.vue'), 'utf8')
+
+    expect(source).toContain('<el-checkbox-group :model-value="selectedChannelCodes"')
+    expect(source).toContain('v-for="channel in channelOptions"')
+    expect(source).toContain('@dblclick.stop.prevent="selectOnlyChannel(channel.code)"')
+    expect(source).toContain('{{ channel.name }}')
+    expect(source).toContain("ElMessage.warning('至少选择一个渠道')")
+    expect(source).toContain('class="compact-summary" aria-label="已选渠道装柜统计"')
+    expect(source).toContain('<dt>候选明细</dt>')
+    expect(source).toContain('<dt>柜子数量</dt>')
+    expect(source).toContain('<dt>已装</dt>')
+    expect(source).toContain('<dt>总重量</dt>')
+    expect(source).toContain('<dt>总体积</dt>')
+    expect(source).toContain('.channel-tags :deep(.el-checkbox-button__inner)')
+    expect(source).toContain('flex-wrap: nowrap; gap: 6px;')
+    expect(source).toContain('height: 34px; padding: 0 10px;')
+    expect(source).toContain('font-size: 13px; line-height: 32px;')
+    expect(source).not.toContain('class="summary-band"')
+    expect(source).toContain('class="capacity-grid"')
+    expect(source).toContain('智能推荐')
+    expect(source).not.toContain('推送预装')
+    expect(source).toContain('缺少自动生成的预装计划')
+    expect(source).not.toContain('关联并放舱真实订舱')
+    expect(source).not.toContain('订舱放舱')
+    expect(source).not.toContain("canPush && plan?.status === 'EDITING' && selectedContainer?.containerNo")
+  })
+})
diff --git a/src/modules/container-loading/pages/GlobalSmartLoadingView.vue b/src/modules/container-loading/pages/GlobalSmartLoadingView.vue
new file mode 100644
index 00000000..97e7f145
--- /dev/null
+++ b/src/modules/container-loading/pages/GlobalSmartLoadingView.vue
@@ -0,0 +1,952 @@
+<script setup lang="ts">
+import { computed, onMounted, reactive, ref } from 'vue'
+import { Pencil, RefreshCw, Sparkles, Trash2 } from '@lucide/vue'
+import SmartLoadingCandidateInbounds from '../components/SmartLoadingCandidateInbounds.vue'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { listPlatformTenants, type PlatformTenantResource } from '@/modules/iam'
+import { listAllPlatformWarehouses, type PlatformWarehouseSummaryResource } from '@/modules/warehouses'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import LineClampText from '@/shared/components/LineClampText.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import {
+  adjustSmartLoadingItem,
+  assignPendingReviewSmartLoadingOrder,
+  assignSmartLoadingGroup,
+  assignSmartLoadingItem,
+  assignSmartLoadingPallet,
+  getSmartLoadingPlanByBooking,
+  listSmartLoadingCandidates,
+  listSmartLoadingWorkbenchContainers,
+  recommendSmartLoading,
+  removeAllUnpickedSmartLoadingItems,
+  removeSmartLoadingGroup,
+  removeSmartLoadingItem,
+  removeSmartLoadingPallet,
+} from '../api/platformContainerLoading'
+import type {
+  SmartLoadingCandidate,
+  SmartLoadingCandidateGroupMember,
+  SmartLoadingPlan,
+  SmartLoadingWorkbenchContainer,
+} from '../types'
+import { groupSmartLoadingItems, type SmartLoadingInboundItem } from '../smartLoadingItems'
+import { loadSmartLoadingPlanCoLoadGroups, type SmartLoadingPlanCoLoadGroup } from '../smartLoadingPlanGroups'
+import {
+  SMART_LOADING_CHANNEL_GROUPS,
+  resolveSmartLoadingChannelGroup,
+} from '../smartLoadingChannelGroups'
+
+const props = withDefaults(defineProps<{ embedded?: boolean }>(), { embedded: false })
+const editingQuantityId = ref('')
+
+const access = useAccessPreviewStore()
+const containers = ref<SmartLoadingWorkbenchContainer[]>([])
+const warehouses = ref<PlatformWarehouseSummaryResource[]>([])
+const customers = ref<PlatformTenantResource[]>([])
+const customersLoading = ref(false)
+const selectedContainerId = ref('')
+const selectedChannelCodes = ref<string[]>([])
+const plan = ref<SmartLoadingPlan | null>(null)
+const candidates = ref<SmartLoadingCandidate[]>([])
+const loading = ref(false)
+const selectionLoading = ref(false)
+const candidateLoading = ref(false)
+const mutating = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const selectionError = ref<ApiErrorDetails | null>(null)
+const candidateError = ref<ApiErrorDetails | null>(null)
+const mutationError = ref<ApiErrorDetails | null>(null)
+const noDraft = ref(false)
+const assignOpen = ref(false)
+const selectedCandidate = ref<SmartLoadingCandidateRow | null>(null)
+const assignForm = reactive({ packageCount: 1 })
+const quantityDrafts = reactive<Record<string, number>>({})
+const planGroupsByInboundId = ref(new Map<string, SmartLoadingPlanCoLoadGroup>())
+const query = ref<QueryModel>({ warehouseId: '', customerId: '', inboundCode: '', createdRange: [], expectedArrivalRange: [], orderStatuses: [] })
+const appliedQuery = ref<QueryModel>({ ...query.value, orderStatuses: [] })
+const candidatePage = ref(1)
+const candidatePageSize = ref(20)
+const candidateTotal = ref(0)
+let selectionRequest = 0
+let candidateRequest = 0
+let containerRequest = 0
+
+const canAssign = computed(() => access.can('platform:firstleg:smart-loading:assign'))
+const canDelete = computed(() => access.can('platform:firstleg:smart-loading:delete'))
+const selectedContainer = computed(() => containers.value.find((item) => item.bookingId === selectedContainerId.value) || null)
+function containerChannelGroup(container: SmartLoadingWorkbenchContainer | null | undefined) {
+  if (!container) return null
+  return SMART_LOADING_CHANNEL_GROUPS.find((group) => group.code === container.channelGroupCode) || null
+}
+const crossChannelAssignment = computed(() => {
+  const candidateGroup = resolveSmartLoadingChannelGroup(selectedCandidate.value?.channelCode, selectedCandidate.value?.channelName)
+  const containerGroup = containerChannelGroup(selectedContainer.value)
+  return Boolean(candidateGroup && containerGroup && candidateGroup.code !== containerGroup.code)
+})
+const orchestratableContainers = computed(() => containers.value)
+const completedContainerCount = computed(() => 0)
+const missingChannelContainerCount = computed(() => orchestratableContainers.value.filter((item) => !item.channelGroupCode).length)
+const unmappedChannelContainerCount = computed(() => orchestratableContainers.value.filter((item) => (
+  item.channelGroupCode && !containerChannelGroup(item)
+)).length)
+const mappedWorkbenchContainerCount = computed(() => orchestratableContainers.value.filter((item) => (
+  containerChannelGroup(item)
+)).length)
+const channelOptions = computed(() => SMART_LOADING_CHANNEL_GROUPS)
+const warehouseOptions = computed(() => {
+  return warehouses.value.map((warehouse) => ({ value: String(warehouse.id), label: warehouse.warehouseName }))
+})
+const editable = computed(() => plan.value?.canEdit === true)
+const assignable = computed(() => plan.value?.canAssign === true)
+const assignedInboundIds = computed(() => new Set((plan.value?.items || []).map((item) => item.inboundId)))
+const assignedPalletIds = computed(() => new Set((plan.value?.items || []).map((item) => item.palletId).filter(Boolean)))
+type SmartLoadingCandidateRow = SmartLoadingCandidate & { memberInboundIds: string[]; memberInboundCodes: string[]; memberOrderSummaries: string[]; memberOrderCount: number; inboundFragmentCount: number; totalGrossWeightKg: number | null; totalVolumeCbm: number | null }
+function memberOrderSummaries<T extends { orderId: string; orderNo?: string | null; inboundCode?: string | null }>(members: T[]) {
+  const orders = new Map<string, { label: string; inboundCodes: string[] }>()
+  for (const member of members) {
+    const current = orders.get(member.orderId) || { label: member.orderNo || '订单编码待补充', inboundCodes: [] }
+    const inboundCode = member.inboundCode || '入仓码暂缺'
+    if (!current.inboundCodes.includes(inboundCode)) current.inboundCodes.push(inboundCode)
+    orders.set(member.orderId, current)
+  }
+  return [...orders.values()].map((order) => `${order.label}：${order.inboundCodes.join('、')}`)
+}
+function groupMemberLabel(group: SmartLoadingPlanCoLoadGroup) {
+  return group.inboundFragmentCount === group.memberOrderCount
+    ? `${group.memberOrderCount} 票`
+    : `${group.memberOrderCount} 票 · ${group.inboundFragmentCount} 个入仓片段`
+}
+function candidateTotalGrossWeight(candidate: SmartLoadingCandidate) {
+  return candidate.unitGrossWeightKg == null ? null : Number(candidate.unitGrossWeightKg) * Number(candidate.availablePackageCount || 0)
+}
+function candidateTotalVolume(candidate: SmartLoadingCandidate) {
+  return candidate.availableVolumeCbm == null
+    ? candidate.averageUnitVolumeCbm == null ? null : Number(candidate.averageUnitVolumeCbm) * Number(candidate.availablePackageCount || 0)
+    : Number(candidate.availableVolumeCbm)
+}
+const displayedCandidates = computed<SmartLoadingCandidateRow[]>(() => {
+  return candidates.value.map((candidate) => {
+    const members: Array<{ accountId: string; inboundId: string | null; orderId: string; orderNo?: string | null; inboundCode?: string | null }> = candidate.groupMembers.length
+      ? candidate.groupMembers
+      : [candidate]
+    return {
+      ...candidate,
+      memberInboundIds: members.map((member) => member.inboundId).filter((id): id is string => Boolean(id)),
+      memberInboundCodes: members.map((member) => member.inboundCode || '入仓码暂缺'),
+      memberOrderSummaries: memberOrderSummaries(members),
+      memberOrderCount: new Set(members.map((member) => member.orderId)).size,
+      inboundFragmentCount: Number(candidate.memberCount || members.length),
+      totalGrossWeightKg: candidateTotalGrossWeight(candidate),
+      totalVolumeCbm: candidateTotalVolume(candidate),
+    }
+  })
+})
+const planPalletMembersByPalletId = computed(() => new Map(
+  (plan.value?.palletMembers || []).map((entry) => [entry.palletId, entry.members]),
+))
+type SmartLoadingPlanRow = SmartLoadingInboundItem & { coLoadGroup: SmartLoadingPlanCoLoadGroup | null; palletMembers: SmartLoadingCandidateGroupMember[]; memberInboundCodes: string[]; memberOrderSummaries: string[] }
+const displayedPlanItems = computed<SmartLoadingPlanRow[]>(() => {
+  const inboundRows = groupSmartLoadingItems(plan.value?.items || [])
+  const result: SmartLoadingPlanRow[] = []
+  const grouped = new Map<string, SmartLoadingInboundItem[]>()
+  for (const row of inboundRows) {
+    const group = planGroupsByInboundId.value.get(row.inboundId)
+    if (!group) {
+      result.push({ ...row, coLoadGroup: null, palletMembers: row.palletId ? planPalletMembersByPalletId.value.get(row.palletId) || [] : [], memberInboundCodes: [row.inboundCode || '入仓码暂缺'], memberOrderSummaries: memberOrderSummaries([row]) })
+      continue
+    }
+    grouped.set(group.groupId, [...(grouped.get(group.groupId) || []), row])
+  }
+  for (const rows of grouped.values()) {
+    const first = rows[0]
+    const group = planGroupsByInboundId.value.get(first.inboundId)!
+    result.push({
+      ...first,
+      id: `coload:${group.groupId}`,
+      inboundCode: rows.map((row) => row.inboundCode).filter(Boolean).join('、'),
+      customerName: [...new Set(rows.map((row) => row.customerName).filter(Boolean))].join('、'),
+      packageCount: rows.reduce((sum, row) => sum + row.packageCount, 0),
+      productQuantity: rows.reduce((sum, row) => sum + Number(row.productQuantity || 0), 0),
+      grossWeightKg: rows.reduce((sum, row) => sum + Number(row.grossWeightKg || 0), 0),
+      volumeCbm: rows.reduce((sum, row) => sum + Number(row.volumeCbm || 0), 0),
+      pickedPackageCount: rows.reduce((sum, row) => sum + row.pickedPackageCount, 0),
+      minPackageCount: rows.reduce((sum, row) => sum + row.minPackageCount, 0),
+      canAdjust: false,
+      canRemove: rows.every((row) => row.canRemove),
+      sourceItems: rows.flatMap((row) => row.sourceItems),
+      detailCount: rows.reduce((sum, row) => sum + row.detailCount, 0),
+      coLoadGroup: group,
+      palletMembers: [],
+      memberInboundCodes: rows.map((row) => row.inboundCode || '入仓码暂缺'),
+      memberOrderSummaries: memberOrderSummaries(rows),
+    })
+  }
+  return result
+})
+const totalPackages = computed(() => (plan.value?.items || []).reduce((sum, item) => sum + Number(item.packageCount || 0), 0))
+const totalVolume = computed(() => (plan.value?.items || []).reduce((sum, item) => sum + Number(item.volumeCbm || 0), 0))
+const totalWeight = computed(() => (plan.value?.items || []).reduce((sum, item) => sum + Number(item.grossWeightKg || 0), 0))
+const volumeLimit = computed(() => Number(selectedContainer.value?.capacityCbm || 0) * 1.5)
+const weightLimit = computed(() => Number(selectedContainer.value?.maxWeightKg || 0) * 1.5)
+const volumePercent = computed(() => volumeLimit.value ? totalVolume.value / volumeLimit.value * 100 : 0)
+const weightPercent = computed(() => weightLimit.value ? totalWeight.value / weightLimit.value * 100 : 0)
+const displayedVolumePercent = computed(() => percentage(volumePercent.value))
+const displayedWeightPercent = computed(() => percentage(weightPercent.value))
+const candidateOrderStatusOptions = [
+  { value: 'PENDING_REVIEW', label: '待审核' },
+  { value: 'WAIT_MEASURE', label: '待测量数据' },
+  { value: 'WAIT_SPLIT', label: '待分柜' },
+  { value: 'LOADING', label: '装柜中' },
+]
+function candidateStatusLabel(status: string | null | undefined) {
+  return candidateOrderStatusOptions.find((item) => item.value === status)?.label || '—'
+}
+const queryFields = computed<QueryField[]>(() => [
+  { key: 'warehouseId', type: 'select', label: '发货仓', placeholder: '全部发货仓', width: 160, options: warehouseOptions.value, props: { filterable: true } },
+  { key: 'customerId', type: 'select', label: '客户', placeholder: '全部客户', width: 180, options: customers.value.filter((customer) => customer.status === 'ACTIVE').map((customer) => ({ label: customer.tenantName, value: String(customer.id) })), props: { filterable: true, loading: customersLoading.value } },
+  { key: 'inboundCode', type: 'input', label: '入仓码', placeholder: '请输入入仓码', width: 210 },
+  { key: 'createdRange', type: 'daterange', label: '创建日期', placeholder: '请选择创建日期范围', width: 260 },
+  { key: 'expectedArrivalRange', type: 'daterange', label: '预计到货时间', placeholder: '请选择预计到货时间范围', width: 260 },
+  { key: 'orderStatuses', type: 'select', label: '订单状态', placeholder: '全部订单状态', width: 210, options: candidateOrderStatusOptions, props: { multiple: true, collapseTags: true, collapseTagsTooltip: true, maxCollapseTags: 2 } },
+])
+
+const filteredContainers = computed(() => containers.value)
+const candidateScopeLabel = computed(() => {
+  const warehouseId = String(appliedQuery.value.warehouseId || '')
+  const warehouse = warehouseOptions.value.find((item) => item.value === warehouseId)?.label || '全部发货仓'
+  const channels = channelOptions.value.filter((item) => selectedChannelCodes.value.includes(item.code)).map((item) => item.name)
+  return `${warehouse} · ${channels.join('、') || '未选择渠道'}`
+})
+
+function preferredContainerId() {
+  const visible = filteredContainers.value
+  return visible.find((item) => item.planStatus === 'EDITING')?.bookingId
+    || visible.find((item) => item.planStatus === 'LOADING')?.bookingId
+    || visible.find((item) => item.planStatus === 'WAIT_LOADING')?.bookingId || visible[0]?.bookingId || ''
+}
+
+const candidateColumns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 90, fixed: 'left', slotName: 'actions' },
+  { key: 'inboundCode', label: '入仓码', minWidth: 220, fixed: 'left', slotName: 'candidateInbounds' },
+  { key: 'palletNo', prop: 'palletNo', label: '托盘号', minWidth: 145, showOverflowTooltip: true },
+  { key: 'coLoadGroup', label: '装柜规则', minWidth: 170, slotName: 'coLoadGroup' },
+  { key: 'customerName', prop: 'customerName', label: '客户', minWidth: 70, slotName: 'customerName' },
+  { key: 'orderStatusSnapshot', prop: 'orderStatusSnapshot', label: '订单状态', width: 100, slotName: 'orderStatusSnapshot' },
+  { key: 'availablePackageCount', prop: 'availablePackageCount', label: '箱数', width: 80 },
+  // { key: 'cartonIdentityStatus', label: '箱号归属', width: 105, slotName: 'cartonIdentityStatus' },
+  { key: 'unitGrossWeightKg', label: '单位毛重', width: 90, slotName: 'unitGrossWeight' },
+  { key: 'totalGrossWeightKg', label: '重量', width: 90, slotName: 'candidateTotalWeight' },
+  { key: 'averageUnitVolumeCbm', label: '单位体积', width: 90, slotName: 'averageUnitVolume' },
+  { key: 'totalVolumeCbm', label: '体积', width: 90, slotName: 'candidateTotalVolume' },
+  { key: 'estimatedVolumeCbm', label: '预估体积', width: 100, slotName: 'estimatedVolume' },
+]
+const itemColumns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 90, fixed: 'left', slotName: 'actions' },
+  { key: 'inboundCode', label: '入仓码', minWidth: 220, fixed: 'left', slotName: 'planInbounds' },
+  { key: 'palletNo', prop: 'palletNo', label: '托盘号', minWidth: 145, showOverflowTooltip: true },
+  { key: 'coLoadGroup', label: '装柜规则', minWidth: 170, slotName: 'coLoadGroup' },
+  { key: 'customerName', prop: 'customerName', label: '客户', minWidth: 70, slotName: 'customerName' },
+  { key: 'packageCount', label: '分配箱数', width: 140, slotName: 'packageCount' },
+  { key: 'grossWeightKg', label: '毛重', width: 90, slotName: 'weight' },
+  { key: 'volumeCbm', label: '体积', width: 90, slotName: 'volume' },
+]
+
+function formatNumber(value: number, digits = 3) {
+  return Number.isFinite(value) ? value.toLocaleString('zh-CN', { maximumFractionDigits: digits }) : '0'
+}
+function formatMeasurement(value: number | null | undefined, unit: string, digits = 3) {
+  return value == null ? '待测量' : `${formatNumber(Number(value), digits)} ${unit}`
+}
+function percentage(value: number) { return Number.isFinite(value) ? Number(Math.max(value, 0).toFixed(2)) : 0 }
+function candidateRow(source: object) { return source as SmartLoadingCandidateRow }
+function itemRow(source: object) { return source as SmartLoadingInboundItem }
+function adjustmentMax(source: object) {
+  const item = itemRow(source)
+  return Math.max(item.minPackageCount, item.totalPackageCount || item.packageCount)
+}
+function startQuantityEdit(source: object) {
+  const item = itemRow(source)
+  quantityDrafts[item.id] = item.packageCount
+  editingQuantityId.value = item.id
+}
+function displayCabinetNo(container: SmartLoadingWorkbenchContainer | null | undefined) {
+  if (!container) return '待生成'
+  const cabinetReference = String(container.cabinetNo || '').trim()
+  return /^\d{15,}$/.test(cabinetReference) ? '待生成' : cabinetReference || '待生成'
+}
+function hasRealContainerNo(container: SmartLoadingWorkbenchContainer | null | undefined) {
+  if (!container) return false
+  const value = String(container.containerNo || '').trim()
+  return Boolean(value) && !/^(?:MAN|SPLIT)-/i.test(value)
+}
+function displayActualContainerNo(container: SmartLoadingWorkbenchContainer | null | undefined) {
+  return hasRealContainerNo(container) ? String(container?.containerNo || '').trim() : '待补录'
+}
+function syncDrafts(next: SmartLoadingPlan, preserved: Record<string, number> = {}) {
+  for (const key of Object.keys(quantityDrafts)) delete quantityDrafts[key]
+  for (const item of groupSmartLoadingItems(next.items || [])) quantityDrafts[item.id] = preserved[item.id] ?? item.packageCount
+}
+function acceptPlan(next: SmartLoadingPlan, preserved: Record<string, number> = {}, syncContainerStatus = true) {
+  plan.value = next
+  planGroupsByInboundId.value = loadSmartLoadingPlanCoLoadGroups(next)
+  noDraft.value = false
+  syncDrafts(next, preserved)
+  const container = selectedContainer.value
+  if (container) {
+    container.planId = next.id
+    if (syncContainerStatus && next.status !== 'COMPLETED') container.planStatus = next.status
+  }
+}
+
+function clearSelectionData() {
+  plan.value = null
+  noDraft.value = false
+  selectionError.value = null
+  mutationError.value = null
+  planGroupsByInboundId.value = new Map()
+  for (const key of Object.keys(quantityDrafts)) delete quantityDrafts[key]
+}
+
+function candidateQueryParams(): Parameters<typeof listSmartLoadingCandidates>[0] {
+  const createdRange = Array.isArray(appliedQuery.value.createdRange)
+    ? appliedQuery.value.createdRange.map((value) => String(value || '').slice(0, 10))
+    : []
+  const expectedArrivalRange = Array.isArray(appliedQuery.value.expectedArrivalRange)
+    ? appliedQuery.value.expectedArrivalRange.map((value) => String(value || '').slice(0, 10))
+    : []
+  const params: Parameters<typeof listSmartLoadingCandidates>[0] = {
+    channelGroupCodes: [...selectedChannelCodes.value],
+    page: candidatePage.value,
+    size: candidatePageSize.value,
+  }
+  const warehouseId = String(appliedQuery.value.warehouseId || '')
+  const customerId = String(appliedQuery.value.customerId || '')
+  const inboundCode = String(appliedQuery.value.inboundCode || '').trim()
+  const orderStatuses = Array.isArray(appliedQuery.value.orderStatuses)
+    ? appliedQuery.value.orderStatuses.map((value) => String(value)).filter(Boolean) as NonNullable<typeof params.orderStatuses>
+    : []
+  if (warehouseId) params.warehouseId = warehouseId
+  if (customerId) params.customerId = customerId
+  if (inboundCode) params.inboundCode = inboundCode
+  if (createdRange.length === 2) {
+    params.createdStart = createdRange[0]
+    params.createdEnd = createdRange[1]
+  }
+  if (expectedArrivalRange.length === 2) {
+    params.expectedArrivalStart = expectedArrivalRange[0]
+    params.expectedArrivalEnd = expectedArrivalRange[1]
+  }
+  if (orderStatuses.length) params.orderStatuses = orderStatuses
+  return params
+}
+
+function containerQueryParams(page = 1): Parameters<typeof listSmartLoadingWorkbenchContainers>[0] {
+  return {
+    channelGroupCodes: [...selectedChannelCodes.value],
+    page,
+    size: 200,
+  }
+}
+
+async function loadCandidateData() {
+  if (!selectedChannelCodes.value.length) return
+  const request = ++candidateRequest
+  candidateLoading.value = true
+  candidateError.value = null
+  try {
+    const result = await listSmartLoadingCandidates(candidateQueryParams())
+    if (request !== candidateRequest) return
+    candidates.value = result.records
+    candidateTotal.value = result.total
+  } catch (error) {
+    if (request === candidateRequest) {
+      candidates.value = []
+      candidateTotal.value = 0
+      candidateError.value = getApiErrorDetails(error, '候选装柜明细加载失败')
+    }
+  } finally {
+    if (request === candidateRequest) candidateLoading.value = false
+  }
+}
+
+async function loadSelectedPlan(preserved: Record<string, number> = {}) {
+  const container = selectedContainer.value
+  const request = ++selectionRequest
+  clearSelectionData()
+  if (!container) return
+  selectionLoading.value = true
+  try {
+    const planResult = await getSmartLoadingPlanByBooking(container.bookingId).then((value) => ({ value, missing: false })).catch((error) => {
+      const details = getApiErrorDetails(error)
+      if (details.code === 'A0404') return { value: null, missing: true }
+      throw error
+    })
+    if (request !== selectionRequest) return
+    if (planResult.value) {
+      acceptPlan(planResult.value, preserved, false)
+      syncDrafts(planResult.value, preserved)
+    }
+    else noDraft.value = planResult.missing
+  } catch (error) {
+    if (request === selectionRequest) selectionError.value = getApiErrorDetails(error, '柜次装柜数据加载失败')
+  } finally {
+    if (request === selectionRequest) selectionLoading.value = false
+  }
+}
+
+async function loadContainerData(preserved: Record<string, number> = {}) {
+  if (!selectedChannelCodes.value.length) return
+  const request = ++containerRequest
+  try {
+    const firstPage = await listSmartLoadingWorkbenchContainers(containerQueryParams())
+    const remainingPages = firstPage.pages > 1
+      ? await Promise.all(Array.from({ length: firstPage.pages - 1 }, (_, index) => listSmartLoadingWorkbenchContainers(containerQueryParams(index + 2))))
+      : []
+    if (request !== containerRequest) return
+    containers.value = [firstPage, ...remainingPages].flatMap((page) => page.records)
+    if (!containers.value.some((item) => item.bookingId === selectedContainerId.value)) selectedContainerId.value = preferredContainerId()
+    await loadSelectedPlan(preserved)
+  } catch (error) {
+    if (request === containerRequest) {
+      containers.value = []
+      selectedContainerId.value = ''
+      clearSelectionData()
+      selectionError.value = getApiErrorDetails(error, '已选渠道柜次加载失败')
+    }
+  }
+}
+
+async function loadWorkbenchData(preserved: Record<string, number> = {}) {
+  await Promise.all([loadCandidateData(), loadContainerData(preserved)])
+}
+
+async function loadAll(preserved: Record<string, number> = {}) {
+  loading.value = true
+  loadError.value = null
+  try {
+    warehouses.value = await listAllPlatformWarehouses({ warehouseType: 'DOMESTIC', status: 'ACTIVE' })
+    const availableChannelCodes = new Set(channelOptions.value.map((item) => item.code))
+    selectedChannelCodes.value = selectedChannelCodes.value.filter((code) => availableChannelCodes.has(code))
+    if (!selectedChannelCodes.value.length) {
+      selectedChannelCodes.value = [channelOptions.value[0]?.code || '']
+    }
+    await loadWorkbenchData(preserved)
+  } catch (error) {
+    loadError.value = getApiErrorDetails(error, '智能装柜工作台加载失败')
+  } finally {
+    loading.value = false
+  }
+}
+async function load() { await loadAll() }
+async function loadCustomers() {
+  customersLoading.value = true
+  try {
+    const result = await listPlatformTenants({ page: 1, size: 200, status: 'ACTIVE' })
+    customers.value = result.records.filter((customer) => customer.status === 'ACTIVE')
+  } catch {
+    customers.value = []
+  } finally {
+    customersLoading.value = false
+  }
+}
+async function selectContainer(containerId: string) {
+  if (selectedContainerId.value === containerId) return
+  selectedContainerId.value = containerId
+  await loadSelectedPlan()
+}
+async function selectChannels(codes: string[]) {
+  if (!codes.length) {
+    ElMessage.warning('至少选择一个渠道')
+    return
+  }
+  selectedChannelCodes.value = codes
+  candidatePage.value = 1
+  await loadWorkbenchData()
+}
+async function selectOnlyChannel(code: string) {
+  if (selectedChannelCodes.value.length === 1 && selectedChannelCodes.value[0] === code) return
+  selectedChannelCodes.value = [code]
+  candidatePage.value = 1
+  await loadWorkbenchData()
+}
+async function applyFilters(model: QueryModel) {
+  appliedQuery.value = {
+    ...model,
+    orderStatuses: Array.isArray(model.orderStatuses) ? model.orderStatuses.map((value) => String(value)) : [],
+  }
+  candidatePage.value = 1
+  await loadCandidateData()
+}
+
+async function changeCandidatePage(page: number) {
+  candidatePage.value = page
+  await loadCandidateData()
+}
+
+async function changeCandidatePageSize(size: number) {
+  candidatePageSize.value = size
+  candidatePage.value = 1
+  await loadCandidateData()
+}
+
+function openAssign(source: object) {
+  const candidate = candidateRow(source)
+  if (candidateBlocked(candidate)) return
+  selectedCandidate.value = candidate
+  assignForm.packageCount = candidate.coLoadGroupId
+    ? Number(candidate.groupTotalBoxes || candidate.availablePackageCount)
+    : candidate.availablePackageCount
+  assignOpen.value = true
+}
+async function assign() {
+  if (!plan.value || !selectedCandidate.value) return
+  if (selectedCandidate.value.unitType !== 'SEALED_PALLET' && assignForm.packageCount < 1) return
+  if (selectedCandidate.value.coLoadGroupId && (selectedCandidate.value.blockReason || selectedCandidate.value.locked)) return
+  if (!selectedCandidate.value.coLoadGroupId && assignForm.packageCount > selectedCandidate.value.availablePackageCount) {
+    ElMessage.warning(`本次最多可分配 ${selectedCandidate.value.availablePackageCount} 箱`)
+    return
+  }
+  await mutate(async () => {
+    const selected = selectedCandidate.value!
+    acceptPlan(selected.unitType === 'SEALED_PALLET' && selected.palletId
+      ? await assignSmartLoadingPallet(plan.value!.id, { palletId: selected.palletId, expectedVersion: plan.value!.version })
+      : selected.orderStatusSnapshot === 'PENDING_REVIEW'
+      ? await assignPendingReviewSmartLoadingOrder(plan.value!.id, {
+        customerId: selected.accountId,
+        orderId: selected.orderId,
+        inboundCode: selected.inboundCode || '',
+        packageCount: assignForm.packageCount,
+        expectedVersion: plan.value!.version,
+      })
+      : selected.coLoadGroupId && selected.inboundId
+      ? await assignSmartLoadingGroup(plan.value!.id, selected.inboundId, plan.value!.version)
+      : await assignSmartLoadingItem(plan.value!.id, {
+        inboundId: selected.inboundId!,
+        packageCount: assignForm.packageCount,
+        expectedVersion: plan.value!.version,
+      }))
+    assignOpen.value = false
+    await loadCandidateData()
+    ElMessage.success(selected.coLoadGroupId ? `同柜不可拆组 ${selected.groupNo} 已整组分配` : '明细已加入当前柜次')
+  }, '分配明细失败', { preserveAssign: true })
+}
+function candidateBlocked(candidate: SmartLoadingCandidateRow) {
+  if (candidate.unitType === 'SEALED_PALLET') {
+    return Boolean(candidate.blockReason) || candidate.locked === true || !candidate.palletId
+      || !candidate.indivisible || assignedPalletIds.value.has(candidate.palletId)
+  }
+  if (candidate.orderStatusSnapshot === 'PENDING_REVIEW') {
+    return Boolean(candidate.blockReason) || candidate.locked === true
+      || !candidate.accountId || !candidate.inboundCode || candidate.availablePackageCount < 1
+  }
+  return Boolean(candidate.blockReason) || candidate.locked === true
+    || !candidate.inboundId
+    || !candidate.inboundCode
+    || candidate.memberInboundIds.some((inboundId) => assignedInboundIds.value.has(inboundId))
+    || candidate.availablePackageCount < 1
+}
+async function recommend() {
+  if (!plan.value) return
+  const scope = {
+    customerId: String(appliedQuery.value.customerId || ''),
+    inboundCode: String(appliedQuery.value.inboundCode || '').trim(),
+  }
+  await mutate(async () => {
+    try {
+      acceptPlan(await recommendSmartLoading(plan.value!.id, plan.value!.version, scope))
+    } catch (error) {
+      const details = getApiErrorDetails(error, '智能推荐失败')
+      if (details.code !== 'A0409' || !/(版本|并发|已被修改|已变化)/.test(details.message)) throw error
+      await loadSelectedPlan()
+      if (!plan.value) throw error
+      acceptPlan(await recommendSmartLoading(plan.value.id, plan.value.version, scope))
+    }
+    await loadCandidateData()
+    ElMessage.success('智能推荐已生成')
+  }, '智能推荐失败')
+}
+async function adjust(source: object) {
+  const item = itemRow(source)
+  if (item.unitType === 'SEALED_PALLET') return
+  if (!plan.value || mutating.value) return
+  const count = Number(quantityDrafts[item.id])
+  if (count === item.packageCount) return
+  if (!Number.isInteger(count) || count < item.minPackageCount) {
+    ElMessage.warning(`分配箱数不能低于已拣下限 ${item.minPackageCount} 箱`)
+    return
+  }
+  const max = adjustmentMax(item)
+  if (count > max) { ElMessage.warning(`该明细最多可分配 ${max} 箱`); return }
+  await mutate(async () => {
+    acceptPlan(await adjustSmartLoadingItem(plan.value!.id, item.id, count, plan.value!.version, item.version))
+    await loadCandidateData()
+    editingQuantityId.value = ''
+    ElMessage.success('箱数已调整')
+  }, '调整箱数失败', { preserveDrafts: { ...quantityDrafts } })
+}
+async function remove(source: object) {
+  const item = itemRow(source)
+  if (!plan.value || !item.canRemove) return
+  const row = source as SmartLoadingPlanRow
+  const sealedPallet = item.unitType === 'SEALED_PALLET' && Boolean(item.palletId)
+  const confirmed = await ElMessageBox.confirm(row.coLoadGroup
+    ? `确认整组移除 ${row.coLoadGroup.groupNo}（${groupMemberLabel(row.coLoadGroup)}、${row.packageCount} 箱）吗？组内所有入仓片段将联动移除。`
+    : sealedPallet
+      ? `确认从当前柜次整托移除托盘“${item.palletNo || '—'}”（${item.packageCount} 箱）吗？`
+      : `确认从当前柜次移除入仓码“${item.inboundCode || '—'}”的 ${item.packageCount} 箱吗？`,
+  row.coLoadGroup ? '移除同柜不可拆组' : sealedPallet ? '整托移除' : '移除装柜明细', {
+    type: 'warning', confirmButtonText: row.coLoadGroup ? '移除整组' : sealedPallet ? '整托移除' : '移除', cancelButtonText: '取消',
+  }).catch(() => false)
+  if (!confirmed || !plan.value) return
+  await mutate(async () => {
+    if (row.coLoadGroup) {
+      acceptPlan(await removeSmartLoadingGroup(plan.value!.id, row.coLoadGroup.groupId, plan.value!.version))
+      await loadCandidateData()
+      ElMessage.success(`同柜不可拆组 ${row.coLoadGroup.groupNo} 已整组移除`)
+      return
+    }
+    if (sealedPallet && item.palletId) {
+      acceptPlan(await removeSmartLoadingPallet(plan.value!.id, item.palletId, plan.value!.version))
+      await loadCandidateData()
+      ElMessage.success(`托盘 ${item.palletNo || '—'} 已整托移除`)
+      return
+    }
+    let current = plan.value!
+    for (const original of item.sourceItems) {
+      const currentItem = current.items.find((value) => value.id === original.id)
+      if (!currentItem) continue
+      current = await removeSmartLoadingItem(current.id, currentItem.id, current.version, currentItem.version)
+      acceptPlan(current)
+    }
+    await loadCandidateData()
+    ElMessage.success('该入仓码已从当前柜次移除')
+  }, '移除装柜明细失败', { pickingConflict: true })
+}
+async function removeAll() {
+  const removableItems = displayedPlanItems.value.filter((item) => item.canRemove)
+  if (!removableItems.length) return
+  const itemCount = removableItems.length
+  const confirmed = await ElMessageBox.confirm(`确认移除当前方案的 ${itemCount} 个未拣入仓码吗？已拣入仓码会保留。`, '移除未拣明细', {
+    type: 'warning', confirmButtonText: '确认移除', cancelButtonText: '取消',
+  }).catch(() => false)
+  if (!confirmed || !plan.value) return
+  await mutate(async () => {
+    acceptPlan(await removeAllUnpickedSmartLoadingItems(plan.value!.id, plan.value!.version))
+    await loadCandidateData()
+    ElMessage.success(`已移除 ${itemCount} 个未拣入仓码`)
+  }, '全部移除失败', { pickingConflict: true })
+}
+async function mutate(
+  action: () => Promise<void>,
+  fallback: string,
+  recovery: { preserveDrafts?: Record<string, number>; preserveAssign?: boolean; pickingConflict?: boolean } = {},
+) {
+  if (mutating.value) return
+  mutating.value = true
+  mutationError.value = null
+  try {
+    await action()
+  } catch (error) {
+    const details = getApiErrorDetails(error, fallback)
+    if (details.code === 'A0409') {
+      await loadAll(recovery.preserveDrafts)
+      const pickingMessage = recovery.pickingConflict && details.message.includes('拣货')
+        ? '该订单在拣货中不许删除'
+        : null
+      const message = pickingMessage || details.message || '计划或 PDA 明细已变化，已刷新最新版本并保留筛选条件，请重新操作'
+      if (recovery.preserveAssign) assignOpen.value = true
+      if (pickingMessage) ElMessage.error(pickingMessage)
+      else ElMessage.warning(message)
+    } else {
+      ElMessage.error(details.message)
+    }
+    mutationError.value = details
+  } finally {
+    mutating.value = false
+  }
+}
+
+onMounted(() => { void load(); void loadCustomers() })
+</script>
+
+<template>
+  <component :is="props.embedded ? 'div' : AdminPage" :class="{ 'embedded-smart-loading': props.embedded }">
+    <section class="global-loading-page">
+      <div v-if="channelOptions.length" class="channel-summary-row">
+        <el-checkbox-group :model-value="selectedChannelCodes" class="channel-tags" aria-label="渠道筛选，至少选择一项" @change="selectChannels($event as string[])">
+          <span class="channel-tags__label">渠道</span>
+          <el-checkbox-button
+            v-for="channel in channelOptions"
+            :key="channel.code"
+            :label="channel.code"
+            :value="channel.code"
+            title="双击仅选择此渠道"
+            @dblclick.stop.prevent="selectOnlyChannel(channel.code)"
+          >{{ channel.name }}</el-checkbox-button>
+        </el-checkbox-group>
+        <dl class="compact-summary" aria-label="已选渠道装柜统计">
+          <div><dt>候选明细</dt><dd><strong>{{ candidateTotal }}</strong> 条</dd></div>
+          <div><dt>柜子数量</dt><dd><strong>{{ filteredContainers.length }}</strong> 个</dd></div>
+          <div><dt>已装</dt><dd><strong>{{ totalPackages }}</strong> 箱</dd></div>
+          <div><dt>总重量</dt><dd><strong>{{ formatNumber(totalWeight, 1) }}</strong> kg</dd></div>
+          <div><dt>总体积</dt><dd><strong>{{ formatNumber(totalVolume) }}</strong> m³</dd></div>
+        </dl>
+      </div>
+      <el-alert v-if="missingChannelContainerCount && !mappedWorkbenchContainerCount" type="warning" :closable="false" show-icon :title="`${missingChannelContainerCount} 个可编排柜次缺少计划渠道，已隔离；请重新创建模拟柜`" />
+      <el-alert v-if="unmappedChannelContainerCount && !mappedWorkbenchContainerCount" type="warning" :closable="false" show-icon :title="`${unmappedChannelContainerCount} 个可编排柜次的计划渠道未纳入固定 9 类，已隔离`" />
+      <el-alert v-if="completedContainerCount && !orchestratableContainers.length" type="success" :closable="false" show-icon title="当前柜次已完成装柜，不可继续编辑" />
+      <QueryToolbar
+        v-model="query"
+        class="smart-loading-query"
+        ariaLabel="智能装柜筛选"
+        :fields="queryFields"
+        preference-key="global-smart-loading-query-v2"
+        :search-on-reset="false"
+        @search="applyFilters"
+        @reset="applyFilters"
+      />
+
+      <LoadErrorState v-if="loadError" title="智能装柜工作台加载失败" :message="loadError.message" :loading="loading" @retry="load">
+        <template #details><ApiErrorMeta :details="loadError" /></template>
+      </LoadErrorState>
+      <template v-else>
+        <LoadErrorState v-if="mutationError" title="装柜操作失败" :message="mutationError.message" compact retry-text="刷新工作台" @retry="loadWorkbenchData()">
+          <template #details><ApiErrorMeta :details="mutationError" /></template>
+        </LoadErrorState>
+        <section class="dispatch-grid" aria-label="智能装柜调度台">
+          <section class="dispatch-pane candidate-pane">
+            <header class="pane-header"><div><strong>候选装柜明细</strong><small>{{ candidateScopeLabel }}</small></div></header>
+            <LoadErrorState v-if="candidateError" title="候选明细加载失败" :message="candidateError.message" compact @retry="loadCandidateData()">
+              <template #details><ApiErrorMeta :details="candidateError" /></template>
+            </LoadErrorState>
+            <DataTable
+              :page="candidatePage"
+              :page-size="candidatePageSize"
+              :data="displayedCandidates"
+              :columns="candidateColumns"
+              :loading="loading || candidateLoading || mutating"
+              :total="candidateTotal"
+              :page-sizes="[20, 50, 100]"
+              stripe
+              preference-key="global-smart-loading-candidates"
+              column-settings-mode="hide"
+              empty-text="当前筛选条件下暂无候选装柜明细"
+              @update:page="changeCandidatePage"
+              @update:page-size="changeCandidatePageSize"
+            >
+              <template #pagination-left="{ total, page, pageCount }"><span v-if="pageCount > 0">共 {{ total }} 条 · {{ page }}/{{ pageCount }} 页</span><span v-else>共 0 条</span></template>
+              <template #actions="{ row }">
+                <el-button
+                  v-if="canAssign && assignable"
+                  size="small"
+                  type="text"
+                  plain
+                  :disabled="mutating || candidateBlocked(row as SmartLoadingCandidateRow)"
+                  @click="openAssign(row)"
+                >加入</el-button>
+              </template>
+              <template #candidateInbounds="{ row }"><SmartLoadingCandidateInbounds :candidate="row as SmartLoadingCandidate" /></template>
+              <template #customerName="{ row }"><LineClampText :content="row.customerName" /></template>
+              <template #coLoadGroup="{ row }"><details v-if="row.coLoadGroupId" class="candidate-group"><summary>整组加入 · 不可拆</summary><el-tag size="small" type="warning"><LineClampText :content="`${row.groupNo} · ${row.memberOrderCount} 票 · ${row.inboundFragmentCount} 个入仓片段`" /></el-tag><LineClampText :content="row.memberOrderSummaries.join('；')" /><LineClampText :content="`整组 ${row.groupTotalBoxes} 箱，必须全量进入同一柜`" /><LineClampText v-if="row.blockReason" class="candidate-block" :content="row.blockReason" /><LineClampText v-else-if="row.locked" content="该组已锁定，不能重复分配" /></details><LineClampText v-else :content="row.unitType === 'SEALED_PALLET' ? '整托加入 · 不可拆' : '按箱加入'" /></template>
+              <template #orderStatusSnapshot="{ row }"><el-tag size="small" effect="plain">{{ candidateStatusLabel(row.orderStatusSnapshot) }}</el-tag></template>
+              <template #unitGrossWeight="{ row }">{{ formatMeasurement(row.unitGrossWeightKg, 'kg', 1) }}</template>
+              <template #candidateTotalWeight="{ row }">{{ formatMeasurement(row.totalGrossWeightKg, 'kg', 1) }}</template>
+              <template #averageUnitVolume="{ row }">{{ formatMeasurement(row.averageUnitVolumeCbm, 'm³') }}</template>
+                <template #candidateTotalVolume="{ row }">{{ formatMeasurement(row.totalVolumeCbm, 'm³') }}</template>
+                <template #estimatedVolume="{ row }">{{ row.estimatedVolumeCbm == null ? '—' : `${formatNumber(Number(row.estimatedVolumeCbm))} m³` }}</template>
+              <template #cartonIdentityStatus><el-tag size="small" type="info" effect="plain">未核验</el-tag></template>
+            </DataTable>
+          </section>
+
+          <aside class="dispatch-pane container-pane" aria-label="货柜列表">
+            <header class="pane-header"><div><strong>已选渠道柜次</strong></div></header>
+            <div v-loading="loading" class="container-list">
+              <el-empty v-if="!filteredContainers.length" description="暂无符合条件的货柜" :image-size="72" />
+              <button
+                v-for="item in filteredContainers"
+                :key="item.bookingId"
+                type="button"
+                class="container-option"
+                :class="{ selected: item.bookingId === selectedContainerId }"
+                @click="selectContainer(item.bookingId)"
+              >
+                <span class="container-option__top">
+                  <strong>{{ hasRealContainerNo(item) ? displayActualContainerNo(item) : '模拟柜次' }}</strong>
+                  <el-tag size="small" :type="hasRealContainerNo(item) ? 'success' : 'info'">
+                    {{ hasRealContainerNo(item) ? '已录入集装箱号' : '空柜' }}
+                  </el-tag>
+                </span>
+                <span class="container-option__identity">柜次号：{{ displayCabinetNo(item) }}</span>
+                <span>集装箱号：{{ displayActualContainerNo(item) }}</span>
+                <span>渠道：{{ containerChannelGroup(item)?.name || '渠道待补充' }}</span>
+                <span>仓库：{{ item.warehouseName || '仓库待补充' }} · 柜型：{{ item.containerType || '柜型待补充' }}</span>
+                <!-- 空柜的操作时机由状态和操作按钮表达，不在每张柜次卡片重复提示。 -->
+              </button>
+            </div>
+          </aside>
+
+          <section class="dispatch-pane plan-pane">
+            <header class="pane-header plan-header">
+              <div><strong>{{ hasRealContainerNo(selectedContainer) ? displayActualContainerNo(selectedContainer) : displayCabinetNo(selectedContainer) }} 装柜方案</strong></div>
+              <div class="plan-actions">
+                <el-tooltip content="刷新当前柜次" placement="top"><el-button aria-label="刷新当前柜次" :loading="selectionLoading" @click="loadSelectedPlan()"><RefreshCw :size="16" /></el-button></el-tooltip>
+                <el-button v-if="canAssign && assignable && plan?.status === 'EDITING'" type="primary" plain :loading="mutating" @click="recommend"><Sparkles :size="16" />智能推荐</el-button>
+                <el-button v-if="canDelete && editable && plan?.items.some((item) => item.canRemove)" type="danger" plain :loading="mutating" @click="removeAll"><Trash2 :size="16" />移除未拣</el-button>
+              </div>
+            </header>
+
+            <LoadErrorState v-if="selectionError" title="当前柜次加载失败" :message="selectionError.message" compact @retry="loadSelectedPlan()">
+              <template #details><ApiErrorMeta :details="selectionError" /></template>
+            </LoadErrorState>
+            <el-empty v-else-if="!selectedContainer" description="请选择一个货柜" />
+            <el-empty v-else-if="noDraft" description="该柜次缺少自动生成的预装计划，请刷新后重试" />
+            <template v-else-if="plan">
+              <!--
+                已下发 PDA 的可编辑说明不再常驻展示，避免挤占装柜明细空间。
+                操作权限仍由 plan.canEdit、canAdjust 和 canRemove 控制。
+              -->
+              <el-alert
+                v-if="!plan.canEdit"
+                class="preload-readiness-alert"
+                :type="plan.finalCompletionStatus === 'COMPLETED' ? 'success' : 'info'"
+                :closable="false"
+                show-icon
+                :title="plan.finalCompletionStatus === 'IN_PROGRESS' ? '正在最终确认，装柜方案暂时只读' : plan.finalCompletionStatus === 'COMPLETED' ? '装柜已完成，方案永久只读' : '当前装柜方案只读'"
+                :description="plan.blockedReason || '请刷新计划获取最新作业状态。'"
+              />
+              <div class="capacity-grid">
+                <div><div class="meter-title"><span>体积</span><strong>{{ formatNumber(totalVolume) }} / {{ formatNumber(volumeLimit) }} m³</strong></div><el-progress :percentage="Math.min(displayedVolumePercent, 100)" :status="volumePercent > 100 ? 'exception' : undefined" /></div>
+                <div><div class="meter-title"><span>重量</span><strong>{{ formatNumber(totalWeight, 1) }} / {{ formatNumber(weightLimit, 1) }} kg</strong></div><el-progress :percentage="Math.min(displayedWeightPercent, 100)" :status="weightPercent > 100 ? 'exception' : undefined" /></div>
+              </div>
+              <DataTable :data="displayedPlanItems" :columns="itemColumns" :loading="selectionLoading || mutating" stripe preference-key="global-smart-loading-items" column-settings-mode="hide" empty-text="当前柜次暂无装柜明细">
+                <template #actions="{ row }"><div class="row-actions"><el-button v-if="canDelete && editable && row.canRemove" size="small" type="danger" text :disabled="mutating" @click="remove(row)"><Trash2 :size="15" />删除</el-button></div></template>
+                <template #planInbounds="{ row }"><SmartLoadingCandidateInbounds :members="row.palletMembers" :sealed-pallet="row.unitType === 'SEALED_PALLET'" :fallback-inbound-code="row.inboundCode" /></template>
+                <template #customerName="{ row }"><LineClampText :content="row.customerName" /></template>
+                <template #coLoadGroup="{ row }"><details v-if="row.coLoadGroup" class="candidate-group"><summary>整组加入 · 不可拆</summary><el-tag size="small" type="warning"><LineClampText :content="`${row.coLoadGroup.groupNo} · ${groupMemberLabel(row.coLoadGroup)}`" /></el-tag><LineClampText :content="row.memberOrderSummaries.join('；')" /><LineClampText :content="`固定 ${row.coLoadGroup.fullPackageCount} 箱 · ${row.coLoadGroup.lockedPlanId ? '已锁定' : '未锁定'}`" /></details><LineClampText v-else :content="row.unitType === 'SEALED_PALLET' ? '整托加入 · 不可拆' : '按箱加入'" /></template>
+                <template #packageCount="{ row }"><LineClampText v-if="row.unitType === 'SEALED_PALLET'" :content="`${row.packageCount} 箱（整托固定）`" /><LineClampText v-else-if="row.coLoadGroup" :content="`${row.packageCount} 箱（整组固定）`" /><div v-else class="package-count-editor"><el-input-number v-if="editingQuantityId === row.id" v-model="quantityDrafts[row.id]" :min="row.minPackageCount" :max="adjustmentMax(row)" :step="1" :controls="false" :disabled="mutating" placeholder="请输入使用箱数" @blur="adjust(row)" @keyup.enter="adjust(row)" /><div v-else class="package-count-summary"><div class="package-count-used"><strong>使用：{{ row.packageCount }}</strong><el-button v-if="canAssign && editable && row.canAdjust" link circle :disabled="mutating" aria-label="调整箱数" @click="startQuantityEdit(row)"><Pencil :size="14" /></el-button></div><small v-if="(row.remainingPackageCount ?? 0) > 0">未用：{{ row.remainingPackageCount }}</small></div><LineClampText v-if="row.detailCount > 1 && editable" content="多规格，需删除后重加" /><LineClampText v-if="row.pickedPackageCount > 0" :content="`已拣 ${row.pickedPackageCount} 箱`" /></div></template>
+                <template #weight="{ row }">{{ formatNumber(Number(row.grossWeightKg || 0), 1) }} kg</template>
+                <template #volume="{ row }">{{ formatNumber(Number(row.volumeCbm || 0)) }} m³</template>
+              </DataTable>
+            </template>
+          </section>
+        </section>
+
+        <AppDialog v-model="assignOpen" :title="selectedCandidate?.unitType === 'SEALED_PALLET' ? '整托加入当前柜次' : selectedCandidate?.coLoadGroupId ? '整组加入当前柜次' : '加入当前柜次'" :confirm-loading="mutating" :confirm-disabled="Boolean(selectedCandidate?.blockReason || selectedCandidate?.locked)" :confirm-text="selectedCandidate?.unitType === 'SEALED_PALLET' ? '确认整托分配' : selectedCandidate?.coLoadGroupId ? '确认整组分配' : '确认加入'" @confirm="assign">
+          <div v-if="selectedCandidate" class="assign-dialog">
+            <p><strong>{{ selectedCandidate.groupNo || selectedCandidate.customerName || '客户待补充' }}</strong></p>
+            <p>目标柜次：{{ displayCabinetNo(selectedContainer) }} · 集装箱号：{{ displayActualContainerNo(selectedContainer) }}</p>
+            <p>发货仓：{{ selectedContainer?.warehouseName || '—' }} · 柜次渠道：{{ containerChannelGroup(selectedContainer)?.name || '—' }}</p>
+            <p>订单渠道：{{ selectedCandidate.channelName || '—' }}</p>
+            <el-alert v-if="crossChannelAssignment" title="订单渠道与柜次渠道不同；这是人工装柜分配，确认后仍会加入。智能推荐不会跨渠道。" type="warning" :closable="false" />
+            <template v-if="selectedCandidate.coLoadGroupId">
+              <p>组内 {{ selectedCandidate.memberOrderCount }} 票、{{ selectedCandidate.inboundFragmentCount }} 个入仓片段，共 {{ selectedCandidate.groupTotalBoxes }} 箱</p>
+              <p v-for="summary in selectedCandidate.memberOrderSummaries" :key="summary">{{ summary }}</p>
+              <el-alert :title="selectedCandidate.blockReason || '同柜且不可拆：全部订单及其入仓片段按完整箱数一次加入，不能部分输入、单独分配或单独移除。'" :type="selectedCandidate.blockReason ? 'error' : 'warning'" :closable="false" />
+            </template>
+            <template v-else-if="selectedCandidate.unitType === 'SEALED_PALLET'">
+              <p>托盘号 {{ selectedCandidate.palletNo || '—' }} · 整托 {{ selectedCandidate.availablePackageCount }} 箱</p>
+              <SmartLoadingCandidateInbounds :candidate="selectedCandidate" />
+              <el-alert title="该封托托盘将作为一个不可拆分单元整托加入；装柜阶段复用此托盘，不会重新生成工作托盘。" type="warning" :closable="false" />
+            </template>
+            <template v-else>
+              <p>入仓码 {{ selectedCandidate.inboundCode || '—' }} · 可用 {{ selectedCandidate.availablePackageCount }} 箱 · 平均单箱毛重 {{ formatMeasurement(selectedCandidate.unitGrossWeightKg, 'kg', 1) }} · 平均单箱体积 {{ formatMeasurement(selectedCandidate.averageUnitVolumeCbm, 'm³') }}</p>
+              <small>本次只记录该入仓码的计划装柜箱数，具体箱号归属为未核验。</small>
+              <el-form label-position="top"><el-form-item label="本次分配箱数" required><el-input-number v-model="assignForm.packageCount" :min="1" :max="selectedCandidate.availablePackageCount" :step="1" controls-position="right" placeholder="请输入本次分配箱数" /></el-form-item></el-form>
+            </template>
+          </div>
+        </AppDialog>
+      </template>
+    </section>
+  </component>
+</template>
+
+<style scoped>
+.global-loading-page { display: flex; min-width: 0; min-height: 0; flex-direction: column; gap: 12px; }
+.embedded-smart-loading { display: flex; width: 100%; min-width: 0; min-height: 0; flex: 1; overflow: hidden; }
+.embedded-smart-loading .global-loading-page { width: 100%; min-height: 0; flex: 1; overflow: hidden; }
+.channel-summary-row { display: grid; grid-template-columns: minmax(0, 1fr) auto; min-width: 0; align-items: center; border-bottom: 2px solid var(--cc-border); background: #fff; }
+.channel-tags { display: flex; min-width: 0; align-items: center; flex-wrap: nowrap; gap: 6px; padding: 6px 0; overflow-x: auto; }
+.channel-tags__label { flex: 0 0 auto; margin-right: 2px; color: var(--cc-text); font-size: 13px; font-weight: 600; }
+.channel-tags :deep(.el-checkbox-button) { flex: 0 0 auto; }
+.channel-tags :deep(.el-checkbox-button__inner) { height: 34px; padding: 0 10px; border: 1px solid var(--cc-border) !important; border-radius: 6px !important; box-shadow: none !important; font-size: 13px; line-height: 32px; }
+.compact-summary { display: flex; min-height: 46px; align-items: center; justify-content: flex-end; gap: 12px; margin: 0; padding: 5px 8px; white-space: nowrap; }
+.compact-summary > div { display: flex; align-items: baseline; gap: 4px; }
+.compact-summary dt { color: var(--cc-muted); font-size: 12px; }
+.compact-summary dd { margin: 0; color: var(--cc-text); font-size: 12px; }
+.compact-summary strong { color: var(--el-color-primary); font-size: 14px; }
+:deep(.smart-loading-query.query-toolbar) { padding: 0; border: 0; background: transparent; }
+:deep(.smart-loading-query .query-toolbar__filters) { flex-wrap: nowrap; gap: 8px; overflow-x: auto; }
+:deep(.smart-loading-query .query-toolbar__tail) { flex-wrap: nowrap; gap: 8px; }
+:deep(.smart-loading-query .query-toolbar__actions) { flex-wrap: nowrap; gap: 6px; }
+.pane-header small,.container-option span,.global-loading-page small { color: var(--cc-muted); font-size: 12px; }
+.dispatch-grid { display: grid; grid-template-columns: minmax(0, 5fr) minmax(0, 2fr) minmax(0, 3fr); height: clamp(520px, 68vh, 720px); min-height: 0; overflow-x: auto; border: 1px solid var(--cc-border); background: #fff; }
+.embedded-smart-loading .dispatch-grid { height: auto; min-height: 0; flex: 1; }
+.dispatch-pane { display: flex; min-width: 0; min-height: 0; flex-direction: column; }
+.dispatch-pane + .dispatch-pane { border-left: 1px solid var(--cc-border); }
+.pane-header { display: flex; min-height: 58px; align-items: center; justify-content: space-between; gap: 12px; padding: 10px 12px; border-bottom: 1px solid var(--cc-border); background: #fff; }
+.pane-header > div:first-child { display: grid; min-width: 0; gap: 3px; }
+.candidate-pane :deep(.data-table),.plan-pane :deep(.data-table) { min-height: 0; flex: 1; }
+.candidate-pane :deep(.el-table),.plan-pane :deep(.el-table) { height: 100%; }
+.candidate-pane :deep(.data-table__pagination) { min-height: 46px; flex-wrap: nowrap; gap: 8px; padding: 7px 8px; }
+.candidate-pane :deep(.data-table__pagination-left) { flex: 0 0 auto; white-space: nowrap; }
+.candidate-pane :deep(.data-table__pagination-controls),.candidate-pane :deep(.data-table__page-size),.candidate-pane :deep(.data-table__page-buttons) { flex-wrap: nowrap; gap: 4px; white-space: nowrap; }
+.candidate-pane :deep(.data-table__page-button[aria-label^='第']),.candidate-pane :deep(.data-table__page-ellipsis) { display: none; }
+.candidate-pane :deep(.data-table__page-size .el-select) { width: 68px; }
+.container-pane { background: #fafafa; }
+.container-list { display: grid; min-height: 0; flex: 1; grid-auto-rows: max-content; align-content: start; gap: 8px; padding: 10px; overflow-y: auto; }
+.container-option { display: grid; width: 100%; min-height: 112px; height: auto; align-content: start; gap: 6px; padding: 14px; overflow: hidden; border: 1px solid var(--cc-border); border-radius: 6px; background: #fff; color: var(--cc-text); line-height: 1.4; text-align: left; cursor: pointer; }
+.container-option:hover,.container-option:focus-visible { border-color: var(--el-color-primary); outline: none; }
+.container-option.selected { border-color: var(--el-color-primary); box-shadow: inset 3px 0 0 var(--el-color-primary); background: var(--el-color-primary-light-9); }
+.container-option__top { display: flex; align-items: center; justify-content: space-between; gap: 8px; color: var(--cc-text) !important; }
+.container-option__identity { color: var(--cc-text); font-size: 13px; font-weight: 600; }
+.container-option__hint { color: var(--el-color-warning); font-weight: 600; }
+.container-option span,.container-option strong { min-width: 0; overflow-wrap: anywhere; }
+.plan-header { flex-wrap: wrap; }
+.plan-actions,.row-actions,.meter-title { display: flex; align-items: center; gap: 8px; }
+.plan-actions,.row-actions { flex-wrap: wrap; }
+.plan-actions :deep(.el-button + .el-button),.row-actions :deep(.el-button + .el-button) { margin-left: 0; }
+.capacity-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 12px; padding: 12px; border-bottom: 1px solid var(--cc-border); }
+.preload-readiness-alert { border-radius: 0; border-right: 0; border-left: 0; }
+.readonly-status-card { display: grid; align-content: start; justify-items: start; gap: 10px; padding: 28px 24px; }
+.readonly-status-card strong { font-size: 16px; }
+.readonly-status-card p { max-width: 460px; margin: 0; color: var(--cc-muted); line-height: 1.6; }
+.meter-title { justify-content: space-between; margin-bottom: 8px; font-size: 12px; }
+.package-count-editor { display: grid; min-width: 0; gap: 4px; }
+.package-count-summary { display: grid; gap: 3px; line-height: 1.35; }
+.package-count-used { display: flex; align-items: center; justify-content: space-between; gap: 6px; }
+.package-count-summary strong { font-size: 13px; font-weight: 600; }
+.package-count-summary small { color: var(--cc-muted); font-size: 12px; }
+.plan-pane :deep(.package-count-editor .el-input-number) { width: 100%; min-width: 0; }
+.assign-dialog p { margin: 0 0 10px; }
+.assign-dialog :deep(.el-input-number) { width: 100%; }
+.candidate-group { display: grid; width: 100%; min-width: 0; gap: 4px; }
+.candidate-group :deep(.el-tag),.candidate-group :deep(.el-tag__content),.candidate-group :deep(.line-clamp-text) { max-width: 100%; min-width: 0; }
+.candidate-group :deep(.line-clamp-text) { width: 100%; }
+.candidate-block { color: var(--el-color-danger) !important; }
+@media (max-width: 1180px) {
+  :deep(.smart-loading-query .query-toolbar__filters),:deep(.smart-loading-query .query-toolbar__tail),:deep(.smart-loading-query .query-toolbar__actions) { flex-wrap: wrap; overflow: visible; }
+  .dispatch-grid { grid-template-columns: 1fr; height: auto; min-height: 0; overflow: visible; }
+  .embedded-smart-loading .dispatch-grid { height: auto; }
+  .dispatch-pane + .dispatch-pane { border-top: 1px solid var(--cc-border); border-left: 0; }
+  .candidate-pane,.plan-pane { height: min(68vh, 560px); min-height: 420px; }
+  .candidate-pane :deep(.data-table__pagination) { flex-wrap: wrap; }
+  .container-pane { max-height: min(58vh, 460px); }
+  .container-list { grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); max-height: none; }
+}
+@media (max-width: 720px) {
+  .channel-summary-row { grid-template-columns: minmax(0, 1fr); align-items: stretch; }
+  .compact-summary { grid-column: 1 / -1; }
+  .compact-summary { min-height: 0; justify-content: flex-start; flex-wrap: wrap; gap: 6px 14px; padding: 8px 12px; white-space: normal; }
+  .capacity-grid { grid-template-columns: 1fr; }
+  .pane-header,.plan-actions,.meter-title { align-items: stretch; flex-direction: column; }
+  .plan-actions :deep(.el-button) { width: 100%; min-height: 40px; margin-left: 0; }
+  .container-list { grid-template-columns: 1fr; }
+  .channel-tags { padding-inline: 8px; }
+}
+</style>
diff --git a/src/modules/container-loading/pages/OverseasContainerDetailView.vue b/src/modules/container-loading/pages/OverseasContainerDetailView.vue
new file mode 100644
index 00000000..868770da
--- /dev/null
+++ b/src/modules/container-loading/pages/OverseasContainerDetailView.vue
@@ -0,0 +1,5 @@
+<script setup lang="ts">
+import ContainerDetailView from './ContainerDetailView.vue'
+</script>
+
+<template><ContainerDetailView workbench="OVERSEAS" /></template>
diff --git a/src/modules/container-loading/pages/OverseasContainersView.vue b/src/modules/container-loading/pages/OverseasContainersView.vue
new file mode 100644
index 00000000..dab93335
--- /dev/null
+++ b/src/modules/container-loading/pages/OverseasContainersView.vue
@@ -0,0 +1,5 @@
+<script setup lang="ts">
+import ContainersView from './ContainersView.vue'
+</script>
+
+<template><ContainersView workbench="OVERSEAS" /></template>
diff --git a/src/modules/container-loading/pages/SmartLoadingWorkbenchView.test.ts b/src/modules/container-loading/pages/SmartLoadingWorkbenchView.test.ts
new file mode 100644
index 00000000..0f9d9e48
--- /dev/null
+++ b/src/modules/container-loading/pages/SmartLoadingWorkbenchView.test.ts
@@ -0,0 +1,256 @@
+import ElementPlus, { ElMessageBox } from 'element-plus'
+import { AxiosError } from 'axios'
+import { createPinia, setActivePinia } from 'pinia'
+import { createMemoryHistory, createRouter } from 'vue-router'
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import SmartLoadingWorkbenchView from './SmartLoadingWorkbenchView.vue'
+import { assignSmartLoadingGroup, assignSmartLoadingItem, assignSmartLoadingPallet, getContainer, getSmartLoadingPlanByBooking, listSmartLoadingCandidates, recommendSmartLoading, removeSmartLoadingGroup } from '../api/platformContainerLoading'
+
+vi.mock('../api/platformContainerLoading', () => ({
+  getContainer: vi.fn(), getSmartLoadingPlanByBooking: vi.fn(), listSmartLoadingCandidates: vi.fn(),
+  createSmartLoadingPlan: vi.fn(), assignSmartLoadingItem: vi.fn(), assignSmartLoadingPallet: vi.fn(), assignSmartLoadingGroup: vi.fn(), recommendSmartLoading: vi.fn(),
+  adjustSmartLoadingItem: vi.fn(), removeSmartLoadingItem: vi.fn(), removeSmartLoadingGroup: vi.fn(), pushSmartLoadingPreload: vi.fn(),
+}))
+vi.mock('../smartLoadingPlanGroups', () => ({ loadSmartLoadingPlanCoLoadGroups: vi.fn().mockResolvedValue(new Map()) }))
+vi.mock('@/core/access/accessPreview', () => ({ useAccessPreviewStore: () => ({ can: () => true }) }))
+
+const container = {
+  id: '9007199254740993', planId: '9007199254740994', bookingNo: 'BK-1', cabinetNo: 'CB-1', containerNo: 'MSCU-1',
+  warehouseId: '8', warehouseName: '义乌仓', channelGroupCode: 'MATSON_CLX', channelCode: null, channelName: null, containerType: '40HQ', planStatus: 'EDITING' as const, version: 1,
+  billOfLadingNo: null, vesselName: null, voyageNo: null, shippingCompanyId: null, shippingCompanyName: null,
+  departurePortCode: null, departurePortName: null, destinationPortCode: null, destinationPortName: null,
+  destinationWarehouseCode: 'LAX9', destinationWarehouseName: 'LAX9', capacityCbm: 68, maxWeightKg: 19500,
+  terminalTruckingCompanyId: null, terminalTruckingCompany: null, loadingAt: null, estimatedSailingAt: null, actualSailingAt: null,
+  estimatedPortArrivalAt: null, actualPortArrivalAt: null, estimatedWarehouseArrivalAt: null, actualWarehouseArrivalAt: null,
+}
+const planResponse = {
+  id: '99', bookingId: container.id, planNo: 'LP-99', status: 'EDITING' as const, containerNo: 'MSCU-1', voyageNo: null, version: 2,
+  canAssign: true, canEdit: true, blockedReason: null, finalCompletionStatus: 'NOT_STARTED' as const,
+  pdaTaskId: null, pdaTaskStatus: null, pdaTaskVersion: null, coLoadGroups: [], palletMembers: [], items: [],
+}
+const candidate = { accountId: '1', inboundId: '2', orderId: '4', orderNo: 'ORD-1', inboundCode: 'IN-1', warehouseId: '8', channelCode: 'ZBYHK', channelName: '美森正班海卡包税', destinationWarehouseId: '9', destinationWarehouseCode: 'LAX9', destinationWarehouseName: 'LAX9', customerName: '示例企业', goodsSummary: '服装', availablePackageCount: 12, unitGrossWeightKg: 10, unitNetWeightKg: 9, averageUnitVolumeCbm: 0.2, availableVolumeCbm: 2.4, coLoadGroupId: null, groupNo: null, memberCount: null, groupTotalBoxes: null, locked: null, blockReason: null }
+function candidatePage(records: unknown[]) {
+  return {
+    records: records.map((record) => {
+      const candidate = record as { accountId?: string; customerId?: string; groupMembers?: unknown[] }
+      return { customerId: candidate.customerId || candidate.accountId || '', groupMembers: [], unitType: 'PACKAGE', palletId: null, palletNo: null, indivisible: false, ...candidate }
+    }),
+    page: 1, size: 200, total: records.length, pages: records.length ? 1 : 0,
+  } as Awaited<ReturnType<typeof listSmartLoadingCandidates>>
+}
+
+describe('SmartLoadingWorkbenchView', () => {
+  it('uses one-line shared text clamps for co-load and assigned-count summaries', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/pages/SmartLoadingWorkbenchView.vue'), 'utf8')
+    expect(source).toContain('<LineClampText :content="row.memberOrderSummaries.join(\'；\')" />')
+    expect(source).toContain('<LineClampText v-else-if="row.coLoadGroup" :content="`${row.packageCount} 箱（整组固定）`" />')
+    expect(source).toContain("row.unitType === 'SEALED_PALLET'")
+    expect(source).toContain('.candidate-group { display: grid; width: 100%; min-width: 0;')
+    expect(source).toContain('.candidate-group :deep(.line-clamp-text) { width: 100%;')
+    expect(source).toContain('<template #goods="{ row }"><div class="goods-cell"><LineClampText')
+    expect(source).toContain('<template #goodsSummary="{ row }"><LineClampText')
+    expect(source).not.toContain('<span v-for="summary in row.memberOrderSummaries"')
+  })
+
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    vi.clearAllMocks()
+    vi.mocked(getContainer).mockResolvedValue(container)
+    vi.mocked(getSmartLoadingPlanByBooking).mockResolvedValue(planResponse)
+    vi.mocked(listSmartLoadingCandidates).mockResolvedValue(candidatePage([candidate]))
+  })
+
+  it('restores the real draft and explains candidate capacity', async () => {
+    const router = createRouter({ history: createMemoryHistory(), routes: [{ path: '/container-loading/:containerId/smart-loading', component: SmartLoadingWorkbenchView }] })
+    await router.push(`/container-loading/${container.id}/smart-loading`); await router.isReady()
+    const wrapper = mount(SmartLoadingWorkbenchView, { global: { plugins: [ElementPlus, router] } })
+    await flushPromises()
+    expect(getContainer).toHaveBeenCalledWith(container.id)
+    expect(getSmartLoadingPlanByBooking).toHaveBeenCalledWith(container.id)
+    expect(listSmartLoadingCandidates).toHaveBeenCalledWith({ channelGroupCodes: ['MATSON_CLX'], warehouseId: '8', page: 1, size: 200 })
+    expect(wrapper.text()).toContain('MSCU-1 装柜方案')
+    expect(wrapper.text()).not.toContain('LP-99')
+    expect(wrapper.text()).toContain('IN-1')
+    expect(wrapper.text()).not.toContain('ORD-1')
+    expect(wrapper.text()).toContain('150% 容量上限')
+  })
+
+  it('shows the full inbound composition for an assigned sealed pallet', async () => {
+    vi.mocked(getSmartLoadingPlanByBooking).mockResolvedValue({
+      ...planResponse,
+      items: [{
+        id: '101', loadingPlanId: '99', accountId: '1', inboundId: '180', inboundDetailId: '201', orderId: '280',
+        orderNo: 'O180', inboundCode: 'I180', customerName: '客户', destinationWarehouseId: '9',
+        destinationWarehouseCode: 'LAX9', destinationWarehouseName: 'LAX9', skuCode: 'SKU-1', productNameZh: '货物',
+        unitType: 'SEALED_PALLET', palletId: '801', palletNo: 'DP-260914-0025', indivisible: true,
+        packageCount: 11, productQuantity: 110, grossWeightKg: 109.2, volumeCbm: 1.87, loadSequence: 1,
+        version: 1, pickedPackageCount: 0, minPackageCount: 11, canAdjust: false, canRemove: true,
+      }],
+      palletMembers: [{ palletId: '801', members: [
+        { accountId: '1', inboundId: '180', orderId: '280', orderNo: 'O180', inboundCode: 'I180', customerName: '客户', availablePackageCount: 6, orderStatusSnapshot: null, expectedArrivalAt: null },
+        { accountId: '1', inboundId: '181', orderId: '281', orderNo: 'O181', inboundCode: 'I181', customerName: '客户', availablePackageCount: 5, orderStatusSnapshot: null, expectedArrivalAt: null },
+      ] }],
+    })
+    const router = createRouter({ history: createMemoryHistory(), routes: [{ path: '/container-loading/:containerId/smart-loading', component: SmartLoadingWorkbenchView }] })
+    await router.push(`/container-loading/${container.id}/smart-loading`); await router.isReady()
+    const wrapper = mount(SmartLoadingWorkbenchView, { global: { plugins: [ElementPlus, router] } })
+    await flushPromises()
+
+    const row = wrapper.findAll('.el-table__body-wrapper tr').find((candidateRow) => candidateRow.text().includes('DP-260914-0025'))
+    expect(row).toBeDefined()
+    expect(row!.text()).toContain('I180：6 箱')
+    expect(row!.text()).toContain('I181：5 箱')
+  })
+
+  it('uses loading plan capabilities to keep PDA increments editable', async () => {
+    vi.mocked(getContainer).mockResolvedValue({ ...container, planStatus: 'LOADING' })
+    vi.mocked(getSmartLoadingPlanByBooking).mockResolvedValue({ ...planResponse, status: 'LOADING', pdaTaskId: '700', pdaTaskStatus: 'LOADING', pdaTaskVersion: 4 })
+    const router = createRouter({ history: createMemoryHistory(), routes: [{ path: '/container-loading/:containerId/smart-loading', component: SmartLoadingWorkbenchView }] })
+    await router.push(`/container-loading/${container.id}/smart-loading`); await router.isReady()
+    const wrapper = mount(SmartLoadingWorkbenchView, { global: { plugins: [ElementPlus, router] } })
+    await flushPromises()
+
+    expect(getSmartLoadingPlanByBooking).toHaveBeenCalledWith(container.id)
+    expect(listSmartLoadingCandidates).toHaveBeenCalledWith({ channelGroupCodes: ['MATSON_CLX'], warehouseId: container.warehouseId, page: 1, size: 200 })
+    expect(wrapper.text()).toContain('已下发 PDA，仍可维护未完成的装柜明细')
+    expect(wrapper.text()).toContain('刷新 PDA 明细与版本')
+    expect(wrapper.text()).not.toContain('智能推荐')
+    expect(wrapper.text()).toContain('IN-1')
+  })
+
+  it('refreshes the latest plan after A0409', async () => {
+    vi.mocked(getSmartLoadingPlanByBooking)
+      .mockResolvedValueOnce(planResponse)
+      .mockResolvedValueOnce({ ...planResponse, version: 3 })
+    vi.mocked(recommendSmartLoading).mockRejectedValueOnce(new AxiosError(
+      'conflict', 'ERR_BAD_REQUEST', undefined, undefined,
+      { data: { code: 'A0409', message: '数据已被修改', requestId: 'request-1', traceId: 'trace-1' }, status: 200, statusText: 'OK', headers: {}, config: {} as never },
+    )).mockResolvedValueOnce({ ...planResponse, version: 4 })
+    const router = createRouter({ history: createMemoryHistory(), routes: [{ path: '/container-loading/:containerId/smart-loading', component: SmartLoadingWorkbenchView }] })
+    await router.push(`/container-loading/${container.id}/smart-loading`); await router.isReady()
+    const wrapper = mount(SmartLoadingWorkbenchView, { global: { plugins: [ElementPlus, router] } })
+    await flushPromises()
+
+    await wrapper.findAll('button').find((button) => button.text().includes('智能推荐'))!.trigger('click')
+    await flushPromises()
+    expect(getSmartLoadingPlanByBooking).toHaveBeenCalledTimes(2)
+    expect(recommendSmartLoading).toHaveBeenCalledWith(planResponse.id, 2)
+    expect(recommendSmartLoading).toHaveBeenCalledWith(planResponse.id, 3)
+    expect(wrapper.text()).not.toContain('装柜操作失败')
+  })
+
+  it('uses bordered row actions and has no manual preload push', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/pages/SmartLoadingWorkbenchView.vue'), 'utf8')
+    expect(source).toContain('size="small" type="primary" plain')
+    expect(source).toContain('size="small" type="danger" plain')
+    expect(source).not.toContain('canPush')
+    expect(source).not.toContain('推送预装')
+    expect(source).not.toContain('关联并放舱真实订舱')
+    expect(source).not.toContain('订舱放舱')
+    expect(source).not.toContain('link type="primary" :disabled="!routeMatches(row)')
+    expect(source).not.toContain("label: '目的仓'")
+    expect(source).not.toContain('plan.planNo')
+    expect(source.match(/<DataTable[^>]*\bstripe\b/g)).toHaveLength(2)
+    expect(source).toContain('<span>柜次号</span>')
+    expect(source).toContain('<span>集装箱号</span>')
+    expect(source).not.toContain('当前柜号')
+  })
+
+  it('keeps the package count editor inside its table cell without overflow ellipsis', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/pages/SmartLoadingWorkbenchView.vue'), 'utf8')
+    expect(source).toContain('<div v-else class="package-count-editor"><el-input-number')
+    expect(source).toContain(':controls="false"')
+    expect(source).toContain('@blur="adjust(row)" @keyup.enter="adjust(row)"')
+    expect(source).not.toContain('<Save')
+    expect(source).toContain('.workbench :deep(.package-count-editor .el-input-number) { width: 100%; min-width: 0; }')
+  })
+
+  it('aggregates a two-order group and calls only the atomic whole-group assignment', async () => {
+    vi.mocked(listSmartLoadingCandidates).mockResolvedValue(candidatePage([{
+      ...candidate, inboundId: '201', orderId: '301', inboundCode: 'IN-201', availablePackageCount: 12, availableVolumeCbm: 2.4, coLoadGroupId: '9007199254740999', groupNo: 'CLG-9007199254740999', memberCount: 3, groupTotalBoxes: 12, locked: false, blockReason: null,
+      groupMembers: [
+        { accountId: '1', inboundId: '201', orderId: '301', orderNo: 'ORD-1', inboundCode: 'IN-201', customerName: '示例企业', availablePackageCount: 4, orderStatusSnapshot: 'WAIT_SPLIT', expectedArrivalAt: null },
+        { accountId: '1', inboundId: '203', orderId: '301', orderNo: 'ORD-1', inboundCode: 'IN-203', customerName: '示例企业', availablePackageCount: 2, orderStatusSnapshot: 'WAIT_SPLIT', expectedArrivalAt: null },
+        { accountId: '2', inboundId: '202', orderId: '302', orderNo: 'ORD-2', inboundCode: 'IN-202', customerName: '另一企业', availablePackageCount: 6, orderStatusSnapshot: 'WAIT_SPLIT', expectedArrivalAt: null },
+      ],
+    }]))
+    vi.mocked(assignSmartLoadingGroup).mockResolvedValue(planResponse)
+    const router = createRouter({ history: createMemoryHistory(), routes: [{ path: '/container-loading/:containerId/smart-loading', component: SmartLoadingWorkbenchView }] })
+    await router.push(`/container-loading/${container.id}/smart-loading`); await router.isReady()
+    const wrapper = mount(SmartLoadingWorkbenchView, { attachTo: document.body, global: { plugins: [ElementPlus, router] } })
+    await flushPromises()
+    expect(wrapper.text()).toContain('CLG-9007199254740999 · 2 票')
+    expect(wrapper.text()).toContain('3 个入仓片段')
+    expect(wrapper.text()).toContain('ORD-1：IN-201、IN-203')
+    expect(wrapper.text()).toContain('整组 12 箱')
+    expect(wrapper.findAll('.el-table__body-wrapper button').filter((button) => button.text() === '加入')).toHaveLength(1)
+    await wrapper.findAll('.el-table__body-wrapper button').find((button) => button.text() === '加入')!.trigger('click')
+    await flushPromises()
+    ;([...document.body.querySelectorAll('button')].find((button) => button.textContent?.includes('确认整组分配')) as HTMLButtonElement).click()
+    await flushPromises()
+    expect(assignSmartLoadingGroup).toHaveBeenCalledWith(planResponse.id, '201', planResponse.version)
+    expect(assignSmartLoadingItem).not.toHaveBeenCalled()
+    wrapper.unmount()
+  })
+
+  it('shows an exact three-member group block and prevents individual assignment', async () => {
+    const members = ['401', '402', '403'].map((inboundId, index) => ({ accountId: `${index + 1}`, inboundId, orderId: `5${index}`, orderNo: `ORD-${index}`, inboundCode: `IN-${inboundId}`, customerName: `客户${index}`, availablePackageCount: 6, orderStatusSnapshot: 'WAIT_SPLIT', expectedArrivalAt: null }))
+    vi.mocked(listSmartLoadingCandidates).mockResolvedValue(candidatePage([{
+      ...candidate, inboundId: '401', orderId: '50', inboundCode: 'IN-401', availablePackageCount: 18, coLoadGroupId: '9900', groupNo: 'CLG-9900',
+      memberCount: 3, groupTotalBoxes: 18, locked: false, blockReason: '同柜不可拆组成员候选不齐，缺少 1 票', groupMembers: members,
+    }]))
+    const router = createRouter({ history: createMemoryHistory(), routes: [{ path: '/container-loading/:containerId/smart-loading', component: SmartLoadingWorkbenchView }] })
+    await router.push(`/container-loading/${container.id}/smart-loading`); await router.isReady()
+    const wrapper = mount(SmartLoadingWorkbenchView, { global: { plugins: [ElementPlus, router] } })
+    await flushPromises()
+    expect(wrapper.text()).toContain('CLG-9900 · 3 票')
+    expect(wrapper.text()).toContain('同柜不可拆组成员候选不齐，缺少 1 票')
+    const button = wrapper.findAll('.el-table__body-wrapper button').find((item) => item.text() === '加入')!
+    expect(button.attributes('disabled')).toBeDefined()
+    expect(wrapper.text()).not.toContain('本次计划装柜箱数')
+  })
+
+  it('keeps an ordinary ungrouped inbound on the existing partial-count assignment', async () => {
+    vi.mocked(assignSmartLoadingItem).mockResolvedValue(planResponse)
+    const router = createRouter({ history: createMemoryHistory(), routes: [{ path: '/container-loading/:containerId/smart-loading', component: SmartLoadingWorkbenchView }] })
+    await router.push(`/container-loading/${container.id}/smart-loading`); await router.isReady()
+    const wrapper = mount(SmartLoadingWorkbenchView, { attachTo: document.body, global: { plugins: [ElementPlus, router] } })
+    await flushPromises()
+    await wrapper.find('.el-table__body-wrapper button').trigger('click')
+    await flushPromises()
+    expect(document.body.textContent).toContain('本次计划装柜箱数')
+    ;([...document.body.querySelectorAll('button')].find((button) => button.textContent?.trim() === '确认分配') as HTMLButtonElement).click()
+    await flushPromises()
+    expect(assignSmartLoadingItem).toHaveBeenCalledWith(planResponse.id, { inboundId: '2', packageCount: 1, expectedVersion: planResponse.version })
+    expect(assignSmartLoadingGroup).not.toHaveBeenCalled()
+    wrapper.unmount()
+  })
+
+  it('assigns a sealed pallet atomically without a package-count input', async () => {
+    vi.mocked(listSmartLoadingCandidates).mockResolvedValue(candidatePage([{
+      ...candidate, unitType: 'SEALED_PALLET', palletId: '9007199254740998', palletNo: 'DP-260908-0001',
+      indivisible: true, availablePackageCount: 12,
+    }]))
+    vi.mocked(assignSmartLoadingPallet).mockResolvedValue(planResponse)
+    const router = createRouter({ history: createMemoryHistory(), routes: [{ path: '/container-loading/:containerId/smart-loading', component: SmartLoadingWorkbenchView }] })
+    await router.push(`/container-loading/${container.id}/smart-loading`); await router.isReady()
+    const wrapper = mount(SmartLoadingWorkbenchView, { attachTo: document.body, global: { plugins: [ElementPlus, router] } })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('DP-260908-0001')
+    await wrapper.find('.el-table__body-wrapper button').trigger('click')
+    await flushPromises()
+    expect(document.body.textContent).toContain('不可拆分单元整托加入')
+    expect(document.body.textContent).not.toContain('本次计划装柜箱数')
+    ;([...document.body.querySelectorAll('button')].find((button) => button.textContent?.trim() === '确认整托分配') as HTMLButtonElement).click()
+    await flushPromises()
+
+    expect(assignSmartLoadingPallet).toHaveBeenCalledWith(planResponse.id, { palletId: '9007199254740998', expectedVersion: planResponse.version })
+    expect(assignSmartLoadingItem).not.toHaveBeenCalled()
+    wrapper.unmount()
+  })
+
+})
diff --git a/src/modules/container-loading/pages/SmartLoadingWorkbenchView.vue b/src/modules/container-loading/pages/SmartLoadingWorkbenchView.vue
new file mode 100644
index 00000000..65bbfad8
--- /dev/null
+++ b/src/modules/container-loading/pages/SmartLoadingWorkbenchView.vue
@@ -0,0 +1,454 @@
+<script setup lang="ts">
+import SmartLoadingCandidateInbounds from '../components/SmartLoadingCandidateInbounds.vue'
+import '@/styles/adminDensity.css'
+import { computed, onMounted, reactive, ref } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { ArrowLeft, ListChecks, RefreshCw, Sparkles } from '@lucide/vue'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import LineClampText from '@/shared/components/LineClampText.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import {
+  adjustSmartLoadingItem, assignSmartLoadingGroup, assignSmartLoadingItem, assignSmartLoadingPallet, getContainer,
+  getSmartLoadingPlanByBooking, listSmartLoadingCandidates,
+  recommendSmartLoading, removeSmartLoadingGroup, removeSmartLoadingItem,
+} from '../api/platformContainerLoading'
+import type { ContainerBookingResource, SmartLoadingCandidate, SmartLoadingCandidateGroupMember, SmartLoadingPlan } from '../types'
+import { groupSmartLoadingItems, type SmartLoadingInboundItem } from '../smartLoadingItems'
+import { loadSmartLoadingPlanCoLoadGroups, type SmartLoadingPlanCoLoadGroup } from '../smartLoadingPlanGroups'
+import { getSmartLoadingChannelGroup } from '../smartLoadingChannelGroups'
+
+const route = useRoute()
+const router = useRouter()
+const access = useAccessPreviewStore()
+const containerId = computed(() => String(route.params.containerId || ''))
+const container = ref<ContainerBookingResource | null>(null)
+const plan = ref<SmartLoadingPlan | null>(null)
+const candidates = ref<SmartLoadingCandidate[]>([])
+const loading = ref(false)
+const mutating = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const mutationError = ref<ApiErrorDetails | null>(null)
+const noDraft = ref(false)
+const editingQuantityId = ref('')
+const assignOpen = ref(false)
+const selectedCandidate = ref<SmartLoadingCandidateRow | null>(null)
+const assignForm = reactive({ packageCount: 1 })
+const quantityDrafts = reactive<Record<string, number>>({})
+const planGroupsByInboundId = ref(new Map<string, SmartLoadingPlanCoLoadGroup>())
+
+const canAssign = computed(() => access.can('platform:firstleg:smart-loading:assign'))
+const canDelete = computed(() => access.can('platform:firstleg:smart-loading:delete'))
+const canViewLoadingList = computed(() => access.can('platform:firstleg:loading-list:list'))
+const editable = computed(() => plan.value?.canEdit === true)
+const assignable = computed(() => plan.value?.canAssign === true)
+const assignedInboundIds = computed(() => new Set((plan.value?.items || []).map((item) => item.inboundId)))
+const assignedPalletIds = computed(() => new Set((plan.value?.items || []).map((item) => item.palletId).filter(Boolean)))
+type SmartLoadingCandidateRow = SmartLoadingCandidate & { memberInboundIds: string[]; memberInboundCodes: string[]; memberOrderSummaries: string[]; memberOrderCount: number; inboundFragmentCount: number }
+function memberOrderSummaries<T extends { orderId: string; orderNo?: string | null; inboundCode?: string | null }>(members: T[]) {
+  const orders = new Map<string, { label: string; inboundCodes: string[] }>()
+  for (const member of members) {
+    const current = orders.get(member.orderId) || { label: member.orderNo || '订单编码待补充', inboundCodes: [] }
+    const inboundCode = member.inboundCode || '入仓码暂缺'
+    if (!current.inboundCodes.includes(inboundCode)) current.inboundCodes.push(inboundCode)
+    orders.set(member.orderId, current)
+  }
+  return [...orders.values()].map((order) => `${order.label}：${order.inboundCodes.join('、')}`)
+}
+function groupMemberLabel(group: SmartLoadingPlanCoLoadGroup) {
+  return group.inboundFragmentCount === group.memberOrderCount
+    ? `${group.memberOrderCount} 票`
+    : `${group.memberOrderCount} 票 · ${group.inboundFragmentCount} 个入仓片段`
+}
+const displayedCandidates = computed<SmartLoadingCandidateRow[]>(() => {
+  return candidates.value.map((candidate) => {
+    const members: Array<{ inboundId: string | null; orderId: string; orderNo?: string | null; inboundCode?: string | null }> = candidate.groupMembers.length
+      ? candidate.groupMembers
+      : [candidate]
+    return {
+      ...candidate,
+      memberInboundIds: members.map((member) => member.inboundId).filter((id): id is string => Boolean(id)),
+      memberInboundCodes: members.map((member) => member.inboundCode || '入仓码暂缺'),
+      memberOrderSummaries: memberOrderSummaries(members),
+      memberOrderCount: new Set(members.map((member) => member.orderId)).size,
+      inboundFragmentCount: Number(candidate.memberCount || members.length),
+    }
+  })
+})
+const planPalletMembersByPalletId = computed(() => new Map(
+  (plan.value?.palletMembers || []).map((entry) => [entry.palletId, entry.members]),
+))
+type SmartLoadingPlanRow = SmartLoadingInboundItem & { coLoadGroup: SmartLoadingPlanCoLoadGroup | null; palletMembers: SmartLoadingCandidateGroupMember[]; memberInboundCodes: string[]; memberOrderSummaries: string[] }
+const displayedPlanItems = computed<SmartLoadingPlanRow[]>(() => {
+  const inboundRows = groupSmartLoadingItems(plan.value?.items || [])
+  const result: SmartLoadingPlanRow[] = []
+  const grouped = new Map<string, SmartLoadingInboundItem[]>()
+  for (const row of inboundRows) {
+    const group = planGroupsByInboundId.value.get(row.inboundId)
+    if (!group) {
+      result.push({ ...row, coLoadGroup: null, palletMembers: row.palletId ? planPalletMembersByPalletId.value.get(row.palletId) || [] : [], memberInboundCodes: [row.inboundCode || '入仓码暂缺'], memberOrderSummaries: memberOrderSummaries([row]) })
+      continue
+    }
+    grouped.set(group.groupId, [...(grouped.get(group.groupId) || []), row])
+  }
+  for (const rows of grouped.values()) {
+    const first = rows[0]
+    const group = planGroupsByInboundId.value.get(first.inboundId)!
+    result.push({
+      ...first,
+      id: `coload:${group.groupId}`,
+      inboundCode: rows.map((row) => row.inboundCode).filter(Boolean).join('、'),
+      customerName: [...new Set(rows.map((row) => row.customerName).filter(Boolean))].join('、'),
+      skuCode: [...new Set(rows.map((row) => row.skuCode).filter(Boolean))].join('、'),
+      productNameZh: [...new Set(rows.map((row) => row.productNameZh).filter(Boolean))].join('、'),
+      packageCount: rows.reduce((sum, row) => sum + row.packageCount, 0),
+      productQuantity: rows.reduce((sum, row) => sum + Number(row.productQuantity || 0), 0),
+      grossWeightKg: rows.reduce((sum, row) => sum + Number(row.grossWeightKg || 0), 0),
+      volumeCbm: rows.reduce((sum, row) => sum + Number(row.volumeCbm || 0), 0),
+      pickedPackageCount: rows.reduce((sum, row) => sum + row.pickedPackageCount, 0),
+      minPackageCount: rows.reduce((sum, row) => sum + row.minPackageCount, 0),
+      canAdjust: false,
+      canRemove: rows.every((row) => row.canRemove),
+      sourceItems: rows.flatMap((row) => row.sourceItems),
+      detailCount: rows.reduce((sum, row) => sum + row.detailCount, 0),
+      coLoadGroup: group,
+      palletMembers: [],
+      memberInboundCodes: rows.map((row) => row.inboundCode || '入仓码暂缺'),
+      memberOrderSummaries: memberOrderSummaries(rows),
+    })
+  }
+  return result
+})
+const totalVolume = computed(() => (plan.value?.items || []).reduce((sum, item) => sum + Number(item.volumeCbm || 0), 0))
+const totalWeight = computed(() => (plan.value?.items || []).reduce((sum, item) => sum + Number(item.grossWeightKg || 0), 0))
+const volumeLimit = computed(() => Number(container.value?.capacityCbm || 0) * 1.5)
+const weightLimit = computed(() => Number(container.value?.maxWeightKg || 0) * 1.5)
+const volumePercent = computed(() => volumeLimit.value ? totalVolume.value / volumeLimit.value * 100 : 0)
+const weightPercent = computed(() => weightLimit.value ? totalWeight.value / weightLimit.value * 100 : 0)
+const displayedVolumePercent = computed(() => percentage(volumePercent.value))
+const displayedWeightPercent = computed(() => percentage(weightPercent.value))
+
+const itemColumns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 90, fixed: 'left', slotName: 'actions' },
+  { key: 'sequence', prop: 'loadSequence', label: '顺序', width: 75 },
+  { key: 'order', label: '入仓码', minWidth: 190, slotName: 'order' },
+  { key: 'palletNo', prop: 'palletNo', label: '托盘号', minWidth: 150, showOverflowTooltip: true },
+  { key: 'coLoadGroup', label: '装柜规则', minWidth: 170, slotName: 'coLoadGroup' },
+  { key: 'customerName', prop: 'customerName', label: '客户', minWidth: 150, slotName: 'customerName' },
+  { key: 'goods', label: '货物', minWidth: 190, slotName: 'goods' },
+  { key: 'packageCount', label: '分配箱数', width: 150, slotName: 'packageCount' },
+  { key: 'volumeCbm', label: '体积', width: 120, slotName: 'volume' },
+  { key: 'grossWeightKg', label: '毛重', width: 130, slotName: 'weight' },
+]
+const candidateColumns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 110, fixed: 'left', slotName: 'actions' },
+  { key: 'inboundCode', label: '入仓码', minWidth: 220, fixed: 'left', slotName: 'candidateInbounds' },
+  { key: 'palletNo', prop: 'palletNo', label: '托盘号', minWidth: 150, showOverflowTooltip: true },
+  { key: 'coLoadGroup', label: '装柜规则', minWidth: 170, slotName: 'coLoadGroup' },
+  { key: 'customerName', prop: 'customerName', label: '客户', minWidth: 150, slotName: 'customerName' },
+  { key: 'goodsSummary', prop: 'goodsSummary', label: '货物摘要', minWidth: 180, slotName: 'goodsSummary' },
+  { key: 'availablePackageCount', prop: 'availablePackageCount', label: '箱数', width: 90 },
+  { key: 'cartonIdentityStatus', label: '箱号归属', width: 110, slotName: 'cartonIdentityStatus' },
+  { key: 'averageUnitVolumeCbm', label: '单位体积', width: 120, slotName: 'averageUnitVolume' },
+  { key: 'unitGrossWeightKg', label: '单位毛重', width: 120, slotName: 'unitGrossWeight' },
+]
+
+function formatNumber(value: number, digits = 3) { return Number.isFinite(value) ? value.toLocaleString('zh-CN', { maximumFractionDigits: digits }) : '0' }
+function percentage(value: number) { return Number.isFinite(value) ? Number(Math.max(value, 0).toFixed(2)) : 0 }
+function candidateRow(source: object) { return source as SmartLoadingCandidateRow }
+function itemRow(source: object) { return source as SmartLoadingInboundItem }
+function adjustmentMax(source: object) {
+  const item = itemRow(source)
+  return Math.max(item.minPackageCount, item.totalPackageCount || item.packageCount)
+}
+function startQuantityEdit(source: object) {
+  const item = itemRow(source)
+  quantityDrafts[item.id] = item.packageCount
+  editingQuantityId.value = item.id
+}
+function explainCandidate(source: object) {
+  const candidate = candidateRow(source)
+  const volume = Number(candidate.averageUnitVolumeCbm || 0)
+  const weight = Number(candidate.unitGrossWeightKg || 0)
+  const volumeRoom = volumeLimit.value ? Math.floor(Math.max(volumeLimit.value - totalVolume.value, 0) / Math.max(volume, 0.000001)) : candidate.availablePackageCount
+  const weightRoom = weightLimit.value ? Math.floor(Math.max(weightLimit.value - totalWeight.value, 0) / Math.max(weight, 0.000001)) : candidate.availablePackageCount
+  return `按 150% 上限，当前最多可装 ${Math.max(Math.min(candidate.availablePackageCount, volumeRoom, weightRoom), 0)} 箱`
+}
+function displayCabinetNo(value: ContainerBookingResource | null | undefined) {
+  if (!value) return '待生成'
+  const cabinetNo = String(value.cabinetNo || '').trim()
+  return /^\d{15,}$/.test(cabinetNo) ? '待生成' : cabinetNo || '待生成'
+}
+function displayContainerNo(value: ContainerBookingResource | null | undefined) {
+  const containerNo = String(value?.containerNo || '').trim()
+  return containerNo && !/^(?:MAN|SPLIT)-/i.test(containerNo) ? containerNo : '待补录'
+}
+function syncDrafts(preserved: Record<string, number> = {}) {
+  for (const key of Object.keys(quantityDrafts)) delete quantityDrafts[key]
+  for (const item of displayedPlanItems.value) quantityDrafts[item.id] = preserved[item.id] ?? item.packageCount
+}
+function acceptPlan(next: SmartLoadingPlan, preserved: Record<string, number> = {}) { plan.value = next; noDraft.value = false; syncDrafts(preserved) }
+async function acceptPlanWithGroups(next: SmartLoadingPlan, preserved: Record<string, number> = {}) {
+  acceptPlan(next, preserved)
+  planGroupsByInboundId.value = await loadSmartLoadingPlanCoLoadGroups(next)
+  syncDrafts(preserved)
+}
+
+async function load() {
+  loading.value = true; loadError.value = null; noDraft.value = false
+  planGroupsByInboundId.value = new Map()
+  try {
+    container.value = await getContainer(containerId.value)
+    if (container.value.planStatus === 'COMPLETED') {
+      plan.value = null
+      candidates.value = []
+      return
+    }
+    try { await acceptPlanWithGroups(await getSmartLoadingPlanByBooking(containerId.value)) }
+    catch (error) {
+      const detail = getApiErrorDetails(error)
+      if (detail.code === 'A0404') { plan.value = null; noDraft.value = true }
+      else throw error
+    }
+    const channelGroup = getSmartLoadingChannelGroup(container.value.channelGroupCode)
+    candidates.value = plan.value?.canAssign && channelGroup
+      ? (await listSmartLoadingCandidates({ channelGroupCodes: [channelGroup.code], warehouseId: container.value.warehouseId, page: 1, size: 200 })).records
+      : []
+  } catch (error) { loadError.value = getApiErrorDetails(error, '智能装柜工作台加载失败') }
+  finally { loading.value = false }
+}
+function openOperationalList() {
+  if (!container.value || container.value.planStatus === 'EDITING') return
+  void router.push({
+    name: container.value.planStatus === 'LOADING' ? 'loading-plans' : 'domestic-container-detail',
+    params: container.value.planStatus === 'COMPLETED' ? { containerId: container.value.id } : undefined,
+    query: container.value.planStatus === 'COMPLETED' ? { tab: 'loading-list' } : { planId: container.value.planId || undefined, warehouseId: container.value.warehouseId },
+  })
+}
+function openAssign(source: object) {
+  const candidate = candidateRow(source)
+  if (candidateBlocked(candidate)) return
+  selectedCandidate.value = candidate
+  assignForm.packageCount = candidate.coLoadGroupId ? Number(candidate.groupTotalBoxes || candidate.availablePackageCount) : Math.min(candidate.availablePackageCount, 1)
+  assignOpen.value = true
+}
+async function assign() {
+  const currentPlan = plan.value
+  const selected = selectedCandidate.value
+  const inboundId = selected?.inboundId
+  if (!currentPlan || !selected || !inboundId) return
+  if (selected.unitType !== 'SEALED_PALLET' && assignForm.packageCount < 1) return
+  if (selected.coLoadGroupId && (selected.blockReason || selected.locked)) return
+  mutating.value = true
+  mutationError.value = null
+  try {
+    const next = selected.unitType === 'SEALED_PALLET' && selected.palletId
+      ? await assignSmartLoadingPallet(currentPlan.id, { palletId: selected.palletId, expectedVersion: currentPlan.version })
+      : selected.coLoadGroupId
+      ? await assignSmartLoadingGroup(currentPlan.id, inboundId, currentPlan.version)
+      : await assignSmartLoadingItem(currentPlan.id, { inboundId, packageCount: assignForm.packageCount, expectedVersion: currentPlan.version })
+    await acceptPlanWithGroups(next)
+    assignOpen.value = false
+    ElMessage.success(selected.coLoadGroupId ? `同柜不可拆组 ${selected.groupNo} 已整组分配` : '货物已分配')
+  } catch (error) { await handleMutationError(error, '分配失败') }
+  finally { mutating.value = false }
+}
+function candidateBlocked(candidate: SmartLoadingCandidateRow) {
+  if (candidate.unitType === 'SEALED_PALLET') {
+    return Boolean(candidate.blockReason) || candidate.locked === true || !candidate.palletId
+      || !candidate.indivisible || assignedPalletIds.value.has(candidate.palletId)
+  }
+  return Boolean(candidate.blockReason) || candidate.locked === true
+    || !candidate.inboundId
+    || candidate.memberInboundIds.some((inboundId) => assignedInboundIds.value.has(inboundId))
+    || candidate.availablePackageCount < 1
+}
+async function recommend() {
+  if (!plan.value) return
+  mutating.value = true
+  mutationError.value = null
+  try {
+    try {
+      await acceptPlanWithGroups(await recommendSmartLoading(plan.value.id, plan.value.version))
+    } catch (error) {
+      const details = getApiErrorDetails(error, '智能推荐失败')
+      if (details.code !== 'A0409' || !/(版本|并发|已被修改|已变化)/.test(details.message)) throw error
+      await load()
+      if (!plan.value) throw error
+      await acceptPlanWithGroups(await recommendSmartLoading(plan.value.id, plan.value.version))
+    }
+    ElMessage.success('智能建议已生成，请人工核对明细')
+  }
+  catch (error) { await handleMutationError(error, '智能推荐失败') }
+  finally { mutating.value = false }
+}
+async function adjust(source: object) {
+  const item = itemRow(source)
+  if (item.unitType === 'SEALED_PALLET') return
+  if (!plan.value || mutating.value) return
+  const count = Number(quantityDrafts[item.id])
+  if (count === item.packageCount) return
+  if (!Number.isInteger(count) || count < item.minPackageCount) { ElMessage.warning(`分配箱数不能低于已拣下限 ${item.minPackageCount} 箱`); return }
+  mutating.value = true
+  mutationError.value = null
+  try { await acceptPlanWithGroups(await adjustSmartLoadingItem(plan.value.id, item.id, count, plan.value.version, item.version)); editingQuantityId.value = ''; ElMessage.success('箱数已调整') }
+  catch (error) { await handleMutationError(error, '调整失败') }
+  finally { mutating.value = false }
+}
+async function remove(source: object) {
+  const item = itemRow(source)
+  if (!plan.value || !item.canRemove) return
+  const row = source as SmartLoadingPlanRow
+  const message = row.coLoadGroup
+    ? `确认整组移除 ${row.coLoadGroup.groupNo}（${groupMemberLabel(row.coLoadGroup)}、${row.packageCount} 箱）吗？组内所有入仓片段将联动移除。`
+    : `确认从计划移除入仓码“${item.inboundCode || '—'}”的 ${item.packageCount} 箱吗？`
+  await ElMessageBox.confirm(message, row.coLoadGroup ? '移除同柜不可拆组' : '移除装柜明细', { customClass: 'admin-density-confirm', type: 'warning', confirmButtonText: row.coLoadGroup ? '移除整组' : '移除', cancelButtonText: '取消' }).catch(() => false).then(async (confirmed) => {
+    if (!confirmed || !plan.value) return
+    mutating.value = true
+    mutationError.value = null
+    try {
+      if (row.coLoadGroup) {
+        await acceptPlanWithGroups(await removeSmartLoadingGroup(plan.value!.id, row.coLoadGroup.groupId, plan.value!.version))
+        await load()
+        ElMessage.success(`同柜不可拆组 ${row.coLoadGroup.groupNo} 已整组移除`)
+        return
+      }
+      let current = plan.value!
+      for (const original of item.sourceItems) {
+        const currentItem = current.items.find((value) => value.id === original.id)
+        if (!currentItem) continue
+        current = await removeSmartLoadingItem(current.id, currentItem.id, current.version, currentItem.version)
+        await acceptPlanWithGroups(current)
+      }
+      await load()
+      ElMessage.success('该入仓码已从装柜方案移除')
+    }
+    catch (error) { await handleMutationError(error, '移除失败', true) }
+    finally { mutating.value = false }
+  })
+}
+async function handleMutationError(error: unknown, fallback: string, pickingConflict = false) {
+  const details = getApiErrorDetails(error, fallback)
+  if (details.code === 'A0409') {
+    const preserved = { ...quantityDrafts }
+    await load()
+    syncDrafts(preserved)
+  }
+  const pickingMessage = pickingConflict && details.code === 'A0409' && details.message.includes('拣货')
+    ? '该订单在拣货中不许删除'
+    : null
+  mutationError.value = { ...details, message: pickingMessage || details.message || (details.code === 'A0409' ? '计划或 PDA 明细已变化，已刷新最新版本并保留本次输入，请重新操作' : details.message) }
+  ElMessage.error(mutationError.value.message)
+}
+
+onMounted(load)
+</script>
+
+<template>
+  <AdminPage class="admin-density">
+  <section class="business-page workbench">
+    <section class="surface-panel workbench-command-bar" aria-label="装柜作业摘要">
+      <div class="workbench-identities">
+        <div class="workbench-identity">
+          <span>柜次号</span>
+          <strong>{{ loading ? '正在加载' : displayCabinetNo(container) }}</strong>
+        </div>
+        <div class="workbench-identity">
+          <span>集装箱号</span>
+          <strong>{{ loading ? '正在加载' : displayContainerNo(container) }}</strong>
+        </div>
+      </div>
+      <div class="header-actions">
+        <el-button link class="density-back" aria-label="返回货柜列表" @click="router.back()"><ArrowLeft :size="18" />返回</el-button>
+        <el-tooltip content="刷新" placement="top"><el-button :loading="loading" aria-label="刷新智能装柜" @click="load"><RefreshCw :size="16" /></el-button></el-tooltip>
+        <el-button v-if="canAssign && assignable && plan?.status === 'EDITING'" type="primary" plain :loading="mutating" @click="recommend"><Sparkles :size="16" />智能推荐</el-button>
+      </div>
+    </section>
+    <LoadErrorState v-if="loadError" title="智能装柜加载失败" :message="loadError.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="loadError" /></template></LoadErrorState>
+    <template v-else>
+      <LoadErrorState v-if="mutationError" title="装柜操作失败" :message="mutationError.message" compact retry-text="刷新最新计划" @retry="load"><template #details><ApiErrorMeta :details="mutationError" /></template></LoadErrorState>
+      <section v-if="container?.planStatus === 'COMPLETED'" class="readonly-status-card" aria-label="装柜完成状态">
+        <el-tag type="success">装柜完成</el-tag>
+        <strong>该柜次已完成装柜</strong>
+        <p>智能装柜方案已锁定，不能继续调整。请进入装柜清单查看完整记录。</p>
+        <el-button v-if="canViewLoadingList" type="primary" @click="openOperationalList"><ListChecks :size="16" />查看装柜清单</el-button>
+      </section>
+      <template v-else>
+      <section v-if="container" class="summary-band"><div><span>柜型</span><strong>{{ container.containerType }}</strong></div><div><span>装柜仓库</span><strong>{{ container.warehouseName || '—' }}</strong></div></section>
+      <section v-if="container" class="capacity-grid"><div><div class="meter-title"><span>体积占用（含 150% 上限）</span><strong>{{ formatNumber(totalVolume) }} / {{ formatNumber(volumeLimit) }} m³</strong></div><el-progress :percentage="Math.min(displayedVolumePercent,100)" :status="volumePercent > 100 ? 'exception' : undefined" /></div><div><div class="meter-title"><span>重量占用（含 150% 上限）</span><strong>{{ formatNumber(totalWeight,1) }} / {{ formatNumber(weightLimit,1) }} kg</strong></div><el-progress :percentage="Math.min(displayedWeightPercent,100)" :status="weightPercent > 100 ? 'exception' : undefined" /></div></section>
+      <el-empty v-if="noDraft" description="该柜次缺少自动生成的预装计划，请刷新后重试" />
+      <template v-else-if="plan">
+        <el-alert v-if="plan.status === 'LOADING' && plan.canEdit" type="warning" :closable="false" show-icon title="已下发 PDA，仍可维护未完成的装柜明细" description="新增、增加或移除未拣明细会刷新 PDA 明细与版本；PDA 端需要刷新后继续操作。" />
+        <el-alert v-else-if="!plan.canEdit" :type="plan.finalCompletionStatus === 'COMPLETED' ? 'success' : 'info'" :closable="false" show-icon :title="plan.finalCompletionStatus === 'IN_PROGRESS' ? '正在最终确认，装柜方案暂时只读' : plan.finalCompletionStatus === 'COMPLETED' ? '装柜已完成，方案永久只读' : '当前装柜方案只读'" :description="plan.blockedReason || '请刷新计划获取最新作业状态。'" />
+        <DataTable :data="displayedPlanItems" :columns="itemColumns" :loading="loading || mutating" stripe preference-key="smart-loading-items" column-settings-mode="hide" empty-text="暂无已分配货物">
+          <template #toolbar-start><div><h2>{{ displayContainerNo(container) }} 装柜方案</h2><p>智能建议必须经人工核对。</p></div></template>
+          <template #actions="{ row }"><div class="row-actions density-actions"><el-button data-tone="danger" class="density-action" v-if="canDelete && editable && row.canRemove" size="small" type="danger" plain @click="remove(row)">删除</el-button></div></template>
+          <template #order="{ row }"><SmartLoadingCandidateInbounds :members="row.palletMembers" :sealed-pallet="row.unitType === 'SEALED_PALLET'" :fallback-inbound-code="row.inboundCode" /></template>
+          <template #customerName="{ row }"><LineClampText :content="row.customerName" /></template>
+          <template #coLoadGroup="{ row }"><details v-if="row.coLoadGroup" class="candidate-group"><summary>整组加入 · 不可拆</summary><el-tag size="small" type="warning"><LineClampText :content="`${row.coLoadGroup.groupNo} · ${groupMemberLabel(row.coLoadGroup)}`" /></el-tag><LineClampText :content="row.memberOrderSummaries.join('；')" /><LineClampText :content="`全部入仓片段联动，固定 ${row.coLoadGroup.fullPackageCount} 箱`" /></details><LineClampText v-else :content="row.unitType === 'SEALED_PALLET' ? '整托加入 · 不可拆' : '按箱加入'" /></template>
+          <template #goods="{ row }"><div class="goods-cell"><LineClampText :content="row.productNameZh || '未命名货物'" /><LineClampText class="goods-cell__sku" :content="row.skuCode || '无 SKU'" /></div></template>
+          <template #packageCount="{ row }"><LineClampText v-if="row.unitType === 'SEALED_PALLET'" :content="`${row.packageCount} 箱（整托固定）`" /><LineClampText v-else-if="row.coLoadGroup" :content="`${row.packageCount} 箱（整组固定）`" /><div v-else class="package-count-editor"><el-input-number v-if="editingQuantityId === row.id" v-model="quantityDrafts[row.id]" :min="row.minPackageCount" :max="adjustmentMax(row)" :step="1" :controls="false" :disabled="mutating" placeholder="请输入使用箱数" @blur="adjust(row)" @keyup.enter="adjust(row)" /><div v-else class="package-count-summary"><div class="package-count-used"><strong>使用：{{ row.packageCount }}</strong><el-button v-if="canAssign && editable && row.canAdjust" class="density-action" :disabled="mutating" aria-label="调整箱数" @click="startQuantityEdit(row)">调整</el-button></div><small v-if="(row.remainingPackageCount ?? 0) > 0">未用：{{ row.remainingPackageCount }}</small></div><LineClampText v-if="row.detailCount > 1 && editable" :content="`含 ${row.detailCount} 个规格，需删除后重加`" /><LineClampText v-if="row.pickedPackageCount > 0" :content="`已拣 ${row.pickedPackageCount} 箱`" /></div></template>
+          <template #volume="{ row }">{{ formatNumber(Number(row.volumeCbm || 0)) }} m³</template><template #weight="{ row }">{{ formatNumber(Number(row.grossWeightKg || 0),1) }} kg</template>
+        </DataTable>
+        <DataTable :data="displayedCandidates" :columns="candidateColumns" :loading="loading || mutating" stripe preference-key="smart-loading-candidates" column-settings-mode="hide" empty-text="当前仓库暂无可装柜货物">
+          <template #toolbar-start><div><h2>候选货物</h2><p>系统基于装柜仓库、物流渠道、可用箱数及 150% 容量上限校验。</p></div></template>
+          <template #actions="{ row }"><el-button data-tone="primary" class="density-action" v-if="canAssign && assignable" size="small" type="primary" plain :disabled="candidateBlocked(row as SmartLoadingCandidateRow)" @click="openAssign(row)">加入</el-button></template>
+          <template #candidateInbounds="{ row }"><SmartLoadingCandidateInbounds :candidate="row as SmartLoadingCandidate" /></template>
+          <template #customerName="{ row }"><LineClampText :content="row.customerName" /></template>
+          <template #goodsSummary="{ row }"><LineClampText :content="row.goodsSummary || '—'" /></template>
+          <template #coLoadGroup="{ row }"><details v-if="row.coLoadGroupId" class="candidate-group"><summary>整组加入 · 不可拆</summary><el-tag size="small" type="warning"><LineClampText :content="`${row.groupNo} · ${row.memberOrderCount} 票 · ${row.inboundFragmentCount} 个入仓片段`" /></el-tag><LineClampText :content="row.memberOrderSummaries.join('；')" /><LineClampText :content="`整组 ${row.groupTotalBoxes} 箱，必须全量进入同一柜`" /><LineClampText v-if="row.blockReason" class="candidate-block" :content="row.blockReason" /><LineClampText v-else-if="row.locked" content="该组已锁定，不能重复分配" /></details><LineClampText v-else :content="row.unitType === 'SEALED_PALLET' ? '整托加入 · 不可拆' : '按箱加入'" /></template>
+          <template #averageUnitVolume="{ row }">{{ formatNumber(Number(row.averageUnitVolumeCbm || 0)) }} m³</template><template #unitGrossWeight="{ row }">{{ formatNumber(Number(row.unitGrossWeightKg || 0),1) }} kg</template>
+          <template #cartonIdentityStatus><el-tag size="small" type="info" effect="plain">未核验</el-tag></template>
+        </DataTable>
+      </template>
+      </template>
+    </template>
+    <AppDialog class="admin-density-dialog" v-model="assignOpen" :title="selectedCandidate?.unitType === 'SEALED_PALLET' ? '整托加入当前柜次' : selectedCandidate?.coLoadGroupId ? '整组加入当前柜次' : '按入仓码分配箱数'" :confirm-loading="mutating" :confirm-disabled="Boolean(selectedCandidate?.blockReason || selectedCandidate?.locked)" :confirm-text="selectedCandidate?.unitType === 'SEALED_PALLET' ? '确认整托分配' : selectedCandidate?.coLoadGroupId ? '确认整组分配' : '确认分配'" @confirm="assign"><div v-if="selectedCandidate" class="assign-dialog"><p><strong>{{ selectedCandidate.palletNo || selectedCandidate.groupNo || selectedCandidate.inboundCode || '入仓码暂缺' }}</strong></p><template v-if="selectedCandidate.coLoadGroupId"><p>组内 {{ selectedCandidate.memberOrderCount }} 票、{{ selectedCandidate.inboundFragmentCount }} 个入仓片段，共 {{ selectedCandidate.groupTotalBoxes }} 箱</p><p v-for="summary in selectedCandidate.memberOrderSummaries" :key="summary">{{ summary }}</p><el-alert :title="selectedCandidate.blockReason || '同柜且不可拆：全部订单及其入仓片段按完整箱数一次加入，不能部分输入或单独移除。'" :type="selectedCandidate.blockReason ? 'error' : 'warning'" :closable="false" /></template><template v-else-if="selectedCandidate.unitType === 'SEALED_PALLET'"><p>托盘号 {{ selectedCandidate.palletNo || '—' }} · 整托 {{ selectedCandidate.availablePackageCount }} 箱</p><SmartLoadingCandidateInbounds :candidate="selectedCandidate" /><el-alert title="该封托托盘将作为一个不可拆分单元整托加入；装柜阶段复用此托盘，不会重新生成工作托盘。" type="warning" :closable="false" /></template><template v-else><p>{{ selectedCandidate.goodsSummary || '货物摘要暂缺' }} · 可用 {{ selectedCandidate.availablePackageCount }} 箱</p><el-form class="density-form" label-position="top"><el-form-item label="本次计划装柜箱数" required><el-input-number v-model="assignForm.packageCount" :min="1" :max="selectedCandidate.availablePackageCount" :step="1" controls-position="right" placeholder="请输入本次分配箱数" /></el-form-item></el-form><el-alert :title="explainCandidate(selectedCandidate)" type="info" :closable="false" /><small>只记录数量，具体上柜箱号未核验。</small></template></div></AppDialog>
+  </section>
+  </AdminPage>
+</template>
+
+<style scoped>
+.workbench { display: grid; gap: var(--admin-space-5); min-width: 0; }
+.workbench-command-bar,.header-actions,.row-actions,.meter-title { display: flex; align-items: center; }
+.workbench-command-bar { justify-content: space-between; gap: var(--admin-space-5); padding: var(--admin-space-5) var(--admin-space-5); }
+.workbench-identities { display: flex; min-width: 0; align-items: center; gap: var(--admin-space-7); }
+.workbench-identity { display: grid; min-width: 0; gap: 3px; }
+.workbench-identity span { color: var(--cc-muted); font-size: var(--admin-font-caption); }
+.workbench-identity strong { font-size: var(--admin-font-title); overflow-wrap: anywhere; }
+.workbench h2,.workbench h2 + p { margin: 0; }
+.workbench h2 { font-size: var(--admin-font-section); }
+.workbench h2 + p,.workbench small { display: block; margin-top: var(--admin-space-1); color: var(--cc-muted); }
+.header-actions,.row-actions { flex-wrap: wrap; gap: var(--admin-space-3); }
+.header-actions :deep(.el-button + .el-button),.row-actions :deep(.el-button + .el-button) { margin-left: 0; }
+.summary-band { display: grid; grid-template-columns: repeat(2,minmax(0,1fr)); gap: 1px; border: 1px solid var(--cc-border); background: var(--cc-border); }
+.summary-band>div { display: grid; gap: 5px; padding: var(--admin-space-5); background: var(--admin-surface); }
+.summary-band span { color: var(--cc-muted); font-size: var(--admin-font-caption); }
+.capacity-grid { display: grid; grid-template-columns: repeat(2,minmax(0,1fr)); gap: var(--admin-space-5); padding: var(--admin-space-5); border: 1px solid var(--cc-border); border-radius: var(--admin-radius); background: var(--admin-surface); }
+.readonly-status-card { display: grid; justify-items: start; gap: var(--admin-space-4); padding: var(--admin-space-6); border: 1px solid var(--cc-border); border-radius: var(--admin-radius); background: var(--admin-surface); }
+.readonly-status-card strong { font-size: var(--admin-font-section); }
+.readonly-status-card p { margin: 0; color: var(--cc-muted); }
+.meter-title { justify-content: space-between; gap: var(--admin-space-5); margin-bottom: var(--admin-space-4); font-size: var(--admin-font-body); }
+.row-actions { min-width: 150px; }
+.goods-cell { display: grid; min-width: 0; gap: 2px; }
+.goods-cell :deep(.line-clamp-text) { width: 100%; font-weight: 600; }
+.goods-cell :deep(.goods-cell__sku.line-clamp-text) { color: var(--cc-muted); font-size: var(--admin-font-caption); font-weight: 400; }
+.package-count-editor { display: grid; min-width: 0; gap: var(--admin-space-1); }
+.package-count-summary { display: grid; gap: 3px; line-height: 1.35; }
+.package-count-used { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-2); }
+.package-count-summary strong { font-size: var(--admin-font-body); font-weight: 600; }
+.package-count-summary small { color: var(--cc-muted); font-size: var(--admin-font-caption); }
+.workbench :deep(.package-count-editor .el-input-number) { width: 100%; min-width: 0; }
+.assign-dialog p { margin: 0 0 var(--admin-space-4); }
+.assign-dialog :deep(.el-input-number) { width: 100%; }
+.candidate-group { display: grid; width: 100%; min-width: 0; gap: 3px; }
+.candidate-group :deep(.el-tag),.candidate-group :deep(.el-tag__content),.candidate-group :deep(.line-clamp-text) { max-width: 100%; min-width: 0; }
+.candidate-group :deep(.line-clamp-text) { width: 100%; color: var(--cc-muted); font-size: var(--admin-font-caption); }
+.candidate-group .candidate-block { color: var(--el-color-danger); }
+@media (max-width: 760px) { .workbench-command-bar,.header-actions { width: 100%; flex-direction: column; align-items: stretch; } .workbench-identities { flex-direction: column; align-items: stretch; gap: 10px; } .summary-band,.capacity-grid { grid-template-columns: 1fr; } .meter-title { align-items: flex-start; flex-direction: column; } .header-actions .el-button { min-height: 44px; margin-left: 0; } }
+</style>
diff --git a/src/modules/container-loading/routes.ts b/src/modules/container-loading/routes.ts
new file mode 100644
index 00000000..c7c45dd4
--- /dev/null
+++ b/src/modules/container-loading/routes.ts
@@ -0,0 +1,34 @@
+import type { RouteRecordRaw } from 'vue-router'
+
+export const containerLoadingRoutes = [
+  {
+    path: 'container-loading/domestic',
+    name: 'domestic-container-workbench',
+    component: () => import('./pages/DomesticContainersView.vue'),
+    meta: { title: '送柜报关', description: '管理国内送柜、装柜、出口报关与出仓', permission: 'platform:firstleg:container:list' },
+  },
+  {
+    path: 'container-loading/domestic/:containerId',
+    name: 'domestic-container-detail',
+    component: () => import('./pages/DomesticContainerDetailView.vue'),
+    meta: { title: '送柜报关详情', description: '查看送柜、装柜清单、报关与出仓', permission: 'platform:firstleg:container:list', showPageHeading: false },
+  },
+  {
+    path: 'container-loading/domestic/:containerId/smart-loading',
+    name: 'smart-loading-workbench',
+    component: () => import('./pages/SmartLoadingWorkbenchView.vue'),
+    meta: { title: '智能装柜', description: '生成、调整并确认可解释的装柜计划', permission: 'platform:firstleg:smart-loading:list' },
+  },
+  {
+    path: 'container-loading/overseas',
+    name: 'overseas-container-workbench',
+    component: () => import('./pages/OverseasContainersView.vue'),
+    meta: { title: '清关提柜', description: '管理海运轨迹、目的港清关、提柜与还空', permission: 'platform:firstleg:terminal-drayage:list' },
+  },
+  {
+    path: 'container-loading/overseas/:containerId',
+    name: 'overseas-container-detail',
+    component: () => import('./pages/OverseasContainerDetailView.vue'),
+    meta: { title: '清关提柜详情', description: '查看清关资料、码头拖车与还空轨迹', permission: 'platform:firstleg:terminal-drayage:list', showPageHeading: false },
+  },
+] satisfies RouteRecordRaw[]
diff --git a/src/modules/container-loading/smartLoadingChannelGroups.test.ts b/src/modules/container-loading/smartLoadingChannelGroups.test.ts
new file mode 100644
index 00000000..7d9dff19
--- /dev/null
+++ b/src/modules/container-loading/smartLoadingChannelGroups.test.ts
@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest'
+import {
+  SMART_LOADING_CHANNEL_GROUPS,
+  SMART_LOADING_WAREHOUSE_GROUPS,
+  isSeaRailChannel,
+  resolveSmartLoadingChannelGroup,
+  resolveSmartLoadingWarehouseGroup,
+} from './smartLoadingChannelGroups'
+
+describe('smartLoadingChannelGroups', () => {
+  it('exposes the nine confirmed display groups in a fixed order', () => {
+    expect(SMART_LOADING_CHANNEL_GROUPS.map((group) => group.name)).toEqual([
+      '美森正班', '美森加班', 'EXX', '合德', '洛杉矶普船', '芝加哥普船', '休斯顿普船', '萨凡纳普船', '纽约普船海卡',
+    ])
+  })
+
+  it.each([
+    ['MATSON_CLX_TRUCK', '美森正班海卡', '美森正班'],
+    ['MATSON_CLX_PARCEL', '美森正班海派', '美森正班'],
+    ['BYHP', '美森加班海派', '美森加班'],
+    ['EXX_RAIL_NY', '纽约EXX海铁', 'EXX'],
+    ['HDHK', '合德海卡包税', '合德'],
+    ['OA_LA_FULL_TRUCK', '洛杉矶普船全卡', '洛杉矶普船'],
+    ['OA_PARCEL', '普船海派', '洛杉矶普船'],
+    ['CPHT', '芝加哥普船海铁', '芝加哥普船'],
+    ['HPHK', '休斯顿普船海卡', '休斯顿普船'],
+    ['SPHK', '萨凡纳普船海卡', '萨凡纳普船'],
+    ['NPHK', '纽约普船海卡', '纽约普船海卡'],
+  ])('maps %s / %s into %s', (channelCode, channelName, expected) => {
+    expect(resolveSmartLoadingChannelGroup(channelCode, channelName)?.name).toBe(expected)
+  })
+
+  it('does not leak an unconfirmed channel into the fixed display groups', () => {
+    expect(resolveSmartLoadingChannelGroup('UNKNOWN', '未确认新渠道')).toBeNull()
+  })
+
+  it('identifies canonical and legacy sea-rail channel codes', () => {
+    expect(['EXX_RAIL_NY', 'NYEXX', 'OA_CHICAGO_RAIL', 'CPHT'].every(isSeaRailChannel)).toBe(true)
+    expect(isSeaRailChannel('OA_LA_TRUCK')).toBe(false)
+  })
+
+  it('exposes Yiwu and Dongguan as the fixed top-level warehouses', () => {
+    expect(SMART_LOADING_WAREHOUSE_GROUPS.map((group) => group.name)).toEqual(['义乌仓', '东莞仓'])
+    expect(resolveSmartLoadingWarehouseGroup('义乌国内仓')?.code).toBe('YIWU')
+    expect(resolveSmartLoadingWarehouseGroup('东莞仓')?.code).toBe('DONGGUAN')
+    expect(resolveSmartLoadingWarehouseGroup('其他仓')).toBeNull()
+  })
+})
diff --git a/src/modules/container-loading/smartLoadingChannelGroups.ts b/src/modules/container-loading/smartLoadingChannelGroups.ts
new file mode 100644
index 00000000..05d157f3
--- /dev/null
+++ b/src/modules/container-loading/smartLoadingChannelGroups.ts
@@ -0,0 +1,102 @@
+export type SmartLoadingChannelGroup = {
+  code: string
+  name: string
+  channelCodes: readonly string[]
+}
+
+export type SmartLoadingWarehouseGroup = {
+  code: string
+  name: string
+  nameKeyword: string
+}
+
+export const SMART_LOADING_WAREHOUSE_GROUPS: readonly SmartLoadingWarehouseGroup[] = [
+  { code: 'YIWU', name: '义乌仓', nameKeyword: '义乌' },
+  { code: 'DONGGUAN', name: '东莞仓', nameKeyword: '东莞' },
+] as const
+
+const SEA_RAIL_CHANNEL_CODES = new Set(['EXX_RAIL_NY', 'NYEXX', 'OA_CHICAGO_RAIL', 'CPHT'])
+
+export function isSeaRailChannel(channelCode?: string | null) {
+  return SEA_RAIL_CHANNEL_CODES.has(String(channelCode || '').trim().toUpperCase())
+}
+
+export const SMART_LOADING_CHANNEL_GROUPS: readonly SmartLoadingChannelGroup[] = [
+  {
+    code: 'MATSON_CLX',
+    name: '美森正班',
+    channelCodes: ['MATSON_CLX_TRUCK', 'MATSON_CLX_PARCEL', 'ZBYHK', 'ZBYHWK', 'ZBYHP'],
+  },
+  {
+    code: 'MATSON_MAX',
+    name: '美森加班',
+    channelCodes: ['MATSON_MAX_TRUCK', 'MATSON_MAX_PARCEL', 'BYHK', 'BYHWK', 'BYHP'],
+  },
+  {
+    code: 'EXX',
+    name: 'EXX',
+    channelCodes: ['EXX_TRUCK', 'EXX_RAIL_NY', 'EXXHK', 'EXXHWK', 'NYEXX'],
+  },
+  {
+    code: 'HEDE',
+    name: '合德',
+    channelCodes: ['HEDE_TRUCK', 'HEDE_PARCEL', 'HDHK', 'HDHWK', 'HDHP'],
+  },
+  {
+    code: 'OA_LA',
+    name: '洛杉矶普船',
+    channelCodes: ['OA_LA_TRUCK', 'OA_LA_FULL_TRUCK', 'OA_PARCEL', 'PCHK', 'PCHWK', 'PCKK', 'PCHP'],
+  },
+  {
+    code: 'OA_CHICAGO',
+    name: '芝加哥普船',
+    channelCodes: ['OA_CHICAGO_RAIL', 'CPHT'],
+  },
+  {
+    code: 'OA_HOUSTON',
+    name: '休斯顿普船',
+    channelCodes: ['OA_HOUSTON_TRUCK', 'HPHK'],
+  },
+  {
+    code: 'OA_SAVANNAH',
+    name: '萨凡纳普船',
+    channelCodes: ['OA_SAVANNAH_TRUCK', 'SPHK'],
+  },
+  {
+    code: 'OA_NEW_YORK_TRUCK',
+    name: '纽约普船海卡',
+    channelCodes: ['OA_NEW_YORK_TRUCK', 'NPHK', 'NPHWK'],
+  },
+] as const
+
+export function getSmartLoadingChannelGroup(groupCode?: string | null) {
+  const normalizedCode = String(groupCode || '').trim().toUpperCase()
+  return SMART_LOADING_CHANNEL_GROUPS.find((group) => group.code === normalizedCode) || null
+}
+
+export function resolveSmartLoadingChannelGroup(channelCode?: string | null, channelName?: string | null) {
+  const normalizedCode = String(channelCode || '').trim().toUpperCase()
+  if (normalizedCode) {
+    const codeMatch = SMART_LOADING_CHANNEL_GROUPS.find((group) => group.channelCodes.includes(normalizedCode))
+    if (codeMatch) return codeMatch
+  }
+
+  const normalizedName = String(channelName || '').replace(/\s+/g, '')
+  if (!normalizedName) return null
+  if (normalizedName.includes('美森正班')) return SMART_LOADING_CHANNEL_GROUPS[0]
+  if (normalizedName.includes('美森加班')) return SMART_LOADING_CHANNEL_GROUPS[1]
+  if (normalizedName.toUpperCase().includes('EXX')) return SMART_LOADING_CHANNEL_GROUPS[2]
+  if (normalizedName.includes('合德')) return SMART_LOADING_CHANNEL_GROUPS[3]
+  if (normalizedName.includes('洛杉矶普船') || normalizedName === '普船海派') return SMART_LOADING_CHANNEL_GROUPS[4]
+  if (normalizedName.includes('芝加哥普船')) return SMART_LOADING_CHANNEL_GROUPS[5]
+  if (normalizedName.includes('休斯顿普船')) return SMART_LOADING_CHANNEL_GROUPS[6]
+  if (normalizedName.includes('萨凡纳普船')) return SMART_LOADING_CHANNEL_GROUPS[7]
+  if (normalizedName.includes('纽约普船')) return SMART_LOADING_CHANNEL_GROUPS[8]
+  return null
+}
+
+export function resolveSmartLoadingWarehouseGroup(warehouseName?: string | null) {
+  const normalizedName = String(warehouseName || '').replace(/\s+/g, '')
+  if (!normalizedName) return null
+  return SMART_LOADING_WAREHOUSE_GROUPS.find((group) => normalizedName.includes(group.nameKeyword)) || null
+}
diff --git a/src/modules/container-loading/smartLoadingItems.test.ts b/src/modules/container-loading/smartLoadingItems.test.ts
new file mode 100644
index 00000000..f6e9917f
--- /dev/null
+++ b/src/modules/container-loading/smartLoadingItems.test.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest'
+import type { SmartLoadingItem } from './types'
+import { groupSmartLoadingItems } from './smartLoadingItems'
+
+function item(overrides: Partial<SmartLoadingItem> = {}): SmartLoadingItem {
+  return {
+    id: '1', loadingPlanId: '10', accountId: '20', inboundId: '30', inboundDetailId: '40',
+    orderId: '50', orderNo: 'FL-1', inboundCode: 'NYEXX2608180003', customerName: '柏悦物流',
+    destinationWarehouseId: '60', destinationWarehouseCode: 'LAX', destinationWarehouseName: '洛杉矶仓',
+    skuCode: 'SKU-1', productNameZh: '货物一', unitType: 'PACKAGE', palletId: null, palletNo: null, indivisible: false, packageCount: 2, productQuantity: 20,
+    grossWeightKg: 662.8, volumeCbm: 0.334, loadSequence: 2, version: 1,
+    pickedPackageCount: 0, minPackageCount: 1, canAdjust: true, canRemove: true,
+    ...overrides,
+  }
+}
+
+describe('groupSmartLoadingItems', () => {
+  it('keeps every sealed pallet as an independent non-adjustable allocation unit', () => {
+    const grouped = groupSmartLoadingItems([
+      item({ id: 'p1', unitType: 'SEALED_PALLET', palletId: '101', palletNo: 'PLT-101', indivisible: true, packageCount: 4 }),
+      item({ id: 'p2', unitType: 'SEALED_PALLET', palletId: '102', palletNo: 'PLT-102', indivisible: true, packageCount: 6 }),
+    ])
+
+    expect(grouped).toHaveLength(2)
+    expect(grouped.map((row) => row.palletNo)).toEqual(['PLT-101', 'PLT-102'])
+    expect(grouped.every((row) => row.canAdjust === false)).toBe(true)
+  })
+
+  it('shows multiple specification rows as one inbound-code row with summed quantities', () => {
+    const grouped = groupSmartLoadingItems([
+      item(),
+      item({ id: '2', inboundDetailId: '41', skuCode: 'SKU-2', productNameZh: '货物二', packageCount: 2, grossWeightKg: 662.8, volumeCbm: 0.334, loadSequence: 3 }),
+    ])
+
+    expect(grouped).toHaveLength(1)
+    expect(grouped[0]).toMatchObject({
+      inboundCode: 'NYEXX2608180003', packageCount: 4, grossWeightKg: 1325.6,
+      volumeCbm: 0.668, detailCount: 2, canAdjust: false, canRemove: true,
+      skuCode: 'SKU-1、SKU-2', productNameZh: '货物一、货物二', loadSequence: 2,
+    })
+    expect(grouped[0].sourceItems.map((source) => source.id)).toEqual(['1', '2'])
+  })
+
+  it('does not merge different inbound codes and keeps single-detail adjustment', () => {
+    const grouped = groupSmartLoadingItems([
+      item(),
+      item({ id: '2', inboundId: '31', inboundCode: 'NYEXX2608180004' }),
+    ])
+
+    expect(grouped).toHaveLength(2)
+    expect(grouped.every((row) => row.detailCount === 1 && row.canAdjust)).toBe(true)
+  })
+})
diff --git a/src/modules/container-loading/smartLoadingItems.ts b/src/modules/container-loading/smartLoadingItems.ts
new file mode 100644
index 00000000..8d66768e
--- /dev/null
+++ b/src/modules/container-loading/smartLoadingItems.ts
@@ -0,0 +1,55 @@
+import type { SmartLoadingItem } from './types'
+
+export interface SmartLoadingInboundItem extends SmartLoadingItem {
+  sourceItems: SmartLoadingItem[]
+  detailCount: number
+}
+
+function sumNullable(items: SmartLoadingItem[], value: (item: SmartLoadingItem) => number | null) {
+  const values = items.map(value).filter((item): item is number => item != null)
+  return values.length ? values.reduce((sum, item) => sum + Number(item || 0), 0) : null
+}
+
+function joinDistinct(items: SmartLoadingItem[], value: (item: SmartLoadingItem) => string | null) {
+  const values = [...new Set(items.map(value).map((item) => String(item || '').trim()).filter(Boolean))]
+  return values.length ? values.join('、') : null
+}
+
+/**
+ * 后端按规格保存装柜明细以保证重量、体积计算准确；作业页面按入仓码汇总展示。
+ */
+export function groupSmartLoadingItems(items: SmartLoadingItem[]): SmartLoadingInboundItem[] {
+  const groups = new Map<string, SmartLoadingItem[]>()
+  for (const item of items) {
+    const key = item.unitType === 'SEALED_PALLET'
+      ? `${item.accountId}:${item.inboundId}:pallet:${item.palletId}`
+      : `${item.accountId}:${item.inboundId}:packages`
+    groups.set(key, [...(groups.get(key) || []), item])
+  }
+
+  return [...groups.values()].map((sourceItems) => {
+    const first = sourceItems[0]
+    const pickedPackageCount = sourceItems.reduce((sum, item) => sum + Number(item.pickedPackageCount || 0), 0)
+    const loadSequences = sourceItems.map((item) => item.loadSequence).filter((item): item is number => item != null)
+    return {
+      ...first,
+      id: sourceItems.length === 1 ? first.id : `inbound:${first.accountId}:${first.inboundId}`,
+      inboundDetailId: sourceItems.length === 1 ? first.inboundDetailId : '',
+      skuCode: joinDistinct(sourceItems, (item) => item.skuCode),
+      productNameZh: joinDistinct(sourceItems, (item) => item.productNameZh),
+      packageCount: sourceItems.reduce((sum, item) => sum + Number(item.packageCount || 0), 0),
+      productQuantity: sumNullable(sourceItems, (item) => item.productQuantity),
+      grossWeightKg: sumNullable(sourceItems, (item) => item.grossWeightKg),
+      volumeCbm: sumNullable(sourceItems, (item) => item.volumeCbm),
+      loadSequence: loadSequences.length ? Math.min(...loadSequences) : null,
+      pickedPackageCount,
+      minPackageCount: sourceItems.reduce((sum, item) => sum + Number(item.minPackageCount || 0), 0),
+      totalPackageCount: sourceItems.reduce((sum, item) => sum + Number(item.totalPackageCount || item.packageCount || 0), 0),
+      remainingPackageCount: sourceItems.reduce((sum, item) => sum + Number(item.remainingPackageCount || 0), 0),
+      canAdjust: first.unitType !== 'SEALED_PALLET' && sourceItems.length === 1 && first.canAdjust,
+      canRemove: sourceItems.every((item) => item.canRemove),
+      sourceItems,
+      detailCount: sourceItems.length,
+    }
+  })
+}
diff --git a/src/modules/container-loading/smartLoadingPlanGroups.test.ts b/src/modules/container-loading/smartLoadingPlanGroups.test.ts
new file mode 100644
index 00000000..8d37b6a7
--- /dev/null
+++ b/src/modules/container-loading/smartLoadingPlanGroups.test.ts
@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest'
+import { loadSmartLoadingPlanCoLoadGroups } from './smartLoadingPlanGroups'
+import type { SmartLoadingPlan } from './types'
+
+const item = {
+  id: '701', loadingPlanId: '99', accountId: '1', inboundId: '201', inboundDetailId: '801', orderId: '301',
+  orderNo: 'ORD-1', inboundCode: 'IN-201', customerName: '客户一', destinationWarehouseId: '9', destinationWarehouseCode: 'LAX9', destinationWarehouseName: 'LAX9',
+  skuCode: 'SKU-1', productNameZh: '货物一', unitType: 'PACKAGE' as const, palletId: null, palletNo: null, indivisible: false, packageCount: 5, productQuantity: 50, grossWeightKg: 50, volumeCbm: 1,
+  loadSequence: 1, version: 1, pickedPackageCount: 0, minPackageCount: 1, canAdjust: true, canRemove: true,
+}
+
+const plan = {
+  id: '99', planNo: 'LP-99', status: 'EDITING', bookingId: '88', containerNo: null, voyageNo: null, version: 2,
+  canAssign: true, canEdit: true, blockedReason: null, finalCompletionStatus: 'NOT_STARTED', pdaTaskId: null,
+  pdaTaskStatus: null, pdaTaskVersion: null,
+  coLoadGroups: [{ groupId: '9001', groupNo: 'CLG-9001', lockedPlanId: '99', memberOrderCount: 2,
+    inboundFragmentCount: 2, fullPackageCount: 12, memberInboundIds: ['201', '202'] }],
+  palletMembers: [],
+  items: [item, { ...item, id: '702', inboundId: '202', inboundDetailId: '802', orderId: '302', orderNo: 'ORD-2', inboundCode: 'IN-202', packageCount: 7 }],
+} satisfies SmartLoadingPlan
+
+describe('smart loading plan co-load groups', () => {
+  it('uses the group snapshot already returned with the plan without per-inbound requests', () => {
+    const result = loadSmartLoadingPlanCoLoadGroups(plan)
+    expect(result.get('201')).toEqual({
+      groupId: '9001', groupNo: 'CLG-9001', lockedPlanId: '99', memberOrderCount: 2, inboundFragmentCount: 2, fullPackageCount: 12,
+    })
+    expect(result.get('202')).toBe(result.get('201'))
+  })
+
+  it('leaves ordinary plan items ungrouped', () => {
+    const result = loadSmartLoadingPlanCoLoadGroups({ ...plan, coLoadGroups: [] })
+    expect(result.size).toBe(0)
+  })
+})
diff --git a/src/modules/container-loading/smartLoadingPlanGroups.ts b/src/modules/container-loading/smartLoadingPlanGroups.ts
new file mode 100644
index 00000000..8a500191
--- /dev/null
+++ b/src/modules/container-loading/smartLoadingPlanGroups.ts
@@ -0,0 +1,26 @@
+import type { SmartLoadingPlan } from './types'
+
+export interface SmartLoadingPlanCoLoadGroup {
+  groupId: string
+  groupNo: string
+  lockedPlanId: string
+  memberOrderCount: number
+  inboundFragmentCount: number
+  fullPackageCount: number
+}
+
+export function loadSmartLoadingPlanCoLoadGroups(plan: SmartLoadingPlan) {
+  const groupsByInboundId = new Map<string, SmartLoadingPlanCoLoadGroup>()
+  for (const source of plan.coLoadGroups || []) {
+    const group = {
+      groupId: source.groupId,
+      groupNo: source.groupNo || '同柜不可拆组',
+      lockedPlanId: source.lockedPlanId || plan.id,
+      memberOrderCount: source.memberOrderCount,
+      inboundFragmentCount: source.inboundFragmentCount,
+      fullPackageCount: source.fullPackageCount,
+    } satisfies SmartLoadingPlanCoLoadGroup
+    for (const inboundId of source.memberInboundIds) groupsByInboundId.set(inboundId, group)
+  }
+  return groupsByInboundId
+}
diff --git a/src/modules/container-loading/types.ts b/src/modules/container-loading/types.ts
new file mode 100644
index 00000000..be31b11c
--- /dev/null
+++ b/src/modules/container-loading/types.ts
@@ -0,0 +1,462 @@
+export type ContainerPlanStatus = 'WAIT_LOADING' | 'EDITING' | 'LOADING' | 'COMPLETED'
+
+export interface ContainerBookingResource {
+  id: string
+  planId: string | null
+  planNo?: string | null
+  bookingNo: string
+  containerNo: string | null
+  cabinetNo: string
+  sourceType?: 'SIMULATION' | 'OCEAN_BOOKING'
+  recordStatus?: 'ACTIVE' | 'MERGED'
+  mergedIntoContainerBookingId?: string | null
+  warehouseId: string
+  warehouseName: string | null
+  channelGroupCode: string
+  channelCode: string | null
+  channelName: string | null
+  oceanBookingId?: string | null
+  oceanBookingRequirementId?: string | null
+  customerId?: string | null
+  customerName?: string | null
+  billOfLadingNo: string | null
+  vesselName: string | null
+  voyageNo: string | null
+  containerType: string
+  shippingCompanyId: string | null
+  shippingCompanyName: string | null
+  departurePortCode: string | null
+  departurePortName: string | null
+  destinationPortCode: string | null
+  destinationPortName: string | null
+  destinationWarehouseCode: string | null
+  destinationWarehouseName: string | null
+  capacityCbm: number | null
+  maxWeightKg: number | null
+  terminalTruckingCompanyId: string | null
+  terminalTruckingCompany: string | null
+  loadingAt: string | null
+  estimatedSailingAt: string | null
+  actualSailingAt: string | null
+  estimatedPortArrivalAt: string | null
+  actualPortArrivalAt: string | null
+  estimatedWarehouseArrivalAt: string | null
+  actualWarehouseArrivalAt: string | null
+  unloadingCompletedAt?: string | null
+  unloadingPhotoUploadedAt?: string | null
+  estimatedEmptyReportedAt?: string | null
+  actualEmptyReportedAt?: string | null
+  emptyReportSourceVersion?: string | null
+  pickupCode?: string | null
+  pickupCodeUpdatedBy?: string | null
+  pickupCodeUpdatedByName?: string | null
+  pickupCodeUpdatedAt?: string | null
+  planStatus: ContainerPlanStatus
+  exceptionActive?: boolean
+  destinationClearanceDocumentStatus?: ContainerDocumentStatus
+  customsDeclarationDocumentStatus?: ContainerDocumentStatus
+  deliveryOrderDocumentStatus?: ContainerDocumentStatus
+  outboundConfirmedAt?: string | null
+  version: number
+  createdAt?: string | null
+  updatedAt?: string | null
+  clearanceDocument?: BusinessDocument | null
+}
+
+export interface ContainerSimulationCreateRequest {
+  channelGroupCode: string
+  warehouseId: string
+  containerType: string
+  capacityCbm: number
+  maxWeightKg: number
+}
+
+export interface ContainerOceanBookingLinkRequest {
+  oceanBookingId: string
+  requirementId: string
+  containerNo: string | null
+  expectedVersion: number
+}
+
+export interface BusinessDocument {
+  id: string | null
+  documentType: string
+  fileId: string
+  fileName: string
+  fileHash: string | null
+  uploadedBy: string | null
+  uploadedByName: string | null
+  uploadedAt: string | null
+  completedBy: string | null
+  completedByName: string | null
+  completedAt: string | null
+  version: number
+}
+
+export type ContainerDocumentType = 'DESTINATION_CLEARANCE' | 'DELIVERY_ORDER'
+export type ContainerDocumentStatus = 'MISSING' | 'UPLOADED' | 'COMPLETED'
+
+export interface ContainerOverviewDocument {
+  id: string
+  documentType: ContainerDocumentType | string
+  fileId: string
+  fileName: string
+  fileHash: string | null
+  uploadedBy: string | null
+  uploadedByName: string | null
+  uploadedAt: string | null
+  version: number
+  completed: boolean
+}
+
+export interface ContainerPdaSummary {
+  taskId: string
+  loadingPlanId: string
+  containerBookingId: string
+  taskStatus: string
+  workflowStatus?: string | null
+  taskVersion: number
+  itemCount: number
+  completedItemCount: number
+  unresolvedItemCount: number
+  photoCounts: Array<{ evidenceType: string; count: number }>
+  photos: ContainerPdaPhoto[]
+  exceptionReasons: string[]
+}
+
+export interface ContainerPdaPhoto {
+  evidenceId: string
+  tenantId: string
+  inboundId: string
+  evidenceType: string
+  fileId: string
+  fileName: string
+  status: string
+  downloadPath: string
+  uploadedAt: string | null
+}
+
+export interface ContainerExceptionState {
+  active: boolean
+  reason: string | null
+  markedBy: string | null
+  markedByName: string | null
+  markedAt: string | null
+}
+
+export interface ContainerExceptionHistory {
+  id: string
+  action: string
+  reason: string
+  operatorId: string | null
+  operatorName: string | null
+  occurredAt: string | null
+}
+
+export interface ContainerTimelineEntry {
+  id?: string | null
+  eventId?: string | null
+  idempotencyKey?: string | null
+  eventType: string
+  action?: string | null
+  fromStatus?: string | null
+  toStatus?: string | null
+  detail: string | null
+  summary?: string | null
+  changeSummary?: string | null
+  reason?: string | null
+  changedFields?: unknown
+  fieldChanges?: unknown
+  changes?: unknown
+  operatorId: string | null
+  operatorName: string | null
+  occurredAt: string | null
+}
+
+export interface ContainerOverview {
+  container: Pick<ContainerBookingResource, 'id' | 'bookingNo' | 'cabinetNo' | 'containerNo' | 'warehouseId' | 'warehouseName' | 'voyageNo' | 'vesselName' | 'pickupCode' | 'pickupCodeUpdatedBy' | 'pickupCodeUpdatedByName' | 'pickupCodeUpdatedAt' | 'version'> & { status: string }
+  loadingPlanId: string | null
+  pda: ContainerPdaSummary | null
+  documents: ContainerOverviewDocument[]
+  exception: ContainerExceptionState
+  exceptionHistory: ContainerExceptionHistory[]
+  timeline: ContainerTimelineEntry[]
+}
+
+export interface ContainerPage {
+  records: ContainerWorkbenchRow[]
+  page: number
+  size: number
+  total: number
+  pages: number
+}
+
+export interface ContainerQuery {
+  page: number
+  size: number
+  customerId?: string
+  keyword?: string
+  containerNo?: string
+  cabinetNo?: string
+  warehouseId?: string
+  containerType?: string
+  status?: ContainerPlanStatus | ''
+  estimatedSailingFrom?: string
+  estimatedSailingTo?: string
+  scope?: ContainerWorkbenchScope
+}
+
+export type ContainerWorkbenchKind = 'DOMESTIC' | 'OVERSEAS'
+export type ContainerWorkbenchScope = 'ACTIVE' | 'HISTORY'
+export type ContainerWorkbenchAction = 'EDIT_CONTAINER' | 'MANAGE_CUSTOMS' | 'CONFIRM_OUTBOUND' | 'MANAGE_DESTINATION_DOCUMENTS' | 'SELECT_FLEET' | 'SCHEDULE_PICKUP' | 'RECORD_EMPTY_RETURN' | 'SEND_PICKUP_EMAIL'
+
+export interface ContainerWorkbenchStatusSummary {
+  loadingStatus?: string | null
+  customsStatus?: string | null
+  outboundStatus?: string | null
+  destinationClearanceStatus?: string | null
+  deliveryOrderStatus?: string | null
+  pickupCodeStatus?: string | null
+  latestActualNode?: string | null
+  latestActualAt?: string | null
+  terminalDrayageStatus?: string | null
+  emptyReturnWarningStatus?: string | null
+}
+
+export interface ContainerWorkbenchActualFacts {
+  actualSailingAt?: string | null
+  actualPortArrivalAt?: string | null
+  actualWarehouseArrivalAt?: string | null
+  unloadingCompletedAt?: string | null
+  actualEmptyReturnAt?: string | null
+  [key: string]: unknown
+}
+
+export interface ContainerWorkbenchTerminalDrayage {
+  containerBookingId: string
+  status: string
+  version: number
+  fleetSupplierId: string | null
+  fleetSupplierName: string | null
+  pickupAppointmentAt: string | null
+  actualPickupAt: string | null
+  estimatedEmptyReturnAt: string | null
+  actualEmptyReturnAt: string | null
+  unloadingCompletedAt: string | null
+  emptyReturnWarning: { status: 'NOT_APPLICABLE' | 'PENDING' | 'OVERDUE' | 'RESOLVED'; deadlineAt: string | null; overdueHours: number; overdueDays: number }
+  allowedActions: ReadonlyArray<'SELECT_FLEET' | 'SCHEDULE_PICKUP' | 'RECORD_EMPTY_RETURN' | 'SEND_PICKUP_EMAIL'>
+  updatedAt: string | null
+}
+
+export interface ContainerWorkbenchRow extends ContainerBookingResource {
+  workbenchStage?: string | null
+  statusSummary?: ContainerWorkbenchStatusSummary
+  allowedActions?: ContainerWorkbenchAction[]
+  actualFacts?: ContainerWorkbenchActualFacts
+  terminalDrayage?: ContainerWorkbenchTerminalDrayage | null
+}
+
+/** Wire shape returned by the domestic and overseas workbench query endpoints. */
+export interface ContainerWorkbenchItem {
+  container: ContainerBookingResource
+  workbenchStage: string
+  statusSummary: ContainerWorkbenchStatusSummary
+  allowedActions: ContainerWorkbenchAction[]
+  actualFacts: ContainerWorkbenchActualFacts | null
+  terminalDrayage: ContainerWorkbenchTerminalDrayage | null
+}
+
+export interface ContainerWorkbenchPage extends Omit<ContainerPage, 'records'> {
+  records: ContainerWorkbenchItem[]
+}
+
+export interface ContainerSaveRequest {
+  containerNo: string | null
+  warehouseId: string
+  warehouseName: string | null
+  billOfLadingNo: string | null
+  vesselName: string | null
+  voyageNo: string | null
+  containerType: string
+  shippingCompanyId: string | null
+  shippingCompanyName: string | null
+  departurePortCode: string | null
+  departurePortName: string | null
+  destinationPortCode: string | null
+  destinationPortName: string | null
+  destinationWarehouseCode: string | null
+  destinationWarehouseName: string | null
+  capacityCbm: number | null
+  maxWeightKg: number | null
+  terminalTruckingCompanyId: string | null
+  terminalTruckingCompany: string | null
+  loadingAt: string | null
+  estimatedSailingAt: string | null
+  actualSailingAt: string | null
+  estimatedPortArrivalAt: string | null
+  actualPortArrivalAt: string | null
+  estimatedWarehouseArrivalAt: string | null
+  actualWarehouseArrivalAt: string | null
+}
+
+export interface SmartLoadingCandidate {
+  accountId: string
+  customerId: string
+  inboundId: string | null
+  orderId: string
+  orderNo: string | null
+  inboundCode: string | null
+  orderStatusSnapshot?: string | null
+  expectedArrivalAt?: string | null
+  warehouseId: string
+  channelCode: string | null
+  channelName: string | null
+  destinationWarehouseId: string | null
+  destinationWarehouseCode: string | null
+  destinationWarehouseName: string | null
+  customerName: string | null
+  goodsSummary: string | null
+  unitType: 'PACKAGE' | 'SEALED_PALLET'
+  palletId: string | null
+  palletNo: string | null
+  indivisible: boolean
+  availablePackageCount: number
+  unitGrossWeightKg: number | null
+  unitNetWeightKg: number | null
+  averageUnitVolumeCbm: number | null
+  availableVolumeCbm: number | null
+  estimatedVolumeCbm: number | null
+  coLoadGroupId: string | null
+  groupNo: string | null
+  memberCount: number | null
+  groupTotalBoxes: number | null
+  locked: boolean | null
+  blockReason: string | null
+  /** Complete co-load group or sealed-pallet membership; pallet member counts are inbound-specific. */
+  groupMembers: SmartLoadingCandidateGroupMember[]
+}
+
+export interface SmartLoadingCandidateGroupMember {
+  accountId: string
+  inboundId: string
+  orderId: string
+  orderNo: string
+  inboundCode: string
+  customerName: string
+  availablePackageCount: number
+  orderStatusSnapshot: string | null
+  expectedArrivalAt: string | null
+}
+
+export interface SmartLoadingCandidateQuery {
+  channelGroupCodes: string[]
+  warehouseId?: string
+  customerId?: string
+  inboundCode?: string
+  createdStart?: string
+  createdEnd?: string
+  expectedArrivalStart?: string
+  expectedArrivalEnd?: string
+  orderStatuses?: Array<'PENDING_REVIEW' | 'WAIT_MEASURE' | 'WAIT_SPLIT' | 'LOADING'>
+  page: number
+  size: number
+}
+
+export interface SmartLoadingCandidatePage {
+  records: SmartLoadingCandidate[]
+  page: number
+  size: number
+  total: number
+  pages: number
+}
+
+export interface SmartLoadingWorkbenchContainer {
+  bookingId: string
+  bookingNo: string
+  cabinetNo: string
+  containerNo: string | null
+  warehouseId: string
+  warehouseName: string
+  channelGroupCode: string
+  channelCode: string | null
+  channelName: string | null
+  containerType: string
+  capacityCbm: number | null
+  maxWeightKg: number | null
+  planId: string | null
+  planNo: string | null
+  planStatus: Exclude<ContainerPlanStatus, 'COMPLETED'>
+  version: number
+}
+
+export interface SmartLoadingWorkbenchContainerPage {
+  records: SmartLoadingWorkbenchContainer[]
+  page: number
+  size: number
+  total: number
+  pages: number
+}
+
+export interface SmartLoadingItem {
+  id: string
+  loadingPlanId: string
+  accountId: string
+  inboundId: string
+  inboundDetailId: string
+  orderId: string
+  orderNo: string | null
+  inboundCode: string | null
+  customerName: string | null
+  destinationWarehouseId: string | null
+  destinationWarehouseCode: string | null
+  destinationWarehouseName: string | null
+  skuCode: string | null
+  productNameZh: string | null
+  unitType: 'PACKAGE' | 'SEALED_PALLET'
+  palletId: string | null
+  palletNo: string | null
+  indivisible: boolean
+  packageCount: number
+  productQuantity: number | null
+  grossWeightKg: number | null
+  volumeCbm: number | null
+  loadSequence: number | null
+  version: number
+  pickedPackageCount: number
+  minPackageCount: number
+  totalPackageCount?: number
+  remainingPackageCount?: number
+  canAdjust: boolean
+  canRemove: boolean
+}
+
+export interface SmartLoadingPlan {
+  id: string
+  planNo: string
+  status: ContainerPlanStatus
+  bookingId: string
+  containerNo: string | null
+  voyageNo: string | null
+  version: number
+  canAssign: boolean
+  canEdit: boolean
+  blockedReason: string | null
+  finalCompletionStatus: 'NOT_STARTED' | 'IN_PROGRESS' | 'COMPLETED'
+  pdaTaskId: string | null
+  pdaTaskStatus: 'LOADING' | 'COMPLETED' | null
+  pdaTaskVersion: number | null
+  coLoadGroups: Array<{
+    groupId: string
+    groupNo: string
+    lockedPlanId: string | null
+    memberOrderCount: number
+    inboundFragmentCount: number
+    fullPackageCount: number
+    memberInboundIds: string[]
+  }>
+  palletMembers: Array<{
+    palletId: string
+    members: SmartLoadingCandidateGroupMember[]
+  }>
+  items: SmartLoadingItem[]
+}
diff --git a/src/modules/customers/CustomerOverseasStorageFeePanel.vue b/src/modules/customers/CustomerOverseasStorageFeePanel.vue
new file mode 100644
index 00000000..2f5744c7
--- /dev/null
+++ b/src/modules/customers/CustomerOverseasStorageFeePanel.vue
@@ -0,0 +1,97 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import '@/modules/customers/customerDensity.css'
+import { computed, nextTick, onMounted, reactive, ref, watch } from 'vue'
+import { ElMessage, ElMessageBox, type FormInstance } from 'element-plus'
+
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useUnsavedWorkRegistration } from '@/core/unsaved-work/useUnsavedWorkRegistration'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import { getCustomerOverseasStorageFees, updateCustomerOverseasStorageFees, type OverseasStorageFeeConfig, type OverseasStorageFeeTier } from './overseasStorageFee'
+import { addFeeTier, removeFeeTier, validateFeeTiers } from './overseasStorageFeeTiers'
+
+const props = defineProps<{ customerId: string; customerName: string }>()
+const access = useAccessPreviewStore()
+const canView = computed(() => access.can('platform:customer:list'))
+const canEdit = computed(() => access.can('platform:customer:edit'))
+const config = ref<OverseasStorageFeeConfig | null>(null)
+const loading = ref(false)
+const saving = ref(false)
+const error = ref<ApiErrorDetails | null>(null)
+const visible = ref(false)
+const dirty = ref(false)
+const formRef = ref<FormInstance>()
+const form = reactive<{ currency: string; tiers: OverseasStorageFeeTier[]; version: number }>({ currency: 'USD', tiers: [], version: 0 })
+const currencies = ['USD', 'CNY', 'HKD', 'EUR', 'GBP']
+const storageTiers = computed(() => form.tiers.filter((tier) => tier.feeType === 'STORAGE'))
+const returnTiers = computed(() => form.tiers.filter((tier) => tier.feeType === 'RETURN_STORAGE'))
+
+const { captureBaseline } = useUnsavedWorkRegistration({ key: `customer-overseas-storage-fee-${props.customerId}`, label: computed(() => `${props.customerName}的海外仓费用`), isOpen: visible, model: form, requiredPermission: computed(() => 'platform:customer:edit') })
+watch(form, () => { if (visible.value) dirty.value = true }, { deep: true })
+watch(() => props.customerId, () => { visible.value = false; void load() })
+
+async function load() {
+  if (!canView.value) return
+  loading.value = true; error.value = null
+  try { config.value = await getCustomerOverseasStorageFees(props.customerId) }
+  catch (cause) { config.value = null; error.value = getApiErrorDetails(cause, '海外仓费用加载失败，请稍后重试') }
+  finally { loading.value = false }
+}
+function cloneTiers(tiers: OverseasStorageFeeTier[]) { return tiers.map((tier) => ({ ...tier })) }
+async function openEditor() {
+  if (!config.value) return
+  form.currency = config.value.currency || 'USD'; form.tiers = cloneTiers(config.value.tiers); form.version = config.value.version
+  await nextTick(); dirty.value = false; visible.value = true; await nextTick(); captureBaseline(); formRef.value?.clearValidate()
+}
+async function closeEditor() {
+  if (saving.value) return
+  if (dirty.value) { try { await ElMessageBox.confirm('海外仓费用尚未保存，确定放弃修改吗？', '放弃编辑', { customClass: 'admin-density-confirm', confirmButtonText: '放弃', cancelButtonText: '继续编辑', type: 'warning' }) } catch { return } }
+  visible.value = false
+}
+function validate() {
+  const message = validateFeeTiers(form.tiers)
+  if (message) { ElMessage.error(message); return false }
+  return true
+}
+function addTier(feeType: OverseasStorageFeeTier['feeType']) { const message = addFeeTier(form.tiers, feeType); if (message) ElMessage.error(message) }
+function removeTier(tier: OverseasStorageFeeTier) { const message = removeFeeTier(form.tiers, tier); if (message) ElMessage.error(message) }
+async function save() {
+  if (!config.value || !validate()) return
+  saving.value = true
+  try {
+    await updateCustomerOverseasStorageFees(props.customerId, { customerId: props.customerId, customerName: props.customerName, currency: form.currency, version: form.version, tiers: form.tiers.map(({ feeType, billingUnit, startDay, endDay, unitPrice }) => ({ feeType, billingUnit, startDay, endDay, unitPrice })) })
+    await load(); dirty.value = false; visible.value = false; ElMessage.success('海外仓费用已保存')
+  } catch (cause) { ElMessage.error(getApiErrorDetails(cause, '海外仓费用保存失败，请刷新后重试').message) }
+  finally { saving.value = false }
+}
+function dayLabel(tier: OverseasStorageFeeTier) { return tier.endDay === null ? `第${tier.startDay}天以上` : `第${tier.startDay}-${tier.endDay}天` }
+onMounted(load)
+</script>
+
+<template>
+  <section class="overseas-fee-panel admin-density customer-density">
+    <header class="panel-heading"><div><h2>海外仓费用</h2><p>客户专属仓租和退货仓储费阶梯</p></div><el-button v-if="canEdit && config" type="primary" :loading="loading" @click="openEditor">编辑费用</el-button></header>
+    <div v-if="error" class="fee-error" role="alert"><div><strong>海外仓费用加载失败</strong><p>{{ error.message }}</p><ApiErrorMeta :details="error" /></div><el-button plain type="primary" :loading="loading" @click="load">重新加载</el-button></div>
+    <div v-else-if="loading && !config" v-loading="true" class="fee-loading" />
+    <template v-else-if="config">
+      <div class="fee-meta"><span>币种：<strong>{{ config.currency }}</strong></span><span>按整组保存，版本 {{ config.version }}</span></div>
+      <div class="fee-groups"><div><h3>仓租（{{ config.currency }}/CBM/天）</h3><table><thead><tr><th>天数</th><th>价格</th></tr></thead><tbody><tr v-for="tier in config.tiers.filter((item) => item.feeType === 'STORAGE')" :key="tier.id"><td>{{ dayLabel(tier) }}</td><td>{{ tier.unitPrice }}</td></tr></tbody></table></div><div><h3>退货仓储费（{{ config.currency }}/托/天）</h3><table><thead><tr><th>天数</th><th>价格</th></tr></thead><tbody><tr v-for="tier in config.tiers.filter((item) => item.feeType === 'RETURN_STORAGE')" :key="tier.id"><td>{{ dayLabel(tier) }}</td><td>{{ tier.unitPrice }}</td></tr></tbody></table></div></div>
+    </template>
+    <div v-else class="fee-empty">当前客户暂无海外仓费用配置</div>
+    <AppDialog class="admin-density-dialog customer-density-dialog" v-model="visible" title="编辑海外仓费用" width="min(1120px, calc(100vw - 28px))" :confirm-loading="saving" :show-cancel="false" @confirm="save">
+      <el-form ref="formRef" :model="form" label-position="top"><el-form-item label="币种"><el-select v-model="form.currency" style="width:180px"><el-option v-for="currency in currencies" :key="currency" :label="currency" :value="currency" /></el-select></el-form-item><div class="edit-groups"><div v-for="(group, groupIndex) in [storageTiers, returnTiers]" :key="groupIndex"><div class="edit-group-heading"><h3>{{ groupIndex === 0 ? '仓租（CBM/天）' : '退货仓储费（托/天）' }} · {{ group.length }}档</h3><el-button class="density-action" data-tone="primary" type="primary" plain size="small" :disabled="form.tiers.length >= 100" @click="addTier(groupIndex === 0 ? 'STORAGE' : 'RETURN_STORAGE')">新增阶梯</el-button></div><table><thead><tr><th>操作</th><th>开始天数</th><th>结束天数</th><th>价格</th></tr></thead><tbody><tr v-for="tier in group" :key="tier.id"><td><el-button class="density-action" data-tone="danger" size="small" plain type="danger" :disabled="group.length <= 1" @click="removeTier(tier)">删除</el-button></td><td><el-input-number v-model="tier.startDay" :min="1" :max="36500" :controls="false" placeholder="请输入开始天数" /></td><td><el-input-number v-if="tier.endDay !== null" v-model="tier.endDay" :min="1" :max="36500" :controls="false" placeholder="请输入结束天数" /><span v-else>以上</span></td><td><el-input-number v-model="tier.unitPrice" :min="0" :precision="6" :controls="false" placeholder="请输入价格" /></td></tr></tbody></table></div></div></el-form>
+      <template #footer><div class="dialog-actions"><el-button :disabled="saving" @click="closeEditor">取消</el-button><el-button type="primary" :loading="saving" @click="save">保存费用</el-button></div></template>
+    </AppDialog>
+  </section>
+</template>
+
+<style scoped>
+.overseas-fee-panel { border: 1px solid var(--cc-border); background: var(--admin-surface, #fff); }.panel-heading { display:flex; align-items:center; justify-content:space-between; border-bottom:1px solid var(--cc-border); }.panel-heading h2 { margin:0; color:var(--cc-text); }.fee-groups h3 { margin:0; color:var(--cc-text); }.edit-groups h3 { margin:0; color:var(--cc-text); }.panel-heading p { margin:5px 0 0; color:var(--cc-muted); }.fee-meta { display:flex; flex-wrap:wrap; gap:var(--admin-space-7, 24px); padding:var(--admin-space-5, 12px) 18px; color:var(--cc-muted); font-size:var(--admin-font-caption, 12px); background:var(--admin-label-bg, #f8fafc); }.fee-meta strong { color:var(--cc-text); }.fee-groups { display:grid; grid-template-columns:repeat(2,minmax(0,1fr)); }.edit-groups { display:grid; grid-template-columns:repeat(2,minmax(0,1fr)); }.fee-groups > div { min-width:0; }.edit-groups > div { min-width:0; }.fee-groups table { width:100%; border-collapse:collapse; font-size:var(--admin-font-caption, 12px); }.edit-groups table { width:100%; border-collapse:collapse; font-size:var(--admin-font-caption, 12px); }.edit-groups table { table-layout:fixed; }.fee-groups th { border-bottom:1px solid var(--cc-border); text-align:left; }.fee-groups td { border-bottom:1px solid var(--cc-border); text-align:left; }.edit-groups th { border-bottom:1px solid var(--cc-border); text-align:left; }.edit-groups td { border-bottom:1px solid var(--cc-border); text-align:left; }.fee-groups th { color:var(--cc-muted); font-weight:650; }.edit-groups th { color:var(--cc-muted); font-weight:650; }.edit-groups th:first-child { width:76px; }.edit-groups td:first-child { width:76px; }.edit-groups :deep(.el-input-number) { width:100%; min-width:0; }.fee-error { display:flex; align-items:center; justify-content:space-between; gap:var(--admin-space-6, 16px); padding:20px; background:#fff4f3; }.fee-error p { margin:5px 0; color:#b42318; font-size:var(--admin-font-caption, 12px); }.fee-empty { display:grid; place-items:center; color:var(--cc-muted); }.dialog-actions { display:flex; gap:var(--admin-space-3, 8px); }.dialog-actions :deep(.el-button + .el-button) { margin-left:0; }
+.edit-group-heading { display:flex; align-items:center; justify-content:space-between; gap:var(--admin-space-5, 12px); margin-bottom:var(--admin-space-4, 10px); }
+.edit-group-heading h3 { min-width:0; }
+.edit-group-heading :deep(.el-button) { flex:0 0 auto; }
+@media (max-width:900px) { .edit-groups { grid-template-columns:1fr; } }
+@media (max-width:760px) { .panel-heading,.fee-error { align-items:stretch; flex-direction:column; }.fee-groups,.edit-groups { grid-template-columns:1fr; padding:12px; }.edit-groups > div { overflow-x:auto; }.edit-groups table { min-width:560px; }.panel-heading :deep(.el-button) { min-height:44px; } }
+</style>
diff --git a/src/modules/customers/components/CustomerBillingRulesPanel.test.ts b/src/modules/customers/components/CustomerBillingRulesPanel.test.ts
new file mode 100644
index 00000000..32cd0e73
--- /dev/null
+++ b/src/modules/customers/components/CustomerBillingRulesPanel.test.ts
@@ -0,0 +1,193 @@
+import ElementPlus from 'element-plus'
+import { createPinia, setActivePinia } from 'pinia'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { getCustomerDimensionConfig, updateCustomerDimensionConfig, updateCustomerDimensionDefaultCalculationMode, type CustomerDimensionConfig } from '@/modules/dimension-config'
+import {
+  createCustomerChargeRule,
+  listCustomerChargeRules,
+  setCustomerChargeRuleDefault,
+  type CustomerChargeRule,
+} from '@/modules/fba-pricing'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import CustomerBillingRulesPanel from './CustomerBillingRulesPanel.vue'
+import { getPlatformTenantDimensionInitializationStatus } from '@/modules/iam'
+
+vi.mock('@/modules/dimension-config', () => ({ getCustomerDimensionConfig: vi.fn(), updateCustomerDimensionConfig: vi.fn(), updateCustomerDimensionDefaultCalculationMode: vi.fn() }))
+vi.mock('@/modules/fba-pricing', () => ({
+  createCustomerChargeRule: vi.fn(),
+  listCustomerChargeRules: vi.fn(),
+  retireCustomerChargeRule: vi.fn(),
+  setCustomerChargeRuleDefault: vi.fn(),
+}))
+vi.mock('@/modules/iam', () => ({ getPlatformTenantDimensionInitializationStatus: vi.fn() }))
+
+const boxes = [
+  ['SMALL', '小箱', 30, 20, 20, '标准小箱'],
+  ['MEDIUM', '中箱', 40, 30, 30, '标准中箱'],
+  ['LARGE', '大箱', 50, 40, 40, '标准大箱'],
+  ['EXTRA_LARGE', '特大箱', 60, 50, 50, '特大箱'],
+] as const
+const config: CustomerDimensionConfig = {
+  tenantId: '8',
+  defaultCalculationMode: 'ADD',
+  rules: boxes.map(([boxType, boxTypeName, innerLengthCm, innerWidthCm, innerHeightCm, remark], index) => ({
+    id: String(100 + index),
+    boxType, boxTypeName, innerLengthCm, innerWidthCm, innerHeightCm, edgeAdditionCm: 2,
+    outerLengthCm: innerLengthCm + 4, outerWidthCm: innerWidthCm + 4, outerHeightCm: innerHeightCm + 4,
+    volumeCbm: Number(((innerLengthCm + 4) * (innerWidthCm + 4) * (innerHeightCm + 4) / 1_000_000).toFixed(3)),
+    remark, version: 3, createdAt: '2026-08-07T10:00:00', updatedAt: '2026-08-07T10:20:00',
+  })),
+}
+const chargeRule: CustomerChargeRule = {
+  id: '201', tenantId: '8', ruleCode: 'RULE-201', ruleVersion: 1, customerId: '8', customerName: '柏悦物流',
+  businessType: 'FBA', chargeMode: 'CBM', taxMode: 'TAX_INCLUDED', conversionFactor: 167,
+  lengthFactor: 1, widthFactor: 1, heightFactor: 1, defaultRule: false, roundingScale: 2,
+  roundingMode: 'HALF_UP', currency: 'CNY', effectiveFrom: '2026-09-02T10:00:00', effectiveTo: null,
+  status: 'ACTIVE', remark: null,
+}
+
+enableAutoUnmount(afterEach)
+
+describe('CustomerBillingRulesPanel', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    document.body.innerHTML = ''
+    const pinia = createPinia(); setActivePinia(pinia)
+    const auth = useAuthStore(); auth.token = 'token'; auth.permissions = [
+      'firstleg:dimension-config:view', 'firstleg:dimension-config:edit',
+      'firstleg:fba-pricing:rule:view', 'firstleg:fba-pricing:rule:edit',
+    ]
+    useAccessPreviewStore().initializeAfterLogin()
+    vi.mocked(getCustomerDimensionConfig).mockResolvedValue(config)
+    vi.mocked(updateCustomerDimensionConfig).mockResolvedValue(config)
+    vi.mocked(updateCustomerDimensionDefaultCalculationMode).mockResolvedValue(config)
+    vi.mocked(listCustomerChargeRules).mockResolvedValue([chargeRule])
+    vi.mocked(createCustomerChargeRule).mockResolvedValue(chargeRule)
+    vi.mocked(getPlatformTenantDimensionInitializationStatus).mockResolvedValue({
+      tenantId: '8', status: 'PENDING', attemptCount: 0, nextRetryAt: null,
+      lastErrorCode: null, lastErrorMessage: null, updatedAt: null,
+    })
+  })
+
+  it('renders the four fixed carton dimension rows and calculated values', async () => {
+    mount(CustomerBillingRulesPanel, { attachTo: document.body, props: { customerId: '8', customerName: '柏悦物流' }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(getCustomerDimensionConfig).toHaveBeenCalledWith('8')
+    expect(document.body.textContent).toContain('按箱规尺寸计算')
+    expect(document.body.textContent).toContain('长、宽、高各加 2X = 外径尺寸')
+    expect(document.body.textContent).toContain('小箱')
+    expect(document.body.textContent).toContain('特大箱')
+    expect(document.body.textContent).toContain('34 × 24 × 24')
+    expect(document.body.textContent).toContain('0.020')
+    expect(document.body.textContent).toContain('标准中箱')
+  })
+
+  it('hides permission codes in the no-access state', async () => {
+    const auth = useAuthStore()
+    auth.permissions = []
+    useAccessPreviewStore().initializeAfterLogin()
+
+    mount(CustomerBillingRulesPanel, { attachTo: document.body, props: { customerId: '8', customerName: '柏悦物流' }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    expect(document.body.textContent).toContain('暂无尺寸计算规则查看权限')
+    expect(document.body.textContent).toContain('请联系管理员申请尺寸计算规则查看权限')
+    expect(document.body.textContent).not.toContain('firstleg:dimension-config:view')
+    expect(getCustomerDimensionConfig).not.toHaveBeenCalled()
+  })
+
+  it('does not request billing rules before customer defaults are ready', async () => {
+    mount(CustomerBillingRulesPanel, {
+      attachTo: document.body,
+      props: {
+        customerId: '8',
+        customerName: '柏悦物流',
+        dimensionInitializationStatus: 'PENDING',
+      },
+      global: { plugins: [ElementPlus] },
+    })
+    await flushPromises()
+
+    expect(document.body.textContent).toContain('客户计费规则正在初始化')
+    expect(document.body.textContent).not.toContain('箱规尺寸规则加载失败')
+    expect(getCustomerDimensionConfig).not.toHaveBeenCalled()
+    expect(listCustomerChargeRules).not.toHaveBeenCalled()
+  })
+
+  it('loads billing rules automatically when asynchronous initialization becomes ready', async () => {
+    vi.mocked(getPlatformTenantDimensionInitializationStatus).mockResolvedValueOnce({
+      tenantId: '8', status: 'READY', attemptCount: 1, nextRetryAt: null,
+      lastErrorCode: null, lastErrorMessage: null, updatedAt: '2026-09-10T20:04:06',
+    })
+    mount(CustomerBillingRulesPanel, {
+      attachTo: document.body,
+      props: { customerId: '8', customerName: '柏悦物流', dimensionInitializationStatus: 'PENDING' },
+      global: { plugins: [ElementPlus] },
+    })
+    await flushPromises()
+
+    expect(getPlatformTenantDimensionInitializationStatus).toHaveBeenCalledWith('8')
+    expect(getCustomerDimensionConfig).toHaveBeenCalledWith('8')
+    expect(listCustomerChargeRules).toHaveBeenCalledWith('8')
+    expect(document.body.textContent).not.toContain('箱规尺寸规则加载失败')
+  })
+
+  it('submits all four rows in one update request', async () => {
+    const wrapper = mount(CustomerBillingRulesPanel, { attachTo: document.body, props: { customerId: '8', customerName: '柏悦物流' }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    ;[...document.querySelectorAll<HTMLButtonElement>('button')].find((button) => button.textContent?.trim() === '编辑规则')?.click()
+    await flushPromises()
+    const saveButton = [...document.querySelectorAll<HTMLButtonElement>('button')].find((button) => button.textContent?.trim() === '保存规则')
+    saveButton?.click(); await flushPromises()
+    expect(updateCustomerDimensionConfig).toHaveBeenCalledWith('8', { rules: expect.arrayContaining([expect.objectContaining({ boxType: 'SMALL', version: 3 }), expect.objectContaining({ boxType: 'EXTRA_LARGE', version: 3 })]) })
+    const submittedRules = vi.mocked(updateCustomerDimensionConfig).mock.calls[0][1].rules
+    expect(submittedRules).toHaveLength(4)
+    expect(Object.keys(submittedRules[0]).sort()).toEqual([
+      'boxType', 'edgeAdditionCm', 'innerHeightCm', 'innerLengthCm', 'innerWidthCm', 'remark', 'version',
+    ])
+    expect(wrapper.findComponent(AppDialog).props('modelValue')).toBe(false)
+  })
+
+  it('keeps the editor open when the whole-set save fails', async () => {
+    vi.mocked(updateCustomerDimensionConfig).mockRejectedValueOnce(new Error('规则版本冲突'))
+    mount(CustomerBillingRulesPanel, { attachTo: document.body, props: { customerId: '8', customerName: '柏悦物流' }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    ;[...document.querySelectorAll<HTMLButtonElement>('button')].find((button) => button.textContent?.trim() === '编辑规则')?.click(); await flushPromises()
+    ;[...document.querySelectorAll<HTMLButtonElement>('button')].find((button) => button.textContent?.trim() === '保存规则')?.click()
+    await flushPromises()
+    expect(document.body.textContent).toContain('编辑箱规尺寸')
+  })
+
+  it('saves the coefficient set and can use it as the customer default calculation mode', async () => {
+    vi.mocked(listCustomerChargeRules)
+      .mockResolvedValueOnce([chargeRule])
+      .mockResolvedValueOnce([{ ...chargeRule, defaultRule: true }])
+    vi.mocked(updateCustomerDimensionDefaultCalculationMode).mockResolvedValue({
+      ...config,
+      defaultCalculationMode: 'MULTIPLY',
+    })
+    const wrapper = mount(CustomerBillingRulesPanel, { attachTo: document.body, props: { customerId: '8', customerName: '柏悦物流' }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    ;[...document.querySelectorAll<HTMLButtonElement>('button')].find((button) => button.textContent?.trim() === '编辑规则')?.click()
+    await flushPromises()
+    expect(document.body.textContent).toContain('箱规按权重系数计算')
+
+    ;[...document.querySelectorAll<HTMLButtonElement>('button')].find((button) => button.textContent?.trim() === '保存系数规则')?.click()
+    await flushPromises()
+    expect(createCustomerChargeRule).toHaveBeenCalledWith('8', expect.objectContaining({
+      defaultRule: false,
+      remark: expect.stringMatching(/SMALL:30,20,20；系数:\d+(?:\.\d+)?/),
+    }))
+    expect(setCustomerChargeRuleDefault).toHaveBeenCalledWith('8', '201')
+    expect(wrapper.findComponent(AppDialog).props('modelValue')).toBe(false)
+
+    const defaultRuleCheckboxes = [...document.querySelectorAll<HTMLInputElement>('input[type="checkbox"]')]
+    defaultRuleCheckboxes[1]?.click()
+    await flushPromises()
+    expect(updateCustomerDimensionDefaultCalculationMode).toHaveBeenCalledWith('8', 'MULTIPLY')
+  })
+})
diff --git a/src/modules/customers/components/CustomerBillingRulesPanel.vue b/src/modules/customers/components/CustomerBillingRulesPanel.vue
new file mode 100644
index 00000000..956c3ca4
--- /dev/null
+++ b/src/modules/customers/components/CustomerBillingRulesPanel.vue
@@ -0,0 +1,455 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import '@/modules/customers/customerDensity.css'
+import { computed, nextTick, onBeforeUnmount, onMounted, reactive, ref, watch } from 'vue'
+import { Ruler } from '@lucide/vue'
+import { ElMessage, ElMessageBox, type FormInstance } from 'element-plus'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useUnsavedWorkRegistration } from '@/core/unsaved-work/useUnsavedWorkRegistration'
+import {
+  getCustomerDimensionConfig,
+  updateCustomerDimensionConfig,
+  updateCustomerDimensionDefaultCalculationMode,
+  type CustomerDimensionBoxType,
+  type CustomerDimensionConfig,
+  type CustomerDimensionConfigFormModel,
+  type CustomerDimensionRule,
+} from '@/modules/dimension-config'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import { createCustomerChargeRule, listCustomerChargeRules, setCustomerChargeRuleDefault, type CustomerChargeRule, type CreateCustomerChargeRuleRequest } from '@/modules/fba-pricing'
+import { getPlatformTenantDimensionInitializationStatus } from '@/modules/iam'
+
+const props = defineProps<{
+  customerId: string
+  customerName: string
+  customerCode?: string
+  dimensionInitializationStatus?: string
+}>()
+const access = useAccessPreviewStore()
+const canView = computed(() => access.can('firstleg:dimension-config:view'))
+const canEdit = computed(() => canView.value && access.can('firstleg:dimension-config:edit'))
+const canChargeView = computed(() => access.can('firstleg:fba-pricing:rule:view'))
+const canChargeEdit = computed(() => canChargeView.value && access.can('firstleg:fba-pricing:rule:edit'))
+const observedInitializationStatus = ref(props.dimensionInitializationStatus?.trim().toUpperCase() || 'READY')
+const initializationStatus = computed(() => observedInitializationStatus.value)
+const initializationPending = computed(() => ['PENDING', 'SENDING'].includes(initializationStatus.value))
+const initializationFailed = computed(() => initializationStatus.value === 'FAILED')
+const initializationReady = computed(() => !initializationPending.value && !initializationFailed.value)
+const config = ref<CustomerDimensionConfig | null>(null)
+const loading = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const editorVisible = ref(false)
+const editorSaving = ref(false)
+const editorDirty = ref(false)
+const defaultCalculationMode = ref<'ACTUAL' | 'DIMENSION' | 'WEIGHT'>('ACTUAL')
+const defaultModeSaving = ref(false)
+const editorForm = ref<FormInstance>()
+let initializationPollTimer: ReturnType<typeof setTimeout> | null = null
+let initializationPollGeneration = 0
+const form = reactive<CustomerDimensionConfigFormModel>({ rules: [] })
+const chargeRules = ref<CustomerChargeRule[]>([])
+const visibleChargeRules = computed(() => chargeRules.value.filter((rule) => rule.status === 'ACTIVE'))
+const chargeDisplayRows = computed(() => {
+  const rule = visibleChargeRules.value.find((item) => item.defaultRule) || visibleChargeRules.value[0]
+  if (!rule) return []
+  return BOX_ORDER.map((boxType) => ({
+    ...rule,
+    boxType,
+    boxTypeName: BOX_NAMES[boxType],
+    dimension: chargeDimension(boxType),
+    coefficient: Number(chargeRows.find((item) => item.boxType === boxType)?.coefficient || rule.lengthFactor || 1),
+    weight: chargeRows.find((item) => item.boxType === boxType)?.weight || 0,
+    remark: chargeRows.find((item) => item.boxType === boxType)?.remark || '',
+  }))
+})
+const chargeLoading = ref(false)
+const chargeSaving = ref(false)
+const chargeForm = reactive<CreateCustomerChargeRuleRequest>({
+  ruleCode: '', customerId: props.customerId, customerName: props.customerName, businessType: 'FBA', chargeMode: 'KG', taxMode: 'TAX_INCLUDED', conversionFactor: 167,
+  lengthFactor: 1, widthFactor: 1, heightFactor: 1, defaultRule: false, roundingScale: 2, roundingMode: 'HALF_UP', currency: 'CNY', effectiveFrom: new Date().toISOString().slice(0, 19), effectiveTo: null, remark: null,
+})
+const chargeRows = reactive([
+  { boxType: 'SMALL' as CustomerDimensionBoxType, length: 30, width: 20, height: 20, coefficient: 1.1, weight: 5, coefficientType: '体积系数', remark: '标准小箱' },
+  { boxType: 'MEDIUM' as CustomerDimensionBoxType, length: 40, width: 30, height: 30, coefficient: 1.1, weight: 8, coefficientType: '体积系数', remark: '标准中箱' },
+  { boxType: 'LARGE' as CustomerDimensionBoxType, length: 50, width: 40, height: 40, coefficient: 1.1, weight: 12, coefficientType: '体积系数', remark: '标准大箱' },
+  { boxType: 'EXTRA_LARGE' as CustomerDimensionBoxType, length: 60, width: 50, height: 50, coefficient: 1.1, weight: 15, coefficientType: '体积系数', remark: '特大箱' },
+])
+
+const BOX_ORDER: readonly CustomerDimensionBoxType[] = ['SMALL', 'MEDIUM', 'LARGE', 'EXTRA_LARGE']
+const BOX_NAMES: Record<CustomerDimensionBoxType, string> = {
+  SMALL: '小箱', MEDIUM: '中箱', LARGE: '大箱', EXTRA_LARGE: '特大箱',
+}
+
+const columns: DataTableColumn[] = [
+  { key: 'boxTypeName', label: '箱规类型', minWidth: 110, slotName: 'boxTypeName' },
+  { key: 'inner', label: '内径尺寸（长×宽×高 cm）', minWidth: 210, slotName: 'inner' },
+  { key: 'edgeAdditionCm', label: '单边加宽（cm）', width: 150, slotName: 'edgeAdditionCm' },
+  { key: 'outer', label: '外径尺寸（长×宽×高 cm）', minWidth: 210, slotName: 'outer' },
+  { key: 'volumeCbm', label: '体积（CBM）', width: 130, slotName: 'volumeCbm' },
+  { key: 'remark', label: '备注', minWidth: 140, prop: 'remark' },
+]
+
+const { captureBaseline } = useUnsavedWorkRegistration({
+  key: `customer-dimension-config-${props.customerId}`,
+  label: computed(() => `${props.customerName}的箱规尺寸规则`),
+  isOpen: editorVisible,
+  model: form,
+  requiredPermission: computed(() => 'firstleg:dimension-config:edit'),
+})
+
+watch(form, () => {
+  if (editorVisible.value) editorDirty.value = true
+}, { deep: true })
+
+watch(() => props.customerId, () => {
+  stopInitializationPolling()
+  observedInitializationStatus.value = props.dimensionInitializationStatus?.trim().toUpperCase() || 'READY'
+  editorVisible.value = false
+  defaultCalculationMode.value = 'ACTUAL'
+  if (initializationReady.value) {
+    void loadConfig()
+    void loadChargeRules()
+  } else if (initializationPending.value) {
+    startInitializationPolling()
+  }
+})
+
+watch(() => props.dimensionInitializationStatus, (status) => {
+  observedInitializationStatus.value = status?.trim().toUpperCase() || 'READY'
+  if (initializationPending.value) startInitializationPolling()
+  else stopInitializationPolling()
+})
+
+watch(initializationReady, (ready, previous) => {
+  if (ready && !previous) {
+    void loadConfig()
+    void loadChargeRules()
+  }
+})
+
+function stopInitializationPolling() {
+  initializationPollGeneration += 1
+  if (initializationPollTimer) clearTimeout(initializationPollTimer)
+  initializationPollTimer = null
+}
+
+function startInitializationPolling() {
+  if (initializationPollTimer) return
+  const generation = ++initializationPollGeneration
+  const tenantId = props.customerId
+  const poll = async () => {
+    initializationPollTimer = null
+    try {
+      const result = await getPlatformTenantDimensionInitializationStatus(tenantId)
+      if (generation !== initializationPollGeneration || tenantId !== props.customerId) return
+      observedInitializationStatus.value = result.status?.trim().toUpperCase() || 'PENDING'
+    } catch {
+      // Initialization is retried by IAM. A transient diagnostic failure must not trigger the dimension API early.
+    }
+    if (generation === initializationPollGeneration && tenantId === props.customerId && initializationPending.value) {
+      initializationPollTimer = setTimeout(poll, 2_000)
+    }
+  }
+  void poll()
+}
+
+function sortRules(rules: CustomerDimensionRule[]) {
+  return [...rules].sort((a, b) => BOX_ORDER.indexOf(a.boxType) - BOX_ORDER.indexOf(b.boxType))
+    .map((rule) => ({ ...rule, boxTypeName: BOX_NAMES[rule.boxType] || rule.boxTypeName }))
+}
+
+async function loadConfig() {
+  if (!canView.value || !initializationReady.value) return
+  loading.value = true
+  loadError.value = null
+  try {
+    config.value = await getCustomerDimensionConfig(props.customerId)
+    config.value.rules = sortRules(config.value.rules)
+    defaultCalculationMode.value = config.value.defaultCalculationMode === 'MULTIPLY' ? 'WEIGHT'
+      : config.value.defaultCalculationMode === 'ADD' ? 'DIMENSION' : 'ACTUAL'
+  } catch (error) {
+    config.value = null
+    loadError.value = getApiErrorDetails(error, '箱规尺寸规则加载失败，请稍后重试')
+  } finally {
+    loading.value = false
+  }
+}
+
+function cloneRules(rules: CustomerDimensionRule[]) {
+  return sortRules(rules).map((rule) => ({ ...rule }))
+}
+
+async function openEditor() {
+  if (!config.value) return
+  Object.assign(chargeForm, { ruleCode: `RULE-${Date.now()}`, customerId: props.customerId, customerName: props.customerName, businessType: 'FBA', chargeMode: 'CBM', taxMode: 'TAX_INCLUDED', conversionFactor: 167, lengthFactor: 1, widthFactor: 1, heightFactor: 1, defaultRule: false, roundingScale: 2, roundingMode: 'HALF_UP', currency: 'CNY', effectiveFrom: new Date().toISOString().slice(0, 19), effectiveTo: null, remark: null })
+  form.rules = cloneRules(config.value.rules)
+  await nextTick()
+  editorDirty.value = false
+  editorVisible.value = true
+  await nextTick()
+  captureBaseline()
+  editorForm.value?.clearValidate()
+}
+
+async function confirmAbandon(): Promise<boolean> {
+  try {
+    await ElMessageBox.confirm('箱规尺寸尚未保存，确定放弃修改吗？', '放弃编辑', {
+      customClass: 'admin-density-confirm', confirmButtonText: '放弃', cancelButtonText: '继续编辑', type: 'warning',
+    })
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function beforeEditorClose(done: () => void) {
+  if (editorSaving.value) return
+  if (!editorDirty.value || await confirmAbandon()) done()
+}
+
+async function closeEditor() {
+  if (editorSaving.value) return
+  if (editorDirty.value && !await confirmAbandon()) return
+  editorVisible.value = false
+}
+
+function validateRules() {
+  if (form.rules.length !== BOX_ORDER.length || form.rules.some((rule) => !BOX_ORDER.includes(rule.boxType))) {
+    ElMessage.error('必须完整保存小箱、中箱、大箱、特大箱四条规则')
+    return false
+  }
+  if (new Set(form.rules.map((rule) => rule.boxType)).size !== BOX_ORDER.length) {
+    ElMessage.error('箱规类型不能重复')
+    return false
+  }
+  if (form.rules.some((rule) => ![rule.innerLengthCm, rule.innerWidthCm, rule.innerHeightCm].every((value) => Number.isFinite(value) && value > 0))) {
+    ElMessage.error('内径长、宽、高必须大于 0')
+    return false
+  }
+  if (form.rules.some((rule) => !Number.isFinite(rule.edgeAdditionCm) || rule.edgeAdditionCm < 0.001 || rule.edgeAdditionCm > 100)) {
+    ElMessage.error('单边加宽必须在 0.001 至 100cm 之间')
+    return false
+  }
+  if (form.rules.some((rule) => (rule.remark || '').length > 500)) {
+    ElMessage.error('备注不能超过 500 个字符')
+    return false
+  }
+  return true
+}
+
+async function saveConfig() {
+  if (!config.value || !validateRules()) return
+  editorSaving.value = true
+  try {
+    const rules = form.rules.map((rule) => ({
+      boxType: rule.boxType,
+      innerLengthCm: rule.innerLengthCm,
+      innerWidthCm: rule.innerWidthCm,
+      innerHeightCm: rule.innerHeightCm,
+      edgeAdditionCm: rule.edgeAdditionCm,
+      remark: rule.remark,
+      version: rule.version,
+    }))
+    config.value = await updateCustomerDimensionConfig(props.customerId, { rules })
+    config.value.rules = sortRules(config.value.rules)
+    editorDirty.value = false
+    editorVisible.value = false
+    ElMessage.success('箱规尺寸规则已保存')
+  } catch (error) {
+    ElMessage.error(getApiErrorDetails(error, '箱规尺寸规则保存失败，请刷新后重试').message)
+  } finally {
+    editorSaving.value = false
+  }
+}
+
+function formatDimension(...values: number[]) {
+  return values.map((value) => Number(value.toFixed(2)).toString()).join(' × ')
+}
+
+async function selectDefaultCalculationMode(mode: 'DIMENSION' | 'WEIGHT', checked = true) {
+  const targetMode = checked ? mode : 'ACTUAL'
+  if (!canEdit.value || defaultModeSaving.value || targetMode === defaultCalculationMode.value) return
+  if (checked && mode === 'WEIGHT' && !visibleChargeRules.value.some((rule) => rule.defaultRule)) {
+    ElMessage.warning('请先保存并启用一套权重系数配置，再将其设为默认规则')
+    return
+  }
+  const previous = defaultCalculationMode.value
+  defaultCalculationMode.value = targetMode
+  defaultModeSaving.value = true
+  try {
+    config.value = await updateCustomerDimensionDefaultCalculationMode(
+      props.customerId,
+      !checked ? 'ACTUAL' : mode === 'WEIGHT' ? 'MULTIPLY' : 'ADD',
+    )
+    config.value.rules = sortRules(config.value.rules)
+    ElMessage.success('默认计算规则已更新')
+  } catch (error) {
+    defaultCalculationMode.value = previous
+    ElMessage.error(getApiErrorDetails(error, '默认计算规则保存失败').message)
+  } finally {
+    defaultModeSaving.value = false
+  }
+}
+
+async function saveChargeConfig() {
+  const coefficient = Number(chargeRows[0].coefficient)
+  if (!canChargeEdit.value || chargeRows.some((row) => !(Number(row.coefficient) > 0))) { ElMessage.warning('权重系数必须大于 0'); return }
+  if (chargeRows.some((row) => !(Number(row.weight) > 0))) { ElMessage.warning('每档重量必须大于 0'); return }
+  chargeSaving.value = true
+  try {
+    // A saved version becomes the active coefficient set immediately.
+    const created = await createCustomerChargeRule(props.customerId, { ...chargeForm, ruleCode: `RULE-${Date.now()}`, lengthFactor: coefficient, widthFactor: coefficient, heightFactor: coefficient, defaultRule: false, remark: chargeRows.map((row) => `${row.boxType}:${row.length},${row.width},${row.height}；系数:${row.coefficient}；重量:${row.weight}；${BOX_NAMES[row.boxType]}：${row.remark || '—'}`).join('；') })
+    await setCustomerChargeRuleDefault(props.customerId, created.id)
+    await loadChargeRules()
+    editorDirty.value = false
+    editorVisible.value = false
+    ElMessage.success('权重系数规则已保存')
+  } catch (error) { ElMessage.error(getApiErrorDetails(error, '权重系数规则保存失败').message) }
+  finally { chargeSaving.value = false }
+}
+
+function dimensionRule(boxType: CustomerDimensionBoxType) { return config.value?.rules.find((rule) => rule.boxType === boxType) }
+function chargeDimension(boxType: CustomerDimensionBoxType) {
+  const row = chargeRows.find((item) => item.boxType === boxType)
+  if (!row) return null
+  return { innerLengthCm: row.length, innerWidthCm: row.width, innerHeightCm: row.height, volumeCbm: (row.length * row.width * row.height) / 1_000_000 }
+}
+function dimensionText(boxType: CustomerDimensionBoxType) { const rule = dimensionRule(boxType); return rule ? formatDimension(rule.innerLengthCm, rule.innerWidthCm, rule.innerHeightCm) : '—' }
+function volumeText(boxType: CustomerDimensionBoxType) { const rule = dimensionRule(boxType); return rule ? Number(rule.volumeCbm).toFixed(3) : '—' }
+function weightedVolumeText(boxType: CustomerDimensionBoxType, coefficient: number) { const rule = dimensionRule(boxType); return rule ? (Number(rule.volumeCbm) * Number(coefficient || 1)).toFixed(3) : '—' }
+function weightText(boxType: CustomerDimensionBoxType) { return chargeRows.find((row) => row.boxType === boxType)?.weight.toFixed(2) || '—' }
+
+function formatDate(value: string | null) {
+  return value ? value.replace('T', ' ').slice(0, 16) : '暂无记录'
+}
+
+async function loadChargeRules() {
+  if (!canChargeView.value || !initializationReady.value) return
+  chargeLoading.value = true
+  try {
+    chargeRules.value = await listCustomerChargeRules(props.customerId)
+    const remark = chargeRules.value.find((item) => item.defaultRule)?.remark || ''
+    const fallbackCoefficient = Number(chargeRules.value.find((item) => item.defaultRule)?.lengthFactor || 1)
+    chargeRows.forEach((row) => {
+      const match = remark.match(new RegExp(`${row.boxType}:(\\d+(?:\\.\\d+)?),(\\d+(?:\\.\\d+)?),(\\d+(?:\\.\\d+)?)`))
+      if (match) { row.length = Number(match[1]); row.width = Number(match[2]); row.height = Number(match[3]) }
+      const coefficient = remark.match(new RegExp(`${row.boxType}(?::[^；]*)?；系数:(\\d+(?:\\.\\d+)?)`))
+      row.coefficient = coefficient ? Number(coefficient[1]) : fallbackCoefficient
+      const weight = remark.match(new RegExp(`${row.boxType}(?::[^；]*)?；系数:[^；]+；重量:(\\d+(?:\\.\\d+)?)`))
+      if (weight) row.weight = Number(weight[1])
+      const note = remark.match(new RegExp(`${BOX_NAMES[row.boxType]}：([^；]+)`))
+      if (note) row.remark = note[1]
+    })
+  }
+  catch (error) { ElMessage.error(getApiErrorDetails(error, '客户计费规则加载失败').message) }
+  finally { chargeLoading.value = false }
+}
+
+onMounted(() => {
+  if (initializationPending.value) {
+    startInitializationPolling()
+    return
+  }
+  if (!initializationReady.value) return
+  void loadConfig()
+  void loadChargeRules()
+})
+
+onBeforeUnmount(stopInitializationPolling)
+</script>
+
+<template>
+  <div class="dimension-rule-panel admin-density customer-density">
+    <div v-if="initializationPending" class="rule-state initialization-state" role="status">
+      <Ruler :size="30" />
+      <strong>客户计费规则正在初始化</strong>
+      <p>默认箱规和权重系数正在后台准备，完成后本页会自动加载。</p>
+    </div>
+    <div v-else-if="initializationFailed" class="rule-error initialization-state" role="alert">
+      <div><strong>客户计费规则初始化失败</strong><p>请在客户管理中重试初始化，成功后再查看计费规则。</p></div>
+    </div>
+    <div v-if="initializationReady && (!canView || loadError)" class="panel-title rule-heading">
+      <div><h2>按箱规尺寸计算</h2><p>{{ customerName }}{{ customerCode ? `（${customerCode}）` : '' }}的尺寸计算规则</p></div>
+    </div>
+    <div v-if="initializationReady && !canView" class="rule-state"><Ruler :size="30" /><strong>暂无尺寸计算规则查看权限</strong><p>请联系管理员申请尺寸计算规则查看权限。</p></div>
+    <div v-else-if="initializationReady && loadError" class="rule-error" role="alert"><div><strong>箱规尺寸规则加载失败</strong><p>{{ loadError.message }}</p><ApiErrorMeta :details="loadError" /></div><el-button type="primary" plain :loading="loading" @click="loadConfig">重新加载</el-button></div>
+    <section v-else-if="initializationReady && config" class="rule-card">
+      <header class="rule-card-heading">
+        <div class="rule-title-row">
+          <h2>按箱规尺寸计算</h2>
+        <el-checkbox :model-value="defaultCalculationMode === 'DIMENSION'" :disabled="!canEdit || defaultModeSaving" @change="selectDefaultCalculationMode('DIMENSION', Boolean($event))">设为默认规则</el-checkbox>
+        </div>
+        <el-button v-if="canEdit" type="primary" :disabled="loading" @click="openEditor">编辑规则</el-button>
+      </header>
+      <div class="formula-band"><span>计算方式：<strong>长、宽、高各加 2X = 外径尺寸</strong>（X 为单边加宽，按实测尺寸匹配箱规）</span><span>体积公式：外径长 × 外径宽 × 外径高 ÷ 1,000,000 = CBM</span><span>低于最低档使用最低档，超出当前档自动匹配下一档，超出最大档使用最大档</span></div>
+      <DataTable :data="config.rules" :columns="columns" :loading="loading" row-key="boxType" empty-text="当前客户暂无箱规尺寸规则">
+        <template #boxTypeName="{ row }"><strong>{{ row.boxTypeName }}</strong></template>
+        <template #inner="{ row }">{{ formatDimension(row.innerLengthCm, row.innerWidthCm, row.innerHeightCm) }}</template>
+        <template #edgeAdditionCm="{ row }"><el-tag effect="light">单边 +{{ row.edgeAdditionCm }}cm</el-tag></template>
+        <template #outer="{ row }">{{ formatDimension(row.outerLengthCm, row.outerWidthCm, row.outerHeightCm) }}</template>
+        <template #volumeCbm="{ row }"><strong class="volume-value">{{ Number(row.volumeCbm).toFixed(3) }}</strong></template>
+        <template #empty><div class="rule-state"><Ruler :size="28" /><strong>当前客户暂无箱规尺寸规则</strong></div></template>
+      </DataTable>
+    </section>
+    <div v-else-if="initializationReady" v-loading="loading" class="loading-state" />
+
+    <section v-if="initializationReady && canChargeView" class="rule-card charge-rule-card">
+      <header class="rule-card-heading"><div><div class="rule-title-row"><h2>箱规按权重系数计算</h2><el-checkbox :model-value="defaultCalculationMode === 'WEIGHT'" :disabled="!canEdit || defaultModeSaving" @change="selectDefaultCalculationMode('WEIGHT', Boolean($event))">设为默认规则</el-checkbox></div><p class="section-hint">勾选后客户下单数据才会按该规则调整；未勾选时默认使用实测原尺寸（不调整）。</p></div></header>
+      <el-table v-loading="chargeLoading" :data="chargeDisplayRows" border stripe empty-text="暂无系数配置">
+        <el-table-column prop="boxTypeName" label="箱规类型" min-width="110" />
+        <el-table-column label="内径尺寸（长×宽×高 cm）" min-width="240"><template #default="{ row }">{{ row.dimension ? formatDimension(row.dimension.innerLengthCm, row.dimension.innerWidthCm, row.dimension.innerHeightCm) : '—' }}</template></el-table-column>
+        <el-table-column label="权重系数" min-width="110"><template #default="{ row }"><strong>{{ row.coefficient }}</strong></template></el-table-column>
+        <el-table-column label="体积（CBM）" min-width="120"><template #default="{ row }">{{ row.dimension ? Number(row.dimension.volumeCbm).toFixed(3) : '—' }}</template></el-table-column>
+        <el-table-column label="加权体积（CBM）" min-width="145"><template #default="{ row }">{{ row.dimension ? (Number(row.dimension.volumeCbm) * row.coefficient).toFixed(3) : '—' }}</template></el-table-column>
+        <el-table-column label="重量（kg）" min-width="105"><template #default="{ row }">{{ row.weight ? row.weight.toFixed(2) : '—' }}</template></el-table-column>
+        <el-table-column label="体积重（kg）" min-width="115"><template #default="{ row }">{{ row.dimension ? (Number(row.dimension.volumeCbm) * row.coefficient * 167).toFixed(2) : '—' }}</template></el-table-column>
+        <el-table-column prop="remark" label="备注" min-width="180" align="left" header-align="left" class-name="charge-remark-column" label-class-name="charge-remark-column"><template #default="{ row }">{{ row.remark || '—' }}</template></el-table-column>
+      </el-table>
+    </section>
+
+    <AppDialog class="admin-density-dialog customer-density-dialog" v-model="editorVisible" title="编辑箱规尺寸 / 计算规则" width="min(1200px, calc(100vw - 28px))" :confirm-loading="editorSaving" :show-cancel="false" :before-close="beforeEditorClose" @confirm="saveConfig">
+      <div class="editor-content">
+        <p class="editor-formula">计算公式：按长、宽、高匹配箱规；长、宽、高各加 2X（X 为单边加宽），体积(CBM) = 外径长 × 外径宽 × 外径高 ÷ 1,000,000</p>
+        <el-form ref="editorForm" :model="form" label-position="top">
+          <div class="editor-table-wrap">
+            <table class="editor-table"><thead><tr><th>箱规类型</th><th>内径长(cm)</th><th>内径宽(cm)</th><th>内径高(cm)</th><th>单边加宽(cm)</th><th>备注</th></tr></thead><tbody>
+              <tr v-for="row in form.rules" :key="row.boxType"><th scope="row">{{ row.boxTypeName }}</th><td><el-input-number v-model="row.innerLengthCm" :min="0.001" :precision="3" :controls="false" placeholder="请输入内径长" /></td><td><el-input-number v-model="row.innerWidthCm" :min="0.001" :precision="3" :controls="false" placeholder="请输入内径宽" /></td><td><el-input-number v-model="row.innerHeightCm" :min="0.001" :precision="3" :controls="false" placeholder="请输入内径高" /></td><td><el-input-number v-model="row.edgeAdditionCm" :min="0.001" :max="100" :precision="3" :controls="false" placeholder="请输入边长加值" /></td><td><el-input v-model="row.remark" maxlength="500" placeholder="请输入备注（选填）" /></td></tr>
+            </tbody></table>
+          </div>
+          <div class="rule-save-row"><el-button type="primary" :loading="editorSaving" @click="saveConfig">保存规则</el-button></div>
+          <section v-if="canChargeView" class="combined-charge-editor"><h3>箱规按权重系数计算</h3><p class="editor-formula">长、宽、高任一项超出当前挡位时进入下一挡；命中规格的一个系数统一应用于长、宽、高。</p><div class="charge-rule-editor-wrap"><table class="charge-rule-editor"><thead><tr><th>箱规类型</th><th>内径长(cm)</th><th>内径宽(cm)</th><th>内径高(cm)</th><th>权重系数</th><th>重量(kg)</th><th>备注</th></tr></thead><tbody><tr v-for="row in chargeRows" :key="`combined-${row.boxType}`"><th>{{ BOX_NAMES[row.boxType] }}</th><td><el-input-number v-model="row.length" :min="0.001" :precision="3" :controls="false" placeholder="请输入内径长" /></td><td><el-input-number v-model="row.width" :min="0.001" :precision="3" :controls="false" placeholder="请输入内径宽" /></td><td><el-input-number v-model="row.height" :min="0.001" :precision="3" :controls="false" placeholder="请输入内径高" /></td><td><el-input-number v-model="row.coefficient" :min="0.001" :precision="3" :controls="false" placeholder="请输入权重系数" /></td><td><el-input-number v-model="row.weight" :min="0.001" :precision="3" :controls="false" placeholder="请输入重量" /></td><td><el-input v-model="row.remark" maxlength="500" placeholder="请输入备注（选填）" /></td></tr></tbody></table></div><div class="rule-save-row"><el-button type="primary" :loading="chargeSaving" @click="saveChargeConfig">保存系数规则</el-button></div></section>
+        </el-form>
+      </div>
+      <template #footer><div class="dialog-actions"><el-button :disabled="editorSaving || chargeSaving" @click="closeEditor">取消</el-button></div></template>
+    </AppDialog>
+  </div>
+</template>
+
+<style scoped>
+.dimension-rule-panel { min-width: 0; }
+.rule-heading { align-items: center; }
+.rule-heading h2 { margin: 0; color: var(--cc-text); }.rule-heading p { margin: var(--admin-space-2, 6px) 0 0; color: var(--cc-muted); }
+.heading-actions { display: flex; align-items: center; flex-wrap: wrap; gap: var(--admin-space-3, 8px); }
+.dialog-actions { display: flex; align-items: center; flex-wrap: wrap; gap: var(--admin-space-3, 8px); }.heading-actions :deep(.el-button) { margin-left: 0; }.dialog-actions :deep(.el-button) { margin-left: 0; }
+.rule-card { min-width: 0; }.rule-card-heading { display: flex; align-items: center; justify-content: space-between; border-bottom: 1px solid var(--cc-border); }.rule-card-heading h2 { margin: 0; color: var(--cc-text); }.formula-band { display: flex; align-items: center; flex-wrap: wrap; border-bottom: 1px solid var(--cc-border); background: var(--admin-label-bg, #f8fafc); color: var(--cc-muted); font-size: var(--admin-font-body, 13px); }.formula-band strong { color: #344054; }
+.rule-title-row { display: flex; align-items: center; flex-wrap: wrap; gap: 14px; }.rule-title-row :deep(.el-checkbox) { height: 30px; margin-right: 0; padding: 0 var(--admin-space-4, 10px); border: 1px solid var(--cc-border); border-radius: 6px; background: var(--admin-surface, #fff); }.rule-title-row :deep(.el-checkbox.is-checked) { border-color: var(--cc-primary); background: var(--cc-primary-soft); }
+.rule-state { display: flex; align-items: center; justify-content: center; flex-direction: column; gap: var(--admin-space-3, 8px); color: #8797b2; text-align: center; }.rule-state strong { color: #475467; font-size: var(--admin-font-body, 13px); }.rule-state p { margin: 0; color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); }
+.rule-error { display: flex; align-items: center; justify-content: space-between; gap: 18px; background: #fff4f3; }.rule-error strong { color: #7a271a; }.rule-error p { margin: 5px 0; color: #b42318; font-size: var(--admin-font-caption, 12px); }
+.volume-value { color: #1570ef; }.editor-content { display: grid; }.editor-formula { margin: 0; color: #475467; font-size: var(--admin-font-body, 13px); line-height: 1.7; }.editor-table-wrap { overflow-x: auto; }.editor-table { width: 100%; min-width: 920px; border-collapse: collapse; }.editor-table th { border-bottom: 1px solid var(--cc-border); text-align: left; white-space: nowrap; }.editor-table td { border-bottom: 1px solid var(--cc-border); text-align: left; white-space: nowrap; }.editor-table thead th { background: #eef0fa; color: #475467; font-size: var(--admin-font-caption, 12px); }.editor-table tbody th { color: var(--cc-text); font-size: var(--admin-font-body, 13px); }.editor-table :deep(.el-input-number) { width: 140px; }.editor-table :deep(.el-input) { width: 140px; }.editor-table :deep(.el-input-number .el-input__wrapper) { width: 100%; }.section-hint { margin: 5px 0 0; color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); font-weight: 400; }.charge-form { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 0 var(--admin-space-6, 16px); }.charge-form :deep(.el-form-item:last-child) { grid-column: 1 / -1; }.charge-form :deep(.el-input-number) { width: 100%; }.charge-form :deep(.el-input) { width: 100%; }
+.charge-form--simple { grid-template-columns: 1fr; }.charge-form--simple :deep(.el-form-item) { grid-column: 1; }
+.charge-rule-editor-wrap { overflow-x: auto; }.charge-rule-editor { width: 100%; min-width: 920px; border-collapse: collapse; }.charge-rule-editor th { border-bottom: 1px solid var(--cc-border); text-align: left; white-space: nowrap; }.charge-rule-editor td { border-bottom: 1px solid var(--cc-border); text-align: left; white-space: nowrap; }.charge-rule-editor thead th { background: #eef0fa; color: #475467; font-size: var(--admin-font-caption, 12px); }.charge-rule-editor tbody th { color: var(--cc-text); font-size: var(--admin-font-body, 13px); }.charge-rule-editor :deep(.el-input-number) { width: 118px; }.charge-rule-editor :deep(.el-input) { width: 118px; }.charge-rule-editor :deep(.el-input-number .el-input__wrapper) { width: 100%; }
+.charge-box-cell { min-height: 34px; display: flex; align-items: center; border-bottom: 1px solid var(--cc-border); }.charge-box-cell:last-child { border-bottom: 0; }
+.rule-save-row { display: flex; justify-content: flex-end; padding: var(--admin-space-5, 12px) 0 var(--admin-space-1, 4px); }
+.dialog-actions { width: 100%; }
+.dialog-actions :deep(.el-button) { min-width: 112px; min-height: 46px; font-size: 15px; }
+.charge-rule-card :deep(.el-table) { color: #344054; font-size: var(--admin-font-body, 13px); }
+.charge-rule-card :deep(.el-table th.el-table__cell) { background: var(--admin-label-bg, #f8fafc); color: #475467; font-size: var(--admin-font-body, 13px); font-weight: 650; }
+.charge-rule-card :deep(.el-table td.el-table__cell) { color: #344054; font-size: var(--admin-font-body, 13px); }
+.charge-rule-card :deep(.el-table .cell) { line-height: 1.5; text-align: center; }
+.charge-rule-card :deep(.el-table .charge-remark-column .cell) { text-align: left; }
+.charge-rule-card :deep(.el-table strong) { color: #1570ef; font-weight: 650; }
+@media (max-width: 760px) { .rule-heading { align-items: stretch; flex-direction: column; }.rule-card-heading { align-items: stretch; flex-direction: column; }.rule-card-heading :deep(.el-button) { min-height: 44px; }.formula-band { align-items: flex-start; flex-direction: column; gap: 8px; }.rule-error { align-items: stretch; flex-direction: column; }.dialog-actions { width: 100%; }.dialog-actions :deep(.el-button) { min-height: 44px; flex: 1; } }
+</style>
diff --git a/src/modules/customers/components/CustomerOperatingMetricCard.test.ts b/src/modules/customers/components/CustomerOperatingMetricCard.test.ts
new file mode 100644
index 00000000..6f67c2d5
--- /dev/null
+++ b/src/modules/customers/components/CustomerOperatingMetricCard.test.ts
@@ -0,0 +1,26 @@
+import { mount } from '@vue/test-utils'
+import { describe, expect, it } from 'vitest'
+import CustomerOperatingMetricCard from './CustomerOperatingMetricCard.vue'
+
+describe('CustomerOperatingMetricCard', () => {
+  const props = { title: '累计应收', value: '12.3456', unit: '万元', detail: '未结清 0.125 万元', tone: 'green' as const }
+
+  it('keeps the supplied decimal precision', () => {
+    const wrapper = mount(CustomerOperatingMetricCard, { props })
+    expect(wrapper.text()).toContain('12.3456万元')
+    expect(wrapper.text()).toContain('未结清 0.125 万元')
+  })
+
+  it('shows a dash instead of zero for failures', () => {
+    const wrapper = mount(CustomerOperatingMetricCard, { props: { ...props, failed: true } })
+    expect(wrapper.text()).toContain('—')
+    expect(wrapper.text()).toContain('加载失败')
+    expect(wrapper.text()).not.toContain('12.3456')
+  })
+
+  it('shows the permission state without exposing a value', () => {
+    const wrapper = mount(CustomerOperatingMetricCard, { props: { ...props, unauthorized: true } })
+    expect(wrapper.text()).toContain('暂无查看权限')
+    expect(wrapper.text()).not.toContain('12.3456')
+  })
+})
diff --git a/src/modules/customers/components/CustomerOperatingMetricCard.vue b/src/modules/customers/components/CustomerOperatingMetricCard.vue
new file mode 100644
index 00000000..b25f5029
--- /dev/null
+++ b/src/modules/customers/components/CustomerOperatingMetricCard.vue
@@ -0,0 +1,41 @@
+<script setup lang="ts">
+defineProps<{
+  title: string
+  value: string
+  unit: string
+  detail: string
+  loading?: boolean
+  failed?: boolean
+  unauthorized?: boolean
+  tone: 'blue' | 'green' | 'amber'
+}>()
+</script>
+
+<template>
+  <article class="operating-metric-card" :aria-label="title" :aria-busy="loading || undefined">
+    <span class="metric-icon" :class="`is-${tone}`" aria-hidden="true"><slot name="icon" /></span>
+    <div class="metric-content">
+      <p>{{ title }}</p>
+      <strong v-if="loading" class="metric-loading" aria-label="加载中">—</strong>
+      <strong v-else-if="failed || unauthorized">—</strong>
+      <strong v-else>{{ value }}<small>{{ unit }}</small></strong>
+      <span :class="{ 'is-error': failed }">{{ unauthorized ? '暂无查看权限' : failed ? '加载失败' : loading ? '加载中…' : detail }}</span>
+    </div>
+  </article>
+</template>
+
+<style scoped>
+.operating-metric-card { display:flex; min-width:0; align-items:center; gap:14px; padding:22px 24px; border-right:1px solid var(--cc-border); }
+.metric-icon { display:grid; width:44px; height:44px; flex:0 0 auto; place-items:center; border-radius:12px; }
+.metric-icon.is-blue { background:linear-gradient(135deg,rgba(102,126,234,.15),rgba(118,75,162,.1)); color:#667eea; }
+.metric-icon.is-green { background:linear-gradient(135deg,rgba(34,197,94,.15),rgba(22,163,74,.1)); color:#16a34a; }
+.metric-icon.is-amber { background:linear-gradient(135deg,rgba(245,158,11,.15),rgba(234,88,12,.1)); color:#ea580c; }
+.metric-content { min-width:0; }
+p,span { margin:0; color:var(--cc-muted); font-size:12px; }
+strong { display:block; min-width:0; margin:5px 0 4px; color:#172033; font-size:26px; line-height:1; overflow-wrap:anywhere; }
+small { margin-left:5px; color:#475467; font-size:12px; font-weight:600; white-space:nowrap; }
+.is-error { color:#d92d20; }
+.metric-loading { color:#98a2b3; }
+@media (max-width:720px) { .operating-metric-card { border-right:0; border-bottom:1px solid var(--cc-border); } }
+@media (max-width:360px) { .operating-metric-card { gap:10px; padding:18px 14px; }.metric-icon { width:40px; height:40px; }strong { font-size:23px; } }
+</style>
diff --git a/src/modules/customers/customerDensity.css b/src/modules/customers/customerDensity.css
new file mode 100644
index 00000000..e0d8c027
--- /dev/null
+++ b/src/modules/customers/customerDensity.css
@@ -0,0 +1,83 @@
+/* Customer menu workspaces and their explicitly opted-in overlays. */
+/* Only remove decoration from text actions; retain icon-only paging/settings controls. */
+.customer-density.admin-density .el-button :is(.lucide-search, .lucide-rotate-ccw, .lucide-copy),
+.customer-density-dialog.admin-density-dialog .el-button .lucide-copy { display: none; }
+
+.customer-density.admin-density.customer-detail-page .detail-page-layout { gap: var(--admin-space-5, 12px); }
+.customer-density.admin-density.customer-detail-page .detail-header { padding: var(--admin-space-3, 8px) var(--admin-space-5, 12px); background: var(--admin-surface, #fff); border: 1px solid var(--cc-border); }
+.customer-density.admin-density .detail-page-toolbar h1 { font-size: var(--admin-font-title, 16px); line-height: 24px; }
+.customer-density.admin-density .detail-page-toolbar p { margin-top: 2px; font-size: var(--admin-font-caption, 12px); }
+.customer-density.admin-density .tab-panel { padding-top: 0; min-height: 0; background: var(--admin-surface, #fff); border: 1px solid var(--cc-border); border-top: 0; }
+.customer-density.admin-density .basic-layout { grid-template-columns: 1fr; gap: 0; }
+.customer-density.admin-density .detail-panel { padding: var(--admin-space-5, 12px); border: 0; border-bottom: 1px solid var(--cc-border); border-radius: 0; background: var(--admin-surface, #fff); box-shadow: none; }
+.customer-density.admin-density .detail-panel:last-child { border-bottom: 0; }
+.customer-density.admin-density .module-panel { min-height: 0; }
+.customer-density.admin-density .panel-title { align-items: center; gap: var(--admin-space-5, 12px); margin-bottom: var(--admin-space-3, 8px); padding-bottom: var(--admin-space-3, 8px); }
+.customer-density.admin-density .panel-title h2 { font-size: var(--admin-font-section, 14px); }
+.customer-density.admin-density .panel-title p { margin-top: 3px; font-size: var(--admin-font-caption, 12px); }
+.customer-density.admin-density .info-grid { grid-template-columns: repeat(4, minmax(0, 1fr)); }
+.customer-density.admin-density .info-grid--three { grid-template-columns: repeat(3, minmax(0, 1fr)); }
+.customer-density.admin-density .qualification-list { gap: 0; border: 1px solid var(--cc-border); }
+.customer-density.admin-density .qualification-list button { grid-template-columns: minmax(0, 1fr) 100px 120px 48px; gap: var(--admin-space-5, 12px); min-height: 40px; padding: var(--admin-space-2, 6px) var(--admin-space-4, 10px); border: 0; border-bottom: 1px solid var(--cc-border); border-radius: 0; }
+.customer-density.admin-density .qualification-list button:last-child { border-bottom: 0; }
+.customer-density.admin-density .qualification-list strong { font-size: var(--admin-font-body, 13px); }
+.customer-density.admin-density .qualification-list small { overflow-wrap: anywhere; font-size: var(--admin-font-caption, 12px); }
+.customer-density.admin-density .file-date { font-size: var(--admin-font-caption, 12px); }
+.customer-density.admin-density .file-preview-label { color: var(--cc-primary); font-size: var(--admin-font-body, 13px); }
+.customer-density.admin-density .section-empty,.customer-density.admin-density .module-empty { min-height: var(--admin-empty-height, 64px); padding: var(--admin-space-5, 12px); gap: var(--admin-space-1, 4px); }
+.customer-density.admin-density .section-empty > svg,.customer-density.admin-density .module-empty > svg { display: none; }
+.customer-density.admin-density .section-empty span { font-size: var(--admin-font-caption, 12px); }
+.customer-density.admin-density .user-table-wrap { border: 1px solid var(--cc-border); border-radius: 0; }
+.customer-density.admin-density .user-table-wrap table { font-size: var(--admin-font-body, 13px); }
+.customer-density.admin-density .user-table-wrap th,.customer-density.admin-density .user-table-wrap td { height: var(--admin-row-height, 36px); padding: var(--admin-space-2, 6px) var(--admin-space-4, 10px); }
+.customer-density.admin-density .user-identity > span { display: none; }
+.customer-density.admin-density .user-identity small,.customer-density.admin-density .member-contact small { font-size: var(--admin-font-caption, 12px); }
+.customer-density-dialog.admin-density-dialog .form-section { padding: var(--admin-space-4, 10px) 0; }
+.customer-density-dialog.admin-density-dialog .form-section__heading { margin-bottom: var(--admin-space-3, 8px); }
+.customer-density-dialog.admin-density-dialog .form-grid { gap: 0 var(--admin-space-6, 16px); }
+.customer-density-dialog.admin-density-dialog .field-hint { font-size: var(--admin-font-caption, 12px); }
+.customer-density-dialog.admin-density-dialog .qualification-row > * { min-height: 44px; padding: var(--admin-space-2, 6px) var(--admin-space-4, 10px); }
+.customer-density-dialog.admin-density-dialog .qualification-header > * { min-height: var(--admin-row-height, 36px); }
+.customer-density-dialog.admin-density-dialog .file-picker { min-height: var(--admin-control-height, 32px); }
+.customer-density-dialog.admin-density-dialog .qualification-file-name { max-width: none; overflow-wrap: anywhere; white-space: normal; }
+.customer-density-dialog.admin-density-dialog .qualification-preview-action { font-size: var(--admin-font-caption, 12px); }
+.customer-density-dialog.admin-density-dialog .review-dialog-content { gap: var(--admin-space-5, 12px); }
+.customer-density-dialog.admin-density-dialog .review-dialog-header { padding: var(--admin-space-3, 8px) var(--admin-space-4, 10px); border-radius: 0; background: var(--admin-surface, #fff); }
+.customer-density-dialog.admin-density-dialog .review-dialog-title strong { white-space: normal; overflow-wrap: anywhere; }
+.customer-density-dialog.admin-density-dialog .review-dialog-icon { display: none; }
+.customer-density-dialog.admin-density-dialog .review-dialog-grid { gap: var(--admin-space-5, 12px); }
+.customer-density-dialog.admin-density-dialog .review-dialog-section,.customer-density-dialog.admin-density-dialog .review-decision-card { padding: var(--admin-space-4, 10px); border-radius: 0; box-shadow: none; }
+.customer-density-dialog.admin-density-dialog .review-section-heading { margin-bottom: var(--admin-space-3, 8px); }
+.customer-density-dialog.admin-density-dialog .review-section-heading span { font-size: var(--admin-font-caption, 12px); }
+.customer-density-dialog.admin-density-dialog .review-info-grid { grid-template-columns: 1fr; }
+.customer-density-dialog.admin-density-dialog .review-document-table { border-radius: 0; }
+.customer-density-dialog.admin-density-dialog .review-document-header { font-size: var(--admin-font-caption, 12px); }
+.customer-density-dialog.admin-density-dialog .review-document-name { white-space: normal; }
+.customer-density-dialog.admin-density-dialog .decision-summary { margin-bottom: var(--admin-space-5, 12px); padding: var(--admin-space-3, 8px) var(--admin-space-4, 10px); border-radius: 0; }
+.customer-density-dialog.admin-density-dialog .approval-credentials { margin-top: var(--admin-space-5, 12px); border-radius: 0; }
+.customer-density-dialog.admin-density-dialog .approval-credentials > div { padding: var(--admin-space-3, 8px) var(--admin-space-4, 10px); }
+
+.customer-density.admin-density .rule-heading,.customer-density.admin-density .rule-card-heading,.customer-density.admin-density .panel-heading { min-height: 0; padding: var(--admin-space-3, 8px) 0; gap: var(--admin-space-5, 12px); }
+.customer-density.admin-density .rule-heading h2,.customer-density.admin-density .rule-card-heading h2,.customer-density.admin-density .panel-heading h2 { font-size: var(--admin-font-section, 14px); }
+.customer-density.admin-density .rule-heading p,.customer-density.admin-density .panel-heading p { margin-top: 3px; font-size: var(--admin-font-caption, 12px); }
+.customer-density.admin-density .formula-band { min-height: var(--admin-row-height, 36px); padding: var(--admin-space-2, 6px) var(--admin-space-4, 10px); gap: var(--admin-space-2, 6px) var(--admin-space-7, 24px); }
+.customer-density.admin-density .rule-state,.customer-density.admin-density .rule-error,.customer-density.admin-density .loading-state,.customer-density.admin-density .fee-loading,.customer-density.admin-density .fee-empty { min-height: var(--admin-empty-height, 64px); padding: var(--admin-space-5, 12px); }
+.customer-density.admin-density .rule-state > svg { display: none; }
+.customer-density.admin-density .charge-rule-card { margin-top: var(--admin-space-5, 12px); }
+.customer-density.admin-density .overseas-fee-panel { margin-top: var(--admin-space-5, 12px); }
+.customer-density.admin-density .fee-groups { gap: var(--admin-space-5, 12px); padding: var(--admin-space-3, 8px) 0; }
+.customer-density.admin-density .fee-groups h3,.customer-density-dialog.admin-density-dialog .edit-groups h3,.customer-density-dialog.admin-density-dialog .groups h3 { font-size: var(--admin-font-section, 14px); }
+.customer-density.admin-density .fee-groups th,.customer-density.admin-density .fee-groups td { padding: var(--admin-space-2, 6px) var(--admin-space-4, 10px); }
+.customer-density-dialog.admin-density-dialog .editor-content { gap: var(--admin-space-5, 12px); }
+.customer-density-dialog.admin-density-dialog .editor-formula { padding: var(--admin-space-2, 6px) 0; }
+.customer-density-dialog.admin-density-dialog .editor-table th,.customer-density-dialog.admin-density-dialog .editor-table td,
+.customer-density-dialog.admin-density-dialog .charge-rule-editor th,.customer-density-dialog.admin-density-dialog .charge-rule-editor td,
+.customer-density-dialog.admin-density-dialog .edit-groups th,.customer-density-dialog.admin-density-dialog .edit-groups td { padding: var(--admin-space-1, 4px) var(--admin-space-3, 8px); }
+.customer-density-dialog.admin-density-dialog .dialog-actions { justify-content: flex-end; }
+.customer-density-dialog.admin-density-dialog .dialog-actions .el-button { min-height: var(--admin-control-height, 32px); min-width: 64px; font-size: var(--admin-font-body, 13px); }
+.customer-density-dialog.admin-density-dialog .edit-groups,.customer-density-dialog.admin-density-dialog .groups { gap: var(--admin-space-5, 12px); padding: 0; }
+
+@media (max-width: 960px) { .customer-density.admin-density .info-grid { grid-template-columns: repeat(2,minmax(0,1fr)); } }
+@media (max-width: 720px) { .customer-density.admin-density .info-grid { grid-template-columns: 1fr; }.customer-density.admin-density .qualification-list button { grid-template-columns: minmax(0,1fr) auto; }.customer-density.admin-density .qualification-list .file-date { white-space: normal; } }
+
+.customer-density-dialog .review-info-grid { --admin-field-label-width: 96px; }
diff --git a/src/modules/customers/overseasStorageFee.test.ts b/src/modules/customers/overseasStorageFee.test.ts
new file mode 100644
index 00000000..d9a03db9
--- /dev/null
+++ b/src/modules/customers/overseasStorageFee.test.ts
@@ -0,0 +1,74 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { getCustomerOverseasStorageFees, updateCustomerOverseasStorageFees } from './overseasStorageFee'
+import { http } from '@/shared/api/http'
+
+const overseasListSource = readFileSync(resolve(process.cwd(), 'src/modules/customers/pages/OverseasStorageFeesView.vue'), 'utf8')
+const overseasPanelSource = readFileSync(resolve(process.cwd(), 'src/modules/customers/CustomerOverseasStorageFeePanel.vue'), 'utf8')
+
+vi.mock('@/shared/api/http', () => ({
+  http: { get: vi.fn(), put: vi.fn() },
+  unwrapApiResponse: <T>(response: { data: T }) => {
+    const value = response.data as T & { code?: string; message?: string; data?: unknown }
+    if (value && typeof value === 'object' && 'code' in value) {
+      if (value.code !== '200') throw new Error(value.message || 'request failed')
+      return value.data as T
+    }
+    return value
+  },
+}))
+
+const config = { id: 12, customerId: 9007199254740993n.toString(), customerName: '客户', currency: 'USD', tiers: [], version: 0, createdAt: null, updatedAt: null }
+
+describe('customer overseas storage fee api', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it('keeps overseas fee business actions as semantic buttons at narrow widths', () => {
+    expect(overseasListSource).toContain('border stripe')
+    expect(overseasListSource).toContain('class="density-action" size="small" plain')
+    expect(overseasListSource).toContain('size="small" plain type="danger"')
+    expect(overseasListSource).toContain('<el-table :data="group" size="small" border stripe>')
+    expect(overseasListSource).not.toContain('<Pencil')
+    expect(overseasListSource).not.toContain('<Trash2')
+    expect(overseasListSource).toContain('@media (max-width:720px)')
+    expect(overseasPanelSource).toContain('size="small" plain type="danger"')
+    expect(overseasPanelSource).toContain('@media (max-width:760px)')
+  })
+
+  it('keeps customer ids as strings and uses the customer detail path', async () => {
+    vi.mocked(http.get).mockResolvedValue({ data: config })
+    const result = await getCustomerOverseasStorageFees(config.customerId)
+    expect(http.get).toHaveBeenCalledWith(`/platform/v1/iam/tenants/${config.customerId}/overseas-storage-fees`)
+    expect(result.id).toBe('12')
+    expect(result.customerId).toBe(config.customerId)
+  })
+
+  it('submits the complete group and reloads the new version', async () => {
+    vi.mocked(http.put).mockResolvedValue({ data: null })
+    vi.mocked(http.get).mockResolvedValue({ data: { ...config, version: 1 } })
+    const request = { customerId: config.customerId, customerName: '客户', currency: 'CNY', version: 0, tiers: [{ feeType: 'STORAGE' as const, billingUnit: 'CBM' as const, startDay: 1, endDay: null, unitPrice: 0 }] }
+    const result = await updateCustomerOverseasStorageFees(config.customerId, request)
+    expect(http.put).toHaveBeenCalledWith(`/platform/v1/iam/tenants/${config.customerId}/overseas-storage-fees`, request)
+    expect(result.version).toBe(1)
+  })
+
+  it('rejects a business error returned by the update endpoint', async () => {
+    vi.mocked(http.put).mockResolvedValue({ data: { code: 'A0400', message: '璇锋眰鏃犳晥', data: null } })
+
+    await expect(updateCustomerOverseasStorageFees(config.customerId, {
+      customerId: config.customerId,
+      customerName: '瀹㈡埛',
+      currency: 'USD',
+      version: 0,
+      tiers: [{ feeType: 'STORAGE', billingUnit: 'CBM', startDay: 1, endDay: null, unitPrice: 0 }],
+    })).rejects.toThrow('璇锋眰鏃犳晥')
+    expect(http.get).not.toHaveBeenCalled()
+  })
+
+  it('normalizes an omitted end day as an open-ended tier', async () => {
+    vi.mocked(http.get).mockResolvedValue({ data: { ...config, tiers: [{ id: 1, startDay: 91, unitPrice: 2, sortNo: 5, feeType: 'STORAGE', billingUnit: 'CBM' }] } })
+    const result = await getCustomerOverseasStorageFees(config.customerId)
+    expect(result.tiers[0]?.endDay).toBeNull()
+  })
+})
diff --git a/src/modules/customers/overseasStorageFee.ts b/src/modules/customers/overseasStorageFee.ts
new file mode 100644
index 00000000..88e590d1
--- /dev/null
+++ b/src/modules/customers/overseasStorageFee.ts
@@ -0,0 +1,67 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+
+export type OverseasFeeType = 'STORAGE' | 'RETURN_STORAGE'
+export type OverseasBillingUnit = 'CBM' | 'PALLET'
+
+export interface OverseasStorageFeeTier {
+  id: string
+  startDay: number
+  endDay: number | null
+  unitPrice: number
+  sortNo: number
+  feeType: OverseasFeeType
+  billingUnit: OverseasBillingUnit
+}
+
+export interface OverseasStorageFeeConfig {
+  id: string
+  customerId: string
+  customerName: string
+  currency: string
+  tiers: OverseasStorageFeeTier[]
+  version: number
+  createdAt: string | null
+  updatedAt: string | null
+}
+
+export interface OverseasStorageFeeUpdateRequest {
+  customerId: string
+  customerName: string
+  currency: string
+  tiers: Array<Pick<OverseasStorageFeeTier, 'feeType' | 'billingUnit' | 'startDay' | 'endDay' | 'unitPrice'>>
+  version: number
+}
+
+const path = (tenantId: string) => `/platform/v1/iam/tenants/${encodeURIComponent(tenantId)}/overseas-storage-fees`
+
+type RawConfig = Omit<OverseasStorageFeeConfig, 'id' | 'customerId' | 'version' | 'tiers'> & {
+  id: string | number
+  customerId: string | number
+  version: string | number
+  tiers: Array<Omit<OverseasStorageFeeTier, 'id'> & { id: string | number; unitPrice: number | string }>
+}
+
+function normalize(data: RawConfig): OverseasStorageFeeConfig {
+  return {
+    ...data,
+    id: String(data.id), customerId: String(data.customerId), version: Number(data.version),
+    tiers: data.tiers.map((tier) => ({ ...tier, id: String(tier.id), endDay: tier.endDay == null ? null : Number(tier.endDay), unitPrice: Number(tier.unitPrice), feeType: tier.feeType as OverseasFeeType, billingUnit: tier.billingUnit as OverseasBillingUnit })),
+  }
+}
+
+export async function getCustomerOverseasStorageFees(tenantId: string) {
+  const response = await http.get<never, ApiEnvelope<RawConfig>>(path(tenantId))
+  return normalize(unwrapApiResponse(response))
+}
+
+export async function updateCustomerOverseasStorageFees(tenantId: string, request: OverseasStorageFeeUpdateRequest) {
+  const response = await http.put<never, ApiEnvelope<null>>(path(tenantId), request)
+  unwrapApiResponse(response)
+  return getCustomerOverseasStorageFees(tenantId)
+}
+
+export async function listOverseasStorageFees(page = 1, size = 20, customerName?: string) {
+  const response = await http.get<never, ApiEnvelope<{ records: RawConfig[]; total: number; page: number; size: number }>>('/platform/v1/overseas-storage-fees', { params: { page, size, customerName } })
+  const result = unwrapApiResponse(response)
+  return { ...result, records: (result.records || []).map(normalize), total: Number(result.total || 0), page: Number(result.page || page), size: Number(result.size || size) }
+}
diff --git a/src/modules/customers/overseasStorageFeeTiers.test.ts b/src/modules/customers/overseasStorageFeeTiers.test.ts
new file mode 100644
index 00000000..cdbe9235
--- /dev/null
+++ b/src/modules/customers/overseasStorageFeeTiers.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest'
+import { addFeeTier, removeFeeTier, validateFeeTiers } from './overseasStorageFeeTiers'
+import type { OverseasFeeType, OverseasStorageFeeTier } from './overseasStorageFee'
+
+function tier(id: string, feeType: OverseasFeeType, startDay: number, endDay: number | null): OverseasStorageFeeTier {
+  return { id, feeType, billingUnit: feeType === 'STORAGE' ? 'CBM' : 'PALLET', startDay, endDay, unitPrice: 1, sortNo: 1 }
+}
+
+describe('overseas storage fee tier editing', () => {
+  it('adds a new open-ended tier and closes the previous tail', () => {
+    const tiers = [
+      tier('s1', 'STORAGE', 1, 7), tier('s2', 'STORAGE', 8, 30), tier('s3', 'STORAGE', 31, 60),
+      tier('s4', 'STORAGE', 61, 90), tier('s5', 'STORAGE', 91, null),
+      tier('r1', 'RETURN_STORAGE', 1, null),
+    ]
+    expect(addFeeTier(tiers, 'STORAGE')).toBeNull()
+    const storageTiers = tiers.filter((item) => item.feeType === 'STORAGE')
+    expect(storageTiers).toHaveLength(6)
+    expect(storageTiers.slice(-2).map(({ startDay, endDay }) => ({ startDay, endDay })))
+      .toEqual([{ startDay: 91, endDay: 91 }, { startDay: 92, endDay: null }])
+    expect(validateFeeTiers(tiers)).toBeNull()
+  })
+
+  it('removes a middle tier and extends the previous range', () => {
+    const tiers = [
+      tier('s1', 'STORAGE', 1, 7), tier('s2', 'STORAGE', 8, 30), tier('s3', 'STORAGE', 31, 60),
+      tier('s4', 'STORAGE', 61, 90), tier('s5', 'STORAGE', 91, null),
+      tier('r1', 'RETURN_STORAGE', 1, null),
+    ]
+    expect(removeFeeTier(tiers, tiers[2]!)).toBeNull()
+    const storageTiers = tiers.filter((item) => item.feeType === 'STORAGE')
+    expect(storageTiers).toHaveLength(4)
+    expect(storageTiers.slice(1, 3).map(({ startDay, endDay }) => ({ startDay, endDay })))
+      .toEqual([{ startDay: 8, endDay: 60 }, { startDay: 61, endDay: 90 }])
+    expect(validateFeeTiers(tiers)).toBeNull()
+  })
+
+  it('does not delete the only tier of a fee type', () => {
+    const tiers = [tier('s1', 'STORAGE', 1, null), tier('r1', 'RETURN_STORAGE', 1, null)]
+    expect(removeFeeTier(tiers, tiers[0]!)).toBe('每种费用至少需要保留1档')
+  })
+})
diff --git a/src/modules/customers/overseasStorageFeeTiers.ts b/src/modules/customers/overseasStorageFeeTiers.ts
new file mode 100644
index 00000000..c8b5b2d0
--- /dev/null
+++ b/src/modules/customers/overseasStorageFeeTiers.ts
@@ -0,0 +1,61 @@
+import type { OverseasFeeType, OverseasStorageFeeTier } from './overseasStorageFee'
+
+let temporaryTierId = 0
+
+export function tiersByType(tiers: OverseasStorageFeeTier[], feeType: OverseasFeeType) {
+  return tiers.filter((tier) => tier.feeType === feeType)
+}
+
+export function addFeeTier(tiers: OverseasStorageFeeTier[], feeType: OverseasFeeType) {
+  if (tiers.length >= 100) return '阶梯费用明细最多为100组'
+  const group = tiersByType(tiers, feeType)
+  const last = group.at(-1)
+  if (!last) return '每种费用至少需要保留1档'
+  if (last.startDay >= 36500) return '当前尾档已从第36500天开始，无法继续新增'
+
+  const startDay = last.startDay + 1
+  last.endDay = startDay - 1
+  const newTier: OverseasStorageFeeTier = {
+    ...last,
+    id: `new-${feeType}-${++temporaryTierId}`,
+    startDay,
+    endDay: null,
+    sortNo: last.sortNo + 1,
+  }
+  const lastIndex = tiers.indexOf(last)
+  tiers.splice(lastIndex + 1, 0, newTier)
+  return null
+}
+
+export function removeFeeTier(tiers: OverseasStorageFeeTier[], tier: OverseasStorageFeeTier) {
+  const group = tiersByType(tiers, tier.feeType)
+  if (group.length <= 1) return '每种费用至少需要保留1档'
+
+  const groupIndex = group.indexOf(tier)
+  const previous = group[groupIndex - 1]
+  const next = group[groupIndex + 1]
+  if (previous) previous.endDay = tier.endDay
+  else if (next) next.startDay = 1
+  tiers.splice(tiers.indexOf(tier), 1)
+  return null
+}
+
+export function validateFeeTiers(tiers: OverseasStorageFeeTier[]) {
+  if (tiers.length < 2 || tiers.length > 100) return '仓租和退货仓储费必须各保留至少1档，合计不超过100档'
+  for (const [feeType, label] of [['STORAGE', '仓租'], ['RETURN_STORAGE', '退货仓储费']] as const) {
+    const group = tiersByType(tiers, feeType)
+    if (group.length === 0) return `${label}至少需要保留1档`
+    let expected = 1
+    for (const [index, tier] of group.entries()) {
+      if (!Number.isInteger(tier.startDay) || tier.startDay !== expected || tier.startDay < 1) return `${label}第${index + 1}档天数必须连续且从第1天开始`
+      if (!Number.isFinite(tier.unitPrice) || tier.unitPrice < 0) return `${label}第${index + 1}档价格不能小于0`
+      if (index === group.length - 1) {
+        if (tier.endDay !== null) return `${label}最后一档必须为“以上”`
+      } else if (!Number.isInteger(tier.endDay) || tier.endDay! < tier.startDay) {
+        return `${label}第${index + 1}档结束天数无效`
+      }
+      if (tier.endDay !== null) expected = tier.endDay + 1
+    }
+  }
+  return null
+}
diff --git a/src/modules/customers/pages/CustomerDetailView.test.ts b/src/modules/customers/pages/CustomerDetailView.test.ts
new file mode 100644
index 00000000..0269d0c7
--- /dev/null
+++ b/src/modules/customers/pages/CustomerDetailView.test.ts
@@ -0,0 +1,147 @@
+import ElementPlus from 'element-plus'
+import { createPinia, setActivePinia } from 'pinia'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  downloadTenantQualification,
+  getPlatformTenant,
+  listPlatformTenantMembers,
+  listTenantQualifications,
+  type PlatformTenantResource,
+} from '@/modules/iam'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+import CustomerDetailView from './CustomerDetailView.vue'
+
+const { routerPush, routeControl } = vi.hoisted(() => ({
+  routerPush: vi.fn(),
+  routeControl: { setTenantId: (_tenantId: string) => {} },
+}))
+
+vi.mock('vue-router', async (importOriginal) => ({
+  ...await importOriginal<typeof import('vue-router')>(),
+  ...await (async () => {
+    const { reactive } = await import('vue')
+    const route = reactive({ params: { tenantId: '8' } })
+    routeControl.setTenantId = (tenantId: string) => { route.params.tenantId = tenantId }
+    return { useRoute: () => route }
+  })(),
+  useRouter: () => ({ push: routerPush }),
+}))
+
+vi.mock('@/modules/iam', () => ({
+  changePlatformTenantStatus: vi.fn(),
+  downloadTenantQualification: vi.fn(),
+  getPlatformTenant: vi.fn(),
+  listPlatformTenantMembers: vi.fn(),
+  listTenantQualifications: vi.fn(),
+  qualificationFileName: vi.fn((documentUrl: string) => documentUrl.split('/').at(-1) || '资质文件'),
+}))
+
+class ResizeObserverStub implements ResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+
+const tenant: PlatformTenantResource = {
+  id: '8', tenantCode: 'TEN8', tenantName: '柏悦物流', customerNickname: '柏', status: 'ACTIVE', legalName: '柏悦物流有限公司',
+  legalRepresentative: '张三', unifiedSocialCreditCode: '91440300MA5ABCDE12', contactName: '张三',
+  contactPhone: '13800138000', contactEmail: 'ops@example.com', servicePackage: '基础版', contactWechat: 'baiyue-ops',
+  salesOwnerName: '李四', paymentTermDays: 30, enterpriseType: '有限责任公司', establishedDate: '2020-01-01',
+  registeredCapital: 1000, registeredCapitalCurrency: 'CNY', registeredAddress: '深圳市宝安区', internalRemark: '重点客户',
+  createdAt: '2026-08-01T10:00:00', approvedAt: '2026-08-02T10:00:00',
+}
+
+enableAutoUnmount(afterEach)
+
+describe('CustomerDetailView', () => {
+  let pinia: ReturnType<typeof createPinia>
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    routeControl.setTenantId('8')
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+    Object.defineProperty(HTMLElement.prototype, 'scrollIntoView', { configurable: true, value: vi.fn() })
+    Object.defineProperty(URL, 'createObjectURL', { configurable: true, value: vi.fn(() => 'blob:qualification-preview') })
+    Object.defineProperty(URL, 'revokeObjectURL', { configurable: true, value: vi.fn() })
+    document.body.innerHTML = ''
+    pinia = createPinia()
+    setActivePinia(pinia)
+    const auth = useAuthStore()
+    auth.token = 'token'
+    auth.permissions = ['platform:customer:list', 'platform:user:list', 'platform:order:list', 'platform:finance:customer-account:list', 'platform:firstleg:container:list']
+    useAccessPreviewStore().initializeAfterLogin()
+    vi.mocked(getPlatformTenant).mockResolvedValue(tenant)
+    vi.mocked(listTenantQualifications).mockResolvedValue([{
+      id: 'qualification-1', tenantId: tenant.id, qualificationType: 'BUSINESS_LICENSE', certificateNo: tenant.unifiedSocialCreditCode,
+      documentUrl: '/files/license.png', status: 'SUPERSEDED', reviewComment: '已替换', validTo: null,
+    }])
+    vi.mocked(listPlatformTenantMembers).mockResolvedValue([{
+      membershipId: 'member-1', userId: 'user-1', authUserId: 'auth-1', username: 'merchant_admin', displayName: '张三',
+      phone: '13800138000', email: 'ops@example.com', memberType: 'OWNER', memberNo: null, status: 'ACTIVE', roleIds: [], roleNames: ['企业管理员'],
+    }])
+    vi.mocked(downloadTenantQualification).mockResolvedValue(new Blob(['image'], { type: 'image/png' }))
+  })
+
+  it('hides the deferred operating metrics and keeps enterprise users in detail content', async () => {
+    mount(CustomerDetailView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+
+    expect([...document.querySelectorAll('.detail-tabs button')].map((button) => button.getAttribute('aria-label'))).toEqual([
+      '基本信息', '计费规则', '操作日志',
+    ])
+    expect(document.body.textContent).not.toContain('累计运单')
+    expect(document.body.textContent).not.toContain('累计应收')
+    expect(document.body.textContent).not.toContain('在途柜量')
+    expect(document.querySelector('.overview-strip')).toBeNull()
+    expect(document.body.textContent).toContain('merchant_admin')
+    expect(document.body.textContent).toContain('企业管理员')
+    expect(document.body.textContent).toContain('公司联系电话')
+    expect(document.body.textContent).toContain('登录手机号')
+    expect(document.body.textContent).toContain('修改会影响登录')
+    expect(document.querySelector('.contact-panel .info-grid--three')).not.toBeNull()
+    expect(listPlatformTenantMembers).toHaveBeenCalledWith(tenant.id)
+    expect(document.body.textContent).toContain('已替换')
+
+    const billingTab = document.querySelector<HTMLButtonElement>('.detail-tabs button[aria-label="计费规则"]')
+    billingTab?.click()
+    await flushPromises()
+    expect(document.body.textContent).toContain('暂无尺寸计算规则查看权限')
+    expect(document.body.textContent).not.toContain('计费规则尚未接入')
+  })
+
+  it('opens an authenticated qualification preview', async () => {
+    mount(CustomerDetailView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+
+    const fileButton = document.querySelector<HTMLButtonElement>('.qualification-list button')
+    fileButton?.click()
+    await flushPromises()
+
+    expect(downloadTenantQualification).toHaveBeenCalledWith(tenant.id, '/files/license.png')
+    expect(document.querySelector('img[alt="license.png预览"]')).not.toBeNull()
+  })
+
+  it('reloads a reused detail view and ignores the previous customer response', async () => {
+    const secondTenant = { ...tenant, id: '9', tenantCode: 'TEN9', tenantName: '远航供应链', legalName: '远航供应链有限公司' }
+    let resolveFirstTenant!: (value: PlatformTenantResource) => void
+    const firstTenantRequest = new Promise<PlatformTenantResource>((resolve) => { resolveFirstTenant = resolve })
+    vi.mocked(getPlatformTenant).mockImplementation((tenantId) => tenantId === '8' ? firstTenantRequest : Promise.resolve(secondTenant))
+    vi.mocked(listTenantQualifications).mockResolvedValue([])
+    vi.mocked(listPlatformTenantMembers).mockResolvedValue([])
+    mount(CustomerDetailView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+    routeControl.setTenantId('9')
+    await flushPromises()
+
+    expect(getPlatformTenant).toHaveBeenCalledWith('9')
+    expect(document.body.textContent).toContain('远航供应链')
+
+    resolveFirstTenant(tenant)
+    await flushPromises()
+    expect(document.body.textContent).toContain('远航供应链')
+    expect(document.body.textContent).not.toContain('柏悦物流')
+  })
+
+})
diff --git a/src/modules/customers/pages/CustomerDetailView.vue b/src/modules/customers/pages/CustomerDetailView.vue
new file mode 100644
index 00000000..3581be5e
--- /dev/null
+++ b/src/modules/customers/pages/CustomerDetailView.vue
@@ -0,0 +1,352 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import '@/modules/customers/customerDensity.css'
+import { computed, onBeforeUnmount, ref, watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { Building2, FileCheck2, FileText, UserRound, UsersRound } from '@lucide/vue'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import {
+  changePlatformTenantStatus,
+  downloadTenantQualification,
+  getPlatformTenant,
+  listPlatformTenantMembers,
+  listTenantQualifications,
+  qualificationFileName,
+  type PlatformTenantQualification,
+  type PlatformTenantMember,
+  type PlatformTenantResource,
+  type PlatformTenantStatus,
+} from '@/modules/iam'
+import { getApiErrorDetails, getApiErrorMessage, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import DetailPageLayout from '@/shared/components/DetailPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import PageToolbar from '@/shared/components/PageToolbar.vue'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import CustomerBillingRulesPanel from '@/modules/customers/components/CustomerBillingRulesPanel.vue'
+import CustomerOverseasStorageFeePanel from '@/modules/customers/CustomerOverseasStorageFeePanel.vue'
+import { CustomerAuditLogsPanel } from '@/modules/audit'
+
+type DetailTab = 'basic' | 'billing' | 'logs'
+type PreviewState = { url: string; kind: 'image' | 'pdf'; loading: boolean; failed: boolean }
+
+const route = useRoute()
+const router = useRouter()
+const access = useAccessPreviewStore()
+const tenantId = computed(() => String(route.params.tenantId ?? ''))
+const activeTab = ref<DetailTab>('basic')
+const loading = ref(true)
+const statusChanging = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const customer = ref<PlatformTenantResource | null>(null)
+const qualifications = ref<PlatformTenantQualification[]>([])
+const members = ref<PlatformTenantMember[]>([])
+let detailRequestSerial = 0
+let disposed = false
+const previews = ref<Record<string, PreviewState>>({})
+const previewOpen = ref(false)
+const previewName = ref('')
+const previewUrl = ref('')
+const previewKind = ref<'image' | 'pdf'>('image')
+const tabList = ref<HTMLElement | null>(null)
+
+const tabs: Array<{ key: DetailTab; label: string; icon: string }> = [
+  { key: 'basic', label: '基本信息', icon: '📋' },
+  { key: 'billing', label: '计费规则', icon: '⚖️' },
+  { key: 'logs', label: '操作日志', icon: '📝' },
+]
+
+const enterpriseMembers = computed(() => members.value.filter((member) => ['OWNER', 'EMPLOYEE'].includes(member.memberType)))
+function displayText(value?: string | null) { return value?.trim() || '—' }
+function formatDate(value?: string | null) { return value ? value.replace('T', ' ').slice(0, 16) : '—' }
+function formatCapital(value: number | string | null, currency: string | null) {
+  if (value === null || value === '') return '—'
+  const numericValue = Number(value)
+  if (!Number.isFinite(numericValue)) return '—'
+  const label = currency === 'USD' ? '美元' : currency === 'HKD' ? '港币' : '人民币'
+  return `${numericValue.toLocaleString('zh-CN')} ${label}`
+}
+function statusMeta(status: PlatformTenantStatus) {
+  if (status === 'ACTIVE') return { label: '启用', type: 'success' as const }
+  if (status === 'PROFILE_REQUIRED') return { label: '待完善', type: 'info' as const }
+  if (status === 'PENDING') return { label: '待审核', type: 'warning' as const }
+  if (status === 'REJECTED') return { label: '已驳回', type: 'danger' as const }
+  if (status === 'ARCHIVED') return { label: '已归档', type: 'info' as const }
+  return { label: '已停用', type: 'info' as const }
+}
+function qualificationLabel(type: string) {
+  return ({ BUSINESS_LICENSE: '营业执照', LEGAL_PERSON_ID: '法人身份证', FREIGHT_FORWARDER_CERTIFICATE: '货代资质证书', BANK_ACCOUNT_LICENSE: '银行开户许可证' } as Record<string, string>)[type] || '未知资质类型'
+}
+function qualificationStatus(status: PlatformTenantQualification['status']) {
+  if (status === 'APPROVED') return { label: '已通过', type: 'success' as const }
+  if (status === 'REJECTED') return { label: '已驳回', type: 'danger' as const }
+  if (status === 'SUPERSEDED') return { label: '已替换', type: 'info' as const }
+  return { label: '待审核', type: 'warning' as const }
+}
+function qualificationName(item: PlatformTenantQualification) {
+  try { return qualificationFileName(item.documentUrl) }
+  catch { return `${qualificationLabel(item.qualificationType)}文件` }
+}
+function clearPreviews() {
+  for (const preview of Object.values(previews.value)) if (preview.url) URL.revokeObjectURL(preview.url)
+  previews.value = {}
+  previewOpen.value = false
+}
+
+async function loadPreview(item: PlatformTenantQualification, notify = true) {
+  const state = previews.value[String(item.id)]
+  if (!state || state.loading) return false
+  state.loading = true
+  try {
+    const blob = await downloadTenantQualification(tenantId.value, item.documentUrl)
+    if (!blob.size) throw new Error('资质文件内容为空')
+    if (state.url) URL.revokeObjectURL(state.url)
+    state.url = URL.createObjectURL(blob)
+    state.kind = blob.type === 'application/pdf' || qualificationName(item).toLowerCase().endsWith('.pdf') ? 'pdf' : 'image'
+    state.failed = false
+    return true
+  } catch (error) {
+    state.failed = true
+    if (notify) ElMessage.error(getApiErrorMessage(error, '资质文件预览加载失败'))
+    return false
+  } finally { state.loading = false }
+}
+
+async function openPreview(item: PlatformTenantQualification) {
+  const state = previews.value[String(item.id)]
+  if (!state) return
+  if (!state.url) await loadPreview(item)
+  if (!state.url) return
+  previewName.value = qualificationName(item)
+  previewUrl.value = state.url
+  previewKind.value = state.kind
+  previewOpen.value = true
+}
+
+async function loadDetail() {
+  const requestedTenantId = tenantId.value
+  const serial = ++detailRequestSerial
+  loading.value = true
+  loadError.value = null
+  clearPreviews()
+  customer.value = null
+  qualifications.value = []
+  members.value = []
+  try {
+    const [tenantResult, qualificationResult, memberResult] = await Promise.all([
+      getPlatformTenant(requestedTenantId),
+      listTenantQualifications(requestedTenantId),
+      listPlatformTenantMembers(requestedTenantId),
+    ])
+    if (disposed || serial !== detailRequestSerial || requestedTenantId !== tenantId.value) return
+    customer.value = tenantResult
+    qualifications.value = qualificationResult
+    members.value = memberResult
+    previews.value = Object.fromEntries(qualificationResult.map((item) => [String(item.id), {
+      url: '', kind: qualificationName(item).toLowerCase().endsWith('.pdf') ? 'pdf' : 'image', loading: false, failed: false,
+    } satisfies PreviewState]))
+  } catch (error) {
+    if (disposed || serial !== detailRequestSerial || requestedTenantId !== tenantId.value) return
+    customer.value = null
+    qualifications.value = []
+    members.value = []
+    loadError.value = getApiErrorDetails(error, '客户详情加载失败，请稍后重试')
+  } finally {
+    if (!disposed && serial === detailRequestSerial) loading.value = false
+  }
+}
+
+async function changeStatus() {
+  if (!customer.value || statusChanging.value) return
+  const next = customer.value.status === 'ACTIVE' ? 'DISABLED' : 'ACTIVE'
+  const verb = next === 'ACTIVE' ? '启用' : '停用'
+  try {
+    await ElMessageBox.confirm(`确认${verb}客户“${customer.value.tenantName}”吗？`, `${verb}客户`, {
+      customClass: 'admin-density-confirm', type: 'warning', confirmButtonText: `确认${verb}`, cancelButtonText: '取消',
+    })
+    statusChanging.value = true
+    customer.value = await changePlatformTenantStatus(tenantId.value, next)
+    ElMessage.success(`客户已${verb}`)
+  } catch (error) {
+    if (error !== 'cancel' && error !== 'close') ElMessage.error(getApiErrorMessage(error, `客户${verb}失败`))
+  } finally { statusChanging.value = false }
+}
+
+function goEdit() { void router.push({ name: 'customers', query: { edit: tenantId.value } }) }
+function selectTab(key: DetailTab, button?: HTMLElement) {
+  activeTab.value = key
+  button?.scrollIntoView({ behavior: 'smooth', block: 'nearest', inline: 'nearest' })
+}
+function handleTabKeydown(event: KeyboardEvent, key: DetailTab) {
+  if (!['ArrowLeft', 'ArrowRight', 'Home', 'End'].includes(event.key)) return
+  event.preventDefault()
+  const current = tabs.findIndex((item) => item.key === key)
+  const next = event.key === 'Home' ? 0 : event.key === 'End' ? tabs.length - 1 : event.key === 'ArrowRight' ? (current + 1) % tabs.length : (current - 1 + tabs.length) % tabs.length
+  const button = tabList.value?.querySelectorAll<HTMLButtonElement>('[role="tab"]')[next]
+  button?.focus()
+  selectTab(tabs[next].key, button)
+}
+watch(tenantId, (value) => {
+  activeTab.value = 'basic'
+  if (value) void loadDetail()
+  else {
+    detailRequestSerial += 1
+    loading.value = false
+    customer.value = null
+    qualifications.value = []
+    members.value = []
+  }
+}, { immediate: true })
+onBeforeUnmount(() => {
+  disposed = true
+  detailRequestSerial += 1
+  clearPreviews()
+})
+</script>
+
+<template>
+  <!--
+  THESIS: 客户档案是一张可核验的运营工作台，不是被抽屉压缩的字段清单。
+  OWN-WORLD: 延续后台冷灰底、白色数据面板、紫蓝主色与克制的状态色。
+  STORY: 运营先确认企业状态，再查看客户资料、计费规则和操作日志。
+  FIRST VIEWPORT: 客户身份与动作居首，三个页签形成稳定内容索引。
+  FORM: 精确继承原型的详情工作台结构，以现有后台组件体系实现。
+  FINISH: unreviewed and undocumented is unfinished; this build ends with the finish review, the verdict, and DESIGN.md
+  -->
+  <AdminPage as="div" class="customer-detail-page admin-density customer-density">
+    <LoadErrorState v-if="loadError" title="客户详情暂时无法加载" :message="loadError.message" :loading="loading" @retry="loadDetail">
+      <template #details><ApiErrorMeta :details="loadError" /></template>
+    </LoadErrorState>
+
+    <DetailPageLayout v-else v-loading="loading" aria-label="客户详情">
+      <template #header>
+        <header class="detail-header">
+          <el-button link class="back-button density-back" @click="router.push({ name: 'customers' })">返回列表</el-button>
+          <PageToolbar class="detail-page-toolbar" as="section" :title="customer?.tenantName || '客户详情'" :description="customer?.tenantCode || '客户资料'">
+            <template #actions>
+              <div v-if="customer" class="header-actions">
+                <el-tag :type="statusMeta(customer.status).type" effect="light" round>{{ statusMeta(customer.status).label }}</el-tag>
+                <el-button v-if="access.can('platform:customer:edit') && customer.status !== 'ARCHIVED'" @click="goEdit">编辑信息</el-button>
+                <el-button v-if="access.can('platform:customer:status') && ['ACTIVE', 'DISABLED'].includes(customer.status)" :type="customer.status === 'ACTIVE' ? 'danger' : 'success'" :loading="statusChanging" @click="changeStatus">{{ customer.status === 'ACTIVE' ? '停用账号' : '启用账号' }}</el-button>
+              </div>
+            </template>
+          </PageToolbar>
+        </header>
+      </template>
+
+      <!-- <template #summary>
+        <section class="overview-strip" aria-label="客户概况">
+          <CustomerOperatingMetricCard title="累计运单" :value="String(orderStatistics.data?.totalSubmittedOrders ?? '')" unit="票" :detail="`本月 ${orderStatistics.data?.currentMonthSubmittedOrders ?? 0} 票`" tone="blue" :loading="orderStatistics.loading" :failed="orderStatistics.failed" :unauthorized="!access.can('platform:order:list')"><template #icon><Ship :size="20" /></template></CustomerOperatingMetricCard>
+          <CustomerOperatingMetricCard title="累计应收" :value="cnyWan(financeStatistics.data?.totalReceivable)" unit="万元" :detail="`未结清 ${cnyWan(financeStatistics.data?.outstandingReceivable)} 万元`" tone="green" :loading="financeStatistics.loading" :failed="financeStatistics.failed" :unauthorized="!access.can('platform:finance:customer-account:list')"><template #icon><CircleDollarSign :size="20" /></template></CustomerOperatingMetricCard>
+          <CustomerOperatingMetricCard title="在途柜量" :value="decimalText(transitStatistics.data?.totalTeu)" unit="TEU" :detail="`${transitStatistics.data?.containerCount ?? 0} 柜${transitStatistics.data?.unknownContainerCount ? ` · 另有 ${transitStatistics.data.unknownContainerCount} 柜柜型未知，未计入TEU` : ''}`" tone="amber" :loading="transitStatistics.loading" :failed="transitStatistics.failed" :unauthorized="!access.can('platform:firstleg:container:list')"><template #icon><Container :size="20" /></template></CustomerOperatingMetricCard>
+        </section>
+      </template> -->
+
+      <div ref="tabList" class="detail-tabs density-tabs" role="tablist" aria-label="客户详情模块">
+          <button v-for="tab in tabs" :id="`customer-tab-${tab.key}`" :key="tab.key" type="button" role="tab" :class="{ active: activeTab === tab.key }" :aria-label="tab.label" :aria-selected="activeTab === tab.key" :aria-controls="`customer-panel-${tab.key}`" :tabindex="activeTab === tab.key ? 0 : -1" @click="selectTab(tab.key, $event.currentTarget as HTMLElement)" @keydown="handleTabKeydown($event, tab.key)"><span class="density-tab-icon" aria-hidden="true">{{ tab.icon }}</span><span>{{ tab.label }}</span></button>
+        </div>
+
+        <div v-if="customer" :id="`customer-panel-${activeTab}`" class="tab-panel" role="tabpanel" :aria-labelledby="`customer-tab-${activeTab}`" tabindex="0">
+          <template v-if="activeTab === 'basic'">
+            <div class="basic-layout">
+              <section class="detail-panel company-panel">
+                <div class="panel-title"><div><h2>企业基本信息</h2><p>工商档案与合作配置</p></div><Building2 :size="19" /></div>
+                <dl class="info-grid density-fields">
+                  <div><dt>公司名称</dt><dd>{{ displayText(customer.legalName || customer.tenantName) }}</dd></div>
+                  <div><dt>客户昵称</dt><dd>{{ displayText(customer.customerNickname) }}</dd></div>
+                  <div><dt>统一社会信用代码</dt><dd>{{ displayText(customer.unifiedSocialCreditCode) }}</dd></div>
+                  <div><dt>企业类型</dt><dd>{{ displayText(customer.enterpriseType) }}</dd></div>
+                  <div><dt>法定代表人</dt><dd>{{ displayText(customer.legalRepresentative) }}</dd></div>
+                  <div><dt>成立日期</dt><dd>{{ formatDate(customer.establishedDate).slice(0, 10) }}</dd></div>
+                  <div><dt>注册资本</dt><dd>{{ formatCapital(customer.registeredCapital, customer.registeredCapitalCurrency) }}</dd></div>
+                  <div class="wide"><dt>注册地址</dt><dd>{{ displayText(customer.registeredAddress) }}</dd></div>
+                </dl>
+              </section>
+              <section class="detail-panel qualification-panel">
+                <div class="panel-title"><div><h2>资质文件</h2><p>共 {{ qualifications.length }} 份</p></div><FileText :size="19" /></div>
+                <div v-if="qualifications.length" class="qualification-list">
+                  <button v-for="item in qualifications" :key="String(item.id)" type="button" :disabled="previews[String(item.id)]?.loading" @click="openPreview(item)">
+                    <span><strong>{{ qualificationLabel(item.qualificationType) }}</strong><small>{{ qualificationName(item) }}</small></span><el-tag :type="qualificationStatus(item.status).type" effect="light" size="small">{{ qualificationStatus(item.status).label }}</el-tag><span class="file-date">{{ item.validTo || '长期有效' }}</span><span class="file-preview-label">预览</span>
+                  </button>
+                </div>
+                <div v-else class="section-empty"><FileCheck2 :size="22" /><strong>暂无资质文件</strong><span>客户尚未上传企业资质</span></div>
+              </section>
+              <section class="detail-panel contact-panel">
+                <div class="panel-title"><div><h2>联系与合作信息</h2><p>客户联络及内部跟进信息</p></div><UserRound :size="19" /></div>
+                <dl class="info-grid info-grid--three density-fields">
+                  <div><dt>联系人</dt><dd>{{ displayText(customer.contactName) }}</dd></div><div><dt>公司联系电话</dt><dd>{{ displayText(customer.contactPhone) }}</dd></div>
+                  <div><dt>联系邮箱</dt><dd>{{ displayText(customer.contactEmail) }}</dd></div><div><dt>联系微信</dt><dd>{{ displayText(customer.contactWechat) }}</dd></div>
+                  <div><dt>客户套餐</dt><dd>{{ displayText(customer.servicePackage) }}</dd></div><div><dt>账期</dt><dd>{{ customer.paymentTermDays ?? 0 }} 天</dd></div>
+                  <div><dt>销售人员</dt><dd>{{ displayText(customer.salesOwnerName) }}</dd></div><div><dt>入驻时间</dt><dd>{{ formatDate(customer.createdAt) }}</dd></div>
+                  <div class="wide"><dt>内部备注</dt><dd>{{ displayText(customer.internalRemark) }}</dd></div>
+                </dl>
+              </section>
+              <section class="detail-panel user-panel">
+                <div class="panel-title"><div><h2>企业用户</h2><p>登录手机号属于账号信息；请在成员/账号管理中单独维护，修改会影响登录</p></div><UsersRound :size="19" /></div>
+                <div v-if="enterpriseMembers.length" class="user-table-wrap">
+                  <table><thead><tr><th>账号</th><th>成员类型</th><th>登录手机号</th><th>邮箱</th><th>角色</th><th>状态</th></tr></thead>
+                    <tbody><tr v-for="member in enterpriseMembers" :key="String(member.membershipId)">
+                      <td><div class="user-identity"><span>{{ (member.displayName || member.username || '?').slice(0, 1) }}</span><div><strong>{{ displayText(member.username) }}</strong><small>{{ displayText(member.displayName) }}</small></div></div></td>
+                      <td>{{ member.memberType === 'OWNER' ? '企业管理员' : '企业员工' }}</td>
+                      <td>{{ displayText(member.phone) }}</td>
+                      <td>{{ displayText(member.email) }}</td>
+                      <td><div v-if="member.roleNames?.length" class="role-list"><el-tag v-for="role in member.roleNames" :key="role" size="small" effect="plain">{{ role }}</el-tag></div><span v-else>—</span></td>
+                      <td><el-tag :type="member.status === 'ACTIVE' ? 'success' : 'info'" effect="light" size="small">{{ member.status === 'ACTIVE' ? '启用' : '停用' }}</el-tag></td>
+                    </tr></tbody>
+                  </table>
+                </div>
+                <div v-else class="section-empty"><UsersRound :size="22" /><strong>暂无企业用户</strong><span>当前客户尚未创建企业成员账号</span></div>
+              </section>
+            </div>
+          </template>
+
+          <section v-else-if="activeTab === 'logs'" class="detail-panel module-panel"><CustomerAuditLogsPanel :customer-id="tenantId" :customer-name="customer.tenantName" /></section>
+          <section v-else class="detail-panel module-panel"><CustomerBillingRulesPanel :customer-id="tenantId" :customer-name="customer.tenantName" :customer-code="customer.tenantCode" :dimension-initialization-status="customer.dimensionInitializationStatus" /><CustomerOverseasStorageFeePanel :customer-id="tenantId" :customer-name="customer.tenantName" /></section>
+      </div>
+    </DetailPageLayout>
+
+    <AppDialog class="admin-density-dialog customer-density-dialog" v-model="previewOpen" :title="previewName" width="min(920px, calc(100vw - 28px))" append-to-body :show-footer="false">
+      <div class="qualification-preview"><img v-if="previewKind === 'image'" :src="previewUrl" :alt="`${previewName}预览`" /><iframe v-else :src="previewUrl" :title="`${previewName}预览`" /></div>
+    </AppDialog>
+  </AdminPage>
+</template>
+
+<style scoped>
+.detail-tabs { border-bottom: 1px solid var(--cc-border); }
+
+.customer-detail-page { min-width: 0; }
+.detail-header { display:flex; min-width:0; align-items:center; gap:var(--admin-space-5, 12px); }
+.back-button { flex:0 0 auto; }
+.detail-page-toolbar { min-width:0; flex:1; }
+.header-actions { display:flex; flex:0 0 auto; gap:var(--admin-space-3, 8px); }
+.header-actions :deep(.el-button + .el-button) { margin-left:0; }
+.basic-layout { display:grid; align-items:start; }
+.detail-panel { min-width:0; }
+.contact-panel { grid-column:1 / -1; }
+.user-panel { grid-column:1 / -1; }
+.panel-title { display:flex; justify-content:space-between; border-bottom:1px solid var(--cc-border); }
+.panel-title h2 { margin:0; color:#344054; }.panel-title p { margin:5px 0 0; color:var(--cc-muted); }.panel-title > svg { color:var(--cc-primary); }
+.info-grid { margin:0; }.info-grid > div.wide { grid-column:1 / -1; }
+.qualification-list { display:flex; flex-direction:column; }
+.qualification-list button { display:grid; width:100%; align-items:center; background:var(--admin-surface, #fff); color:inherit; text-align:left; cursor:pointer; }
+.qualification-list button:hover { border-color:#b9c3f5; background:#fafbff; }.qualification-list button:disabled { cursor:wait; opacity:.65; }
+.qualification-list strong { display:block; }
+.qualification-list small { display:block; }.qualification-list small { margin-top:3px; color:var(--cc-muted); }.file-date { margin-top:3px; color:var(--cc-muted); }.file-date { margin:0; white-space:nowrap; }
+.section-empty { display:flex; align-items:center; justify-content:center; flex-direction:column; color:#98a2b3; text-align:center; }
+.module-empty { display:flex; align-items:center; justify-content:center; flex-direction:column; color:#98a2b3; text-align:center; }
+.section-empty strong { color:#475467; font-size:var(--admin-font-body, 13px); }
+.module-empty strong { color:#475467; font-size:var(--admin-font-body, 13px); }.section-empty span { max-width:600px; margin:0; color:var(--cc-muted); line-height:1.7; }.module-empty p { max-width:600px; margin:0; color:var(--cc-muted); font-size:var(--admin-font-caption, 11px); line-height:1.7; }
+.section-empty button { border:0; background:transparent; color:var(--cc-primary); cursor:pointer; }.section-empty.is-error svg { color:#d92d20; }
+.user-table-wrap { overflow-x:auto; }
+table { width:100%; min-width:720px; border-collapse:collapse; font-size:var(--admin-font-caption, 12px); }th { padding:var(--admin-space-4, 10px) var(--admin-space-5, 12px); background:var(--admin-label-bg, #f8fafc); color:#667085; text-align:left; font-weight:650; }td { padding:var(--admin-space-5, 12px); border-top:1px solid #edf0f4; color:#344054; }
+.user-identity { display:flex; align-items:center; gap:9px; }.user-identity > span { width:34px; height:34px; flex:0 0 auto; place-items:center; border-radius:50%; background:#eef1ff; color:var(--cc-primary); font-weight:700; }.user-identity strong { display:block; }.user-identity small { display:block; }.user-identity small { margin-top:3px; color:var(--cc-muted); }.role-list { display:flex; flex-wrap:wrap; gap:5px; }
+.member-contact span { display:block; }
+.member-contact small { display:block; }.member-contact small { margin-top:3px; color:var(--cc-muted); }.module-empty > svg { color:#8797b2; }.module-empty p { max-width:520px; font-size:var(--admin-font-caption, 12px); }
+.contract-note { padding:var(--admin-space-6, 16px) 18px; border-radius:10px; background:var(--admin-label-bg, #f8fafc); }.contract-note strong { color:#344054; font-size:var(--admin-font-caption, 12px); }.contract-note p { margin:5px 0 0; color:var(--cc-muted); font-size:var(--admin-font-caption, 11px); line-height:1.7; }
+.qualification-preview { display:grid; min-height:320px; max-height:72vh; overflow:auto; place-items:center; border-radius:10px; background:var(--admin-label-bg, #f8fafc); }.qualification-preview img { display:block; max-width:100%; height:auto; }.qualification-preview iframe { width:100%; min-height:68vh; border:0; background:var(--admin-surface, #fff); }
+@media (max-width:960px) { .basic-layout { grid-template-columns:1fr; }.contact-panel,.user-panel { grid-column:auto; }.qualification-panel { order:3; }.user-panel { order:4; }.info-grid--three { grid-template-columns:repeat(2,minmax(0,1fr)); } }
+@media (max-width:720px) { .detail-header { align-items:flex-start; flex-wrap:wrap; }.detail-page-toolbar { width:100%; flex-basis:100%; }.company-mark { width:40px; height:40px; }.header-actions { display:grid; grid-template-columns:repeat(2,minmax(0,1fr)); width:100%; }.header-actions :deep(.el-tag) { grid-column:1 / -1; justify-self:start; }.header-actions :deep(.el-button) { min-height:44px; }.detail-panel { padding:16px; }.info-grid { grid-template-columns:1fr; }.info-grid > div.wide { grid-column:auto; } }
+@media (max-width:420px) { .company-mark { display:none; }.header-actions { grid-template-columns:1fr; }.header-actions :deep(.el-tag) { grid-column:auto; }.qualification-list button { grid-template-columns:36px minmax(0,1fr) auto; }.qualification-list .file-date,.qualification-list button > svg { display:none; } }
+</style>
diff --git a/src/modules/customers/pages/CustomersView.test.ts b/src/modules/customers/pages/CustomersView.test.ts
new file mode 100644
index 00000000..7c354dc2
--- /dev/null
+++ b/src/modules/customers/pages/CustomersView.test.ts
@@ -0,0 +1,806 @@
+import ElementPlus, { ElMessageBox } from 'element-plus'
+import { createPinia, setActivePinia } from 'pinia'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  approveEnterpriseReview,
+  archivePlatformTenant,
+  createPlatformTenant,
+  downloadTenantQualification,
+  createPlatformTenantImpersonation,
+  getPlatformTenant,
+  listEnterpriseReviews,
+  listPlatformTenants,
+  listTenantQualifications,
+  rejectEnterpriseReview,
+  resetPlatformTenantOwnerPassword,
+  submitPlatformTenantReview,
+  updatePlatformTenant,
+  uploadPlatformTenantQualification,
+  uploadPlatformTenantRequiredQualificationPackage,
+  type EnterpriseReview,
+  type PlatformTenantResource,
+} from '@/modules/iam'
+import { createPlatformExportTask } from '@/modules/downloads'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+import QueryToolbar from '@/shared/components/QueryToolbar.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import { showExportTaskCreatedDialog } from '@/shared/components/exportTaskCreatedDialog'
+import CustomersView from './CustomersView.vue'
+
+const customersSource = readFileSync(resolve(process.cwd(), 'src/modules/customers/pages/CustomersView.vue'), 'utf8')
+
+const { routerPush, routerReplace, routeControl } = vi.hoisted(() => ({
+  routerPush: vi.fn(),
+  routerReplace: vi.fn(),
+  routeControl: { setEditId: (_editId: string) => {} },
+}))
+
+vi.mock('vue-router', async (importOriginal) => ({
+  ...await importOriginal<typeof import('vue-router')>(),
+  ...await (async () => {
+    const { reactive } = await import('vue')
+    const route = reactive<{ query: { edit?: string } }>({ query: {} })
+    routeControl.setEditId = (editId: string) => {
+      if (editId) route.query.edit = editId
+      else delete route.query.edit
+    }
+    return { useRoute: () => route }
+  })(),
+  useRouter: () => ({ push: routerPush, replace: routerReplace }),
+}))
+
+vi.mock('@/modules/iam', () => ({
+  approveEnterpriseReview: vi.fn(),
+  archivePlatformTenant: vi.fn(),
+  changePlatformTenantStatus: vi.fn(),
+  checkPlatformTenantContactPhone: vi.fn().mockResolvedValue(true),
+  createPlatformTenant: vi.fn(),
+  createPlatformTenantImpersonation: vi.fn(),
+  downloadTenantQualification: vi.fn(),
+  getPlatformTenant: vi.fn(),
+  listEnterpriseReviews: vi.fn(),
+  listPlatformTenantOrderCounts: vi.fn(),
+  listPlatformTenants: vi.fn(),
+  listTenantQualifications: vi.fn(),
+  qualificationFileName: vi.fn((documentUrl: string) => documentUrl.split('/').at(-1) || '资质文件'),
+  rejectEnterpriseReview: vi.fn(),
+  resetPlatformTenantOwnerPassword: vi.fn(),
+  submitPlatformTenantReview: vi.fn(),
+  updatePlatformTenant: vi.fn(),
+  uploadPlatformTenantQualification: vi.fn(),
+  uploadPlatformTenantRequiredQualificationPackage: vi.fn(),
+}))
+
+vi.mock('@/modules/downloads', () => ({ createPlatformExportTask: vi.fn() }))
+vi.mock('@/shared/components/exportTaskCreatedDialog', () => ({ showExportTaskCreatedDialog: vi.fn() }))
+
+class ResizeObserverStub implements ResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+
+const fullTenant: PlatformTenantResource = {
+  id: '8', tenantCode: 'TEN8', tenantName: '柏悦物流', customerNickname: '柏', status: 'PROFILE_REQUIRED',
+  legalName: '柏悦物流有限公司', legalRepresentative: '张三', unifiedSocialCreditCode: '91440300MA5ABCDE12',
+  contactName: '张三', contactPhone: '13800138000', contactEmail: 'ops@example.com',
+  servicePackage: '基础版', contactWechat: 'baiyue-ops', salesOwnerName: '李四', paymentTermDays: 30,
+  enterpriseType: '有限责任公司', establishedDate: '2020-01-01', registeredCapital: 1000,
+  registeredCapitalCurrency: 'CNY', registeredAddress: '深圳市宝安区', internalRemark: '重点客户',
+  createdAt: '2026-08-01T10:00:00', approvedAt: null,
+}
+
+const pendingReview: EnterpriseReview = {
+  id: '190000000000000001',
+  tenantId: fullTenant.id,
+  tenantName: fullTenant.tenantName,
+  tenantCode: fullTenant.tenantCode,
+  status: 'PENDING',
+}
+
+function tableButtonByText(text: string) {
+  return [...document.querySelectorAll<HTMLButtonElement>('.el-table__body button')]
+    .find((button) => button.textContent?.trim() === text)
+}
+
+function selectQualificationFile(index: number, file: File) {
+  const input = document.querySelectorAll<HTMLInputElement>('.qualification-file input[type="file"]')[index]
+  Object.defineProperty(input, 'files', { configurable: true, value: [file] })
+  input.dispatchEvent(new Event('change', { bubbles: true }))
+}
+
+async function clickMoreAction(text: string) {
+  document.querySelector<HTMLButtonElement>('.el-table__body button[aria-label^="更多客户操作："]')?.click()
+  await flushPromises()
+  const item = [...document.querySelectorAll<HTMLElement>('.el-dropdown-menu__item')]
+    .find((candidate) => candidate.textContent?.trim() === text && !candidate.classList.contains('is-disabled'))
+  expect(item).toBeDefined()
+  item!.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+  await flushPromises()
+}
+
+enableAutoUnmount(afterEach)
+
+describe('CustomersView', () => {
+  let pinia: ReturnType<typeof createPinia>
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    routeControl.setEditId('')
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+    Object.defineProperty(URL, 'createObjectURL', { configurable: true, value: vi.fn(() => 'blob:qualification-preview') })
+    Object.defineProperty(URL, 'revokeObjectURL', { configurable: true, value: vi.fn() })
+    document.body.innerHTML = ''
+    pinia = createPinia()
+    setActivePinia(pinia)
+    const auth = useAuthStore()
+    auth.token = 'token'
+    auth.permissions = ['platform:customer:list', 'platform:customer:edit', 'platform:customer:export', 'platform:download:list']
+    useAccessPreviewStore().initializeAfterLogin()
+    vi.mocked(listPlatformTenants).mockResolvedValue({
+      records: [{ ...fullTenant, contactPhone: '138****8000', contactEmail: 'o***@example.com' }],
+      page: 1, size: 10, total: 1, pages: 1,
+    })
+    vi.mocked(getPlatformTenant).mockResolvedValue(fullTenant)
+    vi.mocked(listTenantQualifications).mockResolvedValue([])
+    vi.mocked(listEnterpriseReviews).mockResolvedValue([])
+    vi.mocked(createPlatformTenant).mockResolvedValue({
+      tenant: fullTenant, administratorUsername: 'merchant_owner', temporaryPassword: 'Temporary#2026',
+    })
+    vi.mocked(submitPlatformTenantReview).mockResolvedValue({ ...fullTenant, status: 'PENDING' })
+    vi.mocked(updatePlatformTenant).mockResolvedValue(fullTenant)
+    vi.mocked(uploadPlatformTenantQualification).mockResolvedValue({
+      qualificationId: 'qualification-1', reviewId: null, tenantStatus: 'PROFILE_REQUIRED', documentUrl: '/files/license.png',
+    })
+    vi.mocked(uploadPlatformTenantRequiredQualificationPackage).mockResolvedValue({
+      businessLicenseQualificationId: 'qualification-business',
+      legalPersonIdQualificationId: 'qualification-legal',
+      tenantStatus: 'PROFILE_REQUIRED',
+      businessLicenseDocumentUrl: '/files/license.png',
+      legalPersonIdDocumentUrl: '/files/legal-person-new.png',
+    })
+    vi.mocked(createPlatformExportTask).mockResolvedValue({
+      id: 'export-1', taskName: '客户列表', taskNo: 'EXP2084', status: 'PENDING',
+    } as never)
+    vi.mocked(showExportTaskCreatedDialog).mockResolvedValue(false)
+  })
+
+  it('waits for the client workspace to confirm impersonation session persistence', () => {
+    expect(customersSource).toContain("searchParams.set('impersonationOrigin', window.location.origin)")
+    expect(customersSource).toContain("event.data?.type !== 'impersonation-complete'")
+    expect(customersSource).toContain("event.data?.type === 'impersonation-failed'")
+    expect(customersSource).toContain("ElMessage.success('客户工作台登录成功')")
+  })
+
+  it('searches the customer list by customer name only', () => {
+    expect(customersSource).toContain("label: '客户名称', placeholder: '请输入客户名称'")
+    expect(customersSource).toContain("label: '客户昵称'")
+    expect(customersSource).toContain('中文拼音大写首字母，如 SZWL')
+    expect(customersSource).not.toContain('公司名称、客户编号或联系人')
+    expect(customersSource).not.toContain('row.tenantCode.toLowerCase().includes(keyword)')
+    expect(customersSource).not.toContain('String(row.id).includes(keyword)')
+  })
+
+  it('matches the frozen prototype containers for customer operations', () => {
+    expect(customersSource).toContain("router.push({ name: 'customer-detail'")
+    expect(customersSource).toContain("const editorDialogWidth = 'min(1120px, calc(100vw - 28px))'")
+    expect(customersSource.match(/class="form-grid three-cols"/g)).toHaveLength(2)
+    expect(customersSource).toContain('width="min(520px, calc(100vw - 28px))" class="admin-density-dialog customer-density-dialog customer-password-dialog"')
+    expect(customersSource).toContain('width="min(1040px, calc(100vw - 28px))" class="admin-density-dialog customer-density-dialog review-decision-dialog"')
+    expect(customersSource).not.toContain('<AppDrawer v-model="editorOpen"')
+  })
+
+  it('reserves enough space for qualification validity dates without widening the upload column', () => {
+    expect(customersSource).toContain('class="qualification-validity" role="cell"')
+    expect(customersSource).toContain('grid-template-columns:170px minmax(0,1fr) 220px')
+    expect(customersSource).toContain('.qualification-validity :deep(.el-date-editor) { width:100%; min-width:0; }')
+    expect(customersSource).toContain('.qualification-file-name { min-width:0;')
+    expect(readFileSync(resolve(process.cwd(), 'src/modules/customers/customerDensity.css'), 'utf8')).toContain('max-width: none; overflow-wrap: anywhere; white-space: normal;')
+  })
+
+  it('loads the complete customer detail before editing masked list fields', async () => {
+    mount(CustomersView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+
+    tableButtonByText('编辑')?.click()
+    await flushPromises()
+
+    expect(getPlatformTenant).toHaveBeenCalledWith(fullTenant.id)
+    const phone = document.querySelector<HTMLInputElement>('input[placeholder="请输入公司联系电话"]')
+    const email = document.querySelector<HTMLInputElement>('input[placeholder="如：contact@example.com"]')
+    expect(phone?.value).toBe(fullTenant.contactPhone)
+    expect(email?.value).toBe(fullTenant.contactEmail)
+  })
+
+  it('shows an authenticated image preview for an uploaded qualification', async () => {
+    vi.mocked(listTenantQualifications).mockResolvedValue([{
+      id: 'qualification-1', tenantId: fullTenant.id, qualificationType: 'BUSINESS_LICENSE',
+      certificateNo: fullTenant.unifiedSocialCreditCode, documentUrl: '/files/license.png',
+      status: 'PENDING', reviewComment: null, validTo: null,
+    }])
+    vi.mocked(downloadTenantQualification).mockResolvedValue(new Blob(['image'], { type: 'image/png' }))
+
+    mount(CustomersView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+    tableButtonByText('编辑')?.click()
+    await flushPromises()
+    await flushPromises()
+
+    expect(downloadTenantQualification).toHaveBeenCalledWith(fullTenant.id, '/files/license.png')
+    const preview = document.querySelector<HTMLImageElement>('img[alt="营业执照预览"]')
+    expect(preview?.src).toBe('blob:qualification-preview')
+  })
+
+  it('marks only the business license as a required file when creating a customer', async () => {
+    const auth = useAuthStore()
+    auth.permissions = [...auth.permissions, 'platform:customer:create']
+    useAccessPreviewStore().initializeAfterLogin()
+    mount(CustomersView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+    ;[...document.querySelectorAll<HTMLButtonElement>('button')]
+      .find((button) => button.textContent?.trim() === '新增客户')?.click()
+    await flushPromises()
+
+    const labels = [...document.querySelectorAll<HTMLElement>('.qualification-label')]
+    expect(labels.map((label) => label.textContent?.replace(/\s/g, ''))).toEqual([
+      '*营业执照',
+      '法人身份证选填',
+      '货代资质证书选填',
+      '银行开户许可证选填',
+    ])
+    expect(document.body.textContent).toContain('营业执照和18位统一社会信用代码为必填业务项')
+  })
+
+  it('creates a customer with a business license and no legal-person ID', async () => {
+    const auth = useAuthStore()
+    auth.permissions = [...auth.permissions, 'platform:customer:create']
+    useAccessPreviewStore().initializeAfterLogin()
+    const wrapper = mount(CustomersView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+    ;[...document.querySelectorAll<HTMLButtonElement>('button')]
+      .find((button) => button.textContent?.trim() === '新增客户')?.click()
+    await flushPromises()
+
+    await wrapper.get('input[placeholder="请输入工商登记公司名称"]').setValue(fullTenant.tenantName)
+    await wrapper.get('input[placeholder="请输入营业执照上的企业名称"]').setValue(fullTenant.legalName)
+    expect(wrapper.get('input[placeholder="请输入法定代表人姓名（选填）"]').attributes('aria-required')).not.toBe('true')
+    await wrapper.get('input[placeholder="请输入主要联系人姓名"]').setValue(fullTenant.contactName)
+    await wrapper.get('input[placeholder="请输入公司联系电话"]').setValue(fullTenant.contactPhone)
+    await wrapper.get('input[placeholder="请输入18位大写字母或数字"]').setValue(fullTenant.unifiedSocialCreditCode)
+    const licenseFile = new File(['license'], 'license.png', { type: 'image/png' })
+    selectQualificationFile(0, licenseFile)
+    await flushPromises()
+    ;[...document.querySelectorAll<HTMLButtonElement>('button')]
+      .find((button) => button.textContent?.includes('保存资料和资质'))?.click()
+    await flushPromises()
+
+    expect(createPlatformTenant).toHaveBeenCalledWith(expect.objectContaining({
+      tenantName: fullTenant.tenantName,
+      contactPhone: fullTenant.contactPhone,
+      legalRepresentative: '',
+    }))
+    expect(createPlatformTenant).toHaveBeenCalledWith(expect.not.objectContaining({ unifiedSocialCreditCode: expect.anything() }))
+    expect(uploadPlatformTenantRequiredQualificationPackage).toHaveBeenCalledWith(
+      fullTenant.id, licenseFile, null, fullTenant.unifiedSocialCreditCode, false, false,
+    )
+    expect(wrapper.findComponent(AppDialog).props('modelValue')).toBe(false)
+  })
+
+  it('keeps the company contact phone editable without changing a member login phone', async () => {
+    const activeTenant = { ...fullTenant, status: 'ACTIVE' as const }
+    vi.mocked(listPlatformTenants).mockResolvedValue({ records: [activeTenant], page: 1, size: 10, total: 1, pages: 1 })
+    vi.mocked(getPlatformTenant).mockResolvedValue(activeTenant)
+    vi.mocked(updatePlatformTenant).mockResolvedValue(activeTenant)
+    vi.mocked(listTenantQualifications).mockResolvedValue([{
+      id: 'qualification-license', tenantId: fullTenant.id, qualificationType: 'BUSINESS_LICENSE',
+      certificateNo: fullTenant.unifiedSocialCreditCode, documentUrl: '/files/license.png', status: 'APPROVED', reviewComment: null, validTo: null,
+    }])
+    const wrapper = mount(CustomersView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+    tableButtonByText('编辑')?.click()
+    await flushPromises()
+
+    const phone = wrapper.get('input[placeholder="请输入公司联系电话"]')
+    expect(phone.attributes('disabled')).toBeUndefined()
+    await phone.setValue('0755-12345678')
+    ;[...document.querySelectorAll<HTMLButtonElement>('button')]
+      .find((button) => button.textContent?.includes('保存资料和资质'))?.click()
+    await flushPromises()
+
+    expect(updatePlatformTenant).toHaveBeenCalledWith(fullTenant.id, expect.objectContaining({ contactPhone: '0755-12345678' }))
+    expect(wrapper.findComponent(AppDialog).props('modelValue')).toBe(false)
+    expect(document.body.textContent).toContain('不会修改企业管理员登录手机号')
+    expect(customersSource).not.toContain('联系电话（登录用户名）')
+  })
+
+  it('does not count rejected or superseded history as a current qualification when resubmitting', async () => {
+    const rejectedTenant = { ...fullTenant, status: 'REJECTED' }
+    vi.mocked(listPlatformTenants).mockResolvedValue({ records: [rejectedTenant], page: 1, size: 10, total: 1, pages: 1 })
+    vi.mocked(getPlatformTenant).mockResolvedValue(rejectedTenant)
+    vi.mocked(listTenantQualifications).mockResolvedValue([
+      {
+        id: 'qualification-old', tenantId: fullTenant.id, qualificationType: 'BUSINESS_LICENSE',
+        certificateNo: fullTenant.unifiedSocialCreditCode, documentUrl: '/files/old-license.png',
+        status: 'SUPERSEDED', reviewComment: '已替换', validTo: null,
+      },
+      {
+        id: 'qualification-rejected', tenantId: fullTenant.id, qualificationType: 'BUSINESS_LICENSE',
+        certificateNo: fullTenant.unifiedSocialCreditCode, documentUrl: '/files/rejected-license.png',
+        status: 'REJECTED', reviewComment: '请重新上传', validTo: null,
+      },
+    ])
+
+    mount(CustomersView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+    tableButtonByText('编辑')?.click()
+    await flushPromises()
+
+    expect(document.querySelector('.qualification-label [aria-label="已上传"]')).toBeNull()
+    expect(document.querySelector('.qualification-file-name')?.textContent).toContain('未选择文件')
+    expect(downloadTenantQualification).not.toHaveBeenCalled()
+  })
+
+  it('opens customer detail as an independent route', async () => {
+    mount(CustomersView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+
+    tableButtonByText('详情')?.click()
+
+    expect(routerPush).toHaveBeenCalledWith({ name: 'customer-detail', params: { tenantId: String(fullTenant.id) } })
+    expect(getPlatformTenant).not.toHaveBeenCalled()
+  })
+
+  it('opens the requested editor when a cached list receives an edit query', async () => {
+    mount(CustomersView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+
+    routeControl.setEditId(String(fullTenant.id))
+    await flushPromises()
+
+    expect(getPlatformTenant).toHaveBeenCalledWith(fullTenant.id)
+    expect(document.querySelector<HTMLInputElement>('input[placeholder="请输入公司联系电话"]')?.value).toBe(fullTenant.contactPhone)
+    expect(routerReplace).toHaveBeenCalledWith({ name: 'customers' })
+  })
+
+  it('saves the business license, credit code and optional legal-person ID through one package action', async () => {
+    vi.mocked(listTenantQualifications).mockResolvedValue([{
+      id: 'qualification-legal', tenantId: fullTenant.id, qualificationType: 'LEGAL_PERSON_ID',
+      certificateNo: null, documentUrl: '/files/legal-person.png', status: 'PENDING', reviewComment: null, validTo: null,
+    }])
+    mount(CustomersView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+    tableButtonByText('编辑')?.click()
+    await flushPromises()
+
+    const licenseFile = new File(['license'], 'license.png', { type: 'image/png' })
+    const legalPersonFile = new File(['legal-person'], 'legal-person.png', { type: 'image/png' })
+    selectQualificationFile(0, licenseFile)
+    selectQualificationFile(1, legalPersonFile)
+    await flushPromises()
+
+    const buttons = [...document.querySelectorAll<HTMLButtonElement>('button')]
+    expect(buttons.some((button) => button.textContent?.trim() === '上传已选资质')).toBe(false)
+    buttons.find((button) => button.textContent?.trim() === '保存资料和资质')?.click()
+    await flushPromises()
+
+    expect(updatePlatformTenant).toHaveBeenCalledWith(fullTenant.id, expect.objectContaining({ tenantName: fullTenant.tenantName }))
+    expect(uploadPlatformTenantRequiredQualificationPackage).toHaveBeenCalledWith(
+      fullTenant.id,
+      licenseFile,
+      legalPersonFile,
+      fullTenant.unifiedSocialCreditCode,
+      false,
+      true,
+    )
+    expect(uploadPlatformTenantQualification).not.toHaveBeenCalled()
+  })
+
+  it('replaces only the business license while preserving an existing legal-person ID', async () => {
+    vi.mocked(listTenantQualifications).mockResolvedValue([
+      { id: 'qualification-license', tenantId: fullTenant.id, qualificationType: 'BUSINESS_LICENSE', certificateNo: fullTenant.unifiedSocialCreditCode, documentUrl: '/files/license.png', status: 'PENDING', reviewComment: null, validTo: null },
+      { id: 'qualification-legal', tenantId: fullTenant.id, qualificationType: 'LEGAL_PERSON_ID', certificateNo: null, documentUrl: '/files/legal-person.png', status: 'PENDING', reviewComment: null, validTo: null },
+    ])
+    vi.mocked(uploadPlatformTenantRequiredQualificationPackage).mockResolvedValueOnce({
+      businessLicenseQualificationId: 'qualification-business-new', legalPersonIdQualificationId: null,
+      tenantStatus: 'PROFILE_REQUIRED', businessLicenseDocumentUrl: '/files/license-new.png', legalPersonIdDocumentUrl: null,
+    })
+    mount(CustomersView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+    tableButtonByText('编辑')?.click()
+    await flushPromises()
+
+    const licenseFile = new File(['license-new'], 'license-new.png', { type: 'image/png' })
+    selectQualificationFile(0, licenseFile)
+    await flushPromises()
+    ;[...document.querySelectorAll<HTMLButtonElement>('button')]
+      .find((button) => button.textContent?.includes('保存资料和资质'))?.click()
+    await flushPromises()
+
+    expect(uploadPlatformTenantRequiredQualificationPackage).toHaveBeenCalledWith(
+      fullTenant.id, licenseFile, null, fullTenant.unifiedSocialCreditCode, true, false,
+    )
+    expect(uploadPlatformTenantQualification).not.toHaveBeenCalled()
+    expect(document.body.textContent).toContain('法人身份证可按需补充')
+  })
+
+  it('uploads an optional legal-person ID independently when the required business license already exists', async () => {
+    vi.mocked(listTenantQualifications).mockResolvedValue([{
+      id: 'qualification-license', tenantId: fullTenant.id, qualificationType: 'BUSINESS_LICENSE',
+      certificateNo: fullTenant.unifiedSocialCreditCode, documentUrl: '/files/license.png', status: 'PENDING', reviewComment: null, validTo: null,
+    }])
+    mount(CustomersView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+    tableButtonByText('编辑')?.click()
+    await flushPromises()
+
+    const legalPersonFile = new File(['legal-person'], 'legal-person.png', { type: 'image/png' })
+    selectQualificationFile(1, legalPersonFile)
+    await flushPromises()
+    ;[...document.querySelectorAll<HTMLButtonElement>('button')]
+      .find((button) => button.textContent?.includes('保存资料和资质'))?.click()
+    await flushPromises()
+
+    expect(uploadPlatformTenantRequiredQualificationPackage).not.toHaveBeenCalled()
+    expect(uploadPlatformTenantQualification).toHaveBeenCalledWith(
+      fullTenant.id, 'LEGAL_PERSON_ID', legalPersonFile, undefined, undefined, false,
+    )
+  })
+
+  it('retains a selected business license after an upload failure so the operator can retry', async () => {
+    vi.mocked(uploadPlatformTenantRequiredQualificationPackage)
+      .mockRejectedValueOnce(new Error('upload unavailable'))
+      .mockResolvedValueOnce({
+        businessLicenseQualificationId: 'qualification-business', legalPersonIdQualificationId: null,
+        tenantStatus: 'PROFILE_REQUIRED', businessLicenseDocumentUrl: '/files/license-new.png', legalPersonIdDocumentUrl: null,
+      })
+    mount(CustomersView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+    tableButtonByText('编辑')?.click()
+    await flushPromises()
+
+    const licenseFile = new File(['license-new'], 'retry-license.png', { type: 'image/png' })
+    selectQualificationFile(0, licenseFile)
+    await flushPromises()
+    const saveButton = [...document.querySelectorAll<HTMLButtonElement>('button')]
+      .find((button) => button.textContent?.includes('保存资料和资质'))
+    saveButton?.click()
+    await flushPromises()
+    expect(document.body.textContent).toContain('retry-license.png')
+
+    saveButton?.click()
+    await flushPromises()
+    expect(uploadPlatformTenantRequiredQualificationPackage).toHaveBeenCalledTimes(2)
+  })
+
+  it('submits a customer for review with a business license and no legal-person ID', async () => {
+    vi.mocked(listTenantQualifications).mockResolvedValue([{
+      id: 'qualification-license', tenantId: fullTenant.id, qualificationType: 'BUSINESS_LICENSE',
+      certificateNo: fullTenant.unifiedSocialCreditCode, documentUrl: '/files/license.png', status: 'PENDING', reviewComment: null, validTo: null,
+    }])
+    vi.spyOn(ElMessageBox, 'confirm').mockResolvedValue('confirm' as never)
+    mount(CustomersView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+    tableButtonByText('编辑')?.click()
+    await flushPromises()
+    ;[...document.querySelectorAll<HTMLButtonElement>('button')]
+      .find((button) => button.textContent?.trim() === '提交审核')?.click()
+    await flushPromises()
+
+    expect(ElMessageBox.confirm).toHaveBeenCalled()
+    expect(submitPlatformTenantReview).toHaveBeenCalledWith(fullTenant.id)
+  })
+
+  it('submits the current filters to the backend export service without loading every customer page', async () => {
+    const wrapper = mount(CustomersView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+
+    wrapper.findComponent(QueryToolbar).vm.$emit('update:modelValue', { keyword: '  Acme  ', status: 'ACTIVE' })
+    await wrapper.vm.$nextTick()
+
+    const exportButton = [...document.querySelectorAll<HTMLButtonElement>('button')]
+      .find((button) => button.textContent?.trim() === '导出Excel')
+    exportButton?.click()
+    await flushPromises()
+
+    expect(createPlatformExportTask).toHaveBeenCalledWith({
+      exportType: 'CUSTOMER_LIST', format: 'XLSX', taskName: '客户列表',
+      parameters: { keyword: 'Acme', status: 'ACTIVE' },
+    })
+    expect(showExportTaskCreatedDialog).toHaveBeenCalledWith({ taskName: '客户列表', taskNo: 'EXP2084' })
+    expect(listPlatformTenants).toHaveBeenCalledTimes(1)
+  })
+
+  it('opens the download center when the export-created dialog action is confirmed', async () => {
+    vi.mocked(createPlatformExportTask).mockResolvedValue({
+      id: 'export-1', taskName: '客户列表', taskNo: 'EXP2084', status: 'PENDING',
+    } as never)
+    vi.mocked(showExportTaskCreatedDialog).mockResolvedValue(true)
+    mount(CustomersView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+
+    const exportButton = [...document.querySelectorAll<HTMLButtonElement>('button')]
+      .find((button) => button.textContent?.trim() === '导出Excel')
+    exportButton?.click()
+    await flushPromises()
+
+    expect(showExportTaskCreatedDialog).toHaveBeenCalledWith({ taskName: '客户列表', taskNo: 'EXP2084' })
+    expect(routerPush).toHaveBeenCalledWith({ name: 'download-center' })
+  })
+
+  it('hides customer export when the stable export permission is absent', async () => {
+    const auth = useAuthStore()
+    auth.permissions = ['platform:customer:list']
+    useAccessPreviewStore().initializeAfterLogin()
+    mount(CustomersView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+
+    expect([...document.querySelectorAll<HTMLButtonElement>('button')]
+      .some((button) => button.textContent?.trim() === '导出Excel')).toBe(false)
+    expect(createPlatformExportTask).not.toHaveBeenCalled()
+  })
+
+  it('does not create an unrecoverable export for a role without download-center access', async () => {
+    const auth = useAuthStore()
+    auth.permissions = ['platform:customer:list', 'platform:customer:export']
+    useAccessPreviewStore().initializeAfterLogin()
+    mount(CustomersView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+
+    expect([...document.querySelectorAll<HTMLButtonElement>('button')]
+      .some((button) => button.textContent?.trim() === '导出Excel')).toBe(false)
+    expect(createPlatformExportTask).not.toHaveBeenCalled()
+  })
+
+  it('approves a pending enterprise directly from the customer list', async () => {
+    const auth = useAuthStore()
+    auth.permissions = [...auth.permissions, 'platform:customer:review', 'platform:customer:approve']
+    useAccessPreviewStore().initializeAfterLogin()
+    vi.mocked(listPlatformTenants).mockResolvedValue({
+      records: [{ ...fullTenant, status: 'PENDING' }], page: 1, size: 10, total: 1, pages: 1,
+    })
+    vi.mocked(listEnterpriseReviews).mockResolvedValue([pendingReview])
+    vi.mocked(approveEnterpriseReview).mockResolvedValue({
+      tenantId: fullTenant.id,
+      administratorCreated: true,
+      administratorUsername: 'merchant_8_owner',
+      temporaryPassword: 'Temporary#2026',
+    })
+
+    mount(CustomersView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+    tableButtonByText('审核')?.click()
+    await flushPromises()
+    ;[...document.querySelectorAll<HTMLButtonElement>('button')]
+      .find((button) => button.textContent?.trim() === '审核通过')?.click()
+    await flushPromises()
+
+    expect(approveEnterpriseReview).toHaveBeenCalledWith(pendingReview.id, '企业资料、营业执照和统一社会信用代码完整、清晰，审核通过（法人身份证为选填项）')
+    expect(rejectEnterpriseReview).not.toHaveBeenCalled()
+    expect(document.body.textContent).toContain('请立即保存以下一次性凭证')
+    expect(document.body.textContent).toContain('merchant_8_owner')
+    expect(document.body.textContent).toContain('Temporary#2026')
+  })
+
+  it('loads and previews authenticated qualification files in the review dialog', async () => {
+    const auth = useAuthStore()
+    auth.permissions = [...auth.permissions, 'platform:customer:review', 'platform:customer:approve']
+    useAccessPreviewStore().initializeAfterLogin()
+    vi.mocked(listPlatformTenants).mockResolvedValue({
+      records: [{ ...fullTenant, status: 'PENDING' }], page: 1, size: 10, total: 1, pages: 1,
+    })
+    vi.mocked(listEnterpriseReviews).mockResolvedValue([pendingReview])
+    vi.mocked(listTenantQualifications).mockResolvedValue([
+      { id: 'qualification-license', tenantId: fullTenant.id, qualificationType: 'BUSINESS_LICENSE', certificateNo: fullTenant.unifiedSocialCreditCode, documentUrl: '/files/license.png', status: 'PENDING', reviewComment: null, validTo: null },
+      { id: 'qualification-legal', tenantId: fullTenant.id, qualificationType: 'LEGAL_PERSON_ID', certificateNo: null, documentUrl: '/files/legal-person.png', status: 'PENDING', reviewComment: null, validTo: null },
+    ])
+    vi.mocked(downloadTenantQualification).mockResolvedValue(new Blob(['image'], { type: 'image/png' }))
+
+    mount(CustomersView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+    tableButtonByText('审核')?.click()
+    await flushPromises()
+
+    expect(listTenantQualifications).toHaveBeenCalledWith(fullTenant.id)
+    expect(document.body.textContent).toContain('营业执照')
+    expect(document.body.textContent).toContain('法人身份证')
+    const previewButton = [...document.querySelectorAll<HTMLButtonElement>('.review-document-actions button')]
+      .find((button) => button.textContent?.trim() === '预览')
+    previewButton?.click()
+    await flushPromises()
+
+    expect(downloadTenantQualification).toHaveBeenCalledWith(fullTenant.id, '/files/license.png')
+    expect(document.querySelector<HTMLImageElement>('img[alt="license.png预览"]')?.src).toBe('blob:qualification-preview')
+  })
+
+  it('keeps the client registration account as administrator after approval', async () => {
+    const auth = useAuthStore()
+    auth.permissions = [...auth.permissions, 'platform:customer:review', 'platform:customer:approve']
+    useAccessPreviewStore().initializeAfterLogin()
+    vi.mocked(listPlatformTenants).mockResolvedValue({
+      records: [{ ...fullTenant, status: 'PENDING' }], page: 1, size: 10, total: 1, pages: 1,
+    })
+    vi.mocked(listEnterpriseReviews).mockResolvedValue([pendingReview])
+    vi.mocked(approveEnterpriseReview).mockResolvedValue({
+      tenantId: fullTenant.id,
+      administratorCreated: false,
+      administratorUsername: null,
+      temporaryPassword: null,
+    })
+
+    mount(CustomersView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+    tableButtonByText('审核')?.click()
+    await flushPromises()
+    ;[...document.querySelectorAll<HTMLButtonElement>('button')]
+      .find((button) => button.textContent?.trim() === '审核通过')?.click()
+    await flushPromises()
+
+    expect(approveEnterpriseReview).toHaveBeenCalledWith(pendingReview.id, '企业资料、营业执照和统一社会信用代码完整、清晰，审核通过（法人身份证为选填项）')
+    expect(rejectEnterpriseReview).not.toHaveBeenCalled()
+    expect(document.body.textContent).toContain('注册账号继续作为企业管理员')
+    expect(document.body.textContent).not.toContain('请立即保存以下一次性凭证')
+  })
+
+  it('keeps review-only roles on the merged customer page without calling the customer list endpoint', async () => {
+    const auth = useAuthStore()
+    auth.permissions = ['platform:customer:review', 'platform:customer:approve']
+    useAccessPreviewStore().initializeAfterLogin()
+    vi.mocked(listEnterpriseReviews).mockResolvedValue([pendingReview])
+
+    mount(CustomersView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+
+    expect(listPlatformTenants).not.toHaveBeenCalled()
+    expect(document.body.textContent).toContain(fullTenant.tenantName)
+    expect(tableButtonByText('审核')).toBeDefined()
+  })
+
+  it('does not let an older review response restore stale actions', async () => {
+    const auth = useAuthStore()
+    auth.permissions = [...auth.permissions, 'platform:customer:review', 'platform:customer:approve']
+    useAccessPreviewStore().initializeAfterLogin()
+    let resolveFirst!: (value: EnterpriseReview[]) => void
+    let resolveSecond!: (value: EnterpriseReview[]) => void
+    vi.mocked(listEnterpriseReviews)
+      .mockImplementationOnce(() => new Promise((resolve) => { resolveFirst = resolve }))
+      .mockImplementationOnce(() => new Promise((resolve) => { resolveSecond = resolve }))
+
+    mount(CustomersView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await Promise.resolve()
+    ;[...document.querySelectorAll<HTMLButtonElement>('.query-toolbar__actions button')]
+      .find((button) => button.textContent?.trim() === '查询')?.click()
+    await Promise.resolve()
+
+    resolveSecond([pendingReview])
+    await flushPromises()
+    expect(tableButtonByText('审核')).toBeDefined()
+
+    resolveFirst([])
+    await flushPromises()
+    expect(tableButtonByText('审核')).toBeDefined()
+  })
+
+  it('resets only the customer owner password through the tenant contract', async () => {
+    const auth = useAuthStore()
+    auth.permissions = [...auth.permissions, 'platform:customer:reset-password']
+    useAccessPreviewStore().initializeAfterLogin()
+    vi.mocked(listPlatformTenants).mockResolvedValue({ records: [{ ...fullTenant, status: 'ACTIVE' }], page: 1, size: 10, total: 1, pages: 1 })
+    vi.mocked(resetPlatformTenantOwnerPassword).mockResolvedValue()
+
+    mount(CustomersView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+    tableButtonByText('重置密码')?.click()
+    await flushPromises()
+
+    const password = document.querySelector<HTMLInputElement>('input[autocomplete="new-password"]')
+    const confirmation = document.querySelector<HTMLInputElement>('input[placeholder="请再次输入新密码"]')
+    password!.value = 'NewPassword#2026'
+    password!.dispatchEvent(new Event('input', { bubbles: true }))
+    confirmation!.value = 'NewPassword#2026'
+    confirmation!.dispatchEvent(new Event('input', { bubbles: true }))
+    await flushPromises()
+    ;[...document.querySelectorAll<HTMLButtonElement>('button')]
+      .find((button) => button.textContent?.trim() === '确认重置')?.click()
+    await flushPromises()
+
+    expect(resetPlatformTenantOwnerPassword).toHaveBeenCalledWith(fullTenant.id, {
+      newPassword: 'NewPassword#2026', forceChangePassword: true,
+    })
+  })
+
+  it('archives a customer only after its customer ID is explicitly confirmed', async () => {
+    const auth = useAuthStore()
+    auth.permissions = [...auth.permissions, 'platform:customer:delete']
+    useAccessPreviewStore().initializeAfterLogin()
+    vi.mocked(archivePlatformTenant).mockResolvedValue({ ...fullTenant, status: 'ARCHIVED' })
+    vi.mocked(listPlatformTenants)
+      .mockResolvedValueOnce({ records: [fullTenant], page: 1, size: 10, total: 1, pages: 1 })
+      .mockResolvedValueOnce({ records: [], page: 1, size: 10, total: 0, pages: 0 })
+
+    mount(CustomersView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+    expect(document.querySelector('.el-table__body button[aria-label^="更多客户操作："]')).toBeNull()
+    tableButtonByText('删除')?.click()
+    await flushPromises()
+
+    const confirmation = document.querySelector<HTMLInputElement>('input[placeholder="TEN8"]')
+    expect(confirmation).toBeTruthy()
+    expect([...document.querySelectorAll<HTMLButtonElement>('button')]
+      .find((button) => button.textContent?.trim() === '确认删除')?.disabled).toBe(true)
+
+    confirmation!.value = 'TEN8'
+    confirmation!.dispatchEvent(new Event('input', { bubbles: true }))
+    await flushPromises()
+    ;[...document.querySelectorAll<HTMLButtonElement>('button')]
+      .find((button) => button.textContent?.trim() === '确认删除')?.click()
+    await flushPromises()
+
+    expect(archivePlatformTenant).toHaveBeenCalledWith(fullTenant.id)
+    expect(document.body.textContent).not.toContain(fullTenant.tenantName)
+  })
+
+  it('keeps the first operation column unfixed so it cannot cover a 320px table viewport', async () => {
+    mount(CustomersView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+
+    expect(document.querySelector('.el-table__fixed')).toBeNull()
+  })
+
+  it('keeps three high-frequency actions visible and moves overflow actions into a menu', async () => {
+    const auth = useAuthStore()
+    auth.permissions = [...auth.permissions, 'platform:customer:reset-password', 'platform:customer:impersonate', 'platform:customer:status', 'platform:customer:delete']
+    useAccessPreviewStore().initializeAfterLogin()
+    vi.mocked(listPlatformTenants).mockResolvedValue({ records: [{ ...fullTenant, status: 'ACTIVE' }], page: 1, size: 10, total: 1, pages: 1 })
+
+    mount(CustomersView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+
+    expect(tableButtonByText('详情')).toBeDefined()
+    expect(tableButtonByText('编辑')).toBeDefined()
+    expect(document.querySelector('.el-table__body button[aria-label^="更多客户操作："]')).not.toBeNull()
+    expect(tableButtonByText('重置密码')).toBeDefined()
+    expect(tableButtonByText('跳转登录')).toBeUndefined()
+    await clickMoreAction('跳转登录')
+    expect(document.body.textContent).toContain('代登录原因')
+  })
+
+  it('renders one overflow menu per customer when permitted actions exceed three', async () => {
+    const auth = useAuthStore()
+    auth.permissions = [...auth.permissions, 'platform:customer:reset-password', 'platform:customer:impersonate', 'platform:customer:status', 'platform:customer:delete']
+    useAccessPreviewStore().initializeAfterLogin()
+    vi.mocked(listPlatformTenants).mockResolvedValue({
+      records: [
+        { ...fullTenant, id: '8', tenantName: '客户甲', tenantCode: 'TEN-A', status: 'ACTIVE' },
+        { ...fullTenant, id: '9', tenantName: '', tenantCode: 'TEN-B', status: 'ACTIVE' },
+        { ...fullTenant, id: '10', tenantName: '', tenantCode: '', status: 'ACTIVE' },
+      ],
+      page: 1, size: 10, total: 3, pages: 1,
+    })
+
+    mount(CustomersView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+
+    expect(document.querySelectorAll('.el-table__body button[aria-label^="更多客户操作："]').length).toBe(3)
+    expect(document.querySelectorAll('.el-table__body .table-actions > .el-button').length).toBe(9)
+  })
+
+  it('keeps the action row usable when all customer identifiers are missing', async () => {
+    const auth = useAuthStore()
+    auth.permissions = [...auth.permissions, 'platform:customer:reset-password', 'platform:customer:impersonate', 'platform:customer:status', 'platform:customer:delete']
+    useAccessPreviewStore().initializeAfterLogin()
+    vi.mocked(listPlatformTenants).mockResolvedValue({
+      records: [{ ...fullTenant, id: null, tenantName: '', tenantCode: '', status: 'ACTIVE' } as unknown as PlatformTenantResource],
+      page: 1, size: 10, total: 1, pages: 1,
+    })
+
+    mount(CustomersView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+
+    expect(document.querySelector('.el-table__body button[aria-label="更多客户操作：当前客户"]')).not.toBeNull()
+    expect(tableButtonByText('详情')).toBeDefined()
+  })
+})
diff --git a/src/modules/customers/pages/CustomersView.vue b/src/modules/customers/pages/CustomersView.vue
new file mode 100644
index 00000000..7e6f38d3
--- /dev/null
+++ b/src/modules/customers/pages/CustomersView.vue
@@ -0,0 +1,1284 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import '@/modules/customers/customerDensity.css'
+import { computed, nextTick, onBeforeUnmount, onMounted, reactive, ref, watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { Building2, CheckCircle2, CircleCheck, FileCheck2, FileText, MoreHorizontal, ShieldCheck, ShieldX } from '@lucide/vue'
+import { ElMessage, ElMessageBox, type FormInstance, type FormRules } from 'element-plus'
+import { getApiErrorDetails, getApiErrorMessage, type ApiErrorDetails } from '@/shared/api/http'
+import { createPlatformExportTask } from '@/modules/downloads'
+import {
+  approveEnterpriseReview,
+  archivePlatformTenant,
+  changePlatformTenantStatus,
+  createPlatformTenant,
+  createPlatformTenantImpersonation,
+  downloadTenantQualification,
+  getPlatformTenant,
+  listEnterpriseReviews,
+  listPlatformTenantOrderCounts,
+  listPlatformTenants,
+  listTenantQualifications,
+  qualificationFileName,
+  rejectEnterpriseReview,
+  resetPlatformTenantOwnerPassword,
+  submitPlatformTenantReview,
+  updatePlatformTenant,
+  uploadPlatformTenantQualification,
+  uploadPlatformTenantRequiredQualificationPackage,
+  type CreatePlatformTenantRequest,
+  type EnterpriseApprovalResponse,
+  type EnterpriseReview,
+  type PlatformQualificationType,
+  type PlatformTenantQualification,
+  type PlatformTenantResource,
+  type PlatformTenantStatus,
+} from '@/modules/iam'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import OperationErrorToast from '@/shared/components/OperationErrorToast.vue'
+import CopyButton from '@/shared/components/CopyButton.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import FormSection from '@/shared/components/FormSection.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { showExportTaskCreatedDialog } from '@/shared/components/exportTaskCreatedDialog'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { getClientWebUrl } from '@/core/config/runtimeConfig'
+
+type CustomerFilters = QueryModel & { keyword: string; status: PlatformTenantStatus | '' }
+type QualificationDraft = {
+  type: PlatformQualificationType
+  label: string
+  required: boolean
+  file: File | null
+  validTo: string
+  uploaded: boolean
+  uploadedName: string
+  documentUrl: string
+  previewUrl: string
+  previewKind: 'image' | 'pdf' | ''
+  previewLoading: boolean
+  previewFailed: boolean
+  uploading: boolean
+  error: string
+}
+
+const access = useAccessPreviewStore()
+const route = useRoute()
+const router = useRouter()
+const page = ref(1)
+const pageSize = ref(10)
+const loading = ref(false)
+const exportSubmitting = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const result = ref({ records: [] as PlatformTenantResource[], total: 0, pages: 0 })
+const orderCounts = ref<Record<string, number>>({})
+const rowActionId = ref('')
+const pendingReviews = ref<EnterpriseReview[]>([])
+const reviewLoadError = ref<ApiErrorDetails | null>(null)
+const selectedReview = ref<EnterpriseReview | null>(null)
+const decisionOpen = ref(false)
+const reviewSubmitting = ref(false)
+const reviewQualifications = ref<PlatformTenantQualification[]>([])
+const reviewQualificationsLoading = ref(false)
+const reviewQualificationsError = ref<ApiErrorDetails | null>(null)
+const reviewPreviewOpen = ref(false)
+const reviewPreviewName = ref('')
+const reviewPreviewUrl = ref('')
+const reviewPreviewKind = ref<'image' | 'pdf'>('image')
+const reviewDocumentLoading = ref('')
+const approvalResultOpen = ref(false)
+const approvalResult = ref<EnterpriseApprovalResponse | null>(null)
+const credentialSource = ref<'creation' | 'approval'>('approval')
+const decision = reactive({ type: 'approve' as 'approve' | 'reject', comment: '' })
+const decisionFormRef = ref<FormInstance>()
+const passwordDialogOpen = ref(false)
+const passwordSubmitting = ref(false)
+const passwordFormRef = ref<FormInstance>()
+const passwordTenant = ref<PlatformTenantResource | null>(null)
+const passwordForm = reactive({ newPassword: '', confirmPassword: '', forceChangePassword: true })
+const passwordError = ref<ApiErrorDetails | null>(null)
+const impersonationDialogOpen = ref(false)
+const impersonationSubmitting = ref(false)
+const impersonationFormRef = ref<FormInstance>()
+const impersonationTenant = ref<PlatformTenantResource | null>(null)
+const impersonationForm = reactive({ reason: '' })
+const impersonationError = ref<ApiErrorDetails | null>(null)
+const archiveDialogOpen = ref(false)
+const archiveSubmitting = ref(false)
+const archiveTenant = ref<PlatformTenantResource | null>(null)
+const archiveConfirmCode = ref('')
+const archiveError = ref<ApiErrorDetails | null>(null)
+let impersonationCleanup: (() => void) | null = null
+const editorOpen = ref(false)
+const editorLoading = ref(false)
+const saving = ref(false)
+const submitting = ref(false)
+const savedFormSnapshot = ref('')
+const editingId = ref<string | null>(null)
+const editorStatus = ref<PlatformTenantStatus | null>(null)
+const formRef = ref<FormInstance>()
+const qualificationLoadError = ref('')
+const qualificationPreviewOpen = ref(false)
+const qualificationPreviewName = ref('')
+const qualificationPreviewUrl = ref('')
+const qualificationPreviewKind = ref<'image' | 'pdf' | ''>('')
+
+const filters = ref<CustomerFilters>({ keyword: '', status: '' })
+const queryFields: QueryField[] = [
+  { key: 'keyword', type: 'input', label: '客户名称', placeholder: '请输入客户名称' },
+  { key: 'status', type: 'select', label: '状态', placeholder: '全部状态', options: [
+    { label: '待完善', value: 'PROFILE_REQUIRED' }, { label: '待审核', value: 'PENDING' },
+    { label: '启用', value: 'ACTIVE' }, { label: '已驳回', value: 'REJECTED' },
+    { label: '已停用', value: 'DISABLED' },
+  ] },
+]
+
+type CustomerForm = CreatePlatformTenantRequest & { customerNickname: string; unifiedSocialCreditCode: string }
+const emptyForm = (): CustomerForm => ({
+  tenantName: '', customerNickname: '', legalName: '', legalRepresentative: '', unifiedSocialCreditCode: '', contactName: '', contactPhone: '',
+  contactEmail: '', contactWechat: '', servicePackage: '基础版', salesOwnerName: '', paymentTermDays: 30,
+  enterpriseType: '', establishedDate: null, registeredCapital: 100000, registeredCapitalCurrency: 'CNY',
+  registeredAddress: '', internalRemark: '',
+})
+const form = ref(emptyForm())
+const rules: FormRules = {
+  tenantName: [{ required: true, message: '请输入公司名称', trigger: 'blur' }],
+  customerNickname: [
+    { max: 32, message: '客户昵称最多 32 个字符', trigger: 'blur' },
+    {
+      validator: (_rule, value, callback) => {
+        if (!editingId.value || (typeof value === 'string' && value.trim())) callback()
+        else callback(new Error('请输入客户昵称'))
+      },
+      trigger: ['blur', 'change'],
+    },
+  ],
+  legalName: [{ required: true, message: '请输入营业执照上的企业名称', trigger: 'blur' }],
+  legalRepresentative: [{ max: 64, message: '法定代表人最多 64 个字符', trigger: 'blur' }],
+  unifiedSocialCreditCode: [
+    { required: true, message: '请输入统一社会信用代码', trigger: 'blur' },
+    { pattern: /^[0-9A-Z]{18}$/, message: '请输入 18 位大写字母或数字', trigger: 'blur' },
+  ],
+  contactName: [{ required: true, message: '请输入联系人姓名', trigger: 'blur' }],
+  contactPhone: [
+    { required: true, message: '请输入公司联系电话', trigger: 'blur' },
+    { pattern: /^[0-9-]{4,32}$/, message: '请输入 4-32 位数字或连字符', trigger: 'blur' },
+  ],
+  contactEmail: [{ type: 'email', message: '请输入有效邮箱地址', trigger: 'blur' }],
+  servicePackage: [{ required: true, message: '请选择客户套餐', trigger: 'change' }],
+  paymentTermDays: [{ required: true, message: '请输入账期天数', trigger: 'change' }],
+}
+const decisionRules: FormRules = {
+  comment: [{
+    validator: (_rule, value, callback) => {
+      if (typeof value === 'string' && value.trim()) callback()
+      else callback(new Error('请填写审核说明或驳回原因'))
+    },
+    trigger: ['blur', 'change'],
+  }],
+}
+
+function newQualificationDrafts(): QualificationDraft[] {
+  const definitions: Array<Pick<QualificationDraft, 'type' | 'label' | 'required'>> = [
+    { type: 'BUSINESS_LICENSE', label: '营业执照', required: true },
+    { type: 'LEGAL_PERSON_ID', label: '法人身份证', required: false },
+    { type: 'FREIGHT_FORWARDER_CERTIFICATE', label: '货代资质证书', required: false },
+    { type: 'BANK_ACCOUNT_LICENSE', label: '银行开户许可证', required: false },
+  ]
+  return definitions.map((item) => ({
+    ...item,
+    file: null,
+    validTo: '',
+    uploaded: false,
+    uploadedName: '',
+    documentUrl: '',
+    previewUrl: '',
+    previewKind: '',
+    previewLoading: false,
+    previewFailed: false,
+    uploading: false,
+    error: '',
+  }))
+}
+const qualifications = ref<QualificationDraft[]>(newQualificationDrafts())
+const creditCodeEstablished = ref(false)
+const unifiedSocialCreditCodePattern = /^[0-9A-Z]{18}$/
+
+const customerColumns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 330, slotName: 'actions' },
+  { key: 'tenantCode', prop: 'tenantCode', label: '客户编号', width: 220, className: 'customer-code-column' },
+  { key: 'customerNickname', prop: 'customerNickname', label: '客户昵称', width: 120, formatter: (row: PlatformTenantResource) => displayText(row.customerNickname) },
+  { key: 'company', label: '公司名称', width: 250, slotName: 'company' },
+  { key: 'unifiedSocialCreditCode', prop: 'unifiedSocialCreditCode', label: '统一社会信用代码', width: 220, formatter: (row: PlatformTenantResource) => displayText(row.unifiedSocialCreditCode) },
+  { key: 'contactName', prop: 'contactName', label: '联系人', minWidth: 120, formatter: (row: PlatformTenantResource) => displayText(row.contactName) },
+  { key: 'contactPhone', prop: 'contactPhone', label: '公司联系电话', minWidth: 150, formatter: (row: PlatformTenantResource) => displayText(row.contactPhone) },
+  { key: 'salesOwnerName', prop: 'salesOwnerName', label: '销售人员', minWidth: 120, formatter: (row: PlatformTenantResource) => displayText(row.salesOwnerName) },
+  { key: 'paymentTermDays', prop: 'paymentTermDays', label: '账期(天)', width: 105, formatter: (row: PlatformTenantResource) => row.paymentTermDays ?? 0 },
+  { key: 'status', label: '状态', width: 110, slotName: 'status' },
+  { key: 'orderCount', label: '运单数', width: 100, slotName: 'orderCount' },
+  { key: 'createdAt', prop: 'createdAt', label: '入驻时间', minWidth: 165, formatter: (row: PlatformTenantResource) => formatDate(row.createdAt) },
+]
+
+let loadSequence = 0
+let reviewLoadSequence = 0
+let editorLoadSequence = 0
+const editorTitle = computed(() => editingId.value ? '编辑客户' : '新增客户')
+const editorDialogWidth = 'min(1120px, calc(100vw - 28px))'
+const canUploadQualifications = computed(() => !editorStatus.value || ['PROFILE_REQUIRED', 'REJECTED'].includes(editorStatus.value))
+const canSubmitReview = computed(() => Boolean(editingId.value) && ['PROFILE_REQUIRED', 'REJECTED'].includes(editorStatus.value || ''))
+const uploadingQualifications = computed(() => qualifications.value.some((item) => item.uploading))
+const hasSelectedQualifications = computed(() => qualifications.value.some((item) => item.file))
+const selectedBusinessLicense = computed(() => qualifications.value.find((item) => item.type === 'BUSINESS_LICENSE')?.file)
+const selectedLegalPersonId = computed(() => qualifications.value.find((item) => item.type === 'LEGAL_PERSON_ID')?.file)
+const businessLicenseReadyForSave = computed(() => Boolean(selectedBusinessLicense.value
+  || qualifications.value.find((item) => item.type === 'BUSINESS_LICENSE')?.uploaded))
+const creditCodeReadyForSave = computed(() => creditCodeEstablished.value
+  || unifiedSocialCreditCodePattern.test(form.value.unifiedSocialCreditCode || ''))
+const requiredQualificationPackageComplete = computed(() => businessLicenseReadyForSave.value && creditCodeReadyForSave.value)
+const missingQualificationPackageItems = computed(() => {
+  const businessLicense = qualifications.value.find((item) => item.type === 'BUSINESS_LICENSE')
+  const missing: string[] = []
+  if (!businessLicense?.file && !businessLicense?.uploaded) missing.push('营业执照')
+  if (!creditCodeReadyForSave.value) missing.push('18位统一社会信用代码（需随营业执照保存）')
+  return missing
+})
+const hasUnsavedChanges = computed(() => Boolean(editingId.value) && JSON.stringify(form.value) !== savedFormSnapshot.value)
+const pendingReviewByTenantId = computed(() => new Map(pendingReviews.value.map((review) => [String(review.tenantId), review])))
+const passwordRules: FormRules = {
+  newPassword: [
+    { required: true, message: '请输入新密码', trigger: 'blur' },
+    { min: 8, max: 20, message: '密码长度为 8-20 位', trigger: 'blur' },
+    { pattern: /^(?=.*[A-Za-z])(?=.*\d).+$/, message: '密码必须同时包含字母和数字', trigger: 'blur' },
+  ],
+  confirmPassword: [{
+    validator: (_rule, value, callback) => value === passwordForm.newPassword ? callback() : callback(new Error('两次输入的密码不一致')),
+    trigger: ['blur', 'change'],
+  }],
+}
+const impersonationRules: FormRules = {
+  reason: [
+    { required: true, message: '请输入代登录原因', trigger: 'blur' },
+    { min: 5, max: 500, message: '代登录原因需填写 5-500 字', trigger: 'blur' },
+  ],
+}
+function displayText(value?: string | null) { return value?.trim() || '—' }
+function formatDate(value?: string | null) { return value ? value.replace('T', ' ').slice(0, 16) : '—' }
+function qualificationLabel(type?: string | null) {
+  return ({ BUSINESS_LICENSE: '营业执照', LEGAL_PERSON_ID: '法人身份证', FREIGHT_FORWARDER_CERTIFICATE: '货代资质证书', BANK_ACCOUNT_LICENSE: '银行开户许可证' } as Record<string, string>)[type || ''] || type || '企业资质'
+}
+function qualificationName(item: PlatformTenantQualification) {
+  try { return qualificationFileName(item.documentUrl) } catch { return qualificationLabel(item.qualificationType) }
+}
+function statusMeta(status: PlatformTenantStatus) {
+  if (status === 'ACTIVE') return { label: '启用', type: 'success' as const }
+  if (status === 'PROFILE_REQUIRED') return { label: '待完善', type: 'info' as const }
+  if (status === 'PENDING') return { label: '待审核', type: 'warning' as const }
+  if (status === 'REJECTED') return { label: '已驳回', type: 'danger' as const }
+  if (status === 'ARCHIVED') return { label: '已归档', type: 'info' as const }
+  return { label: '已停用', type: 'info' as const }
+}
+
+
+async function loadPendingReviews() {
+  const sequence = ++reviewLoadSequence
+  if (!access.can('platform:customer:review')) {
+    if (sequence === reviewLoadSequence) {
+      pendingReviews.value = []
+      reviewLoadError.value = null
+    }
+    return [] as EnterpriseReview[]
+  }
+  if (sequence === reviewLoadSequence) reviewLoadError.value = null
+  try {
+    const reviews = await listEnterpriseReviews()
+    if (sequence === reviewLoadSequence) pendingReviews.value = reviews
+    return reviews
+  } catch (error) {
+    if (sequence === reviewLoadSequence) {
+      pendingReviews.value = []
+      reviewLoadError.value = getApiErrorDetails(error, '待审核客户加载失败，审核操作暂不可用')
+    }
+    return [] as EnterpriseReview[]
+  }
+}
+
+async function reloadPendingReviews() {
+  const reviews = await loadPendingReviews()
+  if (!access.can('platform:customer:list')) result.value = reviewOnlyPage(reviews)
+}
+
+function reviewToCustomer(review: EnterpriseReview): PlatformTenantResource {
+  const tenantId = String(review.tenantId)
+  return {
+    id: tenantId,
+    tenantCode: review.tenantCode?.trim() || '待生成',
+    tenantName: review.tenantName?.trim() || '待审核企业',
+    status: 'PENDING',
+    legalName: null,
+    legalRepresentative: null,
+    unifiedSocialCreditCode: null,
+    contactName: review.contactName ?? null,
+    contactPhone: review.contactPhone ?? null,
+    contactEmail: review.contactEmail ?? null,
+    servicePackage: null,
+    contactWechat: null,
+    salesOwnerName: null,
+    paymentTermDays: null,
+    enterpriseType: null,
+    establishedDate: null,
+    registeredCapital: null,
+    registeredCapitalCurrency: null,
+    registeredAddress: null,
+    internalRemark: null,
+    createdAt: review.submittedAt ?? review.createdAt ?? null,
+    approvedAt: null,
+  }
+}
+
+function reviewOnlyPage(reviews: EnterpriseReview[]) {
+  const keyword = filters.value.keyword.trim().toLowerCase()
+  const records = reviews
+    .map(reviewToCustomer)
+    .filter((row) => (!filters.value.status || filters.value.status === 'PENDING') && (
+      !keyword
+      || row.tenantName.toLowerCase().includes(keyword)
+    ))
+  const start = (page.value - 1) * pageSize.value
+  return {
+    records: records.slice(start, start + pageSize.value),
+    page: page.value,
+    size: pageSize.value,
+    total: records.length,
+    pages: Math.ceil(records.length / pageSize.value),
+  }
+}
+
+async function loadCustomers() {
+  const sequence = ++loadSequence
+  loading.value = true; loadError.value = null
+  try {
+    const reviewsRequest = loadPendingReviews()
+    const pageResult = access.can('platform:customer:list')
+      ? await listPlatformTenants({ page: page.value, size: pageSize.value, keyword: filters.value.keyword.trim() || undefined, status: filters.value.status || undefined })
+      : reviewOnlyPage(await reviewsRequest)
+    if (access.can('platform:customer:list')) await reviewsRequest
+    if (sequence !== loadSequence) return
+    result.value = pageResult; orderCounts.value = {}
+    if (access.can('platform:order:list') && pageResult.records.length) {
+      try {
+        const counts = await listPlatformTenantOrderCounts(pageResult.records.map((item) => item.id))
+        if (sequence === loadSequence) orderCounts.value = Object.fromEntries(counts.map((item) => [String(item.tenantId), Number(item.orderCount)]))
+      } catch { /* 主档可继续使用，运单服务失败时不显示模拟数量。 */ }
+    }
+  } catch (error) {
+    if (sequence === loadSequence) loadError.value = getApiErrorDetails(error, '客户列表加载失败，请稍后重试')
+  } finally { if (sequence === loadSequence) loading.value = false }
+}
+
+function applyFilters() { if (page.value === 1) void loadCustomers(); else page.value = 1 }
+function clearDraftPreview(draft: QualificationDraft) {
+  if (draft.previewUrl) URL.revokeObjectURL(draft.previewUrl)
+  draft.previewUrl = ''
+  draft.previewKind = ''
+  draft.previewLoading = false
+  draft.previewFailed = false
+}
+function clearQualificationPreviews() {
+  for (const draft of qualifications.value) clearDraftPreview(draft)
+  qualificationPreviewOpen.value = false
+  qualificationPreviewName.value = ''
+  qualificationPreviewUrl.value = ''
+  qualificationPreviewKind.value = ''
+}
+function resetEditor() {
+  clearQualificationPreviews()
+  form.value = emptyForm(); qualifications.value = newQualificationDrafts(); creditCodeEstablished.value = false; qualificationLoadError.value = ''; savedFormSnapshot.value = ''
+}
+function openCreate() {
+  editorLoadSequence += 1
+  editingId.value = null; editorStatus.value = null; resetEditor(); editorOpen.value = true
+  nextTick(() => formRef.value?.clearValidate())
+}
+function mapTenantToForm(row: PlatformTenantResource): CustomerForm {
+  return {
+    tenantName: row.tenantName, customerNickname: row.customerNickname || '', legalName: row.legalName || '', legalRepresentative: row.legalRepresentative || '', unifiedSocialCreditCode: row.unifiedSocialCreditCode || '',
+    contactName: row.contactName || '', contactPhone: row.contactPhone || '', contactEmail: row.contactEmail || '',
+    contactWechat: row.contactWechat || '', servicePackage: row.servicePackage || '基础版', salesOwnerName: row.salesOwnerName || '',
+    paymentTermDays: Number(row.paymentTermDays ?? 0), enterpriseType: row.enterpriseType || '', establishedDate: row.establishedDate || null,
+    registeredCapital: row.registeredCapital === null ? null : Number(row.registeredCapital),
+    registeredCapitalCurrency: row.registeredCapitalCurrency || 'CNY', registeredAddress: row.registeredAddress || '',
+    internalRemark: row.internalRemark || '',
+  }
+}
+async function loadEditorQualifications(tenantId: number | string, sequence = editorLoadSequence) {
+  qualificationLoadError.value = ''
+  try {
+    const records = await listTenantQualifications(tenantId)
+    if (sequence !== editorLoadSequence || !editorOpen.value || editingId.value !== String(tenantId)) return
+    const acceptedStatus = ['ACTIVE', 'DISABLED'].includes(editorStatus.value || '') ? 'APPROVED' : 'PENDING'
+    for (const draft of qualifications.value) {
+      const item = [...records].reverse().find((record) => (
+        record.qualificationType === draft.type && record.status === acceptedStatus
+      ))
+      if (item) {
+        draft.uploaded = true
+        draft.validTo = item.validTo || ''
+        draft.documentUrl = item.documentUrl
+        try { draft.uploadedName = qualificationFileName(item.documentUrl) }
+        catch { draft.uploadedName = '已登记文件' }
+        draft.previewKind = draft.uploadedName.toLowerCase().endsWith('.pdf') ? 'pdf' : 'image'
+        if (draft.previewKind === 'image') void loadQualificationPreview(draft, tenantId, false)
+      }
+    }
+  } catch (error) { qualificationLoadError.value = getApiErrorMessage(error, '资质信息加载失败，可稍后重试') }
+}
+async function openEdit(row: PlatformTenantResource) {
+  const id = String(row.id)
+  const sequence = ++editorLoadSequence
+  editingId.value = id; editorStatus.value = row.status; resetEditor(); form.value = mapTenantToForm(row)
+  editorOpen.value = true; editorLoading.value = true
+  try {
+    const tenant = await getPlatformTenant(row.id)
+    if (sequence !== editorLoadSequence || editingId.value !== id || !editorOpen.value) return
+    editorStatus.value = tenant.status
+    form.value = mapTenantToForm(tenant)
+    creditCodeEstablished.value = unifiedSocialCreditCodePattern.test(tenant.unifiedSocialCreditCode || '')
+    savedFormSnapshot.value = JSON.stringify(form.value)
+    await loadEditorQualifications(row.id, sequence)
+    await nextTick(() => formRef.value?.clearValidate())
+  } catch (error) {
+    if (sequence === editorLoadSequence && editingId.value === id) editorOpen.value = false
+    ElMessage.error(getApiErrorMessage(error, '客户完整资料加载失败，请稍后重试'))
+  } finally {
+    if (sequence === editorLoadSequence && editingId.value === id) editorLoading.value = false
+  }
+}
+
+function selectQualificationFile(event: Event, draft: QualificationDraft) {
+  const input = event.target as HTMLInputElement
+  const file = input.files?.[0] || null
+  draft.error = ''; draft.file = null; clearDraftPreview(draft)
+  if (!file) return
+  const extensionValid = /\.(pdf|jpe?g|png)$/i.test(file.name)
+  const mimeValid = ['application/pdf', 'image/jpeg', 'image/png'].includes(file.type)
+  if (!extensionValid || !mimeValid) { draft.error = '仅支持 PDF、JPG、PNG 文件'; input.value = ''; return }
+  if (file.size > 5 * 1024 * 1024) { draft.error = '单个文件不能超过 5MB'; input.value = ''; return }
+  draft.file = file
+  draft.previewKind = file.type === 'application/pdf' || file.name.toLowerCase().endsWith('.pdf') ? 'pdf' : 'image'
+  draft.previewUrl = URL.createObjectURL(file)
+}
+
+async function loadQualificationPreview(draft: QualificationDraft, tenantId: number | string, showError = true) {
+  if (!draft.documentUrl || draft.previewLoading) return false
+  draft.previewLoading = true
+  try {
+    const blob = await downloadTenantQualification(tenantId, draft.documentUrl)
+    if (!blob.size) throw new Error('资质文件内容为空')
+    if (!editorOpen.value || !qualifications.value.includes(draft)) return false
+    clearDraftPreview(draft)
+    draft.previewKind = blob.type === 'application/pdf' || draft.uploadedName.toLowerCase().endsWith('.pdf') ? 'pdf' : 'image'
+    draft.previewUrl = URL.createObjectURL(blob)
+    return true
+  } catch (error) {
+    if (showError) ElMessage.error(getApiErrorMessage(error, '资质文件预览加载失败，请稍后重试'))
+    return false
+  } finally { draft.previewLoading = false }
+}
+
+async function openQualificationPreview(draft: QualificationDraft) {
+  if (draft.previewFailed) {
+    if (!draft.uploaded || !editingId.value) {
+      ElMessage.warning('该文件无法预览，请重新选择有效文件')
+      return
+    }
+    clearDraftPreview(draft)
+    draft.previewKind = draft.uploadedName.toLowerCase().endsWith('.pdf') ? 'pdf' : 'image'
+  }
+  if (!draft.previewUrl && draft.uploaded && editingId.value) {
+    await loadQualificationPreview(draft, editingId.value)
+  }
+  if (!draft.previewUrl || !draft.previewKind) return
+  qualificationPreviewName.value = draft.file?.name || draft.uploadedName || draft.label
+  qualificationPreviewUrl.value = draft.previewUrl
+  qualificationPreviewKind.value = draft.previewKind
+  qualificationPreviewOpen.value = true
+}
+
+function handleQualificationPreviewError(draft: QualificationDraft) {
+  draft.previewFailed = true
+  if (qualificationPreviewUrl.value === draft.previewUrl) qualificationPreviewOpen.value = false
+}
+
+
+async function uploadSelectedQualifications(tenantId: string) {
+  const failures: string[] = []
+  const businessLicense = qualifications.value.find((item) => item.type === 'BUSINESS_LICENSE')
+  const legalPersonId = qualifications.value.find((item) => item.type === 'LEGAL_PERSON_ID')
+  const businessLicenseFile = businessLicense?.file || null
+  const legalPersonIdFile = legalPersonId?.file || null
+  if (businessLicense && businessLicenseFile) {
+    businessLicense.uploading = true
+    if (legalPersonIdFile && legalPersonId) legalPersonId.uploading = true
+    businessLicense.error = ''
+    if (legalPersonId) legalPersonId.error = ''
+    try {
+      const uploaded = await uploadPlatformTenantRequiredQualificationPackage(
+        tenantId, businessLicenseFile, legalPersonIdFile, form.value.unifiedSocialCreditCode,
+        businessLicense.uploaded, Boolean(legalPersonIdFile && legalPersonId?.uploaded),
+      )
+      if (legalPersonIdFile && !uploaded.legalPersonIdDocumentUrl) throw new Error('法人身份证上传结果缺少文件地址')
+      businessLicense.uploaded = true
+      creditCodeEstablished.value = true
+      businessLicense.uploadedName = businessLicenseFile.name
+      businessLicense.documentUrl = uploaded.businessLicenseDocumentUrl
+      businessLicense.file = null
+      if (legalPersonIdFile && legalPersonId) {
+        legalPersonId.uploaded = true
+        legalPersonId.uploadedName = legalPersonIdFile.name
+        legalPersonId.documentUrl = uploaded.legalPersonIdDocumentUrl || ''
+        legalPersonId.file = null
+      }
+    } catch (error) {
+      const message = getApiErrorMessage(error, '营业执照及统一社会信用代码保存失败，请重试')
+      businessLicense.error = message
+      if (legalPersonIdFile && legalPersonId) legalPersonId.error = message
+      failures.push('营业执照资质')
+    } finally {
+      businessLicense.uploading = false
+      if (legalPersonId) legalPersonId.uploading = false
+    }
+  }
+  for (const draft of failures.length ? [] : qualifications.value.filter((item) => !item.required && item.file)) {
+    draft.uploading = true; draft.error = ''
+    try {
+      const uploaded = await uploadPlatformTenantQualification(
+        tenantId, draft.type, draft.file as File, draft.validTo || undefined,
+        undefined,
+        draft.uploaded,
+      )
+      draft.uploaded = true
+      draft.uploadedName = draft.file?.name || '已登记文件'
+      draft.documentUrl = uploaded.documentUrl
+      draft.file = null
+    } catch (error) {
+      draft.error = getApiErrorMessage(error, '上传失败，请重试'); failures.push(draft.label)
+    } finally { draft.uploading = false }
+  }
+  return failures
+}
+
+async function saveCustomer() {
+  if (!formRef.value || !(await formRef.value.validate().catch(() => false))) return
+  if (!requiredQualificationPackageComplete.value) {
+    ElMessage.warning(`请完整保存必填业务项：${missingQualificationPackageItems.value.join('、')}`)
+    return
+  }
+  saving.value = true
+  try {
+    const hadSelectedQualifications = hasSelectedQualifications.value
+    const hadBusinessLicense = Boolean(selectedBusinessLicense.value)
+    const hadLegalPersonId = Boolean(selectedLegalPersonId.value)
+    let saved: PlatformTenantResource
+    if (editingId.value) {
+      const { unifiedSocialCreditCode: _immutable, ...payload } = form.value
+      saved = await updatePlatformTenant(editingId.value, { ...payload, customerNickname: form.value.customerNickname.trim() })
+    } else {
+      const { unifiedSocialCreditCode: _qualificationCreditCode, ...payload } = form.value
+      const created = await createPlatformTenant(payload)
+      saved = created.tenant
+      editingId.value = String(saved.id)
+      credentialSource.value = 'creation'
+      approvalResult.value = {
+        tenantId: saved.id,
+        administratorCreated: true,
+        administratorUsername: created.administratorUsername,
+        temporaryPassword: created.temporaryPassword,
+      }
+      approvalResultOpen.value = true
+    }
+    editorStatus.value = saved.status
+    savedFormSnapshot.value = JSON.stringify(form.value)
+    const failures = hadSelectedQualifications ? await uploadSelectedQualifications(String(saved.id)) : []
+    if (failures.length) {
+      ElMessage.warning(`客户资料已保存，但${failures.join('、')}上传失败；失败文件已保留，请修正后再次保存`)
+    } else if (hadBusinessLicense && hadLegalPersonId) {
+      ElMessage.success('营业执照、统一社会信用代码和选填的法人身份证已保存，尚未提交审核')
+    } else if (hadBusinessLicense) {
+      ElMessage.success('营业执照和统一社会信用代码已保存，法人身份证可按需补充，尚未提交审核')
+    } else if (hadSelectedQualifications) {
+      ElMessage.success('客户资料和已选资质已保存，尚未提交审核')
+    } else {
+      ElMessage.success('客户资料已保存')
+    }
+    await loadCustomers()
+    if (!failures.length) editorOpen.value = false
+  } catch (error) { ElMessage.error(getApiErrorMessage(error, '客户资料保存失败，请稍后重试')) }
+  finally { saving.value = false }
+}
+
+async function submitReview() {
+  if (submitting.value) return
+  submitting.value = true
+  try {
+    if (!editingId.value) { ElMessage.warning('请先保存客户资料和资质文件'); return }
+    if (!formRef.value || !(await formRef.value.validate().catch(() => false))) return
+    if (hasUnsavedChanges.value) { ElMessage.warning('客户资料有未保存的修改，请先保存资料'); return }
+    if (uploadingQualifications.value) { ElMessage.warning('资质文件正在上传，请稍候再提交审核'); return }
+    if (hasSelectedQualifications.value) { ElMessage.warning('存在尚未保存的已选文件，请先点击“保存资料和资质”'); return }
+    if (!creditCodeEstablished.value || !unifiedSocialCreditCodePattern.test(form.value.unifiedSocialCreditCode || '')) {
+      ElMessage.warning('请先完整保存营业执照和18位统一社会信用代码；法人身份证为选填项')
+      return
+    }
+    const missing = qualifications.value.filter((item) => item.required && !item.uploaded)
+    for (const item of missing) item.error = `${item.label}为提交审核必填文件`
+    if (missing.length) { ElMessage.warning(`请先上传${missing.map((item) => item.label).join('、')}`); return }
+    await ElMessageBox.confirm('提交后客户资料与资质将进入企业审核，审核完成前不能继续替换文件。确认提交吗？', '提交企业审核', { customClass: 'admin-density-confirm', type: 'warning', confirmButtonText: '确认提交', cancelButtonText: '继续完善' })
+    const saved = await submitPlatformTenantReview(editingId.value)
+    editorStatus.value = saved.status; ElMessage.success('审核单已提交')
+    editorOpen.value = false; await loadCustomers()
+  } catch (error) {
+    if (error !== 'cancel' && error !== 'close') ElMessage.error(getApiErrorMessage(error, '提交审核失败，请稍后重试'))
+  } finally { submitting.value = false }
+}
+
+function showDetail(row: PlatformTenantResource) {
+  void router.push({ name: 'customer-detail', params: { tenantId: String(row.id) } })
+}
+function canResetPassword(row: PlatformTenantResource) {
+  return access.can('platform:customer:reset-password') && ['ACTIVE', 'DISABLED'].includes(row.status)
+}
+function canImpersonate(row: PlatformTenantResource) {
+  return access.can('platform:customer:impersonate') && row.status === 'ACTIVE'
+}
+function canChangeStatus(row: PlatformTenantResource) {
+  return access.can('platform:customer:status') && ['ACTIVE', 'DISABLED'].includes(row.status)
+}
+function canArchive(row: PlatformTenantResource) {
+  return access.can('platform:customer:delete') && ['PROFILE_REQUIRED', 'REJECTED'].includes(row.status)
+}
+type CustomerRowAction = 'reset-password' | 'impersonate' | 'status' | 'delete'
+function hasReviewAction(row: PlatformTenantResource) {
+  return pendingReviewByTenantId.value.has(String(row.id))
+    && access.can('platform:customer:review')
+    && (access.can('platform:customer:approve') || access.can('platform:customer:reject'))
+}
+function customerSecondaryActions(row: PlatformTenantResource): CustomerRowAction[] {
+  return [
+    ...(canResetPassword(row) ? ['reset-password' as const] : []),
+    ...(canImpersonate(row) ? ['impersonate' as const] : []),
+    ...(canChangeStatus(row) ? ['status' as const] : []),
+    ...(canArchive(row) ? ['delete' as const] : []),
+  ]
+}
+function customerPrimaryActionCount(row: PlatformTenantResource) {
+  return Number(access.can('platform:customer:list'))
+    + Number(access.can('platform:customer:edit') && row.status !== 'ARCHIVED')
+    + Number(hasReviewAction(row))
+}
+function customerDirectSecondaryActions(row: PlatformTenantResource) {
+  return customerSecondaryActions(row).slice(0, Math.max(0, 3 - customerPrimaryActionCount(row)))
+}
+function customerOverflowActions(row: PlatformTenantResource) {
+  return customerSecondaryActions(row).slice(Math.max(0, 3 - customerPrimaryActionCount(row)))
+}
+function customerMoreActionsLabel(row: PlatformTenantResource) {
+  const identity = row.tenantName || row.tenantCode || String(row.id || '当前客户')
+  return `更多客户操作：${identity}`
+}
+function customerActionLabel(row: PlatformTenantResource, action: CustomerRowAction) {
+  if (action === 'reset-password') return '重置密码'
+  if (action === 'impersonate') return '跳转登录'
+  if (action === 'status') return row.status === 'ACTIVE' ? '停用' : '启用'
+  return '删除'
+}
+function customerActionType(row: PlatformTenantResource, action: CustomerRowAction) {
+  if (action === 'delete' || (action === 'status' && row.status === 'ACTIVE')) return 'danger'
+  if (action === 'status') return 'success'
+  return 'primary'
+}
+function customerActionDisabled(action: CustomerRowAction) {
+  if (action === 'reset-password') return passwordSubmitting.value
+  if (action === 'impersonate') return impersonationSubmitting.value
+  if (action === 'delete') return archiveSubmitting.value
+  return false
+}
+function handleMoreAction(row: PlatformTenantResource, command: string) {
+  if (command === 'reset-password') openResetPassword(row)
+  if (command === 'impersonate') openImpersonation(row)
+  if (command === 'status') void toggleStatus(row)
+  if (command === 'delete') openArchive(row)
+}
+async function toggleStatus(row: PlatformTenantResource) {
+  const next = row.status === 'ACTIVE' ? 'DISABLED' : 'ACTIVE'; const verb = next === 'ACTIVE' ? '启用' : '停用'
+  try {
+    await ElMessageBox.confirm(`确认${verb}客户“${row.tenantName}”吗？`, `${verb}客户`, { customClass: 'admin-density-confirm', type: 'warning', confirmButtonText: `确认${verb}`, cancelButtonText: '取消' })
+    rowActionId.value = String(row.id); await changePlatformTenantStatus(row.id, next)
+    ElMessage.success(`客户已${verb}`); await loadCustomers()
+  } catch (error) {
+    if (error !== 'cancel' && error !== 'close') ElMessage.error(getApiErrorMessage(error, `客户${verb}失败`))
+  } finally { rowActionId.value = '' }
+}
+
+function randomPassword() {
+  const alphabet = 'ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz23456789!@#$%^&*'
+  const values = new Uint32Array(10)
+  crypto.getRandomValues(values)
+  const body = Array.from(values, (value) => alphabet[value % alphabet.length]).join('')
+  passwordForm.newPassword = `A7${body}`
+  passwordForm.confirmPassword = passwordForm.newPassword
+  void nextTick(() => passwordFormRef.value?.clearValidate())
+}
+
+function openResetPassword(row: PlatformTenantResource) {
+  passwordTenant.value = row
+  passwordForm.newPassword = ''
+  passwordForm.confirmPassword = ''
+  passwordForm.forceChangePassword = true
+  passwordError.value = null
+  passwordDialogOpen.value = true
+  void nextTick(() => passwordFormRef.value?.clearValidate())
+}
+
+async function submitResetPassword() {
+  if (!passwordTenant.value || passwordSubmitting.value || !passwordFormRef.value) return
+  const valid = await passwordFormRef.value.validate().then(() => true).catch(() => false)
+  if (!valid) return
+  passwordSubmitting.value = true
+  passwordError.value = null
+  try {
+    await resetPlatformTenantOwnerPassword(passwordTenant.value.id, {
+      newPassword: passwordForm.newPassword,
+      forceChangePassword: passwordForm.forceChangePassword,
+    })
+    ElMessage.success('企业管理员密码已重置')
+    passwordDialogOpen.value = false
+    passwordTenant.value = null
+    passwordForm.newPassword = ''
+    passwordForm.confirmPassword = ''
+  } catch (error) {
+    passwordError.value = getApiErrorDetails(error, '客户管理员密码重置失败，请稍后重试')
+  } finally {
+    passwordSubmitting.value = false
+  }
+}
+
+function openImpersonation(row: PlatformTenantResource) {
+  impersonationTenant.value = row
+  impersonationForm.reason = '协助客户处理业务问题'
+  impersonationError.value = null
+  impersonationDialogOpen.value = true
+  void nextTick(() => impersonationFormRef.value?.clearValidate())
+}
+
+async function submitImpersonation() {
+  if (!impersonationTenant.value || impersonationSubmitting.value || !impersonationFormRef.value) return
+  const valid = await impersonationFormRef.value.validate().then(() => true).catch(() => false)
+  if (!valid) return
+  const clientUrl = getClientWebUrl()
+  if (!clientUrl) {
+    impersonationError.value = getApiErrorDetails(new Error('未配置客户工作台地址'), '暂未配置客户工作台地址，无法安全跳转登录')
+    return
+  }
+  let targetUrl: URL
+  try {
+    targetUrl = new URL(clientUrl, window.location.origin)
+    targetUrl.pathname = `${targetUrl.pathname.replace(/\/+$/, '')}/login`
+    targetUrl.search = ''
+    targetUrl.hash = ''
+    targetUrl.searchParams.set('impersonationOrigin', window.location.origin)
+  } catch {
+    impersonationError.value = getApiErrorDetails(new Error('客户工作台地址无效'), '客户工作台地址配置无效，无法安全跳转登录')
+    return
+  }
+  const targetOrigin = targetUrl.origin
+  const popup = window.open(targetUrl.toString(), '_blank')
+  if (!popup) {
+    impersonationError.value = getApiErrorDetails(new Error('浏览器拦截了新窗口'), '浏览器拦截了客户工作台窗口，请允许弹窗后重试')
+    return
+  }
+  impersonationSubmitting.value = true
+  impersonationError.value = null
+  let handoffPending = false
+  try {
+    const ticket = await createPlatformTenantImpersonation(impersonationTenant.value.id, { reason: impersonationForm.reason.trim() })
+    let ticketSent = false
+    const onMessage = (event: MessageEvent) => {
+      if (event.source !== popup || event.origin !== targetOrigin || event.data?.source !== 'chongchong-client') return
+      if (event.data?.type === 'impersonation-ready' && !ticketSent) {
+        ticketSent = true
+        popup.postMessage({ source: 'chongchong-admin', type: 'impersonation-ticket', code: ticket.code }, targetOrigin)
+        return
+      }
+      if (event.data?.type === 'impersonation-failed') {
+        cleanup()
+        impersonationSubmitting.value = false
+        impersonationError.value = getApiErrorDetails(new Error('客户工作台未写入代登录会话'), '客户工作台登录写入失败，请关闭窗口后重试')
+        return
+      }
+      if (event.data?.type !== 'impersonation-complete') return
+      cleanup()
+      impersonationSubmitting.value = false
+      ElMessage.success('客户工作台登录成功')
+      impersonationDialogOpen.value = false
+    }
+    const timeout = window.setTimeout(() => {
+      cleanup()
+      impersonationSubmitting.value = false
+      impersonationError.value = getApiErrorDetails(new Error('客户工作台未确认会话写入'), '客户工作台未确认登录成功，请关闭窗口后重试')
+    }, 15000)
+    const cleanup = () => {
+      window.clearTimeout(timeout)
+      window.removeEventListener('message', onMessage)
+      if (impersonationCleanup === cleanup) impersonationCleanup = null
+    }
+    impersonationCleanup?.()
+    impersonationCleanup = cleanup
+    window.addEventListener('message', onMessage)
+    handoffPending = true
+  } catch (error) {
+    popup.close()
+    impersonationError.value = getApiErrorDetails(error, '跳转客户工作台失败，请稍后重试')
+  } finally {
+    if (!handoffPending) impersonationSubmitting.value = false
+  }
+}
+
+function openArchive(row: PlatformTenantResource) {
+  archiveTenant.value = row
+  archiveConfirmCode.value = ''
+  archiveError.value = null
+  archiveDialogOpen.value = true
+}
+
+async function submitArchive() {
+  if (!archiveTenant.value || archiveSubmitting.value || archiveConfirmCode.value.trim() !== archiveTenant.value.tenantCode) return
+  archiveSubmitting.value = true
+  archiveError.value = null
+  try {
+    await archivePlatformTenant(archiveTenant.value.id)
+    ElMessage.success('客户已归档，历史数据已保留且账号已停用')
+    archiveDialogOpen.value = false
+    archiveTenant.value = null
+    archiveConfirmCode.value = ''
+    await loadCustomers()
+  } catch (error) {
+    archiveError.value = getApiErrorDetails(error, '客户删除失败，当前客户仍保留')
+  } finally {
+    archiveSubmitting.value = false
+  }
+}
+
+async function openDecision(row: PlatformTenantResource, type: 'approve' | 'reject') {
+  if (reviewSubmitting.value) return
+  const review = pendingReviewByTenantId.value.get(String(row.id))
+  if (!review) {
+    ElMessage.warning('未找到该客户的待审核单，请刷新列表后重试')
+    return
+  }
+  selectedReview.value = review
+  decision.type = type
+  decision.comment = type === 'approve' ? '企业资料、营业执照和统一社会信用代码完整、清晰，审核通过（法人身份证为选填项）' : ''
+  decisionOpen.value = true
+  await loadReviewQualifications()
+  void nextTick(() => decisionFormRef.value?.clearValidate('comment'))
+}
+
+async function loadReviewQualifications() {
+  const review = selectedReview.value
+  if (!review) return
+  reviewQualifications.value = []
+  reviewQualificationsError.value = null
+  reviewQualificationsLoading.value = true
+  try {
+    reviewQualifications.value = await listTenantQualifications(review.tenantId)
+  } catch (error) {
+    reviewQualificationsError.value = getApiErrorDetails(error, '客户资质加载失败，请重试后再审核')
+  } finally {
+    reviewQualificationsLoading.value = false
+  }
+}
+
+function clearReviewPreview() {
+  if (reviewPreviewUrl.value) URL.revokeObjectURL(reviewPreviewUrl.value)
+  reviewPreviewOpen.value = false
+  reviewPreviewUrl.value = ''
+  reviewPreviewName.value = ''
+}
+
+async function loadReviewDocument(item: PlatformTenantQualification, download: boolean) {
+  const review = selectedReview.value
+  if (!review || reviewDocumentLoading.value) return
+  const fileName = qualificationName(item)
+  reviewDocumentLoading.value = String(item.id)
+  try {
+    const blob = await downloadTenantQualification(review.tenantId, item.documentUrl)
+    const url = URL.createObjectURL(blob)
+    if (download) {
+      const anchor = document.createElement('a')
+      anchor.href = url
+      anchor.download = fileName
+      anchor.click()
+      URL.revokeObjectURL(url)
+      return
+    }
+    clearReviewPreview()
+    reviewPreviewName.value = fileName
+    reviewPreviewKind.value = blob.type === 'application/pdf' || fileName.toLowerCase().endsWith('.pdf') ? 'pdf' : 'image'
+    reviewPreviewUrl.value = url
+    reviewPreviewOpen.value = true
+  } catch (error) {
+    ElMessage.error(getApiErrorMessage(error, '资质文件读取失败，请稍后重试'))
+  } finally {
+    reviewDocumentLoading.value = ''
+  }
+}
+
+async function submitDecision() {
+  const review = selectedReview.value
+  if (!review || !decisionFormRef.value || reviewSubmitting.value) return
+  const valid = await decisionFormRef.value.validate().then(() => true).catch(() => false)
+  if (!valid) return
+  reviewSubmitting.value = true
+  try {
+    let approved: EnterpriseApprovalResponse | null = null
+    if (decision.type === 'approve') {
+      approved = await approveEnterpriseReview(review.id, decision.comment.trim())
+    } else {
+      await rejectEnterpriseReview(review.id, decision.comment.trim())
+    }
+    decisionOpen.value = false
+    const successMessage = decision.type === 'reject'
+      ? '企业资料已驳回'
+      : approved?.administratorCreated
+        ? '企业资料已审核通过，管理员账号已创建'
+        : '企业资料已审核通过，注册账号继续作为企业管理员'
+    ElMessage.success(successMessage)
+    if (approved?.administratorCreated) {
+      credentialSource.value = 'approval'
+      approvalResult.value = approved
+      approvalResultOpen.value = true
+    }
+    await loadCustomers()
+  } catch (error) {
+    ElMessage.error(getApiErrorMessage(error, '审核提交失败，请稍后重试'))
+  } finally {
+    reviewSubmitting.value = false
+  }
+}
+
+function closeApprovalResult() {
+  approvalResultOpen.value = false
+  approvalResult.value = null
+}
+
+async function exportCustomers() {
+  exportSubmitting.value = true
+  let task: Awaited<ReturnType<typeof createPlatformExportTask>>
+  try {
+    task = await createPlatformExportTask({
+      exportType: 'CUSTOMER_LIST',
+      format: 'XLSX',
+      taskName: '客户列表',
+      parameters: {
+        keyword: filters.value.keyword.trim() || undefined,
+        status: filters.value.status || undefined,
+      },
+    })
+  } catch (error) {
+    ElMessage.error(getApiErrorMessage(error, '客户导出任务创建失败'))
+    return
+  } finally {
+    exportSubmitting.value = false
+  }
+
+  const openDownloadCenter = await showExportTaskCreatedDialog({ taskName: task.taskName, taskNo: task.taskNo })
+  if (openDownloadCenter) await router.push({ name: 'download-center' })
+}
+
+async function openRouteEditor(editId: string) {
+  if (!editId || !access.can('platform:customer:edit')) return
+  const row = result.value.records.find((item) => String(item.id) === editId)
+  try {
+    await openEdit(row ?? await getPlatformTenant(editId))
+  } catch (error) {
+    ElMessage.error(getApiErrorMessage(error, '客户资料加载失败'))
+  }
+  if (route.query.edit === editId) void router.replace({ name: 'customers' })
+}
+
+watch([page, pageSize], () => { void loadCustomers() })
+watch(
+  () => typeof route.query.edit === 'string' ? route.query.edit : '',
+  (editId) => { if (editId) void openRouteEditor(editId) },
+  { immediate: true },
+)
+watch(editorOpen, (open) => {
+  if (!open) {
+    editorLoadSequence += 1
+    clearQualificationPreviews()
+  }
+})
+watch(
+  () => [access.can('platform:customer:approve'), access.can('platform:customer:reject')],
+  ([canApprove, canReject]) => {
+    if ((decision.type === 'approve' && !canApprove) || (decision.type === 'reject' && !canReject)) decisionOpen.value = false
+  },
+)
+watch(() => decision.type, (type) => {
+  if (!decisionOpen.value) return
+  decision.comment = type === 'approve' ? '企业资料、营业执照和统一社会信用代码完整、清晰，审核通过（法人身份证为选填项）' : ''
+  void nextTick(() => decisionFormRef.value?.clearValidate('comment'))
+})
+onBeforeUnmount(() => {
+  clearQualificationPreviews()
+  clearReviewPreview()
+  impersonationCleanup?.()
+})
+onMounted(() => { void loadCustomers() })
+</script>
+
+<template>
+  <AdminPage as="div" class="customers-page admin-density customer-density">
+    <OperationErrorToast :details="passwordError || impersonationError || archiveError" />
+    <ListPageLayout aria-label="客户管理">
+      <template #toolbar><QueryToolbar v-model="filters" class="surface-panel" ariaLabel="客户筛选" :fields="queryFields" preference-key="customers-query" @search="applyFilters" /></template>
+      <template v-if="loadError" #state>
+        <LoadErrorState title="客户列表暂时无法加载" :message="loadError.message" :loading="loading" @retry="loadCustomers">
+          <template #details><ApiErrorMeta :details="loadError" /></template>
+        </LoadErrorState>
+      </template>
+      <section v-if="!loadError" class="surface-panel table-panel" :aria-busy="loading">
+      <div v-if="reviewLoadError" class="review-sync-error" role="alert"><div><ShieldX :size="17" /><span>{{ reviewLoadError.message }}</span></div><el-button link type="primary" @click="reloadPendingReviews">重新加载待审核客户</el-button></div>
+      <DataTable v-model:page="page" v-model:page-size="pageSize" :data="result.records" :columns="customerColumns" preference-key="customers-table" :loading="loading" :total="result.total" aria-label="客户列表" row-key="id" empty-text="暂无符合筛选条件的客户" class="customer-list-table" :stripe="true" border>
+        <template #toolbar-actions><div class="customers-table-actions"><el-button v-if="access.can('platform:customer:export') && access.can('platform:download:list')" :loading="exportSubmitting" :disabled="loading || exportSubmitting" @click="exportCustomers">导出Excel</el-button><el-button v-if="access.can('platform:customer:create')" type="primary" :disabled="loading" @click="openCreate">新增客户</el-button></div></template>
+        <template #actions="{ row }">
+          <div class="table-actions density-actions">
+            <el-button v-if="access.can('platform:customer:list')" class="density-action customer-action-detail" size="small" @click="showDetail(row as PlatformTenantResource)">详情</el-button>
+            <el-button v-if="access.can('platform:customer:edit') && (row as PlatformTenantResource).status !== 'ARCHIVED'" class="density-action customer-action-edit" size="small" @click="openEdit(row as PlatformTenantResource)">编辑</el-button>
+            <el-button v-if="hasReviewAction(row as PlatformTenantResource)" class="density-action" data-tone="warning" size="small" :disabled="reviewSubmitting" @click="openDecision(row as PlatformTenantResource, access.can('platform:customer:approve') ? 'approve' : 'reject')">审核</el-button>
+            <el-button v-for="action in customerDirectSecondaryActions(row as PlatformTenantResource)" :key="action" class="density-action" :data-tone="action === 'reset-password' ? 'purple' : action === 'impersonate' ? 'primary' : action === 'status' && (row as PlatformTenantResource).status !== 'ACTIVE' ? 'success' : 'danger'" size="small" :disabled="customerActionDisabled(action)" @click="handleMoreAction(row as PlatformTenantResource, action)">{{ customerActionLabel(row as PlatformTenantResource, action) }}</el-button>
+            <el-dropdown v-if="customerOverflowActions(row as PlatformTenantResource).length" trigger="click" popper-class="customer-action-menu" @command="handleMoreAction(row as PlatformTenantResource, $event as string)">
+              <el-button class="density-action customer-action-more" size="small" plain :aria-label="customerMoreActionsLabel(row as PlatformTenantResource)" :title="customerMoreActionsLabel(row as PlatformTenantResource)"><MoreHorizontal :size="17" aria-hidden="true" /></el-button>
+              <template #dropdown><el-dropdown-menu><el-dropdown-item v-for="action in customerOverflowActions(row as PlatformTenantResource)" :key="action" :command="action" :disabled="customerActionDisabled(action)" :class="{ 'customer-action-menu__danger': customerActionType(row as PlatformTenantResource, action) === 'danger' }">{{ customerActionLabel(row as PlatformTenantResource, action) }}</el-dropdown-item></el-dropdown-menu></template>
+            </el-dropdown>
+          </div>
+        </template>
+        <template #company="{ row }"><strong class="customer-company-name">{{ (row as PlatformTenantResource).tenantName }}</strong></template>
+        <template #status="{ row }"><el-tag :type="statusMeta((row as PlatformTenantResource).status).type" effect="light">{{ statusMeta((row as PlatformTenantResource).status).label }}</el-tag></template>
+        <template #orderCount="{ row }">{{ access.can('platform:order:list') ? (orderCounts[String((row as PlatformTenantResource).id)] ?? '—') : '—' }}</template>
+        <template #pagination-left="{ total: tableTotal }"><span>共 {{ tableTotal }} 个客户</span></template>
+      </DataTable>
+      </section>
+    </ListPageLayout>
+
+    <AppDialog v-model="editorOpen" :title="editorTitle" :width="editorDialogWidth" class="admin-density-dialog customer-density-dialog customer-editor-dialog" :loading="editorLoading" :confirm-loading="saving" destroy-on-close>
+      <el-form ref="formRef" v-loading="editorLoading" :model="form" :rules="rules" label-position="top" class="drawer-form" :disabled="editorLoading || saving || submitting || uploadingQualifications">
+        <FormSection title="基础资料" description="维护工商登记和企业主体信息。"><div class="form-grid three-cols">
+          <el-form-item label="公司名称" prop="tenantName" required><el-input v-model="form.tenantName" placeholder="请输入工商登记公司名称" maxlength="128" /></el-form-item>
+          <el-form-item label="客户昵称" prop="customerNickname"><el-input v-model="form.customerNickname" placeholder="不填默认生成中文拼音大写首字母，如 SZWL" maxlength="32" /><small class="field-hint">创建后仍可在客户资料中修改。</small></el-form-item>
+          <el-form-item label="营业执照企业名称" prop="legalName" required><el-input v-model="form.legalName" placeholder="请输入营业执照上的企业名称" maxlength="128" /></el-form-item>
+          <el-form-item label="法定代表人" prop="legalRepresentative"><el-input v-model="form.legalRepresentative" placeholder="请输入法定代表人姓名（选填）" maxlength="64" /></el-form-item>
+          <el-form-item label="企业类型" prop="enterpriseType"><el-input v-model="form.enterpriseType" placeholder="如：有限责任公司" maxlength="64" /></el-form-item>
+          <el-form-item label="成立日期" prop="establishedDate"><el-date-picker style="width: 100%;" v-model="form.establishedDate" type="date" value-format="YYYY-MM-DD" placeholder="请选择成立日期" :disabled-date="(date: Date) => date.getTime() > Date.now()" /></el-form-item>
+          <el-form-item label="注册资本" prop="registeredCapital"><div class="capital-input"><el-input-number v-model="form.registeredCapital" :min="0" :precision="2" controls-position="right" placeholder="请输入注册资本（选填）" /><el-select v-model="form.registeredCapitalCurrency" aria-label="注册资本币种"><el-option label="人民币 CNY" value="CNY" /><el-option label="美元 USD" value="USD" /><el-option label="港币 HKD" value="HKD" /></el-select></div></el-form-item>
+        </div><el-form-item label="注册地址" prop="registeredAddress"><el-input v-model="form.registeredAddress" placeholder="请输入省市区、街道及门牌信息" maxlength="500" /></el-form-item></FormSection>
+
+        <FormSection title="联系与商务" description="维护客户联系人、账期和内部跟进信息。"><div class="form-grid three-cols">
+          <el-form-item label="联系人" prop="contactName" required><el-input v-model="form.contactName" placeholder="请输入主要联系人姓名" maxlength="64" /></el-form-item>
+          <el-form-item label="公司联系电话" prop="contactPhone" required><el-input v-model="form.contactPhone" placeholder="请输入公司联系电话" maxlength="32" /><small class="field-hint">仅用于企业业务联系，不会修改企业管理员登录手机号；登录手机号请在成员/账号管理中单独维护，修改会影响登录。</small></el-form-item>
+          <el-form-item label="联系邮箱" prop="contactEmail"><el-input v-model="form.contactEmail" placeholder="如：contact@example.com" maxlength="128" /></el-form-item>
+          <el-form-item label="联系微信" prop="contactWechat"><el-input v-model="form.contactWechat" placeholder="请输入联系人微信号" maxlength="64" /></el-form-item>
+          <!-- <el-form-item label="客户套餐" prop="servicePackage" required><el-select v-model="form.servicePackage"><el-option label="基础版" value="基础版" /><el-option label="专业版" value="专业版" /><el-option label="企业版" value="企业版" /></el-select></el-form-item> -->
+          <el-form-item label="销售人员" prop="salesOwnerName"><el-input v-model="form.salesOwnerName" placeholder="请输入负责销售人员" maxlength="64" /></el-form-item>
+          <el-form-item label="账期(天)" prop="paymentTermDays" required><el-input-number v-model="form.paymentTermDays" :min="0" :max="365" controls-position="right" placeholder="请输入账期天数" /></el-form-item>
+        </div><el-form-item label="内部备注" prop="internalRemark"><el-input v-model="form.internalRemark" type="textarea" :rows="3" placeholder="请输入仅平台人员可见的客户备注" maxlength="1000" show-word-limit /></el-form-item></FormSection>
+
+        <FormSection class="qualification-section" title="企业认证资料" description="营业执照和18位统一社会信用代码为必填业务项；法人身份证、货代资质证书和银行开户许可证均为选填。"><div v-if="editorStatus" class="qualification-heading"><el-tag :type="statusMeta(editorStatus).type" effect="light">{{ statusMeta(editorStatus).label }}</el-tag></div>
+          <el-form-item label="统一社会信用代码" prop="unifiedSocialCreditCode" required class="qualification-credit-code"><el-input v-model="form.unifiedSocialCreditCode" :disabled="creditCodeEstablished" placeholder="请输入18位大写字母或数字" maxlength="18" @input="form.unifiedSocialCreditCode = String($event).toUpperCase()" /><small>{{ creditCodeEstablished ? '已登记的统一社会信用代码不可直接修改。' : '必须与营业执照一致，并随营业执照共同保存；法人身份证为选填。' }}</small></el-form-item>
+          <div v-if="qualificationLoadError" class="qualification-load-error" role="alert">{{ qualificationLoadError }}<el-button v-if="editingId" link type="primary" @click="loadEditorQualifications(editingId)">重试</el-button></div>
+          <div class="qualification-table" role="table" aria-label="客户资质文件">
+            <div class="qualification-row qualification-header" role="row"><span role="columnheader">文件类型</span><span role="columnheader">上传文件</span><span role="columnheader">有效期</span></div>
+            <div v-for="draft in qualifications" :key="draft.type" class="qualification-row" role="row">
+              <div class="qualification-label" role="cell"><span v-if="draft.required" aria-hidden="true">*</span>{{ draft.label }}<small v-if="!draft.required" class="qualification-optional">选填</small><CheckCircle2 v-if="draft.uploaded" :size="16" aria-label="已上传" /></div>
+              <div class="qualification-file" role="cell">
+                <button v-if="draft.file || draft.uploaded" type="button" class="qualification-preview-trigger" :class="{ 'is-loading': draft.previewLoading }" :disabled="draft.previewLoading" :aria-label="`预览${draft.label}：${draft.file?.name || draft.uploadedName}`" @click="openQualificationPreview(draft)">
+                  <img v-if="draft.previewUrl && draft.previewKind === 'image' && !draft.previewFailed" :src="draft.previewUrl" :alt="`${draft.label}预览`" @error="handleQualificationPreviewError(draft)" />
+                  <span v-else class="qualification-preview-placeholder"><FileText :size="20" /><small>{{ draft.previewKind === 'pdf' ? 'PDF' : '文件' }}</small></span>
+                  <span class="qualification-preview-action">{{ draft.previewLoading ? '读取中' : (draft.previewFailed ? '重试' : '查看') }}</span>
+                </button>
+                <div class="qualification-file-control"><label class="file-picker" :class="{ 'is-disabled': !canUploadQualifications || draft.uploading }"><span>{{ draft.uploading ? '上传中' : (draft.file ? '已选择新文件' : (draft.uploaded ? '更换文件' : '选择文件')) }}</span><input type="file" accept=".pdf,.jpg,.jpeg,.png,application/pdf,image/jpeg,image/png" :disabled="!canUploadQualifications || draft.uploading" @change="selectQualificationFile($event, draft)" /></label><span class="qualification-file-name" :title="draft.file?.name || draft.uploadedName">{{ draft.file?.name || draft.uploadedName || '未选择文件' }}</span><small v-if="draft.error" class="qualification-error" role="alert">{{ draft.error }}</small></div>
+              </div>
+              <div class="qualification-validity" role="cell"><el-date-picker v-model="draft.validTo" type="date" value-format="YYYY-MM-DD" placeholder="请选择有效期" :disabled="!canUploadQualifications || draft.uploaded" /></div>
+            </div>
+          </div>
+          <p class="qualification-hint">支持 PDF、JPG、PNG，单个文件不超过 5MB；<span>*</span> 为提交审核必填项。</p>
+        </FormSection>
+      </el-form>
+      <template #footer><div class="customer-editor-footer"><span>保存资料时会一并上传已选资质；进入审核仍需点击“提交审核”并再次确认</span><div><el-button :disabled="editorLoading || saving || submitting || uploadingQualifications" @click="editorOpen = false">关闭</el-button><el-button :loading="saving" :disabled="editorLoading || submitting || uploadingQualifications" @click="saveCustomer">保存资料和资质</el-button><el-button v-if="canSubmitReview" type="primary" :loading="submitting" :disabled="editorLoading || saving || uploadingQualifications" @click="submitReview">提交审核</el-button></div></div></template>
+    </AppDialog>
+
+    <AppDialog v-model="qualificationPreviewOpen" :title="qualificationPreviewName || '查看资质文件'" width="min(860px, calc(100vw - 28px))" class="admin-density-dialog customer-density-dialog qualification-preview-dialog" destroy-on-close :show-confirm="false" cancel-text="关闭预览">
+      <div class="qualification-preview">
+        <img v-if="qualificationPreviewUrl && qualificationPreviewKind === 'image'" :src="qualificationPreviewUrl" :alt="`${qualificationPreviewName}预览`" />
+        <iframe v-else-if="qualificationPreviewUrl && qualificationPreviewKind === 'pdf'" :src="qualificationPreviewUrl" :title="`${qualificationPreviewName} PDF 预览`" />
+      </div>
+    </AppDialog>
+
+    <el-dialog v-model="approvalResultOpen" :title="credentialSource === 'creation' ? '客户已创建，管理员账号已生成' : '审核通过，管理员账号已创建'" width="min(560px, calc(100vw - 28px))" class="admin-density-dialog customer-density-dialog approval-result-dialog" :close-on-click-modal="false" :close-on-press-escape="false" :show-close="false">
+      <div v-if="approvalResult" class="approval-result-content">
+        <div class="approval-result-warning" role="alert"><ShieldCheck :size="20" /><div><strong>请立即保存以下一次性凭证</strong><span>临时密码只在本次{{ credentialSource === 'creation' ? '创建' : '审核' }}响应中返回，关闭后无法再次查看。</span></div></div>
+        <dl class="approval-credentials">
+          <div><dt>登录账号</dt><dd><code>{{ approvalResult.administratorUsername || '未返回' }}</code><CopyButton v-if="approvalResult.administratorUsername" :value="approvalResult.administratorUsername" label="登录账号" size="small" /></dd></div>
+          <div><dt>临时密码</dt><dd><code>{{ approvalResult.temporaryPassword || '未返回' }}</code><CopyButton v-if="approvalResult.temporaryPassword" :value="approvalResult.temporaryPassword" label="临时密码" size="small" /></dd></div>
+        </dl>
+      </div>
+      <template #footer><el-button type="primary" @click="closeApprovalResult">我已保存，关闭</el-button></template>
+    </el-dialog>
+
+    <el-dialog v-model="decisionOpen" title="客户入驻审核" width="min(1040px, calc(100vw - 28px))" class="admin-density-dialog customer-density-dialog review-decision-dialog" :close-on-click-modal="false">
+      <div v-if="selectedReview" class="review-dialog-content">
+        <header class="review-dialog-header">
+          <div class="review-dialog-title"><span class="review-dialog-icon"><Building2 :size="18" /></span><div><strong>{{ selectedReview.tenantName || '未命名客户' }}</strong><span>客户编号：{{ selectedReview.tenantCode || '未生成' }}</span></div></div>
+          <el-tag type="warning" effect="plain">待审核</el-tag>
+        </header>
+        <div class="review-dialog-grid">
+          <section class="review-dialog-section review-dialog-card">
+            <div class="review-section-heading"><div><h3>企业基本信息</h3><span>核对客户提交的主体资料</span></div><CircleCheck :size="18" /></div>
+            <dl class="review-info-grid density-fields">
+              <div><dt>客户名称</dt><dd>{{ selectedReview.tenantName || '未填写' }}</dd></div>
+              <div><dt>客户编号</dt><dd>{{ selectedReview.tenantCode || '未生成' }}</dd></div>
+              <div><dt>联系人</dt><dd>{{ selectedReview.contactName || '未填写' }}</dd></div>
+              <div><dt>公司联系电话</dt><dd>{{ selectedReview.contactPhone || '未填写' }}</dd></div>
+              <div><dt>联系邮箱</dt><dd>{{ selectedReview.contactEmail || '未填写' }}</dd></div>
+              <div><dt>提交时间</dt><dd>{{ formatDate(selectedReview.submittedAt || selectedReview.createdAt) }}</dd></div>
+            </dl>
+          </section>
+          <section class="review-dialog-section review-dialog-card">
+            <div class="review-section-heading"><div><h3>资质文件</h3><span>营业执照为必填；法人身份证及其他资质为选填。共 {{ reviewQualifications.length }} 份</span></div><FileCheck2 :size="18" /></div>
+            <div v-if="reviewQualificationsLoading" class="review-document-state">正在加载资质文件...</div>
+            <div v-else-if="reviewQualificationsError" class="review-document-error" role="alert"><span>{{ reviewQualificationsError.message }}</span><el-button link type="primary" @click="loadReviewQualifications">重试</el-button></div>
+            <div v-else class="review-document-table" role="table" aria-label="待审核客户资质">
+              <div class="review-document-header" role="row"><span role="columnheader">资质类型</span><span role="columnheader">已上传文件</span><span role="columnheader">操作</span></div>
+              <div v-for="item in reviewQualifications" :key="String(item.id)" class="review-document-row" role="row"><span role="cell" class="review-document-type">{{ qualificationLabel(item.qualificationType) }}</span><span role="cell" class="review-document-name" :title="qualificationName(item)"><FileText :size="15" />{{ qualificationName(item) }}</span><span role="cell" class="review-document-actions"><el-button link type="primary" :loading="reviewDocumentLoading === String(item.id)" @click="loadReviewDocument(item, false)">预览</el-button><el-button link :disabled="Boolean(reviewDocumentLoading)" @click="loadReviewDocument(item, true)">下载</el-button></span></div>
+              <div v-if="reviewQualifications.length === 0" class="review-document-empty"><FileText :size="18" /><span>暂无资质文件</span></div>
+            </div>
+          </section>
+        </div>
+        <section class="review-decision-card">
+          <div class="review-section-heading"><div><h3>审核决定</h3><span>确认资料无误后提交审核结果</span></div><ShieldCheck :size="18" /></div>
+          <el-radio-group v-if="access.can('platform:customer:approve') && access.can('platform:customer:reject')" v-model="decision.type" class="decision-type" aria-label="审核决定"><el-radio-button label="approve">通过</el-radio-button><el-radio-button label="reject">驳回</el-radio-button></el-radio-group>
+          <el-form ref="decisionFormRef" :model="decision" :rules="decisionRules" label-position="top">
+            <el-form-item prop="comment" :label="decision.type === 'approve' ? '审核意见' : '驳回原因'" required><el-input v-model="decision.comment" type="textarea" :rows="3" maxlength="300" show-word-limit :placeholder="decision.type === 'approve' ? '可填写审核意见' : '请明确说明需要企业修改的内容'" /></el-form-item>
+          </el-form>
+        </section>
+      </div>
+      <template #footer><div class="drawer-footer"><el-button :disabled="reviewSubmitting" @click="decisionOpen = false">取消</el-button><el-button v-if="access.can('platform:customer:reject') && decision.type === 'reject'" type="danger" :loading="reviewSubmitting" @click="submitDecision">确认驳回</el-button><el-button v-if="access.can('platform:customer:approve') && decision.type === 'approve'" type="primary" :loading="reviewSubmitting" @click="submitDecision">审核通过</el-button></div></template>
+    </el-dialog>
+
+    <AppDialog class="admin-density-dialog customer-density-dialog" v-model="reviewPreviewOpen" :title="reviewPreviewName || '查看资质文件'" width="min(860px, calc(100vw - 28px))" destroy-on-close :show-confirm="false" cancel-text="关闭预览" @closed="clearReviewPreview">
+      <div class="qualification-preview"><img v-if="reviewPreviewUrl && reviewPreviewKind === 'image'" :src="reviewPreviewUrl" :alt="`${reviewPreviewName}预览`" /><iframe v-else-if="reviewPreviewUrl" :src="reviewPreviewUrl" :title="`${reviewPreviewName} PDF 预览`" /></div>
+    </AppDialog>
+
+    <el-dialog v-model="passwordDialogOpen" title="重置客户密码" width="min(520px, calc(100vw - 28px))" class="admin-density-dialog customer-density-dialog customer-password-dialog" :close-on-click-modal="false" :close-on-press-escape="!passwordSubmitting" :show-close="!passwordSubmitting">
+      <div v-if="passwordTenant" class="decision-summary"><div><strong>正在重置企业管理员登录密码</strong><span>{{ passwordTenant.tenantName }}</span></div><span>客户编号：{{ passwordTenant.tenantCode }}</span></div>
+      <el-form ref="passwordFormRef" :model="passwordForm" :rules="passwordRules" label-position="top">
+        <el-form-item label="新密码" prop="newPassword" required><div class="password-input-row"><el-input v-model="passwordForm.newPassword" type="password" show-password autocomplete="new-password" placeholder="请输入 8-20 位新密码" /><el-button @click="randomPassword">随机生成</el-button></div></el-form-item>
+        <el-form-item label="确认新密码" prop="confirmPassword" required><el-input v-model="passwordForm.confirmPassword" type="password" show-password autocomplete="new-password" placeholder="请再次输入新密码" /></el-form-item>
+        <el-checkbox v-model="passwordForm.forceChangePassword">客户下次登录时必须修改密码</el-checkbox>
+        <p class="dialog-hint">重置对象为企业 OWNER 管理员，原密码将立即失效。</p>
+      </el-form>
+      <template #footer><div class="drawer-footer"><el-button :disabled="passwordSubmitting" @click="passwordDialogOpen = false">取消</el-button><el-button type="primary" :loading="passwordSubmitting" @click="submitResetPassword">确认重置</el-button></div></template>
+    </el-dialog>
+
+    <el-dialog class="admin-density-dialog customer-density-dialog" v-model="impersonationDialogOpen" title="跳转登录客户工作台" width="min(560px, calc(100vw - 28px))" :close-on-click-modal="false" :close-on-press-escape="!impersonationSubmitting" :show-close="!impersonationSubmitting">
+      <div v-if="impersonationTenant" class="decision-summary"><div><strong>{{ impersonationTenant.tenantName }}</strong><span>将以企业管理员身份打开客户工作台</span></div><span>客户编号：{{ impersonationTenant.tenantCode }}</span></div>
+      <el-alert type="warning" :closable="false" show-icon>本操作会生成一次性、短时有效的客户会话，并记录代登录原因；不会替换当前 Admin 会话。</el-alert>
+      <el-form ref="impersonationFormRef" :model="impersonationForm" :rules="impersonationRules" label-position="top"><el-form-item label="代登录原因" prop="reason" required><el-input v-model="impersonationForm.reason" type="textarea" :rows="4" maxlength="500" show-word-limit placeholder="请填写 5-500 字的业务原因" /></el-form-item></el-form>
+      <template #footer><div class="drawer-footer"><el-button :disabled="impersonationSubmitting" @click="impersonationDialogOpen = false">取消</el-button><el-button type="primary" :loading="impersonationSubmitting" @click="submitImpersonation">确认跳转</el-button></div></template>
+    </el-dialog>
+
+    <el-dialog class="admin-density-dialog customer-density-dialog" v-model="archiveDialogOpen" title="删除客户" width="min(560px, calc(100vw - 28px))" :close-on-click-modal="false" :close-on-press-escape="!archiveSubmitting" :show-close="!archiveSubmitting">
+      <el-alert type="warning" :closable="false" show-icon>删除是逻辑归档：历史业务数据会保留，客户账号会被停用。是否允许归档由服务端最终判断。</el-alert>
+      <div v-if="archiveTenant" class="archive-confirm"><strong>{{ archiveTenant.tenantName }}</strong><span>请输入客户编号 {{ archiveTenant.tenantCode }} 以确认。</span><el-input v-model="archiveConfirmCode" :disabled="archiveSubmitting" :placeholder="archiveTenant.tenantCode" autocomplete="off" /></div>
+      <template #footer><div class="drawer-footer"><el-button :disabled="archiveSubmitting" @click="archiveDialogOpen = false">取消</el-button><el-button type="danger" :loading="archiveSubmitting" :disabled="!archiveTenant || archiveConfirmCode.trim() !== archiveTenant.tenantCode" @click="submitArchive">确认删除</el-button></div></template>
+    </el-dialog>
+  </AdminPage>
+</template>
+
+<style scoped>
+.customers-table-heading { display:flex; min-width:0; align-items:baseline; gap:var(--admin-space-4, 10px); } .customers-table-heading h2 { margin:0; color:var(--cc-text); font-size:var(--admin-font-title, 16px); } .customers-table-heading span { color:var(--cc-muted); font-size:var(--admin-font-caption, 12px); white-space:nowrap; }
+.customers-table-actions { display:flex; flex-wrap:wrap; gap:var(--admin-space-3, 8px); } .customers-table-actions :deep(.el-button + .el-button) { margin-left:0; }
+.table-actions { display:flex; flex-wrap:wrap; align-items:center; } .table-actions :deep(.el-button) { margin-left:0; }
+:global(.customer-action-menu .el-dropdown-menu__item) { min-height:40px; gap:var(--admin-space-3, 8px); }
+:global(.customer-action-menu .customer-action-menu__danger) { color:var(--el-color-danger); }
+.review-sync-error { display:flex; min-width:0; align-items:center; justify-content:space-between; gap:var(--admin-space-5, 12px); padding:var(--admin-space-4, 10px) 18px; border-bottom:1px solid #fecdca; background:#fffafa; color:#b42318; font-size:var(--admin-font-caption, 12px); } .review-sync-error > div { display:flex; min-width:0; align-items:center; gap:var(--admin-space-3, 8px); } .review-sync-error span { overflow-wrap:anywhere; }
+.customer-company-name { display:block; overflow:hidden; color:#334155; font-weight:500; text-overflow:ellipsis; white-space:nowrap; }
+.customers-table-actions :deep(.el-button--default) { border-color:rgba(102,126,234,.22); }
+:deep(.customer-list-table .customer-code-column .cell) { white-space:nowrap; }
+.capital-input { display:grid; grid-template-columns:minmax(0,1fr) 130px; width:100%; gap:var(--admin-space-3, 8px); } .capital-input :deep(.el-input-number) { width:100%; } .capital-input :deep(.el-select) { width:100%; }
+.qualification-heading { display:flex; justify-content:flex-end; margin-bottom:var(--admin-space-5, 12px); } .qualification-hint { margin:var(--admin-space-5, 12px) 0 0; color:var(--cc-muted); font-size:var(--admin-font-caption, 12px); line-height:1.6; } .qualification-hint span { color:var(--el-color-danger); } .qualification-label > span { color:var(--el-color-danger); }
+.qualification-credit-code { max-width:420px; margin-top:var(--admin-space-6, 16px); } .qualification-credit-code small { display:block; margin-top:var(--admin-space-2, 6px); color:var(--cc-muted); font-size:var(--admin-font-caption, 11px); line-height:1.5; } .field-hint { display:block; margin-top:var(--admin-space-2, 6px); color:var(--cc-muted); line-height:1.5; }
+.qualification-table { overflow:hidden; margin-top:14px; border:1px solid var(--cc-border); border-radius:8px; } .qualification-row { display:grid; grid-template-columns:170px minmax(0,1fr) 220px; min-width:0; border-top:1px solid var(--cc-border); } .qualification-row:first-child { border-top:0; } .qualification-row > * { display:flex; min-width:0; align-items:center; } .qualification-header { min-height:44px; background:#f7f8fc; color:var(--cc-muted); font-size:var(--admin-font-caption, 12px); font-weight:600; }
+.qualification-label { gap:5px; font-weight:600; } .qualification-label svg { margin-left:auto; color:var(--el-color-success); }
+.qualification-optional { padding:2px 5px; border-radius:var(--admin-radius, 4px); background:var(--el-fill-color-light); color:var(--cc-muted); font-size:var(--admin-font-caption, 10px); font-weight:500; line-height:1.4; }
+.qualification-file { gap:var(--admin-space-5, 12px); } .qualification-file-control { display:flex; min-width:0; flex:1; flex-wrap:wrap; align-items:center; gap:var(--admin-space-3, 8px); } .file-picker { position:relative; display:inline-flex; flex:0 0 auto; align-items:center; gap:7px; overflow:hidden; padding:0 var(--admin-space-5, 12px); border:1px solid var(--cc-border); border-radius:6px; background:var(--admin-surface, #fff); color:var(--cc-text); cursor:pointer; } .file-picker:focus-within { outline:2px solid color-mix(in srgb,var(--cc-primary) 35%,transparent); outline-offset:2px; } .file-picker.is-disabled { cursor:not-allowed; opacity:.6; } .file-picker input { position:absolute; inset:0; width:100%; height:100%; opacity:0; cursor:inherit; } .qualification-file-name { min-width:0; overflow:hidden; color:var(--cc-muted); font-size:var(--admin-font-caption, 12px); text-overflow:ellipsis; } .qualification-validity :deep(.el-date-editor) { width:100%; min-width:0; } .qualification-error { width:100%; color:var(--el-color-danger); line-height:1.4; }
+.qualification-preview-trigger { position:relative; display:grid; width:68px; height:68px; flex:0 0 68px; overflow:hidden; place-items:center; padding:0; border:1px solid var(--cc-border); border-radius:6px; background:var(--admin-label-bg, #f8fafc); color:var(--cc-muted); cursor:pointer; }
+.qualification-preview-trigger:hover { border-color:var(--cc-primary); color:var(--cc-primary); }
+.qualification-preview-trigger:focus-visible { outline:2px solid color-mix(in srgb,var(--cc-primary) 42%,transparent); outline-offset:2px; }
+.qualification-preview-trigger:disabled { cursor:wait; opacity:.72; }
+.qualification-preview-trigger img { width:100%; height:100%; object-fit:contain; background:var(--admin-surface, #fff); }
+.qualification-preview-placeholder { display:grid; place-items:center; gap:2px; }
+.qualification-preview-placeholder small { font-size:var(--admin-font-caption, 10px); font-weight:700; }
+.qualification-preview-action { position:absolute; inset:auto 0 0; display:flex; min-height:22px; align-items:center; justify-content:center; gap:3px; background:rgba(23,32,51,.78); color:var(--admin-surface, #fff); }
+.qualification-preview { display:grid; max-height:min(70vh,760px); min-height:240px; place-items:center; overflow:auto; border:1px solid var(--cc-border); border-radius:6px; background:var(--admin-label-bg, #f8fafc); }
+.qualification-preview img { display:block; max-width:100%; height:auto; }
+.qualification-preview iframe { width:100%; min-height:min(68vh,720px); border:0; background:var(--admin-surface, #fff); }
+.qualification-load-error { display:flex; align-items:center; justify-content:space-between; gap:var(--admin-space-4, 10px); margin-top:var(--admin-space-5, 12px); padding:var(--admin-space-4, 10px) var(--admin-space-5, 12px); border:1px solid #fecdca; border-radius:6px; background:#fffafa; color:#b42318; font-size:var(--admin-font-caption, 12px); }
+.customer-editor-footer { display:flex; align-items:center; justify-content:space-between; gap:var(--admin-space-6, 16px); } .customer-editor-footer > span { color:var(--cc-muted); font-size:var(--admin-font-caption, 12px); text-align:left; } .customer-editor-footer > div { display:flex; flex:0 0 auto; gap:var(--admin-space-3, 8px); } .customer-editor-footer :deep(.el-button + .el-button) { margin-left:0; }
+.decision-summary { display:flex; min-width:0; align-items:center; justify-content:space-between; gap:var(--admin-space-5, 12px); background:var(--admin-label-bg, #f8fafc); } .decision-summary > * { min-width:0; overflow-wrap:anywhere; } .decision-summary strong { color:var(--cc-text); font-size:var(--admin-font-body, 13px); } .decision-summary span { color:var(--cc-muted); font-size:var(--admin-font-caption, 11px); }
+.review-dialog-content { display:grid; }
+.review-dialog-header { display:flex; align-items:center; justify-content:space-between; gap:var(--admin-space-6, 16px); border:1px solid #dbe4f0; }
+.review-dialog-title { display:flex; min-width:0; align-items:center; gap:11px; }
+.review-dialog-title > div { display:grid; min-width:0; gap:3px; }
+.review-dialog-title strong { overflow:hidden; color:#18243a; font-size:var(--admin-font-title, 16px); text-overflow:ellipsis; }
+.review-dialog-title span:not(.review-dialog-icon) { overflow:hidden; color:#718096; font-size:var(--admin-font-caption, 12px); text-overflow:ellipsis; white-space:nowrap; }
+.review-dialog-icon { width:36px; height:var(--admin-row-height, 36px); flex:0 0 36px; place-items:center; border-radius:9px; background:#e9efff; color:#526fe8; }
+.review-dialog-grid { display:grid; grid-template-columns:minmax(270px,.85fr) minmax(390px,1.15fr); }
+.review-dialog-section { min-width:0; border:1px solid #e5eaf1; background:var(--admin-surface, #fff); }
+.review-decision-card { min-width:0; border:1px solid #e5eaf1; background:var(--admin-surface, #fff); }
+.review-section-heading { display:flex; align-items:flex-start; justify-content:space-between; gap:var(--admin-space-5, 12px); }
+.review-section-heading > div { min-width:0; }
+.review-section-heading h3 { margin:0; color:#1a2438; font-size:var(--admin-font-section, 14px); font-weight:700; }
+.review-section-heading span { display:block; margin-top:var(--admin-space-1, 4px); color:#8a94a6; line-height:1.4; }
+.review-section-heading > svg { flex:0 0 auto; color:#657bea; }
+.review-info-grid { margin:0; }
+.review-document-table { overflow:hidden; border:1px solid #e4e9f1; }
+.review-document-header { display:grid; grid-template-columns:118px minmax(0,1fr) 138px; }
+.review-document-row { display:grid; grid-template-columns:118px minmax(0,1fr) 138px; }
+.review-document-header { background:#f5f7fb; color:#657188; font-weight:700; }
+.review-document-header > span { min-width:0; padding:9px var(--admin-space-4, 10px); overflow-wrap:anywhere; border-right:1px solid #e4e9f1; }
+.review-document-row > span { min-width:0; padding:9px var(--admin-space-4, 10px); overflow-wrap:anywhere; border-right:1px solid #e4e9f1; }
+.review-document-header > span:last-child { border-right:0; }
+.review-document-row > span:last-child { border-right:0; }
+.review-document-row { min-height:46px; border-top:1px solid #edf0f4; color:#334155; font-size:var(--admin-font-caption, 12px); }
+.review-document-row > span { display:flex; align-items:center; }
+.review-document-type { font-weight:650; }
+.review-document-name { min-width:0; gap:var(--admin-space-2, 6px); overflow:hidden; color:#4c5b72; text-overflow:ellipsis; }
+.review-document-name svg { flex:0 0 auto; color:#8798cf; }
+.review-document-actions { justify-content:flex-end; gap:var(--admin-space-2, 6px); }
+.review-document-actions :deep(.el-button + .el-button) { margin-left:0; }
+.review-document-state { padding:14px; color:var(--cc-muted); font-size:var(--admin-font-caption, 12px); }
+.review-document-error { padding:14px; color:var(--cc-muted); font-size:var(--admin-font-caption, 12px); }
+.review-document-empty { padding:14px; color:var(--cc-muted); font-size:var(--admin-font-caption, 12px); }
+.review-document-error { display:flex; align-items:center; justify-content:space-between; gap:var(--admin-space-5, 12px); margin-bottom:var(--admin-space-3, 8px); border:1px solid #fecdca; border-radius:6px; background:#fffafa; color:#b42318; }
+.review-document-empty { display:flex; align-items:center; justify-content:center; gap:7px; text-align:center; }.review-document-empty svg { color:#a5afc1; }
+.review-decision-card :deep(.el-form-item) { margin-bottom:0; }.review-decision-card :deep(.el-form-item__label) { color:#4b5870; font-size:var(--admin-font-caption, 12px); font-weight:650; }.decision-summary > div > span { display:block; margin-top:var(--admin-space-1, 4px); }.decision-type { margin:0 0 14px; }.password-input-row { display:grid; grid-template-columns:minmax(0,1fr) auto; width:100%; gap:var(--admin-space-3, 8px); }.dialog-hint { margin:var(--admin-space-5, 12px) 0 0; color:var(--cc-muted); font-size:var(--admin-font-caption, 12px); line-height:1.6; }.archive-confirm { display:grid; gap:var(--admin-space-3, 8px); margin:var(--admin-space-6, 16px) 0; }.archive-confirm strong { color:var(--cc-text); }.archive-confirm span { color:var(--cc-muted); font-size:var(--admin-font-caption, 12px); }
+.approval-result-warning { display:flex; align-items:flex-start; gap:var(--admin-space-4, 10px); padding:var(--admin-space-5, 12px) 14px; border:1px solid #fecdca; border-radius:8px; background:#fffafa; color:#b42318; } .approval-result-warning strong { display:block; } .approval-result-warning span { display:block; } .approval-result-warning strong { font-size:var(--admin-font-section, 14px); } .approval-result-warning span { margin-top:var(--admin-space-1, 4px); font-size:var(--admin-font-caption, 12px); line-height:1.5; } .approval-credentials { margin:18px 0 0; border:1px solid var(--cc-border); } .approval-credentials > div { display:grid; grid-template-columns:90px minmax(0,1fr); gap:var(--admin-space-5, 12px); } .approval-credentials > div + div { border-top:1px solid var(--cc-border); } .approval-credentials dt { color:var(--cc-muted); font-size:var(--admin-font-caption, 12px); } .approval-credentials dd { display:flex; min-width:0; align-items:center; gap:var(--admin-space-4, 10px); margin:0; } .approval-credentials code { min-width:0; flex:1; overflow-wrap:anywhere; color:var(--cc-text); font-size:var(--admin-font-section, 14px); font-weight:700; }
+@media (max-width:720px) { .customer-editor-footer,.review-sync-error { align-items:stretch; flex-direction:column; } .customers-table-actions { display:grid; grid-template-columns:1fr 1fr; width:100%; } .customers-table-actions :deep(.el-button) { min-height:40px; margin:0; } .qualification-table { overflow-x:auto; } .qualification-row { min-width:640px; } .customer-editor-footer > div { display:grid; grid-template-columns:repeat(auto-fit,minmax(110px,1fr)); width:100%; } .customer-editor-footer :deep(.el-button) { min-height:40px; margin:0; } .decision-summary { align-items:flex-start; flex-direction:column; }.review-dialog-grid { grid-template-columns:1fr; gap:12px; }.review-info-grid { grid-template-columns:1fr 1fr; }.review-document-header,.review-document-row { grid-template-columns:104px minmax(0,1fr) 124px; }.review-dialog-header { align-items:flex-start; }.password-input-row { grid-template-columns:1fr; }.table-actions :deep(.el-button) { min-height:40px; } }
+@media (max-width:480px) { :global(.review-decision-dialog .el-dialog__header),:global(.review-decision-dialog .el-dialog__body) { padding-left:16px; padding-right:16px; }.review-info-grid { grid-template-columns:1fr; }.review-document-header { display:none; }.review-document-row { grid-template-columns:1fr; gap:6px; padding:10px; }.review-document-row > span { padding:0; border-right:0; }.review-document-actions { justify-content:flex-start; }.review-dialog-title strong { max-width:190px; } }
+@media (max-width:360px) { .customers-table-actions,.capital-input { grid-template-columns:1fr; } }
+</style>
diff --git a/src/modules/customers/pages/OverseasStorageFeesView.vue b/src/modules/customers/pages/OverseasStorageFeesView.vue
new file mode 100644
index 00000000..20322786
--- /dev/null
+++ b/src/modules/customers/pages/OverseasStorageFeesView.vue
@@ -0,0 +1,115 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import '@/modules/customers/customerDensity.css'
+import { computed, onMounted, reactive, ref } from 'vue'
+import { ElMessage } from 'element-plus'
+
+import AdminPage from '@/shared/components/AdminPage.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import QueryToolbar from '@/shared/components/QueryToolbar.vue'
+import DataTable from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import { getApiErrorDetails } from '@/shared/api/http'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { listOverseasStorageFees, updateCustomerOverseasStorageFees, type OverseasStorageFeeConfig, type OverseasStorageFeeTier } from '../overseasStorageFee'
+import { addFeeTier, removeFeeTier, validateFeeTiers } from '../overseasStorageFeeTiers'
+
+const access = useAccessPreviewStore()
+const loading = ref(false)
+const error = ref<ReturnType<typeof getApiErrorDetails> | null>(null)
+const rows = ref<OverseasStorageFeeConfig[]>([])
+const page = ref(1)
+const size = ref(20)
+const total = ref(0)
+const keyword = ref('')
+const dialogOpen = ref(false)
+const saving = ref(false)
+const editing = ref<OverseasStorageFeeConfig | null>(null)
+const form = reactive({ currency: 'USD', version: 0, tiers: [] as OverseasStorageFeeTier[] })
+
+const storageTiers = computed(() => form.tiers.filter((tier) => tier.feeType === 'STORAGE'))
+const returnTiers = computed(() => form.tiers.filter((tier) => tier.feeType === 'RETURN_STORAGE'))
+const filters = ref({ keyword: '' })
+const queryFields = [{ key: 'keyword', label: '客户', type: 'input' as const, placeholder: '搜索客户名称' }]
+const columns = [
+  { key: 'actions', slotName: 'actions', label: '操作', width: 100, fixed: 'left' as const },
+  { key: 'customerName', prop: 'customerName', label: '客户', minWidth: 180 },
+  { key: 'currency', prop: 'currency', label: '币种', width: 90 },
+  { key: 'storage', slotName: 'storage', label: '仓租（CBM/天）', minWidth: 300 },
+  { key: 'returnStorage', slotName: 'returnStorage', label: '退货仓储费（托/天）', minWidth: 300 },
+]
+
+function clone(tiers: OverseasStorageFeeTier[]) { return tiers.map((tier) => ({ ...tier })) }
+function label(tier: OverseasStorageFeeTier) { return tier.endDay === null ? `${tier.startDay}天以上` : `${tier.startDay}-${tier.endDay}天` }
+function tiersFor(row: OverseasStorageFeeConfig, feeType: OverseasStorageFeeTier['feeType']) { return row.tiers.filter((tier) => tier.feeType === feeType).sort((a, b) => a.sortNo - b.sortNo) }
+async function load() {
+  loading.value = true; error.value = null
+  try { const result = await listOverseasStorageFees(page.value, size.value, keyword.value.trim() || undefined); rows.value = result.records; total.value = Number(result.total) }
+  catch (cause) { error.value = getApiErrorDetails(cause, '海外仓阶梯费用加载失败，请稍后重试') }
+  finally { loading.value = false }
+}
+function search() { keyword.value = filters.value.keyword; page.value = 1; void load() }
+function openEdit(row: OverseasStorageFeeConfig) { editing.value = row; form.currency = row.currency || 'USD'; form.version = row.version; form.tiers = clone(row.tiers); dialogOpen.value = true }
+function addTier(feeType: OverseasStorageFeeTier['feeType']) { const message = addFeeTier(form.tiers, feeType); if (message) ElMessage.error(message) }
+function removeTier(tier: OverseasStorageFeeTier) { const message = removeFeeTier(form.tiers, tier); if (message) ElMessage.error(message) }
+async function save() {
+  if (!editing.value) return
+  const validationMessage = validateFeeTiers(form.tiers)
+  if (validationMessage) { ElMessage.error(validationMessage); return }
+  saving.value = true
+  try { await updateCustomerOverseasStorageFees(editing.value.customerId, { customerId: editing.value.customerId, customerName: editing.value.customerName, currency: form.currency, version: form.version, tiers: form.tiers.map(({ feeType, billingUnit, startDay, endDay, unitPrice }) => ({ feeType, billingUnit, startDay, endDay, unitPrice })) }); dialogOpen.value = false; ElMessage.success('海外仓费用已保存'); await load() }
+  catch (cause) { ElMessage.error(getApiErrorDetails(cause, '保存失败，请刷新后重试').message) }
+  finally { saving.value = false }
+}
+onMounted(() => { void load() })
+</script>
+
+<template>
+  <AdminPage>
+  <div class="business-page overseas-fees-page admin-density customer-density">
+    <ListPageLayout ariaLabel="海外仓阶梯费用列表">
+      <template #toolbar><QueryToolbar v-model="filters" class="surface-panel" :fields="queryFields" ariaLabel="海外仓阶梯费用筛选" preference-key="overseas-storage-fees-query" @search="search" /></template>
+      <template v-if="error" #state><section class="surface-panel error-state" role="alert"><div><strong>{{ error.message }}</strong><ApiErrorMeta :details="error" /></div><el-button type="primary" @click="load">重新加载</el-button></section></template>
+    <section v-if="!error" class="surface-panel table-panel">
+      <DataTable v-model:page="page" v-model:page-size="size" :data="rows" :columns="columns" :loading="loading" :total="total" preference-key="overseas-storage-fees-table" row-key="id" border stripe empty-text="暂无海外仓阶梯费用配置" @update:page="load" @update:page-size="load">
+        <template #actions="{ row }"><el-button v-if="access.can('platform:overseas-storage-fee:edit')" class="density-action" size="small" plain @click="openEdit(row as OverseasStorageFeeConfig)">编辑</el-button></template>
+        <template #storage="{ row }">
+          <dl class="tier-list" aria-label="仓租阶梯单价，币种见本行币种列">
+            <div v-for="tier in tiersFor(row as OverseasStorageFeeConfig, 'STORAGE')" :key="tier.id" class="tier-item"><dt>{{ label(tier) }}：</dt><dd>{{ tier.unitPrice }}</dd></div>
+          </dl>
+        </template>
+        <template #returnStorage="{ row }">
+          <dl class="tier-list" aria-label="退货仓储费阶梯单价，币种见本行币种列">
+            <div v-for="tier in tiersFor(row as OverseasStorageFeeConfig, 'RETURN_STORAGE')" :key="tier.id" class="tier-item"><dt>{{ label(tier) }}：</dt><dd>{{ tier.unitPrice }}</dd></div>
+          </dl>
+        </template>
+        <template #pagination-left="{ total: tableTotal }"><span>共 {{ tableTotal }} 个客户</span></template>
+      </DataTable>
+    </section>
+    </ListPageLayout>
+    <AppDialog class="admin-density-dialog customer-density-dialog" v-model="dialogOpen" title="编辑海外仓阶梯费用" width="min(1120px, calc(100vw - 28px))" :confirm-loading="saving" @confirm="save">
+      <el-form label-position="top"><el-form-item label="币种"><el-select v-model="form.currency" style="width:180px"><el-option label="USD" value="USD" /><el-option label="CNY" value="CNY" /><el-option label="EUR" value="EUR" /></el-select></el-form-item><div class="groups"><div v-for="(group, index) in [storageTiers, returnTiers]" :key="index"><div class="group-heading"><h3>{{ index === 0 ? '仓租（CBM/天）' : '退货仓储费（托/天）' }} · {{ group.length }}档</h3><el-button class="density-action" data-tone="primary" type="primary" plain size="small" :disabled="form.tiers.length >= 100" @click="addTier(index === 0 ? 'STORAGE' : 'RETURN_STORAGE')">新增阶梯</el-button></div><el-table :data="group" size="small" border stripe><el-table-column label="操作" width="88" fixed="left"><template #default="{ row }"><el-button class="density-action" data-tone="danger" size="small" plain type="danger" :disabled="group.length <= 1" @click="removeTier(row as OverseasStorageFeeTier)">删除</el-button></template></el-table-column><el-table-column label="开始天数"><template #default="{ row }"><el-input-number v-model="row.startDay" :min="1" :max="36500" :controls="false" placeholder="请输入开始天数" /></template></el-table-column><el-table-column label="结束天数"><template #default="{ row }"><el-input-number v-if="row.endDay !== null" v-model="row.endDay" :min="1" :max="36500" :controls="false" placeholder="请输入结束天数" /><span v-else>以上</span></template></el-table-column><el-table-column label="价格"><template #default="{ row }"><el-input-number v-model="row.unitPrice" :min="0" :precision="6" :controls="false" placeholder="请输入单价" /></template></el-table-column></el-table></div></div></el-form>
+    </AppDialog>
+  </div>
+  </AdminPage>
+</template>
+
+<style scoped>
+.error-state { display:flex; justify-content:space-between; padding:20px; color:#b42318; }
+.tier-list { display:flex; flex-wrap:wrap; gap:var(--admin-space-1, 4px) var(--admin-space-6, 16px); margin:0; padding:2px 0; white-space:normal; }
+.tier-list:empty::after { content:'—'; color:var(--cc-muted); }
+.tier-item { display:flex; align-items:baseline; min-width:0; max-width:100%; line-height:24px; }
+.tier-item dt { flex:0 0 auto; color:var(--cc-muted); font-size:var(--admin-font-caption, 12px); }
+.tier-item dd { min-width:0; margin:0; color:var(--cc-text); font-size:var(--admin-font-body, 13px); font-weight:600; font-variant-numeric:tabular-nums; overflow-wrap:anywhere; }
+.groups { display:grid; grid-template-columns:repeat(2,minmax(0,1fr)); }
+.groups > div { min-width:0; }
+.groups :deep(.el-table) { width:100%; }
+.groups :deep(.el-input-number) { width:100%; min-width:0; }
+.groups h3 { margin:0 0 var(--admin-space-4, 10px); }
+.group-heading { display:flex; align-items:center; justify-content:space-between; gap:var(--admin-space-5, 12px); margin-bottom:var(--admin-space-4, 10px); }
+.group-heading h3 { min-width:0; margin:0; }
+.group-heading :deep(.el-button) { flex:0 0 auto; }
+@media (max-width:900px) { .groups { grid-template-columns:1fr; } }
+@media (max-width:720px) { .error-state { align-items:stretch; flex-direction:column; gap:12px; } .error-state :deep(.el-button) { width:100%; min-height:44px; } .tier-list { grid-template-columns:1fr; } .groups > div { overflow-x:auto; } .groups :deep(.el-table) { min-width:560px; } }
+</style>
diff --git a/src/modules/customers/routes.ts b/src/modules/customers/routes.ts
new file mode 100644
index 00000000..d80ab3f6
--- /dev/null
+++ b/src/modules/customers/routes.ts
@@ -0,0 +1,28 @@
+import type { RouteRecordRaw } from 'vue-router'
+
+export const customerRoutes = [
+  {
+    path: 'customers',
+    name: 'customers',
+    component: () => import('@/modules/customers/pages/CustomersView.vue'),
+    meta: { title: '客户管理', description: '维护客户企业资料、合作状态和注册审核', permission: 'platform:customer:list', permissionAnyOf: ['platform:customer:review'] },
+  },
+  {
+    path: 'customers/overseas-storage-fees',
+    name: 'overseas-storage-fees',
+    component: () => import('@/modules/customers/pages/OverseasStorageFeesView.vue'),
+    meta: { title: '海外仓阶梯费用', description: '维护客户仓租和退货仓储费阶梯', permission: 'platform:overseas-storage-fee:list' },
+  },
+  {
+    path: 'customers/:tenantId',
+    name: 'customer-detail',
+    component: () => import('@/modules/customers/pages/CustomerDetailView.vue'),
+    meta: { title: '客户详情', description: '查看企业资料、关联用户和业务记录', permission: 'platform:customer:list', showPageHeading: false },
+  },
+  {
+    path: 'customers/reviews',
+    name: 'enterprise-reviews',
+    redirect: '/customers',
+    meta: { title: '客户管理', description: '企业审核已合并到客户列表', permission: 'platform:customer:list', permissionAnyOf: ['platform:customer:review'] },
+  },
+] satisfies RouteRecordRaw[]
diff --git a/src/modules/customs/api/platformCustoms.test.ts b/src/modules/customs/api/platformCustoms.test.ts
new file mode 100644
index 00000000..877b7c52
--- /dev/null
+++ b/src/modules/customs/api/platformCustoms.test.ts
@@ -0,0 +1,5 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import { createCustomsCase, listCustomsCases, submitCustomsCase } from './platformCustoms'
+vi.mock('@/shared/api/http', async () => { const actual = await vi.importActual<typeof import('@/shared/api/http')>('@/shared/api/http'); return { ...actual, http: { get: vi.fn(), post: vi.fn() } } })
+describe('platformCustoms', () => { beforeEach(() => vi.clearAllMocks()); it('normalizes case ids', async () => { vi.mocked(http.get).mockResolvedValue({ code: '200', data: { records: [{ id: 1, customsNo: 'C1', orderId: 2, inboundId: 3, checklistVersionId: 4, checklistCode: 'US', checklistVersionNo: 'V1', status: 'DRAFT', version: '1' }], page: 1, size: 20, total: 1, pages: 1 } }); const page = await listCustomsCases({ page: 1, size: 20 }); expect(page.records[0]).toMatchObject({ id: '1', orderId: '2', inboundId: '3', checklistVersionId: '4', version: 1 }) }); it('writes with idempotency, supplier identity and version', async () => { const detail = { customsCase: { id: 1, customsNo: 'C1', orderId: 2, inboundId: 3, checklistVersionId: 4, checklistCode: 'US', checklistVersionNo: 'V1', status: 'DRAFT', version: 0 }, documents: [], supplements: [], submissionBatches: [], receipts: [], history: [] }; vi.mocked(http.post).mockResolvedValueOnce({ code: '200', data: detail }).mockResolvedValueOnce({ code: '200', data: {} }); await createCustomsCase({ customerId: '8', orderId: '2', inboundId: '3', checklistVersionId: '4', expectedVersion: 0 }); await submitCustomsCase('1', { customsAgentId: '81', customsAgentName: '代理', expectedVersion: 2 }); expect(vi.mocked(http.post).mock.calls[0]?.[2]).toMatchObject({ headers: { 'Idempotency-Key': expect.any(String) } }); expect(vi.mocked(http.post).mock.calls[1]?.[1]).toMatchObject({ customsAgentId: '81', customsAgentName: '代理', expectedVersion: 2 }) }) })
diff --git a/src/modules/customs/api/platformCustoms.ts b/src/modules/customs/api/platformCustoms.ts
new file mode 100644
index 00000000..636ede16
--- /dev/null
+++ b/src/modules/customs/api/platformCustoms.ts
@@ -0,0 +1,11 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import type { CustomsCaseCreateRequest, CustomsCaseDetail, CustomsCasePage, CustomsCaseQuery, CustomsCaseResource, CustomsSubmitBatchRequest } from '../types'
+const basePath = '/platform/v1/customs'
+const keys = ['id', 'tenantId', 'orderId', 'inboundId', 'containerBookingId', 'checklistVersionId'] as const
+function item(raw: CustomsCaseResource) { const value = { ...raw } as CustomsCaseResource & Record<string, unknown>; for (const key of keys) if (value[key] != null) value[key] = String(value[key]); value.version = Number(value.version ?? 0); return value }
+function detail(raw: CustomsCaseDetail): CustomsCaseDetail { return { ...raw, customsCase: item(raw.customsCase), documents: (raw.documents || []).map((x) => ({ ...x, id: String(x.id) })), submissionBatches: (raw.submissionBatches || []).map((x) => ({ ...x, id: String(x.id) })), receipts: (raw.receipts || []).map((x) => ({ ...x, id: String(x.id) })), history: (raw.history || []).map((x) => ({ ...x, id: String(x.id) })) } }
+function idem() { return `customs-${Date.now()}-${Math.random().toString(36).slice(2)}` }
+export async function listCustomsCases(query: CustomsCaseQuery) { const response = await http.get<ApiEnvelope<CustomsCasePage>, ApiEnvelope<CustomsCasePage>>(`${basePath}/cases`, { params: query }); const data = unwrapApiResponse(response); return { ...data, records: (data.records || []).map(item), page: Number(data.page), size: Number(data.size), total: Number(data.total), pages: Number(data.pages) } }
+export async function getCustomsCase(id: string) { const response = await http.get<ApiEnvelope<CustomsCaseDetail>, ApiEnvelope<CustomsCaseDetail>>(`${basePath}/cases/${encodeURIComponent(id)}`); return detail(unwrapApiResponse(response)) }
+export async function createCustomsCase(request: CustomsCaseCreateRequest) { const response = await http.post<ApiEnvelope<CustomsCaseDetail>, ApiEnvelope<CustomsCaseDetail>>(`${basePath}/cases`, request, { headers: { 'Idempotency-Key': idem() } }); return detail(unwrapApiResponse(response)) }
+export async function submitCustomsCase(id: string, request: CustomsSubmitBatchRequest) { const response = await http.post<ApiEnvelope<unknown>, ApiEnvelope<unknown>>(`${basePath}/cases/${encodeURIComponent(id)}/submission-batches`, request, { headers: { 'Idempotency-Key': idem() } }); return unwrapApiResponse(response) }
diff --git a/src/modules/customs/index.ts b/src/modules/customs/index.ts
new file mode 100644
index 00000000..e5f14b6e
--- /dev/null
+++ b/src/modules/customs/index.ts
@@ -0,0 +1,2 @@
+export { customsRoutes } from './routes'
+export * from './types'
diff --git a/src/modules/customs/pages/CustomsCasesView.test.ts b/src/modules/customs/pages/CustomsCasesView.test.ts
new file mode 100644
index 00000000..6594b8c7
--- /dev/null
+++ b/src/modules/customs/pages/CustomsCasesView.test.ts
@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+const source = readFileSync(resolve(process.cwd(), 'src/modules/customs/pages/CustomsCasesView.vue'), 'utf8')
+describe('CustomsCasesView', () => {
+  it('uses a wide customer filter and compact status filter', () => {
+    expect(source).toContain("key: 'customerId', type: 'select', label: '客户', placeholder: '全部客户', width: 220")
+    expect(source).toContain("key: 'status', type: 'select', label: '状态', width: 160")
+  })
+  it('uses shared list and dialog components', () => { expect(source).toContain('QueryToolbar'); expect(source).toContain('DataTable'); expect(source).toContain('AppDialog'); expect(source).toContain("fixed: 'left'") })
+  it('supports detail, history and agent submission', () => { expect(source).toContain('getCustomsCase'); expect(source).toContain('submitCustomsCase'); expect(source).toContain('detail.history') })
+  it('selects an active customs supplier and submits its stable identity and name snapshot', () => {
+    expect(source).toContain("listSuppliers({ page: 1, size: 200, category: 'CUSTOMS', status: 'ACTIVE' })")
+    expect(source).toContain("supplier.category === 'CUSTOMS' && supplier.status === 'ACTIVE'")
+    expect(source).toContain(':model-value="submitForm.customsAgentId" filterable clearable')
+    expect(source).toContain("submitForm.customsAgentId = supplier?.id || ''")
+    expect(source).toContain("submitForm.customsAgentName = supplier?.name || ''")
+    expect(source).not.toContain('v-model="submitForm.customsAgentName"')
+    expect(source).toContain("batch.customsAgentName || '服务端未返回名称快照'")
+  })
+  it('localizes backend statuses and timeline actions throughout the page', () => {
+    expect(source).toContain('customsCaseStatusOptions')
+    expect(source).toContain(':status="customsStatusLabel(row.status)"')
+    expect(source).toContain(':status="customsStatusLabel(detail.customsCase.status)"')
+    expect(source).toContain('customsHistoryActionLabel(entry.action)')
+    expect(source).toContain('customsStatusLabel(entry.fromStatus)')
+    expect(source).toContain("detail.value?.customsCase.status === 'READY_TO_SUBMIT'")
+    expect(source).not.toContain("['DRAFT', 'COLLECTING', 'READY', 'SUBMITTED', 'RELEASED', 'REJECTED']")
+  })
+  it('does not expose internal id inputs while resource query APIs are unavailable', () => {
+    expect(source).not.toContain('createCustomsCase')
+    expect(source).not.toContain('新增报关')
+    expect(source).not.toContain('资料清单版本 ID')
+    expect(source).not.toContain("key: 'orderId', type: 'input'")
+    expect(source).not.toContain("key: 'inboundId', type: 'input'")
+  })
+  it('does not render technical order or inbound ids in the list', () => {
+    expect(source).toContain("label: '订单关联'")
+    expect(source).toContain("label: '入库单关联'")
+    expect(source).toContain("return value ? '已关联' : '未关联'")
+    expect(source).not.toContain("label: '订单标识'")
+    expect(source).not.toContain("label: '入库单标识'")
+  })
+  it('keeps the detail dialog responsive with internal scrolling', () => {
+    expect(source).toContain('width:min(900px,calc(100vw - 28px))!important')
+    expect(source).toContain('max-height:90vh')
+    expect(source).toContain('overflow-y:auto')
+  })
+  it('uses a bordered view action instead of a text link', () => {
+    expect(source).toContain('size="small" type="primary" plain')
+    expect(source).not.toContain("customs:view')\" link")
+    expect(source).toContain(':total="total" stripe row-key="id"')
+  })
+  it('uses an active name-only customer selector backed by customerId', () => {
+    expect(source).toContain("listPlatformTenants({ page: 1, size: 200, status: 'ACTIVE' })")
+    expect(source).toContain("customer.status === 'ACTIVE'")
+    expect(source).toContain("label: customer.tenantName")
+    expect(source).toContain("customerId: String(filters.value.customerId || '') || undefined")
+    expect(source).not.toContain('customer.tenantCode')
+  })
+})
diff --git a/src/modules/customs/pages/CustomsCasesView.vue b/src/modules/customs/pages/CustomsCasesView.vue
new file mode 100644
index 00000000..a10cff36
--- /dev/null
+++ b/src/modules/customs/pages/CustomsCasesView.vue
@@ -0,0 +1,42 @@
+<script setup lang="ts">
+import { computed, onMounted, reactive, ref, watch } from 'vue'
+import { ElMessage } from 'element-plus'
+import { Eye, Send } from '@lucide/vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import DataTable from '@/shared/components/DataTable.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import { customsCaseStatusOptions, customsHistoryActionLabel, customsStatusLabel } from '../status'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { listPlatformTenants, type PlatformTenantResource } from '@/modules/iam'
+import { listSuppliers, type Supplier } from '@/modules/suppliers'
+import { getCustomsCase, listCustomsCases, submitCustomsCase } from '../api/platformCustoms'
+import type { CustomsCaseDetail, CustomsCaseResource } from '../types'
+
+const access = useAccessPreviewStore(); const rows = ref<CustomsCaseResource[]>([]); const loading = ref(false); const error = ref<ApiErrorDetails | null>(null); const page = ref(1); const pageSize = ref(20); const total = ref(0)
+const customers = ref<PlatformTenantResource[]>([]); const customersLoading = ref(false)
+const customsAgents = ref<Supplier[]>([]); const customsAgentsLoading = ref(false); const customsAgentsError = ref('')
+const filters = ref<QueryModel>({ customerId: '', status: '' }); const fields = computed<QueryField[]>(() => [
+  { key: 'customerId', type: 'select', label: '客户', placeholder: '全部客户', width: 220, options: customers.value.filter((customer) => customer.status === 'ACTIVE').map((customer) => ({ label: customer.tenantName, value: String(customer.id) })), props: { filterable: true, loading: customersLoading.value } },
+  { key: 'status', type: 'select', label: '状态', width: 160, options: customsCaseStatusOptions.map((option) => ({ ...option })) },
+])
+const columns = [{ key: 'actions', label: '操作', fixed: 'left', width: 175, slotName: 'actions', hideable: false, movable: false }, { prop: 'customsNo', label: '报关编号', minWidth: 145 }, { key: 'orderLink', label: '订单关联', minWidth: 120, formatter: (row: CustomsCaseResource) => associationLabel(row.orderId) }, { key: 'inboundLink', label: '入库单关联', minWidth: 120, formatter: (row: CustomsCaseResource) => associationLabel(row.inboundId) }, { prop: 'checklistCode', label: '资料清单', minWidth: 125 }, { prop: 'checklistVersionNo', label: '版本', width: 90 }, { prop: 'status', label: '状态', width: 110, slotName: 'status' }, { prop: 'updatedAt', label: '更新时间', minWidth: 160 }]
+function associationLabel(value: string | null | undefined) { return value ? '已关联' : '未关联' }
+async function loadCustomers() { customersLoading.value = true; try { const result = await listPlatformTenants({ page: 1, size: 200, status: 'ACTIVE' }); customers.value = result.records.filter((customer) => customer.status === 'ACTIVE') } catch { customers.value = [] } finally { customersLoading.value = false } }
+async function loadCustomsAgents() { customsAgentsLoading.value = true; customsAgentsError.value = ''; try { const result = await listSuppliers({ page: 1, size: 200, category: 'CUSTOMS', status: 'ACTIVE' }); customsAgents.value = result.records.filter((supplier) => supplier.category === 'CUSTOMS' && supplier.status === 'ACTIVE') } catch (cause) { customsAgents.value = []; customsAgentsError.value = getApiErrorDetails(cause, '报关代理加载失败').message } finally { customsAgentsLoading.value = false } }
+async function load() { loading.value = true; error.value = null; try { const result = await listCustomsCases({ page: page.value, size: pageSize.value, customerId: String(filters.value.customerId || '') || undefined, status: String(filters.value.status || '') || undefined }); rows.value = result.records; total.value = result.total } catch (cause) { error.value = getApiErrorDetails(cause) } finally { loading.value = false } }
+function search() { if (page.value === 1) void load(); else page.value = 1 }
+const detailOpen = ref(false); const detail = ref<CustomsCaseDetail | null>(null); const detailLoading = ref(false); const actionError = ref<ApiErrorDetails | null>(null); const submitForm = reactive({ customsAgentId: '', customsAgentName: '', externalReference: '', note: '' }); const canSubmit = computed(() => detail.value?.customsCase.status === 'READY_TO_SUBMIT' && access.can('platform:firstleg:customs:submit'))
+function selectCustomsAgent(supplierId: string) { const supplier = customsAgents.value.find((item) => item.id === supplierId); submitForm.customsAgentId = supplier?.id || ''; submitForm.customsAgentName = supplier?.name || '' }
+async function openDetail(id: string) { detailOpen.value = true; detailLoading.value = true; actionError.value = null; selectCustomsAgent(''); try { detail.value = await getCustomsCase(id) } catch (cause) { actionError.value = getApiErrorDetails(cause) } finally { detailLoading.value = false } }
+async function submit() { if (!detail.value || !submitForm.customsAgentId || !customsAgents.value.some((item) => item.id === submitForm.customsAgentId)) { actionError.value = { message: '请选择有效的合作中报关供应商' }; return } actionError.value = null; try { await submitCustomsCase(detail.value.customsCase.id, { ...submitForm, expectedVersion: detail.value.customsCase.version }); ElMessage.success('已登记线下提交批次'); detail.value = await getCustomsCase(detail.value.customsCase.id) } catch (cause) { actionError.value = getApiErrorDetails(cause); if (actionError.value.code === 'A0409') detail.value = await getCustomsCase(detail.value.customsCase.id) } }
+watch([page, pageSize], () => void load()); onMounted(() => { void load(); void loadCustomers(); void loadCustomsAgents() })
+</script>
+<template><AdminPage as="div"><ListPageLayout aria-label="报关协同列表"><template #toolbar><QueryToolbar v-model="filters" class="surface-panel" ariaLabel="报关协同筛选" :fields="fields" @search="search" /></template><template v-if="error" #state><LoadErrorState title="报关协同加载失败" :message="error.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="error" /></template></LoadErrorState></template><section v-if="!error" class="surface-panel table-panel"><DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :loading="loading" :total="total" stripe row-key="id" preference-key="customs-cases" empty-text="暂无报关协同记录"><template #actions="{ row }"><el-button v-if="access.can('platform:firstleg:customs:view')" size="small" type="primary" plain @click="openDetail(row.id)"><Eye :size="15" />查看</el-button></template><template #status="{ row }"><StatusBadge :status="customsStatusLabel(row.status)" /></template></DataTable></section></ListPageLayout>
+<AppDialog v-model="detailOpen" title="报关协同详情" width="900px" :show-confirm="false"><LoadErrorState v-if="actionError && !detail" title="详情加载失败" :message="actionError.message" :loading="detailLoading" :show-retry="false"><template #details><ApiErrorMeta :details="actionError" /></template></LoadErrorState><template v-if="detail"><el-alert v-if="actionError" type="error" :closable="false"><ApiErrorMeta :details="actionError" /></el-alert><el-descriptions :column="2" border><el-descriptions-item label="报关编号">{{ detail.customsCase.customsNo }}</el-descriptions-item><el-descriptions-item label="状态"><StatusBadge :status="customsStatusLabel(detail.customsCase.status)" /></el-descriptions-item><el-descriptions-item label="资料清单">{{ detail.customsCase.checklistCode }} / {{ detail.customsCase.checklistVersionNo }}</el-descriptions-item><el-descriptions-item label="资料/回执">{{ detail.documents.length }} / {{ detail.receipts.length }}</el-descriptions-item></el-descriptions><el-form v-if="canSubmit" label-position="top" class="submit-form"><el-alert v-if="customsAgentsError" type="warning" :closable="false" :title="customsAgentsError"><el-button link type="warning" :loading="customsAgentsLoading" @click="loadCustomsAgents">重新加载</el-button></el-alert><el-row :gutter="12"><el-col :xs="24" :sm="12"><el-form-item label="报关代理" required><el-select :model-value="submitForm.customsAgentId" filterable clearable placeholder="请选择报关代理" :loading="customsAgentsLoading" no-data-text="暂无可用报关供应商" style="width:100%" @update:model-value="selectCustomsAgent(String($event || ''))"><el-option v-for="supplier in customsAgents" :key="supplier.id" :label="supplier.name" :value="supplier.id" /></el-select></el-form-item></el-col><el-col :xs="24" :sm="12"><el-form-item label="外部参考号"><el-input v-model="submitForm.externalReference" placeholder="请输入代理回传的参考号（可选）" /></el-form-item></el-col><el-col :xs="24"><el-form-item label="提交备注"><el-input v-model="submitForm.note" placeholder="请输入本次提交说明（可选）" /></el-form-item></el-col></el-row><el-button type="primary" :disabled="!submitForm.customsAgentId" @click="submit"><Send :size="16" />登记线下提交</el-button></el-form><h3>提交批次</h3><el-empty v-if="!detail.submissionBatches.length" description="暂无提交批次" :image-size="56" /><el-timeline v-else><el-timeline-item v-for="batch in detail.submissionBatches" :key="batch.id" :timestamp="batch.createdAt">报关代理：{{ batch.customsAgentName || '服务端未返回名称快照' }}</el-timeline-item></el-timeline><h3>状态历史</h3><el-timeline><el-timeline-item v-for="entry in detail.history" :key="entry.id" :timestamp="entry.createdAt">{{ customsHistoryActionLabel(entry.action) }}：{{ customsStatusLabel(entry.fromStatus) }} → {{ customsStatusLabel(entry.toStatus) }}<small>{{ entry.note || '' }}</small></el-timeline-item></el-timeline></template></AppDialog></AdminPage></template>
+<style scoped>.submit-form{margin-top:18px}.submit-form+.el-button{margin-bottom:12px}h3{margin:20px 0 12px}small{display:block;color:var(--cc-muted)}:global(.el-dialog:has(.submit-form,.el-descriptions)){width:min(900px,calc(100vw - 28px))!important;max-height:90vh;overflow:hidden}:global(.el-dialog:has(.submit-form,.el-descriptions) .el-dialog__body){max-height:calc(90vh - 120px);overflow-y:auto}</style>
diff --git a/src/modules/customs/routes.ts b/src/modules/customs/routes.ts
new file mode 100644
index 00000000..f2eb6622
--- /dev/null
+++ b/src/modules/customs/routes.ts
@@ -0,0 +1,2 @@
+import type { RouteRecordRaw } from 'vue-router'
+export const customsRoutes = [{ path: 'customs', name: 'customs-cases', component: () => import('./pages/CustomsCasesView.vue'), meta: { title: '报关协同', description: '维护报关资料、代理提交与放行回执', permission: 'platform:firstleg:customs:list' } }] satisfies RouteRecordRaw[]
diff --git a/src/modules/customs/status.test.ts b/src/modules/customs/status.test.ts
new file mode 100644
index 00000000..d7abfa0f
--- /dev/null
+++ b/src/modules/customs/status.test.ts
@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest'
+import { customsCaseStatusOptions, customsHistoryActionLabel, customsStatusLabel } from './status'
+
+describe('customs status labels', () => {
+  it('matches the backend customs case state machine', () => {
+    expect(customsCaseStatusOptions).toEqual([
+      { value: 'DOCUMENTS_PENDING', label: '待补资料' },
+      { value: 'REVIEWING', label: '审核中' },
+      { value: 'SUPPLEMENT_REQUIRED', label: '需补件' },
+      { value: 'READY_TO_SUBMIT', label: '待提交代理' },
+      { value: 'RECEIPT_PENDING', label: '待回执' },
+      { value: 'RECEIPT_AVAILABLE', label: '已有回执' },
+      { value: 'CLEARANCE_COMPLETED', label: '已放行' },
+      { value: 'CANCELLED', label: '已取消' },
+    ])
+  })
+
+  it('localizes status transitions and does not expose backend codes', () => {
+    expect(customsStatusLabel('READY_TO_SUBMIT')).toBe('待提交代理')
+    expect(customsStatusLabel(null)).toBe('—')
+    expect(customsStatusLabel('FUTURE_STATUS')).toBe('未知状态')
+    expect(customsHistoryActionLabel('REVIEW_DOCUMENT_RETURN')).toBe('退回补件')
+    expect(customsHistoryActionLabel('SUBMIT_AGENT_BATCH')).toBe('提交报关代理')
+    expect(customsHistoryActionLabel('FUTURE_ACTION')).toBe('状态更新')
+  })
+})
diff --git a/src/modules/customs/status.ts b/src/modules/customs/status.ts
new file mode 100644
index 00000000..ac873904
--- /dev/null
+++ b/src/modules/customs/status.ts
@@ -0,0 +1,35 @@
+export const customsCaseStatusOptions = [
+  { value: 'DOCUMENTS_PENDING', label: '待补资料' },
+  { value: 'REVIEWING', label: '审核中' },
+  { value: 'SUPPLEMENT_REQUIRED', label: '需补件' },
+  { value: 'READY_TO_SUBMIT', label: '待提交代理' },
+  { value: 'RECEIPT_PENDING', label: '待回执' },
+  { value: 'RECEIPT_AVAILABLE', label: '已有回执' },
+  { value: 'CLEARANCE_COMPLETED', label: '已放行' },
+  { value: 'CANCELLED', label: '已取消' },
+] as const
+
+const statusLabels = Object.fromEntries(customsCaseStatusOptions.map((option) => [option.value, option.label])) as Record<string, string>
+
+const historyActionLabels: Record<string, string> = {
+  CREATE: '创建报关协同',
+  CREATE_CASE: '创建报关协同',
+  UPLOAD_DOCUMENT: '上传报关资料',
+  REPLACE_DOCUMENT: '替换报关资料',
+  REVIEW_DOCUMENT_APPROVE: '资料审核通过',
+  REVIEW_DOCUMENT_RETURN: '退回补件',
+  SUBMIT_AGENT_BATCH: '提交报关代理',
+  UPLOAD_RECEIPT: '上传报关回执',
+  CANCEL: '取消报关协同',
+  CANCEL_CASE: '取消报关协同',
+}
+
+export function customsStatusLabel(status: string | null | undefined) {
+  if (!status) return '—'
+  return statusLabels[status] || '未知状态'
+}
+
+export function customsHistoryActionLabel(action: string | null | undefined) {
+  if (!action) return '状态更新'
+  return historyActionLabels[action] || '状态更新'
+}
diff --git a/src/modules/customs/types.ts b/src/modules/customs/types.ts
new file mode 100644
index 00000000..4de27a46
--- /dev/null
+++ b/src/modules/customs/types.ts
@@ -0,0 +1,8 @@
+export interface CustomsCaseResource { id: string; customsNo: string; tenantId?: string | null; orderId: string; inboundId: string; containerBookingId?: string | null; checklistVersionId: string; checklistCode: string; checklistVersionNo: string; status: string; remark?: string | null; version: number; updatedAt?: string | null }
+export interface CustomsDocumentResource { id: string; itemCode: string; fileName?: string | null; status?: string | null; version?: number }
+export interface CustomsHistoryResource { id: string; action: string; fromStatus?: string | null; toStatus?: string | null; note?: string | null; operatorName?: string | null; createdAt: string }
+export interface CustomsCaseDetail { customsCase: CustomsCaseResource; documents: CustomsDocumentResource[]; supplements: unknown[]; submissionBatches: Array<{ id: string; customsAgentName?: string; status?: string; createdAt?: string }>; receipts: Array<{ id: string; receiptType?: string; status?: string; createdAt?: string }>; history: CustomsHistoryResource[] }
+export interface CustomsSubmitBatchRequest { customsAgentId: string; customsAgentName: string; externalReference?: string; note?: string; expectedVersion: number }
+export interface CustomsCasePage { records: CustomsCaseResource[]; page: number; size: number; total: number; pages: number }
+export interface CustomsCaseQuery { page: number; size: number; customerId?: string; orderId?: string; inboundId?: string; containerBookingId?: string; status?: string }
+export interface CustomsCaseCreateRequest { customerId: string; orderId: string; inboundId: string; containerBookingId?: string | null; checklistVersionId: string; remark?: string | null; expectedVersion: number }
diff --git a/src/modules/dashboard/api/dashboard.test.ts b/src/modules/dashboard/api/dashboard.test.ts
new file mode 100644
index 00000000..b6b75877
--- /dev/null
+++ b/src/modules/dashboard/api/dashboard.test.ts
@@ -0,0 +1,47 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import { listPlatformTenants } from '@/modules/iam'
+import { listPlatformUnifiedOrders } from '@/modules/unified-orders'
+import {
+  getActiveCustomerCount,
+  getDashboardOperationalMetrics,
+  getTodayNewOrderCount,
+} from './dashboard'
+
+vi.mock('@/modules/iam', () => ({ listPlatformTenants: vi.fn() }))
+vi.mock('@/modules/unified-orders', () => ({ listPlatformUnifiedOrders: vi.fn() }))
+vi.mock('@/shared/api/http', async (importOriginal) => ({
+  ...await importOriginal<typeof import('@/shared/api/http')>(),
+  http: { get: vi.fn() },
+}))
+
+describe('dashboard metrics api', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it('normalizes the operational metrics response', async () => {
+    vi.mocked(http.get).mockResolvedValue({ code: '200', message: 'ok', data: {
+      inTransitContainerCount: '3', inTransitTeu: '4.25', unknownContainerTypeCount: '1',
+      pendingCustomsOrderCount: '7', asOf: '2026-09-11T12:00:00',
+    } })
+
+    await expect(getDashboardOperationalMetrics()).resolves.toEqual({
+      inTransitContainerCount: 3, inTransitTeu: 4.25, unknownContainerTypeCount: 1,
+      pendingCustomsOrderCount: 7, asOf: '2026-09-11T12:00:00',
+    })
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/first-leg/dashboard/operational-metrics')
+  })
+
+  it('uses list totals for today orders and active customers', async () => {
+    vi.mocked(listPlatformUnifiedOrders).mockResolvedValue({ records: [], page: 1, size: 1, total: 12, pages: 12 })
+    vi.mocked(listPlatformTenants).mockResolvedValue({ records: [], page: 1, size: 1, total: 8, pages: 8 })
+
+    await expect(getTodayNewOrderCount()).resolves.toBe(12)
+    await expect(getActiveCustomerCount()).resolves.toBe(8)
+
+    expect(listPlatformUnifiedOrders).toHaveBeenCalledWith(expect.objectContaining({ page: 1, size: 1 }))
+    const orderQuery = vi.mocked(listPlatformUnifiedOrders).mock.calls[0]![0]
+    expect(orderQuery.createdFrom).toMatch(/T00:00:00\.000$/)
+    expect(orderQuery.createdTo).toMatch(/T23:59:59\.999$/)
+    expect(listPlatformTenants).toHaveBeenCalledWith({ page: 1, size: 1, status: 'ACTIVE' })
+  })
+})
diff --git a/src/modules/dashboard/api/dashboard.ts b/src/modules/dashboard/api/dashboard.ts
new file mode 100644
index 00000000..2d168f35
--- /dev/null
+++ b/src/modules/dashboard/api/dashboard.ts
@@ -0,0 +1,55 @@
+import dayjs from 'dayjs'
+import { listPlatformTenants } from '@/modules/iam'
+import { listPlatformUnifiedOrders } from '@/modules/unified-orders'
+import { http, type ApiEnvelope, unwrapApiResponse } from '@/shared/api/http'
+
+export interface DashboardOperationalMetrics {
+  inTransitContainerCount: number
+  inTransitTeu: number
+  unknownContainerTypeCount: number
+  pendingCustomsOrderCount: number
+  asOf: string | null
+}
+
+interface RawDashboardOperationalMetrics {
+  inTransitContainerCount: number | string
+  inTransitTeu: number | string
+  unknownContainerTypeCount: number | string
+  pendingCustomsOrderCount: number | string
+  asOf?: string | null
+}
+
+function numberValue(value: number | string | null | undefined) {
+  const parsed = Number(value)
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : 0
+}
+
+export async function getDashboardOperationalMetrics(): Promise<DashboardOperationalMetrics> {
+  const response = await http.get<ApiEnvelope<RawDashboardOperationalMetrics>, ApiEnvelope<RawDashboardOperationalMetrics>>(
+    '/platform/v1/first-leg/dashboard/operational-metrics',
+  )
+  const data = unwrapApiResponse(response)
+  return {
+    inTransitContainerCount: numberValue(data.inTransitContainerCount),
+    inTransitTeu: numberValue(data.inTransitTeu),
+    unknownContainerTypeCount: numberValue(data.unknownContainerTypeCount),
+    pendingCustomsOrderCount: numberValue(data.pendingCustomsOrderCount),
+    asOf: data.asOf || null,
+  }
+}
+
+export async function getTodayNewOrderCount() {
+  const today = dayjs()
+  const result = await listPlatformUnifiedOrders({
+    createdFrom: today.startOf('day').format('YYYY-MM-DDTHH:mm:ss.SSS'),
+    createdTo: today.endOf('day').format('YYYY-MM-DDTHH:mm:ss.SSS'),
+    page: 1,
+    size: 1,
+  })
+  return result.total
+}
+
+export async function getActiveCustomerCount() {
+  const result = await listPlatformTenants({ page: 1, size: 1, status: 'ACTIVE' })
+  return result.total
+}
diff --git a/src/modules/dashboard/pages/DashboardView.test.ts b/src/modules/dashboard/pages/DashboardView.test.ts
new file mode 100644
index 00000000..ad3e702b
--- /dev/null
+++ b/src/modules/dashboard/pages/DashboardView.test.ts
@@ -0,0 +1,91 @@
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import DashboardView from './DashboardView.vue'
+import { getTodayNewOrderCount } from '../api/dashboard'
+
+vi.mock('../api/dashboard', () => ({
+  getTodayNewOrderCount: vi.fn().mockResolvedValue(12),
+  getActiveCustomerCount: vi.fn().mockResolvedValue(8),
+  getDashboardOperationalMetrics: vi.fn().mockResolvedValue({
+    inTransitContainerCount: 3,
+    inTransitTeu: 4.25,
+    unknownContainerTypeCount: 1,
+    pendingCustomsOrderCount: 7,
+    asOf: '2026-09-11T12:00:00',
+  }),
+}))
+
+enableAutoUnmount(afterEach)
+
+describe('DashboardView', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it('renders only the four live metrics', async () => {
+    const wrapper = mount(DashboardView)
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('核心指标来自实时业务数据')
+    expect(wrapper.text()).toContain('数据更新时间：2026-09-11 12:00')
+    expect(wrapper.findAll('.dashboard-metric')).toHaveLength(4)
+    expect(wrapper.findAll('.dashboard-metric p').map(label => label.text())).toEqual(['今日新运单', '在途柜量', '活跃客户', '待清关票数'])
+    expect(wrapper.find('.density-fields').exists()).toBe(false)
+    expect(wrapper.findAll('.dashboard-metric-mark')).toHaveLength(4)
+    expect(wrapper.text()).toContain('12 票')
+    expect(wrapper.text()).toContain('4.25 TEU')
+    expect(wrapper.text()).toContain('8 家')
+    expect(wrapper.text()).toContain('7 票')
+    expect(wrapper.text()).toContain('1 柜箱型未知')
+    expect(wrapper.text()).not.toContain('近 30 天运单量趋势')
+    expect(wrapper.text()).not.toContain('运单状态分布')
+    expect(wrapper.text()).not.toContain('TOP10 航线货量')
+    expect(wrapper.text()).not.toContain('收入构成')
+    expect(wrapper.text()).not.toContain('待办事项')
+    expect(wrapper.text()).not.toContain('静态演示数据')
+  })
+
+  it('keeps successful metrics when one request fails and refreshes through the visible control', async () => {
+    vi.mocked(getTodayNewOrderCount).mockRejectedValueOnce(new Error('指标加载失败'))
+    const wrapper = mount(DashboardView)
+    await flushPromises()
+    expect(wrapper.text()).toContain('部分核心指标加载失败')
+    expect(wrapper.get('.dashboard-metric strong').text()).toContain('—')
+    expect(wrapper.text()).toContain('4.25 TEU')
+    await wrapper.findAll('button').find(button => button.text().trim() === '刷新数据')!.trigger('click')
+    await flushPromises()
+    expect(getTodayNewOrderCount).toHaveBeenCalledTimes(2)
+    expect(wrapper.text()).toContain('核心指标来自实时业务数据')
+    expect(wrapper.text()).toContain('12 票')
+  })
+
+  it('uses the same visualization root when entering and exiting fullscreen', async () => {
+    const wrapper = mount(DashboardView)
+    await flushPromises()
+    let fullscreen: Element | null = null
+    const previousElement = Object.getOwnPropertyDescriptor(document, 'fullscreenElement')
+    const previousExit = Object.getOwnPropertyDescriptor(document, 'exitFullscreen')
+    const enter = vi.fn(async () => { fullscreen = wrapper.element; document.dispatchEvent(new Event('fullscreenchange')) })
+    const exit = vi.fn(async () => { fullscreen = null; document.dispatchEvent(new Event('fullscreenchange')) })
+    Object.defineProperty(wrapper.element, 'requestFullscreen', { configurable: true, value: enter })
+    Object.defineProperty(document, 'fullscreenElement', { configurable: true, get: () => fullscreen })
+    Object.defineProperty(document, 'exitFullscreen', { configurable: true, value: exit })
+    try {
+      expect(wrapper.classes()).not.toContain('admin-density')
+      const button = wrapper.get('button[aria-pressed]')
+      await button.trigger('click')
+      await flushPromises()
+      expect(enter).toHaveBeenCalledOnce()
+      expect(button.text()).toBe('退出全屏')
+      expect(button.attributes('aria-pressed')).toBe('true')
+      await button.trigger('click')
+      await flushPromises()
+      expect(exit).toHaveBeenCalledOnce()
+      expect(button.text()).toBe('全屏展示')
+      expect(button.attributes('aria-pressed')).toBe('false')
+    } finally {
+      if (previousElement) Object.defineProperty(document, 'fullscreenElement', previousElement)
+      else Reflect.deleteProperty(document, 'fullscreenElement')
+      if (previousExit) Object.defineProperty(document, 'exitFullscreen', previousExit)
+      else Reflect.deleteProperty(document, 'exitFullscreen')
+    }
+  })
+})
diff --git a/src/modules/dashboard/pages/DashboardView.vue b/src/modules/dashboard/pages/DashboardView.vue
new file mode 100644
index 00000000..a78d58a6
--- /dev/null
+++ b/src/modules/dashboard/pages/DashboardView.vue
@@ -0,0 +1,149 @@
+<script setup lang="ts">
+import dayjs from 'dayjs'
+import { computed, onBeforeUnmount, onMounted, ref } from 'vue'
+import {
+  Expand,
+  Minimize,
+  RefreshCw,
+} from '@lucide/vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import {
+  getActiveCustomerCount,
+  getDashboardOperationalMetrics,
+  getTodayNewOrderCount,
+  type DashboardOperationalMetrics,
+} from '../api/dashboard'
+
+const dashboardRef = ref<HTMLElement | null>(null)
+const isFullscreen = ref(false)
+const metricsLoading = ref(true)
+const metricsError = ref(false)
+const todayNewOrderCount = ref<number | null>(null)
+const activeCustomerCount = ref<number | null>(null)
+const operationalMetrics = ref<DashboardOperationalMetrics | null>(null)
+const metricsUpdatedAt = ref<string | null>(null)
+
+function displayNumber(value: number | null | undefined, maximumFractionDigits = 0) {
+  if (metricsLoading.value) return '…'
+  if (value === null || value === undefined) return '—'
+  return new Intl.NumberFormat('zh-CN', { maximumFractionDigits }).format(value)
+}
+
+const metrics = computed(() => [
+  { label: '今日新运单', value: displayNumber(todayNewOrderCount.value), unit: '票', note: '按今日创建时间统计', tone: 'blue' },
+  {
+    label: '在途柜量', value: displayNumber(operationalMetrics.value?.inTransitTeu, 2), unit: 'TEU',
+    note: operationalMetrics.value
+      ? `已开船未到仓 · ${operationalMetrics.value.inTransitContainerCount} 柜${operationalMetrics.value.unknownContainerTypeCount ? ` · ${operationalMetrics.value.unknownContainerTypeCount} 柜箱型未知` : ''}`
+      : '已开船且尚未到仓',
+    tone: 'green',
+  },
+  { label: '活跃客户', value: displayNumber(activeCustomerCount.value), unit: '家', note: '客户状态为启用', tone: 'purple' },
+  { label: '待清关票数', value: displayNumber(operationalMetrics.value?.pendingCustomsOrderCount), unit: '票', note: '已进入清关且尚未完成', tone: 'rose' },
+])
+
+async function toggleFullscreen() {
+  if (!document.fullscreenElement) await dashboardRef.value?.requestFullscreen()
+  else await document.exitFullscreen()
+}
+
+function syncFullscreenState() {
+  isFullscreen.value = document.fullscreenElement === dashboardRef.value
+}
+
+async function loadMetrics() {
+  metricsLoading.value = true
+  metricsError.value = false
+  const [orders, customers, operations] = await Promise.allSettled([
+    getTodayNewOrderCount(),
+    getActiveCustomerCount(),
+    getDashboardOperationalMetrics(),
+  ])
+  todayNewOrderCount.value = orders.status === 'fulfilled' ? orders.value : null
+  activeCustomerCount.value = customers.status === 'fulfilled' ? customers.value : null
+  operationalMetrics.value = operations.status === 'fulfilled' ? operations.value : null
+  metricsError.value = [orders, customers, operations].some(result => result.status === 'rejected')
+  metricsUpdatedAt.value = operations.status === 'fulfilled' && operations.value.asOf
+    ? operations.value.asOf
+    : dayjs().format('YYYY-MM-DDTHH:mm:ss')
+  metricsLoading.value = false
+}
+
+onMounted(() => {
+  document.addEventListener('fullscreenchange', syncFullscreenState)
+  void loadMetrics()
+})
+onBeforeUnmount(() => document.removeEventListener('fullscreenchange', syncFullscreenState))
+</script>
+
+<template>
+  <section ref="dashboardRef" class="dashboard-view">
+    <AdminPage as="div" spacing="normal">
+      <section class="dashboard-context" aria-label="数据看板说明">
+        <p>{{ metricsError ? '部分核心指标加载失败，可刷新重试。' : '核心指标来自实时业务数据。' }}</p>
+        <div class="dashboard-head-actions">
+          <span>数据更新时间：{{ metricsUpdatedAt ? dayjs(metricsUpdatedAt).format('YYYY-MM-DD HH:mm') : '加载中' }}</span>
+          <button type="button" class="dashboard-outline-button" :disabled="metricsLoading" @click="loadMetrics">
+            <RefreshCw :size="16" aria-hidden="true" />
+            刷新数据
+          </button>
+          <button type="button" class="dashboard-outline-button" :aria-pressed="isFullscreen" @click="toggleFullscreen">
+            <Minimize v-if="isFullscreen" :size="16" aria-hidden="true" />
+            <Expand v-else :size="16" aria-hidden="true" />
+            {{ isFullscreen ? '退出全屏' : '全屏展示' }}
+          </button>
+        </div>
+      </section>
+
+      <div class="dashboard-metrics" aria-label="核心业务指标">
+        <article v-for="metric in metrics" :key="metric.label" class="dashboard-metric" :class="`is-${metric.tone}`">
+          <span class="dashboard-metric-mark" aria-hidden="true" />
+          <p>{{ metric.label }}</p>
+          <strong>{{ metric.value }} <small>{{ metric.unit }}</small></strong>
+          <span>{{ metric.note }}</span>
+        </article>
+      </div>
+    </AdminPage>
+  </section>
+</template>
+
+<style scoped>
+.dashboard-view { --dashboard-panel: var(--cc-surface, #fff); display: block; min-width: 0; color: var(--cc-text, #172033); }
+.dashboard-view:fullscreen { overflow: auto; padding: 24px; background: var(--cc-page, #f4f6f8); }
+.dashboard-context { display: flex; min-width: 0; align-items: center; justify-content: space-between; gap: 16px; }
+.dashboard-context p { min-width: 0; margin: 0; color: var(--cc-muted, #667085); font-size: 12px; line-height: 1.55; }
+.dashboard-head-actions { display: flex; align-items: center; gap: 14px; color: var(--cc-muted, #667085); font-size: 12px; white-space: nowrap; }
+.dashboard-outline-button { display: inline-flex; min-height: 36px; align-items: center; justify-content: center; gap: 6px; padding: 0 13px; border: 1px solid var(--cc-border-strong, #d8deea); border-radius: var(--cc-radius-md, 6px); background: var(--cc-surface, #fff); color: var(--cc-text-secondary, #344054); cursor: pointer; transition: border-color .18s ease, background .18s ease, color .18s ease; }
+.dashboard-outline-button:hover:not(:disabled) { border-color: var(--cc-primary); color: var(--cc-primary); }
+.dashboard-outline-button:disabled { cursor: wait; opacity: .65; }
+.dashboard-metrics { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 14px; }
+.dashboard-metric { position: relative; min-width: 0; overflow: hidden; padding: 20px; border: 1px solid var(--cc-border); border-radius: 8px; background: var(--dashboard-panel); }
+.dashboard-metric-mark { position: absolute; top: -38px; right: -30px; width: 110px; height: 110px; border-radius: 50%; background: #edf1ff; }
+.dashboard-metric.is-green .dashboard-metric-mark { background: #e8f7ee; }
+.dashboard-metric.is-purple .dashboard-metric-mark { background: #f1eaff; }
+.dashboard-metric.is-rose .dashboard-metric-mark { background: #fdeaf1; }
+.dashboard-metric p { position: relative; margin: 0 0 25px; color: #5f6573; font-size: 13px; font-weight: 700; }
+.dashboard-metric strong { position: relative; display: block; overflow-wrap: anywhere; font-size: 31px; font-variant-numeric: tabular-nums; line-height: 1; letter-spacing: -.02em; }
+.dashboard-metric strong small { color: #525866; font-size: 12px; font-weight: 600; letter-spacing: 0; }
+.dashboard-metric > span:last-child { position: relative; display: block; margin-top: 17px; color: #8a91a0; font-size: 11px; }
+@media (max-width: 1180px) {
+  .dashboard-metrics { grid-template-columns: repeat(3, minmax(0, 1fr)); }
+}
+@media (max-width: 760px) {
+  .dashboard-context { align-items: flex-start; flex-direction: column; }
+  .dashboard-head-actions { align-items: flex-start; flex-direction: column; gap: 9px; white-space: normal; }
+  .dashboard-metrics { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+}
+@media (max-width: 420px) {
+  .dashboard-metrics { grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 8px; }
+  .dashboard-metric { min-height: 116px; padding: 13px; }
+  .dashboard-metric-mark { top: -30px; right: -24px; width: 80px; height: 80px; }
+  .dashboard-metric p { margin-bottom: 12px; font-size: 11px; }
+  .dashboard-metric strong { font-size: 23px; }
+  .dashboard-metric strong small { font-size: 10px; }
+  .dashboard-metric > span:last-child { margin-top: 10px; font-size: 10px; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .dashboard-outline-button { transition: none; }
+}
+</style>
diff --git a/src/modules/dashboard/routes.ts b/src/modules/dashboard/routes.ts
new file mode 100644
index 00000000..512ba71a
--- /dev/null
+++ b/src/modules/dashboard/routes.ts
@@ -0,0 +1,14 @@
+import type { RouteRecordRaw } from 'vue-router'
+
+export const dashboardRoutes = [
+  {
+    path: 'dashboard',
+    name: 'dashboard',
+    component: () => import('@/modules/dashboard/pages/DashboardView.vue'),
+    meta: {
+      title: '首页数据看板',
+      description: '平台实时核心业务指标',
+      showPageHeading: false,
+    },
+  },
+] satisfies RouteRecordRaw[]
diff --git a/src/modules/dimension-config/api.test.ts b/src/modules/dimension-config/api.test.ts
new file mode 100644
index 00000000..2b960aa8
--- /dev/null
+++ b/src/modules/dimension-config/api.test.ts
@@ -0,0 +1,41 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const http = vi.hoisted(() => ({ get: vi.fn(), put: vi.fn() }))
+vi.mock('@/shared/api/http', () => ({ http, unwrapApiResponse: <T>(response: { data: T }) => response.data }))
+
+import { getCustomerDimensionConfig, updateCustomerDimensionConfig } from './api'
+import type { CustomerDimensionRule, UpdateCustomerDimensionRule } from './types'
+
+const rawRule = {
+  id: '9007199254740995',
+  boxType: 'SMALL', boxTypeName: '小箱', innerLengthCm: 30, innerWidthCm: 20, innerHeightCm: 20,
+  edgeAdditionCm: 2, outerLengthCm: 34, outerWidthCm: 24, outerHeightCm: 24, volumeCbm: 0.02,
+  remark: '标准小箱', version: 3, createdAt: '2026-08-07T10:00:00', updatedAt: '2026-08-07T10:20:00',
+} satisfies CustomerDimensionRule
+
+describe('customer dimension config api', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it('normalizes the wrapped config and keeps the customer id as a string', async () => {
+    http.get.mockResolvedValue({ data: { tenantId: 9007199254740993n.toString(), rules: [rawRule] } })
+    const result = await getCustomerDimensionConfig('9007199254740993')
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/first-leg/customer-dimension-config', { params: { tenantId: '9007199254740993' } })
+    expect(result).toEqual({ tenantId: '9007199254740993', defaultCalculationMode: 'ADD', rules: [rawRule] })
+    expect(result.rules[0].id).toBe('9007199254740995')
+  })
+
+  it('submits the complete rule set in one update request', async () => {
+    const updateRule = {
+      boxType: rawRule.boxType,
+      innerLengthCm: rawRule.innerLengthCm,
+      innerWidthCm: rawRule.innerWidthCm,
+      innerHeightCm: rawRule.innerHeightCm,
+      edgeAdditionCm: rawRule.edgeAdditionCm,
+      remark: rawRule.remark,
+      version: rawRule.version,
+    } satisfies UpdateCustomerDimensionRule
+    http.put.mockResolvedValue({ data: { tenantId: '8', rules: [rawRule] } })
+    await updateCustomerDimensionConfig('8', { rules: [updateRule] })
+    expect(http.put).toHaveBeenCalledWith('/platform/v1/first-leg/customer-dimension-config', { rules: [updateRule] }, { params: { tenantId: '8' } })
+  })
+})
diff --git a/src/modules/dimension-config/api.ts b/src/modules/dimension-config/api.ts
new file mode 100644
index 00000000..ae967ab1
--- /dev/null
+++ b/src/modules/dimension-config/api.ts
@@ -0,0 +1,60 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import type {
+  CustomerDimensionConfig,
+  CustomerDimensionCalculationMode,
+  CustomerDimensionRule,
+  UpdateCustomerDimensionConfigRequest,
+} from './types'
+
+const dimensionConfigPath = '/platform/v1/first-leg/customer-dimension-config'
+
+type RawRule = Omit<CustomerDimensionRule, 'id' | 'version'> & {
+  id: string | number
+  version: string | number
+}
+type RawConfig = Omit<CustomerDimensionConfig, 'tenantId' | 'rules'> & {
+  tenantId: string | number
+  rules: RawRule[]
+}
+
+function normalizeRule(rule: RawRule): CustomerDimensionRule {
+  return { ...rule, id: String(rule.id), version: Number(rule.version) }
+}
+
+function normalizeConfig(config: RawConfig): CustomerDimensionConfig {
+  return {
+    tenantId: String(config.tenantId),
+    defaultCalculationMode: config.defaultCalculationMode === 'MULTIPLY' ? 'MULTIPLY'
+      : config.defaultCalculationMode === 'ACTUAL' ? 'ACTUAL' : 'ADD',
+    rules: config.rules.map(normalizeRule),
+  }
+}
+
+export async function getCustomerDimensionConfig(tenantId: string): Promise<CustomerDimensionConfig> {
+  const response = await http.get<never, ApiEnvelope<RawConfig>>(dimensionConfigPath, {
+    params: { tenantId },
+  })
+  return normalizeConfig(unwrapApiResponse(response))
+}
+
+export async function updateCustomerDimensionConfig(
+  tenantId: string,
+  request: UpdateCustomerDimensionConfigRequest,
+): Promise<CustomerDimensionConfig> {
+  const response = await http.put<never, ApiEnvelope<RawConfig>>(dimensionConfigPath, request, {
+    params: { tenantId },
+  })
+  return normalizeConfig(unwrapApiResponse(response))
+}
+
+export async function updateCustomerDimensionDefaultCalculationMode(
+  tenantId: string,
+  defaultCalculationMode: CustomerDimensionCalculationMode,
+): Promise<CustomerDimensionConfig> {
+  const response = await http.put<never, ApiEnvelope<RawConfig>>(
+    `${dimensionConfigPath}/default-calculation-mode`,
+    { defaultCalculationMode },
+    { params: { tenantId } },
+  )
+  return normalizeConfig(unwrapApiResponse(response))
+}
diff --git a/src/modules/dimension-config/index.ts b/src/modules/dimension-config/index.ts
new file mode 100644
index 00000000..69235887
--- /dev/null
+++ b/src/modules/dimension-config/index.ts
@@ -0,0 +1,15 @@
+export {
+  getCustomerDimensionConfig,
+  updateCustomerDimensionConfig,
+  updateCustomerDimensionDefaultCalculationMode,
+} from './api'
+
+export type {
+  CustomerDimensionBoxType,
+  CustomerDimensionCalculationMode,
+  CustomerDimensionConfig,
+  CustomerDimensionConfigFormModel,
+  CustomerDimensionRule,
+  UpdateCustomerDimensionConfigRequest,
+  UpdateCustomerDimensionRule,
+} from './types'
diff --git a/src/modules/dimension-config/types.ts b/src/modules/dimension-config/types.ts
new file mode 100644
index 00000000..5da4ed07
--- /dev/null
+++ b/src/modules/dimension-config/types.ts
@@ -0,0 +1,44 @@
+export type CustomerDimensionBoxType = 'SMALL' | 'MEDIUM' | 'LARGE' | 'EXTRA_LARGE'
+export type CustomerDimensionCalculationMode = 'ACTUAL' | 'ADD' | 'MULTIPLY'
+
+export interface CustomerDimensionRule {
+  id: string
+  boxType: CustomerDimensionBoxType
+  boxTypeName: string
+  innerLengthCm: number
+  innerWidthCm: number
+  innerHeightCm: number
+  edgeAdditionCm: number
+  outerLengthCm: number
+  outerWidthCm: number
+  outerHeightCm: number
+  volumeCbm: number
+  remark: string | null
+  version: number
+  createdAt: string | null
+  updatedAt: string | null
+}
+
+export interface CustomerDimensionConfig {
+  tenantId: string
+  defaultCalculationMode: CustomerDimensionCalculationMode
+  rules: CustomerDimensionRule[]
+}
+
+export type UpdateCustomerDimensionRule = Pick<CustomerDimensionRule,
+  | 'boxType'
+  | 'innerLengthCm'
+  | 'innerWidthCm'
+  | 'innerHeightCm'
+  | 'edgeAdditionCm'
+  | 'remark'
+  | 'version'
+>
+
+export interface UpdateCustomerDimensionConfigRequest {
+  rules: UpdateCustomerDimensionRule[]
+}
+
+export interface CustomerDimensionConfigFormModel {
+  rules: CustomerDimensionRule[]
+}
diff --git a/src/modules/domestic-containers/api/domesticContainers.test.ts b/src/modules/domestic-containers/api/domesticContainers.test.ts
new file mode 100644
index 00000000..3f18adad
--- /dev/null
+++ b/src/modules/domestic-containers/api/domesticContainers.test.ts
@@ -0,0 +1,10 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import { createDomesticContainerOutbound, listDomesticContainerInventories } from './domesticContainers'
+vi.mock('@/shared/api/http', async (original) => ({ ...(await original<typeof import('@/shared/api/http')>()), http: { get: vi.fn(), post: vi.fn() } }))
+const envelope = <T>(data: T) => ({ code: '200', message: 'ok', data })
+describe('domestic container api', () => {
+  beforeEach(() => vi.clearAllMocks())
+  it('normalizes inventory pagination and summary from the real endpoint', async () => { vi.mocked(http.get).mockResolvedValue(envelope({ records: [], page: '1', size: '20', total: '0', pages: '0', summary: { inboundBoxes: 2, outboundBoxes: 1, availableBoxes: 1, inboundVolumeCbm: 3.25 } })); const result = await listDomesticContainerInventories({ page: 1, size: 20 }); expect(http.get).toHaveBeenCalledWith('/platform/v1/domestic-containers/inventories', { params: { page: 1, size: 20 } }); expect(result).toMatchObject({ page: 1, total: 0, summary: { availableBoxes: 1 } }) })
+  it('passes idempotency key and inventory version without local deduction', async () => { vi.mocked(http.post).mockResolvedValue(envelope({ id: 1, orderNo: 'ZGCK1', replayed: false })); await createDomesticContainerOutbound({ warehouseId: '2', containerNo: 'MSCU1', boxCount: 3, outboundTime: '2026-08-13T10:00:00', status: 'COMPLETED', idempotencyKey: 'stable-key', inventoryVersion: 7 }); expect(http.post).toHaveBeenCalledWith('/platform/v1/domestic-containers/outbounds', expect.objectContaining({ idempotencyKey: 'stable-key', inventoryVersion: 7 })) })
+})
diff --git a/src/modules/domestic-containers/api/domesticContainers.ts b/src/modules/domestic-containers/api/domesticContainers.ts
new file mode 100644
index 00000000..4d763607
--- /dev/null
+++ b/src/modules/domestic-containers/api/domesticContainers.ts
@@ -0,0 +1,34 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import type { ContainerOrder, CreateInboundRequest, CreateOutboundRequest, CreateResponse, DomesticContainerFilters, InventoryDetail, InventoryPage, PageResult } from '../types'
+
+const basePath = '/platform/v1/domestic-containers'
+type PagePayload<T> = Omit<PageResult<T>, 'page' | 'size' | 'total' | 'pages'> & { page: number | string; size: number | string; total: number | string; pages: number | string }
+type InventoryPayload = Omit<InventoryPage, 'page' | 'size' | 'total' | 'pages'> & { page: number | string; size: number | string; total: number | string; pages: number | string; summary?: Partial<InventoryPage['summary']> }
+
+function pageResult<T>(value: PagePayload<T>): PageResult<T> { return { ...value, page: Number(value.page), size: Number(value.size), total: Number(value.total), pages: Number(value.pages) } }
+
+export async function listDomesticContainerInbounds(query: DomesticContainerFilters) {
+  const response = await http.get<ApiEnvelope<PagePayload<ContainerOrder>>, ApiEnvelope<PagePayload<ContainerOrder>>>(`${basePath}/inbounds`, { params: query })
+  return pageResult(unwrapApiResponse(response))
+}
+export async function listDomesticContainerOutbounds(query: DomesticContainerFilters) {
+  const response = await http.get<ApiEnvelope<PagePayload<ContainerOrder>>, ApiEnvelope<PagePayload<ContainerOrder>>>(`${basePath}/outbounds`, { params: query })
+  return pageResult(unwrapApiResponse(response))
+}
+export async function listDomesticContainerInventories(query: DomesticContainerFilters) {
+  const response = await http.get<ApiEnvelope<InventoryPayload>, ApiEnvelope<InventoryPayload>>(`${basePath}/inventories`, { params: query })
+  const result = unwrapApiResponse(response)
+  return { ...pageResult(result), summary: { inboundBoxes: Number(result.summary?.inboundBoxes ?? 0), outboundBoxes: Number(result.summary?.outboundBoxes ?? 0), availableBoxes: Number(result.summary?.availableBoxes ?? 0), inboundVolumeCbm: Number(result.summary?.inboundVolumeCbm ?? 0) } }
+}
+export async function getDomesticContainerInventory(inventoryId: number | string) {
+  const response = await http.get<ApiEnvelope<InventoryDetail>, ApiEnvelope<InventoryDetail>>(`${basePath}/inventories/${inventoryId}`)
+  return unwrapApiResponse(response)
+}
+export async function createDomesticContainerInbound(payload: CreateInboundRequest) {
+  const response = await http.post<ApiEnvelope<CreateResponse>, ApiEnvelope<CreateResponse>>(`${basePath}/inbounds`, payload)
+  return unwrapApiResponse(response)
+}
+export async function createDomesticContainerOutbound(payload: CreateOutboundRequest) {
+  const response = await http.post<ApiEnvelope<CreateResponse>, ApiEnvelope<CreateResponse>>(`${basePath}/outbounds`, payload)
+  return unwrapApiResponse(response)
+}
diff --git a/src/modules/domestic-containers/index.ts b/src/modules/domestic-containers/index.ts
new file mode 100644
index 00000000..556ef0a2
--- /dev/null
+++ b/src/modules/domestic-containers/index.ts
@@ -0,0 +1,2 @@
+export * from './api/domesticContainers'
+export * from './types'
diff --git a/src/modules/domestic-containers/pages/DomesticContainerInventoryDetailView.test.ts b/src/modules/domestic-containers/pages/DomesticContainerInventoryDetailView.test.ts
new file mode 100644
index 00000000..2292bd04
--- /dev/null
+++ b/src/modules/domestic-containers/pages/DomesticContainerInventoryDetailView.test.ts
@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/domestic-containers/pages/DomesticContainerInventoryDetailView.vue'), 'utf8')
+
+const densitySource = readFileSync(resolve(process.cwd(), 'src/styles/adminDensity.css'), 'utf8')
+
+describe('DomesticContainerInventoryDetailView', () => {
+  it('does not invent an action column for immutable transaction history', () => {
+    expect(source).not.toContain("label: '操作'")
+    expect(source).toContain('进销存交易记录')
+  })
+  it('surfaces loading and API diagnostic errors and supports retry', () => {
+    expect(source).toContain('整柜库存详情加载失败')
+    expect(source).toContain('@retry="load"')
+    expect(source).toContain('<ApiErrorMeta :details="error" />')
+    expect(source).toContain('v-loading="loading"')
+  })
+  it('uses a four-column desktop field grid and preserves long business text', () => {
+    expect(source).toContain('grid-template-columns: repeat(4, minmax(0, 1fr))')
+    expect(source).toContain('class="detail-fields density-fields"')
+    expect(densitySource).toContain('overflow-wrap: anywhere')
+  })
+})
diff --git a/src/modules/domestic-containers/pages/DomesticContainerInventoryDetailView.vue b/src/modules/domestic-containers/pages/DomesticContainerInventoryDetailView.vue
new file mode 100644
index 00000000..db524c72
--- /dev/null
+++ b/src/modules/domestic-containers/pages/DomesticContainerInventoryDetailView.vue
@@ -0,0 +1,112 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { onMounted, ref } from 'vue'
+import { ArrowLeft } from '@lucide/vue'
+import { useRoute, useRouter } from 'vue-router'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { getDomesticContainerInventory } from '../api/domesticContainers'
+import type { InventoryDetail, InventoryStatus, TransactionRecord } from '../types'
+
+const route = useRoute()
+const router = useRouter()
+const loading = ref(false)
+const error = ref<ApiErrorDetails | null>(null)
+const detail = ref<InventoryDetail | null>(null)
+
+const transactionColumns: DataTableColumn[] = [
+  { prop: 'businessType', label: '业务类型', width: 110, slotName: 'businessType' },
+  { prop: 'orderNo', label: '单号', minWidth: 210 },
+  { prop: 'quantity', label: '数量', width: 110, align: 'right', formatter: (row: TransactionRecord) => `${row.quantity} 箱` },
+  { prop: 'operationTime', label: '操作时间', width: 170, formatter: (row: TransactionRecord) => displayTime(row.operationTime) },
+  { prop: 'remark', label: '备注', minWidth: 180, formatter: (row: TransactionRecord) => row.remark || '—' },
+]
+
+function inventoryStatus(status: InventoryStatus) {
+  return ({ IN_STOCK: '在库', PARTIALLY_OUTBOUND: '部分出库', OUTBOUND: '已出库' } as const)[status]
+}
+
+function displayTime(value: string) {
+  return value ? value.replace('T', ' ').slice(0, 16) : '—'
+}
+
+function back() {
+  void router.push({ name: 'domestic-containers' })
+}
+
+async function load() {
+  loading.value = true
+  error.value = null
+  try {
+    detail.value = await getDomesticContainerInventory(String(route.params.inventoryId))
+  } catch (cause) {
+    error.value = getApiErrorDetails(cause, '整柜库存详情加载失败')
+  } finally {
+    loading.value = false
+  }
+}
+
+onMounted(load)
+</script>
+
+<template>
+  <AdminPage as="div" class="inventory-detail-page admin-density">
+    <section class="inventory-overview">
+    <header class="detail-header">
+      <el-button link class="density-back" aria-label="返回整柜业务" @click="back"><ArrowLeft :size="16" />返回列表</el-button>
+      <h1>{{ detail?.inventory.containerNo || '整柜库存详情' }}</h1>
+      <StatusBadge v-if="detail" :status="inventoryStatus(detail.inventory.inventoryStatus)" />
+    </header>
+
+    <LoadErrorState v-if="error" title="整柜库存详情加载失败" :message="error.message" :loading="loading" @retry="load">
+      <template #details><ApiErrorMeta :details="error" /></template>
+    </LoadErrorState>
+
+      <section v-else-if="detail" class="detail-section" aria-labelledby="inventory-basic-heading">
+        <h2 id="inventory-basic-heading">整柜信息</h2>
+        <dl class="detail-fields density-fields">
+          <div><dt>货物名称</dt><dd>{{ detail.inventory.cargoName }}</dd></div>
+          <div><dt>集装箱号</dt><dd>{{ detail.inventory.containerNo }}</dd></div>
+          <div><dt>国内仓</dt><dd>{{ detail.inventory.warehouseName }}</dd></div>
+          <div><dt>库存状态</dt><dd>{{ inventoryStatus(detail.inventory.inventoryStatus) }}</dd></div>
+          <div><dt>入库单数量</dt><dd>{{ detail.inboundOrderCount }}</dd></div>
+          <div><dt>出库单数量</dt><dd>{{ detail.outboundOrderCount }}</dd></div>
+          <div><dt>入库箱数</dt><dd>{{ detail.inventory.inboundBoxes }} 箱</dd></div>
+          <div><dt>已出库箱数</dt><dd>{{ detail.inventory.outboundBoxes }} 箱</dd></div>
+          <div><dt>当前库存</dt><dd>{{ detail.inventory.availableBoxes }} 箱</dd></div>
+          <div><dt>累计入库体积</dt><dd>{{ detail.inventory.inboundVolumeCbm.toFixed(2) }} m³</dd></div>
+          <div><dt>最后更新时间</dt><dd>{{ displayTime(detail.inventory.updatedAt) }}</dd></div>
+          <div><dt>库存版本</dt><dd>{{ detail.inventory.version }}</dd></div>
+        </dl>
+      </section>
+      <div v-else class="detail-loading" v-loading="loading">正在加载整柜库存详情</div>
+    </section>
+
+      <section v-if="detail && !error" class="transactions" aria-labelledby="transactions-heading">
+        <h2 id="transactions-heading">进销存交易记录</h2>
+        <DataTable :data="detail.transactions" :columns="transactionColumns" row-key="id" stripe column-settings-mode="hide" empty-text="暂无进销存流水">
+          <template #businessType="{ row }"><StatusBadge :status="row.businessType === 'INBOUND' ? '入库' : '出库'" /></template>
+        </DataTable>
+      </section>
+  </AdminPage>
+</template>
+
+<style scoped>
+.inventory-detail-page { display: grid; min-width: 0; gap: var(--admin-space-5, 12px); }
+.inventory-overview { min-width: 0; border: 1px solid var(--cc-border); background: var(--admin-surface, #fff); }
+.detail-header { display: flex; flex-wrap: wrap; align-items: center; gap: var(--admin-space-5, 12px); min-height: 40px; padding: var(--admin-space-3, 8px) var(--admin-space-5, 12px); }
+.detail-header h1 { margin: 0; font-size: var(--admin-font-title, 16px); letter-spacing: 0; }
+.transactions { min-width: 0; border: 1px solid var(--cc-border); background: var(--admin-surface, #fff); }
+.detail-section { min-width: 0; padding: 0 var(--admin-space-5, 12px) var(--admin-space-5, 12px); }
+.detail-section h2, .transactions h2 { margin: 0; font-size: var(--admin-font-section, 14px); letter-spacing: 0; }
+.detail-fields { grid-template-columns: repeat(4, minmax(0, 1fr)); margin: var(--admin-space-3, 8px) 0 0; }
+.transactions { padding-top: var(--admin-space-5, 12px); overflow: hidden; }
+.transactions h2 { margin: 0 var(--admin-space-5, 12px) var(--admin-space-3, 8px); }
+.detail-loading { min-height: 180px; padding: var(--admin-space-7, 24px); border: 1px solid var(--cc-border); background: var(--admin-surface, #fff); color: var(--cc-muted); }
+@media (max-width: 960px) { .detail-fields { grid-template-columns: repeat(2, minmax(0, 1fr)); } }
+@media (max-width: 520px) { .detail-header { flex-wrap: wrap; } .detail-header h1 { width: 100%; font-size: 18px; } .detail-fields { grid-template-columns: 1fr; } }
+</style>
diff --git a/src/modules/domestic-containers/pages/DomesticContainersView.test.ts b/src/modules/domestic-containers/pages/DomesticContainersView.test.ts
new file mode 100644
index 00000000..fadb5e78
--- /dev/null
+++ b/src/modules/domestic-containers/pages/DomesticContainersView.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+const source = readFileSync(resolve(process.cwd(), 'src/modules/domestic-containers/pages/DomesticContainersView.vue'), 'utf8')
+const summaryStyles = readFileSync(resolve(process.cwd(), 'src/modules/domestic-containers/pages/domesticContainersSummary.css'), 'utf8')
+describe('DomesticContainersView', () => {
+  it('uses formal shared list and centered dialog components', () => { expect(source).toContain('QueryToolbar'); expect(source).toContain('DataTable'); expect(source).toContain('AppDialog'); expect(source).toContain("fixed: 'left'"); expect(source).toContain('width="min(720px, calc(100vw - 28px))"') })
+  it('gates create actions with backend permissions', () => { expect(source).toContain("access.can('platform:domestic-container:inbound:create')"); expect(source).toContain("access.can('platform:domestic-container:outbound:create')") })
+  it('loads only active domestic warehouse candidates and surfaces errors', () => { expect(source).toContain("listAllPlatformWarehouses({ warehouseType: 'DOMESTIC', status: 'ACTIVE' })"); expect(source).toContain('国内仓候选加载失败') })
+  it('keeps idempotency key stable through retry and handles conflicts by refreshing inventory', () => { expect(source).toContain('idempotencyKey.value'); expect(source).toContain("submitError.value.code === 'A0409'"); expect(source).toContain('await loadCandidates()'); expect(source).not.toContain('localStorage') })
+  it('reuses the order-list tab panel and keyboard interaction', () => { expect(source).toContain('class="business-query-panel"'); expect(source).toContain('role="tablist"'); expect(source).toContain('role="tab"'); expect(source).toContain('handleTabKeydown'); expect(source).toContain(".status-tab.is-active::after{background:var(--cc-primary)}"); expect(source).not.toContain('<el-tabs') })
+  it('keeps desktop filters and actions on one row with explicit field widths', () => { expect(source).toContain("key: 'warehouseId', type: 'select', width: 210"); expect(source).toContain("key: 'orderNo', type: 'input', width: 220"); expect(source).toContain("key: 'containerNo', type: 'input', width: 220"); expect(source).toContain("key: 'cargoName', type: 'input', width: 220"); expect(source).toContain("key: 'status', type: 'select', width: 180") })
+  it('uses the shared query toolbar flow without a page-level layout override', () => { expect(source).not.toContain('.query-toolbar__filters') })
+  it('keeps all four inventory facts in the approved compact summary', () => {
+    for (const fact of ['summary.inboundBoxes', 'summary.outboundBoxes', 'summary.availableBoxes', 'summary.inboundVolumeCbm']) expect(source).toContain(fact)
+    expect(source).toContain("import './domesticContainersSummary.css'")
+    expect(summaryStyles).toContain('display: flex; flex-wrap: wrap')
+    expect(summaryStyles).toContain('font-size: var(--admin-font-section, 14px)')
+    expect(summaryStyles).not.toContain('position: absolute')
+  })
+  it('does not offer an inventory detail action before an inbound has formed inventory', () => { expect(source).toContain("canViewInventory(row as ContainerOrder | InventoryRecord)"); expect(source).toContain("row.status === 'COMPLETED'") })
+  it('matches backend numeric and container-number input boundaries before submit', () => { expect(source).toContain("pattern: /^[A-Za-z0-9-]{4,32}$/"); expect(source).toContain(':max="999999999"'); expect(source).toContain(':max="999999999999.9999"') })
+  it('requires a refreshed inventory version for completed outbound submission', () => { expect(source).toContain("outboundForm.inventoryVersion == null"); expect(source).toContain('库存版本未就绪，请重新选择集装箱') })
+})
diff --git a/src/modules/domestic-containers/pages/DomesticContainersView.vue b/src/modules/domestic-containers/pages/DomesticContainersView.vue
new file mode 100644
index 00000000..b375a394
--- /dev/null
+++ b/src/modules/domestic-containers/pages/DomesticContainersView.vue
@@ -0,0 +1,80 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, reactive, ref, watch } from 'vue'
+import { ElMessage, type FormInstance, type FormRules } from 'element-plus'
+import { Plus } from '@lucide/vue'
+import { useRouter } from 'vue-router'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { listAllPlatformWarehouses, type PlatformWarehouseSummaryResource } from '@/modules/warehouses'
+import { createDomesticContainerInbound, createDomesticContainerOutbound, getDomesticContainerInventory, listDomesticContainerInbounds, listDomesticContainerInventories, listDomesticContainerOutbounds } from '../api/domesticContainers'
+import type { ContainerOrder, ContainerOrderStatus, InventoryRecord, InventorySummary } from '../types'
+import './domesticContainersSummary.css'
+
+type TabName = 'inbound' | 'outbound' | 'inventory'
+const router = useRouter(); const access = useAccessPreviewStore(); const activeTab = ref<TabName>('inbound')
+const businessTabs: Array<{ value: TabName; label: string; icon: string }> = [
+  { value: 'inbound', label: '整柜入库单', icon: '📥' },
+  { value: 'outbound', label: '整柜出库单', icon: '📤' },
+  { value: 'inventory', label: '整柜库存', icon: '📦' },
+]
+const loading = ref(false); const loadError = ref<ApiErrorDetails | null>(null); const rows = ref<(ContainerOrder | InventoryRecord)[]>([]); const page = ref(1); const pageSize = ref(20); const total = ref(0)
+const summary = ref<InventorySummary>({ inboundBoxes: 0, outboundBoxes: 0, availableBoxes: 0, inboundVolumeCbm: 0 })
+const warehouses = ref<PlatformWarehouseSummaryResource[]>([]); const warehouseLoading = ref(false); const warehouseError = ref<ApiErrorDetails | null>(null)
+const filters = ref<QueryModel>({ warehouseId: '', orderNo: '', containerNo: '', cargoName: '', status: '' })
+const appliedFilters = ref<QueryModel>({ ...filters.value })
+const warehouseOptions = computed(() => warehouses.value.map((item) => ({ label: item.warehouseName, value: String(item.id) })))
+const queryFields = computed<QueryField[]>(() => {
+  const base: QueryField[] = [{ key: 'warehouseId', type: 'select', width: 210, label: '国内仓', placeholder: warehouseError.value ? '国内仓加载失败' : '全部国内仓', options: warehouseOptions.value, props: { loading: warehouseLoading.value, disabled: Boolean(warehouseError.value) } }]
+  if (activeTab.value !== 'inventory') base.push({ key: 'orderNo', type: 'input', width: 220, label: '单号', placeholder: activeTab.value === 'inbound' ? '入库单号' : '出库单号' })
+  base.push({ key: 'containerNo', type: 'input', width: 220, label: '集装箱号', placeholder: '集装箱号' }, { key: 'cargoName', type: 'input', width: 220, label: '货物名称', placeholder: '货物名称' })
+  base.push({ key: 'status', type: 'select', width: 180, label: '状态', placeholder: '全部状态', options: activeTab.value === 'inventory' ? [{ label: '在库', value: 'IN_STOCK' }, { label: '部分出库', value: 'PARTIALLY_OUTBOUND' }, { label: '已出库', value: 'OUTBOUND' }] : [{ label: activeTab.value === 'inbound' ? '待入库' : '待出库', value: 'PENDING' }, { label: activeTab.value === 'inbound' ? '已入库' : '已出库', value: 'COMPLETED' }] })
+  return base
+})
+const columns = computed<DataTableColumn[]>(() => activeTab.value === 'inventory' ? [
+  { key: 'actions', label: '操作', fixed: 'left', width: 112, slotName: 'actions', hideable: false, movable: false }, { prop: 'containerNo', label: '集装箱号', minWidth: 150 }, { prop: 'warehouseName', label: '国内仓', minWidth: 150 }, { prop: 'cargoName', label: '货物名称', minWidth: 150 }, { prop: 'inboundBoxes', label: '入库箱数', width: 105, align: 'right' }, { prop: 'outboundBoxes', label: '已出库箱数', width: 115, align: 'right' }, { prop: 'availableBoxes', label: '当前库存', width: 105, align: 'right' }, { prop: 'inboundVolumeCbm', label: '累计入库体积(m³)', width: 155, align: 'right' }, { prop: 'inventoryStatus', label: '状态', width: 110, slotName: 'status' },
+] : [
+  { key: 'actions', label: '操作', fixed: 'left', width: 112, slotName: 'actions', hideable: false, movable: false }, { prop: 'orderNo', label: activeTab.value === 'inbound' ? '入库单号' : '出库单号', minWidth: 155 }, { prop: 'warehouseName', label: '国内仓', minWidth: 150 }, { prop: 'containerNo', label: '集装箱号', minWidth: 150 }, { prop: 'cargoName', label: '货物名称', minWidth: 150 }, { prop: 'boxCount', label: activeTab.value === 'inbound' ? '箱子数量' : '出库箱数', width: 105, align: 'right' }, ...(activeTab.value === 'inbound' ? [{ prop: 'volumeCbm', label: '体积(m³)', width: 105, align: 'right' }] : []), { prop: 'operationTime', label: activeTab.value === 'inbound' ? '入库时间' : '出库时间', minWidth: 165, formatter: (row: ContainerOrder) => displayTime(row.operationTime) }, { prop: 'status', label: '状态', width: 105, slotName: 'status' },
+])
+function displayTime(value: string) { return value ? value.replace('T', ' ').slice(0, 16) : '—' }
+function statusLabel(row: ContainerOrder | InventoryRecord) { if ('inventoryStatus' in row) return ({ IN_STOCK: '在库', PARTIALLY_OUTBOUND: '部分出库', OUTBOUND: '已出库' } as const)[row.inventoryStatus]; return row.status === 'PENDING' ? (activeTab.value === 'inbound' ? '待入库' : '待出库') : (activeTab.value === 'inbound' ? '已入库' : '已出库') }
+function canViewInventory(row: ContainerOrder | InventoryRecord) { return 'inventoryStatus' in row || activeTab.value === 'outbound' || row.status === 'COMPLETED' }
+function queryParams() { const model = appliedFilters.value; return { page: page.value, size: pageSize.value, warehouseId: String(model.warehouseId || '') || undefined, orderNo: activeTab.value === 'inventory' ? undefined : String(model.orderNo || '') || undefined, containerNo: String(model.containerNo || '') || undefined, cargoName: String(model.cargoName || '') || undefined, status: String(model.status || '') || undefined } }
+async function load() { loading.value = true; loadError.value = null; try { const result = activeTab.value === 'inbound' ? await listDomesticContainerInbounds(queryParams()) : activeTab.value === 'outbound' ? await listDomesticContainerOutbounds(queryParams()) : await listDomesticContainerInventories(queryParams()); rows.value = result.records; total.value = result.total; if ('summary' in result) summary.value = result.summary } catch (cause) { loadError.value = getApiErrorDetails(cause, '整柜业务加载失败') } finally { loading.value = false } }
+async function loadWarehouses() { warehouseLoading.value = true; warehouseError.value = null; try { warehouses.value = (await listAllPlatformWarehouses({ warehouseType: 'DOMESTIC', status: 'ACTIVE' })).filter((item) => item.warehouseType === 'DOMESTIC' && item.status === 'ACTIVE') } catch (cause) { warehouseError.value = getApiErrorDetails(cause, '国内仓候选加载失败') } finally { warehouseLoading.value = false } }
+function search(model = filters.value) { appliedFilters.value = { ...model }; if (page.value === 1) void load(); else page.value = 1 }
+function switchTab(name: TabName) { if (activeTab.value === name) return; activeTab.value = name; filters.value = { warehouseId: filters.value.warehouseId || '', orderNo: '', containerNo: '', cargoName: '', status: '' }; appliedFilters.value = { ...filters.value }; page.value = 1; void load() }
+function handleTabKeydown(event: KeyboardEvent, index: number) { let nextIndex = index; if (event.key === 'ArrowRight') nextIndex = (index + 1) % businessTabs.length; else if (event.key === 'ArrowLeft') nextIndex = (index - 1 + businessTabs.length) % businessTabs.length; else if (event.key === 'Home') nextIndex = 0; else if (event.key === 'End') nextIndex = businessTabs.length - 1; else return; event.preventDefault(); const tab = businessTabs[nextIndex]; if (!tab) return; switchTab(tab.value); (event.currentTarget as HTMLElement).parentElement?.querySelectorAll<HTMLElement>('[role="tab"]')[nextIndex]?.focus() }
+function viewInventory(row: ContainerOrder | InventoryRecord) { if ('inventoryStatus' in row) void router.push({ name: 'domestic-container-inventory-detail', params: { inventoryId: String(row.id) } }); else void findAndOpenInventory(row) }
+async function findAndOpenInventory(order: ContainerOrder) { try { const result = await listDomesticContainerInventories({ page: 1, size: 20, warehouseId: String(order.warehouseId), containerNo: order.containerNo }); const inventory = result.records.find((item) => String(item.warehouseId) === String(order.warehouseId) && item.containerNo === order.containerNo); if (!inventory) return ElMessage.warning('该单据尚未形成整柜库存'); await router.push({ name: 'domestic-container-inventory-detail', params: { inventoryId: String(inventory.id) } }) } catch (cause) { loadError.value = getApiErrorDetails(cause, '整柜库存定位失败') } }
+
+const dialogType = ref<'inbound' | 'outbound'>('inbound'); const dialogOpen = ref(false); const saving = ref(false); const submitError = ref<ApiErrorDetails | null>(null); const formRef = ref<FormInstance>(); const idempotencyKey = ref('')
+const inboundForm = reactive({ warehouseId: '', cargoName: '', containerNo: '', boxCount: 1, volumeCbm: 0.01, operationTime: '', status: 'COMPLETED' as ContainerOrderStatus, remark: '' })
+const outboundForm = reactive({ warehouseId: '', inventoryId: '', containerNo: '', cargoName: '', availableBoxes: 0, inventoryVersion: undefined as number | undefined, boxCount: 1, operationTime: '', status: 'COMPLETED' as ContainerOrderStatus, remark: '' })
+const inventoryCandidates = ref<InventoryRecord[]>([]); const candidateLoading = ref(false); const candidateError = ref<ApiErrorDetails | null>(null)
+const currentForm = computed(() => dialogType.value === 'inbound' ? inboundForm : outboundForm)
+const rules: FormRules = { warehouseId: [{ required: true, message: '请选择国内仓', trigger: 'change' }], cargoName: [{ required: true, message: '请输入货物名称', trigger: 'blur' }], containerNo: [{ required: true, message: '请选择或输入集装箱号', trigger: 'change' }, { pattern: /^[A-Za-z0-9-]{4,32}$/, message: '集装箱号须为 4–32 位字母、数字或连字符', trigger: 'blur' }], boxCount: [{ required: true, type: 'integer', min: 1, max: 999999999, message: '箱数须为 1–999999999 的整数', trigger: 'change' }], volumeCbm: [{ required: true, type: 'number', min: 0.0001, max: 999999999999.9999, message: '体积须在 0.0001–999999999999.9999 m³ 之间', trigger: 'change' }], operationTime: [{ required: true, message: '请选择操作时间', trigger: 'change' }], status: [{ required: true, message: '请选择状态', trigger: 'change' }] }
+function localDateTime() { const offset = new Date().getTimezoneOffset() * 60_000; return `${new Date(Date.now() - offset).toISOString().slice(0, 16)}:00` }
+function newIdempotencyKey(type: string) { return `${type}-${globalThis.crypto?.randomUUID?.() || `${Date.now()}-${Math.random().toString(16).slice(2)}`}` }
+function openInbound() { dialogType.value = 'inbound'; Object.assign(inboundForm, { warehouseId: '', cargoName: '', containerNo: '', boxCount: 1, volumeCbm: 0.01, operationTime: localDateTime(), status: 'COMPLETED', remark: '' }); idempotencyKey.value = newIdempotencyKey('inbound'); submitError.value = null; dialogOpen.value = true }
+function openOutbound() { dialogType.value = 'outbound'; Object.assign(outboundForm, { warehouseId: '', inventoryId: '', containerNo: '', cargoName: '', availableBoxes: 0, inventoryVersion: undefined, boxCount: 1, operationTime: localDateTime(), status: 'COMPLETED', remark: '' }); inventoryCandidates.value = []; candidateError.value = null; idempotencyKey.value = newIdempotencyKey('outbound'); submitError.value = null; dialogOpen.value = true }
+async function loadCandidates() { inventoryCandidates.value = []; Object.assign(outboundForm, { inventoryId: '', containerNo: '', cargoName: '', availableBoxes: 0, inventoryVersion: undefined }); if (!outboundForm.warehouseId) return; candidateLoading.value = true; candidateError.value = null; try { const result = await listDomesticContainerInventories({ page: 1, size: 200, warehouseId: outboundForm.warehouseId }); inventoryCandidates.value = result.records.filter((item) => item.availableBoxes > 0) } catch (cause) { candidateError.value = getApiErrorDetails(cause, '可出库整柜库存加载失败') } finally { candidateLoading.value = false } }
+async function selectInventory(id: string) { const selected = inventoryCandidates.value.find((item) => String(item.id) === id); if (!selected) return; Object.assign(outboundForm, { inventoryId: id, containerNo: selected.containerNo, cargoName: selected.cargoName, availableBoxes: selected.availableBoxes, inventoryVersion: selected.version }); try { const detail = await getDomesticContainerInventory(id); Object.assign(outboundForm, { availableBoxes: detail.inventory.availableBoxes, inventoryVersion: detail.inventory.version }) } catch (cause) { candidateError.value = getApiErrorDetails(cause, '库存最新版本加载失败') } }
+async function submit() { if (!await formRef.value?.validate().catch(() => false)) return; if (dialogType.value === 'outbound' && outboundForm.status === 'COMPLETED' && outboundForm.inventoryVersion == null) { submitError.value = { message: '库存版本未就绪，请重新选择集装箱', code: 'A0422' }; return } if (dialogType.value === 'outbound' && outboundForm.status === 'COMPLETED' && outboundForm.boxCount > outboundForm.availableBoxes) { submitError.value = { message: `库存不足，当前可用 ${outboundForm.availableBoxes} 箱`, code: 'A0409' }; return } saving.value = true; submitError.value = null; try { const result = dialogType.value === 'inbound' ? await createDomesticContainerInbound({ warehouseId: inboundForm.warehouseId, cargoName: inboundForm.cargoName.trim(), containerNo: inboundForm.containerNo.trim().toUpperCase(), boxCount: inboundForm.boxCount, volumeCbm: inboundForm.volumeCbm, inboundTime: inboundForm.operationTime, status: inboundForm.status, remark: inboundForm.remark.trim() || undefined, idempotencyKey: idempotencyKey.value }) : await createDomesticContainerOutbound({ warehouseId: outboundForm.warehouseId, containerNo: outboundForm.containerNo, boxCount: outboundForm.boxCount, outboundTime: outboundForm.operationTime, status: outboundForm.status, remark: outboundForm.remark.trim() || undefined, idempotencyKey: idempotencyKey.value, inventoryVersion: outboundForm.status === 'COMPLETED' ? outboundForm.inventoryVersion : undefined }); ElMessage.success(result.replayed ? `请求已处理，单号 ${result.orderNo}` : `创建成功，单号 ${result.orderNo}`); dialogOpen.value = false; await load() } catch (cause) { submitError.value = getApiErrorDetails(cause, '整柜单据创建失败'); if (dialogType.value === 'outbound' && submitError.value.code === 'A0409') await loadCandidates() } finally { saving.value = false } }
+watch([page, pageSize], load); onMounted(async () => { await Promise.all([loadWarehouses(), load()]) })
+</script>
+
+<template><AdminPage as="div" class="domestic-containers-page admin-density">
+<LoadErrorState v-if="warehouseError" compact title="国内仓候选加载失败" :message="warehouseError.message" :loading="warehouseLoading" @retry="loadWarehouses"><template #details><ApiErrorMeta :details="warehouseError" /></template></LoadErrorState>
+<ListPageLayout :aria-label="`${activeTab === 'inbound' ? '整柜入库单' : activeTab === 'outbound' ? '整柜出库单' : '整柜库存'}列表`"><template #toolbar><div class="business-query-panel"><div class="status-tabs" role="tablist" aria-label="整柜业务类型"><button v-for="(tab, index) in businessTabs" :key="tab.value" type="button" role="tab" :aria-selected="activeTab === tab.value" aria-controls="domestic-container-results" :tabindex="activeTab === tab.value ? 0 : -1" :class="['status-tab', { 'is-active': activeTab === tab.value }]" @click="switchTab(tab.value)" @keydown="handleTabKeydown($event, index)"><span class="density-tab-icon" aria-hidden="true">{{ tab.icon }}</span>{{ tab.label }}</button></div><QueryToolbar v-model="filters" class="business-query-toolbar" ariaLabel="整柜业务筛选" :fields="queryFields" :preference-key="`domestic-containers-${activeTab}-query`" @search="search" /></div></template><template v-if="loadError" #state><LoadErrorState title="整柜业务加载失败" :message="loadError.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="loadError" /></template></LoadErrorState></template><section v-if="!loadError" id="domestic-container-results" class="surface-panel table-panel"><div v-if="activeTab === 'inventory'" class="inventory-summary"><div><span>入库箱数</span><strong>{{ summary.inboundBoxes }}</strong></div><div><span>已出库箱数</span><strong>{{ summary.outboundBoxes }}</strong></div><div><span>当前库存</span><strong>{{ summary.availableBoxes }}</strong></div><div><span>累计入库体积</span><strong>{{ summary.inboundVolumeCbm.toFixed(2) }} m³</strong></div></div><DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :loading="loading" :total="total" stripe row-key="id" :preference-key="`domestic-containers-${activeTab}-table`" :empty-text="activeTab === 'inbound' ? '暂无整柜入库单' : activeTab === 'outbound' ? '暂无整柜出库单' : '暂无整柜库存'"><template #toolbar-actions><el-button v-if="activeTab === 'inbound' && access.can('platform:domestic-container:inbound:create')" type="primary" @click="openInbound"><Plus :size="16" />新建入库单</el-button><el-button v-if="activeTab === 'outbound' && access.can('platform:domestic-container:outbound:create')" type="primary" @click="openOutbound"><Plus :size="16" />新建出库单</el-button></template><template #actions="{ row }"><el-button v-if="canViewInventory(row as ContainerOrder | InventoryRecord)" class="density-action" size="small" @click="viewInventory(row as ContainerOrder | InventoryRecord)">查看</el-button><span v-else>—</span></template><template #status="{ row }"><StatusBadge :status="statusLabel(row as ContainerOrder | InventoryRecord)" /></template></DataTable></section></ListPageLayout>
+<AppDialog v-model="dialogOpen" class="domestic-container-create-dialog admin-density-dialog" :title="dialogType === 'inbound' ? '新建整柜入库单' : '新建整柜出库单'" width="min(720px, calc(100vw - 28px))" :confirm-loading="saving" :close-on-click-modal="false" :confirm-text="dialogType === 'inbound' ? '创建入库单' : '创建出库单'" @confirm="submit"><LoadErrorState v-if="submitError" compact title="创建失败" :message="submitError.message" :show-retry="false"><template #details><ApiErrorMeta :details="submitError" /></template></LoadErrorState><el-form ref="formRef" :model="currentForm" :rules="rules" label-position="top"><el-row :gutter="16"><template v-if="dialogType === 'inbound'"><el-col :xs="24" :sm="12"><el-form-item label="国内仓" prop="warehouseId"><el-select v-model="inboundForm.warehouseId" :loading="warehouseLoading" :disabled="Boolean(warehouseError)" placeholder="请选择启用的国内仓"><el-option v-for="item in warehouseOptions" :key="String(item.value)" :label="item.label" :value="String(item.value)" /></el-select></el-form-item></el-col><el-col :xs="24" :sm="12"><el-form-item label="货物名称" prop="cargoName"><el-input v-model="inboundForm.cargoName" maxlength="128" placeholder="请输入货物名称" /></el-form-item></el-col><el-col :xs="24" :sm="12"><el-form-item label="集装箱号" prop="containerNo"><el-input v-model="inboundForm.containerNo" maxlength="32" placeholder="如 MSCU1234567" /></el-form-item></el-col><el-col :xs="24" :sm="12"><el-form-item label="箱子数量" prop="boxCount"><el-input-number v-model="inboundForm.boxCount" :min="1" :max="999999999" :precision="0" controls-position="right" placeholder="请输入入库箱数" /></el-form-item></el-col><el-col :xs="24" :sm="12"><el-form-item label="体积(m³)" prop="volumeCbm"><el-input-number v-model="inboundForm.volumeCbm" :min="0.0001" :max="999999999999.9999" :precision="4" controls-position="right" placeholder="请输入体积" /></el-form-item></el-col></template><template v-else><el-col :xs="24" :sm="12"><el-form-item label="国内仓" prop="warehouseId"><el-select v-model="outboundForm.warehouseId" :loading="warehouseLoading" :disabled="Boolean(warehouseError)" placeholder="请选择启用的国内仓" @change="loadCandidates"><el-option v-for="item in warehouseOptions" :key="String(item.value)" :label="item.label" :value="String(item.value)" /></el-select></el-form-item></el-col><el-col :xs="24" :sm="12"><el-form-item label="绑定集装箱号" prop="containerNo"><el-select v-model="outboundForm.inventoryId" :loading="candidateLoading" :disabled="!outboundForm.warehouseId || Boolean(candidateError)" placeholder="请选择已有集装箱号" @change="selectInventory"><el-option v-for="item in inventoryCandidates" :key="String(item.id)" :label="`${item.containerNo} · 可用 ${item.availableBoxes} 箱`" :value="String(item.id)" /></el-select><input v-model="outboundForm.containerNo" class="sr-only" tabindex="-1"></el-form-item></el-col><el-col :xs="24" :sm="12"><el-form-item label="货物名称"><el-input v-model="outboundForm.cargoName" readonly /></el-form-item></el-col><el-col :xs="24" :sm="12"><el-form-item label="出库箱数" prop="boxCount"><el-input-number v-model="outboundForm.boxCount" :min="1" :max="999999999" :precision="0" controls-position="right" placeholder="请输入出库箱数" /></el-form-item></el-col><el-col :xs="24" :sm="12"><el-form-item label="可用库存"><el-input :model-value="`${outboundForm.availableBoxes} 箱`" readonly /></el-form-item></el-col><el-col v-if="candidateError" :xs="24"><LoadErrorState compact title="可出库库存加载失败" :message="candidateError.message" @retry="loadCandidates"><template #details><ApiErrorMeta :details="candidateError" /></template></LoadErrorState></el-col></template><el-col :xs="24" :sm="12"><el-form-item :label="dialogType === 'inbound' ? '入库时间' : '出库时间'" prop="operationTime"><el-date-picker v-model="currentForm.operationTime" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" format="YYYY-MM-DD HH:mm" /></el-form-item></el-col><el-col :xs="24" :sm="12"><el-form-item label="状态" prop="status"><el-select v-model="currentForm.status"><el-option :label="dialogType === 'inbound' ? '已入库' : '已出库'" value="COMPLETED" /><el-option :label="dialogType === 'inbound' ? '待入库' : '待出库'" value="PENDING" /></el-select></el-form-item></el-col><el-col :xs="24"><el-form-item label="备注"><el-input v-model="currentForm.remark" type="textarea" :rows="3" maxlength="500" show-word-limit placeholder="请输入备注" /></el-form-item></el-col></el-row></el-form></AppDialog></AdminPage></template>
+
+<style scoped>.domestic-containers-page{min-width:0}.business-query-panel{overflow:hidden;border:1px solid var(--cc-border);border-radius:var(--admin-radius, 4px);background:var(--admin-surface, #fff)}.status-tabs{display:flex;max-width:100%;overflow-x:auto;margin-bottom:0;border-bottom:1px solid var(--admin-table-border, #e5e7eb);background:#f9fafb;scrollbar-width:thin}.status-tab{position:relative;flex:0 0 auto;display:inline-flex;align-items:center;gap:var(--admin-space-2, 6px);min-height:var(--admin-tab-height, 38px);padding:0 var(--admin-space-6, 16px);border:0;background:transparent;color:var(--cc-muted);font:inherit;font-size:var(--admin-font-body, 13px);cursor:pointer}.status-tab::after{position:absolute;right:12px;bottom:0;left:12px;height:3px;background:transparent;content:''}.status-tab:hover{color:var(--cc-primary);background:#f6f9fd}.status-tab:focus-visible{outline:2px solid var(--cc-primary);outline-offset:-2px}.status-tab.is-active{color:var(--cc-primary);font-weight:600}.status-tab.is-active::after{background:var(--cc-primary)}.business-query-toolbar{border:0}.inventory-summary{display:flex;align-items:center;gap:0;margin:0 var(--admin-space-6, 16px) var(--admin-space-5, 12px);border:1px solid var(--cc-border);background:var(--admin-label-bg, #f8fafc)}.inventory-summary>div{display:flex;align-items:baseline;gap:var(--admin-space-3, 8px);min-width:0;padding:9px var(--admin-space-6, 16px);border-right:1px solid var(--cc-border)}.inventory-summary>div:last-child{border-right:0}.inventory-summary span{color:var(--cc-muted);font-size:var(--admin-font-caption, 12px)}.inventory-summary strong{font-size:15px}.domestic-container-create-dialog :deep(.el-select),.domestic-container-create-dialog :deep(.el-date-editor),.domestic-container-create-dialog :deep(.el-input-number){width:100%}.sr-only{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0,0,0,0)}@media(max-width:720px){.status-tab{min-height:46px;padding:0 14px}.inventory-summary{display:grid;grid-template-columns:repeat(2,minmax(0,1fr))}.inventory-summary>div:nth-child(2){border-right:0}.inventory-summary>div:nth-child(-n+2){border-bottom:1px solid var(--cc-border)}}@media(max-width:360px){.status-tab{padding:0 10px;font-size:13px}.inventory-summary{grid-template-columns:1fr}.inventory-summary>div{border-right:0;border-bottom:1px solid var(--cc-border)}.inventory-summary>div:last-child{border-bottom:0}}</style>
diff --git a/src/modules/domestic-containers/pages/domesticContainersSummary.css b/src/modules/domestic-containers/pages/domesticContainersSummary.css
new file mode 100644
index 00000000..0b979554
--- /dev/null
+++ b/src/modules/domestic-containers/pages/domesticContainersSummary.css
@@ -0,0 +1,9 @@
+.domestic-containers-page .table-panel .inventory-summary {
+  display: flex; flex-wrap: wrap; gap: var(--admin-space-2, 6px) 28px; margin: 0;
+  padding: var(--admin-space-3, 8px) var(--admin-space-5, 12px); border: 0; border-bottom: 1px solid var(--cc-border); background: var(--admin-surface, #fff);
+}
+.domestic-containers-page .table-panel .inventory-summary > div {
+  display: flex; align-items: baseline; min-width: 0; gap: var(--admin-space-3, 8px); padding: 0; border: 0;
+}
+.domestic-containers-page .table-panel .inventory-summary span { color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); }
+.domestic-containers-page .table-panel .inventory-summary strong { font-size: var(--admin-font-section, 14px); font-weight: 600; }
diff --git a/src/modules/domestic-containers/routes.ts b/src/modules/domestic-containers/routes.ts
new file mode 100644
index 00000000..7700008b
--- /dev/null
+++ b/src/modules/domestic-containers/routes.ts
@@ -0,0 +1,5 @@
+import type { RouteRecordRaw } from 'vue-router'
+export const domesticContainerRoutes = [
+  { path: 'domestic-containers', name: 'domestic-containers', component: () => import('./pages/DomesticContainersView.vue'), meta: { title: '整柜业务', description: '管理国内仓整柜入库、出库与库存', permission: 'platform:domestic-container:list' } },
+  { path: 'domestic-containers/inventories/:inventoryId', name: 'domestic-container-inventory-detail', component: () => import('./pages/DomesticContainerInventoryDetailView.vue'), meta: { title: '整柜库存详情', description: '查看整柜库存快照与不可变交易记录', permission: 'platform:domestic-container:list', showPageHeading: false } },
+] satisfies RouteRecordRaw[]
diff --git a/src/modules/domestic-containers/types.ts b/src/modules/domestic-containers/types.ts
new file mode 100644
index 00000000..8c8110bf
--- /dev/null
+++ b/src/modules/domestic-containers/types.ts
@@ -0,0 +1,63 @@
+export type ContainerOrderStatus = 'PENDING' | 'COMPLETED'
+export type InventoryStatus = 'IN_STOCK' | 'PARTIALLY_OUTBOUND' | 'OUTBOUND'
+export type BusinessType = 'INBOUND' | 'OUTBOUND'
+
+export interface DomesticContainerFilters {
+  page: number
+  size: number
+  warehouseId?: string
+  orderNo?: string
+  containerNo?: string
+  cargoName?: string
+  status?: string
+}
+
+export interface ContainerOrder {
+  id: number | string
+  businessType: BusinessType
+  orderNo: string
+  warehouseId: number | string
+  warehouseName: string
+  containerNo: string
+  cargoName: string
+  boxCount: number
+  volumeCbm: number
+  operationTime: string
+  status: ContainerOrderStatus
+  remark?: string | null
+  version: number
+  createdAt: string
+}
+
+export interface InventoryRecord {
+  id: number | string
+  warehouseId: number | string
+  warehouseName: string
+  containerNo: string
+  cargoName: string
+  inboundBoxes: number
+  outboundBoxes: number
+  availableBoxes: number
+  inboundVolumeCbm: number
+  inventoryStatus: InventoryStatus
+  version: number
+  updatedAt: string
+}
+
+export interface TransactionRecord {
+  id: number | string
+  businessType: BusinessType
+  orderNo: string
+  quantity: number
+  operationTime: string
+  remark?: string | null
+}
+
+export interface PageResult<T> { records: T[]; page: number; size: number; total: number; pages: number }
+export interface InventorySummary { inboundBoxes: number; outboundBoxes: number; availableBoxes: number; inboundVolumeCbm: number }
+export interface InventoryPage extends PageResult<InventoryRecord> { summary: InventorySummary }
+export interface InventoryDetail { inventory: InventoryRecord; inboundOrderCount: number; outboundOrderCount: number; transactions: TransactionRecord[] }
+
+export interface CreateResponse { id: number | string; orderNo: string; replayed: boolean }
+export interface CreateInboundRequest { warehouseId: number | string; cargoName: string; containerNo: string; boxCount: number; volumeCbm: number; inboundTime: string; status: ContainerOrderStatus; remark?: string; idempotencyKey: string }
+export interface CreateOutboundRequest { warehouseId: number | string; containerNo: string; boxCount: number; outboundTime: string; status: ContainerOrderStatus; remark?: string; idempotencyKey: string; inventoryVersion?: number }
diff --git a/src/modules/downloads/api/platformExportTasks.test.ts b/src/modules/downloads/api/platformExportTasks.test.ts
new file mode 100644
index 00000000..bdec8d78
--- /dev/null
+++ b/src/modules/downloads/api/platformExportTasks.test.ts
@@ -0,0 +1,121 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { ApiResponseError, http } from '@/shared/api/http'
+import {
+  createPlatformExportTask,
+  downloadPlatformExportTask,
+  getPlatformExportTask,
+  listPlatformExportTasks,
+  retryPlatformExportTask,
+} from './platformExportTasks'
+
+vi.mock('@/shared/api/http', async () => {
+  const actual = await vi.importActual<typeof import('@/shared/api/http')>('@/shared/api/http')
+  return { ...actual, http: { get: vi.fn(), post: vi.fn() } }
+})
+
+describe('platformExportTasks', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it('creates a backend export task with the filter snapshot', async () => {
+    const task = { id: '9', status: 'PENDING', exportType: 'CUSTOMER_LIST' }
+    vi.mocked(http.post).mockResolvedValue({ code: '200', message: 'success', data: task })
+    const payload = { exportType: 'CUSTOMER_LIST', format: 'XLSX' as const, taskName: '客户列表', parameters: { status: 'ACTIVE' } }
+
+    await expect(createPlatformExportTask(payload)).resolves.toEqual(task)
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/files/export-tasks', payload)
+  })
+
+  it('lists, reads, downloads, and retries export tasks through File service', async () => {
+    const page = { records: [], page: '1', size: '20', total: '0', pages: '0' }
+    const task = { id: '9', status: 'SUCCEEDED' }
+    const blob = new Blob(['xlsx'])
+    vi.mocked(http.get)
+      .mockResolvedValueOnce({ code: '200', message: 'success', data: page })
+      .mockResolvedValueOnce({ code: '200', message: 'success', data: task })
+      .mockResolvedValueOnce(blob)
+    vi.mocked(http.post).mockResolvedValue({ code: '200', message: 'success', data: { id: '9', status: 'PENDING' } })
+
+    await expect(listPlatformExportTasks({ page: 1, size: 20, status: 'FAILED' })).resolves.toEqual({ records: [], page: 1, size: 20, total: 0, pages: 0 })
+    await expect(getPlatformExportTask('9')).resolves.toEqual(task)
+    await expect(downloadPlatformExportTask('9')).resolves.toBe(blob)
+    await expect(retryPlatformExportTask('9')).resolves.toMatchObject({ id: '9', status: 'PENDING' })
+
+    expect(http.get).toHaveBeenNthCalledWith(1, '/platform/v1/files/export-tasks', { params: { page: 1, size: 20, status: 'FAILED' } })
+    expect(http.get).toHaveBeenNthCalledWith(2, '/platform/v1/files/export-tasks/9')
+    expect(http.get).toHaveBeenNthCalledWith(3, '/platform/v1/files/export-tasks/9/download', { responseType: 'blob', timeout: 600_000 })
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/files/export-tasks/9/retry', {})
+  })
+
+  it('parses a Blob error envelope and preserves backend trace metadata', async () => {
+    vi.mocked(http.get).mockRejectedValue({
+      isAxiosError: true,
+      response: {
+        status: 410,
+        data: new Blob([JSON.stringify({
+          code: 'FILE_EXPIRED', message: '导出文件已过期', data: null,
+          requestId: 'request-download-1', traceId: 'trace-download-1',
+        })], { type: 'application/json' }),
+      },
+    })
+
+    const error = await downloadPlatformExportTask('9').catch((reason: unknown) => reason)
+    expect(error).toBeInstanceOf(ApiResponseError)
+    expect(error).toMatchObject({
+      message: '导出文件已过期', code: 'FILE_EXPIRED', status: 410,
+      requestId: 'request-download-1', traceId: 'trace-download-1',
+    })
+  })
+
+  it('rejects an HTTP 200 business-error Blob instead of saving it as XLSX', async () => {
+    vi.mocked(http.get).mockResolvedValue(new Blob([JSON.stringify({
+      code: 'FILE_EXPIRED', message: '导出文件已过期', data: null,
+      requestId: 'request-download-200', traceId: 'trace-download-200',
+    })], { type: 'application/json;charset=UTF-8' }))
+
+    const error = await downloadPlatformExportTask('9').catch((reason: unknown) => reason)
+    expect(error).toBeInstanceOf(ApiResponseError)
+    expect(error).toMatchObject({
+      message: '导出文件已过期', code: 'FILE_EXPIRED', status: 200,
+      requestId: 'request-download-200', traceId: 'trace-download-200',
+    })
+  })
+
+  it('rejects malformed JSON download responses instead of saving them as XLSX', async () => {
+    vi.mocked(http.get).mockResolvedValue(new Blob(['{not-json'], { type: 'application/json' }))
+
+    const error = await downloadPlatformExportTask('9').catch((reason: unknown) => reason)
+    expect(error).toBeInstanceOf(ApiResponseError)
+    expect(error).toMatchObject({
+      message: '下载接口返回了无法识别的 JSON 响应',
+      code: 'INVALID_DOWNLOAD_RESPONSE',
+      status: 200,
+    })
+  })
+
+  it('rejects valid JSON values that are not API envelopes', async () => {
+    vi.mocked(http.get).mockResolvedValue(new Blob(['null'], { type: 'application/json' }))
+
+    const error = await downloadPlatformExportTask('9').catch((reason: unknown) => reason)
+    expect(error).toBeInstanceOf(ApiResponseError)
+    expect(error).toMatchObject({
+      message: '下载接口返回了无法识别的 JSON 响应',
+      code: 'INVALID_DOWNLOAD_RESPONSE',
+      status: 200,
+    })
+  })
+
+  it('rejects oversized JSON download responses without parsing or saving them', async () => {
+    vi.mocked(http.get).mockResolvedValue(new Blob(
+      ['x'.repeat(1024 * 1024 + 1)],
+      { type: 'application/problem+json' },
+    ))
+
+    const error = await downloadPlatformExportTask('9').catch((reason: unknown) => reason)
+    expect(error).toBeInstanceOf(ApiResponseError)
+    expect(error).toMatchObject({
+      message: '下载接口返回了超出限制的 JSON 响应',
+      code: 'INVALID_DOWNLOAD_RESPONSE',
+      status: 200,
+    })
+  })
+})
diff --git a/src/modules/downloads/api/platformExportTasks.ts b/src/modules/downloads/api/platformExportTasks.ts
new file mode 100644
index 00000000..c76fa186
--- /dev/null
+++ b/src/modules/downloads/api/platformExportTasks.ts
@@ -0,0 +1,158 @@
+import axios from 'axios'
+import { ApiResponseError, http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+
+export type ExportTaskStatus = 'PENDING' | 'RUNNING' | 'SUCCEEDED' | 'FAILED' | 'EXPIRED'
+export type KnownExportTaskType =
+  | 'CUSTOMER_LIST'
+  | 'DOMESTIC_WAREHOUSE_ORDER_LIST'
+  | 'FINANCE_CUSTOMER_ACCOUNT_LIST'
+  | 'FINANCE_CUSTOMER_ACCOUNT_LEDGER'
+  | 'FINANCE_FEE_SOURCE_LIST'
+  | 'FINANCE_RECONCILIATION_STATEMENT_LIST'
+  | 'FINANCE_RECEIVABLE_SETTLEMENT_LIST'
+  | 'FINANCE_RECEIVABLE_SETTLEMENT_DETAIL'
+  | 'FINANCE_PAYABLE_SETTLEMENT_LIST'
+  | 'FINANCE_PAYABLE_SETTLEMENT_DETAIL'
+export type ExportTaskType = KnownExportTaskType | (string & {})
+
+export interface PlatformExportTask {
+  id: string
+  taskNo: string
+  exportType: ExportTaskType
+  format: 'XLSX' | string
+  taskName: string
+  status: ExportTaskStatus
+  totalRows: number | null
+  processedRows: number
+  fileName: string | null
+  contentType: string | null
+  sizeBytes: number | null
+  failureMessage: string | null
+  attemptCount: number
+  maxAttempts: number
+  nextRetryAt: string | null
+  requestedBy: string
+  requestedUsername: string | null
+  requestedAt: string
+  startedAt: string | null
+  completedAt: string | null
+  expiresAt: string | null
+}
+
+export interface PlatformExportTaskPage {
+  records: PlatformExportTask[]
+  page: number
+  size: number
+  total: number
+  pages: number
+}
+
+export interface PlatformExportTaskQuery {
+  page: number
+  size: number
+  exportType?: string
+  status?: ExportTaskStatus
+  requestedFrom?: string
+  requestedTo?: string
+}
+
+export interface CreatePlatformExportTaskRequest {
+  exportType: ExportTaskType
+  format: 'XLSX'
+  taskName: string
+  parameters: Record<string, string | number | boolean | null | undefined | string[]>
+}
+
+const basePath = '/platform/v1/files/export-tasks'
+const downloadTimeoutMs = 10 * 60 * 1000
+const maxErrorEnvelopeBytes = 1024 * 1024
+
+async function parseDownloadErrorBlob(blob: Blob, status?: number): Promise<ApiResponseError | null> {
+  if (!blob.type.toLowerCase().includes('json')) return null
+
+  if (blob.size > maxErrorEnvelopeBytes) {
+    return new ApiResponseError(
+      '下载接口返回了超出限制的 JSON 响应',
+      'INVALID_DOWNLOAD_RESPONSE',
+      status,
+    )
+  }
+
+  try {
+    const payload = JSON.parse(await blob.text()) as Partial<ApiEnvelope<unknown>>
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+      return new ApiResponseError(
+        '下载接口返回了无法识别的 JSON 响应',
+        'INVALID_DOWNLOAD_RESPONSE',
+        status,
+      )
+    }
+    return new ApiResponseError(
+      payload.code === '200' ? '下载接口未返回文件内容' : payload.message || '文件下载失败',
+      payload.code === '200' ? 'INVALID_DOWNLOAD_RESPONSE' : payload.code || (status ? `HTTP_${status}` : 'DOWNLOAD_FAILED'),
+      status,
+      payload.data,
+      payload.requestId,
+      payload.traceId,
+    )
+  } catch {
+    return new ApiResponseError(
+      '下载接口返回了无法识别的 JSON 响应',
+      'INVALID_DOWNLOAD_RESPONSE',
+      status,
+    )
+  }
+}
+
+export async function createPlatformExportTask(payload: CreatePlatformExportTaskRequest) {
+  const response = await http.post<ApiEnvelope<PlatformExportTask>, ApiEnvelope<PlatformExportTask>>(basePath, payload)
+  return unwrapApiResponse(response)
+}
+
+export async function listPlatformExportTasks(query: PlatformExportTaskQuery) {
+  const response = await http.get<ApiEnvelope<PlatformExportTaskPage>, ApiEnvelope<PlatformExportTaskPage>>(basePath, {
+    params: query,
+  })
+  const page = unwrapApiResponse(response)
+  return {
+    ...page,
+    page: Number(page.page),
+    size: Number(page.size),
+    total: Number(page.total),
+    pages: Number(page.pages),
+  }
+}
+
+export async function getPlatformExportTask(taskId: string) {
+  const response = await http.get<ApiEnvelope<PlatformExportTask>, ApiEnvelope<PlatformExportTask>>(
+    `${basePath}/${encodeURIComponent(taskId)}`,
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function downloadPlatformExportTask(taskId: string) {
+  try {
+    const blob = await http.get<Blob, Blob>(`${basePath}/${encodeURIComponent(taskId)}/download`, {
+      responseType: 'blob',
+      // 导出文件上限 50 MB，不能继承普通接口的 15 秒超时，也不能无限等待半断开的连接。
+      timeout: downloadTimeoutMs,
+    })
+    const responseError = await parseDownloadErrorBlob(blob, 200)
+    if (responseError) throw responseError
+    return blob
+  } catch (error) {
+    if (axios.isAxiosError(error) && error.response?.data instanceof Blob) {
+      const responseError = await parseDownloadErrorBlob(error.response.data, error.response.status)
+      if (responseError) throw responseError
+    }
+    throw error
+  }
+}
+
+export async function retryPlatformExportTask(taskId: string) {
+  const response = await http.post<ApiEnvelope<PlatformExportTask>, ApiEnvelope<PlatformExportTask>>(
+    `${basePath}/${encodeURIComponent(taskId)}/retry`,
+    {},
+  )
+  return unwrapApiResponse(response)
+}
diff --git a/src/modules/downloads/index.ts b/src/modules/downloads/index.ts
new file mode 100644
index 00000000..f62f5ff1
--- /dev/null
+++ b/src/modules/downloads/index.ts
@@ -0,0 +1 @@
+export * from './api/platformExportTasks'
diff --git a/src/modules/downloads/pages/DownloadCenterView.test.ts b/src/modules/downloads/pages/DownloadCenterView.test.ts
new file mode 100644
index 00000000..00901441
--- /dev/null
+++ b/src/modules/downloads/pages/DownloadCenterView.test.ts
@@ -0,0 +1,293 @@
+import ElementPlus from 'element-plus'
+import { createPinia, setActivePinia } from 'pinia'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  downloadPlatformExportTask,
+  getPlatformExportTask,
+  listPlatformExportTasks,
+  retryPlatformExportTask,
+  type PlatformExportTask,
+} from '@/modules/downloads/api/platformExportTasks'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+import DownloadCenterView from './DownloadCenterView.vue'
+
+vi.mock('@/modules/downloads/api/platformExportTasks', () => ({
+  downloadPlatformExportTask: vi.fn(),
+  getPlatformExportTask: vi.fn(),
+  listPlatformExportTasks: vi.fn(),
+  retryPlatformExportTask: vi.fn(),
+}))
+
+class ResizeObserverStub implements ResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+
+const task: PlatformExportTask = {
+  id: '9', taskNo: 'EXP9', exportType: 'CUSTOMER_LIST', format: 'XLSX', taskName: '客户列表',
+  status: 'SUCCEEDED', totalRows: 12, processedRows: 12, fileName: '客户列表.xlsx',
+  contentType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', sizeBytes: 2048,
+  failureMessage: null, attemptCount: 1, maxAttempts: 3, nextRetryAt: null,
+  requestedBy: '1', requestedUsername: 'admin', requestedAt: '2026-08-03T10:00:00',
+  startedAt: '2026-08-03T10:00:01', completedAt: '2026-08-03T10:00:02', expiresAt: '2026-08-10T10:00:02',
+}
+
+enableAutoUnmount(afterEach)
+afterEach(() => vi.useRealTimers())
+
+describe('DownloadCenterView', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    document.body.innerHTML = ''
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+    Object.defineProperty(URL, 'createObjectURL', { configurable: true, value: vi.fn(() => 'blob:export') })
+    Object.defineProperty(URL, 'revokeObjectURL', { configurable: true, value: vi.fn() })
+    vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(() => {})
+    const pinia = createPinia()
+    setActivePinia(pinia)
+    const auth = useAuthStore()
+    auth.token = 'token'
+    auth.permissions = ['platform:download:list', 'platform:customer:export']
+    useAccessPreviewStore().initializeAfterLogin()
+    vi.mocked(listPlatformExportTasks).mockResolvedValue({ records: [task], page: 1, size: 20, total: 1, pages: 1 })
+    vi.mocked(downloadPlatformExportTask).mockResolvedValue(new Blob(['xlsx']))
+    vi.mocked(getPlatformExportTask).mockResolvedValue(task)
+    vi.mocked(retryPlatformExportTask).mockResolvedValue({ ...task, status: 'PENDING' })
+  })
+
+  it('lists completed tasks and downloads the backend-generated artifact', async () => {
+    const pinia = setActivePinia(createPinia())
+    const auth = useAuthStore()
+    auth.token = 'token'
+    auth.permissions = ['platform:download:list', 'platform:customer:export']
+    useAccessPreviewStore().initializeAfterLogin()
+    mount(DownloadCenterView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+
+    expect(document.body.textContent).toContain('客户列表')
+    expect(document.querySelector('.data-table')?.textContent).not.toContain('失败原因')
+    expect(document.querySelector('.data-table')?.textContent).toContain('格式')
+    expect(document.querySelector('.data-table')?.textContent).toContain('完成时间')
+    expect(document.querySelector('.data-table')?.textContent).toContain('过期时间')
+    expect(document.querySelector('.failure-cell')).toBeNull()
+    const button = [...document.querySelectorAll<HTMLButtonElement>('button')].find((item) => item.textContent?.trim() === '下载')
+    button?.click()
+    await flushPromises()
+
+    expect(downloadPlatformExportTask).toHaveBeenCalledWith('9')
+    expect(URL.createObjectURL).toHaveBeenCalled()
+    expect(HTMLAnchorElement.prototype.click).toHaveBeenCalledOnce()
+    const clickedAnchor = vi.mocked(HTMLAnchorElement.prototype.click).mock.instances[0] as HTMLAnchorElement
+    expect(clickedAnchor.download).toBe('客户列表.xlsx')
+    await new Promise((resolve) => window.setTimeout(resolve, 0))
+    expect(URL.revokeObjectURL).toHaveBeenCalledWith('blob:export')
+  })
+
+  it('shows retry for failed tasks with the source export permission', async () => {
+    vi.mocked(listPlatformExportTasks).mockResolvedValue({ records: [{ ...task, status: 'FAILED', failureMessage: 'IAM timeout' }], page: 1, size: 20, total: 1, pages: 1 })
+    const pinia = setActivePinia(createPinia())
+    const auth = useAuthStore()
+    auth.token = 'token'
+    auth.permissions = ['platform:download:list', 'platform:customer:export']
+    useAccessPreviewStore().initializeAfterLogin()
+    mount(DownloadCenterView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+
+    expect(document.querySelector('.failure-cell')).toBeNull()
+    const button = [...document.querySelectorAll<HTMLButtonElement>('button')].find((item) => item.textContent?.trim() === '重试')
+    button?.click()
+    await flushPromises()
+    expect(retryPlatformExportTask).toHaveBeenCalledWith('9')
+  })
+
+  it('shows waiting retry and allows an immediate retry during automatic backoff', async () => {
+    vi.mocked(listPlatformExportTasks).mockResolvedValue({
+      records: [{ ...task, status: 'PENDING', processedRows: 0, failureMessage: '头程服务查询失败', attemptCount: 2, nextRetryAt: '2026-09-03T10:34:28' }],
+      page: 1, size: 20, total: 1, pages: 1,
+    })
+    const pinia = setActivePinia(createPinia())
+    const auth = useAuthStore()
+    auth.token = 'token'
+    auth.permissions = ['platform:download:list', 'platform:customer:export']
+    useAccessPreviewStore().initializeAfterLogin()
+    mount(DownloadCenterView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+
+    expect(document.body.textContent).toContain('等待重试')
+    const retry = [...document.querySelectorAll<HTMLButtonElement>('button')]
+      .find((item) => item.textContent?.trim() === '立即重试')
+    retry?.click()
+    await flushPromises()
+    expect(retryPlatformExportTask).toHaveBeenCalledWith('9')
+  })
+
+  it('labels and retries Finance tasks with their exact source export permission', async () => {
+    const financeTask = {
+      ...task,
+      exportType: 'FINANCE_RECONCILIATION_STATEMENT_LIST',
+      taskName: '客户对账单',
+      status: 'FAILED' as const,
+    }
+    vi.mocked(listPlatformExportTasks).mockResolvedValue({ records: [financeTask], page: 1, size: 20, total: 1, pages: 1 })
+    const pinia = setActivePinia(createPinia())
+    const auth = useAuthStore()
+    auth.token = 'token'
+    auth.permissions = ['platform:download:list', 'platform:finance:customer-statement:export']
+    useAccessPreviewStore().initializeAfterLogin()
+    mount(DownloadCenterView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+
+    expect(document.body.textContent).toContain('客户对账单')
+    const retry = [...document.querySelectorAll<HTMLButtonElement>('button')]
+      .find((item) => item.textContent?.trim() === '重试')
+    retry?.click()
+    await flushPromises()
+    expect(retryPlatformExportTask).toHaveBeenCalledWith('9')
+  })
+
+  it('loads a fresh task detail from the backend', async () => {
+    const wrapper = mount(DownloadCenterView, { attachTo: document.body, global: { plugins: [createPinia(), ElementPlus] } })
+    await flushPromises()
+
+    const button = [...document.querySelectorAll<HTMLButtonElement>('button')]
+      .find((item) => item.textContent?.trim() === '详情')
+    button?.click()
+    await flushPromises()
+
+    expect(getPlatformExportTask).toHaveBeenCalledWith('9')
+    expect(document.body.textContent).toContain('任务详情 · EXP9')
+    expect(document.body.textContent).toContain('客户列表.xlsx')
+    expect(document.querySelector('.el-drawer')).toBeNull()
+    expect(document.querySelector('.el-dialog.admin-density-dialog')).not.toBeNull()
+    expect(document.querySelectorAll('.task-detail-grid.density-fields > div')).toHaveLength(11)
+    const detailDownload = [...document.querySelectorAll<HTMLButtonElement>('button')]
+      .find((item) => item.textContent?.trim() === '下载文件')
+    detailDownload?.click()
+    await flushPromises()
+    expect(downloadPlatformExportTask).toHaveBeenCalledWith('9')
+    wrapper.unmount()
+  })
+
+  it('renders an actionable list error and can recover', async () => {
+    vi.mocked(listPlatformExportTasks)
+      .mockRejectedValueOnce(new Error('network down'))
+      .mockResolvedValueOnce({ records: [task], page: 1, size: 20, total: 1, pages: 1 })
+    mount(DownloadCenterView, { attachTo: document.body, global: { plugins: [createPinia(), ElementPlus] } })
+    await flushPromises()
+
+    expect(document.querySelector('[role="alert"]')?.textContent).toContain('下载任务暂时无法加载')
+    const reload = [...document.querySelectorAll<HTMLButtonElement>('button')]
+      .find((item) => item.textContent?.trim() === '重新加载')
+    reload?.click()
+    await flushPromises()
+
+    expect(listPlatformExportTasks).toHaveBeenCalledTimes(2)
+    expect(document.body.textContent).toContain('共 1 个任务')
+  })
+
+  it('shows a clear empty state and hides retry without the source export permission', async () => {
+    vi.mocked(listPlatformExportTasks).mockResolvedValue({ records: [], page: 1, size: 20, total: 0, pages: 0 })
+    const pinia = setActivePinia(createPinia())
+    const auth = useAuthStore()
+    auth.token = 'token'
+    auth.permissions = ['platform:download:list']
+    useAccessPreviewStore().initializeAfterLogin()
+    mount(DownloadCenterView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+
+    expect(document.body.textContent).toContain('暂无符合筛选条件的下载任务')
+    expect([...document.querySelectorAll<HTMLButtonElement>('button')]
+      .some((item) => item.textContent?.trim() === '重试')).toBe(false)
+  })
+
+  it('keeps failure details out of the list and does not expose retry without the source export permission', async () => {
+    vi.mocked(listPlatformExportTasks).mockResolvedValue({
+      records: [{ ...task, status: 'FAILED', failureMessage: 'IAM timeout' }],
+      page: 1, size: 20, total: 1, pages: 1,
+    })
+    const pinia = setActivePinia(createPinia())
+    const auth = useAuthStore()
+    auth.token = 'token'
+    auth.permissions = ['platform:download:list']
+    useAccessPreviewStore().initializeAfterLogin()
+    vi.mocked(getPlatformExportTask).mockResolvedValue({ ...task, status: 'FAILED', failureMessage: 'IAM timeout' })
+    mount(DownloadCenterView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+
+    expect(document.body.textContent).not.toContain('IAM timeout')
+    expect([...document.querySelectorAll<HTMLButtonElement>('button')]
+      .some((item) => item.textContent?.trim() === '重试')).toBe(false)
+
+    ;[...document.querySelectorAll<HTMLButtonElement>('button')]
+      .find((item) => item.textContent?.trim() === '详情')?.click()
+    await flushPromises()
+    expect(document.body.textContent).toContain('IAM timeout')
+  })
+
+  it('announces the initial loading state while the task request is pending', async () => {
+    let resolveRequest!: (value: { records: PlatformExportTask[]; page: number; size: number; total: number; pages: number }) => void
+    vi.mocked(listPlatformExportTasks).mockReturnValue(new Promise((resolve) => { resolveRequest = resolve }))
+    const wrapper = mount(DownloadCenterView, { global: { plugins: [createPinia(), ElementPlus] } })
+    await wrapper.vm.$nextTick()
+
+    expect(wrapper.find('.table-panel').attributes('aria-busy')).toBe('true')
+    resolveRequest({ records: [], page: 1, size: 20, total: 0, pages: 0 })
+    await flushPromises()
+    expect(wrapper.find('.table-panel').attributes('aria-busy')).toBe('false')
+  })
+
+  it('does not schedule another refresh after an in-flight load finishes on an unmounted page', async () => {
+    vi.useFakeTimers()
+    let resolveRequest!: (value: { records: PlatformExportTask[]; page: number; size: number; total: number; pages: number }) => void
+    vi.mocked(listPlatformExportTasks).mockReturnValue(new Promise((resolve) => { resolveRequest = resolve }))
+    const wrapper = mount(DownloadCenterView, { global: { plugins: [createPinia(), ElementPlus] } })
+
+    wrapper.unmount()
+    resolveRequest({ records: [{ ...task, status: 'RUNNING' }], page: 1, size: 20, total: 1, pages: 1 })
+    await flushPromises()
+    await vi.advanceTimersByTimeAsync(5000)
+
+    expect(listPlatformExportTasks).toHaveBeenCalledTimes(1)
+  })
+
+  it('keeps the last successful task list and continues polling after a background refresh failure', async () => {
+    vi.useFakeTimers()
+    vi.mocked(listPlatformExportTasks)
+      .mockResolvedValueOnce({ records: [{ ...task, status: 'RUNNING', processedRows: 3 }], page: 1, size: 20, total: 1, pages: 1 })
+      .mockRejectedValueOnce(new Error('temporary network failure'))
+      .mockResolvedValueOnce({ records: [{ ...task, status: 'SUCCEEDED', processedRows: 12 }], page: 1, size: 20, total: 1, pages: 1 })
+    mount(DownloadCenterView, { attachTo: document.body, global: { plugins: [createPinia(), ElementPlus] } })
+    await flushPromises()
+
+    await vi.advanceTimersByTimeAsync(5000)
+    await flushPromises()
+    expect(document.body.textContent).toContain('自动刷新暂时失败')
+    expect(document.body.textContent).toContain('客户列表')
+
+    await vi.advanceTimersByTimeAsync(5000)
+    await flushPromises()
+    expect(listPlatformExportTasks).toHaveBeenCalledTimes(3)
+    expect(document.body.textContent).not.toContain('自动刷新暂时失败')
+  })
+
+  it('updates an open task detail from the latest polling result', async () => {
+    vi.useFakeTimers()
+    vi.mocked(listPlatformExportTasks)
+      .mockResolvedValueOnce({ records: [{ ...task, status: 'RUNNING', processedRows: 3 }], page: 1, size: 20, total: 1, pages: 1 })
+      .mockResolvedValueOnce({ records: [{ ...task, status: 'SUCCEEDED', processedRows: 12 }], page: 1, size: 20, total: 1, pages: 1 })
+    vi.mocked(getPlatformExportTask).mockResolvedValue({ ...task, status: 'RUNNING', processedRows: 3 })
+    mount(DownloadCenterView, { attachTo: document.body, global: { plugins: [createPinia(), ElementPlus] } })
+    await flushPromises()
+    ;[...document.querySelectorAll<HTMLButtonElement>('button')]
+      .find((item) => item.textContent?.trim() === '详情')?.click()
+    await flushPromises()
+    expect(document.body.textContent).toContain('3 / 12 行')
+
+    await vi.advanceTimersByTimeAsync(5000)
+    await flushPromises()
+    expect(document.body.textContent).toContain('12 / 12 行')
+  })
+})
diff --git a/src/modules/downloads/pages/DownloadCenterView.vue b/src/modules/downloads/pages/DownloadCenterView.vue
new file mode 100644
index 00000000..3f887a34
--- /dev/null
+++ b/src/modules/downloads/pages/DownloadCenterView.vue
@@ -0,0 +1,399 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import { ElMessage } from 'element-plus'
+import { getApiErrorDetails, getApiErrorMessage, type ApiErrorDetails } from '@/shared/api/http'
+import {
+  downloadPlatformExportTask,
+  getPlatformExportTask,
+  listPlatformExportTasks,
+  retryPlatformExportTask,
+  type ExportTaskStatus,
+  type PlatformExportTask,
+} from '@/modules/downloads/api/platformExportTasks'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+
+type DownloadFilters = QueryModel & {
+  exportType: string
+  status: ExportTaskStatus | ''
+  requestedRange: string[]
+}
+
+const exportTypeMeta: Record<string, { label: string; retryPermission: string }> = {
+  CUSTOMER_LIST: { label: '客户列表', retryPermission: 'platform:customer:export' },
+  DOMESTIC_WAREHOUSE_ORDER_LIST: { label: '国内仓订单列表', retryPermission: 'platform:order:export' },
+  FINANCE_CUSTOMER_ACCOUNT_LIST: { label: '客户账户', retryPermission: 'platform:finance:customer-account:export' },
+  FINANCE_CUSTOMER_ACCOUNT_LEDGER: { label: '客户账户流水', retryPermission: 'platform:finance:customer-account:export' },
+  FINANCE_FEE_SOURCE_LIST: { label: '客户应收应付费用来源', retryPermission: 'platform:finance:customer-arap:export' },
+  FINANCE_RECONCILIATION_STATEMENT_LIST: { label: '客户对账单', retryPermission: 'platform:finance:customer-statement:export' },
+  FINANCE_RECEIVABLE_SETTLEMENT_LIST: { label: '应收结算单列表', retryPermission: 'platform:finance:settlement-ar:export' },
+  FINANCE_RECEIVABLE_SETTLEMENT_DETAIL: { label: '应收结算单详情', retryPermission: 'platform:finance:settlement-ar:export' },
+  FINANCE_PAYABLE_SETTLEMENT_LIST: { label: '应付结算单列表', retryPermission: 'platform:finance:settlement-ap:export' },
+  FINANCE_PAYABLE_SETTLEMENT_DETAIL: { label: '应付结算单详情', retryPermission: 'platform:finance:settlement-ap:export' },
+}
+
+const access = useAccessPreviewStore()
+const page = ref(1)
+const pageSize = ref(20)
+const loading = ref(false)
+const downloadingId = ref('')
+const retryingId = ref('')
+const loadError = ref<ApiErrorDetails | null>(null)
+const syncWarning = ref<ApiErrorDetails | null>(null)
+const detailOpen = ref(false)
+const detailLoading = ref(false)
+const detailError = ref<ApiErrorDetails | null>(null)
+const detailTask = ref<PlatformExportTask | null>(null)
+const result = ref({ records: [] as PlatformExportTask[], total: 0, pages: 0 })
+const filters = ref<DownloadFilters>({ exportType: '', status: '', requestedRange: [] })
+let refreshTimer: number | undefined
+let disposed = false
+let loadRequestId = 0
+let detailRequestId = 0
+
+const queryFields: QueryField[] = [
+  { key: 'exportType', type: 'select', label: '任务类型', placeholder: '全部任务类型', options: [
+    ...Object.entries(exportTypeMeta).map(([value, meta]) => ({ label: meta.label, value })),
+  ] },
+  { key: 'status', type: 'select', label: '任务状态', placeholder: '全部任务状态', options: [
+    { label: '等待处理', value: 'PENDING' }, { label: '处理中', value: 'RUNNING' },
+    { label: '已完成', value: 'SUCCEEDED' }, { label: '失败', value: 'FAILED' },
+    { label: '已过期', value: 'EXPIRED' },
+  ] },
+  { key: 'requestedRange', type: 'daterange', label: '申请日期', placeholder: '请选择申请日期' },
+]
+
+const columns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 210, fixed: 'left', slotName: 'actions' },
+  { key: 'taskName', prop: 'taskName', label: '任务名称', minWidth: 180, showOverflowTooltip: true },
+  { key: 'type', label: '任务类型', width: 120, slotName: 'type' },
+  { key: 'status', label: '状态', width: 110, slotName: 'status' },
+  { key: 'progress', label: '数据量', width: 120, slotName: 'progress' },
+  { key: 'format', prop: 'format', label: '格式', width: 80 },
+  { key: 'requester', label: '申请人', minWidth: 130, slotName: 'requester' },
+  { key: 'requestedAt', label: '申请时间', width: 170, slotName: 'requestedAt' },
+  { key: 'completedAt', label: '完成时间', width: 170, slotName: 'completedAt' },
+  { key: 'expiresAt', label: '过期时间', width: 170, slotName: 'expiresAt' },
+]
+
+const hasActiveTasks = computed(() => result.value.records.some((task) => ['PENDING', 'RUNNING'].includes(task.status)))
+
+function clearRefreshTimer() {
+  if (refreshTimer !== undefined) window.clearTimeout(refreshTimer)
+  refreshTimer = undefined
+}
+
+function scheduleRefresh() {
+  clearRefreshTimer()
+  if (!disposed && hasActiveTasks.value) refreshTimer = window.setTimeout(() => { void loadTasks(true) }, 5000)
+}
+
+async function loadTasks(background = false) {
+  const requestId = ++loadRequestId
+  clearRefreshTimer()
+  if (!background) loading.value = true
+  if (!background) loadError.value = null
+  try {
+    const range = filters.value.requestedRange
+    const response = await listPlatformExportTasks({
+      page: page.value,
+      size: pageSize.value,
+      exportType: filters.value.exportType || undefined,
+      status: filters.value.status || undefined,
+      requestedFrom: range?.[0] || undefined,
+      requestedTo: range?.[1] || undefined,
+    })
+    if (disposed || requestId !== loadRequestId) return
+    result.value = { records: response.records, total: response.total, pages: response.pages }
+    loadError.value = null
+    syncWarning.value = null
+    if (detailOpen.value && detailTask.value) {
+      const freshDetail = response.records.find((task) => task.id === detailTask.value?.id)
+      if (freshDetail) detailTask.value = freshDetail
+    }
+  } catch (error) {
+    if (disposed || requestId !== loadRequestId) return
+    const details = getApiErrorDetails(error, '下载任务加载失败')
+    if (background && result.value.records.length > 0) syncWarning.value = details
+    else loadError.value = details
+  } finally {
+    if (!disposed && requestId === loadRequestId) {
+      if (!background) loading.value = false
+      scheduleRefresh()
+    }
+  }
+}
+
+function applyFilters() {
+  if (page.value === 1) void loadTasks()
+  else page.value = 1
+}
+
+async function openDetail(task: PlatformExportTask) {
+  if (!task?.id) return
+  const requestId = ++detailRequestId
+  detailTask.value = task
+  detailError.value = null
+  detailOpen.value = true
+  detailLoading.value = true
+  try {
+    const response = await getPlatformExportTask(task.id)
+    if (disposed || requestId !== detailRequestId) return
+    detailTask.value = response
+  } catch (error) {
+    if (disposed || requestId !== detailRequestId) return
+    detailError.value = getApiErrorDetails(error, '下载任务详情加载失败')
+  } finally {
+    if (!disposed && requestId === detailRequestId) detailLoading.value = false
+  }
+}
+
+function closeDetail() {
+  detailRequestId += 1
+  detailTask.value = null
+  detailError.value = null
+  detailLoading.value = false
+}
+
+function downloadDetailTask() {
+  if (detailTask.value?.status === 'SUCCEEDED') void downloadTask(detailTask.value)
+}
+
+async function downloadTask(task: PlatformExportTask) {
+  downloadingId.value = task.id
+  try {
+    const blob = await downloadPlatformExportTask(task.id)
+    const url = URL.createObjectURL(blob)
+    const anchor = document.createElement('a')
+    try {
+      anchor.href = url
+      anchor.download = safeFileName(task.fileName || `${task.taskName}.xlsx`)
+      document.body.append(anchor)
+      anchor.click()
+    } finally {
+      anchor.remove()
+      window.setTimeout(() => URL.revokeObjectURL(url), 0)
+    }
+  } catch (error) {
+    const details = getApiErrorDetails(error, '文件下载失败，请刷新任务状态后重试')
+    const trace = [details.code, details.requestId && `requestId: ${details.requestId}`, details.traceId && `traceId: ${details.traceId}`]
+      .filter(Boolean)
+      .join('，')
+    ElMessage.error(trace ? `${details.message}（${trace}）` : details.message)
+  } finally {
+    downloadingId.value = ''
+  }
+}
+
+async function retryTask(task: PlatformExportTask) {
+  retryingId.value = task.id
+  try {
+    await retryPlatformExportTask(task.id)
+    ElMessage.success('导出任务已重新提交')
+    await loadTasks()
+  } catch (error) {
+    ElMessage.error(getApiErrorMessage(error, '任务重试失败'))
+  } finally {
+    retryingId.value = ''
+  }
+}
+
+function safeFileName(value: string) {
+  const safe = value.replace(/[\\/:*?"<>|\u0000-\u001f]/g, '_').trim()
+  return safe || '导出文件.xlsx'
+}
+
+function typeLabel(type: string) { return exportTypeMeta[type]?.label || type }
+
+function statusMeta(status: ExportTaskStatus) {
+  const values = {
+    PENDING: { label: '等待处理', type: 'info' as const },
+    RUNNING: { label: '处理中', type: 'warning' as const },
+    SUCCEEDED: { label: '已完成', type: 'success' as const },
+    FAILED: { label: '失败', type: 'danger' as const },
+    EXPIRED: { label: '已过期', type: 'info' as const },
+  }
+  return values[status] ?? { label: status || '未知状态', type: 'info' as const }
+}
+
+function taskStatusMeta(task: PlatformExportTask) {
+  if (task.status === 'PENDING' && task.attemptCount > 0) {
+    return { label: '等待重试', type: 'warning' as const }
+  }
+  return statusMeta(task.status)
+}
+
+function formatDate(value: string | null) {
+  if (!value) return '—'
+  const date = new Date(value)
+  return Number.isNaN(date.getTime()) ? value : date.toLocaleString('zh-CN', { hour12: false })
+}
+
+function formatSize(bytes: number | null) {
+  if (bytes === null) return ''
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`
+}
+
+function canRetry(task: PlatformExportTask) {
+  const permission = exportTypeMeta[task.exportType]?.retryPermission
+  const retryableStatus = task.status === 'FAILED' || (task.status === 'PENDING' && task.attemptCount > 0)
+  return retryableStatus && permission !== undefined && access.can(permission)
+}
+
+function retryLabel(task: PlatformExportTask) {
+  return task.status === 'PENDING' ? '立即重试' : '重试'
+}
+
+watch([page, pageSize], () => { void loadTasks() })
+onMounted(loadTasks)
+onBeforeUnmount(() => {
+  disposed = true
+  loadRequestId += 1
+  detailRequestId += 1
+  clearRefreshTimer()
+})
+</script>
+
+<template>
+  <AdminPage class="admin-density">
+  <div class="business-page download-center-page">
+    <ListPageLayout ariaLabel="下载任务列表">
+      <template #toolbar>
+        <QueryToolbar v-model="filters" class="surface-panel" ariaLabel="下载任务筛选" :fields="queryFields" preference-key="downloads-query" @search="applyFilters" />
+      </template>
+
+      <template v-if="loadError" #state>
+        <section class="surface-panel download-error" role="alert">
+          <div><strong>下载任务暂时无法加载</strong><p>{{ loadError.message }}</p><ApiErrorMeta :details="loadError" /></div>
+          <el-button type="primary" :loading="loading" @click="loadTasks()">重新加载</el-button>
+        </section>
+      </template>
+
+    <section v-if="!loadError" class="surface-panel table-panel" :aria-busy="loading">
+      <div v-if="syncWarning" class="download-sync-warning" role="status">
+        <span>自动刷新暂时失败，正在保留当前任务并继续重试：{{ syncWarning.message }}</span>
+        <ApiErrorMeta :details="syncWarning" />
+      </div>
+      <DataTable v-model:page="page" v-model:page-size="pageSize" :data="result.records" :columns="columns" preference-key="downloads-table" :loading="loading" :total="result.total" row-key="id" empty-text="暂无符合筛选条件的下载任务" aria-label="下载任务列表">
+        <template #pagination-left="{ total: tableTotal }"><span>共 {{ tableTotal }} 个任务</span></template>
+        <template #actions="{ row }"><div class="table-actions density-actions">
+          <el-button data-tone="neutral" class="density-action" v-if="(row as PlatformExportTask)?.id" @click="openDetail(row as PlatformExportTask)">详情</el-button>
+          <el-button data-tone="neutral" class="density-action" v-if="(row as PlatformExportTask).status === 'SUCCEEDED'" :loading="downloadingId === (row as PlatformExportTask).id" @click="downloadTask(row as PlatformExportTask)">下载</el-button>
+          <el-button data-tone="neutral" class="density-action" v-if="canRetry(row as PlatformExportTask)" :loading="retryingId === (row as PlatformExportTask).id" @click="retryTask(row as PlatformExportTask)">{{ retryLabel(row as PlatformExportTask) }}</el-button>
+        </div></template>
+        <template #type="{ row }">{{ typeLabel((row as PlatformExportTask).exportType) }}</template>
+        <template #status="{ row }"><el-tag :type="taskStatusMeta(row as PlatformExportTask).type" effect="light">{{ taskStatusMeta(row as PlatformExportTask).label }}</el-tag></template>
+        <template #progress="{ row }"><span>{{ (row as PlatformExportTask).processedRows }}<template v-if="(row as PlatformExportTask).totalRows !== null"> / {{ (row as PlatformExportTask).totalRows }}</template></span><small v-if="(row as PlatformExportTask).sizeBytes !== null">{{ formatSize((row as PlatformExportTask).sizeBytes) }}</small></template>
+        <template #requester="{ row }">{{ (row as PlatformExportTask).requestedUsername || (row as PlatformExportTask).requestedBy }}</template>
+        <template #requestedAt="{ row }">{{ formatDate((row as PlatformExportTask).requestedAt) }}</template>
+        <template #completedAt="{ row }">{{ formatDate((row as PlatformExportTask).completedAt) }}</template>
+        <template #expiresAt="{ row }">{{ formatDate((row as PlatformExportTask).expiresAt) }}</template>
+      </DataTable>
+    </section>
+    </ListPageLayout>
+
+    <AppDialog class="admin-density-dialog"
+      v-model="detailOpen"
+      :title="detailTask ? `任务详情 · ${detailTask.taskNo}` : '任务详情'"
+      width="min(720px, calc(100vw - 28px))"
+      :loading="detailLoading"
+      :show-confirm="false"
+      destroy-on-close
+      @closed="closeDetail"
+    >
+      <section v-if="detailError" class="detail-load-error" role="alert">
+        <strong>任务详情暂时无法加载</strong>
+        <p>{{ detailError.message }}</p>
+        <ApiErrorMeta :details="detailError" />
+        <el-button type="primary" @click="detailTask && openDetail(detailTask)">重新加载</el-button>
+      </section>
+      <div v-else-if="detailTask" class="task-detail">
+        <div class="task-detail-summary">
+          <div>
+            <h3>{{ detailTask.taskName }}</h3>
+            <p>{{ typeLabel(detailTask.exportType) }} · {{ detailTask.format }}</p>
+          </div>
+          <el-tag :type="taskStatusMeta(detailTask).type" effect="light">{{ taskStatusMeta(detailTask).label }}</el-tag>
+        </div>
+        <dl class="task-detail-grid density-fields">
+          <div><dt>任务编号</dt><dd>{{ detailTask.taskNo }}</dd></div>
+          <div><dt>申请人</dt><dd>{{ detailTask.requestedUsername || detailTask.requestedBy }}</dd></div>
+          <div><dt>申请时间</dt><dd>{{ formatDate(detailTask.requestedAt) }}</dd></div>
+          <div><dt>开始时间</dt><dd>{{ formatDate(detailTask.startedAt) }}</dd></div>
+          <div><dt>完成时间</dt><dd>{{ formatDate(detailTask.completedAt) }}</dd></div>
+          <div><dt>执行次数</dt><dd>{{ detailTask.attemptCount }} / {{ detailTask.maxAttempts }}</dd></div>
+          <div><dt>下次重试</dt><dd>{{ detailTask.status === 'PENDING' && detailTask.attemptCount > 0 ? formatDate(detailTask.nextRetryAt) : '—' }}</dd></div>
+          <div><dt>过期时间</dt><dd>{{ formatDate(detailTask.expiresAt) }}</dd></div>
+          <div><dt>处理数据</dt><dd>{{ detailTask.processedRows }}<template v-if="detailTask.totalRows !== null"> / {{ detailTask.totalRows }}</template> 行</dd></div>
+          <div><dt>文件大小</dt><dd>{{ formatSize(detailTask.sizeBytes) || '—' }}</dd></div>
+          <div class="is-wide"><dt>文件名称</dt><dd>{{ detailTask.fileName || '—' }}</dd></div>
+        </dl>
+        <section v-if="detailTask.failureMessage" class="task-failure" role="status">
+          <strong>失败原因</strong>
+          <p>{{ detailTask.failureMessage }}</p>
+        </section>
+      </div>
+      <template #footer="{ close }">
+        <div class="app-dialog__footer">
+          <el-button @click="close">关闭</el-button>
+          <el-button
+            v-if="detailTask && canRetry(detailTask)"
+            :loading="retryingId === detailTask.id"
+            @click="retryTask(detailTask)"
+          >{{ retryLabel(detailTask) }}</el-button>
+          <el-button
+            type="primary"
+            :loading="downloadingId === detailTask?.id"
+            :disabled="detailTask?.status !== 'SUCCEEDED'"
+            @click="downloadDetailTask"
+          >下载文件</el-button>
+        </div>
+      </template>
+    </AppDialog>
+  </div>
+  </AdminPage>
+</template>
+
+<style scoped>
+.task-detail-grid.density-fields { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+.task-detail-grid .is-wide { grid-column: 1 / -1; }
+.download-center-page { min-width: 0; }
+.download-error { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-6); }
+.download-error { padding: var(--admin-space-6); }
+.download-error strong { color: var(--cc-danger); font-size: var(--admin-font-body); }
+.download-error p { margin: 5px 0; color: var(--cc-text); font-size: var(--admin-font-body); }
+.download-sync-warning { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-5); padding: var(--admin-space-4) var(--admin-space-6); border-bottom: 1px solid #fedf89; background: #fffaeb; color: #93370d; font-size: var(--admin-font-caption); }
+.failure-cell { display: block; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.failure-message { color: var(--cc-danger); }
+.detail-load-error { display: flex; min-height: 220px; align-items: flex-start; justify-content: center; flex-direction: column; }
+.detail-load-error strong { color: var(--cc-danger); font-size: var(--admin-font-section); }
+.detail-load-error p { margin: var(--admin-space-2) 0; color: var(--cc-text); font-size: var(--admin-font-body); }
+.detail-load-error :deep(.el-button) { margin-top: var(--admin-space-6); }
+.task-detail { min-width: 0; }
+.task-detail-summary { display: flex; align-items: flex-start; justify-content: space-between; gap: var(--admin-space-6); padding-bottom: var(--admin-space-6); border-bottom: 1px solid var(--cc-border); }
+.task-detail-summary h3 { margin: 0; overflow-wrap: anywhere; color: var(--cc-text); font-size: var(--admin-font-section); }
+.task-detail-summary p { margin: var(--admin-space-2) 0 0; color: var(--cc-muted); font-size: var(--admin-font-caption); }
+.task-failure { margin-top: var(--admin-space-6); padding: var(--admin-space-5); border: 1px solid color-mix(in srgb, var(--cc-danger) 24%, var(--cc-border)); border-radius: var(--admin-radius); background: color-mix(in srgb, var(--cc-danger) 5%, #fff); }
+.task-failure strong { color: var(--cc-danger); font-size: var(--admin-font-body); }
+.task-failure p { margin: var(--admin-space-2) 0 0; overflow-wrap: anywhere; color: var(--cc-text); font-size: var(--admin-font-body); line-height: 1.6; }
+small { display: block; margin-top: 3px; color: var(--cc-muted); font-size: var(--admin-font-caption); }
+@media (max-width: 720px) {
+  .download-error, .download-sync-warning { align-items: stretch; flex-direction: column; }
+  .table-actions :deep(.el-button) { min-height: 44px; }
+  .table-actions :deep(.el-button) { padding-right: 8px; padding-left: 8px; }
+}
+@media (max-width: 480px) {
+  .task-detail-summary { flex-direction: column; }
+  .task-detail-grid { grid-template-columns: 1fr; }
+  .task-detail-grid > div:nth-child(odd):not(.is-wide) { border-right: 0; }
+  .task-detail-grid .is-wide { grid-column: 1; }
+}
+</style>
diff --git a/src/modules/downloads/routes.ts b/src/modules/downloads/routes.ts
new file mode 100644
index 00000000..de752c1e
--- /dev/null
+++ b/src/modules/downloads/routes.ts
@@ -0,0 +1,10 @@
+import type { RouteRecordRaw } from 'vue-router'
+
+export const downloadRoutes = [
+  {
+    path: 'downloads',
+    name: 'download-center',
+    component: () => import('@/modules/downloads/pages/DownloadCenterView.vue'),
+    meta: { title: '下载中心', description: '查看异步导出任务并下载已生成文件', permission: 'platform:download:list' },
+  },
+] satisfies RouteRecordRaw[]
diff --git a/src/modules/fba-pricing/carrier-rates/api/platformPriceBooks.test.ts b/src/modules/fba-pricing/carrier-rates/api/platformPriceBooks.test.ts
new file mode 100644
index 00000000..43216167
--- /dev/null
+++ b/src/modules/fba-pricing/carrier-rates/api/platformPriceBooks.test.ts
@@ -0,0 +1,155 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const http = vi.hoisted(() => ({
+  get: vi.fn(),
+  post: vi.fn(),
+}))
+
+vi.mock('@/shared/api/http', () => ({
+  http,
+  unwrapApiResponse: <T>(response: { data: T }) => response.data,
+}))
+
+import {
+  downloadPlatformPriceBookSource,
+  getPlatformPriceBook,
+  listPlatformPriceBooks,
+  publishPlatformPriceBook,
+  uploadPlatformPriceBook,
+} from './platformPriceBooks'
+
+const version = {
+  id: '9007199254740995',
+  customerId: '2096953508805279745',
+  versionNo: '2',
+  originalFileName: '2026-08-price-book.xlsx',
+  sourceFileId: '9007199254740996',
+  sourceSha256: 'a'.repeat(64),
+  status: 'PENDING_CONFIRMATION' as const,
+  channelCount: '15',
+  rateCount: '42',
+  blockingErrorCount: '2',
+  warningCount: 1,
+  parseIssuesJson: null,
+  createdBy: '10001',
+  createdAt: '2026-08-07T10:00:00',
+  publishedBy: null,
+  publishedAt: null,
+  supersededAt: null,
+}
+
+const detail = {
+  version,
+  channels: [{
+    channelCode: 'MASON_TRUCK',
+    channelName: '美森正班海卡',
+    priceModel: 'FBA_WAREHOUSE_RATE' as const,
+    sourceSheetName: '美森正班海卡',
+    estimatedDepartureDate: '2026-08-12',
+    estimatedDepartureText: '8月12日',
+    latestWarehouseEntry: null,
+    vesselName: null,
+    voyageNo: null,
+    referenceTransit: null,
+    surchargeDescription: null,
+    remark: null,
+  }],
+  rates: [{
+    id: '9007199254740997',
+    channelCode: 'MASON_TRUCK',
+    priceModel: 'FBA_WAREHOUSE_RATE' as const,
+    originWarehouseId: null,
+    originWarehouseCode: 'CN-YIWU-01',
+    originWarehouseName: '义乌仓',
+    destinationType: 'OVERSEAS' as const,
+    destinationCode: 'US-LAX-01',
+    destinationWarehouseId: null,
+    destinationName: '洛杉矶仓',
+    regionCode: null,
+    pricingTaxMode: 'TAX_INCLUDED' as const,
+    chargeUnit: 'KG' as const,
+    weightFromKg: null,
+    unitPrice: '12.5',
+    currency: 'CNY',
+    sourceSheetName: '美森正班海卡',
+    sourceRowNumber: '8',
+    sourceDestinationText: '洛杉矶仓',
+    remark: null,
+  }],
+  issues: [{
+    severity: 'BLOCKING',
+    issueCode: 'ORIGIN_MAPPING_REQUIRED',
+    message: '起运仓需要映射到平台国内仓',
+    sourceSheetName: '美森正班海卡',
+    sourceRowNumber: '8',
+    sourceCell: null,
+  }],
+}
+
+describe('platform price-book API', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it('uses the selected customer price-book scope and preserves long ids', async () => {
+    http.get.mockResolvedValue({ data: [version] })
+
+    const result = await listPlatformPriceBooks({ customerId: '2096953508805279745', status: ' PENDING_CONFIRMATION ' })
+
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/fba-pricing/carrier-rates/price-books', {
+      params: { customerId: '2096953508805279745', status: 'PENDING_CONFIRMATION' },
+    })
+    expect(result[0]).toMatchObject({
+      id: '9007199254740995',
+      customerId: '2096953508805279745',
+      sourceFileId: '9007199254740996',
+      createdBy: '10001',
+      versionNo: 2,
+      rateCount: 42,
+    })
+  })
+
+  it('defaults an empty scope to the public price-book history', async () => {
+    http.get.mockResolvedValue({ data: [] })
+
+    await listPlatformPriceBooks({ status: ' ' })
+
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/fba-pricing/carrier-rates/price-books', { params: { customerId: '0' } })
+  })
+
+  it('uploads one workbook, loads its parsed detail, and normalizes parsed rows', async () => {
+    http.post.mockResolvedValue({ data: detail })
+    http.get.mockResolvedValue({ data: detail })
+    const file = new File(['book'], 'price-book.xlsx', { type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' })
+
+    const uploadResult = await uploadPlatformPriceBook(file, '2096953508805279745')
+    const detailResult = await getPlatformPriceBook('9007199254740995')
+
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/fba-pricing/carrier-rates/price-books', expect.any(FormData), {
+      params: { customerId: '2096953508805279745' },
+    })
+    const form = http.post.mock.calls[0][1] as FormData
+    expect(form.get('file')).toBe(file)
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/fba-pricing/carrier-rates/price-books/9007199254740995')
+    expect(uploadResult.rates[0]).toMatchObject({ id: '9007199254740997', unitPrice: 12.5, sourceRowNumber: 8 })
+    expect(detailResult.issues[0].sourceRowNumber).toBe(8)
+  })
+
+  it('publishes only confirmed warehouse mappings and downloads the original workbook', async () => {
+    http.post.mockResolvedValue({ data: detail })
+    const request = {
+      originMappings: [{ originWarehouseCode: 'CN-YIWU-01', warehouseId: '20001' }],
+      overseasMappings: [{ sourceDestinationName: '洛杉矶仓', warehouseId: '20011' }],
+    }
+
+    await publishPlatformPriceBook('9007199254740995', request)
+    await downloadPlatformPriceBookSource('9007199254740995')
+
+    expect(http.post).toHaveBeenCalledWith(
+      '/platform/v1/fba-pricing/carrier-rates/price-books/9007199254740995/publish',
+      request,
+    )
+    expect(http.get).toHaveBeenCalledWith(
+      '/platform/v1/fba-pricing/carrier-rates/price-books/9007199254740995/source',
+      { responseType: 'blob' },
+    )
+  })
+})
diff --git a/src/modules/fba-pricing/carrier-rates/api/platformPriceBooks.ts b/src/modules/fba-pricing/carrier-rates/api/platformPriceBooks.ts
new file mode 100644
index 00000000..20bd6333
--- /dev/null
+++ b/src/modules/fba-pricing/carrier-rates/api/platformPriceBooks.ts
@@ -0,0 +1,291 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+
+export type PriceBookStatus = 'PENDING_CONFIRMATION' | 'ACTIVE' | 'SUPERSEDED' | 'VOIDED' | 'FAILED'
+export type PriceModel = 'FBA_WAREHOUSE_RATE' | 'REGION_WEIGHT_TIER'
+export type PricingTaxMode = 'TAX_INCLUDED' | 'TAX_EXCLUDED'
+export type PricingDestinationType = 'FBA' | 'OVERSEAS'
+export type PriceBookChargeUnit = 'KG' | 'CBM'
+
+type ApiId = string | number
+type ApiNumber = string | number
+
+export interface PlatformPriceBookVersion {
+  id: string
+  customerId: string
+  versionNo: number
+  originalFileName: string
+  sourceFileId: string | null
+  sourceSha256: string | null
+  status: PriceBookStatus
+  channelCount: number
+  rateCount: number
+  blockingErrorCount: number
+  warningCount: number
+  parseIssuesJson: string | null
+  createdBy: string | null
+  createdAt: string | null
+  publishedBy: string | null
+  publishedAt: string | null
+  supersededAt: string | null
+  voidedBy: string | null
+  voidedAt: string | null
+  voidReason: string | null
+}
+
+/** Read-only channel data parsed from the uploaded workbook. */
+export interface PlatformPriceBookParsedChannel {
+  channelCode: string
+  channelName: string
+  priceModel: PriceModel
+  sourceSheetName: string
+  estimatedDepartureDate: string | null
+  estimatedDepartureText: string | null
+  latestWarehouseEntry: string | null
+  vesselName: string | null
+  voyageNo: string | null
+  referenceTransit: string | null
+  surchargeDescription: string | null
+  remark: string | null
+}
+
+/** Read-only price row parsed from the uploaded workbook. */
+export interface PlatformPriceBookParsedRate {
+  id: string | null
+  channelCode: string
+  priceModel: PriceModel
+  originWarehouseId: string | null
+  originWarehouseCode: string
+  originWarehouseName: string
+  destinationType: PricingDestinationType | null
+  destinationCode: string | null
+  destinationWarehouseId: string | null
+  destinationName: string | null
+  regionCode: string | null
+  pricingTaxMode: PricingTaxMode | null
+  chargeUnit: PriceBookChargeUnit
+  weightFromKg: number | null
+  unitPrice: number
+  currency: string
+  sourceSheetName: string
+  sourceRowNumber: number
+  sourceDestinationText: string | null
+  remark: string | null
+}
+
+export interface PlatformPriceBookParseIssue {
+  severity: 'BLOCKING' | 'WARNING' | string
+  issueCode: string
+  message: string
+  sourceSheetName: string | null
+  sourceRowNumber: number | null
+  sourceCell: string | null
+}
+
+export interface PlatformPriceBookDetail {
+  version: PlatformPriceBookVersion
+  channels: PlatformPriceBookParsedChannel[]
+  rates: PlatformPriceBookParsedRate[]
+  issues: PlatformPriceBookParseIssue[]
+}
+
+export interface PriceBookConfirmationRequest {
+  originMappings: Array<{
+    originWarehouseCode: string
+    warehouseId: string
+  }>
+  overseasMappings: Array<{
+    sourceDestinationName: string
+    warehouseId: string
+  }>
+}
+
+export interface PlatformPriceBookQuery {
+  customerId?: string
+  status?: PriceBookStatus | string
+}
+
+interface PriceBookVersionPayload extends Omit<PlatformPriceBookVersion,
+  'id' | 'customerId' | 'versionNo' | 'sourceFileId' | 'channelCount' | 'rateCount' | 'blockingErrorCount' | 'warningCount' | 'createdBy' | 'publishedBy' | 'voidedBy'> {
+  id: ApiId
+  customerId: ApiId
+  versionNo: ApiNumber
+  sourceFileId?: ApiId | null
+  channelCount?: ApiNumber | null
+  rateCount?: ApiNumber | null
+  blockingErrorCount?: ApiNumber | null
+  warningCount?: ApiNumber | null
+  createdBy?: ApiId | null
+  publishedBy?: ApiId | null
+  voidedBy?: ApiId | null
+}
+
+interface PriceBookParsedChannelPayload extends Omit<PlatformPriceBookParsedChannel,
+  'estimatedDepartureDate' | 'estimatedDepartureText' | 'latestWarehouseEntry' | 'vesselName' | 'voyageNo'
+  | 'referenceTransit' | 'surchargeDescription' | 'remark'> {
+  estimatedDepartureDate?: string | null
+  estimatedDepartureText?: string | null
+  latestWarehouseEntry?: string | null
+  vesselName?: string | null
+  voyageNo?: string | null
+  referenceTransit?: string | null
+  surchargeDescription?: string | null
+  remark?: string | null
+}
+
+interface PriceBookParsedRatePayload extends Omit<PlatformPriceBookParsedRate,
+  'id' | 'originWarehouseId' | 'destinationWarehouseId' | 'weightFromKg' | 'unitPrice' | 'sourceRowNumber'> {
+  id?: ApiId | null
+  originWarehouseId?: ApiId | null
+  destinationWarehouseId?: ApiId | null
+  weightFromKg?: ApiNumber | null
+  unitPrice: ApiNumber
+  sourceRowNumber: ApiNumber
+}
+
+interface PriceBookParseIssuePayload extends Omit<PlatformPriceBookParseIssue, 'sourceRowNumber'> {
+  sourceRowNumber?: ApiNumber | null
+}
+
+interface PriceBookDetailPayload {
+  version: PriceBookVersionPayload
+  channels?: PriceBookParsedChannelPayload[] | null
+  rates?: PriceBookParsedRatePayload[] | null
+  issues?: PriceBookParseIssuePayload[] | null
+}
+
+const basePath = '/platform/v1/fba-pricing/carrier-rates/price-books'
+
+function nullableId(value: ApiId | null | undefined) {
+  return value == null ? null : String(value)
+}
+
+function nullableText(value: string | null | undefined) {
+  return value ?? null
+}
+
+function numberValue(value: ApiNumber | null | undefined) {
+  const number = Number(value ?? 0)
+  return Number.isFinite(number) ? number : 0
+}
+
+function normalizeVersion(value: PriceBookVersionPayload): PlatformPriceBookVersion {
+  return {
+    ...value,
+    id: String(value.id),
+    customerId: String(value.customerId),
+    versionNo: numberValue(value.versionNo),
+    sourceFileId: nullableId(value.sourceFileId),
+    channelCount: numberValue(value.channelCount),
+    rateCount: numberValue(value.rateCount),
+    blockingErrorCount: numberValue(value.blockingErrorCount),
+    warningCount: numberValue(value.warningCount),
+    parseIssuesJson: nullableText(value.parseIssuesJson),
+    createdBy: nullableId(value.createdBy),
+    createdAt: nullableText(value.createdAt),
+    publishedBy: nullableId(value.publishedBy),
+    publishedAt: nullableText(value.publishedAt),
+    supersededAt: nullableText(value.supersededAt),
+    voidedBy: nullableId(value.voidedBy),
+    voidedAt: nullableText(value.voidedAt),
+    voidReason: nullableText(value.voidReason),
+  }
+}
+
+function normalizeChannel(value: PriceBookParsedChannelPayload): PlatformPriceBookParsedChannel {
+  return {
+    ...value,
+    estimatedDepartureDate: nullableText(value.estimatedDepartureDate),
+    estimatedDepartureText: nullableText(value.estimatedDepartureText),
+    latestWarehouseEntry: nullableText(value.latestWarehouseEntry),
+    vesselName: nullableText(value.vesselName),
+    voyageNo: nullableText(value.voyageNo),
+    referenceTransit: nullableText(value.referenceTransit),
+    surchargeDescription: nullableText(value.surchargeDescription),
+    remark: nullableText(value.remark),
+  }
+}
+
+function normalizeRate(value: PriceBookParsedRatePayload): PlatformPriceBookParsedRate {
+  return {
+    ...value,
+    id: nullableId(value.id),
+    originWarehouseId: nullableId(value.originWarehouseId),
+    destinationWarehouseId: nullableId(value.destinationWarehouseId),
+    destinationType: value.destinationType ?? null,
+    destinationCode: nullableText(value.destinationCode),
+    destinationName: nullableText(value.destinationName),
+    regionCode: nullableText(value.regionCode),
+    pricingTaxMode: value.pricingTaxMode ?? null,
+    weightFromKg: value.weightFromKg == null ? null : numberValue(value.weightFromKg),
+    unitPrice: numberValue(value.unitPrice),
+    sourceRowNumber: numberValue(value.sourceRowNumber),
+    sourceDestinationText: nullableText(value.sourceDestinationText),
+    remark: nullableText(value.remark),
+  }
+}
+
+function normalizeIssue(value: PriceBookParseIssuePayload): PlatformPriceBookParseIssue {
+  return {
+    ...value,
+    sourceSheetName: nullableText(value.sourceSheetName),
+    sourceRowNumber: value.sourceRowNumber == null ? null : numberValue(value.sourceRowNumber),
+    sourceCell: nullableText(value.sourceCell),
+  }
+}
+
+function normalizeDetail(value: PriceBookDetailPayload): PlatformPriceBookDetail {
+  return {
+    version: normalizeVersion(value.version),
+    channels: (value.channels || []).map(normalizeChannel),
+    rates: (value.rates || []).map(normalizeRate),
+    issues: (value.issues || []).map(normalizeIssue),
+  }
+}
+
+export async function listPlatformPriceBooks(query: PlatformPriceBookQuery = {}): Promise<PlatformPriceBookVersion[]> {
+  const status = query.status?.trim()
+  const customerId = query.customerId?.trim() || '0'
+  const response = await http.get<ApiEnvelope<PriceBookVersionPayload[]>, ApiEnvelope<PriceBookVersionPayload[]>>(basePath, {
+    params: status ? { customerId, status } : { customerId },
+  })
+  return unwrapApiResponse(response).map(normalizeVersion)
+}
+
+export async function getPlatformPriceBook(versionId: string): Promise<PlatformPriceBookDetail> {
+  const response = await http.get<ApiEnvelope<PriceBookDetailPayload>, ApiEnvelope<PriceBookDetailPayload>>(
+    `${basePath}/${encodeURIComponent(versionId)}`,
+  )
+  return normalizeDetail(unwrapApiResponse(response))
+}
+
+export async function uploadPlatformPriceBook(file: File, customerId = '0'): Promise<PlatformPriceBookDetail> {
+  const form = new FormData()
+  form.append('file', file)
+  const response = await http.post<ApiEnvelope<PriceBookDetailPayload>, ApiEnvelope<PriceBookDetailPayload>>(basePath, form, {
+    params: { customerId: customerId.trim() || '0' },
+  })
+  return normalizeDetail(unwrapApiResponse(response))
+}
+
+export async function publishPlatformPriceBook(
+  versionId: string,
+  request: PriceBookConfirmationRequest,
+): Promise<PlatformPriceBookDetail> {
+  const response = await http.post<ApiEnvelope<PriceBookDetailPayload>, ApiEnvelope<PriceBookDetailPayload>>(
+    `${basePath}/${encodeURIComponent(versionId)}/publish`,
+    request,
+  )
+  return normalizeDetail(unwrapApiResponse(response))
+}
+
+export async function voidPlatformPriceBook(versionId: string, reason: string): Promise<PlatformPriceBookDetail> {
+  const response = await http.post<ApiEnvelope<PriceBookDetailPayload>, ApiEnvelope<PriceBookDetailPayload>>(
+    `${basePath}/${encodeURIComponent(versionId)}/void`,
+    { reason },
+  )
+  return normalizeDetail(unwrapApiResponse(response))
+}
+
+export function downloadPlatformPriceBookSource(versionId: string) {
+  return http.get<Blob, Blob>(`${basePath}/${encodeURIComponent(versionId)}/source`, { responseType: 'blob' })
+}
diff --git a/src/modules/fba-pricing/carrier-rates/pages/CarrierRateDetailView.vue b/src/modules/fba-pricing/carrier-rates/pages/CarrierRateDetailView.vue
new file mode 100644
index 00000000..ad190cfa
--- /dev/null
+++ b/src/modules/fba-pricing/carrier-rates/pages/CarrierRateDetailView.vue
@@ -0,0 +1,592 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, ref, watch } from 'vue'
+import { AlertTriangle, ArrowLeft, CircleCheck, Download, FileSpreadsheet, RefreshCw, Ship, Warehouse } from '@lucide/vue'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import { useRoute, useRouter } from 'vue-router'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { listPlatformTenants, type PlatformTenantResource } from '@/modules/iam'
+import { listAllPlatformWarehouses, type PlatformWarehouseResource } from '@/modules/warehouses'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import DetailPageLayout from '@/shared/components/DetailPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import {
+  downloadPlatformPriceBookSource,
+  getPlatformPriceBook,
+  publishPlatformPriceBook,
+  type PlatformPriceBookDetail,
+  type PlatformPriceBookParseIssue,
+  type PlatformPriceBookParsedRate,
+  type PlatformPriceBookVersion,
+  type PriceBookConfirmationRequest,
+  type PriceBookStatus,
+} from '../api/platformPriceBooks'
+
+interface OriginMappingRow {
+  key: string
+  sourceCode: string
+  sourceName: string
+  warehouseId: string | null
+}
+
+interface OverseasMappingRow {
+  key: string
+  sourceName: string
+  destinationCode: string | null
+  warehouseId: string | null
+}
+
+const route = useRoute()
+const router = useRouter()
+const access = useAccessPreviewStore()
+const versionId = computed(() => String(route.params.versionId || ''))
+const detail = ref<PlatformPriceBookDetail | null>(null)
+const loading = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const selectedChannelCode = ref('')
+const publishing = ref(false)
+const downloading = ref(false)
+const mappingWarehouses = ref<PlatformWarehouseResource[]>([])
+const mappingWarehousesLoaded = ref(false)
+const mappingWarehousesLoading = ref(false)
+const mappingWarehousesError = ref<ApiErrorDetails | null>(null)
+const customerOptions = ref<PlatformTenantResource[]>([])
+const originSelections = ref<Record<string, string>>({})
+const overseasSelections = ref<Record<string, string>>({})
+let detailSequence = 0
+let warehouseSequence = 0
+
+const canEdit = computed(() => access.can('firstleg:fba-pricing:rate:edit'))
+const isPending = computed(() => detail.value?.version.status === 'PENDING_CONFIRMATION')
+const domesticWarehouses = computed(() => mappingWarehouses.value.filter((warehouse) => (
+  warehouse.status === 'ACTIVE' && warehouse.warehouseType === 'DOMESTIC'
+)))
+const overseasWarehouses = computed(() => mappingWarehouses.value.filter((warehouse) => (
+  warehouse.status === 'ACTIVE' && warehouse.warehouseType === 'OVERSEAS'
+)))
+const originMappingRows = computed<OriginMappingRow[]>(() => {
+  const unique = new Map<string, OriginMappingRow>()
+  for (const rate of detail.value?.rates || []) {
+    const sourceCode = rate.originWarehouseCode.trim()
+    if (!sourceCode) continue
+    const key = mappingKey(sourceCode)
+    if (!unique.has(key)) unique.set(key, {
+      key,
+      sourceCode,
+      sourceName: rate.originWarehouseName || sourceCode,
+      warehouseId: rate.originWarehouseId,
+    })
+  }
+  return [...unique.values()]
+})
+const overseasMappingRows = computed<OverseasMappingRow[]>(() => {
+  const unique = new Map<string, OverseasMappingRow>()
+  for (const rate of detail.value?.rates || []) {
+    if (rate.destinationType !== 'OVERSEAS' || !rate.destinationName?.trim()) continue
+    const sourceName = rate.destinationName.trim()
+    const key = mappingKey(sourceName)
+    if (!unique.has(key)) unique.set(key, {
+      key,
+      sourceName,
+      destinationCode: rate.destinationCode,
+      warehouseId: rate.destinationWarehouseId,
+    })
+  }
+  return [...unique.values()]
+})
+const hasMissingOverseasSource = computed(() => (detail.value?.rates || []).some((rate) => (
+  rate.destinationType === 'OVERSEAS' && !rate.destinationName?.trim()
+)))
+const selectedChannelRates = computed(() => {
+  const rates = detail.value?.rates || []
+  return selectedChannelCode.value ? rates.filter((rate) => rate.channelCode === selectedChannelCode.value) : rates
+})
+const selectedChannel = computed(() => detail.value?.channels.find((channel) => channel.channelCode === selectedChannelCode.value) || null)
+const mappingBlockingIssueCodes = new Set([
+  'ORIGIN_MAPPING_REQUIRED',
+  'ORIGIN_WAREHOUSE_INVALID',
+  'OVERSEAS_MAPPING_REQUIRED',
+  'OVERSEAS_WAREHOUSE_INVALID',
+  'WAREHOUSE_VALIDATION_FAILED',
+  'DUPLICATE_ORIGIN_MAPPING',
+  'DUPLICATE_OVERSEAS_MAPPING',
+  'UNUSED_ORIGIN_MAPPING',
+  'UNUSED_OVERSEAS_MAPPING',
+  'DUPLICATE_WAREHOUSE_MAPPING',
+  'DUPLICATE_RATE',
+])
+const nonMappingBlockingIssues = computed(() => (detail.value?.issues || []).filter((issue) => (
+  issue.severity === 'BLOCKING' && !mappingBlockingIssueCodes.has(issue.issueCode)
+)))
+const mappingsComplete = computed(() => (
+  originMappingRows.value.length > 0
+  && originMappingRows.value.every((row) => Boolean(originSelections.value[row.key]))
+  && overseasMappingRows.value.every((row) => Boolean(overseasSelections.value[row.key]))
+))
+const mappingCandidatesMissing = computed(() => (
+  originMappingRows.value.some((row) => !domesticWarehouses.value.some((warehouse) => originWarehouseMatches(row, warehouse)))
+  || overseasMappingRows.value.some((row) => !overseasWarehouses.value.some((warehouse) => overseasWarehouseMatches(row, warehouse)))
+))
+const canConfirm = computed(() => (
+  isPending.value
+  && canEdit.value
+  && !loading.value
+  && !publishing.value
+  && !mappingWarehousesLoading.value
+  && mappingWarehousesLoaded.value
+  && !mappingWarehousesError.value
+  && !hasMissingOverseasSource.value
+  && !mappingCandidatesMissing.value
+  && !nonMappingBlockingIssues.value.length
+  && mappingsComplete.value
+))
+const confirmationHint = computed(() => {
+  if (!isPending.value) return ''
+  if (nonMappingBlockingIssues.value.length) return '当前文件仍有无法通过仓库映射解决的阻断错误，请修改原 Excel 后重新上传。'
+  if (hasMissingOverseasSource.value) return '存在未识别名称的海外仓价格行，无法完成映射。'
+  if (mappingWarehousesError.value) return '平台仓库候选加载失败，暂不能确认生效。'
+  if (mappingWarehousesLoading.value || !mappingWarehousesLoaded.value) return '正在加载平台仓库候选。'
+  if (mappingCandidatesMissing.value) return '上传表中的仓库编码尚未配置为匹配的启用平台公共仓库。'
+  if (!mappingsComplete.value) return '请完成所有起运仓和海外仓映射。'
+  return '确认后将立即替换当前生效版本，历史版本和原文件仍可查询。'
+})
+
+function mappingKey(value: string) {
+  return value.trim().toUpperCase()
+}
+
+function formatDateTime(value: string | null | undefined) {
+  return value ? value.replace('T', ' ').slice(0, 16) : '—'
+}
+
+function formatEffectivePeriod(version: PlatformPriceBookVersion) {
+  if (!version.publishedAt) return '尚未生效'
+  const start = formatDateTime(version.publishedAt)
+  return version.supersededAt ? `${start} 至 ${formatDateTime(version.supersededAt)}` : `${start} 起`
+}
+
+function priceBookScopeLabel(customerId: string | null | undefined) {
+  if (!customerId || customerId === '0') return '平台公共报价'
+  const customer = customerOptions.value.find((item) => String(item.id) === String(customerId))
+  return customer ? `客户专属 · ${customer.tenantName || '未命名客户'}` : '客户专属报价'
+}
+
+function formatMoney(value: number, currency: string) {
+  return `${currency} ${value.toLocaleString('zh-CN', { minimumFractionDigits: 2, maximumFractionDigits: 4 })}`
+}
+
+function priceBookStatusMeta(status: PriceBookStatus) {
+  return {
+    PENDING_CONFIRMATION: { label: '待确认', type: 'warning' as const },
+    ACTIVE: { label: '生效中', type: 'success' as const },
+    SUPERSEDED: { label: '已替换', type: 'info' as const },
+    VOIDED: { label: '已作废', type: 'info' as const },
+    FAILED: { label: '解析失败', type: 'danger' as const },
+  }[status]
+}
+
+function priceModelLabel(value: string) {
+  return value === 'REGION_WEIGHT_TIER' ? '海派区域阶梯价' : '按仓价格'
+}
+
+function pricingTaxModeLabel(value: string | null) {
+  if (value === 'TAX_INCLUDED') return '包税'
+  if (value === 'TAX_EXCLUDED') return '不包税'
+  return '—'
+}
+
+function rateDestinationLabel(rate: PlatformPriceBookParsedRate) {
+  if (rate.destinationType === 'OVERSEAS') return rate.destinationName || rate.destinationCode || '—'
+  if (rate.destinationType === 'FBA') return rate.destinationCode || rate.destinationName || '—'
+  return rate.regionCode || '—'
+}
+
+function issueLocation(issue: PlatformPriceBookParseIssue) {
+  return [issue.sourceSheetName, issue.sourceRowNumber ? `第 ${issue.sourceRowNumber} 行` : null, issue.sourceCell]
+    .filter(Boolean)
+    .join(' · ') || '—'
+}
+
+function sourceLocation(rate: PlatformPriceBookParsedRate) {
+  return `${rate.sourceSheetName} · 第 ${rate.sourceRowNumber} 行`
+}
+
+function apiErrorMessage(error: unknown, fallback: string) {
+  const details = getApiErrorDetails(error, fallback)
+  return details.requestId ? `${details.message}（requestId: ${details.requestId}）` : details.message
+}
+
+function safeFileName(value: string) {
+  const safe = value.replace(/[\\/:*?"<>|\u0000-\u001f]/g, '_').trim()
+  return safe || '船期价格表.xlsx'
+}
+
+function saveBlob(blob: Blob, fileName: string) {
+  const url = URL.createObjectURL(blob)
+  const anchor = document.createElement('a')
+  try {
+    anchor.href = url
+    anchor.download = safeFileName(fileName)
+    document.body.append(anchor)
+    anchor.click()
+  } finally {
+    anchor.remove()
+    window.setTimeout(() => URL.revokeObjectURL(url), 0)
+  }
+}
+
+function resetMappings(value: PlatformPriceBookDetail) {
+  const origins: Record<string, string> = {}
+  const overseas: Record<string, string> = {}
+  for (const rate of value.rates) {
+    const originCode = rate.originWarehouseCode.trim()
+    if (originCode && rate.originWarehouseId) origins[mappingKey(originCode)] = rate.originWarehouseId
+    if (rate.destinationType === 'OVERSEAS' && rate.destinationName?.trim() && rate.destinationWarehouseId) {
+      overseas[mappingKey(rate.destinationName)] = rate.destinationWarehouseId
+    }
+  }
+  originSelections.value = origins
+  overseasSelections.value = overseas
+}
+
+function autoSelectExactWarehouseMappings() {
+  const origins = { ...originSelections.value }
+  const overseas = { ...overseasSelections.value }
+  const usedOrigins = new Set(Object.values(origins))
+  const usedOverseas = new Set(Object.values(overseas))
+
+  for (const row of originMappingRows.value) {
+    if (origins[row.key]) continue
+    const matches = domesticWarehouses.value.filter((warehouse) => originWarehouseMatches(row, warehouse))
+    if (matches.length !== 1) continue
+    const warehouseId = String(matches[0].id)
+    if (!usedOrigins.has(warehouseId)) {
+      origins[row.key] = warehouseId
+      usedOrigins.add(warehouseId)
+    }
+  }
+  for (const row of overseasMappingRows.value) {
+    if (overseas[row.key]) continue
+    const matches = overseasWarehouses.value.filter((warehouse) => overseasWarehouseMatches(row, warehouse))
+    if (matches.length !== 1) continue
+    const warehouseId = String(matches[0].id)
+    if (!usedOverseas.has(warehouseId)) {
+      overseas[row.key] = warehouseId
+      usedOverseas.add(warehouseId)
+    }
+  }
+  originSelections.value = origins
+  overseasSelections.value = overseas
+}
+
+function applyDetail(value: PlatformPriceBookDetail) {
+  detail.value = value
+  selectedChannelCode.value = value.channels[0]?.channelCode || ''
+  resetMappings(value)
+  if (mappingWarehousesLoaded.value) autoSelectExactWarehouseMappings()
+}
+
+async function loadCustomerOptions() {
+  try {
+    const result = await listPlatformTenants({ page: 1, size: 200, status: 'ACTIVE' })
+    customerOptions.value = result.records.filter((customer) => customer.status === 'ACTIVE')
+  } catch {
+    customerOptions.value = []
+  }
+}
+
+async function loadMappingWarehouses(force = false) {
+  if (mappingWarehousesLoaded.value && !force) return true
+  const sequence = ++warehouseSequence
+  mappingWarehousesLoading.value = true
+  mappingWarehousesError.value = null
+  try {
+    const result = await listAllPlatformWarehouses()
+    if (sequence !== warehouseSequence) return false
+    mappingWarehouses.value = result
+    mappingWarehousesLoaded.value = true
+    autoSelectExactWarehouseMappings()
+    return true
+  } catch (error) {
+    if (sequence === warehouseSequence) {
+      mappingWarehouses.value = []
+      mappingWarehousesLoaded.value = false
+      mappingWarehousesError.value = getApiErrorDetails(error, '平台公共仓库加载失败，请稍后重试')
+    }
+    return false
+  } finally {
+    if (sequence === warehouseSequence) mappingWarehousesLoading.value = false
+  }
+}
+
+async function loadDetail() {
+  const id = versionId.value
+  const sequence = ++detailSequence
+  detail.value = null
+  loadError.value = null
+  if (!id) {
+    loadError.value = { message: '缺少价格表版本，无法加载详情' }
+    return
+  }
+  loading.value = true
+  try {
+    const result = await getPlatformPriceBook(id)
+    if (sequence !== detailSequence) return
+    applyDetail(result)
+    if (result.version.status === 'PENDING_CONFIRMATION' && canEdit.value) await loadMappingWarehouses()
+  } catch (error) {
+    if (sequence === detailSequence) loadError.value = getApiErrorDetails(error, '船期价格表详情加载失败，请稍后重试')
+  } finally {
+    if (sequence === detailSequence) loading.value = false
+  }
+}
+
+function originWarehouseMatches(row: OriginMappingRow, warehouse: PlatformWarehouseResource) {
+  return mappingKey(warehouse.warehouseCode) === mappingKey(row.sourceCode)
+}
+
+function overseasWarehouseMatches(row: OverseasMappingRow, warehouse: PlatformWarehouseResource) {
+  return !row.destinationCode || mappingKey(warehouse.warehouseCode) === mappingKey(row.destinationCode)
+}
+
+function selectedByOther(selections: Record<string, string>, currentKey: string, warehouseId: string) {
+  return Object.entries(selections).some(([key, selected]) => key !== currentKey && selected === warehouseId)
+}
+
+function originWarehouseDisabled(row: OriginMappingRow, warehouse: PlatformWarehouseResource) {
+  return !originWarehouseMatches(row, warehouse)
+    || selectedByOther(originSelections.value, row.key, String(warehouse.id))
+}
+
+function overseasWarehouseDisabled(row: OverseasMappingRow, warehouse: PlatformWarehouseResource) {
+  return !overseasWarehouseMatches(row, warehouse)
+    || selectedByOther(overseasSelections.value, row.key, String(warehouse.id))
+}
+
+function buildConfirmationRequest(): PriceBookConfirmationRequest {
+  return {
+    originMappings: originMappingRows.value.map((row) => ({
+      originWarehouseCode: row.sourceCode,
+      warehouseId: originSelections.value[row.key],
+    })),
+    overseasMappings: overseasMappingRows.value.map((row) => ({
+      sourceDestinationName: row.sourceName,
+      warehouseId: overseasSelections.value[row.key],
+    })),
+  }
+}
+
+async function confirmPriceBook() {
+  if (!detail.value || !canConfirm.value) return
+  try {
+    await ElMessageBox.confirm(
+      `确认后，该价格表会立即成为“${priceBookScopeLabel(detail.value.version.customerId)}”的唯一生效版本，并仅替换同一报价范围的当前生效版本。历史版本和原始文件将继续保留。`,
+      '确认并生效船期价格表',
+      { customClass: 'admin-density-confirm', type: 'warning', confirmButtonText: '确认并立即生效', cancelButtonText: '取消' },
+    )
+  } catch (error) {
+    if (error === 'cancel' || error === 'close') return
+    ElMessage.error('确认操作未完成，请重试。')
+    return
+  }
+
+  publishing.value = true
+  try {
+    applyDetail(await publishPlatformPriceBook(detail.value.version.id, buildConfirmationRequest()))
+    ElMessage.success('船期价格表已生效，上一生效版本已保留为历史版本。')
+  } catch (error) {
+    ElMessage.error(apiErrorMessage(error, '确认生效失败，请根据校验结果修正后重试'))
+    await loadDetail()
+  } finally {
+    publishing.value = false
+  }
+}
+
+async function downloadSource() {
+  if (!detail.value) return
+  downloading.value = true
+  try {
+    const blob = await downloadPlatformPriceBookSource(detail.value.version.id)
+    if (!blob.size) throw new Error('原始价格表内容为空')
+    saveBlob(blob, detail.value.version.originalFileName)
+  } catch (error) {
+    ElMessage.error(apiErrorMessage(error, '原始价格表下载失败，请稍后重试'))
+  } finally {
+    downloading.value = false
+  }
+}
+
+function backToList() {
+  void router.push({ name: 'fba-carrier-rates' })
+}
+
+watch(versionId, () => { void loadDetail() })
+onMounted(() => {
+  void loadCustomerOptions()
+  void loadDetail()
+})
+</script>
+
+<template>
+  <AdminPage as="div" class="price-book-detail admin-density" spacing="normal">
+    <DetailPageLayout class="density-detail-layout surface-panel" aria-label="船期价格表版本详情">
+      <template #header>
+        <div class="density-detail-header">
+          <div class="density-detail-heading">
+            <el-button link class="density-back" @click="backToList"><ArrowLeft :size="16" />返回列表</el-button>
+            <h1 class="density-detail-title">{{ detail ? '船期价格表 · V' + detail.version.versionNo : '船期价格表详情' }}</h1>
+            <StatusBadge v-if="detail" :status="priceBookStatusMeta(detail.version.status).label" />
+          </div>
+          <div v-if="detail" class="price-book-header-actions">
+            <el-button :loading="downloading" @click="downloadSource"><Download :size="16" />下载原文件</el-button>
+            <el-button v-if="isPending && canEdit" type="primary" :loading="publishing" :disabled="!canConfirm" @click="confirmPriceBook"><CircleCheck :size="16" />确认并立即生效</el-button>
+          </div>
+        </div>
+      </template>
+      <template v-if="detail" #summary>
+        <dl class="density-detail-overview">
+          <div><dt>报价范围</dt><dd>{{ priceBookScopeLabel(detail.version.customerId) }}</dd></div>
+          <div><dt>上传时间</dt><dd>{{ formatDateTime(detail.version.createdAt) }}</dd></div>
+        </dl>
+      </template>
+
+      <LoadErrorState v-if="loadError" title="船期价格表详情加载失败" :message="loadError.message" :loading="loading" @retry="loadDetail">
+        <template #details><ApiErrorMeta :details="loadError" /></template>
+      </LoadErrorState>
+
+      <template v-else-if="detail">
+        <section class="version-panel">
+          <header class="section-heading">
+            <div><h2><FileSpreadsheet :size="18" />版本信息</h2><p>{{ detail.version.originalFileName }}</p></div>
+          </header>
+          <dl class="detail-grid density-fields">
+            <div><dt>解析渠道</dt><dd>{{ detail.version.channelCount }}</dd></div>
+            <div><dt>解析价格行</dt><dd>{{ detail.version.rateCount }}</dd></div>
+            <div><dt>阻断错误</dt><dd :class="{ 'is-danger': detail.version.blockingErrorCount }">{{ detail.version.blockingErrorCount }}</dd></div>
+            <div><dt>警告</dt><dd>{{ detail.version.warningCount }}</dd></div>
+            <div class="detail-grid__wide"><dt>实际生效区间</dt><dd>{{ formatEffectivePeriod(detail.version) }}</dd></div>
+            <div v-if="detail.version.status === 'VOIDED'" class="detail-grid__wide"><dt>作废原因</dt><dd>{{ detail.version.voidReason || '—' }}</dd></div>
+          </dl>
+        </section>
+
+        <section v-if="isPending && canEdit" class="mapping-section">
+          <header class="section-heading"><div><h2><Warehouse :size="18" />仓库映射</h2><p>来源编码必须匹配启用的平台公共仓库编码。</p></div></header>
+          <el-alert
+            v-if="nonMappingBlockingIssues.length"
+            title="当前文件存在无法通过仓库映射解决的阻断错误，请修改原 Excel 后重新上传。"
+            type="error"
+            :closable="false"
+            show-icon
+          />
+          <el-alert v-else-if="confirmationHint" :title="confirmationHint" :type="canConfirm ? 'success' : 'warning'" :closable="false" show-icon />
+
+          <div v-if="mappingWarehousesError" class="mapping-load-error" role="alert">
+            <div><strong>平台仓库候选加载失败</strong><p>{{ mappingWarehousesError.message }}</p><ApiErrorMeta :details="mappingWarehousesError" /></div>
+            <el-button :loading="mappingWarehousesLoading" @click="loadMappingWarehouses(true)"><RefreshCw :size="16" />重新加载</el-button>
+          </div>
+          <div v-else-if="mappingWarehousesLoaded" class="mapping-groups">
+            <section class="mapping-group">
+              <h3>起运仓映射</h3>
+              <div v-for="row in originMappingRows" :key="row.key" class="mapping-row">
+                <div><strong>{{ row.sourceName }}</strong><span>来源编码：{{ row.sourceCode }}</span></div>
+                <el-select v-model="originSelections[row.key]" filterable placeholder="请选择匹配的国内仓">
+                  <el-option v-for="warehouse in domesticWarehouses" :key="String(warehouse.id)" :label="`${warehouse.warehouseName}（${warehouse.warehouseCode}）`" :value="String(warehouse.id)" :disabled="originWarehouseDisabled(row, warehouse)" />
+                </el-select>
+              </div>
+            </section>
+            <section v-if="overseasMappingRows.length" class="mapping-group">
+              <h3>海外仓映射</h3>
+              <div v-for="row in overseasMappingRows" :key="row.key" class="mapping-row">
+                <div><strong>{{ row.sourceName }}</strong><span>目的仓编码：{{ row.destinationCode || '未提供' }}</span></div>
+                <el-select v-model="overseasSelections[row.key]" filterable placeholder="请选择匹配的海外仓">
+                  <el-option v-for="warehouse in overseasWarehouses" :key="String(warehouse.id)" :label="`${warehouse.warehouseName}（${warehouse.warehouseCode}）`" :value="String(warehouse.id)" :disabled="overseasWarehouseDisabled(row, warehouse)" />
+                </el-select>
+              </div>
+            </section>
+            <el-alert v-if="mappingCandidatesMissing" title="未找到编码匹配的启用平台公共仓库，请先在仓库管理中补齐对应仓库。" type="warning" :closable="false" show-icon />
+            <el-alert v-if="hasMissingOverseasSource" title="有海外仓价格行缺少来源名称，无法确认映射。" type="error" :closable="false" show-icon />
+          </div>
+        </section>
+
+        <section class="detail-section">
+          <header class="section-heading"><div><h2><AlertTriangle :size="18" />解析与校验</h2><p>阻断错误未解决时不能生效；价格行不可在页面内修改。</p></div></header>
+          <el-empty v-if="!detail.issues.length" description="未发现解析问题" :image-size="72" />
+          <el-table v-else :data="detail.issues" size="small" max-height="280" aria-label="价格表解析问题">
+            <el-table-column label="级别" width="90"><template #default="{ row }"><el-tag :type="(row as PlatformPriceBookParseIssue).severity === 'BLOCKING' ? 'danger' : 'warning'" size="small">{{ (row as PlatformPriceBookParseIssue).severity === 'BLOCKING' ? '阻断' : '警告' }}</el-tag></template></el-table-column>
+            <el-table-column prop="issueCode" label="编码" min-width="165" show-overflow-tooltip />
+            <el-table-column prop="message" label="说明" min-width="250" show-overflow-tooltip />
+            <el-table-column label="来源" min-width="180"><template #default="{ row }">{{ issueLocation(row as PlatformPriceBookParseIssue) }}</template></el-table-column>
+          </el-table>
+        </section>
+
+        <section class="detail-section channel-preview">
+          <header class="section-heading"><div><h2><Ship :size="18" />按渠道预览</h2><p>显示上传 Excel 的解析结果，确认页不提供在线改价。</p></div></header>
+          <el-empty v-if="!detail.channels.length" description="未解析出渠道" :image-size="72" />
+          <template v-else>
+            <el-tabs v-model="selectedChannelCode" class="channel-tabs density-element-tabs">
+              <el-tab-pane v-for="channel in detail.channels" :key="channel.channelCode" :name="channel.channelCode"><template #label><span class="density-tab-icon" aria-hidden="true">🚢</span>{{ channel.channelName }}</template></el-tab-pane>
+            </el-tabs>
+            <div class="channel-meta"><span>{{ priceModelLabel(selectedChannel?.priceModel || '') }}</span><span>表页：{{ selectedChannel?.sourceSheetName || '—' }}</span></div>
+            <el-table :data="selectedChannelRates" size="small" max-height="440" border stripe aria-label="渠道价格行预览">
+              <el-table-column label="渠道" min-width="140" show-overflow-tooltip><template #default>{{ selectedChannel?.channelName || '—' }}</template></el-table-column>
+              <el-table-column prop="originWarehouseName" label="起运仓" min-width="130" show-overflow-tooltip />
+              <el-table-column label="目的地" min-width="140"><template #default="{ row }">{{ rateDestinationLabel(row as PlatformPriceBookParsedRate) }}</template></el-table-column>
+              <el-table-column label="包税方式" width="105"><template #default="{ row }">{{ pricingTaxModeLabel((row as PlatformPriceBookParsedRate).pricingTaxMode) }}</template></el-table-column>
+              <el-table-column prop="chargeUnit" label="单位" width="78" />
+              <el-table-column label="单价" min-width="120"><template #default="{ row }">{{ formatMoney((row as PlatformPriceBookParsedRate).unitPrice, (row as PlatformPriceBookParsedRate).currency) }}</template></el-table-column>
+              <el-table-column label="参考时效" min-width="130" show-overflow-tooltip><template #default>{{ selectedChannel?.referenceTransit || '—' }}</template></el-table-column>
+              <el-table-column label="最晚进仓时间" min-width="150" show-overflow-tooltip><template #default>{{ selectedChannel?.latestWarehouseEntry || '—' }}</template></el-table-column>
+              <el-table-column label="船期" min-width="150" show-overflow-tooltip><template #default>{{ selectedChannel?.estimatedDepartureText || selectedChannel?.estimatedDepartureDate || '—' }}</template></el-table-column>
+              <el-table-column label="附加费" min-width="180" show-overflow-tooltip><template #default>{{ selectedChannel?.surchargeDescription || '—' }}</template></el-table-column>
+              <el-table-column label="备注" min-width="180" show-overflow-tooltip><template #default>{{ selectedChannel?.remark || '—' }}</template></el-table-column>
+              <el-table-column label="生效状态" width="105"><template #default>{{ priceBookStatusMeta(detail.version.status).label }}</template></el-table-column>
+              <el-table-column label="来源" min-width="170"><template #default="{ row }">{{ sourceLocation(row as PlatformPriceBookParsedRate) }}</template></el-table-column>
+            </el-table>
+          </template>
+        </section>
+      </template>
+    </DetailPageLayout>
+  </AdminPage>
+</template>
+
+<style scoped>
+.price-book-detail { min-width: 0; max-width: 1880px; }
+.version-panel, .mapping-section, .detail-section { padding: var(--admin-space-5) 0; border-bottom: 1px solid var(--cc-border); }
+.detail-section:last-child { border-bottom: 0; }
+.price-book-header-actions { display: flex; align-items: center; flex-wrap: wrap; gap: var(--admin-space-3); }
+.detail-grid .detail-grid__wide { grid-column: 1 / -1; }
+.section-heading > div { min-width: 0; }
+.section-heading { display: flex; align-items: flex-start; justify-content: space-between; gap: var(--admin-space-5); margin-bottom: var(--admin-space-5); }
+.section-heading h2 { display: flex; align-items: center; gap: var(--admin-space-3); margin: 0; color: var(--cc-text); font-size: var(--admin-font-section); }
+.section-heading h2 svg { color: var(--cc-primary); }
+.section-heading p { overflow-wrap: anywhere; margin: 5px 0 0; color: var(--cc-muted); font-size: var(--admin-font-caption); line-height: 1.55; }
+.is-danger { color: var(--el-color-danger) !important; }
+.mapping-section, .detail-section { display: grid; min-width: 0; gap: var(--admin-space-5); }
+.mapping-section .section-heading, .detail-section .section-heading { margin-bottom: 0; }
+.mapping-groups { display: grid; gap: var(--admin-space-5); }
+.mapping-group { display: grid; gap: var(--admin-space-3); }
+.mapping-group h3 { margin: 0; color: var(--cc-text); font-size: var(--admin-font-body); }
+.mapping-row { display: grid; grid-template-columns: minmax(220px, .8fr) minmax(320px, 1fr); align-items: center; gap: var(--admin-space-6); padding: var(--admin-space-5) var(--admin-space-5); border: 1px solid var(--cc-border); border-radius: var(--admin-radius); background: var(--cc-surface-soft, #f8fafc); }
+.mapping-row > div { display: grid; min-width: 0; gap: var(--admin-space-1); }
+.mapping-row strong { overflow-wrap: anywhere; color: var(--cc-text); font-size: var(--admin-font-body); }
+.mapping-row span { color: var(--cc-muted); font-size: var(--admin-font-caption); }
+.mapping-row :deep(.el-select) { width: 100%; }
+.mapping-load-error { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-5); padding: var(--admin-space-5); border: 1px solid color-mix(in srgb, var(--cc-danger) 24%, var(--cc-border)); border-radius: var(--admin-radius); }
+.mapping-load-error strong { color: var(--cc-danger); font-size: var(--admin-font-body); }
+.mapping-load-error p { margin: var(--admin-space-1) 0; color: var(--cc-text); font-size: var(--admin-font-caption); }
+.channel-tabs { width: 100%; min-width: 0; margin-bottom: 0; overflow: hidden; }
+.channel-preview :deep(.el-table) { width: 100%; max-width: 100%; min-width: 0; }
+.channel-meta { display: flex; flex-wrap: wrap; gap: var(--admin-space-2) var(--admin-space-5); margin: calc(-1 * var(--admin-space-1)) 0 0; color: var(--cc-muted); font-size: var(--admin-font-caption); }
+@media (max-width: 720px) {
+  .detail-heading, .mapping-load-error { align-items: stretch; flex-direction: column; }
+  .detail-toolbar { width: 100%; }
+  .detail-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+  .detail-grid > div, .detail-grid > div:nth-child(5n) { border-right: 1px solid var(--cc-border); border-bottom: 1px solid var(--cc-border); }
+  .detail-grid > div:nth-child(2n) { border-right: 0; }
+  .detail-grid__wide, .detail-grid__wide + .detail-grid__wide { grid-column: span 2; }
+  .mapping-row { grid-template-columns: 1fr; gap: 10px; }
+}
+</style>
diff --git a/src/modules/fba-pricing/carrier-rates/pages/CarrierRatesView.test.ts b/src/modules/fba-pricing/carrier-rates/pages/CarrierRatesView.test.ts
new file mode 100644
index 00000000..8075aace
--- /dev/null
+++ b/src/modules/fba-pricing/carrier-rates/pages/CarrierRatesView.test.ts
@@ -0,0 +1,159 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const source = readFileSync(join(process.cwd(), 'src/modules/fba-pricing/carrier-rates/pages/CarrierRatesView.vue'), 'utf8')
+const detailSource = readFileSync(join(process.cwd(), 'src/modules/fba-pricing/carrier-rates/pages/CarrierRateDetailView.vue'), 'utf8')
+const routeSource = readFileSync(join(process.cwd(), 'src/modules/fba-pricing/routes.ts'), 'utf8')
+const queryToolbarSource = readFileSync(join(process.cwd(), 'src/shared/components/QueryToolbar.vue'), 'utf8')
+
+describe('CarrierRatesView price-book source contract', () => {
+  it('keeps the operation column first and presents version-level history', () => {
+    expect(source.indexOf("key: 'actions'")).toBeLessThan(source.indexOf("key: 'version'"))
+    for (const label of ['价格表版本', '原始文件', '解析结果', '校验结果', '上传时间', '实际生效区间']) {
+      expect(source).toContain(label)
+    }
+    expect(source).toContain('formatEffectivePeriod')
+    expect(source).toContain('PENDING_CONFIRMATION')
+    expect(source).toContain('SUPERSEDED')
+    expect(source).not.toContain('<span>ID {{ (row as PlatformPriceBookVersion).id }}</span>')
+    expect(source).toContain("key: 'originalFileName', prop: 'originalFileName', label: '原始文件', minWidth: 250, showOverflowTooltip: true, defaultVisible: false")
+  })
+
+  it('uses only the parsed price-book workflow instead of legacy carrier-rate editing', () => {
+    const workflowSource = `${source}\n${detailSource}`
+    for (const capability of [
+      'listPlatformPriceBooks',
+      'getPlatformPriceBook',
+      'uploadPlatformPriceBook',
+      'publishPlatformPriceBook',
+      'downloadPlatformPriceBookSource',
+    ]) expect(workflowSource).toContain(capability)
+
+    for (const legacyCapability of [
+      'createPlatformCarrierRateVersion',
+      'listPlatformCarrierRates',
+      'retirePlatformCarrierRate',
+      '新增价格版本',
+      '编辑价格',
+      '有效期',
+      '生效日期',
+    ]) expect(workflowSource).not.toContain(legacyCapability)
+  })
+
+  it('opens a formal detail route and keeps uploaded prices immutable', () => {
+    expect(source).toContain('上传并解析')
+    expect(source).toContain('查看并确认')
+    expect(source).toContain("name: 'fba-carrier-rate-detail'")
+    expect(routeSource).toContain("path: 'first-leg-pricing/carrier-rates/:versionId'")
+    expect(routeSource).toContain("import('./carrier-rates/pages/CarrierRateDetailView.vue')")
+    expect(detailSource).toContain('返回列表')
+    expect(detailSource).toContain('确认并立即生效')
+    expect(detailSource).toContain('价格行不可在页面内修改')
+    expect(detailSource).toContain('confirmPriceBook')
+    expect(detailSource).toContain('publishPlatformPriceBook')
+    expect(`${source}\n${detailSource}`).not.toContain('草稿')
+  })
+
+  it('shows all source-backed prototype price metadata without inventing cost breakdowns', () => {
+    for (const label of ['渠道', '参考时效', '最晚进仓时间', '船期', '附加费', '备注', '生效状态']) {
+      expect(detailSource).toContain(`label="${label}"`)
+    }
+    for (const field of ['referenceTransit', 'latestWarehouseEntry', 'estimatedDepartureText', 'surchargeDescription', 'remark']) {
+      expect(detailSource).toContain(`selectedChannel?.${field}`)
+    }
+    expect(detailSource).not.toContain('AMS+换单费')
+    expect(detailSource).not.toContain('建议报价')
+  })
+
+  it('maps only active platform public domestic and overseas warehouses before confirmation', () => {
+    expect(detailSource).toContain('listAllPlatformWarehouses()')
+    expect(detailSource).toContain("warehouse.warehouseType === 'DOMESTIC'")
+    expect(detailSource).toContain("warehouse.warehouseType === 'OVERSEAS'")
+    expect(detailSource).toContain('起运仓映射')
+    expect(detailSource).toContain('海外仓映射')
+    expect(detailSource).toContain('originWarehouseCode')
+    expect(detailSource).toContain('sourceDestinationName')
+    expect(detailSource).toContain('autoSelectExactWarehouseMappings')
+    expect(detailSource).toContain("'DUPLICATE_RATE'")
+    expect(detailSource).toContain('.channel-tabs { width: 100%; min-width: 0;')
+    expect(detailSource).toContain('.channel-preview :deep(.el-table) { width: 100%; max-width: 100%; min-width: 0; }')
+    expect(detailSource).not.toContain('tenantId')
+  })
+
+  it('supports public and customer-specific price-book scopes without exposing technical ids', () => {
+    expect(source).toContain('listPlatformTenants')
+    expect(source).toContain("customerId: '0'")
+    expect(source).toContain('平台公共报价')
+    expect(source).toContain('客户专属')
+    expect(source).toContain('uploadPlatformPriceBook(file, uploadCustomerId.value)')
+    expect(source).toContain('只替换同一报价范围')
+    expect(detailSource).not.toContain('{{ detail.version.customerId }}')
+  })
+
+  it('shows parsing blockers and a channel-tabbed, read-only preview', () => {
+    expect(detailSource).toContain('nonMappingBlockingIssues')
+    expect(detailSource).toContain('解析与校验')
+    expect(detailSource).toContain('按渠道预览')
+    expect(detailSource).toContain('<el-tabs v-model="selectedChannelCode"')
+    expect(detailSource).toContain('sourceLocation')
+    expect(detailSource).toContain('pricingTaxModeLabel')
+    expect(detailSource).toContain('<el-table :data="selectedChannelRates" size="small" max-height="440" border stripe aria-label="渠道价格行预览">')
+    expect(detailSource).toContain('<el-table v-else :data="detail.issues" size="small" max-height="280" aria-label="价格表解析问题">')
+    expect(detailSource).not.toContain('detail.issues" size="small" max-height="280" border stripe')
+  })
+
+  it('accepts only xlsx uploads and retains original-file download', () => {
+    expect(source).toContain('accept=".xlsx,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"')
+    expect(source).toContain("endsWith('.xlsx')")
+    expect(source).toContain('10 * 1024 * 1024')
+    expect(source).toContain('downloadSource')
+    expect(source).toContain('saveBlob')
+  })
+
+  it('uses the shared query and table primitives with mobile layout handling', () => {
+    expect(source).toContain("import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'")
+    expect(source).toContain("import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'")
+    expect(source).toContain('LoadErrorState')
+    expect(queryToolbarSource).toContain('flex-wrap: wrap')
+    expect(source).toContain('@media (max-width: 720px)')
+    expect(source).toContain('.table-actions :deep(.el-button) { min-height: 40px; }')
+    expect(detailSource).toContain('@media (max-width: 720px)')
+    expect(detailSource).toContain('.detail-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }')
+  })
+
+  it('uses bordered striped tables and explicit semantic business buttons', () => {
+    expect(source).toContain('<DataTable')
+    expect(source).toContain(':columns="columns"')
+    expect(detailSource).toContain('border stripe aria-label="渠道价格行预览"')
+    expect(source).toContain('<el-button data-tone="neutral" class="density-action"')
+    expect(source).toMatch(/:loading="downloadingIds\.has/)
+    expect(source).toContain('{{ detailActionLabel')
+    expect(source).toContain('原文件</el-button>')
+    expect(detailSource).toContain('<CircleCheck :size="16" />确认并立即生效')
+    expect(detailSource).toContain('class="density-detail-header"')
+    expect(source).not.toContain('<el-button link type="primary" @click="openDetail')
+  })
+
+  it('keeps upload actions in the table toolbar instead of the query toolbar', () => {
+    const queryToolbarEnd = source.indexOf('/>', source.indexOf('<QueryToolbar'))
+    const queryToolbarBlock = source.slice(source.indexOf('<QueryToolbar'), queryToolbarEnd + 2)
+    expect(queryToolbarBlock).not.toContain('#actions')
+    expect(source).toContain('<template #toolbar-actions><el-button v-if="canEdit" type="primary" @click="openUpload">')
+    expect(source).not.toContain('#toolbar-start')
+    expect(source).toContain('<template #pagination-left>共 {{ rows.length }} 个版本')
+  })
+
+  it('keeps list spacing and error state mutually exclusive', () => {
+    expect(source).toContain('<template v-if="loadError" #state>')
+    expect(source).toContain('<section v-if="!loadError" class="surface-panel table-panel"')
+    expect(source).not.toContain('<template #state>')
+  })
+
+  it('keeps all row actions directly visible without a premature more menu', () => {
+    expect(source).toContain('{{ detailActionLabel')
+    expect(source).toContain('原文件</el-button>')
+    expect(source).toContain('作废</el-button>')
+    expect(source).not.toContain('MoreHorizontal')
+  })
+})
diff --git a/src/modules/fba-pricing/carrier-rates/pages/CarrierRatesView.vue b/src/modules/fba-pricing/carrier-rates/pages/CarrierRatesView.vue
new file mode 100644
index 00000000..39ee9bb6
--- /dev/null
+++ b/src/modules/fba-pricing/carrier-rates/pages/CarrierRatesView.vue
@@ -0,0 +1,442 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, ref, watch } from 'vue'
+import { FileSpreadsheet, FileUp } from '@lucide/vue'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import { useRouter } from 'vue-router'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { listPlatformTenants, type PlatformTenantResource } from '@/modules/iam'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import {
+  downloadPlatformPriceBookSource,
+  listPlatformPriceBooks,
+  uploadPlatformPriceBook,
+  voidPlatformPriceBook,
+  type PlatformPriceBookVersion,
+  type PriceBookStatus,
+} from '../api/platformPriceBooks'
+
+type PriceBookFilters = QueryModel & {
+  customerId: string
+  status: PriceBookStatus | ''
+}
+
+const access = useAccessPreviewStore()
+const router = useRouter()
+const rows = ref<PlatformPriceBookVersion[]>([])
+const page = ref(1)
+const pageSize = ref(20)
+const loading = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const uploadOpen = ref(false)
+const uploadFile = ref<File | null>(null)
+const uploadFileError = ref('')
+const uploadCustomerId = ref('0')
+const uploadInput = ref<HTMLInputElement>()
+const uploading = ref(false)
+const downloadingIds = ref(new Set<string>())
+const voidingIds = ref(new Set<string>())
+const customerOptions = ref<PlatformTenantResource[]>([])
+const customersLoading = ref(false)
+const filters = ref<PriceBookFilters>({ customerId: '0', status: '' })
+const appliedFilters = ref<PriceBookFilters>({ ...filters.value })
+let loadSequence = 0
+
+const queryFields = computed<QueryField[]>(() => [
+  {
+    key: 'customerId',
+    type: 'select',
+    width: 260,
+    label: '报价范围',
+    placeholder: '请选择报价范围',
+    props: { 'aria-label': '报价范围', filterable: true, loading: customersLoading.value },
+    options: [
+      { label: '平台公共报价', value: '0' },
+      ...customerOptions.value.map((customer) => ({ label: `客户专属 · ${customer.tenantName || '未命名客户'}`, value: String(customer.id) })),
+    ],
+  },
+  {
+    key: 'status',
+    type: 'select',
+    width: 190,
+    label: '版本状态',
+    placeholder: '全部版本状态',
+    props: { 'aria-label': '版本状态' },
+    options: [
+      { label: '待确认', value: 'PENDING_CONFIRMATION' },
+      { label: '生效中', value: 'ACTIVE' },
+      { label: '已替换', value: 'SUPERSEDED' },
+      { label: '已作废', value: 'VOIDED' },
+      { label: '解析失败', value: 'FAILED' },
+    ],
+  },
+])
+
+const columns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 300, fixed: 'left', slotName: 'actions' },
+  { key: 'scope', label: '报价范围', minWidth: 190, slotName: 'scope' },
+  { key: 'version', label: '价格表版本', minWidth: 180, slotName: 'version' },
+  { key: 'originalFileName', prop: 'originalFileName', label: '原始文件', minWidth: 250, showOverflowTooltip: true, defaultVisible: false },
+  { key: 'status', label: '状态', width: 110, slotName: 'status' },
+  { key: 'contents', label: '解析结果', minWidth: 155, slotName: 'contents' },
+  { key: 'issues', label: '校验结果', minWidth: 150, slotName: 'issues' },
+  { key: 'createdAt', label: '上传时间', minWidth: 165, formatter: (row: PlatformPriceBookVersion) => formatDateTime(row.createdAt) },
+  { key: 'effectivePeriod', label: '实际生效区间', minWidth: 290, formatter: (row: PlatformPriceBookVersion) => formatEffectivePeriod(row) },
+]
+
+const canEdit = computed(() => access.can('firstleg:fba-pricing:rate:edit'))
+const pagedRows = computed(() => rows.value.slice((page.value - 1) * pageSize.value, page.value * pageSize.value))
+const activeCount = computed(() => rows.value.filter((row) => row.status === 'ACTIVE').length)
+const pendingCount = computed(() => rows.value.filter((row) => row.status === 'PENDING_CONFIRMATION').length)
+const loadErrorMessage = computed(() => loadError.value?.message || '')
+
+function formatDateTime(value: string | null | undefined) {
+  return value ? value.replace('T', ' ').slice(0, 16) : '-'
+}
+
+function formatEffectivePeriod(version: PlatformPriceBookVersion) {
+  if (!version.publishedAt) return '尚未生效'
+  const start = formatDateTime(version.publishedAt)
+  return version.supersededAt ? `${start} 至 ${formatDateTime(version.supersededAt)}` : `${start} 起`
+}
+
+function priceBookScopeLabel(customerId: string | null | undefined) {
+  if (!customerId || customerId === '0') return '平台公共报价'
+  const customer = customerOptions.value.find((item) => String(item.id) === String(customerId))
+  return customer ? `客户专属 · ${customer.tenantName || '未命名客户'}` : '客户专属报价'
+}
+
+async function loadCustomerOptions() {
+  customersLoading.value = true
+  try {
+    const result = await listPlatformTenants({ page: 1, size: 200, status: 'ACTIVE' })
+    customerOptions.value = result.records.filter((customer) => customer.status === 'ACTIVE')
+  } catch {
+    customerOptions.value = []
+    ElMessage.warning('客户列表加载失败，仍可维护平台公共报价')
+  } finally {
+    customersLoading.value = false
+  }
+}
+
+function priceBookStatusMeta(status: PriceBookStatus) {
+  const values = {
+    PENDING_CONFIRMATION: { label: '待确认', type: 'warning' as const },
+    ACTIVE: { label: '生效中', type: 'success' as const },
+    SUPERSEDED: { label: '已替换', type: 'info' as const },
+    VOIDED: { label: '已作废', type: 'info' as const },
+    FAILED: { label: '解析失败', type: 'danger' as const },
+  }
+  return values[status]
+}
+
+function apiErrorMessage(error: unknown, fallback: string) {
+  const details = getApiErrorDetails(error, fallback)
+  return details.requestId ? `${details.message}（requestId: ${details.requestId}）` : details.message
+}
+
+function safeFileName(value: string) {
+  const safe = value.replace(/[\\/:*?"<>|\u0000-\u001f]/g, '_').trim()
+  return safe || '船期价格表.xlsx'
+}
+
+function saveBlob(blob: Blob, fileName: string) {
+  const url = URL.createObjectURL(blob)
+  const anchor = document.createElement('a')
+  try {
+    anchor.href = url
+    anchor.download = safeFileName(fileName)
+    document.body.append(anchor)
+    anchor.click()
+  } finally {
+    anchor.remove()
+    window.setTimeout(() => URL.revokeObjectURL(url), 0)
+  }
+}
+
+async function loadPriceBooks() {
+  const sequence = ++loadSequence
+  loading.value = true
+  loadError.value = null
+  try {
+    const result = await listPlatformPriceBooks({ customerId: appliedFilters.value.customerId, status: appliedFilters.value.status })
+    if (sequence !== loadSequence) return
+    rows.value = result
+  } catch (error) {
+    if (sequence !== loadSequence) return
+    rows.value = []
+    loadError.value = getApiErrorDetails(error, '船期价格表版本加载失败，请稍后重试')
+  } finally {
+    if (sequence === loadSequence) loading.value = false
+  }
+}
+
+async function applyQuery(model: QueryModel) {
+  appliedFilters.value = {
+    customerId: String(model.customerId || '0'),
+    status: (model.status || '') as PriceBookStatus | '',
+  }
+  page.value = 1
+  await loadPriceBooks()
+}
+
+function resetUpload() {
+  uploadFile.value = null
+  uploadFileError.value = ''
+  if (uploadInput.value) uploadInput.value.value = ''
+}
+
+function openUpload() {
+  resetUpload()
+  uploadCustomerId.value = appliedFilters.value.customerId || '0'
+  uploadOpen.value = true
+}
+
+function selectUploadFile(event: Event) {
+  const input = event.target as HTMLInputElement
+  const file = input.files?.[0] || null
+  uploadFile.value = null
+  uploadFileError.value = ''
+  if (!file) return
+  if (!file.name.toLowerCase().endsWith('.xlsx')) {
+    uploadFileError.value = '仅支持 XLSX 格式的船期价格表。'
+    input.value = ''
+    return
+  }
+  if (file.size > 10 * 1024 * 1024) {
+    uploadFileError.value = '价格表文件不能超过 10MB。'
+    input.value = ''
+    return
+  }
+  uploadFile.value = file
+}
+
+function openDetail(row: PlatformPriceBookVersion) {
+  void router.push({ name: 'fba-carrier-rate-detail', params: { versionId: row.id } })
+}
+
+async function submitUpload() {
+  const file = uploadFile.value
+  if (!file) {
+    ElMessage.error('请选择需要上传的 XLSX 价格表。')
+    return
+  }
+  uploading.value = true
+  try {
+    const result = await uploadPlatformPriceBook(file, uploadCustomerId.value)
+    uploadOpen.value = false
+    resetUpload()
+    await loadPriceBooks()
+    ElMessage.success('价格表已解析，请在详情页核对结果并确认仓库映射。')
+    await router.push({ name: 'fba-carrier-rate-detail', params: { versionId: result.version.id } })
+  } catch (error) {
+    ElMessage.error(apiErrorMessage(error, '价格表上传或解析失败，请检查文件后重试'))
+    await loadPriceBooks()
+  } finally {
+    uploading.value = false
+  }
+}
+
+async function downloadSource(row: PlatformPriceBookVersion) {
+  const next = new Set(downloadingIds.value)
+  next.add(row.id)
+  downloadingIds.value = next
+  try {
+    const blob = await downloadPlatformPriceBookSource(row.id)
+    if (!blob.size) throw new Error('原始价格表内容为空')
+    saveBlob(blob, row.originalFileName)
+  } catch (error) {
+    ElMessage.error(apiErrorMessage(error, '原始价格表下载失败，请稍后重试'))
+  } finally {
+    const current = new Set(downloadingIds.value)
+    current.delete(row.id)
+    downloadingIds.value = current
+  }
+}
+
+async function voidPending(row: PlatformPriceBookVersion) {
+  if (row.status !== 'PENDING_CONFIRMATION' || !canEdit.value) return
+  let reason = ''
+  try {
+    const result = await ElMessageBox.prompt(
+      `作废后，版本 V${row.versionNo} 将不能再确认生效；版本记录和原始文件会继续保留。`,
+      '作废待确认价格表',
+      {
+        customClass: 'admin-density-confirm',
+        type: 'warning',
+        confirmButtonText: '确认作废',
+        cancelButtonText: '取消',
+        inputPlaceholder: '请输入作废原因',
+        inputValidator: (value) => value.trim() ? true : '请输入作废原因',
+        inputPattern: /^.{1,500}$/s,
+        inputErrorMessage: '作废原因不能超过 500 个字符',
+      },
+    )
+    reason = result.value.trim()
+  } catch (error) {
+    if (error === 'cancel' || error === 'close') return
+    ElMessage.error('作废操作未完成，请重试。')
+    return
+  }
+
+  const next = new Set(voidingIds.value)
+  next.add(row.id)
+  voidingIds.value = next
+  try {
+    await voidPlatformPriceBook(row.id, reason)
+    ElMessage.success(`价格表 V${row.versionNo} 已作废`)
+    await loadPriceBooks()
+  } catch (error) {
+    ElMessage.error(apiErrorMessage(error, '价格表作废失败，请稍后重试'))
+  } finally {
+    const current = new Set(voidingIds.value)
+    current.delete(row.id)
+    voidingIds.value = current
+  }
+}
+
+function detailActionLabel(row: PlatformPriceBookVersion) {
+  return row.status === 'PENDING_CONFIRMATION' && canEdit.value ? '查看并确认' : '查看详情'
+}
+
+watch(uploadOpen, (open) => {
+  if (!open && !uploading.value) resetUpload()
+})
+
+onMounted(() => {
+  void loadCustomerOptions()
+  void loadPriceBooks()
+})
+</script>
+
+<template>
+  <AdminPage as="div" class="price-book-page admin-density" spacing="normal">
+    <ListPageLayout aria-label="承运商报价版本管理">
+      <template #toolbar>
+        <QueryToolbar
+          v-model="filters"
+          class="surface-panel"
+          ariaLabel="船期价格表筛选"
+          :fields="queryFields"
+          preference-key="price-book-query"
+          @search="applyQuery"
+        />
+      </template>
+
+      <template v-if="loadError" #state>
+        <LoadErrorState
+          title="船期价格表版本加载失败"
+          :message="loadErrorMessage"
+          :loading="loading"
+          @retry="loadPriceBooks()"
+        >
+          <template #details><ApiErrorMeta :details="loadError" /></template>
+        </LoadErrorState>
+      </template>
+
+      <section v-if="!loadError" class="surface-panel table-panel" aria-live="polite">
+      <DataTable
+        v-model:page="page"
+        v-model:page-size="pageSize"
+        :data="pagedRows"
+        :columns="columns"
+        preference-key="price-book-versions-table"
+        :loading="loading"
+        :total="rows.length"
+        :page-sizes="[10, 20, 50]"
+        row-key="id"
+        border
+        stripe
+        aria-label="船期价格表版本列表"
+        empty-text="暂无船期价格表版本"
+      >
+        <template #toolbar-actions><el-button v-if="canEdit" type="primary" @click="openUpload"><FileUp :size="16" />上传价格表</el-button></template>
+        <template #actions="{ row }">
+          <div class="table-actions density-actions">
+            <el-button data-tone="neutral" class="density-action" size="small" @click="openDetail(row as PlatformPriceBookVersion)">{{ detailActionLabel(row as PlatformPriceBookVersion) }}</el-button>
+            <el-button data-tone="neutral" class="density-action"
+              size="small"
+
+              :loading="downloadingIds.has((row as PlatformPriceBookVersion).id)"
+              @click="downloadSource(row as PlatformPriceBookVersion)"
+            >原文件</el-button>
+            <el-button data-tone="danger" class="density-action"
+              v-if="canEdit && (row as PlatformPriceBookVersion).status === 'PENDING_CONFIRMATION'"
+              size="small"
+
+
+              :loading="voidingIds.has((row as PlatformPriceBookVersion).id)"
+              @click="voidPending(row as PlatformPriceBookVersion)"
+            >作废</el-button>
+          </div>
+        </template>
+        <template #version="{ row }"><div class="version-cell"><strong>V{{ (row as PlatformPriceBookVersion).versionNo }}</strong></div></template>
+        <template #scope="{ row }"><el-tag :type="(row as PlatformPriceBookVersion).customerId === '0' ? 'info' : 'warning'" effect="light">{{ priceBookScopeLabel((row as PlatformPriceBookVersion).customerId) }}</el-tag></template>
+        <template #status="{ row }"><el-tag :type="priceBookStatusMeta((row as PlatformPriceBookVersion).status).type" effect="light">{{ priceBookStatusMeta((row as PlatformPriceBookVersion).status).label }}</el-tag></template>
+        <template #contents="{ row }"><div class="metric-cell"><strong>{{ (row as PlatformPriceBookVersion).channelCount }}</strong><span>渠道</span><strong>{{ (row as PlatformPriceBookVersion).rateCount }}</strong><span>价格行</span></div></template>
+        <template #issues="{ row }"><div class="issue-counts"><span :class="{ 'is-blocking': (row as PlatformPriceBookVersion).blockingErrorCount }">阻断 {{ (row as PlatformPriceBookVersion).blockingErrorCount }}</span><span>警告 {{ (row as PlatformPriceBookVersion).warningCount }}</span></div></template>
+        <template #empty><el-empty description="暂无船期价格表版本" /></template>
+        <template #pagination-left>共 {{ rows.length }} 个版本 · {{ activeCount }} 个生效中 · {{ pendingCount }} 个待确认</template>
+      </DataTable>
+      </section>
+    </ListPageLayout>
+
+    <AppDialog class="admin-density-dialog"
+      v-model="uploadOpen"
+      title="上传船期价格表"
+      width="min(560px, calc(100vw - 28px))"
+      :confirm-loading="uploading"
+      :confirm-disabled="!uploadFile || Boolean(uploadFileError)"
+      confirm-text="上传并解析"
+      @confirm="submitUpload"
+    >
+      <div class="upload-content">
+        <el-alert title="上传后先展示解析结果和仓库映射；确认后只替换同一报价范围的当前生效版本。客户专属报价生效后，计价时优先于平台公共报价。" type="info" :closable="false" show-icon />
+        <label class="upload-scope-field"><span>报价范围</span><el-select v-model="uploadCustomerId" filterable :disabled="uploading" aria-label="上传报价范围"><el-option label="平台公共报价" value="0" /><el-option v-for="customer in customerOptions" :key="String(customer.id)" :label="`客户专属 · ${customer.tenantName || '未命名客户'}`" :value="String(customer.id)" /></el-select></label>
+        <input ref="uploadInput" class="visually-hidden-input" type="file" accept=".xlsx,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" aria-label="选择 XLSX 船期价格表" :disabled="uploading" @change="selectUploadFile" />
+        <div class="upload-file-control">
+          <el-button :disabled="uploading" @click="uploadInput?.click()"><FileSpreadsheet :size="16" />选择 XLSX 文件</el-button>
+          <div class="upload-file-name" :class="{ 'is-empty': !uploadFile }">
+            <strong>{{ uploadFile?.name || '尚未选择文件' }}</strong>
+            <span v-if="uploadFile">{{ (uploadFile.size / 1024 / 1024).toFixed(2) }} MB</span>
+            <span v-else>最大 10MB</span>
+          </div>
+        </div>
+        <p v-if="uploadFileError" class="upload-file-error" role="alert">{{ uploadFileError }}</p>
+      </div>
+    </AppDialog>
+
+  </AdminPage>
+</template>
+
+<style scoped>
+.price-book-page { min-width: 0; }
+.version-cell { display: flex; min-width: 0; flex-direction: column; gap: 3px; }
+.version-cell strong { color: var(--cc-text); }
+.version-cell span, .metric-cell span { color: var(--cc-muted); font-size: var(--admin-font-caption); }
+.metric-cell, .issue-counts { display: flex; flex-wrap: wrap; align-items: baseline; gap: var(--admin-space-1) var(--admin-space-3); }
+.metric-cell strong { color: var(--cc-text); font-size: var(--admin-font-body); }
+.issue-counts { color: var(--cc-muted); font-size: var(--admin-font-caption); }
+.issue-counts .is-blocking, .is-danger { color: var(--el-color-danger); font-weight: 700; }
+.upload-content { display: grid; gap: var(--admin-space-6); }
+.upload-scope-field { display: grid; gap: var(--admin-space-2); color: var(--cc-muted); font-size: var(--admin-font-caption); }
+.upload-scope-field :deep(.el-select) { width: 100%; }
+.visually-hidden-input { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; clip-path: inset(50%); }
+.upload-file-control { display: flex; align-items: center; gap: var(--admin-space-5); }
+.upload-file-name { display: grid; min-width: 0; gap: 3px; color: var(--cc-text); font-size: var(--admin-font-body); }
+.upload-file-name strong { overflow-wrap: anywhere; }
+.upload-file-name span { color: var(--cc-muted); font-size: var(--admin-font-caption); }
+.upload-file-name.is-empty strong { color: var(--cc-muted); font-weight: 400; }
+.upload-file-error { margin: calc(-1 * var(--admin-space-3)) 0 0; color: var(--el-color-danger); font-size: var(--admin-font-caption); }
+@media (max-width: 720px) {
+  .table-actions :deep(.el-button) { min-height: 40px; }
+  .upload-file-control { align-items: stretch; flex-direction: column; }
+}
+</style>
diff --git a/src/modules/fba-pricing/customer-rules/api.ts b/src/modules/fba-pricing/customer-rules/api.ts
new file mode 100644
index 00000000..6efc0ab2
--- /dev/null
+++ b/src/modules/fba-pricing/customer-rules/api.ts
@@ -0,0 +1,65 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+
+export interface CustomerChargeRule {
+  id: string
+  tenantId: string
+  ruleCode: string
+  ruleVersion: number
+  customerId: string
+  customerName: string
+  businessType: string
+  chargeMode: 'KG' | 'CBM'
+  taxMode: 'TAX_INCLUDED' | 'TAX_EXCLUDED'
+  conversionFactor: number
+  lengthFactor: number
+  widthFactor: number
+  heightFactor: number
+  defaultRule: boolean
+  roundingScale: number
+  roundingMode: string
+  currency: string
+  effectiveFrom: string
+  effectiveTo: string | null
+  status: 'ACTIVE' | 'INACTIVE'
+  remark: string | null
+}
+
+export type CreateCustomerChargeRuleRequest = Omit<CustomerChargeRule, 'id' | 'tenantId' | 'ruleVersion' | 'status'> & {
+  id?: never
+  tenantId?: never
+  ruleVersion?: never
+  status?: never
+}
+
+const path = '/platform/v1/fba-pricing/customer-rules'
+
+function normalize(value: CustomerChargeRule): CustomerChargeRule {
+  return {
+    ...value,
+    id: String(value.id), tenantId: String(value.tenantId), customerId: String(value.customerId),
+    ruleVersion: Number(value.ruleVersion), conversionFactor: Number(value.conversionFactor),
+    lengthFactor: Number(value.lengthFactor ?? 1), widthFactor: Number(value.widthFactor ?? 1),
+    heightFactor: Number(value.heightFactor ?? 1), defaultRule: Boolean(value.defaultRule),
+    roundingScale: Number(value.roundingScale),
+  }
+}
+
+export async function listCustomerChargeRules(customerId: string, tenantId?: string) {
+  const response = await http.get<never, ApiEnvelope<CustomerChargeRule[]>>(path, {
+    params: { tenantId: tenantId || customerId, customerId },
+  })
+  return unwrapApiResponse(response).map(normalize)
+}
+
+export async function createCustomerChargeRule(tenantId: string, request: CreateCustomerChargeRuleRequest) {
+  const response = await http.post<never, ApiEnvelope<CustomerChargeRule>>(`${path}/versions`, request, { params: { tenantId } })
+  return normalize(unwrapApiResponse(response))
+}
+
+export async function setCustomerChargeRuleDefault(tenantId: string, ruleId: string) {
+  await http.put<never, ApiEnvelope<void>>(`${path}/${encodeURIComponent(ruleId)}/default`, undefined, { params: { tenantId } })
+}
+
+export async function retireCustomerChargeRule(tenantId: string, ruleId: string) {
+  await http.delete<never, ApiEnvelope<void>>(`${path}/${encodeURIComponent(ruleId)}`, { params: { tenantId } })
+}
diff --git a/src/modules/fba-pricing/index.ts b/src/modules/fba-pricing/index.ts
new file mode 100644
index 00000000..545977d1
--- /dev/null
+++ b/src/modules/fba-pricing/index.ts
@@ -0,0 +1 @@
+export * from './public'
diff --git a/src/modules/fba-pricing/public.ts b/src/modules/fba-pricing/public.ts
new file mode 100644
index 00000000..e0e6fc2b
--- /dev/null
+++ b/src/modules/fba-pricing/public.ts
@@ -0,0 +1,7 @@
+export {
+  createCustomerChargeRule,
+  listCustomerChargeRules,
+  retireCustomerChargeRule,
+  setCustomerChargeRuleDefault,
+} from './customer-rules/api'
+export type { CustomerChargeRule, CreateCustomerChargeRuleRequest } from './customer-rules/api'
diff --git a/src/modules/fba-pricing/routes.ts b/src/modules/fba-pricing/routes.ts
new file mode 100644
index 00000000..5ed74cf1
--- /dev/null
+++ b/src/modules/fba-pricing/routes.ts
@@ -0,0 +1,25 @@
+import type { RouteRecordRaw } from 'vue-router'
+
+export const fbaPricingRoutes = [
+  {
+    path: 'first-leg-pricing/carrier-rates',
+    name: 'fba-carrier-rates',
+    component: () => import('./carrier-rates/pages/CarrierRatesView.vue'),
+    meta: {
+      title: '船期价格表',
+      description: '上传、确认并查询平台公共船期价格表版本',
+      permission: 'firstleg:fba-pricing:rate:view',
+    },
+  },
+  {
+    path: 'first-leg-pricing/carrier-rates/:versionId',
+    name: 'fba-carrier-rate-detail',
+    component: () => import('./carrier-rates/pages/CarrierRateDetailView.vue'),
+    meta: {
+      title: '船期价格表详情',
+      description: '查看价格表版本、仓库映射和渠道价格',
+      permission: 'firstleg:fba-pricing:rate:view',
+      showPageHeading: false,
+    },
+  },
+] satisfies RouteRecordRaw[]
diff --git a/src/modules/fee-items/api/platformFeeItems.test.ts b/src/modules/fee-items/api/platformFeeItems.test.ts
new file mode 100644
index 00000000..d3175a33
--- /dev/null
+++ b/src/modules/fee-items/api/platformFeeItems.test.ts
@@ -0,0 +1,69 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import {
+  changePlatformFeeItemStatus,
+  createPlatformFeeItem,
+  deletePlatformFeeItem,
+  getPlatformFeeItem,
+  listPlatformFeeItems,
+  updatePlatformFeeItem,
+  type SavePlatformFeeItemRequest,
+} from './platformFeeItems'
+
+vi.mock('@/shared/api/http', () => ({
+  http: { get: vi.fn(), post: vi.fn(), put: vi.fn(), patch: vi.fn(), delete: vi.fn() },
+  unwrapApiResponse: <T>(response: { data: T }) => response.data,
+}))
+
+const payload: SavePlatformFeeItemRequest = {
+  category: '仓储成本',
+  tradeScope: 'INTERNATIONAL',
+  feeTypeName: '仓库租赁费',
+  supplierCategory: 'TRUCKING',
+  pickupPayable: false,
+  pickupReceivable: false,
+  warehousePayable: true,
+  warehouseReceivable: true,
+  allocationFee: true,
+  description: null,
+}
+
+describe('platform fee item API', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it('sends normalized public list filters without customer context', async () => {
+    vi.mocked(http.get).mockResolvedValue({
+      code: '200', message: 'success', data: { records: [], page: '2', size: '20', total: '21', pages: '2' },
+    })
+
+    await expect(listPlatformFeeItems({
+      category: ' 仓储成本 ', tradeScope: 'INTERNATIONAL',
+      keyword: ' 租赁 ', status: 'ACTIVE', page: 2, size: 20,
+    })).resolves.toMatchObject({ page: 2, size: 20, total: 21, pages: 2 })
+
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/fee-items', { params: {
+      category: '仓储成本', tradeScope: 'INTERNATIONAL',
+      keyword: '租赁', status: 'ACTIVE', page: 2, size: 20,
+    } })
+  })
+
+  it('uses public detail and mutation contracts', async () => {
+    vi.mocked(http.get).mockResolvedValue({ code: '200', message: 'success', data: { id: '11' } })
+    vi.mocked(http.post).mockResolvedValue({ code: '200', message: 'success', data: { id: '11' } })
+    vi.mocked(http.put).mockResolvedValue({ code: '200', message: 'success', data: { id: '11' } })
+    vi.mocked(http.patch).mockResolvedValue({ code: '200', message: 'success', data: null })
+    vi.mocked(http.delete).mockResolvedValue({ code: '200', message: 'success', data: null })
+
+    await getPlatformFeeItem('11')
+    await createPlatformFeeItem(payload)
+    await updatePlatformFeeItem('11', payload)
+    await changePlatformFeeItemStatus('11', 'DISABLED')
+    await deletePlatformFeeItem('11')
+
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/fee-items/11')
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/fee-items', payload)
+    expect(http.put).toHaveBeenCalledWith('/platform/v1/fee-items/11', payload)
+    expect(http.patch).toHaveBeenCalledWith('/platform/v1/fee-items/11/status', { status: 'DISABLED' })
+    expect(http.delete).toHaveBeenCalledWith('/platform/v1/fee-items/11')
+  })
+})
diff --git a/src/modules/fee-items/api/platformFeeItems.ts b/src/modules/fee-items/api/platformFeeItems.ts
new file mode 100644
index 00000000..c30f241f
--- /dev/null
+++ b/src/modules/fee-items/api/platformFeeItems.ts
@@ -0,0 +1,122 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import type { SupplierCategory } from '@/modules/suppliers'
+
+export type FeeItemTradeScope = 'DOMESTIC' | 'INTERNATIONAL'
+export type FeeItemStatus = 'ACTIVE' | 'DISABLED'
+
+export interface PlatformFeeItemResource {
+  id: number | string
+  category: string
+  tradeScope: FeeItemTradeScope
+  feeCode: string | null
+  supplierCategory: SupplierCategory | null
+  feeTypeName: string
+  pickupPayable: boolean
+  pickupReceivable: boolean
+  warehousePayable: boolean
+  warehouseReceivable: boolean
+  allocationFee: boolean
+  description: string | null
+  status: FeeItemStatus
+  createdByName?: string | null
+  updatedByName?: string | null
+  createdAt?: string | null
+  updatedAt?: string | null
+}
+
+export interface SavePlatformFeeItemRequest {
+  category: string
+  tradeScope: FeeItemTradeScope
+  feeTypeName: string
+  supplierCategory: SupplierCategory | null
+  pickupPayable: boolean
+  pickupReceivable: boolean
+  warehousePayable: boolean
+  warehouseReceivable: boolean
+  allocationFee: boolean
+  description: string | null
+}
+
+export interface PlatformFeeItemQuery {
+  category?: string
+  tradeScope?: FeeItemTradeScope | ''
+  keyword?: string
+  status?: FeeItemStatus | ''
+  page: number
+  size: number
+}
+
+export interface PlatformFeeItemPage {
+  records: PlatformFeeItemResource[]
+  page: number
+  size: number
+  total: number
+  pages: number
+}
+
+const basePath = '/platform/v1/fee-items'
+
+export async function listPlatformFeeItems(query: PlatformFeeItemQuery) {
+  const response = await http.get<ApiEnvelope<PlatformFeeItemPage>, ApiEnvelope<PlatformFeeItemPage>>(basePath, {
+    params: {
+      category: query.category?.trim() || undefined,
+      tradeScope: query.tradeScope || undefined,
+      keyword: query.keyword?.trim() || undefined,
+      status: query.status || undefined,
+      page: query.page,
+      size: query.size,
+    },
+  })
+  const result = unwrapApiResponse(response)
+  return {
+    ...result,
+    records: result.records || [],
+    page: Number(result.page),
+    size: Number(result.size),
+    total: Number(result.total),
+    pages: Number(result.pages),
+  }
+}
+
+export async function getPlatformFeeItem(id: number | string) {
+  const response = await http.get<ApiEnvelope<PlatformFeeItemResource>, ApiEnvelope<PlatformFeeItemResource>>(
+    `${basePath}/${id}`,
+    
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function createPlatformFeeItem(payload: SavePlatformFeeItemRequest) {
+  const response = await http.post<ApiEnvelope<PlatformFeeItemResource>, ApiEnvelope<PlatformFeeItemResource>>(
+    basePath,
+    payload,
+    
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function updatePlatformFeeItem(id: number | string, payload: SavePlatformFeeItemRequest) {
+  const response = await http.put<ApiEnvelope<PlatformFeeItemResource>, ApiEnvelope<PlatformFeeItemResource>>(
+    `${basePath}/${id}`,
+    payload,
+    
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function changePlatformFeeItemStatus(id: number | string, status: FeeItemStatus) {
+  const response = await http.patch<ApiEnvelope<null>, ApiEnvelope<null>>(
+    `${basePath}/${id}/status`,
+    { status },
+    
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function deletePlatformFeeItem(id: number | string) {
+  const response = await http.delete<ApiEnvelope<null>, ApiEnvelope<null>>(
+    `${basePath}/${id}`,
+    
+  )
+  return unwrapApiResponse(response)
+}
diff --git a/src/modules/fee-items/pages/FeeItemsView.test.ts b/src/modules/fee-items/pages/FeeItemsView.test.ts
new file mode 100644
index 00000000..5742b7af
--- /dev/null
+++ b/src/modules/fee-items/pages/FeeItemsView.test.ts
@@ -0,0 +1,120 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import ElementPlus from 'element-plus'
+import { createPinia, setActivePinia } from 'pinia'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+import { listPlatformFeeItems } from '@/modules/fee-items/api/platformFeeItems'
+import FeeItemsView from './FeeItemsView.vue'
+
+const source = readFileSync(join(process.cwd(), 'src/modules/fee-items/pages/FeeItemsView.vue'), 'utf8')
+
+vi.mock('@/modules/fee-items/api/platformFeeItems', () => ({
+  listPlatformFeeItems: vi.fn(),
+  getPlatformFeeItem: vi.fn(),
+  createPlatformFeeItem: vi.fn(),
+  updatePlatformFeeItem: vi.fn(),
+  changePlatformFeeItemStatus: vi.fn(),
+  deletePlatformFeeItem: vi.fn(),
+}))
+
+class ResizeObserverStub implements ResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+
+function createMemoryStorage(): Storage {
+  const values = new Map<string, string>()
+  return {
+    get length() { return values.size },
+    clear: () => values.clear(),
+    getItem: (key) => values.get(key) ?? null,
+    key: (index) => [...values.keys()][index] ?? null,
+    removeItem: (key) => values.delete(key),
+    setItem: (key, value) => values.set(key, value),
+  }
+}
+
+async function mountView(permissions: string[]) {
+  const pinia = createPinia()
+  setActivePinia(pinia)
+  const auth = useAuthStore()
+  auth.token = 'token'
+  auth.permissions = permissions
+  useAccessPreviewStore().initializeAfterLogin()
+  const wrapper = mount(FeeItemsView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+  await flushPromises()
+  return wrapper
+}
+
+enableAutoUnmount(afterEach)
+afterAll(() => vi.unstubAllGlobals())
+
+describe('FeeItemsView public master data and access', () => {
+  beforeEach(() => {
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+    vi.stubGlobal('localStorage', createMemoryStorage())
+    vi.stubGlobal('sessionStorage', createMemoryStorage())
+    document.body.innerHTML = ''
+    vi.mocked(listPlatformFeeItems).mockReset().mockResolvedValue({ records: [], page: 1, size: 20, total: 0, pages: 0 })
+  })
+
+  it('loads public fee items immediately without customer selection', async () => {
+    const wrapper = await mountView(['firstleg:fee-item:view', 'firstleg:fee-item:create'])
+
+    expect(wrapper.find('.query-toolbar').exists()).toBe(true)
+    expect(wrapper.find('.data-table').exists()).toBe(true)
+    expect(wrapper.find('.query-toolbar__actions').text()).not.toContain('新增费用项目')
+    expect(wrapper.find('.data-table__business-actions').text()).toContain('新增费用项目')
+    expect(wrapper.find('.data-table__toolbar-start').exists()).toBe(false)
+    expect(wrapper.find('.data-table__pagination-left').text()).toContain('平台公共主数据 · 共 0 项')
+    expect(wrapper.find('.list-page-layout__state').exists()).toBe(false)
+    expect(wrapper.text()).toContain('平台公共主数据')
+    expect(listPlatformFeeItems).toHaveBeenCalledWith(expect.objectContaining({ page: 1, size: 20 }))
+
+    const vm = wrapper.vm as unknown as { applyFilters(model: Record<string, string>): void }
+    vm.applyFilters({ keyword: '', category: '', tradeScope: '', status: '' })
+    await flushPromises()
+
+    expect(listPlatformFeeItems).toHaveBeenCalledWith(expect.objectContaining({ page: 1, size: 20 }))
+  })
+
+  it('renders the load error instead of an empty table panel', async () => {
+    vi.mocked(listPlatformFeeItems).mockRejectedValueOnce(new Error('Gateway unavailable'))
+    const wrapper = await mountView(['firstleg:fee-item:view'])
+
+    expect(wrapper.find('.list-page-layout__state').exists()).toBe(true)
+    expect(wrapper.find('.table-panel').exists()).toBe(false)
+    expect(wrapper.text()).toContain('费用项目加载失败')
+    expect(wrapper.text()).not.toContain('Gateway unavailable')
+  })
+
+  it('renders an explicit no-access state without loading customers or fee items', async () => {
+    const wrapper = await mountView([])
+
+    expect(wrapper.text()).toContain('无权查看费用项目')
+    expect(listPlatformFeeItems).not.toHaveBeenCalled()
+  })
+
+  it('keeps all three row actions visible without a premature more menu', () => {
+    const actions = source.slice(source.indexOf('<template #actions='), source.indexOf('</template>', source.indexOf('<template #actions=')))
+    expect(actions.match(/class="density-action"/g)).toHaveLength(3)
+    expect(actions).toContain('>编辑</el-button>')
+    expect(actions).toContain('>删除</el-button>')
+    expect(actions).toContain('data-tone="danger"')
+    expect(actions).toContain(':data-tone=')
+    expect(actions).not.toMatch(/<(?:el-dropdown|Pencil|Power|Eye|Trash2|Download|CircleX)\b/)
+  })
+  it('keeps the prototype table treatment and mobile form fallback without inventing a pricing mode', () => {
+    expect(source).toContain(':page-sizes="[20, 50, 100]"\n          border\n          stripe')
+    expect(source).toContain('@media (max-width: 720px)')
+    expect(source).toContain('.direction-grid, .form-grid.two-cols { grid-template-columns: 1fr; }')
+    expect(source).not.toContain('pricingMode')
+    expect(source).not.toContain('计价模式')
+    expect(source).not.toContain('固定费用')
+    for (const label of ['创建人', '创建日期', '更新人', '更新日期']) expect(source).toContain(`label: '${label}'`)
+  })
+})
diff --git a/src/modules/fee-items/pages/FeeItemsView.vue b/src/modules/fee-items/pages/FeeItemsView.vue
new file mode 100644
index 00000000..70222bc0
--- /dev/null
+++ b/src/modules/fee-items/pages/FeeItemsView.vue
@@ -0,0 +1,508 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, reactive, ref, watch } from 'vue'
+import { ElMessage, type FormInstance, type FormRules } from 'element-plus'
+import { Plus, Save } from '@lucide/vue'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useUnsavedWorkRegistration } from '@/core/unsaved-work/useUnsavedWorkRegistration'
+import {
+  changePlatformFeeItemStatus,
+  createPlatformFeeItem,
+  deletePlatformFeeItem,
+  getPlatformFeeItem,
+  listPlatformFeeItems,
+  updatePlatformFeeItem,
+  type FeeItemStatus,
+  type FeeItemTradeScope,
+  type PlatformFeeItemResource,
+  type SavePlatformFeeItemRequest,
+} from '@/modules/fee-items/api/platformFeeItems'
+import { categoryLabels, type SupplierCategory } from '@/modules/suppliers'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import AppDrawer from '@/shared/components/AppDrawer.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import FormSection from '@/shared/components/FormSection.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+
+type FeeItemFilters = QueryModel & {
+  keyword: string
+  category: string
+  tradeScope: FeeItemTradeScope | ''
+  status: FeeItemStatus | ''
+}
+
+type FeeItemForm = SavePlatformFeeItemRequest & { id: string }
+
+const access = useAccessPreviewStore()
+const rows = ref<PlatformFeeItemResource[]>([])
+const loading = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const page = ref(1)
+const pageSize = ref(20)
+const total = ref(0)
+const filters = ref<FeeItemFilters>(emptyFilters())
+const appliedFilters = ref<FeeItemFilters>(emptyFilters())
+const editorOpen = ref(false)
+const editorLoading = ref(false)
+const saving = ref(false)
+const formRef = ref<FormInstance>()
+const statusLoadingIds = ref(new Set<string>())
+const statusOpen = ref(false)
+const statusTarget = ref<PlatformFeeItemResource | null>(null)
+const statusSaving = ref(false)
+const deleteOpen = ref(false)
+const deleteTarget = ref<PlatformFeeItemResource | null>(null)
+const deleting = ref(false)
+let loadSequence = 0
+let editorSequence = 0
+
+function emptyFilters(): FeeItemFilters {
+  return { keyword: '', category: '', tradeScope: '', status: '' }
+}
+
+function emptyForm(): FeeItemForm {
+  return {
+    id: '',
+    category: '',
+    tradeScope: 'DOMESTIC',
+    feeTypeName: '',
+    supplierCategory: null,
+    pickupPayable: false,
+    pickupReceivable: false,
+    warehousePayable: false,
+    warehouseReceivable: false,
+    allocationFee: false,
+    description: null,
+  }
+}
+
+const form = reactive<FeeItemForm>(emptyForm())
+const rules: FormRules<FeeItemForm> = {
+  category: [{ required: true, message: '请输入费用分类', trigger: 'blur' }],
+  tradeScope: [{ required: true, message: '请选择贸易范围', trigger: 'change' }],
+  feeTypeName: [{ required: true, message: '请输入费用名称', trigger: 'blur' }],
+}
+const hasPayableDirection = computed(() => form.pickupPayable || form.warehousePayable)
+
+const canView = computed(() => access.can('firstleg:fee-item:view'))
+const editorTitle = computed(() => form.id ? '编辑费用项目' : '新增费用项目')
+const editorPermission = computed(() => form.id ? 'firstleg:fee-item:edit' : 'firstleg:fee-item:create')
+
+const { captureBaseline } = useUnsavedWorkRegistration({
+  key: 'fee-item-editor',
+  label: editorTitle,
+  isOpen: editorOpen,
+  model: form,
+  requiredPermission: editorPermission,
+})
+
+const queryFields = computed<QueryField[]>(() => [
+  { key: 'keyword', type: 'input', width: 210, label: '费用名称', placeholder: '请输入费用名称', props: { 'aria-label': '费用名称', maxlength: 128 } },
+  { key: 'category', type: 'input', width: 190, label: '费用分类', placeholder: '请输入费用分类', props: { 'aria-label': '费用分类', maxlength: 64 } },
+  {
+    key: 'tradeScope', type: 'select', width: 160, label: '贸易范围', placeholder: '全部范围', props: { 'aria-label': '贸易范围' },
+    options: [{ label: '国内', value: 'DOMESTIC' }, { label: '国际', value: 'INTERNATIONAL' }],
+  },
+  {
+    key: 'status', type: 'select', width: 150, label: '状态', placeholder: '全部状态', props: { 'aria-label': '状态' },
+    options: [{ label: '启用', value: 'ACTIVE' }, { label: '停用', value: 'DISABLED' }],
+  },
+])
+
+const columns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 250, fixed: 'left', slotName: 'actions' },
+  { key: 'feeTypeName', label: '费用项目', minWidth: 210, slotName: 'feeItem' },
+  { key: 'category', prop: 'category', label: '费用分类', minWidth: 150 },
+  { key: 'tradeScope', label: '贸易范围', width: 110, slotName: 'tradeScope' },
+  { key: 'pickup', label: '提货', minWidth: 160, slotName: 'pickup' },
+  { key: 'warehouse', label: '仓库', minWidth: 160, slotName: 'warehouse' },
+  { key: 'supplierCategory', label: '供应商类别', width: 120, slotName: 'supplierCategory' },
+  { key: 'allocationFee', label: '分摊费', width: 100, slotName: 'allocationFee' },
+  { key: 'description', label: '说明', minWidth: 220, slotName: 'description', defaultVisible: false },
+  { key: 'createdByName', label: '创建人', minWidth: 120, formatter: (row: PlatformFeeItemResource) => row.createdByName || '—' },
+  { key: 'createdAt', label: '创建日期', minWidth: 155, formatter: (row: PlatformFeeItemResource) => formatTime(row.createdAt) },
+  { key: 'updatedByName', label: '更新人', minWidth: 120, formatter: (row: PlatformFeeItemResource) => row.updatedByName || '—' },
+  { key: 'updatedAt', label: '更新日期', minWidth: 155, formatter: (row: PlatformFeeItemResource) => formatTime(row.updatedAt) },
+  { key: 'status', label: '状态', width: 100, slotName: 'status' },
+]
+
+function optionalText(value: string | null) {
+  return value?.trim() || null
+}
+
+function formatTime(value?: string | null) {
+  return value?.replace('T', ' ').slice(0, 16) || '—'
+}
+
+function directionText(payable: boolean, receivable: boolean) {
+  if (payable && receivable) return '应付、应收'
+  if (payable) return '应付'
+  if (receivable) return '应收'
+  return '不适用'
+}
+
+async function loadFeeItems() {
+  if (!canView.value) {
+    rows.value = []
+    total.value = 0
+    loadError.value = null
+    return
+  }
+  const sequence = ++loadSequence
+  loading.value = true
+  loadError.value = null
+  try {
+    const result = await listPlatformFeeItems({
+      keyword: appliedFilters.value.keyword,
+      category: appliedFilters.value.category,
+      tradeScope: appliedFilters.value.tradeScope,
+      status: appliedFilters.value.status,
+      page: page.value,
+      size: pageSize.value,
+    })
+    if (sequence !== loadSequence) return
+    rows.value = result.records
+    total.value = result.total
+  } catch (error) {
+    if (sequence !== loadSequence) return
+    rows.value = []
+    total.value = 0
+    loadError.value = getApiErrorDetails(error, '费用项目加载失败，请稍后重试')
+  } finally {
+    if (sequence === loadSequence) loading.value = false
+  }
+}
+
+function applyFilters(model: QueryModel) {
+  appliedFilters.value = {
+    keyword: String(model.keyword || ''),
+    category: String(model.category || ''),
+    tradeScope: (model.tradeScope || '') as FeeItemTradeScope | '',
+    status: (model.status || '') as FeeItemStatus | '',
+  }
+  if (page.value === 1) void loadFeeItems()
+  else page.value = 1
+}
+
+function openCreate() {
+  editorSequence += 1
+  Object.assign(form, emptyForm())
+  captureBaseline()
+  editorOpen.value = true
+  void formRef.value?.clearValidate()
+}
+
+function assignForm(item: PlatformFeeItemResource) {
+  Object.assign(form, {
+    id: String(item.id),
+    category: item.category,
+    tradeScope: item.tradeScope,
+    feeTypeName: item.feeTypeName,
+    supplierCategory: item.supplierCategory,
+    pickupPayable: item.pickupPayable,
+    pickupReceivable: item.pickupReceivable,
+    warehousePayable: item.warehousePayable,
+    warehouseReceivable: item.warehouseReceivable,
+    allocationFee: item.allocationFee,
+    description: item.description,
+  })
+  captureBaseline()
+  editorOpen.value = true
+  void formRef.value?.clearValidate()
+}
+
+async function openEdit(item: PlatformFeeItemResource) {
+  const sequence = ++editorSequence
+  editorLoading.value = true
+  try {
+    const detail = await getPlatformFeeItem(item.id)
+    if (sequence === editorSequence) assignForm(detail)
+  } catch (error) {
+    if (sequence !== editorSequence) return
+    const details = getApiErrorDetails(error, '费用项目详情加载失败，请稍后重试')
+    ElMessage.error(details.requestId ? `${details.message}（requestId: ${details.requestId}）` : details.message)
+  } finally {
+    if (sequence === editorSequence) editorLoading.value = false
+  }
+}
+
+function buildPayload(): SavePlatformFeeItemRequest {
+  return {
+    category: form.category.trim(),
+    tradeScope: form.tradeScope,
+    feeTypeName: form.feeTypeName.trim(),
+    supplierCategory: hasPayableDirection.value ? form.supplierCategory : null,
+    pickupPayable: form.pickupPayable,
+    pickupReceivable: form.pickupReceivable,
+    warehousePayable: form.warehousePayable,
+    warehouseReceivable: form.warehouseReceivable,
+    allocationFee: form.allocationFee,
+    description: optionalText(form.description),
+  }
+}
+
+async function saveFeeItem() {
+  const valid = await formRef.value?.validate().catch(() => false)
+  if (!valid) return
+  if (hasPayableDirection.value && !form.supplierCategory) {
+    ElMessage.warning('启用应付方向时必须选择供应商类别')
+    return
+  }
+  saving.value = true
+  try {
+    if (form.id) await updatePlatformFeeItem(form.id, buildPayload())
+    else await createPlatformFeeItem(buildPayload())
+    editorOpen.value = false
+    ElMessage.success(form.id ? '费用项目已更新' : '费用项目已创建')
+    await loadFeeItems()
+  } catch (error) {
+    const details = getApiErrorDetails(error, '费用项目保存失败，请检查后重试')
+    ElMessage.error(details.requestId ? `${details.message}（requestId: ${details.requestId}）` : details.message)
+  } finally {
+    saving.value = false
+  }
+}
+
+function requestStatusChange(item: PlatformFeeItemResource) {
+  statusTarget.value = item
+  statusOpen.value = true
+}
+
+async function confirmStatusChange() {
+  const item = statusTarget.value
+  if (!item) return
+  const nextStatus: FeeItemStatus = item.status === 'ACTIVE' ? 'DISABLED' : 'ACTIVE'
+  const action = nextStatus === 'ACTIVE' ? '启用' : '停用'
+  const key = String(item.id)
+  statusLoadingIds.value = new Set(statusLoadingIds.value).add(key)
+  statusSaving.value = true
+  try {
+    await changePlatformFeeItemStatus(item.id, nextStatus)
+    ElMessage.success(`已${action}“${item.feeTypeName}”`)
+    statusOpen.value = false
+    statusTarget.value = null
+    await loadFeeItems()
+  } catch (error) {
+    const details = getApiErrorDetails(error, `${action}费用项目失败`)
+    ElMessage.error(details.requestId ? `${details.message}（requestId: ${details.requestId}）` : details.message)
+  } finally {
+    const pending = new Set(statusLoadingIds.value)
+    pending.delete(key)
+    statusLoadingIds.value = pending
+    statusSaving.value = false
+  }
+}
+
+function requestDelete(item: PlatformFeeItemResource) {
+  deleteTarget.value = item
+  deleteOpen.value = true
+}
+
+async function confirmDelete() {
+  if (!deleteTarget.value) return
+  deleting.value = true
+  try {
+    await deletePlatformFeeItem(deleteTarget.value.id)
+    ElMessage.success(`已删除“${deleteTarget.value.feeTypeName}”`)
+    deleteOpen.value = false
+    deleteTarget.value = null
+    if (rows.value.length === 1 && page.value > 1) page.value -= 1
+    else await loadFeeItems()
+  } catch (error) {
+    const details = getApiErrorDetails(error, '费用项目删除失败；已被业务使用的项目不能删除')
+    ElMessage.error(details.requestId ? `${details.message}（requestId: ${details.requestId}）` : details.message)
+  } finally {
+    deleting.value = false
+  }
+}
+
+watch([page, pageSize], () => void loadFeeItems())
+watch(
+  () => access.can(editorPermission.value),
+  (allowed) => {
+    if (!allowed && editorOpen.value) editorOpen.value = false
+  },
+  { flush: 'sync' },
+)
+
+onMounted(() => {
+  if (canView.value) void loadFeeItems()
+})
+</script>
+
+<template>
+  <AdminPage as="div" class="fee-items-page admin-density" spacing="normal">
+    <el-result v-if="!canView" icon="warning" title="无权查看费用项目" sub-title="请联系管理员开通费用项目查看权限" />
+
+    <ListPageLayout v-else aria-label="费用项目管理">
+      <template #toolbar>
+        <QueryToolbar
+          v-model="filters"
+          class="surface-panel"
+          ariaLabel="费用项目筛选"
+          :fields="queryFields"
+          :loading="loading"
+          preference-key="fee-items-query"
+          @search="applyFilters"
+        />
+      </template>
+
+      <template v-if="loadError" #state>
+        <LoadErrorState
+          title="费用项目加载失败"
+          :message="loadError.message"
+          :loading="loading"
+          @retry="loadFeeItems"
+        >
+          <template #details><ApiErrorMeta :details="loadError" /></template>
+        </LoadErrorState>
+      </template>
+
+      <section v-if="!loadError" class="surface-panel table-panel">
+        <DataTable
+          v-model:page="page"
+          v-model:page-size="pageSize"
+          :data="rows"
+          :columns="columns"
+          :loading="loading"
+          :total="total"
+          :page-sizes="[20, 50, 100]"
+          border
+          stripe
+          preference-key="fee-items-table"
+          aria-label="费用项目列表"
+          row-key="id"
+          empty-text="暂无符合条件的费用项目"
+        >
+          <template #toolbar-actions>
+            <el-button
+              v-if="access.can('firstleg:fee-item:create')"
+              type="primary"
+              :disabled="loading"
+              @click="openCreate"
+            ><Plus :size="16" />新增费用项目</el-button>
+          </template>
+          <template #actions="{ row }">
+            <div v-if="access.can('firstleg:fee-item:edit') || access.can('firstleg:fee-item:delete')" class="table-actions density-actions">
+              <el-button data-tone="neutral" class="density-action" v-if="access.can('firstleg:fee-item:edit')" size="small" :disabled="loading || editorLoading" @click="openEdit(row as PlatformFeeItemResource)">编辑</el-button>
+              <el-button class="density-action"
+                v-if="access.can('firstleg:fee-item:edit')"
+                size="small"
+
+                :data-tone="(row as PlatformFeeItemResource).status === 'ACTIVE' ? 'danger' : 'success'"
+                :loading="statusLoadingIds.has(String((row as PlatformFeeItemResource).id))"
+                :disabled="loading"
+                @click="requestStatusChange(row as PlatformFeeItemResource)"
+              >{{ (row as PlatformFeeItemResource).status === 'ACTIVE' ? '停用' : '启用' }}</el-button>
+              <el-button data-tone="danger" class="density-action" v-if="access.can('firstleg:fee-item:delete')" size="small" :disabled="loading" @click="requestDelete(row as PlatformFeeItemResource)">删除</el-button>
+            </div>
+            <span v-else class="muted-value">仅查看</span>
+          </template>
+          <template #feeItem="{ row }"><div class="fee-item-name"><strong>{{ (row as PlatformFeeItemResource).feeTypeName }}</strong>
+            <!-- <small>{{ (row as PlatformFeeItemResource).feeCode || '未分配编码' }}</small> -->
+          </div></template>
+          <template #tradeScope="{ row }"><el-tag effect="plain">{{ (row as PlatformFeeItemResource).tradeScope === 'DOMESTIC' ? '国内' : '国际' }}</el-tag></template>
+          <template #pickup="{ row }">{{ directionText((row as PlatformFeeItemResource).pickupPayable, (row as PlatformFeeItemResource).pickupReceivable) }}</template>
+          <template #warehouse="{ row }">{{ directionText((row as PlatformFeeItemResource).warehousePayable, (row as PlatformFeeItemResource).warehouseReceivable) }}</template>
+          <template #supplierCategory="{ row }">{{ (row as PlatformFeeItemResource).supplierCategory ? categoryLabels[(row as PlatformFeeItemResource).supplierCategory as SupplierCategory] : '未配置' }}</template>
+          <template #allocationFee="{ row }">{{ (row as PlatformFeeItemResource).allocationFee ? '是' : '否' }}</template>
+          <template #description="{ row }"><span class="description-cell">{{ (row as PlatformFeeItemResource).description || '—' }}</span></template>
+          <template #status="{ row }"><el-tag :type="(row as PlatformFeeItemResource).status === 'ACTIVE' ? 'success' : 'info'">{{ (row as PlatformFeeItemResource).status === 'ACTIVE' ? '启用' : '停用' }}</el-tag></template>
+          <template #empty>
+            <el-empty v-if="!loading" description="暂无符合条件的费用项目">
+              <el-button v-if="access.can('firstleg:fee-item:create')" type="primary" @click="openCreate"><Plus :size="16" />新增第一项费用</el-button>
+            </el-empty>
+          </template>
+          <template #pagination-left>平台公共主数据 · 共 {{ total }} 项</template>
+        </DataTable>
+      </section>
+    </ListPageLayout>
+
+    <AppDrawer class="admin-density admin-density-drawer"
+      v-model="editorOpen"
+      :title="editorTitle"
+      size="min(620px, 94vw)"
+      :loading="editorLoading"
+      :confirm-loading="saving"
+    >
+      <el-form class="density-form" ref="formRef" :model="form" :rules="rules" label-position="top" :disabled="saving || editorLoading">
+        <FormSection class="density-form-section" title="基本信息" description="费用项目为平台公共主数据，不按客户单独维护。">
+          <div class="form-grid two-cols">
+            <el-form-item label="费用名称" prop="feeTypeName" required><el-input v-model="form.feeTypeName" maxlength="128" placeholder="请输入费用名称" /></el-form-item>
+            <el-form-item label="费用分类" prop="category" required><el-input v-model="form.category" maxlength="64" placeholder="例如 仓储成本" /></el-form-item>
+          </div>
+          <el-form-item label="贸易范围" prop="tradeScope" required>
+            <el-segmented v-model="form.tradeScope" :options="[{ label: '国内', value: 'DOMESTIC' }, { label: '国际', value: 'INTERNATIONAL' }]" />
+          </el-form-item>
+        </FormSection>
+        <FormSection class="density-form-section" title="费用方向" description="选择费用在提货和仓库环节的应收、应付属性。">
+          <div class="direction-grid">
+            <fieldset><legend>提货环节</legend><el-checkbox v-model="form.pickupPayable">应付</el-checkbox><el-checkbox v-model="form.pickupReceivable">应收</el-checkbox></fieldset>
+            <fieldset><legend>仓库环节</legend><el-checkbox v-model="form.warehousePayable">应付</el-checkbox><el-checkbox v-model="form.warehouseReceivable">应收</el-checkbox></fieldset>
+          </div>
+          <el-checkbox v-model="form.allocationFee">作为分摊费用</el-checkbox>
+          <el-form-item v-if="hasPayableDirection" label="供应商类别" required>
+            <el-select v-model="form.supplierCategory" placeholder="请选择 Warehouse 供应商类别">
+              <el-option v-for="(label, value) in categoryLabels" :key="value" :label="label" :value="value" />
+            </el-select>
+          </el-form-item>
+        </FormSection>
+        <FormSection class="density-form-section" title="适用说明" :bordered="false">
+          <el-form-item label="说明"><el-input v-model="form.description" type="textarea" :rows="4" maxlength="500" show-word-limit placeholder="请输入适用场景或核算说明" /></el-form-item>
+        </FormSection>
+      </el-form>
+      <template #footer>
+        <div class="drawer-footer">
+          <el-button :disabled="saving" @click="editorOpen = false">取消</el-button>
+          <el-button type="primary" :loading="saving" :disabled="editorLoading" @click="saveFeeItem"><Save :size="16" />保存费用项目</el-button>
+        </div>
+      </template>
+    </AppDrawer>
+
+    <AppDialog class="admin-density-dialog"
+      v-model="statusOpen"
+      :title="statusTarget?.status === 'ACTIVE' ? '停用费用项目' : '启用费用项目'"
+      :confirm-text="statusTarget?.status === 'ACTIVE' ? '确认停用' : '确认启用'"
+      :confirm-type="statusTarget?.status === 'ACTIVE' ? 'warning' : 'success'"
+      :confirm-loading="statusSaving"
+      @confirm="confirmStatusChange"
+    >
+      <p class="delete-message">
+        确定{{ statusTarget?.status === 'ACTIVE' ? '停用' : '启用' }}“<strong>{{ statusTarget?.feeTypeName }}</strong>”吗？
+        <template v-if="statusTarget?.status === 'ACTIVE'">停用后该项目不能再用于新的费用记录。</template>
+      </p>
+    </AppDialog>
+
+    <AppDialog class="admin-density-dialog"
+      v-model="deleteOpen"
+      title="删除费用项目"
+      confirm-text="确认删除"
+      confirm-type="danger"
+      :confirm-loading="deleting"
+      @confirm="confirmDelete"
+    >
+      <p class="delete-message">确定删除“<strong>{{ deleteTarget?.feeTypeName }}</strong>”吗？删除后无法恢复；已被业务单据使用的项目将由服务端拒绝删除。</p>
+    </AppDialog>
+  </AdminPage>
+</template>
+
+<style scoped>
+.fee-items-page { min-width: 0; }
+.fee-item-name { display: flex; min-width: 0; flex-direction: column; gap: var(--admin-space-1); }
+.fee-item-name strong { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.fee-item-name small { color: var(--cc-muted); font-size: var(--admin-font-caption); }
+.description-cell { display: -webkit-box; overflow: hidden; line-height: 1.5; -webkit-box-orient: vertical; -webkit-line-clamp: 2; }
+.direction-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: var(--admin-space-5); margin-bottom: var(--admin-space-5); }
+.direction-grid fieldset { min-width: 0; margin: 0; padding: var(--admin-space-5); border: 1px solid var(--el-border-color); border-radius: var(--admin-radius); }
+.direction-grid legend { padding: 0 5px; color: var(--el-text-color-secondary); font-size: var(--admin-font-body); }
+.delete-message { margin: 0; color: var(--el-text-color-regular); line-height: 1.7; overflow-wrap: anywhere; }
+@media (max-width: 720px) {
+  .direction-grid, .form-grid.two-cols { grid-template-columns: 1fr; }
+  .table-actions { flex-wrap: wrap; }
+}
+</style>
diff --git a/src/modules/fee-items/routes.test.ts b/src/modules/fee-items/routes.test.ts
new file mode 100644
index 00000000..1c0bc885
--- /dev/null
+++ b/src/modules/fee-items/routes.test.ts
@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest'
+import { feeItemRoutes } from './routes'
+
+describe('fee item routes', () => {
+  it('registers the formal platform master-data management page', () => {
+    expect(feeItemRoutes).toHaveLength(1)
+    expect(feeItemRoutes[0]).toMatchObject({
+      path: 'master-data/fee-items',
+      name: 'fee-items',
+      meta: {
+        description: '统一维护平台公共费用项目及其适用范围',
+        permission: 'firstleg:fee-item:view',
+      },
+    })
+  })
+})
diff --git a/src/modules/fee-items/routes.ts b/src/modules/fee-items/routes.ts
new file mode 100644
index 00000000..47c9d87b
--- /dev/null
+++ b/src/modules/fee-items/routes.ts
@@ -0,0 +1,14 @@
+import type { RouteRecordRaw } from 'vue-router'
+
+export const feeItemRoutes = [
+  {
+    path: 'master-data/fee-items',
+    name: 'fee-items',
+    component: () => import('@/modules/fee-items/pages/FeeItemsView.vue'),
+    meta: {
+      title: '费用项目',
+      description: '统一维护平台公共费用项目及其适用范围',
+      permission: 'firstleg:fee-item:view',
+    },
+  },
+] satisfies RouteRecordRaw[]
diff --git a/src/modules/finance/AGENTS.md b/src/modules/finance/AGENTS.md
new file mode 100644
index 00000000..b90db654
--- /dev/null
+++ b/src/modules/finance/AGENTS.md
@@ -0,0 +1,33 @@
+# Admin Finance Module Instructions
+
+## 范围与入口
+
+- 本文件适用于 `src/modules/finance/`。产品范围和状态读取 `../../../../../docs/财务管理/` 的产品确认与验收契约，后端读取 `../../../../../baiyue-firstleg/finance/AGENTS.md`。
+- 页面从 `pages/` 进入，统一 API 从 `api/finance.ts` 进入；费用来源和柜次成本快照联查 `firstleg/`，凭证与异步导出联查 `file/`。
+- 正式范围包括客户资金账户、充值申请审核、平台手工充值/扣款、授信额度维护、客户应收应付、应收款统计、客户对账单、应收结算单和应付结算单。业务冻结/结算/释放由服务端内部接口和跨区事件调用，不在 Admin 页面复制；第三方支付回调尚未接入，不要从历史原型自动扩大其他财务功能。
+
+## 客户资金账户
+
+- `pages/FinanceCustomerAccountsView.vue` 的列表和详情展示实际余额、冻结金额、授信额度、授信有效期、已用授信、冻结授信和总可用余额；操作列固定第一列。授信到期日必须晚于今天且不限制最远日期，到期日当天仍有效。客户上传的充值申请在详情内按待审核优先展示，审核、驳回及凭证预览以服务端申请版本和客户归属为准。
+- 平台手工充值、扣款和授信调整必须提交账户版本与幂等键；扣款及授信下限由服务端校验。页面只展示服务端余额、授信和流水结果，不在浏览器补算或回退静态数据。
+
+## 客户筛选与统计
+
+- 六个正式列表页统一加载全部 `ACTIVE` 客户并使用可筛选下拉框；用户可见选项只显示 `tenantName`，以 `customerId` 作为接口筛选值。
+- 不恢复自由输入客户关键词，不把客户编码、联系人或手机号拼入下拉标签；业务单号和费用项目继续使用独立筛选字段。
+- 应收款统计从 `pages/FinanceReceivableStatisticsView.vue`、`api/finance.ts` 进入，只汇总指定生成月份的 CNY 正式应收结算单。
+- 统计月份使用 `yyyy-MM`；当前页打印留在页面，Excel 通过 `FINANCE_RECEIVABLE_STATISTICS` 进入 File 下载中心异步导出。
+
+## 费用付款与凭证快速入口
+
+- 入库费用的应付/直接已付表单在 `../unified-orders/components/InboundFeeDetailManager.vue`，柜次费用在 `../loading-lists/components/ContainerFeesPanel.vue`；柜级公共费用在同一面板按服务端返回的真实客户与订单分摊，入仓 ID/入仓码同时选填或同时为空；对应 API 分别为 `../unified-orders/api/inboundFeeDetails.ts`、`../loading-lists/api/containerFees.ts`。
+- 柜级分摊请求的各行金额之和必须精确等于公共费用总额；创建后使用 `allocationGroupId` 整组审核、驳回、调整或作废，前端不得调用单行接口造成部分成功，也不得提交柜外客户、订单或入仓归属。
+- `DIRECT_PAID` 必须提交已付时间、付款方式，以及付款流水号或至少一个付款凭证；凭证由费用 API 调用 `/platform/finance/v1/vouchers` 上传为 `FINANCE_VOUCHER`，并绑定当前客户。
+- 后端事实入口为 Firstleg `FeePaymentSnapshotValidator`、入库/柜次费用服务，文件元数据归 File；Finance 只消费已发布的费用来源快照，不在前端或 Finance 中重建付款事实。
+- 财务与柜级公共费用分摊统一从 `pages/` 和 `api/finance.ts` 进入；`allocationGroupId` 整组审核、驳回、调整或作废，不允许按单条分摊明细绕过整组状态机。
+
+## 权限与验证
+
+- 列表和详情只读遵守 `*:list` 统一语义；确认、审核、导出、上传等写入或产出文件的动作继续使用独立权限。
+- 修改筛选、DTO 或请求参数时同步检查页面、API 类型、Mock/Fixture、测试、Finance OpenAPI 和实际消费者。
+- 至少运行 Finance 模块受影响测试和 `pnpm typecheck`；交付前按项目指引运行 `pnpm test` 与 `pnpm build`。
diff --git a/src/modules/finance/api/finance.test.ts b/src/modules/finance/api/finance.test.ts
new file mode 100644
index 00000000..6fe6106f
--- /dev/null
+++ b/src/modules/finance/api/finance.test.ts
@@ -0,0 +1,313 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import { actionReconciliationStatement, adjustFinanceAccount, adjustFinanceBill, createFinanceCost, createFinanceReceipt, createFinanceSettlementPayment, createPayableSettlement, createReceivableSettlement, createReconciliationStatement, downloadFinanceRechargeVoucher, editFinanceFeeSource, getFinanceBill, getFinanceCustomerAccount, getFinanceCustomerAccountSummary, getFinanceCustomerTerms, getFinanceFeeSource, getFinanceSettlement, getReceivableStatistics, getReconciliationStatement, listFinanceAccountLedger, listFinanceAccounts, listFinanceBillRevisions, listFinanceFeePool, listFinanceFeeSources, listFinancePayableSettlements, listFinanceReceivableSettlements, listFinanceRechargeRequests, listFinanceStatements, reviewFinanceFeeSource, reviewFinanceRechargeRequest, updateFinanceBill, updateFinanceCreditLimit, updateFinanceCustomerTerms, uploadFinanceVoucher, voidFinanceBill } from './finance'
+
+describe('finance api', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('queries the dedicated monthly CNY receivable statistics read model', async () => {
+    const get = vi.spyOn(http, 'get').mockResolvedValue({ code: '200', data: {
+      statisticsMonth: '2026-07', currency: 'CNY', totalReceivable: '300.000000', totalReceived: '100.000000',
+      totalOutstanding: '200.000000', totalCustomers: 1, page: 1, pageSize: 20,
+      records: [{ customerId: '9007199254740993', customerName: '客户A', currency: 'CNY', totalReceivable: '300.000000', totalReceived: '100.000000', totalOutstanding: '200.000000' }],
+    } })
+
+    const result = await getReceivableStatistics({ month: '2026-07', customerId: '9007199254740993', page: 1, pageSize: 20 })
+
+    expect(get).toHaveBeenCalledWith('/platform/finance/v1/receivable-statistics', { params: { month: '2026-07', customerId: '9007199254740993', page: 1, pageSize: 20 } })
+    expect(result).toMatchObject({ currency: 'CNY', totalReceivable: '300.000000', totalReceived: '100.000000', totalOutstanding: '200.000000', records: [{ customerId: '9007199254740993', customerName: '客户A' }] })
+  })
+
+  it('uses only the formal settlement customer summary and keeps money as decimal strings', async () => {
+    const get = vi.spyOn(http, 'get').mockResolvedValue({ code: '200', data: { customerId: '9007199254740993', currency: 'CNY', totalReceivable: '123456.780000', receivedAmount: '100000.000000', outstandingReceivable: '23456.780000', pendingBilling: '0.000000', totalCost: '300.000000', paidCost: '200.000000', outstandingPayable: '100.000000', asOf: '2026-08-13T04:00:00Z', lastChangedAt: null } })
+
+    const result = await getFinanceCustomerAccountSummary('9007199254740993')
+
+    expect(get).toHaveBeenCalledWith('/platform/finance/v1/customer-accounts/9007199254740993/summary')
+    expect(result).toMatchObject({ customerId: '9007199254740993', currency: 'CNY', totalReceivable: '123456.780000', outstandingReceivable: '23456.780000' })
+  })
+
+  it('uses the customer statement read-model path', async () => {
+    const get = vi.spyOn(http, 'get').mockResolvedValue({
+      code: '200', message: 'ok', data: [{ statementId: 1, customerId: 10001, statementNo: 'B-1', customerName: '客户A', periodStart: '2026-08-01', periodEnd: '2026-08-31', creditDays: 30, lineCount: 3, sourceCount: 2, sourceAmount: 120, adjustmentAmount: -20, totalReceivable: 100, receivedAmount: 0, outstandingAmount: 100, settled: false, submittedAt: '2026-08-02T09:00:00', reviewedAt: '2026-08-03T09:00:00', issuedAt: null, status: 'DRAFT', version: 2, customerConfirmationStatus: 'NOT_REQUIRED', createdBy: 7, createdByName: '创建人A', updatedBy: 8, updatedByName: '更新人B' }],
+    })
+
+    const result = await listFinanceStatements('10001')
+
+    expect(get).toHaveBeenCalledWith('/platform/finance/v1/statements', { params: { customerId: '10001' } })
+    expect(result[0]).toMatchObject({ id: '1', customerId: '10001', billNo: 'B-1', periodStart: '2026-08-01', periodEnd: '2026-08-31', lineCount: 3, sourceCount: 2, sourceAmount: 120, adjustmentAmount: -20, currency: 'CNY', status: 'DRAFT', version: 2, customerConfirmationStatus: 'NOT_REQUIRED', createdBy: '7', createdByName: '创建人A', updatedBy: '8', updatedByName: '更新人B' })
+  })
+
+  it('never serializes an empty customerId for optional finance list filters', async () => {
+    const get = vi.spyOn(http, 'get').mockResolvedValue({ code: '200', message: 'ok', data: [] })
+
+    await listFinanceFeePool('')
+    await listFinanceStatements('   ')
+    await listFinanceReceivableSettlements()
+    await listFinancePayableSettlements('')
+
+    expect(get.mock.calls).toEqual([
+      ['/platform/finance/v1/fee-pool', { params: { customerId: undefined, direction: undefined } }],
+      ['/platform/finance/v1/statements', { params: { customerId: undefined } }],
+      ['/platform/finance/v1/receivable-settlements', { params: { customerId: undefined } }],
+      ['/platform/finance/v1/payable-settlements', { params: { customerId: undefined } }],
+    ])
+  })
+
+  it('includes a supplier filter only for payable fee-pool requests', async () => {
+    const get = vi.spyOn(http, 'get').mockResolvedValue({ code: '200', message: 'ok', data: [] })
+
+    await listFinanceFeePool('10001', 'PAYABLE', '301')
+
+    expect(get).toHaveBeenCalledWith('/platform/finance/v1/fee-pool', {
+      params: { customerId: '10001', direction: 'PAYABLE', supplierId: '301' },
+    })
+  })
+
+  it('preserves settlement mode from fee-pool candidates for client-side eligibility checks', async () => {
+    vi.spyOn(http, 'get').mockResolvedValue({ code: '200', message: 'ok', data: [{
+      poolItemId: 'PAYABLE:42', customerId: 10001, direction: 'PAYABLE', sourceType: 'INBOUND_FEE', sourceId: 42,
+      sourceVersion: 1, feeItemName: '进仓费', amount: 33, currency: 'CNY', settlementMode: 'DIRECT_PAID',
+      status: 'AVAILABLE', createdAt: '2026-08-26T00:00:00',
+    }] })
+
+    const [candidate] = await listFinanceFeePool('10001', 'PAYABLE', '301')
+
+    expect(candidate.settlementMode).toBe('DIRECT_PAID')
+  })
+
+  it('uses the formal G1 account list path and fixed page DTO', async () => {
+    const get = vi.spyOn(http, 'get').mockResolvedValue({ code: '200', message: 'success', requestId: 'req-g1', traceId: 'trace-g1', data: [{ customerId: 10001, customerCode: 'C-10001', customerName: '客户A', contactName: '张三', contactPhone: '13800000000', outstandingReceivable: 300, pendingBilling: 50, receivedInPeriod: 100, totalCost: 260, paidCost: 180, outstandingPayable: 80, status: 'ACTIVE', lastChangedAt: '2026-08-11T10:00:00', actualBalance: '126580.50', frozenBalance: '8500.00', availableBalance: '138080.50', creditLimit: '20000.00', creditUsed: '0.00', availableCredit: '20000.00', creditExpiresOn: '2028-09-10', creditActive: true, accountVersion: 7, pendingRechargeCount: 2 }], page: { page: 2, pageSize: 20, total: 21 } })
+
+    const result = await listFinanceAccounts({ page: 2, size: 20, customerId: '10001', status: 'ACTIVE' })
+
+    expect(get).toHaveBeenCalledWith('/platform/finance/v1/accounts', { params: { page: 2, pageSize: 20, customerId: '10001', status: 'ACTIVE' } })
+    expect(result).toEqual({ records: [{ customerId: '10001', customerCode: 'C-10001', customerName: '客户A', contactName: '张三', contactPhone: '13800000000', outstandingReceivable: 300, pendingBilling: 50, receivedInPeriod: 100, totalCost: 260, paidCost: 180, outstandingPayable: 80, status: 'ACTIVE', lastChangedAt: '2026-08-11T10:00:00', actualBalance: '126580.50', frozenBalance: '8500.00', availableBalance: '138080.50', creditLimit: '20000.00', creditUsed: '0.00', availableCredit: '20000.00', creditExpiresOn: '2028-09-10', creditActive: true, accountVersion: 7, pendingRechargeCount: 2 }], total: 21, pages: 2 })
+  })
+
+  it('uses the formal G1 account ledger path and fixed page DTO', async () => {
+    const get = vi.spyOn(http, 'get').mockResolvedValue({ code: '200', message: 'success', requestId: 'req-ledger', traceId: 'trace-ledger', data: [{ ledgerId: 81, occurredAt: '2026-08-11T12:00:00', businessType: 'RECEIPT', documentType: 'SETTLEMENT', documentId: 91, documentNo: 'AR-91', receivableChange: -100, payableChange: 0, outstandingReceivableAfter: 200, operatorName: '财务A', remark: '人工收款', businessNo: 'AC202608110001', changeType: 'RECHARGE', amount: '500.00', actualBalanceAfter: '1500.00', frozenBalanceAfter: '100.00', availableBalanceAfter: '1400.00', sourceType: 'MANUAL_ADJUSTMENT', sourceNo: 'RC-91', createdAt: '2026-08-11T12:00:00' }], page: { page: 1, pageSize: 50, total: 1 } })
+
+    const result = await listFinanceAccountLedger('10001', { page: 1, size: 50, businessType: 'RECEIPT', startDate: '2026-08-01', endDate: '2026-08-31' })
+
+    expect(get).toHaveBeenCalledWith('/platform/finance/v1/accounts/10001/ledger', { params: { page: 1, pageSize: 50, businessType: 'RECEIPT', startDate: '2026-08-01', endDate: '2026-08-31' } })
+    expect(result.records[0]).toMatchObject({ ledgerId: '81', businessNo: 'AC202608110001', changeType: 'RECHARGE', amount: '500.00', actualBalanceAfter: '1500.00', frozenBalanceAfter: '100.00', availableBalanceAfter: '1400.00', sourceNo: 'RC-91' })
+  })
+
+  it('uses frozen recharge review and account adjustment contracts', async () => {
+    const get = vi.spyOn(http, 'get').mockResolvedValue({ code: '200', message: 'ok', data: [{ requestId: 91, requestNo: 'RC-91', amount: '500.00', paymentMethod: 'WECHAT', voucherFileId: 81, voucherFileName: 'receipt.png', status: 'PENDING', version: 3, submittedByName: '客户A', createdAt: '2026-09-04T10:00:00' }], page: { page: 1, pageSize: 200, total: 1 } })
+    const post = vi.spyOn(http, 'post')
+      .mockResolvedValueOnce({ code: '200', message: 'ok', data: { requestId: 91, requestNo: 'RC-91', amount: '500.00', paymentMethod: 'WECHAT', voucherFileId: 81, voucherFileName: 'receipt.png', status: 'APPROVED', version: 4 } })
+      .mockResolvedValueOnce({ code: '200', message: 'ok', data: { ledgerId: 101, businessNo: 'AC-101', changeType: 'DEDUCTION', amount: '-100.00', actualBalanceAfter: '1400.00', frozenBalanceAfter: '100.00', availableBalanceAfter: '1300.00' } })
+
+    const requests = await listFinanceRechargeRequests('10001')
+    await reviewFinanceRechargeRequest('91', { decision: 'APPROVE', remark: '凭证有效', expectedVersion: 3 })
+    const ledger = await adjustFinanceAccount('10001', { type: 'DEDUCTION', amount: '100.00', occurredDate: '2026-09-04', paymentMethod: 'BANK_TRANSFER', referenceNo: 'OUT-1', remark: '贴牌费', expectedAccountVersion: 7 })
+
+    expect(get).toHaveBeenCalledWith('/platform/finance/v1/accounts/10001/recharge-requests', { params: { page: 1, pageSize: 200 } })
+    expect(requests.records[0]).toMatchObject({ requestId: '91', voucherFileId: '81', amount: '500.00', version: 3 })
+    expect(post).toHaveBeenNthCalledWith(1, '/platform/finance/v1/recharge-requests/91/review', { decision: 'APPROVE', remark: '凭证有效', expectedVersion: 3 }, { headers: { 'Idempotency-Key': expect.any(String) } })
+    expect(post).toHaveBeenNthCalledWith(2, '/platform/finance/v1/accounts/10001/adjustments', { type: 'DEDUCTION', amount: '100.00', occurredDate: '2026-09-04', paymentMethod: 'BANK_TRANSFER', referenceNo: 'OUT-1', remark: '贴牌费', expectedAccountVersion: 7 }, { headers: { 'Idempotency-Key': expect.any(String) } })
+    expect(ledger).toMatchObject({ ledgerId: 101, businessNo: 'AC-101', changeType: 'DEDUCTION', amount: '-100.00' })
+  })
+
+  it('updates the customer credit limit with account version and idempotency', async () => {
+    const put = vi.spyOn(http, 'put').mockResolvedValue({ code: '200', message: 'ok', data: { ledgerId: 102, businessNo: 'AC-102', changeType: 'CREDIT_LIMIT', amount: '20000.00', creditLimitAfter: '20000.00', creditUsedAfter: '0.00', availableCreditAfter: '20000.00' } })
+
+    const result = await updateFinanceCreditLimit('10001', { creditLimit: '20000.00', creditExpiresOn: '2028-09-10', remark: '初始化授信', expectedAccountVersion: 7 })
+
+    expect(put).toHaveBeenCalledWith('/platform/finance/v1/accounts/10001/credit-limit', { creditLimit: '20000.00', creditExpiresOn: '2028-09-10', remark: '初始化授信', expectedAccountVersion: 7 }, { headers: { 'Idempotency-Key': expect.any(String) } })
+    expect(result).toMatchObject({ ledgerId: 102, changeType: 'CREDIT_LIMIT', creditLimitAfter: '20000.00', availableCreditAfter: '20000.00' })
+  })
+
+  it('downloads a recharge voucher as an authenticated blob', async () => {
+    const blob = new Blob(['image'], { type: 'image/png' })
+    const get = vi.spyOn(http, 'get').mockResolvedValue(blob)
+    await expect(downloadFinanceRechargeVoucher('91/2')).resolves.toBe(blob)
+    expect(get).toHaveBeenCalledWith('/platform/finance/v1/recharge-requests/91%2F2/voucher', { responseType: 'blob' })
+  })
+
+  it('uses the formal paged fee-source path and preserves independent business fields', async () => {
+    const get = vi.spyOn(http, 'get').mockResolvedValue({
+      code: '200', message: 'success', requestId: 'req-fees', traceId: 'trace-fees',
+      data: [{ feeSourceId: 42, sourceSystem: 'FIRSTLEG', sourceType: 'INBOUND_FEE', sourceBusinessId: 'IB-91', sourceFeeId: 81, sourceVersion: 3, direction: 'PAYABLE', customerId: 10001, customerName: '客户A', supplierId: 71, supplierName: '供应商A', orderId: 11, inboundId: 91, inboundCode: 'IB-91', containerId: 31, containerNo: 'CONT-31', businessDate: '2026-08-11', feeItemName: '运费', quantity: 2, unitPrice: 50, amount: 100, currency: 'CNY', reviewStatus: 'APPROVED', sourceStatus: 'AVAILABLE', statementGenerated: false }],
+      page: { page: 2, pageSize: 50, total: 51 },
+    })
+
+    const result = await listFinanceFeeSources({ page: 2, size: 50, customerId: '10001', direction: 'PAYABLE', status: 'AVAILABLE', reviewStatus: 'APPROVED', statementGenerated: false, businessDateFrom: '2026-08-01', businessDateTo: '2026-08-31', keyword: ' IB-91 ' })
+
+    expect(get).toHaveBeenCalledWith('/platform/finance/v1/fee-sources', { params: {
+      page: 2, pageSize: 50, customerId: '10001', direction: 'PAYABLE', status: 'AVAILABLE', reviewStatus: 'APPROVED', statementGenerated: false, businessDateFrom: '2026-08-01', businessDateTo: '2026-08-31', keyword: 'IB-91',
+    } })
+    expect(result).toMatchObject({ total: 51, pages: 2, records: [{ feeSourceId: '42', sourceSystem: 'FIRSTLEG', sourceBusinessId: 'IB-91', supplierName: '供应商A', inboundCode: 'IB-91', containerNo: 'CONT-31', businessDate: '2026-08-11', reviewStatus: 'APPROVED', statementGenerated: false }] })
+  })
+
+  it('uses fixed read-model paths for all five finance pages', async () => {
+    const get = vi.spyOn(http, 'get')
+      .mockResolvedValueOnce({ code: '200', message: 'ok', data: { customerId: 10001, totalReceivable: 300, totalReceived: 100, outstandingAmount: 200, entries: [] } })
+      .mockResolvedValueOnce({ code: '200', message: 'ok', data: [{ poolItemId: 9, customerId: 10001, direction: 'PAYABLE', sourceType: 'CONTAINER_COST', sourceId: 81, sourceVersion: 2, containerId: 81, feeItemName: '拖车费', amount: 680.5, status: 'OPEN' }] })
+      .mockResolvedValueOnce({ code: '200', message: 'ok', data: [] })
+      .mockResolvedValueOnce({ code: '200', message: 'ok', data: [{ settlementId: 81, customerId: 10001, settlementNo: 'AR-81', direction: 'RECEIVABLE', totalAmount: 300, paidAmount: 100, outstandingAmount: 200, generatedDate: '2026-08-11', status: 'PARTIALLY_PAID', version: 2 }] })
+      .mockResolvedValueOnce({ code: '200', message: 'ok', data: [{ settlementId: 71, customerId: 10001, settlementNo: 'AP-71', direction: 'PAYABLE', supplierName: '供应商A', totalAmount: 680.5, paidAmount: 0, outstandingAmount: 680.5, generatedDate: '2026-08-11', status: 'ISSUED', version: 1 }] })
+
+    const account = await getFinanceCustomerAccount('10001')
+    const pool = await listFinanceFeePool('10001', 'PAYABLE')
+    await listFinanceStatements('10001')
+    const receivables = await listFinanceReceivableSettlements('10001')
+    const payables = await listFinancePayableSettlements('10001')
+
+    expect(get.mock.calls.map(([path]) => path)).toEqual([
+      '/platform/finance/v1/customer-accounts/10001',
+      '/platform/finance/v1/fee-pool',
+      '/platform/finance/v1/statements',
+      '/platform/finance/v1/receivable-settlements',
+      '/platform/finance/v1/payable-settlements',
+    ])
+    expect(account).toMatchObject({ customerId: '10001', currency: 'CNY', accountMode: 'MANUAL_RECEIVABLE_LEDGER', outstandingAmount: 200 })
+    expect(pool[0]).toMatchObject({ poolItemId: '9', customerId: '10001', sourceId: '81', sourceVersion: 2, containerId: '81', feeItemName: '拖车费', amount: 680.5 })
+    expect(receivables[0]).toMatchObject({ id: '81', settlementNo: 'AR-81', currency: 'CNY' })
+    expect(payables[0]).toMatchObject({ id: '71', settlementNo: 'AP-71', supplierName: '供应商A', payableAmount: 680.5, currency: 'CNY' })
+  })
+
+  it('derives the numeric fee source id without treating manual costs as reviewable sources', async () => {
+    vi.spyOn(http, 'get').mockResolvedValue({ code: '200', message: 'ok', data: [
+      { poolItemId: 'RECEIVABLE:42', customerId: 10001, direction: 'RECEIVABLE', sourceType: 'INBOUND_FEE', sourceId: 81, sourceVersion: 3, feeItemName: '运费', amount: 100, status: 'AVAILABLE' },
+      { poolItemId: 'PAYABLE:43', customerId: 10002, direction: 'PAYABLE', sourceType: 'MANUAL_COST', sourceId: 43, sourceVersion: 1, feeItemName: '拖车费', amount: 200, status: 'POSTED' },
+    ] })
+
+    const result = await listFinanceFeePool('10001')
+
+    expect(result.map((item) => item.feeSourceId)).toEqual(['42', null])
+  })
+
+  it('uses the formal fee-source detail, review and edit contracts', async () => {
+    const detail = { feeSourceId: 42, sourceType: 'INBOUND_FEE', sourceFeeId: 81, sourceVersion: 3, direction: 'RECEIVABLE', customerId: 10001, customerName: '客户A', inboundId: 91, inboundCode: 'IB-91', businessDate: '2026-08-11', feeItemName: '运费', quantity: 2, unitPrice: 50, amount: 100, currency: 'CNY', reviewStatus: 'APPROVED', sourceStatus: 'AVAILABLE', statementGenerated: false, operationVersion: 4, operationLogs: [{ occurredAt: '2026-08-11T12:00:00', action: 'FEE_SOURCE_REVIEW_APPROVE', operatorName: '财务A', result: 'SUCCESS' }] }
+    const get = vi.spyOn(http, 'get').mockResolvedValue({ code: '200', message: 'success', requestId: 'req-g2', traceId: 'trace-g2', data: detail })
+    const post = vi.spyOn(http, 'post').mockResolvedValue({ code: '200', message: 'success', data: detail })
+    const put = vi.spyOn(http, 'put').mockResolvedValue({ code: '200', message: 'success', data: detail })
+
+    const result = await getFinanceFeeSource('42')
+    await reviewFinanceFeeSource('42', { action: 'APPROVE', reason: '核对无误', expectedVersion: 3 })
+    await editFinanceFeeSource('42', { amount: 120, reason: '更正金额', expectedVersion: 4 })
+
+    expect(get).toHaveBeenCalledWith('/platform/finance/v1/fee-sources/42')
+    expect(post).toHaveBeenCalledWith('/platform/finance/v1/fee-sources/42/review', { action: 'APPROVE', reason: '核对无误', expectedVersion: 3 }, { headers: { 'Idempotency-Key': expect.any(String) } })
+    expect(put).toHaveBeenCalledWith('/platform/finance/v1/fee-sources/42', { amount: 120, reason: '更正金额', expectedVersion: 4 }, { headers: { 'Idempotency-Key': expect.any(String) } })
+    expect(result).toMatchObject({ feeSourceId: '42', sourceId: '81', customerId: '10001', inboundId: '91', reviewStatus: 'APPROVED', operationVersion: 4, currency: 'CNY' })
+  })
+
+  it('uses the frozen G3 reconciliation create and action contracts', async () => {
+    const detail = { statementId: 501, statementNo: 'REC-501', customerId: 10001, customerName: '客户A', periodStart: '2026-08-01', periodEnd: '2026-08-31', creditDays: 30, currency: 'CNY', totalReceivable: 100, receivedAmount: 0, outstandingAmount: 100, settled: false, status: 'ISSUED', version: 4, customerConfirmationStatus: 'CONFIRMED', customerConfirmedBy: 17, customerConfirmedByName: '客户确认人', customerConfirmedAt: '2026-08-05T10:00:00', createdBy: 7, createdByName: '创建人A', createdAt: '2026-08-01T09:00:00', updatedBy: 8, updatedByName: '更新人B', updatedAt: '2026-08-02T10:00:00', lines: [{ statementLineId: 601, feeSourceId: 42, sourceVersion: 3, sourceHash: 'hash-42', direction: 'RECEIVABLE', sourceType: 'CONTAINER_FEE', sourceNo: 'CONT-31', orderId: 11, inboundId: 21, inboundCode: 'IN-21', containerId: 31, containerNo: 'CONT-31', businessDate: '2026-08-15', quantity: 4, unitPrice: 30, feeItemName: '运费', sourceAmount: 120, statementAmount: 100, adjustmentReason: '优惠调整' }], paymentHistory: [{ transactionId: 701, transactionType: 'RECEIPT', transactionDate: '2026-08-02', amount: 10, method: 'BANK_TRANSFER', referenceNo: 'PAY-701', voucherFileIds: [9001], createdBy: 9, createdByName: '收款登记人', createdAt: '2026-08-02T11:00:00' }], revisions: [{ revisionNo: 1, action: 'ADJUST', beforeAmount: 120, afterAmount: 100, reason: '优惠', operatorId: 10, operatorName: '调整人', occurredAt: '2026-08-02T12:00:00' }] }
+    const post = vi.spyOn(http, 'post').mockResolvedValue({ code: '200', message: 'success', data: detail })
+    const get = vi.spyOn(http, 'get').mockResolvedValue({ code: '200', message: 'success', data: detail })
+
+    const created = await createReconciliationStatement({ customerId: '10001', currency: 'CNY', generationMode: 'BY_CUTOFF', periodStart: '2026-08-01', periodEnd: '2026-08-31' })
+    const loaded = await getReconciliationStatement('501')
+    await actionReconciliationStatement('501', { action: 'SUBMIT', expectedVersion: 0 })
+
+    expect(post.mock.calls[0]).toEqual(['/platform/finance/v1/statements', expect.objectContaining({ customerId: '10001', currency: 'CNY', generationMode: 'BY_CUTOFF' }), { headers: { 'Idempotency-Key': expect.any(String) } }])
+    expect(post.mock.calls[1]).toEqual(['/platform/finance/v1/reconciliation-statements/501/actions', { action: 'SUBMIT', expectedVersion: 0 }, { headers: { 'Idempotency-Key': expect.any(String) } }])
+    expect(get).toHaveBeenCalledWith('/platform/finance/v1/reconciliation-statements/501')
+    expect(created).toMatchObject({ id: '501', billNo: 'REC-501', customerId: '10001', totalAmount: 100, createdBy: '7', createdByName: '创建人A', createdAt: '2026-08-01T09:00:00', updatedBy: '8', updatedByName: '更新人B', updatedAt: '2026-08-02T10:00:00', lines: [{ statementLineId: '601', sourceFeeId: '42', sourceHash: 'hash-42', containerId: '31', sourceAmount: 120, amount: 100, adjustmentReason: '优惠调整' }] })
+    expect(loaded.paymentHistory[0]).toMatchObject({ voucherFileIds: ['9001'], createdBy: '9', createdByName: '收款登记人' })
+    expect(loaded).toMatchObject({ customerConfirmationStatus: 'CONFIRMED', customerConfirmedBy: '17', customerConfirmedByName: '客户确认人', customerConfirmedAt: '2026-08-05T10:00:00' })
+    expect(loaded.revisions[0]).toMatchObject({ operatorId: '10', operatorName: '调整人' })
+  })
+
+  it('uses the frozen G4 settlement create, detail and payment contracts', async () => {
+    const detail = { summary: { settlementId: 701, settlementNo: 'AP-701', customerId: 10001, supplierId: 81, reconciliationStatementId: 501, direction: 'PAYABLE', totalAmount: 200, paidAmount: 0, outstandingAmount: 200, currency: 'CNY', status: 'ISSUED', version: 0 }, lines: [], transactions: [{ transactionId: 801, transactionType: 'PAYMENT', transactionDate: '2026-08-11', amount: 20, method: 'BANK_TRANSFER', referenceNo: 'PAY-801', voucherFileIds: [9001], createdBy: 11, createdByName: '付款登记人', createdAt: '2026-08-11T10:00:00' }], revisions: [{ revisionNo: 1, action: 'VOID', beforeAmount: 200, afterAmount: 200, reason: '测试', operatorId: 12, operatorName: '作废操作人', occurredAt: '2026-08-11T11:00:00' }] }
+    const post = vi.spyOn(http, 'post').mockResolvedValue({ code: '200', message: 'success', data: detail })
+    const get = vi.spyOn(http, 'get').mockResolvedValue({ code: '200', message: 'success', data: detail })
+
+    await createReceivableSettlement({ reconciliationStatementId: '501', currency: 'CNY' })
+    await createPayableSettlement({ customerId: '10001', supplierId: '81', feeSourceIds: ['42'], dueDate: '2026-09-10', currency: 'CNY' })
+    const loaded = await getFinanceSettlement('701')
+    await createFinanceSettlementPayment('701', { transactionDate: '2026-08-11', amount: 200, currency: 'CNY', method: 'BANK_TRANSFER', voucherFileIds: ['9001'], expectedVersion: 0 })
+
+    expect(post.mock.calls[0]?.[0]).toBe('/platform/finance/v1/receivable-settlements')
+    expect(post.mock.calls[1]?.[0]).toBe('/platform/finance/v1/payable-settlements')
+    expect(get).toHaveBeenCalledWith('/platform/finance/v1/settlements/701')
+    expect(post.mock.calls[2]).toEqual(['/platform/finance/v1/settlements/701/transactions', expect.objectContaining({ amount: 200, voucherFileIds: ['9001'], expectedVersion: 0 }), { headers: { 'Idempotency-Key': expect.any(String) } }])
+    expect(loaded).toMatchObject({ id: '701', settlementNo: 'AP-701', customerId: '10001', supplierId: '81', reconciliationStatementId: '501', direction: 'PAYABLE', amount: 200, status: 'ISSUED' })
+    expect(loaded.transactions[0]).toMatchObject({ referenceNo: 'PAY-801', createdBy: '11', createdByName: '付款登记人', createdAt: '2026-08-11T10:00:00' })
+    expect(loaded.revisions[0]).toMatchObject({ operatorId: '12', operatorName: '作废操作人' })
+  })
+
+  it('keeps receipt and cost commands on CNY with real voucher ids', async () => {
+    const post = vi.spyOn(http, 'post').mockResolvedValue({ code: '200', message: 'ok', data: {} })
+
+    await createFinanceReceipt({ customerId: '10001', amount: 100 }, ['90001'])
+    await createFinanceCost({ customerId: '10001', amount: 100 }, ['90001'])
+
+    expect(post.mock.calls[0]?.[1]).toMatchObject({ currency: 'CNY', voucherFileIds: ['90001'] })
+    expect(post.mock.calls[1]?.[1]).toMatchObject({ currency: 'CNY', voucherFileIds: ['90001'] })
+    expect(post.mock.calls[0]?.[2]).toMatchObject({ headers: { 'Idempotency-Key': expect.any(String) } })
+    expect(post.mock.calls[1]?.[2]).toMatchObject({ headers: { 'Idempotency-Key': expect.any(String) } })
+  })
+
+  it('uploads a real voucher through the Finance Controller proxy', async () => {
+    const post = vi.spyOn(http, 'post').mockResolvedValue({ code: '200', message: 'ok', data: { fileId: 90001, tenantId: 10001, fileName: 'receipt.png', contentType: 'image/png', sizeBytes: 128 } })
+    const file = new File(['image'], 'receipt.png', { type: 'image/png' })
+
+    const result = await uploadFinanceVoucher('10001', file)
+
+    expect(result).toEqual({ fileId: '90001', customerId: '10001', fileName: 'receipt.png', contentType: 'image/png', sizeBytes: 128 })
+    expect(post.mock.calls[0]?.[0]).toBe('/platform/finance/v1/vouchers')
+    expect(post.mock.calls[0]?.[1]).toBeInstanceOf(FormData)
+    expect((post.mock.calls[0]?.[1] as FormData).get('file')).toBe(file)
+    expect(post.mock.calls[0]?.[2]).toEqual({ params: { customerId: '10001' }, headers: { 'Content-Type': 'multipart/form-data' } })
+  })
+
+  it('lets Finance backend obtain the container snapshot from Firstleg', async () => {
+    const post = vi.spyOn(http, 'post').mockResolvedValue({ code: '200', message: 'ok', data: {} })
+    const payload = { customerId: '10001', costType: 'CONTAINER_SHARED', containerId: '81', expenseName: '拖车费', amount: '600.000000' }
+
+    await createFinanceCost(payload, ['90001'])
+
+    expect(post.mock.calls[0]?.[1]).toEqual({ ...payload, currency: 'CNY', voucherFileIds: ['90001'] })
+    expect(post.mock.calls[0]?.[1]).not.toHaveProperty('containerOrders')
+  })
+
+  it('gets and updates the customer credit terms', async () => {
+    const get = vi.spyOn(http, 'get').mockResolvedValue({ code: '200', message: 'ok', data: { tenantId: 10001, customerName: '客户A', creditDays: 45, status: 'ACTIVE' } })
+    const put = vi.spyOn(http, 'put').mockResolvedValue({ code: '200', message: 'ok', data: { tenantId: 10001, customerName: '客户A', creditDays: 60, status: 'ACTIVE' } })
+
+    const terms = await getFinanceCustomerTerms('10001')
+    const updated = await updateFinanceCustomerTerms('10001', { customerName: '客户A', creditDays: 60 })
+
+    expect(get).toHaveBeenCalledWith('/platform/finance/v1/customers/10001/terms')
+    expect(put).toHaveBeenCalledWith('/platform/finance/v1/customers/10001/terms', { customerName: '客户A', creditDays: 60 }, { headers: { 'Idempotency-Key': expect.any(String) } })
+    expect(terms.creditDays).toBe(45)
+    expect(updated.creditDays).toBe(60)
+  })
+
+  it('queries and normalizes real bill revision snapshots', async () => {
+    const get = vi.spyOn(http, 'get').mockResolvedValue({ code: '200', message: 'ok', data: [{ id: 301, bill_id: 81, version: 2, reason: '金额修正', bill_snapshot: JSON.stringify({ status: 'ISSUED', total_amount: '120.00', received_amount: '20.00', outstanding_amount: '100.00' }), line_snapshot: JSON.stringify([{ source_id: 91, source_version: 2, fee_item_name: '运费', amount: '120.00' }]), created_by: 7, created_at: '2026-08-11T12:00:00' }] })
+
+    const revisions = await listFinanceBillRevisions('81', '10001')
+
+    expect(get).toHaveBeenCalledWith('/platform/finance/v1/bills/81/revisions', { params: { customerId: '10001' } })
+    expect(revisions[0]).toMatchObject({ id: '301', billId: '81', version: 2, reason: '金额修正', createdBy: '7', status: 'ISSUED', totalAmount: 120, receivedAmount: 20, outstandingAmount: 100, lines: [{ sourceFeeId: '91', sourceFeeVersion: 2, feeItemName: '运费', amount: 120 }] })
+  })
+
+  it('normalizes bill details and uses update, adjust and void contracts', async () => {
+    const statement = { id: 81, customerId: 10001, billNo: 'B-81', customerName: '客户A', billDate: '2026-08-11', dueDate: '2026-09-10', totalAmount: 100, receivedAmount: 0, outstandingAmount: 100, status: 'DRAFT', version: 3 }
+    const raw = { statement, lines: [{ sourceId: 91, sourceVersion: 2, orderId: 92, inboundId: 93, feeItemName: '运费', amount: 100 }] }
+    vi.spyOn(http, 'get').mockResolvedValue({ code: '200', message: 'ok', data: raw })
+    const put = vi.spyOn(http, 'put').mockResolvedValue({ code: '200', message: 'ok', data: raw })
+    const post = vi.spyOn(http, 'post').mockResolvedValue({ code: '200', message: 'ok', data: raw })
+
+    const detail = await getFinanceBill('81')
+    await updateFinanceBill('81', { customerId: '10001', expectedVersion: 3, lines: [] })
+    await adjustFinanceBill('81', { expectedVersion: 3, reason: '金额修正', lines: [] })
+    await voidFinanceBill('81', 3, '重复账单')
+
+    expect(detail).toMatchObject({ id: '81', customerId: '10001', version: 3, lines: [{ sourceFeeId: '91', sourceFeeVersion: 2, orderId: '92', inboundId: '93', feeItemName: '运费', amount: 100 }] })
+    expect(put).toHaveBeenCalledWith('/platform/finance/v1/bills/81', expect.objectContaining({ expectedVersion: 3 }), { headers: { 'Idempotency-Key': expect.any(String) } })
+    expect(post).toHaveBeenNthCalledWith(1, '/platform/finance/v1/bills/81/adjust', expect.objectContaining({ expectedVersion: 3, reason: '金额修正' }), { headers: { 'Idempotency-Key': expect.any(String) } })
+    expect(post).toHaveBeenNthCalledWith(2, '/platform/finance/v1/bills/81/void', { expectedVersion: 3, reason: '重复账单' }, { headers: { 'Idempotency-Key': expect.any(String) } })
+  })
+
+})
diff --git a/src/modules/finance/api/finance.ts b/src/modules/finance/api/finance.ts
new file mode 100644
index 00000000..24a8e79e
--- /dev/null
+++ b/src/modules/finance/api/finance.ts
@@ -0,0 +1,489 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import type { CreatePayableSettlementPayload, CreateReceivableSettlementPayload, CreateReconciliationPayload, CreateSettlementPaymentPayload, FinanceAccountAdjustmentPayload, FinanceAccountEntry, FinanceAccountSummary, FinanceBillDetail, FinanceBillLine, FinanceBillResource, FinanceBillRevision, FinanceCostResource, FinanceCustomerAccountReadModel, FinanceCustomerTerms, FinanceFeePoolItem, FinanceFeeSourceDetail, FinanceFeeSourceSummary, FinanceLedgerEntry, FinancePayableSettlement, FinanceRechargeRequest, FinanceRechargeReviewPayload, FinanceReceivableSettlement, FinanceReceiptResource, FinanceReconciliationDetail, FinanceSettlementDetail, FinanceSettlementLine, FinanceStatementReadModel, FinanceVoucherResource, ReceivableStatisticsResult, ReconciliationActionPayload } from '../types'
+
+const basePath = '/platform/finance/v1'
+export interface FinanceCustomerAccountSummaryResource {
+  customerId: string
+  currency: 'CNY'
+  totalReceivable: number | string
+  receivedAmount: number | string
+  outstandingReceivable: number | string
+  pendingBilling: number | string
+  totalCost: number | string
+  paidCost: number | string
+  outstandingPayable: number | string
+  asOf: string
+  lastChangedAt: string | null
+}
+export const financePhase1Capabilities = {
+  accountList: true,
+  accountLedger: true,
+  feeSourceDetail: true,
+  feeSourceReview: true,
+  feeSourceEditReviewLifecycle: true,
+  reconciliationCreate: true,
+  reconciliationActions: true,
+  receivableSettlementCreate: true,
+  payableSettlementCreate: true,
+  settlementDetail: true,
+  settlementPayment: true,
+} as const
+
+export async function getReceivableStatistics(params: { month: string; customerId?: string; page?: number; pageSize?: number }): Promise<ReceivableStatisticsResult> {
+  const response = await http.get<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/receivable-statistics`, { params: {
+    month: params.month,
+    customerId: params.customerId?.trim() || undefined,
+    page: params.page ?? 1,
+    pageSize: params.pageSize ?? 20,
+  } })
+  const item = unwrapApiResponse(response)
+  return {
+    statisticsMonth: stringValue(item.statisticsMonth), currency: 'CNY',
+    totalReceivable: stringValue(item.totalReceivable), totalReceived: stringValue(item.totalReceived),
+    totalOutstanding: stringValue(item.totalOutstanding), totalCustomers: numberValue(item.totalCustomers),
+    page: numberValue(item.page), pageSize: numberValue(item.pageSize),
+    records: (Array.isArray(item.records) ? item.records : []).map((value) => {
+      const row = value as RawResource
+      return { customerId: stringValue(row.customerId), customerName: stringValue(row.customerName), currency: 'CNY' as const,
+        totalReceivable: stringValue(row.totalReceivable), totalReceived: stringValue(row.totalReceived), totalOutstanding: stringValue(row.totalOutstanding) }
+    }),
+  }
+}
+function idempotencyKey(operation: string) { return `finance-${operation}-${Date.now()}-${Math.random().toString(36).slice(2)}` }
+type RawResource = Record<string, unknown>
+function stringValue(value: unknown) { return value == null ? '' : String(value) }
+function numberValue(value: unknown) { return Number(value ?? 0) }
+function nullableStringValue(value: unknown) { return value == null ? null : String(value) }
+function jsonRecord(value: unknown): RawResource {
+  if (value && typeof value === 'object' && !Array.isArray(value)) return value as RawResource
+  if (typeof value !== 'string' || !value.trim()) return {}
+  try { const parsed = JSON.parse(value) as unknown; return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed as RawResource : {} } catch { return {} }
+}
+function jsonRecords(value: unknown): RawResource[] {
+  if (Array.isArray(value)) return value.filter((item): item is RawResource => Boolean(item) && typeof item === 'object' && !Array.isArray(item))
+  if (typeof value !== 'string' || !value.trim()) return []
+  try { const parsed = JSON.parse(value) as unknown; return Array.isArray(parsed) ? parsed.filter((item): item is RawResource => Boolean(item) && typeof item === 'object' && !Array.isArray(item)) : [] } catch { return [] }
+}
+function normalizeBill(item: RawResource, customerId = stringValue(item.tenant_id ?? item.customerId)): FinanceBillResource {
+  return {
+    id: stringValue(item.id), billNo: stringValue(item.bill_no ?? item.billNo), customerId,
+    customerName: stringValue(item.customer_name_snapshot ?? item.customerName),
+    billDate: stringValue(item.bill_date ?? item.billDate), dueDate: stringValue(item.due_date ?? item.dueDate), currency: 'CNY',
+    totalAmount: numberValue(item.total_amount ?? item.totalAmount), paidAmount: numberValue(item.received_amount ?? item.receivedAmount ?? item.paidAmount),
+    outstandingAmount: numberValue(item.outstanding_amount ?? item.outstandingAmount), status: stringValue(item.status) as FinanceBillResource['status'],
+    version: numberValue(item.version),
+  }
+}
+function normalizeBillLine(item: RawResource): FinanceBillLine {
+  return {
+    statementLineId: stringValue(item.id ?? item.statementLineId),
+    sourceFeeId: stringValue(item.source_id ?? item.sourceId ?? item.sourceFeeId), sourceFeeVersion: numberValue(item.source_version ?? item.sourceVersion ?? item.sourceFeeVersion) || 1,
+    orderId: item.order_id == null && item.orderId == null ? null : stringValue(item.order_id ?? item.orderId),
+    inboundId: item.inbound_id == null && item.inboundId == null ? null : stringValue(item.inbound_id ?? item.inboundId),
+    feeItemName: stringValue(item.fee_item_name ?? item.feeItemName), amount: numberValue(item.amount),
+  }
+}
+function normalizeBillDetail(item: RawResource): FinanceBillDetail {
+  const statement = item.statement && typeof item.statement === 'object' ? item.statement as RawResource : item
+  return { ...normalizeBill(statement), remark: stringValue(statement.remark), lines: Array.isArray(item.lines) ? item.lines.map((line) => normalizeBillLine(line as RawResource)) : [] }
+}
+function mutationHeaders(operation: string) { return { headers: { 'Idempotency-Key': idempotencyKey(operation) } } }
+
+export async function getFinanceCustomerAccount(customerId: string): Promise<FinanceCustomerAccountReadModel> {
+  const response = await http.get<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/customer-accounts/${customerId}`)
+  const item = unwrapApiResponse(response)
+  return {
+    customerId: stringValue(item.customerId), currency: 'CNY', accountMode: 'MANUAL_RECEIVABLE_LEDGER',
+    totalReceivable: numberValue(item.totalReceivable), totalReceived: numberValue(item.totalReceived), outstandingAmount: numberValue(item.outstandingAmount),
+    entries: (Array.isArray(item.entries) ? item.entries : []).map((entry) => { const row = entry as RawResource; return { entryType: stringValue(row.entryType) as FinanceAccountEntry['entryType'], resourceId: stringValue(row.resourceId), resourceNo: stringValue(row.resourceNo), occurredAt: stringValue(row.occurredAt), debitAmount: numberValue(row.debitAmount), creditAmount: numberValue(row.creditAmount), currency: 'CNY', status: stringValue(row.status) } }),
+  }
+}
+
+export async function getFinanceCustomerAccountSummary(customerId: string): Promise<FinanceCustomerAccountSummaryResource> {
+  const response = await http.get<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/customer-accounts/${customerId}/summary`)
+  const item = unwrapApiResponse(response)
+  return {
+    customerId: stringValue(item.customerId), currency: 'CNY',
+    totalReceivable: stringValue(item.totalReceivable), receivedAmount: stringValue(item.receivedAmount),
+    outstandingReceivable: stringValue(item.outstandingReceivable), pendingBilling: stringValue(item.pendingBilling),
+    totalCost: stringValue(item.totalCost), paidCost: stringValue(item.paidCost),
+    outstandingPayable: stringValue(item.outstandingPayable), asOf: stringValue(item.asOf),
+    lastChangedAt: item.lastChangedAt == null ? null : stringValue(item.lastChangedAt),
+  }
+}
+
+export async function listFinanceFeePool(customerId?: string, direction?: 'RECEIVABLE' | 'PAYABLE', supplierId?: string): Promise<FinanceFeePoolItem[]> {
+  const params: Record<string, unknown> = { customerId: customerId?.trim() || undefined, direction }
+  if (supplierId?.trim()) params.supplierId = supplierId.trim()
+  const response = await http.get<ApiEnvelope<RawResource[]>, ApiEnvelope<RawResource[]>>(`${basePath}/fee-pool`, { params })
+  return unwrapApiResponse(response).map((item) => {
+    const poolItemId = stringValue(item.poolItemId)
+    const feeSourceId = stringValue(item.sourceType) === 'MANUAL_COST' ? null : (poolItemId.match(/^[A-Z_]+:(\d+)$/)?.[1] ?? null)
+    return { poolItemId, feeSourceId, customerId: stringValue(item.customerId), customerName: stringValue(item.customerName), direction: stringValue(item.direction) as FinanceFeePoolItem['direction'], sourceType: stringValue(item.sourceType), sourceId: stringValue(item.sourceId), sourceVersion: numberValue(item.sourceVersion), orderId: item.orderId == null ? null : stringValue(item.orderId), inboundId: item.inboundId == null ? null : stringValue(item.inboundId), containerId: item.containerId == null ? null : stringValue(item.containerId), feeItemName: stringValue(item.feeItemName), amount: numberValue(item.amount), currency: 'CNY', settlementMode: item.settlementMode == null ? null : stringValue(item.settlementMode), status: stringValue(item.status), createdAt: stringValue(item.createdAt) }
+  })
+}
+
+export async function listFinanceAccounts(params: { page?: number; size?: number; customerId?: string; status?: string } = {}): Promise<{ records: FinanceAccountSummary[]; total: number; pages: number }> {
+  const query = { page: params.page ?? 1, pageSize: params.size ?? 20, customerId: params.customerId || undefined, status: params.status || undefined }
+  const response = await http.get<ApiEnvelope<RawResource[]> & { page?: RawResource }, ApiEnvelope<RawResource[]> & { page?: RawResource }>(`${basePath}/accounts`, { params: query })
+  const data = unwrapApiResponse(response)
+  const records: FinanceAccountSummary[] = data.map(normalizeFinanceAccount)
+  const total = numberValue(response.page?.total ?? records.length)
+  const pageSize = numberValue(response.page?.pageSize ?? query.pageSize) || query.pageSize
+  return { records, total, pages: Math.max(1, Math.ceil(total / pageSize)) }
+}
+
+function normalizeFinanceAccount(item: RawResource): FinanceAccountSummary {
+  return {
+    customerId: stringValue(item.customerId), customerCode: stringValue(item.customerCode), customerName: stringValue(item.customerName),
+    contactName: stringValue(item.contactName), contactPhone: stringValue(item.contactPhone), outstandingReceivable: numberValue(item.outstandingReceivable),
+    pendingBilling: numberValue(item.pendingBilling), receivedInPeriod: numberValue(item.receivedInPeriod), totalCost: numberValue(item.totalCost),
+    paidCost: numberValue(item.paidCost), outstandingPayable: numberValue(item.outstandingPayable), status: stringValue(item.status),
+    lastChangedAt: stringValue(item.lastChangedAt), actualBalance: stringValue(item.actualBalance), frozenBalance: stringValue(item.frozenBalance),
+    availableBalance: stringValue(item.availableBalance), creditLimit: stringValue(item.creditLimit), creditUsed: stringValue(item.creditUsed),
+    availableCredit: stringValue(item.availableCredit), creditExpiresOn: nullableStringValue(item.creditExpiresOn), creditActive: Boolean(item.creditActive),
+    accountVersion: numberValue(item.accountVersion), pendingRechargeCount: numberValue(item.pendingRechargeCount),
+  }
+}
+
+export async function listFinanceAccountLedger(customerId: string, params: { page?: number; size?: number; businessType?: string; startDate?: string; endDate?: string } = {}): Promise<{ records: FinanceLedgerEntry[]; total: number; pages: number }> {
+  const query = { page: params.page ?? 1, pageSize: params.size ?? 20, businessType: params.businessType || undefined, startDate: params.startDate || undefined, endDate: params.endDate || undefined }
+  const response = await http.get<ApiEnvelope<RawResource[]> & { page?: RawResource }, ApiEnvelope<RawResource[]> & { page?: RawResource }>(`${basePath}/accounts/${customerId}/ledger`, { params: query })
+  const data = unwrapApiResponse(response)
+  const records: FinanceLedgerEntry[] = data.map((item) => ({
+    ledgerId: stringValue(item.ledgerId), occurredAt: stringValue(item.occurredAt), businessType: stringValue(item.businessType),
+    documentType: stringValue(item.documentType), documentId: stringValue(item.documentId), documentNo: stringValue(item.documentNo),
+    receivableChange: numberValue(item.receivableChange), payableChange: numberValue(item.payableChange),
+    outstandingReceivableAfter: numberValue(item.outstandingReceivableAfter), operatorName: stringValue(item.operatorName), remark: stringValue(item.remark),
+    businessNo: nullableStringValue(item.businessNo), changeType: nullableStringValue(item.changeType), amount: nullableStringValue(item.amount),
+    actualBalanceAfter: nullableStringValue(item.actualBalanceAfter), frozenBalanceAfter: nullableStringValue(item.frozenBalanceAfter),
+    availableBalanceAfter: nullableStringValue(item.availableBalanceAfter), sourceType: nullableStringValue(item.sourceType),
+    creditLimitAfter: nullableStringValue(item.creditLimitAfter), creditUsedAfter: nullableStringValue(item.creditUsedAfter),
+    availableCreditAfter: nullableStringValue(item.availableCreditAfter),
+    creditExpiresOnAfter: nullableStringValue(item.creditExpiresOnAfter),
+    sourceNo: nullableStringValue(item.sourceNo), occurredDate: nullableStringValue(item.occurredDate),
+    paymentMethod: nullableStringValue(item.paymentMethod), referenceNo: nullableStringValue(item.referenceNo),
+    createdAt: nullableStringValue(item.createdAt),
+  }))
+  const total = numberValue(response.page?.total ?? records.length)
+  const pageSize = numberValue(response.page?.pageSize ?? query.pageSize) || query.pageSize
+  return { records, total, pages: Math.max(1, Math.ceil(total / pageSize)) }
+}
+
+function normalizeRechargeRequest(item: RawResource): FinanceRechargeRequest {
+  return {
+    requestId: stringValue(item.requestId), requestNo: stringValue(item.requestNo), amount: stringValue(item.amount),
+    paymentMethod: stringValue(item.paymentMethod), voucherFileId: stringValue(item.voucherFileId), voucherFileName: stringValue(item.voucherFileName),
+    status: stringValue(item.status), version: numberValue(item.version), submittedByName: stringValue(item.submittedByName),
+    reviewedByName: stringValue(item.reviewedByName), reviewRemark: stringValue(item.reviewRemark), createdAt: stringValue(item.createdAt),
+    reviewedAt: stringValue(item.reviewedAt),
+  }
+}
+
+export async function listFinanceRechargeRequests(customerId: string, params: { page?: number; size?: number } = {}): Promise<{ records: FinanceRechargeRequest[]; total: number; pages: number }> {
+  const query = { page: params.page ?? 1, pageSize: params.size ?? 200 }
+  const response = await http.get<ApiEnvelope<RawResource[]> & { page?: RawResource }, ApiEnvelope<RawResource[]> & { page?: RawResource }>(`${basePath}/accounts/${customerId}/recharge-requests`, { params: query })
+  const records = unwrapApiResponse(response).map(normalizeRechargeRequest)
+  const total = numberValue(response.page?.total ?? records.length)
+  const pageSize = numberValue(response.page?.pageSize ?? query.pageSize) || query.pageSize
+  return { records, total, pages: Math.max(1, Math.ceil(total / pageSize)) }
+}
+
+export async function reviewFinanceRechargeRequest(requestId: string, payload: FinanceRechargeReviewPayload) {
+  const response = await http.post<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/recharge-requests/${requestId}/review`, payload, mutationHeaders('recharge-review'))
+  return normalizeRechargeRequest(unwrapApiResponse(response))
+}
+
+export function downloadFinanceRechargeVoucher(requestId: string) {
+  return http.get<Blob, Blob>(`${basePath}/recharge-requests/${encodeURIComponent(requestId)}/voucher`, { responseType: 'blob' })
+}
+
+export async function adjustFinanceAccount(customerId: string, payload: FinanceAccountAdjustmentPayload) {
+  const response = await http.post<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/accounts/${customerId}/adjustments`, payload, mutationHeaders('account-adjustment'))
+  return unwrapApiResponse(response)
+}
+
+export async function updateFinanceCreditLimit(customerId: string, payload: { creditLimit: string; creditExpiresOn: string; remark?: string; expectedAccountVersion: number }) {
+  const response = await http.put<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/accounts/${customerId}/credit-limit`, payload, mutationHeaders('credit-limit'))
+  return unwrapApiResponse(response)
+}
+
+export async function listFinanceFeeSources(params: {
+  page?: number
+  size?: number
+  customerId?: string
+  direction?: 'RECEIVABLE' | 'PAYABLE'
+  status?: string
+  reviewStatus?: 'DRAFT' | 'PENDING' | 'APPROVED' | 'REJECTED'
+  statementGenerated?: boolean
+  businessDateFrom?: string
+  businessDateTo?: string
+  keyword?: string
+} = {}): Promise<{ records: FinanceFeeSourceSummary[]; total: number; pages: number }> {
+  const query = {
+    page: params.page ?? 1, pageSize: params.size ?? 20, customerId: params.customerId || undefined,
+    direction: params.direction || undefined, status: params.status || undefined,
+    reviewStatus: params.reviewStatus || undefined,
+    statementGenerated: params.statementGenerated, businessDateFrom: params.businessDateFrom || undefined,
+    businessDateTo: params.businessDateTo || undefined, keyword: params.keyword?.trim() || undefined,
+  }
+  const response = await http.get<ApiEnvelope<RawResource[]> & { page?: RawResource }, ApiEnvelope<RawResource[]> & { page?: RawResource }>(`${basePath}/fee-sources`, { params: query })
+  const records = unwrapApiResponse(response).map(normalizeFeeSourceSummary)
+  const total = numberValue(response.page?.total ?? records.length)
+  const pageSize = numberValue(response.page?.pageSize ?? query.pageSize) || query.pageSize
+  return { records, total, pages: Math.max(1, Math.ceil(total / pageSize)) }
+}
+
+export async function getFinanceFeeSource(feeSourceId: string): Promise<FinanceFeeSourceDetail> {
+  const response = await http.get<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/fee-sources/${feeSourceId}`)
+  return normalizeFeeSourceDetail(unwrapApiResponse(response))
+}
+
+function normalizeFeeSourceSummary(item: RawResource): FinanceFeeSourceSummary {
+  const nullableString = (value: unknown) => value == null ? null : stringValue(value)
+  const nullableNumber = (value: unknown) => value == null ? null : numberValue(value)
+  return {
+    poolItemId: stringValue(item.feeSourceId), feeSourceId: stringValue(item.feeSourceId), sourceSystem: stringValue(item.sourceSystem),
+    sourceType: stringValue(item.sourceType), sourceBusinessId: stringValue(item.sourceBusinessId), sourceId: stringValue(item.sourceFeeId),
+    sourceVersion: numberValue(item.sourceVersion), direction: stringValue(item.direction) as FinanceFeeSourceDetail['direction'],
+    customerId: stringValue(item.customerId), customerName: stringValue(item.customerName), supplierId: nullableString(item.supplierId), supplierName: stringValue(item.supplierName),
+    orderId: nullableString(item.orderId), inboundId: nullableString(item.inboundId), inboundCode: stringValue(item.inboundCode),
+    containerId: nullableString(item.containerId), containerNo: stringValue(item.containerNo), businessDate: stringValue(item.businessDate),
+    feeItemName: stringValue(item.feeItemName), quantity: nullableNumber(item.quantity), quantityUnit: nullableString(item.quantityUnit),
+    unitPrice: nullableNumber(item.unitPrice), periodStart: nullableString(item.periodStart), periodEnd: nullableString(item.periodEnd),
+    amount: numberValue(item.amount), currency: 'CNY', originalCurrency: (stringValue(item.originalCurrency) || 'CNY') as 'CNY' | 'USD',
+    originalAmount: item.originalAmount == null ? numberValue(item.amount) : numberValue(item.originalAmount),
+    exchangeRate: item.exchangeRate == null ? 1 : numberValue(item.exchangeRate), exchangeRateMonth: nullableString(item.exchangeRateMonth),
+    reviewStatus: stringValue(item.reviewStatus) as FinanceFeeSourceDetail['reviewStatus'],
+    sourceStatus: stringValue(item.sourceStatus), status: stringValue(item.sourceStatus), statementGenerated: Boolean(item.statementGenerated),
+    createdAt: stringValue(item.businessDate),
+  }
+}
+
+function normalizeFeeSourceDetail(item: RawResource): FinanceFeeSourceDetail {
+  return {
+    ...normalizeFeeSourceSummary(item), sourceFeeId: stringValue(item.sourceFeeId),
+    reviewReason: stringValue(item.reviewReason) || undefined,
+    sourceHash: stringValue(item.sourceHash) || undefined, operationVersion: numberValue(item.operationVersion),
+    operationLogs: (Array.isArray(item.operationLogs) ? item.operationLogs : []).map((entry) => { const row = entry as RawResource; return { occurredAt: stringValue(row.occurredAt), action: stringValue(row.action), operatorName: stringValue(row.operatorName), result: stringValue(row.result), remark: stringValue(row.remark) || undefined } }),
+  }
+}
+
+export async function reviewFinanceFeeSource(feeSourceId: string, payload: { action: 'APPROVE' | 'REJECT'; reason?: string; expectedVersion: number }): Promise<FinanceFeeSourceDetail> {
+  const response = await http.post<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/fee-sources/${feeSourceId}/review`, payload, mutationHeaders('fee-source-review'))
+  return normalizeFeeSourceDetail(unwrapApiResponse(response))
+}
+export async function editFinanceFeeSource(feeSourceId: string, payload: { amount: number; reason: string; expectedVersion: number }): Promise<FinanceFeeSourceDetail> {
+  const response = await http.put<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/fee-sources/${feeSourceId}`, payload, mutationHeaders('fee-source-edit'))
+  return normalizeFeeSourceDetail(unwrapApiResponse(response))
+}
+export async function submitFinanceFeeSource(feeSourceId: string, payload: { reason: string; expectedVersion: number }): Promise<FinanceFeeSourceDetail> {
+  const response = await http.post<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/fee-sources/${feeSourceId}/submit`, payload, mutationHeaders('fee-source-submit'))
+  return normalizeFeeSourceDetail(unwrapApiResponse(response))
+}
+export async function adjustFinanceFeeSource(feeSourceId: string, payload: { amount: number; reason: string; expectedVersion: number }): Promise<FinanceFeeSourceDetail> {
+  const response = await http.post<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/fee-sources/${feeSourceId}/adjust`, payload, mutationHeaders('fee-source-adjust'))
+  return normalizeFeeSourceDetail(unwrapApiResponse(response))
+}
+export async function voidFinanceFeeSource(feeSourceId: string, payload: { reason: string; expectedVersion: number }): Promise<FinanceFeeSourceDetail> {
+  const response = await http.post<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/fee-sources/${feeSourceId}/void`, payload, mutationHeaders('fee-source-void'))
+  return normalizeFeeSourceDetail(unwrapApiResponse(response))
+}
+function normalizeReconciliationDetail(item: RawResource): FinanceReconciliationDetail {
+  const lines = (Array.isArray(item.lines) ? item.lines : []).map((entry) => {
+    const row = entry as RawResource
+    return {
+      statementLineId: stringValue(row.statementLineId), sourceFeeId: stringValue(row.feeSourceId), sourceFeeVersion: numberValue(row.sourceVersion), sourceHash: stringValue(row.sourceHash) || undefined,
+      direction: stringValue(row.direction) as 'RECEIVABLE' | 'PAYABLE', sourceType: stringValue(row.sourceType), sourceNo: stringValue(row.sourceNo),
+      orderId: row.orderId == null ? null : stringValue(row.orderId), inboundId: row.inboundId == null ? null : stringValue(row.inboundId), containerId: row.containerId == null ? null : stringValue(row.containerId),
+      inboundCode: stringValue(row.inboundCode), containerNo: stringValue(row.containerNo), businessDate: stringValue(row.businessDate),
+      quantity: row.quantity == null ? null : numberValue(row.quantity), unitPrice: row.unitPrice == null ? null : numberValue(row.unitPrice),
+      feeItemName: stringValue(row.feeItemName), sourceAmount: numberValue(row.sourceAmount), amount: numberValue(row.statementAmount), adjustmentReason: stringValue(row.adjustmentReason) || undefined,
+    }
+  })
+  return {
+    id: stringValue(item.statementId), billNo: stringValue(item.statementNo), customerId: stringValue(item.customerId), customerName: stringValue(item.customerName),
+    billDate: stringValue(item.periodEnd), dueDate: '', periodStart: stringValue(item.periodStart), periodEnd: stringValue(item.periodEnd), creditDays: numberValue(item.creditDays), currency: 'CNY',
+    totalAmount: numberValue(item.totalReceivable), paidAmount: numberValue(item.receivedAmount), outstandingAmount: numberValue(item.outstandingAmount), settled: Boolean(item.settled), status: stringValue(item.status) as FinanceBillResource['status'], version: numberValue(item.version), customerConfirmationStatus: stringValue(item.customerConfirmationStatus) as FinanceBillResource['customerConfirmationStatus'], customerConfirmedBy: stringValue(item.customerConfirmedBy) || undefined, customerConfirmedByName: stringValue(item.customerConfirmedByName) || undefined, customerConfirmedAt: stringValue(item.customerConfirmedAt) || undefined, remark: stringValue(item.remark), createdBy: stringValue(item.createdBy), createdByName: stringValue(item.createdByName), createdAt: stringValue(item.createdAt), updatedBy: stringValue(item.updatedBy), updatedByName: stringValue(item.updatedByName), updatedAt: stringValue(item.updatedAt), lines,
+    paymentHistory: (Array.isArray(item.paymentHistory) ? item.paymentHistory : []).map((entry) => { const row = entry as RawResource; return { transactionId: stringValue(row.transactionId), transactionType: stringValue(row.transactionType), transactionDate: stringValue(row.transactionDate), amount: numberValue(row.amount), method: stringValue(row.method), referenceNo: stringValue(row.referenceNo), voucherFileIds: Array.isArray(row.voucherFileIds) ? row.voucherFileIds.map(stringValue) : [], createdBy: stringValue(row.createdBy), createdByName: stringValue(row.createdByName), occurredAt: stringValue(row.occurredAt ?? row.createdAt), remark: stringValue(row.remark) || undefined } }),
+    revisions: (Array.isArray(item.revisions) ? item.revisions : []).map((entry) => { const row = entry as RawResource; return { revisionNo: numberValue(row.revisionNo), action: stringValue(row.action), beforeAmount: numberValue(row.beforeAmount), afterAmount: numberValue(row.afterAmount), reason: stringValue(row.reason) || undefined, operatorId: stringValue(row.operatorId), operatorName: stringValue(row.operatorName), occurredAt: stringValue(row.occurredAt) } }),
+  }
+}
+
+function normalizeSettlementDetail(item: RawResource): FinanceSettlementDetail {
+  const summary = item.summary && typeof item.summary === 'object' ? item.summary as RawResource : item
+  return {
+    id: stringValue(summary.settlementId ?? summary.id), settlementNo: stringValue(summary.settlementNo), customerId: stringValue(summary.customerId), customerName: stringValue(summary.customerName), supplierId: summary.supplierId == null ? undefined : stringValue(summary.supplierId), supplierName: stringValue(summary.supplierName), reconciliationStatementId: summary.reconciliationStatementId == null ? undefined : stringValue(summary.reconciliationStatementId), reconciliationStatementNo: stringValue(summary.reconciliationStatementNo) || undefined, businessPeriod: stringValue(summary.businessPeriod), feeItemSummary: stringValue(summary.feeItemSummary) || undefined, generatedDate: stringValue(summary.generatedDate), dueDate: stringValue(summary.dueDate), paymentStatus: stringValue(summary.paymentStatus) as FinanceSettlementDetail['paymentStatus'], direction: stringValue(summary.direction) as FinanceSettlementDetail['direction'],
+    amount: numberValue(summary.totalAmount ?? summary.amount), paidAmount: numberValue(summary.paidAmount), outstandingAmount: numberValue(summary.outstandingAmount), currency: 'CNY', status: stringValue(summary.status), createdBy: stringValue(summary.createdBy) || undefined, createdByName: stringValue(summary.createdByName) || undefined, createdAt: stringValue(summary.createdAt) || undefined, updatedAt: stringValue(summary.updatedAt) || undefined, lastPaymentAt: stringValue(summary.lastPaymentAt) || undefined, version: numberValue(summary.version),
+    lines: (Array.isArray(item.lines) ? item.lines : []).map((line) => normalizeSettlementLine(line as RawResource)),
+    transactions: (Array.isArray(item.transactions) ? item.transactions : []).map((entry) => { const row = entry as RawResource; return { transactionId: stringValue(row.transactionId), transactionType: stringValue(row.transactionType), transactionDate: stringValue(row.transactionDate), amount: numberValue(row.amount), method: stringValue(row.method), referenceNo: stringValue(row.referenceNo), voucherFileIds: Array.isArray(row.voucherFileIds) ? row.voucherFileIds.map(stringValue) : [], createdBy: stringValue(row.createdBy), createdByName: stringValue(row.createdByName), createdAt: stringValue(row.createdAt), remark: stringValue(row.remark) || undefined } }),
+    revisions: (Array.isArray(item.revisions) ? item.revisions : []).map((entry) => { const row = entry as RawResource; return { revisionNo: numberValue(row.revisionNo), action: stringValue(row.action), beforeAmount: numberValue(row.beforeAmount), afterAmount: numberValue(row.afterAmount), reason: stringValue(row.reason) || undefined, operatorId: stringValue(row.operatorId), operatorName: stringValue(row.operatorName), occurredAt: stringValue(row.occurredAt) } }),
+  }
+}
+
+function normalizeSettlementLine(item: RawResource): FinanceSettlementLine {
+  const nullableString = (value: unknown) => value == null ? null : stringValue(value)
+  const nullableNumber = (value: unknown) => value == null ? null : numberValue(value)
+  return {
+    feeSourceId: stringValue(item.feeSourceId), sourceType: stringValue(item.sourceType), sourceFeeId: stringValue(item.sourceFeeId), sourceVersion: numberValue(item.sourceVersion),
+    direction: stringValue(item.direction) as FinanceSettlementLine['direction'], customerId: stringValue(item.customerId), customerName: stringValue(item.customerName),
+    supplierId: nullableString(item.supplierId), supplierName: stringValue(item.supplierName), orderId: nullableString(item.orderId), orderNo: stringValue(item.orderNo),
+    inboundId: nullableString(item.inboundId), inboundCode: stringValue(item.inboundCode), containerId: nullableString(item.containerId), containerNo: stringValue(item.containerNo),
+    businessDate: stringValue(item.businessDate), feeItemName: stringValue(item.feeItemName), quantity: nullableNumber(item.quantity), unitPrice: nullableNumber(item.unitPrice),
+    amount: numberValue(item.amount), currency: 'CNY', reviewStatus: stringValue(item.reviewStatus) as FinanceSettlementLine['reviewStatus'], sourceStatus: stringValue(item.sourceStatus), statementGenerated: Boolean(item.statementGenerated),
+  }
+}
+
+export async function createReconciliationStatement(payload: CreateReconciliationPayload) {
+  const response = await http.post<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/statements`, payload, mutationHeaders('reconciliation-create'))
+  return normalizeReconciliationDetail(unwrapApiResponse(response))
+}
+export async function actionReconciliationStatement(statementId: string, payload: ReconciliationActionPayload) {
+  const response = await http.post<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/reconciliation-statements/${statementId}/actions`, payload, mutationHeaders('reconciliation-action'))
+  return normalizeReconciliationDetail(unwrapApiResponse(response))
+}
+export async function getReconciliationStatement(statementId: string): Promise<FinanceReconciliationDetail> {
+  const response = await http.get<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/reconciliation-statements/${statementId}`)
+  return normalizeReconciliationDetail(unwrapApiResponse(response))
+}
+export async function createReceivableSettlement(payload: CreateReceivableSettlementPayload) {
+  const response = await http.post<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/receivable-settlements`, payload, mutationHeaders('settlement-ar-create'))
+  return normalizeSettlementDetail(unwrapApiResponse(response))
+}
+export async function createPayableSettlement(payload: CreatePayableSettlementPayload) {
+  const response = await http.post<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/payable-settlements`, payload, mutationHeaders('settlement-ap-create'))
+  return normalizeSettlementDetail(unwrapApiResponse(response))
+}
+export async function getFinanceSettlement(settlementId: string): Promise<FinanceSettlementDetail> {
+  const response = await http.get<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/settlements/${settlementId}`)
+  return normalizeSettlementDetail(unwrapApiResponse(response))
+}
+export async function createFinanceSettlementPayment(settlementId: string, payload: CreateSettlementPaymentPayload) {
+  const response = await http.post<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/settlements/${settlementId}/transactions`, payload, mutationHeaders('settlement-payment'))
+  return normalizeSettlementDetail(unwrapApiResponse(response))
+}
+export async function actionFinanceSettlement(settlementId: string, payload: import('../types').FinanceSettlementActionPayload) {
+  const response = await http.post<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/settlements/${settlementId}/actions`, payload, mutationHeaders('settlement-action'))
+  return normalizeSettlementDetail(unwrapApiResponse(response))
+}
+
+export async function listFinanceStatements(customerId?: string): Promise<FinanceStatementReadModel[]> {
+  const response = await http.get<ApiEnvelope<RawResource[]>, ApiEnvelope<RawResource[]>>(`${basePath}/statements`, { params: { customerId: customerId?.trim() || undefined } })
+  return unwrapApiResponse(response).map((item) => ({ id: stringValue(item.statementId ?? item.id), customerId: stringValue(item.customerId), billNo: stringValue(item.statementNo ?? item.billNo), customerName: stringValue(item.customerName), billDate: stringValue(item.periodEnd ?? item.billDate), dueDate: stringValue(item.dueDate), periodStart: stringValue(item.periodStart), periodEnd: stringValue(item.periodEnd), creditDays: item.creditDays == null ? undefined : numberValue(item.creditDays), lineCount: item.lineCount == null ? undefined : numberValue(item.lineCount), sourceCount: item.sourceCount == null ? undefined : numberValue(item.sourceCount), sourceAmount: item.sourceAmount == null ? undefined : numberValue(item.sourceAmount), adjustmentAmount: item.adjustmentAmount == null ? undefined : numberValue(item.adjustmentAmount), totalAmount: numberValue(item.totalReceivable ?? item.totalAmount), receivedAmount: numberValue(item.receivedAmount), outstandingAmount: numberValue(item.outstandingAmount), currency: 'CNY', settled: item.settled == null ? undefined : Boolean(item.settled), lastReceiptAt: stringValue(item.lastReceiptAt), submittedAt: stringValue(item.submittedAt), reviewedAt: stringValue(item.reviewedAt), issuedAt: stringValue(item.issuedAt), status: stringValue(item.status) as FinanceStatementReadModel['status'], version: numberValue(item.version), customerConfirmationStatus: stringValue(item.customerConfirmationStatus) as FinanceStatementReadModel['customerConfirmationStatus'], customerConfirmedBy: stringValue(item.customerConfirmedBy) || undefined, customerConfirmedByName: stringValue(item.customerConfirmedByName) || undefined, customerConfirmedAt: stringValue(item.customerConfirmedAt) || undefined, remark: stringValue(item.remark), createdBy: stringValue(item.createdBy), createdByName: stringValue(item.createdByName), createdAt: stringValue(item.createdAt), updatedBy: stringValue(item.updatedBy), updatedByName: stringValue(item.updatedByName), updatedAt: stringValue(item.updatedAt) }))
+}
+
+export async function listFinanceReceivableSettlements(customerId?: string): Promise<FinanceReceivableSettlement[]> {
+  const response = await http.get<ApiEnvelope<RawResource[]>, ApiEnvelope<RawResource[]>>(`${basePath}/receivable-settlements`, { params: { customerId: customerId?.trim() || undefined } })
+  return unwrapApiResponse(response).map((item) => ({
+    id: stringValue(item.settlementId ?? item.id), customerId: stringValue(item.customerId),
+    customerName: stringValue(item.customerName), settlementNo: stringValue(item.settlementNo), reconciliationStatementId: item.reconciliationStatementId == null ? undefined : stringValue(item.reconciliationStatementId), reconciliationStatementNo: stringValue(item.reconciliationStatementNo) || undefined, businessPeriod: stringValue(item.businessPeriod), feeItemSummary: stringValue(item.feeItemSummary) || undefined, generatedDate: stringValue(item.generatedDate), createdBy: stringValue(item.createdBy) || undefined, createdByName: stringValue(item.createdByName) || undefined, createdAt: stringValue(item.createdAt) || undefined, updatedAt: stringValue(item.updatedAt) || undefined, lastPaymentAt: stringValue(item.lastPaymentAt) || undefined, billDate: stringValue(item.generatedDate ?? item.billDate),
+    dueDate: stringValue(item.dueDate), receivableAmount: numberValue(item.totalAmount ?? item.receivableAmount),
+    receivedAmount: numberValue(item.paidAmount ?? item.receivedAmount), outstandingAmount: numberValue(item.outstandingAmount),
+    paymentStatus: stringValue(item.paymentStatus) as FinanceReceivableSettlement['paymentStatus'], currency: 'CNY', status: stringValue(item.status) as FinanceReceivableSettlement['status'], version: numberValue(item.version),
+  }))
+}
+
+export async function listFinancePayableSettlements(customerId?: string): Promise<FinancePayableSettlement[]> {
+  const response = await http.get<ApiEnvelope<RawResource[]>, ApiEnvelope<RawResource[]>>(`${basePath}/payable-settlements`, { params: { customerId: customerId?.trim() || undefined } })
+  return unwrapApiResponse(response).map((item) => ({
+    id: stringValue(item.settlementId ?? item.id), customerId: stringValue(item.customerId), customerName: stringValue(item.customerName), settlementNo: stringValue(item.settlementNo), supplierId: item.supplierId == null ? undefined : stringValue(item.supplierId),
+    costType: 'SINGLE_ORDER', orderId: null, inboundId: null, containerId: null,
+    supplierName: stringValue(item.supplierName), feeItemName: stringValue(item.feeItemSummary), feeItemSummary: stringValue(item.feeItemSummary) || undefined, businessPeriod: stringValue(item.businessPeriod), generatedDate: stringValue(item.generatedDate), dueDate: stringValue(item.dueDate), payableAmount: numberValue(item.totalAmount ?? item.payableAmount),
+    paidAmount: numberValue(item.paidAmount), outstandingAmount: numberValue(item.outstandingAmount), paymentStatus: stringValue(item.paymentStatus) as FinancePayableSettlement['paymentStatus'], currency: 'CNY',
+    status: stringValue(item.status), createdAt: stringValue(item.createdAt), createdBy: stringValue(item.createdBy) || undefined, createdByName: stringValue(item.createdByName) || undefined, updatedAt: stringValue(item.updatedAt) || undefined, lastPaymentAt: stringValue(item.lastPaymentAt) || undefined, version: numberValue(item.version),
+  }))
+}
+
+function normalizeCustomerTerms(item: RawResource, customerId: string): FinanceCustomerTerms {
+  return {
+    customerId: stringValue(item.tenant_id ?? item.tenantId ?? customerId),
+    customerName: stringValue(item.customer_name_snapshot ?? item.customerName),
+    creditDays: numberValue(item.credit_days ?? item.creditDays ?? 30),
+    status: stringValue(item.status) || 'ACTIVE',
+  }
+}
+
+export async function getFinanceCustomerTerms(customerId: string) {
+  const response = await http.get<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/customers/${customerId}/terms`)
+  return normalizeCustomerTerms(unwrapApiResponse(response), customerId)
+}
+
+export async function updateFinanceCustomerTerms(customerId: string, payload: { customerName: string; creditDays: number }) {
+  const response = await http.put<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/customers/${customerId}/terms`, payload, mutationHeaders('customer-terms'))
+  return normalizeCustomerTerms(unwrapApiResponse(response), customerId)
+}
+
+export async function getFinanceBill(billId: string) {
+  const response = await http.get<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/bills/${billId}`)
+  return normalizeBillDetail(unwrapApiResponse(response))
+}
+
+export async function listFinanceBillRevisions(billId: string, customerId: string): Promise<FinanceBillRevision[]> {
+  const response = await http.get<ApiEnvelope<RawResource[]>, ApiEnvelope<RawResource[]>>(`${basePath}/bills/${billId}/revisions`, { params: { customerId } })
+  return unwrapApiResponse(response).map((item) => {
+    const bill = jsonRecord(item.bill_snapshot ?? item.billSnapshot)
+    const lines = jsonRecords(item.line_snapshot ?? item.lineSnapshot)
+    return {
+      id: stringValue(item.id), billId: stringValue(item.bill_id ?? item.billId ?? billId), version: numberValue(item.version),
+      reason: stringValue(item.reason), createdBy: stringValue(item.created_by ?? item.createdBy), createdAt: stringValue(item.created_at ?? item.createdAt),
+      status: stringValue(bill.status) as FinanceBillRevision['status'], totalAmount: numberValue(bill.total_amount ?? bill.totalAmount),
+      receivedAmount: numberValue(bill.received_amount ?? bill.receivedAmount), outstandingAmount: numberValue(bill.outstanding_amount ?? bill.outstandingAmount),
+      lines: lines.map(normalizeBillLine),
+    }
+  })
+}
+
+export async function updateFinanceBill(billId: string, payload: Record<string, unknown>) {
+  const response = await http.put<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/bills/${billId}`, payload, mutationHeaders('bill-update'))
+  return normalizeBillDetail(unwrapApiResponse(response))
+}
+
+export async function adjustFinanceBill(billId: string, payload: Record<string, unknown>) {
+  const response = await http.post<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/bills/${billId}/adjust`, payload, mutationHeaders('bill-adjust'))
+  return normalizeBillDetail(unwrapApiResponse(response))
+}
+
+export async function voidFinanceBill(billId: string, expectedVersion: number, reason: string) {
+  const response = await http.post<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/bills/${billId}/void`, { expectedVersion, reason }, mutationHeaders('bill-void'))
+  return normalizeBillDetail(unwrapApiResponse(response))
+}
+
+export async function createFinanceReceipt(payload: Record<string, unknown>, voucherFileIds: string[]) {
+  const response = await http.post<ApiEnvelope<FinanceReceiptResource>, ApiEnvelope<FinanceReceiptResource>>(`${basePath}/receipts`, { ...payload, currency: 'CNY', voucherFileIds }, { headers: { 'Idempotency-Key': idempotencyKey('receipt') } })
+  return unwrapApiResponse(response)
+}
+
+export async function uploadFinanceVoucher(customerId: string, file: File): Promise<FinanceVoucherResource> {
+  const body = new FormData()
+  body.append('file', file)
+  const response = await http.post<ApiEnvelope<RawResource>, ApiEnvelope<RawResource>>(`${basePath}/vouchers`, body, {
+    params: { customerId }, headers: { 'Content-Type': 'multipart/form-data' },
+  })
+  const item = unwrapApiResponse(response)
+  return {
+    fileId: stringValue(item.fileId ?? item.file_id), customerId: stringValue(item.tenantId ?? item.customerId ?? customerId),
+    fileName: stringValue(item.fileName ?? item.file_name), contentType: stringValue(item.contentType ?? item.content_type),
+    sizeBytes: numberValue(item.sizeBytes ?? item.size_bytes),
+  }
+}
+
+export async function createFinanceCost(payload: Record<string, unknown>, voucherFileIds: string[]) {
+  const response = await http.post<ApiEnvelope<FinanceCostResource>, ApiEnvelope<FinanceCostResource>>(`${basePath}/cost-entries`, { ...payload, currency: 'CNY', voucherFileIds }, { headers: { 'Idempotency-Key': idempotencyKey('cost') } })
+  return unwrapApiResponse(response)
+}
+
+export interface FinancePaymentVoucher {
+  fileId: string
+  fileName: string
+  contentType: string
+  sizeBytes: number
+}
+export async function getFinancePaymentVoucher(customerId: string, fileId: string): Promise<FinancePaymentVoucher> {
+  return unwrapApiResponse(await http.get<ApiEnvelope<FinancePaymentVoucher>, ApiEnvelope<FinancePaymentVoucher>>(
+    `${basePath}/vouchers/${encodeURIComponent(fileId)}`, { params: { customerId } }))
+}
+export function downloadFinancePaymentVoucher(customerId: string, fileId: string): Promise<Blob> {
+  return http.get<Blob, Blob>(`${basePath}/vouchers/${encodeURIComponent(fileId)}/content`, {
+    params: { customerId }, responseType: 'blob',
+  })
+}
diff --git a/src/modules/finance/components/CustomerStatementsPanel.test.ts b/src/modules/finance/components/CustomerStatementsPanel.test.ts
new file mode 100644
index 00000000..de59c01a
--- /dev/null
+++ b/src/modules/finance/components/CustomerStatementsPanel.test.ts
@@ -0,0 +1,79 @@
+import ElementPlus from 'element-plus'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { createPinia, setActivePinia } from 'pinia'
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+import { getReconciliationStatement, listFinanceStatements } from '../api/finance'
+import CustomerStatementsPanel from './CustomerStatementsPanel.vue'
+
+vi.mock('../api/finance', () => ({
+  getReconciliationStatement: vi.fn(),
+  listFinanceStatements: vi.fn(),
+}))
+
+const statement = {
+  id: 'statement-1', customerId: '8', billNo: 'ST202608001', customerName: '柏悦物流',
+  billDate: '2026-08-01', dueDate: '2026-08-31', totalAmount: 1200, receivedAmount: 200,
+  outstandingAmount: 1000, currency: 'CNY' as const, status: 'ISSUED' as const, version: 1,
+}
+
+function mountPanel(permissions: string[]) {
+  const pinia = createPinia()
+  setActivePinia(pinia)
+  const auth = useAuthStore()
+  auth.token = 'token'
+  auth.permissions = permissions
+  useAccessPreviewStore().initializeAfterLogin()
+  return mount(CustomerStatementsPanel, {
+    props: { customerId: '8', customerName: '柏悦物流' },
+    global: { plugins: [pinia, ElementPlus] },
+  })
+}
+
+describe('CustomerStatementsPanel', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.mocked(listFinanceStatements).mockResolvedValue([statement])
+  })
+
+  it('loads only the selected customer statements', async () => {
+    const wrapper = mountPanel(['platform:finance:customer-statement:list'])
+    await flushPromises()
+
+    expect(listFinanceStatements).toHaveBeenCalledWith('8')
+    expect(wrapper.text()).toContain('ST202608001')
+    expect(wrapper.text()).toContain('1,200.00')
+  })
+
+  it('does not query finance without statement permission', async () => {
+    const wrapper = mountPanel([])
+    await flushPromises()
+
+    expect(listFinanceStatements).not.toHaveBeenCalled()
+    expect(wrapper.text()).toContain('暂无财务账单查看权限')
+  })
+
+  it('loads the real reconciliation detail from the statement row', async () => {
+    vi.mocked(getReconciliationStatement).mockResolvedValue({
+      ...statement, paidAmount: 200, remark: '', periodStart: '2026-07-01', periodEnd: '2026-07-31',
+      creditDays: 30, settled: false, lines: [{ statementLineId: 'line-1', sourceFeeId: 'fee-1', sourceFeeVersion: 1, orderId: null, inboundId: 'inbound-1', feeItemName: '入库操作费', amount: 1200 }],
+      paymentHistory: [], revisions: [],
+    })
+    const wrapper = mountPanel(['platform:finance:customer-statement:list'])
+    await flushPromises()
+    await wrapper.get('button[aria-label="查看对账单ST202608001详情"]').trigger('click')
+    await flushPromises()
+
+    expect(getReconciliationStatement).toHaveBeenCalledWith('statement-1')
+    expect(wrapper.text()).toContain('入库操作费')
+  })
+
+  it('uses a small primary entity button for the embedded statement detail action', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/finance/components/CustomerStatementsPanel.vue'), 'utf8')
+    expect(source).toContain('<el-button size="small" plain type="primary"')
+    expect(source).not.toContain('<el-button link')
+  })
+})
diff --git a/src/modules/finance/components/CustomerStatementsPanel.vue b/src/modules/finance/components/CustomerStatementsPanel.vue
new file mode 100644
index 00000000..f3d54354
--- /dev/null
+++ b/src/modules/finance/components/CustomerStatementsPanel.vue
@@ -0,0 +1,101 @@
+<script setup lang="ts">
+import { ref, watch } from 'vue'
+import { Eye, FileText } from '@lucide/vue'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AppDrawer from '@/shared/components/AppDrawer.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { getReconciliationStatement, listFinanceStatements } from '../api/finance'
+import { financeStatusLabel, financeStatusTone } from '../status'
+import type { FinanceReconciliationDetail, FinanceStatementReadModel } from '../types'
+
+const props = defineProps<{ customerId: string; customerName: string }>()
+const access = useAccessPreviewStore()
+const rows = ref<FinanceStatementReadModel[]>([])
+const loading = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const detailOpen = ref(false)
+const detailLoading = ref(false)
+const detail = ref<FinanceReconciliationDetail | null>(null)
+const detailError = ref<ApiErrorDetails | null>(null)
+let requestSerial = 0
+
+const columns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 92, fixed: 'left', slotName: 'actions' },
+  { key: 'billNo', prop: 'billNo', label: '对账单号', minWidth: 180 },
+  { key: 'billDate', prop: 'billDate', label: '账单日期', width: 120 },
+  { key: 'dueDate', prop: 'dueDate', label: '到期日', width: 120 },
+  { key: 'totalAmount', label: '应收(CNY)', width: 130, align: 'right', slotName: 'totalAmount' },
+  { key: 'receivedAmount', label: '已收(CNY)', width: 130, align: 'right', slotName: 'receivedAmount' },
+  { key: 'outstandingAmount', label: '未收(CNY)', width: 130, align: 'right', slotName: 'outstandingAmount' },
+  { key: 'status', label: '状态', width: 110, slotName: 'status' },
+]
+
+async function load() {
+  const customerId = props.customerId.trim()
+  const serial = ++requestSerial
+  rows.value = []
+  loadError.value = null
+  if (!customerId || !access.can('platform:finance:customer-statement:list')) return
+  loading.value = true
+  try {
+    const result = await listFinanceStatements(customerId)
+    if (serial === requestSerial && customerId === props.customerId.trim()) rows.value = result
+  } catch (error) {
+    if (serial === requestSerial) loadError.value = getApiErrorDetails(error, '客户财务账单加载失败，请稍后重试')
+  } finally {
+    if (serial === requestSerial) loading.value = false
+  }
+}
+
+async function openDetail(row: FinanceStatementReadModel) {
+  detailOpen.value = true
+  detailLoading.value = true
+  detail.value = null
+  detailError.value = null
+  try { detail.value = await getReconciliationStatement(row.id) }
+  catch (error) { detailError.value = getApiErrorDetails(error, '对账单详情加载失败，请稍后重试') }
+  finally { detailLoading.value = false }
+}
+
+function formatAmount(value: number) {
+  return value.toLocaleString('zh-CN', { minimumFractionDigits: 2, maximumFractionDigits: 2 })
+}
+
+watch(() => props.customerId, () => { void load() }, { immediate: true })
+</script>
+
+<template>
+  <section class="customer-statements-panel">
+    <div class="panel-title"><div><h2>财务账单</h2><p>{{ customerName }}的客户对账单</p></div><FileText :size="19" /></div>
+    <div v-if="!access.can('platform:finance:customer-statement:list')" class="module-empty"><FileText :size="30" /><strong>暂无财务账单查看权限</strong><p>请联系管理员开通客户对账单查看权限。</p></div>
+    <LoadErrorState v-else-if="loadError" title="客户财务账单加载失败" :message="loadError.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="loadError" /></template></LoadErrorState>
+    <DataTable v-else :data="rows" :columns="columns" :loading="loading" row-key="id" aria-label="客户财务账单列表" empty-text="当前客户暂无财务账单" border stripe>
+      <template #actions="{ row }"><el-button size="small" plain type="primary" :disabled="loading" :aria-label="`查看对账单${(row as FinanceStatementReadModel).billNo}详情`" @click="openDetail(row as FinanceStatementReadModel)"><Eye :size="15" />详情</el-button></template>
+      <template #totalAmount="{ row }">{{ formatAmount((row as FinanceStatementReadModel).totalAmount) }}</template>
+      <template #receivedAmount="{ row }">{{ formatAmount((row as FinanceStatementReadModel).receivedAmount) }}</template>
+      <template #outstandingAmount="{ row }">{{ formatAmount((row as FinanceStatementReadModel).outstandingAmount) }}</template>
+      <template #status="{ row }"><el-tag :type="financeStatusTone((row as FinanceStatementReadModel).status)">{{ financeStatusLabel((row as FinanceStatementReadModel).status) }}</el-tag></template>
+      <template #pagination-left>币种：CNY</template>
+    </DataTable>
+
+    <AppDrawer v-model="detailOpen" title="客户对账单详情" size="min(820px, 94vw)" :loading="detailLoading">
+      <LoadErrorState v-if="detailError" title="详情加载失败" :message="detailError.message" :loading="detailLoading"><template #details><ApiErrorMeta :details="detailError" /></template></LoadErrorState>
+      <template v-else-if="detail">
+        <el-descriptions :column="2" border><el-descriptions-item label="对账单号">{{ detail.billNo }}</el-descriptions-item><el-descriptions-item label="客户">{{ detail.customerName }}</el-descriptions-item><el-descriptions-item label="状态">{{ financeStatusLabel(detail.status) }}</el-descriptions-item><el-descriptions-item label="金额">{{ detail.totalAmount }} CNY</el-descriptions-item><el-descriptions-item label="账期">{{ detail.periodStart }} 至 {{ detail.periodEnd }}</el-descriptions-item><el-descriptions-item label="未收金额">{{ detail.outstandingAmount }} CNY</el-descriptions-item></el-descriptions>
+        <el-table :data="detail.lines" size="small" border stripe><el-table-column prop="feeItemName" label="费用项目" /><el-table-column prop="amount" label="账单金额(CNY)" /></el-table>
+        <el-table v-if="detail.revisions.length" :data="detail.revisions" size="small" border stripe><el-table-column prop="revisionNo" label="修订" width="72" /><el-table-column prop="action" label="动作" width="130" /><el-table-column prop="beforeAmount" label="调整前" /><el-table-column prop="afterAmount" label="调整后" /><el-table-column prop="reason" label="原因" /></el-table>
+      </template>
+    </AppDrawer>
+  </section>
+</template>
+
+<style scoped>
+.customer-statements-panel { min-width:0; }
+.panel-title { display:flex; align-items:flex-start; justify-content:space-between; gap:16px; margin-bottom:18px; padding-bottom:14px; border-bottom:1px solid var(--cc-border); }
+.panel-title h2 { margin:0; color:#344054; font-size:16px; }.panel-title p { margin:5px 0 0; color:var(--cc-muted); font-size:11px; }.panel-title > svg { color:var(--cc-primary); }
+.module-empty { display:flex; min-height:260px; align-items:center; justify-content:center; flex-direction:column; gap:7px; color:#98a2b3; text-align:center; }.module-empty strong { color:#475467; font-size:13px; }.module-empty p { max-width:520px; margin:0; color:var(--cc-muted); font-size:12px; line-height:1.7; }
+:deep(.el-descriptions) { margin-bottom:18px; }:deep(.el-table + .el-table) { margin-top:18px; }
+</style>
diff --git a/src/modules/finance/financeDelivery.test.ts b/src/modules/finance/financeDelivery.test.ts
new file mode 100644
index 00000000..6b1daa0f
--- /dev/null
+++ b/src/modules/finance/financeDelivery.test.ts
@@ -0,0 +1,102 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+function source(path: string) {
+  return readFileSync(resolve(process.cwd(), path), 'utf8')
+}
+
+describe('finance six-page delivery contract', () => {
+  const routes = source('src/modules/finance/routes.ts')
+  const navigation = source('src/core/navigation/adminNavigation.ts')
+  const api = source('src/modules/finance/api/finance.ts')
+
+  const pages = [
+    ['finance/customer-accounts', '客户账户'],
+    ['finance/customer-arap', '客户应收应付'],
+    ['finance/receivable-statistics', '应收款统计表'],
+    ['finance/customer-statements', '客户对账单'],
+    ['finance/settlement-receivables', '结算单应收'],
+    ['finance/settlement-payables', '结算单应付'],
+  ] as const
+
+  it('registers the six menu routes plus hidden detail routes', () => {
+    for (const [path, title] of pages) {
+      expect(routes).toContain(`path: '${path}'`)
+      expect(routes).toContain(`title: '${title}'`)
+      expect(navigation).toContain(`path: '/${path}'`)
+      expect(navigation).toContain(`title: '${title}'`)
+    }
+    expect(navigation.match(/path: '\/finance\//g)).toHaveLength(6)
+    expect(routes.match(/path: 'finance\/customer-accounts\/:customerId'/g)).toHaveLength(1)
+    expect(routes.match(/path: 'finance\/customer-arap\/:feeSourceId'/g)).toHaveLength(1)
+    expect(navigation).not.toContain('/finance/customer-accounts/:customerId')
+    expect(navigation).not.toContain('/finance/customer-arap/:feeSourceId')
+  })
+
+  it('does not expose the old three routes or out-of-scope reports', () => {
+    for (const forbidden of ['/finance/bills', '/finance/receipts', '/finance/costs', '费用分析', '利润表']) {
+      expect(routes).not.toContain(forbidden)
+      expect(navigation).not.toContain(forbidden)
+    }
+  })
+
+  it('keeps production reads on fixed DTO endpoints only', () => {
+    for (const endpoint of ['customer-accounts', 'fee-pool', 'receivable-statistics', 'statements', 'receivable-settlements', 'payable-settlements']) {
+      expect(api).toContain(`${basePathMarker(endpoint)}`)
+    }
+    expect(api).not.toContain('function listFinanceBills')
+    expect(api).not.toContain('function listFinanceReceipts')
+    expect(api).not.toContain('function listFinanceCosts')
+  })
+
+  it('connects G1 customer accounts to the formal list and ledger operations', () => {
+    const page = source('src/modules/finance/pages/FinanceCustomerAccountsView.vue')
+    const types = source('src/modules/finance/types.ts')
+    expect(api).toContain('`${basePath}/accounts`')
+    expect(api).toContain('`${basePath}/accounts/${customerId}/ledger`')
+    expect(page).toContain('listFinanceAccounts')
+    expect(page).toContain('listFinanceAccountLedger')
+    expect(page).not.toContain('getFinanceCustomerAccount')
+    expect(page).not.toContain('接口尚未提供')
+    expect(page).toContain("key: 'customerId', type: 'select', label: '客户名称'")
+    expect(page).toContain('options: customers.value.filter')
+    expect(page).toContain('label: item.tenantName')
+    expect(page).not.toContain('tenantCode')
+    expect(types).toContain('export interface FinanceAccountSummary')
+    expect(types).toContain('actualBalance: string')
+    expect(types).toContain('export interface FinanceRechargeRequest')
+    expect(api).toContain('data.map(normalizeFinanceAccount)')
+    for (const metric of ['实际余额', '冻结金额', '可用余额']) expect(page).toContain(metric)
+    for (const operation of ['listFinanceRechargeRequests', 'reviewFinanceRechargeRequest', 'adjustFinanceAccount']) expect(page).toContain(operation)
+    const columns = page.slice(page.indexOf('const columns: DataTableColumn[]'))
+    expect(columns.indexOf("key: 'actions'")).toBeLessThan(columns.indexOf("key: 'customerName'"))
+    for (const state of ['客户账户加载失败', '暂无客户账户', '无权访问客户账户', '账户流水加载失败']) expect(page).toContain(state)
+  })
+
+  it('connects fee sources to the real edit and review lifecycle', () => {
+    const page = source('src/modules/finance/pages/FinanceCustomerArapView.vue')
+    for (const marker of [
+      '`${basePath}/fee-sources/${feeSourceId}`',
+      '`${basePath}/fee-sources/${feeSourceId}/review`',
+      '`${basePath}/fee-sources/${feeSourceId}/submit`',
+      '`${basePath}/fee-sources/${feeSourceId}/adjust`',
+      '`${basePath}/fee-sources/${feeSourceId}/void`',
+    ]) expect(api).toContain(marker)
+    for (const operation of ['getFinanceFeeSource', 'reviewFinanceFeeSource', 'editFinanceFeeSource', 'submitFinanceFeeSource', 'adjustFinanceFeeSource', 'voidFinanceFeeSource']) expect(page).toContain(operation)
+    for (const permission of ['platform:finance:customer-arap:list', 'platform:finance:fee-source:review', 'platform:finance:fee-source:edit']) expect(page).toContain(permission)
+    expect(page).toContain('expectedVersion: detail.value.operationVersion')
+    const columns = page.slice(page.indexOf('const columns:'))
+    expect(columns.indexOf("key: 'actions'")).toBeLessThan(columns.indexOf("key: 'direction'"))
+    expect(page).toContain('<ApiErrorMeta :details="detailError"')
+    expect(page).toContain('<OperationErrorToast :details="reviewError || mutationError" />')
+    expect(page).not.toContain('<ApiErrorMeta :details="reviewError"')
+    expect(page).not.toContain('<ApiErrorMeta :details="mutationError"')
+    expect(page).not.toContain('接口尚未提供')
+    expect(page).not.toContain('disabled title=')
+  })
+})
+
+function basePathMarker(endpoint: string) {
+  return '${basePath}/' + endpoint
+}
diff --git a/src/modules/finance/financeDensity.css b/src/modules/finance/financeDensity.css
new file mode 100644
index 00000000..53e4487f
--- /dev/null
+++ b/src/modules/finance/financeDensity.css
@@ -0,0 +1,17 @@
+/* Finance owns document layout; controls and visual primitives stay shared. */
+.admin-density .detail-page-layout.finance-density-detail { gap: 0; }
+.admin-density .finance-density-detail > .detail-page-layout__header,
+.admin-density .finance-density-detail > .detail-page-layout__summary { padding: 0; }
+.admin-density .finance-density-detail > .detail-page-layout__content,
+.admin-density .finance-density-detail > .detail-page-layout__footer { min-width: 0; padding: var(--admin-space-5); }
+.admin-density .finance-detail-actions { display: flex; flex-wrap: wrap; align-items: center; justify-content: flex-end; gap: var(--admin-space-3); }
+.admin-density .finance-detail-context { min-width: 0; color: var(--cc-muted); font-size: var(--admin-font-caption); overflow-wrap: anywhere; }
+.admin-density .statement-summary-grid .statement-summary-item--remark { grid-column: span 2; }
+.admin-density .settlement-summary.density-detail-overview { padding: 0; border: 0; }
+.admin-density .statement-summary-section { padding: var(--admin-space-5); }
+.admin-density .account-metrics .is-negative,
+.admin-density .density-detail-overview .is-danger,
+.admin-density-dialog .partial-summary .is-danger { color: var(--el-color-danger); }
+.admin-density .density-detail-overview .is-success,
+.admin-density-dialog .partial-summary .is-success { color: var(--el-color-success); }
+.admin-density-dialog .partial-summary { margin-bottom: var(--admin-space-5); }
diff --git a/src/modules/finance/index.ts b/src/modules/finance/index.ts
new file mode 100644
index 00000000..17bb1a6a
--- /dev/null
+++ b/src/modules/finance/index.ts
@@ -0,0 +1,11 @@
+export { financeRoutes } from './routes'
+export { default as CustomerStatementsPanel } from './components/CustomerStatementsPanel.vue'
+export {
+  getFinanceCustomerAccountSummary,
+  getFinancePaymentVoucher,
+  downloadFinancePaymentVoucher,
+  getFinanceSettlement,
+  listFinancePayableSettlements,
+  listFinanceReceivableSettlements,
+  type FinanceCustomerAccountSummaryResource,
+} from './api/finance'
diff --git a/src/modules/finance/pages/FinanceCustomerAccountsView.test.ts b/src/modules/finance/pages/FinanceCustomerAccountsView.test.ts
new file mode 100644
index 00000000..c0d5b51c
--- /dev/null
+++ b/src/modules/finance/pages/FinanceCustomerAccountsView.test.ts
@@ -0,0 +1,357 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import ElementPlus, { ElMessage } from 'element-plus'
+import { createPinia, setActivePinia } from 'pinia'
+import { flushPromises, mount } from '@vue/test-utils'
+import { createMemoryHistory, createRouter } from 'vue-router'
+import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+import { createPlatformExportTask } from '@/modules/downloads'
+import { listPlatformTenants, type PlatformTenantResource } from '@/modules/iam'
+import { showExportTaskCreatedDialog } from '@/shared/components/exportTaskCreatedDialog'
+import { adjustFinanceAccount, downloadFinanceRechargeVoucher, listFinanceAccountLedger, listFinanceAccounts, listFinanceRechargeRequests, reviewFinanceRechargeRequest, updateFinanceCreditLimit } from '../api/finance'
+import FinanceCustomerAccountsView from './FinanceCustomerAccountsView.vue'
+
+vi.mock('../api/finance', () => ({
+  listFinanceAccounts: vi.fn(),
+  listFinanceAccountLedger: vi.fn(),
+  listFinanceRechargeRequests: vi.fn(),
+  reviewFinanceRechargeRequest: vi.fn(),
+  adjustFinanceAccount: vi.fn(),
+  updateFinanceCreditLimit: vi.fn(),
+  downloadFinanceRechargeVoucher: vi.fn(),
+  getFinanceCustomerTerms: vi.fn(),
+  updateFinanceCustomerTerms: vi.fn(),
+}))
+vi.mock('@/modules/iam', () => ({ listPlatformTenants: vi.fn() }))
+vi.mock('@/modules/downloads', () => ({ createPlatformExportTask: vi.fn() }))
+vi.mock('@/shared/components/exportTaskCreatedDialog', () => ({ showExportTaskCreatedDialog: vi.fn() }))
+
+class ResizeObserverStub implements ResizeObserver { observe() {} unobserve() {} disconnect() {} }
+
+function memoryStorage(): Storage {
+  const values = new Map<string, string>()
+  return { get length() { return values.size }, clear: () => values.clear(), getItem: (key) => values.get(key) ?? null, key: (index) => [...values.keys()][index] ?? null, removeItem: (key) => values.delete(key), setItem: (key, value) => values.set(key, value) }
+}
+
+const accountFixture = {
+  customerId: '10001', customerCode: 'C-001', customerName: '客户A', contactName: '张三', contactPhone: '13800000000',
+  outstandingReceivable: 100, pendingBilling: 20, receivedInPeriod: 30, totalCost: 90, paidCost: 50, outstandingPayable: 40,
+  actualBalance: '126580.50', frozenBalance: '8500.00', availableBalance: '138080.50', creditLimit: '20000.00', creditUsed: '0.00', availableCredit: '20000.00', creditExpiresOn: '2028-09-10', creditActive: true, accountVersion: 7, pendingRechargeCount: 1,
+  status: 'ACTIVE', lastChangedAt: '2026-08-13 10:00:00',
+}
+
+async function mountAccountsView(permissions: string[], initialPath = '/finance/customer-accounts') {
+  const pinia = createPinia(); setActivePinia(pinia)
+  const auth = useAuthStore(); auth.token = 'token'; auth.permissions = permissions
+  useAccessPreviewStore().initializeAfterLogin()
+  const router = createRouter({ history: createMemoryHistory(), routes: [
+    { path: '/finance/customer-accounts', name: 'finance-customer-accounts', component: FinanceCustomerAccountsView },
+    { path: '/finance/customer-accounts/:customerId', name: 'finance-customer-account-detail', component: FinanceCustomerAccountsView },
+    { path: '/downloads', name: 'download-center', component: { template: '<div>下载中心</div>' } },
+  ] })
+  await router.push(initialPath); await router.isReady()
+  const wrapper = mount(FinanceCustomerAccountsView, { global: { plugins: [pinia, ElementPlus, router] } })
+  await flushPromises()
+  return Object.assign(wrapper, { router })
+}
+
+describe('FinanceCustomerAccountsView delivery', () => {
+  const page = readFileSync(resolve(process.cwd(), 'src/modules/finance/pages/FinanceCustomerAccountsView.vue'), 'utf8')
+  const routes = readFileSync(resolve(process.cwd(), 'src/modules/finance/routes.ts'), 'utf8')
+
+  it('keeps the account detail as a full page with traceable ledger controls', () => {
+    expect(page).toContain('v-else-if="!detailOpen"')
+    expect(page).toContain('返回客户账户')
+    expect(page).toContain('<DetailPageLayout')
+    expect(page).toContain('class="density-detail-overview account-metrics"')
+    for (const metric of ['实际余额', '冻结金额', '总可用余额', '授信额度', '已用授信', '可用授信']) expect(page).toContain(metric)
+    expect(page).toContain('class="ledger-query"')
+    expect(page).toContain('@search="ledgerPage = 1; void loadLedger($event)"')
+    expect(page).toContain('class="ledger-table"')
+    expect(page).toContain('<template #toolbar-actions>')
+    expect(page).toContain('<template #pagination-left>共 {{ ledgerTotal }} 条</template>')
+    expect(page).not.toContain('class="detail-toolbar"')
+    expect(page).not.toContain('<AppDrawer')
+    for (const marker of ['充值申请', '待审核', '审核', '流水类型', '发生日期', '导出流水', 'listFinanceAccountLedger', 'listFinanceRechargeRequests']) expect(page).toContain(marker)
+    for (const code of ['RECONCILIATION_CREATED', 'SETTLEMENT_ISSUED', 'RECEIPT',
+      'SUPPLIER_DIRECT_PAID', 'SUPPLIER_ON_ACCOUNT_PAYMENT', 'ADJUSTMENT', 'VOID']) expect(page).toContain(code)
+    for (const removed of ['FEE_INCLUDED', 'FEE_EXCLUDED', '纳入结算', '排除结算']) expect(page).not.toContain(removed)
+    for (const obsolete of ["value: 'FEE_SOURCE'", "value: 'RECONCILIATION'", "value: 'SETTLEMENT'"]) expect(page).not.toContain(obsolete)
+  })
+
+  it('keeps term editing aligned with the account summary and nearby actions', () => {
+    for (const marker of ['class="term-section density-form-section"', 'class="term-editor"', '账期天数', '#footer', '保存账期']) expect(page).toContain(marker)
+    expect(page).toContain('density-detail-overview account-metrics')
+    for (const column of ['实际余额(CNY)', '冻结金额(CNY)', '总可用余额(CNY)', '授信额度(CNY)', '已用授信(CNY)', '待审核充值']) expect(page).toContain(column)
+    expect(page).toContain('grid-template-columns: 120px minmax(0, 220px)')
+    expect(page).toContain('justify-content: start')
+    expect(page).toContain('class="surface-panel finance-account-detail__surface"')
+    expect(page).toContain('class="density-detail-header"')
+    expect(page).toContain('padding: var(--admin-space-4) 0')
+    expect(page).toContain('class="detail-table-scroll"')
+    expect(page).toContain('class="ledger-identifier"')
+    expect(page).toContain('class="ledger-document"')
+    expect(page).toContain('text-overflow: ellipsis')
+    expect(page).toContain('white-space: nowrap')
+  })
+
+  it('keeps account detail and term editing readable across the 1920 workspace', () => {
+    expect(page).toContain('width: min(100%, 1920px)')
+    expect(page).toContain('@media (min-width: 1920px)')
+    expect(page).toContain('finance-density-detail')
+    expect(page).toContain('../financeDensity.css')
+    expect(page).not.toContain('max-width: 520px')
+  })
+
+  it('keeps high-frequency account actions visible and groups the remaining actions', () => {
+    expect(page).toContain("{ key: 'actions', label: '操作', width: 290, fixed: 'left', slotName: 'actions' }")
+    expect(page).toContain('@click="openAccount(row, false)">详情</el-button>')
+    expect(page).toContain("openAdjustment(row as FinanceAccountSummary, 'RECHARGE')")
+    expect(page).toContain("openAdjustment(row as FinanceAccountSummary, 'DEDUCTION')")
+    expect(page).toContain('aria-label="更多客户账户操作"')
+    expect(page).toContain('<el-dropdown-item v-if="canAdjust" command="credit">授信</el-dropdown-item>')
+    expect(page).toContain('<el-dropdown-item v-if="canUpdateTerms" command="terms" :divided="canAdjust">账期</el-dropdown-item>')
+    expect(page).not.toContain('<el-button link type="primary" @click="openAccount(row, false)">')
+    expect(page).toContain('class="row-actions density-actions"')
+    expect(page).toContain('white-space: nowrap')
+  })
+
+  it('shows authoritative CNY wallet balances and independently permitted actions', () => {
+    for (const marker of ['实际余额', '冻结金额', '总可用余额', '授信额度', '已用授信', '可用授信', '手工充值', '手工扣款', '设置授信', 'platform:finance:customer-account:adjust', 'platform:finance:recharge:review']) expect(page).toContain(marker)
+    expect(page).not.toContain('operatingFundsSummary')
+    expect(page).not.toContain('adjustmentAccount?.actualBalance -')
+  })
+
+  it.each([
+    [[], ['详情'], false],
+    [['platform:finance:customer-terms:view', 'platform:finance:customer-terms:update'], ['详情', '账期'], false],
+    [['platform:finance:customer-account:adjust'], ['详情', '充值', '扣款', ''], true],
+  ])('folds account operations only when more than three are available: %j', async (extraPermissions, labels, overflow) => {
+    const wrapper = await mountAccountsView(['platform:finance:customer-account:list', ...extraPermissions])
+    const actions = wrapper.get('.el-table__body-wrapper .density-actions')
+    expect(actions.findAll('button').map(button => button.text().trim())).toEqual(labels)
+    expect(actions.find('.el-dropdown').exists()).toBe(overflow)
+    if (overflow) {
+      const trigger = actions.get('button[aria-label="更多客户账户操作"]')
+      expect(trigger.text()).toBe('')
+      expect(trigger.find('svg').exists()).toBe(true)
+    }
+    wrapper.unmount()
+  })
+
+  it('selects an active customer by name from master data', () => {
+    expect(page).toContain("key: 'customerId', type: 'select'")
+    expect(page).toContain("label: '客户名称'")
+    expect(page).toContain('item.tenantName')
+    expect(page).not.toContain('tenantCode')
+    expect(page).toContain('listPlatformTenants')
+    expect(page).not.toContain("key: 'keyword', type: 'input'")
+  })
+
+  it('supports a refreshable customer detail route without inventing an API parameter', () => {
+    expect(routes).toContain("path: 'finance/customer-accounts/:customerId'")
+    expect(page).toContain("name: 'finance-customer-account-detail'")
+    expect(page).toContain('restoreAccountDetail(customerId)')
+    expect(page).toContain("listFinanceAccounts({ page: 1, size: 1, customerId })")
+    expect(page).toContain('customerId: String(filters.value.customerId ||')
+  })
+
+  beforeEach(() => {
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+    vi.stubGlobal('localStorage', memoryStorage())
+    vi.stubGlobal('sessionStorage', memoryStorage())
+    vi.stubGlobal('URL', { createObjectURL: vi.fn(() => 'blob:finance-voucher'), revokeObjectURL: vi.fn() })
+    vi.mocked(listFinanceAccounts).mockReset().mockResolvedValue({ records: [accountFixture], total: 1, pages: 1 })
+    vi.mocked(listFinanceAccountLedger).mockReset().mockResolvedValue({ records: [{ ledgerId: '1', occurredAt: '2026-08-13T10:00:00', businessType: 'REC', documentType: 'RECEIPT', documentId: '2', documentNo: 'REC-2', receivableChange: -10, payableChange: 0, outstandingReceivableAfter: 90, operatorName: 'operator-1000001', remark: '收款', businessNo: 'AC-1', changeType: 'RECHARGE', amount: '500.00', actualBalanceAfter: '126580.50', frozenBalanceAfter: '8500.00', availableBalanceAfter: '118080.50', sourceType: 'MANUAL_ADJUSTMENT', sourceNo: 'RC-2', createdAt: '2026-08-13T10:00:00' }], total: 1, pages: 1 })
+    vi.mocked(listFinanceRechargeRequests).mockReset().mockResolvedValue({ records: [{ requestId: '91', requestNo: 'RC-91', amount: '500.00', paymentMethod: 'WECHAT', voucherFileId: '81', voucherFileName: 'receipt.png', status: 'PENDING', version: 3, submittedByName: '客户A', reviewedByName: '', reviewRemark: '', createdAt: '2026-09-04T10:00:00', reviewedAt: '' }], total: 1, pages: 1 })
+    vi.mocked(reviewFinanceRechargeRequest).mockReset().mockResolvedValue({ requestId: '91', requestNo: 'RC-91', amount: '500.00', paymentMethod: 'WECHAT', voucherFileId: '81', voucherFileName: 'receipt.png', status: 'APPROVED', version: 4, submittedByName: '客户A', reviewedByName: '财务A', reviewRemark: '', createdAt: '2026-09-04T10:00:00', reviewedAt: '2026-09-05T10:00:00' })
+    vi.mocked(adjustFinanceAccount).mockReset().mockResolvedValue({ ...accountFixture, actualBalance: '127080.50', availableBalance: '118580.50', accountVersion: 8 })
+    vi.mocked(updateFinanceCreditLimit).mockReset().mockResolvedValue({ ledgerId: '102', businessNo: 'AC-102', changeType: 'CREDIT_LIMIT', amount: '20000.00', actualBalanceAfter: '126580.50', frozenBalanceAfter: '8500.00', availableBalanceAfter: '138080.50', creditLimitAfter: '20000.00', creditUsedAfter: '0.00', availableCreditAfter: '20000.00', creditExpiresOnAfter: '2028-09-10', sourceType: 'CREDIT_LIMIT_ADJUSTMENT', sourceNo: '', occurredAt: '', occurredDate: '2026-09-05', paymentMethod: '', referenceNo: '', operatorName: '财务A', remark: '', createdAt: '2026-09-05T10:00:00' })
+    vi.mocked(downloadFinanceRechargeVoucher).mockReset().mockResolvedValue(new Blob(['image'], { type: 'image/png' }))
+    vi.mocked(listPlatformTenants).mockReset().mockResolvedValue({ records: [{ id: '10001', tenantName: '客户A', status: 'ACTIVE' } as PlatformTenantResource], page: 1, size: 200, total: 1, pages: 1 })
+    vi.mocked(createPlatformExportTask).mockReset().mockResolvedValue({ id: 'exp-1', taskNo: 'EXP-1', taskName: '客户账户', status: 'PENDING' } as never)
+    vi.mocked(showExportTaskCreatedDialog).mockReset().mockResolvedValue(false)
+  })
+
+  it('restores account summary and ledger after opening the detail URL directly', async () => {
+    const pinia = createPinia(); setActivePinia(pinia)
+    const auth = useAuthStore(); auth.token = 'token'; auth.permissions = ['platform:finance:customer-account:list']
+    useAccessPreviewStore().initializeAfterLogin()
+    const router = createRouter({ history: createMemoryHistory(), routes: [
+      { path: '/finance/customer-accounts', name: 'finance-customer-accounts', component: FinanceCustomerAccountsView },
+      { path: '/finance/customer-accounts/:customerId', name: 'finance-customer-account-detail', component: FinanceCustomerAccountsView },
+    ] })
+    await router.push('/finance/customer-accounts/10001'); await router.isReady()
+    const wrapper = mount(FinanceCustomerAccountsView, { global: { plugins: [pinia, ElementPlus, router] } })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('客户A')
+    expect(wrapper.text()).toContain('C-001')
+    expect(wrapper.text()).toContain('张三')
+    expect(wrapper.text()).toContain('13800000000')
+    const metrics = wrapper.find('.account-metrics')
+    expect(metrics.findAll('.account-metric')).toHaveLength(6)
+    expect(metrics.text()).toContain('实际余额¥126580.50 CNY')
+    expect(metrics.text()).toContain('冻结金额¥8500.00 CNY')
+    expect(metrics.text()).toContain('总可用余额¥138080.50 CNY')
+    expect(metrics.text()).toContain('授信额度¥20000.00 2028-09-10 到期')
+    expect(metrics.text()).toContain('已用授信¥0.00 CNY')
+    expect(metrics.text()).toContain('可用授信¥20000.00 CNY')
+    for (const auxiliary of ['待开账金额', '本期已收', '总成本', '已付成本', '已收客户款', '客户线下支付']) expect(metrics.text()).not.toContain(auxiliary)
+    expect(listFinanceAccounts).toHaveBeenCalledWith({ page: 1, size: 1, customerId: '10001' })
+    expect(listFinanceAccountLedger).toHaveBeenCalledWith('10001', expect.objectContaining({ page: 1, size: 20 }))
+    expect(listFinanceRechargeRequests).toHaveBeenCalledWith('10001', { page: 1, size: 200 })
+    wrapper.unmount()
+  })
+
+  it('shows explicit master-data empty states without exposing the customer id', async () => {
+    vi.mocked(listFinanceAccounts).mockResolvedValue({ records: [{ ...accountFixture, customerCode: '', contactName: '', contactPhone: '', actualBalance: '0.00', frozenBalance: '0.00', availableBalance: '0.00', pendingRechargeCount: 0, lastChangedAt: '' }], total: 1, pages: 1 })
+    const wrapper = await mountAccountsView(['platform:finance:customer-account:list'])
+    expect(wrapper.text()).toContain('客户编号')
+    expect(wrapper.text()).toContain('联系人')
+    expect(wrapper.text()).toContain('联系电话')
+    expect(wrapper.text().match(/未维护/g)?.length).toBeGreaterThanOrEqual(3)
+    expect(wrapper.text()).not.toContain('客户10001')
+    wrapper.unmount()
+  })
+
+  it('formats known ledger codes, operator ids and timestamps for display', async () => {
+    vi.mocked(listFinanceAccountLedger).mockResolvedValue({ records: [{ ledgerId: '2087867025978863617', occurredAt: '2026-08-13T10:00:00', businessType: 'SETTLEMENT_ISSUED', documentType: 'BILL', documentId: '2', documentNo: 'REC-00000000000000000001', receivableChange: 10, payableChange: 0, outstandingReceivableAfter: 90, operatorName: 'operator-1000001', remark: '结算单生效' }], total: 1, pages: 1 })
+    const pinia = createPinia(); setActivePinia(pinia)
+    const auth = useAuthStore(); auth.token = 'token'; auth.permissions = ['platform:finance:customer-account:list']
+    useAccessPreviewStore().initializeAfterLogin()
+    const router = createRouter({ history: createMemoryHistory(), routes: [
+      { path: '/finance/customer-accounts', name: 'finance-customer-accounts', component: FinanceCustomerAccountsView },
+      { path: '/finance/customer-accounts/:customerId', name: 'finance-customer-account-detail', component: FinanceCustomerAccountsView },
+    ] })
+    await router.push('/finance/customer-accounts/10001'); await router.isReady()
+    const wrapper = mount(FinanceCustomerAccountsView, { global: { plugins: [pinia, ElementPlus, router] } })
+    await flushPromises()
+    expect(wrapper.text()).toContain('结算单生效')
+    expect(wrapper.text()).toContain('REC-00000000000000000001')
+    expect(wrapper.text()).toContain('名称数据缺失')
+    expect(wrapper.text()).not.toContain('operator-1000001')
+    expect(wrapper.text()).not.toContain('1000001')
+    expect(wrapper.text()).not.toContain('2026-08-13T10:00:00')
+    wrapper.unmount()
+  })
+
+  it('shows recharge and deduction only with the independent adjustment permission', async () => {
+    const readOnly = await mountAccountsView(['platform:finance:customer-account:list'])
+    expect(readOnly.findAll('button').map(button => button.text())).not.toEqual(expect.arrayContaining(['充值', '扣款']))
+    readOnly.unmount()
+
+    const writable = await mountAccountsView(['platform:finance:customer-account:list', 'platform:finance:customer-account:adjust'])
+    expect(writable.findAll('button').map(button => button.text())).toEqual(expect.arrayContaining(['充值', '扣款']))
+    writable.unmount()
+  })
+
+  it('submits a two-decimal adjustment with account version and refreshes detail data', async () => {
+    const wrapper = await mountAccountsView(['platform:finance:customer-account:list', 'platform:finance:customer-account:adjust'], '/finance/customer-accounts/10001')
+    const vm = wrapper.vm as unknown as {
+      adjustmentForm: Record<string, string>
+      openAdjustment(account: typeof accountFixture, type: 'RECHARGE' | 'DEDUCTION'): void
+      submitAdjustment(): Promise<void>
+    }
+    vm.openAdjustment(accountFixture, 'DEDUCTION')
+    Object.assign(vm.adjustmentForm, { amount: '100', occurredDate: '2026-09-05', paymentMethod: 'BANK_TRANSFER', referenceNo: 'OUT-1', remark: ' 贴牌费 ' })
+    await vm.submitAdjustment()
+
+    expect(adjustFinanceAccount).toHaveBeenCalledWith('10001', {
+      type: 'DEDUCTION', amount: '100.00', occurredDate: '2026-09-05', paymentMethod: 'BANK_TRANSFER',
+      referenceNo: 'OUT-1', remark: '贴牌费', expectedAccountVersion: 7,
+    })
+    expect(listFinanceAccounts).toHaveBeenLastCalledWith({ page: 1, size: 1, customerId: '10001' })
+    expect(listFinanceRechargeRequests).toHaveBeenCalledTimes(2)
+    expect(listFinanceAccountLedger).toHaveBeenCalledTimes(2)
+    wrapper.unmount()
+  })
+
+  it('keeps pending recharge requests first and reviews with request version', async () => {
+    vi.mocked(listFinanceRechargeRequests).mockResolvedValue({ records: [
+      { requestId: '92', requestNo: 'RC-92', amount: '20.00', paymentMethod: 'ALIPAY', voucherFileId: '82', voucherFileName: 'paid.png', status: 'APPROVED', version: 4, submittedByName: '客户A', reviewedByName: '财务A', reviewRemark: '', createdAt: '2026-09-03T10:00:00', reviewedAt: '2026-09-04T10:00:00' },
+      { requestId: '91', requestNo: 'RC-91', amount: '500.00', paymentMethod: 'WECHAT', voucherFileId: '81', voucherFileName: 'receipt.png', status: 'PENDING', version: 3, submittedByName: '客户A', reviewedByName: '', reviewRemark: '', createdAt: '2026-09-04T10:00:00', reviewedAt: '' },
+    ], total: 2, pages: 1 })
+    const wrapper = await mountAccountsView(['platform:finance:customer-account:list', 'platform:finance:recharge:review'], '/finance/customer-accounts/10001')
+    const requestText = wrapper.find('.recharge-table').text()
+    expect(requestText.indexOf('RC-91')).toBeLessThan(requestText.indexOf('RC-92'))
+    expect(wrapper.find('.recharge-table').findAll('button').map(button => button.text()).filter(text => text === '审核')).toEqual(['审核'])
+
+    const vm = wrapper.vm as unknown as { reviewForm: Record<string, string>; openReview(request: Record<string, unknown>): void; submitReview(): Promise<void> }
+    vm.openReview({ requestId: '91', requestNo: 'RC-91', amount: '500.00', paymentMethod: 'WECHAT', voucherFileId: '81', voucherFileName: 'receipt.png', status: 'PENDING', version: 3, submittedByName: '客户A', reviewedByName: '', reviewRemark: '', createdAt: '2026-09-04T10:00:00', reviewedAt: '' })
+    Object.assign(vm.reviewForm, { decision: 'REJECT', remark: ' 凭证不清晰 ' })
+    await vm.submitReview()
+    expect(reviewFinanceRechargeRequest).toHaveBeenCalledWith('91', { decision: 'REJECT', remark: '凭证不清晰', expectedVersion: 3 })
+    expect(listFinanceRechargeRequests).toHaveBeenCalledTimes(2)
+    expect(listFinanceAccountLedger).toHaveBeenCalledTimes(2)
+    wrapper.unmount()
+  })
+
+  it('creates account and ledger export tasks from the complete active filters without page parameters', async () => {
+    const permissions = ['platform:finance:customer-account:list', 'platform:finance:customer-account:export', 'platform:download:list']
+    const listWrapper = await mountAccountsView(permissions)
+    const listVm = listWrapper.vm as unknown as { filters: Record<string, unknown>; exportAccounts(): Promise<void> }
+    Object.assign(listVm.filters, { customerId: '10001', status: 'ACTIVE' })
+    await listVm.exportAccounts()
+    expect(createPlatformExportTask).toHaveBeenLastCalledWith({
+      exportType: 'FINANCE_CUSTOMER_ACCOUNT_LIST', format: 'XLSX', taskName: '客户账户',
+      parameters: { customerId: '10001', status: 'ACTIVE' },
+    })
+    expect(createPlatformExportTask).not.toHaveBeenCalledWith(expect.objectContaining({ parameters: expect.objectContaining({ page: expect.anything() }) }))
+    listWrapper.unmount()
+
+    vi.mocked(createPlatformExportTask).mockResolvedValueOnce({ id: 'exp-2', taskNo: 'EXP-2', taskName: '客户账户流水', status: 'PENDING' } as never)
+    const detailWrapper = await mountAccountsView(permissions, '/finance/customer-accounts/10001')
+    const detailVm = detailWrapper.vm as unknown as { ledgerFilters: Record<string, unknown>; exportLedger(): Promise<void> }
+    Object.assign(detailVm.ledgerFilters, { businessType: 'RECEIPT', occurredRange: ['2026-08-01', '2026-08-31'] })
+    await detailVm.exportLedger()
+    expect(createPlatformExportTask).toHaveBeenLastCalledWith({
+      exportType: 'FINANCE_CUSTOMER_ACCOUNT_LEDGER', format: 'XLSX', taskName: '客户账户流水',
+      parameters: { customerId: '10001', businessType: 'RECEIPT', startDate: '2026-08-01', endDate: '2026-08-31' },
+    })
+    expect(showExportTaskCreatedDialog).toHaveBeenLastCalledWith({ taskName: '客户账户流水', taskNo: 'EXP-2', dense: true })
+    detailWrapper.unmount()
+  })
+
+  it('loads voucher images through the authenticated blob endpoint', async () => {
+    const wrapper = await mountAccountsView(['platform:finance:customer-account:list'], '/finance/customer-accounts/10001')
+    const voucherButton = wrapper.findAll('.recharge-table button').find(button => button.text() === 'receipt.png')
+    expect(voucherButton).toBeTruthy()
+    await voucherButton!.trigger('click')
+    await flushPromises()
+    expect(downloadFinanceRechargeVoucher).toHaveBeenCalledWith('91')
+    expect(URL.createObjectURL).toHaveBeenCalled()
+    expect(wrapper.find('.voucher-preview__image').attributes('src')).toBe('blob:finance-voucher')
+    wrapper.unmount()
+    expect(URL.revokeObjectURL).toHaveBeenCalledWith('blob:finance-voucher')
+  })
+
+  it('requires both the finance export permission and download-center access', async () => {
+    const wrapper = await mountAccountsView(['platform:finance:customer-account:list', 'platform:finance:customer-account:export'])
+    expect(wrapper.findAll('button').map((button) => button.text())).not.toContain('导出Excel')
+    expect(createPlatformExportTask).not.toHaveBeenCalled()
+    wrapper.unmount()
+  })
+
+  it('opens the download center after confirmation and reports task creation failures', async () => {
+    const permissions = ['platform:finance:customer-account:list', 'platform:finance:customer-account:export', 'platform:download:list']
+    vi.mocked(showExportTaskCreatedDialog).mockResolvedValueOnce(true)
+    const wrapper = await mountAccountsView(permissions)
+    await (wrapper.vm as unknown as { exportAccounts(): Promise<void> }).exportAccounts()
+    expect(wrapper.router.currentRoute.value.name).toBe('download-center')
+    wrapper.unmount()
+
+    const errorSpy = vi.spyOn(ElMessage, 'error').mockImplementation(() => undefined as never)
+    vi.mocked(createPlatformExportTask).mockRejectedValueOnce(new Error('导出服务不可用'))
+    const failedWrapper = await mountAccountsView(permissions)
+    await (failedWrapper.vm as unknown as { exportAccounts(): Promise<void> }).exportAccounts()
+    expect(errorSpy).toHaveBeenCalledWith('客户账户导出任务创建失败')
+    expect(showExportTaskCreatedDialog).toHaveBeenCalledTimes(1)
+    failedWrapper.unmount()
+    errorSpy.mockRestore()
+  })
+})
+
+afterAll(() => vi.unstubAllGlobals())
diff --git a/src/modules/finance/pages/FinanceCustomerAccountsView.vue b/src/modules/finance/pages/FinanceCustomerAccountsView.vue
new file mode 100644
index 00000000..f161c4b5
--- /dev/null
+++ b/src/modules/finance/pages/FinanceCustomerAccountsView.vue
@@ -0,0 +1,705 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import '../financeDensity.css'
+import { computed, onBeforeUnmount, onMounted, reactive, ref } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { ArrowLeft, CreditCard, Download, MinusCircle, MoreHorizontal, PlusCircle, Save } from '@lucide/vue'
+import { ElMessage } from 'element-plus'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { createPlatformExportTask } from '@/modules/downloads'
+import { listPlatformTenants, type PlatformTenantResource } from '@/modules/iam'
+import { getApiErrorDetails, getApiErrorMessage, type ApiErrorDetails } from '@/shared/api/http'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import DetailPageLayout from '@/shared/components/DetailPageLayout.vue'
+import FormSection from '@/shared/components/FormSection.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import { showExportTaskCreatedDialog } from '@/shared/components/exportTaskCreatedDialog'
+import { adjustFinanceAccount, downloadFinanceRechargeVoucher, getFinanceCustomerTerms, listFinanceAccountLedger, listFinanceAccounts, listFinanceRechargeRequests, reviewFinanceRechargeRequest, updateFinanceCreditLimit, updateFinanceCustomerTerms } from '../api/finance'
+import { financeBusinessTypeLabel } from '../status'
+import type { FinanceAccountSummary, FinanceCustomerTerms, FinanceLedgerEntry, FinanceRechargeRequest } from '../types'
+
+const access = useAccessPreviewStore()
+const route = useRoute()
+const router = useRouter()
+const filters = ref<QueryModel>({ customerId: '', status: '' })
+const customers = ref<PlatformTenantResource[]>([])
+const customersLoading = ref(false)
+const customersError = ref<ApiErrorDetails | null>(null)
+const rows = ref<FinanceAccountSummary[]>([])
+const loading = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const page = ref(1)
+const pageSize = ref(20)
+const total = ref(0)
+const detailOpen = ref(false)
+const editing = ref(false)
+const saving = ref(false)
+const selected = ref<FinanceAccountSummary | null>(null)
+const ledger = ref<FinanceLedgerEntry[]>([])
+const ledgerLoading = ref(false)
+const ledgerError = ref<ApiErrorDetails | null>(null)
+const selectedTerms = ref<FinanceCustomerTerms | null>(null)
+const creditDays = ref(30)
+const ledgerFilters = ref<QueryModel>({ businessType: '', occurredRange: [] })
+const ledgerPage = ref(1)
+const ledgerPageSize = ref(20)
+const ledgerTotal = ref(0)
+const rechargeRequests = ref<FinanceRechargeRequest[]>([])
+const rechargeLoading = ref(false)
+const rechargeError = ref<ApiErrorDetails | null>(null)
+const accountExportBusy = ref(false)
+const ledgerExportBusy = ref(false)
+const adjustmentOpen = ref(false)
+const adjustmentSaving = ref(false)
+const adjustmentAccount = ref<FinanceAccountSummary | null>(null)
+const adjustmentForm = reactive({ type: 'RECHARGE' as 'RECHARGE' | 'DEDUCTION', amount: '', occurredDate: '', paymentMethod: 'BANK_TRANSFER', referenceNo: '', remark: '' })
+const creditLimitOpen = ref(false)
+const creditLimitSaving = ref(false)
+const creditLimitForm = reactive({ amount: '', expiresOn: '', remark: '' })
+const reviewOpen = ref(false)
+const reviewSaving = ref(false)
+const reviewRequest = ref<FinanceRechargeRequest | null>(null)
+const reviewForm = reactive({ decision: 'APPROVE' as 'APPROVE' | 'REJECT', remark: '' })
+const voucherPreviewOpen = ref(false)
+const voucherPreviewLoading = ref(false)
+const voucherPreviewUrl = ref('')
+const voucherPreviewName = ref('付款凭证')
+
+const canView = computed(() => access.can('platform:finance:customer-account:list'))
+const canListCustomers = computed(() => canView.value || access.can('platform:customer:list'))
+const canViewTerms = computed(() => access.can('platform:finance:customer-terms:view'))
+const canUpdateTerms = computed(() => canViewTerms.value && access.can('platform:finance:customer-terms:update'))
+const canExport = computed(() => access.can('platform:finance:customer-account:export') && access.can('platform:download:list'))
+const canAdjust = computed(() => access.can('platform:finance:customer-account:adjust'))
+const canReviewRecharge = computed(() => access.can('platform:finance:recharge:review'))
+const stateError = computed(() => customersError.value || loadError.value)
+const queryFields = computed<QueryField[]>(() => [
+  { key: 'customerId', type: 'select', label: '客户名称', width: 260, placeholder: '全部客户', props: { 'aria-label': '客户名称', filterable: true, clearable: true, loading: customersLoading.value }, options: customers.value.filter((item) => item.status === 'ACTIVE').map((item) => ({ label: item.tenantName, value: String(item.id) })) },
+  { key: 'status', type: 'select', label: '状态', width: 150, placeholder: '全部状态', options: [{ label: '正常', value: 'ACTIVE' }, { label: '停用', value: 'DISABLED' }] },
+])
+const columns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 290, fixed: 'left', slotName: 'actions' },
+  { key: 'customerName', label: '客户', minWidth: 180, slotName: 'customerName' },
+  { key: 'customerCode', label: '客户编号', width: 150, slotName: 'customerCode' },
+  { key: 'contactName', label: '联系人', width: 130, slotName: 'contactName' },
+  { key: 'contactPhone', label: '联系电话', width: 150, slotName: 'contactPhone' },
+  { key: 'actualBalance', label: '实际余额(CNY)', width: 155, slotName: 'actualBalance' },
+  { key: 'frozenBalance', label: '冻结金额(CNY)', width: 150, slotName: 'frozenBalance' },
+  { key: 'availableBalance', label: '总可用余额(CNY)', width: 155, slotName: 'availableBalance' },
+  { key: 'creditLimit', label: '授信额度(CNY)', width: 155, slotName: 'creditLimit' },
+  { key: 'creditExpiresOn', label: '授信有效期', width: 140, slotName: 'creditExpiresOn' },
+  { key: 'creditUsed', label: '已用授信(CNY)', width: 150, slotName: 'creditUsed' },
+  { key: 'pendingRechargeCount', label: '待审核充值', width: 120, slotName: 'pendingRechargeCount' },
+  { key: 'status', label: '客户状态', width: 110, slotName: 'status' },
+  { key: 'lastChangedAt', label: '最近变动', width: 170, slotName: 'lastChangedAt' },
+]
+const ledgerQueryFields: QueryField[] = [
+  { key: 'businessType', type: 'select', label: '流水类型', width: 180, placeholder: '全部类型', options: [
+    { label: '生成对账单', value: 'RECONCILIATION_CREATED' }, { label: '结算单生效', value: 'SETTLEMENT_ISSUED' },
+    { label: '收款', value: 'RECEIPT' },
+    { label: '供应商线下直付', value: 'SUPPLIER_DIRECT_PAID' },
+    { label: '供应商账期付款', value: 'SUPPLIER_ON_ACCOUNT_PAYMENT' },
+    { label: '账务调整', value: 'ADJUSTMENT' }, { label: '作废', value: 'VOID' },
+  ] },
+  { key: 'occurredRange', type: 'daterange', label: '发生日期', width: 280 },
+]
+const ledgerColumns: DataTableColumn[] = [
+  { key: 'ledgerId', label: '流水号', width: 180, slotName: 'ledgerId' }, { key: 'occurredAt', label: '发生时间', width: 170, slotName: 'occurredAt' }, { key: 'businessType', label: '业务类型', width: 140, slotName: 'businessType' },
+  { key: 'documentNo', label: '关联单据', width: 220, slotName: 'documentNo' }, { key: 'amount', label: '余额变动(CNY)', width: 145, slotName: 'amount' },
+  { key: 'paymentMethod', label: '支付方式', width: 130, slotName: 'ledgerPaymentMethod' },
+  { key: 'actualBalanceAfter', label: '变动后实际余额', width: 160, slotName: 'actualBalanceAfter' },
+  { key: 'frozenBalanceAfter', label: '变动后冻结金额', width: 160, slotName: 'frozenBalanceAfter' },
+  { key: 'availableBalanceAfter', label: '变动后可用余额', width: 160, slotName: 'availableBalanceAfter' },
+  { key: 'creditUsedAfter', label: '变动后已用授信', width: 160, slotName: 'creditUsedAfter' },
+  { key: 'operatorName', label: '操作人', width: 140, slotName: 'operatorName' }, { key: 'remark', label: '备注', minWidth: 180 },
+]
+const rechargeColumns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 150, fixed: 'left', slotName: 'actions' },
+  { key: 'requestNo', label: '申请单号', minWidth: 190 }, { key: 'createdAt', label: '提交时间', width: 170, slotName: 'createdAt' },
+  { key: 'amount', label: '充值金额(CNY)', width: 150, slotName: 'amount' }, { key: 'paymentMethod', label: '付款方式', width: 130, slotName: 'paymentMethod' },
+  { key: 'voucherFileName', label: '付款凭证', minWidth: 170, slotName: 'voucherFileName' }, { key: 'submittedByName', label: '提交人', width: 130 },
+  { key: 'status', label: '状态', width: 110, slotName: 'status' }, { key: 'reviewedByName', label: '审核人', width: 130 },
+  { key: 'reviewRemark', label: '审核备注', minWidth: 180 }, { key: 'reviewedAt', label: '审核时间', width: 170, slotName: 'reviewedAt' },
+]
+const sortedRechargeRequests = computed(() => [...rechargeRequests.value].sort((left, right) => Number(right.status === 'PENDING') - Number(left.status === 'PENDING')))
+
+async function load(model: QueryModel = filters.value) {
+  Object.assign(filters.value, model)
+  if (!canView.value) return
+  loading.value = true
+  loadError.value = null
+  try {
+    const result = await listFinanceAccounts({ page: page.value, size: pageSize.value, customerId: String(filters.value.customerId || '').trim() || undefined, status: String(filters.value.status || '') })
+    rows.value = result.records
+    total.value = result.total
+  } catch (error) { loadError.value = getApiErrorDetails(error, '客户账户加载失败，请重试') }
+  finally { loading.value = false }
+}
+async function loadCustomers() {
+  customersLoading.value = true; customersError.value = null
+  try {
+    const records: PlatformTenantResource[] = []; let currentPage = 1; let pages = 1
+    do { const result = await listPlatformTenants({ page: currentPage, size: 200, status: 'ACTIVE' }); records.push(...result.records); pages = Math.max(1, result.pages); currentPage += 1 } while (currentPage <= pages)
+    customers.value = records
+  } catch (error) { customersError.value = getApiErrorDetails(error, '客户列表加载失败') }
+  finally { customersLoading.value = false }
+}
+function search(model: QueryModel) { page.value = 1; void load(model) }
+async function openAccount(row: Record<string, unknown>, edit: boolean) {
+  selected.value = row as unknown as FinanceAccountSummary
+  editing.value = edit
+  if (!edit) {
+    await router.push({ name: 'finance-customer-account-detail', params: { customerId: selected.value.customerId } })
+    return
+  }
+  detailOpen.value = true
+  ledger.value = []
+  ledgerError.value = null
+  selectedTerms.value = null
+  if (edit) {
+    if (!canViewTerms.value) return
+    try { selectedTerms.value = await getFinanceCustomerTerms(selected.value.customerId); creditDays.value = selectedTerms.value.creditDays }
+    catch (error) { ledgerError.value = getApiErrorDetails(error, '客户账期加载失败，请重试') }
+    return
+  }
+  await loadLedger()
+}
+async function loadLedger(model: QueryModel = ledgerFilters.value) {
+  if (!selected.value) return
+  Object.assign(ledgerFilters.value, model)
+  ledgerLoading.value = true; ledgerError.value = null
+  const range = Array.isArray(ledgerFilters.value.occurredRange) ? ledgerFilters.value.occurredRange.map(String) : []
+  try {
+    const result = await listFinanceAccountLedger(selected.value.customerId, { page: ledgerPage.value, size: ledgerPageSize.value, businessType: String(ledgerFilters.value.businessType || ''), startDate: range[0], endDate: range[1] })
+    ledger.value = result.records
+    ledgerTotal.value = result.total
+  } catch (error) { ledgerError.value = getApiErrorDetails(error, '客户账户流水加载失败，请重试') }
+  finally { ledgerLoading.value = false }
+}
+async function loadRechargeRequests() {
+  if (!selected.value) return
+  rechargeLoading.value = true; rechargeError.value = null
+  try { rechargeRequests.value = (await listFinanceRechargeRequests(selected.value.customerId, { page: 1, size: 200 })).records }
+  catch (error) { rechargeRequests.value = []; rechargeError.value = getApiErrorDetails(error, '充值申请加载失败，请重试') }
+  finally { rechargeLoading.value = false }
+}
+async function refreshSelectedAccount() {
+  if (!selected.value) return
+  const customerId = selected.value.customerId
+  const result = await listFinanceAccounts({ page: 1, size: 1, customerId })
+  selected.value = result.records.find(row => row.customerId === customerId) || null
+}
+async function refreshWalletDetail() {
+  await refreshSelectedAccount()
+  if (!selected.value) return
+  await Promise.all([loadRechargeRequests(), loadLedger()])
+}
+async function retryDrawer() { if (selected.value) await openAccount(selected.value as unknown as Record<string, unknown>, editing.value) }
+async function saveTerms() {
+  if (!selected.value || !Number.isInteger(creditDays.value) || creditDays.value < 0 || creditDays.value > 3650) { ElMessage.warning('账期必须是 0 到 3650 的整数天'); return }
+  saving.value = true
+  ledgerError.value = null
+  try { selectedTerms.value = await updateFinanceCustomerTerms(selected.value.customerId, { customerName: selected.value.customerName, creditDays: creditDays.value }); ElMessage.success('客户账期已保存') }
+  catch (error) { ledgerError.value = getApiErrorDetails(error, '客户账期保存失败，请重试'); ElMessage.error(ledgerError.value.message) }
+  finally { saving.value = false }
+}
+function money(value: unknown) { const amount = String(value ?? '').trim(); return amount ? `¥${amount}` : '—' }
+function amountInput(value: string) {
+  const amount = Number(value)
+  return Number.isFinite(amount) && amount > 0 ? amount.toFixed(2) : null
+}
+function today() {
+  const date = new Date()
+  const month = String(date.getMonth() + 1).padStart(2, '0')
+  const day = String(date.getDate()).padStart(2, '0')
+  return `${date.getFullYear()}-${month}-${day}`
+}
+function disableCreditExpiry(date: Date) {
+  const boundary = new Date()
+  boundary.setHours(0, 0, 0, 0)
+  return date.getTime() <= boundary.getTime()
+}
+function creditExpiryLabel(account: FinanceAccountSummary) {
+  if (!account.creditExpiresOn) return '未设置'
+  return account.creditActive ? `${account.creditExpiresOn} 到期` : `${account.creditExpiresOn} 已到期`
+}
+function paymentMethodLabel(value: unknown) {
+  return ({ BANK_TRANSFER: '银行转账', WECHAT: '微信', ALIPAY: '支付宝', CASH: '现金', OTHER: '其他' } as Record<string, string>)[String(value)] || '其他'
+}
+function walletBusinessType(value: unknown) {
+  return ({ RECHARGE: '充值', DEDUCTION: '扣款', FREEZE: '冻结', UNFREEZE: '解冻', CONSUMPTION: '消费结算', CREDIT_LIMIT: '授信调整' } as Record<string, string>)[String(value)] || ledgerBusinessType(value)
+}
+function openAdjustment(account: FinanceAccountSummary, type: 'RECHARGE' | 'DEDUCTION') {
+  adjustmentAccount.value = account
+  Object.assign(adjustmentForm, { type, amount: '', occurredDate: today(), paymentMethod: 'BANK_TRANSFER', referenceNo: '', remark: '' })
+  adjustmentOpen.value = true
+}
+async function submitAdjustment() {
+  if (!adjustmentAccount.value) return
+  const amount = amountInput(adjustmentForm.amount)
+  if (!amount || !adjustmentForm.occurredDate || !adjustmentForm.paymentMethod) { ElMessage.warning('请填写有效金额、发生日期和付款方式'); return }
+  adjustmentSaving.value = true
+  try {
+    await adjustFinanceAccount(adjustmentAccount.value.customerId, {
+      type: adjustmentForm.type, amount, occurredDate: adjustmentForm.occurredDate, paymentMethod: adjustmentForm.paymentMethod,
+      referenceNo: adjustmentForm.referenceNo.trim() || undefined, remark: adjustmentForm.remark.trim() || undefined,
+      expectedAccountVersion: adjustmentAccount.value.accountVersion,
+    })
+    adjustmentOpen.value = false
+    ElMessage.success(adjustmentForm.type === 'RECHARGE' ? '手工充值已入账' : '手工扣款已入账')
+    if (selected.value?.customerId === adjustmentAccount.value.customerId) await refreshWalletDetail()
+    else await load()
+  } catch (error) { ElMessage.error(getApiErrorMessage(error, adjustmentForm.type === 'RECHARGE' ? '手工充值失败' : '手工扣款失败')) }
+  finally { adjustmentSaving.value = false }
+}
+function openCreditLimit(account: FinanceAccountSummary) {
+  adjustmentAccount.value = account
+  Object.assign(creditLimitForm, {
+    amount: Number(account.creditLimit || 0).toFixed(2),
+    expiresOn: account.creditActive ? account.creditExpiresOn || '' : '',
+    remark: '',
+  })
+  creditLimitOpen.value = true
+}
+function handleAccountMore(command: string, account: FinanceAccountSummary) {
+  if (command === 'credit') openCreditLimit(account)
+  if (command === 'terms') void openAccount(account as unknown as Record<string, unknown>, true)
+}
+async function submitCreditLimit() {
+  if (!adjustmentAccount.value) return
+  const raw = creditLimitForm.amount.trim()
+  const amount = Number(raw)
+  if (!Number.isFinite(amount) || amount < 0 || !/^\d+(?:\.\d{1,2})?$/.test(raw)) {
+    ElMessage.warning('授信额度必须是大于或等于 0 且最多两位小数的金额')
+    return
+  }
+  if (!creditLimitForm.expiresOn || creditLimitForm.expiresOn <= today()) {
+    ElMessage.warning('授信到期日必须晚于今天')
+    return
+  }
+  creditLimitSaving.value = true
+  try {
+    await updateFinanceCreditLimit(adjustmentAccount.value.customerId, {
+      creditLimit: amount.toFixed(2), creditExpiresOn: creditLimitForm.expiresOn,
+      remark: creditLimitForm.remark.trim() || undefined,
+      expectedAccountVersion: adjustmentAccount.value.accountVersion,
+    })
+    creditLimitOpen.value = false
+    ElMessage.success('授信额度已更新')
+    if (selected.value?.customerId === adjustmentAccount.value.customerId) await refreshWalletDetail()
+    else await load()
+  } catch (error) { ElMessage.error(getApiErrorMessage(error, '授信额度更新失败')) }
+  finally { creditLimitSaving.value = false }
+}
+function openReview(request: FinanceRechargeRequest) {
+  reviewRequest.value = request
+  Object.assign(reviewForm, { decision: 'APPROVE', remark: '' })
+  reviewOpen.value = true
+}
+async function submitReview() {
+  if (!reviewRequest.value) return
+  reviewSaving.value = true
+  try {
+    await reviewFinanceRechargeRequest(reviewRequest.value.requestId, {
+      decision: reviewForm.decision, remark: reviewForm.remark.trim() || undefined, expectedVersion: reviewRequest.value.version,
+    })
+    reviewOpen.value = false
+    ElMessage.success(reviewForm.decision === 'APPROVE' ? '充值申请已通过并入账' : '充值申请已驳回')
+    await refreshWalletDetail()
+  } catch (error) { ElMessage.error(getApiErrorMessage(error, '充值申请审核失败')) }
+  finally { reviewSaving.value = false }
+}
+function clearVoucherPreview() {
+  if (voucherPreviewUrl.value) URL.revokeObjectURL(voucherPreviewUrl.value)
+  voucherPreviewUrl.value = ''
+}
+async function previewVoucher(request: FinanceRechargeRequest) {
+  clearVoucherPreview()
+  voucherPreviewName.value = request.voucherFileName || '付款凭证'
+  voucherPreviewOpen.value = true
+  voucherPreviewLoading.value = true
+  try {
+    const blob = await downloadFinanceRechargeVoucher(request.requestId)
+    voucherPreviewUrl.value = URL.createObjectURL(blob)
+  } catch (error) {
+    voucherPreviewOpen.value = false
+    ElMessage.error(getApiErrorMessage(error, '付款凭证加载失败'))
+  } finally { voucherPreviewLoading.value = false }
+}
+function customerName(customerId: string, snapshot?: string) {
+  const masterName = customers.value.find((item) => String(item.id) === String(customerId))?.tenantName?.trim()
+  const candidate = String(snapshot || '').trim()
+  const placeholder = [String(customerId), `客户 ${customerId}`, `客户${customerId}`].includes(candidate)
+  return masterName || (candidate && !placeholder ? candidate : '客户名称暂不可用')
+}
+function ledgerBusinessType(value: unknown) {
+  const code = String(value || '').trim().toUpperCase()
+  const known: Record<string, string> = { REC: '收款', RECONCILIATION: '对账单', FEE_SOURCE: '费用来源' }
+  return known[code] || financeBusinessTypeLabel(code)
+}
+function displayOperator(value: unknown) {
+  const operator = String(value || '').trim()
+  if (!operator) return '名称数据缺失'
+  return /^(?:operator-)?\d+$/i.test(operator) ? '名称数据缺失' : operator
+}
+function formatDateTime(value: unknown) {
+  const raw = String(value || '').trim()
+  if (!raw) return '时间数据缺失'
+  const date = new Date(raw)
+  return Number.isNaN(date.getTime()) ? '时间数据缺失' : date.toLocaleString('zh-CN', { hour12: false })
+}
+function formatLastChangedAt(value: unknown) { return String(value || '').trim() ? formatDateTime(value) : '暂无变动' }
+function customerField(value: unknown) { return String(value || '').trim() || '未维护' }
+function displayDocumentNo(value: unknown) { return String(value || '').trim() || '关联单据缺失' }
+function displayLedgerId(value: unknown) { return String(value || '').trim() || '流水号缺失' }
+async function finishExport(task: Awaited<ReturnType<typeof createPlatformExportTask>>) {
+  const openDownloadCenter = await showExportTaskCreatedDialog({ taskName: task.taskName, taskNo: task.taskNo, dense: true })
+  if (openDownloadCenter) await router.push({ name: 'download-center' })
+}
+async function exportAccounts() {
+  const customerId = String(filters.value.customerId || '').trim()
+  const status = String(filters.value.status || '').trim()
+  accountExportBusy.value = true
+  try {
+    const task = await createPlatformExportTask({
+      exportType: 'FINANCE_CUSTOMER_ACCOUNT_LIST', format: 'XLSX', taskName: '客户账户',
+      parameters: {
+        ...(customerId ? { customerId } : {}),
+        ...(status ? { status } : {}),
+      },
+    })
+    await finishExport(task)
+  } catch (error) { ElMessage.error(getApiErrorMessage(error, '客户账户导出任务创建失败')) }
+  finally { accountExportBusy.value = false }
+}
+async function exportLedger() {
+  if (!selected.value) return
+  const range = Array.isArray(ledgerFilters.value.occurredRange) ? ledgerFilters.value.occurredRange.map(String) : []
+  const businessType = String(ledgerFilters.value.businessType || '').trim()
+  ledgerExportBusy.value = true
+  try {
+    const task = await createPlatformExportTask({
+      exportType: 'FINANCE_CUSTOMER_ACCOUNT_LEDGER', format: 'XLSX', taskName: '客户账户流水',
+      parameters: {
+        customerId: selected.value.customerId,
+        ...(businessType ? { businessType } : {}),
+        ...(range[0] ? { startDate: range[0] } : {}),
+        ...(range[1] ? { endDate: range[1] } : {}),
+      },
+    })
+    await finishExport(task)
+  } catch (error) { ElMessage.error(getApiErrorMessage(error, '客户账户流水导出任务创建失败')) }
+  finally { ledgerExportBusy.value = false }
+}
+async function closeDetail() {
+  detailOpen.value = false; selected.value = null; editing.value = false; ledger.value = []
+  if (route.name === 'finance-customer-account-detail') await router.push({ name: 'finance-customer-accounts' })
+}
+async function restoreAccountDetail(customerId: string) {
+  detailOpen.value = true; editing.value = false; ledgerError.value = null
+  try {
+    selected.value = (await listFinanceAccounts({ page: 1, size: 1, customerId })).records.find(row => row.customerId === customerId) || null
+    if (!selected.value) { ledgerError.value = { message: '未找到该客户账户，可能已停用或无权访问' }; return }
+    await Promise.all([loadLedger(), loadRechargeRequests()])
+  } catch (error) { ledgerError.value = getApiErrorDetails(error, '客户账户详情加载失败，请重试') }
+}
+onMounted(() => {
+  const customerId = String(route.params.customerId || '')
+  if (route.name === 'finance-customer-account-detail' && customerId) { if (canListCustomers.value) void loadCustomers(); void restoreAccountDetail(customerId) }
+  else { if (canListCustomers.value) void loadCustomers(); void load() }
+})
+onBeforeUnmount(clearVoucherPreview)
+</script>
+
+<template>
+  <AdminPage as="div" class="finance-account-page admin-density" spacing="normal">
+    <el-result v-if="!canView" icon="warning" title="无权访问客户账户" sub-title="请联系管理员开通客户账户查看权限" />
+    <ListPageLayout v-else-if="!detailOpen" aria-label="客户账户">
+      <template #toolbar><QueryToolbar v-model="filters" class="surface-panel" ariaLabel="客户账户筛选" :fields="queryFields" preference-key="finance-customer-accounts-query" @search="search" /></template>
+      <template v-if="stateError" #state><LoadErrorState title="客户账户加载失败" :message="stateError.message" :loading="loading || customersLoading" @retry="customersError ? loadCustomers() : load()"><template #details><ApiErrorMeta :details="stateError" /></template></LoadErrorState></template>
+      <section v-if="!stateError" class="surface-panel table-panel">
+        <DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :loading="loading" :total="total" preference-key="finance-customer-accounts-table" aria-label="客户账户列表" row-key="customerId" empty-text="暂无客户账户" @update:page="load()" @update:page-size="page = 1; load()">
+          <template #toolbar-actions><el-button v-if="canExport" :loading="accountExportBusy" :disabled="loading || accountExportBusy" @click="exportAccounts"><Download :size="16" />导出Excel</el-button></template>
+          <template #actions="{ row }"><div class="row-actions density-actions"><el-button data-tone="neutral" class="density-action" size="small" @click="openAccount(row, false)">详情</el-button><el-button data-tone="neutral" class="density-action" v-if="canAdjust" size="small" @click="openAdjustment(row as FinanceAccountSummary, 'RECHARGE')">充值</el-button><el-button data-tone="danger" class="density-action" v-if="canAdjust" size="small" @click="openAdjustment(row as FinanceAccountSummary, 'DEDUCTION')">扣款</el-button><el-button class="density-action" data-tone="neutral" v-if="!canAdjust && canUpdateTerms" size="small" @click="handleAccountMore('terms', row as FinanceAccountSummary)">账期</el-button><el-dropdown v-if="canAdjust" trigger="click" @command="handleAccountMore(String($event), row as FinanceAccountSummary)"><el-button data-tone="neutral" class="density-action" size="small" aria-label="更多客户账户操作" title="更多客户账户操作"><MoreHorizontal aria-hidden="true" :size="15" /></el-button><template #dropdown><el-dropdown-menu><el-dropdown-item v-if="canAdjust" command="credit">授信</el-dropdown-item><el-dropdown-item v-if="canUpdateTerms" command="terms" :divided="canAdjust">账期</el-dropdown-item></el-dropdown-menu></template></el-dropdown></div></template>
+          <template #customerName="{ row }">{{ customerName(row.customerId, row.customerName) }}</template>
+          <template #customerCode="{ row }">{{ customerField(row.customerCode) }}</template><template #contactName="{ row }">{{ customerField(row.contactName) }}</template><template #contactPhone="{ row }">{{ customerField(row.contactPhone) }}</template>
+          <template #lastChangedAt="{ row }">{{ formatLastChangedAt(row.lastChangedAt) }}</template>
+          <template #actualBalance="{ row }"><strong class="balance-value is-actual" :class="{ 'is-negative': Number(row.actualBalance) < 0 }">{{ money(row.actualBalance) }}</strong></template><template #frozenBalance="{ row }"><span class="balance-value is-frozen">{{ money(row.frozenBalance) }}</span></template><template #availableBalance="{ row }"><strong class="balance-value">{{ money(row.availableBalance) }}</strong></template><template #creditLimit="{ row }">{{ money(row.creditLimit) }}</template><template #creditExpiresOn="{ row }"><span :class="{ 'credit-expired': row.creditExpiresOn && !row.creditActive }">{{ creditExpiryLabel(row as FinanceAccountSummary) }}</span></template><template #creditUsed="{ row }"><span class="balance-value is-frozen">{{ money(row.creditUsed) }}</span></template>
+          <template #pendingRechargeCount="{ row }"><el-tag v-if="row.pendingRechargeCount" type="warning">{{ row.pendingRechargeCount }} 笔</el-tag><span v-else>—</span></template>
+          <template #status="{ row }"><el-tag :type="row.status === 'ACTIVE' ? 'success' : 'info'">{{ row.status === 'ACTIVE' ? '正常' : '停用' }}</el-tag></template>
+          <template #pagination-left><span>共 {{ total }} 个客户账户</span></template>
+        </DataTable>
+      </section>
+    </ListPageLayout>
+    <AdminPage v-else as="div" class="finance-account-detail admin-density" spacing="normal">
+      <section class="surface-panel finance-account-detail__surface">
+      <DetailPageLayout class="finance-account-detail__layout finance-density-detail" :aria-label="editing ? '维护客户账期' : '客户账户详情'">
+        <template #header><div class="density-detail-header"><div class="density-detail-heading"><el-button link class="density-back" @click="closeDetail"><ArrowLeft :size="16" />返回客户账户</el-button><h1 class="density-detail-title">{{ selected ? customerName(selected.customerId, selected.customerName) : '客户账户' }}</h1><span class="finance-detail-context">{{ editing ? '维护客户账期' : 'CNY 资金账户' }}</span></div><div v-if="selected && !editing" class="finance-detail-actions"><el-button v-if="canAdjust" type="primary" plain @click="openAdjustment(selected, 'RECHARGE')"><PlusCircle :size="16" />手工充值</el-button><el-button v-if="canAdjust" type="danger" plain @click="openAdjustment(selected, 'DEDUCTION')"><MinusCircle :size="16" />手工扣款</el-button><el-button v-if="canAdjust" plain @click="openCreditLimit(selected)"><CreditCard :size="16" />设置授信</el-button></div></div></template>
+        <template v-if="selected && !ledgerError" #summary><dl class="density-detail-overview account-metrics" aria-label="客户资金账户余额"><div class="account-metric is-actual"><dt>实际余额</dt><dd :class="{ 'is-negative': Number(selected.actualBalance) < 0 }">{{ money(selected.actualBalance) }} <small>CNY</small></dd></div><div class="account-metric is-frozen"><dt>冻结金额</dt><dd>{{ money(selected.frozenBalance) }} <small>CNY</small></dd></div><div class="account-metric is-available"><dt>总可用余额</dt><dd>{{ money(selected.availableBalance) }} <small>CNY</small></dd></div><div class="account-metric"><dt>授信额度</dt><dd>{{ money(selected.creditLimit) }} <small>{{ creditExpiryLabel(selected) }}</small></dd></div><div class="account-metric is-frozen"><dt>已用授信</dt><dd>{{ money(selected.creditUsed) }} <small>CNY</small></dd></div><div class="account-metric"><dt>可用授信</dt><dd>{{ money(selected.availableCredit) }} <small>CNY</small></dd></div></dl></template>
+        <LoadErrorState v-if="ledgerError" :title="editing ? '客户账期加载失败' : '账户流水加载失败'" :message="ledgerError.message" :loading="ledgerLoading" @retry="retryDrawer"><template #details><ApiErrorMeta :details="ledgerError" /></template></LoadErrorState>
+        <template v-else-if="selected">
+          <FormSection class="customer-profile-section density-form-section" title="客户信息" :bordered="false"><el-descriptions border class="density-descriptions" :column="3"><el-descriptions-item label="客户编号">{{ customerField(selected.customerCode) }}</el-descriptions-item><el-descriptions-item label="联系人">{{ customerField(selected.contactName) }}</el-descriptions-item><el-descriptions-item label="联系电话">{{ customerField(selected.contactPhone) }}</el-descriptions-item></el-descriptions></FormSection>
+          <FormSection v-if="!editing" class="recharge-section density-form-section" title="充值申请" :bordered="false">
+            <LoadErrorState v-if="rechargeError" title="充值申请加载失败" :message="rechargeError.message" :loading="rechargeLoading" @retry="loadRechargeRequests" />
+            <div v-else class="detail-table-scroll"><DataTable class="recharge-table" :data="sortedRechargeRequests" :columns="rechargeColumns" :loading="rechargeLoading" row-key="requestId" empty-text="暂无充值申请" column-settings-mode="hide">
+              <template #actions="{ row }"><div class="density-actions"><el-button data-tone="warning" class="density-action" v-if="canReviewRecharge && row.status === 'PENDING'" size="small" @click="openReview(row as FinanceRechargeRequest)">审核</el-button></div></template>
+              <template #createdAt="{ row }">{{ formatDateTime(row.createdAt) }}</template><template #reviewedAt="{ row }">{{ row.reviewedAt ? formatDateTime(row.reviewedAt) : '—' }}</template>
+              <template #amount="{ row }"><strong class="balance-value is-actual">{{ money(row.amount) }}</strong></template><template #paymentMethod="{ row }">{{ paymentMethodLabel(row.paymentMethod) }}</template>
+              <template #voucherFileName="{ row }"><el-button v-if="row.voucherFileId" link type="primary" @click="previewVoucher(row as FinanceRechargeRequest)">{{ row.voucherFileName || '预览付款凭证' }}</el-button><span v-else>—</span></template>
+              <template #status="{ row }"><el-tag :type="row.status === 'PENDING' ? 'warning' : row.status === 'APPROVED' ? 'success' : 'danger'">{{ row.status === 'PENDING' ? '待审核' : row.status === 'APPROVED' ? '已通过' : '已驳回' }}</el-tag></template>
+            </DataTable></div>
+          </FormSection>
+          <FormSection v-if="!editing" class="ledger-section density-form-section" title="账户流水" :bordered="false">
+            <QueryToolbar v-model="ledgerFilters" class="ledger-query" :fields="ledgerQueryFields" ariaLabel="账户流水筛选" preference-key="finance-account-ledger-query" @search="ledgerPage = 1; void loadLedger($event)" />
+            <div class="detail-table-scroll"><DataTable v-model:page="ledgerPage" v-model:page-size="ledgerPageSize" class="ledger-table" :data="ledger" :columns="ledgerColumns" :loading="ledgerLoading" :total="ledgerTotal" row-key="ledgerId" empty-text="暂无账户流水" @update:page="loadLedger()" @update:page-size="ledgerPage = 1; loadLedger()"><template #toolbar-actions><el-button v-if="canExport" :loading="ledgerExportBusy" :disabled="ledgerLoading || ledgerExportBusy" @click="exportLedger"><Download :size="16" />导出流水</el-button></template><template #pagination-left>共 {{ ledgerTotal }} 条</template><template #ledgerId="{ row }"><span class="ledger-identifier" :title="displayLedgerId(row.businessNo || row.ledgerId)">{{ displayLedgerId(row.businessNo || row.ledgerId) }}</span></template><template #occurredAt="{ row }">{{ row.occurredDate || formatDateTime(row.createdAt || row.occurredAt) }}</template><template #businessType="{ row }">{{ walletBusinessType(row.changeType || row.businessType) }}</template><template #documentNo="{ row }"><span class="ledger-document" :title="displayDocumentNo(row.referenceNo || row.sourceNo || row.documentNo)">{{ displayDocumentNo(row.referenceNo || row.sourceNo || row.documentNo) }}</span></template><template #amount="{ row }">{{ money(row.amount) }}</template><template #ledgerPaymentMethod="{ row }">{{ row.paymentMethod ? paymentMethodLabel(row.paymentMethod) : '—' }}</template><template #actualBalanceAfter="{ row }">{{ money(row.actualBalanceAfter) }}</template><template #frozenBalanceAfter="{ row }">{{ money(row.frozenBalanceAfter) }}</template><template #availableBalanceAfter="{ row }">{{ money(row.availableBalanceAfter) }}</template><template #creditUsedAfter="{ row }">{{ money(row.creditUsedAfter) }}</template><template #operatorName="{ row }">{{ displayOperator(row.operatorName) }}</template></DataTable></div>
+          </FormSection>
+          <FormSection v-else class="term-section density-form-section" title="账期设置" :bordered="false"><div class="term-editor"><span class="term-label">账期天数</span><div class="term-control"><el-input-number v-model="creditDays" :min="0" :max="3650" :step="1" placeholder="请输入账期天数" /><span class="term-unit">天</span></div></div></FormSection>
+        </template>
+        <template v-if="editing && selected && !ledgerError" #footer><div class="detail-footer"><el-button @click="closeDetail">关闭</el-button><el-button v-if="canUpdateTerms" type="primary" :loading="saving" @click="saveTerms"><Save :size="16" />保存账期</el-button></div></template>
+      </DetailPageLayout>
+      </section>
+    </AdminPage>
+    <AppDialog class="admin-density-dialog" v-model="adjustmentOpen" :title="adjustmentForm.type === 'RECHARGE' ? '手工充值' : '手工扣款'" width="min(720px, calc(100vw - 28px))" :confirm-text="adjustmentForm.type === 'RECHARGE' ? '确认充值' : '确认扣款'" :confirm-type="adjustmentForm.type === 'RECHARGE' ? 'primary' : 'danger'" :confirm-loading="adjustmentSaving" @confirm="submitAdjustment">
+      <el-alert :title="adjustmentForm.type === 'RECHARGE' ? '充值会先归还已用授信，剩余金额计入实际余额。' : '扣款先使用未冻结的实际余额，不足部分再使用可用授信。'" :type="adjustmentForm.type === 'RECHARGE' ? 'info' : 'warning'" :closable="false" />
+      <el-form label-position="top" class="wallet-form density-form"><div class="wallet-form__grid"><el-form-item label="客户名称"><el-input :model-value="adjustmentAccount ? customerName(adjustmentAccount.customerId, adjustmentAccount.customerName) : ''" readonly /></el-form-item><el-form-item label="当前实际余额"><el-input :model-value="money(adjustmentAccount?.actualBalance)" readonly /></el-form-item><el-form-item v-if="adjustmentForm.type === 'DEDUCTION'" label="当前可用余额"><el-input :model-value="money(adjustmentAccount?.availableBalance)" readonly /></el-form-item><el-form-item :label="adjustmentForm.type === 'RECHARGE' ? '充值金额' : '扣款金额'" required><el-input v-model="adjustmentForm.amount" inputmode="decimal" placeholder="请输入大于 0 的金额" /></el-form-item><el-form-item :label="adjustmentForm.type === 'RECHARGE' ? '到账日期' : '扣款日期'" required><el-date-picker v-model="adjustmentForm.occurredDate" type="date" value-format="YYYY-MM-DD" /></el-form-item><el-form-item :label="adjustmentForm.type === 'RECHARGE' ? '充值方式' : '扣款方式'" required><el-select v-model="adjustmentForm.paymentMethod"><el-option label="银行转账" value="BANK_TRANSFER" /><el-option label="现金" value="CASH" /><el-option label="其他" value="OTHER" /></el-select></el-form-item><el-form-item label="关联单据"><el-input v-model="adjustmentForm.referenceNo" maxlength="128" placeholder="请输入关联业务单号（选填）" /></el-form-item></div><el-form-item :label="adjustmentForm.type === 'RECHARGE' ? '充值备注' : '扣款备注'"><el-input v-model="adjustmentForm.remark" type="textarea" :rows="3" maxlength="1000" show-word-limit placeholder="请输入备注（选填）" /></el-form-item></el-form>
+    </AppDialog>
+    <AppDialog class="admin-density-dialog" v-model="creditLimitOpen" title="设置授信额度" width="min(560px, calc(100vw - 28px))" confirm-text="保存授信额度" :confirm-loading="creditLimitSaving" @confirm="submitCreditLimit">
+      <el-alert title="授信到期日当天仍有效，次日授信失效；届时负数实际余额将阻止客户提交新订单。" type="warning" :closable="false" />
+      <el-form label-position="top" class="wallet-form density-form"><el-form-item label="客户名称"><el-input :model-value="adjustmentAccount ? customerName(adjustmentAccount.customerId, adjustmentAccount.customerName) : ''" readonly /></el-form-item><el-form-item label="当前已用授信"><el-input :model-value="money(adjustmentAccount?.creditUsed)" readonly /></el-form-item><el-form-item label="授信额度" required><el-input v-model="creditLimitForm.amount" inputmode="decimal" placeholder="请输入大于或等于 0 的金额" /></el-form-item><el-form-item label="授信到期日" required><el-date-picker v-model="creditLimitForm.expiresOn" type="date" value-format="YYYY-MM-DD" :disabled-date="disableCreditExpiry" placeholder="请选择今天以后的日期" /></el-form-item><el-form-item label="调整说明"><el-input v-model="creditLimitForm.remark" type="textarea" :rows="3" maxlength="500" show-word-limit placeholder="请输入授信调整说明（选填）" /></el-form-item></el-form>
+    </AppDialog>
+    <AppDialog class="admin-density-dialog" v-model="reviewOpen" title="审核充值申请" width="min(620px, calc(100vw - 28px))" confirm-text="确认审核" :confirm-loading="reviewSaving" @confirm="submitReview">
+      <el-descriptions class="density-descriptions" v-if="reviewRequest" :column="2" border><el-descriptions-item label="申请单号">{{ reviewRequest.requestNo }}</el-descriptions-item><el-descriptions-item label="充值金额">{{ money(reviewRequest.amount) }}</el-descriptions-item><el-descriptions-item label="付款方式">{{ paymentMethodLabel(reviewRequest.paymentMethod) }}</el-descriptions-item><el-descriptions-item label="付款凭证">{{ reviewRequest.voucherFileName || '—' }}</el-descriptions-item></el-descriptions>
+      <el-form label-position="top" class="review-form density-form"><el-form-item label="审核结果" required><el-radio-group v-model="reviewForm.decision"><el-radio value="APPROVE">通过</el-radio><el-radio value="REJECT">驳回</el-radio></el-radio-group></el-form-item><el-form-item label="审核备注"><el-input v-model="reviewForm.remark" type="textarea" :rows="3" maxlength="1000" show-word-limit placeholder="请输入审核备注（选填）" /></el-form-item></el-form>
+    </AppDialog>
+    <AppDialog class="admin-density-dialog" v-model="voucherPreviewOpen" :title="voucherPreviewName" width="min(920px, calc(100vw - 28px))" :show-footer="false" @closed="clearVoucherPreview">
+      <div v-loading="voucherPreviewLoading" class="voucher-preview"><img v-if="voucherPreviewUrl" class="voucher-preview__image" :src="voucherPreviewUrl" :alt="voucherPreviewName" /></div>
+    </AppDialog>
+  </AdminPage>
+</template>
+
+<style scoped>
+.finance-account-page {
+  min-width: 0;
+}
+
+.finance-account-detail {
+  width: 100%;
+  min-width: 0;
+}
+
+.finance-account-detail__surface {
+  width: min(100%, 1920px);
+  margin: 0 auto;
+  overflow: hidden;
+}
+
+.finance-account-detail__layout {
+  width: 100%;
+  margin: 0 auto;
+}
+
+.detail-footer,
+.term-control {
+  display: flex;
+  align-items: center;
+  gap: var(--admin-space-3);
+}
+
+.balance-value {
+  color: var(--cc-text);
+  font-variant-numeric: tabular-nums;
+}
+
+.balance-value.is-actual {
+  color: var(--el-color-success);
+}
+
+.balance-value.is-frozen {
+  color: var(--el-color-warning);
+}
+
+.balance-value.is-negative,
+.credit-expired {
+  color: var(--el-color-danger);
+}
+
+.voucher-preview {
+  display: grid;
+  min-height: 320px;
+  place-items: center;
+}
+
+.voucher-preview__image {
+  display: block;
+  max-width: 100%;
+  max-height: 70vh;
+  object-fit: contain;
+}
+
+.ledger-section {
+  padding: var(--admin-space-4) 0 0;
+}
+
+.recharge-section {
+  padding: var(--admin-space-4) 0 0;
+  border-bottom: 1px solid var(--cc-border, #e3e8ef);
+}
+
+.recharge-table {
+  min-width: 0;
+}
+
+.ledger-query {
+  margin-bottom: var(--admin-space-3);
+}
+
+:deep(.ledger-query.query-toolbar) {
+  padding: 0;
+  border: 0;
+  background: transparent;
+}
+
+.detail-table-scroll {
+  overflow-x: auto;
+}
+
+.ledger-table {
+  min-width: 0;
+}
+
+.ledger-identifier,
+.ledger-document {
+  display: block;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-variant-numeric: tabular-nums;
+}
+
+.term-section {
+  width: 100%;
+  padding: var(--admin-space-4) 0;
+}
+
+.term-editor {
+  display: grid;
+  grid-template-columns: 120px minmax(0, 220px);
+  justify-content: start;
+  align-items: center;
+  gap: var(--admin-space-5);
+  padding: 2px 0;
+}
+
+.term-label {
+  color: var(--cc-text);
+  font-size: var(--admin-font-section);
+  font-weight: 600;
+}
+
+.term-control :deep(.el-input-number) {
+  width: 220px;
+}
+
+.term-unit {
+  color: var(--cc-muted);
+}
+
+.wallet-form,
+.review-form {
+  margin-top: var(--admin-space-5);
+}
+
+.wallet-form__grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 0 var(--admin-space-5);
+}
+
+.wallet-form :deep(.el-date-editor),
+.wallet-form :deep(.el-select) {
+  width: 100%;
+}
+
+.detail-footer {
+  width: 100%;
+  justify-content: flex-end;
+  margin-top: 0;
+  padding-top: var(--admin-space-3);
+  border-top: 0;
+}
+
+@media (min-width: 1920px) {
+
+  .detail-footer {
+    padding-top: 0;
+  }
+}
+
+@media (max-width: 1080px) {
+  .account-metrics {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+
+  .account-metric:nth-child(3),
+  .account-metric:nth-child(5) {
+    padding-left: 0;
+    border-left: 0;
+  }
+
+  .finance-account-detail__surface {
+    width: 100%;
+  }
+}
+
+@media (max-width: 720px) {
+  .wallet-form__grid {
+    grid-template-columns: 1fr;
+  }
+}
+
+@media (max-width: 720px) {
+  .detail-heading {
+    align-items: stretch;
+    flex-direction: column;
+  }
+
+  .detail-back {
+    margin-left: 0;
+  }
+
+  .detail-footer .el-button {
+    min-height: 44px;
+  }
+
+  .term-editor {
+    grid-template-columns: 1fr;
+  }
+
+  .account-metrics {
+    grid-template-columns: 1fr;
+    gap: 12px;
+  }
+
+  .account-metric,
+  .account-metric:first-child,
+  .account-metric:nth-child(3),
+  .account-metric:nth-child(5) {
+    padding-left: 0;
+  }
+
+  .account-metric + .account-metric {
+    border-left: 0;
+  }
+}
+
+@media (max-width: 480px) {
+  .detail-footer .el-button {
+    flex: 1 1 120px;
+  }
+}
+</style>
diff --git a/src/modules/finance/pages/FinanceCustomerArapView.test.ts b/src/modules/finance/pages/FinanceCustomerArapView.test.ts
new file mode 100644
index 00000000..3885197f
--- /dev/null
+++ b/src/modules/finance/pages/FinanceCustomerArapView.test.ts
@@ -0,0 +1,370 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import ElementPlus from 'element-plus'
+import { createPinia, setActivePinia } from 'pinia'
+import { createMemoryHistory, createRouter } from 'vue-router'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+import { createPlatformExportTask } from '@/modules/downloads'
+import { ApiResponseError } from '@/shared/api/http'
+import { showExportTaskCreatedDialog } from '@/shared/components/exportTaskCreatedDialog'
+import { listPlatformTenants, type PlatformTenantResource } from '@/modules/iam'
+import { adjustFinanceFeeSource, editFinanceFeeSource, getFinanceFeeSource, listFinanceFeeSources, reviewFinanceFeeSource, submitFinanceFeeSource, voidFinanceFeeSource } from '../api/finance'
+import type { FinanceFeeSourceDetail, FinanceFeeSourceSummary } from '../types'
+import FinanceCustomerArapView from './FinanceCustomerArapView.vue'
+
+vi.mock('@/modules/iam', () => ({ listPlatformTenants: vi.fn() }))
+vi.mock('@/modules/downloads', () => ({ createPlatformExportTask: vi.fn() }))
+vi.mock('@/shared/components/exportTaskCreatedDialog', () => ({ showExportTaskCreatedDialog: vi.fn() }))
+vi.mock('../api/finance', () => ({
+  listFinanceFeeSources: vi.fn(),
+  getFinanceFeeSource: vi.fn(),
+  reviewFinanceFeeSource: vi.fn(),
+  editFinanceFeeSource: vi.fn(), submitFinanceFeeSource: vi.fn(), adjustFinanceFeeSource: vi.fn(), voidFinanceFeeSource: vi.fn(),
+}))
+
+class ResizeObserverStub implements ResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+
+function createMemoryStorage(): Storage {
+  const values = new Map<string, string>()
+  return {
+    get length() { return values.size }, clear: () => values.clear(), getItem: (key) => values.get(key) ?? null,
+    key: (index) => [...values.keys()][index] ?? null, removeItem: (key) => values.delete(key), setItem: (key, value) => values.set(key, value),
+  }
+}
+
+const detail: FinanceFeeSourceDetail = {
+  poolItemId: '42', feeSourceId: '42', direction: 'RECEIVABLE', sourceType: 'INBOUND_FEE', sourceId: '81', sourceFeeId: '81', sourceVersion: 3,
+  sourceSystem: 'FIRSTLEG', sourceBusinessId: 'IB-91',
+  customerId: '10001', customerName: '客户A', supplierId: null, supplierName: '', orderId: null, inboundId: '91', inboundCode: 'IB-91', containerId: null, containerNo: '',
+  businessDate: '2026-08-11', feeItemName: '运费', quantity: 2, unitPrice: 50, amount: 100, currency: 'CNY', reviewStatus: 'PENDING',
+  sourceStatus: 'AVAILABLE', status: 'AVAILABLE', statementGenerated: false, operationVersion: 3, createdAt: '2026-08-11', operationLogs: [],
+}
+const feeSummary: FinanceFeeSourceSummary = {
+  poolItemId: '42', feeSourceId: '42', sourceSystem: 'FIRSTLEG', sourceType: 'INBOUND_FEE', sourceBusinessId: 'IB-91',
+  sourceId: '81', sourceVersion: 3, customerId: '10001', customerName: '客户A', direction: 'RECEIVABLE', supplierId: null,
+  supplierName: '', orderId: null, inboundId: '91', inboundCode: 'IB-91', containerId: null, containerNo: '', businessDate: '2026-08-11',
+  feeItemName: '运费', quantity: 2, unitPrice: 50, amount: 100, currency: 'CNY', reviewStatus: 'PENDING',
+  sourceStatus: 'AVAILABLE', statementGenerated: false, status: 'AVAILABLE', createdAt: '2026-08-11',
+}
+
+async function mountView(permissions: string[], initialPath = '/finance/customer-arap') {
+  const pinia = createPinia(); setActivePinia(pinia)
+  const auth = useAuthStore(); auth.token = 'token'; auth.permissions = permissions
+  useAccessPreviewStore().initializeAfterLogin()
+  const router = createRouter({ history: createMemoryHistory(), routes: [
+    { path: '/finance/customer-arap', name: 'finance-customer-arap', component: FinanceCustomerArapView },
+    { path: '/finance/customer-arap/:feeSourceId', name: 'finance-customer-arap-detail', component: FinanceCustomerArapView },
+    { path: '/finance/customer-statements', name: 'finance-customer-statements', component: { template: '<div>客户对账单</div>' } },
+  ] })
+  await router.push(initialPath); await router.isReady()
+  const wrapper = mount(FinanceCustomerArapView, {
+    attachTo: document.body,
+    global: { plugins: [pinia, ElementPlus, router], stubs: { LayoutPreferenceList: true } },
+  })
+  await flushPromises()
+  return Object.assign(wrapper, { router })
+}
+
+async function loadRows(wrapper: Awaited<ReturnType<typeof mountView>>) {
+  const vm = wrapper.vm as unknown as { load(model: Record<string, string>): Promise<void> }
+  await vm.load({ customerId: '10001', direction: '', status: '', keyword: '' })
+  await flushPromises()
+}
+
+enableAutoUnmount(afterEach)
+afterAll(() => vi.unstubAllGlobals())
+
+describe('FinanceCustomerArapView G2 operations', () => {
+  beforeEach(() => {
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+    vi.stubGlobal('localStorage', createMemoryStorage())
+    vi.stubGlobal('sessionStorage', createMemoryStorage())
+    document.body.innerHTML = ''
+    const customer = { id: '10001', tenantName: '客户A', status: 'ACTIVE' } as PlatformTenantResource
+    vi.mocked(listPlatformTenants).mockReset().mockResolvedValue({ records: [customer], page: 1, size: 200, total: 1, pages: 1 })
+    vi.mocked(listFinanceFeeSources).mockReset().mockResolvedValue({ records: [feeSummary], total: 1, pages: 1 })
+    vi.mocked(getFinanceFeeSource).mockReset().mockResolvedValue(detail)
+    vi.mocked(reviewFinanceFeeSource).mockReset().mockResolvedValue({ ...detail, reviewStatus: 'APPROVED', operationVersion: 4 })
+    vi.mocked(editFinanceFeeSource).mockReset().mockResolvedValue({ ...detail, reviewStatus: 'DRAFT', operationVersion: 4 })
+    vi.mocked(submitFinanceFeeSource).mockReset().mockResolvedValue({ ...detail, reviewStatus: 'PENDING', operationVersion: 4 })
+    vi.mocked(adjustFinanceFeeSource).mockReset().mockResolvedValue({ ...detail, reviewStatus: 'DRAFT', operationVersion: 4 })
+    vi.mocked(voidFinanceFeeSource).mockReset().mockResolvedValue({ ...detail, sourceStatus: 'VOIDED', status: 'VOIDED', operationVersion: 4 })
+    vi.mocked(createPlatformExportTask).mockReset().mockResolvedValue({ id: 'exp-3', taskNo: 'EXP-3', taskName: '客户应收应付费用来源', status: 'PENDING' } as never)
+    vi.mocked(showExportTaskCreatedDialog).mockReset().mockResolvedValue(false)
+  })
+
+  it.each([
+    ['DRAFT', ['详情', '编辑', '提交审核', ''], true],
+    ['APPROVED', ['详情', '调整', '作废'], false],
+    ['PENDING', ['详情', '作废'], false],
+  ])('keeps fee-source actions reachable at the three-action boundary: %s', async (reviewStatus, labels, overflow) => {
+    const row = { ...feeSummary, sourceSystem: 'FINANCE', sourceType: 'MANUAL', reviewStatus } as FinanceFeeSourceSummary
+    vi.mocked(listFinanceFeeSources).mockResolvedValue({ records: [row], total: 1, pages: 1 })
+    const wrapper = await mountView(['platform:finance:customer-arap:list', 'platform:finance:fee-source:edit'])
+    await loadRows(wrapper)
+    const actions = wrapper.get('.el-table__body-wrapper .density-actions')
+    expect(actions.findAll('button').map(button => button.text().trim())).toEqual(labels)
+    expect(actions.find('.el-dropdown').exists()).toBe(overflow)
+    if (overflow) {
+      const trigger = actions.get('button[title="更多费用来源操作"]')
+      expect(trigger.text()).toBe('')
+      await trigger.trigger('click')
+      await flushPromises()
+      const item = [...document.querySelectorAll<HTMLElement>('.el-dropdown-menu__item')].find(item => item.textContent?.trim() === '作废')
+      expect(item).toBeTruthy()
+      vi.mocked(getFinanceFeeSource).mockResolvedValueOnce({ ...detail, ...row })
+      item!.click()
+      await flushPromises()
+      expect(document.body.textContent).toContain('作废费用')
+      expect(voidFinanceFeeSource).not.toHaveBeenCalled()
+    }
+  })
+
+  it('shows detail from the list permission but keeps G2 operations independent', async () => {
+    const wrapper = await mountView(['platform:finance:customer-arap:list'])
+    await loadRows(wrapper)
+
+    const buttonLabels = wrapper.findAll('button').map((button) => button.text())
+    expect(buttonLabels).not.toContain('审核')
+    expect(buttonLabels).not.toContain('结算')
+    const vm = wrapper.vm as unknown as { openDetail(row: Record<string, unknown>): Promise<void> }
+    await vm.openDetail({ id: 'RECEIVABLE:42', feeSourceId: '42' })
+    expect(getFinanceFeeSource).toHaveBeenCalledWith('42')
+    expect(reviewFinanceFeeSource).not.toHaveBeenCalled()
+    expect(editFinanceFeeSource).not.toHaveBeenCalled()
+  })
+
+  it('treats inbound and container fee types as Firstleg sources when sourceSystem is missing', async () => {
+    const legacyFirstleg = { ...feeSummary, sourceSystem: '', sourceType: 'CONTAINER_FEE', reviewStatus: 'APPROVED' as const }
+    vi.mocked(listFinanceFeeSources).mockResolvedValue({ records: [legacyFirstleg], total: 1, pages: 1 })
+    const wrapper = await mountView(['platform:finance:customer-arap:list', 'platform:finance:fee-source:edit'])
+    await loadRows(wrapper)
+
+    const buttonLabels = wrapper.findAll('button').map((button) => button.text())
+    expect(buttonLabels).not.toContain('编辑')
+    expect(buttonLabels).not.toContain('调整')
+    const vm = wrapper.vm as unknown as { openMutation(row: Record<string, unknown>, mode: 'ADJUST'): Promise<void> }
+    await vm.openMutation(legacyFirstleg as unknown as Record<string, unknown>, 'ADJUST')
+    expect(getFinanceFeeSource).not.toHaveBeenCalled()
+    expect(adjustFinanceFeeSource).not.toHaveBeenCalled()
+  })
+
+  it('closes the customer dropdown when the surrounding page is scrolled', async () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/finance/pages/FinanceCustomerArapView.vue'), 'utf8')
+    expect(source).toContain("document.addEventListener('scroll', closeCustomerSelectOnScroll, true)")
+    expect(source).toContain('onVisibleChange: onCustomerSelectVisible')
+    expect(source).not.toContain('input?.blur()')
+    expect(source).toContain("class: 'finance-customer-select'")
+  })
+
+  it('uses sourceSystem to suppress Firstleg editing when the source type is not in the legacy fallback list', async () => {
+    const firstlegOtherType = { ...feeSummary, sourceType: 'ORDER_FEE', reviewStatus: 'DRAFT' as const }
+    vi.mocked(listFinanceFeeSources).mockResolvedValue({ records: [firstlegOtherType], total: 1, pages: 1 })
+    const wrapper = await mountView(['platform:finance:customer-arap:list', 'platform:finance:fee-source:edit'])
+    await loadRows(wrapper)
+
+    const buttonLabels = wrapper.findAll('button').map((button) => button.text())
+    expect(buttonLabels).not.toContain('缂栬緫')
+    const vm = wrapper.vm as unknown as { openMutation(row: Record<string, unknown>, mode: 'EDIT'): Promise<void> }
+    await vm.openMutation(firstlegOtherType as unknown as Record<string, unknown>, 'EDIT')
+    expect(getFinanceFeeSource).not.toHaveBeenCalled()
+    expect(editFinanceFeeSource).not.toHaveBeenCalled()
+  })
+
+  it('loads all customers by default and keeps explicit customer filtering', async () => {
+    const wrapper = await mountView(['platform:finance:customer-arap:list', 'platform:customer:list'])
+    expect(listFinanceFeeSources).toHaveBeenCalledWith(expect.objectContaining({ page: 1, size: 20, customerId: undefined, direction: undefined }))
+    const vm = wrapper.vm as unknown as { load(model: Record<string, string>): Promise<void> }
+    await vm.load({ customerId: '10001', direction: 'RECEIVABLE', status: '', keyword: '' })
+    expect(listFinanceFeeSources).toHaveBeenLastCalledWith(expect.objectContaining({ customerId: '10001', direction: 'RECEIVABLE' }))
+    expect(wrapper.text()).not.toContain('全客户查询暂不可用')
+  })
+
+  it('maps each all-customer fee row with its backend customerId', async () => {
+    const customerB = { id: '10002', tenantName: '客户B', status: 'ACTIVE' } as PlatformTenantResource
+    vi.mocked(listPlatformTenants).mockResolvedValue({ records: [{ id: '10001', tenantName: '客户A', status: 'ACTIVE' } as PlatformTenantResource, customerB], page: 1, size: 200, total: 2, pages: 1 })
+    vi.mocked(listFinanceFeeSources).mockResolvedValue({ records: [
+      feeSummary,
+      { ...feeSummary, poolItemId: '43', feeSourceId: '43', sourceBusinessId: 'CONT-43', customerId: '10002', customerName: '客户B', direction: 'PAYABLE', sourceType: 'CONTAINER_FEE', sourceId: '82', orderId: '11', inboundId: null, inboundCode: '', containerId: '31', containerNo: 'CONT-43', supplierId: '71', supplierName: '供应商A', feeItemName: '拖车费', amount: 200 },
+    ], total: 2, pages: 1 })
+    const wrapper = await mountView(['platform:finance:customer-arap:list'])
+    const vm = wrapper.vm as unknown as { load(model: Record<string, string>): Promise<void> }
+    await vm.load({ customerId: '', direction: '', status: '', keyword: '' })
+    await flushPromises()
+    expect(wrapper.text()).toContain('客户A')
+    expect(wrapper.text()).toContain('客户B')
+  })
+
+  it('loads detail and submits review with the returned version', async () => {
+    const wrapper = await mountView(['platform:finance:customer-arap:list', 'platform:finance:fee-source:review'])
+    await loadRows(wrapper)
+    const vm = wrapper.vm as unknown as {
+      openDetail(row: Record<string, unknown>): Promise<void>
+      openReview(row: Record<string, unknown>): Promise<void>
+      submitReview(): Promise<void>
+      reviewForm: { action: 'APPROVE' | 'REJECT'; reason: string }
+    }
+    const row = { id: 'RECEIVABLE:42', feeSourceId: '42' }
+
+    await vm.openDetail(row); await flushPromises()
+    expect(getFinanceFeeSource).toHaveBeenCalledWith('42')
+    expect(document.body.textContent).toContain('IB-91')
+    expect(document.body.textContent).toContain('100.00')
+    expect(document.body.textContent).toContain('CNY')
+
+    await vm.openReview(row); vm.reviewForm.action = 'APPROVE'; vm.reviewForm.reason = '核对无误'; await vm.submitReview()
+    expect(reviewFinanceFeeSource).toHaveBeenCalledWith('42', { action: 'APPROVE', reason: '核对无误', expectedVersion: 3 })
+  })
+
+  it('renders request and trace ids when detail loading fails', async () => {
+    vi.mocked(getFinanceFeeSource).mockRejectedValueOnce(new ApiResponseError('费用来源不可用', 'FIN-FEE-404', 404, undefined, 'req-g2-error', 'trace-g2-error'))
+    const wrapper = await mountView(['platform:finance:customer-arap:list'])
+    await loadRows(wrapper)
+    const vm = wrapper.vm as unknown as { openDetail(row: Record<string, unknown>): Promise<void> }
+
+    await vm.openDetail({ id: 'RECEIVABLE:42', feeSourceId: '42' }); await flushPromises()
+
+    expect(document.body.textContent).toContain('费用来源不可用')
+    expect(document.body.textContent).toContain('req-g2-error')
+    expect(document.body.textContent).toContain('trace-g2-error')
+  })
+
+  it('restores the independent detail route from its fee source id', async () => {
+    const wrapper = await mountView(['platform:finance:customer-arap:list'], '/finance/customer-arap/42')
+    expect(getFinanceFeeSource).toHaveBeenCalledWith('42')
+    expect(wrapper.get('.density-detail-title').text()).toContain('运费')
+    expect(wrapper.text()).toContain('IB-91')
+    expect(wrapper.router.currentRoute.value.name).toBe('finance-customer-arap-detail')
+  })
+
+  it('uses the desktop detail layout for summary, source information, and operation history', async () => {
+    const wrapper = await mountView(['platform:finance:customer-arap:list'], '/finance/customer-arap/42')
+    expect(wrapper.find('.finance-arap-detail__layout').exists()).toBe(true)
+    expect(wrapper.find('.finance-arap-detail__surface').exists()).toBe(true)
+    expect(wrapper.find('.detail-page-layout__header').exists()).toBe(true)
+    expect(wrapper.find('.detail-page-layout__summary').exists()).toBe(true)
+    expect(wrapper.find('.arap-metrics').exists()).toBe(true)
+    expect(wrapper.findAll('.arap-metric')).toHaveLength(4)
+    expect(wrapper.find('.arap-information').text()).toContain('单据信息')
+    expect(wrapper.find('.arap-settlement').text()).toContain('审核与结算')
+    expect(wrapper.find('.operation-log').text()).toContain('操作记录')
+    expect(wrapper.find('.arap-information').text()).toContain('业务日期')
+    expect(wrapper.find('.arap-information').text()).not.toContain('T00:00:00')
+  })
+
+  it('keeps the fee-source detail readable across the 1920 workspace', () => {
+    const page = readFileSync(resolve(process.cwd(), 'src/modules/finance/pages/FinanceCustomerArapView.vue'), 'utf8')
+    expect(page).toContain('width: min(100%, 1920px)')
+    expect(page).toContain('@media (min-width: 1920px)')
+    expect(page).toContain('grid-template-columns: minmax(0, 1.35fr) minmax(320px, 0.65fr)')
+    expect(page).toContain('finance-density-detail')
+    expect(page).not.toContain('max-width: 520px')
+  })
+
+  it('renders permitted fee-source row operations as shared outlined text buttons', () => {
+    const page = readFileSync(resolve(process.cwd(), 'src/modules/finance/pages/FinanceCustomerArapView.vue'), 'utf8')
+    expect(page).toContain('@click="openDetail(row)">详情</el-button>')
+    expect(page).toContain("@click=\"openMutation(row, 'SUBMIT')\"")
+    expect(page).toContain("@click=\"openMutation(row, 'ADJUST')\"")
+    expect(page).toContain('!isUpstreamSource(row)')
+    expect(page).toContain('!isUpstreamSource(detail)')
+    expect(page).toContain("['INBOUND_FEE', 'CONTAINER_FEE'].includes(type)")
+    expect(page).toContain("=== 'LASTLEG'")
+    const actions = page.slice(page.indexOf('<template #actions'), page.indexOf('<template #customerName'))
+    expect(actions).not.toMatch(/<el-button[^>]*\blink\b/)
+    expect(page).toContain('white-space: nowrap')
+  })
+
+  it('resolves blank detail customer names and keeps source labels business-facing', async () => {
+    vi.mocked(getFinanceFeeSource).mockResolvedValueOnce({ ...detail, customerName: '', sourceType: 'NEW_SOURCE' })
+    const wrapper = await mountView(['platform:finance:customer-arap:list'], '/finance/customer-arap/42')
+    expect(wrapper.get('.density-detail-title').text()).toContain('运费')
+    expect(wrapper.get('.finance-detail-context').text()).toBe('客户A')
+    expect(wrapper.text()).toContain('其他费用来源')
+    expect(wrapper.text()).not.toContain('其他来源')
+    expect(wrapper.text()).not.toContain('NEW_SOURCE')
+    expect(wrapper.text()).not.toContain('42 ·')
+  })
+
+  it('hides technical source identifiers and versions from list rows', async () => {
+    vi.mocked(listFinanceFeeSources).mockResolvedValue({ records: [{
+      ...feeSummary, poolItemId: '358', feeSourceId: '358', sourceType: 'CONTAINER_FEE', sourceBusinessId: 'CONT-20260814', sourceId: '2088285842638942210', sourceVersion: 1,
+      direction: 'PAYABLE', orderId: null, inboundId: null, inboundCode: '', containerId: '2088285834627821569', containerNo: 'CONT-20260814', supplierId: '71', supplierName: '供应商A',
+      feeItemName: 'ADMIN-API-20260814152244615-整柜成本', amount: 300, businessDate: '2026-08-14', createdAt: '2026-08-14',
+    }], total: 1, pages: 1 })
+    const wrapper = await mountView(['platform:finance:customer-arap:list'])
+    await (wrapper.vm as unknown as { load(model: Record<string, string>): Promise<void> }).load({ customerId: '', direction: '', status: '', keyword: '' })
+    const text = wrapper.text()
+    expect(text).toContain('整柜成本')
+    expect(text).toContain('柜次 CONT-20260814')
+    expect(text).toContain('供应商A')
+    expect(text).toContain('2026/8/14')
+    expect(text).not.toContain('PAYABLE:358')
+    expect(text).not.toContain('2088285842638942210')
+    expect(text).not.toContain('/v1')
+    expect(text).not.toContain('CONTAINER_FEE')
+    expect(text).not.toContain('ADMIN-API-20260814152244615')
+  })
+
+  it.each(['10001', '客户 10001', '客户10001'])('never displays customer id placeholder %s as a customer name', async (customerName) => {
+    vi.mocked(listPlatformTenants).mockResolvedValueOnce({ records: [], page: 1, size: 200, total: 0, pages: 1 })
+    vi.mocked(getFinanceFeeSource).mockResolvedValueOnce({ ...detail, customerName })
+    const wrapper = await mountView(['platform:finance:customer-arap:list'], '/finance/customer-arap/42')
+    expect(wrapper.text()).toContain('客户名称暂不可用')
+    expect(wrapper.text()).not.toContain(customerName)
+  })
+
+  it('continues selected eligible receivables in the customer statement generation center', async () => {
+    const wrapper = await mountView(['platform:finance:customer-arap:list', 'platform:finance:reconciliation:create'])
+    await loadRows(wrapper)
+    const vm = wrapper.vm as unknown as {
+      selectedRows: Array<Record<string, unknown>>
+      continueSelectedGeneration(): Promise<void>
+    }
+    vm.selectedRows = [{ id: 'RECEIVABLE:42', feeSourceId: '42', customerId: '10001', direction: 'RECEIVABLE', reviewStatus: 'APPROVED', status: 'AVAILABLE', statementGenerated: false, amount: 100, businessDate: '2026-08-11' }]
+    await vm.continueSelectedGeneration()
+    expect(wrapper.router.currentRoute.value).toMatchObject({
+      name: 'finance-customer-statements',
+      query: { createMode: 'SELECTED', customerId: '10001', feeSourceIds: '42', periodStart: '2026-08-11', periodEnd: '2026-08-11' },
+    })
+  })
+
+  it('creates a fee-source export task with the complete active filters and typed booleans', async () => {
+    const wrapper = await mountView(['platform:finance:customer-arap:list', 'platform:finance:customer-arap:export', 'platform:download:list'])
+    const vm = wrapper.vm as unknown as { filters: Record<string, unknown>; exportFeeSources(): Promise<void> }
+    Object.assign(vm.filters, {
+      customerId: '10001', direction: 'RECEIVABLE', reviewStatus: 'APPROVED',
+      statementGenerated: 'false', businessRange: ['2026-08-01', '2026-08-31'], keyword: '  运费  ',
+    })
+    await vm.exportFeeSources()
+    expect(createPlatformExportTask).toHaveBeenCalledWith({
+      exportType: 'FINANCE_FEE_SOURCE_LIST', format: 'XLSX', taskName: '客户应收应付费用来源',
+      parameters: {
+        customerId: '10001', direction: 'RECEIVABLE', reviewStatus: 'APPROVED',
+        statementGenerated: false, businessDateFrom: '2026-08-01', businessDateTo: '2026-08-31', keyword: '运费',
+      },
+    })
+    expect(showExportTaskCreatedDialog).toHaveBeenCalledWith({ taskName: '客户应收应付费用来源', taskNo: 'EXP-3', dense: true })
+  })
+
+  it('does not expose fee-source export without download-center access', async () => {
+    const wrapper = await mountView(['platform:finance:customer-arap:list', 'platform:finance:customer-arap:export'])
+    expect(wrapper.findAll('button').map((button) => button.text())).not.toContain('导出Excel')
+    expect(createPlatformExportTask).not.toHaveBeenCalled()
+  })
+
+  it('omits every empty fee-source filter instead of exporting the current table page', async () => {
+    const wrapper = await mountView(['platform:finance:customer-arap:list', 'platform:finance:customer-arap:export', 'platform:download:list'])
+    await (wrapper.vm as unknown as { exportFeeSources(): Promise<void> }).exportFeeSources()
+    expect(createPlatformExportTask).toHaveBeenCalledWith({
+      exportType: 'FINANCE_FEE_SOURCE_LIST', format: 'XLSX', taskName: '客户应收应付费用来源', parameters: {},
+    })
+  })
+})
diff --git a/src/modules/finance/pages/FinanceCustomerArapView.vue b/src/modules/finance/pages/FinanceCustomerArapView.vue
new file mode 100644
index 00000000..1aa197cd
--- /dev/null
+++ b/src/modules/finance/pages/FinanceCustomerArapView.vue
@@ -0,0 +1,594 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import '../financeDensity.css'
+import { computed, onBeforeUnmount, onMounted, reactive, ref, watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { MoreHorizontal, ArrowLeft, Download, FileCheck2, FilePlus2, Pencil, Send } from '@lucide/vue'
+import { ElMessage } from 'element-plus'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { createPlatformExportTask } from '@/modules/downloads'
+import { listPlatformTenants, type PlatformTenantResource } from '@/modules/iam'
+import { getApiErrorDetails, getApiErrorMessage, type ApiErrorDetails } from '@/shared/api/http'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import OperationErrorToast from '@/shared/components/OperationErrorToast.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import DetailPageLayout from '@/shared/components/DetailPageLayout.vue'
+import FormSection from '@/shared/components/FormSection.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import { showExportTaskCreatedDialog } from '@/shared/components/exportTaskCreatedDialog'
+import { adjustFinanceFeeSource, editFinanceFeeSource, getFinanceFeeSource, listFinanceFeeSources, reviewFinanceFeeSource, submitFinanceFeeSource, voidFinanceFeeSource } from '../api/finance'
+import { financeArapStatusOptions, financeDirectionLabel, financeOperationActionLabel, financeOperationResultLabel, financeSourceTypeLabel, financeStatusLabel } from '../status'
+import type { FinanceFeeSourceDetail } from '../types'
+
+interface ArapRow {
+  id: string
+  feeSourceId: string | null
+  sourceSystem: string
+  customerId: string
+  customerName: string
+  direction: 'RECEIVABLE' | 'PAYABLE'
+  documentNo: string
+  sourceBusinessId: string
+  sourceType: string
+  sourceId: string
+  orderId: string
+  inboundId: string
+  containerId: string
+  inboundCode: string
+  containerNo: string
+  supplierName: string
+  feeName: string
+  amount: number
+  status: string
+  occurredAt: string
+  businessDate: string
+  reviewStatus: string
+  statementGenerated: boolean | null
+}
+
+const access = useAccessPreviewStore()
+const route = useRoute()
+const router = useRouter()
+const customers = ref<PlatformTenantResource[]>([])
+const customersLoading = ref(false)
+const customersError = ref<ApiErrorDetails | null>(null)
+const filters = ref<QueryModel>({ customerId: '', direction: '', status: '', reviewStatus: '', statementGenerated: '', businessRange: [], keyword: '' })
+const allRows = ref<ArapRow[]>([])
+const loading = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const detailOpen = ref(false)
+const selected = ref<ArapRow | null>(null)
+const detail = ref<FinanceFeeSourceDetail | null>(null)
+const operationLogRows = computed(() => (detail.value?.operationLogs || []).map((log, index) => ({ ...log, rowKey: index })))
+const operationLogColumns: DataTableColumn[] = [
+  { key: 'occurredAt', label: '时间', width: 170, slotName: 'occurredAt' },
+  { key: 'action', label: '操作类型', minWidth: 120, slotName: 'action' },
+  { key: 'operatorName', label: '操作人', minWidth: 120, slotName: 'operatorName' },
+  { key: 'result', label: '备注 / 结果', minWidth: 280, slotName: 'result' },
+]
+const detailLoading = ref(false)
+const detailError = ref<ApiErrorDetails | null>(null)
+const reviewOpen = ref(false)
+const reviewSaving = ref(false)
+const reviewError = ref<ApiErrorDetails | null>(null)
+const reviewForm = reactive<{ action: 'APPROVE' | 'REJECT'; reason: string }>({ action: 'APPROVE', reason: '' })
+const mutationOpen = ref(false)
+const mutationSaving = ref(false)
+const mutationError = ref<ApiErrorDetails | null>(null)
+const mutationMode = ref<'EDIT' | 'ADJUST' | 'SUBMIT' | 'VOID'>('EDIT')
+const mutationForm = reactive({ amount: 0, reason: '' })
+const mutationTitle = computed(() => ({ EDIT: '编辑费用', ADJUST: '调整费用', SUBMIT: '提交审核', VOID: '作废费用' } as const)[mutationMode.value])
+const selectedRows = ref<ArapRow[]>([])
+const page = ref(1)
+const pageSize = ref(20)
+const total = ref(0)
+const exportBusy = ref(false)
+const customerSelectVisible = ref(false)
+
+const canView = computed(() => access.can('platform:finance:customer-arap:list'))
+const canListCustomers = computed(() => canView.value || access.can('platform:customer:list'))
+const canViewSource = computed(() => access.can('platform:finance:customer-arap:list'))
+const canReviewSource = computed(() => access.can('platform:finance:fee-source:review'))
+const canEditSource = computed(() => access.can('platform:finance:fee-source:edit'))
+const canCreateStatement = computed(() => access.can('platform:finance:reconciliation:create'))
+const canExport = computed(() => access.can('platform:finance:customer-arap:export') && access.can('platform:download:list'))
+function isFirstlegSource(source: { sourceSystem?: unknown; sourceType?: unknown }) {
+  const system = String(source.sourceSystem || '').trim().toUpperCase()
+  const type = String(source.sourceType || '').trim().toUpperCase()
+  return system === 'FIRSTLEG' || ['INBOUND_FEE', 'CONTAINER_FEE'].includes(type)
+}
+const stateError = computed(() => customersError.value || loadError.value)
+const activeCustomers = computed(() => customers.value.filter((item) => item.status === 'ACTIVE'))
+const queryFields = computed<QueryField[]>(() => [
+  {
+    key: 'customerId',
+    type: 'select',
+    label: '客户名称',
+    width: 260,
+    placeholder: '请选择客户',
+    props: {
+      'aria-label': '客户名称',
+      class: 'finance-customer-select',
+      popperClass: 'finance-customer-arap-popper',
+      teleported: false,
+      filterable: true,
+      clearable: true,
+      loading: customersLoading.value,
+      onVisibleChange: onCustomerSelectVisible,
+    },
+    options: activeCustomers.value.map((item) => ({ label: item.tenantName, value: String(item.id) })),
+  },
+  { key: 'direction', type: 'select', label: '收付方向', width: 140, placeholder: '请选择收付方向', options: [{ label: '应收', value: 'RECEIVABLE' }, { label: '应付', value: 'PAYABLE' }] },
+  { key: 'status', type: 'select', label: '来源状态', width: 150, placeholder: '请选择来源状态', options: [{ label: '可结算', value: 'AVAILABLE' }, { label: '已占用', value: 'LOCKED' }, { label: '已生成对账单', value: 'BILLED' }, { label: '资金账户已结清', value: 'SETTLED' }, { label: '已作废', value: 'VOIDED' }, { label: '已被调整替代', value: 'SUPERSEDED' }] },
+  { key: 'reviewStatus', type: 'select', label: '审核状态', width: 150, placeholder: '请选择审核状态', options: financeArapStatusOptions },
+  { key: 'statementGenerated', type: 'select', label: '已生成对账单', width: 160, placeholder: '请选择对账单状态', options: [{ label: '已生成', value: 'true' }, { label: '未生成', value: 'false' }] },
+  { key: 'businessRange', type: 'daterange', label: '业务日期', width: 280 },
+  { key: 'keyword', type: 'input', label: '关键词', width: 240, placeholder: '请输入业务单号/费用/客户/供应商', props: { 'aria-label': '关键词' } },
+])
+function onCustomerSelectVisible(visible: boolean) { customerSelectVisible.value = visible }
+function closeCustomerSelectOnScroll() {
+  if (!customerSelectVisible.value) return
+  const active = document.activeElement
+  if (active instanceof HTMLElement) active.blur()
+}
+function sourceActionCount(row: Record<string, unknown>) {
+  if (!row.feeSourceId) return 0
+  const available = row.status === 'AVAILABLE'
+  const draft = ['DRAFT', 'REJECTED'].includes(String(row.reviewStatus))
+  const editable = canEditSource.value && !isUpstreamSource(row)
+  return Number(canViewSource.value)
+    + Number(editable && draft && available)
+    + Number(canEditSource.value && draft && available)
+    + Number(canReviewSource.value && row.reviewStatus === 'PENDING' && available)
+    + Number(editable && row.reviewStatus === 'APPROVED' && available && !row.statementGenerated)
+    + Number(editable && available && !row.statementGenerated)
+}
+function isUpstreamSource(source: { sourceSystem?: unknown; sourceType?: unknown }) {
+  return isFirstlegSource(source) || String(source.sourceSystem || '').trim().toUpperCase() === 'LASTLEG'
+}
+const columns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 260, fixed: 'left', slotName: 'actions' }, { key: 'selection', type: 'selection', width: 48, fixed: 'left', selectable: isSelectableReceivable }, { key: 'direction', label: '收付方向', width: 100, slotName: 'direction' },
+  { key: 'customerName', label: '客户', minWidth: 180, slotName: 'customerName' }, { key: 'businessReference', label: '关联业务', minWidth: 220, slotName: 'businessReference' }, { key: 'sourceType', label: '来源类型', width: 120, slotName: 'sourceType' },
+  { key: 'feeName', label: '费用项目', minWidth: 150 }, { key: 'amount', label: '金额(CNY)', width: 130 }, { key: 'supplierName', label: '供应商', minWidth: 170, slotName: 'supplierName' },
+  { key: 'status', label: '来源状态', width: 130, slotName: 'sourceStatus' },
+  { key: 'reviewStatus', label: '审核状态', width: 120, slotName: 'status' }, { key: 'statementGenerated', label: '已生成对账单', width: 140, slotName: 'generated' }, { key: 'businessDate', label: '业务发生日', width: 170, slotName: 'businessDate' },
+]
+function customerName(customerId: string, snapshot?: string) {
+  const masterName = customers.value.find((item) => String(item.id) === String(customerId))?.tenantName?.trim()
+  const candidate = String(snapshot || '').trim()
+  const placeholder = [String(customerId), `客户 ${customerId}`, `客户${customerId}`].includes(candidate)
+  return masterName || (candidate && !placeholder ? candidate : '客户名称暂不可用')
+}
+function sourceTypeDisplay(value: unknown) {
+  const code = String(value || '').trim().toUpperCase()
+  const labels: Record<string, string> = {
+    INBOUND_FEE: '入库费用', ORDER_FEE: '订单费用', CONTAINER_COST: '整柜成本', CONTAINER_FEE: '柜次费用',
+    MANUAL_COST: '人工成本', STORAGE_FEE: '仓储费用',
+    OVERSEAS_INBOUND_FEE: '海外入仓费用', OVERSEAS_PROCUREMENT_FEE: '海外采购费用',
+    OVERSEAS_TRUCK_FEE: '本土卡车费用', OVERSEAS_LOOSEBOARD_FEE: '本土散板费用',
+    OVERSEAS_WAREHOUSE_FEE: '海外仓服务费', OVERSEAS_CONTAINER_FEE: '海外柜子费用',
+    OVERSEAS_ORDER_FEE: '尾程订单费用', OVERSEAS_DELIVERY_FEE: '尾程派送费用',
+    OVERSEAS_RELABEL_FEE: '换标费用',
+  }
+  return labels[code] || (code ? '其他费用来源' : '来源类型暂不可用')
+}
+function feeDocumentLabel(direction: ArapRow['direction'], feeName: unknown) {
+  const prefix = direction === 'RECEIVABLE' ? '应收费用' : '应付费用'
+  const name = displayFeeName(feeName)
+  return name ? `${prefix} · ${name}` : prefix
+}
+function displayFeeName(value: unknown) {
+  const name = String(value || '').trim()
+  if (!name) return ''
+  if (/^ADMIN-API-\d+-整柜成本$/i.test(name)) return '整柜成本'
+  return name
+}
+function sourceSummary(sourceType: unknown, orderId: unknown, inboundId: unknown, containerId: unknown) {
+  const relations = [inboundId ? '关联入库单' : '', orderId ? '关联订单' : '', containerId ? '关联柜次' : ''].filter(Boolean)
+  const type = sourceTypeDisplay(sourceType)
+  return relations.length ? `${type} · ${relations.join('、')}` : type
+}
+function businessReference(row: ArapRow) {
+  const references = [row.inboundCode ? `入仓码 ${row.inboundCode}` : '', row.containerNo ? `柜次 ${row.containerNo}` : '']
+  const businessId = row.sourceBusinessId.trim()
+  if (businessId && ![row.inboundCode, row.containerNo].includes(businessId)) references.push(`业务单号 ${businessId}`)
+  return references.filter(Boolean).join(' · ') || '业务关联待补充'
+}
+function supplierDisplay(row: ArapRow) { return row.direction === 'RECEIVABLE' ? '不适用' : row.supplierName.trim() || '供应商待补充' }
+function sourceStatusDisplay(value: unknown) {
+  const labels: Record<string, string> = { AVAILABLE: '可结算', LOCKED: '已占用', BILLED: '已生成对账单', SETTLED: '资金账户已结清', VOIDED: '已作废', SUPERSEDED: '已被调整替代' }
+  return labels[String(value || '').toUpperCase()] || '状态待确认'
+}
+function formatDateTime(value: unknown) {
+  const raw = String(value || '').trim()
+  if (!raw) return '时间暂不可用'
+  const date = new Date(raw)
+  return Number.isNaN(date.getTime()) ? '时间暂不可用' : date.toLocaleString('zh-CN', { hour12: false })
+}
+function formatBusinessDate(value: unknown) {
+  const raw = String(value || '').trim()
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(raw)) return '业务日期待补充'
+  const [year, month, day] = raw.split('-')
+  return `${year}/${Number(month)}/${Number(day)}`
+}
+function displayOperator(value: unknown) {
+  const operator = String(value || '').trim()
+  if (!operator) return '名称数据缺失'
+  return /^(?:operator-)?\d+$/i.test(operator) ? '名称数据缺失' : operator
+}
+const rows = computed(() => allRows.value)
+const selectedAmount = computed(() => selectedRows.value.reduce((sum, row) => sum + row.amount, 0))
+
+async function loadCustomers() {
+  if (!canListCustomers.value) return
+  customersLoading.value = true; customersError.value = null
+  try { const records: PlatformTenantResource[] = []; let currentPage = 1; let pages = 1; do { const result = await listPlatformTenants({ page: currentPage, size: 200, status: 'ACTIVE' }); records.push(...result.records); pages = Math.max(1, result.pages); currentPage += 1 } while (currentPage <= pages); customers.value = records }
+  catch (error) { customersError.value = getApiErrorDetails(error, '客户列表加载失败') }
+  finally { customersLoading.value = false }
+}
+async function load(model: QueryModel = filters.value) {
+  Object.assign(filters.value, model); allRows.value = []; loadError.value = null
+  const customerId = String(filters.value.customerId || '').trim()
+  loading.value = true
+  try {
+    const direction = String(filters.value.direction || '') as 'RECEIVABLE' | 'PAYABLE' | ''
+    const range = Array.isArray(filters.value.businessRange) ? filters.value.businessRange.map(String) : []
+    const result = await listFinanceFeeSources({
+      page: page.value, size: pageSize.value, customerId: customerId || undefined, direction: direction || undefined,
+      status: String(filters.value.status || '') || undefined,
+      reviewStatus: (String(filters.value.reviewStatus || '') || undefined) as 'DRAFT' | 'PENDING' | 'APPROVED' | 'REJECTED' | undefined,
+      statementGenerated: String(filters.value.statementGenerated || '') ? String(filters.value.statementGenerated) === 'true' : undefined,
+      businessDateFrom: range[0], businessDateTo: range[1], keyword: String(filters.value.keyword || '').trim() || undefined,
+    })
+    allRows.value = result.records.map((item): ArapRow => ({ id: item.poolItemId, feeSourceId: item.feeSourceId, sourceSystem: item.sourceSystem, customerId: item.customerId, customerName: customerName(item.customerId, item.customerName), direction: item.direction, documentNo: feeDocumentLabel(item.direction, item.feeItemName), sourceBusinessId: item.sourceBusinessId, sourceType: item.sourceType, sourceId: sourceSummary(item.sourceType, item.orderId, item.inboundId, item.containerId), orderId: item.orderId || '', inboundId: item.inboundId || '', containerId: item.containerId || '', inboundCode: item.inboundCode, containerNo: item.containerNo, supplierName: item.supplierName, feeName: displayFeeName(item.feeItemName), amount: item.amount, status: item.sourceStatus, occurredAt: item.businessDate, businessDate: item.businessDate, reviewStatus: item.reviewStatus, statementGenerated: item.statementGenerated }))
+    total.value = result.total
+  } catch (error) { loadError.value = getApiErrorDetails(error, '客户应收应付加载失败，请重试') }
+  finally { loading.value = false }
+}
+function search(model: QueryModel) { page.value = 1; void load(model) }
+async function loadDetail(row: ArapRow) {
+  detailLoading.value = true; detailError.value = null; detail.value = null
+  if (!row.feeSourceId) { detailError.value = { message: '该手工成本没有可审核的费用来源详情' }; detailLoading.value = false; return null }
+  try { detail.value = await getFinanceFeeSource(row.feeSourceId); return detail.value }
+  catch (error) { detailError.value = getApiErrorDetails(error, '费用来源详情加载失败，请重试'); return null }
+  finally { detailLoading.value = false }
+}
+async function openDetail(row: Record<string, unknown>) {
+  const target = row as unknown as ArapRow
+  if (!target.feeSourceId) return
+  await router.push({ name: 'finance-customer-arap-detail', params: { feeSourceId: target.feeSourceId } })
+}
+async function openReview(row: Record<string, unknown>) {
+  const target = row as unknown as ArapRow; selected.value = target
+  const loaded = await loadDetail(target)
+  if (!loaded) { detailOpen.value = true; return }
+  Object.assign(reviewForm, { action: 'APPROVE', reason: '' }); reviewError.value = null; reviewOpen.value = true
+}
+async function submitReview() {
+  if (!detail.value) return
+  if (reviewForm.action === 'REJECT' && !reviewForm.reason.trim()) { ElMessage.warning('请填写驳回原因'); return }
+  reviewSaving.value = true; reviewError.value = null
+  try {
+    detail.value = await reviewFinanceFeeSource(detail.value.feeSourceId, { action: reviewForm.action, reason: reviewForm.reason.trim() || undefined, expectedVersion: detail.value.operationVersion })
+    reviewOpen.value = false; ElMessage.success(reviewForm.action === 'APPROVE' ? '费用来源已审核通过' : '费用来源已驳回'); await load()
+  } catch (error) { reviewError.value = getApiErrorDetails(error, '费用来源审核失败，请重试') }
+  finally { reviewSaving.value = false }
+}
+async function openMutation(row: Record<string, unknown>, mode: 'EDIT' | 'ADJUST' | 'SUBMIT' | 'VOID') {
+  const target = row as unknown as ArapRow; selected.value = target
+  if ((mode === 'EDIT' || mode === 'ADJUST' || mode === 'VOID') && isUpstreamSource(target)) {
+    ElMessage.info(String(target.sourceSystem || '').toUpperCase() === 'LASTLEG'
+      ? '请到对应海外业务费用中调整或作废，审核后会通过跨区事件同步到财务'
+      : '请到订单入库费用或柜次费用明细中调整或作废，审核后会自动同步到财务')
+    return
+  }
+  const loaded = await loadDetail(target)
+  if (!loaded) { detailOpen.value = true; return }
+  mutationMode.value = mode; Object.assign(mutationForm, { amount: loaded.amount, reason: '' }); mutationError.value = null; mutationOpen.value = true
+}
+async function submitMutation() {
+  if (!detail.value) return
+  if (!mutationForm.reason.trim()) { ElMessage.warning('请填写操作原因'); return }
+  if ((mutationMode.value === 'EDIT' || mutationMode.value === 'ADJUST') && mutationForm.amount <= 0) { ElMessage.warning('金额必须大于 0'); return }
+  mutationSaving.value = true; mutationError.value = null
+  try {
+    const action = { reason: mutationForm.reason.trim(), expectedVersion: detail.value.operationVersion }
+    if (mutationMode.value === 'EDIT') detail.value = await editFinanceFeeSource(detail.value.feeSourceId, { ...action, amount: mutationForm.amount })
+    else if (mutationMode.value === 'ADJUST') detail.value = await adjustFinanceFeeSource(detail.value.feeSourceId, { ...action, amount: mutationForm.amount })
+    else if (mutationMode.value === 'SUBMIT') detail.value = await submitFinanceFeeSource(detail.value.feeSourceId, action)
+    else detail.value = await voidFinanceFeeSource(detail.value.feeSourceId, action)
+    mutationOpen.value = false; ElMessage.success(({ EDIT: '费用已保存为草稿', ADJUST: '费用调整已保存，待重新提交审核', SUBMIT: '费用已提交审核', VOID: '费用已作废' } as const)[mutationMode.value]); await load()
+  } catch (error) { mutationError.value = getApiErrorDetails(error, '费用操作失败，请重试') }
+  finally { mutationSaving.value = false }
+}
+function statusLabel(status: string) { return financeStatusLabel(status) }
+function money(value: unknown) { return Number(value || 0).toFixed(2) }
+function onSelectionChange(rows: ArapRow[]) { selectedRows.value = rows }
+function isSelectableReceivable(row: ArapRow) {
+  return Boolean(row.feeSourceId)
+    && row.direction === 'RECEIVABLE'
+    && row.reviewStatus === 'APPROVED'
+    && row.status === 'AVAILABLE'
+    && row.amount > 0
+    && row.statementGenerated === false
+}
+async function continueSelectedGeneration() {
+  if (!selectedRows.value.length) return ElMessage.warning('请先勾选需要生成对账单的应收费用')
+  if (selectedRows.value.some((row) => !isSelectableReceivable(row))) return ElMessage.warning('所选费用中存在不可生成对账单的记录，请刷新后重新选择')
+  const customerIds = [...new Set(selectedRows.value.map((row) => row.customerId))]
+  if (customerIds.length !== 1) return ElMessage.warning('一次只能选择同一客户的费用生成对账单')
+  const businessDates = selectedRows.value.map((row) => row.businessDate).filter((value) => /^\d{4}-\d{2}-\d{2}$/.test(value)).sort()
+  if (businessDates.length !== selectedRows.value.length) return ElMessage.warning('所选费用缺少有效业务日期，暂不能生成对账单')
+  await router.push({
+    name: 'finance-customer-statements',
+    query: {
+      createMode: 'SELECTED',
+      customerId: customerIds[0],
+      feeSourceIds: selectedRows.value.map((row) => row.feeSourceId as string).join(','),
+      periodStart: businessDates[0],
+      periodEnd: businessDates.at(-1),
+    },
+  })
+}
+async function exportFeeSources() {
+  const range = Array.isArray(filters.value.businessRange) ? filters.value.businessRange.map(String) : []
+  const customerId = String(filters.value.customerId || '').trim()
+  const direction = String(filters.value.direction || '').trim()
+  const reviewStatus = String(filters.value.reviewStatus || '').trim()
+  const generated = String(filters.value.statementGenerated || '')
+  const keyword = String(filters.value.keyword || '').trim()
+  exportBusy.value = true
+  try {
+    const task = await createPlatformExportTask({
+      exportType: 'FINANCE_FEE_SOURCE_LIST', format: 'XLSX', taskName: '客户应收应付费用来源',
+      parameters: {
+        ...(customerId ? { customerId } : {}),
+        ...(direction ? { direction } : {}),
+        ...(reviewStatus ? { reviewStatus } : {}),
+        ...(generated ? { statementGenerated: generated === 'true' } : {}),
+        ...(range[0] ? { businessDateFrom: range[0] } : {}),
+        ...(range[1] ? { businessDateTo: range[1] } : {}),
+        ...(keyword ? { keyword } : {}),
+      },
+    })
+    const openDownloadCenter = await showExportTaskCreatedDialog({ taskName: task.taskName, taskNo: task.taskNo, dense: true })
+    if (openDownloadCenter) await router.push({ name: 'download-center' })
+  } catch (error) { ElMessage.error(getApiErrorMessage(error, '客户应收应付导出任务创建失败')) }
+  finally { exportBusy.value = false }
+}
+async function closeDetail() { detailOpen.value = false; selected.value = null; detail.value = null; await router.push({ name: 'finance-customer-arap' }) }
+async function restoreFeeSourceDetail(feeSourceId: string) {
+  detailOpen.value = true; detailLoading.value = true; detailError.value = null; detail.value = null
+  try {
+    detail.value = await getFinanceFeeSource(feeSourceId)
+    selected.value = { id: detail.value.poolItemId, feeSourceId, sourceSystem: detail.value.sourceSystem, customerId: detail.value.customerId, customerName: customerName(detail.value.customerId, detail.value.customerName), direction: detail.value.direction, documentNo: feeDocumentLabel(detail.value.direction, detail.value.feeItemName), sourceBusinessId: detail.value.sourceBusinessId, sourceType: detail.value.sourceType, sourceId: detail.value.sourceId, orderId: detail.value.orderId || '', inboundId: detail.value.inboundId || '', containerId: detail.value.containerId || '', inboundCode: detail.value.inboundCode, containerNo: detail.value.containerNo, supplierName: detail.value.supplierName, feeName: displayFeeName(detail.value.feeItemName), amount: detail.value.amount, status: detail.value.status, occurredAt: detail.value.createdAt, businessDate: detail.value.businessDate, reviewStatus: detail.value.reviewStatus, statementGenerated: detail.value.statementGenerated }
+  } catch (error) { detailError.value = getApiErrorDetails(error, '费用来源详情加载失败，请重试') }
+  finally { detailLoading.value = false }
+}
+
+onMounted(async () => {
+  document.addEventListener('scroll', closeCustomerSelectOnScroll, true)
+  const feeSourceId = String(route.params.feeSourceId || '')
+  if (route.name === 'finance-customer-arap-detail' && feeSourceId) { if (canListCustomers.value) await loadCustomers(); await restoreFeeSourceDetail(feeSourceId); return }
+  if (canListCustomers.value) await loadCustomers()
+  await load()
+})
+onBeforeUnmount(() => document.removeEventListener('scroll', closeCustomerSelectOnScroll, true))
+watch(() => [route.name, String(route.params.feeSourceId || '')], ([name, feeSourceId], previous) => {
+  if (!previous) return
+  if (name === 'finance-customer-arap-detail' && feeSourceId) void restoreFeeSourceDetail(String(feeSourceId))
+  else { detailOpen.value = false; selected.value = null; detail.value = null; void load() }
+})
+</script>
+
+<template>
+  <AdminPage as="div" class="finance-arap-page admin-density" spacing="normal">
+    <OperationErrorToast :details="reviewError || mutationError" />
+      <el-result v-if="!canView" icon="warning" title="无权访问客户应收应付" sub-title="请联系管理员开通账单查看权限" />
+    <ListPageLayout v-else-if="!detailOpen" aria-label="客户应收应付">
+      <template #toolbar><QueryToolbar v-model="filters" class="surface-panel" ariaLabel="客户应收应付筛选" :fields="queryFields" preference-key="finance-customer-arap-query" @search="search" /></template>
+      <template v-if="stateError" #state><LoadErrorState title="客户应收应付加载失败" :message="stateError.message" :loading="customersLoading || loading" @retry="customersError ? loadCustomers() : load()"><template #details><ApiErrorMeta :details="stateError" /></template></LoadErrorState></template>
+      <section v-if="!customersError && !loadError" class="surface-panel table-panel">
+        <DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :loading="loading" :total="total" max-height="calc(100vh - 300px)" preference-key="finance-customer-arap-table" aria-label="客户应收应付列表" row-key="id" empty-text="暂无客户应收应付数据" @selection-change="onSelectionChange" @update:page="load()" @update:page-size="page = 1; load()">
+        <template #toolbar-actions><div class="generation-actions"><el-button v-if="canExport" :loading="exportBusy" :disabled="loading || exportBusy" @click="exportFeeSources"><Download :size="16" />导出Excel</el-button><el-button v-if="canCreateStatement" type="primary" :disabled="!selectedRows.length" @click="continueSelectedGeneration"><FilePlus2 :size="16" />生成所选对账单</el-button></div></template>
+        <template #actions="{ row }"><div class="row-actions density-actions"><template v-if="row.feeSourceId"><el-button data-tone="neutral" class="density-action" v-if="canViewSource" size="small" @click="openDetail(row)">详情</el-button><el-button data-tone="neutral" class="density-action" v-if="canEditSource && !isUpstreamSource(row) && ['DRAFT','REJECTED'].includes(row.reviewStatus) && row.status === 'AVAILABLE'" size="small" @click="openMutation(row, 'EDIT')">编辑</el-button><el-button data-tone="warning" class="density-action" v-if="canEditSource && ['DRAFT','REJECTED'].includes(row.reviewStatus) && row.status === 'AVAILABLE'" size="small" @click="openMutation(row, 'SUBMIT')">提交审核</el-button><el-button data-tone="warning" class="density-action" v-if="canReviewSource && row.reviewStatus === 'PENDING' && row.status === 'AVAILABLE'" size="small" @click="openReview(row)">审核</el-button><el-button data-tone="neutral" class="density-action" v-if="canEditSource && !isUpstreamSource(row) && row.reviewStatus === 'APPROVED' && row.status === 'AVAILABLE' && !row.statementGenerated" size="small" @click="openMutation(row, 'ADJUST')">调整</el-button><el-button data-tone="danger" class="density-action" v-if="canEditSource && !isUpstreamSource(row) && row.status === 'AVAILABLE' && !row.statementGenerated && sourceActionCount(row) <= 3" size="small" @click="openMutation(row, 'VOID')">作废</el-button><el-dropdown v-if="canEditSource && !isUpstreamSource(row) && row.status === 'AVAILABLE' && !row.statementGenerated && sourceActionCount(row) > 3" trigger="click"><el-button class="density-action" data-tone="neutral" size="small" title="更多费用来源操作" :aria-label="`更多费用来源操作 · ${row.documentNo || '当前费用'}`"><MoreHorizontal :size="15" aria-hidden="true" /></el-button><template #dropdown><el-dropdown-menu><el-dropdown-item class="danger-menu-item" @click="openMutation(row, 'VOID')">作废</el-dropdown-item></el-dropdown-menu></template></el-dropdown></template><span v-else class="muted-action">手工成本</span></div></template>
+        <template #customerName="{ row }">{{ customerName(row.customerId, row.customerName) }}</template><template #direction="{ row }"><el-tag :type="row.direction === 'RECEIVABLE' ? 'success' : row.direction === 'PAYABLE' ? 'warning' : 'info'">{{ financeDirectionLabel(row.direction) }}</el-tag></template>
+        <template #businessReference="{ row }">{{ businessReference(row as unknown as ArapRow) }}</template><template #sourceType="{ row }">{{ sourceTypeDisplay(row.sourceType) }}</template><template #supplierName="{ row }">{{ supplierDisplay(row as unknown as ArapRow) }}</template><template #sourceStatus="{ row }">{{ sourceStatusDisplay(row.status) }}</template>
+        <template #status="{ row }"><el-tag :type="row.reviewStatus === 'APPROVED' ? 'success' : row.reviewStatus === 'REJECTED' ? 'danger' : 'warning'">{{ statusLabel(row.reviewStatus) }}</el-tag></template>
+        <template #generated="{ row }">{{ row.statementGenerated == null ? '待加载' : row.statementGenerated ? '已生成' : '未生成' }}</template>
+        <template #businessDate="{ row }">{{ formatBusinessDate(row.businessDate) }}</template><template #pagination-left>已选 {{ selectedRows.length }} 笔 · 应收金额 {{ money(selectedAmount) }} CNY</template>
+      </DataTable></section>
+    </ListPageLayout>
+    <AdminPage v-else as="div" class="finance-arap-detail admin-density" spacing="normal">
+      <section class="surface-panel finance-arap-detail__surface">
+      <DetailPageLayout class="finance-arap-detail__layout finance-density-detail" aria-label="费用来源详情">
+        <template #header><div class="density-detail-header"><div class="density-detail-heading"><el-button link class="density-back" @click="closeDetail"><ArrowLeft :size="16" />返回客户应收应付</el-button><h1 class="density-detail-title">{{ selected?.documentNo || '费用来源详情' }}</h1><span class="finance-detail-context">{{ selected ? customerName(selected.customerId, selected.customerName) : '—' }}</span><StatusBadge v-if="detail" :status="statusLabel(detail.reviewStatus)" /></div><div class="finance-detail-actions"><el-button v-if="canEditSource && detail && !isUpstreamSource(detail) && ['DRAFT','REJECTED'].includes(detail.reviewStatus)" @click="openMutation(selected as unknown as Record<string, unknown>, 'EDIT')"><Pencil :size="16" />编辑</el-button><el-button v-if="canEditSource && detail && ['DRAFT','REJECTED'].includes(detail.reviewStatus)" @click="openMutation(selected as unknown as Record<string, unknown>, 'SUBMIT')"><Send :size="16" />提交审核</el-button><el-button v-if="canReviewSource && detail?.reviewStatus === 'PENDING' && selected" @click="openReview(selected as unknown as Record<string, unknown>)"><FileCheck2 :size="16" />审核</el-button></div></div></template>
+        <template v-if="detail" #summary><dl class="density-detail-overview arap-metrics" aria-label="费用来源概览"><div class="arap-metric is-amount"><dt>结算金额</dt><dd>{{ money(detail.amount) }} <small>CNY</small></dd></div><div class="arap-metric"><dt>收付方向</dt><dd>{{ financeDirectionLabel(detail.direction) }}</dd></div><div class="arap-metric"><dt>来源状态</dt><dd>{{ sourceStatusDisplay(detail.sourceStatus) }}</dd></div><div class="arap-metric"><dt>审核状态</dt><dd>{{ statusLabel(detail.reviewStatus) }}</dd></div></dl></template>
+        <LoadErrorState v-if="detailError" title="费用来源详情加载失败" :message="detailError.message" :loading="detailLoading" @retry="selected && loadDetail(selected)"><template #details><ApiErrorMeta :details="detailError" /></template></LoadErrorState>
+        <template v-else-if="detail"><div class="arap-detail-grid"><FormSection class="arap-information density-form-section" title="单据信息" :bordered="false"><el-descriptions border :column="2" class="arap-detail density-descriptions"><el-descriptions-item label="客户">{{ customerName(detail.customerId, detail.customerName || selected?.customerName) }}</el-descriptions-item><el-descriptions-item label="费用项目">{{ displayFeeName(detail.feeItemName) }}</el-descriptions-item><el-descriptions-item label="来源类型">{{ sourceTypeDisplay(detail.sourceType) }}</el-descriptions-item><el-descriptions-item label="关联业务">{{ detail.inboundCode || detail.containerNo || detail.sourceBusinessId || '业务关联待补充' }}</el-descriptions-item><el-descriptions-item v-if="detail.direction === 'PAYABLE'" label="供应商">{{ detail.supplierName || '供应商待补充' }}</el-descriptions-item><el-descriptions-item label="业务日期">{{ formatBusinessDate(detail.businessDate) }}</el-descriptions-item><el-descriptions-item label="原币金额">{{ detail.originalCurrency }} {{ money(detail.originalAmount) }}</el-descriptions-item><el-descriptions-item label="折算汇率">{{ detail.exchangeRate }}<template v-if="detail.exchangeRateMonth">（{{ detail.exchangeRateMonth }}）</template></el-descriptions-item><el-descriptions-item v-if="detail.quantity != null" label="计费依据">{{ detail.quantity }} {{ detail.quantityUnit || '' }}<template v-if="detail.unitPrice != null"> × {{ detail.originalCurrency }} {{ detail.unitPrice }}</template></el-descriptions-item><el-descriptions-item v-if="detail.periodStart" label="计费期间">{{ detail.periodStart }} 至 {{ detail.periodEnd }}</el-descriptions-item></el-descriptions></FormSection><FormSection class="arap-settlement density-form-section" title="审核与结算" :bordered="false"><el-descriptions border :column="1" class="arap-detail density-descriptions"><el-descriptions-item label="费用状态">{{ sourceStatusDisplay(detail.sourceStatus) }}</el-descriptions-item><el-descriptions-item label="已生成对账单">{{ detail.statementGenerated ? '是' : '否' }}</el-descriptions-item><el-descriptions-item label="审核原因">{{ detail.reviewReason || '未填写' }}</el-descriptions-item></el-descriptions></FormSection></div><FormSection class="operation-log density-form-section" title="操作记录" :bordered="false"><DataTable :data="operationLogRows" :columns="operationLogColumns" row-key="rowKey" column-settings-mode="hide" empty-text="暂无操作记录"><template #occurredAt="{ row }">{{ formatDateTime(row.occurredAt) }}</template><template #action="{ row }">{{ financeOperationActionLabel(row.action) }}</template><template #operatorName="{ row }">{{ displayOperator(row.operatorName) }}</template><template #result="{ row }">{{ row.remark || financeOperationResultLabel(row.result) }}</template></DataTable></FormSection></template>
+      </DetailPageLayout>
+      </section>
+    </AdminPage>
+    <AppDialog class="admin-density-dialog" v-model="reviewOpen" title="费用来源审核" confirm-text="提交审核" :confirm-loading="reviewSaving" @confirm="submitReview">
+      <el-form class="density-form" label-position="top"><el-form-item label="审核结论"><el-segmented v-model="reviewForm.action" :options="[{ label: '通过', value: 'APPROVE' }, { label: '驳回', value: 'REJECT' }]" /></el-form-item><el-form-item :label="reviewForm.action === 'REJECT' ? '驳回原因' : '审核说明（可选）'"><el-input v-model="reviewForm.reason" type="textarea" :rows="3" maxlength="500" :placeholder="reviewForm.action === 'REJECT' ? '请填写驳回原因' : '请输入审核说明（可选）'" show-word-limit /></el-form-item></el-form>
+    </AppDialog>
+    <AppDialog class="admin-density-dialog" v-model="mutationOpen" :title="mutationTitle" :confirm-text="mutationMode === 'VOID' ? '确认作废' : '确认'" :confirm-loading="mutationSaving" @confirm="submitMutation">
+      <el-form class="density-form" label-position="top"><el-form-item v-if="mutationMode === 'EDIT' || mutationMode === 'ADJUST'" label="金额(CNY)"><el-input-number v-model="mutationForm.amount" :min="0.01" :precision="2" :controls="false" style="width:100%" placeholder="请输入调整金额" /></el-form-item><el-form-item label="操作原因"><el-input v-model="mutationForm.reason" type="textarea" :rows="3" maxlength="500" placeholder="请填写操作原因" show-word-limit /></el-form-item></el-form>
+    </AppDialog>
+  </AdminPage>
+</template>
+
+<style scoped>
+:deep(.danger-menu-item:not(.is-disabled)) { color: var(--el-color-danger); }
+.finance-arap-page {
+  min-width: 0;
+}
+
+/* Customer names can contain an order suffix; keep the selector readable without changing the query value. */
+:deep(.finance-customer-select .el-select__selected-item) {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+:deep(.finance-customer-arap-popper) {
+  width: max(260px, min(360px, calc(100vw - 32px))) !important;
+  max-width: calc(100vw - 32px);
+}
+
+:deep(.finance-customer-arap-popper .el-select-dropdown__item) {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.finance-arap-detail {
+  width: 100%;
+  min-width: 0;
+}
+
+.finance-arap-detail__surface {
+  width: min(100%, 1920px);
+  margin: 0 auto;
+  overflow: hidden;
+}
+
+.finance-arap-detail__layout {
+  width: 100%;
+  margin: 0 auto;
+}
+
+.generation-actions {
+  display: flex;
+  align-items: center;
+  gap: var(--admin-space-3);
+}
+
+.muted-action {
+  color: var(--cc-muted);
+}
+
+.arap-detail-grid {
+  display: grid;
+  grid-template-columns: minmax(0, 1.35fr) minmax(320px, 0.65fr);
+  gap: var(--admin-space-6);
+  border-bottom: 1px solid var(--cc-border, #e3e8ef);
+}
+
+.arap-information,
+.arap-settlement,
+.operation-log {
+  padding: var(--admin-space-4) 0;
+}
+
+.arap-settlement {
+  padding-left: var(--admin-space-6);
+  border-left: 1px solid var(--cc-border, #e3e8ef);
+}
+
+
+
+:deep(.arap-detail .el-descriptions__content) {
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
+:deep(.arap-detail .el-descriptions__label) {
+  width: 112px;
+  color: var(--cc-muted);
+}
+
+.operation-log :deep(.el-empty) {
+  padding: var(--admin-space-4) 0 2px;
+}
+
+.operation-log :deep(.el-empty__image) {
+  display: none;
+}
+
+.operation-log small {
+  display: block;
+  margin-top: var(--admin-space-1);
+  color: var(--cc-muted);
+}
+
+@media (min-width: 1920px) {
+
+  .arap-detail-grid {
+    gap: var(--admin-space-4);
+  }
+
+  .arap-settlement {
+    padding-left: var(--admin-space-4);
+  }
+}
+
+@media (max-width: 1080px) {
+  .finance-arap-detail__surface {
+    width: 100%;
+  }
+
+  .arap-metrics {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+
+  .arap-metric:nth-child(3) {
+    padding-left: 0;
+    border-left: 0;
+  }
+
+  .arap-detail-grid {
+    grid-template-columns: 1fr;
+    gap: 0;
+  }
+
+  .arap-settlement {
+    padding-left: 0;
+    border-left: 0;
+    border-top: 1px solid var(--cc-border, #e3e8ef);
+  }
+}
+
+@media (max-width: 720px) {
+  .detail-heading {
+    align-items: stretch;
+    flex-direction: column;
+  }
+
+  .detail-actions {
+    margin-left: 0;
+  }
+
+  .arap-metrics {
+    grid-template-columns: 1fr;
+    gap: 12px;
+  }
+
+  .arap-metric,
+  .arap-metric:first-child,
+  .arap-metric:nth-child(3) {
+    padding-left: 0;
+  }
+
+  .arap-metric + .arap-metric {
+    border-left: 0;
+  }
+
+  :deep(.arap-detail .el-descriptions__body .el-descriptions__table) {
+    table-layout: fixed;
+  }
+}
+
+@media (max-width: 480px) {
+  :deep(.arap-detail .el-descriptions__cell) {
+    display: block;
+    width: 100%;
+  }
+}
+</style>
diff --git a/src/modules/finance/pages/FinanceCustomerStatementsView.test.ts b/src/modules/finance/pages/FinanceCustomerStatementsView.test.ts
new file mode 100644
index 00000000..ca7a61e9
--- /dev/null
+++ b/src/modules/finance/pages/FinanceCustomerStatementsView.test.ts
@@ -0,0 +1,410 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import ElementPlus from 'element-plus'
+import { createPinia, setActivePinia } from 'pinia'
+import { createMemoryHistory, createRouter } from 'vue-router'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+import { ApiResponseError } from '@/shared/api/http'
+import { createPlatformExportTask } from '@/modules/downloads'
+import { listPlatformTenants } from '@/modules/iam'
+import { showExportTaskCreatedDialog } from '@/shared/components/exportTaskCreatedDialog'
+import { createReconciliationStatement, getReconciliationStatement, listFinanceFeeSources, listFinanceStatements } from '../api/finance'
+import type { FinanceFeeSourceSummary, FinanceReconciliationDetail, FinanceStatementReadModel } from '../types'
+import FinanceCustomerStatementsView from './FinanceCustomerStatementsView.vue'
+
+vi.mock('@/modules/iam', () => ({ listPlatformTenants: vi.fn() }))
+vi.mock('@/modules/downloads', () => ({ createPlatformExportTask: vi.fn() }))
+vi.mock('@/shared/components/exportTaskCreatedDialog', () => ({ showExportTaskCreatedDialog: vi.fn() }))
+vi.mock('../api/finance', () => ({
+  actionReconciliationStatement: vi.fn(), createReconciliationStatement: vi.fn(),
+  getReconciliationStatement: vi.fn(), listFinanceFeeSources: vi.fn(), listFinanceStatements: vi.fn(),
+}))
+
+class ResizeObserverStub implements ResizeObserver { observe() {} unobserve() {} disconnect() {} }
+function memoryStorage(): Storage {
+  const values = new Map<string, string>()
+  return { get length() { return values.size }, clear: () => values.clear(), getItem: (key) => values.get(key) ?? null, key: (index) => [...values.keys()][index] ?? null, removeItem: (key) => values.delete(key), setItem: (key, value) => values.set(key, value) }
+}
+
+const statement: FinanceStatementReadModel = {
+  id: '501', customerId: '10001', billNo: 'REC-501', customerName: '客户A', billDate: '2026-08-31', dueDate: '',
+  periodStart: '2026-08-01', periodEnd: '2026-08-31', creditDays: 30, lineCount: 1, sourceCount: 1,
+  sourceAmount: 320, adjustmentAmount: -20, settled: false, lastReceiptAt: '2026-08-20 10:00:00',
+  submittedAt: '2026-08-02 09:00:00', reviewedAt: '2026-08-03 09:00:00', issuedAt: '2026-08-04 09:00:00', remark: '八月账单',
+  totalAmount: 300, receivedAmount: 100, outstandingAmount: 200, currency: 'CNY', status: 'ISSUED', version: 3,
+  customerConfirmationStatus: 'CONFIRMED', customerConfirmedBy: '17', customerConfirmedByName: '客户确认人', customerConfirmedAt: '2026-08-05 10:00:00',
+  createdBy: '7', createdByName: '创建人A', createdAt: '2026-08-01 09:00:00', updatedBy: '8', updatedByName: '更新人B', updatedAt: '2026-08-20 11:00:00',
+}
+const detail: FinanceReconciliationDetail = {
+  ...statement, paidAmount: 100, periodStart: '2026-08-01', periodEnd: '2026-08-31', creditDays: 30, settled: false, remark: '八月账单',
+  createdBy: '7', createdByName: '创建人A', createdAt: '2026-08-01 09:00:00', updatedBy: '8', updatedByName: '更新人B', updatedAt: '2026-08-20 11:00:00',
+  lines: [{ statementLineId: '601', sourceFeeId: '81', sourceFeeVersion: 2, sourceHash: 'hash-81', direction: 'RECEIVABLE', sourceType: 'CONTAINER_FEE', sourceNo: 'CONT-31', orderId: '11', inboundId: '21', inboundCode: 'IN-21', containerId: '31', containerNo: 'CONT-31', businessDate: '2026-08-15', quantity: 10, unitPrice: 30, feeItemName: '运费', sourceAmount: 320, amount: 300, adjustmentReason: '优惠调整' }],
+  paymentHistory: [{ transactionId: '701', transactionType: 'RECEIPT', transactionDate: '2026-08-20', amount: 100, method: 'BANK_TRANSFER', referenceNo: 'PAY-701', voucherFileIds: ['9001'], createdBy: '9', createdByName: '财务员', occurredAt: '2026-08-20 10:00:00' }],
+  revisions: [{ revisionNo: 1, action: 'ADJUST', beforeAmount: 320, afterAmount: 300, reason: '优惠调整', operatorId: '10', operatorName: '调整人', occurredAt: '2026-08-20 09:00:00' }],
+}
+const eligibleFeeSource: FinanceFeeSourceSummary = {
+  poolItemId: '42', feeSourceId: '42', sourceSystem: 'FIRSTLEG', sourceType: 'INBOUND_FEE', sourceBusinessId: 'IN-21',
+  sourceId: '81', sourceVersion: 2, customerId: '10001', customerName: '客户A', direction: 'RECEIVABLE', supplierId: null,
+  supplierName: '', orderId: '11', inboundId: '21', inboundCode: 'IN-21', containerId: null, containerNo: '', businessDate: '2026-08-15',
+  feeItemName: '运费', quantity: 10, unitPrice: 30, amount: 320, currency: 'CNY', reviewStatus: 'APPROVED',
+  sourceStatus: 'AVAILABLE', statementGenerated: false, status: 'AVAILABLE', createdAt: '2026-08-15',
+}
+
+async function mountPage(permissions = ['platform:finance:customer-statement:list'], initialPath = '/finance/customer-statements') {
+  const pinia = createPinia(); setActivePinia(pinia)
+  const auth = useAuthStore(); auth.token = 'token'; auth.permissions = permissions
+  useAccessPreviewStore().initializeAfterLogin()
+  const router = createRouter({ history: createMemoryHistory(), routes: [
+    { path: '/finance/customer-statements', name: 'finance-customer-statements', component: FinanceCustomerStatementsView },
+    { path: '/finance/customer-statements/:statementId', name: 'finance-customer-statement-detail', component: FinanceCustomerStatementsView },
+    { path: '/downloads', name: 'download-center', component: { template: '<div>下载中心</div>' } },
+  ] })
+  await router.push(initialPath); await router.isReady()
+  const wrapper = mount(FinanceCustomerStatementsView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus, router] } })
+  await flushPromises()
+  return { wrapper, router }
+}
+
+enableAutoUnmount(afterEach)
+afterAll(() => vi.unstubAllGlobals())
+
+describe('FinanceCustomerStatementsView', () => {
+  beforeEach(() => {
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+    vi.stubGlobal('localStorage', memoryStorage())
+    vi.stubGlobal('sessionStorage', memoryStorage())
+    vi.stubGlobal('URL', { createObjectURL: vi.fn(() => 'blob:statement-export'), revokeObjectURL: vi.fn() })
+    document.body.innerHTML = ''
+    vi.mocked(listPlatformTenants).mockResolvedValue({ records: [{ id: '10001', tenantName: '客户A', status: 'ACTIVE' } as never], page: 1, size: 200, total: 1, pages: 1 })
+    vi.mocked(listFinanceStatements).mockResolvedValue([statement])
+    vi.mocked(getReconciliationStatement).mockResolvedValue(detail)
+    vi.mocked(listFinanceFeeSources).mockReset().mockResolvedValue({ records: [eligibleFeeSource], total: 1, pages: 1 })
+    vi.mocked(createReconciliationStatement).mockReset().mockResolvedValue({ ...detail, id: '502', billNo: 'REC-502', status: 'DRAFT' })
+    vi.mocked(createPlatformExportTask).mockReset().mockResolvedValue({ taskName: '客户对账单', taskNo: 'EXP-STMT-1' } as never)
+    vi.mocked(showExportTaskCreatedDialog).mockReset().mockResolvedValue(false)
+  })
+
+  it('opens statement details on a dedicated route instead of below the list', async () => {
+    const { wrapper, router } = await mountPage()
+    await (wrapper.vm as unknown as { openDetail(row: FinanceStatementReadModel): Promise<void> }).openDetail(statement)
+    await flushPromises()
+    expect(router.currentRoute.value.name).toBe('finance-customer-statement-detail')
+    expect(router.currentRoute.value.params.statementId).toBe('501')
+    expect(document.body.textContent).toContain('账单明细表')
+    expect(document.body.textContent).toContain('账单支付历史表')
+    expect(document.body.textContent).toContain('REC-501')
+    expect(document.body.textContent).toContain('CONT-31')
+    expect(document.body.textContent).toContain('IN-21')
+    expect(document.body.textContent).not.toContain('来源版本')
+    expect(document.body.textContent).not.toContain('hash-81')
+    expect(document.body.textContent).toContain('优惠调整')
+    expect(document.body.textContent).toContain('创建人A')
+    expect(document.body.textContent).toContain('调整人')
+    expect(document.body.textContent).toContain('2026-08-20 11:00')
+    expect(document.querySelector('[aria-label="客户对账单详情"]')).toBeTruthy()
+    expect(document.querySelector('[aria-label="客户对账单列表"]')).toBeNull()
+    expect(document.querySelector('[aria-label="所选对账单联动明细"]')).toBeNull()
+    expect(document.querySelector('[aria-label="对账单摘要"]')?.textContent).toContain('200.00 CNY')
+    expect(document.querySelectorAll('.statement-summary-grid .statement-summary-item')).toHaveLength(20)
+    expect(document.querySelector('[aria-label="对账单摘要"]')?.textContent).toContain('客户确认人')
+    expect(document.querySelector('[aria-label="对账单摘要"]')?.textContent).toContain('2026-08-05 10:00')
+    expect(document.querySelector('.density-detail-heading')?.textContent).toContain('REC-501')
+    expect(document.querySelector('[aria-label="客户对账单账单明细"]')).toBeTruthy()
+    expect(document.querySelector('.detail-table-scroll [aria-label="客户对账单账单明细"]')).toBeTruthy()
+    expect(document.querySelector('.el-drawer')).toBeNull()
+  })
+
+  it('uses the shared four-group summary grid with long remarks spanning two groups', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/finance/pages/FinanceCustomerStatementsView.vue'), 'utf8')
+    const shared = readFileSync(resolve(process.cwd(), 'src/styles/adminDensity.css'), 'utf8')
+    const moduleCss = readFileSync(resolve(process.cwd(), 'src/modules/finance/financeDensity.css'), 'utf8')
+    expect(source).toContain('class="density-fields statement-summary-grid"')
+    expect(shared).toContain('repeat(4, minmax(0, 1fr))')
+    expect(moduleCss).toContain('.statement-summary-item--remark { grid-column: span 2; }')
+  })
+
+  it('uses entity buttons for row actions and only folds the fourth action into more', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/finance/pages/FinanceCustomerStatementsView.vue'), 'utf8')
+    const actions = source.slice(source.indexOf('<template #actions="{ row }">'), source.indexOf('<template #status="{ row }">'))
+    expect(actions).not.toContain(' link')
+    for (const label of ['详情', '提交', '通过', '驳回', '出账', '调整', '重开']) {
+      const actionLine = actions.split('\n').find((line) => line.includes(`${label}</el-button>`))
+      expect(actionLine).toContain('class="density-action"')
+      expect(actionLine).toContain('size="small"')
+    }
+    expect(actions).toContain('data-tone="danger"')
+    expect(actions).toContain('aria-label="更多对账单操作" title="更多对账单操作"')
+    expect(actions).toContain("row.status === 'PENDING_REVIEW' && canReview && canVoid")
+    expect(actions.match(/<el-dropdown-item/g)).toHaveLength(1)
+    expect(actions).toContain('class="danger-menu-item"')
+  })
+
+  it('keeps three available row actions visible with primary and danger semantics', async () => {
+    const { wrapper } = await mountPage([
+      'platform:finance:customer-statement:list',
+      'platform:finance:reconciliation:adjust',
+      'platform:finance:reconciliation:void',
+    ])
+    const actionButtons = [...document.querySelectorAll('button')].filter((button) => ['详情', '调整', '作废'].includes(button.textContent?.trim() || ''))
+    const detailButton = actionButtons.find((button) => button.textContent?.trim() === '详情')
+    const adjustButton = actionButtons.find((button) => button.textContent?.trim() === '调整')
+    const voidButton = actionButtons.find((button) => button.textContent?.trim() === '作废')
+    expect(new Set(actionButtons.map((button) => button.textContent?.trim()))).toEqual(new Set(['详情', '调整', '作废']))
+    expect(detailButton?.classList).toContain('el-button--small')
+    expect(detailButton?.classList).toContain('density-action')
+    expect(detailButton?.getAttribute('data-tone')).toBe('neutral')
+    expect(adjustButton?.classList).toContain('density-action')
+    expect(voidButton?.getAttribute('data-tone')).toBe('danger')
+
+    const vm = wrapper.vm as unknown as { actionBusy: boolean; adjustBusy: boolean }
+    vm.actionBusy = true
+    vm.adjustBusy = true
+    await flushPromises()
+    expect(adjustButton?.hasAttribute('disabled')).toBe(true)
+    expect(voidButton?.hasAttribute('disabled')).toBe(true)
+  })
+
+  it('keeps the payment history in the desktop detail layout without duplicating a card container', async () => {
+    const { wrapper } = await mountPage()
+    const vm = wrapper.vm as unknown as { openDetail(row: FinanceStatementReadModel): Promise<void>; activeDetailTab: 'lines' | 'payments' }
+    await vm.openDetail(statement)
+    vm.activeDetailTab = 'payments'
+    await flushPromises()
+
+    expect(document.querySelector('[aria-label="客户对账单支付历史"]')?.textContent).toContain('PAY-701')
+    expect(document.querySelectorAll('.statement-detail-page')).toHaveLength(1)
+  })
+
+  it('resolves customer names from the active customer list and never exposes internal customer or operator ids', async () => {
+    const internalCustomerId = '2088123456789'
+    const internalOperatorId = '1000001'
+    vi.mocked(listPlatformTenants).mockResolvedValue({ records: [{ id: internalCustomerId, tenantName: '虫虫跨境科技', status: 'ACTIVE' } as never], page: 1, size: 200, total: 1, pages: 1 })
+    const internalStatement = {
+      ...statement, customerId: internalCustomerId, customerName: `客户${internalCustomerId}`,
+      createdBy: internalOperatorId, createdByName: '', createdAt: '2026-08-14T03:27:34Z', updatedBy: internalOperatorId, updatedByName: '', updatedAt: '2026-08-14T04:28:35Z',
+    }
+    const internalDetail = {
+      ...detail, ...internalStatement,
+      paymentHistory: [{ ...detail.paymentHistory[0]!, createdBy: internalOperatorId, createdByName: '', occurredAt: '2026-08-14T04:28:35Z' }],
+      revisions: [{ ...detail.revisions[0]!, operatorId: internalOperatorId, operatorName: '' }],
+    }
+    vi.mocked(listFinanceStatements).mockResolvedValue([internalStatement])
+    vi.mocked(getReconciliationStatement).mockResolvedValue(internalDetail)
+
+    const { wrapper } = await mountPage(['platform:finance:customer-statement:list', 'platform:customer:list', 'platform:finance:reconciliation:adjust'])
+    await (wrapper.vm as unknown as { openDetail(row: FinanceStatementReadModel): Promise<void> }).openDetail(internalStatement)
+    await flushPromises()
+
+    const text = document.body.textContent || ''
+    expect(text).toContain('虫虫跨境科技')
+    expect(document.querySelector('[aria-label="客户对账单详情"]')?.textContent).toContain('虫虫跨境科技')
+    expect(text).not.toContain(`客户${internalCustomerId}`)
+    expect(text).not.toContain(internalOperatorId)
+    expect(text).toContain('名称数据缺失')
+    expect(text).toContain('2026-08-14 03:27')
+    expect(text).not.toContain('2026-08-14T03:27:34Z')
+
+    await (wrapper.vm as unknown as { openAdjustment(row: FinanceStatementReadModel): Promise<void> }).openAdjustment(internalStatement)
+    await flushPromises()
+    expect(document.body.textContent).toContain('调整客户对账单')
+    expect(document.body.textContent).toContain('运费')
+  })
+
+  it('filters hydrated statements by status, bill number, container, period, settlement and payment date', async () => {
+    const { wrapper } = await mountPage()
+    const vm = wrapper.vm as unknown as { load(model: Record<string, unknown>): Promise<void>; filters: Record<string, unknown>; filteredRows: FinanceStatementReadModel[] }
+    await vm.load({
+      status: 'ISSUED', billNo: '501', customerId: '', containerNo: 'CONT-31',
+      periodStartRange: ['2026-08-01', '2026-08-02'], periodEndRange: ['2026-08-30', '2026-09-01'],
+      settled: 'false', lastPaymentRange: ['2026-08-20', '2026-08-20'],
+    })
+    await flushPromises()
+    expect(vm.filteredRows).toHaveLength(1)
+    vm.filters.containerNo = 'CONT-99'
+    await flushPromises()
+    expect(vm.filteredRows).toHaveLength(1)
+    await vm.load({
+      status: 'ISSUED', billNo: '501', customerId: '', containerNo: 'CONT-99',
+      periodStartRange: ['2026-08-01', '2026-08-02'], periodEndRange: ['2026-08-30', '2026-09-01'],
+      settled: 'false', lastPaymentRange: ['2026-08-20', '2026-08-20'],
+    })
+    await flushPromises()
+    expect(vm.filteredRows).toHaveLength(0)
+  })
+
+  it('does not issue one detail request per statement for an ordinary query', async () => {
+    vi.mocked(listFinanceStatements).mockResolvedValue(Array.from({ length: 60 }, (_, index) => ({
+      ...statement,
+      id: String(501 + index),
+      billNo: `REC-${501 + index}`,
+    })))
+    const { wrapper } = await mountPage()
+    vi.mocked(listFinanceStatements).mockClear()
+    vi.mocked(getReconciliationStatement).mockClear()
+
+    await (wrapper.vm as unknown as { load(model: Record<string, unknown>): Promise<void> }).load({ status: 'ISSUED' })
+    await flushPromises()
+
+    expect(listFinanceStatements).toHaveBeenCalledTimes(1)
+    expect(getReconciliationStatement).not.toHaveBeenCalled()
+  })
+
+  it('uses only the statement list request for an ordinary search', async () => {
+    const { wrapper } = await mountPage()
+    vi.mocked(listFinanceStatements).mockClear()
+    vi.mocked(getReconciliationStatement).mockClear()
+
+    await (wrapper.vm as unknown as { load(model: Record<string, unknown>): Promise<void> }).load({
+      status: 'ISSUED', billNo: '501', customerId: '', containerNo: '',
+      periodStartRange: [], periodEndRange: [], settled: '', lastPaymentRange: [], createdRange: [],
+    })
+
+    expect(listFinanceStatements).toHaveBeenCalledTimes(1)
+    expect(getReconciliationStatement).not.toHaveBeenCalled()
+  })
+
+  it('keeps statement status filter options aligned with the list status column', async () => {
+    const { wrapper } = await mountPage()
+    const vm = wrapper.vm as unknown as {
+      fields: Array<{ key: string; label: string; placeholder?: string; options?: Array<{ label: string; value: string }> }>
+      columns: Array<{ key: string; label: string }>
+    }
+    const statusField = vm.fields.find((field) => field.key === 'status')
+    const statusColumn = vm.columns.find((column) => column.key === 'status')
+    expect(statusField).toMatchObject({ label: '对账单状态', placeholder: '请选择对账单状态' })
+    expect(statusField?.options).toEqual([
+      { label: '草稿', value: 'DRAFT' },
+      { label: '待审核', value: 'PENDING_REVIEW' },
+      { label: '已审核', value: 'APPROVED' },
+      { label: '已驳回', value: 'REJECTED' },
+      { label: '已出账', value: 'ISSUED' },
+      { label: '部分结清', value: 'PARTIALLY_PAID' },
+      { label: '已结清', value: 'PAID' },
+      { label: '已作废', value: 'VOIDED' },
+    ])
+    expect(statusColumn).toEqual({ key: 'status', label: '对账单状态', width: 120, slotName: 'status' })
+  })
+
+  it('creates a formal statement export task with only non-empty filters', async () => {
+    const { wrapper } = await mountPage()
+    const vm = wrapper.vm as unknown as { filters: Record<string, unknown>; exportStatements(): Promise<void> }
+    vm.filters = {
+      status: 'ISSUED', billNo: ' REC-501 ', customerId: '10001', containerNo: ' CONT-31 ',
+      periodStartRange: ['2026-08-01', '2026-08-05'], periodEndRange: [], settled: 'false',
+      lastPaymentRange: ['2026-08-20', '2026-08-21'], createdRange: [],
+    }
+    await (wrapper.vm as unknown as { exportStatements(): Promise<void> }).exportStatements()
+    expect(createPlatformExportTask).toHaveBeenCalledWith({
+      exportType: 'FINANCE_RECONCILIATION_STATEMENT_LIST', format: 'XLSX', taskName: '客户对账单',
+      parameters: {
+        customerId: '10001', status: 'ISSUED', billNo: 'REC-501', containerNo: 'CONT-31',
+        periodStartFrom: '2026-08-01', periodStartTo: '2026-08-05', settled: false,
+        lastPaymentFrom: '2026-08-20', lastPaymentTo: '2026-08-21',
+      },
+    })
+    expect(showExportTaskCreatedDialog).toHaveBeenCalledWith({ taskName: '客户对账单', taskNo: 'EXP-STMT-1', dense: true })
+    expect(getReconciliationStatement).not.toHaveBeenCalledWith('501')
+    expect(URL.createObjectURL).not.toHaveBeenCalled()
+  })
+
+  it('requires both statement export and download-center list permissions for the export action', async () => {
+    await mountPage(['platform:finance:customer-statement:list', 'platform:finance:customer-statement:export'])
+    expect([...document.querySelectorAll('button')].some((item) => item.textContent?.includes('导出'))).toBe(false)
+
+    document.body.innerHTML = ''
+    await mountPage(['platform:finance:customer-statement:list', 'platform:finance:customer-statement:export', 'platform:download:list'])
+    expect([...document.querySelectorAll('button')].some((item) => item.textContent?.includes('导出'))).toBe(true)
+  })
+
+  it('disables statement generation when customer selection permission is missing', async () => {
+    vi.mocked(listPlatformTenants).mockClear()
+    await mountPage(['platform:finance:customer-statement:list', 'platform:finance:reconciliation:create'])
+    const button = [...document.querySelectorAll('button')].find((item) => item.textContent?.includes('生成对账单'))
+    expect(button).toBeTruthy()
+    expect(button?.disabled).toBe(true)
+    expect(listPlatformTenants).not.toHaveBeenCalled()
+  })
+
+  it('accepts selected fee sources from customer arap and creates them in the statement page', async () => {
+    const permissions = [
+      'platform:finance:customer-statement:list',
+      'platform:finance:customer-arap:list',
+      'platform:finance:reconciliation:create',
+      'platform:customer:list',
+    ]
+    const { wrapper, router } = await mountPage(permissions, '/finance/customer-statements?createMode=SELECTED&customerId=10001&feeSourceIds=42&periodStart=2026-08-15&periodEnd=2026-08-15')
+    const vm = wrapper.vm as unknown as {
+      createOpen: boolean
+      createForm: { generationMode: string; customerId: string; feeSourceIds: string[]; periodStart: string; periodEnd: string }
+      createStatement(): Promise<void>
+    }
+    expect(vm.createOpen).toBe(true)
+    expect(vm.createForm).toMatchObject({ generationMode: 'SELECTED', customerId: '10001', feeSourceIds: ['42'], periodStart: '2026-08-15', periodEnd: '2026-08-15' })
+    expect(listFinanceFeeSources).toHaveBeenCalledWith(expect.objectContaining({
+      customerId: '10001', direction: 'RECEIVABLE', status: 'AVAILABLE', reviewStatus: 'APPROVED', statementGenerated: false,
+      businessDateFrom: '2026-08-15', businessDateTo: '2026-08-15',
+    }))
+
+    await vm.createStatement()
+    expect(createReconciliationStatement).toHaveBeenCalledWith({
+      customerId: '10001', currency: 'CNY', generationMode: 'SELECTED', feeSourceIds: ['42'],
+      periodStart: '2026-08-15', periodEnd: '2026-08-15', remark: undefined,
+    })
+    expect(router.currentRoute.value).toMatchObject({ name: 'finance-customer-statement-detail', params: { statementId: '502' } })
+  })
+
+  it('keeps the generation dialog open with a customer-friendly message when no billable fees exist', async () => {
+    const permissions = ['platform:finance:customer-statement:list', 'platform:finance:reconciliation:create', 'platform:customer:list']
+    const { wrapper } = await mountPage(permissions)
+    const vm = wrapper.vm as unknown as {
+      createOpen: boolean
+      createError: { message: string } | null
+      createForm: { customerId: string; periodStart: string; periodEnd: string; generationMode: string; feeSourceIds: string[] }
+      openCreate(): void
+      createStatement(): Promise<void>
+    }
+    vm.openCreate()
+    vm.createForm.customerId = '10001'
+    vm.createForm.generationMode = 'BY_CUTOFF'
+    vm.createForm.periodStart = '2026-08-01'
+    vm.createForm.periodEnd = '2026-08-25'
+    vi.mocked(createReconciliationStatement).mockRejectedValueOnce(new ApiResponseError('没有符合结算条件的CNY应收费用来源', 'FIN_409'))
+
+    await vm.createStatement()
+    await flushPromises()
+    expect(vm.createOpen).toBe(true)
+    expect(vm.createError?.message).toContain('没有可生成的应收费用')
+    expect(document.body.textContent).toContain('请调整账期或选择其他客户后重试')
+  })
+
+  it('uses statement detail snapshots without a second fee-source request or technical trace fields', async () => {
+    const { wrapper } = await mountPage(['platform:finance:customer-statement:list'])
+    await (wrapper.vm as unknown as { openDetail(row: FinanceStatementReadModel): Promise<void> }).openDetail(statement)
+    await flushPromises()
+    expect(document.body.textContent).toContain('CONT-31')
+    expect(document.body.textContent).toContain('订单 11')
+    expect(document.body.textContent).not.toContain('hash-81')
+  })
+
+  it('surfaces container-filter detail hydration failures instead of silently returning an empty filtered list', async () => {
+    const { wrapper } = await mountPage()
+    vi.mocked(getReconciliationStatement).mockRejectedValueOnce(new Error('detail unavailable'))
+    await (wrapper.vm as unknown as { load(model: Record<string, unknown>): Promise<void> }).load({ status: 'ISSUED', containerNo: 'CONT-31' })
+    await flushPromises()
+    expect(document.body.textContent).toContain('筛选字段加载失败')
+  })
+
+  it('keeps the dedicated detail route visible and exposes a retry state', async () => {
+    vi.mocked(getReconciliationStatement).mockRejectedValueOnce(new Error('detail unavailable'))
+    const { router } = await mountPage(['platform:finance:customer-statement:list'], '/finance/customer-statements/501')
+    await flushPromises()
+    expect(router.currentRoute.value.name).toBe('finance-customer-statement-detail')
+    expect(document.querySelector('[aria-label="客户对账单详情"]')).toBeTruthy()
+    expect(document.body.textContent).toContain('返回客户对账单')
+    expect(document.body.textContent).toContain('明细加载失败')
+    expect(document.body.textContent).toContain('重试')
+  })
+})
diff --git a/src/modules/finance/pages/FinanceCustomerStatementsView.vue b/src/modules/finance/pages/FinanceCustomerStatementsView.vue
new file mode 100644
index 00000000..d37e0db0
--- /dev/null
+++ b/src/modules/finance/pages/FinanceCustomerStatementsView.vue
@@ -0,0 +1,761 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import '../financeDensity.css'
+import { computed, onMounted, ref, watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import { ArrowLeft, Download, MoreHorizontal, Plus } from '@lucide/vue'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { createPlatformExportTask } from '@/modules/downloads'
+import { listPlatformTenants, type PlatformTenantResource } from '@/modules/iam'
+import { getApiErrorDetails, getApiErrorMessage, type ApiErrorDetails } from '@/shared/api/http'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import DetailPageLayout from '@/shared/components/DetailPageLayout.vue'
+import FormSection from '@/shared/components/FormSection.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import { showExportTaskCreatedDialog } from '@/shared/components/exportTaskCreatedDialog'
+import { actionReconciliationStatement, createReconciliationStatement, getReconciliationStatement, listFinanceFeeSources, listFinanceStatements } from '../api/finance'
+import { financeBillStatusOptions, financeSourceTypeLabel, financeStatusLabel, financeStatusTone } from '../status'
+import type { FinanceFeeSourceSummary, FinanceReconciliationDetail, FinanceStatementReadModel, ReconciliationActionPayload } from '../types'
+
+interface AdjustmentRow {
+  selected: boolean
+  statementLineId: string
+  feeItemName: string
+  originalAmount: number
+  adjustedAmount: number
+  reason: string
+}
+
+type StatementRow = Omit<FinanceStatementReadModel, 'creditDays' | 'settled'> & {
+  periodStart: string
+  periodEnd: string
+  creditDays: number | null
+  settled: boolean | null
+  lastPaymentAt: string
+  remark: string
+}
+
+const access = useAccessPreviewStore()
+const route = useRoute()
+const router = useRouter()
+const customers = ref<PlatformTenantResource[]>([])
+const filters = ref<QueryModel>({
+  status: '', billNo: '', customerId: '', containerNo: '', periodStartRange: [], periodEndRange: [],
+  settled: '', lastPaymentRange: [], createdRange: [],
+})
+const appliedFilters = ref<QueryModel>({ ...filters.value })
+const rows = ref<StatementRow[]>([])
+const page = ref(1)
+const pageSize = ref(20)
+const loading = ref(false)
+const error = ref<ApiErrorDetails | null>(null)
+const customerError = ref<ApiErrorDetails | null>(null)
+const selectedId = ref('')
+const detail = ref<FinanceReconciliationDetail | null>(null)
+const detailLoading = ref(false)
+const detailError = ref<ApiErrorDetails | null>(null)
+const activeDetailTab = ref<'lines' | 'payments'>('lines')
+const detailCache = new Map<string, FinanceReconciliationDetail>()
+const createOpen = ref(false)
+const createBusy = ref(false)
+const createSourcesLoading = ref(false)
+const createSourcesError = ref<ApiErrorDetails | null>(null)
+const createError = ref<ApiErrorDetails | null>(null)
+const createSourceOptions = ref<FinanceFeeSourceSummary[]>([])
+const exportBusy = ref(false)
+const actionBusy = ref(false)
+const createForm = ref({
+  generationMode: 'BY_CUTOFF' as 'BY_CUTOFF' | 'SELECTED',
+  customerId: '',
+  periodStart: new Date().toISOString().slice(0, 8) + '01',
+  periodEnd: new Date().toISOString().slice(0, 10),
+  feeSourceIds: [] as string[],
+  remark: '',
+})
+let createSourceLoadSequence = 0
+const adjustOpen = ref(false)
+const adjustBusy = ref(false)
+const adjustStatement = ref<FinanceStatementReadModel | null>(null)
+const adjustReason = ref('')
+const adjustLines = ref<AdjustmentRow[]>([])
+
+const canView = computed(() => access.can('platform:finance:customer-statement:list'))
+const canListCustomers = computed(() => access.can('platform:customer:list'))
+const canViewFeeSource = computed(() => access.can('platform:finance:customer-statement:list'))
+const canSelectSources = computed(() => access.can('platform:finance:customer-arap:list'))
+const canCreate = computed(() => access.can('platform:finance:reconciliation:create'))
+const activeCustomers = computed(() => customers.value.filter((item) => item.status === 'ACTIVE'))
+const canReview = computed(() => access.can('platform:finance:reconciliation:review'))
+const canIssue = computed(() => access.can('platform:finance:reconciliation:issue'))
+const canAdjust = computed(() => access.can('platform:finance:reconciliation:adjust'))
+const canVoid = computed(() => access.can('platform:finance:reconciliation:void'))
+const canExport = computed(() => access.can('platform:finance:customer-statement:export') && access.can('platform:download:list'))
+const canGenerate = computed(() => canCreate.value && canListCustomers.value)
+const selectedCreateSources = computed(() => createSourceOptions.value.filter((item) => createForm.value.feeSourceIds.includes(item.feeSourceId)))
+const selectedCreateAmount = computed(() => selectedCreateSources.value.reduce((total, item) => total + Number(item.amount || 0), 0))
+const detailRouteId = computed(() => route.name === 'finance-customer-statement-detail' ? String(route.params.statementId || '') : '')
+const isDetailRoute = computed(() => Boolean(detailRouteId.value))
+const fields = computed<QueryField[]>(() => [
+  { key: 'status', type: 'select', label: '对账单状态', width: 180, placeholder: '请选择对账单状态', options: financeBillStatusOptions },
+  { key: 'billNo', type: 'input', label: '对账单号', width: 210, placeholder: '请输入对账单号' },
+  { key: 'customerId', type: 'select', label: '客户名称', width: 260, placeholder: '请选择客户', props: { filterable: true, clearable: true }, options: customers.value.filter((item) => item.status === 'ACTIVE').map((item) => ({ label: item.tenantName, value: String(item.id) })) },
+  { key: 'containerNo', type: 'input', label: '柜次号', width: 190, placeholder: canViewFeeSource.value ? '请输入柜次号' : '缺少费用来源查看权限', props: { disabled: !canViewFeeSource.value } },
+  { key: 'periodStartRange', type: 'daterange', label: '结算起始日', width: 280, props: { valueFormat: 'YYYY-MM-DD', startPlaceholder: '请选择开始日期', endPlaceholder: '请选择结束日期' } },
+  { key: 'periodEndRange', type: 'daterange', label: '结算结束日', width: 280, props: { valueFormat: 'YYYY-MM-DD', startPlaceholder: '请选择开始日期', endPlaceholder: '请选择结束日期' } },
+  { key: 'settled', type: 'select', label: '是否结清', width: 160, placeholder: '请选择结清状态', options: [{ label: '是', value: 'true' }, { label: '否', value: 'false' }] },
+  { key: 'lastPaymentRange', type: 'daterange', label: '最后收款时间', width: 280, props: { valueFormat: 'YYYY-MM-DD', startPlaceholder: '请选择开始日期', endPlaceholder: '请选择结束日期' } },
+  { key: 'createdRange', type: 'daterange', label: '创建日期', width: 280, props: { valueFormat: 'YYYY-MM-DD', startPlaceholder: '请选择开始日期', endPlaceholder: '请选择结束日期' } },
+])
+const columns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 280, fixed: 'left', slotName: 'actions' },
+  { key: 'status', label: '对账单状态', width: 120, slotName: 'status' },
+  { key: 'customerConfirmationStatus', label: '客户确认', width: 130, slotName: 'customerConfirmationStatus' },
+  { key: 'billNo', label: '对账单号', minWidth: 180 },
+  { key: 'customerName', label: '客户', minWidth: 180, slotName: 'customerName' },
+  { key: 'periodStart', label: '结算起始日', width: 130 },
+  { key: 'periodEnd', label: '结算结束日', width: 130 },
+  { key: 'creditDays', label: '账期(天)', width: 100 },
+  { key: 'lineCount', label: '费用明细数', width: 110 },
+  { key: 'sourceCount', label: '来源数量', width: 100 },
+  { key: 'currency', label: '货币', width: 86 },
+  { key: 'sourceAmount', label: '调整前金额(CNY)', width: 150 },
+  { key: 'adjustmentAmount', label: '调整金额(CNY)', width: 145 },
+  { key: 'totalAmount', label: '总应收金额(CNY)', width: 155 },
+  { key: 'receivedAmount', label: '已收金额(CNY)', width: 145 },
+  { key: 'outstandingAmount', label: '未收金额(CNY)', width: 145 },
+  { key: 'lastPaymentAt', label: '最后收款时间', minWidth: 170, slotName: 'lastPaymentAt' },
+  { key: 'settled', label: '是否结清', width: 100, slotName: 'settled' },
+  { key: 'remark', label: '备注', minWidth: 180 },
+  { key: 'createdByName', label: '创建人', width: 130, slotName: 'createdByName' },
+  { key: 'createdAt', label: '创建时间', minWidth: 170, slotName: 'createdAt' },
+  { key: 'submittedAt', label: '提交时间', minWidth: 170, slotName: 'submittedAt' },
+  { key: 'reviewedAt', label: '审核时间', minWidth: 170, slotName: 'reviewedAt' },
+  { key: 'issuedAt', label: '出账时间', minWidth: 170, slotName: 'issuedAt' },
+  { key: 'customerConfirmedByName', label: '客户确认人', width: 140, slotName: 'customerConfirmedByName' },
+  { key: 'customerConfirmedAt', label: '客户确认时间', minWidth: 170, slotName: 'customerConfirmedAt' },
+  { key: 'updatedByName', label: '更新人', width: 130, slotName: 'updatedByName' },
+  { key: 'updatedAt', label: '更新时间', minWidth: 170, slotName: 'updatedAt' },
+]
+const detailLineColumns: DataTableColumn[] = [
+  { key: 'direction', label: '方向', width: 90, slotName: 'direction' },
+  { key: 'sourceType', label: '来源类型', width: 120, slotName: 'sourceType' },
+  { key: 'sourceNo', label: '业务单号', minWidth: 160 },
+  { key: 'orderId', label: '订单', minWidth: 150, slotName: 'orderId' },
+  { key: 'inboundCode', label: '入仓号', minWidth: 150, slotName: 'inboundCode' },
+  { key: 'containerNo', label: '柜次号', minWidth: 150, slotName: 'containerNo' },
+  { key: 'businessDate', label: '业务发生日', width: 130, slotName: 'businessDate' },
+  { key: 'feeItemName', label: '费用项目', minWidth: 160 },
+  { key: 'quantity', label: '计费量', width: 110, slotName: 'quantity' },
+  { key: 'unitPrice', label: '单价(CNY)', width: 120, slotName: 'unitPrice' },
+  { key: 'sourceAmount', label: '来源金额(CNY)', width: 150 },
+  { key: 'amount', label: '账单金额(CNY)', width: 150 },
+  { key: 'adjustmentReason', label: '调整说明', minWidth: 190 },
+  { key: 'billNo', label: '对账单号', minWidth: 190, slotName: 'billNo' },
+  { key: 'periodStart', label: '结算起始日', width: 130, slotName: 'periodStart' },
+  { key: 'periodEnd', label: '结算结束日', width: 130, slotName: 'periodEnd' },
+]
+const paymentColumns: DataTableColumn[] = [
+  { key: 'customerName', label: '客户', minWidth: 200, slotName: 'customerName' },
+  { key: 'transactionDate', label: '支付日期', width: 130, slotName: 'transactionDate' },
+  { key: 'amount', label: '支付金额(CNY)', width: 150 },
+  { key: 'method', label: '支付方式', width: 130, slotName: 'method' },
+  { key: 'referenceNo', label: '支付流水号', minWidth: 180 },
+  { key: 'voucherFileIds', label: '收款凭证', minWidth: 130, slotName: 'voucherFileIds' },
+  { key: 'createdByName', label: '登记人', minWidth: 140, slotName: 'createdByName' },
+  { key: 'occurredAt', label: '登记时间', width: 170, slotName: 'occurredAt' },
+  { key: 'remark', label: '备注', minWidth: 200 },
+]
+
+const customerNameById = computed(() => new Map(customers.value.map((item) => [String(item.id), item.tenantName.trim()])))
+
+function isInternalCustomerLabel(value: string, customerId: string) {
+  const normalized = value.replaceAll(' ', '')
+  return normalized === customerId || /^客户(?:ID)?\d+$/.test(normalized)
+}
+
+function customerDisplayName(customerId: string, value?: string) {
+  const resolved = customerNameById.value.get(String(customerId))
+  if (resolved) return resolved
+  const candidate = String(value || '').trim()
+  return candidate && !isInternalCustomerLabel(candidate, String(customerId)) ? candidate : '客户名称未提供'
+}
+
+function operatorDisplayName(value?: string) {
+  const candidate = String(value || '').trim()
+  if (!candidate || /^(?:operator-)?\d+$/i.test(candidate)) return '名称数据缺失'
+  return candidate
+}
+
+function formatDateTime(value?: string) {
+  return value ? value.replace('T', ' ').replace(/Z$/, '').slice(0, 16) : '—'
+}
+
+function detailToRow(row: FinanceStatementReadModel, current?: FinanceReconciliationDetail): StatementRow {
+  const latestPayment = current?.paymentHistory.map((item) => item.occurredAt || item.transactionDate).filter(Boolean).sort().at(-1) || row.lastReceiptAt || ''
+  return {
+    ...row,
+    periodStart: current?.periodStart || row.periodStart || '', periodEnd: current?.periodEnd || row.periodEnd || row.billDate,
+    creditDays: current ? current.creditDays : row.creditDays ?? null, settled: current ? current.settled : row.settled ?? null,
+    lastPaymentAt: latestPayment, remark: current?.remark || row.remark || '',
+    createdBy: current?.createdBy || row.createdBy, createdByName: current?.createdByName || row.createdByName, createdAt: current?.createdAt || row.createdAt,
+    updatedBy: current?.updatedBy || row.updatedBy, updatedByName: current?.updatedByName || row.updatedByName, updatedAt: current?.updatedAt || row.updatedAt,
+  }
+}
+
+function stringFilter(key: string) { return String(appliedFilters.value[key] || '').trim().toLowerCase() }
+function inDateRange(value: string, key: string) {
+  const range = appliedFilters.value[key]
+  if (!Array.isArray(range) || range.length < 2 || !value) return !Array.isArray(range) || range.length < 2
+  const date = value.slice(0, 10)
+  return date >= String(range[0]) && date <= String(range[1])
+}
+const filteredRows = computed(() => rows.value.filter((row) => {
+  const status = stringFilter('status')
+  const billNo = stringFilter('billNo')
+  const settled = stringFilter('settled')
+  const containerNo = stringFilter('containerNo')
+  const current = detailCache.get(row.id)
+  return (!status || String(row.status).toLowerCase() === status)
+    && (!billNo || row.billNo.toLowerCase().includes(billNo))
+    && (!settled || String(row.settled) === settled)
+    && (!containerNo || Boolean(current?.lines.some((line) => line.containerNo?.toLowerCase().includes(containerNo))))
+    && inDateRange(row.periodStart, 'periodStartRange')
+    && inDateRange(row.periodEnd, 'periodEndRange')
+    && inDateRange(row.lastPaymentAt, 'lastPaymentRange')
+    && inDateRange(row.createdAt || '', 'createdRange')
+}))
+const paginatedRows = computed(() => {
+  const start = (page.value - 1) * pageSize.value
+  return filteredRows.value.slice(start, start + pageSize.value)
+})
+
+async function loadCustomers() {
+  if (!canListCustomers.value) return
+  customerError.value = null
+  try {
+    const records: PlatformTenantResource[] = []; let currentPage = 1; let pages = 1
+    do { const result = await listPlatformTenants({ page: currentPage, size: 200, status: 'ACTIVE' }); records.push(...result.records); pages = Math.max(1, result.pages); currentPage += 1 } while (currentPage <= pages)
+    customers.value = records
+  } catch (cause) {
+    customerError.value = getApiErrorDetails(cause, '客户列表加载失败')
+  }
+}
+
+async function load(model?: QueryModel) {
+  // The list response already contains every normal filter field. Only the
+  // container-number filter still depends on statement lines from the detail API.
+  // Avoid loading every statement detail for an ordinary search (N+1 requests).
+  const hydrateDetails = Boolean(String(model?.containerNo || '').trim())
+  if (model) {
+    filters.value = { ...model }
+    appliedFilters.value = { ...model }
+    page.value = 1
+  }
+  rows.value = []
+  selectedId.value = ''
+  detail.value = null
+  detailCache.clear()
+  error.value = null
+  loading.value = true
+  try {
+    const statements = await listFinanceStatements(String(appliedFilters.value.customerId || '').trim() || undefined)
+    const detailErrors: ApiErrorDetails[] = []
+    const hydrated = await Promise.all(statements.map(async (row) => {
+      if (!hydrateDetails) return detailToRow(row)
+      try {
+        const current = await getReconciliationStatement(row.id)
+        detailCache.set(row.id, current)
+        return detailToRow(row, current)
+      } catch (cause) {
+        detailErrors.push(getApiErrorDetails(cause, `对账单 ${row.billNo || row.id} 的筛选字段加载失败`))
+        return detailToRow(row)
+      }
+    }))
+    if (detailErrors.length) {
+      error.value = detailErrors[0]!
+      return
+    }
+    rows.value = hydrated
+  } catch (cause) {
+    error.value = getApiErrorDetails(cause, '客户对账单加载失败，请重试')
+  } finally {
+    loading.value = false
+  }
+}
+
+async function fetchDetail(statementId: string, force = false) {
+  if (!force && detailCache.has(statementId)) return detailCache.get(statementId)!
+  const current = await getReconciliationStatement(statementId)
+  detailCache.set(statementId, current)
+  return current
+}
+
+async function loadDetail(statementId: string) {
+  selectedId.value = statementId
+  detail.value = null
+  detailError.value = null
+  detailLoading.value = true
+  try {
+    detail.value = await fetchDetail(statementId, true)
+  } catch (cause) {
+    detailError.value = getApiErrorDetails(cause, '对账单明细加载失败，请重试')
+  } finally {
+    detailLoading.value = false
+  }
+}
+
+async function openDetail(row: FinanceStatementReadModel) {
+  await router.push({ name: 'finance-customer-statement-detail', params: { statementId: row.id } })
+}
+
+function retrySelectedDetail() {
+  if (selectedId.value) void loadDetail(selectedId.value)
+}
+
+async function returnToList() {
+  await router.push({ name: 'finance-customer-statements' })
+}
+
+function paymentMethodLabel(method: string) {
+  return ({ BANK_TRANSFER: '银行转账', CASH: '现金', OTHER: '其他' } as Record<string, string>)[method] || method || '—'
+}
+
+function revisionActionLabel(action: string) {
+  return ({ SUBMIT: '提交审核', APPROVE: '审核通过', REJECT: '审核驳回', ISSUE: '出账', ADJUST: '调整', VOID: '作废', REOPEN: '重开' } as Record<string, string>)[action] || action || '—'
+}
+
+function revisionTime(actions: string[]) {
+  return detail.value?.revisions.filter((item) => actions.includes(item.action)).map((item) => item.occurredAt).sort().at(-1) || ''
+}
+
+function detailSourceAmount() {
+  return detail.value?.lines.reduce((total, line) => total + (line.sourceAmount ?? line.amount), 0) ?? 0
+}
+
+async function exportStatements() {
+  const customerId = String(filters.value.customerId || '').trim()
+  if (customerId && !/^[1-9]\d*$/.test(customerId)) return ElMessage.error('客户业务标识无效，无法创建导出任务')
+  const parameters: Record<string, string | boolean> = {}
+  const putText = (key: string) => {
+    const value = String(filters.value[key] || '').trim()
+    if (value) parameters[key] = value
+  }
+  const putRange = (sourceKey: string, fromKey: string, toKey: string) => {
+    const value = filters.value[sourceKey]
+    if (!Array.isArray(value)) return
+    if (value[0]) parameters[fromKey] = String(value[0])
+    if (value[1]) parameters[toKey] = String(value[1])
+  }
+  if (customerId) parameters.customerId = customerId
+  putText('status')
+  putText('billNo')
+  putText('containerNo')
+  putRange('periodStartRange', 'periodStartFrom', 'periodStartTo')
+  putRange('periodEndRange', 'periodEndFrom', 'periodEndTo')
+  putRange('lastPaymentRange', 'lastPaymentFrom', 'lastPaymentTo')
+  putRange('createdRange', 'createdFrom', 'createdTo')
+  const settled = String(filters.value.settled || '')
+  if (settled) parameters.settled = settled === 'true'
+
+  exportBusy.value = true
+  try {
+    const task = await createPlatformExportTask({
+      exportType: 'FINANCE_RECONCILIATION_STATEMENT_LIST',
+      format: 'XLSX',
+      taskName: '客户对账单',
+      parameters,
+    })
+    const openDownloadCenter = await showExportTaskCreatedDialog({ taskName: task.taskName, taskNo: task.taskNo, dense: true })
+    if (openDownloadCenter) await router.push({ name: 'download-center' })
+  } catch (cause) {
+    ElMessage.error(getApiErrorMessage(cause, '客户对账单导出任务创建失败'))
+  } finally {
+    exportBusy.value = false
+  }
+}
+
+function defaultCreateForm() {
+  return {
+    generationMode: 'BY_CUTOFF' as 'BY_CUTOFF' | 'SELECTED',
+    customerId: '',
+    periodStart: new Date().toISOString().slice(0, 8) + '01',
+    periodEnd: new Date().toISOString().slice(0, 10),
+    feeSourceIds: [] as string[],
+    remark: '',
+  }
+}
+
+function openCreate() {
+  if (!canListCustomers.value) return ElMessage.warning('缺少客户列表权限，无法选择客户生成对账单')
+  createForm.value = defaultCreateForm()
+  createSourceOptions.value = []
+  createSourcesError.value = null
+  createError.value = null
+  createOpen.value = true
+}
+
+async function loadEligibleCreateSources(preferredIds: string[] = createForm.value.feeSourceIds) {
+  const sequence = ++createSourceLoadSequence
+  createSourcesError.value = null
+  createSourceOptions.value = []
+  if (createForm.value.generationMode !== 'SELECTED' || !createForm.value.customerId
+    || !createForm.value.periodStart || !createForm.value.periodEnd || !canSelectSources.value) {
+    createForm.value.feeSourceIds = []
+    return
+  }
+  createSourcesLoading.value = true
+  try {
+    const records: FinanceFeeSourceSummary[] = []
+    let currentPage = 1
+    let pages = 1
+    do {
+      const result = await listFinanceFeeSources({
+        page: currentPage,
+        size: 200,
+        customerId: createForm.value.customerId,
+        direction: 'RECEIVABLE',
+        status: 'AVAILABLE',
+        reviewStatus: 'APPROVED',
+        statementGenerated: false,
+        businessDateFrom: createForm.value.periodStart,
+        businessDateTo: createForm.value.periodEnd,
+      })
+      records.push(...result.records)
+      pages = Math.max(1, result.pages)
+      currentPage += 1
+    } while (currentPage <= pages)
+    if (sequence !== createSourceLoadSequence) return
+    createSourceOptions.value = records.filter((item) => item.direction === 'RECEIVABLE'
+      && item.reviewStatus === 'APPROVED' && item.status === 'AVAILABLE'
+      && !item.statementGenerated && item.amount > 0)
+    const availableIds = new Set(createSourceOptions.value.map((item) => item.feeSourceId))
+    createForm.value.feeSourceIds = preferredIds.filter((id) => availableIds.has(id))
+    if (preferredIds.length && createForm.value.feeSourceIds.length !== preferredIds.length) {
+      ElMessage.warning('部分带入费用已被占用或不再符合生成条件，请重新核对')
+    }
+  } catch (cause) {
+    if (sequence !== createSourceLoadSequence) return
+    createSourcesError.value = getApiErrorDetails(cause, '可生成费用加载失败')
+    createForm.value.feeSourceIds = []
+  } finally {
+    if (sequence === createSourceLoadSequence) createSourcesLoading.value = false
+  }
+}
+
+function queryText(value: unknown) {
+  return Array.isArray(value) ? String(value[0] || '') : String(value || '')
+}
+
+async function openSelectedCreateFromRoute() {
+  if (route.name !== 'finance-customer-statements' || queryText(route.query.createMode) !== 'SELECTED') return
+  if (!canGenerate.value || !canSelectSources.value) {
+    ElMessage.warning('缺少客户或费用来源权限，无法生成所选对账单')
+    return
+  }
+  const feeSourceIds = queryText(route.query.feeSourceIds).split(',').map((value) => value.trim()).filter((value) => /^[1-9]\d*$/.test(value))
+  const customerId = queryText(route.query.customerId)
+  const periodStart = queryText(route.query.periodStart)
+  const periodEnd = queryText(route.query.periodEnd)
+  if (!customerId || !feeSourceIds.length || !/^\d{4}-\d{2}-\d{2}$/.test(periodStart) || !/^\d{4}-\d{2}-\d{2}$/.test(periodEnd)) {
+    ElMessage.warning('带入的对账单生成参数不完整，请重新选择费用')
+    return
+  }
+  if (!activeCustomers.value.some((item) => String(item.id) === customerId)) {
+    ElMessage.warning('带入费用所属客户当前不可用，请重新选择费用')
+    return
+  }
+  createForm.value = { generationMode: 'SELECTED', customerId, periodStart, periodEnd, feeSourceIds: [], remark: '' }
+  await loadEligibleCreateSources(feeSourceIds)
+  createOpen.value = true
+  await router.replace({ name: 'finance-customer-statements' })
+}
+
+async function createStatement() {
+  if (!createForm.value.customerId) return ElMessage.warning('请先选择客户')
+  if (!createForm.value.periodStart || !createForm.value.periodEnd) return ElMessage.warning('请选择完整账期')
+  if (createForm.value.periodStart > createForm.value.periodEnd) return ElMessage.warning('账期开始日期不能晚于结束日期')
+  if (createForm.value.generationMode === 'SELECTED' && !createForm.value.feeSourceIds.length) return ElMessage.warning('请选择至少一笔应收费用')
+  createBusy.value = true
+  try {
+    const created = await createReconciliationStatement({
+      customerId: String(createForm.value.customerId),
+      currency: 'CNY',
+      generationMode: createForm.value.generationMode,
+      feeSourceIds: createForm.value.generationMode === 'SELECTED' ? createForm.value.feeSourceIds : undefined,
+      periodStart: createForm.value.periodStart,
+      periodEnd: createForm.value.periodEnd,
+      remark: createForm.value.remark || undefined,
+    })
+    createOpen.value = false
+    ElMessage.success('对账单已生成')
+    await router.push({ name: 'finance-customer-statement-detail', params: { statementId: created.id } })
+  } catch (cause) {
+    const details = getApiErrorDetails(cause, '创建对账单失败')
+    const noEligibleSources = details.code === 'FIN_409' && /没有符合结算条件|没有可生成/.test(details.message)
+    createError.value = noEligibleSources
+      ? { ...details, message: '当前客户在所选账期内没有可生成的应收费用，请调整账期或选择其他客户后重试' }
+      : details
+  }
+  finally { createBusy.value = false }
+}
+
+async function performAction(row: FinanceStatementReadModel, actionName: ReconciliationActionPayload['action']) {
+  const reason = ['REJECT', 'VOID', 'REOPEN'].includes(actionName)
+    ? await ElMessageBox.prompt('请输入操作原因', '对账单操作', { customClass: 'admin-density-confirm', inputType: 'textarea', inputPattern: /\S+/, inputErrorMessage: '操作原因不能为空', confirmButtonText: '确认', cancelButtonText: '取消' }).then((result) => result.value).catch(() => null)
+    : undefined
+  if (reason === null) return
+  actionBusy.value = true
+  try {
+    await actionReconciliationStatement(row.id, { action: actionName, expectedVersion: row.version, ...(reason ? { reason } : {}) })
+    ElMessage.success('对账单状态已更新')
+    await load(appliedFilters.value)
+  } catch (cause) { error.value = getApiErrorDetails(cause, '对账单操作失败') }
+  finally { actionBusy.value = false }
+}
+
+async function openAdjustment(row: FinanceStatementReadModel) {
+  adjustBusy.value = true
+  try {
+    const current = await fetchDetail(row.id, true)
+    adjustStatement.value = { ...row, version: current.version }
+    adjustReason.value = ''
+    adjustLines.value = current.lines.flatMap((line) => line.statementLineId ? [{ selected: false, statementLineId: line.statementLineId, feeItemName: line.feeItemName, originalAmount: line.amount, adjustedAmount: line.amount, reason: '' }] : [])
+    adjustOpen.value = true
+  } catch (cause) { error.value = getApiErrorDetails(cause, '调整明细加载失败') }
+  finally { adjustBusy.value = false }
+}
+
+async function submitAdjustment() {
+  const statement = adjustStatement.value
+  const selected = adjustLines.value.filter((line) => line.selected)
+  if (!statement || !adjustReason.value.trim() || !selected.length) return ElMessage.warning('请填写调整原因并至少选择一条明细')
+  if (selected.some((line) => line.adjustedAmount <= 0 || !line.reason.trim())) return ElMessage.warning('请填写所选明细的新金额和调整说明')
+  adjustBusy.value = true
+  try {
+    await actionReconciliationStatement(statement.id, {
+      action: 'ADJUST', reason: adjustReason.value.trim(), expectedVersion: statement.version,
+      adjustmentLines: selected.map((line) => ({ statementLineId: line.statementLineId, adjustedAmount: line.adjustedAmount, reason: line.reason.trim() })),
+    })
+    adjustOpen.value = false
+    ElMessage.success('对账单调整已保存')
+    await load(appliedFilters.value)
+    await openDetail(statement)
+  } catch (cause) { error.value = getApiErrorDetails(cause, '对账单调整失败') }
+  finally { adjustBusy.value = false }
+}
+
+onMounted(async () => {
+  if (canListCustomers.value) await loadCustomers()
+  await openSelectedCreateFromRoute()
+})
+watch(
+  () => [createOpen.value, createForm.value.generationMode, createForm.value.customerId, createForm.value.periodStart, createForm.value.periodEnd],
+  ([open, mode]) => {
+    if (!open || mode !== 'SELECTED') return
+    void loadEligibleCreateSources()
+  },
+)
+watch(detailRouteId, (statementId) => {
+  if (statementId) void loadDetail(statementId)
+  else {
+    selectedId.value = ''
+    detail.value = null
+    detailError.value = null
+    void load()
+  }
+}, { immediate: true })
+</script>
+
+<template>
+  <AdminPage as="div" class="finance-statements-page admin-density" spacing="normal">
+    <el-result v-if="!canView" icon="warning" title="无权访问客户对账单" sub-title="请联系管理员开通财务查看权限" />
+    <DetailPageLayout v-else-if="isDetailRoute" class="surface-panel statement-detail-page finance-density-detail" aria-label="客户对账单详情">
+      <template #header><div class="density-detail-header"><div class="density-detail-heading"><el-button link class="density-back" @click="returnToList"><ArrowLeft :size="16" />返回客户对账单</el-button><h1 class="density-detail-title">{{ detail?.billNo || '—' }}</h1><StatusBadge v-if="detail" :status="financeStatusLabel(detail.status)" /></div></div></template>
+      <template v-if="detail" #summary>
+        <dl class="density-detail-overview"><div><dt>客户</dt><dd>{{ customerDisplayName(detail.customerId, detail.customerName) }}</dd></div><div><dt>期间</dt><dd>{{ detail.periodStart || '—' }} 至 {{ detail.periodEnd || '—' }}</dd></div></dl>
+        <FormSection class="statement-summary-section density-form-section" title="对账单概要" aria-label="对账单摘要">
+          <dl class="density-fields statement-summary-grid">
+            <div class="statement-summary-item"><dt>总应收金额</dt><dd>{{ detail.totalAmount.toFixed(2) }} CNY</dd></div>
+            <div class="statement-summary-item"><dt>已收金额</dt><dd>{{ detail.paidAmount.toFixed(2) }} CNY</dd></div>
+            <div class="statement-summary-item"><dt>未收金额</dt><dd class="statement-outstanding">{{ detail.outstandingAmount.toFixed(2) }} CNY</dd></div>
+            <div class="statement-summary-item"><dt>账期</dt><dd>{{ detail.creditDays }} 天</dd></div>
+            <div class="statement-summary-item"><dt>费用明细 / 来源</dt><dd>{{ detail.lines.length }} / {{ new Set(detail.lines.map((line) => line.sourceFeeId)).size }}</dd></div>
+            <div class="statement-summary-item"><dt>调整前金额</dt><dd>{{ detailSourceAmount().toFixed(2) }} CNY</dd></div>
+            <div class="statement-summary-item"><dt>调整金额</dt><dd>{{ (detail.totalAmount - detailSourceAmount()).toFixed(2) }} CNY</dd></div>
+            <div class="statement-summary-item"><dt>货币</dt><dd>{{ detail.currency }}</dd></div>
+            <div class="statement-summary-item"><dt>是否结清</dt><dd>{{ detail.settled ? '是' : '否' }}</dd></div>
+            <div class="statement-summary-item"><dt>创建人</dt><dd>{{ operatorDisplayName(detail.createdByName) }}</dd></div>
+            <div class="statement-summary-item"><dt>创建时间</dt><dd>{{ formatDateTime(detail.createdAt) }}</dd></div>
+            <div class="statement-summary-item"><dt>提交时间</dt><dd>{{ formatDateTime(revisionTime(['SUBMIT'])) }}</dd></div>
+            <div class="statement-summary-item"><dt>审核时间</dt><dd>{{ formatDateTime(revisionTime(['APPROVE', 'REJECT'])) }}</dd></div>
+            <div class="statement-summary-item"><dt>出账时间</dt><dd>{{ formatDateTime(revisionTime(['ISSUE'])) }}</dd></div>
+            <div class="statement-summary-item"><dt>客户确认状态</dt><dd>{{ financeStatusLabel(detail.customerConfirmationStatus || 'NOT_REQUIRED') }}</dd></div>
+            <div class="statement-summary-item"><dt>客户确认人</dt><dd>{{ operatorDisplayName(detail.customerConfirmedByName) }}</dd></div>
+            <div class="statement-summary-item"><dt>客户确认时间</dt><dd>{{ formatDateTime(detail.customerConfirmedAt) }}</dd></div>
+            <div class="statement-summary-item"><dt>更新人</dt><dd>{{ operatorDisplayName(detail.updatedByName) }}</dd></div>
+            <div class="statement-summary-item"><dt>更新时间</dt><dd>{{ formatDateTime(detail.updatedAt) }}</dd></div>
+            <div class="statement-summary-item statement-summary-item--remark"><dt>备注</dt><dd>{{ detail.remark || '—' }}</dd></div>
+          </dl>
+        </FormSection>
+      </template>
+      <el-tabs v-model="activeDetailTab" class="statement-detail-tabs density-element-tabs density-contained-tabs">
+        <el-tab-pane  name="lines"><template #label><span class="density-tab-icon" aria-hidden="true">📋</span><span>账单明细表</span></template>
+          <LoadErrorState v-if="detailError" title="明细加载失败" :message="detailError.message" :loading="detailLoading" @retry="retrySelectedDetail"><template #details><ApiErrorMeta :details="detailError" /></template></LoadErrorState>
+          <el-skeleton v-else-if="detailLoading" :rows="4" animated />
+          <FormSection class="density-form-section" v-else-if="detail" title="账单明细" :bordered="false">
+            <div class="detail-table-scroll">
+              <DataTable class="statement-detail-table statement-line-table" :data="detail.lines" size="small" border stripe :columns="detailLineColumns" column-settings-mode="hide" row-key="statementLineId" empty-text="该对账单暂无账单明细" aria-label="客户对账单账单明细">
+                <template #direction="{ row }">{{ row.direction === 'PAYABLE' ? '应付' : '应收' }}</template>
+                <template #sourceType="{ row }">{{ financeSourceTypeLabel(row.sourceType) }}</template>
+                <template #orderId="{ row }">{{ row.orderId ? `订单 ${row.orderId}` : '—' }}</template>
+                <template #inboundCode="{ row }">{{ row.inboundCode || '—' }}</template>
+                <template #containerNo="{ row }">{{ row.containerNo || '—' }}</template>
+                <template #businessDate="{ row }">{{ row.businessDate || '—' }}</template>
+                <template #quantity="{ row }">{{ row.quantity ?? '—' }}</template>
+                <template #unitPrice="{ row }">{{ row.unitPrice ?? '—' }}</template>
+                <template #billNo>{{ detail.billNo }}</template>
+                <template #periodStart>{{ detail.periodStart || '—' }}</template>
+                <template #periodEnd>{{ detail.periodEnd || '—' }}</template>
+              </DataTable>
+            </div>
+            <el-collapse v-if="detail.revisions.length" class="revision-collapse"><el-collapse-item title="调整记录" name="revisions"><el-table :data="detail.revisions" size="small" border stripe><el-table-column prop="revisionNo" label="修订" width="72" /><el-table-column label="动作" width="130"><template #default="{ row }">{{ revisionActionLabel(row.action) }}</template></el-table-column><el-table-column prop="beforeAmount" label="调整前" /><el-table-column prop="afterAmount" label="调整后" /><el-table-column prop="reason" label="原因" /><el-table-column label="操作人" min-width="140"><template #default="{ row }">{{ operatorDisplayName(row.operatorName) }}</template></el-table-column><el-table-column label="发生时间" min-width="170"><template #default="{ row }">{{ formatDateTime(row.occurredAt) }}</template></el-table-column></el-table></el-collapse-item></el-collapse>
+          </FormSection>
+        </el-tab-pane>
+        <el-tab-pane  name="payments"><template #label><span class="density-tab-icon" aria-hidden="true">💰</span><span>账单支付历史表</span></template>
+          <FormSection class="density-form-section" v-if="detail" title="支付历史" :bordered="false">
+            <div class="detail-table-scroll">
+              <DataTable class="statement-detail-table statement-payment-table" :data="detail.paymentHistory" size="small" border stripe :columns="paymentColumns" column-settings-mode="hide" row-key="transactionId" empty-text="该对账单暂无有效收款记录" aria-label="客户对账单支付历史">
+                <template #customerName>{{ customerDisplayName(detail.customerId, detail.customerName) }}</template>
+                <template #transactionDate="{ row }">{{ formatDateTime(row.transactionDate).slice(0, 10) }}</template>
+                <template #method="{ row }">{{ paymentMethodLabel(row.method) }}</template>
+                <template #voucherFileIds="{ row }">{{ row.voucherFileIds.length ? `${row.voucherFileIds.length} 个附件` : (row.referenceNo || '—') }}</template>
+                <template #createdByName="{ row }">{{ operatorDisplayName(row.createdByName) }}</template>
+                <template #occurredAt="{ row }">{{ formatDateTime(row.occurredAt) }}</template>
+              </DataTable>
+            </div>
+          </FormSection>
+        </el-tab-pane>
+      </el-tabs>
+    </DetailPageLayout>
+    <ListPageLayout v-else aria-label="客户对账单">
+      <template #toolbar><QueryToolbar v-model="filters" class="surface-panel" ariaLabel="客户对账单筛选" :fields="fields" :loading="loading" preference-key="finance-statements-query" :search-on-clear="false" @search="load" /></template>
+      <template v-if="customerError || error" #state><LoadErrorState title="客户对账单加载失败" :message="(customerError || error)?.message || ''" :loading="loading" @retry="customerError ? loadCustomers() : load()"><template #details><ApiErrorMeta :details="(customerError || error)!" /></template></LoadErrorState></template>
+      <template v-if="!customerError && !error">
+        <section class="surface-panel table-panel">
+          <DataTable v-model:page="page" v-model:page-size="pageSize" :data="paginatedRows" :columns="columns" :loading="loading" :total="filteredRows.length" aria-label="客户对账单列表" row-key="id" empty-text="暂无客户对账单" preference-key="finance-customer-statements" @row-click="openDetail">
+            <template #toolbar-actions>
+              <el-button v-if="canExport" :loading="exportBusy" :disabled="loading || exportBusy" @click="exportStatements"><Download :size="15" />导出</el-button>
+              <el-button v-if="canCreate" type="primary" :disabled="!canGenerate" :title="canGenerate ? '生成对账单' : '缺少客户列表权限，无法选择客户'" @click="openCreate"><Plus :size="15" />生成对账单</el-button>
+            </template>
+            <template #actions="{ row }"><div class="density-actions">
+              <el-button data-tone="neutral" class="density-action" size="small" :disabled="loading" @click.stop="openDetail(row as FinanceStatementReadModel)">详情</el-button>
+              <el-button data-tone="neutral" class="density-action" v-if="row.status === 'DRAFT' && canCreate" size="small" :loading="actionBusy" @click.stop="performAction(row as FinanceStatementReadModel, 'SUBMIT')">提交</el-button>
+              <el-button data-tone="warning" class="density-action" v-if="row.status === 'PENDING_REVIEW' && canReview" size="small" :loading="actionBusy" @click.stop="performAction(row as FinanceStatementReadModel, 'APPROVE')">通过</el-button>
+              <el-button data-tone="danger" class="density-action" v-if="row.status === 'PENDING_REVIEW' && canReview" size="small" :loading="actionBusy" @click.stop="performAction(row as FinanceStatementReadModel, 'REJECT')">驳回</el-button>
+              <el-dropdown v-if="row.status === 'PENDING_REVIEW' && canReview && canVoid" trigger="click" @command="(command: ReconciliationActionPayload['action']) => performAction(row as FinanceStatementReadModel, command)">
+                <el-button data-tone="neutral" class="density-action" size="small" :loading="actionBusy" aria-label="更多对账单操作" title="更多对账单操作" @click.stop><MoreHorizontal aria-hidden="true" :size="16" /></el-button>
+                <template #dropdown><el-dropdown-menu><el-dropdown-item command="VOID" class="danger-menu-item">作废</el-dropdown-item></el-dropdown-menu></template>
+              </el-dropdown>
+              <el-button data-tone="danger" class="density-action" v-if="row.status === 'PENDING_REVIEW' && !canReview && canVoid" size="small" :loading="actionBusy" @click.stop="performAction(row as FinanceStatementReadModel, 'VOID')">作废</el-button>
+              <el-button data-tone="neutral" class="density-action" v-if="row.status === 'APPROVED' && canIssue" size="small" :loading="actionBusy" @click.stop="performAction(row as FinanceStatementReadModel, 'ISSUE')">出账</el-button>
+              <el-button data-tone="neutral" class="density-action" v-if="row.status === 'ISSUED' && canAdjust" size="small" :loading="adjustBusy" @click.stop="openAdjustment(row as FinanceStatementReadModel)">调整</el-button>
+              <el-button data-tone="neutral" class="density-action" v-if="['REJECTED','VOIDED'].includes(String(row.status)) && canVoid" size="small" :loading="actionBusy" @click.stop="performAction(row as FinanceStatementReadModel, 'REOPEN')">重开</el-button>
+              <el-button data-tone="danger" class="density-action" v-if="['DRAFT','APPROVED','ISSUED'].includes(String(row.status)) && canVoid" size="small" :loading="actionBusy" @click.stop="performAction(row as FinanceStatementReadModel, 'VOID')">作废</el-button>
+            </div></template>
+            <template #status="{ row }"><el-tag :type="financeStatusTone(row.status)">{{ financeStatusLabel(row.status) }}</el-tag></template>
+            <template #customerConfirmationStatus="{ row }"><el-tag :type="financeStatusTone(row.customerConfirmationStatus || 'NOT_REQUIRED')">{{ financeStatusLabel(row.customerConfirmationStatus || 'NOT_REQUIRED') }}</el-tag></template>
+            <template #customerName="{ row }">{{ customerDisplayName(row.customerId, row.customerName) }}</template>
+            <template #lastPaymentAt="{ row }">{{ formatDateTime(row.lastPaymentAt) }}</template>
+            <template #settled="{ row }"><el-tag v-if="row.settled !== null" :type="row.settled ? 'success' : 'warning'">{{ row.settled ? '是' : '否' }}</el-tag><span v-else>—</span></template>
+            <template #createdByName="{ row }">{{ operatorDisplayName(row.createdByName) }}</template>
+            <template #createdAt="{ row }">{{ formatDateTime(row.createdAt) }}</template>
+            <template #submittedAt="{ row }">{{ formatDateTime(row.submittedAt) }}</template>
+            <template #reviewedAt="{ row }">{{ formatDateTime(row.reviewedAt) }}</template>
+            <template #issuedAt="{ row }">{{ formatDateTime(row.issuedAt) }}</template>
+            <template #customerConfirmedByName="{ row }">{{ row.customerConfirmationStatus === 'CONFIRMED' ? operatorDisplayName(row.customerConfirmedByName) : '—' }}</template>
+            <template #customerConfirmedAt="{ row }">{{ formatDateTime(row.customerConfirmedAt) }}</template>
+            <template #updatedByName="{ row }">{{ operatorDisplayName(row.updatedByName) }}</template>
+            <template #updatedAt="{ row }">{{ formatDateTime(row.updatedAt) }}</template>
+            <template #pagination-left>共 {{ filteredRows.length }} 条 · 币种：CNY</template>
+          </DataTable>
+        </section>
+
+      </template>
+    </ListPageLayout>
+
+    <AppDialog class="admin-density-dialog" v-model="createOpen" title="生成客户对账单" width="min(680px, 94vw)" :confirm-loading="createBusy" @confirm="createStatement">
+      <el-alert v-if="createError" type="warning" :closable="true" show-icon title="暂时无法生成对账单" @close="createError = null"><p>{{ createError.message }}</p></el-alert>
+      <el-form class="density-form" label-position="top">
+        <el-form-item label="生成方式">
+          <el-radio-group v-model="createForm.generationMode">
+            <el-radio-button value="BY_CUTOFF">按账期自动汇总</el-radio-button>
+            <el-radio-button value="SELECTED" :disabled="!canSelectSources">指定费用生成</el-radio-button>
+          </el-radio-group>
+        </el-form-item>
+        <el-form-item label="客户"><el-select v-model="createForm.customerId" filterable placeholder="请选择客户"><el-option v-for="item in activeCustomers" :key="String(item.id)" :label="item.tenantName" :value="String(item.id)" /></el-select></el-form-item>
+        <div class="create-period-row"><el-form-item label="账期开始"><el-date-picker v-model="createForm.periodStart" type="date" value-format="YYYY-MM-DD" /></el-form-item><el-form-item label="账期结束"><el-date-picker v-model="createForm.periodEnd" type="date" value-format="YYYY-MM-DD" /></el-form-item></div>
+        <template v-if="createForm.generationMode === 'SELECTED'">
+          <el-alert v-if="!canSelectSources" type="warning" :closable="false" title="当前账号没有查看费用来源的权限，不能指定费用生成。" />
+          <el-alert v-else-if="createSourcesError" type="error" :closable="false"><template #title>可生成费用加载失败</template><p>{{ createSourcesError.message }}</p><ApiErrorMeta :details="createSourcesError" /><el-button size="small" @click="loadEligibleCreateSources()">重试</el-button></el-alert>
+          <el-form-item label="应收费用">
+            <el-select v-model="createForm.feeSourceIds" multiple filterable collapse-tags :max-collapse-tags="3" :loading="createSourcesLoading" placeholder="请选择审核通过、已发布且未出账的费用">
+              <el-option v-for="item in createSourceOptions" :key="item.feeSourceId" :label="`${item.feeItemName} · ${item.businessDate} · ${Number(item.amount).toFixed(2)} CNY`" :value="item.feeSourceId" />
+            </el-select>
+            <div class="selected-source-summary">已选 {{ createForm.feeSourceIds.length }} 笔，合计 {{ selectedCreateAmount.toFixed(2) }} CNY</div>
+          </el-form-item>
+        </template>
+        <el-form-item label="备注"><el-input v-model="createForm.remark" type="textarea" :rows="3" maxlength="500" show-word-limit placeholder="请输入备注（选填）" /></el-form-item>
+      </el-form>
+    </AppDialog>
+
+    <AppDialog class="admin-density-dialog" v-model="adjustOpen" title="调整客户对账单" width="min(900px, 96vw)" :confirm-loading="adjustBusy" @confirm="submitAdjustment">
+      <el-form class="density-form" label-position="top"><el-form-item label="整体调整原因"><el-input v-model="adjustReason" type="textarea" maxlength="500" show-word-limit placeholder="请输入整体调整原因" /></el-form-item></el-form>
+      <el-table :data="adjustLines" size="small" max-height="420" border stripe><el-table-column label="选择" width="64"><template #default="{ row }"><el-checkbox v-model="row.selected" /></template></el-table-column><el-table-column prop="feeItemName" label="费用项目" min-width="150" /><el-table-column prop="originalAmount" label="原金额(CNY)" width="130" /><el-table-column label="新金额(CNY)" width="180"><template #default="{ row }"><el-input-number v-model="row.adjustedAmount" :min="0.01" :precision="2" placeholder="请输入新金额" /></template></el-table-column><el-table-column label="明细说明" min-width="220"><template #default="{ row }"><el-input v-model="row.reason" maxlength="500" placeholder="请输入明细说明" /></template></el-table-column></el-table>
+    </AppDialog>
+  </AdminPage>
+</template>
+
+<style scoped>
+.finance-statements-page { min-width: 0; }
+:deep(.el-select), :deep(.el-date-editor) { width: 100%; }
+.create-period-row { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: var(--admin-space-6); }
+.selected-source-summary { width: 100%; margin-top: var(--admin-space-2); color: var(--cc-text-secondary); font-size: var(--admin-font-caption); text-align: right; }
+.statement-detail-page { min-width: 0; width: min(100%, 1920px); margin: 0 auto; overflow: hidden; }
+.statement-summary-section { padding: var(--admin-space-4) var(--admin-space-6); border-bottom: 1px solid var(--cc-border-subtle); }
+.statement-outstanding { color: var(--el-color-warning-dark-2); }
+.statement-detail-tabs { min-width: 0; }
+.statement-detail-table { min-width: 0; }
+.detail-table-scroll { min-width: 0; overflow-x: auto; }
+.statement-line-table { min-width: 1840px; }
+.statement-payment-table { min-width: 1300px; }
+.revision-collapse { margin-top: var(--admin-space-5); }
+:deep(.danger-menu-item:not(.is-disabled)) { color: var(--el-color-danger); }
+
+@media (min-width: 1920px) {
+
+  .statement-summary-section {
+    padding: var(--admin-space-3) var(--admin-space-5);
+  }
+
+  .detail-table-scroll {
+    margin-bottom: var(--admin-space-3);
+  }
+
+  .revision-collapse {
+    margin-top: var(--admin-space-3);
+  }
+}
+
+@media (max-width: 640px) {
+  .statement-detail-page__header { align-items: stretch; flex-direction: column; }
+  .statement-summary-grid { grid-template-columns: 1fr; }
+  .statement-summary-item--remark { grid-column: auto; }
+}
+</style>
diff --git a/src/modules/finance/pages/FinanceFormalSettlementExport.test.ts b/src/modules/finance/pages/FinanceFormalSettlementExport.test.ts
new file mode 100644
index 00000000..82b561fa
--- /dev/null
+++ b/src/modules/finance/pages/FinanceFormalSettlementExport.test.ts
@@ -0,0 +1,160 @@
+import ElementPlus from 'element-plus'
+import { createPinia, setActivePinia } from 'pinia'
+import { createMemoryHistory, createRouter } from 'vue-router'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+import { createPlatformExportTask } from '@/modules/downloads'
+import { listPlatformTenants } from '@/modules/iam'
+import { showExportTaskCreatedDialog } from '@/shared/components/exportTaskCreatedDialog'
+import { getFinanceSettlement, listFinancePayableSettlements, listFinanceReceivableSettlements } from '../api/finance'
+import type { FinanceSettlementDetail } from '../types'
+import FinanceFormalSettlementPage from './FinanceFormalSettlementPage.vue'
+
+vi.mock('@/modules/downloads', () => ({ createPlatformExportTask: vi.fn() }))
+vi.mock('@/modules/iam', () => ({ listPlatformTenants: vi.fn() }))
+vi.mock('@/modules/suppliers', () => ({ categoryLabels: {}, listSuppliers: vi.fn() }))
+vi.mock('@/shared/components/exportTaskCreatedDialog', () => ({ showExportTaskCreatedDialog: vi.fn() }))
+vi.mock('../api/finance', async (importOriginal) => ({
+  ...await importOriginal<typeof import('../api/finance')>(),
+  getFinanceSettlement: vi.fn(),
+  listFinancePayableSettlements: vi.fn(),
+  listFinanceReceivableSettlements: vi.fn(),
+}))
+
+class ResizeObserverStub implements ResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+
+function createMemoryStorage(): Storage {
+  const values = new Map<string, string>()
+  return {
+    get length() { return values.size }, clear: () => values.clear(), getItem: (key) => values.get(key) ?? null,
+    key: (index) => [...values.keys()][index] ?? null, removeItem: (key) => values.delete(key), setItem: (key, value) => values.set(key, value),
+  }
+}
+
+function piniaWithPermissions(permissions: string[]) {
+  const pinia = createPinia()
+  setActivePinia(pinia)
+  const auth = useAuthStore()
+  auth.token = 'token'
+  auth.permissions = permissions
+  useAccessPreviewStore().initializeAfterLogin()
+  return pinia
+}
+
+function testRouter() {
+  return createRouter({
+    history: createMemoryHistory(),
+    routes: [
+      { path: '/', name: 'settlements', component: { template: '<div />' } },
+      { path: '/downloads', name: 'download-center', component: { template: '<div />' } },
+    ],
+  })
+}
+
+const detail: FinanceSettlementDetail = {
+  id: '701', settlementNo: 'AR-701', customerId: '10001', reconciliationStatementId: '501', direction: 'RECEIVABLE',
+  amount: 300, paidAmount: 0, outstandingAmount: 300, currency: 'CNY', status: 'ISSUED', version: 0,
+  lines: [], transactions: [], revisions: [],
+}
+
+enableAutoUnmount(afterEach)
+
+describe('formal settlement download-center exports', () => {
+  beforeEach(() => {
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+    vi.stubGlobal('localStorage', createMemoryStorage())
+    vi.stubGlobal('sessionStorage', createMemoryStorage())
+    vi.mocked(listPlatformTenants).mockReset().mockResolvedValue({ records: [], page: 1, size: 200, total: 0, pages: 1 })
+    vi.mocked(listFinanceReceivableSettlements).mockReset().mockResolvedValue([])
+    vi.mocked(listFinancePayableSettlements).mockReset().mockResolvedValue([])
+    vi.mocked(getFinanceSettlement).mockReset().mockResolvedValue(detail)
+    vi.mocked(createPlatformExportTask).mockReset().mockResolvedValue({ taskName: '应收结算单列表', taskNo: 'EXP-001' } as never)
+    vi.mocked(showExportTaskCreatedDialog).mockReset().mockResolvedValue(false)
+  })
+
+  it('creates an AR list task with current filters and no paging or direction parameters', async () => {
+    const router = testRouter()
+    await router.push('/'); await router.isReady()
+    const pinia = piniaWithPermissions(['platform:finance:settlement-ar:list', 'platform:finance:settlement-ar:export', 'platform:download:list'])
+    const wrapper = mount(FinanceFormalSettlementPage, { props: { kind: 'receivable' }, global: { plugins: [pinia, ElementPlus, router] } })
+    await flushPromises()
+    const vm = wrapper.vm as unknown as { filters: Record<string, unknown>; exportRows(): Promise<void> }
+    vm.filters = { customerId: '10001', status: 'ISSUED', settlementNo: ' AR-001 ', supplierName: '' }
+
+    await vm.exportRows()
+
+    expect(createPlatformExportTask).toHaveBeenCalledWith({
+      exportType: 'FINANCE_RECEIVABLE_SETTLEMENT_LIST', format: 'XLSX', taskName: '应收结算单列表',
+      parameters: { customerId: '10001', status: 'ISSUED', settlementNo: 'AR-001' },
+    })
+    expect(createPlatformExportTask).not.toHaveBeenCalledWith(expect.objectContaining({ parameters: expect.objectContaining({ direction: expect.anything(), page: expect.anything(), pageSize: expect.anything() }) }))
+  })
+
+  it('creates an AP list task with the supplier filter', async () => {
+    const router = testRouter()
+    await router.push('/'); await router.isReady()
+    const pinia = piniaWithPermissions(['platform:finance:settlement-ap:list', 'platform:finance:settlement-ap:export', 'platform:download:list'])
+    const wrapper = mount(FinanceFormalSettlementPage, { props: { kind: 'payable' }, global: { plugins: [pinia, ElementPlus, router] } })
+    await flushPromises()
+    const vm = wrapper.vm as unknown as { filters: Record<string, unknown>; exportRows(): Promise<void> }
+    vm.filters = { customerId: '10002', status: 'PARTIALLY_PAID', settlementNo: 'AP-002', supplierName: '承运供应商' }
+
+    await vm.exportRows()
+
+    expect(createPlatformExportTask).toHaveBeenCalledWith({
+      exportType: 'FINANCE_PAYABLE_SETTLEMENT_LIST', format: 'XLSX', taskName: '应付结算单列表',
+      parameters: { customerId: '10002', status: 'PARTIALLY_PAID', settlementNo: 'AP-002', supplierName: '承运供应商' },
+    })
+  })
+
+  it('exports a detail by settlement business key and opens the download center on confirmation', async () => {
+    vi.mocked(createPlatformExportTask).mockResolvedValueOnce({ taskName: '应收结算单详情', taskNo: 'EXP-DETAIL-1' } as never)
+    vi.mocked(showExportTaskCreatedDialog).mockResolvedValueOnce(true)
+    const router = testRouter()
+    await router.push('/'); await router.isReady()
+    const pinia = piniaWithPermissions(['platform:finance:settlement-ar:list', 'platform:finance:settlement-ar:export', 'platform:download:list'])
+    const wrapper = mount(FinanceFormalSettlementPage, { props: { kind: 'receivable', settlementId: '701' }, global: { plugins: [pinia, ElementPlus, router] } })
+    await flushPromises()
+    const vm = wrapper.vm as unknown as { exportDetail(): Promise<void> }
+
+    await vm.exportDetail()
+
+    expect(createPlatformExportTask).toHaveBeenCalledWith({
+      exportType: 'FINANCE_RECEIVABLE_SETTLEMENT_DETAIL', format: 'XLSX', taskName: '应收结算单详情', parameters: { settlementId: '701' },
+    })
+    expect(showExportTaskCreatedDialog).toHaveBeenCalledWith({ taskName: '应收结算单详情', taskNo: 'EXP-DETAIL-1', dense: true })
+    expect(router.currentRoute.value.name).toBe('download-center')
+  })
+
+  it('uses the payable detail type without a direction parameter', async () => {
+    vi.mocked(getFinanceSettlement).mockResolvedValueOnce({ ...detail, id: '801', settlementNo: 'AP-801', direction: 'PAYABLE' })
+    vi.mocked(createPlatformExportTask).mockResolvedValueOnce({ taskName: '应付结算单详情', taskNo: 'EXP-DETAIL-2' } as never)
+    const router = testRouter()
+    await router.push('/'); await router.isReady()
+    const pinia = piniaWithPermissions(['platform:finance:settlement-ap:list', 'platform:finance:settlement-ap:export', 'platform:download:list'])
+    const wrapper = mount(FinanceFormalSettlementPage, { props: { kind: 'payable', settlementId: '801' }, global: { plugins: [pinia, ElementPlus, router] } })
+    await flushPromises()
+
+    await (wrapper.vm as unknown as { exportDetail(): Promise<void> }).exportDetail()
+
+    expect(createPlatformExportTask).toHaveBeenCalledWith({
+      exportType: 'FINANCE_PAYABLE_SETTLEMENT_DETAIL', format: 'XLSX', taskName: '应付结算单详情', parameters: { settlementId: '801' },
+    })
+  })
+
+  it('hides export actions unless both export and download-list permissions are present', async () => {
+    const router = testRouter()
+    await router.push('/'); await router.isReady()
+    const pinia = piniaWithPermissions(['platform:finance:settlement-ar:list', 'platform:download:list'])
+    const wrapper = mount(FinanceFormalSettlementPage, { props: { kind: 'receivable' }, global: { plugins: [pinia, ElementPlus, router] } })
+    await flushPromises()
+
+    expect(wrapper.find('.settlement-list-actions').text()).not.toContain('导出')
+  })
+})
diff --git a/src/modules/finance/pages/FinanceFormalSettlementFields.test.ts b/src/modules/finance/pages/FinanceFormalSettlementFields.test.ts
new file mode 100644
index 00000000..59f1ca11
--- /dev/null
+++ b/src/modules/finance/pages/FinanceFormalSettlementFields.test.ts
@@ -0,0 +1,68 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import { getFinanceSettlement, listFinancePayableSettlements, listFinanceReceivableSettlements } from '../api/finance'
+
+const pageSource = readFileSync(resolve(process.cwd(), 'src/modules/finance/pages/FinanceFormalSettlementPage.vue'), 'utf8')
+
+afterEach(() => vi.restoreAllMocks())
+
+describe('formal settlement field contract', () => {
+  it('maps list business fields without exposing internal versions', async () => {
+    const get = vi.spyOn(http, 'get')
+      .mockResolvedValueOnce({ code: '200', data: [{
+        settlementId: 701, settlementNo: 'AR-701', direction: 'RECEIVABLE', customerId: 10001,
+        customerName: '客户A', reconciliationStatementId: 501, reconciliationStatementNo: 'REC-501',
+        businessPeriod: '2026-08', feeItemSummary: '海运费、拖车费', currency: 'CNY', totalAmount: 300,
+        paidAmount: 100, outstandingAmount: 200, generatedDate: '2026-08-17', dueDate: '2026-09-16',
+        paymentStatus: 'PARTIALLY_PAID', status: 'PARTIALLY_PAID', createdBy: 7, createdByName: '财务员',
+        createdAt: '2026-08-17T09:00:00', updatedAt: '2026-08-17T10:00:00', lastPaymentAt: '2026-08-17T10:00:00', version: 1,
+      }] } as never)
+      .mockResolvedValueOnce({ code: '200', data: [{
+        settlementId: 801, settlementNo: 'AP-801', direction: 'PAYABLE', customerId: 10001,
+        customerName: '客户A', supplierId: 81, supplierName: '承运供应商', businessPeriod: '2026-08',
+        feeItemSummary: '拖车费', currency: 'CNY', totalAmount: 300, paidAmount: 0, outstandingAmount: 300,
+        generatedDate: '2026-08-17', dueDate: '2026-09-16', paymentStatus: 'UNPAID', status: 'ISSUED',
+        createdBy: 7, createdByName: '财务员', createdAt: '2026-08-17T09:00:00', updatedAt: '2026-08-17T09:00:00', version: 0,
+      }] } as never)
+
+    const [receivable] = await listFinanceReceivableSettlements('10001')
+    const [payable] = await listFinancePayableSettlements('10001')
+
+    expect(receivable).toMatchObject({ reconciliationStatementNo: 'REC-501', feeItemSummary: '海运费、拖车费', createdByName: '财务员', lastPaymentAt: '2026-08-17T10:00:00' })
+    expect(payable).toMatchObject({ customerName: '客户A', supplierName: '承运供应商', feeItemSummary: '拖车费', createdAt: '2026-08-17T09:00:00' })
+    expect(get).toHaveBeenNthCalledWith(1, '/platform/finance/v1/receivable-settlements', { params: { customerId: '10001' } })
+  })
+
+  it('maps immutable source identity and payment evidence in detail', async () => {
+    vi.spyOn(http, 'get').mockResolvedValue({ code: '200', data: {
+      settlementId: 801, settlementNo: 'AP-801', direction: 'PAYABLE', customerId: 10001, customerName: '客户A',
+      supplierId: 81, supplierName: '承运供应商', feeItemSummary: '拖车费', totalAmount: 300, paidAmount: 100,
+      outstandingAmount: 200, currency: 'CNY', generatedDate: '2026-08-17', dueDate: '2026-09-16',
+      paymentStatus: 'PARTIALLY_PAID', status: 'PARTIALLY_PAID', createdBy: 7, createdByName: '财务员',
+      createdAt: '2026-08-17T09:00:00', updatedAt: '2026-08-17T10:00:00', lastPaymentAt: '2026-08-17T10:00:00', version: 1,
+      lines: [{ feeSourceId: 21, sourceType: 'CONTAINER_FEE', sourceFeeId: 9001, sourceVersion: 1, direction: 'PAYABLE', customerId: 10001, supplierId: 81, supplierName: '承运供应商', orderId: 11, orderNo: 'FL-11', inboundId: 12, inboundCode: 'IN-12', containerId: 13, containerNo: 'CONT-13', businessDate: '2026-08-15', feeItemName: '拖车费', amount: 300, currency: 'CNY', reviewStatus: 'APPROVED', sourceStatus: 'AVAILABLE', statementGenerated: true }],
+      transactions: [{ transactionId: 31, transactionType: 'PAYMENT', transactionDate: '2026-08-17', amount: 100, method: 'BANK_TRANSFER', referenceNo: 'BANK-31', voucherFileIds: [41], createdBy: 7, createdByName: '财务员', createdAt: '2026-08-17T10:00:00' }],
+      revisions: [{ revisionNo: 1, action: 'CREATE', beforeAmount: 0, afterAmount: 300, operatorId: 7, operatorName: '财务员', occurredAt: '2026-08-17T09:00:00' }],
+    } } as never)
+
+    const detail = await getFinanceSettlement('801')
+
+    expect(detail.lines[0]).toMatchObject({ orderId: '11', orderNo: 'FL-11', inboundCode: 'IN-12', containerNo: 'CONT-13', feeItemName: '拖车费', amount: 300 })
+    expect(detail.transactions[0]).toMatchObject({ method: 'BANK_TRANSFER', referenceNo: 'BANK-31', voucherFileIds: ['41'], createdByName: '财务员' })
+  })
+
+  it('renders the confirmed list and detail fields as business labels', () => {
+    for (const label of ['关联对账单', '结算周期', '创建时间', '最后收款时间', '最后付款时间', '订单号', '银行流水号/凭证号', '修订记录']) {
+      expect(pageSource).toContain(label)
+    }
+    expect(pageSource).toContain("BANK_TRANSFER: '银行转账'")
+    expect(pageSource).not.toContain('prop="sourceVersion" label="来源版本"')
+    expect(pageSource).not.toContain('{{ detail.version }}')
+  })
+
+  it('does not offer directly paid costs as payable settlement sources', () => {
+    expect(pageSource).toContain("item.settlementMode?.toUpperCase() !== 'DIRECT_PAID'")
+  })
+})
diff --git a/src/modules/finance/pages/FinanceFormalSettlementLayout.test.ts b/src/modules/finance/pages/FinanceFormalSettlementLayout.test.ts
new file mode 100644
index 00000000..77d9f419
--- /dev/null
+++ b/src/modules/finance/pages/FinanceFormalSettlementLayout.test.ts
@@ -0,0 +1,72 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/finance/pages/FinanceFormalSettlementPage.vue'), 'utf8')
+const statementsSource = readFileSync(resolve(process.cwd(), 'src/modules/finance/pages/FinanceCustomerStatementsView.vue'), 'utf8')
+
+describe('Finance formal settlement desktop presentation', () => {
+  it('keeps settlement totals on the left and list actions on the right of the table toolbar', () => {
+    expect(source).toContain('<template #toolbar-start>')
+    expect(source).toContain('<dl class="density-detail-overview settlement-summary" aria-label="结算汇总">')
+    expect(source).toContain('<template #toolbar-actions>')
+    expect(source).toContain('<div class="settlement-list-actions">')
+    expect(source).not.toContain('class="settlement-list-toolbar"')
+  })
+
+  it('paginates customer statements and both settlement lists after filtering', () => {
+    for (const pageSource of [statementsSource, source]) {
+      expect(pageSource).toContain('const page = ref(1)')
+      expect(pageSource).toContain('const pageSize = ref(20)')
+      expect(pageSource).toContain('const paginatedRows = computed(() => {')
+      expect(pageSource).toContain('filteredRows.value.slice(start, start + pageSize.value)')
+      expect(pageSource).toContain('v-model:page="page" v-model:page-size="pageSize" :data="paginatedRows"')
+      expect(pageSource).toContain(':total="filteredRows.length"')
+      expect(pageSource).toContain('page.value = 1')
+    }
+  })
+
+  it('renders at most three permitted row actions as shared outlined text buttons', () => {
+    expect(source.match(/key: 'actions', label: '操作', width: 250/g)).toHaveLength(2)
+    expect(source).toContain('class="settlement-row-actions density-actions"')
+    for (const action of ['openDetail(row)', 'openReceipt(row)', 'openPayment(row)']) expect(source).toContain('@click="' + action + '"')
+    expect(source).toContain('data-tone="danger"')
+    expect(source).toContain('class="density-action"')
+    expect(source).not.toContain('MoreHorizontal')
+    expect(source).toContain("props.kind === 'payable' && access.can('platform:finance:payment:create')")
+    expect(source).toContain("props.kind === 'receivable' && access.can('platform:finance:receipt:create')")
+    expect(source).toContain("canVoid && row.status === 'ISSUED'")
+    expect(source).toContain("canVoid && row.status === 'VOIDED'")
+  })
+
+  it('uses a continuous detail layout with locally scrollable wide tables', () => {
+    expect(source).toContain('<DetailPageLayout v-else-if="detailMode" class="settlement-detail-page surface-panel finance-density-detail"')
+    expect(source).toContain('class="settlement-detail-content"')
+    expect(source).toContain('class="detail-table-scroll"')
+    expect(source).toContain(':deep(.detail-table-scroll .el-table) { min-width: 920px; }')
+    expect(source).not.toContain('class="settlement-detail-card"')
+  })
+
+  it('presents fee sources and revisions as finance business labels', () => {
+    expect(source).toContain('financeSourceTypeLabel(scope.row.sourceType)')
+    expect(source).not.toContain('prop="sourceVersion" label="来源版本"')
+    expect(source).toContain("VOID: '作废'")
+    expect(source).toContain("REOPEN: '重开'")
+    expect(source).toContain("RECEIPT: '收款登记'")
+    expect(source).toContain("PAYMENT: '付款登记'")
+    expect(source).toContain('settlementRevisionActionLabel(scope.row.action)')
+    expect(source).toContain('operatorDisplayName(scope.row.createdByName)')
+    expect(source).toContain('operatorDisplayName(scope.row.operatorName)')
+    expect(source).toContain("'名称数据缺失'")
+  })
+
+  it('keeps receipt and payment dialogs readable at desktop width', () => {
+    expect(source.match(/width="min\(760px, 94vw\)"/g)).toHaveLength(2)
+    expect(source.match(/class="density-detail-overview partial-summary"/g)).toHaveLength(2)
+    expect(source).toContain('.settlement-operation-form { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr));')
+    expect(source).toContain('<OperationErrorToast :message="receiptValidationError" />')
+    expect(source).toContain('<OperationErrorToast :details="receiptError" />')
+    expect(source).not.toContain('<el-alert v-if="receiptValidationError"')
+    expect(source).not.toContain('<el-alert v-if="receiptError"')
+  })
+})
diff --git a/src/modules/finance/pages/FinanceFormalSettlementPage.vue b/src/modules/finance/pages/FinanceFormalSettlementPage.vue
new file mode 100644
index 00000000..26ec4459
--- /dev/null
+++ b/src/modules/finance/pages/FinanceFormalSettlementPage.vue
@@ -0,0 +1,732 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import '../financeDensity.css'
+import { computed, onMounted, ref, watch } from 'vue'
+import { useRouter } from 'vue-router'
+import { ElMessage, ElMessageBox, type UploadFile } from 'element-plus'
+import { ArrowLeft, CreditCard, Download, HandCoins, Plus, RotateCcw, XCircle } from '@lucide/vue'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { createPlatformExportTask } from '@/modules/downloads'
+import { listPlatformTenants, type PlatformTenantResource } from '@/modules/iam'
+import { categoryLabels, listSuppliers, type Supplier } from '@/modules/suppliers'
+import { getApiErrorDetails, getApiErrorMessage, type ApiErrorDetails } from '@/shared/api/http'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import OperationErrorToast from '@/shared/components/OperationErrorToast.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import DetailPageLayout from '@/shared/components/DetailPageLayout.vue'
+import FormSection from '@/shared/components/FormSection.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import { showExportTaskCreatedDialog } from '@/shared/components/exportTaskCreatedDialog'
+import {
+  actionFinanceSettlement,
+  createFinanceReceipt,
+  createFinanceSettlementPayment,
+  createPayableSettlement,
+  createReceivableSettlement,
+  getFinanceSettlement,
+  listFinanceFeePool,
+  listFinancePayableSettlements,
+  listFinanceReceivableSettlements,
+  listFinanceStatements,
+  uploadFinanceVoucher,
+} from '../api/finance'
+import { financeOperationActionLabel, financeSourceTypeLabel, financeStatusLabel, financeStatusTone } from '../status'
+import type {
+  FinanceFeePoolItem,
+  FinancePayableSettlement,
+  FinanceReceivableSettlement,
+  FinanceSettlementDetail,
+  FinanceStatementReadModel,
+} from '../types'
+
+type SettlementRow = FinanceReceivableSettlement | FinancePayableSettlement
+
+const props = defineProps<{ kind: 'receivable' | 'payable'; settlementId?: string }>()
+const emit = defineEmits<{ openDetail: [settlementId: string]; back: [] }>()
+const router = useRouter()
+const access = useAccessPreviewStore()
+const customers = ref<PlatformTenantResource[]>([])
+const filters = ref<QueryModel>({ customerId: '', supplierName: '', settlementNo: '', status: '' })
+const appliedFilters = ref<QueryModel>({ ...filters.value })
+const rows = ref<SettlementRow[]>([])
+const page = ref(1)
+const pageSize = ref(20)
+const loading = ref(false)
+const error = ref<ApiErrorDetails | null>(null)
+const customerError = ref<ApiErrorDetails | null>(null)
+const detail = ref<FinanceSettlementDetail | null>(null)
+const selectedRow = ref<SettlementRow | null>(null)
+const detailLoading = ref(false)
+const detailError = ref<ApiErrorDetails | null>(null)
+const createOpen = ref(false)
+const createBusy = ref(false)
+const statementOptions = ref<FinanceStatementReadModel[]>([])
+const feeOptions = ref<FinanceFeePoolItem[]>([])
+const supplierOptions = ref<Supplier[]>([])
+const suppliersLoaded = ref(false)
+const createForm = ref({
+  customerId: '',
+  reconciliationStatementId: '',
+  supplierId: '',
+  feeSourceIds: [] as string[],
+  dueDate: '',
+})
+const paymentOpen = ref(false)
+const paymentBusy = ref(false)
+const paymentFile = ref<File | null>(null)
+const paymentForm = ref({ transactionDate: new Date().toISOString().slice(0, 10), amount: 0, method: 'BANK_TRANSFER' as 'BANK_TRANSFER' | 'CASH' | 'OTHER', referenceNo: '', remark: '' })
+const receiptOpen = ref(false)
+const receiptBusy = ref(false)
+const receiptFile = ref<File | null>(null)
+const receiptUploadKey = ref(0)
+const receiptValidationError = ref<string | null>(null)
+const receiptError = ref<ApiErrorDetails | null>(null)
+const receiptForm = ref({ receivedDate: new Date().toISOString().slice(0, 10), amount: 0, paymentMethod: 'BANK_TRANSFER' as 'BANK_TRANSFER' | 'CASH' | 'OTHER', remark: '' })
+const actionBusy = ref(false)
+const exportSubmitting = ref(false)
+
+const createPermission = computed(() => props.kind === 'receivable' ? 'platform:finance:settlement-ar:create' : 'platform:finance:settlement-ap:create')
+const listPermission = computed(() => props.kind === 'receivable' ? 'platform:finance:settlement-ar:list' : 'platform:finance:settlement-ap:list')
+const exportPermission = computed(() => props.kind === 'receivable' ? 'platform:finance:settlement-ar:export' : 'platform:finance:settlement-ap:export')
+const canView = computed(() => access.can(listPermission.value))
+const canListCustomers = computed(() => access.can('platform:customer:list'))
+const canCreate = computed(() => access.can(createPermission.value))
+const canPay = computed(() => props.kind === 'payable' && access.can('platform:finance:payment:create'))
+const canReceive = computed(() => props.kind === 'receivable' && access.can('platform:finance:receipt:create'))
+const canVoid = computed(() => access.can('platform:finance:settlement:void'))
+const canExport = computed(() => access.can(exportPermission.value) && access.can('platform:download:list'))
+const title = computed(() => props.kind === 'receivable' ? '结算单应收' : '结算单应付')
+const detailMode = computed(() => Boolean(props.settlementId))
+const createLabel = computed(() => props.kind === 'receivable' ? '生成应收结算单' : '生成应付结算单')
+const activeCustomers = computed(() => customers.value.filter((item) => item.status === 'ACTIVE'))
+const supplierNames = computed(() => [...new Set(rows.value.map((item) => 'supplierName' in item ? item.supplierName : '').filter(Boolean))])
+const statusOptions = computed(() => [...new Set(rows.value.map((item) => item.status).filter(Boolean))])
+const fields = computed<QueryField[]>(() => [
+  { key: 'status', type: 'select', label: props.kind === 'receivable' ? '收款状态' : '付款状态', width: 180, placeholder: '全部状态', props: { clearable: true }, options: statusOptions.value.map((status) => ({ label: financeStatusLabel(status), value: status })) },
+  ...(props.kind === 'receivable'
+    ? [{ key: 'customerId', type: 'select' as const, label: '客户名称', width: 260, placeholder: '全部客户', props: { filterable: true, clearable: true, loading: !customers.value.length && !customerError.value }, options: activeCustomers.value.map((item) => ({ label: item.tenantName, value: String(item.id) })) }]
+    : [
+        { key: 'supplierName', type: 'select' as const, label: '供应商', width: 240, placeholder: '全部供应商', props: { filterable: true, clearable: true }, options: supplierNames.value.map((name) => ({ label: name, value: name })) },
+        { key: 'customerId', type: 'select' as const, label: '客户名称', width: 260, placeholder: '全部客户', props: { filterable: true, clearable: true, loading: !customers.value.length && !customerError.value }, options: activeCustomers.value.map((item) => ({ label: item.tenantName, value: String(item.id) })) },
+      ]),
+  { key: 'settlementNo', type: 'input', label: '结算单号', width: 220, placeholder: '请输入结算单号' },
+])
+const filteredRows = computed(() => {
+  const status = String(appliedFilters.value.status || '')
+  const settlementNo = String(appliedFilters.value.settlementNo || '').trim().toLowerCase()
+  const supplierName = String(appliedFilters.value.supplierName || '')
+  return rows.value.filter((item) => (!status || item.status === status)
+    && (!settlementNo || item.settlementNo.toLowerCase().includes(settlementNo))
+    && (!supplierName || ('supplierName' in item && item.supplierName === supplierName)))
+})
+const paginatedRows = computed(() => {
+  const start = (page.value - 1) * pageSize.value
+  return filteredRows.value.slice(start, start + pageSize.value)
+})
+const totals = computed(() => filteredRows.value.reduce((result, row) => ({
+  amount: result.amount + totalAmount(row),
+  paid: result.paid + paidAmount(row),
+  outstanding: result.outstanding + row.outstandingAmount,
+}), { amount: 0, paid: 0, outstanding: 0 }))
+const columns = computed<DataTableColumn[]>(() => props.kind === 'receivable'
+  ? [
+      { key: 'actions', label: '操作', width: 250, fixed: 'left', slotName: 'actions' },
+      { key: 'settlementNo', label: '结算单号', minWidth: 180 },
+      { key: 'customerId', label: '客户', minWidth: 180, slotName: 'customer' },
+      { key: 'feeItemSummary', label: '费用类型', minWidth: 150, slotName: 'feeItemSummary' },
+      { key: 'currency', label: '币种', width: 80 },
+      { key: 'receivableAmount', label: '应收金额', width: 130, slotName: 'money' },
+      { key: 'receivedAmount', label: '已收', width: 120, slotName: 'paidMoney' },
+      { key: 'outstandingAmount', label: '余额', width: 120, slotName: 'outstandingMoney' },
+      { key: 'reconciliationStatementNo', label: '关联对账单', minWidth: 180, slotName: 'reconciliationStatementNo' },
+      { key: 'businessPeriod', label: '结算周期', width: 120, slotName: 'businessPeriod' },
+      { key: 'generatedDate', label: '生成日期', width: 130, slotName: 'generatedDate' },
+      { key: 'dueDate', label: '到期日', width: 130, slotName: 'dueDate' },
+      { key: 'paymentStatus', label: '收款状态', width: 120, slotName: 'paymentStatus' },
+      { key: 'createdByName', label: '制单人', minWidth: 130, slotName: 'createdByName' },
+      { key: 'createdAt', label: '创建时间', width: 170, slotName: 'createdAt' },
+      { key: 'lastPaymentAt', label: '最后收款时间', width: 170, slotName: 'lastPaymentAt' },
+      { key: 'status', label: '结算状态', width: 120, slotName: 'settlementStatus' },
+    ]
+  : [
+      { key: 'actions', label: '操作', width: 250, fixed: 'left', slotName: 'actions' },
+      { key: 'settlementNo', label: '结算单号', minWidth: 180 },
+      { key: 'supplierName', label: '供应商', minWidth: 180, slotName: 'supplier' },
+      { key: 'customerId', label: '客户', minWidth: 180, slotName: 'customer' },
+      { key: 'feeItemSummary', label: '费用类型', minWidth: 150, slotName: 'feeItemSummary' },
+      { key: 'currency', label: '币种', width: 80 },
+      { key: 'payableAmount', label: '应付金额', width: 130, slotName: 'money' },
+      { key: 'paidAmount', label: '已付', width: 120, slotName: 'paidMoney' },
+      { key: 'outstandingAmount', label: '余额', width: 120, slotName: 'outstandingMoney' },
+      { key: 'businessPeriod', label: '结算周期', width: 120, slotName: 'businessPeriod' },
+      { key: 'generatedDate', label: '生成日期', width: 130, slotName: 'generatedDate' },
+      { key: 'dueDate', label: '到期日', width: 130, slotName: 'dueDate' },
+      { key: 'paymentStatus', label: '付款状态', width: 120, slotName: 'paymentStatus' },
+      { key: 'createdByName', label: '制单人', minWidth: 130, slotName: 'createdByName' },
+      { key: 'createdAt', label: '创建时间', width: 170, slotName: 'createdAt' },
+      { key: 'lastPaymentAt', label: '最后付款时间', width: 170, slotName: 'lastPaymentAt' },
+      { key: 'status', label: '结算状态', width: 120, slotName: 'settlementStatus' },
+    ])
+
+function money(value: number) { return `¥${Number(value || 0).toLocaleString('zh-CN', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}` }
+function displayDate(value?: string) { return value || '—' }
+function displayDateTime(value?: string) { return value ? value.replace('T', ' ').slice(0, 16) : '—' }
+function settlementPaymentStatusLabel(status?: string) {
+  if (status === 'UNPAID') return props.kind === 'receivable' ? '待收款' : '待付款'
+  if (status === 'PARTIALLY_PAID') return props.kind === 'receivable' ? '部分收款' : '部分付款'
+  if (status === 'PAID') return '已结清'
+  return '—'
+}
+function paymentMethodLabel(method?: string) {
+  return ({ BANK_TRANSFER: '银行转账', CASH: '现金', OTHER: '其他' } as Record<string, string>)[String(method || '')] || '—'
+}
+function operatorDisplayName(value?: string) {
+  const candidate = String(value || '').trim()
+  return candidate && !/^(?:operator-)?\d+$/i.test(candidate) ? candidate : '名称数据缺失'
+}
+function settlementRevisionActionLabel(action: string) {
+  return ({
+    SUBMIT: '提交审核',
+    APPROVE: '审核通过',
+    REJECT: '审核驳回',
+    ISSUE: '出账',
+    ADJUST: '调整',
+    VOID: '作废',
+    REOPEN: '重开',
+    RECEIPT: '收款登记',
+    PAYMENT: '付款登记',
+  } as Record<string, string>)[action] || financeOperationActionLabel(action)
+}
+function rowTotal(value: unknown) { return totalAmount(value as SettlementRow) }
+function rowPaid(value: unknown) { return paidAmount(value as SettlementRow) }
+function rowOutstanding(value: unknown) { return Number((value as SettlementRow).outstandingAmount || 0) }
+function customerName(customerId: string, snapshot?: string) {
+  const mappedName = customers.value.find((item) => String(item.id) === String(customerId))?.tenantName
+  // Backend snapshots may contain the internal fallback label; never promote that ID to the finance UI.
+  if (snapshot && !/^客户\d+$/.test(snapshot.trim())) return snapshot
+  return mappedName || '—'
+}
+function totalAmount(row: SettlementRow) { return props.kind === 'receivable' ? (row as FinanceReceivableSettlement).receivableAmount : (row as FinancePayableSettlement).payableAmount }
+function paidAmount(row: SettlementRow) { return props.kind === 'receivable' ? (row as FinanceReceivableSettlement).receivedAmount : (row as FinancePayableSettlement).paidAmount }
+function selectedSupplierName() { return selectedRow.value && 'supplierName' in selectedRow.value ? selectedRow.value.supplierName || '—' : '—' }
+function detailPartyName() { return !detail.value ? '—' : props.kind === 'receivable' ? customerName(detail.value.customerId, detail.value.customerName) : detail.value.supplierName || selectedSupplierName() }
+function detailActionRow(): SettlementRow {
+  const current = detail.value!
+  return props.kind === 'receivable'
+    ? { id: current.id, customerId: current.customerId, customerName: current.customerName || '', settlementNo: current.settlementNo, billDate: current.generatedDate || '', dueDate: current.dueDate || '', receivableAmount: current.amount, receivedAmount: current.paidAmount, outstandingAmount: current.outstandingAmount, currency: 'CNY', status: current.status as FinanceReceivableSettlement['status'], version: current.version }
+    : { id: current.id, customerId: current.customerId, settlementNo: current.settlementNo, costType: 'SINGLE_ORDER', orderId: null, inboundId: null, containerId: null, supplierName: current.supplierName || '', feeItemName: '', payableAmount: current.amount, paidAmount: current.paidAmount, outstandingAmount: current.outstandingAmount, currency: 'CNY', status: current.status, createdAt: current.generatedDate || '', version: current.version }
+}
+function remainingAfter(amount: number) { return money(Math.max(0, Number(detail.value?.outstandingAmount || 0) - Number(amount || 0))) }
+
+async function loadCustomers() {
+  if (!canListCustomers.value) return
+  customerError.value = null
+  try {
+    const records: PlatformTenantResource[] = []; let currentPage = 1; let pages = 1
+    do { const result = await listPlatformTenants({ page: currentPage, size: 200, status: 'ACTIVE' }); records.push(...result.records); pages = Math.max(1, result.pages); currentPage += 1 } while (currentPage <= pages)
+    customers.value = records
+  }
+  catch (cause) { customerError.value = getApiErrorDetails(cause, '客户列表加载失败') }
+}
+
+async function load(model?: QueryModel) {
+  if (model) {
+    filters.value = { ...model }
+    appliedFilters.value = { ...model }
+    page.value = 1
+  }
+  rows.value = []
+  error.value = null
+  loading.value = true
+  try {
+    const customerId = String(appliedFilters.value.customerId || '').trim() || undefined
+    rows.value = props.kind === 'receivable'
+      ? await listFinanceReceivableSettlements(customerId)
+      : await listFinancePayableSettlements(customerId)
+  } catch (cause) { error.value = getApiErrorDetails(cause, `${title.value}加载失败，请重试`) }
+  finally { loading.value = false }
+}
+
+function openDetail(row: unknown) {
+  selectedRow.value = row as SettlementRow
+  emit('openDetail', selectedRow.value.id)
+}
+
+async function loadDetail(settlementId: string) {
+  detail.value = null
+  detailError.value = null
+  detailLoading.value = true
+  try { detail.value = await getFinanceSettlement(settlementId) }
+  catch (cause) { detailError.value = getApiErrorDetails(cause, `${title.value}详情加载失败`) }
+  finally { detailLoading.value = false }
+}
+
+function backToList() { emit('back') }
+
+async function openCreate() {
+  createForm.value = {
+    customerId: '',
+    reconciliationStatementId: '',
+    supplierId: '',
+    feeSourceIds: [],
+    dueDate: '',
+  }
+  createOpen.value = true
+  error.value = null
+  try {
+    await refreshCreateDependencies()
+    if (props.kind === 'payable' && !suppliersLoaded.value) {
+      const suppliers = await listSuppliers({ page: 1, size: 200, status: 'ACTIVE' })
+      supplierOptions.value = suppliers.records.filter((item) => item.status === 'ACTIVE')
+      suppliersLoaded.value = true
+    }
+  } catch (cause) { error.value = getApiErrorDetails(cause, '结算来源加载失败') }
+}
+
+function resetCreateDependentFields() {
+  createForm.value.reconciliationStatementId = ''
+  createForm.value.supplierId = ''
+  createForm.value.feeSourceIds = []
+  createForm.value.dueDate = ''
+}
+
+async function refreshCreateDependencies(customerId?: string) {
+  const selectedCustomerId = String((customerId ?? createForm.value.customerId) || '').trim()
+  statementOptions.value = []
+  feeOptions.value = []
+  if (!selectedCustomerId) {
+    resetCreateDependentFields()
+    return
+  }
+
+  if (props.kind === 'receivable') {
+    statementOptions.value = (await listFinanceStatements(selectedCustomerId)).filter((item) => item.status === 'ISSUED')
+    return
+  }
+
+  const selectedSupplierId = String(createForm.value.supplierId || '').trim() || undefined
+  if (!selectedSupplierId) {
+    createForm.value.feeSourceIds = []
+    return
+  }
+  const fees = await listFinanceFeePool(selectedCustomerId, 'PAYABLE', selectedSupplierId)
+  feeOptions.value = fees.filter((item) => item.feeSourceId && item.status === 'AVAILABLE' && item.settlementMode?.toUpperCase() !== 'DIRECT_PAID')
+  if (createForm.value.supplierId && !supplierOptions.value.find((supplier) => String(supplier.id) === String(createForm.value.supplierId))) {
+    createForm.value.supplierId = ''
+  }
+  if (createForm.value.feeSourceIds.length) {
+    const available = new Set(feeOptions.value.map((item) => item.feeSourceId).filter(Boolean) as string[])
+    createForm.value.feeSourceIds = createForm.value.feeSourceIds.filter((id) => available.has(id))
+    if (!createForm.value.feeSourceIds.length && feeOptions.value.length) {
+      createForm.value.feeSourceIds = []
+    }
+  }
+}
+
+watch(() => createForm.value.customerId, (customerId) => {
+  if (createOpen.value) void refreshCreateDependencies(customerId)
+})
+watch(() => createForm.value.supplierId, () => {
+  if (!createOpen.value) return
+  createForm.value.feeSourceIds = []
+  feeOptions.value = []
+  if (createForm.value.customerId) void refreshCreateDependencies(createForm.value.customerId)
+})
+
+async function submitCreate() {
+  const customerId = String(createForm.value.customerId || '')
+  if (!customerId) return ElMessage.warning('请先选择客户')
+  if (props.kind === 'receivable' && !createForm.value.reconciliationStatementId) return ElMessage.warning('请选择已出账对账单')
+  if (props.kind === 'payable' && (!createForm.value.supplierId || !createForm.value.dueDate || !createForm.value.feeSourceIds.length)) return ElMessage.warning('请完整填写供应商、到期日和费用来源')
+  createBusy.value = true
+  try {
+    if (props.kind === 'receivable') await createReceivableSettlement({ reconciliationStatementId: createForm.value.reconciliationStatementId, currency: 'CNY' })
+    else await createPayableSettlement({ customerId, supplierId: createForm.value.supplierId, feeSourceIds: createForm.value.feeSourceIds, dueDate: createForm.value.dueDate, currency: 'CNY' })
+    createOpen.value = false
+    ElMessage.success(`${title.value}已生成`)
+    await load()
+  } catch (cause) { error.value = getApiErrorDetails(cause, `${title.value}生成失败`) }
+  finally { createBusy.value = false }
+}
+
+function openPayment(row: unknown) {
+  const settlement = row as FinancePayableSettlement
+  selectedRow.value = settlement
+  detail.value = { id: settlement.id, settlementNo: settlement.settlementNo, customerId: settlement.customerId, direction: 'PAYABLE', amount: settlement.payableAmount, paidAmount: settlement.paidAmount, outstandingAmount: settlement.outstandingAmount, currency: 'CNY', status: settlement.status, version: settlement.version, lines: [], transactions: [], revisions: [] }
+  paymentFile.value = null
+  paymentForm.value = { transactionDate: new Date().toISOString().slice(0, 10), amount: settlement.outstandingAmount, method: 'BANK_TRANSFER', referenceNo: '', remark: '' }
+  paymentOpen.value = true
+}
+
+function openPaymentFromDetail() {
+  if (!detail.value) return
+  openPayment({ id: detail.value.id, settlementNo: detail.value.settlementNo, customerId: detail.value.customerId, supplierName: detail.value.supplierName || '', feeItemName: '', payableAmount: detail.value.amount, paidAmount: detail.value.paidAmount, outstandingAmount: detail.value.outstandingAmount, currency: 'CNY', status: detail.value.status, version: detail.value.version })
+}
+
+function selectPaymentFile(file: UploadFile) { paymentFile.value = file.raw ?? null }
+
+async function openReceipt(row: unknown) {
+  const settlement = row as FinanceReceivableSettlement
+  selectedRow.value = settlement
+  receiptError.value = null
+  receiptValidationError.value = null
+  receiptBusy.value = true
+  try {
+    const current = await getFinanceSettlement(settlement.id)
+    if (!current.reconciliationStatementId) throw new Error('应收结算单缺少对账单关联')
+    detail.value = current
+    receiptFile.value = null
+    receiptForm.value = { receivedDate: new Date().toISOString().slice(0, 10), amount: current.outstandingAmount, paymentMethod: 'BANK_TRANSFER', remark: '' }
+    receiptOpen.value = true
+  } catch (cause) { receiptError.value = getApiErrorDetails(cause, '应收结算单加载失败，无法登记收款') }
+  finally { receiptBusy.value = false }
+}
+
+async function openReceiptFromDetail() {
+  if (!detail.value) return
+  await openReceipt({ id: detail.value.id, customerId: detail.value.customerId, settlementNo: detail.value.settlementNo, receivableAmount: detail.value.amount, receivedAmount: detail.value.paidAmount, outstandingAmount: detail.value.outstandingAmount, currency: 'CNY', status: detail.value.status, version: detail.value.version })
+}
+
+function selectReceiptFile(file: UploadFile) {
+  const raw = file.raw
+  if (!raw || !raw.type.startsWith('image/')) {
+    receiptFile.value = null
+    receiptValidationError.value = '收款凭证仅支持图片文件'
+    receiptUploadKey.value += 1
+    return
+  }
+  receiptFile.value = raw
+  receiptValidationError.value = null
+  receiptError.value = null
+}
+
+async function submitReceipt() {
+  const current = detail.value
+  if (!current?.reconciliationStatementId || !receiptFile.value || receiptForm.value.amount <= 0) {
+    receiptValidationError.value = '请填写收款金额并选择收款凭证'
+    return
+  }
+  receiptError.value = null
+  receiptBusy.value = true
+  try {
+    const voucher = await uploadFinanceVoucher(current.customerId, receiptFile.value)
+    await createFinanceReceipt({ customerId: current.customerId, receivedDate: receiptForm.value.receivedDate, amount: receiptForm.value.amount, paymentMethod: receiptForm.value.paymentMethod, remark: receiptForm.value.remark || undefined, allocations: [{ billId: current.reconciliationStatementId, amount: receiptForm.value.amount }] }, [voucher.fileId])
+    receiptOpen.value = false
+    ElMessage.success('收款已登记')
+    if (detailMode.value) await loadDetail(current.id)
+    else await load()
+  } catch (cause) { receiptError.value = getApiErrorDetails(cause, '收款登记失败') }
+  finally { receiptBusy.value = false }
+}
+
+async function submitPayment() {
+  if (!detail.value || !paymentFile.value || paymentForm.value.amount <= 0) return ElMessage.warning('请填写付款金额并选择付款凭证')
+  paymentBusy.value = true
+  try {
+    const voucher = await uploadFinanceVoucher(detail.value.customerId, paymentFile.value)
+    await createFinanceSettlementPayment(detail.value.id, { ...paymentForm.value, currency: 'CNY', voucherFileIds: [voucher.fileId], expectedVersion: detail.value.version })
+    paymentOpen.value = false
+    ElMessage.success('付款已登记')
+    if (detailMode.value) await loadDetail(detail.value.id)
+    else await load()
+  } catch (cause) { error.value = getApiErrorDetails(cause, '付款登记失败') }
+  finally { paymentBusy.value = false }
+}
+
+async function performAction(row: SettlementRow, action: 'VOID' | 'REOPEN') {
+  const reason = await ElMessageBox.prompt('请输入操作原因', action === 'VOID' ? `作废${title.value}` : `重开${title.value}`, {
+    customClass: 'admin-density-confirm',
+    inputType: 'textarea', inputPattern: /\S+/, inputErrorMessage: '操作原因不能为空', confirmButtonText: '确认', cancelButtonText: '取消',
+  }).then((result) => result.value.trim()).catch(() => null)
+  if (reason === null) return
+  actionBusy.value = true
+  try {
+    await actionFinanceSettlement(row.id, { action, reason, expectedVersion: row.version })
+    ElMessage.success(action === 'VOID' ? '结算单已作废' : '结算单已重开')
+    if (detailMode.value) await loadDetail(row.id)
+    else await load()
+  } catch (cause) { error.value = getApiErrorDetails(cause, `${action === 'VOID' ? '作废' : '重开'}结算单失败`) }
+  finally { actionBusy.value = false }
+}
+
+async function createSettlementExport(detailId?: string) {
+  const isDetail = Boolean(detailId)
+  const taskName = props.kind === 'receivable'
+    ? (isDetail ? '应收结算单详情' : '应收结算单列表')
+    : (isDetail ? '应付结算单详情' : '应付结算单列表')
+  const exportType = props.kind === 'receivable'
+    ? (isDetail ? 'FINANCE_RECEIVABLE_SETTLEMENT_DETAIL' : 'FINANCE_RECEIVABLE_SETTLEMENT_LIST')
+    : (isDetail ? 'FINANCE_PAYABLE_SETTLEMENT_DETAIL' : 'FINANCE_PAYABLE_SETTLEMENT_LIST')
+  const settlementId = String(detailId || '')
+  if (isDetail && !/^[1-9]\d*$/.test(settlementId)) return ElMessage.error('结算单业务标识无效，无法创建导出任务')
+  const parameters: Record<string, string> = isDetail ? { settlementId } : {}
+  if (!isDetail) {
+    const customerId = String(filters.value.customerId || '').trim()
+    if (customerId && !/^[1-9]\d*$/.test(customerId)) return ElMessage.error('客户业务标识无效，无法创建导出任务')
+    const status = String(filters.value.status || '').trim()
+    const settlementNo = String(filters.value.settlementNo || '').trim()
+    const supplierName = String(filters.value.supplierName || '').trim()
+    if (customerId) parameters.customerId = customerId
+    if (status) parameters.status = status
+    if (settlementNo) parameters.settlementNo = settlementNo
+    if (props.kind === 'payable' && supplierName) parameters.supplierName = supplierName
+  }
+
+  exportSubmitting.value = true
+  try {
+    const task = await createPlatformExportTask({
+      exportType,
+      format: 'XLSX',
+      taskName,
+      parameters,
+    })
+    const openDownloadCenter = await showExportTaskCreatedDialog({ taskName: task.taskName, taskNo: task.taskNo, dense: true })
+    if (openDownloadCenter) await router.push({ name: 'download-center' })
+  } catch (cause) {
+    ElMessage.error(getApiErrorMessage(cause, `${taskName}导出任务创建失败`))
+  } finally {
+    exportSubmitting.value = false
+  }
+}
+
+function exportRows() { return createSettlementExport() }
+function exportDetail() { return detail.value ? createSettlementExport(detail.value.id) : undefined }
+
+onMounted(() => {
+  if (canListCustomers.value) void loadCustomers()
+  const settlementId = String(props.settlementId || '')
+  if (settlementId) void loadDetail(settlementId)
+  else void load()
+})
+</script>
+
+<template>
+  <AdminPage as="div" class="finance-settlement-page admin-density" spacing="normal">
+    <OperationErrorToast :message="receiptValidationError" />
+    <OperationErrorToast :details="receiptError" />
+    <el-result v-if="!canView" icon="warning" :title="`无权访问${title}`" sub-title="请联系管理员开通结算单查看权限" />
+    <DetailPageLayout v-else-if="detailMode" class="settlement-detail-page surface-panel finance-density-detail" :aria-label="`${title}详情`">
+      <template #header><div class="density-detail-header"><div class="density-detail-heading"><el-button link class="density-back" aria-label="返回列表" @click="backToList"><ArrowLeft :size="16" />返回列表</el-button><h1 class="density-detail-title">{{ detail?.settlementNo || '—' }}</h1><StatusBadge v-if="detail" :status="financeStatusLabel(detail.status)" /></div><div class="finance-detail-actions">
+          <el-button v-if="detail && canExport" :loading="exportSubmitting" :disabled="exportSubmitting" @click="exportDetail"><Download :size="15" />导出</el-button>
+          <el-button v-if="detail && canReceive && ['ISSUED','PARTIALLY_PAID'].includes(detail.status)" type="primary" :loading="receiptBusy" @click="openReceiptFromDetail"><HandCoins :size="15" />部分收款</el-button>
+          <el-button v-if="detail && canPay && ['ISSUED','PARTIALLY_PAID'].includes(detail.status)" type="primary" @click="openPaymentFromDetail"><CreditCard :size="15" />部分付款</el-button>
+          <el-button v-if="detail && canVoid && detail.status === 'ISSUED'" type="danger" :loading="actionBusy" @click="performAction(detailActionRow(), 'VOID')"><XCircle :size="15" />作废</el-button>
+          <el-button v-if="detail && canVoid && detail.status === 'VOIDED'" :loading="actionBusy" @click="performAction(detailActionRow(), 'REOPEN')"><RotateCcw :size="15" />重开</el-button>
+        </div></div></template>
+      <template v-if="detail" #summary>
+        <dl class="density-detail-overview settlement-detail-summary" aria-label="结算金额汇总">
+          <div class="summary-item"><dt>{{ kind === 'receivable' ? '应收金额' : '应付金额' }}</dt><dd>{{ money(detail.amount) }}</dd></div>
+          <div class="summary-item"><dt>{{ kind === 'receivable' ? '已收金额' : '已付金额' }}</dt><dd class="is-success">{{ money(detail.paidAmount) }}</dd></div>
+          <div class="summary-item"><dt>未结余额</dt><dd class="is-danger">{{ money(detail.outstandingAmount) }}</dd></div>
+          <div class="summary-item"><dt>到期日</dt><dd class="is-date">{{ displayDate(detail.dueDate) }}</dd></div>
+        </dl>
+      </template>
+      <LoadErrorState v-if="detailError" class="settlement-detail-state" :title="`${title}详情加载失败`" :message="detailError.message" :loading="detailLoading" @retry="loadDetail(String(settlementId || ''))"><template #details><ApiErrorMeta :details="detailError" /></template></LoadErrorState>
+      <el-skeleton v-else-if="detailLoading" class="settlement-detail-state" :rows="10" animated />
+      <section v-else-if="detail" class="settlement-detail-content">
+        <FormSection class="density-form-section" title="基本信息">
+          <el-descriptions border :column="4" class="settlement-detail-info density-descriptions">
+            <el-descriptions-item label="结算单号">{{ detail.settlementNo }}</el-descriptions-item>
+            <el-descriptions-item :label="kind === 'receivable' ? '客户' : '供应商'">{{ detailPartyName() }}</el-descriptions-item>
+            <el-descriptions-item v-if="kind === 'payable'" label="客户">{{ customerName(detail.customerId, detail.customerName) }}</el-descriptions-item>
+            <el-descriptions-item label="币种">CNY</el-descriptions-item>
+            <el-descriptions-item :label="kind === 'receivable' ? '收款状态' : '付款状态'"><el-tag :type="financeStatusTone(detail.paymentStatus)">{{ settlementPaymentStatusLabel(detail.paymentStatus) }}</el-tag></el-descriptions-item>
+            <el-descriptions-item label="结算状态"><el-tag :type="financeStatusTone(detail.status)">{{ financeStatusLabel(detail.status) }}</el-tag></el-descriptions-item>
+            <el-descriptions-item label="关联对账单">{{ detail.reconciliationStatementNo || '—' }}</el-descriptions-item>
+            <el-descriptions-item label="结算周期">{{ detail.businessPeriod || '—' }}</el-descriptions-item>
+            <el-descriptions-item label="费用类型">{{ detail.feeItemSummary || '—' }}</el-descriptions-item>
+            <el-descriptions-item label="生成日期">{{ displayDate(detail.generatedDate) }}</el-descriptions-item>
+            <el-descriptions-item label="到期日">{{ displayDate(detail.dueDate) }}</el-descriptions-item>
+            <el-descriptions-item label="制单人">{{ operatorDisplayName(detail.createdByName) }}</el-descriptions-item>
+            <el-descriptions-item label="创建时间">{{ displayDateTime(detail.createdAt) }}</el-descriptions-item>
+            <el-descriptions-item :label="kind === 'receivable' ? '最后收款时间' : '最后付款时间'">{{ displayDateTime(detail.lastPaymentAt) }}</el-descriptions-item>
+          </el-descriptions>
+        </FormSection>
+        <FormSection class="density-form-section" title="费用明细">
+          <div class="detail-table-scroll">
+          <el-table :data="detail.lines" size="small" border stripe empty-text="暂无费用明细">
+            <el-table-column prop="feeItemName" label="费用类型" min-width="150" />
+            <el-table-column prop="sourceType" label="来源类型" min-width="140"><template #default="scope">{{ financeSourceTypeLabel(scope.row.sourceType) }}</template></el-table-column>
+            <el-table-column prop="orderNo" label="订单号" min-width="160"><template #default="scope">{{ scope.row.orderNo || '—' }}</template></el-table-column>
+            <el-table-column prop="inboundCode" label="入仓码" min-width="130"><template #default="scope">{{ scope.row.inboundCode || '—' }}</template></el-table-column>
+            <el-table-column prop="containerNo" label="柜次号" min-width="130"><template #default="scope">{{ scope.row.containerNo || '—' }}</template></el-table-column>
+            <el-table-column prop="businessDate" label="业务发生日" width="120"><template #default="scope">{{ displayDate(scope.row.businessDate) }}</template></el-table-column>
+            <el-table-column prop="amount" label="金额(CNY)" width="130" align="right"><template #default="scope">{{ money(scope.row.amount) }}</template></el-table-column>
+          </el-table>
+          </div>
+        </FormSection>
+        <FormSection class="density-form-section" :title="kind === 'receivable' ? '收款记录' : '付款记录'">
+          <div class="detail-table-scroll">
+          <el-table :data="detail.transactions" size="small" border stripe :empty-text="kind === 'receivable' ? '暂无收款记录' : '暂无付款记录'">
+            <el-table-column prop="transactionDate" :label="kind === 'receivable' ? '收款日期' : '付款日期'" width="130" />
+            <el-table-column prop="amount" label="金额(CNY)" width="130" align="right"><template #default="scope">{{ money(scope.row.amount) }}</template></el-table-column>
+            <el-table-column prop="method" :label="kind === 'receivable' ? '收款方式' : '付款方式'" min-width="130"><template #default="scope">{{ paymentMethodLabel(scope.row.method) }}</template></el-table-column>
+            <el-table-column prop="referenceNo" label="银行流水号/凭证号" min-width="180"><template #default="scope">{{ scope.row.referenceNo || '—' }}</template></el-table-column>
+            <el-table-column label="登记人" min-width="140"><template #default="scope">{{ operatorDisplayName(scope.row.createdByName) }}</template></el-table-column>
+            <el-table-column label="登记时间" min-width="170"><template #default="scope">{{ displayDateTime(scope.row.createdAt) }}</template></el-table-column>
+            <el-table-column label="凭证" width="130"><template #default="scope">{{ scope.row.voucherFileIds.length ? `已上传 ${scope.row.voucherFileIds.length} 个` : '—' }}</template></el-table-column>
+            <el-table-column prop="remark" label="备注" min-width="180"><template #default="scope">{{ scope.row.remark || '—' }}</template></el-table-column>
+          </el-table>
+          </div>
+        </FormSection>
+        <FormSection class="density-form-section" title="修订记录" :bordered="false">
+          <div class="detail-table-scroll">
+          <el-table :data="detail.revisions" size="small" border stripe empty-text="暂无调整记录">
+            <el-table-column prop="action" label="动作" min-width="120"><template #default="scope">{{ settlementRevisionActionLabel(scope.row.action) || financeOperationActionLabel(scope.row.action) }}</template></el-table-column>
+            <el-table-column prop="beforeAmount" label="调整前(CNY)" width="140" align="right"><template #default="scope">{{ money(scope.row.beforeAmount) }}</template></el-table-column>
+            <el-table-column prop="afterAmount" label="调整后(CNY)" width="140" align="right"><template #default="scope">{{ money(scope.row.afterAmount) }}</template></el-table-column>
+            <el-table-column prop="reason" label="原因" min-width="180"><template #default="scope">{{ scope.row.reason || '—' }}</template></el-table-column>
+            <el-table-column label="操作人" min-width="140"><template #default="scope">{{ operatorDisplayName(scope.row.operatorName) }}</template></el-table-column>
+            <el-table-column prop="occurredAt" label="时间" min-width="160"><template #default="scope">{{ displayDateTime(scope.row.occurredAt) }}</template></el-table-column>
+          </el-table>
+          </div>
+        </FormSection>
+      </section>
+    </DetailPageLayout>
+    <ListPageLayout v-else :aria-label="title">
+      <template #toolbar>
+        <QueryToolbar v-model="filters" class="surface-panel" :ariaLabel="`${title}筛选`" :fields="fields" :preference-key="`finance-settlement-${kind}-query`" :search-on-clear="false" @search="load" />
+      </template>
+      <template v-if="customerError || error" #state>
+        <LoadErrorState :title="`${title}加载失败`" :message="(customerError || error)?.message || ''" :loading="loading" @retry="customerError ? loadCustomers() : load()"><template #details><ApiErrorMeta :details="(customerError || error)!" /></template></LoadErrorState>
+      </template>
+      <template v-if="!customerError && !error">
+        <section class="surface-panel table-panel">
+          <DataTable v-model:page="page" v-model:page-size="pageSize" :data="paginatedRows" :columns="columns" :loading="loading" :total="filteredRows.length" :aria-label="`${title}列表`" row-key="id" empty-text="暂无符合条件的结算单">
+            <template #toolbar-start>
+              <dl class="density-detail-overview settlement-summary" aria-label="结算汇总">
+                <div class="summary-item"><dt>{{ kind === 'receivable' ? '应收总额' : '应付总额' }}</dt><dd>{{ money(totals.amount) }}</dd></div>
+                <div class="summary-item"><dt>{{ kind === 'receivable' ? '已收' : '已付' }}</dt><dd class="is-success">{{ money(totals.paid) }}</dd></div>
+                <div class="summary-item"><dt>{{ kind === 'receivable' ? '待收' : '待付' }}</dt><dd class="is-danger">{{ money(totals.outstanding) }}</dd></div>
+              </dl>
+            </template>
+            <template #toolbar-actions>
+              <div class="settlement-list-actions">
+                <el-button v-if="canCreate" type="primary" @click="openCreate"><Plus :size="15" />{{ createLabel }}</el-button>
+                <el-button v-if="canExport" :loading="exportSubmitting" :disabled="loading || exportSubmitting" @click="exportRows"><Download :size="15" />导出</el-button>
+              </div>
+            </template>
+            <template #actions="{ row }">
+              <div class="settlement-row-actions density-actions">
+                <el-button data-tone="neutral" class="density-action" size="small" @click="openDetail(row)">详情</el-button>
+                <el-button data-tone="neutral" class="density-action" v-if="canReceive && ['ISSUED','PARTIALLY_PAID'].includes(String(row.status))" size="small" :loading="receiptBusy" @click="openReceipt(row)">收款</el-button>
+                <el-button data-tone="neutral" class="density-action" v-if="canPay && ['ISSUED','PARTIALLY_PAID'].includes(String(row.status))" size="small" @click="openPayment(row)">付款</el-button>
+                <el-button data-tone="danger" class="density-action" v-if="canVoid && row.status === 'ISSUED'" size="small" :loading="actionBusy" @click="performAction(row as SettlementRow, 'VOID')">作废</el-button>
+                <el-button data-tone="neutral" class="density-action" v-if="canVoid && row.status === 'VOIDED'" size="small" :loading="actionBusy" @click="performAction(row as SettlementRow, 'REOPEN')">重开</el-button>
+              </div>
+            </template>
+            <template #customer="{ row }">{{ customerName(String(row.customerId), row.customerName) }}</template>
+            <template #supplier="{ row }">{{ row.supplierName || '—' }}</template>
+            <template #feeItemSummary="{ row }">{{ row.feeItemSummary || '—' }}</template>
+            <template #money="{ row }">{{ money(rowTotal(row)) }}</template>
+            <template #paidMoney="{ row }">{{ money(rowPaid(row)) }}</template>
+            <template #outstandingMoney="{ row }">{{ money(rowOutstanding(row)) }}</template>
+            <template #reconciliationStatementNo="{ row }">{{ row.reconciliationStatementNo || '—' }}</template>
+            <template #businessPeriod="{ row }">{{ row.businessPeriod || '—' }}</template>
+            <template #generatedDate="{ row }">{{ displayDate(row.generatedDate) }}</template>
+            <template #dueDate="{ row }">{{ displayDate((row as FinanceReceivableSettlement).dueDate) }}</template>
+            <template #paymentStatus="{ row }"><el-tag :type="financeStatusTone(row.paymentStatus)">{{ settlementPaymentStatusLabel(row.paymentStatus) }}</el-tag></template>
+            <template #createdByName="{ row }">{{ operatorDisplayName(row.createdByName) }}</template>
+            <template #createdAt="{ row }">{{ displayDateTime(row.createdAt) }}</template>
+            <template #lastPaymentAt="{ row }">{{ displayDateTime(row.lastPaymentAt) }}</template>
+            <template #settlementStatus="{ row }"><el-tag :type="financeStatusTone(row.status)">{{ financeStatusLabel(row.status) }}</el-tag></template>
+            <template #pagination-left>共 {{ filteredRows.length }} 条 · 币种：CNY</template>
+          </DataTable>
+        </section>
+      </template>
+    </ListPageLayout>
+
+    <AppDialog class="admin-density-dialog" v-model="createOpen" :title="`生成${title}`" width="min(600px, 94vw)" :confirm-loading="createBusy" @confirm="submitCreate">
+      <el-form class="density-form" label-position="top">
+        <el-form-item label="客户"><el-select v-model="createForm.customerId" filterable placeholder="请选择客户"><el-option v-for="item in activeCustomers" :key="String(item.id)" :label="item.tenantName" :value="String(item.id)" /></el-select></el-form-item>
+        <el-form-item v-if="kind === 'receivable'" label="已出账对账单"><el-select v-model="createForm.reconciliationStatementId" filterable><el-option v-for="item in statementOptions" :key="item.id" :label="`${item.billNo} · ${item.outstandingAmount} CNY`" :value="item.id" /></el-select></el-form-item>
+        <template v-else><el-form-item label="供应商"><el-select v-model="createForm.supplierId" filterable placeholder="请选择供应商"><el-option v-for="item in supplierOptions" :key="String(item.id)" :label="`${item.name} · ${categoryLabels[item.category]}`" :value="String(item.id)" /></el-select></el-form-item><el-form-item label="到期日"><el-date-picker v-model="createForm.dueDate" type="date" value-format="YYYY-MM-DD" /></el-form-item><el-form-item label="应付费用来源"><el-select v-model="createForm.feeSourceIds" multiple filterable><el-option v-for="item in feeOptions" :key="item.feeSourceId!" :label="`${item.feeItemName} · ${item.amount} CNY`" :value="item.feeSourceId!" /></el-select></el-form-item></template>
+      </el-form>
+    </AppDialog>
+
+    <AppDialog class="admin-density-dialog" v-model="paymentOpen" title="登记付款" width="min(760px, 94vw)" :confirm-loading="paymentBusy" @confirm="submitPayment">
+      <dl v-if="detail" class="density-detail-overview partial-summary"><div><dt>结算单号</dt><dd>{{ detail.settlementNo }}</dd></div><div><dt>供应商</dt><dd>{{ detailPartyName() }}</dd></div><div><dt>应付金额</dt><dd>{{ money(detail.amount) }}</dd></div><div><dt>已付金额</dt><dd class="is-success">{{ money(detail.paidAmount) }}</dd></div><div><dt>当前余额</dt><dd class="is-danger">{{ money(detail.outstandingAmount) }}</dd></div></dl>
+      <el-form class="settlement-operation-form density-form" label-position="top"><el-form-item label="付款日期"><el-date-picker v-model="paymentForm.transactionDate" type="date" value-format="YYYY-MM-DD" /></el-form-item><el-form-item label="本次付款金额(CNY)"><el-input-number v-model="paymentForm.amount" :min="0.01" :max="detail?.outstandingAmount || 0.01" :precision="2" placeholder="请输入付款金额" /></el-form-item><el-form-item label="付款方式"><el-select v-model="paymentForm.method"><el-option label="银行转账" value="BANK_TRANSFER" /><el-option label="现金" value="CASH" /><el-option label="其他" value="OTHER" /></el-select></el-form-item><el-form-item label="银行流水号/凭证号"><el-input v-model="paymentForm.referenceNo" placeholder="请输入付款流水号" /></el-form-item><el-form-item label="付款凭证"><el-upload :auto-upload="false" :limit="1" accept="image/*" :on-change="selectPaymentFile"><el-button>选择图片</el-button></el-upload></el-form-item><el-form-item label="备注"><el-input v-model="paymentForm.remark" type="textarea" placeholder="请输入付款备注（选填）" /></el-form-item></el-form>
+      <div v-if="detail" class="remaining-preview"><span>登记后剩余余额</span><strong>{{ remainingAfter(paymentForm.amount) }}</strong></div>
+    </AppDialog>
+
+    <AppDialog class="admin-density-dialog" v-model="receiptOpen" title="登记收款" width="min(760px, 94vw)" :confirm-loading="receiptBusy" @confirm="submitReceipt">
+      <dl v-if="detail" class="density-detail-overview partial-summary"><div><dt>结算单号</dt><dd>{{ detail.settlementNo }}</dd></div><div><dt>客户公司</dt><dd>{{ detailPartyName() }}</dd></div><div><dt>应收金额</dt><dd>{{ money(detail.amount) }}</dd></div><div><dt>已收金额</dt><dd class="is-success">{{ money(detail.paidAmount) }}</dd></div><div><dt>当前余额</dt><dd class="is-danger">{{ money(detail.outstandingAmount) }}</dd></div></dl>
+      <el-form class="settlement-operation-form density-form" label-position="top"><el-form-item label="收款日期"><el-date-picker v-model="receiptForm.receivedDate" type="date" value-format="YYYY-MM-DD" /></el-form-item><el-form-item label="本次收款金额(CNY)"><el-input-number v-model="receiptForm.amount" :min="0.01" :max="detail?.outstandingAmount || 0.01" :precision="2" placeholder="请输入收款金额" /></el-form-item><el-form-item label="收款方式"><el-select v-model="receiptForm.paymentMethod"><el-option label="银行转账" value="BANK_TRANSFER" /><el-option label="现金" value="CASH" /><el-option label="其他" value="OTHER" /></el-select></el-form-item><el-form-item label="收款凭证"><el-upload :key="receiptUploadKey" :auto-upload="false" :limit="1" accept="image/*" :on-change="selectReceiptFile"><el-button>选择图片</el-button></el-upload></el-form-item><el-form-item label="备注"><el-input v-model="receiptForm.remark" type="textarea" placeholder="请输入收款备注（选填）" /></el-form-item></el-form>
+      <div v-if="detail" class="remaining-preview"><span>登记后剩余余额</span><strong>{{ remainingAfter(receiptForm.amount) }}</strong></div>
+    </AppDialog>
+  </AdminPage>
+</template>
+
+<style scoped>
+.finance-settlement-page { min-width: 0; }
+.settlement-summary, .settlement-list-actions { display: flex; min-width: 0; align-items: center; flex-wrap: wrap; }
+.settlement-summary { gap: var(--admin-space-2) 0; }
+.settlement-list-actions { flex: 0 0 auto; justify-content: flex-end; gap: var(--admin-space-3); }
+.settlement-list-actions :deep(.el-button + .el-button) { margin-left: 0; }
+.settlement-detail-page { display: flex; width: min(100%, 1920px); margin: 0 auto; min-width: 0; gap: 0; overflow: hidden; padding: 0; }
+.settlement-detail-actions { display: flex; align-items: center; gap: var(--admin-space-4); min-width: 0; flex-wrap: wrap; }
+.settlement-detail-state { margin: var(--admin-space-5) var(--admin-space-6); }
+.settlement-detail-content { min-width: 0; padding: 0 var(--admin-space-6) var(--admin-space-5); overflow: hidden; }
+.settlement-detail-info { min-width: 0; }
+.detail-table-scroll { min-width: 0; overflow-x: auto; }
+:deep(.settlement-detail-info .el-descriptions__table) { table-layout: fixed; }
+:deep(.settlement-detail-info .el-descriptions__content) { min-width: 0; overflow-wrap: anywhere; }
+:deep(.detail-table-scroll .el-table) { min-width: 920px; }
+.settlement-operation-form { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); column-gap: var(--admin-space-5); row-gap: 0; }
+.settlement-operation-form :deep(.el-form-item:last-child) { grid-column: 1 / -1; }
+.settlement-operation-form :deep(.el-input-number) { width: 100%; }
+.remaining-preview { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-4); padding: var(--admin-space-3) var(--admin-space-5); border-radius: var(--admin-radius); color: var(--cc-text-secondary, #64748b); background: var(--el-fill-color-light); }
+.remaining-preview strong { color: #b45309; font-size: var(--admin-font-section); }
+.operation-error { margin-bottom: var(--admin-space-5); }
+.operation-error-meta { margin: -var(--admin-space-2) 0 var(--admin-space-5); }
+:deep(.el-select), :deep(.el-date-editor) { width: 100%; }
+
+@media (min-width: 1920px) {
+  .finance-settlement-page {
+    row-gap: var(--admin-space-3);
+  }
+
+  .settlement-detail-page {
+    gap: 0;
+  }
+
+  .settlement-detail-state {
+    margin: var(--admin-space-4) var(--admin-space-5);
+  }
+
+  .settlement-detail-content {
+    padding: 0 var(--admin-space-5) var(--admin-space-4);
+  }
+
+  .detail-table-scroll {
+    margin-bottom: var(--admin-space-3);
+  }
+
+  .settlement-operation-form {
+    column-gap: var(--admin-space-5);
+  }
+}
+@media (max-width: 720px) {
+  .settlement-detail-summary, .partial-summary, .settlement-operation-form { grid-template-columns: 1fr; }
+  .settlement-detail-summary { gap: 10px; padding: 12px 16px; }
+  .settlement-detail-summary .summary-item { padding: 0; border-left: 0; }
+  .settlement-detail-content { padding: 0 16px 14px; }
+  .settlement-detail-state { margin: 14px; }
+  .partial-summary { gap: 10px; padding: 12px 10px; }
+  .partial-summary div { padding: 0; border-left: 0; }
+  .settlement-summary { align-items: flex-start; flex-direction: column; gap: 6px; }
+  .settlement-summary .summary-item + .summary-item { margin-left: 0; padding-left: 0; border-left: 0; }
+  .settlement-list-actions { width: 100%; justify-content: flex-start; }
+  .summary-item strong { font-size: 21px; }
+  .settlement-detail-header { align-items: flex-start; flex-direction: column; padding: 16px; }
+  .settlement-detail-actions { width: 100%; }
+  .settlement-detail-actions :deep(.el-button) { min-height: 40px; }
+  :deep(.settlement-detail-info .el-descriptions__cell) { display: block; width: 100%; }
+}
+</style>
diff --git a/src/modules/finance/pages/FinanceG3G4Operations.test.ts b/src/modules/finance/pages/FinanceG3G4Operations.test.ts
new file mode 100644
index 00000000..e83b63b3
--- /dev/null
+++ b/src/modules/finance/pages/FinanceG3G4Operations.test.ts
@@ -0,0 +1,223 @@
+import ElementPlus, { ElMessage, ElMessageBox } from 'element-plus'
+import { createPinia, setActivePinia } from 'pinia'
+import { createMemoryHistory, createRouter } from 'vue-router'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+import { listPlatformTenants, type PlatformTenantResource } from '@/modules/iam'
+import { ApiResponseError } from '@/shared/api/http'
+import {
+  actionFinanceSettlement,
+  actionReconciliationStatement,
+  createFinanceReceipt,
+  getFinanceSettlement,
+  getReconciliationStatement,
+  listFinancePayableSettlements,
+  listFinanceReceivableSettlements,
+  uploadFinanceVoucher,
+} from '../api/finance'
+import type { FinanceReconciliationDetail, FinanceSettlementDetail, FinanceStatementReadModel } from '../types'
+import FinanceCustomerStatementsView from './FinanceCustomerStatementsView.vue'
+import FinanceFormalSettlementPage from './FinanceFormalSettlementPage.vue'
+
+vi.mock('@/modules/iam', () => ({ listPlatformTenants: vi.fn() }))
+vi.mock('../api/finance', () => ({
+  actionFinanceSettlement: vi.fn(), actionReconciliationStatement: vi.fn(), createFinanceReceipt: vi.fn(), createFinanceSettlementPayment: vi.fn(),
+  createPayableSettlement: vi.fn(), createReceivableSettlement: vi.fn(), createReconciliationStatement: vi.fn(),
+  getFinanceSettlement: vi.fn(), getReconciliationStatement: vi.fn(), listFinanceFeePool: vi.fn(),
+  listFinancePayableSettlements: vi.fn(), listFinanceReceivableSettlements: vi.fn(), listFinanceStatements: vi.fn(),
+  uploadFinanceVoucher: vi.fn(),
+}))
+
+class ResizeObserverStub implements ResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+
+function createMemoryStorage(): Storage {
+  const values = new Map<string, string>()
+  return {
+    get length() { return values.size }, clear: () => values.clear(), getItem: (key) => values.get(key) ?? null,
+    key: (index) => [...values.keys()][index] ?? null, removeItem: (key) => values.delete(key), setItem: (key, value) => values.set(key, value),
+  }
+}
+
+function piniaWithPermissions(permissions: string[]) {
+  const pinia = createPinia()
+  setActivePinia(pinia)
+  const auth = useAuthStore()
+  auth.token = 'token'
+  auth.permissions = permissions
+  useAccessPreviewStore().initializeAfterLogin()
+  return pinia
+}
+
+const statement: FinanceStatementReadModel = {
+  id: '501', customerId: '10001', billNo: 'REC-501', customerName: '客户A', billDate: '2026-08-31',
+  dueDate: '2026-09-30', totalAmount: 300, receivedAmount: 0, outstandingAmount: 300,
+  currency: 'CNY', status: 'ISSUED', version: 3,
+}
+
+const reconciliation: FinanceReconciliationDetail = {
+  ...statement, paidAmount: 0, periodStart: '2026-08-01', periodEnd: '2026-08-31', creditDays: 30, settled: false,
+  remark: '', lines: [
+    { statementLineId: '601', sourceFeeId: '41', sourceFeeVersion: 1, orderId: null, inboundId: '91', feeItemName: '运费', amount: 100 },
+    { statementLineId: '602', sourceFeeId: '42', sourceFeeVersion: 1, orderId: null, inboundId: '92', feeItemName: '操作费', amount: 200 },
+  ], paymentHistory: [], revisions: [],
+}
+
+const receivable: FinanceSettlementDetail = {
+  id: '701', settlementNo: 'AR-701', customerId: '10001', reconciliationStatementId: '501', direction: 'RECEIVABLE',
+  amount: 300, paidAmount: 0, outstandingAmount: 300, currency: 'CNY', status: 'ISSUED', version: 0,
+  lines: [], transactions: [], revisions: [],
+}
+
+enableAutoUnmount(afterEach)
+afterAll(() => vi.unstubAllGlobals())
+
+describe('finance G3/G4 page operations', () => {
+  beforeEach(() => {
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+    vi.stubGlobal('localStorage', createMemoryStorage())
+    vi.stubGlobal('sessionStorage', createMemoryStorage())
+    document.body.innerHTML = ''
+    const customer = { id: '10001', tenantName: '客户A', status: 'ACTIVE' } as PlatformTenantResource
+    vi.mocked(listPlatformTenants).mockReset().mockResolvedValue({ records: [customer], page: 1, size: 200, total: 1, pages: 1 })
+    vi.mocked(actionReconciliationStatement).mockReset().mockResolvedValue(reconciliation)
+    vi.mocked(actionFinanceSettlement).mockReset().mockResolvedValue({ ...receivable, status: 'VOIDED', version: 1 })
+    vi.mocked(getReconciliationStatement).mockReset().mockResolvedValue(reconciliation)
+    vi.mocked(getFinanceSettlement).mockReset().mockResolvedValue(receivable)
+    vi.mocked(listFinanceReceivableSettlements).mockReset().mockResolvedValue([])
+    vi.mocked(listFinancePayableSettlements).mockReset().mockResolvedValue([])
+    vi.mocked(uploadFinanceVoucher).mockReset().mockResolvedValue({ fileId: '9001', customerId: '10001', fileName: 'receipt.png', contentType: 'image/png', sizeBytes: 100 })
+    vi.mocked(createFinanceReceipt).mockReset().mockResolvedValue({ id: '801', customerId: '10001', customerName: '客户A', receivedDate: '2026-08-11', amount: 300, currency: 'CNY', paymentMethod: 'BANK_TRANSFER', voucherFileIds: ['9001'], allocationCount: 1 })
+  })
+
+  it('loads frozen G3 detail and submits multiple selected adjustment lines', async () => {
+    const pinia = piniaWithPermissions(['platform:finance:customer-statement:list', 'platform:finance:reconciliation:adjust'])
+    const router = createRouter({ history: createMemoryHistory(), routes: [
+      { path: '/finance/customer-statements', name: 'finance-customer-statements', component: FinanceCustomerStatementsView },
+      { path: '/finance/customer-statements/:statementId', name: 'finance-customer-statement-detail', component: FinanceCustomerStatementsView },
+    ] })
+    await router.push('/finance/customer-statements'); await router.isReady()
+    const wrapper = mount(FinanceCustomerStatementsView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus, router] } })
+    await flushPromises()
+    const vm = wrapper.vm as unknown as {
+      openAdjustment(row: FinanceStatementReadModel): Promise<void>
+      submitAdjustment(): Promise<void>
+      adjustReason: string
+      adjustLines: Array<{ selected: boolean; adjustedAmount: number; reason: string }>
+    }
+
+    await vm.openAdjustment(statement)
+    vm.adjustReason = '账期复核调整'
+    vm.adjustLines[0]!.selected = true; vm.adjustLines[0]!.adjustedAmount = 90; vm.adjustLines[0]!.reason = '运费更正'
+    vm.adjustLines[1]!.selected = true; vm.adjustLines[1]!.adjustedAmount = 180; vm.adjustLines[1]!.reason = '操作费更正'
+    await vm.submitAdjustment()
+
+    expect(getReconciliationStatement).toHaveBeenCalledWith('501')
+    expect(actionReconciliationStatement).toHaveBeenCalledWith('501', {
+      action: 'ADJUST', reason: '账期复核调整', expectedVersion: 3,
+      adjustmentLines: [
+        { statementLineId: '601', adjustedAmount: 90, reason: '运费更正' },
+        { statementLineId: '602', adjustedAmount: 180, reason: '操作费更正' },
+      ],
+    })
+  }, 15_000)
+
+  it('loads AR linkage, uploads a voucher and allocates a real receipt to its statement', async () => {
+    const pinia = piniaWithPermissions(['platform:finance:settlement-ar:list', 'platform:finance:receipt:create'])
+    const wrapper = mount(FinanceFormalSettlementPage, { props: { kind: 'receivable' }, attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+    const vm = wrapper.vm as unknown as {
+      openReceipt(row: Record<string, unknown>): Promise<void>
+      submitReceipt(): Promise<void>
+      receiptFile: File | null
+      receiptForm: { receivedDate: string; amount: number; paymentMethod: 'BANK_TRANSFER'; remark: string }
+    }
+
+    await vm.openReceipt({ id: '701' })
+    vm.receiptFile = new File(['receipt'], 'receipt.png', { type: 'image/png' })
+    vm.receiptForm.receivedDate = '2026-08-11'; vm.receiptForm.amount = 300; vm.receiptForm.remark = '全额到账'
+    await vm.submitReceipt()
+
+    expect(uploadFinanceVoucher).toHaveBeenCalledWith('10001', vm.receiptFile)
+    expect(createFinanceReceipt).toHaveBeenCalledWith({
+      customerId: '10001', receivedDate: '2026-08-11', amount: 300, paymentMethod: 'BANK_TRANSFER', remark: '全额到账',
+      allocations: [{ billId: '501', amount: 300 }],
+    }, ['9001'])
+  })
+
+  it('shows receipt errors as dismissible light messages and rejects non-image vouchers before upload', async () => {
+    const messageSpy = vi.spyOn(ElMessage, 'error')
+    const pinia = piniaWithPermissions(['platform:finance:settlement-ar:list', 'platform:finance:receipt:create'])
+    const wrapper = mount(FinanceFormalSettlementPage, { props: { kind: 'receivable' }, attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+    const vm = wrapper.vm as unknown as {
+      openReceipt(row: Record<string, unknown>): Promise<void>
+      selectReceiptFile(file: { raw: File }): void
+      submitReceipt(): Promise<void>
+      receiptFile: File | null
+      receiptOpen: boolean
+      receiptValidationError: string | null
+      receiptError: { message: string } | null
+    }
+
+    vm.selectReceiptFile({ raw: new File(['not an image'], 'receipt.pdf', { type: 'application/pdf' }) })
+    expect(vm.receiptFile).toBeNull()
+    expect(vm.receiptValidationError).toBe('收款凭证仅支持图片文件')
+
+    await vm.openReceipt({ id: '701' })
+    vm.selectReceiptFile({ raw: new File(['receipt'], 'receipt.png', { type: 'image/png' }) })
+    vi.mocked(uploadFinanceVoucher).mockRejectedValueOnce(new ApiResponseError('FIN_400: 凭证校验失败', 'FIN_400', 400, undefined, 'request-1', 'trace-1'))
+    await vm.submitReceipt()
+    await flushPromises()
+
+    expect(vm.receiptOpen).toBe(true)
+    expect(vm.receiptError?.message).toContain('FIN_400')
+    expect(messageSpy).toHaveBeenCalledWith(expect.objectContaining({ message: expect.stringContaining('FIN_400'), showClose: true, duration: 4500 }))
+    expect(wrapper.text()).not.toContain('FIN_400')
+    expect(wrapper.find('[aria-label="结算单应收列表"]').exists()).toBe(true)
+  })
+
+  it('emits payable detail navigation and displays customer names without internal IDs', async () => {
+    const pinia = piniaWithPermissions(['platform:finance:settlement-ap:list'])
+    const wrapper = mount(FinanceFormalSettlementPage, { props: { kind: 'payable' }, attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+    const vm = wrapper.vm as unknown as { openDetail(row: Record<string, unknown>): void; customerName(customerId: string, snapshot?: string): string }
+
+    vi.mocked(getFinanceSettlement).mockClear()
+    vm.openDetail({ id: '801' })
+
+    expect(wrapper.emitted('openDetail')).toEqual([['801']])
+    expect(getFinanceSettlement).not.toHaveBeenCalled()
+    expect(vm.customerName('2088', '上海客户有限公司')).toBe('上海客户有限公司')
+    expect(vm.customerName('2088', '客户2088')).toBe('—')
+    expect(vm.customerName('2088')).toBe('—')
+  })
+
+  it('keeps settled settlements readable and exportable while hiding receipt actions', async () => {
+    vi.mocked(getFinanceSettlement).mockResolvedValue({ ...receivable, status: 'PAID', paidAmount: 300, outstandingAmount: 0 })
+    const pinia = piniaWithPermissions(['platform:finance:settlement-ar:list', 'platform:finance:settlement-ar:export', 'platform:finance:receipt:create', 'platform:download:list'])
+    const wrapper = mount(FinanceFormalSettlementPage, { props: { kind: 'receivable', settlementId: '701' }, attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('导出')
+    expect(wrapper.text()).not.toContain('部分收款')
+  })
+
+  it('submits settlement void and reopen actions with the current version and reason', async () => {
+    const prompt = vi.spyOn(ElMessageBox, 'prompt').mockResolvedValue({ value: '账务冲销' } as never)
+    const pinia = piniaWithPermissions(['platform:finance:settlement-ar:list', 'platform:finance:settlement:void'])
+    const wrapper = mount(FinanceFormalSettlementPage, { props: { kind: 'receivable' }, attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+    const vm = wrapper.vm as unknown as { performAction(row: Record<string, unknown>, action: 'VOID' | 'REOPEN'): Promise<void> }
+
+    await vm.performAction({ id: '701', version: 3 }, 'VOID')
+
+    expect(actionFinanceSettlement).toHaveBeenCalledWith('701', { action: 'VOID', reason: '账务冲销', expectedVersion: 3 })
+    prompt.mockRestore()
+  })
+})
diff --git a/src/modules/finance/pages/FinanceG3G4Views.test.ts b/src/modules/finance/pages/FinanceG3G4Views.test.ts
new file mode 100644
index 00000000..cd403677
--- /dev/null
+++ b/src/modules/finance/pages/FinanceG3G4Views.test.ts
@@ -0,0 +1,186 @@
+import ElementPlus from 'element-plus'
+import { createPinia, setActivePinia } from 'pinia'
+import { createMemoryHistory, createRouter } from 'vue-router'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+import { listPlatformTenants, type PlatformTenantResource } from '@/modules/iam'
+import { listSuppliers, type Supplier } from '@/modules/suppliers'
+import { ApiResponseError } from '@/shared/api/http'
+import {
+  actionReconciliationStatement,
+  createFinanceSettlementPayment,
+  createPayableSettlement,
+  createReceivableSettlement,
+  getFinanceSettlement,
+  getReconciliationStatement,
+  listFinanceFeePool,
+  listFinancePayableSettlements,
+  listFinanceReceivableSettlements,
+  listFinanceStatements,
+  uploadFinanceVoucher,
+} from '../api/finance'
+import type { FinancePayableSettlement, FinanceReconciliationDetail, FinanceStatementReadModel } from '../types'
+import FinanceCustomerStatementsView from './FinanceCustomerStatementsView.vue'
+import FinanceFormalSettlementPage from './FinanceFormalSettlementPage.vue'
+
+vi.mock('@/modules/iam', () => ({ listPlatformTenants: vi.fn() }))
+vi.mock('@/modules/suppliers', () => ({
+  listSuppliers: vi.fn(),
+  categoryLabels: { BOOKING: '订舱', CUSTOMS: '报关', TRUCKING: '拖车', CERTIFICATE: '证书' },
+}))
+vi.mock('../api/finance', () => ({
+  actionReconciliationStatement: vi.fn(), createFinanceSettlementPayment: vi.fn(), createPayableSettlement: vi.fn(),
+  createReceivableSettlement: vi.fn(), getFinanceSettlement: vi.fn(), getReconciliationStatement: vi.fn(),
+  listFinanceFeePool: vi.fn(), listFinancePayableSettlements: vi.fn(), listFinanceReceivableSettlements: vi.fn(),
+  listFinanceStatements: vi.fn(), uploadFinanceVoucher: vi.fn(), createReconciliationStatement: vi.fn(),
+}))
+
+class ResizeObserverStub implements ResizeObserver { observe() {} unobserve() {} disconnect() {} }
+function memoryStorage(): Storage {
+  const values = new Map<string, string>()
+  return { get length() { return values.size }, clear: () => values.clear(), getItem: (key) => values.get(key) ?? null, key: (index) => [...values.keys()][index] ?? null, removeItem: (key) => values.delete(key), setItem: (key, value) => values.set(key, value) }
+}
+
+const statement: FinanceStatementReadModel = { id: '501', customerId: '10001', billNo: 'REC-501', customerName: '客户A', billDate: '2026-08-31', dueDate: '2026-09-30', totalAmount: 300, receivedAmount: 0, outstandingAmount: 300, currency: 'CNY', status: 'ISSUED', version: 3 }
+const statementDetail: FinanceReconciliationDetail = {
+  ...statement, paidAmount: 0, remark: '', periodStart: '2026-08-01', periodEnd: '2026-08-31', creditDays: 30, settled: false, paymentHistory: [], revisions: [],
+  lines: [
+    { statementLineId: '601', sourceFeeId: '81', sourceFeeVersion: 1, orderId: '11', inboundId: '21', feeItemName: '运费', amount: 100 },
+    { statementLineId: '602', sourceFeeId: '82', sourceFeeVersion: 1, orderId: '12', inboundId: '22', feeItemName: '操作费', amount: 200 },
+  ],
+}
+const payable: FinancePayableSettlement = { id: '701', customerId: '10001', settlementNo: 'AP-701', costType: 'SINGLE_ORDER', orderId: '11', inboundId: null, containerId: null, supplierName: '供应商A', feeItemName: '拖车费', payableAmount: 200, paidAmount: 0, outstandingAmount: 200, currency: 'CNY', status: 'ISSUED', createdAt: '2026-08-11', version: 4 }
+const settlementDetail = { id: '701', settlementNo: 'AP-701', customerId: '10001', supplierId: '301', direction: 'PAYABLE' as const, amount: 200, paidAmount: 0, outstandingAmount: 200, currency: 'CNY' as const, status: 'ISSUED', version: 4, lines: [], transactions: [], revisions: [] }
+
+async function mountWithAccess(component: typeof FinanceCustomerStatementsView | typeof FinanceFormalSettlementPage, permissions: string[], props: Record<string, unknown> = {}) {
+  const pinia = createPinia(); setActivePinia(pinia)
+  const auth = useAuthStore(); auth.token = 'token'; auth.permissions = permissions
+  useAccessPreviewStore().initializeAfterLogin()
+  const router = createRouter({ history: createMemoryHistory(), routes: [
+    { path: '/finance/customer-statements', name: 'finance-customer-statements', component: FinanceCustomerStatementsView },
+    { path: '/finance/customer-statements/:statementId', name: 'finance-customer-statement-detail', component: FinanceCustomerStatementsView },
+  ] })
+  await router.push('/finance/customer-statements'); await router.isReady()
+  const wrapper = mount(component, { attachTo: document.body, props, global: { plugins: [pinia, ElementPlus, router] } })
+  await flushPromises()
+  return wrapper
+}
+
+enableAutoUnmount(afterEach)
+afterAll(() => vi.unstubAllGlobals())
+
+describe('Finance G3/G4 views', () => {
+  beforeEach(() => {
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+    vi.stubGlobal('localStorage', memoryStorage())
+    vi.stubGlobal('sessionStorage', memoryStorage())
+    document.body.innerHTML = ''
+    const customer = { id: '10001', tenantName: '客户A', status: 'ACTIVE' } as PlatformTenantResource
+    vi.mocked(listPlatformTenants).mockReset().mockResolvedValue({ records: [customer], page: 1, size: 200, total: 1, pages: 1 })
+    vi.mocked(listSuppliers).mockReset().mockResolvedValue({ records: [{ id: '301', tenantId: '0', name: '拖车供应商A', category: 'TRUCKING', truckingScope: 'DOMESTIC', carrierCodes: [], scope: 'DOMESTIC', region: '宁波', legalRepresentative: '', contactName: '', phone: '', email: null, address: null, businessLicenseNo: null, licenseFileId: null, status: 'ACTIVE', settlementPeriod: 'MONTHLY_30', remark: null, createdBy: null, createdAt: '2026-08-01', updatedBy: null, updatedAt: '2026-08-01', deleted: false, version: 0 } as Supplier], page: 1, size: 200, total: 1, pages: 1 })
+    vi.mocked(listFinanceStatements).mockReset().mockResolvedValue([statement])
+    vi.mocked(getReconciliationStatement).mockReset().mockResolvedValue(statementDetail)
+    vi.mocked(actionReconciliationStatement).mockReset().mockResolvedValue(statementDetail)
+    vi.mocked(listFinanceFeePool).mockReset().mockResolvedValue([{ poolItemId: 'PAYABLE:81', feeSourceId: '81', customerId: '10001', direction: 'PAYABLE', sourceType: 'INBOUND_FEE', sourceId: '81', sourceVersion: 1, orderId: '11', inboundId: '21', containerId: null, feeItemName: '拖车费', amount: 200, currency: 'CNY', status: 'AVAILABLE', createdAt: '2026-08-11' }])
+    vi.mocked(listFinancePayableSettlements).mockReset().mockResolvedValue([payable])
+    vi.mocked(listFinanceReceivableSettlements).mockReset().mockResolvedValue([])
+    vi.mocked(createPayableSettlement).mockReset().mockResolvedValue(settlementDetail)
+    vi.mocked(createReceivableSettlement).mockReset().mockResolvedValue({ ...settlementDetail, id: '801', settlementNo: 'AR-801', direction: 'RECEIVABLE', supplierId: undefined })
+    vi.mocked(uploadFinanceVoucher).mockReset().mockResolvedValue({ fileId: '9001', customerId: '10001', fileName: 'voucher.png', contentType: 'image/png', sizeBytes: 1 })
+    vi.mocked(createFinanceSettlementPayment).mockReset().mockResolvedValue({ ...settlementDetail, paidAmount: 100, outstandingAmount: 100, status: 'PARTIALLY_PAID', version: 5 })
+  })
+
+  it('hides G3/G4 commands when list permissions are absent', async () => {
+    const statements = await mountWithAccess(FinanceCustomerStatementsView, [])
+    const settlements = await mountWithAccess(FinanceFormalSettlementPage, [], { kind: 'payable' })
+    expect(statements.text()).not.toContain('生成对账单')
+    expect(settlements.text()).toContain('无权访问结算单应付')
+    expect(createPayableSettlement).not.toHaveBeenCalled()
+    expect(actionReconciliationStatement).not.toHaveBeenCalled()
+  })
+
+  it('submits every selected adjustment line with the detail version', async () => {
+    const wrapper = await mountWithAccess(FinanceCustomerStatementsView, ['platform:finance:customer-statement:list', 'platform:finance:reconciliation:adjust'])
+    const vm = wrapper.vm as unknown as { openAdjustment(row: FinanceStatementReadModel): Promise<void>; submitAdjustment(): Promise<void>; adjustReason: string; adjustLines: Array<{ selected: boolean; adjustedAmount: number; reason: string }> }
+    await vm.openAdjustment(statement)
+    vm.adjustReason = '月末核对更正'
+    vm.adjustLines.forEach((line, index) => { line.selected = true; line.adjustedAmount = index === 0 ? 90 : 180; line.reason = `明细${index + 1}更正` })
+    await vm.submitAdjustment()
+    expect(actionReconciliationStatement).toHaveBeenCalledWith('501', { action: 'ADJUST', reason: '月末核对更正', expectedVersion: 3, adjustmentLines: [{ statementLineId: '601', adjustedAmount: 90, reason: '明细1更正' }, { statementLineId: '602', adjustedAmount: 180, reason: '明细2更正' }] })
+  })
+
+  it('creates a payable settlement and registers a voucher-backed payment', async () => {
+    const wrapper = await mountWithAccess(FinanceFormalSettlementPage, ['platform:finance:settlement-ap:list', 'platform:finance:settlement-ap:create', 'platform:finance:payment:create'], { kind: 'payable' })
+    const vm = wrapper.vm as unknown as { load(model: Record<string, string>): Promise<void>; openCreate(): Promise<void>; submitCreate(): Promise<void>; openPayment(row: FinancePayableSettlement): void; submitPayment(): Promise<void>; createForm: { customerId: string; supplierId: string; dueDate: string; feeSourceIds: string[] }; paymentFile: File | null; paymentForm: { amount: number; transactionDate: string; method: 'BANK_TRANSFER'; referenceNo: string; remark: string } }
+    await vm.load({ customerId: '10001' }); await vm.openCreate()
+    expect(listSuppliers).toHaveBeenCalledWith({ page: 1, size: 200, status: 'ACTIVE' })
+    expect(document.body.textContent).toContain('拖车供应商A · 拖车')
+    Object.assign(vm.createForm, { customerId: '10001', supplierId: '301', dueDate: '2026-09-30', feeSourceIds: ['81'] })
+    await vm.submitCreate()
+    expect(createPayableSettlement).toHaveBeenCalledWith({ customerId: '10001', supplierId: '301', feeSourceIds: ['81'], dueDate: '2026-09-30', currency: 'CNY' })
+    vm.openPayment(payable); vm.paymentFile = new File(['x'], 'voucher.png', { type: 'image/png' }); vm.paymentForm.amount = 100
+    await vm.submitPayment()
+    expect(createFinanceSettlementPayment).toHaveBeenCalledWith('701', expect.objectContaining({ amount: 100, voucherFileIds: ['9001'], expectedVersion: 4 }))
+  })
+
+  it('loads payable sources only for the selected supplier and clears them when the supplier changes', async () => {
+    const wrapper = await mountWithAccess(FinanceFormalSettlementPage, ['platform:finance:settlement-ap:list', 'platform:finance:settlement-ap:create'], { kind: 'payable' })
+    const vm = wrapper.vm as unknown as { openCreate(): Promise<void>; createForm: { customerId: string; supplierId: string; feeSourceIds: string[] } }
+
+    await vm.openCreate()
+    vm.createForm.customerId = '10001'
+    await flushPromises()
+    expect(listFinanceFeePool).not.toHaveBeenCalled()
+
+    vm.createForm.supplierId = '301'
+    await flushPromises()
+    expect(listFinanceFeePool).toHaveBeenCalledWith('10001', 'PAYABLE', '301')
+
+    vm.createForm.feeSourceIds = ['81']
+    vm.createForm.supplierId = ''
+    await flushPromises()
+    expect(vm.createForm.feeSourceIds).toEqual([])
+  })
+
+  it('renders request and trace ids when G3 detail loading fails', async () => {
+    vi.mocked(getReconciliationStatement).mockRejectedValueOnce(new ApiResponseError('对账单不可用', 'FIN_404', 404, undefined, 'req-g3-error', 'trace-g3-error'))
+    const wrapper = await mountWithAccess(FinanceCustomerStatementsView, ['platform:finance:customer-statement:list'])
+    const vm = wrapper.vm as unknown as { openDetail(row: FinanceStatementReadModel): Promise<void> }
+    await vm.openDetail(statement); await flushPromises()
+    expect(document.body.textContent).toContain('req-g3-error')
+    expect(document.body.textContent).toContain('trace-g3-error')
+  })
+
+  it('loads all customers by default and applies explicit customer filters', async () => {
+    const statements = await mountWithAccess(FinanceCustomerStatementsView, ['platform:finance:customer-statement:list'])
+    const receivables = await mountWithAccess(FinanceFormalSettlementPage, ['platform:finance:settlement-ar:list'], { kind: 'receivable' })
+    const payables = await mountWithAccess(FinanceFormalSettlementPage, ['platform:finance:settlement-ap:list'], { kind: 'payable' })
+
+    expect(listFinanceStatements).toHaveBeenCalledWith(undefined)
+    expect(listFinanceReceivableSettlements).toHaveBeenCalledWith(undefined)
+    expect(listFinancePayableSettlements).toHaveBeenCalledWith(undefined)
+    await (statements.vm as unknown as { load(model: Record<string, string>): Promise<void> }).load({ customerId: '10001' })
+    await (receivables.vm as unknown as { load(model: Record<string, string>): Promise<void> }).load({ customerId: '10001' })
+    await (payables.vm as unknown as { load(model: Record<string, string>): Promise<void> }).load({ customerId: '10001' })
+    expect(listFinanceStatements).toHaveBeenLastCalledWith('10001')
+    expect(listFinanceReceivableSettlements).toHaveBeenLastCalledWith('10001')
+    expect(listFinancePayableSettlements).toHaveBeenLastCalledWith('10001')
+  })
+
+  it('applies settlement list text filters only after an explicit query', async () => {
+    const wrapper = await mountWithAccess(FinanceFormalSettlementPage, ['platform:finance:settlement-ap:list'], { kind: 'payable' })
+    const vm = wrapper.vm as unknown as {
+      filters: Record<string, unknown>
+      filteredRows: FinancePayableSettlement[]
+      load(model: Record<string, unknown>): Promise<void>
+    }
+    vm.filters.settlementNo = 'NOT-FOUND'
+    await flushPromises()
+    expect(vm.filteredRows).toHaveLength(1)
+    await vm.load({ customerId: '', supplierName: '', settlementNo: 'NOT-FOUND', status: '' })
+    await flushPromises()
+    expect(vm.filteredRows).toHaveLength(0)
+  })
+})
diff --git a/src/modules/finance/pages/FinancePresentation.test.ts b/src/modules/finance/pages/FinancePresentation.test.ts
new file mode 100644
index 00000000..a3a262af
--- /dev/null
+++ b/src/modules/finance/pages/FinancePresentation.test.ts
@@ -0,0 +1,170 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const settlement = readFileSync(resolve(process.cwd(), 'src/modules/finance/pages/FinanceFormalSettlementPage.vue'), 'utf8')
+const density = readFileSync(resolve(process.cwd(), 'src/styles/adminDensity.css'), 'utf8')
+const financeDensity = readFileSync(resolve(process.cwd(), 'src/modules/finance/financeDensity.css'), 'utf8')
+const financeRoutes = readFileSync(resolve(process.cwd(), 'src/modules/finance/routes.ts'), 'utf8')
+const accounts = readFileSync(resolve(process.cwd(), 'src/modules/finance/pages/FinanceCustomerAccountsView.vue'), 'utf8')
+const statements = readFileSync(resolve(process.cwd(), 'src/modules/finance/pages/FinanceCustomerStatementsView.vue'), 'utf8')
+const arap = readFileSync(resolve(process.cwd(), 'src/modules/finance/pages/FinanceCustomerArapView.vue'), 'utf8')
+
+describe('finance presentation governance', () => {
+  it('shows customer names instead of internal customer IDs in formal settlements', () => {
+    expect(settlement).toContain('customerName(detail.value.customerId, detail.value.customerName)')
+    expect(settlement).toContain('detailPartyName()')
+    expect(settlement).toContain('activeCustomers.value.map')
+    expect(settlement).not.toContain('{{ selected.customerId }}')
+  })
+
+  it('uses prototype-defined standalone settlement details and modal partial payments', () => {
+    expect(financeRoutes).toContain("finance/settlement-receivables/:settlementId")
+    expect(financeRoutes).toContain("finance/settlement-payables/:settlementId")
+    expect(financeRoutes).toContain("finance/receivable-statistics")
+    expect(financeRoutes).toContain("platform:finance:receivable-statistics:list")
+    expect(financeRoutes).toContain('showPageHeading: false')
+    expect(settlement).toContain('class="settlement-detail-page surface-panel finance-density-detail"')
+    expect(settlement).toContain('返回列表')
+    expect(settlement).not.toContain('AppDrawer')
+    expect(settlement).toContain('登记后剩余余额')
+    expect(settlement).toContain('remainingAfter(receiptForm.amount)')
+    expect(settlement).toContain('remainingAfter(paymentForm.amount)')
+  })
+
+  it('uses one continuous desktop detail surface with shared summaries and scroll-safe tables', () => {
+    expect(settlement).toContain('class="settlement-detail-page surface-panel finance-density-detail"')
+    expect(settlement).toContain('class="settlement-detail-content"')
+    expect(settlement).toContain('class="settlement-detail-info density-descriptions"')
+    for (const title of ['基本信息', '费用明细', '修订记录']) expect(settlement).toContain('title="' + title + '"')
+    expect(settlement).toContain(':title="kind === \'receivable\' ? \'收款记录\' : \'付款记录\'"')
+    expect(settlement.match(/class="detail-table-scroll"/g)).toHaveLength(3)
+    expect(settlement).toContain(':deep(.detail-table-scroll .el-table) { min-width: 920px; }')
+    expect(settlement).not.toContain('class="detail-section surface-panel"')
+    expect(settlement.match(/width="min\(760px, 94vw\)"/g)).toHaveLength(2)
+    expect(settlement.match(/class="settlement-operation-form density-form"/g)).toHaveLength(2)
+    expect(settlement).toContain('grid-template-columns: repeat(2, minmax(0, 1fr));')
+    expect(settlement).toContain('column-gap: var(--admin-space-5);')
+  })
+
+  it('keeps settlement totals and list actions in the table toolbar', () => {
+    expect(settlement).toContain('<template #toolbar-start>')
+    expect(settlement).toContain('class="density-detail-overview settlement-summary" aria-label="结算汇总"')
+    expect(settlement).toContain('<template #toolbar-actions>')
+    expect(settlement).toContain('class="settlement-list-actions"')
+    expect(financeDensity).toContain('.settlement-summary.density-detail-overview { padding: 0; border: 0; }')
+    expect(settlement).not.toContain('class="settlement-list-toolbar"')
+  })
+
+  it('keeps settlement details focused on finance-facing labels and fields', () => {
+    expect(settlement).toContain('financeSourceTypeLabel(scope.row.sourceType)')
+    expect(settlement).toContain('financeOperationActionLabel(scope.row.action)')
+    expect(settlement).toContain('displayDateTime(scope.row.occurredAt)')
+    expect(settlement).not.toContain('label="来源版本"')
+  })
+
+  it('uses optional all-customer filters without a customer-selection blocker', () => {
+    for (const source of [settlement]) {
+      expect(source).toContain("placeholder: '全部客户'")
+      expect(source).not.toContain('全客户查询暂不可用')
+      expect(source).not.toContain('empty-text="请选择客户查询')
+    }
+    expect(arap).toContain("placeholder: '请选择客户'")
+    expect(arap).not.toContain("placeholder: '全部客户'")
+    expect(statements).toContain("placeholder: '请选择客户'")
+    expect(statements).toContain("placeholder: '请选择对账单状态'")
+    expect(statements).toContain(':search-on-clear="false"')
+    expect(statements).toContain("placeholder: '请选择结清状态'")
+    expect(statements).toContain("startPlaceholder: '请选择开始日期'")
+    expect(statements).toContain("endPlaceholder: '请选择结束日期'")
+    expect(statements).not.toContain("placeholder: '全部客户'")
+    expect(settlement).toContain(':search-on-clear="false"')
+  })
+
+  it('uses active-customer name selectors across all formal finance pages', () => {
+    for (const source of [accounts, arap, statements, settlement]) {
+      expect(source).toContain("type: 'select'")
+      expect(source).toContain("label: '客户名称'")
+      expect(source).toContain('label: item.tenantName')
+      expect(source).not.toContain('tenantCode} · ${item.tenantName')
+    }
+    expect(accounts).not.toContain("key: 'keyword', type: 'input'")
+  })
+
+  it('keeps customer arap selector text within a stable dropdown layout', () => {
+    expect(arap).toContain("class: 'finance-customer-select'")
+    expect(arap).toContain("popperClass: 'finance-customer-arap-popper'")
+    expect(arap).toContain('teleported: false')
+    expect(arap).toContain('onVisibleChange: onCustomerSelectVisible')
+    expect(arap).toContain("document.addEventListener('scroll', closeCustomerSelectOnScroll, true)")
+    expect(arap).toContain('.finance-customer-arap-popper .el-select-dropdown__item')
+    expect(arap).toContain('text-overflow: ellipsis;')
+  })
+
+  it('keeps the customer arap table body independently scrollable', () => {
+    expect(arap).toContain('max-height="calc(100vh - 300px)"')
+  })
+
+  it('translates source codes and provides reason placeholders', () => {
+    expect(arap).toContain('sourceTypeDisplay(detail.sourceType)')
+    expect(arap).toContain('financeOperationActionLabel(row.action)')
+    expect(arap).toContain('financeOperationResultLabel(row.result)')
+    expect(arap).toContain('financeDirectionLabel(row.direction)')
+    expect(arap).toContain('financeDirectionLabel(detail.direction)')
+    expect(arap).not.toContain("detail.direction === 'RECEIVABLE' ? '应收' : '应付'")
+    expect(arap).toContain('请填写驳回原因')
+    expect(arap).toContain('请填写操作原因')
+  })
+
+  it('exposes frozen G3 controls without unavailable placeholders', () => {
+    expect(settlement).not.toContain('生成{{ title }}')
+    expect(settlement).not.toContain('接口尚未提供，暂不可操作')
+    expect(statements).toContain('生成对账单')
+    expect(statements).toContain('createReconciliationStatement')
+    expect(statements).toContain('actionReconciliationStatement')
+    expect(statements).toContain('<template #toolbar-actions>')
+    expect(statements).toContain('aria-label="更多对账单操作"')
+    expect(statements).toContain('adjustmentLines: selected.map')
+    expect(statements).not.toContain('disabled title="接口尚未提供')
+  })
+
+  it('uses bordered striped tables for statement business details', () => {
+    expect(statements).toContain(':data="detail.lines" size="small" border stripe')
+    expect(statements).toContain(':data="detail.revisions" size="small" border stripe')
+    expect(statements).toContain(':data="adjustLines" size="small" max-height="420" border stripe')
+  })
+
+  it('opens statement details on a compact dedicated route instead of below the list', () => {
+    expect(statements).toContain('v-else-if="isDetailRoute" class="surface-panel statement-detail-page finance-density-detail"')
+    expect(statements).toContain('@row-click="openDetail"')
+    expect(statements).toContain("name: 'finance-customer-statement-detail'")
+    expect(financeDensity).toContain('.detail-page-layout.finance-density-detail { gap: 0; }')
+    expect(statements).toContain('返回客户对账单')
+    expect(statements).not.toContain('aria-label="所选对账单联动明细"')
+    expect(statements).not.toContain('核对账期、金额和结清状态后查看下方业务明细。')
+    expect(statements).not.toContain('展示当前对账单版本中的业务与计费明细。')
+    expect(statements).not.toContain('只读展示当前对账单关联的有效收款记录。')
+  })
+
+  it('uses a shared compact financial summary row for customer accounts', () => {
+    expect(accounts).toContain('class="density-detail-overview account-metrics"')
+    expect(financeDensity).toContain('.detail-page-layout.finance-density-detail { gap: 0; }')
+    expect(density).toContain('.density-detail-overview')
+    expect(accounts).toContain(':deep(.ledger-query.query-toolbar)')
+    expect(accounts).toContain('padding: 0;')
+    expect(accounts).toContain('border: 0;')
+    expect(accounts).toContain('background: transparent;')
+    expect(accounts).not.toContain('展示应收、应付及每次变动后的未收金额。')
+    expect(accounts).not.toContain('到期日按账单日期加客户账期计算；每个客户独立设置，默认 30 天。')
+  })
+
+  it('keeps fee-source details continuous without nested metric and section cards', () => {
+    expect(arap).toContain('class="density-detail-overview arap-metrics"')
+    expect(arap).toContain('class="arap-information density-form-section"')
+    expect(arap).toContain('class="arap-settlement density-form-section"')
+    expect(arap).toContain('padding-left: var(--admin-space-6);')
+    expect(arap).toContain('border-left: 1px solid')
+    expect(arap).not.toContain('.arap-metric.is-amount { border-color:')
+    for (const description of ['费用来源与关联业务摘要', '当前审核和出账状态', '按时间查看审核与结算调整记录']) expect(arap).not.toContain('description="' + description + '"')
+  })
+})
diff --git a/src/modules/finance/pages/FinanceReceivableStatisticsView.test.ts b/src/modules/finance/pages/FinanceReceivableStatisticsView.test.ts
new file mode 100644
index 00000000..d6f1dde1
--- /dev/null
+++ b/src/modules/finance/pages/FinanceReceivableStatisticsView.test.ts
@@ -0,0 +1,25 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const page = readFileSync(resolve(process.cwd(), 'src/modules/finance/pages/FinanceReceivableStatisticsView.vue'), 'utf8')
+
+describe('receivable statistics page', () => {
+  it('renders only the approved CNY derived metrics and current-filter actions', () => {
+    for (const label of ['统计月份', '应收单位', '应收总额', '已收合计', '余额未收', '打印', '导出Excel']) expect(page).toContain(label)
+    expect(page).toContain("exportType: 'FINANCE_RECEIVABLE_STATISTICS'")
+    expect(page).toContain('window.print()')
+    expect(page).toContain('displayCustomerName(row)')
+    expect(page).toContain('/^客户\\s*\\d+$/.test(snapshot)')
+    expect(page).toContain("return masterName || '—'")
+    for (const excluded of ['FBA直发', 'FBA专线', '零头减免', 'USD', '>编辑<']) expect(page).not.toContain(excluded)
+  })
+
+  it('keeps query reset, loading, empty, error and permission states explicit', () => {
+    expect(page).toContain('function reset()')
+    expect(page).toContain('无权访问应收款统计表')
+    expect(page).toContain('<LoadErrorState')
+    expect(page).toContain('当前月份暂无应收数据')
+    expect(page).toContain(':loading="loading"')
+  })
+})
diff --git a/src/modules/finance/pages/FinanceReceivableStatisticsView.vue b/src/modules/finance/pages/FinanceReceivableStatisticsView.vue
new file mode 100644
index 00000000..cdd60201
--- /dev/null
+++ b/src/modules/finance/pages/FinanceReceivableStatisticsView.vue
@@ -0,0 +1,137 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import '../financeDensity.css'
+import { computed, onMounted, ref } from 'vue'
+import { Download, Printer, RotateCcw, Search } from '@lucide/vue'
+import { ElMessage } from 'element-plus'
+import { useRouter } from 'vue-router'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { createPlatformExportTask } from '@/modules/downloads'
+import { listPlatformTenants, type PlatformTenantResource } from '@/modules/iam'
+import { getApiErrorDetails, getApiErrorMessage, type ApiErrorDetails } from '@/shared/api/http'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { showExportTaskCreatedDialog } from '@/shared/components/exportTaskCreatedDialog'
+import { getReceivableStatistics } from '../api/finance'
+import type { ReceivableStatisticsResult, ReceivableStatisticsRow } from '../types'
+
+const now = new Date()
+const defaultMonth = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}`
+const access = useAccessPreviewStore()
+const router = useRouter()
+const month = ref(defaultMonth)
+const customerId = ref('')
+const customers = ref<PlatformTenantResource[]>([])
+const page = ref(1)
+const pageSize = ref(20)
+const loading = ref(false)
+const exporting = ref(false)
+const error = ref<ApiErrorDetails | null>(null)
+const result = ref<ReceivableStatisticsResult | null>(null)
+
+const canView = computed(() => access.can('platform:finance:receivable-statistics:list'))
+const canExport = computed(() => access.can('platform:finance:receivable-statistics:export') && access.can('platform:download:list'))
+const rows = computed<ReceivableStatisticsRow[]>(() => result.value?.records ?? [])
+const customerNameById = computed(() => new Map(customers.value.map((item) => [String(item.id), item.tenantName])))
+const columns: DataTableColumn[] = [
+  { key: 'customerName', label: '应收单位', minWidth: 240, slotName: 'customerName' },
+  { key: 'currency', label: '币种', width: 100 },
+  { key: 'totalReceivable', label: '应收总额(CNY)', width: 180, slotName: 'totalReceivable' },
+  { key: 'totalReceived', label: '已收合计(CNY)', width: 180, slotName: 'totalReceived' },
+  { key: 'totalOutstanding', label: '余额未收(CNY)', width: 180, slotName: 'totalOutstanding' },
+]
+
+async function load() {
+  if (!canView.value || !month.value) return
+  loading.value = true
+  error.value = null
+  try {
+    result.value = await getReceivableStatistics({ month: month.value, customerId: customerId.value || undefined, page: page.value, pageSize: pageSize.value })
+  } catch (reason) { error.value = getApiErrorDetails(reason, '应收款统计加载失败，请重试') }
+  finally { loading.value = false }
+}
+
+async function loadCustomers() {
+  try {
+    const records: PlatformTenantResource[] = []
+    let current = 1; let pages = 1
+    do { const response = await listPlatformTenants({ page: current, size: 200, status: 'ACTIVE' }); records.push(...response.records); pages = response.pages; current += 1 } while (current <= pages)
+    customers.value = records
+  } catch { /* 客户筛选失败不阻断统计，仍可查询全部客户。 */ }
+}
+
+function search() { page.value = 1; void load() }
+function reset() { month.value = defaultMonth; customerId.value = ''; page.value = 1; void load() }
+function printCurrent() { window.print() }
+function statisticsRowKey(row: ReceivableStatisticsRow) { return `${row.customerId}:${row.customerName}` }
+function displayCustomerName(value: unknown) {
+  const row = value as ReceivableStatisticsRow
+  const masterName = customerNameById.value.get(String(row.customerId))?.trim()
+  const snapshot = row.customerName?.trim()
+  if (!snapshot || /^客户\s*\d+$/.test(snapshot) || snapshot === String(row.customerId)) return masterName || '—'
+  return snapshot
+}
+async function exportCurrent() {
+  exporting.value = true
+  try {
+    const task = await createPlatformExportTask({ exportType: 'FINANCE_RECEIVABLE_STATISTICS', format: 'XLSX', taskName: `应收款统计表-${month.value}`,
+      parameters: { month: month.value, ...(customerId.value ? { customerId: customerId.value } : {}) } })
+    const open = await showExportTaskCreatedDialog({ taskName: task.taskName, taskNo: task.taskNo, dense: true })
+    if (open) await router.push({ name: 'download-center' })
+  } catch (reason) { ElMessage.error(getApiErrorMessage(reason, '应收款统计导出任务创建失败')) }
+  finally { exporting.value = false }
+}
+function money(value?: string) { return Number(value || 0).toLocaleString('zh-CN', { minimumFractionDigits: 2, maximumFractionDigits: 2 }) }
+
+onMounted(() => { void loadCustomers(); void load() })
+</script>
+
+<template>
+  <AdminPage class="receivable-statistics-page admin-density" spacing="normal">
+    <el-result v-if="!canView" icon="warning" title="无权访问应收款统计表" sub-title="请联系管理员开通应收款统计查看权限" />
+    <template v-else>
+      <section class="surface-panel statistics-query" aria-label="应收款统计筛选">
+        <div class="query-field"><span>统计月份</span><el-date-picker v-model="month" type="month" value-format="YYYY-MM" format="YYYY年MM月" :clearable="false" aria-label="统计月份" /></div>
+        <div class="query-field"><span>应收单位</span><el-select v-model="customerId" clearable filterable placeholder="全部应收单位" aria-label="应收单位"><el-option v-for="customer in customers" :key="String(customer.id)" :label="customer.tenantName" :value="String(customer.id)" /></el-select></div>
+        <div class="query-actions"><el-button type="primary" :loading="loading" @click="search"><Search :size="16" />查询</el-button><el-button @click="reset"><RotateCcw :size="16" />重置</el-button></div>
+      </section>
+      <LoadErrorState v-if="error" title="应收款统计加载失败" :message="error.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="error" /></template></LoadErrorState>
+      <template v-else>
+        <dl class="density-detail-overview statistics-summary" aria-label="CNY应收汇总">
+          <div><dt>应收总额</dt><dd>CNY {{ money(result?.totalReceivable) }}</dd></div>
+          <div><dt>已收合计</dt><dd class="is-received">CNY {{ money(result?.totalReceived) }}</dd></div>
+          <div><dt>余额未收</dt><dd class="is-outstanding">CNY {{ money(result?.totalOutstanding) }}</dd></div>
+        </dl>
+        <section class="surface-panel statistics-table">
+          <header><h2>应收款明细</h2><span>共 {{ result?.totalCustomers ?? 0 }} 个应收单位 · 仅统计CNY正式应收结算单</span></header>
+          <DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :loading="loading" :total="result?.totalCustomers ?? 0" :row-key="statisticsRowKey" preference-key="finance-receivable-statistics-table" aria-label="应收款统计列表" empty-text="当前月份暂无应收数据" @update:page="load()" @update:page-size="page = 1; load()">
+            <template #toolbar-actions><div class="report-actions"><el-button :disabled="loading || !result" @click="printCurrent"><Printer :size="16" />打印</el-button><el-button v-if="canExport" type="primary" :loading="exporting" :disabled="loading || exporting" @click="exportCurrent"><Download :size="16" />导出Excel</el-button></div></template>
+            <template #customerName="{ row }">{{ displayCustomerName(row) }}</template><template #totalReceivable="{ row }">{{ money(row.totalReceivable) }}</template><template #totalReceived="{ row }">{{ money(row.totalReceived) }}</template><template #totalOutstanding="{ row }"><span class="outstanding-cell">{{ money(row.totalOutstanding) }}</span></template>
+            <template #pagination-left>统计月份：{{ result?.statisticsMonth }} · 币种：CNY</template>
+          </DataTable>
+        </section>
+      </template>
+    </template>
+  </AdminPage>
+</template>
+
+<style scoped>
+.statistics-query { display: flex; align-items: end; gap: var(--admin-space-5); padding: var(--admin-space-6); }
+.query-field { display: grid; min-width: 220px; gap: var(--admin-space-2); color: var(--cc-muted); font-size: var(--admin-font-body); }
+.query-field :deep(.el-select), .query-field :deep(.el-date-editor) { width: 100%; }
+.query-actions, .report-actions { display: flex; gap: var(--admin-space-3); }
+.report-actions { margin-left: auto; }
+.query-actions :deep(.el-button), .report-actions :deep(.el-button) { margin-left: 0; }
+.outstanding-cell { color: var(--el-color-danger); font-variant-numeric: tabular-nums; }
+.statistics-table { overflow: hidden; }
+.statistics-table > header { display: flex; align-items: center; justify-content: space-between; padding: var(--admin-space-5) var(--admin-space-6); border-bottom: 1px solid var(--cc-border, #e3e8ef); }
+.statistics-table h2 { margin: 0; font-size: var(--admin-font-section); }
+.statistics-table header span { color: var(--cc-muted); font-size: var(--admin-font-body); }
+@media print {
+  .statistics-query, :deep(.data-table__toolbar), :deep(.data-table__pagination) { display: none !important; }
+  .receivable-statistics-page { gap: 10px; color: #000; }
+  .statistics-summary > div, .statistics-table { border-color: #999; box-shadow: none; }
+}
+</style>
diff --git a/src/modules/finance/pages/FinanceSettlementPayablesView.vue b/src/modules/finance/pages/FinanceSettlementPayablesView.vue
new file mode 100644
index 00000000..1ddbea0f
--- /dev/null
+++ b/src/modules/finance/pages/FinanceSettlementPayablesView.vue
@@ -0,0 +1,12 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import FinanceFormalSettlementPage from './FinanceFormalSettlementPage.vue'
+
+const route = useRoute()
+const router = useRouter()
+const settlementId = computed(() => String(route.params.settlementId || ''))
+function openDetail(id: string) { void router.push({ name: 'finance-settlement-payable-detail', params: { settlementId: id } }) }
+function back() { void router.push({ name: 'finance-settlement-payables' }) }
+</script>
+<template><FinanceFormalSettlementPage class="finance-settlement-route finance-settlement-route--payable" kind="payable" :settlement-id="settlementId" @open-detail="openDetail" @back="back" /></template>
diff --git a/src/modules/finance/pages/FinanceSettlementReceivablesView.vue b/src/modules/finance/pages/FinanceSettlementReceivablesView.vue
new file mode 100644
index 00000000..aecfb8fa
--- /dev/null
+++ b/src/modules/finance/pages/FinanceSettlementReceivablesView.vue
@@ -0,0 +1,12 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import FinanceFormalSettlementPage from './FinanceFormalSettlementPage.vue'
+
+const route = useRoute()
+const router = useRouter()
+const settlementId = computed(() => String(route.params.settlementId || ''))
+function openDetail(id: string) { void router.push({ name: 'finance-settlement-receivable-detail', params: { settlementId: id } }) }
+function back() { void router.push({ name: 'finance-settlement-receivables' }) }
+</script>
+<template><FinanceFormalSettlementPage class="finance-settlement-route finance-settlement-route--receivable" kind="receivable" :settlement-id="settlementId" @open-detail="openDetail" @back="back" /></template>
diff --git a/src/modules/finance/pages/FinanceSettlementRouteLayout.test.ts b/src/modules/finance/pages/FinanceSettlementRouteLayout.test.ts
new file mode 100644
index 00000000..aef1d8b6
--- /dev/null
+++ b/src/modules/finance/pages/FinanceSettlementRouteLayout.test.ts
@@ -0,0 +1,23 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const receivableSource = readFileSync(resolve(process.cwd(), 'src/modules/finance/pages/FinanceSettlementReceivablesView.vue'), 'utf8')
+const payableSource = readFileSync(resolve(process.cwd(), 'src/modules/finance/pages/FinanceSettlementPayablesView.vue'), 'utf8')
+
+describe('Finance settlement route 1920px layout', () => {
+  it.each([
+    ['应收', receivableSource, 'finance-settlement-route--receivable'],
+    ['应付', payableSource, 'finance-settlement-route--payable'],
+  ])('delegates the detail grid to the shared settlement page for %s', (_label, source, routeClass) => {
+    expect(source).toContain(routeClass)
+    expect(source).toContain('<FinanceFormalSettlementPage')
+    expect(source).toContain(':settlement-id="settlementId"')
+    expect(source).toContain('@open-detail="openDetail" @back="back"')
+    expect(source).toContain('kind="' + (routeClass.endsWith('receivable') ? 'receivable' : 'payable') + '"')
+    expect(source).not.toContain('<style')
+    const shared = readFileSync(resolve(process.cwd(), 'src/modules/finance/pages/FinanceFormalSettlementPage.vue'), 'utf8')
+    expect(shared).toContain(':column="4" class="settlement-detail-info density-descriptions"')
+    expect(shared).toContain('finance-density-detail')
+  })
+})
diff --git a/src/modules/finance/routes.ts b/src/modules/finance/routes.ts
new file mode 100644
index 00000000..3a29479f
--- /dev/null
+++ b/src/modules/finance/routes.ts
@@ -0,0 +1,15 @@
+import type { RouteRecordRaw } from 'vue-router'
+
+export const financeRoutes = [
+  { path: 'finance/customer-accounts', name: 'finance-customer-accounts', component: () => import('./pages/FinanceCustomerAccountsView.vue'), meta: { title: '客户账户', description: '查看客户 CNY 应收台账并维护独立账期', permission: 'platform:finance:customer-account:list' } },
+  { path: 'finance/customer-accounts/:customerId', name: 'finance-customer-account-detail', component: () => import('./pages/FinanceCustomerAccountsView.vue'), meta: { title: '客户账户详情', description: '查看客户派生财务汇总与账户流水', permission: 'platform:finance:customer-account:list', showPageHeading: false } },
+  { path: 'finance/customer-arap', name: 'finance-customer-arap', component: () => import('./pages/FinanceCustomerArapView.vue'), meta: { title: '客户应收应付', description: '按客户追溯入库单、订单和柜次费用来源', permission: 'platform:finance:customer-arap:list' } },
+  { path: 'finance/customer-arap/:feeSourceId', name: 'finance-customer-arap-detail', component: () => import('./pages/FinanceCustomerArapView.vue'), meta: { title: '费用来源详情', description: '查看费用来源、审核进度、关联业务与操作记录', permission: 'platform:finance:customer-arap:list', showPageHeading: false } },
+  { path: 'finance/receivable-statistics', name: 'finance-receivable-statistics', component: () => import('./pages/FinanceReceivableStatisticsView.vue'), meta: { title: '应收款统计表', description: '按月份和客户统计 CNY 应收、已收与未收余额', permission: 'platform:finance:receivable-statistics:list' } },
+  { path: 'finance/customer-statements', name: 'finance-customer-statements', component: () => import('./pages/FinanceCustomerStatementsView.vue'), meta: { title: '客户对账单', description: '维护 CNY 客户对账单并在出账后冻结', permission: 'platform:finance:customer-statement:list' } },
+  { path: 'finance/customer-statements/:statementId', name: 'finance-customer-statement-detail', component: () => import('./pages/FinanceCustomerStatementsView.vue'), meta: { title: '客户对账单详情', description: '查看对账单概要、费用明细、支付历史与调整记录', permission: 'platform:finance:customer-statement:list', showPageHeading: false } },
+  { path: 'finance/settlement-receivables', name: 'finance-settlement-receivables', component: () => import('./pages/FinanceSettlementReceivablesView.vue'), meta: { title: '结算单应收', description: '登记客户收款、凭证及对应对账单金额', permission: 'platform:finance:settlement-ar:list' } },
+  { path: 'finance/settlement-receivables/:settlementId', name: 'finance-settlement-receivable-detail', component: () => import('./pages/FinanceSettlementReceivablesView.vue'), meta: { title: '应收结算单详情', description: '查看应收结算信息、费用明细和收款记录', permission: 'platform:finance:settlement-ar:list', showPageHeading: false } },
+  { path: 'finance/settlement-payables', name: 'finance-settlement-payables', component: () => import('./pages/FinanceSettlementPayablesView.vue'), meta: { title: '结算单应付', description: '登记单票及整柜公共成本并追溯业务来源', permission: 'platform:finance:settlement-ap:list' } },
+  { path: 'finance/settlement-payables/:settlementId', name: 'finance-settlement-payable-detail', component: () => import('./pages/FinanceSettlementPayablesView.vue'), meta: { title: '应付结算单详情', description: '查看应付结算信息、费用明细和付款记录', permission: 'platform:finance:settlement-ap:list', showPageHeading: false } },
+] satisfies RouteRecordRaw[]
diff --git a/src/modules/finance/status.test.ts b/src/modules/finance/status.test.ts
new file mode 100644
index 00000000..06aff4e9
--- /dev/null
+++ b/src/modules/finance/status.test.ts
@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'vitest'
+import { financeArapStatusOptions, financeBillStatusOptions, financeBusinessTypeLabel, financeDirectionLabel, financeDocumentTypeLabel, financeOperationActionLabel, financeOperationResultLabel, financeSourceTypeLabel, financeStatusLabel, financeStatusTone } from './status'
+
+describe('finance status presentation', () => {
+  it.each([
+    ['DRAFT', '草稿'],
+    ['PENDING_REVIEW', '待审核'],
+    ['ISSUED', '已出账'],
+    ['REJECTED', '已驳回'],
+    ['PARTIALLY_PAID', '部分结清'],
+    ['PAID', '已结清'],
+    ['VOIDED', '已作废'],
+    ['AVAILABLE', '待结算'],
+    ['LOCKED', '结算锁定'],
+    ['BILLED', '已入账'],
+    ['RECORDED', '已登记'],
+    ['CONFIRMED', '已确认'],
+    ['ACTIVE', '正常'],
+    ['DISABLED', '停用'],
+  ])('maps %s to %s', (status, label) => {
+    expect(financeStatusLabel(status)).toBe(label)
+  })
+
+  it.each([undefined, null, '', 'NEW_BACKEND_STATUS', 1])('never exposes unknown status %s', (status) => {
+    expect(financeStatusLabel(status)).toBe('未知状态')
+    expect(financeStatusTone(status)).toBe('info')
+  })
+
+  it('translates source and ledger codes without exposing unknown values', () => {
+    expect(financeSourceTypeLabel('CONTAINER_COST')).toBe('整柜成本')
+    expect(financeBusinessTypeLabel('RECEIPT')).toBe('收款')
+    expect(financeBusinessTypeLabel('RECONCILIATION_CREATED')).toBe('生成对账单')
+    expect(financeBusinessTypeLabel('SETTLEMENT_ISSUED')).toBe('结算单生效')
+    expect(financeBusinessTypeLabel('PAYMENT')).toBe('付款')
+    expect(financeBusinessTypeLabel('SUPPLIER_DIRECT_PAID')).toBe('供应商线下直付')
+    expect(financeBusinessTypeLabel('SUPPLIER_ON_ACCOUNT_PAYMENT')).toBe('供应商账期付款')
+    expect(financeBusinessTypeLabel('VOID')).toBe('作废')
+    expect(financeBusinessTypeLabel('NEW_BUSINESS')).toBe('未知业务类型')
+    expect(financeDocumentTypeLabel('SETTLEMENT')).toBe('结算单')
+    expect(financeOperationActionLabel('APPROVE')).toBe('审核通过')
+    expect(financeOperationActionLabel('FEE_SOURCE_REVIEW_APPROVE')).toBe('审核通过')
+    expect(financeOperationActionLabel('RECONCILIATION_ADJUST')).toBe('调整对账单')
+    expect(financeOperationActionLabel('SETTLEMENT_PAYMENT_CREATE')).toBe('登记收付款')
+    expect(financeOperationResultLabel('SUCCESS')).toBe('操作成功')
+    expect(financeDirectionLabel('RECEIVABLE')).toBe('应收')
+    expect(financeDirectionLabel('PAYABLE')).toBe('应付')
+    expect(financeDirectionLabel('NEW_DIRECTION')).toBe('未知方向')
+    expect(financeSourceTypeLabel('NEW_SOURCE')).toBe('未知来源类型')
+    expect(financeDocumentTypeLabel('NEW_DOCUMENT')).toBe('未知单据类型')
+    expect(financeOperationActionLabel('NEW_ACTION')).toBe('未知操作')
+  })
+
+  it('uses review-status values for the customer AR/AP review filter', () => {
+    expect(financeArapStatusOptions).toEqual([
+      { label: '草稿', value: 'DRAFT' },
+      { label: '待审核', value: 'PENDING' },
+      { label: '已审核', value: 'APPROVED' },
+      { label: '已驳回', value: 'REJECTED' },
+    ])
+  })
+
+  it('uses the complete reconciliation statement lifecycle for statement filters', () => {
+    expect(financeBillStatusOptions).toEqual([
+      { label: '草稿', value: 'DRAFT' },
+      { label: '待审核', value: 'PENDING_REVIEW' },
+      { label: '已审核', value: 'APPROVED' },
+      { label: '已驳回', value: 'REJECTED' },
+      { label: '已出账', value: 'ISSUED' },
+      { label: '部分结清', value: 'PARTIALLY_PAID' },
+      { label: '已结清', value: 'PAID' },
+      { label: '已作废', value: 'VOIDED' },
+    ])
+  })
+})
diff --git a/src/modules/finance/status.ts b/src/modules/finance/status.ts
new file mode 100644
index 00000000..6abf7ac4
--- /dev/null
+++ b/src/modules/finance/status.ts
@@ -0,0 +1,108 @@
+export type FinanceStatusTone = 'success' | 'warning' | 'info' | 'danger' | 'primary'
+
+interface FinanceStatusDefinition {
+  label: string
+  tone: FinanceStatusTone
+}
+
+const financeStatuses: Record<string, FinanceStatusDefinition> = {
+  ACTIVE: { label: '正常', tone: 'success' },
+  DISABLED: { label: '停用', tone: 'info' },
+  INACTIVE: { label: '停用', tone: 'info' },
+  DRAFT: { label: '草稿', tone: 'info' },
+  PENDING: { label: '待审核', tone: 'warning' },
+  PENDING_REVIEW: { label: '待审核', tone: 'warning' },
+  APPROVED: { label: '已审核', tone: 'success' },
+  ISSUED: { label: '已出账', tone: 'primary' },
+  REJECTED: { label: '已驳回', tone: 'danger' },
+  UNPAID: { label: '未支付', tone: 'warning' },
+  PARTIALLY_PAID: { label: '部分结清', tone: 'warning' },
+  PAID: { label: '已结清', tone: 'success' },
+  VOIDED: { label: '已作废', tone: 'info' },
+  AVAILABLE: { label: '待结算', tone: 'warning' },
+  LOCKED: { label: '结算锁定', tone: 'warning' },
+  BILLED: { label: '已入账', tone: 'success' },
+  RECORDED: { label: '已登记', tone: 'primary' },
+  CONFIRMED: { label: '已确认', tone: 'success' },
+  PENDING_CONFIRMATION: { label: '待客户确认', tone: 'warning' },
+  NOT_REQUIRED: { label: '无需确认', tone: 'info' },
+}
+
+export const financeBillStatusOptions = [
+  { label: '草稿', value: 'DRAFT' },
+  { label: '待审核', value: 'PENDING_REVIEW' },
+  { label: '已审核', value: 'APPROVED' },
+  { label: '已驳回', value: 'REJECTED' },
+  { label: '已出账', value: 'ISSUED' },
+  { label: '部分结清', value: 'PARTIALLY_PAID' },
+  { label: '已结清', value: 'PAID' },
+  { label: '已作废', value: 'VOIDED' },
+]
+
+export const financeArapStatusOptions = [
+  { label: '草稿', value: 'DRAFT' },
+  { label: '待审核', value: 'PENDING' },
+  { label: '已审核', value: 'APPROVED' },
+  { label: '已驳回', value: 'REJECTED' },
+]
+
+function normalizeStatus(status: unknown) {
+  return typeof status === 'string' ? status.trim().toUpperCase() : ''
+}
+
+export function financeStatusLabel(status: unknown) {
+  return financeStatuses[normalizeStatus(status)]?.label || '未知状态'
+}
+
+export function financeStatusTone(status: unknown): FinanceStatusTone {
+  return financeStatuses[normalizeStatus(status)]?.tone || 'info'
+}
+
+const financeSourceTypeLabels: Record<string, string> = {
+  INBOUND_FEE: '入库费用', ORDER_FEE: '订单费用', CONTAINER_FEE: '装柜费用', CONTAINER_COST: '整柜成本', MANUAL_COST: '人工成本', STORAGE_FEE: '仓储费用',
+}
+const financeBusinessTypeLabels: Record<string, string> = {
+  RECONCILIATION_CREATED: '生成对账单',
+  SETTLEMENT_ISSUED: '结算单生效',
+  RECEIPT: '收款',
+  PAYMENT: '付款',
+  SUPPLIER_DIRECT_PAID: '供应商线下直付',
+  SUPPLIER_ON_ACCOUNT_PAYMENT: '供应商账期付款',
+  ADJUSTMENT: '账务调整',
+  VOID: '作废',
+  // The following values are returned by current Finance read models.
+  BILL: '对账单',
+  COST: '成本',
+  SETTLEMENT: '结算',
+}
+const financeDocumentTypeLabels: Record<string, string> = {
+  BILL: '对账单', RECEIPT: '收款单', COST: '成本单', SETTLEMENT: '结算单', REVISION: '调整记录',
+}
+const financeOperationActionLabels: Record<string, string> = {
+  CREATE: '创建', APPROVE: '审核通过', REJECT: '审核驳回', UPDATE: '更新',
+  FEE_SOURCE_EDIT: '编辑费用', FEE_SOURCE_SUBMIT: '提交审核', FEE_SOURCE_REVIEW_APPROVE: '审核通过',
+  FEE_SOURCE_REVIEW_REJECT: '审核驳回', FEE_SOURCE_ADJUST: '调整费用', FEE_SOURCE_VOID: '作废费用',
+  RECONCILIATION_CREATE: '生成对账单', RECONCILIATION_CREATED: '生成对账单', RECONCILIATION_ADJUST: '调整对账单',
+  BILL_CREATE: '创建账单', BILL_ISSUE: '出账', BILL_ADJUST: '调整账单', BILL_VOID: '作废账单',
+  SETTLEMENT_AR_CREATE: '生成应收结算单', SETTLEMENT_AP_CREATE: '生成应付结算单', SETTLEMENT_PAYMENT_CREATE: '登记收付款',
+  RECEIPT_CREATE: '登记收款', COST_CREATE: '登记成本', VOID: '作废', REOPEN: '重开',
+}
+const financeOperationResultLabels: Record<string, string> = {
+  SUCCESS: '操作成功', FAILED: '操作失败', PENDING: '待处理', PROCESSING: '处理中',
+}
+const financeDirectionLabels: Record<string, string> = {
+  RECEIVABLE: '应收', PAYABLE: '应付',
+}
+
+function codeLabel(value: unknown, labels: Record<string, string>, unknownLabel: string) {
+  const code = normalizeStatus(value)
+  if (!code) return '—'
+  return labels[code] || unknownLabel
+}
+
+export const financeSourceTypeLabel = (value: unknown) => codeLabel(value, financeSourceTypeLabels, '未知来源类型')
+export const financeBusinessTypeLabel = (value: unknown) => codeLabel(value, financeBusinessTypeLabels, '未知业务类型')
+export const financeDocumentTypeLabel = (value: unknown) => codeLabel(value, financeDocumentTypeLabels, '未知单据类型')
+export const financeOperationActionLabel = (value: unknown) => codeLabel(value, financeOperationActionLabels, '未知操作')
+export const financeOperationResultLabel = (value: unknown) => codeLabel(value, financeOperationResultLabels, '结果未知')
+export const financeDirectionLabel = (value: unknown) => codeLabel(value, financeDirectionLabels, '未知方向')
diff --git a/src/modules/finance/types.ts b/src/modules/finance/types.ts
new file mode 100644
index 00000000..0d09a169
--- /dev/null
+++ b/src/modules/finance/types.ts
@@ -0,0 +1,505 @@
+export type FinanceBillStatus = 'DRAFT' | 'PENDING_REVIEW' | 'APPROVED' | 'REJECTED' | 'ISSUED' | 'PARTIALLY_PAID' | 'PAID' | 'VOIDED'
+export type FinanceCostType = 'SINGLE_ORDER' | 'CONTAINER_SHARED'
+export type FinancePaymentMethod = 'BANK_TRANSFER' | 'CASH' | 'OTHER'
+export type FinanceFeeDirection = 'RECEIVABLE' | 'PAYABLE'
+export type FinanceReviewStatus = 'DRAFT' | 'PENDING' | 'APPROVED' | 'REJECTED'
+export type FinanceReconciliationStatus = 'DRAFT' | 'PENDING_REVIEW' | 'APPROVED' | 'REJECTED' | 'ISSUED' | 'VOIDED'
+export type FinanceSettlementStatus = 'ISSUED' | 'PARTIALLY_PAID' | 'PAID' | 'VOIDED'
+export type FinancePaymentStatus = 'UNPAID' | 'PARTIALLY_PAID' | 'PAID'
+export type FinanceCustomerConfirmationStatus = 'NOT_REQUIRED' | 'PENDING_CONFIRMATION' | 'CONFIRMED'
+
+export interface FinanceVoucherResource {
+  fileId: string
+  customerId: string
+  fileName: string
+  contentType: string
+  sizeBytes: number
+}
+
+export interface FinanceCustomerTerms {
+  customerId: string
+  customerName: string
+  creditDays: number
+  status: string
+}
+
+export interface FinanceAccountEntry {
+  entryType: 'RECEIVABLE' | 'RECEIPT'
+  resourceId: string
+  resourceNo: string
+  occurredAt: string
+  debitAmount: number
+  creditAmount: number
+  currency: 'CNY'
+  status: string
+}
+
+export interface FinanceCustomerAccountReadModel {
+  customerId: string
+  currency: 'CNY'
+  accountMode: 'MANUAL_RECEIVABLE_LEDGER'
+  totalReceivable: number
+  totalReceived: number
+  outstandingAmount: number
+  entries: FinanceAccountEntry[]
+}
+
+export interface FinanceFeePoolItem {
+  poolItemId: string
+  feeSourceId: string | null
+  customerId: string
+  customerName?: string
+  direction: 'RECEIVABLE' | 'PAYABLE'
+  sourceType: string
+  sourceId: string
+  sourceVersion: number
+  orderId: string | null
+  inboundId: string | null
+  containerId: string | null
+  feeItemName: string
+  amount: number
+  currency: 'CNY'
+  settlementMode?: string | null
+  status: string
+  createdAt: string
+}
+
+export interface FinanceFeeSourceSummary extends FinanceFeePoolItem {
+  feeSourceId: string
+  sourceSystem: string
+  sourceBusinessId: string
+  customerName: string
+  supplierId: string | null
+  supplierName: string
+  inboundCode: string
+  containerNo: string
+  businessDate: string
+  quantity?: number | null
+  quantityUnit?: string | null
+  unitPrice?: number | null
+  periodStart?: string | null
+  periodEnd?: string | null
+  originalCurrency?: 'CNY' | 'USD'
+  originalAmount?: number
+  exchangeRate?: number
+  exchangeRateMonth?: string | null
+  reviewStatus: FinanceReviewStatus
+  sourceStatus: string
+  statementGenerated: boolean
+}
+
+export interface FinanceStatementReadModel {
+  id: string
+  customerId: string
+  billNo: string
+  customerName: string
+  billDate: string
+  dueDate: string
+  periodStart?: string
+  periodEnd?: string
+  creditDays?: number
+  lineCount?: number
+  sourceCount?: number
+  sourceAmount?: number
+  adjustmentAmount?: number
+  totalAmount: number
+  receivedAmount: number
+  outstandingAmount: number
+  currency: 'CNY'
+  status: FinanceBillStatus
+  version: number
+  customerConfirmationStatus?: FinanceCustomerConfirmationStatus
+  customerConfirmedBy?: string
+  customerConfirmedByName?: string
+  customerConfirmedAt?: string
+  settled?: boolean
+  lastReceiptAt?: string
+  submittedAt?: string
+  reviewedAt?: string
+  issuedAt?: string
+  remark?: string
+  createdBy?: string
+  createdByName?: string
+  createdAt?: string
+  updatedBy?: string
+  updatedByName?: string
+  updatedAt?: string
+}
+
+export interface FinanceReceivableSettlement {
+  id: string
+  customerId: string
+  settlementNo: string
+  customerName?: string
+  reconciliationStatementId?: string
+  reconciliationStatementNo?: string
+  businessPeriod?: string
+  feeItemSummary?: string
+  generatedDate?: string
+  createdBy?: string
+  createdByName?: string
+  createdAt?: string
+  updatedAt?: string
+  lastPaymentAt?: string
+  billDate: string
+  dueDate: string
+  receivableAmount: number
+  receivedAmount: number
+  outstandingAmount: number
+  paymentStatus?: FinancePaymentStatus
+  currency: 'CNY'
+  status: FinanceBillStatus
+  version: number
+}
+
+export interface FinancePayableSettlement {
+  id: string
+  customerId: string
+  settlementNo: string
+  customerName?: string
+  supplierId?: string
+  costType: FinanceCostType
+  orderId: string | null
+  inboundId: string | null
+  containerId: string | null
+  supplierName: string
+  feeItemName: string
+  feeItemSummary?: string
+  businessPeriod?: string
+  generatedDate?: string
+  dueDate?: string
+  payableAmount: number
+  paidAmount: number
+  outstandingAmount: number
+  paymentStatus?: FinancePaymentStatus
+  currency: 'CNY'
+  status: string
+  createdAt: string
+  createdBy?: string
+  createdByName?: string
+  updatedAt?: string
+  lastPaymentAt?: string
+  version: number
+}
+
+export interface FinanceAccountSummary {
+  customerId: string
+  customerCode: string
+  customerName: string
+  contactName: string
+  contactPhone: string
+  outstandingReceivable: number
+  pendingBilling: number
+  receivedInPeriod: number
+  totalCost: number
+  paidCost: number
+  outstandingPayable: number
+  status: string
+  lastChangedAt: string
+  actualBalance: string
+  frozenBalance: string
+  availableBalance: string
+  creditLimit: string
+  creditUsed: string
+  availableCredit: string
+  creditExpiresOn: string | null
+  creditActive: boolean
+  accountVersion: number
+  pendingRechargeCount: number
+}
+
+export interface ReceivableStatisticsRow {
+  customerId: string
+  customerName: string
+  currency: 'CNY'
+  totalReceivable: string
+  totalReceived: string
+  totalOutstanding: string
+}
+
+export interface ReceivableStatisticsResult {
+  statisticsMonth: string
+  currency: 'CNY'
+  totalReceivable: string
+  totalReceived: string
+  totalOutstanding: string
+  totalCustomers: number
+  page: number
+  pageSize: number
+  records: ReceivableStatisticsRow[]
+}
+
+export interface FinanceLedgerEntry {
+  ledgerId: string
+  occurredAt: string
+  businessType: string
+  documentType: string
+  documentId: string
+  documentNo: string
+  receivableChange: number
+  payableChange: number
+  outstandingReceivableAfter: number
+  operatorName: string
+  remark: string
+  businessNo?: string | null
+  changeType?: string | null
+  amount?: string | null
+  actualBalanceAfter?: string | null
+  frozenBalanceAfter?: string | null
+  availableBalanceAfter?: string | null
+  creditLimitAfter?: string | null
+  creditUsedAfter?: string | null
+  availableCreditAfter?: string | null
+  creditExpiresOnAfter?: string | null
+  sourceType?: string | null
+  sourceNo?: string | null
+  occurredDate?: string | null
+  paymentMethod?: string | null
+  referenceNo?: string | null
+  createdAt?: string | null
+}
+
+export interface FinanceRechargeRequest {
+  requestId: string
+  requestNo: string
+  amount: string
+  paymentMethod: string
+  voucherFileId: string
+  voucherFileName: string
+  status: string
+  version: number
+  submittedByName: string
+  reviewedByName: string
+  reviewRemark: string
+  createdAt: string
+  reviewedAt: string
+}
+
+export interface FinanceRechargeReviewPayload {
+  decision: 'APPROVE' | 'REJECT'
+  remark?: string
+  expectedVersion: number
+}
+
+export interface FinanceAccountAdjustmentPayload {
+  type: 'RECHARGE' | 'DEDUCTION'
+  amount: string
+  occurredDate: string
+  paymentMethod: string
+  referenceNo?: string
+  remark?: string
+  expectedAccountVersion: number
+}
+
+export interface FinanceFeeSourceDetail extends FinanceFeeSourceSummary {
+  sourceFeeId: string
+  reviewReason?: string
+  sourceHash?: string
+  operationLogs?: Array<{ occurredAt: string; action: string; operatorName: string; result: string; remark?: string }>
+  operationVersion: number
+}
+
+export interface FinanceSettlementLine {
+  feeSourceId: string
+  sourceType: string
+  sourceFeeId: string
+  sourceVersion: number
+  direction: 'RECEIVABLE' | 'PAYABLE'
+  customerId: string
+  customerName: string
+  supplierId: string | null
+  supplierName: string
+  orderId: string | null
+  orderNo: string
+  inboundId: string | null
+  inboundCode: string
+  containerId: string | null
+  containerNo: string
+  businessDate: string
+  feeItemName: string
+  quantity: number | null
+  unitPrice: number | null
+  amount: number
+  currency: 'CNY'
+  reviewStatus: FinanceReviewStatus
+  sourceStatus: string
+  statementGenerated: boolean
+}
+
+export interface FinanceSettlementDetail {
+  id: string
+  settlementNo: string
+  customerId: string
+  supplierId?: string
+  customerName?: string
+  supplierName?: string
+  reconciliationStatementId?: string
+  reconciliationStatementNo?: string
+  businessPeriod?: string
+  feeItemSummary?: string
+  generatedDate?: string
+  dueDate?: string
+  paymentStatus?: FinancePaymentStatus
+  direction: 'RECEIVABLE' | 'PAYABLE'
+  amount: number
+  paidAmount: number
+  outstandingAmount: number
+  currency: 'CNY'
+  status: string
+  createdBy?: string
+  createdByName?: string
+  createdAt?: string
+  updatedAt?: string
+  lastPaymentAt?: string
+  version: number
+  lines: FinanceSettlementLine[]
+  transactions: Array<{ transactionId: string; transactionType: string; transactionDate: string; amount: number; method: string; referenceNo: string; voucherFileIds: string[]; createdBy: string; createdByName: string; createdAt: string; remark?: string }>
+  revisions: Array<{ revisionNo: number; action: string; beforeAmount: number; afterAmount: number; reason?: string; operatorId: string; operatorName: string; occurredAt: string }>
+}
+
+export interface FinanceSettlementActionPayload {
+  action: 'VOID' | 'REOPEN'
+  reason: string
+  expectedVersion: number
+}
+
+export interface FinanceReconciliationDetail extends FinanceBillDetail {
+  periodStart: string
+  periodEnd: string
+  creditDays: number
+  settled: boolean
+  createdBy?: string
+  createdByName?: string
+  createdAt?: string
+  updatedBy?: string
+  updatedByName?: string
+  updatedAt?: string
+  paymentHistory: Array<{ transactionId: string; transactionType: string; transactionDate: string; amount: number; method: string; referenceNo: string; voucherFileIds: string[]; createdBy: string; createdByName: string; occurredAt: string; remark?: string }>
+  revisions: Array<{ revisionNo: number; action: string; beforeAmount: number; afterAmount: number; reason?: string; operatorId: string; operatorName: string; occurredAt: string }>
+}
+
+export interface CreateReconciliationPayload {
+  customerId: string
+  currency: 'CNY'
+  generationMode: 'BY_CUTOFF' | 'SELECTED'
+  feeSourceIds?: string[]
+  periodStart: string
+  periodEnd: string
+  remark?: string
+}
+
+export interface ReconciliationActionPayload {
+  action: 'SUBMIT' | 'APPROVE' | 'REJECT' | 'ISSUE' | 'ADJUST' | 'VOID' | 'REOPEN'
+  reason?: string
+  expectedVersion: number
+  adjustmentLines?: Array<{ statementLineId: string; adjustedAmount: number; reason: string }>
+}
+
+export interface CreateReceivableSettlementPayload {
+  reconciliationStatementId: string
+  currency: 'CNY'
+}
+
+export interface CreatePayableSettlementPayload {
+  customerId: string
+  supplierId: string
+  feeSourceIds: string[]
+  dueDate: string
+  currency: 'CNY'
+}
+
+export interface CreateSettlementPaymentPayload {
+  transactionDate: string
+  amount: number
+  currency: 'CNY'
+  method: FinancePaymentMethod
+  referenceNo?: string
+  voucherFileIds: string[]
+  expectedVersion: number
+  remark?: string
+}
+
+export interface FinanceBillResource {
+  id: string
+  billNo: string
+  customerId: string
+  customerName: string
+  billDate: string
+  dueDate: string
+  currency: 'CNY'
+  totalAmount: number
+  paidAmount: number
+  outstandingAmount: number
+  status: FinanceBillStatus
+  version: number
+  customerConfirmationStatus?: FinanceCustomerConfirmationStatus
+  customerConfirmedBy?: string
+  customerConfirmedByName?: string
+  customerConfirmedAt?: string
+}
+
+export interface FinanceBillLine {
+  statementLineId?: string
+  sourceFeeId: string
+  sourceFeeVersion: number
+  sourceHash?: string
+  orderId: string | null
+  inboundId: string | null
+  containerId?: string | null
+  direction?: 'RECEIVABLE' | 'PAYABLE'
+  sourceType?: string
+  sourceNo?: string
+  inboundCode?: string
+  containerNo?: string
+  businessDate?: string
+  quantity?: number | null
+  unitPrice?: number | null
+  feeItemName: string
+  sourceAmount?: number
+  amount: number
+  adjustmentReason?: string
+}
+
+export interface FinanceBillDetail extends FinanceBillResource {
+  remark: string
+  lines: FinanceBillLine[]
+}
+
+export interface FinanceBillRevision {
+  id: string
+  billId: string
+  version: number
+  reason: string
+  createdBy: string
+  createdAt: string
+  status: FinanceBillStatus
+  totalAmount: number
+  receivedAmount: number
+  outstandingAmount: number
+  lines: FinanceBillLine[]
+}
+
+export interface FinanceReceiptResource {
+  id: string
+  customerId: string
+  customerName: string
+  receivedDate: string
+  amount: number
+  currency: 'CNY'
+  paymentMethod: FinancePaymentMethod
+  voucherFileIds: string[]
+  allocationCount: number
+}
+
+export interface FinanceCostResource {
+  id: string
+  costType: FinanceCostType
+  customerId: string
+  orderId: string | null
+  containerId: string | null
+  expenseName: string
+  amount: number
+  currency: 'CNY'
+  voucherFileIds: string[]
+  createdAt: string
+}
diff --git a/src/modules/first-leg-orders/api/platformFirstLegOrders.test.ts b/src/modules/first-leg-orders/api/platformFirstLegOrders.test.ts
new file mode 100644
index 00000000..c141fa9c
--- /dev/null
+++ b/src/modules/first-leg-orders/api/platformFirstLegOrders.test.ts
@@ -0,0 +1,106 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import {
+  getPlatformTenantOrderStatistics,
+  acceptPlatformFirstLegOrder,
+  approvePlatformFirstLegOrder,
+  cancelPlatformFirstLegOrder,
+  completePlatformFirstLegOrder,
+  getPlatformFirstLegOrder,
+  listPlatformFirstLegOrders,
+  startPlatformFirstLegOrder,
+  updatePlatformFirstLegOrderExpress,
+} from './platformFirstLegOrders'
+
+vi.mock('@/shared/api/http', () => ({
+  http: { get: vi.fn(), post: vi.fn(), put: vi.fn() },
+  unwrapApiResponse: <T>(response: { data: T }) => response.data,
+}))
+
+describe('platform first-leg order API', () => {
+  beforeEach(() => {
+    vi.mocked(http.get).mockReset()
+    vi.mocked(http.post).mockReset()
+    vi.mocked(http.put).mockReset()
+  })
+
+  it('uses the submitted master-order statistics contract and preserves the long customer id', async () => {
+    vi.mocked(http.get).mockResolvedValue({ code: '200', data: { tenantId: '9007199254740993', totalSubmittedOrders: 12, currentMonthSubmittedOrders: 3, monthStart: '2026-08-01T00:00:00+08:00', nextMonthStart: '2026-09-01T00:00:00+08:00', zoneId: 'Asia/Shanghai', asOf: '2026-08-13T12:00:00+08:00' } })
+
+    const result = await getPlatformTenantOrderStatistics('9007199254740993')
+
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/orders/first-leg/tenant-statistics', { params: { tenantId: '9007199254740993' } })
+    expect(result).toMatchObject({ tenantId: '9007199254740993', totalSubmittedOrders: 12, currentMonthSubmittedOrders: 3, zoneId: 'Asia/Shanghai' })
+  })
+
+  it('queries the cross-tenant review queue with one server-paginated request', async () => {
+    const page = { records: [], page: 2, size: 20, total: 0, pages: 0 }
+    vi.mocked(http.get).mockResolvedValue({ code: '200', message: 'success', data: page })
+
+    await expect(listPlatformFirstLegOrders({
+      keyword: 'FL2026', status: 'SUBMITTED', createdFrom: '2026-07-01T00:00:00', createdTo: '2026-07-31T23:59:59', page: 2, size: 20,
+    })).resolves.toEqual(page)
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/orders/first-leg', {
+      params: {
+        keyword: 'FL2026', status: 'SUBMITTED', createdFrom: '2026-07-01T00:00:00', createdTo: '2026-07-31T23:59:59', page: 2, size: 20,
+      },
+    })
+    expect(http.get).toHaveBeenCalledTimes(1)
+  })
+
+  it('adds the optional enterprise filter without changing server pagination', async () => {
+    const page = { records: [], page: 1, size: 20, total: 0, pages: 0 }
+    vi.mocked(http.get).mockResolvedValue({ code: '200', message: 'success', data: page })
+
+    await listPlatformFirstLegOrders({ tenantId: '2084455952401629185', status: 'SUBMITTED', page: 1, size: 20 })
+
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/orders/first-leg', {
+      params: { tenantId: '2084455952401629185', status: 'SUBMITTED', page: 1, size: 20 },
+    })
+  })
+
+  it('normalizes string pagination fields returned by the gateway', async () => {
+    vi.mocked(http.get).mockResolvedValue({
+      code: '200',
+      message: 'success',
+      data: { records: [], page: '1', size: '20', total: '6', pages: '1' },
+    })
+
+    await expect(listPlatformFirstLegOrders({ status: 'SUBMITTED', page: 1, size: 20 })).resolves.toMatchObject({
+      page: 1,
+      size: 20,
+      total: 6,
+      pages: 1,
+    })
+  })
+
+  it('uses the platform lifecycle routes and target tenant query parameter', async () => {
+    vi.mocked(http.get).mockResolvedValue({ code: '200', message: 'success', data: { order: {} } })
+    vi.mocked(http.post).mockResolvedValue({ code: '200', message: 'success', data: null })
+
+    await getPlatformFirstLegOrder('10001', '90001')
+    await approvePlatformFirstLegOrder('10001', '90001')
+    await acceptPlatformFirstLegOrder('10001', '90001')
+    await startPlatformFirstLegOrder('10001', '90001')
+    await completePlatformFirstLegOrder('10001', '90001')
+    await cancelPlatformFirstLegOrder('10001', '90001', '客户取消')
+
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/orders/first-leg/90001', { params: { tenantId: '10001' } })
+    expect(http.post).toHaveBeenNthCalledWith(1, '/platform/v1/orders/first-leg/90001/approve', undefined, { params: { tenantId: '10001' } })
+    expect(http.post).toHaveBeenNthCalledWith(2, '/platform/v1/orders/first-leg/90001/accept', undefined, { params: { tenantId: '10001' } })
+    expect(http.post).toHaveBeenNthCalledWith(3, '/platform/v1/orders/first-leg/90001/start', undefined, { params: { tenantId: '10001' } })
+    expect(http.post).toHaveBeenNthCalledWith(4, '/platform/v1/orders/first-leg/90001/complete', undefined, { params: { tenantId: '10001' } })
+    expect(http.post).toHaveBeenNthCalledWith(5, '/platform/v1/orders/first-leg/90001/cancel', { reason: '客户取消' }, { params: { tenantId: '10001' } })
+  })
+
+  it('writes the backend express contract as names, not a guessed master-data ID', async () => {
+    vi.mocked(http.put).mockResolvedValue({ code: '200', message: 'success', data: null })
+
+    await updatePlatformFirstLegOrderExpress('10001', '90001', { expressCompany: '顺丰速运', expressTrackingNo: 'SF123456' })
+    expect(http.put).toHaveBeenCalledWith(
+      '/platform/v1/orders/first-leg/90001/express',
+      { expressCompany: '顺丰速运', expressTrackingNo: 'SF123456' },
+      { params: { tenantId: '10001' } },
+    )
+  })
+})
diff --git a/src/modules/first-leg-orders/api/platformFirstLegOrders.ts b/src/modules/first-leg-orders/api/platformFirstLegOrders.ts
new file mode 100644
index 00000000..45a9d704
--- /dev/null
+++ b/src/modules/first-leg-orders/api/platformFirstLegOrders.ts
@@ -0,0 +1,205 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+
+export type PlatformFirstLegOrderStatus =
+  | 'DRAFT'
+  | 'SUBMITTED'
+  | 'APPROVED'
+  | 'ACCEPTED'
+  | 'REJECTED'
+  | 'CANCELLED'
+  | 'PROCESSING'
+  | 'COMPLETED'
+
+export interface PlatformFirstLegOrderResource {
+  id: number | string
+  tenantId: number | string
+  orderNo: string | null
+  customerId: number | string | null
+  customerName: string
+  status: PlatformFirstLegOrderStatus
+  transportMode: 'SEA' | 'AIR' | 'RAIL' | 'TRUCK'
+  tradeTerm: string | null
+  destinationCountryCode: string
+  destinationWarehouseId: number | string | null
+  destinationWarehouseName: string
+  expectedShipDate: string | null
+  customerRemark: string | null
+  pickupMethod: string
+  receivingWarehouseId: number | string
+  receivingWarehouseName: string
+  receivingWarehouseAddress: string | null
+  receivingTime: string | null
+  channelCode: string
+  channelName: string
+  taxMode: string
+  containerMode: string | null
+  customsInspection: boolean | null
+  destinationType: string
+  amazonWarehouseCode: string | null
+  shipmentId: string | null
+  referenceId: string | null
+  expressCompany: string | null
+  expressTrackingNo: string | null
+  createdAt: string
+  updatedAt: string
+}
+
+export interface PlatformFirstLegCargoResource {
+  id: number | string
+  itemNo: number
+  cargoName: string
+  cargoNameEn: string | null
+  packageType: string
+  packageCount: number
+  grossWeightKg: number
+  volumeCbm: number
+  totalQuantity: number | null
+  cargoRemark: string | null
+}
+
+export interface PlatformFirstLegPartyResource {
+  id: number | string
+  partyType: 'SENDER' | 'RECEIVER' | string
+  companyName: string
+  contactName: string
+  phone: string
+  email: string | null
+  countryCode: string
+  province: string | null
+  city: string
+  district: string | null
+  addressLine: string
+  postalCode: string | null
+}
+
+export interface PlatformOrderStatusHistoryResource {
+  id: number | string
+  fromStatus: PlatformFirstLegOrderStatus | null
+  toStatus: PlatformFirstLegOrderStatus
+  action: string
+  reason: string | null
+  operatorName: string | null
+  occurredAt: string
+}
+
+export interface PlatformOrderInternalNoteResource {
+  id: number | string
+  content: string
+  createdAt: string
+  createdBy: number | string | null
+}
+
+export interface PlatformFirstLegOrderDetailResource {
+  order: PlatformFirstLegOrderResource
+  cargoes: PlatformFirstLegCargoResource[]
+  parties: PlatformFirstLegPartyResource[]
+  internalNotes: PlatformOrderInternalNoteResource[]
+  statusHistory: PlatformOrderStatusHistoryResource[]
+}
+
+export interface PlatformFirstLegOrderPageResource {
+  records: PlatformFirstLegOrderResource[]
+  page: number
+  size: number
+  total: number
+  pages: number
+}
+
+export interface PlatformTenantOrderStatistics {
+  tenantId: string
+  totalSubmittedOrders: number
+  currentMonthSubmittedOrders: number
+  monthStart: string
+  nextMonthStart: string
+  zoneId: 'Asia/Shanghai' | string
+  asOf: string
+}
+
+type PlatformFirstLegOrderPagePayload = Omit<PlatformFirstLegOrderPageResource, 'page' | 'size' | 'total' | 'pages'> & {
+  page: number | string
+  size: number | string
+  total: number | string
+  pages: number | string
+}
+
+export interface PlatformFirstLegOrderQuery {
+  tenantId?: string
+  keyword?: string
+  status?: PlatformFirstLegOrderStatus
+  customerId?: string
+  destinationWarehouseId?: string
+  createdFrom?: string
+  createdTo?: string
+  page: number
+  size: number
+}
+
+async function getData<T>(path: string, params?: Record<string, unknown>) {
+  const response = await http.get<ApiEnvelope<T>, ApiEnvelope<T>>(path, { params })
+  return unwrapApiResponse(response)
+}
+
+async function postData<T>(path: string, body?: unknown, params?: Record<string, unknown>) {
+  const response = await http.post<ApiEnvelope<T>, ApiEnvelope<T>>(path, body, { params })
+  return unwrapApiResponse(response)
+}
+
+function paginationNumber(value: number | string, fallback: number) {
+  const parsed = Number(value)
+  return Number.isFinite(parsed) && parsed >= 0 ? Math.trunc(parsed) : fallback
+}
+
+export async function listPlatformFirstLegOrders(query: PlatformFirstLegOrderQuery) {
+  const result = await getData<PlatformFirstLegOrderPagePayload>('/platform/v1/orders/first-leg', { ...query })
+  return {
+    ...result,
+    page: paginationNumber(result.page, query.page),
+    size: paginationNumber(result.size, query.size),
+    total: paginationNumber(result.total, 0),
+    pages: paginationNumber(result.pages, 0),
+  } satisfies PlatformFirstLegOrderPageResource
+}
+
+export async function getPlatformTenantOrderStatistics(tenantId: string): Promise<PlatformTenantOrderStatistics> {
+  const result = await getData<Omit<PlatformTenantOrderStatistics, 'tenantId'> & { tenantId: number | string }>(
+    '/platform/v1/orders/first-leg/tenant-statistics',
+    { tenantId },
+  )
+  return { ...result, tenantId: String(result.tenantId) }
+}
+
+export function getPlatformFirstLegOrder(tenantId: string, orderId: string) {
+  return getData<PlatformFirstLegOrderDetailResource>(`/platform/v1/orders/first-leg/${orderId}`, { tenantId })
+}
+
+export function approvePlatformFirstLegOrder(tenantId: string, orderId: string) {
+  return postData<void>(`/platform/v1/orders/first-leg/${orderId}/approve`, undefined, { tenantId })
+}
+
+export function acceptPlatformFirstLegOrder(tenantId: string, orderId: string) {
+  return postData<void>(`/platform/v1/orders/first-leg/${orderId}/accept`, undefined, { tenantId })
+}
+
+export function startPlatformFirstLegOrder(tenantId: string, orderId: string) {
+  return postData<void>(`/platform/v1/orders/first-leg/${orderId}/start`, undefined, { tenantId })
+}
+
+export function completePlatformFirstLegOrder(tenantId: string, orderId: string) {
+  return postData<void>(`/platform/v1/orders/first-leg/${orderId}/complete`, undefined, { tenantId })
+}
+
+export function cancelPlatformFirstLegOrder(tenantId: string, orderId: string, reason: string) {
+  return postData<void>(`/platform/v1/orders/first-leg/${orderId}/cancel`, { reason }, { tenantId })
+}
+
+export function updatePlatformFirstLegOrderExpress(
+  tenantId: string,
+  orderId: string,
+  payload: { expressCompany: string; expressTrackingNo: string },
+) {
+  return http.put<ApiEnvelope<void>, ApiEnvelope<void>>(
+    `/platform/v1/orders/first-leg/${orderId}/express`,
+    payload,
+    { params: { tenantId } },
+  ).then(unwrapApiResponse)
+}
diff --git a/src/modules/first-leg-orders/index.ts b/src/modules/first-leg-orders/index.ts
new file mode 100644
index 00000000..c8916055
--- /dev/null
+++ b/src/modules/first-leg-orders/index.ts
@@ -0,0 +1,7 @@
+export {
+  getPlatformTenantOrderStatistics,
+  listPlatformFirstLegOrders,
+  type PlatformFirstLegOrderResource,
+  type PlatformFirstLegOrderStatus,
+  type PlatformTenantOrderStatistics,
+} from './api/platformFirstLegOrders'
diff --git a/src/modules/iam/api/platformIam.test.ts b/src/modules/iam/api/platformIam.test.ts
new file mode 100644
index 00000000..86774b90
--- /dev/null
+++ b/src/modules/iam/api/platformIam.test.ts
@@ -0,0 +1,464 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import {
+  approveEnterpriseReview,
+  archivePlatformTenant,
+  assignPlatformInternalUserRoles,
+  changePlatformManagedUserStatus,
+  changePlatformInternalUserStatus,
+  changePlatformTenantStatus,
+  changePlatformPermissionStatus,
+  changePlatformRoleStatus,
+  createPlatformPermission,
+  createPlatformManagedUser,
+  createPlatformRole,
+  createPlatformTenant,
+  createPlatformTenantImpersonation,
+  deletePlatformPermission,
+  deletePlatformRole,
+  downloadTenantQualification,
+  getPlatformTenantDimensionInitializationStatus,
+  listPlatformTenants,
+  listPlatformTenantOrderCounts,
+  listTenantQualifications,
+  listPlatformPermissions,
+  listPlatformRoles,
+  listPlatformInternalUsers,
+  listPlatformManagedUsers,
+  listSharedReceivingOverseasWarehouseOptions,
+  getPlatformUserOptions,
+  qualificationFileName,
+  replacePlatformRolePermissions,
+  resetPlatformInternalUserPassword,
+  resetPlatformManagedUserPassword,
+  resetPlatformTenantOwnerPassword,
+  submitPlatformTenantReview,
+  updatePlatformInternalUser,
+  updatePlatformManagedUser,
+  updatePlatformPermission,
+  updatePlatformRole,
+  updatePlatformTenant,
+  uploadPlatformTenantQualification,
+  uploadPlatformTenantRequiredQualificationPackage,
+  type PlatformPermissionResource,
+  type PlatformInternalUser,
+  type PlatformManagedUser,
+  type PlatformRoleResource,
+} from './platformIam'
+
+vi.mock('@/shared/api/http', () => ({
+  http: { get: vi.fn(), post: vi.fn(), put: vi.fn(), delete: vi.fn() },
+  unwrapApiResponse: <T>(response: { data: T }) => response.data,
+}))
+
+const role: PlatformRoleResource = {
+  id: 4000002,
+  tenantId: 0,
+  appCode: 'PLATFORM',
+  roleCode: 'CUSTOMER_REVIEWER',
+  roleName: '企业审核员',
+  roleType: 'SYSTEM',
+  status: 'ACTIVE',
+  description: '企业资料与入驻审核',
+  memberCount: 3,
+  permissionIds: ['5100010'],
+}
+
+const permission: PlatformPermissionResource = {
+  id: 5100010,
+  tenantId: 0,
+  appCode: 'PLATFORM',
+  permissionType: 'MENU',
+  parentId: 5100000,
+  permissionCode: 'platform:customer:list',
+  permissionName: '企业客户',
+  routePath: '/customers',
+  httpMethod: null,
+  sortNo: 10,
+  status: 'ACTIVE',
+  builtIn: false,
+}
+
+const internalUser: PlatformInternalUser = {
+  membershipId: 3000001,
+  userId: 2000001,
+  authUserId: 2000001,
+  username: 'platform_admin',
+  displayName: '平台管理员',
+  phone: '13800138000',
+  email: 'admin@example.com',
+  memberType: 'INTERNAL',
+  memberNo: 'PLATFORM-0001',
+  status: 'ACTIVE',
+  roleIds: [4000001],
+}
+
+const managedUser: PlatformManagedUser = {
+  membershipId: '3000002',
+  userId: '2000002',
+  authUserId: '1000002',
+  username: 'zhangwei',
+  displayName: '张伟',
+  phone: '13800138000',
+  email: 'zhangwei@example.com',
+  tenantId: '0',
+  tenantName: '平台',
+  memberType: 'INTERNAL',
+  memberNo: 'PLATFORM-3000002',
+  status: 'ACTIVE',
+  roleIds: ['40001'],
+  roleNames: ['运营管理员'],
+  lastLoginAt: '2026-06-01T10:30:00',
+  protectedAccount: false,
+  overseasWarehouseId: null,
+}
+
+describe('platform IAM roles', () => {
+  beforeEach(() => {
+    vi.mocked(http.get).mockReset()
+    vi.mocked(http.post).mockReset()
+    vi.mocked(http.put).mockReset()
+    vi.mocked(http.delete).mockReset()
+  })
+
+  it('loads roles from the platform IAM prefix', async () => {
+    vi.mocked(http.get).mockResolvedValue({ code: '200', message: 'success', data: [role] })
+
+    await expect(listPlatformRoles()).resolves.toEqual([role])
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/iam/roles')
+  })
+
+  it('creates a platform role with the documented payload', async () => {
+    const payload = {
+      roleCode: 'CUSTOMER_REVIEWER',
+      roleName: '企业审核员',
+      description: '企业资料与入驻审核',
+    }
+    vi.mocked(http.post).mockResolvedValue({ code: '200', message: 'success', data: role })
+
+    await expect(createPlatformRole(payload)).resolves.toEqual(role)
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/iam/roles', payload)
+  })
+
+  it('updates status, permissions, and deletes roles with the implemented IAM routes', async () => {
+    vi.mocked(http.put).mockResolvedValue({ code: '200', message: 'success', data: role })
+    vi.mocked(http.delete).mockResolvedValue({ code: '200', message: 'success', data: null })
+
+    await expect(updatePlatformRole(role.id, { roleName: '审核主管', description: '负责企业审核' })).resolves.toEqual(role)
+    await expect(changePlatformRoleStatus(role.id, 'DISABLED')).resolves.toEqual(role)
+    await expect(replacePlatformRolePermissions(role.id, ['5100010'])).resolves.toEqual(role)
+    await expect(deletePlatformRole(role.id)).resolves.toBeNull()
+
+    expect(http.put).toHaveBeenNthCalledWith(1, `/platform/v1/iam/roles/${role.id}`, { roleName: '审核主管', description: '负责企业审核' })
+    expect(http.put).toHaveBeenNthCalledWith(2, `/platform/v1/iam/roles/${role.id}/status`, { status: 'DISABLED' })
+    expect(http.put).toHaveBeenNthCalledWith(3, '/platform/v1/iam/roles/permissions', { roleId: role.id, permissionIds: ['5100010'] })
+    expect(http.delete).toHaveBeenCalledWith(`/platform/v1/iam/roles/${role.id}`)
+  })
+
+  it('loads and creates permission resources under the platform IAM prefix', async () => {
+    vi.mocked(http.get).mockResolvedValue({ code: '200', message: 'success', data: [permission] })
+    vi.mocked(http.post).mockResolvedValue({ code: '200', message: 'success', data: permission })
+    const payload = {
+      type: 'MENU' as const,
+      code: permission.permissionCode,
+      name: permission.permissionName,
+      parentId: permission.parentId,
+      routePath: permission.routePath,
+      httpMethod: null,
+      sortNo: permission.sortNo,
+    }
+
+    await expect(listPlatformPermissions()).resolves.toEqual([permission])
+    await expect(createPlatformPermission(payload)).resolves.toEqual(permission)
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/iam/permissions')
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/iam/permissions', payload)
+  })
+
+  it('updates, changes status, and deletes custom permission resources with IAM routes', async () => {
+    vi.mocked(http.put).mockResolvedValue({ code: '200', message: 'success', data: permission })
+    vi.mocked(http.delete).mockResolvedValue({ code: '200', message: 'success', data: null })
+    const payload = { name: '企业客户', parentId: permission.parentId, routePath: '/customers', httpMethod: null, sortNo: 10 }
+
+    await expect(updatePlatformPermission(permission.id, payload)).resolves.toEqual(permission)
+    await expect(changePlatformPermissionStatus(permission.id, 'DISABLED')).resolves.toEqual(permission)
+    await expect(deletePlatformPermission(permission.id)).resolves.toBeNull()
+
+    expect(http.put).toHaveBeenNthCalledWith(1, `/platform/v1/iam/permissions/${permission.id}`, payload)
+    expect(http.put).toHaveBeenNthCalledWith(2, `/platform/v1/iam/permissions/${permission.id}/status`, { status: 'DISABLED' })
+    expect(http.delete).toHaveBeenCalledWith(`/platform/v1/iam/permissions/${permission.id}`)
+  })
+
+  it('maintains internal users through their public membership ID', async () => {
+    vi.mocked(http.get).mockResolvedValue({ code: '200', message: 'success', data: [internalUser] })
+    vi.mocked(http.put).mockResolvedValue({ code: '200', message: 'success', data: internalUser })
+    const update = {
+      displayName: '平台管理员',
+      phone: '13800138000',
+      email: 'admin@example.com',
+      memberNo: 'PLATFORM-0001',
+      roleIds: [4000001],
+    }
+
+    await expect(listPlatformInternalUsers()).resolves.toEqual([internalUser])
+    await expect(updatePlatformInternalUser(internalUser.membershipId, update)).resolves.toEqual(internalUser)
+    await expect(changePlatformInternalUserStatus(internalUser.membershipId, 'DISABLED')).resolves.toEqual(internalUser)
+    await expect(resetPlatformInternalUserPassword(internalUser.membershipId, 'ChangeMe123')).resolves.toEqual(internalUser)
+    await expect(assignPlatformInternalUserRoles(internalUser.membershipId, [4000001])).resolves.toEqual(internalUser)
+
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/iam/internal-users')
+    expect(http.put).toHaveBeenNthCalledWith(1, `/platform/v1/iam/internal-users/${internalUser.membershipId}`, update)
+    expect(http.put).toHaveBeenNthCalledWith(2, `/platform/v1/iam/internal-users/${internalUser.membershipId}/status`, { status: 'DISABLED' })
+    expect(http.put).toHaveBeenNthCalledWith(3, `/platform/v1/iam/internal-users/${internalUser.membershipId}/password`, { newPassword: 'ChangeMe123' })
+    expect(http.put).toHaveBeenNthCalledWith(4, `/platform/v1/iam/internal-users/${internalUser.membershipId}/roles`, { roleIds: [4000001] })
+  })
+
+  it('maintains paginated platform users through the unified user contract', async () => {
+    const userOptionsPayload = {
+      tenants: [{ id: '0', name: '平台', status: 'ACTIVE' }],
+      roles: [{ id: '40001', tenantId: '0', name: '运营管理员', status: 'ACTIVE' }],
+    }
+    const userOptions = {
+      ...userOptionsPayload,
+      roles: [{ ...userOptionsPayload.roles[0], roleCode: 'PLATFORM_OPERATOR' }],
+    }
+    const create = {
+      username: 'zhangwei', displayName: '张伟', phone: '13800138000', email: 'zhangwei@example.com',
+      tenantId: '0', roleIds: ['40001'], overseasWarehouseId: null, password: 'Password1', status: 'ACTIVE' as const,
+    }
+    const update = {
+      displayName: '张伟', phone: '13800138000', email: 'zhangwei@example.com',
+      tenantId: '0', roleIds: ['40001'], overseasWarehouseId: null,
+    }
+    const userPage = { records: [managedUser], page: 2, size: 10, total: 11, pages: 2 }
+    vi.mocked(http.get).mockResolvedValueOnce({
+      code: '200', message: 'success', data: { ...userPage, page: '2', size: '10', total: '11', pages: '2' },
+    })
+      .mockResolvedValueOnce({ code: '200', message: 'success', data: userOptionsPayload })
+      .mockResolvedValueOnce({
+        code: '200', message: 'success',
+        data: [{ ...role, id: '40001', roleCode: 'PLATFORM_OPERATOR' }],
+      })
+    vi.mocked(http.post).mockResolvedValue({ code: '200', message: 'success', data: managedUser })
+    vi.mocked(http.put).mockResolvedValue({ code: '200', message: 'success', data: managedUser })
+
+    await expect(listPlatformManagedUsers({ page: 2, size: 10, keyword: '张伟', status: 'ACTIVE' })).resolves.toEqual(userPage)
+    await expect(getPlatformUserOptions()).resolves.toEqual(userOptions)
+    await expect(createPlatformManagedUser(create)).resolves.toEqual(managedUser)
+    await expect(updatePlatformManagedUser(managedUser.membershipId, update)).resolves.toEqual(managedUser)
+    await expect(changePlatformManagedUserStatus(managedUser.membershipId, 'DISABLED')).resolves.toEqual(managedUser)
+    await expect(resetPlatformManagedUserPassword(managedUser.membershipId, 'ChangeMe123')).resolves.toEqual(managedUser)
+
+    expect(http.get).toHaveBeenNthCalledWith(1, '/platform/v1/iam/users', {
+      params: { page: 2, size: 10, keyword: '张伟', status: 'ACTIVE' },
+    })
+    expect(http.get).toHaveBeenNthCalledWith(2, '/platform/v1/iam/users/options')
+    expect(http.get).toHaveBeenNthCalledWith(3, '/platform/v1/iam/roles')
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/iam/users', create)
+    expect(http.put).toHaveBeenNthCalledWith(1, `/platform/v1/iam/users/${managedUser.membershipId}`, update)
+    expect(http.put).toHaveBeenNthCalledWith(2, `/platform/v1/iam/users/${managedUser.membershipId}/status`, { status: 'DISABLED' })
+    expect(http.put).toHaveBeenNthCalledWith(3, `/platform/v1/iam/users/${managedUser.membershipId}/password`, { newPassword: 'ChangeMe123' })
+  })
+
+  it('loads only active shared receiving overseas warehouses from domestic warehouse master data', async () => {
+    vi.mocked(http.get).mockResolvedValue({
+      code: '200', message: 'success', data: {
+        records: [
+          { id: '90071992547409931', tenantId: '0', warehouseCode: 'LAX-01', warehouseName: '洛杉矶收货仓', warehouseType: 'OVERSEAS', countryCode: 'US', status: 'ACTIVE' },
+          { id: '90071992547409932', tenantId: '0', warehouseCode: 'NYC-01', warehouseName: '纽约收货仓', warehouseType: 'OVERSEAS', countryCode: 'US', status: 'ACTIVE' },
+          { id: '2', tenantId: '100', warehouseCode: 'CUST', warehouseName: '客户仓', warehouseType: 'OVERSEAS', countryCode: 'US', status: 'ACTIVE' },
+          { id: '3', tenantId: '0', warehouseCode: 'PARTNER', warehouseName: '合作仓', warehouseType: 'OVERSEAS_PARTNER', countryCode: 'US', status: 'ACTIVE' },
+          { id: '4', tenantId: '0', warehouseCode: 'ONT8', warehouseName: 'ONT8', warehouseType: 'FBA', countryCode: 'US', status: 'ACTIVE' },
+          { id: '5', tenantId: '0', warehouseCode: 'SEA-INACTIVE', warehouseName: '西雅图停用仓', warehouseType: 'OVERSEAS', countryCode: 'US', status: 'INACTIVE' },
+        ], page: 1, size: 200, total: 6, pages: 1,
+      },
+    })
+
+    await expect(listSharedReceivingOverseasWarehouseOptions()).resolves.toEqual([
+      { id: '90071992547409931', warehouseCode: 'LAX-01', warehouseName: '洛杉矶收货仓', countryCode: 'US' },
+      { id: '90071992547409932', warehouseCode: 'NYC-01', warehouseName: '纽约收货仓', countryCode: 'US' },
+    ])
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/warehouse-admin', {
+      params: {
+        tenantId: '0', page: 1, size: 200, capabilityCode: 'RECEIVING',
+        warehouseType: 'OVERSEAS', status: 'ACTIVE',
+      },
+    })
+  })
+
+  it('loads qualifications for the selected tenant', async () => {
+    const qualification = {
+      id: 12,
+      tenantId: 8,
+      qualificationType: 'BUSINESS_LICENSE',
+      certificateNo: '91440300XXXXXXXXXX',
+      documentUrl: '/api/merchant/v1/files/qualifications/license.png',
+      status: 'PENDING' as const,
+      reviewComment: null,
+    }
+    vi.mocked(http.get).mockResolvedValue({ code: '200', message: 'success', data: [qualification] })
+
+    await expect(listTenantQualifications(8)).resolves.toEqual([qualification])
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/iam/tenants/8/qualifications')
+  })
+
+  it('loads paginated tenants with the documented filters', async () => {
+    const page = { records: [], page: 2, size: 10, total: 11, pages: 2 }
+    vi.mocked(http.get).mockResolvedValue({ code: '200', message: 'success', data: { ...page, page: '2', size: '10', total: '11', pages: '2' } })
+
+    await expect(listPlatformTenants({ page: 2, size: 10, keyword: '柏悦', status: 'ACTIVE' })).resolves.toEqual(page)
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/iam/tenants', {
+      params: { page: 2, size: 10, keyword: '柏悦', status: 'ACTIVE' },
+    })
+  })
+
+  it('creates, updates, and changes customer status with the platform tenant contract', async () => {
+    const tenant = { id: '8', tenantCode: 'TEN8', tenantName: '柏悦物流', status: 'ACTIVE' }
+    const create = {
+      tenantName: '柏悦物流', customerNickname: '柏', legalName: '柏悦物流有限公司', legalRepresentative: '张三',
+      contactName: '张三', contactPhone: '13800138000', contactEmail: 'ops@example.com', servicePackage: '标准版',
+      contactWechat: 'baiyue-ops', salesOwnerName: '李四', paymentTermDays: 30, enterpriseType: '有限责任公司',
+      establishedDate: '2020-01-01', registeredCapital: 1000, registeredCapitalCurrency: 'CNY',
+      registeredAddress: '深圳市宝安区', internalRemark: '重点客户',
+    }
+    const creation = { tenant, administratorUsername: '13800138000', temporaryPassword: 'Password1234' }
+    vi.mocked(http.post).mockResolvedValue({ code: '200', message: 'success', data: creation })
+    vi.mocked(http.put).mockResolvedValue({ code: '200', message: 'success', data: tenant })
+
+    await expect(createPlatformTenant(create)).resolves.toEqual(creation)
+    await expect(updatePlatformTenant('8', create)).resolves.toEqual(tenant)
+    await expect(changePlatformTenantStatus('8', 'DISABLED')).resolves.toEqual(tenant)
+
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/iam/tenants', create)
+    expect(http.put).toHaveBeenNthCalledWith(1, '/platform/v1/iam/tenants/8', create)
+    expect(http.put).toHaveBeenNthCalledWith(2, '/platform/v1/iam/tenants/8/status', { status: 'DISABLED' })
+  })
+
+  it('supports owner password reset, logical archive, and audited impersonation contracts', async () => {
+    const password = { newPassword: 'NewPassword#2026', forceChangePassword: true }
+    const archivedTenant = { id: '190000000000000099', tenantCode: 'TEN99', tenantName: '测试客户', status: 'ARCHIVED' }
+    const impersonation = { code: 'ticket-code', ticketId: 'ticket-id', expiresIn: 60 }
+    vi.mocked(http.put).mockResolvedValue({ code: '200', message: 'success', data: null })
+    vi.mocked(http.post)
+      .mockResolvedValueOnce({ code: '200', message: 'success', data: archivedTenant })
+      .mockResolvedValueOnce({ code: '200', message: 'success', data: impersonation })
+
+    await expect(resetPlatformTenantOwnerPassword('190000000000000099', password)).resolves.toBeNull()
+    await expect(archivePlatformTenant('190000000000000099')).resolves.toEqual(archivedTenant)
+    await expect(createPlatformTenantImpersonation('190000000000000099', { reason: '客户问题排查' })).resolves.toEqual(impersonation)
+
+    expect(http.put).toHaveBeenCalledWith('/platform/v1/iam/tenants/190000000000000099/owner/password', password)
+    expect(http.post).toHaveBeenNthCalledWith(1, '/platform/v1/iam/tenants/190000000000000099/archive', {})
+    expect(http.post).toHaveBeenNthCalledWith(2, '/platform/v1/iam/tenants/190000000000000099/impersonation', { reason: '客户问题排查' })
+  })
+
+  it('loads real order totals for the visible customer tenants', async () => {
+    const counts = [{ tenantId: '8', orderCount: 12 }, { tenantId: '9', orderCount: 0 }]
+    vi.mocked(http.get).mockResolvedValue({ code: '200', message: 'success', data: counts })
+    await expect(listPlatformTenantOrderCounts(['8', '9'])).resolves.toEqual(counts)
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/orders/first-leg/tenant-counts?tenantIds=8,9')
+  })
+
+  it('uploads optional qualification metadata before explicitly submitting the customer review', async () => {
+    const uploadResult = { qualificationId: '91', reviewId: null, tenantStatus: 'PROFILE_REQUIRED', documentUrl: '/file.pdf' }
+    const tenant = { id: '8', tenantCode: 'TEN8', tenantName: '柏悦物流', status: 'PENDING' }
+    vi.mocked(http.post).mockResolvedValueOnce({ code: '200', message: 'success', data: uploadResult })
+      .mockResolvedValueOnce({ code: '200', message: 'success', data: tenant })
+    const file = new File(['%PDF-1.4'], '开户许可证.pdf', { type: 'application/pdf' })
+
+    await expect(uploadPlatformTenantQualification('8', 'BANK_ACCOUNT_LICENSE', file, '2030-12-31', undefined, true)).resolves.toEqual(uploadResult)
+    await expect(submitPlatformTenantReview('8')).resolves.toEqual(tenant)
+
+    const form = vi.mocked(http.post).mock.calls[0]?.[1] as FormData
+    expect(http.post).toHaveBeenNthCalledWith(1, '/platform/v1/files/qualifications/8', expect.any(FormData))
+    expect(form.get('file')).toBe(file)
+    expect(form.get('qualificationType')).toBe('BANK_ACCOUNT_LICENSE')
+    expect(form.get('validTo')).toBe('2030-12-31')
+    expect(form.get('certificateNo')).toBeNull()
+    expect(form.get('replace')).toBe('true')
+    expect(http.post).toHaveBeenNthCalledWith(2, '/platform/v1/iam/tenants/8/submit-review', {})
+  })
+
+  it('uploads the business license, credit code and optional legal-person ID in one package request', async () => {
+    const result = {
+      businessLicenseQualificationId: '91', legalPersonIdQualificationId: '92',
+      tenantStatus: 'PROFILE_REQUIRED', businessLicenseDocumentUrl: '/license.pdf',
+      legalPersonIdDocumentUrl: '/legal-person.png',
+    }
+    vi.mocked(http.post).mockResolvedValue({ code: '200', message: 'success', data: result })
+    const businessLicense = new File(['%PDF-1.4'], '营业执照.pdf', { type: 'application/pdf' })
+    const legalPersonId = new File(['image'], '法人身份证.png', { type: 'image/png' })
+
+    await expect(uploadPlatformTenantRequiredQualificationPackage(
+      '8', businessLicense, legalPersonId, '91440300MA5ABCDE12', true, true,
+    )).resolves.toEqual(result)
+
+    const form = vi.mocked(http.post).mock.calls[0]?.[1] as FormData
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/files/qualifications/8/required-package', form)
+    expect(form.get('businessLicense')).toBe(businessLicense)
+    expect(form.get('legalPersonId')).toBe(legalPersonId)
+    expect(form.get('unifiedSocialCreditCode')).toBe('91440300MA5ABCDE12')
+    expect(form.get('replaceBusinessLicense')).toBe('true')
+    expect(form.get('replaceLegalPersonId')).toBe('true')
+  })
+
+  it('loads the customer dimension initialization status before querying dimension rules', async () => {
+    const status = {
+      tenantId: '2098016473058967554', status: 'PENDING', attemptCount: 3,
+      nextRetryAt: '2026-09-10T20:04:00', lastErrorCode: 'S0503',
+      lastErrorMessage: 'Firstleg 服务暂时不可用', updatedAt: '2026-09-10T19:54:00',
+    }
+    vi.mocked(http.get).mockResolvedValue({ code: '200', message: 'success', data: status })
+
+    await expect(getPlatformTenantDimensionInitializationStatus(status.tenantId)).resolves.toEqual(status)
+    expect(http.get).toHaveBeenCalledWith(
+      '/platform/v1/iam/tenants/2098016473058967554/dimension-initialization',
+    )
+  })
+
+  it('omits the optional legal-person ID parts when only the business license is uploaded', async () => {
+    const result = {
+      businessLicenseQualificationId: '91', legalPersonIdQualificationId: null,
+      tenantStatus: 'PROFILE_REQUIRED', businessLicenseDocumentUrl: '/license.pdf',
+      legalPersonIdDocumentUrl: null,
+    }
+    vi.mocked(http.post).mockResolvedValue({ code: '200', message: 'success', data: result })
+    const businessLicense = new File(['%PDF-1.4'], '营业执照.pdf', { type: 'application/pdf' })
+
+    await expect(uploadPlatformTenantRequiredQualificationPackage(
+      '8', businessLicense, null, '91440300MA5ABCDE12', true, false,
+    )).resolves.toEqual(result)
+
+    const form = vi.mocked(http.post).mock.calls[0]?.[1] as FormData
+    expect(form.get('businessLicense')).toBe(businessLicense)
+    expect(form.get('legalPersonId')).toBeNull()
+    expect(form.get('replaceBusinessLicense')).toBe('true')
+    expect(form.get('replaceLegalPersonId')).toBeNull()
+  })
+
+  it('preserves long review identifiers and returns one-time administrator credentials', async () => {
+    const reviewId = '190000000000000001'
+    const approval = {
+      tenantId: '190000000000000099',
+      administratorCreated: true,
+      administratorUsername: 'merchant_owner',
+      temporaryPassword: 'Temporary#2026',
+    }
+    vi.mocked(http.post).mockResolvedValue({ code: '200', message: 'success', data: approval })
+
+    await expect(approveEnterpriseReview(reviewId, '资料完整')).resolves.toEqual(approval)
+    expect(http.post).toHaveBeenCalledWith(`/platform/v1/iam/reviews/${reviewId}/approve`, { comment: '资料完整' })
+  })
+
+  it('downloads a qualification with the platform file endpoint and a safe filename', async () => {
+    const blob = new Blob(['image'], { type: 'image/png' })
+    vi.mocked(http.get).mockResolvedValue(blob)
+
+    expect(qualificationFileName('/api/merchant/v1/files/qualifications/%E8%90%A5%E4%B8%9A%E6%89%A7%E7%85%A7.png?token=ignored')).toBe('营业执照.png')
+    await expect(downloadTenantQualification(8, '/api/merchant/v1/files/qualifications/%E8%90%A5%E4%B8%9A%E6%89%A7%E7%85%A7.png')).resolves.toBe(blob)
+    expect(http.get).toHaveBeenCalledWith(
+      '/platform/v1/files/qualifications/8/%E8%90%A5%E4%B8%9A%E6%89%A7%E7%85%A7.png',
+      { responseType: 'blob' },
+    )
+    expect(() => qualificationFileName('/api/merchant/v1/files/qualifications/%2Fetc%2Fpasswd')).toThrow('资质文件地址无效')
+  })
+})
diff --git a/src/modules/iam/api/platformIam.ts b/src/modules/iam/api/platformIam.ts
new file mode 100644
index 00000000..e6f4cf31
--- /dev/null
+++ b/src/modules/iam/api/platformIam.ts
@@ -0,0 +1,666 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import type { PlatformPermissionResource } from '@/shared/types/platformPermission'
+
+export type { PlatformPermissionResource } from '@/shared/types/platformPermission'
+
+export interface EnterpriseReview {
+  id: number | string
+  tenantId: number | string
+  status: 'PENDING' | 'APPROVED' | 'REJECTED'
+  tenantName?: string | null
+  tenantCode?: string | null
+  qualificationId?: number | string | null
+  qualificationType?: string | null
+  certificateNo?: string | null
+  documentUrl?: string | null
+  contactName?: string | null
+  contactPhone?: string | null
+  contactEmail?: string | null
+  submittedAt?: string | null
+  createdAt?: string | null
+  reviewComment?: string | null
+  [key: string]: unknown
+}
+
+export type PlatformTenantStatus = 'PROFILE_REQUIRED' | 'PENDING' | 'ACTIVE' | 'REJECTED' | 'DISABLED' | 'ARCHIVED' | string
+
+export interface PlatformTenantResource {
+  id: number | string
+  tenantCode: string
+  tenantName: string
+  customerNickname?: string | null
+  status: PlatformTenantStatus
+  dimensionInitializationStatus?: 'PENDING' | 'SENDING' | 'READY' | 'FAILED' | string
+  legalName: string | null
+  legalRepresentative: string | null
+  unifiedSocialCreditCode: string | null
+  contactName: string | null
+  contactPhone: string | null
+  contactEmail: string | null
+  servicePackage: string | null
+  contactWechat: string | null
+  salesOwnerName: string | null
+  paymentTermDays: number | null
+  enterpriseType: string | null
+  establishedDate: string | null
+  registeredCapital: number | string | null
+  registeredCapitalCurrency: string | null
+  registeredAddress: string | null
+  internalRemark: string | null
+  createdAt: string | null
+  approvedAt: string | null
+}
+
+export interface CreatePlatformTenantRequest {
+  tenantName: string
+  customerNickname?: string
+  legalName: string
+  legalRepresentative?: string
+  contactName: string
+  contactPhone: string
+  contactEmail: string
+  servicePackage: string
+  contactWechat: string
+  salesOwnerName: string
+  paymentTermDays: number
+  enterpriseType: string
+  establishedDate: string | null
+  registeredCapital: number | null
+  registeredCapitalCurrency: string
+  registeredAddress: string
+  internalRemark: string
+}
+
+export type UpdatePlatformTenantRequest = Omit<CreatePlatformTenantRequest, 'customerNickname'> & { customerNickname: string }
+
+export interface PlatformTenantOrderCount {
+  tenantId: number | string
+  orderCount: number
+}
+
+export interface PlatformTenantPage {
+  records: PlatformTenantResource[]
+  page: number
+  size: number
+  total: number
+  pages: number
+}
+
+export interface PlatformTenantQuery {
+  page: number
+  size: number
+  keyword?: string
+  status?: PlatformTenantStatus
+}
+
+export interface PlatformTenantQualification {
+  id: number | string
+  tenantId: number | string
+  qualificationType: 'BUSINESS_LICENSE' | string
+  certificateNo: string | null
+  documentUrl: string
+  status: 'PENDING' | 'APPROVED' | 'REJECTED' | 'SUPERSEDED'
+  reviewComment: string | null
+  validTo?: string | null
+}
+
+export interface PlatformTenantMember {
+  membershipId: number | string
+  userId: number | string
+  authUserId: number | string
+  username?: string | null
+  displayName: string | null
+  phone: string | null
+  email: string | null
+  memberType: string
+  memberNo: string | null
+  status: 'ACTIVE' | 'DISABLED' | string
+  roleIds?: Array<number | string>
+  roleNames?: string[]
+}
+
+export type PlatformQualificationType = 'BUSINESS_LICENSE' | 'LEGAL_PERSON_ID' | 'FREIGHT_FORWARDER_CERTIFICATE' | 'BANK_ACCOUNT_LICENSE'
+
+export interface PlatformQualificationUploadResponse {
+  qualificationId: number | string
+  reviewId: number | string | null
+  tenantStatus: PlatformTenantStatus
+  documentUrl: string
+  replacedDocumentUrl?: string | null
+}
+
+export interface PlatformRequiredQualificationPackageUploadResponse {
+  businessLicenseQualificationId: number | string
+  legalPersonIdQualificationId: number | string | null
+  tenantStatus: PlatformTenantStatus
+  businessLicenseDocumentUrl: string
+  legalPersonIdDocumentUrl: string | null
+}
+
+export interface EnterpriseApprovalResponse {
+  tenantId: number | string
+  administratorCreated: boolean
+  administratorUsername: string | null
+  temporaryPassword: string | null
+}
+
+export interface PlatformTenantCreationResponse {
+  tenant: PlatformTenantResource
+  administratorUsername: string
+  temporaryPassword: string
+}
+
+export interface CustomerDimensionInitializationStatus {
+  tenantId: number | string
+  status: 'PENDING' | 'SENDING' | 'READY' | 'FAILED' | string
+  attemptCount: number
+  nextRetryAt: string | null
+  lastErrorCode: string | null
+  lastErrorMessage: string | null
+  updatedAt: string | null
+}
+
+export interface ResetPlatformTenantOwnerPasswordRequest {
+  newPassword: string
+  forceChangePassword: boolean
+}
+
+export interface CreatePlatformTenantImpersonationRequest {
+  reason: string
+}
+
+export interface PlatformTenantImpersonationResponse {
+  code: string
+  ticketId: string
+  expiresIn: number
+}
+
+export interface PlatformRoleResource {
+  id: number | string
+  tenantId: number | string
+  appCode: 'PLATFORM'
+  roleCode: string
+  roleName: string
+  roleType: 'SYSTEM' | 'CUSTOM' | string
+  status: 'ACTIVE' | 'INACTIVE' | string
+  description: string | null
+  memberCount: number
+  permissionIds?: Array<number | string>
+}
+
+export interface CreatePlatformRoleRequest {
+  roleCode: string
+  roleName: string
+  description: string
+}
+
+export interface UpdatePlatformRoleRequest {
+  roleName: string
+  description: string
+}
+
+export interface CreatePlatformPermissionRequest {
+  type: 'MENU' | 'PAGE' | 'BUTTON' | 'API'
+  code: string
+  name: string
+  parentId: number | string
+  routePath: string | null
+  httpMethod: string | null
+  sortNo: number
+}
+
+export interface UpdatePlatformPermissionRequest {
+  name: string
+  parentId: number | string | null
+  routePath: string | null
+  httpMethod: string | null
+  sortNo: number
+}
+
+export interface PlatformInternalUser {
+  membershipId: number | string
+  userId: number | string
+  authUserId: number | string
+  username: string
+  displayName: string
+  phone: string | null
+  email: string | null
+  memberType: string
+  memberNo: string | null
+  status: 'ACTIVE' | 'DISABLED' | string
+  roleIds: Array<number | string>
+}
+
+export interface CreatePlatformInternalUserRequest {
+  authUserId: number | string
+  userType: string
+  displayName: string
+  phone: string
+  email: string
+  memberNo?: string
+  roleIds?: Array<number | string>
+}
+
+export interface UpdatePlatformInternalUserRequest {
+  displayName: string
+  phone: string
+  email: string
+  memberNo: string
+  roleIds: Array<number | string>
+}
+
+export interface PlatformManagedUser {
+  membershipId: number | string
+  userId: number | string
+  authUserId: number | string
+  username: string
+  displayName: string
+  phone: string | null
+  email: string | null
+  tenantId: number | string
+  tenantName: string
+  memberType: string
+  memberNo: string | null
+  status: 'ACTIVE' | 'DISABLED'
+  roleIds: Array<number | string>
+  roleNames: string[]
+  lastLoginAt: string | null
+  protectedAccount: boolean
+  overseasWarehouseId: number | string | null
+}
+
+export interface PlatformManagedUserPage {
+  records: PlatformManagedUser[]
+  page: number
+  size: number
+  total: number
+  pages: number
+}
+
+export interface PlatformManagedUserQuery {
+  page: number
+  size: number
+  keyword?: string
+  status?: PlatformManagedUser['status']
+}
+
+export interface PlatformUserOptions {
+  tenants: Array<{ id: number | string; name: string; status: string }>
+  roles: Array<{ id: number | string; tenantId: number | string; roleCode: string; name: string; status: string }>
+}
+
+interface PlatformUserOptionsPayload {
+  tenants: PlatformUserOptions['tenants']
+  roles: Array<Omit<PlatformUserOptions['roles'][number], 'roleCode'>>
+}
+
+export interface SharedReceivingOverseasWarehouseOption {
+  id: string
+  warehouseCode: string
+  warehouseName: string
+  countryCode: string
+}
+
+export interface CreatePlatformManagedUserRequest {
+  username: string
+  displayName: string
+  phone: string
+  email: string
+  tenantId: number | string
+  roleIds: Array<number | string>
+  overseasWarehouseId: number | string | null
+  password: string
+  status: 'ACTIVE' | 'DISABLED'
+}
+
+export interface UpdatePlatformManagedUserRequest {
+  displayName: string
+  phone: string
+  email: string
+  tenantId: number | string
+  roleIds: Array<number | string>
+  overseasWarehouseId: number | string | null
+}
+
+async function getData<T>(path: string): Promise<T> {
+  const response = await http.get<ApiEnvelope<T>, ApiEnvelope<T>>(path)
+  return unwrapApiResponse(response)
+}
+
+async function postData<T>(path: string, body: unknown): Promise<T> {
+  const response = await http.post<ApiEnvelope<T>, ApiEnvelope<T>>(path, body)
+  return unwrapApiResponse(response)
+}
+
+async function putData<T>(path: string, body: unknown): Promise<T> {
+  const response = await http.put<ApiEnvelope<T>, ApiEnvelope<T>>(path, body)
+  return unwrapApiResponse(response)
+}
+
+async function deleteData<T>(path: string): Promise<T> {
+  const response = await http.delete<ApiEnvelope<T>, ApiEnvelope<T>>(path)
+  return unwrapApiResponse(response)
+}
+
+export function listPlatformPermissions() {
+  return getData<PlatformPermissionResource[]>('/platform/v1/iam/permissions')
+}
+
+export function listEnterpriseReviews() {
+  return getData<EnterpriseReview[]>('/platform/v1/iam/reviews')
+}
+
+export async function listPlatformTenants(query: PlatformTenantQuery) {
+  const response = await http.get<ApiEnvelope<PlatformTenantPage>, ApiEnvelope<PlatformTenantPage>>(
+    '/platform/v1/iam/tenants',
+    {
+      params: {
+        page: query.page,
+        size: query.size,
+        ...(query.keyword ? { keyword: query.keyword } : {}),
+        ...(query.status ? { status: query.status } : {}),
+      },
+    },
+  )
+  const data = unwrapApiResponse(response)
+  return {
+    ...data,
+    page: Number(data.page),
+    size: Number(data.size),
+    total: Number(data.total),
+    pages: Number(data.pages),
+  }
+}
+
+export function getPlatformTenant(tenantId: number | string) {
+  return getData<PlatformTenantResource>(`/platform/v1/iam/tenants/${tenantId}`)
+}
+
+export function getPlatformTenantDimensionInitializationStatus(tenantId: number | string) {
+  return getData<CustomerDimensionInitializationStatus>(
+    `/platform/v1/iam/tenants/${tenantId}/dimension-initialization`,
+  )
+}
+
+export async function checkPlatformTenantContactPhone(contactPhone: string, excludeTenantId?: number | string) {
+  const response = await http.get<ApiEnvelope<boolean>, ApiEnvelope<boolean>>(
+    '/platform/v1/iam/tenants/contact-phone-availability',
+    { params: { contactPhone, ...(excludeTenantId ? { excludeTenantId } : {}) } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export function createPlatformTenant(payload: CreatePlatformTenantRequest) {
+  return postData<PlatformTenantCreationResponse>('/platform/v1/iam/tenants', payload)
+}
+
+export function updatePlatformTenant(tenantId: number | string, payload: UpdatePlatformTenantRequest) {
+  return putData<PlatformTenantResource>(`/platform/v1/iam/tenants/${tenantId}`, payload)
+}
+
+export function changePlatformTenantStatus(tenantId: number | string, status: 'ACTIVE' | 'DISABLED') {
+  return putData<PlatformTenantResource>(`/platform/v1/iam/tenants/${tenantId}/status`, { status })
+}
+
+export function submitPlatformTenantReview(tenantId: number | string) {
+  return postData<PlatformTenantResource>(`/platform/v1/iam/tenants/${tenantId}/submit-review`, {})
+}
+
+export function resetPlatformTenantOwnerPassword(
+  tenantId: number | string,
+  payload: ResetPlatformTenantOwnerPasswordRequest,
+) {
+  return putData<void>(`/platform/v1/iam/tenants/${tenantId}/owner/password`, payload)
+}
+
+export function archivePlatformTenant(tenantId: number | string) {
+  return postData<PlatformTenantResource>(`/platform/v1/iam/tenants/${tenantId}/archive`, {})
+}
+
+export function createPlatformTenantImpersonation(
+  tenantId: number | string,
+  payload: CreatePlatformTenantImpersonationRequest,
+) {
+  return postData<PlatformTenantImpersonationResponse>(`/platform/v1/iam/tenants/${tenantId}/impersonation`, payload)
+}
+
+export async function uploadPlatformTenantQualification(
+  tenantId: number | string,
+  qualificationType: PlatformQualificationType,
+  file: File,
+  validTo?: string,
+  certificateNo?: string,
+  replace = false,
+) {
+  const form = new FormData()
+  form.append('file', file)
+  form.append('qualificationType', qualificationType)
+  if (validTo) form.append('validTo', validTo)
+  if (certificateNo) form.append('certificateNo', certificateNo)
+  if (replace) form.append('replace', 'true')
+  const response = await http.post<ApiEnvelope<PlatformQualificationUploadResponse>, ApiEnvelope<PlatformQualificationUploadResponse>>(
+    `/platform/v1/files/qualifications/${tenantId}`,
+    form,
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function uploadPlatformTenantRequiredQualificationPackage(
+  tenantId: number | string,
+  businessLicense: File,
+  legalPersonId: File | null,
+  unifiedSocialCreditCode: string,
+  replaceBusinessLicense = false,
+  replaceLegalPersonId = false,
+) {
+  const form = new FormData()
+  form.append('businessLicense', businessLicense)
+  if (legalPersonId) form.append('legalPersonId', legalPersonId)
+  form.append('unifiedSocialCreditCode', unifiedSocialCreditCode)
+  if (replaceBusinessLicense) form.append('replaceBusinessLicense', 'true')
+  if (replaceLegalPersonId) form.append('replaceLegalPersonId', 'true')
+  const response = await http.post<ApiEnvelope<PlatformRequiredQualificationPackageUploadResponse>, ApiEnvelope<PlatformRequiredQualificationPackageUploadResponse>>(
+    `/platform/v1/files/qualifications/${tenantId}/required-package`,
+    form,
+  )
+  return unwrapApiResponse(response)
+}
+
+export function listPlatformTenantOrderCounts(tenantIds: Array<number | string>) {
+  const ids = tenantIds.map((id) => encodeURIComponent(String(id))).join(',')
+  return getData<PlatformTenantOrderCount[]>(`/platform/v1/orders/first-leg/tenant-counts?tenantIds=${ids}`)
+}
+
+export function listTenantQualifications(tenantId: number | string) {
+  return getData<PlatformTenantQualification[]>(`/platform/v1/iam/tenants/${tenantId}/qualifications`)
+}
+
+export function listPlatformTenantMembers(tenantId: number | string) {
+  return getData<PlatformTenantMember[]>(`/platform/v1/iam/tenants/${tenantId}/members`)
+}
+
+export function qualificationFileName(documentUrl: string) {
+  const path = documentUrl.split(/[?#]/, 1)[0]
+  const encodedName = path.split('/').filter(Boolean).at(-1)
+  if (!encodedName) throw new Error('资质文件地址无效')
+  let fileName: string
+  try {
+    fileName = decodeURIComponent(encodedName)
+  } catch {
+    throw new Error('资质文件地址无效')
+  }
+  if (!fileName || fileName === '.' || fileName === '..' || /[\\/]/.test(fileName)) {
+    throw new Error('资质文件地址无效')
+  }
+  return fileName
+}
+
+export function downloadTenantQualification(tenantId: number | string, documentUrl: string) {
+  const fileName = qualificationFileName(documentUrl)
+  return http.get<Blob, Blob>(`/platform/v1/files/qualifications/${tenantId}/${encodeURIComponent(fileName)}`, {
+    responseType: 'blob',
+  })
+}
+
+export function listPlatformRoles() {
+  return getData<PlatformRoleResource[]>('/platform/v1/iam/roles')
+}
+
+export function createPlatformRole(payload: CreatePlatformRoleRequest) {
+  return postData<PlatformRoleResource>('/platform/v1/iam/roles', payload)
+}
+
+export function updatePlatformRole(roleId: number | string, payload: UpdatePlatformRoleRequest) {
+  return putData<PlatformRoleResource>(`/platform/v1/iam/roles/${roleId}`, payload)
+}
+
+export function changePlatformRoleStatus(roleId: number | string, status: 'ACTIVE' | 'DISABLED') {
+  return putData<PlatformRoleResource>(`/platform/v1/iam/roles/${roleId}/status`, { status })
+}
+
+export function deletePlatformRole(roleId: number | string) {
+  return deleteData<void>(`/platform/v1/iam/roles/${roleId}`)
+}
+
+export function replacePlatformRolePermissions(roleId: number | string, permissionIds: Array<number | string>) {
+  return putData<void>('/platform/v1/iam/roles/permissions', { roleId, permissionIds })
+}
+
+export function createPlatformPermission(payload: CreatePlatformPermissionRequest) {
+  return postData<PlatformPermissionResource>('/platform/v1/iam/permissions', payload)
+}
+
+export function updatePlatformPermission(permissionId: number | string, payload: UpdatePlatformPermissionRequest) {
+  return putData<PlatformPermissionResource>(`/platform/v1/iam/permissions/${permissionId}`, payload)
+}
+
+export function changePlatformPermissionStatus(permissionId: number | string, status: 'ACTIVE' | 'DISABLED') {
+  return putData<PlatformPermissionResource>(`/platform/v1/iam/permissions/${permissionId}/status`, { status })
+}
+
+export function deletePlatformPermission(permissionId: number | string) {
+  return deleteData<void>(`/platform/v1/iam/permissions/${permissionId}`)
+}
+
+export function listPlatformInternalUsers() {
+  return getData<PlatformInternalUser[]>('/platform/v1/iam/internal-users')
+}
+
+export function createPlatformInternalUser(payload: CreatePlatformInternalUserRequest) {
+  return postData<PlatformInternalUser>('/platform/v1/iam/internal-users', payload)
+}
+
+export function updatePlatformInternalUser(membershipId: number | string, payload: UpdatePlatformInternalUserRequest) {
+  return putData<PlatformInternalUser>(`/platform/v1/iam/internal-users/${membershipId}`, payload)
+}
+
+export function changePlatformInternalUserStatus(membershipId: number | string, status: 'ACTIVE' | 'DISABLED') {
+  return putData<PlatformInternalUser>(`/platform/v1/iam/internal-users/${membershipId}/status`, { status })
+}
+
+export function resetPlatformInternalUserPassword(membershipId: number | string, newPassword: string) {
+  return putData<void>(`/platform/v1/iam/internal-users/${membershipId}/password`, { newPassword })
+}
+
+export function assignPlatformInternalUserRoles(membershipId: number | string, roleIds: Array<number | string>) {
+  return putData<PlatformInternalUser>(`/platform/v1/iam/internal-users/${membershipId}/roles`, { roleIds })
+}
+
+export async function listPlatformManagedUsers(query: PlatformManagedUserQuery) {
+  const response = await http.get<ApiEnvelope<PlatformManagedUserPage>, ApiEnvelope<PlatformManagedUserPage>>(
+    '/platform/v1/iam/users',
+    {
+      params: {
+        page: query.page,
+        size: query.size,
+        ...(query.keyword ? { keyword: query.keyword } : {}),
+        ...(query.status ? { status: query.status } : {}),
+      },
+    },
+  )
+  const data = unwrapApiResponse(response)
+  return {
+    ...data,
+    page: Number(data.page),
+    size: Number(data.size),
+    total: Number(data.total),
+    pages: Number(data.pages),
+  }
+}
+
+export async function getPlatformUserOptions(): Promise<PlatformUserOptions> {
+  const [optionsResponse, rolesResponse] = await Promise.all([
+    http.get<ApiEnvelope<PlatformUserOptionsPayload>, ApiEnvelope<PlatformUserOptionsPayload>>('/platform/v1/iam/users/options'),
+    http.get<ApiEnvelope<PlatformRoleResource[]>, ApiEnvelope<PlatformRoleResource[]>>('/platform/v1/iam/roles'),
+  ])
+  const options = unwrapApiResponse(optionsResponse)
+  const roleCodes = new Map(unwrapApiResponse(rolesResponse).map((role) => [String(role.id), role.roleCode]))
+  return {
+    tenants: options.tenants,
+    roles: options.roles.map((role) => ({
+      ...role,
+      roleCode: roleCodes.get(String(role.id)) ?? '',
+    })),
+  }
+}
+
+export async function listSharedReceivingOverseasWarehouseOptions() {
+  interface WarehousePage {
+    records: Array<{
+      id: number | string
+      tenantId: number | string
+      warehouseCode: string
+      warehouseName: string
+      warehouseType: string
+      countryCode: string
+      status: string
+    }>
+  }
+  const response = await http.get<ApiEnvelope<WarehousePage>, ApiEnvelope<WarehousePage>>(
+    '/platform/v1/warehouse-admin',
+    {
+      params: {
+        tenantId: '0',
+        page: 1,
+        size: 200,
+        capabilityCode: 'RECEIVING',
+        warehouseType: 'OVERSEAS',
+        status: 'ACTIVE',
+      },
+    },
+  )
+  return unwrapApiResponse(response).records
+    .filter((warehouse) => String(warehouse.tenantId) === '0'
+      && warehouse.warehouseType === 'OVERSEAS'
+      && warehouse.status === 'ACTIVE')
+    .map((warehouse) => ({
+      id: String(warehouse.id),
+      warehouseCode: warehouse.warehouseCode,
+      warehouseName: warehouse.warehouseName,
+      countryCode: warehouse.countryCode,
+    }))
+}
+
+export function createPlatformManagedUser(payload: CreatePlatformManagedUserRequest) {
+  return postData<PlatformManagedUser>('/platform/v1/iam/users', payload)
+}
+
+export function updatePlatformManagedUser(membershipId: number | string, payload: UpdatePlatformManagedUserRequest) {
+  return putData<PlatformManagedUser>(`/platform/v1/iam/users/${membershipId}`, payload)
+}
+
+export function changePlatformManagedUserStatus(membershipId: number | string, status: 'ACTIVE' | 'DISABLED') {
+  return putData<PlatformManagedUser>(`/platform/v1/iam/users/${membershipId}/status`, { status })
+}
+
+export function resetPlatformManagedUserPassword(membershipId: number | string, newPassword: string) {
+  return putData<void>(`/platform/v1/iam/users/${membershipId}/password`, { newPassword })
+}
+
+export function approveEnterpriseReview(reviewId: number | string, comment: string) {
+  return postData<EnterpriseApprovalResponse>(`/platform/v1/iam/reviews/${reviewId}/approve`, { comment })
+}
+
+export function rejectEnterpriseReview(reviewId: number | string, comment: string) {
+  return postData<void>(`/platform/v1/iam/reviews/${reviewId}/reject`, { comment })
+}
diff --git a/src/modules/iam/components/PlatformTenantSelector.test.ts b/src/modules/iam/components/PlatformTenantSelector.test.ts
new file mode 100644
index 00000000..5563d289
--- /dev/null
+++ b/src/modules/iam/components/PlatformTenantSelector.test.ts
@@ -0,0 +1,120 @@
+import ElementPlus from 'element-plus'
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { listPlatformTenants, type PlatformTenantResource } from '../api/platformIam'
+import PlatformTenantSelector from './PlatformTenantSelector.vue'
+
+vi.mock('../api/platformIam', () => ({ listPlatformTenants: vi.fn() }))
+
+const customer = {
+  id: '190000000000000008',
+  tenantCode: 'CUS-008',
+  tenantName: '柏悦物流',
+  status: 'ACTIVE',
+} as PlatformTenantResource
+
+function mountSelector(props: { modelValue?: string; label?: string } = {}) {
+  return mount(PlatformTenantSelector, {
+    props: { modelValue: props.modelValue ?? '', ...(props.label ? { label: props.label } : {}) },
+    global: { plugins: [ElementPlus] },
+  })
+}
+
+describe('PlatformTenantSelector customer labels', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.mocked(listPlatformTenants).mockResolvedValue({ records: [customer], page: 1, size: 200, total: 1, pages: 1 })
+  })
+
+  it('shows business identity and status without exposing the internal id', async () => {
+    const wrapper = mountSelector({ modelValue: String(customer.id) })
+    await flushPromises()
+
+    expect(listPlatformTenants).toHaveBeenCalledWith({ page: 1, size: 200, status: 'ACTIVE' })
+    expect(wrapper.text()).toContain('目标客户')
+    expect(document.body.textContent).toContain('柏悦物流 · 启用')
+    expect(document.body.textContent).not.toContain('CUS-008')
+    expect(document.body.textContent).not.toContain(String(customer.id))
+  })
+
+  it('keeps the internal id only as the emitted contract value', async () => {
+    const wrapper = mountSelector()
+    await flushPromises()
+
+    expect(wrapper.emitted('update:modelValue')).toEqual([[String(customer.id)]])
+    expect(wrapper.text()).not.toContain(String(customer.id))
+  })
+
+  it('selects the first active customer without preferring a fixed customer id', async () => {
+    vi.mocked(listPlatformTenants).mockResolvedValue({
+      records: [
+        { ...customer, id: '9', tenantName: '停用客户', status: 'DISABLED' },
+        { ...customer, id: '20002', tenantName: '首个客户' },
+        { ...customer, id: '10001', tenantName: '后续客户' },
+      ],
+      page: 1, size: 200, total: 3, pages: 1,
+    })
+    const wrapper = mountSelector()
+    await flushPromises()
+
+    expect(wrapper.emitted('update:modelValue')).toEqual([['20002']])
+  })
+
+  it('preserves an explicitly selected customer', async () => {
+    const wrapper = mountSelector({ modelValue: String(customer.id) })
+    await flushPromises()
+
+    expect(wrapper.emitted('update:modelValue')).toBeUndefined()
+  })
+
+  it('keeps non-active customers out of the selectable options', async () => {
+    vi.mocked(listPlatformTenants).mockResolvedValue({
+      records: [customer, { ...customer, id: '9', tenantName: '停用客户', status: 'DISABLED' }],
+      page: 1, size: 200, total: 2, pages: 1,
+    })
+    mountSelector({ modelValue: String(customer.id) })
+    await flushPromises()
+
+    expect(document.body.textContent).toContain('柏悦物流 · 启用')
+    expect(document.body.textContent).not.toContain('停用客户')
+  })
+
+  it('safely degrades labels when customer name or code is missing', async () => {
+    vi.mocked(listPlatformTenants).mockResolvedValue({
+      records: [
+        { ...customer, id: '1', tenantName: '', tenantCode: 'CUS-001', status: 'ACTIVE' },
+        { ...customer, id: '2', tenantName: '远航供应链', tenantCode: '', status: 'ACTIVE' },
+        { ...customer, id: '3', tenantName: '', tenantCode: '', status: 'ACTIVE' },
+      ],
+      page: 1, size: 200, total: 3, pages: 1,
+    })
+    mountSelector({ modelValue: '1' })
+    await flushPromises()
+
+    expect(document.body.textContent).toContain('未命名客户 · 启用')
+    expect(document.body.textContent).toContain('远航供应链 · 启用')
+    expect(document.body.textContent).not.toContain('CUS-001')
+    expect(document.body.textContent).not.toMatch(/[（(][123] ·/)
+  })
+
+  it('uses a custom business label for both visible and accessible names', async () => {
+    const wrapper = mountSelector({ modelValue: String(customer.id), label: '客户企业' })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('客户企业')
+    expect(wrapper.get('[aria-label="客户企业"]').attributes('aria-label')).toBe('客户企业')
+  })
+
+  it('shows an actionable customer-list error and retries', async () => {
+    vi.mocked(listPlatformTenants)
+      .mockRejectedValueOnce('unavailable')
+      .mockResolvedValueOnce({ records: [customer], page: 1, size: 200, total: 1, pages: 1 })
+    const wrapper = mountSelector()
+    await flushPromises()
+
+    expect(wrapper.get('[role="alert"]').text()).toContain('客户列表加载失败，请重试')
+    await wrapper.get('[role="alert"] button').trigger('click')
+    await flushPromises()
+    expect(listPlatformTenants).toHaveBeenCalledTimes(2)
+  })
+})
diff --git a/src/modules/iam/components/PlatformTenantSelector.vue b/src/modules/iam/components/PlatformTenantSelector.vue
new file mode 100644
index 00000000..9ca6d96f
--- /dev/null
+++ b/src/modules/iam/components/PlatformTenantSelector.vue
@@ -0,0 +1,90 @@
+<script setup lang="ts">
+import { computed, onMounted, ref } from 'vue'
+import { RefreshCw } from '@lucide/vue'
+import { listPlatformTenants, type PlatformTenantResource } from '../api/platformIam'
+
+const props = withDefaults(defineProps<{
+  modelValue: string
+  disabled?: boolean
+  label?: string
+}>(), {
+  disabled: false,
+  label: '目标客户',
+})
+
+const emit = defineEmits<{
+  'update:modelValue': [value: string]
+}>()
+
+const tenants = ref<PlatformTenantResource[]>([])
+const loading = ref(false)
+const error = ref('')
+
+const selectedValue = computed({
+  get: () => props.modelValue,
+  set: (value: string) => emit('update:modelValue', value),
+})
+
+const statusLabels: Record<string, string> = {
+  PROFILE_REQUIRED: '待完善',
+  PENDING: '待审核',
+  ACTIVE: '启用',
+  REJECTED: '已驳回',
+  DISABLED: '已停用',
+  INACTIVE: '已停用',
+  ARCHIVED: '已归档',
+}
+
+function tenantLabel(tenant: PlatformTenantResource) {
+  const status = statusLabels[tenant.status] || tenant.status
+  const name = tenant.tenantName?.trim()
+  return status ? `${name || '未命名客户'} · ${status}` : name || '未命名客户'
+}
+
+async function loadTenants() {
+  loading.value = true
+  error.value = ''
+  try {
+    const result = await listPlatformTenants({ page: 1, size: 200, status: 'ACTIVE' })
+    tenants.value = result.records.filter((tenant) => tenant.status === 'ACTIVE')
+    if (!props.modelValue && tenants.value.length) {
+      emit('update:modelValue', String(tenants.value[0].id))
+    }
+  } catch (reason) {
+    error.value = reason instanceof Error ? reason.message : '客户列表加载失败，请重试'
+  } finally {
+    loading.value = false
+  }
+}
+
+onMounted(() => void loadTenants())
+</script>
+
+<template>
+  <div class="platform-tenant-selector">
+    <div class="platform-tenant-selector-label"><span>{{ label }}</span><span v-if="loading">加载中…</span></div>
+    <el-select
+      v-model="selectedValue"
+      class="platform-tenant-selector-input"
+      filterable
+      :disabled="disabled || loading || tenants.length === 0"
+      :placeholder="loading ? '正在加载客户' : '请选择目标客户'"
+      :aria-label="label"
+    >
+      <el-option v-for="tenant in tenants" :key="String(tenant.id)" :label="tenantLabel(tenant)" :value="String(tenant.id)" />
+    </el-select>
+    <div v-if="error" class="platform-tenant-selector-error" role="alert">
+      <span>{{ error }}</span>
+      <el-button link type="primary" :disabled="loading" @click="loadTenants"><RefreshCw :size="14" />重新加载</el-button>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.platform-tenant-selector { display: grid; min-width: min(100%, 360px); gap: 6px; }
+.platform-tenant-selector-label { display: flex; align-items: center; justify-content: space-between; gap: 12px; color: var(--cc-muted); font-size: 12px; }
+.platform-tenant-selector-label span:last-child { color: var(--cc-primary); font-size: 11px; }
+.platform-tenant-selector-input { width: 100%; }
+.platform-tenant-selector-error { display: flex; align-items: center; justify-content: space-between; gap: 8px; color: var(--el-color-danger); font-size: 12px; line-height: 1.5; }
+.platform-tenant-selector-error :deep(.el-button) { flex: 0 0 auto; }
+</style>
diff --git a/src/modules/iam/iamDensity.css b/src/modules/iam/iamDensity.css
new file mode 100644
index 00000000..66d75bd8
--- /dev/null
+++ b/src/modules/iam/iamDensity.css
@@ -0,0 +1,8 @@
+/* IAM-only layout; the shared stylesheet owns forms, dialogs and row buttons. */
+.iam-density .permission-tree { margin-top: 0; padding: 0; border-top: 0; }
+.iam-density .permission-tree .el-tree-node__content { height: auto; min-height: var(--admin-row-height); }
+.iam-density .permission-node { align-items: flex-start; gap: var(--admin-space-3); padding-right: var(--admin-space-5); }
+.iam-density .permission-node span { white-space: normal; overflow-wrap: anywhere; }
+.iam-density :is(.permission-node code, .code-value, .endpoint-cell code) { font-size: var(--admin-font-caption); }
+.iam-density .form-callout { gap: var(--admin-space-4); margin-top: var(--admin-space-5); padding: var(--admin-space-5); border-radius: var(--admin-radius); }
+.iam-density .form-callout strong, .iam-density .form-callout p { font-size: var(--admin-font-caption); }
diff --git a/src/modules/iam/index.ts b/src/modules/iam/index.ts
new file mode 100644
index 00000000..40e9d230
--- /dev/null
+++ b/src/modules/iam/index.ts
@@ -0,0 +1,2 @@
+export * from './api/platformIam'
+export { default as PlatformTenantSelector } from './components/PlatformTenantSelector.vue'
diff --git a/src/modules/iam/pages/InternalUsersView.test.ts b/src/modules/iam/pages/InternalUsersView.test.ts
new file mode 100644
index 00000000..c61da8da
--- /dev/null
+++ b/src/modules/iam/pages/InternalUsersView.test.ts
@@ -0,0 +1,315 @@
+import ElementPlus from 'element-plus'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { createPinia, setActivePinia } from 'pinia'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  createPlatformManagedUser,
+  getPlatformUserOptions,
+  listSharedReceivingOverseasWarehouseOptions,
+  listPlatformManagedUsers,
+  updatePlatformManagedUser,
+  type PlatformManagedUser,
+} from '@/modules/iam/api/platformIam'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+import InternalUsersView from './InternalUsersView.vue'
+
+const internalUsersSource = readFileSync(resolve(process.cwd(), 'src/modules/iam/pages/InternalUsersView.vue'), 'utf8')
+
+vi.mock('@/modules/iam/api/platformIam', () => ({
+  listPlatformManagedUsers: vi.fn(),
+  getPlatformUserOptions: vi.fn(),
+  listSharedReceivingOverseasWarehouseOptions: vi.fn(),
+  createPlatformManagedUser: vi.fn(),
+  updatePlatformManagedUser: vi.fn(),
+  changePlatformManagedUserStatus: vi.fn(),
+  resetPlatformManagedUserPassword: vi.fn(),
+}))
+
+class ResizeObserverStub implements ResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+
+function createMemoryStorage(): Storage {
+  const values = new Map<string, string>()
+  return {
+    get length() { return values.size },
+    clear: () => values.clear(),
+    getItem: (key) => values.get(key) ?? null,
+    key: (index) => [...values.keys()][index] ?? null,
+    removeItem: (key) => values.delete(key),
+    setItem: (key, value) => values.set(key, value),
+  }
+}
+
+const user: PlatformManagedUser = {
+  membershipId: '30', userId: '20', authUserId: '10', username: 'zhangwei', displayName: '张伟',
+  phone: '13800138000', email: 'zhangwei@example.com', tenantId: '0', tenantName: '平台',
+  memberType: 'INTERNAL', memberNo: 'PLATFORM-30', status: 'ACTIVE', roleIds: ['40'],
+  roleNames: ['运营管理员'], lastLoginAt: '2026-06-01T10:30:00',
+  protectedAccount: false,
+  overseasWarehouseId: null,
+}
+
+async function mountView() {
+  vi.stubGlobal('localStorage', createMemoryStorage())
+  vi.stubGlobal('sessionStorage', createMemoryStorage())
+  const pinia = createPinia()
+  setActivePinia(pinia)
+  const auth = useAuthStore()
+  auth.token = 'token'
+  auth.permissions = [
+    'platform:user:list', 'platform:user:create', 'platform:user:edit',
+    'platform:user:status', 'platform:user:reset-password', 'platform:user:grant-role',
+  ]
+  useAccessPreviewStore().initializeAfterLogin()
+  const wrapper = mount(InternalUsersView, {
+    attachTo: document.body,
+    global: { plugins: [pinia, ElementPlus] },
+  })
+  await flushPromises()
+  return wrapper
+}
+
+enableAutoUnmount(afterEach)
+afterAll(() => vi.unstubAllGlobals())
+
+describe('InternalUsersView platform internal user management', () => {
+  it('renders row business actions as shared outlined text buttons', () => {
+    expect(internalUsersSource).toContain('size="small" data-tone="neutral" @click="openEdit')
+    expect(internalUsersSource).toContain('size="small" :data-tone="(row as PlatformManagedUser).status')
+    expect(internalUsersSource).toMatch(/>\s*编辑\s*<\/el-button>/)
+    expect(internalUsersSource).toContain(':data-tone=')
+    expect(internalUsersSource).not.toContain('v-if="canChangeStatus" link')
+  })
+
+  it('uses the prototype-sized centered editor with a scrollable body and mobile single column', () => {
+    expect(internalUsersSource).toContain('width="min(650px, calc(100vw - 28px))"')
+    expect(internalUsersSource).toContain(':global(.internal-user-editor-dialog .el-dialog__body) { min-height: 0; overflow-y: auto; }')
+    expect(internalUsersSource).toContain(':global(.internal-user-editor-dialog .el-dialog__footer) { flex: 0 0 auto; }')
+    expect(internalUsersSource).toContain('@media (max-width: 720px)')
+    expect(internalUsersSource).toContain('.form-grid.two-cols { grid-template-columns: 1fr; }')
+  })
+  beforeEach(() => {
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+    document.body.innerHTML = ''
+    vi.mocked(listPlatformManagedUsers).mockReset().mockResolvedValue({
+      records: [user], page: 1, size: 10, total: 21, pages: 3,
+    })
+    vi.mocked(getPlatformUserOptions).mockReset().mockResolvedValue({
+      tenants: [
+        { id: '0', name: '平台', status: 'ACTIVE' },
+        { id: '10001', name: '华远贸易', status: 'ACTIVE' },
+      ],
+      roles: [
+        { id: '40', tenantId: '0', roleCode: 'PLATFORM_OPERATOR', name: '运营管理员', status: 'ACTIVE' },
+        { id: '41', tenantId: '10001', roleCode: 'CUSTOMER_ADMIN', name: '客户管理员', status: 'ACTIVE' },
+      ],
+    })
+    vi.mocked(listSharedReceivingOverseasWarehouseOptions).mockReset().mockResolvedValue([
+      { id: '90071992547409931', warehouseCode: 'LAX-01', warehouseName: '洛杉矶收货仓', countryCode: 'US' },
+    ])
+    vi.mocked(createPlatformManagedUser).mockReset().mockResolvedValue(user)
+    vi.mocked(updatePlatformManagedUser).mockReset().mockResolvedValue(user)
+  })
+
+  it('loads a server page and only renders internal-user fields', async () => {
+    const wrapper = await mountView()
+
+    expect(listPlatformManagedUsers).toHaveBeenCalledOnce()
+    expect(listPlatformManagedUsers).toHaveBeenCalledWith({ page: 1, size: 10 })
+    expect(getPlatformUserOptions).toHaveBeenCalledOnce()
+    expect(wrapper.text()).toContain('zhangwei')
+    expect(wrapper.text()).toContain('张伟')
+    expect(wrapper.text()).toContain('运营管理员')
+    expect(wrapper.text()).toContain('2026-06-01 10:30')
+    expect(wrapper.find('[aria-label="用户筛选"]').exists()).toBe(true)
+    expect(wrapper.find('[aria-label="内部用户列表"]').exists()).toBe(true)
+    expect(wrapper.text()).toContain('共 21 条')
+    expect(wrapper.text()).toContain('查询')
+    expect(wrapper.text()).toContain('重置')
+    expect(wrapper.text()).not.toContain('认证用户 ID')
+    expect(wrapper.text()).not.toContain('成员编号')
+    expect(wrapper.text()).not.toContain('所属租户')
+    expect(wrapper.text()).not.toContain('华远贸易')
+  })
+
+  it('opens an internal-user form without a tenant selector', async () => {
+    const wrapper = await mountView()
+    const createButton = wrapper.findAll('button').find((button) => button.text().trim() === '新增用户')
+    await createButton?.trigger('click')
+    await flushPromises()
+
+    expect(document.querySelector('input[placeholder="登录用户名"]')).not.toBeNull()
+    expect(document.querySelector('input[placeholder="真实姓名"]')).not.toBeNull()
+    expect(document.querySelector('input[placeholder="手机号码"]')).not.toBeNull()
+    expect(document.querySelector('input[placeholder="邮箱地址"]')).not.toBeNull()
+    expect(document.body.textContent).not.toContain('所属租户')
+    expect(document.body.textContent).toContain('初始密码')
+    expect(document.body.textContent).toContain('确认添加')
+  })
+
+  it('requires a shared receiving warehouse for OVERSEAS_WAREHOUSE_PDA_OPERATOR', async () => {
+    vi.mocked(getPlatformUserOptions).mockResolvedValueOnce({
+      tenants: [{ id: '0', name: '平台', status: 'ACTIVE' }],
+      roles: [
+        { id: '40', tenantId: '0', roleCode: 'PLATFORM_OPERATOR', name: '运营管理员', status: 'ACTIVE' },
+        { id: '4000005', tenantId: '0', roleCode: 'OVERSEAS_WAREHOUSE_PDA_OPERATOR', name: '海外仓 PDA 作业员', status: 'ACTIVE' },
+      ],
+    })
+    const wrapper = await mountView()
+    await wrapper.findAll('button').find((button) => button.text().trim() === '新增用户')?.trigger('click')
+    await flushPromises()
+
+    expect(document.body.textContent).not.toContain('实际海外收货仓')
+    const roleSelect = wrapper.findAllComponents({ name: 'ElSelect' })
+      .find((component) => component.props('placeholder') === '选择角色')
+    expect(roleSelect).toBeDefined()
+    roleSelect?.vm.$emit('update:modelValue', ['4000005'])
+    await flushPromises()
+
+    expect(listSharedReceivingOverseasWarehouseOptions).toHaveBeenCalledOnce()
+    expect(document.body.textContent).toContain('实际海外收货仓')
+    const warehouseSelect = wrapper.findAllComponents({ name: 'ElSelect' })
+      .find((component) => component.props('placeholder') === '请选择平台共享海外收货仓')
+    expect(warehouseSelect).toBeDefined()
+  })
+
+  it('uses the stable role code instead of localized role names to activate the warehouse binding', () => {
+    expect(internalUsersSource).toContain("role.roleCode === 'OVERSEAS_WAREHOUSE_PDA_OPERATOR'")
+    expect(internalUsersSource).toContain('overseasWarehouseId: hasOverseasPdaRole.value ? form.overseasWarehouseId : null')
+    expect(internalUsersSource).not.toContain("role.name === '海外仓 PDA 作业员'")
+  })
+
+  it('preserves the picker warehouse binding when editing a OVERSEAS_WAREHOUSE_PDA_OPERATOR user', async () => {
+    const pickerUser: PlatformManagedUser = {
+      ...user,
+      roleIds: ['4000005'],
+      roleNames: ['海外仓 PDA 作业员'],
+      overseasWarehouseId: '90071992547409931',
+    }
+    vi.mocked(listPlatformManagedUsers).mockResolvedValueOnce({
+      records: [pickerUser], page: 1, size: 10, total: 1, pages: 1,
+    })
+    vi.mocked(getPlatformUserOptions).mockResolvedValueOnce({
+      tenants: [{ id: '0', name: '平台', status: 'ACTIVE' }],
+      roles: [{ id: '4000005', tenantId: '0', roleCode: 'OVERSEAS_WAREHOUSE_PDA_OPERATOR', name: '海外仓 PDA 作业员', status: 'ACTIVE' }],
+    })
+    vi.mocked(updatePlatformManagedUser).mockResolvedValueOnce(pickerUser)
+
+    const wrapper = await mountView()
+    const setupState = (wrapper.vm.$ as unknown as {
+      setupState: { openEdit: (row: PlatformManagedUser) => void }
+    }).setupState
+    setupState.openEdit(pickerUser)
+    await flushPromises()
+    await wrapper.findAll('button').find((button) => button.text().trim() === '保存修改')?.trigger('click')
+    await flushPromises()
+
+    expect(updatePlatformManagedUser).toHaveBeenCalledWith('30', {
+      displayName: '张伟',
+      phone: '13800138000',
+      email: 'zhangwei@example.com',
+      tenantId: '0',
+      roleIds: ['4000005'],
+      overseasWarehouseId: '90071992547409931',
+    })
+  })
+
+  it('clears a warehouse binding after switching away from OVERSEAS_WAREHOUSE_PDA_OPERATOR', async () => {
+    vi.mocked(getPlatformUserOptions).mockResolvedValueOnce({
+      tenants: [{ id: '0', name: '平台', status: 'ACTIVE' }],
+      roles: [
+        { id: '40', tenantId: '0', roleCode: 'PLATFORM_OPERATOR', name: '运营管理员', status: 'ACTIVE' },
+        { id: '4000005', tenantId: '0', roleCode: 'OVERSEAS_WAREHOUSE_PDA_OPERATOR', name: '海外仓 PDA 作业员', status: 'ACTIVE' },
+      ],
+    })
+    const wrapper = await mountView()
+    const setupState = (wrapper.vm.$ as unknown as {
+      setupState: {
+        openCreate: () => void
+        form: { roleIds: string[]; overseasWarehouseId: string }
+      }
+    }).setupState
+    setupState.openCreate()
+    setupState.form.roleIds = ['4000005']
+    await flushPromises()
+    setupState.form.overseasWarehouseId = '90071992547409931'
+
+    setupState.form.roleIds = ['40']
+    await flushPromises()
+
+    expect(setupState.form.overseasWarehouseId).toBe('')
+    expect(document.body.textContent).not.toContain('实际海外收货仓')
+  })
+
+  it('submits the selected picker warehouse as an unchanged long-id string', async () => {
+    vi.mocked(getPlatformUserOptions).mockResolvedValueOnce({
+      tenants: [{ id: '0', name: '平台', status: 'ACTIVE' }],
+      roles: [{ id: '4000005', tenantId: '0', roleCode: 'OVERSEAS_WAREHOUSE_PDA_OPERATOR', name: '海外仓 PDA 作业员', status: 'ACTIVE' }],
+    })
+    const wrapper = await mountView()
+    const setupState = (wrapper.vm.$ as unknown as {
+      setupState: {
+        openCreate: () => void
+        saveUser: () => Promise<void>
+        form: Record<string, unknown>
+      }
+    }).setupState
+    setupState.openCreate()
+    Object.assign(setupState.form, {
+      username: 'overseas_picker_dev',
+      displayName: '海外仓操作员',
+      phone: '17512095155',
+      email: 'overseas_picker_dev@qq.com',
+      roleIds: ['4000005'],
+      overseasWarehouseId: '90071992547409931',
+      password: 'ChangeMe123!',
+      confirmPassword: 'ChangeMe123!',
+      status: 'ACTIVE',
+    })
+    await flushPromises()
+    await setupState.saveUser()
+
+    expect(createPlatformManagedUser).toHaveBeenCalledWith({
+      username: 'overseas_picker_dev',
+      displayName: '海外仓操作员',
+      phone: '17512095155',
+      email: 'overseas_picker_dev@qq.com',
+      tenantId: '0',
+      roleIds: ['4000005'],
+      overseasWarehouseId: '90071992547409931',
+      password: 'ChangeMe123!',
+      status: 'ACTIVE',
+    })
+  })
+
+  it('requests server-side pages and filters instead of slicing locally', async () => {
+    const wrapper = await mountView()
+    await wrapper.find('button[aria-label="第 2 页"]').trigger('click')
+    await flushPromises()
+
+    expect(listPlatformManagedUsers).toHaveBeenLastCalledWith({ page: 2, size: 10 })
+
+    await wrapper.find('input[aria-label="用户关键词"]').setValue('  张伟  ')
+    const searchButton = wrapper.findAll('button').find((button) => button.text().trim() === '查询')
+    await searchButton?.trigger('click')
+    await flushPromises()
+
+    expect(listPlatformManagedUsers).toHaveBeenLastCalledWith({ page: 1, size: 10, keyword: '张伟' })
+  })
+
+  it('shows a recoverable API error without fake users', async () => {
+    vi.mocked(listPlatformManagedUsers).mockRejectedValueOnce(new Error('Gateway unavailable'))
+    const wrapper = await mountView()
+
+    expect(wrapper.text()).toContain('内部用户列表加载失败，请稍后重试')
+    expect(wrapper.text()).not.toContain('Gateway unavailable')
+    expect(wrapper.text()).toContain('重新加载')
+    expect(wrapper.text()).not.toContain('zhangwei')
+  })
+})
diff --git a/src/modules/iam/pages/InternalUsersView.vue b/src/modules/iam/pages/InternalUsersView.vue
new file mode 100644
index 00000000..dbb66ecd
--- /dev/null
+++ b/src/modules/iam/pages/InternalUsersView.vue
@@ -0,0 +1,471 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import '../iamDensity.css'
+import { computed, nextTick, onMounted, reactive, ref, watch } from 'vue'
+import { ElMessage, ElMessageBox, type FormInstance, type FormRules } from 'element-plus'
+import { Plus } from '@lucide/vue'
+import {
+  changePlatformManagedUserStatus,
+  createPlatformManagedUser,
+  getPlatformUserOptions,
+  listSharedReceivingOverseasWarehouseOptions,
+  listPlatformManagedUsers,
+  resetPlatformManagedUserPassword,
+  updatePlatformManagedUser,
+  type PlatformManagedUser,
+  type PlatformUserOptions,
+  type SharedReceivingOverseasWarehouseOption,
+} from '@/modules/iam/api/platformIam'
+import { getApiErrorDetails, getApiErrorMessage, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import FormSection from '@/shared/components/FormSection.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { useUnsavedWorkRegistration } from '@/core/unsaved-work/useUnsavedWorkRegistration'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+
+const access = useAccessPreviewStore()
+const auth = useAuthStore()
+const users = ref<PlatformManagedUser[]>([])
+const options = ref<PlatformUserOptions>({ tenants: [], roles: [] })
+const overseasWarehouses = ref<SharedReceivingOverseasWarehouseOption[]>([])
+const overseasWarehousesLoading = ref(false)
+const overseasWarehousesError = ref<ApiErrorDetails | null>(null)
+const loading = ref(false)
+const saving = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const editorOpen = ref(false)
+const formRef = ref<FormInstance>()
+const editingUser = ref<PlatformManagedUser | null>(null)
+const rowActionId = ref('')
+let loadRequestId = 0
+let warehouseRequestId = 0
+const page = ref(1)
+const pageSize = ref(10)
+const total = ref(0)
+type UserFilters = QueryModel & { keyword: string; status: string }
+const filters = ref<UserFilters>({ keyword: '', status: '' })
+const appliedFilters = ref<UserFilters>({ ...filters.value })
+const queryFields = computed<QueryField[]>(() => [
+  {
+    key: 'keyword',
+    type: 'input',
+    label: '用户关键词',
+    placeholder: '姓名、手机号、邮箱或员工编号',
+    props: { maxlength: 128, 'aria-label': '用户关键词' },
+  },
+  {
+    key: 'status',
+    type: 'select',
+    label: '状态',
+    placeholder: '全部状态',
+    props: { 'aria-label': '用户状态' },
+    options: [
+      { label: '正常', value: 'ACTIVE' },
+      { label: '禁用', value: 'DISABLED' },
+    ],
+  },
+])
+
+const emptyForm = () => ({
+  username: '',
+  displayName: '',
+  phone: '',
+  email: '',
+  tenantId: '0',
+  roleIds: [] as string[],
+  overseasWarehouseId: '',
+  password: '',
+  confirmPassword: '',
+  status: 'ACTIVE' as 'ACTIVE' | 'DISABLED',
+  resetPassword: false,
+})
+const form = reactive(emptyForm())
+
+const canCreate = computed(() => access.can('platform:user:create') && access.can('platform:user:grant-role'))
+const canEdit = computed(() => access.can('platform:user:edit'))
+const canGrantRoles = computed(() => access.can('platform:user:grant-role'))
+const canChangeStatus = computed(() => access.can('platform:user:status'))
+const canResetPassword = computed(() => access.can('platform:user:reset-password'))
+const editorLabel = computed(() => editingUser.value ? `编辑用户 - ${editingUser.value.displayName}` : '新增用户')
+
+useUnsavedWorkRegistration({
+  key: 'platform-user-editor',
+  label: editorLabel,
+  isOpen: editorOpen,
+  model: form,
+  requiredPermission: computed(() => editingUser.value ? 'platform:user:edit' : 'platform:user:create'),
+})
+
+const availableRoles = computed(() => options.value.roles.filter((role) =>
+  String(role.tenantId) === '0'
+  && (role.status === 'ACTIVE' || form.roleIds.includes(String(role.id))),
+))
+const overseasPdaRoleIds = computed(() => new Set(
+  availableRoles.value.filter((role) => role.roleCode === 'OVERSEAS_WAREHOUSE_PDA_OPERATOR').map((role) => String(role.id)),
+))
+const hasOverseasPdaRole = computed(() => form.roleIds.some((roleId) => overseasPdaRoleIds.value.has(roleId)))
+
+const formRules = computed<FormRules>(() => ({
+  username: editingUser.value ? [] : [
+    { required: true, whitespace: true, message: '请输入用户名', trigger: 'blur' },
+    { pattern: /^[A-Za-z0-9_.@-]{4,64}$/, message: '用户名为 4-64 位字母、数字或 _ . @ -', trigger: 'blur' },
+  ],
+  displayName: editingUser.value && !canEdit.value ? [] : [{ required: true, whitespace: true, message: '请输入姓名', trigger: 'blur' }],
+  phone: editingUser.value && !canEdit.value ? [] : [
+    { required: true, message: '请输入手机号', trigger: 'blur' },
+    { pattern: /^1\d{10}$/, message: '请输入正确的 11 位手机号', trigger: 'blur' },
+  ],
+  email: editingUser.value && !canEdit.value ? [] : [{ type: 'email', message: '请输入有效的邮箱地址', trigger: 'blur' }],
+  roleIds: editingUser.value && !canEdit.value ? [] : [{ type: 'array', required: true, min: 1, message: '请选择角色', trigger: 'change' }],
+  overseasWarehouseId: !hasOverseasPdaRole.value || (editingUser.value && !canEdit.value) ? [] : [
+    { required: true, message: '请选择实际海外收货仓', trigger: 'change' },
+  ],
+  password: editingUser.value && !form.resetPassword ? [] : [
+    { required: true, message: '请输入密码', trigger: 'blur' },
+    { pattern: /^(?=.*[A-Za-z])(?=.*\d).{8,64}$/, message: '密码为 8-64 位，且必须包含字母和数字', trigger: 'blur' },
+  ],
+  confirmPassword: editingUser.value && !form.resetPassword ? [] : [
+    { required: true, message: '请再次输入密码', trigger: 'blur' },
+    { validator: (_rule, value, callback) => value === form.password ? callback() : callback(new Error('两次输入的密码不一致')), trigger: 'blur' },
+  ],
+}))
+
+const userColumns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 170, fixed: 'left', slotName: 'actions' },
+  { key: 'username', prop: 'username', label: '用户名', minWidth: 145 },
+  { key: 'displayName', prop: 'displayName', label: '姓名', minWidth: 130 },
+  { key: 'roles', label: '角色', minWidth: 180, slotName: 'roles' },
+  { key: 'status', label: '状态', width: 100, slotName: 'status' },
+  { key: 'lastLoginAt', label: '最后登录', minWidth: 170, slotName: 'lastLoginAt' },
+]
+
+function userQuery() {
+  return {
+    page: page.value,
+    size: pageSize.value,
+    ...(appliedFilters.value.keyword.trim() ? { keyword: appliedFilters.value.keyword.trim() } : {}),
+    ...(appliedFilters.value.status ? { status: appliedFilters.value.status as PlatformManagedUser['status'] } : {}),
+  }
+}
+
+async function loadUsers() {
+  const requestId = ++loadRequestId
+  loading.value = true
+  loadError.value = null
+  try {
+    const result = await listPlatformManagedUsers(userQuery())
+    if (requestId !== loadRequestId) return
+    users.value = result.records
+    total.value = result.total
+  } catch (error) {
+    if (requestId !== loadRequestId) return
+    users.value = []
+    total.value = 0
+    loadError.value = getApiErrorDetails(error, '用户列表加载失败，请稍后重试')
+  } finally {
+    if (requestId === loadRequestId) loading.value = false
+  }
+}
+
+async function loadInitialData() {
+  const requestId = ++loadRequestId
+  loading.value = true
+  loadError.value = null
+  try {
+    const [result, optionRecords] = await Promise.all([
+      listPlatformManagedUsers(userQuery()),
+      getPlatformUserOptions(),
+    ])
+    options.value = {
+      tenants: optionRecords.tenants.filter((tenant) => String(tenant.id) === '0'),
+      roles: optionRecords.roles.filter((role) => String(role.tenantId) === '0'),
+    }
+    if (requestId !== loadRequestId) return
+    users.value = result.records
+    total.value = result.total
+  } catch (error) {
+    if (requestId !== loadRequestId) return
+    users.value = []
+    total.value = 0
+    loadError.value = getApiErrorDetails(error, '内部用户列表加载失败，请稍后重试')
+  } finally {
+    if (requestId === loadRequestId) loading.value = false
+  }
+}
+
+function openCreate() {
+  Object.assign(form, emptyForm())
+  editingUser.value = null
+  editorOpen.value = true
+  nextTick(() => formRef.value?.clearValidate())
+}
+
+function openEdit(row: PlatformManagedUser) {
+  editingUser.value = row
+  Object.assign(form, {
+    username: row.username,
+    displayName: row.displayName,
+    phone: row.phone ?? '',
+    email: row.email ?? '',
+    tenantId: '0',
+    roleIds: row.roleIds.map(String),
+    overseasWarehouseId: row.overseasWarehouseId == null ? '' : String(row.overseasWarehouseId),
+    password: '',
+    confirmPassword: '',
+    status: row.status,
+    resetPassword: false,
+  })
+  editorOpen.value = true
+  nextTick(() => formRef.value?.clearValidate())
+}
+
+async function loadOverseasWarehouses() {
+  const requestId = ++warehouseRequestId
+  overseasWarehousesLoading.value = true
+  overseasWarehousesError.value = null
+  try {
+    const records = await listSharedReceivingOverseasWarehouseOptions()
+    if (requestId !== warehouseRequestId) return
+    overseasWarehouses.value = records
+  } catch (error) {
+    if (requestId !== warehouseRequestId) return
+    overseasWarehouses.value = []
+    overseasWarehousesError.value = getApiErrorDetails(error, '共享海外收货仓加载失败，请重试')
+  } finally {
+    if (requestId === warehouseRequestId) overseasWarehousesLoading.value = false
+  }
+}
+
+function isCurrentUser(row: PlatformManagedUser | null) {
+  if (!row) return false
+  return String(row.userId) === auth.user?.id || String(row.authUserId) === auth.user?.id
+}
+
+function cannotDisable(row: PlatformManagedUser | null) {
+  return Boolean(row?.protectedAccount) || isCurrentUser(row)
+}
+
+async function saveUser() {
+  const valid = await formRef.value?.validate().catch(() => false)
+  if (!valid) return
+  saving.value = true
+  try {
+    if (!editingUser.value) {
+      await createPlatformManagedUser({
+        username: form.username.trim(),
+        displayName: form.displayName.trim(),
+        phone: form.phone.trim(),
+        email: form.email.trim(),
+        tenantId: '0',
+        roleIds: form.roleIds,
+        overseasWarehouseId: hasOverseasPdaRole.value ? form.overseasWarehouseId : null,
+        password: form.password,
+        status: form.status,
+      })
+      ElMessage.success('用户添加成功')
+    } else {
+      const row = editingUser.value
+      if (canEdit.value) {
+        await updatePlatformManagedUser(row.membershipId, {
+          displayName: form.displayName.trim(),
+          phone: form.phone.trim(),
+          email: form.email.trim(),
+          tenantId: '0',
+          roleIds: form.roleIds,
+          overseasWarehouseId: hasOverseasPdaRole.value ? form.overseasWarehouseId : null,
+        })
+      }
+      if (canChangeStatus.value && form.status !== row.status) {
+        await changePlatformManagedUserStatus(row.membershipId, form.status)
+      }
+      if (canResetPassword.value && form.resetPassword) {
+        await resetPlatformManagedUserPassword(row.membershipId, form.password)
+      }
+      ElMessage.success(form.resetPassword ? '用户信息已更新，密码已重置' : '用户信息已更新')
+    }
+    editorOpen.value = false
+    await loadUsers()
+  } catch (error) {
+    ElMessage.error(getApiErrorMessage(error, editingUser.value ? '用户更新失败，请稍后重试' : '用户添加失败，请稍后重试'))
+  } finally {
+    saving.value = false
+  }
+}
+
+async function toggleStatus(row: PlatformManagedUser) {
+  const targetStatus = row.status === 'ACTIVE' ? 'DISABLED' : 'ACTIVE'
+  const targetLabel = targetStatus === 'ACTIVE' ? '启用' : '禁用'
+  try {
+    await ElMessageBox.confirm(`确认${targetLabel}用户“${row.displayName}”吗？`, `${targetLabel}用户`, { customClass: 'admin-density-confirm',
+      confirmButtonText: `确认${targetLabel}`,
+      cancelButtonText: '取消',
+      type: targetStatus === 'DISABLED' ? 'warning' : 'info',
+    })
+    rowActionId.value = String(row.membershipId)
+    const updated = await changePlatformManagedUserStatus(row.membershipId, targetStatus)
+    Object.assign(row, updated)
+    ElMessage.success(`用户已${targetLabel}`)
+  } catch (error) {
+    if (error === 'cancel' || error === 'close') return
+    ElMessage.error(getApiErrorMessage(error, `用户${targetLabel}失败，请稍后重试`))
+  } finally {
+    rowActionId.value = ''
+  }
+}
+
+function formatLogin(value: string | null) {
+  if (!value) return '—'
+  return value.replace('T', ' ').slice(0, 16)
+}
+
+function applyFilters() {
+  appliedFilters.value = { ...filters.value }
+  if (page.value === 1) void loadUsers()
+  else page.value = 1
+}
+
+watch([page, pageSize], () => void loadUsers())
+watch(hasOverseasPdaRole, (selected) => {
+  if (!selected) {
+    form.overseasWarehouseId = ''
+    overseasWarehousesError.value = null
+    return
+  }
+  void loadOverseasWarehouses()
+})
+onMounted(loadInitialData)
+</script>
+
+<template>
+  <AdminPage class="admin-density iam-density" as="div">
+    <ListPageLayout aria-label="内部用户管理">
+      <template #toolbar>
+        <QueryToolbar
+          v-model="filters"
+          class="surface-panel"
+          ariaLabel="用户筛选"
+          :fields="queryFields"
+          preference-key="internal-users-query"
+          @search="applyFilters"
+        />
+      </template>
+      <template v-if="loadError" #state>
+        <LoadErrorState title="内部用户列表暂时无法加载" :message="loadError.message" :loading="loading" @retry="loadInitialData">
+          <template #details><ApiErrorMeta :details="loadError" /></template>
+        </LoadErrorState>
+      </template>
+
+      <section v-if="!loadError" class="surface-panel table-panel" :aria-busy="loading">
+      <DataTable v-model:page="page" v-model:page-size="pageSize" :data="users" :columns="userColumns" preference-key="internal-users-table"
+        :loading="loading" :total="total" aria-label="内部用户列表" row-key="membershipId" empty-text="没有符合筛选条件的内部用户">
+        <template #toolbar-actions><el-button v-if="canCreate" type="primary" @click="openCreate"><Plus :size="16" />新增用户</el-button></template>
+        <template #actions="{ row }">
+          <div class="table-actions density-actions">
+            <el-button class="density-action" v-if="canEdit || canChangeStatus || canResetPassword" size="small" data-tone="neutral" @click="openEdit(row as PlatformManagedUser)">
+              编辑
+            </el-button>
+            <el-button class="density-action" v-if="canChangeStatus" size="small" :data-tone="(row as PlatformManagedUser).status === 'ACTIVE' ? 'danger' : 'success'"
+              :loading="rowActionId === String((row as PlatformManagedUser).membershipId)"
+              :disabled="cannotDisable(row as PlatformManagedUser)"
+              :title="(row as PlatformManagedUser).protectedAccount ? '系统管理员不能被禁用' : isCurrentUser(row as PlatformManagedUser) ? '不能禁用当前登录用户' : undefined"
+              @click="toggleStatus(row as PlatformManagedUser)">
+              {{ (row as PlatformManagedUser).status === 'ACTIVE' ? '禁用' : '启用' }}
+            </el-button>
+          </div>
+        </template>
+        <template #roles="{ row }">
+          <div class="tag-list">
+            <el-tag v-for="role in (row as PlatformManagedUser).roleNames" :key="role" effect="plain" size="small">{{ role }}</el-tag>
+            <span v-if="!(row as PlatformManagedUser).roleNames.length" class="secondary-text">未分配</span>
+          </div>
+        </template>
+        <template #status="{ row }"><StatusBadge :status="(row as PlatformManagedUser).status === 'ACTIVE' ? '正常' : '禁用'" /></template>
+        <template #lastLoginAt="{ row }">{{ formatLogin((row as PlatformManagedUser).lastLoginAt) }}</template>
+        <template #pagination-left="{ total: tableTotal }"><span>共 {{ tableTotal }} 条</span></template>
+      </DataTable>
+      </section>
+    </ListPageLayout>
+
+    <AppDialog v-model="editorOpen" :title="editorLabel" width="min(650px, calc(100vw - 28px))" class="internal-user-editor-dialog admin-density-dialog iam-density" destroy-on-close :confirm-loading="saving" :confirm-text="editingUser ? '保存修改' : '确认添加'" @confirm="saveUser">
+      <el-form class="density-form" ref="formRef" :model="form" :rules="formRules" label-position="top">
+        <FormSection class="density-form-section" title="用户资料" description="维护登录身份、联系方式与平台角色。">
+          <div class="form-grid two-cols">
+          <el-form-item label="用户名" prop="username" required>
+            <el-input v-model="form.username" :disabled="Boolean(editingUser)" placeholder="登录用户名" maxlength="64" />
+          </el-form-item>
+          <el-form-item label="姓名" prop="displayName" required>
+            <el-input v-model="form.displayName" :disabled="Boolean(editingUser) && !canEdit" placeholder="真实姓名" maxlength="64" />
+          </el-form-item>
+          <el-form-item label="手机号" prop="phone" required>
+            <el-input v-model="form.phone" :disabled="Boolean(editingUser) && !canEdit" placeholder="手机号码" inputmode="tel" maxlength="11" />
+          </el-form-item>
+          <el-form-item label="邮箱" prop="email">
+            <el-input v-model="form.email" :disabled="Boolean(editingUser) && !canEdit" placeholder="邮箱地址" inputmode="email" maxlength="128" />
+          </el-form-item>
+          <el-form-item label="角色" prop="roleIds" required>
+            <el-select v-model="form.roleIds" multiple collapse-tags collapse-tags-tooltip
+              :disabled="Boolean(editingUser) && (!canEdit || !canGrantRoles || editingUser?.protectedAccount)" placeholder="选择角色">
+              <el-option v-for="role in availableRoles" :key="role.id" :label="role.name" :value="String(role.id)" :disabled="role.status !== 'ACTIVE'" />
+            </el-select>
+          </el-form-item>
+          <el-form-item label="状态" prop="status">
+            <el-select v-model="form.status" :disabled="Boolean(editingUser) && (!canChangeStatus || cannotDisable(editingUser))">
+              <el-option label="正常" value="ACTIVE" />
+              <el-option label="禁用" value="DISABLED" />
+            </el-select>
+          </el-form-item>
+          <el-form-item v-if="hasOverseasPdaRole" label="实际海外收货仓" prop="overseasWarehouseId" required>
+            <el-select v-model="form.overseasWarehouseId" filterable
+              :loading="overseasWarehousesLoading" :disabled="Boolean(editingUser) && !canEdit"
+              placeholder="请选择平台共享海外收货仓">
+              <el-option v-for="warehouse in overseasWarehouses" :key="warehouse.id"
+                :label="`${warehouse.warehouseName}（${warehouse.warehouseCode} · ${warehouse.countryCode}）`"
+                :value="warehouse.id" />
+            </el-select>
+            <p v-if="overseasWarehousesError" class="field-error">
+              {{ overseasWarehousesError.message }}
+              <el-button link type="primary" :loading="overseasWarehousesLoading" @click="loadOverseasWarehouses">重新加载</el-button>
+            </p>
+            <p v-else class="field-help">仓库将写入登录 Token，海外 PDA 不提供仓库切换。</p>
+          </el-form-item>
+          <el-form-item v-if="editingUser" label="最后登录">
+            <el-input :model-value="formatLogin(editingUser.lastLoginAt)" disabled />
+          </el-form-item>
+          </div>
+        </FormSection>
+
+        <FormSection class="density-form-section" v-if="!editingUser || canResetPassword" title="登录密码" description="密码为 8-64 位，并同时包含字母和数字。">
+          <el-checkbox v-if="editingUser" v-model="form.resetPassword">同时重置密码</el-checkbox>
+          <div v-if="!editingUser || form.resetPassword" class="form-grid two-cols password-fields">
+            <el-form-item :label="editingUser ? '新密码' : '初始密码'" prop="password" required>
+              <el-input v-model="form.password" type="password" show-password autocomplete="new-password" placeholder="8-64 位，包含字母和数字" />
+            </el-form-item>
+            <el-form-item label="确认密码" prop="confirmPassword" required>
+              <el-input v-model="form.confirmPassword" type="password" show-password autocomplete="new-password" placeholder="再次输入密码" />
+            </el-form-item>
+          </div>
+        </FormSection>
+      </el-form>
+    </AppDialog>
+  </AdminPage>
+</template>
+
+<style scoped>
+.password-fields { margin-top: var(--admin-space-6); }
+.field-help, .field-error { margin: 6px 0 0; font-size: var(--admin-font-caption); line-height: 1.5; }
+.field-help { color: var(--cc-text-secondary); }
+.field-error { color: var(--el-color-danger); }
+:global(.internal-user-editor-dialog) { max-height: min(760px, calc(100vh - 32px)); display: flex; flex-direction: column; }
+:global(.internal-user-editor-dialog .el-dialog__body) { min-height: 0; overflow-y: auto; }
+:global(.internal-user-editor-dialog .el-dialog__footer) { flex: 0 0 auto; }
+@media (max-width: 720px) {
+  .form-grid.two-cols { grid-template-columns: 1fr; }
+}
+</style>
diff --git a/src/modules/iam/pages/PermissionsDialog.behavior.test.ts b/src/modules/iam/pages/PermissionsDialog.behavior.test.ts
new file mode 100644
index 00000000..606fa3f3
--- /dev/null
+++ b/src/modules/iam/pages/PermissionsDialog.behavior.test.ts
@@ -0,0 +1,69 @@
+import ElementPlus, { type FormInstance } from 'element-plus'
+import { createPinia, setActivePinia } from 'pinia'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { useAuthStore } from '@/core/auth/auth'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import { createPlatformPermission, listPlatformPermissions, updatePlatformPermission } from '../api/platformIam'
+import PermissionsView from './PermissionsView.vue'
+
+vi.mock('../api/platformIam', () => ({
+  listPlatformPermissions: vi.fn(), createPlatformPermission: vi.fn(), updatePlatformPermission: vi.fn(),
+  changePlatformPermissionStatus: vi.fn(), deletePlatformPermission: vi.fn(),
+}))
+
+enableAutoUnmount(afterEach)
+afterEach(() => { document.body.innerHTML = ''; vi.unstubAllGlobals(); vi.clearAllMocks() })
+
+describe('permission editor modal', () => {
+  it.each(['create', 'edit'])('keeps the %s form in the centered dialog and preserves failed writes', async mode => {
+    vi.stubGlobal('ResizeObserver', class { observe() {} unobserve() {} disconnect() {} })
+    const pinia = createPinia()
+    setActivePinia(pinia)
+    const auth = useAuthStore()
+    auth.isServerSession = true
+    auth.permissions = ['platform:permission:list', 'platform:permission:create', 'platform:permission:edit']
+    vi.mocked(listPlatformPermissions).mockResolvedValue([{
+      id: '90071992547409931', tenantId: 0, appCode: 'PLATFORM', permissionType: 'MENU', parentId: 0,
+      permissionCode: 'platform:sample:list', permissionName: '测试菜单', routePath: '/sample',
+      httpMethod: null, sortNo: 10, status: 'ACTIVE',
+    }])
+    vi.mocked(createPlatformPermission).mockRejectedValue(new Error('保存失败'))
+    vi.mocked(updatePlatformPermission).mockRejectedValue(new Error('保存失败'))
+    const wrapper = mount(PermissionsView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+    await flushPromises()
+    await wrapper.findAll(mode === 'create' ? 'button' : '.el-table__body-wrapper button').find(button => button.text().trim() === (mode === 'create' ? '新增权限' : '编辑'))!.trigger('click')
+    await flushPromises()
+
+    const dialog = document.querySelector<HTMLElement>('.el-dialog.permission-editor-dialog.admin-density-dialog')!
+    expect(dialog).not.toBeNull()
+    expect(dialog.style.getPropertyValue('--el-dialog-width')).toBe('min(720px, calc(100vw - 28px))')
+    expect(document.querySelector('.el-drawer')).toBeNull()
+    expect(dialog.querySelectorAll('.el-form-item')).toHaveLength(6)
+    const codeInput = dialog.querySelector<HTMLInputElement>('input[placeholder="如：platform:customer:list"]')!
+    expect(codeInput.disabled).toBe(mode === 'edit')
+    // Vitest externalizes Element Plus: its CJS validator interop differs from the Vite browser bundle.
+    // Exercise the dialog's validation gate explicitly, without changing production rules.
+    const form = wrapper.findComponent({ name: 'ElForm' })
+    expect(form.props('rules').name).toEqual(expect.arrayContaining([expect.objectContaining({ required: true })]))
+    const validate = vi.spyOn(form.vm.$.exposed as FormInstance, 'validate').mockResolvedValue(true)
+    if (mode === 'create') {
+      validate.mockRejectedValueOnce({ name: [{ message: '请输入权限名称' }] })
+      wrapper.getComponent(AppDialog).vm.$emit('confirm')
+      await flushPromises()
+      expect(createPlatformPermission).not.toHaveBeenCalled()
+      for (const [placeholder, value] of [['用户可理解的中文名称', '新增菜单'], ['如：platform:customer:list', 'platform:new:list'], ['如：/customers', '/new']]) {
+        const input = dialog.querySelector<HTMLInputElement>(`input[placeholder="${placeholder}"]`)!
+        input.value = value!
+        input.dispatchEvent(new Event('input', { bubbles: true }))
+      }
+    }
+    await flushPromises()
+    wrapper.getComponent(AppDialog).vm.$emit('confirm')
+    await flushPromises()
+    if (mode === 'create') expect(createPlatformPermission).toHaveBeenCalledWith({ type: 'MENU', code: 'platform:new:list', name: '新增菜单', parentId: '0', routePath: '/new', httpMethod: null, sortNo: 10 })
+    else expect(updatePlatformPermission).toHaveBeenCalledWith('90071992547409931', { name: '测试菜单', parentId: null, routePath: '/sample', httpMethod: null, sortNo: 10 })
+    expect(wrapper.getComponent(AppDialog).props('modelValue')).toBe(true)
+    expect(codeInput.value).toBe(mode === 'create' ? 'platform:new:list' : 'platform:sample:list')
+  })
+})
diff --git a/src/modules/iam/pages/PermissionsView.test.ts b/src/modules/iam/pages/PermissionsView.test.ts
new file mode 100644
index 00000000..5bc8dab0
--- /dev/null
+++ b/src/modules/iam/pages/PermissionsView.test.ts
@@ -0,0 +1,242 @@
+import { createPinia, setActivePinia } from 'pinia'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { flushPromises, shallowMount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { listPlatformPermissions, type PlatformPermissionResource } from '@/modules/iam/api/platformIam'
+import { useAuthStore } from '@/core/auth/auth'
+import PermissionsView from './PermissionsView.vue'
+
+const permissionsSource = readFileSync(resolve(process.cwd(), 'src/modules/iam/pages/PermissionsView.vue'), 'utf8')
+
+vi.mock('@/modules/iam/api/platformIam', () => ({
+  changePlatformPermissionStatus: vi.fn(),
+  createPlatformPermission: vi.fn(),
+  deletePlatformPermission: vi.fn(),
+  listPlatformPermissions: vi.fn(),
+  updatePlatformPermission: vi.fn(),
+}))
+
+const permission: PlatformPermissionResource = {
+  id: 5100010,
+  tenantId: 0,
+  appCode: 'PLATFORM',
+  permissionType: 'MENU',
+  parentId: 0,
+  permissionCode: 'platform:customer:list',
+  permissionName: '企业客户',
+  routePath: '/customers',
+  httpMethod: null,
+  sortNo: 10,
+  status: 'ACTIVE',
+}
+
+const allActionPermissions = [
+  'platform:permission:list',
+  'platform:permission:create',
+  'platform:permission:edit',
+  'platform:permission:status',
+  'platform:permission:delete',
+]
+
+function mountServerView(permissionCodes = ['platform:permission:list', 'platform:permission:create']) {
+  const pinia = createPinia()
+  setActivePinia(pinia)
+  const auth = useAuthStore()
+  auth.isServerSession = true
+  auth.permissions = permissionCodes
+  return shallowMount(PermissionsView, {
+    global: {
+      plugins: [pinia],
+      directives: { loading: () => undefined },
+      stubs: {
+        AdminPage: { template: '<main><slot /></main>' },
+        ListPageLayout: { template: '<section><slot name="toolbar" /><slot name="state" /><slot /></section>' },
+        FormSection: { template: '<section><slot /></section>' },
+        AppDialog: { template: '<section><slot /><slot name="footer" /></section>' },
+        LoadErrorState: { props: ['message'], template: '<div role="alert">{{ message }}<slot name="details" /></div>' },
+        DataTable: {
+          props: ['data'],
+          template: '<section><slot name="toolbar-actions" /><div v-for="row in data" :key="row.id" class="row-actions" :data-row-id="row.id"><slot name="actions" :row="row" /></div><span data-testid="row-count">{{ data.length }}</span></section>',
+        },
+        'el-alert': { props: ['title'], template: '<div role="alert">{{ title }}<slot name="title" /></div>' },
+        'el-input': true,
+        'el-option': true,
+        'el-select': true,
+        'el-button': { props: ['disabled'], template: '<button :disabled="disabled"><slot /></button>' },
+        'el-dropdown': { template: '<div class="dropdown"><slot /><slot name="dropdown" /></div>' },
+        'el-dropdown-menu': { template: '<div><slot /></div>' },
+        'el-dropdown-item': { props: ['disabled'], template: '<button class="dropdown-item" :disabled="disabled"><slot /></button>' },
+        'el-table': true,
+        'el-table-column': true,
+        'el-input-number': true,
+        'el-radio-group': true,
+        'el-radio-button': true,
+        'el-drawer': { template: '<section><slot /><slot name="footer" /></section>' },
+        'el-form': { template: '<form><slot /></form>' },
+        'el-form-item': { template: '<label><slot /></label>' },
+      },
+    },
+  })
+}
+
+describe('PermissionsView IAM mode', () => {
+  it('keeps the shared status badge prop defined during table slot initialization', () => {
+    expect(permissionsSource).toContain("(row as Permission).status || '—'")
+  })
+  it('uses outlined business action buttons while keeping tree view helpers as links', () => {
+    expect(permissionsSource).toContain('size="small" data-tone="neutral" @click="openCreate((row as Permission).id)"')
+    expect(permissionsSource).toContain('size="small" data-tone="neutral" :disabled="rowActionId')
+    expect(permissionsSource).toContain('size="small" :data-tone="(row as Permission).status')
+    expect(permissionsSource).toContain('size="small" data-tone="danger"')
+    expect(permissionsSource).toContain('size="small" :aria-label="moreActionsLabel(row as Permission)"')
+    expect(permissionsSource).toContain('>添加下级</el-button>')
+    expect(permissionsSource).toContain('>编辑</el-button>')
+    expect(permissionsSource).toContain(':data-tone=')
+    expect(permissionsSource).toContain('>删除</el-button>')
+    expect(permissionsSource).toContain('<MoreHorizontal aria-hidden="true" :size="16" />')
+    expect(permissionsSource).toContain('<el-button link type="primary" @click="expandAllRows">展开全部</el-button>')
+    expect(permissionsSource).not.toContain('canAddChild(row as Permission)" link')
+    expect(permissionsSource).not.toContain('canEditRow(row as Permission)" link')
+    expect(permissionsSource).not.toContain('canChangeStatusRow(row as Permission)" link')
+  })
+
+  beforeEach(() => {
+    vi.mocked(listPlatformPermissions).mockReset()
+  })
+
+  it('keeps technical permission fields out of the default list and labels the table', () => {
+    expect(permissionsSource).toContain("{ key: 'code', label: '权限编码', minWidth: 220, slotName: 'code' }")
+    expect(permissionsSource).toContain("{ key: 'endpoint', label: '路由 / 接口', minWidth: 260, slotName: 'endpoint' }")
+    expect(permissionsSource).toContain("{ key: 'sort', prop: 'sort', label: '排序', width: 72, align: 'right' }")
+    expect(permissionsSource).toContain('aria-label="平台权限资源列表"')
+  })
+
+  it('loads the platform permission resource tree from IAM', async () => {
+    vi.mocked(listPlatformPermissions).mockResolvedValue([permission])
+
+    const wrapper = mountServerView()
+    await flushPromises()
+
+    expect(listPlatformPermissions).toHaveBeenCalledTimes(1)
+    expect(wrapper.text()).not.toContain('权限资源树')
+  })
+
+  it('shows a recoverable state when the permission list fails', async () => {
+    vi.mocked(listPlatformPermissions).mockRejectedValue(new Error('IAM unavailable'))
+
+    const wrapper = mountServerView()
+    await flushPromises()
+
+    const alertText = wrapper.findAll('[role="alert"]').map((item) => item.text()).join(' ')
+    expect(alertText).toContain('权限资源加载失败，请稍后重试')
+    expect(alertText).not.toContain('IAM unavailable')
+  })
+
+  it('shows only add-child directly for a built-in menu even with all permissions', async () => {
+    vi.mocked(listPlatformPermissions).mockResolvedValue([{ ...permission, builtIn: true }])
+
+    const wrapper = mountServerView(allActionPermissions)
+    await flushPromises()
+
+    const actions = wrapper.get('[data-row-id="5100010"]')
+    expect(actions.text()).toContain('添加下级')
+    expect(actions.text()).not.toContain('系统内置')
+    expect(actions.text()).not.toContain('编辑')
+    expect(actions.text()).not.toContain('停用')
+    expect(actions.text()).not.toContain('删除')
+    expect(actions.find('.dropdown').exists()).toBe(false)
+  })
+
+  it('keeps three frequent actions direct and moves delete into more for a custom menu', async () => {
+    vi.mocked(listPlatformPermissions).mockResolvedValue([{ ...permission, builtIn: false }])
+
+    const wrapper = mountServerView(allActionPermissions)
+    await flushPromises()
+
+    const actions = wrapper.get('[data-row-id="5100010"]')
+    expect(actions.text()).toContain('添加下级')
+    expect(actions.text()).toContain('编辑')
+    expect(actions.text()).toContain('停用')
+    expect(actions.get('.dropdown').text()).toContain('删除')
+    expect(actions.get('.dropdown-item').classes()).toContain('danger-menu-item')
+    expect(actions.get('[aria-label="企业客户的更多操作"]').attributes('title')).toBe('企业客户的更多操作')
+  })
+
+  it('shows edit, status, and delete directly for a custom non-menu resource', async () => {
+    vi.mocked(listPlatformPermissions).mockResolvedValue([{
+      ...permission,
+      permissionType: 'BUTTON',
+      permissionCode: 'platform:customer:edit',
+      permissionName: '编辑企业客户',
+      routePath: null,
+      builtIn: false,
+    }])
+
+    const wrapper = mountServerView(allActionPermissions)
+    await flushPromises()
+
+    const actions = wrapper.get('[data-row-id="5100010"]')
+    expect(actions.text()).not.toContain('添加下级')
+    expect(actions.text()).toContain('编辑')
+    expect(actions.text()).toContain('停用')
+    expect(actions.text()).toContain('删除')
+    expect(actions.find('.dropdown').exists()).toBe(false)
+  })
+
+  it('shows all three actually available menu actions directly when permissions are reduced', async () => {
+    vi.mocked(listPlatformPermissions).mockResolvedValue([{ ...permission, builtIn: false }])
+
+    const wrapper = mountServerView([
+      'platform:permission:list',
+      'platform:permission:create',
+      'platform:permission:edit',
+      'platform:permission:delete',
+    ])
+    await flushPromises()
+
+    const actions = wrapper.get('[data-row-id="5100010"]')
+    expect(actions.text()).toContain('添加下级')
+    expect(actions.text()).toContain('编辑')
+    expect(actions.text()).toContain('删除')
+    expect(actions.text()).not.toContain('停用')
+    expect(actions.find('.dropdown').exists()).toBe(false)
+  })
+
+  it('falls back from a missing name and code to the row id for the more-action label', async () => {
+    vi.mocked(listPlatformPermissions).mockResolvedValue([{
+      ...permission,
+      permissionName: '',
+      permissionCode: '',
+      builtIn: false,
+    }])
+
+    const wrapper = mountServerView(allActionPermissions)
+    await flushPromises()
+
+    const moreButton = wrapper.get('[data-row-id="5100010"] [aria-label="当前权限的更多操作"]')
+    expect(moreButton.attributes('title')).toBe('当前权限的更多操作')
+    expect(moreButton.attributes('aria-label')).not.toMatch(/undefined|null/)
+  })
+
+  it('gives more-action buttons distinct accessible names across rows', async () => {
+    vi.mocked(listPlatformPermissions).mockResolvedValue([
+      { ...permission, builtIn: false },
+      {
+        ...permission,
+        id: 5100020,
+        permissionCode: 'platform:role:list',
+        permissionName: '角色管理',
+        routePath: '/roles',
+        builtIn: false,
+      },
+    ])
+
+    const wrapper = mountServerView(allActionPermissions)
+    await flushPromises()
+
+    const labels = wrapper.findAll('[aria-label$="的更多操作"]').map((button) => button.attributes('aria-label'))
+    expect(labels).toEqual(['企业客户的更多操作', '角色管理的更多操作'])
+    expect(new Set(labels).size).toBe(labels.length)
+  })
+})
diff --git a/src/modules/iam/pages/PermissionsView.vue b/src/modules/iam/pages/PermissionsView.vue
new file mode 100644
index 00000000..6757d9bf
--- /dev/null
+++ b/src/modules/iam/pages/PermissionsView.vue
@@ -0,0 +1,343 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import '../iamDensity.css'
+import { computed, nextTick, onMounted, reactive, ref } from 'vue'
+import { ElMessage, ElMessageBox, type FormInstance, type FormRules } from 'element-plus'
+import { Braces, FolderTree, MoreHorizontal, Plus, ShieldCheck } from '@lucide/vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import FormSection from '@/shared/components/FormSection.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import {
+  changePlatformPermissionStatus,
+  createPlatformPermission,
+  deletePlatformPermission,
+  listPlatformPermissions,
+  updatePlatformPermission,
+} from '@/modules/iam/api/platformIam'
+import { getApiErrorDetails, getApiErrorMessage, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import { useUnsavedWorkRegistration } from '@/core/unsaved-work/useUnsavedWorkRegistration'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import type { Permission, PermissionType } from '@/modules/iam/types'
+import { buildPermissionTree, getDescendantIds, type PermissionTreeNode } from '@/modules/iam/utils/permissionTree'
+import { mapPlatformPermission } from '@/modules/iam/utils/platformPermission'
+
+const access = useAccessPreviewStore()
+const editorOpen = ref(false)
+const formRef = ref<FormInstance>()
+const serverPermissions = ref<Permission[]>([])
+const loading = ref(false)
+const saving = ref(false)
+const rowActionId = ref('')
+const loadError = ref<ApiErrorDetails | null>(null)
+const page = ref(1)
+const pageSize = ref(10)
+type PermissionFilters = QueryModel & { keyword: string; type: string; status: string }
+const filters = ref<PermissionFilters>({ keyword: '', type: '', status: '' })
+const appliedFilters = ref<PermissionFilters>({ ...filters.value })
+const queryFields: QueryField[] = [
+  { key: 'keyword', type: 'input', label: '权限关键词', placeholder: '权限名称、编码或路径' },
+  { key: 'type', type: 'select', label: '类型', placeholder: '全部类型', options: [{ label: '菜单', value: '菜单' }, { label: '页面', value: '页面' }, { label: '按钮', value: '按钮' }, { label: '接口', value: '接口' }] },
+  { key: 'status', type: 'select', label: '状态', placeholder: '全部状态', options: [{ label: '启用', value: '启用' }, { label: '停用', value: '停用' }] },
+]
+const expandedRowKeys = ref<string[]>([])
+const tableRenderKey = ref(0)
+const emptyForm = (): Permission => ({ id: '', parentId: null, name: '', code: '', type: '菜单', path: '', method: '-', status: '启用', sort: 10 })
+const form = reactive(emptyForm())
+const formRules = computed<FormRules>(() => ({
+  name: [{ required: true, whitespace: true, message: '请输入权限名称', trigger: 'blur' }],
+  code: [{ required: true, whitespace: true, message: '请输入权限编码', trigger: 'blur' }],
+  type: [{ required: true, message: '请选择资源类型', trigger: 'change' }],
+  parentId: ['按钮', '页面', '接口'].includes(form.type) ? [{ required: true, message: '请选择上级菜单', trigger: 'change' }] : [],
+  path: ['菜单', '页面'].includes(form.type) ? [{ required: true, whitespace: true, message: '请输入菜单路由', trigger: 'blur' }] : [],
+  method: form.type === '接口' ? [{ required: true, message: '请选择 HTTP 方法', trigger: 'change' }] : [],
+  sort: [{ required: true, type: 'number', message: '请输入显示排序', trigger: 'change' }],
+}))
+const editorLabel = computed(() => form.id ? '编辑权限' : '新增权限')
+const requiredPermission = computed(() => form.id ? 'platform:permission:edit' : 'platform:permission:create')
+const { captureBaseline } = useUnsavedWorkRegistration({
+  key: 'permission-editor',
+  label: editorLabel,
+  isOpen: editorOpen,
+  model: form,
+  requiredPermission,
+})
+const availablePermissionTypes: PermissionType[] = ['菜单', '页面', '按钮', '接口']
+const permissions = computed(() => serverPermissions.value)
+const canCreate = computed(() => access.can('platform:permission:create'))
+const canEdit = computed(() => access.can('platform:permission:edit'))
+const canChangeStatus = computed(() => access.can('platform:permission:status'))
+const canDelete = computed(() => access.can('platform:permission:delete'))
+
+function matches(item: Permission) {
+  const keyword = appliedFilters.value.keyword.trim().toLowerCase()
+  return (!keyword || [item.name, item.code, item.path].some((value) => value.toLowerCase().includes(keyword))) && (!appliedFilters.value.type || item.type === appliedFilters.value.type) && (!appliedFilters.value.status || item.status === appliedFilters.value.status)
+}
+const treeRows = computed(() => buildPermissionTree(permissions.value, matches))
+const pagedTreeRows = computed(() => treeRows.value.slice((page.value - 1) * pageSize.value, page.value * pageSize.value))
+const rootRowKeys = computed(() => treeRows.value.map((item) => item.id))
+const blockedParentIds = computed(() => new Set(
+  form.id ? [form.id, ...getDescendantIds(permissions.value, form.id)] : [],
+))
+const parentOptions = computed(() => permissions.value.filter((item) => (
+  ['目录', '菜单', '页面'].includes(item.type) && !blockedParentIds.value.has(item.id)
+)))
+const permissionColumns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 280, fixed: 'left', slotName: 'actions' },
+  { key: 'name', label: '权限名称', minWidth: 260, slotName: 'name' },
+  { key: 'code', label: '权限编码', minWidth: 220, slotName: 'code' },
+  { key: 'type', prop: 'type', label: '类型', width: 80 },
+  { key: 'endpoint', label: '路由 / 接口', minWidth: 260, slotName: 'endpoint' },
+  { key: 'sort', prop: 'sort', label: '排序', width: 72, align: 'right' },
+  { key: 'status', label: '状态', width: 88, slotName: 'status' },
+]
+
+async function loadPermissions() {
+  loading.value = true
+  loadError.value = null
+  serverPermissions.value = []
+  try {
+    serverPermissions.value = (await listPlatformPermissions()).map(mapPlatformPermission)
+    expandedRowKeys.value = rootRowKeys.value
+    tableRenderKey.value += 1
+  } catch (error) {
+    loadError.value = getApiErrorDetails(error, '权限资源加载失败，请稍后重试')
+  } finally {
+    loading.value = false
+  }
+}
+
+function applyFilters() {
+  appliedFilters.value = { ...filters.value }
+  page.value = 1
+  void loadPermissions()
+}
+
+function collectDescendantIds(nodes: PermissionTreeNode[], ids: string[] = []) {
+  nodes.forEach((node) => {
+    ids.push(node.id)
+    if (node.children) collectDescendantIds(node.children, ids)
+  })
+  return ids
+}
+
+function permissionSummary(row: PermissionTreeNode) {
+  const descendants = collectDescendantIds(row.children ?? [])
+    .map((id) => permissions.value.find((item) => item.id === id))
+    .filter((item): item is Permission => Boolean(item))
+  const menuCount = descendants.filter((item) => ['菜单', '页面'].includes(item.type)).length
+  const actionCount = descendants.filter((item) => ['按钮', '接口'].includes(item.type)).length
+  if (menuCount === 0 && actionCount === 0) return '无下级权限'
+  return [menuCount ? `${menuCount} 个菜单` : '', actionCount ? `${actionCount} 项操作` : ''].filter(Boolean).join(' · ')
+}
+
+function expandAllRows() {
+  expandedRowKeys.value = collectDescendantIds(treeRows.value)
+  tableRenderKey.value += 1
+}
+
+function collapseActionRows() {
+  expandedRowKeys.value = rootRowKeys.value
+  tableRenderKey.value += 1
+}
+
+function openCreate(parentId: string | null = null) {
+  Object.assign(form, emptyForm(), { parentId })
+  captureBaseline()
+  editorOpen.value = true
+  nextTick(() => formRef.value?.clearValidate())
+}
+function openEdit(row: Permission) {
+  if (!canEdit.value || row.builtIn) return
+  Object.assign(form, { ...row })
+  captureBaseline()
+  editorOpen.value = true
+  nextTick(() => formRef.value?.clearValidate())
+}
+function handleTypeChange() {
+  if (!['菜单', '页面'].includes(form.type)) form.path = ''
+  form.method = form.type === '接口' ? (form.method === '-' ? 'GET' : form.method) : '-'
+  nextTick(() => formRef.value?.clearValidate(['parentId', 'path', 'method']))
+}
+async function savePermission() {
+  const valid = await formRef.value?.validate().catch(() => false)
+  if (!valid) return
+  if (permissions.value.some((item) => item.code.toLowerCase() === form.code.toLowerCase() && item.id !== form.id)) { ElMessage.error('权限编码已经存在'); return }
+  saving.value = true
+  try {
+    if (form.id) {
+      const updated = await updatePlatformPermission(form.id, {
+        name: form.name.trim(),
+        parentId: form.parentId,
+        routePath: ['菜单', '页面'].includes(form.type) ? form.path.trim() : null,
+        httpMethod: form.method === '-' ? null : form.method,
+        sortNo: form.sort,
+      })
+      const index = serverPermissions.value.findIndex((item) => item.id === form.id)
+      if (index >= 0) serverPermissions.value[index] = mapPlatformPermission(updated)
+      ElMessage.success('权限资源已更新')
+    } else {
+      const created = await createPlatformPermission({
+        type: ({ 目录: 'MENU', 菜单: 'MENU', 页面: 'PAGE', 按钮: 'BUTTON', 接口: 'API' } as const)[form.type],
+        code: form.code.trim(),
+        name: form.name.trim(),
+        parentId: form.parentId || '0',
+        routePath: ['菜单', '页面'].includes(form.type) ? form.path.trim() : null,
+        httpMethod: form.type === '接口' ? form.method : null,
+        sortNo: form.sort,
+      })
+      serverPermissions.value.push(mapPlatformPermission(created))
+      ElMessage.success('权限资源已创建')
+    }
+    editorOpen.value = false
+  } catch (error) {
+    ElMessage.error(getApiErrorMessage(error, form.id ? '权限资源更新失败，请稍后重试' : '权限资源创建失败，请稍后重试'))
+  } finally {
+    saving.value = false
+  }
+}
+async function toggleStatus(row: Permission) {
+  if (row.builtIn) return
+  const target = row.status === '启用' ? '停用' : '启用'
+  try {
+    await ElMessageBox.confirm(`确认${target}权限“${row.name}”吗？`, '权限状态', { customClass: 'admin-density-confirm',  confirmButtonText: '确认', cancelButtonText: '取消' })
+    rowActionId.value = row.id
+    const updated = await changePlatformPermissionStatus(row.id, target === '启用' ? 'ACTIVE' : 'DISABLED')
+    Object.assign(row, mapPlatformPermission(updated))
+    ElMessage.success(`权限已${target}`)
+  } catch (error) {
+    if (error === 'cancel' || error === 'close') return
+    ElMessage.error(getApiErrorMessage(error, '权限状态更新失败，请稍后重试'))
+  } finally {
+    rowActionId.value = ''
+  }
+}
+
+async function removePermission(row: Permission) {
+  if (row.builtIn) return
+  try {
+    await ElMessageBox.confirm(`确认删除权限“${row.name}”吗？删除前需确保没有下级资源且未分配给角色。`, '删除权限', { customClass: 'admin-density-confirm',  confirmButtonText: '删除', cancelButtonText: '取消', type: 'warning' })
+    rowActionId.value = row.id
+    await deletePlatformPermission(row.id)
+    await loadPermissions()
+    ElMessage.success('权限资源已删除')
+  } catch (error) {
+    if (error === 'cancel' || error === 'close') return
+    ElMessage.error(getApiErrorMessage(error, '权限资源删除失败，请稍后重试'))
+  } finally {
+    rowActionId.value = ''
+  }
+}
+function typeClass(type: PermissionType) { return { '目录': 'directory', '菜单': 'menu', '页面': 'menu', '按钮': 'action', '接口': 'api' }[type] }
+
+function canAddChild(row: Permission) {
+  return canCreate.value && ['菜单', '页面'].includes(row.type)
+}
+function canEditRow(row: Permission) {
+  return canEdit.value && !row.builtIn
+}
+function canChangeStatusRow(row: Permission) {
+  return canChangeStatus.value && !row.builtIn
+}
+function canDeleteRow(row: Permission) {
+  return canDelete.value && !row.builtIn
+}
+function permissionActionCount(row: Permission) {
+  return Number(canAddChild(row))
+    + Number(canEditRow(row))
+    + Number(canChangeStatusRow(row))
+    + Number(canDeleteRow(row))
+}
+function showDeleteDirect(row: Permission) {
+  return canDeleteRow(row) && permissionActionCount(row) <= 3
+}
+function showDeleteMore(row: Permission) {
+  return canDeleteRow(row) && permissionActionCount(row) > 3
+}
+function moreActionsLabel(row: Permission) {
+  const resourceLabel = [row.name]
+    .find((value) => typeof value === 'string' && value.trim())
+    ?.trim() || '当前权限'
+  return `${resourceLabel}的更多操作`
+}
+
+onMounted(loadPermissions)
+</script>
+
+<template>
+  <AdminPage class="admin-density iam-density" as="div">
+    <ListPageLayout aria-label="平台权限资源管理">
+      <template #toolbar><QueryToolbar v-model="filters" class="surface-panel" ariaLabel="权限筛选" :fields="queryFields" preference-key="permissions-query" @search="applyFilters" /></template>
+      <template v-if="loadError" #state>
+        <LoadErrorState title="权限资源暂时无法加载" :message="loadError.message" :loading="loading" @retry="loadPermissions">
+          <template #details><ApiErrorMeta :details="loadError" /></template>
+        </LoadErrorState>
+      </template>
+
+      <section v-if="!loadError" class="surface-panel table-panel">
+      <DataTable :key="tableRenderKey" v-model:page="page" v-model:page-size="pageSize" :data="pagedTreeRows" :columns="permissionColumns" preference-key="permissions-table" :loading="loading" :total="treeRows.length" row-key="id" aria-label="平台权限资源列表" :expand-row-keys="expandedRowKeys" :tree-props="{ children: 'children' }" empty-text="没有符合条件的权限资源">
+        <template #toolbar-start><div class="permission-tree-tools"><div class="legend-list"><span><i class="is-menu" />目录 / 菜单</span><span><i class="is-action" />操作</span><span><i class="is-api" />接口预留</span><span class="permission-protection-hint">受保护资源不可编辑、停用或删除</span></div><div class="tree-view-actions"><el-button link type="primary" @click="expandAllRows">展开全部</el-button><el-button link @click="collapseActionRows">收起操作权限</el-button></div></div></template>
+        <template #toolbar-actions><el-button v-if="canCreate" type="primary" @click="openCreate(null)"><Plus :size="16" />新增权限</el-button></template>
+        <template #actions="{ row }">
+          <div v-if="permissionActionCount(row as Permission) > 0 || (row as Permission).builtIn" class="table-actions density-actions">
+            <el-button class="density-action" v-if="canAddChild(row as Permission)" size="small" data-tone="neutral" @click="openCreate((row as Permission).id)">添加下级</el-button>
+            <el-button class="density-action" v-if="canEditRow(row as Permission)" size="small" data-tone="neutral" :disabled="rowActionId === (row as Permission).id" @click="openEdit(row as Permission)">编辑</el-button>
+            <el-button class="density-action" v-if="canChangeStatusRow(row as Permission)" size="small" :data-tone="(row as Permission).status === '启用' ? 'danger' : 'success'" :loading="rowActionId === (row as Permission).id" @click="toggleStatus(row as Permission)">{{ (row as Permission).status === '启用' ? '停用' : '启用' }}</el-button>
+            <el-button class="density-action" v-if="showDeleteDirect(row as Permission)" size="small" data-tone="danger" :disabled="rowActionId === (row as Permission).id" @click="removePermission(row as Permission)">删除</el-button>
+            <el-dropdown v-if="showDeleteMore(row as Permission)" trigger="click" @command="(command: string) => command === 'delete' && removePermission(row as Permission)">
+              <el-button data-tone="neutral" class="density-action" size="small" :aria-label="moreActionsLabel(row as Permission)" :title="moreActionsLabel(row as Permission)"><MoreHorizontal aria-hidden="true" :size="16" /></el-button>
+              <template #dropdown><el-dropdown-menu><el-dropdown-item command="delete" :disabled="rowActionId === (row as Permission).id" class="danger-menu-item">删除</el-dropdown-item></el-dropdown-menu></template>
+            </el-dropdown>
+          </div>
+          <span v-else class="secondary-text">仅查看</span>
+        </template>
+        <template #name="{ row }"><div class="permission-name"><span :class="`is-${typeClass((row as Permission).type)}`"><FolderTree v-if="['目录', '菜单', '页面'].includes((row as Permission).type)" :size="16" /><ShieldCheck v-else-if="(row as Permission).type === '按钮'" :size="16" /><Braces v-else :size="16" /></span><div><strong>{{ (row as Permission).name }}</strong><small v-if="(row as PermissionTreeNode).children?.length">{{ permissionSummary(row as PermissionTreeNode) }}</small></div></div></template>
+        <template #code="{ row }"><code class="code-value">{{ (row as Permission).code }}</code></template>
+        <template #endpoint="{ row }"><div class="endpoint-cell"><span v-if="(row as Permission).method !== '-'">{{ (row as Permission).method }}</span><code>{{ (row as Permission).path || '-' }}</code></div></template>
+        <template #status="{ row }"><StatusBadge :status="(row as Permission).status || '—'" /></template>
+        <template #pagination-left="{ total: tableTotal }"><span>共 {{ tableTotal }} 项</span></template>
+      </DataTable>
+      </section>
+    </ListPageLayout>
+
+    <AppDialog v-model="editorOpen" :title="form.id ? '编辑权限资源' : '新增权限资源'" width="min(720px, calc(100vw - 28px))" class="permission-editor-dialog admin-density-dialog iam-density" :confirm-loading="saving" :confirm-text="form.id ? '保存修改' : '保存权限'" :show-confirm="form.id ? canEdit : canCreate" @confirm="savePermission">
+      <el-form ref="formRef" :model="form" :rules="formRules" label-position="top" class="density-form">
+        <FormSection class="density-form-section" title="资源定义" description="定义权限名称、编码、类型和层级关系。">
+          <div class="form-grid two-cols">
+            <el-form-item label="权限名称" prop="name" required><el-input v-model="form.name" placeholder="用户可理解的中文名称" maxlength="64" /></el-form-item>
+            <el-form-item label="权限编码" prop="code" required><el-input v-model="form.code" :disabled="Boolean(form.id)" placeholder="如：platform:customer:list" maxlength="128" /></el-form-item>
+            <el-form-item label="资源类型" prop="type" required><el-select v-model="form.type" :disabled="Boolean(form.id)" @change="handleTypeChange"><el-option v-for="item in availablePermissionTypes" :key="item" :label="item" :value="item" /></el-select></el-form-item>
+            <el-form-item label="上级资源" prop="parentId" :required="['按钮', '页面', '接口'].includes(form.type)"><el-select v-model="form.parentId" clearable placeholder="作为一级资源"><el-option v-for="item in parentOptions" :key="item.id" :label="`${item.name} (${item.code})`" :value="item.id" /></el-select></el-form-item>
+            <el-form-item v-if="['菜单', '页面'].includes(form.type)" label="路由路径" prop="path" required><el-input v-model="form.path" placeholder="如：/customers" /></el-form-item>
+            <el-form-item v-if="form.type === '接口'" label="HTTP 方法" prop="method" required><el-select v-model="form.method"><el-option v-for="method in ['GET', 'POST', 'PUT', 'PATCH', 'DELETE']" :key="method" :label="method" :value="method" /></el-select></el-form-item>
+            <el-form-item label="显示排序" prop="sort" required><el-input-number v-model="form.sort" :min="0" :max="999" controls-position="right" placeholder="请输入排序值" /></el-form-item>
+          </div>
+        </FormSection>
+        <div class="form-callout"><Braces :size="18" /><div><strong>权限编码约定</strong><p>使用稳定的“业务域:资源:动作”编码；资源类型与后端 MENU、PAGE、BUTTON、API 契约一致。</p></div></div>
+      </el-form>
+    </AppDialog>
+  </AdminPage>
+</template>
+
+<style scoped>
+.permission-tree-tools { display: flex; align-items: center; gap: var(--admin-space-6); }
+.permission-protection-hint { color: var(--cc-muted); }
+.tree-view-actions { display: flex; align-items: center; gap: var(--admin-space-1); white-space: nowrap; }
+.tree-view-actions .el-button + .el-button { margin-left: 0; }
+.permission-name > div { display: flex; min-width: 0; flex-direction: column; gap: 2px; }
+.permission-name small { color: var(--cc-muted); font-size: var(--admin-font-caption); line-height: 1.35; }
+:deep(.danger-menu-item:not(.is-disabled)) { color: var(--el-color-danger); }
+
+@media (max-width: 720px) {
+  .permission-tree-tools { width: 100%; align-items: flex-start; flex-direction: column; gap: 8px; }
+}
+
+@media (max-width: 420px) {
+  .tree-view-actions { width: 100%; justify-content: flex-start; }
+}
+</style>
diff --git a/src/modules/iam/pages/RolesView.test.ts b/src/modules/iam/pages/RolesView.test.ts
new file mode 100644
index 00000000..eb805e05
--- /dev/null
+++ b/src/modules/iam/pages/RolesView.test.ts
@@ -0,0 +1,160 @@
+import { createPinia, setActivePinia } from 'pinia'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { flushPromises, shallowMount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { createPlatformRole, listPlatformPermissions, listPlatformRoles, type PlatformRoleResource } from '@/modules/iam/api/platformIam'
+import { useAuthStore } from '@/core/auth/auth'
+import RolesView from './RolesView.vue'
+
+const rolesSource = readFileSync(resolve(process.cwd(), 'src/modules/iam/pages/RolesView.vue'), 'utf8')
+
+vi.mock('@/modules/iam/api/platformIam', () => ({
+  createPlatformRole: vi.fn(),
+  listPlatformPermissions: vi.fn(),
+  listPlatformRoles: vi.fn(),
+  updatePlatformRole: vi.fn(),
+  changePlatformRoleStatus: vi.fn(),
+  deletePlatformRole: vi.fn(),
+  replacePlatformRolePermissions: vi.fn(),
+}))
+
+const platformRole: PlatformRoleResource = {
+  id: 4000002,
+  tenantId: 0,
+  appCode: 'PLATFORM',
+  roleCode: 'CUSTOMER_REVIEWER',
+  roleName: '企业审核员',
+  roleType: 'SYSTEM',
+  status: 'ACTIVE',
+  description: '企业资料与入驻审核',
+  memberCount: 3,
+}
+
+function mountView(pinia = createPinia()) {
+  setActivePinia(pinia)
+  const auth = useAuthStore()
+  if (auth.permissions.length === 0) auth.permissions = ['platform:role:list', 'platform:role:create', 'platform:role:grant']
+  return shallowMount(RolesView, {
+    global: {
+      plugins: [pinia],
+      directives: { loading: () => undefined },
+      stubs: {
+        AdminPage: { template: '<main><slot /></main>' },
+        ListPageLayout: { template: '<section><slot name="toolbar" /><slot name="state" /><slot /></section>' },
+        FormSection: { template: '<section><slot /></section>' },
+        AppDialog: { template: '<section><slot /><slot name="footer" /></section>' },
+        LoadErrorState: { props: ['message'], template: '<div role="alert">{{ message }}<slot name="details" /></div>' },
+        DataTable: { props: ['data'], template: '<section><slot name="toolbar-actions" /><span data-testid="row-count">{{ data.length }}</span></section>' },
+        'el-alert': { props: ['title'], template: '<div role="alert">{{ title }}<slot name="title" /></div>' },
+        'el-input': true,
+        'el-option': true,
+        'el-select': true,
+        'el-button': true,
+        'el-table': true,
+        'el-table-column': true,
+        'el-tag': true,
+        'el-radio-group': true,
+        'el-radio-button': true,
+        'el-drawer': {
+          props: ['modelValue'],
+          template: '<section><slot /><slot name="footer" /></section>',
+        },
+        'el-form': { template: '<form><slot /></form>' },
+        'el-form-item': { template: '<label><slot /></label>' },
+        'el-tree': {
+          props: { checkStrictly: Boolean },
+          template: '<div data-testid="permission-tree" :data-check-strictly="String(checkStrictly)" />',
+        },
+      },
+    },
+  })
+}
+
+describe('RolesView', () => {
+  it('keeps the shared status badge prop defined during table slot initialization', () => {
+    expect(rolesSource).toContain("(row as Role).status || '—'")
+  })
+  it('uses bordered striped tables and semantic role operation buttons', () => {
+    expect(rolesSource).toContain('border stripe')
+    expect(rolesSource).toContain('size="small" data-tone="neutral"')
+    expect(rolesSource).toContain('size="small" :data-tone=')
+    expect(rolesSource).toContain('size="small" data-tone="danger"')
+    expect(rolesSource).toContain('>配置</el-button>')
+    expect(rolesSource).toContain(':data-tone=')
+    expect(rolesSource).toContain('>删除</el-button>')
+    expect(rolesSource).toContain('@media (max-width: 720px)')
+  })
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    vi.mocked(listPlatformRoles).mockReset()
+    vi.mocked(listPlatformPermissions).mockReset()
+    vi.mocked(listPlatformPermissions).mockResolvedValue([])
+    vi.mocked(createPlatformRole).mockReset()
+  })
+
+  it('links menu groups and permissions so partial selections use the half-checked state', () => {
+    const wrapper = mountView()
+
+    expect(wrapper.get('[data-testid="permission-tree"]').attributes('data-check-strictly')).toBe('false')
+    expect(rolesSource).not.toContain('check-strictly')
+    expect(rolesSource).not.toContain("disabled: 'disabled'")
+  })
+
+  it('restores saved permission ids after the dialog tree has mounted', () => {
+    expect(rolesSource).toContain('@opened="initializePermissionSelection"')
+    expect(rolesSource).toContain('treeRef.value?.setCheckedKeys([...form.permissionIds])')
+    expect(rolesSource).not.toContain('nextTick(() =>')
+  })
+
+  it('shows the role code in the default list layout', () => {
+    expect(rolesSource).toContain("{ key: 'roleCode', prop: 'code', label: '角色编码', minWidth: 180, showOverflowTooltip: true }")
+    expect(rolesSource).toContain('<el-form-item label="角色编码"')
+    expect(rolesSource).not.toContain('<small>{{ (row as Role).code }}</small>')
+    expect(rolesSource).toContain('aria-label="平台角色列表"')
+  })
+
+  it('uses the prototype-sized centered role editor with responsive split panes', () => {
+    expect(rolesSource).toContain('<AppDialog v-model="editorOpen"')
+    expect(rolesSource).toContain('width="min(860px, calc(100vw - 28px))"')
+    expect(rolesSource).not.toContain('<AppDrawer v-model="editorOpen"')
+    expect(rolesSource).toContain('grid-template-columns: minmax(0, 0.9fr) minmax(0, 1.3fr)')
+    expect(rolesSource).toContain('.role-editor-layout { grid-template-columns: minmax(0, 1fr); }')
+    expect(rolesSource).toContain(':global(.role-editor-dialog .el-dialog__body) { min-height: 0; overflow-y: auto; }')
+  })
+
+  it('loads platform roles from IAM for a server session', async () => {
+    const pinia = createPinia()
+    setActivePinia(pinia)
+    const auth = useAuthStore()
+    auth.isServerSession = true
+    auth.permissions = ['platform:role:list', 'platform:role:create']
+    vi.mocked(listPlatformRoles).mockResolvedValue([platformRole])
+
+    const wrapper = mountView(pinia)
+    await flushPromises()
+
+    expect(listPlatformRoles).toHaveBeenCalledTimes(1)
+    expect(rolesSource).toContain('userCount: role.memberCount')
+    expect(rolesSource).not.toContain('listPlatformInternalUsers')
+    expect(wrapper.get('[data-testid="row-count"]').text()).toBe('1')
+    expect(wrapper.text()).not.toContain('角色负责聚合菜单、操作和数据范围，内部用户可分配多个角色')
+    expect(wrapper.find('[data-testid="permission-tree"]').exists()).toBe(false)
+  })
+
+  it('keeps a failed IAM role list recoverable', async () => {
+    const pinia = createPinia()
+    setActivePinia(pinia)
+    const auth = useAuthStore()
+    auth.isServerSession = true
+    auth.permissions = ['platform:role:list']
+    vi.mocked(listPlatformRoles).mockRejectedValue(new Error('IAM unavailable'))
+
+    const wrapper = mountView(pinia)
+    await flushPromises()
+
+    const alertText = wrapper.findAll('[role="alert"]').map((item) => item.text()).join(' ')
+    expect(alertText).toContain('平台角色列表加载失败，请稍后重试')
+    expect(alertText).not.toContain('IAM unavailable')
+  })
+})
diff --git a/src/modules/iam/pages/RolesView.vue b/src/modules/iam/pages/RolesView.vue
new file mode 100644
index 00000000..3300bfad
--- /dev/null
+++ b/src/modules/iam/pages/RolesView.vue
@@ -0,0 +1,291 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import '../iamDensity.css'
+import { computed, onMounted, reactive, ref } from 'vue'
+import { ElMessage, ElMessageBox, type FormInstance, type FormRules } from 'element-plus'
+import { Plus, ShieldCheck } from '@lucide/vue'
+import {
+  changePlatformRoleStatus,
+  createPlatformRole,
+  deletePlatformRole,
+  listPlatformPermissions,
+  listPlatformRoles,
+  replacePlatformRolePermissions,
+  updatePlatformRole,
+  type PlatformRoleResource,
+} from '@/modules/iam/api/platformIam'
+import { getApiErrorDetails, getApiErrorMessage, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import FormSection from '@/shared/components/FormSection.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { useUnsavedWorkRegistration } from '@/core/unsaved-work/useUnsavedWorkRegistration'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { adminNavigation } from '@/core/navigation/adminNavigation'
+import type { Permission, Role } from '@/modules/iam/types'
+import { buildNavigationPermissionTree, summarizePermissionSelection } from '@/modules/iam/utils/permissionTree'
+import { mapPlatformPermission } from '@/modules/iam/utils/platformPermission'
+
+interface TreeController {
+  getCheckedKeys: (leafOnly?: boolean) => Array<string | number>
+  getHalfCheckedKeys: () => Array<string | number>
+  setCheckedKeys: (keys: string[]) => void
+}
+
+const access = useAccessPreviewStore()
+const editorOpen = ref(false)
+const formRef = ref<FormInstance>()
+const treeRef = ref<TreeController | null>(null)
+const serverRoles = ref<Role[]>([])
+const serverPermissions = ref<Permission[]>([])
+const loading = ref(false)
+const saving = ref(false)
+const rowActionId = ref('')
+const loadError = ref<ApiErrorDetails | null>(null)
+const page = ref(1)
+const pageSize = ref(10)
+type RoleFilters = QueryModel & { keyword: string; status: string }
+const filters = ref<RoleFilters>({ keyword: '', status: '' })
+const appliedFilters = ref<RoleFilters>({ ...filters.value })
+const queryFields: QueryField[] = [
+  { key: 'keyword', type: 'input', label: '角色关键词', placeholder: '角色名称、编码或描述' },
+  { key: 'status', type: 'select', label: '状态', placeholder: '全部状态', options: [{ label: '启用', value: '启用' }, { label: '停用', value: '停用' }] },
+]
+const emptyForm = (): Omit<Role, 'userCount'> => ({ id: '', name: '', code: '', description: '', dataScope: '本部门数据', status: '启用', permissionIds: [], builtIn: false })
+const form = reactive(emptyForm())
+const formRules: FormRules = {
+  name: [{ required: true, whitespace: true, message: '请输入角色名称', trigger: 'blur' }],
+  code: [{ required: true, whitespace: true, message: '请输入角色编码', trigger: 'blur' }],
+}
+const editorLabel = computed(() => form.id ? '配置角色' : '新增角色')
+const canEdit = computed(() => access.can('platform:role:edit'))
+const canGrant = computed(() => access.can('platform:role:grant'))
+const requiredPermission = computed(() => form.id && canEdit.value ? 'platform:role:edit' : form.id ? 'platform:role:grant' : 'platform:role:create')
+const { captureBaseline } = useUnsavedWorkRegistration({
+  key: 'role-editor',
+  label: editorLabel,
+  isOpen: editorOpen,
+  model: form,
+  requiredPermission,
+})
+const roles = computed(() => serverRoles.value)
+const canCreate = computed(() => access.can('platform:role:create'))
+const filteredRows = computed(() => roles.value.filter((item) => {
+  const keyword = appliedFilters.value.keyword.trim().toLowerCase()
+  return (!keyword || [item.name, item.code, item.description].some((value) => value.toLowerCase().includes(keyword))) && (!appliedFilters.value.status || item.status === appliedFilters.value.status)
+}))
+const pagedRows = computed(() => filteredRows.value.slice((page.value - 1) * pageSize.value, page.value * pageSize.value))
+const roleColumns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 250, fixed: 'left', slotName: 'actions' },
+  { key: 'role', label: '角色名称', minWidth: 180, slotName: 'role' },
+  { key: 'roleCode', prop: 'code', label: '角色编码', minWidth: 180, showOverflowTooltip: true },
+  { key: 'description', prop: 'description', label: '说明', minWidth: 240, showOverflowTooltip: true },
+  { key: 'permissionSummary', label: '授权范围', minWidth: 170, slotName: 'permissionSummary' },
+  { key: 'userCount', prop: 'userCount', label: '用户数', width: 86, align: 'right' },
+  { key: 'roleType', label: '类型', width: 95, slotName: 'roleType' },
+  { key: 'status', label: '状态', width: 88, slotName: 'status' },
+]
+const availablePermissions = computed(() => serverPermissions.value)
+const permissionTree = computed(() => buildNavigationPermissionTree(availablePermissions.value, adminNavigation))
+const permissionGroupIds = computed(() => permissionTree.value.map((node) => node.id))
+const assignablePermissionIds = computed(() => new Set(availablePermissions.value.map((permission) => permission.id)))
+
+function applyFilters() {
+  appliedFilters.value = { ...filters.value }
+  page.value = 1
+  void loadRoles()
+}
+
+function mapPlatformRole(role: PlatformRoleResource): Role {
+  return {
+    id: String(role.id),
+    name: role.roleName,
+    code: role.roleCode,
+    description: role.description ?? '暂无角色说明',
+    userCount: role.memberCount,
+    dataScope: '全部数据',
+    status: role.status === 'ACTIVE' ? '启用' : '停用',
+    permissionIds: (role.permissionIds ?? []).map(String),
+    builtIn: role.roleType === 'SYSTEM',
+  }
+}
+
+async function loadRoles() {
+  loading.value = true
+  loadError.value = null
+  serverRoles.value = []
+  serverPermissions.value = []
+  try {
+    const [roleRecords, permissionRecords] = await Promise.all([
+      listPlatformRoles(),
+      listPlatformPermissions(),
+    ])
+    serverPermissions.value = permissionRecords.map(mapPlatformPermission)
+    serverRoles.value = roleRecords.map(mapPlatformRole)
+  } catch (error) {
+    loadError.value = getApiErrorDetails(error, '平台角色列表加载失败，请稍后重试')
+  } finally {
+    loading.value = false
+  }
+}
+
+function openCreate() {
+  Object.assign(form, emptyForm())
+  captureBaseline()
+  editorOpen.value = true
+}
+function openEdit(row: Role) {
+  if (!canEdit.value && !canGrant.value) return
+  Object.assign(form, { ...row, permissionIds: [...row.permissionIds] })
+  captureBaseline()
+  editorOpen.value = true
+}
+
+function initializePermissionSelection() {
+  formRef.value?.clearValidate()
+  treeRef.value?.setCheckedKeys([...form.permissionIds])
+}
+
+function selectedPermissionIds() {
+  const checked = treeRef.value?.getCheckedKeys(false).map(String).filter((id) => assignablePermissionIds.value.has(id)) || []
+  const halfChecked = treeRef.value?.getHalfCheckedKeys().map(String).filter((id) => assignablePermissionIds.value.has(id)) || []
+  return [...new Set([...checked, ...halfChecked])]
+}
+
+function syncPermissionIds() {
+  form.permissionIds = selectedPermissionIds()
+}
+
+async function saveRole() {
+  const valid = await formRef.value?.validate().catch(() => false)
+  if (!valid) return
+  const normalizedCode = form.code.trim().toUpperCase()
+  const duplicate = roles.value.some((item) => item.code.toLowerCase() === normalizedCode.toLowerCase() && item.id !== form.id)
+  if (duplicate) { ElMessage.error('角色编码已经存在'); return }
+  saving.value = true
+  try {
+      const permissionIds = selectedPermissionIds()
+      if (form.id) {
+        if (canEdit.value) {
+          await updatePlatformRole(form.id, { roleName: form.name.trim(), description: form.description.trim() })
+        }
+        if (canGrant.value) await replacePlatformRolePermissions(form.id, permissionIds)
+      } else {
+        const created = await createPlatformRole({
+          roleCode: normalizedCode,
+          roleName: form.name.trim(),
+          description: form.description.trim(),
+        })
+        if (canGrant.value && permissionIds.length > 0) await replacePlatformRolePermissions(created.id, permissionIds)
+      }
+      await loadRoles()
+      editorOpen.value = false
+      ElMessage.success(form.id ? '角色已更新' : '角色已创建')
+  } catch (error) {
+    ElMessage.error(getApiErrorMessage(error, '角色保存失败，请稍后重试'))
+  } finally {
+    saving.value = false
+  }
+}
+
+async function removeRole(row: Role) {
+  if (row.builtIn) { ElMessage.warning('系统内置角色不能删除'); return }
+  if (row.userCount > 0) { ElMessage.warning('请先移除该角色下的用户'); return }
+  try {
+    await ElMessageBox.confirm(`确认删除角色“${row.name}”吗？`, '删除角色', { customClass: 'admin-density-confirm',  confirmButtonText: '删除', cancelButtonText: '取消', type: 'warning' })
+    rowActionId.value = row.id
+    await deletePlatformRole(row.id)
+    serverRoles.value = serverRoles.value.filter((item) => item.id !== row.id)
+    ElMessage.success('角色已删除')
+  } catch (error) {
+    if (error === 'cancel' || error === 'close') return
+    ElMessage.error(getApiErrorMessage(error, '角色删除失败，请稍后重试'))
+  } finally {
+    rowActionId.value = ''
+  }
+}
+
+async function toggleStatus(row: Role) {
+  if (row.builtIn) { ElMessage.warning('系统内置角色不能停用'); return }
+  const target = row.status === '启用' ? '停用' : '启用'
+  try {
+    await ElMessageBox.confirm(`确认${target}角色“${row.name}”吗？`, '角色状态', { customClass: 'admin-density-confirm',  confirmButtonText: '确认', cancelButtonText: '取消' })
+    rowActionId.value = row.id
+    const updated = await changePlatformRoleStatus(row.id, target === '启用' ? 'ACTIVE' : 'DISABLED')
+    Object.assign(row, mapPlatformRole(updated))
+    ElMessage.success(`角色已${target}`)
+  } catch (error) {
+    if (error === 'cancel' || error === 'close') return
+    ElMessage.error(getApiErrorMessage(error, '角色状态更新失败，请稍后重试'))
+  } finally {
+    rowActionId.value = ''
+  }
+}
+
+function permissionSummary(row: Role) {
+  const { menuCount, actionCount } = summarizePermissionSelection(availablePermissions.value, row.permissionIds)
+  return `${menuCount} 菜单 · ${actionCount} 操作`
+}
+
+onMounted(loadRoles)
+</script>
+
+<template>
+  <AdminPage class="admin-density iam-density" as="div">
+    <ListPageLayout aria-label="平台角色管理">
+      <template #toolbar><QueryToolbar v-model="filters" class="surface-panel" ariaLabel="角色筛选" :fields="queryFields" preference-key="roles-query" @search="applyFilters" /></template>
+      <template v-if="loadError" #state>
+        <LoadErrorState title="角色列表暂时无法加载" :message="loadError.message" :loading="loading" @retry="loadRoles">
+          <template #details><ApiErrorMeta :details="loadError" /></template>
+        </LoadErrorState>
+      </template>
+
+      <section v-if="!loadError" class="surface-panel table-panel">
+      <DataTable v-model:page="page" v-model:page-size="pageSize" :data="pagedRows" :columns="roleColumns" preference-key="roles-table" :loading="loading" :total="filteredRows.length" row-key="id" border stripe aria-label="平台角色列表" empty-text="没有符合条件的角色">
+        <template #toolbar-actions><el-button v-if="canCreate" type="primary" @click="openCreate"><Plus :size="16" />新增角色</el-button></template>
+        <template #actions="{ row }"><div v-if="canEdit || canGrant || access.can('platform:role:status') || access.can('platform:role:delete')" class="table-actions density-actions"><el-button class="density-action" v-if="canEdit || canGrant" size="small" data-tone="neutral" :disabled="rowActionId === (row as Role).id || (row as Role).builtIn" @click="openEdit(row as Role)">配置</el-button><el-button class="density-action" v-if="access.can('platform:role:status')" size="small" :data-tone="(row as Role).status === '启用' ? 'danger' : 'success'" :loading="rowActionId === (row as Role).id" :disabled="(row as Role).builtIn" @click="toggleStatus(row as Role)">{{ (row as Role).status === '启用' ? '停用' : '启用' }}</el-button><el-button class="density-action" v-if="access.can('platform:role:delete')" size="small" data-tone="danger" :disabled="(row as Role).builtIn || (row as Role).userCount > 0 || rowActionId === (row as Role).id" @click="removeRole(row as Role)">删除</el-button></div><span v-else class="secondary-text">仅查看</span></template>
+        <template #role="{ row }"><div class="role-cell"><span><ShieldCheck :size="18" /></span><div><strong>{{ (row as Role).name }}</strong></div></div></template>
+        <template #permissionSummary="{ row }"><div class="primary-cell"><strong>{{ permissionSummary(row as Role) }}</strong><span>平台 IAM 权限</span></div></template>
+        <template #roleType="{ row }"><el-tag :type="(row as Role).builtIn ? 'warning' : 'info'" effect="plain" size="small">{{ (row as Role).builtIn ? '系统内置' : '自定义' }}</el-tag></template>
+        <template #status="{ row }"><StatusBadge :status="(row as Role).status || '—'" /></template>
+        <template #pagination-left="{ total: tableTotal }"><span>共 {{ tableTotal }} 条</span></template>
+      </DataTable>
+      </section>
+    </ListPageLayout>
+
+    <AppDialog v-model="editorOpen" :title="form.id ? '配置角色' : '新增角色'" width="min(860px, calc(100vw - 28px))" class="role-editor-dialog admin-density-dialog iam-density" :confirm-loading="saving" confirm-text="保存角色" :show-confirm="form.id ? canEdit || canGrant : canCreate" destroy-on-close @opened="initializePermissionSelection" @confirm="saveRole">
+      <el-form ref="formRef" :model="form" :rules="formRules" label-position="top" class="role-editor-form density-form">
+        <div class="role-editor-layout">
+          <FormSection title="基本信息" description="维护角色名称、编码和职责说明。" class="role-editor-basic density-form-section">
+            <el-form-item label="角色名称" prop="name" required><el-input v-model="form.name" :disabled="Boolean(form.id) && !canEdit" placeholder="如：订单运营专员" maxlength="64" /></el-form-item>
+            <el-form-item label="角色编码" prop="code" required><el-input v-model="form.code" :disabled="Boolean(form.id)" placeholder="如：ORDER_OPERATOR" maxlength="64" /></el-form-item>
+            <el-form-item label="角色说明"><el-input v-model="form.description" :disabled="Boolean(form.id) && !canEdit" type="textarea" :rows="3" placeholder="说明该角色的工作范围" maxlength="200" show-word-limit /></el-form-item>
+          </FormSection>
+          <FormSection v-if="canGrant" title="菜单与操作权限" :description="`按当前后台菜单分组；勾选上级可全选下级，部分选中时显示半选，当前 ${form.permissionIds.length} 项授权。`" class="role-editor-permissions density-form-section"><el-tree ref="treeRef" class="permission-tree" :data="permissionTree" node-key="id" show-checkbox :default-expanded-keys="permissionGroupIds" :props="{ label: 'name', children: 'children' }" @check="syncPermissionIds"><template #default="{ data }"><div class="permission-node" :class="{ 'is-navigation-group': !data.permissionId }"><span>{{ data.name }}</span><code v-if="data.code">{{ data.code }}</code></div></template></el-tree></FormSection>
+        </div>
+      </el-form>
+    </AppDialog>
+  </AdminPage>
+</template>
+
+<style scoped>
+.role-editor-layout { display: grid; grid-template-columns: minmax(0, 0.9fr) minmax(0, 1.3fr); gap: var(--admin-space-5); }
+.role-editor-layout:not(:has(.role-editor-permissions)) { grid-template-columns: minmax(0, 1fr); }
+.role-editor-layout > .role-editor-permissions.density-form-section { min-width: 0; padding: 0 0 0 var(--admin-space-5); border-left: 1px solid var(--cc-border); }
+.permission-tree { max-height: 380px; overflow-x: hidden; overflow-y: auto; }
+.permission-node span { min-width: 0; }
+.permission-node code { max-width: 58%; white-space: normal; text-align: right; }
+.permission-node.is-navigation-group span { font-weight: 650; }
+:global(.role-editor-dialog) { max-height: min(760px, calc(100vh - 32px)); display: flex; flex-direction: column; }
+:global(.role-editor-dialog .el-dialog__body) { min-height: 0; overflow-y: auto; }
+:global(.role-editor-dialog .el-dialog__footer) { flex: 0 0 auto; }
+@media (max-width: 720px) {
+  .role-editor-layout { grid-template-columns: minmax(0, 1fr); }
+  .role-editor-layout > .role-editor-permissions.density-form-section { padding-top: 18px; padding-left: 0; border-top: 1px solid var(--cc-border); border-left: 0; }
+}
+</style>
diff --git a/src/modules/iam/routes.ts b/src/modules/iam/routes.ts
new file mode 100644
index 00000000..69abd941
--- /dev/null
+++ b/src/modules/iam/routes.ts
@@ -0,0 +1,22 @@
+import type { RouteRecordRaw } from 'vue-router'
+
+export const iamRoutes = [
+  {
+    path: 'system/users',
+    name: 'users',
+    component: () => import('@/modules/iam/pages/InternalUsersView.vue'),
+    meta: { title: '用户管理', description: '统一管理平台内部用户、状态及角色', permission: 'platform:user:list' },
+  },
+  {
+    path: 'system/roles',
+    name: 'roles',
+    component: () => import('@/modules/iam/pages/RolesView.vue'),
+    meta: { title: '角色权限', description: '维护平台角色并配置菜单及操作权限', permission: 'platform:role:list' },
+  },
+  {
+    path: 'system/permissions',
+    name: 'permissions',
+    component: () => import('@/modules/iam/pages/PermissionsView.vue'),
+    meta: { title: '菜单权限', description: '维护菜单、页面、按钮和接口权限编码', permission: 'platform:permission:list' },
+  },
+] satisfies RouteRecordRaw[]
diff --git a/src/modules/iam/types.ts b/src/modules/iam/types.ts
new file mode 100644
index 00000000..4f1cb62b
--- /dev/null
+++ b/src/modules/iam/types.ts
@@ -0,0 +1,42 @@
+export type RecordStatus = '正常' | '停用'
+export type RoleStatus = '启用' | '停用'
+export type PermissionType = '目录' | '菜单' | '页面' | '按钮' | '接口'
+export type DataScope = '全部数据' | '本部门数据' | '本人数据' | '自定义'
+
+export interface InternalUser {
+  id: string
+  account: string
+  name: string
+  department: string
+  phone: string
+  email: string
+  roleIds: string[]
+  status: RecordStatus
+  lastLogin: string
+  createdAt: string
+}
+
+export interface Role {
+  id: string
+  name: string
+  code: string
+  description: string
+  userCount: number
+  dataScope: DataScope
+  status: RoleStatus
+  permissionIds: string[]
+  builtIn?: boolean
+}
+
+export interface Permission {
+  id: string
+  parentId: string | null
+  name: string
+  code: string
+  type: PermissionType
+  path: string
+  method: string
+  status: RoleStatus
+  sort: number
+  builtIn?: boolean
+}
diff --git a/src/utils/permissionTree.test.ts b/src/modules/iam/utils/permissionTree.test.ts
similarity index 56%
rename from src/utils/permissionTree.test.ts
rename to src/modules/iam/utils/permissionTree.test.ts
index 5bb5c978..be1c9e5a 100644
--- a/src/utils/permissionTree.test.ts
+++ b/src/modules/iam/utils/permissionTree.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest'
-import type { Permission } from '@/types/admin'
-import { buildPermissionTree, getDescendantIds, summarizePermissionSelection } from '@/utils/permissionTree'
+import type { Permission } from '@/modules/iam/types'
+import { buildNavigationPermissionTree, buildPermissionTree, getDescendantIds, summarizePermissionSelection } from '@/modules/iam/utils/permissionTree'
+import { adminNavigation } from '@/core/navigation/adminNavigation'
 
 const permissions: Permission[] = [
   { id: 'action-b', parentId: 'menu', name: '操作 B', code: 'demo:b', type: '按钮', path: '', method: '-', status: '启用', sort: 20 },
@@ -52,4 +53,24 @@ describe('permissionTree', () => {
       actionCount: 1,
     })
   })
+
+  it('groups assignable permissions by the current admin navigation and hides technical containers', () => {
+    const rolePermissions: Permission[] = [
+      { id: 'supplier', parentId: null, name: '供应商旧名称', code: 'platform:supplier:list', type: '菜单', path: '/suppliers', method: 'GET', status: '启用', sort: 10 },
+      { id: 'supplier-create', parentId: 'supplier', name: '新增供应商', code: 'platform:supplier:create', type: '按钮', path: '', method: 'POST', status: '启用', sort: 10 },
+      { id: 'express', parentId: null, name: '快递公司', code: 'platform:express:list', type: '菜单', path: '/master-data/express-companies', method: 'GET', status: '启用', sort: 20 },
+      { id: 'counterparty', parentId: null, name: '往来单位', code: 'platform:counterparty:list', type: '菜单', path: '/master-data/counterparties', method: 'GET', status: '启用', sort: 30 },
+      { id: 'technical', parentId: null, name: '服务接口', code: 'platform:technical:invoke', type: '接口', path: '/internal', method: 'POST', status: '启用', sort: 40 },
+    ]
+
+    const tree = buildNavigationPermissionTree(rolePermissions, adminNavigation)
+    const general = tree.find((node) => node.name === '通用')
+
+    expect(tree.some((node) => node.name === '供应商中心')).toBe(false)
+    expect(general?.permissionId).toBeUndefined()
+    expect(general?.children?.map((node) => node.name)).toEqual(['供应商列表', '快递公司', '往来单位'])
+    expect(general?.children?.[0]?.children?.map((node) => node.name)).toEqual(['供应商旧名称', '新增供应商'])
+    expect(tree.some((node) => node.name === '其他权限')).toBe(false)
+    expect(JSON.stringify(tree)).not.toContain('platform:technical:invoke')
+  })
 })
diff --git a/src/modules/iam/utils/permissionTree.ts b/src/modules/iam/utils/permissionTree.ts
new file mode 100644
index 00000000..03853b1d
--- /dev/null
+++ b/src/modules/iam/utils/permissionTree.ts
@@ -0,0 +1,141 @@
+import type { Permission } from '@/modules/iam/types'
+import type { AdminNavigationNode } from '@/core/navigation/adminNavigation'
+
+export type PermissionTreeNode = Permission & { children?: PermissionTreeNode[] }
+export type PermissionMatcher = (permission: Permission) => boolean
+export interface RolePermissionTreeNode {
+  id: string
+  permissionId?: string
+  name: string
+  code: string
+  children?: RolePermissionTreeNode[]
+}
+
+function groupByParent(permissions: Permission[]) {
+  const childrenByParent = new Map<string | null, Permission[]>()
+
+  permissions.forEach((permission) => {
+    const siblings = childrenByParent.get(permission.parentId) ?? []
+    siblings.push(permission)
+    childrenByParent.set(permission.parentId, siblings)
+  })
+
+  childrenByParent.forEach((siblings) => {
+    siblings.sort((left, right) => left.sort - right.sort)
+  })
+
+  return childrenByParent
+}
+
+export function buildPermissionTree(
+  permissions: Permission[],
+  matches: PermissionMatcher = () => true,
+): PermissionTreeNode[] {
+  const childrenByParent = groupByParent(permissions)
+
+  function buildNode(permission: Permission, ancestors: Set<string>): PermissionTreeNode | null {
+    if (ancestors.has(permission.id)) return null
+
+    const nextAncestors = new Set(ancestors).add(permission.id)
+    const children = (childrenByParent.get(permission.id) ?? [])
+      .map((child) => buildNode(child, nextAncestors))
+      .filter((child): child is PermissionTreeNode => child !== null)
+
+    if (!matches(permission) && children.length === 0) return null
+
+    return {
+      ...permission,
+      ...(children.length ? { children } : {}),
+    }
+  }
+
+  return (childrenByParent.get(null) ?? [])
+    .map((permission) => buildNode(permission, new Set()))
+    .filter((node): node is PermissionTreeNode => node !== null)
+}
+
+export function getDescendantIds(permissions: Permission[], permissionId: string): string[] {
+  const childrenByParent = groupByParent(permissions)
+  const visited = new Set([permissionId])
+  const descendants: string[] = []
+  const queue = [...(childrenByParent.get(permissionId) ?? [])]
+
+  while (queue.length) {
+    const current = queue.shift()
+    if (!current || visited.has(current.id)) continue
+
+    visited.add(current.id)
+    descendants.push(current.id)
+    queue.push(...(childrenByParent.get(current.id) ?? []))
+  }
+
+  return descendants
+}
+
+export function summarizePermissionSelection(permissions: Permission[], selectedIds: string[]) {
+  const selected = new Set(selectedIds)
+  const selectedPermissions = permissions.filter((permission) => selected.has(permission.id))
+
+  return {
+    menuCount: selectedPermissions.filter((permission) => ['菜单', '页面'].includes(permission.type)).length,
+    actionCount: selectedPermissions.filter((permission) => ['按钮', '接口'].includes(permission.type)).length,
+  }
+}
+
+export function buildNavigationPermissionTree(
+  permissions: Permission[],
+  navigation: AdminNavigationNode[],
+): RolePermissionTreeNode[] {
+  const childrenByParent = groupByParent(permissions)
+  const permissionByCode = new Map(permissions.map((permission) => [permission.code, permission]))
+  const usedPermissionIds = new Set<string>()
+
+  function permissionLeaves(permission: Permission, ancestors: Set<string>): RolePermissionTreeNode[] {
+    if (ancestors.has(permission.id)) return []
+
+    usedPermissionIds.add(permission.id)
+    const nextAncestors = new Set(ancestors).add(permission.id)
+    const children = (childrenByParent.get(permission.id) ?? [])
+      .flatMap((child) => permissionLeaves(child, nextAncestors))
+
+    return [{ id: permission.id, permissionId: permission.id, name: permission.name, code: permission.code }, ...children]
+  }
+
+  function navigationNode(node: AdminNavigationNode): RolePermissionTreeNode | null {
+    if (node.hidden) return null
+
+    if (node.children?.length) {
+      const children = node.children
+        .map(navigationNode)
+        .filter((child): child is RolePermissionTreeNode => child !== null)
+      if (!children.length) return null
+      return {
+        id: `navigation-group:${node.key}`,
+        name: node.title,
+        code: '',
+        children,
+      }
+    }
+
+    const codes = [...new Set([node.permission, ...(node.permissionAnyOf ?? [])].filter(Boolean))] as string[]
+    const permissionNodes = codes
+      .map((code) => permissionByCode.get(code))
+      .filter((permission): permission is Permission => permission !== undefined)
+      .flatMap((permission) => usedPermissionIds.has(permission.id) ? [] : permissionLeaves(permission, new Set()))
+
+    if (permissionNodes.length) {
+      return {
+        id: `navigation-menu:${node.key}`,
+        name: node.title,
+        code: '',
+        children: permissionNodes,
+      }
+    }
+    return null
+  }
+
+  const navigationGroups = navigation
+    .map(navigationNode)
+    .filter((node): node is RolePermissionTreeNode => node !== null)
+  return navigationGroups
+}
diff --git a/src/modules/iam/utils/platformPermission.test.ts b/src/modules/iam/utils/platformPermission.test.ts
new file mode 100644
index 00000000..fb3e9d47
--- /dev/null
+++ b/src/modules/iam/utils/platformPermission.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest'
+import { mapPlatformPermission } from '@/modules/iam/utils/platformPermission'
+
+describe('mapPlatformPermission', () => {
+  it('treats the string root parent as a root node and preserves long ids', () => {
+    expect(mapPlatformPermission({
+      id: '2082813911786024961',
+      tenantId: '0',
+      appCode: 'PLATFORM',
+      permissionType: 'MENU',
+      parentId: '0',
+      permissionCode: 'platform:audit',
+      permissionName: '审计管理',
+      routePath: '/audit',
+      httpMethod: null,
+      sortNo: 50,
+      status: 'ACTIVE',
+    })).toMatchObject({ id: '2082813911786024961', parentId: null, code: 'platform:audit' })
+  })
+
+  it('preserves a long string parent id for child resources', () => {
+    expect(mapPlatformPermission({
+      id: '2082813911786024962',
+      tenantId: '0',
+      appCode: 'PLATFORM',
+      permissionType: 'BUTTON',
+      parentId: '2082813911786024961',
+      permissionCode: 'platform:audit:list',
+      permissionName: '操作日志',
+      routePath: null,
+      httpMethod: null,
+      sortNo: 10,
+      status: 'ACTIVE',
+    })).toMatchObject({ id: '2082813911786024962', parentId: '2082813911786024961', type: '按钮' })
+  })
+
+  it.each([
+    ['MENU', '菜单'],
+    ['PAGE', '页面'],
+    ['BUTTON', '按钮'],
+    ['API', '接口'],
+  ] as const)('maps backend permission type %s without collapsing it', (permissionType, type) => {
+    expect(mapPlatformPermission({
+      id: '1', tenantId: '0', appCode: 'PLATFORM', permissionType, parentId: '0',
+      permissionCode: `platform:test:${permissionType.toLowerCase()}`, permissionName: type,
+      routePath: null, httpMethod: permissionType === 'API' ? 'GET' : null,
+      sortNo: 10, status: 'ACTIVE',
+    })).toMatchObject({ type })
+  })
+})
diff --git a/src/modules/iam/utils/platformPermission.ts b/src/modules/iam/utils/platformPermission.ts
new file mode 100644
index 00000000..e8d4084e
--- /dev/null
+++ b/src/modules/iam/utils/platformPermission.ts
@@ -0,0 +1,18 @@
+import type { PlatformPermissionResource } from '@/modules/iam/api/platformIam'
+import type { Permission } from '@/modules/iam/types'
+
+export function mapPlatformPermission(item: PlatformPermissionResource): Permission {
+  const parentId = String(item.parentId)
+  return {
+    id: String(item.id),
+    parentId: parentId === '0' ? null : parentId,
+    name: item.permissionName,
+    code: item.permissionCode,
+    type: ({ MENU: '菜单', PAGE: '页面', BUTTON: '按钮', API: '接口' } as const)[item.permissionType],
+    path: item.routePath ?? '',
+    method: item.httpMethod ?? '-',
+    status: item.status === 'ACTIVE' ? '启用' : '停用',
+    sort: item.sortNo,
+    builtIn: Boolean(item.builtIn),
+  }
+}
diff --git a/src/modules/inbounds/components/InboundTaskList.test.ts b/src/modules/inbounds/components/InboundTaskList.test.ts
new file mode 100644
index 00000000..8ebeb2d2
--- /dev/null
+++ b/src/modules/inbounds/components/InboundTaskList.test.ts
@@ -0,0 +1,194 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import type { PlatformTenantResource } from '@/modules/iam'
+import { loadAllActiveCustomers } from '../task-list'
+
+function activeCustomer(id: string, tenantName: string, legalName: string | null, tenantCode: string): PlatformTenantResource {
+  return {
+    id, tenantName, legalName, tenantCode, status: 'ACTIVE', legalRepresentative: null,
+    unifiedSocialCreditCode: null, contactName: null, contactPhone: null, contactEmail: null,
+    servicePackage: null, contactWechat: null, salesOwnerName: null, paymentTermDays: null,
+    enterpriseType: null, establishedDate: null, registeredCapital: null,
+    registeredCapitalCurrency: null, registeredAddress: null, internalRemark: null,
+    createdAt: null, approvedAt: null,
+  }
+}
+
+describe('InboundTaskList measurement scope', () => {
+  it('supports selecting only pending measurement reviews for batch approval', () => {
+    const source = readFileSync(resolve('src/modules/inbounds/components/InboundTaskList.vue'), 'utf8')
+
+    expect(source).toContain("key: 'selection', type: 'selection'")
+    expect(source).toContain("row.measureReviewStatus === 'PENDING'")
+    expect(source).toContain('@selection-change="handleReviewSelectionChange"')
+    expect(source).toContain('batchApproveMeasurements')
+    expect(source).toContain('批量审核通过')
+    expect(source).toContain('getMeasurementReviewDetail')
+    expect(source).toContain('approveMeasurement')
+    expect(source).toContain('expectedVersion: detail.inboundVersion')
+    expect(source).not.toContain('expectedVersion: detail.version')
+    expect(source).toContain('approval.initialPricingSucceeded')
+    expect(source).toContain('费用初算未生成，可补价后重新计算')
+  })
+
+  it('uses the inbound tenant isolation key for measurement and review requests', () => {
+    const source = readFileSync(resolve('src/modules/inbounds/components/InboundTaskList.vue'), 'utf8')
+
+    expect(source).toContain(':tenant-id="selectedInbound.tenantId"')
+    expect(source).toContain(':customer-id="selectedInbound.tenantId"')
+    expect(source).toContain(':customer-name="selectedInbound.customerName || selectedInbound.companyName"')
+    expect(source).toContain(':channel-name="selectedInbound.channelName"')
+    expect(source).not.toContain('selectedInbound.customerId || selectedInbound.tenantId')
+  })
+
+  it('opens the unique shared measurement dialog and refreshes without duplicating its workflow', () => {
+    const source = readFileSync(resolve('src/modules/inbounds/components/InboundTaskList.vue'), 'utf8')
+
+    expect(source).toContain("import InboundMeasurementDialog from '../measurement/InboundMeasurementDialog.vue'")
+    expect(source).toContain('<InboundMeasurementDialog')
+    expect(source).toContain('v-model="measurementDialogOpen"')
+    expect(source).toContain(':customer-id="selectedInbound.tenantId"')
+    expect(source).toContain('@updated="handleMeasurementUpdated"')
+    expect(source).toContain('@submitted="handleMeasurementSubmitted"')
+    expect(source).not.toContain('<WeightOcrPanel')
+    expect(source).not.toContain('<InboundMeasurementPanel')
+  })
+
+  it('loads only active customers and exposes a searchable name-only select', () => {
+    const source = readFileSync(resolve('src/modules/inbounds/components/InboundTaskList.vue'), 'utf8')
+    const queryFieldsSource = source.slice(source.indexOf('const queryFields'), source.indexOf('const columns'))
+
+    expect(source).toContain('loadAllActiveCustomers')
+    expect(queryFieldsSource).toContain("type: 'select'")
+    expect(queryFieldsSource).toContain('filterable: true')
+    expect(queryFieldsSource).toContain('label: customer.legalName?.trim() || customer.tenantName')
+    expect(queryFieldsSource).not.toContain('tenantCode')
+    expect(queryFieldsSource).not.toContain('客户编码')
+  })
+
+  it('clears date conditions safely and uses explicit select placeholders', () => {
+    const source = readFileSync(resolve('src/modules/inbounds/components/InboundTaskList.vue'), 'utf8')
+    const queryFieldsSource = source.slice(source.indexOf('const queryFields'), source.indexOf('const columns'))
+
+    expect(source).toContain('Array.isArray(filters.value.expectedArrivalRange)')
+    expect(queryFieldsSource).toContain("placeholder: customerLoadError.value ? '客户列表加载失败' : '请选择客户'")
+    expect(queryFieldsSource).toContain("placeholder: '请选择仓库'")
+  })
+
+  it('requests every active-customer page and merges name-only options', async () => {
+    const calls: Array<{ page: number; size: number; status: 'ACTIVE' }> = []
+    const records = await loadAllActiveCustomers(async (query) => {
+      calls.push(query)
+      if (query.page === 1) {
+        return {
+          pages: 2,
+          records: [activeCustomer('10001', '客户一', '客户一有限公司', 'CUS-001')],
+        }
+      }
+      return {
+        pages: 2,
+        records: [activeCustomer('10002', '客户二', null, 'CUS-002')],
+      }
+    })
+
+    expect(calls).toEqual([
+      { page: 1, size: 200, status: 'ACTIVE' },
+      { page: 2, size: 200, status: 'ACTIVE' },
+    ])
+    expect(records.map((customer) => customer.legalName?.trim() || customer.tenantName)).toEqual(['客户一有限公司', '客户二'])
+    expect(records.map((customer) => customer.legalName?.trim() || customer.tenantName).join(' ')).not.toContain('CUS-')
+  })
+
+  it('opens the shared unified order detail from the view action', () => {
+    const source = readFileSync(resolve('src/modules/inbounds/components/InboundTaskList.vue'), 'utf8')
+
+    expect(source).toContain("name: 'unified-order-detail', params: { orderId: row.orderId }, query: { tenantId: row.tenantId }")
+    expect(source).toContain("access.can('platform:firstleg:inbound:view') && (row as InboundOrderSummary).orderId")
+    expect(source).not.toContain("name: 'inbound-order-detail', params: { inboundId: row.id }")
+  })
+
+  it('keeps relationship data entry out of measurement and review task lists', () => {
+    const source = readFileSync(resolve('src/modules/inbounds/components/InboundTaskList.vue'), 'utf8')
+
+    expect(source).not.toContain('关联数据')
+    expect(source).not.toContain('InboundCodeRelationshipDialog')
+    expect(source).not.toContain('openRelationship')
+  })
+
+  it('closes only after navigating an approved review to the measurement tab', () => {
+    const source = readFileSync(resolve('src/modules/inbounds/components/InboundTaskList.vue'), 'utf8')
+    const handler = source.slice(source.indexOf('async function handleTaskChanged'), source.indexOf('function handleReviewSelectionChange'))
+
+    expect(handler).toContain("name: 'unified-order-detail-by-inbound-code'")
+    expect(handler).toContain('params: { inboundCode }')
+    expect(handler).toContain("query: { tab: 'measurement', from: 'measurement-review' }")
+    expect(handler).toContain('await router.push')
+    expect(handler.indexOf('await router.push')).toBeLessThan(handler.lastIndexOf('reviewDialogOpen.value = false'))
+    expect(handler).toContain("getApiErrorDetails(error, '订单详情打开失败，请重试')")
+    expect(handler).toContain("name: 'unified-order-detail'")
+    expect(handler).toContain("query: { tenantId: target.tenantId, tab: 'measurement', from: 'measurement-review' }")
+    expect(source).toContain(':post-approve-loading="reviewNavigationLoading"')
+    expect(source).toContain(':approval-completed="reviewApproved"')
+    expect(source).toContain(':close-on-click-modal="!reviewNavigationLoading"')
+    expect(source).toContain('reviewNavigationError')
+    expect(source).toContain('重新打开订单详情')
+    expect(source).not.toContain('params: { inboundId: target.id }')
+  })
+
+  it('shows authoritative measurement totals with operation first and no internal IDs as primary columns', () => {
+    const source = readFileSync(resolve('src/modules/inbounds/components/InboundTaskList.vue'), 'utf8')
+    const columnsSource = source.slice(source.indexOf('const columns'), source.indexOf('function text'))
+
+    expect(columnsSource.indexOf("key: 'actions'")).toBeLessThan(columnsSource.indexOf("key: 'inboundCode'"))
+    expect(columnsSource).toContain("key: 'customerName', label: '客户'")
+    expect(columnsSource).toContain("key: 'channelName', label: '渠道'")
+    expect(columnsSource).toContain("key: 'totalPackageCount', label: '总箱数'")
+    expect(columnsSource).toContain("key: 'palletCount', label: '托盘数'")
+    expect(columnsSource).toContain("key: 'actualGrossWeightKg', label: '实测毛重(kg)'")
+    expect(columnsSource).toContain("key: 'actualNetWeightKg', label: '货物重量(kg)'")
+    expect(columnsSource).toContain("key: 'actualVolumeCbm', label: '实测体积(m³)'")
+    expect(columnsSource).toContain("key: 'measureCompletedAt', label: '提交时间'")
+    expect(columnsSource).not.toContain("key: 'id'")
+    expect(columnsSource).not.toContain("key: 'orderId'")
+    expect(source).toContain('{{ formatNumber((row as InboundOrderSummary).actualGrossWeightKg) }}')
+    expect(source).toContain('{{ formatNumber((row as InboundOrderSummary).actualNetWeightKg) }}')
+    expect(source).not.toContain('actualGrossWeightKg ||')
+    expect(source).not.toContain('actualNetWeightKg ||')
+  })
+
+  it('renders missing list facts as an explicit dash instead of guessing values', () => {
+    const source = readFileSync(resolve('src/modules/inbounds/components/InboundTaskList.vue'), 'utf8')
+
+    expect(source).toContain("value === null || value === undefined || value === '' ? '—'")
+    expect(source).toContain("value === null || value === undefined ? '—'")
+    expect(source).toContain("if (!value) return '—'")
+  })
+
+  it('shows the expected arrival as a date in both measurement and review lists', () => {
+    const source = readFileSync(resolve('src/modules/inbounds/components/InboundTaskList.vue'), 'utf8')
+
+    expect(source).toContain("date.toLocaleDateString('zh-CN')")
+    expect(source).toContain('{{ formatDateOnly((row as InboundOrderSummary).expectedArrivalAt) }}')
+    expect(source).toContain('{{ formatDate((row as InboundOrderSummary).measureCompletedAt) }}')
+    expect(source).not.toContain('{{ formatDate((row as InboundOrderSummary).expectedArrivalAt) }}')
+  })
+
+  it('renders first-leg business types with the shared Chinese labels', () => {
+    const source = readFileSync(resolve('src/modules/inbounds/components/InboundTaskList.vue'), 'utf8')
+
+    expect(source).toContain("import { firstLegBusinessTypeLabel } from '@/shared/utils/firstLegBusinessLabels'")
+    expect(source).toContain('firstLegBusinessTypeLabel((row as InboundOrderSummary).businessType)')
+    expect(source).not.toContain('text((row as InboundOrderSummary).businessType)')
+  })
+
+  it('refreshes cached task lists when users return from measurement work', () => {
+    const source = readFileSync(resolve('src/modules/inbounds/components/InboundTaskList.vue'), 'utf8')
+
+    expect(source).toContain('onActivated(() => {')
+    expect(source).toContain('if (!activatedOnce)')
+    expect(source).toContain('activatedOnce = true')
+    expect(source).toContain('void loadTasks()')
+    expect(source).toContain('onMounted(() => { void loadOptions(); void loadTasks() })')
+  })
+})
diff --git a/src/modules/inbounds/components/InboundTaskList.vue b/src/modules/inbounds/components/InboundTaskList.vue
new file mode 100644
index 00000000..b2bfce49
--- /dev/null
+++ b/src/modules/inbounds/components/InboundTaskList.vue
@@ -0,0 +1,473 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import '../measurement/measurementDensity.css'
+import { computed, onActivated, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import { useRouter } from 'vue-router'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import { CircleCheckBig } from '@lucide/vue'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { listPlatformTenants, type PlatformTenantResource } from '@/modules/iam'
+import { listPlatformWarehouses } from '@/modules/warehouses'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import LineClampText from '@/shared/components/LineClampText.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import { firstLegBusinessTypeLabel } from '@/shared/utils/firstLegBusinessLabels'
+import { listPlatformInbounds } from '../core/api'
+import type { InboundOrderSummary } from '../core/types'
+import InboundMeasurementDialog from '../measurement/InboundMeasurementDialog.vue'
+import MeasurementReviewPanel from '../review/MeasurementReviewPanel.vue'
+import { approveMeasurement, getMeasurementReviewDetail } from '../review/api'
+import { inboundProcessStatusLabels, inboundReviewStatusLabels, inboundStatusLabel } from '../status'
+import { buildInboundTaskQuery, loadAllActiveCustomers, type InboundTaskMode } from '../task-list'
+
+type FilterModel = QueryModel & {
+  customerId: string
+  inboundCode: string
+  warehouseId: string
+  expectedArrivalRange: string[]
+}
+
+const props = defineProps<{ mode: InboundTaskMode }>()
+const router = useRouter()
+const access = useAccessPreviewStore()
+const page = ref(1)
+const pageSize = ref(20)
+const loading = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const result = ref({ records: [] as InboundOrderSummary[], total: 0 })
+const filters = ref<FilterModel>({ customerId: '', inboundCode: '', warehouseId: '', expectedArrivalRange: [] })
+const appliedFilters = ref<FilterModel>({ ...filters.value, expectedArrivalRange: [] })
+const customers = ref<PlatformTenantResource[]>([])
+const customerLoadError = ref<ApiErrorDetails | null>(null)
+const warehouseOptions = ref<Array<{ label: string; value: string }>>([])
+const selectedInbound = ref<InboundOrderSummary | null>(null)
+const measurementDialogOpen = ref(false)
+const reviewDialogOpen = ref(false)
+const reviewNavigationLoading = ref(false)
+const reviewApproved = ref(false)
+const reviewNavigationError = ref<ApiErrorDetails | null>(null)
+const batchReviewLoading = ref(false)
+const selectedReviewRows = ref<InboundOrderSummary[]>([])
+let requestSerial = 0
+let optionsRequestSerial = 0
+let disposed = false
+let activatedOnce = false
+
+const isReview = computed(() => props.mode === 'review')
+const actionPermission = computed(() => isReview.value
+  ? 'firstleg:inbound:measurement-review'
+  : 'platform:firstleg:inbound:measure:view')
+const taskLabel = computed(() => isReview.value ? '审核' : '测量')
+const emptyText = computed(() => isReview.value ? '暂无待审核的测量数据' : '暂无当前可测量的订单')
+const preferenceKey = computed(() => isReview.value ? 'inbound-measurement-reviews' : 'inbound-measurements')
+
+const queryFields = computed<QueryField[]>(() => [
+  {
+    key: 'customerId',
+    type: 'select',
+    label: '客户',
+    width: 260,
+    placeholder: customerLoadError.value ? '客户列表加载失败' : '请选择客户',
+    options: customers.value.map((customer) => ({
+      value: String(customer.id),
+      label: customer.legalName?.trim() || customer.tenantName,
+    })),
+    props: { filterable: true, disabled: Boolean(customerLoadError.value) },
+  },
+  { key: 'warehouseId', type: 'select', label: '定位仓库', width: 220, placeholder: '请选择仓库', options: warehouseOptions.value, props: { filterable: true } },
+  { key: 'inboundCode', type: 'input', label: '入仓码', width: 220, placeholder: '请输入入仓码' },
+  { key: 'expectedArrivalRange', type: 'daterange', label: '预计到达时间', width: 320, placeholder: '请选择日期范围' },
+])
+
+const columns = computed<DataTableColumn[]>(() => [
+  { key: 'actions', label: '操作', width: 160, fixed: 'left', slotName: 'actions' },
+  ...(isReview.value && access.can(actionPermission.value) ? [{
+    key: 'selection', type: 'selection', width: 48, fixed: 'left',
+    selectable: (row: InboundOrderSummary) => row.measureReviewStatus === 'PENDING' && !batchReviewLoading.value,
+  } satisfies DataTableColumn] : []),
+  { key: 'inboundCode', label: '入仓码', minWidth: 140, slotName: 'inboundCode' },
+  { key: 'processStatus', label: '流程状态', minWidth: 132, slotName: 'processStatus' },
+  { key: 'measureReviewStatus', label: '测量审核状态', minWidth: 120, slotName: 'measureReviewStatus' },
+  { key: 'expectedArrivalAt', label: '预计到达时间', minWidth: 140, slotName: 'expectedArrivalAt' },
+  { key: 'customerName', label: '客户', minWidth: 140, slotName: 'customerName' },
+  { key: 'warehouseName', label: '仓库', minWidth: 120, slotName: 'warehouseName' },
+  { key: 'deliveryWarehouseName', label: '交货仓', minWidth: 120, slotName: 'deliveryWarehouseName' },
+  { key: 'businessType', label: '业务类型', minWidth: 100, slotName: 'businessType' },
+  { key: 'channelName', label: '渠道', minWidth: 100, slotName: 'channelName' },
+  { key: 'totalPackageCount', label: '总箱数', width: 90, slotName: 'totalPackageCount' },
+  { key: 'palletCount', label: '托盘数', width: 90, slotName: 'palletCount' },
+  { key: 'actualGrossWeightKg', label: '实测毛重(kg)', minWidth: 100, slotName: 'actualGrossWeightKg' },
+  { key: 'actualNetWeightKg', label: '货物重量(kg)', minWidth: 100, slotName: 'actualNetWeightKg' },
+  { key: 'actualVolumeCbm', label: '实测体积(m³)', minWidth: 100, slotName: 'actualVolumeCbm' },
+  { key: 'measureCompletedAt', label: '提交时间', minWidth: 140, slotName: 'measureCompletedAt' },
+])
+
+function text(value: unknown) {
+  return value === null || value === undefined || value === '' ? '—' : String(value)
+}
+
+function formatNumber(value: number | null | undefined) {
+  return value === null || value === undefined ? '—' : value.toLocaleString('zh-CN', { maximumFractionDigits: 3 })
+}
+
+function formatDate(value: string | null | undefined) {
+  if (!value) return '—'
+  const date = new Date(value)
+  return Number.isNaN(date.getTime()) ? value : date.toLocaleString('zh-CN', { hour12: false })
+}
+
+function formatDateOnly(value: string | null | undefined) {
+  if (!value) return '—'
+  const date = new Date(value)
+  return Number.isNaN(date.getTime()) ? value : date.toLocaleDateString('zh-CN')
+}
+
+function dateParam(value: string | undefined, end = false) {
+  return value ? `${value}T${end ? '23:59:59' : '00:00:00'}` : undefined
+}
+
+async function loadOptions() {
+  const serial = ++optionsRequestSerial
+  customerLoadError.value = null
+  try {
+    const [customerRecords, warehousePage] = await Promise.all([
+      loadAllActiveCustomers((query) => listPlatformTenants(query)),
+      listPlatformWarehouses(1, 200),
+    ])
+    if (disposed || serial !== optionsRequestSerial) return
+    customers.value = customerRecords
+    warehouseOptions.value = warehousePage.records.map((warehouse) => ({
+      label: `${warehouse.warehouseName} · ${warehouse.warehouseCode}`,
+      value: String(warehouse.id),
+    }))
+  } catch (error) {
+    if (disposed) return
+    customerLoadError.value = getApiErrorDetails(error, '客户或仓库筛选项加载失败，不影响查看全部待办')
+  }
+}
+
+async function loadTasks() {
+  selectedReviewRows.value = []
+  const serial = ++requestSerial
+  loading.value = true
+  loadError.value = null
+  const applied = appliedFilters.value
+  try {
+    const response = await listPlatformInbounds(applied.customerId || undefined, buildInboundTaskQuery(props.mode, {
+      page: page.value,
+      size: pageSize.value,
+      warehouseId: applied.warehouseId || undefined,
+      inboundCode: applied.inboundCode.trim() || undefined,
+      expectedArrivalFrom: dateParam(applied.expectedArrivalRange[0]),
+      expectedArrivalTo: dateParam(applied.expectedArrivalRange[1], true),
+    }))
+    if (disposed || serial !== requestSerial) return
+    result.value = { records: response.records, total: response.total }
+  } catch (error) {
+    if (disposed || serial !== requestSerial) return
+    loadError.value = getApiErrorDetails(error, `${taskLabel.value}待办加载失败`)
+  } finally {
+    if (!disposed && serial === requestSerial) loading.value = false
+  }
+}
+
+function applyFilters() {
+  appliedFilters.value = {
+    ...filters.value,
+    expectedArrivalRange: Array.isArray(filters.value.expectedArrivalRange) ? [...filters.value.expectedArrivalRange] : [],
+  }
+  if (page.value === 1) void loadTasks()
+  else page.value = 1
+}
+
+function resetFilters() {
+  filters.value = { customerId: '', inboundCode: '', warehouseId: '', expectedArrivalRange: [] }
+  appliedFilters.value = { ...filters.value, expectedArrivalRange: [] }
+  if (page.value === 1) void loadTasks()
+  else page.value = 1
+}
+
+function openTask(row: InboundOrderSummary) {
+  selectedInbound.value = row
+  if (isReview.value) {
+    reviewApproved.value = false
+    reviewNavigationError.value = null
+    reviewDialogOpen.value = true
+  }
+  else measurementDialogOpen.value = true
+}
+
+function openDetail(row: InboundOrderSummary) {
+  if (!row.orderId) return
+  void router.push({ name: 'unified-order-detail', params: { orderId: row.orderId }, query: { tenantId: row.tenantId } })
+}
+
+async function handleTaskChanged() {
+  const target = selectedInbound.value
+  if (!isReview.value) {
+    reviewDialogOpen.value = false
+    selectedInbound.value = null
+    void loadTasks()
+    return
+  }
+  if (!target || reviewNavigationLoading.value) return
+  reviewApproved.value = true
+  reviewNavigationError.value = null
+
+  const inboundCode = target.inboundCode?.trim()
+  const orderId = target.orderId?.trim()
+  if (!inboundCode && !orderId) {
+    reviewNavigationError.value = { message: '审核已通过，但未找到对应订单，请关闭弹框后刷新列表重试' }
+    return
+  }
+
+  reviewNavigationLoading.value = true
+  try {
+    if (inboundCode) {
+      await router.push({
+        name: 'unified-order-detail-by-inbound-code',
+        params: { inboundCode },
+        query: { tab: 'measurement', from: 'measurement-review' },
+      })
+    } else {
+      await router.push({
+        name: 'unified-order-detail',
+        params: { orderId },
+        query: { tenantId: target.tenantId, tab: 'measurement', from: 'measurement-review' },
+      })
+    }
+    reviewDialogOpen.value = false
+    selectedInbound.value = null
+  } catch (error) {
+    reviewNavigationError.value = getApiErrorDetails(error, '订单详情打开失败，请重试')
+  } finally {
+    reviewNavigationLoading.value = false
+  }
+}
+
+function handleReviewSelectionChange(rows: InboundOrderSummary[]) {
+  selectedReviewRows.value = rows.filter((row) => row.measureReviewStatus === 'PENDING')
+}
+
+async function batchApproveMeasurements() {
+  const selected = [...selectedReviewRows.value]
+  if (!selected.length || batchReviewLoading.value) return
+  batchReviewLoading.value = true
+  try {
+    await ElMessageBox.confirm(
+      `确认批量审核通过已勾选的 ${selected.length} 条测量数据吗？一件代发通过后进入待组托，其他订单进入待分柜。`,
+      '批量审核测量数据',
+      { customClass: 'admin-density-confirm', confirmButtonText: '确认批量审核', cancelButtonText: '取消', type: 'warning' },
+    )
+    let successCount = 0
+    let failureCount = 0
+    const failures: string[] = []
+    const pricingWarnings: string[] = []
+    for (const row of selected) {
+      try {
+        const detail = await getMeasurementReviewDetail(String(row.tenantId), String(row.id))
+        const approval = await approveMeasurement(String(row.tenantId), String(row.id), {
+          measurementId: detail.measurementId,
+          expectedVersion: detail.inboundVersion,
+        })
+        successCount += 1
+        if (!approval.initialPricingSucceeded) {
+          pricingWarnings.push(
+            `${row.inboundCode || '入仓码待补充'}：${approval.initialPricingMessage || '费用初算未生成'}`,
+          )
+        }
+      } catch (error) {
+        failureCount += 1
+        failures.push(getApiErrorDetails(error, `${row.inboundCode || '入仓码待补充'} 审核失败`).message)
+      }
+    }
+    await loadTasks()
+    const reason = [...new Set(failures.filter(Boolean))].slice(0, 3).join('；')
+    const pricingReason = [...new Set(pricingWarnings.filter(Boolean))].slice(0, 3).join('；')
+    if (!failureCount && !pricingWarnings.length) ElMessage.success(`已批量审核通过 ${successCount} 条测量数据，费用初算已生成`)
+    else if (!failureCount) ElMessage.warning(`已批量审核通过 ${successCount} 条测量数据；其中 ${pricingWarnings.length} 条费用初算未生成，可补价后重新计算${pricingReason ? `。${pricingReason}` : ''}`)
+    else if (successCount) ElMessage.warning(`批量审核完成：成功 ${successCount} 条，失败 ${failureCount} 条${reason ? `。${reason}` : ''}`)
+    else ElMessage.error(`批量审核失败：${failureCount} 条测量数据未通过${reason ? `。${reason}` : ''}`)
+  } catch (error) {
+    if (error !== 'cancel' && error !== 'close') ElMessage.error(getApiErrorDetails(error, '批量审核失败').message)
+  } finally {
+    batchReviewLoading.value = false
+  }
+}
+
+function handleMeasurementUpdated() {
+  void loadTasks()
+}
+
+function handleMeasurementSubmitted() {
+  void loadTasks()
+}
+
+function clearSelectedInbound() {
+  selectedInbound.value = null
+  reviewApproved.value = false
+  reviewNavigationError.value = null
+  reviewNavigationLoading.value = false
+}
+
+watch([page, pageSize], () => { void loadTasks() })
+onMounted(() => { void loadOptions(); void loadTasks() })
+onActivated(() => {
+  if (!activatedOnce) {
+    activatedOnce = true
+    return
+  }
+  void loadTasks()
+})
+onBeforeUnmount(() => { disposed = true; requestSerial += 1; optionsRequestSerial += 1 })
+</script>
+
+<template>
+  <AdminPage as="div" class="inbound-task-page admin-density">
+    <ListPageLayout :aria-label="`${taskLabel}待办`">
+      <template #toolbar>
+        <QueryToolbar
+          v-model="filters"
+          class="surface-panel"
+          :ariaLabel="`${taskLabel}待办筛选`"
+          :fields="queryFields"
+          :preference-key="`${preferenceKey}-query`"
+          :search-on-reset="false"
+          @search="applyFilters"
+          @reset="resetFilters"
+        />
+      </template>
+
+      <template v-if="customerLoadError || loadError" #state>
+        <div class="state-stack">
+          <el-alert v-if="customerLoadError" type="warning" :closable="false" show-icon>
+            <template #title><span>{{ customerLoadError.message }}</span></template>
+          </el-alert>
+          <LoadErrorState v-if="loadError" :title="`${taskLabel}待办暂时无法加载`" :message="loadError.message" @retry="loadTasks">
+            <template #details><ApiErrorMeta :details="loadError" /></template>
+          </LoadErrorState>
+        </div>
+      </template>
+
+      <section v-if="!loadError" class="surface-panel table-panel" :aria-busy="loading">
+        <DataTable
+          v-model:page="page"
+          v-model:page-size="pageSize"
+          :data="result.records"
+          :columns="columns"
+          :preference-key="`${preferenceKey}-table`"
+          :loading="loading"
+          :total="result.total"
+          :page-sizes="[20, 50, 100]"
+          row-key="id"
+          :empty-text="emptyText"
+          :aria-label="`${taskLabel}待办列表`"
+          @selection-change="handleReviewSelectionChange"
+        >
+          <template v-if="isReview && access.can(actionPermission)" #toolbar-actions>
+            <el-button type="success" :loading="batchReviewLoading" :disabled="loading || !selectedReviewRows.length" @click="batchApproveMeasurements"><CircleCheckBig :size="16" />批量审核通过<span v-if="selectedReviewRows.length">（{{ selectedReviewRows.length }}）</span></el-button>
+          </template>
+          <template #pagination-left>当前显示 {{ result.records.length }} 条 · 共 {{ result.total }} 条</template>
+          <template #actions="{ row }">
+            <div class="row-actions density-actions">
+              <el-button v-if="access.can(actionPermission)" class="density-action" :data-tone="isReview ? 'warning' : 'purple'" size="small" @click="openTask(row as InboundOrderSummary)">
+                {{ taskLabel }}
+              </el-button>
+              <el-button v-if="access.can('platform:firstleg:inbound:view') && (row as InboundOrderSummary).orderId" class="density-action" size="small" @click="openDetail(row as InboundOrderSummary)">
+                查看
+              </el-button>
+              <span v-if="!access.can(actionPermission) && (!access.can('platform:firstleg:inbound:view') || !(row as InboundOrderSummary).orderId)" class="muted-action">无操作权限</span>
+            </div>
+          </template>
+          <template #inboundCode="{ row }"><div class="inbound-code-cell"><strong>{{ text((row as InboundOrderSummary).inboundCode) }}</strong></div></template>
+          <template #processStatus="{ row }"><el-tag effect="light">{{ inboundStatusLabel((row as InboundOrderSummary).processStatus, inboundProcessStatusLabels) }}</el-tag></template>
+          <template #measureReviewStatus="{ row }">{{ inboundStatusLabel((row as InboundOrderSummary).measureReviewStatus, inboundReviewStatusLabels) }}</template>
+          <template #expectedArrivalAt="{ row }">{{ formatDateOnly((row as InboundOrderSummary).expectedArrivalAt) }}</template>
+          <template #customerName="{ row }"><LineClampText :content="(row as InboundOrderSummary).customerName" /></template>
+          <template #warehouseName="{ row }">{{ text((row as InboundOrderSummary).warehouseName) }}</template>
+          <template #deliveryWarehouseName="{ row }">{{ text((row as InboundOrderSummary).deliveryWarehouseName) }}</template>
+          <template #businessType="{ row }">{{ firstLegBusinessTypeLabel((row as InboundOrderSummary).businessType) }}</template>
+          <template #channelName="{ row }"><LineClampText :content="(row as InboundOrderSummary).channelName || (row as InboundOrderSummary).channelCode" /></template>
+          <template #totalPackageCount="{ row }">{{ text((row as InboundOrderSummary).totalPackageCount) }}</template>
+          <template #palletCount="{ row }">{{ text((row as InboundOrderSummary).palletCount) }}</template>
+          <template #actualGrossWeightKg="{ row }">{{ formatNumber((row as InboundOrderSummary).actualGrossWeightKg) }}</template>
+          <template #actualNetWeightKg="{ row }">{{ formatNumber((row as InboundOrderSummary).actualNetWeightKg) }}</template>
+          <template #actualVolumeCbm="{ row }">{{ formatNumber((row as InboundOrderSummary).actualVolumeCbm) }}</template>
+          <template #measureCompletedAt="{ row }">{{ formatDate((row as InboundOrderSummary).measureCompletedAt) }}</template>
+          <template #empty><el-empty :description="emptyText" /></template>
+        </DataTable>
+      </section>
+    </ListPageLayout>
+
+    <el-dialog
+      v-if="isReview"
+      v-model="reviewDialogOpen"
+      :title="selectedInbound ? `${taskLabel} · ${selectedInbound.inboundCode || '入仓码待补充'}` : taskLabel"
+      width="min(1560px, calc(100vw - 48px))"
+      top="4vh"
+      destroy-on-close
+      append-to-body
+      :close-on-click-modal="!reviewNavigationLoading"
+      :close-on-press-escape="!reviewNavigationLoading"
+      class="inbound-task-dialog admin-density-dialog admin-density-workspace inbound-density"
+      @closed="clearSelectedInbound"
+    >
+      <el-alert v-if="reviewNavigationError" type="error" :closable="false" show-icon class="review-navigation-error">
+        <template #title>{{ reviewNavigationError.message }}</template>
+        <ApiErrorMeta :details="reviewNavigationError" />
+        <el-button v-if="selectedInbound?.inboundCode || selectedInbound?.orderId" link type="danger" :loading="reviewNavigationLoading" @click="handleTaskChanged">重新打开订单详情</el-button>
+      </el-alert>
+      <MeasurementReviewPanel
+        v-if="selectedInbound"
+        :tenant-id="selectedInbound.tenantId"
+        :inbound-id="selectedInbound.id"
+        :fulfillment-type="selectedInbound.fulfillmentType"
+        :customer-name="selectedInbound.customerName || selectedInbound.companyName"
+        :channel-name="selectedInbound.channelName"
+        :channel-code="selectedInbound.channelCode"
+        :post-approve-loading="reviewNavigationLoading"
+        :approval-completed="reviewApproved"
+        @changed="handleTaskChanged"
+      />
+    </el-dialog>
+
+    <InboundMeasurementDialog
+      v-if="!isReview && selectedInbound"
+      v-model="measurementDialogOpen"
+      :customer-id="selectedInbound.tenantId"
+      :inbound-id="selectedInbound.id"
+      :inbound-code="selectedInbound.inboundCode"
+      @updated="handleMeasurementUpdated"
+      @submitted="handleMeasurementSubmitted"
+      @closed="clearSelectedInbound"
+    />
+  </AdminPage>
+</template>
+
+<style scoped>
+.inbound-task-page { min-width: 0; }
+.state-stack { display: grid; gap: var(--admin-space-5, 12px); }
+.review-navigation-error { margin-bottom: 14px; }
+.row-actions { white-space: nowrap; }
+.primary-cell { display: grid; gap: 3px; min-width: 0; }
+.primary-cell strong, .primary-cell span { overflow-wrap: anywhere; }
+.inbound-code-cell { display: grid; gap: 3px; min-width: 0; }
+.primary-cell span, .muted-action { color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); }
+@media (max-width: 520px) {
+  .row-actions { align-items: stretch; flex-direction: column; }
+  .row-actions :deep(.el-button) { width: 100%; }
+}
+</style>
+
+<style>
+.inbound-task-dialog.admin-density-workspace.el-dialog:not(.is-fullscreen) { height: auto; max-height: 92vh; overflow: hidden; }
+.inbound-task-dialog .el-dialog__body { max-height: calc(92vh - 62px); }
+@media (max-width: 520px) {
+  .inbound-task-dialog .el-dialog__body { padding: 14px; }
+}
+</style>
diff --git a/src/modules/inbounds/components/InboundWorkflowWorkspace.test.ts b/src/modules/inbounds/components/InboundWorkflowWorkspace.test.ts
new file mode 100644
index 00000000..9b5f1dc9
--- /dev/null
+++ b/src/modules/inbounds/components/InboundWorkflowWorkspace.test.ts
@@ -0,0 +1,103 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/inbounds/components/InboundWorkflowWorkspace.vue'), 'utf8')
+const measurementDialogSource = readFileSync(resolve(process.cwd(), 'src/modules/inbounds/measurement/InboundMeasurementDialog.vue'), 'utf8')
+
+describe('InboundWorkflowWorkspace', () => {
+  it('assembles every phase-two inbound domain behind one server-backed workspace', () => {
+    expect(source).toContain('InboundSummaryPanel')
+    expect(source).toContain('InboundHistoryPanel')
+    expect(source).toContain('InboundMeasurementDialog')
+    expect(source).toContain('MeasurementReviewPanel')
+    expect(source).toContain('InboundFeePanel')
+    expect(source).toContain('getPlatformInbound')
+    expect(source).toContain('StatusBadge')
+    expect(source).toContain('label="基本信息"')
+    expect(source).toContain('label="货品与测量"')
+    expect(source).toContain('label="测量审核"')
+    expect(source).toContain('label="费用信息"')
+    expect(source).toContain('label="状态历史"')
+    expect(source).toContain("detail.summary.fulfillmentType === 'ONE_CLICK_DROPSHIP' ? '清点组托与其他记录' : '其他记录'")
+    expect(source).toContain('listPlatformInboundDropshipPallets(props.customerId, props.inboundId)')
+  })
+
+  it('opens measurement editing and review in prototype-sized centered dialogs', () => {
+    expect(source).toContain('<InboundMeasurementDialog')
+    expect(source).toContain('width="min(1240px, calc(100vw - 32px))"')
+    expect(source).toContain(':title="`测量审核 · ${title}`"')
+    expect(source).toContain('width="min(1240px, calc(100vw - 32px))"')
+    expect(source).toContain('height: 92vh')
+    expect(source).toContain('max-height: 92vh')
+    expect(source).toContain('.el-dialog__body) { min-height: 0; flex: 1 1 auto; overflow-y: auto;')
+    expect(source).toContain('@media (max-width: 720px)')
+    expect(source).toContain('@media (max-width: 360px)')
+  })
+
+  it('keeps domain writes inside their existing panels and mounts them only in dialog bodies', () => {
+    expect(source).toContain('@click="measurementDialogOpen = true"')
+    expect(source).toContain('@click="reviewDialogOpen = true"')
+    expect(source).toContain(':key="`review-dialog-${revision}`"')
+    expect(source).toContain(':customer-name="detail?.summary.customerName || detail?.summary.companyName"')
+    expect(source).toContain(':channel-name="detail?.summary.channelName"')
+    expect(source).toContain('@changed="handleReviewChanged"')
+    expect(source).not.toContain('<template #footer>')
+    expect(source).toContain('@updated="handleDomainChanged"')
+    expect(source).toContain('@submitted="handleDomainChanged"')
+    expect(source).not.toContain('reviewPanelRef')
+    expect(source).not.toContain('inbound-operation-dialog__footer')
+    expect(source).not.toContain('approveMeasurement')
+    expect(source).not.toContain('submitInboundMeasurement')
+  })
+
+  it('uses the established first-leg detail density without nested framed surfaces', () => {
+    expect(source).toContain('padding: 18px 24px 16px')
+    expect(source).toContain('border-bottom: 1px solid var(--cc-border)')
+    expect(source).not.toContain('border-radius: 10px')
+    expect(source).not.toContain('<el-tag')
+  })
+
+  it('refreshes the aggregate and remounts domains after manual or child refresh', () => {
+    expect(source).toContain('function handleDomainChanged()')
+    expect(source).toContain('async function refreshWorkspace()')
+    expect(source).toContain('revision.value += 1')
+    expect(source).toContain('void refreshWorkspace()')
+    expect(source).toContain('@click="refreshWorkspace"')
+    expect(source).toContain('@changed="handleDomainChanged"')
+  })
+
+  it('uses customer context in the page layer and maps it to compatible domain APIs', () => {
+    expect(source).toContain('customerId: string')
+    expect(source).toContain('getPlatformInbound(props.customerId, props.inboundId)')
+    expect(source).toContain(':customer-id="customerId"')
+    expect(source).toContain('缺少所属企业信息')
+    expect(source).not.toContain('请选择企业')
+    expect(source).not.toContain('租户')
+  })
+
+  it('does not mount the review domain without its required measurement data permission', () => {
+    expect(source).toContain("access.can('platform:firstleg:inbound:measure:view')")
+    expect(source).toContain('v-if="canViewMeasurement"')
+    expect(source).toContain('无测量审核查看权限')
+  })
+
+  it('keeps pallet and location results read-only in the overview', () => {
+    expect(source).toContain(':pallet-locations="detail.palletLocations"')
+    expect(source).toContain(':sections="[\'history\']"')
+    expect(source).toContain(':sections="[\'dropship\', \'allocations\', \'files\', \'notes\', \'remark\']"')
+    expect(source).not.toContain('reserveLocation')
+    expect(source).not.toContain('allocatePallet')
+  })
+
+  it('uses semantic outlined or solid buttons for workflow launches and decisions', () => {
+    expect(source).toContain('<el-button v-if="canViewMeasurement" type="primary" @click="measurementDialogOpen = true">')
+    expect(source).toContain('<el-button type="primary" @click="reviewDialogOpen = true">')
+    expect(measurementDialogSource).toContain('type="primary"')
+    expect(measurementDialogSource).toContain('plain')
+    expect(source).not.toContain('异常放行')
+    expect(source).toContain('<Pencil :size="16" />编辑测量数据')
+    expect(source).toContain('<ClipboardCheck :size="16" />审核测量数据')
+    expect(source).toContain('@media (max-width: 360px)')
+  })
+})
diff --git a/src/modules/inbounds/components/InboundWorkflowWorkspace.vue b/src/modules/inbounds/components/InboundWorkflowWorkspace.vue
new file mode 100644
index 00000000..6ec4e862
--- /dev/null
+++ b/src/modules/inbounds/components/InboundWorkflowWorkspace.vue
@@ -0,0 +1,269 @@
+<script setup lang="ts">
+import { computed, onBeforeUnmount, ref, watch } from 'vue'
+import { ClipboardCheck, Pencil, RefreshCw } from '@lucide/vue'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import { getPlatformInbound, listPlatformInboundDropshipPallets } from '../core/api'
+import InboundHistoryPanel from '../core/InboundHistoryPanel.vue'
+import InboundSummaryPanel from '../core/InboundSummaryPanel.vue'
+import type { InboundOrderDetail } from '../core/types'
+import { InboundMeasurementDialog } from '../measurement'
+import { MeasurementReviewPanel } from '../review'
+import { InboundFeePanel } from '../fee'
+import { inboundProcessStatusLabels, inboundStatusLabel } from '../status'
+
+const props = defineProps<{
+  customerId: string
+  inboundId: string
+}>()
+
+const emit = defineEmits<{
+  changed: []
+}>()
+
+const access = useAccessPreviewStore()
+const activeTab = ref('overview')
+const measurementDialogOpen = ref(false)
+const reviewDialogOpen = ref(false)
+const loading = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const detail = ref<InboundOrderDetail | null>(null)
+const revision = ref(0)
+let requestSerial = 0
+let disposed = false
+
+const title = computed(() => detail.value?.summary.inboundCode || '入仓码待补充')
+const canViewMeasurement = computed(() => access.can('platform:firstleg:inbound:measure:view'))
+const canViewDropshipPallets = computed(() => access.can('platform:firstleg:pda:view'))
+const statusLabel = computed(() => inboundStatusLabel(detail.value?.summary.processStatus, inboundProcessStatusLabels, '未知状态'))
+
+async function loadDetail() {
+  const serial = ++requestSerial
+  if (!props.customerId || !props.inboundId) {
+    detail.value = null
+    loadError.value = null
+    loading.value = false
+    return
+  }
+  loading.value = true
+  loadError.value = null
+  try {
+    const response = await getPlatformInbound(props.customerId, props.inboundId)
+    if (response.summary.fulfillmentType === 'ONE_CLICK_DROPSHIP' && canViewDropshipPallets.value) {
+      response.dropshipPallets = await listPlatformInboundDropshipPallets(props.customerId, props.inboundId)
+    }
+    if (disposed || serial !== requestSerial) return
+    detail.value = response
+  } catch (error) {
+    if (disposed || serial !== requestSerial) return
+    detail.value = null
+    loadError.value = getApiErrorDetails(error, '入库单详情加载失败')
+  } finally {
+    if (!disposed && serial === requestSerial) loading.value = false
+  }
+}
+
+async function refreshWorkspace() {
+  revision.value += 1
+  await loadDetail()
+}
+
+function handleDomainChanged() {
+  void refreshWorkspace()
+  emit('changed')
+}
+
+function handleReviewChanged() {
+  reviewDialogOpen.value = false
+  handleDomainChanged()
+}
+
+watch(
+  () => [props.customerId, props.inboundId],
+  () => {
+    activeTab.value = 'overview'
+    detail.value = null
+    loadError.value = null
+    revision.value += 1
+    void loadDetail()
+  },
+  { immediate: true },
+)
+
+onBeforeUnmount(() => {
+  disposed = true
+  requestSerial += 1
+})
+</script>
+
+<template>
+  <section class="inbound-workspace" :aria-busy="loading">
+    <header class="workspace-header">
+      <div>
+        <div class="workspace-title-row">
+          <h2>入库码：{{ title }}</h2>
+          <StatusBadge v-if="detail" :status="statusLabel" />
+        </div>
+        <p>按基本信息、货物测量、审核、费用和托盘库位顺序处理，所有结果以服务端最新状态为准。</p>
+      </div>
+      <el-button :loading="loading" :disabled="!customerId || !inboundId" @click="refreshWorkspace">
+        <RefreshCw :size="16" />刷新
+      </el-button>
+    </header>
+
+    <LoadErrorState
+      v-if="loadError"
+      class="workspace-state"
+      title="入库作业详情暂时无法加载"
+      :message="loadError.message"
+      @retry="loadDetail"
+    >
+      <template #details><ApiErrorMeta :details="loadError" /></template>
+    </LoadErrorState>
+
+    <div v-else-if="loading && !detail" class="workspace-state workspace-skeleton" aria-label="正在加载入库作业详情">
+      <el-skeleton :rows="8" animated />
+    </div>
+
+    <el-empty v-else-if="!detail" class="workspace-state" description="缺少所属企业信息，无法查看入库作业详情" />
+
+    <el-tabs v-else v-model="activeTab" class="workflow-tabs">
+      <el-tab-pane label="基本信息" name="overview">
+        <InboundSummaryPanel :summary="detail.summary" :public-remark="detail.publicRemark" />
+      </el-tab-pane>
+      <el-tab-pane label="货品与测量" name="measurement" lazy>
+        <div class="workflow-action-row">
+          <span>核对原单数据、确认扫描箱数，并查看服务端计算的重量和体积结果。</span>
+          <el-button v-if="canViewMeasurement" type="primary" @click="measurementDialogOpen = true"><Pencil :size="16" />编辑测量数据</el-button>
+        </div>
+        <el-alert
+          :title="canViewMeasurement ? '称重图片、OCR、托盘与箱规统一在测量弹框中维护。' : '当前账号缺少测量查看权限。'"
+          :type="canViewMeasurement ? 'info' : 'warning'"
+          :closable="false"
+          show-icon
+        />
+      </el-tab-pane>
+      <el-tab-pane label="测量审核" name="review" lazy>
+          <div v-if="canViewMeasurement" class="workflow-action-row">
+          <span>对照原单、设备实测和称重 OCR 结果后作出审核决定。</span>
+          <el-button type="primary" @click="reviewDialogOpen = true"><ClipboardCheck :size="16" />审核测量数据</el-button>
+        </div>
+        <el-alert
+          v-else
+          title="无测量审核查看权限"
+          description="当前账号缺少测量查看权限，无法读取审核所需的原单、箱规和称重数据。"
+          type="warning"
+          :closable="false"
+          show-icon
+        />
+      </el-tab-pane>
+      <el-tab-pane label="费用信息" name="fee" lazy>
+        <InboundFeePanel
+          :key="`fee-${revision}`"
+          :tenant-id="customerId"
+          :inbound-id="inboundId"
+          @changed="handleDomainChanged"
+        />
+      </el-tab-pane>
+      <el-tab-pane label="状态历史" name="history" lazy>
+        <InboundHistoryPanel
+          :pallet-locations="[]"
+          :files="[]"
+          :internal-notes="[]"
+          :status-history="detail.statusHistory"
+          :public-remark="null"
+          :sections="['history']"
+        />
+      </el-tab-pane>
+      <el-tab-pane :label="detail.summary.fulfillmentType === 'ONE_CLICK_DROPSHIP' ? '清点组托与其他记录' : '其他记录'" name="records" lazy>
+        <InboundHistoryPanel
+          :pallet-locations="detail.palletLocations"
+          :dropship-pallets="detail.dropshipPallets"
+          :customer-id="customerId"
+          :inbound-id="inboundId"
+          :can-view-dropship="canViewDropshipPallets"
+          :files="detail.files"
+          :internal-notes="detail.internalNotes"
+          :status-history="[]"
+          :public-remark="detail.publicRemark"
+          :sections="['dropship', 'allocations', 'files', 'notes', 'remark']"
+        />
+      </el-tab-pane>
+    </el-tabs>
+
+    <InboundMeasurementDialog
+      v-model="measurementDialogOpen"
+      :customer-id="customerId"
+      :inbound-id="inboundId"
+      :inbound-code="title"
+      @updated="handleDomainChanged"
+      @submitted="handleDomainChanged"
+    />
+
+    <el-dialog
+      v-model="reviewDialogOpen"
+      class="inbound-operation-dialog inbound-review-dialog"
+      :title="`测量审核 · ${title}`"
+      width="min(1240px, calc(100vw - 32px))"
+      top="4vh"
+      destroy-on-close
+      :close-on-click-modal="false"
+    >
+      <div class="inbound-operation-dialog__body">
+        <MeasurementReviewPanel
+          v-if="canViewMeasurement"
+          :key="`review-dialog-${revision}`"
+          :tenant-id="customerId"
+          :inbound-id="inboundId"
+          :fulfillment-type="detail?.summary.fulfillmentType"
+          :customer-name="detail?.summary.customerName || detail?.summary.companyName"
+          :channel-name="detail?.summary.channelName"
+          :channel-code="detail?.summary.channelCode"
+          @changed="handleReviewChanged"
+        />
+      </div>
+    </el-dialog>
+  </section>
+</template>
+
+<style scoped>
+.inbound-workspace { min-width: 0; }
+.workspace-header { display: flex; align-items: flex-start; justify-content: space-between; gap: 20px; padding: 18px 24px 16px; border-bottom: 1px solid var(--cc-border); }
+.workspace-title-row { display: flex; min-width: 0; align-items: center; flex-wrap: wrap; gap: 10px; }
+.workspace-title-row h2 { margin: 0; overflow-wrap: anywhere; color: #172033; font-size: 16px; line-height: 1.35; }
+.workspace-header p { margin: 5px 0 0; color: var(--cc-muted); font-size: 12px; line-height: 1.5; }
+.workspace-state { margin: 24px; }
+.workspace-skeleton { padding: 0; }
+.workflow-tabs { min-width: 0; padding: 0 24px 24px; }
+.workflow-tabs :deep(.el-tabs__header) { margin-bottom: 20px; }
+.workflow-tabs :deep(.el-tabs__nav-wrap::after) { height: 1px; background: var(--cc-border); }
+.workflow-tabs :deep(.el-tabs__active-bar) { height: 2px; background: var(--cc-primary); }
+.workflow-tabs :deep(.el-tabs__item) { min-height: 44px; padding: 0 18px; color: #475467; font-size: 13px; font-weight: 500; }
+.workflow-tabs :deep(.el-tabs__item.is-active) { color: var(--cc-primary); font-weight: 650; }
+.workflow-action-row { display: flex; min-width: 0; align-items: center; justify-content: space-between; gap: 16px; padding: 0 0 14px; border-bottom: 1px solid var(--cc-border); color: var(--cc-muted); font-size: 12px; line-height: 1.5; }
+.inbound-operation-dialog__body { min-width: 0; }
+:global(.inbound-operation-dialog.el-dialog) { display: flex; max-width: calc(100vw - 32px); height: 92vh; max-height: 92vh; margin-bottom: 0; flex-direction: column; overflow: hidden; }
+:global(.inbound-operation-dialog .el-dialog__header) { flex: 0 0 auto; margin: 0; padding: 18px 24px; border-bottom: 1px solid var(--cc-border); }
+:global(.inbound-operation-dialog .el-dialog__body) { min-height: 0; flex: 1 1 auto; overflow-y: auto; padding: 20px 24px; }
+@media (max-width: 720px) {
+  .workspace-header { align-items: stretch; flex-direction: column; padding: 16px; }
+  .workspace-header :deep(.el-button) { width: 100%; min-height: 44px; }
+  .workspace-state { margin: 16px; }
+  .workflow-tabs { padding: 0 16px 16px; }
+  .workflow-tabs :deep(.el-tabs__nav-wrap) { overflow-x: auto; }
+  .workflow-tabs :deep(.el-tabs__item) { min-height: 44px; padding-inline: 14px; }
+  .workflow-action-row { align-items: stretch; flex-direction: column; }
+  .workflow-action-row :deep(.el-button) { width: 100%; min-height: 44px; }
+  :global(.inbound-operation-dialog.el-dialog) { width: calc(100vw - 20px) !important; max-width: calc(100vw - 20px); height: 92vh; }
+  :global(.inbound-operation-dialog .el-dialog__header) { padding: 16px; }
+  :global(.inbound-operation-dialog .el-dialog__body) { padding: 14px; }
+}
+@media (max-width: 360px) {
+  :global(.inbound-operation-dialog.el-dialog) { width: calc(100vw - 12px) !important; max-width: calc(100vw - 12px); }
+  :global(.inbound-operation-dialog .el-dialog__header) { padding: 14px 12px; }
+  :global(.inbound-operation-dialog .el-dialog__body) { padding: 10px; }
+}
+</style>
diff --git a/src/modules/inbounds/core/DropshipPalletPrintPanel.test.ts b/src/modules/inbounds/core/DropshipPalletPrintPanel.test.ts
new file mode 100644
index 00000000..0141f44e
--- /dev/null
+++ b/src/modules/inbounds/core/DropshipPalletPrintPanel.test.ts
@@ -0,0 +1,29 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/inbounds/core/DropshipPalletPrintPanel.vue'), 'utf8')
+
+describe('DropshipPalletPrintPanel', () => {
+  it('explains whole-pallet box totals and distinct SKU codes rather than item quantities', () => {
+    expect(source).toContain('prop="cartonCount" label="整托箱数"')
+    expect(source).toContain('prop="skuCount" label="SKU 种类数"')
+    expect(source).toContain('包含合托的其他入仓码')
+    expect(source).toContain('相同 SKU 编码只计一种，不代表商品件数')
+  })
+  it('provides desktop batch printing and single-pallet reprinting', () => {
+    expect(source).toContain('一件代发托盘打印')
+    expect(source).toContain('打印全部托盘')
+    expect(source).toContain('单托补打')
+    expect(source).toContain('downloadAllDropshipPalletLabels')
+    expect(source).toContain('downloadDropshipPalletLabel')
+    expect(source).toContain('label="操作" width="120" fixed="left"')
+  })
+
+  it('explains the computer-first printing flow and covers loading, empty and error states', () => {
+    expect(source).toContain('在电脑端打印并贴到空托盘，再交由 PDA 扫码组托')
+    expect(source).toContain('v-loading="loading"')
+    expect(source).toContain('测量审核通过并生成托盘码后，可在这里打印')
+    expect(source).toContain('托盘数据暂时无法加载')
+  })
+})
diff --git a/src/modules/inbounds/core/DropshipPalletPrintPanel.vue b/src/modules/inbounds/core/DropshipPalletPrintPanel.vue
new file mode 100644
index 00000000..f07f6b2f
--- /dev/null
+++ b/src/modules/inbounds/core/DropshipPalletPrintPanel.vue
@@ -0,0 +1,128 @@
+<script setup lang="ts">
+import { onBeforeUnmount, ref, watch } from 'vue'
+import { Printer, RefreshCw } from '@lucide/vue'
+import { ElMessage } from 'element-plus'
+import '@/styles/adminDensity.css'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { downloadAllDropshipPalletLabels, downloadDropshipPalletLabel, listPlatformInboundDropshipPallets } from './api'
+import type { InboundDropshipPallet } from './types'
+
+const props = defineProps<{
+  customerId: string
+  inboundId: string
+  inboundCode?: string | null
+}>()
+
+const pallets = ref<InboundDropshipPallet[]>([])
+const loading = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const printing = ref('')
+let requestSerial = 0
+let disposed = false
+
+function statusLabel(status: InboundDropshipPallet['status']) {
+  return status === 'SEALED' ? '已封托' : '待封托'
+}
+
+function download(blob: Blob, fileName: string) {
+  const url = URL.createObjectURL(blob)
+  const link = document.createElement('a')
+  link.href = url
+  link.download = fileName
+  link.click()
+  window.setTimeout(() => URL.revokeObjectURL(url), 0)
+}
+
+async function loadPallets() {
+  const serial = ++requestSerial
+  loading.value = true
+  loadError.value = null
+  try {
+    const response = await listPlatformInboundDropshipPallets(props.customerId, props.inboundId)
+    if (!disposed && serial === requestSerial) pallets.value = response
+  } catch (error) {
+    if (!disposed && serial === requestSerial) {
+      pallets.value = []
+      loadError.value = getApiErrorDetails(error, '一件代发托盘加载失败')
+    }
+  } finally {
+    if (!disposed && serial === requestSerial) loading.value = false
+  }
+}
+
+async function printAll() {
+  if (!pallets.value.length || printing.value) return
+  printing.value = 'all'
+  try {
+    const blob = await downloadAllDropshipPalletLabels(props.customerId, props.inboundId)
+    download(blob, `${props.inboundCode || '一件代发'}-全部托盘.pdf`)
+    ElMessage.success(`已生成 ${pallets.value.length} 个托盘的打印文件`)
+  } catch (error) {
+    ElMessage.error(getApiErrorDetails(error, '全部托盘打印文件生成失败').message)
+  } finally {
+    printing.value = ''
+  }
+}
+
+async function printOne(pallet: InboundDropshipPallet) {
+  if (!pallet.palletNo || printing.value) return
+  printing.value = pallet.palletId
+  try {
+    const blob = await downloadDropshipPalletLabel(props.customerId, props.inboundId, pallet.palletId)
+    download(blob, `${pallet.palletNo}-托盘.pdf`)
+    ElMessage.success(`${pallet.palletNo} 打印文件已生成`)
+  } catch (error) {
+    ElMessage.error(getApiErrorDetails(error, '单托打印文件生成失败').message)
+  } finally {
+    printing.value = ''
+  }
+}
+
+watch(() => [props.customerId, props.inboundId], loadPallets, { immediate: true })
+onBeforeUnmount(() => { disposed = true; requestSerial += 1 })
+</script>
+
+<template>
+  <section class="dropship-print-panel admin-density" aria-labelledby="dropship-print-title">
+    <header class="print-heading">
+      <div>
+        <h3 id="dropship-print-title">一件代发托盘打印</h3>
+        <p>测量审核生成托盘码后，在电脑端打印并贴到空托盘，再交由 PDA 扫码组托。</p>
+        <p>箱数与 SKU 种类数按整托统计，包含合托的其他入仓码；相同 SKU 编码只计一种，不代表商品件数。</p>
+      </div>
+      <div class="print-actions">
+        <el-button :disabled="loading || Boolean(printing)" @click="loadPallets"><RefreshCw :size="15" />刷新</el-button>
+        <el-button type="primary" :disabled="!pallets.length" :loading="printing === 'all'" @click="printAll"><Printer :size="15" />打印全部托盘</el-button>
+      </div>
+    </header>
+
+    <LoadErrorState v-if="loadError" title="托盘数据暂时无法加载" :message="loadError.message" @retry="loadPallets">
+      <template #details><ApiErrorMeta :details="loadError" /></template>
+    </LoadErrorState>
+    <el-table v-else-if="pallets.length" v-loading="loading" :data="pallets" border stripe empty-text="暂无托盘码" aria-label="一件代发托盘打印列表">
+      <el-table-column label="操作" width="120" fixed="left">
+        <template #default="{ row }">
+          <el-button class="density-action" :loading="printing === row.palletId" :disabled="Boolean(printing) && printing !== row.palletId" @click="printOne(row as InboundDropshipPallet)">单托补打</el-button>
+        </template>
+      </el-table-column>
+      <el-table-column prop="palletNo" label="托盘码" min-width="210" />
+      <el-table-column label="状态" width="110"><template #default="{ row }"><el-tag size="small" :type="row.status === 'SEALED' ? 'success' : 'warning'" effect="plain">{{ statusLabel(row.status) }}</el-tag></template></el-table-column>
+      <el-table-column prop="cartonCount" label="整托箱数" width="120" align="right" />
+      <el-table-column prop="skuCount" label="SKU 种类数" width="120" align="right" />
+    </el-table>
+    <el-empty v-else-if="!loading" description="测量审核通过并生成托盘码后，可在这里打印" :image-size="64" />
+    <div v-else class="loading-state"><el-skeleton :rows="4" animated /></div>
+  </section>
+</template>
+
+<style scoped>
+.dropship-print-panel { min-width: 0; }
+.print-heading { display: flex; align-items: flex-start; justify-content: space-between; gap: var(--admin-space-5); margin-bottom: var(--admin-space-5); }
+.print-heading h3 { margin: 0; color: var(--cc-text); font-size: var(--admin-font-section); }
+.print-heading p { margin: var(--admin-space-1) 0 0; color: var(--cc-muted); font-size: var(--admin-font-caption); line-height: 1.5; }
+.print-actions { display: flex; flex-shrink: 0; gap: var(--admin-space-2); }
+.print-actions .el-button { margin-left: 0; }
+.loading-state { padding: var(--admin-space-5) 0; }
+</style>
diff --git a/src/modules/inbounds/core/InboundHistoryPanel.test.ts b/src/modules/inbounds/core/InboundHistoryPanel.test.ts
new file mode 100644
index 00000000..410a8fe8
--- /dev/null
+++ b/src/modules/inbounds/core/InboundHistoryPanel.test.ts
@@ -0,0 +1,22 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/inbounds/core/InboundHistoryPanel.vue'), 'utf8')
+
+describe('InboundHistoryPanel dropship pallet result', () => {
+  it('shows the frozen pallet, carton and discrepancy facts', () => {
+    for (const marker of [
+      '一件代发清点与组托结果', 'pallet.palletNo', 'pallet.status', 'pallet.cartonCount',
+      'pallet.skuCount', 'pallet.weightKg', 'pallet.volumeCbm', 'pallet.discrepancyCartons', 'pallet.sealedAt',
+      'item.inboundCode', 'item.skuCode', 'item.cargoName', 'item.skuQuantity', 'item.cartonCount', 'item.cartonMarks',
+    ]) expect(source).toContain(marker)
+    expect(source).toContain("SEALED: '已封托'")
+  })
+
+  it('keeps the existing scoped pallet-label action available', () => {
+    expect(source).toContain('downloadDropshipPalletLabel(props.customerId, props.inboundId, pallet.palletId)')
+    expect(source).toContain('v-if="pallet.palletNo"')
+    expect(source).toContain('打印托盘码')
+  })
+})
diff --git a/src/modules/inbounds/core/InboundHistoryPanel.vue b/src/modules/inbounds/core/InboundHistoryPanel.vue
new file mode 100644
index 00000000..3ee36b71
--- /dev/null
+++ b/src/modules/inbounds/core/InboundHistoryPanel.vue
@@ -0,0 +1,156 @@
+<script setup lang="ts">
+import type { InboundDropshipPallet, InboundFileSummary, InboundInternalNote, InboundPalletLocation, InboundStatusHistory } from './types'
+import { inboundHistoryActionLabel, inboundProcessStatusLabels, inboundStatusLabel } from '../status'
+import { downloadDropshipPalletLabel } from './api'
+import { ElMessage } from 'element-plus'
+
+const props = withDefaults(defineProps<{
+  palletLocations: InboundPalletLocation[]
+  dropshipPallets?: InboundDropshipPallet[]
+  customerId?: string
+  inboundId?: string
+  canViewDropship?: boolean
+  files: InboundFileSummary[]
+  internalNotes: InboundInternalNote[]
+  statusHistory: InboundStatusHistory[]
+  publicRemark: string | null
+  sections?: Array<'dropship' | 'allocations' | 'files' | 'notes' | 'history' | 'remark'>
+}>(), {
+  dropshipPallets: () => [],
+  canViewDropship: true,
+  sections: () => ['dropship', 'allocations', 'files', 'notes', 'history', 'remark'],
+})
+
+function shows(section: 'dropship' | 'allocations' | 'files' | 'notes' | 'history' | 'remark') {
+  return props.sections.includes(section)
+}
+
+function value(value: string | number | null | undefined) { return value === null || value === undefined || value === '' ? '—' : String(value) }
+function number(value: number | null) { return value === null ? '—' : value.toFixed(3) }
+function date(value: string | null) {
+  if (!value) return '—'
+  const parsed = new Date(value)
+  return Number.isNaN(parsed.getTime()) ? value : parsed.toLocaleString('zh-CN', { hour12: false })
+}
+function dropshipPalletStatus(value: string) {
+  return ({ OPEN: '清点组托中', SEALED: '已封托' } as Record<string, string>)[value] || value || '状态未知'
+}
+async function printPallet(pallet: InboundDropshipPallet) {
+  if (!props.customerId || !props.inboundId || !pallet.palletNo) return
+  try {
+    const blob = await downloadDropshipPalletLabel(props.customerId, props.inboundId, pallet.palletId)
+    const url = URL.createObjectURL(blob)
+    const link = document.createElement('a'); link.href = url; link.download = `${pallet.palletNo}-托盘唛.pdf`; link.click()
+    URL.revokeObjectURL(url)
+  } catch { ElMessage.error('托盘唛下载失败，请稍后重试') }
+}
+</script>
+
+<template>
+  <div class="history-panel">
+    <section v-if="shows('dropship')" class="history-section">
+      <div class="section-heading"><h3>一件代发清点与组托结果</h3><span>{{ dropshipPallets.length }} 个托盘</span></div>
+      <el-alert v-if="!canViewDropship" title="当前账号缺少一件代发 PDA 查看权限，无法读取清点组托结果。" type="warning" :closable="false" show-icon />
+      <div v-else-if="dropshipPallets.length" class="dropship-pallet-list">
+        <article v-for="pallet in dropshipPallets" :key="pallet.palletId" class="dropship-pallet-card">
+          <header>
+            <div><strong>{{ value(pallet.palletNo) }}</strong><el-tag size="small" :type="pallet.status === 'SEALED' ? 'success' : 'warning'" effect="plain">{{ dropshipPalletStatus(pallet.status) }}</el-tag></div>
+            <el-button v-if="pallet.palletNo" link type="primary" @click="printPallet(pallet)">打印托盘码</el-button>
+          </header>
+          <dl class="dropship-pallet-summary">
+            <div><dt>箱数</dt><dd>{{ pallet.cartonCount }}</dd></div>
+            <div><dt>SKU 数</dt><dd>{{ pallet.skuCount }}</dd></div>
+            <div><dt>毛重</dt><dd>{{ number(pallet.weightKg) }} kg</dd></div>
+            <div><dt>体积</dt><dd>{{ number(pallet.volumeCbm) }} m³</dd></div>
+            <div><dt>差异箱数</dt><dd><el-tag size="small" :type="pallet.discrepancyCartons ? 'warning' : 'success'">{{ pallet.discrepancyCartons }}</el-tag></dd></div>
+            <div><dt>封托时间</dt><dd>{{ date(pallet.sealedAt) }}</dd></div>
+          </dl>
+          <div class="dropship-item-table">
+            <div class="dropship-item-row dropship-item-row--header"><span>入仓码</span><span>SKU / 货物</span><span>商品数量</span><span>箱数</span><span>箱码</span></div>
+            <div v-for="item in pallet.items" :key="`${pallet.palletId}-${item.inboundDetailId}`" class="dropship-item-row">
+              <span>{{ value(item.inboundCode) }}</span>
+              <span><strong>{{ value(item.skuCode) }}</strong><small>{{ value(item.cargoName) }}</small></span>
+              <span>{{ item.skuQuantity }}</span>
+              <span>{{ item.cartonCount }}</span>
+              <span>{{ item.cartonMarks.length ? item.cartonMarks.join('、') : '—' }}</span>
+            </div>
+          </div>
+        </article>
+      </div>
+      <p v-else class="muted-empty">暂无一件代发清点与组托结果</p>
+    </section>
+    <section v-if="shows('allocations')" class="history-section">
+      <div class="section-heading"><h3>托盘与库位</h3><span>{{ palletLocations.length }} 条分配</span></div>
+      <div v-if="palletLocations.length" class="allocation-list">
+        <div v-for="item in palletLocations" :key="`${item.allocationNo}-${item.palletId}-${item.locationId}`" class="allocation-row">
+          <div><strong>{{ value(item.palletCode) }}</strong><span>分配 {{ value(item.allocationNo) }}</span></div>
+          <div><span>{{ number(item.allocatedVolumeCbm) }} CBM</span><span>{{ value(item.allocatedPackageCount) }} 箱</span></div>
+          <div class="allocation-location">{{ value(item.locationCode) }}</div>
+        </div>
+      </div>
+      <p v-else class="muted-empty">暂无托盘库位分配记录</p>
+    </section>
+    <section v-if="shows('files')" class="history-section">
+      <div class="section-heading"><h3>文件记录</h3><span>{{ files.length }} 个文件</span></div>
+      <div v-if="files.length" class="simple-list"><div v-for="file in files" :key="`${file.fileId}-${file.fileVersion}`"><strong>{{ value(file.fileNameSnapshot) }}</strong><span>{{ value(file.fileType) }} · {{ date(file.uploadedAt) }}</span></div></div>
+      <p v-else class="muted-empty">暂无文件记录</p>
+    </section>
+    <section v-if="shows('notes')" class="history-section">
+      <div class="section-heading"><h3>内部备注</h3><span>{{ internalNotes.length }} 条</span></div>
+      <div v-if="internalNotes.length" class="simple-list"><div v-for="note in internalNotes" :key="String(note.id)"><strong>{{ value(note.createdByName || note.createdBy) }}</strong><span>{{ value(note.content) }} · {{ date(note.createdAt) }}</span></div></div>
+      <p v-else class="muted-empty">暂无内部备注</p>
+    </section>
+    <section v-if="shows('history')" class="history-section">
+      <div class="section-heading"><h3>状态历史</h3><span>{{ statusHistory.length }} 条</span></div>
+      <ol v-if="statusHistory.length" class="timeline"><li v-for="(history, index) in statusHistory" :key="`${history.occurredAt}-${index}`"><span class="timeline-dot" /><div><strong>{{ inboundHistoryActionLabel(history.action) }}</strong><span>{{ inboundStatusLabel(history.fromStatus, inboundProcessStatusLabels) }} → {{ inboundStatusLabel(history.toStatus, inboundProcessStatusLabels) }} · {{ value(history.operatorName || history.operatorId) }}</span><small>{{ date(history.occurredAt) }}<template v-if="history.reason"> · {{ history.reason }}</template></small></div></li></ol>
+      <p v-else class="muted-empty">暂无状态历史</p>
+    </section>
+    <section v-if="shows('remark') && publicRemark" class="history-section remark-section"><div class="section-heading"><h3>公开备注</h3></div><p>{{ publicRemark }}</p></section>
+  </div>
+</template>
+
+<style scoped>
+.history-panel { display: grid; gap: 24px; min-width: 0; }
+.history-section { min-width: 0; padding-top: 16px; border-top: 1px solid var(--cc-border); }
+.history-section:first-child { padding-top: 0; border-top: 0; }
+.section-heading { display: flex; align-items: baseline; justify-content: space-between; gap: 12px; margin-bottom: 12px; }
+.section-heading h3 { margin: 0; color: #172033; font-size: 13px; }
+.section-heading span { color: var(--cc-muted); font-size: 12px; }
+.allocation-list, .simple-list { overflow: hidden; border: 1px solid var(--cc-border); border-radius: 6px; background: #fff; }
+.allocation-row { display: grid; grid-template-columns: 1fr auto minmax(100px, 0.8fr); gap: 12px; align-items: center; padding: 10px 12px; border-bottom: 1px solid #edf0f4; font-size: 12px; }
+.allocation-row:last-child, .simple-list > div:last-child { border-bottom: 0; }
+.allocation-row > div, .simple-list > div { min-width: 0; }
+.allocation-row span, .simple-list span { display: block; margin-top: 3px; color: var(--cc-muted); }
+.allocation-location { overflow-wrap: anywhere; color: var(--cc-primary); text-align: right; }
+.simple-list > div { padding: 10px 12px; border-bottom: 1px solid #edf0f4; font-size: 12px; }
+.simple-list strong, .simple-list span { overflow-wrap: anywhere; }
+.dropship-pallet-list { display: grid; gap: 12px; }
+.dropship-pallet-card { min-width: 0; overflow: hidden; border: 1px solid var(--cc-border); border-radius: 6px; background: #fff; }
+.dropship-pallet-card > header { display: flex; min-height: 42px; align-items: center; justify-content: space-between; gap: 12px; padding: 8px 12px; border-bottom: 1px solid #edf0f4; background: #f8fafc; }
+.dropship-pallet-card > header > div { display: flex; min-width: 0; align-items: center; gap: 8px; }
+.dropship-pallet-card > header strong { overflow-wrap: anywhere; color: #172033; font-size: 13px; }
+.dropship-pallet-summary { display: grid; grid-template-columns: repeat(6, minmax(0, 1fr)); margin: 0; border-bottom: 1px solid #edf0f4; }
+.dropship-pallet-summary > div { min-width: 0; padding: 8px 12px; border-right: 1px solid #edf0f4; }
+.dropship-pallet-summary > div:last-child { border-right: 0; }
+.dropship-pallet-summary dt { color: var(--cc-muted); font-size: 11px; }
+.dropship-pallet-summary dd { margin: 3px 0 0; overflow-wrap: anywhere; color: var(--cc-text); font-size: 12px; font-weight: 650; }
+.dropship-item-table { min-width: 680px; }
+.dropship-pallet-card { overflow-x: auto; }
+.dropship-item-row { display: grid; grid-template-columns: minmax(140px, 1fr) minmax(180px, 1.2fr) 100px 70px minmax(220px, 1.5fr); min-width: 800px; border-bottom: 1px solid #edf0f4; }
+.dropship-item-row:last-child { border-bottom: 0; }
+.dropship-item-row > span { min-width: 0; padding: 8px 12px; overflow-wrap: anywhere; color: var(--cc-text); font-size: 12px; }
+.dropship-item-row > span + span { border-left: 1px solid #edf0f4; }
+.dropship-item-row small { display: block; margin-top: 3px; color: var(--cc-muted); font-size: 11px; }
+.dropship-item-row--header { background: #f8fafc; }
+.dropship-item-row--header > span { color: var(--cc-muted); font-size: 11px; font-weight: 650; }
+.muted-empty { margin: 0; padding: 18px 12px; border: 1px dashed var(--cc-border); border-radius: 6px; background: #f8fafc; color: var(--cc-muted); font-size: 12px; text-align: center; }
+.timeline { display: grid; gap: 0; margin: 0; padding: 0; list-style: none; }
+.timeline li { display: grid; grid-template-columns: 16px 1fr; gap: 10px; min-width: 0; padding-bottom: 16px; }
+.timeline-dot { width: 8px; height: 8px; margin-top: 5px; border: 2px solid var(--cc-primary); border-radius: 50%; background: #fff; box-shadow: 0 0 0 3px color-mix(in srgb, var(--cc-primary) 12%, transparent); }
+.timeline li > div { min-width: 0; padding-bottom: 12px; border-bottom: 1px solid #edf0f4; }
+.timeline strong, .timeline span, .timeline small { display: block; overflow-wrap: anywhere; }
+.timeline span, .timeline small { margin-top: 3px; color: var(--cc-muted); font-size: 12px; line-height: 1.5; }
+.remark-section p { margin: 0; padding: 12px; border-radius: 6px; background: #f8fafc; color: var(--cc-text); font-size: 13px; line-height: 1.6; white-space: pre-wrap; }
+@media (max-width: 720px) { .dropship-pallet-summary { grid-template-columns: 1fr; } .dropship-pallet-summary > div { border-right: 0; border-bottom: 1px solid #edf0f4; } .dropship-pallet-summary > div:last-child { border-bottom: 0; } }
+@media (max-width: 480px) { .allocation-row { grid-template-columns: 1fr auto; } .allocation-location { grid-column: 1 / -1; text-align: left; } }
+</style>
diff --git a/src/modules/inbounds/core/InboundSummaryPanel.test.ts b/src/modules/inbounds/core/InboundSummaryPanel.test.ts
new file mode 100644
index 00000000..4197c28f
--- /dev/null
+++ b/src/modules/inbounds/core/InboundSummaryPanel.test.ts
@@ -0,0 +1,36 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/inbounds/core/InboundSummaryPanel.vue'), 'utf8')
+
+describe('InboundSummaryPanel', () => {
+  it('organizes the aggregate detail into the prototype-aligned backend-backed sections', () => {
+    expect(source).toContain('基本信息')
+    expect(source).toContain('仓库与运输')
+    expect(source).toContain('测量与计费')
+    expect(source).toContain('入库资源')
+    expect(source).toContain('summary.deliveryWarehouseName')
+    expect(source).toContain('summary.chargeableWeightKg')
+    expect(source).toContain('summary.locationCodes')
+    expect(source).toContain('summary.notificationStatus')
+    expect(source).toContain('publicRemark')
+    expect(source).toContain('买单 / 退税')
+    expect(source).toContain('计费毛重')
+  })
+
+  it('does not restore excluded receiving review or customer fee confirmation actions', () => {
+    expect(source).not.toContain('接收审核')
+    expect(source).not.toContain('客户确认费用')
+  })
+
+  it('renders aggregate statuses through the inbound translation contract', () => {
+    expect(source).toContain('inboundOrderStatusLabels')
+    expect(source).toContain('inboundLoadingStatusLabels')
+    expect(source).toContain('inboundReviewStatusLabels')
+    expect(source).not.toContain('{{ value(summary.orderStatusSnapshot) }}')
+    expect(source).toContain('firstLegBusinessTypeLabel(summary.businessType)')
+    expect(source).toContain('firstLegTaxModeLabel(summary.taxMode)')
+    expect(source).toContain('firstLegDestinationTypeLabel(summary.destinationType)')
+  })
+})
diff --git a/src/modules/inbounds/core/InboundSummaryPanel.vue b/src/modules/inbounds/core/InboundSummaryPanel.vue
new file mode 100644
index 00000000..412b83fc
--- /dev/null
+++ b/src/modules/inbounds/core/InboundSummaryPanel.vue
@@ -0,0 +1,123 @@
+<script setup lang="ts">
+import { Box, MapPin, Scale, Warehouse } from '@lucide/vue'
+import { firstLegBusinessTypeLabel, firstLegContainerModeLabel, firstLegDestinationTypeLabel, firstLegTaxModeLabel } from '@/shared/utils/firstLegBusinessLabels'
+import type { InboundOrderSummary } from './types'
+import { inboundFeeStatusLabels, inboundLoadingStatusLabels, inboundNotificationStatusLabels, inboundOrderStatusLabels, inboundProcessStatusLabels, inboundReviewStatusLabels, inboundStatusLabel } from '../status'
+
+withDefaults(defineProps<{ summary: InboundOrderSummary; publicRemark?: string | null }>(), { publicRemark: null })
+
+function processLabel(status: string) { return inboundStatusLabel(status, inboundProcessStatusLabels, '未知状态') }
+function processType(status: string) {
+  if (status === 'WAIT_SPLIT') return 'success'
+  if (status === 'MEASURE_REJECTED' || status === 'VOIDED') return 'danger'
+  if (status === 'MEASURING' || status === 'INBOUNDING') return 'info'
+  return 'warning'
+}
+function value(value: string | number | null | undefined) { return value === null || value === undefined || value === '' ? '—' : String(value) }
+function number(value: number | null, digits = 3) { return value === null ? '—' : value.toFixed(digits) }
+function date(value: string | null) {
+  if (!value) return '—'
+  const parsed = new Date(value)
+  return Number.isNaN(parsed.getTime()) ? value : parsed.toLocaleString('zh-CN', { hour12: false })
+}
+function yesNo(value: boolean | null) { return value === null ? '—' : value ? '是' : '否' }
+function label(value: string | null, labels: Record<string, string>) { return inboundStatusLabel(value, labels) }
+</script>
+
+<template>
+  <section class="summary-panel" aria-label="入库单概览">
+    <div class="summary-heading">
+      <span class="summary-icon" aria-hidden="true"><Box :size="20" /></span>
+      <div class="summary-title">
+        <h3>入仓码：{{ summary.inboundCode || '暂缺' }}</h3>
+        <p class="summary-subtitle">{{ value(summary.customerName) }}</p>
+      </div>
+      <el-tag :type="processType(summary.processStatus)" effect="light">{{ processLabel(summary.processStatus) }}</el-tag>
+    </div>
+    <p v-if="summary.holdFlag" class="hold-note" role="status">当前挂起：{{ summary.currentHoldReason || '待处理异常' }}</p>
+    <div class="summary-sections">
+      <section aria-labelledby="inbound-basic-heading">
+        <h4 id="inbound-basic-heading">基本信息</h4>
+        <dl class="summary-grid">
+          <div><dt>订单状态</dt><dd>{{ label(summary.orderStatusSnapshot, inboundOrderStatusLabels) }}</dd></div>
+          <div><dt>客户</dt><dd>{{ value(summary.customerName) }}</dd></div>
+          <div><dt>公司</dt><dd>{{ value(summary.companyName) }}</dd></div>
+          <div><dt>业务类型</dt><dd>{{ firstLegBusinessTypeLabel(summary.businessType) }}</dd></div>
+          <div><dt>渠道</dt><dd>{{ value(summary.channelName || summary.channelCode) }}</dd></div>
+          <div><dt>买单 / 退税</dt><dd>{{ firstLegTaxModeLabel(summary.taxMode) }}</dd></div>
+          <div><dt>是否整柜</dt><dd>{{ firstLegContainerModeLabel(summary.containerMode) }}</dd></div>
+          <div><dt>商检验</dt><dd>{{ yesNo(summary.customsInspection) }}</dd></div>
+          <div><dt>备注</dt><dd>{{ value(publicRemark) }}</dd></div>
+          <div><dt>创建时间</dt><dd>{{ date(summary.createdAt) }}</dd></div>
+        </dl>
+      </section>
+
+      <section aria-labelledby="inbound-route-heading">
+        <h4 id="inbound-route-heading">仓库与运输</h4>
+        <dl class="summary-grid">
+          <div><dt><Warehouse :size="14" />收货仓</dt><dd>{{ value(summary.warehouseName) }}</dd></div>
+          <div><dt>交货仓</dt><dd>{{ value(summary.deliveryWarehouseName) }}</dd></div>
+          <div><dt><MapPin :size="14" />目的仓</dt><dd>{{ value(summary.destinationName || summary.destinationCode) }}</dd></div>
+          <div><dt>目的仓类型</dt><dd>{{ firstLegDestinationTypeLabel(summary.destinationType) }}</dd></div>
+          <div><dt>集装箱号</dt><dd>{{ value(summary.containerNo) }}</dd></div>
+          <div><dt>柜号</dt><dd>{{ value(summary.cabinetNo) }}</dd></div>
+          <div><dt>船名 / 航次</dt><dd>{{ value(summary.vesselName) }} / {{ value(summary.voyageNo) }}</dd></div>
+          <div><dt>配载状态</dt><dd>{{ label(summary.loadingStatus, inboundLoadingStatusLabels) }}</dd></div>
+          <div><dt>预计到达</dt><dd>{{ date(summary.expectedArrivalAt) }}</dd></div>
+          <div><dt>开船 / 到港</dt><dd>{{ date(summary.sailingAt) }} / {{ date(summary.portArrivalAt) }}</dd></div>
+          <div><dt>快递公司</dt><dd>{{ value(summary.expressCompanyName || summary.expressCompanyCode) }}</dd></div>
+          <div><dt>快递单号</dt><dd>{{ value(summary.expressTrackingNo) }}</dd></div>
+        </dl>
+      </section>
+
+      <section aria-labelledby="inbound-measure-heading">
+        <h4 id="inbound-measure-heading">测量与计费</h4>
+        <dl class="summary-grid">
+          <div><dt><Box :size="14" />总箱数</dt><dd>{{ value(summary.totalPackageCount) }} 箱</dd></div>
+          <div><dt><Scale :size="14" />总毛重 (T.K.GW)</dt><dd>{{ number(summary.actualGrossWeightKg) }} kg</dd></div>
+          <div><dt>总净重 (T.K.NW)</dt><dd>{{ number(summary.actualNetWeightKg) }} kg</dd></div>
+          <div><dt>总体积</dt><dd>{{ number(summary.actualVolumeCbm) }} CBM</dd></div>
+          <div><dt>总材积重</dt><dd>{{ number(summary.volumeWeightKg) }} kg</dd></div>
+          <div><dt>计费毛重</dt><dd>{{ number(summary.chargeableWeightKg) }} kg</dd></div>
+          <div><dt>计费体积</dt><dd>{{ number(summary.chargeableVolumeCbm) }} CBM</dd></div>
+          <div><dt>测量审核</dt><dd>{{ label(summary.measureReviewStatus, inboundReviewStatusLabels) }}</dd></div>
+          <div><dt>费用状态</dt><dd>{{ label(summary.feeStatus, inboundFeeStatusLabels) }}</dd></div>
+          <div><dt>费用审核状态</dt><dd>{{ label(summary.feeReviewStatus, inboundReviewStatusLabels) }}</dd></div>
+          <div><dt>测量完成时间</dt><dd>{{ date(summary.measureCompletedAt) }}</dd></div>
+          <div><dt>通知状态</dt><dd>{{ label(summary.notificationStatus, inboundNotificationStatusLabels) }}</dd></div>
+        </dl>
+      </section>
+
+      <section aria-labelledby="inbound-storage-heading">
+        <h4 id="inbound-storage-heading">入库资源</h4>
+        <dl class="summary-grid">
+          <div><dt>总托盘数</dt><dd>{{ value(summary.palletCount) }}</dd></div>
+          <div><dt>库位位置</dt><dd>{{ value(summary.locationCodes) }}</dd></div>
+          <div><dt>入库完成时间</dt><dd>{{ date(summary.inboundedAt) }}</dd></div>
+          <div><dt>最后更新时间</dt><dd>{{ date(summary.updatedAt) }}</dd></div>
+        </dl>
+      </section>
+    </div>
+  </section>
+</template>
+
+<style scoped>
+.summary-panel { min-width: 0; }
+.summary-heading { display: grid; grid-template-columns: 36px minmax(0, 1fr) auto; align-items: center; gap: 10px; padding-bottom: 18px; border-bottom: 1px solid var(--cc-border); }
+.summary-icon { display: grid; width: 36px; height: 36px; place-items: center; border-radius: 8px; background: #172033; color: #fff; }
+.summary-title { min-width: 0; }
+h3 { margin: 0; overflow-wrap: anywhere; color: #172033; font-size: 16px; line-height: 1.35; }
+.summary-subtitle { margin: 6px 0 0; color: var(--cc-muted); font-size: 12px; }
+.summary-sections { display: grid; min-width: 0; gap: 24px; margin-top: 18px; }
+.summary-sections section { min-width: 0; padding-top: 16px; border-top: 1px solid var(--cc-border); }
+.summary-sections section:first-child { padding-top: 0; border-top: 0; }
+h4 { margin: 0 0 12px; color: #172033; font-size: 13px; line-height: 1.4; }
+.summary-grid { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 12px 24px; margin: 0; color: #475467; }
+.summary-grid > div { display: grid; min-width: 0; grid-template-columns: max-content minmax(0, 1fr); align-items: baseline; gap: 4px; min-height: 26px; line-height: 1.7; }
+dt { display: flex; align-items: center; gap: 6px; color: var(--cc-muted); font-size: 12px; white-space: nowrap; }
+dt::after { content: "："; }
+dd { margin: 0; overflow-wrap: anywhere; color: #475467; font-size: 13px; line-height: 1.7; }
+.hold-note { margin: 16px 0 0; padding: 10px 12px; border: 1px solid var(--cc-border); border-radius: 8px; background: #fffaeb; color: #b54708; font-size: 12px; line-height: 1.5; }
+@media (max-width: 900px) { .summary-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); } }
+@media (max-width: 480px) { .summary-heading { grid-template-columns: 36px minmax(0, 1fr); align-items: start; } .summary-heading :deep(.el-tag) { grid-column: 2; justify-self: start; } .summary-grid { grid-template-columns: 1fr; } .summary-grid > div { grid-template-columns: 1fr; gap: 1px; } dt::after { content: ""; } }
+</style>
diff --git a/src/modules/inbounds/core/api.test.ts b/src/modules/inbounds/core/api.test.ts
new file mode 100644
index 00000000..3fce2fed
--- /dev/null
+++ b/src/modules/inbounds/core/api.test.ts
@@ -0,0 +1,215 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import { downloadAllDropshipPalletLabels, downloadDropshipPalletLabel, downloadInboundCartonLabels, downloadInboundCartonLabelsBatch, downloadPlatformInboundHoldEvidence, getPlatformInbound, getPlatformInboundHold, holdPlatformInbound, listPlatformInboundDropshipPallets, listPlatformInbounds, releasePlatformInbound, uploadPlatformInboundHoldEvidence } from './api'
+
+vi.mock('@/shared/api/http', () => ({
+  ApiResponseError: class ApiResponseError extends Error {
+    code: string
+    constructor(message: string, code: string) { super(message); this.code = code }
+  },
+  http: { get: vi.fn(), post: vi.fn() },
+  unwrapApiResponse: <T>(response: { data: T }) => response.data,
+}))
+
+describe('platform inbound query API', () => {
+  beforeEach(() => {
+    vi.mocked(http.get).mockReset()
+    vi.mocked(http.post).mockReset()
+  })
+
+  it('omits the backend tenant filter for an all-customer list query', async () => {
+    vi.mocked(http.get).mockResolvedValue({
+      code: '200', message: 'success', data: { records: [], page: 1, size: 20, total: 0, pages: 0 },
+    })
+
+    await listPlatformInbounds(undefined, { page: 1, size: 20 })
+
+    expect(http.get).toHaveBeenCalledWith('/platform/inbounds', { params: { page: 1, size: 20 } })
+  })
+
+  it('uses the implemented non-v1 list path and normalizes page values and IDs', async () => {
+    vi.mocked(http.get).mockResolvedValue({
+      code: '200', message: 'success', data: {
+        records: [{
+          id: 19001, tenantId: 10002, orderId: 18001, customerId: 10001,
+          totalPackageCount: '6', palletCount: '2', actualGrossWeightKg: '21.5',
+          actualNetWeightKg: '18.25', actualVolumeCbm: '0.456', holdFlag: 'false',
+        }],
+        page: '1', size: '20', total: '1', pages: '1',
+      },
+    })
+
+    await expect(listPlatformInbounds('10001', {
+      page: 1, size: 20, tab: 'WAIT_MEASURE', inboundCode: 'RK', holdFlag: false,
+    })).resolves.toMatchObject({
+      records: [{
+        id: '19001', tenantId: '10002', orderId: '18001', customerId: '10001',
+        totalPackageCount: 6, palletCount: 2, actualGrossWeightKg: 21.5,
+        actualNetWeightKg: 18.25, actualVolumeCbm: 0.456, holdFlag: false,
+      }],
+      total: 1, pages: 1,
+    })
+    expect(http.get).toHaveBeenCalledWith('/platform/inbounds', {
+      params: { tenantId: '10001', page: 1, size: 20, tab: 'WAIT_MEASURE', inboundCode: 'RK', holdFlag: false },
+    })
+  })
+
+  it('loads a tenant-scoped aggregate detail and keeps nested IDs as strings', async () => {
+    vi.mocked(http.get).mockResolvedValue({
+      code: '200', message: 'success', data: {
+        summary: { id: 19001, tenantId: 10002, orderId: 18001 }, publicRemark: null,
+        palletLocations: [{ palletId: 21001, locationId: 22001 }], files: [{ fileId: 23001, uploadedBy: 2 }],
+        internalNotes: [{ id: 24001, createdBy: 2 }], statusHistory: [{ operatorId: 2 }],
+      },
+    })
+
+    await expect(getPlatformInbound('10001', '19001')).resolves.toMatchObject({
+      summary: { id: '19001', tenantId: '10002', orderId: '18001' },
+      palletLocations: [{ palletId: '21001', locationId: '22001' }],
+      files: [{ fileId: '23001', uploadedBy: '2' }],
+      internalNotes: [{ id: '24001', createdBy: '2' }],
+      statusHistory: [{ operatorId: '2' }],
+    })
+    expect(http.get).toHaveBeenCalledWith('/platform/inbounds/19001', { params: { tenantId: '10001' } })
+  })
+
+  it('loads and normalizes the inbound-scoped dropship pallet result', async () => {
+    vi.mocked(http.get).mockResolvedValue({ code: '200', data: [{
+      palletId: 9007199254740993n, palletNo: 'PLT-001', status: 'SEALED', cartonCount: '2', skuCount: '1', version: '3',
+      weightKg: '20.5', volumeCbm: '0.88', discrepancyCartons: '1', sealedAt: '2026-09-08T10:00:00',
+      items: [{ inboundId: 19001, inboundCode: 'RK001', inboundDetailId: 9007199254740994n, skuCode: 'SKU001', cargoName: '服装', cartonCount: '2', skuQuantity: '19', cartonMarks: ['BOX-001', 'BOX-002'] }],
+    }] })
+
+    await expect(listPlatformInboundDropshipPallets('10001', '19001')).resolves.toMatchObject([{
+      palletId: '9007199254740993', weightKg: 20.5, volumeCbm: 0.88, discrepancyCartons: 1,
+      items: [{ inboundId: '19001', inboundDetailId: '9007199254740994', cartonCount: 2, skuQuantity: 19, cartonMarks: ['BOX-001', 'BOX-002'] }],
+    }])
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/first-leg/pda-dropship/inbound-orders/19001/pallets', { params: { accountId: '10001' } })
+  })
+
+  it('downloads one or all inbound-scoped dropship pallet documents for desktop printing', async () => {
+    const pdf = new Blob(['pdf'], { type: 'application/pdf' })
+    vi.mocked(http.get).mockResolvedValue(pdf)
+
+    await expect(downloadDropshipPalletLabel('10001', '19001', '21001')).resolves.toBe(pdf)
+    await expect(downloadAllDropshipPalletLabels('10001', '19001')).resolves.toBe(pdf)
+
+    expect(http.get).toHaveBeenNthCalledWith(1,
+      '/platform/v1/first-leg/pda-dropship/inbound-orders/19001/pallets/21001/print',
+      { params: { accountId: '10001' }, responseType: 'blob', timeout: 60_000 })
+    expect(http.get).toHaveBeenNthCalledWith(2,
+      '/platform/v1/first-leg/pda-dropship/inbound-orders/19001/pallets/print',
+      { params: { accountId: '10001' }, responseType: 'blob', timeout: 60_000 })
+  })
+
+  it('passes the implemented order, process, measurement and fee review filters without renaming them', async () => {
+    vi.mocked(http.get).mockResolvedValue({
+      code: '200', message: 'success', data: { records: [], page: 1, size: 20, total: 0, pages: 0 },
+    })
+
+    await listPlatformInbounds('10001', {
+      page: 1,
+      size: 20,
+      processStatus: 'MEASURE_PENDING',
+      orderStatus: 'APPROVED',
+      measureReviewStatus: 'PENDING',
+      feeStatus: 'UNPRICED',
+      feeReviewStatus: 'PENDING',
+      warehouseId: '9007199254740993',
+      deliveryWarehouseId: '9007199254740995',
+    })
+
+    expect(http.get).toHaveBeenCalledWith('/platform/inbounds', {
+      params: {
+        tenantId: '10001', page: 1, size: 20, processStatus: 'MEASURE_PENDING',
+        orderStatus: 'APPROVED', measureReviewStatus: 'PENDING', feeStatus: 'UNPRICED', feeReviewStatus: 'PENDING',
+        warehouseId: '9007199254740993', deliveryWarehouseId: '9007199254740995',
+      },
+    })
+  })
+
+  it('downloads stable carton labels and rejects JSON business errors', async () => {
+    const pdf = new Blob(['pdf'], { type: 'application/pdf' })
+    vi.mocked(http.post).mockResolvedValueOnce(pdf)
+
+    await expect(downloadInboundCartonLabels('10001', '19001', [1, 3])).resolves.toBe(pdf)
+    expect(http.post).toHaveBeenCalledWith('/platform/inbounds/19001/carton-label-pdf', null, {
+      params: { tenantId: '10001', cartonIndex: [1, 3] }, responseType: 'blob', timeout: 60_000,
+    })
+
+    vi.mocked(http.post).mockResolvedValueOnce({
+      type: 'application/json',
+      text: async () => JSON.stringify({ code: 'A0422', message: '箱号映射不完整' }),
+    } as Blob)
+    await expect(downloadInboundCartonLabels('10001', '19001')).rejects.toMatchObject({
+      message: '箱号映射不完整', code: 'A0422',
+    })
+  })
+
+  it('downloads one PDF for a cross-customer batch of inbound orders', async () => {
+    const pdf = new Blob(['pdf'], { type: 'application/pdf' })
+    vi.mocked(http.post).mockResolvedValueOnce(pdf)
+    const items = [
+      { tenantId: '10001', inboundId: '19001' },
+      { tenantId: '10002', inboundId: '19002' },
+    ]
+
+    await expect(downloadInboundCartonLabelsBatch(items)).resolves.toBe(pdf)
+    expect(http.post).toHaveBeenCalledWith('/platform/inbounds/carton-label-pdf', items, {
+      responseType: 'blob', timeout: 120_000,
+    })
+  })
+
+  it('loads and normalizes the tenant-scoped hold state and immutable history', async () => {
+    vi.mocked(http.get).mockResolvedValue({ data: {
+      inboundId: 19001, tenantId: 10002, holdFlag: true, currentHoldReason: ' 待核对货款 ', version: '4',
+      canHold: false, canRelease: true, actionBlockReason: null,
+      history: [{ id: 88001, action: 'HOLD', reason: ' 待核对货款 ', evidenceFileId: 99001, operatorName: ' 财务A ', operatedAt: '2026-09-07T10:00:00' }],
+    } })
+
+    await expect(getPlatformInboundHold('10002', '19001')).resolves.toEqual({
+      inboundId: '19001', tenantId: '10002', holdFlag: true, currentHoldReason: '待核对货款', version: 4,
+      canHold: false, canRelease: true, actionBlockReason: null,
+      history: [{ id: '88001', action: 'HOLD', reason: '待核对货款', evidenceFileId: '99001', operatorName: '财务A', operatedAt: '2026-09-07T10:00:00' }],
+    })
+    expect(http.get).toHaveBeenCalledWith('/platform/inbounds/19001/hold', { params: { tenantId: '10002' } })
+  })
+
+  it('posts hold and release commands with versions, reasons and independent idempotency keys', async () => {
+    const result = { data: { inboundId: '19001', tenantId: '10002', holdFlag: true, currentHoldReason: '待核对货款', version: 4, canHold: false, canRelease: true, actionBlockReason: null, history: [] } }
+    vi.mocked(http.post).mockResolvedValue(result)
+
+    await holdPlatformInbound('10002', '19001', { expectedVersion: 3, reason: '待核对货款' }, 'hold-key')
+    expect(http.post).toHaveBeenNthCalledWith(1, '/platform/inbounds/19001/hold', { expectedVersion: 3, reason: '待核对货款' }, {
+      params: { tenantId: '10002' }, headers: { 'Idempotency-Key': 'hold-key' },
+    })
+
+    await releasePlatformInbound('10002', '19001', { expectedVersion: 4, reason: '货款已核对' }, 'release-key')
+    expect(http.post).toHaveBeenNthCalledWith(2, '/platform/inbounds/19001/hold/release', { expectedVersion: 4, reason: '货款已核对' }, {
+      params: { tenantId: '10002' }, headers: { 'Idempotency-Key': 'release-key' },
+    })
+  })
+
+  it('uploads and downloads tenant-scoped hold evidence without narrowing long IDs', async () => {
+    const file = new File(['evidence'], '扣货说明.pdf', { type: 'application/pdf' })
+    vi.mocked(http.post).mockResolvedValueOnce({ data: {
+      fileId: '9007199254740999', fileName: '扣货说明.pdf', contentType: 'application/pdf', sizeBytes: '8',
+    } })
+    await expect(uploadPlatformInboundHoldEvidence('10002', '19001', file)).resolves.toEqual({
+      fileId: '9007199254740999', fileName: '扣货说明.pdf', contentType: 'application/pdf', sizeBytes: 8,
+    })
+    const [path, body, options] = vi.mocked(http.post).mock.calls[0]!
+    expect(path).toBe('/platform/inbounds/19001/hold/evidence')
+    expect(body).toBeInstanceOf(FormData)
+    expect((body as FormData).get('file')).toBe(file)
+    expect(options).toEqual({ params: { tenantId: '10002' }, headers: { 'Content-Type': 'multipart/form-data' } })
+
+    const blob = new Blob(['evidence'], { type: 'application/pdf' })
+    vi.mocked(http.get).mockResolvedValueOnce(blob)
+    await expect(downloadPlatformInboundHoldEvidence('10002', '19001', '9007199254740999')).resolves.toBe(blob)
+    expect(http.get).toHaveBeenLastCalledWith(
+      '/platform/inbounds/19001/hold/evidence/9007199254740999/download',
+      { params: { tenantId: '10002' }, responseType: 'blob' },
+    )
+  })
+})
diff --git a/src/modules/inbounds/core/api.ts b/src/modules/inbounds/core/api.ts
new file mode 100644
index 00000000..f5e37f27
--- /dev/null
+++ b/src/modules/inbounds/core/api.ts
@@ -0,0 +1,300 @@
+import { ApiResponseError, http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import type {
+  InboundFileSummary,
+  InboundInternalNote,
+  InboundHoldCommand,
+  InboundHoldDetail,
+  InboundHoldEvidenceUpload,
+  InboundListQuery,
+  InboundOrderDetail,
+  InboundOrderSummary,
+  InboundPageResult,
+  InboundPalletLocation,
+  InboundStatusHistory,
+  InboundDropshipPallet,
+} from './types'
+
+const basePath = '/platform/inbounds'
+
+function id(value: unknown): string | null {
+  return value === null || value === undefined ? null : String(value)
+}
+
+function numberValue(value: unknown): number | null {
+  if (value === null || value === undefined || value === '') return null
+  const parsed = typeof value === 'number' ? value : Number(value)
+  return Number.isFinite(parsed) ? parsed : null
+}
+
+function integerValue(value: unknown): number | null {
+  const parsed = numberValue(value)
+  return parsed === null ? null : Math.trunc(parsed)
+}
+
+function boolValue(value: unknown): boolean | null {
+  if (value === null || value === undefined) return null
+  if (typeof value === 'boolean') return value
+  if (value === 'true' || value === 1 || value === '1') return true
+  if (value === 'false' || value === 0 || value === '0') return false
+  return null
+}
+
+export function normalizeInboundSummary(raw: InboundOrderSummary): InboundOrderSummary {
+  return {
+    ...raw,
+    id: String(raw.id),
+    tenantId: String(raw.tenantId),
+    orderId: id(raw.orderId),
+    customerId: id(raw.customerId),
+    companyId: id(raw.companyId),
+    warehouseId: id(raw.warehouseId),
+    deliveryWarehouseId: id(raw.deliveryWarehouseId),
+    destinationWarehouseId: id(raw.destinationWarehouseId),
+    version: integerValue(raw.version),
+    customsInspection: boolValue(raw.customsInspection),
+    holdFlag: boolValue(raw.holdFlag),
+    totalPackageCount: integerValue(raw.totalPackageCount),
+    actualGrossWeightKg: numberValue(raw.actualGrossWeightKg),
+    actualNetWeightKg: numberValue(raw.actualNetWeightKg),
+    actualVolumeCbm: numberValue(raw.actualVolumeCbm),
+    volumeWeightKg: numberValue(raw.volumeWeightKg),
+    chargeableWeightKg: numberValue(raw.chargeableWeightKg),
+    chargeableVolumeCbm: numberValue(raw.chargeableVolumeCbm),
+    palletCount: integerValue(raw.palletCount),
+  }
+}
+
+function normalizePage(raw: InboundPageResult): InboundPageResult {
+  return {
+    records: (raw.records || []).map(normalizeInboundSummary),
+    page: integerValue(raw.page) || 1,
+    size: integerValue(raw.size) || 20,
+    total: integerValue(raw.total) || 0,
+    pages: integerValue(raw.pages) || 0,
+  }
+}
+
+function normalizePallet(raw: InboundPalletLocation): InboundPalletLocation {
+  return {
+    ...raw,
+    allocationNo: integerValue(raw.allocationNo),
+    warehouseId: id(raw.warehouseId),
+    palletId: id(raw.palletId),
+    locationId: id(raw.locationId),
+    palletCapacityCbm: numberValue(raw.palletCapacityCbm),
+    allocatedVolumeCbm: numberValue(raw.allocatedVolumeCbm),
+    allocatedPackageCount: integerValue(raw.allocatedPackageCount),
+  }
+}
+
+function normalizeFile(raw: InboundFileSummary): InboundFileSummary {
+  return { ...raw, fileId: id(raw.fileId), uploadedBy: id(raw.uploadedBy), fileVersion: integerValue(raw.fileVersion) }
+}
+
+function normalizeNote(raw: InboundInternalNote): InboundInternalNote {
+  return { ...raw, id: id(raw.id), createdBy: id(raw.createdBy) }
+}
+
+function normalizeHistory(raw: InboundStatusHistory): InboundStatusHistory {
+  return { ...raw, operatorId: id(raw.operatorId) }
+}
+
+function normalizeDetail(raw: InboundOrderDetail): InboundOrderDetail {
+  return {
+    ...raw,
+    summary: normalizeInboundSummary(raw.summary),
+    dropshipPallets: [],
+    palletLocations: (raw.palletLocations || []).map(normalizePallet),
+    files: (raw.files || []).map(normalizeFile),
+    internalNotes: (raw.internalNotes || []).map(normalizeNote),
+    statusHistory: (raw.statusHistory || []).map(normalizeHistory),
+  }
+}
+
+function normalizeDropshipPallet(raw: InboundDropshipPallet): InboundDropshipPallet {
+  return {
+    ...raw,
+    palletId: id(raw.palletId) || '',
+    palletNo: raw.palletNo || null,
+    cartonCount: integerValue(raw.cartonCount) || 0,
+    skuCount: integerValue(raw.skuCount) || 0,
+    version: integerValue(raw.version) || 0,
+    weightKg: numberValue(raw.weightKg),
+    volumeCbm: numberValue(raw.volumeCbm),
+    discrepancyCartons: integerValue(raw.discrepancyCartons) || 0,
+    sealedAt: raw.sealedAt || null,
+    items: (raw.items || []).map((item) => ({
+      ...item,
+      inboundId: id(item.inboundId) || '',
+      inboundDetailId: id(item.inboundDetailId) || '',
+      cartonCount: integerValue(item.cartonCount) || 0,
+      skuQuantity: integerValue(item.skuQuantity) || 0,
+      cartonMarks: item.cartonMarks || [],
+    })),
+  }
+}
+
+function normalizeHoldDetail(raw: InboundHoldDetail): InboundHoldDetail {
+  return {
+    ...raw,
+    inboundId: String(raw.inboundId),
+    tenantId: String(raw.tenantId),
+    holdFlag: Boolean(raw.holdFlag),
+    currentHoldReason: raw.currentHoldReason?.trim() || null,
+    version: integerValue(raw.version) || 0,
+    canHold: Boolean(raw.canHold),
+    canRelease: Boolean(raw.canRelease),
+    actionBlockReason: raw.actionBlockReason?.trim() || null,
+    history: (raw.history || []).map((item) => ({
+      ...item,
+      id: String(item.id),
+      reason: item.reason?.trim() || '',
+      evidenceFileId: id(item.evidenceFileId),
+      operatorName: item.operatorName?.trim() || null,
+    })),
+  }
+}
+
+export function createInboundHoldIdempotencyKey(action: 'hold' | 'release') {
+  const uuid = globalThis.crypto?.randomUUID?.()
+  return uuid ? `inbound-${action}-${uuid}` : `inbound-${action}-${Date.now()}-${Math.random().toString(36).slice(2)}`
+}
+
+function queryParams(tenantId: string | undefined, query: InboundListQuery) {
+  return Object.fromEntries(
+    Object.entries({ tenantId, ...query }).filter(([, value]) => value !== undefined && value !== ''),
+  )
+}
+
+export async function listPlatformInbounds(tenantId: string | undefined, query: InboundListQuery) {
+  const response = await http.get<ApiEnvelope<InboundPageResult>, ApiEnvelope<InboundPageResult>>(basePath, {
+    params: queryParams(tenantId, query),
+  })
+  return normalizePage(unwrapApiResponse(response))
+}
+
+export async function getPlatformInbound(tenantId: string, inboundId: string) {
+  const response = await http.get<ApiEnvelope<InboundOrderDetail>, ApiEnvelope<InboundOrderDetail>>(
+    `${basePath}/${inboundId}`,
+    { params: { tenantId } },
+  )
+  return normalizeDetail(unwrapApiResponse(response))
+}
+
+export async function listPlatformInboundDropshipPallets(accountId: string, inboundId: string) {
+  const response = await http.get<ApiEnvelope<InboundDropshipPallet[]>, ApiEnvelope<InboundDropshipPallet[]>>(
+    `/platform/v1/first-leg/pda-dropship/inbound-orders/${encodeURIComponent(inboundId)}/pallets`,
+    { params: { accountId } },
+  )
+  return (unwrapApiResponse(response) || []).map(normalizeDropshipPallet)
+}
+
+export async function getPlatformInboundHold(tenantId: string, inboundId: string) {
+  const response = await http.get<ApiEnvelope<InboundHoldDetail>, ApiEnvelope<InboundHoldDetail>>(
+    `${basePath}/${encodeURIComponent(inboundId)}/hold`,
+    { params: { tenantId } },
+  )
+  return normalizeHoldDetail(unwrapApiResponse(response))
+}
+
+async function postPlatformInboundHold(
+  tenantId: string,
+  inboundId: string,
+  action: 'hold' | 'release',
+  payload: InboundHoldCommand,
+  idempotencyKey = createInboundHoldIdempotencyKey(action),
+) {
+  const suffix = action === 'release' ? '/release' : ''
+  const response = await http.post<ApiEnvelope<InboundHoldDetail>, ApiEnvelope<InboundHoldDetail>>(
+    `${basePath}/${encodeURIComponent(inboundId)}/hold${suffix}`,
+    payload,
+    { params: { tenantId }, headers: { 'Idempotency-Key': idempotencyKey } },
+  )
+  return normalizeHoldDetail(unwrapApiResponse(response))
+}
+
+export function holdPlatformInbound(tenantId: string, inboundId: string, payload: InboundHoldCommand, idempotencyKey?: string) {
+  return postPlatformInboundHold(tenantId, inboundId, 'hold', payload, idempotencyKey)
+}
+
+export function releasePlatformInbound(tenantId: string, inboundId: string, payload: InboundHoldCommand, idempotencyKey?: string) {
+  return postPlatformInboundHold(tenantId, inboundId, 'release', payload, idempotencyKey)
+}
+
+export async function uploadPlatformInboundHoldEvidence(tenantId: string, inboundId: string, file: File) {
+  const body = new FormData()
+  body.append('file', file)
+  const response = await http.post<ApiEnvelope<InboundHoldEvidenceUpload>, ApiEnvelope<InboundHoldEvidenceUpload>>(
+    `${basePath}/${encodeURIComponent(inboundId)}/hold/evidence`,
+    body,
+    { params: { tenantId }, headers: { 'Content-Type': 'multipart/form-data' } },
+  )
+  const raw = unwrapApiResponse(response)
+  return {
+    fileId: String(raw.fileId),
+    fileName: String(raw.fileName || file.name),
+    contentType: String(raw.contentType || file.type || 'application/octet-stream'),
+    sizeBytes: numberValue(raw.sizeBytes) || 0,
+  } satisfies InboundHoldEvidenceUpload
+}
+
+export function downloadPlatformInboundHoldEvidence(tenantId: string, inboundId: string, fileId: string) {
+  return http.get<Blob, Blob>(
+    `${basePath}/${encodeURIComponent(inboundId)}/hold/evidence/${encodeURIComponent(fileId)}/download`,
+    { params: { tenantId }, responseType: 'blob' },
+  )
+}
+
+export async function downloadInboundCartonLabels(tenantId: string, inboundId: string, cartonIndexes?: number[]) {
+  const response = await http.post<Blob, Blob>(
+    `${basePath}/${encodeURIComponent(inboundId)}/carton-label-pdf`,
+    null,
+    {
+      params: {
+        tenantId,
+        ...(cartonIndexes?.length ? { cartonIndex: cartonIndexes } : {}),
+      },
+      responseType: 'blob',
+      timeout: 60_000,
+    },
+  )
+  if (response.type.includes('json')) {
+    const error = JSON.parse(await response.text()) as Partial<ApiEnvelope<unknown>>
+    throw new ApiResponseError(error.message || '箱唛生成失败', error.code || 'UNKNOWN', undefined,
+      error.data, error.requestId, error.traceId)
+  }
+  return response
+}
+
+export interface InboundCartonLabelBatchItem {
+  tenantId: string
+  inboundId: string
+}
+
+export async function downloadInboundCartonLabelsBatch(items: InboundCartonLabelBatchItem[]) {
+  const response = await http.post<Blob, Blob>(
+    `${basePath}/carton-label-pdf`,
+    items,
+    { responseType: 'blob', timeout: 120_000 },
+  )
+  if (response.type.includes('json')) {
+    const error = JSON.parse(await response.text()) as Partial<ApiEnvelope<unknown>>
+    throw new ApiResponseError(error.message || '批量箱唛生成失败', error.code || 'UNKNOWN', undefined,
+      error.data, error.requestId, error.traceId)
+  }
+  return response
+}
+
+export async function downloadDropshipPalletLabel(tenantId: string, inboundId: string, palletId: string) {
+  return http.get<Blob, Blob>(
+    `/platform/v1/first-leg/pda-dropship/inbound-orders/${encodeURIComponent(inboundId)}/pallets/${encodeURIComponent(palletId)}/print`,
+    { params: { accountId: tenantId }, responseType: 'blob', timeout: 60_000 },
+  )
+}
+
+export async function downloadAllDropshipPalletLabels(tenantId: string, inboundId: string) {
+  return http.get<Blob, Blob>(
+    `/platform/v1/first-leg/pda-dropship/inbound-orders/${encodeURIComponent(inboundId)}/pallets/print`,
+    { params: { accountId: tenantId }, responseType: 'blob', timeout: 60_000 },
+  )
+}
diff --git a/src/modules/inbounds/core/types.ts b/src/modules/inbounds/core/types.ts
new file mode 100644
index 00000000..7c218e48
--- /dev/null
+++ b/src/modules/inbounds/core/types.ts
@@ -0,0 +1,216 @@
+export type InboundListTab = 'WAIT_MEASURE' | 'WAIT_REVIEW' | 'WAIT_FEE_SEND' | 'WAIT_SPLIT'
+
+export type InboundProcessStatus =
+  | 'WAIT_MEASURE'
+  | 'MEASURING'
+  | 'MEASURE_PENDING'
+  | 'MEASURE_REJECTED'
+  | 'WAIT_PRICING'
+  | 'FEE_CONFIRMING'
+  | 'INBOUNDING'
+  | 'WAIT_PALLETIZE'
+  | 'WAIT_SPLIT'
+  | 'VOIDED'
+
+export type InboundFeeStatus = 'UNPRICED' | 'CALCULATED' | 'CONFIRMED' | 'SENT' | 'VOIDED' | string
+
+export interface InboundOrderSummary {
+  id: string
+  tenantId: string
+  orderId: string | null
+  orderNo: string | null
+  inboundCode: string | null
+  processStatus: InboundProcessStatus | string
+  orderStatusSnapshot: string | null
+  measureReviewStatus: string | null
+  feeStatus: InboundFeeStatus | null
+  feeReviewStatus: string | null
+  notificationStatus: string | null
+  version: number | null
+  expectedArrivalAt: string | null
+  customerId: string | null
+  customerName: string | null
+  companyId: string | null
+  companyName: string | null
+  warehouseId: string | null
+  warehouseName: string | null
+  deliveryWarehouseId: string | null
+  deliveryWarehouseName: string | null
+  businessType: string | null
+  fulfillmentType: 'STANDARD' | 'ONE_CLICK_DROPSHIP' | string | null
+  channelCode: string | null
+  channelName: string | null
+  taxMode: string | null
+  containerMode: string | null
+  customsInspection: boolean | null
+  destinationType: string | null
+  destinationWarehouseId: string | null
+  destinationCode: string | null
+  destinationName: string | null
+  holdFlag: boolean | null
+  currentHoldReason: string | null
+  totalPackageCount: number | null
+  actualGrossWeightKg: number | null
+  actualNetWeightKg: number | null
+  actualVolumeCbm: number | null
+  volumeWeightKg: number | null
+  chargeableWeightKg: number | null
+  chargeableVolumeCbm: number | null
+  palletCount: number | null
+  locationCodes: string | null
+  measureCompletedAt: string | null
+  inboundedAt: string | null
+  expressCompanyCode: string | null
+  expressCompanyName: string | null
+  expressTrackingNo: string | null
+  loadingStatus: string | null
+  containerNo: string | null
+  cabinetNo: string | null
+  vesselName: string | null
+  voyageNo: string | null
+  sailingAt: string | null
+  portArrivalAt: string | null
+  createdAt: string | null
+  updatedAt: string | null
+}
+
+export interface InboundPalletLocation {
+  allocationNo: number | null
+  warehouseId: string | null
+  palletId: string | null
+  palletCode: string | null
+  palletCapacityCbm: number | null
+  allocatedVolumeCbm: number | null
+  allocatedPackageCount: number | null
+  locationId: string | null
+  locationCode: string | null
+  reservationNo: string | null
+  allocationStatus: string | null
+}
+
+export interface InboundFileSummary {
+  fileId: string | null
+  fileType: string | null
+  fileNameSnapshot: string | null
+  visibility: string | null
+  fileVersion: number | null
+  uploadedBy: string | null
+  uploadedAt: string | null
+}
+
+export interface InboundInternalNote {
+  id: string | null
+  content: string | null
+  createdBy: string | null
+  createdByName: string | null
+  createdAt: string | null
+}
+
+export interface InboundStatusHistory {
+  fromStatus: string | null
+  toStatus: string | null
+  action: string | null
+  reason: string | null
+  operatorId: string | null
+  operatorName: string | null
+  occurredAt: string | null
+}
+
+export interface InboundOrderDetail {
+  summary: InboundOrderSummary
+  publicRemark: string | null
+  dropshipPallets: InboundDropshipPallet[]
+  palletLocations: InboundPalletLocation[]
+  files: InboundFileSummary[]
+  internalNotes: InboundInternalNote[]
+  statusHistory: InboundStatusHistory[]
+}
+
+export interface InboundHoldHistoryEntry {
+  id: string
+  action: 'HOLD' | 'RELEASE'
+  reason: string
+  evidenceFileId: string | null
+  operatorName: string | null
+  operatedAt: string
+}
+
+export interface InboundHoldDetail {
+  inboundId: string
+  tenantId: string
+  holdFlag: boolean
+  currentHoldReason: string | null
+  version: number
+  canHold: boolean
+  canRelease: boolean
+  actionBlockReason: string | null
+  history: InboundHoldHistoryEntry[]
+}
+
+export interface InboundHoldCommand {
+  expectedVersion: number
+  reason: string
+  evidenceFileId?: string
+}
+
+export interface InboundHoldEvidenceUpload {
+  fileId: string
+  fileName: string
+  contentType: string
+  sizeBytes: number
+}
+
+export interface InboundDropshipPallet {
+  palletId: string
+  palletNo: string | null
+  status: 'OPEN' | 'SEALED'
+  cartonCount: number
+  skuCount: number
+  version: number
+  weightKg: number | null
+  volumeCbm: number | null
+  discrepancyCartons: number
+  sealedAt: string | null
+  items: InboundDropshipSkuItem[]
+}
+
+export interface InboundDropshipSkuItem {
+  inboundId: string
+  inboundCode: string
+  inboundDetailId: string
+  skuCode: string
+  cargoName: string | null
+  cartonCount: number
+  skuQuantity: number
+  cartonMarks: string[]
+}
+
+export interface InboundPageResult {
+  records: InboundOrderSummary[]
+  page: number
+  size: number
+  total: number
+  pages: number
+}
+
+export interface InboundListQuery {
+  page: number
+  size: number
+  tab?: InboundListTab
+  inboundCode?: string
+  orderNo?: string
+  processStatus?: string
+  orderStatus?: string
+  measureReviewStatus?: string
+  customerName?: string
+  destinationCode?: string
+  feeStatus?: string
+  feeReviewStatus?: string
+  customerId?: string
+  holdFlag?: boolean
+  companyId?: string
+  warehouseId?: string
+  deliveryWarehouseId?: string
+  expectedArrivalFrom?: string
+  expectedArrivalTo?: string
+}
diff --git a/src/modules/inbounds/fee/InboundFeePanel.test.ts b/src/modules/inbounds/fee/InboundFeePanel.test.ts
new file mode 100644
index 00000000..3930dfb7
--- /dev/null
+++ b/src/modules/inbounds/fee/InboundFeePanel.test.ts
@@ -0,0 +1,384 @@
+import ElementPlus from 'element-plus'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { createPinia, setActivePinia } from 'pinia'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { ElMessageBox } from 'element-plus'
+import { ApiResponseError } from '@/shared/api/http'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+import {
+  adjustPublishedInboundFee,
+  confirmInboundFee,
+  getLatestInboundFee,
+  sendInboundFee,
+} from './api'
+import type { InboundFeeSnapshot } from './types'
+import InboundFeePanel from './InboundFeePanel.vue'
+
+vi.mock('./api', async () => {
+  const actual = await vi.importActual<typeof import('./api')>('./api')
+  return {
+    ...actual,
+    getLatestInboundFee: vi.fn(),
+    adjustPublishedInboundFee: vi.fn(),
+    confirmInboundFee: vi.fn(),
+    sendInboundFee: vi.fn(),
+  }
+})
+
+const snapshot: InboundFeeSnapshot = {
+  feeId: '9007199254740993', feeNo: 'FBAF-88-2', feeVersion: 2, feeStatus: 'SENT',
+  inboundId: '88', inboundCode: 'RK202608040088',
+  chargeRuleId: '101', ruleCode: 'RULE-FBA-KG', chargeRuleVersion: 3,
+  carrierRateId: '202', rateCode: 'RATE-LAX', carrierRateVersion: 5,
+  customerId: '303', customerName: '测试客户', originWarehouseId: '404', originWarehouseName: '义乌仓',
+  businessType: 'FBA_SEA', channelCode: 'SEA-TAX', carrierId: '505', carrierName: '测试船司',
+  destinationCode: 'LAX9', taxMode: 'TAX_REFUND', pricingTaxMode: 'TAX_INCLUDED', chargeMode: 'KG',
+  conversionFactor: 167, roundingScale: 2, roundingMode: 'HALF_UP',
+  actualWeightKg: 100, actualVolumeCbm: 0.8, convertedQuantity: 133.6,
+  baselineChargeableQuantity: 133.6, lowerChargeableQuantity: 120.24, upperChargeableQuantity: 146.96,
+  tolerancePercent: 10, chargeableQuantity: 133.6,
+  chargeUnit: 'KG', unitPrice: 8.5, subtotalAmount: 1135.6, additionalAmount: 100,
+  totalAmount: 1235.6, currency: 'CNY',
+  rateEffectiveFrom: '2026-08-01T00:00:00', rateEffectiveTo: null,
+  calculatedAt: '2026-08-04T10:00:00', confirmedAt: '2026-08-04T10:01:00', sentAt: '2026-08-04T10:02:00',
+  nextProcessStatus: 'WAIT_SPLIT',
+  customerConfirmationStatus: 'PENDING_CONFIRMATION', customerConfirmedBy: null,
+  customerConfirmedByName: null, customerConfirmedAt: null,
+}
+
+enableAutoUnmount(afterEach)
+
+function setupPermissions(permissions: string[]) {
+  const pinia = createPinia()
+  setActivePinia(pinia)
+  const auth = useAuthStore()
+  auth.token = 'token'
+  auth.permissions = permissions
+  useAccessPreviewStore().initializeAfterLogin()
+  return pinia
+}
+
+function mountPanel(permissions = [
+  'firstleg:fba-pricing:view',
+  'firstleg:fba-pricing:adjust',
+  'firstleg:fba-pricing:confirm',
+  'firstleg:inbound:send-fee',
+]) {
+  const pinia = setupPermissions(permissions)
+  return mount(InboundFeePanel, {
+    attachTo: document.body,
+    props: { customerId: '10001', inboundId: '88' },
+    global: { plugins: [pinia, ElementPlus] },
+  })
+}
+
+describe('InboundFeePanel', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    document.body.innerHTML = ''
+    vi.mocked(getLatestInboundFee).mockResolvedValue(snapshot)
+    vi.mocked(adjustPublishedInboundFee).mockResolvedValue({ ...snapshot, feeVersion: 3, feeNo: 'FBAF-88-3' })
+    vi.mocked(confirmInboundFee).mockResolvedValue({ ...snapshot, feeStatus: 'CONFIRMED', confirmedAt: '2026-08-04T10:01:00', sentAt: null })
+    vi.mocked(sendInboundFee).mockResolvedValue(snapshot)
+  })
+
+  it('shows the immutable calculation basis, versions, amount, and timestamps', async () => {
+    mountPanel()
+    await flushPromises()
+
+    expect(getLatestInboundFee).toHaveBeenCalledWith('10001', '88')
+    expect(document.body.textContent).toContain('订单报关：退税报关')
+    expect(document.body.textContent).toContain('报价税制：包税')
+    expect(document.body.textContent).not.toContain('租户')
+    expect(document.body.textContent).toContain('头程自动费用 · CNY')
+    expect(document.body.textContent).toContain('¥1,235.60')
+    expect(document.body.textContent).toContain('基础运费小计 ¥1,135.60')
+    expect(document.body.textContent).toContain('附加费 ¥100.00')
+    expect(document.body.textContent).toContain('133.6 KG')
+    expect(document.body.textContent).toContain('按重量计费')
+    expect(document.body.textContent).toContain('FBA 海运')
+    expect(document.body.textContent).toContain('¥8.50 / KG')
+    expect(document.body.textContent).toContain('RULE-FBA-KG · V3')
+    expect(document.body.textContent).toContain('RATE-LAX · V5')
+    expect(document.body.textContent).toContain('时间记录')
+    expect(document.body.textContent).toContain('发布')
+    expect(document.body.textContent).not.toContain('重新试算')
+    expect(document.body.textContent).not.toContain('确认费用')
+    expect(document.body.textContent).not.toContain('发送费用')
+  })
+
+  it('follows the admin detail interaction pattern without list-only scaffolding', async () => {
+    const wrapper = mountPanel()
+    await flushPromises()
+
+    expect(wrapper.get('button[aria-label="刷新费用快照"]').classes()).toContain('is-circle')
+    expect(wrapper.get('.version-status .el-tag').text()).toBe('已发布')
+    expect(wrapper.find('.query-toolbar').exists()).toBe(false)
+    expect(wrapper.find('.data-table').exists()).toBe(false)
+    expect(wrapper.find('.surface-panel').exists()).toBe(false)
+  })
+
+  it('keeps the compact title and refresh action on one heading row', async () => {
+    const pinia = setupPermissions(['firstleg:fba-pricing:view'])
+    const wrapper = mount(InboundFeePanel, {
+      props: { customerId: '10001', inboundId: '88', compact: true, displayOnly: true },
+      global: { plugins: [pinia, ElementPlus] },
+    })
+    await flushPromises()
+
+    const heading = wrapper.get('.fee-heading--compact')
+    expect(heading.get('#inbound-fee-title').text()).toBe('头程自动初算')
+    expect(heading.find('button[aria-label="刷新费用快照"]').exists()).toBe(true)
+  })
+
+  it('keeps the refresh icon visible and spinning while the snapshot reloads', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/inbounds/fee/InboundFeePanel.vue'), 'utf8')
+    expect(source).toContain('class="fee-refresh-button"')
+    expect(source).toContain(':aria-busy="loading"')
+    expect(source).toContain(`<RefreshCw :size="16" :class="{ 'is-spinning': loading }" />`)
+    expect(source).not.toMatch(/aria-label="刷新费用快照"[^>]*:loading=/)
+    expect(source).toContain('@keyframes fee-refresh-spin')
+  })
+
+  it('supports a display-only fee snapshot without calculation or transition actions', async () => {
+    vi.mocked(getLatestInboundFee).mockResolvedValue({ ...snapshot, feeStatus: 'CALCULATED', confirmedAt: null, sentAt: null })
+    const pinia = setupPermissions([
+      'firstleg:fba-pricing:view', 'firstleg:fba-pricing:calculate', 'firstleg:fba-pricing:adjust',
+      'firstleg:fba-pricing:confirm', 'firstleg:inbound:send-fee',
+    ])
+    const wrapper = mount(InboundFeePanel, {
+      props: { customerId: '10001', inboundId: '88', displayOnly: true },
+      global: { plugins: [pinia, ElementPlus] },
+    })
+    await flushPromises()
+
+    expect(wrapper.find('button[aria-label="刷新费用快照"]').exists()).toBe(true)
+    expect(wrapper.text()).not.toContain('费用试算')
+    expect(wrapper.text()).not.toContain('确认费用')
+    expect(wrapper.text()).not.toContain('确认推送费用')
+    expect(wrapper.find('[data-testid="adjust-fee-button"]').exists()).toBe(false)
+    expect(wrapper.find('[data-testid="confirm-fee-button"]').exists()).toBe(false)
+    expect(wrapper.find('[data-testid="send-fee-button"]').exists()).toBe(false)
+  })
+
+  it('keeps the legacy integration prop compatible while the page layer uses customer context', async () => {
+    const pinia = setupPermissions(['firstleg:fba-pricing:view'])
+    mount(InboundFeePanel, {
+      props: { tenantId: 'legacy-10001', inboundId: '88' },
+      global: { plugins: [pinia, ElementPlus] },
+    })
+    await flushPromises()
+
+    expect(getLatestInboundFee).toHaveBeenCalledWith('legacy-10001', '88')
+    expect(document.body.textContent).not.toContain('租户')
+  })
+
+  it('keeps the prototype-aligned detail order and renders long values with pending timestamps', async () => {
+    const longRuleCode = `RULE-${'LONG-'.repeat(20)}`
+    const longChannelCode = `CHANNEL-${'LONG-'.repeat(20)}`
+    vi.mocked(getLatestInboundFee).mockResolvedValue({
+      ...snapshot,
+      ruleCode: longRuleCode,
+      channelCode: longChannelCode,
+      confirmedAt: null,
+      sentAt: null,
+    })
+
+    const wrapper = mountPanel()
+    await flushPromises()
+
+    const content = wrapper.find('.fee-content').text()
+    expect(wrapper.findAll('.fee-summary > div > span').map((node) => node.text())).toEqual([
+      '头程自动费用 · CNY',
+      '最终计费量',
+      '单价',
+      '附加费',
+      '快照版本',
+    ])
+    expect(wrapper.findAll('.calculation-flow > div > span').map((node) => node.text())).toEqual([
+      '实际重量',
+      '实际体积',
+      '体积重量',
+      '取大后的计费量',
+    ])
+    expect(wrapper.findAll('.fee-detail-grid h4').map((node) => node.text())).toEqual([
+      '客户计费规则',
+      '渠道价格',
+    ])
+    expect(content).toContain(longRuleCode)
+    expect(content).toContain(longChannelCode)
+    const pendingTimelineItems = wrapper.findAll('.fee-timeline li.pending')
+    expect(pendingTimelineItems).toHaveLength(2)
+    expect(pendingTimelineItems.map((item) => item.find('strong').text())).toEqual(['—', '—'])
+  })
+
+  it('does not request or expose fees without the view permission', async () => {
+    mountPanel([])
+    await flushPromises()
+
+    expect(getLatestInboundFee).not.toHaveBeenCalled()
+    expect(document.body.textContent).toContain('没有查看入库费用的权限')
+  })
+
+  it.each(['', ' ', 'null', 'undefined'])('does not request a fee for invalid inboundId %j', async (inboundId) => {
+    const pinia = setupPermissions(['firstleg:fba-pricing:view'])
+    mount(InboundFeePanel, {
+      props: { customerId: '10001', inboundId },
+      global: { plugins: [pinia, ElementPlus] },
+    })
+    await flushPromises()
+    expect(getLatestInboundFee).not.toHaveBeenCalled()
+  })
+
+  it('treats A0404 as a neutral not-yet-generated state', async () => {
+    vi.mocked(getLatestInboundFee).mockRejectedValue(new ApiResponseError('费用快照不存在', 'A0404'))
+    mountPanel(['firstleg:fba-pricing:view'])
+    await flushPromises()
+
+    expect(document.body.textContent).toContain('尚未生成费用快照')
+    expect(document.body.textContent).toContain('测量审核完成后')
+    expect(document.querySelector('[role="alert"]')).toBeNull()
+  })
+
+  it('shows adjustment only for authorized calculated inbound fees', async () => {
+    mountPanel(['firstleg:fba-pricing:view'])
+    await flushPromises()
+    expect(document.querySelector('[data-testid="adjust-fee-button"]')).toBeNull()
+
+    document.body.innerHTML = ''
+    vi.mocked(getLatestInboundFee).mockResolvedValue({ ...snapshot, feeStatus: 'CALCULATED' })
+    mountPanel()
+    await flushPromises()
+    expect(document.querySelector('[data-testid="adjust-fee-button"]')).not.toBeNull()
+  })
+
+  it('allows adjustment for a calculated fee waiting for split', async () => {
+    vi.mocked(getLatestInboundFee).mockResolvedValue({ ...snapshot, feeStatus: 'CALCULATED' })
+    const wrapper = mountPanel()
+    await flushPromises()
+
+    expect(wrapper.find('[data-testid="adjust-fee-button"]').exists()).toBe(true)
+  })
+
+  it('allows a published fee adjustment until the customer confirms it', async () => {
+    const wrapper = mountPanel()
+    await flushPromises()
+    expect(wrapper.get('[data-testid="adjust-fee-button"]').text()).toContain('调整已发布费用')
+
+    document.body.innerHTML = ''
+    vi.mocked(getLatestInboundFee).mockResolvedValue({ ...snapshot, customerConfirmationStatus: 'CONFIRMED' })
+    const confirmed = mountPanel()
+    await flushPromises()
+    expect(confirmed.find('[data-testid="adjust-fee-button"]').exists()).toBe(false)
+  })
+
+  it('confirms and then sends a calculated fee through the implemented backend transitions', async () => {
+    vi.mocked(getLatestInboundFee).mockResolvedValue({ ...snapshot, feeStatus: 'CALCULATED', confirmedAt: null, sentAt: null })
+    vi.spyOn(ElMessageBox, 'confirm').mockResolvedValue(undefined as never)
+    const wrapper = mountPanel()
+    await flushPromises()
+
+    await wrapper.get('[data-testid="confirm-fee-button"]').trigger('click')
+    await flushPromises()
+    expect(confirmInboundFee).toHaveBeenCalledWith('10001', '88', expect.stringMatching(/^fee-confirm-/))
+    expect(wrapper.find('[data-testid="send-fee-button"]').exists()).toBe(true)
+
+    await wrapper.get('[data-testid="send-fee-button"]').trigger('click')
+    await flushPromises()
+    expect(sendInboundFee).toHaveBeenCalledWith('10001', '88', expect.stringMatching(/^fee-send-/))
+    expect(wrapper.emitted('changed')).toHaveLength(2)
+    expect(wrapper.find('[data-testid="send-fee-button"]').exists()).toBe(false)
+  })
+
+  it('does not expose fee transitions without their independent permissions', async () => {
+    vi.mocked(getLatestInboundFee).mockResolvedValue({ ...snapshot, feeStatus: 'CALCULATED', confirmedAt: null, sentAt: null })
+    const wrapper = mountPanel(['firstleg:fba-pricing:view', 'firstleg:fba-pricing:adjust'])
+    await flushPromises()
+
+    expect(wrapper.find('[data-testid="confirm-fee-button"]').exists()).toBe(false)
+    expect(wrapper.find('[data-testid="send-fee-button"]').exists()).toBe(false)
+  })
+
+  it('submits a reasoned adjustment and emits the refreshed snapshot', async () => {
+    vi.mocked(getLatestInboundFee).mockResolvedValue({ ...snapshot, feeStatus: 'CALCULATED' })
+    const wrapper = mountPanel()
+    await flushPromises()
+    ;(document.querySelector('[data-testid="adjust-fee-button"]') as HTMLButtonElement).click()
+    await flushPromises()
+
+    const numbers = [...document.querySelectorAll<HTMLInputElement>('.adjustment-form input')]
+    numbers[0]!.value = '140'
+    numbers[0]!.dispatchEvent(new Event('input', { bubbles: true }))
+    numbers[0]!.dispatchEvent(new Event('change', { bubbles: true }))
+    numbers[1]!.value = '8.2'
+    numbers[1]!.dispatchEvent(new Event('input', { bubbles: true }))
+    numbers[1]!.dispatchEvent(new Event('change', { bubbles: true }))
+    numbers[2]!.value = '80'
+    numbers[2]!.dispatchEvent(new Event('input', { bubbles: true }))
+    numbers[2]!.dispatchEvent(new Event('change', { bubbles: true }))
+    const reason = document.querySelector<HTMLTextAreaElement>('.adjustment-form textarea')!
+    reason.value = '补充已确认的附加费用'
+    reason.dispatchEvent(new Event('input', { bubbles: true }))
+    reason.dispatchEvent(new Event('blur', { bubbles: true }))
+
+    const confirm = [...document.querySelectorAll<HTMLButtonElement>('button')]
+      .find((button) => button.textContent?.includes('确认调整并生成新版本'))
+    confirm?.click()
+    await flushPromises()
+
+    expect(adjustPublishedInboundFee).toHaveBeenCalledWith(
+      '10001',
+      '88',
+      { expectedFeeVersion: 2, chargeableQuantity: 140, unitPrice: 8.2, additionalAmount: 80, reason: '补充已确认的附加费用', toleranceConfirmed: true },
+      expect.stringMatching(/^fee-adjust-/),
+    )
+    expect(wrapper.emitted('changed')?.[0]?.[0]).toMatchObject({ feeVersion: 3 })
+  })
+
+  it('keeps adjustment units on one line in a three-column desktop layout', () => {
+    const source = readFileSync(resolve('src/modules/inbounds/fee/InboundFeePanel.vue'), 'utf8')
+
+    expect(source).toContain('width="min(760px, calc(100vw - 28px))"')
+    expect(source).toContain('grid-template-columns: repeat(3, minmax(0, 1fr))')
+    expect(source).toContain('class="adjustment-unit"')
+    expect(source).toContain('white-space: nowrap')
+    expect(source).toContain('snapshot.value?.lowerChargeableQuantity')
+    expect(source).toContain('snapshot.value?.upperChargeableQuantity')
+    expect(source).toContain('toleranceConfirmed: true')
+    expect(source).toContain("'再次确认计费量调整'")
+    expect(source).toContain('nextQuantity < adjustmentMinimum.value || nextQuantity > adjustmentMaximum.value')
+  })
+
+  it('refreshes the latest snapshot after a conflict while retaining the dialog', async () => {
+    vi.mocked(getLatestInboundFee).mockResolvedValue({ ...snapshot, feeStatus: 'CALCULATED' })
+    vi.mocked(adjustPublishedInboundFee).mockRejectedValue(
+      new ApiResponseError('费用已被其他操作员修改，请刷新后重试', 'A0409', 409),
+    )
+    mountPanel()
+    await flushPromises()
+    ;(document.querySelector('[data-testid="adjust-fee-button"]') as HTMLButtonElement).click()
+    await flushPromises()
+
+    const numbers = [...document.querySelectorAll<HTMLInputElement>('.adjustment-form input')]
+    numbers[0]!.value = '140'
+    numbers[0]!.dispatchEvent(new Event('input', { bubbles: true }))
+    numbers[1]!.value = '8.2'
+    numbers[1]!.dispatchEvent(new Event('input', { bubbles: true }))
+    numbers[2]!.value = '80'
+    numbers[2]!.dispatchEvent(new Event('input', { bubbles: true }))
+    const reason = document.querySelector<HTMLTextAreaElement>('.adjustment-form textarea')!
+    reason.value = '并发场景价格修正'
+    reason.dispatchEvent(new Event('input', { bubbles: true }))
+    reason.dispatchEvent(new Event('blur', { bubbles: true }))
+    ;[...document.querySelectorAll<HTMLButtonElement>('button')]
+      .find((button) => button.textContent?.includes('确认调整并生成新版本'))?.click()
+    await flushPromises()
+
+    expect(getLatestInboundFee).toHaveBeenCalledTimes(2)
+    expect(document.body.textContent).toContain('系统已刷新最新快照')
+    expect(document.body.textContent).toContain('当前输入仍保留')
+  })
+})
diff --git a/src/modules/inbounds/fee/InboundFeePanel.vue b/src/modules/inbounds/fee/InboundFeePanel.vue
new file mode 100644
index 00000000..ed9609f0
--- /dev/null
+++ b/src/modules/inbounds/fee/InboundFeePanel.vue
@@ -0,0 +1,705 @@
+<script setup lang="ts">
+import { computed, reactive, ref, watch } from 'vue'
+import { ElMessage, ElMessageBox, type FormInstance, type FormRules } from 'element-plus'
+import { Check, CircleDollarSign, PencilLine, RefreshCw, Send } from '@lucide/vue'
+import { firstLegBusinessTypeLabel, firstLegTaxModeLabel } from '@/shared/utils/firstLegBusinessLabels'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import OperationErrorToast from '@/shared/components/OperationErrorToast.vue'
+import {
+  ApiResponseError,
+  getApiErrorDetails,
+  type ApiErrorDetails,
+} from '@/shared/api/http'
+import {
+  adjustPublishedInboundFee,
+  calculateInboundFee,
+  confirmInboundFee,
+  createFeeActionIdempotencyKey,
+  createFeeAdjustmentIdempotencyKey,
+  getLatestInboundFee,
+  sendInboundFee,
+} from './api'
+import type { AdjustPublishedInboundFeeRequest, InboundFeeSnapshot } from './types'
+import { getInboundMeasurement } from '../measurement/api'
+import type { InboundMeasurementDetail } from '../measurement/types'
+
+const props = defineProps<{
+  customerId?: string
+  tenantId?: string
+  inboundId: string
+  compact?: boolean
+  displayOnly?: boolean
+}>()
+
+const emit = defineEmits<{
+  changed: [snapshot: InboundFeeSnapshot]
+  loaded: [snapshot: InboundFeeSnapshot | null]
+}>()
+
+const access = useAccessPreviewStore()
+const loading = ref(false)
+const adjusting = ref(false)
+const feeAction = ref<'confirm' | 'send' | null>(null)
+const notFound = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const adjustmentError = ref<ApiErrorDetails | null>(null)
+const conflictRefreshed = ref(false)
+const snapshot = ref<InboundFeeSnapshot | null>(null)
+const adjustOpen = ref(false)
+const trialOpen = ref(false)
+const trialLoading = ref(false)
+const measurement = ref<InboundMeasurementDetail | null>(null)
+const trial = reactive({ weightSource: 'ACTUAL', volumeSource: 'ACTUAL' })
+const adjustFormRef = ref<FormInstance>()
+let loadSequence = 0
+let adjustmentFingerprint = ''
+let adjustmentIdempotencyKey = ''
+
+const adjustmentForm = reactive({
+  expectedFeeVersion: 0,
+  chargeableQuantity: 0,
+  unitPrice: 0,
+  additionalAmount: 0,
+  reason: '',
+})
+
+const adjustmentRules: FormRules = {
+  chargeableQuantity: [{ required: true, message: '请输入调整后的计费量', trigger: 'change' }],
+  unitPrice: [{ required: true, message: '请输入调整后的单价', trigger: 'change' }],
+  additionalAmount: [{ required: true, message: '请输入调整后的附加费', trigger: 'change' }],
+  reason: [
+    { required: true, whitespace: true, message: '请填写费用调整原因', trigger: 'blur' },
+    { min: 2, max: 500, message: '调整原因需为 2–500 个字符', trigger: 'blur' },
+  ],
+}
+
+const canView = computed(() => access.can('firstleg:fba-pricing:view'))
+const canAdjust = computed(() => access.can('firstleg:fba-pricing:adjust'))
+const canConfirm = computed(() => access.can('firstleg:fba-pricing:confirm'))
+const canSend = computed(() => access.can('firstleg:inbound:send-fee'))
+const canCalculate = computed(() => access.can('firstleg:fba-pricing:calculate'))
+const customerContextId = computed(() => props.customerId || props.tenantId || '')
+const normalizedInboundId = computed(() => {
+  const identifier = String(props.inboundId ?? '').trim()
+  return identifier && identifier !== 'null' && identifier !== 'undefined' ? identifier : ''
+})
+const adjustmentEligible = computed(() => (
+  ['CALCULATED', 'CONFIRMED', 'SENT'].includes(snapshot.value?.feeStatus || '')
+  && snapshot.value?.nextProcessStatus === 'WAIT_SPLIT'
+  && snapshot.value?.customerConfirmationStatus !== 'CONFIRMED'
+))
+const chargeModeLabel = computed(() => snapshot.value?.chargeMode === 'KG' ? '按重量计费' : '按体积计费')
+const chargeUnitLabel = computed(() => snapshot.value?.chargeUnit === 'KG' ? 'KG' : 'CBM')
+const convertedQuantityLabel = computed(() => snapshot.value?.chargeMode === 'KG' ? '体积重量' : '重量折算体积')
+const adjustmentBaseline = computed(() => Number(snapshot.value?.baselineChargeableQuantity || 0))
+const adjustmentMinimum = computed(() => Number(snapshot.value?.lowerChargeableQuantity || 0))
+const adjustmentMaximum = computed(() => Number(snapshot.value?.upperChargeableQuantity || 0))
+const adjustmentQuantityChanged = computed(() => Math.abs(Number(adjustmentForm.chargeableQuantity) - adjustmentBaseline.value) > 1e-8)
+const statusInfo = computed(() => feeStatusInfo(snapshot.value?.feeStatus))
+const sourceOptions = computed(() => {
+  const value = measurement.value
+  if (!value) return []
+  const itemWeight = value.items.reduce((sum, item) => sum + Number(item.totalWeightKg || 0), 0)
+  const itemVolume = value.items.reduce((sum, item) => sum + Number(item.totalVolumeCbm || 0), 0)
+  return [
+    { value: 'CUSTOMER', label: '客户下单数据', weight: Number(value.originalGrossWeightKg || 0), volume: Number(value.originalVolumeCbm || 0) },
+    { value: 'OUTER', label: '外箱规数据', weight: itemWeight, volume: itemVolume },
+    { value: 'ACTUAL', label: '实际测量数据', weight: Number(value.actualNetWeightKg || value.actualGrossWeightKg || 0), volume: Number(value.actualVolumeCbm || 0) },
+    { value: 'WAREHOUSE', label: '仓库建议数据', weight: itemWeight, volume: itemVolume },
+  ]
+})
+
+function feeStatusInfo(status?: string) {
+  const map: Record<string, { label: string; type: 'success' | 'warning' | 'info' }> = {
+    CALCULATED: { label: '已试算', type: 'warning' },
+    CONFIRMED: { label: '已确认', type: 'info' },
+    SENT: { label: '已发布', type: 'success' },
+    SUPERSEDED: { label: '历史版本', type: 'info' },
+  }
+  return map[status || ''] || { label: '未知状态', type: 'info' as const }
+}
+
+function formatNumber(value: number | null | undefined, digits = 3) {
+  if (value === null || value === undefined || !Number.isFinite(Number(value))) return '—'
+  return new Intl.NumberFormat('zh-CN', { maximumFractionDigits: digits }).format(Number(value))
+}
+
+function formatMoney(value: number | null | undefined, currency?: string) {
+  if (value === null || value === undefined || !Number.isFinite(Number(value))) return '—'
+  try {
+    return new Intl.NumberFormat('zh-CN', {
+      style: 'currency', currency: currency || 'CNY', minimumFractionDigits: 2,
+    }).format(Number(value))
+  } catch {
+    return `${formatNumber(value, 2)} ${currency || ''}`.trim()
+  }
+}
+
+function formatDateTime(value: string | null | undefined) {
+  if (!value) return '—'
+  const date = new Date(value)
+  if (Number.isNaN(date.getTime())) return value.replace('T', ' ')
+  return new Intl.DateTimeFormat('zh-CN', {
+    year: 'numeric', month: '2-digit', day: '2-digit',
+    hour: '2-digit', minute: '2-digit', hour12: false,
+  }).format(date)
+}
+
+function taxModeLabel(value: string) {
+  return firstLegTaxModeLabel(value)
+}
+
+function pricingTaxModeLabel(value: string | null | undefined) {
+  if (value === 'TAX_INCLUDED') return '包税'
+  if (value === 'TAX_EXCLUDED') return '不包税'
+  return '—'
+}
+
+function roundingModeLabel(value: string) {
+  const labels: Record<string, string> = {
+    UP: '远离零方向', DOWN: '向零方向', CEILING: '向上', FLOOR: '向下',
+    HALF_UP: '四舍五入', HALF_DOWN: '五舍六入', HALF_EVEN: '银行家舍入',
+  }
+  return labels[value] || '未知规则'
+}
+
+async function loadFee(options: { preserveAdjustment?: boolean } = {}) {
+  const sequence = ++loadSequence
+  loadError.value = null
+  notFound.value = false
+  if (!customerContextId.value || !normalizedInboundId.value || !canView.value) {
+    snapshot.value = null
+    loading.value = false
+    return
+  }
+  loading.value = true
+  try {
+    const result = await getLatestInboundFee(customerContextId.value, normalizedInboundId.value)
+    if (sequence !== loadSequence) return
+    snapshot.value = result
+    emit('loaded', result)
+    if (!options.preserveAdjustment && adjustOpen.value) fillAdjustmentForm(result)
+  } catch (error) {
+    if (sequence !== loadSequence) return
+    snapshot.value = null
+    emit('loaded', null)
+    if (error instanceof ApiResponseError && error.code === 'A0404') notFound.value = true
+    else loadError.value = getApiErrorDetails(error, '费用快照加载失败，请稍后重试')
+  } finally {
+    if (sequence === loadSequence) loading.value = false
+  }
+}
+
+function fillAdjustmentForm(value: InboundFeeSnapshot) {
+  adjustmentForm.expectedFeeVersion = Number(value.feeVersion)
+  adjustmentForm.chargeableQuantity = Number(value.chargeableQuantity)
+  adjustmentForm.unitPrice = Number(value.unitPrice)
+  adjustmentForm.additionalAmount = Number(value.additionalAmount)
+  adjustmentForm.reason = ''
+  adjustmentError.value = null
+  conflictRefreshed.value = false
+  adjustmentFingerprint = ''
+  adjustmentIdempotencyKey = ''
+}
+
+function openAdjustment() {
+  if (!snapshot.value || !adjustmentEligible.value) return
+  fillAdjustmentForm(snapshot.value)
+  adjustOpen.value = true
+}
+
+async function openTrial() {
+  trialLoading.value = true
+  try { measurement.value = await getInboundMeasurement(customerContextId.value, normalizedInboundId.value); trial.weightSource = 'ACTUAL'; trial.volumeSource = 'ACTUAL'; trialOpen.value = true }
+  catch (error) { ElMessage.error(getApiErrorDetails(error, '测量数据加载失败，无法试算').message) }
+  finally { trialLoading.value = false }
+}
+
+async function submitTrial() {
+  const weight = sourceOptions.value.find((item) => item.value === trial.weightSource)
+  const volume = sourceOptions.value.find((item) => item.value === trial.volumeSource)
+  if (!weight?.weight || !volume?.volume) { ElMessage.warning('所选重量或体积没有有效数据'); return }
+  trialLoading.value = true
+  try {
+    const result = await calculateInboundFee(customerContextId.value, normalizedInboundId.value, { selectedWeightKg: weight.weight, selectedVolumeCbm: volume.volume, weightSource: weight.value, volumeSource: volume.value }, createFeeActionIdempotencyKey('calculate'))
+    snapshot.value = result; trialOpen.value = false; emit('changed', result); ElMessage.success('费用试算已更新')
+  } catch (error) { adjustmentError.value = getApiErrorDetails(error, '费用试算失败') }
+  finally { trialLoading.value = false }
+}
+
+async function confirmAndPush() {
+  if (!snapshot.value || feeAction.value) return
+  try { await ElMessageBox.confirm('将确认当前试算结果并立即推送给客户，是否继续？', '确认推送费用', { type: 'warning', confirmButtonText: '确认推送' }) } catch { return }
+  feeAction.value = 'confirm'
+  try {
+    await confirmInboundFee(customerContextId.value, normalizedInboundId.value, createFeeActionIdempotencyKey('confirm'))
+    feeAction.value = 'send'
+    const result = await sendInboundFee(customerContextId.value, normalizedInboundId.value, createFeeActionIdempotencyKey('send'))
+    snapshot.value = result; emit('changed', result); ElMessage.success('费用已确认并推送给客户')
+  } catch (error) { adjustmentError.value = getApiErrorDetails(error, '确认推送费用失败'); await loadFee() }
+  finally { feeAction.value = null }
+}
+
+async function transitionFee(action: 'confirm' | 'send') {
+  if (!snapshot.value || feeAction.value) return
+  const confirming = action === 'confirm'
+  const expectedStatus = confirming ? 'CALCULATED' : 'CONFIRMED'
+  if (snapshot.value.feeStatus !== expectedStatus) return
+  try {
+    await ElMessageBox.confirm(
+      confirming
+        ? '确认后费用金额与计费依据将进入已确认状态，下一步需要发送费用。是否继续？'
+        : '发送后费用将正式发布，并进入客户应收应付费用来源。是否继续？',
+      confirming ? '确认头程费用' : '发送头程费用',
+      {
+        type: confirming ? 'warning' : 'success',
+        confirmButtonText: confirming ? '确认费用' : '确认发送',
+        cancelButtonText: '取消',
+      },
+    )
+  } catch {
+    return
+  }
+  feeAction.value = action
+  adjustmentError.value = null
+  try {
+    const key = createFeeActionIdempotencyKey(action)
+    const result = confirming
+      ? await confirmInboundFee(customerContextId.value, normalizedInboundId.value, key)
+      : await sendInboundFee(customerContextId.value, normalizedInboundId.value, key)
+    snapshot.value = result
+    emit('changed', result)
+    ElMessage.success(confirming ? '费用已确认，请继续发送费用' : '费用已发送并发布')
+  } catch (error) {
+    adjustmentError.value = getApiErrorDetails(error, confirming ? '费用确认失败，请刷新后重试' : '费用发送失败，请刷新后重试')
+    await loadFee()
+  } finally {
+    feeAction.value = null
+  }
+}
+
+function adjustmentPayload(): AdjustPublishedInboundFeeRequest {
+  return {
+    expectedFeeVersion: adjustmentForm.expectedFeeVersion,
+    chargeableQuantity: Number(adjustmentForm.chargeableQuantity),
+    unitPrice: Number(adjustmentForm.unitPrice),
+    additionalAmount: Number(adjustmentForm.additionalAmount),
+    reason: adjustmentForm.reason.trim(),
+    toleranceConfirmed: true,
+  }
+}
+
+function getAdjustmentKey(payload: AdjustPublishedInboundFeeRequest) {
+  const fingerprint = JSON.stringify(payload)
+  if (!adjustmentIdempotencyKey || fingerprint !== adjustmentFingerprint) {
+    adjustmentFingerprint = fingerprint
+    adjustmentIdempotencyKey = createFeeAdjustmentIdempotencyKey()
+  }
+  return adjustmentIdempotencyKey
+}
+
+async function submitAdjustment() {
+  if (!snapshot.value) return
+  const valid = await adjustFormRef.value?.validate().catch(() => false)
+  if (!valid) return
+  const nextQuantity = Number(adjustmentForm.chargeableQuantity)
+  if (nextQuantity < adjustmentMinimum.value || nextQuantity > adjustmentMaximum.value) {
+    ElMessage.warning(`调整后计费量须在基准值的 ±10% 范围内（${formatNumber(adjustmentMinimum.value, 4)}–${formatNumber(adjustmentMaximum.value, 4)} ${chargeUnitLabel.value}）`)
+    return
+  }
+  if (adjustmentQuantityChanged.value) {
+    try {
+      await ElMessageBox.confirm(
+        `计费量将由 ${formatNumber(adjustmentBaseline.value, 4)} 调整为 ${formatNumber(nextQuantity, 4)} ${chargeUnitLabel.value}，并生成新费用版本。是否继续？`,
+        '再次确认计费量调整',
+        { type: 'warning', confirmButtonText: '确认调整', cancelButtonText: '返回检查' },
+      )
+    } catch {
+      return
+    }
+  }
+  const payload = adjustmentPayload()
+  adjustmentError.value = null
+  conflictRefreshed.value = false
+  adjusting.value = true
+  try {
+    const result = await adjustPublishedInboundFee(
+      customerContextId.value,
+      normalizedInboundId.value,
+      payload,
+      getAdjustmentKey(payload),
+    )
+    snapshot.value = result
+    adjustOpen.value = false
+    ElMessage.success(`费用已调整为第 ${result.feeVersion} 版`)
+    emit('changed', result)
+  } catch (error) {
+    adjustmentError.value = getApiErrorDetails(error, '费用调整失败，请检查后重试')
+    if (error instanceof ApiResponseError && error.code === 'A0409') {
+      await loadFee({ preserveAdjustment: true })
+      conflictRefreshed.value = true
+      adjustmentFingerprint = ''
+      adjustmentIdempotencyKey = ''
+    }
+  } finally {
+    adjusting.value = false
+  }
+}
+
+watch(
+  () => [customerContextId.value, normalizedInboundId.value, access.permissionSignature],
+  () => {
+    adjustOpen.value = false
+    snapshot.value = null
+    void loadFee()
+  },
+  { immediate: true },
+)
+
+defineExpose({ reload: loadFee })
+</script>
+
+<template>
+  <section class="inbound-fee-panel" :aria-busy="loading" aria-labelledby="inbound-fee-title">
+    <header class="fee-heading" :class="{ 'fee-heading--compact': compact }">
+      <h3 v-if="compact" id="inbound-fee-title" class="fee-heading-title--compact">头程自动初算</h3>
+      <div v-else class="fee-heading-copy">
+        <span class="fee-heading-icon" aria-hidden="true"><CircleDollarSign :size="20" /></span>
+        <div>
+          <h3 id="inbound-fee-title">入库费用快照</h3>
+          <p>测量审核后的头程费用，人工确认后才发布。</p>
+        </div>
+      </div>
+      <div class="fee-heading-actions">
+        <el-tooltip content="刷新费用快照" placement="top">
+          <el-button
+            class="fee-refresh-button"
+            circle
+            aria-label="刷新费用快照"
+            :aria-busy="loading"
+            :disabled="loading || !customerContextId || !normalizedInboundId || !canView"
+            @click="loadFee()"
+          ><RefreshCw :size="16" :class="{ 'is-spinning': loading }" /></el-button>
+        </el-tooltip>
+        <el-button
+          v-if="!displayOnly && canCalculate"
+          type="primary"
+          plain
+          :loading="trialLoading"
+          @click="openTrial"
+        ><CircleDollarSign :size="16" />费用试算</el-button>
+        <el-button
+          v-if="!displayOnly && canAdjust && adjustmentEligible"
+          data-testid="adjust-fee-button"
+          type="primary"
+          @click="openAdjustment"
+        ><PencilLine :size="16" />{{ snapshot?.feeStatus === 'CALCULATED' ? '调整初算费用' : '调整已发布费用' }}</el-button>
+        <el-button
+          v-if="!displayOnly && canConfirm && snapshot?.feeStatus === 'CALCULATED'"
+          data-testid="confirm-fee-button"
+          type="primary"
+          :loading="feeAction === 'confirm'"
+          :disabled="Boolean(feeAction)"
+          @click="transitionFee('confirm')"
+        ><Check :size="16" />确认费用</el-button>
+        <el-button
+          v-if="!displayOnly && canConfirm && canSend && snapshot?.feeStatus === 'CALCULATED'"
+          type="primary"
+          :loading="Boolean(feeAction)"
+          :disabled="Boolean(feeAction)"
+          @click="confirmAndPush"
+        ><Send :size="16" />确认推送费用</el-button>
+        <el-button
+          v-if="!displayOnly && canSend && snapshot?.feeStatus === 'CONFIRMED'"
+          data-testid="send-fee-button"
+          type="primary"
+          :loading="feeAction === 'send'"
+          :disabled="Boolean(feeAction)"
+          @click="transitionFee('send')"
+        ><Send :size="16" />发送费用</el-button>
+      </div>
+    </header>
+
+    <AppDialog v-model="trialOpen" title="头程费用试算" width="min(760px, calc(100vw - 28px))" :confirm-loading="trialLoading" confirm-text="开始试算" @confirm="submitTrial">
+      <el-alert title="重量和体积各选择一项；默认选择实际测量数据。" type="info" :closable="false" show-icon />
+      <div class="trial-source-grid">
+        <section><h4>计费重量（单选）</h4><el-radio-group v-model="trial.weightSource"><el-radio v-for="item in sourceOptions" :key="`weight-${item.value}`" :value="item.value" :disabled="item.weight <= 0"><span>{{ item.label }}</span><strong>{{ formatNumber(item.weight) }} KG</strong></el-radio></el-radio-group></section>
+        <section><h4>计费体积（单选）</h4><el-radio-group v-model="trial.volumeSource"><el-radio v-for="item in sourceOptions" :key="`volume-${item.value}`" :value="item.value" :disabled="item.volume <= 0"><span>{{ item.label }}</span><strong>{{ formatNumber(item.volume, 6) }} CBM</strong></el-radio></el-radio-group></section>
+      </div>
+    </AppDialog>
+
+    <el-alert v-if="!canView" type="warning" :closable="false" show-icon>
+      <template #title>当前账号没有查看入库费用的权限</template>
+      <p>需要权限：firstleg:fba-pricing:view</p>
+    </el-alert>
+
+    <div v-else-if="loading && !snapshot" class="fee-loading" aria-live="polite">
+      <el-skeleton :rows="6" animated />
+      <span class="sr-only">正在加载费用快照</span>
+    </div>
+
+    <el-alert v-else-if="loadError" type="error" :closable="false" show-icon role="alert">
+      <template #title>费用快照加载失败</template>
+      <p>{{ loadError.message }}</p>
+      <ApiErrorMeta :details="loadError" />
+      <el-button size="small" @click="loadFee()">重新加载</el-button>
+    </el-alert>
+
+    <el-empty v-else-if="notFound" :image-size="64" description="尚未生成费用快照">
+      <p class="empty-note">测量审核完成后，系统会自动生成初算费用；人工确认后才发布。</p>
+    </el-empty>
+
+    <div v-else-if="snapshot" class="fee-content">
+      <div class="fee-summary" aria-label="费用关键结果">
+        <div class="fee-total">
+          <span>头程自动费用 · {{ snapshot.currency }}</span>
+          <strong>{{ formatMoney(snapshot.totalAmount, snapshot.currency) }}</strong>
+          <small>基础运费小计 {{ formatMoney(snapshot.subtotalAmount, snapshot.currency) }} · 附加费 {{ formatMoney(snapshot.additionalAmount, snapshot.currency) }}</small>
+        </div>
+        <div class="fee-summary-item">
+          <span>最终计费量</span>
+          <strong>{{ formatNumber(snapshot.chargeableQuantity, snapshot.roundingScale) }} {{ chargeUnitLabel }}</strong>
+          <small>{{ chargeModeLabel }}</small>
+        </div>
+        <div class="fee-summary-item">
+          <span>单价</span>
+          <strong>{{ formatMoney(snapshot.unitPrice, snapshot.currency) }} / {{ chargeUnitLabel }}</strong>
+          <small>{{ snapshot.channelCode }}</small>
+        </div>
+        <div class="fee-summary-item">
+          <span>附加费</span>
+          <strong>{{ formatMoney(snapshot.additionalAmount, snapshot.currency) }}</strong>
+          <small>{{ snapshot.additionalAmount ? '已计入总额' : '无附加费' }}</small>
+        </div>
+        <div class="fee-summary-item">
+          <span>快照版本</span>
+          <div class="version-status"><strong>V{{ snapshot.feeVersion }}</strong><el-tag :type="statusInfo.type" effect="light">{{ statusInfo.label }}</el-tag></div>
+          <small>{{ snapshot.feeNo }}</small>
+        </div>
+      </div>
+
+      <section class="calculation-section" aria-labelledby="calculation-title">
+        <div class="section-title">
+          <div><h4 id="calculation-title">计费依据</h4><p v-if="!compact">实际重量与体积重量取大后计费，金额以服务端快照为准。</p></div>
+          <div class="calculation-tags">
+            <el-tag effect="plain">订单报关：{{ taxModeLabel(snapshot.taxMode) }}</el-tag>
+            <el-tag effect="plain">报价税制：{{ pricingTaxModeLabel(snapshot.pricingTaxMode) }}</el-tag>
+          </div>
+        </div>
+        <div class="calculation-flow">
+          <div><span>实际重量</span><strong>{{ formatNumber(snapshot.actualWeightKg, 3) }} KG</strong></div>
+          <div><span>实际体积</span><strong>{{ formatNumber(snapshot.actualVolumeCbm, 4) }} CBM</strong></div>
+          <div><span>{{ convertedQuantityLabel }}</span><strong>{{ formatNumber(snapshot.convertedQuantity, snapshot.roundingScale) }} {{ chargeUnitLabel }}</strong><small>系数 {{ formatNumber(snapshot.conversionFactor, 4) }}</small></div>
+          <div class="is-chargeable"><span>取大后的计费量</span><strong>{{ formatNumber(snapshot.chargeableQuantity, snapshot.roundingScale) }} {{ chargeUnitLabel }}</strong></div>
+        </div>
+        <div class="amount-equation" aria-label="费用计算公式">
+          <span>{{ formatNumber(snapshot.chargeableQuantity, snapshot.roundingScale) }} {{ chargeUnitLabel }}</span>
+          <i>×</i>
+          <span>{{ formatMoney(snapshot.unitPrice, snapshot.currency) }} / {{ chargeUnitLabel }}</span>
+          <i>+</i>
+          <span>附加费 {{ formatMoney(snapshot.additionalAmount, snapshot.currency) }}</span>
+          <i>=</i>
+          <strong>{{ formatMoney(snapshot.totalAmount, snapshot.currency) }}</strong>
+        </div>
+      </section>
+
+      <details class="fee-advanced">
+        <summary>查看价格来源与时间记录</summary>
+        <div class="fee-detail-grid">
+          <section v-if="snapshot.ruleCode" aria-labelledby="rule-title">
+            <div class="section-title"><div><h4 id="rule-title">客户计费规则</h4><p>{{ snapshot.ruleCode }} · V{{ snapshot.chargeRuleVersion }}</p></div></div>
+            <dl>
+              <div><dt>客户</dt><dd>{{ snapshot.customerName }}</dd></div>
+              <div><dt>业务类型</dt><dd>{{ firstLegBusinessTypeLabel(snapshot.businessType) }}</dd></div>
+              <div><dt>计费口径</dt><dd>{{ chargeModeLabel }}</dd></div>
+              <div><dt>舍入规则</dt><dd>{{ snapshot.roundingScale == null ? '—' : `保留 ${snapshot.roundingScale} 位，${roundingModeLabel(snapshot.roundingMode)}` }}</dd></div>
+            </dl>
+          </section>
+          <section aria-labelledby="rate-title">
+            <div class="section-title"><div><h4 id="rate-title">渠道价格</h4><p>{{ snapshot.rateCode }} · V{{ snapshot.carrierRateVersion }}</p></div></div>
+            <dl>
+              <div><dt>起运仓</dt><dd>{{ snapshot.originWarehouseName }}</dd></div>
+              <div><dt>渠道</dt><dd>{{ snapshot.channelCode }}</dd></div>
+              <div><dt>FBA 目的仓</dt><dd>{{ snapshot.destinationCode }}</dd></div>
+              <div><dt>价格有效期</dt><dd>{{ formatDateTime(snapshot.rateEffectiveFrom) }} 至 {{ formatDateTime(snapshot.rateEffectiveTo) }}</dd></div>
+            </dl>
+          </section>
+        </div>
+
+        <section class="fee-timeline" aria-labelledby="fee-timeline-title">
+          <div class="section-title"><div><h4 id="fee-timeline-title">时间记录</h4></div></div>
+          <ol>
+            <li><span>试算</span><strong>{{ formatDateTime(snapshot.calculatedAt) }}</strong></li>
+            <li :class="{ pending: !snapshot.confirmedAt }"><span>确认</span><strong>{{ formatDateTime(snapshot.confirmedAt) }}</strong></li>
+            <li :class="{ pending: !snapshot.sentAt }"><span>发布</span><strong>{{ formatDateTime(snapshot.sentAt) }}</strong></li>
+          </ol>
+        </section>
+      </details>
+    </div>
+
+    <OperationErrorToast :details="adjustmentError" />
+
+    <AppDialog
+      v-model="adjustOpen"
+      title="调整入库费用"
+      width="min(760px, calc(100vw - 28px))"
+      confirm-text="确认调整并生成新版本"
+      confirm-type="warning"
+      :confirm-loading="adjusting"
+      @confirm="submitAdjustment"
+    >
+      <el-alert type="warning" :closable="false" show-icon title="调整会生成新的费用版本；小计和总额由服务端按计费量、单价和附加费重算。" />
+      <el-alert class="adjustment-alert" type="info" :closable="false" show-icon>
+        <template #title>计费量允许在系统原始基准值 ±{{ formatNumber(snapshot?.tolerancePercent, 2) }}% 内调整</template>
+        <p>系统基准 {{ formatNumber(adjustmentBaseline, 4) }} {{ chargeUnitLabel }}，服务端允许范围 {{ formatNumber(adjustmentMinimum, 4) }}–{{ formatNumber(adjustmentMaximum, 4) }} {{ chargeUnitLabel }}（包含边界）；超出范围将无法提交。</p>
+      </el-alert>
+      <el-alert v-if="conflictRefreshed" class="adjustment-alert" type="warning" :closable="false" show-icon>
+        <template #title>费用已被其他操作员更新，系统已刷新最新快照</template>
+        <p>当前输入仍保留，请先核对最新版本后再提交。</p>
+      </el-alert>
+      <el-form ref="adjustFormRef" :model="adjustmentForm" :rules="adjustmentRules" label-position="top" class="adjustment-form" :disabled="adjusting">
+        <div class="adjustment-amounts">
+          <el-form-item label="调整后计费量" prop="chargeableQuantity" required>
+            <el-input-number v-model="adjustmentForm.chargeableQuantity" aria-label="调整后计费量" :min="adjustmentMinimum" :max="adjustmentMaximum" :precision="4" :step="1" controls-position="right" placeholder="请输入调整后计费量" />
+            <span class="adjustment-unit">{{ chargeUnitLabel }}</span>
+          </el-form-item>
+          <el-form-item label="调整后单价" prop="unitPrice" required>
+            <el-input-number v-model="adjustmentForm.unitPrice" aria-label="调整后单价" :min="0" :max="999999999999.9999" :precision="4" :step="0.1" controls-position="right" placeholder="请输入调整后单价" />
+            <span class="adjustment-unit">{{ snapshot?.currency }} / {{ chargeUnitLabel }}</span>
+          </el-form-item>
+          <el-form-item label="调整后附加费" prop="additionalAmount" required>
+            <el-input-number v-model="adjustmentForm.additionalAmount" aria-label="调整后附加费" :min="0" :max="999999999999.99" :precision="2" :step="10" controls-position="right" placeholder="请输入调整后附加费" />
+            <span class="adjustment-unit">{{ snapshot?.currency }}</span>
+          </el-form-item>
+        </div>
+        <div class="adjustment-total"><span>当前服务端计算金额</span><strong>{{ formatMoney(snapshot?.totalAmount, snapshot?.currency) }}</strong><small>提交后以服务端返回的新版本金额为准</small></div>
+        <el-form-item label="调整原因" prop="reason" required>
+          <el-input v-model="adjustmentForm.reason" type="textarea" :rows="4" maxlength="500" show-word-limit placeholder="说明价格变更、补充费用或修正原因，记录将进入审计历史" />
+        </el-form-item>
+      </el-form>
+    </AppDialog>
+  </section>
+</template>
+
+<style scoped>
+.inbound-fee-panel { min-width: 0; color: var(--cc-text); }
+.fee-heading { display: flex; align-items: flex-start; justify-content: space-between; gap: 16px; padding-bottom: 16px; }
+.fee-heading--compact { align-items: center; justify-content: space-between; padding: 12px 0 8px; }
+.fee-heading h3.fee-heading-title--compact { color: #344054; font-size: var(--admin-font-section, 14px); line-height: 1.4; }
+.fee-heading-copy { display: flex; min-width: 0; align-items: flex-start; gap: 12px; }
+.fee-heading-icon { display: grid; width: 38px; height: 38px; flex: 0 0 38px; place-items: center; border-radius: 10px; background: #eef4ff; color: var(--cc-primary); }
+.fee-heading h3, .section-title h4 { margin: 0; }
+.fee-heading h3 { font-size: 16px; }
+.fee-heading p, .section-title p { margin: 5px 0 0; color: var(--cc-muted); font-size: 12px; line-height: 1.55; }
+.fee-heading-actions { display: flex; flex-wrap: wrap; justify-content: flex-end; gap: 8px; }
+.fee-heading-actions .el-button { margin-left: 0; }
+.fee-refresh-button .is-spinning { animation: fee-refresh-spin 0.8s linear infinite; }
+.fee-loading { padding: 20px 0; }
+.inbound-fee-panel :deep(.el-alert p) { margin: 5px 0 0; line-height: 1.55; }
+.inbound-fee-panel :deep(.el-alert .el-button) { margin-top: 8px; }
+.empty-note { margin: 0; color: var(--cc-muted); font-size: 12px; }
+.fee-content { border-top: 1px solid var(--cc-border); }
+.fee-summary { display: grid; grid-template-columns: minmax(230px, 1.3fr) repeat(4, minmax(135px, 1fr)); border-top: 1px solid var(--cc-border); border-bottom: 1px solid var(--cc-border); }
+.fee-total, .fee-summary-item { display: flex; min-width: 0; flex-direction: column; justify-content: center; gap: 3px; padding: 11px 14px; }
+.fee-summary-item { border-left: 1px solid var(--cc-border); }
+.fee-summary span, .fee-summary small { color: var(--cc-muted); font-size: 11px; }
+.fee-summary strong { font-size: 18px; line-height: 1.25; overflow-wrap: anywhere; }
+.fee-total strong { color: #0f5c49; font-size: 21px; letter-spacing: -.01em; }
+.fee-summary-item strong { font-size: 15px; }
+.version-status { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; }
+@keyframes fee-refresh-spin { to { transform: rotate(360deg); } }
+.calculation-section, .fee-timeline { padding: 10px 0; border-bottom: 1px solid var(--cc-border); }
+.section-title { display: flex; align-items: flex-start; justify-content: space-between; gap: 16px; }
+.calculation-tags { display: flex; flex-wrap: wrap; justify-content: flex-end; gap: 6px; }
+.section-title h4 { font-size: 14px; }
+.calculation-flow { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); margin-top: 7px; border-top: 1px solid var(--cc-border); border-bottom: 1px solid var(--cc-border); }
+.calculation-flow > div { display: flex; min-width: 0; min-height: 46px; flex-direction: row; align-items: center; justify-content: space-between; gap: 8px; padding: 6px 10px; border-right: 1px solid var(--cc-border); }
+.calculation-flow > div:last-child { border-right: 0; }
+.calculation-flow span, .calculation-flow small { color: var(--cc-muted); font-size: 11px; }
+.calculation-flow strong { font-size: 13px; overflow-wrap: anywhere; }
+.calculation-flow small { display: none; }
+.calculation-flow .is-chargeable { background: #f7fbfa; }
+.calculation-flow .is-chargeable strong { color: #087d70; }
+.amount-equation { display: flex; flex-wrap: wrap; align-items: center; gap: 7px; margin-top: 5px; padding: 4px 0 0; color: #475467; font-size: 12px; }
+.amount-equation i { color: #98a2b3; font-style: normal; }
+.amount-equation strong { color: var(--cc-text); font-size: 15px; }
+.fee-detail-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); border-bottom: 1px solid var(--cc-border); }
+.fee-detail-grid > section { min-width: 0; padding: 22px 20px 22px 0; }
+.fee-detail-grid > section + section { padding-right: 0; padding-left: 20px; border-left: 1px solid var(--cc-border); }
+.fee-detail-grid dl { margin: 14px 0 0; }
+.fee-detail-grid dl > div { display: grid; grid-template-columns: 104px minmax(0, 1fr); gap: 12px; padding: 9px 0; border-top: 1px solid #edf0f4; font-size: 12px; }
+.fee-detail-grid dt { color: var(--cc-muted); }
+.fee-detail-grid dd { min-width: 0; margin: 0; font-weight: 600; overflow-wrap: anywhere; }
+.fee-timeline { border-bottom: 0; }
+.fee-timeline ol { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 0; margin: 18px 0 0; padding: 0; list-style: none; }
+.fee-timeline li { position: relative; display: flex; min-width: 0; flex-direction: column; gap: 5px; padding: 0 18px 0 20px; }
+.fee-timeline li::before { position: absolute; top: 4px; left: 0; width: 9px; height: 9px; border-radius: 50%; background: #12b76a; content: ''; }
+.fee-timeline li::after { position: absolute; top: 8px; right: 0; left: 10px; z-index: -1; height: 1px; background: var(--cc-border); content: ''; }
+.fee-timeline li:last-child::after { display: none; }
+.fee-timeline li.pending::before { background: #98a2b3; }
+.fee-timeline span { color: var(--cc-muted); font-size: 11px; }
+.fee-timeline strong { font-size: 12px; overflow-wrap: anywhere; }
+.fee-advanced { border-top: 1px solid var(--cc-border); }
+.fee-advanced > summary { padding: 10px 2px; color: var(--cc-primary); font-size: 12px; font-weight: 600; cursor: pointer; }
+.fee-advanced:not([open]) > summary { border-bottom: 0; }
+.fee-advanced .fee-detail-grid > section:only-child { grid-column: 1 / -1; }
+.adjustment-alert { margin-top: 12px; }
+.adjustment-form { margin-top: 18px; }
+.adjustment-amounts { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 18px; }
+.adjustment-amounts :deep(.el-form-item) { min-width: 0; margin-bottom: 18px; }
+.adjustment-amounts :deep(.el-form-item__content) { display: grid; grid-template-columns: minmax(0, 1fr) auto; flex-wrap: nowrap; column-gap: 8px; }
+.adjustment-amounts :deep(.el-input-number) { width: 100%; }
+.adjustment-unit { min-width: max-content; color: var(--cc-muted); font-size: 12px; white-space: nowrap; }
+.adjustment-total { display: grid; grid-template-columns: auto minmax(150px, 1fr) auto; align-items: baseline; gap: 18px; margin: 0 0 18px; padding: 13px 16px; border-radius: 8px; background: #f8fafc; }
+.adjustment-total span { color: var(--cc-muted); font-size: 12px; }
+.adjustment-total strong { justify-self: center; font-size: 18px; white-space: nowrap; }
+.adjustment-total small { color: var(--cc-muted); font-size: 11px; text-align: right; }
+.trial-source-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 18px; margin-top: 16px; }.trial-source-grid section { padding: 14px; border: 1px solid var(--cc-border); border-radius: 8px; }.trial-source-grid h4 { margin: 0 0 12px; }.trial-source-grid :deep(.el-radio-group) { display: grid; gap: 10px; }.trial-source-grid :deep(.el-radio) { display: grid; grid-template-columns: minmax(0, 1fr) auto; width: 100%; height: auto; margin: 0; padding: 10px; border: 1px solid var(--cc-border); border-radius: 6px; }.trial-source-grid :deep(.el-radio__label) { display: flex; min-width: 0; justify-content: space-between; gap: 10px; }.trial-source-grid strong { color: var(--cc-text); }
+.sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); clip-path: inset(50%); white-space: nowrap; }
+
+@media (max-width: 900px) {
+  .fee-summary { grid-template-columns: 1fr 1fr; }
+  .fee-total { grid-column: 1 / -1; }
+  .fee-summary-item:first-of-type { border-left: 0; }
+  .calculation-flow { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+  .calculation-flow > div:nth-child(2) { border-right: 0; }
+  .calculation-flow > div:nth-child(-n+2) { border-bottom: 1px solid var(--cc-border); }
+}
+
+@media (max-width: 720px) {
+  .fee-heading { align-items: stretch; flex-direction: column; }
+  .fee-heading-actions { justify-content: flex-start; }
+  .fee-heading-actions .el-button:not(.is-circle) { flex: 1; min-height: 44px; }
+  .fee-summary, .calculation-flow, .fee-detail-grid, .fee-timeline ol { grid-template-columns: 1fr; }
+  .fee-summary-item { border-top: 1px solid var(--cc-border); border-left: 0; }
+  .calculation-flow > div { min-height: 76px; border-right: 0; border-bottom: 1px solid var(--cc-border); }
+  .calculation-flow > div:last-child { border-bottom: 0; }
+  .fee-detail-grid > section, .fee-detail-grid > section + section { padding: 20px 0; border-left: 0; }
+  .fee-detail-grid > section + section { border-top: 1px solid var(--cc-border); }
+  .fee-timeline ol { gap: 16px; }
+  .fee-timeline li { padding-left: 20px; }
+  .fee-timeline li::after { display: none; }
+  .adjustment-amounts { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+  .adjustment-total { grid-template-columns: auto 1fr; }
+  .adjustment-total strong { justify-self: end; }
+  .adjustment-total small { grid-column: 1 / -1; text-align: left; }
+}
+
+@media (max-width: 520px) {
+  .adjustment-amounts { grid-template-columns: 1fr; gap: 0; }
+  .adjustment-total { grid-template-columns: 1fr; gap: 6px; }
+  .adjustment-total strong { justify-self: start; }
+}
+
+@media (max-width: 360px) {
+  .fee-heading-copy { gap: 8px; }
+  .fee-heading-icon { width: 34px; height: 34px; flex-basis: 34px; }
+  .fee-total, .fee-summary-item { padding: 16px 12px; }
+  .fee-total strong { font-size: 22px; }
+  .fee-detail-grid dl > div { grid-template-columns: 1fr; gap: 4px; }
+  .amount-equation { align-items: flex-start; flex-direction: column; }
+  .amount-equation i { display: none; }
+}
+</style>
diff --git a/src/modules/inbounds/fee/api.test.ts b/src/modules/inbounds/fee/api.test.ts
new file mode 100644
index 00000000..95f7aab9
--- /dev/null
+++ b/src/modules/inbounds/fee/api.test.ts
@@ -0,0 +1,98 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { ApiResponseError, http } from '@/shared/api/http'
+import {
+  adjustPublishedInboundFee,
+  confirmInboundFee,
+  createFeeActionIdempotencyKey,
+  createFeeAdjustmentIdempotencyKey,
+  getLatestInboundFee,
+  sendInboundFee,
+} from './api'
+
+vi.mock('@/shared/api/http', async () => {
+  const actual = await vi.importActual<typeof import('@/shared/api/http')>('@/shared/api/http')
+  return { ...actual, http: { get: vi.fn(), post: vi.fn(), put: vi.fn() } }
+})
+
+const snapshot = {
+  feeId: '9007199254740993',
+  feeNo: 'FBAF-88-2',
+  feeVersion: 2,
+  feeStatus: 'SENT',
+  inboundId: '88',
+  totalAmount: 1280,
+}
+
+describe('inbound fee API', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it.each(['', ' ', 'null', 'undefined'])('rejects invalid inboundId %j without issuing HTTP', async (inboundId) => {
+    await expect(getLatestInboundFee('10001', inboundId)).rejects.toThrow('inboundId is required')
+    expect(http.get).not.toHaveBeenCalled()
+  })
+
+  it('loads the latest immutable fee snapshot with string IDs', async () => {
+    vi.mocked(http.get).mockResolvedValue({ code: '200', message: 'success', data: snapshot })
+
+    await expect(getLatestInboundFee('10001', '88')).resolves.toEqual(snapshot)
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/inbounds/88/fees/latest', {
+      params: { tenantId: '10001' },
+    })
+  })
+
+  it('adjusts a published snapshot with the required idempotency key', async () => {
+    vi.mocked(http.put).mockResolvedValue({ code: '200', message: 'success', data: { ...snapshot, feeVersion: 3 } })
+    const payload = { expectedFeeVersion: 2, chargeableQuantity: 140, unitPrice: 8.2, additionalAmount: 80, reason: '补充已确认的附加费', toleranceConfirmed: true as const }
+
+    await expect(adjustPublishedInboundFee('10001', '88', payload, 'fee-adjust-1'))
+      .resolves.toMatchObject({ feeVersion: 3 })
+    expect(http.put).toHaveBeenCalledWith(
+      '/platform/v1/inbounds/88/fees/published',
+      payload,
+      { params: { tenantId: '10001' }, headers: { 'Idempotency-Key': 'fee-adjust-1' } },
+    )
+  })
+
+  it('confirms and sends a calculated fee with independent idempotency keys', async () => {
+    vi.mocked(http.post)
+      .mockResolvedValueOnce({ code: '200', message: 'success', data: { ...snapshot, feeStatus: 'CONFIRMED' } })
+      .mockResolvedValueOnce({ code: '200', message: 'success', data: snapshot })
+
+    await expect(confirmInboundFee('10001', '88', 'fee-confirm-1')).resolves.toMatchObject({ feeStatus: 'CONFIRMED' })
+    await expect(sendInboundFee('10001', '88', 'fee-send-1')).resolves.toMatchObject({ feeStatus: 'SENT' })
+
+    expect(http.post).toHaveBeenNthCalledWith(1, '/platform/v1/inbounds/88/fees/confirm', undefined, {
+      params: { tenantId: '10001' }, headers: { 'Idempotency-Key': 'fee-confirm-1' },
+    })
+    expect(http.post).toHaveBeenNthCalledWith(2, '/platform/v1/inbounds/88/fees/send', undefined, {
+      params: { tenantId: '10001' }, headers: { 'Idempotency-Key': 'fee-send-1' },
+    })
+  })
+
+  it('preserves backend conflict metadata for stale-version recovery', async () => {
+    vi.mocked(http.put).mockResolvedValue({
+      code: 'A0409', message: '费用已被其他操作员修改，请刷新后重试', data: null,
+      requestId: 'request-fee-409', traceId: 'trace-fee-409',
+    })
+
+    const error = await adjustPublishedInboundFee(
+      '10001',
+      '88',
+      { expectedFeeVersion: 2, chargeableQuantity: 140, unitPrice: 8.2, additionalAmount: 80, reason: '价格修正', toleranceConfirmed: true },
+      'fee-adjust-2',
+    ).catch((reason: unknown) => reason)
+
+    expect(error).toBeInstanceOf(ApiResponseError)
+    expect(error).toMatchObject({ code: 'A0409', requestId: 'request-fee-409', traceId: 'trace-fee-409' })
+  })
+
+  it('creates bounded unique keys for adjustment retries', () => {
+    const first = createFeeAdjustmentIdempotencyKey()
+    const second = createFeeAdjustmentIdempotencyKey()
+    expect(first).toMatch(/^fee-adjust-/)
+    expect(first.length).toBeLessThanOrEqual(128)
+    expect(second).not.toBe(first)
+    expect(createFeeActionIdempotencyKey('confirm')).toMatch(/^fee-confirm-/)
+    expect(createFeeActionIdempotencyKey('send')).toMatch(/^fee-send-/)
+  })
+})
diff --git a/src/modules/inbounds/fee/api.ts b/src/modules/inbounds/fee/api.ts
new file mode 100644
index 00000000..27993cfb
--- /dev/null
+++ b/src/modules/inbounds/fee/api.ts
@@ -0,0 +1,70 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import type { AdjustPublishedInboundFeeRequest, InboundFeeSnapshot } from './types'
+
+function feeBasePath(inboundId: string) {
+  const identifier = String(inboundId ?? '').trim()
+  if (!identifier || identifier === 'null' || identifier === 'undefined') throw new TypeError('inboundId is required')
+  return `/platform/v1/inbounds/${encodeURIComponent(identifier)}/fees`
+}
+
+export async function getLatestInboundFee(tenantId: string, inboundId: string) {
+  const response = await http.get<unknown, ApiEnvelope<InboundFeeSnapshot>>(
+    `${feeBasePath(inboundId)}/latest`,
+    { params: { tenantId } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function calculateInboundFee(tenantId: string, inboundId: string, payload: { selectedWeightKg: number; selectedVolumeCbm: number; weightSource: string; volumeSource: string }, idempotencyKey: string) {
+  const response = await http.post<unknown, ApiEnvelope<InboundFeeSnapshot>>(
+    `${feeBasePath(inboundId)}/calculate`, payload,
+    { params: { tenantId }, headers: { 'Idempotency-Key': idempotencyKey } },
+  )
+  return unwrapApiResponse(response)
+}
+
+async function transitionInboundFee(
+  tenantId: string,
+  inboundId: string,
+  action: 'confirm' | 'send',
+  idempotencyKey: string,
+) {
+  const response = await http.post<unknown, ApiEnvelope<InboundFeeSnapshot>>(
+    `${feeBasePath(inboundId)}/${action}`,
+    undefined,
+    { params: { tenantId }, headers: { 'Idempotency-Key': idempotencyKey } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export function confirmInboundFee(tenantId: string, inboundId: string, idempotencyKey: string) {
+  return transitionInboundFee(tenantId, inboundId, 'confirm', idempotencyKey)
+}
+
+export function sendInboundFee(tenantId: string, inboundId: string, idempotencyKey: string) {
+  return transitionInboundFee(tenantId, inboundId, 'send', idempotencyKey)
+}
+
+export async function adjustPublishedInboundFee(
+  tenantId: string,
+  inboundId: string,
+  payload: AdjustPublishedInboundFeeRequest,
+  idempotencyKey: string,
+) {
+  const response = await http.put<unknown, ApiEnvelope<InboundFeeSnapshot>>(
+    `${feeBasePath(inboundId)}/published`,
+    payload,
+    { params: { tenantId }, headers: { 'Idempotency-Key': idempotencyKey } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export function createFeeAdjustmentIdempotencyKey() {
+  return createFeeActionIdempotencyKey('adjust')
+}
+
+export function createFeeActionIdempotencyKey(action: 'adjust' | 'calculate' | 'confirm' | 'send') {
+  const uuid = globalThis.crypto?.randomUUID?.()
+  if (uuid) return `fee-${action}-${uuid}`
+  return `fee-${action}-${Date.now()}-${Math.random().toString(36).slice(2, 12)}`
+}
diff --git a/src/modules/inbounds/fee/index.ts b/src/modules/inbounds/fee/index.ts
new file mode 100644
index 00000000..f899b457
--- /dev/null
+++ b/src/modules/inbounds/fee/index.ts
@@ -0,0 +1,12 @@
+export { default as InboundFeePanel } from './InboundFeePanel.vue'
+export {
+  adjustPublishedInboundFee,
+  createFeeAdjustmentIdempotencyKey,
+  getLatestInboundFee,
+} from './api'
+export type {
+  AdjustPublishedInboundFeeRequest,
+  InboundChargeMode,
+  InboundFeeSnapshot,
+  InboundFeeStatus,
+} from './types'
diff --git a/src/modules/inbounds/fee/types.ts b/src/modules/inbounds/fee/types.ts
new file mode 100644
index 00000000..1e3b814b
--- /dev/null
+++ b/src/modules/inbounds/fee/types.ts
@@ -0,0 +1,67 @@
+export type InboundFeeStatus = 'CALCULATED' | 'CONFIRMED' | 'SENT' | 'SUPERSEDED' | string
+export type InboundChargeMode = 'KG' | 'CBM' | string
+
+export interface InboundFeeSnapshot {
+  feeId: string
+  feeNo: string
+  feeVersion: number
+  feeStatus: InboundFeeStatus
+  inboundId: string
+  inboundCode: string | null
+  measurementId?: string | null
+  measurementSource?: string | null
+  chargeRuleId: string
+  ruleCode: string
+  chargeRuleVersion: number
+  carrierRateId: string
+  rateCode: string
+  carrierRateVersion: number
+  customerId: string
+  customerName: string
+  originWarehouseId: string
+  originWarehouseName: string
+  businessType: string
+  channelCode: string
+  carrierId: string
+  carrierName: string
+  destinationCode: string
+  taxMode: string
+  pricingTaxMode: string | null
+  chargeMode: InboundChargeMode
+  conversionFactor: number
+  roundingScale: number
+  roundingMode: string
+  actualWeightKg: number
+  actualVolumeCbm: number
+  convertedQuantity: number
+  baselineChargeableQuantity: number
+  lowerChargeableQuantity: number
+  upperChargeableQuantity: number
+  tolerancePercent: number
+  chargeableQuantity: number
+  chargeUnit: string
+  unitPrice: number | null
+  subtotalAmount: number
+  additionalAmount: number
+  totalAmount: number
+  currency: string
+  rateEffectiveFrom: string
+  rateEffectiveTo: string | null
+  calculatedAt: string
+  confirmedAt: string | null
+  sentAt: string | null
+  nextProcessStatus: string | null
+  customerConfirmationStatus: 'PENDING_CONFIRMATION' | 'CONFIRMED'
+  customerConfirmedBy: string | null
+  customerConfirmedByName: string | null
+  customerConfirmedAt: string | null
+}
+
+export interface AdjustPublishedInboundFeeRequest {
+  expectedFeeVersion: number
+  chargeableQuantity: number
+  unitPrice: number
+  additionalAmount: number
+  reason: string
+  toleranceConfirmed: true
+}
diff --git a/src/modules/inbounds/index.ts b/src/modules/inbounds/index.ts
new file mode 100644
index 00000000..1aadb9cf
--- /dev/null
+++ b/src/modules/inbounds/index.ts
@@ -0,0 +1,20 @@
+export { getInboundMeasurement, saveInboundMeasurementDraft, updateMeasurementCalculationStrategy, updateMeasurementOuterDimensions } from './measurement/api'
+export { createInboundHoldIdempotencyKey, downloadInboundCartonLabelsBatch, downloadPlatformInboundHoldEvidence, getPlatformInboundHold, holdPlatformInbound, releasePlatformInbound, uploadPlatformInboundHoldEvidence } from './core/api'
+export { default as DropshipPalletPrintPanel } from './core/DropshipPalletPrintPanel.vue'
+export { default as InboundMeasurementPanel } from './measurement/InboundMeasurementPanel.vue'
+export { default as InboundMeasurementDialog } from './measurement/InboundMeasurementDialog.vue'
+export { default as MeasurementEvidenceThumbnail } from './measurement/components/MeasurementEvidenceThumbnail.vue'
+export { default as InboundFeePanel } from './fee/InboundFeePanel.vue'
+export {
+  adjustPublishedInboundFee,
+  calculateInboundFee,
+  confirmInboundFee,
+  createFeeAdjustmentIdempotencyKey,
+  createFeeActionIdempotencyKey,
+  getLatestInboundFee,
+  sendInboundFee,
+} from './fee/api'
+export type { AdjustPublishedInboundFeeRequest, InboundFeeSnapshot } from './fee/types'
+export { downloadWeightImage } from './weight/api/weightOcr'
+export type { InboundMeasurementDetail } from './measurement/types'
+export type { InboundHoldCommand, InboundHoldDetail, InboundHoldEvidenceUpload, InboundHoldHistoryEntry } from './core/types'
diff --git a/src/modules/inbounds/measurement/InboundMeasurementDialog.test.ts b/src/modules/inbounds/measurement/InboundMeasurementDialog.test.ts
new file mode 100644
index 00000000..afa33645
--- /dev/null
+++ b/src/modules/inbounds/measurement/InboundMeasurementDialog.test.ts
@@ -0,0 +1,73 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/inbounds/measurement/InboundMeasurementDialog.vue'), 'utf8')
+const panelSource = readFileSync(resolve(process.cwd(), 'src/modules/inbounds/measurement/InboundMeasurementPanel.vue'), 'utf8')
+const taskListSource = readFileSync(resolve(process.cwd(), 'src/modules/inbounds/components/InboundTaskList.vue'), 'utf8')
+const orderListSource = readFileSync(resolve(process.cwd(), 'src/modules/unified-orders/pages/UnifiedOrdersView.vue'), 'utf8')
+
+const densitySource = readFileSync(resolve(process.cwd(), 'src/styles/adminDensity.css'), 'utf8')
+
+describe('InboundMeasurementDialog', () => {
+  it('owns the complete measurement workspace behind one centered dialog', () => {
+    expect(source).toContain("import AppDialog from '@/shared/components/AppDialog.vue'")
+    expect(source).toContain('<AppDialog')
+    expect(source).toContain('class="inbound-measurement-workspace-dialog admin-density-dialog admin-density-workspace inbound-density"')
+    expect(source).toContain('width="min(1560px, calc(100vw - 48px))"')
+    expect(source).toContain('height: 92vh')
+    expect(densitySource).toContain('.admin-density-dialog.el-dialog .el-dialog__header')
+    expect(densitySource).toContain('padding: var(--admin-space-4, 10px) 48px var(--admin-space-4, 10px) var(--admin-space-6, 16px)')
+    expect(source).toContain('<WeightOcrPanel')
+    expect(source).toContain('<InboundMeasurementPanel')
+    expect(source).toContain('class="measurement-dialog-weight"')
+    expect(source).not.toContain('class="surface-panel measurement-dialog-weight"')
+    expect(source).toContain('border-bottom: 1px solid var(--cc-border)')
+    expect(source).toContain('@summary-changed="handleWeightSummaryChanged"')
+    expect(source).toContain('measurementPanelRef.value?.updateWeightEvidence(actualGrossWeightKg, actualNetWeightKg, hasConfirmedWeight)')
+    expect(source).toContain('measurementPanelRef?.submissionBlockReason')
+  })
+
+  it('offers the shared fullscreen control without forcing fullscreen on open', () => {
+    expect(source).toContain('fullscreenable')
+    expect(source).not.toContain('default-fullscreen')
+    expect(source).not.toContain('<el-dialog')
+  })
+
+  it('shows the inbound code once in the dialog title and not as a second body heading', () => {
+    expect(source).toContain("`测量 · ${props.inboundCode?.trim() || '入仓码待补充'}`")
+    expect(source).not.toContain('props.inboundCode?.trim() || props.inboundId')
+    expect(source).toContain(':title="title"')
+    expect(panelSource).not.toContain('<span>入仓码</span>')
+    expect(panelSource).not.toContain('<strong>{{ detail.inboundCode')
+    expect(panelSource).toContain('class="measurement-summary-context"')
+  })
+
+  it('is the only measurement dialog opened by both formal list entries', () => {
+    for (const entrySource of [taskListSource, orderListSource]) {
+      expect(entrySource).toContain('<InboundMeasurementDialog')
+      expect(entrySource).not.toContain('<InboundMeasurementPanel')
+      expect(entrySource).not.toContain('<WeightOcrPanel')
+    }
+  })
+
+  it('keeps draft saves open, closes only after submit, and refreshes parent entries consistently', () => {
+    expect(source).toContain('@saved="handleUpdated"')
+    expect(source).toContain('@updated="handleUpdated"')
+    expect(source).toContain('@submitted="handleSubmitted"')
+    expect(source).toContain("emit('updated')")
+    expect(source).toContain("emit('update:modelValue', false)")
+    expect(source).toContain("emit('submitted')")
+    expect(panelSource).toContain("emit('saved')")
+    expect(panelSource).toContain("emit('submitted')")
+  })
+
+  it('uses the existing permission-aware panels and protects unsaved work on close', () => {
+    expect(source).toContain('measurementPanelRef.value?.isDirty')
+    expect(source).toContain('当前测量数据尚未保存')
+    expect(source).toContain(':close-on-click-modal="false"')
+    expect(source).toContain(':before-close="beforeClose"')
+    expect(source).toContain('measurementPanelRef?.canEdit')
+    expect(source).toContain('measurementPanelRef?.canSubmit')
+  })
+})
diff --git a/src/modules/inbounds/measurement/InboundMeasurementDialog.vue b/src/modules/inbounds/measurement/InboundMeasurementDialog.vue
new file mode 100644
index 00000000..36f92ba6
--- /dev/null
+++ b/src/modules/inbounds/measurement/InboundMeasurementDialog.vue
@@ -0,0 +1,157 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import './measurementDensity.css'
+import { computed, ref } from 'vue'
+import { ElMessageBox } from 'element-plus'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import InboundMeasurementPanel from './InboundMeasurementPanel.vue'
+import WeightOcrPanel from '../weight/components/WeightOcrPanel.vue'
+
+const props = defineProps<{
+  modelValue: boolean
+  customerId: string
+  inboundId: string
+  inboundCode?: string | null
+  openWarehouseSuggestion?: boolean
+}>()
+
+const emit = defineEmits<{
+  'update:modelValue': [value: boolean]
+  updated: []
+  submitted: []
+  closed: []
+}>()
+
+const measurementPanelRef = ref<InstanceType<typeof InboundMeasurementPanel> | null>(null)
+const title = computed(() => `测量 · ${props.inboundCode?.trim() || '入仓码待补充'}`)
+
+async function mayClose() {
+  if (!measurementPanelRef.value?.isDirty) return true
+  try {
+    await ElMessageBox.confirm('当前测量数据尚未保存，关闭后将丢失修改。确定关闭吗？', '关闭测量', { customClass: 'admin-density-confirm',
+      type: 'warning',
+      confirmButtonText: '放弃修改并关闭',
+      cancelButtonText: '继续编辑',
+    })
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function requestClose() {
+  if (await mayClose()) emit('update:modelValue', false)
+}
+
+async function beforeClose(done: () => void) {
+  if (await mayClose()) done()
+}
+
+function handleWeightSummaryChanged(
+  actualGrossWeightKg: number | null,
+  actualNetWeightKg: number | null,
+  hasConfirmedWeight: boolean,
+) {
+  measurementPanelRef.value?.updateWeightEvidence(actualGrossWeightKg, actualNetWeightKg, hasConfirmedWeight)
+}
+
+function handleUpdated() {
+  emit('updated')
+}
+
+function handleSubmitted() {
+  emit('update:modelValue', false)
+  emit('submitted')
+}
+</script>
+
+<template>
+  <AppDialog
+    :model-value="modelValue"
+    class="inbound-measurement-workspace-dialog admin-density-dialog admin-density-workspace inbound-density"
+    :title="title"
+    width="min(1560px, calc(100vw - 48px))"
+    top="4vh"
+    fullscreenable
+    destroy-on-close
+    append-to-body
+    :close-on-click-modal="false"
+    :before-close="beforeClose"
+    @update:model-value="emit('update:modelValue', $event)"
+    @closed="emit('closed')"
+  >
+    <div class="measurement-dialog-workspace">
+      <section class="measurement-dialog-weight" aria-label="称重图片、OCR 与托盘核对">
+        <WeightOcrPanel
+          :customer-id="customerId"
+          :inbound-id="inboundId"
+          @changed="handleUpdated"
+          @summary-changed="handleWeightSummaryChanged"
+        />
+      </section>
+      <InboundMeasurementPanel
+        ref="measurementPanelRef"
+        :customer-id="customerId"
+        :inbound-id="inboundId"
+        :open-warehouse-suggestion="openWarehouseSuggestion"
+        @updated="handleUpdated"
+        @saved="handleUpdated"
+        @submitted="handleSubmitted"
+      />
+    </div>
+    <template #footer>
+      <div class="measurement-dialog-footer">
+        <span v-if="measurementPanelRef?.submissionBlockReason" class="measurement-dialog-footer__hint">
+          {{ measurementPanelRef.submissionBlockReason }}
+        </span>
+        <el-button :disabled="Boolean(measurementPanelRef?.saving || measurementPanelRef?.submitting)" @click="requestClose">取消</el-button>
+        <el-button
+          v-if="measurementPanelRef?.canEdit"
+          type="primary"
+          plain
+          :loading="measurementPanelRef?.saving"
+          :disabled="!measurementPanelRef?.mayMaintain"
+          @click="measurementPanelRef?.saveDraft()"
+        >保存测量数据</el-button>
+        <el-button
+          v-if="measurementPanelRef?.canSubmit"
+          type="primary"
+          :loading="measurementPanelRef?.submitting"
+          :disabled="!measurementPanelRef?.maySubmit"
+          @click="measurementPanelRef?.submitForReview()"
+        >提交审核</el-button>
+      </div>
+    </template>
+  </AppDialog>
+</template>
+
+<style scoped>
+.measurement-dialog-workspace { display: grid; min-width: 0; }
+.measurement-dialog-weight { min-width: 0; padding: 0 0 var(--admin-space-6, 16px); border-bottom: 1px solid var(--cc-border); }
+.measurement-dialog-footer { display: flex; flex-wrap: wrap; align-items: center; justify-content: flex-end; gap: var(--admin-space-4, 10px); }
+.measurement-dialog-footer__hint { margin-right: auto; color: var(--el-color-warning-dark-2); font-size: var(--admin-font-caption, 12px); }
+.measurement-dialog-footer :deep(.el-button) { margin-left: 0; }
+@media (max-width: 720px) {
+  .measurement-dialog-weight { padding-bottom: 14px; }
+  .measurement-dialog-footer { display: grid; grid-template-columns: 1fr; }
+  .measurement-dialog-footer :deep(.el-button) { width: 100%; min-height: 44px; }
+}
+</style>
+
+<style>
+.inbound-measurement-workspace-dialog.el-dialog { display: flex; max-width: calc(100vw - 32px); height: 92vh; max-height: 92vh; margin-bottom: 0; flex-direction: column; overflow: hidden; }
+.inbound-measurement-workspace-dialog .el-dialog__body { flex: 1 1 auto; }
+.inbound-measurement-workspace-dialog .measurement-panel { border: 0; border-radius: 0; box-shadow: none; }
+.inbound-measurement-workspace-dialog .measurement-panel__heading .measurement-panel__actions,
+.inbound-measurement-workspace-dialog .measurement-panel__footer { display: none; }
+@media (max-width: 720px) {
+  .inbound-measurement-workspace-dialog.el-dialog { width: calc(100vw - 20px) !important; max-width: calc(100vw - 20px); }
+  .inbound-measurement-workspace-dialog .el-dialog__header { padding: 16px; }
+  .inbound-measurement-workspace-dialog .el-dialog__body { padding: 14px; }
+}
+@media (max-width: 360px) {
+  .inbound-measurement-workspace-dialog.el-dialog { width: calc(100vw - 12px) !important; max-width: calc(100vw - 12px); }
+  .inbound-measurement-workspace-dialog .el-dialog__header { padding: 14px 12px; }
+  .inbound-measurement-workspace-dialog .el-dialog__body { padding: 10px; }
+}
+</style>
diff --git a/src/modules/inbounds/measurement/InboundMeasurementPanel.test.ts b/src/modules/inbounds/measurement/InboundMeasurementPanel.test.ts
new file mode 100644
index 00000000..dc624456
--- /dev/null
+++ b/src/modules/inbounds/measurement/InboundMeasurementPanel.test.ts
@@ -0,0 +1,593 @@
+import ElementPlus, { ElMessage, ElMessageBox } from 'element-plus'
+import { createPinia, setActivePinia } from 'pinia'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { ApiResponseError } from '@/shared/api/http'
+import { useAuthStore } from '@/core/auth/auth'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import {
+  downloadInboundMeasurementImage,
+  createManualCartonScan,
+  getInboundMeasurement,
+  saveInboundMeasurementDraft,
+  submitInboundMeasurement,
+  updateConfirmedPackageCount,
+} from './api'
+import type { InboundMeasurementDetail } from './types'
+import InboundMeasurementPanel from './InboundMeasurementPanel.vue'
+
+vi.mock('./api', () => ({
+  createManualCartonScan: vi.fn(),
+  downloadInboundMeasurementImage: vi.fn(),
+  getInboundMeasurement: vi.fn(),
+  saveInboundMeasurementDraft: vi.fn(),
+  submitInboundMeasurement: vi.fn(),
+  updateConfirmedPackageCount: vi.fn(),
+}))
+
+class ResizeObserverStub implements ResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+
+function createMemoryStorage(): Storage {
+  const values = new Map<string, string>()
+  return {
+    get length() { return values.size },
+    clear: () => values.clear(),
+    getItem: (key) => values.get(key) ?? null,
+    key: (index) => [...values.keys()][index] ?? null,
+    removeItem: (key) => values.delete(key),
+    setItem: (key, value) => values.set(key, value),
+  }
+}
+
+function measurement(overrides: Partial<InboundMeasurementDetail> = {}): InboundMeasurementDetail {
+  return {
+    inboundId: '7001',
+    inboundCode: 'RK202608040001',
+    companyName: '测试企业',
+    channelCode: 'SEA-FBA',
+    channelName: '美西海运',
+    processStatus: 'MEASURING',
+    measureReviewStatus: null,
+    recommendedPalletType: 'STANDARD',
+    reviewReason: null,
+    reviewerId: null,
+    reviewerName: null,
+    measurementId: '9001',
+    sourceType: 'THIRD_PARTY',
+    measurementStatus: 'RECEIVED',
+    version: 2,
+    originalDocumentNo: 'DOC-001',
+    originalGrossWeightKg: 118.5,
+    originalVolumeCbm: 0.8,
+    originalPackageCount: 10,
+    actualPackageCount: 10,
+    actualGrossWeightKg: 120,
+    actualNetWeightKg: 110,
+    actualVolumeCbm: 0.6,
+    volumeWeightKg: 100.2,
+    actualGoodsName: '蓝牙音箱',
+    latestDeclaration: {
+      referenceId: 'DOC-001',
+      totalPackageCount: 10,
+      grossWeightKg: 118.5,
+      volumeCbm: 0.8,
+      goodsName: '蓝牙音箱',
+      items: [{
+        inboundDetailId: '8101',
+        itemNo: 1,
+        cargoName: '蓝牙音箱',
+        packageCount: 10,
+        lengthCm: 50,
+        widthCm: 40,
+        heightCm: 30,
+      }],
+    },
+    items: [{
+      id: '9101',
+      inboundDetailId: '8101',
+      inboundCode: 'RK202608040001',
+      fbaShipmentNo: 'FBA18ABC1234',
+      scannedShipmentId: 'FBA18SCAN5678',
+      boxCode: 'RK202608040001#10-1',
+      itemNo: '001',
+      boxSpecification: '50×40×30cm',
+      packageCount: 10,
+      lengthCm: 50,
+      widthCm: 40,
+      heightCm: 30,
+      girthCm: 190,
+      unitWeightKg: 12,
+      unitVolumeCbm: 0.06,
+      totalWeightKg: 120,
+      totalVolumeCbm: 0.6,
+      volumeWeightKg: 100.2,
+      intelligentImageFileId: '88001',
+      machineNo: 'MJ20210327',
+      deviceMeasuredAt: '2026-08-04T10:30:00+08:00',
+      overLimitWarning: null,
+      outerLengthCm: null,
+      outerWidthCm: null,
+      outerHeightCm: null,
+      calculatedOuterLengthCm: 50,
+      calculatedOuterWidthCm: 40,
+      calculatedOuterHeightCm: 30,
+      calculationRuleVersion: 'DIMENSION_ACTUAL_V1',
+      remark: '设备自动回传',
+    }],
+    weightResults: [{
+      id: '30001', fileId: '40001', palletId: '50001', palletCode: 'TP-001', palletType: '木托盘',
+      palletCapacityCbm: 1.2, palletTareWeightKg: 10, ocrProvider: 'FILE_WEIGHT_OCR', ocrRawText: '120',
+      ocrWeightValue: 120, ocrWeightUnit: 'KG', confidence: 0.98, adjustedWeightValue: null,
+      adjustedWeightUnit: null, grossWeightKg: 120, netWeightKg: 110, recognitionStatus: 'CONFIRMED',
+      adjustmentReason: null, adjustedBy: null, adjustedAt: null, confirmedBy: '9',
+      confirmedAt: '2026-08-04T10:35:00+08:00', version: 1,
+    }],
+    ...overrides,
+  }
+}
+
+async function mountPanel(permissions = [
+  'platform:firstleg:inbound:measure:view',
+  'platform:firstleg:inbound:measure:edit',
+  'platform:firstleg:inbound:measure:manual-entry',
+  'platform:firstleg:inbound:measure:submit',
+]) {
+  const pinia = createPinia()
+  setActivePinia(pinia)
+  const auth = useAuthStore()
+  auth.token = 'token'
+  auth.permissions = permissions
+  useAccessPreviewStore().initializeAfterLogin()
+  const wrapper = mount(InboundMeasurementPanel, {
+    props: { customerId: '10001', inboundId: '7001' },
+    attachTo: document.body,
+    global: { plugins: [pinia, ElementPlus] },
+  })
+  await flushPromises()
+  return wrapper
+}
+
+enableAutoUnmount(afterEach)
+afterAll(() => vi.unstubAllGlobals())
+
+describe('InboundMeasurementPanel', () => {
+  beforeEach(() => {
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+    vi.stubGlobal('localStorage', createMemoryStorage())
+    vi.stubGlobal('sessionStorage', createMemoryStorage())
+    document.body.innerHTML = ''
+    vi.mocked(getInboundMeasurement).mockReset().mockResolvedValue(measurement())
+    vi.mocked(updateConfirmedPackageCount).mockReset().mockResolvedValue({
+      measurementId: '9001', measurementVersion: 3, itemId: '9101',
+      boxCode: 'RK202608040001#10-1', confirmedPackageCount: 10,
+    })
+    vi.mocked(saveInboundMeasurementDraft).mockReset().mockResolvedValue({ measurementId: '9001', version: 3, status: 'DRAFT' })
+    vi.mocked(submitInboundMeasurement).mockReset().mockResolvedValue({
+      measurementId: '9001', version: 2, processStatus: 'MEASURE_PENDING', measureReviewStatus: 'PENDING',
+      recommendedPalletType: 'STANDARD', feeId: null, feeNo: null, feeStatus: null,
+    })
+    vi.mocked(createManualCartonScan).mockReset().mockResolvedValue({
+      measurementId: '9001', measurementVersion: 3, itemId: '9102', boxCode: 'RK202608040001#10-2',
+      confirmedPackageCount: 1,
+    })
+    vi.spyOn(ElMessageBox, 'confirm').mockResolvedValue(undefined as never)
+  })
+
+  it('loads third-party facts and renders server-calculated values separately', async () => {
+    const wrapper = await mountPanel()
+
+    expect(getInboundMeasurement).toHaveBeenCalledWith('10001', '7001')
+    expect(wrapper.text()).toContain('RK202608040001')
+    expect(wrapper.find('.measurement-table').text()).toContain('FBA18ABC1234')
+    expect(wrapper.find('.measurement-table').text()).toContain('FBA18SCAN5678')
+    expect(wrapper.find('.measurement-table').text()).toContain('0.6')
+    expect(wrapper.find('.measurement-table').text()).not.toContain('周长')
+    await wrapper.find('.el-table__expand-icon').trigger('click')
+    await flushPromises()
+    expect(wrapper.text()).toContain('箱规周长')
+    expect(wrapper.text()).toContain('190 cm')
+    expect(wrapper.text()).toContain('MJ20210327')
+    expect(wrapper.text()).toContain('2026-08-04 10:30:00+08:00')
+    expect(wrapper.find('button[aria-label="预览测量图片"]').exists()).toBe(true)
+  })
+
+  it('warns when declared dimensions or gross weight differ from measurements by at least ten percent', async () => {
+    vi.mocked(getInboundMeasurement).mockResolvedValueOnce(measurement({
+      actualGrossWeightKg: 132,
+      items: [{
+        ...measurement().items[0],
+        lengthCm: 55,
+        widthCm: 36,
+      }],
+    }))
+    const wrapper = await mountPanel()
+    const alert = wrapper.find('.measurement-deviation-alert')
+
+    expect(alert.exists()).toBe(true)
+    expect(alert.text()).toContain('下单箱规与测量数据差异达到 10%')
+    expect(alert.text()).toContain('长偏差 10%')
+    expect(alert.text()).toContain('下单 50 cm → 实测 55 cm')
+    expect(alert.text()).toContain('宽偏差 10%')
+    expect(alert.text()).toContain('重量偏差 11.4%')
+    expect(alert.text()).not.toContain('高偏差')
+  })
+
+  it('does not warn when every declared and measured value differs by less than ten percent', async () => {
+    const wrapper = await mountPanel()
+
+    expect(wrapper.find('.measurement-deviation-alert').exists()).toBe(false)
+  })
+
+  it('opens the manual carton entry form in an editable measurement state', async () => {
+    const wrapper = await mountPanel()
+    const button = wrapper.findAll('button').find((candidate) => candidate.text().includes('手动录入箱规'))
+    expect(button?.attributes('disabled')).toBeUndefined()
+    await button?.trigger('click')
+    expect(wrapper.text()).toContain('手动录入箱规')
+
+    expect(document.body.textContent).toContain('箱号')
+    expect(document.body.textContent).toContain('测量长（cm）')
+    expect(document.body.textContent).toContain('测量图片')
+    expect(document.body.textContent).toContain('保存箱规')
+  })
+
+  it('does not expose manual carton entry without its dedicated permission', async () => {
+    const wrapper = await mountPanel([
+      'platform:firstleg:inbound:measure:view',
+      'platform:firstleg:inbound:measure:edit',
+      'platform:firstleg:inbound:measure:submit',
+    ])
+
+    expect(wrapper.text()).not.toContain('手动录入箱规')
+  })
+
+  it('does not expose unknown measurement source codes', async () => {
+    vi.mocked(getInboundMeasurement).mockResolvedValueOnce(measurement({ sourceType: 'LEGACY_DEVICE' }))
+
+    const wrapper = await mountPanel()
+
+    expect(wrapper.text()).toContain('未知来源')
+    expect(wrapper.text()).not.toContain('LEGACY_DEVICE')
+  })
+
+  it('keeps key totals compact and shows declaration information without another disclosure card', async () => {
+    const wrapper = await mountPanel()
+    const text = wrapper.text()
+
+    expect(text).toContain('实测箱数')
+    expect(text).toContain('货物净重')
+    expect(text).toContain('总体积')
+    expect(text).toContain('材积重')
+    expect(text).toContain('客户申报')
+    expect(text).toContain('平台实测')
+    expect(text).toContain('差异 +1.5 kg')
+    expect(text).toContain('差异 -0.2 m³')
+    expect(text).toContain('箱规明细')
+    expect(text).not.toContain('租户')
+    expect(text).not.toContain('数据版本')
+
+    expect(wrapper.find('.measurement-table').exists()).toBe(true)
+    expect(wrapper.find('.measurement-item').exists()).toBe(false)
+    expect(wrapper.find('.measurement-table').text()).not.toContain('周长')
+    expect(wrapper.text()).not.toContain('每箱毛重')
+    expect(wrapper.text()).not.toContain('总重量(kg)')
+    const source = await import('./InboundMeasurementPanel.vue?raw').then((module) => module.default)
+    expect(source).toContain('<section class="measurement-declaration"')
+    expect(source).not.toContain('<el-collapse-item name="declaration"')
+    expect(source).toContain('grid-template-columns: repeat(4, minmax(0, 1fr))')
+    expect(source).toContain('.measurement-data-grid { display: grid; grid-template-columns: repeat(5, minmax(0, 1fr));')
+    expect(source).toContain('.measurement-table { width: 100%; font-size: var(--admin-font-caption, 12px); }')
+    expect(source).toContain('.measurement-data-grid :deep(.el-input__wrapper)')
+    expect(source).toContain('defineExpose({ saveDraft, submitForReview, updateWeightEvidence, submissionBlockReason, mayMaintain, maySubmit, saving, submitting, canEdit, canSubmit, isDirty })')
+  })
+
+  it('renders customer declaration facts as plain read-only values', async () => {
+    const wrapper = await mountPanel()
+    const declaration = wrapper.find('.measurement-declaration')
+
+    expect(declaration.text()).toContain('申报箱数')
+    expect(declaration.text()).toContain('10')
+    expect(declaration.text()).toContain('申报毛重（kg）')
+    expect(declaration.text()).toContain('118.5')
+    expect(declaration.text()).toContain('申报体积（m³）')
+    expect(declaration.text()).toContain('0.8')
+    expect(declaration.text()).toContain('原单据号码')
+    expect(declaration.text()).toContain('DOC-001')
+    expect(declaration.findAll('.measurement-readonly-field')).toHaveLength(4)
+    expect(declaration.findAll('input')).toHaveLength(1)
+    expect(declaration.find('.measurement-goods-name input').exists()).toBe(true)
+    expect(declaration.find('[aria-label="客户申报箱规明细"]').text()).toContain('蓝牙音箱')
+    expect(declaration.find('[aria-label="客户申报箱规明细"]').text()).toContain('50 × 40 × 30')
+  })
+
+  it('does not render differences when the corresponding declaration is unavailable', async () => {
+    vi.mocked(getInboundMeasurement).mockResolvedValueOnce(measurement({ originalGrossWeightKg: null, originalVolumeCbm: null }))
+    const wrapper = await mountPanel()
+    expect(wrapper.find('.measurement-metrics').text()).not.toContain('差异')
+  })
+
+  it('shows all declaration fields as plain text when measurement is not editable', async () => {
+    vi.mocked(getInboundMeasurement).mockResolvedValueOnce(measurement({ processStatus: 'WAIT_SPLIT' }))
+    const wrapper = await mountPanel()
+    const declaration = wrapper.find('.measurement-declaration')
+
+    expect(declaration.find('input').exists()).toBe(false)
+    expect(declaration.text()).toContain('蓝牙音箱')
+    expect(declaration.findAll('.measurement-readonly-field')).toHaveLength(5)
+  })
+
+  it('saves the corrected actual goods name without overriding declaration facts', async () => {
+    const wrapper = await mountPanel()
+    await wrapper.find('.measurement-goods-name input').setValue('修正后的蓝牙音箱')
+    const save = wrapper.findAll('button').find((button) => button.text().includes('保存测量数据'))
+    await save?.trigger('click')
+    await flushPromises()
+
+    expect(saveInboundMeasurementDraft).toHaveBeenCalledWith('10001', '7001', expect.objectContaining({
+      measurementId: '9001',
+      version: 2,
+      actualGoodsName: '修正后的蓝牙音箱',
+      items: expect.any(Array),
+    }))
+    const payload = vi.mocked(saveInboundMeasurementDraft).mock.calls[0]?.[2]
+    expect(payload).not.toHaveProperty('originalDocumentNo')
+    expect(payload).not.toHaveProperty('originalGrossWeightKg')
+    expect(payload).not.toHaveProperty('originalVolumeCbm')
+  })
+
+  it('allows saving one warehouse outer dimension against the measured sequence', async () => {
+    const wrapper = await mountPanel()
+    expect(wrapper.text()).toContain('001')
+    await wrapper.find('input[aria-label="仓库修改外箱长"]').setValue('55')
+    const save = wrapper.findAll('button').find((button) => button.text().includes('保存测量数据'))
+    await save?.trigger('click')
+    await flushPromises()
+
+    const payload = vi.mocked(saveInboundMeasurementDraft).mock.calls[0]?.[2]
+    expect(payload?.items[0]).toMatchObject({
+      itemNo: '001', outerLengthCm: 55, outerWidthCm: null, outerHeightCm: null,
+    })
+  })
+
+  it('updates the server weight summary without discarding unsaved measurement edits', async () => {
+    const wrapper = await mountPanel()
+    const countInput = wrapper.find('.measurement-count-editor input')
+    await countInput.setValue('9')
+
+    wrapper.vm.updateWeightEvidence(125.75, 115.75, true)
+    await flushPromises()
+
+    expect(wrapper.find('.measurement-metrics').text()).toContain('125.75')
+    expect(wrapper.find('.measurement-metrics').text()).toContain('115.75')
+    expect((countInput.element as HTMLInputElement).value).toBe('9')
+  })
+
+  it('shows the complete server-calculated measurement facts in the expanded row', async () => {
+    const wrapper = await mountPanel()
+    await wrapper.get('.el-table__expand-icon').trigger('click')
+    await flushPromises()
+
+    const text = wrapper.text()
+    expect(text).toContain('箱规')
+    expect(text).toContain('50×40×30cm')
+    expect(text).toContain('计算方式')
+    expect(text).toContain('实测原尺寸')
+    expect(text).toContain('计算后外箱')
+    expect(text).toContain('50 × 40 × 30 cm')
+    expect(text).toContain('计算规则版本')
+    expect(text).toContain('DIMENSION_ACTUAL_V1')
+  })
+
+  it('reuses the established first-leg detail surface and status patterns', async () => {
+    const wrapper = await mountPanel()
+
+    expect(wrapper.classes()).toContain('surface-panel')
+    expect(wrapper.find('.measurement-summary-header').exists()).toBe(true)
+    expect(wrapper.find('.measurement-summary-status').text()).toContain('测量中')
+    expect(wrapper.find('.measurement-summary-header').text()).not.toContain('RK202608040001')
+    expect(wrapper.find('.measurement-summary-header').text()).toContain('测试企业')
+    expect(wrapper.find('.measurement-summary-header').text()).toContain('美西海运')
+  })
+
+  it('saves only the changed confirmed package count with the current measurement version', async () => {
+    vi.mocked(updateConfirmedPackageCount).mockResolvedValueOnce({
+      measurementId: '9001', measurementVersion: 3, itemId: '9101',
+      boxCode: 'RK202608040001#10-1', confirmedPackageCount: 9,
+    })
+    const wrapper = await mountPanel()
+    const countInput = wrapper.find('.measurement-count-editor input')
+    await countInput?.setValue('9')
+    const save = wrapper.findAll('button').find((button) => button.text().includes('保存测量数据'))
+    await save?.trigger('click')
+    await flushPromises()
+
+    expect(updateConfirmedPackageCount).toHaveBeenCalledWith('10001', '7001', '9101', {
+      measurementVersion: 2,
+      confirmedPackageCount: 9,
+    })
+  })
+
+  it('does not submit a second count update when the full draft already saved the changed count', async () => {
+    const wrapper = await mountPanel()
+    await wrapper.find('.measurement-count-editor input').setValue('9')
+    await wrapper.find('input[aria-label="仓库修改外箱长"]').setValue('55')
+    const save = wrapper.findAll('button').find((button) => button.text().includes('保存测量数据'))
+    await save?.trigger('click')
+    await flushPromises()
+
+    expect(saveInboundMeasurementDraft).toHaveBeenCalledWith('10001', '7001', expect.objectContaining({
+      version: 2,
+      items: [expect.objectContaining({ packageCount: 9, outerLengthCm: 55 })],
+    }))
+    expect(updateConfirmedPackageCount).not.toHaveBeenCalled()
+  })
+
+  it('preserves the edited form when the backend reports a version conflict', async () => {
+    vi.mocked(updateConfirmedPackageCount).mockRejectedValueOnce(
+      new ApiResponseError('测量数据已被其他人修改，请刷新后重试', 'A0409', 200, null, 'req-conflict', 'trace-conflict'),
+    )
+    const wrapper = await mountPanel()
+    const countInput = wrapper.find('.measurement-count-editor input')
+    await countInput?.setValue('9')
+    const save = wrapper.findAll('button').find((button) => button.text().includes('保存测量数据'))
+    await save?.trigger('click')
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('数据版本已变化，当前修改尚未丢失')
+    expect(wrapper.text()).toContain('req-conflict')
+    expect((countInput?.element as HTMLInputElement).value).toBe('9')
+    expect(getInboundMeasurement).toHaveBeenCalledTimes(1)
+  })
+
+  it('shows a normal A0409 business reason instead of relabeling it as a version conflict', async () => {
+    const messageSpy = vi.spyOn(ElMessage, 'error')
+    vi.mocked(updateConfirmedPackageCount).mockRejectedValueOnce(
+      new ApiResponseError('该托盘已被占用，请重新选择', 'A0409', 409),
+    )
+    const wrapper = await mountPanel()
+    const countInput = wrapper.find('.measurement-count-editor input')
+    await countInput.setValue('9')
+    const save = wrapper.findAll('button').find((button) => button.text().includes('保存测量数据'))
+    await save?.trigger('click')
+    await flushPromises()
+
+    expect(messageSpy).toHaveBeenCalledWith(expect.objectContaining({
+      message: '该托盘已被占用，请重新选择',
+      showClose: true,
+      duration: 4500,
+    }))
+    expect(wrapper.text()).not.toContain('操作未完成')
+    expect(wrapper.text()).not.toContain('数据版本已变化，当前修改尚未丢失')
+  })
+
+  it('reports draft validation as a dismissible light message without a fixed page alert', async () => {
+    const messageSpy = vi.spyOn(ElMessage, 'warning')
+    vi.mocked(getInboundMeasurement).mockResolvedValueOnce(measurement({ items: [] }))
+    const wrapper = await mountPanel()
+    const save = wrapper.findAll('button').find((button) => button.text().includes('保存测量数据'))
+    await save?.trigger('click')
+    await flushPromises()
+
+    expect(messageSpy).toHaveBeenCalledWith(expect.objectContaining({
+      message: '请至少保留一条实际扫描箱测量记录',
+      showClose: true,
+      duration: 4500,
+    }))
+    expect(wrapper.text()).not.toContain('请修正测量草稿中的问题')
+  })
+
+  it('requires the dirty draft to be saved before submitting for review', async () => {
+    const wrapper = await mountPanel()
+    const countInput = wrapper.find('.measurement-count-editor input')
+    await countInput?.setValue('9')
+    const submit = wrapper.findAll('button').find((button) => button.text().includes('提交审核'))
+    await submit?.trigger('click')
+    await flushPromises()
+
+    expect(submitInboundMeasurement).not.toHaveBeenCalled()
+    expect(ElMessageBox.confirm).not.toHaveBeenCalled()
+  })
+
+  it('submits the saved version and emits changed after confirmation', async () => {
+    const wrapper = await mountPanel()
+    const submit = wrapper.findAll('button').find((button) => button.text().includes('提交审核'))
+    await submit?.trigger('click')
+    await flushPromises()
+
+    expect(ElMessageBox.confirm).toHaveBeenCalledWith(
+      expect.stringContaining('准备托盘与库位占用'),
+      '提交测量审核',
+      expect.objectContaining({ confirmButtonText: '确认提交' }),
+    )
+    expect(submitInboundMeasurement).toHaveBeenCalledWith('10001', '7001', { measurementId: '9001', version: 2 })
+    expect(wrapper.emitted('changed')).toHaveLength(1)
+  })
+
+  it('requires at least one confirmed weight image before submitting for review', async () => {
+    const messageSpy = vi.spyOn(ElMessage, 'warning')
+    vi.mocked(getInboundMeasurement).mockResolvedValueOnce(measurement({ weightResults: [] }))
+    const wrapper = await mountPanel()
+
+    expect(wrapper.text()).toContain('即使只有一箱，也必须上传并确认至少一张称重图片后才能提交审核')
+    const submit = wrapper.findAll('button').find((button) => button.text().includes('提交审核'))
+    expect(submit?.attributes('disabled')).toBeDefined()
+    await wrapper.vm.submitForReview()
+    expect(messageSpy).toHaveBeenCalledWith('即使只有一箱，也必须上传并确认至少一张称重图片后才能提交审核')
+    expect(submitInboundMeasurement).not.toHaveBeenCalled()
+  })
+
+  it('updates submission eligibility when the weight panel confirms or removes the last image', async () => {
+    const wrapper = await mountPanel()
+    expect(wrapper.vm.maySubmit).toBe(true)
+
+    wrapper.vm.updateWeightEvidence(null, null, false)
+    await flushPromises()
+    expect(wrapper.vm.maySubmit).toBe(false)
+    expect(wrapper.vm.submissionBlockReason).toContain('必须上传并确认')
+
+    wrapper.vm.updateWeightEvidence(125.75, 115.75, true)
+    await flushPromises()
+    expect(wrapper.vm.maySubmit).toBe(true)
+  })
+
+  it('emits updated without closing the parent task after manual carton entry', async () => {
+    const wrapper = await mountPanel()
+    const source = await import('./InboundMeasurementPanel.vue?raw').then((module) => module.default)
+    expect(source).toContain("emit('updated')")
+    expect(wrapper.emitted('updated')).toBeUndefined()
+  })
+
+  it('maps the formal deviceMeasuredAt response field into the read-only measurement time', async () => {
+    const wrapper = await mountPanel()
+    await wrapper.get('.el-table__expand-icon').trigger('click')
+
+    expect(wrapper.text()).toContain('2026-08-04 10:30:00+08:00')
+    const source = await import('./InboundMeasurementPanel.vue?raw').then((module) => module.default)
+    expect(source).toContain('measuredAt: item.deviceMeasuredAt')
+    expect(source).not.toContain('measuredAt: item.measuredAt')
+  })
+
+  it('blocks normal submission when confirmed box counts do not match the order total', async () => {
+    vi.mocked(getInboundMeasurement).mockResolvedValueOnce(measurement({ originalPackageCount: 12 }))
+    const wrapper = await mountPanel()
+
+    expect(wrapper.text()).not.toContain('确认箱数尚未与订单总箱数匹配')
+    const submit = wrapper.findAll('button').find((button) => button.text().includes('提交审核'))
+    expect(submit?.attributes('disabled')).toBeDefined()
+    expect(submitInboundMeasurement).not.toHaveBeenCalled()
+  })
+
+  it('keeps device facts read-only but allows manual count correction after submission', async () => {
+    vi.mocked(getInboundMeasurement).mockResolvedValueOnce(measurement({ processStatus: 'MEASURE_PENDING' }))
+    const wrapper = await mountPanel()
+    const countInput = wrapper.find('.measurement-count-editor input')
+
+    expect((countInput?.element as HTMLInputElement).matches(':disabled')).toBe(false)
+    expect(wrapper.findAll('button').find((button) => button.text().includes('保存测量数据'))?.attributes('disabled')).toBeUndefined()
+    expect(wrapper.findAll('button').find((button) => button.text().includes('提交审核'))?.attributes('disabled')).toBeDefined()
+    expect(vi.mocked(downloadInboundMeasurementImage)).not.toHaveBeenCalled()
+  })
+
+  it('clears the previous customer context before loading the next one', async () => {
+    const wrapper = await mountPanel()
+    vi.mocked(getInboundMeasurement).mockResolvedValueOnce(measurement({ inboundId: '7002', inboundCode: 'RK202608040002', companyName: '第二企业' }))
+
+    await wrapper.setProps({ customerId: '10002', inboundId: '7002' })
+    await flushPromises()
+
+    expect(getInboundMeasurement).toHaveBeenLastCalledWith('10002', '7002')
+    expect(wrapper.find('.measurement-summary-header').text()).toContain('第二企业')
+    expect(wrapper.find('.measurement-summary-header').text()).not.toContain('测试企业')
+  })
+
+  it('renders a permission-specific read-only state without requesting data', async () => {
+    const wrapper = await mountPanel([])
+
+    expect(wrapper.text()).toContain('无测量查看权限')
+    expect(getInboundMeasurement).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/modules/inbounds/measurement/InboundMeasurementPanel.vue b/src/modules/inbounds/measurement/InboundMeasurementPanel.vue
new file mode 100644
index 00000000..3b02e553
--- /dev/null
+++ b/src/modules/inbounds/measurement/InboundMeasurementPanel.vue
@@ -0,0 +1,1000 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onBeforeUnmount, reactive, ref, watch } from 'vue'
+import { ElMessage, ElMessageBox, type UploadFile } from 'element-plus'
+import { AlertTriangle, Image, Plus, Save, Send, Upload } from '@lucide/vue'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useUnsavedWorkRegistration } from '@/core/unsaved-work/useUnsavedWorkRegistration'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { inboundProcessStatusLabels, inboundStatusLabel } from '../status'
+import { createManualCartonScan, downloadInboundMeasurementImage, getInboundMeasurement, saveInboundMeasurementDraft, submitInboundMeasurement, updateConfirmedPackageCount } from './api'
+import type {
+  InboundMeasurementDetail,
+  InboundMeasurementItem,
+  SaveInboundMeasurementItemRequest,
+} from './types'
+
+const props = defineProps<{
+  customerId?: string
+  tenantId?: string
+  inboundId: string
+}>()
+
+const emit = defineEmits<{
+  changed: []
+  updated: []
+  saved: []
+  submitted: []
+}>()
+
+type EditableMeasurementItem = Omit<SaveInboundMeasurementItemRequest, 'coefficientMode'> & {
+  itemId: string
+  clientKey: string
+  inboundCode: string
+  fbaShipmentNo: string | null
+  scannedShipmentId: string | null
+  serverValues: Pick<InboundMeasurementItem, 'girthCm' | 'unitVolumeCbm' | 'totalWeightKg' | 'totalVolumeCbm' | 'volumeWeightKg'>
+  chargeRuleId: string | null
+  coefficientMode: 'ACTUAL' | 'ADD' | 'MULTIPLY'
+  calculatedOuterLengthCm: number | null
+  calculatedOuterWidthCm: number | null
+  calculatedOuterHeightCm: number | null
+  calculationRuleVersion: string | null
+}
+
+interface MeasurementFormModel {
+  measurementId: string | null
+  version: number
+  actualGoodsName: string
+  expectedPalletCount: number | null
+  items: EditableMeasurementItem[]
+}
+
+interface ManualCartonFormModel {
+  boxCode: string
+  length: number | null
+  width: number | null
+  height: number | null
+  weight: number | null
+  scannedShipmentId: string
+  machineNo: string
+  measuredAt: string
+}
+
+const access = useAccessPreviewStore()
+const loading = ref(false)
+const saving = ref(false)
+const submitting = ref(false)
+const manualEntryOpen = ref(false)
+const manualEntrySubmitting = ref(false)
+const manualEntryImage = ref<File | null>(null)
+const manualEntryErrors = ref<string[]>([])
+const detail = ref<InboundMeasurementDetail | null>(null)
+const loadError = ref<ApiErrorDetails | null>(null)
+const operationError = ref<ApiErrorDetails | null>(null)
+const conflictDetected = ref(false)
+const imagePreviewOpen = ref(false)
+const imagePreviewLoading = ref(false)
+const imagePreviewUrl = ref('')
+const imagePreviewError = ref<ApiErrorDetails | null>(null)
+const validationErrors = ref<Record<string, string[]>>({})
+const baseline = ref('')
+const confirmedWeightAvailable = ref(false)
+let requestSequence = 0
+let itemSequence = 0
+
+const form = reactive<MeasurementFormModel>({
+  measurementId: null,
+  version: 0,
+  actualGoodsName: '',
+  expectedPalletCount: null,
+  items: [],
+})
+
+const manualForm = reactive<ManualCartonFormModel>({
+  boxCode: '',
+  length: null,
+  width: null,
+  height: null,
+  weight: null,
+  scannedShipmentId: '',
+  machineNo: 'MANUAL-ADMIN',
+  measuredAt: '',
+})
+
+const canView = computed(() => access.can('platform:firstleg:inbound:measure:view'))
+const canEdit = computed(() => access.can('platform:firstleg:inbound:measure:edit'))
+const canManualEntry = computed(() => access.can('platform:firstleg:inbound:measure:manual-entry'))
+const canSubmit = computed(() => access.can('platform:firstleg:inbound:measure:submit'))
+const customerId = computed(() => props.customerId || props.tenantId || '')
+const hasContext = computed(() => Boolean(customerId.value && props.inboundId))
+const countEditableProcess = computed(() => ['PREPARING', 'WAIT_MEASURE', 'MEASURING', 'MEASURE_PENDING', 'MEASURE_REJECTED'].includes(detail.value?.processStatus || ''))
+const submitEditableProcess = computed(() => ['PREPARING', 'WAIT_MEASURE', 'MEASURING', 'MEASURE_REJECTED'].includes(detail.value?.processStatus || ''))
+const mayMaintain = computed(() => canEdit.value && countEditableProcess.value && !loading.value && !submitting.value)
+const manualEntryEditableProcess = computed(() => ['PREPARING', 'WAIT_MEASURE', 'MEASURING', 'MEASURE_REJECTED'].includes(detail.value?.processStatus || ''))
+const mayCreateManualEntry = computed(() => canManualEntry.value && manualEntryEditableProcess.value && !loading.value && !saving.value && !submitting.value && !isDirty.value)
+const confirmedPackageCount = computed(() => form.items.reduce((sum, item) => sum + (Number.isFinite(item.packageCount) ? item.packageCount : 0), 0))
+const expectedPackageCount = computed(() => detail.value?.originalPackageCount ?? null)
+const packageCountDifference = computed(() => expectedPackageCount.value == null ? null : confirmedPackageCount.value - expectedPackageCount.value)
+const packageCountMatched = computed(() => packageCountDifference.value === null || packageCountDifference.value === 0)
+const hasConfirmedWeightResult = computed(() => confirmedWeightAvailable.value)
+const isDropship = computed(() => detail.value?.fulfillmentType === 'ONE_CLICK_DROPSHIP')
+const expectedPalletCountValid = computed(() => !isDropship.value || (Number.isInteger(form.expectedPalletCount) && Number(form.expectedPalletCount) >= 1))
+const maySubmit = computed(() => canSubmit.value && submitEditableProcess.value && Boolean(form.measurementId) && packageCountMatched.value && hasConfirmedWeightResult.value && expectedPalletCountValid.value && !loading.value && !saving.value)
+const submissionBlockReason = computed(() => {
+  if (!canSubmit.value || !submitEditableProcess.value || !form.measurementId) return ''
+  if (!hasConfirmedWeightResult.value) return '即使只有一箱，也必须上传并确认至少一张称重图片后才能提交审核'
+  if (!packageCountMatched.value) return '确认箱数合计必须与订单总箱数一致后才能提交审核'
+  if (!expectedPalletCountValid.value) return '请先填写并保存有效的预计托数后再提交审核'
+  if (isDirty.value) return '请先保存当前修改，再提交审核'
+  return ''
+})
+const snapshot = computed(() => JSON.stringify(form))
+const isDirty = computed(() => Boolean(detail.value) && snapshot.value !== baseline.value)
+const registrationOpen = computed(() => hasContext.value && canView.value && Boolean(detail.value))
+const requiredPermission = computed(() => canEdit.value ? 'platform:firstleg:inbound:measure:edit' : null)
+const sourceLabel = computed(() => ({ THIRD_PARTY: '第三方设备', MANUAL: '平台人工', OPENAPI: '第三方设备' }[detail.value?.sourceType || ''] || (detail.value?.sourceType ? '未知来源' : '尚未测量')))
+
+interface MeasurementDeviationWarning {
+  key: string
+  text: string
+}
+
+const measurementDeviationWarnings = computed<MeasurementDeviationWarning[]>(() => {
+  const resource = detail.value
+  if (!resource) return []
+
+  const warnings: MeasurementDeviationWarning[] = []
+  const declaredItems = resource.latestDeclaration?.items || []
+  const dimensions = [
+    { key: 'lengthCm', label: '长' },
+    { key: 'widthCm', label: '宽' },
+    { key: 'heightCm', label: '高' },
+  ] as const
+
+  for (const dimension of dimensions) {
+    const differences = resource.items.flatMap((measuredItem) => {
+      const declaredItem = declaredItems.find((candidate) => (
+        measuredItem.inboundDetailId != null
+          && candidate.inboundDetailId != null
+          && String(candidate.inboundDetailId) === String(measuredItem.inboundDetailId)
+      )) || declaredItems.find((candidate) => candidate.itemNo != null && Number(candidate.itemNo) === Number(measuredItem.itemNo))
+      if (!declaredItem) return []
+      const declaredValue = declaredItem[dimension.key]
+      const measuredValue = measuredItem[dimension.key]
+      const ratio = deviationRatio(measuredValue, declaredValue)
+      if (ratio == null || ratio < 0.1 - 1e-9) return []
+      return [{
+        measuredItem,
+        declaredValue,
+        measuredValue,
+        ratio,
+      }]
+    }).sort((left, right) => right.ratio - left.ratio)
+
+    const largest = differences[0]
+    if (!largest) continue
+    const boxLabel = largest.measuredItem.boxCode || `第 ${largest.measuredItem.itemNo} 条箱规`
+    const countSuffix = differences.length > 1 ? `，共 ${differences.length} 条箱规` : ''
+    warnings.push({
+      key: dimension.key,
+      text: `${dimension.label}偏差 ${formatPercentage(largest.ratio)}（${boxLabel}：下单 ${formatNumber(largest.declaredValue)} cm → 实测 ${formatNumber(largest.measuredValue)} cm${countSuffix}）`,
+    })
+  }
+
+  const declaredGrossWeight = resource.latestDeclaration?.grossWeightKg ?? resource.originalGrossWeightKg
+  const weightRatio = deviationRatio(resource.actualGrossWeightKg, declaredGrossWeight)
+  if (weightRatio != null && weightRatio >= 0.1 - 1e-9) {
+    warnings.push({
+      key: 'grossWeightKg',
+      text: `重量偏差 ${formatPercentage(weightRatio)}（下单 ${formatNumber(declaredGrossWeight)} kg → 实测 ${formatNumber(resource.actualGrossWeightKg)} kg）`,
+    })
+  }
+  return warnings
+})
+
+const { captureBaseline } = useUnsavedWorkRegistration({
+  key: 'p2-inbound-measurement-editor',
+  label: computed(() => `入仓码 ${detail.value?.inboundCode || '待补充'} 的测量草稿`),
+  isOpen: registrationOpen,
+  model: form,
+  requiredPermission,
+})
+
+function nextItemKey() {
+  itemSequence += 1
+  return `measurement-item-${itemSequence}`
+}
+
+function localDateTimeNow() {
+  const now = new Date()
+  const pad = (value: number) => String(value).padStart(2, '0')
+  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}T${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}`
+}
+
+function resetManualEntry() {
+  manualForm.boxCode = ''
+  manualForm.length = null
+  manualForm.width = null
+  manualForm.height = null
+  manualForm.weight = null
+  manualForm.scannedShipmentId = ''
+  manualForm.machineNo = 'MANUAL-ADMIN'
+  manualForm.measuredAt = localDateTimeNow()
+  manualEntryImage.value = null
+  manualEntryErrors.value = []
+}
+
+function openManualEntry() {
+  if (!mayCreateManualEntry.value) {
+    if (isDirty.value) ElMessage.warning('请先保存当前确认箱数，再录入新的箱规')
+    return
+  }
+  resetManualEntry()
+  manualEntryOpen.value = true
+}
+
+function selectManualImage(uploadFile: UploadFile) {
+  const file = uploadFile.raw
+  manualEntryImage.value = file || null
+}
+
+function validateManualEntry() {
+  const errors: string[] = []
+  if (!manualForm.boxCode.trim()) errors.push('请输入箱号')
+  if (manualForm.boxCode.trim().length > 128) errors.push('箱号不能超过 128 个字符')
+  if (!(manualForm.length != null && manualForm.length > 0)) errors.push('测量长必须大于 0')
+  if (!(manualForm.width != null && manualForm.width > 0)) errors.push('测量宽必须大于 0')
+  if (!(manualForm.height != null && manualForm.height > 0)) errors.push('测量高必须大于 0')
+  if (!(manualForm.weight != null && manualForm.weight > 0)) errors.push('单箱毛重必须大于 0')
+  if (!manualForm.measuredAt) errors.push('请选择测量时间')
+  if (!manualEntryImage.value) errors.push('请上传当前箱测量图片')
+  if (manualEntryImage.value && manualEntryImage.value.size > 5 * 1024 * 1024) errors.push('测量图片不能超过 5 MB')
+  manualEntryErrors.value = errors
+  return errors.length === 0
+}
+
+async function submitManualEntry() {
+  if (!mayCreateManualEntry.value || !validateManualEntry() || manualForm.weight == null) return
+  manualEntrySubmitting.value = true
+  operationError.value = null
+  try {
+    await createManualCartonScan(customerId.value, props.inboundId, {
+      boxCode: manualForm.boxCode.trim(),
+      length: manualForm.length!,
+      width: manualForm.width!,
+      height: manualForm.height!,
+      weight: manualForm.weight,
+      scannedShipmentId: manualForm.scannedShipmentId.trim() || null,
+      machineNo: manualForm.machineNo.trim() || 'MANUAL-ADMIN',
+      measuredAt: manualForm.measuredAt,
+    }, manualEntryImage.value!)
+    manualEntryOpen.value = false
+    ElMessage.success('箱规已录入，服务端计算结果已更新')
+    await loadMeasurement()
+    emit('updated')
+  } catch (error) {
+    setOperationError(error, '手动箱规录入失败，请检查后重试')
+  } finally {
+    manualEntrySubmitting.value = false
+  }
+}
+
+function editableItem(item: InboundMeasurementItem): EditableMeasurementItem {
+  return {
+    itemId: String(item.id),
+    inboundDetailId: String(item.inboundDetailId || item.id),
+    clientKey: nextItemKey(),
+    inboundCode: item.inboundCode || '—',
+    fbaShipmentNo: item.fbaShipmentNo || null,
+    scannedShipmentId: item.scannedShipmentId || null,
+    boxCode: item.boxCode,
+    itemNo: item.itemNo,
+    boxSpecification: item.boxSpecification,
+    packageCount: item.packageCount,
+    lengthCm: item.lengthCm,
+    widthCm: item.widthCm,
+    heightCm: item.heightCm,
+    unitWeightKg: item.unitWeightKg,
+    intelligentImageFileId: item.intelligentImageFileId == null ? null : String(item.intelligentImageFileId),
+    machineNo: item.machineNo,
+    measuredAt: item.deviceMeasuredAt,
+    overLimitWarning: item.overLimitWarning,
+    outerLengthCm: item.outerLengthCm,
+    outerWidthCm: item.outerWidthCm,
+    outerHeightCm: item.outerHeightCm,
+    remark: item.remark,
+    serverValues: {
+      girthCm: item.girthCm,
+      unitVolumeCbm: item.unitVolumeCbm,
+      totalWeightKg: item.totalWeightKg,
+      totalVolumeCbm: item.totalVolumeCbm,
+      volumeWeightKg: item.volumeWeightKg,
+    },
+    chargeRuleId: item.chargeRuleId == null ? null : String(item.chargeRuleId),
+    coefficientMode: item.coefficientMode === 'MULTIPLY' ? 'MULTIPLY' : item.coefficientMode === 'ADD' ? 'ADD' : 'ACTUAL',
+    calculatedOuterLengthCm: item.calculatedOuterLengthCm ?? null,
+    calculatedOuterWidthCm: item.calculatedOuterWidthCm ?? null,
+    calculatedOuterHeightCm: item.calculatedOuterHeightCm ?? null,
+    calculationRuleVersion: item.calculationRuleVersion ?? null,
+  }
+}
+
+function clearForm() {
+  confirmedWeightAvailable.value = false
+  form.measurementId = null
+  form.version = 0
+  form.actualGoodsName = ''
+  form.expectedPalletCount = null
+  form.items.splice(0)
+  baseline.value = JSON.stringify(form)
+  captureBaseline()
+}
+
+function applyDetail(resource: InboundMeasurementDetail) {
+  detail.value = resource
+  confirmedWeightAvailable.value = resource.weightResults.some((item) => item.recognitionStatus === 'CONFIRMED')
+  form.measurementId = resource.measurementId == null ? null : String(resource.measurementId)
+  form.version = resource.version ?? 0
+  form.actualGoodsName = resource.actualGoodsName || ''
+  form.expectedPalletCount = resource.expectedPalletCount ?? null
+  form.items.splice(0, form.items.length, ...resource.items.map(editableItem))
+  baseline.value = JSON.stringify(form)
+  captureBaseline()
+  validationErrors.value = {}
+  conflictDetected.value = false
+}
+
+async function loadMeasurement() {
+  if (!hasContext.value || !canView.value) return
+  const sequence = ++requestSequence
+  loading.value = true
+  loadError.value = null
+  operationError.value = null
+  try {
+    const resource = await getInboundMeasurement(customerId.value, props.inboundId)
+    if (sequence !== requestSequence) return
+    applyDetail(resource)
+  } catch (error) {
+    if (sequence !== requestSequence) return
+    detail.value = null
+    clearForm()
+    loadError.value = getApiErrorDetails(error, '测量数据加载失败，请稍后重试')
+  } finally {
+    if (sequence === requestSequence) loading.value = false
+  }
+}
+
+async function reloadLatest() {
+  if (isDirty.value) {
+    try {
+      await ElMessageBox.confirm('加载最新版本会丢弃当前尚未保存的修改。确定继续吗？', '重新加载测量数据', { customClass: 'admin-density-confirm',
+        type: 'warning',
+        confirmButtonText: '加载最新版本',
+        cancelButtonText: '继续编辑',
+      })
+    } catch {
+      return
+    }
+  }
+  await loadMeasurement()
+}
+
+function validateDraft() {
+  const errors: Record<string, string[]> = {}
+  const general: string[] = []
+  if (!form.items.length) general.push('请至少保留一条实际扫描箱测量记录')
+  if (isDropship.value && (!Number.isInteger(form.expectedPalletCount) || Number(form.expectedPalletCount) < 1 || Number(form.expectedPalletCount) > 1000)) general.push('一件代发预计托数必须是 1 至 1,000 的整数')
+  else if (isDropship.value && Number(form.expectedPalletCount) > confirmedPackageCount.value) general.push('一件代发预计托数不能超过实测箱数')
+  if (form.items.length > 500) general.push('单个测量批次最多包含 500 条实际扫描箱记录')
+  form.items.forEach((item, index) => {
+    const itemErrors: string[] = []
+    if (!Number.isInteger(item.packageCount) || item.packageCount < 1 || item.packageCount > 1_000_000) itemErrors.push('箱数必须是 1 至 1,000,000 的整数')
+    const dimensions = [
+      ['长', item.lengthCm],
+      ['宽', item.widthCm],
+      ['高', item.heightCm],
+    ] as const
+    for (const [label, value] of dimensions) {
+      if (!Number.isFinite(value) || value <= 0) itemErrors.push(`${label}必须是大于 0 的有效数值`)
+      else if (value > 999_999_999.999) itemErrors.push(`${label}超出系统允许上限 999,999,999.999 cm`)
+      else if (Math.abs(value * 1000 - Math.round(value * 1000)) > 1e-6) itemErrors.push(`${label}最多保留 3 位小数`)
+    }
+    const outerDimensions = [item.outerLengthCm, item.outerWidthCm, item.outerHeightCm]
+    if (outerDimensions.some((value) => value != null)) {
+      outerDimensions.forEach((value) => {
+        if (value != null && (!Number.isFinite(value) || value <= 0)) itemErrors.push('仓库修改外箱尺寸必须大于 0')
+        else if (value != null && Math.abs(value * 1000 - Math.round(value * 1000)) > 1e-6) itemErrors.push('仓库修改外箱尺寸最多保留 3 位小数')
+      })
+    }
+    if (itemErrors.length) errors[item.clientKey] = itemErrors.map((message) => `第 ${index + 1} 条：${message}`)
+  })
+  if (general.length) errors.general = general
+  validationErrors.value = errors
+  const messages = Object.values(errors).flat()
+  if (messages.length) {
+    ElMessage.warning({
+      message: messages.length === 1 ? messages[0] : `${messages[0]}（另有 ${messages.length - 1} 项）`,
+      showClose: true,
+      duration: 4500,
+    })
+  }
+  return Object.keys(errors).length === 0
+}
+
+function setOperationError(error: unknown, fallback: string) {
+  const source = getApiErrorDetails(error, fallback)
+  const numericOverflow = /data truncation|out of range|numeric value|decimal|数值.*(过大|超出)|尺寸.*(过大|超限)/i.test(source.message)
+  const largestItem = numericOverflow
+    ? [...form.items].sort((left, right) => Math.max(right.lengthCm, right.widthCm, right.heightCm) - Math.max(left.lengthCm, left.widthCm, left.heightCm))[0]
+    : undefined
+  const details = numericOverflow ? {
+    ...source,
+    message: largestItem
+      ? `箱规尺寸或箱数超出系统允许范围，请检查箱号 ${largestItem.boxCode || largestItem.itemNo}（${formatNumber(largestItem.lengthCm)} × ${formatNumber(largestItem.widthCm)} × ${formatNumber(largestItem.heightCm)} cm）后重试`
+      : '箱规尺寸或箱数超出系统允许范围，请检查长、宽、高和箱数后重试',
+  } : source
+  const conflict = details.message.includes('版本已变化')
+    || details.message.includes('并发修改')
+    || details.message.includes('已被其他人修改')
+  conflictDetected.value = conflict
+  operationError.value = conflict ? details : null
+  if (!conflict) {
+    ElMessage.error({ message: details.message, showClose: true, duration: 4500 })
+  }
+  return details
+}
+
+async function saveDraft() {
+  if (!mayMaintain.value || !validateDraft()) return
+  saving.value = true
+  operationError.value = null
+  conflictDetected.value = false
+  try {
+    const originalCounts = new Map((detail.value?.items || []).map((item) => [String(item.id), item.packageCount]))
+    const originalDraftValues = new Map((detail.value?.items || []).map((item) => [String(item.id), JSON.stringify({
+      lengthCm: item.lengthCm, widthCm: item.widthCm, heightCm: item.heightCm,
+      outerLengthCm: item.outerLengthCm, outerWidthCm: item.outerWidthCm, outerHeightCm: item.outerHeightCm,
+      chargeRuleId: item.chargeRuleId || null, coefficientMode: item.coefficientMode || 'ACTUAL', remark: item.remark || null,
+    })]))
+    const draftChanged = Boolean(detail.value && ((detail.value.actualGoodsName || '') !== form.actualGoodsName || (detail.value.expectedPalletCount ?? null) !== form.expectedPalletCount || form.items.some((item) => originalDraftValues.get(item.itemId) !== JSON.stringify({
+      lengthCm: item.lengthCm, widthCm: item.widthCm, heightCm: item.heightCm,
+      outerLengthCm: item.outerLengthCm, outerWidthCm: item.outerWidthCm, outerHeightCm: item.outerHeightCm,
+      chargeRuleId: item.chargeRuleId || null, coefficientMode: item.coefficientMode, remark: item.remark || null,
+    }))))
+    const changedItems = form.items.filter((item) => originalCounts.get(item.itemId) !== item.packageCount)
+    let version = form.version
+    if (draftChanged) {
+      const saved = await saveInboundMeasurementDraft(customerId.value, props.inboundId, {
+        measurementId: form.measurementId,
+        version,
+        actualGoodsName: form.actualGoodsName.trim() || null,
+        expectedPalletCount: isDropship.value ? form.expectedPalletCount : null,
+        items: form.items.map((item) => ({
+          inboundDetailId: item.inboundDetailId, itemNo: item.itemNo, boxSpecification: item.boxSpecification,
+          packageCount: item.packageCount, lengthCm: item.lengthCm, widthCm: item.widthCm, heightCm: item.heightCm,
+          intelligentImageFileId: item.intelligentImageFileId, overLimitWarning: item.overLimitWarning,
+          outerLengthCm: item.outerLengthCm, outerWidthCm: item.outerWidthCm, outerHeightCm: item.outerHeightCm,
+          chargeRuleId: item.coefficientMode === 'MULTIPLY' ? item.chargeRuleId : null,
+          coefficientMode: item.coefficientMode === 'ACTUAL' ? null : item.coefficientMode, remark: item.remark,
+        })),
+      })
+      version = saved.version
+    }
+    if (!draftChanged) {
+      for (const item of changedItems) {
+        const saved = await updateConfirmedPackageCount(customerId.value, props.inboundId, item.itemId, {
+          measurementVersion: version,
+          confirmedPackageCount: item.packageCount,
+        })
+        version = saved.measurementVersion
+      }
+    }
+    form.version = version
+    ElMessage.success('确认箱数已保存，计算结果已由服务端更新')
+    await loadMeasurement()
+    emit('saved')
+    emit('changed')
+  } catch (error) {
+    setOperationError(error, '测量草稿保存失败，请检查后重试')
+  } finally {
+    saving.value = false
+  }
+}
+
+async function submitForReview() {
+  if (!hasConfirmedWeightResult.value) {
+    ElMessage.warning('即使只有一箱，也必须上传并确认至少一张称重图片后才能提交审核')
+    return
+  }
+  if (!maySubmit.value || !form.measurementId) return
+  if (!validateDraft()) return
+  if (isDirty.value) {
+    ElMessage.warning('请先保存当前修改，再提交审核')
+    return
+  }
+  try {
+    await ElMessageBox.confirm(
+      '提交成功后本批次不能继续编辑',
+      '提交测量审核',
+      { customClass: 'admin-density-confirm', type: 'warning', confirmButtonText: '确认提交', cancelButtonText: '取消' },
+    )
+  } catch {
+    return
+  }
+  submitting.value = true
+  operationError.value = null
+  conflictDetected.value = false
+  try {
+    await submitInboundMeasurement(customerId.value, props.inboundId, {
+      measurementId: form.measurementId,
+      version: form.version,
+    })
+    ElMessage.success('测量数据已提交审核')
+    await loadMeasurement()
+    emit('submitted')
+    emit('changed')
+  } catch (error) {
+    setOperationError(error, '测量数据提交失败，请检查图片和称重结果后重试')
+  } finally {
+    submitting.value = false
+  }
+}
+
+function formatNumber(value: number | null | undefined, maximumFractionDigits = 3) {
+  if (value == null || !Number.isFinite(value)) return '—'
+  return new Intl.NumberFormat('zh-CN', { maximumFractionDigits }).format(value)
+}
+
+function deviationRatio(actual: number | null | undefined, declared: number | null | undefined) {
+  if (actual == null || declared == null || !Number.isFinite(actual) || !Number.isFinite(declared) || declared <= 0) return null
+  return Math.abs(actual - declared) / Math.abs(declared)
+}
+
+function formatPercentage(ratio: number) {
+  return `${formatNumber(ratio * 100, 1)}%`
+}
+
+function formatDifference(actual: number | null | undefined, declared: number | null | undefined, maximumFractionDigits = 3, unit = '') {
+  if (actual == null || declared == null || !Number.isFinite(actual) || !Number.isFinite(declared)) return null
+  const difference = actual - declared
+  if (difference === 0) return null
+  const sign = difference > 0 ? '+' : ''
+  return `差异 ${sign}${formatNumber(difference, maximumFractionDigits)}${unit}`
+}
+
+function releaseImagePreview() {
+  if (imagePreviewUrl.value) URL.revokeObjectURL(imagePreviewUrl.value)
+  imagePreviewUrl.value = ''
+  imagePreviewError.value = null
+}
+
+async function previewImage(fileId: string | null) {
+  if (!fileId) return
+  releaseImagePreview()
+  imagePreviewOpen.value = true
+  imagePreviewLoading.value = true
+  try {
+    const blob = await downloadInboundMeasurementImage(customerId.value, props.inboundId, fileId)
+    imagePreviewUrl.value = URL.createObjectURL(blob)
+  } catch (error) {
+    imagePreviewError.value = getApiErrorDetails(error, '测量图片加载失败')
+  } finally {
+    imagePreviewLoading.value = false
+  }
+}
+
+function processStatusLabel(status: string | undefined) {
+  return inboundStatusLabel(status, inboundProcessStatusLabels)
+}
+
+function updateWeightEvidence(
+  actualGrossWeightKg: number | null,
+  actualNetWeightKg: number | null,
+  hasConfirmedWeight: boolean,
+) {
+  if (!detail.value) return
+  detail.value = { ...detail.value, actualGrossWeightKg, actualNetWeightKg }
+  confirmedWeightAvailable.value = hasConfirmedWeight
+}
+
+function calculationModeLabel(value: EditableMeasurementItem['coefficientMode']) {
+  return value === 'ADD' ? '箱规尺寸' : value === 'MULTIPLY' ? '箱规系数' : '实测原尺寸'
+}
+
+function measurementRowClassName({ row }: { row: EditableMeasurementItem }) {
+  return validationErrors.value[row.clientKey]?.length ? 'measurement-table__row--error' : ''
+}
+
+watch(
+  () => [customerId.value, props.inboundId, canView.value] as const,
+  () => {
+    requestSequence += 1
+    detail.value = null
+    confirmedWeightAvailable.value = false
+    loadError.value = null
+    operationError.value = null
+    conflictDetected.value = false
+    validationErrors.value = {}
+    clearForm()
+    if (hasContext.value && canView.value) void loadMeasurement()
+  },
+  { immediate: true },
+)
+
+onBeforeUnmount(releaseImagePreview)
+
+defineExpose({ saveDraft, submitForReview, updateWeightEvidence, submissionBlockReason, mayMaintain, maySubmit, saving, submitting, canEdit, canSubmit, isDirty })
+</script>
+
+<template>
+  <section class="surface-panel measurement-panel" aria-label="入库测量草稿">
+    <el-empty v-if="!hasContext" description="请选择所属企业和入库单后维护测量数据" />
+
+    <LoadErrorState
+      v-else-if="!canView"
+      title="无测量查看权限"
+      message="当前账号缺少 platform:firstleg:inbound:measure:view 权限。"
+      :show-retry="false"
+    />
+
+    <div v-else-if="loading && !detail" class="measurement-skeleton" aria-label="正在加载测量数据">
+      <el-skeleton :rows="8" animated />
+    </div>
+
+    <LoadErrorState
+      v-else-if="loadError && !detail"
+      title="测量数据加载失败"
+      :message="loadError.message"
+      :loading="loading"
+      @retry="loadMeasurement"
+    >
+      <template #details><ApiErrorMeta :details="loadError" /></template>
+    </LoadErrorState>
+
+    <template v-else-if="detail">
+      <el-alert
+        v-if="detail.processStatus === 'PREPARING'"
+        type="warning"
+        :closable="false"
+        show-icon
+        class="measurement-alert"
+        title="订单尚待客服审核，可先完成到仓称重和测量"
+      >
+        已采集数据会保留并在订单审核通过后继续使用；订单审核前不能审核测量、计费或进入分柜。
+      </el-alert>
+      <el-alert v-if="!countEditableProcess" type="info" :closable="false" show-icon>
+        <template #title>当前状态为“{{ processStatusLabel(detail.processStatus) }}”，测量数据仅可查看</template>
+        确认箱数只允许在待测量、测量中、待审核或审核驳回状态维护。
+      </el-alert>
+
+      <el-alert v-else-if="!canEdit" type="info" :closable="false" show-icon title="当前账号仅可查看测量数据" />
+
+      <el-alert
+        v-if="submissionBlockReason && !hasConfirmedWeightResult"
+        type="warning"
+        :closable="false"
+        show-icon
+        class="measurement-alert"
+        :title="submissionBlockReason"
+      />
+
+      <el-alert v-if="conflictDetected" type="warning" :closable="false" show-icon class="measurement-alert">
+        <template #title>数据版本已变化，当前修改尚未丢失</template>
+        <p>{{ operationError?.message }}</p>
+        <ApiErrorMeta v-if="operationError" :details="operationError" />
+        <el-button size="small" @click="reloadLatest">加载最新版本</el-button>
+      </el-alert>
+      <p v-if="Object.keys(validationErrors).length" class="sr-only" role="alert">
+        {{ Object.values(validationErrors).flat().join('；') }}
+      </p>
+
+      <form class="measurement-form" @submit.prevent="saveDraft">
+        <fieldset :disabled="!mayMaintain || saving">
+          <legend class="sr-only">测量草稿</legend>
+          <section class="measurement-section measurement-summary-section">
+            <header class="measurement-summary-header">
+              <div class="measurement-summary-context">
+                <p><span>客户</span>{{ detail.companyName || '客户未命名' }}</p>
+                <p><span>渠道</span>{{ detail.channelName || detail.channelCode || '渠道未填写' }}</p>
+              </div>
+              <div class="measurement-summary-status">
+                <el-tag effect="light">{{ processStatusLabel(detail.processStatus) }}</el-tag>
+                <span>{{ sourceLabel }}</span>
+              </div>
+            </header>
+
+            <el-alert
+              v-if="measurementDeviationWarnings.length"
+              class="measurement-deviation-alert"
+              type="warning"
+              :closable="false"
+              show-icon
+              title="下单箱规与测量数据差异达到 10%"
+            >
+              <p v-for="warning in measurementDeviationWarnings" :key="warning.key">{{ warning.text }}</p>
+            </el-alert>
+
+            <h4 class="measurement-subheading">平台实测</h4>
+            <dl class="measurement-metrics" aria-label="平台实测结果汇总">
+              <div :class="{ 'measurement-metric--warning': !packageCountMatched }">
+                <dt>实测箱数</dt>
+                <dd>{{ formatNumber(confirmedPackageCount, 0) }} <small v-if="formatDifference(confirmedPackageCount, expectedPackageCount, 0)">/ {{ formatDifference(confirmedPackageCount, expectedPackageCount, 0) }}</small></dd>
+              </div>
+              <div><dt>实测毛重</dt><dd>{{ formatNumber(detail.actualGrossWeightKg) }} <small>kg<span v-if="formatDifference(detail.actualGrossWeightKg, detail.originalGrossWeightKg, 3, ' kg')"> · {{ formatDifference(detail.actualGrossWeightKg, detail.originalGrossWeightKg, 3, ' kg') }}</span></small></dd></div>
+              <div class="measurement-metric--primary"><dt>货物净重</dt><dd>{{ formatNumber(detail.actualNetWeightKg) }} <small>kg</small></dd></div>
+              <div><dt>总体积</dt><dd>{{ formatNumber(detail.actualVolumeCbm, 4) }} <small>m³<span v-if="formatDifference(detail.actualVolumeCbm, detail.originalVolumeCbm, 4, ' m³')"> · {{ formatDifference(detail.actualVolumeCbm, detail.originalVolumeCbm, 4, ' m³') }}</span></small></dd></div>
+              <div><dt>材积重</dt><dd>{{ formatNumber(detail.volumeWeightKg) }} <small>kg</small></dd></div>
+            </dl>
+
+            <section class="measurement-declaration" aria-labelledby="measurement-declaration-title">
+              <h4 id="measurement-declaration-title">客户申报</h4>
+              <div class="measurement-data-grid">
+                <div class="measurement-readonly-field"><span>申报箱数</span><strong>{{ formatNumber(expectedPackageCount, 0) }}</strong></div>
+                <div class="measurement-readonly-field"><span>申报毛重（kg）</span><strong>{{ formatNumber(detail.originalGrossWeightKg) }}</strong></div>
+                <div class="measurement-readonly-field"><span>申报体积（m³）</span><strong>{{ formatNumber(detail.originalVolumeCbm, 4) }}</strong></div>
+                <label v-if="mayMaintain" class="measurement-goods-name"><span>实际品名</span><el-input v-model="form.actualGoodsName" placeholder="请输入实际品名" maxlength="255" /></label>
+                <div v-else class="measurement-readonly-field measurement-goods-name"><span>实际品名</span><strong>{{ detail.actualGoodsName || '—' }}</strong></div>
+                <label v-if="isDropship && mayMaintain"><span>预计托数</span><el-input-number v-model="form.expectedPalletCount" placeholder="请输入预计托数" :min="1" :max="1000" :step="1" step-strictly controls-position="right" /></label>
+                <div v-else-if="isDropship" class="measurement-readonly-field"><span>预计托数</span><strong>{{ detail.expectedPalletCount ?? '—' }}</strong></div>
+                <div class="measurement-readonly-field"><span>原单据号码</span><strong>{{ detail.originalDocumentNo || '—' }}</strong></div>
+              </div>
+              <el-table
+                v-if="detail.latestDeclaration?.items.length"
+                :data="detail.latestDeclaration.items"
+                border
+                stripe
+                size="small"
+                class="measurement-declaration-table"
+                aria-label="客户申报箱规明细"
+              >
+                <el-table-column prop="itemNo" label="#" width="70" />
+                <el-table-column prop="cargoName" label="货物品名" min-width="150" show-overflow-tooltip />
+                <el-table-column prop="packageCount" label="申报箱数" width="100" />
+                <el-table-column label="申报尺寸 长×宽×高(cm)" min-width="190">
+                  <template #default="{ row }">{{ formatNumber(row.lengthCm) }} × {{ formatNumber(row.widthCm) }} × {{ formatNumber(row.heightCm) }}</template>
+                </el-table-column>
+              </el-table>
+            </section>
+          </section>
+
+          <section class="measurement-section measurement-items-section">
+            <div class="measurement-section__heading">
+              <div><h3>箱规明细</h3></div>
+              <div class="measurement-section-actions">
+                <el-button v-if="canManualEntry" type="primary" plain :disabled="!mayCreateManualEntry" @click="openManualEntry"><Plus :size="15" />手动录入箱规</el-button>
+              </div>
+            </div>
+
+            <el-table
+              v-if="form.items.length"
+              :data="form.items"
+              border
+              stripe
+              table-layout="fixed"
+              class="measurement-table"
+              :row-class-name="measurementRowClassName"
+            >
+              <el-table-column type="expand" width="42">
+                <template #default="{ row }">
+                  <dl class="measurement-row-details">
+                    <div><dt>箱规</dt><dd>{{ row.boxSpecification || '—' }}</dd></div>
+                    <div><dt>机器编号</dt><dd>{{ row.machineNo || '人工录入' }}</dd></div>
+                    <div><dt>测量时间</dt><dd>{{ row.measuredAt ? row.measuredAt.replace('T', ' ') : '—' }}</dd></div>
+                    <div><dt>计算方式</dt><dd>{{ calculationModeLabel(row.coefficientMode) }}</dd></div>
+                    <div><dt>计算后外箱</dt><dd>{{ formatNumber(row.calculatedOuterLengthCm) }} × {{ formatNumber(row.calculatedOuterWidthCm) }} × {{ formatNumber(row.calculatedOuterHeightCm) }} cm</dd></div>
+                    <div><dt>单箱体积</dt><dd>{{ formatNumber(row.serverValues.unitVolumeCbm, 4) }} m³</dd></div>
+                    <div><dt>箱规周长</dt><dd>{{ formatNumber(row.serverValues.girthCm) }} cm</dd></div>
+                    <div><dt>总材积重</dt><dd>{{ formatNumber(row.serverValues.volumeWeightKg) }} kg</dd></div>
+                    <div><dt>计算规则版本</dt><dd>{{ row.calculationRuleVersion || '—' }}</dd></div>
+                    <div><dt>超限提醒</dt><dd>{{ row.overLimitWarning || '—' }}</dd></div>
+                    <div><dt>备注</dt><dd>{{ row.remark || '—' }}</dd></div>
+                  </dl>
+                </template>
+              </el-table-column>
+              <el-table-column prop="itemNo" label="#" width="70" align="center" />
+              <el-table-column label="入仓码" min-width="154" show-overflow-tooltip>
+                <template #default="{ row }">{{ row.inboundCode || '—' }}</template>
+              </el-table-column>
+              <el-table-column label="FBA 货件号" min-width="150" show-overflow-tooltip>
+                <template #default="{ row }">{{ row.fbaShipmentNo || '—' }}</template>
+              </el-table-column>
+              <el-table-column label="设备实扫货件号" min-width="164" show-overflow-tooltip>
+                <template #default="{ row }">{{ row.scannedShipmentId || '—' }}</template>
+              </el-table-column>
+              <el-table-column label="箱号" min-width="156" show-overflow-tooltip>
+                <template #default="{ row }"><span class="measurement-box-code">{{ row.boxCode || '—' }}</span></template>
+              </el-table-column>
+              <el-table-column label="尺寸 长×宽×高(cm)" width="166" align="center">
+                <template #default="{ row }">{{ formatNumber(row.lengthCm) }} × {{ formatNumber(row.widthCm) }} × {{ formatNumber(row.heightCm) }}</template>
+              </el-table-column>
+              <el-table-column label="仓库修改外箱（长）" width="165" align="center">
+                <template #default="{ row }"><el-input-number v-model="row.outerLengthCm" aria-label="仓库修改外箱长" :min="0.001" :precision="3" :controls="false" placeholder="不修改" /></template>
+              </el-table-column>
+              <el-table-column label="仓库修改外箱（宽）" width="165" align="center">
+                <template #default="{ row }"><el-input-number v-model="row.outerWidthCm" aria-label="仓库修改外箱宽" :min="0.001" :precision="3" :controls="false" placeholder="不修改" /></template>
+              </el-table-column>
+              <el-table-column label="仓库修改外箱（高）" width="165" align="center">
+                <template #default="{ row }"><el-input-number v-model="row.outerHeightCm" aria-label="仓库修改外箱高" :min="0.001" :precision="3" :controls="false" placeholder="不修改" /></template>
+              </el-table-column>
+              <el-table-column label="确认箱数" width="132" align="center">
+                <template #default="{ row }">
+                  <el-input-number
+                    v-model="row.packageCount"
+                    class="measurement-count-editor"
+                    aria-label="确认箱数"
+                    :min="1"
+                    :max="1000000"
+                    :step="1"
+                    step-strictly
+                    controls-position="right" placeholder="请输入箱数" />
+                </template>
+              </el-table-column>
+              <el-table-column label="总体积(m³)" width="108" align="right">
+                <template #default="{ row }">{{ formatNumber(row.serverValues.totalVolumeCbm, 4) }}</template>
+              </el-table-column>
+              <el-table-column label="图片" width="82" align="center">
+                <template #default="{ row }">
+                  <el-tooltip :content="row.intelligentImageFileId ? '预览测量图片' : '暂无测量图片'">
+                    <el-button text type="primary" :disabled="!row.intelligentImageFileId" aria-label="预览测量图片" @click="previewImage(row.intelligentImageFileId)">
+                      <Image :size="16" />
+                    </el-button>
+                  </el-tooltip>
+                </template>
+              </el-table-column>
+            </el-table>
+            <el-empty v-else description="暂无扫描箱测量数据" />
+          </section>
+        </fieldset>
+      </form>
+
+      <footer v-if="canEdit || canSubmit" class="measurement-panel__footer">
+        <span v-if="!hasConfirmedWeightResult"><AlertTriangle :size="15" />至少上传并确认一张称重图片后才能提交审核</span>
+        <span v-else-if="isDirty"><AlertTriangle :size="15" />有尚未保存的修改</span>
+        <span v-else>所有修改已保存</span>
+        <div>
+          <el-button v-if="canEdit" type="primary" plain :loading="saving" :disabled="!mayMaintain" @click="saveDraft"><Save :size="15" />保存测量数据</el-button>
+          <el-button v-if="canSubmit" type="primary" :loading="submitting" :disabled="!maySubmit" @click="submitForReview"><Send :size="15" />提交审核</el-button>
+        </div>
+      </footer>
+
+      <el-dialog class="admin-density-dialog" v-model="imagePreviewOpen" title="当前有效测量图片" width="min(720px, 92vw)" destroy-on-close @closed="releaseImagePreview">
+        <div class="measurement-image-preview">
+          <el-skeleton v-if="imagePreviewLoading" :rows="5" animated />
+          <LoadErrorState v-else-if="imagePreviewError" title="图片加载失败" :message="imagePreviewError.message" :show-retry="false">
+            <template #details><ApiErrorMeta :details="imagePreviewError" /></template>
+          </LoadErrorState>
+          <img v-else-if="imagePreviewUrl" :src="imagePreviewUrl" alt="当前扫描箱测量图片" />
+          <el-empty v-else description="暂无可预览图片" />
+        </div>
+      </el-dialog>
+
+      <el-dialog class="admin-density-dialog" v-model="manualEntryOpen" title="手动录入箱规" width="min(680px, 92vw)" destroy-on-close>
+        <el-alert v-if="manualEntryErrors.length" type="error" :closable="false" show-icon class="manual-entry-alert" title="请修正以下问题">
+          <ul><li v-for="error in manualEntryErrors" :key="error">{{ error }}</li></ul>
+        </el-alert>
+        <el-form label-position="top" class="manual-entry-form" @submit.prevent="submitManualEntry">
+          <div class="measurement-form-grid">
+            <el-form-item label="箱号 *"><el-input v-model="manualForm.boxCode" placeholder="请输入已打印箱唛上的箱号" /></el-form-item>
+            <el-form-item label="测量长（cm） *"><el-input-number v-model="manualForm.length" :min="0.001" :precision="3" controls-position="right" placeholder="请输入测量长" /></el-form-item>
+            <el-form-item label="测量宽（cm） *"><el-input-number v-model="manualForm.width" :min="0.001" :precision="3" controls-position="right" placeholder="请输入测量宽" /></el-form-item>
+            <el-form-item label="测量高（cm） *"><el-input-number v-model="manualForm.height" :min="0.001" :precision="3" controls-position="right" placeholder="请输入测量高" /></el-form-item>
+            <el-form-item label="单箱毛重（kg） *"><el-input-number v-model="manualForm.weight" :min="0.001" :precision="3" controls-position="right" placeholder="请输入单箱毛重" /></el-form-item>
+            <el-form-item label="测量时间 *"><el-date-picker v-model="manualForm.measuredAt" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" format="YYYY-MM-DD HH:mm:ss" /></el-form-item>
+            <el-form-item label="设备/来源编号"><el-input v-model="manualForm.machineNo" maxlength="64" placeholder="请输入设备编号（选填）" /></el-form-item>
+            <el-form-item label="Shipment ID"><el-input v-model="manualForm.scannedShipmentId" maxlength="64" placeholder="请输入扫描运单号（选填）" /></el-form-item>
+          </div>
+          <el-form-item label="当前箱测量图片 *">
+            <el-upload class="manual-entry-upload" :auto-upload="false" :limit="1" accept="image/*" :on-change="selectManualImage" :on-remove="() => { manualEntryImage = null }">
+              <el-button><Upload :size="15" />选择图片</el-button>
+              <template #tip><div class="el-upload__tip">支持图片格式，大小不超过 5 MB</div></template>
+            </el-upload>
+          </el-form-item>
+        </el-form>
+        <template #footer>
+          <el-button :disabled="manualEntrySubmitting" @click="manualEntryOpen = false">取消</el-button>
+          <el-button type="primary" :loading="manualEntrySubmitting" @click="submitManualEntry">保存箱规</el-button>
+        </template>
+      </el-dialog>
+    </template>
+  </section>
+</template>
+
+<style scoped>
+.measurement-panel { overflow: hidden; }
+.measurement-panel__heading > div:first-child { display: flex; min-width: 0; align-items: flex-start; gap: 11px; }
+.measurement-panel__icon { display: grid; width: 34px; height: 34px; flex: 0 0 34px; place-items: center; border-radius: 8px; background: #eef4ff; color: var(--cc-primary); }
+.measurement-panel h2, .measurement-panel h3 { margin: 0; color: var(--cc-text); }
+.measurement-panel h2 { font-size: var(--admin-font-title, 16px); }
+.measurement-panel h3 { font-size: var(--admin-font-section, 14px); }
+.measurement-panel__heading p, .measurement-section__heading p { margin: var(--admin-space-1, 4px) 0 0; color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); line-height: 1.55; }
+.measurement-panel__actions, .measurement-panel__footer > div { display: flex; flex: 0 0 auto; flex-wrap: wrap; justify-content: flex-end; gap: var(--admin-space-3, 8px); }
+.measurement-declaration-table { margin-top: var(--admin-space-5, 12px); }
+.measurement-panel__actions :deep(.el-button), .measurement-panel__footer :deep(.el-button) { margin-left: 0; }
+.measurement-skeleton { padding: var(--admin-space-7, 24px); }
+.measurement-panel > :deep(.el-alert), .measurement-alert { margin: var(--admin-space-6, 16px) 20px 0; width: auto; }
+.measurement-alert p { margin: 5px 0 0; line-height: 1.55; }
+.measurement-alert ul { margin: 7px 0 0; padding-left: 18px; font-size: var(--admin-font-caption, 12px); line-height: 1.65; }
+.measurement-alert .el-button { margin-top: 9px; }
+.measurement-form fieldset { min-width: 0; margin: 0; padding: 0; border: 0; }
+.measurement-section { padding: var(--admin-space-6, 16px) 0px; border-top: 1px solid var(--cc-border); }
+.measurement-summary-section { display: grid; gap: var(--admin-space-5, 12px); border-top: 0; }
+.measurement-summary-header { display: flex; align-items: flex-start; justify-content: space-between; gap: 20px; }
+.measurement-summary-context { display: flex; min-width: 0; flex-wrap: wrap; align-items: center; gap: var(--admin-space-3, 8px) 20px; }
+.measurement-summary-header span { color: var(--cc-muted); font-size: var(--admin-font-caption, 11px); }
+.measurement-deviation-alert { margin: 0; width: auto; }
+.measurement-deviation-alert p { margin: 3px 0 0; line-height: 1.55; }
+.measurement-summary-context p { display: inline-flex; min-width: 0; align-items: baseline; gap: var(--admin-space-2, 6px); margin: 0; overflow-wrap: anywhere; color: var(--cc-text); font-size: var(--admin-font-caption, 12px); font-weight: 600; }
+.measurement-summary-status { display: flex; flex: 0 0 auto; align-items: center; gap: 9px; }
+.measurement-metrics { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); margin: 2px 0; }
+.measurement-subheading { margin: 0; color: #344054; font-size: var(--admin-font-caption, 12px); font-weight: 700; }
+.measurement-metrics > div { display: grid; min-width: 0; min-height: 58px; align-content: center; gap: var(--admin-space-1, 4px); padding: 5px 18px; border-left: 1px solid var(--cc-border); }
+.measurement-metrics > div:first-child { padding-left: 0; border-left: 0; }
+.measurement-metrics dt { color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); }
+.measurement-metrics dd { min-width: 0; margin: 0; color: var(--cc-text); font-size: 18px; font-weight: 700; overflow-wrap: anywhere; }
+.measurement-metrics small { color: var(--cc-muted); font-size: var(--admin-font-caption, 11px); font-weight: 500; }
+.measurement-metric--primary dd { color: var(--cc-primary); font-size: 20px; }
+.measurement-metric--warning dd { color: var(--el-color-warning-dark-2); }
+.measurement-declaration { padding-top: var(--admin-space-5, 12px); border-top: 1px solid var(--cc-border); }
+.measurement-declaration h4 { margin: 0 0 var(--admin-space-4, 10px); color: #344054; font-size: var(--admin-font-caption, 12px); font-weight: 700; }
+.measurement-section__heading { display: flex; align-items: flex-start; justify-content: space-between; gap: 18px; margin-bottom: var(--admin-space-6, 16px); }
+.measurement-section__heading > div { min-width: 0; }
+.measurement-section-actions { display: flex; flex-wrap: wrap; justify-content: flex-end; gap: var(--admin-space-3, 8px); }.measurement-section-actions :deep(.el-button) { margin-left: 0; }
+.warehouse-suggestion-form { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 0 var(--admin-space-6, 16px); }.warehouse-suggestion-form :deep(.el-select),.warehouse-suggestion-form :deep(.el-input-number) { width: 100%; }.warehouse-suggestion-form :deep(.el-form-item:last-child) { grid-column: 1 / -1; }.suggestion-preview { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); margin: var(--admin-space-1, 4px) 0 0; border: 1px solid var(--cc-border); border-radius: 6px; }.suggestion-preview div { padding: var(--admin-space-5, 12px); border-right: 1px solid var(--cc-border); }.suggestion-preview div:last-child { border-right: 0; }.suggestion-preview dt { color: var(--cc-muted); font-size: var(--admin-font-caption, 11px); }.suggestion-preview dd { margin: 5px 0 0; color: var(--cc-text); font-size: var(--admin-font-body, 13px); font-weight: 650; }
+.measurement-form-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 0 var(--admin-space-6, 16px); }
+.measurement-data-grid { display: grid; grid-template-columns: repeat(5, minmax(0, 1fr)); gap: var(--admin-space-5, 12px); }
+.measurement-form label { display: flex; min-width: 0; flex-direction: column; gap: 7px; color: #344054; font-size: var(--admin-font-caption, 12px); font-weight: 650; }
+.measurement-form :deep(.el-input-number), .measurement-form :deep(.el-input) { width: 100%; }
+.measurement-data-grid label { display: flex; min-width: 0; flex-direction: column; gap: 5px; color: #344054; font-size: var(--admin-font-caption, 12px); font-weight: 600; }
+.measurement-data-grid :deep(.el-input__wrapper) { border-radius: 3px; }
+.measurement-readonly-field { display: grid; min-width: 0; align-content: start; gap: 7px; }
+.measurement-readonly-field span { color: #344054; font-size: var(--admin-font-caption, 12px); font-weight: 600; }
+.measurement-readonly-field strong { min-height: var(--admin-control-height, 32px); padding: 7px 0; overflow-wrap: anywhere; color: var(--cc-text); font-size: var(--admin-font-body, 13px); line-height: 18px; }
+.measurement-image-preview { display: grid; min-height: 240px; place-items: center; }
+.measurement-image-preview img { display: block; width: auto; max-width: 100%; max-height: 68vh; object-fit: contain; }
+.manual-entry-alert { margin-bottom: var(--admin-space-6, 16px); }
+.manual-entry-alert ul { margin: var(--admin-space-2, 6px) 0 0; padding-left: 18px; }
+.manual-entry-form :deep(.el-input-number), .manual-entry-form :deep(.el-date-editor) { width: 100%; }
+.manual-entry-upload { width: 100%; }
+.measurement-items-section { background: var(--admin-surface, #fff); }
+.measurement-table { width: 100%; font-size: var(--admin-font-caption, 12px); }
+.measurement-table :deep(.el-table__header th) { padding: var(--admin-space-3, 8px) 0; background: #f6f8fa; color: #475467; font-size: var(--admin-font-caption, 11px); font-weight: 700; }
+.measurement-table :deep(.el-table__cell) { padding: 7px 0; }
+.measurement-table :deep(.cell) { line-height: 1.35; }
+.measurement-table :deep(.measurement-table__row--error > td.el-table__cell) { background: var(--el-color-danger-light-9); }
+.warehouse-suggestion-table { display: grid; gap: var(--admin-space-4, 10px); margin-top: 18px; }.warehouse-suggestion-table h3 { margin: 0; color: var(--cc-text); font-size: var(--admin-font-section, 14px); }
+.measurement-box-code { font-weight: 650; }
+.measurement-count-editor { width: 104px !important; }
+.measurement-row-details { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: var(--admin-space-3, 8px) 20px; margin: 0; padding: var(--admin-space-1, 4px) 18px var(--admin-space-3, 8px) 62px; }
+.measurement-row-details dt { color: var(--cc-muted); font-size: var(--admin-font-caption, 11px); }
+.measurement-row-details dd { margin: 3px 0 0; overflow-wrap: anywhere; color: var(--cc-text); font-size: var(--admin-font-caption, 12px); font-weight: 600; }
+.measurement-panel__footer { position: sticky; bottom: 0; z-index: 2; display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-6, 16px); padding: var(--admin-space-5, 12px) 20px; border-top: 1px solid var(--cc-border); background: var(--admin-surface, #fff); }
+.measurement-panel__footer > span { display: inline-flex; align-items: center; gap: var(--admin-space-2, 6px); color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); }
+.measurement-panel__footer > span:has(svg) { color: #b54708; font-weight: 650; }
+.sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; }
+
+@media (max-width: 960px) {
+  .measurement-form-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+  .measurement-data-grid { grid-template-columns: repeat(3, minmax(0, 1fr)); }
+  .measurement-row-details { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+  .measurement-metrics { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+  .measurement-metrics > div:nth-child(3) { padding-left: 0; border-left: 0; }
+}
+
+@media (max-width: 720px) {
+  .measurement-panel__heading, .measurement-summary-header, .measurement-section__heading, .measurement-panel__footer { align-items: stretch; flex-direction: column; }
+  .measurement-panel__actions, .measurement-panel__actions :deep(.el-button), .measurement-panel__footer > div, .measurement-panel__footer :deep(.el-button) { width: 100%; }
+  .measurement-panel__actions :deep(.el-button), .measurement-panel__footer :deep(.el-button), .measurement-section__heading :deep(.el-button) { min-height: 44px; }
+  .measurement-tags { justify-content: flex-start; }
+  .measurement-section { padding-right: 14px; padding-left: 14px; }
+  .measurement-panel > :deep(.el-alert), .measurement-alert { margin-right: 14px; margin-left: 14px; }
+  .measurement-form-grid, .measurement-data-grid { grid-template-columns: 1fr; }
+  .measurement-row-details { grid-template-columns: 1fr; padding-left: 54px; }
+}
+
+@media (max-width: 420px) {
+}
+</style>
diff --git a/src/modules/inbounds/measurement/api.test.ts b/src/modules/inbounds/measurement/api.test.ts
new file mode 100644
index 00000000..04fc059e
--- /dev/null
+++ b/src/modules/inbounds/measurement/api.test.ts
@@ -0,0 +1,149 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import { createManualCartonScan, downloadInboundMeasurementImage, getInboundMeasurement, saveInboundMeasurementDraft, submitInboundMeasurement, updateConfirmedPackageCount, updateMeasurementCalculationStrategy, updateMeasurementOuterDimensions } from './api'
+import type { SaveInboundMeasurementDraftRequest } from './types'
+
+vi.mock('@/shared/api/http', () => ({
+  http: { get: vi.fn(), put: vi.fn(), post: vi.fn() },
+  unwrapApiResponse: <T>(response: { data: T }) => response.data,
+}))
+
+const draft: SaveInboundMeasurementDraftRequest = {
+  measurementId: '9001',
+  version: 2,
+  actualGoodsName: '蓝牙音箱',
+  items: [{
+    boxCode: 'RK202608040001#10-1',
+    itemNo: '001',
+    boxSpecification: '50×40×30cm',
+    packageCount: 10,
+    lengthCm: 50,
+    widthCm: 40,
+    heightCm: 30,
+    unitWeightKg: 12,
+    intelligentImageFileId: '88001',
+    machineNo: 'MJ20210327',
+    measuredAt: '2026-08-04T10:30:00+08:00',
+    overLimitWarning: null,
+    outerLengthCm: null,
+    outerWidthCm: null,
+    outerHeightCm: null,
+    remark: null,
+  }],
+}
+
+describe('inbound measurement API', () => {
+  beforeEach(() => {
+    vi.mocked(http.get).mockReset()
+    vi.mocked(http.put).mockReset()
+    vi.mocked(http.post).mockReset()
+  })
+
+  it('maps the selected customer to the backend tenant compatibility parameter', async () => {
+    const detail = { inboundId: '7001', items: [], weightResults: [] }
+    vi.mocked(http.get).mockResolvedValue({ code: '200', message: 'success', data: detail })
+
+    await expect(getInboundMeasurement('10001', '7001')).resolves.toEqual(detail)
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/first-leg/inbounds/7001/measurement', {
+      params: { tenantId: '10001', requestAt: expect.any(Number) },
+    })
+  })
+
+  it('saves a versioned draft without inventing an idempotency header', async () => {
+    const saved = { measurementId: '9001', version: 3, status: 'DRAFT' }
+    vi.mocked(http.put).mockResolvedValue({ code: '200', message: 'success', data: saved })
+
+    await expect(saveInboundMeasurementDraft('10001', '7001', draft)).resolves.toEqual(saved)
+    expect(http.put).toHaveBeenCalledWith(
+      '/platform/v1/first-leg/inbounds/7001/measurement/draft',
+      draft,
+      { params: { tenantId: '10001' } },
+    )
+    expect(draft).not.toHaveProperty('originalDocumentNo')
+    expect(draft).not.toHaveProperty('originalGrossWeightKg')
+    expect(draft).not.toHaveProperty('originalVolumeCbm')
+  })
+
+  it('submits the server measurement id and optimistic-lock version', async () => {
+    const submitted = { measurementId: '9001', version: 3, processStatus: 'MEASURE_PENDING' }
+    vi.mocked(http.post).mockResolvedValue({ code: '200', message: 'success', data: submitted })
+
+    await expect(submitInboundMeasurement('10001', '7001', { measurementId: '9001', version: 3 })).resolves.toEqual(submitted)
+    expect(http.post).toHaveBeenCalledWith(
+      '/platform/v1/first-leg/inbounds/7001/measurement/submit',
+      { measurementId: '9001', version: 3 },
+      { params: { tenantId: '10001' } },
+    )
+  })
+
+  it('updates calculation strategy without resaving the frozen measurement batch', async () => {
+    const payload = { measurementId: '9001', version: 3, coefficientMode: 'ADD' as const, chargeRuleId: null }
+    const saved = { ...payload, version: 4, status: 'SUBMITTED' }
+    vi.mocked(http.put).mockResolvedValue({ code: '200', message: 'success', data: saved })
+
+    await expect(updateMeasurementCalculationStrategy('10001', '7001', payload)).resolves.toEqual(saved)
+    expect(http.put).toHaveBeenCalledWith(
+      '/platform/v1/first-leg/inbounds/7001/measurement/calculation-strategy',
+      payload,
+      { params: { tenantId: '10001' } },
+    )
+  })
+
+  it('updates one warehouse outer dimension row without resaving the frozen measurement batch', async () => {
+    const payload = {
+      measurementId: '9001', version: 4,
+      outerLengthCm: 30, outerWidthCm: 20, outerHeightCm: 20,
+    }
+    const saved = { measurementId: '9001', version: 5, status: 'SUBMITTED', itemId: '81' }
+    vi.mocked(http.put).mockResolvedValue({ code: '200', message: 'success', data: saved })
+
+    await expect(updateMeasurementOuterDimensions('10001', '7001', '81', payload)).resolves.toEqual(saved)
+    expect(http.put).toHaveBeenCalledWith(
+      '/platform/v1/first-leg/inbounds/7001/measurement/items/81/outer-dimensions',
+      payload,
+      { params: { tenantId: '10001' } },
+    )
+  })
+
+  it('downloads the current measurement image using the scoped file route', async () => {
+    const image = new Blob(['image-data'], { type: 'image/jpeg' })
+    vi.mocked(http.get).mockResolvedValue(image)
+
+    await expect(downloadInboundMeasurementImage('100/01', '7001#1', '88001')).resolves.toBe(image)
+    expect(http.get).toHaveBeenCalledWith(
+      '/platform/v1/files/measurements/100%2F01/7001%231/88001',
+      { responseType: 'blob' },
+    )
+  })
+
+  it('updates one scanned carton confirmed package count', async () => {
+    const saved = { measurementId: '9001', measurementVersion: 3, itemId: '1', boxCode: 'RK#10-1', confirmedPackageCount: 9 }
+    vi.mocked(http.put).mockResolvedValue({ code: '200', message: 'success', data: saved })
+
+    await expect(updateConfirmedPackageCount('10001', '7001', '1', {
+      measurementVersion: 2,
+      confirmedPackageCount: 9,
+    })).resolves.toEqual(saved)
+    expect(http.put).toHaveBeenCalledWith(
+      '/platform/v1/first-leg/inbounds/7001/measurement/items/1/confirmed-package-count',
+      { measurementVersion: 2, confirmedPackageCount: 9 },
+      { params: { tenantId: '10001' } },
+    )
+  })
+
+  it('posts manual carton scan data and image to the scoped multipart route', async () => {
+    const result = { measurementId: '9001', measurementVersion: 3, itemId: '2', boxCode: 'RK#10-2', confirmedPackageCount: 1 }
+    vi.mocked(http.post).mockResolvedValue({ code: '200', message: 'success', data: result })
+    const image = new File(['image'], 'carton.jpg', { type: 'image/jpeg' })
+
+    await expect(createManualCartonScan('10001', '7001', {
+      boxCode: 'RK#10-2', length: 40, width: 30, height: 20, weight: 5,
+      machineNo: 'MANUAL-ADMIN', measuredAt: '2026-08-12T14:00:00', scannedShipmentId: null,
+    }, image)).resolves.toEqual(result)
+    const [path, body, config] = vi.mocked(http.post).mock.calls[0]!
+    expect(path).toBe('/platform/v1/first-leg/inbounds/7001/measurement/manual-cartons')
+    expect(body).toBeInstanceOf(FormData)
+    expect((body as FormData).get('image')).toBe(image)
+    expect(config).toEqual({ params: { tenantId: '10001' }, headers: { 'Content-Type': 'multipart/form-data' } })
+  })
+})
diff --git a/src/modules/inbounds/measurement/api.ts b/src/modules/inbounds/measurement/api.ts
new file mode 100644
index 00000000..bbf33f12
--- /dev/null
+++ b/src/modules/inbounds/measurement/api.ts
@@ -0,0 +1,126 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import type {
+  InboundMeasurementDetail,
+  InboundMeasurementDraftSaved,
+  InboundMeasurementSubmitted,
+  CartonMeasurementResult,
+  ConfirmedPackageCountRequest,
+  SaveInboundMeasurementDraftRequest,
+  SubmitInboundMeasurementRequest,
+  UpdateMeasurementCalculationStrategyRequest,
+  MeasurementCalculationStrategyUpdated,
+  UpdateMeasurementOuterDimensionsRequest,
+  MeasurementOuterDimensionsUpdated,
+  ManualCartonScanRequest,
+} from './types'
+
+function measurementPath(inboundId: string) {
+  return `/platform/v1/first-leg/inbounds/${encodeURIComponent(inboundId)}/measurement`
+}
+
+export async function updateConfirmedPackageCount(
+  customerId: string,
+  inboundId: string,
+  itemId: string,
+  payload: ConfirmedPackageCountRequest,
+) {
+  const response = await http.put<ApiEnvelope<CartonMeasurementResult>, ApiEnvelope<CartonMeasurementResult>>(
+    `${measurementPath(inboundId)}/items/${segment(itemId)}/confirmed-package-count`,
+    payload,
+    { params: { tenantId: customerId } },
+  )
+  return unwrapApiResponse(response)
+}
+
+function segment(value: string) {
+  return encodeURIComponent(value)
+}
+
+export async function getInboundMeasurement(customerId: string, inboundId: string) {
+  // Device-scanned fields expected from the backend: originalPackageCount and
+  // items[].boxCode, machineNo, deviceMeasuredAt. Keep the response aligned with the backend OpenAPI.
+  const response = await http.get<ApiEnvelope<InboundMeasurementDetail>, ApiEnvelope<InboundMeasurementDetail>>(
+    measurementPath(inboundId),
+    // Calculation-mode saves use a sibling PUT endpoint. A cache may otherwise keep
+    // returning the pre-save measurement and make a successful update look failed.
+    { params: { tenantId: customerId, requestAt: Date.now() } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function saveInboundMeasurementDraft(
+  customerId: string,
+  inboundId: string,
+  payload: SaveInboundMeasurementDraftRequest,
+) {
+  const response = await http.put<ApiEnvelope<InboundMeasurementDraftSaved>, ApiEnvelope<InboundMeasurementDraftSaved>>(
+    `${measurementPath(inboundId)}/draft`,
+    payload,
+    { params: { tenantId: customerId } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function updateMeasurementCalculationStrategy(
+  customerId: string,
+  inboundId: string,
+  payload: UpdateMeasurementCalculationStrategyRequest,
+) {
+  const response = await http.put<ApiEnvelope<MeasurementCalculationStrategyUpdated>, ApiEnvelope<MeasurementCalculationStrategyUpdated>>(
+    `${measurementPath(inboundId)}/calculation-strategy`,
+    payload,
+    { params: { tenantId: customerId } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function updateMeasurementOuterDimensions(
+  customerId: string,
+  inboundId: string,
+  itemId: string,
+  payload: UpdateMeasurementOuterDimensionsRequest,
+) {
+  const response = await http.put<ApiEnvelope<MeasurementOuterDimensionsUpdated>, ApiEnvelope<MeasurementOuterDimensionsUpdated>>(
+    `${measurementPath(inboundId)}/items/${segment(itemId)}/outer-dimensions`,
+    payload,
+    { params: { tenantId: customerId } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function submitInboundMeasurement(
+  customerId: string,
+  inboundId: string,
+  payload: SubmitInboundMeasurementRequest,
+) {
+  const response = await http.post<ApiEnvelope<InboundMeasurementSubmitted>, ApiEnvelope<InboundMeasurementSubmitted>>(
+    `${measurementPath(inboundId)}/submit`,
+    payload,
+    { params: { tenantId: customerId } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function createManualCartonScan(
+  customerId: string,
+  inboundId: string,
+  payload: ManualCartonScanRequest,
+  image: File,
+) {
+  const data = new FormData()
+  data.append('data', new Blob([JSON.stringify(payload)], { type: 'application/json' }))
+  data.append('image', image)
+  const response = await http.post<ApiEnvelope<CartonMeasurementResult>, ApiEnvelope<CartonMeasurementResult>>(
+    `${measurementPath(inboundId)}/manual-cartons`,
+    data,
+    { params: { tenantId: customerId }, headers: { 'Content-Type': 'multipart/form-data' } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export function downloadInboundMeasurementImage(customerId: string, inboundId: string, fileId: string) {
+  return http.get<Blob, Blob>(
+    `/platform/v1/files/measurements/${segment(customerId)}/${segment(inboundId)}/${segment(fileId)}`,
+    { responseType: 'blob' },
+  )
+}
diff --git a/src/modules/inbounds/measurement/components/MeasurementEvidenceThumbnail.test.ts b/src/modules/inbounds/measurement/components/MeasurementEvidenceThumbnail.test.ts
new file mode 100644
index 00000000..fddc473c
--- /dev/null
+++ b/src/modules/inbounds/measurement/components/MeasurementEvidenceThumbnail.test.ts
@@ -0,0 +1,27 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/inbounds/measurement/components/MeasurementEvidenceThumbnail.vue'), 'utf8')
+const weightWrapperSource = readFileSync(resolve(process.cwd(), 'src/modules/inbounds/weight/components/WeightImageThumbnail.vue'), 'utf8')
+
+describe('MeasurementEvidenceThumbnail', () => {
+  it('uses the authenticated measurement thumbnail API with stale-request and object-url cleanup', () => {
+    expect(source).toContain("import { downloadWeightThumbnail } from '../../weight/api/weightOcr'")
+    expect(source).toContain('downloadWeightThumbnail(props.customerId, props.inboundId, props.fileId)')
+    expect(source).toContain('currentRequest !== requestId')
+    expect(source).toContain('URL.revokeObjectURL(imageUrl.value)')
+  })
+
+  it('renders explicit loading, failure and missing-file states', () => {
+    expect(source).toContain("fileId?: string | null")
+    expect(source).toContain("!fileId ? emptyText : failed ? '图片加载失败'")
+    expect(source).toContain(':disabled="!fileId"')
+  })
+
+  it('is also the evidence thumbnail used by the editable OCR workspace', () => {
+    expect(weightWrapperSource).toContain("import MeasurementEvidenceThumbnail from '../../measurement/components/MeasurementEvidenceThumbnail.vue'")
+    expect(weightWrapperSource).toContain('<MeasurementEvidenceThumbnail')
+    expect(weightWrapperSource).toContain('empty-text="未绑定称重图片"')
+  })
+})
diff --git a/src/modules/inbounds/measurement/components/MeasurementEvidenceThumbnail.vue b/src/modules/inbounds/measurement/components/MeasurementEvidenceThumbnail.vue
new file mode 100644
index 00000000..2943dd97
--- /dev/null
+++ b/src/modules/inbounds/measurement/components/MeasurementEvidenceThumbnail.vue
@@ -0,0 +1,79 @@
+<script setup lang="ts">
+import { onBeforeUnmount, ref, watch } from 'vue'
+import { ImageOff } from '@lucide/vue'
+import { downloadWeightThumbnail } from '../../weight/api/weightOcr'
+
+const props = withDefaults(defineProps<{
+  customerId: string
+  inboundId: string
+  fileId?: string | null
+  alt: string
+  emptyText?: string
+}>(), {
+  fileId: null,
+  emptyText: '未绑定测量图片',
+})
+
+defineEmits<{ open: [] }>()
+
+const imageUrl = ref('')
+const loading = ref(false)
+const failed = ref(false)
+let requestId = 0
+
+function releaseImage() {
+  if (imageUrl.value) URL.revokeObjectURL(imageUrl.value)
+  imageUrl.value = ''
+}
+
+async function load() {
+  const currentRequest = ++requestId
+  releaseImage()
+  failed.value = false
+  if (!props.fileId) {
+    loading.value = false
+    return
+  }
+  loading.value = true
+  try {
+    const blob = await downloadWeightThumbnail(props.customerId, props.inboundId, props.fileId)
+    if (currentRequest !== requestId) return
+    imageUrl.value = URL.createObjectURL(blob)
+  } catch {
+    if (currentRequest === requestId) failed.value = true
+  } finally {
+    if (currentRequest === requestId) loading.value = false
+  }
+}
+
+watch(() => [props.customerId, props.inboundId, props.fileId], load, { immediate: true })
+onBeforeUnmount(() => {
+  requestId += 1
+  releaseImage()
+})
+</script>
+
+<template>
+  <button
+    class="measurement-evidence-thumb"
+    type="button"
+    :disabled="!fileId"
+    :aria-label="fileId ? `查看${alt}` : emptyText"
+    @click="$emit('open')"
+  >
+    <img v-if="imageUrl" :src="imageUrl" :alt="alt" loading="lazy" />
+    <span v-else class="measurement-evidence-thumb__state" :class="{ 'is-loading': loading }">
+      <ImageOff v-if="failed || !fileId" :size="22" aria-hidden="true" />
+      <span>{{ !fileId ? emptyText : failed ? '图片加载失败' : '图片加载中' }}</span>
+    </span>
+  </button>
+</template>
+
+<style scoped>
+.measurement-evidence-thumb { display: block; width: 100%; min-width: 96px; aspect-ratio: 4 / 3; overflow: hidden; padding: 0; border: 1px solid var(--cc-border); border-radius: 6px; background: #f2f4f7; cursor: zoom-in; }
+.measurement-evidence-thumb:disabled { cursor: default; }
+.measurement-evidence-thumb img { display: block; width: 100%; height: 100%; object-fit: cover; }
+.measurement-evidence-thumb__state { display: grid; width: 100%; height: 100%; place-items: center; align-content: center; gap: 7px; padding: 8px; color: #667085; font-size: 12px; }
+.measurement-evidence-thumb__state.is-loading { color: #98a2b3; }
+.measurement-evidence-thumb:focus-visible { outline: 2px solid var(--cc-primary); outline-offset: 2px; }
+</style>
diff --git a/src/modules/inbounds/measurement/index.ts b/src/modules/inbounds/measurement/index.ts
new file mode 100644
index 00000000..37158724
--- /dev/null
+++ b/src/modules/inbounds/measurement/index.ts
@@ -0,0 +1,5 @@
+export { default as InboundMeasurementPanel } from './InboundMeasurementPanel.vue'
+export { default as InboundMeasurementDialog } from './InboundMeasurementDialog.vue'
+export { default as MeasurementEvidenceThumbnail } from './components/MeasurementEvidenceThumbnail.vue'
+export * from './api'
+export type * from './types'
diff --git a/src/modules/inbounds/measurement/measurementDensity.css b/src/modules/inbounds/measurement/measurementDensity.css
new file mode 100644
index 00000000..221be5af
--- /dev/null
+++ b/src/modules/inbounds/measurement/measurementDensity.css
@@ -0,0 +1,30 @@
+@media (min-width: 961px) {
+  .inbound-density.admin-density-dialog .measurement-dialog-weight { padding-bottom: var(--admin-space-4, 10px); }
+  .inbound-density.admin-density-dialog .measurement-section { padding: var(--admin-space-4, 10px) 0; }
+  .inbound-density.admin-density-dialog .measurement-summary-section { gap: var(--admin-space-3, 8px); }
+  .inbound-density.admin-density-dialog .measurement-section__heading { align-items: center; margin-bottom: var(--admin-space-3, 8px); }
+  .inbound-density.admin-density-dialog .measurement-metrics { grid-template-columns: repeat(5, minmax(0, 1fr)); }
+  .inbound-density.admin-density-dialog .measurement-metrics > div { min-height: var(--admin-row-height, 36px); padding: var(--admin-space-2, 6px) var(--admin-space-4, 10px); display: flex; align-items: baseline; gap: var(--admin-space-3, 8px); }
+  .inbound-density.admin-density-dialog .measurement-metrics dd { font-size: var(--admin-font-section, 14px); }
+  .inbound-density.admin-density-dialog .measurement-metrics small { font-size: var(--admin-font-caption, 12px); }
+  .inbound-density.admin-density-dialog .measurement-data-grid { gap: var(--admin-space-3, 8px) var(--admin-space-5, 12px); }
+  .inbound-density.admin-density-dialog .measurement-declaration { padding-top: var(--admin-space-3, 8px); }
+  .inbound-density.admin-density-dialog .measurement-declaration h4 { margin-bottom: var(--admin-space-2, 6px); font-size: var(--admin-font-body, 13px); }
+  .inbound-density.admin-density-dialog .measurement-panel > .el-alert { margin: var(--admin-space-3, 8px) 0; }
+  .inbound-density.admin-density-dialog .measurement-summary-header span { font-size: var(--admin-font-caption, 12px); }
+  .inbound-density.admin-density-dialog .measurement-table .el-table__header th { padding: var(--admin-space-1, 4px) 0; font-size: var(--admin-font-body, 13px); }
+  .inbound-density.admin-density-dialog .weight-heading { flex-wrap: wrap; gap: var(--admin-space-3, 8px); padding-bottom: var(--admin-space-3, 8px); }
+  .inbound-density.admin-density-dialog .weight-heading__actions { flex-wrap: wrap; gap: var(--admin-space-5, 12px); }
+  .inbound-density.admin-density-dialog .pallet-picker { width: 340px; }
+  .inbound-density.admin-density-dialog .weight-list { margin-top: var(--admin-space-3, 8px); }
+  .inbound-density.admin-density-dialog .weight-grid { grid-template-columns: repeat(auto-fill, minmax(420px, 1fr)); gap: var(--admin-space-3, 8px); }
+  .inbound-density.admin-density-dialog .weight-card { display: grid; grid-template-columns: 120px minmax(0, 1fr); gap: var(--admin-space-4, 10px); align-items: start; padding: var(--admin-space-3, 8px); border-radius: 2px; }
+  .inbound-density.admin-density-dialog .weight-card .weight-thumb { width: 120px; border-radius: 2px; }
+  .inbound-density.admin-density-dialog .weight-card__body { min-width: 0; padding: 0; text-align: left; }
+  .inbound-density.admin-density-dialog .weight-card__value { min-height: var(--admin-action-height, 28px); padding-right: 32px; text-align: left; }
+  .inbound-density.admin-density-dialog .weight-card__value strong { font-size: var(--admin-font-section, 14px); }
+  .inbound-density.admin-density-dialog .weight-card__facts { gap: 3px; margin-top: var(--admin-space-1, 4px); padding-top: var(--admin-space-1, 4px); }
+  .inbound-density.admin-density-dialog .weight-card__facts div { font-size: var(--admin-font-caption, 12px); }
+  .inbound-density.admin-density-dialog .weight-card__correct { width: auto; margin-top: var(--admin-space-2, 6px); }
+}
+
diff --git a/src/modules/inbounds/measurement/types.ts b/src/modules/inbounds/measurement/types.ts
new file mode 100644
index 00000000..1ff449d0
--- /dev/null
+++ b/src/modules/inbounds/measurement/types.ts
@@ -0,0 +1,231 @@
+export type MeasurementIdentifier = string
+
+export type InboundMeasurementProcessStatus =
+  | 'PREPARING'
+  | 'WAIT_MEASURE'
+  | 'MEASURING'
+  | 'MEASURE_PENDING'
+  | 'MEASURE_REJECTED'
+  | 'WAIT_PRICING'
+  | 'FEE_CONFIRMING'
+  | 'INBOUNDING'
+  | 'WAIT_PALLET'
+  | 'WAIT_PALLETIZE'
+  | 'WAIT_SPLIT'
+  | 'LOADING'
+  | 'LOADED'
+  | 'DELIVERED'
+  | 'VOIDED'
+
+export interface InboundMeasurementItem {
+  id: MeasurementIdentifier
+  inboundCode?: string | null
+  inboundDetailId?: MeasurementIdentifier | null
+  fbaShipmentNo?: string | null
+  scannedShipmentId?: string | null
+  boxCode: string | null
+  itemNo: string
+  boxSpecification: string
+  packageCount: number
+  lengthCm: number
+  widthCm: number
+  heightCm: number
+  girthCm: number | null
+  unitWeightKg: number
+  unitVolumeCbm: number | null
+  totalWeightKg: number | null
+  totalVolumeCbm: number | null
+  volumeWeightKg: number | null
+  intelligentImageFileId: MeasurementIdentifier | null
+  machineNo: string | null
+  deviceMeasuredAt: string | null
+  overLimitWarning: string | null
+  outerLengthCm: number | null
+  outerWidthCm: number | null
+  outerHeightCm: number | null
+  calculatedOuterLengthCm?: number | null
+  calculatedOuterWidthCm?: number | null
+  calculatedOuterHeightCm?: number | null
+  calculationRuleVersion?: string | null
+  chargeRuleId?: MeasurementIdentifier | null
+  coefficientMode?: 'ACTUAL' | 'ADD' | 'MULTIPLY' | null
+  remark: string | null
+}
+
+export interface InboundMeasurementDeclarationItem {
+  inboundDetailId: MeasurementIdentifier | null
+  itemNo: number | null
+  cargoName: string | null
+  packageCount: number | null
+  lengthCm: number | null
+  widthCm: number | null
+  heightCm: number | null
+}
+
+export interface InboundMeasurementDeclarationSnapshot {
+  referenceId: string | null
+  totalPackageCount: number | null
+  grossWeightKg: number | null
+  volumeCbm: number | null
+  goodsName: string | null
+  items: InboundMeasurementDeclarationItem[]
+}
+
+export interface InboundMeasurementWeightResult {
+  id: MeasurementIdentifier
+  fileId: MeasurementIdentifier
+  palletId: MeasurementIdentifier
+  palletCode: string
+  palletType: string
+  palletCapacityCbm: number
+  palletTareWeightKg: number
+  ocrProvider: string | null
+  ocrRawText: string | null
+  ocrWeightValue: number | null
+  ocrWeightUnit: string | null
+  confidence: number | null
+  adjustedWeightValue: number | null
+  adjustedWeightUnit: string | null
+  grossWeightKg: number | null
+  netWeightKg: number | null
+  recognitionStatus: string
+  adjustmentReason: string | null
+  adjustedBy: MeasurementIdentifier | null
+  adjustedAt: string | null
+  confirmedBy: MeasurementIdentifier | null
+  confirmedAt: string | null
+  version: number
+}
+
+export interface InboundMeasurementDetail {
+  inboundId: MeasurementIdentifier
+  inboundCode: string
+  companyName: string
+  channelCode: string | null
+  channelName: string | null
+  fulfillmentType?: string | null
+  expectedPalletCount?: number | null
+  processStatus: InboundMeasurementProcessStatus
+  measureReviewStatus: string | null
+  recommendedPalletType: string | null
+  reviewReason: string | null
+  reviewerId: MeasurementIdentifier | null
+  reviewerName: string | null
+  measurementId: MeasurementIdentifier | null
+  sourceType: string | null
+  measurementStatus: string | null
+  version: number | null
+  originalDocumentNo: string | null
+  originalGrossWeightKg: number | null
+  originalVolumeCbm: number | null
+  originalPackageCount: number | null
+  actualPackageCount: number | null
+  actualGrossWeightKg: number | null
+  actualNetWeightKg: number | null
+  actualVolumeCbm: number | null
+  volumeWeightKg: number | null
+  actualGoodsName: string | null
+  latestDeclaration?: InboundMeasurementDeclarationSnapshot | null
+  items: InboundMeasurementItem[]
+  weightResults: InboundMeasurementWeightResult[]
+}
+
+export interface SaveInboundMeasurementItemRequest {
+  inboundDetailId?: MeasurementIdentifier
+  boxCode?: string | null
+  itemNo: string
+  boxSpecification: string
+  packageCount: number
+  lengthCm: number
+  widthCm: number
+  heightCm: number
+  unitWeightKg?: number
+  intelligentImageFileId: MeasurementIdentifier | null
+  machineNo?: string | null
+  measuredAt?: string | null
+  overLimitWarning: string | null
+  outerLengthCm: number | null
+  outerWidthCm: number | null
+  outerHeightCm: number | null
+  chargeRuleId?: MeasurementIdentifier | null
+  coefficientMode?: 'ACTUAL' | 'ADD' | 'MULTIPLY' | null
+  remark: string | null
+}
+
+export interface SaveInboundMeasurementDraftRequest {
+  measurementId: MeasurementIdentifier | null
+  version: number
+  actualGoodsName: string | null
+  expectedPalletCount?: number | null
+  items: SaveInboundMeasurementItemRequest[]
+}
+
+export interface InboundMeasurementDraftSaved {
+  measurementId: MeasurementIdentifier
+  version: number
+  status: string
+}
+
+export interface UpdateMeasurementCalculationStrategyRequest {
+  measurementId: MeasurementIdentifier
+  version: number
+  coefficientMode: 'ACTUAL' | 'ADD' | 'MULTIPLY'
+  chargeRuleId?: MeasurementIdentifier | null
+}
+
+export interface MeasurementCalculationStrategyUpdated extends InboundMeasurementDraftSaved {
+  coefficientMode: 'ACTUAL' | 'ADD' | 'MULTIPLY'
+  chargeRuleId: MeasurementIdentifier | null
+}
+
+export interface UpdateMeasurementOuterDimensionsRequest {
+  measurementId: MeasurementIdentifier
+  version: number
+  outerLengthCm: number | null
+  outerWidthCm: number | null
+  outerHeightCm: number | null
+}
+
+export interface MeasurementOuterDimensionsUpdated extends InboundMeasurementDraftSaved {
+  itemId: MeasurementIdentifier
+}
+
+export interface ConfirmedPackageCountRequest {
+  measurementVersion: number
+  confirmedPackageCount: number
+}
+
+export interface CartonMeasurementResult {
+  measurementId: MeasurementIdentifier
+  measurementVersion: number
+  itemId: MeasurementIdentifier
+  boxCode: string
+  confirmedPackageCount: number
+}
+
+export interface ManualCartonScanRequest {
+  boxCode: string
+  length: number
+  width: number
+  height: number
+  weight: number | null
+  machineNo: string
+  measuredAt: string
+  scannedShipmentId: string | null
+}
+
+export interface SubmitInboundMeasurementRequest {
+  measurementId: MeasurementIdentifier
+  version: number
+}
+
+export interface InboundMeasurementSubmitted {
+  measurementId: MeasurementIdentifier
+  version: number
+  processStatus: string
+  measureReviewStatus: string
+  recommendedPalletType: string | null
+  feeId: MeasurementIdentifier | null
+  feeNo: string | null
+  feeStatus: string | null
+}
diff --git a/src/modules/inbounds/pages/InboundMeasurementsView.vue b/src/modules/inbounds/pages/InboundMeasurementsView.vue
new file mode 100644
index 00000000..e610eb87
--- /dev/null
+++ b/src/modules/inbounds/pages/InboundMeasurementsView.vue
@@ -0,0 +1,7 @@
+<script setup lang="ts">
+import InboundTaskList from '../components/InboundTaskList.vue'
+</script>
+
+<template>
+  <InboundTaskList mode="measurement" />
+</template>
diff --git a/src/modules/inbounds/pages/InboundOrdersView.test.ts b/src/modules/inbounds/pages/InboundOrdersView.test.ts
new file mode 100644
index 00000000..b4553a25
--- /dev/null
+++ b/src/modules/inbounds/pages/InboundOrdersView.test.ts
@@ -0,0 +1,359 @@
+import ElementPlus from 'element-plus'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { createPinia, setActivePinia } from 'pinia'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import InboundOrdersView from './InboundOrdersView.vue'
+import { listPlatformTenants, type PlatformTenantResource } from '@/modules/iam'
+import QueryToolbar from '@/shared/components/QueryToolbar.vue'
+import DataTable from '@/shared/components/DataTable.vue'
+import { listPlatformWarehouses } from '@/modules/warehouses'
+import { useAuthStore } from '@/core/auth/auth'
+import { downloadInboundCartonLabels, listPlatformInbounds } from '../core/api'
+import type { InboundOrderSummary } from '../core/types'
+
+const routerPush = vi.fn()
+
+vi.mock('vue-router', async (importOriginal) => ({
+  ...await importOriginal<typeof import('vue-router')>(),
+  useRouter: () => ({ push: routerPush }),
+}))
+
+vi.mock('../core/api', () => ({
+  downloadInboundCartonLabels: vi.fn(),
+  listPlatformInbounds: vi.fn(),
+}))
+
+vi.mock('@/modules/warehouses', () => ({
+  listPlatformWarehouses: vi.fn(),
+}))
+
+vi.mock('@/modules/iam', () => ({
+  listPlatformTenants: vi.fn(),
+}))
+
+const customers: PlatformTenantResource[] = [
+  { id: '10001', tenantCode: 'CUS-001', tenantName: '示例企业', status: 'ACTIVE', legalName: '示例企业有限公司', legalRepresentative: null, unifiedSocialCreditCode: null, contactName: null, contactPhone: null, contactEmail: null, servicePackage: null, contactWechat: null, salesOwnerName: null, paymentTermDays: null, enterpriseType: null, establishedDate: null, registeredCapital: null, registeredCapitalCurrency: null, registeredAddress: null, internalRemark: null, createdAt: null, approvedAt: null },
+  { id: '10002', tenantCode: 'CUS-002', tenantName: '第二客户', status: 'ACTIVE', legalName: null, legalRepresentative: null, unifiedSocialCreditCode: null, contactName: null, contactPhone: null, contactEmail: null, servicePackage: null, contactWechat: null, salesOwnerName: null, paymentTermDays: null, enterpriseType: null, establishedDate: null, registeredCapital: null, registeredCapitalCurrency: null, registeredAddress: null, internalRemark: null, createdAt: null, approvedAt: null },
+]
+
+const summary: InboundOrderSummary = {
+  id: '19001', tenantId: '10002', orderId: '18001', orderNo: 'ORD-001', inboundCode: 'RK-001', processStatus: 'WAIT_MEASURE',
+  orderStatusSnapshot: 'APPROVED', measureReviewStatus: 'PENDING', feeStatus: 'UNPRICED', feeReviewStatus: null,
+  notificationStatus: null, version: 1, expectedArrivalAt: '2026-08-04T10:00:00', customerId: '10001', customerName: '示例客户',
+  companyId: '10001', companyName: '示例企业', warehouseId: '20001', warehouseName: '义乌收货仓', deliveryWarehouseId: null,
+  deliveryWarehouseName: null, businessType: 'FBA', fulfillmentType: 'STANDARD', channelCode: 'SEA', channelName: '海运', taxMode: 'DDP', containerMode: null,
+  customsInspection: false, destinationType: 'FBA', destinationWarehouseId: '30001', destinationCode: 'ONT8', destinationName: 'ONT8',
+  holdFlag: false, currentHoldReason: null, totalPackageCount: 6, actualGrossWeightKg: 120, actualNetWeightKg: 110,
+  actualVolumeCbm: 1.2, volumeWeightKg: 200, chargeableWeightKg: 200, chargeableVolumeCbm: null, palletCount: 1, locationCodes: 'A-01',
+  measureCompletedAt: null, inboundedAt: null, expressCompanyCode: null, expressCompanyName: null, expressTrackingNo: null,
+  loadingStatus: null, containerNo: null, cabinetNo: null, vesselName: null, voyageNo: null, sailingAt: null, portArrivalAt: null,
+  createdAt: '2026-08-01T10:00:00', updatedAt: '2026-08-01T10:00:00',
+}
+
+enableAutoUnmount(afterEach)
+
+function mountPage() {
+  return mount(InboundOrdersView, {
+    attachTo: document.body,
+    global: { plugins: [ElementPlus] },
+  })
+}
+
+async function selectCustomer(wrapper: ReturnType<typeof mountPage>, customerId = '10001') {
+  await flushPromises()
+  const toolbar = wrapper.findComponent(QueryToolbar)
+  toolbar.vm.$emit('update:modelValue', { ...toolbar.props('modelValue'), customerId })
+  await flushPromises()
+  return toolbar
+}
+
+describe('InboundOrdersView', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    setActivePinia(createPinia())
+    useAuthStore().permissions = ['platform:firstleg:inbound:view']
+    vi.mocked(listPlatformInbounds).mockResolvedValue({ records: [summary], page: 1, size: 20, total: 1, pages: 1 })
+    vi.mocked(downloadInboundCartonLabels).mockResolvedValue(new Blob(['pdf'], { type: 'application/pdf' }))
+    vi.mocked(listPlatformTenants).mockResolvedValue({ records: customers, page: 1, size: 200, total: 2, pages: 1 })
+    vi.mocked(listPlatformWarehouses).mockResolvedValue({
+      records: [
+        { id: '20001', tenantId: '10001', warehouseCode: 'YIWU', internalCode: null, warehouseName: '义乌收货仓', warehouseType: 'DOMESTIC', countryCode: 'CN', timezone: 'Asia/Shanghai', contactName: null, contactPhone: null, contactEmail: null, status: 'ACTIVE', remark: null },
+        { id: 20002, tenantId: '10001', warehouseCode: 'B001', internalCode: null, warehouseName: '交货仓 B001', warehouseType: 'DOMESTIC', countryCode: 'CN', timezone: 'Asia/Shanghai', contactName: null, contactPhone: null, contactEmail: null, status: 'ACTIVE', remark: null },
+      ],
+      page: 1, size: 200, total: 2, pages: 1,
+    })
+  })
+
+  it('loads the customer-scoped list and renders the first-column view action', async () => {
+    const wrapper = mountPage()
+    await flushPromises()
+    const toolbar = wrapper.findComponent(QueryToolbar)
+    const customerField = (toolbar.props('fields') as Array<{ key: string; placeholder?: string }>).find((field) => field.key === 'customerId')
+    expect(customerField?.placeholder).toBe('全部客户')
+    expect((toolbar.props('modelValue') as { customerId: string }).customerId).toBe('')
+    expect(listPlatformInbounds).toHaveBeenCalledWith(undefined, expect.objectContaining({ page: 1, size: 20 }))
+    expect(listPlatformWarehouses).not.toHaveBeenCalled()
+    const requestsBeforeSearch = vi.mocked(listPlatformInbounds).mock.calls.length
+    toolbar.vm.$emit('search')
+    await flushPromises()
+    expect(vi.mocked(listPlatformInbounds).mock.calls).toHaveLength(requestsBeforeSearch + 1)
+    expect(listPlatformInbounds).toHaveBeenLastCalledWith(undefined, expect.objectContaining({ page: 1, size: 20 }))
+
+    const requestsBeforeCustomerChange = vi.mocked(listPlatformInbounds).mock.calls.length
+    await selectCustomer(wrapper)
+    expect(vi.mocked(listPlatformInbounds).mock.calls).toHaveLength(requestsBeforeCustomerChange)
+    expect(listPlatformWarehouses).toHaveBeenCalledWith(1, 200)
+    toolbar.vm.$emit('search')
+    await flushPromises()
+    expect(vi.mocked(listPlatformInbounds).mock.calls).toHaveLength(requestsBeforeCustomerChange + 1)
+    expect(listPlatformInbounds).toHaveBeenLastCalledWith('10001', expect.objectContaining({ page: 1, size: 20 }))
+    expect(listPlatformTenants).toHaveBeenCalledWith({ page: 1, size: 200, status: 'ACTIVE' })
+    const customerQueryField = (toolbar.props('fields') as Array<{ key: string; type?: string; props?: Record<string, unknown> }>).find((field) => field.key === 'customerId')
+    expect(customerQueryField?.type).toBe('select')
+    expect(customerQueryField?.props?.filterable).toBe(true)
+    expect(document.body.textContent).toContain('RK-001')
+    expect(document.body.textContent).toContain('查看')
+    expect(document.body.textContent).toContain('示例企业有限公司')
+    expect(document.body.textContent).not.toContain('租户')
+    expect(wrapper.find('.inbound-tabs .is-active').text()).toContain('全部')
+  })
+
+  it('keeps the customer filter name-only and does not add a customer-code input', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/inbounds/pages/InboundOrdersView.vue'), 'utf8')
+    const queryFieldsSource = source.slice(source.indexOf('const allQueryFields'), source.indexOf('const columns'))
+
+    expect(queryFieldsSource).toContain("key: 'customerId'")
+    expect(queryFieldsSource).toContain("type: 'select'")
+    expect(queryFieldsSource).toContain('filterable: true')
+    expect(queryFieldsSource).toContain('legalName?.trim() || customer.tenantName')
+    expect(queryFieldsSource).not.toContain('tenantCode')
+    expect(queryFieldsSource).not.toContain('客户编码')
+  })
+
+  it('uses backend-supported warehouse IDs from tenant-scoped options without coercing Long IDs', async () => {
+    const wrapper = mountPage()
+    const toolbar = await selectCustomer(wrapper)
+    toolbar.vm.$emit('update:modelValue', {
+      ...toolbar.props('modelValue'),
+      warehouseId: '20001',
+      deliveryWarehouseId: '20002',
+    })
+    toolbar.vm.$emit('search')
+    await flushPromises()
+    expect(listPlatformInbounds).toHaveBeenLastCalledWith('10001', expect.objectContaining({
+      warehouseId: '20001',
+      deliveryWarehouseId: '20002',
+    }))
+  })
+
+  it('keeps common filters compact and clears hidden advanced filters when collapsed', async () => {
+    const wrapper = mountPage()
+    const toolbar = await selectCustomer(wrapper)
+    const fieldKeys = () => (toolbar.props('fields') as Array<{ key: string }>).map((field) => field.key)
+    const widths = Object.fromEntries((toolbar.props('fields') as Array<{ key: string; width?: number }>).map((field) => [field.key, field.width]))
+    expect(widths.customerId).toBe(260)
+    expect(widths.processStatus).toBe(160)
+    expect(widths.inboundCode).toBe(220)
+    expect(widths.expectedArrivalRange).toBe(320)
+    expect(fieldKeys()).toContain('expectedArrivalRange')
+    expect(fieldKeys()).not.toContain('feeReviewStatus')
+
+    const advancedButton = () => wrapper.findAll('button').find((button) => button.text().includes('更多筛选') || button.text().includes('收起筛选'))
+    await advancedButton()?.trigger('click')
+    expect(fieldKeys()).toContain('feeReviewStatus')
+
+    toolbar.vm.$emit('update:modelValue', {
+      ...toolbar.props('modelValue'),
+      feeReviewStatus: 'PENDING',
+      destinationCode: 'ONT8',
+    })
+    await flushPromises()
+    const requestsBeforeCollapse = vi.mocked(listPlatformInbounds).mock.calls.length
+    await advancedButton()?.trigger('click')
+    await flushPromises()
+    expect(fieldKeys()).not.toContain('feeReviewStatus')
+    expect(vi.mocked(listPlatformInbounds).mock.calls).toHaveLength(requestsBeforeCollapse)
+    toolbar.vm.$emit('search')
+    await flushPromises()
+    expect(vi.mocked(listPlatformInbounds).mock.calls).toHaveLength(requestsBeforeCollapse + 1)
+    expect(listPlatformInbounds).toHaveBeenLastCalledWith('10001', expect.objectContaining({
+      feeReviewStatus: undefined,
+      destinationCode: undefined,
+    }))
+  })
+
+  it('passes the selected backend tab and routes view to the unified order detail page', async () => {
+    const wrapper = mountPage()
+    const toolbar = await selectCustomer(wrapper)
+    toolbar.vm.$emit('search')
+    await flushPromises()
+    const requestsBeforeTab = vi.mocked(listPlatformInbounds).mock.calls.length
+    ;[...document.querySelectorAll<HTMLButtonElement>('.inbound-tab')].find((button) => button.textContent?.includes('待审核'))?.click()
+    await flushPromises()
+    expect(vi.mocked(listPlatformInbounds).mock.calls).toHaveLength(requestsBeforeTab + 1)
+    expect(listPlatformInbounds).toHaveBeenLastCalledWith('10001', expect.objectContaining({ tab: 'WAIT_REVIEW', page: 1 }))
+    ;[...document.querySelectorAll<HTMLButtonElement>('button')].filter((button) => button.textContent?.trim() === '查看').at(-1)?.click()
+    await flushPromises()
+    expect(routerPush).toHaveBeenCalledWith({
+      name: 'unified-order-detail',
+      params: { orderId: '18001' },
+      query: { tenantId: '10002' },
+    })
+    expect(wrapper.find('[aria-label="入库单详情抽屉"]').exists()).toBe(false)
+    wrapper.unmount()
+  })
+
+  it('downloads carton labels from the stable server-side mapping', async () => {
+    const createObjectURL = vi.fn(() => 'blob:labels')
+    const revokeObjectURL = vi.fn()
+    vi.stubGlobal('URL', { createObjectURL, revokeObjectURL })
+    const click = vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(() => {})
+    const wrapper = mountPage()
+    await flushPromises()
+
+    ;[...document.querySelectorAll<HTMLButtonElement>('button')]
+      .filter((button) => button.textContent?.trim() === '打印箱唛').at(-1)?.click()
+    await flushPromises()
+
+    expect(downloadInboundCartonLabels).toHaveBeenCalledWith('10002', '19001')
+    expect(createObjectURL).toHaveBeenCalledOnce()
+    expect(revokeObjectURL).toHaveBeenCalledWith('blob:labels')
+    expect(click).toHaveBeenCalledOnce()
+    click.mockRestore()
+    vi.unstubAllGlobals()
+  })
+
+  it('does not expose row operations without the confirmed inbound view permission', async () => {
+    useAuthStore().permissions = []
+    const wrapper = mountPage()
+    await flushPromises()
+
+    expect(wrapper.find('.row-actions').exists()).toBe(false)
+    expect(wrapper.text()).toContain('无查看权限')
+    expect(wrapper.text()).not.toContain('打印箱唛')
+  })
+
+  it('uses the app header as the page title and exposes compact accessible status tabs', async () => {
+    const wrapper = mountPage()
+    await flushPromises()
+    expect(wrapper.find('.inbound-page-heading').exists()).toBe(false)
+    expect(wrapper.text()).not.toContain('所有处理均进入单票工作台完成')
+    const tabList = wrapper.find('[role="tablist"]')
+    const tabButtons = tabList.findAll('[role="tab"]')
+    const queryToolbar = wrapper.findComponent(QueryToolbar)
+    expect(tabList.attributes('aria-label')).toBe('入库单处理状态')
+    expect(tabList.element.closest('.table-toolbar')).not.toBeNull()
+    expect(queryToolbar.element.compareDocumentPosition(tabList.element) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy()
+    expect(tabButtons).toHaveLength(5)
+    const toolbarRows = wrapper.find('.table-toolbar').element.children
+    expect(toolbarRows[0].classList.contains('table-tabs-row')).toBe(true)
+    expect(toolbarRows[1].classList.contains('inbound-stats-row')).toBe(true)
+    expect(toolbarRows).toHaveLength(2)
+    expect(wrapper.findComponent(DataTable).find('.data-table__pagination-left').text()).toContain('当前显示 1 条 · 共 1 条')
+    const dataTableToolbarStart = wrapper.findComponent(DataTable).find('.data-table__toolbar-start')
+    expect(dataTableToolbarStart.exists() ? dataTableToolbarStart.text() : '').not.toContain('入库单列表')
+    expect(wrapper.text()).not.toContain('刷新')
+    expect(wrapper.text()).not.toContain('全部入库单')
+    expect(tabButtons[0].attributes('aria-selected')).toBe('true')
+    expect(tabButtons[0].attributes('tabindex')).toBe('0')
+    await tabButtons[0].trigger('keydown', { key: 'ArrowRight' })
+    await flushPromises()
+    expect(tabButtons[1].attributes('aria-selected')).toBe('true')
+    expect(listPlatformInbounds).toHaveBeenLastCalledWith(undefined, expect.objectContaining({ tab: 'WAIT_MEASURE', page: 1 }))
+  })
+
+  it('shows an actionable list error and recovers on retry', async () => {
+    vi.mocked(listPlatformInbounds).mockRejectedValueOnce(new Error('network down')).mockResolvedValueOnce({ records: [summary], page: 1, size: 20, total: 1, pages: 1 })
+    const wrapper = mountPage()
+    await flushPromises()
+    expect(document.body.textContent).toContain('入库单暂时无法加载')
+    ;[...document.querySelectorAll<HTMLButtonElement>('button')].find((button) => button.textContent?.trim() === '重新加载')?.click()
+    await flushPromises()
+    expect(listPlatformInbounds).toHaveBeenCalledTimes(2)
+    expect(document.body.textContent).toContain('RK-001')
+  })
+
+  it('updates customer-dependent options without querying until search', async () => {
+    const wrapper = mountPage()
+    const toolbar = await selectCustomer(wrapper)
+    toolbar.vm.$emit('search')
+    await flushPromises()
+    const requestsBeforeCustomerChange = vi.mocked(listPlatformInbounds).mock.calls.length
+    toolbar.vm.$emit('update:modelValue', { ...toolbar.props('modelValue'), customerId: '10002' })
+    await flushPromises()
+    expect(vi.mocked(listPlatformInbounds).mock.calls).toHaveLength(requestsBeforeCustomerChange)
+    toolbar.vm.$emit('search')
+    await flushPromises()
+    expect(vi.mocked(listPlatformInbounds).mock.calls).toHaveLength(requestsBeforeCustomerChange + 1)
+    expect(listPlatformInbounds).toHaveBeenLastCalledWith('10002', expect.objectContaining({ page: 1 }))
+    expect(listPlatformWarehouses).toHaveBeenLastCalledWith(1, 200)
+  })
+
+  it('resets to all customers without sending an empty backend tenant ID', async () => {
+    const wrapper = mountPage()
+    const toolbar = await selectCustomer(wrapper)
+    const requestsBeforeReset = vi.mocked(listPlatformInbounds).mock.calls.length
+    const resetButton = wrapper.findAll('button').find((button) => button.text().includes('重置'))
+    await resetButton?.trigger('click')
+    await flushPromises()
+    expect((toolbar.props('modelValue') as { customerId: string }).customerId).toBe('')
+    expect(vi.mocked(listPlatformInbounds).mock.calls).toHaveLength(requestsBeforeReset + 1)
+    expect(listPlatformInbounds).toHaveBeenLastCalledWith(undefined, expect.objectContaining({ page: 1 }))
+    expect(document.body.textContent).not.toContain('请选择所属企业')
+    expect(document.body.textContent).not.toContain('请选择客户')
+  })
+
+  it('loads another full-data page without a customer filter', async () => {
+    vi.mocked(listPlatformInbounds).mockResolvedValue({ records: [summary], page: 1, size: 20, total: 60, pages: 3 })
+    const wrapper = mountPage()
+    await flushPromises()
+    const requestsBeforePage = vi.mocked(listPlatformInbounds).mock.calls.length
+    wrapper.findComponent(DataTable).vm.$emit('update:page', 2)
+    await flushPromises()
+    expect(vi.mocked(listPlatformInbounds).mock.calls).toHaveLength(requestsBeforePage + 1)
+    expect(listPlatformInbounds).toHaveBeenLastCalledWith(undefined, expect.objectContaining({ page: 2, size: 20 }))
+  })
+
+  it('keeps the operation column first and follows the prototype field order with backend-backed columns', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/inbounds/pages/InboundOrdersView.vue'), 'utf8')
+    const toolbarSource = readFileSync(resolve(process.cwd(), 'src/shared/components/QueryToolbar.vue'), 'utf8')
+    const columnSource = source.slice(source.indexOf('const columns:'))
+    const operation = columnSource.indexOf("key: 'actions'")
+    const inboundCode = columnSource.indexOf("key: 'inboundCode'")
+    const processStatus = columnSource.indexOf("key: 'processStatus'")
+    const orderStatus = columnSource.indexOf("key: 'orderStatus'")
+    const measureReview = columnSource.indexOf("key: 'measureReviewStatus'")
+    const feeStatus = columnSource.indexOf("key: 'feeStatus'")
+    const feeReviewStatus = columnSource.indexOf("key: 'feeReviewStatus'")
+    const customer = columnSource.indexOf("key: 'customerName'")
+    const warehouse = columnSource.indexOf("key: 'warehouseName'")
+    expect(operation).toBeGreaterThan(-1)
+    expect(operation).toBeLessThan(inboundCode)
+    expect(inboundCode).toBeLessThan(processStatus)
+    expect(processStatus).toBeLessThan(orderStatus)
+    expect(orderStatus).toBeLessThan(measureReview)
+    expect(measureReview).toBeLessThan(feeStatus)
+    expect(feeStatus).toBeLessThan(feeReviewStatus)
+    expect(feeReviewStatus).toBeLessThan(customer)
+    expect(customer).toBeLessThan(warehouse)
+    expect(columnSource).toContain("fixed: 'left'")
+    expect(columnSource).toContain("{ key: 'processStatus', label: '入库流程状态'")
+    expect(columnSource).toContain("{ key: 'orderStatus', label: '订单状态'")
+    expect(columnSource).toContain("{ key: 'feeStatus', label: '费用状态'")
+    expect(columnSource).toContain("{ key: 'feeReviewStatus', label: '费用审核状态'")
+    expect(source).toContain('<template #processStatus="{ row }">')
+    expect(source).toContain('<template #feeReviewStatus="{ row }">')
+    expect(source).toContain("access.can('platform:firstleg:inbound:view')")
+    expect(source).toContain('preference-key="inbound-orders-table"')
+    expect(columnSource.match(/defaultVisible: false/g)?.length).toBeGreaterThanOrEqual(25)
+    expect(toolbarSource).toMatch(/@media \(max-width: 720px\)[\s\S]*width: 100%/)
+    expect(source).toContain('name: \'unified-order-detail\'')
+    expect(source).toContain(':disabled="!(row as InboundOrderSummary).orderId"')
+    expect(source).toContain('<ClipboardCheck :size="15" />处理')
+    expect(source).toContain('<el-button size="small" plain type="primary"')
+    expect(source).not.toContain('<el-button link type="primary" @click="openDetail(row as InboundOrderSummary)">')
+    expect(source).toContain('@media (max-width: 360px) { .inbound-tab { padding-inline: 12px; } .row-actions { align-items: stretch; flex-direction: column; }')
+  })
+})
diff --git a/src/modules/inbounds/pages/InboundOrdersView.vue b/src/modules/inbounds/pages/InboundOrdersView.vue
new file mode 100644
index 00000000..5fe1610c
--- /dev/null
+++ b/src/modules/inbounds/pages/InboundOrdersView.vue
@@ -0,0 +1,496 @@
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import { useRouter } from 'vue-router'
+import { ElMessage } from 'element-plus'
+import { ChevronDown, ChevronUp, ClipboardCheck, Eye, Link2, Printer, RefreshCw, SlidersHorizontal } from '@lucide/vue'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import InboundCodeRelationshipDialog from '@/shared/components/InboundCodeRelationshipDialog.vue'
+import LineClampText from '@/shared/components/LineClampText.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import { firstLegBusinessTypeLabel, firstLegContainerModeLabel, firstLegDestinationTypeLabel, firstLegTaxModeLabel } from '@/shared/utils/firstLegBusinessLabels'
+import { listPlatformTenants, type PlatformTenantResource } from '@/modules/iam'
+import { listPlatformWarehouses } from '@/modules/warehouses'
+import { downloadInboundCartonLabels, listPlatformInbounds } from '../core/api'
+import type { InboundListTab, InboundOrderSummary } from '../core/types'
+import { inboundFeeStatusLabels, inboundLoadingStatusLabels, inboundOrderStatusLabels, inboundProcessStatusLabels, inboundReviewStatusLabels, inboundStatusLabel } from '../status'
+
+type FilterModel = QueryModel & {
+  customerId: string
+  inboundCode: string
+  warehouseId: string
+  deliveryWarehouseId: string
+  processStatus: string
+  orderStatus: string
+  measureReviewStatus: string
+  customerName: string
+  destinationCode: string
+  feeStatus: string
+  feeReviewStatus: string
+  holdFlag: string
+  expectedArrivalRange: string[]
+}
+
+const router = useRouter()
+const access = useAccessPreviewStore()
+const tab = ref<InboundListTab | ''>('')
+const page = ref(1)
+const pageSize = ref(20)
+const loading = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const printingInboundId = ref('')
+const relationshipDialogOpen = ref(false)
+const relationshipDialogInboundCode = ref('')
+const result = ref({ records: [] as InboundOrderSummary[], total: 0 })
+const filters = ref<FilterModel>({ customerId: '', inboundCode: '', warehouseId: '', deliveryWarehouseId: '', processStatus: '', orderStatus: '', measureReviewStatus: '', customerName: '', destinationCode: '', feeStatus: '', feeReviewStatus: '', holdFlag: '', expectedArrivalRange: [] })
+const appliedFilters = ref<FilterModel>({ ...filters.value, expectedArrivalRange: [] })
+const selectedCustomerId = ref('')
+const appliedCustomerId = ref('')
+const customers = ref<PlatformTenantResource[]>([])
+const customersLoading = ref(false)
+const customerLoadError = ref<ApiErrorDetails | null>(null)
+const warehouseOptions = ref<Array<{ label: string; value: string }>>([])
+const warehousesLoading = ref(false)
+const warehousesUnavailable = ref(false)
+const showAdvancedFilters = ref(false)
+let loadRequestId = 0
+let customerRequestId = 0
+let warehouseRequestId = 0
+let disposed = false
+
+const tabs: Array<{ value: InboundListTab | ''; label: string; description: string }> = [
+  { value: '', label: '全部', description: '全部入库单' },
+  { value: 'WAIT_MEASURE', label: '待测量', description: '等待测量或补正' },
+  { value: 'WAIT_REVIEW', label: '待审核', description: '等待测量审核' },
+  { value: 'WAIT_FEE_SEND', label: '待费用/入库', description: '等待费用编排完成' },
+  { value: 'WAIT_SPLIT', label: '待分柜', description: '测量审核完成，等待分柜；费用可继续维护' },
+]
+
+const advancedFilterKeys = new Set(['orderStatus', 'feeReviewStatus', 'customerName', 'destinationCode', 'holdFlag'])
+
+const allQueryFields = computed<QueryField[]>(() => [
+  {
+    key: 'customerId',
+    type: 'select',
+    label: '所属企业',
+    width: 260,
+    placeholder: customerLoadError.value ? '所属企业加载失败' : customersLoading.value ? '正在加载客户' : '全部客户',
+    options: customers.value.map((customer) => ({
+      value: String(customer.id),
+      label: customer.legalName?.trim() || customer.tenantName,
+    })),
+    props: { 'aria-label': '所属企业', loading: customersLoading.value, filterable: true, disabled: Boolean(customerLoadError.value) || customers.value.length === 0 },
+  },
+  { key: 'warehouseId', type: 'select', width: 180, label: '定位仓库', placeholder: warehousesUnavailable.value ? '定位仓库加载失败' : '定位仓库', options: warehouseOptions.value, props: { 'aria-label': '定位仓库', loading: warehousesLoading.value, filterable: true, disabled: !selectedCustomerId.value || warehousesUnavailable.value } },
+  { key: 'deliveryWarehouseId', type: 'select', width: 180, label: '交货仓', placeholder: warehousesUnavailable.value ? '交货仓加载失败' : '交货仓', options: warehouseOptions.value, props: { 'aria-label': '交货仓', loading: warehousesLoading.value, filterable: true, disabled: !selectedCustomerId.value || warehousesUnavailable.value } },
+  { key: 'inboundCode', type: 'input', width: 220, label: '入仓码', placeholder: '入仓码' },
+  { key: 'processStatus', type: 'select', width: 160, label: '流程状态', placeholder: '流程状态', options: [
+    { label: '待测量', value: 'WAIT_MEASURE' }, { label: '测量中', value: 'MEASURING' },
+    { label: '待测量审核', value: 'MEASURE_PENDING' }, { label: '测量已驳回', value: 'MEASURE_REJECTED' },
+    { label: '待计费', value: 'WAIT_PRICING' }, { label: '费用处理中', value: 'FEE_CONFIRMING' },
+    { label: '入库处理中', value: 'INBOUNDING' }, { label: '待分柜', value: 'WAIT_SPLIT' }, { label: '已作废', value: 'VOIDED' },
+  ] },
+  { key: 'orderStatus', type: 'select', width: 180, label: '订单状态', placeholder: '全部订单状态', options: Object.entries(inboundOrderStatusLabels).map(([value, label]) => ({ value, label })) },
+  { key: 'measureReviewStatus', type: 'select', width: 160, label: '测量审核状态', placeholder: '测量审核状态', options: [
+    { label: '待审核', value: 'PENDING' }, { label: '审核通过', value: 'APPROVED' }, { label: '审核驳回', value: 'REJECTED' },
+  ] },
+  { key: 'feeStatus', type: 'select', width: 160, label: '费用状态', placeholder: '费用状态', options: [
+    { label: '未计费', value: 'UNPRICED' }, { label: '已试算', value: 'CALCULATED' },
+    { label: '已确认', value: 'CONFIRMED' }, { label: '已发送', value: 'SENT' }, { label: '已作废', value: 'VOIDED' },
+  ] },
+  { key: 'feeReviewStatus', type: 'select', width: 180, label: '费用审核状态', placeholder: '全部审核状态', options: Object.entries(inboundReviewStatusLabels).map(([value, label]) => ({ value, label })) },
+  { key: 'customerName', type: 'input', width: 260, label: '客户名称', placeholder: '客户名称' },
+  { key: 'destinationCode', type: 'input', width: 220, label: '目的仓编码', placeholder: '目的仓编码' },
+  { key: 'holdFlag', type: 'select', width: 160, label: '挂起状态', placeholder: '挂起状态', options: [{ label: '已挂起', value: 'true' }, { label: '未挂起', value: 'false' }] },
+  { key: 'expectedArrivalRange', type: 'daterange', width: 320, label: '预计到达日期', placeholder: '预计到达日期' },
+])
+
+const queryFields = computed(() => showAdvancedFilters.value
+  ? allQueryFields.value
+  : allQueryFields.value.filter((field) => !advancedFilterKeys.has(field.key)))
+
+const columns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 228, fixed: 'left', slotName: 'actions' },
+  { key: 'inboundCode', label: '入仓码', minWidth: 166, slotName: 'inbound' },
+  { key: 'processStatus', label: '入库流程状态', minWidth: 132, slotName: 'processStatus' },
+  { key: 'orderStatus', label: '订单状态', minWidth: 120, slotName: 'orderStatus' },
+  { key: 'measureReviewStatus', label: '测量数据审核状态', minWidth: 142, slotName: 'measureReviewStatus' },
+  { key: 'expectedArrivalAt', label: '预计到达时间', minWidth: 164, slotName: 'expectedArrivalAt' },
+  { key: 'feeStatus', label: '费用状态', minWidth: 112, slotName: 'feeStatus' },
+  { key: 'feeReviewStatus', label: '费用审核状态', minWidth: 132, slotName: 'feeReviewStatus' },
+  { key: 'customerName', label: '客户', minWidth: 142, slotName: 'customerName' },
+  { key: 'warehouseName', label: '仓库', minWidth: 140, slotName: 'warehouseName' },
+  { key: 'deliveryWarehouseName', label: '交货仓', minWidth: 140, slotName: 'deliveryWarehouseName' },
+  { key: 'loadingStatus', label: '配载状态', minWidth: 110, slotName: 'loadingStatus', defaultVisible: false },
+  { key: 'holdFlag', label: '是否扣货', width: 96, slotName: 'holdFlag', defaultVisible: false },
+  { key: 'currentHoldReason', label: '扣货理由', minWidth: 150, slotName: 'currentHoldReason', defaultVisible: false },
+  { key: 'containerNo', label: '集装箱号', minWidth: 132, slotName: 'containerNo', defaultVisible: false },
+  { key: 'cabinetNo', label: '柜号', minWidth: 118, slotName: 'cabinetNo', defaultVisible: false },
+  { key: 'companyName', label: '公司', minWidth: 160, slotName: 'companyName', defaultVisible: false },
+  { key: 'businessType', label: '业务类型', minWidth: 112, slotName: 'businessType', defaultVisible: false },
+  { key: 'channelName', label: '渠道', minWidth: 138, slotName: 'channelName', defaultVisible: false },
+  { key: 'taxMode', label: '买单/退税', minWidth: 108, slotName: 'taxMode', defaultVisible: false },
+  { key: 'containerMode', label: '是否整柜', minWidth: 108, slotName: 'containerMode', defaultVisible: false },
+  { key: 'customsInspection', label: '商检验', width: 92, slotName: 'customsInspection', defaultVisible: false },
+  { key: 'sailingAt', label: '开船时间', minWidth: 164, slotName: 'sailingAt', defaultVisible: false },
+  { key: 'portArrivalAt', label: '到港时间', minWidth: 164, slotName: 'portArrivalAt', defaultVisible: false },
+  { key: 'totalPackageCount', label: '总箱数', width: 90, slotName: 'totalPackageCount', defaultVisible: false },
+  { key: 'actualGrossWeightKg', label: '总毛重(T.K.GW)', minWidth: 136, slotName: 'actualGrossWeightKg', defaultVisible: false },
+  { key: 'chargeableWeightKg', label: '计费毛重', minWidth: 112, slotName: 'chargeableWeightKg', defaultVisible: false },
+  { key: 'actualVolumeCbm', label: '总体积(m³)', minWidth: 118, slotName: 'actualVolumeCbm', defaultVisible: false },
+  { key: 'chargeableVolumeCbm', label: '计费体积(m³)', minWidth: 128, slotName: 'chargeableVolumeCbm', defaultVisible: false },
+  { key: 'palletCount', label: '总托盘数', width: 100, slotName: 'palletCount', defaultVisible: false },
+  { key: 'locationCodes', label: '库位位置', minWidth: 124, slotName: 'locationCodes', defaultVisible: false },
+  { key: 'volumeWeightKg', label: '总材积重', minWidth: 110, slotName: 'volumeWeightKg', defaultVisible: false },
+  { key: 'actualNetWeightKg', label: '总净重(T.K.NW)', minWidth: 136, slotName: 'actualNetWeightKg', defaultVisible: false },
+  { key: 'destinationType', label: '目的仓类型', minWidth: 112, slotName: 'destinationType', defaultVisible: false },
+  { key: 'destinationName', label: '目的仓', minWidth: 132, slotName: 'destinationName', defaultVisible: false },
+  { key: 'measureCompletedAt', label: '测量完成时间', minWidth: 164, slotName: 'measureCompletedAt', defaultVisible: false },
+  { key: 'inboundedAt', label: '入库完成时间', minWidth: 164, slotName: 'inboundedAt', defaultVisible: false },
+  { key: 'expressCompanyName', label: '快递公司', minWidth: 120, slotName: 'expressCompanyName', defaultVisible: false },
+  { key: 'expressTrackingNo', label: '快递单号', minWidth: 150, slotName: 'expressTrackingNo', defaultVisible: false },
+  { key: 'createdAt', label: '创建日期', minWidth: 164, slotName: 'createdAt', defaultVisible: false },
+]
+
+const selectedCustomerName = computed(() => {
+  const customer = customers.value.find((item) => String(item.id) === appliedCustomerId.value)
+  return customer?.legalName?.trim() || customer?.tenantName?.trim() || '全部客户'
+})
+const listEmptyText = '暂无符合条件的入库单'
+const currentPageCount = computed(() => result.value.records.length)
+const aggregateStats = computed(() => {
+  const records = result.value.records
+  return {
+    packages: records.reduce((total, item) => total + (item.totalPackageCount || 0), 0),
+    grossWeight: records.reduce((total, item) => total + (item.actualGrossWeightKg || 0), 0),
+    chargeableWeight: records.reduce((total, item) => total + (item.chargeableWeightKg || 0), 0),
+    volume: records.reduce((total, item) => total + (item.actualVolumeCbm || 0), 0),
+  }
+})
+
+function queryValue(value: string) { return value.trim() || undefined }
+function handleTabKeydown(event: KeyboardEvent, currentIndex: number) {
+  const lastIndex = tabs.length - 1
+  let nextIndex = currentIndex
+  if (event.key === 'ArrowRight') nextIndex = currentIndex === lastIndex ? 0 : currentIndex + 1
+  else if (event.key === 'ArrowLeft') nextIndex = currentIndex === 0 ? lastIndex : currentIndex - 1
+  else if (event.key === 'Home') nextIndex = 0
+  else if (event.key === 'End') nextIndex = lastIndex
+  else return
+  event.preventDefault()
+  tab.value = tabs[nextIndex].value
+  const tabButtons = (event.currentTarget as HTMLElement).parentElement?.querySelectorAll<HTMLElement>('[role="tab"]')
+  tabButtons?.[nextIndex]?.focus()
+}
+function dateParam(value: string | undefined, end = false) {
+  if (!value) return undefined
+  return `${value}T${end ? '23:59:59' : '00:00:00'}`
+}
+
+async function loadWarehouseOptions() {
+  const requestId = ++warehouseRequestId
+  warehouseOptions.value = []
+  warehousesUnavailable.value = false
+  if (!selectedCustomerId.value) {
+    warehousesLoading.value = false
+    return
+  }
+  warehousesLoading.value = true
+  try {
+    const response = await listPlatformWarehouses(1, 200)
+    if (disposed || requestId !== warehouseRequestId) return
+    warehouseOptions.value = response.records.map((warehouse) => ({
+      label: `${warehouse.warehouseName} · ${warehouse.warehouseCode}`,
+      value: String(warehouse.id),
+    }))
+  } catch {
+    if (disposed || requestId !== warehouseRequestId) return
+    warehousesUnavailable.value = true
+  } finally {
+    if (!disposed && requestId === warehouseRequestId) warehousesLoading.value = false
+  }
+}
+
+async function loadCustomers() {
+  const requestId = ++customerRequestId
+  customersLoading.value = true
+  customerLoadError.value = null
+  try {
+    const records: PlatformTenantResource[] = []
+    let currentPage = 1
+    let pages = 1
+    do {
+      const response = await listPlatformTenants({ page: currentPage, size: 200, status: 'ACTIVE' })
+      records.push(...response.records)
+      pages = Math.max(1, response.pages)
+      currentPage += 1
+    } while (currentPage <= pages)
+    if (disposed || requestId !== customerRequestId) return
+    customers.value = records
+  } catch (error) {
+    if (disposed || requestId !== customerRequestId) return
+    customers.value = []
+    customerLoadError.value = getApiErrorDetails(error, '客户列表加载失败，暂时无法按所属企业筛选；入库单仍按全部客户查询')
+  } finally {
+    if (!disposed && requestId === customerRequestId) customersLoading.value = false
+  }
+}
+
+async function loadInbounds() {
+  const requestId = ++loadRequestId
+  loading.value = true
+  loadError.value = null
+  const applied = appliedFilters.value
+  const range = applied.expectedArrivalRange
+  try {
+    const response = await listPlatformInbounds(appliedCustomerId.value || undefined, {
+      page: page.value,
+      size: pageSize.value,
+      tab: tab.value || undefined,
+      inboundCode: queryValue(applied.inboundCode),
+      warehouseId: queryValue(applied.warehouseId),
+      deliveryWarehouseId: queryValue(applied.deliveryWarehouseId),
+      processStatus: queryValue(applied.processStatus),
+      orderStatus: queryValue(applied.orderStatus),
+      measureReviewStatus: queryValue(applied.measureReviewStatus),
+      customerName: queryValue(applied.customerName),
+      destinationCode: queryValue(applied.destinationCode),
+      feeStatus: queryValue(applied.feeStatus),
+      feeReviewStatus: queryValue(applied.feeReviewStatus),
+      holdFlag: applied.holdFlag === '' ? undefined : applied.holdFlag === 'true',
+      expectedArrivalFrom: dateParam(range?.[0]),
+      expectedArrivalTo: dateParam(range?.[1], true),
+    })
+    if (disposed || requestId !== loadRequestId) return
+    result.value = { records: response.records, total: response.total }
+  } catch (error) {
+    if (disposed || requestId !== loadRequestId) return
+    loadError.value = getApiErrorDetails(error, '入库单加载失败')
+  } finally {
+    if (!disposed && requestId === loadRequestId) loading.value = false
+  }
+}
+
+function applyFilters() {
+  appliedFilters.value = { ...filters.value, expectedArrivalRange: [...filters.value.expectedArrivalRange] }
+  appliedCustomerId.value = selectedCustomerId.value
+  if (page.value === 1) void loadInbounds()
+  else page.value = 1
+}
+
+function openDetail(row: InboundOrderSummary) {
+  if (!row.orderId) {
+    ElMessage.warning('该入库单尚未关联订单，暂时无法查看订单详情')
+    return
+  }
+  void router.push({ name: 'unified-order-detail', params: { orderId: row.orderId }, query: { tenantId: row.tenantId } })
+}
+function openRelationship(row: InboundOrderSummary) { const code = row.inboundCode?.trim(); if (!code) return; relationshipDialogInboundCode.value = code; relationshipDialogOpen.value = true }
+async function printCartonLabels(row: InboundOrderSummary) {
+  if (printingInboundId.value) return
+  printingInboundId.value = row.id
+  try {
+    const blob = await downloadInboundCartonLabels(row.tenantId, row.id)
+    const url = URL.createObjectURL(blob)
+    const anchor = document.createElement('a')
+    anchor.href = url
+    anchor.download = `${row.inboundCode || '入仓码待补充'}-${row.totalPackageCount || '整单'}件-箱唛.pdf`
+    anchor.click()
+    URL.revokeObjectURL(url)
+    ElMessage.success('箱唛已生成，重复打印将继续使用原箱号')
+  } catch (error) {
+    ElMessage.error(getApiErrorDetails(error, '箱唛生成失败').message)
+  } finally {
+    printingInboundId.value = ''
+  }
+}
+function formatNumber(value: number | null, digits = 3) { return value === null ? '—' : value.toFixed(digits) }
+function formatAggregate(value: number, digits = 3) {
+  if (!Number.isFinite(value)) return '0'
+  return value.toLocaleString('zh-CN', { maximumFractionDigits: digits })
+}
+function formatDate(value: string | null) {
+  if (!value) return '—'
+  const date = new Date(value)
+  return Number.isNaN(date.getTime()) ? value : date.toLocaleString('zh-CN', { hour12: false })
+}
+function text(value: string | number | null | undefined) { return value === null || value === undefined || value === '' ? '—' : String(value) }
+function statusLabel(status: string) {
+  return inboundStatusLabel(status, inboundProcessStatusLabels, '未知状态')
+}
+function statusType(status: string) {
+  if (status === 'WAIT_SPLIT') return 'success'
+  if (status === 'MEASURE_REJECTED' || status === 'VOIDED') return 'danger'
+  if (status === 'MEASURING' || status === 'INBOUNDING') return 'info'
+  return 'warning'
+}
+function codeLabel(status: string | null | undefined, labels: Record<string, string>) { return inboundStatusLabel(status, labels) }
+const measureReviewLabels = inboundReviewStatusLabels
+const feeStatusLabels = inboundFeeStatusLabels
+const loadingStatusLabels = inboundLoadingStatusLabels
+function resetFilters() {
+  selectedCustomerId.value = ''
+  showAdvancedFilters.value = false
+  filters.value = { ...filters.value, customerId: '', warehouseId: '', deliveryWarehouseId: '' }
+  warehouseOptions.value = []
+  warehousesUnavailable.value = false
+  applyFilters()
+}
+
+function toggleAdvancedFilters() {
+  if (!showAdvancedFilters.value) {
+    showAdvancedFilters.value = true
+    return
+  }
+  showAdvancedFilters.value = false
+  filters.value = {
+    ...filters.value,
+    orderStatus: '',
+    feeReviewStatus: '',
+    customerName: '',
+    destinationCode: '',
+    holdFlag: '',
+  }
+}
+
+watch(() => filters.value.customerId, (customerId) => {
+  if (customerId === selectedCustomerId.value) return
+  selectedCustomerId.value = customerId
+  filters.value = { ...filters.value, warehouseId: '', deliveryWarehouseId: '' }
+  void loadWarehouseOptions()
+})
+watch(tab, () => { if (page.value === 1) void loadInbounds(); else page.value = 1 })
+watch([page, pageSize], () => { void loadInbounds() })
+onMounted(() => { void loadCustomers(); void loadInbounds() })
+onBeforeUnmount(() => { disposed = true; loadRequestId += 1; customerRequestId += 1; warehouseRequestId += 1 })
+</script>
+
+<template>
+  <AdminPage as="div" class="business-page inbound-orders-page">
+    <ListPageLayout ariaLabel="入库单管理">
+      <template #toolbar>
+        <QueryToolbar v-model="filters" class="surface-panel inbound-query-toolbar" ariaLabel="入库单筛选" :fields="queryFields" :available-fields="allQueryFields" preference-key="inbound-orders-query" :search-on-reset="false" @search="applyFilters" @reset="resetFilters">
+          <template #actions>
+            <el-button :aria-expanded="showAdvancedFilters" @click="toggleAdvancedFilters">
+              <SlidersHorizontal :size="16" />
+              {{ showAdvancedFilters ? '收起筛选' : '更多筛选' }}
+              <ChevronUp v-if="showAdvancedFilters" :size="15" />
+              <ChevronDown v-else :size="15" />
+            </el-button>
+          </template>
+        </QueryToolbar>
+      </template>
+
+      <template v-if="customerLoadError || loadError" #state>
+        <div class="inbound-state-stack">
+          <el-alert v-if="customerLoadError" type="warning" :closable="false" show-icon role="alert">
+            <template #title><div class="api-error-alert-title"><span>{{ customerLoadError.message }}</span><ApiErrorMeta :details="customerLoadError" /></div></template>
+            <el-button link type="warning" :loading="customersLoading" @click="loadCustomers"><RefreshCw :size="15" />重新加载客户列表</el-button>
+          </el-alert>
+          <LoadErrorState v-if="loadError" :message="loadError.message" title="入库单暂时无法加载" @retry="loadInbounds"><template #details><ApiErrorMeta :details="loadError" /></template></LoadErrorState>
+        </div>
+      </template>
+
+      <section v-if="!loadError" class="surface-panel table-panel" :aria-busy="loading">
+      <header class="table-toolbar">
+        <div class="table-tabs-row">
+          <nav class="inbound-tabs" role="tablist" aria-label="入库单处理状态">
+            <button v-for="(item, index) in tabs" :key="item.value || 'all'" type="button" role="tab" class="inbound-tab" :class="{ 'is-active': tab === item.value }" :aria-selected="tab === item.value" :tabindex="tab === item.value ? 0 : -1" :title="item.description" @click="tab = item.value" @keydown="handleTabKeydown($event, index)">{{ item.label }}</button>
+          </nav>
+        </div>
+        <div class="inbound-stats-row" aria-label="入库单统计">
+          <span class="total-info">
+            <b>总箱数 {{ formatAggregate(aggregateStats.packages, 0) }}</b>
+            <i aria-hidden="true" />
+            <b>总毛重 {{ formatAggregate(aggregateStats.grossWeight) }} kg</b>
+            <i aria-hidden="true" />
+            <b>计费重量 {{ formatAggregate(aggregateStats.chargeableWeight) }} kg</b>
+            <i aria-hidden="true" />
+            <b>总体积 {{ formatAggregate(aggregateStats.volume) }} m³</b>
+          </span>
+        </div>
+      </header>
+      <DataTable v-model:page="page" v-model:page-size="pageSize" :data="result.records" :columns="columns" preference-key="inbound-orders-table" :loading="loading" :total="result.total" :page-sizes="[20, 50, 100]" row-key="id" :empty-text="listEmptyText" aria-label="入库单列表">
+        <template #pagination-left>当前显示 {{ currentPageCount }} 条 · 共 {{ result.total }} 条</template>
+        <template #actions="{ row }"><div v-if="access.can('platform:firstleg:inbound:view')" class="row-actions"><el-button size="small" type="primary" :disabled="!(row as InboundOrderSummary).orderId" @click="openDetail(row as InboundOrderSummary)"><ClipboardCheck :size="15" />处理</el-button><el-button size="small" plain type="primary" :loading="printingInboundId === (row as InboundOrderSummary).id" :disabled="Boolean(printingInboundId)" @click="printCartonLabels(row as InboundOrderSummary)"><Printer :size="15" />打印箱唛</el-button><el-button size="small" plain type="primary" :disabled="!(row as InboundOrderSummary).orderId" @click="openDetail(row as InboundOrderSummary)"><Eye :size="15" />查看</el-button></div><span v-else class="muted-action">无查看权限</span></template>
+        <template #inbound="{ row }"><div class="inbound-code-cell"><strong>{{ text((row as InboundOrderSummary).inboundCode) }}</strong><el-button v-if="(row as InboundOrderSummary).inboundCode" link type="primary" @click="openRelationship(row as InboundOrderSummary)"><Link2 :size="14" />关联数据</el-button></div></template>
+        <template #processStatus="{ row }"><el-tag :type="statusType((row as InboundOrderSummary).processStatus)" effect="light">{{ statusLabel((row as InboundOrderSummary).processStatus) }}</el-tag></template>
+        <template #orderStatus="{ row }">{{ codeLabel((row as InboundOrderSummary).orderStatusSnapshot, inboundOrderStatusLabels) }}</template>
+        <template #measureReviewStatus="{ row }">{{ codeLabel((row as InboundOrderSummary).measureReviewStatus, measureReviewLabels) }}</template>
+        <template #expectedArrivalAt="{ row }">{{ formatDate((row as InboundOrderSummary).expectedArrivalAt) }}</template>
+        <template #feeStatus="{ row }">{{ codeLabel((row as InboundOrderSummary).feeStatus, feeStatusLabels) }}</template>
+        <template #feeReviewStatus="{ row }">{{ codeLabel((row as InboundOrderSummary).feeReviewStatus, inboundReviewStatusLabels) }}</template>
+        <template #customerName="{ row }"><LineClampText :content="(row as InboundOrderSummary).customerName" /></template>
+        <template #warehouseName="{ row }">{{ text((row as InboundOrderSummary).warehouseName) }}</template>
+        <template #deliveryWarehouseName="{ row }">{{ text((row as InboundOrderSummary).deliveryWarehouseName) }}</template>
+        <template #loadingStatus="{ row }">{{ codeLabel((row as InboundOrderSummary).loadingStatus, loadingStatusLabels) }}</template>
+        <template #holdFlag="{ row }"><el-tag :type="(row as InboundOrderSummary).holdFlag ? 'danger' : 'info'" effect="plain">{{ (row as InboundOrderSummary).holdFlag ? '是' : '否' }}</el-tag></template>
+        <template #currentHoldReason="{ row }">{{ text((row as InboundOrderSummary).currentHoldReason) }}</template>
+        <template #containerNo="{ row }">{{ text((row as InboundOrderSummary).containerNo) }}</template>
+        <template #cabinetNo="{ row }">{{ text((row as InboundOrderSummary).cabinetNo) }}</template>
+        <template #companyName="{ row }">{{ text((row as InboundOrderSummary).companyName) }}</template>
+        <template #businessType="{ row }">{{ firstLegBusinessTypeLabel((row as InboundOrderSummary).businessType) }}</template>
+        <template #channelName="{ row }"><div class="primary-cell"><LineClampText :content="(row as InboundOrderSummary).channelName" /><span>{{ text((row as InboundOrderSummary).channelCode) }}</span></div></template>
+        <template #taxMode="{ row }">{{ firstLegTaxModeLabel((row as InboundOrderSummary).taxMode) }}</template>
+        <template #containerMode="{ row }">{{ firstLegContainerModeLabel((row as InboundOrderSummary).containerMode) }}</template>
+        <template #customsInspection="{ row }">{{ (row as InboundOrderSummary).customsInspection === null ? '—' : (row as InboundOrderSummary).customsInspection ? '是' : '否' }}</template>
+        <template #sailingAt="{ row }">{{ formatDate((row as InboundOrderSummary).sailingAt) }}</template>
+        <template #portArrivalAt="{ row }">{{ formatDate((row as InboundOrderSummary).portArrivalAt) }}</template>
+        <template #totalPackageCount="{ row }">{{ text((row as InboundOrderSummary).totalPackageCount) }}</template>
+        <template #actualGrossWeightKg="{ row }">{{ formatNumber((row as InboundOrderSummary).actualGrossWeightKg) }}</template>
+        <template #chargeableWeightKg="{ row }">{{ formatNumber((row as InboundOrderSummary).chargeableWeightKg) }}</template>
+        <template #actualVolumeCbm="{ row }">{{ formatNumber((row as InboundOrderSummary).actualVolumeCbm) }}</template>
+        <template #chargeableVolumeCbm="{ row }">{{ formatNumber((row as InboundOrderSummary).chargeableVolumeCbm) }}</template>
+        <template #palletCount="{ row }">{{ text((row as InboundOrderSummary).palletCount) }}</template>
+        <template #locationCodes="{ row }">{{ text((row as InboundOrderSummary).locationCodes) }}</template>
+        <template #volumeWeightKg="{ row }">{{ formatNumber((row as InboundOrderSummary).volumeWeightKg) }}</template>
+        <template #actualNetWeightKg="{ row }">{{ formatNumber((row as InboundOrderSummary).actualNetWeightKg) }}</template>
+        <template #destinationType="{ row }">{{ firstLegDestinationTypeLabel((row as InboundOrderSummary).destinationType) }}</template>
+        <template #destinationName="{ row }"><div class="primary-cell"><strong>{{ text((row as InboundOrderSummary).destinationName) }}</strong><span>{{ text((row as InboundOrderSummary).destinationCode) }}</span></div></template>
+        <template #measureCompletedAt="{ row }">{{ formatDate((row as InboundOrderSummary).measureCompletedAt) }}</template>
+        <template #inboundedAt="{ row }">{{ formatDate((row as InboundOrderSummary).inboundedAt) }}</template>
+        <template #expressCompanyName="{ row }">{{ text((row as InboundOrderSummary).expressCompanyName) }}</template>
+        <template #expressTrackingNo="{ row }">{{ text((row as InboundOrderSummary).expressTrackingNo) }}</template>
+        <template #createdAt="{ row }">{{ formatDate((row as InboundOrderSummary).createdAt) }}</template>
+        <template #empty><el-empty :description="listEmptyText" /></template>
+      </DataTable>
+      </section>
+    </ListPageLayout>
+    <InboundCodeRelationshipDialog v-if="relationshipDialogOpen" v-model="relationshipDialogOpen" :inbound-code="relationshipDialogInboundCode" :can-read-base="access.can('platform:order:list')" :can-read-loading="access.can('platform:firstleg:smart-loading:list')" :can-read-overseas="access.can('platform:overseas-warehouse:inventory:list')" />
+  </AdminPage>
+</template>
+
+<style scoped>
+.inbound-orders-page { min-width: 0; }
+.inbound-code-cell { display: grid; gap: 3px; min-width: 0; }.inbound-code-cell .el-button { width: fit-content; margin: 0; padding: 0; }
+.inbound-query-toolbar { align-items: stretch; border-radius: 8px; background: #f8fafc; }
+.inbound-tabs { display: flex; width: max-content; max-width: 100%; min-width: 0; overflow-x: auto; border-bottom: 2px solid var(--cc-border); scrollbar-width: none; }
+.inbound-tabs::-webkit-scrollbar { display: none; }
+.inbound-tab { min-height: 42px; flex: 0 0 auto; padding: 10px 22px; border: 0; border-bottom: 2px solid transparent; margin-bottom: -2px; background: transparent; color: #475467; cursor: pointer; font-size: 13px; line-height: 1.4; white-space: nowrap; transition: border-color .16s ease, color .16s ease, background-color .16s ease; }
+.inbound-tab:hover { color: var(--cc-primary); background: #f8fbff; }
+.inbound-tab:focus-visible { outline: 3px solid rgba(102, 126, 234, .2); outline-offset: 1px; }
+.inbound-tab.is-active { border-bottom-color: var(--cc-primary); background: #fff; color: var(--cc-primary); font-weight: 650; }
+.inbound-state-stack { display: grid; min-width: 0; gap: 12px; }
+.row-actions { display: flex; align-items: center; gap: 2px; white-space: nowrap; }
+.row-actions :deep(.el-button) { margin-left: 0; }
+.table-toolbar { display: grid; min-width: 0; border-bottom: 1px solid var(--cc-border); }
+.table-tabs-row { min-width: 0; padding: 0 14px; background: #fff; }
+.inbound-stats-row { display: flex; min-width: 0; align-items: center; justify-content: space-between; gap: 16px; padding: 10px 14px; background: var(--cc-primary); color: #fff; }
+.inbound-stats-row .selected-info, .inbound-stats-row .total-info { min-width: 0; font-size: 12px; font-weight: 650; line-height: 1.5; }
+.inbound-stats-row .total-info { display: flex; align-items: center; flex-wrap: wrap; justify-content: flex-end; gap: 8px; }
+.inbound-stats-row b { font-weight: 650; }
+.inbound-stats-row i { width: 1px; height: 12px; background: rgba(255, 255, 255, .38); }
+.table-panel :deep(.el-table th.el-table__cell) { border-right: 1px solid #edf0f4; }
+.table-panel :deep(.el-table td.el-table__cell) { border-right: 1px solid #edf0f4; }
+.primary-cell, .status-stack { display: grid; min-width: 0; justify-items: start; gap: 4px; }
+.primary-cell strong, .primary-cell span, .status-stack span, .status-stack small { overflow-wrap: anywhere; }
+.primary-cell span, .status-stack span, .status-stack small { color: var(--cc-muted); font-size: 12px; }
+@media (max-width: 900px) { .inbound-tabs { width: 100%; } }
+@media (max-width: 720px) { .inbound-tab { padding-inline: 14px; } .table-tabs-row { padding: 0 10px; } .inbound-stats-row { min-height: 0; align-items: stretch; flex-direction: column; gap: 10px; padding: 10px; } .inbound-stats-row .total-info { justify-content: flex-start; } }
+@media (max-width: 360px) { .inbound-tab { padding-inline: 12px; } .row-actions { align-items: stretch; flex-direction: column; } .row-actions :deep(.el-button) { width: 100%; min-height: 40px; } }
+</style>
diff --git a/src/modules/inbounds/pages/MeasurementReviewsView.vue b/src/modules/inbounds/pages/MeasurementReviewsView.vue
new file mode 100644
index 00000000..b8551a57
--- /dev/null
+++ b/src/modules/inbounds/pages/MeasurementReviewsView.vue
@@ -0,0 +1,7 @@
+<script setup lang="ts">
+import InboundTaskList from '../components/InboundTaskList.vue'
+</script>
+
+<template>
+  <InboundTaskList mode="review" />
+</template>
diff --git a/src/modules/inbounds/review/MeasurementReviewPanel.test.ts b/src/modules/inbounds/review/MeasurementReviewPanel.test.ts
new file mode 100644
index 00000000..105a9ac1
--- /dev/null
+++ b/src/modules/inbounds/review/MeasurementReviewPanel.test.ts
@@ -0,0 +1,291 @@
+import ElementPlus, { ElMessage, ElMessageBox } from 'element-plus'
+import { createPinia, setActivePinia } from 'pinia'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+import { approveMeasurement, getMeasurementReviewDetail, listMeasurementReviewHistory } from './api'
+import MeasurementReviewPanel from './MeasurementReviewPanel.vue'
+import type { MeasurementReviewDetail } from './types'
+
+vi.mock('./api', () => ({
+  approveMeasurement: vi.fn(),
+  getMeasurementReviewDetail: vi.fn(),
+  listMeasurementReviewHistory: vi.fn(),
+}))
+
+vi.mock('../weight/components/WeightOcrPanel.vue', () => ({
+  default: {
+    name: 'WeightOcrPanel',
+    props: { customerId: String, inboundId: String, reviewMode: Boolean, correctionMode: Boolean },
+    emits: ['changed'],
+    template: '<button class="mock-weight-change" @click="$emit(\'changed\')">重量证据</button>',
+  },
+}))
+
+vi.mock('../measurement/components/MeasurementEvidenceThumbnail.vue', () => ({
+  default: {
+    name: 'MeasurementEvidenceThumbnail',
+    props: { customerId: String, inboundId: String, fileId: String, alt: String, emptyText: String },
+    emits: ['open'],
+    template: '<button class="mock-measurement-image" @click="$emit(\'open\')">测量图片</button>',
+  },
+}))
+
+const detail: MeasurementReviewDetail = {
+  inboundId: '90001', inboundCode: 'RK90001', companyName: '柏悦客户', channelCode: 'SEA', channelName: '海运',
+  processStatus: 'MEASURE_PENDING', measureReviewStatus: 'PENDING', recommendedPalletType: 'STANDARD', reviewReason: null, reviewerId: null, reviewerName: null,
+  measurementId: '70001', sourceType: 'DEVICE', measurementStatus: 'SUBMITTED', inboundVersion: 7, version: 4,
+  originalDocumentNo: 'ORD-001', originalGrossWeightKg: 100, originalVolumeCbm: 2, originalPackageCount: 10,
+  actualPackageCount: 10, actualGrossWeightKg: 120, actualNetWeightKg: 110, actualVolumeCbm: 2.2, volumeWeightKg: 367.4, actualGoodsName: '测试货物',
+  items: [],
+  weightResults: [],
+}
+
+enableAutoUnmount(afterEach)
+
+describe('MeasurementReviewPanel', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    setActivePinia(createPinia())
+    const auth = useAuthStore()
+    auth.token = 'token'
+    auth.permissions = [
+      'firstleg:inbound:measurement-review',
+      'firstleg:inbound:measurement-review-history',
+      'platform:firstleg:inbound:measure:view',
+      'platform:firstleg:inbound:weight:edit',
+      'platform:firstleg:inbound:weight:confirm',
+    ]
+    useAccessPreviewStore().initializeAfterLogin()
+    vi.mocked(getMeasurementReviewDetail).mockResolvedValue(detail)
+    vi.mocked(listMeasurementReviewHistory).mockResolvedValue({ records: [], page: 1, size: 20, total: 0, pages: 0 })
+  })
+
+  it('keeps customer context and pending actions in one sticky toolbar while reviewing long content', async () => {
+    const wrapper = mount(MeasurementReviewPanel, { props: { customerId: '10001', inboundId: '90001' }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    const toolbar = wrapper.get('.review-toolbar')
+    expect(toolbar.text()).toContain('待审核')
+    expect(toolbar.text()).toContain('修改重量')
+    expect(toolbar.text()).toContain('通过并进入待分柜')
+    expect(toolbar.text()).toContain('刷新')
+    expect(toolbar.text()).toContain('客户：柏悦客户')
+    expect(toolbar.text()).toContain('渠道：海运')
+    expect(wrapper.find('.review-toolbar__context').exists()).toBe(true)
+    expect(wrapper.get('.review-toolbar__status').find('.review-toolbar__context').exists()).toBe(true)
+    expect(wrapper.find('.review-context').exists()).toBe(false)
+    expect(wrapper.text()).not.toContain('RK90001')
+    expect(wrapper.text()).not.toContain('入仓码')
+    expect(wrapper.text()).not.toContain('驳回')
+    expect(wrapper.text()).not.toContain('异常放行')
+    expect(wrapper.text()).not.toContain('审核历史')
+    expect(listMeasurementReviewHistory).not.toHaveBeenCalled()
+    const source = await import('./MeasurementReviewPanel.vue?raw').then((module) => module.default)
+    expect(source).toContain('position: sticky')
+    expect(source).toContain('review-toolbar__context')
+    expect(source.indexOf('class="review-toolbar"')).toBeLessThan(source.indexOf('<WeightOcrPanel'))
+    expect(source).not.toContain('reasonDialog')
+    expect(source).not.toContain('saveInboundMeasurementDraft')
+    expect(source).not.toContain('submitInboundMeasurement')
+    expect(source).not.toContain('listMeasurementReviewHistory')
+  })
+
+  it.each([true, false])('describes dropship palletizing and uses the server result when pricing succeeds=%s', async (initialPricingSucceeded) => {
+    vi.mocked(approveMeasurement).mockResolvedValue({ inboundId: '90001', measurementId: '70001', processStatus: 'WAIT_PALLETIZE', feeStatus: initialPricingSucceeded ? 'CALCULATED' : 'UNPRICED', initialPricingSucceeded, initialPricingMessage: null, initialFee: null })
+    const confirmation = vi.spyOn(ElMessageBox, 'confirm').mockResolvedValue(undefined as never)
+    const success = vi.spyOn(ElMessage, 'success')
+    const warning = vi.spyOn(ElMessage, 'warning')
+    const wrapper = mount(MeasurementReviewPanel, { props: { customerId: '10001', inboundId: '90001', fulfillmentType: 'ONE_CLICK_DROPSHIP' }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(wrapper.text()).not.toContain('通过并进入待分柜')
+    await wrapper.findAll('button').find((button) => button.text().includes('通过并进入待一件代发组托'))!.trigger('click')
+    await flushPromises()
+    expect(confirmation).toHaveBeenCalledWith(expect.stringContaining('进入待一件代发组托'), '确认测量审核通过', expect.objectContaining({ confirmButtonText: '通过并进入待一件代发组托' }))
+    expect(initialPricingSucceeded ? success : warning).toHaveBeenCalledWith(expect.stringContaining('入库单已进入待一件代发组托'))
+    expect(approveMeasurement).toHaveBeenCalledTimes(1)
+    expect(wrapper.emitted('changed')).toHaveLength(1)
+  })
+
+  it('uses the list customer context when the review detail has no customer name', async () => {
+    vi.mocked(getMeasurementReviewDetail).mockResolvedValue({ ...detail, companyName: null })
+    const wrapper = mount(MeasurementReviewPanel, {
+      props: { customerId: '10001', inboundId: '90001', customerName: '欧阳的公司', channelName: '纽约海铁' },
+      global: { plugins: [ElementPlus] },
+    })
+    await flushPromises()
+
+    expect(wrapper.get('.review-toolbar__context').text()).toBe('客户：欧阳的公司 · 渠道：海运')
+  })
+
+  it('shows declared facts, authoritative measurement totals, and box-detail evidence for manual review', async () => {
+    vi.mocked(getMeasurementReviewDetail).mockResolvedValue({
+      ...detail,
+      originalPackageCount: 9,
+      originalGrossWeightKg: 118,
+      originalVolumeCbm: 2,
+      actualPackageCount: 10,
+      actualGrossWeightKg: 120,
+      actualNetWeightKg: 110,
+      actualVolumeCbm: 2.2,
+      volumeWeightKg: 367.4,
+      items: [{
+        id: 'item-1', boxCode: 'BOX-001', itemNo: '1', boxSpecification: null, packageCount: 10,
+        lengthCm: 60, widthCm: 40, heightCm: 30, girthCm: 200, unitWeightKg: 12,
+        unitVolumeCbm: 0.072, totalWeightKg: 120, totalVolumeCbm: 0.72, volumeWeightKg: 120.2,
+        intelligentImageFileId: '88001', machineNo: 'DEVICE-01', deviceMeasuredAt: '2026-08-18T10:30:00',
+        overLimitWarning: null, outerLengthCm: null, outerWidthCm: null, outerHeightCm: null, remark: null,
+      }],
+    })
+    const wrapper = mount(MeasurementReviewPanel, { props: { customerId: '10001', inboundId: '90001' }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    const summary = wrapper.get('.review-data').text()
+    expect(summary).toContain('审核数据总览')
+    const comparisonRows = wrapper.findAll('.review-comparison__row')
+    expect(comparisonRows).toHaveLength(2)
+    expect(comparisonRows[0].text()).toContain('客户申报')
+    expect(comparisonRows[0].text()).toContain('箱数9')
+    expect(comparisonRows[0].text()).toContain('毛重118 kg')
+    expect(comparisonRows[0].text()).not.toContain('实际品名')
+    expect(comparisonRows[0].text()).not.toContain('原单据号码')
+    expect(comparisonRows[1].text()).toContain('平台实测')
+    expect(comparisonRows[1].text()).toContain('箱数10 差异 +1')
+    expect(comparisonRows[1].text()).toContain('毛重120 kg · 差异 +2 kg')
+    expect(comparisonRows[1].text()).toContain('货物净重110 kg')
+    expect(comparisonRows[1].text()).toContain('体积2.2 m³ · 差异 +0.2 m³')
+    expect(comparisonRows[1].text()).toContain('体积重367.4 kg')
+
+    const items = wrapper.get('.review-items').text()
+    expect(items).toContain('箱规测量明细')
+    expect(items).toContain('BOX-001')
+    expect(items).toContain('60 × 40 × 30')
+    expect(items).toContain('120.2')
+    expect(items).toContain('2026-08-18 10:30:00')
+    expect(items).not.toContain('每箱毛重(kg)')
+    expect(items).not.toContain('总重量(kg)')
+    const image = wrapper.getComponent({ name: 'MeasurementEvidenceThumbnail' })
+    expect(image.props('customerId')).toBe('10001')
+    expect(image.props('inboundId')).toBe('90001')
+    expect(image.props('fileId')).toBe('88001')
+
+    const source = await import('./MeasurementReviewPanel.vue?raw').then((module) => module.default)
+    expect(source).toContain(':file-id="row.intelligentImageFileId"')
+    expect(source).toContain('openImagePreview(row.intelligentImageFileId')
+    expect(source).toContain('downloadInboundMeasurementImage')
+    expect(source).toContain('.review-table :deep(.el-table__header .cell) { white-space: nowrap; }')
+    expect(source).toContain('.review-table :deep(.review-time-cell .cell) { white-space: nowrap; }')
+  })
+
+  it('keeps difference labels absent when declared values are unavailable', async () => {
+    vi.mocked(getMeasurementReviewDetail).mockResolvedValue({ ...detail, originalGrossWeightKg: null, originalVolumeCbm: null })
+    const wrapper = mount(MeasurementReviewPanel, { props: { customerId: '10001', inboundId: '90001' }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    expect(wrapper.get('.review-comparison').text()).not.toContain('差异')
+  })
+
+  it('reuses WeightOcrPanel and enables only its review correction mode', async () => {
+    const wrapper = mount(MeasurementReviewPanel, { props: { customerId: '10001', inboundId: '90001' }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    const weightPanel = wrapper.getComponent({ name: 'WeightOcrPanel' })
+    expect(weightPanel.props('reviewMode')).toBe(true)
+    expect(weightPanel.props('correctionMode')).toBe(false)
+    await wrapper.findAll('button').find((button) => button.text().includes('修改重量'))?.trigger('click')
+    expect(weightPanel.props('correctionMode')).toBe(true)
+  })
+
+  it('refreshes inboundVersion after a weight correction before approval', async () => {
+    vi.mocked(getMeasurementReviewDetail)
+      .mockResolvedValueOnce(detail)
+      .mockResolvedValueOnce({ ...detail, inboundVersion: 8, actualGrossWeightKg: 125, actualNetWeightKg: 115 })
+    vi.mocked(approveMeasurement).mockResolvedValue({ inboundId: '90001', measurementId: '70001', processStatus: 'WAIT_SPLIT', feeStatus: 'CALCULATED', initialPricingSucceeded: true, initialPricingMessage: null, initialFee: null })
+    vi.spyOn(ElMessageBox, 'confirm').mockResolvedValue(undefined as never)
+    const wrapper = mount(MeasurementReviewPanel, { props: { customerId: '10001', inboundId: '90001' }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    await wrapper.get('.mock-weight-change').trigger('click')
+    await flushPromises()
+    await wrapper.findAll('button').find((button) => button.text().includes('通过并进入待分柜'))?.trigger('click')
+    await flushPromises()
+
+    expect(getMeasurementReviewDetail).toHaveBeenCalledTimes(2)
+    expect(approveMeasurement).toHaveBeenCalledWith('10001', '90001', { measurementId: '70001', expectedVersion: 8 })
+    expect(wrapper.emitted('changed')).toHaveLength(1)
+  })
+
+  it('emits only after approval succeeds and blocks duplicate submissions', async () => {
+    let finishApproval: (() => void) | undefined
+    vi.mocked(approveMeasurement).mockImplementation(() => new Promise((resolve) => {
+      finishApproval = () => resolve({ inboundId: '90001', measurementId: '70001', processStatus: 'WAIT_SPLIT', feeStatus: 'CALCULATED', initialPricingSucceeded: true, initialPricingMessage: null, initialFee: null })
+    }))
+    vi.spyOn(ElMessageBox, 'confirm').mockResolvedValue(undefined as never)
+    const wrapper = mount(MeasurementReviewPanel, { props: { customerId: '10001', inboundId: '90001' }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    const approveButton = wrapper.findAll('button').find((button) => button.text().includes('通过并进入待分柜'))!
+    await approveButton.trigger('click')
+    await approveButton.trigger('click')
+
+    expect(approveMeasurement).toHaveBeenCalledTimes(1)
+    expect(wrapper.emitted('changed')).toBeUndefined()
+    finishApproval?.()
+    await flushPromises()
+    expect(wrapper.emitted('changed')).toHaveLength(1)
+    expect(getMeasurementReviewDetail).toHaveBeenCalledTimes(1)
+  })
+
+  it('keeps the review panel open and does not emit when approval fails', async () => {
+    vi.mocked(approveMeasurement).mockRejectedValue(new Error('审核写入失败'))
+    vi.spyOn(ElMessageBox, 'confirm').mockResolvedValue(undefined as never)
+    const wrapper = mount(MeasurementReviewPanel, { props: { customerId: '10001', inboundId: '90001' }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    await wrapper.findAll('button').find((button) => button.text().includes('通过并进入待分柜'))!.trigger('click')
+    await flushPromises()
+
+    expect(wrapper.emitted('changed')).toBeUndefined()
+    expect(wrapper.find('.review-panel').exists()).toBe(true)
+    expect(wrapper.findAll('button').some((button) => button.text().includes('通过并进入待分柜'))).toBe(true)
+  })
+
+  it('blocks approval while the order detail navigation is loading', async () => {
+    vi.spyOn(ElMessageBox, 'confirm').mockResolvedValue(undefined as never)
+    const wrapper = mount(MeasurementReviewPanel, {
+      props: { customerId: '10001', inboundId: '90001', postApproveLoading: true },
+      global: { plugins: [ElementPlus] },
+    })
+    await flushPromises()
+
+    await wrapper.findAll('button').find((button) => button.text().includes('通过并进入待分柜'))!.trigger('click')
+
+    expect(approveMeasurement).not.toHaveBeenCalled()
+  })
+
+  it('does not submit approval again after approval succeeded but navigation needs retrying', async () => {
+    vi.spyOn(ElMessageBox, 'confirm').mockResolvedValue(undefined as never)
+    const wrapper = mount(MeasurementReviewPanel, {
+      props: { customerId: '10001', inboundId: '90001', approvalCompleted: true },
+      global: { plugins: [ElementPlus] },
+    })
+    await flushPromises()
+
+    const approveButton = wrapper.findAll('button').find((button) => button.text().includes('审核已通过'))!
+    expect(approveButton.attributes('disabled')).toBeDefined()
+    await approveButton.trigger('click')
+    expect(approveMeasurement).not.toHaveBeenCalled()
+  })
+
+  it('shows historical rejected data read-only without new reject or release operations', async () => {
+    vi.mocked(getMeasurementReviewDetail).mockResolvedValue({ ...detail, processStatus: 'MEASURE_REJECTED', measureReviewStatus: 'REJECTED', reviewReason: '历史审核说明' })
+    const wrapper = mount(MeasurementReviewPanel, { props: { customerId: '10001', inboundId: '90001' }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('历史记录为审核驳回，仅供查看')
+    expect(wrapper.text()).toContain('历史审核说明')
+    expect(wrapper.text()).not.toContain('修改重量')
+    expect(wrapper.text()).not.toContain('异常放行')
+  })
+})
diff --git a/src/modules/inbounds/review/MeasurementReviewPanel.vue b/src/modules/inbounds/review/MeasurementReviewPanel.vue
new file mode 100644
index 00000000..5bfcfc1b
--- /dev/null
+++ b/src/modules/inbounds/review/MeasurementReviewPanel.vue
@@ -0,0 +1,357 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import { Check, Pencil, RotateCcw } from '@lucide/vue'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import { downloadInboundMeasurementImage } from '../measurement/api'
+import MeasurementEvidenceThumbnail from '../measurement/components/MeasurementEvidenceThumbnail.vue'
+import { inboundProcessStatusLabels, inboundReviewStatusLabels, inboundStatusLabel } from '../status'
+import WeightOcrPanel from '../weight/components/WeightOcrPanel.vue'
+import { approveMeasurement, getMeasurementReviewDetail } from './api'
+import type { MeasurementReviewDetail } from './types'
+
+const props = defineProps<{
+  customerId?: string
+  /** @deprecated 仅用于兼容尚未完成 customerId 映射的上层集成。 */
+  tenantId?: string
+  inboundId: string
+  fulfillmentType?: string | null
+  customerName?: string | null
+  channelName?: string | null
+  channelCode?: string | null
+  postApproveLoading?: boolean
+  approvalCompleted?: boolean
+}>()
+
+const emit = defineEmits<{ changed: [] }>()
+
+const access = useAccessPreviewStore()
+const detail = ref<MeasurementReviewDetail | null>(null)
+const loading = ref(false)
+const actionLoading = ref('')
+const loadError = ref<ApiErrorDetails | null>(null)
+const correctionMode = ref(false)
+const requestSerial = ref(0)
+const imagePreviewOpen = ref(false)
+const imagePreviewTitle = ref('测量图片')
+const imagePreviewUrl = ref('')
+const imagePreviewLoading = ref(false)
+const imagePreviewError = ref<ApiErrorDetails | null>(null)
+let imagePreviewRequestSerial = 0
+
+const canReview = computed(() => access.can('firstleg:inbound:measurement-review'))
+const customerId = computed(() => props.customerId || props.tenantId || '')
+const isPending = computed(() => detail.value?.measureReviewStatus === 'PENDING' && detail.value?.processStatus === 'MEASURE_PENDING')
+const approvalTargetLabel = computed(() => props.fulfillmentType === 'ONE_CLICK_DROPSHIP' ? '待一件代发组托' : '待分柜')
+const approvalButtonLabel = computed(() => `通过并进入${approvalTargetLabel.value}`)
+const isRejected = computed(() => detail.value?.measureReviewStatus === 'REJECTED' && detail.value?.processStatus === 'MEASURE_REJECTED')
+const reviewStatusLabel = computed(() => inboundStatusLabel(detail.value?.measureReviewStatus, inboundReviewStatusLabels, '未提交'))
+const displayCustomerName = computed(() => detail.value?.companyName?.trim() || props.customerName?.trim() || '客户未命名')
+const displayChannelName = computed(() => detail.value?.channelName?.trim() || detail.value?.channelCode?.trim() || props.channelName?.trim() || props.channelCode?.trim() || '渠道未填写')
+const sourceLabels: Record<string, string> = {
+  THIRD_PARTY: '第三方设备',
+  DEVICE: '第三方设备',
+  OPENAPI: '第三方设备',
+  MANUAL: '平台人工',
+}
+const sourceLabel = computed(() => sourceLabels[detail.value?.sourceType || ''] || (detail.value?.sourceType ? '未知来源' : '尚未记录'))
+
+function formatNumber(value: number | null | undefined, maximumFractionDigits = 3) {
+  if (value === null || value === undefined || !Number.isFinite(value)) return '—'
+  return new Intl.NumberFormat('zh-CN', { maximumFractionDigits, minimumFractionDigits: 0 }).format(value)
+}
+
+function formatDifference(actual: number | null | undefined, declared: number | null | undefined, maximumFractionDigits = 3, unit = '') {
+  if (actual == null || declared == null || !Number.isFinite(actual) || !Number.isFinite(declared)) return null
+  const difference = actual - declared
+  if (difference === 0) return null
+  const sign = difference > 0 ? '+' : ''
+  return `差异 ${sign}${formatNumber(difference, maximumFractionDigits)}${unit}`
+}
+
+function formatDate(value: string | null | undefined) {
+  return value ? value.replace('T', ' ') : '—'
+}
+
+function releaseImagePreview() {
+  imagePreviewRequestSerial += 1
+  if (imagePreviewUrl.value) URL.revokeObjectURL(imagePreviewUrl.value)
+  imagePreviewUrl.value = ''
+  imagePreviewLoading.value = false
+  imagePreviewError.value = null
+}
+
+async function openImagePreview(fileId: string | null, itemLabel: string) {
+  if (!fileId) return
+  releaseImagePreview()
+  const serial = ++imagePreviewRequestSerial
+  imagePreviewTitle.value = `测量图片 · ${itemLabel}`
+  imagePreviewOpen.value = true
+  imagePreviewLoading.value = true
+  try {
+    const blob = await downloadInboundMeasurementImage(customerId.value, props.inboundId, fileId)
+    if (serial !== imagePreviewRequestSerial) return
+    imagePreviewUrl.value = URL.createObjectURL(blob)
+  } catch (error) {
+    if (serial !== imagePreviewRequestSerial) return
+    imagePreviewError.value = getApiErrorDetails(error, '测量原图读取失败，请稍后重试')
+  } finally {
+    if (serial === imagePreviewRequestSerial) imagePreviewLoading.value = false
+  }
+}
+
+function isConflict(error: unknown) {
+  const details = getApiErrorDetails(error)
+  return details.message.includes('版本已变化') || details.message.includes('并发修改')
+}
+
+async function loadReview() {
+  const serial = ++requestSerial.value
+  loadError.value = null
+  loading.value = true
+  try {
+    const result = await getMeasurementReviewDetail(customerId.value, props.inboundId)
+    if (serial === requestSerial.value) detail.value = result
+  } catch (error) {
+    if (serial === requestSerial.value) {
+      detail.value = null
+      loadError.value = getApiErrorDetails(error, '测量审核数据加载失败')
+    }
+  } finally {
+    if (serial === requestSerial.value) loading.value = false
+  }
+}
+
+async function reload() {
+  await loadReview()
+}
+
+async function handleWeightChanged() {
+  await loadReview()
+}
+
+async function confirmApprove() {
+  if (!detail.value || !isPending.value || !canReview.value || actionLoading.value || props.postApproveLoading || props.approvalCompleted) return
+  try {
+    await ElMessageBox.confirm(
+      `审核通过后，入库单将进入${approvalTargetLabel.value}。系统会尝试生成初算费用，但初算失败不影响审核通过，后续可由平台人员补充调整。是否继续？`,
+      '确认测量审核通过',
+      { customClass: 'admin-density-confirm', confirmButtonText: approvalButtonLabel.value, cancelButtonText: '返回', type: 'warning' },
+    )
+  } catch {
+    return
+  }
+  actionLoading.value = 'approve'
+  try {
+    const result = await approveMeasurement(customerId.value, props.inboundId, {
+      measurementId: detail.value.measurementId,
+      expectedVersion: detail.value.inboundVersion,
+    })
+    const resultStatusLabel = inboundStatusLabel(result.processStatus, inboundProcessStatusLabels)
+    if (result.initialPricingSucceeded) ElMessage.success(`审核已通过，入库单已进入${resultStatusLabel}，费用已完成初算`)
+    else ElMessage.warning(`审核已通过，入库单已进入${resultStatusLabel}；费用初算未完成${result.initialPricingMessage ? `：${result.initialPricingMessage}` : ''}`)
+    emit('changed')
+  } catch (error) {
+    ElMessage.error(isConflict(error) ? '数据已被更新，请刷新后重新审核' : getApiErrorDetails(error, '审核通过失败').message)
+    if (isConflict(error)) await reload()
+  } finally {
+    actionLoading.value = ''
+  }
+}
+
+watch(() => [customerId.value, props.inboundId], () => {
+  correctionMode.value = false
+  if (customerId.value && props.inboundId) void reload()
+}, { immediate: true })
+
+onMounted(() => {
+  if (!customerId.value || !props.inboundId) loadError.value = { message: '缺少所属企业或入库单标识，无法加载审核数据' }
+})
+onBeforeUnmount(releaseImagePreview)
+
+defineExpose({ confirmApprove, isPending, canReview, actionLoading })
+</script>
+
+<template>
+  <section class="review-panel" aria-labelledby="measurement-review-title">
+    <h2 id="measurement-review-title" class="sr-only">测量审核内容</h2>
+    <div class="review-toolbar" aria-label="测量审核操作">
+      <div class="review-toolbar__status">
+        <StatusBadge v-if="detail" :status="reviewStatusLabel" />
+        <span v-if="isPending">通过后进入待分柜</span>
+        <span v-else-if="isRejected">历史记录为审核驳回，仅供查看</span>
+        <span v-else>当前记录不可审核</span>
+        <span v-if="detail" class="review-toolbar__context">客户：{{ displayCustomerName }} · 渠道：{{ displayChannelName }}</span>
+      </div>
+      <div class="review-toolbar__actions">
+        <el-button v-if="isPending && canReview" type="primary" plain @click="correctionMode = true"><Pencil :size="16" />修改重量</el-button>
+        <el-button v-if="isPending && canReview" type="primary" :loading="actionLoading === 'approve' || postApproveLoading" :disabled="approvalCompleted" @click="confirmApprove"><Check :size="16" />{{ approvalCompleted ? '审核已通过' : approvalButtonLabel }}</el-button>
+        <el-button :loading="loading" aria-label="刷新审核数据" @click="reload"><RotateCcw :size="16" />刷新</el-button>
+      </div>
+    </div>
+
+    <el-alert v-if="loadError" type="error" :closable="false" show-icon role="alert">
+      <template #title><div class="review-alert-title"><span>{{ loadError.message }}</span><ApiErrorMeta :details="loadError" /></div></template>
+      <el-button link type="danger" @click="reload">重新加载</el-button>
+    </el-alert>
+    <el-skeleton v-if="loading && !detail" :rows="8" animated />
+
+    <template v-else-if="detail">
+      <el-alert v-if="detail.reviewReason" type="warning" :closable="false" show-icon :title="`最近审核说明：${detail.reviewReason}`" />
+
+      <section class="review-data" aria-labelledby="review-data-title">
+        <header class="review-section-heading">
+          <div>
+            <h3 id="review-data-title">审核数据总览</h3>
+          </div>
+          <el-tag effect="plain">{{ sourceLabel }}</el-tag>
+        </header>
+
+        <div class="review-comparison">
+          <div class="review-comparison__row review-comparison__row--declared">
+            <strong>客户申报</strong>
+            <dl class="review-declaration" aria-label="客户申报信息">
+              <div><dt>箱数</dt><dd>{{ formatNumber(detail.originalPackageCount, 0) }}</dd></div>
+              <div><dt>毛重</dt><dd>{{ formatNumber(detail.originalGrossWeightKg) }} <small>kg</small></dd></div>
+              <div><dt>体积</dt><dd>{{ formatNumber(detail.originalVolumeCbm, 4) }} <small>m³</small></dd></div>
+            </dl>
+          </div>
+          <div class="review-comparison__row">
+            <strong>平台实测</strong>
+            <dl class="review-metrics" aria-label="平台实测结果汇总">
+              <div><dt>箱数</dt><dd>{{ formatNumber(detail.actualPackageCount, 0) }} <small v-if="formatDifference(detail.actualPackageCount, detail.originalPackageCount, 0)">{{ formatDifference(detail.actualPackageCount, detail.originalPackageCount, 0) }}</small></dd></div>
+              <div><dt>毛重</dt><dd>{{ formatNumber(detail.actualGrossWeightKg) }} <small>kg<span v-if="formatDifference(detail.actualGrossWeightKg, detail.originalGrossWeightKg, 3, ' kg')"> · {{ formatDifference(detail.actualGrossWeightKg, detail.originalGrossWeightKg, 3, ' kg') }}</span></small></dd></div>
+              <div class="review-metric--primary"><dt>货物净重</dt><dd>{{ formatNumber(detail.actualNetWeightKg) }} <small>kg</small></dd></div>
+              <div><dt>体积</dt><dd>{{ formatNumber(detail.actualVolumeCbm, 4) }} <small>m³<span v-if="formatDifference(detail.actualVolumeCbm, detail.originalVolumeCbm, 4, ' m³')"> · {{ formatDifference(detail.actualVolumeCbm, detail.originalVolumeCbm, 4, ' m³') }}</span></small></dd></div>
+              <div><dt>体积重</dt><dd>{{ formatNumber(detail.volumeWeightKg) }} <small>kg</small></dd></div>
+            </dl>
+          </div>
+        </div>
+      </section>
+
+      <section class="review-items" aria-labelledby="review-items-title">
+        <header class="review-section-heading">
+          <div>
+            <h3 id="review-items-title">箱规测量明细</h3>
+          </div>
+          <span>{{ detail.items.length }} 条</span>
+        </header>
+        <div v-if="detail.items.length" class="review-table-scroll">
+          <el-table :data="detail.items" border stripe table-layout="fixed" class="review-table">
+            <el-table-column type="index" label="#" width="44" align="center" />
+            <el-table-column label="箱号" width="240" show-overflow-tooltip>
+              <template #default="{ row }">{{ row.boxCode || row.itemNo || '—' }}</template>
+            </el-table-column>
+            <el-table-column label="测量图片" width="98" align="center">
+              <template #default="{ row }">
+                <MeasurementEvidenceThumbnail
+                  :customer-id="customerId"
+                  :inbound-id="inboundId"
+                  :file-id="row.intelligentImageFileId"
+                  :alt="`箱规 ${row.boxCode || row.itemNo || '箱规编码待补充'} 的测量图片`"
+                  empty-text="无图片"
+                  @open="openImagePreview(row.intelligentImageFileId, row.boxCode || row.itemNo || '箱规编码待补充')"
+                />
+              </template>
+            </el-table-column>
+            <el-table-column label="尺寸 长×宽×高(cm)" min-width="200" align="center">
+              <template #default="{ row }">{{ formatNumber(row.lengthCm) }} × {{ formatNumber(row.widthCm) }} × {{ formatNumber(row.heightCm) }}</template>
+            </el-table-column>
+            <el-table-column prop="packageCount" label="箱数" width="54" align="right">
+              <template #default="{ row }">{{ formatNumber(row.packageCount, 0) }}</template>
+            </el-table-column>
+            <el-table-column label="单箱体积(m³)" width="106" align="right">
+              <template #default="{ row }">{{ formatNumber(row.unitVolumeCbm, 4) }}</template>
+            </el-table-column>
+            <el-table-column label="总体积(m³)" width="96" align="right">
+              <template #default="{ row }">{{ formatNumber(row.totalVolumeCbm, 4) }}</template>
+            </el-table-column>
+            <el-table-column label="体积重(kg)" width="96" align="right">
+              <template #default="{ row }">{{ formatNumber(row.volumeWeightKg) }}</template>
+            </el-table-column>
+            <el-table-column label="测量时间" width="190" class-name="review-time-cell">
+              <template #default="{ row }">{{ formatDate(row.deviceMeasuredAt) }}</template>
+            </el-table-column>
+          </el-table>
+        </div>
+        <el-empty v-else description="暂无箱规测量明细" :image-size="48" />
+      </section>
+
+      <WeightOcrPanel
+        review-mode
+        :correction-mode="correctionMode"
+        :customer-id="customerId"
+        :inbound-id="inboundId"
+        @changed="handleWeightChanged"
+      />
+    </template>
+
+    <el-dialog class="admin-density-dialog" v-model="imagePreviewOpen" :title="imagePreviewTitle" width="min(760px, 92vw)" destroy-on-close append-to-body @closed="releaseImagePreview">
+      <div class="review-image-preview">
+        <el-skeleton v-if="imagePreviewLoading" :rows="5" animated />
+        <div v-else-if="imagePreviewError" class="review-image-preview__error">
+          <span>{{ imagePreviewError.message }}</span>
+          <ApiErrorMeta :details="imagePreviewError" />
+        </div>
+        <img v-else-if="imagePreviewUrl" :src="imagePreviewUrl" alt="当前箱规测量原图" />
+        <el-empty v-else description="暂无可预览图片" />
+      </div>
+    </el-dialog>
+  </section>
+</template>
+
+<style scoped>
+.review-panel { display: grid; gap: var(--admin-space-5, 12px); color: var(--cc-text); }
+.review-toolbar { display: flex; align-items: center; justify-content: space-between; gap: 14px; position: sticky; top: -12px; z-index: 3; flex-wrap: wrap; margin: -var(--admin-space-5, 12px) -var(--admin-space-6, 16px) 0; padding: var(--admin-space-3, 8px) var(--admin-space-6, 16px); border-bottom: 1px solid var(--cc-border); background: var(--admin-surface, #fff); }
+.review-toolbar__status, .review-toolbar__actions { display: flex; min-width: 0; align-items: center; flex-wrap: wrap; gap: var(--admin-space-3, 8px); }
+.review-toolbar__status > span { color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); }
+.review-toolbar__actions { justify-content: flex-end; }
+.review-toolbar__actions :deep(.el-button) { margin-left: 0; }
+.review-toolbar__status > .review-toolbar__context { padding-left: var(--admin-space-3, 8px); border-left: 1px solid var(--cc-border); font-size: var(--admin-font-body, 13px); line-height: 1.55; overflow-wrap: anywhere; }
+.review-alert-title { display: inline-flex; align-items: center; gap: var(--admin-space-3, 8px); flex-wrap: wrap; }
+.review-data, .review-items { min-width: 0; padding: 0 0 var(--admin-space-5, 12px); border-bottom: 1px solid var(--cc-border); }
+.review-section-heading { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-6, 16px); margin-bottom: var(--admin-space-3, 8px); }
+.review-section-heading > div { min-width: 0; }
+.review-section-heading h3 { margin: 0; color: var(--cc-text); font-size: var(--admin-font-section, 14px); line-height: 1.35; }
+.review-section-heading > span { color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); white-space: nowrap; }
+.review-comparison { border-top: 1px solid var(--cc-border); }
+.review-comparison__row { display: grid; grid-template-columns: 78px minmax(0, 1fr); align-items: center; min-width: 0; padding: var(--admin-space-3, 8px) 0; }
+.review-comparison__row + .review-comparison__row { border-top: 1px dashed var(--cc-border); }
+.review-comparison__row > strong { color: #344054; font-size: var(--admin-font-caption, 12px); }
+.review-metrics, .review-declaration { display: grid; grid-template-columns: repeat(5, minmax(0, 1fr)); gap: var(--admin-space-3, 8px) var(--admin-space-6, 16px); min-width: 0; margin: 0; }
+.review-declaration { grid-template-columns: repeat(3, minmax(0, 1fr)); }
+.review-metrics > div, .review-declaration > div { display: flex; min-width: 0; align-items: baseline; gap: var(--admin-space-2, 6px); }
+.review-metrics dt, .review-declaration dt { color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); line-height: 1.4; }
+.review-metrics dd { margin: 0; overflow-wrap: anywhere; color: #172033; font-size: var(--admin-font-section, 14px); font-weight: 600; line-height: 1.35; }
+.review-metrics dd small, .review-declaration dd small { color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); font-weight: 500; }
+.review-metrics .review-metric--primary dd { color: #067647; }
+.review-declaration dd { margin: 0; overflow-wrap: anywhere; color: var(--cc-text); font-size: var(--admin-font-body, 13px); font-weight: 650; line-height: 1.4; }
+.review-table-scroll { width: 100%; min-width: 0; overflow: hidden; }
+.review-table { width: 100%; font-size: var(--admin-font-caption, 12px); }
+.review-table :deep(.el-table__header th) { padding: var(--admin-space-3, 8px) 0; background: #f6f8fa; color: #475467; font-size: var(--admin-font-caption, 12px); font-weight: 700; }
+.review-table :deep(.el-table__header .cell) { white-space: nowrap; }
+.review-table :deep(.el-table__cell) { padding: 7px 0; }
+.review-table :deep(.review-time-cell .cell) { white-space: nowrap; }
+.review-table :deep(.measurement-evidence-thumb) { min-width: 72px; border-radius: var(--admin-radius, 4px); }
+.review-image-preview { display: grid; min-height: 240px; place-items: center; }
+.review-image-preview img { display: block; width: auto; max-width: 100%; max-height: 70vh; object-fit: contain; }
+.review-image-preview__error { display: grid; justify-items: center; gap: var(--admin-space-3, 8px); color: var(--el-color-danger); }
+@media (max-width: 720px) {
+  .review-toolbar { align-items: stretch; flex-direction: column; margin: -14px -14px 0; padding: 12px 14px; }
+  .review-toolbar__status > .review-toolbar__context { width: 100%; padding-top: 8px; padding-left: 0; border-top: 1px solid var(--cc-border); border-left: 0; }
+  .review-toolbar__actions { display: grid; width: 100%; grid-template-columns: 1fr; justify-content: stretch; }
+  .review-toolbar__actions :deep(.el-button) { width: 100%; min-height: 44px; }
+  .review-section-heading { align-items: stretch; flex-direction: column; }
+  .review-comparison__row { grid-template-columns: 78px minmax(0, 1fr); align-items: start; }
+  .review-metrics, .review-declaration { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+}
+@media (max-width: 360px) {
+  .review-toolbar { margin: -10px -10px 0; padding: 10px; }
+  .review-comparison__row { grid-template-columns: 1fr; gap: 6px; }
+  .review-metrics, .review-declaration { grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 7px 10px; }
+}
+</style>
diff --git a/src/modules/inbounds/review/api.test.ts b/src/modules/inbounds/review/api.test.ts
new file mode 100644
index 00000000..50bfee3e
--- /dev/null
+++ b/src/modules/inbounds/review/api.test.ts
@@ -0,0 +1,41 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import {
+  approveMeasurement,
+  getMeasurementReviewDetail,
+  listMeasurementReviewHistory,
+} from './api'
+
+vi.mock('@/shared/api/http', () => ({
+  http: { get: vi.fn(), post: vi.fn() },
+  unwrapApiResponse: <T>(response: { data: T }) => response.data,
+}))
+
+describe('measurement review API', () => {
+  beforeEach(() => {
+    vi.mocked(http.get).mockReset()
+    vi.mocked(http.post).mockReset()
+  })
+
+  it('keeps the measurement detail and review history prefixes from the backend controllers', async () => {
+    vi.mocked(http.get)
+      .mockResolvedValueOnce({ code: '200', message: 'success', data: { measurementId: '7' } })
+      .mockResolvedValueOnce({ code: '200', message: 'success', data: { records: [], page: '1', size: '20', total: '0', pages: '0' } })
+
+    await getMeasurementReviewDetail('10001', '90001')
+    await listMeasurementReviewHistory('10001', '90001')
+
+    expect(http.get).toHaveBeenNthCalledWith(1, '/platform/v1/first-leg/inbounds/90001/measurement', { params: { tenantId: '10001' } })
+    expect(http.get).toHaveBeenNthCalledWith(2, '/platform/v1/inbounds/90001/measurement-review-history', { params: { tenantId: '10001', page: 1, size: 20 } })
+  })
+
+  it('normalizes string pagination and sends idempotency headers for review writes', async () => {
+    vi.mocked(http.get).mockResolvedValue({ code: '200', message: 'success', data: { records: [], page: '2', size: '20', total: '3', pages: '1' } })
+    vi.mocked(http.post).mockResolvedValue({ code: '200', message: 'success', data: null })
+
+    await expect(listMeasurementReviewHistory('10001', '90001', 2, 20)).resolves.toMatchObject({ page: 2, total: 3 })
+    await approveMeasurement('10001', '90001', { measurementId: '7', expectedVersion: 4 }, 'approve-key')
+    expect(http.post).toHaveBeenNthCalledWith(1, '/platform/v1/inbounds/90001/measurements/approve', { measurementId: '7', expectedVersion: 4 }, { params: { tenantId: '10001' }, headers: { 'Idempotency-Key': 'approve-key' } })
+    expect(http.post).toHaveBeenCalledTimes(1)
+  })
+})
diff --git a/src/modules/inbounds/review/api.ts b/src/modules/inbounds/review/api.ts
new file mode 100644
index 00000000..62d7cdc4
--- /dev/null
+++ b/src/modules/inbounds/review/api.ts
@@ -0,0 +1,71 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import type {
+  MeasurementApprovalResponse,
+  MeasurementReviewDetail,
+  MeasurementReviewHistoryPage,
+  MeasurementReviewHistoryPayload,
+  MeasurementReviewRequest,
+} from './types'
+
+async function getData<T>(path: string, params: Record<string, unknown>) {
+  const response = await http.get<ApiEnvelope<T>, ApiEnvelope<T>>(path, { params })
+  return unwrapApiResponse(response)
+}
+
+function idempotencyKey() {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') return crypto.randomUUID()
+  return `review-${Date.now()}-${Math.random().toString(36).slice(2)}`
+}
+
+async function postReview<T>(path: string, tenantId: string, body: unknown, key = idempotencyKey()) {
+  const response = await http.post<ApiEnvelope<T>, ApiEnvelope<T>>(path, body, {
+    params: { tenantId },
+    headers: { 'Idempotency-Key': key },
+  })
+  return unwrapApiResponse(response)
+}
+
+function paginationNumber(value: number | string, fallback: number) {
+  const parsed = Number(value)
+  return Number.isFinite(parsed) && parsed >= 0 ? Math.trunc(parsed) : fallback
+}
+
+export function getMeasurementReviewDetail(tenantId: string, inboundId: string) {
+  return getData<MeasurementReviewDetail>(
+    `/platform/v1/first-leg/inbounds/${inboundId}/measurement`,
+    { tenantId },
+  )
+}
+
+export async function listMeasurementReviewHistory(
+  tenantId: string,
+  inboundId: string,
+  page = 1,
+  size = 20,
+) {
+  const result = await getData<MeasurementReviewHistoryPayload>(
+    `/platform/v1/inbounds/${inboundId}/measurement-review-history`,
+    { tenantId, page, size },
+  )
+  return {
+    ...result,
+    page: paginationNumber(result.page, page),
+    size: paginationNumber(result.size, size),
+    total: paginationNumber(result.total, 0),
+    pages: paginationNumber(result.pages, 0),
+  } satisfies MeasurementReviewHistoryPage
+}
+
+export function approveMeasurement(
+  tenantId: string,
+  inboundId: string,
+  request: MeasurementReviewRequest,
+  key?: string,
+) {
+  return postReview<MeasurementApprovalResponse>(
+    `/platform/v1/inbounds/${inboundId}/measurements/approve`,
+    tenantId,
+    request,
+    key,
+  )
+}
diff --git a/src/modules/inbounds/review/index.ts b/src/modules/inbounds/review/index.ts
new file mode 100644
index 00000000..369df2dd
--- /dev/null
+++ b/src/modules/inbounds/review/index.ts
@@ -0,0 +1,3 @@
+export { default as MeasurementReviewPanel } from './MeasurementReviewPanel.vue'
+export * from './api'
+export type * from './types'
diff --git a/src/modules/inbounds/review/types.ts b/src/modules/inbounds/review/types.ts
new file mode 100644
index 00000000..0ab2b032
--- /dev/null
+++ b/src/modules/inbounds/review/types.ts
@@ -0,0 +1,141 @@
+export type MeasurementReviewStatus = 'PENDING' | 'APPROVED' | 'REJECTED' | string
+
+export interface MeasurementReviewItem {
+  id: string
+  boxCode: string | null
+  itemNo: string
+  boxSpecification: string | null
+  packageCount: number | null
+  lengthCm: number | null
+  widthCm: number | null
+  heightCm: number | null
+  girthCm: number | null
+  unitWeightKg: number | null
+  unitVolumeCbm: number | null
+  totalWeightKg: number | null
+  totalVolumeCbm: number | null
+  volumeWeightKg: number | null
+  intelligentImageFileId: string | null
+  machineNo: string | null
+  deviceMeasuredAt: string | null
+  overLimitWarning: string | null
+  outerLengthCm: number | null
+  outerWidthCm: number | null
+  outerHeightCm: number | null
+  remark: string | null
+}
+
+export interface MeasurementReviewWeightResult {
+  id: string
+  fileId: string | null
+  palletId: string
+  palletCode: string
+  palletType: string
+  palletCapacityCbm: number
+  palletTareWeightKg: number
+  ocrProvider: string | null
+  ocrRawText: string | null
+  ocrWeightValue: number | null
+  ocrWeightUnit: string | null
+  confidence: number | null
+  adjustedWeightValue: number | null
+  adjustedWeightUnit: string | null
+  grossWeightKg: number | null
+  netWeightKg: number | null
+  recognitionStatus: string | null
+  adjustmentReason: string | null
+  adjustedBy: string | null
+  adjustedAt: string | null
+  confirmedBy: string | null
+  confirmedAt: string | null
+  version: number
+}
+
+export interface MeasurementReviewDetail {
+  inboundId: string
+  inboundCode: string | null
+  companyName: string | null
+  channelCode: string | null
+  channelName: string | null
+  processStatus: string | null
+  measureReviewStatus: MeasurementReviewStatus | null
+  recommendedPalletType: string | null
+  reviewReason: string | null
+  reviewerId: string | null
+  reviewerName: string | null
+  measurementId: string
+  sourceType: string | null
+  measurementStatus: string | null
+  /** 入库单乐观锁版本；审核接口 expectedVersion 使用此字段。 */
+  inboundVersion: number
+  /** 测量批次自身版本，不用于入库单状态审核。 */
+  version: number
+  originalDocumentNo: string | null
+  originalGrossWeightKg: number | null
+  originalVolumeCbm: number | null
+  originalPackageCount: number | null
+  actualPackageCount: number | null
+  actualGrossWeightKg: number | null
+  actualNetWeightKg: number | null
+  actualVolumeCbm: number | null
+  volumeWeightKg: number | null
+  actualGoodsName: string | null
+  items: MeasurementReviewItem[]
+  weightResults: MeasurementReviewWeightResult[]
+}
+
+export interface MeasurementReviewRecord {
+  id: string
+  tenantId: string
+  inboundId: string
+  measurementId: string
+  reviewResult: string | null
+  reviewReason: string | null
+  exceptionRelease: boolean
+  releaseReason: string | null
+  allowRejectedConfig: boolean
+  reviewerName: string | null
+  reviewedAt: string | null
+}
+
+export interface MeasurementReviewHistoryPage {
+  records: MeasurementReviewRecord[]
+  page: number
+  size: number
+  total: number
+  pages: number
+}
+
+export interface MeasurementReviewHistoryPayload extends Omit<MeasurementReviewHistoryPage, 'page' | 'size' | 'total' | 'pages'> {
+  page: number | string
+  size: number | string
+  total: number | string
+  pages: number | string
+}
+
+export interface MeasurementReviewRequest {
+  measurementId: string
+  expectedVersion: number
+  reason?: string
+}
+
+export interface MeasurementApprovalResponse {
+  inboundId: string | null
+  measurementId: string | null
+  processStatus: 'WAIT_SPLIT' | string
+  feeStatus: 'CALCULATED' | 'UNPRICED' | string
+  initialPricingSucceeded: boolean
+  initialPricingMessage: string | null
+  initialFee: FeeSnapshotAfterApprove | null
+}
+
+export interface FeeSnapshotAfterApprove {
+  feeId: string | null
+  feeNo: string | null
+  feeVersion: number | null
+  feeStatus: string | null
+  inboundId: string | null
+  totalAmount: number | null
+  currency: string | null
+  nextProcessStatus: string | null
+}
diff --git a/src/modules/inbounds/routes.ts b/src/modules/inbounds/routes.ts
new file mode 100644
index 00000000..3aa0d1d2
--- /dev/null
+++ b/src/modules/inbounds/routes.ts
@@ -0,0 +1,34 @@
+import type { RouteRecordRaw } from 'vue-router'
+
+export const inboundRoutes = [
+  {
+    path: 'inbounds/measurements',
+    name: 'inbound-measurements',
+    component: () => import('./pages/InboundMeasurementsView.vue'),
+    meta: {
+      title: '订单测量',
+      description: '只展示当前可录入或修正测量数据的国内仓订单',
+      permission: 'platform:firstleg:inbound:measure:view',
+    },
+  },
+  {
+    path: 'inbounds/measurement-reviews',
+    name: 'inbound-measurement-reviews',
+    component: () => import('./pages/MeasurementReviewsView.vue'),
+    meta: {
+      title: '测量数据审核',
+      description: '处理待审核且当前可审核的国内仓测量数据',
+      permission: 'firstleg:inbound:measurement-review',
+    },
+  },
+  {
+    path: 'inbounds',
+    name: 'inbound-orders',
+    redirect: '/orders',
+    meta: {
+      title: '订单列表',
+      description: '旧入库列表入口已合并到统一订单列表',
+      permission: 'platform:firstleg:inbound:list',
+    },
+  },
+] satisfies RouteRecordRaw[]
diff --git a/src/modules/inbounds/status.test.ts b/src/modules/inbounds/status.test.ts
new file mode 100644
index 00000000..7ac157cb
--- /dev/null
+++ b/src/modules/inbounds/status.test.ts
@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest'
+import { inboundHistoryActionLabel, inboundOrderStatusLabels, inboundProcessStatusLabels, inboundStatusLabel } from './status'
+
+describe('inbound status presentation', () => {
+  it('translates process and order statuses', () => {
+    expect(inboundStatusLabel('PREPARING', inboundProcessStatusLabels)).toBe('订单待审核（可先测量）')
+    expect(inboundStatusLabel('MEASURE_PENDING', inboundProcessStatusLabels)).toBe('待测量审核')
+    expect(inboundStatusLabel('WAIT_SPLIT', inboundOrderStatusLabels)).toBe('待分柜')
+  })
+
+  it('does not expose unknown status and action codes', () => {
+    expect(inboundStatusLabel('NEW_STATUS', inboundProcessStatusLabels)).toBe('未知状态')
+    expect(inboundHistoryActionLabel('NEW_ACTION')).toBe('状态更新')
+  })
+})
diff --git a/src/modules/inbounds/status.ts b/src/modules/inbounds/status.ts
new file mode 100644
index 00000000..894f3b45
--- /dev/null
+++ b/src/modules/inbounds/status.ts
@@ -0,0 +1,47 @@
+export const inboundProcessStatusLabels: Record<string, string> = {
+  PREPARING: '订单待审核（可先测量）', WAIT_MEASURE: '待测量', MEASURING: '测量中', MEASURE_PENDING: '待测量审核', MEASURE_REJECTED: '测量已驳回',
+  WAIT_PRICING: '待计费', FEE_CONFIRMING: '费用处理中', INBOUNDING: '入库处理中', WAIT_PALLETIZE: '待一件代发组托', WAIT_SPLIT: '待分柜', VOIDED: '已作废',
+}
+
+export const inboundOrderStatusLabels: Record<string, string> = {
+  DRAFT: '草稿', SUBMITTED: '待审核', APPROVED: '已审核', ACCEPTED: '已受理', REJECTED: '已驳回',
+  PROCESSING: '处理中', COMPLETED: '已完成', CANCELLED: '已取消', PENDING_REVIEW: '待审核',
+  WAIT_MEASURE: '待测量', WAIT_PALLETIZE: '待一件代发组托', WAIT_SPLIT: '待分柜', LOADING: '装柜中',
+  LOADED: '装柜完成', DELIVERED: '派送完成',
+}
+
+export const inboundReviewStatusLabels: Record<string, string> = {
+  NOT_SUBMITTED: '未提交', UNRECORDED: '未录入', PENDING: '待审核', APPROVED: '审核通过', REJECTED: '审核驳回', CONFIRMED: '已确认',
+}
+
+export const inboundFeeStatusLabels: Record<string, string> = {
+  UNPRICED: '未计费', CALCULATED: '已试算', CONFIRMED: '已确认', SENT: '已发送', VOIDED: '已作废',
+}
+
+export const inboundLoadingStatusLabels: Record<string, string> = {
+  NOT_LOADED: '未配载', WAIT_LOADING: '待配载', EDITING: '预装柜中', LOADING: '配载中', LOADED: '已配载', COMPLETED: '装柜完成',
+}
+
+export const inboundNotificationStatusLabels: Record<string, string> = {
+  NOT_CREATED: '未创建', PENDING: '待发送', SUCCESS: '发送成功', FAILED: '发送失败',
+}
+
+export const weightRecognitionStatusLabels: Record<string, string> = {
+  PENDING: '待识别', PENDING_CONFIRM: '待确认', NEEDS_MANUAL: '需人工录入', CONFIRMED: '已确认',
+}
+
+const inboundHistoryActionLabels: Record<string, string> = {
+  CREATE: '创建入库单', STATUS_UPDATE: '状态更新', MEASURE_SUBMIT: '提交测量', MEASURE_APPROVE: '测量审核通过',
+  MEASURE_REJECT: '测量审核驳回', FEE_CALCULATE: '费用试算', FEE_CONFIRM: '费用确认',
+  INBOUND_BEGIN: '开始入库', INBOUND_COMPLETE: '完成入库', VOID: '作废入库单',
+}
+
+export function inboundStatusLabel(value: string | null | undefined, labels: Record<string, string>, emptyLabel = '—') {
+  if (!value) return emptyLabel
+  return labels[value] || '未知状态'
+}
+
+export function inboundHistoryActionLabel(value: string | null | undefined) {
+  if (!value) return '状态更新'
+  return inboundHistoryActionLabels[value] || '状态更新'
+}
diff --git a/src/modules/inbounds/task-list.test.ts b/src/modules/inbounds/task-list.test.ts
new file mode 100644
index 00000000..94e65921
--- /dev/null
+++ b/src/modules/inbounds/task-list.test.ts
@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest'
+import { buildInboundTaskQuery } from './task-list'
+
+describe('inbound task list query', () => {
+  it('limits the measurement page to currently measurable inbound orders', () => {
+    expect(buildInboundTaskQuery('measurement', { page: 1, size: 20, inboundCode: 'RK-1' })).toEqual({
+      page: 1,
+      size: 20,
+      inboundCode: 'RK-1',
+      tab: 'WAIT_MEASURE',
+    })
+  })
+
+  it('limits the review page to pending and reviewable measurement data', () => {
+    expect(buildInboundTaskQuery('review', { page: 2, size: 50, warehouseId: '20001' })).toEqual({
+      page: 2,
+      size: 50,
+      warehouseId: '20001',
+      tab: 'WAIT_REVIEW',
+      measureReviewStatus: 'PENDING',
+    })
+  })
+})
diff --git a/src/modules/inbounds/task-list.ts b/src/modules/inbounds/task-list.ts
new file mode 100644
index 00000000..de46da39
--- /dev/null
+++ b/src/modules/inbounds/task-list.ts
@@ -0,0 +1,48 @@
+import type { PlatformTenantResource } from '@/modules/iam'
+import type { InboundListQuery } from './core/types'
+
+export type InboundTaskMode = 'measurement' | 'review'
+
+export interface ActiveCustomerPage {
+  records: PlatformTenantResource[]
+  pages: number
+}
+
+export interface ActiveCustomerQuery {
+  page: number
+  size: number
+  status: 'ACTIVE'
+}
+
+export async function loadAllActiveCustomers(
+  fetchPage: (query: ActiveCustomerQuery) => Promise<ActiveCustomerPage>,
+) {
+  const records: PlatformTenantResource[] = []
+  let page = 1
+  let pages = 1
+  do {
+    const response = await fetchPage({ page, size: 200, status: 'ACTIVE' })
+    records.push(...response.records)
+    pages = Math.max(1, response.pages)
+    page += 1
+  } while (page <= pages)
+  return records
+}
+
+export function buildInboundTaskQuery(
+  mode: InboundTaskMode,
+  query: Omit<InboundListQuery, 'tab' | 'processStatus' | 'measureReviewStatus'>,
+): InboundListQuery {
+  if (mode === 'review') {
+    return {
+      ...query,
+      tab: 'WAIT_REVIEW',
+      measureReviewStatus: 'PENDING',
+    }
+  }
+
+  return {
+    ...query,
+    tab: 'WAIT_MEASURE',
+  }
+}
diff --git a/src/modules/inbounds/weight/api/weightOcr.test.ts b/src/modules/inbounds/weight/api/weightOcr.test.ts
new file mode 100644
index 00000000..52b5298e
--- /dev/null
+++ b/src/modules/inbounds/weight/api/weightOcr.test.ts
@@ -0,0 +1,196 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import {
+  confirmWeightResult,
+  correctWeightResult,
+  createWeightResult,
+  deleteWeightResult,
+  downloadWeightImage,
+  downloadWeightThumbnail,
+  getWeightOcrRawText,
+  getWeightPalletOptions,
+  getWeightWorkspace,
+  normalizeWeightConfidence,
+  retryWeightRecognition,
+  uploadWeightImage,
+} from './weightOcr'
+
+vi.mock('@/shared/api/http', () => ({
+  http: { delete: vi.fn(), get: vi.fn(), post: vi.fn(), put: vi.fn() },
+  ApiResponseError: class ApiResponseError extends Error {},
+  unwrapApiResponse: <T>(response: { data: T }) => response.data,
+}))
+
+describe('inbound weight OCR API', () => {
+  beforeEach(() => {
+    vi.mocked(http.get).mockReset()
+    vi.mocked(http.delete).mockReset()
+    vi.mocked(http.post).mockReset()
+    vi.mocked(http.put).mockReset()
+  })
+
+  it('normalizes OCR confidence to the firstleg decimal contract', () => {
+    expect(normalizeWeightConfidence(0.5097191334)).toBe(0.50972)
+    expect(normalizeWeightConfidence(1.2)).toBe(1)
+    expect(normalizeWeightConfidence(-0.2)).toBe(0)
+    expect(normalizeWeightConfidence(Number.NaN)).toBeNull()
+    expect(normalizeWeightConfidence(null)).toBeNull()
+  })
+
+  it('accepts current and compatible OCR raw-text response fields', () => {
+    const upload = {
+      fileId: '1',
+      fileName: 'weight.jpg',
+      contentType: 'image/jpeg',
+      sizeBytes: 100,
+      recognitionStatus: 'SUCCESS',
+      weightValue: 12.5,
+      weightUnit: 'KG',
+      confidence: 0.98,
+      error: null,
+    }
+    expect(getWeightOcrRawText({ ...upload, ocrRawText: '  12.5 KG  ' })).toBe('12.5 KG')
+    expect(getWeightOcrRawText({ ...upload, rawText: 'display: 12.5' })).toBe('display: 12.5')
+    expect(getWeightOcrRawText(upload)).toBeNull()
+  })
+
+  it('loads the measurement workspace using the real firstleg path', async () => {
+    const detail = { inboundId: '9007199254740993', weightResults: [] }
+    vi.mocked(http.get).mockResolvedValue({ code: '200', message: 'success', data: detail })
+
+    await expect(getWeightWorkspace('10001', '9007199254740993')).resolves.toEqual(detail)
+    expect(http.get).toHaveBeenCalledWith(
+      '/platform/v1/first-leg/inbounds/9007199254740993/measurement',
+      { params: { tenantId: '10001' } },
+    )
+  })
+
+  it('uploads and retries against the file service without converting long IDs', async () => {
+    const result = { fileId: '9007199254740995', recognitionStatus: 'SUCCESS' }
+    vi.mocked(http.post).mockResolvedValue({ code: '200', message: 'success', data: result })
+    const file = new File(['image'], 'weight.png', { type: 'image/png' })
+
+    await expect(uploadWeightImage('10001', '9007199254740993', file)).resolves.toEqual(result)
+    const [uploadPath, body] = vi.mocked(http.post).mock.calls[0]!
+    expect(uploadPath).toBe('/platform/v1/files/measurements/10001/9007199254740993')
+    expect(body).toBeInstanceOf(FormData)
+    expect((body as FormData).get('file')).toBe(file)
+
+    await retryWeightRecognition('10001', '9007199254740993', '9007199254740995')
+    expect(http.post).toHaveBeenLastCalledWith(
+      '/platform/v1/files/measurements/10001/9007199254740993/9007199254740995/recognize',
+    )
+  })
+
+  it('normalizes the formal paged pallet response returned by Firstleg', async () => {
+    const records = [
+      { palletId: '2092803000000000001', palletCode: 'TP-11', palletType: '木托盘', capacityCbm: 1.2, tareWeightKg: 12 },
+      { palletId: '2092803000000000002', palletCode: 'TP-12', palletType: '塑料托盘', capacityCbm: 1.1, tareWeightKg: 10 },
+    ]
+    vi.mocked(http.get).mockResolvedValue({
+      code: '200',
+      message: 'success',
+      data: { records, page: '1', size: '20', total: '2', pages: '1' },
+    })
+
+    await expect(getWeightPalletOptions('10001', '20001', { page: 1, size: 50 })).resolves.toEqual({
+      records, page: 1, size: 20, total: 2, pages: 1,
+    })
+    expect(http.get).toHaveBeenCalledWith(
+      '/platform/v1/first-leg/inbounds/20001/weight-pallet-options',
+      { params: { tenantId: '10001', page: 1, size: 50, keyword: undefined } },
+    )
+  })
+
+  it('passes remote page, keyword and abort signal through the frozen pallet endpoint', async () => {
+    vi.mocked(http.get).mockResolvedValue({
+      code: '200', message: 'success', data: { records: [], page: '1', size: '20', total: '0', pages: '0' },
+    })
+    const controller = new AbortController()
+
+    await getWeightPalletOptions('10001', '20001', { page: 2, size: 50, keyword: ' 木托盘 ', signal: controller.signal })
+
+    expect(http.get).toHaveBeenCalledWith(
+      '/platform/v1/first-leg/inbounds/20001/weight-pallet-options',
+      { params: { tenantId: '10001', page: 2, size: 50, keyword: '木托盘' }, signal: controller.signal },
+    )
+  })
+
+  it('registers, corrects, and confirms a weight result using the implemented contracts', async () => {
+    vi.mocked(http.post).mockResolvedValue({ code: '200', message: 'success', data: { id: '1' } })
+    vi.mocked(http.put).mockResolvedValue({ code: '200', message: 'success', data: { id: '1', version: 1 } })
+
+    const createPayload = {
+      fileId: '9007199254740995',
+      palletId: '11',
+      ocrProvider: 'FILE_WEIGHT_OCR',
+      ocrRawText: null,
+      ocrWeightValue: 12.5,
+      ocrWeightUnit: 'KG',
+      confidence: 0.5097191334,
+    }
+    await createWeightResult('10001', '20001', createPayload)
+    expect(http.post).toHaveBeenNthCalledWith(
+      1,
+      '/platform/v1/first-leg/inbounds/20001/weight-results',
+      { ...createPayload, confidence: 0.50972 },
+      { params: { tenantId: '10001' } },
+    )
+
+    const correction = { version: 0, adjustedWeightValue: 12.8, adjustedWeightUnit: 'KG' as const, adjustmentReason: '读数模糊' }
+    await correctWeightResult('10001', '20001', '30001', correction)
+    expect(http.put).toHaveBeenCalledWith(
+      '/platform/v1/first-leg/inbounds/20001/weight-results/30001',
+      correction,
+      { params: { tenantId: '10001' } },
+    )
+
+    await confirmWeightResult('10001', '20001', '30001', { version: 1 })
+    expect(http.post).toHaveBeenLastCalledWith(
+      '/platform/v1/first-leg/inbounds/20001/weight-results/30001/confirm',
+      { version: 1 },
+      { params: { tenantId: '10001' } },
+    )
+
+    const confirmWithAdjustment = {
+      version: 0,
+      adjustedWeightValue: 286.125,
+      adjustedWeightUnit: 'KG' as const,
+      adjustmentReason: 'OCR 原值 285.500 KG，人工确认 286.125 KG',
+    }
+    await confirmWeightResult('10001', '20001', '30002', confirmWithAdjustment)
+    expect(http.post).toHaveBeenLastCalledWith(
+      '/platform/v1/first-leg/inbounds/20001/weight-results/30002/confirm',
+      confirmWithAdjustment,
+      { params: { tenantId: '10001' } },
+    )
+  })
+
+  it('downloads an authenticated image as a blob', async () => {
+    const image = new Blob(['png'], { type: 'image/png' })
+    vi.mocked(http.get).mockResolvedValue(image)
+    await expect(downloadWeightImage('10001', '20001', '40001')).resolves.toBe(image)
+    expect(http.get).toHaveBeenCalledWith(
+      '/platform/v1/files/measurements/10001/20001/40001',
+      { responseType: 'blob' },
+    )
+  })
+
+  it('downloads a thumbnail and deletes a result without converting long IDs', async () => {
+    const image = new Blob(['jpg'], { type: 'image/jpeg' })
+    vi.mocked(http.get).mockResolvedValue(image)
+    vi.mocked(http.delete).mockResolvedValue({ code: '200', message: 'success', data: null })
+
+    await expect(downloadWeightThumbnail('10001', '20001', '9007199254740995')).resolves.toBe(image)
+    expect(http.get).toHaveBeenCalledWith(
+      '/platform/v1/files/measurements/10001/20001/9007199254740995/thumbnail',
+      { responseType: 'blob' },
+    )
+
+    await deleteWeightResult('10001', '20001', '9007199254740997', 3)
+    expect(http.delete).toHaveBeenCalledWith(
+      '/platform/v1/first-leg/inbounds/20001/weight-results/9007199254740997',
+      { params: { tenantId: '10001', version: 3 } },
+    )
+  })
+})
diff --git a/src/modules/inbounds/weight/api/weightOcr.ts b/src/modules/inbounds/weight/api/weightOcr.ts
new file mode 100644
index 00000000..5fe7b276
--- /dev/null
+++ b/src/modules/inbounds/weight/api/weightOcr.ts
@@ -0,0 +1,210 @@
+import axios from 'axios'
+import { ApiResponseError, http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import type {
+  ConfirmWeightResultRequest,
+  CorrectWeightResultRequest,
+  CreateWeightResultRequest,
+  WeightImageUploadResult,
+  WeightPalletOption,
+  WeightPalletOptionPage,
+  WeightResultResource,
+  WeightWorkspaceResource,
+} from '../types'
+
+const measurementBasePath = '/platform/v1/first-leg/inbounds'
+const imageBasePath = '/platform/v1/files/measurements'
+const maxErrorEnvelopeBytes = 1024 * 1024
+const confidenceScale = 100_000
+
+interface WeightPalletOptionPageResponse {
+  records: WeightPalletOption[]
+  page: number | string
+  size: number | string
+  total: number | string
+  pages: number | string
+}
+
+function segment(value: string) {
+  return encodeURIComponent(value)
+}
+
+function normalizedPageNumber(value: number | string, fallback: number, minimum: number) {
+  const parsed = typeof value === 'number' ? value : Number(value)
+  return Number.isFinite(parsed) ? Math.max(minimum, Math.trunc(parsed)) : fallback
+}
+
+export function normalizeWeightConfidence(value: number | null) {
+  if (value == null || !Number.isFinite(value)) return null
+  const clamped = Math.min(1, Math.max(0, value))
+  return Math.round(clamped * confidenceScale) / confidenceScale
+}
+
+export function getWeightOcrRawText(result: WeightImageUploadResult) {
+  const rawText = result.ocrRawText ?? result.rawText
+  if (typeof rawText !== 'string') return null
+  const normalized = rawText.trim()
+  return normalized ? normalized.slice(0, 1000) : null
+}
+
+async function parseBlobError(blob: Blob, status?: number) {
+  if (!blob.type.toLowerCase().includes('json')) return null
+  if (blob.size > maxErrorEnvelopeBytes) {
+    return new ApiResponseError('图片接口返回了超出限制的 JSON 响应', 'INVALID_IMAGE_RESPONSE', status)
+  }
+  try {
+    const payload = JSON.parse(await blob.text()) as Partial<ApiEnvelope<unknown>>
+    return new ApiResponseError(
+      payload.code === '200' ? '图片接口未返回图片内容' : payload.message || '称重图片读取失败',
+      payload.code === '200' ? 'INVALID_IMAGE_RESPONSE' : payload.code || (status ? `HTTP_${status}` : 'IMAGE_FAILED'),
+      status,
+      payload.data,
+      payload.requestId,
+      payload.traceId,
+    )
+  } catch {
+    return new ApiResponseError('图片接口返回了无法识别的响应', 'INVALID_IMAGE_RESPONSE', status)
+  }
+}
+
+export async function getWeightWorkspace(tenantId: string, inboundId: string) {
+  const response = await http.get<ApiEnvelope<WeightWorkspaceResource>, ApiEnvelope<WeightWorkspaceResource>>(
+    `${measurementBasePath}/${segment(inboundId)}/measurement`,
+    { params: { tenantId } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function getWeightPalletOptions(tenantId: string, inboundId: string, query: {
+  page?: number
+  size?: number
+  keyword?: string
+  signal?: AbortSignal
+} = {}) {
+  const keyword = query.keyword?.trim()
+  const response = await http.get<ApiEnvelope<WeightPalletOptionPageResponse>, ApiEnvelope<WeightPalletOptionPageResponse>>(
+    `${measurementBasePath}/${segment(inboundId)}/weight-pallet-options`,
+    {
+      params: { tenantId, page: query.page ?? 1, size: query.size ?? 50, keyword: keyword || undefined },
+      ...(query.signal ? { signal: query.signal } : {}),
+    },
+  )
+  const page = unwrapApiResponse(response)
+  return {
+    records: page.records,
+    page: normalizedPageNumber(page.page, 1, 1),
+    size: normalizedPageNumber(page.size, page.records.length, 0),
+    total: normalizedPageNumber(page.total, page.records.length, 0),
+    pages: normalizedPageNumber(page.pages, 0, 0),
+  } satisfies WeightPalletOptionPage
+}
+
+export async function uploadWeightImage(tenantId: string, inboundId: string, file: File) {
+  const body = new FormData()
+  body.append('file', file)
+  const response = await http.post<ApiEnvelope<WeightImageUploadResult>, ApiEnvelope<WeightImageUploadResult>>(
+    `${imageBasePath}/${segment(tenantId)}/${segment(inboundId)}`,
+    body,
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function retryWeightRecognition(tenantId: string, inboundId: string, fileId: string) {
+  const response = await http.post<ApiEnvelope<WeightImageUploadResult>, ApiEnvelope<WeightImageUploadResult>>(
+    `${imageBasePath}/${segment(tenantId)}/${segment(inboundId)}/${segment(fileId)}/recognize`,
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function downloadWeightImage(tenantId: string, inboundId: string, fileId: string) {
+  try {
+    const blob = await http.get<Blob, Blob>(
+      `${imageBasePath}/${segment(tenantId)}/${segment(inboundId)}/${segment(fileId)}`,
+      { responseType: 'blob' },
+    )
+    const responseError = await parseBlobError(blob, 200)
+    if (responseError) throw responseError
+    return blob
+  } catch (error) {
+    if (axios.isAxiosError(error) && error.response?.data instanceof Blob) {
+      const responseError = await parseBlobError(error.response.data, error.response.status)
+      if (responseError) throw responseError
+    }
+    throw error
+  }
+}
+
+export async function downloadWeightThumbnail(tenantId: string, inboundId: string, fileId: string) {
+  try {
+    const blob = await http.get<Blob, Blob>(
+      `${imageBasePath}/${segment(tenantId)}/${segment(inboundId)}/${segment(fileId)}/thumbnail`,
+      { responseType: 'blob' },
+    )
+    const responseError = await parseBlobError(blob, 200)
+    if (responseError) throw responseError
+    return blob
+  } catch (error) {
+    if (axios.isAxiosError(error) && error.response?.data instanceof Blob) {
+      const responseError = await parseBlobError(error.response.data, error.response.status)
+      if (responseError) throw responseError
+    }
+    throw error
+  }
+}
+
+export async function createWeightResult(
+  tenantId: string,
+  inboundId: string,
+  payload: CreateWeightResultRequest,
+) {
+  const normalizedPayload = {
+    ...payload,
+    confidence: normalizeWeightConfidence(payload.confidence),
+  }
+  const response = await http.post<ApiEnvelope<WeightResultResource>, ApiEnvelope<WeightResultResource>>(
+    `${measurementBasePath}/${segment(inboundId)}/weight-results`,
+    normalizedPayload,
+    { params: { tenantId } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function correctWeightResult(
+  tenantId: string,
+  inboundId: string,
+  resultId: string,
+  payload: CorrectWeightResultRequest,
+) {
+  const response = await http.put<ApiEnvelope<WeightResultResource>, ApiEnvelope<WeightResultResource>>(
+    `${measurementBasePath}/${segment(inboundId)}/weight-results/${segment(resultId)}`,
+    payload,
+    { params: { tenantId } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function confirmWeightResult(
+  tenantId: string,
+  inboundId: string,
+  resultId: string,
+  payload: ConfirmWeightResultRequest,
+) {
+  const response = await http.post<ApiEnvelope<WeightResultResource>, ApiEnvelope<WeightResultResource>>(
+    `${measurementBasePath}/${segment(inboundId)}/weight-results/${segment(resultId)}/confirm`,
+    payload,
+    { params: { tenantId } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function deleteWeightResult(
+  tenantId: string,
+  inboundId: string,
+  resultId: string,
+  version: number,
+) {
+  const response = await http.delete<ApiEnvelope<null>, ApiEnvelope<null>>(
+    `${measurementBasePath}/${segment(inboundId)}/weight-results/${segment(resultId)}`,
+    { params: { tenantId, version } },
+  )
+  unwrapApiResponse(response)
+}
diff --git a/src/modules/inbounds/weight/components/WeightImageThumbnail.test.ts b/src/modules/inbounds/weight/components/WeightImageThumbnail.test.ts
new file mode 100644
index 00000000..cc445e8b
--- /dev/null
+++ b/src/modules/inbounds/weight/components/WeightImageThumbnail.test.ts
@@ -0,0 +1,44 @@
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { downloadWeightThumbnail } from '../api/weightOcr'
+import WeightImageThumbnail from './WeightImageThumbnail.vue'
+
+vi.mock('../api/weightOcr', () => ({
+  downloadWeightThumbnail: vi.fn(),
+}))
+
+enableAutoUnmount(afterEach)
+
+describe('WeightImageThumbnail', () => {
+  const createObjectURL = vi.fn(() => 'blob:thumbnail')
+  const revokeObjectURL = vi.fn()
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.stubGlobal('URL', { createObjectURL, revokeObjectURL })
+  })
+
+  it('loads an authenticated thumbnail and releases its object URL', async () => {
+    vi.mocked(downloadWeightThumbnail).mockResolvedValue(new Blob(['image'], { type: 'image/jpeg' }))
+    const wrapper = mount(WeightImageThumbnail, {
+      props: { customerId: '10001', inboundId: '20001', fileId: '30001', alt: '称重图片 1' },
+    })
+    await flushPromises()
+
+    expect(downloadWeightThumbnail).toHaveBeenCalledWith('10001', '20001', '30001')
+    expect(wrapper.get('img').attributes('src')).toBe('blob:thumbnail')
+    await wrapper.unmount()
+    expect(revokeObjectURL).toHaveBeenCalledWith('blob:thumbnail')
+  })
+
+  it('shows a stable failure state when the thumbnail cannot be read', async () => {
+    vi.mocked(downloadWeightThumbnail).mockRejectedValue(new Error('network'))
+    const wrapper = mount(WeightImageThumbnail, {
+      props: { customerId: '10001', inboundId: '20001', fileId: '30001', alt: '称重图片 1' },
+    })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('图片加载失败')
+    expect(wrapper.find('img').exists()).toBe(false)
+  })
+})
diff --git a/src/modules/inbounds/weight/components/WeightImageThumbnail.vue b/src/modules/inbounds/weight/components/WeightImageThumbnail.vue
new file mode 100644
index 00000000..f3da8e33
--- /dev/null
+++ b/src/modules/inbounds/weight/components/WeightImageThumbnail.vue
@@ -0,0 +1,24 @@
+<script setup lang="ts">
+import MeasurementEvidenceThumbnail from '../../measurement/components/MeasurementEvidenceThumbnail.vue'
+
+const props = defineProps<{
+  customerId: string
+  inboundId: string
+  fileId: string | null
+  alt: string
+}>()
+
+defineEmits<{ open: [] }>()
+</script>
+
+<template>
+  <MeasurementEvidenceThumbnail
+    class="weight-thumb"
+    :customer-id="props.customerId"
+    :inbound-id="props.inboundId"
+    :file-id="props.fileId"
+    :alt="props.alt"
+    empty-text="未绑定称重图片"
+    @open="$emit('open')"
+  />
+</template>
diff --git a/src/modules/inbounds/weight/components/WeightOcrPanel.behavior.test.ts b/src/modules/inbounds/weight/components/WeightOcrPanel.behavior.test.ts
new file mode 100644
index 00000000..c7432a7d
--- /dev/null
+++ b/src/modules/inbounds/weight/components/WeightOcrPanel.behavior.test.ts
@@ -0,0 +1,943 @@
+import ElementPlus from 'element-plus'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import { AxiosError } from 'axios'
+import { createPinia, setActivePinia } from 'pinia'
+import { DOMWrapper, enableAutoUnmount, flushPromises, mount, type VueWrapper } from '@vue/test-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+import { ApiResponseError } from '@/shared/api/http'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import {
+  confirmWeightResult,
+  correctWeightResult,
+  createWeightResult,
+  deleteWeightResult,
+  downloadWeightImage,
+  downloadWeightThumbnail,
+  getWeightWorkspace,
+  getWeightPalletOptions,
+  uploadWeightImage,
+} from '../api/weightOcr'
+import type { WeightResultResource, WeightWorkspaceResource } from '../types'
+import WeightOcrPanel from './WeightOcrPanel.vue'
+
+vi.mock('../api/weightOcr', async () => {
+  const actual = await vi.importActual<typeof import('../api/weightOcr')>('../api/weightOcr')
+  return {
+    ...actual,
+    confirmWeightResult: vi.fn(),
+    correctWeightResult: vi.fn(),
+    createWeightResult: vi.fn(),
+    deleteWeightResult: vi.fn(),
+    downloadWeightImage: vi.fn(),
+    downloadWeightThumbnail: vi.fn(),
+    getWeightWorkspace: vi.fn(),
+    getWeightPalletOptions: vi.fn(),
+    uploadWeightImage: vi.fn(),
+  }
+})
+
+const pendingWeight: WeightResultResource = {
+  id: '30001',
+  fileId: '40001',
+  palletId: '50001',
+  palletCode: 'TP-001',
+  palletType: '木托盘',
+  palletCapacityCbm: 1.2,
+  palletTareWeightKg: 12,
+  ocrProvider: 'FILE_WEIGHT_OCR',
+  ocrRawText: '285.5',
+  ocrWeightValue: 285.5,
+  ocrWeightUnit: 'KG',
+  confidence: 0.98,
+  adjustedWeightValue: null,
+  adjustedWeightUnit: null,
+  grossWeightKg: 285.5,
+  netWeightKg: null,
+  recognitionStatus: 'PENDING_CONFIRM',
+  adjustmentReason: null,
+  adjustedBy: null,
+  adjustedAt: null,
+  confirmedBy: null,
+  confirmedAt: null,
+  palletSequence: 1,
+  blockId: '70001',
+  slotNo: 1,
+  reservationId: '71001',
+  locationId: '72001',
+  locationCode: 'A01',
+  sharedOverflow: false,
+  slotStatus: 'BOUND',
+  version: 0,
+}
+
+const workspace: WeightWorkspaceResource = {
+  inboundId: '20001',
+  inboundCode: 'RK-20001',
+  processStatus: 'MEASURING',
+  actualGrossWeightKg: null,
+  actualNetWeightKg: null,
+  weightResults: [pendingWeight],
+  palletLocationGuide: {
+    blockId: '70001',
+    reservedSlotCount: 1,
+    actualPalletCount: 1,
+    reservedEmptySlotCount: 0,
+    slots: [{
+      slotNo: 1,
+      reservationId: '71001',
+      locationId: '72001',
+      locationCode: 'A01',
+      sharedOverflow: false,
+      slotStatus: 'BOUND',
+      boundWeightResultId: '30001',
+      palletSequence: 1,
+      palletId: '50001',
+      palletCode: 'TP-001',
+    }],
+  },
+}
+
+function palletPage(records = [{
+  palletId: '50001', palletCode: 'TP-001', palletType: '木托盘', capacityCbm: 1.2, tareWeightKg: 12,
+}]) {
+  return { records, page: 1, size: 20, total: records.length, pages: records.length ? 1 : 0 }
+}
+
+enableAutoUnmount(afterEach)
+
+const allWeightPermissions = [
+  'platform:firstleg:inbound:measure:view',
+  'platform:firstleg:inbound:weight:edit',
+  'platform:firstleg:inbound:weight:confirm',
+]
+
+function mountPanel(permissions = allWeightPermissions, props: Record<string, unknown> = {}) {
+  const pinia = createPinia()
+  setActivePinia(pinia)
+  const auth = useAuthStore()
+  auth.token = 'token'
+  auth.permissions = permissions
+  useAccessPreviewStore().initializeAfterLogin()
+  return mount(WeightOcrPanel, {
+    attachTo: document.body,
+    props: { customerId: '10001', inboundId: '20001', ...props },
+    global: { plugins: [pinia, ElementPlus] },
+  })
+}
+
+async function openWeightDialog(wrapper: VueWrapper) {
+  await wrapper.get('button[aria-label="查看称重图片 1"]').trigger('click')
+  await flushPromises()
+}
+
+function dialogWeightInput() {
+  const input = document.body.querySelector<HTMLInputElement>('input[aria-label="当前图片确认重量"]')
+  if (!input) throw new Error('weight confirmation input is missing')
+  return new DOMWrapper(input)
+}
+
+function dialogUnit(index: number) {
+  const option = document.body.querySelectorAll<HTMLElement>('.el-dialog .el-segmented__item').item(index)
+  return new DOMWrapper(option)
+}
+
+function dialogConfirmButton(text = '确认重量') {
+  const button = [...document.body.querySelectorAll<HTMLButtonElement>('.el-dialog__footer button')]
+    .find((candidate) => candidate.textContent?.trim() === text)
+  if (!button) throw new Error('weight confirmation button is missing')
+  return new DOMWrapper(button)
+}
+
+describe('WeightOcrPanel confirmation behavior', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    document.body.innerHTML = ''
+    vi.mocked(getWeightWorkspace).mockResolvedValue(workspace)
+    vi.mocked(getWeightPalletOptions).mockResolvedValue(palletPage())
+    vi.mocked(downloadWeightImage).mockResolvedValue(new Blob(['image'], { type: 'image/jpeg' }))
+    vi.mocked(downloadWeightThumbnail).mockResolvedValue(new Blob(['thumb'], { type: 'image/jpeg' }))
+    vi.stubGlobal('URL', {
+      createObjectURL: vi.fn(() => 'blob:test-image'),
+      revokeObjectURL: vi.fn(),
+    })
+    vi.mocked(confirmWeightResult).mockResolvedValue({
+      ...pendingWeight,
+      recognitionStatus: 'CONFIRMED',
+      grossWeightKg: 297.5,
+      netWeightKg: 285.5,
+      version: 1,
+    })
+  })
+
+  it('opens the editable confirmation dialog immediately after upload', async () => {
+    vi.mocked(uploadWeightImage).mockResolvedValue({
+      fileId: '40002',
+      fileName: 'weight.jpg',
+      contentType: 'image/jpeg',
+      sizeBytes: 100,
+      recognitionStatus: 'SUCCESS',
+      weightValue: 12.5,
+      weightUnit: 'KG',
+      confidence: 0.98,
+      error: null,
+    })
+    vi.mocked(createWeightResult).mockResolvedValue({
+      ...pendingWeight,
+      id: '30002',
+      fileId: '40002',
+      ocrWeightValue: 12.5,
+    })
+    const wrapper = mountPanel()
+    await flushPromises()
+    await wrapper.find('.pallet-picker .el-select').trigger('click')
+    expect(document.body.textContent).toContain('木托盘 · 皮重 12.000 KG · 容量 1.2 m³')
+    await new DOMWrapper(document.body).find('.el-select-dropdown__item').trigger('click')
+    const input = wrapper.get('input[type="file"]')
+    const file = new File(['image'], 'weight.jpg', { type: 'image/jpeg' })
+    Object.defineProperty(input.element, 'files', { configurable: true, value: [file] })
+
+    await input.trigger('change')
+    await flushPromises()
+
+    expect(uploadWeightImage).toHaveBeenCalledWith('10001', '20001', file)
+    expect(createWeightResult).toHaveBeenCalledWith('10001', '20001', expect.objectContaining({ palletId: '50001' }))
+    expect(document.body.textContent).toContain('确认称重图片')
+    expect(document.body.textContent).toContain('当前托盘皮重')
+    expect(document.body.textContent).toContain('OCR 识别毛重')
+    expect(document.body.textContent).toContain('12.500 KG')
+    expect(document.body.querySelector('input[aria-label="当前图片确认重量"]')).not.toBeNull()
+  })
+
+  it('renders thirty compact image cards without technical OCR details', async () => {
+    vi.mocked(getWeightWorkspace).mockResolvedValue({
+      ...workspace,
+      weightResults: Array.from({ length: 30 }, (_, index) => ({
+        ...pendingWeight,
+        id: String(30001 + index),
+        fileId: String(40001 + index),
+        ocrRawText: `raw-${index}`,
+      })),
+    })
+    const wrapper = mountPanel()
+    await flushPromises()
+
+    expect(wrapper.findAll('.weight-card')).toHaveLength(30)
+    expect(wrapper.findAll('.weight-thumb')).toHaveLength(30)
+    expect(wrapper.text()).not.toContain('置信度')
+    expect(wrapper.text()).not.toContain('OCR 原文')
+    expect(wrapper.text()).not.toContain('FILE_WEIGHT_OCR')
+    expect(wrapper.text()).not.toContain('raw-0')
+  })
+
+  it('renders the server-bound location and status once in the compact card facts', async () => {
+    const wrapper = mountPanel()
+    await flushPromises()
+
+    const card = wrapper.get('.weight-card')
+    expect(card.text()).toContain('库位A01 · 待上架')
+    expect(card.text()).toContain('待上架')
+    expect(card.find('.weight-card__putaway').exists()).toBe(false)
+    expect(card.get('.weight-card__facts').text()).toContain('库位A01 · 待上架')
+  })
+
+  it('keeps whole-inbound reservation guidance out of the panel and shows location on each weight card', async () => {
+    vi.mocked(getWeightWorkspace).mockResolvedValue({
+      ...workspace,
+      palletLocationGuide: {
+        blockId: '70001',
+        reservedSlotCount: 3,
+        actualPalletCount: 2,
+        reservedEmptySlotCount: 1,
+        slots: [
+          { slotNo: 1, reservationId: '71001', locationId: '72001', locationCode: 'A01', sharedOverflow: false, slotStatus: 'BOUND', boundWeightResultId: '30001', palletSequence: 1, palletId: '50001', palletCode: 'TP-001' },
+          { slotNo: 2, reservationId: '71002', locationId: '72002', locationCode: 'A02', sharedOverflow: false, slotStatus: 'TRANSFERRED', boundWeightResultId: '30002', palletSequence: 2, palletId: '50002', palletCode: 'TP-002' },
+          { slotNo: 3, reservationId: '71003', locationId: '72003', locationCode: 'A03', sharedOverflow: false, slotStatus: 'RESERVED_EMPTY', boundWeightResultId: null, palletSequence: null, palletId: null, palletCode: null },
+        ],
+      },
+    })
+    const wrapper = mountPanel()
+    await flushPromises()
+
+    expect(wrapper.find('.putaway-guide').exists()).toBe(false)
+    expect(wrapper.text()).not.toContain('整票上架引导')
+    expect(wrapper.get('.weight-card__facts').text()).toContain('库位A01 · 待上架')
+  })
+
+  it('does not render a full-width placeholder when no whole-inbound guide exists', async () => {
+    vi.mocked(getWeightWorkspace).mockResolvedValue({ ...workspace, palletLocationGuide: null })
+    const wrapper = mountPanel()
+    await flushPromises()
+
+    expect(wrapper.text()).not.toContain('尚未分配整票预留库位')
+    expect(wrapper.find('.putaway-guide-empty').exists()).toBe(false)
+  })
+
+  it('marks A0 as a temporary overflow location from the server flag', async () => {
+    vi.mocked(getWeightWorkspace).mockResolvedValue({
+      ...workspace,
+      weightResults: [{ ...pendingWeight, locationCode: 'A0', sharedOverflow: true }],
+      palletLocationGuide: {
+        ...workspace.palletLocationGuide!,
+        slots: [{
+          ...workspace.palletLocationGuide!.slots[0]!,
+          locationCode: 'A0',
+          sharedOverflow: true,
+        }],
+      },
+    })
+    const wrapper = mountPanel()
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('A0 临时溢出位')
+    expect(wrapper.get('.weight-card__facts').text()).toContain('库位A0 · 待上架 · A0 临时溢出位')
+    expect(wrapper.find('.putaway-guide').exists()).toBe(false)
+  })
+
+  it.each([
+    ['TRANSFERRED', '已上架'],
+    ['RELEASED', '已释放'],
+    ['RESERVED_EMPTY', '预留空位'],
+  ] as const)('renders the authoritative %s slot status as %s', async (slotStatus, label) => {
+    vi.mocked(getWeightWorkspace).mockResolvedValue({
+      ...workspace,
+      weightResults: [{ ...pendingWeight, slotStatus }],
+    })
+    const wrapper = mountPanel()
+    await flushPromises()
+
+    expect(wrapper.text()).toContain(label)
+  })
+
+  it('shows an explicit unassigned state when the server has not bound a slot', async () => {
+    vi.mocked(getWeightWorkspace).mockResolvedValue({
+      ...workspace,
+      weightResults: [{
+        ...pendingWeight,
+        palletSequence: null,
+        blockId: null,
+        slotNo: null,
+        reservationId: null,
+        locationId: null,
+        locationCode: null,
+        sharedOverflow: null,
+        slotStatus: null,
+      }],
+    })
+    const wrapper = mountPanel()
+    await flushPromises()
+
+    expect(wrapper.text()).not.toContain('托盘未分配')
+    expect(wrapper.get('.weight-card__facts').text()).toContain('库位未分配')
+  })
+
+  it('deletes a pending image with its optimistic-lock version', async () => {
+    const confirm = vi.spyOn(ElMessageBox, 'confirm').mockResolvedValue(undefined as never)
+    vi.mocked(deleteWeightResult).mockResolvedValue(undefined)
+    vi.mocked(getWeightWorkspace)
+      .mockResolvedValueOnce(workspace)
+      .mockResolvedValueOnce({
+        ...workspace,
+        weightResults: [],
+        palletLocationGuide: {
+          ...workspace.palletLocationGuide!,
+          actualPalletCount: 0,
+          reservedEmptySlotCount: 1,
+          slots: [{
+            ...workspace.palletLocationGuide!.slots[0]!,
+            slotStatus: 'RESERVED_EMPTY',
+            boundWeightResultId: null,
+            palletSequence: null,
+            palletId: null,
+            palletCode: null,
+          }],
+        },
+      })
+    const wrapper = mountPanel()
+    await flushPromises()
+
+    await wrapper.get('button[aria-label="删除称重图片 1"]').trigger('click')
+    await flushPromises()
+
+    expect(deleteWeightResult).toHaveBeenCalledWith('10001', '20001', '30001', 0)
+    expect(confirm).toHaveBeenCalledWith(
+      expect.stringContaining('对应库位仍为本票保留，不会释放给其他订单'),
+      '删除称重图片',
+      expect.any(Object),
+    )
+    expect(getWeightWorkspace).toHaveBeenCalledTimes(2)
+    expect(wrapper.findAll('.weight-card')).toHaveLength(0)
+    expect(wrapper.text()).toContain('尚未上传称重图片')
+    expect(wrapper.find('.putaway-guide').exists()).toBe(false)
+  })
+
+  it('keeps the image and server workspace visible when deletion fails', async () => {
+    vi.spyOn(ElMessageBox, 'confirm').mockResolvedValue(undefined as never)
+    const errorMessage = vi.spyOn(ElMessage, 'error')
+    vi.mocked(deleteWeightResult).mockRejectedValueOnce(
+      new ApiResponseError('无权删除当前称重图片', 'A0403', 403),
+    )
+    const wrapper = mountPanel()
+    await flushPromises()
+
+    await wrapper.get('button[aria-label="删除称重图片 1"]').trigger('click')
+    await flushPromises()
+
+    expect(wrapper.findAll('.weight-card')).toHaveLength(1)
+    expect(wrapper.text()).toContain('A01')
+    expect(getWeightWorkspace).toHaveBeenCalledTimes(1)
+    expect(errorMessage).toHaveBeenCalledWith(expect.objectContaining({
+      message: '当前账号无权访问该数据，请联系管理员确认权限',
+    }))
+  })
+
+  it('shows a retryable workspace load failure without fabricating putaway guidance', async () => {
+    vi.mocked(getWeightWorkspace).mockRejectedValueOnce(
+      new ApiResponseError('称重工作区暂不可用', 'A0500', 503),
+    )
+    const wrapper = mountPanel()
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('称重数据加载失败')
+    expect(wrapper.text()).toContain('称重工作区暂不可用')
+    expect(wrapper.find('.putaway-guide').exists()).toBe(false)
+    expect(wrapper.find('.putaway-guide-empty').exists()).toBe(false)
+  })
+
+  it('shows only the key weights and allows direct confirmation', async () => {
+    const wrapper = mountPanel()
+    await flushPromises()
+    await openWeightDialog(wrapper)
+
+    const dialogText = document.body.querySelector('.el-dialog')?.textContent || ''
+    expect(dialogText).toContain('当前托盘皮重')
+    expect(dialogText).toContain('12.000 KG')
+    expect(dialogText).toContain('OCR 识别毛重')
+    expect(dialogText).toContain('285.500 KG')
+    expect(dialogText).toContain('确认含托盘毛重')
+    expect(dialogText).toContain('托盘类型')
+    expect(dialogText).toContain('木托盘')
+    expect(dialogText).not.toContain('TP-001')
+    for (const hiddenLabel of ['托盘编码', '托盘容量', '识别状态', '置信度', '服务端毛重', '服务端净重', 'OCR 原文']) {
+      expect(dialogText).not.toContain(hiddenLabel)
+    }
+    expect(dialogConfirmButton().attributes('disabled')).toBeUndefined()
+    await dialogConfirmButton().trigger('click')
+    await flushPromises()
+
+    expect(confirmWeightResult).toHaveBeenCalledTimes(1)
+    expect(confirmWeightResult).toHaveBeenCalledWith('10001', '20001', '30001', { version: 0 })
+    expect(correctWeightResult).not.toHaveBeenCalled()
+  })
+
+  it('emits the latest server total after confirming a weight', async () => {
+    vi.mocked(getWeightWorkspace)
+      .mockResolvedValueOnce(workspace)
+      .mockResolvedValueOnce({
+        ...workspace,
+        actualGrossWeightKg: 1787.5,
+        actualNetWeightKg: 1747.5,
+        weightResults: [{ ...pendingWeight, recognitionStatus: 'CONFIRMED', grossWeightKg: 297.5, netWeightKg: 285.5, version: 1 }],
+      })
+    const wrapper = mountPanel()
+    await flushPromises()
+    await openWeightDialog(wrapper)
+
+    await dialogConfirmButton().trigger('click')
+    await flushPromises()
+
+    expect(wrapper.emitted('summaryChanged')).toEqual([[1787.5, 1747.5, true]])
+    expect(wrapper.emitted('changed')).toHaveLength(1)
+    expect(wrapper.text()).toContain('实测毛重')
+    expect(wrapper.text()).toContain('货物重量')
+    expect(wrapper.text()).toContain('1787.500 KG')
+    expect(wrapper.text()).toContain('1747.500 KG')
+  })
+
+  it('atomically corrects and confirms an approved weight during measurement review', async () => {
+    const confirmed = {
+      ...pendingWeight,
+      recognitionStatus: 'CONFIRMED',
+      adjustedWeightValue: 120,
+      adjustedWeightUnit: 'KG',
+      grossWeightKg: 120,
+      netWeightKg: 108,
+      version: 1,
+    }
+    vi.mocked(getWeightWorkspace).mockResolvedValue({
+      ...workspace,
+      processStatus: 'MEASURE_PENDING',
+      actualGrossWeightKg: 120,
+      actualNetWeightKg: 108,
+      weightResults: [confirmed],
+    })
+    vi.mocked(confirmWeightResult).mockResolvedValue({ ...confirmed, grossWeightKg: 125, netWeightKg: 113, version: 2 })
+    const wrapper = mountPanel(allWeightPermissions, { reviewMode: true, correctionMode: true })
+    await flushPromises()
+
+    expect(wrapper.find('input[type="file"]').exists()).toBe(false)
+    expect(wrapper.text()).not.toContain('删除图片')
+    await wrapper.findAll('button').find((button) => button.text().includes('修改含托盘毛重'))?.trigger('click')
+    await flushPromises()
+    await dialogWeightInput().setValue('125')
+    const reason = document.body.querySelector<HTMLTextAreaElement>('textarea[placeholder="请填写本次毛重修正原因"]')
+    expect(reason).not.toBeNull()
+    await new DOMWrapper(reason!).setValue('复核磅秤读数')
+    await dialogConfirmButton('保存重量修正').trigger('click')
+    await flushPromises()
+
+    expect(confirmWeightResult).toHaveBeenCalledWith('10001', '20001', '30001', {
+      version: 1,
+      adjustedWeightValue: 125,
+      adjustedWeightUnit: 'KG',
+      adjustmentReason: '复核磅秤读数',
+    })
+    expect(correctWeightResult).not.toHaveBeenCalled()
+  })
+
+  it('closes the confirmation dialog immediately after a successful confirmation', async () => {
+    const wrapper = mountPanel()
+    await flushPromises()
+    await openWeightDialog(wrapper)
+
+    expect(wrapper.getComponent(AppDialog).props('modelValue')).toBe(true)
+    await dialogConfirmButton().trigger('click')
+    await flushPromises()
+
+    expect(wrapper.getComponent(AppDialog).props('modelValue')).toBe(false)
+  })
+
+  it('requires a pallet selection before opening the file picker', async () => {
+    const wrapper = mountPanel()
+    await flushPromises()
+    const click = vi.spyOn(wrapper.get('input[type="file"]').element as HTMLInputElement, 'click')
+
+    await wrapper.findAll('button').find((button) => button.text().includes('上传称重图片'))?.trigger('click')
+
+    expect(click).not.toHaveBeenCalled()
+  })
+
+  it('shows an actionable empty state when the warehouse has no pallet options', async () => {
+    vi.mocked(getWeightPalletOptions).mockResolvedValueOnce(palletPage([]))
+    const wrapper = mountPanel()
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('当前仓库暂无可选托盘')
+    expect(wrapper.findAll('button').some((button) => button.text().includes('重新加载'))).toBe(true)
+  })
+
+  it('renders records from the formal paged response without showing a load failure', async () => {
+    vi.mocked(getWeightPalletOptions).mockResolvedValueOnce({
+      records: [
+        { palletId: '2092803000000000001', palletCode: 'TP-11', palletType: '木托盘', capacityCbm: 1.2, tareWeightKg: 12 },
+        { palletId: '2092803000000000002', palletCode: 'TP-12', palletType: '塑料托盘', capacityCbm: 1.1, tareWeightKg: 10 },
+      ],
+      page: 1,
+      size: 20,
+      total: 2,
+      pages: 1,
+    })
+    const wrapper = mountPanel()
+    await flushPromises()
+
+    await wrapper.find('.pallet-picker .el-select').trigger('click')
+    await flushPromises()
+
+    expect(document.body.textContent).toContain('木托盘 · 皮重 12.000 KG · 容量 1.2 m³')
+    expect(document.body.textContent).toContain('塑料托盘 · 皮重 10.000 KG · 容量 1.1 m³')
+    expect(wrapper.text()).not.toContain('可选托盘加载失败')
+  })
+
+  it('remote search keyword uses page 1 and size 50', async () => {
+    const wrapper = mountPanel()
+    await flushPromises()
+    vi.useFakeTimers()
+    try {
+      await wrapper.find('.pallet-picker .el-select').trigger('click')
+      await wrapper.find('.pallet-picker input').setValue(' 木托盘 ')
+      await vi.advanceTimersByTimeAsync(350)
+      await flushPromises()
+
+      expect(getWeightPalletOptions).toHaveBeenLastCalledWith('10001', '20001', expect.objectContaining({
+        page: 1, size: 50, keyword: '木托盘', signal: expect.any(AbortSignal),
+      }))
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('shows pallet loading failures without hiding existing weight results', async () => {
+    vi.mocked(getWeightPalletOptions).mockRejectedValueOnce(new ApiResponseError('托盘服务暂不可用', 'A0500', 503))
+    const wrapper = mountPanel()
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('托盘服务暂不可用')
+    expect(wrapper.findAll('.weight-card')).toHaveLength(1)
+  })
+
+  it('shows a network error as a pallet candidate load failure without hiding historical snapshots', async () => {
+    vi.mocked(getWeightPalletOptions).mockRejectedValueOnce(new AxiosError('Network Error', 'ERR_NETWORK'))
+    const wrapper = mountPanel()
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('可选托盘加载失败')
+    expect(wrapper.findAll('.weight-card')).toHaveLength(1)
+    expect(wrapper.text()).toContain('木托盘')
+    expect(wrapper.text()).toContain('12.000 KG')
+  })
+
+  it('does not load weight or pallet data without measurement view permission', async () => {
+    const wrapper = mountPanel([])
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('缺少入库测量查看权限')
+    expect(getWeightWorkspace).not.toHaveBeenCalled()
+    expect(getWeightPalletOptions).not.toHaveBeenCalled()
+  })
+
+  it('keeps historical palletCode snapshots visible for a read-only operator', async () => {
+    const wrapper = mountPanel(['platform:firstleg:inbound:measure:view'])
+    await flushPromises()
+
+    expect(getWeightWorkspace).toHaveBeenCalledOnce()
+    expect(getWeightPalletOptions).not.toHaveBeenCalled()
+    expect(wrapper.find('.pallet-picker .el-select').exists()).toBe(false)
+    expect(wrapper.text()).toContain('TP-001')
+    expect(wrapper.text()).toContain('木托盘')
+    expect(wrapper.text()).toContain('12.000 KG')
+  })
+
+  it('does not request pallet candidates when the inbound status is not editable', async () => {
+    vi.mocked(getWeightWorkspace).mockResolvedValue({ ...workspace, processStatus: 'MEASURE_PENDING' })
+
+    mountPanel()
+    await flushPromises()
+
+    expect(getWeightPalletOptions).not.toHaveBeenCalled()
+  })
+
+  it('virtualizes one thousand pallet candidates instead of rendering one thousand option nodes', async () => {
+    vi.mocked(getWeightPalletOptions).mockResolvedValue(palletPage(Array.from({ length: 1_000 }, (_, index) => ({
+      palletId: String(60_000 + index),
+      palletCode: `TP-${index}`,
+      palletType: `托盘类型 ${index}`,
+      capacityCbm: 1.2,
+      tareWeightKg: 12,
+    }))))
+    const wrapper = mountPanel()
+    await flushPromises()
+
+    await wrapper.find('.pallet-picker .el-select').trigger('click')
+    await flushPromises()
+
+    const renderedOptions = document.body.querySelectorAll('.el-select-dropdown__item')
+    expect(renderedOptions.length).toBeGreaterThan(0)
+    expect(renderedOptions.length).toBeLessThan(100)
+  })
+
+  it('aborts an in-flight pallet request and ignores its late result when the panel closes', async () => {
+    let resolveOptions: ((value: Awaited<ReturnType<typeof getWeightPalletOptions>>) => void) | undefined
+    vi.mocked(getWeightPalletOptions).mockImplementationOnce(() => new Promise((resolve) => {
+      resolveOptions = resolve
+    }))
+    const wrapper = mountPanel()
+    await flushPromises()
+    const signal = vi.mocked(getWeightPalletOptions).mock.calls[0]?.[2]?.signal
+
+    wrapper.unmount()
+    resolveOptions?.(palletPage([{
+      palletId: 'late', palletCode: 'TP-LATE', palletType: '过期托盘', capacityCbm: 1, tareWeightKg: 10,
+    }]))
+    await flushPromises()
+
+    expect(signal?.aborted).toBe(true)
+    expect(document.body.textContent).not.toContain('过期托盘')
+  })
+
+  it('keeps a low-confidence OCR result focused on the editable weight', async () => {
+    vi.mocked(getWeightWorkspace).mockResolvedValue({
+      ...workspace,
+      weightResults: [{ ...pendingWeight, ocrRawText: '5360', ocrWeightValue: 5360, confidence: 0.51863 }],
+    })
+    const wrapper = mountPanel()
+    await flushPromises()
+    await openWeightDialog(wrapper)
+
+    const dialogText = document.body.textContent || ''
+    expect(dialogText).toContain('OCR 识别毛重')
+    expect(dialogText).toContain('5360.000 KG')
+    expect(dialogText).toContain('确认含托盘毛重')
+    expect(dialogText).not.toContain('置信度')
+    expect(dialogText).not.toContain('OCR 原文')
+    expect(dialogText).not.toContain('OCR 可能误读数字或小数点')
+    expect(dialogConfirmButton().attributes('disabled')).toBeUndefined()
+
+    await dialogConfirmButton().trigger('click')
+    await flushPromises()
+
+    expect(confirmWeightResult).toHaveBeenCalledWith('10001', '20001', '30001', { version: 0 })
+  })
+
+  it('sends the adjusted value and a specific audit reason in the same confirmation request', async () => {
+    const wrapper = mountPanel()
+    await flushPromises()
+    await openWeightDialog(wrapper)
+
+    await dialogWeightInput().setValue('286.125')
+    await dialogConfirmButton().trigger('click')
+    await flushPromises()
+
+    expect(confirmWeightResult).toHaveBeenCalledTimes(1)
+    expect(confirmWeightResult).toHaveBeenCalledWith('10001', '20001', '30001', {
+      version: 0,
+      adjustedWeightValue: 286.125,
+      adjustedWeightUnit: 'KG',
+      adjustmentReason: 'OCR 原值 285.500 KG，人工确认 286.125 KG',
+    })
+    expect(correctWeightResult).not.toHaveBeenCalled()
+  })
+
+  it('sends an LB adjustment atomically after switching units', async () => {
+    const wrapper = mountPanel()
+    await flushPromises()
+    await openWeightDialog(wrapper)
+
+    await dialogWeightInput().setValue('30.125')
+    await dialogUnit(1).trigger('click')
+    await dialogConfirmButton().trigger('click')
+    await flushPromises()
+
+    expect(confirmWeightResult).toHaveBeenCalledWith('10001', '20001', '30001', {
+      version: 0,
+      adjustedWeightValue: 30.125,
+      adjustedWeightUnit: 'LB',
+      adjustmentReason: 'OCR 原值 285.500 KG，人工确认 30.125 LB',
+    })
+    expect(correctWeightResult).not.toHaveBeenCalled()
+  })
+
+  it('rejects an LB value that would round to zero kilograms', async () => {
+    const wrapper = mountPanel()
+    await flushPromises()
+    await openWeightDialog(wrapper)
+
+    await dialogWeightInput().setValue('0.001')
+    await dialogUnit(1).trigger('click')
+
+    expect(dialogConfirmButton().attributes('disabled')).toBeDefined()
+    expect(confirmWeightResult).not.toHaveBeenCalled()
+  })
+
+  it('rejects a positive gross weight that does not exceed the pallet tare', async () => {
+    const warning = vi.spyOn(ElMessage, 'warning')
+    const wrapper = mountPanel()
+    await flushPromises()
+    await openWeightDialog(wrapper)
+
+    await dialogWeightInput().setValue('0.002')
+    await dialogUnit(1).trigger('click')
+    await dialogConfirmButton().trigger('click')
+    await flushPromises()
+
+    expect(confirmWeightResult).not.toHaveBeenCalled()
+    expect(warning).toHaveBeenCalledWith('称重毛重必须大于托盘皮重 12.000 KG')
+  })
+
+  it('clamps a value outside the safe three-decimal JavaScript range', async () => {
+    const wrapper = mountPanel()
+    await flushPromises()
+    await openWeightDialog(wrapper)
+    const input = dialogWeightInput()
+
+    await input.setValue('9000000000001')
+    expect((input.element as HTMLInputElement).value).toBe('9000000000000.000')
+    await dialogConfirmButton().trigger('click')
+    await flushPromises()
+
+    expect(confirmWeightResult).toHaveBeenCalledWith('10001', '20001', '30001', {
+      version: 0,
+      adjustedWeightValue: 9_000_000_000_000,
+      adjustedWeightUnit: 'KG',
+      adjustmentReason: 'OCR 原值 285.500 KG，人工确认 9000000000000.000 KG',
+    })
+  })
+
+  it('rounds an input with more than three decimals before confirmation', async () => {
+    const wrapper = mountPanel()
+    await flushPromises()
+    await openWeightDialog(wrapper)
+    const input = dialogWeightInput()
+
+    await input.setValue('13.2345')
+    expect((input.element as HTMLInputElement).value).toBe('13.235')
+    await dialogConfirmButton().trigger('click')
+    await flushPromises()
+
+    expect(confirmWeightResult).toHaveBeenCalledWith('10001', '20001', '30001', {
+      version: 0,
+      adjustedWeightValue: 13.235,
+      adjustedWeightUnit: 'KG',
+      adjustmentReason: 'OCR 原值 285.500 KG，人工确认 13.235 KG',
+    })
+  })
+
+  it('confirms an existing corrected value without creating another correction', async () => {
+    vi.mocked(getWeightWorkspace).mockResolvedValue({
+      ...workspace,
+      weightResults: [{
+        ...pendingWeight,
+        adjustedWeightValue: 286.125,
+        adjustedWeightUnit: 'KG',
+        adjustmentReason: '首次修正',
+        version: 1,
+      }],
+    })
+    const wrapper = mountPanel()
+    await flushPromises()
+    await openWeightDialog(wrapper)
+
+    await dialogConfirmButton().trigger('click')
+    await flushPromises()
+
+    expect(confirmWeightResult).toHaveBeenCalledWith('10001', '20001', '30001', { version: 1 })
+    expect(correctWeightResult).not.toHaveBeenCalled()
+  })
+
+  it('allows a confirm-only operator to accept an unchanged OCR value', async () => {
+    const wrapper = mountPanel([
+      'platform:firstleg:inbound:measure:view',
+      'platform:firstleg:inbound:weight:confirm',
+    ])
+    await flushPromises()
+    await openWeightDialog(wrapper)
+
+    expect(dialogWeightInput().attributes('disabled')).toBeDefined()
+    await dialogConfirmButton().trigger('click')
+    await flushPromises()
+
+    expect(confirmWeightResult).toHaveBeenCalledWith('10001', '20001', '30001', { version: 0 })
+  })
+
+  it('does not render confirmation for an edit-only operator', async () => {
+    const wrapper = mountPanel([
+      'platform:firstleg:inbound:measure:view',
+      'platform:firstleg:inbound:weight:edit',
+    ])
+    await flushPromises()
+    await openWeightDialog(wrapper)
+
+    const confirmButtons = [...document.body.querySelectorAll<HTMLButtonElement>('.el-dialog__footer button')]
+      .filter((button) => button.textContent?.trim() === '确认重量')
+    expect(confirmButtons).toHaveLength(0)
+    expect(confirmWeightResult).not.toHaveBeenCalled()
+  })
+
+  it('supports manual entry when OCR did not return a value', async () => {
+    vi.mocked(getWeightWorkspace).mockResolvedValue({
+      ...workspace,
+      weightResults: [{
+        ...pendingWeight,
+        ocrRawText: null,
+        ocrWeightValue: null,
+        ocrWeightUnit: null,
+        recognitionStatus: 'NEEDS_MANUAL',
+      }],
+    })
+    const wrapper = mountPanel()
+    await flushPromises()
+    await openWeightDialog(wrapper)
+
+    expect(dialogConfirmButton().attributes('disabled')).toBeDefined()
+    await dialogWeightInput().setValue('13.500')
+    await dialogConfirmButton().trigger('click')
+    await flushPromises()
+
+    expect(confirmWeightResult).toHaveBeenCalledWith('10001', '20001', '30001', {
+      version: 0,
+      adjustedWeightValue: 13.5,
+      adjustedWeightUnit: 'KG',
+      adjustmentReason: 'OCR 原值 —，人工确认 13.500 KG',
+    })
+  })
+
+  it('normalizes a supported OCR unit alias with surrounding whitespace', async () => {
+    vi.mocked(getWeightWorkspace).mockResolvedValue({
+      ...workspace,
+      weightResults: [{ ...pendingWeight, ocrWeightUnit: ' lbs ' }],
+    })
+    const wrapper = mountPanel()
+    await flushPromises()
+    await openWeightDialog(wrapper)
+
+    await dialogConfirmButton().trigger('click')
+    await flushPromises()
+
+    expect(confirmWeightResult).toHaveBeenCalledWith('10001', '20001', '30001', { version: 0 })
+  })
+
+  it('sends an explicit correction when OCR returns an unsupported unit', async () => {
+    vi.mocked(getWeightWorkspace).mockResolvedValue({
+      ...workspace,
+      weightResults: [{ ...pendingWeight, ocrWeightUnit: 'G' }],
+    })
+    const wrapper = mountPanel()
+    await flushPromises()
+    await openWeightDialog(wrapper)
+
+    await dialogConfirmButton().trigger('click')
+    await flushPromises()
+
+    expect(confirmWeightResult).toHaveBeenCalledWith('10001', '20001', '30001', {
+      version: 0,
+      adjustedWeightValue: 285.5,
+      adjustedWeightUnit: 'KG',
+      adjustmentReason: 'OCR 原值 285.500 G，人工确认 285.500 KG',
+    })
+  })
+
+  it('sends an explicit correction when OCR returns a value without a unit', async () => {
+    vi.mocked(getWeightWorkspace).mockResolvedValue({
+      ...workspace,
+      weightResults: [{ ...pendingWeight, ocrWeightUnit: null }],
+    })
+    const wrapper = mountPanel()
+    await flushPromises()
+    await openWeightDialog(wrapper)
+
+    await dialogConfirmButton().trigger('click')
+    await flushPromises()
+
+    expect(confirmWeightResult).toHaveBeenCalledWith('10001', '20001', '30001', {
+      version: 0,
+      adjustedWeightValue: 285.5,
+      adjustedWeightUnit: 'KG',
+      adjustmentReason: 'OCR 原值 285.500（单位缺失），人工确认 285.500 KG',
+    })
+  })
+
+  it('keeps the edited draft available when confirmation fails', async () => {
+    const errorMessage = vi.spyOn(ElMessage, 'error')
+    vi.mocked(confirmWeightResult).mockRejectedValueOnce(
+      new ApiResponseError('数据版本已变化，请刷新后重试', 'A0409', 409, undefined, 'request-1'),
+    )
+    const wrapper = mountPanel()
+    await flushPromises()
+    await openWeightDialog(wrapper)
+    const input = dialogWeightInput()
+
+    await input.setValue('286.125')
+    await dialogConfirmButton().trigger('click')
+    await flushPromises()
+
+    expect((input.element as HTMLInputElement).value).toBe('286.125')
+    expect(wrapper.text()).not.toContain('操作未完成')
+    expect(errorMessage).toHaveBeenCalledWith(expect.objectContaining({
+      message: '数据版本已变化，请刷新后重试（请求 ID：request-1）',
+      duration: 5_000,
+      showClose: true,
+    }))
+    expect(wrapper.getComponent(AppDialog).props('modelValue')).toBe(true)
+    expect(confirmWeightResult).toHaveBeenCalledTimes(1)
+  })
+})
diff --git a/src/modules/inbounds/weight/components/WeightOcrPanel.test.ts b/src/modules/inbounds/weight/components/WeightOcrPanel.test.ts
new file mode 100644
index 00000000..5210c0c5
--- /dev/null
+++ b/src/modules/inbounds/weight/components/WeightOcrPanel.test.ts
@@ -0,0 +1,105 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/inbounds/weight/components/WeightOcrPanel.vue'), 'utf8')
+
+describe('WeightOcrPanel contract', () => {
+  it('uses customer language at the page boundary while retaining a compatibility input', () => {
+    expect(source).toContain('reviewMode?: boolean')
+    expect(source).toContain("const customerId = computed(() => props.customerId || props.tenantId || '')")
+    expect(source).toContain('summaryChanged: [actualGrossWeightKg: number | null, actualNetWeightKg: number | null, hasConfirmedWeight: boolean]')
+    expect(source).toContain("defineExpose({ reload: loadWorkspace })")
+    const template = source.match(/<template>([\s\S]*?)<\/template>/)?.[1] || ''
+    expect(template).not.toContain('租户')
+  })
+
+  it('covers upload, immediate preview, inline correction, deletion, confirmation, and server totals', () => {
+    expect(source).toContain('uploadWeightImage')
+    expect(source).toContain('getWeightPalletOptions')
+    expect(source).toContain('palletId: selectedPalletId.value')
+    expect(source).toContain('downloadWeightImage')
+    expect(source).toContain('await openPreview(created, URL.createObjectURL(file))')
+    expect(source).toContain('deleteWeightResult')
+    expect(source).toContain('confirmWeightResult')
+    expect(source).toContain('class="weight-card__value"')
+    expect(source).toContain('v-model="weightDrafts[previewResult.id].value"')
+    expect(source).toContain('当前托盘皮重')
+    expect(source).toContain("previewResult.palletType || '未记录类型'")
+    expect(source).toContain('OCR 识别毛重')
+    expect(source).toContain('确认含托盘毛重')
+    expect(source).toContain('payload.adjustedWeightValue = Number(draft.value)')
+    expect(source).toContain("row.recognitionStatus === 'CONFIRMED' && reviewCorrectionEnabled.value")
+    expect(source).toContain('draft.reason.trim()')
+    expect(source).toContain('实测毛重')
+    expect(source).toContain('货物重量')
+    expect(source).toContain('palletTareWeightKg')
+    expect(source).toContain('netWeightKg')
+    expect(source).toContain('row.locationCode')
+    expect(source).toContain('row.sharedOverflow')
+    expect(source).toContain('putawayStatusLabel(row.slotStatus)')
+    expect(source).not.toContain('class="putaway-guide"')
+    expect(source).not.toContain('整票上架引导')
+    expect(source).not.toContain('整票预留库位')
+    expect(source).not.toContain('尚未分配整票预留库位')
+    expect(source).not.toContain('class="weight-card__putaway"')
+    expect(source).toContain('<div><dt>库位</dt><dd')
+    expect(source).not.toContain('workspace.palletLocationGuide.slots')
+    expect(source).toContain('对应库位仍为本票保留，不会释放给其他订单')
+    expect(source).toContain("workspace.value?.weightResults.some((item) => item.recognitionStatus === 'CONFIRMED') === true")
+  })
+
+  it('matches backend image limits and keeps technical OCR data out of the list', () => {
+    expect(source).toContain("['image/jpeg', 'image/png', 'image/bmp']")
+    expect(source).toContain('5 * 1024 * 1024')
+    expect(source).toContain('ocrRawText: getWeightOcrRawText(upload)')
+    expect(source).not.toContain('ocr-review-check')
+    expect(source).not.toContain('OCR 可能误读数字或小数点')
+    expect(source).not.toContain('<span>置信度</span>')
+    expect(source).not.toContain('<span>OCR 原文</span>')
+    expect(source).not.toContain('<span>托盘编码</span>')
+    expect(source).toContain('<span>托盘类型</span>')
+    expect(source).not.toContain('<span>托盘容量</span>')
+    expect(source).not.toContain('<span>服务端毛重</span>')
+    expect(source).not.toContain('<span>服务端净重</span>')
+    expect(source).not.toContain('`${option.palletCode} · ${option.palletType}`')
+    expect(source).toContain("option.palletType || '未记录类型'")
+  })
+
+  it('keeps pallet type, tare weight, and capacity in one virtualized select line', () => {
+    expect(source).toContain('<el-select-v2')
+    expect(source).toContain(':options="virtualPalletOptions"')
+    expect(source).toContain('label: palletOptionLabel(option)')
+    expect(source).toContain("`${option.palletType || '未记录类型'} · 皮重 ${formatWeight(option.tareWeightKg)} · 容量 ${option.capacityCbm} m³`")
+    expect(source).not.toContain('<small v-if="selectedPallet">')
+    expect(source).toContain('width: clamp(360px, 36vw, 520px)')
+  })
+
+  it('gates every action with the implemented permissions and editable statuses', () => {
+    expect(source).toContain("platform:firstleg:inbound:measure:view")
+    expect(source).toContain("platform:firstleg:inbound:weight:edit")
+    expect(source).toContain("platform:firstleg:inbound:weight:confirm")
+    expect(source).toContain("new Set(['PREPARING', 'WAIT_MEASURE', 'MEASURING', 'MEASURE_REJECTED'])")
+    expect(source).toContain('&& canEdit.value')
+    expect(source).toContain('&& editable.value')
+    expect(source).toContain('cancelPalletOptionsLoad()')
+    expect(source).toContain("workspace.value?.processStatus === 'MEASURE_PENDING'")
+    expect(source).toContain('v-if="canEdit && !reviewMode"')
+    expect(source).toContain('v-if="canEdit && editable && !reviewMode"')
+  })
+
+  it('provides error tracking, empty, loading, and narrow-screen states', () => {
+    expect(source).toContain('<ApiErrorMeta')
+    expect(source).toContain('<LoadErrorState')
+    expect(source).toContain('尚未上传称重图片')
+    expect(source).not.toContain('称重数据仅供查看')
+    expect(source).toContain('v-loading="loading"')
+    expect(source).toContain('@media (max-width: 720px)')
+    expect(source).toContain('@media (max-width: 360px)')
+  })
+
+  it('keeps each weight summary label and value on one compact line', () => {
+    expect(source).toContain('.weight-summary { display: flex; align-items: baseline; gap: var(--admin-space-2, 6px); white-space: nowrap; }')
+    expect(source).not.toContain('.weight-summary { display: grid;')
+  })
+})
diff --git a/src/modules/inbounds/weight/components/WeightOcrPanel.vue b/src/modules/inbounds/weight/components/WeightOcrPanel.vue
new file mode 100644
index 00000000..e64efb09
--- /dev/null
+++ b/src/modules/inbounds/weight/components/WeightOcrPanel.vue
@@ -0,0 +1,742 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onBeforeUnmount, ref, watch } from 'vue'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import {
+  ImagePlus,
+  RefreshCw,
+  Scale,
+  Trash2,
+} from '@lucide/vue'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import {
+  confirmWeightResult,
+  createWeightResult,
+  deleteWeightResult,
+  downloadWeightImage,
+  getWeightOcrRawText,
+  getWeightPalletOptions,
+  getWeightWorkspace,
+  uploadWeightImage,
+} from '../api/weightOcr'
+import type {
+  WeightPalletOption,
+  WeightResultResource,
+  WeightWorkspaceResource,
+} from '../types'
+import WeightImageThumbnail from './WeightImageThumbnail.vue'
+
+const props = withDefaults(defineProps<{
+  customerId?: string
+  tenantId?: string
+  inboundId: string
+  reviewMode?: boolean
+  correctionMode?: boolean
+}>(), {
+  reviewMode: false,
+  correctionMode: false,
+})
+const emit = defineEmits<{
+  changed: []
+  summaryChanged: [actualGrossWeightKg: number | null, actualNetWeightKg: number | null, hasConfirmedWeight: boolean]
+}>()
+
+const access = useAccessPreviewStore()
+const fileInput = ref<HTMLInputElement>()
+const workspace = ref<WeightWorkspaceResource | null>(null)
+const palletOptions = ref<WeightPalletOption[]>([])
+const selectedPalletId = ref('')
+const palletKeyword = ref('')
+const palletLoading = ref(false)
+const palletError = ref<ApiErrorDetails | null>(null)
+const loading = ref(false)
+const uploading = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const activeAction = ref('')
+const previewOpen = ref(false)
+const previewLoading = ref(false)
+const previewError = ref<ApiErrorDetails | null>(null)
+const previewUrl = ref('')
+const previewResultId = ref('')
+const previewSnapshot = ref<WeightResultResource | null>(null)
+const weightDrafts = ref<Record<string, { value: number | null; unit: 'KG' | 'LB'; reason: string }>>({})
+let loadSequence = 0
+let palletLoadSequence = 0
+let palletAbortController: AbortController | null = null
+const PALLET_OPTION_PAGE_SIZE = 50
+
+const editableStatuses = new Set(['PREPARING', 'WAIT_MEASURE', 'MEASURING', 'MEASURE_REJECTED'])
+const minimumWeight = { KG: 0.001, LB: 0.002 } as const
+const maximumSafeWeight = 9_000_000_000_000
+const customerId = computed(() => props.customerId || props.tenantId || '')
+const canEdit = computed(() => access.can('platform:firstleg:inbound:weight:edit'))
+const canConfirm = computed(() => access.can('platform:firstleg:inbound:weight:confirm'))
+const canView = computed(() => access.can('platform:firstleg:inbound:measure:view'))
+const editable = computed(() => Boolean(workspace.value && editableStatuses.has(workspace.value.processStatus)))
+const canLoadPalletOptions = computed(() => Boolean(
+  !props.reviewMode
+  && customerId.value
+  && props.inboundId
+  && canView.value
+  && canEdit.value
+  && editable.value,
+))
+const virtualPalletOptions = computed(() => palletOptions.value.map((option) => ({
+  label: palletOptionLabel(option),
+  value: option.palletId,
+})))
+const reviewCorrectionEnabled = computed(() => Boolean(
+  props.reviewMode
+  && props.correctionMode
+  && workspace.value?.processStatus === 'MEASURE_PENDING',
+))
+const rows = computed(() => workspace.value?.weightResults ?? [])
+const previewResult = computed(() => rows.value.find((row) => row.id === previewResultId.value)
+  || previewSnapshot.value)
+const previewConfirmDisabled = computed(() => {
+  const row = previewResult.value
+  return !row
+    || !isWeightDraftValid(row)
+    || (row.recognitionStatus === 'CONFIRMED' && reviewCorrectionEnabled.value
+      && (!hasWeightDraftChanged(row) || !weightDrafts.value[row.id]?.reason.trim()))
+    || Boolean(activeAction.value)
+})
+const previewCanConfirm = computed(() => Boolean(previewResult.value && canConfirm.value
+  && (editable.value || (reviewCorrectionEnabled.value && canEdit.value))))
+const previewInputEditable = computed(() => Boolean(previewResult.value && canEdit.value && canConfirm.value
+  && (editable.value || reviewCorrectionEnabled.value)))
+const previewConfirmText = computed(() => previewResult.value?.recognitionStatus === 'CONFIRMED'
+  ? '保存重量修正'
+  : '确认重量')
+
+function formatWeight(value: number | null, unit = 'KG') {
+  return value == null ? '—' : `${Number(value).toFixed(3)} ${unit}`
+}
+
+function palletOptionLabel(option: WeightPalletOption) {
+  return `${option.palletType || '未记录类型'} · 皮重 ${formatWeight(option.tareWeightKg)} · 容量 ${option.capacityCbm} m³`
+}
+
+function actionKey(action: string, id: string) {
+  return `${action}:${id}`
+}
+
+function isActionLoading(action: string, id: string) {
+  return activeAction.value === actionKey(action, id)
+}
+
+function normalizeUnit(value: string | null) {
+  return value?.trim().toUpperCase().startsWith('LB') ? 'LB' as const : 'KG' as const
+}
+
+function isSupportedUnit(value: string | null) {
+  return ['KG', 'KGS', 'LB', 'LBS'].includes(value?.trim().toUpperCase() || '')
+}
+
+function syncWeightDrafts(results: WeightResultResource[]) {
+  weightDrafts.value = Object.fromEntries(results.map((row) => [row.id, {
+    value: row.adjustedWeightValue ?? row.ocrWeightValue,
+    unit: normalizeUnit(row.adjustedWeightUnit ?? row.ocrWeightUnit),
+    reason: '',
+  }]))
+}
+
+function ensureWeightDraft(row: WeightResultResource) {
+  weightDrafts.value[row.id] ??= {
+    value: row.adjustedWeightValue ?? row.ocrWeightValue,
+    unit: normalizeUnit(row.adjustedWeightUnit ?? row.ocrWeightUnit),
+    reason: '',
+  }
+}
+
+function isWeightDraftValid(row: WeightResultResource) {
+  const draft = weightDrafts.value[row.id]
+  const value = Number(draft?.value)
+  return Boolean(draft
+    && Number.isFinite(value)
+    && value >= minimumWeight[draft.unit]
+    && value <= maximumSafeWeight)
+}
+
+function draftGrossWeightKg(row: WeightResultResource) {
+  const draft = weightDrafts.value[row.id]
+  if (!draft || !Number.isFinite(Number(draft.value))) return null
+  const value = Number(draft.value)
+  return draft.unit === 'LB' ? value * 0.45359237 : value
+}
+
+function showActionError(error: unknown, fallback: string) {
+  const details = getApiErrorDetails(error, fallback)
+  const requestReference = details.requestId ? `（请求 ID：${details.requestId}）` : ''
+  ElMessage.error({
+    message: `${details.message}${requestReference}`,
+    duration: 5_000,
+    showClose: true,
+  })
+}
+
+function cardWeight(row: WeightResultResource) {
+  if (row.recognitionStatus === 'CONFIRMED') return formatWeight(row.netWeightKg)
+  const draft = weightDrafts.value[row.id]
+  return formatWeight(draft?.value ?? null, draft?.unit ?? 'KG')
+}
+
+function putawayStatusLabel(status: WeightResultResource['slotStatus']) {
+  return ({
+    RESERVED_EMPTY: '预留空位',
+    BOUND: '待上架',
+    TRANSFERRED: '已上架',
+    RELEASED: '已释放',
+  } as const)[status as Exclude<WeightResultResource['slotStatus'], null>] || '未分配'
+}
+
+function hasWeightDraftChanged(row: WeightResultResource) {
+  const draft = weightDrafts.value[row.id]
+  if (!draft) return false
+  const savedValue = row.adjustedWeightValue ?? row.ocrWeightValue
+  const rawSavedUnit = row.adjustedWeightUnit ?? row.ocrWeightUnit
+  const savedUnit = normalizeUnit(rawSavedUnit)
+  if (!isSupportedUnit(rawSavedUnit)) return true
+  return Number(draft.value) !== Number(savedValue) || draft.unit !== savedUnit
+}
+
+function buildAdjustmentReason(row: WeightResultResource) {
+  const draft = weightDrafts.value[row.id]
+  const ocrUnit = row.ocrWeightUnit?.trim().toUpperCase()
+  const ocrValue = row.ocrWeightValue == null
+    ? '—'
+    : `${Number(row.ocrWeightValue).toFixed(3)}${ocrUnit ? ` ${ocrUnit}` : '（单位缺失）'}`
+  return `OCR 原值 ${ocrValue}，人工确认 ${formatWeight(Number(draft.value), draft.unit)}`
+}
+
+function emitWorkspaceChanged() {
+  emit(
+    'summaryChanged',
+    workspace.value?.actualGrossWeightKg ?? null,
+    workspace.value?.actualNetWeightKg ?? null,
+    workspace.value?.weightResults.some((item) => item.recognitionStatus === 'CONFIRMED') === true,
+  )
+  emit('changed')
+}
+
+async function loadWorkspace() {
+  if (!customerId.value || !props.inboundId || !canView.value) {
+    workspace.value = null
+    weightDrafts.value = {}
+    return
+  }
+  const sequence = ++loadSequence
+  loading.value = true
+  loadError.value = null
+  try {
+    const result = await getWeightWorkspace(customerId.value, props.inboundId)
+    if (sequence === loadSequence) {
+      workspace.value = result
+      syncWeightDrafts(result.weightResults)
+    }
+  } catch (error) {
+    if (sequence !== loadSequence) return
+    loadError.value = getApiErrorDetails(error, '称重与 OCR 数据加载失败，请稍后重试')
+  } finally {
+    if (sequence === loadSequence) loading.value = false
+  }
+}
+
+async function loadPalletOptions(keyword = palletKeyword.value) {
+  if (!canLoadPalletOptions.value) {
+    cancelPalletOptionsLoad()
+    palletOptions.value = []
+    selectedPalletId.value = ''
+    palletError.value = null
+    return
+  }
+  cancelPalletOptionsLoad()
+  const sequence = ++palletLoadSequence
+  const controller = new AbortController()
+  palletAbortController = controller
+  palletKeyword.value = keyword.trim()
+  palletLoading.value = true
+  palletError.value = null
+  try {
+    const result = await getWeightPalletOptions(customerId.value, props.inboundId, {
+      page: 1,
+      size: PALLET_OPTION_PAGE_SIZE,
+      keyword: palletKeyword.value || undefined,
+      signal: controller.signal,
+    })
+    if (sequence !== palletLoadSequence || controller.signal.aborted) return
+    palletOptions.value = result.records
+    if (!result.records.some((option) => option.palletId === selectedPalletId.value)) selectedPalletId.value = ''
+  } catch (error) {
+    if (sequence !== palletLoadSequence || controller.signal.aborted) return
+    palletOptions.value = []
+    selectedPalletId.value = ''
+    palletError.value = getApiErrorDetails(error, '可选托盘加载失败，请稍后重试')
+  } finally {
+    if (sequence === palletLoadSequence) {
+      palletLoading.value = false
+      if (palletAbortController === controller) palletAbortController = null
+    }
+  }
+}
+
+function searchPalletOptions(keyword: string) {
+  void loadPalletOptions(keyword)
+}
+
+function reloadPalletOptions() {
+  void loadPalletOptions()
+}
+
+function cancelPalletOptionsLoad() {
+  ++palletLoadSequence
+  palletAbortController?.abort()
+  palletAbortController = null
+  palletLoading.value = false
+}
+
+function chooseFile() {
+  if (!editable.value) {
+    ElMessage.warning('当前入库状态不允许上传称重图片')
+    return
+  }
+  if (!selectedPalletId.value) {
+    ElMessage.warning('请先选择本次称重使用的托盘')
+    return
+  }
+  fileInput.value?.click()
+}
+
+function validateImage(file: File) {
+  if (!['image/jpeg', 'image/png', 'image/bmp'].includes(file.type)) return '称重图片仅支持 JPG、PNG、BMP'
+  if (file.size > 5 * 1024 * 1024) return '称重图片不能超过 5MB'
+  return ''
+}
+
+async function handleFileChange(event: Event) {
+  const input = event.target as HTMLInputElement
+  const file = input.files?.[0]
+  input.value = ''
+  if (!file || uploading.value) return
+  const validationError = validateImage(file)
+  if (validationError) {
+    ElMessage.warning(validationError)
+    return
+  }
+  uploading.value = true
+  try {
+    const upload = await uploadWeightImage(customerId.value, props.inboundId, file)
+    const created = await createWeightResult(customerId.value, props.inboundId, {
+      fileId: String(upload.fileId),
+      palletId: selectedPalletId.value,
+      ocrProvider: 'FILE_WEIGHT_OCR',
+      ocrRawText: getWeightOcrRawText(upload),
+      ocrWeightValue: upload.weightValue,
+      ocrWeightUnit: upload.weightUnit,
+      confidence: upload.confidence,
+    })
+    ensureWeightDraft(created)
+    await openPreview(created, URL.createObjectURL(file))
+    await loadWorkspace()
+    ensureWeightDraft(created)
+    emitWorkspaceChanged()
+  } catch (error) {
+    showActionError(error, '称重图片上传失败，请检查后重试')
+  } finally {
+    uploading.value = false
+  }
+}
+
+async function confirmResult(row: WeightResultResource, closeAfterSuccess = false) {
+  const draft = weightDrafts.value[row.id]
+  if (!draft || !isWeightDraftValid(row)) {
+    ElMessage.warning('请输入大于 0 的有效重量')
+    return
+  }
+  const grossWeightKg = draftGrossWeightKg(row)
+  if (grossWeightKg == null || grossWeightKg <= Number(row.palletTareWeightKg)) {
+    ElMessage.warning(`称重毛重必须大于托盘皮重 ${formatWeight(row.palletTareWeightKg)}`)
+    return
+  }
+  const key = actionKey('confirm', row.id)
+  activeAction.value = key
+  try {
+    const payload = { version: row.version } as Parameters<typeof confirmWeightResult>[3]
+    if (hasWeightDraftChanged(row)) {
+      if (!canEdit.value) {
+        ElMessage.warning('当前账号缺少重量修改权限')
+        return
+      }
+      payload.adjustedWeightValue = Number(draft.value)
+      payload.adjustedWeightUnit = draft.unit
+      payload.adjustmentReason = row.recognitionStatus === 'CONFIRMED' && reviewCorrectionEnabled.value
+        ? draft.reason.trim()
+        : buildAdjustmentReason(row)
+    }
+    await confirmWeightResult(customerId.value, props.inboundId, row.id, payload)
+    if (closeAfterSuccess) previewOpen.value = false
+    ElMessage.success(row.recognitionStatus === 'CONFIRMED' ? '含托盘毛重已修正，货物重量和合计已由服务端重算' : '重量已确认')
+    await loadWorkspace()
+    emitWorkspaceChanged()
+    return true
+  } catch (error) {
+    showActionError(error, '重量确认失败，请刷新后重试')
+  } finally {
+    activeAction.value = ''
+  }
+  return false
+}
+
+function releasePreview() {
+  if (previewUrl.value) URL.revokeObjectURL(previewUrl.value)
+  previewUrl.value = ''
+}
+
+async function openPreview(row: WeightResultResource, localUrl = '') {
+  releasePreview()
+  previewResultId.value = row.id
+  previewSnapshot.value = row
+  previewError.value = null
+  previewOpen.value = true
+  if (localUrl) {
+    previewUrl.value = localUrl
+    previewLoading.value = false
+    return
+  }
+  previewLoading.value = true
+  try {
+    const blob = await downloadWeightImage(customerId.value, props.inboundId, row.fileId)
+    previewUrl.value = URL.createObjectURL(blob)
+  } catch (error) {
+    previewError.value = getApiErrorDetails(error, '称重图片读取失败，请稍后重试')
+  } finally {
+    previewLoading.value = false
+  }
+}
+
+async function removeResult(row: WeightResultResource) {
+  try {
+    await ElMessageBox.confirm(
+      row.recognitionStatus === 'CONFIRMED'
+        ? '删除后将重新计算货物总重量；对应库位仍为本票保留，不会释放给其他订单。确认删除这张称重图片吗？'
+        : '对应库位仍为本票保留，不会释放给其他订单。确认删除这张称重图片吗？',
+      '删除称重图片',
+      { customClass: 'admin-density-confirm', type: 'warning', confirmButtonText: '删除', cancelButtonText: '取消' },
+    )
+  } catch {
+    return
+  }
+  const key = actionKey('delete', row.id)
+  activeAction.value = key
+  try {
+    await deleteWeightResult(customerId.value, props.inboundId, row.id, row.version)
+    if (previewResultId.value === row.id) previewOpen.value = false
+    ElMessage.success('称重图片已删除')
+    await loadWorkspace()
+    emitWorkspaceChanged()
+  } catch (error) {
+    showActionError(error, '称重图片删除失败，请刷新后重试')
+  } finally {
+    activeAction.value = ''
+  }
+}
+
+watch(
+  () => [customerId.value, props.inboundId, canView.value] as const,
+  () => {
+    ++loadSequence
+    workspace.value = null
+    palletOptions.value = []
+    selectedPalletId.value = ''
+    palletKeyword.value = ''
+    palletError.value = null
+    weightDrafts.value = {}
+    loadError.value = null
+    previewOpen.value = false
+    releasePreview()
+    void loadWorkspace()
+  },
+  { immediate: true },
+)
+
+watch(
+  () => [customerId.value, props.inboundId, canLoadPalletOptions.value] as const,
+  () => {
+    cancelPalletOptionsLoad()
+    palletOptions.value = []
+    selectedPalletId.value = ''
+    palletKeyword.value = ''
+    palletError.value = null
+    if (canLoadPalletOptions.value) void loadPalletOptions()
+  },
+)
+
+watch(previewOpen, (open) => {
+  if (!open) {
+    releasePreview()
+  }
+})
+onBeforeUnmount(() => {
+  cancelPalletOptionsLoad()
+  palletOptions.value = []
+  selectedPalletId.value = ''
+  releasePreview()
+})
+
+defineExpose({ reload: loadWorkspace })
+</script>
+
+<template>
+  <section class="weight-workspace" aria-labelledby="weight-ocr-title">
+    <header class="weight-heading">
+      <div>
+        <h3 id="weight-ocr-title"><Scale :size="18" aria-hidden="true" />称重图片</h3>
+      </div>
+      <div class="weight-heading__actions">
+        <div v-if="workspace" class="weight-summary-group" aria-live="polite">
+          <div class="weight-summary"><span>实测毛重</span><strong>{{ formatWeight(workspace.actualGrossWeightKg) }}</strong></div>
+          <div class="weight-summary"><span>货物重量</span><strong>{{ formatWeight(workspace.actualNetWeightKg) }}</strong></div>
+        </div>
+        <div class="pallet-picker">
+          <el-select-v2
+            v-if="canEdit && !reviewMode"
+            v-model="selectedPalletId"
+            :options="virtualPalletOptions"
+            aria-label="选择称重托盘"
+            placeholder="选择称重托盘"
+            filterable
+            remote
+            :remote-method="searchPalletOptions"
+            :loading="palletLoading"
+            :disabled="loading || uploading || !editable || !canEdit || Boolean(palletError)"
+          />
+        </div>
+        <input
+          v-if="!reviewMode"
+          ref="fileInput"
+          class="visually-hidden-input"
+          type="file"
+          accept="image/jpeg,image/png,image/bmp"
+          aria-label="选择称重图片"
+          @change="handleFileChange"
+        />
+        <el-button
+          v-if="canEdit && !reviewMode"
+          type="primary"
+          :loading="uploading"
+          :disabled="loading || palletLoading || !editable || !selectedPalletId || Boolean(palletError)"
+          @click="chooseFile"
+        ><ImagePlus :size="16" />上传称重图片</el-button>
+      </div>
+    </header>
+
+    <el-alert v-if="!canView" type="warning" :closable="false" show-icon>
+      当前账号缺少入库测量查看权限。
+    </el-alert>
+
+    <template v-else>
+      <LoadErrorState
+        v-if="loadError"
+        title="称重数据加载失败"
+        :message="loadError.message"
+        :loading="loading"
+        compact
+        @retry="loadWorkspace"
+      >
+        <template #details><ApiErrorMeta :details="loadError" /></template>
+      </LoadErrorState>
+
+      <template v-else>
+        <LoadErrorState
+          v-if="palletError"
+          title="可选托盘加载失败"
+          :message="palletError.message"
+          :loading="palletLoading"
+          compact
+          class="weight-action-error"
+          @retry="reloadPalletOptions"
+        >
+          <template #details><ApiErrorMeta :details="palletError" /></template>
+        </LoadErrorState>
+        <el-alert
+          v-else-if="!palletLoading && palletOptions.length === 0 && editable && canEdit"
+          type="warning"
+          :closable="false"
+          show-icon
+          class="weight-action-error"
+          title="当前仓库暂无可选托盘，暂时不能上传称重图片。"
+        >
+          <el-button size="small" @click="reloadPalletOptions"><RefreshCw :size="14" />重新加载</el-button>
+        </el-alert>
+        <div v-loading="loading" class="weight-list" aria-live="polite">
+          <div v-if="!loading && rows.length === 0" class="weight-empty">
+            <strong>尚未上传称重图片</strong>
+          </div>
+
+          <div v-else class="weight-grid">
+            <article v-for="(row, index) in rows" :key="row.id" class="weight-card">
+              <WeightImageThumbnail
+                :customer-id="customerId"
+                :inbound-id="inboundId"
+                :file-id="row.fileId"
+                :alt="`称重图片 ${index + 1}`"
+                @open="openPreview(row)"
+              />
+              <el-tooltip v-if="canEdit && editable && !reviewMode" content="删除图片" placement="top">
+                <el-button
+                  plain
+                  type="danger"
+                  class="weight-delete"
+                  :aria-label="`删除称重图片 ${index + 1}`"
+                  :loading="isActionLoading('delete', row.id)"
+                  :disabled="Boolean(activeAction)"
+                  @click="removeResult(row)"
+                ><Trash2 :size="16" /></el-button>
+              </el-tooltip>
+              <div class="weight-card__body">
+                <button
+                  type="button"
+                  class="weight-card__value"
+                  :aria-label="`查看称重图片 ${index + 1}，重量 ${cardWeight(row)}`"
+                  @click="openPreview(row)"
+                ><strong>{{ cardWeight(row) }}</strong></button>
+                <dl class="weight-card__facts">
+                  <div><dt>托盘编码</dt><dd :title="row.palletCode">{{ row.palletCode || '未记录编码' }}</dd></div>
+                  <div><dt>托盘类型</dt><dd>{{ row.palletType || '未记录类型' }}</dd></div>
+                  <div><dt>库位</dt><dd :title="row.locationCode || '未分配'">{{ row.locationCode || '未分配' }}<template v-if="row.locationCode"> · {{ putawayStatusLabel(row.slotStatus) }}</template><template v-if="row.sharedOverflow"> · A0 临时溢出位</template></dd></div>
+                  <div><dt>服务端确认毛重</dt><dd>{{ formatWeight(row.grossWeightKg) }}</dd></div>
+                  <div><dt>托盘皮重</dt><dd>{{ formatWeight(row.palletTareWeightKg) }}</dd></div>
+                  <div><dt>货物重量</dt><dd>{{ formatWeight(row.netWeightKg) }}</dd></div>
+                </dl>
+                <el-button
+                  v-if="reviewCorrectionEnabled && row.recognitionStatus === 'CONFIRMED' && canEdit && canConfirm"
+                  class="weight-card__correct"
+                  type="primary"
+                  plain
+                  @click="openPreview(row)"
+                >修改含托盘毛重</el-button>
+              </div>
+            </article>
+          </div>
+        </div>
+      </template>
+    </template>
+
+    <AppDialog class="admin-density-dialog"
+      v-model="previewOpen"
+      title="确认称重图片"
+      :loading="previewLoading"
+      :confirm-loading="Boolean(previewResult && isActionLoading('confirm', previewResult.id))"
+      :confirm-disabled="previewConfirmDisabled"
+      :show-confirm="Boolean(previewResult && previewCanConfirm && (previewResult.recognitionStatus !== 'CONFIRMED' || reviewCorrectionEnabled))"
+      :confirm-text="previewConfirmText"
+      confirm-type="success"
+      width="min(640px, calc(100vw - 28px))"
+      @confirm="previewResult && confirmResult(previewResult, true)"
+    >
+      <LoadErrorState
+        v-if="previewError"
+        title="图片读取失败"
+        :message="previewError.message"
+        :show-retry="false"
+        compact
+      >
+        <template #details><ApiErrorMeta :details="previewError" /></template>
+      </LoadErrorState>
+      <template v-else-if="previewResult">
+        <img v-if="previewUrl" class="weight-preview" :src="previewUrl" alt="当前入库单的称重图片" />
+        <div class="weight-key-facts" aria-label="称重关键数据">
+          <div><span>托盘类型</span><strong>{{ previewResult.palletType || '未记录类型' }}</strong></div>
+          <div><span>当前托盘皮重</span><strong>{{ formatWeight(previewResult.palletTareWeightKg) }}</strong></div>
+          <div><span>OCR 识别毛重</span><strong>{{ formatWeight(previewResult.ocrWeightValue, previewResult.ocrWeightUnit || 'KG') }}</strong></div>
+        </div>
+        <div v-if="weightDrafts[previewResult.id]" class="preview-weight">
+          <label>
+            <span>确认含托盘毛重</span>
+            <el-input-number
+              v-model="weightDrafts[previewResult.id].value"
+              aria-label="当前图片确认重量"
+              :min="minimumWeight[weightDrafts[previewResult.id].unit]"
+              :max="maximumSafeWeight"
+              :precision="3"
+              :controls="false"
+              :disabled="Boolean(activeAction) || !previewInputEditable" placeholder="请输入确认重量" />
+          </label>
+          <el-segmented
+            v-model="weightDrafts[previewResult.id].unit"
+            aria-label="当前图片重量单位"
+            :options="['KG', 'LB']"
+            :disabled="Boolean(activeAction) || !previewInputEditable"
+          />
+        </div>
+        <label v-if="reviewCorrectionEnabled && previewResult.recognitionStatus === 'CONFIRMED' && weightDrafts[previewResult.id]" class="correction-reason">
+          <span>修改原因 *</span>
+          <el-input v-model="weightDrafts[previewResult.id].reason" type="textarea" :rows="3" maxlength="500" show-word-limit placeholder="请填写本次毛重修正原因" />
+        </label>
+      </template>
+    </AppDialog>
+  </section>
+</template>
+
+<style scoped>
+.weight-workspace { min-width: 0; color: var(--el-text-color-primary); }
+.weight-heading { display: flex; align-items: center; justify-content: space-between; gap: 20px; padding-bottom: var(--admin-space-4, 10px); border-bottom: 1px solid var(--cc-border); }
+.weight-heading h3 { display: flex; align-items: center; gap: var(--admin-space-3, 8px); margin: 0; font-size: 15px; }
+.weight-heading h3 svg { color: var(--cc-primary); }
+.weight-heading__actions { display: flex; flex: 0 0 auto; align-items: center; flex-wrap: wrap; justify-content: flex-end; gap: var(--admin-space-6, 16px); }
+.pallet-picker { width: clamp(360px, 36vw, 520px); min-width: 0; }
+.pallet-picker :deep(.el-select) { width: 100%; }
+.weight-summary { display: flex; align-items: baseline; gap: var(--admin-space-2, 6px); white-space: nowrap; }
+.weight-summary-group { display: flex; align-items: center; flex-wrap: wrap; gap: 20px; }
+.weight-summary span { color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); }
+.weight-summary strong { color: #067647; font-size: var(--admin-font-title, 16px); }
+.visually-hidden-input { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); clip-path: inset(50%); white-space: nowrap; }
+.weight-action-error { margin-bottom: 14px; }
+.weight-list { min-height: 0; margin-top: 14px; }
+.weight-empty { display: flex; min-height: 0; align-items: center; gap: var(--admin-space-4, 10px); padding: var(--admin-space-1, 4px) 0 0; color: var(--cc-muted); }
+.weight-empty strong { color: #344054; font-size: var(--admin-font-section, 14px); }
+ .weight-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(190px, 1fr)); gap: 14px; }
+ .weight-card { position: relative; min-width: 0; overflow: hidden; border: 1px solid var(--cc-border); border-radius: 6px; background: var(--admin-surface, #fff); }
+.weight-card__body { padding: var(--admin-space-5, 12px); text-align: center; }
+ .weight-delete { position: absolute; z-index: 2; top: 8px; right: 8px; width: 30px; height: 30px; padding: 0; border: 1px solid rgb(255 255 255 / 82%); background: rgb(255 255 255 / 92%); box-shadow: 0 1px 3px rgb(16 24 40 / 16%); }
+ .weight-card__value { width: 100%; padding: 0; border: 0; background: transparent; color: inherit; cursor: pointer; text-align: center; }
+ .weight-card__value strong { color: #101828; font-size: 17px; }
+ .weight-card__value:focus-visible { outline: 2px solid var(--cc-primary); outline-offset: 4px; }
+.weight-card__facts { display: grid; gap: var(--admin-space-2, 6px); margin: var(--admin-space-4, 10px) 0 0; padding-top: var(--admin-space-4, 10px); border-top: 1px solid var(--cc-border); }
+.weight-card__facts div { display: flex; justify-content: space-between; gap: var(--admin-space-3, 8px); font-size: var(--admin-font-caption, 11px); line-height: 1.4; }
+.weight-card__facts dt { color: var(--cc-muted); }
+.weight-card__facts dd { min-width: 0; margin: 0; color: #344054; overflow-wrap: anywhere; text-align: right; }
+.weight-card__correct { width: 100%; margin: var(--admin-space-5, 12px) 0 0; }
+.weight-preview { display: block; width: 100%; max-height: min(50vh, 460px); object-fit: contain; border-radius: 6px; background: #f2f4f7; }
+.weight-key-facts { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: var(--admin-space-3, 8px) var(--admin-space-5, 12px); margin-top: var(--admin-space-3, 8px); padding: var(--admin-space-3, 8px) 0; border-block: 1px solid var(--cc-border); }
+.weight-key-facts div { display: grid; min-width: 0; gap: var(--admin-space-1, 4px); }
+.weight-key-facts span { color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); }
+.weight-key-facts strong { color: #101828; font-size: var(--admin-font-section, 14px); }
+.preview-weight { display: grid; grid-template-columns: minmax(0, 1fr) 120px; align-items: end; gap: var(--admin-space-5, 12px); margin-top: 14px; }
+.preview-weight label { display: grid; gap: var(--admin-space-2, 6px); color: #475467; font-size: var(--admin-font-caption, 12px); }
+.preview-weight :deep(.el-input-number), .preview-weight :deep(.el-segmented) { width: 100%; }
+.correction-reason { display: grid; gap: var(--admin-space-2, 6px); margin-top: 14px; color: #475467; font-size: var(--admin-font-caption, 12px); }
+
+@media (max-width: 720px) {
+  .weight-heading { flex-direction: column; }
+  .weight-heading__actions { width: 100%; align-items: stretch; flex-direction: column; }
+  .pallet-picker { width: 100%; min-width: 0; }
+  .pallet-picker :deep(.el-select) { width: 100%; }
+  .weight-heading__actions :deep(.el-button) { width: 100%; min-height: 44px; }
+  .weight-summary-group { width: 100%; justify-content: space-between; }
+  .weight-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+}
+
+@media (max-width: 360px) {
+  .weight-grid { grid-template-columns: 1fr; }
+  .preview-weight { grid-template-columns: 1fr; }
+  .weight-key-facts { grid-template-columns: 1fr 1fr; gap: 12px; }
+  .weight-key-facts strong { font-size: 15px; }
+  .weight-card__facts div { align-items: flex-start; flex-direction: column; gap: 2px; }
+  .weight-card__facts dd { text-align: left; }
+}
+</style>
diff --git a/src/modules/inbounds/weight/index.ts b/src/modules/inbounds/weight/index.ts
new file mode 100644
index 00000000..91bef6c1
--- /dev/null
+++ b/src/modules/inbounds/weight/index.ts
@@ -0,0 +1,3 @@
+export { default as WeightOcrPanel } from './components/WeightOcrPanel.vue'
+export type { WeightResultResource, WeightWorkspaceResource } from './types'
+
diff --git a/src/modules/inbounds/weight/types.ts b/src/modules/inbounds/weight/types.ts
new file mode 100644
index 00000000..faf69663
--- /dev/null
+++ b/src/modules/inbounds/weight/types.ts
@@ -0,0 +1,121 @@
+export type WeightRecognitionStatus = 'PENDING_CONFIRM' | 'NEEDS_MANUAL' | 'CONFIRMED' | string
+export type WeightPutawaySlotStatus = 'RESERVED_EMPTY' | 'BOUND' | 'TRANSFERRED' | 'RELEASED'
+
+export interface WeightPalletLocationSlot {
+  slotNo: number
+  reservationId: string
+  locationId: string
+  locationCode: string
+  sharedOverflow: boolean
+  slotStatus: WeightPutawaySlotStatus
+  boundWeightResultId: string | null
+  palletSequence: number | null
+  palletId: string | null
+  palletCode: string | null
+}
+
+export interface WeightPalletLocationGuide {
+  blockId: string
+  reservedSlotCount: number
+  actualPalletCount: number
+  reservedEmptySlotCount: number
+  slots: WeightPalletLocationSlot[]
+}
+
+export interface WeightResultResource {
+  id: string
+  fileId: string
+  palletId: string
+  palletCode: string
+  palletType: string
+  palletCapacityCbm: number
+  palletTareWeightKg: number
+  ocrProvider: string | null
+  ocrRawText: string | null
+  ocrWeightValue: number | null
+  ocrWeightUnit: string | null
+  confidence: number | null
+  adjustedWeightValue: number | null
+  adjustedWeightUnit: string | null
+  grossWeightKg: number | null
+  netWeightKg: number | null
+  recognitionStatus: WeightRecognitionStatus
+  adjustmentReason: string | null
+  adjustedBy: string | null
+  adjustedAt: string | null
+  confirmedBy: string | null
+  confirmedAt: string | null
+  palletSequence: number | null
+  blockId: string | null
+  slotNo: number | null
+  reservationId: string | null
+  locationId: string | null
+  locationCode: string | null
+  sharedOverflow: boolean | null
+  slotStatus: WeightPutawaySlotStatus | null
+  version: number
+}
+
+export interface WeightWorkspaceResource {
+  inboundId: string
+  inboundCode: string
+  processStatus: string
+  actualGrossWeightKg: number | null
+  actualNetWeightKg: number | null
+  weightResults: WeightResultResource[]
+  palletLocationGuide: WeightPalletLocationGuide | null
+}
+
+export interface WeightPalletOption {
+  palletId: string
+  palletCode: string
+  palletType: string
+  capacityCbm: number
+  tareWeightKg: number
+}
+
+export interface WeightPalletOptionPage {
+  records: WeightPalletOption[]
+  page: number
+  size: number
+  total: number
+  pages: number
+}
+
+export interface WeightImageUploadResult {
+  fileId: string
+  fileName: string
+  contentType: string
+  sizeBytes: number
+  recognitionStatus: string
+  weightValue: number | null
+  weightUnit: string | null
+  confidence: number | null
+  ocrRawText?: string | null
+  rawText?: string | null
+  error: string | null
+}
+
+export interface CreateWeightResultRequest {
+  fileId: string
+  palletId: string
+  ocrProvider: string | null
+  ocrRawText: string | null
+  ocrWeightValue: number | null
+  ocrWeightUnit: string | null
+  confidence: number | null
+}
+
+export interface CorrectWeightResultRequest {
+  version: number
+  adjustedWeightValue: number
+  adjustedWeightUnit: 'KG' | 'LB'
+  adjustmentReason: string
+}
+
+export interface ConfirmWeightResultRequest {
+  version: number
+  adjustedWeightValue?: number
+  adjustedWeightUnit?: 'KG' | 'LB'
+  adjustmentReason?: string
+}
diff --git a/src/modules/inputPlaceholder.contract.test.ts b/src/modules/inputPlaceholder.contract.test.ts
new file mode 100644
index 00000000..3703a38f
--- /dev/null
+++ b/src/modules/inputPlaceholder.contract.test.ts
@@ -0,0 +1,52 @@
+import { readFileSync, readdirSync } from 'node:fs'
+import { extname, join, relative } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const modulesRoot = join(process.cwd(), 'src/modules')
+
+function vueFiles(directory: string): string[] {
+  return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    const path = join(directory, entry.name)
+    if (entry.isDirectory()) return vueFiles(path)
+    return extname(entry.name) === '.vue' ? [path] : []
+  })
+}
+
+function isPermanentlyReadOnly(tag: string): boolean {
+  return (
+    /\s(?:disabled|readonly)(?=\s|\/>|>)/.test(tag) ||
+    /\s(?:disabled|readonly)=(?:""|'')/.test(tag) ||
+    /\s(?::|v-bind:)(?:disabled|readonly)=(?:"true"|'true')/.test(tag)
+  )
+}
+
+function hasMeaningfulPlaceholder(tag: string): boolean {
+  const value = tag.match(/\s(?::|v-bind:)?placeholder\s*=\s*(["'])(.*?)\1/)?.[2]
+  return Boolean(value?.trim())
+}
+
+describe('正式业务模块输入提示合同', () => {
+  it('所有可编辑 el-input 与 el-input-number 都提供 placeholder', () => {
+    const violations: string[] = []
+
+    for (const file of vueFiles(modulesRoot)) {
+      const source = readFileSync(file, 'utf8').replace(/<!--[\s\S]*?-->/g, (comment) =>
+        comment.replace(/[^\n]/g, ' '),
+      )
+      const openingTag = /<el-input(?:-number)?\b(?:"[^"]*"|'[^']*'|[^'">])*>/g
+
+      for (const match of source.matchAll(openingTag)) {
+        const tag = match[0]
+        if (isPermanentlyReadOnly(tag)) continue
+        if (hasMeaningfulPlaceholder(tag)) continue
+
+        const line = source.slice(0, match.index).split('\n').length
+        violations.push(
+          `${relative(modulesRoot, file).replaceAll('\\', '/')}:${line} ${tag.replace(/\s+/g, ' ')}`,
+        )
+      }
+    }
+
+    expect(violations, `缺少 placeholder：\n${violations.join('\n')}`).toEqual([])
+  })
+})
diff --git a/src/modules/loading-lists/api/containerFees.test.ts b/src/modules/loading-lists/api/containerFees.test.ts
new file mode 100644
index 00000000..586f080f
--- /dev/null
+++ b/src/modules/loading-lists/api/containerFees.test.ts
@@ -0,0 +1,88 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import { adjustContainerFee, approveContainerFee, approveContainerFeeAllocationGroup, createContainerFee, createContainerFeeAllocationGroup, getContainerSettlementDetails, listContainerFeeSupplierOptions, listContainerFees, rejectContainerFee, uploadContainerFeePaymentVoucher, voidContainerFee, voidContainerFeeAllocationGroup } from './containerFees'
+import { listSuppliers } from '@/modules/suppliers'
+
+vi.mock('@/modules/suppliers', () => ({ listSuppliers: vi.fn() }))
+
+describe('container fee API', () => {
+  beforeEach(() => vi.restoreAllMocks())
+  it('passes accountId and exact controller DTOs', async () => {
+    const get = vi.spyOn(http, 'get').mockResolvedValue({ code: '200', data: [] })
+    const post = vi.spyOn(http, 'post').mockResolvedValue({ code: '200', data: { id: 3, loadingPlanId: 9, containerBookingId: 99, feeItemId: 7, feeItemNameSnapshot: '操作费', direction: 'PAYABLE', supplierId: 41, supplierName: '承运商A', supplierCategory: 'TRUCKING', settlementMode: 'DIRECT_PAID', paidAt: '2026-08-12T10:30:00', paymentMethod: 'BANK_TRANSFER', paymentReferenceNo: 'BANK-7', paymentVoucherFileIds: [9001], businessDate: '2026-08-12', amount: 100, currency: 'CNY', reviewStatus: 'PENDING', sourceStatus: 'ACTIVE', sourceVersion: 1 } })
+    const values = { feeItemId: '7', direction: 'PAYABLE' as const, supplierId: '41', settlementMode: 'DIRECT_PAID' as const, paidAt: '2026-08-12T10:30:00', paymentMethod: 'BANK_TRANSFER' as const, paymentReferenceNo: 'BANK-7', paymentVoucherFileIds: ['9001'], businessDate: '2026-08-12', amount: 100, currency: 'CNY' as const, remark: null }
+    await listContainerFees('9', '11'); const created = await createContainerFee('9', '11', values)
+    await approveContainerFee('9', '11', '3'); await rejectContainerFee('9', '11', '3', '资料不全')
+    await adjustContainerFee('9', '11', '3', { expectedSourceVersion: 2, businessDate: '2026-08-13', amount: 120 }); await voidContainerFee('9', '11', '3', 3)
+    expect(get).toHaveBeenCalledWith('/platform/v1/loading-plans/9/fee-details', { params: { accountId: '11' } })
+    expect(post).toHaveBeenCalledWith('/platform/v1/loading-plans/9/fee-details', values, { params: { accountId: '11' } })
+    expect(post).toHaveBeenCalledWith('/platform/v1/loading-plans/9/fee-details/3/adjust', { expectedSourceVersion: 2, businessDate: '2026-08-13', amount: 120 }, { params: { accountId: '11' } })
+    expect(post).toHaveBeenCalledWith('/platform/v1/loading-plans/9/fee-details/3/void', { expectedSourceVersion: 3 }, { params: { accountId: '11' } })
+    expect(created).toMatchObject({ id: '3', loadingPlanId: '9', containerBookingId: '99', direction: 'PAYABLE', supplierId: '41', supplierName: '承运商A', supplierCategory: 'TRUCKING', settlementMode: 'DIRECT_PAID', paymentVoucherFileIds: ['9001'] })
+  })
+
+  it('writes and reviews one atomic allocation group without an accountId shortcut', async () => {
+    const post = vi.spyOn(http, 'post').mockResolvedValue({ code: '200', data: [] })
+    const fee = { feeItemId: '7', direction: 'RECEIVABLE' as const, supplierId: null,
+      settlementMode: null, paidAt: null, paymentMethod: null, paymentReferenceNo: null,
+      paymentVoucherFileIds: null, businessDate: '2026-09-02', amount: 300,
+      currency: 'CNY' as const, remark: null }
+    const allocations = [
+      { customerId: '11', orderId: '501', orderNo: 'FL-501', inboundId: null, inboundCode: null, amount: 120 },
+      { customerId: '12', orderId: '502', orderNo: 'FL-502', inboundId: '602', inboundCode: 'IB-602', amount: 180 },
+    ]
+    await createContainerFeeAllocationGroup('9', { fee, allocations })
+    await approveContainerFeeAllocationGroup('9', '71')
+    await voidContainerFeeAllocationGroup('9', '71', 1)
+    expect(post).toHaveBeenCalledWith('/platform/v1/loading-plans/9/fee-details/allocation-groups', { fee, allocations })
+    expect(post).toHaveBeenCalledWith('/platform/v1/loading-plans/9/fee-details/allocation-groups/71/approve')
+    expect(post).toHaveBeenCalledWith('/platform/v1/loading-plans/9/fee-details/allocation-groups/71/void', { expectedSourceVersion: 1 })
+  })
+
+  it('uploads a payment voucher in the current customer scope and rejects a mismatched echo', async () => {
+    const post = vi.spyOn(http, 'post').mockResolvedValueOnce({ code: '200', data: { fileId: 9001, tenantId: 11, fileName: '付款凭证.png' } })
+    await expect(uploadContainerFeePaymentVoucher('11', new File(['x'], '付款凭证.png'))).resolves.toEqual({ fileId: '9001', fileName: '付款凭证.png' })
+    expect(post).toHaveBeenCalledWith('/platform/finance/v1/vouchers', expect.any(FormData), { params: { customerId: '11' }, headers: { 'Content-Type': 'multipart/form-data' } })
+    post.mockResolvedValueOnce({ code: '200', data: { fileId: 9002, tenantId: 12, fileName: '错客户.png' } })
+    await expect(uploadContainerFeePaymentVoucher('11', new File(['x'], '错客户.png'))).rejects.toThrow('付款凭证与当前客户不匹配')
+  })
+
+  it('loads only ACTIVE suppliers in the requested category', async () => {
+    vi.mocked(listSuppliers).mockResolvedValue({ records: [
+      { id: '41', name: '承运商A', status: 'ACTIVE', category: 'TRUCKING' },
+      { id: '42', name: '停用承运商', status: 'INACTIVE', category: 'TRUCKING' },
+      { id: '43', name: '报关行', status: 'ACTIVE', category: 'CUSTOMS' },
+    ], page: 1, size: 200, total: 3, pages: 1 } as never)
+    await expect(listContainerFeeSupplierOptions('TRUCKING')).resolves.toEqual([{ id: '41', supplierName: '承运商A', category: 'TRUCKING' }])
+    expect(listSuppliers).toHaveBeenCalledWith({ status: 'ACTIVE', category: 'TRUCKING', page: 1, size: 200 })
+  })
+
+  it('loads every ACTIVE supplier without a category filter when the fee item category is empty', async () => {
+    vi.mocked(listSuppliers).mockResolvedValue({ records: [
+      { id: '41', name: '承运商A', status: 'ACTIVE', category: 'TRUCKING' },
+      { id: '42', name: '停用承运商', status: 'INACTIVE', category: 'TRUCKING' },
+      { id: '43', name: '报关行', status: 'ACTIVE', category: 'CUSTOMS' },
+    ], page: 1, size: 200, total: 3, pages: 1 } as never)
+    await expect(listContainerFeeSupplierOptions(null)).resolves.toEqual([
+      { id: '41', supplierName: '承运商A', category: 'TRUCKING' },
+      { id: '43', supplierName: '报关行', category: 'CUSTOMS' },
+    ])
+    expect(listSuppliers).toHaveBeenCalledWith({ status: 'ACTIVE', category: undefined, page: 1, size: 200 })
+  })
+
+  it('maps settled fees and allocation rows from one container aggregate request', async () => {
+    const get = vi.spyOn(http, 'get').mockResolvedValue({ code: '200', data: {
+      customerId: 11, containerBookingId: 99, settledSourceFeeIds: [7],
+      costs: [{ costId: 81, costNo: 'COST-81', costType: 'TRUCKING', costOrigin: 'CONTAINER_FEE', sourceFeeId: 7, sourceFeeVersion: 2, containerBookingId: 99, supplierName: '承运商A', feeItemName: '拖车费', amount: 300, currency: 'CNY', status: 'CONFIRMED', allocations: [{ allocationId: 1, orderId: 8, inboundId: 9, volumeCbm: 2, totalVolumeCbm: 5, allocationRate: 0.4, allocatedAmount: 120, roundingAdjustment: false }] }],
+    } })
+    const result = await getContainerSettlementDetails('11', '99')
+    expect(result).toMatchObject({ customerId: '11', containerBookingId: '99', settledSourceFeeIds: ['7'], costs: [{ id: '81', containerBookingId: '99', sourceFeeId: '7', amount: 300, allocations: [{ id: '1', orderId: '8', inboundId: '9', allocatedAmount: 120 }] }] })
+    expect(get).toHaveBeenCalledWith('/platform/finance/v1/container-settlement-details', { params: { customerId: '11', containerBookingId: '99' } })
+    expect(get).toHaveBeenCalledTimes(1)
+  })
+
+  it('fails closed when the Finance aggregate does not echo the selected customer and container', async () => {
+    vi.spyOn(http, 'get').mockResolvedValue({ code: '200', data: { customerId: 12, containerBookingId: 99, settledSourceFeeIds: [], costs: [] } })
+    await expect(getContainerSettlementDetails('11', '99')).rejects.toThrow('Finance 聚合结果与柜次或客户上下文不一致')
+  })
+})
diff --git a/src/modules/loading-lists/api/containerFees.ts b/src/modules/loading-lists/api/containerFees.ts
new file mode 100644
index 00000000..5d16c89d
--- /dev/null
+++ b/src/modules/loading-lists/api/containerFees.ts
@@ -0,0 +1,265 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import { listSuppliers, type SupplierCategory } from '@/modules/suppliers'
+
+export type ContainerFeeDirection = 'RECEIVABLE' | 'PAYABLE'
+export type ContainerFeeReviewStatus = 'PENDING' | 'APPROVED' | 'REJECTED'
+export type ContainerFeeSettlementMode = 'ON_ACCOUNT' | 'DIRECT_PAID'
+export type ContainerFeePaymentMethod = 'ONLINE' | 'BANK_TRANSFER' | 'CASH' | 'OTHER'
+
+export interface ContainerFeeResource {
+  id: string
+  loadingPlanId: string
+  customerId?: string
+  allocationGroupId?: string | null
+  allocationOrderId?: string | null
+  allocationOrderNo?: string | null
+  allocationInboundId?: string | null
+  allocationInboundCode?: string | null
+  allocationGroupAmount?: number | null
+  containerBookingId: string | null
+  containerNo: string | null
+  feeItemId: string
+  feeItemName: string
+  direction: ContainerFeeDirection
+  supplierId: string | null
+  supplierName: string | null
+  supplierCategory: SupplierCategory | null
+  settlementMode?: ContainerFeeSettlementMode | null
+  paidAt?: string | null
+  paymentMethod?: ContainerFeePaymentMethod | null
+  paymentReferenceNo?: string | null
+  paymentVoucherFileIds?: string[] | null
+  businessDate: string
+  amount: number
+  currency: 'CNY'
+  reviewStatus: ContainerFeeReviewStatus
+  sourceStatus: 'ACTIVE' | 'VOIDED'
+  sourceVersion: number
+  remark: string | null
+  reviewerName: string | null
+  reviewedAt: string | null
+  reviewReason: string | null
+}
+
+export interface ContainerFeeSaveRequest {
+  feeItemId: string
+  direction: ContainerFeeDirection
+  supplierId: string | null
+  settlementMode: ContainerFeeSettlementMode | null
+  paidAt: string | null
+  paymentMethod: ContainerFeePaymentMethod | null
+  paymentReferenceNo: string | null
+  paymentVoucherFileIds: string[] | null
+  businessDate: string
+  amount: number
+  currency: 'CNY'
+  remark: string | null
+}
+
+export interface ContainerFeeAdjustRequest {
+  expectedSourceVersion: number
+  businessDate: string
+  amount: number
+}
+
+export interface ContainerFeeAllocation {
+  customerId: string
+  orderId: string
+  orderNo: string
+  inboundId: string | null
+  inboundCode: string | null
+  amount: number
+}
+
+export interface ContainerFeeAllocationGroupRequest {
+  fee: ContainerFeeSaveRequest
+  allocations: ContainerFeeAllocation[]
+}
+
+export interface ContainerFeeAllocationGroupAdjustRequest {
+  expectedSourceVersion: number
+  businessDate: string
+  totalAmount: number
+  allocations: Array<{ feeId: string; amount: number }>
+}
+
+export interface ApplicableFeeItem {
+  id: string
+  name: string
+  feeCode: string
+  supplierCategory: SupplierCategory | null
+  warehouseReceivable: boolean
+  warehousePayable: boolean
+  pickupReceivable: boolean
+  pickupPayable: boolean
+}
+
+export interface ContainerFeeSupplierOption {
+  id: string
+  supplierName: string
+  category: SupplierCategory
+}
+
+export interface ContainerCostAllocation {
+  id: string
+  orderId: string
+  inboundId: string | null
+  volumeCbm: number
+  totalVolumeCbm: number
+  allocationRate: number
+  allocatedAmount: number
+  roundingAdjustment: boolean
+}
+
+export interface ContainerCostDetail {
+  id: string
+  costNo: string
+  costType: string
+  costOrigin: string
+  sourceFeeId: string | null
+  sourceFeeVersion: number
+  containerBookingId: string | null
+  supplierName: string | null
+  feeItemName: string
+  amount: number
+  currency: string
+  status: string
+  allocations: ContainerCostAllocation[]
+}
+
+export interface ContainerSettlementDetails {
+  customerId: string
+  containerBookingId: string
+  settledSourceFeeIds: string[]
+  costs: ContainerCostDetail[]
+}
+
+const id = (value: unknown) => value == null ? '' : String(value)
+const numberValue = (value: unknown) => Number.isFinite(Number(value)) ? Number(value) : 0
+const supplierCategories: SupplierCategory[] = ['BOOKING', 'CUSTOMS', 'TRUCKING', 'CERTIFICATE']
+function supplierCategory(value: unknown): SupplierCategory | null {
+  if (value == null || value === '') return null
+  if (supplierCategories.includes(value as SupplierCategory)) return value as SupplierCategory
+  throw new TypeError(`Unsupported supplierCategory: ${String(value)}`)
+}
+const base = (planId: string) => `/platform/v1/loading-plans/${encodeURIComponent(planId)}/fee-details`
+const params = (accountId: string) => ({ accountId })
+
+function normalizeFee(raw: Record<string, unknown>): ContainerFeeResource {
+  return {
+    id: id(raw.id), loadingPlanId: id(raw.loadingPlanId), customerId: id(raw.tenantId),
+    allocationGroupId: raw.allocationGroupId == null ? null : id(raw.allocationGroupId),
+    allocationOrderId: raw.allocationOrderId == null ? null : id(raw.allocationOrderId),
+    allocationOrderNo: raw.allocationOrderNo == null ? null : String(raw.allocationOrderNo),
+    allocationInboundId: raw.allocationInboundId == null ? null : id(raw.allocationInboundId),
+    allocationInboundCode: raw.allocationInboundCode == null ? null : String(raw.allocationInboundCode),
+    allocationGroupAmount: raw.allocationGroupAmount == null ? null : numberValue(raw.allocationGroupAmount),
+    containerBookingId: raw.containerBookingId == null ? null : id(raw.containerBookingId),
+    containerNo: raw.containerNo == null ? null : String(raw.containerNo), feeItemId: id(raw.feeItemId),
+    feeItemName: String(raw.feeItemNameSnapshot || ''), direction: raw.direction as ContainerFeeDirection,
+    supplierId: raw.supplierId == null ? null : id(raw.supplierId), supplierName: raw.supplierName == null ? null : String(raw.supplierName),
+    supplierCategory: supplierCategory(raw.supplierCategory),
+    settlementMode: raw.settlementMode == null ? null : raw.settlementMode as ContainerFeeSettlementMode,
+    paidAt: raw.paidAt == null ? null : String(raw.paidAt), paymentMethod: raw.paymentMethod == null ? null : raw.paymentMethod as ContainerFeePaymentMethod,
+    paymentReferenceNo: raw.paymentReferenceNo == null ? null : String(raw.paymentReferenceNo),
+    paymentVoucherFileIds: Array.isArray(raw.paymentVoucherFileIds) ? raw.paymentVoucherFileIds.map(id) : null,
+    businessDate: String(raw.businessDate || ''), amount: numberValue(raw.amount), currency: 'CNY',
+    reviewStatus: raw.reviewStatus as ContainerFeeReviewStatus,
+    sourceStatus: raw.sourceStatus as ContainerFeeResource['sourceStatus'], sourceVersion: numberValue(raw.sourceVersion),
+    remark: raw.remark == null ? null : String(raw.remark), reviewerName: raw.reviewerName == null ? null : String(raw.reviewerName),
+    reviewedAt: raw.reviewedAt == null ? null : String(raw.reviewedAt), reviewReason: raw.reviewReason == null ? null : String(raw.reviewReason),
+  }
+}
+
+export async function listContainerFees(planId: string, accountId: string) {
+  const response = await http.get<ApiEnvelope<Record<string, unknown>[]>, ApiEnvelope<Record<string, unknown>[]>>(base(planId), { params: params(accountId) })
+  return unwrapApiResponse(response).map(normalizeFee)
+}
+
+export async function createContainerFee(planId: string, accountId: string, payload: ContainerFeeSaveRequest) {
+  const response = await http.post<ApiEnvelope<Record<string, unknown>>, ApiEnvelope<Record<string, unknown>>>(base(planId), payload, { params: params(accountId) })
+  return normalizeFee(unwrapApiResponse(response))
+}
+
+export async function createContainerFeeAllocationGroup(planId: string, payload: ContainerFeeAllocationGroupRequest) {
+  const response = await http.post<ApiEnvelope<Record<string, unknown>[]>, ApiEnvelope<Record<string, unknown>[]>>(`${base(planId)}/allocation-groups`, payload)
+  return unwrapApiResponse(response).map(normalizeFee)
+}
+
+export async function approveContainerFeeAllocationGroup(planId: string, groupId: string) {
+  const response = await http.post<ApiEnvelope<Record<string, unknown>[]>, ApiEnvelope<Record<string, unknown>[]>>(`${base(planId)}/allocation-groups/${encodeURIComponent(groupId)}/approve`)
+  return unwrapApiResponse(response).map(normalizeFee)
+}
+
+export async function rejectContainerFeeAllocationGroup(planId: string, groupId: string, reason: string) {
+  const response = await http.post<ApiEnvelope<Record<string, unknown>[]>, ApiEnvelope<Record<string, unknown>[]>>(`${base(planId)}/allocation-groups/${encodeURIComponent(groupId)}/reject`, { reason })
+  return unwrapApiResponse(response).map(normalizeFee)
+}
+
+export async function adjustContainerFeeAllocationGroup(planId: string, groupId: string, payload: ContainerFeeAllocationGroupAdjustRequest) {
+  const response = await http.post<ApiEnvelope<Record<string, unknown>[]>, ApiEnvelope<Record<string, unknown>[]>>(`${base(planId)}/allocation-groups/${encodeURIComponent(groupId)}/adjust`, payload)
+  return unwrapApiResponse(response).map(normalizeFee)
+}
+
+export async function voidContainerFeeAllocationGroup(planId: string, groupId: string, expectedSourceVersion: number) {
+  await http.post(`${base(planId)}/allocation-groups/${encodeURIComponent(groupId)}/void`, { expectedSourceVersion })
+}
+
+export async function approveContainerFee(planId: string, accountId: string, feeId: string) {
+  await http.post(`${base(planId)}/${encodeURIComponent(feeId)}/approve`, undefined, { params: params(accountId) })
+}
+
+export async function rejectContainerFee(planId: string, accountId: string, feeId: string, reason: string) {
+  await http.post(`${base(planId)}/${encodeURIComponent(feeId)}/reject`, { reason }, { params: params(accountId) })
+}
+
+export async function adjustContainerFee(planId: string, accountId: string, feeId: string, payload: ContainerFeeAdjustRequest) {
+  const response = await http.post<ApiEnvelope<Record<string, unknown>>, ApiEnvelope<Record<string, unknown>>>(`${base(planId)}/${encodeURIComponent(feeId)}/adjust`, payload, { params: params(accountId) })
+  return normalizeFee(unwrapApiResponse(response))
+}
+
+export async function voidContainerFee(planId: string, accountId: string, feeId: string, expectedSourceVersion: number) {
+  await http.post(`${base(planId)}/${encodeURIComponent(feeId)}/void`, { expectedSourceVersion }, { params: params(accountId) })
+}
+
+export async function listApplicableFeeItems() {
+  const response = await http.get<ApiEnvelope<{ records: Record<string, unknown>[] }>, ApiEnvelope<{ records: Record<string, unknown>[] }>>('/platform/v1/fee-items', { params: { status: 'ACTIVE', page: 1, size: 200 } })
+  return (unwrapApiResponse(response).records || []).map((raw) => ({ id: id(raw.id), name: String(raw.feeTypeName || ''), feeCode: String(raw.feeCode || ''), supplierCategory: supplierCategory(raw.supplierCategory), warehouseReceivable: Boolean(raw.warehouseReceivable), warehousePayable: Boolean(raw.warehousePayable), pickupReceivable: Boolean(raw.pickupReceivable), pickupPayable: Boolean(raw.pickupPayable) }))
+}
+
+export async function listContainerFeeSupplierOptions(category: SupplierCategory | null): Promise<ContainerFeeSupplierOption[]> {
+  const page = await listSuppliers({ status: 'ACTIVE', category: category ?? undefined, page: 1, size: 200 })
+  return page.records.filter((supplier) => supplier.status === 'ACTIVE' && (!category || supplier.category === category)).map((supplier) => ({ id: supplier.id, supplierName: supplier.name, category: supplier.category }))
+}
+
+export async function uploadContainerFeePaymentVoucher(customerId: string, file: File): Promise<{ fileId: string; fileName: string }> {
+  const body = new FormData(); body.append('file', file)
+  const raw = unwrapApiResponse(await http.post<ApiEnvelope<Record<string, unknown>>, ApiEnvelope<Record<string, unknown>>>('/platform/finance/v1/vouchers', body, {
+    params: { customerId }, headers: { 'Content-Type': 'multipart/form-data' },
+  }))
+  const fileId = raw.fileId == null ? '' : id(raw.fileId)
+  const echoedCustomerId = raw.tenantId == null ? id(raw.customerId ?? customerId) : id(raw.tenantId)
+  if (!fileId || echoedCustomerId !== customerId) throw new Error('付款凭证与当前客户不匹配')
+  return { fileId, fileName: String(raw.fileName || raw.file_name || file.name) }
+}
+
+export async function getContainerSettlementDetails(customerId: string, containerBookingId: string): Promise<ContainerSettlementDetails> {
+  const response = await http.get<ApiEnvelope<Record<string, unknown>>, ApiEnvelope<Record<string, unknown>>>('/platform/finance/v1/container-settlement-details', { params: { customerId, containerBookingId } })
+  const raw = unwrapApiResponse(response)
+  if (id(raw.customerId) !== customerId || id(raw.containerBookingId) !== containerBookingId) throw new Error('Finance 聚合结果与柜次或客户上下文不一致')
+  const costs = (Array.isArray(raw.costs) ? raw.costs : []).map((value) => {
+    const cost = value as Record<string, unknown>
+    if (id(cost.containerBookingId) !== containerBookingId) throw new Error('Finance 聚合成本与柜次上下文不一致')
+    return {
+      id: id(cost.costId), costNo: String(cost.costNo || ''), costType: String(cost.costType || ''), costOrigin: String(cost.costOrigin || ''),
+      sourceFeeId: cost.sourceFeeId == null ? null : id(cost.sourceFeeId), sourceFeeVersion: numberValue(cost.sourceFeeVersion),
+      containerBookingId: cost.containerBookingId == null ? null : id(cost.containerBookingId), supplierName: cost.supplierName == null ? null : String(cost.supplierName),
+      feeItemName: String(cost.feeItemName || ''), amount: numberValue(cost.amount), currency: String(cost.currency || ''), status: String(cost.status || ''),
+      allocations: (Array.isArray(cost.allocations) ? cost.allocations : []).map((value) => {
+        const allocation = value as Record<string, unknown>
+        return { id: id(allocation.allocationId), orderId: id(allocation.orderId), inboundId: allocation.inboundId == null ? null : id(allocation.inboundId), volumeCbm: numberValue(allocation.volumeCbm), totalVolumeCbm: numberValue(allocation.totalVolumeCbm), allocationRate: numberValue(allocation.allocationRate), allocatedAmount: numberValue(allocation.allocatedAmount), roundingAdjustment: Boolean(allocation.roundingAdjustment) }
+      }),
+    }
+  })
+  return { customerId, containerBookingId, settledSourceFeeIds: (Array.isArray(raw.settledSourceFeeIds) ? raw.settledSourceFeeIds : []).map(id), costs }
+}
diff --git a/src/modules/loading-lists/api/platformLoadingLists.test.ts b/src/modules/loading-lists/api/platformLoadingLists.test.ts
new file mode 100644
index 00000000..fd6a5f27
--- /dev/null
+++ b/src/modules/loading-lists/api/platformLoadingLists.test.ts
@@ -0,0 +1,179 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import {
+  getConfirmedLoadingList,
+  confirmPreloadPlan,
+  getPreloadPlan,
+  listConfirmedLoadingLists,
+  listPreloadPlans,
+  preparePalletLabels,
+  printPalletLabels,
+  updatePreloadTransport,
+  updateLoadingItemRemarks,
+} from './platformLoadingLists'
+
+const preloadSummary = {
+  planId: 1900000000000000001n as unknown as string,
+  containerBookingId: 1900000000000000004n as unknown as string,
+  preloadNo: 'PL-001',
+  containerNo: 'MSCU1234567',
+  cabinetNo: 'YG-001',
+  customers: [{ accountId: 1900000000000000002n as unknown as string, customerName: '测试客户' }],
+  warehouseId: 1900000000000000003n as unknown as string,
+  warehouseName: '义乌仓',
+  vesselName: 'MATSON',
+  voyageNo: '001E',
+  containerType: '40HQ',
+  status: 'LOADING',
+  skuCount: '2',
+  totalPackageCount: '10',
+  totalVolumeCbm: 12.3,
+  totalGrossWeightKg: 1200,
+  createdAt: '2026-08-10T10:00:00',
+  version: 3,
+  readiness: {
+    containerNoReady: true,
+    preloadLinkCount: 1,
+    confirmedPreloadCount: 0,
+    oceanBookingId: 1900000000000000005n as unknown as string,
+    oceanBookingStatus: 'RELEASED',
+    pdaTaskId: null,
+    pdaTaskStatus: null,
+    confirmationStatus: 'PENDING',
+    canConfirm: true,
+    readyForPda: false,
+    blockingReasons: [],
+  },
+}
+
+const detail = {
+  summary: preloadSummary,
+  items: [{
+    itemId: 11, itemVersion: 4, accountId: 12, orderId: 15, orderNo: 'ORD-001', inboundId: 13, inboundDetailId: 14, containerNo: 'MSCU1234567', productQuantity: 20,
+    customerName: '测试客户', customsTaxMode: 'TAX_REFUND', taxRefundFlag: true, inboundCode: 'RK001', skuCode: 'SKU001', destinationWarehouse: 'ONT8', chineseName: '产品', englishName: null,
+    goodsImageUrl: null, unitType: 'SEALED_PALLET', palletId: 9007199254740993n, palletNo: 'PLT-001', indivisible: true, packageCount: 2, palletCount: 1, grossWeightKg: 10, netWeightKg: 9, volumeCbm: 1,
+    dimensionalWeightKg: 2, unitsPerPackage: 10, fbaTrackingNo: null, shipmentNo: null, shippingMark: null,
+    internalRemark: null, customerRemark: null, warehouseRemark: null, customerServiceRemark: null, loadSequence: 1, frozenAt: null,
+  }],
+  histories: [{ historyId: 21, itemId: 11, operationId: 'transport-21', actionType: 'UPDATE_TRANSPORT', fromStatus: 'LOADING', toStatus: 'LOADING', beforeSnapshot: null, afterSnapshot: null, operatorId: 22, operatorName: '操作员', operationReason: '调整', occurredAt: '2026-08-10T11:00:00' }],
+}
+
+describe('platform loading lists API', () => {
+  beforeEach(() => vi.restoreAllMocks())
+
+  it('queries preload plans without forcing a status so EDITING and LOADING are returned', async () => {
+    const get = vi.spyOn(http, 'get').mockResolvedValue({ code: '200', message: 'ok', data: { records: [preloadSummary], page: '1', size: '20', total: '1', pages: '1' } })
+    const result = await listPreloadPlans({ page: 1, size: 20, keyword: 'PL' })
+
+    expect(get).toHaveBeenCalledWith('/platform/v1/first-leg/loading-plans', { params: { page: 1, size: 20, keyword: 'PL' } })
+    expect(result.total).toBe(1)
+    expect(result.records[0]?.planId).toBe('1900000000000000001')
+    expect(result.records[0]?.containerBookingId).toBe('1900000000000000004')
+    expect(result.records[0]?.readiness.oceanBookingId).toBe('1900000000000000005')
+    expect(result.records[0]?.customers[0]?.accountId).toBe('1900000000000000002')
+  })
+
+  it('normalizes long ids in preload detail items and history', async () => {
+    vi.spyOn(http, 'get').mockResolvedValue({ code: '200', message: 'ok', data: detail })
+    const result = await getPreloadPlan('100', '300')
+
+    expect(result.items[0]).toMatchObject({ itemId: '11', itemVersion: 4, accountId: '12', orderId: '15', orderNo: 'ORD-001', inboundId: '13', inboundDetailId: '14', unitType: 'SEALED_PALLET', palletId: '9007199254740993', palletNo: 'PLT-001', indivisible: true, containerNo: 'MSCU1234567', productQuantity: '20', customsTaxMode: 'TAX_REFUND', taxRefundFlag: true })
+    expect(result.summary.containerBookingId).toBe('1900000000000000004')
+    expect(result.histories[0]).toMatchObject({ historyId: '21', itemId: '11', operationId: 'transport-21', operatorId: '22' })
+  })
+
+  it('updates transport with expectedVersion, warehouse and idempotency key', async () => {
+    const patch = vi.spyOn(http, 'patch').mockResolvedValue({ code: '200', message: 'ok', data: detail })
+    await updatePreloadTransport('100', '300', { containerNo: 'MSCU1234567', voyageNo: '001E', expectedVersion: 3, operationReason: '调整' })
+
+    expect(patch.mock.calls[0]?.[0]).toBe('/platform/v1/first-leg/loading-plans/100/transport')
+    expect(patch.mock.calls[0]?.[1]).toMatchObject({ expectedVersion: 3, voyageNo: '001E' })
+    expect(patch.mock.calls[0]?.[2]).toMatchObject({ params: { warehouseId: '300' }, headers: { 'Idempotency-Key': expect.any(String) } })
+  })
+
+  it('uses distinct completed list and detail endpoints', async () => {
+    const confirmed = { ...preloadSummary, loadingListNo: 'LL-001', totalNetWeightKg: 1100, totalQuantity: '20', remark: null, createdBy: 9, createdByName: '操作员', status: 'COMPLETED' }
+    const get = vi.spyOn(http, 'get')
+      .mockResolvedValueOnce({ code: '200', message: 'ok', data: { records: [confirmed], page: '1', size: '20', total: '1', pages: '1' } })
+      .mockResolvedValueOnce({ code: '200', message: 'ok', data: { ...detail, summary: confirmed } })
+
+    const page = await listConfirmedLoadingLists({ page: 1, size: 20 })
+    const loaded = await getConfirmedLoadingList('100', '300')
+
+    expect(get.mock.calls[0]?.[0]).toBe('/platform/v1/first-leg/loading-lists')
+    expect(get.mock.calls[0]?.[1]).toEqual({ params: { page: 1, size: 20 } })
+    expect(get.mock.calls[1]?.[0]).toBe('/platform/v1/first-leg/loading-lists/100')
+    expect(page.records[0]?.createdBy).toBe('9')
+    expect(page.records[0]?.containerBookingId).toBe('1900000000000000004')
+    expect(loaded.summary.status).toBe('COMPLETED')
+  })
+
+  it('updates one item editable remarks with both optimistic-lock versions and operation id', async () => {
+    const patch = vi.spyOn(http, 'patch').mockResolvedValue({ code: '200', message: 'ok', data: { id: 100, version: 4, items: [{ id: 11, internalRemark: '内部', warehouseRemark: '装柜时注意外箱', customerServiceRemark: '客服', version: 5 }] } })
+    const result = await updateLoadingItemRemarks('100', '11', {
+      internalRemark: '内部',
+      warehouseRemark: '装柜时注意外箱',
+      customerServiceRemark: '客服',
+      expectedPlanVersion: 3,
+      expectedItemVersion: 4,
+      operationId: 'warehouse-remark-1',
+    })
+
+    expect(patch).toHaveBeenCalledWith(
+      '/platform/v1/first-leg/smart-loading/plans/100/items/11/remarks',
+      { internalRemark: '内部', warehouseRemark: '装柜时注意外箱', customerServiceRemark: '客服', expectedPlanVersion: 3, expectedItemVersion: 4, operationId: 'warehouse-remark-1' },
+    )
+    expect(result).toMatchObject({ id: '100', version: 4, items: [{ id: '11', version: 5, warehouseRemark: '装柜时注意外箱' }] })
+  })
+
+  it('confirms the whole preload plan with expectedVersion and the caller operation id', async () => {
+    const post = vi.spyOn(http, 'post').mockResolvedValue({
+      code: '200', message: 'ok', data: {
+        planId: 1900000000000000001n,
+        containerBookingId: 1900000000000000004n,
+        confirmationStatus: 'CONFIRMED',
+        version: 4,
+        readiness: {
+          ...preloadSummary.readiness,
+          confirmedPreloadCount: 1,
+          confirmationStatus: 'CONFIRMED',
+          canConfirm: false,
+          readyForPda: true,
+          pdaTaskId: 1900000000000000006n,
+          pdaTaskStatus: 'PENDING',
+          blockingReasons: ['PRELOAD_ALREADY_CONFIRMED'],
+        },
+      },
+    })
+
+    const result = await confirmPreloadPlan('1900000000000000001', 3, 'confirm-operation-1')
+
+    expect(post).toHaveBeenCalledWith(
+      '/platform/v1/first-leg/loading-plans/1900000000000000001/confirm',
+      { expectedVersion: 3 },
+      { headers: { 'Idempotency-Key': 'confirm-operation-1' } },
+    )
+    expect(result).toMatchObject({
+      planId: '1900000000000000001',
+      containerBookingId: '1900000000000000004',
+      confirmationStatus: 'CONFIRMED',
+      version: 4,
+      readiness: { pdaTaskId: '1900000000000000006', readyForPda: true },
+    })
+  })
+
+  it('prepares and prints pallet labels by FBA warehouse', async () => {
+    const post = vi.spyOn(http, 'post')
+      .mockResolvedValueOnce({ code: '200', message: 'ok', data: { planId: 10, planNo: 'LP-1', containerNo: 'MSCU6639870', totalCount: 2, groups: [{ destinationWarehouseCode: 'ONT8', destinationWarehouseInternalCode: '154', destinationWarehouseName: 'ONT8', totalCount: 2, labels: [{ labelId: 1, itemId: 2, accountId: 3, inboundId: 4, inboundCode: 'RK-1', containerNo: 'MSCU6639870', destinationWarehouseCode: 'ONT8', destinationWarehouseInternalCode: '154', destinationWarehouseName: 'ONT8', palletIndex: 1, palletCode: 'MSCU6639870-154-001' }] }] } })
+      .mockResolvedValueOnce(new Blob(['pdf'], { type: 'application/pdf' }))
+
+    const manifest = await preparePalletLabels('10', '20')
+    const pdf = await printPalletLabels('10', '20', 'ONT8', 1)
+
+    expect(manifest).toMatchObject({ planId: '10', groups: [{ labels: [{ labelId: '1', itemId: '2', accountId: '3', inboundId: '4' }] }] })
+    expect(pdf.type).toBe('application/pdf')
+    expect(post).toHaveBeenNthCalledWith(1, '/platform/v1/first-leg/loading-plans/10/pallet-labels/prepare', null, { params: { warehouseId: '20' } })
+    expect(post).toHaveBeenNthCalledWith(2, '/platform/v1/first-leg/loading-plans/10/pallet-labels/print', { destinationWarehouseCode: 'ONT8', count: 1 }, { params: { warehouseId: '20' }, responseType: 'blob', timeout: 60_000 })
+  })
+
+})
diff --git a/src/modules/loading-lists/api/platformLoadingLists.ts b/src/modules/loading-lists/api/platformLoadingLists.ts
new file mode 100644
index 00000000..6248fe26
--- /dev/null
+++ b/src/modules/loading-lists/api/platformLoadingLists.ts
@@ -0,0 +1,419 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+
+export type LoadingListMode = 'preload' | 'confirmed'
+
+export interface LoadingCustomer {
+  accountId: string
+  customerName: string | null
+}
+
+export type PreloadConfirmationStatus = 'PENDING' | 'PARTIALLY_CONFIRMED' | 'CONFIRMED'
+export type PreloadBlockingReason =
+  | 'LOADING_PLAN_NOT_EDITING'
+  | 'PRELOAD_LINK_MISSING'
+  | 'CONTAINER_NO_MISSING'
+  | 'OCEAN_BOOKING_NOT_LINKED'
+  | 'OCEAN_BOOKING_NOT_RELEASED'
+  | 'PDA_TASK_ALREADY_CREATED'
+  | 'PRELOAD_ALREADY_CONFIRMED'
+
+export interface PreloadReadiness {
+  containerNoReady: boolean
+  preloadLinkCount: number
+  confirmedPreloadCount: number
+  oceanBookingId: string | null
+  oceanBookingStatus: 'CONFIRMED' | 'CHANGE_PENDING' | 'RELEASED' | 'CANCELLED' | null
+  pdaTaskId: string | null
+  pdaTaskStatus: string | null
+  confirmationStatus: PreloadConfirmationStatus
+  canConfirm: boolean
+  readyForPda: boolean
+  blockingReasons: PreloadBlockingReason[]
+}
+
+export interface PreloadSummary {
+  planId: string
+  containerBookingId: string
+  preloadNo: string
+  containerNo: string | null
+  cabinetNo: string | null
+  customers: LoadingCustomer[]
+  warehouseId: string | null
+  warehouseName: string | null
+  vesselName: string | null
+  voyageNo: string | null
+  containerType: string | null
+  status: string
+  skuCount: string
+  totalPackageCount: string
+  totalVolumeCbm: number
+  totalGrossWeightKg: number
+  createdAt: string
+  version: number
+  readiness: PreloadReadiness
+}
+
+export interface ConfirmedSummary {
+  planId: string
+  containerBookingId: string
+  loadingListNo: string
+  warehouseId: string | null
+  warehouseName: string | null
+  containerNo: string | null
+  cabinetNo: string | null
+  status: string
+  totalPackageCount: string
+  totalGrossWeightKg: number
+  totalNetWeightKg: number
+  totalVolumeCbm: number
+  totalQuantity: string
+  remark: string | null
+  createdBy: string | null
+  createdByName: string | null
+  createdAt: string
+  version: number
+}
+
+export type LoadingListSummary = PreloadSummary | ConfirmedSummary
+
+export interface LoadingItem {
+  itemId: string
+  itemVersion: number
+  accountId: string
+  customerName: string | null
+  customsTaxMode: 'TAX_REFUND' | 'BUY_DECLARATION' | null
+  taxRefundFlag: boolean | null
+  orderId: string
+  orderNo: string
+  inboundId: string
+  inboundDetailId: string
+  inboundCode: string | null
+  containerNo: string | null
+  skuCode: string | null
+  destinationWarehouse: string | null
+  chineseName: string | null
+  englishName: string | null
+  goodsImageUrl: string | null
+  unitType: 'PACKAGE' | 'SEALED_PALLET'
+  palletId: string | null
+  palletNo: string | null
+  indivisible: boolean
+  packageCount: number
+  palletCount: number
+  grossWeightKg: number
+  netWeightKg: number
+  volumeCbm: number
+  dimensionalWeightKg: number
+  productQuantity: string
+  unitsPerPackage: number
+  fbaTrackingNo: string | null
+  shipmentNo: string | null
+  shippingMark: string | null
+  internalRemark: string | null
+  customerRemark: string | null
+  warehouseRemark: string | null
+  customerServiceRemark: string | null
+  loadSequence: number
+  frozenAt: string | null
+}
+
+export interface LoadingHistory {
+  historyId: string
+  itemId: string | null
+  operationId: string
+  actionType: string
+  fromStatus: string | null
+  toStatus: string | null
+  beforeSnapshot: string | null
+  afterSnapshot: string | null
+  operatorId: string
+  operatorName: string | null
+  operationReason: string | null
+  occurredAt: string
+}
+
+export interface LoadingDetail<T extends LoadingListSummary = LoadingListSummary> {
+  summary: T
+  items: LoadingItem[]
+  histories: LoadingHistory[]
+}
+
+export interface LoadingListPage<T extends LoadingListSummary = LoadingListSummary> {
+  records: T[]
+  page: number
+  size: number
+  total: number
+  pages: number
+}
+
+export interface LoadingListQuery {
+  page: number
+  size: number
+  customerId?: string
+  warehouseId?: string
+  keyword?: string
+  createdFrom?: string
+  createdTo?: string
+}
+
+export interface TransportUpdateRequest {
+  containerNo: string | null
+  voyageNo: string | null
+  expectedVersion: number
+  operationReason: string | null
+}
+
+export interface LoadingItemRemarksUpdateRequest {
+  internalRemark: string | null
+  warehouseRemark: string | null
+  customerServiceRemark: string | null
+  expectedPlanVersion: number
+  expectedItemVersion: number
+  operationId: string
+}
+
+export interface LoadingItemRemarksUpdateResponse {
+  id: string
+  version: number
+  items: Array<{ id: string; version: number; internalRemark: string | null; warehouseRemark: string | null; customerServiceRemark: string | null }>
+}
+
+export interface PreloadConfirmationResponse {
+  planId: string
+  containerBookingId: string
+  confirmationStatus: 'CONFIRMED'
+  version: number
+  readiness: PreloadReadiness
+}
+
+type RawId = string | number | null | undefined
+type RawPage<T extends LoadingListSummary> = Omit<LoadingListPage<T>, 'page' | 'size' | 'total' | 'pages'> & {
+  page: string | number
+  size: string | number
+  total: string | number
+  pages: string | number
+}
+
+const basePath = '/platform/v1/first-leg'
+
+function requiredId(value: RawId) {
+  return String(value ?? '')
+}
+
+function optionalId(value: RawId) {
+  return value === null || value === undefined ? null : String(value)
+}
+
+function normalizePreloadReadiness(raw: PreloadReadiness): PreloadReadiness {
+  return {
+    ...raw,
+    oceanBookingId: optionalId(raw.oceanBookingId),
+    pdaTaskId: optionalId(raw.pdaTaskId),
+    blockingReasons: raw.blockingReasons || [],
+  }
+}
+
+function normalizePreloadSummary(raw: PreloadSummary): PreloadSummary {
+  return {
+    ...raw,
+    planId: requiredId(raw.planId),
+    containerBookingId: requiredId(raw.containerBookingId),
+    warehouseId: optionalId(raw.warehouseId),
+    skuCount: String(raw.skuCount ?? '0'),
+    totalPackageCount: String(raw.totalPackageCount ?? '0'),
+    readiness: normalizePreloadReadiness(raw.readiness),
+    customers: (raw.customers || []).map((customer) => ({
+      ...customer,
+      accountId: requiredId(customer.accountId),
+    })),
+  }
+}
+
+function normalizeConfirmedSummary(raw: ConfirmedSummary): ConfirmedSummary {
+  return {
+    ...raw,
+    planId: requiredId(raw.planId),
+    containerBookingId: requiredId(raw.containerBookingId),
+    warehouseId: optionalId(raw.warehouseId),
+    createdBy: optionalId(raw.createdBy),
+    totalPackageCount: String(raw.totalPackageCount ?? '0'),
+    totalQuantity: String(raw.totalQuantity ?? '0'),
+  }
+}
+
+function normalizeItem(raw: LoadingItem): LoadingItem {
+  return {
+    ...raw,
+    itemId: requiredId(raw.itemId),
+    itemVersion: Number(raw.itemVersion),
+    accountId: requiredId(raw.accountId),
+    orderId: requiredId(raw.orderId),
+    inboundId: requiredId(raw.inboundId),
+    inboundDetailId: requiredId(raw.inboundDetailId),
+    palletId: optionalId(raw.palletId),
+    palletNo: raw.palletNo || null,
+    indivisible: Boolean(raw.indivisible),
+    productQuantity: String(raw.productQuantity ?? '0'),
+  }
+}
+
+function normalizeHistory(raw: LoadingHistory): LoadingHistory {
+  return {
+    ...raw,
+    historyId: requiredId(raw.historyId),
+    itemId: optionalId(raw.itemId),
+    operationId: requiredId(raw.operationId),
+    operatorId: requiredId(raw.operatorId),
+  }
+}
+
+export interface PalletLabel {
+  labelId: string
+  itemId: string
+  accountId: string
+  inboundId: string
+  inboundCode: string
+  containerNo: string
+  destinationWarehouseCode: string
+  destinationWarehouseInternalCode: string
+  destinationWarehouseName: string | null
+  palletIndex: number
+  palletCode: string
+}
+
+export interface PalletLabelGroup {
+  destinationWarehouseCode: string
+  destinationWarehouseInternalCode: string
+  destinationWarehouseName: string | null
+  totalCount: number
+  labels: PalletLabel[]
+}
+
+export interface PalletLabelManifest {
+  planId: string
+  planNo: string
+  containerNo: string
+  totalCount: number
+  groups: PalletLabelGroup[]
+}
+
+function normalizePage<T extends LoadingListSummary>(raw: RawPage<T>, normalize: (row: T) => T): LoadingListPage<T> {
+  return {
+    records: (raw.records || []).map(normalize),
+    page: Number(raw.page),
+    size: Number(raw.size),
+    total: Number(raw.total),
+    pages: Number(raw.pages),
+  }
+}
+
+function idempotencyKey(planId: string) {
+  return `admin-preload-transport-${planId}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+}
+
+export async function listPreloadPlans(query: LoadingListQuery) {
+  const response = await http.get<ApiEnvelope<RawPage<PreloadSummary>>, ApiEnvelope<RawPage<PreloadSummary>>>(
+    `${basePath}/loading-plans`,
+    { params: query },
+  )
+  return normalizePage(unwrapApiResponse(response), normalizePreloadSummary)
+}
+
+export async function getPreloadPlan(planId: string, warehouseId: string) {
+  const response = await http.get<ApiEnvelope<LoadingDetail<PreloadSummary>>, ApiEnvelope<LoadingDetail<PreloadSummary>>>(
+    `${basePath}/loading-plans/${planId}`,
+    { params: { warehouseId } },
+  )
+  const result = unwrapApiResponse(response)
+  return {
+    summary: normalizePreloadSummary(result.summary),
+    items: (result.items || []).map(normalizeItem),
+    histories: (result.histories || []).map(normalizeHistory),
+  }
+}
+
+export async function updatePreloadTransport(planId: string, warehouseId: string, request: TransportUpdateRequest) {
+  const response = await http.patch<ApiEnvelope<LoadingDetail<PreloadSummary>>, ApiEnvelope<LoadingDetail<PreloadSummary>>>(
+    `${basePath}/loading-plans/${planId}/transport`,
+    request,
+    { params: { warehouseId }, headers: { 'Idempotency-Key': idempotencyKey(planId) } },
+  )
+  const result = unwrapApiResponse(response)
+  return {
+    summary: normalizePreloadSummary(result.summary),
+    items: (result.items || []).map(normalizeItem),
+    histories: (result.histories || []).map(normalizeHistory),
+  }
+}
+
+export async function updateLoadingItemRemarks(planId: string, itemId: string, request: LoadingItemRemarksUpdateRequest) {
+  const response = await http.patch<ApiEnvelope<LoadingItemRemarksUpdateResponse>, ApiEnvelope<LoadingItemRemarksUpdateResponse>>(
+    `${basePath}/smart-loading/plans/${encodeURIComponent(planId)}/items/${encodeURIComponent(itemId)}/remarks`,
+    request,
+  )
+  const result = unwrapApiResponse(response)
+  return {
+    ...result,
+    id: requiredId(result.id),
+    items: (result.items || []).map((item) => ({ ...item, id: requiredId(item.id), version: Number(item.version) })),
+  }
+}
+
+export async function confirmPreloadPlan(planId: string, expectedVersion: number, operationId: string) {
+  const response = await http.post<ApiEnvelope<PreloadConfirmationResponse>, ApiEnvelope<PreloadConfirmationResponse>>(
+    `${basePath}/loading-plans/${encodeURIComponent(planId)}/confirm`,
+    { expectedVersion },
+    { headers: { 'Idempotency-Key': operationId } },
+  )
+  const result = unwrapApiResponse(response)
+  return {
+    ...result,
+    planId: requiredId(result.planId),
+    containerBookingId: requiredId(result.containerBookingId),
+    readiness: normalizePreloadReadiness(result.readiness),
+  }
+}
+
+export async function listConfirmedLoadingLists(query: LoadingListQuery) {
+  const response = await http.get<ApiEnvelope<RawPage<ConfirmedSummary>>, ApiEnvelope<RawPage<ConfirmedSummary>>>(
+    `${basePath}/loading-lists`,
+    { params: query },
+  )
+  return normalizePage(unwrapApiResponse(response), normalizeConfirmedSummary)
+}
+
+export async function getConfirmedLoadingList(planId: string, warehouseId: string) {
+  const response = await http.get<ApiEnvelope<LoadingDetail<ConfirmedSummary>>, ApiEnvelope<LoadingDetail<ConfirmedSummary>>>(
+    `${basePath}/loading-lists/${planId}`,
+    { params: { warehouseId } },
+  )
+  const result = unwrapApiResponse(response)
+  return {
+    summary: normalizeConfirmedSummary(result.summary),
+    items: (result.items || []).map(normalizeItem),
+    histories: (result.histories || []).map(normalizeHistory),
+  }
+}
+
+export async function preparePalletLabels(planId: string, warehouseId: string) {
+  const response = await http.post<ApiEnvelope<PalletLabelManifest>, ApiEnvelope<PalletLabelManifest>>(
+    `${basePath}/loading-plans/${encodeURIComponent(planId)}/pallet-labels/prepare`, null, { params: { warehouseId } },
+  )
+  const result = unwrapApiResponse(response)
+  return {
+    ...result,
+    planId: requiredId(result.planId),
+    groups: (result.groups || []).map((group) => ({
+      ...group,
+      labels: (group.labels || []).map((label) => ({ ...label, labelId: requiredId(label.labelId), itemId: requiredId(label.itemId), accountId: requiredId(label.accountId), inboundId: requiredId(label.inboundId) })),
+    })),
+  }
+}
+
+export function printPalletLabels(planId: string, warehouseId: string, destinationWarehouseCode?: string, count?: number) {
+  return http.post<Blob, Blob>(
+    `${basePath}/loading-plans/${encodeURIComponent(planId)}/pallet-labels/print`,
+    { destinationWarehouseCode: destinationWarehouseCode || null, count: count || null },
+    { params: { warehouseId }, responseType: 'blob', timeout: 60_000 },
+  )
+}
diff --git a/src/modules/loading-lists/components/ContainerFeesPanel.test.ts b/src/modules/loading-lists/components/ContainerFeesPanel.test.ts
new file mode 100644
index 00000000..1339a279
--- /dev/null
+++ b/src/modules/loading-lists/components/ContainerFeesPanel.test.ts
@@ -0,0 +1,274 @@
+import ElementPlus from 'element-plus'
+import { createPinia, setActivePinia } from 'pinia'
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+import { adjustContainerFee, createContainerFee, getContainerSettlementDetails, listApplicableFeeItems, listContainerFeeSupplierOptions, listContainerFees, uploadContainerFeePaymentVoucher } from '../api/containerFees'
+import ContainerFeesPanel from './ContainerFeesPanel.vue'
+
+vi.mock('../api/containerFees', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../api/containerFees')>()
+  return { ...actual, listContainerFees: vi.fn(), listApplicableFeeItems: vi.fn(), listContainerFeeSupplierOptions: vi.fn(), getContainerSettlementDetails: vi.fn(), createContainerFee: vi.fn(), adjustContainerFee: vi.fn(), uploadContainerFeePaymentVoucher: vi.fn(), approveContainerFee: vi.fn(), rejectContainerFee: vi.fn(), voidContainerFee: vi.fn() }
+})
+
+const panel = readFileSync(resolve(process.cwd(), 'src/modules/loading-lists/components/ContainerFeesPanel.vue'), 'utf8')
+const detail = readFileSync(resolve(process.cwd(), 'src/modules/loading-lists/components/LoadingListDetailDrawer.vue'), 'utf8')
+const containerDetail = readFileSync(resolve(process.cwd(), 'src/modules/container-loading/pages/ContainerDetailView.vue'), 'utf8')
+
+class ResizeObserverStub { observe() {}; unobserve() {}; disconnect() {} }
+function memoryStorage(): Storage { const values = new Map<string, string>(); return { get length() { return values.size }, clear: () => values.clear(), getItem: (key) => values.get(key) ?? null, key: (index) => [...values.keys()][index] ?? null, removeItem: (key) => values.delete(key), setItem: (key, value) => values.set(key, value) } }
+async function mountPanel(permissions: string[], customers = [{ accountId: '11', customerName: '客户A' }], containerBookingId = '99') {
+  const pinia = createPinia(); setActivePinia(pinia)
+  const auth = useAuthStore(); auth.token = 'token'; auth.permissions = permissions
+  useAccessPreviewStore().initializeAfterLogin()
+  const wrapper = mount(ContainerFeesPanel, { attachTo: document.body, props: { planId: '9', containerBookingId, customers, businessReferences: [{ accountId: '11', customerName: '客户A', orderId: '501', orderNo: 'FL-501', inboundId: '601', inboundCode: 'NYEXX2608300001' }] }, global: { plugins: [pinia, ElementPlus] } })
+  await flushPromises(); return wrapper
+}
+
+beforeEach(() => {
+  vi.stubGlobal('ResizeObserver', ResizeObserverStub); vi.stubGlobal('localStorage', memoryStorage()); vi.stubGlobal('sessionStorage', memoryStorage())
+  vi.mocked(listContainerFees).mockReset().mockResolvedValue([]); vi.mocked(listApplicableFeeItems).mockReset().mockResolvedValue([])
+  vi.mocked(listContainerFeeSupplierOptions).mockReset().mockResolvedValue([])
+  vi.mocked(getContainerSettlementDetails).mockReset().mockResolvedValue({ customerId: '11', containerBookingId: '99', settledSourceFeeIds: [], costs: [] }); vi.mocked(createContainerFee).mockReset()
+  vi.mocked(adjustContainerFee).mockReset().mockResolvedValue({} as never)
+  vi.mocked(uploadContainerFeePaymentVoucher).mockReset().mockResolvedValue({ fileId: '9001', fileName: '付款凭证.pdf' })
+  document.body.innerHTML = ''
+})
+
+describe('ContainerFeesPanel contract', () => {
+  it('keeps fee controls and table utilities in compact aligned toolbars', () => {
+    expect(panel).toContain('class="fees-header__actions"')
+    expect(panel).toContain('class="customer-context"')
+    expect(panel).toContain('<template #toolbar-start><div class="fees-table-title">')
+    expect(panel).toContain('class="fees-panel admin-density"')
+  })
+
+  it('is exposed from the domestic container fee tab and derives customer context from real items', () => {
+    expect(detail).not.toContain('ContainerFeesPanel')
+    expect(containerDetail).toContain('title="国内段费用（头程）"')
+    expect(containerDetail).toContain(':container-booking-id="detail.id"')
+    expect(containerDetail).toContain(':plan-id="overview.loadingPlanId"')
+    expect(containerDetail).toContain('item.accountId')
+    expect(panel).toContain('该柜次包含多个客户，请先选择费用归属客户')
+    expect(panel).toContain('装柜明细缺少客户归属，无法安全维护费用')
+  })
+
+  it('covers create, review, reject, approved adjustment and void actions', () => {
+    expect(panel).toContain('新增费用')
+    expect(panel).toContain("row.reviewStatus === 'PENDING'")
+    expect(panel).toContain('approveContainerFee')
+    expect(panel).toContain('rejectContainerFee')
+    expect(panel).toContain("row.reviewStatus === 'APPROVED'")
+    expect(panel).toContain('adjustContainerFee')
+    expect(panel).toContain('voidContainerFee')
+    expect(panel).toContain('调整仅允许修改业务日期和金额')
+    expect(panel).toContain('请先作废后新增')
+    expect(panel).toContain("row.supplierName || '服务端未返回'")
+  })
+
+  it('adjusts only business date and amount while preserving the approved snapshot', async () => {
+    const wrapper = await mountPanel(['firstleg:inbound:fee-detail:view', 'firstleg:inbound:fee-detail:edit'])
+    const item = { id: '2', loadingPlanId: '9', containerBookingId: '99', containerNo: null, feeItemId: '7', feeItemName: '拖车费', direction: 'PAYABLE' as const, supplierId: '41', supplierName: '承运商A', supplierCategory: 'TRUCKING' as const, businessDate: '2026-08-12', amount: 100, currency: 'CNY' as const, reviewStatus: 'APPROVED' as const, sourceStatus: 'ACTIVE' as const, sourceVersion: 3, remark: '原备注', reviewerName: null, reviewedAt: null, reviewReason: null }
+    const state = (wrapper.vm.$ as unknown as { setupState: { openAdjust(value: typeof item): void; save(): Promise<void>; form: { businessDate: string; amount: number } } }).setupState
+    state.openAdjust(item); await flushPromises()
+    state.form.businessDate = '2026-08-13'; state.form.amount = 120
+    await state.save()
+    expect(adjustContainerFee).toHaveBeenCalledWith('9', '11', '2', { expectedSourceVersion: 3, businessDate: '2026-08-13', amount: 120 })
+    expect(wrapper.text()).toContain('已审核费用仍可调整日期与金额')
+  })
+
+  it('shows only server allocations and supplier snapshots', () => {
+    expect(panel).toContain('getContainerSettlementDetails')
+    expect(panel).toContain('仅展示 Finance 已持久化结果')
+    expect(panel).toContain("cost.supplierName || '服务端未返回'")
+    expect(panel).toContain('尚无与该柜次关联的财务分摊结果')
+    expect(panel).not.toMatch(/allocatedAmount\s*=|allocationRate\s*=/)
+    expect(panel).toContain("orderNumbers.get(row.orderId) || '订单编码待补充'")
+    expect(panel).toContain("inboundCodes.get(row.inboundId) || '入仓码待补充'")
+    expect(panel).not.toContain("prop: 'orderId', label: '订单'")
+    expect(panel).not.toContain("prop: 'inboundId', label: '入库单'")
+  })
+
+  it('clears the previous customer context and ignores a late response', async () => {
+    let resolveFirst!: (value: Awaited<ReturnType<typeof listContainerFees>>) => void
+    vi.mocked(listContainerFees).mockImplementation((planId, accountId) => accountId === '11'
+      ? new Promise((resolve) => { resolveFirst = resolve })
+      : Promise.resolve([]))
+    const wrapper = await mountPanel(['firstleg:inbound:fee-detail:view'], [{ accountId: '11', customerName: '客户A' }, { accountId: '22', customerName: '客户B' }])
+    const state = (wrapper.vm.$ as unknown as { setupState: { accountId: string; fees: unknown[]; costs: unknown[]; editorOpen: boolean } }).setupState
+    state.accountId = '11'; await flushPromises(); state.editorOpen = true
+    state.accountId = '22'; await flushPromises()
+    expect(state.fees).toEqual([]); expect(state.costs).toEqual([]); expect(state.editorOpen).toBe(false)
+    resolveFirst([{ id: 'old', loadingPlanId: '9', containerBookingId: '99', containerNo: null, feeItemId: '1', feeItemName: '旧客户费用', direction: 'RECEIVABLE', supplierId: null, supplierName: null, supplierCategory: null, businessDate: '2026-08-12', amount: 10, currency: 'CNY', reviewStatus: 'PENDING', sourceStatus: 'ACTIVE', sourceVersion: 1, remark: null, reviewerName: null, reviewedAt: null, reviewReason: null }])
+    await flushPromises()
+    expect(state.fees).toEqual([])
+    expect(getContainerSettlementDetails).not.toHaveBeenCalledWith('11', expect.anything())
+  })
+
+  it('does not request any Finance data when container fees are empty', async () => {
+    vi.mocked(listContainerFees).mockResolvedValue([])
+    await mountPanel(['firstleg:inbound:fee-detail:view'])
+    expect(getContainerSettlementDetails).not.toHaveBeenCalled()
+  })
+
+  it('loads Finance data only on an explicit single request when fee rows agree', async () => {
+    vi.mocked(listContainerFees).mockResolvedValue([
+      { id: '1', loadingPlanId: '9', containerBookingId: '99', containerNo: null, feeItemId: '1', feeItemName: '费用A', direction: 'RECEIVABLE', supplierId: null, supplierName: null, supplierCategory: null, businessDate: '2026-08-12', amount: 10, currency: 'CNY', reviewStatus: 'PENDING', sourceStatus: 'ACTIVE', sourceVersion: 1, remark: null, reviewerName: null, reviewedAt: null, reviewReason: null },
+    ])
+    const wrapper = await mountPanel(['firstleg:inbound:fee-detail:view'])
+    expect(getContainerSettlementDetails).not.toHaveBeenCalled()
+    await wrapper.findAll('button').find((button) => button.text() === '加载财务状态')!.trigger('click')
+    await flushPromises()
+    expect(getContainerSettlementDetails).toHaveBeenCalledWith('11', '99')
+    expect(getContainerSettlementDetails).toHaveBeenCalledTimes(1)
+  })
+
+  it('fails closed when fee rows disagree with the summary container', async () => {
+    vi.mocked(listContainerFees).mockResolvedValue([
+      { id: '2', loadingPlanId: '9', containerBookingId: '100', containerNo: null, feeItemId: '2', feeItemName: '费用B', direction: 'PAYABLE', supplierId: '41', supplierName: '承运商A', supplierCategory: 'TRUCKING', businessDate: '2026-08-12', amount: 20, currency: 'CNY', reviewStatus: 'PENDING', sourceStatus: 'ACTIVE', sourceVersion: 1, remark: null, reviewerName: null, reviewedAt: null, reviewReason: null },
+    ])
+    const wrapper = await mountPanel(['firstleg:inbound:fee-detail:view', 'firstleg:fee-item:view'])
+    await wrapper.findAll('button').find((button) => button.text() === '加载财务状态')!.trigger('click')
+    await flushPromises()
+    expect(wrapper.text()).toContain('财务状态加载失败')
+    expect(getContainerSettlementDetails).not.toHaveBeenCalled()
+  })
+
+  it('blocks write entry points without a selected customer or edit permission', async () => {
+    const wrapper = await mountPanel(['firstleg:inbound:fee-detail:view'], [{ accountId: '11', customerName: '客户A' }, { accountId: '22', customerName: '客户B' }])
+    const state = (wrapper.vm.$ as unknown as { setupState: { openCreate(): void; save(): Promise<void>; editorOpen: boolean } }).setupState
+    state.openCreate(); await state.save()
+    expect(state.editorOpen).toBe(false)
+    expect(createContainerFee).not.toHaveBeenCalled()
+  })
+
+  it('hides all mutation buttons when permissions are missing', async () => {
+    vi.mocked(listContainerFees).mockResolvedValue([
+      { id: '1', loadingPlanId: '9', containerBookingId: '99', containerNo: null, feeItemId: '1', feeItemName: '待审费用', direction: 'RECEIVABLE', supplierId: null, supplierName: null, supplierCategory: null, businessDate: '2026-08-12', amount: 10, currency: 'CNY', reviewStatus: 'PENDING', sourceStatus: 'ACTIVE', sourceVersion: 1, remark: null, reviewerName: null, reviewedAt: null, reviewReason: null },
+      { id: '2', loadingPlanId: '9', containerBookingId: '99', containerNo: null, feeItemId: '2', feeItemName: '已审费用', direction: 'PAYABLE', supplierId: '41', supplierName: '承运商A', supplierCategory: 'TRUCKING', businessDate: '2026-08-12', amount: 20, currency: 'CNY', reviewStatus: 'APPROVED', sourceStatus: 'ACTIVE', sourceVersion: 1, remark: null, reviewerName: null, reviewedAt: null, reviewReason: null },
+    ])
+    const wrapper = await mountPanel(['firstleg:inbound:fee-detail:view'])
+    for (const label of ['新增费用', '通过', '驳回', '调整', '作废']) expect(wrapper.findAll('button').some((button) => button.text() === label)).toBe(false)
+  })
+
+  it('hides adjustment and void actions for settled fees', async () => {
+    vi.mocked(listContainerFees).mockResolvedValue([
+      { id: '1', loadingPlanId: '9', containerBookingId: '99', containerNo: null, feeItemId: '1', feeItemName: '海运费', direction: 'RECEIVABLE', supplierId: null, supplierName: null, supplierCategory: null, businessDate: '2026-08-12', amount: 300, currency: 'CNY', reviewStatus: 'APPROVED', sourceStatus: 'ACTIVE', sourceVersion: 1, remark: null, reviewerName: null, reviewedAt: null, reviewReason: null },
+    ])
+    vi.mocked(getContainerSettlementDetails).mockResolvedValue({ customerId: '11', containerBookingId: '99', settledSourceFeeIds: ['1'], costs: [] })
+    const wrapper = await mountPanel([
+      'firstleg:inbound:fee-detail:view', 'firstleg:inbound:fee-detail:edit', 'firstleg:inbound:fee-detail:review',
+    ])
+    await wrapper.findAll('button').find((button) => button.text() === '加载财务状态')!.trigger('click')
+    await flushPromises()
+    expect(wrapper.findAll('button').some((button) => button.text() === '调整')).toBe(false)
+    expect(wrapper.findAll('button').some((button) => button.text() === '作废')).toBe(false)
+    expect(getContainerSettlementDetails).toHaveBeenCalledTimes(1)
+  })
+
+  it('hides adjustment and void actions for directly paid payable fees', async () => {
+    vi.mocked(listContainerFees).mockResolvedValue([
+      { id: '2', loadingPlanId: '9', containerBookingId: '99', containerNo: null, feeItemId: '1', feeItemName: '拖车费', direction: 'PAYABLE', supplierId: '41', supplierName: '承运商A', supplierCategory: 'TRUCKING', settlementMode: 'DIRECT_PAID', paidAt: '2026-08-12T10:00:00', paymentMethod: 'BANK_TRANSFER', paymentReferenceNo: 'BANK-1', paymentVoucherFileIds: ['9001'], businessDate: '2026-08-12', amount: 100, currency: 'CNY', reviewStatus: 'APPROVED', sourceStatus: 'ACTIVE', sourceVersion: 1, remark: null, reviewerName: null, reviewedAt: null, reviewReason: null },
+    ])
+    const wrapper = await mountPanel(['firstleg:inbound:fee-detail:view', 'firstleg:inbound:fee-detail:edit', 'firstleg:inbound:fee-detail:review'])
+    expect(wrapper.findAll('button').some((button) => button.text() === '调整')).toBe(false)
+    expect(wrapper.findAll('button').some((button) => button.text() === '作废')).toBe(false)
+  })
+
+  it('keeps receivable usable when supplier permission is missing', async () => {
+    vi.mocked(listApplicableFeeItems).mockResolvedValue([{ id: '7', name: '操作费', feeCode: 'OPERATION', supplierCategory: 'TRUCKING', warehouseReceivable: true, warehousePayable: true, pickupReceivable: false, pickupPayable: false }])
+    const wrapper = await mountPanel(['firstleg:inbound:fee-detail:view', 'firstleg:inbound:fee-detail:edit', 'firstleg:fee-item:view'])
+    const state = (wrapper.vm.$ as unknown as { setupState: { openCreate(): void; form: { direction: string; supplierId: string | null } } }).setupState
+    state.openCreate(); await flushPromises()
+    expect(wrapper.text()).toContain('当前账号缺少供应商查看权限，仅可维护应收费用')
+    expect(listApplicableFeeItems).toHaveBeenCalledTimes(1)
+    expect(listContainerFeeSupplierOptions).not.toHaveBeenCalled()
+    expect(state.form.direction).toBe('RECEIVABLE')
+  })
+
+  it('isolates a supplier load failure and clears supplier fields for receivable', async () => {
+    vi.mocked(listApplicableFeeItems).mockResolvedValue([{ id: '7', name: '操作费', feeCode: 'TRUCKING', supplierCategory: 'TRUCKING', warehouseReceivable: true, warehousePayable: true, pickupReceivable: false, pickupPayable: false }])
+    vi.mocked(listContainerFeeSupplierOptions).mockRejectedValue(new Error('suppliers unavailable'))
+    const wrapper = await mountPanel(['firstleg:inbound:fee-detail:view', 'firstleg:inbound:fee-detail:edit', 'firstleg:fee-item:view', 'platform:supplier:list'])
+    const state = (wrapper.vm.$ as unknown as { setupState: { openCreate(): void; form: { direction: string; feeItemId: string; supplierId: string | null }; feeItems: unknown[] } }).setupState
+    state.openCreate(); await flushPromises()
+    expect(state.feeItems).toHaveLength(1)
+    state.form.direction = 'PAYABLE'; state.form.feeItemId = '7'; await flushPromises()
+    expect(wrapper.text()).toContain('供应商加载失败')
+    state.form.supplierId = '41'; state.form.direction = 'RECEIVABLE'; await flushPromises()
+    expect(state.form.supplierId).toBeNull()
+  })
+
+  it('submits only the selected supplier ID for payable fees', async () => {
+    vi.mocked(listApplicableFeeItems).mockResolvedValue([{ id: '7', name: '操作费', feeCode: 'TRUCKING', supplierCategory: 'TRUCKING', warehouseReceivable: true, warehousePayable: true, pickupReceivable: false, pickupPayable: false }])
+    vi.mocked(listContainerFeeSupplierOptions).mockResolvedValue([{ id: '41', supplierName: '承运商A', category: 'TRUCKING' }])
+    const wrapper = await mountPanel(['firstleg:inbound:fee-detail:view', 'firstleg:inbound:fee-detail:edit', 'firstleg:fee-item:view', 'platform:supplier:list'])
+    const state = (wrapper.vm.$ as unknown as { setupState: { openCreate(): void; save(): Promise<void>; form: { direction: string; feeItemId: string; supplierId: string | null; settlementMode: string | null; amount: number } } }).setupState
+    state.openCreate(); await flushPromises()
+    state.form.direction = 'PAYABLE'; state.form.feeItemId = '7'; await flushPromises(); state.form.supplierId = '41'; state.form.settlementMode = 'ON_ACCOUNT'; state.form.amount = 100
+    await state.save()
+    expect(createContainerFee).toHaveBeenCalledWith('9', '11', expect.objectContaining({ direction: 'PAYABLE', supplierId: '41', settlementMode: 'ON_ACCOUNT', paidAt: null, paymentMethod: null, paymentReferenceNo: null, paymentVoucherFileIds: null }))
+    expect(createContainerFee).not.toHaveBeenCalledWith(expect.anything(), expect.anything(), expect.objectContaining({ partnerId: expect.anything() }))
+  })
+
+  it('allows any loaded ACTIVE supplier when the payable fee item has no supplier category', async () => {
+    vi.mocked(listApplicableFeeItems).mockResolvedValue([{ id: '7', name: '未映射费用', feeCode: 'UNMAPPED', supplierCategory: null, warehouseReceivable: false, warehousePayable: true, pickupReceivable: false, pickupPayable: false }])
+    vi.mocked(listContainerFeeSupplierOptions).mockResolvedValue([{ id: '41', supplierName: '报关行', category: 'CUSTOMS' }])
+    const wrapper = await mountPanel(['firstleg:inbound:fee-detail:view', 'firstleg:inbound:fee-detail:edit', 'firstleg:fee-item:view', 'platform:supplier:list'])
+    const state = (wrapper.vm.$ as unknown as { setupState: { openCreate(): void; save(): Promise<void>; form: { direction: string; feeItemId: string; supplierId: string | null; settlementMode: string | null; amount: number } } }).setupState
+    state.openCreate(); await flushPromises()
+    state.form.direction = 'PAYABLE'; state.form.feeItemId = '7'; await flushPromises(); state.form.supplierId = '41'; state.form.settlementMode = 'ON_ACCOUNT'; state.form.amount = 100
+    await state.save(); await flushPromises()
+    expect(listContainerFeeSupplierOptions).toHaveBeenCalledWith(null)
+    expect(createContainerFee).toHaveBeenCalledWith('9', '11', expect.objectContaining({ direction: 'PAYABLE', supplierId: '41', settlementMode: 'ON_ACCOUNT', paidAt: null, paymentMethod: null, paymentReferenceNo: null, paymentVoucherFileIds: null }))
+  })
+
+  it('fails closed when a supplier candidate does not match the fee-item category', async () => {
+    vi.mocked(listApplicableFeeItems).mockResolvedValue([{ id: '7', name: '拖车费', feeCode: 'TRUCKING', supplierCategory: 'TRUCKING', warehouseReceivable: false, warehousePayable: true, pickupReceivable: false, pickupPayable: false }])
+    vi.mocked(listContainerFeeSupplierOptions).mockResolvedValue([{ id: '41', supplierName: '报关行', category: 'CUSTOMS' }])
+    const wrapper = await mountPanel(['firstleg:inbound:fee-detail:view', 'firstleg:inbound:fee-detail:edit', 'firstleg:fee-item:view', 'platform:supplier:list'])
+    const state = (wrapper.vm.$ as unknown as { setupState: { openCreate(): void; save(): Promise<void>; form: { direction: string; feeItemId: string; supplierId: string | null; amount: number } } }).setupState
+    state.openCreate(); await flushPromises()
+    state.form.direction = 'PAYABLE'; state.form.feeItemId = '7'; await flushPromises(); state.form.supplierId = '41'; state.form.amount = 100
+    await state.save(); await flushPromises()
+    expect(createContainerFee).not.toHaveBeenCalled()
+    expect(document.body.textContent).toContain('所选供应商与费用项目要求的供应商类别不匹配')
+  })
+
+  it('requires fee-item permission before opening a write form', async () => {
+    const wrapper = await mountPanel(['firstleg:inbound:fee-detail:view', 'firstleg:inbound:fee-detail:edit'])
+    const state = (wrapper.vm.$ as unknown as { setupState: { openCreate(): void; editorOpen: boolean } }).setupState
+    state.openCreate(); await flushPromises()
+    expect(state.editorOpen).toBe(false)
+    expect(wrapper.text()).toContain('当前账号缺少费用项目查看权限')
+    expect(listApplicableFeeItems).not.toHaveBeenCalled()
+  })
+
+  it('clears paid inputs for RECEIVABLE and ON_ACCOUNT and shows backend settlement semantics', async () => {
+    vi.mocked(listContainerFees).mockResolvedValue([{ id: '2', loadingPlanId: '9', containerBookingId: '99', containerNo: null, feeItemId: '7', feeItemName: '已付拖车费', direction: 'PAYABLE', supplierId: '41', supplierName: '承运商A', supplierCategory: 'TRUCKING', settlementMode: 'DIRECT_PAID', paidAt: '2026-08-12T10:00:00', paymentMethod: 'BANK_TRANSFER', paymentReferenceNo: 'BANK-1', paymentVoucherFileIds: ['9001'], businessDate: '2026-08-12', amount: 100, currency: 'CNY', reviewStatus: 'PENDING', sourceStatus: 'ACTIVE', sourceVersion: 1, remark: null, reviewerName: null, reviewedAt: null, reviewReason: null }])
+    vi.mocked(listApplicableFeeItems).mockResolvedValue([{ id: '7', name: '操作费', feeCode: 'TRUCKING', supplierCategory: 'TRUCKING', warehouseReceivable: true, warehousePayable: true, pickupReceivable: false, pickupPayable: false }])
+    const wrapper = await mountPanel(['firstleg:inbound:fee-detail:view', 'firstleg:inbound:fee-detail:edit', 'firstleg:fee-item:view', 'platform:supplier:list'])
+    expect(wrapper.text()).toContain('已付成本'); expect(wrapper.text()).toContain('银行转账'); expect(wrapper.text()).toContain('BANK-1')
+    const state = (wrapper.vm.$ as unknown as { setupState: { openCreate(): void; form: { direction: string; settlementMode: string | null; paidAt: string | null; paymentMethod: string | null; paymentReferenceNo: string | null; paymentVoucherFileIds: string[] | null } } }).setupState
+    state.openCreate(); await flushPromises(); Object.assign(state.form, { direction: 'PAYABLE', settlementMode: 'DIRECT_PAID', paidAt: '2026-08-12T10:00:00', paymentMethod: 'CASH', paymentReferenceNo: 'CASH-1', paymentVoucherFileIds: ['9001'] }); await flushPromises()
+    state.form.settlementMode = 'ON_ACCOUNT'; await flushPromises(); expect(state.form).toMatchObject({ settlementMode: 'ON_ACCOUNT', paidAt: null, paymentMethod: null, paymentReferenceNo: null, paymentVoucherFileIds: null })
+    state.form.direction = 'RECEIVABLE'; await flushPromises(); expect(state.form.settlementMode).toBeNull()
+  })
+
+  it('fails closed without DIRECT_PAID evidence and submits a scoped uploaded voucher', async () => {
+    vi.mocked(listApplicableFeeItems).mockResolvedValue([{ id: '7', name: '操作费', feeCode: 'TRUCKING', supplierCategory: 'TRUCKING', warehouseReceivable: false, warehousePayable: true, pickupReceivable: false, pickupPayable: false }])
+    vi.mocked(listContainerFeeSupplierOptions).mockResolvedValue([{ id: '41', supplierName: '承运商A', category: 'TRUCKING' }])
+    const wrapper = await mountPanel(['firstleg:inbound:fee-detail:view', 'firstleg:inbound:fee-detail:edit', 'firstleg:fee-item:view', 'platform:supplier:list'])
+    const state = (wrapper.vm.$ as unknown as { setupState: { openCreate(): void; save(): Promise<void>; selectVoucher(event: Event): Promise<void>; form: { direction: string; feeItemId: string; supplierId: string | null; settlementMode: string | null; paidAt: string | null; paymentMethod: string | null; paymentReferenceNo: string | null; amount: number } } }).setupState
+    state.openCreate(); await flushPromises(); Object.assign(state.form, { direction: 'PAYABLE', feeItemId: '7' }); await flushPromises()
+    Object.assign(state.form, { supplierId: '41', settlementMode: 'DIRECT_PAID', paidAt: '2026-08-12T10:00:00', paymentMethod: 'ONLINE', paymentReferenceNo: null, amount: 100 }); await flushPromises()
+    await state.save(); expect(createContainerFee).not.toHaveBeenCalled()
+    const input = document.createElement('input'); Object.defineProperty(input, 'files', { value: [new File(['x'], '付款凭证.pdf')] })
+    await state.selectVoucher({ target: input } as unknown as Event); await state.save()
+    expect(uploadContainerFeePaymentVoucher).toHaveBeenCalledWith('11', expect.objectContaining({ name: '付款凭证.pdf' }))
+    expect(createContainerFee).toHaveBeenCalledWith('9', '11', expect.objectContaining({ settlementMode: 'DIRECT_PAID', paymentMethod: 'ONLINE', paymentVoucherFileIds: ['9001'] }))
+  })
+})
diff --git a/src/modules/loading-lists/components/ContainerFeesPanel.vue b/src/modules/loading-lists/components/ContainerFeesPanel.vue
new file mode 100644
index 00000000..e6ac949a
--- /dev/null
+++ b/src/modules/loading-lists/components/ContainerFeesPanel.vue
@@ -0,0 +1,450 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, reactive, ref, watch } from 'vue'
+import { FileUp, Plus, X } from '@lucide/vue'
+import { ElMessage, ElMessageBox, type FormInstance, type FormRules } from 'element-plus'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { adjustContainerFee, adjustContainerFeeAllocationGroup, approveContainerFee, approveContainerFeeAllocationGroup, createContainerFee, createContainerFeeAllocationGroup, getContainerSettlementDetails, listApplicableFeeItems, listContainerFeeSupplierOptions, listContainerFees, rejectContainerFee, rejectContainerFeeAllocationGroup, uploadContainerFeePaymentVoucher, voidContainerFee, voidContainerFeeAllocationGroup, type ApplicableFeeItem, type ContainerCostDetail, type ContainerFeeAllocation, type ContainerFeeSupplierOption, type ContainerFeeResource, type ContainerFeeSaveRequest } from '../api/containerFees'
+
+const props = withDefaults(defineProps<{
+  title?: string
+  planId: string
+  containerBookingId: string
+  customers: Array<{ accountId: string; customerName: string | null }>
+  businessReferences: Array<{ accountId: string; customerName: string | null; orderId: string; orderNo: string; inboundId: string | null; inboundCode: string | null }>
+  readonly?: boolean
+}>(), { title: '柜次费用', readonly: false })
+const access = useAccessPreviewStore()
+const accountId = ref('')
+const fees = ref<ContainerFeeResource[]>([])
+const settledFeeIds = ref<Set<string>>(new Set())
+const feeItems = ref<ApplicableFeeItem[]>([])
+const suppliers = ref<ContainerFeeSupplierOption[]>([])
+const costs = ref<ContainerCostDetail[]>([])
+const loading = ref(false)
+const financeLoading = ref(false)
+const financeLoaded = ref(false)
+const error = ref<ApiErrorDetails | null>(null)
+const financeError = ref<ApiErrorDetails | null>(null)
+const feeItemsError = ref<ApiErrorDetails | null>(null)
+const suppliersError = ref<ApiErrorDetails | null>(null)
+const feeItemsLoading = ref(false)
+const suppliersLoading = ref(false)
+const loadedSupplierCategory = ref<string | null | undefined>(undefined)
+const editorOpen = ref(false)
+const editorError = ref<ApiErrorDetails | null>(null)
+const rejectOpen = ref(false)
+const saving = ref(false)
+const target = ref<ContainerFeeResource | null>(null)
+const targetGroupRows = ref<ContainerFeeResource[]>([])
+const allocationDraft = ref<ContainerFeeAllocation[]>([])
+const formRef = ref<FormInstance>()
+const form = reactive<ContainerFeeSaveRequest>({ feeItemId: '', direction: 'RECEIVABLE', supplierId: null, settlementMode: null, paidAt: null, paymentMethod: null, paymentReferenceNo: null, paymentVoucherFileIds: null, businessDate: new Date().toISOString().slice(0, 10), amount: 0, currency: 'CNY', remark: null })
+const settlementModeModel = computed<string>({
+  get: () => form.settlementMode ?? '',
+  set: (value) => { form.settlementMode = value === 'ON_ACCOUNT' || value === 'DIRECT_PAID' ? value : null },
+})
+const voucherFiles = ref<Array<{ fileId: string; fileName: string }>>([])
+const voucherUploading = ref(false)
+const voucherError = ref<ApiErrorDetails | null>(null)
+const rejection = ref('')
+let loadSequence = 0
+let supplierLoadSequence = 0
+
+const canView = computed(() => access.can('firstleg:inbound:fee-detail:view'))
+const canEdit = computed(() => !props.readonly && access.can('firstleg:inbound:fee-detail:edit'))
+const canReview = computed(() => !props.readonly && access.can('firstleg:inbound:fee-detail:review'))
+const canViewFeeItems = computed(() => access.can('firstleg:fee-item:view'))
+const canViewSuppliers = computed(() => access.can('platform:supplier:list'))
+const customerOptions = computed(() => {
+  const unique = new Map<string, string>()
+  for (const item of props.customers) if (item.accountId) unique.set(item.accountId, item.customerName || '客户信息缺失')
+  return [...unique].map(([value, label]) => ({ value, label }))
+})
+const selectedCustomer = computed(() => customerOptions.value.find((item) => item.value === accountId.value))
+const allocationCandidates = computed(() => {
+  const unique = new Map<string, ContainerFeeAllocation>()
+  for (const item of props.businessReferences) {
+    if (!item.accountId || !item.orderId || !item.orderNo) continue
+    const key = `${item.accountId}|${item.orderId}|${item.inboundId || ''}|${item.inboundCode || ''}`
+    unique.set(key, { customerId: item.accountId, orderId: item.orderId, orderNo: item.orderNo,
+      inboundId: item.inboundId || null, inboundCode: item.inboundCode?.trim() || null, amount: 0 })
+  }
+  return [...unique.values()]
+})
+const allocationMode = computed(() => allocationCandidates.value.length > 1 || Boolean(target.value?.allocationGroupId))
+const allocationSum = computed(() => allocationDraft.value.reduce((sum, item) => sum + Number(item.amount || 0), 0))
+const orderNumbers = computed(() => new Map(props.businessReferences.map((item) => [item.orderId, item.orderNo])))
+const inboundCodes = computed(() => new Map(props.businessReferences.map((item) => [item.inboundId, item.inboundCode])))
+const applicableItems = computed(() => feeItems.value.filter((item) => form.direction === 'RECEIVABLE'
+  ? item.warehouseReceivable || item.pickupReceivable : item.warehousePayable || item.pickupPayable))
+const selectedFeeItem = computed(() => feeItems.value.find((item) => item.id === form.feeItemId))
+const columns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', fixed: 'left', width: 270, slotName: 'actions', hideable: false, movable: false },
+  { key: 'feeItemName', prop: 'feeItemName', label: '费用项目', minWidth: 150 },
+  { key: 'direction', label: '方向', width: 90, slotName: 'direction' },
+  { key: 'settlementMode', label: '结算方式', width: 120, slotName: 'settlementMode' },
+  { key: 'paidSummary', label: '已付摘要', minWidth: 290, slotName: 'paidSummary' },
+  { key: 'supplier', label: '供应商/客户', minWidth: 170, slotName: 'supplier' },
+  { key: 'businessReference', label: '费用归属', minWidth: 220, slotName: 'businessReference' },
+  { key: 'amount', label: '金额(CNY)', width: 120, align: 'right', slotName: 'amount' },
+  { key: 'businessDate', prop: 'businessDate', label: '业务日期', width: 120 },
+  { key: 'reviewStatus', label: '审核状态', width: 110, slotName: 'reviewStatus' },
+  { key: 'sourceStatus', label: '来源状态', width: 100, slotName: 'sourceStatus' },
+  { key: 'remark', prop: 'remark', label: '备注', minWidth: 180, showOverflowTooltip: true },
+]
+const allocationColumns: DataTableColumn[] = [
+  { key: 'orderNo', label: '订单编码', fixed: 'left', minWidth: 170, slotName: 'orderNo' },
+  { key: 'inboundCode', label: '入仓码', minWidth: 170, slotName: 'inboundCode' },
+  { key: 'volumeCbm', label: '订单体积(m³)', width: 125, align: 'right', slotName: 'volume' },
+  { key: 'allocationRate', label: '分摊比例', width: 110, align: 'right', slotName: 'rate' },
+  { key: 'allocatedAmount', label: '分摊金额(CNY)', width: 135, align: 'right', slotName: 'allocated' },
+]
+const rules: FormRules = { feeItemId: [{ required: true, message: '请选择费用项目', trigger: 'change' }], businessDate: [{ required: true, message: '请选择业务日期', trigger: 'change' }], amount: [{ type: 'number', min: 0, message: '金额不能小于 0', trigger: 'change' }] }
+
+function resetForm(item?: ContainerFeeResource) {
+  target.value = item || null
+  targetGroupRows.value = []
+  allocationDraft.value = item?.allocationGroupId ? [] : allocationCandidates.value.map((value) => ({ ...value }))
+  Object.assign(form, item ? { feeItemId: item.feeItemId, direction: item.direction, supplierId: item.supplierId, settlementMode: item.settlementMode ?? null, paidAt: item.paidAt ?? null, paymentMethod: item.paymentMethod ?? null, paymentReferenceNo: item.paymentReferenceNo ?? null, paymentVoucherFileIds: item.paymentVoucherFileIds ?? null, businessDate: item.businessDate, amount: item.amount, currency: 'CNY', remark: item.remark }
+    : { feeItemId: '', direction: 'RECEIVABLE', supplierId: null, settlementMode: null, paidAt: null, paymentMethod: null, paymentReferenceNo: null, paymentVoucherFileIds: null, businessDate: new Date().toISOString().slice(0, 10), amount: 0, currency: 'CNY', remark: null })
+  voucherFiles.value = (item?.paymentVoucherFileIds || []).map((fileId) => ({ fileId, fileName: `凭证 ${fileId}` }))
+  voucherError.value = null
+}
+
+function clearPaidFields() {
+  form.paidAt = null; form.paymentMethod = null; form.paymentReferenceNo = null; form.paymentVoucherFileIds = null
+  voucherFiles.value = []; voucherError.value = null
+}
+function settlementLabel(item: ContainerFeeResource) { return item.direction !== 'PAYABLE' ? '—' : item.settlementMode === 'DIRECT_PAID' ? '已付成本' : item.settlementMode === 'ON_ACCOUNT' ? '账期应付' : '未设置' }
+function paymentMethodLabel(value: string | null | undefined) { return ({ ONLINE: '线上支付', BANK_TRANSFER: '银行转账', CASH: '现金', OTHER: '其他' } as Record<string, string>)[value || ''] || '—' }
+function customerLabel(customerId: string) { return customerOptions.value.find((item) => item.value === customerId)?.label || '客户信息缺失' }
+function paidSummary(item: ContainerFeeResource) {
+  if (item.settlementMode !== 'DIRECT_PAID') return '—'
+  const evidence = item.paymentReferenceNo || (item.paymentVoucherFileIds?.length ? `${item.paymentVoucherFileIds.length} 个凭证` : '凭证缺失')
+  return `${item.paidAt?.replace('T', ' ').slice(0, 16) || '时间缺失'} · ${paymentMethodLabel(item.paymentMethod)} · ${evidence}`
+}
+function isSettled(item: ContainerFeeResource) {
+  return item.settlementMode === 'DIRECT_PAID' || settledFeeIds.value.has(item.id)
+}
+async function selectVoucher(event: Event) {
+  const input = event.target as HTMLInputElement
+  const file = input.files?.[0]
+  input.value = ''
+  if (!file || voucherUploading.value || !accountId.value) return
+  if (voucherFiles.value.length >= 20) { voucherError.value = { message: '付款凭证最多上传 20 个' }; return }
+  voucherUploading.value = true; voucherError.value = null
+  try {
+    const uploaded = await uploadContainerFeePaymentVoucher(accountId.value, file)
+    if (!voucherFiles.value.some((item) => item.fileId === uploaded.fileId)) voucherFiles.value.push(uploaded)
+    form.paymentVoucherFileIds = voucherFiles.value.map((item) => item.fileId)
+  } catch (cause) { voucherError.value = getApiErrorDetails(cause, '付款凭证上传或校验失败') }
+  finally { voucherUploading.value = false }
+}
+function removeVoucher(fileId: string) {
+  voucherFiles.value = voucherFiles.value.filter((item) => item.fileId !== fileId)
+  form.paymentVoucherFileIds = voucherFiles.value.length ? voucherFiles.value.map((item) => item.fileId) : null
+}
+
+async function loadFeeItems() {
+  feeItems.value = []; feeItemsError.value = null
+  if (!canViewFeeItems.value) return
+  feeItemsLoading.value = true
+  try { feeItems.value = await listApplicableFeeItems() }
+  catch (cause) { feeItemsError.value = getApiErrorDetails(cause, '费用项目加载失败') }
+  finally { feeItemsLoading.value = false }
+}
+
+async function loadSuppliers() {
+  const sequence = ++supplierLoadSequence
+  suppliers.value = []; loadedSupplierCategory.value = undefined; suppliersError.value = null
+  const item = selectedFeeItem.value
+  if (!canViewSuppliers.value || form.direction !== 'PAYABLE' || !item) return
+  const category = item.supplierCategory
+  suppliersLoading.value = true
+  try {
+    const result = await listContainerFeeSupplierOptions(category)
+    if (sequence === supplierLoadSequence && form.direction === 'PAYABLE' && selectedFeeItem.value?.supplierCategory === category) {
+      suppliers.value = result
+      loadedSupplierCategory.value = category
+    }
+  }
+  catch (cause) { if (sequence === supplierLoadSequence) suppliersError.value = getApiErrorDetails(cause, '供应商加载失败') }
+  finally { if (sequence === supplierLoadSequence) suppliersLoading.value = false }
+}
+
+async function load() {
+  if (!accountId.value || !canView.value) return
+  const sequence = ++loadSequence
+  const requestedAccountId = accountId.value
+  loading.value = true; error.value = null
+  try {
+    const feeRows = await listContainerFees(props.planId, requestedAccountId)
+    if (sequence !== loadSequence || requestedAccountId !== accountId.value) return
+    fees.value = feeRows
+    settledFeeIds.value = new Set(feeRows.filter((item) => item.settlementMode === 'DIRECT_PAID').map((item) => item.id))
+    costs.value = []
+    financeLoaded.value = false
+    financeError.value = null
+  } catch (cause) { if (sequence === loadSequence && requestedAccountId === accountId.value) error.value = getApiErrorDetails(cause, '柜次费用加载失败') }
+  finally { if (sequence === loadSequence) loading.value = false }
+}
+
+async function loadFinanceDetails() {
+  if (!accountId.value || !canView.value || !fees.value.length || financeLoading.value) return
+  const sequence = loadSequence
+  const requestedAccountId = accountId.value
+  const feeRows = [...fees.value]
+  financeLoading.value = true; financeError.value = null
+  try {
+    const containerIds = [...new Set(feeRows.map((item) => item.containerBookingId).filter((value): value is string => Boolean(value)))]
+    if (containerIds.some((value) => value !== props.containerBookingId)) throw new Error('柜次费用与装柜摘要的柜次标识不一致，已停止查询财务分摊')
+    const aggregate = await getContainerSettlementDetails(requestedAccountId, props.containerBookingId)
+    if (sequence !== loadSequence || requestedAccountId !== accountId.value) return
+    settledFeeIds.value = new Set([
+      ...feeRows.filter((item) => item.settlementMode === 'DIRECT_PAID').map((item) => item.id),
+      ...aggregate.settledSourceFeeIds,
+    ])
+    costs.value = aggregate.costs
+    financeLoaded.value = true
+  } catch (cause) {
+    if (sequence === loadSequence && requestedAccountId === accountId.value) financeError.value = getApiErrorDetails(cause, '财务状态加载失败')
+  } finally {
+    if (sequence === loadSequence && requestedAccountId === accountId.value) financeLoading.value = false
+  }
+}
+
+function openCreate() { if (!canEdit.value || !canViewFeeItems.value || !accountId.value) return; resetForm(); editorError.value = null; editorOpen.value = true; void loadFeeItems() }
+async function openAdjust(item: ContainerFeeResource) {
+  if (!canEdit.value || !accountId.value) return
+  resetForm(item); editorError.value = null
+  if (item.allocationGroupId) {
+    try {
+      const all = await Promise.all(customerOptions.value.map((customer) => listContainerFees(props.planId, customer.value)))
+      targetGroupRows.value = all.flat().filter((row, index, rows) => row.allocationGroupId === item.allocationGroupId
+        && rows.findIndex((candidate) => candidate.id === row.id) === index)
+      allocationDraft.value = targetGroupRows.value.map((row) => ({ customerId: '', orderId: row.allocationOrderId || '',
+        orderNo: row.allocationOrderNo || '', inboundId: row.allocationInboundId ?? null,
+        inboundCode: row.allocationInboundCode ?? null, amount: row.amount }))
+      if (!targetGroupRows.value.length) throw new Error('未读取到完整分摊组')
+      form.amount = item.allocationGroupAmount ?? targetGroupRows.value.reduce((sum, row) => sum + row.amount, 0)
+    } catch (cause) { ElMessage.error(getApiErrorDetails(cause, '完整分摊组加载失败').message); return }
+  }
+  editorOpen.value = true
+}
+async function save() {
+  if (!canEdit.value || !accountId.value || (!target.value && !canViewFeeItems.value)) return
+  if (!target.value && form.direction === 'PAYABLE' && !canViewSuppliers.value) { ElMessage.warning('当前账号缺少供应商查看权限，无法保存应付费用'); return }
+  if (!await formRef.value?.validate().catch(() => false)) return
+  editorError.value = null
+  if (target.value) {
+    saving.value = true
+    try {
+      if (target.value.allocationGroupId) {
+        if (Math.abs(allocationSum.value - form.amount) > 0.001 || allocationDraft.value.some((row) => row.amount <= 0)) {
+          ElMessage.warning('每个业务归属的分摊金额必须大于 0，且合计等于费用总额'); return
+        }
+        await adjustContainerFeeAllocationGroup(props.planId, target.value.allocationGroupId, {
+          expectedSourceVersion: target.value.sourceVersion, businessDate: form.businessDate,
+          totalAmount: form.amount, allocations: targetGroupRows.value.map((row, index) => ({
+            feeId: row.id, amount: allocationDraft.value[index]?.amount || 0,
+          })),
+        })
+      } else {
+        await adjustContainerFee(props.planId, accountId.value, target.value.id, {
+          expectedSourceVersion: target.value.sourceVersion,
+          businessDate: form.businessDate,
+          amount: form.amount,
+        })
+      }
+      editorOpen.value = false; ElMessage.success('费用调整已提交审核'); await load()
+    } catch (cause) {
+      const details = getApiErrorDetails(cause, '费用调整失败')
+      editorError.value = details.code === 'A0409'
+        ? { ...details, message: `${details.message}；当前输入已保留，请刷新费用明细后重试。` }
+        : details
+    } finally { saving.value = false }
+    return
+  }
+  if (form.direction === 'PAYABLE' && suppliersError.value) { ElMessage.warning('供应商列表加载失败，无法校验应付费用供应商'); return }
+  if (form.direction === 'PAYABLE' && loadedSupplierCategory.value !== selectedFeeItem.value?.supplierCategory) { ElMessage.warning('供应商候选尚未按费用项目类别加载完成，无法保存'); return }
+  if (form.direction === 'PAYABLE' && !form.supplierId) { ElMessage.warning('应付费用必须选择供应商'); return }
+  const supplier = suppliers.value.find((item) => item.id === String(form.supplierId))
+  if (form.direction === 'PAYABLE' && (!supplier || (selectedFeeItem.value?.supplierCategory && supplier.category !== selectedFeeItem.value.supplierCategory))) { ElMessage.warning('所选供应商与费用项目要求的供应商类别不匹配'); return }
+  if (form.direction === 'PAYABLE' && !form.settlementMode) { ElMessage.warning('应付费用必须选择结算方式'); return }
+  if (voucherUploading.value || voucherError.value) { ElMessage.warning(voucherUploading.value ? '付款凭证正在上传，请稍候' : '付款凭证上传或校验失败，请处理后再保存'); return }
+  if (form.settlementMode === 'DIRECT_PAID' && (!form.paidAt || !form.paymentMethod || (!form.paymentReferenceNo?.trim() && !voucherFiles.value.length))) { ElMessage.warning('直接已付必须填写已付时间、付款方式，并提供流水号或付款凭证'); return }
+  const directPaid = form.direction === 'PAYABLE' && form.settlementMode === 'DIRECT_PAID'
+  const payload: ContainerFeeSaveRequest = { ...form, supplierId: form.direction === 'PAYABLE' ? form.supplierId : null,
+    settlementMode: form.direction === 'PAYABLE' ? form.settlementMode : null,
+    paidAt: directPaid ? form.paidAt : null, paymentMethod: directPaid ? form.paymentMethod : null,
+    paymentReferenceNo: directPaid ? form.paymentReferenceNo?.trim() || null : null,
+    paymentVoucherFileIds: directPaid && voucherFiles.value.length ? voucherFiles.value.map((item) => item.fileId) : null }
+  saving.value = true
+  try {
+    if (allocationMode.value) {
+      const allocations = allocationDraft.value.filter((row) => row.amount > 0)
+      if (!allocations.length || Math.abs(allocationSum.value - form.amount) > 0.001) {
+        ElMessage.warning('请填写分摊金额，分摊合计必须等于费用总额'); return
+      }
+      if (payload.settlementMode === 'DIRECT_PAID' && payload.paymentVoucherFileIds?.length
+        && new Set(allocations.map((row) => row.customerId)).size > 1) {
+        ElMessage.warning('跨客户直接已付费用不能共用客户凭证，请改用付款流水号或分别录入'); return
+      }
+      await createContainerFeeAllocationGroup(props.planId, { fee: payload, allocations })
+    } else {
+      await createContainerFee(props.planId, accountId.value, payload)
+    }
+    editorOpen.value = false; ElMessage.success('费用已新增'); await load()
+  } catch (cause) { editorError.value = getApiErrorDetails(cause, '费用保存失败') }
+  finally { saving.value = false }
+}
+async function approve(item: ContainerFeeResource) { if (!canReview.value || !accountId.value) return; await (item.allocationGroupId
+  ? approveContainerFeeAllocationGroup(props.planId, item.allocationGroupId)
+  : approveContainerFee(props.planId, accountId.value, item.id)).then(() => ElMessage.success(item.allocationGroupId ? '分摊组已整体审核通过' : '费用已审核通过')).then(load).catch((cause) => ElMessage.error(getApiErrorDetails(cause, '审核失败').message)) }
+function openReject(item: ContainerFeeResource) { if (!canReview.value || !accountId.value) return; target.value = item; rejection.value = ''; rejectOpen.value = true }
+async function reject() {
+  if (!canReview.value || !accountId.value || !target.value) return
+  if (!rejection.value.trim()) return ElMessage.warning('请输入驳回原因')
+  saving.value = true
+  try {
+    if (target.value.allocationGroupId) await rejectContainerFeeAllocationGroup(props.planId, target.value.allocationGroupId, rejection.value.trim())
+    else await rejectContainerFee(props.planId, accountId.value, target.value.id, rejection.value.trim())
+    rejectOpen.value = false; ElMessage.success(target.value.allocationGroupId ? '分摊组已整体驳回' : '费用已驳回'); await load()
+  }
+  catch (cause) { ElMessage.error(getApiErrorDetails(cause, '驳回失败').message) } finally { saving.value = false }
+}
+async function voidFee(item: ContainerFeeResource) {
+  if (!canReview.value || !accountId.value) return
+  await ElMessageBox.confirm(`确认作废“${item.feeItemName}”费用？作废后将同步财务来源状态。`, '作废费用', { customClass: 'admin-density-confirm', type: 'warning', confirmButtonText: '确认作废' })
+  await (item.allocationGroupId
+    ? voidContainerFeeAllocationGroup(props.planId, item.allocationGroupId, item.sourceVersion)
+    : voidContainerFee(props.planId, accountId.value, item.id, item.sourceVersion))
+    .then(() => ElMessage.success(item.allocationGroupId ? '分摊组已整体作废' : '费用已作废')).then(load)
+    .catch((cause) => ElMessage.error(getApiErrorDetails(cause, '作废失败').message))
+}
+function money(value: number) { return value.toLocaleString('zh-CN', { minimumFractionDigits: 2, maximumFractionDigits: 2 }) }
+function initializeCustomer() { accountId.value = customerOptions.value.length === 1 ? customerOptions.value[0].value : '' }
+function clearCustomerContext() {
+  loadSequence += 1
+  supplierLoadSequence += 1
+  fees.value = []; settledFeeIds.value = new Set(); costs.value = []; feeItems.value = []; suppliers.value = []; error.value = null; financeError.value = null; feeItemsError.value = null; suppliersError.value = null; loading.value = false; financeLoading.value = false; financeLoaded.value = false; feeItemsLoading.value = false; suppliersLoading.value = false; loadedSupplierCategory.value = undefined
+  editorOpen.value = false; rejectOpen.value = false; target.value = null; rejection.value = ''
+  resetForm()
+}
+watch(customerOptions, initializeCustomer, { immediate: true })
+watch(accountId, () => { clearCustomerContext(); void load() })
+watch(() => form.direction, (direction) => {
+  if (!applicableItems.value.some((item) => item.id === form.feeItemId)) form.feeItemId = ''
+  if (direction === 'RECEIVABLE') { supplierLoadSequence += 1; form.supplierId = null; form.settlementMode = null; clearPaidFields(); suppliers.value = []; loadedSupplierCategory.value = undefined; suppliersError.value = null; suppliersLoading.value = false }
+  else void loadSuppliers()
+})
+watch(() => form.settlementMode, (mode) => { if (mode !== 'DIRECT_PAID') clearPaidFields() })
+watch(() => form.feeItemId, () => { form.supplierId = null; suppliers.value = []; loadedSupplierCategory.value = undefined; suppliersError.value = null; if (form.direction === 'PAYABLE') void loadSuppliers() })
+onMounted(() => void load())
+</script>
+
+<template>
+  <section class="fees-panel admin-density" aria-label="柜次费用维护">
+    <header class="fees-header">
+      <div><h2>{{ title }}</h2><p>费用与财务分摊均来自服务端真实记录</p></div>
+      <div class="fees-header__actions">
+        <label v-if="customerOptions.length > 1" class="customer-context"><span>客户</span><el-select v-model="accountId" placeholder="请选择费用归属客户"><el-option v-for="item in customerOptions" :key="item.value" :label="item.label" :value="item.value" /></el-select></label>
+        <el-button v-if="canEdit && canViewFeeItems && accountId" type="primary" @click="openCreate"><Plus :size="16" />新增费用</el-button>
+      </div>
+    </header>
+    <el-alert v-if="!canView" type="warning" :closable="false" show-icon title="当前账号没有查看柜次费用的权限" />
+    <template v-else>
+      <el-alert v-if="customerOptions.length === 0" type="warning" :closable="false" show-icon title="装柜明细缺少客户归属，无法安全维护费用" />
+      <el-alert v-else-if="!accountId" type="info" :closable="false" show-icon title="该柜次包含多个客户，请先选择费用归属客户" />
+      <el-alert v-else-if="!canViewFeeItems" type="warning" :closable="false" show-icon title="当前账号缺少费用项目查看权限，无法新增费用；已审核费用仍可调整日期与金额" />
+      <LoadErrorState v-else-if="error" compact title="柜次费用加载失败" :message="error.message" @retry="load"><template #details><ApiErrorMeta :details="error" /></template></LoadErrorState>
+      <DataTable v-else :data="fees" :columns="columns" :loading="loading" preference-key="container-fees" row-key="id" empty-text="当前客户暂无柜次费用">
+        <template #toolbar-start><div class="fees-table-title"><strong>费用明细</strong><span>{{ fees.length }} 条</span></div></template>
+        <template #actions="{ row }"><div class="row-actions density-actions"><el-button data-tone="warning" class="density-action" v-if="canReview && row.reviewStatus === 'PENDING'" type="success" @click="approve(row as ContainerFeeResource)">通过</el-button><el-button data-tone="danger" class="density-action" v-if="canReview && row.reviewStatus === 'PENDING'" type="danger" @click="openReject(row as ContainerFeeResource)">驳回</el-button><el-button class="density-action" v-if="canEdit && financeLoaded && row.reviewStatus === 'APPROVED' && row.sourceStatus === 'ACTIVE' && !isSettled(row as ContainerFeeResource)" type="primary" @click="openAdjust(row as ContainerFeeResource)">调整</el-button><el-button data-tone="danger" class="density-action" v-if="canReview && financeLoaded && row.reviewStatus === 'APPROVED' && row.sourceStatus === 'ACTIVE' && !isSettled(row as ContainerFeeResource)" type="danger" @click="voidFee(row as ContainerFeeResource)">作废</el-button></div></template>
+        <template #direction="{ row }"><el-tag :type="row.direction === 'RECEIVABLE' ? 'success' : 'warning'" effect="plain">{{ row.direction === 'RECEIVABLE' ? '应收' : '应付' }}</el-tag></template>
+        <template #settlementMode="{ row }">{{ settlementLabel(row as ContainerFeeResource) }}</template>
+        <template #paidSummary="{ row }">{{ paidSummary(row as ContainerFeeResource) }}</template>
+        <template #supplier="{ row }">{{ row.direction === 'PAYABLE' ? row.supplierName || '服务端未返回' : selectedCustomer?.label || '客户信息缺失' }}</template>
+        <template #businessReference="{ row }"><div class="business-reference"><span>{{ row.allocationOrderNo || '订单号待补充' }}</span><small>{{ row.allocationInboundCode || '无入仓码' }}<template v-if="row.allocationGroupId"> · 分摊组</template></small></div></template>
+        <template #amount="{ row }">{{ money(row.amount) }}</template><template #reviewStatus="{ row }"><StatusBadge :status="row.reviewStatus === 'PENDING' ? '待审核' : row.reviewStatus === 'APPROVED' ? '已通过' : '已驳回'" /></template><template #sourceStatus="{ row }"><StatusBadge :status="row.sourceStatus === 'ACTIVE' ? '有效' : '已作废'" /></template>
+      </DataTable>
+
+      <div v-if="accountId && fees.length" class="allocation-section"><header><div><h3>财务体积分摊</h3><p>{{ selectedCustomer?.label }} · 仅展示 Finance 已持久化结果</p></div><el-button :loading="financeLoading" @click="loadFinanceDetails">{{ financeLoaded ? '刷新财务状态' : '加载财务状态' }}</el-button></header><LoadErrorState v-if="financeError" compact title="财务状态加载失败" :message="financeError.message" @retry="loadFinanceDetails"><template #details><ApiErrorMeta :details="financeError" /></template></LoadErrorState><el-empty v-else-if="!financeLoaded" description="点击加载财务状态后查看结算与成本分摊" :image-size="64" /><el-empty v-else-if="!financeLoading && costs.length === 0" description="尚无与该柜次关联的财务分摊结果" :image-size="64" /><article v-for="cost in costs" :key="cost.id" class="cost-block"><div class="cost-summary"><strong>{{ cost.feeItemName || '柜次成本' }}</strong><span>供应商：{{ cost.supplierName || '服务端未返回' }}</span><span>金额：¥{{ money(cost.amount) }}</span></div><DataTable :data="cost.allocations" :columns="allocationColumns" :preference-key="`container-cost-${cost.id}`" row-key="id" empty-text="服务端未返回分摊明细"><template #orderNo="{ row }">{{ orderNumbers.get(row.orderId) || '订单编码待补充' }}</template><template #inboundCode="{ row }">{{ row.inboundId ? (inboundCodes.get(row.inboundId) || '入仓码待补充') : '—' }}</template><template #volume="{ row }">{{ row.volumeCbm.toFixed(3) }}</template><template #rate="{ row }">{{ (row.allocationRate * 100).toFixed(2) }}%</template><template #allocated="{ row }">{{ money(row.allocatedAmount) }}</template></DataTable></article></div>
+    </template>
+
+    <AppDialog class="admin-density-dialog" v-model="editorOpen" :title="target ? '调整已审核费用' : '新增柜次费用'" confirm-text="保存" :confirm-loading="saving" @confirm="save">
+      <div v-if="target" class="adjust-snapshot">
+        <p>调整仅允许修改业务日期和金额；如需变更方向、费用项目、供应商或其他信息，请先作废后新增。</p>
+        <el-descriptions :column="3" border size="small">
+          <el-descriptions-item label="方向">{{ target.direction === 'RECEIVABLE' ? '应收' : '应付' }}</el-descriptions-item>
+          <el-descriptions-item label="费用项目">{{ target.feeItemName }}</el-descriptions-item>
+          <el-descriptions-item label="供应商">{{ target.supplierName || '—' }}</el-descriptions-item>
+          <el-descriptions-item label="结算方式">{{ settlementLabel(target) }}</el-descriptions-item>
+          <el-descriptions-item label="已付摘要">{{ paidSummary(target) }}</el-descriptions-item>
+          <el-descriptions-item label="币种">{{ target.currency }}</el-descriptions-item>
+          <el-descriptions-item label="备注">{{ target.remark || '—' }}</el-descriptions-item>
+          <el-descriptions-item label="费用归属">{{ target.allocationOrderNo || '—' }} / {{ target.allocationInboundCode || '无入仓码' }}</el-descriptions-item>
+        </el-descriptions>
+      </div>
+      <template v-else>
+        <el-alert v-if="!canViewSuppliers" type="warning" :closable="false" show-icon title="当前账号缺少供应商查看权限，仅可维护应收费用" />
+        <el-alert v-else-if="suppliersError" type="warning" :closable="false" show-icon :title="suppliersError.message" />
+        <el-alert v-if="feeItemsError" type="warning" :closable="false" show-icon :title="feeItemsError.message" />
+      </template>
+      <el-form ref="formRef" :model="form" :rules="rules" label-position="top" class="fee-form density-form">
+        <template v-if="!target">
+          <el-form-item label="方向" prop="direction"><el-segmented v-model="form.direction" :options="[{ label: '应收', value: 'RECEIVABLE' }, { label: '应付', value: 'PAYABLE', disabled: !canViewSuppliers }]" /></el-form-item>
+          <el-form-item label="费用项目" prop="feeItemId"><el-select v-model="form.feeItemId" filterable :loading="feeItemsLoading" :disabled="!canViewFeeItems" placeholder="请选择启用且适用的费用项目"><el-option v-for="item in applicableItems" :key="item.id" :label="item.name" :value="item.id" /></el-select></el-form-item>
+          <el-form-item v-if="form.direction === 'PAYABLE'" label="供应商" required><el-select v-model="form.supplierId" filterable :loading="suppliersLoading" :disabled="!canViewSuppliers || !selectedFeeItem || !!suppliersError" placeholder="请先选择费用项目"><el-option v-for="supplier in suppliers" :key="supplier.id" :label="supplier.supplierName" :value="supplier.id" /></el-select></el-form-item>
+          <el-form-item v-if="form.direction === 'PAYABLE'" label="结算方式" required><el-radio-group v-model="settlementModeModel"><el-radio-button value="ON_ACCOUNT">账期应付</el-radio-button><el-radio-button value="DIRECT_PAID">已付成本</el-radio-button></el-radio-group></el-form-item>
+          <template v-if="form.direction === 'PAYABLE' && form.settlementMode === 'DIRECT_PAID'">
+            <el-form-item label="已付时间" required><el-date-picker v-model="form.paidAt" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" placeholder="请选择实际付款时间" /></el-form-item>
+            <el-form-item label="付款方式" required><el-select v-model="form.paymentMethod" placeholder="请选择付款方式"><el-option label="线上支付" value="ONLINE" /><el-option label="银行转账" value="BANK_TRANSFER" /><el-option label="现金" value="CASH" /><el-option label="其他" value="OTHER" /></el-select></el-form-item>
+            <el-form-item label="付款流水号"><el-input v-model="form.paymentReferenceNo" maxlength="128" placeholder="流水号与付款凭证至少填写一项" /></el-form-item>
+            <el-form-item label="付款凭证" class="voucher-field"><div class="voucher-control"><label class="voucher-picker" :class="{ 'is-disabled': voucherUploading }"><FileUp :size="15" /><span>{{ voucherUploading ? '上传并校验中' : '选择凭证' }}</span><input type="file" accept=".pdf,.jpg,.jpeg,.png,application/pdf,image/jpeg,image/png" :disabled="voucherUploading" @change="selectVoucher" /></label><span class="voucher-hint">FINANCE_VOUCHER · 最多 20 个</span></div><el-alert v-if="voucherError" type="error" :closable="true" show-icon @close="voucherError = null"><template #title>{{ voucherError.message }}</template><ApiErrorMeta :details="voucherError" /></el-alert><div v-if="voucherFiles.length" class="voucher-list"><span v-for="file in voucherFiles" :key="file.fileId"><span :title="file.fileName">{{ file.fileName }}</span><button type="button" :aria-label="`移除${file.fileName}`" @click="removeVoucher(file.fileId)"><X :size="14" /></button></span></div></el-form-item>
+          </template>
+        </template>
+        <el-form-item label="业务日期" prop="businessDate"><el-date-picker v-model="form.businessDate" type="date" value-format="YYYY-MM-DD" /></el-form-item>
+        <el-form-item label="金额(CNY)" prop="amount"><el-input-number v-model="form.amount" :min="0" :precision="2" controls-position="right" placeholder="请输入金额" /></el-form-item>
+        <el-form-item v-if="allocationMode" label="业务归属分摊" class="allocation-editor" required>
+          <el-alert type="info" :closable="false" show-icon title="客户必须明确；入仓码没有时按订单归属，分摊合计必须等于费用总额。" />
+          <div class="allocation-editor__rows">
+            <div v-for="(row, index) in allocationDraft" :key="`${row.customerId}-${row.orderId}-${row.inboundId || 'none'}`" class="allocation-editor__row">
+              <span><strong>{{ customerLabel(row.customerId || targetGroupRows[index]?.customerId || '') }}</strong><small>{{ row.orderNo }} · {{ row.inboundCode || '无入仓码' }}</small></span>
+              <el-input-number v-model="row.amount" :min="0" :precision="2" controls-position="right" placeholder="请输入分摊金额" />
+            </div>
+          </div>
+          <p class="allocation-editor__sum" :class="{ 'is-error': Math.abs(allocationSum - form.amount) > 0.001 }">已分摊 ¥{{ money(allocationSum) }} / 总额 ¥{{ money(form.amount) }}</p>
+        </el-form-item>
+        <template v-if="!target">
+          <el-form-item label="备注"><el-input v-model="form.remark" type="textarea" :rows="3" maxlength="500" show-word-limit placeholder="请输入备注（选填）" /></el-form-item>
+        </template>
+      </el-form>
+      <LoadErrorState v-if="editorError" compact title="费用保存失败" :message="editorError.message" :show-retry="false"><template #details><ApiErrorMeta :details="editorError" /></template></LoadErrorState>
+    </AppDialog>
+    <AppDialog class="admin-density-dialog" v-model="rejectOpen" title="驳回柜次费用" confirm-text="确认驳回" :confirm-loading="saving" @confirm="reject"><el-input v-model="rejection" type="textarea" :rows="4" maxlength="500" show-word-limit placeholder="请输入驳回原因" /></AppDialog>
+  </section>
+</template>
+
+<style scoped>
+.fees-panel { min-width: 0; overflow: hidden; padding-top: 0; border-top: 0; }
+.fees-header, .allocation-section > header { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-5); padding: 0 0 var(--admin-space-5); }
+.fees-header h2, .allocation-section h3 { margin: 0; font-size: var(--admin-font-section); }.fees-header p, .allocation-section p { margin: var(--admin-space-1) 0 0; color: var(--cc-muted); font-size: var(--admin-font-caption); }
+.fees-header__actions, .customer-context { display: flex; align-items: center; gap: var(--admin-space-4); }
+.customer-context > span { color: var(--cc-muted); font-size: var(--admin-font-body); white-space: nowrap; }.customer-context :deep(.el-select) { width: 260px; }
+.fees-table-title { display: flex; align-items: baseline; gap: var(--admin-space-3); }.fees-table-title strong { font-size: var(--admin-font-section); }.fees-table-title span { color: var(--cc-muted); font-size: var(--admin-font-caption); }
+.row-actions { flex-wrap: wrap; }.allocation-section { padding-top: var(--admin-space-5); border-top: 1px solid var(--cc-border); }.cost-block { border-top: 1px solid var(--cc-border); }.cost-summary { display: flex; flex-wrap: wrap; gap: var(--admin-space-4) var(--admin-space-6); padding: var(--admin-space-4) var(--admin-space-5); background: #f8fafc; font-size: var(--admin-font-body); }.cost-summary span { color: var(--cc-muted); }.fee-form { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 0 var(--admin-space-5); margin-top: var(--admin-space-5); }.fee-form :deep(.el-form-item:last-child) { grid-column: 1 / -1; }
+.voucher-field { grid-column: 1 / -1; }.voucher-control { display: flex; align-items: center; flex-wrap: wrap; gap: var(--admin-space-4); width: 100%; }.voucher-picker { display: inline-flex; align-items: center; gap: var(--admin-space-2); padding: 7px var(--admin-space-5); border: 1px solid var(--cc-border); border-radius: var(--admin-radius); color: var(--el-color-primary); cursor: pointer; }.voucher-picker.is-disabled { cursor: not-allowed; opacity: .6; }.voucher-picker input { position: absolute; width: 1px; height: 1px; opacity: 0; }.voucher-hint { color: var(--cc-muted); font-size: var(--admin-font-caption); }.voucher-list { display: grid; width: 100%; gap: var(--admin-space-2); margin-top: var(--admin-space-3); }.voucher-list > span { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-3); padding: var(--admin-space-2) 9px; border-radius: 5px; background: var(--el-fill-color-light); }.voucher-list > span > span { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }.voucher-list button { display: inline-flex; padding: 2px; border: 0; background: transparent; color: var(--el-color-danger); cursor: pointer; }
+.adjust-snapshot p { margin: 0 0 var(--admin-space-5); color: var(--cc-muted); font-size: var(--admin-font-body); line-height: 1.5; }
+.business-reference { display: grid; gap: 2px; }.business-reference small { color: var(--cc-muted); }
+.allocation-editor { grid-column: 1 / -1; }.allocation-editor :deep(.el-form-item__content) { display: block; }
+.allocation-editor__rows { display: grid; gap: var(--admin-space-3); margin-top: var(--admin-space-4); }.allocation-editor__row { display: grid; grid-template-columns: minmax(0, 1fr) 160px; align-items: center; gap: var(--admin-space-5); padding: var(--admin-space-3) var(--admin-space-4); border: 1px solid var(--cc-border); border-radius: var(--admin-radius); }.allocation-editor__row > span { display: grid; min-width: 0; }.allocation-editor__row small { overflow: hidden; color: var(--cc-muted); text-overflow: ellipsis; white-space: nowrap; }.allocation-editor__sum { margin: var(--admin-space-3) 0 0; text-align: right; color: var(--el-color-success); }.allocation-editor__sum.is-error { color: var(--el-color-danger); }
+@media (max-width: 640px) { .fees-header { align-items: stretch; flex-direction: column; }.fees-header .el-button { width: 100%; }.fee-form { grid-template-columns: 1fr; }.fee-form :deep(.el-form-item:last-child) { grid-column: auto; }.customer-context { align-items: stretch; flex-direction: column; } }
+</style>
diff --git a/src/modules/loading-lists/components/LoadingListDetailDrawer.vue b/src/modules/loading-lists/components/LoadingListDetailDrawer.vue
new file mode 100644
index 00000000..00c9f868
--- /dev/null
+++ b/src/modules/loading-lists/components/LoadingListDetailDrawer.vue
@@ -0,0 +1,295 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed } from 'vue'
+import { ArrowLeft, Check, Pencil } from '@lucide/vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import DetailPageLayout from '@/shared/components/DetailPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import PalletLabelPrintDialog from './PalletLabelPrintDialog.vue'
+import { loadingListStatusLabel } from '../status'
+import type { ApiErrorDetails } from '@/shared/api/http'
+import type { LoadingDetail, LoadingHistory, LoadingItem, LoadingListMode, LoadingListSummary, PreloadSummary } from '../api/platformLoadingLists'
+
+const props = defineProps<{
+  mode: LoadingListMode
+  loading: boolean
+  detail: LoadingDetail | null
+  error: ApiErrorDetails | null
+  canEdit: boolean
+  dense?: boolean
+  embedded?: boolean
+  canEditTransport?: boolean
+  transportNote?: string
+  confirmSaving?: boolean
+}>()
+
+const emit = defineEmits<{ back: []; retry: []; edit: []; editRemarks: [item: LoadingItem]; confirmPreload: [] }>()
+
+const actionColumn: DataTableColumn = { key: 'actions', label: '操作', fixed: 'left', width: 132, slotName: 'actions', hideable: false, movable: false }
+const baseItemColumns: DataTableColumn[] = [
+  { key: 'sequence', prop: 'loadSequence', label: '装柜顺序', width: 92 },
+  { key: 'inboundCode', prop: 'inboundCode', label: '入仓码', minWidth: 170, className: 'identifier-column', showOverflowTooltip: true },
+  { key: 'palletNo', prop: 'palletNo', label: '托盘号', minWidth: 155, className: 'identifier-column', showOverflowTooltip: true },
+  { key: 'unitType', label: '装柜单位', width: 110, slotName: 'unitType' },
+  { key: 'orderNo', prop: 'orderNo', label: '订单号', minWidth: 210, className: 'identifier-column', showOverflowTooltip: true },
+  { key: 'containerNo', prop: 'containerNo', label: '集装箱号', minWidth: 165, className: 'identifier-column', showOverflowTooltip: true, formatter: (row: LoadingItem) => row.containerNo || '待补录' },
+  { key: 'skuCode', prop: 'skuCode', label: 'SKU', minWidth: 220, className: 'identifier-column', showOverflowTooltip: true },
+  { key: 'destinationWarehouse', prop: 'destinationWarehouse', label: '目的仓', minWidth: 150, className: 'identifier-column', showOverflowTooltip: true },
+  { key: 'customerName', prop: 'customerName', label: '客户', minWidth: 220 },
+  { key: 'taxRefundFlag', label: '是否退税', width: 96, align: 'center', slotName: 'taxRefundFlag' },
+  { key: 'chineseName', prop: 'chineseName', label: '中文品名', minWidth: 160 },
+  { key: 'englishName', prop: 'englishName', label: '英文品名', minWidth: 170 },
+  { key: 'netWeightKg', label: '净重(kg)', width: 110, align: 'right', slotName: 'netWeight' },
+  { key: 'packageCount', prop: 'packageCount', label: '箱数', width: 86, align: 'right' },
+  { key: 'palletCount', prop: 'palletCount', label: '托盘数', width: 86, align: 'right' },
+  { key: 'volumeCbm', label: '体积(m³)', width: 110, align: 'right', slotName: 'volume' },
+  { key: 'grossWeightKg', label: '毛重(kg)', width: 110, align: 'right', slotName: 'grossWeight' },
+  { key: 'dimensionalWeightKg', label: '材积重(kg)', width: 115, align: 'right', slotName: 'dimensionalWeight' },
+  { key: 'productQuantity', prop: 'productQuantity', label: '产品数', width: 96, align: 'right' },
+  { key: 'unitsPerPackage', prop: 'unitsPerPackage', label: '每箱产品数', width: 110, align: 'right' },
+  { key: 'fbaTrackingNo', prop: 'fbaTrackingNo', label: 'FBA 追踪编码', minWidth: 155 },
+  { key: 'shipmentNo', prop: 'shipmentNo', label: '货件号', minWidth: 140 },
+  { key: 'shippingMark', prop: 'shippingMark', label: '唛头', minWidth: 130 },
+  { key: 'customerRemark', prop: 'customerRemark', label: '备注（客户）', minWidth: 190, slotName: 'customerRemark' },
+  { key: 'internalRemark', prop: 'internalRemark', label: '备注（内部）', minWidth: 190, slotName: 'internalRemark' },
+  { key: 'warehouseRemark', prop: 'warehouseRemark', label: '备注（仓库）', minWidth: 210, slotName: 'warehouseRemark' },
+  { key: 'customerServiceRemark', prop: 'customerServiceRemark', label: '备注（客服）', minWidth: 210, slotName: 'customerServiceRemark' },
+  { key: 'frozenAt', label: '冻结时间', minWidth: 150, slotName: 'frozenAt' },
+]
+
+const summary = computed<LoadingListSummary | null>(() => props.detail?.summary || null)
+const preloadSummary = computed(() => props.mode === 'preload' ? summary.value as PreloadSummary | null : null)
+const canEditItemRemark = computed(() => props.mode === 'preload' && props.canEdit && ['EDITING', 'LOADING'].includes(summary.value?.status || ''))
+const itemColumns = computed(() => canEditItemRemark.value ? [actionColumn, ...baseItemColumns] : baseItemColumns)
+const volatileSnapshotFields = new Set(['requestHash', 'version', 'updatedAt', 'operatorId', 'operatorName', 'occurredAt'])
+
+function stableSnapshotValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(stableSnapshotValue)
+  if (!value || typeof value !== 'object') return value
+  return Object.fromEntries(Object.entries(value as Record<string, unknown>)
+    .filter(([key]) => !volatileSnapshotFields.has(key))
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([key, nested]) => [key, stableSnapshotValue(nested)]))
+}
+
+function normalizedSnapshot(value: string | null) {
+  if (!value) return null
+  try { return stableSnapshotValue(JSON.parse(value) as unknown) } catch { return value }
+}
+
+function isPureStatusNoop(history: LoadingHistory) {
+  return history.actionType === 'STATUS_UPDATE'
+    && history.fromStatus === history.toStatus
+    && JSON.stringify(normalizedSnapshot(history.beforeSnapshot)) === JSON.stringify(normalizedSnapshot(history.afterSnapshot))
+}
+
+function historyEventKey(history: LoadingHistory) {
+  if (history.operationId) return `operation:${history.operationId}`
+  return history.historyId ? `history:${history.historyId}` : null
+}
+
+const visibleHistories = computed(() => {
+  const seen = new Set<string>()
+  return (props.detail?.histories || []).filter((history) => {
+    if (isPureStatusNoop(history)) return false
+    const eventKey = historyEventKey(history)
+    if (!eventKey) return true
+    if (seen.has(eventKey)) return false
+    seen.add(eventKey)
+    return true
+  })
+})
+const blockingReasonLabels: Record<string, string> = {
+  LOADING_PLAN_NOT_EDITING: '装柜计划已不在可确认的编辑状态',
+  PRELOAD_LINK_MISSING: '装柜明细尚未完整关联入库预装票据',
+  CONTAINER_NO_MISSING: '尚未录入真实集装箱号，请先补录后再确认预装',
+  OCEAN_BOOKING_NOT_LINKED: '尚未关联真实订舱',
+  OCEAN_BOOKING_NOT_RELEASED: '关联订舱尚未放舱',
+  PDA_TASK_ALREADY_CREATED: 'PDA 任务已创建，无需重复确认',
+  PRELOAD_ALREADY_CONFIRMED: '整份预装计划已经确认',
+}
+const confirmationStatusLabels: Record<string, string> = {
+  PENDING: '待确认', PARTIALLY_CONFIRMED: '部分票据已确认', CONFIRMED: '已确认',
+}
+const oceanBookingStatusLabels: Record<string, string> = {
+  CONFIRMED: '已确认', CHANGE_PENDING: '改船处理中', RELEASED: '已放舱', CANCELLED: '已取消',
+}
+const pdaTaskStatusLabels: Record<string, string> = {
+  PENDING: '待领取', CLAIMED: '已领取', LOADING: '作业中', AWAITING_REVIEW: '待人工复核', COMPLETED: '已完成',
+}
+const blockingReasonText = computed(() => (preloadSummary.value?.readiness.blockingReasons || [])
+  .map((reason) => blockingReasonLabels[reason] || '存在未满足的确认条件')
+  .join('；'))
+const title = computed(() => {
+  if (!summary.value) return props.mode === 'preload' ? '预装清单详情' : '装柜清单详情'
+  const number = props.mode === 'preload'
+    ? (summary.value as PreloadSummary).preloadNo
+    : 'loadingListNo' in summary.value ? summary.value.loadingListNo : ''
+  return `${props.mode === 'preload' ? '预装清单' : '装柜清单'} · ${number}`
+})
+
+function actionLabel(action: string) {
+  return ({
+    CREATE: '创建计划', ASSIGN: '分配货物', ADJUST: '调整货物', DELETE: '移除货物',
+    RECOMMEND: '智能排柜', PUSH_PRELOAD: '推送预装', UPDATE_TRANSPORT: '修改运输信息',
+    CONFIRM_PRELOAD: '确认预装',
+    START_LOADING: '开始拣货', COMPLETE: '完成装柜',
+  } as Record<string, string>)[action] || '状态更新'
+}
+
+function formatDateTime(value?: string | null) {
+  return value ? value.replace('T', ' ').slice(0, 16) : '—'
+}
+
+function formatNumber(value?: number | null, digits = 3) {
+  if (value === null || value === undefined || !Number.isFinite(Number(value))) return '—'
+  return Number(value).toLocaleString('zh-CN', { maximumFractionDigits: digits })
+}
+</script>
+
+<template>
+  <section v-loading="loading" class="loading-detail-content" :class="{ 'admin-density loading-density': mode === 'preload' || dense }" :aria-label="title" :aria-busy="loading">
+    <section class="detail-overview" aria-label="清单概览">
+      <header class="detail-page-header" :class="{ 'detail-page-header--embedded': embedded }">
+        <el-button link type="primary" class="detail-page-header__back" :class="{ 'density-back': mode === 'preload' || dense }" @click="emit('back')"><ArrowLeft :size="16" />返回列表</el-button>
+        <div v-if="!embedded" class="detail-page-header__identity">
+          <h1>{{ title }}</h1>
+          <p>{{ mode === 'preload' ? '核对运输信息、确认预装并维护逐条仓库备注' : '查看已完成装柜明细和柜次费用' }}</p>
+        </div>
+        <div v-if="detail && summary" class="detail-page-header__actions">
+          <PalletLabelPrintDialog :dense="mode === 'preload' || dense" v-if="summary.warehouseId" :plan-id="summary.planId" :warehouse-id="summary.warehouseId" :disabled="!summary.containerNo || summary.status === 'EDITING'" />
+          <template v-if="canEditItemRemark">
+            <el-button v-if="canEditTransport" @click="emit('edit')"><Pencil :size="16" />{{ summary.containerNo ? '纠正集装箱号 / 航次' : '补录集装箱号 / 航次' }}</el-button>
+            <el-button type="primary" :loading="confirmSaving" :disabled="!preloadSummary?.readiness.canConfirm" @click="emit('confirmPreload')"><Check :size="16" />确认预装</el-button>
+          </template>
+        </div>
+      </header>
+      <section v-if="detail && summary" class="detail-summary" aria-label="清单基本信息">
+        <div><span>柜次号</span><strong>{{ summary.cabinetNo || '—' }}</strong></div>
+        <div><span>集装箱号</span><strong>{{ summary.containerNo || '待补录' }}</strong></div>
+        <div><span>仓库</span><strong>{{ summary.warehouseName || '—' }}</strong></div>
+        <div><span>状态</span><StatusBadge :status="loadingListStatusLabel(summary.status)" /></div>
+        <template v-if="preloadSummary">
+          <div><span>船名 / 航次</span><strong>{{ preloadSummary.vesselName || '—' }} / {{ preloadSummary.voyageNo || '—' }}</strong></div>
+          <div><span>箱型</span><strong>{{ preloadSummary.containerType || '—' }}</strong></div>
+          <div><span>预装确认</span><StatusBadge :status="confirmationStatusLabels[preloadSummary.readiness.confirmationStatus] || '未知状态'" /></div>
+          <div><span>订舱状态</span><strong>{{ preloadSummary.readiness.oceanBookingStatus ? (oceanBookingStatusLabels[preloadSummary.readiness.oceanBookingStatus] || '未知状态') : '未关联' }}</strong></div>
+          <div><span>PDA 状态</span><strong>{{ preloadSummary.readiness.pdaTaskStatus ? (pdaTaskStatusLabels[preloadSummary.readiness.pdaTaskStatus] || '未知状态') : (preloadSummary.readiness.readyForPda ? '可下发' : '未就绪') }}</strong></div>
+          <div class="detail-summary__wide"><span>客户</span><strong>{{ preloadSummary.customers.map((item) => item.customerName || '客户信息缺失').join('、') || '客户信息缺失' }}</strong></div>
+        </template>
+        <div><span>创建时间</span><strong>{{ formatDateTime(summary.createdAt) }}</strong></div>
+      </section>
+    </section>
+    <LoadErrorState v-if="error" title="清单详情加载失败" :message="error.message" @retry="emit('retry')">
+      <template #details><ApiErrorMeta :details="error" /></template>
+    </LoadErrorState>
+
+    <div v-else-if="detail && summary" class="detail-layout">
+      <DetailPageLayout :ariaLabel="title">
+      <div v-if="preloadSummary && preloadSummary.readiness.confirmationStatus !== 'CONFIRMED' && !preloadSummary.readiness.canConfirm" class="readiness-note" role="status">
+        <strong>暂不能确认预装：</strong>
+        <span>{{ blockingReasonText || '请刷新详情获取最新确认条件' }}</span>
+      </div>
+      <div v-if="preloadSummary" class="readiness-note transport-note" role="status"><strong>真实集装箱号：</strong><span>{{ transportNote }}</span></div>
+
+      <section class="detail-section">
+        <DataTable
+          :data="detail.items"
+          :columns="itemColumns"
+          stripe
+          preference-key="loading-list-detail-items"
+          row-key="itemId"
+          empty-text="暂无装柜货物明细"
+          aria-label="装柜货物明细"
+        >
+          <template #toolbar-start><div class="detail-section__heading"><div><h2>装柜货物明细 <span>{{ detail.items.length }} 条</span></h2><p>仓库备注将随装柜完成资料下发海外仓</p></div></div></template>
+          <template #actions="{ row }">
+            <el-button :class="{ 'density-action': mode === 'preload' || dense }" size="small" :type="mode === 'preload' ? undefined : 'primary'" :plain="mode !== 'preload'" :aria-label="`编辑 ${row.inboundCode || row.orderNo} 的备注`" @click="emit('editRemarks', row as LoadingItem)"><Pencil v-if="mode !== 'preload'" :size="14" />编辑备注</el-button>
+          </template>
+          <template #unitType="{ row }"><el-tag size="small" :type="row.unitType === 'SEALED_PALLET' ? 'success' : 'info'">{{ row.unitType === 'SEALED_PALLET' ? '封托托盘' : '箱件' }}</el-tag><small v-if="row.indivisible">整托不可拆</small></template>
+          <template #grossWeight="{ row }">{{ formatNumber(row.grossWeightKg) }}</template>
+          <template #netWeight="{ row }">{{ formatNumber(row.netWeightKg) }}</template>
+          <template #taxRefundFlag="{ row }">{{ row.taxRefundFlag === true ? '是' : row.taxRefundFlag === false ? '否' : '—' }}</template>
+          <template #volume="{ row }">{{ formatNumber(row.volumeCbm) }}</template>
+          <template #dimensionalWeight="{ row }">{{ formatNumber(row.dimensionalWeightKg) }}</template>
+          <template #customerRemark="{ row }"><div class="remark-cell"><span>{{ row.customerRemark || '—' }}</span><small>来源：客户下单</small></div></template>
+          <template #internalRemark="{ row }"><div class="remark-cell"><span>{{ row.internalRemark || '—' }}</span><small>来源：订单内部备注</small></div></template>
+          <template #warehouseRemark="{ row }"><div class="remark-cell"><span>{{ row.warehouseRemark || '—' }}</span><small>{{ mode === 'preload' ? '由仓库维护' : '装柜完成时冻结' }}</small></div></template>
+          <template #customerServiceRemark="{ row }"><div class="remark-cell"><span>{{ row.customerServiceRemark || '—' }}</span><small>{{ mode === 'preload' ? '由客服维护' : '装柜完成时冻结' }}</small></div></template>
+          <template #frozenAt="{ row }">{{ formatDateTime(row.frozenAt) }}</template>
+        </DataTable>
+      </section>
+
+      <section class="history-section" aria-label="操作历史">
+        <header><h2>操作历史</h2><span>{{ visibleHistories.length }} 条</span></header>
+        <el-table :data="visibleHistories" border stripe empty-text="暂无操作历史" aria-label="清单操作历史">
+          <el-table-column label="时间" width="170"><template #default="{ row }">{{ formatDateTime(row.occurredAt) }}</template></el-table-column>
+          <el-table-column label="事件" width="140"><template #default="{ row }">{{ actionLabel(row.actionType) }}</template></el-table-column>
+          <el-table-column label="状态变化" min-width="200"><template #default="{ row }"><span v-if="row.fromStatus || row.toStatus">{{ loadingListStatusLabel(row.fromStatus) }} → {{ loadingListStatusLabel(row.toStatus) }}</span><span v-else>—</span></template></el-table-column>
+          <el-table-column label="操作人" min-width="160"><template #default="{ row }">{{ row.operatorName || '操作人信息缺失' }}</template></el-table-column>
+          <el-table-column label="原因 / 备注" min-width="240"><template #default="{ row }">{{ row.operationReason || '—' }}</template></el-table-column>
+        </el-table>
+      </section>
+      </DetailPageLayout>
+    </div>
+  </section>
+</template>
+
+<style scoped>
+.loading-detail-content { display: grid; min-width: 0; gap: var(--admin-space-6, 16px); padding: var(--admin-space-6, 16px); border: 1px solid var(--cc-border); border-radius: 8px; background: var(--admin-surface, #fff); }
+.detail-layout { display: grid; min-width: 0; }
+.detail-overview { min-width: 0; }
+.detail-page-header { display: grid; grid-template-columns: auto minmax(0, 1fr) auto; align-items: center; gap: var(--admin-space-6, 16px); padding: var(--admin-space-3, 8px) 0 var(--admin-space-5, 12px); }
+.detail-page-header--embedded { grid-template-columns: minmax(0, 1fr) auto; padding-top: 0; }
+.detail-page-header__back { margin-right: 2px; }
+.detail-page-header__identity { min-width: 0; }
+.detail-page-header__identity h1 { margin: 0; color: var(--cc-text); font-size: 18px; line-height: 1.35; }
+.detail-page-header__identity p { margin: 3px 0 0; color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); }
+.detail-page-header__actions { display: flex; align-items: center; justify-content: flex-end; gap: var(--admin-space-3, 8px); }
+.detail-page-header__actions :deep(.el-button + .el-button) { margin-left: 0; }
+.detail-summary { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: var(--admin-space-2, 6px) 28px; padding: var(--admin-space-4, 10px) 0 2px; border-top: 1px solid var(--cc-border); }
+.detail-summary > div { display: flex; min-width: 0; min-height: 26px; align-items: center; gap: var(--admin-space-2, 6px); }
+.detail-summary > div > span:first-child { flex: 0 0 auto; color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); white-space: nowrap; }
+.detail-summary > div > span:first-child::after { content: "："; }
+.detail-summary strong { min-width: 0; color: var(--cc-text); font-size: var(--admin-font-body, 13px); overflow-wrap: anywhere; }
+.detail-summary :deep(.status-badge) { width: fit-content; }
+.detail-summary small { color: var(--cc-muted); font-size: var(--admin-font-caption, 11px); }
+.detail-summary__wide { grid-column: auto; }
+.detail-layout :deep(.detail-page-layout__content) { display: grid; min-width: 0; gap: 20px; }
+.readiness-note { display: flex; min-width: 0; align-items: center; padding: 2px var(--admin-space-1, 4px); color: var(--cc-text); font-size: var(--admin-font-caption, 12px); }
+.readiness-note strong { flex: 0 0 auto; color: var(--el-color-warning-dark-2); }
+.readiness-note span { min-width: 0; color: var(--cc-muted); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.detail-section, .history-section { min-width: 0; overflow: hidden; padding: var(--admin-space-6, 16px) 0 0; border-top: 1px solid var(--cc-border); }
+.detail-section__heading h2 { margin: 0; font-size: 15px; }
+.detail-section__heading h2 span { margin-left: var(--admin-space-2, 6px); color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); font-weight: 400; }
+.detail-section__heading p { margin: 2px 0 0; color: var(--cc-muted); font-size: var(--admin-font-caption, 11px); line-height: 1.35; }
+.detail-section :deep(.el-table) { width: 100%; }
+.detail-section :deep(.el-table th.el-table__cell) { padding: 7px 0; }
+.detail-section :deep(.el-table td.el-table__cell) { padding: var(--admin-space-2, 6px) 0; }
+.detail-section :deep(.identifier-column .cell) { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.detail-section small { display: block; margin-top: 3px; color: var(--cc-muted); }
+.remark-cell { min-width: 0; line-height: 1.45; overflow-wrap: anywhere; }
+.history-section header { display: flex; align-items: baseline; gap: var(--admin-space-4, 10px); margin-bottom: 18px; }
+.history-section h2 { margin: 0; font-size: var(--admin-font-title, 16px); }
+.history-section header span { color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); }
+.loading-density { gap: var(--admin-space-5, 12px); padding: var(--admin-space-5, 12px); border-radius: var(--admin-radius, 4px); }
+.loading-density .detail-page-header { gap: var(--admin-space-5, 12px); padding: 0 0 var(--admin-space-3, 8px); }
+.loading-density .detail-page-header__identity h1 { font-size: var(--admin-font-title, 16px); overflow-wrap: anywhere; }
+.loading-density .detail-page-header__actions { flex-wrap: wrap; }
+.loading-density .detail-summary { gap: 0; padding: 0; border-left: 1px solid var(--cc-border); }
+.loading-density .detail-summary > div { gap: 0; align-items: stretch; min-height: var(--admin-row-height, 36px); border-bottom: 1px solid var(--cc-border); border-right: 1px solid var(--cc-border); }
+.loading-density .detail-summary > div > span:first-child { display: flex; align-items: center; flex: 0 0 96px; padding: var(--admin-space-2, 6px) var(--admin-space-3, 8px); background: var(--admin-label-bg, #f8fafc); }
+.loading-density .detail-summary > div > span:first-child::after { content: none; }
+.loading-density .detail-summary strong, .loading-density .detail-summary :deep(.status-badge) { align-self: center; margin: var(--admin-space-2, 6px) var(--admin-space-3, 8px); font-weight: 400; }
+.loading-density .detail-summary__wide { grid-column: span 2; }
+.loading-density .detail-layout :deep(.detail-page-layout__content) { gap: var(--admin-space-5, 12px); }
+.loading-density .detail-section, .loading-density .history-section { padding-top: var(--admin-space-3, 8px); }
+.loading-density .detail-section__heading h2, .loading-density .history-section h2 { font-size: var(--admin-font-section, 14px); }
+.loading-density .history-section header { margin-bottom: var(--admin-space-3, 8px); }
+.loading-density .detail-section__heading p, .loading-density small { font-size: var(--admin-font-caption, 12px); }
+.loading-density .readiness-note { align-items: baseline; }
+.loading-density .readiness-note span { white-space: normal; overflow: visible; overflow-wrap: anywhere; }
+@media (max-width: 720px) { .loading-density .detail-summary { grid-template-columns: 1fr; } .loading-density .detail-summary__wide { grid-column: auto; } }
+</style>
diff --git a/src/modules/loading-lists/components/LoadingListsView.creation.test.ts b/src/modules/loading-lists/components/LoadingListsView.creation.test.ts
new file mode 100644
index 00000000..29691556
--- /dev/null
+++ b/src/modules/loading-lists/components/LoadingListsView.creation.test.ts
@@ -0,0 +1,65 @@
+import ElementPlus from 'element-plus'
+import { createPinia, setActivePinia } from 'pinia'
+import { createMemoryHistory, createRouter } from 'vue-router'
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import LoadingListsView from './LoadingListsView.vue'
+import { ContainerSimulationCreate } from '@/modules/container-loading'
+import { listPreloadPlans } from '../api/platformLoadingLists'
+
+const accessCan = vi.hoisted(() => vi.fn())
+vi.mock('@/core/access/accessPreview', () => ({ useAccessPreviewStore: () => ({ can: accessCan }) }))
+vi.mock('@/modules/iam', () => ({ listPlatformTenants: vi.fn().mockResolvedValue({ records: [] }) }))
+vi.mock('@/modules/container-loading', () => ({ ContainerSimulationCreate: { emits: ['created'], template: '<button @click="$emit(\'created\')">新增模拟柜</button>' } }))
+vi.mock('../api/platformLoadingLists', () => ({
+  listPreloadPlans: vi.fn().mockResolvedValue({ records: [], total: 0 }),
+  listConfirmedLoadingLists: vi.fn().mockResolvedValue({ records: [], total: 0 }),
+}))
+
+async function mountList(mode: 'preload' | 'confirmed' = 'preload') {
+  const router = createRouter({ history: createMemoryHistory(), routes: [{ path: '/', component: { template: '<div />' } }] })
+  await router.push('/')
+  await router.isReady()
+  const wrapper = mount(LoadingListsView, { props: { mode }, global: { plugins: [ElementPlus, router] } })
+  await flushPromises()
+  return wrapper
+}
+
+describe('preload simulation entry', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    setActivePinia(createPinia())
+    accessCan.mockReturnValue(true)
+  })
+
+  it('refreshes the first page without old filters after creation, staying on the list', async () => {
+    const wrapper = await mountList()
+    const state = wrapper.vm as unknown as { page: number; query: { customerId: string; keyword: string; createdRange: string[] } }
+    Object.assign(state.query, { customerId: '11', keyword: 'OLD', createdRange: ['2026-01-01', '2026-01-02'] })
+    state.page = 3
+    await flushPromises()
+    vi.mocked(listPreloadPlans).mockClear()
+    wrapper.findComponent(ContainerSimulationCreate).vm.$emit('created')
+    await flushPromises()
+    expect(listPreloadPlans).toHaveBeenCalledTimes(1)
+    expect(listPreloadPlans).toHaveBeenLastCalledWith({ page: 1, size: 20, customerId: undefined, keyword: undefined, createdFrom: undefined, createdTo: undefined })
+    expect(wrapper.vm.$route.path).toBe('/')
+    wrapper.findComponent(ContainerSimulationCreate).vm.$emit('created')
+    await flushPromises()
+    expect(listPreloadPlans).toHaveBeenCalledTimes(2)
+    wrapper.unmount()
+  })
+
+  it('hides creation without container create permission', async () => {
+    accessCan.mockImplementation((code: string) => code !== 'platform:firstleg:container:create')
+    const wrapper = await mountList()
+    expect(wrapper.findComponent(ContainerSimulationCreate).exists()).toBe(false)
+    wrapper.unmount()
+  })
+
+  it('does not add creation to confirmed loading lists', async () => {
+    const wrapper = await mountList('confirmed')
+    expect(wrapper.findComponent(ContainerSimulationCreate).exists()).toBe(false)
+    wrapper.unmount()
+  })
+})
diff --git a/src/modules/loading-lists/components/LoadingListsView.test.ts b/src/modules/loading-lists/components/LoadingListsView.test.ts
new file mode 100644
index 00000000..7dff6f1d
--- /dev/null
+++ b/src/modules/loading-lists/components/LoadingListsView.test.ts
@@ -0,0 +1,260 @@
+import { describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/loading-lists/components/LoadingListsView.vue'), 'utf8')
+const detailSource = readFileSync(resolve(process.cwd(), 'src/modules/loading-lists/components/LoadingListDetailDrawer.vue'), 'utf8')
+const preloadDetailSource = readFileSync(resolve(process.cwd(), 'src/modules/loading-lists/pages/PreloadPlanDetailView.vue'), 'utf8')
+const confirmedDetailSource = readFileSync(resolve(process.cwd(), 'src/modules/loading-lists/pages/ConfirmedLoadingListDetailView.vue'), 'utf8')
+const routesSource = readFileSync(resolve(process.cwd(), 'src/modules/loading-lists/routes.ts'), 'utf8')
+
+describe('LoadingListsView', () => {
+  it('filters both list modes by an active name-only customer selector', () => {
+    expect(source).toContain("listPlatformTenants({ page: 1, size: 200, status: 'ACTIVE' })")
+    expect(source).toContain("label: customer.tenantName")
+    expect(source).toContain("customerId: String(query.customerId || '').trim() || undefined")
+    expect(source).not.toContain('customer.tenantCode')
+  })
+  it('keeps the operation column first and fixed left in both lists', () => {
+    const actionColumns = [...source.matchAll(/key: 'actions', label: '操作', fixed: 'left'/g)]
+    expect(actionColumns).toHaveLength(2)
+    expect(source.indexOf("key: 'actions'")).toBeLessThan(source.indexOf("key: 'preloadNo'"))
+    expect(source.indexOf("key: 'actions'", source.indexOf("key: 'actions'") + 1)).toBeLessThan(source.indexOf("key: 'loadingListNo'"))
+  })
+
+  it('queries all warehouses without exposing a warehouse selector', () => {
+    expect(source).not.toContain('listAllPlatformWarehouses')
+    expect(source).not.toContain("key: 'warehouseId'")
+    expect(source).not.toContain('loadingWarehouses')
+    expect(source).not.toContain('warehouseId: warehouseId || undefined')
+    expect(source).toContain('query: { warehouseId: String(row.warehouseId || \'\') }')
+    expect(source).not.toContain("ElMessage.warning('请先选择仓库')")
+    expect(source).not.toContain("'请先选择仓库后查询'")
+    expect(preloadDetailSource).toContain('MISSING_WAREHOUSE_CONTEXT')
+    expect(confirmedDetailSource).toContain('MISSING_WAREHOUSE_CONTEXT')
+  })
+
+  it('uses the shared query and table components while keeping details on route pages', () => {
+    expect(source).toContain('QueryToolbar')
+    expect(source).toContain('DataTable')
+    expect(source).toContain('LoadErrorState')
+    expect(source).toContain('ApiErrorMeta')
+    expect(preloadDetailSource).toContain('AppDialog')
+    expect(confirmedDetailSource).not.toContain('AppDialog')
+    expect(detailSource).not.toContain('AppDrawer')
+    expect(detailSource).not.toContain('ContainerFeesPanel')
+  })
+
+  it('distinguishes the generated cabinet reference from the physical container number', () => {
+    expect(source).toContain("label: '柜次号'")
+    expect(source).toContain("label: '集装箱号'")
+    expect(source).toContain('装柜清单号/柜次号/集装箱号')
+    expect(detailSource).toContain('<span>柜次号</span>')
+    expect(detailSource).toContain('<span>集装箱号</span>')
+    expect(source).not.toContain("label: '柜号'")
+    expect(detailSource).not.toContain('<span>柜号</span>')
+    expect(source).toContain("key: 'cabinetNo', prop: 'cabinetNo'")
+    expect(source).not.toContain('internalContainerNo')
+  })
+
+  it('keeps preload routes while completed lists move into domestic container detail', () => {
+    expect(source).toContain("name: 'preload-plan-detail'")
+    expect(source).toContain("name: 'loading-list-detail'")
+    expect(source).not.toContain('confirmed-inline-detail')
+    expect(preloadDetailSource).toContain('返回列表')
+    expect(preloadDetailSource).toContain('router.back()')
+    expect(confirmedDetailSource).toContain('返回列表')
+    expect(confirmedDetailSource).toContain('router.back()')
+    expect(confirmedDetailSource).toContain('@media (min-width: 1920px) { .confirmed-loading-detail-page { width: 100%; max-width: none; gap: 12px; } }')
+    expect(routesSource).not.toContain("path: 'loading-lists/:planId'")
+    expect(routesSource).not.toContain("name: 'loading-list-detail'")
+  })
+
+  it('keeps the real transport edit contract in a 620px centered modal on the detail page', () => {
+    expect(source).not.toContain('class="loading-transport-dialog"')
+    expect(preloadDetailSource).toContain('width="min(620px, calc(100vw - 28px))"')
+    expect(preloadDetailSource).not.toContain('备注信息（仅自己可见）')
+    expect(preloadDetailSource).not.toContain('备注信息（客户可见）')
+    expect(preloadDetailSource).not.toContain('备注信息（仓库可见）')
+  })
+
+  it('only exposes transport editing for LOADING preload details', () => {
+    expect(detailSource).toContain("props.mode === 'preload' && props.canEdit && ['EDITING', 'LOADING'].includes(summary.value?.status || '')")
+    expect(detailSource).toContain('const itemColumns = computed(() => canEditItemRemark.value ? [actionColumn, ...baseItemColumns] : baseItemColumns)')
+    expect(detailSource).not.toContain('报关资料')
+    expect(detailSource).not.toContain('完成报关')
+    expect(preloadDetailSource).toContain('expectedVersion: detail.value.summary.version')
+  })
+
+  it('renders business labels instead of raw loading-plan status codes', () => {
+    expect(source).toContain(':status="loadingListStatusLabel(row.status)"')
+    expect(detailSource).toContain(':status="loadingListStatusLabel(summary.status)"')
+    expect(detailSource).not.toContain(':status="summary.status"')
+    expect(source).not.toContain('仅装柜中允许修改')
+  })
+
+  it('keeps transport editing as a detail-page action', () => {
+    expect(source).not.toContain('openEditFromRow(row)')
+    expect(source).not.toContain('编辑运输信息')
+    expect(detailSource).toContain("summary.containerNo || '待补录'")
+    expect(detailSource).toContain('v-if="canEditTransport"')
+    expect(preloadDetailSource).toContain("isContainerCorrection.value ? '纠正集装箱号 / 航次' : '补录集装箱号 / 航次'")
+  })
+
+  it('refreshes the detail version on A0409 while preserving transport input', () => {
+    expect(preloadDetailSource).toContain("details.code === 'A0409'")
+    expect(preloadDetailSource).toContain('await loadDetail()')
+    expect(preloadDetailSource).toContain('当前输入已保留，请核对后重新保存')
+  })
+
+  it('opens a validated plan and warehouse deep link without mixing list modes', () => {
+    expect(source).toContain('useRoute()')
+    expect(source).toContain('route.query.planId')
+    expect(source).toContain('route.query.warehouseId')
+    expect(source).toContain("router.replace({ name: 'loading-list-detail'")
+    expect(confirmedDetailSource).toContain("result.summary.status !== 'COMPLETED'")
+    expect(confirmedDetailSource).toContain('MODE_STATUS_MISMATCH')
+    expect(confirmedDetailSource).toContain('watch([planId, warehouseId], () => void loadDetail())')
+    expect(confirmedDetailSource).toContain('if (sequence !== loadSequence) return')
+    expect(preloadDetailSource).toContain('watch([planId, warehouseId], () => void loadDetail())')
+  })
+
+  it('uses backend readiness for whole-plan confirmation and translates blocking reasons', () => {
+    expect(detailSource).toContain(':disabled="!preloadSummary?.readiness.canConfirm"')
+    expect(detailSource).toContain("OCEAN_BOOKING_NOT_RELEASED: '关联订舱尚未放舱'")
+    expect(detailSource).toContain("PRELOAD_ALREADY_CONFIRMED: '整份预装计划已经确认'")
+    expect(detailSource).toContain("confirmationStatus !== 'CONFIRMED' && !preloadSummary.readiness.canConfirm")
+    expect(detailSource).toContain('confirmationStatusLabels[preloadSummary.readiness.confirmationStatus]')
+    expect(detailSource).toContain("pdaTaskStatusLabels")
+    expect(preloadDetailSource).toContain('@confirm-preload="openConfirmPreload"')
+  })
+
+  it('passes translated status text directly to the badge', () => {
+    expect(source).toContain('<StatusBadge :status="loadingListStatusLabel(row.status)" />')
+    expect(source).not.toContain('<StatusBadge :status="row.status" />')
+    expect(detailSource).toContain('<StatusBadge :status="loadingListStatusLabel(summary.status)" />')
+  })
+
+  it('uses bordered list actions with a stable 320px layout', () => {
+    expect(source).toContain(":class=\"{ 'density-action': isPreload }\"")
+    expect(source).toContain(':type="isPreload ? undefined : \'primary\'" :plain="!isPreload"')
+    expect(source).not.toContain('<el-button v-if="canView" link')
+    expect(source).toContain("key: 'actions', label: '操作', fixed: 'left', width: 110")
+    expect(source).toContain('flex-wrap: wrap')
+    expect(source).toContain('@media (max-width: 720px)')
+    expect(source).toContain('.row-actions { gap: 4px; }')
+    expect(source).toMatch(/:loading="loading"\s+stripe/)
+    expect(detailSource).toMatch(/:columns="itemColumns"\s+stripe/)
+  })
+
+  it('shows every prototype detail field that is backed by the loading item contract', () => {
+    expect(detailSource.indexOf("key: 'actions'")).toBeLessThan(detailSource.indexOf("key: 'sequence'"))
+    expect(detailSource).toContain("key: 'actions', label: '操作', fixed: 'left'")
+    expect(detailSource.indexOf("key: 'orderNo'")).toBeLessThan(detailSource.indexOf("key: 'containerNo'"))
+    expect(detailSource.indexOf("key: 'containerNo'")).toBeLessThan(detailSource.indexOf("key: 'skuCode'"))
+    const fields = [
+      'taxRefundFlag',
+      'chineseName',
+      'englishName',
+      'netWeightKg',
+      'packageCount',
+      'palletCount',
+      'volumeCbm',
+      'grossWeightKg',
+      'dimensionalWeightKg',
+      'productQuantity',
+      'unitsPerPackage',
+      'fbaTrackingNo',
+      'shipmentNo',
+      'shippingMark',
+      'customerRemark',
+      'internalRemark',
+      'warehouseRemark',
+      'customerServiceRemark',
+    ]
+    let previous = detailSource.indexOf("key: 'customerName'")
+    for (const field of fields) {
+      const current = detailSource.indexOf(`key: '${field}'`, previous + 1)
+      expect(current, field).toBeGreaterThan(previous)
+      previous = current
+    }
+    expect(detailSource).not.toContain("key: 'goodsImageUrl'")
+    expect(detailSource).not.toContain("label: '退税资料'")
+  })
+
+  it('keeps customer remarks read-only while exposing three editable collaboration remarks', () => {
+    expect(detailSource).toContain('来源：客户下单')
+    expect(detailSource).toContain('来源：订单内部备注')
+    expect(detailSource).toContain('仓库备注将随装柜完成资料下发海外仓')
+    expect(detailSource).toContain("emit('editRemarks', row as LoadingItem)")
+    expect(detailSource).toContain("props.mode === 'preload' && props.canEdit && ['EDITING', 'LOADING'].includes(summary.value?.status || '')")
+    expect(detailSource).not.toContain("emit('editCustomerRemark'")
+    expect(detailSource).toContain("key: 'customerServiceRemark'")
+  })
+
+  it('uses one white detail surface, a readable four-column summary and dense item table', () => {
+    expect(detailSource).toContain('class="detail-overview"')
+    expect(detailSource).not.toContain('class="detail-overview surface-panel"')
+    expect(detailSource).toContain('class="detail-page-header"')
+    expect(detailSource).toContain("@click=\"emit('back')\"")
+    expect(detailSource).toContain('class="detail-page-header__actions"')
+    expect(detailSource).toContain('grid-template-columns: repeat(4, minmax(0, 1fr))')
+    expect(detailSource).toContain('min-height: 26px')
+    expect(detailSource).toContain('> div > span:first-child::after { content: "："; }')
+    expect(detailSource).not.toContain('> div > span::after { content: "："; }')
+    expect(detailSource).toContain('background: var(--admin-surface, #fff)')
+    expect(detailSource).toContain('overflow-wrap: anywhere')
+    expect(detailSource).toContain("className: 'identifier-column'")
+    expect(detailSource).toContain('showOverflowTooltip: true')
+    expect(detailSource).toContain('white-space: nowrap')
+    expect(detailSource).toContain('<template #toolbar-start>')
+    expect(detailSource).not.toContain('<span v-else aria-label="只读">—</span>')
+  })
+
+  it('merges the page header and summary while spacing independent business sections', () => {
+    expect(detailSource).toContain('<section v-if="detail && summary" class="detail-summary"')
+    expect(detailSource).not.toContain('class="detail-summary surface-panel"')
+    expect(detailSource).toContain('.detail-layout :deep(.detail-page-layout__content) { display: grid; min-width: 0; gap: 20px; }')
+    expect(detailSource).toContain('<section class="detail-section">')
+    expect(detailSource).not.toContain('class="detail-section surface-panel"')
+    expect(detailSource).not.toContain('class="history-section surface-panel"')
+    expect(detailSource).toContain('padding: var(--admin-space-6, 16px) 0 0')
+    expect(detailSource).toContain("fixed: 'left', width: 132")
+  })
+
+  it('does not expose unknown history action codes', () => {
+    expect(detailSource).toContain("CONFIRM_PRELOAD: '确认预装'")
+    expect(detailSource).toContain("[action] || '状态更新'")
+    expect(detailSource).not.toContain('[action] || action')
+  })
+  it('uses safe labels when customer or operator names are missing', () => {
+    expect(source).toContain("item.customerName || '客户信息缺失'")
+    expect(source).not.toContain('item.customerName || item.accountId')
+    expect(detailSource).toContain("item.customerName || '客户信息缺失'")
+    expect(detailSource).toContain("row.operatorName || '操作人信息缺失'")
+    expect(detailSource).not.toContain('item.customerName || item.accountId')
+    expect(detailSource).not.toContain('row.operatorName || row.operatorId')
+  })
+
+  it('does not retain the retired loading-list customs entry', () => {
+    expect(confirmedDetailSource).not.toContain('LoadingDeclaration')
+    expect(confirmedDetailSource).not.toContain('customsDocument')
+    expect(detailSource).not.toContain('customsDocument')
+    expect(detailSource).not.toContain('报关资料')
+  })
+
+  it('filters pure status no-ops and counts identity-distinct visible history events', () => {
+    for (const marker of ['visibleHistories', 'STATUS_UPDATE', 'operationId', 'PUSH_PRELOAD']) expect(detailSource).toContain(marker)
+    expect(detailSource).toContain('visibleHistories.length }} 条')
+    expect(detailSource).toContain(':data="visibleHistories"')
+    expect(detailSource).not.toContain('detail.histories.length }} 条')
+    expect(detailSource).not.toContain('v-for="history in detail.histories"')
+    expect(detailSource).toContain('seen.has(eventKey)')
+    expect(detailSource).toContain('history.operationId')
+    const sameWording = [
+      { historyId: '4', operationId: '', actionType: 'ADJUST_ITEM', operationReason: '相同文案' },
+      { historyId: '5', operationId: '', actionType: 'ADJUST_ITEM', operationReason: '相同文案' },
+    ]
+    expect(new Set(sameWording.map((history) => history.historyId)).size).toBe(2)
+  })
+})
diff --git a/src/modules/loading-lists/components/LoadingListsView.vue b/src/modules/loading-lists/components/LoadingListsView.vue
new file mode 100644
index 00000000..53841ce0
--- /dev/null
+++ b/src/modules/loading-lists/components/LoadingListsView.vue
@@ -0,0 +1,247 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, reactive, ref, watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { ContainerSimulationCreate } from '@/modules/container-loading'
+import { Eye } from '@lucide/vue'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { listPlatformTenants, type PlatformTenantResource } from '@/modules/iam'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import LineClampText from '@/shared/components/LineClampText.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import { loadingListStatusLabel } from '../status'
+import {
+  listConfirmedLoadingLists,
+  listPreloadPlans,
+  type ConfirmedSummary,
+  type LoadingListMode,
+  type LoadingListQuery,
+  type LoadingListSummary,
+  type PreloadSummary,
+} from '../api/platformLoadingLists'
+
+const props = defineProps<{ mode: LoadingListMode }>()
+const route = useRoute()
+const router = useRouter()
+const access = useAccessPreviewStore()
+const rows = ref<LoadingListSummary[]>([])
+const loading = ref(false)
+const error = ref<ApiErrorDetails | null>(null)
+const page = ref(1)
+const pageSize = ref(20)
+const total = ref(0)
+const customers = ref<PlatformTenantResource[]>([])
+const customersLoading = ref(false)
+const query = reactive<QueryModel>({ customerId: '', keyword: '', createdRange: [] })
+const handledDeepLink = ref('')
+
+const isPreload = computed(() => props.mode === 'preload')
+const title = computed(() => isPreload.value ? '预装清单' : '装柜清单')
+const listPermission = computed(() => isPreload.value ? 'platform:firstleg:preload:list' : 'platform:firstleg:loading-list:list')
+const canList = computed(() => access.can(listPermission.value))
+const canCreate = computed(() => isPreload.value && canList.value && access.can('platform:firstleg:container:create'))
+const canView = computed(() => canList.value)
+const fields = computed<QueryField[]>(() => [
+  { key: 'customerId', type: 'select', label: '客户', placeholder: '全部客户', width: 220, options: customers.value.filter((customer) => customer.status === 'ACTIVE').map((customer) => ({ label: customer.tenantName, value: String(customer.id) })), props: { filterable: true, loading: customersLoading.value } },
+  { key: 'keyword', type: 'input', label: '关键词', placeholder: isPreload.value ? '预装单号/柜次号/集装箱号' : '装柜清单号/柜次号/集装箱号', width: 270 },
+  { key: 'createdRange', type: 'daterange', label: '创建日期', width: 260 },
+])
+
+const columns = computed<DataTableColumn[]>(() => isPreload.value ? [
+  { key: 'actions', label: '操作', fixed: 'left', width: 88, slotName: 'actions', hideable: false, movable: false },
+  { key: 'preloadNo', prop: 'preloadNo', label: '预装单号', minWidth: 120 },
+  { key: 'containerNo', prop: 'containerNo', label: '集装箱号', minWidth: 120 },
+  { key: 'cabinetNo', prop: 'cabinetNo', label: '柜次号', minWidth: 140 },
+  // { key: 'customers', label: '客户', minWidth: 190, slotName: 'customers' },
+  { key: 'warehouseName', prop: 'warehouseName', label: '仓库', minWidth: 80 },
+  { key: 'vesselVoyage', label: '船名 / 航次', minWidth: 175, slotName: 'vesselVoyage' },
+  { key: 'containerType', prop: 'containerType', label: '箱型', width: 80 },
+  { key: 'status', label: '状态', width: 108, slotName: 'status' },
+  { key: 'totalPackageCount', prop: 'totalPackageCount', label: '总箱数', width: 90, align: 'right' },
+  { key: 'skuCount', prop: 'skuCount', label: 'SKU 数', width: 90, align: 'right' },
+  { key: 'totalVolumeCbm', label: '总体积(m³)', width: 90, align: 'right', slotName: 'volume' },
+  { key: 'totalGrossWeightKg', label: '总毛重(kg)', width: 90, align: 'right', slotName: 'grossWeight' },
+  { key: 'createdAt', label: '创建时间', minWidth: 140, slotName: 'createdAt' },
+] : [
+  { key: 'actions', label: '操作', fixed: 'left', width: 110, slotName: 'actions', hideable: false, movable: false },
+  { key: 'loadingListNo', prop: 'loadingListNo', label: '装柜清单号', minWidth: 175 },
+  { key: 'containerNo', prop: 'containerNo', label: '集装箱号', minWidth: 145 },
+  { key: 'cabinetNo', prop: 'cabinetNo', label: '柜次号', minWidth: 150 },
+  { key: 'warehouseName', prop: 'warehouseName', label: '仓库', minWidth: 140 },
+  { key: 'status', label: '状态', width: 110, slotName: 'status' },
+  { key: 'totalPackageCount', prop: 'totalPackageCount', label: '总箱数', width: 90, align: 'right' },
+  { key: 'totalGrossWeightKg', label: '总毛重(kg)', width: 125, align: 'right', slotName: 'grossWeight' },
+  { key: 'totalNetWeightKg', label: '总净重(kg)', width: 125, align: 'right', slotName: 'netWeight' },
+  { key: 'totalVolumeCbm', label: '总体积(m³)', width: 120, align: 'right', slotName: 'volume' },
+  { key: 'totalQuantity', prop: 'totalQuantity', label: '产品总数', width: 105, align: 'right' },
+  { key: 'remark', prop: 'remark', label: '备注', minWidth: 180, showOverflowTooltip: true },
+  { key: 'createdByName', prop: 'createdByName', label: '创建人', minWidth: 120 },
+  { key: 'createdAt', label: '创建时间', minWidth: 155, slotName: 'createdAt' },
+])
+
+function formatDateTime(value?: string | null) {
+  return value ? value.replace('T', ' ').slice(0, 16) : '—'
+}
+
+function formatNumber(value?: number | null, digits = 3) {
+  if (value === null || value === undefined || !Number.isFinite(Number(value))) return '—'
+  return Number(value).toLocaleString('zh-CN', { maximumFractionDigits: digits })
+}
+
+function queryId(value: unknown) {
+  return typeof value === 'string' && /^[1-9]\d*$/.test(value) ? value : ''
+}
+
+function toQuery(): LoadingListQuery {
+  const range = Array.isArray(query.createdRange) ? query.createdRange.map(String) : []
+  return {
+    page: page.value,
+    size: pageSize.value,
+    customerId: String(query.customerId || '').trim() || undefined,
+    keyword: String(query.keyword || '').trim() || undefined,
+    createdFrom: range[0] ? `${range[0]}T00:00:00` : undefined,
+    createdTo: range[1] ? `${range[1]}T23:59:59` : undefined,
+  }
+}
+
+async function load() {
+  if (!canList.value) return
+  const request = toQuery()
+  loading.value = true
+  error.value = null
+  try {
+    const result = isPreload.value ? await listPreloadPlans(request) : await listConfirmedLoadingLists(request)
+    rows.value = result.records
+    total.value = result.total
+    await openDeepLinkedDetail()
+  } catch (cause) {
+    error.value = getApiErrorDetails(cause, `${title.value}加载失败，请稍后重试`)
+  } finally {
+    loading.value = false
+  }
+}
+
+async function openDeepLinkedDetail() {
+  const planId = queryId(route.query.planId)
+  const warehouseId = queryId(route.query.warehouseId)
+  if (!planId || !warehouseId || !canView.value) return
+  const key = `${props.mode}:${planId}:${warehouseId}`
+  if (handledDeepLink.value === key) return
+  handledDeepLink.value = key
+  if (isPreload.value) {
+    await router.replace({ name: 'preload-plan-detail', params: { planId }, query: { warehouseId } })
+    return
+  }
+  await router.replace({ name: 'loading-list-detail', params: { planId }, query: { warehouseId } })
+}
+
+function onSimulationCreated() {
+  Object.assign(query, { customerId: '', keyword: '', createdRange: [] })
+  search()
+}
+
+function search() {
+  if (page.value !== 1) page.value = 1
+  else void load()
+}
+
+
+function openDetail(rowValue: object) {
+  const row = rowValue as LoadingListSummary
+  if (isPreload.value) {
+    void router.push({ name: 'preload-plan-detail', params: { planId: String(row.planId) }, query: { warehouseId: String(row.warehouseId || '') } })
+    return
+  }
+  void router.push({ name: 'loading-list-detail', params: { planId: String(row.planId) }, query: { warehouseId: String(row.warehouseId || '') } })
+}
+
+async function loadCustomers() {
+  customersLoading.value = true
+  try {
+    const result = await listPlatformTenants({ page: 1, size: 200, status: 'ACTIVE' })
+    customers.value = result.records.filter((customer) => customer.status === 'ACTIVE')
+  } catch {
+    customers.value = []
+  } finally {
+    customersLoading.value = false
+  }
+}
+watch([page, pageSize], () => void load())
+watch(() => [route.query.planId, route.query.warehouseId], () => void openDeepLinkedDetail())
+onMounted(() => {
+  void load()
+  void loadCustomers()
+})
+</script>
+
+<template>
+  <AdminPage>
+  <div class="business-page loading-lists-page" :class="{ 'admin-density': isPreload }">
+    <ListPageLayout :ariaLabel="title">
+      <template #toolbar>
+    <QueryToolbar
+      v-model="query"
+      :ariaLabel="`${title}筛选`"
+      :fields="fields"
+      :available-fields="fields"
+      :preference-key="`loading-lists-${mode}-query`"
+      @search="search"
+    />
+      </template>
+
+      <template v-if="!canList || error" #state>
+        <LoadErrorState v-if="!canList" :title="`无权查看${title}`" message="当前账号缺少该清单的列表权限。" :show-retry="false" />
+        <LoadErrorState v-else-if="error" :title="`${title}加载失败`" :message="error.message" :loading="loading" @retry="load">
+          <template #details><ApiErrorMeta :details="error" /></template>
+        </LoadErrorState>
+      </template>
+    <section v-if="canList && !error" class="surface-panel table-panel">
+      <DataTable
+        v-model:page="page"
+        v-model:page-size="pageSize"
+        :data="rows"
+        :columns="columns"
+        :loading="loading"
+        stripe
+        :total="total"
+        :preference-key="`loading-lists-${mode}`"
+        row-key="planId"
+        :empty-text="`暂无符合筛选条件的${title}`"
+        :aria-label="title"
+      >
+        <template #toolbar-actions>
+          <ContainerSimulationCreate :dense="isPreload" v-if="canCreate" success-message="模拟柜及预装清单已创建" @created="onSimulationCreated" />
+        </template>
+        <template #actions="{ row }">
+          <div class="row-actions" :class="{ 'density-actions': isPreload }">
+            <el-button v-if="canView" :class="{ 'density-action': isPreload }" size="small" :type="isPreload ? undefined : 'primary'" :plain="!isPreload" @click="openDetail(row)"><Eye v-if="!isPreload" :size="15" />查看</el-button>
+          </div>
+        </template>
+        <template #customers="{ row }"><LineClampText :content="(row as PreloadSummary).customers.map((item) => item.customerName || '客户信息缺失').join('、')" /></template>
+        <template #vesselVoyage="{ row }">{{ (row as PreloadSummary).vesselName || '—' }} / {{ (row as PreloadSummary).voyageNo || '—' }}</template>
+        <template #status="{ row }"><StatusBadge :status="loadingListStatusLabel(row.status)" /></template>
+        <template #grossWeight="{ row }">{{ formatNumber(row.totalGrossWeightKg) }}</template>
+        <template #netWeight="{ row }">{{ formatNumber((row as ConfirmedSummary).totalNetWeightKg) }}</template>
+        <template #volume="{ row }">{{ formatNumber(row.totalVolumeCbm) }}</template>
+        <template #createdAt="{ row }">{{ formatDateTime(row.createdAt) }}</template>
+      </DataTable>
+    </section>
+    </ListPageLayout>
+
+  </div>
+  </AdminPage>
+</template>
+
+<style scoped>
+.loading-lists-page { display: grid; min-width: 0; gap: var(--admin-space-6, 16px); }
+.table-panel { min-width: 0; overflow: hidden; border: 1px solid var(--cc-border); background: var(--admin-surface, #fff); }
+.row-actions { display: flex; align-items: center; flex-wrap: wrap; gap: var(--admin-space-2, 6px); }
+.row-actions :deep(.el-button) { margin-left: 0; }
+@media (max-width: 720px) { .row-actions { gap: 4px; } }
+</style>
diff --git a/src/modules/loading-lists/components/PalletLabelPrintDialog.test.ts b/src/modules/loading-lists/components/PalletLabelPrintDialog.test.ts
new file mode 100644
index 00000000..71e0822b
--- /dev/null
+++ b/src/modules/loading-lists/components/PalletLabelPrintDialog.test.ts
@@ -0,0 +1,58 @@
+import { mount } from '@vue/test-utils'
+import { nextTick } from 'vue'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import PalletLabelPrintDialog from './PalletLabelPrintDialog.vue'
+
+const preparePalletLabels = vi.fn()
+
+vi.mock('../api/platformLoadingLists', () => ({
+  preparePalletLabels: (...args: unknown[]) => preparePalletLabels(...args),
+  printPalletLabels: vi.fn(),
+}))
+
+describe('PalletLabelPrintDialog', () => {
+  beforeEach(() => {
+    preparePalletLabels.mockReset().mockResolvedValue({
+      planId: '10', planNo: 'LP-1', containerNo: 'HLCU1723867', totalCount: 2,
+      groups: [{
+        destinationWarehouseCode: 'ACY2', destinationWarehouseInternalCode: '101',
+        destinationWarehouseName: 'ACY2', totalCount: 2,
+        labels: [
+          { palletCode: 'HLCU1723867-101-001' },
+          { palletCode: 'HLCU1723867-101-002' },
+        ],
+      }],
+    })
+  })
+
+  it('shows the server-generated internal code rule and both warehouse codes', async () => {
+    const wrapper = mount(PalletLabelPrintDialog, {
+      props: { planId: '10', warehouseId: '20' },
+      global: {
+        stubs: {
+          AppDialog: { template: '<section><slot /></section>' },
+          LoadErrorState: true,
+          Printer: true,
+          'el-button': { template: '<button @click="$emit(\'click\')"><slot /></button>' },
+          'el-alert': { props: ['title'], template: '<p>{{ title }}</p>' },
+          'el-radio-group': { template: '<div><slot /></div>' },
+          'el-radio': { template: '<span><slot /></span>' },
+          'el-select': { template: '<div><slot /></div>' },
+          'el-option': true,
+          'el-input-number': true,
+          'el-table': { props: ['data'], template: '<div>{{ data }}</div>' },
+          'el-table-column': true,
+        },
+      },
+    })
+    await wrapper.get('button').trigger('click')
+    await nextTick()
+    await nextTick()
+
+    expect(preparePalletLabels).toHaveBeenCalledWith('10', '20')
+    expect(wrapper.text()).toContain('HLCU1723867-FBA地址内部编号-三位序号')
+    expect(wrapper.text()).toContain('ACY2')
+    expect(wrapper.text()).toContain('101')
+    expect(wrapper.text()).toContain('HLCU1723867-101-001')
+  })
+})
diff --git a/src/modules/loading-lists/components/PalletLabelPrintDialog.vue b/src/modules/loading-lists/components/PalletLabelPrintDialog.vue
new file mode 100644
index 00000000..602eb11a
--- /dev/null
+++ b/src/modules/loading-lists/components/PalletLabelPrintDialog.vue
@@ -0,0 +1,66 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, ref } from 'vue'
+import { Printer } from '@lucide/vue'
+import { ElMessage } from 'element-plus'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { preparePalletLabels, printPalletLabels, type PalletLabelManifest } from '../api/platformLoadingLists'
+
+const props = defineProps<{ planId: string; warehouseId: string; disabled?: boolean; dense?: boolean }>()
+const open = ref(false)
+const loading = ref(false)
+const printing = ref(false)
+const error = ref<ApiErrorDetails | null>(null)
+const manifest = ref<PalletLabelManifest | null>(null)
+const scope = ref<'ALL' | 'WAREHOUSE'>('ALL')
+const warehouseCode = ref('')
+const count = ref(1)
+const selectedGroup = computed(() => manifest.value?.groups.find((group) => group.destinationWarehouseCode === warehouseCode.value) || null)
+const disabledConfirm = computed(() => !manifest.value?.totalCount || (scope.value === 'WAREHOUSE' && (!selectedGroup.value || count.value < 1 || count.value > selectedGroup.value.totalCount)))
+
+async function show() {
+  open.value = true; loading.value = true; error.value = null; manifest.value = null
+  try {
+    manifest.value = await preparePalletLabels(props.planId, props.warehouseId)
+    warehouseCode.value = manifest.value.groups[0]?.destinationWarehouseCode || ''
+    count.value = manifest.value.groups[0]?.totalCount || 1
+  } catch (cause) { error.value = getApiErrorDetails(cause, '托盘码清单加载失败') }
+  finally { loading.value = false }
+}
+
+function onWarehouseChange() { count.value = selectedGroup.value?.totalCount || 1 }
+async function print() {
+  if (!manifest.value) return
+  printing.value = true; error.value = null
+  try {
+    const blob = await printPalletLabels(props.planId, props.warehouseId,
+      scope.value === 'WAREHOUSE' ? warehouseCode.value : undefined,
+      scope.value === 'WAREHOUSE' ? count.value : undefined)
+    const url = URL.createObjectURL(blob); const anchor = document.createElement('a')
+    anchor.href = url; anchor.download = `${manifest.value.containerNo}-托盘码.pdf`; anchor.click(); URL.revokeObjectURL(url)
+    ElMessage.success(`已生成 ${scope.value === 'ALL' ? manifest.value.totalCount : count.value} 张托盘码`)
+  } catch (cause) { error.value = getApiErrorDetails(cause, '托盘码打印失败') }
+  finally { printing.value = false }
+}
+</script>
+
+<template>
+  <el-button :disabled="disabled" @click="show"><Printer :size="16" />打印托盘码</el-button>
+  <AppDialog :class="{ 'admin-density-dialog': dense }" v-model="open" title="散货托盘码" width="min(760px, calc(100vw - 28px))" confirm-text="生成 PDF" :loading="loading" :confirm-loading="printing" :confirm-disabled="disabledConfirm" @confirm="print">
+    <LoadErrorState v-if="error" compact title="托盘码操作失败" :message="error.message" :show-retry="false" />
+    <template v-if="manifest">
+      <el-alert type="info" :closable="false" :title="`编号规则：${manifest.containerNo}-FBA地址内部编号-三位序号；一件代发托盘不在此清单。`" />
+      <el-radio-group v-model="scope" class="print-scope"><el-radio value="ALL">全部打印（{{ manifest.totalCount }} 张）</el-radio><el-radio value="WAREHOUSE">按 FBA 仓补打</el-radio></el-radio-group>
+      <div v-if="scope === 'WAREHOUSE'" class="print-options"><el-select v-model="warehouseCode" placeholder="选择 FBA 仓" @change="onWarehouseChange"><el-option v-for="group in manifest.groups" :key="group.destinationWarehouseCode" :label="`${group.destinationWarehouseCode} · ${group.totalCount} 张`" :value="group.destinationWarehouseCode" /></el-select><el-input-number v-model="count" placeholder="打印张数" :min="1" :max="selectedGroup?.totalCount || 1" /><span>张（从该仓第 1 张起）</span></div>
+      <el-table :data="manifest.groups" border max-height="300"><el-table-column label="FBA 仓编码" prop="destinationWarehouseCode" width="140" /><el-table-column label="内部编号" prop="destinationWarehouseInternalCode" width="120" /><el-table-column label="FBA 仓名称" prop="destinationWarehouseName" min-width="160"><template #default="{ row }">{{ row.destinationWarehouseName || '—' }}</template></el-table-column><el-table-column label="托盘数" prop="totalCount" width="90" align="right" /><el-table-column label="编号范围" min-width="230"><template #default="{ row }">{{ row.labels[0]?.palletCode || '—' }}<template v-if="row.labels.length > 1"> ～ {{ row.labels[row.labels.length - 1]?.palletCode }}</template></template></el-table-column></el-table>
+    </template>
+  </AppDialog>
+</template>
+
+<style scoped>
+.print-scope { display:flex; margin:18px 0 var(--admin-space-5, 12px); }
+.print-options { display:flex; align-items:center; gap:var(--admin-space-5, 12px); margin-bottom:var(--admin-space-6, 16px); }
+.print-options .el-select { width:240px; }
+</style>
diff --git a/src/modules/loading-lists/index.ts b/src/modules/loading-lists/index.ts
new file mode 100644
index 00000000..f73be7ad
--- /dev/null
+++ b/src/modules/loading-lists/index.ts
@@ -0,0 +1,13 @@
+export * from './api/platformLoadingLists'
+export {
+  listContainerFeeSupplierOptions,
+  uploadContainerFeePaymentVoucher,
+  type ContainerFeePaymentMethod,
+  type ContainerFeeSettlementMode,
+  type ContainerFeeSupplierOption,
+} from './api/containerFees'
+export { loadingListRoutes } from './routes'
+export { loadingListStatusLabel } from './status'
+export { default as ContainerFeesPanel } from './components/ContainerFeesPanel.vue'
+export { default as LoadingListDetailDrawer } from './components/LoadingListDetailDrawer.vue'
+export { default as PalletLabelPrintDialog } from './components/PalletLabelPrintDialog.vue'
diff --git a/src/modules/loading-lists/pages/ConfirmedLoadingListDetailView.vue b/src/modules/loading-lists/pages/ConfirmedLoadingListDetailView.vue
new file mode 100644
index 00000000..03bd60b8
--- /dev/null
+++ b/src/modules/loading-lists/pages/ConfirmedLoadingListDetailView.vue
@@ -0,0 +1,77 @@
+<script setup lang="ts">
+import { computed, onMounted, ref, watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import LoadingListDetailDrawer from '../components/LoadingListDetailDrawer.vue'
+import {
+  getConfirmedLoadingList,
+  type ConfirmedSummary,
+  type LoadingDetail,
+} from '../api/platformLoadingLists'
+
+const route = useRoute()
+const router = useRouter()
+const loading = ref(false)
+const detail = ref<LoadingDetail<ConfirmedSummary> | null>(null)
+const error = ref<ApiErrorDetails | null>(null)
+let loadSequence = 0
+const planId = computed(() => String(route.params.planId || ''))
+const warehouseId = computed(() => typeof route.query.warehouseId === 'string' ? route.query.warehouseId : '')
+
+async function loadDetail() {
+  const sequence = ++loadSequence
+  detail.value = null
+  if (!planId.value || !warehouseId.value) {
+    loading.value = false
+    error.value = { code: 'MISSING_WAREHOUSE_CONTEXT', message: '该清单缺少所属仓库信息，无法安全查询详情，请返回列表重新进入。' }
+    return
+  }
+  loading.value = true
+  error.value = null
+  try {
+    const result = await getConfirmedLoadingList(planId.value, warehouseId.value)
+    if (sequence !== loadSequence) return
+    if (result.summary.status !== 'COMPLETED') {
+      error.value = { code: 'MODE_STATUS_MISMATCH', message: '该计划尚未形成正式装柜清单，请从预装清单入口查看。' }
+      return
+    }
+    detail.value = result
+  } catch (cause) {
+    if (sequence !== loadSequence) return
+    detail.value = null
+    error.value = getApiErrorDetails(cause, '装柜清单详情加载失败，请稍后重试')
+  } finally {
+    if (sequence === loadSequence) loading.value = false
+  }
+}
+
+function goBack() {
+  if (window.history.length > 1) router.back()
+  else void router.push({ name: 'loading-lists' })
+}
+
+onMounted(() => void loadDetail())
+watch([planId, warehouseId], () => void loadDetail())
+</script>
+
+<template>
+  <AdminPage>
+    <div class="confirmed-loading-detail-page">
+      <LoadingListDetailDrawer
+        mode="confirmed"
+        :loading="loading"
+        :detail="detail"
+        :error="error"
+        :can-edit="false"
+        @back="goBack"
+        @retry="loadDetail"
+      />
+    </div>
+  </AdminPage>
+</template>
+
+<style scoped>
+.confirmed-loading-detail-page { display: grid; min-width: 0; max-width: 1280px; gap: 16px; }
+@media (min-width: 1920px) { .confirmed-loading-detail-page { width: 100%; max-width: none; gap: 12px; } }
+</style>
diff --git a/src/modules/loading-lists/pages/ConfirmedLoadingListsView.vue b/src/modules/loading-lists/pages/ConfirmedLoadingListsView.vue
new file mode 100644
index 00000000..fc79c1f4
--- /dev/null
+++ b/src/modules/loading-lists/pages/ConfirmedLoadingListsView.vue
@@ -0,0 +1,5 @@
+<script setup lang="ts">
+import LoadingListsView from '../components/LoadingListsView.vue'
+</script>
+
+<template><LoadingListsView mode="confirmed" /></template>
diff --git a/src/modules/loading-lists/pages/PreloadPlanDetailView.lifecycle.test.ts b/src/modules/loading-lists/pages/PreloadPlanDetailView.lifecycle.test.ts
new file mode 100644
index 00000000..b81b4870
--- /dev/null
+++ b/src/modules/loading-lists/pages/PreloadPlanDetailView.lifecycle.test.ts
@@ -0,0 +1,138 @@
+import { flushPromises, shallowMount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { ElMessage } from 'element-plus'
+import { ApiResponseError, http } from '@/shared/api/http'
+import { getConfirmedLoadingList, getPreloadPlan } from '../api/platformLoadingLists'
+import PreloadPlanDetailView from './PreloadPlanDetailView.vue'
+
+const routerReplace = vi.hoisted(() => vi.fn())
+const removeWorkspaceTabs = vi.hoisted(() => vi.fn())
+vi.mock('vue-router', () => ({
+  useRoute: () => ({ params: { planId: '1900000000000000001' }, query: { warehouseId: '1900000000000000002' } }),
+  useRouter: () => ({ replace: routerReplace, push: vi.fn(), back: vi.fn() }),
+}))
+vi.mock('@/core/access/accessPreview', () => ({ useAccessPreviewStore: () => ({ can: () => true }) }))
+vi.mock('@/core/workspace-tabs/workspaceTabs', () => ({ useWorkspaceTabsStore: () => ({ removeByIds: removeWorkspaceTabs }) }))
+vi.mock('../api/platformLoadingLists', () => ({
+  confirmPreloadPlan: vi.fn(),
+  getConfirmedLoadingList: vi.fn(),
+  getPreloadPlan: vi.fn(),
+  updateLoadingItemRemarks: vi.fn(),
+  updatePreloadTransport: vi.fn(),
+}))
+
+async function mountView() {
+  const wrapper = shallowMount(PreloadPlanDetailView, {
+    global: {
+      stubs: {
+        AdminPage: { template: '<main><slot /></main>' },
+        LoadingListDetailDrawer: { name: 'LoadingListDetailDrawer', props: ['error', 'loading'], template: '<section />' },
+        OperationErrorToast: true,
+        AppDialog: true,
+      },
+    },
+  })
+  await flushPromises()
+  return wrapper
+}
+
+function drawerError(wrapper: Awaited<ReturnType<typeof mountView>>) {
+  return wrapper.findComponent({ name: 'LoadingListDetailDrawer' }).props('error')
+}
+
+function lifecycle(detailResource: 'PRELOAD' | 'LOADING_LIST', planStatus: string) {
+  return { code: '200', message: 'success', data: { planId: '1900000000000000001', detailResource, planStatus } }
+}
+
+describe('PreloadPlanDetailView lifecycle handoff', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks()
+    vi.clearAllMocks()
+    routerReplace.mockResolvedValue(undefined)
+  })
+
+  it('replaces the current tab after authoritative lifecycle resolution', async () => {
+    vi.spyOn(http, 'get').mockResolvedValue(lifecycle('LOADING_LIST', 'COMPLETED'))
+    vi.mocked(getConfirmedLoadingList).mockResolvedValue({ summary: { containerBookingId: '2900000000000000001' }, items: [], histories: [] } as never)
+    const message = vi.spyOn(ElMessage, 'success').mockImplementation(() => undefined as never)
+
+    const wrapper = await mountView()
+
+    expect(http.get).toHaveBeenCalledWith(
+      '/platform/v1/first-leg/loading-plans/1900000000000000001/lifecycle',
+      { params: { warehouseId: '1900000000000000002' } },
+    )
+    expect(getPreloadPlan).not.toHaveBeenCalled()
+    expect(routerReplace).toHaveBeenCalledTimes(1)
+    expect(routerReplace).toHaveBeenCalledWith({
+      name: 'domestic-container-detail',
+      params: { containerId: '2900000000000000001' },
+      query: { tab: 'loading-list' },
+    })
+    expect(removeWorkspaceTabs).toHaveBeenCalledWith(['preload-plan-detail'])
+    expect(routerReplace.mock.invocationCallOrder[0]).toBeLessThan(removeWorkspaceTabs.mock.invocationCallOrder[0]!)
+    expect(message).toHaveBeenCalledWith('装柜已完成，已切换至装柜清单详情')
+    expect(drawerError(wrapper)).toBeNull()
+    expect(wrapper.findComponent({ name: 'LoadingListDetailDrawer' }).props('loading')).toBe(false)
+  })
+
+  it('loads preload detail only while the lifecycle remains PRELOAD', async () => {
+    vi.spyOn(http, 'get').mockResolvedValue(lifecycle('PRELOAD', 'LOADING'))
+    vi.mocked(getPreloadPlan).mockResolvedValue({
+      summary: {
+        status: 'LOADING', containerNo: null,
+        readiness: { pdaTaskStatus: null },
+      },
+      items: [], histories: [],
+    } as never)
+
+    const wrapper = await mountView()
+
+    expect(getPreloadPlan).toHaveBeenCalledWith('1900000000000000001', '1900000000000000002')
+    expect(routerReplace).not.toHaveBeenCalled()
+    expect(removeWorkspaceTabs).not.toHaveBeenCalled()
+    expect(drawerError(wrapper)).toBeNull()
+  })
+
+  it('shows A0404 only when lifecycle resolution confirms the plan is absent', async () => {
+    vi.spyOn(http, 'get').mockRejectedValue(new ApiResponseError('装柜计划不存在', 'A0404', 404, undefined, 'request-lifecycle', 'trace-lifecycle'))
+
+    const wrapper = await mountView()
+
+    expect(getPreloadPlan).not.toHaveBeenCalled()
+    expect(routerReplace).not.toHaveBeenCalled()
+    expect(drawerError(wrapper)).toMatchObject({ code: 'A0404', requestId: 'request-lifecycle', traceId: 'trace-lifecycle', message: '装柜计划不存在' })
+  })
+
+  it.each([
+    ['A0403', 403, 'request-forbidden', 'trace-forbidden'],
+    ['S0503', 503, 'request-unavailable', 'trace-unavailable'],
+  ])('does not swallow a lifecycle %s error', async (code, status, requestId, traceId) => {
+    vi.spyOn(http, 'get').mockRejectedValue(new ApiResponseError('装柜计划解析失败', code, status, undefined, requestId, traceId))
+
+    const wrapper = await mountView()
+
+    expect(getPreloadPlan).not.toHaveBeenCalled()
+    expect(routerReplace).not.toHaveBeenCalled()
+    expect(drawerError(wrapper)).toMatchObject({ code, requestId, traceId })
+  })
+
+  it('surfaces a network failure without guessing from another detail endpoint', async () => {
+    vi.spyOn(http, 'get').mockRejectedValue(new Error('Network Error'))
+
+    const wrapper = await mountView()
+
+    expect(getPreloadPlan).not.toHaveBeenCalled()
+    expect(routerReplace).not.toHaveBeenCalled()
+    expect(drawerError(wrapper)).toMatchObject({ message: '预装清单详情加载失败，请稍后重试' })
+  })
+
+  it('does not redirect for an internally inconsistent lifecycle payload', async () => {
+    vi.spyOn(http, 'get').mockResolvedValue(lifecycle('LOADING_LIST', 'LOADING'))
+
+    const wrapper = await mountView()
+
+    expect(routerReplace).not.toHaveBeenCalled()
+    expect(drawerError(wrapper)).toMatchObject({ code: 'MODE_STATUS_MISMATCH' })
+  })
+})
diff --git a/src/modules/loading-lists/pages/PreloadPlanDetailView.test.ts b/src/modules/loading-lists/pages/PreloadPlanDetailView.test.ts
new file mode 100644
index 00000000..dcf1e06d
--- /dev/null
+++ b/src/modules/loading-lists/pages/PreloadPlanDetailView.test.ts
@@ -0,0 +1,111 @@
+import { describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/loading-lists/pages/PreloadPlanDetailView.vue'), 'utf8')
+const detailSource = readFileSync(resolve(process.cwd(), 'src/modules/loading-lists/components/LoadingListDetailDrawer.vue'), 'utf8')
+
+describe('PreloadPlanDetailView prototype contract', () => {
+  it('is a formal desktop detail page wired to the shared header return action', () => {
+    expect(source).toContain('<AdminPage>')
+    expect(source).toContain('@back="goBack"')
+    expect(source).toContain("router.push({ name: 'loading-plans' })")
+    expect(source).toContain('@media (min-width: 1920px) { .preload-detail-page { width: 100%; max-width: none; gap: var(--admin-space-5, 12px); } }')
+    expect(source).not.toContain('AppDrawer')
+  })
+
+  it('requires the real warehouse context and preserves status boundaries', () => {
+    expect(source).toContain('MISSING_WAREHOUSE_CONTEXT')
+    expect(source).toContain("['EDITING', 'LOADING'].includes(result.summary.status)")
+    expect(source).toContain('MODE_STATUS_MISMATCH')
+  })
+
+  it('switches a completed preload lifecycle to the confirmed detail without swallowing unrelated errors', () => {
+    expect(source).toContain('/loading-plans/${encodeURIComponent(planId.value)}/lifecycle')
+    expect(source).toContain("lifecycle.detailResource === 'LOADING_LIST'")
+    expect(source).toContain("lifecycle.planStatus !== 'COMPLETED'")
+    expect(source).toContain("router.replace({ name: 'domestic-container-detail'")
+    expect(source).toContain("workspace.removeByIds(['preload-plan-detail'])")
+    expect(source).toContain('装柜已完成，已切换至装柜清单详情')
+    expect(source).not.toContain("preloadError.code !== 'A0404'")
+    expect(source).toContain('getConfirmedLoadingList')
+    expect(source).not.toContain("router.push({ name: 'loading-list-detail'")
+  })
+
+  it('uses the real optimistic-lock transport endpoint without inventing note writes', () => {
+    expect(source).toContain('updatePreloadTransport')
+    expect(source).toContain('expectedVersion: detail.value.summary.version')
+    expect(source).toContain('width="min(620px, calc(100vw - 28px))"')
+    expect(source).not.toContain('saveMfNote')
+  })
+
+  it('edits the selected item internal, warehouse and customer-service remarks with optimistic locking', () => {
+    expect(source).toContain('@edit-remarks="openRemarks"')
+    expect(source).toContain('updateLoadingItemRemarks(current.summary.planId, target.itemId')
+    expect(source).toContain('expectedPlanVersion: current.summary.version')
+    expect(source).toContain('expectedItemVersion: target.itemVersion')
+    expect(source).toContain('operationId: remarkOperationId.value')
+    expect(source).toContain('maxlength="1000"')
+    expect(source).toContain("remarkForm.internalRemark.trim() || null")
+    expect(source).toContain("remarkForm.warehouseRemark.trim() || null")
+    expect(source).toContain("remarkForm.customerServiceRemark.trim() || null")
+    expect(source).toContain('summary: { ...current.summary, version: result.version }')
+    expect(source).toContain('updatedItem?.version')
+    expect(source).not.toContain('plan.remark')
+  })
+
+  it('preserves remark input and refreshes current data on conflicts', () => {
+    expect(source).toContain("details.code === 'A0409'")
+    expect(source).toContain('await loadDetail()')
+    expect(source).toContain("detail.value?.items.find((item) => item.itemId === target.itemId) || target")
+    expect(source).toContain('当前输入已保留')
+    expect(source).toContain('计划状态或明细版本已变化')
+    expect(source).toContain(':confirm-loading="remarkSaving"')
+  })
+
+  it('requires first entry before confirmation and still repairs historical tasks that were created without it', () => {
+    expect(source).toContain("{ required: true, message: '请输入集装箱号'")
+    expect(source).toContain("['EDITING', 'LOADING'].includes(summary.status)")
+    expect(source).toContain('if (!summary.containerNo) return true')
+    expect(source).not.toContain('summary?.containerNo && summary.status')
+    expect(source).toContain('PDA 已领取或作业已开始，真实集装箱号只读。')
+    expect(source).toContain('该历史 PDA 任务缺少真实集装箱号；补录保存后即可进入任务。')
+    expect(source).toContain('确认预装前必须补录真实集装箱号。')
+    expect(source).toContain("isContainerCorrection.value ? '纠正集装箱号 / 航次' : '补录集装箱号 / 航次'")
+    expect(source).toContain("isContainerCorrection.value && !String(value || '').trim() ? new Error('纠错时请输入操作原因')")
+    expect(source).toContain("String(value || '').trim().toUpperCase()")
+    expect(source).toContain('operationReason: editForm.operationReason.trim() || null')
+    expect(detailSource).toContain('v-if="canEditTransport"')
+    expect(detailSource).toContain("summary.containerNo || '待补录'")
+    expect(detailSource).toContain("CONTAINER_NO_MISSING: '尚未录入真实集装箱号，请先补录后再确认预装'")
+  })
+
+  it('uses a flat blocking note instead of repeated colored page alerts', () => {
+    expect(source).not.toContain('<el-alert\n        v-if="detail"')
+    expect(detailSource).toContain('class="readiness-note"')
+    expect(detailSource).toContain('role="status"')
+    expect(detailSource).toContain("confirmationStatus !== 'CONFIRMED' && !preloadSummary.readiness.canConfirm")
+    expect(detailSource).not.toContain('type="success" :closable="false" show-icon title="整份预装计划已确认"')
+    expect(detailSource).toContain('<el-button type="primary" :loading="confirmSaving"')
+    expect(detailSource).not.toContain('<el-button type="success" :loading="confirmSaving"')
+  })
+
+  it('confirms the whole plan through readiness with stable idempotency and refreshes the detail', () => {
+    expect(source).toContain('confirmPreloadPlan(summary.planId, summary.version, confirmOperationId.value)')
+    expect(source).toContain('summary?.readiness.canConfirm')
+    expect(source).toContain('confirmSaving.value')
+    expect(source).toContain('await loadDetail()')
+    expect(source).toContain('本操作将确认整份预装计划')
+    expect(source).toContain(':confirm-disabled="!detail?.summary.readiness.canConfirm"')
+    expect(source).not.toContain('/inbounds/')
+  })
+
+  it('keeps backend confirmation errors visible and supports narrow dialogs', () => {
+    expect(source).toContain("confirmError.value = getApiErrorDetails(cause, '确认预装失败，请稍后重试')")
+    expect(source).toContain('<OperationErrorToast :details="remarkError || editError || confirmError" />')
+    expect(source).not.toContain(':message="confirmError.message"')
+    expect(source).toContain('width="min(520px, calc(100vw - 28px))"')
+    expect(source).toContain("label=\"柜次号\"")
+    expect(source).toContain("label=\"集装箱号\"")
+  })
+})
diff --git a/src/modules/loading-lists/pages/PreloadPlanDetailView.vue b/src/modules/loading-lists/pages/PreloadPlanDetailView.vue
new file mode 100644
index 00000000..2b1da4fa
--- /dev/null
+++ b/src/modules/loading-lists/pages/PreloadPlanDetailView.vue
@@ -0,0 +1,304 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, reactive, ref, watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { ElMessage, type FormInstance, type FormRules } from 'element-plus'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import OperationErrorToast from '@/shared/components/OperationErrorToast.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { getApiErrorDetails, http, unwrapApiResponse, type ApiEnvelope, type ApiErrorDetails } from '@/shared/api/http'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useWorkspaceTabsStore } from '@/core/workspace-tabs/workspaceTabs'
+import LoadingListDetailDrawer from '../components/LoadingListDetailDrawer.vue'
+import { confirmPreloadPlan, getConfirmedLoadingList, getPreloadPlan, updateLoadingItemRemarks, updatePreloadTransport, type LoadingDetail, type LoadingItem, type PreloadSummary } from '../api/platformLoadingLists'
+
+const route = useRoute()
+const router = useRouter()
+const access = useAccessPreviewStore()
+const workspace = useWorkspaceTabsStore()
+const loading = ref(false)
+const detail = ref<LoadingDetail<PreloadSummary> | null>(null)
+const error = ref<ApiErrorDetails | null>(null)
+const editOpen = ref(false)
+const editSaving = ref(false)
+const editError = ref<ApiErrorDetails | null>(null)
+const confirmOpen = ref(false)
+const confirmSaving = ref(false)
+const confirmError = ref<ApiErrorDetails | null>(null)
+const confirmOperationId = ref('')
+const editFormRef = ref<FormInstance>()
+const editForm = reactive({ containerNo: '', voyageNo: '', operationReason: '' })
+const remarkOpen = ref(false)
+const remarkSaving = ref(false)
+const remarkError = ref<ApiErrorDetails | null>(null)
+const remarkTarget = ref<LoadingItem | null>(null)
+const remarkForm = reactive({ internalRemark: '', warehouseRemark: '', customerServiceRemark: '' })
+const remarkOperationId = ref('')
+let loadSequence = 0
+const planId = computed(() => String(route.params.planId || ''))
+const warehouseId = computed(() => typeof route.query.warehouseId === 'string' ? route.query.warehouseId : '')
+type LoadingPlanLifecycle = { planId: string | number; planStatus: string; detailResource: 'PRELOAD' | 'LOADING_LIST' }
+
+async function resolveLoadingPlanLifecycle() {
+  const response = await http.get<ApiEnvelope<LoadingPlanLifecycle>, ApiEnvelope<LoadingPlanLifecycle>>(
+    `/platform/v1/first-leg/loading-plans/${encodeURIComponent(planId.value)}/lifecycle`,
+    { params: { warehouseId: warehouseId.value } },
+  )
+  return unwrapApiResponse(response)
+}
+const canEdit = computed(() => access.can('platform:firstleg:preload:edit'))
+const canCorrectTransport = computed(() => {
+  const summary = detail.value?.summary
+  const pdaStatus = summary?.readiness.pdaTaskStatus
+  if (!canEdit.value || !summary || !['EDITING', 'LOADING'].includes(summary.status)) return false
+  if (!summary.containerNo) return true
+  return !pdaStatus || pdaStatus === 'PENDING'
+})
+const isContainerCorrection = computed(() => Boolean(detail.value?.summary.containerNo))
+const transportCorrectionNote = computed(() => {
+  const summary = detail.value?.summary
+  if (!summary) return ''
+  if (!summary.containerNo && summary.readiness.pdaTaskId) return '该历史 PDA 任务缺少真实集装箱号；补录保存后即可进入任务。'
+  if (summary.readiness.pdaTaskStatus && summary.readiness.pdaTaskStatus !== 'PENDING') return 'PDA 已领取或作业已开始，真实集装箱号只读。'
+  if (!canCorrectTransport.value) return '当前服务端阶段不允许纠正真实集装箱号。'
+  if (!summary.containerNo) return '确认预装前必须补录真实集装箱号。'
+  return '真实集装箱号仅可在 PDA 领取前纠错，纠错保存时必须填写操作原因。'
+})
+const editDialogTitle = computed(() => isContainerCorrection.value ? '纠正集装箱号 / 航次' : '补录集装箱号 / 航次')
+const editRules: FormRules = {
+  containerNo: [
+    { required: true, message: '请输入集装箱号', trigger: 'blur' },
+    { max: 64, message: '集装箱号不能超过 64 个字符', trigger: 'blur' },
+  ],
+  voyageNo: [{ max: 64, message: '航次不能超过 64 个字符', trigger: 'blur' }],
+  operationReason: [
+    { validator: (_rule, value, callback) => callback(isContainerCorrection.value && !String(value || '').trim() ? new Error('纠错时请输入操作原因') : undefined), trigger: 'blur' },
+    { max: 500, message: '操作原因不能超过 500 个字符', trigger: 'blur' },
+  ],
+}
+
+function normalizedContainerNo(value: string | null | undefined) { return String(value || '').trim().toUpperCase() }
+
+async function loadDetail() {
+  const sequence = ++loadSequence
+  detail.value = null
+  if (!planId.value || !warehouseId.value) {
+    loading.value = false
+    error.value = { code: 'MISSING_WAREHOUSE_CONTEXT', message: '该清单缺少所属仓库信息，无法安全查询详情，请返回列表重新进入。' }
+    return
+  }
+  loading.value = true
+  error.value = null
+  try {
+    const lifecycle = await resolveLoadingPlanLifecycle()
+    if (sequence !== loadSequence) return
+    if (lifecycle.detailResource === 'LOADING_LIST') {
+      if (lifecycle.planStatus !== 'COMPLETED') {
+        error.value = { code: 'MODE_STATUS_MISMATCH', message: '装柜计划阶段异常，暂时无法切换详情，请稍后重试。' }
+        return
+      }
+      const confirmed = await getConfirmedLoadingList(planId.value, warehouseId.value)
+      await router.replace({ name: 'domestic-container-detail', params: { containerId: confirmed.summary.containerBookingId }, query: { tab: 'loading-list' } })
+      workspace.removeByIds(['preload-plan-detail'])
+      if (sequence === loadSequence) ElMessage.success('装柜已完成，已切换至装柜清单详情')
+      return
+    }
+    if (lifecycle.detailResource !== 'PRELOAD') {
+      error.value = { code: 'MODE_STATUS_MISMATCH', message: '无法识别当前装柜计划阶段，请稍后重试。' }
+      return
+    }
+    const result = await getPreloadPlan(planId.value, warehouseId.value)
+    if (sequence !== loadSequence) return
+    if (!['EDITING', 'LOADING'].includes(result.summary.status)) {
+      detail.value = null
+      error.value = { code: 'MODE_STATUS_MISMATCH', message: '该计划不属于预装清单状态，请从对应清单入口查看。' }
+      return
+    }
+    detail.value = result
+  } catch (cause) {
+    if (sequence !== loadSequence) return
+    error.value = getApiErrorDetails(cause, '预装清单详情加载失败，请稍后重试')
+  } finally {
+    if (sequence === loadSequence) loading.value = false
+  }
+}
+
+function goBack() {
+  if (window.history.length > 1) router.back()
+  else void router.push({ name: 'loading-plans' })
+}
+
+function openEdit() {
+  if (!detail.value || !canCorrectTransport.value) return
+  editForm.containerNo = detail.value.summary.containerNo || ''
+  editForm.voyageNo = detail.value.summary.voyageNo || ''
+  editForm.operationReason = ''
+  editError.value = null
+  editOpen.value = true
+}
+
+async function saveTransport() {
+  if (!detail.value || !canCorrectTransport.value || !(await editFormRef.value?.validate().catch(() => false))) return
+  const correcting = isContainerCorrection.value
+  editForm.containerNo = normalizedContainerNo(editForm.containerNo)
+  editSaving.value = true
+  editError.value = null
+  try {
+    detail.value = await updatePreloadTransport(planId.value, warehouseId.value, {
+      containerNo: editForm.containerNo,
+      voyageNo: editForm.voyageNo.trim() || null,
+      operationReason: editForm.operationReason.trim() || null,
+      expectedVersion: detail.value.summary.version,
+    })
+    editOpen.value = false
+    ElMessage.success(correcting ? '运输信息已纠正' : '真实集装箱号已补录')
+  } catch (cause) {
+    const details = getApiErrorDetails(cause, '运输信息保存失败，请刷新详情后重试')
+    if (details.code === 'A0409' || /版本|并发|已被其他人修改/.test(details.message)) {
+      await loadDetail()
+      editError.value = { ...details, message: '运输信息已被其他人修改，系统已刷新最新版本；当前输入已保留，请核对后重新保存。' }
+    } else editError.value = details
+  } finally {
+    editSaving.value = false
+  }
+}
+
+function openRemarks(item: LoadingItem) {
+  if (!canEdit.value || !detail.value || !['EDITING', 'LOADING'].includes(detail.value.summary.status)) return
+  remarkTarget.value = item
+  remarkForm.internalRemark = item.internalRemark || ''
+  remarkForm.warehouseRemark = item.warehouseRemark || ''
+  remarkForm.customerServiceRemark = item.customerServiceRemark || ''
+  remarkError.value = null
+  remarkOperationId.value = `admin-preload-remarks-${detail.value.summary.planId}-${item.itemId}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`
+  remarkOpen.value = true
+}
+
+async function saveRemarks() {
+  const target = remarkTarget.value
+  const current = detail.value
+  if (!target || !current || !canEdit.value || remarkSaving.value) return
+  if (Object.values(remarkForm).some((value) => value.length > 1000)) {
+    remarkError.value = { code: 'REMARK_TOO_LONG', message: '每项备注不能超过 1000 个字符' }
+    return
+  }
+  remarkSaving.value = true
+  remarkError.value = null
+  try {
+    const result = await updateLoadingItemRemarks(current.summary.planId, target.itemId, {
+      internalRemark: remarkForm.internalRemark.trim() || null,
+      warehouseRemark: remarkForm.warehouseRemark.trim() || null,
+      customerServiceRemark: remarkForm.customerServiceRemark.trim() || null,
+      expectedPlanVersion: current.summary.version,
+      expectedItemVersion: target.itemVersion,
+      operationId: remarkOperationId.value,
+    })
+    const updatedItem = result.items.find((item) => item.id === target.itemId)
+    detail.value = {
+      ...current,
+      summary: { ...current.summary, version: result.version },
+      items: current.items.map((item) => item.itemId === target.itemId
+        ? { ...item, itemVersion: updatedItem?.version ?? item.itemVersion,
+            internalRemark: updatedItem?.internalRemark ?? null,
+            warehouseRemark: updatedItem?.warehouseRemark ?? null,
+            customerServiceRemark: updatedItem?.customerServiceRemark ?? null }
+        : item),
+    }
+    remarkOpen.value = false
+    remarkTarget.value = null
+    remarkOperationId.value = ''
+    ElMessage.success('备注已更新')
+  } catch (cause) {
+    const details = getApiErrorDetails(cause, '备注保存失败，请稍后重试')
+    if (details.code === 'A0409' || /版本|并发|状态.*变化/.test(details.message)) {
+      await loadDetail()
+      remarkTarget.value = detail.value?.items.find((item) => item.itemId === target.itemId) || target
+      remarkError.value = { ...details, message: '计划状态或明细版本已变化，系统已刷新最新数据；当前输入已保留，请核对后重新保存。' }
+    } else remarkError.value = details
+  } finally {
+    remarkSaving.value = false
+  }
+}
+
+function openConfirmPreload() {
+  const summary = detail.value?.summary
+  if (!canEdit.value || !summary?.readiness.canConfirm) return
+  confirmError.value = null
+  confirmOperationId.value = `admin-preload-confirm-${summary.planId}-${summary.version}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`
+  confirmOpen.value = true
+}
+
+async function submitConfirmPreload() {
+  const summary = detail.value?.summary
+  if (!summary?.readiness.canConfirm || confirmSaving.value) return
+  confirmSaving.value = true
+  confirmError.value = null
+  try {
+    const result = await confirmPreloadPlan(summary.planId, summary.version, confirmOperationId.value)
+    await loadDetail()
+    confirmOpen.value = false
+    confirmOperationId.value = ''
+    ElMessage.success(result.readiness.readyForPda ? '预装已确认，PDA 任务已具备下发条件' : '预装已确认')
+  } catch (cause) {
+    confirmError.value = getApiErrorDetails(cause, '确认预装失败，请稍后重试')
+  } finally {
+    confirmSaving.value = false
+  }
+}
+
+onMounted(() => void loadDetail())
+watch([planId, warehouseId], () => void loadDetail())
+</script>
+
+<template>
+  <AdminPage>
+    <div class="preload-detail-page admin-density">
+      <OperationErrorToast :details="remarkError || editError || confirmError" />
+      <LoadingListDetailDrawer :mode="'preload'" :loading="loading" :detail="detail" :error="error" :can-edit="canEdit" :can-edit-transport="canCorrectTransport" :transport-note="transportCorrectionNote" :confirm-saving="confirmSaving" @back="goBack" @retry="loadDetail" @edit="openEdit" @edit-remarks="openRemarks" @confirm-preload="openConfirmPreload" />
+    </div>
+
+    <AppDialog v-model="editOpen" class="loading-transport-dialog admin-density-dialog" :title="editDialogTitle" width="min(620px, calc(100vw - 28px))" confirm-text="保存" :confirm-loading="editSaving" :confirm-disabled="!canEdit" @confirm="saveTransport">
+      <el-form ref="editFormRef" class="transport-form" :model="editForm" :rules="editRules" label-position="top">
+        <el-form-item label="真实集装箱号" prop="containerNo"><el-input v-model="editForm.containerNo" maxlength="64" placeholder="请输入提柜后取得的真实集装箱号" @blur="editForm.containerNo = normalizedContainerNo(editForm.containerNo)" /></el-form-item>
+        <el-form-item label="航次" prop="voyageNo"><el-input v-model="editForm.voyageNo" maxlength="64" placeholder="请输入航次" /></el-form-item>
+        <el-form-item :label="isContainerCorrection ? '纠错原因' : '操作原因（可选）'" prop="operationReason"><el-input v-model="editForm.operationReason" type="textarea" :rows="3" maxlength="500" :placeholder="isContainerCorrection ? '必填，将记录在操作历史中' : '可填写补录说明'" /></el-form-item>
+      </el-form>
+    </AppDialog>
+
+    <AppDialog v-model="remarkOpen" class="remarks-dialog admin-density-dialog" title="编辑备注" width="min(680px, calc(100vw - 28px))" confirm-text="保存备注" cancel-text="取消" :confirm-loading="remarkSaving" :confirm-disabled="!canEdit" @confirm="saveRemarks">
+      <el-alert type="info" :closable="false" show-icon title="客户备注来自客户下单且不可修改；其余备注可维护" />
+      <el-form label-position="top" class="remarks-form">
+        <el-form-item label="客户备注（只读）"><el-input :model-value="remarkTarget?.customerRemark || '—'" disabled /><small>来源：客户下单</small></el-form-item>
+        <el-form-item label="内部备注"><el-input v-model="remarkForm.internalRemark" type="textarea" :rows="3" maxlength="1000" show-word-limit placeholder="可填写、修改或清空内部备注" /></el-form-item>
+        <el-form-item label="仓库备注"><el-input v-model="remarkForm.warehouseRemark" type="textarea" :rows="3" maxlength="1000" show-word-limit placeholder="可填写、修改或清空仓库备注" /></el-form-item>
+        <el-form-item label="客服备注"><el-input v-model="remarkForm.customerServiceRemark" type="textarea" :rows="3" maxlength="1000" show-word-limit placeholder="可填写、修改或清空客服备注" /></el-form-item>
+      </el-form>
+      <LoadErrorState v-if="remarkError" compact title="备注保存失败" :message="remarkError.message" :show-retry="false"><template #details><ApiErrorMeta :details="remarkError" /></template></LoadErrorState>
+    </AppDialog>
+
+    <AppDialog v-model="confirmOpen" class="preload-confirm-dialog admin-density-dialog" title="确认整份预装计划" width="min(520px, calc(100vw - 28px))" confirm-text="确认预装" :confirm-loading="confirmSaving" :confirm-disabled="!detail?.summary.readiness.canConfirm" @confirm="submitConfirmPreload">
+      <div class="confirm-content">
+        <el-alert type="warning" :closable="false" show-icon title="本操作将确认整份预装计划" />
+        <el-descriptions v-if="detail" :column="1" border>
+          <el-descriptions-item label="预装单号">{{ detail.summary.preloadNo }}</el-descriptions-item>
+          <el-descriptions-item label="柜次号">{{ detail.summary.cabinetNo || '—' }}</el-descriptions-item>
+          <el-descriptions-item label="集装箱号">{{ detail.summary.containerNo || '待补录' }}</el-descriptions-item>
+        </el-descriptions>
+      </div>
+    </AppDialog>
+  </AdminPage>
+</template>
+
+<style scoped>
+.preload-detail-page { display: grid; min-width: 0; width: 100%; gap: var(--admin-space-5, 12px); }
+.transport-form { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 0 var(--admin-space-6, 16px); }
+.transport-form :deep(.el-form-item:last-child) { grid-column: 1 / -1; }
+.confirm-content { display: grid; gap: var(--admin-space-5, 12px); }
+.remarks-form { margin-top: 14px; }
+.remarks-form small { display: block; margin-top: var(--admin-space-1, 4px); color: var(--cc-muted); }
+:global(.loading-transport-dialog.el-dialog) { max-height: 90vh; overflow: hidden; }
+@media (min-width: 1920px) { .preload-detail-page { width: 100%; max-width: none; gap: var(--admin-space-5, 12px); } }
+@media (max-width: 720px) { .transport-form { grid-template-columns: 1fr; } .transport-form :deep(.el-form-item:last-child) { grid-column: auto; } }
+</style>
diff --git a/src/modules/loading-lists/pages/PreloadPlansView.vue b/src/modules/loading-lists/pages/PreloadPlansView.vue
new file mode 100644
index 00000000..805d6112
--- /dev/null
+++ b/src/modules/loading-lists/pages/PreloadPlansView.vue
@@ -0,0 +1,5 @@
+<script setup lang="ts">
+import LoadingListsView from '../components/LoadingListsView.vue'
+</script>
+
+<template><LoadingListsView mode="preload" /></template>
diff --git a/src/modules/loading-lists/routes.test.ts b/src/modules/loading-lists/routes.test.ts
new file mode 100644
index 00000000..0f4d7cbf
--- /dev/null
+++ b/src/modules/loading-lists/routes.test.ts
@@ -0,0 +1,11 @@
+import { describe, expect, it } from 'vitest'
+import { loadingListRoutes } from './routes'
+
+describe('loading list routes', () => {
+  it('keeps completed loading lists inside domestic container detail', () => {
+    expect(loadingListRoutes.map((route) => [route.path, route.meta.permission])).toEqual([
+      ['loading-plans', 'platform:firstleg:preload:list'],
+      ['loading-plans/:planId', 'platform:firstleg:preload:list'],
+    ])
+  })
+})
diff --git a/src/modules/loading-lists/routes.ts b/src/modules/loading-lists/routes.ts
new file mode 100644
index 00000000..9f836197
--- /dev/null
+++ b/src/modules/loading-lists/routes.ts
@@ -0,0 +1,24 @@
+import type { RouteRecordRaw } from 'vue-router'
+
+export const loadingListRoutes = [
+  {
+    path: 'loading-plans',
+    name: 'loading-plans',
+    component: () => import('./pages/PreloadPlansView.vue'),
+    meta: {
+      title: '预装清单',
+      description: '查看全部仓库拣货中的预装计划、货物明细和操作历史',
+      permission: 'platform:firstleg:preload:list',
+    },
+  },
+  {
+    path: 'loading-plans/:planId',
+    name: 'preload-plan-detail',
+    component: () => import('./pages/PreloadPlanDetailView.vue'),
+    meta: {
+      title: '预装清单详情',
+      description: '查看预装清单基本信息、装柜货物明细和操作历史',
+      permission: 'platform:firstleg:preload:list',
+    },
+  },
+] satisfies RouteRecordRaw[]
diff --git a/src/modules/loading-lists/status.test.ts b/src/modules/loading-lists/status.test.ts
new file mode 100644
index 00000000..571fb044
--- /dev/null
+++ b/src/modules/loading-lists/status.test.ts
@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest'
+import { mount } from '@vue/test-utils'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import { loadingListStatusLabel } from './status'
+
+describe('loading list status labels', () => {
+  it.each([
+    ['WAIT_LOADING', '待装柜', 'warning'],
+    ['EDITING', '预装柜中', 'warning'],
+    ['LOADING', '拣货中', 'info'],
+    ['COMPLETED', '装柜完成', 'success'],
+    ['NEW_LOADING_STATE', '未知状态', 'neutral'],
+  ])('renders %s with its shared status tone', (status, label, tone) => {
+    const wrapper = mount(StatusBadge, { props: { status: loadingListStatusLabel(status) } })
+    expect(wrapper.text()).toBe(label)
+    expect(wrapper.classes()).toContain(`is-${tone}`)
+    wrapper.unmount()
+  })
+
+  it('translates known states and hides unknown backend enums', () => {
+    expect(loadingListStatusLabel('EDITING')).toBe('预装柜中')
+    expect(loadingListStatusLabel('COMPLETED')).toBe('装柜完成')
+    expect(loadingListStatusLabel('NEW_LOADING_STATE')).toBe('未知状态')
+    expect(loadingListStatusLabel(null)).toBe('—')
+  })
+})
diff --git a/src/modules/loading-lists/status.ts b/src/modules/loading-lists/status.ts
new file mode 100644
index 00000000..f83c3a3c
--- /dev/null
+++ b/src/modules/loading-lists/status.ts
@@ -0,0 +1,11 @@
+const loadingListStatusLabels: Record<string, string> = {
+  WAIT_LOADING: '待装柜',
+  EDITING: '预装柜中',
+  LOADING: '拣货中',
+  COMPLETED: '装柜完成',
+}
+
+export function loadingListStatusLabel(status: string | null | undefined) {
+  if (!status) return '—'
+  return loadingListStatusLabels[status] || '未知状态'
+}
diff --git a/src/modules/master-data/counterparties/api/platformPartners.test.ts b/src/modules/master-data/counterparties/api/platformPartners.test.ts
new file mode 100644
index 00000000..935308b8
--- /dev/null
+++ b/src/modules/master-data/counterparties/api/platformPartners.test.ts
@@ -0,0 +1,92 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import {
+  changePlatformPartnerStatus,
+  createPlatformPartner,
+  downloadPlatformPartnerImportTemplate,
+  getPlatformPartner,
+  importPlatformPartners,
+  listPlatformPartners,
+  updatePlatformPartner,
+  type SavePlatformPartnerRequest,
+} from './platformPartners'
+
+vi.mock('@/shared/api/http', () => ({
+  http: { get: vi.fn(), post: vi.fn(), put: vi.fn(), patch: vi.fn() },
+  unwrapApiResponse: <T>(response: { data: T }) => response.data,
+}))
+
+const payload: SavePlatformPartnerRequest = {
+  partnerCode: 'CUS-001',
+  partnerName: '测试往来单位',
+  partnerType: 'SHIPPER',
+  types: ['SHIPPER'],
+  carrierCode: null,
+  contactName: '测试联系人',
+  contactPhone: '13800000000',
+  contactEmail: null,
+  countryCode: 'CN',
+  province: '广东省',
+  city: '深圳市',
+  district: null,
+  addressLine: '测试地址 1 号',
+  postalCode: null,
+  status: 'ACTIVE',
+  remark: '测试档案',
+}
+
+describe('platform partner API', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it('queries the platform partner page with filters only', async () => {
+    vi.mocked(http.get).mockResolvedValue({ code: '200', message: 'success', data: { records: [], page: '1', size: '20', total: '1', pages: '1' } })
+
+    const result = await listPlatformPartners({ page: 1, size: 20, keyword: '测试', type: 'SHIPPER', status: 'ACTIVE' })
+
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/partners', {
+      params: { page: 1, size: 20, keyword: '测试', type: 'SHIPPER', status: 'ACTIVE' },
+    })
+    expect(result).toMatchObject({ page: 1, size: 20, total: 1, pages: 1 })
+  })
+
+  it('uses the backend create, update and status contracts', async () => {
+    vi.mocked(http.post).mockResolvedValue({ code: '200', message: 'success', data: '19001' })
+    vi.mocked(http.put).mockResolvedValue({ code: '200', message: 'success', data: null })
+    vi.mocked(http.patch).mockResolvedValue({ code: '200', message: 'success', data: null })
+
+    await createPlatformPartner(payload)
+    await updatePlatformPartner('19001', payload)
+    await changePlatformPartnerStatus('19001', 'INACTIVE')
+
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/partners', payload, { params: { tenantId: 0 } })
+    expect(http.put).toHaveBeenCalledWith('/platform/v1/partners/19001', payload, { params: { tenantId: 0 } })
+    expect(http.patch).toHaveBeenCalledWith('/platform/v1/partners/19001/status', { status: 'INACTIVE' }, { params: { tenantId: 0 } })
+  })
+
+  it('normalizes legacy detail types and uses import contracts', async () => {
+    vi.mocked(http.get)
+      .mockResolvedValueOnce({ code: '200', message: 'success', data: {
+        id: '19001', tenantId: 0, dataScopeId: 0, partnerCode: 'CUS-001', partnerName: '测试单位',
+        partnerType: 'CONSIGNEE', carrierCode: null, contactName: '张三', contactPhone: '13800000000', contactEmail: null,
+        countryCode: 'CN', province: null, city: '深圳市', district: null, addressLine: '测试地址',
+        postalCode: null, status: 'ACTIVE',
+      } })
+      .mockResolvedValueOnce(new Blob(['template']))
+    vi.mocked(http.post).mockResolvedValue({ code: '200', message: 'success', data: {
+      fileName: 'partners.xlsx', totalRows: 1, importedRows: 1, success: true, errors: [],
+    } })
+
+    const detail = await getPlatformPartner('19001')
+    const template = await downloadPlatformPartnerImportTemplate()
+    const file = new File(['xlsx'], 'partners.xlsx')
+    const result = await importPlatformPartners(file)
+
+    expect(detail.types).toEqual(['CONSIGNEE'])
+    expect(detail.dataScopeId).toBe(0)
+    expect(template).toBeInstanceOf(Blob)
+    expect(result.success).toBe(true)
+    expect(http.get).toHaveBeenNthCalledWith(1, '/platform/v1/partners/19001', { params: { tenantId: 0 } })
+    expect(http.get).toHaveBeenNthCalledWith(2, '/platform/v1/partners/import-template', { responseType: 'blob' })
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/partners/import', expect.any(FormData), { params: { tenantId: 0 } })
+  })
+})
diff --git a/src/modules/master-data/counterparties/api/platformPartners.ts b/src/modules/master-data/counterparties/api/platformPartners.ts
new file mode 100644
index 00000000..8a772dbb
--- /dev/null
+++ b/src/modules/master-data/counterparties/api/platformPartners.ts
@@ -0,0 +1,163 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+
+export type PlatformPartnerType = 'CARRIER' | 'SHIPPER' | 'CONSIGNEE'
+export type PlatformPartnerStatus = 'ACTIVE' | 'INACTIVE'
+export type PlatformPartnerCarrierCode = 'MATSON' | 'SML' | 'ZIM' | 'COSCO' | 'EMC' | 'HEDE' | 'OTHER'
+
+export interface PlatformPartnerResource {
+  id: number | string
+  tenantId: number | string
+  dataScopeId: number | string
+  partnerCode: string
+  partnerName: string
+  partnerType: PlatformPartnerType
+  types: PlatformPartnerType[]
+  carrierCode: PlatformPartnerCarrierCode | null
+  contactName: string
+  contactPhone: string
+  contactEmail: string | null
+  countryCode: string
+  province: string | null
+  city: string
+  district: string | null
+  addressLine: string
+  postalCode: string | null
+  status: PlatformPartnerStatus
+  remark: string | null
+  createdAt?: string | null
+  updatedAt?: string | null
+}
+
+export interface PlatformPartnerPage {
+  records: PlatformPartnerResource[]
+  page: number
+  size: number
+  total: number
+  pages: number
+}
+
+type PlatformPartnerPagePayload = Omit<PlatformPartnerPage, 'page' | 'size' | 'total' | 'pages'> & {
+  page: number | string
+  size: number | string
+  total: number | string
+  pages: number | string
+}
+
+export interface PlatformPartnerQuery {
+  page: number
+  size: number
+  keyword?: string
+  type?: PlatformPartnerType
+  status?: PlatformPartnerStatus
+}
+
+export interface SavePlatformPartnerRequest {
+  partnerCode: string
+  partnerName: string
+  partnerType: PlatformPartnerType
+  types: PlatformPartnerType[]
+  carrierCode: PlatformPartnerCarrierCode | null
+  contactName: string
+  contactPhone: string
+  contactEmail: string | null
+  countryCode: string
+  province: string | null
+  city: string
+  district: string | null
+  addressLine: string
+  postalCode: string | null
+  status: PlatformPartnerStatus
+  remark: string | null
+}
+
+export interface PlatformPartnerImportError {
+  row: number
+  field: string
+  message: string
+}
+
+export interface PlatformPartnerImportResult {
+  fileName: string
+  totalRows: number
+  importedRows: number
+  success: boolean
+  errors: PlatformPartnerImportError[]
+}
+
+const basePath = '/platform/v1/partners'
+const platformResourceScope = 0
+
+function normalizePartner(resource: PlatformPartnerResource): PlatformPartnerResource {
+  return {
+    ...resource,
+    dataScopeId: resource.dataScopeId ?? resource.tenantId,
+    types: resource.types?.length ? resource.types : [resource.partnerType],
+    carrierCode: resource.carrierCode ?? null,
+    remark: resource.remark ?? null,
+  }
+}
+
+export async function listPlatformPartners(query: PlatformPartnerQuery) {
+  const response = await http.get<ApiEnvelope<PlatformPartnerPagePayload>, ApiEnvelope<PlatformPartnerPagePayload>>(basePath, {
+    params: query,
+  })
+  const page = unwrapApiResponse(response)
+  return {
+    ...page,
+    records: page.records.map(normalizePartner),
+    page: Number(page.page),
+    size: Number(page.size),
+    total: Number(page.total),
+    pages: Number(page.pages),
+  }
+}
+
+export async function getPlatformPartner(partnerId: number | string) {
+  const response = await http.get<ApiEnvelope<PlatformPartnerResource>, ApiEnvelope<PlatformPartnerResource>>(
+    `${basePath}/${partnerId}`,
+    { params: { tenantId: platformResourceScope } },
+  )
+  return normalizePartner(unwrapApiResponse(response))
+}
+
+export async function downloadPlatformPartnerImportTemplate() {
+  return http.get<Blob, Blob>(`${basePath}/import-template`, { responseType: 'blob' })
+}
+
+export async function importPlatformPartners(file: File) {
+  const form = new FormData()
+  form.append('file', file)
+  const response = await http.post<ApiEnvelope<PlatformPartnerImportResult>, ApiEnvelope<PlatformPartnerImportResult>>(
+    `${basePath}/import`,
+    form,
+    { params: { tenantId: platformResourceScope } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function createPlatformPartner(payload: SavePlatformPartnerRequest) {
+  const response = await http.post<ApiEnvelope<number | string>, ApiEnvelope<number | string>>(basePath, payload, {
+    params: { tenantId: platformResourceScope },
+  })
+  return unwrapApiResponse(response)
+}
+
+export async function updatePlatformPartner(
+  partnerId: number | string,
+  payload: SavePlatformPartnerRequest,
+) {
+  const response = await http.put<ApiEnvelope<null>, ApiEnvelope<null>>(`${basePath}/${partnerId}`, payload, {
+    params: { tenantId: platformResourceScope },
+  })
+  return unwrapApiResponse(response)
+}
+
+export async function changePlatformPartnerStatus(
+  partnerId: number | string,
+  status: PlatformPartnerStatus,
+) {
+  const response = await http.patch<ApiEnvelope<null>, ApiEnvelope<null>>(`${basePath}/${partnerId}/status`, { status }, {
+    params: { tenantId: platformResourceScope },
+  })
+  return unwrapApiResponse(response)
+}
diff --git a/src/modules/master-data/counterparties/index.ts b/src/modules/master-data/counterparties/index.ts
new file mode 100644
index 00000000..0ef47b12
--- /dev/null
+++ b/src/modules/master-data/counterparties/index.ts
@@ -0,0 +1 @@
+export * from './api/platformPartners'
diff --git a/src/modules/master-data/counterparties/pages/PartnersView.test.ts b/src/modules/master-data/counterparties/pages/PartnersView.test.ts
new file mode 100644
index 00000000..aaac30ce
--- /dev/null
+++ b/src/modules/master-data/counterparties/pages/PartnersView.test.ts
@@ -0,0 +1,289 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import ElementPlus from 'element-plus'
+import { createPinia, setActivePinia } from 'pinia'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  getPlatformPartner,
+  listPlatformPartners,
+  type PlatformPartnerResource,
+} from '@/modules/master-data/counterparties/api/platformPartners'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+import QueryToolbar from '@/shared/components/QueryToolbar.vue'
+import PartnersView from './PartnersView.vue'
+
+const source = readFileSync(join(process.cwd(), 'src/modules/master-data/counterparties/pages/PartnersView.vue'), 'utf8')
+
+vi.mock('@/modules/master-data/counterparties/api/platformPartners', () => ({
+  listPlatformPartners: vi.fn(),
+  createPlatformPartner: vi.fn(),
+  getPlatformPartner: vi.fn(),
+  downloadPlatformPartnerImportTemplate: vi.fn(),
+  importPlatformPartners: vi.fn(),
+  updatePlatformPartner: vi.fn(),
+  changePlatformPartnerStatus: vi.fn(),
+}))
+
+class ResizeObserverStub implements ResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+
+function createMemoryStorage(): Storage {
+  const values = new Map<string, string>()
+  return {
+    get length() { return values.size },
+    clear: () => values.clear(),
+    getItem: (key) => values.get(key) ?? null,
+    key: (index) => [...values.keys()][index] ?? null,
+    removeItem: (key) => values.delete(key),
+    setItem: (key, value) => values.set(key, value),
+  }
+}
+
+const partner: PlatformPartnerResource = {
+  id: '19001',
+  tenantId: 0,
+  dataScopeId: 0,
+  partnerCode: 'SHP-001',
+  partnerName: '深圳示例贸易有限公司',
+  partnerType: 'SHIPPER',
+  types: ['SHIPPER'],
+  carrierCode: null,
+  contactName: '张三',
+  contactPhone: '13800138000',
+  contactEmail: 'contact@example.com',
+  countryCode: 'CN',
+  province: '广东省',
+  city: '深圳市',
+  district: '宝安区',
+  addressLine: '航城街道示例路 1 号',
+  postalCode: '518000',
+  status: 'ACTIVE',
+  remark: '长期合作单位',
+  updatedAt: '2026-07-30T22:45:00',
+}
+
+async function mountView() {
+  vi.stubGlobal('localStorage', createMemoryStorage())
+  vi.stubGlobal('sessionStorage', createMemoryStorage())
+  const pinia = createPinia()
+  setActivePinia(pinia)
+  const auth = useAuthStore()
+  auth.token = 'token'
+  auth.permissions = [
+    'platform:counterparty:list',
+    'platform:counterparty:create',
+    'platform:counterparty:edit',
+    'platform:counterparty:status',
+  ]
+  useAccessPreviewStore().initializeAfterLogin()
+  const wrapper = mount(PartnersView, {
+    attachTo: document.body,
+    global: { plugins: [pinia, ElementPlus] },
+  })
+  await flushPromises()
+  return wrapper
+}
+
+enableAutoUnmount(afterEach)
+afterAll(() => vi.unstubAllGlobals())
+
+describe('PartnersView real API integration', () => {
+  it('clamps long unit names with the shared component', () => {
+    expect(source).toContain("LineClampText from '@/shared/components/LineClampText.vue'")
+    expect(source).toContain('<LineClampText :content="(row as PlatformPartnerResource).partnerName" />')
+    expect(source).not.toContain('.partner-cell strong')
+  })
+
+  it('keeps operation first and separates the prototype contact columns', () => {
+    const actionsIndex = source.indexOf("{ key: 'actions', label: '操作'")
+    const nameIndex = source.indexOf("{ key: 'partner', label: '单位名称'")
+    const typeIndex = source.indexOf("{ key: 'type', label: '类型'")
+    const contactIndex = source.indexOf("{ key: 'contact', prop: 'contactName', label: '联系人'")
+    const phoneIndex = source.indexOf("{ key: 'contactPhone', prop: 'contactPhone', label: '电话'")
+    expect([actionsIndex, nameIndex, typeIndex, contactIndex, phoneIndex].every((index) => index >= 0)).toBe(true)
+    expect(actionsIndex).toBeLessThan(nameIndex)
+    expect(nameIndex).toBeLessThan(typeIndex)
+    expect(typeIndex).toBeLessThan(contactIndex)
+    expect(contactIndex).toBeLessThan(phoneIndex)
+    expect(source).toContain("{ key: 'partnerCode', prop: 'partnerCode', label: '单位编码', minWidth: 130, defaultVisible: false }")
+    expect(source).toContain("{ key: 'contactEmail', prop: 'contactEmail', label: '邮箱', minWidth: 190, defaultVisible: false")
+  })
+  beforeEach(() => {
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+    document.body.innerHTML = ''
+    vi.mocked(listPlatformPartners).mockReset().mockResolvedValue({
+      records: [partner], page: 1, size: 20, total: 1, pages: 1,
+    })
+    vi.mocked(getPlatformPartner).mockReset().mockResolvedValue(partner)
+  })
+
+  it('loads platform partner data and renders the real partner fields', async () => {
+    const wrapper = await mountView()
+
+    expect(listPlatformPartners).toHaveBeenCalledWith({
+      page: 1, size: 20, keyword: undefined, type: undefined, status: undefined,
+    })
+    expect(wrapper.find('input[aria-label="所属企业"]').exists()).toBe(false)
+    expect(wrapper.text()).toContain('平台公共数据 · 共 1 个往来单位')
+    expect(wrapper.text()).toContain('深圳示例贸易有限公司')
+    expect(wrapper.find('.data-table').text()).toContain('13800138000')
+    expect(wrapper.find('.data-table').text()).not.toContain('CUS-001')
+    expect(wrapper.find('.data-table').text()).not.toContain('contact@example.com')
+    expect(wrapper.find('.data-table').text()).not.toContain('广东省 深圳市 宝安区 航城街道示例路 1 号')
+    expect(wrapper.text()).not.toContain('往来单位总数')
+    expect(wrapper.text()).not.toContain('往来单位档案')
+    expect(wrapper.find('.query-toolbar').exists()).toBe(true)
+    expect(wrapper.find('.data-table').exists()).toBe(true)
+    expect(wrapper.find('.table-panel').exists()).toBe(true)
+    expect(wrapper.find('.query-toolbar__actions').text()).not.toContain('新增往来单位')
+    expect(wrapper.find('.data-table__business-actions').text()).toContain('新增往来单位')
+    expect(wrapper.find('.data-table__toolbar-start').exists()).toBe(false)
+    expect(wrapper.find('.data-table__pagination-left').text()).toContain('平台公共数据 · 共 1 个往来单位')
+    expect(wrapper.find('.list-page-layout__state').exists()).toBe(false)
+    const detailButton = wrapper.findAll('button').find((button) => button.text().trim() === '详情')
+    await detailButton?.trigger('click')
+    await flushPromises()
+    expect(document.body.textContent).toContain('广东省 深圳市 宝安区 航城街道示例路 1 号')
+  })
+
+  it('opens the create form without selecting an enterprise', async () => {
+    const wrapper = await mountView()
+    const createButton = wrapper.findAll('button').find((button) => button.text().trim() === '新增往来单位')
+    await createButton?.trigger('click')
+    await flushPromises()
+
+    expect(document.body.textContent).toContain('新增往来单位')
+    expect(document.body.textContent).not.toContain('请先在筛选条件中选择所属企业')
+    expect(document.body.textContent).toContain('船公司')
+    expect(document.body.textContent).toContain('发货单位')
+    expect(document.body.textContent).toContain('收货单位')
+    expect(document.body.textContent).not.toContain('报关行')
+    expect(document.body.textContent).not.toContain('供应商')
+  })
+
+  it('uses the fixed carrier-code selector when the unit is a shipping company', async () => {
+    const wrapper = await mountView()
+    await wrapper.findAll('button').find((button) => button.text().trim() === '新增往来单位')?.trigger('click')
+    await flushPromises()
+    const typeSelect = wrapper.findAllComponents({ name: 'ElSelect' }).find((select) => select.props('multiple'))
+    typeSelect!.vm.$emit('update:modelValue', ['CARRIER'])
+    await flushPromises()
+
+    expect(document.body.textContent).toContain('船司标准编码')
+    const carrierValues = new Set(['MATSON', 'SML', 'ZIM', 'COSCO', 'EMC', 'HEDE', 'OTHER'])
+    const carrierOptions = wrapper.findAllComponents({ name: 'ElOption' }).filter((option) => carrierValues.has(String(option.props('value'))))
+    expect(carrierOptions.map((option) => option.props('value'))).toEqual(['MATSON', 'SML', 'ZIM', 'COSCO', 'EMC', 'HEDE', 'OTHER'])
+    expect(carrierOptions.map((option) => option.props('label'))).toContain('美森 (MATSON)')
+    expect(source).toContain('placeholder="请选择船司标准编码"')
+    expect(source).toContain("MATSON: '美森'")
+    expect(source).toContain("OTHER: '其他'")
+    expect(source).toContain("carrierCode: types.includes('CARRIER') ? form.carrierCode : null")
+  })
+
+  it('renders a padded detail layout without an empty data-scope cell', async () => {
+    const wrapper = await mountView()
+    const detailButton = wrapper.findAll('button').find((button) => button.text().trim() === '详情')
+    await detailButton?.trigger('click')
+    await flushPromises()
+
+    const detailContent = document.querySelector<HTMLElement>('.detail-drawer .partner-detail')
+    const sections = detailContent?.querySelectorAll('section')
+    const otherInfo = sections?.item(sections.length - 1)
+    expect(detailContent).not.toBeNull()
+    expect(detailContent?.closest('.el-drawer')?.classList.contains('admin-density-drawer')).toBe(true)
+    expect(detailContent?.querySelectorAll('.density-fields')).toHaveLength(3)
+    expect(otherInfo?.querySelectorAll('.detail-grid > .detail-span')).toHaveLength(2)
+    expect(otherInfo?.textContent).toContain('更新时间')
+    expect(otherInfo?.textContent).toContain('长期合作单位')
+    expect(document.body.textContent).not.toContain('数据范围')
+  })
+
+  it('updates filters locally and only requests after search', async () => {
+    const wrapper = await mountView()
+    const keywordInput = wrapper.find('input[placeholder="请输入往来单位名称"]')
+
+    await keywordInput.setValue('深圳')
+    await flushPromises()
+    expect(listPlatformPartners).toHaveBeenCalledTimes(1)
+
+    const searchButton = wrapper.findAll('button').find((button) => button.text().trim() === '查询')
+    expect(searchButton).toBeDefined()
+    await searchButton?.trigger('click')
+    await flushPromises()
+
+    expect(listPlatformPartners).toHaveBeenCalledTimes(2)
+    expect(listPlatformPartners).toHaveBeenLastCalledWith({
+      page: 1, size: 20, keyword: '深圳', type: undefined, status: undefined,
+    })
+  })
+
+  it('shows useful placeholders and visible required markers in the create form', async () => {
+    const wrapper = await mountView()
+    const toolbar = wrapper.findComponent(QueryToolbar)
+    const model = { keyword: '', type: '', status: '' }
+    toolbar.vm.$emit('update:modelValue', model)
+    toolbar.vm.$emit('search', model)
+    await flushPromises()
+    const createButton = wrapper.findAll('button').find((button) => button.text().trim() === '新增往来单位')
+    expect(createButton).toBeDefined()
+    await createButton?.trigger('click')
+    await flushPromises()
+
+    expect(document.querySelector('input[placeholder="请输入工商登记或常用单位名称"]')).not.toBeNull()
+    expect(document.querySelector('input[placeholder="请输入主要联系人姓名"]')).not.toBeNull()
+    expect(document.querySelector('textarea[placeholder="请输入街道、园区、楼栋及门牌信息"]')).not.toBeNull()
+    expect(document.querySelectorAll('.el-form-item.is-required').length).toBe(9)
+  })
+
+  it('shows a recoverable API failure without demo data', async () => {
+    vi.mocked(listPlatformPartners).mockRejectedValueOnce(new Error('Gateway unavailable'))
+    const wrapper = await mountView()
+
+    expect(wrapper.text()).toContain('往来单位列表暂时无法加载')
+    expect(wrapper.text()).not.toContain('Gateway unavailable')
+    expect(wrapper.text()).toContain('重新加载')
+    expect(wrapper.text()).not.toContain('深圳示例贸易有限公司')
+    expect(wrapper.find('.list-page-layout__state').exists()).toBe(true)
+    expect(wrapper.find('.table-panel').exists()).toBe(false)
+  })
+
+  it('keeps the latest detail when an older partner request finishes last', async () => {
+    const secondPartner = { ...partner, id: '19002', partnerCode: 'CUS-002', partnerName: '上海示例贸易有限公司' }
+    let resolveFirst!: (value: PlatformPartnerResource) => void
+    let resolveSecond!: (value: PlatformPartnerResource) => void
+    vi.mocked(getPlatformPartner).mockImplementation((partnerId) => new Promise((resolve) => {
+      if (String(partnerId) === String(partner.id)) resolveFirst = resolve
+      else resolveSecond = resolve
+    }))
+    const wrapper = await mountView()
+    const vm = wrapper.vm as unknown as {
+      detailOpen: boolean
+      detail: PlatformPartnerResource | null
+      openDetail(row: PlatformPartnerResource): Promise<void>
+    }
+
+    void vm.openDetail(partner)
+    vm.detailOpen = false
+    await wrapper.vm.$nextTick()
+    void vm.openDetail(secondPartner)
+    resolveSecond(secondPartner)
+    await flushPromises()
+    resolveFirst(partner)
+    await flushPromises()
+
+    expect(vm.detail?.partnerCode).toBe('CUS-002')
+  })
+
+  it('keeps all three row actions visible without a premature more menu', () => {
+    const actions = source.slice(source.indexOf('<template #actions='), source.indexOf('</template>', source.indexOf('<template #actions=')))
+    expect(actions.match(/class="density-action"/g)).toHaveLength(3)
+    expect(actions).toContain('>详情</el-button>')
+    expect(actions).toContain('>编辑</el-button>')
+    expect(actions).toContain(':data-tone=')
+    expect(actions).not.toMatch(/<(?:el-dropdown|Pencil|Power|Eye|Trash2|Download|CircleX)\b/)
+  })})
diff --git a/src/modules/master-data/counterparties/pages/PartnersView.vue b/src/modules/master-data/counterparties/pages/PartnersView.vue
new file mode 100644
index 00000000..274c6676
--- /dev/null
+++ b/src/modules/master-data/counterparties/pages/PartnersView.vue
@@ -0,0 +1,514 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, reactive, ref, watch } from 'vue'
+import { ElMessage, ElMessageBox, type FormInstance, type FormRules } from 'element-plus'
+import { Building2, FileUp, MapPin, Plus, Save } from '@lucide/vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import AppDrawer from '@/shared/components/AppDrawer.vue'
+import BatchImportDialog from '@/shared/components/BatchImportDialog.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import DetailPageLayout from '@/shared/components/DetailPageLayout.vue'
+import FormSection from '@/shared/components/FormSection.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import LineClampText from '@/shared/components/LineClampText.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import { useUnsavedWorkRegistration } from '@/core/unsaved-work/useUnsavedWorkRegistration'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import {
+  changePlatformPartnerStatus,
+  createPlatformPartner,
+  downloadPlatformPartnerImportTemplate,
+  getPlatformPartner,
+  importPlatformPartners,
+  listPlatformPartners,
+  updatePlatformPartner,
+  type PlatformPartnerResource,
+  type PlatformPartnerCarrierCode,
+  type PlatformPartnerStatus,
+  type PlatformPartnerType,
+  type SavePlatformPartnerRequest,
+} from '@/modules/master-data/counterparties/api/platformPartners'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+
+const pageSize = ref(20)
+const access = useAccessPreviewStore()
+const loading = ref(false)
+const saving = ref(false)
+const editorOpen = ref(false)
+const detailOpen = ref(false)
+const detailLoading = ref(false)
+const detail = ref<PlatformPartnerResource | null>(null)
+const importOpen = ref(false)
+const formRef = ref<FormInstance>()
+const rows = ref<PlatformPartnerResource[]>([])
+const page = ref(1)
+const total = ref(0)
+const loadError = ref<ApiErrorDetails | null>(null)
+const statusLoadingIds = ref(new Set<string>())
+let loadSequence = 0
+let detailSequence = 0
+
+type PartnerFilters = QueryModel & {
+  keyword: string
+  type: PlatformPartnerType | ''
+  status: PlatformPartnerStatus | ''
+}
+
+const filters = ref<PartnerFilters>({
+  keyword: '',
+  type: '',
+  status: '',
+})
+const appliedFilters = ref<PartnerFilters>({ ...filters.value })
+const queryFields = computed<QueryField[]>(() => [
+  { key: 'keyword', type: 'input', label: '往来单位名称', placeholder: '请输入往来单位名称' },
+  {
+    key: 'type',
+    type: 'select',
+    label: '单位类型',
+    placeholder: '全部类型',
+    options: [
+      { label: '船公司', value: 'CARRIER' },
+      { label: '发货单位', value: 'SHIPPER' },
+      { label: '收货单位', value: 'CONSIGNEE' },
+    ],
+  },
+  {
+    key: 'status',
+    type: 'select',
+    label: '状态',
+    placeholder: '全部状态',
+    options: [
+      { label: '启用', value: 'ACTIVE' },
+      { label: '停用', value: 'INACTIVE' },
+    ],
+  },
+])
+
+interface PartnerForm extends SavePlatformPartnerRequest {
+  id: string
+}
+
+const emptyForm = (): PartnerForm => ({
+  id: '',
+  partnerCode: '',
+  partnerName: '',
+  partnerType: 'SHIPPER',
+  types: ['SHIPPER'],
+  carrierCode: null,
+  contactName: '',
+  contactPhone: '',
+  contactEmail: null,
+  countryCode: 'CN',
+  province: null,
+  city: '',
+  district: null,
+  addressLine: '',
+  postalCode: null,
+  status: 'ACTIVE',
+  remark: null,
+})
+const form = reactive<PartnerForm>(emptyForm())
+const editorLabel = computed(() => form.id ? '编辑往来单位' : '新增往来单位')
+const editorPermission = computed(() => form.id ? 'platform:counterparty:edit' : 'platform:counterparty:create')
+const { captureBaseline } = useUnsavedWorkRegistration({
+  key: 'partner-editor',
+  label: editorLabel,
+  isOpen: editorOpen,
+  model: form,
+  requiredPermission: editorPermission,
+})
+
+const rules: FormRules<PartnerForm> = {
+  partnerCode: [{ required: true, whitespace: true, message: '请输入往来单位编码', trigger: 'blur' }],
+  partnerName: [{ required: true, whitespace: true, message: '请输入往来单位名称', trigger: 'blur' }],
+  types: [{ required: true, type: 'array', min: 1, message: '请至少选择一个单位类型', trigger: 'change' }],
+  carrierCode: [{ validator: (_rule, value, callback) => form.types.includes('CARRIER') && !value ? callback(new Error('请选择船司标准编码')) : callback(), trigger: 'change' }],
+  contactName: [{ required: true, whitespace: true, message: '请输入联系人', trigger: 'blur' }],
+  contactPhone: [{ required: true, whitespace: true, message: '请输入联系电话', trigger: 'blur' }],
+  contactEmail: [{ type: 'email', message: '请输入有效的邮箱地址', trigger: 'blur' }],
+  countryCode: [
+    { required: true, whitespace: true, message: '请输入国家二字码', trigger: 'blur' },
+    { pattern: /^[A-Z]{2}$/, message: '国家码须为两个大写英文字母', trigger: 'blur' },
+  ],
+  city: [{ required: true, whitespace: true, message: '请输入城市', trigger: 'blur' }],
+  addressLine: [{ required: true, whitespace: true, message: '请输入详细地址', trigger: 'blur' }],
+  status: [{ required: true, message: '请选择状态', trigger: 'change' }],
+}
+
+const typeLabels: Record<PlatformPartnerType, string> = {
+  CARRIER: '船公司',
+  SHIPPER: '发货单位',
+  CONSIGNEE: '收货单位',
+}
+const typeOptions = Object.entries(typeLabels).map(([value, label]) => ({ value: value as PlatformPartnerType, label }))
+const carrierCodeLabels: Record<PlatformPartnerCarrierCode, string> = {
+  MATSON: '美森', SML: 'SML', ZIM: '以星', COSCO: '中远', EMC: '长荣', HEDE: '合德', OTHER: '其他',
+}
+const carrierCodeOptions = (Object.entries(carrierCodeLabels) as [PlatformPartnerCarrierCode, string][]).map(([value, label]) => ({ value, label: `${label} (${value})` }))
+function formatCarrierCode(value?: PlatformPartnerCarrierCode | null) { return value ? `${carrierCodeLabels[value]} (${value})` : '—' }
+function partnerTypeLabel(type: PlatformPartnerType) {
+  return typeLabels[type]
+}
+const partnerColumns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 250, fixed: 'left', slotName: 'actions' },
+  { key: 'partner', label: '单位名称', minWidth: 210, slotName: 'partner' },
+  { key: 'partnerCode', prop: 'partnerCode', label: '单位编码', minWidth: 130, defaultVisible: false },
+  { key: 'type', label: '类型', minWidth: 115, slotName: 'type' },
+  { key: 'contact', prop: 'contactName', label: '联系人', minWidth: 130 },
+  { key: 'contactPhone', prop: 'contactPhone', label: '电话', minWidth: 145 },
+  { key: 'contactEmail', prop: 'contactEmail', label: '邮箱', minWidth: 190, defaultVisible: false, formatter: (row: PlatformPartnerResource) => row.contactEmail || '—' },
+  { key: 'address', label: '地址', minWidth: 240, slotName: 'address', defaultVisible: false },
+  { key: 'status', label: '状态', width: 90, slotName: 'status' },
+  { key: 'updatedAt', prop: 'updatedAt', label: '更新时间', minWidth: 140, defaultVisible: false, formatter: (row: PlatformPartnerResource) => formatUpdatedAt(row.updatedAt) },
+]
+
+watch(
+  () => access.can(editorPermission.value),
+  (canWrite) => {
+    if (canWrite || !editorOpen.value) return
+    editorOpen.value = false
+    Object.assign(form, emptyForm())
+  },
+  { flush: 'sync' },
+)
+
+function queryParams() {
+  return {
+    page: page.value,
+    size: pageSize.value,
+    keyword: appliedFilters.value.keyword.trim() || undefined,
+    type: appliedFilters.value.type || undefined,
+    status: appliedFilters.value.status || undefined,
+  }
+}
+
+async function loadPartners() {
+  const sequence = ++loadSequence
+  loading.value = true
+  loadError.value = null
+  try {
+    const result = await listPlatformPartners(queryParams())
+    if (sequence !== loadSequence) return
+    rows.value = result.records
+    total.value = result.total
+  } catch (error) {
+    if (sequence !== loadSequence) return
+    rows.value = []
+    total.value = 0
+    loadError.value = getApiErrorDetails(error, '往来单位加载失败，请稍后重试')
+  } finally {
+    if (sequence === loadSequence) loading.value = false
+  }
+}
+
+function searchPartners(model: QueryModel) {
+  appliedFilters.value = {
+    keyword: String(model.keyword || ''),
+    type: (model.type || '') as PlatformPartnerType | '',
+    status: (model.status || '') as PlatformPartnerStatus | '',
+  }
+  if (page.value === 1) {
+    void loadPartners()
+    return
+  }
+  page.value = 1
+}
+
+function openCreate() {
+  Object.assign(form, emptyForm())
+  captureBaseline()
+  editorOpen.value = true
+  requestAnimationFrame(() => formRef.value?.clearValidate())
+}
+
+function nullable(value: string | null) {
+  return value?.trim() || null
+}
+
+function openEdit(row: PlatformPartnerResource) {
+  Object.assign(form, {
+    id: String(row.id),
+    partnerCode: row.partnerCode,
+    partnerName: row.partnerName,
+    partnerType: row.types[0],
+    types: [...row.types],
+    carrierCode: row.carrierCode,
+    contactName: row.contactName,
+    contactPhone: row.contactPhone,
+    contactEmail: row.contactEmail,
+    countryCode: row.countryCode,
+    province: row.province,
+    city: row.city,
+    district: row.district,
+    addressLine: row.addressLine,
+    postalCode: row.postalCode,
+    status: row.status,
+    remark: row.remark,
+  })
+  captureBaseline()
+  editorOpen.value = true
+  requestAnimationFrame(() => formRef.value?.clearValidate())
+}
+
+function savePayload(): SavePlatformPartnerRequest {
+  const types = [...form.types]
+  return {
+    partnerCode: form.partnerCode.trim(),
+    partnerName: form.partnerName.trim(),
+    partnerType: types[0],
+    types,
+    carrierCode: types.includes('CARRIER') ? form.carrierCode : null,
+    contactName: form.contactName.trim(),
+    contactPhone: form.contactPhone.trim(),
+    contactEmail: nullable(form.contactEmail),
+    countryCode: form.countryCode.trim().toUpperCase(),
+    province: nullable(form.province),
+    city: form.city.trim(),
+    district: nullable(form.district),
+    addressLine: form.addressLine.trim(),
+    postalCode: nullable(form.postalCode),
+    status: form.status,
+    remark: nullable(form.remark),
+  }
+}
+
+async function openDetail(row: PlatformPartnerResource) {
+  const sequence = ++detailSequence
+  detailOpen.value = true
+  detailLoading.value = true
+  detail.value = null
+  try {
+    const result = await getPlatformPartner(row.id)
+    if (sequence !== detailSequence || !detailOpen.value) return
+    detail.value = result
+  } catch (error) {
+    if (sequence !== detailSequence) return
+    const meta = getApiErrorDetails(error, '往来单位详情加载失败')
+    ElMessage.error(meta.requestId ? `${meta.message}（requestId: ${meta.requestId}）` : meta.message)
+    detailOpen.value = false
+  } finally {
+    if (sequence === detailSequence) detailLoading.value = false
+  }
+}
+
+function openImport() {
+  importOpen.value = true
+}
+
+async function savePartner() {
+  const valid = await formRef.value?.validate().catch(() => false)
+  if (!valid) return
+  saving.value = true
+  try {
+    const payload = savePayload()
+    if (form.id) {
+      await updatePlatformPartner(form.id, payload)
+      ElMessage.success('往来单位已更新')
+    } else {
+      await createPlatformPartner(payload)
+      ElMessage.success('往来单位已新增')
+    }
+    editorOpen.value = false
+    await loadPartners()
+  } catch (error) {
+    const details = getApiErrorDetails(error, '往来单位保存失败，请重试')
+    ElMessage.error(details.requestId ? `${details.message}（requestId: ${details.requestId}）` : details.message)
+  } finally {
+    saving.value = false
+  }
+}
+
+async function toggleStatus(row: PlatformPartnerResource) {
+  const nextStatus: PlatformPartnerStatus = row.status === 'ACTIVE' ? 'INACTIVE' : 'ACTIVE'
+  const action = nextStatus === 'ACTIVE' ? '启用' : '停用'
+  try {
+    await ElMessageBox.confirm(
+      `${action}后${nextStatus === 'ACTIVE' ? '可继续用于新业务' : '不再用于新业务，历史数据不受影响'}。`,
+      `${action}“${row.partnerName}”`,
+      { customClass: 'admin-density-confirm', type: nextStatus === 'ACTIVE' ? 'success' : 'warning', confirmButtonText: action, cancelButtonText: '取消' },
+    )
+  } catch {
+    return
+  }
+  const id = String(row.id)
+  statusLoadingIds.value = new Set(statusLoadingIds.value).add(id)
+  try {
+    await changePlatformPartnerStatus(row.id, nextStatus)
+    ElMessage.success(`往来单位已${action}`)
+    await loadPartners()
+  } catch (error) {
+    const details = getApiErrorDetails(error, `往来单位${action}失败，请重试`)
+    ElMessage.error(details.requestId ? `${details.message}（requestId: ${details.requestId}）` : details.message)
+  } finally {
+    const next = new Set(statusLoadingIds.value)
+    next.delete(id)
+    statusLoadingIds.value = next
+  }
+}
+
+function formatUpdatedAt(value?: string | null) {
+  return value ? value.replace('T', ' ').slice(0, 16) : '-'
+}
+
+watch([page, pageSize], () => { void loadPartners() })
+watch(() => form.types.includes('CARRIER'), (carrier) => {
+  if (carrier) return
+  form.carrierCode = null
+  formRef.value?.clearValidate('carrierCode')
+})
+watch(detailOpen, (open) => {
+  if (open) return
+  detailSequence += 1
+  detailLoading.value = false
+  detail.value = null
+})
+onMounted(() => {
+  void loadPartners()
+})
+</script>
+
+<template>
+  <AdminPage as="div" class="partners-page admin-density" spacing="normal">
+    <ListPageLayout aria-label="往来单位管理">
+      <template #toolbar>
+        <QueryToolbar v-model="filters" class="surface-panel" ariaLabel="往来单位筛选" :fields="queryFields" preference-key="partners-query" @search="searchPartners" />
+      </template>
+
+      <template v-if="loadError" #state>
+        <LoadErrorState
+          title="往来单位列表暂时无法加载"
+          :message="loadError.message"
+          :loading="loading"
+          @retry="loadPartners()"
+        >
+          <template #details><ApiErrorMeta :details="loadError" /></template>
+        </LoadErrorState>
+      </template>
+
+      <section v-if="!loadError" class="surface-panel table-panel" :aria-busy="loading">
+      <DataTable
+        v-model:page="page"
+        v-model:page-size="pageSize"
+        :data="rows"
+        :columns="partnerColumns"
+        preference-key="partners-table"
+        :loading="loading"
+        :total="total"
+        :page-sizes="[20, 50, 100]"
+        aria-label="往来单位列表"
+        row-key="id"
+        empty-text="暂无符合条件的往来单位"
+      >
+        <template #toolbar-actions><div class="partners-primary-actions"><el-button v-if="access.can('platform:counterparty:import')" :disabled="loading" @click="openImport"><FileUp :size="16" />批量导入</el-button><el-button v-if="access.can('platform:counterparty:create')" type="primary" :disabled="loading" @click="openCreate"><Plus :size="16" />新增往来单位</el-button></div></template>
+        <template #actions="{ row }">
+          <div class="table-actions density-actions">
+            <el-button data-tone="neutral" class="density-action" size="small" @click="openDetail(row as PlatformPartnerResource)">详情</el-button>
+            <el-button data-tone="neutral" class="density-action" v-if="access.can('platform:counterparty:edit')" size="small" :disabled="loading" @click="openEdit(row as PlatformPartnerResource)">编辑</el-button>
+            <el-button class="density-action" v-if="access.can('platform:counterparty:status')" size="small" :disabled="loading" :data-tone="(row as PlatformPartnerResource).status === 'ACTIVE' ? 'danger' : 'success'" :loading="statusLoadingIds.has(String((row as PlatformPartnerResource).id))" @click="toggleStatus(row as PlatformPartnerResource)">{{ (row as PlatformPartnerResource).status === 'ACTIVE' ? '停用' : '启用' }}</el-button>
+          </div>
+        </template>
+        <template #partner="{ row }"><div class="partner-cell"><span><Building2 :size="18" /></span><div><LineClampText :content="(row as PlatformPartnerResource).partnerName" /></div></div></template>
+        <template #type="{ row }"><div class="partner-types"><el-tag v-for="type in (row as PlatformPartnerResource).types" :key="type" effect="plain">{{ partnerTypeLabel(type) }}</el-tag></div></template>
+        <template #address="{ row }"><div class="partner-address"><MapPin :size="15" /><span>{{ [(row as PlatformPartnerResource).province, (row as PlatformPartnerResource).city, (row as PlatformPartnerResource).district, (row as PlatformPartnerResource).addressLine].filter(Boolean).join(' ') }}</span></div></template>
+        <template #status="{ row }"><el-tag :type="(row as PlatformPartnerResource).status === 'ACTIVE' ? 'success' : 'info'" effect="light">{{ (row as PlatformPartnerResource).status === 'ACTIVE' ? '启用' : '停用' }}</el-tag></template>
+        <template #pagination-left>平台公共数据 · 共 {{ total }} 个往来单位</template>
+      </DataTable>
+      </section>
+    </ListPageLayout>
+
+    <AppDrawer
+      v-model="editorOpen"
+      :title="editorLabel"
+      size="min(680px, 94vw)"
+      class="editor-drawer admin-density admin-density-drawer"
+      :confirm-loading="saving"
+    >
+      <el-form ref="formRef" :model="form" :rules="rules" label-position="top" class="density-form" :disabled="saving">
+        <FormSection class="density-form-section" title="单位信息"><div class="form-grid two-cols">
+          <el-form-item label="单位编码" prop="partnerCode" required><el-input v-model="form.partnerCode" placeholder="如：CUS-001" maxlength="50" /></el-form-item>
+          <el-form-item label="单位名称" prop="partnerName" required><el-input v-model="form.partnerName" placeholder="请输入工商登记或常用单位名称" maxlength="128" /></el-form-item>
+          <el-form-item label="单位类型" prop="types" required><el-select v-model="form.types" multiple collapse-tags collapse-tags-tooltip placeholder="请选择一个或多个单位类型"><el-option v-for="option in typeOptions" :key="option.value" :label="option.label" :value="option.value" /></el-select></el-form-item>
+          <el-form-item label="状态" prop="status" required><el-radio-group v-model="form.status"><el-radio-button value="ACTIVE">启用</el-radio-button><el-radio-button value="INACTIVE">停用</el-radio-button></el-radio-group></el-form-item>
+          <el-form-item v-if="form.types.includes('CARRIER')" label="船司标准编码" prop="carrierCode" required><el-select v-model="form.carrierCode" placeholder="请选择船司标准编码" style="width:100%"><el-option v-for="option in carrierCodeOptions" :key="option.value" :label="option.label" :value="option.value" /></el-select></el-form-item>
+        </div></FormSection>
+        <FormSection class="density-form-section" title="联系信息"><div class="form-grid two-cols">
+          <el-form-item label="联系人" prop="contactName" required><el-input v-model="form.contactName" placeholder="请输入主要联系人姓名" maxlength="64" /></el-form-item>
+          <el-form-item label="联系电话" prop="contactPhone" required><el-input v-model="form.contactPhone" placeholder="请输入手机号或固定电话" maxlength="32" /></el-form-item>
+          <el-form-item label="联系邮箱" prop="contactEmail"><el-input v-model="form.contactEmail" placeholder="如：contact@example.com" maxlength="128" /></el-form-item>
+        </div></FormSection>
+        <FormSection class="density-form-section" title="地址信息"><div class="form-grid two-cols">
+          <el-form-item label="国家二字码" prop="countryCode" required><el-input v-model="form.countryCode" placeholder="如：CN" maxlength="2" @input="form.countryCode = String($event).toUpperCase()" /></el-form-item>
+          <el-form-item label="省 / 州" prop="province"><el-input v-model="form.province" placeholder="如：广东省" maxlength="64" /></el-form-item>
+          <el-form-item label="城市" prop="city" required><el-input v-model="form.city" placeholder="如：深圳市" maxlength="64" /></el-form-item>
+          <el-form-item label="区 / 县" prop="district"><el-input v-model="form.district" placeholder="如：宝安区" maxlength="64" /></el-form-item>
+          <el-form-item label="邮政编码" prop="postalCode"><el-input v-model="form.postalCode" placeholder="如：518000" maxlength="20" /></el-form-item>
+        </div><el-form-item label="详细地址" prop="addressLine" required><el-input v-model="form.addressLine" type="textarea" :rows="3" placeholder="请输入街道、园区、楼栋及门牌信息" maxlength="255" show-word-limit /></el-form-item></FormSection>
+        <FormSection class="density-form-section" title="其他信息" :bordered="false"><el-form-item label="备注" prop="remark"><el-input v-model="form.remark" type="textarea" :rows="3" placeholder="请输入内部说明（选填）" maxlength="500" show-word-limit /></el-form-item></FormSection>
+      </el-form>
+      <template #footer>
+        <div class="drawer-footer">
+          <el-button :disabled="saving" @click="editorOpen = false">取消</el-button>
+          <el-button type="primary" :loading="saving" @click="savePartner"><Save :size="16" />保存往来单位</el-button>
+        </div>
+      </template>
+    </AppDrawer>
+
+    <AppDrawer v-model="detailOpen" title="往来单位详情" size="min(680px, 94vw)" class="detail-drawer admin-density admin-density-drawer" :loading="detailLoading" :show-footer="false">
+      <div class="partner-detail">
+        <DetailPageLayout class="partner-detail-layout" v-if="detail" aria-label="往来单位详情">
+          <FormSection class="density-form-section" title="单位信息"><dl class="detail-grid density-fields">
+            <div><dt>单位编码</dt><dd>{{ detail.partnerCode }}</dd></div>
+            <div><dt>单位名称</dt><dd>{{ detail.partnerName }}</dd></div>
+            <div><dt>状态</dt><dd><el-tag :type="detail.status === 'ACTIVE' ? 'success' : 'info'">{{ detail.status === 'ACTIVE' ? '启用' : '停用' }}</el-tag></dd></div>
+            <div><dt>单位类型</dt><dd class="partner-types"><el-tag v-for="type in detail.types" :key="type" effect="plain">{{ partnerTypeLabel(type) }}</el-tag></dd></div>
+            <div v-if="detail.types.includes('CARRIER')"><dt>船司标准编码</dt><dd>{{ formatCarrierCode(detail.carrierCode) }}</dd></div>
+          </dl></FormSection>
+          <FormSection class="density-form-section" title="联系与地址"><dl class="detail-grid density-fields">
+            <div><dt>联系人</dt><dd>{{ detail.contactName }}</dd></div><div><dt>联系电话</dt><dd>{{ detail.contactPhone }}</dd></div>
+            <div><dt>联系邮箱</dt><dd>{{ detail.contactEmail || '-' }}</dd></div><div><dt>邮政编码</dt><dd>{{ detail.postalCode || '-' }}</dd></div>
+            <div class="detail-span"><dt>详细地址</dt><dd>{{ [detail.countryCode, detail.province, detail.city, detail.district, detail.addressLine].filter(Boolean).join(' ') }}</dd></div>
+          </dl></FormSection>
+          <FormSection class="density-form-section" title="其他信息" :bordered="false"><dl class="detail-grid density-fields">
+            <div class="detail-span"><dt>更新时间</dt><dd>{{ formatUpdatedAt(detail.updatedAt) }}</dd></div>
+            <div class="detail-span"><dt>备注</dt><dd>{{ detail.remark || '-' }}</dd></div>
+          </dl></FormSection>
+        </DetailPageLayout>
+      </div>
+    </AppDrawer>
+
+    <BatchImportDialog class="admin-density-dialog"
+      v-model="importOpen"
+      title="批量导入往来单位"
+      entity-label="往来单位"
+      template-file-name="往来单位导入模板-v1.xlsx"
+      :download-template="downloadPlatformPartnerImportTemplate"
+      :import-file="importPlatformPartners"
+      @success="loadPartners"
+    />
+  </AdminPage>
+</template>
+
+<style scoped>
+.partner-detail-layout { gap: 0; }
+.partners-page { min-width: 0; }
+.partners-primary-actions, .partner-types { display: flex; flex-wrap: wrap; gap: var(--admin-space-3); }
+.partner-cell { display: flex; align-items: center; gap: var(--admin-space-4); }
+.partner-cell > span { display: grid; width: 34px; height: 34px; flex: 0 0 34px; place-items: center; border-radius: var(--admin-radius); background: #eef3fa; color: var(--cc-primary); }
+.partner-cell > div { display: flex; min-width: 0; flex-direction: column; gap: 3px; }
+.partner-cell :deep(.line-clamp-text) { width: 100%; }
+.partner-address { display: flex; align-items: flex-start; gap: 7px; line-height: 1.55; overflow-wrap: anywhere; }
+.partner-address svg { flex: 0 0 15px; margin-top: 3px; color: var(--cc-muted); }
+.partner-detail { min-width: 0; }
+.partner-detail .detail-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+.detail-grid .detail-span { grid-column: 1 / -1; }
+@media (max-width: 720px) {
+  .partners-primary-actions :deep(.el-button) { width: 100%; min-height: 40px; }
+  .partners-primary-actions { flex-direction: column; }
+  .partner-detail { padding: 16px; }
+  .detail-grid { grid-template-columns: minmax(0, 1fr); }
+  .detail-grid .detail-span { grid-column: auto; }
+}
+</style>
diff --git a/src/modules/master-data/express-companies/api/platformExpressCompanies.test.ts b/src/modules/master-data/express-companies/api/platformExpressCompanies.test.ts
new file mode 100644
index 00000000..5f26224d
--- /dev/null
+++ b/src/modules/master-data/express-companies/api/platformExpressCompanies.test.ts
@@ -0,0 +1,100 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import {
+  changePlatformExpressCompanyStatus,
+  createPlatformExpressCompany,
+  downloadPlatformExpressCompanyImportTemplate,
+  getPlatformExpressCompany,
+  importPlatformExpressCompanies,
+  listPlatformExpressCompanies,
+  updatePlatformExpressCompany,
+  type SavePlatformExpressCompanyRequest,
+} from './platformExpressCompanies'
+
+vi.mock('@/shared/api/http', () => ({
+  http: { get: vi.fn(), post: vi.fn(), put: vi.fn(), patch: vi.fn() },
+  unwrapApiResponse: <T>(response: { data: T }) => response.data,
+}))
+
+const payload: SavePlatformExpressCompanyRequest = {
+  companyCode: 'SF',
+  companyName: '顺丰速运',
+  servicePhone: '95338',
+  website: 'https://www.sf-express.com',
+  trackingUrlTemplate: 'https://example.com/track/{trackingNo}',
+  status: 'ACTIVE',
+  remark: null,
+}
+
+describe('platform express company API', () => {
+  beforeEach(() => {
+    vi.mocked(http.get).mockReset()
+    vi.mocked(http.post).mockReset()
+    vi.mocked(http.put).mockReset()
+    vi.mocked(http.patch).mockReset()
+  })
+
+  it('uses the implemented list and detail contracts', async () => {
+    const page = { records: [], page: '1', size: '20', total: '0', pages: '0' }
+    vi.mocked(http.get)
+      .mockResolvedValueOnce({ code: '200', message: 'success', data: page })
+      .mockResolvedValueOnce({ code: '200', message: 'success', data: { id: '19001' } })
+
+    await expect(listPlatformExpressCompanies(2, 20, ' 顺丰 ', 'ACTIVE')).resolves.toEqual({
+      records: [],
+      page: 1,
+      size: 20,
+      total: 0,
+      pages: 0,
+    })
+    await expect(getPlatformExpressCompany('19001')).resolves.toEqual({ id: '19001' })
+    expect(http.get).toHaveBeenNthCalledWith(1, '/platform/v1/express-companies', {
+      params: { page: 2, size: 20, keyword: '顺丰', status: 'ACTIVE' },
+    })
+    expect(http.get).toHaveBeenNthCalledWith(2, '/platform/v1/express-companies/19001', {
+      params: { tenantId: 0 },
+    })
+  })
+
+  it('uses the implemented create, update, and status contracts', async () => {
+    vi.mocked(http.post).mockResolvedValue({ code: '200', message: 'success', data: '19001' })
+    vi.mocked(http.put).mockResolvedValue({ code: '200', message: 'success', data: null })
+    vi.mocked(http.patch).mockResolvedValue({ code: '200', message: 'success', data: null })
+
+    await expect(createPlatformExpressCompany(payload)).resolves.toBe('19001')
+    await expect(updatePlatformExpressCompany('19001', payload)).resolves.toBeNull()
+    await expect(changePlatformExpressCompanyStatus('19001', 'INACTIVE')).resolves.toBeNull()
+
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/express-companies', payload, { params: { tenantId: 0 } })
+    expect(http.put).toHaveBeenCalledWith('/platform/v1/express-companies/19001', payload, { params: { tenantId: 0 } })
+    expect(http.patch).toHaveBeenCalledWith(
+      '/platform/v1/express-companies/19001/status',
+      { status: 'INACTIVE' },
+      { params: { tenantId: 0 } },
+    )
+  })
+
+  it('downloads the standard template as a blob', async () => {
+    const template = new Blob(['xlsx'], { type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' })
+    vi.mocked(http.get).mockResolvedValue(template)
+
+    await expect(downloadPlatformExpressCompanyImportTemplate()).resolves.toBe(template)
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/express-companies/import-template', { responseType: 'blob' })
+  })
+
+  it('uploads the selected XLSX file as multipart form data', async () => {
+    const result = { fileName: 'express.xlsx', totalRows: 2, importedRows: 2, success: true, errors: [] }
+    vi.mocked(http.post).mockResolvedValue({ code: '200', message: 'success', data: result })
+    const file = new File(['xlsx'], 'express.xlsx', {
+      type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    })
+
+    await expect(importPlatformExpressCompanies(file)).resolves.toEqual(result)
+    expect(http.post).toHaveBeenCalledOnce()
+    const [path, body, config] = vi.mocked(http.post).mock.calls[0]!
+    expect(path).toBe('/platform/v1/express-companies/import')
+    expect(body).toBeInstanceOf(FormData)
+    expect((body as FormData).get('file')).toBe(file)
+    expect(config).toEqual({ params: { tenantId: 0 } })
+  })
+})
diff --git a/src/modules/master-data/express-companies/api/platformExpressCompanies.ts b/src/modules/master-data/express-companies/api/platformExpressCompanies.ts
new file mode 100644
index 00000000..10281958
--- /dev/null
+++ b/src/modules/master-data/express-companies/api/platformExpressCompanies.ts
@@ -0,0 +1,126 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+
+export type PlatformExpressCompanyStatus = 'ACTIVE' | 'INACTIVE'
+
+export interface PlatformExpressCompanyResource {
+  id: number | string
+  tenantId: number | string
+  companyCode: string
+  companyName: string
+  servicePhone: string | null
+  website: string | null
+  trackingUrlTemplate: string | null
+  status: PlatformExpressCompanyStatus
+  remark: string | null
+  createdAt?: string | null
+  updatedAt?: string | null
+}
+
+export interface PlatformExpressCompanyPage {
+  records: PlatformExpressCompanyResource[]
+  page: number
+  size: number
+  total: number
+  pages: number
+}
+
+export interface SavePlatformExpressCompanyRequest {
+  companyCode: string
+  companyName: string
+  servicePhone: string | null
+  website: string | null
+  trackingUrlTemplate: string | null
+  status: PlatformExpressCompanyStatus
+  remark: string | null
+}
+
+export interface PlatformExpressCompanyImportError {
+  row: number
+  field: string
+  message: string
+}
+
+export interface PlatformExpressCompanyImportResult {
+  fileName: string
+  totalRows: number
+  importedRows: number
+  success: boolean
+  errors: PlatformExpressCompanyImportError[]
+}
+
+const basePath = '/platform/v1/express-companies'
+const platformResourceScope = 0
+
+export async function listPlatformExpressCompanies(
+  page = 1,
+  size = 20,
+  keyword = '',
+  status: PlatformExpressCompanyStatus | '' = '',
+) {
+  const response = await http.get<ApiEnvelope<PlatformExpressCompanyPage>, ApiEnvelope<PlatformExpressCompanyPage>>(basePath, {
+    params: {
+      page,
+      size,
+      keyword: keyword.trim() || undefined,
+      status: status || undefined,
+    },
+  })
+  const result = unwrapApiResponse(response)
+  return {
+    ...result,
+    page: Number(result.page),
+    size: Number(result.size),
+    total: Number(result.total),
+    pages: Number(result.pages),
+  }
+}
+
+export async function getPlatformExpressCompany(id: number | string) {
+  const response = await http.get<ApiEnvelope<PlatformExpressCompanyResource>, ApiEnvelope<PlatformExpressCompanyResource>>(
+    `${basePath}/${id}`,
+    { params: { tenantId: platformResourceScope } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function createPlatformExpressCompany(payload: SavePlatformExpressCompanyRequest) {
+  const response = await http.post<ApiEnvelope<number | string>, ApiEnvelope<number | string>>(basePath, payload, {
+    params: { tenantId: platformResourceScope },
+  })
+  return unwrapApiResponse(response)
+}
+
+export async function updatePlatformExpressCompany(
+  id: number | string,
+  payload: SavePlatformExpressCompanyRequest,
+) {
+  const response = await http.put<ApiEnvelope<null>, ApiEnvelope<null>>(`${basePath}/${id}`, payload, {
+    params: { tenantId: platformResourceScope },
+  })
+  return unwrapApiResponse(response)
+}
+
+export async function changePlatformExpressCompanyStatus(
+  id: number | string,
+  status: PlatformExpressCompanyStatus,
+) {
+  const response = await http.patch<ApiEnvelope<null>, ApiEnvelope<null>>(`${basePath}/${id}/status`, { status }, {
+    params: { tenantId: platformResourceScope },
+  })
+  return unwrapApiResponse(response)
+}
+
+export async function downloadPlatformExpressCompanyImportTemplate() {
+  return http.get<Blob, Blob>(`${basePath}/import-template`, { responseType: 'blob' })
+}
+
+export async function importPlatformExpressCompanies(file: File) {
+  const formData = new FormData()
+  formData.append('file', file)
+  const response = await http.post<ApiEnvelope<PlatformExpressCompanyImportResult>, ApiEnvelope<PlatformExpressCompanyImportResult>>(
+    `${basePath}/import`,
+    formData,
+    { params: { tenantId: platformResourceScope } },
+  )
+  return unwrapApiResponse(response)
+}
diff --git a/src/modules/master-data/express-companies/pages/ExpressCompaniesView.test.ts b/src/modules/master-data/express-companies/pages/ExpressCompaniesView.test.ts
new file mode 100644
index 00000000..16fa1d9e
--- /dev/null
+++ b/src/modules/master-data/express-companies/pages/ExpressCompaniesView.test.ts
@@ -0,0 +1,178 @@
+import ElementPlus from 'element-plus'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { createPinia, setActivePinia } from 'pinia'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { getPlatformExpressCompany, listPlatformExpressCompanies, type PlatformExpressCompanyResource } from '@/modules/master-data/express-companies/api/platformExpressCompanies'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+import ExpressCompaniesView from './ExpressCompaniesView.vue'
+
+const expressCompaniesSource = readFileSync(resolve(process.cwd(), 'src/modules/master-data/express-companies/pages/ExpressCompaniesView.vue'), 'utf8')
+
+vi.mock('@/modules/master-data/express-companies/api/platformExpressCompanies', () => ({
+  listPlatformExpressCompanies: vi.fn(),
+  getPlatformExpressCompany: vi.fn(),
+  createPlatformExpressCompany: vi.fn(),
+  downloadPlatformExpressCompanyImportTemplate: vi.fn(),
+  importPlatformExpressCompanies: vi.fn(),
+  updatePlatformExpressCompany: vi.fn(),
+  changePlatformExpressCompanyStatus: vi.fn(),
+}))
+
+class ResizeObserverStub implements ResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+
+function createMemoryStorage(): Storage {
+  const values = new Map<string, string>()
+  return {
+    get length() { return values.size },
+    clear: () => values.clear(),
+    getItem: (key) => values.get(key) ?? null,
+    key: (index) => [...values.keys()][index] ?? null,
+    removeItem: (key) => values.delete(key),
+    setItem: (key, value) => values.set(key, value),
+  }
+}
+
+const company: PlatformExpressCompanyResource = {
+  id: '19001',
+  tenantId: 0,
+  companyCode: 'SF',
+  companyName: '顺丰速运',
+  servicePhone: '95338',
+  website: 'https://www.sf-express.com',
+  trackingUrlTemplate: 'https://example.com/track/{trackingNo}',
+  status: 'ACTIVE',
+  remark: '测试数据',
+  updatedAt: '2026-07-31T10:20:00',
+}
+
+async function mountView() {
+  vi.stubGlobal('localStorage', createMemoryStorage())
+  vi.stubGlobal('sessionStorage', createMemoryStorage())
+  const pinia = createPinia()
+  setActivePinia(pinia)
+  const auth = useAuthStore()
+  auth.token = 'token'
+  auth.permissions = ['platform:express:list', 'platform:express:create', 'platform:express:edit', 'platform:express:status']
+  useAccessPreviewStore().initializeAfterLogin()
+  const wrapper = mount(ExpressCompaniesView, {
+    attachTo: document.body,
+    global: { plugins: [pinia, ElementPlus] },
+  })
+  await flushPromises()
+  return wrapper
+}
+
+enableAutoUnmount(afterEach)
+afterAll(() => vi.unstubAllGlobals())
+
+describe('ExpressCompaniesView query and table migration', () => {
+  it('renders edit and status as shared outlined text buttons', () => {
+    const actions = expressCompaniesSource.slice(expressCompaniesSource.indexOf('<template #actions='), expressCompaniesSource.indexOf('</template>', expressCompaniesSource.indexOf('<template #actions=')))
+    expect(actions.match(/class="density-action"/g)).toHaveLength(2)
+    expect(actions).toContain('>编辑</el-button>')
+    expect(actions).toContain(' :data-tone=')
+    expect(actions).not.toMatch(/<(?:el-dropdown|Pencil|Power|Eye|Trash2|Download|CircleX)\b/)
+  })
+  it('keeps operation first and exposes the prototype business columns separately', () => {
+    const actionsIndex = expressCompaniesSource.indexOf("{ key: 'actions', label: '操作'")
+    const nameIndex = expressCompaniesSource.indexOf("{ key: 'company', label: '公司名称'")
+    const codeIndex = expressCompaniesSource.indexOf("{ key: 'companyCode', prop: 'companyCode', label: '编码'")
+    const websiteIndex = expressCompaniesSource.indexOf("{ key: 'website', label: '官方网站'")
+    const phoneIndex = expressCompaniesSource.indexOf("{ key: 'servicePhone', prop: 'servicePhone', label: '客服电话'")
+    expect([actionsIndex, nameIndex, codeIndex, websiteIndex, phoneIndex].every((index) => index >= 0)).toBe(true)
+    expect(actionsIndex).toBeLessThan(nameIndex)
+    expect(nameIndex).toBeLessThan(codeIndex)
+    expect(codeIndex).toBeLessThan(websiteIndex)
+    expect(websiteIndex).toBeLessThan(phoneIndex)
+    expect(expressCompaniesSource).toContain("label: '更新时间', minWidth: 150, defaultVisible: false")
+  })
+  beforeEach(() => {
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+    document.body.innerHTML = ''
+    vi.mocked(listPlatformExpressCompanies).mockReset().mockResolvedValue({
+      records: [company], page: 1, size: 20, total: 1, pages: 1,
+    })
+    vi.mocked(getPlatformExpressCompany).mockReset().mockResolvedValue(company)
+  })
+
+  it('renders the shared toolbar and data table without a summary strip', async () => {
+    const wrapper = await mountView()
+
+    expect(wrapper.find('.query-toolbar').exists()).toBe(true)
+    expect(wrapper.find('input[aria-label="所属企业"]').exists()).toBe(false)
+    expect(wrapper.find('.data-table').exists()).toBe(true)
+    expect(wrapper.text()).toContain('顺丰速运')
+    expect(wrapper.text()).toContain('平台公共数据 · 共 1 家快递公司')
+    expect(wrapper.find('.metric-strip').exists()).toBe(false)
+    expect(wrapper.find('.list-page-layout__state').exists()).toBe(false)
+    expect(listPlatformExpressCompanies).toHaveBeenCalledWith(1, 20, '', '')
+    expect(wrapper.find('.data-table').text()).not.toContain('轨迹查询模板')
+    expect(wrapper.find('.data-table').text()).not.toContain('测试数据')
+  })
+
+  it('renders the error state instead of an empty table panel', async () => {
+    vi.mocked(listPlatformExpressCompanies).mockRejectedValueOnce(new Error('Gateway unavailable'))
+    const wrapper = await mountView()
+
+    expect(wrapper.find('.list-page-layout__state').exists()).toBe(true)
+    expect(wrapper.find('.table-panel').exists()).toBe(false)
+    expect(wrapper.text()).toContain('快递公司加载失败')
+    expect(wrapper.text()).not.toContain('Gateway unavailable')
+  })
+
+  it('does not request with edited filters until search is submitted', async () => {
+    const wrapper = await mountView()
+    await wrapper.find('input[placeholder="请输入快递公司名称"]').setValue('顺丰')
+    await flushPromises()
+    expect(listPlatformExpressCompanies).toHaveBeenCalledTimes(1)
+
+    const searchButton = wrapper.findAll('button').find((button) => button.text().trim() === '查询')
+    await searchButton?.trigger('click')
+    await flushPromises()
+
+    expect(listPlatformExpressCompanies).toHaveBeenLastCalledWith(1, 20, '顺丰', '')
+  })
+
+  it('opens the create form without selecting an enterprise', async () => {
+    const wrapper = await mountView()
+    const createButton = wrapper.findAll('button').find((button) => button.text().trim() === '新增快递公司')
+    await createButton?.trigger('click')
+    await flushPromises()
+
+    expect(document.body.textContent).toContain('新增快递公司')
+    expect(document.body.textContent).not.toContain('请先在筛选条件中选择所属企业')
+    expect(document.body.textContent).toContain('轨迹查询地址模板')
+    expect(document.body.textContent).toContain('内部说明')
+  })
+
+  it('keeps the latest express company selected for editing', async () => {
+    const secondCompany = { ...company, id: '19002', companyCode: 'JD', companyName: '京东物流' }
+    let resolveFirst!: (value: PlatformExpressCompanyResource) => void
+    let resolveSecond!: (value: PlatformExpressCompanyResource) => void
+    vi.mocked(getPlatformExpressCompany).mockImplementation((companyId) => new Promise((resolve) => {
+      if (String(companyId) === String(company.id)) resolveFirst = resolve
+      else resolveSecond = resolve
+    }))
+    const wrapper = await mountView()
+    const vm = wrapper.vm as unknown as {
+      form: { companyCode: string; companyName: string }
+      openEdit(row: PlatformExpressCompanyResource): Promise<void>
+    }
+
+    void vm.openEdit(company)
+    void vm.openEdit(secondCompany)
+    resolveSecond(secondCompany)
+    await flushPromises()
+    resolveFirst(company)
+    await flushPromises()
+
+    expect(vm.form).toMatchObject({ companyCode: 'JD', companyName: '京东物流' })
+  })
+})
diff --git a/src/modules/master-data/express-companies/pages/ExpressCompaniesView.vue b/src/modules/master-data/express-companies/pages/ExpressCompaniesView.vue
new file mode 100644
index 00000000..c462c6ab
--- /dev/null
+++ b/src/modules/master-data/express-companies/pages/ExpressCompaniesView.vue
@@ -0,0 +1,409 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, reactive, ref, watch } from 'vue'
+import { ElMessage, ElMessageBox, type FormInstance, type FormRules } from 'element-plus'
+import { ExternalLink, FileUp, Plus, Save, Truck } from '@lucide/vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import BatchImportDialog from '@/shared/components/BatchImportDialog.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import FormSection from '@/shared/components/FormSection.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import { useUnsavedWorkRegistration } from '@/core/unsaved-work/useUnsavedWorkRegistration'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import {
+  changePlatformExpressCompanyStatus,
+  createPlatformExpressCompany,
+  downloadPlatformExpressCompanyImportTemplate,
+  getPlatformExpressCompany,
+  importPlatformExpressCompanies,
+  listPlatformExpressCompanies,
+  updatePlatformExpressCompany,
+  type PlatformExpressCompanyResource,
+  type PlatformExpressCompanyStatus,
+  type SavePlatformExpressCompanyRequest,
+} from '@/modules/master-data/express-companies/api/platformExpressCompanies'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+
+const access = useAccessPreviewStore()
+const loading = ref(false)
+const saving = ref(false)
+const editorOpen = ref(false)
+const importOpen = ref(false)
+const formRef = ref<FormInstance>()
+const rows = ref<PlatformExpressCompanyResource[]>([])
+const page = ref(1)
+const pageSize = ref(20)
+const total = ref(0)
+const loadError = ref<ApiErrorDetails | null>(null)
+const statusLoadingIds = ref(new Set<string>())
+const editLoadingIds = ref(new Set<string>())
+type ExpressCompanyFilters = QueryModel & {
+  keyword: string
+  status: PlatformExpressCompanyStatus | ''
+}
+const filters = ref<ExpressCompanyFilters>({ keyword: '', status: '' })
+const appliedFilters = ref<ExpressCompanyFilters>({ ...filters.value })
+const queryFields = computed<QueryField[]>(() => [
+  { key: 'keyword', type: 'input', label: '快递公司名称', placeholder: '请输入快递公司名称', props: { maxlength: 128, 'aria-label': '快递公司名称' } },
+  {
+    key: 'status',
+    type: 'select',
+    label: '状态',
+    placeholder: '全部状态',
+    props: { 'aria-label': '快递公司状态' },
+    options: [
+      { label: '启用', value: 'ACTIVE' },
+      { label: '停用', value: 'INACTIVE' },
+    ],
+  },
+])
+let loadSequence = 0
+let editorLoadSequence = 0
+
+const emptyForm = (): SavePlatformExpressCompanyRequest & { id: string } => ({
+  id: '',
+  companyCode: '',
+  companyName: '',
+  servicePhone: null,
+  website: null,
+  trackingUrlTemplate: null,
+  status: 'ACTIVE',
+  remark: null,
+})
+const form = reactive(emptyForm())
+const rules: FormRules<typeof form> = {
+  companyCode: [{ required: true, message: '请输入快递公司编码', trigger: 'blur' }],
+  companyName: [{ required: true, message: '请输入快递公司名称', trigger: 'blur' }],
+  website: [{ type: 'url', message: '请输入以 http:// 或 https:// 开头的完整网址', trigger: 'blur' }],
+  status: [{ required: true, message: '请选择状态', trigger: 'change' }],
+}
+const editorTitle = computed(() => form.id ? '编辑快递公司' : '新增快递公司')
+const editorPermission = computed(() => form.id ? 'platform:express:edit' : 'platform:express:create')
+const { captureBaseline } = useUnsavedWorkRegistration({
+  key: 'express-company-editor',
+  label: editorTitle,
+  isOpen: editorOpen,
+  model: form,
+  requiredPermission: editorPermission,
+})
+
+watch(
+  () => access.can(editorPermission.value),
+  (canWrite) => {
+    if (canWrite || !editorOpen.value) return
+    editorOpen.value = false
+    Object.assign(form, emptyForm())
+  },
+  { flush: 'sync' },
+)
+
+function optionalText(value: string | null) {
+  const trimmed = value?.trim()
+  return trimmed || null
+}
+
+function safeHttpUrl(value: string | null) {
+  if (!value) return null
+  try {
+    const url = new URL(value)
+    return ['http:', 'https:'].includes(url.protocol) ? url.toString() : null
+  } catch {
+    return null
+  }
+}
+
+function formatUpdatedAt(value?: string | null) {
+  return value?.replace('T', ' ').slice(0, 16) || '—'
+}
+
+const expressCompanyColumns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 170, fixed: 'left', slotName: 'actions' },
+  { key: 'company', label: '公司名称', minWidth: 210, slotName: 'company' },
+  { key: 'companyCode', prop: 'companyCode', label: '编码', minWidth: 120 },
+  { key: 'website', label: '官方网站', minWidth: 210, slotName: 'website' },
+  { key: 'servicePhone', prop: 'servicePhone', label: '客服电话', minWidth: 130, formatter: (row: PlatformExpressCompanyResource) => row.servicePhone || '—' },
+  { key: 'status', label: '状态', width: 100, slotName: 'status' },
+  { key: 'updatedAt', prop: 'updatedAt', label: '更新时间', minWidth: 150, defaultVisible: false, formatter: (row: PlatformExpressCompanyResource) => formatUpdatedAt(row.updatedAt) },
+]
+
+async function loadExpressCompanies() {
+  const sequence = ++loadSequence
+  loading.value = true
+  loadError.value = null
+  try {
+    const result = await listPlatformExpressCompanies(
+      page.value,
+      pageSize.value,
+      appliedFilters.value.keyword,
+      appliedFilters.value.status,
+    )
+    if (sequence !== loadSequence) return
+    rows.value = result.records
+    total.value = result.total
+  } catch (error) {
+    if (sequence !== loadSequence) return
+    rows.value = []
+    total.value = 0
+    loadError.value = getApiErrorDetails(error, '快递公司加载失败，请稍后重试')
+  } finally {
+    if (sequence === loadSequence) loading.value = false
+  }
+}
+
+function applyFilters(model: QueryModel) {
+  appliedFilters.value = {
+    keyword: String(model.keyword || ''),
+    status: (model.status || '') as PlatformExpressCompanyStatus | '',
+  }
+  if (page.value === 1) {
+    void loadExpressCompanies()
+    return
+  }
+  page.value = 1
+}
+
+function openCreate() {
+  editorLoadSequence += 1
+  Object.assign(form, emptyForm())
+  captureBaseline()
+  editorOpen.value = true
+  void formRef.value?.clearValidate()
+}
+
+function assignEditor(row: PlatformExpressCompanyResource) {
+  Object.assign(form, {
+    id: String(row.id),
+    companyCode: row.companyCode,
+    companyName: row.companyName,
+    servicePhone: row.servicePhone,
+    website: row.website,
+    trackingUrlTemplate: row.trackingUrlTemplate,
+    status: row.status,
+    remark: row.remark,
+  })
+  captureBaseline()
+  editorOpen.value = true
+  void formRef.value?.clearValidate()
+}
+
+async function openEdit(row: PlatformExpressCompanyResource) {
+  const sequence = ++editorLoadSequence
+  const id = String(row.id)
+  const pending = new Set(editLoadingIds.value)
+  pending.add(id)
+  editLoadingIds.value = pending
+  try {
+    const result = await getPlatformExpressCompany(row.id)
+    if (sequence !== editorLoadSequence) return
+    assignEditor(result)
+  } catch (error) {
+    if (sequence !== editorLoadSequence) return
+    const details = getApiErrorDetails(error, '快递公司详情加载失败，请稍后重试')
+    ElMessage.error(details.requestId ? `${details.message}（requestId: ${details.requestId}）` : details.message)
+  } finally {
+    const next = new Set(editLoadingIds.value)
+    next.delete(id)
+    editLoadingIds.value = next
+  }
+}
+
+function openImport() {
+  importOpen.value = true
+}
+
+function buildPayload(): SavePlatformExpressCompanyRequest {
+  return {
+    companyCode: form.companyCode.trim(),
+    companyName: form.companyName.trim(),
+    servicePhone: optionalText(form.servicePhone),
+    website: optionalText(form.website),
+    trackingUrlTemplate: optionalText(form.trackingUrlTemplate),
+    status: form.status,
+    remark: optionalText(form.remark),
+  }
+}
+
+async function saveExpressCompany() {
+  const valid = await formRef.value?.validate().catch(() => false)
+  if (!valid) return
+  saving.value = true
+  try {
+    const payload = buildPayload()
+    if (form.id) await updatePlatformExpressCompany(form.id, payload)
+    else await createPlatformExpressCompany(payload)
+    editorOpen.value = false
+    ElMessage.success(form.id ? '快递公司资料已更新' : '快递公司已创建')
+    await loadExpressCompanies()
+  } catch (error) {
+    const details = getApiErrorDetails(error, '快递公司保存失败，请检查后重试')
+    ElMessage.error(details.requestId ? `${details.message}（requestId: ${details.requestId}）` : details.message)
+  } finally {
+    saving.value = false
+  }
+}
+
+async function toggleStatus(row: PlatformExpressCompanyResource) {
+  const nextStatus: PlatformExpressCompanyStatus = row.status === 'ACTIVE' ? 'INACTIVE' : 'ACTIVE'
+  const action = nextStatus === 'ACTIVE' ? '启用' : '停用'
+  try {
+    await ElMessageBox.confirm(
+      `确定${action}“${row.companyName}”吗？${nextStatus === 'INACTIVE' ? '停用后不会再作为可用快递公司。' : ''}`,
+      `${action}快递公司`,
+      { customClass: 'admin-density-confirm', type: nextStatus === 'ACTIVE' ? 'success' : 'warning', confirmButtonText: `确认${action}`, cancelButtonText: '取消' },
+    )
+  } catch {
+    return
+  }
+  const id = String(row.id)
+  const pending = new Set(statusLoadingIds.value)
+  pending.add(id)
+  statusLoadingIds.value = pending
+  try {
+    await changePlatformExpressCompanyStatus(row.id, nextStatus)
+    ElMessage.success(`已${action}${row.companyName}`)
+    await loadExpressCompanies()
+  } catch (error) {
+    const details = getApiErrorDetails(error, `${action}快递公司失败`)
+    ElMessage.error(details.requestId ? `${details.message}（requestId: ${details.requestId}）` : details.message)
+  } finally {
+    const next = new Set(statusLoadingIds.value)
+    next.delete(id)
+    statusLoadingIds.value = next
+  }
+}
+
+watch([page, pageSize], () => { void loadExpressCompanies() })
+onMounted(() => {
+  void loadExpressCompanies()
+})
+</script>
+
+<template>
+  <AdminPage class="admin-density">
+    <div class="business-page express-company-page">
+      <ListPageLayout ariaLabel="快递公司列表">
+        <template #toolbar>
+          <QueryToolbar v-model="filters" class="surface-panel" ariaLabel="快递公司筛选" :fields="queryFields" preference-key="express-companies-query" @search="applyFilters" />
+        </template>
+        <template v-if="loadError" #state>
+    <el-alert type="error" :closable="false" show-icon class="state-alert">
+      <template #title>快递公司加载失败</template>
+      <p>{{ loadError.message }}</p>
+      <ApiErrorMeta :details="loadError" />
+      <el-button size="small" @click="loadExpressCompanies()">重新查询</el-button>
+    </el-alert>
+        </template>
+
+    <section v-if="!loadError" class="surface-panel table-panel">
+      <DataTable
+        v-model:page="page"
+        v-model:page-size="pageSize"
+        :data="rows"
+        :columns="expressCompanyColumns"
+        preference-key="express-companies-table"
+        :loading="loading"
+        :total="total"
+        :page-sizes="[20, 50, 100]"
+        aria-label="快递公司列表"
+        row-key="id"
+        :empty-text="appliedFilters.keyword.trim() || appliedFilters.status ? '暂无符合筛选条件的快递公司' : '暂无快递公司档案'"
+      >
+        <template #toolbar-actions><div class="table-actions"><el-button v-if="access.can('platform:express:import')" :disabled="loading" @click="openImport"><FileUp :size="16" />批量导入</el-button><el-button v-if="access.can('platform:express:create')" type="primary" :disabled="loading" @click="openCreate"><Plus :size="16" />新增快递公司</el-button></div></template>
+        <template #actions="{ row }">
+          <div v-if="access.can('platform:express:edit') || access.can('platform:express:status')" class="table-actions density-actions">
+            <el-button data-tone="neutral" class="density-action"
+              v-if="access.can('platform:express:edit')"
+              size="small"
+
+
+              :disabled="loading"
+              :loading="editLoadingIds.has(String((row as PlatformExpressCompanyResource).id))"
+              @click="openEdit(row as PlatformExpressCompanyResource)"
+            >编辑</el-button>
+            <el-button class="density-action"
+              v-if="access.can('platform:express:status')"
+              size="small"
+
+              :disabled="loading"
+              :data-tone="(row as PlatformExpressCompanyResource).status === 'ACTIVE' ? 'danger' : 'success'"
+              :loading="statusLoadingIds.has(String((row as PlatformExpressCompanyResource).id))"
+              @click="toggleStatus(row as PlatformExpressCompanyResource)"
+            >{{ (row as PlatformExpressCompanyResource).status === 'ACTIVE' ? '停用' : '启用' }}</el-button>
+          </div>
+          <span v-else class="muted-value">仅查看</span>
+        </template>
+        <template #company="{ row }"><div class="express-company-cell"><span><Truck :size="17" /></span><div><strong>{{ (row as PlatformExpressCompanyResource).companyName }}</strong></div></div></template>
+        <template #website="{ row }">
+          <a v-if="safeHttpUrl((row as PlatformExpressCompanyResource).website)" class="external-link" :href="safeHttpUrl((row as PlatformExpressCompanyResource).website)!" target="_blank" rel="noopener noreferrer">访问官网<ExternalLink :size="13" /></a>
+          <span v-else class="muted-value">{{ (row as PlatformExpressCompanyResource).website || '—' }}</span>
+        </template>
+        <template #status="{ row }"><el-tag :type="(row as PlatformExpressCompanyResource).status === 'ACTIVE' ? 'success' : 'info'" effect="light">{{ (row as PlatformExpressCompanyResource).status === 'ACTIVE' ? '启用' : '停用' }}</el-tag></template>
+        <template #empty>
+          <el-empty v-if="!loading" :description="appliedFilters.keyword.trim() || appliedFilters.status ? '暂无符合筛选条件的快递公司' : '暂无快递公司档案'">
+            <el-button v-if="!appliedFilters.keyword.trim() && !appliedFilters.status && access.can('platform:express:create')" type="primary" @click="openCreate"><Plus :size="16" />新增第一家快递公司</el-button>
+          </el-empty>
+        </template>
+        <template #pagination-left="{ total: tableTotal }"><span>平台公共数据 · 共 {{ tableTotal }} 家快递公司</span></template>
+      </DataTable>
+    </section>
+      </ListPageLayout>
+
+    <BatchImportDialog class="admin-density-dialog"
+      v-model="importOpen"
+      title="批量导入快递公司"
+      entity-label="快递公司"
+      success-unit="家"
+      template-file-name="快递公司批量导入模板-v1.xlsx"
+      error-report-file-name="快递公司导入错误报告.csv"
+      :download-template="downloadPlatformExpressCompanyImportTemplate"
+      :import-file="importPlatformExpressCompanies"
+      @success="loadExpressCompanies"
+    />
+
+    <el-drawer v-model="editorOpen" :title="editorTitle" size="580px" class="editor-drawer admin-density admin-density-drawer" :close-on-click-modal="false">
+      <el-form ref="formRef" :model="form" :rules="rules" label-position="top" class="density-form" :disabled="saving">
+        <FormSection class="density-form-section" title="基础信息">
+          <div class="form-grid two-cols">
+            <el-form-item label="快递公司编码" prop="companyCode" required><el-input v-model.trim="form.companyCode" maxlength="50" placeholder="例如 SF" /></el-form-item>
+            <el-form-item label="快递公司名称" prop="companyName" required><el-input v-model.trim="form.companyName" maxlength="128" placeholder="例如 顺丰速运" /></el-form-item>
+          </div>
+          <el-form-item label="状态" prop="status" required><el-radio-group v-model="form.status"><el-radio-button value="ACTIVE">启用</el-radio-button><el-radio-button value="INACTIVE">停用</el-radio-button></el-radio-group></el-form-item>
+        </FormSection>
+        <FormSection class="density-form-section" title="服务配置">
+          <div class="form-grid two-cols">
+            <el-form-item label="客服电话"><el-input v-model.trim="form.servicePhone" maxlength="32" placeholder="例如 95338" /></el-form-item>
+            <el-form-item label="官方网站" prop="website"><el-input v-model.trim="form.website" maxlength="255" placeholder="https://www.example.com" /></el-form-item>
+          </div>
+          <el-form-item label="轨迹查询地址模板"><el-input v-model.trim="form.trackingUrlTemplate" maxlength="500" placeholder="https://example.com/track/{trackingNo}" /></el-form-item>
+          <p class="form-help">可使用 <code>{trackingNo}</code> 作为快递单号占位符；一期不包含轨迹订阅和自动回传。</p>
+        </FormSection>
+        <FormSection class="density-form-section" title="备注"><el-form-item label="内部说明"><el-input v-model.trim="form.remark" type="textarea" :rows="4" maxlength="500" show-word-limit placeholder="请输入适用范围、服务限制或其他说明" /></el-form-item></FormSection>
+      </el-form>
+      <template #footer><div class="drawer-footer"><el-button :disabled="saving" @click="editorOpen = false">取消</el-button><el-button type="primary" :loading="saving" @click="saveExpressCompany"><Save :size="16" />保存快递公司</el-button></div></template>
+    </el-drawer>
+    </div>
+  </AdminPage>
+</template>
+
+<style scoped>
+.express-company-page { gap: var(--admin-space-6); }
+.state-alert p { margin: var(--admin-space-2) 0 0; line-height: 1.55; }
+.state-alert .el-button { margin-top: var(--admin-space-4); }
+.express-company-cell { display: flex; min-width: 0; align-items: center; gap: var(--admin-space-4); }
+.express-company-cell > span { display: grid; width: 34px; height: 34px; flex: 0 0 34px; place-items: center; border: 1px solid var(--cc-border); border-radius: var(--admin-radius); background: #f8fafc; color: var(--cc-primary); }
+.express-company-cell > div { display: flex; min-width: 0; flex-direction: column; gap: 3px; }
+.express-company-cell strong { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.external-link { display: inline-flex; align-items: center; gap: 5px; color: var(--cc-primary); font-size: var(--admin-font-caption); text-decoration: none; }
+.external-link:hover { text-decoration: underline; }
+.tracking-template { display: block; max-width: 100%; color: #475467; font-family: "Cascadia Code", Consolas, monospace; font-size: var(--admin-font-caption); overflow-wrap: anywhere; }
+.remark-cell { display: -webkit-box; overflow: hidden; line-height: 1.5; -webkit-box-orient: vertical; -webkit-line-clamp: 2; }
+.form-help code { color: #475467; font-family: "Cascadia Code", Consolas, monospace; }
+.panel-actions { display: flex; flex-wrap: wrap; justify-content: flex-end; gap: var(--admin-space-3); }
+.panel-actions .el-button { margin-left: 0; }
+@media (max-width: 720px) {
+  .panel-actions, .panel-actions .el-button { width: 100%; }
+  .express-company-page :deep(.query-toolbar__actions) { width: 100%; }
+}
+</style>
diff --git a/src/modules/master-data/index.ts b/src/modules/master-data/index.ts
new file mode 100644
index 00000000..676fa1fd
--- /dev/null
+++ b/src/modules/master-data/index.ts
@@ -0,0 +1 @@
+export * from './counterparties'
diff --git a/src/modules/master-data/routes.ts b/src/modules/master-data/routes.ts
new file mode 100644
index 00000000..e24951f6
--- /dev/null
+++ b/src/modules/master-data/routes.ts
@@ -0,0 +1,16 @@
+import type { RouteRecordRaw } from 'vue-router'
+
+export const masterDataRoutes = [
+  {
+    path: 'master-data/express-companies',
+    name: 'express-companies',
+    component: () => import('@/modules/master-data/express-companies/pages/ExpressCompaniesView.vue'),
+    meta: { title: '快递公司', description: '查询平台可用的快递公司档案与公开联系信息', permission: 'platform:express:list' },
+  },
+  {
+    path: 'master-data/counterparties',
+    name: 'counterparties',
+    component: () => import('@/modules/master-data/counterparties/pages/PartnersView.vue'),
+    meta: { title: '往来单位', description: '维护客户、供应商及客户/供应商双重类型单位档案', permission: 'platform:counterparty:list' },
+  },
+] satisfies RouteRecordRaw[]
diff --git a/src/modules/notifications/PROTOTYPE_MATRIX.md b/src/modules/notifications/PROTOTYPE_MATRIX.md
new file mode 100644
index 00000000..7d95afed
--- /dev/null
+++ b/src/modules/notifications/PROTOTYPE_MATRIX.md
@@ -0,0 +1,20 @@
+# Admin 消息中心原型核对矩阵
+
+原型事实来源：`docs/悦/货代SAAS平台后台/prototype-src/modules/11-system-messages.html`（260–290 行）与 `prototype-src/overlays.html`（354–395 行）。接口事实来源：`iam/src/main/resources/openapi/notification-v1.yaml`。当前实现仅支持站内信，不扩展微信、邮件或短信渠道。
+
+| 页面 | 操作 | 原型承载方式 | 当前实现 | 契约差异与结论 |
+|---|---|---|---|---|
+| 消息管理 | 列表/查询 | `page-msg-manage` 页面内表格 | `/notifications/messages` 展示通知任务，支持任务号/标题、分类、状态查询；操作列固定第一列 | 冻结契约只提供任务列表，未提供按消息正文管理的列表；按任务 DTO 展示任务号、接收人数、定时/发送时间与状态 |
+| 消息管理 | 新建消息 | `modal-msg-create`，约 680px 居中弹框 | 680px `AppDialog`；选择激活模板、平台员工/指定企业范围、接收对象、模板变量 | 企业选择按现有 API 的 `tenantId` 字段提交；页面统一使用“企业/客户”文案 |
+| 消息管理 | 立即/定时发送 | 新建消息弹框内 | 调用 `POST /platform/v1/notifications`；立即发送传 `scheduledAt=null`，定时发送传 ISO 时间；生成幂等键 | 契约已覆盖两种发送方式；仅创建任务，不静默模拟发送成功 |
+| 消息管理 | 草稿 | 新建消息弹框内“存为草稿” | 不展示 | 冻结契约没有消息草稿创建、更新或查询 API，不能提供伪草稿 |
+| 消息管理 | 取消/重试 | 原型未明确 | CREATED/SCHEDULED 可取消，RETRYING/DEAD 可重试 | 按冻结任务 API 与状态约束补充，分别受 `task:cancel`、`task:retry` 权限控制 |
+| 消息管理 | 详情/投递明细 | 原型仅有详情按钮，未定义容器 | 当前 `getTask` 打开 820px `AppDrawer`，展示任务摘要、失败原因与收件人投递明细 | 保留当前正式能力；不把投递明细改称已读统计 |
+| 模板管理 | 列表/查询 | `page-msg-template` 页面内表格 | `/notifications/templates` 查询 CODE、分类、名称/标题、状态；操作列固定第一列 | 对接模板分页 API；原型导入/导出因无 API 不展示 |
+| 模板管理 | 新增模板 | `modal-msg-template-create`，约 760px 居中弹框 | 760px `AppDialog`；CODE、名称、分类、标题/正文、变量白名单、预览；保存为 DRAFT | 仅支持 `IN_APP`，不展示真实渠道选择 |
+| 模板管理 | 编辑模板 | 原型仅有编辑按钮，未定义容器 | 复用同尺寸模板弹框，仅 DRAFT 可编辑，CODE 不可变并携带 version | 冻结契约明确只允许编辑草稿，复用表单避免重复交互 |
+| 模板管理 | 状态流转 | 原型未定义 | DRAFT 可激活，ACTIVE 可禁用，DISABLED 无操作 | 严格执行 `DRAFT -> ACTIVE -> DISABLED`；禁用后不可恢复 |
+| 我的消息 | 列表、已读与详情 | `page-msg-my`；详情容器原型未定义 | 当前 `/notifications` 正式路由及顶部入口，详情为 680px `AppDrawer` | 按实际平台收件箱入口保留权限和标记已读逻辑 |
+| 顶部入口 | 消息中心 | `topMessageMenu` 顶部下拉，左侧无消息菜单 | 当前按权限展示“我的消息”“消息管理”“模板管理” | 三个正式路由均纳入样式核对，见 `docs/Admin消息中心样式核对记录.md` |
+
+接口依赖：所有响应经 `{code,data}` 解包；分页统一读取 `records/page/size/total/pages`；响应中的 `int64` ID 在前端保持字符串。写请求中的企业、用户和成员 ID 也在类型适配边界保持数字字符串，避免 JavaScript 大整数精度损失，由服务端 Long DTO 解析。
diff --git a/src/modules/notifications/api/notificationCenter.test.ts b/src/modules/notifications/api/notificationCenter.test.ts
new file mode 100644
index 00000000..ae3ddd6f
--- /dev/null
+++ b/src/modules/notifications/api/notificationCenter.test.ts
@@ -0,0 +1,90 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import {
+  cancelTask,
+  changeTemplateStatus,
+  createNotification,
+  getMyNotification,
+  getMyUnreadNotificationCount,
+  getTask,
+  listMyNotifications,
+  listTasks,
+  listTemplates,
+  markAllMyNotificationsRead,
+  markMyNotificationRead,
+  retryTask,
+  updateTemplate,
+} from './notificationCenter'
+
+vi.mock('@/shared/api/http', () => ({
+  http: { get: vi.fn(), post: vi.fn(), put: vi.fn() },
+  unwrapApiResponse: <T>(response: { data: T }) => response.data,
+}))
+
+const envelope = <T>(data: T) => ({ code: '200', data })
+const template = { id: 12, templateCode: 'ORDER_SENT', templateName: '订单已发货', category: 'ORDER', channel: 'IN_APP' as const, titleTemplate: '已发货', bodyTemplate: '正文', variableWhitelist: [], status: 'DRAFT' as const, version: 1 }
+const task = { id: 13, taskNo: 'NT-13', category: 'ORDER', title: '已发货', status: 'CREATED' as const, recipientCount: 2, scheduledAt: null, sentAt: null, duplicated: false }
+const taskDetail = { id: 13, taskNo: 'NT-13', category: 'ORDER', title: '已发货', status: 'DEAD' as const, recipientCount: 1, attemptCount: 3, scheduledAt: null, sentAt: null, lastError: 'gateway timeout', recipients: [{ id: 21, displayName: '客户成员', appCode: 'MERCHANT', status: 'FAILED', failureReason: 'gateway timeout', deliveredAt: null }] }
+
+describe('notificationCenter API', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it('posts the frozen create-notification DTO unchanged', async () => {
+    vi.mocked(http.post).mockResolvedValueOnce(envelope(task))
+    const payload = { tenantId: '0', templateCode: 'ORDER_SENT', recipientType: 'PLATFORM_ROLE' as const, roleCode: 'PLATFORM_ADMIN', variables: {}, scheduledAt: null, idempotencyKey: 'notification-1' }
+    expect((await createNotification(payload)).id).toBe('13')
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/notifications', payload)
+  })
+
+  it('uses template list, update, and one-way status paths', async () => {
+    vi.mocked(http.get).mockResolvedValueOnce(envelope({ records: [template], page: 1, size: 20, total: 1, pages: 1 }))
+    vi.mocked(http.put).mockResolvedValue(envelope(template))
+    await listTemplates({ page: 1, size: 20, status: 'DRAFT' })
+    const update = { templateName: '新名称', category: 'ORDER', titleTemplate: '标题', bodyTemplate: '正文', variableWhitelist: [], version: 1 }
+    await updateTemplate('12', update)
+    await changeTemplateStatus('12', 'ACTIVE', 1)
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/notification-templates', { params: { page: 1, size: 20, status: 'DRAFT' } })
+    expect(http.put).toHaveBeenNthCalledWith(1, '/platform/v1/notification-templates/12', update)
+    expect(http.put).toHaveBeenNthCalledWith(2, '/platform/v1/notification-templates/12/status', { targetStatus: 'ACTIVE', version: 1 })
+  })
+
+  it('uses task list, cancel, and retry paths without request bodies', async () => {
+    vi.mocked(http.get).mockResolvedValueOnce(envelope({ records: [task], page: 1, size: 20, total: 1, pages: 1 }))
+    vi.mocked(http.put).mockResolvedValue(envelope(task))
+    await listTasks({ page: 1, size: 20, status: 'CREATED' })
+    await cancelTask('13')
+    await retryTask('13')
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/notification-tasks', { params: { page: 1, size: 20, status: 'CREATED' } })
+    expect(http.put).toHaveBeenNthCalledWith(1, '/platform/v1/notification-tasks/13/cancel')
+    expect(http.put).toHaveBeenNthCalledWith(2, '/platform/v1/notification-tasks/13/retry')
+  })
+
+  it('loads task failure evidence and normalizes nested long ids', async () => {
+    vi.mocked(http.get).mockResolvedValueOnce(envelope(taskDetail))
+    const result = await getTask('13')
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/notification-tasks/13')
+    expect(result.id).toBe('13')
+    expect(result.recipients[0]?.id).toBe('21')
+    expect(result.lastError).toBe('gateway timeout')
+  })
+  it('uses platform inbox paths and normalizes inbox ids', async () => {
+    const inbox = { id: 14, category: 'ORDER', title: 'order notice', summary: 'summary', status: 'UNREAD' as const, sentAt: '2026-08-27T10:00:00', readAt: null }
+    const detail = { ...inbox, body: 'body', sourceType: null, sourceId: null }
+    vi.mocked(http.get)
+      .mockResolvedValueOnce(envelope({ records: [inbox], page: 1, size: 20, total: 1, pages: 1 }))
+      .mockResolvedValueOnce(envelope(detail))
+      .mockResolvedValueOnce(envelope({ unreadCount: 1 }))
+    vi.mocked(http.put)
+      .mockResolvedValueOnce(envelope(detail))
+      .mockResolvedValueOnce(envelope({ updatedCount: 1 }))
+    const result = await listMyNotifications({ page: 1, size: 20, status: 'UNREAD' })
+    await getMyNotification('14')
+    await markMyNotificationRead('14')
+    await markAllMyNotificationsRead()
+    expect(await getMyUnreadNotificationCount()).toBe(1)
+    expect(result.records[0]?.id).toBe('14')
+    expect(http.get).toHaveBeenNthCalledWith(1, '/platform/v1/notifications', { params: { page: 1, size: 20, status: 'UNREAD' } })
+    expect(http.put).toHaveBeenNthCalledWith(1, '/platform/v1/notifications/14/read')
+    expect(http.put).toHaveBeenNthCalledWith(2, '/platform/v1/notifications/read-all')
+  })
+})
diff --git a/src/modules/notifications/api/notificationCenter.ts b/src/modules/notifications/api/notificationCenter.ts
new file mode 100644
index 00000000..c1219550
--- /dev/null
+++ b/src/modules/notifications/api/notificationCenter.ts
@@ -0,0 +1,54 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import type { CreateNotificationRequest, CreateTemplateRequest, NotificationInboxDetail, NotificationInboxItem, NotificationInboxStatus, NotificationTask, NotificationTaskDetail, NotificationTaskStatus, NotificationTemplate, PageResult, TemplateStatus, UpdateTemplateRequest } from '../types'
+
+type RawId = string | number
+type RawPage<T> = Omit<PageResult<T>, 'page' | 'size' | 'total' | 'pages'> & { page: RawId; size: RawId; total: RawId; pages: RawId }
+type RawTemplate = Omit<NotificationTemplate, 'id'> & { id: RawId }
+type RawTask = Omit<NotificationTask, 'id'> & { id: RawId }
+type RawTaskDetail = Omit<NotificationTaskDetail, 'id' | 'recipients'> & { id: RawId; recipients: Array<Omit<NotificationTaskDetail['recipients'][number], 'id'> & { id: RawId }> }
+type RawInbox = Omit<NotificationInboxItem, 'id'> & { id: RawId }
+type RawInboxDetail = Omit<NotificationInboxDetail, 'id'> & { id: RawId }
+
+const notificationPath = '/platform/v1/notifications'
+const templatePath = '/platform/v1/notification-templates'
+const taskPath = '/platform/v1/notification-tasks'
+const id = (value: RawId) => String(value)
+const page = <T>(value: RawPage<T>): PageResult<T> => ({ ...value, page: Number(value.page), size: Number(value.size), total: Number(value.total), pages: Number(value.pages) })
+const template = (value: RawTemplate): NotificationTemplate => ({ ...value, id: id(value.id) })
+const task = (value: RawTask): NotificationTask => ({ ...value, id: id(value.id) })
+const taskDetail = (value: RawTaskDetail): NotificationTaskDetail => ({ ...value, id: id(value.id), recipients: value.recipients.map((recipient) => ({ ...recipient, id: id(recipient.id) })) })
+const inbox = (value: RawInbox): NotificationInboxItem => ({ ...value, id: id(value.id), summary: value.summary ?? '', readAt: value.readAt ?? null })
+const inboxDetail = (value: RawInboxDetail): NotificationInboxDetail => ({ ...value, id: id(value.id), summary: value.summary ?? '', readAt: value.readAt ?? null, body: value.body ?? '', sourceType: value.sourceType ?? null, sourceId: value.sourceId ?? null })
+
+export async function createNotification(payload: CreateNotificationRequest) { const response = await http.post<ApiEnvelope<RawTask>, ApiEnvelope<RawTask>>(notificationPath, payload); return task(unwrapApiResponse(response)) }
+export async function listTemplates(query: { page: number; size: number; templateCode?: string; category?: string; title?: string; status?: TemplateStatus }) { const response = await http.get<ApiEnvelope<RawPage<RawTemplate>>, ApiEnvelope<RawPage<RawTemplate>>>(templatePath, { params: query }); const data = unwrapApiResponse(response); return page({ ...data, records: data.records.map(template) }) }
+export async function createTemplate(payload: CreateTemplateRequest) { const response = await http.post<ApiEnvelope<RawTemplate>, ApiEnvelope<RawTemplate>>(templatePath, payload); return template(unwrapApiResponse(response)) }
+export async function updateTemplate(templateId: string, payload: UpdateTemplateRequest) { const response = await http.put<ApiEnvelope<RawTemplate>, ApiEnvelope<RawTemplate>>(`${templatePath}/${encodeURIComponent(templateId)}`, payload); return template(unwrapApiResponse(response)) }
+export async function changeTemplateStatus(templateId: string, targetStatus: Exclude<TemplateStatus, 'DRAFT'>, version: number) { const response = await http.put<ApiEnvelope<RawTemplate>, ApiEnvelope<RawTemplate>>(`${templatePath}/${encodeURIComponent(templateId)}/status`, { targetStatus, version }); return template(unwrapApiResponse(response)) }
+export async function listTasks(query: { page: number; size: number; taskNo?: string; category?: string; title?: string; status?: NotificationTaskStatus }) { const response = await http.get<ApiEnvelope<RawPage<RawTask>>, ApiEnvelope<RawPage<RawTask>>>(taskPath, { params: query }); const data = unwrapApiResponse(response); return page({ ...data, records: data.records.map(task) }) }
+export async function getTask(taskId: string) { const response = await http.get<ApiEnvelope<RawTaskDetail>, ApiEnvelope<RawTaskDetail>>(`${taskPath}/${encodeURIComponent(taskId)}`); return taskDetail(unwrapApiResponse(response)) }
+export async function cancelTask(taskId: string) { const response = await http.put<ApiEnvelope<RawTask>, ApiEnvelope<RawTask>>(`${taskPath}/${encodeURIComponent(taskId)}/cancel`); return task(unwrapApiResponse(response)) }
+export async function retryTask(taskId: string) { const response = await http.put<ApiEnvelope<RawTask>, ApiEnvelope<RawTask>>(`${taskPath}/${encodeURIComponent(taskId)}/retry`); return task(unwrapApiResponse(response)) }
+
+const inboxPath = '/platform/v1/notifications'
+export async function listMyNotifications(query: { page: number; size: number; status?: NotificationInboxStatus; category?: string }) {
+  const response = await http.get<ApiEnvelope<RawPage<RawInbox>>, ApiEnvelope<RawPage<RawInbox>>>(inboxPath, { params: query })
+  const data = unwrapApiResponse(response)
+  return page({ ...data, records: data.records.map(inbox) })
+}
+export async function getMyNotification(notificationId: string) {
+  const response = await http.get<ApiEnvelope<RawInboxDetail>, ApiEnvelope<RawInboxDetail>>(`${inboxPath}/${encodeURIComponent(notificationId)}`)
+  return inboxDetail(unwrapApiResponse(response))
+}
+export async function markMyNotificationRead(notificationId: string) {
+  const response = await http.put<ApiEnvelope<RawInboxDetail>, ApiEnvelope<RawInboxDetail>>(`${inboxPath}/${encodeURIComponent(notificationId)}/read`)
+  return inboxDetail(unwrapApiResponse(response))
+}
+export async function markAllMyNotificationsRead() {
+  const response = await http.put<ApiEnvelope<{ updatedCount: number }>, ApiEnvelope<{ updatedCount: number }>>(`${inboxPath}/read-all`)
+  return unwrapApiResponse(response)
+}
+export async function getMyUnreadNotificationCount() {
+  const response = await http.get<ApiEnvelope<{ unreadCount: number }>, ApiEnvelope<{ unreadCount: number }>>(`${inboxPath}/unread-count`)
+  return unwrapApiResponse(response).unreadCount
+}
diff --git a/src/modules/notifications/components/MessageComposerDialog.vue b/src/modules/notifications/components/MessageComposerDialog.vue
new file mode 100644
index 00000000..145eae30
--- /dev/null
+++ b/src/modules/notifications/components/MessageComposerDialog.vue
@@ -0,0 +1,81 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, reactive, ref, watch } from 'vue'
+import { ElMessage } from 'element-plus'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import OperationErrorToast from '@/shared/components/OperationErrorToast.vue'
+import { PlatformTenantSelector } from '@/modules/iam'
+import { createNotification } from '../api/notificationCenter'
+import type { NotificationTemplate, RecipientType } from '../types'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+
+const props = defineProps<{ templates: NotificationTemplate[] }>()
+const open = defineModel<boolean>({ default: false })
+const emit = defineEmits<{ success: [] }>()
+const submitting = ref(false)
+const error = ref<ApiErrorDetails | null>(null)
+const scope = ref<'platform' | 'customer'>('platform')
+const recipientIdsText = ref('')
+const variables = reactive<Record<string, string>>({})
+const form = reactive({ tenantId: '0', templateCode: '', recipientType: 'PLATFORM_ROLE' as RecipientType, roleCode: '', scheduledAt: '' })
+const selectedTemplate = computed(() => props.templates.find((item) => item.templateCode === form.templateCode) ?? null)
+function toDateTimeValue(date: Date) {
+  const pad = (value: number) => String(value).padStart(2, '0')
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`
+}
+const scheduled = computed({
+  get: () => Boolean(form.scheduledAt),
+  set: (value: boolean) => {
+    if (value && !form.scheduledAt) form.scheduledAt = toDateTimeValue(new Date(Date.now() + 5 * 60 * 1000))
+    if (!value) form.scheduledAt = ''
+  },
+})
+const needsIds = computed(() => ['USER', 'MEMBERSHIP'].includes(form.recipientType))
+const needsRole = computed(() => ['TENANT_ROLE', 'PLATFORM_ROLE'].includes(form.recipientType))
+const allowedRecipients = computed(() => scope.value === 'platform'
+  ? [{ label: '指定平台用户', value: 'USER' }, { label: '平台角色', value: 'PLATFORM_ROLE' }]
+  : [{ label: '指定企业成员', value: 'USER' }, { label: '企业角色', value: 'TENANT_ROLE' }, { label: '企业全部成员', value: 'TENANT_ALL' }])
+
+watch(scope, (value) => { form.tenantId = value === 'platform' ? '0' : ''; form.recipientType = value === 'platform' ? 'PLATFORM_ROLE' : 'TENANT_ALL'; form.roleCode = ''; recipientIdsText.value = '' })
+watch(selectedTemplate, (value) => { for (const key of Object.keys(variables)) delete variables[key]; for (const key of value?.variableWhitelist ?? []) variables[key] = '' })
+
+function reset() { scope.value = 'platform'; Object.assign(form, { tenantId: '0', templateCode: '', recipientType: 'PLATFORM_ROLE', roleCode: '', scheduledAt: '' }); recipientIdsText.value = ''; error.value = null; for (const key of Object.keys(variables)) delete variables[key] }
+const MAX_LONG_ID = 9_223_372_036_854_775_807n
+function parseIds() { return [...new Set(recipientIdsText.value.split(/[\s,，]+/).map((value) => value.trim()).filter(Boolean))] }
+function idempotencyKey() { return typeof crypto !== 'undefined' && crypto.randomUUID ? crypto.randomUUID() : `notification-${Date.now()}-${Math.random().toString(36).slice(2)}` }
+async function submit() {
+  error.value = null
+  const recipientIds = parseIds()
+  if (!form.templateCode) return ElMessage.warning('请选择已激活模板')
+  if (scope.value === 'customer' && !form.tenantId) return ElMessage.warning('请选择目标企业')
+  if (needsIds.value && (!recipientIds.length || recipientIds.length > 1000 || recipientIds.some((value) => !/^\d+$/.test(value) || BigInt(value) > MAX_LONG_ID))) return ElMessage.warning('请输入有效的数字用户 ID，单次最多 1000 个且不能超过 19 位')
+  if (needsRole.value && !form.roleCode.trim()) return ElMessage.warning('请输入角色编码')
+  if (Object.values(variables).some((value) => !value.trim())) return ElMessage.warning('请填写全部模板变量')
+  submitting.value = true
+  try {
+    await createNotification({ tenantId: form.tenantId, templateCode: form.templateCode, recipientType: form.recipientType, ...(needsIds.value ? { recipientIds } : {}), ...(needsRole.value ? { roleCode: form.roleCode.trim() } : {}), variables: { ...variables }, scheduledAt: form.scheduledAt ? new Date(form.scheduledAt).toISOString() : null, idempotencyKey: idempotencyKey() })
+    ElMessage.success(form.scheduledAt ? '消息已定时' : '消息发送任务已创建')
+    open.value = false; reset(); emit('success')
+  } catch (reason) { error.value = getApiErrorDetails(reason, '消息发送失败') } finally { submitting.value = false }
+}
+</script>
+
+<template>
+  <AppDialog class="admin-density-dialog" v-model="open" title="新建消息" width="min(680px, calc(100vw - 28px))" :show-confirm="false" destroy-on-close @cancel="reset">
+    <OperationErrorToast :details="error" />
+    <el-form class="message-form density-form" label-position="top">
+      <div class="form-grid"><el-form-item label="发送范围" required><el-segmented v-model="scope" :options="[{ label: '平台员工', value: 'platform' }, { label: '指定企业', value: 'customer' }]" /></el-form-item><el-form-item label="发送方式"><el-input model-value="站内信" disabled /></el-form-item></div>
+      <PlatformTenantSelector v-if="scope === 'customer'" v-model="form.tenantId" label="目标企业" />
+      <el-form-item label="消息模板" required><el-select v-model="form.templateCode" filterable placeholder="请选择已激活模板"><el-option v-for="item in templates" :key="item.id" :label="`${item.templateName}（${item.templateCode}）`" :value="item.templateCode" /></el-select></el-form-item>
+      <div class="form-grid"><el-form-item label="接收对象" required><el-select v-model="form.recipientType"><el-option v-for="item in allowedRecipients" :key="item.value" :label="item.label" :value="item.value" /></el-select></el-form-item><el-form-item v-if="needsRole" label="角色编码" required><el-input v-model="form.roleCode" maxlength="64" placeholder="请输入服务端角色编码" /></el-form-item></div>
+      <el-form-item v-if="needsIds" label="接收人用户 ID" required><el-input v-model="recipientIdsText" type="textarea" :rows="2" placeholder="多个用户 ID 使用逗号或换行分隔，最多 1000 个" /></el-form-item>
+      <section v-if="selectedTemplate?.variableWhitelist.length" class="variables"><strong>模板变量</strong><el-form-item v-for="key in selectedTemplate.variableWhitelist" :key="key" :label="key" required><el-input v-model="variables[key]" maxlength="2000" placeholder="请输入变量值" /></el-form-item></section>
+      <el-form-item label="定时发送"><div class="schedule-row"><el-switch v-model="scheduled" aria-label="启用定时发送" /><span>启用</span><el-date-picker v-model="form.scheduledAt" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" placeholder="选择发送时间" :disabled="!scheduled" /></div></el-form-item>
+    </el-form>
+    <template #footer="{ close }"><div class="dialog-actions"><el-button :disabled="submitting" @click="close">取消</el-button><el-button type="primary" :loading="submitting" @click="submit">{{ scheduled ? '确认定时发送' : '立即发送' }}</el-button></div></template>
+  </AppDialog>
+</template>
+
+<style scoped>
+.message-form { margin-top: var(--admin-space-5); }.form-grid { display: grid; grid-template-columns: repeat(2,minmax(0,1fr)); gap: var(--admin-space-5); }.form-grid :deep(.el-select),.message-form > :deep(.el-form-item .el-select),.schedule-row :deep(.el-date-editor) { width: 100%; }.variables { margin-bottom: var(--admin-space-5); padding: var(--admin-space-5); border: 1px solid var(--cc-border); border-radius: var(--admin-radius); }.variables > strong { display: block; margin-bottom: var(--admin-space-5); font-size: var(--admin-font-body); }.schedule-row { display:grid;width:100%;grid-template-columns:auto auto minmax(180px,1fr);align-items:center;gap:var(--admin-space-3) }.dialog-actions {display:flex;justify-content:flex-end;gap:var(--admin-space-4)}.dialog-actions :deep(.el-button){margin-left:0}@media(max-width:560px){.form-grid{grid-template-columns:1fr;gap:0}.schedule-row{grid-template-columns:auto 1fr}.schedule-row :deep(.el-date-editor){grid-column:1/-1}}
+</style>
diff --git a/src/modules/notifications/components/TemplateEditorDialog.vue b/src/modules/notifications/components/TemplateEditorDialog.vue
new file mode 100644
index 00000000..39d3865d
--- /dev/null
+++ b/src/modules/notifications/components/TemplateEditorDialog.vue
@@ -0,0 +1,48 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, reactive, ref, watch } from 'vue'
+import { ElMessage } from 'element-plus'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import OperationErrorToast from '@/shared/components/OperationErrorToast.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { createTemplate, updateTemplate } from '../api/notificationCenter'
+import type { NotificationTemplate } from '../types'
+
+const props = defineProps<{ template?: NotificationTemplate | null }>()
+const open = defineModel<boolean>({ default: false })
+const emit = defineEmits<{ success: [] }>()
+const submitting = ref(false)
+const error = ref<ApiErrorDetails | null>(null)
+const contentInput = ref<{ textarea?: HTMLTextAreaElement } | null>(null)
+const whitelistText = ref('')
+const form = reactive({ code: '', name: '', category: '', title: '', content: '' })
+const editing = computed(() => Boolean(props.template))
+const preview = computed(() => form.title || form.content ? `[站内信] ${form.title || '未填写标题'}\n${form.content || '未填写模板内容'}` : '填写标题和内容后，将在这里显示预览效果。')
+const whitelist = computed(() => [...new Set(whitelistText.value.split(/[\s,，]+/).map((v) => v.trim()).filter(Boolean))])
+
+watch([open, () => props.template], ([isOpen]) => { if (!isOpen) return; const item = props.template; Object.assign(form, item ? { code: item.templateCode, name: item.templateName, category: item.category, title: item.titleTemplate, content: item.bodyTemplate } : { code: '', name: '', category: '', title: '', content: '' }); whitelistText.value = item?.variableWhitelist.join(', ') ?? ''; error.value = null }, { immediate: true })
+function normalizeCode(value: string) { form.code = value.replace(/[^A-Za-z0-9_]/g, '').toUpperCase() }
+function insertVariable(name: string) { if (!whitelist.value.includes(name)) whitelistText.value = [...whitelist.value, name].join(', '); const textarea = contentInput.value?.textarea; const value = `\${${name}}`; const start = textarea?.selectionStart ?? form.content.length; const end = textarea?.selectionEnd ?? start; form.content = `${form.content.slice(0,start)}${value}${form.content.slice(end)}`.slice(0,10000) }
+async function submit() {
+  error.value = null
+  if (!/^[A-Z][A-Z0-9_]{0,63}$/.test(form.code)) return ElMessage.warning('模板CODE须以字母开头，仅支持大写字母、数字和下划线')
+  if (!form.name.trim() || !form.category.trim() || !form.title.trim() || !form.content.trim()) return ElMessage.warning('请填写完整模板信息')
+  if (whitelist.value.some((key) => !/^[a-z][a-z0-9_]{0,31}$/.test(key))) return ElMessage.warning('变量名须以小写字母开头，仅支持小写字母、数字和下划线')
+  const payload = { templateName: form.name.trim(), category: form.category.trim(), titleTemplate: form.title.trim(), bodyTemplate: form.content.trim(), variableWhitelist: whitelist.value }
+  submitting.value = true
+  try { if (props.template) await updateTemplate(props.template.id, { ...payload, version: props.template.version }); else await createTemplate({ templateCode: form.code, ...payload }); ElMessage.success(props.template ? '模板已更新' : '模板草稿已创建'); open.value = false; emit('success') } catch (reason) { error.value = getApiErrorDetails(reason, '模板保存失败') } finally { submitting.value = false }
+}
+</script>
+
+<template>
+  <AppDialog class="admin-density-dialog" v-model="open" :title="editing ? '编辑消息模板' : '新增消息模板'" width="min(760px, calc(100vw - 28px))" :show-confirm="false" destroy-on-close>
+    <OperationErrorToast :details="error" />
+    <el-alert title="首期仅支持站内信；新模板保存为草稿，草稿激活后不可再编辑。" type="info" :closable="false" show-icon />
+    <el-form class="template-form density-form" label-position="top"><div class="form-grid"><el-form-item label="模板CODE" required><el-input :model-value="form.code" maxlength="64" :disabled="editing" placeholder="如：ORDER_SHIPPED_NOTICE" @update:model-value="normalizeCode(String($event))" /></el-form-item><el-form-item label="模板名称" required><el-input v-model="form.name" maxlength="128" placeholder="请输入模板名称" /></el-form-item></div><div class="form-grid"><el-form-item label="业务分类" required><el-input v-model="form.category" maxlength="64" placeholder="请输入业务分类" /></el-form-item><el-form-item label="模板类型"><el-input model-value="站内信" disabled /></el-form-item></div><el-form-item label="消息标题模板" required><el-input v-model="form.title" maxlength="256" show-word-limit placeholder="请输入消息标题模板" /></el-form-item><el-form-item label="消息正文模板" required><el-input ref="contentInput" v-model="form.content" type="textarea" :rows="6" maxlength="10000" show-word-limit placeholder="请输入消息正文模板" /></el-form-item><el-form-item label="变量白名单"><el-input v-model="whitelistText" placeholder="多个变量使用逗号分隔，如 customer_name, order_no" /></el-form-item><div class="variable-row"><span>常用变量</span><el-button v-for="name in ['customer_name','order_no','container_no','amount','date']" :key="name" size="small" @click="insertVariable(name)">{{ name }}</el-button></div><section class="template-preview"><strong>内容预览</strong><p>{{ preview }}</p></section></el-form>
+    <template #footer="{ close }"><div class="dialog-actions"><el-button :disabled="submitting" @click="close">取消</el-button><el-button type="primary" :loading="submitting" @click="submit">保存模板</el-button></div></template>
+  </AppDialog>
+</template>
+
+<style scoped>
+.template-form{margin-top:var(--admin-space-5)}.form-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:var(--admin-space-5)}.variable-row{display:flex;flex-wrap:wrap;align-items:center;gap:var(--admin-space-3);margin-bottom:var(--admin-space-5);color:var(--cc-muted);font-size:var(--admin-font-caption)}.variable-row :deep(.el-button){margin-left:0}.template-preview{overflow:hidden;border:1px solid var(--cc-border);border-radius:var(--admin-radius)}.template-preview strong{display:block;padding:var(--admin-space-3) var(--admin-space-5);border-bottom:1px solid var(--cc-border);background:var(--admin-label-bg);font-size:var(--admin-font-body)}.template-preview p{min-height:76px;margin:0;padding:var(--admin-space-5);white-space:pre-wrap;overflow-wrap:anywhere;color:var(--cc-muted);font-size:var(--admin-font-body);line-height:1.7}.dialog-actions{display:flex;justify-content:flex-end;gap:var(--admin-space-4)}.dialog-actions :deep(.el-button){margin-left:0}@media(max-width:560px){.form-grid{grid-template-columns:1fr;gap:0}}
+</style>
diff --git a/src/modules/notifications/notifications.test.ts b/src/modules/notifications/notifications.test.ts
new file mode 100644
index 00000000..af9353a6
--- /dev/null
+++ b/src/modules/notifications/notifications.test.ts
@@ -0,0 +1,80 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { mount } from '@vue/test-utils'
+import { describe, expect, it } from 'vitest'
+import MessageComposerDialog from './components/MessageComposerDialog.vue'
+import TemplateEditorDialog from './components/TemplateEditorDialog.vue'
+
+const source = (path: string) => readFileSync(fileURLToPath(new URL(path, import.meta.url)), 'utf8')
+
+const dialogStubs = {
+  AppDialog: { props: ['width'], template: '<div class="dialog" :data-width="width"><slot /><slot name="footer" :close="() => {}" /></div>' },
+  ApiErrorMeta: true,
+  PlatformTenantSelector: true,
+  'el-alert': true,
+  'el-form': { template: '<form><slot /></form>' },
+  'el-form-item': { template: '<label><slot /></label>' },
+  'el-segmented': true,
+  'el-select': { template: '<select><slot /></select>' },
+  'el-option': true,
+  'el-input': true,
+  'el-switch': true,
+  'el-date-picker': true,
+  'el-button': { props: ['disabled'], template: '<button :disabled="disabled"><slot /></button>' },
+}
+
+describe('notification center contract UI', () => {
+  it.each([
+    './pages/MessageManagementView.vue',
+    './pages/MessageTemplatesView.vue',
+  ])('keeps actions as the first table column in %s', (path) => {
+    const content = source(path)
+    expect(content).toMatch(/const columns:[^=]+\s*=\s*\[\{key:'actions',label:'操作'/)
+  })
+
+  it('does not expose unsupported clear-read or disabled-template restore actions', () => {
+    const templates = source('./pages/MessageTemplatesView.vue')
+    expect(templates).toContain("status!=='DISABLED'")
+    expect(templates).toContain("status==='DRAFT'?'激活':'禁用'")
+  })
+
+  it('exposes read-only task delivery evidence behind the task list contract', () => {
+    const management = source('./pages/MessageManagementView.vue')
+    expect(management).toContain('getTask(row.id)')
+    expect(management).toContain('消息任务详情')
+    expect(management).toContain('任务失败原因')
+    expect(management).toContain('收件人投递明细')
+    expect(management).toContain('failureReason')
+    expect(management).toContain('notificationCategoryLabel((row as NotificationTask).category)')
+    expect(management).toContain('notificationCategoryLabel(detail.category)')
+    expect(management).toContain('notificationAppLabel(row.appCode)')
+    expect(management).toContain('notificationRecipientStatusLabel(row.status)')
+  })
+
+  it('uses the prototype composer width and exposes the real send command', () => {
+    const wrapper = mount(MessageComposerDialog, {
+      props: { modelValue: true, templates: [] },
+      global: { stubs: dialogStubs },
+    })
+    expect(wrapper.get('.dialog').attributes('data-width')).toContain('680px')
+    expect(wrapper.findAll('button').some((button) => button.text() === '立即发送' && !button.attributes('disabled'))).toBe(true)
+    expect(wrapper.text()).not.toContain('存为草稿')
+  })
+
+  it('keeps the scheduled-send switch actionable and clears its date when disabled', () => {
+    const composer = source('./components/MessageComposerDialog.vue')
+    expect(composer).toContain('if (value && !form.scheduledAt)')
+    expect(composer).toContain('if (!value) form.scheduledAt = \'\'')
+    expect(composer).toContain('Date.now() + 5 * 60 * 1000')
+  })
+
+  it('uses the prototype editor width and exposes the real save command', () => {
+    const wrapper = mount(TemplateEditorDialog, {
+      props: { modelValue: true },
+      global: { stubs: dialogStubs },
+    })
+    expect(wrapper.get('.dialog').attributes('data-width')).toContain('760px')
+    const save = wrapper.findAll('button').find((button) => button.text() === '保存模板')
+    expect(save?.attributes('disabled')).toBeUndefined()
+  })
+})
diff --git a/src/modules/notifications/notificationsDensity.behavior.test.ts b/src/modules/notifications/notificationsDensity.behavior.test.ts
new file mode 100644
index 00000000..b59b6d9a
--- /dev/null
+++ b/src/modules/notifications/notificationsDensity.behavior.test.ts
@@ -0,0 +1,135 @@
+import ElementPlus, { ElDrawer, ElSelect } from 'element-plus'
+import { enableAutoUnmount, flushPromises, mount, type VueWrapper } from '@vue/test-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import PlatformNotificationsView from './pages/PlatformNotificationsView.vue'
+import MessageManagementView from './pages/MessageManagementView.vue'
+import MessageTemplatesView from './pages/MessageTemplatesView.vue'
+import MessageComposerDialog from './components/MessageComposerDialog.vue'
+import TemplateEditorDialog from './components/TemplateEditorDialog.vue'
+import * as api from './api/notificationCenter'
+import type { NotificationTemplate, NotificationTask, NotificationInboxDetail, PageResult } from './types'
+
+const can = vi.hoisted(() => vi.fn(() => true))
+vi.mock('@/core/access/accessPreview', () => ({ useAccessPreviewStore: () => ({ can }) }))
+vi.mock('./api/notificationCenter', () => ({
+  listMyNotifications: vi.fn(), getMyUnreadNotificationCount: vi.fn(), getMyNotification: vi.fn(),
+  markMyNotificationRead: vi.fn(), markAllMyNotificationsRead: vi.fn(), listTasks: vi.fn(), getTask: vi.fn(),
+  listTemplates: vi.fn(), createNotification: vi.fn(), createTemplate: vi.fn(), updateTemplate: vi.fn(),
+  cancelTask: vi.fn(), retryTask: vi.fn(), changeTemplateStatus: vi.fn(),
+}))
+
+const template: NotificationTemplate = { id: 'template-1', templateCode: 'ORDER_NOTICE', templateName: '订单通知', category: 'ORDER', channel: 'IN_APP', titleTemplate: '订单更新', bodyTemplate: '订单已更新', variableWhitelist: [], status: 'DRAFT', version: 3 }
+const task: NotificationTask = { id: 'task-1', taskNo: 'NT202609140001', category: 'ORDER', title: '订单更新', status: 'CREATED', recipientCount: 1, scheduledAt: null, sentAt: null, duplicated: false }
+const inbox: NotificationInboxDetail = { id: 'inbox-1', category: 'ORDER', title: '订单更新', summary: '订单状态有更新', body: '第一行\n第二行', status: 'UNREAD', sentAt: '2026-09-14T01:00:00Z', readAt: null, sourceType: null, sourceId: null }
+const page = <T,>(records: T[]): PageResult<T> => ({ records, page: 1, size: 20, total: records.length, pages: 1 })
+const options = () => ({ attachTo: document.body, global: { plugins: [ElementPlus] } })
+async function click(wrapper: VueWrapper, label: string, selector = 'button') {
+  const button = wrapper.findAll(selector).find(item => item.text().trim() === label)
+  expect(button, label).toBeDefined()
+  await button!.trigger('click')
+  await flushPromises()
+}
+enableAutoUnmount(afterEach)
+afterEach(() => { vi.unstubAllGlobals(); document.body.innerHTML = '' })
+beforeEach(() => {
+  vi.clearAllMocks()
+  can.mockReturnValue(true)
+  vi.stubGlobal('ResizeObserver', class { observe() {} unobserve() {} disconnect() {} })
+  vi.mocked(api.listMyNotifications).mockResolvedValue(page([inbox]))
+  vi.mocked(api.getMyUnreadNotificationCount).mockResolvedValue(1)
+  vi.mocked(api.getMyNotification).mockResolvedValue(inbox)
+  vi.mocked(api.markMyNotificationRead).mockResolvedValue({ ...inbox, status: 'READ' })
+  vi.mocked(api.listTasks).mockResolvedValue(page([task]))
+  vi.mocked(api.getTask).mockResolvedValue({ ...task, attemptCount: 1, lastError: '测试投递失败原因', recipients: [{ id: 'recipient-1', displayName: '测试员工', appCode: 'ADMIN', status: 'FAILED', failureReason: '测试收件失败', deliveredAt: null }] })
+  vi.mocked(api.listTemplates).mockResolvedValue(page([template]))
+})
+
+describe('notification density in native lists and overlays', () => {
+  it('keeps inbox actions visible and opens the styled drawer with read marking', async () => {
+    const wrapper = mount(PlatformNotificationsView, options())
+    await flushPromises()
+    const actions = wrapper.get('.el-table__body-wrapper .density-actions')
+    expect(actions.findAll('button').map(item => item.text())).toEqual(['查看', '标为已读'])
+    expect(actions.find('svg').exists()).toBe(false)
+    await click(wrapper, '查看', '.el-table__body-wrapper button')
+    const drawer = document.querySelector('.el-drawer.admin-density-drawer')!
+    expect(drawer.textContent).toContain('第一行\n第二行')
+    expect(wrapper.getComponent(ElDrawer).props('size')).toBe('min(680px, 94vw)')
+    expect(api.markMyNotificationRead).toHaveBeenCalledWith(inbox.id)
+  })
+
+  it('retains read-only inbox viewing without read permission', async () => {
+    can.mockReturnValue(false)
+    const wrapper = mount(PlatformNotificationsView, options())
+    await flushPromises()
+    expect(wrapper.get('.el-table__body-wrapper .density-actions').findAll('button').map(item => item.text())).toEqual(['查看'])
+    await click(wrapper, '查看', '.el-table__body-wrapper button')
+    expect(document.querySelector('.el-drawer')?.textContent).toContain('第一行')
+    expect(api.markMyNotificationRead).not.toHaveBeenCalled()
+  })
+
+  it.each([
+    ['CREATED', ['查看', '取消']], ['SENT', ['查看']], ['DEAD', ['查看', '重试']],
+  ] as const)('keeps task actions for %s and shows delivery evidence in the drawer', async (status, labels) => {
+    vi.mocked(api.listTasks).mockResolvedValue(page([{ ...task, status }]))
+    const wrapper = mount(MessageManagementView, options())
+    await flushPromises()
+    const actions = wrapper.get('.el-table__body-wrapper .density-actions')
+    expect(actions.findAll('button').map(item => item.text())).toEqual(labels)
+    expect(actions.find('svg').exists()).toBe(false)
+    await click(wrapper, '查看', '.el-table__body-wrapper button')
+    const drawer = document.querySelector('.el-drawer.admin-density-drawer')!
+    expect(wrapper.getComponent(ElDrawer).props('size')).toBe('min(820px, 94vw)')
+    expect(drawer.querySelectorAll('.density-fields > div')).toHaveLength(6)
+    expect(drawer.textContent).toContain(task.taskNo)
+    expect(drawer.textContent).toContain('测试员工')
+    expect(drawer.textContent).toContain('测试投递失败原因')
+  })
+
+  it.each([
+    ['DRAFT', ['编辑', '激活']], ['ACTIVE', ['禁用']], ['DISABLED', []],
+  ] as const)('keeps template state actions for %s', async (status, labels) => {
+    vi.mocked(api.listTemplates).mockResolvedValue(page([{ ...template, status }]))
+    const wrapper = mount(MessageTemplatesView, options())
+    await flushPromises()
+    const actions = wrapper.get('.el-table__body-wrapper .density-actions')
+    expect(actions.findAll('button').map(item => item.text())).toEqual(labels)
+    expect(actions.find('svg').exists()).toBe(false)
+    if (status === 'DRAFT') {
+      await click(wrapper, '编辑', '.el-table__body-wrapper button')
+      expect(document.querySelector('.el-dialog.admin-density-dialog .density-form')).not.toBeNull()
+    }
+  })
+
+  it('preserves template code, variable preview, version and draft editing in the native modal', async () => {
+    vi.mocked(api.updateTemplate).mockResolvedValue(template)
+    const wrapper = mount(TemplateEditorDialog, { ...options(), props: { modelValue: true, template } })
+    await flushPromises()
+    const modal = wrapper.get('.el-dialog.admin-density-dialog')
+    expect((modal.element as HTMLElement).style.getPropertyValue('--el-dialog-width')).toContain('760px')
+    expect(wrapper.get('input[placeholder="如：ORDER_SHIPPED_NOTICE"]').attributes('disabled')).toBeDefined()
+    await click(wrapper, 'order_no')
+    expect(wrapper.get('.template-preview').text()).toContain('${order_no}')
+    await click(wrapper, '保存模板')
+    expect(api.updateTemplate).toHaveBeenCalledWith(template.id, expect.objectContaining({ version: 3, variableWhitelist: ['order_no'], bodyTemplate: expect.stringContaining('${order_no}') }))
+    expect(wrapper.emitted('success')).toHaveLength(1)
+  })
+
+  it('keeps required composer input and scheduled payload in the native modal', async () => {
+    vi.mocked(api.createNotification).mockResolvedValue(task)
+    const wrapper = mount(MessageComposerDialog, { ...options(), props: { modelValue: true, templates: [{ ...template, status: 'ACTIVE' }] } })
+    await flushPromises()
+    const modal = wrapper.get('.el-dialog.admin-density-dialog')
+    expect((modal.element as HTMLElement).style.getPropertyValue('--el-dialog-width')).toContain('680px')
+    expect(modal.find('.density-form').exists()).toBe(true)
+    await click(wrapper, '立即发送')
+    expect(api.createNotification).not.toHaveBeenCalled()
+    wrapper.findAllComponents(ElSelect)[0]!.vm.$emit('update:modelValue', template.templateCode)
+    await wrapper.get('input[placeholder="请输入服务端角色编码"]').setValue('TEST_OPERATOR')
+    await wrapper.get('[role="switch"]').trigger('click')
+    await flushPromises()
+    await click(wrapper, '确认定时发送')
+    expect(api.createNotification).toHaveBeenCalledWith(expect.objectContaining({ tenantId: '0', templateCode: template.templateCode, recipientType: 'PLATFORM_ROLE', roleCode: 'TEST_OPERATOR', variables: {}, scheduledAt: expect.any(String), idempotencyKey: expect.any(String) }))
+    expect(wrapper.emitted('success')).toHaveLength(1)
+  })
+})
diff --git a/src/modules/notifications/pages/MessageManagementView.vue b/src/modules/notifications/pages/MessageManagementView.vue
new file mode 100644
index 00000000..6be0596c
--- /dev/null
+++ b/src/modules/notifications/pages/MessageManagementView.vue
@@ -0,0 +1,28 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { onMounted, ref, watch } from 'vue'
+import { Plus } from '@lucide/vue'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import AdminPage from '@/shared/components/AdminPage.vue'; import AppDrawer from '@/shared/components/AppDrawer.vue'; import DataTable,{type DataTableColumn} from '@/shared/components/DataTable.vue'; import ListPageLayout from '@/shared/components/ListPageLayout.vue'; import QueryToolbar,{type QueryField,type QueryModel} from '@/shared/components/QueryToolbar.vue'; import LoadErrorState from '@/shared/components/LoadErrorState.vue'; import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import MessageComposerDialog from '../components/MessageComposerDialog.vue'; import { cancelTask, getTask, listTasks, listTemplates, retryTask } from '../api/notificationCenter'; import type { NotificationTask, NotificationTaskDetail, NotificationTaskStatus, NotificationTemplate } from '../types'; import { getApiErrorDetails, getApiErrorMessage, type ApiErrorDetails } from '@/shared/api/http'; import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { notificationAppLabel, notificationCategoryLabel, notificationRecipientStatusLabel } from '../presentation'
+const access=useAccessPreviewStore(),page=ref(1),pageSize=ref(20),loading=ref(false),actionId=ref(''),error=ref<ApiErrorDetails|null>(null),composerOpen=ref(false),detailOpen=ref(false),detailLoading=ref(false),detailError=ref<ApiErrorDetails|null>(null),detail=ref<NotificationTaskDetail|null>(null),templates=ref<NotificationTemplate[]>([]),result=ref({records:[] as NotificationTask[],total:0,pages:0}),filters=ref<QueryModel>({category:'',status:'',keyword:''})
+const queryFields:QueryField[]=[{key:'category',type:'input',label:'业务分类',placeholder:'业务分类'},{key:'status',type:'select',label:'任务状态',placeholder:'全部状态',options:['CREATED','SCHEDULED','DISPATCHING','RETRYING','SENT','DEAD','CANCELLED'].map(value=>({label:statusLabel(value as NotificationTaskStatus),value}))},{key:'keyword',type:'input',label:'任务号或标题',placeholder:'任务号/消息标题'}]
+const columns:DataTableColumn[]=[{key:'actions',label:'操作',width:240,fixed:'left',slotName:'actions'},{key:'taskNo',prop:'taskNo',label:'任务号',minWidth:190},{key:'title',prop:'title',label:'标题',minWidth:220},{key:'category',label:'业务分类',width:130,slotName:'category'},{key:'recipientCount',prop:'recipientCount',label:'接收人数',width:100},{key:'scheduledAt',label:'定时发送',width:170,slotName:'scheduledAt'},{key:'sentAt',label:'发送时间',width:170,slotName:'sentAt'},{key:'status',label:'状态',width:110,slotName:'status'}]
+function statusLabel(v:NotificationTaskStatus){return {CREATED:'已创建',SCHEDULED:'待定时发送',DISPATCHING:'发送中',RETRYING:'重试中',SENT:'已发送',DEAD:'发送失败',CANCELLED:'已取消'}[v]}
+function formatDate(v:string|null){return v?new Date(v).toLocaleString('zh-CN',{hour12:false}):'—'}
+async function load(){loading.value=true;error.value=null;try{const keyword=String(filters.value.keyword||'').trim();const data=await listTasks({page:page.value,size:pageSize.value,category:String(filters.value.category||'').trim()||undefined,status:(filters.value.status||undefined) as NotificationTaskStatus|undefined,...(keyword.startsWith('NT')?{taskNo:keyword}:{title:keyword||undefined})});result.value={records:data.records,total:data.total,pages:data.pages}}catch(e){error.value=getApiErrorDetails(e,'消息任务加载失败')}finally{loading.value=false}}
+async function loadTemplates(){if(!access.can('platform:notification:create'))return;try{const data=await listTemplates({page:1,size:200,status:'ACTIVE'});templates.value=data.records}catch(e){ElMessage.error(getApiErrorMessage(e,'可用模板加载失败'))}}
+async function openDetail(row:NotificationTask){detailOpen.value=true;detailLoading.value=true;detailError.value=null;detail.value=null;try{detail.value=await getTask(row.id)}catch(e){detailError.value=getApiErrorDetails(e,'消息任务详情加载失败')}finally{detailLoading.value=false}}
+function search(){page.value===1?void load():page.value=1}
+async function action(row:NotificationTask,type:'cancel'|'retry'){try{await ElMessageBox.confirm(type==='cancel'?'确定取消该消息任务吗？':'确定重试该消息任务吗？',type==='cancel'?'取消任务':'重试任务',{type:'warning',customClass:'admin-density-confirm'});actionId.value=row.id;if(type==='cancel')await cancelTask(row.id);else await retryTask(row.id);ElMessage.success(type==='cancel'?'任务已取消':'任务已提交重试');await load()}catch(e){if(e!=='cancel'&&e!=='close')ElMessage.error(getApiErrorMessage(e,type==='cancel'?'取消失败':'重试失败'))}finally{actionId.value=''}}
+watch([page,pageSize],load);onMounted(()=>{void load();void loadTemplates()})
+</script>
+<template><AdminPage class="admin-density"><ListPageLayout aria-label="消息管理列表"><template #toolbar><QueryToolbar v-model="filters" class="surface-panel" ariaLabel="消息任务筛选" :fields="queryFields" preference-key="notifications-messages-query" @search="search" /></template><template v-if="error" #state><LoadErrorState title="消息任务加载失败" :message="error.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="error" /></template></LoadErrorState></template><section v-if="!error" class="surface-panel table-panel"><DataTable v-model:page="page" v-model:page-size="pageSize" :data="result.records" :columns="columns" preference-key="notifications-messages-table" :loading="loading" :total="result.total" row-key="id" empty-text="暂无消息任务"><template #toolbar-actions><el-button v-if="access.can('platform:notification:create')" type="primary" :disabled="!templates.length" @click="composerOpen=true"><Plus :size="16"/>新建消息</el-button></template><template #pagination-left><span>共 {{ result.total }} 个任务</span></template><template #actions="{row}"><div class="density-actions"><el-button class="density-action" data-tone="neutral" @click="openDetail(row as NotificationTask)">查看</el-button><el-button v-if="access.can('platform:notification:task:cancel')&&['CREATED','SCHEDULED'].includes((row as NotificationTask).status)" class="density-action" data-tone="danger" :loading="actionId===(row as NotificationTask).id" @click="action(row as NotificationTask,'cancel')">取消</el-button><el-button v-if="access.can('platform:notification:task:retry')&&['RETRYING','DEAD'].includes((row as NotificationTask).status)" class="density-action" data-tone="neutral" :loading="actionId===(row as NotificationTask).id" @click="action(row as NotificationTask,'retry')">重试</el-button></div></template><template #category="{row}">{{notificationCategoryLabel((row as NotificationTask).category)}}</template><template #scheduledAt="{row}">{{formatDate((row as NotificationTask).scheduledAt)}}</template><template #sentAt="{row}">{{formatDate((row as NotificationTask).sentAt)}}</template><template #status="{row}"><el-tag>{{statusLabel((row as NotificationTask).status)}}</el-tag></template></DataTable></section></ListPageLayout><MessageComposerDialog v-model="composerOpen" :templates="templates" @success="load"/><AppDrawer class="admin-density admin-density-drawer" v-model="detailOpen" title="消息任务详情" size="min(820px, 94vw)" :loading="detailLoading" :show-footer="false" destroy-on-close><LoadErrorState v-if="detailError" title="消息任务详情加载失败" :message="detailError.message" :loading="detailLoading"><template #details><ApiErrorMeta :details="detailError" /></template></LoadErrorState><template v-else-if="detail"><dl class="detail-grid density-fields"><div><dt>任务号</dt><dd>{{detail.taskNo}}</dd></div><div><dt>状态</dt><dd>{{statusLabel(detail.status)}}</dd></div><div><dt>业务分类</dt><dd>{{notificationCategoryLabel(detail.category)}}</dd></div><div><dt>接收人数</dt><dd>{{detail.recipientCount}}</dd></div><div><dt>尝试次数</dt><dd>{{detail.attemptCount}}</dd></div><div><dt>发送时间</dt><dd>{{formatDate(detail.sentAt)}}</dd></div></dl><section v-if="detail.lastError" class="failure-panel" role="alert"><strong>任务失败原因</strong><p>{{detail.lastError}}</p></section><h3 class="recipient-heading">收件人投递明细</h3><el-table :data="detail.recipients" row-key="id" empty-text="暂无收件人明细" size="small"><el-table-column prop="displayName" label="收件人" min-width="150"/><el-table-column label="应用端" width="110"><template #default="{row}">{{notificationAppLabel(row.appCode)}}</template></el-table-column><el-table-column label="投递状态" width="120"><template #default="{row}">{{notificationRecipientStatusLabel(row.status)}}</template></el-table-column><el-table-column label="送达时间" width="180"><template #default="{row}">{{formatDate(row.deliveredAt)}}</template></el-table-column><el-table-column prop="failureReason" label="失败原因" min-width="220"><template #default="{row}">{{row.failureReason||'—'}}</template></el-table-column></el-table></template></AppDrawer></AdminPage></template>
+<style scoped>
+.detail-grid.density-fields { grid-template-columns: repeat(2, minmax(0, 1fr)); margin-bottom: var(--admin-space-6); }
+.failure-panel { margin-bottom: var(--admin-space-6); padding: var(--admin-space-5); border: 1px solid #f2b8b5; border-radius: var(--admin-radius); background: #fff7f6; color: #9f2d27; }
+.failure-panel p { margin: var(--admin-space-2) 0 0; white-space: pre-wrap; overflow-wrap: anywhere; }
+.recipient-heading { margin: 0 0 var(--admin-space-5); font-size: var(--admin-font-section); }
+@media(max-width:720px) { .detail-grid.density-fields { grid-template-columns: 1fr; } }
+</style>
diff --git a/src/modules/notifications/pages/MessageTemplatesView.vue b/src/modules/notifications/pages/MessageTemplatesView.vue
new file mode 100644
index 00000000..16f12e11
--- /dev/null
+++ b/src/modules/notifications/pages/MessageTemplatesView.vue
@@ -0,0 +1,14 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { onMounted, ref, watch } from 'vue'; import { Plus } from '@lucide/vue'; import { ElMessage, ElMessageBox } from 'element-plus'
+import AdminPage from '@/shared/components/AdminPage.vue'; import DataTable,{type DataTableColumn} from '@/shared/components/DataTable.vue'; import ListPageLayout from '@/shared/components/ListPageLayout.vue'; import QueryToolbar,{type QueryField,type QueryModel} from '@/shared/components/QueryToolbar.vue'; import LoadErrorState from '@/shared/components/LoadErrorState.vue'; import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'; import TemplateEditorDialog from '../components/TemplateEditorDialog.vue'; import { changeTemplateStatus, listTemplates } from '../api/notificationCenter'; import type { NotificationTemplate, TemplateStatus } from '../types'; import { getApiErrorDetails,getApiErrorMessage,type ApiErrorDetails } from '@/shared/api/http'; import { useAccessPreviewStore } from '@/core/access/accessPreview'
+const access=useAccessPreviewStore(),page=ref(1),pageSize=ref(20),loading=ref(false),actionId=ref(''),error=ref<ApiErrorDetails|null>(null),editorOpen=ref(false),editing=ref<NotificationTemplate|null>(null),result=ref({records:[] as NotificationTemplate[],total:0,pages:0}),filters=ref<QueryModel>({code:'',category:'',title:'',status:''})
+const queryFields:QueryField[]=[{key:'code',type:'input',label:'模板CODE',placeholder:'模板CODE'},{key:'category',type:'input',label:'业务分类',placeholder:'业务分类'},{key:'title',type:'input',label:'名称或标题',placeholder:'模板名称/标题'},{key:'status',type:'select',label:'状态',placeholder:'全部状态',options:[{label:'草稿',value:'DRAFT'},{label:'已激活',value:'ACTIVE'},{label:'已禁用',value:'DISABLED'}]}]
+const columns:DataTableColumn[]=[{key:'actions',label:'操作',width:190,fixed:'left',slotName:'actions'},{key:'templateCode',prop:'templateCode',label:'模板CODE',minWidth:190},{key:'templateName',prop:'templateName',label:'模板名称',minWidth:170},{key:'category',prop:'category',label:'业务分类',width:130},{key:'titleTemplate',prop:'titleTemplate',label:'消息标题模板',minWidth:220},{key:'bodyTemplate',prop:'bodyTemplate',label:'正文模板',minWidth:320,showOverflowTooltip:true},{key:'status',label:'状态',width:100,slotName:'status'},{key:'version',prop:'version',label:'版本',width:80}]
+function statusLabel(v:TemplateStatus){return {DRAFT:'草稿',ACTIVE:'已激活',DISABLED:'已禁用'}[v]}
+async function load(){loading.value=true;error.value=null;try{const d=await listTemplates({page:page.value,size:pageSize.value,templateCode:String(filters.value.code||'').trim()||undefined,category:String(filters.value.category||'').trim()||undefined,title:String(filters.value.title||'').trim()||undefined,status:(filters.value.status||undefined) as TemplateStatus|undefined});result.value={records:d.records,total:d.total,pages:d.pages}}catch(e){error.value=getApiErrorDetails(e,'模板加载失败')}finally{loading.value=false}}
+function search(){page.value===1?void load():page.value=1}function create(){editing.value=null;editorOpen.value=true}function edit(row:NotificationTemplate){editing.value=row;editorOpen.value=true}
+async function changeStatus(row:NotificationTemplate){const target=row.status==='DRAFT'?'ACTIVE':'DISABLED';try{await ElMessageBox.confirm(target==='ACTIVE'?'激活后模板不可再编辑，确定继续吗？':'禁用后首期不可重新启用，确定继续吗？',target==='ACTIVE'?'激活模板':'禁用模板',{type:'warning',customClass:'admin-density-confirm'});actionId.value=row.id;await changeTemplateStatus(row.id,target,row.version);ElMessage.success(target==='ACTIVE'?'模板已激活':'模板已禁用');await load()}catch(e){if(e!=='cancel'&&e!=='close')ElMessage.error(getApiErrorMessage(e,'模板状态变更失败'))}finally{actionId.value=''}}
+watch([page,pageSize],load);onMounted(load)
+</script>
+<template><AdminPage class="admin-density"><ListPageLayout aria-label="消息模板列表"><template #toolbar><QueryToolbar v-model="filters" class="surface-panel" ariaLabel="消息模板筛选" :fields="queryFields" preference-key="notifications-templates-query" @search="search"/></template><template v-if="error" #state><LoadErrorState title="模板加载失败" :message="error.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="error"/></template></LoadErrorState></template><section v-if="!error" class="surface-panel table-panel"><DataTable v-model:page="page" v-model:page-size="pageSize" :data="result.records" :columns="columns" preference-key="notifications-templates-table" :loading="loading" :total="result.total" row-key="id" empty-text="暂无消息模板"><template #toolbar-actions><el-button v-if="access.can('platform:notification:template:create')" type="primary" @click="create"><Plus :size="16"/>新增模板</el-button></template><template #pagination-left><span>共 {{result.total}} 个模板</span></template><template #actions="{row}"><div class="density-actions"><el-button v-if="access.can('platform:notification:template:edit')&&(row as NotificationTemplate).status==='DRAFT'" class="density-action" data-tone="neutral" @click="edit(row as NotificationTemplate)">编辑</el-button><el-button v-if="access.can('platform:notification:template:status')&&(row as NotificationTemplate).status!=='DISABLED'" class="density-action" :data-tone="(row as NotificationTemplate).status==='ACTIVE'?'danger':'success'" :loading="actionId===(row as NotificationTemplate).id" @click="changeStatus(row as NotificationTemplate)">{{(row as NotificationTemplate).status==='DRAFT'?'激活':'禁用'}}</el-button></div></template><template #status="{row}"><el-tag>{{statusLabel((row as NotificationTemplate).status)}}</el-tag></template></DataTable></section></ListPageLayout><TemplateEditorDialog v-model="editorOpen" :template="editing" @success="load"/></AdminPage></template>
diff --git a/src/modules/notifications/pages/PlatformNotificationsView.vue b/src/modules/notifications/pages/PlatformNotificationsView.vue
new file mode 100644
index 00000000..161776b7
--- /dev/null
+++ b/src/modules/notifications/pages/PlatformNotificationsView.vue
@@ -0,0 +1,109 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, ref, watch } from 'vue'
+import { CheckCheck } from '@lucide/vue'
+import { ElMessage } from 'element-plus'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import AppDrawer from '@/shared/components/AppDrawer.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import { getApiErrorDetails, getApiErrorMessage, type ApiErrorDetails } from '@/shared/api/http'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { getMyNotification, getMyUnreadNotificationCount, listMyNotifications, markAllMyNotificationsRead, markMyNotificationRead } from '../api/notificationCenter'
+import { notificationCategoryLabel } from '../presentation'
+import type { NotificationInboxDetail, NotificationInboxItem, NotificationInboxStatus, PageResult } from '../types'
+
+const page = ref(1)
+const pageSize = ref(20)
+const loading = ref(false)
+const error = ref<ApiErrorDetails | null>(null)
+const result = ref<PageResult<NotificationInboxItem>>({ records: [], page: 1, size: 20, total: 0, pages: 0 })
+const filters = ref<QueryModel>({ status: '', category: '' })
+const unreadCount = ref<number | null>(null)
+const detailOpen = ref(false)
+const detailLoading = ref(false)
+const detailError = ref<ApiErrorDetails | null>(null)
+const detail = ref<NotificationInboxDetail | null>(null)
+const access = useAccessPreviewStore()
+const canRead = computed(() => access.can('platform:notification:read'))
+const canReadAll = computed(() => access.can('platform:notification:read-all'))
+const queryFields: QueryField[] = [
+  { key: 'status', type: 'select', label: '消息状态', placeholder: '全部状态', options: [{ label: '未读', value: 'UNREAD' }, { label: '已读', value: 'READ' }] },
+  { key: 'category', type: 'input', label: '消息分类', placeholder: '请输入消息分类' },
+]
+const columns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 190, fixed: 'left', slotName: 'actions' },
+  { key: 'title', prop: 'title', label: '消息标题', minWidth: 220 },
+  { key: 'summary', prop: 'summary', label: '内容摘要', minWidth: 300, showOverflowTooltip: true },
+  { key: 'category', label: '分类', width: 130, slotName: 'category' },
+  { key: 'sentAt', label: '发送时间', width: 180, slotName: 'sentAt' },
+  { key: 'status', label: '状态', width: 90, slotName: 'status' },
+]
+
+function statusLabel(status: NotificationInboxStatus) { return status === 'UNREAD' ? '未读' : '已读' }
+function formatDate(value: string | null) { return value ? new Date(value).toLocaleString('zh-CN', { hour12: false }) : '—' }
+function search() { page.value === 1 ? void load() : page.value = 1 }
+async function load() {
+  loading.value = true
+  error.value = null
+  try {
+    result.value = await listMyNotifications({ page: page.value, size: pageSize.value, status: filters.value.status as NotificationInboxStatus || undefined, category: String(filters.value.category || '').trim() || undefined })
+    unreadCount.value = await getMyUnreadNotificationCount()
+  } catch (reason) {
+    error.value = getApiErrorDetails(reason, '我的消息加载失败')
+    result.value = { records: [], page: page.value, size: pageSize.value, total: 0, pages: 0 }
+  } finally { loading.value = false }
+}
+async function openDetail(row: NotificationInboxItem) {
+  detailOpen.value = true; detailLoading.value = true; detailError.value = null; detail.value = null
+  try {
+    detail.value = await getMyNotification(row.id)
+    if (detail.value.status === 'UNREAD' && canRead.value) {
+      detail.value = await markMyNotificationRead(row.id)
+      await load()
+    }
+  } catch (reason) { detailError.value = getApiErrorDetails(reason, '消息详情加载失败') } finally { detailLoading.value = false }
+}
+async function markRead(row: NotificationInboxItem) {
+  if (!canRead.value || row.status !== 'UNREAD') return
+  try { await markMyNotificationRead(row.id); ElMessage.success('消息已标记为已读'); await load() } catch (reason) { ElMessage.error(getApiErrorMessage(reason, '标记已读失败')) }
+}
+async function markAllRead() {
+  try { await markAllMyNotificationsRead(); ElMessage.success('全部消息已标记为已读'); await load() } catch (reason) { ElMessage.error(getApiErrorMessage(reason, '标记已读失败')) }
+}
+watch([page, pageSize], () => void load())
+onMounted(() => void load())
+</script>
+
+<template>
+  <AdminPage class="admin-density">
+    <ListPageLayout aria-label="我的消息列表">
+      <template #toolbar><QueryToolbar v-model="filters" class="surface-panel" ariaLabel="我的消息筛选" :fields="queryFields" preference-key="notifications-inbox-query" @search="search" /></template>
+      <template v-if="error" #state><LoadErrorState title="我的消息加载失败" :message="error.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="error" /></template></LoadErrorState></template>
+      <section v-if="!error" class="surface-panel table-panel">
+        <DataTable v-model:page="page" v-model:page-size="pageSize" :data="result.records" :columns="columns" :loading="loading" :total="result.total" row-key="id" empty-text="暂无消息">
+          <template #toolbar-actions><el-button v-if="canReadAll && unreadCount" type="primary" plain :disabled="loading" @click="markAllRead"><CheckCheck :size="16" />全部标为已读</el-button></template>
+          <template #pagination-left><span>共 {{ result.total }} 条<span v-if="unreadCount">，未读 {{ unreadCount }} 条</span></span></template>
+          <template #actions="{ row }"><div class="density-actions"><el-button class="density-action" data-tone="neutral" @click="openDetail(row as NotificationInboxItem)">查看</el-button><el-button v-if="canRead && (row as NotificationInboxItem).status === 'UNREAD'" class="density-action" data-tone="neutral" @click="markRead(row as NotificationInboxItem)">标为已读</el-button></div></template>
+          <template #category="{ row }">{{ notificationCategoryLabel((row as NotificationInboxItem).category) }}</template>
+          <template #sentAt="{ row }">{{ formatDate((row as NotificationInboxItem).sentAt) }}</template>
+          <template #status="{ row }"><el-tag :type="(row as NotificationInboxItem).status === 'UNREAD' ? 'danger' : 'info'">{{ statusLabel((row as NotificationInboxItem).status) }}</el-tag></template>
+        </DataTable>
+      </section>
+    </ListPageLayout>
+    <AppDrawer class="admin-density admin-density-drawer" v-model="detailOpen" title="消息详情" size="min(680px, 94vw)" :loading="detailLoading" :show-footer="false" destroy-on-close>
+      <LoadErrorState v-if="detailError" title="消息详情加载失败" :message="detailError.message" :loading="detailLoading"><template #details><ApiErrorMeta :details="detailError" /></template></LoadErrorState>
+      <article v-else-if="detail" class="notification-detail"><header><h2>{{ detail.title }}</h2><el-tag :type="detail.status === 'UNREAD' ? 'danger' : 'info'">{{ statusLabel(detail.status) }}</el-tag></header><p class="meta">{{ notificationCategoryLabel(detail.category) }} · {{ formatDate(detail.sentAt) }}</p><div class="body">{{ detail.body || '暂无消息内容' }}</div></article>
+    </AppDrawer>
+  </AdminPage>
+</template>
+
+<style scoped>
+.notification-detail header { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-5); }
+.notification-detail h2 { min-width: 0; margin: 0; overflow-wrap: anywhere; color: var(--cc-text); font-size: var(--admin-font-title); line-height: 1.4; }
+.notification-detail .meta { margin: var(--admin-space-5) 0; color: var(--cc-muted); font-size: var(--admin-font-caption); }
+.notification-detail .body { padding-top: var(--admin-space-6); border-top: 1px solid var(--cc-border); color: var(--cc-text); white-space: pre-wrap; overflow-wrap: anywhere; line-height: 1.8; }
+</style>
diff --git a/src/modules/notifications/presentation.test.ts b/src/modules/notifications/presentation.test.ts
new file mode 100644
index 00000000..1533ca00
--- /dev/null
+++ b/src/modules/notifications/presentation.test.ts
@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest'
+import { notificationAppLabel, notificationCategoryLabel, notificationRecipientStatusLabel } from './presentation'
+
+describe('notification presentation', () => {
+  it('maps known notification values to user-facing Chinese labels', () => {
+    expect(notificationCategoryLabel('ORDER')).toBe('订单消息')
+    expect(notificationAppLabel('MERCHANT')).toBe('企业客户端')
+    expect(notificationRecipientStatusLabel('DELIVERED')).toBe('已送达')
+  })
+
+  it('falls back to the original code for values added by the backend later', () => {
+    expect(notificationCategoryLabel('FUTURE_CATEGORY')).toBe('FUTURE_CATEGORY')
+    expect(notificationAppLabel('MOBILE')).toBe('MOBILE')
+    expect(notificationRecipientStatusLabel('QUEUED')).toBe('QUEUED')
+  })
+})
diff --git a/src/modules/notifications/presentation.ts b/src/modules/notifications/presentation.ts
new file mode 100644
index 00000000..1a2d38ef
--- /dev/null
+++ b/src/modules/notifications/presentation.ts
@@ -0,0 +1,39 @@
+const categoryLabels: Record<string, string> = {
+  SYSTEM: '系统通知',
+  SYSTEM_NOTICE: '系统通知',
+  BUSINESS: '业务提醒',
+  BUSINESS_REMINDER: '业务提醒',
+  ALERT: '异常告警',
+  EXCEPTION_ALERT: '异常告警',
+  WARNING: '异常告警',
+  TASK: '任务待办',
+  TASK_TODO: '任务待办',
+  ORDER: '订单消息',
+  INBOUND: '入库消息',
+  FINANCE: '财务消息',
+  CUSTOMS: '报关消息',
+  ACCEPTANCE: '验收消息',
+  CLIENT_ACCEPTANCE: '验收消息',
+}
+
+const appLabels: Record<string, string> = {
+  PLATFORM: '管理后台',
+  ADMIN: '管理后台',
+  MERCHANT: '企业客户端',
+}
+
+const recipientStatusLabels: Record<string, string> = {
+  RESOLVED: '待投递',
+  DELIVERED: '已送达',
+  FAILED: '投递失败',
+}
+
+function mappedLabel(value: string | null | undefined, labels: Record<string, string>) {
+  const code = value?.trim()
+  if (!code) return '—'
+  return labels[code.toUpperCase()] ?? code
+}
+
+export const notificationCategoryLabel = (value?: string | null) => mappedLabel(value, categoryLabels)
+export const notificationAppLabel = (value?: string | null) => mappedLabel(value, appLabels)
+export const notificationRecipientStatusLabel = (value?: string | null) => mappedLabel(value, recipientStatusLabels)
diff --git a/src/modules/notifications/routes.ts b/src/modules/notifications/routes.ts
new file mode 100644
index 00000000..f2f4dea6
--- /dev/null
+++ b/src/modules/notifications/routes.ts
@@ -0,0 +1,22 @@
+import type { RouteRecordRaw } from 'vue-router'
+
+export const notificationRoutes = [
+  {
+    path: 'notifications',
+    name: 'notification-inbox',
+    component: () => import('@/modules/notifications/pages/PlatformNotificationsView.vue'),
+    meta: { title: '我的消息', description: '查看当前平台账号的站内消息', permission: 'platform:notification:view' },
+  },
+  {
+    path: 'notifications/messages',
+    name: 'notification-messages',
+    component: () => import('@/modules/notifications/pages/MessageManagementView.vue'),
+    meta: { title: '消息管理', description: '创建并管理平台站内消息', permission: 'platform:notification:task:list' },
+  },
+  {
+    path: 'notifications/templates',
+    name: 'notification-templates',
+    component: () => import('@/modules/notifications/pages/MessageTemplatesView.vue'),
+    meta: { title: '模板管理', description: '维护平台站内消息模板', permission: 'platform:notification:template:list' },
+  },
+] satisfies RouteRecordRaw[]
diff --git a/src/modules/notifications/types.ts b/src/modules/notifications/types.ts
new file mode 100644
index 00000000..99dfc57a
--- /dev/null
+++ b/src/modules/notifications/types.ts
@@ -0,0 +1,17 @@
+export type TemplateStatus = 'DRAFT' | 'ACTIVE' | 'DISABLED'
+export type NotificationTaskStatus = 'CREATED' | 'SCHEDULED' | 'DISPATCHING' | 'RETRYING' | 'SENT' | 'DEAD' | 'CANCELLED'
+export type RecipientType = 'USER' | 'MEMBERSHIP' | 'TENANT_ROLE' | 'TENANT_ALL' | 'PLATFORM_ROLE'
+
+export interface PageResult<T> { records: T[]; page: number; size: number; total: number; pages: number }
+export interface NotificationTemplate { id: string; templateCode: string; templateName: string; category: string; channel: 'IN_APP'; titleTemplate: string; bodyTemplate: string; variableWhitelist: string[]; status: TemplateStatus; version: number }
+export interface NotificationTask { id: string; taskNo: string; category: string; title: string; status: NotificationTaskStatus; recipientCount: number; scheduledAt: string | null; sentAt: string | null; duplicated: boolean }
+export interface NotificationTaskRecipient { id: string; displayName: string; appCode: string; status: string; failureReason: string | null; deliveredAt: string | null }
+export interface NotificationTaskDetail extends Omit<NotificationTask, 'duplicated'> { attemptCount: number; lastError: string | null; recipients: NotificationTaskRecipient[] }
+
+export type NotificationInboxStatus = 'UNREAD' | 'READ'
+export interface NotificationInboxItem { id: string; category: string; title: string; summary: string; status: NotificationInboxStatus; sentAt: string; readAt: string | null }
+export interface NotificationInboxDetail extends NotificationInboxItem { body: string; sourceType: string | null; sourceId: string | null }
+
+export interface CreateNotificationRequest { tenantId: string; templateCode: string; recipientType: RecipientType; recipientIds?: string[]; roleCode?: string; variables: Record<string, string>; scheduledAt: string | null; idempotencyKey: string; sourceEventId?: string | null }
+export interface CreateTemplateRequest { templateCode: string; templateName: string; category: string; titleTemplate: string; bodyTemplate: string; variableWhitelist: string[] }
+export interface UpdateTemplateRequest extends Omit<CreateTemplateRequest, 'templateCode'> { version: number }
diff --git a/src/modules/ocean-bookings/api/platformOceanBookings.test.ts b/src/modules/ocean-bookings/api/platformOceanBookings.test.ts
new file mode 100644
index 00000000..9c3819a8
--- /dev/null
+++ b/src/modules/ocean-bookings/api/platformOceanBookings.test.ts
@@ -0,0 +1,125 @@
+import { describe, expect, it, vi } from 'vitest'
+import { createOceanBooking, deleteOceanBookingDraft, downloadOceanBookingDocument, downloadOceanBookingPrint, invalidateOceanBookingDocument, listOceanBookingAgents, listOceanBookingDocuments, listOceanBookingLinkCandidates, listOceanBookings, listWarehouseLogisticsChannels, referenceOceanBookingDocument, releaseOceanBooking, updateOceanBookingDraft, uploadOceanBookingDocument } from './platformOceanBookings'
+import { http } from '@/shared/api/http'
+
+const detailResponse = (version = 0, status = 'DRAFT') => ({
+  oceanBooking: {
+    id: 123, bookingNo: 'OB123', status, version, customerId: 456, customerName: '客户', shipperName: '发货企业', consigneeName: '收货企业', containerCount: '2',
+  },
+  parties: [],
+  containerRequirements: [{ id: 9007199254740994, oceanBookingId: 123, containerType: '40HQ', containerKind: 'FCL', quantity: 2, capacityCbm: 68, maxWeightKg: 19500 }],
+  containers: [{ containerBookingId: 9007199254740993, cabinetNo: 'CAB-1', containerNo: 'MSCU1234567', requirementId: 9007199254740994, allocationId: 9007199254740995, containerType: '40HQ', containerKind: 'FCL', capacityCbm: 68, maxWeightKg: 19500, warehouseId: 9007199254740996, warehouseName: '义乌仓', channelCode: 'SEA', channelName: '海运', customerId: 456, customerName: '客户' }],
+  documents: [{ id: 9007199254740997, oceanBookingId: 123, fileId: 9007199254740998, documentType: 'BOOKING_CONFIRMATION', fileName: '订舱确认.pdf', fileHash: null, sizeBytes: '128', contentType: 'application/pdf', valid: true, uploadedBy: 7, uploadedByName: '平台', uploadedAt: '2026-08-31T10:00:00', invalidatedBy: null, invalidatedByName: null, invalidatedAt: null }],
+  histories: [],
+})
+
+describe('ocean bookings api', () => {
+  it('normalizes pagination and long ids', async () => {
+    vi.spyOn(http, 'get').mockResolvedValueOnce({ code: '200', message: 'ok', data: { records: [{ id: 123, bookingNo: 'OB-260825-0183', customerId: 456, shipperName: '发货企业', consigneeName: '收货企业', containerCount: '1' }], page: '2', size: '20', total: '21', pages: '2' } })
+    const result = await listOceanBookings({ page: 1, size: 10 })
+    expect(result.page).toBe(2)
+    expect(result.total).toBe(21)
+    expect(result.records[0]?.id).toBe('123')
+    expect(result.records[0]?.customerId).toBe('456')
+    expect(result.records[0]).toMatchObject({ bookingNo: 'OB-260825-0183', shipperName: '发货企业', consigneeName: '收货企业', containerCount: 1 })
+  })
+
+  it('uses the frozen single-query link candidate contract and normalizes long ids', async () => {
+    vi.spyOn(http, 'get').mockResolvedValueOnce({ code: '200', data: { records: [{ oceanBookingId: 9007199254740993, bookingNo: 'OB-1', requirementId: 9007199254740994, containerType: '40HQ', capacityCbm: '68', maxWeightKg: '19500', requiredQuantity: '2', allocatedQuantity: '1', remainingQuantity: '1', customerName: '客户', warehouseName: '义乌仓', channelName: '美森正班' }], page: '1', size: '200', total: '1', pages: '1' } })
+    const query = { warehouseId: '8', channelGroupCode: 'MATSON_CLX', containerType: '40HQ', page: 1, size: 200 }
+
+    const result = await listOceanBookingLinkCandidates(query)
+
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/ocean-bookings/link-candidates', { params: query })
+    expect(result.records[0]).toMatchObject({ oceanBookingId: '9007199254740992', requirementId: '9007199254740994', capacityCbm: 68, maxWeightKg: 19500, requiredQuantity: 2, allocatedQuantity: 1, remainingQuantity: 1 })
+  })
+
+  it('uses version zero for create and extracts the id from the returned Detail', async () => {
+    const post = vi.spyOn(http, 'post').mockResolvedValue({ code: '200', message: 'ok', data: detailResponse() })
+    const created = await createOceanBooking({ expectedVersion: 0, data: { customerId: null, customerName: null, channelCode: null, warehouseId: null, billOfLadingNo: '', vesselName: '', voyageNo: '', estimatedSailingAt: null, estimatedArrivalAt: null, parties: [], containerRequirements: [{ containerType: '40HQ', containerKind: 'FCL', quantity: 2, capacityCbm: 68, maxWeightKg: 19500 }] } })
+    const sentPayload = post.mock.calls[0]?.[1] as { expectedVersion: number; data: Record<string, unknown> }
+    expect(sentPayload).toMatchObject({ expectedVersion: 0, data: { customerId: null, customerName: null, channelCode: null, warehouseId: null } })
+    expect(sentPayload).not.toMatchObject({ data: { customerId: '', customerName: '' } })
+    expect(sentPayload.data).toMatchObject({ containerRequirements: [{ containerType: '40HQ', quantity: 2, capacityCbm: 68, maxWeightKg: 19500 }] })
+    expect(sentPayload.data).not.toHaveProperty('containers')
+    expect(sentPayload.data).not.toHaveProperty('warehouseName')
+    expect(post.mock.calls[0]?.[2]).toMatchObject({ headers: { 'Idempotency-Key': expect.any(String) } })
+    expect(created.id).toBe('123')
+    expect(created.version).toBe(0)
+    expect(created.status).toBe('DRAFT')
+    expect(created.containerRequirements[0]).toMatchObject({ id: '9007199254740994', requirementId: '9007199254740994', quantity: 2 })
+    expect(created.containers[0]).toMatchObject({ containerBookingId: '9007199254740992', requirementId: '9007199254740994' })
+    expect(created.documents[0]).toMatchObject({ id: '9007199254740996', oceanBookingId: '123', fileId: '9007199254740998', sizeBytes: 128, uploadedBy: '7' })
+  })
+
+  it('uses draft update, delete and release contracts without legacy actions', async () => {
+    const put = vi.spyOn(http, 'put').mockResolvedValue({ code: '200', message: 'ok', data: detailResponse(4) })
+    const remove = vi.spyOn(http, 'delete').mockResolvedValue({ code: '200', message: 'ok', data: null })
+    const post = vi.spyOn(http, 'post').mockResolvedValue({ code: '200', message: 'ok', data: detailResponse(5, 'RELEASED') })
+    const data = { customerId: null, customerName: null, channelCode: null, warehouseId: null, billOfLadingNo: '', vesselName: '', voyageNo: '', estimatedSailingAt: null, estimatedArrivalAt: null, parties: [], containerRequirements: [] }
+    await updateOceanBookingDraft('123', { expectedVersion: 3, data })
+    await deleteOceanBookingDraft('123', 4)
+    await releaseOceanBooking('123', { expectedVersion: 4 })
+    expect(put).toHaveBeenCalledWith('/platform/v1/ocean-bookings/123', { expectedVersion: 3, data }, { headers: { 'Idempotency-Key': expect.any(String) } })
+    expect(remove).toHaveBeenCalledWith('/platform/v1/ocean-bookings/123', { data: { expectedVersion: 4 }, headers: { 'Idempotency-Key': expect.any(String) } })
+    expect(post).toHaveBeenCalledWith('/platform/v1/ocean-bookings/123/release', { expectedVersion: 4 }, { headers: { 'Idempotency-Key': expect.any(String) } })
+  })
+
+  it('loads warehouse-scoped logistics channels from the booking contract', async () => {
+    vi.spyOn(http, 'get').mockResolvedValue({ code: '200', message: 'ok', data: [{ channelCode: 'SEA_FCL', channelName: '海运整箱' }] })
+    await expect(listWarehouseLogisticsChannels('8')).resolves.toEqual([{ channelCode: 'SEA_FCL', channelName: '海运整箱' }])
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/ocean-bookings/channels', { params: { originWarehouseId: '8' } })
+  })
+
+  it('loads only server-filtered booking agents for the selected carrier and preserves long ids', async () => {
+    vi.spyOn(http, 'get').mockResolvedValue({ code: '200', message: 'ok', data: [{ supplierId: 9007199254740993n, name: '代理A', carrierCodes: ['MATSON', 'COSCO'] }] })
+    await expect(listOceanBookingAgents('MATSON')).resolves.toEqual([{ supplierId: '9007199254740993', name: '代理A', carrierCodes: ['MATSON', 'COSCO'] }])
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/ocean-bookings/booking-agents', { params: { carrierCode: 'MATSON' } })
+  })
+
+  it('treats an empty server candidate response as a successful empty list', async () => {
+    vi.spyOn(http, 'get').mockResolvedValue({ code: '200', message: 'ok', data: [] })
+    await expect(listOceanBookingAgents('HEDE')).resolves.toEqual([])
+  })
+
+  it('downloads both booking PDF documents from their dedicated public endpoints', async () => {
+    const get = vi.spyOn(http, 'get').mockResolvedValue(new Blob(['pdf'], { type: 'application/pdf' }))
+    await downloadOceanBookingPrint('123/456', 'SHIPPING_INSTRUCTION')
+    await downloadOceanBookingPrint('123/456', 'BILL_OF_LADING_CONFIRMATION')
+    expect(get).toHaveBeenNthCalledWith(1, '/platform/v1/ocean-bookings/123%2F456/prints/shipping-instruction', { responseType: 'blob' })
+    expect(get).toHaveBeenNthCalledWith(2, '/platform/v1/ocean-bookings/123%2F456/prints/bill-of-lading-confirmation', { responseType: 'blob' })
+  })
+
+  it('uses the booking-owned document list, upload, reference, invalidate and download contracts', async () => {
+    const rawDocument = { id: 9007199254740993n, oceanBookingId: 123, fileId: 9007199254740995n, documentType: 'BOOKING_CONFIRMATION', fileName: '订舱确认.pdf', fileHash: null, sizeBytes: '128', contentType: 'application/pdf', valid: true, uploadedBy: 7, uploadedByName: '平台', uploadedAt: '2026-08-31T10:00:00', invalidatedBy: null, invalidatedByName: null, invalidatedAt: null }
+    const get = vi.spyOn(http, 'get')
+      .mockResolvedValueOnce({ code: '200', data: [rawDocument] })
+      .mockResolvedValueOnce(new Blob(['pdf'], { type: 'application/pdf' }))
+    const post = vi.spyOn(http, 'post')
+      .mockResolvedValueOnce({ code: '200', data: { document: rawDocument, bookingVersion: '3' } })
+      .mockResolvedValueOnce({ code: '200', data: { document: rawDocument, bookingVersion: '4' } })
+    const remove = vi.spyOn(http, 'delete').mockResolvedValue({ code: '200', data: { documentId: 9007199254740993n, bookingVersion: '5' } })
+
+    await expect(listOceanBookingDocuments('123')).resolves.toMatchObject([{ id: '9007199254740993', oceanBookingId: '123', fileId: '9007199254740995', sizeBytes: 128, uploadedBy: '7' }])
+    await expect(referenceOceanBookingDocument('123', 2, '9007199254740995', 'BOOKING_CONFIRMATION')).resolves.toMatchObject({ bookingVersion: 3 })
+    const file = new File(['bill'], '提单.pdf', { type: 'application/pdf' })
+    await expect(uploadOceanBookingDocument('123', 3, 'BILL_OF_LADING', file)).resolves.toMatchObject({ bookingVersion: 4 })
+    const form = post.mock.calls[1]?.[1] as FormData
+    expect(form.get('expectedVersion')).toBe('3')
+    expect(form.get('documentType')).toBe('BILL_OF_LADING')
+    expect(form.get('file')).toBe(file)
+    await expect(invalidateOceanBookingDocument('123', '9007199254740993', 4)).resolves.toEqual({ documentId: '9007199254740993', bookingVersion: 5 })
+    await downloadOceanBookingDocument('123', '9007199254740993')
+
+    expect(get).toHaveBeenNthCalledWith(1, '/platform/v1/ocean-bookings/123/documents')
+    expect(post).toHaveBeenNthCalledWith(1, '/platform/v1/ocean-bookings/123/documents', { expectedVersion: 2, fileId: '9007199254740995', documentType: 'BOOKING_CONFIRMATION' }, { headers: { 'Idempotency-Key': expect.any(String) } })
+    expect(post).toHaveBeenNthCalledWith(2, '/platform/v1/ocean-bookings/123/documents/upload', expect.any(FormData), { headers: { 'Content-Type': 'multipart/form-data', 'Idempotency-Key': expect.any(String) } })
+    expect(remove).toHaveBeenCalledWith('/platform/v1/ocean-bookings/123/documents/9007199254740993', { data: { expectedVersion: 4 }, headers: { 'Idempotency-Key': expect.any(String) } })
+    expect(get).toHaveBeenNthCalledWith(2, '/platform/v1/ocean-bookings/123/documents/9007199254740993/download', { responseType: 'blob' })
+  })
+
+  it('preserves request and trace ids when a PDF endpoint returns a JSON business envelope as a blob', async () => {
+    vi.spyOn(http, 'get').mockResolvedValueOnce(new Blob([JSON.stringify({ code: 'B0409', message: '订舱资料不完整', requestId: 'req-pdf', traceId: 'trace-pdf' })], { type: 'application/json' }))
+    await expect(downloadOceanBookingPrint('123', 'SHIPPING_INSTRUCTION')).rejects.toMatchObject({ code: 'B0409', message: '订舱资料不完整', requestId: 'req-pdf', traceId: 'trace-pdf' })
+  })
+})
diff --git a/src/modules/ocean-bookings/api/platformOceanBookings.ts b/src/modules/ocean-bookings/api/platformOceanBookings.ts
new file mode 100644
index 00000000..3f4d6ea8
--- /dev/null
+++ b/src/modules/ocean-bookings/api/platformOceanBookings.ts
@@ -0,0 +1,169 @@
+import axios from 'axios'
+import { ApiResponseError, http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import type { OceanBookingAgentOption, OceanBookingCarrierCode, OceanBookingDetail, OceanBookingDocument, OceanBookingDocumentInvalidation, OceanBookingDocumentMutation, OceanBookingDocumentType, OceanBookingLinkCandidatePage, OceanBookingLinkCandidateQuery, OceanBookingPage, OceanBookingPrintType, OceanBookingQuery, OceanBookingResource, OceanBookingSaveRequest, OceanBookingStatus, OceanBookingReleaseRequest } from '../types'
+
+const basePath = '/platform/v1/ocean-bookings'
+const maxErrorEnvelopeBytes = 1024 * 1024
+
+export interface OceanLogisticsChannel {
+  channelCode: string
+  channelName: string
+}
+function pageNumber(value: number | string, fallback: number) { const n = Number(value); return Number.isFinite(n) ? Math.trunc(n) : fallback }
+function booking(raw: OceanBookingResource): OceanBookingResource {
+  const item = raw as OceanBookingResource & { version?: number | string | null }
+  return {
+    ...raw,
+    id: String(raw.id),
+    version: Number(item.version ?? 0),
+    customerId: raw.customerId == null ? null : String(raw.customerId),
+    shippingCompanyId: raw.shippingCompanyId == null ? null : String(raw.shippingCompanyId),
+    carrierCode: raw.carrierCode ?? null,
+    bookingAgentId: raw.bookingAgentId == null ? null : String(raw.bookingAgentId),
+    containerCount: Number(raw.containerCount ?? 0),
+    pol: raw.pol ?? raw.departurePortName ?? null,
+    pod: raw.pod ?? raw.destinationPortName ?? null,
+    carrierName: raw.carrierName ?? raw.shippingCompanyName ?? null,
+    bookingAgent: raw.bookingAgent ?? raw.bookingAgentName ?? null,
+    etd: raw.etd ?? raw.estimatedSailingAt ?? null,
+    eta: raw.eta ?? raw.estimatedArrivalAt ?? null,
+  }
+}
+function detail(raw: OceanBookingDetail): OceanBookingDetail {
+  const source = booking(raw.oceanBooking || raw)
+  const histories = (raw.histories || raw.statusHistory || []).map((event) => ({ ...event, id: String(event.id) }))
+  return {
+    ...raw,
+    ...source,
+    oceanBooking: source,
+    parties: (raw.parties || []).map((party) => ({ ...party, id: party.id == null ? undefined : String(party.id) })),
+    containerRequirements: (raw.containerRequirements || []).map((requirement) => ({
+      ...requirement,
+      id: requirement.id == null ? undefined : String(requirement.id),
+      requirementId: requirement.requirementId == null && requirement.id == null ? undefined : String(requirement.requirementId ?? requirement.id),
+      quantity: Number(requirement.quantity),
+      remainingQuantity: requirement.remainingQuantity == null ? undefined : Number(requirement.remainingQuantity),
+      capacityCbm: Number(requirement.capacityCbm),
+      maxWeightKg: Number(requirement.maxWeightKg),
+    })),
+    containers: (raw.containers || []).map((container) => ({
+      ...container,
+      containerBookingId: String(container.containerBookingId),
+      requirementId: String(container.requirementId),
+      capacityCbm: Number(container.capacityCbm),
+      maxWeightKg: Number(container.maxWeightKg),
+    })),
+    documents: (raw.documents || []).map(document),
+    histories,
+    statusHistory: histories,
+  }
+}
+export async function listOceanBookings(query: OceanBookingQuery) {
+  const response = await http.get<ApiEnvelope<OceanBookingPage>, ApiEnvelope<OceanBookingPage>>(basePath, { params: query })
+  const result = unwrapApiResponse(response)
+  return { ...result, records: (result.records || []).map(booking), page: pageNumber(result.page, query.page), size: pageNumber(result.size, query.size), total: pageNumber(result.total, 0), pages: pageNumber(result.pages, 0) } satisfies OceanBookingPage
+}
+export async function listOceanBookingLinkCandidates(query: OceanBookingLinkCandidateQuery) {
+  const response = await http.get<ApiEnvelope<OceanBookingLinkCandidatePage>, ApiEnvelope<OceanBookingLinkCandidatePage>>(`${basePath}/link-candidates`, { params: query })
+  const result = unwrapApiResponse(response)
+  return {
+    ...result,
+    records: (result.records || []).map((candidate) => ({
+      ...candidate,
+      oceanBookingId: String(candidate.oceanBookingId),
+      requirementId: String(candidate.requirementId),
+      capacityCbm: Number(candidate.capacityCbm),
+      maxWeightKg: Number(candidate.maxWeightKg),
+      requiredQuantity: Number(candidate.requiredQuantity),
+      allocatedQuantity: Number(candidate.allocatedQuantity),
+      remainingQuantity: Number(candidate.remainingQuantity),
+    })),
+    page: pageNumber(result.page, query.page),
+    size: pageNumber(result.size, query.size),
+    total: pageNumber(result.total, 0),
+    pages: pageNumber(result.pages, 0),
+  } satisfies OceanBookingLinkCandidatePage
+}
+export async function getOceanBooking(id: string) { const response = await http.get<ApiEnvelope<OceanBookingDetail>, ApiEnvelope<OceanBookingDetail>>(`${basePath}/${encodeURIComponent(id)}`); return detail(unwrapApiResponse(response)) }
+function idempotencyKey() { return `ocean-booking-${Date.now()}-${Math.random().toString(36).slice(2)}` }
+export async function createOceanBooking(payload: OceanBookingSaveRequest) { const response = await http.post<ApiEnvelope<OceanBookingDetail>, ApiEnvelope<OceanBookingDetail>>(basePath, payload, { headers: { 'Idempotency-Key': idempotencyKey() } }); return detail(unwrapApiResponse(response)) }
+export async function updateOceanBookingDraft(id: string, payload: OceanBookingSaveRequest) { const response = await http.put<ApiEnvelope<OceanBookingDetail>, ApiEnvelope<OceanBookingDetail>>(`${basePath}/${encodeURIComponent(id)}`, payload, { headers: { 'Idempotency-Key': idempotencyKey() } }); return detail(unwrapApiResponse(response)) }
+export async function deleteOceanBookingDraft(id: string, expectedVersion: number) { await http.delete(`${basePath}/${encodeURIComponent(id)}`, { data: { expectedVersion }, headers: { 'Idempotency-Key': idempotencyKey() } }) }
+export async function releaseOceanBooking(id: string, request: OceanBookingReleaseRequest) { const response = await http.post<ApiEnvelope<OceanBookingDetail>, ApiEnvelope<OceanBookingDetail>>(`${basePath}/${encodeURIComponent(id)}/release`, request, { headers: { 'Idempotency-Key': idempotencyKey() } }); return detail(unwrapApiResponse(response)) }
+const printPaths: Record<OceanBookingPrintType, string> = {
+  SHIPPING_INSTRUCTION: 'shipping-instruction',
+  BILL_OF_LADING_CONFIRMATION: 'bill-of-lading-confirmation',
+}
+function document(raw: OceanBookingDocument): OceanBookingDocument {
+  return {
+    ...raw,
+    id: String(raw.id),
+    oceanBookingId: String(raw.oceanBookingId),
+    fileId: String(raw.fileId),
+    sizeBytes: raw.sizeBytes == null ? null : Number(raw.sizeBytes),
+    uploadedBy: String(raw.uploadedBy),
+    invalidatedBy: raw.invalidatedBy == null ? null : String(raw.invalidatedBy),
+  }
+}
+export async function downloadOceanBookingPrint(id: string, type: OceanBookingPrintType) {
+  return requestBlob(`${basePath}/${encodeURIComponent(id)}/prints/${printPaths[type]}`)
+}
+async function parseBlobError(blob: Blob, status?: number) {
+  if (!blob.type.toLowerCase().includes('json')) return null
+  if (blob.size > maxErrorEnvelopeBytes) return new ApiResponseError('文件接口返回了超出限制的 JSON 响应', 'INVALID_FILE_RESPONSE', status)
+  try {
+    const payload = JSON.parse(await blob.text()) as Partial<ApiEnvelope<unknown>>
+    return new ApiResponseError(payload.code === '200' ? '文件接口未返回文件内容' : payload.message || '文件请求失败', payload.code === '200' ? 'INVALID_FILE_RESPONSE' : payload.code || (status ? `HTTP_${status}` : 'FILE_REQUEST_FAILED'), status, payload.data, payload.requestId, payload.traceId)
+  } catch {
+    return new ApiResponseError('文件接口返回了无法识别的 JSON 响应', 'INVALID_FILE_RESPONSE', status)
+  }
+}
+async function requestBlob(path: string) {
+  try {
+    const blob = await http.get<Blob, Blob>(path, { responseType: 'blob' })
+    const responseError = await parseBlobError(blob, 200)
+    if (responseError) throw responseError
+    return blob
+  } catch (error) {
+    if (axios.isAxiosError(error) && error.response?.data instanceof Blob) {
+      const responseError = await parseBlobError(error.response.data, error.response.status)
+      if (responseError) throw responseError
+    }
+    throw error
+  }
+}
+export async function listOceanBookingDocuments(id: string) {
+  const response = await http.get<ApiEnvelope<OceanBookingDocument[]>, ApiEnvelope<OceanBookingDocument[]>>(`${basePath}/${encodeURIComponent(id)}/documents`)
+  return (unwrapApiResponse(response) || []).map(document)
+}
+export async function referenceOceanBookingDocument(id: string, expectedVersion: number, fileId: string, documentType: OceanBookingDocumentType) {
+  const response = await http.post<ApiEnvelope<OceanBookingDocumentMutation>, ApiEnvelope<OceanBookingDocumentMutation>>(`${basePath}/${encodeURIComponent(id)}/documents`, { expectedVersion, fileId, documentType }, { headers: { 'Idempotency-Key': idempotencyKey() } })
+  const result = unwrapApiResponse(response)
+  return { document: document(result.document), bookingVersion: Number(result.bookingVersion) }
+}
+export async function uploadOceanBookingDocument(id: string, expectedVersion: number, documentType: OceanBookingDocumentType, file: File) {
+  const form = new FormData()
+  form.append('expectedVersion', String(expectedVersion))
+  form.append('documentType', documentType)
+  form.append('file', file)
+  const response = await http.post<ApiEnvelope<OceanBookingDocumentMutation>, ApiEnvelope<OceanBookingDocumentMutation>>(`${basePath}/${encodeURIComponent(id)}/documents/upload`, form, { headers: { 'Content-Type': 'multipart/form-data', 'Idempotency-Key': idempotencyKey() } })
+  const result = unwrapApiResponse(response)
+  return { document: document(result.document), bookingVersion: Number(result.bookingVersion) }
+}
+export async function invalidateOceanBookingDocument(id: string, documentId: string, expectedVersion: number) {
+  const response = await http.delete<ApiEnvelope<OceanBookingDocumentInvalidation>, ApiEnvelope<OceanBookingDocumentInvalidation>>(`${basePath}/${encodeURIComponent(id)}/documents/${encodeURIComponent(documentId)}`, { data: { expectedVersion }, headers: { 'Idempotency-Key': idempotencyKey() } })
+  const result = unwrapApiResponse(response)
+  return { documentId: String(result.documentId), bookingVersion: Number(result.bookingVersion) }
+}
+export async function downloadOceanBookingDocument(id: string, documentId: string) {
+  return requestBlob(`${basePath}/${encodeURIComponent(id)}/documents/${encodeURIComponent(documentId)}/download`)
+}
+export async function listWarehouseLogisticsChannels(warehouseId: string): Promise<OceanLogisticsChannel[]> {
+  const response = await http.get<ApiEnvelope<OceanLogisticsChannel[]>, ApiEnvelope<OceanLogisticsChannel[]>>(`${basePath}/channels`, { params: { originWarehouseId: warehouseId } })
+  return (unwrapApiResponse(response) || []).map((item) => ({ channelCode: String(item.channelCode), channelName: String(item.channelName) }))
+}
+export async function listOceanBookingAgents(carrierCode: OceanBookingCarrierCode): Promise<OceanBookingAgentOption[]> {
+  const response = await http.get<ApiEnvelope<OceanBookingAgentOption[]>, ApiEnvelope<OceanBookingAgentOption[]>>(`${basePath}/booking-agents`, { params: { carrierCode } })
+  return (unwrapApiResponse(response) || []).map((item) => ({ ...item, supplierId: String(item.supplierId), name: String(item.name), carrierCodes: [...(item.carrierCodes || [])] }))
+}
+export type { OceanBookingResource, OceanBookingStatus }
diff --git a/src/modules/ocean-bookings/bookingAgents.test.ts b/src/modules/ocean-bookings/bookingAgents.test.ts
new file mode 100644
index 00000000..c70c2171
--- /dev/null
+++ b/src/modules/ocean-bookings/bookingAgents.test.ts
@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest'
+import { shouldClearBookingAgent } from './bookingAgents'
+
+describe('ocean booking agent candidates', () => {
+  const options = [{ supplierId: '11', name: '代理A', carrierCodes: ['MATSON', 'COSCO'] as const }]
+
+  it('keeps an agent returned by the server-filtered carrier candidates', () => {
+    expect(shouldClearBookingAgent('11', options.map((item) => ({ ...item, carrierCodes: [...item.carrierCodes] })))).toBe(false)
+  })
+
+  it('clears an agent missing from the newly selected carrier candidates', () => {
+    expect(shouldClearBookingAgent('12', options.map((item) => ({ ...item, carrierCodes: [...item.carrierCodes] })))).toBe(true)
+  })
+
+  it('does not clear an empty selection', () => {
+    expect(shouldClearBookingAgent(null, [])).toBe(false)
+  })
+})
diff --git a/src/modules/ocean-bookings/bookingAgents.ts b/src/modules/ocean-bookings/bookingAgents.ts
new file mode 100644
index 00000000..982ad619
--- /dev/null
+++ b/src/modules/ocean-bookings/bookingAgents.ts
@@ -0,0 +1,5 @@
+import type { OceanBookingAgentOption } from './types'
+
+export function shouldClearBookingAgent(currentSupplierId: string | null | undefined, options: OceanBookingAgentOption[]) {
+  return Boolean(currentSupplierId) && !options.some((option) => option.supplierId === String(currentSupplierId))
+}
diff --git a/src/modules/ocean-bookings/components/OceanBookingDocumentsPanel.test.ts b/src/modules/ocean-bookings/components/OceanBookingDocumentsPanel.test.ts
new file mode 100644
index 00000000..a5a206f9
--- /dev/null
+++ b/src/modules/ocean-bookings/components/OceanBookingDocumentsPanel.test.ts
@@ -0,0 +1,95 @@
+import ElementPlus from 'element-plus'
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import OceanBookingDocumentsPanel from './OceanBookingDocumentsPanel.vue'
+import { uploadOceanBookingDocument } from '../api/platformOceanBookings'
+
+vi.mock('../api/platformOceanBookings', () => ({
+  downloadOceanBookingDocument: vi.fn(),
+  invalidateOceanBookingDocument: vi.fn(),
+  uploadOceanBookingDocument: vi.fn(),
+}))
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/ocean-bookings/components/OceanBookingDocumentsPanel.vue'), 'utf8')
+
+describe('OceanBookingDocumentsPanel contract', () => {
+  beforeEach(() => { vi.clearAllMocks() })
+  it('owns the two confirmed document types under the booking', () => {
+    expect(source).toContain("value: 'BOOKING_CONFIRMATION', label: '订舱确认文件'")
+    expect(source).toContain("value: 'BILL_OF_LADING', label: '提单文件'")
+    expect(source).toContain('文件统一归属当前订舱')
+    expect(source).not.toContain('TRUCK_APPOINTMENT_ATTACHMENT')
+  })
+
+  it('supports upload, replacement, logical invalidation and download with version chaining', () => {
+    expect(source).toContain('uploadOceanBookingDocument(props.bookingId, props.bookingVersion, type, file)')
+    expect(source).toContain('invalidateOceanBookingDocument(props.bookingId, item.id, version)')
+    expect(source).toContain('version = invalidated.bookingVersion')
+    expect(source).toContain('确认替换')
+    expect(source).toContain('确认作废')
+    expect(source).toContain('downloadOceanBookingDocument')
+    expect(source).toContain('URL.createObjectURL(blob)')
+  })
+
+  it('accepts every file format while rejecting a single file above 50 MiB before upload', () => {
+    expect(source).toContain('const maxFileBytes = 50 * 1024 * 1024')
+    expect(source).toContain('file.size > maxFileBytes')
+    expect(source).toContain('单个订舱资料文件不能超过 50MB，请重新选择')
+    expect(source).toContain('任意格式，单文件不超过 50MB')
+    expect(source).not.toContain('accept="')
+  })
+
+  it('rejects an oversized arbitrary-format file before calling the backend', async () => {
+    const wrapper = mount(OceanBookingDocumentsPanel, {
+      props: { bookingId: '123', bookingVersion: 2, bookingStatus: 'DRAFT', documents: [], canManage: true },
+      global: { plugins: [ElementPlus] },
+    })
+    const file = new File(['data'], 'archive.custom', { type: 'application/x-custom' })
+    Object.defineProperty(file, 'size', { value: 50 * 1024 * 1024 + 1 })
+    const input = wrapper.get('input[type="file"]')
+    Object.defineProperty(input.element, 'files', { configurable: true, value: [file] })
+    await input.trigger('change')
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('单个订舱资料文件不能超过 50MB')
+    expect(uploadOceanBookingDocument).not.toHaveBeenCalled()
+    wrapper.unmount()
+  })
+
+  it('makes released booking files permanently read-only and preserves traced errors', () => {
+    expect(source).toContain("props.bookingStatus === 'DRAFT' && props.canManage")
+    expect(source).toContain('已放舱 · 永久只读')
+    expect(source).toContain('manageReason')
+    expect(source).toContain('<ApiErrorMeta :details="error" />')
+    expect(source).toContain('订舱资料上传失败，请稍后重试')
+    expect(source).toContain('订舱资料下载失败，请稍后重试')
+  })
+
+  it('suppresses duplicate file mutations and protects list-only access', () => {
+    expect(source).toContain('if (busyDocumentId.value || busyType.value) return')
+    expect(source).toContain('if (busyDocumentId.value || busyType.value || !editable.value) return')
+    expect(source).toContain('!file || !editable.value || busyType.value || busyDocumentId.value')
+    expect(source).toContain(':disabled="Boolean(busyType || busyDocumentId)"')
+  })
+
+  it('keeps long Unicode active and invalidated file names readable', () => {
+    const fileName = '客户资料-中文-🚢-é-'.repeat(16) + '.数据包'
+    const document = {
+      id: 'doc-1', oceanBookingId: '123', fileId: 'file-1', documentType: 'BILL_OF_LADING' as const,
+      fileName, fileHash: null, sizeBytes: 12, contentType: null, valid: true,
+      uploadedBy: '7', uploadedByName: '操作员', uploadedAt: '2026-08-31',
+      invalidatedBy: null, invalidatedByName: null, invalidatedAt: null,
+    }
+    const wrapper = mount(OceanBookingDocumentsPanel, {
+      props: { bookingId: '123', bookingVersion: 2, bookingStatus: 'DRAFT', documents: [document], canManage: false, manageReason: '暂无订舱资料维护权限' },
+      global: { plugins: [ElementPlus] },
+    })
+    expect(wrapper.get('.booking-document-list strong').attributes('title')).toBe(fileName)
+    expect(wrapper.find('input[type="file"]').exists()).toBe(false)
+    expect(wrapper.text()).not.toContain('作废')
+    expect(source).toContain('.booking-document-history li span{min-width:0;overflow-wrap:anywhere}')
+    wrapper.unmount()
+  })
+})
diff --git a/src/modules/ocean-bookings/components/OceanBookingDocumentsPanel.vue b/src/modules/ocean-bookings/components/OceanBookingDocumentsPanel.vue
new file mode 100644
index 00000000..3666f5d3
--- /dev/null
+++ b/src/modules/ocean-bookings/components/OceanBookingDocumentsPanel.vue
@@ -0,0 +1,128 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, ref } from 'vue'
+import { FileUp } from '@lucide/vue'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { downloadOceanBookingDocument, invalidateOceanBookingDocument, uploadOceanBookingDocument } from '../api/platformOceanBookings'
+import type { OceanBookingDocument, OceanBookingDocumentType, OceanBookingStatus } from '../types'
+
+const props = defineProps<{ bookingId: string; bookingVersion: number; bookingStatus: OceanBookingStatus; documents: OceanBookingDocument[]; canManage: boolean; manageReason?: string }>()
+const emit = defineEmits<{ updated: [documents: OceanBookingDocument[], bookingVersion: number] }>()
+const busyType = ref<OceanBookingDocumentType | ''>('')
+const busyDocumentId = ref('')
+const error = ref<ApiErrorDetails | null>(null)
+const maxFileBytes = 50 * 1024 * 1024
+const types: Array<{ value: OceanBookingDocumentType; label: string; description: string }> = [
+  { value: 'BOOKING_CONFIRMATION', label: '订舱确认文件', description: '用于确认已订妥舱位及放舱前资料完整性' },
+  { value: 'BILL_OF_LADING', label: '提单文件', description: '用于提单号和拖车派车前资料校验' },
+]
+const editable = computed(() => props.bookingStatus === 'DRAFT' && props.canManage)
+const validDocuments = computed(() => props.documents.filter((item) => item.valid))
+const invalidDocuments = computed(() => props.documents.filter((item) => !item.valid))
+
+function documentsOfType(type: OceanBookingDocumentType) { return validDocuments.value.filter((item) => item.documentType === type) }
+function fileSize(value: number | null) {
+  if (value == null) return '大小未知'
+  if (value < 1024) return `${value} B`
+  if (value < 1024 * 1024) return `${(value / 1024).toFixed(1)} KB`
+  return `${(value / 1024 / 1024).toFixed(1)} MB`
+}
+function saveBlob(blob: Blob, name: string) {
+  const url = URL.createObjectURL(blob)
+  const anchor = document.createElement('a')
+  anchor.href = url
+  anchor.download = name || '订舱资料'
+  anchor.click()
+  URL.revokeObjectURL(url)
+}
+async function download(item: OceanBookingDocument) {
+  if (busyDocumentId.value || busyType.value) return
+  busyDocumentId.value = item.id
+  error.value = null
+  try {
+    saveBlob(await downloadOceanBookingDocument(props.bookingId, item.id), item.fileName)
+  } catch (cause) {
+    error.value = getApiErrorDetails(cause, '订舱资料下载失败，请稍后重试')
+  } finally {
+    busyDocumentId.value = ''
+  }
+}
+async function invalidate(item: OceanBookingDocument, expectedVersion = props.bookingVersion) {
+  const result = await invalidateOceanBookingDocument(props.bookingId, item.id, expectedVersion)
+  const nextDocuments = props.documents.map((document) => document.id === item.id ? { ...document, valid: false, invalidatedAt: new Date().toISOString() } : document)
+  emit('updated', nextDocuments, result.bookingVersion)
+  return { documents: nextDocuments, version: result.bookingVersion }
+}
+async function remove(item: OceanBookingDocument) {
+  if (busyDocumentId.value || busyType.value || !editable.value) return
+  busyDocumentId.value = item.id
+  error.value = null
+  try {
+    await ElMessageBox.confirm(`确认作废“${item.fileName}”？文件历史仍会保留。`, '作废订舱资料', { customClass: 'admin-density-confirm', confirmButtonText: '确认作废', cancelButtonText: '取消', type: 'warning' })
+    await invalidate(item)
+    ElMessage.success('订舱资料已作废')
+  } catch (cause) {
+    if (cause === 'cancel' || cause === 'close') return
+    error.value = getApiErrorDetails(cause, '订舱资料作废失败，请稍后重试')
+  } finally {
+    busyDocumentId.value = ''
+  }
+}
+async function selectFile(event: Event, type: OceanBookingDocumentType) {
+  const input = event.target as HTMLInputElement
+  const file = input.files?.[0]
+  input.value = ''
+  if (!file || !editable.value || busyType.value || busyDocumentId.value) return
+  if (file.size > maxFileBytes) {
+    error.value = { message: '单个订舱资料文件不能超过 50MB，请重新选择' }
+    return
+  }
+  const previous = documentsOfType(type)
+  busyType.value = type
+  error.value = null
+  try {
+    if (previous.length) {
+      await ElMessageBox.confirm(`将上传“${file.name}”并作废当前 ${previous.length} 份同类型文件，是否继续？`, '替换订舱资料', { customClass: 'admin-density-confirm', confirmButtonText: '确认替换', cancelButtonText: '取消', type: 'warning' })
+    }
+    const uploaded = await uploadOceanBookingDocument(props.bookingId, props.bookingVersion, type, file)
+    let documents = [...props.documents, uploaded.document]
+    let version = uploaded.bookingVersion
+    emit('updated', documents, version)
+    for (const item of previous) {
+      const invalidated = await invalidateOceanBookingDocument(props.bookingId, item.id, version)
+      version = invalidated.bookingVersion
+      documents = documents.map((document) => document.id === item.id ? { ...document, valid: false, invalidatedAt: new Date().toISOString() } : document)
+      emit('updated', documents, version)
+    }
+    ElMessage.success(previous.length ? '订舱资料已替换' : '订舱资料已上传')
+  } catch (cause) {
+    if (cause === 'cancel' || cause === 'close') return
+    error.value = getApiErrorDetails(cause, '订舱资料上传失败，请稍后重试')
+  } finally {
+    busyType.value = ''
+  }
+}
+</script>
+
+<template>
+  <section class="surface-panel booking-documents admin-density" aria-label="订舱资料">
+    <div class="booking-documents__heading"><div><h2>订舱资料</h2><p>文件统一归属当前订舱；放舱要求至少一份有效的订舱确认文件或提单文件。</p></div><el-tag v-if="bookingStatus === 'RELEASED'" type="info">已放舱 · 永久只读</el-tag></div>
+    <el-alert v-if="bookingStatus === 'DRAFT' && !editable && manageReason" type="warning" :closable="false" show-icon :title="manageReason" />
+    <el-alert v-if="error" type="error" :closable="true" show-icon @close="error = null"><template #title>{{ error.message }}</template><ApiErrorMeta :details="error" /></el-alert>
+    <div class="booking-document-types">
+      <article v-for="type in types" :key="type.value" class="booking-document-card">
+        <div class="booking-document-card__heading"><div><h3>{{ type.label }}</h3><p>{{ type.description }}</p><small class="booking-document-limit">任意格式，单文件不超过 50MB</small></div><label v-if="editable" class="booking-document-upload" :class="{ 'is-disabled': Boolean(busyType || busyDocumentId) }"><FileUp :size="15" /><span>{{ busyType === type.value ? '上传处理中' : (documentsOfType(type.value).length ? '替换文件' : '上传文件') }}</span><input type="file" :disabled="Boolean(busyType || busyDocumentId)" @change="selectFile($event, type.value)" /></label></div>
+        <el-empty v-if="!documentsOfType(type.value).length" description="暂无有效文件" :image-size="48" />
+        <ul v-else class="booking-document-list"><li v-for="item in documentsOfType(type.value)" :key="item.id"><div><strong :title="item.fileName">{{ item.fileName }}</strong><small>{{ fileSize(item.sizeBytes) }} · {{ item.uploadedByName || item.uploadedBy }} · {{ item.uploadedAt }}</small></div><div class="booking-document-actions density-actions"><el-button class="density-action" size="small" plain :loading="busyDocumentId === item.id" @click="download(item)">下载</el-button><el-button data-tone="danger" class="density-action" v-if="editable" size="small" type="danger" plain :loading="busyDocumentId === item.id" @click="remove(item)">作废</el-button></div></li></ul>
+      </article>
+    </div>
+    <details v-if="invalidDocuments.length" class="booking-document-history"><summary>查看已作废资料（{{ invalidDocuments.length }}）</summary><ul><li v-for="item in invalidDocuments" :key="item.id"><span>{{ item.fileName }}</span><small>{{ item.invalidatedByName || item.invalidatedBy || '系统' }} · {{ item.invalidatedAt || '—' }}</small></li></ul></details>
+  </section>
+</template>
+
+<style scoped>
+.booking-documents{padding:var(--admin-space-5)}.booking-documents__heading,.booking-document-card__heading,.booking-document-list li,.booking-document-actions{display:flex;align-items:center}.booking-documents__heading,.booking-document-card__heading,.booking-document-list li{justify-content:space-between;gap:var(--admin-space-5)}.booking-documents__heading{margin-bottom:var(--admin-space-5)}.booking-documents h2,.booking-document-card h3{margin:0}.booking-documents__heading h2{font-size:var(--admin-font-section)}.booking-documents__heading p,.booking-document-card__heading p{margin:var(--admin-space-1) 0 0;color:var(--cc-muted);font-size:var(--admin-font-caption)}.booking-document-limit{display:block;margin-top:5px;color:var(--cc-muted);font-size:var(--admin-font-caption)}.booking-document-types{display:grid;grid-template-columns:1fr;gap:0}.booking-document-card{min-width:0;border:0;border-top:1px solid var(--cc-border);border-radius:0;padding:var(--admin-space-3) 0}.booking-document-card h3{font-size:var(--admin-font-section)}.booking-document-upload{display:flex;flex:0 0 auto;align-items:center;gap:var(--admin-space-2);min-height:var(--admin-control-height);padding:0 var(--admin-space-5);border:1px solid var(--cc-primary);border-radius:var(--admin-radius);color:var(--cc-primary);font-size:var(--admin-font-caption);cursor:pointer}.booking-document-upload.is-disabled{cursor:not-allowed;opacity:.55}.booking-document-upload input{position:absolute;width:1px;height:1px;overflow:hidden;opacity:0}.booking-document-list,.booking-document-history ul{display:grid;gap:var(--admin-space-3);margin:var(--admin-space-5) 0 0;padding:0;list-style:none}.booking-document-list li{min-width:0;border-radius:0;background:transparent;border-bottom:1px solid var(--cc-border);padding:var(--admin-space-2) 0}.booking-document-list li>div:first-child{display:grid;min-width:0;gap:3px}.booking-document-list strong{white-space:normal;overflow-wrap:anywhere}.booking-document-list small,.booking-document-history small{color:var(--cc-muted);font-size:var(--admin-font-caption)}.booking-document-actions{flex:0 0 auto}.booking-document-actions :deep(.el-button){margin-left:0}.booking-document-history{margin-top:var(--admin-space-5);color:var(--cc-muted);font-size:var(--admin-font-caption)}.booking-document-history summary{cursor:pointer}.booking-document-history li{display:flex;justify-content:space-between;gap:var(--admin-space-5);padding:7px var(--admin-space-4);border-bottom:1px solid var(--cc-border)}@media(max-width:900px){.booking-document-types{grid-template-columns:1fr;gap:0}}@media(max-width:560px){.booking-documents__heading,.booking-document-card__heading,.booking-document-list li{align-items:flex-start;flex-direction:column}.booking-document-actions{width:100%}}
+.booking-document-history li span{min-width:0;overflow-wrap:anywhere}
+</style>
diff --git a/src/modules/ocean-bookings/components/OceanBookingPrintDialog.test.ts b/src/modules/ocean-bookings/components/OceanBookingPrintDialog.test.ts
new file mode 100644
index 00000000..02f33242
--- /dev/null
+++ b/src/modules/ocean-bookings/components/OceanBookingPrintDialog.test.ts
@@ -0,0 +1,79 @@
+import ElementPlus from 'element-plus'
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import OceanBookingPrintDialog from './OceanBookingPrintDialog.vue'
+import { downloadOceanBookingPrint } from '../api/platformOceanBookings'
+import { ApiResponseError } from '@/shared/api/http'
+
+vi.mock('../api/platformOceanBookings', () => ({ downloadOceanBookingPrint: vi.fn() }))
+
+describe('OceanBookingPrintDialog', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    document.body.innerHTML = ''
+    vi.stubGlobal('URL', { createObjectURL: vi.fn(() => 'blob:booking-print'), revokeObjectURL: vi.fn() })
+  })
+
+  it('offers the two confirmed documents and previews the selected PDF', async () => {
+    vi.mocked(downloadOceanBookingPrint).mockResolvedValue(new Blob(['pdf'], { type: 'application/pdf' }))
+    const wrapper = mount(OceanBookingPrintDialog, {
+      props: { modelValue: true, bookingId: '123', bookingNo: 'OB-123', allowed: true },
+      global: { plugins: [ElementPlus] },
+      attachTo: document.body,
+    })
+    await flushPromises()
+
+    expect(document.body.textContent).toContain('出口货物托运单')
+    expect(document.body.textContent).toContain('提单确认件')
+    await wrapper.findAll('.booking-print-option')[0]!.trigger('click')
+    await flushPromises()
+    await Array.from(document.body.querySelectorAll('button')).find((button) => button.textContent?.includes('预览 PDF'))?.click()
+    await flushPromises()
+
+    expect(downloadOceanBookingPrint).toHaveBeenCalledWith('123', 'SHIPPING_INSTRUCTION')
+    expect(document.body.querySelector('iframe')?.getAttribute('src')).toBe('blob:booking-print')
+    wrapper.unmount()
+  })
+
+  it('shows permission and API errors without attempting a download', async () => {
+    const denied = mount(OceanBookingPrintDialog, { props: { modelValue: true, bookingId: '123', allowed: false }, global: { plugins: [ElementPlus] }, attachTo: document.body })
+    await flushPromises()
+    expect(document.body.textContent).toContain('暂无订舱单据打印权限')
+    expect(downloadOceanBookingPrint).not.toHaveBeenCalled()
+    denied.unmount()
+
+    vi.mocked(downloadOceanBookingPrint).mockRejectedValue(new ApiResponseError('缺少提单号', 'B0409', 200, undefined, 'req-print', 'trace-print'))
+    const failed = mount(OceanBookingPrintDialog, { props: { modelValue: true, bookingId: '123', allowed: true }, global: { plugins: [ElementPlus] }, attachTo: document.body })
+    await flushPromises()
+    await failed.findAll('.booking-print-option')[1]!.trigger('click')
+    await flushPromises()
+    await Array.from(document.body.querySelectorAll('button')).find((button) => button.textContent?.includes('预览 PDF'))?.click()
+    await flushPromises()
+    expect(document.body.textContent).toContain('缺少提单号')
+    expect(document.body.textContent).toContain('req-print')
+    expect(document.body.textContent).toContain('trace-print')
+    failed.unmount()
+  })
+
+  it('suppresses duplicate preview clicks and restores loading after completion', async () => {
+    let resolvePrint!: (blob: Blob) => void
+    vi.mocked(downloadOceanBookingPrint).mockImplementation(() => new Promise<Blob>((resolve) => { resolvePrint = resolve }))
+    const wrapper = mount(OceanBookingPrintDialog, {
+      props: { modelValue: true, bookingId: '123', bookingNo: 'OB-123', allowed: true },
+      global: { plugins: [ElementPlus] },
+      attachTo: document.body,
+    })
+    await flushPromises()
+    await wrapper.findAll('.booking-print-option')[0]!.trigger('click')
+    const preview = Array.from(document.body.querySelectorAll('button')).find((button) => button.textContent?.includes('预览 PDF'))!
+    preview.click()
+    preview.click()
+    await flushPromises()
+    expect(downloadOceanBookingPrint).toHaveBeenCalledTimes(1)
+    expect(preview.disabled).toBe(true)
+    resolvePrint(new Blob(['pdf'], { type: 'application/pdf' }))
+    await flushPromises()
+    expect(document.body.querySelector('iframe')).not.toBeNull()
+    wrapper.unmount()
+  })
+})
diff --git a/src/modules/ocean-bookings/components/OceanBookingPrintDialog.vue b/src/modules/ocean-bookings/components/OceanBookingPrintDialog.vue
new file mode 100644
index 00000000..dce1ab21
--- /dev/null
+++ b/src/modules/ocean-bookings/components/OceanBookingPrintDialog.vue
@@ -0,0 +1,109 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onBeforeUnmount, ref, watch } from 'vue'
+import { Download, FileText } from '@lucide/vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { downloadOceanBookingPrint } from '../api/platformOceanBookings'
+import type { OceanBookingPrintType } from '../types'
+
+const props = defineProps<{ bookingId: string; bookingNo?: string | null; allowed: boolean }>()
+const open = defineModel<boolean>({ default: false })
+const selectedType = ref<OceanBookingPrintType | ''>('')
+const loading = ref(false)
+const previewUrl = ref('')
+const printBlob = ref<Blob | null>(null)
+const error = ref<ApiErrorDetails | null>(null)
+
+const options: Array<{ value: OceanBookingPrintType; label: string; description: string }> = [
+  { value: 'SHIPPING_INSTRUCTION', label: '出口货物托运单', description: 'Sea Freight Shipping Instructions · PDF' },
+  { value: 'BILL_OF_LADING_CONFIRMATION', label: '提单确认件', description: '提单内容确认及打印 · PDF' },
+]
+const selectedOption = computed(() => options.find((item) => item.value === selectedType.value) || null)
+const previewTitle = computed(() => `${selectedOption.value?.label || '打印单据'} · ${props.bookingNo || props.bookingId}`)
+
+function releasePreview() {
+  if (previewUrl.value) URL.revokeObjectURL(previewUrl.value)
+  previewUrl.value = ''
+  printBlob.value = null
+}
+function reset() {
+  releasePreview()
+  selectedType.value = ''
+  error.value = null
+  loading.value = false
+}
+async function preview() {
+  if (!props.allowed || !selectedType.value || loading.value) return
+  loading.value = true
+  error.value = null
+  releasePreview()
+  try {
+    const blob = await downloadOceanBookingPrint(props.bookingId, selectedType.value)
+    printBlob.value = blob
+    previewUrl.value = URL.createObjectURL(blob)
+  } catch (cause) {
+    error.value = getApiErrorDetails(cause, '打印单据加载失败，请稍后重试')
+  } finally {
+    loading.value = false
+  }
+}
+function backToSelection() {
+  releasePreview()
+  error.value = null
+}
+function download() {
+  if (!printBlob.value || !selectedOption.value) return
+  const url = URL.createObjectURL(printBlob.value)
+  const anchor = document.createElement('a')
+  anchor.href = url
+  anchor.download = `${props.bookingNo || props.bookingId}-${selectedOption.value.label}.pdf`
+  anchor.click()
+  URL.revokeObjectURL(url)
+}
+
+watch(open, (value) => { if (!value) reset() })
+onBeforeUnmount(releasePreview)
+</script>
+
+<template>
+  <AppDialog class="admin-density-dialog"
+    v-model="open"
+    :title="previewUrl ? previewTitle : '选择打印单据'"
+    width="min(1120px, calc(100vw - 48px))"
+    :loading="loading"
+    :show-confirm="false"
+    :cancel-text="previewUrl ? '关闭预览' : '取消'"
+    destroy-on-close
+  >
+    <el-alert v-if="!allowed" title="暂无订舱单据打印权限" type="warning" :closable="false" show-icon />
+    <template v-else-if="!previewUrl">
+      <p class="booking-print-current">当前订舱：<strong>{{ bookingNo || bookingId }}</strong></p>
+      <div class="booking-print-options" role="radiogroup" aria-label="打印单据类型">
+        <label v-for="item in options" :key="item.value" class="booking-print-option" :class="{ 'is-selected': selectedType === item.value }">
+          <el-radio v-model="selectedType" :value="item.value"><span class="sr-only">{{ item.label }}</span></el-radio>
+          <FileText :size="22" />
+          <span><strong>{{ item.label }}</strong><small>{{ item.description }}</small></span>
+        </label>
+      </div>
+      <LoadErrorState v-if="error" title="打印单据加载失败" :message="error.message" :show-retry="false"><template #details><ApiErrorMeta :details="error" /></template></LoadErrorState>
+    </template>
+    <div v-else class="booking-print-preview" :aria-label="previewTitle">
+      <iframe :src="previewUrl" :title="`${previewTitle} PDF 预览`" />
+    </div>
+    <template #footer="{ close }">
+      <div class="app-dialog__footer booking-print-footer">
+        <el-button v-if="previewUrl" :disabled="loading" @click="backToSelection">返回选择</el-button>
+        <el-button v-else :disabled="loading" @click="close">取消</el-button>
+        <el-button v-if="previewUrl" type="primary" :disabled="!printBlob" @click="download"><Download :size="16" />下载 PDF</el-button>
+        <el-button v-else type="primary" :loading="loading" :disabled="!allowed || !selectedType" @click="preview">预览 PDF</el-button>
+      </div>
+    </template>
+  </AppDialog>
+</template>
+
+<style scoped>
+.booking-print-current{margin:0 0 var(--admin-space-5);color:var(--cc-muted);font-size:var(--admin-font-body)}.booking-print-current strong{color:var(--cc-text)}.booking-print-options{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:var(--admin-space-5)}.booking-print-option{display:grid;grid-template-columns:auto auto minmax(0,1fr);align-items:center;gap:var(--admin-space-5);border:1px solid var(--cc-border);border-radius:var(--admin-radius);background:var(--admin-surface);cursor:pointer;min-height:var(--admin-empty-height, 64px);padding:var(--admin-space-3) var(--admin-space-5)}.booking-print-option.is-selected{border-color:var(--cc-primary);background:var(--cc-primary-soft)}.booking-print-option span{display:grid;min-width:0;gap:var(--admin-space-1)}.booking-print-option strong{color:var(--cc-text);font-size:var(--admin-font-section)}.booking-print-option small{color:var(--cc-muted);font-size:var(--admin-font-caption)}.booking-print-preview{min-height:0;overflow:hidden;border:1px solid var(--cc-border);border-radius:var(--admin-radius);background:#f3f5f8}.booking-print-preview iframe{display:block;width:100%;height:min(72vh,760px);border:0;background:var(--admin-surface)}.booking-print-footer{width:100%}.sr-only{position:absolute;width:1px;height:1px;padding:0;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}@media(max-width:720px){.booking-print-options{grid-template-columns:1fr}.booking-print-preview iframe{height:68vh}}
+</style>
diff --git a/src/modules/ocean-bookings/containerRequirements.test.ts b/src/modules/ocean-bookings/containerRequirements.test.ts
new file mode 100644
index 00000000..4363467a
--- /dev/null
+++ b/src/modules/ocean-bookings/containerRequirements.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+import { containerRequirementError, createBlankContainerRequirement, selectContainerRequirementType } from './containerRequirements'
+
+describe('ocean booking container requirements', () => {
+  it('starts with one requirement and applies the fixed platform specification', () => {
+    const requirement = createBlankContainerRequirement()
+    expect(requirement).toEqual({ containerType: '40HQ', containerKind: 'FCL', quantity: 1, capacityCbm: 68, maxWeightKg: 19500 })
+    selectContainerRequirementType(requirement, '40GP')
+    expect(requirement).toMatchObject({ containerType: '40GP', capacityCbm: 58, maxWeightKg: 19500 })
+  })
+
+  it('requires positive quantities and fixed specifications', () => {
+    const requirement = createBlankContainerRequirement()
+    expect(containerRequirementError([])).toContain('至少保留一项')
+    expect(containerRequirementError([{ ...requirement, quantity: 0 }])).toContain('数量必须')
+    expect(containerRequirementError([{ ...requirement, capacityCbm: 75 }])).toContain('固定规格')
+    expect(containerRequirementError([requirement])).toBeNull()
+  })
+
+  it('limits one booking to twenty requirement rows', () => {
+    const requirements = Array.from({ length: 21 }, () => createBlankContainerRequirement())
+    expect(containerRequirementError(requirements)).toContain('最多登记 20 项')
+  })
+})
diff --git a/src/modules/ocean-bookings/containerRequirements.ts b/src/modules/ocean-bookings/containerRequirements.ts
new file mode 100644
index 00000000..73a55b1a
--- /dev/null
+++ b/src/modules/ocean-bookings/containerRequirements.ts
@@ -0,0 +1,23 @@
+import type { OceanBookingContainerRequirement } from './types'
+import { applyContainerSpecification, containerSpecification, DEFAULT_CONTAINER_TYPE } from '@/shared/domain/containerSpecifications'
+
+export function createBlankContainerRequirement(): OceanBookingContainerRequirement {
+  return { containerType: DEFAULT_CONTAINER_TYPE, containerKind: 'FCL', quantity: 1, capacityCbm: 68, maxWeightKg: 19500 }
+}
+
+export function selectContainerRequirementType(requirement: OceanBookingContainerRequirement, containerType: string) {
+  applyContainerSpecification(requirement, containerType)
+}
+
+export function containerRequirementError(requirements: OceanBookingContainerRequirement[]) {
+  if (!requirements.length) return '请至少保留一项柜型需求'
+  if (requirements.length > 20) return '单次订舱最多登记 20 项柜型需求'
+  const invalidQuantityIndex = requirements.findIndex((item) => !Number.isInteger(Number(item.quantity)) || Number(item.quantity) < 1)
+  if (invalidQuantityIndex >= 0) return `第 ${invalidQuantityIndex + 1} 项柜型需求的数量必须是大于 0 的整数`
+  const invalid = requirements.find((item) => {
+    const specification = containerSpecification(item.containerType)
+    return !specification || Number(item.capacityCbm) !== specification.capacityCbm
+      || Number(item.maxWeightKg) !== specification.maxWeightKg
+  })
+  return invalid ? `柜型 ${invalid.containerType || '未命名'} 必须使用平台固定规格，请重新选择柜型` : null
+}
diff --git a/src/modules/ocean-bookings/index.ts b/src/modules/ocean-bookings/index.ts
new file mode 100644
index 00000000..5bfe4427
--- /dev/null
+++ b/src/modules/ocean-bookings/index.ts
@@ -0,0 +1,4 @@
+export { oceanBookingRoutes } from './routes'
+export { getOceanBooking, listOceanBookingLinkCandidates, listOceanBookings, listWarehouseLogisticsChannels, type OceanLogisticsChannel } from './api/platformOceanBookings'
+export * from './status'
+export * from './types'
diff --git a/src/modules/ocean-bookings/pages/OceanBookingDetailView.release.test.ts b/src/modules/ocean-bookings/pages/OceanBookingDetailView.release.test.ts
new file mode 100644
index 00000000..8fd9fb34
--- /dev/null
+++ b/src/modules/ocean-bookings/pages/OceanBookingDetailView.release.test.ts
@@ -0,0 +1,210 @@
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import ElementPlus from 'element-plus'
+import { ApiResponseError } from '@/shared/api/http'
+import { listPlatformTenants } from '@/modules/iam'
+import { listPlatformPartners } from '@/modules/master-data'
+import { listPlatformWarehouses } from '@/modules/warehouses'
+import {
+  createOceanBooking,
+  getOceanBooking,
+  listOceanBookingAgents,
+  listWarehouseLogisticsChannels,
+  releaseOceanBooking,
+  updateOceanBookingDraft,
+} from '../api/platformOceanBookings'
+import type { OceanBookingDetail, OceanBookingStatus } from '../types'
+import OceanBookingDetailView from './OceanBookingDetailView.vue'
+
+const routerReplace = vi.hoisted(() => vi.fn())
+const routeState = vi.hoisted(() => ({ name: 'ocean-booking-detail', params: { bookingId: '123' } }))
+vi.mock('vue-router', () => ({
+  useRoute: () => routeState,
+  useRouter: () => ({ push: vi.fn(), replace: routerReplace }),
+}))
+vi.mock('@/core/access/accessPreview', () => ({ useAccessPreviewStore: () => ({ can: () => true }) }))
+vi.mock('@/core/workspace-tabs/workspaceTabs', () => ({ useWorkspaceTabsStore: () => ({ removeByIds: vi.fn(), bumpCacheEpoch: vi.fn() }) }))
+vi.mock('@/modules/iam', () => ({ listPlatformTenants: vi.fn() }))
+vi.mock('@/modules/master-data', () => ({ listPlatformPartners: vi.fn() }))
+vi.mock('@/modules/warehouses', () => ({ listPlatformWarehouses: vi.fn() }))
+vi.mock('../api/platformOceanBookings', () => ({
+  createOceanBooking: vi.fn(), deleteOceanBookingDraft: vi.fn(), getOceanBooking: vi.fn(),
+  listOceanBookingAgents: vi.fn(), listWarehouseLogisticsChannels: vi.fn(),
+  releaseOceanBooking: vi.fn(), updateOceanBookingDraft: vi.fn(),
+}))
+
+function booking(status: OceanBookingStatus = 'DRAFT', version = 3, billOfLadingNo = 'BL-001'): OceanBookingDetail {
+  const resource = {
+    id: '123', bookingNo: 'OB-123', status, version, customerId: '456', customerName: '测试客户',
+    billOfLadingNo, shipperName: '发货人', consigneeName: '收货人', containerCount: 2,
+    channelCode: 'MATSON_CLX', channelName: '美森正班', warehouseId: '8', warehouseName: '义乌仓',
+    shippingCompanyId: '10', shippingCompanyName: '测试船公司', carrierCode: 'MATSON' as const,
+    bookingAgentId: '20', bookingAgentName: '订舱代理', vesselName: 'TEST VESSEL', voyageNo: 'V001',
+    departurePortCode: 'CNSHA', departurePortName: '上海', destinationPortCode: 'USLAX', destinationPortName: '洛杉矶',
+    placeOfDelivery: 'ONT8',
+    estimatedSailingAt: '2026-09-01T08:00:00', estimatedArrivalAt: '2026-09-20T08:00:00', remark: null,
+    createdAt: null, updatedAt: null, orderNo: null, carrierName: null, bookingAgent: null,
+    pol: '上海', pod: '洛杉矶', mblShipper: null, mblConsignee: null, soNo: null, cutoffAt: null,
+    etd: null, atd: null, eta: null, ata: null, containerSummary: null, amount: null, currency: null,
+  }
+  return {
+    ...resource,
+    oceanBooking: resource,
+    parties: [
+      { partyType: 'SHIPPER', partyName: '发货人' },
+      { partyType: 'CONSIGNEE', partyName: '收货人' },
+      { partyType: 'NOTIFY_PARTY', partyName: '通知人' },
+    ],
+    containerRequirements: [{ requirementId: '31', containerType: '40HQ', containerKind: 'FCL', quantity: 2, remainingQuantity: 2, capacityCbm: 68, maxWeightKg: 19500 }],
+    containers: [],
+    documents: [{ id: '41', oceanBookingId: '123', fileId: '51', documentType: 'BOOKING_CONFIRMATION', fileName: '订舱确认.pdf', fileHash: null, sizeBytes: 128, contentType: 'application/pdf', valid: true, uploadedBy: '7', uploadedByName: '平台', uploadedAt: '2026-08-31T10:00:00', invalidatedBy: null, invalidatedByName: null, invalidatedAt: null }],
+    histories: [], statusHistory: [],
+  }
+}
+
+type ViewModel = {
+  form: { data: import('../types').OceanBookingDraftData }
+  save: () => Promise<void>
+  selectCustomer: (value: unknown) => void
+  canManageDocuments: boolean
+  detail: OceanBookingDetail | null
+  actionError: { code?: string; requestId?: string; traceId?: string; message: string } | null
+  actionSaving: boolean
+  submitRelease: () => Promise<void>
+}
+
+async function mountView() {
+  const wrapper = mount(OceanBookingDetailView, {
+    global: {
+      plugins: [ElementPlus],
+      stubs: {
+        AdminPage: { template: '<main><slot /></main>' },
+        DetailPageLayout: { template: '<section><slot name="header" /><slot /></section>' },
+        PageToolbar: { template: '<header><slot name="actions" /></header>' },
+        CarrierScheduleQueryPanel: true,
+      },
+    },
+  })
+  await flushPromises()
+  return { wrapper, vm: wrapper.vm as unknown as ViewModel }
+}
+
+describe('OceanBookingDetailView one-click release', () => {
+  beforeEach(() => {
+    routeState.name = 'ocean-booking-detail'; routeState.params.bookingId = '123'
+    vi.clearAllMocks()
+    vi.mocked(getOceanBooking).mockResolvedValue(booking())
+    vi.mocked(listPlatformTenants).mockResolvedValue({ records: [], page: 1, size: 200, total: 0, pages: 0 })
+    vi.mocked(listPlatformPartners).mockResolvedValue({ records: [], page: 1, size: 200, total: 0, pages: 0 })
+    vi.mocked(listPlatformWarehouses).mockResolvedValue({ records: [], page: 1, size: 200, total: 0, pages: 0 })
+    vi.mocked(listWarehouseLogisticsChannels).mockResolvedValue([{ channelCode: 'MATSON_CLX_TRUCK', channelName: '美森正班海卡' }])
+    vi.mocked(listOceanBookingAgents).mockResolvedValue([{ supplierId: '20', name: '订舱代理', carrierCodes: ['MATSON'] }])
+  })
+
+  it('shows the matching fixed logistics group instead of the underlying price-book channel', async () => {
+    const { wrapper } = await mountView()
+    expect(wrapper.text()).toContain('美森正班')
+    expect(wrapper.text()).not.toContain('美森正班海卡')
+    wrapper.unmount()
+  })
+
+  it('saves dirty form data and releases with the returned latest version', async () => {
+    vi.mocked(updateOceanBookingDraft).mockResolvedValue(booking('DRAFT', 4, 'NEW-BL'))
+    vi.mocked(releaseOceanBooking).mockResolvedValue(booking('RELEASED', 5, 'NEW-BL'))
+    const { vm } = await mountView()
+    vm.form.data.billOfLadingNo = '  NEW-BL  '
+
+    await vm.submitRelease()
+
+    expect(updateOceanBookingDraft).toHaveBeenCalledWith('123', expect.objectContaining({ expectedVersion: 3, data: expect.objectContaining({ billOfLadingNo: 'NEW-BL' }) }))
+    expect(releaseOceanBooking).toHaveBeenCalledWith('123', { expectedVersion: 4 })
+    expect(vi.mocked(updateOceanBookingDraft).mock.invocationCallOrder[0]).toBeLessThan(vi.mocked(releaseOceanBooking).mock.invocationCallOrder[0]!)
+    expect(vm.detail?.status).toBe('RELEASED')
+    expect(vm.detail?.version).toBe(5)
+  })
+
+  it('saves a new booking without a customer using explicit nulls', async () => {
+    routeState.name = 'ocean-booking-create'; routeState.params.bookingId = 'new'
+    vi.mocked(createOceanBooking).mockResolvedValue(booking())
+    const { vm, wrapper } = await mountView()
+    await vm.save()
+    expect(createOceanBooking).toHaveBeenCalledWith(expect.objectContaining({ data: expect.objectContaining({ customerId: null, customerName: null }) }))
+    wrapper.unmount()
+  })
+
+  it('clears an existing customer before saving and releasing with the returned version', async () => {
+    const saved = booking('DRAFT', 4)
+    saved.customerId = null; saved.customerName = null; saved.oceanBooking.customerId = null; saved.oceanBooking.customerName = null
+    vi.mocked(updateOceanBookingDraft).mockResolvedValue(saved)
+    vi.mocked(releaseOceanBooking).mockResolvedValue({ ...saved, status: 'RELEASED', version: 5 })
+    const { vm, wrapper } = await mountView()
+    vm.selectCustomer('')
+    await vm.submitRelease()
+    expect(updateOceanBookingDraft).toHaveBeenCalledWith('123', expect.objectContaining({ data: expect.objectContaining({ customerId: null, customerName: null }) }))
+    expect(releaseOceanBooking).toHaveBeenCalledWith('123', { expectedVersion: 4 })
+    wrapper.unmount()
+  })
+
+  it('allows documents and release for a saved booking with no single customer', async () => {
+    const empty = booking()
+    empty.customerId = null; empty.customerName = null; empty.oceanBooking.customerId = null; empty.oceanBooking.customerName = null
+    vi.mocked(getOceanBooking).mockResolvedValue(empty)
+    vi.mocked(releaseOceanBooking).mockResolvedValue({ ...empty, status: 'RELEASED', version: 4 })
+    const { vm, wrapper } = await mountView()
+    expect(vm.canManageDocuments).toBe(true)
+    await vm.submitRelease()
+    expect(releaseOceanBooking).toHaveBeenCalledWith('123', { expectedVersion: 3 })
+    expect(updateOceanBookingDraft).not.toHaveBeenCalled()
+    wrapper.unmount()
+  })
+
+  it('preserves a selected single customer when saving', async () => {
+    vi.mocked(updateOceanBookingDraft).mockResolvedValue(booking('DRAFT', 4))
+    const { vm, wrapper } = await mountView()
+    await vm.save()
+    expect(updateOceanBookingDraft).toHaveBeenCalledWith('123', expect.objectContaining({ data: expect.objectContaining({ customerId: '456', customerName: '测试客户' }) }))
+    wrapper.unmount()
+  })
+
+  it('does not call release when automatic draft saving fails', async () => {
+    vi.mocked(updateOceanBookingDraft).mockRejectedValue(new ApiResponseError('保存草稿失败', 'A0409', 409, undefined, 'request-save', 'trace-save'))
+    const { vm } = await mountView()
+    vm.form.data.billOfLadingNo = 'NEW-BL'
+
+    await vm.submitRelease()
+
+    expect(releaseOceanBooking).not.toHaveBeenCalled()
+    expect(vm.form.data.billOfLadingNo).toBe('NEW-BL')
+    expect(vm.actionError).toMatchObject({ code: 'A0409', requestId: 'request-save', traceId: 'trace-save' })
+  })
+
+  it('keeps the saved draft and evidence when release fails after automatic saving', async () => {
+    vi.mocked(updateOceanBookingDraft).mockResolvedValue(booking('DRAFT', 4, 'NEW-BL'))
+    vi.mocked(releaseOceanBooking).mockRejectedValue(new ApiResponseError('放舱失败', 'A0409', 409, undefined, 'request-release', 'trace-release'))
+    const { vm } = await mountView()
+    vm.form.data.billOfLadingNo = 'NEW-BL'
+
+    await vm.submitRelease()
+
+    expect(vm.detail).toMatchObject({ status: 'DRAFT', version: 4, billOfLadingNo: 'NEW-BL' })
+    expect(vm.form.data.billOfLadingNo).toBe('NEW-BL')
+    expect(vm.actionError).toMatchObject({ code: 'A0409', requestId: 'request-release', traceId: 'trace-release' })
+  })
+
+  it('releases an unchanged draft directly and ignores duplicate submissions while busy', async () => {
+    let resolveRelease!: (value: OceanBookingDetail) => void
+    vi.mocked(releaseOceanBooking).mockReturnValue(new Promise((resolve) => { resolveRelease = resolve }))
+    const { vm } = await mountView()
+
+    const first = vm.submitRelease()
+    const duplicate = vm.submitRelease()
+    await flushPromises()
+    expect(vm.actionSaving).toBe(true)
+    expect(updateOceanBookingDraft).not.toHaveBeenCalled()
+    expect(releaseOceanBooking).toHaveBeenCalledTimes(1)
+    expect(releaseOceanBooking).toHaveBeenCalledWith('123', { expectedVersion: 3 })
+    resolveRelease(booking('RELEASED', 4))
+    await Promise.all([first, duplicate])
+    expect(vm.actionSaving).toBe(false)
+  })
+})
diff --git a/src/modules/ocean-bookings/pages/OceanBookingDetailView.test.ts b/src/modules/ocean-bookings/pages/OceanBookingDetailView.test.ts
new file mode 100644
index 00000000..4c4e2eca
--- /dev/null
+++ b/src/modules/ocean-bookings/pages/OceanBookingDetailView.test.ts
@@ -0,0 +1,134 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/ocean-bookings/pages/OceanBookingDetailView.vue'), 'utf8')
+const routesSource = readFileSync(resolve(process.cwd(), 'src/modules/ocean-bookings/routes.ts'), 'utf8')
+
+describe('OceanBookingDetailView draft and release contract', () => {
+  it('recognizes create and DRAFT detail routes as editable', () => {
+    expect(source).toContain("route.name === 'ocean-booking-create' || id.value === 'new'")
+    expect(source).toContain("const editable = computed(() => isNew.value || detail.value?.status === 'DRAFT')")
+    expect(source).toContain("platform:firstleg:ocean-booking:edit")
+    expect(routesSource.indexOf("path: 'ocean-bookings/new'")).toBeLessThan(routesSource.indexOf("path: 'ocean-bookings/:bookingId'"))
+  })
+
+  it('uses only DRAFT and RELEASED actions and removes voyage-change/cancel paths', () => {
+    expect(source).toContain("detail.value?.status === 'DRAFT'")
+    expect(source).toContain('删除草稿')
+    expect(source).toContain('放舱')
+    expect(source).not.toContain('申请改船')
+    expect(source).not.toContain('取消订舱')
+    expect(source).not.toContain('change-request')
+    expect(source).not.toContain('取消订舱')
+    expect(source).not.toContain('cancelOceanBooking')
+  })
+
+  it('invalidates the cached booking list after deleting a draft', () => {
+    expect(source).toContain("workspace.bumpCacheEpoch('ocean-bookings')")
+    expect(source).toContain("await router.replace('/ocean-bookings')")
+  })
+
+  it('saves incomplete DRAFT data and sends null for blank nullable fields', () => {
+    expect(source).toContain('保存草稿')
+    expect(source).toContain('function draftPayload(): OceanBookingDraftData')
+    expect(source).toContain('channelCode: form.data.channelCode?.trim() || null')
+    expect(source).toContain('warehouseId: form.data.warehouseId?.trim() || null')
+    expect(source).toContain('parties: form.data.parties.filter((party) => party.partyName.trim())')
+    expect(source).toContain('containerRequirements: form.data.containerRequirements.map')
+    expect(source).not.toContain('登记后直接确认')
+  })
+
+  it('renders editable container requirements with fixed specifications', () => {
+    expect(source).toContain('aria-label="柜型需求"')
+    expect(source).toContain('containerRequirements')
+    expect(source).toContain('<th scope="col">数量</th>')
+    expect(source).toContain('v-model="requirement.quantity"')
+    expect(source).toContain('selectContainerRequirementType(requirement')
+    expect(source).toContain('{{ requirement.capacityCbm }} m³')
+    expect(source).toContain('{{ requirement.maxWeightKg }} kg')
+    expect(source).not.toContain('v-model="container.containerNo"')
+    expect(source).not.toContain('新增真实柜')
+  })
+
+  it('performs the complete release gate and presents the irreversible warning', () => {
+    expect(source).toContain('function releaseValidationError()')
+    expect(source).toContain('预计到港时间不能早于预计开船时间')
+    expect(source).toContain('放舱前请填写起运港代码或名称')
+    expect(source).toContain('放舱前请填写目的港代码或名称')
+    expect(source).toContain("[form.data.placeOfDelivery, '交货地点']")
+    expect(source).not.toContain("[form.data.customerId, '客户']")
+    expect(source).toContain("if (!form.data.carrierCode) return '放舱前请重新选择船公司，所选船公司必须配置标准编码'")
+    expect(source).not.toContain('请先保存草稿后再放舱')
+    expect(source).toContain('放舱前请填写${missing[1]}')
+    expect(source).toContain('放舱后资料将同步到关联货柜，不能修改、不能删除；填写错误只能由管理员处理数据库，请确认资料无误。')
+    expect(source).toContain('if (hasUnsavedDraftChanges.value)')
+    expect(source).toContain('const saved = await persistDraft(false)')
+    expect(source).toContain('releaseVersion = saved.version')
+    expect(source).toContain('releaseOceanBooking(id.value, { expectedVersion: releaseVersion })')
+    expect(source.indexOf('const saved = await persistDraft(false)')).toBeLessThan(source.indexOf('releaseOceanBooking(id.value, { expectedVersion: releaseVersion })'))
+    expect(source).toContain('if (!saved) return')
+    expect(source).toContain("{{ form.data.billOfLadingNo || '—' }}")
+    expect(source).not.toContain("{{ detail?.billOfLadingNo || '—' }}")
+    expect(source).toContain('const workflowBusy = computed(() => saving.value || actionSaving.value)')
+    expect(source).toContain(':disabled="workflowBusy" @click="openReleaseDialog"')
+    expect(source).not.toContain('releaseReason')
+    expect(source).toContain('放舱前请上传有效的订舱确认文件或提单文件')
+    expect(source).toContain('OceanBookingDocumentsPanel')
+    expect(source).toContain('@updated="updateDocuments"')
+  })
+
+  it('freezes the selected carrier standard code into the booking draft', () => {
+    expect(source).toContain('form.data.carrierCode = partner?.carrierCode ?? null')
+    expect(source).toContain('carrierCode: value.carrierCode ?? selectedCarrier?.carrierCode ?? null')
+    expect(source).toContain('form.data.shippingCompanyId && !form.data.carrierCode')
+    expect(source).toContain('form.data.carrierCode = selected?.carrierCode ?? null')
+  })
+
+  it('keeps warehouse-scoped channel and server-filtered booking-agent selectors accessible', () => {
+    expect(source).toContain("warehouseType: 'DOMESTIC', status: 'ACTIVE'")
+    expect(source).toContain('listWarehouseLogisticsChannels')
+    expect(source).toContain('placeholder="单客户可选择，多客户可留空"')
+    expect(source).toContain('当前船公司暂无可用订舱代理')
+    expect(source).toContain(':label="supplier.name"')
+    expect(source).toContain('filterable clearable')
+    expect(source).toContain(':disabled="!formWritable || !form.data.warehouseId || channelsLoading || !!channelsError || channelUnavailable"')
+    expect(source).toContain(':disabled="!editable || !form.data.carrierCode || bookingAgentsLoading || !!bookingAgentsError"')
+  })
+
+  it('loads booking agents from the carrier-filtered backend contract and clears an invalid selection', () => {
+    expect(source).toContain('listOceanBookingAgents(carrierCode)')
+    expect(source).toContain('shouldClearBookingAgent(form.data.bookingAgentId, options)')
+    expect(source).toContain('clearBookingAgent()')
+    expect(source).toContain("form.data.carrierCode ? '请选择订舱代理' : '请先选择船公司'")
+    expect(source).toContain('<ApiErrorMeta :details="bookingAgentsError" />')
+    expect(source).not.toContain('listSuppliers(')
+    expect(source).not.toContain('isActiveBookingAgent')
+  })
+
+  it('keeps dense layout, operation feedback and narrow-screen behavior', () => {
+    expect(source).toContain('<OperationErrorToast :details="actionError" />')
+    expect(source).toContain('LoadErrorState')
+    expect(source).toContain('@media(max-width:720px)')
+    expect(source).toContain('@media(max-width:420px)')
+    expect(source).toContain('OceanBookingPrintDialog')
+    expect(source).toContain('打印单据')
+  })
+
+  it('keeps a DRAFT detail read-only when the user lacks write permission', () => {
+    expect(source).toContain('const formWritable = computed(() => canSave.value)')
+    expect(source).toContain(':disabled="!formWritable" class="booking-groups density-form"')
+    expect(source).toContain('.booking-groups{display:grid;grid-template-columns:minmax(0,1.35fr) minmax(0,1fr);gap:var(--admin-space-5)}')
+    expect(source).toContain('.booking-group:last-child{grid-column:1/-1}')
+    expect(source).toContain('.container-table-wrap{max-width:100%;overflow-x:auto')
+    expect(source).toContain('v-if="formWritable" class="container-actions"')
+    expect(source).toContain(':disabled="!formWritable"')
+  })
+
+  it('carries the existing read-only CarrierScheduleQuery on the booking detail page', () => {
+    expect(source).toContain('CarrierScheduleQueryPanel')
+    expect(source).toContain("from '@/modules/port-schedules'")
+    expect(source).toContain(':ocean-booking-id="detail.id"')
+    expect(source).not.toContain('createCarrierScheduleQuery')
+  })
+})
diff --git a/src/modules/ocean-bookings/pages/OceanBookingDetailView.vue b/src/modules/ocean-bookings/pages/OceanBookingDetailView.vue
new file mode 100644
index 00000000..343c3c07
--- /dev/null
+++ b/src/modules/ocean-bookings/pages/OceanBookingDetailView.vue
@@ -0,0 +1,497 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, reactive, ref } from 'vue'
+import { ElMessage, ElMessageBox, type FormInstance, type FormRules } from 'element-plus'
+import { useRoute, useRouter } from 'vue-router'
+import { ArrowLeft, Printer, Save, Trash2 } from '@lucide/vue'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useWorkspaceTabsStore } from '@/core/workspace-tabs/workspaceTabs'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import OperationErrorToast from '@/shared/components/OperationErrorToast.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import DetailPageLayout from '@/shared/components/DetailPageLayout.vue'
+import PageToolbar from '@/shared/components/PageToolbar.vue'
+import { CONTAINER_SPECIFICATIONS } from '@/shared/domain/containerSpecifications'
+import { listPlatformTenants, type PlatformTenantResource } from '@/modules/iam'
+import { listPlatformPartners, type PlatformPartnerResource } from '@/modules/master-data'
+import { listPlatformWarehouses, type PlatformWarehouseResource } from '@/modules/warehouses'
+import { CarrierScheduleQueryPanel } from '@/modules/port-schedules'
+import { SMART_LOADING_CHANNEL_GROUPS } from '@/modules/container-loading/smartLoadingChannelGroups'
+import {
+  createOceanBooking,
+  deleteOceanBookingDraft,
+  getOceanBooking,
+  listOceanBookingAgents,
+  releaseOceanBooking,
+  listWarehouseLogisticsChannels,
+  updateOceanBookingDraft,
+  type OceanLogisticsChannel,
+} from '../api/platformOceanBookings'
+import type {
+  OceanBookingDetail,
+  OceanBookingAgentOption,
+  OceanBookingCarrierCode,
+  OceanBookingDraftData,
+  OceanBookingDocument,
+  OceanBookingParty,
+  OceanBookingSaveRequest,
+  OceanBookingStatus,
+} from '../types'
+import { oceanBookingStatusLabel } from '../status'
+import { containerRequirementError, createBlankContainerRequirement, selectContainerRequirementType } from '../containerRequirements'
+import { shouldClearBookingAgent } from '../bookingAgents'
+import OceanBookingPrintDialog from '../components/OceanBookingPrintDialog.vue'
+import OceanBookingDocumentsPanel from '../components/OceanBookingDocumentsPanel.vue'
+
+const partyTypes = [
+  { value: 'SHIPPER', label: '发货人' },
+  { value: 'CONSIGNEE', label: '收货人' },
+  { value: 'NOTIFY_PARTY', label: '通知人' },
+] as const
+const containerTypeOptions = CONTAINER_SPECIFICATIONS
+const containerKindOptions = [
+  { value: 'FCL', label: '整箱 FCL' },
+  { value: 'LCL', label: '拼箱 LCL' },
+]
+const route = useRoute()
+const router = useRouter()
+const access = useAccessPreviewStore()
+const workspace = useWorkspaceTabsStore()
+const id = computed(() => String(route.params.bookingId || ''))
+const isNew = computed(() => route.name === 'ocean-booking-create' || id.value === 'new')
+const detail = ref<OceanBookingDetail | null>(null)
+const loading = ref(false)
+const saving = ref(false)
+const actionSaving = ref(false)
+const error = ref<ReturnType<typeof getApiErrorDetails> | null>(null)
+const actionError = ref<ReturnType<typeof getApiErrorDetails> | null>(null)
+const formRef = ref<FormInstance>()
+const customers = ref<PlatformTenantResource[]>([])
+const partners = ref<PlatformPartnerResource[]>([])
+const bookingAgents = ref<OceanBookingAgentOption[]>([])
+const bookingAgentsLoading = ref(false)
+const bookingAgentsError = ref<ApiErrorDetails | null>(null)
+const warehouses = ref<PlatformWarehouseResource[]>([])
+const optionsLoading = ref(false)
+const optionsError = ref('')
+const channels = ref<OceanLogisticsChannel[]>([])
+const channelsLoading = ref(false)
+const channelsError = ref('')
+const selectedChannelName = ref('')
+let channelRequestSerial = 0
+let bookingAgentRequestSerial = 0
+const selectableCustomers = computed(() => customers.value.filter((customer) => (
+  customer.status === 'ACTIVE' || String(customer.id) === String(form.data.customerId)
+)))
+const shippingCompanies = computed(() => partners.value.filter((partner) => partner.types.includes('CARRIER')))
+const channelGroups = computed(() => {
+  const activeCodes = new Set(channels.value.map((channel) => channel.channelCode))
+  return SMART_LOADING_CHANNEL_GROUPS.filter((group) => group.channelCodes.some((code) => activeCodes.has(code)))
+})
+const channelUnavailable = computed(() => Boolean(form.data.warehouseId) && !channelsLoading.value && !channelsError.value && channelGroups.value.length === 0)
+
+function blankParties(): OceanBookingParty[] {
+  return partyTypes.map(({ value }) => ({ partyType: value, partyName: '', contactName: '', contactPhone: '', address: '' }))
+}
+function blankData(): OceanBookingDraftData {
+  return {
+    customerId: null, customerName: null, channelCode: '', warehouseId: '', parties: blankParties(),
+    billOfLadingNo: '', vesselName: '', voyageNo: '', estimatedSailingAt: null, estimatedArrivalAt: null,
+    shippingCompanyId: null, shippingCompanyName: null, carrierCode: null,
+    containerRequirements: [createBlankContainerRequirement()],
+  }
+}
+const form = reactive<OceanBookingSaveRequest>({ expectedVersion: 0, data: blankData() })
+const savedDraftSignature = ref('')
+const rules: FormRules = {}
+const editable = computed(() => isNew.value || detail.value?.status === 'DRAFT')
+const canSave = computed(() => editable.value && access.can(isNew.value ? 'platform:firstleg:ocean-booking:create' : 'platform:firstleg:ocean-booking:edit'))
+const formWritable = computed(() => canSave.value)
+const canDelete = computed(() => detail.value?.status === 'DRAFT' && access.can('platform:firstleg:ocean-booking:delete'))
+const canRelease = computed(() => detail.value?.status === 'DRAFT' && access.can('platform:firstleg:ocean-booking:release'))
+const canPrint = computed(() => !!detail.value && access.can('platform:firstleg:ocean-booking:list'))
+const canManageDocuments = computed(() => detail.value?.status === 'DRAFT' && access.can('platform:firstleg:ocean-booking:edit'))
+const documentManageReason = computed(() => !access.can('platform:firstleg:ocean-booking:edit') ? '暂无订舱资料维护权限' : '')
+const workflowBusy = computed(() => saving.value || actionSaving.value)
+const releaseDialogOpen = ref(false)
+const printOpen = ref(false)
+
+function statusLabel(status: OceanBookingStatus | string | null | undefined) {
+  return oceanBookingStatusLabel(status)
+}
+async function loadOptions() {
+  optionsLoading.value = true
+  optionsError.value = ''
+  try {
+    const [customerResult, partnerResult, warehouseResult] = await Promise.all([
+      listPlatformTenants({ page: 1, size: 200, status: 'ACTIVE' }),
+      listPlatformPartners({ page: 1, size: 200, status: 'ACTIVE' }),
+      listPlatformWarehouses({ page: 1, size: 200, warehouseType: 'DOMESTIC', status: 'ACTIVE' }),
+    ])
+    customers.value = customerResult.records.filter((customer) => customer.status === 'ACTIVE')
+    partners.value = partnerResult.records
+    if (form.data.shippingCompanyId && !form.data.carrierCode) {
+      const selected = partners.value.find((partner) => String(partner.id) === String(form.data.shippingCompanyId))
+      form.data.carrierCode = selected?.carrierCode ?? null
+    }
+    warehouses.value = warehouseResult.records.filter((warehouse) => warehouse.status === 'ACTIVE' && warehouse.warehouseType === 'DOMESTIC')
+    if (form.data.carrierCode) void loadBookingAgents(form.data.carrierCode)
+  } catch (cause) {
+    optionsError.value = getApiErrorDetails(cause, '客户、船公司或仓库选项加载失败').message
+  } finally {
+    optionsLoading.value = false
+  }
+}
+function selectCustomer(value: unknown) {
+  const customerId = value == null || value === '' ? null : String(value)
+  form.data.customerId = customerId
+  const customer = customerId == null ? null : customers.value.find((item) => String(item.id) === customerId)
+  form.data.customerName = customer?.tenantName || null
+}
+function draftPayload(): OceanBookingDraftData {
+  const customerId = form.data.customerId || null
+  return {
+    ...form.data,
+    customerId,
+    customerName: customerId ? form.data.customerName : null,
+    channelCode: form.data.channelCode?.trim() || null,
+    warehouseId: form.data.warehouseId?.trim() || null,
+    billOfLadingNo: form.data.billOfLadingNo.trim(),
+    vesselName: form.data.vesselName.trim(),
+    voyageNo: form.data.voyageNo.trim(),
+    parties: form.data.parties.filter((party) => party.partyName.trim()).map((party) => ({ ...party, partyName: party.partyName.trim() })),
+    containerRequirements: form.data.containerRequirements.map(({ containerType, containerKind, quantity, capacityCbm, maxWeightKg }) => ({ containerType, containerKind, quantity: Number(quantity), capacityCbm, maxWeightKg })),
+  }
+}
+function draftSignature() { return JSON.stringify(draftPayload()) }
+const hasUnsavedDraftChanges = computed(() => Boolean(detail.value?.status === 'DRAFT' && savedDraftSignature.value && draftSignature() !== savedDraftSignature.value))
+function selectWarehouse(value: unknown) {
+  const warehouseId = value == null || value === '' ? null : String(value)
+  form.data.warehouseId = warehouseId
+  form.data.channelCode = ''
+  selectedChannelName.value = ''
+  channels.value = []
+  channelsError.value = ''
+  if (warehouseId) void loadChannels(warehouseId)
+}
+async function loadChannels(warehouseId: string) {
+  const serial = ++channelRequestSerial
+  channelsLoading.value = true
+  channelsError.value = ''
+  try {
+    const result = await listWarehouseLogisticsChannels(warehouseId)
+    if (serial === channelRequestSerial && warehouseId === form.data.warehouseId) channels.value = result
+  } catch (cause) {
+    if (serial === channelRequestSerial) channelsError.value = getApiErrorDetails(cause, '物流渠道加载失败').message
+  } finally {
+    if (serial === channelRequestSerial) channelsLoading.value = false
+  }
+}
+function selectChannel(channelCode: string) {
+  const channel = SMART_LOADING_CHANNEL_GROUPS.find((item) => item.code === channelCode)
+  form.data.channelCode = channelCode
+  selectedChannelName.value = channel?.name || ''
+}
+function clearBookingAgent() {
+  form.data.bookingAgentId = null
+  form.data.bookingAgentName = null
+}
+async function loadBookingAgents(carrierCode: OceanBookingCarrierCode) {
+  const serial = ++bookingAgentRequestSerial
+  bookingAgentsLoading.value = true
+  bookingAgentsError.value = null
+  try {
+    const options = await listOceanBookingAgents(carrierCode)
+    if (serial !== bookingAgentRequestSerial || carrierCode !== form.data.carrierCode) return
+    bookingAgents.value = options
+    if (formWritable.value && shouldClearBookingAgent(form.data.bookingAgentId, options)) clearBookingAgent()
+  } catch (cause) {
+    if (serial !== bookingAgentRequestSerial) return
+    bookingAgents.value = []
+    bookingAgentsError.value = getApiErrorDetails(cause, '订舱代理候选加载失败')
+  } finally {
+    if (serial === bookingAgentRequestSerial) bookingAgentsLoading.value = false
+  }
+}
+function selectShippingCompany(partnerId: string) {
+  const partner = partners.value.find((item) => String(item.id) === partnerId)
+  form.data.shippingCompanyId = partnerId || null
+  form.data.shippingCompanyName = partner?.partnerName || null
+  form.data.carrierCode = partner?.carrierCode ?? null
+  bookingAgents.value = []
+  bookingAgentsError.value = null
+  bookingAgentRequestSerial += 1
+  if (form.data.carrierCode) void loadBookingAgents(form.data.carrierCode)
+  else clearBookingAgent()
+}
+function selectBookingAgent(supplierId: string) {
+  const supplier = bookingAgents.value.find((item) => item.supplierId === supplierId)
+  form.data.bookingAgentId = supplier?.supplierId ?? null
+  form.data.bookingAgentName = supplier?.name ?? null
+}
+function applyDetail(value: OceanBookingDetail) {
+  detail.value = value
+  form.expectedVersion = value.version
+  const selectedCarrier = partners.value.find((partner) => String(partner.id) === String(value.shippingCompanyId || ''))
+  form.data = {
+    customerId: value.customerId ?? null, customerName: value.customerName ?? null, channelCode: value.channelCode || '', warehouseId: value.warehouseId || '',
+    billOfLadingNo: value.billOfLadingNo || '', vesselName: value.vesselName || '', voyageNo: value.voyageNo || '',
+    estimatedSailingAt: value.estimatedSailingAt || null, estimatedArrivalAt: value.estimatedArrivalAt || null,
+    shippingCompanyId: value.shippingCompanyId, shippingCompanyName: value.shippingCompanyName,
+    carrierCode: value.carrierCode ?? selectedCarrier?.carrierCode ?? null,
+    bookingAgentId: value.bookingAgentId, bookingAgentName: value.bookingAgentName,
+    departurePortCode: value.departurePortCode, departurePortName: value.departurePortName,
+    destinationPortCode: value.destinationPortCode, destinationPortName: value.destinationPortName,
+    placeOfDelivery: value.placeOfDelivery,
+    remark: value.remark,
+    parties: value.parties.length ? value.parties.map(({ partyType, partyName, contactName, contactPhone, address }) => ({ partyType, partyName, contactName, contactPhone, address })) : blankParties(),
+    containerRequirements: value.containerRequirements.length ? value.containerRequirements.map(({ requirementId, containerType, containerKind, quantity, remainingQuantity, capacityCbm, maxWeightKg }) => ({ requirementId, containerType, containerKind, quantity, remainingQuantity, capacityCbm, maxWeightKg })) : [createBlankContainerRequirement()],
+  }
+  selectedChannelName.value = value.channelName || ''
+  savedDraftSignature.value = draftSignature()
+  channels.value = []
+  if (form.data.warehouseId) void loadChannels(form.data.warehouseId)
+  if (form.data.carrierCode) void loadBookingAgents(form.data.carrierCode)
+}
+async function load() {
+  if (!id.value || isNew.value) return
+  loading.value = true
+  error.value = null
+  try { applyDetail(await getOceanBooking(id.value)) }
+  catch (cause) { error.value = getApiErrorDetails(cause) }
+  finally { loading.value = false }
+}
+async function validateDraftForm() {
+  const valid = await formRef.value?.validate().catch(() => false)
+  if (valid === false) { actionError.value = { message: '请检查表单中的必填项和格式' }; return false }
+  const requirementMessage = containerRequirementError(form.data.containerRequirements)
+  if (requirementMessage) { actionError.value = { message: requirementMessage }; return false }
+  return true
+}
+async function persistDraft(showSuccess: boolean) {
+  if (!canSave.value || !(await validateDraftForm())) return null
+  actionError.value = null
+  try {
+    const payload = draftPayload()
+    const saved = isNew.value
+      ? await createOceanBooking({ expectedVersion: 0, data: payload })
+      : await updateOceanBookingDraft(id.value, { expectedVersion: detail.value?.version || 0, data: payload })
+    if (showSuccess) ElMessage.success(isNew.value ? `订舱创建成功：${saved.bookingNo || saved.id}` : '订舱草稿已保存')
+    if (isNew.value) {
+      workspace.removeByIds(['ocean-booking-create'])
+      await router.replace('/ocean-bookings')
+      return saved
+    }
+    applyDetail(saved)
+    return saved
+  } catch (cause) { actionError.value = getApiErrorDetails(cause); return null }
+}
+async function save() {
+  if (!canSave.value || workflowBusy.value) return
+  saving.value = true
+  try { await persistDraft(true) }
+  finally { saving.value = false }
+}
+async function openReleaseDialog() {
+  if (!canRelease.value || workflowBusy.value || !(await validateDraftForm())) return
+  const validationError = releaseValidationError()
+  if (validationError) { actionError.value = { message: validationError }; return }
+  releaseDialogOpen.value = true
+}
+function releaseValidationError() {
+  if (!form.data.carrierCode) return '放舱前请重新选择船公司，所选船公司必须配置标准编码'
+  if (!form.data.departurePortCode?.trim() && !form.data.departurePortName?.trim()) return '放舱前请填写起运港代码或名称'
+  if (!form.data.destinationPortCode?.trim() && !form.data.destinationPortName?.trim()) return '放舱前请填写目的港代码或名称'
+  const requiredFields: Array<[unknown, string]> = [
+    [form.data.warehouseId, '装柜仓库'], [form.data.channelCode, '物流渠道'],
+    [form.data.billOfLadingNo, '提单号'], [form.data.vesselName, '船名'], [form.data.voyageNo, '航次'],
+    [form.data.estimatedSailingAt, '预计开船时间'], [form.data.estimatedArrivalAt, '预计到港时间'],
+    [form.data.placeOfDelivery, '交货地点'],
+    [form.data.shippingCompanyId, '船公司'], [form.data.bookingAgentId, '订舱代理'],
+  ]
+  const missing = requiredFields.find(([value]) => !String(value || '').trim())
+  if (missing) return `放舱前请填写${missing[1]}`
+  if (form.data.estimatedArrivalAt! < form.data.estimatedSailingAt!) return '预计到港时间不能早于预计开船时间'
+  if (form.data.parties.some((party) => !party.partyName.trim())) return '放舱前请填写发货人、收货人和通知人名称'
+  if (!detail.value?.documents.some((document) => document.valid && ['BOOKING_CONFIRMATION', 'BILL_OF_LADING'].includes(document.documentType))) return '放舱前请上传有效的订舱确认文件或提单文件'
+  return containerRequirementError(form.data.containerRequirements)
+}
+function updateDocuments(documents: OceanBookingDocument[], bookingVersion: number) {
+  if (!detail.value) return
+  detail.value.documents = documents
+  detail.value.version = bookingVersion
+  detail.value.oceanBooking.version = bookingVersion
+  form.expectedVersion = bookingVersion
+}
+async function submitRelease() {
+  if (!detail.value || workflowBusy.value) return
+  actionSaving.value = true
+  actionError.value = null
+  try {
+    if (!(await validateDraftForm())) { releaseDialogOpen.value = false; return }
+    const validationError = releaseValidationError()
+    if (validationError) { actionError.value = { message: validationError }; releaseDialogOpen.value = false; return }
+    let releaseVersion = detail.value.version
+    if (hasUnsavedDraftChanges.value) {
+      const saved = await persistDraft(false)
+      if (!saved) return
+      releaseVersion = saved.version
+    }
+    applyDetail(await releaseOceanBooking(id.value, { expectedVersion: releaseVersion }))
+    releaseDialogOpen.value = false
+    ElMessage.success('确认放舱成功')
+  } catch (cause) { actionError.value = getApiErrorDetails(cause) }
+  finally { actionSaving.value = false }
+}
+async function removeDraft() {
+  if (!detail.value || !canDelete.value) return
+  actionError.value = null
+  try {
+    await ElMessageBox.confirm('确认删除该订舱草稿？删除后无法恢复。', '删除草稿', { customClass: 'admin-density-confirm', confirmButtonText: '确认删除', cancelButtonText: '取消', type: 'warning' })
+    actionSaving.value = true
+    await deleteOceanBookingDraft(id.value, detail.value.version)
+    ElMessage.success('订舱草稿已删除')
+    workspace.bumpCacheEpoch('ocean-bookings')
+    await router.replace('/ocean-bookings')
+  } catch (cause) {
+    if (cause !== 'cancel' && !(cause instanceof Error && cause.message === 'cancel')) actionError.value = getApiErrorDetails(cause)
+  } finally { actionSaving.value = false }
+}
+function addRequirement() {
+  if (form.data.containerRequirements.length < 20) form.data.containerRequirements.push(createBlankContainerRequirement())
+}
+function removeRequirement(index: number) { if (form.data.containerRequirements.length > 1) form.data.containerRequirements.splice(index, 1) }
+
+onMounted(() => { void load(); void loadOptions() })
+</script>
+
+<template>
+  <AdminPage as="div" class="booking-detail admin-density">
+    <OperationErrorToast :details="actionError" />
+    <DetailPageLayout aria-label="订舱详情">
+      <template #header>
+        <div class="detail-heading">
+          <el-button link class="density-back" @click="router.push('/ocean-bookings')"><ArrowLeft :size="16" />返回列表</el-button>
+          <PageToolbar class="booking-page-toolbar" as="section" :title="detail?.bookingNo || '订舱草稿'" :description="detail ? `${detail.customerName || '未关联客户'} · ${detail.pol || '—'} → ${detail.pod || '—'}` : '先保存订舱草稿，资料完整后再确认放舱'">
+            <template v-if="detail" #actions><div class="heading-status"><StatusBadge :status="statusLabel(detail.status)" /></div></template>
+          </PageToolbar>
+        </div>
+      </template>
+
+      <LoadErrorState v-if="error" title="订舱详情加载失败" :message="error.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="error" /></template></LoadErrorState>
+      <template v-else>
+      <section class="surface-panel">
+        <div class="section-title">
+          <div><h2>订舱信息</h2><p v-if="detail?.status === 'DRAFT'">草稿可反复保存；放舱后资料同步至关联货柜并锁定。</p><p v-else-if="detail">已放舱资料只读。</p></div>
+          <div class="actions">
+            <el-tooltip :content="canPrint ? '按当前已保存资料打印出口货物托运单或提单确认件' : '暂无订舱单据打印权限'" placement="top"><span><el-button v-if="detail" plain :disabled="!canPrint || workflowBusy" @click="printOpen = true"><Printer :size="16" />打印单据</el-button></span></el-tooltip>
+            <el-button v-if="canDelete" type="danger" plain :loading="actionSaving" :disabled="workflowBusy" @click="removeDraft"><Trash2 :size="16" />删除草稿</el-button>
+            <el-button v-if="canRelease" type="primary" plain :loading="actionSaving" :disabled="workflowBusy" @click="openReleaseDialog">放舱</el-button>
+            <el-button v-if="canSave" type="primary" :loading="saving" :disabled="workflowBusy" @click="save"><Save :size="16" />保存草稿</el-button>
+          </div>
+        </div>
+        <el-alert v-if="optionsError" type="warning" :closable="false" show-icon :title="optionsError"><el-button link type="warning" :loading="optionsLoading" @click="loadOptions">重新加载选项</el-button></el-alert>
+        <el-form ref="formRef" :model="form.data" :rules="rules" label-position="top" :disabled="!formWritable" class="booking-groups density-form">
+          <section class="booking-group" aria-label="基本信息">
+            <h3>基本信息</h3><div class="booking-group__body booking-group__body--fields">
+            <el-form-item label="订舱号"><el-input :model-value="detail?.bookingNo || '保存后生成'" disabled /></el-form-item>
+            <el-form-item label="客户（选填）"><el-select :model-value="form.data.customerId" filterable clearable placeholder="单客户可选择，多客户可留空" no-data-text="暂无可选客户" :loading="optionsLoading" style="width:100%" @update:model-value="selectCustomer"><el-option v-if="form.data.customerId && !selectableCustomers.some((customer) => String(customer.id) === String(form.data.customerId))" :label="form.data.customerName || '客户名称缺失'" :value="String(form.data.customerId)" /><el-option v-for="customer in selectableCustomers" :key="String(customer.id)" :label="customer.tenantName" :value="String(customer.id)" /></el-select></el-form-item>
+            <el-form-item label="状态"><el-input :model-value="detail ? statusLabel(detail.status) : '保存后为草稿'" disabled /></el-form-item>
+            <el-form-item label="装柜仓库" prop="warehouseId"><el-select :model-value="form.data.warehouseId" filterable placeholder="请选择装柜仓库" :loading="optionsLoading" style="width:100%" @update:model-value="selectWarehouse"><el-option v-for="warehouse in warehouses" :key="String(warehouse.id)" :label="warehouse.warehouseName" :value="String(warehouse.id)" /></el-select></el-form-item>
+            <el-form-item label="物流渠道" prop="channelCode"><el-select :model-value="form.data.channelCode" filterable :disabled="!formWritable || !form.data.warehouseId || channelsLoading || !!channelsError || channelUnavailable" :loading="channelsLoading" :placeholder="form.data.warehouseId ? '请选择物流渠道' : '请先选择装柜仓库'" no-data-text="该仓库暂无有效物流渠道" style="width:100%" @update:model-value="selectChannel(String($event || ''))"><el-option v-if="form.data.channelCode && !channelGroups.some((channel) => channel.code === form.data.channelCode)" :label="selectedChannelName || form.data.channelCode" :value="form.data.channelCode" /><el-option v-for="channel in channelGroups" :key="channel.code" :label="channel.name" :value="channel.code" /></el-select><div v-if="channelsError" class="field-error"><span>{{ channelsError }}</span><el-button link type="primary" :loading="channelsLoading" @click="form.data.warehouseId && loadChannels(form.data.warehouseId)">重新加载</el-button></div><div v-else-if="channelUnavailable" class="field-hint">该仓库暂无有效物流渠道，请更换仓库或联系管理员。</div></el-form-item>
+            <el-form-item label="提单号" prop="billOfLadingNo"><el-input v-model="form.data.billOfLadingNo" maxlength="128" placeholder="请输入提单号" /></el-form-item>
+            <el-form-item label="船公司"><el-select :model-value="form.data.shippingCompanyId" filterable clearable placeholder="请选择船公司" :loading="optionsLoading" style="width:100%" @update:model-value="selectShippingCompany(String($event || ''))"><el-option v-if="form.data.shippingCompanyId && !shippingCompanies.some((partner) => String(partner.id) === String(form.data.shippingCompanyId))" :label="form.data.shippingCompanyName || '船公司名称缺失'" :value="String(form.data.shippingCompanyId)" /><el-option v-for="partner in shippingCompanies" :key="String(partner.id)" :label="partner.partnerName" :value="String(partner.id)" /></el-select></el-form-item>
+            <el-form-item label="订舱代理"><el-select :model-value="form.data.bookingAgentId" filterable clearable :disabled="!editable || !form.data.carrierCode || bookingAgentsLoading || !!bookingAgentsError" :placeholder="form.data.carrierCode ? '请选择订舱代理' : '请先选择船公司'" :loading="bookingAgentsLoading" no-data-text="当前船公司暂无可用订舱代理" style="width:100%" @update:model-value="selectBookingAgent(String($event || ''))"><el-option v-if="!editable && form.data.bookingAgentId && !bookingAgents.some((supplier) => supplier.supplierId === String(form.data.bookingAgentId))" :label="form.data.bookingAgentName || '订舱代理名称缺失'" :value="String(form.data.bookingAgentId)" /><el-option v-for="supplier in bookingAgents" :key="supplier.supplierId" :label="supplier.name" :value="supplier.supplierId" /></el-select><div v-if="bookingAgentsError" class="field-error"><ApiErrorMeta :details="bookingAgentsError" /><el-button link type="primary" :loading="bookingAgentsLoading" @click="form.data.carrierCode && loadBookingAgents(form.data.carrierCode)">重新加载</el-button></div></el-form-item>
+            </div>
+          </section>
+          <section class="booking-group" aria-label="航线船期">
+            <h3>航线船期</h3><div class="booking-group__body booking-group__body--fields">
+            <el-form-item label="船名" prop="vesselName"><el-input v-model="form.data.vesselName" maxlength="128" placeholder="请输入船名" /></el-form-item>
+            <el-form-item label="航次" prop="voyageNo"><el-input v-model="form.data.voyageNo" maxlength="64" placeholder="请输入航次" /></el-form-item>
+            <el-form-item label="起运港代码"><el-input v-model="form.data.departurePortCode" placeholder="例如：CNNGB" /></el-form-item>
+            <el-form-item label="起运港"><el-input v-model="form.data.departurePortName" placeholder="例如：宁波港" /></el-form-item>
+            <el-form-item label="目的港代码"><el-input v-model="form.data.destinationPortCode" placeholder="例如：USLAX" /></el-form-item>
+            <el-form-item label="目的港"><el-input v-model="form.data.destinationPortName" placeholder="例如：洛杉矶港" /></el-form-item>
+            <el-form-item class="booking-field--wide" label="交货地点"><el-input v-model="form.data.placeOfDelivery" placeholder="请输入最终交货地点" /></el-form-item>
+            <el-form-item label="预计开船" prop="estimatedSailingAt"><el-date-picker v-model="form.data.estimatedSailingAt" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" placeholder="请选择预计开船时间" style="width:100%" /></el-form-item>
+            <el-form-item label="预计到港" prop="estimatedArrivalAt"><el-date-picker v-model="form.data.estimatedArrivalAt" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" placeholder="请选择预计到港时间" style="width:100%" /></el-form-item>
+            </div>
+          </section>
+          <section class="booking-group" aria-label="柜型需求">
+            <h3>柜型需求</h3><div class="booking-group__body">
+            <div class="container-table-wrap" aria-label="柜型需求">
+              <table class="container-table density-table">
+                <thead><tr><th scope="col">操作</th><th scope="col">柜型</th><th scope="col">箱种</th><th scope="col">数量</th><th scope="col">容量</th><th scope="col">限重</th><th v-if="detail?.status === 'RELEASED'" scope="col">剩余可关联</th></tr></thead>
+                <tbody>
+                  <tr v-for="(requirement, index) in form.data.containerRequirements" :key="requirement.requirementId || index">
+                    <td class="container-table__action">
+                      <el-tooltip v-if="formWritable" :content="form.data.containerRequirements.length === 1 ? '至少保留一项柜型需求' : '删除该柜型需求'" placement="top">
+                        <span><el-button data-tone="danger" class="density-action" plain size="small" type="danger" :aria-label="`删除柜型需求 ${index + 1}`" :disabled="form.data.containerRequirements.length === 1" @click="removeRequirement(index)">删除</el-button></span>
+                      </el-tooltip>
+                      <span v-else aria-hidden="true">—</span>
+                    </td>
+                    <td><el-select :model-value="requirement.containerType" :disabled="!formWritable" placeholder="请选择柜型" @update:model-value="selectContainerRequirementType(requirement, String($event || ''))"><el-option v-for="item in containerTypeOptions" :key="item.type" :label="item.type" :value="item.type" /></el-select></td>
+                    <td><el-select v-model="requirement.containerKind" :disabled="!formWritable" placeholder="请选择箱种"><el-option v-for="item in containerKindOptions" :key="item.value" :label="item.label" :value="item.value" /></el-select></td>
+                    <td><el-input-number v-model="requirement.quantity" :disabled="!formWritable" :min="1" :max="99" controls-position="right" placeholder="请输入柜量" /></td>
+                    <td class="container-table__specification"><span>{{ requirement.capacityCbm }} m³</span></td>
+                    <td class="container-table__specification"><span>{{ requirement.maxWeightKg }} kg</span></td>
+                    <td v-if="detail?.status === 'RELEASED'"><span>{{ requirement.remainingQuantity ?? requirement.quantity }}</span></td>
+                  </tr>
+                </tbody>
+              </table>
+            </div>
+            <div v-if="formWritable" class="container-actions"><el-button class="add-container density-action" size="small" :disabled="form.data.containerRequirements.length >= 20" @click="addRequirement">新增柜型需求</el-button><span>{{ form.data.containerRequirements.length }} / 20 项</span></div>
+            <el-form-item label="备注"><el-input v-model="form.data.remark" type="textarea" :rows="3" placeholder="请输入订舱备注（可选）" /></el-form-item>
+            </div>
+          </section>
+        </el-form>
+      </section>
+
+      <section class="surface-panel">
+        <h2>订舱关系方</h2>
+        <div class="party-grid">
+          <div v-for="(party, index) in form.data.parties" :key="party.partyType" class="subsection">
+            <h3><span class="required-mark" aria-hidden="true">*</span>{{ partyTypes[index]?.label || party.partyType }}</h3>
+            <el-input v-model="party.partyName" :disabled="!formWritable" :aria-label="`${partyTypes[index]?.label || party.partyType}单位名称（必填）`" placeholder="单位名称（必填）" />
+            <el-input v-model="party.contactName" :disabled="!formWritable" placeholder="联系人" />
+            <el-input v-model="party.contactPhone" :disabled="!formWritable" placeholder="联系电话" />
+            <el-input v-model="party.address" :disabled="!formWritable" placeholder="地址" />
+          </div>
+        </div>
+      </section>
+
+      <OceanBookingDocumentsPanel v-if="detail" :booking-id="detail.id" :booking-version="detail.version" :booking-status="detail.status" :documents="detail.documents" :can-manage="canManageDocuments" :manage-reason="documentManageReason" @updated="updateDocuments" />
+
+      <div v-if="detail" class="surface-panel"><CarrierScheduleQueryPanel dense :ocean-booking-id="detail.id" /></div>
+
+      <section v-if="detail" class="surface-panel history-panel">
+        <div class="section-title"><div><h2>状态历史</h2><p>当前进度：{{ statusLabel(detail.status) }}</p></div></div>
+        <table class="density-table booking-history-table"><thead><tr><th>时间</th><th>状态变化</th><th>操作人</th><th>备注</th></tr></thead><tbody><tr v-for="event in detail.histories" :key="event.id"><td>{{ event.occurredAt }}</td><td>{{ statusLabel(event.fromStatus) }} → {{ statusLabel(event.toStatus) }}</td><td>{{ event.operatorName || '系统' }}</td><td>{{ event.reason || '—' }}</td></tr><tr v-if="!detail.histories.length"><td colspan="4">暂无状态历史</td></tr></tbody></table>
+      </section>
+      </template>
+    </DetailPageLayout>
+    <OceanBookingPrintDialog v-if="detail" v-model="printOpen" :booking-id="detail.id" :booking-no="detail.bookingNo" :allowed="canPrint" />
+
+    <AppDialog class="admin-density-dialog" v-model="releaseDialogOpen" title="确认放舱" width="min(560px, 94vw)" :confirm-loading="actionSaving" :confirm-disabled="workflowBusy" confirm-text="确认放舱" cancel-text="取消" @confirm="submitRelease">
+      <el-form class="density-form" label-position="top">
+        <el-alert title="放舱后资料将同步到关联货柜，不能修改、不能删除；填写错误只能由管理员处理数据库，请确认资料无误。" type="warning" :closable="false" show-icon />
+        <el-descriptions class="release-summary" :column="2" border>
+          <el-descriptions-item label="提单号">{{ form.data.billOfLadingNo || '—' }}</el-descriptions-item>
+          <el-descriptions-item label="船名">{{ form.data.vesselName || '—' }}</el-descriptions-item>
+          <el-descriptions-item label="航次">{{ form.data.voyageNo || '—' }}</el-descriptions-item>
+          <el-descriptions-item label="预计开船">{{ form.data.estimatedSailingAt || '—' }}</el-descriptions-item>
+          <el-descriptions-item label="预计到港">{{ form.data.estimatedArrivalAt || '—' }}</el-descriptions-item>
+        </el-descriptions>
+      </el-form>
+    </AppDialog>
+  </AdminPage>
+</template>
+
+<style scoped>
+.channel-code{display:block;margin-left:var(--admin-space-3);color:var(--cc-muted);font-size:var(--admin-font-caption)}.field-error,.field-hint{display:flex;align-items:center;justify-content:space-between;gap:var(--admin-space-3);margin-top:5px;color:var(--cc-muted);font-size:var(--admin-font-caption);line-height:20px}.field-error{color:var(--el-color-danger)}
+.booking-detail{min-width:0}.detail-heading{display:flex;min-width:0;gap:var(--admin-space-5);padding:var(--admin-space-3) var(--admin-space-5);background:var(--admin-surface);border:1px solid var(--cc-border);align-items:center}.booking-page-toolbar{min-width:0;flex:1}.section-title p,.history-panel p{margin:5px 0 0;color:var(--cc-muted);font-size:var(--admin-font-body)}.heading-status{display:flex;align-items:center;gap:var(--admin-space-3)}.surface-panel{padding:var(--admin-space-5)}.surface-panel h2{margin:0;font-size:var(--admin-font-section)}.section-title{display:flex;justify-content:space-between;gap:var(--admin-space-5);align-items:flex-start;margin-bottom:var(--admin-space-5)}.actions{display:flex;flex-wrap:wrap;gap:var(--admin-space-3)}.booking-groups{display:grid;grid-template-columns:minmax(0,1.35fr) minmax(0,1fr);gap:var(--admin-space-5)}.booking-group{min-width:0;overflow:hidden;background:var(--admin-surface);border:0}.booking-group:last-child{grid-column:1/-1}.booking-group>h3{margin:0;color:#1f2937;font-size:var(--admin-font-section);padding:var(--admin-space-3) 0;border-bottom:1px solid var(--cc-border)}.booking-group__body{padding:var(--admin-space-3) 0 0}.booking-group__body--fields,.booking-terms{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));column-gap:var(--admin-space-4);row-gap:var(--admin-space-3)}.booking-field--wide{grid-column:1/-1}.booking-terms :deep(.el-select){width:100%}.party-grid{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:var(--admin-space-4);margin-top:var(--admin-space-5)}.subsection{display:grid;gap:var(--admin-space-4);border:0;padding:0}.subsection h3{margin:0;font-size:var(--admin-font-section)}.required-mark{margin-right:var(--admin-space-1);color:var(--el-color-danger)}.container-table-wrap{max-width:100%;overflow-x:auto;margin-bottom:var(--admin-space-4)}.container-table{width:100%;min-width:780px;table-layout:fixed}.container-table th:first-child,.container-table td:first-child{width:80px}.container-table th:nth-child(2),.container-table td:nth-child(2){width:180px}.container-table th:nth-child(3),.container-table td:nth-child(3){width:90px}.container-table th:nth-child(4),.container-table td:nth-child(4){width:110px}.container-table th:nth-child(5),.container-table td:nth-child(5),.container-table th:nth-child(6),.container-table td:nth-child(6){width:100px}.container-table td :deep(.el-select),.container-table td :deep(.el-input){width:100%;min-width:0}.container-table__action{text-align:center!important}.container-table__specification{color:var(--cc-muted);white-space:nowrap}.container-actions{display:flex;align-items:center;gap:var(--admin-space-4);margin-bottom:var(--admin-space-5);color:var(--cc-muted);font-size:var(--admin-font-caption)}.add-container{margin:0}@media(max-width:720px){.booking-groups,.party-grid{grid-template-columns:1fr}.booking-group:last-child{grid-column:auto}.detail-heading{flex-direction:column;padding:var(--admin-space-3) var(--admin-space-5);background:var(--admin-surface);border:1px solid var(--cc-border);align-items:center}.booking-page-toolbar{width:100%}.section-title{flex-direction:column}.actions{width:100%}}@media(max-width:520px){.booking-group__body--fields,.booking-terms{grid-template-columns:1fr}.booking-field--wide{grid-column:auto}}@media(max-width:420px){.surface-panel{padding:12px}.booking-group__body{padding:var(--admin-space-3) 0 0}.actions :deep(.el-button){min-height:44px}}.booking-history-table th:nth-child(1){width:180px}.booking-history-table th:nth-child(2){width:220px}.booking-history-table th:nth-child(3){width:140px}.booking-page-toolbar :deep(h1){font-size:var(--admin-font-title)}
+</style>
diff --git a/src/modules/ocean-bookings/pages/OceanBookingsView.test.ts b/src/modules/ocean-bookings/pages/OceanBookingsView.test.ts
new file mode 100644
index 00000000..789fd507
--- /dev/null
+++ b/src/modules/ocean-bookings/pages/OceanBookingsView.test.ts
@@ -0,0 +1,106 @@
+import ElementPlus from 'element-plus'
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import OceanBookingsView from './OceanBookingsView.vue'
+import { listOceanBookings } from '../api/platformOceanBookings'
+
+const routerPush = vi.hoisted(() => vi.fn())
+vi.mock('vue-router', () => ({ useRouter: () => ({ push: routerPush }) }))
+vi.mock('@/core/access/accessPreview', () => ({ useAccessPreviewStore: () => ({ can: () => true }) }))
+vi.mock('@/modules/iam', () => ({ listPlatformTenants: vi.fn().mockResolvedValue({ records: [] }) }))
+vi.mock('../api/platformOceanBookings', () => ({ listOceanBookings: vi.fn() }))
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/ocean-bookings/pages/OceanBookingsView.vue'), 'utf8')
+
+describe('OceanBookingsView', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.mocked(listOceanBookings).mockResolvedValue({ records: [], page: 1, size: 20, total: 0, pages: 0 })
+  })
+  it('keeps the operation column first and left fixed', () => {
+    expect(source.indexOf("key: 'actions'")).toBeLessThan(source.indexOf("prop: 'bookingNo'"))
+    expect(source).toContain("fixed: 'left'")
+  })
+
+  it('renders loading, empty and error states and keeps draft creation available', () => {
+    expect(source).toContain('LoadErrorState')
+    expect(source).toContain(':loading="loading"')
+    expect(source).toContain('新增订舱')
+    expect(source).toContain("router.push('/ocean-bookings/new')")
+  })
+
+  it('edits DRAFT rows and views RELEASED rows', () => {
+    expect(source).toContain('class="density-action"')
+    expect(source).toContain("row.status === 'DRAFT' ? '编辑' : '查看'")
+    expect(source).not.toContain('MoreHorizontal')
+    expect(source).toContain('打印单据')
+    expect(source).toContain('OceanBookingPrintDialog')
+    expect(source).toContain("access.can('platform:firstleg:ocean-booking:list')")
+  })
+
+  it.each(['DRAFT', 'RELEASED'] as const)('opens printing for %s with incomplete booking data', async (status) => {
+    vi.mocked(listOceanBookings).mockResolvedValueOnce({ records: [{
+      id: '183', bookingNo: 'OB-183', status, containerCount: 1,
+      billOfLadingNo: null, shipperName: null, consigneeName: null,
+    }], page: 1, size: 20, total: 1, pages: 1 } as never)
+    const wrapper = mount(OceanBookingsView, { global: { plugins: [ElementPlus], stubs: { OceanBookingPrintDialog: true } } })
+    await (wrapper.vm as unknown as { load: () => Promise<void> }).load()
+    await flushPromises()
+    const button = wrapper.findAll('button').find((item) => item.text().includes('打印单据'))!
+    expect(button.attributes('disabled')).toBeUndefined()
+    await button.trigger('click')
+    expect(wrapper.findComponent({ name: 'OceanBookingPrintDialog' }).attributes('modelvalue')).toBe('true')
+    wrapper.unmount()
+  })
+
+  it('uses only the frozen DRAFT and RELEASED status options', () => {
+    expect(source).toContain('options: oceanBookingStatusOptions')
+    expect(source).toContain(':status="oceanBookingStatusLabel(row.status)"')
+    expect(source).not.toContain('CONFIRMED')
+    expect(source).not.toContain('CHANGE_PENDING')
+    expect(source).not.toContain('CANCELLED')
+  })
+
+  it('keeps the prototype business field order after actions', () => {
+    const fields = ['bookingNo', 'customerName', 'billOfLadingNo', 'shipperName', 'consigneeName', 'containerCount', 'carrierName', 'bookingAgent', 'vesselName', 'pol', 'pod', 'etd', 'eta', 'status', 'updatedAt']
+    let previous = source.indexOf("key: 'actions'")
+    for (const field of fields) {
+      const current = source.indexOf(`prop: '${field}'`, previous + 1)
+      expect(current, field).toBeGreaterThan(previous)
+      previous = current
+    }
+  })
+
+  it('displays the server containerCount as the booking requirement total without detail N+1', async () => {
+    vi.mocked(listOceanBookings).mockResolvedValueOnce({ records: [{
+      id: '183', bookingNo: 'OB-260825-0183', status: 'RELEASED', containerCount: 1,
+      customerName: '回归客户', vesselName: null, voyageNo: null, etd: null, eta: null, updatedAt: null,
+    }], page: 1, size: 20, total: 1, pages: 1 } as never)
+    const wrapper = mount(OceanBookingsView, { global: { plugins: [ElementPlus] } })
+
+    await (wrapper.vm as unknown as { load: () => Promise<void> }).load()
+    await flushPromises()
+
+    const tableText = wrapper.find('.el-table__body-wrapper').text()
+    expect(tableText).toContain('OB-260825-0183')
+    expect(tableText).toContain('1')
+    expect(source).toContain("label: '订舱柜量'")
+    expect(source).not.toContain('getOceanBooking')
+    wrapper.unmount()
+  })
+
+  it('loads active customers by name and stays usable on narrow screens', () => {
+    expect(source).toContain("listPlatformTenants({ page: 1, size: 200, status: 'ACTIVE' })")
+    expect(source).toContain('label: customer.tenantName')
+    expect(source).not.toContain('customer.tenantCode')
+    expect(source).toContain('@media(max-width:420px)')
+  })
+
+  it('keeps desktop filter widths proportional instead of stretching short status fields', () => {
+    expect(source).toContain("key: 'customerId', type: 'select', label: '客户', placeholder: '全部客户', width: 220")
+    expect(source).toContain("key: 'keyword', type: 'input', label: '关键词', placeholder: '订舱号/提单号/船名/航次', width: 260")
+    expect(source).toContain("key: 'status', type: 'select', label: '状态', width: 160")
+  })
+})
diff --git a/src/modules/ocean-bookings/pages/OceanBookingsView.vue b/src/modules/ocean-bookings/pages/OceanBookingsView.vue
new file mode 100644
index 00000000..ae325f45
--- /dev/null
+++ b/src/modules/ocean-bookings/pages/OceanBookingsView.vue
@@ -0,0 +1,91 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onActivated, onMounted, reactive, ref, watch } from 'vue'
+import { useRouter } from 'vue-router'
+import { Plus } from '@lucide/vue'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import DataTable from '@/shared/components/DataTable.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import { getApiErrorDetails } from '@/shared/api/http'
+import { listPlatformTenants, type PlatformTenantResource } from '@/modules/iam'
+import { listOceanBookings, type OceanBookingResource } from '../api/platformOceanBookings'
+import type { OceanBookingQuery, OceanBookingStatus } from '../types'
+import { oceanBookingStatusLabel, oceanBookingStatusOptions } from '../status'
+import OceanBookingPrintDialog from '../components/OceanBookingPrintDialog.vue'
+
+const router = useRouter()
+const access = useAccessPreviewStore()
+const rows = ref<OceanBookingResource[]>([])
+const loading = ref(false)
+const error = ref<ReturnType<typeof getApiErrorDetails> | null>(null)
+const page = ref(1)
+const pageSize = ref(20)
+const total = ref(0)
+const customers = ref<PlatformTenantResource[]>([])
+const customersLoading = ref(false)
+const query = reactive<QueryModel>({ customerId: '', keyword: '', status: '' })
+const activeCustomers = computed(() => customers.value.filter((customer) => customer.status === 'ACTIVE'))
+const canCreate = computed(() => access.can('platform:firstleg:ocean-booking:create'))
+const canPrint = computed(() => access.can('platform:firstleg:ocean-booking:list'))
+const printOpen = ref(false)
+const printBooking = ref<{ id: string; bookingNo?: string | null } | null>(null)
+const fields = computed<QueryField[]>(() => [
+  { key: 'customerId', type: 'select', label: '客户', placeholder: '全部客户', width: 220, options: activeCustomers.value.map((customer) => ({ label: customer.tenantName, value: String(customer.id) })), props: { filterable: true, loading: customersLoading.value } },
+  { key: 'keyword', type: 'input', label: '关键词', placeholder: '订舱号/提单号/船名/航次', width: 260 },
+  { key: 'status', type: 'select', label: '状态', width: 160, options: oceanBookingStatusOptions },
+])
+const columns = [
+  { key: 'actions', label: '操作', fixed: 'left', width: 196, slotName: 'actions', hideable: false, movable: false },
+  { prop: 'bookingNo', label: '订舱号', minWidth: 150 },
+  { prop: 'customerName', label: '客户', minWidth: 160, formatter: (row: OceanBookingResource) => row.customerName || '—' },
+  { prop: 'billOfLadingNo', label: '提单号', minWidth: 155, formatter: (row: OceanBookingResource) => row.billOfLadingNo || '—' },
+  { prop: 'shipperName', label: '提单发货人', minWidth: 160, formatter: (row: OceanBookingResource) => row.shipperName || '—' },
+  { prop: 'consigneeName', label: '提单收货人', minWidth: 160, formatter: (row: OceanBookingResource) => row.consigneeName || '—' },
+  { prop: 'containerCount', label: '订舱柜量', width: 100, align: 'right' },
+  { prop: 'carrierName', label: '船公司', minWidth: 130 },
+  { prop: 'bookingAgent', label: '订舱代理', minWidth: 140 },
+  { prop: 'vesselName', label: '船名 / 航次', minWidth: 175, slotName: 'vessel' },
+  { prop: 'pol', label: '起运港', minWidth: 125 },
+  { prop: 'pod', label: '目的港', minWidth: 125 },
+  { prop: 'etd', label: '预计开船', minWidth: 155, slotName: 'etd' },
+  { prop: 'eta', label: '预计到港', minWidth: 155, slotName: 'eta' },
+  { prop: 'status', label: '状态', minWidth: 110, slotName: 'status' },
+  { prop: 'updatedAt', label: '更新时间', minWidth: 155, slotName: 'updatedAt' },
+]
+function formatDateTime(value?: string | null) { return value ? value.replace('T', ' ').slice(0, 16) : '—' }
+async function loadCustomers() { customersLoading.value = true; try { const result = await listPlatformTenants({ page: 1, size: 200, status: 'ACTIVE' }); customers.value = result.records.filter((customer) => customer.status === 'ACTIVE') } catch { customers.value = [] } finally { customersLoading.value = false } }
+async function load() { loading.value = true; error.value = null; try { const keyword = String(query.keyword ?? '').trim(); const customerId = String(query.customerId ?? '').trim(); const status = String(query.status ?? '').trim(); const result = await listOceanBookings({ page: page.value, size: pageSize.value, customerId: customerId || undefined, keyword: keyword || undefined, status: (status || undefined) as OceanBookingStatus | undefined } satisfies OceanBookingQuery); rows.value = result.records; total.value = result.total } catch (e) { error.value = getApiErrorDetails(e) } finally { loading.value = false } }
+function open(id: string) { void router.push(`/ocean-bookings/${id}`) }
+function createBooking() { void router.push('/ocean-bookings/new') }
+function openPrint(row: Record<string, unknown>) { printBooking.value = { id: String(row.id), bookingNo: typeof row.bookingNo === 'string' ? row.bookingNo : null }; printOpen.value = true }
+function printHint() { return !canPrint.value ? '暂无订舱单据打印权限' : '按当前已保存资料打印出口货物托运单或提单确认件' }
+function search() { if (page.value === 1) void load(); else page.value = 1 }
+watch([page, pageSize], () => void load()); onMounted(() => void loadCustomers())
+onActivated(() => void load())
+</script>
+<template>
+  <AdminPage as="div" class="ocean-bookings-page admin-density">
+    <ListPageLayout aria-label="订舱列表">
+      <template #toolbar><QueryToolbar v-model="query" class="surface-panel" ariaLabel="订舱筛选" :fields="fields" @search="search" /></template>
+      <template v-if="error" #state><LoadErrorState title="订舱列表加载失败" :message="error.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="error" /></template></LoadErrorState></template>
+      <section v-if="!error" class="surface-panel table-panel">
+      <DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :loading="loading" :total="total" stripe preference-key="ocean-bookings" aria-label="订舱列表" row-key="id" empty-text="暂无符合筛选条件的订舱">
+        <template #toolbar-actions><el-button v-if="canCreate" type="primary" @click="createBooking"><Plus :size="16" />新增订舱</el-button></template>
+        <template #actions="{ row }"><div class="table-actions density-actions"><el-button data-tone="primary" class="density-action" size="small" type="primary" plain @click="open(row.id)">{{ row.status === 'DRAFT' ? '编辑' : '查看' }}</el-button><el-tooltip :content="printHint()" placement="top"><span><el-button class="density-action" size="small" plain :disabled="!canPrint" @click="openPrint(row)">打印单据</el-button></span></el-tooltip></div></template>
+        <template #vessel="{ row }">{{ row.vesselName || '—' }}<span v-if="row.voyageNo"> / {{ row.voyageNo }}</span></template>
+        <template #etd="{ row }">{{ formatDateTime(row.etd) }}</template>
+        <template #eta="{ row }">{{ formatDateTime(row.eta) }}</template>
+        <template #status="{ row }"><StatusBadge :status="oceanBookingStatusLabel(row.status)" /></template>
+        <template #updatedAt="{ row }">{{ formatDateTime(row.updatedAt) }}</template>
+      </DataTable>
+      </section>
+    </ListPageLayout>
+    <OceanBookingPrintDialog v-if="printBooking" v-model="printOpen" :booking-id="printBooking.id" :booking-no="printBooking.bookingNo" :allowed="canPrint" />
+  </AdminPage>
+</template>
+<style scoped>.ocean-bookings-page{min-width:0}.table-actions{flex-wrap:wrap}.table-actions :deep(.el-button){margin-left:0}@media(max-width:420px){.table-actions{flex-direction:column}.table-actions :deep(.el-button){width:100%;min-height:40px}}</style>
diff --git a/src/modules/ocean-bookings/routes.ts b/src/modules/ocean-bookings/routes.ts
new file mode 100644
index 00000000..10dc739d
--- /dev/null
+++ b/src/modules/ocean-bookings/routes.ts
@@ -0,0 +1,2 @@
+import type { RouteRecordRaw } from 'vue-router'
+export const oceanBookingRoutes = [{ path: 'ocean-bookings', name: 'ocean-bookings', component: () => import('./pages/OceanBookingsView.vue'), meta: { title: '海运订舱', description: '维护海运订舱申请、船期与放舱状态', permission: 'platform:firstleg:ocean-booking:list' } }, { path: 'ocean-bookings/new', name: 'ocean-booking-create', component: () => import('./pages/OceanBookingDetailView.vue'), meta: { title: '新增订舱', description: '登记线下已确认的真实海运订舱', permission: 'platform:firstleg:ocean-booking:create' } }, { path: 'ocean-bookings/:bookingId', name: 'ocean-booking-detail', component: () => import('./pages/OceanBookingDetailView.vue'), meta: { title: '订舱详情', description: '查看和维护订舱详情', permission: 'platform:firstleg:ocean-booking:list' } }] satisfies RouteRecordRaw[]
diff --git a/src/modules/ocean-bookings/status.test.ts b/src/modules/ocean-bookings/status.test.ts
new file mode 100644
index 00000000..c108d5cd
--- /dev/null
+++ b/src/modules/ocean-bookings/status.test.ts
@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest'
+import { oceanBookingStatusLabel, oceanBookingStatusOptions } from './status'
+
+describe('ocean booking status labels', () => {
+  it('translates every backend status for selectors and badges', () => {
+    expect(oceanBookingStatusOptions).toEqual([
+      { value: 'DRAFT', label: '草稿' },
+      { value: 'RELEASED', label: '已放舱' },
+    ])
+  })
+
+  it('does not leak unknown backend enum values to users', () => {
+    expect(oceanBookingStatusLabel('NEW_BACKEND_STATUS')).toBe('未知状态')
+    expect(oceanBookingStatusLabel(null)).toBe('未设置')
+  })
+})
diff --git a/src/modules/ocean-bookings/status.ts b/src/modules/ocean-bookings/status.ts
new file mode 100644
index 00000000..a0919e42
--- /dev/null
+++ b/src/modules/ocean-bookings/status.ts
@@ -0,0 +1,16 @@
+import type { OceanBookingStatus } from './types'
+
+export const oceanBookingStatusLabels: Record<OceanBookingStatus, string> = {
+  DRAFT: '草稿',
+  RELEASED: '已放舱',
+}
+
+export const oceanBookingStatusOptions = Object.entries(oceanBookingStatusLabels).map(([value, label]) => ({
+  value: value as OceanBookingStatus,
+  label,
+}))
+
+export function oceanBookingStatusLabel(status: string | null | undefined, emptyLabel = '未设置') {
+  if (!status) return emptyLabel
+  return oceanBookingStatusLabels[status as OceanBookingStatus] || '未知状态'
+}
diff --git a/src/modules/ocean-bookings/types.ts b/src/modules/ocean-bookings/types.ts
new file mode 100644
index 00000000..526ba594
--- /dev/null
+++ b/src/modules/ocean-bookings/types.ts
@@ -0,0 +1,110 @@
+import type { ContainerType } from '@/shared/domain/containerSpecifications'
+
+export type OceanBookingStatus = 'DRAFT' | 'RELEASED'
+export type OceanBookingPrintType = 'SHIPPING_INSTRUCTION' | 'BILL_OF_LADING_CONFIRMATION'
+export type OceanBookingDocumentType = 'BOOKING_CONFIRMATION' | 'BILL_OF_LADING'
+
+export interface OceanBookingDocument {
+  id: string
+  oceanBookingId: string
+  fileId: string
+  documentType: OceanBookingDocumentType
+  fileName: string
+  fileHash: string | null
+  sizeBytes: number | null
+  contentType: string | null
+  valid: boolean
+  uploadedBy: string
+  uploadedByName: string | null
+  uploadedAt: string
+  invalidatedBy: string | null
+  invalidatedByName: string | null
+  invalidatedAt: string | null
+}
+export interface OceanBookingDocumentMutation { document: OceanBookingDocument; bookingVersion: number }
+export interface OceanBookingDocumentInvalidation { documentId: string; bookingVersion: number }
+export type OceanBookingContainerType = ContainerType
+export type OceanBookingCarrierCode = 'MATSON' | 'SML' | 'ZIM' | 'COSCO' | 'EMC' | 'HEDE' | 'OTHER'
+
+export interface OceanBookingAgentOption {
+  supplierId: string
+  name: string
+  carrierCodes: OceanBookingCarrierCode[]
+}
+
+export interface OceanBookingParty { id?: string; partyType: string; partyName: string; contactName?: string | null; contactPhone?: string | null; address?: string | null }
+export interface OceanBookingContainerRequirement {
+  id?: string
+  requirementId?: string
+  containerType: OceanBookingContainerType
+  containerKind: string
+  quantity: number
+  remainingQuantity?: number
+  capacityCbm: number
+  maxWeightKg: number
+}
+export interface OceanBookingAllocatedContainer {
+  containerBookingId: string
+  cabinetNo: string
+  containerNo: string | null
+  requirementId: string
+  containerType: OceanBookingContainerType
+  containerKind: string
+  capacityCbm: number
+  maxWeightKg: number
+}
+export interface OceanBookingDraftData {
+  customerId: string | null; customerName: string | null; parties: OceanBookingParty[]; containerRequirements: OceanBookingContainerRequirement[]
+  channelCode: string | null; warehouseId: string | null
+  billOfLadingNo: string; vesselName: string; voyageNo: string
+  estimatedSailingAt: string | null; estimatedArrivalAt: string | null
+  shippingCompanyId?: string | null; shippingCompanyName?: string | null; carrierCode?: OceanBookingCarrierCode | null; bookingAgentId?: string | null; bookingAgentName?: string | null
+  departurePortCode?: string | null; departurePortName?: string | null; destinationPortCode?: string | null; destinationPortName?: string | null
+  placeOfDelivery?: string | null
+  remark?: string | null
+}
+export interface OceanBookingResource {
+  id: string; bookingNo: string | null; status: OceanBookingStatus; version: number
+  customerId: string | null; customerName: string | null; billOfLadingNo: string | null
+  /** 订舱柜型需求 quantity 的总和，不是已关联真实柜数。 */
+  shipperName: string | null; consigneeName: string | null; containerCount: number
+  channelCode: string | null; channelName: string | null; warehouseId: string | null; warehouseName: string | null
+  shippingCompanyId: string | null; shippingCompanyName: string | null; carrierCode: OceanBookingCarrierCode | null; bookingAgentId: string | null; bookingAgentName: string | null
+  vesselName: string | null; voyageNo: string | null; departurePortCode: string | null; departurePortName: string | null
+  destinationPortCode: string | null; destinationPortName: string | null; placeOfDelivery: string | null
+  estimatedSailingAt: string | null; estimatedArrivalAt: string | null
+  remark: string | null
+  createdAt: string | null; updatedAt: string | null
+  orderNo: string | null; carrierName: string | null; bookingAgent: string | null; pol: string | null; pod: string | null
+  mblShipper: string | null; mblConsignee: string | null; soNo: string | null; cutoffAt: string | null
+  etd: string | null; atd: string | null; eta: string | null; ata: string | null; containerSummary: string | null
+  amount: string | null; currency: string | null
+}
+export interface OceanBookingDetail extends OceanBookingResource { oceanBooking: OceanBookingResource; parties: OceanBookingParty[]; containerRequirements: OceanBookingContainerRequirement[]; containers: OceanBookingAllocatedContainer[]; documents: OceanBookingDocument[]; histories: OceanBookingStatusEvent[]; statusHistory: OceanBookingStatusEvent[] }
+export interface OceanBookingStatusEvent { id: string; fromStatus: OceanBookingStatus | null; toStatus: OceanBookingStatus; action: string; reason?: string | null; operatorName: string | null; occurredAt: string }
+export interface OceanBookingPage { records: OceanBookingResource[]; page: number; size: number; total: number; pages: number }
+export interface OceanBookingQuery { page: number; size: number; keyword?: string; status?: OceanBookingStatus; customerId?: string }
+export interface OceanBookingLinkCandidate {
+  oceanBookingId: string
+  bookingNo: string
+  requirementId: string
+  containerType: string
+  capacityCbm: number
+  maxWeightKg: number
+  requiredQuantity: number
+  allocatedQuantity: number
+  remainingQuantity: number
+  customerName: string
+  warehouseName: string
+  channelName: string
+}
+export interface OceanBookingLinkCandidatePage { records: OceanBookingLinkCandidate[]; page: number; size: number; total: number; pages: number }
+export interface OceanBookingLinkCandidateQuery {
+  warehouseId: string
+  channelGroupCode: string
+  containerType: string
+  page: number
+  size: number
+}
+export interface OceanBookingSaveRequest { expectedVersion: number; data: OceanBookingDraftData }
+export interface OceanBookingReleaseRequest { expectedVersion: number }
diff --git a/src/modules/outbound-dispatch/api/platformOutboundDispatch.test.ts b/src/modules/outbound-dispatch/api/platformOutboundDispatch.test.ts
new file mode 100644
index 00000000..d0ede23c
--- /dev/null
+++ b/src/modules/outbound-dispatch/api/platformOutboundDispatch.test.ts
@@ -0,0 +1,96 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import {
+  changeOutboundDispatch,
+  checkContainerOutboundGate,
+  confirmContainerOutboundDispatch,
+  getContainerOutboundDispatch,
+  listOutboundDispatches,
+} from './platformOutboundDispatch'
+
+vi.mock('@/shared/api/http', async () => {
+  const actual = await vi.importActual<typeof import('@/shared/api/http')>('@/shared/api/http')
+  return { ...actual, http: { get: vi.fn(), post: vi.fn() } }
+})
+
+const gate = {
+  passed: true,
+  checkedAt: '2026-08-26T12:00:00',
+  inbounds: [{
+    inboundId: '2092438843630391501',
+    inboundCode: 'IN-1',
+    gate: { passed: true, checkedAt: '2026-08-26T12:00:00', items: [] },
+  }],
+}
+const aggregate = {
+  containerBookingId: '2092438843630391297',
+  cabinetNo: 'CAB-1',
+  containerNo: 'C11111111',
+  loadingPlanId: '2092438843630391401',
+  loadingPlanStatus: 'COMPLETED',
+  oceanBookingId: '2092438843630391601',
+  truckAppointmentId: null,
+  dispatchStatus: 'READY_FOR_DISPATCH',
+  version: '4',
+  inbounds: [{
+    orderId: '2092438843630391701',
+    orderNo: 'O1',
+    inboundId: '2092438843630391501',
+    inboundCode: 'IN-1',
+    tenantId: '2092438843630391801',
+    customerId: '2092438843630391901',
+    inboundStatus: 'LOADED',
+    pickTaskId: null,
+  }],
+  gate,
+}
+
+describe('platformOutboundDispatch', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it('normalizes aggregate ids', async () => {
+    vi.mocked(http.get).mockResolvedValue({ code: '200', data: [{ orderId: 1, orderNo: 'O1', inboundId: 2, inboundCode: 'I1', customerId: 3, version: '4' }] })
+    const result = await listOutboundDispatches({})
+    expect(result[0]).toMatchObject({ orderId: '1', inboundId: '2', customerId: '3', version: 4 })
+  })
+
+  it('posts legacy action with version and idempotency', async () => {
+    vi.mocked(http.post).mockResolvedValue({ code: '200', data: { aggregate: { orderId: 1, orderNo: 'O1', inboundId: 2, inboundCode: 'I1', version: 5 }, timeline: [] } })
+    await changeOutboundDispatch('confirm-dispatch', { inboundId: '2', expectedVersion: 4 })
+    expect(vi.mocked(http.post).mock.calls[0]?.[1]).toEqual({ inboundId: '2', expectedVersion: 4 })
+    expect(vi.mocked(http.post).mock.calls[0]?.[2]).toMatchObject({ headers: { 'Idempotency-Key': expect.any(String) } })
+  })
+
+  it('gets exact container-level paths and normalizes all ids', async () => {
+    vi.mocked(http.get)
+      .mockResolvedValueOnce({ code: '200', data: { aggregate, timeline: [{ module: 'OUTBOUND', action: 'READY', operatorId: 9, occurredAt: '2026-08-26T12:00:00' }] } })
+      .mockResolvedValueOnce({ code: '200', data: gate })
+
+    const detail = await getContainerOutboundDispatch('2092438843630391297')
+    const resultGate = await checkContainerOutboundGate('2092438843630391297')
+
+    expect(http.get).toHaveBeenNthCalledWith(1, '/platform/v1/first-leg/outbound-dispatches/2092438843630391297')
+    expect(http.get).toHaveBeenNthCalledWith(2, '/platform/v1/first-leg/outbound-dispatches/2092438843630391297/gate')
+    expect(detail.aggregate).toMatchObject({
+      containerBookingId: String(aggregate.containerBookingId),
+      loadingPlanId: String(aggregate.loadingPlanId),
+      oceanBookingId: String(aggregate.oceanBookingId),
+      version: 4,
+      inbounds: [{ orderId: String(aggregate.inbounds[0].orderId), inboundId: String(aggregate.inbounds[0].inboundId), tenantId: String(aggregate.inbounds[0].tenantId), customerId: String(aggregate.inbounds[0].customerId) }],
+    })
+    expect(detail.timeline[0]?.operatorId).toBe('9')
+    expect(resultGate.inbounds[0]?.inboundId).toBe(String(gate.inbounds[0].inboundId))
+  })
+
+  it('confirms once at container level without inboundId and includes idempotency', async () => {
+    vi.mocked(http.post).mockResolvedValue({ code: '200', data: { aggregate, timeline: [] } })
+    await confirmContainerOutboundDispatch('2092438843630391297', { expectedVersion: 4, remark: '货柜详情确认国内出仓' })
+
+    expect(http.post).toHaveBeenCalledWith(
+      '/platform/v1/first-leg/outbound-dispatches/2092438843630391297/confirm',
+      { expectedVersion: 4, remark: '货柜详情确认国内出仓' },
+      { headers: { 'Idempotency-Key': expect.any(String) } },
+    )
+    expect(vi.mocked(http.post).mock.calls[0]?.[1]).not.toHaveProperty('inboundId')
+  })
+})
diff --git a/src/modules/outbound-dispatch/api/platformOutboundDispatch.ts b/src/modules/outbound-dispatch/api/platformOutboundDispatch.ts
new file mode 100644
index 00000000..8506de19
--- /dev/null
+++ b/src/modules/outbound-dispatch/api/platformOutboundDispatch.ts
@@ -0,0 +1,87 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import type {
+  ContainerOutboundActionRequest,
+  ContainerOutboundAggregate,
+  ContainerOutboundDispatchDetail,
+  ContainerOutboundGateResult,
+  ContainerOutboundInboundBinding,
+  ContainerOutboundInboundGate,
+  OutboundDispatchDetail,
+  OutboundDispatchQuery,
+  OutboundDispatchResource,
+  OutboundGateResult,
+} from '../types'
+const basePath = '/platform/v1/first-leg/outbound-dispatches'; const keys = ['orderId', 'inboundId', 'containerBookingId', 'customerId'] as const
+function item(raw: OutboundDispatchResource): OutboundDispatchResource { const value = { ...raw } as OutboundDispatchResource & Record<string, unknown>; for (const key of keys) if (value[key] != null) value[key] = String(value[key]); value.version = Number(value.version ?? 0); return value }
+function idem() { return `outbound-dispatch-${Date.now()}-${Math.random().toString(36).slice(2)}` }
+export async function listOutboundDispatches(query: OutboundDispatchQuery) { const response = await http.get<ApiEnvelope<OutboundDispatchResource[]>, ApiEnvelope<OutboundDispatchResource[]>>(basePath, { params: query }); return (unwrapApiResponse(response) || []).map(item) }
+export async function getOutboundDispatchDetail(query: OutboundDispatchQuery) { const response = await http.get<ApiEnvelope<OutboundDispatchDetail>, ApiEnvelope<OutboundDispatchDetail>>(`${basePath}/detail`, { params: query }); const data = unwrapApiResponse(response); return { ...data, aggregate: item(data.aggregate) } }
+export async function checkOutboundGate(query: OutboundDispatchQuery) { const response = await http.get<ApiEnvelope<OutboundGateResult>, ApiEnvelope<OutboundGateResult>>(`${basePath}/check-gate`, { params: query }); return unwrapApiResponse(response) }
+export async function changeOutboundDispatch(action: 'confirm-dispatch' | 'reverse-dispatch', request: { inboundId: string; containerBookingId?: string | null; expectedVersion: number; remark?: string }) { const response = await http.post<ApiEnvelope<OutboundDispatchDetail>, ApiEnvelope<OutboundDispatchDetail>>(`${basePath}/${action}`, request, { headers: { 'Idempotency-Key': idem() } }); const data = unwrapApiResponse(response); return { ...data, aggregate: item(data.aggregate) } }
+
+function optionalId(value: unknown): string | null {
+  return value == null ? null : String(value)
+}
+
+function inboundBinding(raw: ContainerOutboundInboundBinding): ContainerOutboundInboundBinding {
+  return {
+    ...raw,
+    orderId: String(raw.orderId),
+    inboundId: String(raw.inboundId),
+    tenantId: String(raw.tenantId),
+    customerId: optionalId(raw.customerId),
+    pickTaskId: optionalId(raw.pickTaskId),
+  }
+}
+
+function inboundGate(raw: ContainerOutboundInboundGate): ContainerOutboundInboundGate {
+  return { ...raw, inboundId: String(raw.inboundId), gate: { ...raw.gate, items: raw.gate?.items || [] } }
+}
+
+function containerGate(raw: ContainerOutboundGateResult): ContainerOutboundGateResult {
+  return { ...raw, inbounds: (raw.inbounds || []).map(inboundGate) }
+}
+
+function containerAggregate(raw: ContainerOutboundAggregate): ContainerOutboundAggregate {
+  return {
+    ...raw,
+    containerBookingId: String(raw.containerBookingId),
+    loadingPlanId: String(raw.loadingPlanId),
+    oceanBookingId: optionalId(raw.oceanBookingId),
+    truckAppointmentId: optionalId(raw.truckAppointmentId),
+    version: Number(raw.version ?? 0),
+    inbounds: (raw.inbounds || []).map(inboundBinding),
+    gate: containerGate(raw.gate),
+  }
+}
+
+function containerDetail(raw: ContainerOutboundDispatchDetail): ContainerOutboundDispatchDetail {
+  return {
+    ...raw,
+    aggregate: containerAggregate(raw.aggregate),
+    timeline: (raw.timeline || []).map((entry) => ({ ...entry, operatorId: optionalId(entry.operatorId) })),
+  }
+}
+
+export async function getContainerOutboundDispatch(containerBookingId: string) {
+  const response = await http.get<ApiEnvelope<ContainerOutboundDispatchDetail>, ApiEnvelope<ContainerOutboundDispatchDetail>>(
+    `${basePath}/${encodeURIComponent(containerBookingId)}`,
+  )
+  return containerDetail(unwrapApiResponse(response))
+}
+
+export async function checkContainerOutboundGate(containerBookingId: string) {
+  const response = await http.get<ApiEnvelope<ContainerOutboundGateResult>, ApiEnvelope<ContainerOutboundGateResult>>(
+    `${basePath}/${encodeURIComponent(containerBookingId)}/gate`,
+  )
+  return containerGate(unwrapApiResponse(response))
+}
+
+export async function confirmContainerOutboundDispatch(containerBookingId: string, request: ContainerOutboundActionRequest) {
+  const response = await http.post<ApiEnvelope<ContainerOutboundDispatchDetail>, ApiEnvelope<ContainerOutboundDispatchDetail>>(
+    `${basePath}/${encodeURIComponent(containerBookingId)}/confirm`,
+    request,
+    { headers: { 'Idempotency-Key': idem() } },
+  )
+  return containerDetail(unwrapApiResponse(response))
+}
diff --git a/src/modules/outbound-dispatch/index.ts b/src/modules/outbound-dispatch/index.ts
new file mode 100644
index 00000000..c7818e3b
--- /dev/null
+++ b/src/modules/outbound-dispatch/index.ts
@@ -0,0 +1,3 @@
+export { outboundDispatchRoutes } from './routes'
+export { confirmContainerOutboundDispatch, getContainerOutboundDispatch } from './api/platformOutboundDispatch'
+export * from './types'
diff --git a/src/modules/outbound-dispatch/pages/OutboundDispatchesView.test.ts b/src/modules/outbound-dispatch/pages/OutboundDispatchesView.test.ts
new file mode 100644
index 00000000..f6604778
--- /dev/null
+++ b/src/modules/outbound-dispatch/pages/OutboundDispatchesView.test.ts
@@ -0,0 +1,182 @@
+import ElementPlus from 'element-plus'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { createPinia, setActivePinia } from 'pinia'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import QueryToolbar from '@/shared/components/QueryToolbar.vue'
+import DataTable from '@/shared/components/DataTable.vue'
+import { listPlatformTenants, type PlatformTenantResource } from '@/modules/iam'
+import { listPlatformUnifiedOrders, type UnifiedOrderResource } from '@/modules/unified-orders'
+import { listContainers, type ContainerBookingResource } from '@/modules/container-loading'
+import { getOutboundDispatchDetail, listOutboundDispatches } from '../api/platformOutboundDispatch'
+import type { OutboundDispatchResource } from '../types'
+import OutboundDispatchesView from './OutboundDispatchesView.vue'
+
+vi.mock('@/modules/iam', () => ({ listPlatformTenants: vi.fn() }))
+vi.mock('@/modules/unified-orders', () => ({ listPlatformUnifiedOrders: vi.fn() }))
+vi.mock('@/modules/container-loading', () => ({ listContainers: vi.fn() }))
+vi.mock('../api/platformOutboundDispatch', () => ({ listOutboundDispatches: vi.fn(), getOutboundDispatchDetail: vi.fn(), changeOutboundDispatch: vi.fn() }))
+
+const customer = { id: '10001', tenantCode: 'CUS-1', tenantName: '示例客户', legalName: '示例客户有限公司', status: 'ACTIVE' } as PlatformTenantResource
+const order = { orderId: '20001', orderNo: 'ORD-001', inboundId: '30001', inboundCode: 'IN-001', customerId: '10001', customerName: '示例客户' } as UnifiedOrderResource
+const secondOrder = { ...order, orderId: '20002', orderNo: 'ORD-002', inboundId: '30002', inboundCode: 'IN-002' } as UnifiedOrderResource
+const container = { id: '40001', bookingNo: 'BK-001', cabinetNo: 'CAB-001', containerNo: 'MSCU-001' } as ContainerBookingResource
+const row = { orderId: '20001', orderNo: 'ORD-001', inboundId: '30001', inboundCode: 'IN-001', customerId: '10001', customerName: '示例客户', containerBookingId: '40001', cabinetNo: 'CAB-001', containerNo: 'MSCU-001', oceanBookingStatus: 'RELEASED', truckAppointmentStatus: 'COMPLETED', pickTaskStatus: 'AWAITING_REVIEW', dispatchStatus: 'READY_FOR_DISPATCH', version: 1, gate: { passed: true, items: [], checkedAt: '2026-08-11T10:00:00' } } as OutboundDispatchResource
+
+enableAutoUnmount(afterEach)
+
+function deferred<T>() {
+  let resolve!: (value: T) => void
+  let reject!: (reason?: unknown) => void
+  const promise = new Promise<T>((resolvePromise, rejectPromise) => { resolve = resolvePromise; reject = rejectPromise })
+  return { promise, resolve, reject }
+}
+
+function mountPage() {
+  return mount(OutboundDispatchesView, { attachTo: document.body, global: { plugins: [ElementPlus, createPinia()] } })
+}
+
+async function setFilters(wrapper: ReturnType<typeof mountPage>, values: Record<string, string>) {
+  const toolbar = wrapper.findComponent(QueryToolbar)
+  toolbar.vm.$emit('update:modelValue', { ...toolbar.props('modelValue'), ...values })
+  await flushPromises()
+  return toolbar
+}
+
+describe('OutboundDispatchesView', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    setActivePinia(createPinia())
+    vi.mocked(listPlatformTenants).mockResolvedValue({ records: [customer], page: 1, size: 200, total: 1, pages: 1 })
+    vi.mocked(listPlatformUnifiedOrders).mockResolvedValue({ records: [order, secondOrder], page: 1, size: 200, total: 2, pages: 1 })
+    vi.mocked(listContainers).mockResolvedValue({ records: [container], page: 1, size: 200, total: 1, pages: 1 })
+    vi.mocked(listOutboundDispatches).mockResolvedValue([row])
+  })
+
+  it('starts idle and queries real ids selected through business labels', async () => {
+    const wrapper = mountPage()
+    await flushPromises()
+    expect(listOutboundDispatches).not.toHaveBeenCalled()
+    expect(wrapper.text()).toContain('请选择入仓码或柜次后查询')
+    const toolbar = await setFilters(wrapper, { orderId: '20001' })
+    toolbar.vm.$emit('search')
+    await flushPromises()
+    expect(listOutboundDispatches).toHaveBeenCalledOnce()
+    expect(listOutboundDispatches).toHaveBeenCalledWith({ orderId: '20001', inboundId: '30001', containerBookingId: undefined })
+    expect(wrapper.text()).toContain('IN-001')
+    expect(wrapper.text()).not.toContain('ORD-001')
+    expect(wrapper.text()).toContain('已放舱')
+    expect(wrapper.text()).toContain('已完成')
+    expect(wrapper.text()).toContain('待复核')
+    expect(wrapper.text()).toContain('待确认出仓')
+    expect(wrapper.text()).not.toContain('READY_FOR_DISPATCH')
+  })
+
+  it('loads only active customer names for the filter', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/outbound-dispatch/pages/OutboundDispatchesView.vue'), 'utf8')
+    expect(source).toContain("listPlatformTenants({ page: currentPage, size: 200, status: 'ACTIVE' })")
+    expect(source).toContain("result.records.filter((customer) => customer.status === 'ACTIVE')")
+    expect(source).toContain('while (currentPage <= pages)')
+    expect(source).toContain("item.tenantName")
+    expect(source).not.toContain('item.tenantCode')
+  })
+
+  it('does not issue a search when reset returns to the initial state', async () => {
+    const wrapper = mountPage()
+    await flushPromises()
+    const toolbar = await setFilters(wrapper, { containerBookingId: '40001' })
+    toolbar.vm.$emit('search')
+    await flushPromises()
+    expect(listOutboundDispatches).toHaveBeenCalledOnce()
+    const resetButton = wrapper.findAll('button').find((button) => button.text().includes('重置'))
+    await resetButton?.trigger('click')
+    await flushPromises()
+    expect(listOutboundDispatches).toHaveBeenCalledOnce()
+    expect(wrapper.text()).toContain('请选择入仓码或柜次后查询')
+  })
+
+  it('shows loading, empty and recoverable error states', async () => {
+    const pending = deferred<OutboundDispatchResource[]>()
+    vi.mocked(listOutboundDispatches).mockReturnValueOnce(pending.promise)
+    const wrapper = mountPage()
+    await flushPromises()
+    const toolbar = await setFilters(wrapper, { containerBookingId: '40001' })
+    toolbar.vm.$emit('search')
+    await flushPromises()
+    expect(wrapper.findComponent(DataTable).props('loading')).toBe(true)
+    pending.resolve([])
+    await flushPromises()
+    expect(wrapper.text()).toContain('暂无符合条件的出仓记录')
+
+    vi.mocked(listOutboundDispatches).mockRejectedValueOnce(new Error('network down')).mockResolvedValueOnce([row])
+    toolbar.vm.$emit('search')
+    await flushPromises()
+    expect(wrapper.text()).toContain('国内出仓加载失败')
+    const retry = wrapper.findAll('button').find((button) => button.text().includes('重新加载'))
+    await retry?.trigger('click')
+    await flushPromises()
+    expect(listOutboundDispatches).toHaveBeenCalledTimes(3)
+    expect(wrapper.text()).toContain('IN-001')
+    expect(wrapper.text()).not.toContain('ORD-001')
+  })
+
+  it('ignores stale list responses when a newer query wins', async () => {
+    const first = deferred<OutboundDispatchResource[]>()
+    const second = deferred<OutboundDispatchResource[]>()
+    vi.mocked(listOutboundDispatches).mockReturnValueOnce(first.promise).mockReturnValueOnce(second.promise)
+    const wrapper = mountPage()
+    await flushPromises()
+    let toolbar = await setFilters(wrapper, { orderId: '20001' })
+    toolbar.vm.$emit('search')
+    toolbar = await setFilters(wrapper, { orderId: '20002' })
+    toolbar.vm.$emit('search')
+    second.resolve([{ ...row, orderId: '20002', orderNo: 'ORD-002', inboundId: '30002', inboundCode: 'IN-002' }])
+    await flushPromises()
+    first.resolve([row])
+    await flushPromises()
+    expect(wrapper.text()).toContain('IN-002')
+    expect(wrapper.text()).not.toContain('IN-001')
+    expect(wrapper.text()).not.toContain('ORD-002')
+  })
+
+  it('keeps the operation column first and guarded workflow actions', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/outbound-dispatch/pages/OutboundDispatchesView.vue'), 'utf8')
+    const columnSource = source.slice(source.indexOf('const columns'))
+    expect(columnSource.indexOf("key: 'actions'")).toBeLessThan(columnSource.indexOf("prop: 'inboundCode'"))
+    expect(columnSource).not.toContain("prop: 'orderNo'")
+    expect(columnSource.indexOf("prop: 'cabinetNo', label: '柜次号'")).toBeLessThan(columnSource.indexOf("prop: 'containerNo', label: '集装箱号'"))
+    expect(columnSource).toContain("fixed: 'left'")
+    expect(source).toContain('aggregate.gate?.items')
+    expect(source).toContain('detail.timeline')
+    expect(source).toContain("'confirm-dispatch'")
+    expect(source).toContain("'reverse-dispatch'")
+    expect(source).toContain("row.dispatchStatus === 'READY_FOR_DISPATCH'")
+    expect(source).toContain("row.dispatchStatus === 'WAITING_FOR_LOADING'")
+    expect(source).toContain('timelineModuleLabel(entry.module)')
+    expect(source).toContain('timelineActionLabel(entry.action)')
+    expect(source).toContain('timelineStatusLabel(entry.module, entry.fromStatus)')
+    expect(source).toContain("error.value?.code === 'A0409'")
+    expect(getOutboundDispatchDetail).not.toHaveBeenCalled()
+  })
+
+  it('keeps the gate detail dialog responsive with internal scrolling', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/outbound-dispatch/pages/OutboundDispatchesView.vue'), 'utf8')
+    expect(source).toContain('width="min(900px, calc(100vw - 28px))"')
+    expect(source).toContain('max-height: 90vh')
+    expect(source).toContain('overflow-y: auto')
+  })
+  it('styles the native gate table with prototype borders, stripes and hover', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/outbound-dispatch/pages/OutboundDispatchesView.vue'), 'utf8')
+    expect(source).toContain('<el-table class="gate-table" :data="detail.aggregate.gate?.items || []" border stripe>')
+    expect(source).toContain('.gate-table { --el-table-row-hover-bg-color: #f1f7ff; }')
+  })
+  it('uses semantic bordered and filled business buttons instead of text links', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/outbound-dispatch/pages/OutboundDispatchesView.vue'), 'utf8')
+    expect(source).toContain('size="small" type="primary" plain')
+    expect(source).toContain('size="small" type="primary" @click="action')
+    expect(source).toContain('size="small" type="danger" plain')
+    expect(source).not.toContain("outbound-dispatch:view')\" link")
+    expect(source).toContain(':loading="loading" stripe row-key="inboundId"')
+  })
+})
diff --git a/src/modules/outbound-dispatch/pages/OutboundDispatchesView.vue b/src/modules/outbound-dispatch/pages/OutboundDispatchesView.vue
new file mode 100644
index 00000000..70d3d756
--- /dev/null
+++ b/src/modules/outbound-dispatch/pages/OutboundDispatchesView.vue
@@ -0,0 +1,226 @@
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import { Eye, RotateCcw, Send } from '@lucide/vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import DataTable from '@/shared/components/DataTable.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { listPlatformTenants, type PlatformTenantResource } from '@/modules/iam'
+import { listPlatformUnifiedOrders, type UnifiedOrderResource } from '@/modules/unified-orders'
+import { listContainers, type ContainerBookingResource } from '@/modules/container-loading'
+import { changeOutboundDispatch, getOutboundDispatchDetail, listOutboundDispatches } from '../api/platformOutboundDispatch'
+import type { OutboundDispatchDetail, OutboundDispatchQuery, OutboundDispatchResource } from '../types'
+import { oceanBookingStatusLabel, outboundDispatchStatusLabel, pickTaskStatusLabel, timelineActionLabel, timelineModuleLabel, timelineStatusLabel, truckStatusLabel } from '../statusLabels'
+
+type DispatchFilters = QueryModel & { customerId: string; orderId: string; containerBookingId: string }
+
+const access = useAccessPreviewStore()
+const rows = ref<OutboundDispatchResource[]>([])
+const loading = ref(false)
+const error = ref<ApiErrorDetails | null>(null)
+const queried = ref(false)
+const filters = ref<DispatchFilters>({ customerId: '', orderId: '', containerBookingId: '' })
+const customers = ref<PlatformTenantResource[]>([])
+const orders = ref<UnifiedOrderResource[]>([])
+const containers = ref<ContainerBookingResource[]>([])
+const optionsLoading = ref(false)
+const optionsError = ref('')
+const activeQuery = ref<OutboundDispatchQuery | null>(null)
+let listRequestId = 0
+let optionRequestId = 0
+let detailRequestId = 0
+let disposed = false
+
+const fields = computed<QueryField[]>(() => [
+  { key: 'customerId', type: 'select', label: '客户', width: 240, placeholder: '全部客户', options: customers.value.map((item) => ({ label: item.tenantName, value: String(item.id) })), props: { filterable: true, loading: optionsLoading.value } },
+  { key: 'orderId', type: 'select', label: '入仓码', width: 280, placeholder: filters.value.customerId ? '请选择该客户的入仓码' : '请选择入仓码', options: orders.value.map((item) => ({ label: item.inboundCode || '入仓码暂缺', value: String(item.orderId), disabled: item.inboundId == null })), props: { filterable: true, loading: optionsLoading.value } },
+  { key: 'containerBookingId', type: 'select', label: '柜次', width: 240, placeholder: '请选择柜号或集装箱号', options: containers.value.map((item) => ({ label: `${item.cabinetNo || item.bookingNo}${item.containerNo ? ` / ${item.containerNo}` : ''}`, value: item.id })), props: { filterable: true, loading: optionsLoading.value } },
+])
+
+const columns = [
+  { key: 'actions', label: '操作', fixed: 'left', width: 240, slotName: 'actions', hideable: false, movable: false },
+  { prop: 'inboundCode', label: '入仓码', minWidth: 145 },
+  { prop: 'customerName', label: '客户', minWidth: 140 },
+  { prop: 'cabinetNo', label: '柜次号', minWidth: 145, formatter: (row: OutboundDispatchResource) => row.cabinetNo || '—' },
+  { prop: 'containerNo', label: '集装箱号', minWidth: 145, formatter: (row: OutboundDispatchResource) => row.containerNo || '—' },
+  { prop: 'oceanBookingStatus', label: '订舱', width: 105, slotName: 'booking' },
+  { prop: 'truckAppointmentStatus', label: '拖车', width: 105, slotName: 'truck' },
+  { prop: 'pickTaskStatus', label: '拣货', width: 105, slotName: 'pick' },
+  { prop: 'dispatchStatus', label: '出仓状态', width: 115, slotName: 'status' },
+  { key: 'gate', label: '门禁', width: 90, slotName: 'gate' },
+]
+
+function currentQuery(): OutboundDispatchQuery | null {
+  const order = orders.value.find((item) => String(item.orderId) === filters.value.orderId)
+  const params = {
+    orderId: order ? String(order.orderId) : undefined,
+    inboundId: order?.inboundId == null ? undefined : String(order.inboundId),
+    containerBookingId: String(filters.value.containerBookingId || '').trim() || undefined,
+  }
+  return params.orderId || params.inboundId || params.containerBookingId ? params : null
+}
+
+async function load(params = activeQuery.value) {
+  if (!params) return
+  const requestId = ++listRequestId
+  loading.value = true
+  error.value = null
+  queried.value = true
+  try {
+    const result = await listOutboundDispatches(params)
+    if (disposed || requestId !== listRequestId) return
+    rows.value = result
+  } catch (cause) {
+    if (disposed || requestId !== listRequestId) return
+    rows.value = []
+    error.value = getApiErrorDetails(cause)
+  } finally {
+    if (!disposed && requestId === listRequestId) loading.value = false
+  }
+}
+
+function search() {
+  const params = currentQuery()
+  if (!params) {
+    listRequestId += 1
+    activeQuery.value = null
+    rows.value = []
+    error.value = null
+    loading.value = false
+    queried.value = false
+    return
+  }
+  activeQuery.value = params
+  void load(params)
+}
+
+function resetSearch() {
+  listRequestId += 1
+  activeQuery.value = null
+  rows.value = []
+  error.value = null
+  loading.value = false
+  queried.value = false
+}
+
+async function loadOptions(customerId = filters.value.customerId) {
+  const requestId = ++optionRequestId
+  optionsLoading.value = true
+  optionsError.value = ''
+  const results = await Promise.allSettled([
+    loadActiveCustomers(),
+    listPlatformUnifiedOrders({ customerId: customerId || undefined, page: 1, size: 200 }),
+    listContainers({ page: 1, size: 200 }),
+  ])
+  if (disposed || requestId !== optionRequestId) return
+  if (results[0].status === 'fulfilled') customers.value = results[0].value
+  if (results[1].status === 'fulfilled') orders.value = results[1].value.records
+  if (results[2].status === 'fulfilled') containers.value = results[2].value.records
+  const failed = ['客户', '订单', '柜次'].filter((_, index) => results[index]?.status === 'rejected')
+  if (failed.length) optionsError.value = `${failed.join('、')}选项加载失败，可重新加载后再查询`
+  optionsLoading.value = false
+}
+
+async function loadActiveCustomers() {
+  const records: PlatformTenantResource[] = []
+  let currentPage = 1
+  let pages = 1
+  do {
+    const result = await listPlatformTenants({ page: currentPage, size: 200, status: 'ACTIVE' })
+    records.push(...result.records.filter((customer) => customer.status === 'ACTIVE'))
+    pages = Math.max(1, result.pages)
+    currentPage += 1
+  } while (currentPage <= pages)
+  return records
+}
+
+watch(() => filters.value.customerId, (customerId, previous) => {
+  if (customerId === previous) return
+  filters.value = { ...filters.value, orderId: '' }
+  orders.value = []
+  void loadOptions(customerId)
+})
+
+const detailOpen = ref(false)
+const detail = ref<OutboundDispatchDetail | null>(null)
+const detailTarget = ref<OutboundDispatchResource | null>(null)
+const detailLoading = ref(false)
+const actionError = ref<ApiErrorDetails | null>(null)
+async function open(value: unknown) {
+  const row = value as OutboundDispatchResource
+  const requestId = ++detailRequestId
+  detailOpen.value = true
+  detailTarget.value = row
+  detail.value = null
+  detailLoading.value = true
+  actionError.value = null
+  try {
+    const result = await getOutboundDispatchDetail({ inboundId: row.inboundId, containerBookingId: row.containerBookingId || undefined })
+    if (disposed || requestId !== detailRequestId) return
+    detail.value = result
+  } catch (cause) {
+    if (disposed || requestId !== detailRequestId) return
+    actionError.value = getApiErrorDetails(cause)
+  } finally {
+    if (!disposed && requestId === detailRequestId) detailLoading.value = false
+  }
+}
+function retryDetail() { if (detailTarget.value) void open(detailTarget.value) }
+
+async function action(value: unknown, name: 'confirm-dispatch' | 'reverse-dispatch') {
+  const row = value as OutboundDispatchResource
+  try {
+    await ElMessageBox.confirm(name === 'confirm-dispatch' ? '确认国内出仓？系统将校验全部装柜门禁。' : '确认撤销国内出仓？', '出仓状态确认', { type: name === 'reverse-dispatch' ? 'warning' : 'info' })
+    await changeOutboundDispatch(name, { inboundId: row.inboundId, containerBookingId: row.containerBookingId, expectedVersion: row.version, remark: name === 'confirm-dispatch' ? '后台确认出仓' : '后台撤销出仓' })
+    ElMessage.success('出仓状态已更新')
+    await load()
+  } catch (cause) {
+    if (cause !== 'cancel' && !(cause instanceof Error && cause.message === 'cancel')) error.value = getApiErrorDetails(cause)
+    if (error.value?.code === 'A0409') await load()
+  }
+}
+
+onMounted(() => void loadOptions())
+onBeforeUnmount(() => { disposed = true; listRequestId += 1; optionRequestId += 1; detailRequestId += 1 })
+</script>
+
+<template>
+  <AdminPage as="div">
+    <ListPageLayout aria-label="国内出仓列表">
+      <template #toolbar><QueryToolbar v-model="filters" class="surface-panel" ariaLabel="国内出仓筛选" :fields="fields" :search-on-reset="false" @search="search" @reset="resetSearch" /></template>
+      <template v-if="optionsError || error" #state>
+        <el-alert v-if="optionsError" type="warning" :closable="false" show-icon :title="optionsError"><el-button link type="warning" :loading="optionsLoading" @click="loadOptions()">重新加载选项</el-button></el-alert>
+        <LoadErrorState v-if="error" title="国内出仓加载失败" :message="error.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="error" /></template></LoadErrorState>
+      </template>
+      <section v-if="!error" class="surface-panel table-panel">
+        <el-empty v-if="!queried" description="请选择入仓码或柜次后查询" />
+        <DataTable v-else :data="rows" :columns="columns" :loading="loading" stripe row-key="inboundId" preference-key="outbound-dispatches" empty-text="暂无符合条件的出仓记录">
+          <template #actions="{ row }"><div class="table-actions"><el-button v-if="access.can('platform:firstleg:outbound-dispatch:view')" size="small" type="primary" plain @click="open(row)"><Eye :size="15" />查看</el-button><el-button v-if="access.can('platform:firstleg:outbound-dispatch:confirm') && row.dispatchStatus === 'READY_FOR_DISPATCH'" size="small" type="primary" @click="action(row, 'confirm-dispatch')"><Send :size="15" />确认</el-button><el-button v-if="access.can('platform:firstleg:outbound-dispatch:reverse') && row.dispatchStatus === 'WAITING_FOR_LOADING'" size="small" type="danger" plain @click="action(row, 'reverse-dispatch')"><RotateCcw :size="15" />撤销</el-button></div></template>
+          <template #booking="{ row }"><StatusBadge :status="oceanBookingStatusLabel(row.oceanBookingStatus)" /></template><template #truck="{ row }"><StatusBadge :status="truckStatusLabel(row.truckAppointmentStatus)" /></template><template #pick="{ row }"><StatusBadge :status="pickTaskStatusLabel(row.pickTaskStatus)" /></template><template #status="{ row }"><StatusBadge :status="outboundDispatchStatusLabel(row.dispatchStatus)" /></template><template #gate="{ row }"><el-tag :type="row.gate?.passed ? 'success' : 'danger'">{{ row.gate?.passed ? '通过' : '未通过' }}</el-tag></template>
+        </DataTable>
+      </section>
+    </ListPageLayout>
+    <AppDialog v-model="detailOpen" class="outbound-detail-dialog" title="国内出仓详情" width="min(900px, calc(100vw - 28px))" :show-confirm="false">
+      <LoadErrorState v-if="actionError" title="出仓详情加载失败" :message="actionError.message" :loading="detailLoading" @retry="retryDetail"><template #details><ApiErrorMeta :details="actionError" /></template></LoadErrorState>
+      <div v-else-if="detailLoading" class="detail-loading" aria-busy="true"><el-skeleton :rows="5" animated /></div>
+      <template v-else-if="detail"><el-descriptions :column="2" border><el-descriptions-item label="入仓码">{{ detail.aggregate.inboundCode || '—' }}</el-descriptions-item><el-descriptions-item label="柜次号">{{ detail.aggregate.cabinetNo || '—' }}</el-descriptions-item><el-descriptions-item label="集装箱号">{{ detail.aggregate.containerNo || '—' }}</el-descriptions-item><el-descriptions-item label="出仓状态"><StatusBadge :status="outboundDispatchStatusLabel(detail.aggregate.dispatchStatus)" /></el-descriptions-item></el-descriptions><h3>统一门禁</h3><el-table class="gate-table" :data="detail.aggregate.gate?.items || []" border stripe><el-table-column label="结果" width="80"><template #default="scope"><el-tag :type="scope.row.passed ? 'success' : 'danger'">{{ scope.row.passed ? '通过' : '阻断' }}</el-tag></template></el-table-column><el-table-column prop="name" label="门禁" min-width="140" /><el-table-column prop="actual" label="当前情况" min-width="180" /><el-table-column prop="requirement" label="要求" min-width="180" /></el-table><h3>整体时间线</h3><el-timeline><el-timeline-item v-for="entry in detail.timeline" :key="`${entry.module}-${entry.occurredAt}-${entry.action}`" :timestamp="entry.occurredAt">{{ timelineModuleLabel(entry.module) }} · {{ timelineActionLabel(entry.action) }}：{{ timelineStatusLabel(entry.module, entry.fromStatus) }} → {{ timelineStatusLabel(entry.module, entry.toStatus) }}<small>{{ entry.operatorName || '系统' }} {{ entry.remark || '' }}</small></el-timeline-item></el-timeline></template>
+    </AppDialog>
+  </AdminPage>
+</template>
+
+<style scoped>
+h3 { margin: 20px 0 12px; }
+small { display: block; color: var(--cc-muted); }
+.detail-loading { padding: 12px 0; }
+.gate-table { --el-table-row-hover-bg-color: #f1f7ff; }
+.table-actions { display: flex; align-items: center; gap: 6px; }.table-actions :deep(.el-button) { margin-left: 0; }
+:global(.outbound-detail-dialog.el-dialog) { max-height: 90vh; overflow: hidden; }
+:global(.outbound-detail-dialog .el-dialog__body) { max-height: calc(90vh - 120px); overflow-y: auto; }
+</style>
diff --git a/src/modules/outbound-dispatch/routes.ts b/src/modules/outbound-dispatch/routes.ts
new file mode 100644
index 00000000..1fe6a3b7
--- /dev/null
+++ b/src/modules/outbound-dispatch/routes.ts
@@ -0,0 +1,2 @@
+import type { RouteRecordRaw } from 'vue-router'
+export const outboundDispatchRoutes = [{ path: 'outbound-dispatches', name: 'outbound-dispatches', component: () => import('./pages/OutboundDispatchesView.vue'), meta: { title: '国内出仓', description: '查看装柜门禁、整体时间线并确认国内出仓', permission: 'platform:firstleg:outbound-dispatch:list' } }] satisfies RouteRecordRaw[]
diff --git a/src/modules/outbound-dispatch/statusLabels.test.ts b/src/modules/outbound-dispatch/statusLabels.test.ts
new file mode 100644
index 00000000..9d01d3c2
--- /dev/null
+++ b/src/modules/outbound-dispatch/statusLabels.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest'
+import { oceanBookingStatusLabel, outboundDispatchStatusLabel, pickTaskStatusLabel, timelineActionLabel, timelineModuleLabel, timelineStatusLabel, truckStatusLabel } from './statusLabels'
+
+describe('outbound dispatch status labels', () => {
+  it('maps list statuses to business Chinese', () => {
+    expect(outboundDispatchStatusLabel('READY_FOR_DISPATCH')).toBe('待确认出仓')
+    expect(outboundDispatchStatusLabel('WAITING_FOR_LOADING')).toBe('等待装柜')
+    expect(oceanBookingStatusLabel('RELEASED')).toBe('已放舱')
+    expect(truckStatusLabel('PICKUP_IN_PROGRESS')).toBe('提柜中')
+    expect(pickTaskStatusLabel('PENDING')).toBe('待拣货')
+    expect(pickTaskStatusLabel('IN_PROGRESS')).toBe('拣货中')
+    expect(pickTaskStatusLabel('AWAITING_REVIEW')).toBe('待复核')
+    expect(pickTaskStatusLabel('COMPLETED')).toBe('已完成')
+  })
+
+  it('localizes timeline modules, actions and module-specific states', () => {
+    expect(timelineModuleLabel('OUTBOUND_DISPATCH')).toBe('国内出仓')
+    expect(timelineActionLabel('CONFIRM_DISPATCH')).toBe('确认出仓')
+    expect(timelineStatusLabel('OUTBOUND_DISPATCH', 'READY_FOR_DISPATCH')).toBe('待确认出仓')
+    expect(timelineStatusLabel('OCEAN_BOOKING', 'RELEASED')).toBe('已放舱')
+    expect(timelineStatusLabel('TRUCK_APPOINTMENT', 'COMPLETED')).toBe('已完成')
+    expect(timelineStatusLabel('INBOUND', 'WAIT_SPLIT')).toBe('待分柜')
+  })
+
+  it('does not expose unknown backend enum values', () => {
+    expect(outboundDispatchStatusLabel('NEW_BACKEND_STATE')).toBe('未知状态')
+    expect(timelineModuleLabel('NEW_MODULE')).toBe('其他业务流程')
+    expect(timelineActionLabel('NEW_ACTION')).toBe('状态更新')
+    expect(timelineStatusLabel('NEW_MODULE', 'NEW_STATE')).toBe('未知状态')
+  })
+})
diff --git a/src/modules/outbound-dispatch/statusLabels.ts b/src/modules/outbound-dispatch/statusLabels.ts
new file mode 100644
index 00000000..58b7a1fc
--- /dev/null
+++ b/src/modules/outbound-dispatch/statusLabels.ts
@@ -0,0 +1,111 @@
+import { truckAppointmentStatusLabels } from '@/modules/trucking'
+import { oceanBookingStatusLabel as sharedOceanBookingStatusLabel } from '@/modules/ocean-bookings'
+
+const dispatchStatusLabels: Record<string, string> = {
+  READY_FOR_DISPATCH: '待确认出仓',
+  WAITING_FOR_LOADING: '等待装柜',
+}
+
+const pickTaskStatusLabels: Record<string, string> = {
+  PENDING: '待拣货',
+  IN_PROGRESS: '拣货中',
+  AWAITING_REVIEW: '待复核',
+  COMPLETED: '已完成',
+  CANCELLED: '已取消',
+}
+
+const inboundStatusLabels: Record<string, string> = {
+  WAIT_MEASURE: '待测量',
+  MEASURING: '测量中',
+  MEASURE_PENDING: '待测量审核',
+  MEASURE_REJECTED: '测量已驳回',
+  WAIT_PRICING: '待计费',
+  FEE_CONFIRMING: '费用处理中',
+  INBOUNDING: '入库处理中',
+  WAIT_SPLIT: '待分柜',
+  VOIDED: '已作废',
+}
+
+const loadingPlanStatusLabels: Record<string, string> = {
+  WAIT_LOADING: '等待装柜',
+  EDITING: '编辑中',
+  PRELOADED: '已预装',
+  CONFIRMED: '已确认',
+  LOADING: '装柜中',
+  COMPLETED: '已完成',
+  CANCELLED: '已取消',
+}
+
+const moduleLabels: Record<string, string> = {
+  INBOUND: '入库作业',
+  LOADING_PLAN: '装柜计划',
+  PDA_PICK: 'PDA 拣货',
+  LOADING_EVIDENCE: '装柜证据',
+  OCEAN_BOOKING: '海运订舱',
+  TRUCK_APPOINTMENT: '拖车预约',
+  OUTBOUND_DISPATCH: '国内出仓',
+}
+
+const actionLabels: Record<string, string> = {
+  CREATE: '创建',
+  UPDATE: '更新',
+  SUBMIT: '提交',
+  APPROVE: '审核通过',
+  REJECT: '审核驳回',
+  CONFIRM: '确认',
+  RELEASE: '放舱',
+  FAIL: '标记失败',
+  CANCEL: '取消',
+  CHANGE_REQUEST: '申请改船',
+  REQUEST_CHANGE: '申请改船',
+  CONFIRM_CHANGE: '确认改船',
+  FAIL_CHANGE: '驳回改船',
+  CONFIRM_DISPATCH: '确认出仓',
+  REVERSE_DISPATCH: '撤销出仓',
+  UPSERT_EVIDENCE: '登记装柜证据',
+  VOID_EVIDENCE: '作废装柜证据',
+  START: '开始作业',
+  COMPLETE: '完成作业',
+}
+
+function mapped(value: string | null | undefined, labels: Record<string, string>, empty: string) {
+  if (!value) return empty
+  return labels[value] || '未知状态'
+}
+
+export function outboundDispatchStatusLabel(value: string | null | undefined) {
+  return mapped(value, dispatchStatusLabels, '待确认出仓')
+}
+
+export function oceanBookingStatusLabel(value: string | null | undefined) {
+  return sharedOceanBookingStatusLabel(value, '未关联')
+}
+
+export function truckStatusLabel(value: string | null | undefined) {
+  return mapped(value, truckAppointmentStatusLabels as Record<string, string>, '未关联')
+}
+
+export function pickTaskStatusLabel(value: string | null | undefined) {
+  return mapped(value, pickTaskStatusLabels, '未关联')
+}
+
+export function timelineModuleLabel(value: string | null | undefined) {
+  if (!value) return '业务流程'
+  return moduleLabels[value] || '其他业务流程'
+}
+
+export function timelineActionLabel(value: string | null | undefined) {
+  if (!value) return '状态更新'
+  return actionLabels[value] || '状态更新'
+}
+
+export function timelineStatusLabel(module: string | null | undefined, value: string | null | undefined) {
+  if (!value) return '—'
+  if (module === 'OUTBOUND_DISPATCH') return outboundDispatchStatusLabel(value)
+  if (module === 'OCEAN_BOOKING') return oceanBookingStatusLabel(value)
+  if (module === 'TRUCK_APPOINTMENT') return truckStatusLabel(value)
+  if (module === 'PDA_PICK') return pickTaskStatusLabel(value)
+  if (module === 'INBOUND') return mapped(value, inboundStatusLabels, '—')
+  if (module === 'LOADING_PLAN') return mapped(value, loadingPlanStatusLabels, '—')
+  return '未知状态'
+}
diff --git a/src/modules/outbound-dispatch/types.ts b/src/modules/outbound-dispatch/types.ts
new file mode 100644
index 00000000..e38c1775
--- /dev/null
+++ b/src/modules/outbound-dispatch/types.ts
@@ -0,0 +1,77 @@
+export interface OutboundGateItem { code: string; name: string; passed: boolean; actual?: string | null; requirement?: string | null }
+export interface OutboundGateResult { passed: boolean; items: OutboundGateItem[]; checkedAt: string }
+export interface OutboundDispatchResource { orderId: string; orderNo: string; inboundId: string; inboundCode: string; customerId?: string | null; customerName?: string | null; inboundStatus?: string | null; containerBookingId?: string | null; cabinetNo?: string | null; containerNo?: string | null; loadingPlanStatus?: string | null; pickTaskStatus?: string | null; oceanBookingStatus?: string | null; truckAppointmentStatus?: string | null; dispatchStatus?: string | null; version: number; gate?: OutboundGateResult | null }
+export interface OutboundDispatchDetail { aggregate: OutboundDispatchResource; timeline: Array<{ module: string; action: string; fromStatus?: string | null; toStatus?: string | null; operatorName?: string | null; remark?: string | null; occurredAt: string }> }
+export interface OutboundDispatchQuery { orderId?: string; inboundId?: string; containerBookingId?: string }
+
+export interface ContainerOutboundGateItem {
+  code: string
+  name: string
+  passed: boolean
+  actual?: string | null
+  requirement?: string | null
+}
+
+export interface ContainerOutboundInboundGate {
+  inboundId: string
+  inboundCode: string
+  gate: {
+    passed: boolean
+    items: ContainerOutboundGateItem[]
+    checkedAt: string
+  }
+}
+
+export interface ContainerOutboundGateResult {
+  passed: boolean
+  inbounds: ContainerOutboundInboundGate[]
+  checkedAt: string
+}
+
+export interface ContainerOutboundInboundBinding {
+  orderId: string
+  orderNo: string
+  inboundId: string
+  inboundCode: string
+  tenantId: string
+  customerId?: string | null
+  customerName?: string | null
+  inboundStatus: string
+  pickTaskId?: string | null
+  pickTaskStatus?: string | null
+}
+
+export interface ContainerOutboundAggregate {
+  containerBookingId: string
+  cabinetNo: string
+  containerNo?: string | null
+  loadingPlanId: string
+  loadingPlanStatus: string
+  oceanBookingId?: string | null
+  oceanBookingStatus?: string | null
+  truckAppointmentId?: string | null
+  truckAppointmentStatus?: string | null
+  dispatchStatus: string
+  version: number
+  inbounds: ContainerOutboundInboundBinding[]
+  gate: ContainerOutboundGateResult
+}
+
+export interface ContainerOutboundDispatchDetail {
+  aggregate: ContainerOutboundAggregate
+  timeline: Array<{
+    module: string
+    action: string
+    fromStatus?: string | null
+    toStatus?: string | null
+    operatorId?: string | null
+    operatorName?: string | null
+    remark?: string | null
+    occurredAt: string
+  }>
+}
+
+export interface ContainerOutboundActionRequest {
+  expectedVersion: number
+  remark?: string
+}
diff --git a/src/modules/overseas-business/CONTRACT_GAPS.md b/src/modules/overseas-business/CONTRACT_GAPS.md
new file mode 100644
index 00000000..2c36e5c6
--- /dev/null
+++ b/src/modules/overseas-business/CONTRACT_GAPS.md
@@ -0,0 +1,19 @@
+# 海外业务真实接口契约
+
+模块通过 `@/shared/api/overseasHttp` 访问海外 Gateway，业务路径只传 `/platform/v1/...`。页面不读取 Token、不调用兑换端点，也不感知区域 Base。
+
+当前已接入：
+
+- 海外采购：客户候选、采购仓候选、列表、详情操作流水及 `PATCH` 三态编辑；缺失字段不修改，显式 `null` 清空。
+- 采购审核 `review`：采购详情页只对待审核订单和独立审核权限开放，提交订单版本、通过/拒绝决定、稳定幂等键和可选备注。
+- 本土卡车：平台列表、详情、创建和仅待审核状态允许的普通编辑。
+- 本土散板：独立稳定子域的列表、详情数据承载、创建和仅待接单状态允许的编辑；详情只用于既有编辑页预填，不新增详情路由。
+- canonical 权限统一为 `platform:overseas-business:*`；长整型 ID 与 decimal 字段在适配层归一化。
+
+明确不接入：
+
+- 采购出库不提供独立 `/outbounds` 端点；采购编辑通过出库明细维护出库量并派生待出库、部分出库、全部出库状态，不直接操作海外仓 PDA 可用库存。
+- 卡车状态推进、收托盘和散板状态推进：后端存在，但当前原型没有对应操作承载方式。
+- 海外出库、海外派送和 Merchant API。
+
+剩余验收项仅为真实 Gateway/Token 环境 HTTP 验收及 `1920×1080`、浏览器缩放 `100%` 的人工页面操作和截图确认。
diff --git a/src/modules/overseas-business/PROTOTYPE_MATRIX.md b/src/modules/overseas-business/PROTOTYPE_MATRIX.md
new file mode 100644
index 00000000..70cef489
--- /dev/null
+++ b/src/modules/overseas-business/PROTOTYPE_MATRIX.md
@@ -0,0 +1,21 @@
+# 海外业务原型核对矩阵
+
+原型来源：`docs/悦/货代SAAS平台后台/prototype-src/modules/07-overseas-business.html`；按钮函数来源：同原型目录 `prototype-src/app.js`。
+
+| 页面 | 操作 | 原型证据 | 原型承载方式 | 冻结结论 |
+|---|---|---|---|---|
+| 海外采购订单 | 列表/筛选 | `page-overseas-purchase` 2–12 行；海外面板 9–11 行；`renderOverseasPurchaseList()` 13531–13534 行 | 独立列表页，订单编号/采购品类/商品名称筛选 | 仅实现海外面板；国内页与 `domestic-*` 全部排除；操作列第一列；真实联调补充后端客户候选筛选 |
+| 海外采购订单 | 详情 | `page-overseas-purchase-detail` 204–206 行；`showOverseasPurchaseDetail()` 13538–13540 行 | 独立详情页，商品/库存/订单/快递/进销存五分区 | 建立正式详情路由，详情复用 `purchase:list` |
+| 海外采购订单 | 编辑 | `page-overseas-purchase-edit` 143–150 行；`editOverseasPurchase()`、`saveOverseasPurchaseEdit()` 13536–13537 行 | 独立编辑页 | 建立正式编辑路由，使用独立 `purchase:edit` 权限 |
+| 海外采购订单 | 审核 | 原型未定义；当前对话明确要求按后端既有审核契约补齐前端 | 详情页顶部操作 + 居中确认弹框 | 仅待审核订单且具备 `purchase:review` 权限展示；提交版本、通过/拒绝决定、稳定幂等键及可选备注 |
+| 海外采购订单 | 新增 | 14–15 行明确“历史新增表单仅保留为不可达模板” | 不可达 | 不建立新增入口或路由 |
+| 本土卡车 | 列表 | `page-overseas-truck` 58–80 行；`renderTruckOrderList()` 13550–13566 行 | 独立列表页 | 正式列表；操作列按根规则移到第一列 |
+| 本土卡车 | 新增 | `page-overseas-truck-add` 83–130 行；`saveTruckOrder()` 13567–13579 行 | 独立页面 | 建立正式新增路由；使用平台创建接口真实提交并显式选择客户 |
+| 本土卡车 | 编辑 | `page-overseas-truck-edit` 313–362 行；`editTruckOrder()`、`saveTruckOrderEdit()` 13630–13674 行 | 独立页面 | 建立正式编辑路由；仅 `PENDING_REVIEW` 可真实提交 |
+| 本土卡车 | 详情 | 列表渲染函数 13563 行仅提示“详情开发中” | 原型未定义 | 不建立详情路由 |
+| 本土散板 | 列表 | `page-overseas-looseboard` 222–244 行；`renderLooseboardList()` 13589–13605 行 | 独立列表页 | 正式列表；操作列按根规则移到第一列 |
+| 本土散板 | 新增 | `page-overseas-looseboard-add` 247–310 行；`saveLooseboardOrder()` 13606–13622 行 | 独立页面 | 建立正式新增路由；使用独立稳定子域真实提交并显式选择客户 |
+| 本土散板 | 编辑 | `page-overseas-looseboard-edit` 365–430 行；`editLooseboardOrder()`、`saveLooseboardOrderEdit()` 13676–13726 行 | 独立页面 | 建立正式编辑路由；仅 `PENDING_ACCEPTANCE` 可真实提交 |
+| 本土散板 | 详情 | 列表渲染函数 13602 行仅提示“详情开发中” | 原型未定义 | 不建立详情路由 |
+
+删除和文件预览在三类正式页面中均未定义，不自行补充承载方式；海外采购审核按当前对话确认的承载方式实现。
diff --git a/src/modules/overseas-business/api/platformOverseasBusiness.test.ts b/src/modules/overseas-business/api/platformOverseasBusiness.test.ts
new file mode 100644
index 00000000..1a683b83
--- /dev/null
+++ b/src/modules/overseas-business/api/platformOverseasBusiness.test.ts
@@ -0,0 +1,110 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const overseas = vi.hoisted(() => ({ get: vi.fn(), patch: vi.fn(), post: vi.fn(), put: vi.fn() }))
+vi.mock('@/shared/api/overseasHttp', () => ({ overseasHttp: overseas }))
+
+import {
+  createLocalLooseboardOrder, createUsTruckOrder, getLocalLooseboardOrder, getOverseasPurchase, getUsTruckOrder,
+  listLocalLooseboardOrders, listOverseasPurchaseCustomerOptions, listOverseasPurchases,
+  listOverseasPurchaseWarehouseOptions, listUsTruckOrders, reviewOverseasPurchase, updateLocalLooseboardOrder, updateOverseasPurchase,
+  updateUsTruckOrder,
+} from './platformOverseasBusiness'
+import type { UpdateLocalTransportOrderRequest } from '../types'
+
+const envelope = <T>(data: T) => ({ code: '200', message: 'success', data })
+const purchaseSummary = {
+  id: '9007199254740993', orderNo: 'OP-1', customerId: '10001', customerName: '客户一', purchaseCategory: '服装', productName: '外套',
+  productSpecification: null, purchaseQuantity: 10, budgetUnitPrice: 12.34, currency: 'USD', purchaseWarehouseId: '9007199254740995',
+  purchaseWarehouseName: '采购仓', inboundQuantity: 5, outboundQuantity: 0, inventoryQuantity: 5, status: 'PENDING_OUTBOUND', version: 4,
+  createdAt: '2026-08-01T00:00:00', updatedAt: '2026-08-02T00:00:00',
+}
+const truckSummary = {
+  id: '9007199254740997', customerId: '10002', orderNo: 'TR-1', transportType: 'PORT_PICKUP', origin: 'LA', destination: 'ONT',
+  containerType: '40HQ', palletCount: 2, packageCount: 10, receivedPalletCount: 1, allocatedPalletCount: 0, shippedPalletCount: 0,
+  totalWeightKg: 123.45, totalVolumeCbm: 6.7, budgetAmount: 88.5, currency: 'USD', contactName: 'A', contactInfo: '1',
+  requestedDate: '2026-08-20', status: 'PENDING_REVIEW', version: 2, createdAt: '2026-08-01T00:00:00', updatedAt: '2026-08-02T00:00:00',
+}
+const looseboardSummary = {
+  id: '9007199254741005', customerId: '10003', orderNo: 'LB-1', transportMode: 'SHARED_TRUCK', palletRequired: 'YES', transportType: 'WAREHOUSE_TO_WAREHOUSE',
+  origin: 'LA', destination: 'ONT', containerType: null, packageCount: 8, totalWeightKg: 80.5, totalVolumeCbm: 3.2,
+  budgetAmount: 50, currency: 'USD', contactName: null, contactInfo: null, requestedDate: null, status: 'PENDING_ACCEPTANCE', version: 0,
+  createdAt: '2026-08-01T00:00:00', updatedAt: '2026-08-01T00:00:00',
+}
+
+describe('platform overseas business API adapter', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it('loads procurement candidates and normalizes procurement pages', async () => {
+    overseas.get
+      .mockResolvedValueOnce(envelope([{ customerId: '10001', customerName: '客户一' }]))
+      .mockResolvedValueOnce(envelope([{ warehouseId: '9007199254740995', warehouseCode: 'LAX', warehouseName: '采购仓', countryCode: 'US' }]))
+      .mockResolvedValueOnce(envelope({ records: [purchaseSummary], page: 1, size: 20, total: 1, pages: 1 }))
+    expect(await listOverseasPurchaseCustomerOptions(' 客户 ', 50)).toEqual([{ customerId: '10001', customerName: '客户一' }])
+    expect(overseas.get).toHaveBeenNthCalledWith(1, '/platform/v1/last-leg/overseas-procurements/customer-options', { params: { keyword: '客户', limit: 50 } })
+    expect((await listOverseasPurchaseWarehouseOptions())[0]?.warehouseId).toBe('9007199254740995')
+    const result = await listOverseasPurchases({ page: 1, size: 20, customerId: '10001', orderNo: ' OP-1 ', purchaseWarehouseId: '9007199254740995' })
+    expect(overseas.get).toHaveBeenNthCalledWith(3, '/platform/v1/last-leg/overseas-procurements', { params: expect.objectContaining({ page: 1, size: 20, customerId: '10001', orderNo: 'OP-1', purchaseWarehouseId: '9007199254740995' }) })
+    expect(result.records[0]).toMatchObject({ id: '9007199254740993', purchaseWarehouseId: '9007199254740995', budgetUnitPrice: '12.34' })
+  })
+
+  it('loads and patches procurement detail with three-state null payloads', async () => {
+    const detail = { summary: purchaseSummary, productUrl: null, histories: [{ operationType: 'UPDATE', fromStatus: 'APPROVED', toStatus: 'APPROVED', operatorId: '7', changeDetail: '{}', remark: null, createdAt: '2026-08-02T00:00:00' }] }
+    overseas.get.mockResolvedValue(envelope(detail))
+    expect((await getOverseasPurchase('OP/1', '10001')).histories[0]?.operationType).toBe('UPDATE')
+    overseas.patch.mockResolvedValue(envelope(detail))
+    const payload = { version: 4, productUrl: null, estimatedArrivalAt: null }
+    await updateOverseasPurchase('OP-1', '10001', payload)
+    expect(overseas.patch).toHaveBeenCalledWith('/platform/v1/last-leg/overseas-procurements/OP-1', payload, { params: { customerId: '10001' } })
+  })
+
+  it('submits procurement review with version and idempotency data', async () => {
+    const detail = { summary: { ...purchaseSummary, status: 'APPROVED', version: 5 }, histories: [] }
+    overseas.post.mockResolvedValue(envelope(detail))
+    const payload = { version: 4, decision: 'APPROVE' as const, idempotencyKey: 'review-key', remark: '资料齐全' }
+    const result = await reviewOverseasPurchase('OP/1', '10001', payload)
+    expect(overseas.post).toHaveBeenCalledWith('/platform/v1/last-leg/overseas-procurements/OP%2F1/review', payload, { params: { customerId: '10001' } })
+    expect(result.status).toBe('APPROVED')
+    expect(result.version).toBe(5)
+  })
+
+  it('supports platform truck list/detail/create/update without status endpoints', async () => {
+    const detail = { summary: truckSummary, pallets: [{ id: '9007199254741001', warehousePalletId: '9007199254741003', palletNo: 'P-1' }], histories: [] }
+    overseas.get.mockResolvedValueOnce(envelope({ records: [truckSummary], page: '1', size: '20', total: '1', pages: '1' })).mockResolvedValueOnce(envelope(detail))
+    expect((await listUsTruckOrders({ routeKeyword: ' LA ' })).records[0]?.totalWeightKg).toBe('123.45')
+    expect((await getUsTruckOrder('TR-1', '10002')).pallets[0]?.warehousePalletId).toBe('9007199254741003')
+    const create = { transportType: 'PORT_PICKUP' as const, origin: 'LA', destination: 'ONT', palletCount: 2, packageCount: 10, totalWeightKg: 123.45, totalVolumeCbm: 6.7, contactName: 'A', contactInfo: '1', requestedDate: '2026-08-20', idempotencyKey: 'HTTP-20260824-MARKER-truck' }
+    overseas.post.mockResolvedValue(envelope(detail)); await createUsTruckOrder('9007199254741999', create)
+    expect(overseas.post).toHaveBeenCalledWith('/platform/v1/last-leg/us-truck-orders', create, { params: { customerId: '9007199254741999' } })
+    const { idempotencyKey: _truckKey, ...truckFields } = create
+    const update = { ...truckFields, version: 2 }
+    overseas.patch.mockResolvedValue(envelope(detail)); await updateUsTruckOrder('TR-1', '9007199254741999', update)
+    expect(overseas.patch).toHaveBeenCalledWith('/platform/v1/last-leg/us-truck-orders/TR-1', update, { params: { customerId: '9007199254741999' } })
+  })
+
+  it('supports looseboard list/detail/create and PUT update', async () => {
+    const detail = { summary: looseboardSummary, originAddress: null, destinationAddress: null, remark: null, createdBy: '7', histories: [] }
+    overseas.get.mockResolvedValueOnce(envelope({ records: [looseboardSummary], page: 1, size: 20, total: 1, pages: 1 })).mockResolvedValueOnce(envelope(detail))
+    expect((await listLocalLooseboardOrders({ status: 'PENDING_ACCEPTANCE' })).records[0]?.id).toBe('9007199254741005')
+    expect((await getLocalLooseboardOrder('LB-1', '10003')).status).toBe('PENDING_ACCEPTANCE')
+    const create = { transportMode: 'SHARED_TRUCK' as const, palletRequired: 'YES' as const, transportType: 'WAREHOUSE_TO_WAREHOUSE' as const, origin: 'LA', destination: 'ONT', packageCount: 8, totalWeightKg: 80.5, totalVolumeCbm: 3.2, idempotencyKey: 'HTTP-20260824-MARKER-looseboard' }
+    overseas.post.mockResolvedValue(envelope(detail)); await createLocalLooseboardOrder('9007199254742001', create)
+    expect(overseas.post).toHaveBeenCalledWith('/platform/v1/last-leg/local-looseboard-orders', create, { params: { customerId: '9007199254742001' } })
+    const { idempotencyKey: _looseKey, ...looseboardFields } = create
+    const update = { ...looseboardFields, version: 0 }
+    overseas.put.mockResolvedValue(envelope(detail)); await updateLocalLooseboardOrder('LB/1', '9007199254742001', update)
+    expect(overseas.put).toHaveBeenCalledWith('/platform/v1/last-leg/local-looseboard-orders/LB%2F1', update, { params: { customerId: '9007199254742001' } })
+  })
+
+  it('propagates a 409 envelope without issuing any fallback write', async () => {
+    const payload: UpdateLocalTransportOrderRequest = {
+      version: 2, transportType: 'PORT_PICKUP', origin: 'LA', destination: 'ONT-EDIT', palletCount: 2,
+      packageCount: 10, totalWeightKg: 123.45, totalVolumeCbm: 6.7, contactName: 'A', contactInfo: '1',
+      requestedDate: '2026-08-20',
+    }
+    overseas.patch.mockResolvedValue({ code: 'B0409', message: 'Order was changed', data: null, requestId: 'REQ-409' })
+    await expect(updateUsTruckOrder('TR-1', '9007199254741999', payload)).rejects.toMatchObject({ code: 'B0409', requestId: 'REQ-409' })
+    expect(overseas.patch).toHaveBeenCalledTimes(1)
+    expect(overseas.post).not.toHaveBeenCalled()
+    expect(overseas.put).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/modules/overseas-business/api/platformOverseasBusiness.ts b/src/modules/overseas-business/api/platformOverseasBusiness.ts
new file mode 100644
index 00000000..e5df5822
--- /dev/null
+++ b/src/modules/overseas-business/api/platformOverseasBusiness.ts
@@ -0,0 +1,123 @@
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import type {
+  CreateLocalLooseboardOrderRequest, CreateLocalTransportOrderRequest, LocalLooseboardDetail, LocalLooseboardOrder,
+  LocalLooseboardQuery, LocalTransportDetail, LocalTransportOrder, LocalTransportPallet, LocalTransportQuery,
+  OverseasBusinessHistory, OverseasBusinessPage, OverseasPurchaseCustomerOption, OverseasPurchaseDetail,
+  OverseasPurchaseQuery, OverseasPurchaseSummary, OverseasPurchaseWarehouseOption, UpdateLocalLooseboardOrderRequest,
+  UpdateLocalTransportOrderRequest, UpdateOverseasPurchaseRequest, OverseasPurchaseOutboundDetail,
+  OverseasPurchaseFile, OverseasPurchaseFee, ReviewOverseasPurchaseRequest,
+} from '../types'
+
+const procurementBasePath = '/platform/v1/last-leg/overseas-procurements'
+const truckBasePath = '/platform/v1/last-leg/us-truck-orders'
+const looseboardBasePath = '/platform/v1/last-leg/local-looseboard-orders'
+type Numeric = number | string
+interface PagePayload<T> { records?: T[]; page: Numeric; size: Numeric; total: Numeric; pages: Numeric }
+interface ProcurementSummaryPayload extends Omit<OverseasPurchaseSummary, 'id' | 'purchaseWarehouseId' | 'budgetUnitPrice'> { id: Numeric; purchaseWarehouseId?: Numeric | null; budgetUnitPrice?: Numeric | null }
+interface ProcurementDetailPayload {
+  summary: ProcurementSummaryPayload; productUrl?: string | null; receivingAddress?: string | null
+  contactName?: string | null; contactPhone?: string | null; domesticCarrier?: string | null; domesticTrackingNo?: string | null
+  overseasCarrier?: string | null; overseasTrackingNo?: string | null; estimatedArrivalAt?: string | null; remark?: string | null
+  createdBy?: string | null; reviewedBy?: string | null; reviewRemark?: string | null; reviewedAt?: string | null
+  histories?: OverseasBusinessHistory[]; outboundDetails?: OverseasPurchaseOutboundDetail[]; files?: any[]; fees?: any[]
+}
+interface TruckSummaryPayload extends Omit<LocalTransportOrder, 'id' | 'budgetAmount' | 'totalWeightKg' | 'totalVolumeCbm'> { id: Numeric; budgetAmount?: Numeric | null; totalWeightKg: Numeric; totalVolumeCbm: Numeric }
+interface TruckPalletPayload extends Omit<LocalTransportPallet, 'id' | 'warehousePalletId'> { id: Numeric; warehousePalletId?: Numeric | null }
+interface TruckDetailPayload {
+  summary: TruckSummaryPayload; originAddress?: string | null; destinationAddress?: string | null
+  remark?: string | null; createdBy?: string | null; pallets?: TruckPalletPayload[]; histories?: OverseasBusinessHistory[]
+}
+interface LooseboardSummaryPayload extends Omit<LocalLooseboardOrder, 'id' | 'budgetAmount' | 'totalWeightKg' | 'totalVolumeCbm'> { id: Numeric; budgetAmount?: Numeric | null; totalWeightKg: Numeric; totalVolumeCbm: Numeric }
+interface LooseboardDetailPayload {
+  summary: LooseboardSummaryPayload; originAddress?: string | null; destinationAddress?: string | null
+  remark?: string | null; createdBy?: string | null; histories?: OverseasBusinessHistory[]
+}
+
+function normalizePage<TPayload, TResult>(payload: PagePayload<TPayload>, normalize: (value: TPayload) => TResult): OverseasBusinessPage<TResult> {
+  return { records: (payload.records || []).map(normalize), page: Number(payload.page), size: Number(payload.size), total: Number(payload.total), pages: Number(payload.pages) }
+}
+function procurementSummary(value: ProcurementSummaryPayload): OverseasPurchaseSummary {
+  return { ...value, id: String(value.id), purchaseWarehouseId: value.purchaseWarehouseId == null ? null : String(value.purchaseWarehouseId), budgetUnitPrice: value.budgetUnitPrice == null ? null : String(value.budgetUnitPrice) }
+}
+function procurementDetail(value: ProcurementDetailPayload): OverseasPurchaseDetail {
+  return { ...procurementSummary(value.summary), productUrl: value.productUrl || null, receivingAddress: value.receivingAddress || null, contactName: value.contactName || null, contactPhone: value.contactPhone || null, domesticCarrier: value.domesticCarrier || null, domesticTrackingNo: value.domesticTrackingNo || null, overseasCarrier: value.overseasCarrier || null, overseasTrackingNo: value.overseasTrackingNo || null, estimatedArrivalAt: value.estimatedArrivalAt || null, remark: value.remark || null, createdBy: value.createdBy || null, reviewedBy: value.reviewedBy || null, reviewRemark: value.reviewRemark || null, reviewedAt: value.reviewedAt || null, histories: value.histories || [], outboundDetails: (value.outboundDetails || []).map((item) => ({ ...item, id: String(item.id), quantity: Number(item.quantity) })), files: (value.files || []).map((item) => ({ ...item, id: String(item.id), fileId: String(item.fileId), sizeBytes: Number(item.sizeBytes) })), fees: (value.fees || []).map((item) => ({ ...item, id: String(item.id), voucherFileId: String(item.voucherFileId), amount: String(item.amount) })) }
+}
+function truckSummary(value: TruckSummaryPayload): LocalTransportOrder {
+  return { ...value, id: String(value.id), totalWeightKg: String(value.totalWeightKg), totalVolumeCbm: String(value.totalVolumeCbm), budgetAmount: value.budgetAmount == null ? null : String(value.budgetAmount) }
+}
+function truckDetail(value: TruckDetailPayload): LocalTransportDetail {
+  return { ...truckSummary(value.summary), originAddress: value.originAddress || null, destinationAddress: value.destinationAddress || null, remark: value.remark || null, createdBy: value.createdBy || null, pallets: (value.pallets || []).map((item) => ({ ...item, id: String(item.id), warehousePalletId: item.warehousePalletId == null ? null : String(item.warehousePalletId) })), histories: value.histories || [] }
+}
+function looseboardSummary(value: LooseboardSummaryPayload): LocalLooseboardOrder {
+  return { ...value, id: String(value.id), totalWeightKg: String(value.totalWeightKg), totalVolumeCbm: String(value.totalVolumeCbm), budgetAmount: value.budgetAmount == null ? null : String(value.budgetAmount) }
+}
+function looseboardDetail(value: LooseboardDetailPayload): LocalLooseboardDetail {
+  return { ...looseboardSummary(value.summary), originAddress: value.originAddress || null, destinationAddress: value.destinationAddress || null, remark: value.remark || null, createdBy: value.createdBy || null, histories: value.histories || [] }
+}
+
+export async function listOverseasPurchaseCustomerOptions(keyword = '', limit = 200) {
+  const response = await overseasHttp.get<ApiEnvelope<OverseasPurchaseCustomerOption[]>, ApiEnvelope<OverseasPurchaseCustomerOption[]>>(`${procurementBasePath}/customer-options`, { params: { keyword: keyword.trim() || undefined, limit } })
+  return unwrapApiResponse(response)
+}
+export async function listOverseasPurchaseWarehouseOptions() {
+  const response = await overseasHttp.get<ApiEnvelope<OverseasPurchaseWarehouseOption[]>, ApiEnvelope<OverseasPurchaseWarehouseOption[]>>(`${procurementBasePath}/warehouse-options`)
+  return unwrapApiResponse(response).map((item) => ({ ...item, warehouseId: String(item.warehouseId) }))
+}
+export async function listOverseasPurchases(query: OverseasPurchaseQuery = {}) {
+  const response = await overseasHttp.get<ApiEnvelope<PagePayload<ProcurementSummaryPayload>>, ApiEnvelope<PagePayload<ProcurementSummaryPayload>>>(procurementBasePath, { params: { ...query, customerId: query.customerId || undefined, orderNo: query.orderNo?.trim() || undefined, customerKeyword: query.customerKeyword?.trim() || undefined, purchaseCategory: query.purchaseCategory?.trim() || undefined, productName: query.productName?.trim() || undefined, status: query.status || undefined, purchaseWarehouseId: query.purchaseWarehouseId || undefined } })
+  return normalizePage(unwrapApiResponse(response), procurementSummary)
+}
+export async function getOverseasPurchase(orderNo: string, customerId: string) {
+  const response = await overseasHttp.get<ApiEnvelope<ProcurementDetailPayload>, ApiEnvelope<ProcurementDetailPayload>>(`${procurementBasePath}/${encodeURIComponent(orderNo)}`, { params: { customerId } })
+  return procurementDetail(unwrapApiResponse(response))
+}
+export async function updateOverseasPurchase(orderNo: string, customerId: string, payload: UpdateOverseasPurchaseRequest) {
+  const response = await overseasHttp.patch<ApiEnvelope<ProcurementDetailPayload>, ApiEnvelope<ProcurementDetailPayload>>(`${procurementBasePath}/${encodeURIComponent(orderNo)}`, payload, { params: { customerId } })
+  return procurementDetail(unwrapApiResponse(response))
+}
+export async function reviewOverseasPurchase(orderNo: string, customerId: string, payload: ReviewOverseasPurchaseRequest) {
+  const response = await overseasHttp.post<ApiEnvelope<ProcurementDetailPayload>, ApiEnvelope<ProcurementDetailPayload>>(`${procurementBasePath}/${encodeURIComponent(orderNo)}/review`, payload, { params: { customerId } })
+  return procurementDetail(unwrapApiResponse(response))
+}
+export async function uploadOverseasPurchaseFile(orderNo: string, customerId: string, category: 'RECEIPT' | 'VOUCHER', file: File) {
+  const body = new FormData(); body.append('file', file)
+  const response = await overseasHttp.post<ApiEnvelope<OverseasPurchaseFile>, ApiEnvelope<OverseasPurchaseFile>>(`${procurementBasePath}/${encodeURIComponent(orderNo)}/files/${category}`, body, { params: { customerId } })
+  return unwrapApiResponse(response)
+}
+export async function createOverseasPurchaseFee(orderNo: string, customerId: string, payload: { feeItemCode: string; feeItemName: string; amount: number; voucherFileId: string; remark?: string }) {
+  const response = await overseasHttp.post<ApiEnvelope<OverseasPurchaseFee>, ApiEnvelope<OverseasPurchaseFee>>(`${procurementBasePath}/${encodeURIComponent(orderNo)}/fees`, payload, { params: { customerId } })
+  return unwrapApiResponse(response)
+}
+export async function listUsTruckOrders(query: LocalTransportQuery = {}) {
+  const response = await overseasHttp.get<ApiEnvelope<PagePayload<TruckSummaryPayload>>, ApiEnvelope<PagePayload<TruckSummaryPayload>>>(truckBasePath, { params: { ...query, orderNo: query.orderNo?.trim() || undefined, routeKeyword: query.routeKeyword?.trim() || undefined, status: query.status || undefined, transportType: query.transportType || undefined, customerId: query.customerId || undefined } })
+  return normalizePage(unwrapApiResponse(response), truckSummary)
+}
+export async function getUsTruckOrder(orderNo: string, customerId: string) {
+  const response = await overseasHttp.get<ApiEnvelope<TruckDetailPayload>, ApiEnvelope<TruckDetailPayload>>(`${truckBasePath}/${encodeURIComponent(orderNo)}`, { params: { customerId } })
+  return truckDetail(unwrapApiResponse(response))
+}
+export async function createUsTruckOrder(customerId: string, payload: CreateLocalTransportOrderRequest) {
+  const response = await overseasHttp.post<ApiEnvelope<TruckDetailPayload>, ApiEnvelope<TruckDetailPayload>>(truckBasePath, payload, { params: { customerId } })
+  return truckDetail(unwrapApiResponse(response))
+}
+export async function updateUsTruckOrder(orderNo: string, customerId: string, payload: UpdateLocalTransportOrderRequest) {
+  const response = await overseasHttp.patch<ApiEnvelope<TruckDetailPayload>, ApiEnvelope<TruckDetailPayload>>(`${truckBasePath}/${encodeURIComponent(orderNo)}`, payload, { params: { customerId } })
+  return truckDetail(unwrapApiResponse(response))
+}
+export async function listLocalLooseboardOrders(query: LocalLooseboardQuery = {}) {
+  const response = await overseasHttp.get<ApiEnvelope<PagePayload<LooseboardSummaryPayload>>, ApiEnvelope<PagePayload<LooseboardSummaryPayload>>>(looseboardBasePath, { params: { ...query, customerId: query.customerId || undefined, orderNo: query.orderNo?.trim() || undefined, routeKeyword: query.routeKeyword?.trim() || undefined, status: query.status || undefined, transportMode: query.transportMode || undefined } })
+  return normalizePage(unwrapApiResponse(response), looseboardSummary)
+}
+export async function getLocalLooseboardOrder(orderNo: string, customerId: string) {
+  const response = await overseasHttp.get<ApiEnvelope<LooseboardDetailPayload>, ApiEnvelope<LooseboardDetailPayload>>(`${looseboardBasePath}/${encodeURIComponent(orderNo)}`, { params: { customerId } })
+  return looseboardDetail(unwrapApiResponse(response))
+}
+export async function createLocalLooseboardOrder(customerId: string, payload: CreateLocalLooseboardOrderRequest) {
+  const response = await overseasHttp.post<ApiEnvelope<LooseboardDetailPayload>, ApiEnvelope<LooseboardDetailPayload>>(looseboardBasePath, payload, { params: { customerId } })
+  return looseboardDetail(unwrapApiResponse(response))
+}
+export async function updateLocalLooseboardOrder(orderNo: string, customerId: string, payload: UpdateLocalLooseboardOrderRequest) {
+  const response = await overseasHttp.put<ApiEnvelope<LooseboardDetailPayload>, ApiEnvelope<LooseboardDetailPayload>>(`${looseboardBasePath}/${encodeURIComponent(orderNo)}`, payload, { params: { customerId } })
+  return looseboardDetail(unwrapApiResponse(response))
+}
diff --git a/src/modules/overseas-business/contract.test.ts b/src/modules/overseas-business/contract.test.ts
new file mode 100644
index 00000000..55d60820
--- /dev/null
+++ b/src/modules/overseas-business/contract.test.ts
@@ -0,0 +1,54 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const read = (path: string) => readFileSync(resolve(process.cwd(), `src/modules/overseas-business/${path}`), 'utf8')
+
+describe('overseas business real contract pages', () => {
+  it('keeps operation columns first and renders no sample records', () => {
+    const purchase = read('pages/PurchaseOrdersView.vue'); const transport = read('pages/TransportOrdersView.vue')
+    const purchaseColumns = purchase.slice(purchase.indexOf('const columns')); const truckColumns = transport.slice(transport.indexOf('const truckColumns')); const looseboardColumns = transport.slice(transport.indexOf('const looseboardColumns'))
+    expect(purchaseColumns.indexOf("key: 'actions'")).toBeLessThan(purchaseColumns.indexOf("key: 'orderNo'"))
+    expect(truckColumns.indexOf("key: 'actions'")).toBeLessThan(truckColumns.indexOf("key: 'orderNo'"))
+    expect(looseboardColumns.indexOf("key: 'actions'")).toBeLessThan(looseboardColumns.indexOf("key: 'orderNo'"))
+    expect(`${purchase}${transport}`).not.toMatch(/OPO\d|TK\d|LB\d/)
+  })
+
+  it('loads procurement candidates, operations and three-state PATCH fields', () => {
+    const list = read('pages/PurchaseOrdersView.vue'); const detail = read('pages/PurchaseOrderDetailView.vue'); const edit = read('pages/PurchaseOrderEditView.vue')
+    expect(list).toContain('listOverseasPurchaseCustomerOptions')
+    expect(edit).toContain('listOverseasPurchaseWarehouseOptions')
+    expect(detail).toContain('detail?.histories || []')
+    expect(detail).not.toContain('outbounds')
+    expect(edit).toContain('estimatedArrivalAt: form.estimatedArrivalAt || null')
+    expect(edit).toContain('purchaseWarehouseId: form.purchaseWarehouseId || null')
+    expect(edit).not.toContain('入库量不能小于 0')
+    expect(edit).not.toMatch(/payload[^\n]*(outboundQuantity|status):/)
+  })
+
+  it('uses only platform truck create/update and the stable looseboard subdomain', () => {
+    const api = read('api/platformOverseasBusiness.ts'); const list = read('pages/TransportOrdersView.vue'); const form = read('pages/TransportOrderFormView.vue')
+    expect(api).toContain("const looseboardBasePath = '/platform/v1/last-leg/local-looseboard-orders'")
+    expect(api).toContain('createUsTruckOrder')
+    expect(api).toContain('updateUsTruckOrder')
+    expect(api).toContain('createLocalLooseboardOrder')
+    expect(api).toContain('updateLocalLooseboardOrder')
+    expect(api).not.toMatch(/export async function createOverseasPurchase\s*\(/)
+    expect(api).not.toMatch(/\/merchant\/|receive-pallets|\/status/)
+    expect(list).toContain('listLocalLooseboardOrders')
+    expect(form).toContain('listPlatformTenants')
+    expect(form).not.toContain('ContractPendingNotice')
+  })
+
+  it('keeps state-constrained editing and unsaved-work protection', () => {
+    const purchaseEdit = read('pages/PurchaseOrderEditView.vue'); const transportList = read('pages/TransportOrdersView.vue'); const transportForm = read('pages/TransportOrderFormView.vue')
+    expect(purchaseEdit).toContain('useUnsavedWorkRegistration')
+    expect(transportForm).toContain('useUnsavedWorkRegistration')
+    expect(transportList).toContain("row.status === 'PENDING_ACCEPTANCE'")
+    expect(transportList).toContain("row.status === 'PENDING_REVIEW'")
+    expect(transportForm).toContain("form.status === 'PENDING_ACCEPTANCE'")
+    expect(transportForm).toContain("form.status === 'PENDING_REVIEW'")
+    expect(transportForm).toContain('idempotencyKey: form.idempotencyKey')
+    expect(transportForm.match(/idempotencyKey:\s*newIdempotencyKey\(\)/g)).toHaveLength(1)
+  })
+})
diff --git a/src/modules/overseas-business/index.ts b/src/modules/overseas-business/index.ts
new file mode 100644
index 00000000..50474d8e
--- /dev/null
+++ b/src/modules/overseas-business/index.ts
@@ -0,0 +1,3 @@
+export { overseasBusinessPermissions } from './permissions'
+export { overseasBusinessRoutes } from './routes'
+export type * from './types'
diff --git a/src/modules/overseas-business/overseasBusinessDensity.css b/src/modules/overseas-business/overseasBusinessDensity.css
new file mode 100644
index 00000000..7955c34f
--- /dev/null
+++ b/src/modules/overseas-business/overseasBusinessDensity.css
@@ -0,0 +1,11 @@
+/* Shared business form layout for purchase and local transport editors. */
+.admin-density.overseas-business-editor { width: 100%; max-width: 1120px; }
+.overseas-business-editor .overseas-business-form-layout { gap: 0; border: 1px solid var(--cc-border); border-radius: var(--admin-radius); background: var(--admin-surface); }
+.overseas-business-editor .form-reference { min-width: 0; color: var(--cc-muted); font-size: var(--admin-font-body); overflow-wrap: anywhere; }
+.overseas-business-editor .form-panel { min-width: 0; padding: var(--admin-space-5); }
+.overseas-business-editor .form-grid { display: grid; min-width: 0; gap: 0 var(--admin-space-5); }
+.overseas-business-editor .form-grid :is(.el-select, .el-date-editor, .el-input-number) { width: 100%; }
+.overseas-business-editor .form-grid small { display: block; margin-top: var(--admin-space-1); color: var(--cc-muted); font-size: var(--admin-font-caption); }
+.overseas-business-editor .field-error { display: block; margin-top: var(--admin-space-1); color: var(--el-color-danger); font-size: var(--admin-font-caption); }
+.overseas-business-editor .form-grid .field-error { color: var(--el-color-danger); }
+.overseas-business-editor .form-actions { display: flex; justify-content: flex-end; gap: var(--admin-space-3); padding-top: var(--admin-space-5); border-top: 1px solid var(--cc-border); }
diff --git a/src/modules/overseas-business/pages/OverseasBusinessViews.test.ts b/src/modules/overseas-business/pages/OverseasBusinessViews.test.ts
new file mode 100644
index 00000000..c4a65bca
--- /dev/null
+++ b/src/modules/overseas-business/pages/OverseasBusinessViews.test.ts
@@ -0,0 +1,125 @@
+import ElementPlus from 'element-plus'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { createPinia, setActivePinia } from 'pinia'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { ApiResponseError } from '@/shared/api/http'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+import { listPlatformTenants } from '@/modules/iam'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import type { LocalLooseboardDetail, LocalLooseboardOrder, LocalTransportDetail, LocalTransportOrder, OverseasPurchaseDetail } from '../types'
+import {
+  createOverseasPurchaseFee, uploadOverseasPurchaseFile, createLocalLooseboardOrder, createUsTruckOrder, getLocalLooseboardOrder, getOverseasPurchase, getUsTruckOrder,
+  listLocalLooseboardOrders, listOverseasPurchaseCustomerOptions, listOverseasPurchaseWarehouseOptions,
+  listOverseasPurchases, listUsTruckOrders, reviewOverseasPurchase, updateLocalLooseboardOrder, updateOverseasPurchase, updateUsTruckOrder,
+} from '../api/platformOverseasBusiness'
+import PurchaseOrdersView from './PurchaseOrdersView.vue'
+import PurchaseOrderDetailView from './PurchaseOrderDetailView.vue'
+import PurchaseOrderEditView from './PurchaseOrderEditView.vue'
+import TransportOrdersView from './TransportOrdersView.vue'
+import TransportOrderFormView from './TransportOrderFormView.vue'
+
+const purchaseListSource = readFileSync(resolve(process.cwd(), 'src/modules/overseas-business/pages/PurchaseOrdersView.vue'), 'utf8')
+const purchaseDetailSource = readFileSync(resolve(process.cwd(), 'src/modules/overseas-business/pages/PurchaseOrderDetailView.vue'), 'utf8')
+
+const routing = vi.hoisted(() => ({ push: vi.fn(), route: { params: {} as Record<string, string>, query: {} as Record<string, string> } }))
+vi.mock('vue-router', () => ({ useRoute: () => routing.route, useRouter: () => ({ push: routing.push }) }))
+vi.mock('@/modules/iam', () => ({ listPlatformTenants: vi.fn() }))
+vi.mock('../api/platformOverseasBusiness', () => ({
+  listOverseasPurchases: vi.fn(), getOverseasPurchase: vi.fn(), updateOverseasPurchase: vi.fn(), reviewOverseasPurchase: vi.fn(), uploadOverseasPurchaseFile: vi.fn(), createOverseasPurchaseFee: vi.fn(), listOverseasPurchaseCustomerOptions: vi.fn(), listOverseasPurchaseWarehouseOptions: vi.fn(),
+  listUsTruckOrders: vi.fn(), getUsTruckOrder: vi.fn(), createUsTruckOrder: vi.fn(), updateUsTruckOrder: vi.fn(),
+  listLocalLooseboardOrders: vi.fn(), getLocalLooseboardOrder: vi.fn(), createLocalLooseboardOrder: vi.fn(), updateLocalLooseboardOrder: vi.fn(),
+}))
+vi.mock('@/core/unsaved-work/useUnsavedWorkRegistration', () => ({ useUnsavedWorkRegistration: () => ({ captureBaseline: vi.fn() }) }))
+
+class ResizeObserverStub implements ResizeObserver { observe() {} unobserve() {} disconnect() {} }
+function memoryStorage(): Storage { const values = new Map<string, string>(); return { get length() { return values.size }, clear: () => values.clear(), getItem: (key) => values.get(key) ?? null, key: (index) => [...values.keys()][index] ?? null, removeItem: (key) => values.delete(key), setItem: (key, value) => values.set(key, value) } }
+
+const purchase: OverseasPurchaseDetail = {
+  id: '9007199254740993', orderNo: 'OP-100', customerId: '10001', customerName: '客户甲', purchaseCategory: '家居', productName: '置物架', productSpecification: '黑色', productUrl: 'https://example.test/product',
+  purchaseQuantity: 20, budgetUnitPrice: '12.50', currency: 'USD', purchaseWarehouseId: '20001', purchaseWarehouseName: '洛杉矶采购仓', inboundQuantity: 10, outboundQuantity: 0, inventoryQuantity: 10, status: 'PENDING_OUTBOUND', version: 3,
+  createdAt: '2026-08-01T10:00:00', updatedAt: '2026-08-02T10:00:00', receivingAddress: 'LA', contactName: 'Alice', contactPhone: '10086', domesticCarrier: null, domesticTrackingNo: null,
+  overseasCarrier: 'UPS', overseasTrackingNo: 'UPS-1', estimatedArrivalAt: '2026-08-25T12:00:00', remark: '采购备注', createdBy: '7', reviewedBy: '8', reviewRemark: null, reviewedAt: '2026-08-02T09:00:00',
+  histories: [{ operationType: 'UPDATE', fromStatus: 'APPROVED', toStatus: 'APPROVED', operatorId: 'INTERNAL-OPERATOR-7', changeDetail: '{"remark":"采购备注"}', remark: null, createdAt: '2026-08-02T10:00:00' }], files: [], fees: [],
+}
+const truck: LocalTransportOrder = { id: '9007199254740995', customerId: '10002', orderNo: 'TK-200', transportType: 'PORT_PICKUP', origin: 'Long Beach', destination: 'Ontario', containerType: '40HQ', palletCount: 2, packageCount: 20, receivedPalletCount: 0, allocatedPalletCount: 0, shippedPalletCount: 0, totalWeightKg: '1200.000', totalVolumeCbm: '16.500', budgetAmount: '850.00', currency: 'USD', contactName: 'Bob', contactInfo: '10010', requestedDate: '2026-08-28', status: 'PENDING_REVIEW', version: 1, createdAt: '2026-08-01T10:00:00', updatedAt: '2026-08-02T10:00:00' }
+const truckDetail: LocalTransportDetail = { ...truck, originAddress: 'Pier A', destinationAddress: 'Warehouse B', remark: null, createdBy: '7', pallets: [], histories: [] }
+const looseboard: LocalLooseboardOrder = { id: '9007199254740997', customerId: '10003', orderNo: 'LB-300', transportMode: 'SHARED_TRUCK', palletRequired: 'YES', transportType: 'WAREHOUSE_TO_WAREHOUSE', origin: 'LA', destination: 'ONT', containerType: '40HQ', packageCount: 8, totalWeightKg: '80.5', totalVolumeCbm: '3.2', budgetAmount: '50.00', currency: 'USD', contactName: null, contactInfo: null, requestedDate: null, status: 'PENDING_ACCEPTANCE', version: 0, createdAt: '2026-08-01T10:00:00', updatedAt: '2026-08-01T10:00:00' }
+const looseboardDetail: LocalLooseboardDetail = { ...looseboard, originAddress: null, destinationAddress: null, remark: null, createdBy: '7', histories: [] }
+
+function activatePermissions() { const pinia = createPinia(); setActivePinia(pinia); const auth = useAuthStore(); auth.token = 'test-token'; auth.permissions = ['platform:overseas-business:purchase:list', 'platform:overseas-business:purchase:edit', 'platform:overseas-business:purchase:review', 'platform:overseas-business:truck:list', 'platform:overseas-business:truck:create', 'platform:overseas-business:truck:edit', 'platform:overseas-business:looseboard:list', 'platform:overseas-business:looseboard:create', 'platform:overseas-business:looseboard:edit']; useAccessPreviewStore().initializeAfterLogin(); return pinia }
+function mountPage(component: Parameters<typeof mount>[0], props?: Record<string, unknown>) { const pinia = activatePermissions(); return mount(component, { attachTo: document.body, props, global: { plugins: [pinia, ElementPlus] } }) }
+enableAutoUnmount(afterEach); afterAll(() => vi.unstubAllGlobals())
+
+describe('overseas business mounted pages', () => {
+  beforeEach(() => {
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub); vi.stubGlobal('localStorage', memoryStorage()); vi.stubGlobal('sessionStorage', memoryStorage()); document.body.innerHTML = ''
+    routing.push.mockReset(); routing.route.params = {}; routing.route.query = {}
+    vi.mocked(listOverseasPurchases).mockReset().mockResolvedValue({ records: [purchase], page: 1, size: 20, total: 1, pages: 1 }); vi.mocked(getOverseasPurchase).mockReset().mockResolvedValue(purchase); vi.mocked(updateOverseasPurchase).mockReset().mockResolvedValue({ ...purchase, version: 4 }); vi.mocked(reviewOverseasPurchase).mockReset().mockResolvedValue({ ...purchase, status: 'APPROVED', version: 4 })
+    vi.mocked(listOverseasPurchaseCustomerOptions).mockReset().mockResolvedValue([{ customerId: '10001', customerName: '客户甲' }]); vi.mocked(listOverseasPurchaseWarehouseOptions).mockReset().mockResolvedValue([{ warehouseId: '20001', warehouseCode: 'LAX', warehouseName: '洛杉矶采购仓', countryCode: 'US' }])
+    vi.mocked(listUsTruckOrders).mockReset().mockResolvedValue({ records: [truck], page: 1, size: 20, total: 1, pages: 1 }); vi.mocked(getUsTruckOrder).mockReset().mockResolvedValue(truckDetail); vi.mocked(createUsTruckOrder).mockReset().mockResolvedValue(truckDetail); vi.mocked(updateUsTruckOrder).mockReset().mockResolvedValue(truckDetail)
+    vi.mocked(listLocalLooseboardOrders).mockReset().mockResolvedValue({ records: [looseboard], page: 1, size: 20, total: 1, pages: 1 }); vi.mocked(getLocalLooseboardOrder).mockReset().mockResolvedValue(looseboardDetail); vi.mocked(createLocalLooseboardOrder).mockReset().mockResolvedValue(looseboardDetail); vi.mocked(updateLocalLooseboardOrder).mockReset().mockResolvedValue(looseboardDetail)
+    vi.mocked(listPlatformTenants).mockReset().mockResolvedValue({ records: [{ id: '10001', tenantName: '可选客户', status: 'ACTIVE' } as never], page: 1, size: 200, total: 1, pages: 1 })
+  })
+
+
+  it('keeps all procurement facts in dense groups and business references in the heading', async () => {
+    routing.route.params = { purchaseId: 'internal-purchase-route' }; routing.route.query = { customerId: '10001' }
+    const wrapper = mountPage(PurchaseOrderDetailView)
+    await flushPromises()
+    expect(wrapper.get('.density-detail-title').text()).toBe('OP-100')
+    expect(wrapper.get('[aria-label="采购订单概览"]').text()).toContain('洛杉矶采购仓')
+    expect(wrapper.findAll('.density-fields')).toHaveLength(4)
+    expect(wrapper.findAll('.density-fields dt')).toHaveLength(23)
+    expect(wrapper.findAll('.density-fields .wide')).toHaveLength(4)
+    expect(wrapper.text()).not.toContain('internal-purchase-route')
+    await wrapper.get('.density-back').trigger('click')
+    expect(routing.push).toHaveBeenCalledWith({ name: 'overseas-business-purchases' })
+  })
+
+  it('retains the voucher upload and fee dialog workflow with teleported density', async () => {
+    routing.route.params = { purchaseId: 'OP-100' }; routing.route.query = { customerId: '10001' }
+    const voucher = { id: 'voucher-1', fileId: 'file-1', fileName: 'voucher.pdf', category: 'VOUCHER' as const, contentType: 'application/pdf', sizeBytes: 3, createdAt: '2026-09-14T10:00:00' }
+    vi.mocked(uploadOverseasPurchaseFile).mockReset().mockResolvedValue(voucher)
+    vi.mocked(createOverseasPurchaseFee).mockReset().mockResolvedValue({ id: 'fee-1', feeNo: 'FEE-1', feeItemCode: 'COURIER', feeItemName: '快递费', amount: '25', currency: 'CNY', voucherFileId: 'file-1', voucherFileName: 'voucher.pdf', remark: null, walletStatus: 'FREEZE_PENDING', walletErrorMessage: null, createdAt: '2026-09-14T10:00:00' })
+    const wrapper = mountPage(PurchaseOrderDetailView)
+    await flushPromises()
+    const input = wrapper.findAll('input[type="file"]')[1]!
+    const file = new File(['pdf'], 'voucher.pdf', { type: 'application/pdf' })
+    Object.defineProperty(input.element, 'files', { value: [file], configurable: true })
+    await input.trigger('change'); await flushPromises()
+    expect(uploadOverseasPurchaseFile).toHaveBeenCalledWith('OP-100', '10001', 'VOUCHER', file)
+    const dialog = wrapper.findAllComponents(AppDialog)[1]!
+    expect(dialog.props('modelValue')).toBe(true)
+    expect(document.querySelector('.admin-density-dialog .density-form')).not.toBeNull()
+    dialog.findComponent({ name: 'ElInputNumber' }).vm.$emit('update:modelValue', 25)
+    await wrapper.vm.$nextTick()
+    dialog.vm.$emit('confirm'); await flushPromises()
+    expect(createOverseasPurchaseFee).toHaveBeenCalledWith('OP-100', '10001', expect.objectContaining({ amount: 25, voucherFileId: 'file-1' }))
+    expect(dialog.props('modelValue')).toBe(false)
+  })
+
+  it('mounts procurement list with customer candidates and real data', async () => { const wrapper = mountPage(PurchaseOrdersView); await flushPromises(); expect(listOverseasPurchaseCustomerOptions).toHaveBeenCalled(); expect(listOverseasPurchases).toHaveBeenCalledWith({ page: 1, size: 20, customerId: '', orderNo: '', purchaseCategory: '', productName: '' }); expect(wrapper.text()).toContain('OP-100'); expect(wrapper.text()).toContain('待出库'); expect(wrapper.text()).toContain('2026-08-01 10:00') })
+  it('refreshes the cached procurement list after returning from detail or edit', () => { expect(purchaseListSource).toContain('onActivated'); expect(purchaseListSource).toMatch(/onActivated\(\(\) => \{ if \(activatedOnce\) void load\(\)/) })
+  it('refreshes the cached procurement detail after an edit completes', () => { expect(purchaseDetailSource).toContain('onActivated'); expect(purchaseDetailSource).toMatch(/onActivated\(\(\) => \{ if \(activatedOnce\) void load\(\)/) })
+  it('paginates procurement results', async () => { vi.mocked(listOverseasPurchases).mockResolvedValue({ records: [purchase], page: 1, size: 20, total: 40, pages: 2 }); const wrapper = mountPage(PurchaseOrdersView); await flushPromises(); await wrapper.find('button[aria-label="第 2 页"]').trigger('click'); await flushPromises(); expect(listOverseasPurchases).toHaveBeenLastCalledWith(expect.objectContaining({ page: 2 })) })
+  it('renders procurement empty and traceable 403 states', async () => { vi.mocked(listOverseasPurchases).mockResolvedValueOnce({ records: [], page: 1, size: 20, total: 0, pages: 0 }); let wrapper = mountPage(PurchaseOrdersView); await flushPromises(); expect(wrapper.text()).toContain('暂无符合筛选条件的海外采购订单'); wrapper.unmount(); vi.mocked(listOverseasPurchases).mockRejectedValue(new ApiResponseError('forbidden', 'A0403', 403, null, 'REQ-403')); wrapper = mountPage(PurchaseOrdersView); await flushPromises(); expect(wrapper.text()).toContain('当前账号无权访问该数据'); expect(wrapper.text()).toContain('REQ-403') })
+  it('mounts procurement detail operation history without exposing internal operator ids', async () => { routing.route.params = { purchaseId: 'OP-100' }; routing.route.query = { customerId: '10001' }; const wrapper = mountPage(PurchaseOrderDetailView); await flushPromises(); expect(getOverseasPurchase).toHaveBeenCalledWith('OP-100', '10001'); expect(wrapper.text()).toContain('操作流水'); expect(wrapper.text()).toContain('编辑'); expect(wrapper.text()).not.toContain('INTERNAL-OPERATOR-7') })
+  it('reviews a pending procurement from its detail page', async () => { const pending = { ...purchase, status: 'PENDING_REVIEW' as const, inboundQuantity: 0, inventoryQuantity: 0, version: 2 }; routing.route.params = { purchaseId: 'OP-100' }; routing.route.query = { customerId: '10001' }; vi.mocked(getOverseasPurchase).mockResolvedValue(pending); vi.mocked(reviewOverseasPurchase).mockResolvedValue({ ...pending, status: 'APPROVED', version: 3 }); const wrapper = mountPage(PurchaseOrderDetailView); await flushPromises(); await wrapper.findAll('button').find((button) => button.text().includes('通过'))?.trigger('click'); await wrapper.vm.$nextTick(); const reviewDialog = wrapper.findAllComponents(AppDialog)[0]; expect(reviewDialog.props('modelValue')).toBe(true); reviewDialog.vm.$emit('confirm'); await flushPromises(); expect(reviewOverseasPurchase).toHaveBeenCalledWith('OP-100', '10001', expect.objectContaining({ version: 2, decision: 'APPROVE', idempotencyKey: expect.any(String) })); expect(wrapper.text()).toContain('已通过'); expect(wrapper.find('.header-actions').exists()).toBe(false); expect(wrapper.get('.density-back').text()).toBe('返回列表') })
+  it('submits procurement explicit null clears and keeps a 409 visible without local overwrite', async () => { routing.route.params = { purchaseId: 'OP-100' }; routing.route.query = { customerId: '10001' }; vi.mocked(updateOverseasPurchase).mockRejectedValue(new ApiResponseError('订单版本冲突，请刷新后重试', 'B0409', 409)); const wrapper = mountPage(PurchaseOrderEditView); await flushPromises(); const productUrl = wrapper.findAll('.el-form-item').find((item) => item.text().startsWith('商品链接'))!.find('input'); const domesticCarrier = wrapper.findAll('.el-form-item').find((item) => item.text().startsWith('国内承运商'))!.find('input'); await productUrl.setValue(''); await domesticCarrier.setValue(''); wrapper.findComponent({ name: 'ElSelect' }).vm.$emit('update:modelValue', null); wrapper.findComponent({ name: 'ElDatePicker' }).vm.$emit('update:modelValue', null); await wrapper.vm.$nextTick(); await wrapper.findAll('button').find((button) => button.text().trim() === '保存')?.trigger('click'); await flushPromises(); expect(updateOverseasPurchase).toHaveBeenCalledWith('OP-100', '10001', expect.objectContaining({ version: 3, productUrl: null, domesticCarrier: null, estimatedArrivalAt: null, purchaseWarehouseId: null })); expect(document.body.textContent).toContain('订单版本冲突，请刷新后重试'); expect((productUrl.element as HTMLInputElement).value).toBe(''); expect((domesticCarrier.element as HTMLInputElement).value).toBe(''); expect(routing.push).not.toHaveBeenCalled() })
+  it('keeps procurement list usable when customer candidates fail', async () => { vi.mocked(listOverseasPurchaseCustomerOptions).mockRejectedValue(new Error('candidate unavailable')); const wrapper = mountPage(PurchaseOrdersView); await flushPromises(); expect(listOverseasPurchases).toHaveBeenCalled(); expect(wrapper.text()).toContain('OP-100'); expect(wrapper.text()).not.toContain('candidate unavailable') })
+  it('loads procurement edit data but blocks unsafe warehouse selection when candidates fail', async () => { routing.route.params = { purchaseId: 'OP-100' }; routing.route.query = { customerId: '10001' }; vi.mocked(listOverseasPurchaseWarehouseOptions).mockRejectedValue(new Error('candidate unavailable')); const wrapper = mountPage(PurchaseOrderEditView); await flushPromises(); expect(getOverseasPurchase).toHaveBeenCalledWith('OP-100', '10001'); expect(wrapper.text()).toContain('采购仓候选加载失败'); expect(wrapper.text()).toContain('OP-100') })
+  it('mounts truck list with enabled create and supported types', async () => { const wrapper = mountPage(TransportOrdersView, { domain: 'truck' }); await flushPromises(); expect(listUsTruckOrders).toHaveBeenCalled(); expect(wrapper.text()).toContain('TK-200'); expect(wrapper.text()).toContain('港口提柜'); expect(wrapper.text()).toContain('2026-08-01 10:00'); expect(wrapper.findAll('button').find((button) => button.text().includes('新增订单'))?.attributes('disabled')).toBeUndefined() })
+  it('renders truck load failure without samples', async () => { vi.mocked(listUsTruckOrders).mockRejectedValue(new Error('hidden')); const wrapper = mountPage(TransportOrdersView, { domain: 'truck' }); await flushPromises(); expect(wrapper.text()).toContain('本土卡车订单加载失败'); expect(wrapper.text()).not.toContain('TK-200') })
+  it('loads and submits pending-review truck edit', async () => { routing.route.params = { orderId: 'TK-200' }; routing.route.query = { customerId: '10002' }; const wrapper = mountPage(TransportOrderFormView, { domain: 'truck' }); await flushPromises(); await wrapper.findAll('button').find((button) => button.text().includes('保存修改'))?.trigger('click'); await flushPromises(); expect(getUsTruckOrder).toHaveBeenCalledWith('TK-200', '10002'); expect(updateUsTruckOrder).toHaveBeenCalledWith('TK-200', '10002', expect.objectContaining({ version: 1, transportType: 'PORT_PICKUP', palletCount: 2 })) })
+  it('keeps truck edit form and version unchanged after a 409', async () => { routing.route.params = { orderId: 'TK-200' }; routing.route.query = { customerId: '10002' }; vi.mocked(updateUsTruckOrder).mockRejectedValue(new ApiResponseError('订单版本冲突', 'B0409', 409)); const wrapper = mountPage(TransportOrderFormView, { domain: 'truck' }); await flushPromises(); const destination = wrapper.find('input[placeholder="城市 / 州"]'); await destination.setValue('Ontario-MARKER-EDIT'); await wrapper.findAll('button').find((button) => button.text().includes('保存修改'))?.trigger('click'); await flushPromises(); expect(updateUsTruckOrder).toHaveBeenCalledWith('TK-200', '10002', expect.objectContaining({ version: 1, destination: 'Ontario-MARKER-EDIT' })); expect((destination.element as HTMLInputElement).value).toBe('Ontario-MARKER-EDIT'); expect(document.body.textContent).toContain('订单版本冲突'); expect(routing.push).not.toHaveBeenCalled() })
+  it('mounts truck create with explicit customer selector and enabled submit', async () => { const wrapper = mountPage(TransportOrderFormView, { domain: 'truck' }); await flushPromises(); expect(listPlatformTenants).toHaveBeenCalledWith({ page: 1, size: 200, status: 'ACTIVE' }); expect(wrapper.text()).toContain('客户信息'); expect(wrapper.text()).toContain('请选择客户'); expect(wrapper.findAll('button').find((button) => button.text().includes('提交订单'))?.attributes('disabled')).toBeUndefined() })
+  it('reuses one idempotency key and preserves truck create input after retries fail', async () => { vi.mocked(createUsTruckOrder).mockRejectedValue(new ApiResponseError('temporary failure', 'S0500', 500)); const wrapper = mountPage(TransportOrderFormView, { domain: 'truck' }); await flushPromises(); const selects = wrapper.findAllComponents({ name: 'ElSelect' }); selects[0].vm.$emit('update:modelValue', '10001'); wrapper.findComponent({ name: 'ElRadioGroup' }).vm.$emit('update:modelValue', 'PORT_PICKUP'); const origin = wrapper.find('input[placeholder="城市 / 港口 / 州"]'); const destination = wrapper.find('input[placeholder="城市 / 州"]'); await origin.setValue('LA-MARKER'); await destination.setValue('ONT-MARKER'); await wrapper.findAll('.el-form-item').find((item) => item.text().startsWith('联系人'))!.find('input').setValue('联系人'); await wrapper.findAll('.el-form-item').find((item) => item.text().startsWith('联系方式'))!.find('input').setValue('13800000000'); await wrapper.findAll('.el-form-item').find((item) => item.text().startsWith('总重量'))!.find('input').setValue('100'); await wrapper.findAll('.el-form-item').find((item) => item.text().startsWith('总体积'))!.find('input').setValue('2.5'); wrapper.findComponent({ name: 'ElDatePicker' }).vm.$emit('update:modelValue', '2026-08-31'); await wrapper.vm.$nextTick(); const submit = wrapper.findAll('button').find((button) => button.text().includes('提交订单')); await submit?.trigger('click'); await flushPromises(); await submit?.trigger('click'); await flushPromises(); expect(createUsTruckOrder).toHaveBeenCalledTimes(2); const keys = vi.mocked(createUsTruckOrder).mock.calls.map((call) => call[1].idempotencyKey); expect(keys[0]).toBeTruthy(); expect(keys[1]).toBe(keys[0]); expect((origin.element as HTMLInputElement).value).toBe('LA-MARKER'); expect((destination.element as HTMLInputElement).value).toBe('ONT-MARKER'); expect(document.body.textContent).toContain('服务暂时不可用'); expect(routing.push).not.toHaveBeenCalled() })
+  it('loads the real looseboard list', async () => { const wrapper = mountPage(TransportOrdersView, { domain: 'looseboard' }); await flushPromises(); expect(listLocalLooseboardOrders).toHaveBeenCalledWith({ page: 1, size: 20, routeKeyword: '', status: '' }); expect(wrapper.text()).toContain('LB-300'); expect(wrapper.text()).toContain('待接单'); expect(wrapper.text()).toContain('2026-08-01 10:00'); expect(listUsTruckOrders).not.toHaveBeenCalled() })
+  it('loads and submits pending-acceptance looseboard edit with PUT adapter', async () => { routing.route.params = { orderId: 'LB-300' }; routing.route.query = { customerId: '10003' }; const wrapper = mountPage(TransportOrderFormView, { domain: 'looseboard' }); await flushPromises(); await wrapper.findAll('button').find((button) => button.text().includes('保存修改'))?.trigger('click'); await flushPromises(); expect(getLocalLooseboardOrder).toHaveBeenCalledWith('LB-300', '10003'); expect(updateLocalLooseboardOrder).toHaveBeenCalledWith('LB-300', '10003', expect.objectContaining({ version: 0, transportMode: 'SHARED_TRUCK', palletRequired: 'YES' })) })
+  it('keeps looseboard edit form and version unchanged after a 409', async () => { routing.route.params = { orderId: 'LB-300' }; routing.route.query = { customerId: '10003' }; vi.mocked(updateLocalLooseboardOrder).mockRejectedValue(new ApiResponseError('订单版本冲突', 'B0409', 409)); const wrapper = mountPage(TransportOrderFormView, { domain: 'looseboard' }); await flushPromises(); const destination = wrapper.find('input[placeholder="城市 / 州"]'); await destination.setValue('ONT-MARKER-EDIT'); await wrapper.findAll('button').find((button) => button.text().includes('保存修改'))?.trigger('click'); await flushPromises(); expect(updateLocalLooseboardOrder).toHaveBeenCalledWith('LB-300', '10003', expect.objectContaining({ version: 0, destination: 'ONT-MARKER-EDIT' })); expect((destination.element as HTMLInputElement).value).toBe('ONT-MARKER-EDIT'); expect(document.body.textContent).toContain('订单版本冲突'); expect(routing.push).not.toHaveBeenCalled() })
+  it('mounts looseboard create without a detail route or pending notice', async () => { const wrapper = mountPage(TransportOrderFormView, { domain: 'looseboard' }); await flushPromises(); expect(wrapper.text()).toContain('客户信息'); expect(wrapper.text()).toContain('请选择客户'); expect(wrapper.text()).not.toContain('接口能力待后端补齐'); expect(wrapper.findAll('button').find((button) => button.text().includes('提交订单'))?.attributes('disabled')).toBeUndefined() })
+  it('reuses one idempotency key and preserves looseboard create input after retries fail', async () => { vi.mocked(createLocalLooseboardOrder).mockRejectedValue(new ApiResponseError('temporary failure', 'S0500', 500)); const wrapper = mountPage(TransportOrderFormView, { domain: 'looseboard' }); await flushPromises(); const selects = wrapper.findAllComponents({ name: 'ElSelect' }); selects[0].vm.$emit('update:modelValue', '10001'); const groups = wrapper.findAllComponents({ name: 'ElRadioGroup' }); groups[0].vm.$emit('update:modelValue', 'SHARED_TRUCK'); groups[1].vm.$emit('update:modelValue', 'YES'); groups[2].vm.$emit('update:modelValue', 'WAREHOUSE_TO_WAREHOUSE'); const origin = wrapper.find('input[placeholder="城市 / 港口 / 州"]'); const destination = wrapper.find('input[placeholder="城市 / 州"]'); await origin.setValue('LA-MARKER'); await destination.setValue('ONT-MARKER'); await wrapper.findAll('.el-form-item').find((item) => item.text().startsWith('总重量'))!.find('input').setValue('80'); await wrapper.findAll('.el-form-item').find((item) => item.text().startsWith('总体积'))!.find('input').setValue('1.8'); await wrapper.vm.$nextTick(); const submit = wrapper.findAll('button').find((button) => button.text().includes('提交订单')); await submit?.trigger('click'); await flushPromises(); await submit?.trigger('click'); await flushPromises(); expect(createLocalLooseboardOrder).toHaveBeenCalledTimes(2); const keys = vi.mocked(createLocalLooseboardOrder).mock.calls.map((call) => call[1].idempotencyKey); expect(keys[0]).toBeTruthy(); expect(keys[1]).toBe(keys[0]); expect((origin.element as HTMLInputElement).value).toBe('LA-MARKER'); expect((destination.element as HTMLInputElement).value).toBe('ONT-MARKER'); expect(routing.push).not.toHaveBeenCalled() })
+})
diff --git a/src/modules/overseas-business/pages/PurchaseOrderDetailView.vue b/src/modules/overseas-business/pages/PurchaseOrderDetailView.vue
new file mode 100644
index 00000000..f6745f59
--- /dev/null
+++ b/src/modules/overseas-business/pages/PurchaseOrderDetailView.vue
@@ -0,0 +1,136 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onActivated, reactive, ref, watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { ArrowLeft, Check, Upload, X } from '@lucide/vue'
+import { ElMessage } from 'element-plus'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import DetailPageLayout from '@/shared/components/DetailPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { createOverseasPurchaseFee, getOverseasPurchase, reviewOverseasPurchase, uploadOverseasPurchaseFile } from '../api/platformOverseasBusiness'
+import { overseasBusinessPermissions } from '../permissions'
+import type { OverseasBusinessHistory, OverseasPurchaseDetail, OverseasPurchaseFile, OverseasPurchaseFee, OverseasPurchaseStatus } from '../types'
+
+const route = useRoute(); const router = useRouter()
+const access = useAccessPreviewStore()
+const purchaseId = computed(() => typeof route.params.purchaseId === 'string' ? route.params.purchaseId : '')
+const customerId = computed(() => typeof route.query.customerId === 'string' ? route.query.customerId : '')
+const detail = ref<OverseasPurchaseDetail | null>(null); const loading = ref(false); const loadError = ref<ApiErrorDetails | null>(null)
+const statusLabels: Record<OverseasPurchaseStatus, string> = { PENDING_REVIEW: '待审核', APPROVED: '已通过', REJECTED: '已拒绝', PENDING_OUTBOUND: '待出库', PARTIALLY_OUTBOUND: '部分出库', OUTBOUNDED: '全部出库' }
+const productFields = computed(() => [['客户名称', detail.value?.customerName], ['采购仓库', detail.value?.purchaseWarehouseName], ['采购品类', detail.value?.purchaseCategory], ['商品名称', detail.value?.productName], ['商品规格', detail.value?.productSpecification], ['商品链接', detail.value?.productUrl]] as const)
+const stockFields = computed(() => [['入库量', detail.value?.inboundQuantity], ['出库量', detail.value?.outboundQuantity], ['库存量', detail.value?.inventoryQuantity], ['库存状态', detail.value ? (detail.value.inventoryQuantity > 0 ? '在库' : '无库存') : null]] as const)
+const orderFields = computed(() => [['订单编号', detail.value?.orderNo], ['采购数量', detail.value?.purchaseQuantity], ['预算单价', detail.value ? formatAmount(detail.value.budgetUnitPrice, detail.value.currency) : null], ['订单状态', detail.value ? statusLabels[detail.value.status] : null], ['联系人', detail.value?.contactName], ['联系电话', detail.value?.contactPhone], ['收货地址', detail.value?.receivingAddress], ['订单备注', detail.value?.remark]] as const)
+const courierFields = computed(() => [['国内承运商', detail.value?.domesticCarrier], ['国内运单号', detail.value?.domesticTrackingNo], ['海外承运商', detail.value?.overseasCarrier], ['海外运单号', detail.value?.overseasTrackingNo], ['预计到达时间', formatDateTime(detail.value?.estimatedArrivalAt)]] as const)
+const outboundDetails = computed(() => detail.value?.outboundDetails || [])
+const receiptInput = ref<HTMLInputElement | null>(null); const voucherInput = ref<HTMLInputElement | null>(null)
+const uploading = ref(false); const feeDialogOpen = ref(false); const savingFee = ref(false); const voucher = ref<OverseasPurchaseFile | null>(null)
+const feeForm = reactive({ feeItemCode: 'COURIER', feeItemName: '快递费', amount: 0, remark: '' })
+const reviewDialogOpen = ref(false); const reviewing = ref(false); const reviewDecision = ref<'APPROVE' | 'REJECT'>('APPROVE'); const reviewRemark = ref(''); const reviewKey = ref('')
+const fileColumns: DataTableColumn[] = [{ key: 'category', label: '类型', width: 100, formatter: (row: OverseasPurchaseFile) => row.category === 'RECEIPT' ? '签收文件' : '费用凭证' }, { key: 'fileName', prop: 'fileName', label: '文件名', minWidth: 220 }, { key: 'createdAt', label: '上传时间', minWidth: 155, formatter: (row: OverseasPurchaseFile) => formatDateTime(row.createdAt) }]
+const feeColumns: DataTableColumn[] = [{ key: 'feeNo', prop: 'feeNo', label: '费用编号', minWidth: 170 }, { key: 'feeItemName', prop: 'feeItemName', label: '费用项', minWidth: 120 }, { key: 'amount', label: '金额', width: 120, formatter: (row: OverseasPurchaseFee) => formatAmount(row.amount, row.currency) }, { key: 'voucherFileName', prop: 'voucherFileName', label: '凭证', minWidth: 180 }, { key: 'walletStatus', label: '资金状态', minWidth: 130, formatter: (row: OverseasPurchaseFee) => walletStatus(row.walletStatus) }, { key: 'walletErrorMessage', label: '异常说明', minWidth: 180, formatter: (row: OverseasPurchaseFee) => row.walletErrorMessage || '—' }]
+const historyColumns: DataTableColumn[] = [
+  { key: 'createdAt', label: '时间', minWidth: 155, formatter: (row: OverseasBusinessHistory) => formatDateTime(row.createdAt) },
+  { key: 'operationType', label: '操作类型', width: 110, formatter: (row: OverseasBusinessHistory) => operationLabels[row.operationType || ''] || row.operationType || '—' },
+  { key: 'status', label: '状态变化', minWidth: 150, formatter: (row: OverseasBusinessHistory) => row.fromStatus ? `${statusLabel(row.fromStatus)} → ${statusLabel(row.toStatus)}` : statusLabel(row.toStatus) },
+  { key: 'changeDetail', prop: 'changeDetail', label: '变更明细', minWidth: 260 },
+  { key: 'operator', label: '操作人', minWidth: 120, formatter: () => '—' },
+  { key: 'remark', prop: 'remark', label: '备注', minWidth: 180 },
+]
+const operationLabels: Record<string, string> = { CREATE: '创建', REVIEW: '审核', UPDATE: '编辑' }
+function statusLabel(status?: string | null) { return status ? (statusLabels[status as OverseasPurchaseStatus] || status) : '—' }
+function display(value: unknown) { return value === null || value === undefined || value === '' ? '—' : String(value) }
+function formatDateTime(value?: string | null) { return value ? value.replace('T', ' ').slice(0, 16) : '—' }
+function formatAmount(value: string | null, currency: string) { return value == null ? '—' : `${Number(value).toLocaleString('zh-CN', { minimumFractionDigits: 2, maximumFractionDigits: 2 })} ${currency}` }
+function walletStatus(value: string) { return ({ FREEZE_PENDING: '冻结中', FROZEN: '已冻结', SETTLE_PENDING: '结算中', SETTLED: '已结算', RELEASE_PENDING: '释放中', RELEASED: '已释放', FREEZE_FAILED: '冻结失败', SETTLE_FAILED: '结算失败', RELEASE_FAILED: '释放失败' } as Record<string,string>)[value] || value }
+function idempotencyKey() { return globalThis.crypto?.randomUUID?.() || `purchase-review-${Date.now()}-${Math.random().toString(16).slice(2)}` }
+function openReview(decision: 'APPROVE' | 'REJECT') {
+  reviewDecision.value = decision; reviewRemark.value = ''; reviewKey.value = idempotencyKey(); reviewDialogOpen.value = true
+}
+function closeReview() {
+  if (reviewing.value) return
+  reviewDialogOpen.value = false; reviewRemark.value = ''; reviewKey.value = ''
+}
+async function submitReview() {
+  if (!detail.value) return
+  reviewing.value = true
+  try {
+    detail.value = await reviewOverseasPurchase(detail.value.orderNo, customerId.value, {
+      version: detail.value.version,
+      decision: reviewDecision.value,
+      idempotencyKey: reviewKey.value || (reviewKey.value = idempotencyKey()),
+      remark: reviewRemark.value.trim() || undefined,
+    })
+    reviewDialogOpen.value = false; reviewRemark.value = ''; reviewKey.value = ''
+    ElMessage.success(reviewDecision.value === 'APPROVE' ? '采购订单审核已通过' : '采购订单已拒绝')
+  } catch (error) { ElMessage.error(getApiErrorDetails(error, '采购订单审核失败').message) }
+  finally { reviewing.value = false }
+}
+async function upload(category: 'RECEIPT' | 'VOUCHER', event: Event) {
+  const input = event.target as HTMLInputElement; const file = input.files?.[0]; input.value = ''
+  if (!file || !detail.value) return
+  uploading.value = true
+  try { const saved = await uploadOverseasPurchaseFile(detail.value.orderNo, customerId.value, category, file); if (category === 'VOUCHER') { voucher.value = saved; feeDialogOpen.value = true } else { ElMessage.success('签收文件已上传'); await load() } }
+  catch (error) { ElMessage.error(getApiErrorDetails(error, '文件上传失败').message) } finally { uploading.value = false }
+}
+async function saveFee() {
+  if (!detail.value || !voucher.value || feeForm.amount <= 0 || !feeForm.feeItemName.trim()) { ElMessage.warning('请填写正确的费用名称和金额'); return }
+  savingFee.value = true
+  try { await createOverseasPurchaseFee(detail.value.orderNo, customerId.value, { feeItemCode: feeForm.feeItemCode.trim(), feeItemName: feeForm.feeItemName.trim(), amount: feeForm.amount, voucherFileId: voucher.value.fileId, remark: feeForm.remark.trim() || undefined }); feeDialogOpen.value = false; voucher.value = null; ElMessage.success('费用已登记并提交资金冻结'); await load() }
+  catch (error) { ElMessage.error(getApiErrorDetails(error, '费用登记失败').message) } finally { savingFee.value = false }
+}
+async function load() {
+  detail.value = null; loadError.value = null
+  if (!purchaseId.value || !customerId.value) { loadError.value = { message: '缺少采购订单号或客户标识，请从采购订单列表重新进入' }; return }
+  loading.value = true
+  try { detail.value = await getOverseasPurchase(purchaseId.value, customerId.value) } catch (error) { loadError.value = getApiErrorDetails(error, '海外采购订单详情加载失败') } finally { loading.value = false }
+}
+let activatedOnce = false
+watch([purchaseId, customerId], () => { void load() }, { immediate: true })
+onActivated(() => { if (activatedOnce) void load(); else activatedOnce = true })
+</script>
+
+<template>
+  <AdminPage class="admin-density"><DetailPageLayout class="purchase-detail" aria-label="海外采购订单详情">
+    <template #header>
+      <div class="density-detail-header">
+        <div class="density-detail-heading"><el-button link class="density-back" @click="router.push({ name: 'overseas-business-purchases' })"><ArrowLeft :size="16" />返回列表</el-button><h1 class="density-detail-title">{{ detail?.orderNo || '—' }}</h1><StatusBadge v-if="detail" :status="statusLabels[detail.status]" /></div>
+        <div v-if="detail?.status === 'PENDING_REVIEW' && access.can(overseasBusinessPermissions.purchaseReview)" class="header-actions"><el-button type="danger" plain @click="openReview('REJECT')"><X :size="16" />拒绝</el-button><el-button type="primary" @click="openReview('APPROVE')"><Check :size="16" />通过</el-button></div>
+      </div>
+    </template>
+    <template v-if="detail" #summary><dl class="density-detail-overview" aria-label="采购订单概览"><div><dt>客户</dt><dd>{{ display(detail.customerName) }}</dd></div><div><dt>采购仓库</dt><dd>{{ display(detail.purchaseWarehouseName) }}</dd></div><div><dt>采购数量</dt><dd>{{ display(detail.purchaseQuantity) }}</dd></div><div><dt>入库量</dt><dd>{{ display(detail.inboundQuantity) }}</dd></div><div><dt>出库量</dt><dd>{{ display(detail.outboundQuantity) }}</dd></div><div><dt>库存量</dt><dd>{{ display(detail.inventoryQuantity) }}</dd></div></dl></template>
+    <LoadErrorState v-if="loadError" title="采购订单详情暂时无法加载" :message="loadError.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="loadError" /></template></LoadErrorState>
+    <div v-else v-loading="loading" class="detail-surface">
+      <div class="detail-grid">
+        <section><h3>商品信息</h3><dl class="density-fields"><div v-for="field in productFields" :key="field[0]" :class="{ wide: ['商品规格', '商品链接', '收货地址', '订单备注'].includes(field[0]) }"><dt>{{ field[0] }}</dt><dd>{{ display(field[1]) }}</dd></div></dl></section>
+        <section><h3>库存信息</h3><dl class="density-fields"><div v-for="field in stockFields" :key="field[0]" :class="{ wide: ['商品规格', '商品链接', '收货地址', '订单备注'].includes(field[0]) }"><dt>{{ field[0] }}</dt><dd>{{ display(field[1]) }}</dd></div></dl></section>
+        <section><h3>订单信息</h3><dl class="density-fields"><div v-for="field in orderFields" :key="field[0]" :class="{ wide: ['商品规格', '商品链接', '收货地址', '订单备注'].includes(field[0]) }"><dt>{{ field[0] }}</dt><dd>{{ display(field[1]) }}</dd></div></dl></section>
+        <section><h3>快递信息</h3><dl class="density-fields"><div v-for="field in courierFields" :key="field[0]" :class="{ wide: ['商品规格', '商品链接', '收货地址', '订单备注'].includes(field[0]) }"><dt>{{ field[0] }}</dt><dd>{{ display(field[1]) }}</dd></div></dl></section>
+        <section class="full"><div class="section-heading"><h3>出库明细</h3><span>共 {{ outboundDetails.length }} 条，出库量 {{ outboundDetails.reduce((sum, item) => sum + item.quantity, 0) }}</span></div><DataTable :data="outboundDetails" :columns="[{ key: 'quantity', label: '出库数量', width: 110 }, { key: 'carrier', label: '承运商', minWidth: 140 }, { key: 'trackingNo', label: '运单号', minWidth: 160 }, { key: 'shippedAt', label: '出库时间', minWidth: 155, formatter: (row: any) => formatDateTime(row.shippedAt) }, { key: 'remark', label: '备注', minWidth: 180 }]" row-key="id" empty-text="暂无出库明细" /></section>
+        <section class="full"><div class="section-heading"><h3>签收文件与费用凭证</h3><div v-if="access.can(overseasBusinessPermissions.purchaseEdit)" class="section-actions"><input ref="receiptInput" hidden type="file" @change="upload('RECEIPT', $event)"><input ref="voucherInput" hidden type="file" @change="upload('VOUCHER', $event)"><el-button :loading="uploading" @click="receiptInput?.click()"><Upload :size="15" />上传签收文件</el-button><el-button type="primary" :loading="uploading" :disabled="!detail || ['PENDING_REVIEW', 'REJECTED'].includes(detail.status)" @click="voucherInput?.click()"><Upload :size="15" />登记费用</el-button></div></div><DataTable :data="detail?.files || []" :columns="fileColumns" row-key="id" empty-text="暂无签收文件或费用凭证" /></section>
+        <section class="full"><div class="section-heading"><h3>费用明细</h3><span>每条费用独立冻结，订单全部入库后结算。</span></div><DataTable :data="detail?.fees || []" :columns="feeColumns" row-key="id" empty-text="暂无费用明细" /></section>
+        <section class="full"><div class="section-heading"><h3>操作流水</h3><span>展示创建、审核、入库与出库明细变更。</span></div><DataTable :data="detail?.histories || []" :columns="historyColumns" row-key="createdAt" empty-text="暂无操作流水" /></section>
+      </div>
+    </div>
+  </DetailPageLayout><AppDialog class="admin-density-dialog" v-model="reviewDialogOpen" :title="reviewDecision === 'APPROVE' ? '通过采购订单' : '拒绝采购订单'" width="min(520px, calc(100vw - 28px))" :confirm-text="reviewDecision === 'APPROVE' ? '确认通过' : '确认拒绝'" :confirm-loading="reviewing" @confirm="submitReview" @cancel="closeReview"><el-alert :title="reviewDecision === 'APPROVE' ? '通过后平台可维护采购入库、出库和费用信息。' : '拒绝后该采购订单将结束审核流程。'" :type="reviewDecision === 'APPROVE' ? 'success' : 'warning'" show-icon :closable="false" /><p class="review-reference">订单编号：{{ detail?.orderNo || '—' }}</p><el-form class="density-form review-form" label-position="top"><el-form-item label="审核备注"><el-input v-model="reviewRemark" type="textarea" :rows="4" maxlength="1000" show-word-limit :placeholder="reviewDecision === 'APPROVE' ? '请输入通过说明（选填）' : '请输入拒绝原因（选填）'" /></el-form-item></el-form></AppDialog><AppDialog class="admin-density-dialog" v-model="feeDialogOpen" title="登记采购费用" width="min(560px, calc(100vw - 28px))" confirm-text="确认登记" :confirm-loading="savingFee" @confirm="saveFee"><el-form class="density-form" label-position="top"><el-form-item label="费用项" required><el-input v-model="feeForm.feeItemName" maxlength="64" placeholder="请输入费用名称" /></el-form-item><el-form-item label="费用代码" required><el-input v-model="feeForm.feeItemCode" maxlength="64" placeholder="请输入费用代码" /></el-form-item><el-form-item label="费用金额（CNY）" required><el-input-number v-model="feeForm.amount" :min="0.01" :precision="2" controls-position="right" placeholder="请输入费用金额" /></el-form-item><el-form-item label="费用凭证"><el-input :model-value="voucher?.fileName" disabled /></el-form-item><el-form-item label="备注"><el-input v-model="feeForm.remark" type="textarea" :rows="3" maxlength="500" placeholder="请输入费用说明（选填）" /></el-form-item></el-form></AppDialog></AdminPage>
+</template>
+
+<style scoped>
+.purchase-detail { gap: 0; border: 1px solid var(--cc-border); border-radius: var(--admin-radius); background: var(--admin-surface); }
+.header-actions, .section-actions { display: flex; align-items: center; gap: var(--admin-space-3); }
+.detail-surface { min-width: 0; padding: var(--admin-space-5); }
+.detail-grid { display: grid; min-width: 0; gap: var(--admin-space-5); }
+.detail-grid section { min-width: 0; }
+.detail-grid h3 { margin: 0 0 var(--admin-space-3); font-size: var(--admin-font-section); }
+.detail-grid .density-fields > .wide { grid-column: span 2; }
+.section-heading { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-3); margin-bottom: var(--admin-space-3); }
+.section-heading h3 { margin: 0; }
+.section-heading span, .review-reference { color: var(--cc-muted); font-size: var(--admin-font-caption); }
+.review-reference { margin: var(--admin-space-3) 0; }
+:deep(.el-input-number) { width: 100%; }
+</style>
diff --git a/src/modules/overseas-business/pages/PurchaseOrderEditView.vue b/src/modules/overseas-business/pages/PurchaseOrderEditView.vue
new file mode 100644
index 00000000..289c047b
--- /dev/null
+++ b/src/modules/overseas-business/pages/PurchaseOrderEditView.vue
@@ -0,0 +1,99 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import '../overseasBusinessDensity.css'
+import { computed, reactive, ref, watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { ArrowLeft, Save } from '@lucide/vue'
+import { ElMessage, type FormInstance, type FormRules } from 'element-plus'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import DetailPageLayout from '@/shared/components/DetailPageLayout.vue'
+import FormSection from '@/shared/components/FormSection.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import OperationErrorToast from '@/shared/components/OperationErrorToast.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { useUnsavedWorkRegistration } from '@/core/unsaved-work/useUnsavedWorkRegistration'
+import { getOverseasPurchase, listOverseasPurchaseWarehouseOptions, updateOverseasPurchase } from '../api/platformOverseasBusiness'
+import { overseasBusinessPermissions } from '../permissions'
+import type { OverseasPurchaseOutboundDetail, OverseasPurchaseStatus, OverseasPurchaseWarehouseOption, UpdateOverseasPurchaseRequest } from '../types'
+
+interface PurchaseEditModel {
+  orderNo: string; purchaseCategory: string; productName: string; productSpecification: string | null; productUrl: string | null
+  inboundQuantity: number; status: OverseasPurchaseStatus; purchaseWarehouseId: string | null
+  domesticCarrier: string | null; domesticTrackingNo: string | null; overseasCarrier: string | null; overseasTrackingNo: string | null
+  estimatedArrivalAt: string | null; remark: string | null; version: number
+  outboundDetails: OverseasPurchaseOutboundDetail[]
+}
+const route = useRoute(); const router = useRouter()
+const purchaseId = computed(() => typeof route.params.purchaseId === 'string' ? route.params.purchaseId : '')
+const customerId = computed(() => typeof route.query.customerId === 'string' ? route.query.customerId : '')
+const formRef = ref<FormInstance>(); const loading = ref(false); const saving = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null); const submitError = ref<ApiErrorDetails | null>(null)
+const warehouses = ref<OverseasPurchaseWarehouseOption[]>([]); const warehousesLoading = ref(false); const warehousesError = ref('')
+const initial = (): PurchaseEditModel => ({ orderNo: '', purchaseCategory: '', productName: '', productSpecification: null, productUrl: null, inboundQuantity: 0, status: 'PENDING_REVIEW', purchaseWarehouseId: null, domesticCarrier: null, domesticTrackingNo: null, overseasCarrier: null, overseasTrackingNo: null, estimatedArrivalAt: null, remark: null, version: 0, outboundDetails: [] })
+const form = reactive<PurchaseEditModel>(initial())
+const rules: FormRules<PurchaseEditModel> = {
+  purchaseCategory: [{ required: true, message: '请输入采购品类', trigger: 'blur' }],
+  productName: [{ required: true, message: '请输入商品名称', trigger: 'blur' }],
+}
+const statusLabels: Record<OverseasPurchaseStatus, string> = { PENDING_REVIEW: '待审核', APPROVED: '已通过', REJECTED: '已拒绝', PENDING_OUTBOUND: '待出库', PARTIALLY_OUTBOUND: '部分出库', OUTBOUNDED: '全部出库' }
+const inboundEditable = computed(() => ['APPROVED', 'PENDING_OUTBOUND', 'PARTIALLY_OUTBOUND', 'OUTBOUNDED'].includes(form.status))
+const outboundQuantity = computed(() => form.outboundDetails.reduce((sum, item) => sum + (Number(item.quantity) || 0), 0))
+function addOutbound() { form.outboundDetails.push({ id: `new-${Date.now()}-${form.outboundDetails.length}`, quantity: 0, carrier: null, trackingNo: null, shippedAt: null, remark: null }) }
+function removeOutbound(index: number) { form.outboundDetails.splice(index, 1) }
+const { captureBaseline } = useUnsavedWorkRegistration({ key: 'overseas-purchase-editor', label: computed(() => '编辑海外采购订单'), isOpen: computed(() => true), model: form, requiredPermission: computed(() => overseasBusinessPermissions.purchaseEdit) })
+async function loadWarehouses() {
+  warehousesLoading.value = true; warehousesError.value = ''
+  try { warehouses.value = await listOverseasPurchaseWarehouseOptions() }
+  catch { warehouses.value = []; warehousesError.value = '采购仓候选加载失败，请稍后重试' }
+  finally { warehousesLoading.value = false }
+}
+async function load() {
+  Object.assign(form, initial()); loadError.value = null; submitError.value = null
+  if (!purchaseId.value || !customerId.value) { loadError.value = { message: '缺少采购订单号或客户标识，请从采购订单列表重新进入' }; captureBaseline(); return }
+  loading.value = true
+  try {
+    const detail = await getOverseasPurchase(purchaseId.value, customerId.value)
+    Object.assign(form, { orderNo: detail.orderNo, purchaseCategory: detail.purchaseCategory, productName: detail.productName, productSpecification: detail.productSpecification, productUrl: detail.productUrl, inboundQuantity: detail.inboundQuantity, status: detail.status, purchaseWarehouseId: detail.purchaseWarehouseId, domesticCarrier: detail.domesticCarrier, domesticTrackingNo: detail.domesticTrackingNo, overseasCarrier: detail.overseasCarrier, overseasTrackingNo: detail.overseasTrackingNo, estimatedArrivalAt: detail.estimatedArrivalAt, remark: detail.remark, version: detail.version, outboundDetails: (detail.outboundDetails || []).map((item) => ({ ...item })) })
+    if (detail.purchaseWarehouseId && !warehouses.value.some((item) => item.warehouseId === detail.purchaseWarehouseId)) warehouses.value.push({ warehouseId: detail.purchaseWarehouseId, warehouseCode: '', warehouseName: detail.purchaseWarehouseName || '当前采购仓', countryCode: '' })
+    captureBaseline()
+  } catch (error) { loadError.value = getApiErrorDetails(error, '海外采购订单加载失败') } finally { loading.value = false }
+}
+async function save() {
+  if (!await formRef.value?.validate().catch(() => false)) return
+  if (outboundQuantity.value > form.inboundQuantity) { ElMessage.error('出库总量不能超过入库量'); return }
+  saving.value = true; submitError.value = null
+  const payload: UpdateOverseasPurchaseRequest = { version: form.version, purchaseCategory: form.purchaseCategory.trim(), productName: form.productName.trim(), productSpecification: form.productSpecification?.trim() || null, productUrl: form.productUrl?.trim() || null, inboundQuantity: inboundEditable.value ? form.inboundQuantity : undefined, purchaseWarehouseId: form.purchaseWarehouseId || null, domesticCarrier: form.domesticCarrier?.trim() || null, domesticTrackingNo: form.domesticTrackingNo?.trim() || null, overseasCarrier: form.overseasCarrier?.trim() || null, overseasTrackingNo: form.overseasTrackingNo?.trim() || null, estimatedArrivalAt: form.estimatedArrivalAt || null, remark: form.remark?.trim() || null, outboundDetails: form.outboundDetails.map((item) => ({ ...item, quantity: Number(item.quantity) || 0, carrier: item.carrier?.trim() || null, trackingNo: item.trackingNo?.trim() || null, remark: item.remark?.trim() || null })) }
+  try {
+    const updated = await updateOverseasPurchase(purchaseId.value, customerId.value, payload)
+    form.version = updated.version; captureBaseline(); ElMessage.success('海外采购订单已保存')
+    await router.push({ name: 'overseas-business-purchase-detail', params: { purchaseId: updated.orderNo }, query: { customerId: updated.customerId } })
+  } catch (error) { submitError.value = getApiErrorDetails(error, '海外采购订单保存失败') } finally { saving.value = false }
+}
+watch([purchaseId, customerId], () => { void loadWarehouses().then(load) }, { immediate: true })
+</script>
+
+<template>
+  <AdminPage class="admin-density overseas-business-editor"><OperationErrorToast :details="submitError" /><DetailPageLayout class="overseas-business-form-layout" aria-label="编辑海外采购订单">
+    <template #header><div class="density-detail-header"><div class="density-detail-heading"><el-button link class="density-back" @click="router.push({ name: 'overseas-business-purchase-detail', params: { purchaseId }, query: { customerId } })"><ArrowLeft :size="16" />返回详情</el-button><h1 class="density-detail-title">编辑海外采购订单</h1><span class="form-reference">{{ form.orderNo || '—' }}</span></div></div></template>
+    <LoadErrorState v-if="loadError" title="采购订单暂时无法编辑" :message="loadError.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="loadError" /></template></LoadErrorState>
+    <section v-else v-loading="loading" class="form-panel"><el-form class="density-form" ref="formRef" :model="form" :rules="rules" label-position="top" :disabled="saving">
+      <FormSection class="density-form-section" title="商品信息"><div class="form-grid three"><el-form-item label="订单编号"><el-input v-model="form.orderNo" disabled /></el-form-item><el-form-item label="采购品类" prop="purchaseCategory"><el-input v-model="form.purchaseCategory" maxlength="128" placeholder="请输入采购品类" /></el-form-item><el-form-item label="商品名称" prop="productName"><el-input v-model="form.productName" maxlength="255" placeholder="请输入商品名称" /></el-form-item><el-form-item class="span-2" label="商品规格"><el-input v-model="form.productSpecification" maxlength="500" placeholder="请输入商品规格" /></el-form-item><el-form-item class="span-3" label="商品链接"><el-input v-model="form.productUrl" maxlength="2000" placeholder="请输入商品链接" /></el-form-item></div></FormSection>
+      <FormSection class="density-form-section" title="库存与快递信息"><div class="form-grid three"><el-form-item label="入库量"><el-input-number v-model="form.inboundQuantity" :min="0" :disabled="!inboundEditable" controls-position="right" placeholder="请输入入库数量" /><small v-if="!inboundEditable">服务端仅允许已通过订单修改入库量</small></el-form-item><el-form-item label="出库量"><el-input :model-value="outboundQuantity" disabled /></el-form-item><el-form-item label="状态"><el-input :model-value="statusLabels[form.status]" disabled /></el-form-item><el-form-item label="采购仓库"><el-select v-model="form.purchaseWarehouseId" clearable filterable :loading="warehousesLoading" :disabled="Boolean(warehousesError)" placeholder="请选择采购仓"><el-option v-for="item in warehouses" :key="item.warehouseId" :label="`${item.warehouseName}${item.warehouseCode ? ` · ${item.warehouseCode}` : ''}`" :value="item.warehouseId" /></el-select><small v-if="warehousesError" class="field-error">{{ warehousesError }}</small></el-form-item><el-form-item label="预计到达时间"><el-date-picker v-model="form.estimatedArrivalAt" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" clearable /></el-form-item><el-form-item label="国内承运商"><el-input v-model="form.domesticCarrier" maxlength="128" placeholder="请输入国内承运商" /></el-form-item><el-form-item label="国内运单号"><el-input v-model="form.domesticTrackingNo" maxlength="128" placeholder="请输入国内物流单号" /></el-form-item><el-form-item label="海外承运商"><el-input v-model="form.overseasCarrier" maxlength="128" placeholder="请输入海外承运商" /></el-form-item><el-form-item label="海外运单号"><el-input v-model="form.overseasTrackingNo" maxlength="128" placeholder="请输入海外物流单号" /></el-form-item><el-form-item class="span-3" label="备注"><el-input v-model="form.remark" type="textarea" :rows="3" maxlength="1000" show-word-limit placeholder="请输入备注（选填）" /></el-form-item></div></FormSection>
+      <FormSection class="density-form-section" title="出库明细"><div class="outbound-head"><span>出库总量：<b>{{ outboundQuantity }}</b> / {{ form.inboundQuantity }}</span><el-button class="density-action" data-tone="primary" size="small" @click="addOutbound">添加出库明细</el-button></div><div v-if="!form.outboundDetails.length" class="empty-outbound">暂无出库明细，可添加多条出库记录</div><div v-for="(item, index) in form.outboundDetails" :key="item.id" class="outbound-row"><el-form-item label="出库数量"><el-input-number v-model="item.quantity" :min="0" :max="form.inboundQuantity" controls-position="right" placeholder="请输入出库数量" /></el-form-item><el-form-item label="承运商"><el-input v-model="item.carrier" maxlength="128" placeholder="请输入快递或物流名称" /></el-form-item><el-form-item label="运单号"><el-input v-model="item.trackingNo" maxlength="128" placeholder="请输入物流单号" /></el-form-item><el-form-item label="出库时间"><el-date-picker v-model="item.shippedAt" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" clearable /></el-form-item><el-form-item class="outbound-remark" label="备注"><el-input v-model="item.remark" maxlength="500" placeholder="请输入本次出库备注（选填）" /></el-form-item><el-button class="remove-outbound density-action" data-tone="danger" @click="removeOutbound(index)" :aria-label="`删除第 ${index + 1} 条出库明细`">删除</el-button></div></FormSection>
+    </el-form><footer class="form-actions"><el-button type="primary" :loading="saving" @click="save"><Save :size="16" />保存</el-button><el-button :disabled="saving" @click="router.push({ name: 'overseas-business-purchase-detail', params: { purchaseId }, query: { customerId } })">取消</el-button></footer></section>
+  </DetailPageLayout></AdminPage>
+</template>
+
+<style scoped>
+.form-grid { grid-template-columns: repeat(3, minmax(0, 1fr)); }
+.span-2 { grid-column: span 2; }
+.span-3 { grid-column: 1 / -1; }
+.outbound-head { display: flex; align-items: center; justify-content: space-between; margin-bottom: var(--admin-space-3); color: var(--cc-muted); font-size: var(--admin-font-body); }
+.outbound-head b { color: var(--cc-text); }
+.empty-outbound { padding: var(--admin-space-5); color: var(--cc-muted); text-align: center; }
+.outbound-row { display: grid; grid-template-columns: 110px minmax(0,1fr) minmax(0,1fr) 190px minmax(0,1fr) 60px; gap: var(--admin-space-3); align-items: start; padding: var(--admin-space-3) 0; border-bottom: 1px solid var(--cc-border); }
+.outbound-row :deep(.el-form-item) { margin-bottom: 0; }
+.outbound-row :deep(.el-input-number), .outbound-row :deep(.el-date-editor) { width: 100%; }
+.remove-outbound { align-self: end; }
+</style>
diff --git a/src/modules/overseas-business/pages/PurchaseOrdersView.vue b/src/modules/overseas-business/pages/PurchaseOrdersView.vue
new file mode 100644
index 00000000..0fcd6384
--- /dev/null
+++ b/src/modules/overseas-business/pages/PurchaseOrdersView.vue
@@ -0,0 +1,75 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onActivated, onMounted, ref, watch } from 'vue'
+import { useRouter } from 'vue-router'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { listOverseasPurchaseCustomerOptions, listOverseasPurchases } from '../api/platformOverseasBusiness'
+import { overseasBusinessPermissions } from '../permissions'
+import type { OverseasPurchaseCustomerOption, OverseasPurchaseQuery, OverseasPurchaseStatus, OverseasPurchaseSummary } from '../types'
+
+const router = useRouter(); const access = useAccessPreviewStore()
+const rows = ref<OverseasPurchaseSummary[]>([]); const loading = ref(false); const loadError = ref<ApiErrorDetails | null>(null)
+const page = ref(1); const pageSize = ref(20); const total = ref(0)
+const filters = ref<QueryModel>({ orderNo: '', customerId: '', purchaseCategory: '', productName: '' }); const applied = ref({ ...filters.value })
+const customerOptions = ref<OverseasPurchaseCustomerOption[]>([]); const customersLoading = ref(false)
+const fields = computed<QueryField[]>(() => [
+  { key: 'orderNo', type: 'input', label: '订单编号', placeholder: '请输入订单编号', width: 210 },
+  { key: 'customerId', type: 'select', label: '客户', placeholder: '全部客户', width: 210, options: customerOptions.value.map((item) => ({ label: item.customerName, value: item.customerId })), props: { filterable: true, loading: customersLoading.value } },
+  { key: 'purchaseCategory', type: 'input', label: '采购品类', placeholder: '请输入采购品类', width: 190 },
+  { key: 'productName', type: 'input', label: '商品名称', placeholder: '请输入商品名称', width: 210 },
+])
+const columns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 176, fixed: 'left', slotName: 'actions' },
+  { key: 'orderNo', prop: 'orderNo', label: '订单编号', minWidth: 170 },
+  { key: 'customerName', prop: 'customerName', label: '客户名称', minWidth: 180, formatter: (row: OverseasPurchaseSummary) => row.customerName || '—' },
+  { key: 'purchaseWarehouseName', prop: 'purchaseWarehouseName', label: '采购仓库', minWidth: 160, formatter: (row: OverseasPurchaseSummary) => row.purchaseWarehouseName || '—' },
+  { key: 'purchaseCategory', prop: 'purchaseCategory', label: '采购品类', minWidth: 130 },
+  { key: 'productName', prop: 'productName', label: '商品名称', minWidth: 160 },
+  { key: 'productSpecification', prop: 'productSpecification', label: '商品规格', minWidth: 180, formatter: (row: OverseasPurchaseSummary) => row.productSpecification || '—' },
+  { key: 'budgetUnitPrice', label: '采购单价', width: 120, align: 'right', formatter: (row: OverseasPurchaseSummary) => formatAmount(row.budgetUnitPrice, row.currency) },
+  { key: 'inboundQuantity', prop: 'inboundQuantity', label: '入库量', width: 95, align: 'right' },
+  { key: 'outboundQuantity', prop: 'outboundQuantity', label: '出库量', width: 95, align: 'right' },
+  { key: 'inventoryQuantity', prop: 'inventoryQuantity', label: '库存量', width: 95, align: 'right' },
+  { key: 'status', label: '状态', width: 105, formatter: (row: OverseasPurchaseSummary) => purchaseStatusLabel(row.status) },
+  { key: 'createdAt', prop: 'createdAt', label: '创建时间', minWidth: 165, formatter: (row: OverseasPurchaseSummary) => formatDateTime(row.createdAt) },
+]
+const statusLabels: Record<OverseasPurchaseStatus, string> = { PENDING_REVIEW: '待审核', APPROVED: '已通过', REJECTED: '已拒绝', PENDING_OUTBOUND: '待出库', PARTIALLY_OUTBOUND: '部分出库', OUTBOUNDED: '全部出库' }
+function purchaseStatusLabel(status: OverseasPurchaseStatus) { return statusLabels[status] || status }
+function formatAmount(value: string | null, currency: string) { if (value == null) return '—'; const amount = Number(value); return `${Number.isFinite(amount) ? amount.toLocaleString('zh-CN', { minimumFractionDigits: 2, maximumFractionDigits: 2 }) : value} ${currency}` }
+function formatDateTime(value?: string | null) { return value ? value.replace('T', ' ').slice(0, 16) : '—' }
+async function load() {
+  loading.value = true; loadError.value = null
+  try {
+    const result = await listOverseasPurchases({ page: page.value, size: pageSize.value, customerId: String(applied.value.customerId || ''), orderNo: String(applied.value.orderNo || ''), purchaseCategory: String(applied.value.purchaseCategory || ''), productName: String(applied.value.productName || '') } satisfies OverseasPurchaseQuery)
+    rows.value = result.records; total.value = result.total
+  } catch (error) { rows.value = []; total.value = 0; loadError.value = getApiErrorDetails(error, '海外采购订单加载失败，请稍后重试') } finally { loading.value = false }
+}
+function search(model: QueryModel) { applied.value = { ...model }; if (page.value === 1) void load(); else page.value = 1 }
+function open(row: OverseasPurchaseSummary, edit = false) { void router.push({ name: edit ? 'overseas-business-purchase-edit' : 'overseas-business-purchase-detail', params: { purchaseId: row.orderNo }, query: { customerId: row.customerId } }) }
+async function loadCustomerOptions() { customersLoading.value = true; try { customerOptions.value = await listOverseasPurchaseCustomerOptions() } catch { customerOptions.value = [] } finally { customersLoading.value = false } }
+let activatedOnce = false
+watch([page, pageSize], () => { void load() }); onMounted(() => { void load(); void loadCustomerOptions() })
+onActivated(() => { if (activatedOnce) void load(); else activatedOnce = true })
+</script>
+
+<template>
+  <AdminPage class="admin-density"><ListPageLayout aria-label="海外采购订单列表">
+    <template #toolbar><QueryToolbar v-model="filters" class="surface-panel" :fields="fields" ariaLabel="海外采购订单筛选" preference-key="overseas-business-purchases-query" @search="search" /></template>
+    <template v-if="loadError" #state><LoadErrorState title="海外采购订单暂时无法加载" :message="loadError.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="loadError" /></template></LoadErrorState></template>
+    <section v-if="!loadError" class="surface-panel table-panel"><DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :loading="loading" :total="total" preference-key="overseas-business-purchases" row-key="id" empty-text="暂无符合筛选条件的海外采购订单">
+      <template #actions="{ row }"><div class="density-actions"><el-button class="density-action" data-tone="neutral" size="small" @click="open(row as OverseasPurchaseSummary)">详情</el-button><el-button class="density-action" data-tone="neutral" v-if="access.can(overseasBusinessPermissions.purchaseEdit)" size="small" @click="open(row as OverseasPurchaseSummary, true)">编辑</el-button></div></template>
+      <template #pagination-left>共 {{ total }} 条海外采购订单</template>
+    </DataTable></section>
+  </ListPageLayout></AdminPage>
+</template>
+
+<style scoped>
+.table-panel { overflow: hidden; }
+</style>
diff --git a/src/modules/overseas-business/pages/TransportOrderFormView.vue b/src/modules/overseas-business/pages/TransportOrderFormView.vue
new file mode 100644
index 00000000..bfc13416
--- /dev/null
+++ b/src/modules/overseas-business/pages/TransportOrderFormView.vue
@@ -0,0 +1,130 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import '../overseasBusinessDensity.css'
+import { computed, reactive, ref, watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { ArrowLeft, Save } from '@lucide/vue'
+import { ElMessage, type FormInstance, type FormRules } from 'element-plus'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import DetailPageLayout from '@/shared/components/DetailPageLayout.vue'
+import FormSection from '@/shared/components/FormSection.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import OperationErrorToast from '@/shared/components/OperationErrorToast.vue'
+import { listPlatformTenants, type PlatformTenantResource } from '@/modules/iam'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { CONTAINER_SPECIFICATIONS, DEFAULT_CONTAINER_TYPE } from '@/shared/domain/containerSpecifications'
+import { useUnsavedWorkRegistration } from '@/core/unsaved-work/useUnsavedWorkRegistration'
+import { createLocalLooseboardOrder, createUsTruckOrder, getLocalLooseboardOrder, getUsTruckOrder, updateLocalLooseboardOrder, updateUsTruckOrder } from '../api/platformOverseasBusiness'
+import { overseasBusinessPermissions } from '../permissions'
+import type { CreateLocalLooseboardOrderRequest, CreateLocalTransportOrderRequest, LocalLooseboardStatus, LocalTransportStatus, LocalTransportType, LooseboardTransportMode, PalletRequired, UpdateLocalLooseboardOrderRequest, UpdateLocalTransportOrderRequest } from '../types'
+
+const props = defineProps<{ domain: 'truck' | 'looseboard' }>()
+const route = useRoute(); const router = useRouter(); const formRef = ref<FormInstance>()
+const orderId = computed(() => typeof route.params.orderId === 'string' ? route.params.orderId : '')
+const routeCustomerId = computed(() => typeof route.query.customerId === 'string' ? route.query.customerId : '')
+const editing = computed(() => Boolean(orderId.value)); const isLooseboard = computed(() => props.domain === 'looseboard')
+const domainLabel = computed(() => isLooseboard.value ? '本土散板' : '本土卡车'); const listRouteName = computed(() => isLooseboard.value ? 'overseas-business-looseboards' : 'overseas-business-trucks')
+const requiredPermission = computed(() => isLooseboard.value ? (editing.value ? overseasBusinessPermissions.looseboardEdit : overseasBusinessPermissions.looseboardCreate) : (editing.value ? overseasBusinessPermissions.truckEdit : overseasBusinessPermissions.truckCreate))
+type FormStatus = LocalTransportStatus | LocalLooseboardStatus
+interface TransportFormModel {
+  customerId: string; orderNo: string; transportMode: LooseboardTransportMode | ''; palletRequired: PalletRequired | ''
+  transportType: LocalTransportType | ''; origin: string; destination: string; originAddress: string | null; destinationAddress: string | null
+  contactName: string | null; contactInfo: string | null; containerType: string | null; palletCount: number; packageCount: number
+  totalWeightKg: string | null; totalVolumeCbm: string | null; budgetAmount: string | null; currency: string
+  requestedDate: string | null; remark: string | null; status: FormStatus; version: number; idempotencyKey: string
+}
+function newIdempotencyKey() { return globalThis.crypto?.randomUUID?.() || `admin-${Date.now()}-${Math.random().toString(36).slice(2)}` }
+const initial = (): TransportFormModel => ({ customerId: '', orderNo: '', transportMode: '', palletRequired: '', transportType: '', origin: '', destination: '', originAddress: null, destinationAddress: null, contactName: null, contactInfo: null, containerType: DEFAULT_CONTAINER_TYPE, palletCount: 1, packageCount: 0, totalWeightKg: null, totalVolumeCbm: null, budgetAmount: null, currency: 'USD', requestedDate: null, remark: null, status: isLooseboard.value ? 'PENDING_ACCEPTANCE' : 'PENDING_REVIEW', version: 0, idempotencyKey: newIdempotencyKey() })
+const form = reactive<TransportFormModel>(initial()); const loading = ref(false); const saving = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null); const submitError = ref<ApiErrorDetails | null>(null)
+const customers = ref<PlatformTenantResource[]>([]); const customersLoading = ref(false); const customersError = ref('')
+const requiredDecimal = (label: string) => ({ validator: (_rule: unknown, value: string | null, callback: (error?: Error) => void) => value !== null && value !== '' && Number.isFinite(Number(value)) && Number(value) >= 0 ? callback() : callback(new Error(`请输入有效的${label}`)), trigger: 'blur' })
+const rules: FormRules<TransportFormModel> = {
+  transportMode: [{ validator: (_rule, value, callback) => (!isLooseboard.value || value) ? callback() : callback(new Error('请选择运输方式')), trigger: 'change' }],
+  palletRequired: [{ validator: (_rule, value, callback) => (!isLooseboard.value || value) ? callback() : callback(new Error('请选择是否打盘')), trigger: 'change' }],
+  transportType: [{ required: true, message: '请选择运输类型', trigger: 'change' }], origin: [{ required: true, message: '请输入起运地', trigger: 'blur' }], destination: [{ required: true, message: '请输入目的地', trigger: 'blur' }],
+  palletCount: [{ validator: (_rule, value, callback) => (isLooseboard.value || (Number.isInteger(value) && value >= 1)) ? callback() : callback(new Error('托数至少为 1')), trigger: 'change' }],
+  packageCount: [{ required: true, type: 'number', min: 0, message: '件数不能小于 0', trigger: 'change' }], totalWeightKg: [requiredDecimal('总重量')], totalVolumeCbm: [requiredDecimal('总体积')],
+  contactName: [{ validator: (_rule, value, callback) => (isLooseboard.value || String(value || '').trim()) ? callback() : callback(new Error('请输入联系人')), trigger: 'blur' }],
+  contactInfo: [{ validator: (_rule, value, callback) => (isLooseboard.value || String(value || '').trim()) ? callback() : callback(new Error('请输入联系方式')), trigger: 'blur' }],
+  requestedDate: [{ validator: (_rule, value, callback) => (isLooseboard.value || value) ? callback() : callback(new Error('请选择要求时间')), trigger: 'change' }],
+  budgetAmount: [{ pattern: /^\d+(\.\d{1,2})?$/, message: '预算总价最多保留 2 位小数', trigger: 'blur' }],
+}
+const transportTypes = [{ value: 'PORT_PICKUP', label: '⚓ 港口提柜' }, { value: 'WAREHOUSE_TO_WAREHOUSE', label: '🏭 仓到仓' }, { value: 'WAREHOUSE_TO_DOOR', label: '🚛 仓到门' }]
+const transportModes = [{ value: 'SHARED_TRUCK', label: '🚐 拼车' }, { value: 'PRIORITY_CONSOLIDATION', label: '📦 优先拼载' }]
+const truckStatusLabels: Record<LocalTransportStatus, string> = { PENDING_REVIEW: '待审核', WAITING_INBOUND: '待入仓', RECEIVING: '收货中', WAITING_CONSOLIDATION: '待合托', PALLET_OVERAGE_REVIEW: '超托待审', PARTIALLY_ALLOCATED: '部分分配', ALLOCATED: '已分配', PENDING_DISPATCH: '待派车', DISPATCHED: '已派车', IN_TRANSIT: '运输中', COMPLETED: '已完成', REJECTED: '已拒绝', CANCELLED: '已取消' }
+const looseboardStatusLabels: Record<LocalLooseboardStatus, string> = { PENDING_ACCEPTANCE: '待接单', DISPATCHED: '已派车', IN_TRANSIT: '运输中', COMPLETED: '已完成', CANCELLED: '已取消' }
+const statusLabel = computed(() => isLooseboard.value ? looseboardStatusLabels[form.status as LocalLooseboardStatus] : truckStatusLabels[form.status as LocalTransportStatus])
+const editableStatus = computed(() => !editing.value || (isLooseboard.value ? form.status === 'PENDING_ACCEPTANCE' : form.status === 'PENDING_REVIEW'))
+const { captureBaseline } = useUnsavedWorkRegistration({ key: `overseas-${props.domain}-editor`, label: computed(() => `${editing.value ? '编辑' : '新增'}${domainLabel.value}订单`), isOpen: computed(() => true), model: form, requiredPermission })
+function optional(value: string | null) { return value?.trim() || null }
+function amount(value: string | null) { return value === null || value === '' ? null : Number(value) }
+async function loadCustomers() {
+  if (editing.value) return
+  customersLoading.value = true; customersError.value = ''
+  try { const result = await listPlatformTenants({ page: 1, size: 200, status: 'ACTIVE' }); customers.value = result.records.filter((item) => item.status === 'ACTIVE') }
+  catch { customers.value = []; customersError.value = '客户候选加载失败，请稍后重试' }
+  finally { customersLoading.value = false }
+}
+async function load() {
+  Object.assign(form, initial()); loadError.value = null; submitError.value = null
+  if (!editing.value) { captureBaseline(); return }
+  if (!routeCustomerId.value) { loadError.value = { message: `缺少客户标识，请从${domainLabel.value}列表重新进入` }; captureBaseline(); return }
+  loading.value = true
+  try {
+    if (isLooseboard.value) {
+      const detail = await getLocalLooseboardOrder(orderId.value, routeCustomerId.value)
+      Object.assign(form, { customerId: detail.customerId, orderNo: detail.orderNo, transportMode: detail.transportMode, palletRequired: detail.palletRequired, transportType: detail.transportType, origin: detail.origin, destination: detail.destination, originAddress: detail.originAddress, destinationAddress: detail.destinationAddress, contactName: detail.contactName, contactInfo: detail.contactInfo, containerType: detail.containerType, packageCount: detail.packageCount, totalWeightKg: detail.totalWeightKg, totalVolumeCbm: detail.totalVolumeCbm, budgetAmount: detail.budgetAmount, currency: detail.currency, requestedDate: detail.requestedDate, remark: detail.remark, status: detail.status, version: detail.version })
+    } else {
+      const detail = await getUsTruckOrder(orderId.value, routeCustomerId.value)
+      Object.assign(form, { customerId: detail.customerId, orderNo: detail.orderNo, transportType: detail.transportType || '', origin: detail.origin, destination: detail.destination, originAddress: detail.originAddress, destinationAddress: detail.destinationAddress, contactName: detail.contactName, contactInfo: detail.contactInfo, containerType: detail.containerType, palletCount: detail.palletCount, packageCount: detail.packageCount, totalWeightKg: detail.totalWeightKg, totalVolumeCbm: detail.totalVolumeCbm, budgetAmount: detail.budgetAmount, currency: detail.currency, requestedDate: detail.requestedDate, remark: detail.remark, status: detail.status, version: detail.version })
+    }
+    captureBaseline()
+  } catch (error) { loadError.value = getApiErrorDetails(error, `${domainLabel.value}订单详情加载失败`) } finally { loading.value = false }
+}
+async function save() {
+  if (!editableStatus.value) { submitError.value = { message: `当前${domainLabel.value}订单状态不可编辑` }; return }
+  if (!editing.value && !form.customerId) { submitError.value = { message: '请选择客户' }; return }
+  if (!await formRef.value?.validate().catch(() => false)) return
+  const common = { transportType: form.transportType as LocalTransportType, origin: form.origin.trim(), originAddress: optional(form.originAddress), destination: form.destination.trim(), destinationAddress: optional(form.destinationAddress), containerType: optional(form.containerType), packageCount: form.packageCount, totalWeightKg: Number(form.totalWeightKg), totalVolumeCbm: Number(form.totalVolumeCbm), budgetAmount: amount(form.budgetAmount), currency: form.currency, contactName: optional(form.contactName), contactInfo: optional(form.contactInfo), requestedDate: form.requestedDate, remark: optional(form.remark) }
+  saving.value = true; submitError.value = null
+  try {
+    if (isLooseboard.value) {
+      const loose = { ...common, transportMode: form.transportMode as LooseboardTransportMode, palletRequired: form.palletRequired as PalletRequired }
+      if (editing.value) await updateLocalLooseboardOrder(orderId.value, routeCustomerId.value, { ...loose, version: form.version } satisfies UpdateLocalLooseboardOrderRequest)
+      else await createLocalLooseboardOrder(form.customerId, { ...loose, idempotencyKey: form.idempotencyKey } satisfies CreateLocalLooseboardOrderRequest)
+    } else {
+      const truck = { ...common, contactName: form.contactName!.trim(), contactInfo: form.contactInfo!.trim(), requestedDate: form.requestedDate!, palletCount: form.palletCount }
+      if (editing.value) await updateUsTruckOrder(orderId.value, routeCustomerId.value, { ...truck, version: form.version } satisfies UpdateLocalTransportOrderRequest)
+      else await createUsTruckOrder(form.customerId, { ...truck, idempotencyKey: form.idempotencyKey } satisfies CreateLocalTransportOrderRequest)
+    }
+    captureBaseline(); ElMessage.success(`${domainLabel.value}订单已${editing.value ? '保存' : '创建'}`); await router.push({ name: listRouteName.value })
+  } catch (error) { submitError.value = getApiErrorDetails(error, `${domainLabel.value}订单保存失败`) } finally { saving.value = false }
+}
+function back() { void router.push({ name: listRouteName.value }) }
+watch([orderId, routeCustomerId, isLooseboard], () => { void load(); void loadCustomers() }, { immediate: true })
+</script>
+
+<template>
+  <AdminPage class="admin-density overseas-business-editor"><OperationErrorToast :details="submitError" /><DetailPageLayout class="overseas-business-form-layout" :aria-label="`${editing ? '编辑' : '新增'}${domainLabel}订单`">
+    <template #header><div class="density-detail-header"><div class="density-detail-heading"><el-button link class="density-back" @click="back"><ArrowLeft :size="16" />返回列表</el-button><h1 class="density-detail-title">{{ editing ? '编辑' : '新增' }}{{ domainLabel }}订单</h1><span v-if="editing" class="form-reference">{{ form.orderNo || '—' }}</span></div></div></template>
+    <LoadErrorState v-if="loadError" :title="`${domainLabel}订单暂时无法加载`" :message="loadError.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="loadError" /></template></LoadErrorState>
+    <section v-else v-loading="loading" class="form-panel"><el-form class="density-form" ref="formRef" :model="form" :rules="rules" label-position="top" :disabled="saving || !editableStatus">
+      <FormSection class="density-form-section" v-if="!editing" title="客户信息"><el-form-item label="客户"><el-select v-model="form.customerId" filterable :loading="customersLoading" :disabled="Boolean(customersError)" placeholder="请选择客户" style="width:100%"><el-option v-for="item in customers" :key="String(item.id)" :label="item.tenantName" :value="String(item.id)" /></el-select><small v-if="customersError" class="field-error">{{ customersError }}</small></el-form-item></FormSection>
+      <el-alert v-if="editing && !editableStatus" type="warning" :closable="false" show-icon title="当前状态不可普通编辑，请返回列表查看" />
+      <FormSection class="density-form-section" v-if="isLooseboard" title="散板方式"><div class="choice-block"><el-form-item label="运输方式" prop="transportMode"><el-radio-group v-model="form.transportMode"><el-radio-button v-for="item in transportModes" :key="item.value" :value="item.value">{{ item.label }}</el-radio-button></el-radio-group></el-form-item><el-form-item label="是否打盘" prop="palletRequired"><el-radio-group v-model="form.palletRequired"><el-radio-button value="YES">是</el-radio-button><el-radio-button value="NO">否</el-radio-button></el-radio-group></el-form-item></div></FormSection>
+      <FormSection class="density-form-section" title="运输信息"><el-form-item label="运输类型" prop="transportType"><el-radio-group v-model="form.transportType"><el-radio-button v-for="item in transportTypes" :key="item.value" :value="item.value">{{ item.label }}</el-radio-button></el-radio-group></el-form-item><div class="form-grid two"><el-form-item label="起运地" prop="origin"><el-input v-model="form.origin" maxlength="255" placeholder="城市 / 港口 / 州" /></el-form-item><el-form-item label="目的地" prop="destination"><el-input v-model="form.destination" maxlength="255" placeholder="城市 / 州" /></el-form-item><el-form-item label="详细地址"><el-input v-model="form.originAddress" maxlength="500" placeholder="街道 / 门牌" /></el-form-item><el-form-item label="详细地址 / 码头 / 仓号"><el-input v-model="form.destinationAddress" maxlength="500" placeholder="地址 / 码头 / 仓号" /></el-form-item><el-form-item label="联系人" prop="contactName"><el-input v-model="form.contactName" maxlength="128" placeholder="请输入联系人姓名" /></el-form-item><el-form-item label="联系方式" prop="contactInfo"><el-input v-model="form.contactInfo" maxlength="128" placeholder="请输入联系方式" /></el-form-item></div></FormSection>
+      <FormSection class="density-form-section" title="📦 货物信息"><div class="form-grid" :class="isLooseboard ? 'four' : 'five'"><el-form-item label="柜型"><el-select v-model="form.containerType"><el-option v-for="item in CONTAINER_SPECIFICATIONS" :key="item.type" :label="item.type" :value="item.type" /></el-select></el-form-item><el-form-item v-if="!isLooseboard" label="托数" prop="palletCount"><el-input-number v-model="form.palletCount" :min="1" controls-position="right" placeholder="请输入托盘数" /></el-form-item><el-form-item label="件数" prop="packageCount"><el-input-number v-model="form.packageCount" :min="0" controls-position="right" placeholder="请输入件数" /></el-form-item><el-form-item label="总重量 (kg)" prop="totalWeightKg"><el-input v-model="form.totalWeightKg" inputmode="decimal" placeholder="请输入总重量" /></el-form-item><el-form-item label="总体积 (m³)" prop="totalVolumeCbm"><el-input v-model="form.totalVolumeCbm" inputmode="decimal" placeholder="请输入总体积" /></el-form-item></div></FormSection>
+      <FormSection class="density-form-section" title="费用与时效"><div class="form-grid two"><el-form-item label="预算总价" prop="budgetAmount"><el-input v-model="form.budgetAmount" inputmode="decimal" placeholder="请输入预算金额" ><template #append>{{ form.currency }}</template></el-input></el-form-item><el-form-item label="要求时间" prop="requestedDate"><el-date-picker v-model="form.requestedDate" type="date" value-format="YYYY-MM-DD" clearable /></el-form-item><el-form-item v-if="editing" label="状态"><el-input :model-value="statusLabel" disabled /></el-form-item><el-form-item class="span-2" label="备注"><el-input v-model="form.remark" type="textarea" :rows="3" maxlength="1000" show-word-limit placeholder="请输入备注（选填）" /></el-form-item></div></FormSection>
+    </el-form><footer class="form-actions"><el-button @click="back">取消</el-button><el-button type="primary" :loading="saving" :disabled="!editableStatus" @click="save"><Save :size="16" />{{ editing ? '保存修改' : '提交订单' }}</el-button></footer></section>
+  </DetailPageLayout></AdminPage>
+</template>
+
+<style scoped>
+.form-grid.two { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+.form-grid.four { grid-template-columns: repeat(4, minmax(0, 1fr)); }
+.form-grid.five { grid-template-columns: repeat(5, minmax(0, 1fr)); }
+.choice-block { display: grid; grid-template-columns: 1fr 1fr; gap: var(--admin-space-5); }
+.span-2 { grid-column: 1 / -1; }
+</style>
diff --git a/src/modules/overseas-business/pages/TransportOrdersView.vue b/src/modules/overseas-business/pages/TransportOrdersView.vue
new file mode 100644
index 00000000..d2b4eb60
--- /dev/null
+++ b/src/modules/overseas-business/pages/TransportOrdersView.vue
@@ -0,0 +1,89 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, ref, watch } from 'vue'
+import { useRouter } from 'vue-router'
+import { Plus } from '@lucide/vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { listLocalLooseboardOrders, listUsTruckOrders } from '../api/platformOverseasBusiness'
+import { overseasBusinessPermissions } from '../permissions'
+import type { LocalLooseboardOrder, LocalLooseboardQuery, LocalLooseboardStatus, LocalTransportOrder, LocalTransportQuery, LocalTransportStatus, LocalTransportType, LooseboardTransportMode } from '../types'
+
+const props = defineProps<{ domain: 'truck' | 'looseboard' }>()
+const router = useRouter(); const access = useAccessPreviewStore()
+const isLooseboard = computed(() => props.domain === 'looseboard'); const domainLabel = computed(() => isLooseboard.value ? '本土散板' : '本土卡车')
+const queryPreferenceKey = computed(() => isLooseboard.value ? 'overseas-business-looseboard-query' : 'overseas-business-truck-query')
+const createPermission = computed(() => isLooseboard.value ? overseasBusinessPermissions.looseboardCreate : overseasBusinessPermissions.truckCreate)
+const editPermission = computed(() => isLooseboard.value ? overseasBusinessPermissions.looseboardEdit : overseasBusinessPermissions.truckEdit)
+const rows = ref<Array<LocalTransportOrder | LocalLooseboardOrder>>([]); const loading = ref(false); const loadError = ref<ApiErrorDetails | null>(null)
+const page = ref(1); const pageSize = ref(20); const total = ref(0)
+const filters = ref<QueryModel>({ status: '', routeKeyword: '' }); const applied = ref({ ...filters.value })
+const truckStatusLabels: Record<LocalTransportStatus, string> = { PENDING_REVIEW: '待审核', WAITING_INBOUND: '待入仓', RECEIVING: '收货中', WAITING_CONSOLIDATION: '待合托', PALLET_OVERAGE_REVIEW: '超托待审', PARTIALLY_ALLOCATED: '部分分配', ALLOCATED: '已分配', PENDING_DISPATCH: '待派车', DISPATCHED: '已派车', IN_TRANSIT: '运输中', COMPLETED: '已完成', REJECTED: '已拒绝', CANCELLED: '已取消' }
+const looseboardStatusLabels: Record<LocalLooseboardStatus, string> = { PENDING_ACCEPTANCE: '待接单', DISPATCHED: '已派车', IN_TRANSIT: '运输中', COMPLETED: '已完成', CANCELLED: '已取消' }
+const transportTypeLabels: Record<LocalTransportType, string> = { PORT_PICKUP: '港口提柜', WAREHOUSE_TO_WAREHOUSE: '仓到仓', WAREHOUSE_TO_DOOR: '仓到门' }
+const transportModeLabels: Record<LooseboardTransportMode, string> = { SHARED_TRUCK: '拼车', PRIORITY_CONSOLIDATION: '优先拼载' }
+const fields = computed<QueryField[]>(() => [
+  { key: 'status', type: 'select', label: '状态', placeholder: '全部状态', width: 170, options: Object.entries(isLooseboard.value ? looseboardStatusLabels : truckStatusLabels).map(([value, label]) => ({ value, label })) },
+  { key: 'routeKeyword', type: 'input', label: '运输路线', placeholder: '起运地/目的地', width: 240 },
+])
+const truckColumns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 110, fixed: 'left', slotName: 'actions' }, { key: 'orderNo', prop: 'orderNo', label: '订单编号', minWidth: 170 },
+  { key: 'transportType', label: '运输类型', minWidth: 120, formatter: (row: LocalTransportOrder) => row.transportType ? transportTypeLabels[row.transportType] : '—' },
+  { key: 'origin', prop: 'origin', label: '起运地', minWidth: 145 }, { key: 'destination', prop: 'destination', label: '目的地', minWidth: 145 },
+  { key: 'contactName', prop: 'contactName', label: '联系人', minWidth: 110 }, { key: 'contactInfo', prop: 'contactInfo', label: '联系方式', minWidth: 145 },
+  { key: 'containerType', prop: 'containerType', label: '柜型', width: 90 }, { key: 'palletCount', prop: 'palletCount', label: '托数', width: 80, align: 'right' },
+  { key: 'packageCount', prop: 'packageCount', label: '件数', width: 80, align: 'right' }, { key: 'totalWeightKg', prop: 'totalWeightKg', label: '总重量(kg)', width: 115, align: 'right' },
+  { key: 'budgetAmount', label: '预算总价', width: 120, align: 'right', formatter: (row: LocalTransportOrder) => row.budgetAmount == null ? '—' : `${row.budgetAmount} ${row.currency}` },
+  { key: 'requestedDate', prop: 'requestedDate', label: '要求时间', width: 120 }, { key: 'status', label: '状态', width: 120, formatter: (row: LocalTransportOrder) => truckStatusLabels[row.status] },
+  { key: 'createdAt', prop: 'createdAt', label: '创建时间', minWidth: 165, formatter: (row: LocalTransportOrder) => formatDateTime(row.createdAt) },
+]
+const looseboardColumns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 110, fixed: 'left', slotName: 'actions' }, { key: 'orderNo', prop: 'orderNo', label: '订单编号', minWidth: 170 },
+  { key: 'transportMode', label: '运输方式', minWidth: 120, formatter: (row: LocalLooseboardOrder) => transportModeLabels[row.transportMode] }, { key: 'palletRequired', label: '是否打盘', width: 100, formatter: (row: LocalLooseboardOrder) => row.palletRequired === 'YES' ? '是' : '否' },
+  { key: 'transportType', label: '运输类型', minWidth: 120, formatter: (row: LocalLooseboardOrder) => transportTypeLabels[row.transportType] }, { key: 'origin', prop: 'origin', label: '起运地', minWidth: 145 },
+  { key: 'destination', prop: 'destination', label: '目的地', minWidth: 145 }, { key: 'contactName', prop: 'contactName', label: '联系人', minWidth: 110 },
+  { key: 'contactInfo', prop: 'contactInfo', label: '联系方式', minWidth: 145 }, { key: 'packageCount', prop: 'packageCount', label: '件数', width: 80, align: 'right' },
+  { key: 'totalWeightKg', prop: 'totalWeightKg', label: '总重量(kg)', width: 115, align: 'right' }, { key: 'budgetAmount', label: '预算总价', width: 115, align: 'right', formatter: (row: LocalLooseboardOrder) => row.budgetAmount == null ? '—' : `${row.budgetAmount} ${row.currency}` },
+  { key: 'requestedDate', prop: 'requestedDate', label: '要求时间', width: 120 }, { key: 'status', label: '状态', width: 105, formatter: (row: LocalLooseboardOrder) => looseboardStatusLabels[row.status] },
+  { key: 'createdAt', prop: 'createdAt', label: '创建时间', minWidth: 165, formatter: (row: LocalLooseboardOrder) => formatDateTime(row.createdAt) },
+]
+const columns = computed(() => isLooseboard.value ? looseboardColumns : truckColumns)
+function formatDateTime(value?: string | null) { return value ? value.replace('T', ' ').slice(0, 16) : '—' }
+async function load() {
+  rows.value = []; total.value = 0; loadError.value = null; loading.value = true
+  try {
+    if (isLooseboard.value) {
+      const result = await listLocalLooseboardOrders({ page: page.value, size: pageSize.value, routeKeyword: String(applied.value.routeKeyword || ''), status: String(applied.value.status || '') as LocalLooseboardStatus | '' } satisfies LocalLooseboardQuery)
+      rows.value = result.records; total.value = result.total
+    } else {
+      const result = await listUsTruckOrders({ page: page.value, size: pageSize.value, routeKeyword: String(applied.value.routeKeyword || ''), status: String(applied.value.status || '') as LocalTransportStatus | '' } satisfies LocalTransportQuery)
+      rows.value = result.records; total.value = result.total
+    }
+  } catch (error) { loadError.value = getApiErrorDetails(error, `${domainLabel.value}订单加载失败，请稍后重试`) } finally { loading.value = false }
+}
+function search(model: QueryModel) { applied.value = { ...model }; if (page.value === 1) void load(); else page.value = 1 }
+function openCreate() { void router.push({ name: isLooseboard.value ? 'overseas-business-looseboard-new' : 'overseas-business-truck-new' }) }
+function canEdit(row: LocalTransportOrder | LocalLooseboardOrder) { return isLooseboard.value ? row.status === 'PENDING_ACCEPTANCE' : row.status === 'PENDING_REVIEW' }
+function openEdit(row: LocalTransportOrder | LocalLooseboardOrder) { if (!canEdit(row)) return; void router.push({ name: isLooseboard.value ? 'overseas-business-looseboard-edit' : 'overseas-business-truck-edit', params: { orderId: row.orderNo }, query: { customerId: row.customerId } }) }
+watch([page, pageSize], () => { void load() }); watch(isLooseboard, () => { page.value = 1; applied.value = { status: '', routeKeyword: '' }; filters.value = { ...applied.value }; void load() }); onMounted(() => { void load() })
+</script>
+
+<template>
+  <AdminPage class="admin-density"><ListPageLayout :aria-label="`${domainLabel}订单列表`">
+    <template #toolbar><QueryToolbar v-model="filters" class="surface-panel" :fields="fields" :ariaLabel="`${domainLabel}订单筛选`" :preference-key="queryPreferenceKey" @search="search" /></template>
+    <template v-if="loadError" #state><LoadErrorState :title="`${domainLabel}订单暂时无法加载`" :message="loadError.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="loadError" /></template></LoadErrorState></template>
+    <section v-if="!loadError" class="surface-panel table-panel"><DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :loading="loading" :total="total" :preference-key="`overseas-business-${domain}`" row-key="id" :empty-text="`暂无符合筛选条件的${domainLabel}订单`">
+      <template #toolbar-actions><el-button v-if="access.can(createPermission)" type="primary" @click="openCreate"><Plus :size="16" />新增订单</el-button></template>
+      <template #actions="{ row }"><el-tooltip v-if="access.can(editPermission)" :disabled="canEdit(row as LocalTransportOrder | LocalLooseboardOrder)" content="当前状态不可编辑"><span><el-button class="density-action" data-tone="neutral" size="small" :disabled="!canEdit(row as LocalTransportOrder | LocalLooseboardOrder)" @click="openEdit(row as LocalTransportOrder | LocalLooseboardOrder)">编辑</el-button></span></el-tooltip></template>
+      <template #pagination-left>共 {{ total }} 条{{ domainLabel }}订单</template>
+    </DataTable></section>
+  </ListPageLayout></AdminPage>
+</template>
+
+<style scoped>.table-panel { overflow:hidden; }</style>
diff --git a/src/modules/overseas-business/permissions.ts b/src/modules/overseas-business/permissions.ts
new file mode 100644
index 00000000..09a9840e
--- /dev/null
+++ b/src/modules/overseas-business/permissions.ts
@@ -0,0 +1,13 @@
+export const overseasBusinessPermissions = {
+  purchaseList: 'platform:overseas-business:purchase:list',
+  purchaseEdit: 'platform:overseas-business:purchase:edit',
+  purchaseReview: 'platform:overseas-business:purchase:review',
+  truckList: 'platform:overseas-business:truck:list',
+  truckCreate: 'platform:overseas-business:truck:create',
+  truckEdit: 'platform:overseas-business:truck:edit',
+  truckStatus: 'platform:overseas-business:truck:status',
+  looseboardList: 'platform:overseas-business:looseboard:list',
+  looseboardCreate: 'platform:overseas-business:looseboard:create',
+  looseboardEdit: 'platform:overseas-business:looseboard:edit',
+  looseboardStatus: 'platform:overseas-business:looseboard:status',
+} as const
diff --git a/src/modules/overseas-business/routes.test.ts b/src/modules/overseas-business/routes.test.ts
new file mode 100644
index 00000000..5e68c088
--- /dev/null
+++ b/src/modules/overseas-business/routes.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest'
+import { overseasBusinessPermissions as permission } from './permissions'
+import { overseasBusinessRoutes } from './routes'
+
+describe('overseas business routes', () => {
+  it('keeps the frozen paths and permissions', () => {
+    expect(overseasBusinessRoutes.map((route) => [route.path, route.meta?.permission])).toEqual([
+      ['overseas-business/purchases', permission.purchaseList],
+      ['overseas-business/purchases/:purchaseId', permission.purchaseList],
+      ['overseas-business/purchases/:purchaseId/edit', permission.purchaseEdit],
+      ['overseas-business/trucks', permission.truckList],
+      ['overseas-business/trucks/new', permission.truckCreate],
+      ['overseas-business/trucks/:orderId/edit', permission.truckEdit],
+      ['overseas-business/looseboards', permission.looseboardList],
+      ['overseas-business/looseboards/new', permission.looseboardCreate],
+      ['overseas-business/looseboards/:orderId/edit', permission.looseboardEdit],
+    ])
+  })
+
+  it('does not invent excluded create or detail routes', () => {
+    const paths = overseasBusinessRoutes.map((route) => route.path)
+    expect(paths).not.toContain('overseas-business/purchases/new')
+    expect(paths).not.toContain('overseas-business/trucks/:orderId')
+    expect(paths).not.toContain('overseas-business/looseboards/:orderId')
+    expect(JSON.stringify(overseasBusinessRoutes)).not.toContain('permissionAnyOf')
+  })
+})
diff --git a/src/modules/overseas-business/routes.ts b/src/modules/overseas-business/routes.ts
new file mode 100644
index 00000000..20dc5976
--- /dev/null
+++ b/src/modules/overseas-business/routes.ts
@@ -0,0 +1,65 @@
+import type { RouteRecordRaw } from 'vue-router'
+import { overseasBusinessPermissions as permission } from './permissions'
+
+export const overseasBusinessRoutes = [
+  {
+    path: 'overseas-business/purchases',
+    name: 'overseas-business-purchases',
+    component: () => import('./pages/PurchaseOrdersView.vue'),
+    meta: { title: '海外采购订单', description: '查询海外采购订单与库存变化', permission: permission.purchaseList },
+  },
+  {
+    path: 'overseas-business/purchases/:purchaseId',
+    name: 'overseas-business-purchase-detail',
+    component: () => import('./pages/PurchaseOrderDetailView.vue'),
+    meta: { title: '海外采购订单详情', description: '查看商品、库存、订单、快递与进销存明细', permission: permission.purchaseList, showPageHeading: false },
+  },
+  {
+    path: 'overseas-business/purchases/:purchaseId/edit',
+    name: 'overseas-business-purchase-edit',
+    component: () => import('./pages/PurchaseOrderEditView.vue'),
+    meta: { title: '编辑海外采购订单', description: '维护采购商品、库存和快递信息', permission: permission.purchaseEdit, showPageHeading: false },
+  },
+  {
+    path: 'overseas-business/trucks',
+    name: 'overseas-business-trucks',
+    component: () => import('./pages/TransportOrdersView.vue'),
+    props: { domain: 'truck' },
+    meta: { title: '本土卡车', description: '管理海外本土卡车订单', permission: permission.truckList },
+  },
+  {
+    path: 'overseas-business/trucks/new',
+    name: 'overseas-business-truck-new',
+    component: () => import('./pages/TransportOrderFormView.vue'),
+    props: { domain: 'truck' },
+    meta: { title: '新增本土卡车订单', description: '创建海外本土卡车订单', permission: permission.truckCreate, showPageHeading: false },
+  },
+  {
+    path: 'overseas-business/trucks/:orderId/edit',
+    name: 'overseas-business-truck-edit',
+    component: () => import('./pages/TransportOrderFormView.vue'),
+    props: { domain: 'truck' },
+    meta: { title: '编辑本土卡车订单', description: '维护海外本土卡车订单', permission: permission.truckEdit, showPageHeading: false },
+  },
+  {
+    path: 'overseas-business/looseboards',
+    name: 'overseas-business-looseboards',
+    component: () => import('./pages/TransportOrdersView.vue'),
+    props: { domain: 'looseboard' },
+    meta: { title: '本土散板', description: '管理海外本土散板订单', permission: permission.looseboardList },
+  },
+  {
+    path: 'overseas-business/looseboards/new',
+    name: 'overseas-business-looseboard-new',
+    component: () => import('./pages/TransportOrderFormView.vue'),
+    props: { domain: 'looseboard' },
+    meta: { title: '新增本土散板订单', description: '创建海外本土散板订单', permission: permission.looseboardCreate, showPageHeading: false },
+  },
+  {
+    path: 'overseas-business/looseboards/:orderId/edit',
+    name: 'overseas-business-looseboard-edit',
+    component: () => import('./pages/TransportOrderFormView.vue'),
+    props: { domain: 'looseboard' },
+    meta: { title: '编辑本土散板订单', description: '维护海外本土散板订单', permission: permission.looseboardEdit, showPageHeading: false },
+  },
+] satisfies RouteRecordRaw[]
diff --git a/src/modules/overseas-business/types.ts b/src/modules/overseas-business/types.ts
new file mode 100644
index 00000000..b9fbeeda
--- /dev/null
+++ b/src/modules/overseas-business/types.ts
@@ -0,0 +1,109 @@
+export interface OverseasBusinessPage<T> { records: T[]; page: number; size: number; total: number; pages: number }
+
+export interface OverseasBusinessHistory {
+  operationType?: string | null; fromStatus: string | null; toStatus: string | null
+  operatorId: string | null; changeDetail?: string | null; remark: string | null; createdAt: string
+}
+
+export type OverseasPurchaseStatus = 'PENDING_REVIEW' | 'APPROVED' | 'REJECTED' | 'PENDING_OUTBOUND' | 'PARTIALLY_OUTBOUND' | 'OUTBOUNDED'
+export interface OverseasPurchaseQuery {
+  page?: number; size?: number; customerId?: string; orderNo?: string; customerKeyword?: string
+  purchaseCategory?: string; productName?: string; status?: OverseasPurchaseStatus | ''
+  purchaseWarehouseId?: string; createdFrom?: string; createdTo?: string
+}
+export interface OverseasPurchaseSummary {
+  id: string; orderNo: string; customerId: string; customerName: string | null
+  purchaseCategory: string; productName: string; productSpecification: string | null
+  purchaseQuantity: number; budgetUnitPrice: string | null; currency: string
+  purchaseWarehouseId: string | null; purchaseWarehouseName: string | null
+  inboundQuantity: number; outboundQuantity: number; inventoryQuantity: number
+  status: OverseasPurchaseStatus; version: number; createdAt: string; updatedAt: string
+}
+export interface OverseasPurchaseDetail extends OverseasPurchaseSummary {
+  productUrl: string | null; receivingAddress: string | null; contactName: string | null; contactPhone: string | null
+  domesticCarrier: string | null; domesticTrackingNo: string | null; overseasCarrier: string | null; overseasTrackingNo: string | null
+  estimatedArrivalAt: string | null; remark: string | null; createdBy: string | null; reviewedBy: string | null
+  reviewRemark: string | null; reviewedAt: string | null; histories: OverseasBusinessHistory[]
+  outboundDetails?: OverseasPurchaseOutboundDetail[]
+  files: OverseasPurchaseFile[]; fees: OverseasPurchaseFee[]
+}
+export interface OverseasPurchaseFile { id: string; category: 'RECEIPT' | 'VOUCHER'; fileId: string; fileName: string; contentType: string | null; sizeBytes: number; createdAt: string }
+export interface OverseasPurchaseFee { id: string; feeNo: string; feeItemCode: string; feeItemName: string; amount: string; currency: string; voucherFileId: string; voucherFileName: string; remark: string | null; walletStatus: string; walletErrorMessage: string | null; createdAt: string }
+export interface OverseasPurchaseOutboundDetail { id: string; quantity: number; carrier: string | null; trackingNo: string | null; shippedAt: string | null; remark: string | null }
+export interface OverseasPurchaseCustomerOption { customerId: string; customerName: string }
+export interface OverseasPurchaseWarehouseOption { warehouseId: string; warehouseCode: string; warehouseName: string; countryCode: string }
+export interface UpdateOverseasPurchaseRequest {
+  version: number; purchaseCategory?: string; productName?: string; productSpecification?: string | null
+  productUrl?: string | null; inboundQuantity?: number; purchaseWarehouseId?: string | null
+  domesticCarrier?: string | null; domesticTrackingNo?: string | null; overseasCarrier?: string | null
+  overseasTrackingNo?: string | null; estimatedArrivalAt?: string | null; remark?: string | null
+  outboundDetails?: OverseasPurchaseOutboundDetail[]
+}
+export interface ReviewOverseasPurchaseRequest {
+  version: number
+  decision: 'APPROVE' | 'REJECT'
+  idempotencyKey: string
+  remark?: string
+}
+
+export type LocalTransportType = 'PORT_PICKUP' | 'WAREHOUSE_TO_WAREHOUSE' | 'WAREHOUSE_TO_DOOR'
+export type LocalTransportStatus = 'PENDING_REVIEW' | 'WAITING_INBOUND' | 'RECEIVING' | 'WAITING_CONSOLIDATION' | 'PALLET_OVERAGE_REVIEW' | 'PARTIALLY_ALLOCATED' | 'ALLOCATED' | 'PENDING_DISPATCH' | 'DISPATCHED' | 'IN_TRANSIT' | 'COMPLETED' | 'REJECTED' | 'CANCELLED'
+export interface LocalTransportQuery {
+  page?: number; size?: number; orderNo?: string; routeKeyword?: string; status?: LocalTransportStatus | ''
+  transportType?: LocalTransportType | ''; customerId?: string; requestedFrom?: string; requestedTo?: string
+}
+export interface LocalTransportOrder {
+  id: string; customerId: string; orderNo: string; transportType: LocalTransportType | null
+  origin: string; destination: string; containerType: string | null; palletCount: number; packageCount: number
+  receivedPalletCount: number; allocatedPalletCount: number; shippedPalletCount: number
+  totalWeightKg: string; totalVolumeCbm: string; budgetAmount: string | null; currency: string
+  contactName: string; contactInfo: string; requestedDate: string; status: LocalTransportStatus
+  version: number; createdAt: string; updatedAt: string
+}
+export interface LocalTransportPallet {
+  id: string; palletNo: string; sequenceNo: number; source: string; status: string
+  warehousePalletId: string | null; packageCount: number | null; receivedAt: string | null
+}
+export interface LocalTransportDetail extends LocalTransportOrder {
+  originAddress: string | null; destinationAddress: string | null; remark: string | null; createdBy: string | null
+  pallets: LocalTransportPallet[]; histories: OverseasBusinessHistory[]
+}
+export interface CreateLocalTransportOrderRequest {
+  transportType?: LocalTransportType; origin: string; originAddress?: string | null; destination: string; destinationAddress?: string | null
+  containerType?: string | null; palletCount: number; packageCount?: number; totalWeightKg: number; totalVolumeCbm: number
+  budgetAmount?: number | null; currency?: string; contactName: string; contactInfo: string; requestedDate: string
+  remark?: string | null; idempotencyKey: string
+}
+export interface UpdateLocalTransportOrderRequest {
+  version: number; transportType?: LocalTransportType; origin?: string; originAddress?: string | null
+  destination?: string; destinationAddress?: string | null; containerType?: string | null; palletCount?: number
+  packageCount?: number; totalWeightKg?: number; totalVolumeCbm?: number; budgetAmount?: number | null
+  currency?: string; contactName?: string; contactInfo?: string; requestedDate?: string; remark?: string | null
+}
+
+export type LooseboardTransportMode = 'SHARED_TRUCK' | 'PRIORITY_CONSOLIDATION'
+export type PalletRequired = 'YES' | 'NO'
+export type LocalLooseboardStatus = 'PENDING_ACCEPTANCE' | 'DISPATCHED' | 'IN_TRANSIT' | 'COMPLETED' | 'CANCELLED'
+export interface LocalLooseboardQuery {
+  page?: number; size?: number; customerId?: string; orderNo?: string; routeKeyword?: string
+  status?: LocalLooseboardStatus | ''; transportMode?: LooseboardTransportMode | ''; requestedFrom?: string; requestedTo?: string
+}
+export interface LocalLooseboardOrder {
+  id: string; customerId: string; orderNo: string; transportMode: LooseboardTransportMode; palletRequired: PalletRequired
+  transportType: LocalTransportType; origin: string; destination: string; containerType: string | null; packageCount: number
+  totalWeightKg: string; totalVolumeCbm: string; budgetAmount: string | null; currency: string
+  contactName: string | null; contactInfo: string | null; requestedDate: string | null; status: LocalLooseboardStatus
+  version: number; createdAt: string; updatedAt: string
+}
+export interface LocalLooseboardDetail extends LocalLooseboardOrder {
+  originAddress: string | null; destinationAddress: string | null; remark: string | null; createdBy: string | null
+  histories: OverseasBusinessHistory[]
+}
+export interface CreateLocalLooseboardOrderRequest {
+  transportMode: LooseboardTransportMode; palletRequired: PalletRequired; transportType: LocalTransportType
+  origin: string; originAddress?: string | null; destination: string; destinationAddress?: string | null
+  containerType?: string | null; packageCount: number; totalWeightKg: number; totalVolumeCbm: number
+  budgetAmount?: number | null; currency?: string; contactName?: string | null; contactInfo?: string | null
+  requestedDate?: string | null; remark?: string | null; idempotencyKey: string
+}
+export interface UpdateLocalLooseboardOrderRequest extends Omit<CreateLocalLooseboardOrderRequest, 'idempotencyKey'> { version: number }
diff --git a/src/modules/overseas-master-data/CONTRACT_GAPS.md b/src/modules/overseas-master-data/CONTRACT_GAPS.md
new file mode 100644
index 00000000..e104547b
--- /dev/null
+++ b/src/modules/overseas-master-data/CONTRACT_GAPS.md
@@ -0,0 +1,16 @@
+# 海外通用资料真实接口边界
+
+三域统一经 `overseasHttp` 使用浏览器业务路径 `/platform/v1/last-leg/master-data`，由海外 Gateway 对应到服务端 `/api/platform/v1/last-leg/master-data`。长 ID 始终按字符串处理，分页使用 `records/page/size/total/pages`，更新与状态操作提交 `recordVersion`。
+
+- 报价：已接分页、详情、创建、编辑、启停、CSV 导出和 `/overseas-quotes/warehouse-options`。浏览器不调用国内 `/internal/warehouses/overseas-partners`。
+- 汇率：已接摘要、分页、详情、创建、覆盖编辑、状态和 CSV 导出。
+- 车辆：已接分页、独立详情、创建、编辑、状态和 CSV 导出。
+
+当前明确边界：
+
+- 报价和车辆 Controller/OpenAPI 没有删除端点，前端不展示删除操作。
+- 车辆详情明确不包含派送履约与车辆更换历史；页面保留原型分区并标记当前接口边界，不拼装其他订单数据。
+- 权限资源由总控统一写入 IAM/SQL；本模块只使用 canonical `platform:overseas-master-data:{quote|exchange-rate|vehicle}:{list|create|edit|status|export}`。
+- 报价创建请求包含 `warehouseId`、`versionCode`，编辑请求不提交这两个服务端不可编辑字段；所有编辑与状态请求提交当前 `recordVersion`。
+- 金额、汇率、里程和版本字段在 API 适配层统一转成 `number`，报价与车辆长 ID 保持字符串透传。
+- CSV 下载只接受真实 Blob；JSON 错误 Blob 转为带 `requestId/traceId` 的业务错误，不保存为文件。
diff --git a/src/modules/overseas-master-data/PROTOTYPE_MATRIX.md b/src/modules/overseas-master-data/PROTOTYPE_MATRIX.md
new file mode 100644
index 00000000..e4b689ab
--- /dev/null
+++ b/src/modules/overseas-master-data/PROTOTYPE_MATRIX.md
@@ -0,0 +1,20 @@
+# 海外通用资料原型核对矩阵
+
+事实来源：`docs/悦/货代SAAS平台后台/prototype-src/modules/10-general.html`、`prototype-src/overlays.html`、`prototype-src/app.js`。
+
+| 页面 | 操作 | 原型证据 | 原型承载方式 | 原型尺寸/布局 | 当前实现 | 结论 |
+|---|---|---|---|---|---|---|
+| 合作仓 `gen-partner-warehouse` | 列表/筛选 | `10-general.html:50-56` | 现有仓库管理页内分类 | 自有仓筛选、代码/地址、国家；操作列在表格末尾（与仓库稳定页的全局操作列第一约定冲突时服从全局约定） | 现有仓库页新增 `OVERSEAS_PARTNER` 类型筛选，不新增重复页面 | 使用国内公共仓库接口与 `platform:warehouse:list`；普通 `OVERSEAS` 语义不变 |
+| 合作仓 | 新增/编辑 | `overlays.html:1731-1756`、`app.js:1655-1701` | 居中弹框 `modal-fba-add` | 最大约 560px；单列标签表单 | 复用现有仓库居中弹框，开放 `OVERSEAS_PARTNER` 新增和编辑 | 分别复用 `platform:warehouse:create`、`platform:warehouse:edit`，不跨区域查询报价候选 |
+| 海外仓报价 `gen-overseas-quote` | 列表/筛选 | `10-general.html:152-169`、`app.js:14860-14894` | 独立列表页 | 五项筛选；操作列固定在第一列；横向密集表格 | 已接海外分页与服务端合作仓候选 | 使用 quote:list，不跨区拼装候选 |
+| 海外仓报价 | 详情 | `10-general.html:208-216`、`app.js:14896-14933` | 居中弹框 `modal-gen-overseas-quote-detail` | 约 980px；摘要、仓储作业费用、中转派送价格 | 已接真实详情弹框 | 使用 quote:list |
+| 海外仓报价 | 新增/编辑 | `10-general.html:177-204`、`app.js:14935-15055` | 居中弹框 `modal-gen-overseas-quote` | 最大约 1180px；基础信息、费用明细、派送价格；正文滚动 | 已接真实创建/编辑与 recordVersion | quote:create/edit 独立校验 |
+| 海外仓报价 | 启停/删除/导出 | `10-general.html:154-169`、`app.js:15056-15070` | 启停、删除为列表行操作；导出在工具栏 | 操作列第一列 | 已接真实启停与 CSV 导出；服务端无删除端点，未展示删除 | quote:status/export 独立校验；不推断 DELETE |
+| 汇率管理 `gen-exchange-rate` | 列表/筛选 | `10-general.html:21-33`、`app.js:3673-3699` | 独立列表页 | 四项摘要；月份筛选；8 列表格 | 已接摘要与真实分页 | 统一展示 `1 USD = X CNY` |
+| 汇率管理 | 更新/编辑 | `overlays.html:1695-1704`、`app.js:3701-3728` | 居中弹框 `modal-exchange-rate-edit` | 560px；月份、平均汇率、备注；已有月份覆盖提示 | 已接创建/覆盖、状态与导出 | recordVersion 冲突保留服务端错误 |
+| 车辆 `vehicle` | 列表/筛选 | `10-general.html:299-351`、`app.js:10437-10456`；当前对话于 2026-08-19 修正双页签问题，并指定复用统一订单列表 `UnifiedOrdersView.vue` 的 `status-tabs` 样式 | 独立列表页 | 原型同时使用国内/海外区域页签与自有/外派归属页签，形成重复主切换；原型操作列在末尾 | 已接真实分页；区域降为查询下拉框，仅保留自有/外派归属页签；操作列按全局约定移到第一列 | 当前对话确认高于原型；查询提交 ownership/region/status，不拼装数据 |
+| 车辆 | 详情 | `10-general.html:421-448`、`app.js:10546-10591` | 独立页面 `vehicle-detail` | 紧凑页头；车辆信息、派送订单明细、更换记录 | 已接真实车辆详情；履约与更换区显示后端明确排除说明 | 不拼装订单/派送数据 |
+| 车辆 | 新增/编辑 | `10-general.html:363-394`、`app.js:10458-10529` | 居中弹框 `modal-vehicle-edit` | 760px；两列表单，窄屏单列退化 | 已接创建/编辑、独立状态与导出 | create/edit/status 权限独立 |
+| 车辆 | 删除/导出 | `10-general.html:302-351`、`app.js:10437-10456` | 删除为列表行操作；导出在工具栏 | 原型列表操作 | 已接真实 CSV 导出；服务端无删除端点，未展示删除 | vehicle:export 独立校验；不推断 DELETE |
+
+原型未定义车辆文件预览、审核/确认流程；本模块不自行补充。
diff --git a/src/modules/overseas-master-data/api/overseasMasterData.test.ts b/src/modules/overseas-master-data/api/overseasMasterData.test.ts
new file mode 100644
index 00000000..d192ff54
--- /dev/null
+++ b/src/modules/overseas-master-data/api/overseasMasterData.test.ts
@@ -0,0 +1,145 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { ApiResponseError } from '@/shared/api/http'
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import {
+  changeExchangeRateStatus, changeQuoteStatus, changeVehicleStatus, createExchangeRate, createQuote, createVehicle,
+  exportExchangeRates, exportQuotes, exportVehicles, getExchangeRate, getExchangeRateSummary, getQuote, getVehicle,
+  listExchangeRates, listQuotes, listQuoteWarehouseOptions, listVehicles, updateExchangeRate, updateQuote, updateVehicle,
+  type QuoteCreate, type QuoteUpdate,
+} from './overseasMasterData'
+
+vi.mock('@/shared/api/overseasHttp', () => ({ overseasHttp: { get: vi.fn(), post: vi.fn(), put: vi.fn(), patch: vi.fn() } }))
+const ok = (data: unknown) => ({ code: '200', message: 'success', data })
+const longId = '9223372036854775807'
+const quoteSummary = {
+  id: longId, name: '报价', warehouseId: '9223372036854775806', warehouseCode: 'US-LAX', warehouseName: '洛杉矶合作仓',
+  countryCode: 'US', providerName: '服务商', currency: 'USD', effectiveStart: '2026-08-01', effectiveEnd: '2026-12-31',
+  versionCode: 'V1', status: 'INACTIVE', recordVersion: '7', updatedBy: 'admin', updatedAt: '2026-08-24T10:00:00', remark: null,
+}
+const quoteDetail = {
+  summary: quoteSummary,
+  warehouseFees: [{ item: '入库', billingUnit: 'PALLET', unitPrice: '1.2500', minimumCharge: '2.5000', remark: null }],
+  transitPrices: [{ fbaWarehouseCode: 'ONT8', deliveryMethod: 'TRUCK', estimatedMiles: '12.50', price: '18.7500', minimumCharge: null, remark: null }],
+  createdBy: 'admin', createdAt: '2026-08-24T09:00:00',
+}
+const exchangeRate = { month: '2026-08', baseCurrency: 'USD', quoteCurrency: 'CNY', usdToCnyAverage: '7.12345678', status: 'ACTIVE', recordVersion: '3', updatedBy: 'admin', updatedAt: '2026-08-24T10:00:00', remark: null }
+const vehicle = { id: longId, plateNumber: 'CA-01', model: 'Truck', fuelConsumptionPer100Km: '12.50', mileageKm: '101', driverOrDispatchCompany: null, phone: null, region: 'OVERSEAS', ownership: 'OWNED', status: 'IN_SERVICE', remark: null, recordVersion: '4', updatedBy: 'admin', updatedAt: '2026-08-24T10:00:00' }
+
+beforeEach(() => vi.clearAllMocks())
+
+describe('overseas master data API', () => {
+  it('normalizes quote page/detail decimals and preserves long string IDs', async () => {
+    vi.mocked(overseasHttp.get)
+      .mockResolvedValueOnce(ok({ records: [quoteSummary], page: '1', size: '20', total: '1', pages: '1' }))
+      .mockResolvedValueOnce(ok(quoteDetail))
+      .mockResolvedValueOnce(ok([{ warehouseId: quoteSummary.warehouseId, warehouseCode: 'US-LAX', warehouseName: '洛杉矶合作仓', countryCode: 'US' }]))
+
+    const result = await listQuotes({ page: 1, size: 20, keyword: 'V1' })
+    expect(result).toMatchObject({ page: 1, size: 20, total: 1, pages: 1 })
+    expect(result.records[0]).toMatchObject({ id: longId, warehouseId: quoteSummary.warehouseId, recordVersion: 7 })
+    const detail = await getQuote(longId)
+    expect(detail.summary.id).toBe(longId)
+    expect(detail.summary.recordVersion).toBe(7)
+    expect(detail.warehouseFees[0]).toMatchObject({ unitPrice: 1.25, minimumCharge: 2.5 })
+    expect(detail.transitPrices[0]).toMatchObject({ estimatedMiles: 12.5, price: 18.75, minimumCharge: null })
+    await listQuoteWarehouseOptions()
+
+    expect(overseasHttp.get).toHaveBeenNthCalledWith(1, '/platform/v1/last-leg/master-data/overseas-quotes', { params: { page: 1, size: 20, keyword: 'V1' } })
+    expect(overseasHttp.get).toHaveBeenNthCalledWith(2, `/platform/v1/last-leg/master-data/overseas-quotes/${longId}`)
+    expect(overseasHttp.get).toHaveBeenNthCalledWith(3, '/platform/v1/last-leg/master-data/overseas-quotes/warehouse-options')
+  })
+
+  it('keeps quote create/update DTOs distinct and sends recordVersion on writes', async () => {
+    const create: QuoteCreate = {
+      name: '报价', warehouseId: quoteSummary.warehouseId, providerName: '服务商', currency: 'USD',
+      effectiveStart: '2026-08-01', effectiveEnd: '2026-12-31', versionCode: 'V1',
+      warehouseFees: [{ item: '入库', billingUnit: 'PALLET', unitPrice: 1.25, minimumCharge: null, remark: null }],
+      transitPrices: [], remark: null,
+    }
+    const update: QuoteUpdate = {
+      name: '报价-编辑', providerName: '服务商', currency: 'USD', effectiveStart: '2026-08-01', effectiveEnd: '2026-12-31',
+      warehouseFees: create.warehouseFees, transitPrices: [], remark: null, recordVersion: 7,
+    }
+    vi.mocked(overseasHttp.post).mockResolvedValue(ok(quoteDetail))
+    vi.mocked(overseasHttp.put).mockResolvedValue(ok({ ...quoteDetail, summary: { ...quoteSummary, recordVersion: '8' } }))
+    vi.mocked(overseasHttp.patch).mockResolvedValue(ok({ ...quoteDetail, summary: { ...quoteSummary, status: 'ACTIVE', recordVersion: '9' } }))
+
+    await createQuote(create)
+    const updated = await updateQuote(longId, update)
+    await changeQuoteStatus(longId, 'ACTIVE', 8)
+
+    expect(updated.summary.recordVersion).toBe(8)
+    expect(overseasHttp.post).toHaveBeenCalledWith('/platform/v1/last-leg/master-data/overseas-quotes', create)
+    expect(overseasHttp.put).toHaveBeenCalledWith(`/platform/v1/last-leg/master-data/overseas-quotes/${longId}`, update)
+    expect(overseasHttp.patch).toHaveBeenCalledWith(`/platform/v1/last-leg/master-data/overseas-quotes/${longId}/status`, { status: 'ACTIVE', recordVersion: 8 })
+    expect(update).not.toHaveProperty('warehouseId')
+    expect(update).not.toHaveProperty('versionCode')
+  })
+
+  it('normalizes exchange-rate decimal/version and uses month as the stable key', async () => {
+    vi.mocked(overseasHttp.get)
+      .mockResolvedValueOnce(ok({ records: [exchangeRate], page: '1', size: '20', total: '1', pages: '1' }))
+      .mockResolvedValueOnce(ok(exchangeRate))
+      .mockResolvedValueOnce(ok({ latestMonth: '2026-08', latestUsdToCnyAverage: '7.12345678', updatedBy: 'admin', updatedAt: '2026-08-24T10:00:00' }))
+    const page = await listExchangeRates({ page: 1, size: 20, monthFrom: '2026-08', monthTo: '2026-08' })
+    const detail = await getExchangeRate('2026-08')
+    const summary = await getExchangeRateSummary()
+    expect(page.records[0]).toMatchObject({ usdToCnyAverage: 7.12345678, recordVersion: 3 })
+    expect(detail).toMatchObject({ month: '2026-08', usdToCnyAverage: 7.12345678, recordVersion: 3 })
+    expect(summary.latestUsdToCnyAverage).toBe(7.12345678)
+
+    vi.mocked(overseasHttp.post).mockResolvedValue(ok(exchangeRate))
+    vi.mocked(overseasHttp.put).mockResolvedValue(ok({ ...exchangeRate, recordVersion: '4' }))
+    vi.mocked(overseasHttp.patch).mockResolvedValue(ok({ ...exchangeRate, status: 'INACTIVE', recordVersion: '5' }))
+    await createExchangeRate({ month: '2026-08', usdToCnyAverage: 7.12345678, remark: null })
+    await updateExchangeRate('2026-08', { recordVersion: 3, usdToCnyAverage: 7.2, remark: null })
+    await changeExchangeRateStatus('2026-08', 'INACTIVE', 4, '停用')
+    expect(overseasHttp.patch).toHaveBeenLastCalledWith('/platform/v1/last-leg/master-data/exchange-rates/2026-08/status', { status: 'INACTIVE', recordVersion: 4, remark: '停用' })
+  })
+
+  it('normalizes vehicle decimals/version while preserving long string IDs', async () => {
+    vi.mocked(overseasHttp.get)
+      .mockResolvedValueOnce(ok({ records: [vehicle], page: '1', size: '20', total: '1', pages: '1' }))
+      .mockResolvedValueOnce(ok(vehicle))
+    const result = await listVehicles({ page: 1, size: 20, ownership: 'OWNED' })
+    const detail = await getVehicle(longId)
+    expect(result.records[0]).toMatchObject({ id: longId, fuelConsumptionPer100Km: 12.5, mileageKm: 101, recordVersion: 4 })
+    expect(detail.id).toBe(longId)
+
+    const editable = { plateNumber: 'CA-01', model: 'Truck', fuelConsumptionPer100Km: 12.5, mileageKm: 101, driverOrDispatchCompany: null, phone: null, region: 'OVERSEAS' as const, ownership: 'OWNED' as const, remark: null }
+    vi.mocked(overseasHttp.post).mockResolvedValue(ok(vehicle))
+    vi.mocked(overseasHttp.put).mockResolvedValue(ok({ ...vehicle, recordVersion: '5' }))
+    vi.mocked(overseasHttp.patch).mockResolvedValue(ok({ ...vehicle, status: 'INACTIVE', recordVersion: '6' }))
+    await createVehicle({ ...editable, status: 'IN_SERVICE' })
+    await updateVehicle(longId, { ...editable, recordVersion: 4 })
+    await changeVehicleStatus(longId, 'INACTIVE', 5)
+    expect(overseasHttp.put).toHaveBeenCalledWith(`/platform/v1/last-leg/master-data/vehicles/${longId}`, { ...editable, recordVersion: 4 })
+    expect(overseasHttp.patch).toHaveBeenCalledWith(`/platform/v1/last-leg/master-data/vehicles/${longId}/status`, { status: 'INACTIVE', recordVersion: 5 })
+  })
+
+  it('preserves A0409 metadata instead of translating it into success', async () => {
+    vi.mocked(overseasHttp.put).mockResolvedValue({ code: 'A0409', message: '记录版本已变化', data: null, requestId: 'request-conflict', traceId: 'trace-conflict' })
+    const error = await updateExchangeRate('2026-08', { recordVersion: 1, usdToCnyAverage: 7.2, remark: null }).catch((reason: unknown) => reason)
+    expect(error).toBeInstanceOf(ApiResponseError)
+    expect(error).toMatchObject({ code: 'A0409', message: '记录版本已变化', requestId: 'request-conflict', traceId: 'trace-conflict' })
+  })
+
+  it('downloads real CSV Blobs and rejects JSON error Blobs with trace metadata', async () => {
+    const csv = new Blob(['id,status\n1,ACTIVE\n'], { type: 'text/csv;charset=UTF-8' })
+    vi.mocked(overseasHttp.get)
+      .mockResolvedValueOnce(csv)
+      .mockResolvedValueOnce(csv)
+      .mockResolvedValueOnce(csv)
+      .mockResolvedValueOnce(new Blob([JSON.stringify({ code: 'A0409', message: '导出条件已变化', data: null, requestId: 'request-export' })], { type: 'application/json' }))
+
+    await expect(exportQuotes({ status: 'ACTIVE' })).resolves.toBe(csv)
+    await expect(exportExchangeRates({})).resolves.toBe(csv)
+    await expect(exportVehicles({ ownership: 'OWNED' })).resolves.toBe(csv)
+    const error = await exportVehicles({}).catch((reason: unknown) => reason)
+    expect(error).toBeInstanceOf(ApiResponseError)
+    expect(error).toMatchObject({ code: 'A0409', message: '导出条件已变化', requestId: 'request-export' })
+    expect(overseasHttp.get).toHaveBeenNthCalledWith(1, '/platform/v1/last-leg/master-data/overseas-quotes/export', { params: { status: 'ACTIVE' }, responseType: 'arraybuffer' })
+    expect(overseasHttp.get).toHaveBeenNthCalledWith(2, '/platform/v1/last-leg/master-data/exchange-rates/export', { params: {}, responseType: 'arraybuffer' })
+    expect(overseasHttp.get).toHaveBeenNthCalledWith(3, '/platform/v1/last-leg/master-data/vehicles/export', { params: { ownership: 'OWNED' }, responseType: 'arraybuffer' })
+  })
+})
diff --git a/src/modules/overseas-master-data/api/overseasMasterData.ts b/src/modules/overseas-master-data/api/overseasMasterData.ts
new file mode 100644
index 00000000..53901045
--- /dev/null
+++ b/src/modules/overseas-master-data/api/overseasMasterData.ts
@@ -0,0 +1,124 @@
+import axios from 'axios'
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { ApiResponseError, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import type {
+  MasterDataStatus, MonthlyExchangeRate, OverseasTransitPrice, OverseasWarehouseFee, OverseasWarehouseQuote, OverseasWarehouseQuoteDetail, PartnerWarehouseOption,
+  VehicleDetail, VehicleOwnership, VehicleRegion, VehicleStatus,
+} from '../types'
+
+export interface PageResult<T> { records: T[]; page: number; size: number; total: number; pages: number }
+type PagePayload<T> = Omit<PageResult<T>, 'page' | 'size' | 'total' | 'pages'> & { page: number | string; size: number | string; total: number | string; pages: number | string }
+const base = '/platform/v1/last-leg/master-data'
+type Numeric = number | string
+type QuoteWire = Omit<OverseasWarehouseQuote, 'recordVersion'> & { recordVersion: Numeric }
+type FeeWire = Omit<OverseasWarehouseFee, 'unitPrice' | 'minimumCharge'> & { unitPrice: Numeric; minimumCharge: Numeric | null }
+type TransitPriceWire = Omit<OverseasTransitPrice, 'estimatedMiles' | 'price' | 'minimumCharge'> & { estimatedMiles: Numeric | null; price: Numeric; minimumCharge: Numeric | null }
+type QuoteDetailWire = Omit<OverseasWarehouseQuoteDetail, 'summary' | 'warehouseFees' | 'transitPrices'> & { summary: QuoteWire; warehouseFees: FeeWire[]; transitPrices: TransitPriceWire[] }
+type ExchangeRateWire = Omit<MonthlyExchangeRate, 'usdToCnyAverage' | 'recordVersion'> & { usdToCnyAverage: Numeric; recordVersion: Numeric }
+type ExchangeRateSummary = { latestMonth: string | null; latestUsdToCnyAverage: number | null; updatedBy: string | null; updatedAt: string | null }
+type ExchangeRateSummaryWire = Omit<ExchangeRateSummary, 'latestUsdToCnyAverage'> & { latestUsdToCnyAverage: Numeric | null }
+type VehicleWire = Omit<VehicleDetail, 'fuelConsumptionPer100Km' | 'mileageKm' | 'recordVersion'> & { fuelConsumptionPer100Km: Numeric; mileageKm: Numeric; recordVersion: Numeric }
+
+function page<T, W>(value: PagePayload<W>, normalize: (record: W) => T): PageResult<T> {
+  return { ...value, records: value.records.map(normalize), page: Number(value.page), size: Number(value.size), total: Number(value.total), pages: Number(value.pages) }
+}
+async function getPage<T, W>(path: string, params: object, normalize: (record: W) => T) {
+  return page(unwrapApiResponse(await overseasHttp.get<ApiEnvelope<PagePayload<W>>, ApiEnvelope<PagePayload<W>>>(path, { params })), normalize)
+}
+const numeric = (value: Numeric) => Number(value)
+const nullableNumeric = (value: Numeric | null) => value == null ? null : Number(value)
+const normalizeQuote = (value: QuoteWire): OverseasWarehouseQuote => ({ ...value, recordVersion: numeric(value.recordVersion) })
+const normalizeFee = (value: FeeWire): OverseasWarehouseFee => ({ ...value, unitPrice: numeric(value.unitPrice), minimumCharge: nullableNumeric(value.minimumCharge) })
+const normalizeTransitPrice = (value: TransitPriceWire): OverseasTransitPrice => ({ ...value, estimatedMiles: nullableNumeric(value.estimatedMiles), price: numeric(value.price), minimumCharge: nullableNumeric(value.minimumCharge) })
+const normalizeQuoteDetail = (value: QuoteDetailWire): OverseasWarehouseQuoteDetail => ({ ...value, summary: normalizeQuote(value.summary), warehouseFees: value.warehouseFees.map(normalizeFee), transitPrices: value.transitPrices.map(normalizeTransitPrice) })
+const normalizeExchangeRate = (value: ExchangeRateWire): MonthlyExchangeRate => ({ ...value, usdToCnyAverage: numeric(value.usdToCnyAverage), recordVersion: numeric(value.recordVersion) })
+const normalizeVehicle = (value: VehicleWire): VehicleDetail => ({ ...value, fuelConsumptionPer100Km: numeric(value.fuelConsumptionPer100Km), mileageKm: numeric(value.mileageKm), recordVersion: numeric(value.recordVersion) })
+
+type DownloadPayload = Blob | ArrayBuffer | ArrayBufferView | string
+
+async function downloadText(payload: DownloadPayload) {
+  if (typeof payload === 'string') return payload
+  if (payload instanceof Blob) return payload.text()
+  const bytes = payload instanceof ArrayBuffer
+    ? new Uint8Array(payload)
+    : new Uint8Array(payload.buffer, payload.byteOffset, payload.byteLength)
+  return new TextDecoder().decode(bytes)
+}
+
+async function csvError(payload: DownloadPayload, status: number) {
+  const contentType = payload instanceof Blob ? payload.type.toLowerCase() : ''
+  const text = await downloadText(payload)
+  if (!contentType.includes('json') && !/^\s*[\[{]/.test(text)) return null
+  try {
+    const envelope = JSON.parse(text) as Partial<ApiEnvelope<unknown>>
+    if (!envelope || typeof envelope !== 'object' || Array.isArray(envelope)) throw new Error('invalid envelope')
+    return new ApiResponseError(envelope.message || 'CSV 导出失败', envelope.code || 'DOWNLOAD_FAILED', status,
+      envelope.data, envelope.requestId, envelope.traceId)
+  } catch (error) {
+    if (error instanceof ApiResponseError) return error
+    return new ApiResponseError('CSV 导出接口返回了无法识别的 JSON 响应', 'INVALID_DOWNLOAD_RESPONSE', status)
+  }
+}
+function csvBlob(payload: DownloadPayload) {
+  if (payload instanceof Blob) return payload
+  if (typeof payload === 'string') return new Blob([payload], { type: 'text/csv;charset=utf-8' })
+  const bytes = payload instanceof ArrayBuffer
+    ? new Uint8Array(payload)
+    : new Uint8Array(payload.buffer, payload.byteOffset, payload.byteLength)
+  const copy = new Uint8Array(bytes.byteLength)
+  copy.set(bytes)
+  return new Blob([copy.buffer], { type: 'text/csv;charset=utf-8' })
+}
+async function download(path: string, params: object) {
+  try {
+    const payload = await overseasHttp.get<DownloadPayload, DownloadPayload>(path, { params, responseType: 'arraybuffer' })
+    const error = await csvError(payload, 200)
+    if (error) throw error
+    return csvBlob(payload)
+  } catch (error) {
+    const axiosError = axios.isAxiosError(error) ? error : null
+    const responsePayload = axiosError?.response?.data as DownloadPayload | undefined
+    if (responsePayload !== undefined) {
+      const responseError = await csvError(responsePayload, axiosError?.response?.status || 0)
+      if (responseError) throw responseError
+    }
+    throw error
+  }
+}
+
+export interface QuoteQuery { page: number; size: number; keyword?: string; warehouseId?: string; providerName?: string; currency?: string; status?: MasterDataStatus }
+type QuoteDetailFields = { warehouseFees: OverseasWarehouseFee[]; transitPrices: OverseasTransitPrice[] }
+type QuoteEditableFields = Pick<OverseasWarehouseQuote, 'name' | 'providerName' | 'currency' | 'effectiveStart' | 'remark'>
+  & { effectiveEnd: string } & QuoteDetailFields
+export type QuoteCreate = QuoteEditableFields & Pick<OverseasWarehouseQuote, 'warehouseId' | 'versionCode'>
+export type QuoteUpdate = QuoteEditableFields & Pick<OverseasWarehouseQuote, 'recordVersion'>
+export const listQuotes = (query: QuoteQuery) => getPage<OverseasWarehouseQuote, QuoteWire>(`${base}/overseas-quotes`, query, normalizeQuote)
+export async function getQuote(id: string) { return normalizeQuoteDetail(unwrapApiResponse(await overseasHttp.get<ApiEnvelope<QuoteDetailWire>, ApiEnvelope<QuoteDetailWire>>(`${base}/overseas-quotes/${encodeURIComponent(id)}`))) }
+export async function listQuoteWarehouseOptions() { return unwrapApiResponse(await overseasHttp.get<ApiEnvelope<PartnerWarehouseOption[]>, ApiEnvelope<PartnerWarehouseOption[]>>(`${base}/overseas-quotes/warehouse-options`)) }
+export async function createQuote(payload: QuoteCreate) { return normalizeQuoteDetail(unwrapApiResponse(await overseasHttp.post<ApiEnvelope<QuoteDetailWire>, ApiEnvelope<QuoteDetailWire>>(`${base}/overseas-quotes`, payload))) }
+export async function updateQuote(id: string, payload: QuoteUpdate) { return normalizeQuoteDetail(unwrapApiResponse(await overseasHttp.put<ApiEnvelope<QuoteDetailWire>, ApiEnvelope<QuoteDetailWire>>(`${base}/overseas-quotes/${encodeURIComponent(id)}`, payload))) }
+export async function changeQuoteStatus(id: string, status: MasterDataStatus, recordVersion: number) { return normalizeQuoteDetail(unwrapApiResponse(await overseasHttp.patch<ApiEnvelope<QuoteDetailWire>, ApiEnvelope<QuoteDetailWire>>(`${base}/overseas-quotes/${encodeURIComponent(id)}/status`, { status, recordVersion }))) }
+export const exportQuotes = (query: Omit<QuoteQuery, 'page' | 'size'>) => download(`${base}/overseas-quotes/export`, query)
+
+export interface ExchangeRateQuery { page: number; size: number; monthFrom?: string; monthTo?: string; status?: MasterDataStatus }
+export const listExchangeRates = (query: ExchangeRateQuery) => getPage<MonthlyExchangeRate, ExchangeRateWire>(`${base}/exchange-rates`, query, normalizeExchangeRate)
+export async function getExchangeRate(month: string) { return normalizeExchangeRate(unwrapApiResponse(await overseasHttp.get<ApiEnvelope<ExchangeRateWire>, ApiEnvelope<ExchangeRateWire>>(`${base}/exchange-rates/${encodeURIComponent(month)}`))) }
+export async function getExchangeRateSummary(): Promise<ExchangeRateSummary> {
+  const value = unwrapApiResponse(await overseasHttp.get<ApiEnvelope<ExchangeRateSummaryWire>, ApiEnvelope<ExchangeRateSummaryWire>>(`${base}/exchange-rates/summary`))
+  return { ...value, latestUsdToCnyAverage: nullableNumeric(value.latestUsdToCnyAverage) }
+}
+export async function createExchangeRate(payload: { month: string; usdToCnyAverage: number; remark: string | null }) { return normalizeExchangeRate(unwrapApiResponse(await overseasHttp.post<ApiEnvelope<ExchangeRateWire>, ApiEnvelope<ExchangeRateWire>>(`${base}/exchange-rates`, payload))) }
+export async function updateExchangeRate(month: string, payload: { recordVersion: number; usdToCnyAverage: number; remark: string | null }) { return normalizeExchangeRate(unwrapApiResponse(await overseasHttp.put<ApiEnvelope<ExchangeRateWire>, ApiEnvelope<ExchangeRateWire>>(`${base}/exchange-rates/${encodeURIComponent(month)}`, payload))) }
+export async function changeExchangeRateStatus(month: string, status: MasterDataStatus, recordVersion: number, remark: string | null) { return normalizeExchangeRate(unwrapApiResponse(await overseasHttp.patch<ApiEnvelope<ExchangeRateWire>, ApiEnvelope<ExchangeRateWire>>(`${base}/exchange-rates/${encodeURIComponent(month)}/status`, { status, recordVersion, remark }))) }
+export const exportExchangeRates = (query: Omit<ExchangeRateQuery, 'page' | 'size'>) => download(`${base}/exchange-rates/export`, query)
+
+export interface VehicleQuery { page: number; size: number; keyword?: string; ownership?: VehicleOwnership; region?: VehicleRegion; status?: VehicleStatus }
+type VehicleEditableFields = Omit<VehicleDetail, 'id' | 'recordVersion' | 'updatedBy' | 'updatedAt' | 'status'>
+export type VehicleCreate = VehicleEditableFields & Pick<VehicleDetail, 'status'>
+export type VehicleUpdate = VehicleEditableFields & Pick<VehicleDetail, 'recordVersion'>
+export const listVehicles = (query: VehicleQuery) => getPage<VehicleDetail, VehicleWire>(`${base}/vehicles`, query, normalizeVehicle)
+export async function getVehicle(id: string) { return normalizeVehicle(unwrapApiResponse(await overseasHttp.get<ApiEnvelope<VehicleWire>, ApiEnvelope<VehicleWire>>(`${base}/vehicles/${encodeURIComponent(id)}`))) }
+export async function createVehicle(payload: VehicleCreate) { return normalizeVehicle(unwrapApiResponse(await overseasHttp.post<ApiEnvelope<VehicleWire>, ApiEnvelope<VehicleWire>>(`${base}/vehicles`, payload))) }
+export async function updateVehicle(id: string, payload: VehicleUpdate) { return normalizeVehicle(unwrapApiResponse(await overseasHttp.put<ApiEnvelope<VehicleWire>, ApiEnvelope<VehicleWire>>(`${base}/vehicles/${encodeURIComponent(id)}`, payload))) }
+export async function changeVehicleStatus(id: string, status: VehicleStatus, recordVersion: number) { return normalizeVehicle(unwrapApiResponse(await overseasHttp.patch<ApiEnvelope<VehicleWire>, ApiEnvelope<VehicleWire>>(`${base}/vehicles/${encodeURIComponent(id)}/status`, { status, recordVersion }))) }
+export const exportVehicles = (query: Omit<VehicleQuery, 'page' | 'size'>) => download(`${base}/vehicles/export`, query)
diff --git a/src/modules/overseas-master-data/apiError.ts b/src/modules/overseas-master-data/apiError.ts
new file mode 100644
index 00000000..f72f5f5c
--- /dev/null
+++ b/src/modules/overseas-master-data/apiError.ts
@@ -0,0 +1,7 @@
+import { getApiErrorDetails } from '@/shared/api/http'
+
+export function masterDataErrorMessage(error: unknown, fallback: string) {
+  const details = getApiErrorDetails(error, fallback)
+  const reference = details.requestId || details.traceId
+  return reference ? `${details.message}（请求标识：${reference}）` : details.message
+}
diff --git a/src/modules/overseas-master-data/components/ContractPendingNotice.vue b/src/modules/overseas-master-data/components/ContractPendingNotice.vue
new file mode 100644
index 00000000..208fdf3a
--- /dev/null
+++ b/src/modules/overseas-master-data/components/ContractPendingNotice.vue
@@ -0,0 +1,14 @@
+<script setup lang="ts">
+withDefaults(defineProps<{ domain: string; detail?: boolean }>(), { detail: false })
+</script>
+
+<template>
+  <el-alert class="contract-pending" type="warning" :closable="false" show-icon>
+    <template #title>{{ domain }}海外区域接口待接入</template>
+    <p>{{ detail ? '当前详情没有可查询的真实记录。' : '页面已按四期原型冻结字段与布局。' }}海外请求统一经 gateway-overseas；在统一 Base/Token 选择及本页面端点、DTO 与权限适配完成前，不展示演示数据，也不会模拟查询或写操作成功。</p>
+  </el-alert>
+</template>
+
+<style scoped>
+.contract-pending p { margin: 5px 0 0; color: var(--el-text-color-regular); font-size: 13px; line-height: 1.55; }
+</style>
diff --git a/src/modules/overseas-master-data/downloadCsv.test.ts b/src/modules/overseas-master-data/downloadCsv.test.ts
new file mode 100644
index 00000000..4ddd11f1
--- /dev/null
+++ b/src/modules/overseas-master-data/downloadCsv.test.ts
@@ -0,0 +1,29 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { saveCsv } from '@/shared/downloadCsv'
+
+describe('saveCsv', () => {
+  beforeEach(() => vi.stubGlobal('URL', { createObjectURL: vi.fn(), revokeObjectURL: vi.fn() }))
+  afterEach(() => { vi.restoreAllMocks(); vi.unstubAllGlobals() })
+
+  it('downloads the provided Blob with the requested file name and always revokes the URL', () => {
+    const blob = new Blob(['id,status\n1,ACTIVE\n'], { type: 'text/csv;charset=UTF-8' })
+    const createObjectURL = vi.mocked(URL.createObjectURL).mockReturnValue('blob:overseas-master-data')
+    const revokeObjectURL = vi.mocked(URL.revokeObjectURL)
+    const click = vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(() => undefined)
+
+    saveCsv(blob, 'vehicles.csv')
+
+    expect(createObjectURL).toHaveBeenCalledWith(blob)
+    expect(click).toHaveBeenCalledOnce()
+    expect(revokeObjectURL).toHaveBeenCalledWith('blob:overseas-master-data')
+  })
+
+  it('revokes the Blob URL even when the browser click fails', () => {
+    vi.mocked(URL.createObjectURL).mockReturnValue('blob:failed-download')
+    const revokeObjectURL = vi.mocked(URL.revokeObjectURL)
+    vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(() => { throw new Error('browser blocked') })
+
+    expect(() => saveCsv(new Blob(['csv']), 'quotes.csv')).toThrow('browser blocked')
+    expect(revokeObjectURL).toHaveBeenCalledWith('blob:failed-download')
+  })
+})
diff --git a/src/modules/overseas-master-data/index.ts b/src/modules/overseas-master-data/index.ts
new file mode 100644
index 00000000..2f9deabc
--- /dev/null
+++ b/src/modules/overseas-master-data/index.ts
@@ -0,0 +1,3 @@
+export { overseasMasterDataRoutes } from './routes'
+export { overseasMasterDataPermissions } from './permissions'
+export type * from './types'
diff --git a/src/modules/overseas-master-data/pages/ExchangeRatesView.vue b/src/modules/overseas-master-data/pages/ExchangeRatesView.vue
new file mode 100644
index 00000000..f06b385e
--- /dev/null
+++ b/src/modules/overseas-master-data/pages/ExchangeRatesView.vue
@@ -0,0 +1,59 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { onMounted, reactive, ref, watch } from 'vue'
+import { Download, Plus } from '@lucide/vue'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { changeExchangeRateStatus, createExchangeRate, exportExchangeRates, getExchangeRate, getExchangeRateSummary, listExchangeRates, updateExchangeRate } from '../api/overseasMasterData'
+import { overseasMasterDataPermissions as permission } from '../permissions'
+import { saveCsv } from '@/shared/downloadCsv'
+import { masterDataErrorMessage } from '../apiError'
+import type { MasterDataStatus, MonthlyExchangeRate } from '../types'
+
+const access = useAccessPreviewStore()
+const rows = ref<MonthlyExchangeRate[]>([]), total = ref(0), page = ref(1), pageSize = ref(20), loading = ref(false), saving = ref(false), exporting = ref(false)
+const error = ref<ApiErrorDetails | null>(null), editorOpen = ref(false), editingMonth = ref('')
+const filters = ref<QueryModel>({ month: '', status: '' })
+const fields: QueryField[] = [
+  { key: 'month', type: 'date', label: '查询月份', placeholder: '请选择月份', width: 200, props: { type: 'month', 'value-format': 'YYYY-MM' } },
+  { key: 'status', type: 'select', label: '状态', placeholder: '全部状态', width: 130, options: [{ label: '启用', value: 'ACTIVE' }, { label: '停用', value: 'INACTIVE' }] },
+]
+const columns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 230, fixed: 'left', slotName: 'actions' }, { key: 'month', prop: 'month', label: '汇率月份', minWidth: 120 },
+  { key: 'usdToCnyAverage', prop: 'usdToCnyAverage', label: '平均汇率', minWidth: 120 }, { key: 'conversion', label: '换算说明', minWidth: 190, slotName: 'conversion' },
+  { key: 'status', label: '状态', width: 90, slotName: 'status' }, { key: 'updatedBy', prop: 'updatedBy', label: '更新人', minWidth: 120 },
+  { key: 'updatedAt', prop: 'updatedAt', label: '更新时间', minWidth: 150 }, { key: 'remark', prop: 'remark', label: '备注', minWidth: 200 },
+]
+const summary = reactive({ latestMonth: '', latestUsdToCnyAverage: null as number | null, updatedBy: '', updatedAt: '' })
+const form = reactive({ month: '', usdToCnyAverage: 0, remark: '', recordVersion: 0 })
+function params() { const month = String(filters.value.month || ''); return { page: page.value, size: pageSize.value, monthFrom: month || undefined, monthTo: month || undefined, status: (filters.value.status || undefined) as MasterDataStatus | undefined } }
+async function load() { loading.value = true; error.value = null; try { const [result, latest] = await Promise.all([listExchangeRates(params()), getExchangeRateSummary()]); rows.value = result.records; total.value = result.total; Object.assign(summary, latest) } catch (cause) { rows.value = []; total.value = 0; error.value = getApiErrorDetails(cause, '月度汇率加载失败') } finally { loading.value = false } }
+function search() { if (page.value === 1) void load(); else page.value = 1 }
+function openCreate() { editingMonth.value = ''; Object.assign(form, { month: '', usdToCnyAverage: 0, remark: '', recordVersion: 0 }); editorOpen.value = true }
+async function openEdit(row: MonthlyExchangeRate) { try { const value = await getExchangeRate(row.month); editingMonth.value = value.month; Object.assign(form, { month: value.month, usdToCnyAverage: Number(value.usdToCnyAverage), remark: value.remark || '', recordVersion: value.recordVersion }); editorOpen.value = true } catch (cause) { ElMessage.error(masterDataErrorMessage(cause, '汇率详情加载失败')) } }
+async function save() { if (!form.month || form.usdToCnyAverage <= 0) { ElMessage.warning('请选择月份并填写大于 0 的平均汇率'); return } saving.value = true; try { if (editingMonth.value) await updateExchangeRate(editingMonth.value, { recordVersion: form.recordVersion, usdToCnyAverage: form.usdToCnyAverage, remark: form.remark || null }); else await createExchangeRate({ month: form.month, usdToCnyAverage: form.usdToCnyAverage, remark: form.remark || null }); ElMessage.success(editingMonth.value ? '月度汇率已更新' : '月度汇率已创建'); editorOpen.value = false; await load() } catch (cause) { ElMessage.error(masterDataErrorMessage(cause, '月度汇率保存失败')) } finally { saving.value = false } }
+async function toggle(row: MonthlyExchangeRate) { const next: MasterDataStatus = row.status === 'ACTIVE' ? 'INACTIVE' : 'ACTIVE'; try { await ElMessageBox.confirm(`确认${next === 'ACTIVE' ? '启用' : '停用'} ${row.month} 汇率吗？`, '汇率状态', { customClass: 'admin-density-confirm', type: 'warning' }); await changeExchangeRateStatus(row.month, next, row.recordVersion, null); ElMessage.success('汇率状态已更新'); await load() } catch (cause) { if (cause !== 'cancel' && cause !== 'close') ElMessage.error(masterDataErrorMessage(cause, '汇率状态更新失败')) } }
+async function exportCsv() { exporting.value = true; try { const { page: _page, size: _size, ...query } = params(); saveCsv(await exportExchangeRates(query), 'monthly-exchange-rates.csv') } catch (cause) { ElMessage.error(masterDataErrorMessage(cause, '汇率导出失败')) } finally { exporting.value = false } }
+watch([page, pageSize], load); onMounted(load)
+</script>
+
+<template><AdminPage class="admin-density"><ListPageLayout aria-label="汇率管理">
+  <template #toolbar><QueryToolbar v-model="filters" class="surface-panel" :fields="fields" ariaLabel="汇率月份筛选" preference-key="overseas-exchange-rates-query" :loading="loading" @search="search" /></template>
+  <template #metrics><dl class="rate-summary density-detail-overview"><div v-for="item in [{label:'最新维护汇率',value:summary.latestUsdToCnyAverage??'—'},{label:'汇率月份',value:summary.latestMonth||'—'},{label:'最后更新人',value:summary.updatedBy||'—'},{label:'最后更新时间',value:summary.updatedAt||'—'}]" :key="item.label"><dt>{{ item.label }}</dt><dd>{{ item.value }}</dd></div></dl></template>
+  <template #state><LoadErrorState v-if="error" title="月度汇率加载失败" :message="error.message" @retry="load" /></template>
+  <section class="surface-panel table-panel"><DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :total="total" :loading="loading" row-key="month" preference-key="overseas-exchange-rates-table" empty-text="暂无月度汇率">
+
+    <template #toolbar-actions><el-button v-if="access.can(permission.exchangeRateCreate)" type="primary" @click="openCreate"><Plus :size="16" />更新月度汇率</el-button><el-button v-if="access.can(permission.exchangeRateExport)" :loading="exporting" @click="exportCsv"><Download :size="16" />导出</el-button></template>
+    <template #actions="{ row }"><div class="density-actions"><el-button data-tone="neutral" class="density-action" v-if="access.can(permission.exchangeRateEdit)"   @click="openEdit(row as MonthlyExchangeRate)">编辑</el-button><el-button class="density-action" v-if="access.can(permission.exchangeRateStatus)"  :data-tone="(row as MonthlyExchangeRate).status === 'ACTIVE' ? 'danger' : 'success'" @click="toggle(row as MonthlyExchangeRate)">{{ (row as MonthlyExchangeRate).status === 'ACTIVE' ? '停用' : '启用' }}</el-button></div></template>
+    <template #conversion="{ row }">1 USD = {{ (row as MonthlyExchangeRate).usdToCnyAverage }} CNY</template><template #status="{ row }"><el-tag :type="(row as MonthlyExchangeRate).status === 'ACTIVE' ? 'success' : 'info'">{{ (row as MonthlyExchangeRate).status === 'ACTIVE' ? '启用' : '停用' }}</el-tag></template>
+  </DataTable></section>
+  <AppDialog class="admin-density-dialog" v-model="editorOpen" :title="editingMonth ? '编辑月度汇率' : '更新月度汇率'" width="min(560px, calc(100vw - 28px))" :confirm-loading="saving" @confirm="save"><el-form class="density-form" label-position="top"><el-form-item label="汇率月份"><el-date-picker v-model="form.month" type="month" value-format="YYYY-MM" :disabled="!!editingMonth" /></el-form-item><el-form-item label="美元兑人民币平均汇率"><el-input-number v-model="form.usdToCnyAverage" :min="0.00000001" :precision="8" placeholder="请输入美元兑人民币月均汇率" /><p>汇率方向：1 USD = X CNY</p></el-form-item><el-form-item label="备注"><el-input v-model="form.remark" type="textarea" :rows="3" maxlength="1000" placeholder="请输入备注（选填）" /></el-form-item></el-form></AppDialog>
+</ListPageLayout></AdminPage></template>
+<style scoped>.table-panel{min-width:0;overflow:hidden}</style>
diff --git a/src/modules/overseas-master-data/pages/OverseasMasterDataMount.test.ts b/src/modules/overseas-master-data/pages/OverseasMasterDataMount.test.ts
new file mode 100644
index 00000000..7c683a8a
--- /dev/null
+++ b/src/modules/overseas-master-data/pages/OverseasMasterDataMount.test.ts
@@ -0,0 +1,41 @@
+import { flushPromises, shallowMount, type VueWrapper } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { getVehicle } from '../api/overseasMasterData'
+import ExchangeRatesView from './ExchangeRatesView.vue'
+import OverseasQuotesView from './OverseasQuotesView.vue'
+import VehicleDetailView from './VehicleDetailView.vue'
+import VehiclesView from './VehiclesView.vue'
+
+const push = vi.fn()
+vi.mock('vue-router', () => ({ useRoute: () => ({ params: { vehicleId: 'VH-TEST-001' } }), useRouter: () => ({ push }) }))
+vi.mock('@/core/access/accessPreview', () => ({ useAccessPreviewStore: () => ({ can: () => true }) }))
+vi.mock('../api/overseasMasterData', () => ({
+  listQuotes: vi.fn().mockResolvedValue({ records: [], page: 1, size: 20, total: 0, pages: 0 }),
+  listQuoteWarehouseOptions: vi.fn().mockResolvedValue([]), getQuote: vi.fn(), createQuote: vi.fn(), updateQuote: vi.fn(), changeQuoteStatus: vi.fn(), exportQuotes: vi.fn(),
+  listExchangeRates: vi.fn().mockResolvedValue({ records: [], page: 1, size: 20, total: 0, pages: 0 }),
+  getExchangeRateSummary: vi.fn().mockResolvedValue({ latestMonth: null, latestUsdToCnyAverage: null, updatedBy: null, updatedAt: null }),
+  getExchangeRate: vi.fn(), createExchangeRate: vi.fn(), updateExchangeRate: vi.fn(), changeExchangeRateStatus: vi.fn(), exportExchangeRates: vi.fn(),
+  listVehicles: vi.fn().mockResolvedValue({ records: [], page: 1, size: 20, total: 0, pages: 0 }),
+  getVehicle: vi.fn().mockResolvedValue({ id: 'VH-TEST-001', plateNumber: 'CA-TEST', model: 'Truck', fuelConsumptionPer100Km: 12, mileageKm: 100, driverOrDispatchCompany: null, phone: null, region: 'OVERSEAS', ownership: 'OWNED', status: 'IN_SERVICE', remark: null, recordVersion: 0, updatedBy: 'tester', updatedAt: '2026-08-20T10:00:00' }),
+  createVehicle: vi.fn(), updateVehicle: vi.fn(), changeVehicleStatus: vi.fn(), exportVehicles: vi.fn(),
+}))
+
+const slot = { template: '<div><slot/><slot name="header"/><slot name="toolbar"/><slot name="metrics"/><slot name="state"/><slot name="toolbar-start"/><slot name="toolbar-actions"/><slot name="actions"/></div>' }
+const stubs = { AdminPage: slot, ListPageLayout: slot, DetailPageLayout: slot, QueryToolbar: true, DataTable: { template: '<div data-test="data-table"><slot name="toolbar-actions"/></div>' }, FormSection: slot, LoadErrorState: true, AppDialog: slot, ElTooltip: slot, ElButton: slot, ElTag: slot, ElTable: slot, ElTableColumn: true, ElForm: slot, ElFormItem: slot, ElInput: true, ElSelect: slot, ElOption: true, ElDatePicker: true, ElInputNumber: true }
+function mountView(component: object): VueWrapper { return shallowMount(component, { global: { stubs, directives: { loading: () => undefined } } }) }
+
+describe('overseas master data real page mounts', () => {
+  beforeEach(() => push.mockReset())
+  it.each([OverseasQuotesView, ExchangeRatesView, VehiclesView])('mounts a real API-backed list page', async (component) => { const wrapper = mountView(component); await flushPromises(); expect(wrapper.find('[data-test="data-table"]').exists()).toBe(true) })
+  it('keeps the business title empty on detail failure instead of exposing the route ID', async () => {
+    vi.mocked(getVehicle).mockRejectedValueOnce(new Error('加载失败'))
+    const wrapper = mountView(VehicleDetailView)
+    await flushPromises()
+    expect(wrapper.get('.density-detail-title').text()).toBe('—')
+    expect(wrapper.text()).not.toContain('VH-TEST-001')
+    expect(wrapper.find('.density-fields').exists()).toBe(false)
+    expect(wrapper.findComponent({ name: 'LoadErrorState' }).exists()).toBe(true)
+  })
+
+  it('mounts API-backed vehicle detail without fabricating fulfillment history', async () => { const wrapper = mountView(VehicleDetailView); await flushPromises(); expect(wrapper.get('.density-detail-title').text()).toBe('CA-TEST'); expect(wrapper.get('.density-fields').findAll('dt')).toHaveLength(11); expect(wrapper.get('.density-fields').text()).toContain('在役'); expect(wrapper.text()).not.toContain('IN_SERVICE'); expect(wrapper.text()).toContain('当前车辆主数据接口明确不包含派送履约记录') })
+})
diff --git a/src/modules/overseas-master-data/pages/OverseasMasterDataViews.test.ts b/src/modules/overseas-master-data/pages/OverseasMasterDataViews.test.ts
new file mode 100644
index 00000000..31f3aa59
--- /dev/null
+++ b/src/modules/overseas-master-data/pages/OverseasMasterDataViews.test.ts
@@ -0,0 +1,106 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+function source(name: string) {
+  return readFileSync(resolve(process.cwd(), `src/modules/overseas-master-data/pages/${name}.vue`), 'utf8')
+}
+
+describe('overseas master data real contract pages', () => {
+  it('gives every list query toolbar a unique stable preference key', () => {
+    const expectedKeys = new Map([
+      ['OverseasQuotesView', 'overseas-quotes-query'],
+      ['ExchangeRatesView', 'overseas-exchange-rates-query'],
+      ['VehiclesView', 'overseas-vehicles-query'],
+    ])
+    const actualKeys: string[] = []
+
+    for (const [name, expectedKey] of expectedKeys) {
+      const view = source(name)
+      const toolbar = view.match(/<QueryToolbar\b[^>]*\/>/s)?.[0]
+      expect(toolbar, `${name} should render QueryToolbar`).toBeDefined()
+      expect(toolbar).toContain(`preference-key="${expectedKey}"`)
+      const actualKey = toolbar?.match(/preference-key="([^"]+)"/)?.[1]
+      expect(actualKey).toBe(expectedKey)
+      actualKeys.push(actualKey!)
+    }
+
+    expect(new Set(actualKeys).size).toBe(actualKeys.length)
+  })
+
+  it('keeps operation columns first and preserves the prototype fields', () => {
+    const quotes = source('OverseasQuotesView')
+    const exchangeRates = source('ExchangeRatesView')
+    const vehicles = source('VehiclesView')
+    expect(quotes.indexOf("key:'actions'")).toBeLessThan(quotes.indexOf("key:'name'"))
+    for (const label of ['报价名称', '海外仓', '服务商', '币种', '生效日期', '失效日期', '报价版本', '状态', '更新时间', '备注']) {
+      expect(quotes).toContain(`label:'${label}'`)
+    }
+    const exchangeColumns = exchangeRates.slice(exchangeRates.indexOf('const columns'))
+    expect(exchangeColumns.indexOf("key: 'actions'")).toBeLessThan(exchangeColumns.indexOf("key: 'month'"))
+    expect(vehicles.indexOf("key:'actions'")).toBeLessThan(vehicles.indexOf("key:'plateNumber'"))
+    for (const label of ['自有车辆', '外派车辆', '司机 / 外派单位']) expect(vehicles).toContain(label)
+    expect(vehicles).toContain("key:'region'")
+    expect(vehicles).toContain("placeholder:'全部区域'")
+    expect(vehicles).toContain('class="status-tabs density-tabs"')
+    expect(vehicles).toContain("'status-tab',{active:ownership===tab[1]}")
+    expect(vehicles).not.toContain('<el-segmented')
+    expect(vehicles).not.toContain('aria-label="车辆区域"')
+  })
+
+  it('uses real API operations and canonical action permissions', () => {
+    for (const name of ['OverseasQuotesView', 'ExchangeRatesView', 'VehiclesView']) {
+      const view = source(name)
+      expect(view).toContain("from '../api/overseasMasterData'")
+      expect(view).toContain('access.can(permission.')
+      expect(view).toContain('ElMessage.success')
+    }
+    expect(source('OverseasQuotesView')).toContain('导出CSV')
+    expect(source('VehiclesView')).toContain('导出CSV')
+    expect(source('ExchangeRatesView')).toContain("'monthly-exchange-rates.csv'")
+    for (const name of ['OverseasQuotesView', 'ExchangeRatesView', 'VehiclesView']) {
+      expect(source(name)).not.toMatch(/deleteQuote|deleteExchangeRate|deleteVehicle/)
+    }
+    expect(source('OverseasQuotesView')).toContain('changeQuoteStatus(row.id,next,row.recordVersion)')
+    expect(source('ExchangeRatesView')).toContain('changeExchangeRateStatus(row.month, next, row.recordVersion, null)')
+    expect(source('VehiclesView')).toContain('changeVehicleStatus(row.id,statusTarget.value,row.recordVersion)')
+    for (const name of ['OverseasQuotesView', 'ExchangeRatesView', 'VehiclesView']) {
+      expect(source(name)).toContain("masterDataErrorMessage(")
+      expect(source(name)).toContain('saveCsv(await export')
+    }
+  })
+
+  it('uses an independent API-backed vehicle detail page without inventing fulfillment history', () => {
+    const detail = source('VehicleDetailView')
+    expect(detail).toContain('车辆信息')
+    expect(detail).toContain('派送订单明细')
+    expect(detail).toContain('派送更换记录')
+    expect(detail).toContain('getVehicle(')
+    expect(detail).toContain('明确不包含派送履约记录')
+    expect(detail).not.toContain('AppDrawer')
+    expect(detail).not.toContain('const vehicle =')
+  })
+
+  it('records the prototype evidence before implementation', () => {
+    const matrix = readFileSync(resolve(process.cwd(), 'src/modules/overseas-master-data/PROTOTYPE_MATRIX.md'), 'utf8')
+    for (const id of ['gen-partner-warehouse', 'gen-overseas-quote', 'gen-exchange-rate', 'vehicle-detail']) expect(matrix).toContain(id)
+    for (const modal of ['modal-gen-overseas-quote-detail', 'modal-gen-overseas-quote', 'modal-exchange-rate-edit', 'modal-vehicle-edit']) expect(matrix).toContain(modal)
+    expect(matrix).toContain('原型未定义车辆文件预览、审核/确认流程')
+  })
+
+  it('records the real service boundary and remaining unsupported operations', () => {
+    const gaps = readFileSync(resolve(process.cwd(), 'src/modules/overseas-master-data/CONTRACT_GAPS.md'), 'utf8')
+    expect(gaps).toContain('/api/platform/v1/last-leg/master-data')
+    expect(gaps).toContain('/overseas-quotes/warehouse-options')
+    expect(gaps).toContain('浏览器不调用国内')
+    expect(gaps).toContain('没有删除端点')
+    expect(gaps).toContain('JSON 错误 Blob')
+    expect(gaps).not.toContain('尚无已确认')
+    expect(matrixSource()).not.toContain('写入口禁用')
+    expect(matrixSource()).not.toContain('等待查询接口')
+  })
+})
+
+function matrixSource() {
+  return readFileSync(resolve(process.cwd(), 'src/modules/overseas-master-data/PROTOTYPE_MATRIX.md'), 'utf8')
+}
diff --git a/src/modules/overseas-master-data/pages/OverseasMasterDataWriteBehavior.test.ts b/src/modules/overseas-master-data/pages/OverseasMasterDataWriteBehavior.test.ts
new file mode 100644
index 00000000..e0f73299
--- /dev/null
+++ b/src/modules/overseas-master-data/pages/OverseasMasterDataWriteBehavior.test.ts
@@ -0,0 +1,125 @@
+import { flushPromises, shallowMount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { ApiResponseError } from '@/shared/api/http'
+import { ElMessage } from 'element-plus'
+import * as api from '../api/overseasMasterData'
+import ExchangeRatesView from './ExchangeRatesView.vue'
+import OverseasQuotesView from './OverseasQuotesView.vue'
+import VehiclesView from './VehiclesView.vue'
+
+vi.mock('element-plus', () => ({
+  ElMessage: { success: vi.fn(), warning: vi.fn(), error: vi.fn() },
+  ElMessageBox: { confirm: vi.fn().mockResolvedValue(undefined) },
+}))
+vi.mock('vue-router', () => ({ useRouter: () => ({ push: vi.fn() }) }))
+vi.mock('@/core/access/accessPreview', () => ({ useAccessPreviewStore: () => ({ can: () => true }) }))
+vi.mock('../api/overseasMasterData', () => ({
+  listQuotes: vi.fn(), listQuoteWarehouseOptions: vi.fn(), getQuote: vi.fn(), createQuote: vi.fn(), updateQuote: vi.fn(), changeQuoteStatus: vi.fn(), exportQuotes: vi.fn(),
+  listExchangeRates: vi.fn(), getExchangeRateSummary: vi.fn(), getExchangeRate: vi.fn(), createExchangeRate: vi.fn(), updateExchangeRate: vi.fn(), changeExchangeRateStatus: vi.fn(), exportExchangeRates: vi.fn(),
+  listVehicles: vi.fn(), getVehicle: vi.fn(), createVehicle: vi.fn(), updateVehicle: vi.fn(), changeVehicleStatus: vi.fn(), exportVehicles: vi.fn(),
+}))
+
+const longId = '9223372036854775807'
+const quote = { id: longId, name: '真实报价', warehouseId: '9223372036854775806', warehouseName: '合作仓', warehouseCode: 'US-LAX', countryCode: 'US', providerName: 'Provider', currency: 'USD' as const, effectiveStart: '2026-08-01', effectiveEnd: '2026-12-31', versionCode: 'V1', status: 'INACTIVE' as const, updatedAt: '2026-08-24T10:00:00', updatedBy: 'admin', recordVersion: 7, remark: null }
+const quoteDetail = { summary: quote, warehouseFees: [{ item: '入库', billingUnit: 'PALLET', unitPrice: 1.25, minimumCharge: null, remark: null }], transitPrices: [], createdBy: 'admin', createdAt: '2026-08-24T09:00:00' }
+const rate = { month: '2026-08', baseCurrency: 'USD', quoteCurrency: 'CNY', usdToCnyAverage: 7.12345678, status: 'ACTIVE' as const, recordVersion: 3, updatedBy: 'admin', updatedAt: '2026-08-24T10:00:00', remark: null }
+const vehicle = { id: longId, plateNumber: 'CA-01', model: 'Truck', fuelConsumptionPer100Km: 12.5, mileageKm: 101, driverOrDispatchCompany: null, phone: null, region: 'OVERSEAS' as const, ownership: 'OWNED' as const, status: 'IN_SERVICE' as const, remark: null, recordVersion: 4, updatedBy: 'admin', updatedAt: '2026-08-24T10:00:00' }
+const emptyPage = { records: [], page: 1, size: 20, total: 0, pages: 0 }
+
+const slot = { template: '<div><slot/><slot name="header"/><slot name="toolbar"/><slot name="metrics"/><slot name="state"/></div>' }
+const stubs = {
+  AdminPage: slot,
+  ListPageLayout: slot,
+  QueryToolbar: true,
+  LoadErrorState: true,
+  DataTable: {
+    props: ['data'],
+    template: '<div><slot name="toolbar-actions"/><slot v-if="data && data[0]" name="actions" :row="data[0]"/></div>',
+  },
+  AppDialog: {
+    props: ['modelValue'], emits: ['confirm', 'update:modelValue'],
+    template: '<div v-if="modelValue" data-test="dialog"><slot/><button data-test="dialog-confirm" @click="$emit(\'confirm\')">confirm</button></div>',
+  },
+  ElButton: { emits: ['click'], template: '<button @click="$emit(\'click\')"><slot/></button>' },
+  ElForm: slot, ElFormItem: slot, ElInput: true, ElSelect: slot, ElOption: true, ElDatePicker: true, ElInputNumber: true,
+  ElTable: slot, ElTableColumn: true, ElTag: slot,
+}
+const mountView = (component: object) => shallowMount(component, { global: { stubs } })
+const button = (wrapper: ReturnType<typeof mountView>, label: string) => {
+  const found = wrapper.findAll('button').find((item) => item.text().includes(label))
+  expect(found, `button ${label}`).toBeDefined()
+  return found!
+}
+
+describe('overseas master data failed writes preserve editor context', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.mocked(api.listQuotes).mockResolvedValue({ ...emptyPage, records: [quote], total: 1, pages: 1 })
+    vi.mocked(api.listQuoteWarehouseOptions).mockResolvedValue([{ warehouseId: quote.warehouseId, warehouseCode: 'US-LAX', warehouseName: '合作仓', countryCode: 'US' }])
+    vi.mocked(api.getQuote).mockResolvedValue(quoteDetail)
+    vi.mocked(api.listExchangeRates).mockResolvedValue({ ...emptyPage, records: [rate], total: 1, pages: 1 })
+    vi.mocked(api.getExchangeRateSummary).mockResolvedValue({ latestMonth: rate.month, latestUsdToCnyAverage: rate.usdToCnyAverage, updatedBy: 'admin', updatedAt: rate.updatedAt })
+    vi.mocked(api.getExchangeRate).mockResolvedValue(rate)
+    vi.mocked(api.listVehicles).mockResolvedValue({ ...emptyPage, records: [vehicle], total: 1, pages: 1 })
+    vi.mocked(api.getVehicle).mockResolvedValue(vehicle)
+  })
+
+  it.each([
+    [OverseasQuotesView, ['详情', '编辑', '停用']],
+    [VehiclesView, ['查看', '编辑', '状态']],
+    [ExchangeRatesView, ['编辑', '停用']],
+  ])('keeps all available actions visible without an unnecessary overflow menu', async (component, labels) => {
+    const wrapper = mountView(component)
+    await flushPromises()
+    const actions = wrapper.get('.density-actions')
+    const expected = component === OverseasQuotesView ? ['详情', '编辑', '启用'] : labels
+    expect(actions.findAll('button').map(button => button.text().trim())).toEqual(expected)
+    expect(actions.findAll('button').every(button => button.classes().includes('density-action'))).toBe(true)
+    expect(actions.find('el-dropdown-stub').exists()).toBe(false)
+  })
+
+  it('keeps quote edit open, sends only update fields, and shows A0409 request ID', async () => {
+    vi.mocked(api.updateQuote).mockRejectedValue(new ApiResponseError('记录版本已变化', 'A0409', 200, null, 'req-quote-409'))
+    const wrapper = mountView(OverseasQuotesView)
+    await flushPromises()
+    await button(wrapper, '编辑').trigger('click')
+    await flushPromises()
+    await wrapper.get('[data-test="dialog-confirm"]').trigger('click')
+    await flushPromises()
+
+    expect(api.updateQuote).toHaveBeenCalledWith(longId, expect.objectContaining({ recordVersion: 7, name: quote.name }))
+    const payload = vi.mocked(api.updateQuote).mock.calls[0]?.[1]
+    expect(payload).not.toHaveProperty('warehouseId')
+    expect(payload).not.toHaveProperty('versionCode')
+    expect(wrapper.find('[data-test="dialog"]').exists()).toBe(true)
+    expect(ElMessage.error).toHaveBeenCalledWith(expect.stringContaining('req-quote-409'))
+  })
+
+  it('keeps exchange-rate decimal/version in the open editor after A0409', async () => {
+    vi.mocked(api.updateExchangeRate).mockRejectedValue(new ApiResponseError('汇率版本已变化', 'A0409', 200, null, 'req-rate-409'))
+    const wrapper = mountView(ExchangeRatesView)
+    await flushPromises()
+    await button(wrapper, '编辑').trigger('click')
+    await flushPromises()
+    await wrapper.get('[data-test="dialog-confirm"]').trigger('click')
+    await flushPromises()
+
+    expect(api.updateExchangeRate).toHaveBeenCalledWith('2026-08', { recordVersion: 3, usdToCnyAverage: 7.12345678, remark: null })
+    expect(wrapper.find('[data-test="dialog"]').exists()).toBe(true)
+    expect(ElMessage.error).toHaveBeenCalledWith(expect.stringContaining('req-rate-409'))
+  })
+
+  it('keeps vehicle long ID, decimal and recordVersion in the open editor after A0409', async () => {
+    vi.mocked(api.updateVehicle).mockRejectedValue(new ApiResponseError('车辆版本已变化', 'A0409', 200, null, 'req-vehicle-409'))
+    const wrapper = mountView(VehiclesView)
+    await flushPromises()
+    await button(wrapper, '编辑').trigger('click')
+    await flushPromises()
+    await wrapper.get('[data-test="dialog-confirm"]').trigger('click')
+    await flushPromises()
+
+    expect(api.updateVehicle).toHaveBeenCalledWith(longId, expect.objectContaining({ recordVersion: 4, fuelConsumptionPer100Km: 12.5, mileageKm: 101 }))
+    expect(wrapper.find('[data-test="dialog"]').exists()).toBe(true)
+    expect(ElMessage.error).toHaveBeenCalledWith(expect.stringContaining('req-vehicle-409'))
+  })
+})
diff --git a/src/modules/overseas-master-data/pages/OverseasQuotesView.vue b/src/modules/overseas-master-data/pages/OverseasQuotesView.vue
new file mode 100644
index 00000000..49b13606
--- /dev/null
+++ b/src/modules/overseas-master-data/pages/OverseasQuotesView.vue
@@ -0,0 +1,67 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { onMounted, reactive, ref, watch } from 'vue'
+import { Download, Plus } from '@lucide/vue'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { changeQuoteStatus, createQuote, exportQuotes, getQuote, listQuotes, listQuoteWarehouseOptions, updateQuote } from '../api/overseasMasterData'
+import { overseasMasterDataPermissions as permission } from '../permissions'
+import { saveCsv } from '@/shared/downloadCsv'
+import { masterDataErrorMessage } from '../apiError'
+import type { MasterDataStatus, OverseasTransitPrice, OverseasWarehouseFee, OverseasWarehouseQuote, OverseasWarehouseQuoteDetail, PartnerWarehouseOption } from '../types'
+
+const access = useAccessPreviewStore()
+const rows = ref<OverseasWarehouseQuote[]>([]), total = ref(0), page = ref(1), pageSize = ref(20), loading = ref(false), saving = ref(false), exporting = ref(false)
+const error = ref<ApiErrorDetails | null>(null), options = ref<PartnerWarehouseOption[]>([]), detail = ref<OverseasWarehouseQuoteDetail | null>(null)
+const detailOpen = ref(false), editorOpen = ref(false), editingId = ref('')
+const filters = ref<QueryModel>({ keyword: '', warehouseId: '', providerName: '', currency: '', status: '' })
+const fields = ref<QueryField[]>([])
+function syncFields() { fields.value = [
+  { key: 'keyword', type: 'input', label: '报价名称 / 版本', placeholder: '报价名称 / 版本', width: 180 },
+  { key: 'warehouseId', type: 'select', label: '海外仓', placeholder: '全部海外仓', options: options.value.map(v => ({ label: `${v.warehouseName} · ${v.warehouseCode}`, value: v.warehouseId })), width: 220 },
+  { key: 'providerName', type: 'input', label: '服务商', placeholder: '服务商', width: 170 },
+  { key: 'currency', type: 'select', label: '币种', placeholder: '全部币种', options: ['USD','CNY'].map(v => ({ label:v,value:v })), width: 120 },
+  { key: 'status', type: 'select', label: '状态', placeholder: '全部状态', options: [{label:'启用',value:'ACTIVE'},{label:'停用',value:'INACTIVE'}], width: 120 },
+] }
+syncFields()
+const columns: DataTableColumn[] = [
+  { key:'actions',label:'操作',width:270,fixed:'left',slotName:'actions' }, { key:'name',prop:'name',label:'报价名称',minWidth:190 },
+  { key:'warehouseName',prop:'warehouseName',label:'海外仓',minWidth:170 }, { key:'providerName',prop:'providerName',label:'服务商',minWidth:180 },
+  { key:'currency',prop:'currency',label:'币种',width:74 }, { key:'effectiveStart',prop:'effectiveStart',label:'生效日期',width:112 },
+  { key:'effectiveEnd',prop:'effectiveEnd',label:'失效日期',width:112 }, { key:'versionCode',prop:'versionCode',label:'报价版本',width:92 },
+  { key:'status',label:'状态',width:76,slotName:'status' }, { key:'updatedAt',prop:'updatedAt',label:'更新时间',minWidth:150 }, { key:'remark',prop:'remark',label:'备注',minWidth:180 },
+]
+const form = reactive({ name:'', warehouseId:'', providerName:'', currency:'USD', effectiveStart:'', effectiveEnd:'', versionCode:'V1.0', remark:'', recordVersion:0, warehouseFees:[] as OverseasWarehouseFee[], transitPrices:[] as OverseasTransitPrice[] })
+function resetForm(){ Object.assign(form,{name:'',warehouseId:'',providerName:'',currency:'USD',effectiveStart:'',effectiveEnd:'',versionCode:'V1.0',remark:'',recordVersion:0,warehouseFees:[{item:'入库卸货',billingUnit:'托',unitPrice:0,minimumCharge:null,remark:null}],transitPrices:[]}) }
+function params(){ return { page:page.value,size:pageSize.value,keyword:String(filters.value.keyword||'')||undefined,warehouseId:String(filters.value.warehouseId||'')||undefined,providerName:String(filters.value.providerName||'')||undefined,currency:String(filters.value.currency||'')||undefined,status:(filters.value.status||undefined) as MasterDataStatus|undefined } }
+async function load(){ loading.value=true;error.value=null;try{const r=await listQuotes(params());rows.value=r.records;total.value=r.total}catch(e){rows.value=[];total.value=0;error.value=getApiErrorDetails(e,'海外仓报价加载失败')}finally{loading.value=false} }
+async function loadOptions(){ try{options.value=await listQuoteWarehouseOptions();syncFields()}catch(e){ElMessage.error(masterDataErrorMessage(e,'合作仓候选加载失败'))} }
+function search(){ if(page.value===1) void load(); else page.value=1 }
+async function openDetail(row:OverseasWarehouseQuote){ try{detail.value=await getQuote(row.id);detailOpen.value=true}catch(e){ElMessage.error(masterDataErrorMessage(e,'报价详情加载失败'))} }
+function fill(d:OverseasWarehouseQuoteDetail){const s=d.summary;Object.assign(form,{name:s.name,warehouseId:s.warehouseId,providerName:s.providerName,currency:s.currency,effectiveStart:s.effectiveStart,effectiveEnd:s.effectiveEnd,versionCode:s.versionCode,remark:s.remark||'',recordVersion:s.recordVersion,warehouseFees:d.warehouseFees.map(v=>({...v})),transitPrices:d.transitPrices.map(v=>({...v}))})}
+async function openCreate(){editingId.value='';resetForm();if(!options.value.length)await loadOptions();editorOpen.value=true}
+async function openEdit(row:OverseasWarehouseQuote){try{const d=await getQuote(row.id);editingId.value=row.id;fill(d);editorOpen.value=true}catch(e){ElMessage.error(masterDataErrorMessage(e,'报价详情加载失败'))}}
+async function save(){if(!form.name||!form.warehouseId||!form.providerName||!form.effectiveStart||!form.effectiveEnd||!form.warehouseFees.length){ElMessage.warning('请完整填写报价必填信息');return} if(form.effectiveEnd<form.effectiveStart){ElMessage.warning('失效日期不能早于生效日期');return} saving.value=true;try{const common={name:form.name,providerName:form.providerName,currency:form.currency as 'USD'|'CNY',effectiveStart:form.effectiveStart,effectiveEnd:form.effectiveEnd,warehouseFees:form.warehouseFees,transitPrices:form.transitPrices,remark:form.remark||null};if(editingId.value)await updateQuote(editingId.value,{...common,recordVersion:form.recordVersion});else await createQuote({...common,warehouseId:form.warehouseId,versionCode:form.versionCode});ElMessage.success(editingId.value?'报价已更新':'报价已创建');editorOpen.value=false;await load()}catch(e){ElMessage.error(masterDataErrorMessage(e,'报价保存失败'))}finally{saving.value=false}}
+async function toggle(row:OverseasWarehouseQuote){const next:MasterDataStatus=row.status==='ACTIVE'?'INACTIVE':'ACTIVE';try{await ElMessageBox.confirm(`确认${next==='ACTIVE'?'启用':'停用'}“${row.name}”吗？`,'报价状态',{customClass:'admin-density-confirm',type:'warning'});await changeQuoteStatus(row.id,next,row.recordVersion);ElMessage.success('报价状态已更新');await load()}catch(e){if(e!=='cancel'&&e!=='close')ElMessage.error(masterDataErrorMessage(e,'报价状态更新失败'))}}
+async function exportCsv(){exporting.value=true;try{const {page:_,size:__,...q}=params();saveCsv(await exportQuotes(q),'overseas-quotes.csv')}catch(e){ElMessage.error(masterDataErrorMessage(e,'报价导出失败'))}finally{exporting.value=false}}
+watch([page,pageSize],load);onMounted(()=>{void Promise.all([load(),loadOptions()])})
+</script>
+<template><AdminPage class="admin-density"><ListPageLayout aria-label="海外仓报价列表">
+  <template #toolbar><QueryToolbar v-model="filters" class="surface-panel" :fields="fields" ariaLabel="海外仓报价筛选" preference-key="overseas-quotes-query" :loading="loading" @search="search" /></template>
+  <template #state><LoadErrorState v-if="error" title="海外仓报价加载失败" :message="error.message" @retry="load" /></template>
+  <section class="surface-panel table-panel"><DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :total="total" :loading="loading" preference-key="overseas-quotes-table" row-key="id" empty-text="暂无海外仓报价">
+    <template #toolbar-actions><el-button v-if="access.can(permission.quoteCreate)" type="primary" @click="openCreate"><Plus :size="16"/>新增报价</el-button><el-button v-if="access.can(permission.quoteExport)" :loading="exporting" @click="exportCsv"><Download :size="16"/>导出CSV</el-button></template>
+    <template #actions="{row}"><div class="density-actions"><el-button data-tone="neutral" class="density-action"   @click="openDetail(row as OverseasWarehouseQuote)">详情</el-button><el-button data-tone="neutral" class="density-action" v-if="access.can(permission.quoteEdit)"   @click="openEdit(row as OverseasWarehouseQuote)">编辑</el-button><el-button class="density-action" v-if="access.can(permission.quoteStatus)"  :data-tone="(row as OverseasWarehouseQuote).status==='ACTIVE'?'danger':'success'" @click="toggle(row as OverseasWarehouseQuote)">{{(row as OverseasWarehouseQuote).status==='ACTIVE'?'停用':'启用'}}</el-button></div></template>
+    <template #status="{row}"><el-tag :type="(row as OverseasWarehouseQuote).status==='ACTIVE'?'success':'info'">{{(row as OverseasWarehouseQuote).status==='ACTIVE'?'启用':'停用'}}</el-tag></template>
+  </DataTable></section>
+  <AppDialog class="admin-density-dialog" v-model="detailOpen" title="海外仓报价详情" width="min(980px, calc(100vw - 28px))" :show-confirm="false"><dl v-if="detail" class="detail-grid density-fields"><div v-for="item in [['报价名称',detail.summary.name],['海外仓',detail.summary.warehouseName],['服务商',detail.summary.providerName],['币种',detail.summary.currency],['生效日期',detail.summary.effectiveStart],['失效日期',detail.summary.effectiveEnd],['版本',detail.summary.versionCode],['状态',detail.summary.status]]" :key="item[0]"><dt>{{item[0]}}</dt><dd>{{item[1]}}</dd></div></dl><h3>仓储作业费用</h3><el-table :data="detail?.warehouseFees||[]" border><el-table-column prop="item" label="费用项目"/><el-table-column prop="billingUnit" label="计费单位"/><el-table-column prop="unitPrice" label="单价"/><el-table-column prop="minimumCharge" label="最低收费"/><el-table-column prop="remark" label="备注"/></el-table><h3>中转派送价格</h3><el-table :data="detail?.transitPrices||[]" border><el-table-column prop="fbaWarehouseCode" label="目的FBA仓"/><el-table-column prop="deliveryMethod" label="车型/提货方式"/><el-table-column prop="estimatedMiles" label="预估迈数"/><el-table-column prop="price" label="报价"/><el-table-column prop="minimumCharge" label="最低收费"/></el-table></AppDialog>
+  <AppDialog class="admin-density-dialog" v-model="editorOpen" :title="editingId?'编辑海外仓报价':'新增海外仓报价'" width="min(1180px, calc(100vw - 28px))" :confirm-loading="saving" confirm-text="保存报价" @confirm="save"><el-form class="density-form" label-position="top"><div class="form-grid"><el-form-item label="报价名称"><el-input v-model="form.name" placeholder="请输入报价名称" /></el-form-item><el-form-item label="海外仓"><el-select v-model="form.warehouseId" :disabled="!!editingId"><el-option v-for="o in options" :key="o.warehouseId" :label="`${o.warehouseName} · ${o.warehouseCode}`" :value="o.warehouseId"/></el-select></el-form-item><el-form-item label="服务商"><el-input v-model="form.providerName" placeholder="请输入服务商名称" /></el-form-item><el-form-item label="币种"><el-select v-model="form.currency"><el-option label="USD" value="USD"/><el-option label="CNY" value="CNY"/></el-select></el-form-item><el-form-item label="生效日期"><el-date-picker v-model="form.effectiveStart" type="date" value-format="YYYY-MM-DD"/></el-form-item><el-form-item label="失效日期"><el-date-picker v-model="form.effectiveEnd" type="date" value-format="YYYY-MM-DD"/></el-form-item><el-form-item label="报价版本"><el-input v-model="form.versionCode" :disabled="!!editingId" placeholder="请输入版本号" /></el-form-item><el-form-item label="备注"><el-input v-model="form.remark" placeholder="请输入备注（选填）" /></el-form-item></div><h3>仓储作业费用 <el-button @click="form.warehouseFees.push({item:'',billingUnit:'',unitPrice:0,minimumCharge:null,remark:null})">+ 添加费用</el-button></h3><div v-for="(f,i) in form.warehouseFees" :key="i" class="line-grid"><el-input v-model="f.item" placeholder="请输入费用项目"/><el-input v-model="f.billingUnit" placeholder="请输入计费单位"/><el-input-number v-model="f.unitPrice" :min="0" placeholder="请输入单价" /><el-input-number v-model="f.minimumCharge" :min="0" placeholder="请输入最低收费" /><el-button data-tone="danger" class="density-action"   @click="form.warehouseFees.splice(i,1)">删除</el-button></div><h3>中转派送价格 <el-button @click="form.transitPrices.push({fbaWarehouseCode:'',deliveryMethod:'',estimatedMiles:null,price:0,minimumCharge:null,remark:null})">+ 添加派送价格</el-button></h3><div v-for="(t,i) in form.transitPrices" :key="i" class="line-grid"><el-input v-model="t.fbaWarehouseCode" placeholder="请输入目的 FBA 仓"/><el-input v-model="t.deliveryMethod" placeholder="请输入车型或提货方式"/><el-input-number v-model="t.price" :min="0" placeholder="请输入报价" /><el-input-number v-model="t.minimumCharge" :min="0" placeholder="请输入最低收费" /><el-button data-tone="danger" class="density-action"   @click="form.transitPrices.splice(i,1)">删除</el-button></div></el-form></AppDialog>
+</ListPageLayout></AdminPage></template>
+<style scoped>.detail-grid.density-fields { grid-template-columns: repeat(2, minmax(0, 1fr)); }.table-panel{min-width:0;overflow:hidden}.form-grid{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:var(--admin-space-5) var(--admin-space-6)}.line-grid{display:grid;grid-template-columns:2fr 1.2fr 1fr 1fr auto;gap:var(--admin-space-3);margin:var(--admin-space-3) 0}h3{margin:var(--admin-space-6) 0 var(--admin-space-4);font-size:var(--admin-font-body)}</style>
diff --git a/src/modules/overseas-master-data/pages/VehicleDetailView.vue b/src/modules/overseas-master-data/pages/VehicleDetailView.vue
new file mode 100644
index 00000000..96a819de
--- /dev/null
+++ b/src/modules/overseas-master-data/pages/VehicleDetailView.vue
@@ -0,0 +1,15 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { onMounted, ref } from 'vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import { vehicleStatusLabels } from '../presentation'
+import { ArrowLeft } from '@lucide/vue'
+import { useRoute, useRouter } from 'vue-router'
+import AdminPage from '@/shared/components/AdminPage.vue'; import DetailPageLayout from '@/shared/components/DetailPageLayout.vue'; import FormSection from '@/shared/components/FormSection.vue'; import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { getApiErrorDetails,type ApiErrorDetails } from '@/shared/api/http'; import { getVehicle } from '../api/overseasMasterData'; import type { VehicleDetail } from '../types'
+const route=useRoute(),router=useRouter(),detail=ref<VehicleDetail|null>(null),loading=ref(false),error=ref<ApiErrorDetails|null>(null)
+async function load(){loading.value=true;error.value=null;try{detail.value=await getVehicle(String(route.params.vehicleId||''))}catch(e){detail.value=null;error.value=getApiErrorDetails(e,'车辆详情加载失败')}finally{loading.value=false}}
+function back(){void router.push({name:'overseas-master-data-vehicles'})} onMounted(load)
+</script>
+<template><AdminPage class="admin-density" ><DetailPageLayout class="density-detail-layout surface-panel" aria-label="车辆详情"><template #header><div class="density-detail-header"><div class="density-detail-heading"><el-button link class="density-back" @click="back"><ArrowLeft :size="16" />返回列表</el-button><h1 class="density-detail-title">{{ detail?.plateNumber || '—' }}</h1><StatusBadge v-if="detail" :status="vehicleStatusLabels[detail.status]" /></div></div></template><LoadErrorState v-if="error" title="车辆详情加载失败" :message="error.message" @retry="load"/><section v-loading="loading" class="detail-surface"><FormSection class="density-form-section" title="车辆信息"><dl v-if="detail" class="detail-grid density-fields"><div v-for="item in [['车牌号',detail.plateNumber],['车型',detail.model],['油耗(L/100km)',detail.fuelConsumptionPer100Km],['当前公里码(km)',detail.mileageKm],['司机 / 外派单位',detail.driverOrDispatchCompany||'—'],['联系电话',detail.phone||'—'],['区域',detail.region==='OVERSEAS'?'海外':'国内'],['车辆归属',detail.ownership==='OWNED'?'自有车辆':'外派车辆'],['状态',vehicleStatusLabels[detail.status]],['更新时间',detail.updatedAt],['备注',detail.remark||'—']]" :key="item[0]" :class="{ 'wide-field': ['司机 / 外派单位', '备注'].includes(String(item[0])) }"><dt>{{item[0]}}</dt><dd>{{item[1]}}</dd></div></dl></FormSection><FormSection class="density-form-section" title="派送订单明细"><p class="contract-note">当前车辆主数据接口明确不包含派送履约记录。</p></FormSection><FormSection class="density-form-section" title="派送更换记录" :bordered="false"><p class="contract-note">当前车辆主数据接口明确不包含车辆更换历史。</p></FormSection></section></DetailPageLayout></AdminPage></template>
+<style scoped>.detail-grid .wide-field { grid-column: span 2; }.contract-note{margin:0;padding:var(--admin-space-6);color:var(--cc-muted);text-align:center}</style>
diff --git a/src/modules/overseas-master-data/pages/VehiclesView.vue b/src/modules/overseas-master-data/pages/VehiclesView.vue
new file mode 100644
index 00000000..da44e5a5
--- /dev/null
+++ b/src/modules/overseas-master-data/pages/VehiclesView.vue
@@ -0,0 +1,29 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { vehicleStatusLabels } from '../presentation'
+import { onMounted, reactive, ref, watch } from 'vue'
+import { Download, Plus } from '@lucide/vue'
+import { ElMessage } from 'element-plus'
+import { useRouter } from 'vue-router'
+import AdminPage from '@/shared/components/AdminPage.vue'; import AppDialog from '@/shared/components/AppDialog.vue'; import DataTable,{type DataTableColumn} from '@/shared/components/DataTable.vue'; import ListPageLayout from '@/shared/components/ListPageLayout.vue'; import QueryToolbar,{type QueryField,type QueryModel} from '@/shared/components/QueryToolbar.vue'; import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { getApiErrorDetails,type ApiErrorDetails } from '@/shared/api/http'; import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { changeVehicleStatus,createVehicle,exportVehicles,getVehicle,listVehicles,updateVehicle } from '../api/overseasMasterData'; import { overseasMasterDataPermissions as permission } from '../permissions'; import { saveCsv } from '@/shared/downloadCsv'; import type { VehicleDetail,VehicleOwnership,VehicleRegion,VehicleStatus } from '../types'
+import { masterDataErrorMessage } from '../apiError'
+const router=useRouter(),access=useAccessPreviewStore(),rows=ref<VehicleDetail[]>([]),total=ref(0),page=ref(1),pageSize=ref(20),loading=ref(false),saving=ref(false),exporting=ref(false),error=ref<ApiErrorDetails|null>(null),editorOpen=ref(false),editingId=ref(''),statusOpen=ref(false),statusRow=ref<VehicleDetail|null>(null),statusTarget=ref<VehicleStatus>('IN_SERVICE')
+const ownership=ref<VehicleOwnership>('OWNED'),tabs:[string,VehicleOwnership][]=[['自有车辆','OWNED'],['外派车辆','DISPATCHED']]
+const filters=ref<QueryModel>({keyword:'',region:'',status:''});const fields:QueryField[]=[{key:'keyword',type:'input',label:'车辆关键词',placeholder:'车牌 / 司机 / 车型',width:220},{key:'region',type:'select',label:'区域',placeholder:'全部区域',width:140,options:[{label:'国内',value:'DOMESTIC'},{label:'海外',value:'OVERSEAS'}]},{key:'status',type:'select',label:'状态',placeholder:'全部状态',width:140,options:Object.entries(vehicleStatusLabels).map(([value,label])=>({label,value}))}]
+const columns:DataTableColumn[]=[{key:'actions',label:'操作',width:250,fixed:'left',slotName:'actions'},{key:'plateNumber',prop:'plateNumber',label:'车牌',minWidth:130},{key:'model',prop:'model',label:'车型',minWidth:180},{key:'fuelConsumptionPer100Km',prop:'fuelConsumptionPer100Km',label:'油耗(L/100km)',minWidth:130,align:'right'},{key:'mileageKm',prop:'mileageKm',label:'当前公里码(km)',minWidth:140,align:'right'},{key:'driverOrDispatchCompany',prop:'driverOrDispatchCompany',label:'司机 / 外派单位',minWidth:160},{key:'phone',prop:'phone',label:'联系电话',minWidth:145},{key:'status',label:'状态',width:100,slotName:'status'},{key:'region',label:'区域',width:100,slotName:'region'}]
+const form=reactive({plateNumber:'',model:'',fuelConsumptionPer100Km:0,mileageKm:0,driverOrDispatchCompany:'',phone:'',region:'OVERSEAS' as VehicleRegion,ownership:'OWNED' as VehicleOwnership,status:'IN_SERVICE' as VehicleStatus,remark:'',recordVersion:0})
+function params(){return{page:page.value,size:pageSize.value,keyword:String(filters.value.keyword||'')||undefined,ownership:ownership.value,region:(filters.value.region||undefined) as VehicleRegion|undefined,status:(filters.value.status||undefined) as VehicleStatus|undefined}}
+async function load(){loading.value=true;error.value=null;try{const r=await listVehicles(params());rows.value=r.records;total.value=r.total}catch(e){rows.value=[];total.value=0;error.value=getApiErrorDetails(e,'车辆加载失败')}finally{loading.value=false}}
+function search(){if(page.value===1)void load();else page.value=1} function selectOwnership(v:VehicleOwnership){if(ownership.value===v)return;ownership.value=v;page.value=1;void load()}
+function reset(){Object.assign(form,{plateNumber:'',model:'',fuelConsumptionPer100Km:0,mileageKm:0,driverOrDispatchCompany:'',phone:'',region:'OVERSEAS',ownership:ownership.value,status:'IN_SERVICE',remark:'',recordVersion:0})}
+function openCreate(){editingId.value='';reset();editorOpen.value=true} async function openEdit(row:VehicleDetail){try{const d=await getVehicle(row.id);editingId.value=d.id;Object.assign(form,{...d,driverOrDispatchCompany:d.driverOrDispatchCompany||'',phone:d.phone||'',remark:d.remark||''});editorOpen.value=true}catch(e){ElMessage.error(masterDataErrorMessage(e,'车辆详情加载失败'))}}
+async function save(){if(!form.plateNumber||!form.model||form.fuelConsumptionPer100Km<=0){ElMessage.warning('请完整填写车辆必填信息');return}saving.value=true;try{const base={plateNumber:form.plateNumber,model:form.model,fuelConsumptionPer100Km:form.fuelConsumptionPer100Km,mileageKm:form.mileageKm,driverOrDispatchCompany:form.driverOrDispatchCompany||null,phone:form.phone||null,region:form.region,ownership:form.ownership,remark:form.remark||null};if(editingId.value)await updateVehicle(editingId.value,{...base,recordVersion:form.recordVersion});else await createVehicle({...base,status:form.status});ElMessage.success(editingId.value?'车辆已更新':'车辆已创建');editorOpen.value=false;await load()}catch(e){ElMessage.error(masterDataErrorMessage(e,'车辆保存失败'))}finally{saving.value=false}}
+function openStatus(row:VehicleDetail){statusRow.value=row;statusTarget.value=row.status;statusOpen.value=true} async function submitStatus(){const row=statusRow.value;if(!row)return;saving.value=true;try{await changeVehicleStatus(row.id,statusTarget.value,row.recordVersion);ElMessage.success('车辆状态已更新');statusOpen.value=false;await load()}catch(e){ElMessage.error(masterDataErrorMessage(e,'车辆状态更新失败'))}finally{saving.value=false}}
+async function exportCsv(){exporting.value=true;try{const{page:_,size:__,...q}=params();saveCsv(await exportVehicles(q),'vehicles.csv')}catch(e){ElMessage.error(masterDataErrorMessage(e,'车辆导出失败'))}finally{exporting.value=false}}
+watch([page,pageSize],load);onMounted(load)
+</script>
+<template><AdminPage class="admin-density"><ListPageLayout aria-label="车辆列表"><template #toolbar><div class="query-panel"><div class="status-tabs density-tabs" role="tablist" aria-label="车辆归属"><button v-for="tab in tabs" :key="tab[1]" role="tab" :aria-selected="ownership===tab[1]" :class="['status-tab',{active:ownership===tab[1]}]" @click="selectOwnership(tab[1])"><span class="density-tab-icon" aria-hidden="true">{{ tab[1] === 'OWNED' ? '🚚' : '🚛' }}</span>{{tab[0]}}</button></div><QueryToolbar v-model="filters" :fields="fields" ariaLabel="车辆筛选" preference-key="overseas-vehicles-query" :loading="loading" @search="search"/></div></template><template #state><LoadErrorState v-if="error" title="车辆加载失败" :message="error.message" @retry="load"/></template><section class="surface-panel vehicle-panel"><DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :total="total" :loading="loading" preference-key="overseas-vehicles-table" row-key="id" empty-text="暂无车辆"><template #toolbar-actions><el-button v-if="access.can(permission.vehicleCreate)" type="primary" @click="openCreate"><Plus :size="16"/>添加车辆</el-button><el-button v-if="access.can(permission.vehicleExport)" :loading="exporting" @click="exportCsv"><Download :size="16"/>导出CSV</el-button></template><template #actions="{row}"><div class="density-actions"><el-button data-tone="neutral" class="density-action"   @click="router.push({name:'overseas-master-data-vehicle-detail',params:{vehicleId:(row as VehicleDetail).id}})">查看</el-button><el-button data-tone="neutral" class="density-action" v-if="access.can(permission.vehicleEdit)"   @click="openEdit(row as VehicleDetail)">编辑</el-button><el-button data-tone="neutral" class="density-action" v-if="access.can(permission.vehicleStatus)"   @click="openStatus(row as VehicleDetail)">状态</el-button></div></template><template #status="{row}"><el-tag>{{vehicleStatusLabels[(row as VehicleDetail).status]}}</el-tag></template><template #region="{row}">{{(row as VehicleDetail).region==='OVERSEAS'?'海外':'国内'}}</template></DataTable></section>
+<AppDialog class="admin-density-dialog" v-model="editorOpen" :title="editingId?'编辑车辆':'添加车辆'" width="min(760px, calc(100vw - 28px))" :confirm-loading="saving" @confirm="save"><el-form class="density-form" label-position="top"><div class="form-grid"><el-form-item label="车辆归属"><el-select v-model="form.ownership"><el-option label="自有车辆" value="OWNED"/><el-option label="外派车辆" value="DISPATCHED"/></el-select></el-form-item><el-form-item label="车牌号"><el-input v-model="form.plateNumber" placeholder="请输入车牌号" /></el-form-item><el-form-item label="车型"><el-input v-model="form.model" placeholder="请输入车辆型号" /></el-form-item><el-form-item label="油耗(L/100km)"><el-input-number v-model="form.fuelConsumptionPer100Km" :min="0.01" :precision="2" placeholder="请输入百公里油耗" /></el-form-item><el-form-item label="当前公里码(km)"><el-input-number v-model="form.mileageKm" :min="0" placeholder="请输入当前里程" /></el-form-item><el-form-item label="联系电话"><el-input v-model="form.phone" placeholder="请输入联系电话" /></el-form-item><el-form-item label="司机 / 外派单位"><el-input v-model="form.driverOrDispatchCompany" placeholder="请输入司机或外派单位" /></el-form-item><el-form-item label="区域"><el-select v-model="form.region"><el-option label="国内" value="DOMESTIC"/><el-option label="海外" value="OVERSEAS"/></el-select></el-form-item><el-form-item v-if="!editingId" label="状态"><el-select v-model="form.status"><el-option v-for="s in ['IN_SERVICE','DISPATCHED','MAINTENANCE','INACTIVE','RETURNED']" :key="s" :label="vehicleStatusLabels[s as keyof typeof vehicleStatusLabels]" :value="s"/></el-select></el-form-item><el-form-item label="备注"><el-input v-model="form.remark" placeholder="请输入备注（选填）" /></el-form-item></div></el-form></AppDialog><AppDialog class="admin-density-dialog" v-model="statusOpen" title="变更车辆状态" width="min(480px, calc(100vw - 28px))" :confirm-loading="saving" @confirm="submitStatus"><el-select v-model="statusTarget" style="width:100%"><el-option v-for="s in ['IN_SERVICE','DISPATCHED','MAINTENANCE','INACTIVE','RETURNED']" :key="s" :label="vehicleStatusLabels[s as keyof typeof vehicleStatusLabels]" :value="s"/></el-select></AppDialog></ListPageLayout></AdminPage></template>
+<style scoped>.vehicle-panel{min-width:0;overflow:hidden}.query-panel{overflow:hidden;border:1px solid var(--cc-border);border-radius:var(--admin-radius);background:#fff}.form-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:var(--admin-space-5) var(--admin-space-6)}</style>
diff --git a/src/modules/overseas-master-data/permissions.ts b/src/modules/overseas-master-data/permissions.ts
new file mode 100644
index 00000000..b9cae1c4
--- /dev/null
+++ b/src/modules/overseas-master-data/permissions.ts
@@ -0,0 +1,18 @@
+export const overseasMasterDataPermissions = {
+  quoteList: 'platform:overseas-master-data:quote:list',
+  quoteCreate: 'platform:overseas-master-data:quote:create',
+  quoteEdit: 'platform:overseas-master-data:quote:edit',
+  quoteStatus: 'platform:overseas-master-data:quote:status',
+  quoteExport: 'platform:overseas-master-data:quote:export',
+  exchangeRateList: 'platform:overseas-master-data:exchange-rate:list',
+  exchangeRateCreate: 'platform:overseas-master-data:exchange-rate:create',
+  exchangeRateEdit: 'platform:overseas-master-data:exchange-rate:edit',
+  exchangeRateStatus: 'platform:overseas-master-data:exchange-rate:status',
+  exchangeRateExport: 'platform:overseas-master-data:exchange-rate:export',
+  vehicleList: 'platform:overseas-master-data:vehicle:list',
+  vehicleCreate: 'platform:overseas-master-data:vehicle:create',
+  vehicleEdit: 'platform:overseas-master-data:vehicle:edit',
+  vehicleStatus: 'platform:overseas-master-data:vehicle:status',
+  vehicleExport: 'platform:overseas-master-data:vehicle:export',
+} as const
+
diff --git a/src/modules/overseas-master-data/presentation.ts b/src/modules/overseas-master-data/presentation.ts
new file mode 100644
index 00000000..d8d4d2b4
--- /dev/null
+++ b/src/modules/overseas-master-data/presentation.ts
@@ -0,0 +1,9 @@
+import type { VehicleStatus } from './types'
+
+export const vehicleStatusLabels: Record<VehicleStatus, string> = {
+  IN_SERVICE: '在役',
+  DISPATCHED: '外派中',
+  MAINTENANCE: '维修中',
+  INACTIVE: '停用',
+  RETURNED: '已归还',
+}
diff --git a/src/modules/overseas-master-data/routes.test.ts b/src/modules/overseas-master-data/routes.test.ts
new file mode 100644
index 00000000..47738eb7
--- /dev/null
+++ b/src/modules/overseas-master-data/routes.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { overseasMasterDataPermissions } from './permissions'
+import { overseasMasterDataRoutes } from './routes'
+
+describe('overseas master data routes', () => {
+  it('uses the frozen stable paths and list permissions', () => {
+    expect(overseasMasterDataRoutes.map((route) => [route.path, route.meta?.permission])).toEqual([
+      ['overseas-master-data/quotes', overseasMasterDataPermissions.quoteList],
+      ['overseas-master-data/exchange-rates', overseasMasterDataPermissions.exchangeRateList],
+      ['overseas-master-data/vehicles', overseasMasterDataPermissions.vehicleList],
+      ['overseas-master-data/vehicles/:vehicleId', overseasMasterDataPermissions.vehicleList],
+    ])
+  })
+
+  it('keeps vehicle detail as a route page and does not add a duplicate partner warehouse route', () => {
+    expect(overseasMasterDataRoutes.at(-1)?.meta?.showPageHeading).toBe(false)
+    expect(overseasMasterDataRoutes.some((route) => route.path.includes('partner-warehouse'))).toBe(false)
+  })
+
+  it('activates the confirmed partner type in the existing warehouse domain without a duplicate route', () => {
+    const apiSource = readFileSync(resolve(process.cwd(), 'src/modules/warehouses/api/platformWarehouses.ts'), 'utf8')
+    expect(apiSource).toContain("'OVERSEAS_PARTNER'")
+    expect(overseasMasterDataRoutes.some((route) => route.path.includes('partner-warehouse'))).toBe(false)
+  })
+})
diff --git a/src/modules/overseas-master-data/routes.ts b/src/modules/overseas-master-data/routes.ts
new file mode 100644
index 00000000..abc8c418
--- /dev/null
+++ b/src/modules/overseas-master-data/routes.ts
@@ -0,0 +1,30 @@
+import type { RouteRecordRaw } from 'vue-router'
+import { overseasMasterDataPermissions as permission } from './permissions'
+
+export const overseasMasterDataRoutes = [
+  {
+    path: 'overseas-master-data/quotes',
+    name: 'overseas-master-data-quotes',
+    component: () => import('./pages/OverseasQuotesView.vue'),
+    meta: { title: '海外仓报价', description: '维护海外合作仓仓储作业与中转派送报价', permission: permission.quoteList },
+  },
+  {
+    path: 'overseas-master-data/exchange-rates',
+    name: 'overseas-master-data-exchange-rates',
+    component: () => import('./pages/ExchangeRatesView.vue'),
+    meta: { title: '汇率管理', description: '维护美元兑人民币月平均汇率', permission: permission.exchangeRateList },
+  },
+  {
+    path: 'overseas-master-data/vehicles',
+    name: 'overseas-master-data-vehicles',
+    component: () => import('./pages/VehiclesView.vue'),
+    meta: { title: '车辆列表', description: '查询国内与海外自有、外派车辆档案', permission: permission.vehicleList },
+  },
+  {
+    path: 'overseas-master-data/vehicles/:vehicleId',
+    name: 'overseas-master-data-vehicle-detail',
+    component: () => import('./pages/VehicleDetailView.vue'),
+    meta: { title: '车辆详情', description: '查看车辆档案、派送订单与更换记录', permission: permission.vehicleList, showPageHeading: false },
+  },
+] satisfies RouteRecordRaw[]
+
diff --git a/src/modules/overseas-master-data/types.ts b/src/modules/overseas-master-data/types.ts
new file mode 100644
index 00000000..4e0847f5
--- /dev/null
+++ b/src/modules/overseas-master-data/types.ts
@@ -0,0 +1,95 @@
+/** 四期海外主数据页面模型，由模块 API 适配层从 Lastleg 稳定 DTO 转换。 */
+export type MasterDataStatus = 'ACTIVE' | 'INACTIVE'
+export type QuoteCurrency = 'USD' | 'CNY'
+export type VehicleRegion = 'DOMESTIC' | 'OVERSEAS'
+export type VehicleOwnership = 'OWNED' | 'DISPATCHED'
+export type VehicleStatus = 'IN_SERVICE' | 'DISPATCHED' | 'MAINTENANCE' | 'INACTIVE' | 'RETURNED'
+
+export interface OverseasWarehouseFee {
+  item: string
+  billingUnit: string
+  unitPrice: number
+  minimumCharge: number | null
+  remark: string | null
+}
+
+export interface OverseasTransitPrice {
+  fbaWarehouseCode: string
+  deliveryMethod: string
+  estimatedMiles: number | null
+  price: number
+  minimumCharge: number | null
+  remark: string | null
+}
+
+export interface OverseasWarehouseQuote {
+  id: string
+  name: string
+  warehouseId: string
+  warehouseName: string
+  warehouseCode: string
+  countryCode: string
+  providerName: string
+  currency: QuoteCurrency
+  effectiveStart: string
+  effectiveEnd: string | null
+  versionCode: string
+  status: MasterDataStatus
+  updatedAt: string
+  updatedBy: string
+  recordVersion: number
+  remark: string | null
+}
+export interface OverseasWarehouseQuoteDetail { summary: OverseasWarehouseQuote; warehouseFees: OverseasWarehouseFee[]; transitPrices: OverseasTransitPrice[]; createdBy: string; createdAt: string }
+
+export interface MonthlyExchangeRate {
+  month: string
+  baseCurrency: string
+  quoteCurrency: string
+  usdToCnyAverage: number
+  status: MasterDataStatus
+  recordVersion: number
+  updatedBy: string
+  updatedAt: string
+  remark: string | null
+}
+
+export interface VehicleSummary {
+  id: string
+  plateNumber: string
+  model: string
+  fuelConsumptionPer100Km: number
+  mileageKm: number
+  driverOrDispatchCompany: string | null
+  phone: string | null
+  region: VehicleRegion
+  ownership: VehicleOwnership
+  status: VehicleStatus
+  remark: string | null
+  recordVersion: number
+  updatedBy: string
+  updatedAt: string
+}
+
+export interface VehicleDeliveryOrder {
+  orderNo: string
+  sourceOrderNo: string | null
+  customerName: string
+  destinationWarehouse: string
+  appointmentDate: string | null
+  status: string
+  relation: string
+}
+
+export interface VehicleReplacementHistory {
+  occurredAt: string
+  orderNo: string
+  action: string
+  relatedVehicle: string
+  reason: string
+  operatorName: string
+}
+
+export type VehicleDetail = VehicleSummary
+
+export interface PartnerWarehouseOption { warehouseId: string; warehouseCode: string; warehouseName: string; countryCode: string }
diff --git a/src/modules/overseas-warehouse/AGENTS.md b/src/modules/overseas-warehouse/AGENTS.md
new file mode 100644
index 00000000..3321afc7
--- /dev/null
+++ b/src/modules/overseas-warehouse/AGENTS.md
@@ -0,0 +1,43 @@
+# Admin 海外仓模块指引
+
+## 样式入口
+
+- 导航“海外仓”的 10 个菜单及关联详情/弹框采用公共密度样式，逐操作范围见 [海外仓样式核对记录](../../../../../docs/Admin海外仓样式核对记录.md)。不要扩展到客户服务、海外业务或未注册产品/箱号页面。
+- 独立页面直接导入 `@/styles/adminDensity.css`；`OverseasDetailShell`、`OverseasReadOnlyDetail` 与共享 `InboundCodeRelationshipDialog` 仅为显式 `dense` 调用启用。正文在 `el-tab-pane` 内的页签必须同时使用 `density-contained-tabs`。
+
+## 读取与路径基准
+
+- 本文件适用于 `src/modules/overseas-warehouse/`，路径默认相对此目录；其他模块以 `../` 开头。应用公共规则见 `../../../AGENTS.md`。
+- 先按下表定位页面，再沿 `routes.ts`、页面 import 与 `api/` 追踪；页面是否开放以正式路由、权限和测试为准。后台接口与状态进入 `../../../../../baiyue-firstleg/lastleg-service/AGENTS.md`，不扩大扫描其他业务模块。
+- 请求统一使用 `../../shared/api/overseasHttp.ts`；不以 `PROTOTYPE_MATRIX.md` 或 `CONTRACT_GAPS.md` 代替代码与服务端契约。
+
+## 页面与业务快速索引
+
+退货库存与退货箱号：`pages/ReturnInventoryManagementView.vue`、`api/returnInventory.ts`，由 `routes.ts` 的 `return-inventory/return-cartons` 分别以 `mode=inventory/cartons` 进入；只消费 Lastleg `returnreceipt/` 的平台库存、箱号、流水和标签接口。退货出库从 `pages/OutboundsView.vue` 进入，区别于 `pages/ExceptionOrdersView.vue` 的派送异常退回。
+
+| 关键词 | 页面/路由入口 | API 与联查 |
+|---|---|---|
+| 排车车型、托位容量与限重提示 | `dispatchVehicleSpecs.ts`、`components/SmartDispatchDialog.vue`、`pages/DispatchesView.vue` | 预排车型与排车编辑选项共用规格入口：大车 30 托/40000 LB，小车 15 托/10000 LB；超重提示在预排组件，不能把前端提示当作服务端允许提交的依据。回归见 `pages/DispatchesView.test.ts`、`pages/prototypeContract.test.ts` |
+| 仓储转运审核、通过与驳回 | `pages/LastMileOrdersView.vue`、`components/WarehouseTransferReviewDialog.vue` | `api/warehouseTransfers.ts` 的列表、详情及 `/warehouse-transfers/{transferNo}/review`；审核按钮要求 `permissions.ts` 的 `warehouseTransferApprove` 且行类型为 `WAREHOUSE_TRANSFER`、状态为 `PENDING_REVIEW`。请求携带该行客户范围和转运单号，审核结论为 `APPROVE/REJECT`，驳回原因必填；这是尾程订单内的审核弹框，不是独立审核路由或排车转派送入口 |
+| 尾程订单控制与柜级入仓计划转换 | `pages/LastMileOrdersView.vue`、`pages/LastMileOrderDetailView.vue` | 柜子工作台按 `sourceContainerBookingId` 消费 `/orders/container-summaries`；服务端分页返回全部稳定来源柜，计划已经齐全的柜仍保留用于接柜仓查询和修改，并按冻结 `plannedArrivalAt` 升序、空值最后排序。详情返回全柜订单且不受列表分页截断；单票手工计划保存后，由服务端在整柜最后一票计划齐全时自动生成并绑定全柜托盘码，一票柜立即生成；`resourcePendingPlanCount` 只表示自动生成异常的重试入口，不是正常人工步骤。柜级确认弹框先调用 `/inbound-plans/container-preview`，按服务端 FBA/一件代发/私人地址分组展示头程已有、海外仓补充和最终托数以及 `readiness/blockers`；散货最终托数不得少于头程已有托盘码，差额连续补码且不阻断流程；一件代发必须严格按不可变头程封托托盘数整体入库，单票表单托数锁定且服务端再次失败关闭校验。前端不计算托数、不逐票建计划、不预占托盘，再把同一 `snapshotVersion/snapshotHash` 原样提交 `/inbound-plans/convert-container`，快照冲突后重新获取预览。服务端只为剩余订单逐票生成独立计划，并为异常遗留的人工计划补齐真实托盘，整批原子且重放不得产生第二批资源。单票完整入库计划、暂扣/解除和八行人工节点均从 `api/lastMileOrders.ts` 提交订单版本与幂等键；预计到仓时间只读展示来源柜冻结值，不进入人工计划请求，服务端按整柜校验并写入同一日期；入仓码只读展示并提交订单冻结值，不允许人工改写，暂扣资格、接柜仓锁定原因和操作能力只消费服务端结果，人工节点一经保存不得回退柜级节点。转仓候选只取 `../iam/api/platformIam.ts` 的平台公共 `ACTIVE + FBA` 仓主档；Backend `lastleg-service/` |
+| 入仓单、入仓计划、FBA 预约 | `pages/InboundOrdersView.vue`、`pages/InboundOrderDetailView.vue` | 列表/预约 `api/inboundOrders.ts`，计划列表/详情 `api/inboundPlans.ts`；Backend `lastleg-service/inboundplan/` |
+| 排车查询、智能预排与转派送 | `pages/DispatchesView.vue`、`pages/DispatchDetailView.vue`、`components/SmartDispatchDialog.vue` | `api/dispatches.ts`；Backend `lastleg-service/dispatch/`、`delivery/`；覆盖详情、候选、草稿柜、托盘锁、`pre-arrange` 和 `transfer-delivery`。路线只读并由已排托盘关联的 FBA 仓去重后以英文逗号连接，预排和普通编辑均不接收人工路线。一次转派送仍生成一张车辆级出库单，响应的 `deliveries` 按目的 FBA 仓返回多张派送单。页面能力必须由正式路由、API 调用和测试共同证明 |
+| 海外出库与派送 | `pages/OutboundsView.vue`、`pages/OutboundDetailView.vue`、`pages/DeliveryOrdersView.vue`、`pages/DeliveryOrderDetailView.vue` | `api/outbounds.ts`、`api/deliveryOrders.ts`；出库详情使用 `deliveries` 展示按目的 FBA 仓拆出的全部派送单，派送列表和详情必须显示目的 FBA 仓。人工状态入口不提供完成派送；签收资料保存成功后提示自动完成并刷新列表。出库列表按类型筛选并展示中文类型，状态须覆盖 `WAIT_PICK/待拣货`、`PICKING/拣货中`、`PICKED/已拣货`、`WAIT_OUTBOUND/待出库`、`OUTBOUNDED/已出库` 和 `CANCELLED/已取消`；仅未开始的 `WAIT_PICK/WAIT_OUTBOUND` 允许取消。一件代发新建弹窗直接跨客户加载服务端可用候选，不单独展示客户筛选，海外仓必选并优先默认洛杉矶仓；订单条件可按订单号、入库单号、客户、托盘号、SKU 或品名查询/重置，以托盘+SKU 行分页多选。提交时从所选行解析唯一客户，并校验所选行属于当前唯一海外仓，不要求先选客户。退货出库客户下拉同时展示客户名称与联系电话并支持手机号检索，客户和仓库选项独立容错加载；选择客户后须立即按当前默认/已选海外仓加载库存。SKU 与箱号查询均使用输入态/已查询态分离，只允许点击查询按钮后生效；支持英文逗号批量条件，查询时清除空格并按任一条件命中，左右列表分别提供每页 5/10/20/50 条选择。SKU 列表只展示 `availableQuantity > 0` 的未占用可用数量，合箱后已扣减为零的 SKU 不再作为可选库存显示，实际作业以可用箱唛选择和箱内 SKU 明细扣减为准。取消、派送列表/详情及退回入口对应 Backend `lastleg-service/delivery/`、`dropship/` |
+| 异常退回与客户回访 | `pages/ExceptionOrdersView.vue`、`pages/CustomerVisitsView.vue` | `api/exceptionOrders.ts`、`api/customerVisits.ts`；异常关系解析、异常建档、派送退回、完成/状态和回访附件对应 Backend `lastleg-service/exceptionorder/`、`customervisit/` |
+| 库存余额、库位与流水 | `pages/InventoryView.vue`、`pages/InventoryDetailView.vue`、`pages/InventoryTransactionsView.vue` | `api/inventory.ts`；业务库存归 `lastleg-service/inventory/`，实物资源归 `warehouse-overseas-service/` |
+| 托盘、箱唛、产品与换标 | `pages/PalletsView.vue`、`pages/CartonsView.vue`、`pages/ProductsView.vue`、`pages/RelabelOrdersView.vue` 及详情页 | `api/pallets.ts`、`api/relabelOrders.ts`；换标详情展示 PDA 完工照片与复核人，状态区分待客户确认和待出库；路由是否公开以 `routes.ts` 为准 |
+
+## 履约硬边界
+
+- 托盘管理单张打印：`pages/PalletsView.vue` 每行“打印”经 `api/pallets.ts` 的 `getPalletLabelPdf` 下载当前托盘一页 PDF；使用该行仓库 ID 与托盘 ID，权限复用托盘列表。Backend `warehouse-overseas-service` 的 `PalletLabelPrintService` 读取公共托盘；有 FBA 仓码的托盘与国内统一使用 Print `FBA_PALLET_A4_LANDSCAPE_V1`（297×210 mm，FBA 仓码、完整托盘号 Code 128、托盘号文字），其他托盘使用 `INBOUND_MARK_V1`。不在前端生成标签、改码或维护第二套模板。
+
+- API 为 `api/dispatches.ts`、`api/outbounds.ts`、`api/deliveryOrders.ts`；Backend `lastleg-service/dispatch/`、`delivery/`、`dropship/`。一件代发独立出库，从服务端库存位置选择并携带幂等键；普通出库及换标单经头程排车转出库，按托盘快照绑定头程箱唛，PDA 按托盘作业，详情展示箱唛与已拣数量；排车转派送按稳定 `dispatchNo` 进入服务端命令，可在 `PENDING_DEPARTURE`、`PICKING`、`READY_TO_DEPART` 状态执行并须在 PDA 发车前生成一张待出库单及按目的 FBA 仓拆分的派送单
+- API 为 `api/exceptionOrders.ts`、`api/customerVisits.ts`；Backend `lastleg-service/exceptionorder/`、`customervisit/`。异常处理只消费服务端 `allowedActions/version`；完成时至少上传一份异常证据。派送退回先从服务端原出库拣货事实选择入仓单和可退箱数，不允许自由填写 SKU/数量；退回海外仓时必须选择服务端校验的目标托盘和库位，库存恢复、异常完成与派送 `RETURNED` 由服务端原子推进。回访附件和派送完成/状态均走海外真实 API
+
+## 验证
+
+- 一件代发出库候选选择：`pages/OutboundsView.vue` 按 `inventoryPositionId + skuCode` 保留跨页选择，只提供本页全选；查询/重置回到第一页，切换海外仓清空选择。提交仍校验同客户、同海外仓，数量取所选行的 `availablePackages`（箱数），不能按 SKU 件数替代。候选交互回归见 `pages/OutboundsView.selection.test.ts`；状态展示与取消门禁见 `pages/OutboundsView.test.ts`、`pages/OutboundDetailView.test.ts`。
+- 转运审核定向测试：从应用根运行 `pnpm test src/modules/overseas-warehouse/api/warehouseTransfers.test.ts src/modules/overseas-warehouse/pages/prototypeContract.test.ts`，分别核对客户作用域/API 与审核入口权限、状态。
+- 排车列表编辑、托盘移除、BOL PDF 和转派送从 `pages/DispatchesView.vue` → `api/dispatches.ts` 进入；智能预排的候选、草稿柜与托盘锁从 `components/SmartDispatchDialog.vue` 进入。回归为 `pages/DispatchesView.test.ts`、`pages/prototypeContract.test.ts`，不要把列表操作与预排草稿当作同一入口。
+- 从应用根按目标页面选择相邻测试：`pnpm test src/modules/overseas-warehouse/<目标测试路径>`；API 或类型变化同时运行 `pnpm typecheck`。应用完整门禁继续遵循上层指引。
+- 索引变更从后端根运行 `./scripts/agents-index-contract.ps1`。离线检查不代替真实 HTTP 和人工截图验收。
diff --git a/src/modules/overseas-warehouse/API_INTEGRATION_MATRIX.md b/src/modules/overseas-warehouse/API_INTEGRATION_MATRIX.md
new file mode 100644
index 00000000..e00781c4
--- /dev/null
+++ b/src/modules/overseas-warehouse/API_INTEGRATION_MATRIX.md
@@ -0,0 +1,34 @@
+# 海外仓真实接口接入矩阵
+
+海外业务与库位/托盘资源通过共享 `overseasHttp` 请求海外 Gateway；仓库主数据候选只通过国内 `http` 请求国内 Warehouse。长整型 ID 及业务单号均按字符串传递，path 参数使用 `encodeURIComponent`。接口事实已核对 Controller/DTO、Springdoc 与 `lastleg-service/src/main/resources/openapi/overseas-business-v1.yaml`，不再沿用“海外 Gateway 提供仓库根列表”的旧结论。
+
+| 页面/能力 | Method + Path | Params / Body（当前 adapter） | 权限与承载 |
+|---|---|---|---|
+| 尾程列表/详情 | `GET /platform/v1/last-leg/orders`；`GET /orders/{id}` | list query：`page,size,orderNo,orderType,warehouse,inboundCode,sourceOrderNo,containerNo,currentStatus,transferWarehouseCode,abnormal,detained,createdFrom,createdTo`；平台跨客户，不传 `customerId`；货主只消费响应 `customerName`，空值显示 `—` | `platform:overseas-warehouse:last-mile-order:list`；真实分页、空态、错误及 request/trace 元数据；详情只读展示离仓关联事实 |
+| 尾程转目的仓 | `PUT /platform/v1/last-leg/orders/destination` | body：`orderIds:string[],warehouseId,warehouseCode,warehouseName,remark?`；目的仓只取国内 Warehouse 正式 `FBA + ACTIVE` 公共候选，候选切换时同步提交精确字符串 ID、编码和名称，不允许自由输入 | `...:last-mile-order:edit`；保留原尾程订单/入仓码多选范围与跨客户能力；候选或提交失败保留弹框并展示错误元数据，不提示成功 |
+| 尾程转入仓计划 | `POST /platform/v1/last-leg/inbound-plans/convert` | body：`orderId:string,customerId:string`，客户作用域精确取自所选尾程行；缺失时前端失败关闭 | `...:inbound-order:create`；A0404/A0409 保留 code/requestId/traceId；不接补托/PDA |
+| 尾程整柜转入仓计划 | `POST /platform/v1/last-leg/inbound-plans/convert-container` | body：`sourceContainerBookingId:string`；只调用一次柜级原子接口，不在前端循环逐票；返回一个计划数组，每个尾程订单/入仓码对应一个独立计划 | `...:inbound-order:create`；成功按接口返回计划数提示并刷新原待分配订单列表，不用当前订单页行数校验整柜总数；错误保留 code/requestId/traceId |
+| 柜级计划进度/详情 | `GET /platform/v1/last-leg/orders/container-summaries`；`GET /container-summaries/{sourceContainerBookingId}` | summary：`sourceContainerBookingId,containerNo?,totalOrderCount,inboundCodeCount,missingInboundCodeCount,planCount,plannedInboundCodeCount,pendingPlanCount,plannedArrivalAt?,allPlansReady,blockingReason?`；list query：`page,size,containerNo?,createdFrom?,createdTo?`；detail：`summary,orders[]`，订单与计划 ID 均为字符串 | 独立“柜子”Tab 消费服务端全柜分页，默认按计划到仓升序且 null 最后；详情抽屉显示柜内全部订单、入仓码和独立计划状态；同一摘要也供按柜生成选择框，不从订单分页本地拼柜 |
+| 入库列表 | `GET /platform/v1/last-leg/inbound-plans` | query：`page,size,planNo,inboundCode,status,warehouse,fbaWarehouseCode,appointmentStatus,dispatchStatus,createdFrom,createdTo`；平台跨客户；每行返回计划级 `assigned/mergeAllowed/urgent` | `...:inbound-order:list`；`lineId/planId/orderId/customerId` 均为字符串；合托展示为可选提示，不作为完成门禁 |
+| 入库详情 | `GET /platform/v1/last-leg/inbound-plans/{planNo}` | query：显式 `customerId`；path 编码；`allocations[]` 直接返回实际 `palletNo`、`palletOwnerPlanNo`、`palletOwnedByCurrentPlan` | 同 list；缺客户范围时页面明确报错；`sourceOrderId` 字符串化；跨计划合托按分配事实展示真实托盘码、所属计划和本单箱数，不把外部托盘计入当前计划自有托盘数 |
+| FBA 预约新增 | `POST /platform/v1/last-leg/inbound-plans/fba-appointments/batch` | body：`customerId,lineIds:string[],appointmentNo,appointmentAt,expectedLoadingAt,appointmentStatus,appointmentRemark?` | `...:inbound-order:fba-appointment`；只允许同客户、同 FBA 仓勾选 |
+| FBA 预约详情/编辑 | `GET /fba-appointments/{appointmentNo}?customerId=...`；`PUT` 同 path | PUT body：`customerId,appointmentAt,expectedLoadingAt,appointmentStatus,appointmentRemark?` | GET 同 list；PUT 同 appointment；失败保留弹框和错误元数据 |
+| 排车列表/详情 | `GET /platform/v1/last-leg/dispatches`；`GET /dispatches/{dispatchNo}` | list query：`page,size,dispatchNo,vehiclePlate,status,fbaAppointmentNo`；不传客户 | `...:inbound-order:list`；Controller 受 `lastleg.dispatch-query-api.enabled` 控制 |
+| 排车候选 | `GET /platform/v1/last-leg/dispatches/candidates` | query：`planIds?`（逗号分隔长 ID）、`orderNo?`,`fbaWarehouseCode?`,`sourceStage?`,`draftToken?` | 同 inbound list；仅发 `PLAN/RECEIVED` |
+| 草稿/锁/预排 | `GET /dispatches/drafts`；`POST /drafts/containers`；`DELETE /drafts/{draftToken}/containers/{containerId}`；`POST /draft-locks/lock|unlock|release`；`POST /pre-arrange` | 车厢：`draftToken,capacity`；锁：`planPalletId,draftToken,draftContainerId?`；释放：`draftToken`；预排：`planPalletIds:string[],draftToken` | `...:inbound-order:smart-dispatch`；Controller 受 `lastleg.smart-dispatch-api.enabled` 控制；409 锁冲突显示真实错误；不调用编辑、取消、depart、PDA 或派送 |
+| 库存汇总/余额 | `GET /platform/v1/last-leg/inventory/summary`；`GET /balances` | summary 强制 `page=1,size=200`；余额保留页面分页；支持 `skuCode,productName` 与仓库/入库/批次/库位筛选；不传客户；列表/详情客户只显示 `customerName`，海外仓只显示 `overseasWarehouseName`，空值为 `—` | `...:inventory:list`；只读，不调用 allocate/unallocate/pick/ship；不以客户 ID、本地客户候选、国内来源仓或目的仓猜名称 |
+| 库存位置/进销存 | `GET /inventory/balances/{balanceId}/positions`；`GET /inventory/ledger` | position：`palletNo?,batchNo?,inventoryStatus?`；ledger 含 `page,size,skuCode` 与业务单/仓库/时间筛选 | 同 inventory list；`balanceId` 编码；只展示后端事实 |
+| 公共海外收货仓候选（国内 HTTP） | `GET /platform/v1/warehouse-admin` | `tenantId=0,page=1,size=200,capabilityCode=RECEIVING,warehouseType=OVERSEAS,status=ACTIVE` | 国内 Warehouse 是唯一仓库主数据源；托盘、库存和换标复用公共候选并保留字符串 ID，不请求海外仓库根路径 |
+| 托盘列表/详情 | `GET /platform/v1/warehouse-admin/{warehouseId}/pallets`；`GET /pallets/{palletId}` | list：`page,size,keyword?,palletType?,status?`；无客户参数 | `...:pallet:list`；仓库/托盘长 ID 编码 |
+| 托盘新增 | `POST /platform/v1/warehouse-admin/{warehouseId}/pallets` | body：`palletCode,palletType,fbaWarehouseCode,capacityCbm,unitPrice,status,locationId,remark`，明确不带 `version` | 前端 `...:pallet:create`；失败不模拟成功 |
+| 托盘编辑 | `PUT /platform/v1/warehouse-admin/{warehouseId}/pallets/{palletId}` | 新增同字段，并必传详情返回的 `version:number` | `...:pallet:edit`；旧版本返回 `A0409`，页面保留真实冲突错误。原型未定义删除，模块不保留删除 adapter/入口 |
+| 换标列表/详情 | `GET /platform/v1/last-leg/relabel-applications`；`GET /{relabelNo}` | list：`page,size,skuCode?,status?`；平台跨客户；详情 path 编码 | `...:relabel-order:list`；未返回字段不填演示值 |
+| 换标创建 | `POST /platform/v1/last-leg/relabel-applications?customerId={positiveLong}` | `customerId` 只在 query；body：`customerOrderNo,overseasWarehouseId,labelDeadline,contactName,contactPhone,remark?,idempotencyKey,items[]` | `...:relabel-order:create`；显式 ACTIVE 客户与公共 ACTIVE+OVERSEAS+RECEIVING 收货仓分别选择；同一弹框会话重试复用同一幂等键，失败保留 |
+| 换标状态 | `PUT /platform/v1/last-leg/relabel-applications/{relabelNo}/status` | body：`status,remark?` | `...:relabel-order:status`；仅允许 `PENDING_PROCESSING→PROCESSING/REJECTED/CANCELLED`、`PROCESSING→COMPLETED/REJECTED/CANCELLED` |
+
+## 原型与范围
+
+- 页面 ID：尾程 `fba-last-mile-order*`、入库 `fba-inbound-order*`、换标 `fba-relabel-order*`、托盘 `fba-pallet*`、库存 `fba-inventory*`。排车没有独立海外仓原型页，只在入库页智能排车弹框及既有排车查询页承载。
+- 托盘原型操作列仅查看、编辑，工具栏仅新增；后端即使存在 DELETE，Admin 也不暴露。所有业务表格操作列保持第一列并固定左侧。
+- 箱号和产品库不设独立正式 routes；海外出库、退货出库、海外派送、PDA、卸柜照片和库存离仓命令均按海外仓全流程的正式页面与接口归属验收，内部事件仍只作为服务端协作事实。
+- 1920×1080、浏览器 100% 的人工截图仍待验收。
diff --git a/src/modules/overseas-warehouse/CONTRACT_GAPS.md b/src/modules/overseas-warehouse/CONTRACT_GAPS.md
new file mode 100644
index 00000000..d31d5d74
--- /dev/null
+++ b/src/modules/overseas-warehouse/CONTRACT_GAPS.md
@@ -0,0 +1,25 @@
+# 海外仓前端剩余契约与环境缺口
+
+已接请求、权限、客户作用域和错误承载见 `API_INTEGRATION_MATRIX.md`。本文件只保留当前仍影响真实联调或原型完整度的差异，不再把 FBA 预约、换标写接口、托盘公共作用域或静态 OpenAPI 记为“未接/不存在”。
+
+## 需后端或产品继续确认
+
+- **库存客户/海外仓快照**：正式余额 DTO 已返回 `customerName` 与 `overseasWarehouseName`，Admin 列表和详情只显示这两个服务端快照，空值为 `—`，不以 `customerId`、客户候选、国内来源仓、目的仓/FBA 仓或固定值补齐。当前测试数据“客户全为 — / 海外仓显示义乌仓”属于后端库存事实阻断：`LoadingCompletedConsumer#registerInTransit` 的客户名来自可能为空的跨区 `source.customerName`，并把国内装柜 `payload.warehouseName` 传入库存的 `overseasWarehouseName`；后续命中既有余额时 `InventoryCommandService#balance` 不会修订快照。后端需保证正式客户名称快照，并在实际海外收货仓冻结前保持海外仓为空、冻结后写入真实海外收货仓；前端不修复或猜测历史/错误事实。
+- **换标原型字段**：列表 Summary 仍不含 `productNameZh/labelRequirement/relabelFile/budgetTotal/relabelCost`；本模块没有可用的换标文件上传端点。页面不伪造金额或文件名。创建 DTO 额外要求海外仓、截止时间、联系人、电话、货件号和新 SKU，这是完成真实创建的最小扩展。
+- **托盘新增服务端权限**：前端新增按钮按 `platform:overseas-warehouse:pallet:create` 控制，但当前审计的 `PlatformWarehouseResourceController#createPallet` 未见对应 `@PreAuthorize`；需后端补齐或确认由网关等价强制。原型要求“托盘重量”，当前 Save DTO 无该字段，页面不伪造或发送。
+- **托盘状态语义**：原型只给闲置/占用，DTO 还允许 `SCRAPPED`。是否允许 Admin 在普通编辑中直接改为报废仍需确认；不新增独立停用/报废动作。PUT 已按冻结契约携带详情 `version`，旧版本 `A0409`。
+- **库存导出**：后端已存在只读 `GET /inventory/balances/export` 与 `GET /inventory/ledger/export`（权限 `...:inventory:export`），当前模块页面/adapter 尚无二进制下载实现；原型承载与共享下载约定确认后再接，不能用 JSON 请求替代。
+- **入库补充托盘**：`POST /inbound-plans/{planNo}/pallets/supplement` 已存在，但权限、幂等、打印及原型承载未整体冻结，Admin 不接。FBA 预约创建、详情和编辑已经接入。
+
+## 真实环境仍需的数据与配置
+
+- 可获得海外 Token 且持有矩阵 canonical 权限的 Admin 测试账号；失败响应需验证 `requestId/traceId`。
+- 至少一个 ACTIVE 客户，以及国内 Warehouse 中 `tenantId=0`、`OVERSEAS`、`ACTIVE`、启用 `RECEIVING` 的公共收货仓；换标写验收还需允许关联的专用测试尾程订单/SKU，不能操作历史数据。
+- 带 `sourceOrderId`、明细和托盘的入仓计划，以及已有 FBA 预约号，用于详情长 ID 与预约编辑。
+- 开启 `lastleg.dispatch-query-api.enabled`、`lastleg.smart-dispatch-api.enabled`，并准备未锁候选托盘；验证 409 草稿锁冲突、关闭释放和预排回读。
+- 至少一个国内公共海外收货仓 ID，以及 Warehouse Overseas 中引用同一 ID 的公共托盘；新增需验证洛杉矶仓下 `IDLE + ABE3`，编辑需验证正确 version 与旧 version `A0409`。
+- 至少一条含 SKU/产品名、位置和 ledger 的库存事实，用于核对分页、汇总与长 ID；不调用离仓命令。
+
+## 仍然排除
+
+箱号平台、产品库、海外出库、退货出库、海外派送、PDA 扫描/拣货/卸柜照片、内部事件，以及库存 `allocate/unallocate/pick/ship`。不得为自动化覆盖扩展这些前端路径。
diff --git a/src/modules/overseas-warehouse/PROTOTYPE_MATRIX.md b/src/modules/overseas-warehouse/PROTOTYPE_MATRIX.md
new file mode 100644
index 00000000..f726c931
--- /dev/null
+++ b/src/modules/overseas-warehouse/PROTOTYPE_MATRIX.md
@@ -0,0 +1,59 @@
+# 海外仓原型核对矩阵
+
+原型来源：`docs/悦/货代SAAS平台后台/prototype-src/modules/03-overseas-warehouse.html`。
+
+当前范围按海外仓全流程维护。箱号管理、产品库不设独立正式路由，其数据通过入仓、箱唛、SKU 与库存页面承载；正式范围包含尾程订单、入库单、换标、转运、退货、托盘、库存、排车、出库、派送、异常退回、客户回访和一件代发。
+
+| 页面 | 操作 | 原型证据 | 原型承载方式 | 当前实现（开工前） | 冻结结论 |
+|---|---|---|---|---|---|
+| 尾程订单 | 列表/筛选 | `page-last-mile-orders`，868–897 行；`lastMileSearch()`、`lastMileReset()` | 独立列表页，状态标签、查询区、横向宽表 | `/prototype/overseas-warehouse-orders/*` 占位 | 建立正式列表路由；操作列第一列，保留原型字段顺序，接口未接时显示明确契约态 |
+| 尾程订单 | 详情 | `page-last-mile-order-detail`，899–909 行；`openLastMileOrderDetail()`、`renderLastMileOrderDetail()` | 独立详情页，紧凑页头；订单信息、订单明细、计划信息、关联单据、货物信息、操作记录两列分区 | 正式参数路由与 `LastMileOrderDetailView.vue`；接口待接入时保留字段、空表与明确契约态 | 保持独立页面，不改为抽屉或弹框；出库计划和派送通过对应子单与独立操作入口展示 |
+| 尾程订单 | 导入 | `modal-lmo-import`，933 行 | 居中弹框，约 980px | 无正式实现 | 后端导入契约未定义，本批不提供可点击成功入口 |
+| 尾程订单 | 导出字段 | `modal-lmo-field-selector`，935 行 | 居中弹框，约 760px | 无正式实现 | 后端异步导出契约未定义，本批不模拟导出 |
+| 尾程订单 | 批量转仓 | `modal-lmo-batch-transfer`，921 行 | 居中弹框，约 720px | 无正式实现 | 属库内操作，但写接口/幂等契约未定义；暂不提供写入口 |
+| 尾程订单 | 入库计划 | `modal-lmo-inbound-plan`，912 行 | 居中弹框，约 720px | 无正式实现 | 属于当前入仓链路；待写接口与状态机冻结后按原型实现 |
+| 尾程订单 | 出库计划 | `modal-lmo-outbound-plan`，927 行 | 居中弹框，约 760px | 无正式实现 | 明确属于库存离仓，排除，不实现 |
+| 入库单 | 列表/筛选 | `page-fba-inbound-order`，491–525 行；`fbioSearch()`、`fbioReset()` | 独立列表页，查询区、批量预约/排车、横向宽表 | `/prototype/fba-returns/inbound-orders` 占位 | 已接真实分页、显式客户、筛选、状态、加载/错误/空态；排车字段后端未提供，保持只读空值 |
+| 入库单 | 详情 | `page-fba-inbound-order-detail`，684–691 行；`openFbaInboundOrderDetail()` 8567–8575 行 | 独立详情页；单据信息、仓储信息、预约与排车三组字段，应收费用明细位于正文 | 正式参数路由与 `InboundOrderDetailView.vue` | 已接计划详情和 `sourceOrderId`；接口未提供的预约/排车时间、备注和费用继续显示空值 |
+| 入库单 | 编辑 | `modal-fbio-edit`，527 行 | 居中弹框，约 880px | 无正式实现 | 待海外区域写接口与状态机冻结后实现 |
+| 入库单 | 预约 | `modal-fbio-appointment`，526 行 | 居中弹框，约 720px | 无正式实现 | 待预约/排车接口与幂等契约冻结后实现 |
+| 入库单 | 新增 | 页面按钮存在但原型未定义对应可达表单 | 原型未定义 | 无正式实现 | 标记待确认，不自行选弹框/抽屉/独立页 |
+| 库存管理 | 列表/筛选 | `page-inventory-overview`，51–89 行；`unifiedInventorySearch()`、`unifiedInventoryReset()` | 独立列表页，六项紧凑汇总、查询区、横向宽表 | 无正式页面 | 已接 SKU 余额和汇总；散板指标后端无独立字段，显示空值，不以 receiving 等桶冒充 |
+| 库存管理 | 详情 | `page-warehouse-stock-detail`，938–983 行；`renderWarehouseStockDetail()` 6624–6646 行 | 独立详情页；商品/库存汇总左右并列，库位库存、托盘箱号、进销存明细连续分区 | 正式参数路由与 `InventoryDetailView.vue` | 已接余额、库位/托盘位置和订单范围流水；流水缺 SKU 时明确提示，只读展示出库关联且不提供离仓操作 |
+| 库存管理 | 导出 | 列表页“导出Excel”按钮 | 页面工具栏动作，具体浮层未定义 | 无正式实现 | 待 File 导出类型与海外 API 契约补齐，不模拟成功 |
+
+第一批明确不实现：`overseas-outbound`、`fba-outbound-order*`、`fba-return-outbound`、尾程订单的出库计划及任何海外派送/库存离仓操作。
+
+尾程列表按 `page-last-mile-orders` 保留“全部 / 待分配”状态页签，并保留入库单号、出库单号、派送单号、换标单号的原型列顺序；其中出库单号和派送单号仅为只读关联事实，不提供链接、详情跳转或操作入口。箱号列表遵循 `renderFbaCarton()`：仅“在库”记录显示编辑入口，“已出库”记录只读。
+
+第一批桌面布局按 `1920×1080` 验收：列表使用紧凑查询区与横向宽表；详情使用连续白底、双列或三列紧凑字段分区，长表保持横向滚动。当前缺少人工页面截图，视觉结果待总控按真实页面截图确认。
+
+## 第二批：换标单、托盘、箱号、产品库
+
+| 页面 | 操作 | 原型证据 | 原型承载方式与尺寸 | 实施结论 |
+|---|---|---|---|---|
+| 换标单 | 列表/筛选 | `page-fba-relabel-order`，531–555 行；`renderFbaRelabelOrder()` 8042–8058 行 | 独立列表页；SKU、状态筛选；换标单号、SKU、中文品名、箱数、预算总价、贴标要求、文件、状态 | 建立正式列表；操作列按仓库规则移到第一列；无查询接口时保持空表和契约态 |
+| 换标单 | 详情 | `page-fba-relabel-order-detail`，696–699 行；`openFbaRelabelOrderDetail()` 8605–8613 行 | 独立详情页；单据信息、商品信息、作业要求、费用明细 | 建立正式参数路由，详情复用 `list` 权限；不改为弹框或抽屉 |
+| 换标单 | 新增 | `modal-fba-relabel-form`，556–566 行；`openFbaRelabelCreate()` 7994–8001 行 | 居中弹框，最大宽度约 760px；订单信息与作业要求分组 | 按原型建立 `create` 权限入口与弹框；写接口未冻结，保存禁用且不模拟成功 |
+| 换标单 | 编辑/审核 | 同一 `modal-fba-relabel-form`；`openFbaRelabelEdit()` 8003–8022 行 | 居中弹框，约 760px；显示状态和预算报价，提交文案为“提交审核” | 使用独立 `edit` 权限；仅保留承载和字段契约，端点/状态机未冻结前不提交 |
+| 托盘管理 | 列表/筛选 | `page-fba-pallet`，626–652 行；`renderFbaPallet()` 8319–8335 行 | 独立列表页；编码、类型、仓库、状态筛选；横向表格 | 已接公共托盘分页；资源请求不传客户参数，仓库候选独立加载，不受页面客户筛选控制 |
+| 托盘管理 | 详情 | `page-fba-pallet-detail`，702–705 行；`openFbaPalletDetail()` 8615–8621 行 | 独立详情页；基础信息、使用信息 | 已接真实详情，复用 `list` 权限；后端未提供 FBA 仓和业务绑定汇总，显示空值 |
+| 托盘管理 | 新增/编辑 | `modal-fba-pallet-form`，654 行；`openFbaPalletForm()` 8358–8375 行 | 同一居中弹框，最大宽度约 760px；两列字段 | 已接真实 POST/PUT 和独立权限；FBA 仓不在 DTO 中，原字段只读提示“接口未提供” |
+| 箱号管理 | 列表/筛选 | `page-fba-carton`，657–681 行；`renderFbaCarton()` 8428–8448 行 | 独立列表页；箱号、FBA 仓、状态筛选 | 本期暂缓并移除正式路由；保留页面源码和操作列首列约束，后续恢复仍不承接离仓动作 |
+| 箱号管理 | 详情 | `page-fba-carton-detail`，708–711 行；`openFbaCartonDetail()` 8623–8630 行 | 独立详情页；基础信息、商品信息 | 本期暂缓并移除正式参数路由；保留详情源码，关联出库单始终只读 |
+| 箱号管理 | 新增/编辑 | `overlays.html` 的 `modal-fba-carton-form`，1528–1541 行；`openFbaCartonForm()` 8460–8481 行 | 同一居中弹框，最大宽度约 860px；两列字段；已出库不可编辑 | 本期暂缓；保留禁用弹框源码，不接写接口 |
+| 产品库 | 列表/筛选 | `page-fba-product`，720–745 行；`renderFbaProduct()` 8695–8711 行 | 独立列表页；SKU、中文品名、品类筛选 | 本期暂缓并移除正式路由；保留页面源码和操作列首列约束 |
+| 产品库 | 详情 | `page-fba-product-detail`，714–717 行；`openFbaProductDetail()` 8683–8690 行 | 独立详情页；基础信息、包装信息、其他信息 | 本期暂缓并移除正式参数路由；保留详情源码 |
+| 产品库 | 新增/编辑 | `modal-fbap-add`，748–771 行；`openFbapModal()`、`openFbapEditModal()` 8753–8767 行 | 同一居中弹框，最大宽度约 560px；单列标签/控件布局 | 本期暂缓；保留禁用弹框源码，不接写接口 |
+
+第二批所有新增/编辑弹框按原型尺寸和字段顺序承载；接口未冻结时只用于展示已确认的交互容器，不提供可成功提交路径。导出接口同样未定义，本批不显示可用导出动作。
+
+## 第三批：库存只读支撑页
+
+| 页面 | 操作 | 原型证据 | 原型承载方式与布局 | 实施结论 |
+|---|---|---|---|---|
+| 进销存记录 | 列表/筛选 | `page-inventory-transactions`，986–1007 行；`renderInventoryTransactions()` 6573–6582 行；`inventoryTransactionSearch()`、`inventoryTransactionReset()` 6584–6599 行 | 从库存管理进入的独立列表页；日期、客户/货主、海外仓、SKU、业务类型及业务/入库/出库单号筛选；约 2050px 横向表格 | 已接真实流水分页，复用库存 `list` 权限；DTO 未提供 SKU/品名时对应筛选禁用、列显示空值，出库事实只读且无跳转 |
+| 进销存记录 | 返回 | `backToInventoryManagement()` 6606–6609 行 | 返回库存管理列表 | 页面工具栏提供明确返回按钮 |
+| 进销存记录 | 导出 | 页面 989 行“导出Excel”按钮 | 工具栏动作，原型未定义导出任务载体 | File 导出类型与海外接口未冻结，本批不显示可成功导出入口 |
+
+`overseas-inbound`、`overseas-relabel` 等原型库存视图用于联查入仓/换标库存事实，不新增重复菜单页；当前正式入库单、换标单、库存列表与详情已经分别承载对应入口。`purchase-stock*` 和 `fba-return-stock` 是否作为独立正式页面尚无本轮导航与接口契约，不在本批自行扩展。
diff --git a/src/modules/overseas-warehouse/api/customerVisits.test.ts b/src/modules/overseas-warehouse/api/customerVisits.test.ts
new file mode 100644
index 00000000..dd45827e
--- /dev/null
+++ b/src/modules/overseas-warehouse/api/customerVisits.test.ts
@@ -0,0 +1,52 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import {
+  getCustomerVisit,
+  listCustomerVisits,
+  saveCustomerVisit,
+  updateDeliveryOrderStatus,
+  uploadCustomerVisitAttachment,
+} from './customerVisits'
+
+vi.mock('@/shared/api/overseasHttp', () => ({ overseasHttp: { get: vi.fn(), post: vi.fn(), put: vi.fn() } }))
+
+describe('customer visit API', () => {
+  beforeEach(() => {
+    vi.mocked(overseasHttp.get).mockReset()
+    vi.mocked(overseasHttp.post).mockReset()
+    vi.mocked(overseasHttp.put).mockReset()
+  })
+
+  it('loads the customer visit page and detail in customer scope', async () => {
+    vi.mocked(overseasHttp.get).mockResolvedValueOnce({ code: '200', data: { records: [], current: 1, size: 10, total: 0, pages: 0, visitable: 3, pending: 2, completed: 1 } })
+    await listCustomerVisits({ page: 1, size: 10, keyword: 'DEL' })
+    expect(overseasHttp.get).toHaveBeenNthCalledWith(1, '/platform/v1/last-leg/customer-visits', { params: { page: 1, size: 10, keyword: 'DEL' } })
+
+    vi.mocked(overseasHttp.get).mockResolvedValueOnce({ code: '200', data: { visit: { id: '9' }, inboundOrders: [] } })
+    await getCustomerVisit('9', '100')
+    expect(overseasHttp.get).toHaveBeenNthCalledWith(2, '/platform/v1/last-leg/customer-visits/9', { params: { customerId: '100' } })
+  })
+
+  it('updates a delivery to an operator-managed nonterminal status', async () => {
+    vi.mocked(overseasHttp.put).mockResolvedValue({ code: '200', data: { deliveryStatus: 'DELIVERING' } })
+    await updateDeliveryOrderStatus('DEL/1', '100', { status: 'DELIVERING', expectedVersion: 7, remark: '开始派送' })
+    expect(overseasHttp.put).toHaveBeenCalledWith('/platform/v1/last-leg/delivery-orders/DEL%2F1/status', { status: 'DELIVERING', expectedVersion: 7, remark: '开始派送' }, { params: { customerId: '100' } })
+  })
+
+  it('uploads and saves repeatable visit material', async () => {
+    const file = new File(['data'], 'visit.pdf', { type: 'application/pdf' })
+    vi.mocked(overseasHttp.post).mockResolvedValue({ code: '200', data: { fileId: '8', fileName: 'visit.pdf', sizeBytes: 4 } })
+    await uploadCustomerVisitAttachment('9', '100', file)
+    const body = vi.mocked(overseasHttp.post).mock.calls[0]?.[1] as FormData
+    expect(body.get('file')).toBe(file)
+    expect(overseasHttp.post).toHaveBeenCalledWith(
+      '/platform/v1/last-leg/customer-visits/9/attachments',
+      body,
+      { params: { customerId: '100' }, headers: { 'Content-Type': 'multipart/form-data' } },
+    )
+
+    vi.mocked(overseasHttp.put).mockResolvedValue({ code: '200', data: { visit: { id: '9' }, inboundOrders: [] } })
+    await saveCustomerVisit('9', '100', { selectedInboundOrderId: '7', visitResult: 'NORMAL', attachments: [] })
+    expect(overseasHttp.put).toHaveBeenCalledWith('/platform/v1/last-leg/customer-visits/9', expect.objectContaining({ selectedInboundOrderId: '7' }), { params: { customerId: '100' } })
+  })
+})
diff --git a/src/modules/overseas-warehouse/api/customerVisits.ts b/src/modules/overseas-warehouse/api/customerVisits.ts
new file mode 100644
index 00000000..df84a332
--- /dev/null
+++ b/src/modules/overseas-warehouse/api/customerVisits.ts
@@ -0,0 +1,108 @@
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+
+export interface CustomerVisitAttachment {
+  fileId: string
+  fileName: string
+  contentType?: string | null
+  sizeBytes: number
+}
+
+export interface CustomerVisitRow {
+  id: string
+  customerId: string
+  deliveryNo: string
+  customerName?: string | null
+  contactName?: string | null
+  contactPhone?: string | null
+  destination?: string | null
+  deliveryCompletedAt: string
+  status: 'PENDING' | 'COMPLETED'
+  selectedInboundCode?: string | null
+  visitResult?: string | null
+  visitedAt?: string | null
+  visitCount: number
+  attachments: CustomerVisitAttachment[]
+}
+
+export interface CustomerVisitPage {
+  records: CustomerVisitRow[]
+  current: number
+  size: number
+  total: number
+  pages: number
+  visitable: number
+  pending: number
+  completed: number
+}
+
+export interface CustomerVisitInboundOption {
+  inboundOrderId: string
+  inboundCode: string
+  lastMileOrderId: string
+  lastMileOrderNo: string
+  destinationWarehouseCode?: string | null
+  destinationWarehouseName?: string | null
+  packageCount: number
+}
+
+export interface CustomerVisitDetail {
+  visit: CustomerVisitRow
+  inboundOrders: CustomerVisitInboundOption[]
+  customerFeedback?: string | null
+  remark?: string | null
+  visitedBy?: string | null
+}
+
+export async function listCustomerVisits(params: {
+  page: number
+  size: number
+  keyword?: string
+  status?: string
+  customerId?: string
+  completedFrom?: string
+  completedTo?: string
+}) {
+  const response = await overseasHttp.get<ApiEnvelope<CustomerVisitPage>, ApiEnvelope<CustomerVisitPage>>(
+    '/platform/v1/last-leg/customer-visits', { params },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function getCustomerVisit(visitId: string, customerId: string) {
+  const response = await overseasHttp.get<ApiEnvelope<CustomerVisitDetail>, ApiEnvelope<CustomerVisitDetail>>(
+    `/platform/v1/last-leg/customer-visits/${encodeURIComponent(visitId)}`, { params: { customerId } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function saveCustomerVisit(visitId: string, customerId: string, payload: {
+  selectedInboundOrderId: string
+  visitResult: string
+  customerFeedback?: string
+  remark?: string
+  attachments: CustomerVisitAttachment[]
+}) {
+  const response = await overseasHttp.put<ApiEnvelope<CustomerVisitDetail>, ApiEnvelope<CustomerVisitDetail>>(
+    `/platform/v1/last-leg/customer-visits/${encodeURIComponent(visitId)}`, payload, { params: { customerId } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function uploadCustomerVisitAttachment(visitId: string, customerId: string, file: File) {
+  const body = new FormData()
+  body.append('file', file)
+  const response = await overseasHttp.post<ApiEnvelope<CustomerVisitAttachment>, ApiEnvelope<CustomerVisitAttachment>>(
+    `/platform/v1/last-leg/customer-visits/${encodeURIComponent(visitId)}/attachments`, body,
+    { params: { customerId }, headers: { 'Content-Type': 'multipart/form-data' } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function updateDeliveryOrderStatus(deliveryNo: string, customerId: string, payload: { status: string; expectedVersion: number; remark?: string }) {
+  const response = await overseasHttp.put<ApiEnvelope<{ visitId?: string | null; deliveryNo: string; deliveryStatus: string; visitStatus?: string | null; replayed: boolean }>, ApiEnvelope<{ visitId?: string | null; deliveryNo: string; deliveryStatus: string; visitStatus?: string | null; replayed: boolean }>>(
+    `/platform/v1/last-leg/delivery-orders/${encodeURIComponent(deliveryNo)}/status`, payload,
+    { params: { customerId } },
+  )
+  return unwrapApiResponse(response)
+}
diff --git a/src/modules/overseas-warehouse/api/deliveryDocuments.test.ts b/src/modules/overseas-warehouse/api/deliveryDocuments.test.ts
new file mode 100644
index 00000000..bc07ffb8
--- /dev/null
+++ b/src/modules/overseas-warehouse/api/deliveryDocuments.test.ts
@@ -0,0 +1,28 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { deliveryDocumentCategories, getDeliveryDocuments, saveDeliveryDocuments, uploadDeliveryDocument, downloadDeliveryDocument } from './deliveryDocuments'
+vi.mock('@/shared/api/overseasHttp', () => ({ overseasHttp: { get: vi.fn(), post: vi.fn(), put: vi.fn() } }))
+describe('delivery document API', () => {
+  beforeEach(() => vi.clearAllMocks())
+  it('scopes reads and full three-category snapshots by customer and delivery number', async () => {
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', data: {} })
+    vi.mocked(overseasHttp.put).mockResolvedValue({ code: '200', data: {} })
+    await getDeliveryDocuments('DL/1', '9007199254740993')
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/delivery-orders/DL%2F1/documents', { params: { customerId: '9007199254740993' } })
+    const body = { expectedVersion: 8, idempotencyKey: 'save-1', bolNo: null, documents: deliveryDocumentCategories.map(item => ({ category: item.category, fileIds: [] })) }
+    await saveDeliveryDocuments('DL/1', '9007199254740993', body)
+    expect(overseasHttp.put).toHaveBeenCalledWith('/platform/v1/last-leg/delivery-orders/DL%2F1/documents', body, { params: { customerId: '9007199254740993' } })
+  })
+  it('uploads only the file and downloads through the authenticated category endpoint', async () => {
+    vi.mocked(overseasHttp.post).mockResolvedValue({ code: '200', data: { fileId: '9007199254740995' } })
+    const file = new File(['data'], 'proof.bin')
+    await uploadDeliveryDocument('DL/1', '100', 'RECEIPT', file)
+    const [url, body, config] = vi.mocked(overseasHttp.post).mock.calls[0]!
+    expect(url).toBe('/platform/v1/last-leg/delivery-orders/DL%2F1/documents/RECEIPT/files')
+    expect(Array.from((body as FormData).keys())).toEqual(['file'])
+    expect((body as FormData).get('file')).toBe(file)
+    expect(config).toEqual({ params: { customerId: '100' } })
+    await downloadDeliveryDocument('DL/1', '100', 'RECEIPT', '9007199254740995')
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/delivery-orders/DL%2F1/documents/RECEIPT/files/9007199254740995/download', { params: { customerId: '100' }, responseType: 'blob' })
+  })
+})
diff --git a/src/modules/overseas-warehouse/api/deliveryDocuments.ts b/src/modules/overseas-warehouse/api/deliveryDocuments.ts
new file mode 100644
index 00000000..13eaf4e0
--- /dev/null
+++ b/src/modules/overseas-warehouse/api/deliveryDocuments.ts
@@ -0,0 +1,33 @@
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+
+export const deliveryDocumentCategories = [
+  { category: 'LOADING_PHOTO', label: '装车照片' },
+  { category: 'BOL', label: 'BOL文件（含签名）' },
+  { category: 'RECEIPT', label: '签收文件（POD签收/快递签收）' },
+] as const
+export type DeliveryDocumentCategory = typeof deliveryDocumentCategories[number]['category']
+export interface DeliveryDocumentFile { fileId: string; fileName: string; contentType: string | null; sizeBytes: number; uploadedAt: string }
+export interface DeliveryDocumentCategorySummary { category: DeliveryDocumentCategory; status: 'UPLOADED' | 'MISSING'; fileCount: number }
+export interface DeliveryDocumentSummary { uploadedCategoryCount: number; totalCategoryCount: number; categories: DeliveryDocumentCategorySummary[] }
+export interface DeliveryDocuments extends DeliveryDocumentSummary {
+  deliveryNo: string; customerId: string; version: number; bolNo: string | null
+  categories: Array<DeliveryDocumentCategorySummary & { files: DeliveryDocumentFile[] }>
+  allowedActions: string[]; replayed: boolean
+}
+export interface SaveDeliveryDocuments { expectedVersion: number; idempotencyKey: string; bolNo: string | null; documents: Array<{ category: DeliveryDocumentCategory; fileIds: string[] }> }
+const path = (deliveryNo: string) => `/platform/v1/last-leg/delivery-orders/${encodeURIComponent(deliveryNo)}/documents`
+export async function getDeliveryDocuments(deliveryNo: string, customerId: string) {
+  return unwrapApiResponse(await overseasHttp.get<ApiEnvelope<DeliveryDocuments>, ApiEnvelope<DeliveryDocuments>>(path(deliveryNo), { params: { customerId } }))
+}
+export async function saveDeliveryDocuments(deliveryNo: string, customerId: string, body: SaveDeliveryDocuments) {
+  return unwrapApiResponse(await overseasHttp.put<ApiEnvelope<DeliveryDocuments>, ApiEnvelope<DeliveryDocuments>>(path(deliveryNo), body, { params: { customerId } }))
+}
+export async function uploadDeliveryDocument(deliveryNo: string, customerId: string, category: DeliveryDocumentCategory, file: File) {
+  const body = new FormData()
+  body.append('file', file)
+  return unwrapApiResponse(await overseasHttp.post<ApiEnvelope<DeliveryDocumentFile>, ApiEnvelope<DeliveryDocumentFile>>(`${path(deliveryNo)}/${category}/files`, body, { params: { customerId } }))
+}
+export async function downloadDeliveryDocument(deliveryNo: string, customerId: string, category: DeliveryDocumentCategory, fileId: string) {
+  return overseasHttp.get<Blob, Blob>(`${path(deliveryNo)}/${category}/files/${encodeURIComponent(fileId)}/download`, { params: { customerId }, responseType: 'blob' })
+}
diff --git a/src/modules/overseas-warehouse/api/deliveryOrders.test.ts b/src/modules/overseas-warehouse/api/deliveryOrders.test.ts
new file mode 100644
index 00000000..2aa59f70
--- /dev/null
+++ b/src/modules/overseas-warehouse/api/deliveryOrders.test.ts
@@ -0,0 +1,48 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { getDeliveryOrder, listDeliveryOrders, listDeliveryReturnInboundOptions, markDeliveryReturn } from './deliveryOrders'
+
+vi.mock('@/shared/api/overseasHttp', () => ({ overseasHttp: { get: vi.fn(), post: vi.fn() } }))
+
+describe('delivery order API', () => {
+  beforeEach(() => {
+    vi.mocked(overseasHttp.get).mockReset()
+    vi.mocked(overseasHttp.post).mockReset()
+  })
+
+  it('passes paging and expanded filters and normalizes page numbers', async () => {
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', data: { records: [], page: '2', size: '20', total: '41', pages: '3' } })
+    const result = await listDeliveryOrders({ page: 2, size: 20, documentNo: 'DEL-1', vehiclePlate: 'CA-1' })
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/delivery-orders', { params: { page: 2, size: 20, documentNo: 'DEL-1', vehiclePlate: 'CA-1' } })
+    expect(result).toMatchObject({ page: 2, size: 20, total: 41, pages: 3 })
+  })
+
+  it('loads an encoded detail in its explicit customer scope', async () => {
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', data: { order: { deliveryNo: 'DEL/1', version: '0' }, skus: [], fees: [], operations: [] } })
+    await getDeliveryOrder('DEL/1', '1001')
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/delivery-orders/DEL%2F1', { params: { customerId: '1001', page: 1, size: 200 } })
+  })
+
+  it.each(['0', '7', '9007199254740991'])('reads Java Long version %s for status editing', async version => {
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', data: { order: { version, id: '2097515131537313794' } } })
+    const detail = await getDeliveryOrder('DEL/1', '1001')
+    expect(detail.order.version).toBe(Number(version))
+    expect(detail.order.id).toBe('2097515131537313794')
+  })
+
+  it.each([null, undefined, '', ' ', '-1', '1.5', '9007199254740992', -1])('rejects invalid version %s', async version => {
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', data: { order: { version } } })
+    await expect(getDeliveryOrder('DEL/1', '1001')).rejects.toThrow('派送单缺少有效版本')
+  })
+
+  it('loads return options and marks a return in the explicit customer scope', async () => {
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', data: [{ inboundOrderId: '9', inboundCode: 'IN-1' }] })
+    await listDeliveryReturnInboundOptions('DEL/1', '1001')
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/delivery-orders/DEL%2F1/return-inbound-options', { params: { customerId: '1001' } })
+
+    const payload = { inboundOrderId: '9', reason: '客户拒收', returnDirection: 'OVERSEAS_WAREHOUSE' as const, items: [{ outboundPalletItemId: '9007199254740995', inventoryPositionId: '9007199254740996', packageCount: 2 }], idempotencyKey: 'return-1' }
+    vi.mocked(overseasHttp.post).mockResolvedValue({ code: '200', data: { id: '19', exceptionNo: 'EXC-1', status: 'PENDING' } })
+    await markDeliveryReturn('DEL/1', '1001', payload)
+    expect(overseasHttp.post).toHaveBeenCalledWith('/platform/v1/last-leg/delivery-orders/DEL%2F1/mark-return', payload, { params: { customerId: '1001' } })
+  })
+})
diff --git a/src/modules/overseas-warehouse/api/deliveryOrders.ts b/src/modules/overseas-warehouse/api/deliveryOrders.ts
new file mode 100644
index 00000000..02a8eaa5
--- /dev/null
+++ b/src/modules/overseas-warehouse/api/deliveryOrders.ts
@@ -0,0 +1,126 @@
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import { normalizeOverseasPage, type OverseasPagePayload } from './lastMileOrders'
+import type { DeliveryDocumentSummary } from './deliveryDocuments'
+
+export interface DeliveryOrderQuery {
+  page: number
+  size: number
+  customerId?: string
+  documentNo?: string
+  dispatchNo?: string
+  waybillNo?: string
+  warehouseId?: string
+  status?: string
+  vehiclePlate?: string
+  driverName?: string
+  deliveryMethod?: string
+  plannedFrom?: string
+  plannedTo?: string
+}
+
+export interface DeliveryOrderRow {
+  version: number
+  allowedActions: string[]
+  bolNo?: string | null
+  documentSummary?: DeliveryDocumentSummary
+  id: string
+  customerId: string
+  customerName?: string | null
+  deliveryNo: string
+  outboundNo: string
+  dispatchNo: string
+  destinationWarehouseId?: string | null
+  destinationWarehouseCode?: string | null
+  destinationWarehouseName?: string | null
+  overseasWarehouseId?: string | null
+  overseasWarehouseName?: string | null
+  status: string
+  waybillNo?: string | null
+  deliveryMethod?: string | null
+  carrierName?: string | null
+  pickupMethod?: string | null
+  loadingType?: string | null
+  vehicleType?: string | null
+  vehicleSize?: string | null
+  vehiclePlate?: string | null
+  driverName?: string | null
+  driverPhone?: string | null
+  appointmentAccount?: string | null
+  sellerName?: string | null
+  palletCount: number
+  packageCount: number
+  totalWeightKg?: number | null
+  totalVolumeCbm?: number | null
+  plannedDeliveryAt?: string | null
+  dispatchedAt?: string | null
+  expectedArrivalAt?: string | null
+  signedAt?: string | null
+  remark?: string | null
+  createdAt: string
+}
+
+export interface DeliverySkuRow { inboundCode?: string | null; customerName?: string | null; destinationWarehouseCode?: string | null; receivingAddress?: string | null; shipmentNo?: string | null; fbaTrackingNo?: string | null; skuCode?: string | null; productName?: string | null; packageCount: number; weightKg?: number | null; volumeCbm?: number | null }
+export interface DeliveryFeeRow { id: string; feeDirection: string; feeType: string; currency: string; amount: number; remark?: string | null }
+export interface DeliveryOperationRow { id: string; operatedAt: string; operationNode: string; operatorName?: string | null; result: string }
+export interface DeliveryOrderDetail { order: DeliveryOrderRow; skus: DeliverySkuRow[]; fees: DeliveryFeeRow[]; operations: DeliveryOperationRow[] }
+
+export interface DeliveryReturnSource {
+  outboundPalletItemId: string
+  inventoryPositionId: string
+  palletNo?: string | null
+  skuCode?: string | null
+  maxReturnPackages: number
+}
+export interface DeliveryReturnRelation {
+  inboundOrderId: string
+  inboundCode?: string | null
+  lastMileOrderNo?: string | null
+  customerId: string
+  returnSources: DeliveryReturnSource[]
+}
+export interface MarkDeliveryReturnPayload {
+  inboundOrderId: string
+  reason: string
+  returnDirection: 'OVERSEAS_WAREHOUSE' | 'CUSTOMER' | 'OTHER'
+  returnLogisticsNo?: string
+  items: Array<{ outboundPalletItemId: string; inventoryPositionId: string; packageCount: number }>
+  idempotencyKey: string
+}
+
+export async function listDeliveryOrders(query: DeliveryOrderQuery) {
+  const { customerId, ...params } = query
+  const response = await overseasHttp.get<ApiEnvelope<OverseasPagePayload<DeliveryOrderRow>>, ApiEnvelope<OverseasPagePayload<DeliveryOrderRow>>>(
+    '/platform/v1/last-leg/delivery-orders', { params: { ...params, ...(customerId ? { customerId } : {}) } },
+  )
+  return normalizeOverseasPage(unwrapApiResponse(response))
+}
+
+export async function getDeliveryOrder(deliveryNo: string, customerId: string) {
+  const response = await overseasHttp.get<ApiEnvelope<DeliveryOrderDetail>, ApiEnvelope<DeliveryOrderDetail>>(
+    `/platform/v1/last-leg/delivery-orders/${encodeURIComponent(deliveryNo)}`, { params: { customerId, page: 1, size: 200 } },
+  )
+  const detail = unwrapApiResponse(response)
+  // Java Long values are serialized as decimal strings, including the version.
+  const rawVersion: unknown = detail.order.version
+  const version = typeof rawVersion === 'string' && /^(0|[1-9]\d*)$/.test(rawVersion)
+    ? Number(rawVersion) : rawVersion
+  if (typeof version !== 'number' || !Number.isSafeInteger(version) || version < 0) {
+    throw new Error('派送单缺少有效版本，请刷新后重试')
+  }
+  return { ...detail, order: { ...detail.order, version } }
+}
+
+export async function listDeliveryReturnInboundOptions(deliveryNo: string, customerId: string) {
+  const response = await overseasHttp.get<ApiEnvelope<DeliveryReturnRelation[]>, ApiEnvelope<DeliveryReturnRelation[]>>(
+    `/platform/v1/last-leg/delivery-orders/${encodeURIComponent(deliveryNo)}/return-inbound-options`, { params: { customerId } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function markDeliveryReturn(deliveryNo: string, customerId: string, payload: MarkDeliveryReturnPayload) {
+  const response = await overseasHttp.post<ApiEnvelope<{ id: string; exceptionNo: string; status: string }>, ApiEnvelope<{ id: string; exceptionNo: string; status: string }>>(
+    `/platform/v1/last-leg/delivery-orders/${encodeURIComponent(deliveryNo)}/mark-return`, payload, { params: { customerId } },
+  )
+  return unwrapApiResponse(response)
+}
diff --git a/src/modules/overseas-warehouse/api/dispatches.test.ts b/src/modules/overseas-warehouse/api/dispatches.test.ts
new file mode 100644
index 00000000..4468258d
--- /dev/null
+++ b/src/modules/overseas-warehouse/api/dispatches.test.ts
@@ -0,0 +1,108 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { cancelDispatch, createDispatchDraftContainer, deleteDispatchDraftContainer, getDispatch, getDispatchBolPdf, listDispatchCandidates, listDispatchDrafts, listDispatches, lockDispatchDraftPallet, preArrangeDispatch, releaseDispatchDraft, transferDispatchToDelivery, unlockDispatchDraftPallet, updateDispatch } from './dispatches'
+
+vi.mock('@/shared/api/overseasHttp', () => ({ overseasHttp: { get: vi.fn(), post: vi.fn(), put: vi.fn(), delete: vi.fn() } }))
+
+describe('dispatch overseas API', () => {
+  beforeEach(() => {
+    vi.mocked(overseasHttp.get).mockReset()
+    vi.mocked(overseasHttp.post).mockReset()
+    vi.mocked(overseasHttp.put).mockReset()
+    vi.mocked(overseasHttp.delete).mockReset()
+  })
+
+  it('uses the platform dispatch page without customer scope', async () => {
+    vi.mocked(overseasHttp.get).mockResolvedValue({
+      code: '200', message: 'success', data: { records: [], page: 2, size: 50, total: 0, pages: 0 },
+    })
+
+    await listDispatches({
+      page: 2, size: 50, dispatchNo: 'PC-1',
+      vehiclePlate: 'CA-100', status: 'PENDING_DEPARTURE', fbaAppointmentNo: 'FBA-1',
+    })
+
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/dispatches', {
+      params: {
+        page: 2, size: 50, dispatchNo: 'PC-1',
+        vehiclePlate: 'CA-100', status: 'PENDING_DEPARTURE', fbaAppointmentNo: 'FBA-1',
+      },
+    })
+  })
+
+  it('loads a platform dispatch detail by encoded dispatch number', async () => {
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', message: 'success', data: { id: '1', dispatchNo: 'PC/1' } })
+
+    await getDispatch('PC/1')
+
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/dispatches/PC%2F1')
+  })
+
+  it('requests the generated BOL as a PDF blob', async () => {
+    vi.mocked(overseasHttp.get).mockResolvedValue(new Blob(['%PDF-test']))
+    await getDispatchBolPdf('PC/1')
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/dispatches/PC%2F1/prints/bol', { responseType: 'blob' })
+  })
+
+  it('loads candidates and creates a pre-arrange dispatch in an explicit customer scope', async () => {
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', message: 'success', data: [] })
+    vi.mocked(overseasHttp.post).mockResolvedValue({ code: '200', message: 'success', data: { id: '1', dispatchNo: 'PC-1' } })
+    await listDispatchCandidates({ planIds: '101,102', fbaWarehouseCode: 'ONT8', sourceStage: 'PLAN' })
+    await preArrangeDispatch({ planPalletIds: ['190000000000000099'] })
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/dispatches/candidates', { params: { planIds: '101,102', fbaWarehouseCode: 'ONT8', sourceStage: 'PLAN' } })
+    expect(overseasHttp.post).toHaveBeenCalledWith('/platform/v1/last-leg/dispatches/pre-arrange', { planPalletIds: ['190000000000000099'] })
+  })
+
+  it('loads platform candidates without selected inbound plans', async () => {
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', message: 'success', data: [] })
+
+    await listDispatchCandidates({ sourceStage: 'RECEIVED' })
+
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/dispatches/candidates', {
+      params: { sourceStage: 'RECEIVED' },
+    })
+  })
+
+  it('locks, unlocks, and releases intelligent dispatch drafts through dedicated endpoints', async () => {
+    vi.mocked(overseasHttp.post).mockResolvedValue({ code: '200', message: 'success', data: null })
+
+    await lockDispatchDraftPallet('99', 'draft-1')
+    await unlockDispatchDraftPallet('99', 'draft-1')
+    await releaseDispatchDraft('draft-1')
+
+    expect(overseasHttp.post).toHaveBeenNthCalledWith(1, '/platform/v1/last-leg/dispatches/draft-locks/lock', { planPalletId: '99', draftToken: 'draft-1' })
+    expect(overseasHttp.post).toHaveBeenNthCalledWith(2, '/platform/v1/last-leg/dispatches/draft-locks/unlock', { planPalletId: '99', draftToken: 'draft-1' })
+    expect(overseasHttp.post).toHaveBeenNthCalledWith(3, '/platform/v1/last-leg/dispatches/draft-locks/release', { draftToken: 'draft-1' })
+  })
+
+  it('edits and cancels only by dispatchNo without customer scope or status mutation', async () => {
+    vi.mocked(overseasHttp.put).mockResolvedValue({ code: '200', message: 'success', data: { id: '1', dispatchNo: 'PC/1' } })
+    vi.mocked(overseasHttp.delete).mockResolvedValue({ code: '200', message: 'success', data: null })
+    await updateDispatch('PC/1', { vehiclePlate: 'CA-100' })
+    await cancelDispatch('PC/1')
+    expect(overseasHttp.put).toHaveBeenCalledWith('/platform/v1/last-leg/dispatches/PC%2F1', { vehiclePlate: 'CA-100' })
+    expect(overseasHttp.put).not.toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ status: expect.anything() }))
+    expect(overseasHttp.delete).toHaveBeenCalledWith('/platform/v1/last-leg/dispatches/PC%2F1')
+  })
+
+  it('transfers to delivery only by dispatchNo without customerId', async () => {
+    vi.mocked(overseasHttp.post).mockResolvedValue({ code: '200', message: 'success', data: { dispatchNo: 'PC/1', outboundNo: 'OUT-1', outboundStatus: 'PICKED', palletCount: 2, packageCount: 20, deliveries: [{ deliveryNo: 'DEL-1', deliveryStatus: 'WAIT_DELIVERY', destinationWarehouseCode: 'ACY2', palletCount: 2, packageCount: 20 }], replayed: false } })
+    const payload = { idempotencyKey: 'transfer-1', plannedDeliveryAt: '2026-09-01T10:00:00', deliveryMethod: 'TRUCK_PALLET', pickupMethod: 'WAREHOUSE_PICKUP', loadingType: 'PALLET', fees: [{ feeType: 'DELIVERY_FEE', feeName: '派送费用', direction: 'RECEIVABLE' as const, currency: 'USD' as const, amount: 10 }] }
+    await transferDispatchToDelivery('PC/1', payload)
+    expect(overseasHttp.post).toHaveBeenCalledWith('/platform/v1/last-leg/dispatches/PC%2F1/transfer-delivery', payload)
+  })
+
+  it('loads drafts and preserves long container ids in create and delete paths', async () => {
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', message: 'success', data: [] })
+    vi.mocked(overseasHttp.post).mockResolvedValue({ code: '200', message: 'success', data: { id: '190000000000000099', capacity: 30, palletIds: [] } })
+    vi.mocked(overseasHttp.delete).mockResolvedValue({ code: '200', message: 'success', data: null })
+
+    await listDispatchDrafts()
+    await createDispatchDraftContainer('draft/1', 30)
+    await deleteDispatchDraftContainer('draft/1', '190000000000000099')
+
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/dispatches/drafts')
+    expect(overseasHttp.post).toHaveBeenCalledWith('/platform/v1/last-leg/dispatches/drafts/containers', { draftToken: 'draft/1', capacity: 30 })
+    expect(overseasHttp.delete).toHaveBeenCalledWith('/platform/v1/last-leg/dispatches/drafts/draft%2F1/containers/190000000000000099')
+  })
+})
diff --git a/src/modules/overseas-warehouse/api/dispatches.ts b/src/modules/overseas-warehouse/api/dispatches.ts
new file mode 100644
index 00000000..b5df3545
--- /dev/null
+++ b/src/modules/overseas-warehouse/api/dispatches.ts
@@ -0,0 +1,255 @@
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import { normalizeOverseasPage, type OverseasPagePayload } from './lastMileOrders'
+
+export interface DispatchQuery {
+  page: number
+  size: number
+  dispatchNo?: string
+  vehiclePlate?: string
+  status?: string
+  fbaAppointmentNo?: string
+}
+
+export interface DispatchPalletCandidateDto {
+  planId?: string | null
+  planPalletId?: string | null
+  warehousePalletId?: string | null
+  orderId: string
+  customerId?: string | null
+  customerName?: string | null
+  planNo?: string | null
+  orderType?: string | null
+  volumeWeightKg?: number | null
+  containerNo?: string | null
+  appointmentAt?: string | null
+  expectedLoadingAt?: string | null
+  overseasWarehouseId?: string | null
+  overseasWarehouseName?: string | null
+  orderNo?: string | null
+  orderRefs?: string | null
+  inboundCode?: string | null
+  palletNo?: string | null
+  destinationWarehouseId?: string | null
+  destinationWarehouseCode?: string | null
+  destinationWarehouseName?: string | null
+  fbaWarehouseCode?: string | null
+  packageCount?: number | null
+  volumeCbm?: number | null
+  sourceStage?: 'PLAN' | 'RECEIVED' | 'RELABEL' | null
+  cartonMarks?: string | null
+  relabelCartonMarks?: string | null
+}
+
+export interface DispatchCandidateQuery {
+  planIds?: string
+  orderNo?: string
+  fbaWarehouseCode?: string
+  sourceStage?: 'PLAN' | 'RECEIVED'
+  draftToken?: string
+}
+export interface DispatchDraftContainerDto { id: string; capacity: number; palletIds: string[] }
+export interface DispatchDraftDto { draftToken: string; containers?: DispatchDraftContainerDto[] }
+
+export interface PreArrangeDispatchPayload {
+  planPalletIds: string[]
+  fbaAppointmentNo?: string
+  fbaAppointmentStatus?: string
+  vehicleAppointmentStatus?: string
+  draftToken?: string
+  relabelNo?: string
+}
+
+export interface DispatchSummaryDto {
+  id: string
+  dispatchNo: string
+  vehiclePlate?: string | null
+  driverName?: string | null
+  driverPhone?: string | null
+  carrierName?: string | null
+  orderNos?: string | null
+  route?: string | null
+  overseasWarehouseId?: string | null
+  overseasWarehouseName?: string | null
+  departAt?: string | null
+  fbaAppointmentNo?: string | null
+  fbaAppointmentStatus?: string | null
+  vehicleAppointmentStatus?: string | null
+  estimatedArrivalAt?: string | null
+  status?: string | null
+  itemCount?: number | null
+  palletCount?: number | null
+  packageCount?: number | null
+  pickedPackageCount?: number | null
+  shippedPackageCount?: number | null
+  remainingPackageCount?: number | null
+  partialCompletionReason?: string | null
+  createdAt?: string | null
+  items?: DispatchItemDto[]
+  bolLines?: DispatchBolLineDto[]
+}
+
+export interface DispatchBolLineDto {
+  containerNo?: string | null
+  palletNo?: string | null
+  fbaWarehouseCode?: string | null
+  destinationWarehouseName?: string | null
+  warehouseNo?: string | null
+  fbaShipmentId?: string | null
+  poReferenceNo?: string | null
+  packageCount: number
+}
+
+export interface UpdateDispatchPayload {
+  vehiclePlate?: string | null
+  driverName?: string | null
+  driverPhone?: string | null
+  carrierName?: string | null
+  departAt?: string | null
+  fbaAppointmentNo?: string | null
+  fbaAppointmentStatus?: string | null
+  vehicleAppointmentStatus?: string | null
+  estimatedArrivalAt?: string | null
+}
+
+export interface DispatchItemDto {
+  id: string
+  planPalletId: string
+  warehousePalletId?: string | null
+  palletNo?: string | null
+  overseasWarehouseId?: string | null
+  overseasWarehouseName?: string | null
+  orderNo?: string | null
+  orderRefs?: string | null
+  inboundCode?: string | null
+  destinationWarehouseCode?: string | null
+  destinationWarehouseName?: string | null
+  fbaWarehouseCode?: string | null
+  packageCount?: number | null
+  volumeCbm?: number | null
+  sourceStage?: string | null
+}
+
+export async function listDispatches(query: DispatchQuery) {
+  const response = await overseasHttp.get<ApiEnvelope<OverseasPagePayload<DispatchSummaryDto>>, ApiEnvelope<OverseasPagePayload<DispatchSummaryDto>>>(
+    '/platform/v1/last-leg/dispatches',
+    { params: query },
+  )
+  return normalizeOverseasPage(unwrapApiResponse(response))
+}
+
+export async function getDispatch(dispatchNo: string) {
+  const response = await overseasHttp.get<ApiEnvelope<DispatchSummaryDto>, ApiEnvelope<DispatchSummaryDto>>(
+    `/platform/v1/last-leg/dispatches/${encodeURIComponent(dispatchNo)}`,
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function getDispatchBolPdf(dispatchNo: string) {
+  return overseasHttp.get<Blob, Blob>(
+    `/platform/v1/last-leg/dispatches/${encodeURIComponent(dispatchNo)}/prints/bol`,
+    { responseType: 'blob' },
+  )
+}
+
+export async function updateDispatch(dispatchNo: string, payload: UpdateDispatchPayload) {
+  const response = await overseasHttp.put<ApiEnvelope<DispatchSummaryDto>, ApiEnvelope<DispatchSummaryDto>>(
+    `/platform/v1/last-leg/dispatches/${encodeURIComponent(dispatchNo)}`, payload,
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function cancelDispatch(dispatchNo: string) {
+  const response = await overseasHttp.delete<ApiEnvelope<null>, ApiEnvelope<null>>(
+    `/platform/v1/last-leg/dispatches/${encodeURIComponent(dispatchNo)}`,
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function removeDispatchItem(dispatchNo: string, itemId: string) {
+  const response = await overseasHttp.delete<ApiEnvelope<DispatchSummaryDto>, ApiEnvelope<DispatchSummaryDto>>(
+    `/platform/v1/last-leg/dispatches/${encodeURIComponent(dispatchNo)}/items/${encodeURIComponent(itemId)}`,
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function listDispatchCandidates(query: DispatchCandidateQuery) {
+  const response = await overseasHttp.get<ApiEnvelope<DispatchPalletCandidateDto[]>, ApiEnvelope<DispatchPalletCandidateDto[]>>(
+    '/platform/v1/last-leg/dispatches/candidates',
+    { params: query },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function preArrangeDispatch(payload: PreArrangeDispatchPayload) {
+  const response = await overseasHttp.post<ApiEnvelope<DispatchSummaryDto>, ApiEnvelope<DispatchSummaryDto>>(
+    '/platform/v1/last-leg/dispatches/pre-arrange',
+    payload,
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function lockDispatchDraftPallet(planPalletId: string, draftToken: string, draftContainerId?: string) {
+  const response = await overseasHttp.post<ApiEnvelope<null>, ApiEnvelope<null>>(
+    '/platform/v1/last-leg/dispatches/draft-locks/lock', { planPalletId, draftToken, ...(draftContainerId ? { draftContainerId } : {}) },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function listDispatchDrafts() {
+  const response = await overseasHttp.get<ApiEnvelope<DispatchDraftDto[]>, ApiEnvelope<DispatchDraftDto[]>>('/platform/v1/last-leg/dispatches/drafts')
+  return unwrapApiResponse(response)
+}
+export async function createDispatchDraftContainer(draftToken: string, capacity: number) {
+  const response = await overseasHttp.post<ApiEnvelope<DispatchDraftContainerDto>, ApiEnvelope<DispatchDraftContainerDto>>('/platform/v1/last-leg/dispatches/drafts/containers', { draftToken, capacity })
+  return unwrapApiResponse(response)
+}
+export async function deleteDispatchDraftContainer(draftToken: string, containerId: string) {
+  const response = await overseasHttp.delete<ApiEnvelope<null>, ApiEnvelope<null>>(`/platform/v1/last-leg/dispatches/drafts/${encodeURIComponent(draftToken)}/containers/${encodeURIComponent(containerId)}`)
+  return unwrapApiResponse(response)
+}
+
+export async function unlockDispatchDraftPallet(planPalletId: string, draftToken: string) {
+  const response = await overseasHttp.post<ApiEnvelope<null>, ApiEnvelope<null>>(
+    '/platform/v1/last-leg/dispatches/draft-locks/unlock', { planPalletId, draftToken },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function releaseDispatchDraft(draftToken: string) {
+  const response = await overseasHttp.post<ApiEnvelope<null>, ApiEnvelope<null>>(
+    '/platform/v1/last-leg/dispatches/draft-locks/release', { draftToken },
+  )
+  return unwrapApiResponse(response)
+}
+
+export interface TransferDeliveryItem { deliveryNo: string; deliveryStatus: string; destinationWarehouseId?: string | null; destinationWarehouseCode?: string | null; destinationWarehouseName?: string | null; palletCount: number; packageCount: number }
+export interface TransferDeliveryResult { dispatchNo: string; outboundNo: string; outboundStatus: string; palletCount: number; packageCount: number; deliveries: TransferDeliveryItem[]; replayed: boolean }
+export interface TransferDeliveryPayload {
+  idempotencyKey: string
+  plannedDeliveryAt: string
+  deliveryMethod: string
+  waybillNo?: string
+  carrierName?: string
+  pickupMethod: string
+  loadingType: string
+  vehicleType?: string
+  vehicleSize?: string
+  driverName?: string
+  driverPhone?: string
+  vehiclePlate?: string
+  appointmentAccount?: string
+  sellerName?: string
+  remark?: string
+  fees: Array<{ feeType: string; feeName: string; direction: 'RECEIVABLE' | 'PAYABLE'; currency: 'CNY' | 'USD'; amount: number
+    supplierId?: string; supplierName?: string; supplierCategory?: string; settlementMode?: 'ON_ACCOUNT' | 'DIRECT_PAID'
+    paidAt?: string; paymentMethod?: 'ONLINE' | 'BANK_TRANSFER' | 'CASH' | 'OTHER'; paymentReferenceNo?: string
+    paymentVoucherFileIds?: string[]; chargeableQuantity?: number; quantityUnit?: string; unitPrice?: number
+    periodStart?: string; periodEnd?: string; remark?: string }>
+}
+export async function transferDispatchToDelivery(dispatchNo: string, payload: TransferDeliveryPayload) {
+  const response = await overseasHttp.post<ApiEnvelope<TransferDeliveryResult>, ApiEnvelope<TransferDeliveryResult>>(
+    `/platform/v1/last-leg/dispatches/${encodeURIComponent(dispatchNo)}/transfer-delivery`, payload,
+  )
+  return unwrapApiResponse(response)
+}
diff --git a/src/modules/overseas-warehouse/api/exceptionOrders.test.ts b/src/modules/overseas-warehouse/api/exceptionOrders.test.ts
new file mode 100644
index 00000000..c56716e5
--- /dev/null
+++ b/src/modules/overseas-warehouse/api/exceptionOrders.test.ts
@@ -0,0 +1,26 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { createExceptionOrder, listExceptionOrders, resolveExceptionRelation } from './exceptionOrders'
+
+vi.mock('@/shared/api/overseasHttp', () => ({ overseasHttp: { get: vi.fn(), post: vi.fn() } }))
+
+describe('exception order API', () => {
+  beforeEach(() => { vi.mocked(overseasHttp.get).mockReset(); vi.mocked(overseasHttp.post).mockReset() })
+
+  it('queries the real paginated exception endpoint', async () => {
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', data: { records: [], page: '1', size: '20', total: '2', pages: '1' } })
+    const result = await listExceptionOrders({ page: 1, size: 20, keyword: 'EXC' })
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/exception-orders', { params: { page: 1, size: 20, keyword: 'EXC' } })
+    expect(result.total).toBe(2)
+  })
+
+  it('resolves relation before creating an exception document', async () => {
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', data: { inboundOrderId: '11', inboundCode: 'IN-1', lastMileOrderId: '12', lastMileOrderNo: 'LM-1', customerId: '1' } })
+    await resolveExceptionRelation({ inboundCode: 'IN-1', lastMileOrderNo: 'LM-1' })
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/exception-orders/resolve', { params: { inboundCode: 'IN-1', lastMileOrderNo: 'LM-1' } })
+
+    vi.mocked(overseasHttp.post).mockResolvedValue({ code: '200', data: { id: '99', exceptionNo: 'EXC-1', status: 'PENDING' } })
+    await createExceptionOrder({ inboundCode: 'IN-1', lastMileOrderNo: 'LM-1', exceptionType: 'RETURN', reason: '拒收' })
+    expect(overseasHttp.post).toHaveBeenCalledWith('/platform/v1/last-leg/exception-orders', expect.objectContaining({ inboundCode: 'IN-1', lastMileOrderNo: 'LM-1' }))
+  })
+})
diff --git a/src/modules/overseas-warehouse/api/exceptionOrders.ts b/src/modules/overseas-warehouse/api/exceptionOrders.ts
new file mode 100644
index 00000000..241c8f9a
--- /dev/null
+++ b/src/modules/overseas-warehouse/api/exceptionOrders.ts
@@ -0,0 +1,32 @@
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import { normalizeOverseasPage, type OverseasPagePayload } from './lastMileOrders'
+
+export interface ExceptionOrderQuery { page: number; size: number; keyword?: string; exceptionType?: string; status?: string; customerId?: string; warehouseId?: string; createdFrom?: string; createdTo?: string }
+export interface ExceptionOrderRow {
+  id: string; exceptionNo: string; exceptionType: string; status: string; reason: string
+  customerId: string; customerName?: string | null; overseasWarehouseId?: string | null; overseasWarehouseName?: string | null
+  lastMileOrderId?: string | null; lastMileOrderNo?: string | null; inboundOrderId?: string | null; inboundCode?: string | null
+  deliveryOrderId?: string | null; deliveryNo?: string | null; outboundNo?: string | null
+  skuCode?: string | null; packageCount?: number | null; returnDirection?: string | null; returnLogisticsNo?: string | null
+  handlingAction?: string | null; handlerName?: string | null; exceptionAt: string; updatedAt: string
+}
+export interface ExceptionRelation {
+  lastMileOrderId?: string | null; lastMileOrderNo?: string | null; inboundOrderId?: string | null; inboundCode?: string | null
+  customerId: string; customerName?: string | null; overseasWarehouseId?: string | null; overseasWarehouseName?: string | null
+  deliveryNo?: string | null; outboundNo?: string | null; availablePackages?: number | null
+}
+export interface CreateExceptionOrderPayload { customerId?: string; inboundCode?: string; lastMileOrderNo?: string; exceptionType: string; reason: string; packageCount?: number; skuCode?: string }
+
+export async function listExceptionOrders(query: ExceptionOrderQuery) {
+  const response = await overseasHttp.get<ApiEnvelope<OverseasPagePayload<ExceptionOrderRow>>, ApiEnvelope<OverseasPagePayload<ExceptionOrderRow>>>('/platform/v1/last-leg/exception-orders', { params: query })
+  return normalizeOverseasPage(unwrapApiResponse(response))
+}
+export async function resolveExceptionRelation(params: { customerId?: string; inboundCode?: string; lastMileOrderNo?: string }) {
+  const response = await overseasHttp.get<ApiEnvelope<ExceptionRelation>, ApiEnvelope<ExceptionRelation>>('/platform/v1/last-leg/exception-orders/resolve', { params })
+  return unwrapApiResponse(response)
+}
+export async function createExceptionOrder(payload: CreateExceptionOrderPayload) {
+  const response = await overseasHttp.post<ApiEnvelope<{ id: string; exceptionNo: string; status: string }>, ApiEnvelope<{ id: string; exceptionNo: string; status: string }>>('/platform/v1/last-leg/exception-orders', payload)
+  return unwrapApiResponse(response)
+}
diff --git a/src/modules/overseas-warehouse/api/inboundOrders.test.ts b/src/modules/overseas-warehouse/api/inboundOrders.test.ts
new file mode 100644
index 00000000..443982d0
--- /dev/null
+++ b/src/modules/overseas-warehouse/api/inboundOrders.test.ts
@@ -0,0 +1,47 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { createFbaAppointment, getFbaAppointment, listInboundOrders, updateFbaAppointment } from './inboundOrders'
+
+vi.mock('@/shared/api/overseasHttp', () => ({ overseasHttp: { get: vi.fn(), post: vi.fn(), put: vi.fn() } }))
+
+describe('inbound order overseas API', () => {
+  beforeEach(() => {
+    vi.mocked(overseasHttp.get).mockReset()
+    vi.mocked(overseasHttp.post).mockReset()
+    vi.mocked(overseasHttp.put).mockReset()
+  })
+
+  it('loads appointment details and updates the existing appointment without replacing its lines', async () => {
+    const detail = { id: '1', customerId: '190000000000000001', appointmentNo: 'APT/1', appointmentAt: '2026-08-20T10:30:00', expectedLoadingAt: '2026-08-20T09:00:00', appointmentStatus: 'SUCCESS', selectedCount: 2, fbaWarehouseCode: 'ONT8', items: [] }
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', message: 'success', data: detail })
+    vi.mocked(overseasHttp.put).mockResolvedValue({ code: '200', message: 'success', data: detail })
+
+    await getFbaAppointment('190000000000000001', 'APT/1')
+    await updateFbaAppointment('APT/1', { customerId: '190000000000000001', appointmentAt: detail.appointmentAt, expectedLoadingAt: detail.expectedLoadingAt, appointmentStatus: 'SUCCESS' })
+
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/inbound-plans/fba-appointments/APT%2F1', { params: { customerId: '190000000000000001' } })
+    expect(overseasHttp.put).toHaveBeenCalledWith('/platform/v1/last-leg/inbound-plans/fba-appointments/APT%2F1', expect.objectContaining({ customerId: '190000000000000001' }))
+  })
+
+  it('loads the paginated list across all customers without a customer scope', async () => {
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', message: 'success', data: { records: [], page: 1, size: 20, total: 0, pages: 0 } })
+    await listInboundOrders({ page: 1, size: 20, appointmentStatus: 'UNAPPOINTED' })
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/inbound-plans', {
+      params: { page: 1, size: 20, appointmentStatus: 'UNAPPOINTED' },
+    })
+  })
+
+  it('preserves selected line ids as strings when creating an appointment', async () => {
+    vi.mocked(overseasHttp.post).mockResolvedValue({ code: '200', message: 'success', data: { id: '1', appointmentNo: 'APT-1', appointmentStatus: 'SUCCESS', selectedCount: 1, fbaWarehouseCode: 'ONT8' } })
+    const payload = {
+      customerId: '190000000000000001',
+      lineIds: ['190000000000000099'],
+      appointmentNo: 'APT-1',
+      appointmentAt: '2026-08-20T10:30:00',
+      expectedLoadingAt: '2026-08-20T09:00:00',
+      appointmentStatus: 'SUCCESS' as const,
+    }
+    await createFbaAppointment(payload)
+    expect(overseasHttp.post).toHaveBeenCalledWith('/platform/v1/last-leg/inbound-plans/fba-appointments/batch', payload)
+  })
+})
diff --git a/src/modules/overseas-warehouse/api/inboundOrders.ts b/src/modules/overseas-warehouse/api/inboundOrders.ts
new file mode 100644
index 00000000..26b1e835
--- /dev/null
+++ b/src/modules/overseas-warehouse/api/inboundOrders.ts
@@ -0,0 +1,113 @@
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import { normalizeOverseasPage, type OverseasPagePayload } from './lastMileOrders'
+
+export interface InboundOrderQuery {
+  page: number
+  size: number
+  planNo?: string
+  inboundCode?: string
+  lxCode?: string
+  status?: string
+  warehouse?: string
+  fbaWarehouseCode?: string
+  appointmentStatus?: string
+  dispatchStatus?: string
+  createdFrom?: string
+  createdTo?: string
+}
+
+export interface InboundOrderSummaryDto {
+  lineId: string
+  planId: string
+  planNo: string
+  customerId: string
+  orderId: string
+  inboundCode?: string | null
+  lxCode?: string | null
+  orderType?: string | null
+  overseasWarehouseCode?: string | null
+  overseasWarehouseName?: string | null
+  warehouseId?: string | null
+  warehouseCode?: string | null
+  warehouseName?: string | null
+  fbaWarehouseCode?: string | null
+  customerName?: string | null
+  packageCount?: number | null
+  pickedPackageCount?: number | null
+  volumeCbm?: number | null
+  palletCount?: number | null
+  assigned?: boolean | null
+  mergeAllowed?: boolean | null
+  urgent?: boolean | null
+  status?: string | null
+  appointmentNo?: string | null
+  appointmentStatus?: string | null
+  appointmentAt?: string | null
+  expectedLoadingAt?: string | null
+  dispatchStatus?: string | null
+  createdAt?: string | null
+  version?: number | null
+}
+
+export interface BatchFbaAppointmentPayload {
+  customerId: string
+  lineIds: string[]
+  appointmentNo: string
+  appointmentAt: string
+  expectedLoadingAt: string
+  appointmentStatus: 'PENDING' | 'SUCCESS' | 'FAILED' | 'CANCELLED'
+  appointmentRemark?: string
+}
+
+export interface FbaAppointmentDto {
+  id: string
+  customerId: string
+  appointmentNo: string
+  appointmentAt: string
+  expectedLoadingAt: string
+  appointmentStatus: string
+  appointmentRemark?: string | null
+  selectedCount: number
+  fbaWarehouseCode: string
+  items: Array<{ id: string; planId: string; lineId: string; orderId: string; inboundCode: string; fbaWarehouseCode: string }>
+}
+
+export type UpdateFbaAppointmentPayload = Omit<BatchFbaAppointmentPayload, 'lineIds' | 'appointmentNo'>
+
+export async function listInboundOrders(query: InboundOrderQuery) {
+  const response = await overseasHttp.get<ApiEnvelope<OverseasPagePayload<InboundOrderSummaryDto>>, ApiEnvelope<OverseasPagePayload<InboundOrderSummaryDto>>>(
+    '/platform/v1/last-leg/inbound-plans', { params: query },
+  )
+  return normalizeOverseasPage(unwrapApiResponse(response))
+}
+
+export async function createFbaAppointment(payload: BatchFbaAppointmentPayload) {
+  const response = await overseasHttp.post<ApiEnvelope<FbaAppointmentDto>, ApiEnvelope<FbaAppointmentDto>>(
+    '/platform/v1/last-leg/inbound-plans/fba-appointments/batch', payload,
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function getFbaAppointment(customerId: string, appointmentNo: string) {
+  const response = await overseasHttp.get<ApiEnvelope<FbaAppointmentDto>, ApiEnvelope<FbaAppointmentDto>>(
+    `/platform/v1/last-leg/inbound-plans/fba-appointments/${encodeURIComponent(appointmentNo)}`,
+    { params: { customerId } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function updateFbaAppointment(appointmentNo: string, payload: UpdateFbaAppointmentPayload) {
+  const response = await overseasHttp.put<ApiEnvelope<FbaAppointmentDto>, ApiEnvelope<FbaAppointmentDto>>(
+    `/platform/v1/last-leg/inbound-plans/fba-appointments/${encodeURIComponent(appointmentNo)}`,
+    payload,
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function updateInboundPlan(planNo: string, payload: { customerId: string; overseasWarehouseId: string; warehouseCode?: string; warehouseName?: string; version: number }) {
+  const response = await overseasHttp.put<ApiEnvelope<InboundOrderSummaryDto>, ApiEnvelope<InboundOrderSummaryDto>>(
+    `/platform/v1/last-leg/inbound-plans/${encodeURIComponent(planNo)}`, payload,
+  )
+  return unwrapApiResponse(response)
+}
diff --git a/src/modules/overseas-warehouse/api/inboundPlans.test.ts b/src/modules/overseas-warehouse/api/inboundPlans.test.ts
new file mode 100644
index 00000000..37a0bf09
--- /dev/null
+++ b/src/modules/overseas-warehouse/api/inboundPlans.test.ts
@@ -0,0 +1,18 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { getInboundPlan, listInboundPlans } from './inboundPlans'
+
+vi.mock('@/shared/api/overseasHttp', () => ({ overseasHttp: { get: vi.fn() } }))
+describe('inbound plan overseas API', () => {
+  beforeEach(() => vi.mocked(overseasHttp.get).mockReset())
+  it('pages plans with explicit customer scope', async () => {
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', message: 'ok', data: { records: [], page: 1, size: 20, total: 0, pages: 0 } })
+    await listInboundPlans({ customerId: '190000000000000001', page: 1, size: 20, inboundCode: 'IN-1' })
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/inbound-plans', { params: { customerId: '190000000000000001', page: 1, size: 20, inboundCode: 'IN-1' } })
+  })
+  it('gets detail by encoded plan number', async () => {
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', message: 'ok', data: { id: '1', planNo: 'IP/1', customerId: '2', sourceOrderId: '190000000000000099', lineCount: 0, palletCount: 0, totalVolumeCbm: 0, lines: [], pallets: [], allocations: [] } })
+    await getInboundPlan('IP/1', '2')
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/inbound-plans/IP%2F1', { params: { customerId: '2' } })
+  })
+})
diff --git a/src/modules/overseas-warehouse/api/inboundPlans.ts b/src/modules/overseas-warehouse/api/inboundPlans.ts
new file mode 100644
index 00000000..4871b48f
--- /dev/null
+++ b/src/modules/overseas-warehouse/api/inboundPlans.ts
@@ -0,0 +1,77 @@
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import { normalizeOverseasPage, type OverseasPagePayload } from './lastMileOrders'
+
+export interface InboundPlanQuery {
+  customerId: string
+  page: number
+  size: number
+  planNo?: string
+  inboundCode?: string
+  status?: string
+  overseasWarehouseId?: string
+  destinationWarehouseCode?: string
+  fbaWarehouseCode?: string
+  appointmentStatus?: string
+  createdFrom?: string
+  createdTo?: string
+}
+
+export interface InboundPlanSummaryDto {
+  id: string
+  planNo: string
+  sourceOrderId: string
+  customerId: string
+  customerName?: string | null
+  orderType?: string | null
+  inboundCode?: string | null
+  containerNo?: string | null
+  overseasWarehouseId?: string | null
+  overseasWarehouseCode?: string | null
+  overseasWarehouseName?: string | null
+  destinationWarehouseId?: string | null
+  destinationWarehouseCode?: string | null
+  destinationWarehouseName?: string | null
+  fbaWarehouseCode?: string | null
+  packageCount?: number | null
+  totalVolumeCbm?: number | null
+  palletCount?: number | null
+  status?: string | null
+  appointmentStatus?: string | null
+  createdAt?: string | null
+  updatedAt?: string | null
+}
+
+export interface InboundPlanDetailDto {
+  id: string
+  planNo: string
+  customerId: string
+  sourceOrderId: string
+  sourceOrderNo?: string | null
+  customerName?: string | null
+  orderType?: string | null
+  containerNo?: string | null
+  overseasWarehouseCode?: string | null
+  overseasWarehouseName?: string | null
+  status?: string | null
+  lineCount: number
+  palletCount: number
+  totalVolumeCbm: number
+  expectedPackageCount?: number
+  pickedPackageCount?: number
+  createdAt?: string | null
+  updatedAt?: string | null
+  remark?: string | null
+  lines: Array<{ id: string; orderId: string; inboundCode?: string | null; fbaWarehouseCode?: string | null; destinationWarehouseId?: string | null; destinationWarehouseCode?: string | null; destinationWarehouseName?: string | null; volumeCbm?: number | null; requiredPackageCount: number; plannedPalletCount: number }>
+  pallets: Array<{ id: string; palletNo?: string | null; destinationWarehouseId?: string | null; destinationWarehouseCode?: string | null; destinationWarehouseName?: string | null; capacityCbm?: number | null; allocatedVolumeCbm?: number | null; sequenceNo: number; warehousePalletId?: string | null; warehouseLocationId?: string | null; warehouseResourceLockId?: string | null; assignmentStatus?: string | null; lockedAt?: string | null; actualVolumeCbm?: number | null; actualPackageCount: number }>
+  allocations: Array<{ lineId: string; palletId: string; palletNo: string; palletOwnerPlanNo: string; palletOwnedByCurrentPlan: boolean; allocatedVolumeCbm?: number | null; plannedPackageCount: number; countedPackageCount: number; pickedPackageCount: number; actualVolumeCbm?: number | null; status?: string | null; version: number }>
+}
+
+export async function listInboundPlans(query: InboundPlanQuery) {
+  const { customerId, ...params } = query
+  return normalizeOverseasPage(unwrapApiResponse(await overseasHttp.get<ApiEnvelope<OverseasPagePayload<InboundPlanSummaryDto>>, ApiEnvelope<OverseasPagePayload<InboundPlanSummaryDto>>>('/platform/v1/last-leg/inbound-plans', { params: { customerId, ...params } })))
+}
+
+export async function getInboundPlan(planNo: string, customerId: string) {
+  return unwrapApiResponse(await overseasHttp.get<ApiEnvelope<InboundPlanDetailDto>, ApiEnvelope<InboundPlanDetailDto>>(`/platform/v1/last-leg/inbound-plans/${encodeURIComponent(planNo)}`, { params: { customerId } }))
+}
diff --git a/src/modules/overseas-warehouse/api/inventory.test.ts b/src/modules/overseas-warehouse/api/inventory.test.ts
new file mode 100644
index 00000000..3e915304
--- /dev/null
+++ b/src/modules/overseas-warehouse/api/inventory.test.ts
@@ -0,0 +1,37 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { getInventorySummary, listInventoryBalances, listInventoryLedger, listInventoryPositions } from './inventory'
+
+vi.mock('@/shared/api/overseasHttp', () => ({ overseasHttp: { get: vi.fn() } }))
+
+describe('overseas inventory API', () => {
+  beforeEach(() => { vi.clearAllMocks() })
+
+  it('keeps skuCode and nullable location filters on real balance queries', async () => {
+    vi.mocked(overseasHttp.get).mockResolvedValueOnce({ code: '200', data: { records: [], page: 1, size: 20, total: 0, pages: 0 } }).mockResolvedValueOnce({ code: '200', data: { totalPackages: 0 } })
+    const query = { page: 1, size: 20, skuCode: 'SKU-1', warehouseLocationCode: 'A-01' }
+
+    await listInventoryBalances(query)
+    await getInventorySummary(query)
+
+    expect(overseasHttp.get).toHaveBeenNthCalledWith(1, '/platform/v1/last-leg/inventory/balances', { params: query })
+    expect(overseasHttp.get).toHaveBeenNthCalledWith(2, '/platform/v1/last-leg/inventory/summary', { params: { page: 1, size: 200, skuCode: 'SKU-1', warehouseLocationCode: 'A-01' } })
+  })
+
+  it('uses the read-only position and ledger endpoints without customer scope', async () => {
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', data: [] })
+
+    await listInventoryPositions('190000000000000099')
+    await listInventoryLedger({ page: 1, size: 20, skuCode: 'SKU-1' })
+
+    expect(overseasHttp.get).toHaveBeenNthCalledWith(1, '/platform/v1/last-leg/inventory/balances/190000000000000099/positions', { params: {} })
+    expect(overseasHttp.get).toHaveBeenNthCalledWith(2, '/platform/v1/last-leg/inventory/ledger', { params: { page: 1, size: 20, skuCode: 'SKU-1' } })
+  })
+
+  it('passes the inbound code as a business filter and preserves the returned customer name', async () => {
+    const record = { id: '2093539779795795969', customerId: '2093539779795795970', customerName: '华远贸易', inboundCode: 'NYEXX2608300001', beforePackages: 0, deltaPackages: 2, afterPackages: 2 }
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', data: { records: [record], page: 1, size: 20, total: 1, pages: 1 } })
+    await expect(listInventoryLedger({ page: 1, size: 20, inboundCode: 'NYEXX2608300001', customerName: '华远贸易' })).resolves.toMatchObject({ records: [record] })
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/inventory/ledger', { params: { page: 1, size: 20, inboundCode: 'NYEXX2608300001', customerName: '华远贸易' } })
+  })
+})
diff --git a/src/modules/overseas-warehouse/api/inventory.ts b/src/modules/overseas-warehouse/api/inventory.ts
new file mode 100644
index 00000000..d49698f5
--- /dev/null
+++ b/src/modules/overseas-warehouse/api/inventory.ts
@@ -0,0 +1,173 @@
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import { normalizeOverseasPage, type OverseasPagePayload } from './lastMileOrders'
+
+export interface InventoryBalanceDto {
+  id: string
+  customerId: string
+  customerName?: string | null
+  overseasWarehouseId: string
+  overseasWarehouseCode?: string | null
+  overseasWarehouseName?: string | null
+  destinationWarehouseId?: string | null
+  destinationWarehouseCode?: string | null
+  destinationWarehouseName?: string | null
+  inboundOrderId: string
+  inboundOrderNo?: string | null
+  inboundCode: string
+  skuCode?: string | null
+  productNameZh?: string | null
+  productNameEn?: string | null
+  totalPackages: number
+  availablePackages: number
+  holdPackages: number
+  allocatedPackages: number
+  pickedPackages: number
+  inTransitPackages: number
+  receivingPackages: number
+  procurementPackages: number
+  updatedAt?: string | null
+}
+
+export interface InventoryDashboardDto {
+  inboundOrderCount: number
+  palletCount: number
+  totalPackages: number
+  availablePackages: number
+  holdPackages: number
+  allocatedPackages: number
+  pickedPackages: number
+  inTransitPackages: number
+  receivingPackages: number
+  procurementPackages: number
+}
+
+export interface InventoryPositionDto {
+  id: string
+  balanceId: string
+  overseasWarehouseId?: string | null
+  destinationWarehouseCode?: string | null
+  inboundOrderId?: string | null
+  inboundOrderNo?: string | null
+  inboundCode?: string | null
+  palletId?: string | null
+  palletNo?: string | null
+  batchNo?: string | null
+  warehouseLocationId?: string | null
+  warehouseLocationCode?: string | null
+  totalPackages: number
+  availablePackages: number
+  holdPackages: number
+  allocatedPackages: number
+  pickedPackages: number
+  receivingPackages: number
+  status?: string | null
+  updatedAt?: string | null
+}
+
+export interface InventoryLedgerDto {
+  id: string
+  customerId: string
+  customerName?: string | null
+  overseasWarehouseId?: string | null
+  destinationWarehouseCode?: string | null
+  inboundOrderId?: string | null
+  inboundOrderNo?: string | null
+  inboundCode?: string | null
+  palletNo?: string | null
+  batchNo?: string | null
+  warehouseLocationCode?: string | null
+  skuCode?: string | null
+  businessType?: string | null
+  businessOrderNo?: string | null
+  outboundOrderNo?: string | null
+  statusFrom?: string | null
+  statusTo?: string | null
+  beforePackages: number
+  deltaPackages: number
+  afterPackages: number
+  operatorId?: string | null
+  remark?: string | null
+  occurredAt?: string | null
+}
+
+export interface InventoryBalanceQuery {
+  page: number
+  size: number
+  customerName?: string
+  overseasWarehouseId?: string
+  overseasWarehouseCode?: string
+  destinationWarehouseCode?: string
+  inboundOrderNo?: string
+  inboundCode?: string
+  businessOrderNo?: string
+  skuCode?: string
+  productName?: string
+  batchNo?: string
+  warehouseLocationCode?: string
+  inventoryStatus?: string
+}
+
+function params(query: InventoryBalanceQuery) { return { ...query } }
+
+export async function listInventoryBalances(query: InventoryBalanceQuery) {
+  const response = await overseasHttp.get<ApiEnvelope<OverseasPagePayload<InventoryBalanceDto>>, ApiEnvelope<OverseasPagePayload<InventoryBalanceDto>>>(
+    '/platform/v1/last-leg/inventory/balances', { params: params(query) },
+  )
+  return normalizeOverseasPage(unwrapApiResponse(response))
+}
+
+export async function downloadInventoryBalances(query: Partial<InventoryBalanceQuery>) {
+  const response = await overseasHttp.get<Blob>('/platform/v1/last-leg/inventory/balances/export', { params: query, responseType: 'blob' })
+  return response.data
+}
+
+export async function getInventorySummary(query: InventoryBalanceQuery) {
+  const response = await overseasHttp.get<ApiEnvelope<InventoryDashboardDto>, ApiEnvelope<InventoryDashboardDto>>(
+    '/platform/v1/last-leg/inventory/summary', { params: params({ ...query, page: 1, size: 200 }) },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function listInventoryPositions(
+  balanceId: string,
+  query: { palletNo?: string; batchNo?: string; inventoryStatus?: string } = {},
+) {
+  const response = await overseasHttp.get<ApiEnvelope<InventoryPositionDto[]>, ApiEnvelope<InventoryPositionDto[]>>(
+    `/platform/v1/last-leg/inventory/balances/${encodeURIComponent(balanceId)}/positions`,
+    { params: query },
+  )
+  return unwrapApiResponse(response)
+}
+
+export interface InventoryLedgerQuery {
+  page: number
+  size: number
+  customerName?: string
+  overseasWarehouseId?: string
+  destinationWarehouseCode?: string
+  businessType?: string
+  businessOrderNo?: string
+  inboundOrderNo?: string
+  inboundCode?: string
+  outboundOrderNo?: string
+  palletNo?: string
+  batchNo?: string
+  skuCode?: string
+  warehouseLocationCode?: string
+  occurredFrom?: string
+  occurredTo?: string
+}
+
+export async function listInventoryLedger(query: InventoryLedgerQuery) {
+  const response = await overseasHttp.get<ApiEnvelope<OverseasPagePayload<InventoryLedgerDto>>, ApiEnvelope<OverseasPagePayload<InventoryLedgerDto>>>(
+    '/platform/v1/last-leg/inventory/ledger',
+    { params: { ...query } },
+  )
+  return normalizeOverseasPage(unwrapApiResponse(response))
+}
+
+export async function downloadInventoryLedger(query: Partial<InventoryLedgerQuery>) {
+  const response = await overseasHttp.get<Blob>('/platform/v1/last-leg/inventory/ledger/export', { params: query, responseType: 'blob' })
+  return response.data
+}
diff --git a/src/modules/overseas-warehouse/api/lastMileOrders.test.ts b/src/modules/overseas-warehouse/api/lastMileOrders.test.ts
new file mode 100644
index 00000000..e424038b
--- /dev/null
+++ b/src/modules/overseas-warehouse/api/lastMileOrders.test.ts
@@ -0,0 +1,171 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { changeContainerReceivingWarehouse, convertLastMileContainerToInboundPlans, createManualInboundPlan, downloadLastMileOrders, getContainerPlanProgress, getLastMileOrder, getLastMileOrderManualNodes, listContainerPlanProgress, listLastMileOrders, transferLastMileOrders, updateLastMileOrderHold, updateLastMileOrderManualNodes } from './lastMileOrders'
+
+vi.mock('@/shared/api/overseasHttp', () => ({ overseasHttp: { get: vi.fn(), put: vi.fn(), post: vi.fn() } }))
+
+describe('last-mile order overseas API', () => {
+  beforeEach(() => {
+    vi.mocked(overseasHttp.get).mockReset()
+    vi.mocked(overseasHttp.put).mockReset()
+    vi.mocked(overseasHttp.post).mockReset()
+  })
+
+  it('loads all platform orders without a customer scope', async () => {
+    const record = { id: '190000000000000099', customerId: '190000000000000001', sourceContainerBookingId: '190000000000000088', customerName: '华远贸易', orderNo: 'LMO-260827-0001' }
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', message: 'success', data: { records: [record], page: '2', size: '20', total: '1', pages: '1' } })
+    await expect(listLastMileOrders({ page: 2, size: 20, orderType: 'FIRST_LEG', currentStatus: 'PENDING_ASSIGNMENT', warehouse: 'LAX' })).resolves.toEqual({ records: [record], page: 2, size: 20, total: 1, pages: 1 })
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/orders', {
+      params: { page: 2, size: 20, orderType: 'FIRST_LEG', currentStatus: 'PENDING_ASSIGNMENT', warehouse: 'LAX' },
+    })
+  })
+
+  it('preserves a long order id as a string in the detail path', async () => {
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', message: 'success', data: { order: { id: '190000000000000099' }, cargo: [], statusHistory: [] } })
+    await getLastMileOrder('190000000000000099')
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/orders/190000000000000099')
+  })
+
+  it('does not call outbound or delivery endpoints', () => {
+    const source = `${listLastMileOrders}${getLastMileOrder}`
+    expect(source).not.toMatch(/outbound|delivery|dispatch/)
+  })
+
+  it('passes all supported list filters and pagination without customerId', async () => {
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', message: 'success', data: { records: [], page: 2, size: 50, total: 0, pages: 0 } })
+    await listLastMileOrders({
+      page: 2, size: 50, orderNo: 'LM-1', inboundCode: 'IN-1', sourceOrderNo: 'SRC-1',
+      containerNo: 'CONT-1', status: 'PENDING_DELIVERY', transferWarehouseCode: 'ONT8',
+      abnormal: true, detained: false, createdFrom: '2026-08-01T00:00:00', createdTo: '2026-08-31T23:59:59',
+    })
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/orders', {
+      params: expect.objectContaining({ page: 2, size: 50, sourceOrderNo: 'SRC-1', transferWarehouseCode: 'ONT8', abnormal: true, detained: false }),
+    })
+    expect(JSON.stringify(vi.mocked(overseasHttp.get).mock.calls[0]?.[1])).not.toContain('customerId')
+  })
+
+  it('uses the real destination transfer endpoint and edit contract', async () => {
+    vi.mocked(overseasHttp.put).mockResolvedValue({ code: '200', message: 'success', data: 1 })
+    await transferLastMileOrders({
+      orderIds: ['190000000000000099'], warehouseId: 'WH-1', warehouseCode: 'ONT8', warehouseName: 'Ontario',
+    })
+    expect(overseasHttp.put).toHaveBeenCalledWith('/platform/v1/last-leg/orders/destination', expect.objectContaining({ orderIds: ['190000000000000099'] }))
+  })
+
+  it('returns the exported CSV blob without reading data twice', async () => {
+    const blob = new Blob(['orders'], { type: 'text/csv' })
+    vi.mocked(overseasHttp.get).mockResolvedValue(blob)
+
+    await expect(downloadLastMileOrders({ orderNo: 'LM-1' })).resolves.toBe(blob)
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/orders/export', {
+      params: { orderNo: 'LM-1' }, responseType: 'blob',
+    })
+  })
+
+  it('exports all authorized orders without pagination or empty filters', async () => {
+    const blob = new Blob(['orders'], { type: 'text/csv' })
+    vi.mocked(overseasHttp.get).mockResolvedValue(blob)
+
+    await downloadLastMileOrders({ page: 1, size: 10, orderNo: '', createdFrom: undefined })
+
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/orders/export', {
+      params: {}, responseType: 'blob',
+    })
+  })
+
+  it('rejects a JSON business error instead of saving it as CSV', async () => {
+    const blob = new Blob([JSON.stringify({
+      code: 'S0500', message: '系统内部错误', data: null, requestId: 'req-1', traceId: 'trace-1',
+    })], { type: 'application/json' })
+    vi.mocked(overseasHttp.get).mockResolvedValue(blob)
+
+    await expect(downloadLastMileOrders({})).rejects.toMatchObject({
+      code: 'S0500', message: '系统内部错误', requestId: 'req-1', traceId: 'trace-1',
+    })
+  })
+
+  it('uses the manual inbound-plan endpoint with the complete form and idempotency evidence', async () => {
+    vi.mocked(overseasHttp.post).mockResolvedValue({ code: '200', message: 'success', data: {} })
+    const payload = { orderId: '190000000000000099', customerId: '190000000000000001', expectedOrderVersion: 4,
+      palletCount: 8, palletType: 'STANDARD' as const,
+      assigned: false, mergeRequired: false, urgent: true, remark: '加急' }
+    await createManualInboundPlan(payload, 'plan-key-1')
+    expect(overseasHttp.post).toHaveBeenCalledWith('/platform/v1/last-leg/inbound-plans/manual', payload,
+      { headers: { 'Idempotency-Key': 'plan-key-1' } })
+    expect(payload).not.toHaveProperty('inboundCode')
+    expect(payload).not.toHaveProperty('plannedArrivalDate')
+    expect(payload).not.toHaveProperty('plannedWarehouseId')
+    expect(payload).not.toHaveProperty('plannedWarehouseCode')
+    expect(payload).not.toHaveProperty('plannedWarehouseName')
+  })
+
+  it('uses versioned idempotent order hold and complete manual-node snapshot endpoints', async () => {
+    vi.mocked(overseasHttp.put).mockResolvedValue({ code: '200', message: 'success', data: {} })
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', message: 'success', data: { nodes: [] } })
+    await updateLastMileOrderHold('190000000000000099', { held: true, chargeable: true, reason: '海关查验', expectedVersion: 4 }, 'hold-key-1')
+    expect(overseasHttp.put).toHaveBeenLastCalledWith('/platform/v1/last-leg/orders/190000000000000099/hold',
+      { held: true, chargeable: true, reason: '海关查验', expectedVersion: 4 }, { headers: { 'Idempotency-Key': 'hold-key-1' } })
+    await getLastMileOrderManualNodes('190000000000000099')
+    expect(overseasHttp.get).toHaveBeenLastCalledWith('/platform/v1/last-leg/orders/190000000000000099/manual-nodes')
+    const nodes = [{ nodeCode: 'ESTIMATED_ARRIVAL' as const, nodeAt: '2026-09-10T10:00:00' }]
+    await updateLastMileOrderManualNodes('190000000000000099', 5, nodes, 'node-key-1')
+    expect(overseasHttp.put).toHaveBeenLastCalledWith('/platform/v1/last-leg/orders/190000000000000099/manual-nodes',
+      { expectedVersion: 5, nodes }, { headers: { 'Idempotency-Key': 'node-key-1' } })
+  })
+
+  it('uses one atomic container request without looping individual conversions', async () => {
+    vi.mocked(overseasHttp.post).mockResolvedValue({ code: '200', message: 'success', data: [] })
+    await expect(convertLastMileContainerToInboundPlans({
+      sourceContainerBookingId: '2092873463568597001',
+      snapshotVersion: 9,
+      snapshotHash: 'a'.repeat(64),
+    }, 'container-plan-idempotency-key')).resolves.toEqual([])
+    expect(overseasHttp.post).toHaveBeenCalledTimes(1)
+    expect(overseasHttp.post).toHaveBeenCalledWith('/platform/v1/last-leg/inbound-plans/convert-container', {
+      sourceContainerBookingId: '2092873463568597001',
+      snapshotVersion: 9,
+      snapshotHash: 'a'.repeat(64),
+    }, { headers: { 'Idempotency-Key': 'container-plan-idempotency-key' } })
+  })
+
+  it('loads server-side container progress with pagination and filters', async () => {
+    const record = {
+      sourceContainerBookingId: '2092873463568597001', containerNo: 'CONT-15', totalOrderCount: 15,
+      inboundCodeCount: 13, missingInboundCodeCount: 2, planCount: 10, plannedInboundCodeCount: 10,
+      pendingPlanCount: 5, resourcePendingPlanCount: 0, plannedArrivalAt: '2026-09-01T08:00:00', allPlansReady: false, blockingReason: '存在2票缺少入仓码',
+    }
+    vi.mocked(overseasHttp.get).mockResolvedValue({
+      code: '200', message: 'success', data: { records: [record], page: '2', size: '10', total: '21', pages: '3' },
+    })
+    await expect(listContainerPlanProgress({
+      page: 2, size: 10, containerNo: 'CONT-15',
+      createdFrom: '2026-08-01T00:00:00', createdTo: '2026-08-31T23:59:59',
+    })).resolves.toEqual({ records: [record], page: 2, size: 10, total: 21, pages: 3 })
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/orders/container-summaries', {
+      params: {
+        page: 2, size: 10, containerNo: 'CONT-15',
+        createdFrom: '2026-08-01T00:00:00', createdTo: '2026-08-31T23:59:59',
+      },
+    })
+  })
+
+  it('loads one container detail with the encoded stable long id', async () => {
+    const detail = { summary: { sourceContainerBookingId: '2092873463568597001' }, orders: [] }
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', message: 'success', data: detail })
+    await expect(getContainerPlanProgress('2092873463568597001/unsafe')).resolves.toEqual(detail)
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/orders/container-summaries/2092873463568597001%2Funsafe')
+  })
+
+  it('changes one whole container receiving warehouse with version and idempotency evidence', async () => {
+    const updated = { sourceContainerBookingId: '2092873463568597001', overseasWarehouseId: '9007199254740993' }
+    vi.mocked(overseasHttp.put).mockResolvedValue({ code: '200', message: 'success', data: updated })
+    await expect(changeContainerReceivingWarehouse('2092873463568597001/unsafe', {
+      overseasWarehouseId: '9007199254740993', expectedVersion: 7, remark: '改派洛杉矶接柜',
+    }, 'receiving-key-1')).resolves.toEqual(updated)
+    expect(overseasHttp.put).toHaveBeenCalledWith(
+      '/platform/v1/last-leg/orders/container-summaries/2092873463568597001%2Funsafe/receiving-warehouse',
+      { overseasWarehouseId: '9007199254740993', expectedVersion: 7, remark: '改派洛杉矶接柜' },
+      { headers: { 'Idempotency-Key': 'receiving-key-1' } },
+    )
+  })
+})
diff --git a/src/modules/overseas-warehouse/api/lastMileOrders.ts b/src/modules/overseas-warehouse/api/lastMileOrders.ts
new file mode 100644
index 00000000..f766721c
--- /dev/null
+++ b/src/modules/overseas-warehouse/api/lastMileOrders.ts
@@ -0,0 +1,479 @@
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { ApiResponseError, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import type { InboundPlanDetailDto } from './inboundPlans'
+
+export interface OverseasPageResult<T> {
+  records: T[]
+  page: number
+  size: number
+  total: number
+  pages: number
+}
+
+export type OverseasPagePayload<T> = Omit<OverseasPageResult<T>, 'page' | 'size' | 'total' | 'pages'> & {
+  page: number | string
+  size: number | string
+  total: number | string
+  pages: number | string
+}
+
+export function normalizeOverseasPage<T>(value: OverseasPagePayload<T>): OverseasPageResult<T> {
+  return { ...value, page: Number(value.page), size: Number(value.size), total: Number(value.total), pages: Number(value.pages) }
+}
+
+export interface LastMileOrderQuery {
+  page: number
+  size: number
+  orderNo?: string
+  relabelNo?: string
+  orderType?: string
+  inboundCode?: string
+  lxCode?: string
+  containerNo?: string
+  currentStatus?: string
+  status?: string
+  warehouse?: string
+  sourceOrderNo?: string
+  transferWarehouseCode?: string
+  abnormal?: boolean
+  detained?: boolean
+  createdFrom?: string
+  createdTo?: string
+}
+
+export interface LastMileOrderSummaryDto {
+  id: string
+  customerId: string
+  sourceContainerBookingId?: string | null
+  orderNo: string
+  orderType?: string | null
+  orderTypeName?: string | null
+  inboundCode?: string | null
+  lxCode?: string | null
+  sourceOrderNo?: string | null
+  sourceInboundId?: string | null
+  customerName?: string | null
+  overseasWarehouseId?: string | null
+  overseasWarehouseCode?: string | null
+  overseasWarehouseName?: string | null
+  transferWarehouseName?: string | null
+  transferWarehouseId?: string | null
+  transferWarehouseCode?: string | null
+  fbaWarehouseCode?: string | null
+  containerNo?: string | null
+  containerNode?: string | null
+  abnormal?: boolean | null
+  detained?: boolean | null
+  holdChargeable?: boolean | null
+  holdReason?: string | null
+  manualOverrideEnabled?: boolean | null
+  nodeSource?: 'CONTAINER' | 'MANUAL' | null
+  version?: number | null
+  palletCount?: number | null
+  packageCount?: number | null
+  volumeCbm?: number | null
+  productQuantity?: number | null
+  volumeWeightKg?: number | null
+  estimatedArrivalAt?: string | null
+  actualArrivalAt?: string | null
+  estimatedWarehouseAt?: string | null
+  inboundOrderNo?: string | null
+  dispatchStatus?: 'SCHEDULED' | 'UNSCHEDULED' | null
+  /** Legacy read-only association retained for compatibility; absent from current service DTO. */
+  deliveryOrderNo?: string | null
+  outboundOrderNo?: string | null
+  relabelOrderNo?: string | null
+  relabelStatus?: string | null
+  palletMergeFlag?: string | null
+  /** Optional grouping facts returned by newer last-leg services. */
+  palletMergeBatchId?: string | null
+  palletMergeInboundNos?: string[] | null
+  currentStatus?: string | null
+  privateRemark?: string | null
+  customerRemark?: string | null
+  warehouseRemark?: string | null
+  createdAt?: string | null
+}
+
+export interface LastMileOrderDto extends LastMileOrderSummaryDto {
+  customerId: string
+  sourceOrderNo?: string | null
+  subOrderStatus?: string | null
+  updatedAt?: string | null
+}
+
+export interface LastMileCargoDto {
+  id: string
+  skuCode?: string | null
+  productNameZh?: string | null
+  productNameEn?: string | null
+  packageCount?: number | null
+  productQuantity?: number | null
+  palletCount?: number | null
+  grossWeightKg?: number | null
+  dimensionalWeightKg?: number | null
+  volumeCbm?: number | null
+  destinationWarehouseName?: string | null
+  fbaTrackingNo?: string | null
+  shipmentNo?: string | null
+}
+
+export interface LastMileStatusHistoryDto {
+  id: string
+  fromStatus?: string | null
+  toStatus?: string | null
+  remark?: string | null
+  createdAt?: string | null
+}
+
+export interface LastMileFeeDto {
+  id: string; sourceFeeId: string; sourceVersion: number; customerId: string; orderId?: string | null
+  feeItemCode: string; feeItemName: string; direction: 'RECEIVABLE' | 'PAYABLE'
+  currency: 'CNY'; amount: number; originalCurrency: 'CNY' | 'USD'; originalAmount: number
+  exchangeRate: number; exchangeRateMonth: string; reviewStatus: 'DRAFT' | 'PENDING' | 'APPROVED' | 'REJECTED'
+  publicationStatus: string; sourceStatus: string; supplierId?: string | null; supplierName?: string | null
+  settlementMode?: 'ON_ACCOUNT' | 'DIRECT_PAID' | null; businessDate: string
+  chargeableQuantity?: number | null; quantityUnit?: string | null; unitPrice?: number | null
+  periodStart?: string | null; periodEnd?: string | null; createdAt: string; updatedAt: string
+}
+
+export interface LastMileOperationDto {
+  id: string
+  operationNode: string
+  operatorName: string
+  result: string
+  createdAt: string
+}
+
+export interface CreateLastMileFeePayload {
+  feeItemCode: string; feeItemName: string; direction: 'RECEIVABLE' | 'PAYABLE'; currency: 'CNY' | 'USD'
+  amount: number; businessDate: string; supplierId?: string; supplierName?: string; supplierCategory?: string
+  settlementMode?: 'ON_ACCOUNT' | 'DIRECT_PAID'; paidAt?: string; paymentMethod?: 'ONLINE' | 'BANK_TRANSFER' | 'CASH' | 'OTHER'
+  paymentReferenceNo?: string; paymentVoucherFileIds?: string[]; chargeableQuantity?: number
+  quantityUnit?: string; unitPrice?: number; periodStart?: string; periodEnd?: string
+}
+
+export interface TransferDestinationPayload {
+  orderIds: string[]
+  warehouseId: string
+  warehouseCode: string
+  warehouseName: string
+  remark?: string
+}
+
+export interface ContainerPlanProgressQuery {
+  page: number
+  size: number
+  containerNo?: string
+  createdFrom?: string
+  createdTo?: string
+}
+
+export interface ContainerPlanProgressSummaryDto {
+  sourceContainerBookingId: string
+  containerNo: string | null
+  overseasWarehouseId: string | null
+  overseasWarehouseCode: string | null
+  overseasWarehouseName: string | null
+  assignmentVersion: number
+  canChangeReceivingWarehouse: boolean
+  receivingWarehouseLockReason: string | null
+  totalOrderCount: number
+  inboundCodeCount: number
+  missingInboundCodeCount: number
+  planCount: number
+  plannedInboundCodeCount: number
+  pendingPlanCount: number
+  resourcePendingPlanCount: number
+  plannedArrivalAt: string | null
+  allPlansReady: boolean
+  blockingReason: string | null
+}
+
+export interface ContainerPlanProgressItemDto {
+  orderId: string
+  customerId: string
+  orderNo: string | null
+  inboundCode: string | null
+  orderStatus: string
+  planId: string | null
+  planNo: string | null
+  planStatus: string | null
+  planValid: boolean
+  plannedArrivalAt: string | null
+}
+
+export interface ContainerPlanProgressDetailDto {
+  summary: ContainerPlanProgressSummaryDto
+  orders: ContainerPlanProgressItemDto[]
+}
+
+export interface ConvertContainerInboundPlanPayload {
+  sourceContainerBookingId: string
+  snapshotVersion: number
+  snapshotHash: string
+}
+
+export type ContainerInboundPlanPreviewReadiness = 'READY' | 'RESOURCE_PENDING' | 'PLANNED' | 'BLOCKED'
+
+export interface ContainerInboundPlanPreviewOrderDto {
+  customerId: string
+  customerName: string | null
+  orderId: string
+  businessOrderNo: string
+  inboundCode: string | null
+  orderType: string
+  destinationType: 'FBA' | 'ONE_CLICK_DROPSHIP' | 'PRIVATE_ADDRESS'
+  destinationWarehouseId: string | null
+  destinationWarehouseCode: string | null
+  destinationWarehouseName: string | null
+  fbaWarehouseCode: string | null
+  packageCount: number
+  volumeCbm: number
+  suggestedPalletCount: number | null
+  sourcePalletCount: number
+  targetPalletCount: number
+  supplementPalletCount: number
+  plannedPalletCount: number | null
+  existingPlanNo: string | null
+  planStatus: string | null
+  orderVersion: number
+  readiness: ContainerInboundPlanPreviewReadiness
+  blockers: string[]
+}
+
+export interface ContainerInboundPlanPreviewGroupDto {
+  destinationType: 'FBA' | 'ONE_CLICK_DROPSHIP' | 'PRIVATE_ADDRESS'
+  destinationWarehouseId: string | null
+  destinationWarehouseCode: string | null
+  destinationWarehouseName: string | null
+  orderCount: number
+  pendingOrderCount: number
+  pendingPalletCount: number
+  sourcePalletCount: number
+  supplementPalletCount: number
+  existingPlannedPalletCount: number
+  suggestedPalletCount: number
+  plannedPalletCount: number
+  orders: ContainerInboundPlanPreviewOrderDto[]
+}
+
+export interface ContainerInboundPlanPreviewDto {
+  sourceContainerBookingId: string
+  containerNo: string | null
+  overseasWarehouseId: string | null
+  overseasWarehouseCode: string | null
+  overseasWarehouseName: string | null
+  snapshotVersion: number
+  snapshotHash: string
+  totalOrderCount: number
+  readyOrderCount: number
+  blockedOrderCount: number
+  pendingOrderCount: number
+  pendingPalletCount: number
+  sourcePalletCount: number
+  supplementPalletCount: number
+  existingPlannedPalletCount: number
+  totalSuggestedPalletCount: number
+  totalPlannedPalletCount: number
+  ready: boolean
+  groups: ContainerInboundPlanPreviewGroupDto[]
+}
+
+export type ManualNodeCode =
+  | 'DOMESTIC_CUSTOMS_COMPLETED'
+  | 'ESTIMATED_DEPARTURE'
+  | 'ACTUAL_DEPARTURE'
+  | 'ESTIMATED_ARRIVAL'
+  | 'OVERSEAS_CUSTOMS_COMPLETED'
+  | 'ACTUAL_ARRIVAL_WAITING_UNLOAD'
+  | 'PICKUP_APPOINTED'
+  | 'UNLOADED'
+
+export interface ManualInboundPlanPayload {
+  customerId: string
+  orderId: string
+  expectedOrderVersion: number
+  palletCount: number
+  palletType: 'STANDARD' | 'WOOD' | 'PAPER'
+  assigned: boolean
+  mergeRequired: boolean
+  urgent: boolean
+  remark?: string
+}
+
+export interface HoldLastMileOrderPayload {
+  held: boolean
+  chargeable: boolean
+  reason: string
+  expectedVersion: number
+}
+
+export interface HoldLastMileOrderResponse {
+  orderId: string
+  held: boolean
+  chargeable: boolean
+  reason?: string | null
+  version: number
+}
+
+export interface ManualNodeValue {
+  nodeCode: ManualNodeCode
+  nodeAt: string | null
+}
+
+export interface ManualNodesResponse {
+  orderId: string
+  manualOverrideEnabled: boolean
+  nodes: Array<ManualNodeValue & { source: 'MANUAL' }>
+  version: number
+}
+
+export interface ChangeContainerReceivingWarehousePayload {
+  overseasWarehouseId: string
+  expectedVersion: number
+  remark?: string
+}
+
+export interface LastMileOrderDetailDto {
+  order: LastMileOrderDto
+  manualNodes?: ManualNodesResponse['nodes']
+  cargo: LastMileCargoDto[]
+  statusHistory: LastMileStatusHistoryDto[]
+  fees: LastMileFeeDto[]
+  operationHistory: LastMileOperationDto[]
+}
+
+export async function listLastMileOrders(query: LastMileOrderQuery) {
+  const response = await overseasHttp.get<ApiEnvelope<OverseasPagePayload<LastMileOrderSummaryDto>>, ApiEnvelope<OverseasPagePayload<LastMileOrderSummaryDto>>>(
+    '/platform/v1/last-leg/orders',
+    { params: query },
+  )
+  return normalizeOverseasPage(unwrapApiResponse(response))
+}
+
+export async function getLastMileOrder(orderId: string) {
+  const response = await overseasHttp.get<ApiEnvelope<LastMileOrderDetailDto>, ApiEnvelope<LastMileOrderDetailDto>>(
+    `/platform/v1/last-leg/orders/${encodeURIComponent(orderId)}`,
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function downloadLastMileOrders(query: Partial<LastMileOrderQuery>) {
+  const { page: _page, size: _size, ...filters } = query
+  const params = Object.fromEntries(
+    Object.entries(filters).filter(([, value]) => value !== undefined && value !== null && value !== ''),
+  )
+  const blob = await overseasHttp.get<Blob, Blob>('/platform/v1/last-leg/orders/export', { params, responseType: 'blob' })
+  if (!blob.type.toLowerCase().includes('json')) return blob
+  let error: Partial<ApiEnvelope<unknown>>
+  try {
+    error = JSON.parse(await blob.text()) as Partial<ApiEnvelope<unknown>>
+  } catch {
+    throw new ApiResponseError('导出接口返回了非 CSV 内容', 'INVALID_EXPORT_RESPONSE')
+  }
+  throw new ApiResponseError(
+    error.message || '尾程订单导出失败',
+    error.code || 'INVALID_EXPORT_RESPONSE',
+    undefined,
+    error.data,
+    error.requestId,
+    error.traceId,
+  )
+}
+
+export async function createLastMileOrderFee(orderId: string, payload: CreateLastMileFeePayload) {
+  const response = await overseasHttp.post<ApiEnvelope<LastMileFeeDto>, ApiEnvelope<LastMileFeeDto>>(
+    `/platform/v1/last-leg/orders/${encodeURIComponent(orderId)}/fees`, payload,
+    { headers: { 'Idempotency-Key': `last-mile-fee-${orderId}-${Date.now()}-${Math.random().toString(36).slice(2)}` } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function transferLastMileOrders(payload: TransferDestinationPayload) {
+  const response = await overseasHttp.put<ApiEnvelope<number>, ApiEnvelope<number>>(
+    '/platform/v1/last-leg/orders/destination', payload,
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function listContainerPlanProgress(query: ContainerPlanProgressQuery): Promise<OverseasPageResult<ContainerPlanProgressSummaryDto>> {
+  const response = await overseasHttp.get<ApiEnvelope<OverseasPagePayload<ContainerPlanProgressSummaryDto>>, ApiEnvelope<OverseasPagePayload<ContainerPlanProgressSummaryDto>>>(
+    '/platform/v1/last-leg/orders/container-summaries',
+    { params: query },
+  )
+  return normalizeOverseasPage(unwrapApiResponse(response))
+}
+
+export async function getContainerPlanProgress(sourceContainerBookingId: string) {
+  const response = await overseasHttp.get<ApiEnvelope<ContainerPlanProgressDetailDto>, ApiEnvelope<ContainerPlanProgressDetailDto>>(
+    `/platform/v1/last-leg/orders/container-summaries/${encodeURIComponent(sourceContainerBookingId)}`,
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function createManualInboundPlan(payload: ManualInboundPlanPayload, idempotencyKey: string) {
+  const response = await overseasHttp.post<ApiEnvelope<InboundPlanDetailDto>, ApiEnvelope<InboundPlanDetailDto>>(
+    '/platform/v1/last-leg/inbound-plans/manual', payload,
+    { headers: { 'Idempotency-Key': idempotencyKey } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function updateLastMileOrderHold(orderId: string, payload: HoldLastMileOrderPayload, idempotencyKey: string) {
+  const response = await overseasHttp.put<ApiEnvelope<HoldLastMileOrderResponse>, ApiEnvelope<HoldLastMileOrderResponse>>(
+    `/platform/v1/last-leg/orders/${encodeURIComponent(orderId)}/hold`, payload,
+    { headers: { 'Idempotency-Key': idempotencyKey } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function getLastMileOrderManualNodes(orderId: string) {
+  const response = await overseasHttp.get<ApiEnvelope<ManualNodesResponse>, ApiEnvelope<ManualNodesResponse>>(
+    `/platform/v1/last-leg/orders/${encodeURIComponent(orderId)}/manual-nodes`,
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function updateLastMileOrderManualNodes(
+  orderId: string,
+  expectedVersion: number,
+  nodes: ManualNodeValue[],
+  idempotencyKey: string,
+) {
+  const response = await overseasHttp.put<ApiEnvelope<ManualNodesResponse>, ApiEnvelope<ManualNodesResponse>>(
+    `/platform/v1/last-leg/orders/${encodeURIComponent(orderId)}/manual-nodes`,
+    { expectedVersion, nodes },
+    { headers: { 'Idempotency-Key': idempotencyKey } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function changeContainerReceivingWarehouse(
+  sourceContainerBookingId: string,
+  payload: ChangeContainerReceivingWarehousePayload,
+  idempotencyKey: string,
+) {
+  const response = await overseasHttp.put<ApiEnvelope<ContainerPlanProgressSummaryDto>, ApiEnvelope<ContainerPlanProgressSummaryDto>>(
+    `/platform/v1/last-leg/orders/container-summaries/${encodeURIComponent(sourceContainerBookingId)}/receiving-warehouse`,
+    payload,
+    { headers: { 'Idempotency-Key': idempotencyKey } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function getContainerInboundPlanPreview(sourceContainerBookingId: string) {
+  const response = await overseasHttp.get<ApiEnvelope<ContainerInboundPlanPreviewDto>, ApiEnvelope<ContainerInboundPlanPreviewDto>>(
+    '/platform/v1/last-leg/inbound-plans/container-preview',
+    { params: { sourceContainerBookingId } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function convertLastMileContainerToInboundPlans(payload: ConvertContainerInboundPlanPayload, idempotencyKey: string) {
+  const response = await overseasHttp.post<ApiEnvelope<InboundPlanDetailDto[]>, ApiEnvelope<InboundPlanDetailDto[]>>(
+    '/platform/v1/last-leg/inbound-plans/convert-container', payload,
+    { headers: { 'Idempotency-Key': idempotencyKey } },
+  )
+  return unwrapApiResponse(response)
+}
diff --git a/src/modules/overseas-warehouse/api/outbounds.test.ts b/src/modules/overseas-warehouse/api/outbounds.test.ts
new file mode 100644
index 00000000..5255dc4f
--- /dev/null
+++ b/src/modules/overseas-warehouse/api/outbounds.test.ts
@@ -0,0 +1,31 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { cancelOutbound, createOneClickDropshipOutbound, getOutbound, listOutbounds } from './outbounds'
+
+vi.mock('@/shared/api/overseasHttp', () => ({ overseasHttp: { get: vi.fn(), post: vi.fn() } }))
+
+describe('outbound overseas API', () => {
+  beforeEach(() => { vi.mocked(overseasHttp.get).mockReset(); vi.mocked(overseasHttp.post).mockReset() })
+
+  it('lists outbound orders with supported filters', async () => {
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', data: { records: [], page: 1, size: 20, total: 0, pages: 0 } })
+    await listOutbounds({ page: 1, size: 20, documentNo: 'OUT-1', warehouseId: 'WH-1', status: 'PICKED' })
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/outbound-orders', { params: { page: 1, size: 20, documentNo: 'OUT-1', warehouseId: 'WH-1', status: 'PICKED' } })
+  })
+
+  it('loads detail and cancels only by outboundNo without customerId', async () => {
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', data: { outbound: { id: '1', outboundNo: 'OUT/1', status: 'PICKED' }, deliveries: [] } })
+    vi.mocked(overseasHttp.post).mockResolvedValue({ code: '200', data: null })
+    await getOutbound('OUT/1')
+    await cancelOutbound('OUT/1', '运营取消')
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/outbound-orders/OUT%2F1')
+    expect(overseasHttp.post).toHaveBeenCalledWith('/platform/v1/last-leg/outbound-orders/OUT%2F1/cancel', { reason: '运营取消' })
+  })
+
+  it('keeps customerId explicit only for one-click dropship creation', async () => {
+    vi.mocked(overseasHttp.post).mockResolvedValue({ code: '200', data: { id: '1', outboundNo: 'OUT-1' } })
+    const payload = { recipient: 'John / 555 / LA', items: [{ inventoryPositionId: '99', packages: 2, sku: 'SKU-1' }], idempotencyKey: 'dropship-1' }
+    await createOneClickDropshipOutbound('customer-1', payload)
+    expect(overseasHttp.post).toHaveBeenCalledWith('/platform/v1/last-leg/outbound-orders/one-click-dropship', payload, { params: { customerId: 'customer-1' } })
+  })
+})
diff --git a/src/modules/overseas-warehouse/api/outbounds.ts b/src/modules/overseas-warehouse/api/outbounds.ts
new file mode 100644
index 00000000..e8cca936
--- /dev/null
+++ b/src/modules/overseas-warehouse/api/outbounds.ts
@@ -0,0 +1,50 @@
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import { normalizeOverseasPage, type OverseasPagePayload } from './lastMileOrders'
+import type { DeliveryOrderRow } from './deliveryOrders'
+
+export interface OutboundRow { id: string; outboundNo: string; dispatchNo?: string | null; overseasWarehouseId?: string | null; lxCodes?: string | null; status?: string | null; palletCount?: number | null; packageCount?: number | null; createdAt?: string | null; outboundType?: string | null }
+export interface OutboundPalletRow {
+  id?: string | null
+  palletNo?: string | null
+  cartonMarks?: string | null
+  inboundCode?: string | null
+  destinationWarehouseCode?: string | null
+  destinationWarehouseName?: string | null
+  skuCode?: string | null
+  packageCount?: number | null
+  pickedPackageCount?: number | null
+  status?: string | null
+}
+export interface OutboundDetail { outbound: OutboundRow; pallets?: OutboundPalletRow[]; deliveries?: DeliveryOrderRow[] }
+export interface OutboundQuery { page: number; size: number; documentNo?: string; lxCode?: string; warehouseId?: string; status?: string; outboundType?: string }
+export interface ReturnOutboundCandidate { returnNo?: string | null; overseasWarehouseId?: string | null; cartonMark?: string | null; fbaCartonMark?: string | null; destinationWarehouseCode?: string | null; destinationWarehouseName?: string | null; totalQuantity?: number | null; status?: string | null }
+export interface OneClickOutboundCandidate { inventoryPositionId: string; orderNo?: string | null; customerId?: string | null; customerName?: string | null; overseasWarehouseId?: string | null; overseasWarehouseName?: string | null; palletNo?: string | null; inboundCode?: string | null; skuCode?: string | null; productName?: string | null; availablePackages: number }
+export async function listOutbounds(query: OutboundQuery) {
+  const response = await overseasHttp.get<ApiEnvelope<OverseasPagePayload<OutboundRow>>, ApiEnvelope<OverseasPagePayload<OutboundRow>>>('/platform/v1/last-leg/outbound-orders', { params: query })
+  return normalizeOverseasPage(unwrapApiResponse(response))
+}
+export async function getOutbound(outboundNo: string) {
+  const response = await overseasHttp.get<ApiEnvelope<OutboundDetail>, ApiEnvelope<OutboundDetail>>(`/platform/v1/last-leg/outbound-orders/${encodeURIComponent(outboundNo)}`)
+  return unwrapApiResponse(response)
+}
+export async function createOneClickDropshipOutbound(customerId: string, payload: { recipient: string; items: Array<{ inventoryPositionId: string; packages: number; sku?: string; cartonMarks?: string[] }>; remark?: string; idempotencyKey: string }) {
+  const response = await overseasHttp.post<ApiEnvelope<OutboundRow>, ApiEnvelope<OutboundRow>>('/platform/v1/last-leg/outbound-orders/one-click-dropship', payload, { params: { customerId } })
+  return unwrapApiResponse(response)
+}
+export async function listOneClickOutboundCandidates(customerId?: string, query: { warehouseId?: string } = {}) {
+  const response = await overseasHttp.get<ApiEnvelope<OneClickOutboundCandidate[]>, ApiEnvelope<OneClickOutboundCandidate[]>>('/platform/v1/last-leg/outbound-orders/one-click-dropship/candidates', { params: { customerId, ...query } })
+  return unwrapApiResponse(response).map((item) => ({ ...item, inventoryPositionId: String(item.inventoryPositionId), availablePackages: Number(item.availablePackages || 0) }))
+}
+export async function listReturnOutboundCandidates(customerId: string, warehouseId: string) {
+  const response = await overseasHttp.get<ApiEnvelope<ReturnOutboundCandidate[]>, ApiEnvelope<ReturnOutboundCandidate[]>>('/platform/v1/last-leg/outbound-orders/return/candidates', { params: { customerId, warehouseId } })
+  return unwrapApiResponse(response)
+}
+export async function createReturnOutbound(customerId: string, payload: { recipient: string; overseasWarehouseId: string; returnNo: string; cartonMarks: string[]; remark?: string; idempotencyKey: string }) {
+  const response = await overseasHttp.post<ApiEnvelope<OutboundRow>, ApiEnvelope<OutboundRow>>('/platform/v1/last-leg/outbound-orders/return', payload, { params: { customerId } })
+  return unwrapApiResponse(response)
+}
+export async function cancelOutbound(outboundNo: string, reason: string) {
+  const response = await overseasHttp.post<ApiEnvelope<null>, ApiEnvelope<null>>(`/platform/v1/last-leg/outbound-orders/${encodeURIComponent(outboundNo)}/cancel`, { reason })
+  return unwrapApiResponse(response)
+}
diff --git a/src/modules/overseas-warehouse/api/palletWarehouseRouting.contract.test.ts b/src/modules/overseas-warehouse/api/palletWarehouseRouting.contract.test.ts
new file mode 100644
index 00000000..e08c1509
--- /dev/null
+++ b/src/modules/overseas-warehouse/api/palletWarehouseRouting.contract.test.ts
@@ -0,0 +1,27 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const source = (relativePath: string) => readFileSync(path.resolve(process.cwd(), relativePath), 'utf8')
+const palletsApi = source('src/modules/overseas-warehouse/api/pallets.ts')
+const palletsPage = source('src/modules/overseas-warehouse/pages/PalletsView.vue')
+const iamApi = source('src/modules/iam/api/platformIam.ts')
+
+describe('Admin pallet warehouse routing contract', () => {
+  it('loads ACTIVE OVERSEAS receiving warehouse candidates from domestic Warehouse only', () => {
+    expect(palletsApi).toContain("import { listSharedReceivingOverseasWarehouseOptions } from '@/modules/iam'")
+    expect(palletsApi).toContain('await listSharedReceivingOverseasWarehouseOptions()')
+    expect(palletsPage).toContain('listReceivingOverseasWarehouses()')
+    expect(iamApi).toContain("'/platform/v1/warehouse-admin'")
+    for (const filter of ["tenantId: '0'", "capabilityCode: 'RECEIVING'", "warehouseType: 'OVERSEAS'", "status: 'ACTIVE'"]) {
+      expect(iamApi).toContain(filter)
+    }
+  })
+
+  it('never calls the nonexistent overseas warehouse-admin root and always scopes pallet calls by warehouseId', () => {
+    expect(palletsApi).not.toMatch(/overseasHttp\.get[^\n]*\(\s*['"]\/platform\/v1\/warehouse-admin['"]/)
+    expect(palletsApi).not.toContain('listCustomerWarehouses')
+    expect(palletsApi).toContain('`/platform/v1/warehouse-admin/${encodeURIComponent(warehouseId)}/pallets`')
+    expect(palletsApi).toContain('`/platform/v1/warehouse-admin/${encodeURIComponent(warehouseId)}/pallets/${encodeURIComponent(palletId)}`')
+  })
+})
diff --git a/src/modules/overseas-warehouse/api/pallets.test.ts b/src/modules/overseas-warehouse/api/pallets.test.ts
new file mode 100644
index 00000000..26bb06b4
--- /dev/null
+++ b/src/modules/overseas-warehouse/api/pallets.test.ts
@@ -0,0 +1,47 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { listSharedReceivingOverseasWarehouseOptions } from '@/modules/iam'
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { createPallet, getPallet, getPalletLabelPdf, listPallets, listReceivingOverseasWarehouses, updatePallet } from './pallets'
+
+vi.mock('@/modules/iam', () => ({ listSharedReceivingOverseasWarehouseOptions: vi.fn() }))
+vi.mock('@/shared/api/overseasHttp', () => ({ overseasHttp: { get: vi.fn(), post: vi.fn(), put: vi.fn() } }))
+
+describe('overseas pallet API', () => {
+  beforeEach(() => { vi.clearAllMocks() })
+
+  it('downloads only the selected pallet through the overseas gateway', async () => {
+    const pdf = new Blob(['%PDF-label'], { type: 'application/pdf' })
+    vi.mocked(overseasHttp.get).mockResolvedValueOnce(pdf)
+    await expect(getPalletLabelPdf('200', '9007199254740993')).resolves.toBe(pdf)
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/warehouse-admin/200/pallets/9007199254740993/label', { responseType: 'blob', timeout: 60_000 })
+  })
+
+  it('surfaces a JSON business failure instead of saving it as a PDF', async () => {
+    const error = new Blob([JSON.stringify({ code: 'A0422', message: '托盘编码不支持打印', requestId: 'r1' })], { type: 'application/json' })
+    vi.mocked(overseasHttp.get).mockResolvedValueOnce(error)
+    await expect(getPalletLabelPdf('200', '9')).rejects.toMatchObject({ message: '托盘编码不支持打印', code: 'A0422', requestId: 'r1' })
+  })
+
+  it('uses the public warehouse scoped pallet CRUD contract', async () => {
+    const page = { records: [], page: 1, size: 20, total: 0, pages: 0 }
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', data: page })
+    vi.mocked(overseasHttp.post).mockResolvedValue({ code: '200', data: '9' })
+    vi.mocked(overseasHttp.put).mockResolvedValue({ code: '200', data: null })
+    vi.mocked(listSharedReceivingOverseasWarehouseOptions).mockResolvedValue([{ id: '200', warehouseCode: 'LAX', warehouseName: '洛杉矶仓', countryCode: 'US' }])
+    const payload = { palletCode: 'PLT-NEW', palletType: 'WOOD', fbaWarehouseCode: 'ABE3', capacityCbm: 2, unitPrice: 10, status: 'IDLE' }
+
+    await expect(listReceivingOverseasWarehouses()).resolves.toMatchObject({ records: [{ id: '200', customerId: '0', warehouseCode: 'LAX', warehouseType: 'OVERSEAS', status: 'ACTIVE' }] })
+    await listPallets('200', { page: 1, size: 20, keyword: 'PLT' })
+    await getPallet('200', '9')
+    await createPallet('200', payload)
+    await updatePallet('200', '9', { ...payload, version: 7 })
+
+    expect(listSharedReceivingOverseasWarehouseOptions).toHaveBeenCalledOnce()
+    expect(overseasHttp.get).toHaveBeenNthCalledWith(1, '/platform/v1/warehouse-admin/200/pallets', { params: { page: 1, size: 20, keyword: 'PLT' } })
+    expect(overseasHttp.get).toHaveBeenNthCalledWith(2, '/platform/v1/warehouse-admin/200/pallets/9', {})
+    expect(overseasHttp.post).toHaveBeenCalledWith('/platform/v1/warehouse-admin/200/pallets', payload)
+    expect(overseasHttp.put).toHaveBeenCalledWith('/platform/v1/warehouse-admin/200/pallets/9', { ...payload, version: 7 })
+    expect(overseasHttp.put).toHaveBeenCalledWith('/platform/v1/warehouse-admin/200/pallets/9', expect.objectContaining({ palletCode: 'PLT-NEW', fbaWarehouseCode: 'ABE3', status: 'IDLE', version: 7 }))
+    expect(overseasHttp.post).toHaveBeenCalledWith('/platform/v1/warehouse-admin/200/pallets', expect.not.objectContaining({ version: expect.anything() }))
+  })
+})
diff --git a/src/modules/overseas-warehouse/api/pallets.ts b/src/modules/overseas-warehouse/api/pallets.ts
new file mode 100644
index 00000000..abc0218a
--- /dev/null
+++ b/src/modules/overseas-warehouse/api/pallets.ts
@@ -0,0 +1,104 @@
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import { listSharedReceivingOverseasWarehouseOptions } from '@/modules/iam'
+import { normalizeOverseasPage, type OverseasPagePayload } from './lastMileOrders'
+
+export interface ReceivingOverseasWarehouseDto {
+  id: string
+  customerId: string
+  warehouseCode: string
+  warehouseName: string
+  warehouseType: string
+  status: string
+}
+
+export interface PalletDto {
+  id: string
+  customerId: string
+  warehouseId: string
+  locationId?: string | null
+  palletCode: string
+  palletType: string
+  fbaWarehouseCode: string
+  capacityCbm: number
+  unitPrice: number
+  status: string
+  remark?: string | null
+  version: number
+  createdAt?: string | null
+  updatedAt?: string | null
+}
+
+export interface SavePalletPayload {
+  palletCode: string
+  palletType: string
+  fbaWarehouseCode: string
+  capacityCbm: number
+  unitPrice: number
+  status: string
+  locationId?: string | null
+  remark?: string | null
+}
+
+export interface UpdatePalletPayload extends SavePalletPayload {
+  version: number
+}
+export interface PalletSummaryDto { totalCount: number; idleCount: number; occupiedCount: number; scrappedCount: number }
+
+export async function listReceivingOverseasWarehouses() {
+  const records: ReceivingOverseasWarehouseDto[] = (await listSharedReceivingOverseasWarehouseOptions()).map((warehouse) => ({
+    id: warehouse.id,
+    customerId: '0',
+    warehouseCode: warehouse.warehouseCode,
+    warehouseName: warehouse.warehouseName,
+    warehouseType: 'OVERSEAS',
+    status: 'ACTIVE',
+  }))
+  return { records, page: 1, size: 200, total: records.length, pages: records.length ? 1 : 0 }
+}
+
+export async function listPallets(warehouseId: string | undefined, query: { page: number; size: number; keyword?: string; palletType?: string; status?: string }) {
+  const response = await overseasHttp.get<ApiEnvelope<OverseasPagePayload<PalletDto>>, ApiEnvelope<OverseasPagePayload<PalletDto>>>(
+    warehouseId ? `/platform/v1/warehouse-admin/${encodeURIComponent(warehouseId)}/pallets` : '/platform/v1/warehouse-admin/pallets',
+    { params: { ...query } },
+  )
+  return normalizeOverseasPage(unwrapApiResponse(response))
+}
+export async function getPalletSummary(warehouseId: string, query: { keyword?: string; palletType?: string }) {
+  const path = warehouseId ? `/platform/v1/warehouse-admin/${encodeURIComponent(warehouseId)}/pallets/summary` : '/platform/v1/warehouse-admin/pallets/summary'
+  const response = await overseasHttp.get<ApiEnvelope<PalletSummaryDto>, ApiEnvelope<PalletSummaryDto>>(path, { params: { page: 1, size: 1, ...query } })
+  const value = unwrapApiResponse(response); return { totalCount: Number(value.totalCount), idleCount: Number(value.idleCount), occupiedCount: Number(value.occupiedCount), scrappedCount: Number(value.scrappedCount) }
+}
+
+export async function getPallet(warehouseId: string, palletId: string) {
+  const response = await overseasHttp.get<ApiEnvelope<PalletDto>, ApiEnvelope<PalletDto>>(
+    `/platform/v1/warehouse-admin/${encodeURIComponent(warehouseId)}/pallets/${encodeURIComponent(palletId)}`,
+    {},
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function getPalletLabelPdf(warehouseId: string, palletId: string) {
+  const blob = await overseasHttp.get<Blob, Blob>(
+    `/platform/v1/warehouse-admin/${encodeURIComponent(warehouseId)}/pallets/${encodeURIComponent(palletId)}/label`,
+    { responseType: 'blob', timeout: 60_000 },
+  )
+  if (blob.type.includes('application/json')) unwrapApiResponse(JSON.parse(await blob.text()) as ApiEnvelope<unknown>)
+  if (!blob.size || !blob.type.includes('application/pdf')) throw new Error('打印服务未返回有效 PDF，请重试')
+  return blob
+}
+
+export async function createPallet(warehouseId: string, payload: SavePalletPayload) {
+  const response = await overseasHttp.post<ApiEnvelope<string>, ApiEnvelope<string>>(
+    `/platform/v1/warehouse-admin/${encodeURIComponent(warehouseId)}/pallets`, payload,
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function updatePallet(warehouseId: string, palletId: string, payload: UpdatePalletPayload) {
+  const response = await overseasHttp.put<ApiEnvelope<null>, ApiEnvelope<null>>(
+    `/platform/v1/warehouse-admin/${encodeURIComponent(warehouseId)}/pallets/${encodeURIComponent(palletId)}`,
+    payload,
+  )
+  return unwrapApiResponse(response)
+}
diff --git a/src/modules/overseas-warehouse/api/relabelOrders.test.ts b/src/modules/overseas-warehouse/api/relabelOrders.test.ts
new file mode 100644
index 00000000..ba328e35
--- /dev/null
+++ b/src/modules/overseas-warehouse/api/relabelOrders.test.ts
@@ -0,0 +1,45 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { listSharedReceivingOverseasWarehouseOptions } from '@/modules/iam'
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { changeRelabelOrderStatus, createRelabelOrder, getRelabelOrder, listRelabelOrders, listRelabelWarehouseOptions } from './relabelOrders'
+
+vi.mock('@/modules/iam', () => ({ listSharedReceivingOverseasWarehouseOptions: vi.fn() }))
+vi.mock('@/shared/api/overseasHttp', () => ({ overseasHttp: { get: vi.fn(), post: vi.fn(), put: vi.fn() } }))
+
+describe('relabel overseas API', () => {
+  beforeEach(() => {
+    vi.mocked(overseasHttp.get).mockReset()
+    vi.mocked(overseasHttp.post).mockReset()
+    vi.mocked(overseasHttp.put).mockReset()
+    vi.mocked(listSharedReceivingOverseasWarehouseOptions).mockReset()
+  })
+
+  it('uses the platform page endpoint without customer scope', async () => {
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', message: 'success', data: { records: [], page: 1, size: 20, total: 0, pages: 0 } })
+    await listRelabelOrders({ page: 1, size: 20, skuCode: 'SKU-1' })
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/relabel-applications', { params: { page: 1, size: 20, skuCode: 'SKU-1' } })
+  })
+
+  it('encodes the relabel number and does not call a mutation endpoint', async () => {
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', message: 'success', data: { application: { id: '1', relabelNo: 'RL/1' }, items: [], history: [] } })
+    await getRelabelOrder('RL/1')
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/relabel-applications/RL%2F1')
+  })
+
+  it('uses the real create and status endpoints', async () => {
+    vi.mocked(overseasHttp.post).mockResolvedValue({ code: '200', data: {} })
+    vi.mocked(overseasHttp.put).mockResolvedValue({ code: '200', data: {} })
+    const payload = { customerOrderNo: 'CO-1', overseasWarehouseId: '9', labelDeadline: '2026-08-20T10:00:00', contactName: 'A', contactPhone: '1', chargeAmount: 20, idempotencyKey: 'k', items: [{ skuCode: 'SKU', productNameZh: 'P', totalPackageCount: 1, notifiedPackageCount: 1, shipmentNo: 'S', newSkuCode: 'SKU-2' }] }
+    await createRelabelOrder('10001', payload)
+    await changeRelabelOrderStatus('RL/1', 'PROCESSING', 'ok')
+    expect(overseasHttp.post).toHaveBeenCalledWith('/platform/v1/last-leg/relabel-applications', payload, { params: { customerId: '10001' } })
+    expect(overseasHttp.put).toHaveBeenCalledWith('/platform/v1/last-leg/relabel-applications/RL%2F1/status', { status: 'PROCESSING', remark: 'ok' })
+  })
+
+  it('loads shared ACTIVE OVERSEAS RECEIVING warehouses from the domestic candidate contract', async () => {
+    vi.mocked(listSharedReceivingOverseasWarehouseOptions).mockResolvedValue([{ id: '200', warehouseCode: 'LAX', warehouseName: '洛杉矶仓', countryCode: 'US' }])
+    await expect(listRelabelWarehouseOptions()).resolves.toMatchObject({ records: [{ id: '200', customerId: '0', warehouseType: 'OVERSEAS', status: 'ACTIVE' }] })
+    expect(listSharedReceivingOverseasWarehouseOptions).toHaveBeenCalledOnce()
+    expect(overseasHttp.get).not.toHaveBeenCalledWith('/platform/v1/warehouse-admin', expect.anything())
+  })
+})
diff --git a/src/modules/overseas-warehouse/api/relabelOrders.ts b/src/modules/overseas-warehouse/api/relabelOrders.ts
new file mode 100644
index 00000000..2a284697
--- /dev/null
+++ b/src/modules/overseas-warehouse/api/relabelOrders.ts
@@ -0,0 +1,192 @@
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import { listSharedReceivingOverseasWarehouseOptions } from '@/modules/iam'
+import { normalizeOverseasPage, type OverseasPagePayload } from './lastMileOrders'
+
+export interface RelabelOrderQuery {
+  page: number
+  size: number
+  relabelNo?: string
+  skuCode?: string
+  status?: string
+}
+
+export interface CreateRelabelItemPayload {
+  skuCode: string
+  productNameZh: string
+  totalPackageCount: number
+  notifiedPackageCount: number
+  shipmentNo: string
+  newSkuCode: string
+  labelRequirement?: string
+  productImageFileId?: string
+  productImageFileName?: string
+  productImageUrl?: string
+  trackingCode?: string
+  relabelFileId?: string
+  relabelFileName?: string
+  relabelFileUrl?: string
+}
+
+export interface CreateRelabelPayload {
+  customerOrderNo: string
+  overseasWarehouseId: string
+  labelDeadline: string
+  contactName: string
+  contactPhone: string
+  chargeAmount: number
+  remark?: string
+  idempotencyKey: string
+  items: CreateRelabelItemPayload[]
+}
+
+export interface RelabelWarehouseOptionDto {
+  id: string
+  customerId: string
+  warehouseCode: string
+  warehouseName: string
+  warehouseType: string
+  status: string
+}
+
+export interface RelabelSummaryDto {
+  id: string
+  relabelNo: string
+  lastlegOrderId?: string | null
+  lastlegOrderNo?: string | null
+  customerOrderNo?: string | null
+  overseasWarehouseId?: string | null
+  labelDeadline?: string | null
+  contactName?: string | null
+  contactPhone?: string | null
+  status?: string | null
+  itemCount?: number | null
+  totalPackageCount?: number | null
+  notifiedPackageCount?: number | null
+  skuCodes?: string | null
+  totalFileId?: string | null
+  totalFileName?: string | null
+  totalFileUrl?: string | null
+  chargeAmount?: number | string | null
+  chargeCurrency?: string | null
+  walletStatus?: string | null
+  walletErrorMessage?: string | null
+  deliveryMethod?: string | null
+  printShippingLabel?: boolean | null
+  shippingLabelFileId?: string | null
+  shippingLabelFileName?: string | null
+  fulfillmentStatus?: string | null
+  outboundOrderNo?: string | null
+  customerConfirmedAt?: string | null
+  createdAt?: string | null
+}
+
+export interface RelabelItemDto {
+  id: string
+  skuCode?: string | null
+  productNameZh?: string | null
+  totalPackageCount?: number | null
+  notifiedPackageCount?: number | null
+  newSkuCode?: string | null
+  labelRequirement?: string | null
+  relabelFileId?: string | null
+  relabelFileName?: string | null
+  relabelFileUrl?: string | null
+  shipmentNo?: string | null
+  trackingCode?: string | null
+  remark?: string | null
+  cartonMark?: string | null
+  fbaCartonMark?: string | null
+  destinationWarehouseId?: string | null
+}
+
+export interface RelabelHistoryDto {
+  fromStatus?: string | null
+  toStatus?: string | null
+  operatorId?: string | null
+  remark?: string | null
+  createdAt?: string | null
+}
+
+export interface RelabelDetailDto {
+  application: RelabelSummaryDto
+  remark?: string | null
+  items: RelabelItemDto[]
+  history: RelabelHistoryDto[]
+  completionEvidence?: { taskId: string; photoFileIds: string[]; completionRemark?: string | null; reviewerName?: string | null; reviewRemark?: string | null; completedAt?: string | null } | null
+}
+
+export async function listRelabelOrders(query: RelabelOrderQuery) {
+  const response = await overseasHttp.get<ApiEnvelope<OverseasPagePayload<RelabelSummaryDto>>, ApiEnvelope<OverseasPagePayload<RelabelSummaryDto>>>(
+    '/platform/v1/last-leg/relabel-applications', { params: query },
+  )
+  return normalizeOverseasPage(unwrapApiResponse(response))
+}
+
+export async function getRelabelOrder(relabelNo: string) {
+  const response = await overseasHttp.get<ApiEnvelope<RelabelDetailDto>, ApiEnvelope<RelabelDetailDto>>(
+    `/platform/v1/last-leg/relabel-applications/${encodeURIComponent(relabelNo)}`,
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function listRelabelWarehouseOptions() {
+  const records: RelabelWarehouseOptionDto[] = (await listSharedReceivingOverseasWarehouseOptions()).map((warehouse) => ({
+    id: warehouse.id,
+    customerId: '0',
+    warehouseCode: warehouse.warehouseCode,
+    warehouseName: warehouse.warehouseName,
+    warehouseType: 'OVERSEAS',
+    status: 'ACTIVE',
+  }))
+  return { records, page: 1, size: 200, total: records.length, pages: records.length ? 1 : 0 }
+}
+
+export async function createRelabelOrder(customerId: string, payload: CreateRelabelPayload) {
+  const response = await overseasHttp.post<ApiEnvelope<RelabelDetailDto>, ApiEnvelope<RelabelDetailDto>>(
+    '/platform/v1/last-leg/relabel-applications', payload, { params: { customerId } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function changeRelabelOrderStatus(relabelNo: string, status: string, remark?: string) {
+  const response = await overseasHttp.put<ApiEnvelope<RelabelDetailDto>, ApiEnvelope<RelabelDetailDto>>(
+    `/platform/v1/last-leg/relabel-applications/${encodeURIComponent(relabelNo)}/status`,
+    { status, remark },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function getRelabelReviewTask(relabelNo: string) {
+  const response = await overseasHttp.get<ApiEnvelope<{ version: number; taskStatus: string }>, ApiEnvelope<{ version: number; taskStatus: string }>>(`/platform/v1/last-leg/relabel-applications/${encodeURIComponent(relabelNo)}/review-task`)
+  return unwrapApiResponse(response)
+}
+
+export async function returnRelabelForRework(relabelNo: string, expectedVersion: number, remark: string, idempotencyKey: string) {
+  const response = await overseasHttp.post<ApiEnvelope<unknown>, ApiEnvelope<unknown>>(`/platform/v1/last-leg/relabel-applications/${encodeURIComponent(relabelNo)}/rework`, { decision: 'REWORK', expectedVersion, remark, idempotencyKey })
+  return unwrapApiResponse(response)
+}
+
+export async function uploadRelabelPdf(relabelNo: string, file: File, scope: 'TOTAL' | 'ITEM', itemId?: string) {
+  const body = new FormData()
+  body.append('file', file)
+  const response = await overseasHttp.post<ApiEnvelope<RelabelDetailDto>, ApiEnvelope<RelabelDetailDto>>(
+    `/platform/v1/last-leg/relabel-applications/${encodeURIComponent(relabelNo)}/files`, body,
+    { params: { scope, itemId }, headers: { 'Content-Type': 'multipart/form-data' } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function downloadRelabelPdf(relabelNo: string, fileId: string, scope: 'TOTAL' | 'ITEM', itemId?: string) {
+  return overseasHttp.get<Blob, Blob>(
+    `/platform/v1/last-leg/relabel-applications/${encodeURIComponent(relabelNo)}/files/${encodeURIComponent(fileId)}/download`,
+    { params: { scope, itemId }, responseType: 'blob' },
+  )
+}
+
+export async function downloadRelabelCompletionPhoto(relabelNo: string, fileId: string) {
+  return overseasHttp.get<Blob, Blob>(
+    `/platform/v1/last-leg/relabel-applications/${encodeURIComponent(relabelNo)}/completion-photos/${encodeURIComponent(fileId)}/download`,
+    { responseType: 'blob' },
+  )
+}
diff --git a/src/modules/overseas-warehouse/api/returnInventory.ts b/src/modules/overseas-warehouse/api/returnInventory.ts
new file mode 100644
index 00000000..05b1ef14
--- /dev/null
+++ b/src/modules/overseas-warehouse/api/returnInventory.ts
@@ -0,0 +1,16 @@
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import { normalizeOverseasPage, type OverseasPagePayload } from './lastMileOrders'
+
+export interface ReturnStockRow { customerId: string; overseasWarehouseId: string; skuCode: string; productNameZh?: string; totalQuantity: number; availableQuantity: number; cartonQuantity: number; updatedAt: string }
+export interface ReturnCartonRow { customerId: string; overseasWarehouseId: string; cartonMark: string; sourceReturnNo?: string; sourceBatchNo?: string; status: string; fbaCartonMark?: string; destinationWarehouseCode?: string; destinationWarehouseName?: string; relabelNo?: string; relabelStatus?: string; skuTypes: number; totalQuantity: number; length?: number; width?: number; height?: number; weight?: number; createdAt: string }
+export interface ReturnCartonDetail extends ReturnCartonRow { customerId: string; items: Array<{ skuCode: string; productNameZh?: string; quantity: number }> }
+export interface ReturnCartonLabel extends ReturnCartonDetail { printableHtml: string }
+export interface ReturnInventoryMovement { customerId: string; overseasWarehouseId: string; skuCode: string; productNameZh?: string; movementType: 'RECEIPT' | 'MERGE' | 'OUTBOUND'; referenceNo: string; totalDelta: number; availableDelta: number; occurredAt: string }
+export interface ReturnInventoryQuery { page: number; size: number; customerId?: string; overseasWarehouseId?: string; skuCode?: string; cartonMark?: string; returnNo?: string; status?: string }
+
+export async function listReturnStock(params: ReturnInventoryQuery) { const response = await overseasHttp.get<ApiEnvelope<OverseasPagePayload<ReturnStockRow>>, ApiEnvelope<OverseasPagePayload<ReturnStockRow>>>('/platform/v1/last-leg/return-inventory', { params }); return normalizeOverseasPage(unwrapApiResponse(response)) }
+export async function listReturnCartons(params: ReturnInventoryQuery) { const response = await overseasHttp.get<ApiEnvelope<OverseasPagePayload<ReturnCartonRow>>, ApiEnvelope<OverseasPagePayload<ReturnCartonRow>>>('/platform/v1/last-leg/return-inventory/cartons', { params }); return normalizeOverseasPage(unwrapApiResponse(response)) }
+export async function listReturnInventoryMovements(params: ReturnInventoryQuery) { const response = await overseasHttp.get<ApiEnvelope<OverseasPagePayload<ReturnInventoryMovement>>, ApiEnvelope<OverseasPagePayload<ReturnInventoryMovement>>>('/platform/v1/last-leg/return-inventory/movements', { params }); return normalizeOverseasPage(unwrapApiResponse(response)) }
+export async function getReturnCarton(cartonMark: string) { const response = await overseasHttp.get<ApiEnvelope<ReturnCartonDetail>, ApiEnvelope<ReturnCartonDetail>>(`/platform/v1/last-leg/return-inventory/cartons/${encodeURIComponent(cartonMark)}`); return unwrapApiResponse(response) }
+export async function getReturnCartonLabel(cartonMark: string) { const response = await overseasHttp.get<ApiEnvelope<ReturnCartonLabel>, ApiEnvelope<ReturnCartonLabel>>(`/platform/v1/last-leg/return-inventory/cartons/${encodeURIComponent(cartonMark)}/label`); return unwrapApiResponse(response) }
diff --git a/src/modules/overseas-warehouse/api/warehouseTransfers.test.ts b/src/modules/overseas-warehouse/api/warehouseTransfers.test.ts
new file mode 100644
index 00000000..ab84f311
--- /dev/null
+++ b/src/modules/overseas-warehouse/api/warehouseTransfers.test.ts
@@ -0,0 +1,28 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { getWarehouseTransfer, listWarehouseTransfers, reviewWarehouseTransfer } from './warehouseTransfers'
+
+vi.mock('@/shared/api/overseasHttp', () => ({ overseasHttp: { get: vi.fn(), post: vi.fn() } }))
+
+describe('warehouseTransfers API', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it('always scopes platform list and detail requests to the selected customer', async () => {
+    vi.mocked(overseasHttp.get).mockResolvedValueOnce({ code: '200', data: { records: [], page: 1, size: 10, total: 0, pages: 0 } })
+    vi.mocked(overseasHttp.get).mockResolvedValueOnce({ code: '200', data: { transferNo: 'WT-1', items: [], cartons: [], relabelBindings: [] } })
+    await listWarehouseTransfers('20001', { page: 1, size: 10, status: 'PENDING_REVIEW' })
+    await getWarehouseTransfer('20001', 'WT-1')
+    expect(vi.mocked(overseasHttp.get).mock.calls[0]).toEqual(['/platform/v1/last-leg/warehouse-transfers', { params: { page: 1, size: 10, status: 'PENDING_REVIEW', customerId: '20001' } }])
+    expect(vi.mocked(overseasHttp.get).mock.calls[1]).toEqual(['/platform/v1/last-leg/warehouse-transfers/WT-1', { params: { customerId: '20001' } }])
+  })
+
+  it('posts the real review decision with customer scope', async () => {
+    vi.mocked(overseasHttp.post).mockResolvedValue({ code: '200', data: { transferNo: 'WT-1', items: [], cartons: [], relabelBindings: [] } })
+    await reviewWarehouseTransfer('20001', 'WT-1', 'APPROVE', '资料无误')
+    expect(overseasHttp.post).toHaveBeenCalledWith(
+      '/platform/v1/last-leg/warehouse-transfers/WT-1/review',
+      { decision: 'APPROVE', remark: '资料无误' },
+      { params: { customerId: '20001' } },
+    )
+  })
+})
diff --git a/src/modules/overseas-warehouse/api/warehouseTransfers.ts b/src/modules/overseas-warehouse/api/warehouseTransfers.ts
new file mode 100644
index 00000000..10407f11
--- /dev/null
+++ b/src/modules/overseas-warehouse/api/warehouseTransfers.ts
@@ -0,0 +1,117 @@
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import { normalizeOverseasPage, type OverseasPagePayload } from './lastMileOrders'
+
+export interface WarehouseTransferQuery {
+  page: number
+  size: number
+  transferNo?: string
+  operatingWarehouseId?: string
+  fbaWarehouseCode?: string
+  status?: string
+  needRelabel?: boolean
+}
+
+export interface WarehouseTransferSummaryDto {
+  id: string
+  transferNo: string
+  inboundCode?: string | null
+  lastlegOrderId?: string | null
+  lastlegOrderNo?: string | null
+  operatingWarehouseId?: string | null
+  fbaWarehouseCode?: string | null
+  packageCount: number
+  deliveryMethod?: string | null
+  needRelabel: boolean
+  relabelNo?: string | null
+  status: string
+  estimatedArrivalAt?: string | null
+  createdAt?: string | null
+}
+
+export interface WarehouseTransferItemDto {
+  id: string
+  skuCode: string
+  productNameZh: string
+  packageCount: number
+  shippingMark?: string | null
+}
+
+export interface WarehouseTransferCartonDto {
+  cartonMark?: string | null
+  customerCartonMark?: string | null
+  cartonIndex: number
+  totalCartons: number
+  status: string
+}
+
+export interface WarehouseTransferRelabelBindingDto {
+  operationType: string
+  customerCartonMark: string
+  originalSku: string
+  newSku?: string | null
+  quantity: number
+  fbaCartonMark?: string | null
+  destinationWarehouseCode?: string | null
+  remark?: string | null
+}
+
+export interface WarehouseTransferPalletDto {
+  id: string
+  sequenceNo: number
+  palletNo?: string | null
+  cartonCount: number
+  grossWeightKg: number
+  volumeCbm: number
+  status: string
+}
+
+export interface WarehouseTransferDetailDto extends WarehouseTransferSummaryDto {
+  inboundOrderId?: string | null
+  orderType?: string | null
+  orderStatus?: string | null
+  relabelApplicationId?: string | null
+  relabelStatus?: string | null
+  deliveryAddress?: string | null
+  estimatedShipAt?: string | null
+  fbaShipmentNo?: string | null
+  trackingNo?: string | null
+  fbaBoxNos?: string | null
+  remark?: string | null
+  items: WarehouseTransferItemDto[]
+  cartons: WarehouseTransferCartonDto[]
+  pallets: WarehouseTransferPalletDto[]
+  relabelBindings: WarehouseTransferRelabelBindingDto[]
+  customerConfirmedAt?: string | null
+  actualShipAt?: string | null
+}
+
+export async function listWarehouseTransfers(customerId: string, query: WarehouseTransferQuery) {
+  const response = await overseasHttp.get<ApiEnvelope<OverseasPagePayload<WarehouseTransferSummaryDto>>, ApiEnvelope<OverseasPagePayload<WarehouseTransferSummaryDto>>>(
+    '/platform/v1/last-leg/warehouse-transfers',
+    { params: { ...query, customerId } },
+  )
+  return normalizeOverseasPage(unwrapApiResponse(response))
+}
+
+export async function getWarehouseTransfer(customerId: string, transferNo: string) {
+  const response = await overseasHttp.get<ApiEnvelope<WarehouseTransferDetailDto>, ApiEnvelope<WarehouseTransferDetailDto>>(
+    `/platform/v1/last-leg/warehouse-transfers/${encodeURIComponent(transferNo)}`,
+    { params: { customerId } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function reviewWarehouseTransfer(
+  customerId: string,
+  transferNo: string,
+  decision: 'APPROVE' | 'REJECT',
+  remark?: string,
+) {
+  const response = await overseasHttp.post<ApiEnvelope<WarehouseTransferDetailDto>, ApiEnvelope<WarehouseTransferDetailDto>>(
+    `/platform/v1/last-leg/warehouse-transfers/${encodeURIComponent(transferNo)}/review`,
+    { decision, remark },
+    { params: { customerId } },
+  )
+  return unwrapApiResponse(response)
+}
diff --git a/src/modules/overseas-warehouse/components/ContractPendingFormDialog.vue b/src/modules/overseas-warehouse/components/ContractPendingFormDialog.vue
new file mode 100644
index 00000000..19a8d1f9
--- /dev/null
+++ b/src/modules/overseas-warehouse/components/ContractPendingFormDialog.vue
@@ -0,0 +1,29 @@
+<script setup lang="ts">
+import AppDialog from '@/shared/components/AppDialog.vue'
+
+withDefaults(defineProps<{
+  title: string
+  width: string
+  domain: string
+  confirmText?: string
+}>(), {
+  confirmText: '保存',
+})
+
+const open = defineModel<boolean>({ default: false })
+</script>
+
+<template>
+  <AppDialog v-model="open" :title="title" :width="width" :confirm-text="confirmText" confirm-disabled>
+    <el-alert type="warning" :closable="false" show-icon :title="`${domain}写接口待接入`">
+      <p>弹框按原型保留字段与尺寸；端点、状态机和幂等契约冻结前不可提交，也不会在本地模拟保存成功。</p>
+    </el-alert>
+    <div class="pending-form"><slot /></div>
+  </AppDialog>
+</template>
+
+<style scoped>
+.pending-form { margin-top: 16px; }
+.pending-form :deep(.el-select), .pending-form :deep(.el-input-number) { width: 100%; }
+.pending-form :deep(.el-alert p) { margin: 0; }
+</style>
diff --git a/src/modules/overseas-warehouse/components/ContractPendingNotice.vue b/src/modules/overseas-warehouse/components/ContractPendingNotice.vue
new file mode 100644
index 00000000..b42eb653
--- /dev/null
+++ b/src/modules/overseas-warehouse/components/ContractPendingNotice.vue
@@ -0,0 +1,14 @@
+<script setup lang="ts">
+defineProps<{ domain: string }>()
+</script>
+
+<template>
+  <el-alert class="contract-pending" type="warning" :closable="false" show-icon>
+    <template #title>{{ domain }}海外区域接口待接入</template>
+    <p>后端边界已固定为 gateway-overseas → lastleg-service / warehouse-overseas-service；统一海外 Base/Token 选择及本页面端点、DTO 与权限适配完成前，不展示演示数据，也不会模拟查询或写操作成功。</p>
+  </el-alert>
+</template>
+
+<style scoped>
+.contract-pending p { margin: 5px 0 0; color: var(--el-text-color-regular); font-size: 13px; line-height: 1.55; }
+</style>
diff --git a/src/modules/overseas-warehouse/components/DeliveryDocumentsDialog.test.ts b/src/modules/overseas-warehouse/components/DeliveryDocumentsDialog.test.ts
new file mode 100644
index 00000000..17b97822
--- /dev/null
+++ b/src/modules/overseas-warehouse/components/DeliveryDocumentsDialog.test.ts
@@ -0,0 +1,191 @@
+import ElementPlus, { ElMessage } from 'element-plus'
+import { defineComponent, h } from 'vue'
+import { DOMWrapper, flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import DeliveryDocumentsDialog from './DeliveryDocumentsDialog.vue'
+import { commonPhase5Stubs } from '../pages/phase5TestStubs'
+import { deliveryDocumentCategories, getDeliveryDocuments, saveDeliveryDocuments, uploadDeliveryDocument, type DeliveryDocuments } from '../api/deliveryDocuments'
+const can = vi.hoisted(() => vi.fn(() => true))
+vi.mock('@/core/access/accessPreview', () => ({ useAccessPreviewStore: () => ({ can }) }))
+vi.mock('../api/deliveryDocuments', async importOriginal => ({ ...await importOriginal<typeof import('../api/deliveryDocuments')>(), getDeliveryDocuments: vi.fn(), saveDeliveryDocuments: vi.fn(), uploadDeliveryDocument: vi.fn(), downloadDeliveryDocument: vi.fn() }))
+const dialogStub = defineComponent({
+  name: 'AppDialog', props: ['modelValue', 'showConfirm', 'confirmDisabled'], emits: ['confirm', 'update:modelValue'],
+  setup(props, { slots, emit }) { return () => props.modelValue ? h('section', [slots.default?.(), props.showConfirm ? h('button', { class: 'save', disabled: props.confirmDisabled, onClick: () => emit('confirm') }, '保存资料') : null, h('button', { class: 'close', onClick: () => emit('update:modelValue', false) }, '关闭')]) : null },
+})
+const uploadStub = defineComponent({
+  name: 'ElUpload', props: ['onChange', 'disabled'],
+  setup(props, { slots }) { return () => h('label', [slots.default?.(), h('input', { type: 'file', disabled: props.disabled, onChange: (event: Event) => props.onChange({ raw: (event.target as HTMLInputElement).files?.[0] }) })]) },
+})
+const originalFile = { fileId: '9007199254740995', fileName: 'original.pdf', contentType: 'application/pdf', sizeBytes: 4, uploadedAt: '2026-09-09T09:00:00' }
+function response(): DeliveryDocuments {
+  return { deliveryNo: 'DL/1', customerId: '100', version: 9, bolNo: 'BOL-1', uploadedCategoryCount: 1, totalCategoryCount: 3, allowedActions: ['MANAGE_DOCUMENTS'], replayed: false, categories: deliveryDocumentCategories.map(item => ({ category: item.category, status: item.category === 'BOL' ? 'UPLOADED' : 'MISSING', fileCount: item.category === 'BOL' ? 1 : 0, files: item.category === 'BOL' ? [{ ...originalFile }] : [] })) }
+}
+function mountDialog() {
+  const wrapper = mount(DeliveryDocumentsDialog, { props: { modelValue: true, deliveryNo: 'DL/1', customerId: '100' }, global: { plugins: [ElementPlus], stubs: { ...commonPhase5Stubs, AppDialog: dialogStub, ElUpload: uploadStub } } })
+  return wrapper
+}
+async function choose(input: ReturnType<ReturnType<typeof mountDialog>['find']>, file: File) {
+  Object.defineProperty(input.element, 'files', { value: [file], configurable: true })
+  await input.trigger('change'); await flushPromises()
+}
+describe('delivery document drafts', () => {
+  beforeEach(() => {
+    can.mockReset().mockReturnValue(true)
+    vi.mocked(getDeliveryDocuments).mockReset().mockResolvedValue(response())
+    vi.mocked(saveDeliveryDocuments).mockReset().mockResolvedValue(response())
+    vi.mocked(uploadDeliveryDocument).mockReset().mockResolvedValue({ ...originalFile, fileId: '9007199254740996', fileName: 'new.pdf' })
+  })
+  it('loads once and stages replacement and deletion until a full versioned save', async () => {
+    const wrapper = mountDialog(); await flushPromises()
+    expect(getDeliveryDocuments).toHaveBeenCalledTimes(1)
+    expect(wrapper.text()).toContain('1/3 已上传')
+    await choose(wrapper.find('[data-category="BOL"] .document-file input[type="file"]'), new File(['next'], 'new.pdf'))
+    expect(saveDeliveryDocuments).not.toHaveBeenCalled()
+    expect(wrapper.text()).not.toContain('original.pdf')
+    expect(wrapper.text()).toContain('new.pdf')
+    await wrapper.find('[data-category="BOL"] .document-file').findAll('button').find(button => button.text() === '删除')!.trigger('click')
+    expect(wrapper.text()).toContain('0/3 已上传')
+    await wrapper.find('.save').trigger('click'); await flushPromises()
+    expect(saveDeliveryDocuments).toHaveBeenCalledWith('DL/1', '100', { expectedVersion: 9, idempotencyKey: expect.any(String), bolNo: 'BOL-1', documents: deliveryDocumentCategories.map(item => ({ category: item.category, fileIds: [] })) })
+    expect(wrapper.emitted('saved')).toHaveLength(1)
+    wrapper.unmount()
+  })
+  it('uses real upload controls to add, replace, delete and reload the saved three-category snapshot', async () => {
+    const success = vi.spyOn(ElMessage, 'success')
+    const receipt = { ...originalFile, fileId: 'receipt-1', fileName: 'pod.pdf' }
+    const courier = { ...originalFile, fileId: 'receipt-2', fileName: 'courier.pdf' }
+    const replacement = { ...originalFile, fileId: 'bol-2', fileName: 'signed-bol.pdf' }
+    vi.mocked(uploadDeliveryDocument).mockResolvedValueOnce(receipt).mockResolvedValueOnce(courier).mockResolvedValueOnce(replacement)
+    const wrapper = mount(DeliveryDocumentsDialog, { attachTo: document.body, props: { modelValue: true, deliveryNo: 'DL/1', customerId: '100' }, global: { plugins: [ElementPlus] } })
+    const body = new DOMWrapper(document.body)
+    try {
+      await flushPromises()
+      const dialog = body.find('[role="dialog"]')
+      expect(dialog.findAll('[data-category]')).toHaveLength(3)
+      await choose(dialog.find('[data-category="RECEIPT"] header input[type="file"]'), new File(['pod'], 'pod.pdf'))
+      await choose(dialog.find('[data-category="RECEIPT"] header input[type="file"]'), new File(['courier'], 'courier.pdf'))
+      expect(dialog.text()).toContain('2/3 已上传')
+      await choose(dialog.find('[data-category="BOL"] .document-file input[type="file"]'), new File(['signed'], 'signed-bol.pdf'))
+      await dialog.find('[data-category="RECEIPT"] .document-file').findAll('button').find(button => button.text() === '删除')!.trigger('click')
+      expect(dialog.text()).not.toContain('pod.pdf')
+      expect(dialog.text()).toContain('courier.pdf')
+      expect(saveDeliveryDocuments).not.toHaveBeenCalled()
+      await dialog.findAll('button').find(button => button.text() === '保存资料')!.trigger('click'); await flushPromises()
+      expect(saveDeliveryDocuments).toHaveBeenCalledWith('DL/1', '100', { expectedVersion: 9, idempotencyKey: expect.any(String), bolNo: 'BOL-1', documents: [{ category: 'LOADING_PHOTO', fileIds: [] }, { category: 'BOL', fileIds: ['bol-2'] }, { category: 'RECEIPT', fileIds: ['receipt-2'] }] })
+      expect(wrapper.emitted('saved')).toHaveLength(1)
+      expect(success).toHaveBeenCalledWith('签收文件已保存，派送单已自动完成')
+      const persisted = response()
+      persisted.version = 10; persisted.uploadedCategoryCount = 2
+      persisted.categories = persisted.categories.map(group => ({ ...group, files: group.category === 'BOL' ? [replacement] : group.category === 'RECEIPT' ? [courier] : [], fileCount: group.category === 'LOADING_PHOTO' ? 0 : 1, status: group.category === 'LOADING_PHOTO' ? 'MISSING' : 'UPLOADED' }))
+      vi.mocked(getDeliveryDocuments).mockResolvedValue(persisted)
+      await wrapper.setProps({ modelValue: false }); await wrapper.setProps({ modelValue: true }); await flushPromises()
+      const reopened = body.find('[role="dialog"]')
+      expect(reopened.text()).toContain('2/3 已上传')
+      expect(reopened.text()).toContain('signed-bol.pdf')
+      expect(reopened.text()).toContain('courier.pdf')
+      expect(reopened.text()).not.toContain('original.pdf')
+      expect(getDeliveryDocuments).toHaveBeenCalledTimes(2)
+    } finally { wrapper.unmount() }
+  })
+  it('discards unsaved uploads on cancel and reloads persisted categories on reopening', async () => {
+    const wrapper = mountDialog(); await flushPromises()
+    await choose(wrapper.find('[data-category="RECEIPT"] input[type="file"]'), new File(['proof'], 'new.pdf'))
+    expect(wrapper.text()).toContain('2/3 已上传')
+    await wrapper.find('.close').trigger('click')
+    await wrapper.setProps({ modelValue: false }); await wrapper.setProps({ modelValue: true }); await flushPromises()
+    expect(saveDeliveryDocuments).not.toHaveBeenCalled()
+    expect(wrapper.emitted('saved')).toBeUndefined()
+    expect(wrapper.text()).toContain('1/3 已上传')
+    expect(wrapper.text()).not.toContain('new.pdf')
+    wrapper.unmount()
+  })
+  it('preserves the draft and idempotency key on a failed save, and prevents duplicate submissions', async () => {
+    const wrapper = mountDialog(); await flushPromises()
+    let reject!: (error: Error) => void
+    vi.mocked(saveDeliveryDocuments).mockReturnValueOnce(new Promise((_resolve, rejectRequest) => { reject = rejectRequest }))
+    await wrapper.find('.save').trigger('click'); await wrapper.find('.save').trigger('click')
+    expect(saveDeliveryDocuments).toHaveBeenCalledTimes(1)
+    reject(new Error('保存失败')); await flushPromises()
+    expect(wrapper.text()).toContain('original.pdf')
+    expect(wrapper.emitted('saved')).toBeUndefined()
+    const key = vi.mocked(saveDeliveryDocuments).mock.calls[0]![2].idempotencyKey
+    await wrapper.find('.save').trigger('click'); await flushPromises()
+    expect(vi.mocked(saveDeliveryDocuments).mock.calls[1]![2].idempotencyKey).toBe(key)
+    wrapper.unmount()
+  })
+  it('retains the existing file after replacement upload fails and rejects invalid file sizes', async () => {
+    const wrapper = mountDialog(); await flushPromises()
+    vi.mocked(uploadDeliveryDocument).mockRejectedValueOnce(new Error('上传失败'))
+    await choose(wrapper.find('[data-category="BOL"] .document-file input[type="file"]'), new File(['data'], 'bad.pdf'))
+    expect(wrapper.text()).toContain('original.pdf')
+    await choose(wrapper.find('[data-category="RECEIPT"] input[type="file"]'), new File([], 'empty.bin'))
+    const oversized = new File(['data'], 'large.bin'); Object.defineProperty(oversized, 'size', { value: 52428801 })
+    await choose(wrapper.find('[data-category="RECEIPT"] input[type="file"]'), oversized)
+    expect(uploadDeliveryDocument).toHaveBeenCalledTimes(1)
+    const exact = new File(['data'], 'valid.bin'); Object.defineProperty(exact, 'size', { value: 52428800 })
+    await choose(wrapper.find('[data-category="RECEIPT"] input[type="file"]'), exact)
+    expect(uploadDeliveryDocument).toHaveBeenCalledTimes(2)
+    wrapper.unmount()
+  })
+  it.each(['permission', 'action'])('is read-only without the required %s', async kind => {
+    if (kind === 'permission') can.mockReturnValue(false)
+    else vi.mocked(getDeliveryDocuments).mockResolvedValue({ ...response(), allowedActions: [] })
+    const wrapper = mountDialog(); await flushPromises()
+    expect(wrapper.find('.save').exists()).toBe(false)
+    expect(wrapper.find('input[type="file"]').exists()).toBe(false)
+    expect(wrapper.text()).toContain('original.pdf')
+    expect(saveDeliveryDocuments).not.toHaveBeenCalled()
+    wrapper.unmount()
+  })
+  it('blocks retries after a version conflict without losing draft files', async () => {
+    vi.mocked(saveDeliveryDocuments).mockRejectedValue({ isAxiosError: true, response: { status: 409, data: { code: 'A0409', message: '版本已变化', requestId: 'req-1', traceId: 'trace-1' } } })
+    const wrapper = mountDialog(); await flushPromises()
+    await wrapper.find('.save').trigger('click'); await flushPromises()
+    expect(wrapper.find('.save').attributes('disabled')).toBeDefined()
+    expect(wrapper.text()).toContain('original.pdf')
+    expect(wrapper.emitted('saved')).toBeUndefined()
+    wrapper.unmount()
+  })
+
+  it('limits each category to twenty files while allowing replacement', async () => {
+    const snapshot = response()
+    snapshot.categories.find(item => item.category === 'BOL')!.files = Array.from({ length: 20 }, (_, index) => ({ ...originalFile, fileId: String(index + 1) }))
+    snapshot.categories.find(item => item.category === 'BOL')!.fileCount = 20
+    vi.mocked(getDeliveryDocuments).mockResolvedValue(snapshot)
+    const wrapper = mountDialog(); await flushPromises()
+    expect(wrapper.find('[data-category="BOL"] header input[type="file"]').attributes('disabled')).toBeDefined()
+    await choose(wrapper.find('[data-category="BOL"] .document-file input[type="file"]'), new File(['data'], 'replace.pdf'))
+    await wrapper.find('.save').trigger('click'); await flushPromises()
+    expect(vi.mocked(saveDeliveryDocuments).mock.calls[0]![2].documents.find(item => item.category === 'BOL')!.fileIds).toHaveLength(20)
+    expect(vi.mocked(saveDeliveryDocuments).mock.calls[0]![2].documents.find(item => item.category === 'BOL')!.fileIds).toContain('9007199254740996')
+    wrapper.unmount()
+  })
+
+  it('ignores a late save response after switching to another customer delivery', async () => {
+    let finish!: (value: DeliveryDocuments) => void
+    vi.mocked(saveDeliveryDocuments).mockReturnValueOnce(new Promise(resolve => { finish = resolve }))
+    const wrapper = mountDialog(); await flushPromises()
+    await wrapper.find('.save').trigger('click')
+    vi.mocked(getDeliveryDocuments).mockResolvedValue({ ...response(), deliveryNo: 'DL/2', customerId: '200', bolNo: 'BOL-2' })
+    await wrapper.setProps({ deliveryNo: 'DL/2', customerId: '200' }); await flushPromises()
+    finish(response()); await flushPromises()
+    expect(wrapper.emitted('saved')).toBeUndefined()
+    expect(wrapper.emitted('update:modelValue')).toBeUndefined()
+    expect(wrapper.find('.save').exists()).toBe(true)
+    wrapper.unmount()
+  })
+
+  it('ignores a late upload failure after closing and reopening on another delivery', async () => {
+    let fail!: (reason: Error) => void
+    vi.mocked(uploadDeliveryDocument).mockReturnValueOnce(new Promise((_resolve, reject) => { fail = reject }))
+    const wrapper = mountDialog(); await flushPromises()
+    await choose(wrapper.find('[data-category="RECEIPT"] input[type="file"]'), new File(['data'], 'pending.pdf'))
+    await wrapper.setProps({ modelValue: false }); await flushPromises()
+    await wrapper.setProps({ modelValue: true, deliveryNo: 'DL/2', customerId: '200' }); await flushPromises()
+    fail(new Error('old upload failed')); await flushPromises()
+    expect(wrapper.text()).not.toContain('old upload failed')
+    expect(wrapper.text()).toContain('1/3 已上传')
+    expect(wrapper.find('[data-category="RECEIPT"] input[type="file"]').attributes('disabled')).toBeUndefined()
+    wrapper.unmount()
+  })
+})
diff --git a/src/modules/overseas-warehouse/components/DeliveryDocumentsDialog.vue b/src/modules/overseas-warehouse/components/DeliveryDocumentsDialog.vue
new file mode 100644
index 00000000..2829ace7
--- /dev/null
+++ b/src/modules/overseas-warehouse/components/DeliveryDocumentsDialog.vue
@@ -0,0 +1,136 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, ref, watch } from 'vue'
+import { ElMessage, ElMessageBox, type UploadFile } from 'element-plus'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { overseasWarehousePermissions as permission } from '../permissions'
+import { deliveryDocumentCategories, getDeliveryDocuments, saveDeliveryDocuments, uploadDeliveryDocument, downloadDeliveryDocument, type DeliveryDocuments, type DeliveryDocumentCategory, type DeliveryDocumentFile } from '../api/deliveryDocuments'
+
+const props = defineProps<{ deliveryNo: string; customerId: string }>()
+const open = defineModel<boolean>({ default: false })
+const emit = defineEmits<{ saved: [] }>()
+const access = useAccessPreviewStore()
+const snapshot = ref<DeliveryDocuments | null>(null)
+const draft = ref<Array<{ category: DeliveryDocumentCategory; label: string; files: DeliveryDocumentFile[] }>>([])
+const bolNo = ref('')
+const loading = ref(false)
+const saving = ref(false)
+const uploading = ref(false)
+const downloading = ref(false)
+const uploadKey = ref(0)
+const error = ref<ApiErrorDetails | null>(null)
+const conflict = ref(false)
+const canEdit = computed(() => access.can(permission.deliveryDocuments) && Boolean(snapshot.value?.allowedActions.includes('MANAGE_DOCUMENTS')))
+const busy = computed(() => saving.value || uploading.value)
+const uploadedCount = computed(() => draft.value.filter(item => item.files.length > 0).length)
+let sequence = 0
+function isCurrent(current: number, deliveryNo: string, customerId: string) { return current === sequence && open.value && props.deliveryNo === deliveryNo && props.customerId === customerId }
+let attempt: { body: string; key: string } | null = null
+async function load() {
+  const current = ++sequence
+  loading.value = true; saving.value = false; uploading.value = false; downloading.value = false; error.value = null; conflict.value = false; snapshot.value = null; draft.value = []; attempt = null
+  try {
+    const result = await getDeliveryDocuments(props.deliveryNo, props.customerId)
+    if (current !== sequence || !open.value) return
+    snapshot.value = result; bolNo.value = result.bolNo || ''
+    draft.value = deliveryDocumentCategories.map(item => ({ ...item, files: (result.categories.find(group => group.category === item.category)?.files || []).map(file => ({ ...file })) }))
+  } catch (cause) { if (current === sequence) error.value = getApiErrorDetails(cause, '派送资料加载失败') }
+  finally { if (current === sequence) loading.value = false }
+}
+async function reload() {
+  if (busy.value) return
+  if (snapshot.value && canEdit.value) {
+    try { await ElMessageBox.confirm('重新加载将放弃本次未保存的资料修改，是否继续？', '重新加载资料', { customClass: 'admin-density-confirm', type: 'warning' }) } catch { return }
+  }
+  await load()
+}
+watch(() => [open.value, props.deliveryNo, props.customerId] as const, ([visible]) => {
+  if (visible && props.deliveryNo && props.customerId) void load()
+  else { sequence++; snapshot.value = null; draft.value = []; error.value = null; bolNo.value = ''; attempt = null }
+}, { immediate: true })
+async function upload(category: DeliveryDocumentCategory, file: UploadFile, replaceId?: string) {
+  if (!canEdit.value || busy.value || conflict.value || !file.raw) return
+  const group = draft.value.find(item => item.category === category)
+  if (!group || (!replaceId && group.files.length >= 20)) { ElMessage.warning('每类最多上传20个文件'); return }
+  if (file.raw.size === 0 || file.raw.size > 52428800) { ElMessage.warning('文件不能为空，单个文件不能超过50MiB'); return }
+  uploading.value = true; error.value = null
+  const current = sequence; const { deliveryNo, customerId } = props
+  try {
+    const result = await uploadDeliveryDocument(deliveryNo, customerId, category, file.raw)
+    if (!isCurrent(current, deliveryNo, customerId)) return
+    const index = replaceId ? group.files.findIndex(item => item.fileId === replaceId) : -1
+    if (index >= 0) group.files.splice(index, 1, result)
+    else group.files.push(result)
+  } catch (cause) { if (isCurrent(current, deliveryNo, customerId)) error.value = getApiErrorDetails(cause, '资料上传失败') }
+  finally { if (isCurrent(current, deliveryNo, customerId)) { uploading.value = false; uploadKey.value++ } }
+}
+function remove(category: DeliveryDocumentCategory, fileId: string) {
+  if (!canEdit.value || busy.value || conflict.value) return
+  const group = draft.value.find(item => item.category === category)
+  if (group) group.files = group.files.filter(file => file.fileId !== fileId)
+}
+function isSaved(category: DeliveryDocumentCategory, fileId: string) { return snapshot.value?.categories.find(item => item.category === category)?.files.some(file => file.fileId === fileId) }
+async function download(category: DeliveryDocumentCategory, file: DeliveryDocumentFile) {
+  if (downloading.value || !isSaved(category, file.fileId)) return
+  downloading.value = true
+  const current = sequence; const { deliveryNo, customerId } = props
+  try {
+    const blob = await downloadDeliveryDocument(deliveryNo, customerId, category, file.fileId)
+    if (!isCurrent(current, deliveryNo, customerId)) return
+    const url = URL.createObjectURL(blob)
+    const link = document.createElement('a'); link.href = url; link.download = file.fileName; link.click()
+    setTimeout(() => URL.revokeObjectURL(url), 1000)
+  } catch (cause) { if (isCurrent(current, deliveryNo, customerId)) error.value = getApiErrorDetails(cause, '文件下载失败') }
+  finally { if (isCurrent(current, deliveryNo, customerId)) downloading.value = false }
+}
+async function save() {
+  if (!open.value || !canEdit.value || !snapshot.value || busy.value || conflict.value || loading.value) return
+  const body = { expectedVersion: snapshot.value.version, bolNo: bolNo.value.trim() || null, documents: draft.value.map(item => ({ category: item.category, fileIds: item.files.map(file => file.fileId) })) }
+  const serialized = JSON.stringify(body)
+  if (attempt?.body !== serialized) attempt = { body: serialized, key: crypto.randomUUID() }
+  saving.value = true; error.value = null
+  const current = sequence; const { deliveryNo, customerId } = props
+  try {
+    await saveDeliveryDocuments(deliveryNo, customerId, { ...body, idempotencyKey: attempt.key })
+    if (!isCurrent(current, deliveryNo, customerId)) return
+    const hasReceipt = body.documents.some(item => item.category === 'RECEIPT' && item.fileIds.length > 0)
+    open.value = false; emit('saved'); ElMessage.success(hasReceipt ? '签收文件已保存，派送单已自动完成' : '派送资料已保存')
+  } catch (cause) { if (isCurrent(current, deliveryNo, customerId)) { error.value = getApiErrorDetails(cause, '派送资料保存失败'); conflict.value = error.value.code === 'A0409' } }
+  finally { if (current === sequence) saving.value = false }
+}
+</script>
+
+<template>
+  <AppDialog class="admin-density-dialog" v-model="open" title="派送单所需资料" width="min(1040px, calc(100vw - 40px))" confirm-text="保存资料" cancel-text="关闭" :loading="loading" :show-confirm="canEdit" :confirm-loading="busy" :confirm-disabled="conflict || loading" @confirm="save">
+    <div class="delivery-documents">
+      <div class="document-identifiers"><label>派送单号<el-input :model-value="deliveryNo" readonly /></label><label>BOL号<el-input v-model="bolNo" :readonly="!canEdit" :disabled="busy || conflict" placeholder="未填写" /></label></div>
+      <LoadErrorState v-if="error" compact title="派送资料操作失败" :message="error.message" :show-retry="!snapshot || conflict" @retry="reload"><template #details><ApiErrorMeta :details="error" /></template></LoadErrorState>
+      <template v-if="snapshot">
+        <div class="document-summary"><span>{{ canEdit ? '上传、替换和删除将在保存资料后生效；关闭将放弃未保存修改。' : '当前账号仅可查看已保存资料。' }}</span><strong>{{ uploadedCount }}/3 已上传</strong></div>
+        <div class="document-groups">
+          <section v-for="group in draft" :key="group.category" class="document-group" :data-category="group.category">
+            <header><strong>{{ group.label }}</strong><el-tag :type="group.files.length ? 'success' : 'info'">{{ group.files.length ? '已上传' : '待上传' }}</el-tag><span>{{ group.files.length }}/20</span><el-upload v-if="canEdit" :key="uploadKey" :auto-upload="false" :show-file-list="false" :disabled="busy || conflict || group.files.length >= 20" :on-change="(file: UploadFile) => upload(group.category, file)"><el-button class="density-action" data-tone="primary" :disabled="busy || conflict || group.files.length >= 20">上传</el-button></el-upload></header>
+            <p v-if="!group.files.length" class="document-empty">尚未上传文件</p>
+            <div v-for="file in group.files" :key="file.fileId" class="document-file">
+              <div class="document-file-info"><button type="button" class="document-file-name" :title="file.fileName" :disabled="downloading || !isSaved(group.category, file.fileId)" @click="download(group.category, file)">{{ file.fileName }}</button><small>{{ file.uploadedAt?.replace('T', ' ') || '—' }}{{ isSaved(group.category, file.fileId) ? '' : ' · 待保存' }}</small></div>
+              <template v-if="canEdit"><el-upload :key="uploadKey" :auto-upload="false" :show-file-list="false" :disabled="busy || conflict" :on-change="(uploadFile: UploadFile) => upload(group.category, uploadFile, file.fileId)"><el-button class="density-action" data-tone="primary" :disabled="busy || conflict">替换</el-button></el-upload><el-button class="density-action" data-tone="danger" :disabled="busy || conflict" @click="remove(group.category, file.fileId)">删除</el-button></template>
+            </div>
+          </section>
+        </div>
+      </template>
+    </div>
+  </AppDialog>
+</template>
+
+<style scoped>
+.delivery-documents { display:grid; gap:var(--admin-space-5);  padding:2px var(--admin-space-2) var(--admin-space-1) 0; }
+.document-identifiers { display:grid; grid-template-columns:1fr 1fr; gap:var(--admin-space-5); }.document-identifiers label { display:grid; gap:var(--admin-space-3); font-weight:600; }
+.document-summary { display:flex; justify-content:space-between; align-items:center; gap:var(--admin-space-5); padding:var(--admin-space-5) var(--admin-space-5); background:var(--el-color-primary-light-9); color:var(--el-color-primary); border-radius:var(--admin-radius); }.document-summary strong { white-space:nowrap; }
+.document-groups { border:1px solid var(--cc-border); border-radius:var(--admin-radius); overflow:hidden; }.document-group { padding:var(--admin-space-5) var(--admin-space-5); }.document-group + .document-group { border-top:1px solid var(--cc-border); }
+.document-group header { display:flex; align-items:center; gap:var(--admin-space-4); }.document-group header > span { color:var(--cc-muted); font-size:var(--admin-font-caption); }.document-group header :deep(.el-upload) { margin-left:auto; }.document-group header > :last-child { margin-left:auto; }
+.document-file { display:flex; align-items:center; gap:var(--admin-space-5); padding-top:var(--admin-space-4); }.document-file-info { display:grid; min-width:0; flex:1; gap:var(--admin-space-1); }.document-file-name { border:0; background:none; padding:0; text-align:left; color:var(--cc-primary); overflow:hidden; white-space:nowrap; text-overflow:ellipsis; cursor:pointer; font:inherit; }.document-file-name:disabled { color:var(--cc-muted); cursor:default; }.document-file-info small,.document-empty { color:var(--cc-muted); }.document-empty { margin:var(--admin-space-4) 0 0; }
+</style>
diff --git a/src/modules/overseas-warehouse/components/OrderReferenceText.test.ts b/src/modules/overseas-warehouse/components/OrderReferenceText.test.ts
new file mode 100644
index 00000000..81512bdc
--- /dev/null
+++ b/src/modules/overseas-warehouse/components/OrderReferenceText.test.ts
@@ -0,0 +1,37 @@
+import { flushPromises, mount } from '@vue/test-utils'
+import { describe, expect, it, vi } from 'vitest'
+import OrderReferenceText from './OrderReferenceText.vue'
+
+describe('OrderReferenceText', () => {
+  it.each([
+    ['desktop-1920', '170px'],
+    ['narrow', '88px'],
+  ])('keeps the complete server order number in %s layouts', (_viewport, width) => {
+    const orderNo = 'LEGACY-LAST-MILE-ORDER-202608270000000001'
+    const wrapper = mount({
+      components: { OrderReferenceText },
+      template: `<div style="width:${width}"><OrderReferenceText value="${orderNo}" /></div>`,
+    })
+
+    const reference = wrapper.get('.order-reference-text')
+    expect(reference.text()).toBe(orderNo)
+    expect(reference.attributes('title')).toBe(orderNo)
+  })
+
+  it('renders the new short number in full and does not guess from another identifier', () => {
+    const wrapper = mount(OrderReferenceText, { props: { value: 'LMO-260827-0001' } })
+    expect(wrapper.text()).toBe('LMO-260827-0001')
+    expect(wrapper.attributes('title')).toBe('LMO-260827-0001')
+  })
+
+  it('copies the exact server short number without frontend formatting', async () => {
+    const writeText = vi.fn().mockResolvedValue(undefined)
+    vi.stubGlobal('navigator', { clipboard: { writeText } })
+    const wrapper = mount(OrderReferenceText, { props: { value: 'LMO-9A7', copyable: true } })
+    await wrapper.get('el-button').trigger('click')
+    await flushPromises()
+    expect(writeText).toHaveBeenCalledWith('LMO-9A7')
+    expect(wrapper.attributes('title')).toBe('LMO-9A7')
+    vi.unstubAllGlobals()
+  })
+})
diff --git a/src/modules/overseas-warehouse/components/OrderReferenceText.vue b/src/modules/overseas-warehouse/components/OrderReferenceText.vue
new file mode 100644
index 00000000..56dc2689
--- /dev/null
+++ b/src/modules/overseas-warehouse/components/OrderReferenceText.vue
@@ -0,0 +1,41 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import CopyButton from '@/shared/components/CopyButton.vue'
+
+const props = withDefaults(defineProps<{
+  value?: string | null
+  emptyText?: string
+  copyable?: boolean
+  compact?: boolean
+  copyLabel?: string
+}>(), { value: null, emptyText: '—', copyable: false, copyLabel: '尾程单号' })
+
+const displayValue = computed(() => {
+  const value = String(props.value ?? '')
+  return value || props.emptyText
+})
+
+const fullTitle = computed(() => displayValue.value === props.emptyText ? undefined : displayValue.value)
+</script>
+
+<template>
+  <span class="order-reference-text" :title="fullTitle"><span class="order-reference-text__value">{{ displayValue }}</span><CopyButton v-if="copyable && fullTitle" class="order-reference-text__copy" :text="compact" :size="compact ? 'small' : undefined" :value="displayValue" :label="copyLabel" button-text="" /></span>
+</template>
+
+<style scoped>
+.order-reference-text {
+  display: inline-flex;
+  min-width: 0;
+  align-items: center;
+  gap: 4px;
+  max-width: 100%;
+  vertical-align: bottom;
+}
+.order-reference-text__value {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.order-reference-text__copy { flex: 0 0 auto; margin: 0; padding-inline: 6px; }
+</style>
diff --git a/src/modules/overseas-warehouse/components/OverseasDetailShell.vue b/src/modules/overseas-warehouse/components/OverseasDetailShell.vue
new file mode 100644
index 00000000..83899620
--- /dev/null
+++ b/src/modules/overseas-warehouse/components/OverseasDetailShell.vue
@@ -0,0 +1,55 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { ArrowLeft } from '@lucide/vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import ContractPendingNotice from './ContractPendingNotice.vue'
+
+withDefaults(defineProps<{
+  title: string
+  dense?: boolean
+  referenceLabel: string
+  referenceValue: string
+  backLabel: string
+  domain: string
+  pending?: boolean
+  statusText?: string
+}>(), { pending: true, statusText: '接口待接入' })
+
+defineEmits<{ back: [] }>()
+</script>
+
+<template>
+  <AdminPage as="div" class="overseas-detail-page" :class="{ 'admin-density': dense }" :aria-label="title">
+    <header v-if="dense" class="density-detail-header">
+      <div class="overseas-detail-title density-detail-heading">
+        <el-button link class="density-back" :aria-label="backLabel" @click="$emit('back')"><ArrowLeft :size="16" />返回列表</el-button>
+        <h1 class="density-detail-title"><slot name="reference">{{ referenceValue }}</slot></h1>
+        <StatusBadge v-if="statusText" :status="statusText" />
+      </div>
+    </header>
+    <header v-else class="overseas-detail-head">
+      <el-button :class="{ 'density-back': dense }" :link="dense" :aria-label="backLabel" @click="$emit('back')"><ArrowLeft :size="16" />返回</el-button>
+      <div class="overseas-detail-title">
+        <h1>{{ title }}</h1>
+        <p>{{ referenceLabel }} <strong><slot name="reference">{{ referenceValue }}</slot></strong></p>
+      </div>
+      <span class="overseas-detail-status" :class="{ 'is-live': !pending }" role="status">{{ statusText }}</span>
+    </header>
+    <slot name="overview" />
+    <ContractPendingNotice v-if="pending" :domain="domain" />
+    <slot />
+  </AdminPage>
+</template>
+
+<style scoped>
+.overseas-detail-page { min-width: 0; }
+.overseas-detail-head { display: flex; min-height: 44px; align-items: center; gap: 12px; }
+.overseas-detail-head .overseas-detail-title { min-width: 0; flex: 1; }
+.overseas-detail-head .overseas-detail-title h1 { margin: 0; color: var(--cc-text); font-size: 20px; line-height: 1.35; }
+.overseas-detail-head .overseas-detail-title p { display: flex; min-width: 0; align-items: baseline; gap: 4px; margin: 3px 0 0; color: var(--cc-muted); font-size: 12px; line-height: 1.5; }
+.overseas-detail-head .overseas-detail-title strong { min-width: 0; max-width: 100%; color: var(--cc-text); }
+.overseas-detail-status { display: inline-flex; min-height: 26px; align-items: center; padding: 3px 10px; border: 1px solid #f3d19e; border-radius: 999px; background: #fdf6ec; color: #b88230; font-size: 12px; font-weight: 600; white-space: nowrap; }
+.overseas-detail-status.is-live { border-color: var(--el-color-success-light-7); background: var(--el-color-success-light-9); color: var(--el-color-success-dark-2); }
+.overseas-detail-page.admin-density { background: var(--admin-surface); border: 1px solid var(--cc-border); border-radius: var(--admin-radius); gap: 0; }
+</style>
diff --git a/src/modules/overseas-warehouse/components/OverseasReadOnlyDetail.vue b/src/modules/overseas-warehouse/components/OverseasReadOnlyDetail.vue
new file mode 100644
index 00000000..201ebdf3
--- /dev/null
+++ b/src/modules/overseas-warehouse/components/OverseasReadOnlyDetail.vue
@@ -0,0 +1,69 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import OverseasDetailShell from './OverseasDetailShell.vue'
+
+interface DetailGroup {
+  title: string
+  fields: string[]
+}
+
+defineProps<{
+  dense?: boolean
+  title: string
+  referenceLabel: string
+  referenceValue: string
+  backLabel: string
+  domain: string
+  groups: DetailGroup[]
+  fieldValues?: Record<string, string | number>
+  pending?: boolean
+  statusText?: string
+  loading?: boolean
+  showContent?: boolean
+}>()
+
+defineEmits<{ back: [] }>()
+</script>
+
+<template>
+  <OverseasDetailShell
+    :dense="dense"
+    :class="{ 'admin-density': dense }"
+    :title="title"
+    :reference-label="referenceLabel"
+    :reference-value="referenceValue"
+    :back-label="backLabel"
+    :domain="domain"
+    :pending="pending"
+    :status-text="statusText"
+    @back="$emit('back')"
+  >
+    <slot name="state" />
+    <section v-if="showContent !== false" v-loading="loading" class="read-only-detail" :aria-label="title" :aria-busy="loading">
+      <section v-for="group in groups" :key="group.title" class="detail-group" :aria-label="group.title">
+        <h2>{{ group.title }}</h2>
+        <dl class="detail-fields" :class="{ 'density-fields': dense }"><div v-for="field in group.fields" :key="field"><dt>{{ field }}</dt><dd>{{ fieldValues?.[field] ?? '—' }}</dd></div></dl>
+      </section>
+      <slot name="content-after" />
+    </section>
+  </OverseasDetailShell>
+</template>
+
+<style scoped>
+.read-only-detail { display: grid; min-width: 0; grid-template-columns: repeat(2, minmax(0, 1fr)); border: 1px solid var(--cc-border); background: #fff; }
+.detail-group { min-width: 0; padding: 16px 18px 18px; border-right: 1px solid var(--cc-border); border-bottom: 1px solid var(--cc-border); }
+.detail-group:nth-child(even) { border-right: 0; }
+.detail-group h2 { margin: 0 0 12px; color: var(--cc-text); font-size: 15px; }
+.detail-fields:not(.density-fields) { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); margin: 0; border-top: 1px solid var(--cc-border); border-left: 1px solid var(--cc-border); }
+.detail-fields:not(.density-fields) > div { display: grid; min-width: 0; min-height: 46px; grid-template-columns: 126px minmax(0, 1fr); border-right: 1px solid var(--cc-border); border-bottom: 1px solid var(--cc-border); }
+.detail-fields:not(.density-fields) dt, .detail-fields:not(.density-fields) dd { display: flex; min-width: 0; align-items: center; padding: 8px 10px; }
+.detail-fields:not(.density-fields) dt { background: #f8fafc; color: var(--cc-muted); font-size: 12px; }
+.detail-fields:not(.density-fields) dd { margin: 0; color: var(--cc-text); overflow-wrap: anywhere; }
+@media (max-width: 1100px) { .read-only-detail, .detail-fields:not(.density-fields) { grid-template-columns: 1fr; } .detail-group { border-right: 0; } }
+
+.admin-density .read-only-detail { grid-template-columns: minmax(0, 1fr); border: 0; }
+.admin-density .detail-group { padding: var(--admin-space-5); border-right: 0; }
+.admin-density .detail-group h2 { margin-bottom: var(--admin-space-3); font-size: var(--admin-font-section); }
+@media(max-width:1100px) { .admin-density .density-fields { grid-template-columns: 1fr; } }
+
+</style>
diff --git a/src/modules/overseas-warehouse/components/SmartDispatchDialog.vue b/src/modules/overseas-warehouse/components/SmartDispatchDialog.vue
new file mode 100644
index 00000000..8aef39a3
--- /dev/null
+++ b/src/modules/overseas-warehouse/components/SmartDispatchDialog.vue
@@ -0,0 +1,772 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, reactive, ref, watch } from 'vue'
+import { GripVertical, Plus } from '@lucide/vue'
+import { ElMessage } from 'element-plus'
+import { useRouter } from 'vue-router'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import OperationErrorToast from '@/shared/components/OperationErrorToast.vue'
+import { createDispatchDraftContainer, deleteDispatchDraftContainer, listDispatchCandidates, listDispatchDrafts, lockDispatchDraftPallet, preArrangeDispatch, unlockDispatchDraftPallet, type DispatchPalletCandidateDto } from '../api/dispatches'
+import { formatOverseasDateTime } from '../lastMilePresentation'
+import type { InboundOrderListItem } from '../types'
+import { dispatchVehicleSpecs } from '../dispatchVehicleSpecs'
+import OrderReferenceText from './OrderReferenceText.vue'
+
+interface LoadingContainer {
+  id: string
+  capacity: number
+  maxWeightLb: number
+  vehicleLabel: string
+  palletIds: string[]
+}
+
+const props = defineProps<{
+  modelValue: boolean
+  orders: InboundOrderListItem[]
+}>()
+const emit = defineEmits<{
+  'update:modelValue': [value: boolean]
+  created: []
+}>()
+const router = useRouter()
+const loading = ref(false)
+const saving = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const mutationError = ref<ApiErrorDetails | null>(null)
+const candidates = ref<DispatchPalletCandidateDto[]>([])
+const palletSnapshots = ref<Record<string, DispatchPalletCandidateDto>>({})
+const activeOrderKey = ref('')
+const containers = ref<LoadingContainer[]>([])
+const busyPalletIds = ref<string[]>([])
+const draftToken = ref('')
+const vehicleDialogOpen = ref(false)
+const selectedVehicle = ref('')
+const query = reactive({
+  orderNo: '',
+  orderType: '',
+  sourceStage: 'RECEIVED' as '' | 'PLAN' | 'RECEIVED',
+  fbaWarehouseCode: '',
+})
+const warehouseTab = ref<'ALL' | 'LAX' | 'NYC'>('ALL')
+
+const orderTypeOptions = [
+  { value: 'FIRST_LEG', label: '头程订单' },
+  { value: 'RELABEL_APPLICATION', label: '换标下单' },
+  { value: 'RETURN_RELABEL', label: '退货换标' },
+  { value: 'LOCAL_LOOSEBOARD', label: '本土散板' },
+  { value: 'WAREHOUSE_TRANSFER', label: '仓储转运' },
+]
+
+const planIds = computed(() => [...new Set(props.orders.map((item) => item.planId).filter(Boolean))])
+const visibleCandidates = computed(() =>
+  candidates.value.filter((item) => {
+    const typeMatches = !query.orderType || String(item.orderType || '') === query.orderType
+    if (!typeMatches) return false
+    if (warehouseTab.value === 'ALL') return true
+    const warehouse = `${item.overseasWarehouseId || ''} ${item.overseasWarehouseName || ''}`.toLowerCase()
+    return warehouseTab.value === 'LAX' ? /lax|洛杉矶|los angeles/.test(warehouse) : /nyc|jfk|纽约|new york/.test(warehouse)
+  }),
+)
+const orderGroups = computed(() => {
+  const groups = new Map<string, DispatchPalletCandidateDto[]>()
+  for (const item of visibleCandidates.value) {
+    const key = String(item.orderId || item.orderNo || item.planId)
+    groups.set(key, [...(groups.get(key) || []), item])
+  }
+  return [...groups.entries()].map(([key, pallets]) => ({
+    key,
+    first: pallets[0]!,
+    pallets,
+  }))
+})
+const activePallets = computed(() => orderGroups.value.find((item) => item.key === activeOrderKey.value)?.pallets || [])
+const assignedIds = computed(() => containers.value.flatMap((item) => item.palletIds))
+const assigned = computed(() => assignedIds.value.map((id) => palletSnapshot(id)).filter((item): item is DispatchPalletCandidateDto => Boolean(item)))
+const assignedPackages = computed(() => assigned.value.reduce((sum, item) => sum + Number(item.packageCount || 0), 0))
+const assignedVolume = computed(() => assigned.value.reduce((sum, item) => sum + Number(item.volumeCbm || 0), 0))
+const selectedVehicleSpec = computed(() => dispatchVehicleSpecs.find((item) => item.value === selectedVehicle.value))
+const weightLb = (item?: DispatchPalletCandidateDto) => Number(item?.volumeWeightKg || 0) * 2.2046226218
+const containerWeightLb = (container: LoadingContainer) => container.palletIds.reduce((sum, id) => sum + weightLb(palletSnapshot(id)), 0)
+
+function palletId(item: DispatchPalletCandidateDto) {
+  return String(item.planPalletId || item.warehousePalletId || '')
+}
+function text(value: unknown) {
+  const normalized = String(value ?? '').trim()
+  return normalized || '—'
+}
+function number(value: unknown, digits = 0) {
+  const normalized = Number(value)
+  return Number.isFinite(normalized) ? normalized.toFixed(digits) : '0'
+}
+function dateTime(value: unknown) {
+  return formatOverseasDateTime(value)
+}
+function orderType(value: unknown) {
+  return (
+    (
+      {
+        FIRST_LEG: '头程订单',
+        RELABEL_APPLICATION: '换标下单',
+        RETURN_RELABEL: '退货换标',
+        LOCAL_LOOSEBOARD: '本土散板',
+        WAREHOUSE_TRANSFER: '仓储转运',
+        ONE_CLICK_DROPSHIP: '一件代发',
+        REJECTED: '拒收订单',
+        EXPRESS: '快递订单',
+      } as Record<string, string>
+    )[String(value || '')] || text(value)
+  )
+}
+function relabelCartonMarks(item: DispatchPalletCandidateDto) {
+  return String(item.relabelCartonMarks || '')
+    .split(',')
+    .map((value) => value.trim())
+    .filter(Boolean)
+}
+function containerFor(id: string) {
+  return containers.value.find((item) => item.palletIds.includes(id))
+}
+function palletSnapshot(id: string) {
+  return palletSnapshots.value[id]
+}
+function makeDraftToken() {
+  return globalThis.crypto?.randomUUID?.() || `dispatch-${Date.now()}-${Math.random().toString(16).slice(2)}`
+}
+function ensureDraftToken() {
+  if (!draftToken.value.trim()) draftToken.value = makeDraftToken()
+  return draftToken.value
+}
+function rememberPallets(items: DispatchPalletCandidateDto[]) {
+  palletSnapshots.value = {
+    ...palletSnapshots.value,
+    ...Object.fromEntries(items.map((item) => [palletId(item), item])),
+  }
+}
+async function hydrateDraftPallets() {
+  const restored = await listDispatchCandidates({
+    draftToken: ensureDraftToken(),
+  })
+  rememberPallets(restored)
+}
+
+async function load() {
+  loading.value = true
+  loadError.value = null
+  try {
+    candidates.value = await listDispatchCandidates({
+      planIds: planIds.value.length ? planIds.value.join(',') : undefined,
+      orderNo: query.orderNo.trim() || undefined,
+      fbaWarehouseCode: query.fbaWarehouseCode.trim() || undefined,
+      sourceStage: query.sourceStage || undefined,
+      draftToken: ensureDraftToken(),
+    })
+    rememberPallets(candidates.value)
+    activeOrderKey.value = orderGroups.value[0]?.key || ''
+  } catch (error) {
+    candidates.value = []
+    activeOrderKey.value = ''
+    loadError.value = getApiErrorDetails(error, '可排车入仓单加载失败，请重试')
+  } finally {
+    loading.value = false
+  }
+}
+function reset() {
+  query.orderNo = ''
+  query.orderType = ''
+  query.sourceStage = 'RECEIVED'
+  query.fbaWarehouseCode = ''
+  warehouseTab.value = 'ALL'
+  void load()
+}
+
+function addContainer() {
+  selectedVehicle.value = ''
+  vehicleDialogOpen.value = true
+}
+async function confirmAddContainer() {
+  const spec = selectedVehicleSpec.value
+  if (!spec) {
+    ElMessage.warning('请选择车型')
+    return
+  }
+  try {
+    const created = await createDispatchDraftContainer(ensureDraftToken(), spec.capacity)
+    containers.value.push({
+      id: created.id,
+      capacity: created.capacity,
+      maxWeightLb: spec.maxWeightLb,
+      vehicleLabel: spec.label,
+      palletIds: created.palletIds || [],
+    })
+    vehicleDialogOpen.value = false
+  } catch (error) {
+    mutationError.value = getApiErrorDetails(error, '添加装车车型失败，请重试')
+  }
+}
+
+async function movePallet(item: DispatchPalletCandidateDto, containerId: string) {
+  const id = palletId(item)
+  const target = containers.value.find((container) => container.id === containerId)
+  if (!target || target.palletIds.includes(id)) return
+  if (!String(item.overseasWarehouseId || '').trim()) {
+    ElMessage.warning('该托盘尚未关联海外仓，不能排车')
+    return
+  }
+  if (containerFor(id)) {
+    ElMessage.warning('该托盘已在其他装车托盘中')
+    return
+  }
+  if (target.palletIds.length >= target.capacity) {
+    ElMessage.warning('该装车托盘已达到设置的托数')
+    return
+  }
+  const nextWeight = containerWeightLb(target) + weightLb(item)
+  if (nextWeight > target.maxWeightLb * 1.1) ElMessage.error(`${target.vehicleLabel}重量将达到 ${nextWeight.toFixed(0)}LB，已超过限重10%，请注意调整`)
+  else if (nextWeight > target.maxWeightLb) ElMessage.warning(`${target.vehicleLabel}当前重量 ${nextWeight.toFixed(0)}LB，已超过额定限重 ${target.maxWeightLb}LB`)
+  const anchor = assigned.value[0]
+  if (anchor?.customerId && anchor.customerId !== item.customerId) {
+    ElMessage.warning('一次排车只能装同一客户的托盘')
+    return
+  }
+  if (anchor?.overseasWarehouseId && anchor.overseasWarehouseId !== item.overseasWarehouseId) {
+    ElMessage.warning('一次排车只能装同一海外仓的托盘')
+    return
+  }
+  busyPalletIds.value.push(id)
+  mutationError.value = null
+  try {
+    if (item.sourceStage !== 'RELABEL') await lockDispatchDraftPallet(id, ensureDraftToken(), target.id)
+    target.palletIds.push(id)
+  } catch (error) {
+    mutationError.value = getApiErrorDetails(error, '托盘锁定失败，请刷新后重试')
+  } finally {
+    busyPalletIds.value = busyPalletIds.value.filter((value) => value !== id)
+  }
+}
+
+async function removePallet(id: string) {
+  const owner = containerFor(id)
+  if (!owner) return
+  busyPalletIds.value.push(id)
+  mutationError.value = null
+  try {
+    if (palletSnapshot(id)?.sourceStage !== 'RELABEL') await unlockDispatchDraftPallet(id, ensureDraftToken())
+    owner.palletIds = owner.palletIds.filter((value) => value !== id)
+  } catch (error) {
+    mutationError.value = getApiErrorDetails(error, '托盘解锁失败，请重试')
+  } finally {
+    busyPalletIds.value = busyPalletIds.value.filter((value) => value !== id)
+  }
+}
+
+async function deleteContainer(container: LoadingContainer) {
+  for (const id of [...container.palletIds]) {
+    await removePallet(id)
+  }
+  if (!container.palletIds.length) {
+    await deleteDispatchDraftContainer(ensureDraftToken(), container.id)
+    containers.value = containers.value.filter((item) => item.id !== container.id)
+  }
+}
+function dragStart(event: DragEvent, item: DispatchPalletCandidateDto) {
+  event.dataTransfer?.setData('text/plain', palletId(item))
+}
+function dropInto(event: DragEvent, containerId: string) {
+  const id = event.dataTransfer?.getData('text/plain') || ''
+  const item = candidates.value.find((candidate) => palletId(candidate) === id)
+  if (item) void movePallet(item, containerId)
+}
+
+async function close(value = false) {
+  emit('update:modelValue', value)
+}
+
+async function submit() {
+  if (!assignedIds.value.length) {
+    ElMessage.warning('请至少移入一个托盘')
+    return
+  }
+  if (assigned.value.some((item) => !String(item.overseasWarehouseId || '').trim())) {
+    ElMessage.warning('所选托盘中存在尚未关联海外仓的托盘')
+    return
+  }
+  const relabelOrders = [...new Set(assigned.value.filter((item) => item.sourceStage === 'RELABEL')
+    .map((item) => String(item.orderNo || '').trim()).filter(Boolean))]
+  if (relabelOrders.length && (relabelOrders.length !== 1 || assigned.value.some((item) => item.sourceStage !== 'RELABEL'))) {
+    ElMessage.warning('一张换标单的托盘需要单独排车')
+    return
+  }
+  saving.value = true
+  mutationError.value = null
+  try {
+    await preArrangeDispatch({
+      planPalletIds: assignedIds.value,
+      ...(relabelOrders.length ? { relabelNo: relabelOrders[0] } : { draftToken: ensureDraftToken() }),
+    })
+    emit('update:modelValue', false)
+    emit('created')
+    ElMessage.success('排车明细已同步到预排列表')
+    await router.push({ name: 'overseas-dispatches' })
+  } catch (error) {
+    mutationError.value = getApiErrorDetails(error, '预排车创建失败，请重试')
+  } finally {
+    saving.value = false
+  }
+}
+
+watch(
+  () => props.modelValue,
+  (open) => {
+    if (!open) return
+    draftToken.value = makeDraftToken()
+    containers.value = []
+    palletSnapshots.value = {}
+    query.orderNo = ''
+    query.orderType = ''
+    query.sourceStage = 'RECEIVED'
+    query.fbaWarehouseCode = ''
+    warehouseTab.value = 'ALL'
+    mutationError.value = null
+    void (async () => {
+      const drafts = await listDispatchDrafts().catch(() => [])
+      const draft = drafts[0]
+      if (draft?.draftToken) {
+        draftToken.value = draft.draftToken
+        containers.value = (draft.containers || []).map((c) => {
+          const spec = dispatchVehicleSpecs.find((item) => item.capacity === c.capacity) || dispatchVehicleSpecs[0]!
+          return {
+            id: c.id,
+            capacity: c.capacity,
+            maxWeightLb: spec.maxWeightLb,
+            vehicleLabel: spec.label,
+            palletIds: c.palletIds || [],
+          }
+        })
+        await hydrateDraftPallets().catch(() => undefined)
+      }
+      await load()
+    })()
+  },
+  { immediate: true },
+)
+
+watch([warehouseTab, () => query.orderType], () => {
+  activeOrderKey.value = orderGroups.value[0]?.key || ''
+})
+</script>
+
+<template>
+  <OperationErrorToast :details="mutationError" />
+  <AppDialog class="admin-density-dialog admin-density" :model-value="modelValue" title="智能排车" width="min(1800px, calc(100vw - 40px))" @update:model-value="close($event)">
+    <section class="dispatch-query" aria-label="智能排车筛选">
+      <el-input v-model="query.orderNo" clearable placeholder="订单号" @keyup.enter="load" />
+      <el-select v-model="query.orderType" clearable placeholder="全部订单类型"><el-option v-for="option in orderTypeOptions" :key="option.value" :label="option.label" :value="option.value" /></el-select>
+      <el-select v-model="query.sourceStage" clearable placeholder="全部状态"><el-option label="入库完成托盘" value="RECEIVED" /><el-option label="计划托盘" value="PLAN" /></el-select>
+      <el-input v-model="query.fbaWarehouseCode" clearable placeholder="FBA仓库" @keyup.enter="load" />
+      <el-button type="primary" :loading="loading" @click="load">查询</el-button><el-button :disabled="loading" @click="reset">重置</el-button>
+    </section>
+
+    <nav class="warehouse-tabs density-tabs" aria-label="海外仓筛选">
+      <button
+ v-for="tab in [
+          { value: 'ALL', label: '全部' },
+          { value: 'LAX', label: '洛杉矶' },
+          { value: 'NYC', label: '纽约' },
+        ]"
+ :key="tab.value"
+ type="button"
+ :class="['warehouse-tab', { active: warehouseTab === tab.value }]"
+ @click="warehouseTab = tab.value as 'ALL' | 'LAX' | 'NYC'"
+ >
+        {{ tab.label }}
+      </button>
+    </nav>
+
+    <LoadErrorState v-if="loadError" title="可排车入仓单加载失败" :message="loadError.message" :loading="loading" @retry="load"
+ ><template #details><ApiErrorMeta :details="loadError" /></template
+    ></LoadErrorState>
+    <div v-else class="dispatch-workbench">
+      <section class="order-pane" aria-label="可排车入仓单">
+        <header>
+          <div>
+            <h3>
+              出库单列表 <span>({{ orderGroups.length }}单)</span>
+            </h3>
+            <div class="order-type-tabs density-tabs">
+              <button v-for="option in [{ value: '', label: '全部' }, ...orderTypeOptions]" :key="option.value || 'all'" type="button" :class="{ active: query.orderType === option.value }" @click="query.orderType = option.value">
+                {{ option.label }}
+              </button>
+            </div>
+          </div>
+        </header>
+        <div v-loading="loading" class="order-table-wrap">
+          <el-table :data="orderGroups" border height="520" highlight-current-row row-key="key" @current-change="activeOrderKey = $event?.key || ''">
+            <el-table-column label="订单号" min-width="170"
+ ><template #default="{ row }"><OrderReferenceText :value="text(row.first.orderNo)" /></template
+            ></el-table-column>
+            <el-table-column label="换标单号" min-width="180"
+ ><template #default="{ row }">{{ row.first.sourceStage === 'RELABEL' ? text(row.first.orderRefs) : '—' }}</template
+            ></el-table-column>
+            <el-table-column label="原入仓码" min-width="150"
+ ><template #default="{ row }">{{ text(row.first.inboundCode) }}</template
+            ></el-table-column>
+            <el-table-column label="订单类型" width="100"
+ ><template #default="{ row }">{{ orderType(row.first.orderType) }}</template></el-table-column
+            >
+            <el-table-column label="重量(lb)" width="100" align="right"
+ ><template #default="{ row }">{{ number(Number(row.first.volumeWeightKg || 0) * 2.2046226218, 0) }}LB</template></el-table-column
+            >
+            <el-table-column label="托盘数量" width="90" align="right"
+ ><template #default="{ row }">{{ row.pallets.length }}</template></el-table-column
+            >
+            <el-table-column label="目的地FBA" width="110"
+ ><template #default="{ row }">{{ text(row.first.fbaWarehouseCode) }}</template></el-table-column
+            >
+            <el-table-column label="体积(m³)" width="100" align="right"
+ ><template #default="{ row }">{{
+                number(
+                  row.pallets.reduce((sum: number, item: DispatchPalletCandidateDto) => sum + Number(item.volumeCbm || 0), 0),
+                  2,
+                )
+              }}</template></el-table-column
+            >
+            <el-table-column label="货柜号" min-width="125"
+ ><template #default="{ row }">{{ text(row.first.containerNo) }}</template></el-table-column
+            >
+            <el-table-column label="预约送仓时间" min-width="145"
+ ><template #default="{ row }">{{ dateTime(row.first.appointmentAt) }}</template></el-table-column
+            >
+            <el-table-column label="预计装车时间" min-width="145"
+ ><template #default="{ row }">{{ dateTime(row.first.expectedLoadingAt) }}</template></el-table-column
+            >
+          </el-table>
+        </div>
+      </section>
+
+      <section class="detail-pane" aria-label="入仓单托盘和箱号详情">
+        <header>
+          <h3>
+            托盘明细
+            <span>{{ activePallets.length ? `(${activePallets.length}托)` : '' }}</span>
+          </h3>
+          <span class="detail-order-reference">订单号：<OrderReferenceText :value="text(activePallets[0]?.orderNo)" /></span>
+        </header>
+        <div class="pallet-list">
+          <div v-for="item in activePallets" :key="palletId(item)" class="pallet-row" :class="{ assigned: containerFor(palletId(item)) }" draggable="true" @dragstart="dragStart($event, item)">
+            <GripVertical :size="16" class="drag-handle" />
+            <div class="pallet-copy">
+              <strong>{{ text(item.palletNo) }}</strong
+              ><span>{{ Number(item.packageCount || 0) }}箱 · {{ number(weightLb(item), 0) }}LB</span>
+              <div v-if="relabelCartonMarks(item).length" class="carton-marks">
+                <div v-for="mark in relabelCartonMarks(item)" :key="`relabel-${mark}`" class="carton-mark-line">
+                  <span>{{ mark }}</span
+                  ><el-tag size="small" type="warning">换标</el-tag>
+                </div>
+              </div>
+            </div>
+            <el-tag v-if="containerFor(palletId(item))" type="success" size="small">已锁定</el-tag>
+            <el-dropdown v-else trigger="click" :disabled="!containers.length || busyPalletIds.includes(palletId(item))" @command="movePallet(item, String($event))">
+              <el-button class="density-action" data-tone="primary" :loading="busyPalletIds.includes(palletId(item))">移入 </el-button>
+              <template #dropdown
+ ><el-dropdown-menu
+ ><el-dropdown-item v-for="(container, index) in containers" :key="container.id" :command="container.id" :disabled="container.palletIds.length >= container.capacity">装车托盘 {{ index + 1 }}（{{ container.palletIds.length }}/{{ container.capacity }}）</el-dropdown-item></el-dropdown-menu
+                ></template
+              >
+            </el-dropdown>
+          </div>
+          <el-empty v-if="!activePallets.length" :image-size="64" description="点击左侧入仓单查看托盘和箱号" />
+        </div>
+      </section>
+
+      <aside class="container-pane" aria-label="装车托盘容器">
+        <header>
+          <div>
+            <h3>装车托盘</h3>
+            <p>
+              托盘 {{ assigned.length }} · 箱数 {{ assignedPackages }} · 立方
+              {{ assignedVolume.toFixed(2) }}
+            </p>
+          </div>
+          <el-button type="primary" plain @click="addContainer"><Plus :size="15" />添加装车托盘</el-button>
+        </header>
+        <div class="container-list">
+          <div
+ v-for="(container, index) in containers"
+ :key="container.id"
+ class="loading-container"
+ :class="{
+              'loading-container--overweight': containerWeightLb(container) > container.maxWeightLb * 1.1,
+            }"
+ @dragover.prevent
+ @drop.prevent="dropInto($event, container.id)"
+ >
+            <div class="container-head">
+              <strong>{{ container.vehicleLabel }}</strong
+              ><span
+ >托数 <b>{{ container.palletIds.length }}</b
+                >/{{ container.capacity }} · 重量 <b>{{ number(containerWeightLb(container), 0) }}LB</b>/{{ container.maxWeightLb }}LB <em v-if="containerWeightLb(container) > container.maxWeightLb * 1.1">超限10%</em></span
+              ><el-button class="density-action" data-tone="danger" :aria-label="`删除装车车型${index + 1}`" @click="deleteContainer(container)">删除</el-button>
+            </div>
+            <div class="container-body">
+              <div v-for="id in container.palletIds" :key="id" class="loaded-pallet">
+                <span
+ ><strong>{{ text(palletSnapshot(id)?.palletNo || '托盘号待补充') }}</strong
+                  ><OrderReferenceText :value="text(palletSnapshot(id)?.orderNo)" /></span
+                ><el-button class="density-action" data-tone="danger" :loading="busyPalletIds.includes(id)" @click="removePallet(id)">移除</el-button>
+              </div>
+              <span v-if="!container.palletIds.length" class="drop-hint">拖入托盘，移入后立即锁定</span>
+            </div>
+          </div>
+          <el-empty v-if="!containers.length" :image-size="64" description="请先添加装车托盘" />
+        </div>
+      </aside>
+    </div>
+
+    <template #footer><footer class="dialog-footer">
+      <span>托盘移入即锁定，重量按 1kg = 2.2046lb 换算。</span>
+      <div><el-button :disabled="saving" @click="close(false)">取消</el-button><el-button type="primary" :loading="saving" :disabled="!assignedIds.length" @click="submit">预排车</el-button></div>
+    </footer></template>
+  </AppDialog>
+  <el-dialog class="admin-density-dialog" v-model="vehicleDialogOpen" title="选择车型" width="360px" append-to-body>
+    <el-radio-group v-model="selectedVehicle" class="vehicle-options">
+      <el-radio v-for="spec in dispatchVehicleSpecs" :key="spec.value" :value="spec.value">{{ spec.label }} · 限重 {{ spec.maxWeightLb }}LB</el-radio>
+    </el-radio-group>
+    <template #footer><el-button @click="vehicleDialogOpen = false">取消</el-button><el-button type="primary" @click="confirmAddContainer">确定</el-button></template>
+  </el-dialog>
+</template>
+
+<style scoped>
+.dispatch-query {
+  display: flex;
+  align-items: center;
+  gap: var(--admin-space-5);
+  padding: var(--admin-space-5) var(--admin-space-5);
+  border: 1px solid #e6eaf2;
+  border-radius: var(--admin-radius);
+  background: #f7f8fb;
+}
+.dispatch-query :deep(.el-input),
+.dispatch-query :deep(.el-select) {
+  width: 190px;
+}
+.warehouse-tabs {
+  margin-top: var(--admin-space-5);
+}
+.dispatch-workbench {
+  display: grid;
+  grid-template-columns: minmax(550px, 1.5fr) minmax(330px, 0.85fr) minmax(390px, 1fr);
+  gap: var(--admin-space-5);
+  margin-top: var(--admin-space-5);
+}
+.order-pane,
+.detail-pane,
+.container-pane {
+  min-width: 0;
+}
+.order-pane header,
+.detail-pane header,
+.container-pane header {
+  display: flex;
+  min-height: 74px;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--admin-space-4);
+}
+.detail-order-reference {
+  display: flex;
+  min-width: 0;
+  max-width: 240px;
+  align-items: baseline;
+  gap: 3px;
+}
+h3,
+p {
+  margin: 0;
+}
+h3 {
+  font-size: var(--admin-font-section);
+}
+h3 span,
+header > span,
+p {
+  color: var(--cc-muted);
+  font-size: var(--admin-font-caption);
+  font-weight: 400;
+}
+.order-type-tabs {
+  margin-top: var(--admin-space-4);
+}
+.order-table-wrap {
+  min-height: 520px;
+}
+.detail-pane,
+.container-pane {
+  border-left: 1px solid var(--cc-border);
+  padding-left: var(--admin-space-5);
+}
+.pallet-list,
+.container-list {
+  height: 520px;
+  overflow-y: auto;
+  border: 1px solid var(--cc-border);
+  border-radius: var(--admin-radius);
+  background: #fafbfc;
+}
+.pallet-row:hover {
+  background: #f8f6ff;
+}
+.pallet-row.assigned {
+  background: #f2fbf6;
+}
+.drag-handle {
+  color: var(--cc-muted);
+}
+.pallet-copy {
+  display: flex;
+  min-width: 0;
+  flex-direction: column;
+  gap: var(--admin-space-1);
+}
+.pallet-copy > span,
+.carton-marks > span {
+  color: var(--cc-muted);
+  font-size: var(--admin-font-caption);
+}
+.carton-marks {
+  display: flex;
+  min-width: 0;
+  flex-direction: column;
+  gap: var(--admin-space-1);
+}
+.carton-mark-line {
+  display: flex;
+  min-width: 0;
+  align-items: center;
+  gap: var(--admin-space-2);
+  color: var(--cc-muted);
+  font-size: var(--admin-font-caption);
+}
+.carton-mark-line > span {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.container-pane > .el-input {
+  margin-bottom: var(--admin-space-4);
+}
+.container-list {
+  height: 460px;
+  padding: var(--admin-space-3);
+}
+.loading-container {
+  margin-bottom: var(--admin-space-4);
+  border: 1px dashed #bcc6d5;
+  border-radius: var(--admin-radius);
+  background: #fff;
+}
+.loading-container--overweight {
+  border-color: var(--el-color-danger);
+}
+.loading-container--overweight .container-head {
+  background: var(--el-color-danger-light-9);
+}
+.loading-container--overweight .container-head span,
+.loading-container--overweight .container-head b {
+  color: var(--el-color-danger);
+}
+.container-head em {
+  margin-left: var(--admin-space-1);
+  color: var(--el-color-danger);
+  font-style: normal;
+  font-weight: 700;
+}
+.container-head span {
+  color: var(--cc-muted);
+  font-size: var(--admin-font-caption);
+}
+.container-head b {
+  color: var(--el-color-primary);
+}
+.container-body {
+  min-height: 76px;
+  padding: var(--admin-space-3);
+}
+.drop-hint {
+  display: grid;
+  min-height: 60px;
+  place-items: center;
+  color: var(--cc-muted);
+  font-size: var(--admin-font-caption);
+}
+.loaded-pallet {
+  display: flex;
+  min-height: 52px;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--admin-space-3);
+  border-bottom: 1px solid var(--cc-border);
+}
+.loaded-pallet > span {
+  display: flex;
+  min-width: 0;
+  flex: 1;
+  flex-direction: column;
+  color: var(--cc-muted);
+  font-size: var(--admin-font-caption);
+}
+.loaded-pallet strong {
+  color: var(--cc-text);
+  font-size: var(--admin-font-body);
+}
+.dialog-footer > span {
+  color: var(--cc-muted);
+  font-size: var(--admin-font-caption);
+}
+.vehicle-options {
+  display: grid;
+  gap: var(--admin-space-5);
+}
+@media (max-width: 1280px) {
+  .dispatch-workbench {
+    grid-template-columns: minmax(500px, 1.3fr) minmax(320px, 1fr);
+  }
+  .container-pane {
+    grid-column: 1 / -1;
+    border-left: 0;
+    padding-left: 0;
+  }
+  .container-list {
+    height: 300px;
+  }
+}
+
+.dialog-footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--admin-space-5); margin: 0; padding: 0;
+  border-top: 1px solid var(--cc-border); background: transparent; border: 0; text-align: left; }
+.container-head {
+  display: grid; grid-template-columns: minmax(0, 1fr) auto auto;
+  min-height: 44px;
+  align-items: center;
+  gap: var(--admin-space-3);
+  padding: 0 var(--admin-space-3) 0 var(--admin-space-5);
+  background: #f4f6fa; }
+.pallet-row {
+  display: grid;
+  grid-template-columns: 20px minmax(0, 1fr) auto; min-height: var(--admin-empty-height);
+  align-items: center;
+  gap: var(--admin-space-3);
+  padding: var(--admin-space-4) var(--admin-space-5);
+  border-bottom: 1px solid var(--cc-border);
+  background: #fff;
+  cursor: grab;
+  transition: background 0.18s ease; }
+.order-pane header, .detail-pane header, .container-pane header { min-height: 60px; }
+
+</style>
diff --git a/src/modules/overseas-warehouse/components/WarehouseTransferReviewDialog.vue b/src/modules/overseas-warehouse/components/WarehouseTransferReviewDialog.vue
new file mode 100644
index 00000000..305a2675
--- /dev/null
+++ b/src/modules/overseas-warehouse/components/WarehouseTransferReviewDialog.vue
@@ -0,0 +1,78 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, reactive, ref, watch } from 'vue'
+import { CheckCircle2, XCircle } from '@lucide/vue'
+import { ElMessage } from 'element-plus'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { getWarehouseTransfer, reviewWarehouseTransfer, type WarehouseTransferDetailDto } from '../api/warehouseTransfers'
+
+const props = defineProps<{ modelValue: boolean; customerId: string; customerName: string; transferNo: string }>()
+const emit = defineEmits<{ 'update:modelValue': [value: boolean]; reviewed: [] }>()
+const open = computed({ get: () => props.modelValue, set: (value) => emit('update:modelValue', value) })
+const detail = ref<WarehouseTransferDetailDto | null>(null)
+const loading = ref(false)
+const saving = ref(false)
+const error = ref<ApiErrorDetails | null>(null)
+const form = reactive<{ decision: 'APPROVE' | 'REJECT'; remark: string }>({ decision: 'APPROVE', remark: '' })
+const itemColumns: DataTableColumn[] = [
+  { key: 'skuCode', label: 'SKU', minWidth: 140 }, { key: 'productNameZh', label: '品名', minWidth: 160 },
+  { key: 'packageCount', label: '箱数', width: 80, align: 'right' }, { key: 'shippingMark', label: '客户箱唛', minWidth: 160 },
+]
+const bindingColumns: DataTableColumn[] = [
+  { key: 'operationType', label: '换标类型', minWidth: 120 }, { key: 'customerCartonMark', label: '客户箱唛', minWidth: 150 },
+  { key: 'originalSku', label: '原 SKU', minWidth: 120 }, { key: 'newSku', label: '新 SKU', minWidth: 120 },
+  { key: 'quantity', label: '数量', width: 80, align: 'right' }, { key: 'fbaCartonMark', label: '新箱唛', minWidth: 150 },
+]
+const palletColumns: DataTableColumn[] = [
+  { key: 'sequenceNo', label: '托序', width: 70, align: 'center' }, { key: 'palletNo', label: '托盘号', minWidth: 150 },
+  { key: 'cartonCount', label: '箱数', width: 80, align: 'right' }, { key: 'volumeCbm', label: '托盘总体积(m³)', width: 150, align: 'right' },
+  { key: 'grossWeightKg', label: '托盘总重量(kg)', width: 150, align: 'right' },
+]
+
+async function load() {
+  if (!props.customerId || !props.transferNo) return
+  loading.value = true; error.value = null; detail.value = null
+  try { detail.value = await getWarehouseTransfer(props.customerId, props.transferNo) }
+  catch (cause) { error.value = getApiErrorDetails(cause, '转运单审核资料加载失败，请重试') }
+  finally { loading.value = false }
+}
+async function submit() {
+  if (saving.value) return
+  if (form.decision === 'REJECT' && !form.remark.trim()) { ElMessage.warning('驳回时请填写审核原因'); return }
+  saving.value = true
+  try {
+    await reviewWarehouseTransfer(props.customerId, props.transferNo, form.decision, form.remark.trim() || undefined)
+    ElMessage.success(form.decision === 'APPROVE' ? '转运单审核通过，已推送 PDA 收货打托' : '转运单已驳回')
+    open.value = false; emit('reviewed')
+  } catch (cause) { ElMessage.error(getApiErrorDetails(cause, '审核提交失败，请重试').message) }
+  finally { saving.value = false }
+}
+watch(() => props.modelValue, (value) => { if (value) { form.decision = 'APPROVE'; form.remark = ''; void load() } })
+</script>
+
+<template>
+  <AppDialog class="admin-density-dialog" v-model="open" title="审核仓储转运单" width="min(920px, calc(100vw - 28px))" confirm-text="提交审核" :confirm-loading="saving" :loading="loading" @confirm="submit">
+    <LoadErrorState v-if="error" compact title="审核资料加载失败" :message="error.message" @retry="load"><template #details><ApiErrorMeta :details="error" /></template></LoadErrorState>
+    <el-form v-else-if="detail" label-position="top" class="review-form density-form">
+      <div class="review-heading"><strong>{{ detail.transferNo }}</strong><span>{{ customerName }} · {{ detail.packageCount }} 箱 · {{ detail.needRelabel ? '需要换标' : '无需换标' }}</span></div>
+      <h3>货物明细</h3><DataTable :data="detail.items" :columns="itemColumns" :show-pagination="false" row-key="id" empty-text="暂无货物明细" />
+      <template v-if="detail.needRelabel"><h3>换标绑定明细</h3><DataTable :data="detail.relabelBindings" :columns="bindingColumns" :show-pagination="false" row-key="customerCartonMark" empty-text="暂无换标绑定明细" /></template>
+      <template v-if="detail.pallets?.length"><h3>PDA 打托实测</h3><DataTable :data="detail.pallets" :columns="palletColumns" :show-pagination="false" row-key="id" empty-text="暂无打托数据" /></template>
+      <el-form-item label="审核结论" required><el-radio-group v-model="form.decision"><el-radio-button value="APPROVE"><CheckCircle2 :size="15" />审核通过</el-radio-button><el-radio-button value="REJECT"><XCircle :size="15" />驳回</el-radio-button></el-radio-group></el-form-item>
+      <el-form-item :label="form.decision === 'REJECT' ? '驳回原因' : '审核备注'" :required="form.decision === 'REJECT'"><el-input v-model="form.remark" type="textarea" :rows="3" maxlength="1000" show-word-limit placeholder="请输入审核备注（选填）" /></el-form-item>
+    </el-form>
+  </AppDialog>
+</template>
+
+<style scoped>
+.review-form { display: grid; gap: var(--admin-space-5); }
+.review-heading { display: flex; align-items: baseline; justify-content: space-between; gap: var(--admin-space-5); }
+.review-heading span { color: var(--cc-muted); font-size: var(--admin-font-caption); }
+h3 { margin: 2px 0 0; font-size: var(--admin-font-section); }
+.review-form :deep(.el-form-item) { margin: var(--admin-space-1) 0 0; }
+.review-form :deep(.el-radio-button__inner) { display: inline-flex; align-items: center; gap: var(--admin-space-2); }
+</style>
diff --git a/src/modules/overseas-warehouse/dispatchVehicleSpecs.ts b/src/modules/overseas-warehouse/dispatchVehicleSpecs.ts
new file mode 100644
index 00000000..30f5832e
--- /dev/null
+++ b/src/modules/overseas-warehouse/dispatchVehicleSpecs.ts
@@ -0,0 +1,9 @@
+export const dispatchVehicleSpecs = [
+  { value: 'LARGE_30', label: '大车（30托）', capacity: 30, maxWeightLb: 40000 },
+  { value: 'SMALL_15', label: '小车（15托）', capacity: 15, maxWeightLb: 10000 },
+] as const
+
+export const dispatchVehicleSizeOptions = dispatchVehicleSpecs.map(({ capacity }) => ({
+  label: `${capacity}托`,
+  value: `${capacity}托`,
+}))
diff --git a/src/modules/overseas-warehouse/inventoryPresentation.test.ts b/src/modules/overseas-warehouse/inventoryPresentation.test.ts
new file mode 100644
index 00000000..f2051bc4
--- /dev/null
+++ b/src/modules/overseas-warehouse/inventoryPresentation.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest'
+import { inventoryProductName, toInventoryListItem } from './inventoryPresentation'
+
+describe('overseas inventory presentation adapter', () => {
+  it('maps the latest singular balance DTO fields without inventing position data', () => {
+    const row = toInventoryListItem({
+      id: '2089652067743272963',
+      customerId: '990018',
+      customerName: 'Acceptance Customer',
+      overseasWarehouseId: '990018000000000001',
+      overseasWarehouseName: 'Acceptance US Warehouse',
+      inboundOrderId: '2089652066950549505',
+      inboundOrderNo: 'LIP2089652067021852673',
+      inboundCode: 'ACCEPT-20260818-R4-IN-03B',
+      skuCode: 'SKU-ACCEPT-1',
+      productNameZh: '验收商品',
+      productNameEn: 'Acceptance Product',
+      totalPackages: 20,
+      availablePackages: 18,
+      holdPackages: 2,
+      allocatedPackages: 0,
+      pickedPackages: 0,
+      inTransitPackages: 0,
+      receivingPackages: 0,
+      procurementPackages: 0,
+      updatedAt: '2026-08-18T17:54:11',
+    })
+
+    expect(row).toMatchObject({
+      id: '2089652067743272963',
+      customerId: '990018',
+      owner: 'Acceptance Customer',
+      warehouse: 'Acceptance US Warehouse',
+      sku: 'SKU-ACCEPT-1',
+      productName: '验收商品',
+      location: '—',
+      onHand: 20,
+      available: 18,
+      held: 2,
+      status: '存在暂扣',
+      updatedAt: '2026-08-18 17:54:11',
+    })
+  })
+
+  it('shows an unknown owner as a dash and never substitutes customerId', () => {
+    const row = toInventoryListItem({
+      id: '1', customerId: '2092618717861048321', customerName: null,
+      overseasWarehouseId: '3', inboundOrderId: '4', inboundCode: 'IN-1',
+      totalPackages: 1, availablePackages: 1, holdPackages: 0, allocatedPackages: 0,
+      pickedPackages: 0, inTransitPackages: 0, receivingPackages: 0, procurementPackages: 0,
+    })
+    expect(row.owner).toBe('—')
+    expect(row.owner).not.toBe(row.customerId)
+  })
+
+  it('uses only the formal overseas warehouse name snapshot', () => {
+    const row = toInventoryListItem({
+      id: '1', customerId: '2', customerName: '客户甲', overseasWarehouseId: '3',
+      overseasWarehouseCode: 'LAX', overseasWarehouseName: null, destinationWarehouseName: 'ONT8目的仓',
+      inboundOrderId: '4', inboundCode: 'IN-1', totalPackages: 1, availablePackages: 1,
+      holdPackages: 0, allocatedPackages: 0, pickedPackages: 0, inTransitPackages: 0,
+      receivingPackages: 0, procurementPackages: 0,
+    })
+    expect(row.warehouse).toBe('—')
+    expect(row.warehouse).not.toBe('LAX')
+    expect(row.warehouse).not.toBe('ONT8目的仓')
+  })
+
+  it('falls back to the English product name only when the Chinese name is absent', () => {
+    expect(inventoryProductName({
+      id: '1', customerId: '2', overseasWarehouseId: '3', inboundOrderId: '4', inboundCode: 'IN-1',
+      productNameEn: 'English Product', totalPackages: 0, availablePackages: 0, holdPackages: 0,
+      allocatedPackages: 0, pickedPackages: 0, inTransitPackages: 0, receivingPackages: 0,
+      procurementPackages: 0,
+    })).toBe('English Product')
+  })
+})
diff --git a/src/modules/overseas-warehouse/inventoryPresentation.ts b/src/modules/overseas-warehouse/inventoryPresentation.ts
new file mode 100644
index 00000000..434b1166
--- /dev/null
+++ b/src/modules/overseas-warehouse/inventoryPresentation.ts
@@ -0,0 +1,46 @@
+import type { InventoryBalanceDto } from './api/inventory'
+import type { InventoryListItem } from './types'
+import { formatOverseasDateTime } from './lastMilePresentation'
+
+function text(value: unknown) {
+  const normalized = String(value ?? '').trim()
+  return normalized || '—'
+}
+
+function count(value: unknown) {
+  const normalized = Number(value)
+  return Number.isFinite(normalized) ? normalized : 0
+}
+
+export function inventoryProductName(dto: InventoryBalanceDto) {
+  return text(dto.productNameZh || dto.productNameEn)
+}
+
+export function inventoryStatusLabel(dto: InventoryBalanceDto) {
+  if (count(dto.holdPackages) > 0) return '存在暂扣'
+  if (count(dto.availablePackages) <= 0) return '无可用库存'
+  return '正常'
+}
+
+export function toInventoryListItem(dto: InventoryBalanceDto): InventoryListItem {
+  return {
+    id: String(dto.id),
+    customerId: String(dto.customerId),
+    warehouseId: String(dto.overseasWarehouseId || ''),
+    inboundOrderNo: text(dto.inboundOrderNo) === '—' ? '' : String(dto.inboundOrderNo),
+    inboundCode: text(dto.inboundCode) === '—' ? '' : String(dto.inboundCode),
+    owner: text(dto.customerName),
+    warehouse: text(dto.overseasWarehouseName),
+    sku: text(dto.skuCode),
+    productName: inventoryProductName(dto),
+    location: '—',
+    onHand: count(dto.totalPackages),
+    available: count(dto.availablePackages),
+    held: count(dto.holdPackages),
+    looseboard: '—',
+    inTransit: count(dto.inTransitPackages),
+    purchase: count(dto.procurementPackages),
+    status: inventoryStatusLabel(dto),
+    updatedAt: formatOverseasDateTime(dto.updatedAt),
+  }
+}
diff --git a/src/modules/overseas-warehouse/lastMilePresentation.test.ts b/src/modules/overseas-warehouse/lastMilePresentation.test.ts
new file mode 100644
index 00000000..17c475e8
--- /dev/null
+++ b/src/modules/overseas-warehouse/lastMilePresentation.test.ts
@@ -0,0 +1,117 @@
+import { describe, expect, it } from 'vitest'
+import { formatOverseasDateTime, inventoryBusinessTypeLabel, lastMileOrderReference, relabelBusinessStatusLabel, toLastMileOrderListItem } from './lastMilePresentation'
+
+describe('last-mile order presentation adapter', () => {
+  it('formats overseas timestamps with zero-padded seconds', () => {
+    expect(formatOverseasDateTime('2026-08-27T16:19:46')).toBe('2026-08-27 16:19:46')
+    expect(formatOverseasDateTime('2026-08-07T06:09:04')).toBe('2026-08-07 06:09:04')
+    expect(formatOverseasDateTime('2026-08-07')).toMatch(/^2026-08-07 /)
+    expect(formatOverseasDateTime(new Date(2026, 7, 7, 6, 9, 4))).toBe('2026-08-07 06:09:04')
+    expect(formatOverseasDateTime('')).toBe('—')
+    expect(formatOverseasDateTime('not-a-date')).toBe('not-a-date')
+  })
+
+  it.each([
+    ['IN_TRANSIT', '在途入账'],
+    ['STOCK_IN', '入库'],
+    ['STOCK_IN_TRANSIT_RELEASE', '在途库存转入'],
+    ['HOLD', '库存暂扣'],
+    ['RELEASE', '解除暂扣'],
+    ['ALLOCATE', '库存分配'],
+    ['UNALLOCATE', '取消分配'],
+    ['PICK', '拣货'],
+    ['SHIP', '出库'],
+    ['ADJUST', '库存调整'],
+    ['STOCKTAKE_ADJUST', '盘点调整'],
+    ['PALLET_ASSEMBLE', '组托'],
+    ['PALLET_DISASSEMBLE', '拆托'],
+    ['PALLET_SWAP', '换托'],
+    ['PALLET_UNBIND', '解托'],
+  ])('maps inventory business type %s to %s', (code, label) => {
+    expect(inventoryBusinessTypeLabel(code)).toBe(label)
+  })
+
+  it('maps backend codes, associations and long ids without inventing data', () => {
+    const row = toLastMileOrderListItem({
+      id: '190000000000000099', customerId: '190000000000000001', orderNo: 'LL-001', orderType: 'ONE_CLICK_DROPSHIP', currentStatus: 'PENDING_ASSIGNMENT',
+      abnormal: true, detained: false, packageCount: 12, palletMergeFlag: 'REQUIRED', deliveryOrderNo: 'DEL-READ-ONLY', outboundOrderNo: 'OUT-READ-ONLY',
+    })
+    expect(row).toMatchObject({
+      id: '190000000000000099', customerId: '190000000000000001', orderType: '一件代发', status: '待分配',
+      warning: '异常', abnormal: '是', held: '否', cartons: 12, consolidated: '待合托', palletMergeFlag: 'REQUIRED', dispatchOrderNo: 'DEL-READ-ONLY', outboundOrderNo: 'OUT-READ-ONLY',
+    })
+    expect(row.rejectedAt).toBe('—')
+  })
+
+  it('shows the backend customerName and never guesses the owner from customerId', () => {
+    expect(toLastMileOrderListItem({
+      id: '1', customerId: '190000000000000001', customerName: '华远贸易', orderNo: 'LMO-260827-0001',
+    }).owner).toBe('华远贸易')
+    expect(toLastMileOrderListItem({
+      id: '2', customerId: '190000000000000002', customerName: null, orderNo: 'LMO-260827-0002',
+    }).owner).toBe('—')
+  })
+
+  it('preserves the frozen overseas receiving warehouse id and code as strings', () => {
+    const row = toLastMileOrderListItem({
+      id: '190000000000000099', customerId: '190000000000000001', orderNo: 'LMO-260908-0001',
+      overseasWarehouseId: '190000000000000123', overseasWarehouseCode: 'LAX01', overseasWarehouseName: '洛杉矶接柜仓',
+    })
+
+    expect(row.overseasWarehouseId).toBe('190000000000000123')
+    expect(row.overseasWarehouseCode).toBe('LAX01')
+    expect(row.warehouse).toBe('洛杉矶接柜仓')
+  })
+
+  it('preserves the exact server LMO short number without padding, prefixing or deriving it from id', () => {
+    const serverOrderNo = 'LMO-9A7'
+    const row = toLastMileOrderListItem({ id: '2092873463568596994', customerId: '100', orderNo: serverOrderNo })
+    expect(row.orderNo).toBe(serverOrderNo)
+    expect(lastMileOrderReference(serverOrderNo)).toBe(serverOrderNo)
+    expect(row.orderNo).not.toContain(row.id)
+  })
+
+  it('preserves real metrics and distinguishes zero from unknown fields and times', () => {
+    const estimatedArrivalAt = '2026-08-27T12:30:00Z'
+    const row = toLastMileOrderListItem({
+      id: '3', customerId: '190000000000000003', orderNo: 'LMO-260827-0003',
+      palletCount: 3, packageCount: 0, volumeCbm: 12.75, productQuantity: null, volumeWeightKg: 88.6,
+      estimatedArrivalAt, actualArrivalAt: null, estimatedWarehouseAt: null,
+    })
+    expect(row).toMatchObject({
+      pallets: 3, cartons: 0, volume: 12.75, quantity: '—', volumeWeight: 88.6,
+      portEta: formatOverseasDateTime(estimatedArrivalAt), portAta: '—',
+      estimatedWarehouseAt: '', warehouseEta: '—',
+    })
+  })
+
+  it.each([
+    ['RELABEL_APPLICATION', '换标下单'],
+    ['WAREHOUSE_TRANSFER', '仓储转运'],
+    ['RETURN_RELABEL', '退货换标'],
+    ['LOCAL_LOOSEBOARD', '本土散板'],
+    ['CARGO_DISCARD', '货物废弃订单'],
+  ])('maps %s to its Chinese display name', (orderType, expected) => {
+    const row = toLastMileOrderListItem({ id: '1', customerId: '100', orderNo: 'LL-1', orderType })
+    expect(row.orderType).toBe(expected)
+  })
+
+  it('shows related inbound numbers instead of the shared tail-leg order number', () => {
+    const row = toLastMileOrderListItem({
+      id: '11', customerId: '100', orderNo: 'LMO-1', palletMergeFlag: 'MERGED',
+      palletMergeBatchId: 'PMG-1', palletMergeInboundNos: ['NYEXX2608280001', 'NYEXX2608280002'],
+    })
+
+    expect(row.palletMergeRelation).toBe('NYEXX2608280001、NYEXX2608280002')
+  })
+
+  it.each([
+    ['PENDING_PROCESSING', '待处理'],
+    ['PROCESSING', '处理中'],
+    ['CUSTOMER_CONFIRM_PENDING', '待处理'],
+    ['READY_FOR_OUTBOUND', '换标完成'],
+    ['COMPLETED', '换标完成'],
+  ])('collapses internal relabel node %s into business status %s', (status, expected) => {
+    expect(relabelBusinessStatusLabel(status)).toBe(expected)
+  })
+})
diff --git a/src/modules/overseas-warehouse/lastMilePresentation.ts b/src/modules/overseas-warehouse/lastMilePresentation.ts
new file mode 100644
index 00000000..7a0d9bf4
--- /dev/null
+++ b/src/modules/overseas-warehouse/lastMilePresentation.ts
@@ -0,0 +1,162 @@
+import type { LastMileOrderSummaryDto } from './api/lastMileOrders'
+import type { LastMileOrderListItem } from './types'
+
+const orderTypeLabels: Record<string, string> = {
+  ONE_CLICK_DROPSHIP: '一件代发',
+  FIRST_LEG: '头程订单',
+  RELABEL_APPLICATION: '换标下单',
+  WAREHOUSE_TRANSFER: '仓储转运',
+  RETURN_RELABEL: '退货换标',
+  LOCAL_LOOSEBOARD: '本土散板',
+  CARGO_DISCARD: '货物废弃订单',
+  REJECTED: '拒收订单',
+  EXPRESS: '快递订单',
+}
+
+const statusLabels: Record<string, string> = {
+  PENDING_REVIEW: '待审核',
+  APPROVED: '审核通过',
+  PENDING_ASSIGNMENT: '待分配',
+  DESTINATION_ASSIGNED: '已分配目的仓',
+  INBOUND_PLANNED: '已生成入库计划',
+  PENDING_PROCESSING: '待处理',
+  PROCESSING: '处理中',
+  COMPLETED: '已完成',
+  CANCELLED: '已取消',
+}
+
+const inventoryBusinessTypeLabels: Record<string, string> = {
+  IN_TRANSIT: '在途入账',
+  STOCK_IN: '入库',
+  STOCK_IN_TRANSIT_RELEASE: '在途库存转入',
+  HOLD: '库存暂扣',
+  RELEASE: '解除暂扣',
+  ALLOCATE: '库存分配',
+  UNALLOCATE: '取消分配',
+  PICK: '拣货',
+  SHIP: '出库',
+  ADJUST: '库存调整',
+  STOCKTAKE_ADJUST: '盘点调整',
+  PALLET_ASSEMBLE: '组托',
+  PALLET_DISASSEMBLE: '拆托',
+  PALLET_SWAP: '换托',
+  PALLET_UNBIND: '解托',
+}
+
+function text(value: unknown) {
+  const normalized = String(value ?? '').trim()
+  return normalized || '—'
+}
+
+function metric(value: number | null | undefined): number | '—' {
+  return value != null && Number.isFinite(value) ? Number(value) : '—'
+}
+
+function yesNo(value: boolean | null | undefined) {
+  return value == null ? '—' : value ? '是' : '否'
+}
+
+export function lastMileStatusLabel(value: unknown) {
+  const code = String(value ?? '').trim()
+  return statusLabels[code] || text(code)
+}
+
+// 认领后显示处理中，可出库节点统一显示换标完成。
+export function relabelBusinessStatusLabel(value: unknown) {
+  const code = String(value ?? '').trim()
+  if (code === 'PROCESSING') return '处理中'
+  if (!code || code === 'NOT_REQUIRED') return '—'
+  return ['READY_FOR_OUTBOUND', 'COMPLETED'].includes(code) ? '换标完成' : '待处理'
+}
+
+export function lastMileOrderTypeLabel(value: unknown) {
+  const code = String(value ?? '').trim()
+  return orderTypeLabels[code] || text(code)
+}
+
+export function inventoryBusinessTypeLabel(value: unknown) {
+  const code = String(value ?? '').trim()
+  return inventoryBusinessTypeLabels[code] || text(code)
+}
+
+export function lastMileOrderReference(value: unknown, emptyLabel = '—') {
+  const serverValue = value == null ? '' : String(value)
+  return serverValue || emptyLabel
+}
+
+export function formatOverseasDateTime(value: unknown) {
+  const raw = String(value ?? '').trim()
+  if (!raw) return '—'
+  const dateOnly = /^(\d{4})-(\d{2})-(\d{2})$/.exec(raw)
+  const date = value instanceof Date
+    ? new Date(value.getTime())
+    : typeof value === 'number'
+      ? new Date(value)
+      : dateOnly
+        ? new Date(Number(dateOnly[1]), Number(dateOnly[2]) - 1, Number(dateOnly[3]))
+        : new Date(raw)
+  if (Number.isNaN(date.getTime())) return raw
+  const pad = (part: number) => String(part).padStart(2, '0')
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`
+}
+
+export function palletMergeLabel(value: unknown) {
+  const code = String(value ?? '').trim()
+  return ({ REQUIRED: '待合托', MERGED: '已合托' } as Record<string, string>)[code] || (code ? text(code) : '未标记')
+}
+
+export function toLastMileOrderListItem(dto: LastMileOrderSummaryDto): LastMileOrderListItem {
+  return {
+    id: String(dto.id),
+    customerId: String(dto.customerId),
+    sourceContainerBookingId: String(dto.sourceContainerBookingId ?? '').trim(),
+    orderNo: lastMileOrderReference(dto.orderNo),
+    orderTypeCode: String(dto.orderType ?? '').trim(),
+    currentStatusCode: String(dto.currentStatus ?? '').trim(),
+    warning: dto.abnormal ? '异常' : '—',
+    orderType: text(dto.orderTypeName || lastMileOrderTypeLabel(dto.orderType)),
+    rejectedAt: '—',
+    inboundCode: text(dto.inboundCode),
+    lxCode: text(dto.lxCode),
+    owner: text(dto.customerName),
+    overseasWarehouseId: String(dto.overseasWarehouseId ?? '').trim(),
+    overseasWarehouseCode: String(dto.overseasWarehouseCode ?? '').trim(),
+    warehouse: text(dto.overseasWarehouseName),
+    transferWarehouse: text(dto.transferWarehouseName),
+    fbaWarehouse: text(dto.fbaWarehouseCode),
+    containerNo: text(dto.containerNo),
+    containerNode: text(dto.containerNode),
+    abnormal: yesNo(dto.abnormal),
+    held: yesNo(dto.detained),
+    detained: Boolean(dto.detained),
+    holdChargeable: Boolean(dto.holdChargeable),
+    holdReason: String(dto.holdReason ?? '').trim(),
+    manualNodeOverride: Boolean(dto.manualOverrideEnabled),
+    version: Number(dto.version ?? 0),
+    pallets: metric(dto.palletCount),
+    cartons: metric(dto.packageCount),
+    volume: metric(dto.volumeCbm),
+    quantity: metric(dto.productQuantity),
+    volumeWeight: metric(dto.volumeWeightKg),
+    portEta: formatOverseasDateTime(dto.estimatedArrivalAt),
+    portAta: formatOverseasDateTime(dto.actualArrivalAt),
+    estimatedWarehouseAt: String(dto.estimatedWarehouseAt ?? '').trim(),
+    warehouseEta: formatOverseasDateTime(dto.estimatedWarehouseAt),
+    inboundOrderNo: text(dto.inboundOrderNo),
+    dispatchStatus: dto.dispatchStatus === 'SCHEDULED' ? '已排车' : '未排车',
+    outboundOrderNo: text(dto.outboundOrderNo),
+    dispatchOrderNo: text(dto.deliveryOrderNo),
+    relabelOrderNo: text(dto.relabelOrderNo),
+    relabelStatus: relabelBusinessStatusLabel(dto.relabelStatus),
+    consolidated: palletMergeLabel(dto.palletMergeFlag),
+    palletMergeFlag: String(dto.palletMergeFlag ?? '').trim(),
+    palletMergeRelation: Array.isArray(dto.palletMergeInboundNos) && dto.palletMergeInboundNos.length
+      ? dto.palletMergeInboundNos.map((value) => text(value)).join('、')
+      : dto.palletMergeBatchId ? `批次 ${text(dto.palletMergeBatchId)}` : '—',
+    status: lastMileStatusLabel(dto.currentStatus),
+    internalRemark: text(dto.privateRemark),
+    customerRemark: text(dto.customerRemark),
+    warehouseRemark: text(dto.warehouseRemark),
+    createdAt: formatOverseasDateTime(dto.createdAt),
+  }
+}
diff --git a/src/modules/overseas-warehouse/layoutAcceptance.test.ts b/src/modules/overseas-warehouse/layoutAcceptance.test.ts
new file mode 100644
index 00000000..81b0b92f
--- /dev/null
+++ b/src/modules/overseas-warehouse/layoutAcceptance.test.ts
@@ -0,0 +1,81 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const page = (name: string) => readFileSync(resolve(process.cwd(), 'src/modules/overseas-warehouse/pages', name), 'utf8')
+const component = (name: string) => readFileSync(resolve(process.cwd(), 'src/modules/overseas-warehouse/components', name), 'utf8')
+
+describe('overseas warehouse 1920px layout acceptance', () => {
+  it('keeps action columns first and wide enough for every visible action', () => {
+    const widths: Record<string, number> = {
+      'LastMileOrdersView.vue': 330,
+      'InboundOrdersView.vue': 300,
+      'DispatchesView.vue': 380,
+      'OutboundsView.vue': 180,
+      'DeliveryOrdersView.vue': 300,
+      'RelabelOrdersView.vue': 180,
+      'PalletsView.vue': 180,
+      'InventoryView.vue': 110,
+    }
+    for (const [name, width] of Object.entries(widths)) {
+      const source = page(name)
+      const columns = source.slice(source.indexOf('const columns'), source.indexOf('async function', source.indexOf('const columns')))
+      expect(columns).toMatch(new RegExp(`key: 'actions',[\\s\\S]*?label: '操作',[\\s\\S]*?width: ${width},[\\s\\S]*?fixed: 'left'`))
+      expect(columns.indexOf("key: 'actions'")).toBeLessThan(columns.indexOf("label:", columns.indexOf("key: 'actions'") + 20))
+    }
+  })
+
+  it('keeps all inbound-order row actions on one line', () => {
+    const source = page('InboundOrdersView.vue')
+    expect(source).toContain('<template #actions="{ row }"><div class="row-actions density-actions">')
+    expect(source).toContain('.row-actions { min-width: max-content; flex-wrap: nowrap; white-space: nowrap; }')
+    expect(source).toContain('.row-actions :deep(.el-button) { flex: 0 0 auto; }')
+    expect(readFileSync(resolve(process.cwd(), 'src/styles/adminDensity.css'), 'utf8')).toContain('.density-actions > :is(.el-button, .el-dropdown) { margin-left: 0; }')
+  })
+
+  it('assigns explicit desktop widths to dense query inputs', () => {
+    for (const name of ['LastMileOrdersView.vue', 'InboundOrdersView.vue', 'OutboundsView.vue', 'DeliveryOrdersView.vue', 'RelabelOrdersView.vue', 'PalletsView.vue', 'InventoryView.vue']) {
+      const source = page(name)
+      const fieldLines = source.split(/\r?\n/).filter((line) => /type: '(input|select|daterange)'/.test(line))
+      expect(fieldLines.length, name).toBeGreaterThan(0)
+      expect(fieldLines.every((line) => line.includes('width:')), `${name} has a query field without width`).toBe(true)
+    }
+  })
+
+  it('provides semantic placeholders for editable form controls', () => {
+    for (const name of ['LastMileOrdersView.vue', 'InboundOrdersView.vue', 'OutboundsView.vue', 'DeliveryOrdersView.vue', 'RelabelOrdersView.vue', 'PalletsView.vue', 'InventoryView.vue']) {
+      const editableControls = [...page(name).matchAll(/<el-(?:input-number|date-picker|input|select)[ >][^>]*>/g)]
+        .map(([tag]) => tag)
+        .filter((tag) => !/\s(?:readonly|disabled)(?:\s|\/?>)/.test(tag))
+        .filter((tag) => !tag.includes('v-model="planEditForm.warehouseId"'))
+      expect(editableControls.every((tag) => tag.includes('placeholder=')), `${name} has an editable control without placeholder`).toBe(true)
+    }
+  })
+
+  it('uses four-field desktop density and full-width form controls', () => {
+    const sharedDetail = component('OverseasReadOnlyDetail.vue')
+    expect(sharedDetail).toContain('grid-template-columns: repeat(2, minmax(0, 1fr))')
+    expect(page('LastMileOrderDetailView.vue')).toContain('density-fields')
+    expect(page('InboundOrderDetailView.vue')).toContain('density-fields')
+    expect(page('DispatchDetailView.vue')).toContain('.document-section { grid-column: 1 / -1; }')
+    expect(page('DispatchDetailView.vue')).toContain('density-fields')
+    expect(page('DeliveryOrderDetailView.vue')).toContain('density-fields')
+    expect(page('InventoryDetailView.vue')).toContain('density-fields')
+    const outbounds = page('OutboundsView.vue')
+    expect(outbounds).toContain('.create-outbound-form :deep(.el-form-item__content > .el-input-number) { width: 100%; }')
+    expect(outbounds).not.toContain('.create-outbound-form :deep(.el-select)')
+    expect(outbounds).toContain('.candidate-pagination :deep(.el-pagination__sizes .el-select), .return-pagination :deep(.el-pagination__sizes .el-select) { width: 128px; }')
+    expect(page('RelabelOrdersView.vue')).toContain('.el-form :deep(.el-date-editor) { width: 100%; }')
+    expect(page('PalletsView.vue')).toContain('.el-form :deep(.el-input-number) { width: 100%; }')
+    expect(page('RelabelOrdersView.vue')).toContain('.el-form :deep(.el-row) { margin-left: 0 !important; margin-right: 0 !important; }')
+    expect(page('PalletsView.vue')).toContain('.el-form :deep(.el-row) { margin-left: 0 !important; margin-right: 0 !important; }')
+    const lastMileDetail = page('LastMileOrderDetailView.vue')
+    expect(lastMileDetail).toContain('class="fee-form-grid"')
+    expect(lastMileDetail).toContain('filterable allow-create clearable default-first-option')
+    expect(lastMileDetail).toContain('.fee-form { min-width: 0; overflow-x: hidden; }')
+    expect(lastMileDetail).toContain('.fee-form :deep(.el-select), .fee-form :deep(.el-input-number) { width: 100%; }')
+    expect(lastMileDetail).toContain("field.label === '入仓码' || field.label === '集装箱号'")
+    expect(lastMileDetail).toContain(':title="isSingleLineBusinessField(field) ? String(field.value) : undefined"')
+    expect(lastMileDetail).toContain('.detail-field-value--business { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }')
+  })
+})
diff --git a/src/modules/overseas-warehouse/pages/CartonDetailView.vue b/src/modules/overseas-warehouse/pages/CartonDetailView.vue
new file mode 100644
index 00000000..77dc9d41
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/CartonDetailView.vue
@@ -0,0 +1,16 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import OverseasReadOnlyDetail from '../components/OverseasReadOnlyDetail.vue'
+
+const route = useRoute()
+const router = useRouter()
+const cartonId = computed(() => String(route.params.cartonId || '—'))
+const groups = [
+  { title: '基础信息', fields: ['箱号', '所属FBA仓', '状态', '关联托盘', '关联入库单', '关联出库单'] },
+  { title: '商品信息', fields: ['商品SKU', '中文品名', '数量', '重量(kg)', '创建时间', '更新时间', '备注'] },
+]
+function back() { void router.push({ name: 'overseas-cartons' }) }
+</script>
+
+<template><OverseasReadOnlyDetail title="箱号详情" reference-label="箱号" :reference-value="cartonId" back-label="返回箱号管理" domain="箱号详情" :groups="groups" @back="back" /></template>
diff --git a/src/modules/overseas-warehouse/pages/CartonsView.vue b/src/modules/overseas-warehouse/pages/CartonsView.vue
new file mode 100644
index 00000000..8e27e094
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/CartonsView.vue
@@ -0,0 +1,69 @@
+<script setup lang="ts">
+import { reactive, ref } from 'vue'
+import { Eye, Pencil, Plus } from '@lucide/vue'
+import { useRouter } from 'vue-router'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import ContractPendingNotice from '../components/ContractPendingNotice.vue'
+import ContractPendingFormDialog from '../components/ContractPendingFormDialog.vue'
+import { overseasWarehousePermissions as permission } from '../permissions'
+import type { CartonListItem } from '../types'
+
+const access = useAccessPreviewStore()
+const router = useRouter()
+const rows = ref<CartonListItem[]>([])
+const page = ref(1)
+const pageSize = ref(10)
+const filters = ref<QueryModel>({ cartonNo: '', fbaWarehouse: '', status: '' })
+const fields: QueryField[] = [
+  { key: 'cartonNo', type: 'input', label: '箱号', placeholder: '请输入箱号', width: 190 },
+  { key: 'fbaWarehouse', type: 'select', label: '所属FBA仓', placeholder: '全部FBA仓', width: 180, options: [] },
+  { key: 'status', type: 'select', label: '状态', placeholder: '全部状态', width: 150, options: ['在库', '已出库'].map((value) => ({ label: value, value })) },
+]
+const columns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 180, fixed: 'left', slotName: 'actions' },
+  { key: 'cartonNo', label: '箱号', minWidth: 180 }, { key: 'fbaWarehouse', label: '所属FBA仓', minWidth: 150 },
+  { key: 'sku', label: '商品SKU', minWidth: 150 }, { key: 'productName', label: '中文品名', minWidth: 180 },
+  { key: 'quantity', label: '数量', width: 100, align: 'right' }, { key: 'weight', label: '重量(kg)', width: 110, align: 'right' },
+  { key: 'status', label: '状态', width: 100 },
+]
+const dialogOpen = ref(false)
+const dialogMode = ref<'create' | 'edit'>('create')
+const form = reactive({ cartonNo: '', fbaWarehouse: '', sku: '', productName: '', quantity: undefined as number | undefined, weight: undefined as number | undefined, palletNo: '', inboundOrderNo: '', outboundOrderNo: '', status: '在库', remark: '' })
+
+function optionalNumber(value: unknown) { const number = Number(value); return value === '' || value == null || !Number.isFinite(number) ? undefined : number }
+function openForm(mode: 'create' | 'edit', source?: object) { const row = source as CartonListItem | undefined; dialogMode.value = mode; Object.assign(form, { cartonNo: '', fbaWarehouse: '', sku: '', productName: '', quantity: undefined, weight: undefined, palletNo: '', inboundOrderNo: '', outboundOrderNo: '', status: '在库', remark: '' }); if (mode === 'edit' && row) Object.assign(form, { cartonNo: String(row.cartonNo || ''), fbaWarehouse: String(row.fbaWarehouse || ''), sku: String(row.sku || ''), productName: String(row.productName || ''), quantity: optionalNumber(row.quantity), weight: optionalNumber(row.weight), palletNo: String(row.palletNo || ''), inboundOrderNo: String(row.inboundOrderNo || ''), outboundOrderNo: String(row.outboundOrderNo || ''), status: String(row.status || '在库'), remark: String(row.remark || '') }); dialogOpen.value = true }
+function canEditCarton(source: object) { return String((source as CartonListItem).status) === '在库' }
+function openDetail(source: object) { const row = source as CartonListItem; void router.push({ name: 'overseas-carton-detail', params: { cartonId: String(row.cartonNo) } }) }
+</script>
+
+<template>
+  <AdminPage><ListPageLayout aria-label="箱号管理列表">
+    <template #toolbar><QueryToolbar v-model="filters" class="surface-panel" :fields="fields" ariaLabel="箱号筛选" preference-key="overseas-cartons-query" @search="page = 1" /></template>
+    <template #state><ContractPendingNotice domain="箱号管理" /></template>
+    <section class="surface-panel table-panel"><DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :total="0" preference-key="overseas-cartons" row-key="cartonNo" empty-text="海外区域箱号查询契约待接入">
+      <template #toolbar-actions><el-button v-if="access.can(permission.cartonCreate)" type="primary" @click="openForm('create')"><Plus :size="16" />新增箱号</el-button></template>
+      <template #actions="{ row }"><el-button size="small" plain type="primary" @click="openDetail(row)"><Eye :size="15" />查看</el-button><el-button v-if="access.can(permission.cartonEdit) && canEditCarton(row)" size="small" plain @click="openForm('edit', row)"><Pencil :size="15" />编辑</el-button></template>
+      <template #pagination-left>共 0 条箱号记录</template>
+    </DataTable></section>
+  </ListPageLayout>
+  <ContractPendingFormDialog v-model="dialogOpen" :title="dialogMode === 'create' ? '新增箱号' : '编辑箱号'" width="min(860px, calc(100vw - 28px))" domain="箱号">
+    <el-form label-position="top"><el-row :gutter="16">
+      <el-col :span="12"><el-form-item label="箱号" required><el-input v-model="form.cartonNo" :readonly="dialogMode === 'edit'" placeholder="请输入箱号" /></el-form-item></el-col>
+      <el-col :span="12"><el-form-item label="所属 FBA 仓" required><el-select v-model="form.fbaWarehouse" placeholder="FBA仓候选接口待接入" disabled /></el-form-item></el-col>
+      <el-col :span="12"><el-form-item label="商品 SKU" required><el-input v-model="form.sku" placeholder="请输入商品 SKU" /></el-form-item></el-col>
+      <el-col :span="12"><el-form-item label="中文品名" required><el-input v-model="form.productName" placeholder="请输入中文品名" /></el-form-item></el-col>
+      <el-col :span="12"><el-form-item label="数量" required><el-input-number v-model="form.quantity" :min="1" :precision="0" controls-position="right" placeholder="请输入数量" /></el-form-item></el-col>
+      <el-col :span="12"><el-form-item label="重量(kg)" required><el-input-number v-model="form.weight" :min="0.01" :precision="2" controls-position="right" placeholder="请输入重量" /></el-form-item></el-col>
+      <el-col :span="12"><el-form-item label="关联托盘"><el-input v-model="form.palletNo" placeholder="请输入关联托盘号" /></el-form-item></el-col>
+      <el-col :span="12"><el-form-item label="关联入库单"><el-input v-model="form.inboundOrderNo" placeholder="请输入关联入库单号" /></el-form-item></el-col>
+      <el-col :span="12"><el-form-item label="关联出库单"><el-input v-model="form.outboundOrderNo" readonly /></el-form-item></el-col>
+      <el-col :span="12"><el-form-item label="状态"><el-input v-model="form.status" readonly /></el-form-item></el-col>
+      <el-col :span="24"><el-form-item label="备注"><el-input v-model="form.remark" type="textarea" :rows="3" maxlength="500" show-word-limit placeholder="请输入备注（选填）" /></el-form-item></el-col>
+    </el-row></el-form>
+  </ContractPendingFormDialog>
+  </AdminPage>
+</template>
diff --git a/src/modules/overseas-warehouse/pages/CustomerVisitsView.test.ts b/src/modules/overseas-warehouse/pages/CustomerVisitsView.test.ts
new file mode 100644
index 00000000..e452508d
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/CustomerVisitsView.test.ts
@@ -0,0 +1,80 @@
+import ElementPlus from 'element-plus'
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { getCustomerVisit, listCustomerVisits, saveCustomerVisit, uploadCustomerVisitAttachment } from '../api/customerVisits'
+import CustomerVisitsView from './CustomerVisitsView.vue'
+import { commonPhase5Stubs } from './phase5TestStubs'
+
+const canPermission = vi.hoisted(() => vi.fn((_code: string) => false))
+vi.mock('@/core/access/accessPreview', () => ({ useAccessPreviewStore: () => ({ can: canPermission }) }))
+vi.mock('../api/customerVisits', () => ({ listCustomerVisits: vi.fn(), getCustomerVisit: vi.fn(), saveCustomerVisit: vi.fn(), uploadCustomerVisitAttachment: vi.fn() }))
+
+const visit = {
+  id: '9', customerId: '100', deliveryNo: 'DEL-1', deliveryCompletedAt: '2026-09-01T10:00:00',
+  status: 'PENDING' as const, visitCount: 0, attachments: [],
+}
+function mountView() { return mount(CustomerVisitsView, { global: { plugins: [ElementPlus], stubs: commonPhase5Stubs } }) }
+
+describe('CustomerVisitsView permissions and visit material', () => {
+  beforeEach(() => {
+    canPermission.mockReset().mockReturnValue(false)
+    vi.mocked(listCustomerVisits).mockReset().mockResolvedValue({ records: [visit], current: 1, size: 10, total: 1, pages: 1, visitable: 1, pending: 1, completed: 0 })
+    vi.mocked(getCustomerVisit).mockReset().mockResolvedValue({
+      visit,
+      inboundOrders: [{ inboundOrderId: '7', inboundCode: 'IN-1', lastMileOrderId: '6', lastMileOrderNo: 'LM-1', packageCount: 2 }],
+      customerFeedback: '', remark: '',
+    })
+    vi.mocked(saveCustomerVisit).mockReset().mockResolvedValue({ visit, inboundOrders: [] })
+    vi.mocked(uploadCustomerVisitAttachment).mockReset().mockResolvedValue({ fileId: '8', fileName: 'visit.pdf', sizeBytes: 4 })
+  })
+
+  it('hides the visit action without edit permission', async () => {
+    const wrapper = mountView()
+    await flushPromises()
+    expect(wrapper.find('[data-testid="data-table"]').text()).not.toContain('回访')
+    wrapper.unmount()
+  })
+
+  it('validates and submits a customer-scoped visit', async () => {
+    canPermission.mockImplementation(code => code.endsWith(':edit'))
+    const wrapper = mountView()
+    await flushPromises()
+    await wrapper.findAll('button').find(button => button.text() === '回访')!.trigger('click')
+    await flushPromises()
+    expect(getCustomerVisit).toHaveBeenCalledWith('9', '100')
+
+    const dialog = wrapper.find('[data-dialog="客户回访"]')
+    await dialog.find('.dialog-confirm').trigger('click')
+    expect(saveCustomerVisit).not.toHaveBeenCalled()
+    await dialog.find('select').setValue('NORMAL')
+    const textareas = dialog.findAll('textarea')
+    await textareas[0].setValue(' 服务正常 ')
+    await textareas[1].setValue(' 后续关注 ')
+    await dialog.find('.dialog-confirm').trigger('click')
+    await flushPromises()
+    expect(saveCustomerVisit).toHaveBeenCalledWith('9', '100', {
+      selectedInboundOrderId: '7', visitResult: 'NORMAL', customerFeedback: '服务正常', remark: '后续关注', attachments: [],
+    })
+    wrapper.unmount()
+  })
+
+  it('uploads the selected attachment in the visit customer scope', async () => {
+    canPermission.mockImplementation(code => code.endsWith(':edit'))
+    const wrapper = mountView()
+    await flushPromises()
+    await wrapper.findAll('button').find(button => button.text() === '回访')!.trigger('click')
+    await flushPromises()
+    const input = wrapper.find('[data-dialog="客户回访"] input[type="file"]')
+    const inputClick = vi.spyOn(input.element as HTMLInputElement, 'click').mockImplementation(() => {})
+    await wrapper.findAll('button').find(button => button.text() === '选择文件')!.trigger('click')
+    expect(inputClick).toHaveBeenCalledOnce()
+    inputClick.mockRestore()
+    const file = new File(['data'], 'visit.pdf', { type: 'application/pdf' })
+    Object.defineProperty(input.element, 'files', { configurable: true, value: [file] })
+    await input.trigger('change')
+    await flushPromises()
+    expect(uploadCustomerVisitAttachment).toHaveBeenCalledWith('9', '100', file)
+    expect(wrapper.text()).toContain('visit.pdf')
+    wrapper.unmount()
+  })
+})
diff --git a/src/modules/overseas-warehouse/pages/CustomerVisitsView.vue b/src/modules/overseas-warehouse/pages/CustomerVisitsView.vue
new file mode 100644
index 00000000..82bc96c9
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/CustomerVisitsView.vue
@@ -0,0 +1,222 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { onMounted, reactive, ref } from 'vue'
+import { FileUp } from '@lucide/vue'
+import { ElMessage } from 'element-plus'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { formatOverseasDateTime } from '../lastMilePresentation'
+import {
+  getCustomerVisit,
+  listCustomerVisits,
+  saveCustomerVisit,
+  uploadCustomerVisitAttachment,
+  type CustomerVisitAttachment,
+  type CustomerVisitDetail,
+  type CustomerVisitRow,
+} from '../api/customerVisits'
+import { overseasWarehousePermissions as permission } from '../permissions'
+import OrderReferenceText from '../components/OrderReferenceText.vue'
+
+const access = useAccessPreviewStore()
+const rows = ref<CustomerVisitRow[]>([])
+const page = ref(1)
+const pageSize = ref(10)
+const total = ref(0)
+const summary = reactive({ visitable: 0, pending: 0, completed: 0 })
+const loading = ref(false)
+const error = ref<ApiErrorDetails | null>(null)
+const filters = ref<QueryModel>({ keyword: '', status: '', completedAt: [] })
+const fields: QueryField[] = [
+  { key: 'keyword', type: 'input', label: '关键词', placeholder: '派送单号 / 客户 / 联系人' },
+  { key: 'status', type: 'select', label: '回访状态', placeholder: '全部状态', options: [{ label: '待回访', value: 'PENDING' }, { label: '已回访', value: 'COMPLETED' }] },
+  { key: 'completedAt', type: 'daterange', label: '派送完成时间' },
+]
+const columns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 130, fixed: 'left', slotName: 'actions' },
+  { key: 'deliveryNo', prop: 'deliveryNo', label: '派送单号', minWidth: 180, fixed: 'left' },
+  { key: 'customerName', prop: 'customerName', label: '客户', minWidth: 180 },
+  { key: 'contact', label: '联系人', minWidth: 170, formatter: (row: CustomerVisitRow) => [row.contactName, row.contactPhone].filter(Boolean).join(' ') || '—' },
+  { key: 'deliveryCompletedAt', prop: 'deliveryCompletedAt', label: '完成时间', minWidth: 170, formatter: (row: CustomerVisitRow) => formatOverseasDateTime(row.deliveryCompletedAt) },
+  { key: 'destination', prop: 'destination', label: '目的地', minWidth: 140 },
+  { key: 'status', prop: 'status', label: '回访状态', width: 110, slotName: 'status' },
+  { key: 'visitedAt', prop: 'visitedAt', label: '回访时间', minWidth: 170, formatter: (row: CustomerVisitRow) => formatOverseasDateTime(row.visitedAt) },
+  { key: 'visitResult', prop: 'visitResult', label: '回访结果', minWidth: 130, formatter: (row: CustomerVisitRow) => resultLabels[row.visitResult || ''] || '—' },
+  { key: 'attachments', label: '资料', minWidth: 110, formatter: (row: CustomerVisitRow) => row.attachments.length ? `${row.attachments.length} 份` : '—' },
+]
+const resultLabels: Record<string, string> = { SATISFIED: '满意', NORMAL: '正常', FOLLOW_UP: '需跟进', NO_CONTACT: '未联系上' }
+
+async function load(model: QueryModel = filters.value) {
+  Object.assign(filters.value, model)
+  loading.value = true
+  error.value = null
+  try {
+    const range = Array.isArray(filters.value.completedAt) ? filters.value.completedAt.map(String) : []
+    const result = await listCustomerVisits({
+      page: page.value,
+      size: pageSize.value,
+      keyword: text('keyword'),
+      status: text('status'),
+      completedFrom: range[0] ? `${range[0]}T00:00:00` : undefined,
+      completedTo: range[1] ? `${range[1]}T23:59:59` : undefined,
+    })
+    rows.value = result.records
+    total.value = result.total
+    Object.assign(summary, { visitable: result.visitable, pending: result.pending, completed: result.completed })
+  } catch (cause) {
+    rows.value = []
+    total.value = 0
+    error.value = getApiErrorDetails(cause, '客户回访列表加载失败')
+  } finally { loading.value = false }
+}
+function text(key: string) { return String(filters.value[key] || '').trim() || undefined }
+function search(model: QueryModel) { page.value = 1; void load(model) }
+function reset(model: QueryModel) { page.value = 1; void load(model) }
+
+const dialogOpen = ref(false)
+const detailLoading = ref(false)
+const saving = ref(false)
+const uploading = ref(false)
+const fileInput = ref<HTMLInputElement | null>(null)
+const detail = ref<CustomerVisitDetail | null>(null)
+const form = reactive({ selectedInboundOrderId: '', visitResult: '', customerFeedback: '', remark: '', attachments: [] as CustomerVisitAttachment[] })
+
+async function openVisit(row: CustomerVisitRow) {
+  dialogOpen.value = true
+  detailLoading.value = true
+  detail.value = null
+  Object.assign(form, { selectedInboundOrderId: '', visitResult: '', customerFeedback: '', remark: '', attachments: [] })
+  try {
+    const value = await getCustomerVisit(row.id, row.customerId)
+    detail.value = value
+    Object.assign(form, {
+      selectedInboundOrderId: value.inboundOrders.find(option => option.inboundCode === value.visit.selectedInboundCode)?.inboundOrderId || (value.inboundOrders.length === 1 ? value.inboundOrders[0]?.inboundOrderId : '') || '',
+      visitResult: value.visit.visitResult || '',
+      customerFeedback: value.customerFeedback || '',
+      remark: value.remark || '',
+      attachments: [...value.visit.attachments],
+    })
+  } catch (cause) {
+    ElMessage.error(getApiErrorDetails(cause, '回访信息加载失败').message)
+    dialogOpen.value = false
+  } finally { detailLoading.value = false }
+}
+
+async function selectFiles(event: Event) {
+  const input = event.target as HTMLInputElement
+  const selected = Array.from(input.files || [])
+  input.value = ''
+  if (!detail.value || !selected.length) return
+  if (form.attachments.length + selected.length > 20) { ElMessage.warning('最多保留20份回访资料'); return }
+  uploading.value = true
+  try {
+    for (const file of selected) {
+      const uploaded = await uploadCustomerVisitAttachment(detail.value.visit.id, detail.value.visit.customerId, file)
+      if (!form.attachments.some(item => item.fileId === uploaded.fileId)) form.attachments.push(uploaded)
+    }
+    ElMessage.success('回访资料上传成功')
+  } catch (cause) { ElMessage.error(getApiErrorDetails(cause, '回访资料上传失败').message) }
+  finally { uploading.value = false }
+}
+
+function removeAttachment(fileId: string) {
+  form.attachments = form.attachments.filter(item => item.fileId !== fileId)
+}
+
+async function submit() {
+  if (!detail.value || !form.selectedInboundOrderId || !form.visitResult) {
+    ElMessage.warning('请选择本次回访的入仓单和回访结果')
+    return
+  }
+  saving.value = true
+  try {
+    await saveCustomerVisit(detail.value.visit.id, detail.value.visit.customerId, {
+      selectedInboundOrderId: form.selectedInboundOrderId,
+      visitResult: form.visitResult,
+      customerFeedback: form.customerFeedback.trim() || undefined,
+      remark: form.remark.trim() || undefined,
+      attachments: form.attachments,
+    })
+    dialogOpen.value = false
+    ElMessage.success(detail.value.visit.status === 'COMPLETED' ? '再次回访已保存' : '回访已完成')
+    await load()
+  } catch (cause) { ElMessage.error(getApiErrorDetails(cause, '回访保存失败').message) }
+  finally { saving.value = false }
+}
+
+function fileSize(value: number) { return value >= 1024 * 1024 ? `${(value / 1024 / 1024).toFixed(1)} MB` : `${Math.max(1, Math.round(value / 1024))} KB` }
+onMounted(load)
+</script>
+
+<template>
+  <AdminPage class="admin-density">
+    <ListPageLayout aria-label="客户回访列表">
+      <template #toolbar>
+        <dl class="visit-summary density-detail-overview" aria-label="回访统计"><div><dt>可回访订单</dt><dd>{{ summary.visitable }}</dd></div><div><dt>待回访</dt><dd>{{ summary.pending }}</dd></div><div><dt>已完成回访</dt><dd>{{ summary.completed }}</dd></div></dl>
+        <QueryToolbar v-model="filters" class="surface-panel" :fields="fields" :loading="loading" ariaLabel="客户回访筛选" preference-key="overseas-customer-visits-query" :search-on-reset="false" @search="search" @reset="reset" />
+      </template>
+      <template v-if="error" #state><LoadErrorState title="客户回访列表加载失败" :message="error.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="error" /></template></LoadErrorState></template>
+      <section v-if="!error" class="surface-panel table-panel">
+        <DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :loading="loading" :total="total" preference-key="overseas-customer-visits" row-key="id" empty-text="暂无可回访派送单" @update:page="load()" @update:page-size="page = 1; load()">
+          <template #actions="{ row }"><el-button v-if="access.can(permission.customerVisitEdit)" class="density-action" data-tone="neutral" size="small" @click="openVisit(row as CustomerVisitRow)">{{ row.status === 'COMPLETED' ? '再次回访' : '回访' }}</el-button></template>
+          <template #status="{ row }"><StatusBadge :status="row.status === 'COMPLETED' ? '已回访' : '待回访'" /></template>
+          <template #pagination-left>共 {{ total }} 条回访记录</template>
+        </DataTable>
+      </section>
+    </ListPageLayout>
+  </AdminPage>
+
+  <AppDialog class="admin-density-dialog" v-model="dialogOpen" title="客户回访" width="min(920px, calc(100vw - 28px))" confirm-text="保存回访" :loading="detailLoading" :confirm-loading="saving" :confirm-disabled="uploading" @confirm="submit">
+    <template v-if="detail">
+      <dl class="visit-order-summary density-fields">
+        <div><dt>派送单号</dt><dd>{{ detail.visit.deliveryNo }}</dd></div>
+        <div><dt>客户</dt><dd>{{ detail.visit.customerName || '—' }}</dd></div>
+        <div><dt>完成时间</dt><dd>{{ formatOverseasDateTime(detail.visit.deliveryCompletedAt) }}</dd></div>
+        <div><dt>目的地</dt><dd>{{ detail.visit.destination || '—' }}</dd></div>
+      </dl>
+      <el-form label-position="top" class="visit-form density-form">
+        <el-form-item label="选择本次回访的入仓单" required>
+          <div class="inbound-options">
+            <label v-for="option in detail.inboundOrders" :key="option.inboundOrderId" class="inbound-option" :class="{ selected: form.selectedInboundOrderId === option.inboundOrderId }">
+              <el-radio v-model="form.selectedInboundOrderId" :value="option.inboundOrderId"><strong>{{ option.inboundCode }}</strong></el-radio>
+              <span class="visit-order-reference">尾程单：<OrderReferenceText :value="option.lastMileOrderNo" /></span><span>目的仓：{{ option.destinationWarehouseCode || option.destinationWarehouseName || '—' }}</span><span>箱数：{{ option.packageCount }}</span>
+            </label>
+          </div>
+        </el-form-item>
+        <el-form-item label="回访结果" required><el-select v-model="form.visitResult" placeholder="请选择回访结果"><el-option v-for="(label, value) in resultLabels" :key="value" :label="label" :value="value" /></el-select></el-form-item>
+        <el-form-item label="客户反馈"><el-input v-model="form.customerFeedback" type="textarea" :rows="4" maxlength="2000" show-word-limit placeholder="记录客户对派送服务的反馈" /></el-form-item>
+        <el-form-item label="备注"><el-input v-model="form.remark" type="textarea" :rows="3" maxlength="1000" show-word-limit placeholder="补充后续跟进事项" /></el-form-item>
+        <el-form-item label="回访资料">
+          <el-button :disabled="uploading" :loading="uploading" @click="fileInput?.click()"><FileUp :size="16" />{{ uploading ? '上传中...' : '选择文件' }}</el-button><input ref="fileInput" hidden type="file" multiple :disabled="uploading" accept=".pdf,.doc,.docx,.xls,.xlsx,.ppt,.pptx,.jpg,.jpeg,.png,.webp" @change="selectFiles" />
+          <span class="file-tip">支持 PDF、Office、JPG、PNG、WEBP，单个不超过20MB</span>
+          <div v-if="form.attachments.length" class="attachment-list">
+            <div v-for="file in form.attachments" :key="file.fileId"><span>{{ file.fileName }}</span><small>{{ fileSize(file.sizeBytes) }}</small><el-button class="density-action" data-tone="danger" size="small" aria-label="移除资料" @click="removeAttachment(file.fileId)">移除</el-button></div>
+          </div>
+          <div v-else class="attachment-empty">暂未上传回访资料</div>
+        </el-form-item>
+      </el-form>
+    </template>
+  </AppDialog>
+</template>
+
+<style scoped>
+.visit-summary { flex-wrap: wrap; }
+.visit-order-summary.density-fields { grid-template-columns: repeat(2, minmax(0, 1fr)); margin-bottom: var(--admin-space-5); }
+.inbound-options { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: var(--admin-space-3); width: 100%; }
+.inbound-option { display: grid; min-width: 0; gap: var(--admin-space-2); padding: var(--admin-space-3); border: 1px solid var(--cc-border); border-radius: var(--admin-radius); cursor: pointer; color: var(--cc-muted); overflow-wrap: anywhere; }
+.visit-order-reference { display: flex; min-width: 0; align-items: baseline; gap: var(--admin-space-1); }
+.inbound-option.selected { border-color: var(--el-color-primary); background: var(--el-color-primary-light-9); }
+.file-tip { margin-left: var(--admin-space-3); color: var(--cc-muted); font-size: var(--admin-font-caption); }
+.attachment-list, .attachment-empty { width: 100%; margin-top: var(--admin-space-3); }
+.attachment-list > div { display: grid; grid-template-columns: minmax(0, 1fr) auto auto; align-items: center; gap: var(--admin-space-3); padding: var(--admin-space-2) 0; border-bottom: 1px solid var(--cc-border); overflow-wrap: anywhere; }
+.attachment-list small, .attachment-empty { color: var(--cc-muted); font-size: var(--admin-font-caption); }
+@media (max-width: 720px) { .visit-summary { flex-wrap: wrap; } .visit-order-summary.density-fields, .inbound-options { grid-template-columns: 1fr; } .file-tip { display: block; margin: 8px 0 0; } }
+</style>
diff --git a/src/modules/overseas-warehouse/pages/DeliveryOrderDetailView.test.ts b/src/modules/overseas-warehouse/pages/DeliveryOrderDetailView.test.ts
new file mode 100644
index 00000000..2811b2a6
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/DeliveryOrderDetailView.test.ts
@@ -0,0 +1,50 @@
+import ElementPlus from 'element-plus'
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { getDeliveryOrder } from '../api/deliveryOrders'
+import DeliveryOrderDetailView from './DeliveryOrderDetailView.vue'
+
+const routeState = vi.hoisted(() => ({ params: { deliveryNo: 'DEL/1' }, query: { customerId: '100' } as Record<string, string> }))
+vi.mock('vue-router', () => ({ useRoute: () => routeState, useRouter: () => ({ push: vi.fn() }) }))
+vi.mock('../api/deliveryOrders', () => ({ getDeliveryOrder: vi.fn() }))
+
+describe('DeliveryOrderDetailView', () => {
+  beforeEach(() => {
+    routeState.query = { customerId: '100' }
+    vi.mocked(getDeliveryOrder).mockReset().mockResolvedValue({
+      order: {
+        version: 3, allowedActions: ['COMPLETE_DELIVERY'],
+        id: '1', customerId: '100', deliveryNo: 'DEL/1', outboundNo: 'OUT-1', dispatchNo: 'PC-1',
+        status: 'DELIVERING', overseasWarehouseName: '洛杉矶仓', destinationWarehouseCode: 'ACY2', palletCount: 1, packageCount: 2,
+        createdAt: '2026-09-01T10:00:00',
+      },
+      skus: [], fees: [
+        { id: 'fee-private', feeDirection: 'RECEIVABLE', feeType: 'PRIVATE_LAST_MILE_DELIVERY', currency: 'USD', amount: 88 },
+        { id: 'fee-delivery', feeDirection: 'RECEIVABLE', feeType: 'DELIVERY_FEE', currency: 'USD', amount: 66 },
+      ], operations: [],
+    })
+  })
+
+  it('loads and renders detail in the explicit customer scope', async () => {
+    const wrapper = mount(DeliveryOrderDetailView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(getDeliveryOrder).toHaveBeenCalledWith('DEL/1', '100')
+    expect(wrapper.text()).toContain('DEL/1')
+    expect(wrapper.text()).toContain('派送中')
+    expect(wrapper.text()).toContain('洛杉矶仓')
+    expect(wrapper.text()).toContain('ACY2')
+    await wrapper.find('.el-tabs__item:nth-child(3)').trigger('click')
+    expect(wrapper.text()).toContain('私人仓尾程派送费')
+    expect(wrapper.text()).toContain('派送费用')
+    wrapper.unmount()
+  })
+
+  it('blocks an unsafe detail request without customer scope', async () => {
+    routeState.query = {}
+    const wrapper = mount(DeliveryOrderDetailView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(getDeliveryOrder).not.toHaveBeenCalled()
+    expect(wrapper.text()).toContain('缺少派送单客户范围')
+    wrapper.unmount()
+  })
+})
diff --git a/src/modules/overseas-warehouse/pages/DeliveryOrderDetailView.vue b/src/modules/overseas-warehouse/pages/DeliveryOrderDetailView.vue
new file mode 100644
index 00000000..07468871
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/DeliveryOrderDetailView.vue
@@ -0,0 +1,134 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, ref, watch } from 'vue'
+import { ArrowLeft } from '@lucide/vue'
+import { useRoute, useRouter } from 'vue-router'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import DetailPageLayout from '@/shared/components/DetailPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { formatOverseasDateTime } from '../lastMilePresentation'
+import { getDeliveryOrder, type DeliveryOrderDetail } from '../api/deliveryOrders'
+
+const route = useRoute()
+const router = useRouter()
+const detail = ref<DeliveryOrderDetail | null>(null)
+const loading = ref(false)
+const error = ref<ApiErrorDetails | null>(null)
+const activeTab = ref('order')
+const deliveryNo = computed(() => String(route.params.deliveryNo || '').trim())
+const customerId = computed(() => String(route.query.customerId || '').trim())
+
+const statusLabels: Record<string, string> = { WAIT_DELIVERY: '待派送', DELIVERING: '派送中', DELIVERED: '派送完成', SIGNED: '已签收', REJECTED: '已拒签', RETURN_PENDING: '退货处理中', CANCELLED: '已取消' }
+const methodLabels: Record<string, string> = { FBA_PICKUP: 'FBA自提', CUSTOMER_PICKUP: '客户自提', TRUCK: '卡车派送', TRUCK_PALLET: '卡派打托', TRUCK_FLOOR: '卡派地板', EXPRESS: '快递', OUTSOURCED: '外配', DEDICATED_TRUCK: '专车直送', LTL: '零担派送', SELF_DELIVERY: '自送', THIRD_PARTY: '第三方配送' }
+const pickupLabels: Record<string, string> = { ONE_PICKUP_ONE_DROP: '一提一卸', ONE_PICKUP_MULTI_DROP: '一提多卸', MULTI_PICKUP_ONE_DROP: '多提一卸', MULTI_PICKUP_MULTI_DROP: '多提多卸', WAREHOUSE_PICKUP: '仓库自提', DOOR_PICKUP: '上门提货', SELF_PICKUP: '自提' }
+const loadingLabels: Record<string, string> = { PALLET: '托盘', FLOOR: '地板', MIXED: '混装', CARTON: '散箱' }
+const feeLabels: Record<string, string> = { DELIVERY_FEE: '派送费用', PRIVATE_LAST_MILE_DELIVERY: '私人仓尾程派送费', EXPRESS_FEE: '快递费用', LOADING_FEE: '装车费', APPOINTMENT_FEE: '买约费用', OTHER: '其他费用' }
+const operationLabels: Record<string, string> = { CREATE_DELIVERY: '创建派送单', ASSIGN_VEHICLE: '车队分配', DISPATCH: '开始派送', SIGN: '签收', COMPLETE_DELIVERY: '完成派送', UPDATE_DELIVERY_STATUS: '更新派送状态', CUSTOMER_VISIT: '客户回访', MARK_RETURN: '标记退货', CANCEL_OUTBOUND: '取消出库' }
+const resultLabels: Record<string, string> = { CREATED: '已创建' }
+
+function show(value: unknown) { const text = String(value ?? '').trim(); return text || '—' }
+function displayPerson(value: unknown) { const text = String(value ?? '').trim(); return text && !/^\d+$/.test(text) ? text : '—' }
+function quantity(value: number | null | undefined, unit: string) { return value === null || value === undefined ? '—' : `${value} ${unit}` }
+function customerConfirmation() { const signedAt = detail.value?.order.signedAt; return signedAt ? `已签收 · ${formatOverseasDateTime(signedAt)}` : '—' }
+function back() { void router.push({ name: 'overseas-delivery-orders' }) }
+async function load() {
+  if (!deliveryNo.value || !customerId.value) { detail.value = null; error.value = { message: '缺少派送单客户范围，无法安全查询详情' }; return }
+  loading.value = true; error.value = null
+  try { detail.value = await getDeliveryOrder(deliveryNo.value, customerId.value) }
+  catch (cause) { detail.value = null; error.value = getApiErrorDetails(cause, '派送单详情加载失败') }
+  finally { loading.value = false }
+}
+watch([deliveryNo, customerId], () => { void load() }, { immediate: true })
+</script>
+
+<template>
+  <AdminPage class="admin-density">
+    <DetailPageLayout aria-label="派送单详情">
+      <template #header>
+        <el-breadcrumb separator=">" class="detail-breadcrumb">
+          <el-breadcrumb-item>首页</el-breadcrumb-item><el-breadcrumb-item>海外派送</el-breadcrumb-item>
+          <el-breadcrumb-item :to="{ name: 'overseas-delivery-orders' }">派送单列表</el-breadcrumb-item><el-breadcrumb-item>详情</el-breadcrumb-item>
+        </el-breadcrumb>
+        <div class="detail-heading">
+          <el-button class="density-back" link aria-label="返回派送单列表" @click="back"><ArrowLeft :size="16" />返回</el-button>
+          <div class="detail-title"><div class="title-line"><h1>派送单详情</h1><StatusBadge v-if="detail" :status="statusLabels[detail.order.status] || detail.order.status" /></div><p>派送单号 {{ deliveryNo }}</p></div>
+        </div>
+      </template>
+
+      <LoadErrorState v-if="error" title="派送单详情加载失败" :message="error.message" :loading="loading" @retry="load">
+        <template #details><ApiErrorMeta :details="error" /></template>
+      </LoadErrorState>
+
+      <section v-else v-loading="loading" class="surface-panel delivery-detail">
+        <el-tabs v-model="activeTab" class="detail-tabs density-element-tabs density-contained-tabs">
+          <el-tab-pane name="order"><template #label><span class="density-tab-icon" aria-hidden="true">📋</span><span>订单信息</span></template>
+            <section class="tab-content" aria-label="订单信息">
+              <dl v-if="detail" class="info-grid density-fields">
+                <div class="info-item"><dt>派送单号</dt><dd>{{ show(detail.order.deliveryNo) }}</dd></div><div class="info-item"><dt>状态</dt><dd>{{ statusLabels[detail.order.status] || detail.order.status }}</dd></div>
+                <div class="info-item"><dt>仓库</dt><dd>{{ show(detail.order.overseasWarehouseName) }}</dd></div><div class="info-item"><dt>目的 FBA 仓</dt><dd>{{ show(detail.order.destinationWarehouseCode || detail.order.destinationWarehouseName) }}</dd></div>
+                <div class="info-item"><dt>运单号</dt><dd>{{ show(detail.order.waybillNo) }}</dd></div><div class="info-item"><dt>派送人</dt><dd>{{ show(detail.order.carrierName) }}</dd></div>
+                <div class="info-item"><dt>派送时间</dt><dd>{{ formatOverseasDateTime(detail.order.dispatchedAt || detail.order.plannedDeliveryAt) }}</dd></div><div class="info-item"><dt>提货方式</dt><dd>{{ pickupLabels[detail.order.pickupMethod || ''] || show(detail.order.pickupMethod) }}</dd></div>
+                <div class="info-item"><dt>装车类型</dt><dd>{{ loadingLabels[detail.order.loadingType || ''] || show(detail.order.loadingType) }}</dd></div><div class="info-item"><dt>派送方式</dt><dd>{{ methodLabels[detail.order.deliveryMethod || ''] || show(detail.order.deliveryMethod) }}</dd></div>
+                <div class="info-item"><dt>司机/车队</dt><dd>{{ show(detail.order.driverName) }}</dd></div>
+                <div class="info-item"><dt>车牌号</dt><dd>{{ show(detail.order.vehiclePlate) }}</dd></div><div class="info-item"><dt>总箱数</dt><dd>{{ quantity(detail.order.packageCount, '箱') }}</dd></div>
+                <div class="info-item"><dt>总重量</dt><dd>{{ quantity(detail.order.totalWeightKg, 'kg') }}</dd></div><div class="info-item"><dt>总体积</dt><dd>{{ quantity(detail.order.totalVolumeCbm, 'm³') }}</dd></div>
+                <div class="info-item"><dt>预计到达时间</dt><dd>{{ formatOverseasDateTime(detail.order.expectedArrivalAt) }}</dd></div><div class="info-item"><dt>客户确认</dt><dd>{{ customerConfirmation() }}</dd></div>
+                <div class="info-item info-item--wide"><dt>备注</dt><dd>{{ show(detail.order.remark) }}</dd></div>
+              </dl>
+            </section>
+          </el-tab-pane>
+
+          <el-tab-pane name="sku"><template #label><span class="density-tab-icon" aria-hidden="true">📦</span><span>{{ `SKU明细 (${detail?.skus.length || 0})` }}</span></template>
+            <section class="tab-content" aria-label="SKU明细">
+              <el-table :data="detail?.skus || []" border stripe empty-text="暂无SKU明细">
+                <el-table-column prop="inboundCode" label="入库码" min-width="160" /><el-table-column prop="customerName" label="客户" min-width="180" />
+                <el-table-column prop="destinationWarehouseCode" label="目的仓编码" min-width="140" /><el-table-column prop="receivingAddress" label="收货地址" min-width="240" />
+                <el-table-column prop="shipmentNo" label="货件编号" min-width="160" /><el-table-column prop="fbaTrackingNo" label="FBA追踪号" min-width="160" />
+                <el-table-column prop="skuCode" label="SKU" min-width="140" /><el-table-column prop="productName" label="品名" min-width="160" />
+                <el-table-column prop="packageCount" label="箱数" width="90" align="right" /><el-table-column prop="weightKg" label="重量(kg)" width="110" align="right" /><el-table-column prop="volumeCbm" label="体积(m³)" width="110" align="right" />
+              </el-table>
+            </section>
+          </el-tab-pane>
+
+          <el-tab-pane name="fees"><template #label><span class="density-tab-icon" aria-hidden="true">💰</span><span>{{ `费用明细 (${detail?.fees.length || 0})` }}</span></template>
+            <section class="tab-content" aria-label="派送单费用明细">
+              <el-table :data="detail?.fees || []" border stripe empty-text="暂无费用明细">
+                <el-table-column type="index" label="序号" width="80" /><el-table-column label="应收/应付" width="120"><template #default="scope">{{ scope.row.feeDirection === 'PAYABLE' ? '应付' : scope.row.feeDirection === 'RECEIVABLE' ? '应收' : show(scope.row.feeDirection) }}</template></el-table-column>
+                <el-table-column label="费用类型" min-width="180"><template #default="scope">{{ feeLabels[scope.row.feeType] || scope.row.feeType }}</template></el-table-column><el-table-column prop="currency" label="币种" width="100" />
+                <el-table-column prop="amount" label="金额" min-width="140" align="right" /><el-table-column prop="remark" label="备注" min-width="240" />
+              </el-table>
+            </section>
+          </el-tab-pane>
+
+          <el-tab-pane name="operations"><template #label><span class="density-tab-icon" aria-hidden="true">📝</span><span>{{ `操作记录 (${detail?.operations.length || 0})` }}</span></template>
+            <section class="tab-content" aria-label="操作记录">
+              <el-table :data="detail?.operations || []" border stripe empty-text="暂无操作记录">
+                <el-table-column label="操作时间" min-width="180"><template #default="scope">{{ formatOverseasDateTime(scope.row.operatedAt) }}</template></el-table-column>
+                <el-table-column label="操作节点" min-width="180"><template #default="scope">{{ operationLabels[scope.row.operationNode] || scope.row.operationNode }}</template></el-table-column>
+                <el-table-column label="操作人" min-width="160"><template #default="scope">{{ displayPerson(scope.row.operatorName) }}</template></el-table-column><el-table-column label="处理结果" min-width="280"><template #default="scope">{{ resultLabels[scope.row.result] || scope.row.result }}</template></el-table-column>
+              </el-table>
+            </section>
+          </el-tab-pane>
+        </el-tabs>
+      </section>
+    </DetailPageLayout>
+  </AdminPage>
+</template>
+
+<style scoped>
+.detail-breadcrumb { margin-bottom: var(--admin-space-5); }.detail-heading { display: flex; align-items: center; gap: var(--admin-space-5); }.title-line { display: flex; align-items: center; gap: var(--admin-space-4); }.tab-content h2 { margin: 0 0 var(--admin-space-5); font-size: var(--admin-font-section); line-height: 22px; }
+@media (max-width: 980px) { .info-grid { grid-template-columns: 1fr; }.info-item, .info-item:nth-child(odd), .info-item:nth-child(even) { padding: 0; }.info-item--wide { grid-column: auto; } }
+
+:deep(.detail-page-layout) { gap: 0; background: var(--admin-surface); border: 1px solid var(--cc-border); }
+:deep(.detail-page-layout__header) { padding: var(--admin-space-5); border-bottom: 1px solid var(--cc-border); }
+.detail-title { min-width: 0; display: flex; align-items: center; flex-wrap: wrap; gap: var(--admin-space-5); }
+.detail-title p { margin: 0; color: var(--cc-muted); font-size: var(--admin-font-title); font-weight: 600; overflow-wrap: anywhere; }
+.title-line h1 { margin: 0; font-size: var(--admin-font-section); line-height: 28px; font-weight: 500; }
+.delivery-detail { min-height: 0; overflow: hidden; border: 0; border-radius: 0; }
+.tab-content { width: 100%; padding: 0; box-sizing: border-box; }
+.info-item--wide { grid-column: 1 / -1; }
+
+</style>
diff --git a/src/modules/overseas-warehouse/pages/DeliveryOrdersView.test.ts b/src/modules/overseas-warehouse/pages/DeliveryOrdersView.test.ts
new file mode 100644
index 00000000..df6205b1
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/DeliveryOrdersView.test.ts
@@ -0,0 +1,236 @@
+import ElementPlus from 'element-plus'
+import { defineComponent, h, type PropType } from 'vue'
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { getDeliveryOrder, listDeliveryOrders, listDeliveryReturnInboundOptions, markDeliveryReturn } from '../api/deliveryOrders'
+import { updateDeliveryOrderStatus } from '../api/customerVisits'
+import DeliveryOrdersView from './DeliveryOrdersView.vue'
+import { commonPhase5Stubs } from './phase5TestStubs'
+import { getDeliveryDocuments, deliveryDocumentCategories } from '../api/deliveryDocuments'
+
+const canPermission = vi.hoisted(() => vi.fn((_code: string) => false))
+vi.mock('@/core/access/accessPreview', () => ({ useAccessPreviewStore: () => ({ can: canPermission }) }))
+vi.mock('vue-router', () => ({ useRouter: () => ({ push: vi.fn() }) }))
+vi.mock('../api/deliveryOrders', () => ({ getDeliveryOrder: vi.fn(), listDeliveryOrders: vi.fn(), listDeliveryReturnInboundOptions: vi.fn(), markDeliveryReturn: vi.fn() }))
+vi.mock('../api/customerVisits', () => ({ updateDeliveryOrderStatus: vi.fn() }))
+vi.mock('../api/pallets', () => ({ listReceivingOverseasWarehouses: vi.fn() }))
+vi.mock('../api/deliveryDocuments', async importOriginal => ({ ...await importOriginal<typeof import('../api/deliveryDocuments')>(), getDeliveryDocuments: vi.fn() }))
+
+const row = {
+  version: 2, allowedActions: ['START_DELIVERY', 'COMPLETE_DELIVERY', 'REJECT_DELIVERY', 'CANCEL_DELIVERY', 'MARK_RETURN'],
+  id: '1', customerId: '100', deliveryNo: 'DEL/1', outboundNo: 'OUT-1', dispatchNo: 'PC-1',
+  status: 'WAIT_DELIVERY', palletCount: 1, packageCount: 2, createdAt: '2026-09-01T10:00:00',
+}
+
+function mountView() {
+  return mount(DeliveryOrdersView, { global: { plugins: [ElementPlus], stubs: commonPhase5Stubs } })
+}
+
+describe('DeliveryOrdersView permissions and commands', () => {
+  beforeEach(() => {
+    canPermission.mockReset().mockReturnValue(false)
+    vi.mocked(getDeliveryDocuments).mockReset()
+    vi.mocked(getDeliveryOrder).mockReset().mockResolvedValue({ order: { ...row, version: 7 }, skus: [], fees: [], operations: [] })
+    vi.mocked(listDeliveryOrders).mockReset().mockResolvedValue({ records: [row], page: 1, size: 10, total: 1, pages: 1 })
+    vi.mocked(listDeliveryReturnInboundOptions).mockReset().mockResolvedValue([{ inboundOrderId: '9', inboundCode: 'IN-1', lastMileOrderNo: 'LM-1', customerId: '100', returnSources: [{ outboundPalletItemId: '9007199254740995', inventoryPositionId: '9007199254740996', palletNo: 'PL-1', skuCode: 'SKU-1', maxReturnPackages: 3 }] }])
+    vi.mocked(markDeliveryReturn).mockReset().mockResolvedValue({ id: '19', exceptionNo: 'EXC-1', status: 'PENDING' })
+    vi.mocked(updateDeliveryOrderStatus).mockReset().mockResolvedValue({ deliveryNo: 'DEL/1', deliveryStatus: 'WAIT_DELIVERY', replayed: false })
+  })
+
+  it('keeps detail read-only while hiding independent write operations', async () => {
+    const wrapper = mountView()
+    await flushPromises()
+    const tableText = wrapper.find('[data-testid="data-table"]').text()
+    expect(tableText).toContain('详情')
+    expect(tableText).not.toContain('编辑状态')
+    expect(tableText).not.toContain('标记退货')
+    wrapper.unmount()
+  })
+
+  it('submits status and return commands with the row customer scope', async () => {
+    canPermission.mockImplementation(code => code.endsWith(':status') || code.endsWith(':return'))
+    const wrapper = mountView()
+    await flushPromises()
+
+    await wrapper.findAll('button').find(button => button.text().includes('编辑状态'))!.trigger('click')
+    await flushPromises()
+    await wrapper.find('[data-dialog="编辑派送状态"] select').setValue('DELIVERING')
+    await wrapper.find('[data-dialog="编辑派送状态"] .dialog-confirm').trigger('click')
+    await flushPromises()
+    expect(updateDeliveryOrderStatus).toHaveBeenCalledWith('DEL/1', '100', { status: 'DELIVERING', expectedVersion: 7, remark: undefined })
+
+    await wrapper.findAll('button').find(button => button.text().includes('标记退货'))!.trigger('click')
+    await flushPromises()
+    expect(listDeliveryReturnInboundOptions).toHaveBeenCalledWith('DEL/1', '100')
+    await wrapper.find('[data-dialog="标记退货"] textarea').setValue(' 客户拒收 ')
+    await wrapper.find('[data-dialog="标记退货"] input[type="checkbox"]').setValue(true)
+    await wrapper.find('[data-dialog="标记退货"] input[type="number"]').setValue(2)
+    await wrapper.find('[data-dialog="标记退货"] .dialog-confirm').trigger('click')
+    await flushPromises()
+    expect(markDeliveryReturn).toHaveBeenCalledWith('DEL/1', '100', {
+      inboundOrderId: '9', reason: '客户拒收', returnDirection: 'OVERSEAS_WAREHOUSE',
+      returnLogisticsNo: undefined, items: [{ outboundPalletItemId: '9007199254740995', inventoryPositionId: '9007199254740996', packageCount: 2 }], idempotencyKey: expect.any(String),
+    })
+    wrapper.unmount()
+  })
+
+  it('does not submit an incomplete return form', async () => {
+    canPermission.mockImplementation(code => code.endsWith(':return'))
+    vi.mocked(listDeliveryReturnInboundOptions).mockResolvedValue([])
+    const wrapper = mountView()
+    await flushPromises()
+    await wrapper.findAll('button').find(button => button.text().includes('标记退货'))!.trigger('click')
+    await flushPromises()
+    await wrapper.find('[data-dialog="标记退货"] .dialog-confirm').trigger('click')
+    expect(markDeliveryReturn).not.toHaveBeenCalled()
+    wrapper.unmount()
+  })
+
+  it('excludes manual completion and blocks duplicate or conflicted status submission', async () => {
+    canPermission.mockReturnValue(true)
+    const wrapper = mountView()
+    await flushPromises()
+    await wrapper.findAll('button').find(button => button.text().includes('编辑状态'))!.trigger('click')
+    await flushPromises()
+    const select = wrapper.find('[data-dialog="编辑派送状态"] select')
+    expect(select.find('option[value="DELIVERING"]').text()).toBe('派送中')
+    expect(select.find('option[value="DELIVERED"]').exists()).toBe(false)
+    expect(select.find('option[value="WAIT_DELIVERY"]').exists()).toBe(false)
+    await select.setValue('DELIVERING')
+    await wrapper.find('[data-dialog="编辑派送状态"] textarea').setValue('123')
+    let reject!: (error: unknown) => void
+    vi.mocked(updateDeliveryOrderStatus).mockReturnValueOnce(new Promise((_resolve, rejectRequest) => { reject = rejectRequest }))
+    const button = wrapper.find('[data-dialog="编辑派送状态"] .dialog-confirm')
+    await button.trigger('click'); await button.trigger('click')
+    expect(updateDeliveryOrderStatus).toHaveBeenCalledTimes(1)
+    expect(updateDeliveryOrderStatus).toHaveBeenCalledWith('DEL/1', '100', { status: 'DELIVERING', expectedVersion: 7, remark: '123' })
+    reject({ isAxiosError: true, response: { status: 409, data: { code: 'A0409', message: '版本冲突', requestId: 'req-conflict', traceId: 'trace-conflict' } } })
+    await flushPromises()
+    const state = wrapper.vm as unknown as { statusConflict: boolean; statusOpen: boolean; statusForm: { remark: string }; refreshStatus: () => Promise<void> }
+    expect(state.statusConflict).toBe(true)
+    expect(state.statusOpen).toBe(true)
+    expect(state.statusForm.remark).toBe('123')
+    await button.trigger('click')
+    expect(updateDeliveryOrderStatus).toHaveBeenCalledTimes(1)
+    vi.mocked(getDeliveryOrder).mockResolvedValue({ order: { ...row, version: 8, allowedActions: ['COMPLETE_DELIVERY'] }, skus: [], fees: [], operations: [] })
+    await state.refreshStatus(); await flushPromises()
+    expect(select.findAll('option')).toHaveLength(0)
+    wrapper.unmount()
+  })
+
+  it('keeps return hidden without the server action even when the user has permission', async () => {
+    canPermission.mockImplementation(code => code.endsWith(':return'))
+    vi.mocked(listDeliveryOrders).mockResolvedValue({ records: [{ ...row, status: 'RETURNED', allowedActions: [] }], page: 1, size: 10, total: 1, pages: 1 })
+    const wrapper = mountView(); await flushPromises()
+    expect(wrapper.find('[data-testid="data-table"]').text()).not.toContain('标记退货')
+    expect(listDeliveryReturnInboundOptions).not.toHaveBeenCalled()
+    wrapper.unmount()
+  })
+
+  it('validates selected return sources and reuses the idempotency key after a failed request', async () => {
+    canPermission.mockImplementation(code => code.endsWith(':return'))
+    const wrapper = mountView(); await flushPromises()
+    try {
+      await wrapper.findAll('button').find(button => button.text().includes('标记退货'))!.trigger('click'); await flushPromises()
+      const dialog = wrapper.find('[data-dialog="标记退货"]')
+      expect(dialog.text()).toContain('PL-1 · SKU-1（最多 3 箱）')
+      expect(dialog.text()).not.toContain('9007199254740995')
+      expect(dialog.text()).not.toContain('可自由填写')
+      await dialog.find('textarea').setValue('拒收')
+      await dialog.find('.dialog-confirm').trigger('click')
+      expect(markDeliveryReturn).not.toHaveBeenCalled()
+      await dialog.find('input[type="checkbox"]').setValue(true)
+      for (const invalid of [0, 4, 1.5]) {
+        await dialog.find('input[type="number"]').setValue(invalid)
+        await dialog.find('.dialog-confirm').trigger('click')
+        expect(markDeliveryReturn).not.toHaveBeenCalled()
+      }
+      await dialog.find('input[type="number"]').setValue(2)
+      let reject!: (error: Error) => void
+      vi.mocked(markDeliveryReturn).mockReturnValueOnce(new Promise((_resolve, fail) => { reject = fail }))
+      await dialog.find('.dialog-confirm').trigger('click'); await dialog.find('.dialog-confirm').trigger('click')
+      expect(markDeliveryReturn).toHaveBeenCalledTimes(1)
+      const first = vi.mocked(markDeliveryReturn).mock.calls[0]![2]
+      reject(new Error('网络异常')); await flushPromises()
+      expect(dialog.text()).toContain('标记退货失败')
+      expect((dialog.find('textarea').element as HTMLTextAreaElement).value).toBe('拒收')
+      await dialog.find('.dialog-confirm').trigger('click'); await flushPromises()
+      expect(vi.mocked(markDeliveryReturn).mock.calls[1]![2]).toEqual(first)
+      expect(first.items).toEqual([{ outboundPalletItemId: '9007199254740995', inventoryPositionId: '9007199254740996', packageCount: 2 }])
+      expect(first).not.toHaveProperty('skuCode')
+      expect(first).not.toHaveProperty('packageCount')
+    } finally { wrapper.unmount() }
+  })
+
+  it('clears the selected source when a different inbound order is chosen', async () => {
+    canPermission.mockImplementation(code => code.endsWith(':return'))
+    vi.mocked(listDeliveryReturnInboundOptions).mockResolvedValue([
+      { inboundOrderId: '9', inboundCode: 'IN-1', customerId: '100', returnSources: [{ outboundPalletItemId: '11', inventoryPositionId: '12', palletNo: 'PL-1', skuCode: 'SKU-1', maxReturnPackages: 3 }] },
+      { inboundOrderId: '10', inboundCode: 'IN-2', customerId: '100', returnSources: [] },
+    ])
+    const wrapper = mountView(); await flushPromises()
+    try {
+      await wrapper.findAll('button').find(button => button.text().includes('标记退货'))!.trigger('click'); await flushPromises()
+      const dialog = wrapper.find('[data-dialog="标记退货"]')
+      await dialog.find('select').setValue('9')
+      await dialog.find('input[type="checkbox"]').setValue(true)
+      await dialog.find('input[type="number"]').setValue(2)
+      await dialog.find('textarea').setValue('拒收')
+      await dialog.find('select').setValue('10')
+      expect(dialog.find('input[type="checkbox"]').exists()).toBe(false)
+      await dialog.find('.dialog-confirm').trigger('click')
+      expect(markDeliveryReturn).not.toHaveBeenCalled()
+    } finally { wrapper.unmount() }
+  })
+
+  it('hides status editing when the server supplies no actions', async () => {
+    canPermission.mockReturnValue(true)
+    vi.mocked(listDeliveryOrders).mockResolvedValue({ records: [{ ...row, status: 'DELIVERED', allowedActions: [] }], page: 1, size: 10, total: 1, pages: 1 })
+    const wrapper = mountView(); await flushPromises()
+    expect(wrapper.find('[data-testid="data-table"]').text()).not.toContain('编辑状态')
+    expect(getDeliveryOrder).not.toHaveBeenCalled()
+    wrapper.unmount()
+  })
+
+  it('hides status editing when completion is the only server action', async () => {
+    canPermission.mockImplementation(code => code.endsWith(':status'))
+    vi.mocked(getDeliveryOrder).mockResolvedValue({ order: { ...row, version: 7, status: 'DELIVERING', allowedActions: ['COMPLETE_DELIVERY'] }, skus: [], fees: [], operations: [] })
+    vi.mocked(listDeliveryOrders).mockResolvedValue({ records: [{ ...row, status: 'DELIVERING', allowedActions: ['COMPLETE_DELIVERY'] }], page: 1, size: 10, total: 1, pages: 1 })
+    const wrapper = mountView(); await flushPromises()
+    expect(wrapper.find('[data-testid="data-table"]').text()).not.toContain('编辑状态')
+    expect(getDeliveryOrder).not.toHaveBeenCalled()
+    expect(updateDeliveryOrderStatus).not.toHaveBeenCalled()
+    wrapper.unmount()
+  })
+
+  it('shows the destination FBA warehouse that identifies each split delivery', async () => {
+    vi.mocked(listDeliveryOrders).mockResolvedValue({ records: [{ ...row, destinationWarehouseCode: 'ACY2', destinationWarehouseName: 'Amazon ACY2' }], page: 1, size: 10, total: 1, pages: 1 })
+    const table = defineComponent({
+      props: { data: Array as PropType<object[]>, columns: Array as PropType<Array<{ key: string; formatter?: (row: object) => string }>> },
+      setup(props) { return () => h('div', props.columns?.find(column => column.key === 'destinationWarehouse')?.formatter?.(props.data?.[0] || {}) || '') },
+    })
+    const wrapper = mount(DeliveryOrdersView, { global: { plugins: [ElementPlus], stubs: { ...commonPhase5Stubs, DataTable: table } } })
+    await flushPromises()
+    expect(wrapper.text()).toContain('ACY2 · Amazon ACY2')
+    wrapper.unmount()
+  })
+
+  it('renders category counts from the list without per-row document requests', async () => {
+    canPermission.mockReturnValue(true)
+    const documentSummary = { uploadedCategoryCount: 1, totalCategoryCount: 3, categories: deliveryDocumentCategories.map(item => ({ category: item.category, status: item.category === 'RECEIPT' ? 'UPLOADED' as const : 'MISSING' as const, fileCount: item.category === 'RECEIPT' ? 3 : 0 })) }
+    vi.mocked(listDeliveryOrders).mockResolvedValue({ records: [{ ...row, documentSummary }], page: 1, size: 10, total: 1, pages: 1 })
+    const table = defineComponent({ props: { data: Array as PropType<object[]> }, setup(props, { slots }) { return () => h('div', props.data?.flatMap(item => slots.documents?.({ row: item }) || [])) } })
+    const wrapper = mount(DeliveryOrdersView, { global: { plugins: [ElementPlus], stubs: { ...commonPhase5Stubs, DataTable: table, DeliveryDocumentsDialog: true } } })
+    await flushPromises()
+    expect(wrapper.text()).toContain('1/3 已上传')
+    expect(wrapper.text()).toContain('签收文件（POD签收/快递签收） · 已上传')
+    expect(getDeliveryDocuments).not.toHaveBeenCalled()
+    await wrapper.findAll('button').find(button => button.text().includes('管理资料'))!.trigger('click')
+    const dialog = wrapper.findComponent({ name: 'DeliveryDocumentsDialog' })
+    expect(dialog.props()).toMatchObject({ deliveryNo: 'DEL/1', customerId: '100', modelValue: true })
+    const calls = vi.mocked(listDeliveryOrders).mock.calls.length
+    dialog.vm.$emit('saved'); await flushPromises()
+    expect(listDeliveryOrders).toHaveBeenCalledTimes(calls + 1)
+    wrapper.unmount()
+  })
+})
diff --git a/src/modules/overseas-warehouse/pages/DeliveryOrdersView.vue b/src/modules/overseas-warehouse/pages/DeliveryOrdersView.vue
new file mode 100644
index 00000000..3e7a618b
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/DeliveryOrdersView.vue
@@ -0,0 +1,178 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, reactive, ref, watch } from 'vue'
+
+import { ElMessage } from 'element-plus'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useRouter } from 'vue-router'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { formatOverseasDateTime } from '../lastMilePresentation'
+import { getDeliveryOrder, listDeliveryOrders, listDeliveryReturnInboundOptions, markDeliveryReturn, type DeliveryOrderRow, type DeliveryReturnRelation, type DeliveryReturnSource, type MarkDeliveryReturnPayload } from '../api/deliveryOrders'
+import { updateDeliveryOrderStatus } from '../api/customerVisits'
+import { overseasWarehousePermissions as permission } from '../permissions'
+import { listReceivingOverseasWarehouses, type ReceivingOverseasWarehouseDto } from '../api/pallets'
+
+import DeliveryDocumentsDialog from '../components/DeliveryDocumentsDialog.vue'
+import { deliveryDocumentCategories } from '../api/deliveryDocuments'
+
+const documentsOpen = ref(false)
+const documentsRow = ref<DeliveryOrderRow | null>(null)
+function openDocuments(row: DeliveryOrderRow) { if (!access.can(permission.deliveryList)) return; documentsRow.value = row; documentsOpen.value = true }
+const router = useRouter()
+const access = useAccessPreviewStore()
+const rows = ref<DeliveryOrderRow[]>([]); const page = ref(1); const pageSize = ref(10); const total = ref(0); const loading = ref(false); const error = ref<ApiErrorDetails | null>(null)
+const warehouses = ref<ReceivingOverseasWarehouseDto[]>([]); const warehousesLoading = ref(false)
+const filters = ref<QueryModel>({ documentNo: '', dispatchNo: '', waybillNo: '', warehouseId: '', status: '', vehiclePlate: '', driverName: '', deliveryMethod: '', plannedAt: [] })
+const fields = computed<QueryField[]>(() => [
+  { key: 'status', type: 'select', label: '状态', width: 160, placeholder: '全部状态', options: [{ label: '待派送', value: 'WAIT_DELIVERY' }, { label: '派送中', value: 'DELIVERING' }, { label: '派送完成', value: 'DELIVERED' }, { label: '已签收（历史）', value: 'SIGNED' }, { label: '已拒签', value: 'REJECTED' }, { label: '退货处理中', value: 'RETURN_PENDING' }, { label: '已取消', value: 'CANCELLED' }] },
+  { key: 'documentNo', type: 'input', label: '派送单号', width: 190, placeholder: '请输入派送单号' },
+  { key: 'dispatchNo', type: 'input', label: '排车单号', width: 190, placeholder: '请输入排车单号' },
+  { key: 'waybillNo', type: 'input', label: '运单号', width: 180, placeholder: '请输入运单号' },
+  { key: 'warehouseId', type: 'select', label: '海外仓', width: 220, placeholder: '全部海外仓', options: warehouses.value.map((item) => ({ label: `${item.warehouseName}（${item.warehouseCode}）`, value: String(item.id) })), props: { filterable: true, clearable: true, loading: warehousesLoading.value } },
+  { key: 'deliveryMethod', type: 'select', label: '派送方式', width: 170, placeholder: '全部方式', options: [{ label: 'FBA自提', value: 'FBA_PICKUP' }, { label: '客户自提', value: 'CUSTOMER_PICKUP' }, { label: '卡派打托', value: 'TRUCK_PALLET' }, { label: '卡派地板', value: 'TRUCK_FLOOR' }, { label: '快递', value: 'EXPRESS' }, { label: '外配', value: 'OUTSOURCED' }, { label: '专车直送', value: 'DEDICATED_TRUCK' }, { label: '零担派送', value: 'LTL' }] },
+  { key: 'vehiclePlate', type: 'input', label: '车牌号', width: 160, placeholder: '请输入车牌号' },
+  { key: 'driverName', type: 'input', label: '司机', width: 180, placeholder: '请输入司机或车队' },
+  { key: 'plannedAt', type: 'daterange', label: '预计派送时间', width: 280 },
+])
+const columns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 300, fixed: 'left', slotName: 'actions' },
+  { key: 'deliveryNo', prop: 'deliveryNo', label: '派送单号', minWidth: 180, fixed: 'left' },
+  { key: 'documents', label: '所需资料', minWidth: 380, slotName: 'documents' },
+  { key: 'bolNo', prop: 'bolNo', label: 'BOL号', minWidth: 170 },
+  { key: 'customerName', prop: 'customerName', label: '客户', minWidth: 160 },
+  { key: 'destinationWarehouse', label: '目的 FBA 仓', minWidth: 180, formatter: (row: DeliveryOrderRow) => destinationWarehouseLabel(row) },
+  { key: 'overseasWarehouseName', prop: 'overseasWarehouseName', label: '仓库', minWidth: 150 },
+  { key: 'dispatchNo', prop: 'dispatchNo', label: '排车单号', minWidth: 170 },
+  { key: 'waybillNo', prop: 'waybillNo', label: '运单号', minWidth: 150 },
+  { key: 'status', prop: 'status', label: '订单状态', width: 110, slotName: 'status' },
+  { key: 'deliveryMethod', prop: 'deliveryMethod', label: '派送方式', width: 120, formatter: (row: DeliveryOrderRow) => deliveryMethodLabel(row.deliveryMethod) },
+  { key: 'carrierName', prop: 'carrierName', label: '派送人', minWidth: 150 },
+  { key: 'vehiclePlate', prop: 'vehiclePlate', label: '车牌', minWidth: 120 },
+  { key: 'driverName', prop: 'driverName', label: '司机/车队', minWidth: 140 },
+  { key: 'plannedDeliveryAt', prop: 'plannedDeliveryAt', label: '期望派送时间', minWidth: 170, formatter: (row: DeliveryOrderRow) => formatOverseasDateTime(row.plannedDeliveryAt) },
+  { key: 'dispatchedAt', prop: 'dispatchedAt', label: '派送时间', minWidth: 170, formatter: (row: DeliveryOrderRow) => formatOverseasDateTime(row.dispatchedAt) },
+  { key: 'pickupMethod', prop: 'pickupMethod', label: '提货方式', width: 110, formatter: (row: DeliveryOrderRow) => pickupMethodLabel(row.pickupMethod) },
+  { key: 'loadingType', prop: 'loadingType', label: '装车类型', width: 110, formatter: (row: DeliveryOrderRow) => loadingTypeLabel(row.loadingType) },
+  { key: 'packageCount', prop: 'packageCount', label: '总箱数', width: 90, align: 'right' },
+  { key: 'totalWeightKg', prop: 'totalWeightKg', label: '总重量(kg)', width: 120, align: 'right' },
+  { key: 'totalVolumeCbm', prop: 'totalVolumeCbm', label: '总体积(m³)', width: 120, align: 'right' },
+  { key: 'expectedArrivalAt', prop: 'expectedArrivalAt', label: '预计到达时间', minWidth: 170, formatter: (row: DeliveryOrderRow) => formatOverseasDateTime(row.expectedArrivalAt) },
+  { key: 'signedAt', prop: 'signedAt', label: '签收时间', minWidth: 170, formatter: (row: DeliveryOrderRow) => formatOverseasDateTime(row.signedAt) },
+  { key: 'remark', prop: 'remark', label: '备注', minWidth: 160 },
+]
+const statusLabels: Record<string, string> = { WAIT_DELIVERY: '待派送', DELIVERING: '派送中', DELIVERED: '派送完成', SIGNED: '已签收', REJECTED: '已拒签', RETURN_PENDING: '退货处理中', CANCELLED: '已取消' }
+function deliveryMethodLabel(value?: string | null) { return ({ FBA_PICKUP: 'FBA自提', CUSTOMER_PICKUP: '客户自提', TRUCK_PALLET: '卡派打托', TRUCK_FLOOR: '卡派地板', EXPRESS: '快递', OUTSOURCED: '外配', DEDICATED_TRUCK: '专车直送', LTL: '零担派送', SELF_DELIVERY: '自送', THIRD_PARTY: '第三方配送' } as Record<string, string>)[String(value)] || value || '—' }
+function pickupMethodLabel(value?: string | null) { return ({ ONE_PICKUP_ONE_DROP: '一提一卸', ONE_PICKUP_MULTI_DROP: '一提多卸', MULTI_PICKUP_ONE_DROP: '多提一卸', MULTI_PICKUP_MULTI_DROP: '多提多卸', WAREHOUSE_PICKUP: '仓库自提', DOOR_PICKUP: '上门提货', SELF_PICKUP: '自提' } as Record<string, string>)[String(value)] || value || '—' }
+function loadingTypeLabel(value?: string | null) { return ({ PALLET: '托盘', FLOOR: '地板', MIXED: '混装', CARTON: '散箱' } as Record<string, string>)[String(value)] || value || '—' }
+function destinationWarehouseLabel(row: DeliveryOrderRow) {
+  const code = row.destinationWarehouseCode?.trim()
+  const name = row.destinationWarehouseName?.trim()
+  return code && name && code !== name ? `${code} · ${name}` : code || name || '—'
+}
+async function load(model: QueryModel = filters.value) { Object.assign(filters.value, model); loading.value = true; error.value = null; try { const range = Array.isArray(filters.value.plannedAt) ? filters.value.plannedAt.map(String) : []; const result = await listDeliveryOrders({ page: page.value, size: pageSize.value, documentNo: text('documentNo'), dispatchNo: text('dispatchNo'), waybillNo: text('waybillNo'), warehouseId: text('warehouseId'), status: text('status'), vehiclePlate: text('vehiclePlate'), driverName: text('driverName'), deliveryMethod: text('deliveryMethod'), plannedFrom: range[0] ? `${range[0]}T00:00:00` : undefined, plannedTo: range[1] ? `${range[1]}T23:59:59` : undefined }); rows.value = result.records; total.value = result.total } catch (cause) { rows.value = []; total.value = 0; error.value = getApiErrorDetails(cause, '派送单列表加载失败') } finally { loading.value = false } }
+function text(key: string) { return String(filters.value[key] || '').trim() || undefined }
+function open(row: DeliveryOrderRow) { void router.push({ name: 'overseas-delivery-order-detail', params: { deliveryNo: row.deliveryNo }, query: { customerId: row.customerId } }) }
+const returnOpen = ref(false); const returnLoading = ref(false); const returnSaving = ref(false); const returnRow = ref<DeliveryOrderRow | null>(null); const returnOptions = ref<DeliveryReturnRelation[]>([])
+const returnError = ref<ApiErrorDetails | null>(null)
+const returnForm = reactive({ inboundOrderId: '', reason: '', returnDirection: 'OVERSEAS_WAREHOUSE' as MarkDeliveryReturnPayload['returnDirection'], returnLogisticsNo: '' })
+const returnItems = ref<Array<DeliveryReturnSource & { selected: boolean; packageCount: number | undefined }>>([])
+let returnSequence = 0
+let returnAttempt: { body: string; key: string } | null = null
+function canReturn(row: DeliveryOrderRow) { return access.can(permission.deliveryReturn) && row.allowedActions?.includes('MARK_RETURN') }
+watch(() => returnForm.inboundOrderId, () => {
+  returnItems.value = (returnOptions.value.find(option => option.inboundOrderId === returnForm.inboundOrderId)?.returnSources || []).map(source => ({ ...source, selected: false, packageCount: undefined }))
+})
+watch(returnOpen, visible => { if (!visible) returnSequence++ })
+async function openReturn(row: DeliveryOrderRow) {
+  if (!canReturn(row) || returnSaving.value) return
+  const sequence = ++returnSequence
+  returnRow.value = row; Object.assign(returnForm, { inboundOrderId: '', reason: '', returnDirection: 'OVERSEAS_WAREHOUSE', returnLogisticsNo: '' })
+  returnOptions.value = []; returnItems.value = []; returnError.value = null; returnAttempt = null; returnOpen.value = true; returnLoading.value = true
+  try {
+    const options = await listDeliveryReturnInboundOptions(row.deliveryNo, row.customerId)
+    if (sequence !== returnSequence || !returnOpen.value) return
+    returnOptions.value = options
+    if (options.length === 1) returnForm.inboundOrderId = options[0]!.inboundOrderId
+  } catch (cause) { if (sequence === returnSequence) returnError.value = getApiErrorDetails(cause, '退货入仓单加载失败') }
+  finally { if (sequence === returnSequence) returnLoading.value = false }
+}
+async function submitReturn() {
+  if (!returnOpen.value || !returnRow.value || !canReturn(returnRow.value) || returnLoading.value || returnSaving.value) return
+  if (!returnOptions.value.some(option => option.inboundOrderId === returnForm.inboundOrderId) || !returnForm.reason.trim()) { ElMessage.warning('请选择入仓单并填写退货原因'); return }
+  const selected = returnItems.value.filter(item => item.selected)
+  if (!selected.length || selected.some(item => !Number.isSafeInteger(item.packageCount) || !item.packageCount || item.packageCount < 1 || item.packageCount > item.maxReturnPackages)) { ElMessage.warning('请选择原出库明细，并填写不超过可退上限的整数箱数'); return }
+  const body = { inboundOrderId: returnForm.inboundOrderId, reason: returnForm.reason.trim(), returnDirection: returnForm.returnDirection, returnLogisticsNo: returnForm.returnLogisticsNo.trim() || undefined, items: selected.map(item => ({ outboundPalletItemId: item.outboundPalletItemId, inventoryPositionId: item.inventoryPositionId, packageCount: item.packageCount! })) }
+  const serialized = JSON.stringify(body)
+  if (returnAttempt?.body !== serialized) returnAttempt = { body: serialized, key: crypto.randomUUID() }
+  returnSaving.value = true; returnError.value = null
+  try {
+    const result = await markDeliveryReturn(returnRow.value.deliveryNo, returnRow.value.customerId, { ...body, idempotencyKey: returnAttempt.key })
+    returnOpen.value = false; ElMessage.success(`已生成异常退货单 ${result.exceptionNo}`); await load()
+  } catch (cause) { returnError.value = getApiErrorDetails(cause, '标记退货失败') }
+  finally { returnSaving.value = false }
+}
+const statusOpen = ref(false)
+const statusSaving = ref(false)
+const statusLoading = ref(false)
+const statusError = ref<ApiErrorDetails | null>(null)
+const statusConflict = ref(false)
+const statusRow = ref<DeliveryOrderRow | null>(null)
+const statusForm = reactive({ status: '', remark: '' })
+let statusSequence = 0
+const statusTargets = [
+  { action: 'START_DELIVERY', value: 'DELIVERING', label: '派送中' },
+  { action: 'REJECT_DELIVERY', value: 'REJECTED', label: '已拒签' },
+  { action: 'CANCEL_DELIVERY', value: 'CANCELLED', label: '已取消' },
+]
+function availableStatuses(row: DeliveryOrderRow) { return statusTargets.filter(option => row.allowedActions?.includes(option.action)) }
+const statusOptions = computed(() => statusRow.value ? availableStatuses(statusRow.value) : [])
+async function refreshStatus() {
+  const row = statusRow.value
+  if (!row || statusSaving.value) return
+  const sequence = ++statusSequence
+  statusLoading.value = true; statusError.value = null
+  try {
+    const latest = await getDeliveryOrder(row.deliveryNo, row.customerId)
+    if (sequence !== statusSequence || !statusOpen.value) return
+    if (!Number.isSafeInteger(latest.order.version) || latest.order.version < 0) throw new Error('派送单缺少有效版本，请刷新后重试')
+    statusRow.value = latest.order
+    if (!availableStatuses(latest.order).some(option => option.value === statusForm.status)) statusForm.status = ''
+    statusConflict.value = false
+  } catch (cause) { if (sequence === statusSequence) { statusError.value = getApiErrorDetails(cause, '派送单最新状态加载失败'); statusConflict.value = true } }
+  finally { if (sequence === statusSequence) statusLoading.value = false }
+}
+async function openStatus(row: DeliveryOrderRow) {
+  if (!access.can(permission.deliveryStatus) || statusSaving.value || !availableStatuses(row).length) return
+  statusRow.value = row; Object.assign(statusForm, { status: '', remark: '' }); statusConflict.value = true; statusOpen.value = true
+  await refreshStatus()
+}
+async function submitStatus() {
+  if (!statusOpen.value || !statusRow.value || statusLoading.value || statusSaving.value || statusConflict.value || !access.can(permission.deliveryStatus) || !statusOptions.value.some(option => option.value === statusForm.status)) return
+  statusSaving.value = true; statusError.value = null
+  try {
+    await updateDeliveryOrderStatus(statusRow.value.deliveryNo, statusRow.value.customerId, { status: statusForm.status, expectedVersion: statusRow.value.version, remark: statusForm.remark.trim() || undefined })
+    statusOpen.value = false
+    ElMessage.success('派送状态已更新')
+    await load()
+  } catch (cause) {
+    const details = getApiErrorDetails(cause, '派送状态更新失败')
+    statusConflict.value = details.code === 'A0409'
+    statusError.value = statusConflict.value ? { ...details, message: '派送单已被更新，请刷新最新状态并重新确认后提交。' } : details
+  } finally { statusSaving.value = false }
+}
+function search(model: QueryModel) { page.value = 1; void load(model) }
+function reset(model: QueryModel) { page.value = 1; void load(model) }
+async function loadWarehouses() { if (!access.can(permission.warehouseList)) return; warehousesLoading.value = true; try { warehouses.value = (await listReceivingOverseasWarehouses()).records } catch { warehouses.value = [] } finally { warehousesLoading.value = false } }
+onMounted(() => { void load(); void loadWarehouses() })
+</script>
+<template><AdminPage class="admin-density"><ListPageLayout aria-label="派送单列表"><template #toolbar><QueryToolbar v-model="filters" class="surface-panel" :fields="fields" :loading="loading" ariaLabel="派送单筛选" preference-key="overseas-delivery-orders-query" :search-on-reset="false" @search="search" @reset="reset" /></template><template v-if="error" #state><LoadErrorState title="派送单列表加载失败" :message="error.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="error" /></template></LoadErrorState></template><section v-if="!error" class="surface-panel table-panel"><DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :loading="loading" :total="total" preference-key="overseas-delivery-orders" row-key="id" empty-text="暂无派送单" @update:page="load()" @update:page-size="page = 1; load()"><template #actions="{ row }"><div class="density-actions"><el-button class="density-action" data-tone="neutral" size="small" @click="open(row as DeliveryOrderRow)">详情</el-button><el-button class="density-action" data-tone="neutral" v-if="access.can(permission.deliveryStatus) && availableStatuses(row as DeliveryOrderRow).length > 0" size="small" @click="openStatus(row as DeliveryOrderRow)">编辑状态</el-button><el-button class="density-action" data-tone="warning" v-if="canReturn(row as DeliveryOrderRow)" size="small" @click="openReturn(row as DeliveryOrderRow)">标记退货</el-button></div></template><template #documents="{ row }"><div class="delivery-document-summary"><div><strong>{{ row.documentSummary ? `${row.documentSummary.uploadedCategoryCount}/3 已上传` : '资料摘要暂无' }}</strong><el-button class="density-action" data-tone="neutral" v-if="access.can(permission.deliveryList)" size="small" @click="openDocuments(row as DeliveryOrderRow)">管理资料</el-button></div><div class="delivery-document-categories"><span v-for="category in deliveryDocumentCategories" :key="category.category" :class="{ uploaded: row.documentSummary?.categories.some((item: { category: string; status: string }) => item.category === category.category && item.status === 'UPLOADED') }">{{ category.label }} · {{ row.documentSummary?.categories.find((item: { category: string }) => item.category === category.category)?.status === 'UPLOADED' ? '已上传' : '未上传' }}</span></div></div></template><template #status="{ row }"><StatusBadge :status="statusLabels[String(row.status)] || String(row.status || '—')" /></template><template #pagination-left>共 {{ total }} 条派送单</template></DataTable></section></ListPageLayout></AdminPage><AppDialog class="admin-density-dialog" v-model="statusOpen" title="编辑派送状态" width="min(520px, calc(100vw - 28px))" confirm-text="保存状态" :confirm-loading="statusSaving" :loading="statusLoading" :confirm-disabled="!statusForm.status || statusConflict || statusLoading" @confirm="submitStatus"><el-form class="density-form" label-position="top"><el-form-item label="派送单号"><el-input :model-value="statusRow?.deliveryNo" readonly /></el-form-item><el-form-item label="派送状态" required><el-select v-model="statusForm.status" placeholder="请选择派送状态"><el-option v-for="option in statusOptions" :key="option.value" :label="option.label" :value="option.value" /></el-select></el-form-item><el-form-item label="备注"><el-input v-model="statusForm.remark" type="textarea" :rows="3" maxlength="500" show-word-limit placeholder="请输入状态备注（选填）" /></el-form-item></el-form><LoadErrorState v-if="statusError" compact title="派送状态操作失败" :message="statusError.message" :show-retry="statusConflict" @retry="refreshStatus"><template #details><ApiErrorMeta :details="statusError" /></template></LoadErrorState></AppDialog><AppDialog class="admin-density-dialog" v-model="returnOpen" title="标记退货" width="min(720px, calc(100vw - 28px))" confirm-text="确认转入退货" :loading="returnLoading" :confirm-loading="returnSaving" @confirm="submitReturn"><el-form class="density-form" label-position="top"><el-form-item label="派送单号"><el-input :model-value="returnRow?.deliveryNo" readonly /></el-form-item><el-form-item label="对应入仓单" required><el-select v-model="returnForm.inboundOrderId" placeholder="请选择该派送单对应的入仓单"><el-option v-for="option in returnOptions" :key="String(option.inboundOrderId)" :value="String(option.inboundOrderId)" :label="`${option.inboundCode} · ${option.lastMileOrderNo || '无尾程单号'}`" /></el-select></el-form-item><el-form-item label="退货原因" required><el-input v-model="returnForm.reason" type="textarea" :rows="4" maxlength="1000" show-word-limit placeholder="请输入退货原因" /></el-form-item><div class="return-grid"><el-form-item label="退货去向" required><el-select v-model="returnForm.returnDirection" placeholder="请选择退货去向"><el-option label="退回海外仓" value="OVERSEAS_WAREHOUSE" /><el-option label="退回客户" value="CUSTOMER" /><el-option label="其他" value="OTHER" /></el-select></el-form-item><el-form-item label="退回物流单号"><el-input v-model="returnForm.returnLogisticsNo" placeholder="可安排物流后补充" /></el-form-item></div><el-form-item label="原出库明细" required><div class="return-sources"><p v-if="!returnItems.length">暂无可退原出库明细</p><div v-for="item in returnItems" :key="`${item.outboundPalletItemId}:${item.inventoryPositionId}`" class="return-source"><el-checkbox v-model="item.selected" :disabled="returnSaving || item.maxReturnPackages < 1">{{ item.palletNo || '—' }} · {{ item.skuCode || '—' }}（最多 {{ item.maxReturnPackages }} 箱）</el-checkbox><el-input-number v-model="item.packageCount" placeholder="请输入退货箱数" :disabled="!item.selected || returnSaving" :min="1" :max="item.maxReturnPackages" :precision="0" :aria-label="`退货箱数 ${item.palletNo || '—'} ${item.skuCode || '—'}`" /></div></div></el-form-item><LoadErrorState v-if="returnError" compact title="标记退货失败" :message="returnError.message" :show-retry="false"><template #details><ApiErrorMeta :details="returnError" /></template></LoadErrorState><el-alert title="确认后会生成异常退货单，并将派送单标记为退货处理中。" type="warning" :closable="false" /></el-form></AppDialog><DeliveryDocumentsDialog v-if="documentsRow" v-model="documentsOpen" :delivery-no="documentsRow.deliveryNo" :customer-id="documentsRow.customerId" @saved="load()" /></template>
+
+<style scoped>.delivery-document-summary{display:grid;gap:var(--admin-space-3);padding:var(--admin-space-2) 0}.delivery-document-summary>div:first-child{display:flex;align-items:center;justify-content:space-between;gap:var(--admin-space-5)}.delivery-document-categories{display:flex;flex-wrap:wrap;gap:var(--admin-space-2) var(--admin-space-5);font-size:var(--admin-font-caption);color:var(--cc-muted)}.delivery-document-categories .uploaded{color:var(--el-color-success)}.return-sources { width:100%; }.return-source { display:flex; flex-wrap:wrap; align-items:center; justify-content:space-between; gap:var(--admin-space-5); padding:var(--admin-space-3) 0; }.return-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 0 var(--admin-space-5); }.return-grid :deep(.el-input),.return-grid :deep(.el-select),.return-grid :deep(.el-input-number){width:100%} @media (max-width: 720px) { .return-grid { grid-template-columns: 1fr; } }</style>
diff --git a/src/modules/overseas-warehouse/pages/DispatchDetailView.test.ts b/src/modules/overseas-warehouse/pages/DispatchDetailView.test.ts
new file mode 100644
index 00000000..cf1e8372
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/DispatchDetailView.test.ts
@@ -0,0 +1,32 @@
+import ElementPlus from 'element-plus'
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { getDispatch } from '../api/dispatches'
+import DispatchDetailView from './DispatchDetailView.vue'
+import { DataTableStub } from './phase5TestStubs'
+
+const routerPush = vi.hoisted(() => vi.fn())
+vi.mock('vue-router', () => ({ useRoute: () => ({ params: { dispatchNo: 'PC/1' } }), useRouter: () => ({ push: routerPush }) }))
+vi.mock('../api/dispatches', () => ({ getDispatch: vi.fn() }))
+
+describe('DispatchDetailView', () => {
+  beforeEach(() => {
+    routerPush.mockReset()
+    vi.mocked(getDispatch).mockReset().mockResolvedValue({
+      id: '1', dispatchNo: 'PC/1', vehiclePlate: 'CA-100', driverName: '张师傅', status: 'PENDING_DEPARTURE',
+      route: 'LAX → ONT8', items: [{ id: '11', planPalletId: '20', orderNo: 'LM-1', warehousePalletId: '21', fbaWarehouseCode: 'ONT8', volumeCbm: 1.25 }],
+    })
+  })
+
+  it('loads the business dispatch number and renders summary and related orders', async () => {
+    const wrapper = mount(DispatchDetailView, { global: { plugins: [ElementPlus], stubs: { DataTable: DataTableStub } } })
+    await flushPromises()
+    expect(getDispatch).toHaveBeenCalledWith('PC/1')
+    expect(wrapper.text()).toContain('PC/1')
+    expect(wrapper.text()).toContain('CA-100')
+    expect(wrapper.text()).toContain('待发车')
+    const table = wrapper.findComponent(DataTableStub)
+    expect(table.props('data')).toEqual([{ orderNo: 'LM-1', weight: '—', palletCount: 1, fbaWarehouse: 'ONT8', volume: 1.25, containerNo: '—' }])
+    wrapper.unmount()
+  })
+})
diff --git a/src/modules/overseas-warehouse/pages/DispatchDetailView.vue b/src/modules/overseas-warehouse/pages/DispatchDetailView.vue
new file mode 100644
index 00000000..4d0c0db7
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/DispatchDetailView.vue
@@ -0,0 +1,166 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, ref } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { getDispatch, type DispatchItemDto, type DispatchSummaryDto } from '../api/dispatches'
+import OverseasDetailShell from '../components/OverseasDetailShell.vue'
+import { formatOverseasDateTime } from '../lastMilePresentation'
+
+interface DetailField { label: string; value: string | number }
+interface RelatedOrderRow {
+  orderNo: string
+  weight: string
+  palletCount: number
+  fbaWarehouse: string
+  volume: number
+  containerNo: string
+}
+
+const route = useRoute()
+const router = useRouter()
+const dispatchNo = computed(() => String(route.params.dispatchNo || ''))
+const detail = ref<DispatchSummaryDto | null>(null)
+const loading = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+
+const dispatchStatusLabels: Record<string, string> = {
+  PENDING_DEPARTURE: '待发车',
+  PICKING: '拣货中',
+  READY_TO_DEPART: '待发车（拣货完成）',
+  PARTIAL_READY_TO_DEPART: '待发车（部分完成）',
+  DEPARTED: '已发车',
+  PARTIAL_DEPARTED: '已发车（部分完成）',
+  CANCELLED: '已取消',
+}
+const appointmentStatusLabels: Record<string, string> = {
+  PENDING: '待预约',
+  BOOKED: '已预约',
+  RESERVED: '已预约',
+  CONFIRMED: '已确认',
+  CANCELLED: '已取消',
+}
+
+function text(value: unknown) { return String(value ?? '').trim() || '—' }
+function dispatchStatus(value: unknown) {
+  const code = String(value ?? '').trim()
+  return dispatchStatusLabels[code] || text(code)
+}
+function appointmentStatus(value: unknown) {
+  const code = String(value ?? '').trim()
+  return appointmentStatusLabels[code] || text(code)
+}
+function orderReferences(item: DispatchItemDto) {
+  const references = String(item.orderRefs || '').split(/[,，;；\s]+/).map((value) => value.trim()).filter(Boolean)
+  return references.length ? references : [text(item.orderNo)]
+}
+
+const vehicleFields = computed<DetailField[]>(() => [
+  { label: '车牌号', value: text(detail.value?.vehiclePlate) },
+  { label: '司机', value: text(detail.value?.driverName) },
+  { label: '联系电话', value: text(detail.value?.driverPhone) },
+  { label: '拖车公司名称', value: text(detail.value?.carrierName) },
+  { label: '车辆状态', value: dispatchStatus(detail.value?.status) },
+])
+const dispatchFields = computed<DetailField[]>(() => [
+  { label: '路线', value: text(detail.value?.route) },
+  { label: '发车时间', value: formatOverseasDateTime(detail.value?.departAt) },
+  { label: '预计到达时间', value: formatOverseasDateTime(detail.value?.estimatedArrivalAt) },
+  { label: 'FBA预约', value: appointmentStatus(detail.value?.fbaAppointmentStatus) },
+  { label: '车辆预约', value: appointmentStatus(detail.value?.vehicleAppointmentStatus) },
+])
+const documentFields = computed<DetailField[]>(() => [
+  { label: '排车单号', value: text(detail.value?.dispatchNo || dispatchNo.value) },
+  { label: '关联订单', value: text(detail.value?.orderNos) },
+  { label: '创建时间', value: formatOverseasDateTime(detail.value?.createdAt) },
+  { label: '更新时间', value: '—' },
+  { label: '备注', value: '—' },
+  ...(detail.value?.partialCompletionReason
+    ? [{ label: '部分完成原因', value: text(detail.value.partialCompletionReason) }]
+    : []),
+])
+
+const relatedOrders = computed<RelatedOrderRow[]>(() => {
+  const grouped = new Map<string, { pallets: Set<string>; destinations: Set<string>; volume: number }>()
+  for (const item of detail.value?.items || []) {
+    for (const orderNo of orderReferences(item)) {
+      const current = grouped.get(orderNo) || { pallets: new Set<string>(), destinations: new Set<string>(), volume: 0 }
+      current.pallets.add(String(item.warehousePalletId || item.planPalletId || item.id))
+      const destination = text(item.fbaWarehouseCode || item.destinationWarehouseCode || item.destinationWarehouseName)
+      if (destination !== '—') current.destinations.add(destination)
+      current.volume += Number(item.volumeCbm || 0)
+      grouped.set(orderNo, current)
+    }
+  }
+  return [...grouped.entries()].map(([orderNo, value]) => ({
+    orderNo,
+    weight: '—',
+    palletCount: value.pallets.size,
+    fbaWarehouse: [...value.destinations].join('、') || '—',
+    volume: Number(value.volume.toFixed(3)),
+    containerNo: '—',
+  }))
+})
+
+const orderColumns: DataTableColumn[] = [
+  { key: 'orderNo', prop: 'orderNo', label: '订单号', minWidth: 210 },
+  { key: 'weight', prop: 'weight', label: '重量(lb)', minWidth: 130, align: 'right' },
+  { key: 'palletCount', prop: 'palletCount', label: '托数', minWidth: 100, align: 'right' },
+  { key: 'fbaWarehouse', prop: 'fbaWarehouse', label: '目的FBA仓', minWidth: 150 },
+  { key: 'volume', prop: 'volume', label: '体积(m³)', minWidth: 130, align: 'right' },
+  { key: 'containerNo', prop: 'containerNo', label: '集装箱号', minWidth: 170 },
+]
+
+async function load() {
+  if (!dispatchNo.value) {
+    loadError.value = { message: '详情缺少排车单号，请从排车列表重新进入' }
+    return
+  }
+  loading.value = true
+  loadError.value = null
+  try { detail.value = await getDispatch(dispatchNo.value) }
+  catch (error) { loadError.value = getApiErrorDetails(error, '排车详情加载失败，请重试') }
+  finally { loading.value = false }
+}
+function back() { void router.push({ name: 'overseas-dispatches' }) }
+
+onMounted(load)
+</script>
+
+<template>
+  <OverseasDetailShell class="admin-density" dense title="排车详情" reference-label="排车单号" :reference-value="detail?.dispatchNo || dispatchNo" back-label="返回排车列表" domain="排车详情" :pending="false" :status-text="detail ? dispatchStatus(detail.status) : '加载中'" @back="back">
+    <LoadErrorState v-if="loadError" title="排车详情加载失败" :message="loadError.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="loadError" /></template></LoadErrorState>
+    <div v-else v-loading="loading" class="dispatch-detail" :aria-busy="loading">
+      <div class="summary-grid">
+        <section class="detail-section" aria-labelledby="dispatch-vehicle-heading"><h2 id="dispatch-vehicle-heading">车辆信息</h2><dl class="detail-fields density-fields"><div v-for="field in vehicleFields" :key="field.label"><dt>{{ field.label }}</dt><dd>{{ field.value }}</dd></div></dl></section>
+        <section class="detail-section" aria-labelledby="dispatch-info-heading"><h2 id="dispatch-info-heading">排车信息</h2><dl class="detail-fields density-fields"><div v-for="field in dispatchFields" :key="field.label"><dt>{{ field.label }}</dt><dd>{{ field.value }}</dd></div></dl></section>
+        <section class="detail-section document-section" aria-labelledby="dispatch-document-heading"><h2 id="dispatch-document-heading">单据信息</h2><dl class="detail-fields density-fields"><div v-for="field in documentFields" :key="field.label"><dt>{{ field.label }}</dt><dd>{{ field.value }}</dd></div></dl></section>
+      </div>
+      <section class="detail-section order-section" aria-labelledby="dispatch-orders-heading"><h2 id="dispatch-orders-heading">关联订单明细</h2><DataTable :data="relatedOrders" :columns="orderColumns" column-settings-mode="hide" row-key="orderNo" empty-text="暂无关联订单明细" /></section>
+    </div>
+  </OverseasDetailShell>
+</template>
+
+<style scoped>
+.detail-section { min-width: 0; padding: var(--admin-space-5); }
+.summary-grid > .detail-section:nth-child(2) { border-right: 0; }
+.document-section { grid-column: 1 / -1; }
+.order-section h2 { margin-right: var(--admin-space-1); margin-left: var(--admin-space-1); }
+@media (max-width: 960px) {
+  .summary-grid { grid-template-columns: 1fr; }
+  .summary-grid > .detail-section, .summary-grid > .detail-section:nth-child(2) { border-right: 0; }
+  .document-section { grid-column: auto; }
+  .detail-fields, .document-section .detail-fields { grid-template-columns: 1fr; }
+  .detail-fields > div { grid-template-columns: 132px minmax(0, 1fr); }
+}
+
+.dispatch-detail { min-width: 0; min-height: 0; }
+.summary-grid { display: grid; grid-template-columns: minmax(0, 1fr); border: 0; border-bottom: 0; background: #fff; }
+.summary-grid > .detail-section { border-right: 0; border-bottom: 1px solid var(--cc-border); }
+.detail-section h2 { margin: 0 0 var(--admin-space-5); color: var(--cc-text); font-size: var(--admin-font-section); }
+.order-section { overflow: hidden; border: 0; border-top: 0; background: #fff; }
+
+</style>
diff --git a/src/modules/overseas-warehouse/pages/DispatchesView.test.ts b/src/modules/overseas-warehouse/pages/DispatchesView.test.ts
new file mode 100644
index 00000000..a8d64658
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/DispatchesView.test.ts
@@ -0,0 +1,149 @@
+import ElementPlus from 'element-plus'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import QueryToolbar, { type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import { cancelDispatch, getDispatchBolPdf, listDispatches, removeDispatchItem, transferDispatchToDelivery, updateDispatch } from '../api/dispatches'
+import DispatchesView from './DispatchesView.vue'
+
+const canPermission = vi.hoisted(() => vi.fn<(permissionCode: string) => boolean>(() => true))
+vi.mock('@/core/access/accessPreview', () => ({ useAccessPreviewStore: () => ({ can: canPermission }) }))
+vi.mock('../api/dispatches', () => ({ listDispatches: vi.fn(), removeDispatchItem: vi.fn(), getDispatchBolPdf: vi.fn(), updateDispatch: vi.fn(), cancelDispatch: vi.fn(), transferDispatchToDelivery: vi.fn() }))
+
+class ResizeObserverStub implements ResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+
+function memoryStorage(): Storage {
+  const values = new Map<string, string>()
+  return {
+    get length() { return values.size },
+    clear: () => values.clear(),
+    getItem: (key) => values.get(key) ?? null,
+    key: (index) => [...values.keys()][index] ?? null,
+    removeItem: (key) => values.delete(key),
+    setItem: (key, value) => values.set(key, value),
+  }
+}
+
+enableAutoUnmount(afterEach)
+afterAll(() => vi.unstubAllGlobals())
+
+describe('DispatchesView', () => {
+  beforeEach(() => {
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+    vi.stubGlobal('localStorage', memoryStorage())
+    vi.mocked(listDispatches).mockReset().mockResolvedValue({
+      records: [{
+        id: '190000000000000099', dispatchNo: 'PC-1', vehiclePlate: 'CA-100', driverName: '张师傅',
+        driverPhone: '555-0100', carrierName: 'Carrier A', orderNos: 'LM-1,LM-2', route: 'LAX -> ONT8',
+        overseasWarehouseName: '洛杉矶仓', departAt: '2026-08-20T09:00:00', fbaAppointmentNo: 'FBA-1',
+        fbaAppointmentStatus: 'CONFIRMED', vehicleAppointmentStatus: 'BOOKED', estimatedArrivalAt: '2026-08-20T18:00:00',
+        status: 'PENDING_DEPARTURE', palletCount: 12, packageCount: 80, createdAt: '2026-08-19T16:00:00',
+      }],
+      page: 1, size: 20, total: 1, pages: 1,
+    })
+    vi.mocked(updateDispatch).mockReset()
+    vi.mocked(getDispatchBolPdf).mockReset().mockResolvedValue(new Blob(['%PDF-test'], { type: 'application/pdf' }))
+    vi.mocked(removeDispatchItem).mockReset()
+    vi.mocked(cancelDispatch).mockReset()
+    vi.mocked(transferDispatchToDelivery).mockReset()
+    canPermission.mockReset().mockReturnValue(true)
+  })
+
+
+  it.each([
+    [[], ['查看', '打印BOL'], false],
+    [['edit'], ['查看', '打印BOL', '编辑'], false],
+    [['cancel'], ['查看', '打印BOL', '取消'], false],
+    [['transfer-delivery'], ['查看', '打印BOL', '转派送'], false],
+    [['edit', 'cancel'], ['查看', '打印BOL', '编辑', ''], true],
+    [['edit', 'cancel', 'transfer-delivery'], ['查看', '打印BOL', '编辑', ''], true],
+  ])('uses the row action threshold for permissions %j', async (allowed, labels, overflow) => {
+    canPermission.mockImplementation(code => allowed.some(action => code === 'platform:overseas-warehouse:dispatch:' + action))
+    const wrapper = mount(DispatchesView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    const actions = wrapper.get('.el-table__body-wrapper .density-actions')
+    expect(actions.findAll('button').map(button => button.text().trim())).toEqual(labels)
+    expect(actions.find('.el-dropdown').exists()).toBe(overflow)
+  })
+
+  it('loads immediately and sends only supported page filters', async () => {
+    const wrapper = mount(DispatchesView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(listDispatches).toHaveBeenCalledWith({ page: 1, size: 10, dispatchNo: undefined, vehiclePlate: undefined, status: undefined, fbaAppointmentNo: undefined })
+
+    const model: QueryModel = {
+      dispatchNo: 'PC-1', vehiclePlate: 'CA-100',
+      status: 'PENDING_DEPARTURE', fbaAppointmentNo: 'FBA-1',
+    }
+    wrapper.findComponent(QueryToolbar).vm.$emit('search', model)
+    await flushPromises()
+
+    expect(listDispatches).toHaveBeenCalledWith({
+      page: 1, size: 10, dispatchNo: 'PC-1',
+      vehiclePlate: 'CA-100', status: 'PENDING_DEPARTURE', fbaAppointmentNo: 'FBA-1',
+    })
+    expect(wrapper.text()).toContain('PC-1')
+    expect(wrapper.text()).toContain('待发车')
+    expect(wrapper.text()).toContain('FBA-1 · 已确认')
+    expect(wrapper.text()).toContain('已预约')
+  })
+
+  it('keeps long dispatch identifiers as strings', async () => {
+    vi.mocked(listDispatches).mockResolvedValueOnce({
+      records: [{ id: '190000000000000099', dispatchNo: '190000000000000099' }],
+      page: 1, size: 20, total: 1, pages: 1,
+    })
+    const wrapper = mount(DispatchesView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(wrapper.html()).toContain('190000000000000099')
+  })
+
+  it('opens the server-generated BOL PDF with one request', async () => {
+    const pdfWindow = { location: { href: '' }, close: vi.fn() }
+    vi.spyOn(window, 'open').mockReturnValue(pdfWindow as unknown as Window)
+    vi.stubGlobal('URL', { createObjectURL: vi.fn(() => 'blob:dispatch-bol'), revokeObjectURL: vi.fn() })
+    const wrapper = mount(DispatchesView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(getDispatchBolPdf).not.toHaveBeenCalled()
+
+    await wrapper.findAll('.el-table__body-wrapper button').find((button) => button.text().trim() === '打印BOL')!.trigger('click')
+    await flushPromises()
+
+    expect(getDispatchBolPdf).toHaveBeenCalledOnce()
+    expect(getDispatchBolPdf).toHaveBeenCalledWith('PC-1')
+    expect(pdfWindow.location.href).toBe('blob:dispatch-bol')
+  })
+
+  it('documents the backend feature flag required by a missing endpoint', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/overseas-warehouse/pages/DispatchesView.vue'), 'utf8')
+    expect(source).toContain('请确认海外尾程排车接口已发布')
+  })
+
+  it('gates edit, cancel and transfer with independent permissions and service statuses', async () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/overseas-warehouse/pages/DispatchesView.vue'), 'utf8')
+    expect(source).toContain('permission.dispatchEdit')
+    expect(source).toContain('permission.dispatchCancel')
+    expect(source).toContain('permission.dispatchTransferDelivery')
+    expect(source).toMatch(/function isPendingDeparture\(row: DispatchListItem\)\s*{\s*return row\.statusCode === 'PENDING_DEPARTURE'/)
+    expect(source).toMatch(/access\.can\(permission\.dispatchEdit\)\s*&&\s*isPendingDeparture\(row\)/)
+    expect(source).toMatch(/access\.can\(permission\.dispatchTransferDelivery\)\s*&&\s*\['PENDING_DEPARTURE', 'PICKING', 'READY_TO_DEPART'\]\.includes\(row\.statusCode\)/)
+    expect(source).toContain('未生成出库单前可移除托盘')
+    expect(source).toContain('removeDispatchItem')
+    expect(source).not.toContain('托盘箱唛确认')
+    expect(source).not.toContain('palletCartonMarks')
+    expect(source).toContain('v-model="editForm.route" readonly')
+    expect(source).not.toContain('route: editForm.route.trim()')
+    expect(source).toContain('dispatchVehicleSizeOptions')
+    expect(source).not.toContain('departDispatch')
+
+    canPermission.mockReturnValue(false)
+    const wrapper = mount(DispatchesView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(wrapper.text()).not.toContain('转派送')
+  })
+})
diff --git a/src/modules/overseas-warehouse/pages/DispatchesView.vue b/src/modules/overseas-warehouse/pages/DispatchesView.vue
new file mode 100644
index 00000000..656a8939
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/DispatchesView.vue
@@ -0,0 +1,588 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, reactive, ref } from 'vue'
+import { MoreHorizontal } from '@lucide/vue'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import { useRouter } from 'vue-router'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import OperationErrorToast from '@/shared/components/OperationErrorToast.vue'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { cancelDispatch, getDispatchBolPdf, listDispatches, removeDispatchItem, transferDispatchToDelivery, updateDispatch, type DispatchItemDto, type DispatchSummaryDto } from '../api/dispatches'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import type { DispatchListItem } from '../types'
+import { formatOverseasDateTime } from '../lastMilePresentation'
+import { overseasWarehousePermissions as permission } from '../permissions'
+import { dispatchVehicleSizeOptions } from '../dispatchVehicleSpecs'
+
+const router = useRouter()
+const access = useAccessPreviewStore()
+const rows = ref<DispatchListItem[]>([])
+const loading = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const page = ref(1)
+const pageSize = ref(10)
+const total = ref(0)
+const filters = ref<QueryModel>({
+  dispatchNo: '',
+  vehiclePlate: '',
+  status: '',
+  fbaAppointmentNo: '',
+})
+const transferOpen = ref(false)
+const transferRow = ref<DispatchListItem | null>(null)
+const transferSaving = ref(false)
+const mutationError = ref<ApiErrorDetails | null>(null)
+const editOpen = ref(false)
+const editRow = ref<DispatchListItem | null>(null)
+const editSaving = ref(false)
+const editItems = ref<DispatchItemDto[]>([])
+const removingItemId = ref('')
+const bolLoadingNo = ref('')
+const dispatchSnapshots = new Map<string, DispatchSummaryDto>()
+const editForm = reactive({
+  vehiclePlate: '',
+  driverName: '',
+  driverPhone: '',
+  carrierName: '',
+  route: '',
+  departAt: '',
+  fbaAppointmentNo: '',
+  fbaAppointmentStatus: '',
+  vehicleAppointmentStatus: '',
+  estimatedArrivalAt: '',
+})
+const transferForm = reactive({
+  plannedDeliveryAt: '',
+  deliveryMethod: '',
+  waybillNo: '',
+  carrierName: '',
+  pickupMethod: '',
+  loadingType: '',
+  vehicleType: '',
+  vehicleSize: '',
+  driverName: '',
+  driverPhone: '',
+  vehiclePlate: '',
+  appointmentAccount: '',
+  sellerName: '',
+  deliveryFee: undefined as number | undefined,
+  loadingFee: undefined as number | undefined,
+  appointmentFee: undefined as number | undefined,
+  remark: '',
+})
+
+const deliveryMethodOptions = [
+  { label: 'FBA自提', value: 'FBA_PICKUP' },
+  { label: '客户自提', value: 'CUSTOMER_PICKUP' },
+  { label: '卡派打托', value: 'TRUCK_PALLET' },
+  { label: '卡派地板', value: 'TRUCK_FLOOR' },
+  { label: '快递', value: 'EXPRESS' },
+  { label: '外配', value: 'OUTSOURCED' },
+  { label: '专车直送', value: 'DEDICATED_TRUCK' },
+  { label: '零担派送', value: 'LTL' },
+]
+const pickupMethodOptions = [
+  { label: '一提一卸', value: 'ONE_PICKUP_ONE_DROP' },
+  { label: '一提多卸', value: 'ONE_PICKUP_MULTI_DROP' },
+  { label: '多提一卸', value: 'MULTI_PICKUP_ONE_DROP' },
+  { label: '多提多卸', value: 'MULTI_PICKUP_MULTI_DROP' },
+  { label: '仓库自提', value: 'WAREHOUSE_PICKUP' },
+]
+const loadingTypeOptions = [
+  { label: '托盘', value: 'PALLET' },
+  { label: '地板', value: 'FLOOR' },
+  { label: '混装', value: 'MIXED' },
+]
+const vehicleTypeOptions = ['厢式货车', '平板车', '冷藏车', '集装箱卡车', '尾板车'].map((label) => ({ label, value: label }))
+const vehicleSizeOptions = dispatchVehicleSizeOptions
+const appointmentAccountOptions = [
+  { label: '4号账号（美西）', value: '4' },
+  { label: '8号账号（美东）', value: '8' },
+  { label: '10号账号（美中）', value: '10' },
+  { label: '12号账号（加拿大）', value: '12' },
+  { label: '买约', value: 'BUY_APPOINTMENT' },
+]
+const isBuyAppointment = computed(() => transferForm.appointmentAccount === 'BUY_APPOINTMENT')
+const needsLoadingFee = computed(() => ['FLOOR', 'MIXED'].includes(transferForm.loadingType))
+
+const statusOptions = [
+  { label: '待发车', value: 'PENDING_DEPARTURE' },
+  { label: '拣货中', value: 'PICKING' },
+  { label: '待发车（拣货完成）', value: 'READY_TO_DEPART' },
+  { label: '待发车（部分完成）', value: 'PARTIAL_READY_TO_DEPART' },
+  { label: '已发车', value: 'DEPARTED' },
+  { label: '已发车（部分完成）', value: 'PARTIAL_DEPARTED' },
+  { label: '已取消', value: 'CANCELLED' },
+]
+
+const fields = computed<QueryField[]>(() => [
+  {
+    key: 'dispatchNo',
+    type: 'input',
+    label: '排车单号',
+    placeholder: '请输入排车单号',
+    width: 220,
+  },
+  {
+    key: 'vehiclePlate',
+    type: 'input',
+    label: '车牌号',
+    placeholder: '请输入车牌号',
+    width: 180,
+  },
+  {
+    key: 'status',
+    type: 'select',
+    label: '车辆状态',
+    placeholder: '全部状态',
+    options: statusOptions,
+    width: 180,
+  },
+  {
+    key: 'fbaAppointmentNo',
+    type: 'input',
+    label: 'FBA预约号',
+    placeholder: '请输入FBA预约号',
+    width: 220,
+  },
+])
+
+const columns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 380, fixed: 'left', slotName: 'actions' },
+  { key: 'dispatchNo', prop: 'dispatchNo', label: '排车单号', minWidth: 170, fixed: 'left' },
+  { key: 'vehiclePlate', prop: 'vehiclePlate', label: '车牌号', minWidth: 130 },
+  { key: 'driverName', prop: 'driverName', label: '司机', minWidth: 120 },
+  { key: 'driverPhone', prop: 'driverPhone', label: '联系电话', minWidth: 140 },
+  {
+    key: 'carrierName',
+    prop: 'carrierName',
+    label: '托车公司名称',
+    minWidth: 160,
+  },
+  { key: 'orderNos', prop: 'orderNos', label: '关联订单', minWidth: 220 },
+  { key: 'route', prop: 'route', label: '路线', minWidth: 180 },
+  {
+    key: 'overseasWarehouse',
+    prop: 'overseasWarehouse',
+    label: '海外仓',
+    minWidth: 160,
+  },
+  { key: 'departAt', prop: 'departAt', label: '发车时间', minWidth: 170 },
+  {
+    key: 'fbaAppointment',
+    prop: 'fbaAppointment',
+    label: 'FBA预约',
+    minWidth: 180,
+  },
+  {
+    key: 'vehicleAppointment',
+    prop: 'vehicleAppointment',
+    label: '车辆预约',
+    minWidth: 130,
+  },
+  {
+    key: 'estimatedArrivalAt',
+    prop: 'estimatedArrivalAt',
+    label: '预计到达时间',
+    minWidth: 170,
+  },
+  {
+    key: 'palletCount',
+    prop: 'palletCount',
+    label: '托盘数',
+    width: 90,
+    align: 'right',
+  },
+  {
+    key: 'packageCount',
+    prop: 'packageCount',
+    label: '箱数',
+    width: 80,
+    align: 'right',
+  },
+  {
+    key: 'status',
+    prop: 'status',
+    label: '车辆状态',
+    width: 150,
+    slotName: 'status',
+  },
+  { key: 'createdAt', prop: 'createdAt', label: '创建时间', minWidth: 170 },
+]
+
+function text(value: unknown) {
+  const normalized = String(value ?? '').trim()
+  return normalized || '—'
+}
+
+function number(value: unknown) {
+  const normalized = Number(value)
+  return Number.isFinite(normalized) ? normalized : 0
+}
+
+function statusLabel(value: unknown) {
+  const status = String(value || '')
+  return statusOptions.find((option) => option.value === status)?.label || text(value)
+}
+
+function appointmentStatusLabel(value: unknown) {
+  const code = String(value || '')
+  const labels: Record<string, string> = {
+    PENDING: '待预约',
+    BOOKED: '已预约',
+    CONFIRMED: '已确认',
+    CANCELLED: '已取消',
+  }
+  return labels[code] || text(value)
+}
+
+function appointmentLabel(numberValue: unknown, statusValue: unknown) {
+  const appointmentNo = text(numberValue)
+  const appointmentStatus = appointmentStatusLabel(statusValue)
+  if (appointmentNo === '—') return appointmentStatus
+  return appointmentStatus === '—' ? appointmentNo : `${appointmentNo} · ${appointmentStatus}`
+}
+
+function toListItem(dto: DispatchSummaryDto): DispatchListItem {
+  return {
+    id: String(dto.id),
+    dispatchNo: text(dto.dispatchNo),
+    vehiclePlate: text(dto.vehiclePlate),
+    driverName: text(dto.driverName),
+    driverPhone: text(dto.driverPhone),
+    carrierName: text(dto.carrierName),
+    orderNos: text(dto.orderNos),
+    route: text(dto.route),
+    overseasWarehouse: text(dto.overseasWarehouseName || '仓库名称待补充'),
+    departAt: formatOverseasDateTime(dto.departAt),
+    fbaAppointment: appointmentLabel(dto.fbaAppointmentNo, dto.fbaAppointmentStatus),
+    vehicleAppointment: appointmentStatusLabel(dto.vehicleAppointmentStatus),
+    estimatedArrivalAt: formatOverseasDateTime(dto.estimatedArrivalAt),
+    status: statusLabel(dto.status),
+    statusCode: String(dto.status || ''),
+    palletCount: number(dto.palletCount),
+    packageCount: number(dto.packageCount),
+    createdAt: formatOverseasDateTime(dto.createdAt),
+  }
+}
+
+function dispatchError(error: unknown) {
+  const details = getApiErrorDetails(error, '排车列表加载失败，请重试')
+  return details.code === 'HTTP_404'
+    ? {
+        ...details,
+        message: '排车接口未启用或不存在，请确认海外尾程排车接口已发布',
+      }
+    : details
+}
+
+async function load(model: QueryModel = filters.value) {
+  Object.assign(filters.value, model)
+  loading.value = true
+  loadError.value = null
+  try {
+    const result = await listDispatches({
+      page: page.value,
+      size: pageSize.value,
+      dispatchNo: String(filters.value.dispatchNo || '').trim() || undefined,
+      vehiclePlate: String(filters.value.vehiclePlate || '').trim() || undefined,
+      status: String(filters.value.status || '').trim() || undefined,
+      fbaAppointmentNo: String(filters.value.fbaAppointmentNo || '').trim() || undefined,
+    })
+    dispatchSnapshots.clear()
+    result.records.forEach((item) => dispatchSnapshots.set(String(item.dispatchNo), item))
+    rows.value = result.records.map(toListItem)
+    total.value = result.total
+  } catch (error) {
+    rows.value = []
+    total.value = 0
+    loadError.value = dispatchError(error)
+  } finally {
+    loading.value = false
+  }
+}
+
+function search(model: QueryModel) {
+  page.value = 1
+  void load(model)
+}
+function reset(model: QueryModel) {
+  page.value = 1
+  void load(model)
+}
+function openDetail(row: DispatchListItem) {
+  void router.push({
+    name: 'overseas-dispatch-detail',
+    params: { dispatchNo: row.dispatchNo },
+  })
+}
+async function openBol(row: DispatchListItem) {
+  if (bolLoadingNo.value) return
+  const pdfWindow = window.open('', '_blank')
+  if (!pdfWindow) { ElMessage.warning('浏览器拦截了 BOL PDF 窗口，请允许本站打开新窗口'); return }
+  bolLoadingNo.value = row.dispatchNo
+  mutationError.value = null
+  try {
+    const pdf = await getDispatchBolPdf(row.dispatchNo)
+    const url = URL.createObjectURL(pdf)
+    pdfWindow.location.href = url
+    window.setTimeout(() => URL.revokeObjectURL(url), 60_000)
+  } catch (cause) {
+    pdfWindow.close()
+    mutationError.value = getApiErrorDetails(cause, 'BOL PDF 生成失败，请重试')
+  } finally {
+    bolLoadingNo.value = ''
+  }
+}
+function rowActionCount(row: DispatchListItem) {
+  return 2 + Number(canEdit(row)) + Number(canTransfer(row)) + Number(canCancel(row))
+}
+function isPendingDeparture(row: DispatchListItem) {
+  return row.statusCode === 'PENDING_DEPARTURE'
+}
+function canEdit(row: DispatchListItem) {
+  return access.can(permission.dispatchEdit) && isPendingDeparture(row)
+}
+function canCancel(row: DispatchListItem) {
+  return access.can(permission.dispatchCancel) && row.statusCode === 'PENDING_DEPARTURE'
+}
+function canTransfer(row: DispatchListItem) {
+  return access.can(permission.dispatchTransferDelivery) && ['PENDING_DEPARTURE', 'PICKING', 'READY_TO_DEPART'].includes(row.statusCode)
+}
+function openEdit(row: DispatchListItem) {
+  if (!canEdit(row)) return
+  const source = dispatchSnapshots.get(row.dispatchNo)
+  editRow.value = row
+  editItems.value = [...(source?.items || [])]
+  Object.assign(editForm, {
+    vehiclePlate: source?.vehiclePlate || '',
+    driverName: source?.driverName || '',
+    driverPhone: source?.driverPhone || '',
+    carrierName: source?.carrierName || '',
+    route: source?.route || '',
+    departAt: source?.departAt || '',
+    fbaAppointmentNo: source?.fbaAppointmentNo || '',
+    fbaAppointmentStatus: source?.fbaAppointmentStatus || '',
+    vehicleAppointmentStatus: source?.vehicleAppointmentStatus || '',
+    estimatedArrivalAt: source?.estimatedArrivalAt || '',
+  })
+  mutationError.value = null
+  editOpen.value = true
+}
+function openTransfer(row: DispatchListItem) {
+  if (!canTransfer(row)) return
+  transferRow.value = row
+  Object.assign(transferForm, {
+    plannedDeliveryAt: '',
+    deliveryMethod: '',
+    waybillNo: '',
+    carrierName: row.carrierName === '—' ? '' : row.carrierName,
+    pickupMethod: '',
+    loadingType: '',
+    vehicleType: '',
+    vehicleSize: '',
+    driverName: row.driverName === '—' ? '' : row.driverName,
+    driverPhone: row.driverPhone === '—' ? '' : row.driverPhone,
+    vehiclePlate: row.vehiclePlate === '—' ? '' : row.vehiclePlate,
+    appointmentAccount: '',
+    sellerName: '',
+    deliveryFee: undefined,
+    loadingFee: undefined,
+    appointmentFee: undefined,
+    remark: '',
+  })
+  mutationError.value = null
+  transferOpen.value = true
+}
+async function submitEdit() {
+  if (!editRow.value || !canEdit(editRow.value) || editSaving.value) return
+  editSaving.value = true
+  mutationError.value = null
+  try {
+    await updateDispatch(editRow.value.dispatchNo, {
+      vehiclePlate: editForm.vehiclePlate.trim() || null,
+      driverName: editForm.driverName.trim() || null,
+      driverPhone: editForm.driverPhone.trim() || null,
+      carrierName: editForm.carrierName.trim() || null,
+      departAt: editForm.departAt || null,
+      fbaAppointmentNo: editForm.fbaAppointmentNo.trim() || null,
+      fbaAppointmentStatus: editForm.fbaAppointmentStatus || null,
+      vehicleAppointmentStatus: editForm.vehicleAppointmentStatus || null,
+      estimatedArrivalAt: editForm.estimatedArrivalAt || null,
+    })
+    editOpen.value = false
+    ElMessage.success('排车信息已保存')
+    await load()
+  } catch (cause) {
+    mutationError.value = getApiErrorDetails(cause, '排车信息保存失败，请重试')
+  } finally {
+    editSaving.value = false
+  }
+}
+async function removePallet(itemValue: unknown) {
+  const item = itemValue as DispatchItemDto
+  if (!editRow.value || removingItemId.value) return
+  try {
+    await ElMessageBox.confirm(`确认从排车单移除托盘 ${text(item.palletNo)}？移除后可重新排车。`, '移除排车托盘', { customClass: 'admin-density-confirm',
+      confirmButtonText: '确认移除',
+      cancelButtonText: '返回',
+      type: 'warning',
+    })
+  } catch {
+    return
+  }
+  removingItemId.value = String(item.id)
+  mutationError.value = null
+  try {
+    const updated = await removeDispatchItem(editRow.value.dispatchNo, String(item.id))
+    editItems.value = [...(updated.items || [])]
+    editForm.route = updated.route || ''
+    dispatchSnapshots.set(editRow.value.dispatchNo, updated)
+    const row = rows.value.find((value) => value.dispatchNo === editRow.value?.dispatchNo)
+    if (row) {
+      row.palletCount = number(updated.palletCount)
+      row.packageCount = number(updated.packageCount)
+      row.orderNos = text(updated.orderNos)
+      row.route = text(updated.route)
+    }
+    ElMessage.success('托盘已移除，可重新排车')
+  } catch (cause) {
+    mutationError.value = getApiErrorDetails(cause, '托盘移除失败，请重试')
+  } finally {
+    removingItemId.value = ''
+  }
+}
+async function cancel(row: DispatchListItem) {
+  if (!canCancel(row)) return
+  try {
+    await ElMessageBox.confirm(`确认取消排车单 ${row.dispatchNo}？取消后将释放托盘锁。`, '取消排车', { customClass: 'admin-density-confirm',
+      confirmButtonText: '确认取消',
+      cancelButtonText: '返回',
+      type: 'warning',
+    })
+  } catch {
+    return
+  }
+  mutationError.value = null
+  try {
+    await cancelDispatch(row.dispatchNo)
+    ElMessage.success('排车单已取消')
+    await load()
+  } catch (cause) {
+    mutationError.value = getApiErrorDetails(cause, '排车取消失败，请重试')
+  }
+}
+function handleMore(command: string, row: DispatchListItem) {
+  if (command === 'edit') openEdit(row)
+  else if (command === 'cancel') void cancel(row)
+}
+async function submitTransfer() {
+  if (!transferRow.value || !canTransfer(transferRow.value)) return
+  if (!transferForm.plannedDeliveryAt || !transferForm.deliveryMethod || !transferForm.pickupMethod || !transferForm.loadingType) {
+    ElMessage.warning('请填写预计派送时间、派送方式、提货方式和装车类型')
+    return
+  }
+  if (transferForm.deliveryFee == null) {
+    ElMessage.warning('请填写派送费用')
+    return
+  }
+  if (needsLoadingFee.value && transferForm.loadingFee == null) {
+    ElMessage.warning('当前装车类型需要填写装车费')
+    return
+  }
+  if (isBuyAppointment.value && (!transferForm.sellerName.trim() || transferForm.appointmentFee == null)) {
+    ElMessage.warning('买约时请填写卖家姓名和买约费用')
+    return
+  }
+  const feeInputs = [
+    ['DELIVERY_FEE', transferForm.deliveryFee, '派送费用'],
+    ['LOADING_FEE', needsLoadingFee.value ? transferForm.loadingFee : undefined, '装车费'],
+    ['APPOINTMENT_FEE', isBuyAppointment.value ? transferForm.appointmentFee : undefined, '买约费用'],
+  ] as const
+  const fees = feeInputs
+    .filter(([, amount]) => amount != null)
+    .map(([feeType, amount, feeName]) => ({
+      feeType,
+      feeName,
+      direction: 'RECEIVABLE' as const,
+      currency: 'USD' as const,
+      amount: Number(amount),
+      remark: feeName,
+    }))
+  transferSaving.value = true
+  try {
+    await transferDispatchToDelivery(transferRow.value.dispatchNo, {
+      idempotencyKey: `web-transfer-${transferRow.value.dispatchNo}-${Date.now()}`,
+      plannedDeliveryAt: transferForm.plannedDeliveryAt,
+      deliveryMethod: transferForm.deliveryMethod,
+      waybillNo: transferForm.waybillNo.trim() || undefined,
+      carrierName: transferForm.carrierName.trim() || undefined,
+      pickupMethod: transferForm.pickupMethod,
+      loadingType: transferForm.loadingType,
+      vehicleType: transferForm.vehicleType || undefined,
+      vehicleSize: transferForm.vehicleSize || undefined,
+      driverName: transferForm.driverName.trim() || undefined,
+      driverPhone: transferForm.driverPhone.trim() || undefined,
+      vehiclePlate: transferForm.vehiclePlate.trim() || undefined,
+      appointmentAccount: transferForm.appointmentAccount || undefined,
+      sellerName: isBuyAppointment.value ? transferForm.sellerName.trim() : undefined,
+      remark: transferForm.remark.trim() || undefined,
+      fees,
+    })
+    transferOpen.value = false
+    ElMessage.success('已生成出库单和派送单')
+    await load()
+  } catch (cause) {
+    mutationError.value = getApiErrorDetails(cause, '转派送失败，请重试')
+  } finally {
+    transferSaving.value = false
+  }
+}
+
+onMounted(load)
+</script>
+
+<template>
+  <AdminPage class="admin-density"><ListPageLayout aria-label="海外仓排车列表">
+    <OperationErrorToast :details="mutationError" />
+    <template #toolbar><QueryToolbar v-model="filters" class="surface-panel" :fields="fields" :loading="loading" ariaLabel="排车列表筛选" preference-key="overseas-dispatches-query" :search-on-reset="false" @search="search" @reset="reset" /></template>
+    <template v-if="loadError" #state><LoadErrorState title="排车列表加载失败" :message="loadError.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="loadError" /></template></LoadErrorState></template>
+    <section v-if="!loadError" class="surface-panel table-panel"><DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :loading="loading" :total="total" preference-key="overseas-dispatches" row-key="id" empty-text="暂无排车记录" @update:page="load()" @update:page-size="page = 1; load()">
+       <template #actions="{ row }"><div class="density-actions"><el-button class="density-action" data-tone="neutral" size="small" @click="openDetail(row as DispatchListItem)">查看</el-button><el-button class="density-action" data-tone="neutral" size="small" :loading="bolLoadingNo === (row as DispatchListItem).dispatchNo" @click="openBol(row as DispatchListItem)">打印BOL</el-button><el-button class="density-action" data-tone="neutral" v-if="canEdit(row as DispatchListItem)" size="small" @click="handleMore('edit', row as DispatchListItem)">编辑</el-button><el-button class="density-action" data-tone="success" v-if="canTransfer(row as DispatchListItem) && !canEdit(row as DispatchListItem)" size="small" @click="openTransfer(row as DispatchListItem)">转派送</el-button><el-button class="density-action" data-tone="danger" v-if="canCancel(row as DispatchListItem) && rowActionCount(row as DispatchListItem) <= 3" size="small" @click="handleMore('cancel', row as DispatchListItem)">取消</el-button><el-dropdown v-if="rowActionCount(row as DispatchListItem) > 3" trigger="click" @command="handleMore(String($event), row as DispatchListItem)"><el-button class="density-action" :aria-label="`更多操作 · ${row.orderNo || row.dispatchNo || '当前记录'}`" title="更多操作" data-tone="neutral" size="small" ><MoreHorizontal aria-hidden="true" :size="15" /></el-button><template #dropdown><el-dropdown-menu><el-dropdown-item v-if="canTransfer(row as DispatchListItem) && canEdit(row as DispatchListItem)" @click="openTransfer(row as DispatchListItem)">转派送</el-dropdown-item><el-dropdown-item v-if="canCancel(row as DispatchListItem)" command="cancel" divided>取消</el-dropdown-item></el-dropdown-menu></template></el-dropdown></div></template>
+      <template #status="{ row }"><StatusBadge :status="String((row as DispatchListItem).status || '—')" /></template>
+      <template #pagination-left>共 {{ total }} 条排车记录</template>
+    </DataTable></section>
+  </ListPageLayout></AdminPage><AppDialog class="admin-density-dialog" v-model="transferOpen" title="转派送" width="min(1120px, calc(100vw - 28px))" confirm-text="确认提交" :confirm-loading="transferSaving" @confirm="submitTransfer"><el-form class="density-form" label-position="top"><h3>派送信息</h3><div class="transfer-grid"><el-form-item label="排车单号"><el-input :model-value="transferRow?.dispatchNo" readonly /></el-form-item><el-form-item label="预计派送时间" required><el-date-picker v-model="transferForm.plannedDeliveryAt" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" placeholder="请选择预计派送时间" /></el-form-item><el-form-item label="派送方式" required><el-select v-model="transferForm.deliveryMethod" placeholder="请选择"><el-option v-for="option in deliveryMethodOptions" :key="option.value" v-bind="option" /></el-select></el-form-item><el-form-item label="快递/车队"><el-input v-model="transferForm.carrierName" placeholder="请输入快递或车队名称" /></el-form-item><el-form-item label="运单号"><el-input v-model="transferForm.waybillNo" placeholder="请输入运单号" /></el-form-item><el-form-item label="提货方式" required><el-select v-model="transferForm.pickupMethod" placeholder="请选择"><el-option v-for="option in pickupMethodOptions" :key="option.value" v-bind="option" /></el-select></el-form-item><el-form-item label="装车类型" required><el-select v-model="transferForm.loadingType" placeholder="请选择"><el-option v-for="option in loadingTypeOptions" :key="option.value" v-bind="option" /></el-select></el-form-item><el-form-item label="司机/车队名称"><el-input v-model="transferForm.driverName" placeholder="请输入司机或车队名称" /></el-form-item><el-form-item label="联系电话"><el-input v-model="transferForm.driverPhone" placeholder="请输入联系电话" /></el-form-item><el-form-item label="车牌号"><el-input v-model="transferForm.vehiclePlate" placeholder="请输入车牌号" /></el-form-item><el-form-item label="车辆类型"><el-select v-model="transferForm.vehicleType" clearable placeholder="请选择"><el-option v-for="option in vehicleTypeOptions" :key="option.value" v-bind="option" /></el-select></el-form-item><el-form-item label="车辆大小"><el-select v-model="transferForm.vehicleSize" clearable placeholder="请选择"><el-option v-for="option in vehicleSizeOptions" :key="option.value" v-bind="option" /></el-select></el-form-item><el-form-item label="预约账号"><el-select v-model="transferForm.appointmentAccount" clearable placeholder="请选择"><el-option v-for="option in appointmentAccountOptions" :key="option.value" v-bind="option" /></el-select></el-form-item><el-form-item v-if="isBuyAppointment" label="卖家姓名" required><el-input v-model="transferForm.sellerName" placeholder="请输入卖家姓名" /></el-form-item></div><h3>费用信息（USD）</h3><div class="transfer-grid"><el-form-item label="派送费用" required><el-input-number v-model="transferForm.deliveryFee" :min="0" :precision="2" controls-position="right" placeholder="请输入派送费用" /></el-form-item><el-form-item v-if="needsLoadingFee" label="装车费" required><el-input-number v-model="transferForm.loadingFee" :min="0" :precision="2" controls-position="right" placeholder="请输入装车费" /></el-form-item><el-form-item v-if="isBuyAppointment" label="买约费用" required><el-input-number v-model="transferForm.appointmentFee" :min="0" :precision="2" controls-position="right" placeholder="请输入买约费用" /></el-form-item></div><el-form-item label="备注"><el-input v-model="transferForm.remark" type="textarea" :rows="3" placeholder="请输入派送备注（选填）" /></el-form-item><el-alert title="费用不会自动带出，请手工填写后提交；提交后将生成待出库单、待派送单，并保存费用明细" type="info" :closable="false" /></el-form></AppDialog>
+  <AppDialog class="admin-density-dialog" v-model="editOpen" title="编辑排车" width="min(900px, calc(100vw - 48px))" confirm-text="保存" :confirm-loading="editSaving" @confirm="submitEdit"><el-alert :title="`当前状态：${editRow?.status || '—'}；普通编辑不会修改排车状态；未生成出库单前可移除托盘。`" type="info" :closable="false" /><el-form class="density-form" label-position="top"><div class="edit-grid"><el-form-item label="车牌号"><el-input v-model="editForm.vehiclePlate" placeholder="请输入车牌号" /></el-form-item><el-form-item label="司机"><el-input v-model="editForm.driverName" placeholder="请输入司机姓名" /></el-form-item><el-form-item label="联系电话"><el-input v-model="editForm.driverPhone" placeholder="请输入联系电话" /></el-form-item><el-form-item label="拖车公司名称"><el-input v-model="editForm.carrierName" placeholder="请输入拖车公司名称" /></el-form-item><el-form-item label="路线"><el-input v-model="editForm.route" readonly placeholder="按已排托盘自动汇总 FBA 仓" /></el-form-item><el-form-item label="发车时间"><el-date-picker v-model="editForm.departAt" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" /></el-form-item><el-form-item label="预计到达时间"><el-date-picker v-model="editForm.estimatedArrivalAt" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" /></el-form-item><el-form-item label="FBA预约号"><el-input v-model="editForm.fbaAppointmentNo" placeholder="请输入 FBA 预约号" /></el-form-item><el-form-item label="FBA预约状态"><el-select v-model="editForm.fbaAppointmentStatus" clearable><el-option label="待预约" value="PENDING" /><el-option label="已预约" value="BOOKED" /><el-option label="已确认" value="CONFIRMED" /><el-option label="已取消" value="CANCELLED" /></el-select></el-form-item><el-form-item label="车辆预约状态"><el-select v-model="editForm.vehicleAppointmentStatus" clearable><el-option label="待预约" value="PENDING" /><el-option label="已预约" value="BOOKED" /><el-option label="已确认" value="CONFIRMED" /><el-option label="已取消" value="CANCELLED" /></el-select></el-form-item></div></el-form><h3>已排车托盘</h3><el-table :data="editItems" border max-height="280" empty-text="暂无托盘"><el-table-column label="操作" width="90" fixed="left"><template #default="{ row }"><el-button class="density-action" data-tone="danger" :loading="removingItemId === String(row.id)" :disabled="Boolean(removingItemId)" @click="removePallet(row)">移除</el-button></template></el-table-column><el-table-column prop="palletNo" label="托盘号" min-width="160" /><el-table-column prop="orderNo" label="订单号" min-width="160" /><el-table-column prop="inboundCode" label="入仓码" min-width="140" /><el-table-column prop="packageCount" label="箱数" width="80" align="right" /></el-table></AppDialog>
+</template>
+<style scoped>
+.transfer-grid,
+.edit-grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 0 var(--admin-space-5);
+}
+.transfer-grid :deep(.el-select),
+.transfer-grid :deep(.el-date-editor),
+.transfer-grid :deep(.el-input-number),
+.edit-grid :deep(.el-select),
+.edit-grid :deep(.el-date-editor) {
+  width: 100%;
+}
+h3 {
+  margin: var(--admin-space-1) 0 var(--admin-space-5);
+}
+@media (max-width: 900px) {
+  .transfer-grid,
+  .edit-grid {
+    grid-template-columns: 1fr;
+  }
+}
+</style>
diff --git a/src/modules/overseas-warehouse/pages/ExceptionOrdersView.test.ts b/src/modules/overseas-warehouse/pages/ExceptionOrdersView.test.ts
new file mode 100644
index 00000000..ee6fd783
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/ExceptionOrdersView.test.ts
@@ -0,0 +1,81 @@
+import ElementPlus from 'element-plus'
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { createExceptionOrder, listExceptionOrders, resolveExceptionRelation } from '../api/exceptionOrders'
+import ExceptionOrdersView from './ExceptionOrdersView.vue'
+import { commonPhase5Stubs } from './phase5TestStubs'
+
+const canPermission = vi.hoisted(() => vi.fn((_code: string) => false))
+vi.mock('@/core/access/accessPreview', () => ({ useAccessPreviewStore: () => ({ can: canPermission }) }))
+vi.mock('../api/exceptionOrders', () => ({ listExceptionOrders: vi.fn(), resolveExceptionRelation: vi.fn(), createExceptionOrder: vi.fn() }))
+
+function mountView() { return mount(ExceptionOrdersView, { global: { plugins: [ElementPlus], stubs: commonPhase5Stubs } }) }
+
+describe('ExceptionOrdersView permissions and creation', () => {
+  beforeEach(() => {
+    canPermission.mockReset().mockReturnValue(false)
+    vi.mocked(listExceptionOrders).mockReset().mockResolvedValue({ records: [], page: 1, size: 10, total: 0, pages: 0 })
+    vi.mocked(resolveExceptionRelation).mockReset().mockResolvedValue({ inboundOrderId: '9', inboundCode: 'IN-1', lastMileOrderId: '8', lastMileOrderNo: 'LM-1', customerId: '100' })
+    vi.mocked(createExceptionOrder).mockReset().mockResolvedValue({ id: '19', exceptionNo: 'EXC-1', status: 'PENDING' })
+  })
+
+  it('hides creation without the independent permission', async () => {
+    const wrapper = mountView()
+    await flushPromises()
+    expect(wrapper.find('[data-testid="data-table"]').text()).not.toContain('新增异常订单')
+    wrapper.unmount()
+  })
+
+  it('keeps the detail action available and hides numeric operator identifiers', async () => {
+    vi.mocked(listExceptionOrders).mockResolvedValue({
+      records: [{
+        id: '19', exceptionNo: 'EXC-1', exceptionType: 'DAMAGED', status: 'PROCESSING', reason: '包装破损',
+        customerId: '100', customerName: '示例客户', overseasWarehouseName: '洛杉矶仓', handlerName: '1000001',
+        exceptionAt: '2026-09-03T09:00:00', updatedAt: '2026-09-03T10:00:00',
+      }],
+      page: 1, size: 10, total: 1, pages: 1,
+    })
+    const wrapper = mountView()
+    await flushPromises()
+    const table = wrapper.find('[data-testid="data-table"]')
+    expect(table.text()).toContain('查看')
+    await table.find('button').trigger('click')
+    await flushPromises()
+    const detail = wrapper.find('[data-dialog="异常订单详情"]')
+    expect(detail.text()).toContain('示例客户')
+    expect(detail.text()).toContain('包装破损')
+    expect(detail.text()).not.toContain('1000001')
+    wrapper.unmount()
+  })
+
+  it('validates the required relation before submitting', async () => {
+    canPermission.mockImplementation(code => code.endsWith(':create'))
+    const wrapper = mountView()
+    await flushPromises()
+    await wrapper.findAll('button').find(button => button.text().includes('新增异常订单'))!.trigger('click')
+    await wrapper.find('[data-dialog="新增异常订单"] .dialog-confirm').trigger('click')
+    await flushPromises()
+    expect(resolveExceptionRelation).not.toHaveBeenCalled()
+    expect(createExceptionOrder).not.toHaveBeenCalled()
+    wrapper.unmount()
+  })
+
+  it('resolves and submits trimmed business fields', async () => {
+    canPermission.mockImplementation(code => code.endsWith(':create'))
+    const wrapper = mountView()
+    await flushPromises()
+    await wrapper.findAll('button').find(button => button.text().includes('新增异常订单'))!.trigger('click')
+    const dialog = wrapper.find('[data-dialog="新增异常订单"]')
+    await dialog.find('input[placeholder="请输入入仓码"]').setValue(' IN-1 ')
+    await dialog.find('select').setValue('RETURN')
+    await dialog.find('textarea').setValue(' 包裹破损 ')
+    await dialog.find('.dialog-confirm').trigger('click')
+    await flushPromises()
+    expect(resolveExceptionRelation).toHaveBeenCalledWith({ customerId: undefined, inboundCode: 'IN-1', lastMileOrderNo: undefined })
+    expect(createExceptionOrder).toHaveBeenCalledWith({
+      customerId: undefined, inboundCode: 'IN-1', lastMileOrderNo: 'LM-1',
+      exceptionType: 'RETURN', reason: '包裹破损', packageCount: undefined, skuCode: undefined,
+    })
+    wrapper.unmount()
+  })
+})
diff --git a/src/modules/overseas-warehouse/pages/ExceptionOrdersView.vue b/src/modules/overseas-warehouse/pages/ExceptionOrdersView.vue
new file mode 100644
index 00000000..3575e486
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/ExceptionOrdersView.vue
@@ -0,0 +1,125 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { onMounted, reactive, ref } from 'vue'
+import { Plus } from '@lucide/vue'
+import { ElMessage } from 'element-plus'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { formatOverseasDateTime } from '../lastMilePresentation'
+import { overseasWarehousePermissions as permission } from '../permissions'
+import { createExceptionOrder, listExceptionOrders, resolveExceptionRelation, type ExceptionOrderRow, type ExceptionRelation } from '../api/exceptionOrders'
+import OrderReferenceText from '../components/OrderReferenceText.vue'
+
+const rows = ref<ExceptionOrderRow[]>([]); const page = ref(1); const pageSize = ref(10); const total = ref(0); const loading = ref(false); const error = ref<ApiErrorDetails | null>(null)
+const access = useAccessPreviewStore()
+const filters = ref<QueryModel>({ keyword: '', exceptionType: '', status: '' })
+const fields: QueryField[] = [
+  { key: 'keyword', type: 'input', label: '关键词', placeholder: '异常单号 / 关联单号 / 客户 / 原因' },
+  { key: 'exceptionType', type: 'select', label: '异常类型', placeholder: '全部类型', options: [{ label: '退货', value: 'RETURN' }, { label: '拒收', value: 'REJECT' }, { label: '破损', value: 'DAMAGED' }, { label: '其他', value: 'OTHER' }] },
+  { key: 'status', type: 'select', label: '处理状态', placeholder: '全部状态', options: [{ label: '待处理', value: 'PENDING' }, { label: '处理中', value: 'PROCESSING' }, { label: '已完成', value: 'COMPLETED' }] },
+]
+const columns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 100, fixed: 'left', slotName: 'actions' },
+  { key: 'exceptionNo', prop: 'exceptionNo', label: '异常订单号', minWidth: 180, fixed: 'left' },
+  { key: 'related', label: '关联订单号', minWidth: 230, slotName: 'related' },
+  { key: 'exceptionType', label: '异常类型', width: 100, formatter: (row: ExceptionOrderRow) => typeLabels[row.exceptionType] || row.exceptionType },
+  { key: 'customerName', prop: 'customerName', label: '客户', minWidth: 160 },
+  { key: 'overseasWarehouseName', prop: 'overseasWarehouseName', label: '仓库', minWidth: 140 },
+  { key: 'reason', prop: 'reason', label: '异常原因', minWidth: 200 },
+  { key: 'skuCode', prop: 'skuCode', label: 'SKU', minWidth: 120 },
+  { key: 'packageCount', prop: 'packageCount', label: '箱数', width: 80 },
+  { key: 'exceptionAt', label: '异常时间', minWidth: 170, formatter: (row: ExceptionOrderRow) => formatOverseasDateTime(row.exceptionAt) },
+  { key: 'status', label: '处理状态', width: 100, slotName: 'status' },
+  { key: 'handlingAction', prop: 'handlingAction', label: '处理动作', minWidth: 140 },
+  { key: 'returnLogisticsNo', prop: 'returnLogisticsNo', label: '退回物流单号', minWidth: 160 },
+  { key: 'handlerName', prop: 'handlerName', label: '处理人', minWidth: 110, slotName: 'handlerName' },
+  { key: 'updatedAt', label: '更新时间', minWidth: 170, formatter: (row: ExceptionOrderRow) => formatOverseasDateTime(row.updatedAt) },
+]
+const typeLabels: Record<string, string> = { RETURN: '退货', REJECT: '拒收', DAMAGED: '破损', OTHER: '其他' }
+const statusLabels: Record<string, string> = { PENDING: '待处理', PROCESSING: '处理中', COMPLETED: '已完成' }
+const detailOpen = ref(false); const detailRow = ref<ExceptionOrderRow | null>(null)
+function openDetail(row: ExceptionOrderRow) { detailRow.value = row; detailOpen.value = true }
+function displayHandler(value: unknown) {
+  const normalized = String(value ?? '').trim()
+  return normalized && !/^\d+$/.test(normalized) ? normalized : '—'
+}
+
+const createOpen = ref(false); const saving = ref(false); const resolving = ref(false); const relation = ref<ExceptionRelation | null>(null); const relationError = ref('')
+const form = reactive({ customerId: '', inboundCode: '', lastMileOrderNo: '', exceptionType: '', reason: '', packageCount: undefined as number | undefined, skuCode: '' })
+function openCreate() { Object.assign(form, { customerId: '', inboundCode: '', lastMileOrderNo: '', exceptionType: '', reason: '', packageCount: undefined, skuCode: '' }); relation.value = null; relationError.value = ''; createOpen.value = true }
+async function resolveRelation() {
+  if (!form.inboundCode.trim() && !form.lastMileOrderNo.trim()) { relation.value = null; relationError.value = '入仓码和尾程订单号至少填写一个'; return }
+  resolving.value = true; relationError.value = ''
+  try { relation.value = await resolveExceptionRelation({ customerId: form.customerId.trim() || undefined, inboundCode: form.inboundCode.trim() || undefined, lastMileOrderNo: form.lastMileOrderNo.trim() || undefined }); if (!form.inboundCode && relation.value.inboundCode) form.inboundCode = relation.value.inboundCode; if (!form.lastMileOrderNo && relation.value.lastMileOrderNo) form.lastMileOrderNo = relation.value.lastMileOrderNo }
+  catch (cause) { relation.value = null; relationError.value = getApiErrorDetails(cause, '关联单据校验失败').message }
+  finally { resolving.value = false }
+}
+async function submit() {
+  await resolveRelation(); if (!relation.value) return
+  if (!form.exceptionType || !form.reason.trim()) { ElMessage.warning('请选择异常类型并填写异常原因'); return }
+  saving.value = true
+  try { const result = await createExceptionOrder({ customerId: form.customerId.trim() || undefined, inboundCode: form.inboundCode.trim() || undefined, lastMileOrderNo: form.lastMileOrderNo.trim() || undefined, exceptionType: form.exceptionType, reason: form.reason.trim(), packageCount: form.packageCount, skuCode: form.skuCode.trim() || undefined }); createOpen.value = false; ElMessage.success(`异常单 ${result.exceptionNo} 创建成功`); page.value = 1; await load() }
+  catch (cause) { ElMessage.error(getApiErrorDetails(cause, '新增异常订单失败').message) } finally { saving.value = false }
+}
+async function load(model: QueryModel = filters.value) { Object.assign(filters.value, model); loading.value = true; error.value = null; try { const result = await listExceptionOrders({ page: page.value, size: pageSize.value, keyword: text('keyword'), exceptionType: text('exceptionType'), status: text('status') }); rows.value = result.records; total.value = result.total } catch (cause) { rows.value = []; total.value = 0; error.value = getApiErrorDetails(cause, '异常订单列表加载失败') } finally { loading.value = false } }
+function text(key: string) { return String(filters.value[key] || '').trim() || undefined }
+function search(model: QueryModel) { page.value = 1; void load(model) }
+function reset(model: QueryModel) { page.value = 1; void load(model) }
+onMounted(load)
+</script>
+
+<template>
+  <AdminPage class="admin-density"><ListPageLayout aria-label="异常订单列表">
+    <template #toolbar><QueryToolbar v-model="filters" class="surface-panel" :fields="fields" :loading="loading" ariaLabel="异常订单筛选" preference-key="overseas-exception-orders-query" :search-on-reset="false" @search="search" @reset="reset" /></template>
+    <template v-if="error" #state><LoadErrorState title="异常订单列表加载失败" :message="error.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="error" /></template></LoadErrorState></template>
+    <section v-if="!error" class="surface-panel table-panel"><DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :loading="loading" :total="total" preference-key="overseas-exception-orders" row-key="id" empty-text="暂无异常订单" @update:page="load()" @update:page-size="page = 1; load()">
+      <template #toolbar-actions><el-button v-if="access.can(permission.exceptionOrderCreate)" type="primary" @click="openCreate"><Plus :size="16" />新增异常订单</el-button></template>
+      <template #actions="{ row }"><el-button class="density-action" data-tone="neutral" size="small" @click="openDetail(row as ExceptionOrderRow)">查看</el-button></template>
+      <template #related="{ row }"><div class="related-orders"><span v-if="row.lastMileOrderNo" class="related-order-reference">尾程 <OrderReferenceText :value="String(row.lastMileOrderNo)" /></span><span v-if="row.deliveryNo">派送 {{ row.deliveryNo }}</span><span v-if="row.inboundCode">入仓 {{ row.inboundCode }}</span><span v-if="row.outboundNo">出库 {{ row.outboundNo }}</span></div></template>
+      <template #handlerName="{ row }">{{ displayHandler(row.handlerName) }}</template>
+      <template #status="{ row }"><StatusBadge :status="statusLabels[String(row.status)] || String(row.status)" /></template><template #pagination-left>共 {{ total }} 条异常订单</template>
+    </DataTable></section>
+  </ListPageLayout></AdminPage>
+  <AppDialog class="admin-density-dialog" v-model="createOpen" title="新增异常订单" width="min(760px, calc(100vw - 28px))" confirm-text="保存" :confirm-loading="saving" :loading="resolving" @confirm="submit">
+    <el-alert title="入仓码和尾程订单号至少填写一个；两项都填写时必须属于同一订单。" type="warning" :closable="false" />
+    <el-form label-position="top" class="create-form density-form"><div class="form-grid">
+      <el-form-item label="入仓码"><el-input v-model="form.inboundCode" placeholder="请输入入仓码" @blur="resolveRelation" /></el-form-item>
+      <el-form-item label="尾程订单号"><el-input v-model="form.lastMileOrderNo" placeholder="请输入尾程订单号" @blur="resolveRelation" /></el-form-item>
+      <el-form-item label="异常类型" required><el-select v-model="form.exceptionType" placeholder="请选择异常类型"><el-option v-for="(label, value) in typeLabels" :key="value" :label="label" :value="value" /></el-select></el-form-item>
+      <el-form-item label="处理状态"><el-input model-value="待处理" readonly /></el-form-item>
+      <el-form-item label="箱数"><el-input-number v-model="form.packageCount" :min="1" :max="relation?.availablePackages || 999999" placeholder="请输入箱数" /></el-form-item>
+      <el-form-item label="SKU（可自由填写）"><el-input v-model="form.skuCode" maxlength="128" placeholder="请输入 SKU（选填）" /></el-form-item>
+    </div><el-form-item label="异常原因" required><el-input v-model="form.reason" type="textarea" :rows="4" maxlength="1000" show-word-limit placeholder="请输入异常原因" /></el-form-item>
+    <el-alert v-if="relation" type="success" :closable="false"><template #title><span class="relation-alert-title">已关联：<OrderReferenceText :value="relation.lastMileOrderNo || '无尾程单'" /> / {{ relation.inboundCode || '无入仓单' }}，客户 {{ relation.customerName || '客户信息待补充' }}</span></template></el-alert>
+    <el-alert v-else-if="relationError" :title="relationError" type="error" :closable="false" />
+    </el-form>
+  </AppDialog>
+  <AppDialog class="admin-density-dialog" v-model="detailOpen" title="异常订单详情" width="min(760px, calc(100vw - 28px))" :show-confirm="false" cancel-text="关闭">
+    <el-descriptions class="density-descriptions" v-if="detailRow" :column="2" border>
+      <el-descriptions-item label="异常订单号">{{ detailRow.exceptionNo }}</el-descriptions-item>
+      <el-descriptions-item label="处理状态">{{ statusLabels[String(detailRow.status)] || detailRow.status }}</el-descriptions-item>
+      <el-descriptions-item label="异常类型">{{ typeLabels[detailRow.exceptionType] || detailRow.exceptionType }}</el-descriptions-item>
+      <el-descriptions-item label="客户">{{ detailRow.customerName || '—' }}</el-descriptions-item>
+      <el-descriptions-item label="海外仓">{{ detailRow.overseasWarehouseName || '—' }}</el-descriptions-item>
+      <el-descriptions-item label="处理人">{{ displayHandler(detailRow.handlerName) }}</el-descriptions-item>
+      <el-descriptions-item label="异常时间">{{ formatOverseasDateTime(detailRow.exceptionAt) }}</el-descriptions-item>
+      <el-descriptions-item label="更新时间">{{ formatOverseasDateTime(detailRow.updatedAt) }}</el-descriptions-item>
+      <el-descriptions-item label="异常原因" :span="2">{{ detailRow.reason || '—' }}</el-descriptions-item>
+      <el-descriptions-item label="处理动作" :span="2">{{ detailRow.handlingAction || '—' }}</el-descriptions-item>
+    </el-descriptions>
+  </AppDialog>
+</template>
+
+<style scoped>
+.related-orders { display: grid; gap: var(--admin-space-1); font-size: var(--admin-font-caption); }.related-order-reference,.relation-alert-title { display: flex; min-width: 0; align-items: baseline; gap: 3px; }.create-form { margin-top: var(--admin-space-5); }.form-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 0 var(--admin-space-5); }
+@media (max-width: 720px) { .form-grid { grid-template-columns: 1fr; } }
+.form-grid :deep(.el-input-number), .form-grid :deep(.el-select) { width: 100%; }
+</style>
diff --git a/src/modules/overseas-warehouse/pages/InboundOrderDetailView.vue b/src/modules/overseas-warehouse/pages/InboundOrderDetailView.vue
new file mode 100644
index 00000000..f81e7cd0
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/InboundOrderDetailView.vue
@@ -0,0 +1,76 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, ref } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { getInboundPlan, type InboundPlanDetailDto } from '../api/inboundPlans'
+import OverseasDetailShell from '../components/OverseasDetailShell.vue'
+import { formatOverseasDateTime, lastMileOrderTypeLabel } from '../lastMilePresentation'
+
+const route = useRoute(); const router = useRouter()
+const planNo = computed(() => String(route.params.orderId || ''))
+const customerId = computed(() => String(route.query.customerId || ''))
+const detail = ref<InboundPlanDetailDto | null>(null); const loading = ref(false); const loadError = ref<ApiErrorDetails | null>(null)
+const referenceValue = computed(() => detail.value?.planNo || (/^\d+$/.test(planNo.value) ? '—' : planNo.value))
+function text(value: unknown) { return String(value ?? '').trim() || '—' }
+function receivingWarehouse(code: unknown, name: unknown) {
+  const normalizedCode = String(code ?? '').trim()
+  const normalizedName = String(name ?? '').trim()
+  return normalizedCode && normalizedName ? `${normalizedCode} · ${normalizedName}` : '—'
+}
+function status(value: unknown) { const labels: Record<string, string> = { PENDING_ASSIGNMENT: '待入库', PDA_PENDING: '待入库', ASSIGNED: '待入库', PICKING: '拣货中', PARTIAL_INBOUND: '部分入库', COMPLETED: '全部入库' }; return labels[String(value || '')] || text(value) }
+const firstLine = computed(() => detail.value?.lines[0])
+const fieldValues = computed<Record<string, string | number>>(() => ({
+  入库单号: text(detail.value?.planNo), 入仓码: text(firstLine.value?.inboundCode), 类型: lastMileOrderTypeLabel(detail.value?.orderType), 货主: text(detail.value?.customerName), 关联订单: text(detail.value?.sourceOrderNo),
+  海外仓: receivingWarehouse(detail.value?.overseasWarehouseCode, detail.value?.overseasWarehouseName), FBA仓库: text(firstLine.value?.fbaWarehouseCode), 总箱数: detail.value?.expectedPackageCount ?? detail.value?.lines.reduce((sum, line) => sum + line.requiredPackageCount, 0) ?? 0,
+  应拣货数: detail.value?.expectedPackageCount ?? detail.value?.lines.reduce((sum, line) => sum + line.requiredPackageCount, 0) ?? 0, 实际拣货数: detail.value?.pickedPackageCount ?? detail.value?.allocations.reduce((sum, item) => sum + item.pickedPackageCount, 0) ?? 0,
+  '计费体积(m³)': Number(detail.value?.totalVolumeCbm || 0), 总托盘数: Number(detail.value?.palletCount || 0), 状态: status(detail.value?.status),
+  预约状态: '—', 预约送仓时间: '—', 预计装车时间: '—', 排车状态: '—', 创建时间: formatOverseasDateTime(detail.value?.createdAt), 更新时间: formatOverseasDateTime(detail.value?.updatedAt), 备注: text(detail.value?.remark),
+}))
+const groups = [
+  { title: '单据信息', fields: ['入库单号', '入仓码', '类型', '货主', '关联订单'] },
+  { title: '仓储信息', fields: ['海外仓', 'FBA仓库', '总箱数', '应拣货数', '实际拣货数', '计费体积(m³)', '总托盘数'] },
+  { title: '预约与排车', fields: ['状态', '预约状态', '预约送仓时间', '预计装车时间', '排车状态', '创建时间', '更新时间', '备注'] },
+]
+const feeColumns: DataTableColumn[] = [{ key: 'index', label: '序号', width: 70, align: 'center' }, { key: 'name', label: '费用项目', minWidth: 180 }, { key: 'currency', label: '币种', width: 100 }, { key: 'amount', label: '金额', width: 140, align: 'right' }, { key: 'remark', label: '备注', minWidth: 200 }]
+const palletColumns: DataTableColumn[] = [
+  { key: 'inboundCode', prop: 'inboundCode', label: '入仓码', minWidth: 150 },
+  { key: 'palletNo', prop: 'palletNo', label: '托盘号', minWidth: 150 },
+  { key: 'palletOwner', prop: 'palletOwner', label: '托盘所属计划', minWidth: 190 },
+  { key: 'packageCount', prop: 'packageCount', label: '对应箱数', width: 110, align: 'right' },
+]
+const palletRows = computed(() => (detail.value?.allocations || []).map((allocation, index) => {
+  const line = detail.value?.lines.find(item => item.id === allocation.lineId)
+  return {
+    id: `${allocation.lineId}-${allocation.palletId}-${index}`,
+    inboundCode: text(line?.inboundCode),
+    palletNo: text(allocation.palletNo),
+    palletOwner: allocation.palletOwnedByCurrentPlan ? `${allocation.palletOwnerPlanNo}（本计划）` : `${allocation.palletOwnerPlanNo}（跨计划合托）`,
+    packageCount: Number(allocation.pickedPackageCount ?? allocation.countedPackageCount ?? allocation.plannedPackageCount ?? 0),
+  }
+}))
+async function load() { if (!planNo.value || !customerId.value) { loadError.value = { message: '详情缺少客户范围，请从入库单列表重新进入' }; return }; loading.value = true; loadError.value = null; try { detail.value = await getInboundPlan(planNo.value, customerId.value) } catch (error) { loadError.value = getApiErrorDetails(error, '入库单详情加载失败，请重试') } finally { loading.value = false } }
+function back() { void router.push({ name: 'overseas-inbound-orders' }) }
+onMounted(load)
+</script>
+
+<template><OverseasDetailShell class="admin-density" dense title="入库单详情" reference-label="入库单号" :reference-value="referenceValue" back-label="返回入库单" domain="入库单详情" :pending="false" :status-text="detail ? status(detail.status) : '加载中'" @back="back">
+  <LoadErrorState v-if="loadError" title="入库单详情加载失败" :message="loadError.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="loadError" /></template></LoadErrorState>
+  <template v-else><section v-loading="loading" class="detail-section" aria-label="入库单基本信息"><div class="detail-groups"><section v-for="group in groups" :key="group.title" class="detail-group" :aria-label="group.title"><h2>{{ group.title }}</h2><dl class="detail-fields density-fields"><div v-for="label in group.fields" :key="label"><dt>{{ label }}</dt><dd>{{ fieldValues[label] }}</dd></div></dl></section></div></section>
+  <section class="detail-section pallet-section" aria-labelledby="inbound-pallet-heading"><h2 id="inbound-pallet-heading">入库单托盘明细</h2><p class="pallet-note">PDA 合托后，参与合托的入库单会分别展示同一托盘及本单对应箱数。</p><DataTable :data="palletRows" :columns="palletColumns" column-settings-mode="hide" row-key="id" empty-text="暂无托盘明细" /></section>
+  <section class="detail-section fee-section" aria-labelledby="inbound-fees-heading"><h2 id="inbound-fees-heading">应收费用明细</h2><DataTable :data="[]" :columns="feeColumns" column-settings-mode="hide" empty-text="当前入库计划详情接口未提供应收费用" /><footer class="fee-total"><span>应收费用合计（USD）</span><strong>—</strong></footer></section></template>
+</OverseasDetailShell></template>
+
+<style scoped>
+.detail-group:nth-child(2) { border-right: 0; }.detail-group:last-child { grid-column: 1 / -1; border-right: 0; border-bottom: 0; }.detail-group h2,.fee-section h2 { margin: 0 0 var(--admin-space-5); color: var(--cc-text); font-size: var(--admin-font-section); }.fee-section { overflow:hidden; padding-top:var(--admin-space-5); }.fee-section h2 { margin-right:var(--admin-space-5); margin-left:var(--admin-space-5); }.fee-total { display:flex; min-height:48px; align-items:center; justify-content:flex-end; gap:40px; padding:var(--admin-space-4) var(--admin-space-5); border-top:1px solid var(--cc-border); }.fee-total strong { min-width:120px; font-size:var(--admin-font-section); }
+.pallet-section { overflow: hidden; padding-top: var(--admin-space-5); }.pallet-section h2 { margin: 0 var(--admin-space-5) var(--admin-space-1); color: var(--cc-text); font-size: var(--admin-font-section); }.pallet-note { margin: 0 var(--admin-space-5) var(--admin-space-5); color: var(--cc-muted); font-size: var(--admin-font-caption); }
+@media(max-width:1200px){.detail-groups,.detail-fields,.detail-group:last-child .detail-fields{grid-template-columns:1fr}.detail-group:last-child{grid-column:auto}.detail-group{border-right:0}}
+
+.detail-section { min-width: 0; border: 0; background: #fff; }
+.detail-groups { display: grid; grid-template-columns: minmax(0, 1fr); }
+.detail-group { min-width: 0; padding: var(--admin-space-5) var(--admin-space-5) var(--admin-space-5); border-right: 0; border-bottom: 1px solid var(--cc-border); }
+
+</style>
diff --git a/src/modules/overseas-warehouse/pages/InboundOrdersView.vue b/src/modules/overseas-warehouse/pages/InboundOrdersView.vue
new file mode 100644
index 00000000..517c6da4
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/InboundOrdersView.vue
@@ -0,0 +1,224 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, reactive, ref } from 'vue'
+import { CalendarCheck2, Truck } from '@lucide/vue'
+import { ElMessage } from 'element-plus'
+import { useRouter } from 'vue-router'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import OperationErrorToast from '@/shared/components/OperationErrorToast.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import SmartDispatchDialog from '../components/SmartDispatchDialog.vue'
+import { createFbaAppointment, getFbaAppointment, listInboundOrders, updateFbaAppointment, updateInboundPlan, type InboundOrderSummaryDto } from '../api/inboundOrders'
+import { listReceivingOverseasWarehouses, type ReceivingOverseasWarehouseDto } from '../api/pallets'
+import { overseasWarehousePermissions as permission } from '../permissions'
+import { formatOverseasDateTime, lastMileOrderTypeLabel } from '../lastMilePresentation'
+import type { InboundOrderListItem } from '../types'
+
+const access = useAccessPreviewStore()
+const router = useRouter()
+const rows = ref<InboundOrderListItem[]>([])
+const selectedRows = ref<InboundOrderListItem[]>([])
+const loading = ref(false)
+const saving = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const mutationError = ref<ApiErrorDetails | null>(null)
+const page = ref(1)
+const pageSize = ref(10)
+const total = ref(0)
+const filters = ref<QueryModel>({ orderNo: '', inboundCode: '', lxCode: '', status: '', warehouse: '', fbaWarehouse: '', appointmentStatus: '', dispatchStatus: '', inboundDate: [] })
+const fields = computed<QueryField[]>(() => [
+  { key: 'orderNo', type: 'input', label: '入库单号', width: 165, placeholder: '入库单号' },
+  { key: 'inboundCode', type: 'input', label: '入仓码', width: 145, placeholder: '入仓码' },
+  { key: 'lxCode', type: 'input', label: 'LX代码', width: 160, placeholder: '领星入库单代码' },
+  { key: 'status', type: 'select', label: '状态', width: 130, placeholder: '全部状态', options: [{ label: '待入库', value: 'PENDING_ASSIGNMENT' }, { label: '拣货中', value: 'PICKING' }, { label: '全部入库', value: 'COMPLETED' }, { label: '部分入库', value: 'PARTIAL_INBOUND' }] },
+  { key: 'warehouse', type: 'input', label: '海外仓', width: 155, placeholder: '全部海外仓' },
+  { key: 'fbaWarehouse', type: 'input', label: 'FBA仓库', width: 145, placeholder: '全部FBA仓库' },
+  { key: 'appointmentStatus', type: 'select', label: '预约状态', width: 145, placeholder: '全部预约状态', options: [{ label: '未预约', value: 'UNAPPOINTED' }, { label: '预约中', value: 'PENDING' }, { label: '预约成功', value: 'SUCCESS' }, { label: '预约失败', value: 'FAILED' }, { label: '已取消', value: 'CANCELLED' }] },
+  { key: 'dispatchStatus', type: 'select', label: '排车状态', width: 140, placeholder: '全部排车状态', options: [{ label: '未排车', value: 'UNSCHEDULED' }, { label: '已排车', value: 'SCHEDULED' }] },
+  { key: 'inboundDate', type: 'daterange', label: '入库时间', width: 260 },
+])
+
+const appointmentOpen = ref(false)
+const smartDispatchOpen = ref(false)
+const appointmentLoading = ref(false)
+const appointmentMode = ref<'create' | 'edit'>('create')
+const editingAppointmentNo = ref('')
+const editingCustomerId = ref('')
+const appointmentSelectedCount = ref(0)
+const appointmentFbaWarehouse = ref('—')
+const appointmentForm = reactive({ appointmentNo: '', appointmentAt: '', expectedLoadingAt: '', appointmentStatus: 'SUCCESS' as 'PENDING' | 'SUCCESS' | 'FAILED' | 'CANCELLED', appointmentRemark: '' })
+const appointmentTitle = computed(() => appointmentMode.value === 'edit' ? '编辑预约' : '预约')
+const planEditOpen = ref(false); const planEditLoading = ref(false); const planEditSaving = ref(false); const planEditTarget = ref<InboundOrderListItem | null>(null); const planEditForm = reactive({ warehouseId: '', warehouseCode: '', warehouseName: '', version: 0 }); const warehouses = ref<ReceivingOverseasWarehouseDto[]>([])
+
+function selectableRow(source: object) {
+  const row = source as InboundOrderListItem
+  if (!row.fbaWarehouse || row.fbaWarehouse === '—') return false
+  const anchor = selectedRows.value[0]
+  return !anchor || (anchor.customerId === row.customerId && anchor.fbaWarehouse === row.fbaWarehouse)
+}
+
+const columns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 300, fixed: 'left', slotName: 'actions' },
+  { key: 'selection', type: 'selection', width: 48, fixed: 'left', selectable: selectableRow },
+  { key: 'orderNo', prop: 'orderNo', label: '入库单号', minWidth: 170 },
+  { key: 'inboundCode', prop: 'inboundCode', label: '入仓码', minWidth: 140 },
+  { key: 'lxCode', prop: 'lxCode', label: 'LX代码', minWidth: 150 },
+  { key: 'type', prop: 'type', label: '类型', width: 100 },
+  { key: 'warehouse', prop: 'warehouse', label: '海外仓', minWidth: 170 },
+  { key: 'fbaWarehouse', prop: 'fbaWarehouse', label: 'FBA仓库', minWidth: 130 },
+  { key: 'owner', prop: 'owner', label: '货主', minWidth: 150 },
+  { key: 'cartons', prop: 'cartons', label: '应拣货数', width: 100, align: 'right' },
+  { key: 'pickedCartons', prop: 'pickedCartons', label: '实际拣货数', width: 110, align: 'right' },
+  { key: 'volume', prop: 'volume', label: '计费体积(m³)', width: 125, align: 'right' },
+  { key: 'pallets', prop: 'pallets', label: '总托盘数', width: 100, align: 'right' },
+  { key: 'assigned', prop: 'assigned', label: '分配', width: 82, align: 'center' },
+  { key: 'mergeAllowed', prop: 'mergeAllowed', label: '合托', width: 96, align: 'center' },
+  { key: 'urgent', prop: 'urgent', label: '加急', width: 82, align: 'center' },
+  { key: 'status', prop: 'status', label: '状态', width: 100 },
+  { key: 'appointmentStatus', prop: 'appointmentStatus', label: 'FBA预约', width: 110 },
+  { key: 'dispatchStatus', prop: 'dispatchStatus', label: '排车状态', width: 110 },
+  { key: 'createdAt', prop: 'createdAt', label: '创建时间', minWidth: 170 },
+]
+
+function text(value: unknown) { const normalized = String(value ?? '').trim(); return normalized || '—' }
+function receivingWarehouse(code: unknown, name: unknown) {
+  const normalizedCode = String(code ?? '').trim()
+  const normalizedName = String(name ?? '').trim()
+  return normalizedCode && normalizedName ? `${normalizedCode} · ${normalizedName}` : '—'
+}
+function number(value: unknown) { const normalized = Number(value); return Number.isFinite(normalized) ? normalized : 0 }
+function typeLabel(value: unknown) { return lastMileOrderTypeLabel(value) }
+function planStatusLabel(value: unknown) { return ({ PENDING_ASSIGNMENT: '待入库', ASSIGNED: '待入库', PDA_PENDING: '待入库', PICKING: '拣货中', COMPLETED: '全部入库', PARTIAL_INBOUND: '部分入库' } as Record<string, string>)[String(value || '')] || text(value) }
+function appointmentStatusLabel(value: unknown) { return !value ? '未预约' : ({ PENDING: '预约中', SUCCESS: '预约成功', FAILED: '预约失败', CANCELLED: '已取消' } as Record<string, string>)[String(value)] || text(value) }
+
+function toListItem(dto: InboundOrderSummaryDto): InboundOrderListItem {
+  return {
+    lineId: String(dto.lineId), planId: String(dto.planId), customerId: String(dto.customerId), orderId: String(dto.orderId),
+    warehouseId: text(dto.warehouseId) === '—' ? '' : String(dto.warehouseId), destinationWarehouseCode: text(dto.warehouseCode), destinationWarehouseName: text(dto.warehouseName),
+    orderNo: text(dto.planNo), inboundCode: text(dto.inboundCode), lxCode: text(dto.lxCode), type: typeLabel(dto.orderType), warehouse: receivingWarehouse(dto.overseasWarehouseCode, dto.overseasWarehouseName),
+    fbaWarehouse: text(dto.fbaWarehouseCode), owner: text(dto.customerName), cartons: number(dto.packageCount), pickedCartons: number(dto.pickedPackageCount), volume: number(dto.volumeCbm), pallets: number(dto.palletCount),
+    assigned: dto.assigned ? '已分配' : '未分配', mergeAllowed: dto.mergeAllowed ? '可合托' : '不合托', urgent: dto.urgent ? '加急' : '普通',
+    status: planStatusLabel(dto.status), appointmentNo: text(dto.appointmentNo), appointmentStatus: appointmentStatusLabel(dto.appointmentStatus),
+    appointmentAt: formatOverseasDateTime(dto.appointmentAt), expectedLoadingAt: formatOverseasDateTime(dto.expectedLoadingAt), dispatchStatus: dto.dispatchStatus === 'SCHEDULED' ? '已排车' : '未排车',
+    createdAt: formatOverseasDateTime(dto.createdAt), version: number(dto.version),
+  }
+}
+
+function onSelectionChange(selection: object[]) { selectedRows.value = selection as InboundOrderListItem[] }
+function selectionError() {
+  if (!selectedRows.value.length) return '请至少选择 1 条入库单'
+  if (selectedRows.value.some((row) => !row.fbaWarehouse || row.fbaWarehouse === '—')) return '所选入库单缺少 FBA 仓库信息'
+  if (new Set(selectedRows.value.map((row) => row.customerId)).size !== 1) return '所选入库单必须属于同一客户'
+  if (new Set(selectedRows.value.map((row) => row.fbaWarehouse)).size !== 1) return '所选入库单必须属于同一 FBA 仓库'
+  return ''
+}
+
+function openAppointment() {
+  const error = selectionError()
+  if (error) { ElMessage.warning(error); return }
+  appointmentMode.value = 'create'; editingAppointmentNo.value = ''; editingCustomerId.value = ''
+  appointmentSelectedCount.value = selectedRows.value.length; appointmentFbaWarehouse.value = selectedRows.value[0]?.fbaWarehouse || '—'
+  Object.assign(appointmentForm, { appointmentNo: '', appointmentAt: '', expectedLoadingAt: '', appointmentStatus: 'SUCCESS', appointmentRemark: '' })
+  mutationError.value = null
+  appointmentOpen.value = true
+}
+
+function openSmartDispatch() {
+  smartDispatchOpen.value = true
+}
+
+async function openAppointmentEdit(source: object) {
+  const row = source as InboundOrderListItem
+  if (!row.appointmentNo || row.appointmentNo === '—') return
+  appointmentMode.value = 'edit'; editingAppointmentNo.value = row.appointmentNo; editingCustomerId.value = row.customerId
+  appointmentLoading.value = true; mutationError.value = null; appointmentOpen.value = true
+  try {
+    const detail = await getFbaAppointment(row.customerId, row.appointmentNo)
+    appointmentSelectedCount.value = detail.selectedCount
+    appointmentFbaWarehouse.value = detail.fbaWarehouseCode || row.fbaWarehouse
+    Object.assign(appointmentForm, { appointmentNo: detail.appointmentNo, appointmentAt: detail.appointmentAt, expectedLoadingAt: detail.expectedLoadingAt, appointmentStatus: detail.appointmentStatus, appointmentRemark: detail.appointmentRemark || '' })
+  } catch (caught) {
+    appointmentOpen.value = false
+    mutationError.value = getApiErrorDetails(caught, 'FBA 预约详情加载失败，请重试')
+  } finally { appointmentLoading.value = false }
+}
+
+async function submitAppointment() {
+  if (appointmentMode.value === 'create') { const error = selectionError(); if (error) { ElMessage.warning(error); return } }
+  if (!appointmentForm.appointmentNo.trim() || !appointmentForm.appointmentAt || !appointmentForm.expectedLoadingAt) { ElMessage.warning('请填写预约号、预约送仓时间和预计装车时间'); return }
+  saving.value = true; mutationError.value = null
+  try {
+    const common = { appointmentAt: appointmentForm.appointmentAt, expectedLoadingAt: appointmentForm.expectedLoadingAt, appointmentStatus: appointmentForm.appointmentStatus, appointmentRemark: appointmentForm.appointmentRemark.trim() || undefined }
+    if (appointmentMode.value === 'edit') await updateFbaAppointment(editingAppointmentNo.value, { customerId: editingCustomerId.value, ...common })
+    else await createFbaAppointment({ customerId: selectedRows.value[0].customerId, lineIds: selectedRows.value.map((row) => row.lineId), appointmentNo: appointmentForm.appointmentNo.trim(), ...common })
+    appointmentOpen.value = false; selectedRows.value = []; ElMessage.success('FBA 预约保存成功'); await load()
+  } catch (caught) { mutationError.value = getApiErrorDetails(caught, 'FBA 预约保存失败，请重试') }
+  finally { saving.value = false }
+}
+
+function dateRange() {
+  const range = Array.isArray(filters.value.inboundDate) ? filters.value.inboundDate : []
+  return { createdFrom: range[0] ? `${String(range[0]).slice(0, 10)}T00:00:00` : undefined, createdTo: range[1] ? `${String(range[1]).slice(0, 10)}T23:59:59` : undefined }
+}
+
+async function load(model: QueryModel = filters.value) {
+  Object.assign(filters.value, model)
+  selectedRows.value = []
+  loading.value = true; loadError.value = null
+  try {
+    const result = await listInboundOrders({ page: page.value, size: pageSize.value, planNo: String(filters.value.orderNo || '').trim() || undefined, inboundCode: String(filters.value.inboundCode || '').trim() || undefined, lxCode: String(filters.value.lxCode || '').trim() || undefined, status: String(filters.value.status || '').trim() || undefined, warehouse: String(filters.value.warehouse || '').trim() || undefined, fbaWarehouseCode: String(filters.value.fbaWarehouse || '').trim() || undefined, appointmentStatus: String(filters.value.appointmentStatus || '').trim() || undefined, dispatchStatus: String(filters.value.dispatchStatus || '').trim() || undefined, ...dateRange() })
+    rows.value = result.records.map(toListItem); total.value = result.total
+  } catch (error) { rows.value = []; total.value = 0; loadError.value = getApiErrorDetails(error, '入库单加载失败，请重试') }
+  finally { loading.value = false }
+}
+
+function search(model: QueryModel) { page.value = 1; void load(model) }
+function reset(model: QueryModel) { page.value = 1; void load(model) }
+function openDetail(source: object) { const row = source as InboundOrderListItem; void router.push({ name: 'overseas-inbound-order-detail', params: { orderId: row.orderNo }, query: { customerId: row.customerId } }) }
+async function openPlanEdit(source: object) { const row = source as InboundOrderListItem; planEditTarget.value = row; planEditOpen.value = true; planEditLoading.value = true; mutationError.value = null; try { Object.assign(planEditForm, { warehouseId: row.warehouseId, warehouseCode: row.destinationWarehouseCode === '—' ? '' : row.destinationWarehouseCode, warehouseName: row.destinationWarehouseName === '—' ? '' : row.destinationWarehouseName, version: row.version }); if (!warehouses.value.length) warehouses.value = (await listReceivingOverseasWarehouses()).records } catch (error) { planEditOpen.value = false; mutationError.value = getApiErrorDetails(error, '海外仓列表加载失败，请重试') } finally { planEditLoading.value = false } }
+async function submitPlanEdit() { const target = planEditTarget.value; if (!target || !planEditForm.warehouseId) { ElMessage.warning('请选择目的仓'); return } planEditSaving.value = true; mutationError.value = null; try { await updateInboundPlan(target.orderNo, { customerId: target.customerId, overseasWarehouseId: planEditForm.warehouseId, warehouseCode: planEditForm.warehouseCode, warehouseName: planEditForm.warehouseName, version: planEditForm.version }); planEditOpen.value = false; ElMessage.success('入库单已更新'); await load() } catch (error) { mutationError.value = getApiErrorDetails(error, '入库单更新失败，请重试') } finally { planEditSaving.value = false } }
+onMounted(() => { void load() })
+</script>
+
+<template>
+  <AdminPage class="admin-density"><OperationErrorToast :details="mutationError" /><ListPageLayout aria-label="海外仓入库单列表">
+    <template #toolbar><QueryToolbar v-model="filters" class="surface-panel" :fields="fields" :loading="loading" ariaLabel="入库单筛选" preference-key="overseas-inbound-orders-query" :search-on-reset="false" @search="search" @reset="reset" /></template>
+    <template v-if="loadError" #state><LoadErrorState title="入库单加载失败" :message="loadError.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="loadError" /></template></LoadErrorState></template>
+    <section v-if="!loadError" class="surface-panel table-panel"><DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :loading="loading" :total="total" preference-key="overseas-inbound-orders" row-key="lineId" empty-text="暂无入库单" @selection-change="onSelectionChange" @update:page="load()" @update:page-size="page = 1; load()">
+      <template #toolbar-actions><el-button v-if="access.can(permission.inboundOrderAppointment)" plain :disabled="!selectedRows.length" @click="openAppointment"><CalendarCheck2 :size="16" />预约</el-button><el-button v-if="access.can(permission.inboundOrderSmartDispatch)" type="primary" @click="openSmartDispatch"><Truck :size="16" />智能排车</el-button></template>
+      <template #actions="{ row }"><div class="row-actions density-actions"><el-button class="density-action" data-tone="neutral" size="small" @click="openDetail(row)">查看</el-button><el-button class="density-action" data-tone="neutral" v-if="access.can(permission.inboundOrderEdit) && ['待入库'].includes((row as InboundOrderListItem).status)" size="small" @click="openPlanEdit(row)">编辑</el-button><el-button class="density-action" data-tone="neutral" v-if="(row as InboundOrderListItem).appointmentNo !== '—' && access.can(permission.inboundOrderAppointment)" size="small" @click="openAppointmentEdit(row)">预约</el-button></div></template>
+      <template #pagination-left>共 {{ total }} 条入库单 · 已选 {{ selectedRows.length }} 条</template>
+    </DataTable></section>
+  </ListPageLayout>
+  <AppDialog class="admin-density-dialog" v-model="appointmentOpen" :title="appointmentTitle" width="min(1080px, calc(100vw - 48px))" confirm-text="保存预约" :confirm-loading="saving" @confirm="submitAppointment">
+    <div v-loading="appointmentLoading">
+    <div class="appointment-summary">已选择 {{ appointmentSelectedCount }} 条，FBA仓库：{{ appointmentFbaWarehouse }}</div>
+    <el-form label-position="top" class="appointment-form density-form">
+      <el-form-item label="预约号" required><el-input v-model="appointmentForm.appointmentNo" maxlength="64" :readonly="appointmentMode === 'edit'" placeholder="请输入预约号" /></el-form-item>
+      <el-form-item label="预约送仓时间" required><el-date-picker v-model="appointmentForm.appointmentAt" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" placeholder="请选择预约送仓时间" /></el-form-item>
+      <el-form-item label="预计装车时间" required><el-date-picker v-model="appointmentForm.expectedLoadingAt" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" placeholder="请选择预计装车时间" /></el-form-item>
+      <el-form-item label="预约状态" required><el-select v-model="appointmentForm.appointmentStatus" placeholder="请选择预约状态"><el-option label="预约中" value="PENDING" /><el-option label="预约成功" value="SUCCESS" /><el-option label="预约失败" value="FAILED" /><el-option label="已取消" value="CANCELLED" /></el-select></el-form-item>
+      <el-form-item label="预约备注"><el-input v-model="appointmentForm.appointmentRemark" maxlength="1000" placeholder="请输入预约备注" /></el-form-item>
+    </el-form>
+    </div>
+  </AppDialog>
+  <SmartDispatchDialog v-model="smartDispatchOpen" :orders="selectedRows" @created="selectedRows = []; load()" />
+  <AppDialog class="admin-density-dialog" v-model="planEditOpen" title="编辑入库单" confirm-text="保存" :confirm-loading="planEditSaving" @confirm="submitPlanEdit"><div v-loading="planEditLoading"><el-form class="density-form" label-position="top"><el-form-item label="目的仓" required><el-select v-model="planEditForm.warehouseId" filterable style="width:100%" @change="(id: string) => { const w = warehouses.find((item) => item.id === id); planEditForm.warehouseCode = w?.warehouseCode || ''; planEditForm.warehouseName = w?.warehouseName || '' }"><el-option v-for="warehouse in warehouses" :key="warehouse.id" :label="`${warehouse.warehouseName}（${warehouse.warehouseCode}）`" :value="warehouse.id" /></el-select></el-form-item><el-form-item label="版本"><el-input-number v-model="planEditForm.version" :min="0" disabled /></el-form-item></el-form></div></AppDialog>
+  </AdminPage>
+</template>
+
+<style scoped>
+.appointment-summary { margin-bottom: var(--admin-space-5); padding: var(--admin-space-4) var(--admin-space-5); border: 1px solid #cdddfd; border-radius: var(--admin-radius); background: #f5f9ff; color: #52627a; font-size: var(--admin-font-body); }
+.appointment-form { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 0 var(--admin-space-5); }
+.appointment-form :deep(.el-date-editor), .appointment-form :deep(.el-select) { width: 100%; }
+.row-actions { min-width: max-content; flex-wrap: nowrap; white-space: nowrap; }
+.row-actions :deep(.el-button) { flex: 0 0 auto; }
+@media (max-width: 720px) { .appointment-form { grid-template-columns: 1fr; } }
+</style>
diff --git a/src/modules/overseas-warehouse/pages/InventoryCustomerName.behavior.test.ts b/src/modules/overseas-warehouse/pages/InventoryCustomerName.behavior.test.ts
new file mode 100644
index 00000000..0af191b4
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/InventoryCustomerName.behavior.test.ts
@@ -0,0 +1,92 @@
+import ElementPlus from 'element-plus'
+import { createPinia } from 'pinia'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { getInventorySummary, listInventoryBalances, listInventoryLedger, listInventoryPositions } from '../api/inventory'
+import InventoryDetailView from './InventoryDetailView.vue'
+import InventoryView from './InventoryView.vue'
+
+const routing = vi.hoisted(() => ({ push: vi.fn(), route: { params: {} as Record<string, string>, query: {} as Record<string, string> } }))
+vi.mock('vue-router', () => ({ useRoute: () => routing.route, useRouter: () => ({ push: routing.push }) }))
+vi.mock('@/core/access/accessPreview', () => ({ useAccessPreviewStore: () => ({ can: () => false }) }))
+vi.mock('../api/pallets', () => ({ listReceivingOverseasWarehouses: vi.fn() }))
+vi.mock('../api/inventory', () => ({
+  listInventoryBalances: vi.fn(), getInventorySummary: vi.fn(),
+  listInventoryPositions: vi.fn(), listInventoryLedger: vi.fn(),
+}))
+
+class ResizeObserverStub implements ResizeObserver { observe() {} unobserve() {} disconnect() {} }
+function memoryStorage(): Storage {
+  const values = new Map<string, string>()
+  return {
+    get length() { return values.size }, clear: () => values.clear(), getItem: (key) => values.get(key) ?? null,
+    key: (index) => [...values.keys()][index] ?? null, removeItem: (key) => values.delete(key), setItem: (key, value) => values.set(key, value),
+  }
+}
+
+const customerId = '2092618717861048321'
+const balance = {
+  id: '2092873463568596994', customerId, customerName: '华远贸易', overseasWarehouseId: '200',
+  overseasWarehouseName: '洛杉矶仓', inboundOrderId: '300', inboundOrderNo: 'LIP-1', inboundCode: 'IN-1',
+  destinationWarehouseName: 'ONT8目的仓',
+  skuCode: 'SKU-1', productNameZh: '验收商品', totalPackages: 10, availablePackages: 10,
+  holdPackages: 0, allocatedPackages: 0, pickedPackages: 0, inTransitPackages: 0,
+  receivingPackages: 0, procurementPackages: 0, updatedAt: '2026-08-28T10:00:00',
+}
+
+enableAutoUnmount(afterEach)
+afterAll(() => vi.unstubAllGlobals())
+
+describe('inventory customer-name snapshots', () => {
+  beforeEach(() => {
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+    vi.stubGlobal('localStorage', memoryStorage())
+    routing.push.mockReset(); routing.route.params = {}; routing.route.query = {}
+    vi.mocked(listInventoryBalances).mockReset().mockResolvedValue({ records: [balance], page: 1, size: 10, total: 1, pages: 1 })
+    vi.mocked(getInventorySummary).mockReset().mockResolvedValue({ inboundOrderCount: 1, palletCount: 1, totalPackages: 10, availablePackages: 10, holdPackages: 0, allocatedPackages: 0, pickedPackages: 0, inTransitPackages: 0, receivingPackages: 0, procurementPackages: 0 })
+    vi.mocked(listInventoryPositions).mockReset().mockResolvedValue([])
+    vi.mocked(listInventoryLedger).mockReset().mockResolvedValue({ records: [], page: 1, size: 200, total: 0, pages: 0 })
+  })
+
+  it('renders the formal server customerName in the inventory list', async () => {
+    const wrapper = mount(InventoryView, { attachTo: document.body, global: { plugins: [createPinia(), ElementPlus] } })
+    await flushPromises()
+    expect(wrapper.text()).toContain('华远贸易')
+    expect(wrapper.text()).toContain('洛杉矶仓')
+    expect(wrapper.text()).not.toContain('ONT8目的仓')
+    expect(wrapper.text()).not.toContain(customerId)
+  })
+
+  it('renders the same server snapshot in inventory detail', async () => {
+    routing.route.params = { inventoryId: balance.id }
+    routing.route.query = { overseasWarehouseId: balance.overseasWarehouseId, inboundOrderNo: balance.inboundOrderNo, inboundCode: balance.inboundCode, skuCode: balance.skuCode }
+    const wrapper = mount(InventoryDetailView, { attachTo: document.body, global: { plugins: [createPinia(), ElementPlus] } })
+    await flushPromises()
+    expect(wrapper.text()).toContain('华远贸易')
+    expect(wrapper.text()).toContain('洛杉矶仓')
+    expect(wrapper.find('.density-detail-title').text()).toBe(`${balance.inboundOrderNo} / ${balance.inboundCode} / ${balance.skuCode}`)
+    expect(wrapper.text()).toContain('美本土散板')
+    expect(wrapper.text()).not.toContain('美本土散版')
+    expect(wrapper.text()).not.toContain('ONT8目的仓')
+    expect(wrapper.text()).not.toContain(customerId)
+    expect(wrapper.text()).not.toContain(balance.id)
+  })
+
+  it('combines the available references and then shows an explicit empty business reference without exposing the inventory id', async () => {
+    vi.mocked(listInventoryBalances).mockResolvedValueOnce({ records: [{ ...balance, inboundOrderNo: '', skuCode: '' }], page: 1, size: 10, total: 1, pages: 1 })
+    routing.route.params = { inventoryId: balance.id }
+    routing.route.query = { inboundCode: balance.inboundCode }
+    const inboundCodeWrapper = mount(InventoryDetailView, { attachTo: document.body, global: { plugins: [createPinia(), ElementPlus] } })
+    await flushPromises()
+    expect(inboundCodeWrapper.find('.density-detail-title').text()).toBe(`${balance.inboundCode}`)
+    expect(inboundCodeWrapper.text()).not.toContain(balance.id)
+
+    inboundCodeWrapper.unmount()
+    vi.mocked(listInventoryBalances).mockResolvedValueOnce({ records: [{ ...balance, inboundOrderNo: '', inboundCode: '', skuCode: '' }], page: 1, size: 10, total: 1, pages: 1 })
+    routing.route.query = {}
+    const emptyWrapper = mount(InventoryDetailView, { attachTo: document.body, global: { plugins: [createPinia(), ElementPlus] } })
+    await flushPromises()
+    expect(emptyWrapper.find('.density-detail-title').text()).toBe('—')
+    expect(emptyWrapper.text()).not.toContain(balance.id)
+  })
+})
diff --git a/src/modules/overseas-warehouse/pages/InventoryDetailView.vue b/src/modules/overseas-warehouse/pages/InventoryDetailView.vue
new file mode 100644
index 00000000..a7441dbb
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/InventoryDetailView.vue
@@ -0,0 +1,41 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, ref } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'; import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'; import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { listInventoryBalances, listInventoryLedger, listInventoryPositions, type InventoryBalanceDto, type InventoryLedgerDto, type InventoryPositionDto } from '../api/inventory'; import { inventoryProductName } from '../inventoryPresentation'; import { formatOverseasDateTime, inventoryBusinessTypeLabel } from '../lastMilePresentation'; import OverseasDetailShell from '../components/OverseasDetailShell.vue'
+
+const route = useRoute(); const router = useRouter(); const inventoryId = computed(() => String(route.params.inventoryId || ''))
+const balance = ref<InventoryBalanceDto | null>(null); const positions = ref<InventoryPositionDto[]>([]); const ledger = ref<InventoryLedgerDto[]>([]); const loading = ref(false); const loadError = ref<ApiErrorDetails | null>(null)
+function text(value: unknown) { return String(value ?? '').trim() || '—' }
+const businessReferences = computed(() => [
+  ['入库单号', balance.value?.inboundOrderNo || route.query.inboundOrderNo],
+  ['入仓码', balance.value?.inboundCode || route.query.inboundCode],
+  ['SKU', balance.value?.skuCode || route.query.skuCode],
+].map(([label, value]) => [String(label), String(value ?? '').trim()] as const).filter(([, value]) => value))
+const referenceLabel = computed(() => businessReferences.value.map(([label]) => label).join(' / ') || '业务标识')
+const referenceValue = computed(() => businessReferences.value.map(([, value]) => value).join(' / ') || '—')
+const productValues = computed(() => ({ 客户: text(balance.value?.customerName), 海外仓: text(balance.value?.overseasWarehouseName), SKU编码: text(balance.value?.skuCode), 产品名称: balance.value ? inventoryProductName(balance.value) : '—', 更新时间: formatOverseasDateTime(balance.value?.updatedAt) }))
+const stockValues = computed(() => ({ 在库总量: Number(balance.value?.totalPackages || 0), 可用库存: Number(balance.value?.availablePackages || 0), 暂扣库存: Number(balance.value?.holdPackages || 0), 美本土散板: '—', 在途库存: Number(balance.value?.inTransitPackages || 0), 采购库存: Number(balance.value?.procurementPackages || 0), 预计总量: Number(balance.value?.totalPackages || 0) + Number(balance.value?.inTransitPackages || 0) + Number(balance.value?.procurementPackages || 0) }))
+const productFields = ['客户', '海外仓', 'SKU编码', '产品名称', '更新时间']; const stockFields = ['在库总量', '可用库存', '暂扣库存', '美本土散板', '在途库存', '采购库存', '预计总量']
+const locationRows = computed(() => positions.value.map((item) => ({ id: String(item.id), location: text(item.warehouseLocationCode), status: text(item.status), palletNo: text(item.palletNo), cartons: Number(item.totalPackages || 0), quantity: Number(item.totalPackages || 0), available: Number(item.availablePackages || 0), inboundDate: formatOverseasDateTime(item.updatedAt), ageDays: '—' })))
+const palletRows = computed(() => positions.value.map((item) => ({ id: String(item.id), palletNo: text(item.palletNo), cartons: Number(item.totalPackages || 0), cartonRange: '—', location: text(item.warehouseLocationCode), quantity: Number(item.totalPackages || 0) })))
+const ledgerRows = computed(() => ledger.value.map((item) => ({ id: String(item.id), occurredAt: formatOverseasDateTime(item.occurredAt), businessType: inventoryBusinessTypeLabel(item.businessType), businessOrderNo: text(item.businessOrderNo), inboundOrderNo: text(item.inboundOrderNo), outboundOrderNo: text(item.outboundOrderNo), location: text(item.warehouseLocationCode), inboundQuantity: item.deltaPackages > 0 ? item.deltaPackages : 0, outboundQuantity: item.deltaPackages < 0 ? Math.abs(item.deltaPackages) : 0, balance: Number(item.afterPackages || 0), operator: '—', remark: text(item.remark) })))
+const locationColumns: DataTableColumn[] = [{ key: 'location', prop: 'location', label: '库位', minWidth: 130 }, { key: 'status', prop: 'status', label: '库存状态', width: 120 }, { key: 'palletNo', prop: 'palletNo', label: '托盘号', minWidth: 150 }, { key: 'cartons', prop: 'cartons', label: '箱数', width: 90, align: 'right' }, { key: 'quantity', prop: 'quantity', label: '库存数量', width: 110, align: 'right' }, { key: 'available', prop: 'available', label: '可用数量', width: 110, align: 'right' }, { key: 'inboundDate', prop: 'inboundDate', label: '最近更新', width: 160 }, { key: 'ageDays', prop: 'ageDays', label: '库龄(天)', width: 100, align: 'right' }]
+const palletColumns: DataTableColumn[] = [{ key: 'palletNo', prop: 'palletNo', label: '托盘号', minWidth: 150 }, { key: 'cartons', prop: 'cartons', label: '关联箱数', width: 110, align: 'right' }, { key: 'cartonRange', prop: 'cartonRange', label: '箱号范围', minWidth: 200 }, { key: 'location', prop: 'location', label: '库位', minWidth: 130 }, { key: 'quantity', prop: 'quantity', label: '库存数量', width: 110, align: 'right' }]
+const ledgerColumns: DataTableColumn[] = [{ key: 'occurredAt', prop: 'occurredAt', label: '发生时间', minWidth: 160 }, { key: 'businessType', prop: 'businessType', label: '业务类型', width: 120 }, { key: 'businessOrderNo', prop: 'businessOrderNo', label: '业务订单号', minWidth: 170 }, { key: 'inboundOrderNo', prop: 'inboundOrderNo', label: '入库单号', minWidth: 160 }, { key: 'outboundOrderNo', prop: 'outboundOrderNo', label: '出库单号', minWidth: 160 }, { key: 'location', prop: 'location', label: '库位', minWidth: 120 }, { key: 'inboundQuantity', prop: 'inboundQuantity', label: '入库数量', width: 110, align: 'right' }, { key: 'outboundQuantity', prop: 'outboundQuantity', label: '出库数量', width: 110, align: 'right' }, { key: 'balance', prop: 'balance', label: '结存', width: 100, align: 'right' }, { key: 'operator', prop: 'operator', label: '操作人', minWidth: 120 }, { key: 'remark', prop: 'remark', label: '备注', minWidth: 180 }]
+async function load() { if (!inventoryId.value) { loadError.value = { message: '详情缺少库存记录编号，请从库存列表重新进入' }; return }; loading.value = true; loadError.value = null; try { const inboundOrderNo = String(route.query.inboundOrderNo || ''); const inboundCode = String(route.query.inboundCode || ''); const skuCode = String(route.query.skuCode || ''); const overseasWarehouseId = String(route.query.overseasWarehouseId || ''); const result = await listInventoryBalances({ page: 1, size: 200, inboundOrderNo: inboundOrderNo || undefined, inboundCode: inboundCode || undefined, skuCode: skuCode || undefined, overseasWarehouseId: overseasWarehouseId || undefined }); balance.value = result.records.find((item) => String(item.id) === inventoryId.value) || null; if (!balance.value) throw new Error('Inventory balance not found'); const [positionRows, ledgerPage] = await Promise.all([listInventoryPositions(inventoryId.value), listInventoryLedger({ page: 1, size: 200, inboundOrderNo: balance.value.inboundOrderNo || undefined, inboundCode: balance.value.inboundCode || undefined })]); positions.value = positionRows; ledger.value = ledgerPage.records } catch (error) { loadError.value = getApiErrorDetails(error, '库存详情加载失败，请重试') } finally { loading.value = false } }
+function back() { void router.push({ name: 'overseas-inventory' }) }; onMounted(load)
+</script>
+
+<template><OverseasDetailShell class="admin-density" dense title="库存详情" :reference-label="referenceLabel" :reference-value="referenceValue" back-label="返回库存管理" domain="库存详情" :pending="false" :status-text="balance ? '库存事实' : '加载中'" @back="back"><LoadErrorState v-if="loadError" title="库存详情加载失败" :message="loadError.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="loadError" /></template></LoadErrorState>
+  <template v-else><section v-loading="loading" class="overview-panel" aria-label="库存概览"><section aria-labelledby="inventory-product-heading"><h2 id="inventory-product-heading">商品信息</h2><dl class="detail-fields density-fields"><div v-for="label in productFields" :key="label"><dt>{{ label }}</dt><dd>{{ productValues[label as keyof typeof productValues] }}</dd></div></dl></section><section aria-labelledby="inventory-summary-heading"><h2 id="inventory-summary-heading">库存状态汇总</h2><dl class="detail-fields density-fields"><div v-for="label in stockFields" :key="label"><dt>{{ label }}</dt><dd>{{ stockValues[label as keyof typeof stockValues] }}</dd></div></dl></section></section>
+  <section class="ledger-section" aria-labelledby="inventory-location-heading"><h2 id="inventory-location-heading">库位库存</h2><DataTable :data="locationRows" :columns="locationColumns" column-settings-mode="hide" row-key="id" empty-text="暂无库位库存" /></section><section class="ledger-section" aria-labelledby="inventory-pallet-heading"><h2 id="inventory-pallet-heading">托盘箱号信息</h2><DataTable :data="palletRows" :columns="palletColumns" column-settings-mode="hide" row-key="id" empty-text="暂无托盘库存" /></section><section class="ledger-section" aria-labelledby="inventory-ledger-heading"><h2 id="inventory-ledger-heading">进销存单据明细</h2><p class="ledger-note">按该库存记录的入库单范围展示，出库字段仅为只读事实。</p><DataTable :data="ledgerRows" :columns="ledgerColumns" column-settings-mode="hide" row-key="id" empty-text="暂无进销存明细" /></section></template>
+</OverseasDetailShell></template>
+<style scoped>.overview-panel>section{min-width:0;padding:var(--admin-space-5) var(--admin-space-5) var(--admin-space-5);border-right:1px solid var(--cc-border)}.overview-panel>section:last-child{border-right:0}.overview-panel h2,.ledger-section h2{margin:0 0 var(--admin-space-5);color:var(--cc-text);font-size:var(--admin-font-section)}.ledger-section h2,.ledger-note{margin-right:var(--admin-space-5);margin-left:var(--admin-space-5)}.ledger-note{color:var(--cc-muted);font-size:var(--admin-font-caption)}@media(max-width:1100px){.overview-panel,.detail-fields{grid-template-columns:1fr}.overview-panel>section{border-right:0;border-bottom:1px solid var(--cc-border)}}
+.overview-panel {display:grid;min-width:0; grid-template-columns: minmax(0, 1fr); border: 0;background:#fff; }
+.overview-panel > section { border-right: 0; }
+.ledger-section {min-width:0;overflow:hidden;padding-top:var(--admin-space-5); border: 0;background:#fff; border-top: 1px solid var(--cc-border); }
+
+</style>
diff --git a/src/modules/overseas-warehouse/pages/InventoryTransactionsView.vue b/src/modules/overseas-warehouse/pages/InventoryTransactionsView.vue
new file mode 100644
index 00000000..cb131063
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/InventoryTransactionsView.vue
@@ -0,0 +1,51 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, ref } from 'vue'
+import { ArrowLeft, Download } from '@lucide/vue'
+import { ElMessage } from 'element-plus'
+import { useRoute, useRouter } from 'vue-router'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import AdminPage from '@/shared/components/AdminPage.vue'; import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'; import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'; import ListPageLayout from '@/shared/components/ListPageLayout.vue'; import LoadErrorState from '@/shared/components/LoadErrorState.vue'; import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import InboundCodeRelationshipDialog from '@/shared/components/InboundCodeRelationshipDialog.vue'
+import { saveCsv } from '@/shared/downloadCsv'
+import { downloadInventoryLedger, listInventoryLedger } from '../api/inventory'; import { formatOverseasDateTime, inventoryBusinessTypeLabel } from '../lastMilePresentation'; import { overseasWarehousePermissions as permission } from '../permissions'; import type { InventoryTransactionListItem } from '../types'
+
+const route = useRoute(); const router = useRouter(); const access = useAccessPreviewStore(); const rows = ref<InventoryTransactionListItem[]>([]); const page = ref(1); const pageSize = ref(10); const total = ref(0); const loading = ref(false); const loadError = ref<ApiErrorDetails | null>(null)
+const exportLoading = ref(false)
+const relationshipDialogOpen = ref(false); const relationshipDialogInboundCode = ref('')
+const filters = ref<QueryModel>({ occurredDate: [], customerName: '', warehouse: '', sku: '', businessType: '', businessOrderNo: '', inboundCode: '', inboundOrderNo: '', outboundOrderNo: '' })
+const fields = computed<QueryField[]>(() => [
+  { key: 'occurredDate', type: 'daterange', label: '发生日期', width: 260 },
+  { key: 'customerName', type: 'input', label: '客户名称', placeholder: '请输入客户名称', width: 190 },
+  { key: 'warehouse', type: 'input', label: '目的仓代码', placeholder: '请输入目的仓代码', width: 190 }, { key: 'sku', type: 'input', label: 'SKU编码', placeholder: '请输入 SKU 编码', width: 170 },
+  { key: 'businessType', type: 'select', label: '业务类型', placeholder: '全部业务类型', width: 170, options: [
+    { label: '在途入账', value: 'IN_TRANSIT' }, { label: '入库', value: 'STOCK_IN' }, { label: '库存暂扣', value: 'HOLD' }, { label: '解除暂扣', value: 'RELEASE' },
+    { label: '库存分配', value: 'ALLOCATE' }, { label: '取消分配', value: 'UNALLOCATE' }, { label: '拣货', value: 'PICK' }, { label: '出库', value: 'SHIP' },
+    { label: '库存调整', value: 'ADJUST' }, { label: '盘点调整', value: 'STOCKTAKE_ADJUST' }, { label: '组托', value: 'PALLET_ASSEMBLE' },
+    { label: '拆托', value: 'PALLET_DISASSEMBLE' }, { label: '换托', value: 'PALLET_SWAP' }, { label: '解托', value: 'PALLET_UNBIND' },
+  ] }, { key: 'businessOrderNo', type: 'input', label: '业务订单号', placeholder: '请输入业务订单号', width: 180 },
+  { key: 'inboundCode', type: 'input', label: '入仓码', placeholder: '请输入入仓码', width: 190 }, { key: 'inboundOrderNo', type: 'input', label: '入库单号', placeholder: '请输入入库单号', width: 180 }, { key: 'outboundOrderNo', type: 'input', label: '出库单号', placeholder: '只读关联筛选', width: 180 },
+])
+const columns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 108, fixed: 'left', slotName: 'actions' },
+  { key: 'occurredAt', prop: 'occurredAt', label: '发生时间', minWidth: 160 }, { key: 'owner', prop: 'owner', label: '客户', minWidth: 160 }, { key: 'warehouse', prop: 'warehouse', label: '目的仓编码', minWidth: 180 },
+  { key: 'sku', prop: 'sku', label: 'SKU编码', minWidth: 150 }, { key: 'productName', prop: 'productName', label: '中文品名', minWidth: 180 }, { key: 'businessType', prop: 'businessType', label: '业务类型', width: 120 },
+  { key: 'businessOrderNo', prop: 'businessOrderNo', label: '业务订单号', minWidth: 170 }, { key: 'inboundCode', prop: 'inboundCode', label: '入仓码', minWidth: 170 }, { key: 'inboundOrderNo', prop: 'inboundOrderNo', label: '入库单号', minWidth: 160 }, { key: 'outboundOrderNo', prop: 'outboundOrderNo', label: '出库单号', minWidth: 160 },
+  { key: 'inboundQuantity', prop: 'inboundQuantity', label: '入库数量', width: 110, align: 'right' }, { key: 'outboundQuantity', prop: 'outboundQuantity', label: '出库数量', width: 110, align: 'right' }, { key: 'balance', prop: 'balance', label: '结存', width: 100, align: 'right' },
+  { key: 'operator', prop: 'operator', label: '操作人', minWidth: 120 }, { key: 'remark', prop: 'remark', label: '备注', minWidth: 180 },
+]
+function text(value: unknown) { return String(value ?? '').trim() || '—' }
+function openRelationship(row: InventoryTransactionListItem) { if (row.inboundCode === '—') return; relationshipDialogInboundCode.value = row.inboundCode; relationshipDialogOpen.value = true }
+async function load(model: QueryModel = filters.value) { Object.assign(filters.value, model); const range = Array.isArray(filters.value.occurredDate) ? filters.value.occurredDate.map(String) : []; loading.value = true; loadError.value = null; try { const result = await listInventoryLedger({ page: page.value, size: pageSize.value, customerName: String(filters.value.customerName || '').trim() || undefined, destinationWarehouseCode: String(filters.value.warehouse || '').trim() || undefined, skuCode: String(filters.value.sku || '').trim() || undefined, businessType: String(filters.value.businessType || '').trim() || undefined, businessOrderNo: String(filters.value.businessOrderNo || '').trim() || undefined, inboundCode: String(filters.value.inboundCode || '').trim() || undefined, inboundOrderNo: String(filters.value.inboundOrderNo || '').trim() || undefined, outboundOrderNo: String(filters.value.outboundOrderNo || '').trim() || undefined, occurredFrom: range[0] ? `${range[0]}T00:00:00` : undefined, occurredTo: range[1] ? `${range[1]}T23:59:59` : undefined }); rows.value = result.records.map((item) => ({ id: String(item.id), occurredAt: formatOverseasDateTime(item.occurredAt), owner: text(item.customerName), warehouse: text(item.destinationWarehouseCode), sku: text(item.skuCode), productName: '—', businessType: inventoryBusinessTypeLabel(item.businessType), businessOrderNo: text(item.businessOrderNo), inboundCode: text(item.inboundCode), inboundOrderNo: text(item.inboundOrderNo), outboundOrderNo: text(item.outboundOrderNo), inboundQuantity: item.deltaPackages > 0 ? item.deltaPackages : 0, outboundQuantity: item.deltaPackages < 0 ? Math.abs(item.deltaPackages) : 0, balance: Number(item.afterPackages || 0), operator: '—', remark: text(item.remark) })); total.value = result.total } catch (error) { rows.value = []; total.value = 0; loadError.value = getApiErrorDetails(error, '进销存记录加载失败，请重试') } finally { loading.value = false } }
+function search(model: QueryModel) { page.value = 1; void load(model) }; function reset(model: QueryModel) { page.value = 1; void load(model) }; function back() { void router.push({ name: 'overseas-inventory' }) }; onMounted(load)
+async function exportLedger() { exportLoading.value = true; try { const range = Array.isArray(filters.value.occurredDate) ? filters.value.occurredDate.map(String) : []; saveCsv(await downloadInventoryLedger({ customerName: String(filters.value.customerName || '').trim() || undefined, destinationWarehouseCode: String(filters.value.warehouse || '').trim() || undefined, skuCode: String(filters.value.sku || '').trim() || undefined, businessType: String(filters.value.businessType || '').trim() || undefined, businessOrderNo: String(filters.value.businessOrderNo || '').trim() || undefined, inboundCode: String(filters.value.inboundCode || '').trim() || undefined, inboundOrderNo: String(filters.value.inboundOrderNo || '').trim() || undefined, outboundOrderNo: String(filters.value.outboundOrderNo || '').trim() || undefined, occurredFrom: range[0] ? `${range[0]}T00:00:00` : undefined, occurredTo: range[1] ? `${range[1]}T23:59:59` : undefined }) as Blob, '进销存记录.csv') } catch { ElMessage.error('进销存导出失败，请重试') } finally { exportLoading.value = false } }
+</script>
+
+<template><AdminPage class="admin-density"><ListPageLayout aria-label="进销存记录列表"><template #toolbar><QueryToolbar v-model="filters" class="surface-panel" :fields="fields" :loading="loading" ariaLabel="进销存记录筛选" preference-key="overseas-inventory-transactions-query" :search-on-reset="false" @search="search" @reset="reset" /></template>
+  <template v-if="loadError" #state><LoadErrorState title="进销存记录加载失败" :message="loadError.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="loadError" /></template></LoadErrorState></template>
+  <template v-else #state><p class="read-only-boundary">本页面仅用于查询库存流水，不提供出库单跳转或库存变更操作。</p></template>
+  <section v-if="!loadError" class="surface-panel table-panel"><DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :loading="loading" :total="total" preference-key="overseas-inventory-transactions" row-key="id" empty-text="暂无进销存记录" @update:page="load()" @update:page-size="page = 1; load()"><template #toolbar-actions><el-button v-if="access.can(permission.inventoryExport)" plain :loading="exportLoading" @click="exportLedger"><Download :size="16" />导出记录</el-button><el-button class="density-back" link @click="back"><ArrowLeft :size="16" />返回库存管理</el-button></template><template #actions="{ row }"><div class="density-actions"><el-button class="density-action" data-tone="neutral" :disabled="(row as InventoryTransactionListItem).inboundCode === '—'" @click="openRelationship(row as InventoryTransactionListItem)">关联数据</el-button></div></template><template #pagination-left>共 {{ total }} 条进销存记录</template></DataTable></section>
+  <InboundCodeRelationshipDialog dense v-if="relationshipDialogOpen" v-model="relationshipDialogOpen" :inbound-code="relationshipDialogInboundCode" :can-read-base="access.can('platform:order:list')" :can-read-loading="access.can('platform:firstleg:smart-loading:list')" :can-read-overseas="access.can('platform:overseas-warehouse:inventory:list')" />
+</ListPageLayout></AdminPage></template>
+<style scoped>.read-only-boundary{margin:var(--admin-space-3) 2px 0;color:var(--cc-muted);font-size:var(--admin-font-caption);line-height:1.5}</style>
diff --git a/src/modules/overseas-warehouse/pages/InventoryView.vue b/src/modules/overseas-warehouse/pages/InventoryView.vue
new file mode 100644
index 00000000..9788ffb2
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/InventoryView.vue
@@ -0,0 +1,114 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, ref } from 'vue'
+import { BookOpen, Download } from '@lucide/vue'
+import { useRouter } from 'vue-router'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import { downloadInventoryBalances, getInventorySummary, listInventoryBalances, type InventoryDashboardDto } from '../api/inventory'
+import { saveCsv } from '@/shared/downloadCsv'
+import { ElMessage } from 'element-plus'
+import { listReceivingOverseasWarehouses, type ReceivingOverseasWarehouseDto } from '../api/pallets'
+import { toInventoryListItem } from '../inventoryPresentation'
+import { overseasWarehousePermissions } from '../permissions'
+import type { InventoryListItem } from '../types'
+
+const router = useRouter()
+const access = useAccessPreviewStore()
+const warehouses = ref<ReceivingOverseasWarehouseDto[]>([])
+const rows = ref<InventoryListItem[]>([])
+const summary = ref<InventoryDashboardDto | null>(null)
+const loading = ref(false)
+const contextLoading = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const page = ref(1)
+const pageSize = ref(10)
+const total = ref(0)
+const exportLoading = ref(false)
+const filters = ref<QueryModel>({ warehouseId: '', owner: '', sku: '', productName: '', batchNo: '', location: '', status: '' })
+const fields = computed<QueryField[]>(() => [
+  ...(access.can(overseasWarehousePermissions.warehouseList) ? [{ key: 'warehouseId', type: 'select' as const, label: '海外仓', width: 200, placeholder: '全部海外仓', options: warehouses.value.map((item) => ({ label: `${item.warehouseName}（${item.warehouseCode}）`, value: String(item.id) })), props: { filterable: true, clearable: true, disabled: contextLoading.value } }] : []),
+  { key: 'owner', type: 'input', label: '客户/货主', width: 190, placeholder: '请输入客户或货主' },
+  { key: 'sku', type: 'input', label: 'SKU编码', width: 180, placeholder: '请输入SKU编码' },
+  { key: 'productName', type: 'input', label: '中文品名', width: 190, placeholder: '请输入中文品名' },
+  { key: 'batchNo', type: 'input', label: '批次号', width: 170, placeholder: '请输入批次号' },
+  { key: 'location', type: 'input', label: '库位', width: 200, placeholder: '请输入库位（可空）' },
+  { key: 'status', type: 'select', label: '库存状态', width: 170, placeholder: '全部库存状态', options: [{ label: '有可用库存', value: 'AVAILABLE' }, { label: '存在暂扣', value: 'HOLD' }, { label: '已分配', value: 'ALLOCATED' }, { label: '在途', value: 'IN_TRANSIT' }, { label: '收货中', value: 'RECEIVING' }, { label: '采购库存', value: 'PROCUREMENT' }] },
+])
+const metrics = computed(() => [
+  ['在库总量', summary.value?.totalPackages ?? 0, 'primary'], ['可用库存', summary.value?.availablePackages ?? 0, 'success'], ['暂扣库存', summary.value?.holdPackages ?? 0, 'danger'],
+  ['美本土散板', '—', 'neutral'], ['在途库存', summary.value?.inTransitPackages ?? 0, 'warning'], ['采购库存', summary.value?.procurementPackages ?? 0, 'neutral'],
+] as const)
+const columns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 110, fixed: 'left', slotName: 'actions' },
+  { key: 'owner', prop: 'owner', label: '客户', minWidth: 160 },
+  { key: 'warehouse', prop: 'warehouse', label: '海外仓', minWidth: 170 },
+  { key: 'sku', prop: 'sku', label: 'SKU编码', minWidth: 150 },
+  { key: 'productName', prop: 'productName', label: '中文品名', minWidth: 180 },
+  { key: 'location', prop: 'location', label: '库位', minWidth: 140, defaultVisible: false },
+  { key: 'onHand', prop: 'onHand', label: '在库总量', width: 105, align: 'right' },
+  { key: 'available', prop: 'available', label: '可用库存', width: 105, align: 'right' },
+  { key: 'held', prop: 'held', label: '暂扣库存', width: 105, align: 'right' },
+  { key: 'looseboard', prop: 'looseboard', label: '美本土散板', width: 115, align: 'right' },
+  { key: 'inTransit', prop: 'inTransit', label: '在途库存', width: 105, align: 'right' },
+  { key: 'updatedAt', prop: 'updatedAt', label: '更新时间', minWidth: 150 },
+]
+
+async function loadWarehouses() {
+  if (!access.can(overseasWarehousePermissions.warehouseList)) return
+  contextLoading.value = true; loadError.value = null
+  try { warehouses.value = (await listReceivingOverseasWarehouses()).records }
+  catch (error) { loadError.value = getApiErrorDetails(error, '海外仓列表加载失败，请重试') }
+  finally { contextLoading.value = false }
+}
+
+function query() {
+  return { page: page.value, size: pageSize.value, customerName: String(filters.value.owner || '').trim() || undefined, overseasWarehouseId: String(filters.value.warehouseId || '') || undefined, skuCode: String(filters.value.sku || '').trim() || undefined, productName: String(filters.value.productName || '').trim() || undefined, batchNo: String(filters.value.batchNo || '').trim() || undefined, warehouseLocationCode: String(filters.value.location || '').trim() || undefined, inventoryStatus: String(filters.value.status || '') || undefined }
+}
+
+async function load(model: QueryModel = filters.value) {
+  Object.assign(filters.value, model)
+  loading.value = true; loadError.value = null
+  try { const [pageResult, summaryResult] = await Promise.all([listInventoryBalances(query()), getInventorySummary(query())]); rows.value = pageResult.records.map(toInventoryListItem); total.value = pageResult.total; summary.value = summaryResult }
+  catch (error) { rows.value = []; total.value = 0; summary.value = null; loadError.value = getApiErrorDetails(error, '库存数据加载失败，请重试') }
+  finally { loading.value = false }
+}
+
+function search(model: QueryModel) { page.value = 1; void load(model) }
+function openDetail(source: object) { const row = source as InventoryListItem; void router.push({ name: 'overseas-inventory-detail', params: { inventoryId: row.id }, query: { overseasWarehouseId: row.warehouseId, inboundOrderNo: row.inboundOrderNo, inboundCode: row.inboundCode, skuCode: row.sku === '—' ? undefined : row.sku.split('、')[0] } }) }
+async function exportBalances() { exportLoading.value = true; try { const q = query(); const { page: _page, size: _size, ...params } = q; saveCsv(await downloadInventoryBalances(params) as Blob, '库存余额.csv') } catch { ElMessage.error('库存导出失败，请重试') } finally { exportLoading.value = false } }
+onMounted(() => { void loadWarehouses(); void load() })
+</script>
+
+<template>
+  <AdminPage class="admin-density"><ListPageLayout aria-label="海外仓库存管理">
+    <template #toolbar><QueryToolbar v-model="filters" class="surface-panel" :fields="fields" :loading="loading || contextLoading" ariaLabel="库存筛选" preference-key="overseas-inventory-query" @search="search" @reset="page = 1; rows = []; total = 0; summary = null" /></template>
+    <template #metrics><section class="inventory-metrics" aria-label="库存汇总"><div v-for="metric in metrics" :key="metric[0]" class="inventory-metric" :class="`is-${metric[2]}`"><span>{{ metric[0] }}</span><strong>{{ metric[1] }}</strong></div></section></template>
+    <template v-if="loadError" #state><LoadErrorState title="库存数据加载失败" :message="loadError.message" :loading="loading || contextLoading" @retry="load"><template #details><ApiErrorMeta :details="loadError" /></template></LoadErrorState></template>
+    <section v-if="!loadError" class="surface-panel table-panel"><DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :loading="loading" :total="total" preference-key="overseas-inventory" row-key="id" empty-text="暂无库存记录" @update:page="load()" @update:page-size="page = 1; load()">
+      <template #toolbar-actions><el-button v-if="access.can(overseasWarehousePermissions.inventoryExport)" plain :loading="exportLoading" @click="exportBalances"><Download :size="16" />导出库存</el-button><el-button @click="router.push({ name: 'overseas-inventory-transactions' })"><BookOpen :size="16" />进销存记录</el-button></template>
+      <template #actions="{ row }"><div class="density-actions"><el-button class="density-action" data-tone="neutral" size="small" @click="openDetail(row)">查看</el-button></div></template>
+      <template #pagination-left>共 {{ total }} 条库存记录</template>
+    </DataTable></section>
+  </ListPageLayout></AdminPage>
+</template>
+
+<style scoped>
+.inventory-metrics { display: grid; grid-template-columns: repeat(6, minmax(130px, 1fr)); overflow: hidden; border: 1px solid var(--cc-border); border-radius: var(--admin-radius); background: #fff; }
+.inventory-metric:last-child { border-right: 0; }
+.inventory-metric span { color: #64748b; font-size: var(--admin-font-caption); }
+.inventory-metric.is-primary strong { color: var(--cc-primary); }
+.inventory-metric.is-success strong { color: #16a34a; }
+.inventory-metric.is-danger strong { color: #dc2626; }
+.inventory-metric.is-warning strong { color: #d97706; }
+
+.inventory-metric { display: flex; min-width: 0; flex-direction: row; gap: var(--admin-space-3); padding: var(--admin-space-3) var(--admin-space-5); border-right: 1px solid var(--cc-border); align-items: baseline; }
+.inventory-metric strong { color: #334155; font-size: var(--admin-font-body); line-height: 20px; overflow-wrap: anywhere; }
+
+</style>
diff --git a/src/modules/overseas-warehouse/pages/LastMileOrderDetailView.test.ts b/src/modules/overseas-warehouse/pages/LastMileOrderDetailView.test.ts
new file mode 100644
index 00000000..f06b7beb
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/LastMileOrderDetailView.test.ts
@@ -0,0 +1,58 @@
+import ElementPlus from 'element-plus'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { getLastMileOrder } from '../api/lastMileOrders'
+import LastMileOrderDetailView from './LastMileOrderDetailView.vue'
+
+const push = vi.hoisted(() => vi.fn())
+vi.mock('vue-router', () => ({ useRoute: () => ({ params: { orderId: 'internal-order-id' } }), useRouter: () => ({ push }) }))
+vi.mock('@/core/access/accessPreview', () => ({ useAccessPreviewStore: () => ({ can: () => false }) }))
+vi.mock('../api/lastMileOrders', () => ({ getLastMileOrder: vi.fn(), createLastMileOrderFee: vi.fn() }))
+enableAutoUnmount(afterEach)
+
+describe('LastMileOrderDetailView domestic detail alignment', () => {
+  beforeEach(() => {
+    push.mockReset()
+    vi.mocked(getLastMileOrder).mockResolvedValue({
+      order: { id: 'internal-order-id', customerId: 'customer-1', orderNo: 'FL-WH-001', currentStatus: 'PENDING_ASSIGNMENT', customerName: '示例客户', overseasWarehouseName: '洛杉矶仓', packageCount: 0, palletCount: 2, volumeCbm: 6.374, inboundCode: 'IN-001', containerNo: 'CONT-001', customerRemark: '完整保留客户备注', updatedAt: '2026-09-14T10:00:00' },
+      cargo: [{ id: 'cargo-1', skuCode: 'SKU-001', productNameZh: '测试货物' }], fees: [], statusHistory: [], operationHistory: [],
+    })
+  })
+
+  it('shows one business heading, a semantic status and summary without losing basic fields', async () => {
+    const wrapper = mount(LastMileOrderDetailView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(wrapper.findAll('h1')).toHaveLength(1)
+    expect(wrapper.get('h1').text()).toBe('FL-WH-001')
+    const header = wrapper.get('.density-detail-header')
+    expect(header.text()).not.toContain('尾程订单详情')
+    expect(header.text()).not.toContain('尾程单号')
+    expect(header.get('.status-badge').classes()).toContain('is-warning')
+    expect(header.get('.order-reference-text__copy').classes()).toContain('is-text')
+    const summary = wrapper.get('[aria-label="尾程订单概览"]')
+    expect(summary.findAll('dd').map(item => item.text())).toEqual(['示例客户', '洛杉矶仓', '0 箱', '2 托', '6.374 m³', expect.stringContaining('2026-09-14')])
+    const fields = wrapper.get('dl[aria-label="基本信息"]')
+    expect(fields.findAll('dt')).toHaveLength(20)
+    expect(fields.text()).toContain('CONT-001')
+    expect(fields.text()).toContain('完整保留客户备注')
+    expect(fields.findAll('.wide')).toHaveLength(3)
+    expect(wrapper.text()).not.toContain('internal-order-id')
+    await header.get('.density-back').trigger('click')
+    expect(push).toHaveBeenCalledWith({ name: 'overseas-last-mile-orders' })
+  })
+
+  it('keeps all five tab panels reachable after applying the shared tab style', async () => {
+    const wrapper = mount(LastMileOrderDetailView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    const tabs = wrapper.findAll('[role="tab"]')
+    expect(tabs.map(tab => tab.text())).toEqual(['📋基本信息', '📦货物信息', '🗓️计划信息', '💰费用明细', '📝操作记录'])
+    for (const [index, tab] of tabs.entries()) {
+      await tab.trigger('click')
+      await flushPromises()
+      expect(tab.attributes('aria-selected')).toBe('true')
+      const panel = wrapper.findAll('[role="tabpanel"]')[index]!
+      expect(panel.isVisible()).toBe(true)
+      if (index === 1) expect(panel.text()).toContain('SKU-001')
+    }
+  })
+})
diff --git a/src/modules/overseas-warehouse/pages/LastMileOrderDetailView.vue b/src/modules/overseas-warehouse/pages/LastMileOrderDetailView.vue
new file mode 100644
index 00000000..42c60d29
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/LastMileOrderDetailView.vue
@@ -0,0 +1,242 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, reactive, ref } from 'vue'
+import { Plus } from '@lucide/vue'
+import { ElMessage } from 'element-plus'
+import { useRoute, useRouter } from 'vue-router'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { listSuppliers, type Supplier } from '@/modules/suppliers'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import OperationErrorToast from '@/shared/components/OperationErrorToast.vue'
+import { createLastMileOrderFee, getLastMileOrder, type LastMileOrderDetailDto } from '../api/lastMileOrders'
+import { formatOverseasDateTime, lastMileOrderReference, lastMileOrderTypeLabel, lastMileStatusLabel } from '../lastMilePresentation'
+import { overseasWarehousePermissions as permission } from '../permissions'
+import OverseasDetailShell from '../components/OverseasDetailShell.vue'
+import OrderReferenceText from '../components/OrderReferenceText.vue'
+
+interface DetailField { label: string; value: string | number; wide?: boolean }
+interface CargoRow { id: string; sku: string; productName: string; pallets: number; cartons: number; quantity: number; weight: number; volume: number }
+interface DocumentRow { type: string; number: string; createdAt: string; quote: string }
+interface FeeRow { id: string; item: string; currency: string; amount: string; status: string; description: string }
+interface LogRow { id: string; occurredAt: string; node: string; operator: string; result: string; sortAt: string }
+
+const route = useRoute()
+const router = useRouter()
+const access = useAccessPreviewStore()
+const orderId = computed(() => String(route.params.orderId || ''))
+const detail = ref<LastMileOrderDetailDto | null>(null)
+const loading = ref(false)
+const saving = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const mutationError = ref<ApiErrorDetails | null>(null)
+const activeTab = ref('basic')
+const feeDialogOpen = ref(false)
+const supplierOptions = ref<Supplier[]>([])
+const feeForm = reactive({ itemCode: '', itemName: '', direction: 'RECEIVABLE' as 'RECEIVABLE' | 'PAYABLE', currency: 'USD' as 'CNY' | 'USD', amount: 0, businessDate: new Date().toISOString().slice(0, 10), supplierId: '', quantity: undefined as number | undefined, quantityUnit: '', periodStart: '', periodEnd: '' })
+const feeItemOptions = [{ code: 'STORAGE_FEE', name: '仓租' }, { code: 'INBOUND_OPERATION', name: '入库操作费' }, { code: 'OUTBOUND_OPERATION', name: '出库操作费' }, { code: 'RELABEL_FEE', name: '换标费' }, { code: 'REBOX_FEE', name: '换箱费' }, { code: 'PALLET_FEE', name: '托盘费' }, { code: 'DELIVERY_FEE', name: '派送费' }, { code: 'TRANSFER_FEE', name: '转仓费' }, { code: 'EXCEPTION_FEE', name: '异常处理费' }, { code: 'OTHER', name: '其他' }]
+
+function text(value: unknown) { return String(value ?? '').trim() || '—' }
+function containerNodeLabel(value: unknown) {
+  const code = String(value ?? '').trim()
+  return ({
+    DEPARTED_WAREHOUSE: '已离开国内仓库', AT_ORIGIN_PORT: '重箱已进入起运港',
+    LOADED_ON_VESSEL: '已装船', DEPARTED_ORIGIN_PORT: '船舶已离开起运港', IN_TRANSIT: '海运途中',
+    ARRIVED_DESTINATION_PORT: '船舶已到目的港', DISCHARGED_FROM_VESSEL: '已卸船、未清关',
+    PICKUP_READY: '已清关、可提柜', PICKED_UP: '已提柜', EMPTY_RETURNED: '已还柜',
+  } as Record<string, string>)[code] || text(code)
+}
+function yesNo(value: boolean | null | undefined) { return value == null ? '—' : value ? '是' : '否' }
+function feeStatusLabel(value: string) { return ({ PENDING_REVIEW: '待审核', APPROVED: '审核通过', REJECTED: '已驳回' } as Record<string, string>)[value] || value }
+function isSingleLineBusinessField(field: DetailField) { return field.label === '入仓码' || field.label === '集装箱号' }
+
+const referenceValue = computed(() => lastMileOrderReference(detail.value?.order.orderNo, '订单编码待补充'))
+const orderFields = computed<DetailField[]>(() => {
+  const order = detail.value?.order
+  return [
+    { label: '订单类型', value: text(order?.orderTypeName || lastMileOrderTypeLabel(order?.orderType)) },
+    { label: '入仓码', value: text(order?.inboundCode) },
+    { label: '货主', value: text(order?.customerName) },
+    { label: '海外仓', value: text(order?.overseasWarehouseName) },
+    { label: '转仓目的仓', value: text(order?.transferWarehouseName) },
+    { label: '目的仓', value: text(order?.fbaWarehouseCode || order?.transferWarehouseName) },
+    { label: '是否暂扣', value: yesNo(order?.detained) },
+    { label: '是否异常', value: yesNo(order?.abnormal) },
+    { label: '异常原因', wide: true, value: order?.abnormal ? text(order.subOrderStatus) : '—' },
+    { label: '仓库异常作业备注', wide: true, value: text(order?.warehouseRemark) },
+    { label: '备注（客户）', wide: true, value: text(order?.customerRemark) },
+  ]
+})
+const containerFields = computed<DetailField[]>(() => {
+  const order = detail.value?.order
+  return [
+    { label: '运输渠道', value: text(order?.orderTypeName || lastMileOrderTypeLabel(order?.orderType)) },
+    { label: '集装箱号', value: text(order?.containerNo) },
+    { label: '托数', value: Number(order?.palletCount || 0) },
+    { label: '箱数', value: Number(order?.packageCount || 0) },
+    { label: '体积（m³）', value: Number(order?.volumeCbm || 0) },
+    { label: '预计到港时间', value: formatOverseasDateTime(order?.estimatedArrivalAt) },
+    { label: '实际到港时间', value: formatOverseasDateTime(order?.actualArrivalAt) },
+    { label: '预计到仓时间', value: formatOverseasDateTime(order?.estimatedWarehouseAt) },
+    { label: '货柜节点', value: containerNodeLabel(order?.containerNode) },
+  ]
+})
+const basicFields = computed(() => [...orderFields.value, ...containerFields.value])
+const overviewFields = computed(() => {
+  const order = detail.value?.order
+  return [
+    { label: '客户', value: text(order?.customerName) },
+    { label: '海外仓', value: text(order?.overseasWarehouseName) },
+    { label: '总箱数', value: order?.packageCount == null ? '—' : order.packageCount + ' 箱' },
+    { label: '总托数', value: order?.palletCount == null ? '—' : order.palletCount + ' 托' },
+    { label: '体积', value: order?.volumeCbm == null ? '—' : order.volumeCbm + ' m³' },
+    { label: '最近更新', value: formatOverseasDateTime(order?.updatedAt) },
+  ]
+})
+const planFields = computed<DetailField[]>(() => {
+  const order = detail.value?.order
+  return [
+    { label: '入仓码', value: text(order?.inboundCode) },
+    { label: '计划入库仓', value: text(order?.transferWarehouseName || order?.overseasWarehouseName) },
+    { label: '合托批次', value: text(order?.palletMergeFlag) },
+    { label: '计划托数', value: Number(order?.palletCount || 0) },
+    { label: '入库单号', value: text(order?.inboundOrderNo) },
+    { label: '换标状态', value: lastMileStatusLabel(order?.relabelStatus) },
+  ]
+})
+const documents = computed<DocumentRow[]>(() => {
+  const order = detail.value?.order
+  if (!order) return []
+  return [['入库单', order.inboundOrderNo], ['出库单（只读关联）', order.outboundOrderNo], ['派送单（只读关联）', order.deliveryOrderNo], ['换标单', order.relabelOrderNo]]
+    .filter((item) => item[1]).map(([type, number]) => ({ type: String(type), number: String(number), createdAt: '—', quote: '—' }))
+})
+const cargo = computed<CargoRow[]>(() => (detail.value?.cargo || []).map((item) => ({
+  id: String(item.id), sku: text(item.skuCode), productName: text(item.productNameZh), pallets: Number(item.palletCount || 0),
+  cartons: Number(item.packageCount || 0), quantity: Number(item.productQuantity || 0), weight: Number(item.grossWeightKg || 0), volume: Number(item.volumeCbm || 0),
+})))
+const fees = computed<FeeRow[]>(() => (detail.value?.fees || []).map((item) => ({
+  id: String(item.id), item: item.feeItemName, currency: item.originalCurrency, amount: `${item.originalCurrency} ${Number(item.originalAmount).toFixed(2)}`,
+  status: feeStatusLabel(item.reviewStatus === 'PENDING' ? 'PENDING_REVIEW' : item.reviewStatus), description: text(item.supplierName || (item.chargeableQuantity == null ? null : `${item.chargeableQuantity} ${item.quantityUnit || ''}`)),
+})))
+const logs = computed<LogRow[]>(() => {
+  const statusRows = (detail.value?.statusHistory || []).map((item) => ({
+    id: `status-${item.id}`, occurredAt: formatOverseasDateTime(item.createdAt), sortAt: item.createdAt || '', node: lastMileStatusLabel(item.toStatus), operator: '系统',
+    result: text(item.remark || `${lastMileStatusLabel(item.fromStatus)} → ${lastMileStatusLabel(item.toStatus)}`),
+  }))
+  const operationRows = (detail.value?.operationHistory || []).map((item) => ({
+    id: `operation-${item.id}`, occurredAt: formatOverseasDateTime(item.createdAt), sortAt: item.createdAt || '', node: item.operationNode, operator: text(item.operatorName), result: text(item.result),
+  }))
+  return [...statusRows, ...operationRows].sort((left, right) => right.sortAt.localeCompare(left.sortAt))
+})
+
+const cargoColumns: DataTableColumn[] = [
+  { key: 'sku', prop: 'sku', label: 'SKU', minWidth: 150 }, { key: 'productName', prop: 'productName', label: '中文品名', minWidth: 180 },
+  { key: 'pallets', prop: 'pallets', label: '托数', width: 100, align: 'right' }, { key: 'cartons', prop: 'cartons', label: '箱数', width: 100, align: 'right' },
+  { key: 'quantity', prop: 'quantity', label: '件数', width: 100, align: 'right' }, { key: 'weight', prop: 'weight', label: '重量(kg)', width: 120, align: 'right' },
+  { key: 'volume', prop: 'volume', label: '体积(m³)', width: 120, align: 'right' },
+]
+const documentColumns: DataTableColumn[] = [
+  { key: 'type', prop: 'type', label: '单据类型', minWidth: 150 }, { key: 'number', prop: 'number', label: '单据编号', minWidth: 200 },
+  { key: 'createdAt', prop: 'createdAt', label: '生成时间', minWidth: 170 }, { key: 'quote', prop: 'quote', label: '报价', minWidth: 150 },
+]
+const feeColumns: DataTableColumn[] = [
+  { key: 'item', prop: 'item', label: '费用项目', minWidth: 180 }, { key: 'currency', prop: 'currency', label: '币种', width: 120 },
+  { key: 'amount', prop: 'amount', label: '金额', minWidth: 160 }, { key: 'status', prop: 'status', label: '状态', width: 140 },
+  { key: 'description', prop: 'description', label: '供应商/说明', minWidth: 260 },
+]
+const logColumns: DataTableColumn[] = [
+  { key: 'occurredAt', prop: 'occurredAt', label: '时间', minWidth: 180 }, { key: 'node', prop: 'node', label: '操作节点', minWidth: 180 },
+  { key: 'operator', prop: 'operator', label: '操作人', minWidth: 150 }, { key: 'result', prop: 'result', label: '处理结果', minWidth: 320 },
+]
+
+async function load() {
+  if (!orderId.value) { loadError.value = { message: '详情缺少尾程订单号' }; return }
+  loading.value = true; loadError.value = null
+  try { detail.value = await getLastMileOrder(orderId.value) }
+  catch (error) { loadError.value = error instanceof Error && error.message === '当前环境未签发海外访问令牌' ? { message: error.message } : getApiErrorDetails(error, '尾程订单详情加载失败，请重试') }
+  finally { loading.value = false }
+}
+async function openFeeDialog() {
+  Object.assign(feeForm, { itemCode: '', itemName: '', direction: 'RECEIVABLE', currency: 'USD', amount: 0, businessDate: new Date().toISOString().slice(0, 10), supplierId: '', quantity: undefined, quantityUnit: '', periodStart: '', periodEnd: '' })
+  mutationError.value = null; feeDialogOpen.value = true
+  if (access.can('platform:supplier:list') && supplierOptions.value.length === 0) {
+    try { supplierOptions.value = (await listSuppliers({ page: 1, size: 200, status: 'ACTIVE' })).records.filter((item) => item.status === 'ACTIVE') }
+    catch (error) { mutationError.value = getApiErrorDetails(error, '供应商列表加载失败') }
+  }
+}
+async function saveFee() {
+  if (!feeForm.itemCode || !feeForm.itemName.trim() || feeForm.amount <= 0 || !feeForm.businessDate) { ElMessage.warning('请填写费用项目、业务日期和大于 0 的金额'); return }
+  const supplier = supplierOptions.value.find((item) => String(item.id) === feeForm.supplierId)
+  if (feeForm.direction === 'PAYABLE' && !supplier) { ElMessage.warning('应付费用必须选择供应商'); return }
+  saving.value = true; mutationError.value = null
+  try {
+    await createLastMileOrderFee(orderId.value, { feeItemCode: feeForm.itemCode, feeItemName: feeForm.itemName.trim(), direction: feeForm.direction, currency: feeForm.currency, amount: feeForm.amount, businessDate: feeForm.businessDate, supplierId: supplier ? String(supplier.id) : undefined, supplierName: supplier?.name, supplierCategory: supplier?.category, settlementMode: supplier ? 'ON_ACCOUNT' : undefined, chargeableQuantity: feeForm.quantity, quantityUnit: feeForm.quantity == null ? undefined : feeForm.quantityUnit.trim(), unitPrice: feeForm.quantity ? feeForm.amount / feeForm.quantity : undefined, periodStart: feeForm.periodStart || undefined, periodEnd: feeForm.periodEnd || undefined })
+    feeDialogOpen.value = false; ElMessage.success('费用已提交财务审核'); await load(); activeTab.value = 'fees'
+  } catch (error) { mutationError.value = getApiErrorDetails(error, '费用新增失败，请重试') }
+  finally { saving.value = false }
+}
+function back() { void router.push({ name: 'overseas-last-mile-orders' }) }
+onMounted(load)
+</script>
+
+<template>
+  <OverseasDetailShell class="admin-density" dense title="尾程订单详情" reference-label="尾程单号" :reference-value="referenceValue" back-label="返回尾程订单" domain="尾程订单详情" :pending="false" :status-text="detail ? lastMileStatusLabel(detail.order.currentStatus) : '加载中'" @back="back">
+    <template #reference><OrderReferenceText :value="referenceValue" copyable compact /></template>
+    <template #overview>
+      <dl v-if="detail" class="density-detail-overview" aria-label="尾程订单概览">
+        <div v-for="field in overviewFields" :key="field.label"><dt>{{ field.label }}</dt><dd>{{ field.value }}</dd></div>
+      </dl>
+    </template>
+    <OperationErrorToast :details="mutationError" />
+    <LoadErrorState v-if="loadError" title="尾程订单详情加载失败" :message="loadError.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="loadError" /></template></LoadErrorState>
+    <section v-else v-loading="loading" class="detail-surface" :aria-busy="loading">
+      <el-tabs v-model="activeTab" class="detail-tabs density-element-tabs density-contained-tabs">
+        <el-tab-pane name="basic"><template #label><span class="density-tab-icon" aria-hidden="true">📋</span><span>基本信息</span></template>
+          <dl class="detail-fields density-fields" aria-label="基本信息">
+            <div v-for="field in basicFields" :key="field.label" :class="{ wide: field.wide }"><dt>{{ field.label }}</dt><dd :class="{ 'detail-field-value--business': isSingleLineBusinessField(field) }" :title="isSingleLineBusinessField(field) ? String(field.value) : undefined">{{ field.value }}</dd></div>
+          </dl>
+        </el-tab-pane>
+        <el-tab-pane name="cargo"><template #label><span class="density-tab-icon" aria-hidden="true">📦</span><span>货物信息</span></template><section class="table-panel"><DataTable :data="cargo" :columns="cargoColumns" column-settings-mode="hide" row-key="id" empty-text="暂无货物明细"></DataTable></section></el-tab-pane>
+        <el-tab-pane name="plan"><template #label><span class="density-tab-icon" aria-hidden="true">🗓️</span><span>计划信息</span></template>
+          <section class="info-panel plan-panel" aria-label="计划信息"><dl class="detail-fields plan-fields density-fields"><div v-for="field in planFields" :key="field.label"><dt>{{ field.label }}</dt><dd :class="{ 'detail-field-value--business': isSingleLineBusinessField(field) }" :title="isSingleLineBusinessField(field) ? String(field.value) : undefined">{{ field.value }}</dd></div></dl></section>
+          <section class="table-panel related-panel"><DataTable :data="documents" :columns="documentColumns" column-settings-mode="hide" empty-text="暂无关联单据"><template #toolbar-start><h2>关联单据</h2></template></DataTable></section>
+        </el-tab-pane>
+        <el-tab-pane name="fees"><template #label><span class="density-tab-icon" aria-hidden="true">💰</span><span>费用明细</span></template><section class="table-panel"><DataTable :data="fees" :columns="feeColumns" column-settings-mode="hide" row-key="id" empty-text="暂无费用明细"><template #toolbar-actions><el-button v-if="access.can(permission.lastMileOrderTransfer)" type="primary" @click="openFeeDialog"><Plus :size="16" />新增费用</el-button></template></DataTable></section></el-tab-pane>
+        <el-tab-pane name="logs"><template #label><span class="density-tab-icon" aria-hidden="true">📝</span><span>操作记录</span></template><section class="table-panel"><DataTable :data="logs" :columns="logColumns" column-settings-mode="hide" row-key="id" empty-text="暂无操作记录"></DataTable></section></el-tab-pane>
+      </el-tabs>
+    </section>
+    <AppDialog class="admin-density-dialog" v-model="feeDialogOpen" title="新增费用" width="min(720px, calc(100vw - 28px))" confirm-text="保存费用" :confirm-loading="saving" @confirm="saveFee">
+      <el-form class="fee-form density-form" label-position="top"><div class="fee-form-grid">
+         <el-form-item label="费用项目" required><el-select v-model="feeForm.itemCode" filterable allow-create clearable default-first-option placeholder="请选择或输入费用项目" @change="feeForm.itemName = feeItemOptions.find(item => item.code === feeForm.itemCode)?.name || String(feeForm.itemCode).trim()"><el-option v-for="item in feeItemOptions" :key="item.code" :label="item.name" :value="item.code" /></el-select></el-form-item>
+        <el-form-item label="收付方向" required><el-select v-model="feeForm.direction"><el-option label="应收客户" value="RECEIVABLE" /><el-option label="应付供应商" value="PAYABLE" /></el-select></el-form-item>
+        <el-form-item v-if="feeForm.direction === 'PAYABLE'" label="供应商" required><el-select v-model="feeForm.supplierId" filterable placeholder="请选择供应商"><el-option v-for="item in supplierOptions" :key="String(item.id)" :label="item.name" :value="String(item.id)" /></el-select></el-form-item>
+        <el-form-item label="业务日期" required><el-date-picker v-model="feeForm.businessDate" type="date" value-format="YYYY-MM-DD" /></el-form-item>
+        <el-form-item label="币种" required><el-select v-model="feeForm.currency" placeholder="请选择币种"><el-option label="USD" value="USD" /><el-option label="CNY" value="CNY" /></el-select></el-form-item>
+        <el-form-item label="金额" required><el-input-number v-model="feeForm.amount" :min="0" :precision="2" :step="10" controls-position="right" placeholder="请输入费用金额" /></el-form-item>
+         <el-form-item label="计费数量"><el-input-number v-model="feeForm.quantity" :min="0.0001" :precision="4" controls-position="right" placeholder="请输入计费数量" /></el-form-item><el-form-item label="计费单位"><el-input v-model="feeForm.quantityUnit" :disabled="feeForm.quantity == null" placeholder="如 箱、托、天、m³" /></el-form-item>
+        <el-form-item label="计费开始日期"><el-date-picker v-model="feeForm.periodStart" type="date" value-format="YYYY-MM-DD" placeholder="仓租等周期费用填写" /></el-form-item><el-form-item label="计费结束日期"><el-date-picker v-model="feeForm.periodEnd" type="date" value-format="YYYY-MM-DD" placeholder="仓租等周期费用填写" /></el-form-item>
+      </div></el-form>
+    </AppDialog>
+  </OverseasDetailShell>
+</template>
+
+<style scoped>
+.detail-fields > div.wide { grid-column: span 2; }
+.detail-field-value--business { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.plan-panel { margin-bottom: var(--admin-space-5); }
+.related-panel { margin-top: var(--admin-space-5); }
+.fee-form { min-width: 0; overflow-x: hidden; }
+.fee-form-grid { display: grid; min-width: 0; grid-template-columns: repeat(2, minmax(0, 1fr)); column-gap: var(--admin-space-5); }
+.fee-form-full { grid-column: 1 / -1; }
+.fee-form :deep(.el-select), .fee-form :deep(.el-input-number) { width: 100%; }
+@media (max-width: 1100px) { .plan-fields { grid-template-columns: repeat(2, minmax(0, 1fr)); } }
+@media (max-width: 720px) { .detail-tabs :deep(.el-tabs__header) { padding: 0 10px; } .detail-tabs :deep(.el-tabs__content) { padding: 12px; } .detail-tabs :deep(.el-tabs__item) { padding: 0 12px; } .detail-fields, .plan-fields, .fee-form-grid { grid-template-columns: 1fr; } .fee-form-full, .detail-fields > div.wide { grid-column: auto; } }
+
+.detail-surface { min-width: 0; min-height: 0; margin-top: 0; border: 0; border-radius: 0; background: #fff; overflow: hidden; }
+.info-panel, .table-panel { min-width: 0; border: 0; border-radius: 0; background: #fff; overflow: hidden; }
+.info-panel h2, .table-panel h2 { margin: 0; padding: 0 0 var(--admin-space-3); border-bottom: 0; color: var(--cc-text); font-size: var(--admin-font-section); }
+
+</style>
diff --git a/src/modules/overseas-warehouse/pages/LastMileOrdersView.behavior.test.ts b/src/modules/overseas-warehouse/pages/LastMileOrdersView.behavior.test.ts
new file mode 100644
index 00000000..6c076d5e
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/LastMileOrdersView.behavior.test.ts
@@ -0,0 +1,754 @@
+import ElementPlus from 'element-plus'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { createPinia } from 'pinia'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { ApiResponseError } from '@/shared/api/http'
+import DataTable from '@/shared/components/DataTable.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import QueryToolbar from '@/shared/components/QueryToolbar.vue'
+import { listAllPlatformWarehouses } from '@/modules/warehouses'
+import {
+  changeContainerReceivingWarehouse,
+  createManualInboundPlan,
+  convertLastMileContainerToInboundPlans,
+  getContainerInboundPlanPreview,
+  getContainerPlanProgress,
+  listContainerPlanProgress,
+  listLastMileOrders,
+  transferLastMileOrders,
+  getLastMileOrderManualNodes,
+  updateLastMileOrderHold,
+  updateLastMileOrderManualNodes,
+} from '../api/lastMileOrders'
+import LastMileOrdersView from './LastMileOrdersView.vue'
+
+const canAccess = vi.hoisted(() => vi.fn<(permissionCode: string) => boolean>(() => true))
+vi.mock('@/core/access/accessPreview', () => ({ useAccessPreviewStore: () => ({ can: canAccess }) }))
+vi.mock('vue-router', () => ({ useRouter: () => ({ push: vi.fn() }) }))
+vi.mock('@/modules/warehouses', () => ({ listAllPlatformWarehouses: vi.fn() }))
+vi.mock('../api/lastMileOrders', () => ({
+  listLastMileOrders: vi.fn(), listContainerPlanProgress: vi.fn(), getContainerPlanProgress: vi.fn(),
+  changeContainerReceivingWarehouse: vi.fn(),
+  createManualInboundPlan: vi.fn(), convertLastMileContainerToInboundPlans: vi.fn(), getContainerInboundPlanPreview: vi.fn(), transferLastMileOrders: vi.fn(),
+  getLastMileOrderManualNodes: vi.fn(), updateLastMileOrderHold: vi.fn(), updateLastMileOrderManualNodes: vi.fn(),
+  downloadLastMileOrders: vi.fn(),
+}))
+
+class ResizeObserverStub implements ResizeObserver { observe() {} unobserve() {} disconnect() {} }
+function memoryStorage(): Storage {
+  const values = new Map<string, string>()
+  return {
+    get length() { return values.size }, clear: () => values.clear(), getItem: (key) => values.get(key) ?? null,
+    key: (index) => [...values.keys()][index] ?? null, removeItem: (key) => values.delete(key), setItem: (key, value) => values.set(key, value),
+  }
+}
+
+const bookingId = '2092873463568597001'
+const customerId = '2092618717861048321'
+const summary = {
+  sourceContainerBookingId: bookingId, containerNo: 'CONT-15', totalOrderCount: 15,
+  overseasWarehouseId: '9007199254740995', overseasWarehouseCode: 'LAX01', overseasWarehouseName: '洛杉矶接柜仓',
+  assignmentVersion: 7, canChangeReceivingWarehouse: true, receivingWarehouseLockReason: null,
+  inboundCodeCount: 15, missingInboundCodeCount: 0, planCount: 10, plannedInboundCodeCount: 10,
+  pendingPlanCount: 5, resourcePendingPlanCount: 0, plannedArrivalAt: '2026-09-01T08:00:00', allPlansReady: false,
+  blockingReason: '存在5票尚未生成有效入库计划',
+}
+const fbaWarehouse = {
+  id: '9007199254740993', tenantId: '0', warehouseCode: 'ONT8', warehouseName: 'Ontario FBA',
+  warehouseType: 'FBA', countryCode: 'US', timezone: 'America/Los_Angeles', contactName: null,
+  contactPhone: null, contactEmail: null, status: 'ACTIVE', remark: null,
+  primaryAddress: {
+    id: '9007199254740994', tenantId: '0', warehouseId: '9007199254740993', addressType: 'OPERATING',
+    countryCode: 'US', stateProvince: 'CA', city: 'Ontario', district: null, postalCode: '91761',
+    addressLine1: 'FBA address', addressLine2: null, latitude: null, longitude: null,
+  },
+  addressSummary: 'CA Ontario',
+}
+const preview = {
+  sourceContainerBookingId: bookingId, containerNo: 'CONT-15',
+  overseasWarehouseId: summary.overseasWarehouseId, overseasWarehouseCode: summary.overseasWarehouseCode,
+  overseasWarehouseName: summary.overseasWarehouseName, snapshotVersion: 9, snapshotHash: 'a'.repeat(64),
+  totalOrderCount: 5, readyOrderCount: 5, blockedOrderCount: 0, pendingOrderCount: 5,
+  pendingPalletCount: 5, sourcePalletCount: 4, supplementPalletCount: 1,
+  existingPlannedPalletCount: 0, totalSuggestedPalletCount: 5,
+  totalPlannedPalletCount: 0, ready: true,
+  groups: [{
+    destinationType: 'FBA', destinationWarehouseId: null, destinationWarehouseCode: 'ONT8',
+    destinationWarehouseName: 'Ontario FBA', orderCount: 5, pendingOrderCount: 5, pendingPalletCount: 5,
+    sourcePalletCount: 4, supplementPalletCount: 1,
+    existingPlannedPalletCount: 0, suggestedPalletCount: 5, plannedPalletCount: 0,
+    orders: [{
+      customerId, customerName: '测试客户', orderId: '2092873463568596994', businessOrderNo: 'LMO-1',
+      inboundCode: 'IN-1', orderType: 'FIRST_LEG', destinationType: 'FBA', destinationWarehouseId: null,
+      destinationWarehouseCode: 'ONT8', destinationWarehouseName: 'Ontario FBA', packageCount: 10,
+      volumeCbm: 1, suggestedPalletCount: 5, sourcePalletCount: 4, targetPalletCount: 5,
+      supplementPalletCount: 1, plannedPalletCount: null, existingPlanNo: null,
+      planStatus: null, orderVersion: 3, readiness: 'READY', blockers: [],
+    }],
+  }],
+}
+const receivingWarehouse = {
+  ...fbaWarehouse,
+  id: '9007199254740996', warehouseCode: 'LAX02', warehouseName: '洛杉矶二号接柜仓', warehouseType: 'OVERSEAS',
+}
+const currentReceivingWarehouse = {
+  ...receivingWarehouse,
+  id: summary.overseasWarehouseId, warehouseCode: summary.overseasWarehouseCode, warehouseName: summary.overseasWarehouseName,
+}
+function selectedRow(overrides: Record<string, unknown> = {}) {
+  return {
+    id: '2092873463568596994', customerId, sourceContainerBookingId: bookingId, orderNo: 'LMO-260827-0001',
+    overseasWarehouseId: summary.overseasWarehouseId, overseasWarehouseCode: summary.overseasWarehouseCode,
+    warehouse: summary.overseasWarehouseName, inboundCode: 'IN-LOCKED', version: 3, pallets: 2,
+    estimatedWarehouseAt: '2026-09-01T08:00:00', warehouseEta: '2026-09-01 08:00',
+    ...overrides,
+  }
+}
+
+enableAutoUnmount(afterEach)
+afterAll(() => vi.unstubAllGlobals())
+
+async function mountView() {
+  const wrapper = mount(LastMileOrdersView, { attachTo: document.body, global: { plugins: [createPinia(), ElementPlus] } })
+  await flushPromises()
+  return wrapper
+}
+
+async function openPending() {
+  const wrapper = await mountView()
+  const pendingTab = wrapper.findAll('.el-radio-button').find((item) => item.text() === '待分配')
+  await pendingTab!.trigger('click')
+  await flushPromises()
+  return wrapper
+}
+
+async function openHiddenContainerWorkbench(wrapper: Awaited<ReturnType<typeof mountView>>) {
+  const view = wrapper.vm as unknown as {
+    statusTab: '全部' | '待分配' | '柜子'
+    changeStatusTab(): void
+  }
+  view.statusTab = '柜子'
+  view.changeStatusTab()
+  await flushPromises()
+}
+
+async function selectRows(wrapper: Awaited<ReturnType<typeof mountView>>, rows: object[]) {
+  wrapper.findComponent(DataTable).vm.$emit('selection-change', rows)
+  await wrapper.vm.$nextTick()
+}
+
+function button(wrapper: Awaited<ReturnType<typeof mountView>>, text: string) {
+  return wrapper.findAll('button').find((item) => item.text().includes(text))
+}
+
+async function openContainerDialog(wrapper: Awaited<ReturnType<typeof mountView>>) {
+  await button(wrapper, '按柜批量生成')!.trigger('click')
+  await flushPromises()
+}
+
+async function chooseContainer(wrapper: Awaited<ReturnType<typeof mountView>>) {
+  const selects = wrapper.findAllComponents({ name: 'ElSelect' })
+  const containerSelect = selects[selects.length - 1]
+  expect(containerSelect).toBeDefined()
+  containerSelect.vm.$emit('update:modelValue', bookingId)
+  containerSelect.vm.$emit('change', bookingId)
+  await flushPromises()
+  await wrapper.vm.$nextTick()
+}
+
+describe('LastMileOrdersView pending order and container conversion', () => {
+  it.each([
+    [[], ['查看'], false],
+    [['inbound-order:create'], ['查看', '入库计划'], false],
+    [['last-mile-order:edit'], ['查看', '暂扣订单', '人工修改节点'], false],
+    [['inbound-order:create', 'last-mile-order:edit'], ['查看', '入库计划', ''], true],
+  ])('only collapses row actions above three for %j', async (allowed, labels, overflow) => {
+    canAccess.mockImplementation(code => allowed.some(action => code === 'platform:overseas-warehouse:' + action))
+    vi.mocked(listLastMileOrders).mockResolvedValue({ records: [{ id: 'order-1', customerId, orderNo: 'LM-1', currentStatus: 'PENDING_ASSIGNMENT', orderType: 'FIRST_LEG' }], page: 1, size: 10, total: 1, pages: 1 })
+    const wrapper = await mountView()
+    const actions = wrapper.get('.el-table__body-wrapper .row-actions')
+    expect(actions.findAll('button').map(button => button.text().trim())).toEqual(labels)
+    expect(actions.find('.el-dropdown').exists()).toBe(overflow)
+  })
+
+  beforeEach(() => {
+    canAccess.mockReset().mockReturnValue(true)
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+    vi.stubGlobal('localStorage', memoryStorage())
+    vi.mocked(listLastMileOrders).mockReset().mockResolvedValue({ records: [], page: 1, size: 10, total: 0, pages: 0 })
+    vi.mocked(listContainerPlanProgress).mockReset().mockResolvedValue({ records: [summary], page: 1, size: 50, total: 1, pages: 1 })
+    vi.mocked(getContainerPlanProgress).mockReset().mockResolvedValue({
+      summary,
+      orders: [{ orderId: '2092873463568596994', customerId, orderNo: 'LMO-1', inboundCode: 'IN-1', orderStatus: 'INBOUND_PLANNED', planId: '2092873463568597010', planNo: 'LIP-1', planStatus: 'PENDING_RECEIVING', planValid: true, plannedArrivalAt: '2026-09-01T08:00:00' }],
+    })
+    vi.mocked(createManualInboundPlan).mockReset().mockResolvedValue({} as never)
+    vi.mocked(getContainerInboundPlanPreview).mockReset().mockResolvedValue(preview as never)
+    vi.mocked(getLastMileOrderManualNodes).mockReset().mockResolvedValue({ orderId: '2092873463568596994', manualOverrideEnabled: false, nodes: [], version: 0 })
+    vi.mocked(updateLastMileOrderHold).mockReset().mockResolvedValue({ orderId: '2092873463568596994', held: true, chargeable: true, version: 1 })
+    vi.mocked(updateLastMileOrderManualNodes).mockReset().mockResolvedValue({ orderId: '2092873463568596994', manualOverrideEnabled: true, nodes: [], version: 1 })
+    vi.mocked(convertLastMileContainerToInboundPlans).mockReset().mockResolvedValue([
+      { planNo: 'LIP-1', pallets: [{ id: 'PALLET-1', palletNo: 'PLT-001' }] },
+      { planNo: 'LIP-2', pallets: [{ id: 'PALLET-2', palletNo: 'PLT-002' }] },
+    ] as never)
+    vi.mocked(changeContainerReceivingWarehouse).mockReset().mockResolvedValue({ ...summary, overseasWarehouseId: '9007199254740996', overseasWarehouseCode: 'LAX02', overseasWarehouseName: '洛杉矶二号接柜仓', assignmentVersion: 8 })
+    vi.mocked(listAllPlatformWarehouses).mockReset().mockResolvedValue([fbaWarehouse] as never)
+    vi.mocked(transferLastMileOrders).mockReset().mockResolvedValue(2)
+  })
+
+  it('keeps the original pending order table and does not render a view switch or container table', async () => {
+    const wrapper = await openPending()
+    expect(wrapper.text()).toContain('尾程单号')
+    expect(wrapper.text()).toContain('海外仓')
+    expect(wrapper.text()).toContain('转仓')
+    expect(wrapper.text()).toContain('生成入库计划')
+    expect(wrapper.text()).toContain('按柜批量生成')
+    expect(wrapper.text()).not.toContain('按订单')
+    expect(wrapper.text()).not.toContain('待分配整柜')
+    expect(wrapper.text()).not.toContain('柜子工作台')
+    expect(listLastMileOrders).toHaveBeenLastCalledWith(expect.objectContaining({ page: 1, size: 10, currentStatus: 'PENDING_ASSIGNMENT' }))
+    expect(listContainerPlanProgress).not.toHaveBeenCalled()
+  })
+
+  it('forwards complete searches and switches every status tab without stale filter failures', async () => {
+    const wrapper = await mountView()
+    const toolbar = wrapper.findComponent(QueryToolbar)
+    const model = {
+      orderNo: 'LMO-SEARCH', inboundCode: 'IN-SEARCH', lxCode: 'LX-SEARCH', orderType: 'FIRST_LEG',
+      warehouse: 'LAX', sourceOrderNo: 'SOURCE-SEARCH', containerNo: 'CONT-SEARCH', transferWarehouseCode: 'ONT8',
+      status: 'DELIVERED', abnormal: 'true', detained: 'false', createdAt: ['2026-09-01', '2026-09-07'],
+    }
+    toolbar.vm.$emit('search', model)
+    await flushPromises()
+    expect(listLastMileOrders).toHaveBeenLastCalledWith({
+      page: 1, size: 10, orderNo: 'LMO-SEARCH', inboundCode: 'IN-SEARCH', lxCode: 'LX-SEARCH', orderType: 'FIRST_LEG',
+      warehouse: 'LAX', sourceOrderNo: 'SOURCE-SEARCH', containerNo: 'CONT-SEARCH', transferWarehouseCode: 'ONT8',
+      currentStatus: 'DELIVERED', abnormal: true, detained: false,
+      createdFrom: '2026-09-01T00:00:00', createdTo: '2026-09-07T23:59:59',
+    })
+    const availableFields = toolbar.props('availableFields') as Array<{ key: string; label: string; placeholder?: string }>
+    expect(availableFields.find((field) => field.key === 'lxCode')).toMatchObject({
+      label: 'LX代码', placeholder: '请输入LX代码',
+    })
+    expect(availableFields.map((field) => field.key)).not.toEqual(expect.arrayContaining(['planNo', 'inboundOrderNo']))
+
+    await wrapper.findAll('.el-radio-button').find((item) => item.text() === '待分配')!.trigger('click')
+    await flushPromises()
+    expect(listLastMileOrders).toHaveBeenLastCalledWith(expect.objectContaining({ currentStatus: 'PENDING_ASSIGNMENT', lxCode: 'LX-SEARCH' }))
+
+    await openHiddenContainerWorkbench(wrapper)
+    expect(listContainerPlanProgress).toHaveBeenLastCalledWith({
+      page: 1, size: 10, containerNo: 'CONT-SEARCH',
+      createdFrom: '2026-09-01T00:00:00', createdTo: '2026-09-07T23:59:59',
+    })
+
+    await wrapper.findAll('.el-radio-button').find((item) => item.text() === '全部')!.trigger('click')
+    await flushPromises()
+    expect(listLastMileOrders).toHaveBeenLastCalledWith(expect.objectContaining({ currentStatus: 'DELIVERED', lxCode: 'LX-SEARCH' }))
+
+    const callsBeforeReset = vi.mocked(listLastMileOrders).mock.calls.length
+    ;(toolbar.vm as unknown as { reset(): void }).reset()
+    await flushPromises()
+    expect(vi.mocked(listLastMileOrders).mock.calls).toHaveLength(callsBeforeReset + 1)
+    expect(listLastMileOrders).toHaveBeenLastCalledWith(expect.objectContaining({ page: 1 }))
+    expect(vi.mocked(listLastMileOrders).mock.calls.at(-1)?.[0].lxCode).toBeUndefined()
+    expect(wrapper.text()).not.toContain('尾程订单加载失败')
+  })
+
+  it('opens the required single-order inbound-plan form without invoking the cabinet conversion', async () => {
+    const wrapper = await openPending()
+    await selectRows(wrapper, [selectedRow()])
+    await button(wrapper, '生成入库计划')!.trigger('click')
+    await flushPromises()
+    expect(document.body.textContent).toContain('计划入库仓')
+    expect(document.body.textContent).toContain('预计到仓时间')
+    expect(document.body.textContent).toContain('托盘类型')
+    const inboundCodeInput = wrapper.findAllComponents({ name: 'ElInput' })
+      .find((input) => input.props('placeholder') === '订单冻结入仓码')
+    expect(inboundCodeInput?.props('disabled')).toBe(true)
+    const receivingWarehouseInput = wrapper.findAllComponents({ name: 'ElInput' })
+      .find((input) => input.props('placeholder') === '当前柜接柜仓')
+    expect(receivingWarehouseInput?.props('disabled')).toBe(true)
+    expect(receivingWarehouseInput?.props('modelValue')).toBe('LAX01 · 洛杉矶接柜仓')
+    const expectedArrivalInput = wrapper.findAllComponents({ name: 'ElInput' })
+      .find((input) => input.props('placeholder') === '当前柜预计到仓时间')
+    expect(expectedArrivalInput?.props('disabled')).toBe(true)
+    expect(expectedArrivalInput?.props('modelValue')).toBe('2026-09-01 08:00')
+    expect(document.body.textContent).toContain('同柜所有入库计划保持一致')
+    expect(document.body.textContent).toContain('接柜仓按柜统一')
+    expect(listAllPlatformWarehouses).not.toHaveBeenCalled()
+    expect(createManualInboundPlan).not.toHaveBeenCalled()
+    expect(convertLastMileContainerToInboundPlans).not.toHaveBeenCalled()
+    expect(listContainerPlanProgress).not.toHaveBeenCalled()
+  })
+
+  it('shows cabinet-frozen facts but never sends arrival time or per-order warehouse overrides', async () => {
+    const wrapper = await openPending()
+    await selectRows(wrapper, [selectedRow()])
+    await button(wrapper, '生成入库计划')!.trigger('click')
+    await flushPromises()
+    const confirm = [...document.body.querySelectorAll('button')]
+      .find((item) => item.textContent?.includes('保存并生成入库单')) as HTMLButtonElement
+    confirm.click()
+    await flushPromises()
+
+    expect(createManualInboundPlan).toHaveBeenCalledWith(expect.objectContaining({
+      customerId, orderId: '2092873463568596994', expectedOrderVersion: 3,
+      palletCount: 5, palletType: 'WOOD',
+    }), expect.stringContaining('manual-inbound-plan-'))
+    const payload = vi.mocked(createManualInboundPlan).mock.calls[0][0] as unknown as Record<string, unknown>
+    expect(payload).not.toHaveProperty('inboundCode')
+    expect(payload).not.toHaveProperty('plannedArrivalDate')
+    expect(payload).not.toHaveProperty('plannedWarehouseId')
+    expect(payload).not.toHaveProperty('plannedWarehouseCode')
+    expect(payload).not.toHaveProperty('plannedWarehouseName')
+  })
+
+  it('blocks manual plan creation when the cabinet has no frozen expected arrival time', async () => {
+    const wrapper = await openPending()
+    await selectRows(wrapper, [selectedRow({ estimatedWarehouseAt: '', warehouseEta: '—' })])
+    await button(wrapper, '生成入库计划')!.trigger('click')
+    await flushPromises()
+
+    const confirm = [...document.body.querySelectorAll('button')]
+      .find((item) => item.textContent?.includes('保存并生成入库单')) as HTMLButtonElement
+    expect(confirm.disabled).toBe(true)
+    expect(createManualInboundPlan).not.toHaveBeenCalled()
+  })
+
+  it('locks one-click dropship manual plans to the frozen source pallet count', async () => {
+    vi.mocked(getContainerInboundPlanPreview).mockResolvedValue({
+      ...preview,
+      sourcePalletCount: 1,
+      groups: [{
+        ...preview.groups[0], destinationType: 'ONE_CLICK_DROPSHIP', sourcePalletCount: 1,
+        orders: [{
+          ...preview.groups[0].orders[0], orderType: 'ONE_CLICK_DROPSHIP',
+          destinationType: 'ONE_CLICK_DROPSHIP', sourcePalletCount: 1,
+          targetPalletCount: 1, supplementPalletCount: 0,
+        }],
+      }],
+    } as never)
+    const wrapper = await openPending()
+    await selectRows(wrapper, [selectedRow({ orderTypeCode: 'ONE_CLICK_DROPSHIP', pallets: 2 })])
+    await button(wrapper, '生成入库计划')!.trigger('click')
+    await flushPromises()
+
+    const palletInput = wrapper.find('.command-form').findComponent({ name: 'ElInputNumber' })
+    expect(palletInput.props('disabled')).toBe(true)
+    expect(palletInput.props('modelValue')).toBe(1)
+    expect(document.body.textContent).toContain('固定按头程已封托托盘数整体入库')
+
+    ;([...document.body.querySelectorAll('button')]
+      .find((item) => item.textContent?.includes('保存并生成入库单')) as HTMLButtonElement).click()
+    await flushPromises()
+
+    expect(createManualInboundPlan).toHaveBeenCalledWith(expect.objectContaining({ palletCount: 1 }),
+      expect.stringContaining('manual-inbound-plan-'))
+  })
+
+  it('opens a cabinet selector without requiring order selection and loads server summaries only then', async () => {
+    const wrapper = await openPending()
+    await openContainerDialog(wrapper)
+    expect(listContainerPlanProgress).toHaveBeenCalledTimes(1)
+    expect(listContainerPlanProgress).toHaveBeenCalledWith({ page: 1, size: 50, containerNo: undefined })
+    expect(document.body.textContent).toContain('选择待分配柜')
+    expect(document.body.textContent).toContain('确认后整柜只提交一次生成命令')
+    expect(getContainerInboundPlanPreview).not.toHaveBeenCalled()
+    expect(convertLastMileContainerToInboundPlans).not.toHaveBeenCalled()
+  })
+
+  it('selects one cabinet and sends one long-id convert-container request without using current-page row counts', async () => {
+    const wrapper = await openPending()
+    await openContainerDialog(wrapper)
+    await chooseContainer(wrapper)
+    const confirm = [...document.body.querySelectorAll('button')].find((item) => item.textContent?.includes('确认生成')) as HTMLButtonElement
+    expect(confirm.disabled).toBe(false)
+    confirm.click()
+    await flushPromises()
+    expect(convertLastMileContainerToInboundPlans).toHaveBeenCalledTimes(1)
+    expect(getContainerInboundPlanPreview).toHaveBeenCalledTimes(2)
+    expect(getContainerInboundPlanPreview).toHaveBeenNthCalledWith(1, bookingId)
+    expect(getContainerInboundPlanPreview).toHaveBeenNthCalledWith(2, bookingId)
+    expect(convertLastMileContainerToInboundPlans).toHaveBeenCalledWith({
+      sourceContainerBookingId: bookingId,
+      snapshotVersion: 9,
+      snapshotHash: 'a'.repeat(64),
+    }, expect.stringContaining('container-inbound-plan-'))
+    expect(createManualInboundPlan).not.toHaveBeenCalled()
+    expect(document.body.textContent).toContain('新建 2 个 / 已有 0 个')
+    expect(document.body.textContent).toContain('PLT-001')
+    expect(listLastMileOrders).toHaveBeenCalledTimes(3)
+  })
+
+  it.each(['A0404', 'A0409'])('keeps %s request evidence visible after cabinet conversion failure', async (code) => {
+    vi.mocked(convertLastMileContainerToInboundPlans).mockRejectedValueOnce(new ApiResponseError(
+      '柜级生成失败', code, 200, undefined, `request-${code}`, `trace-${code}`,
+    ))
+    const wrapper = await openPending()
+    await openContainerDialog(wrapper)
+    await chooseContainer(wrapper)
+    const confirm = [...document.body.querySelectorAll('button')].find((item) => item.textContent?.includes('确认生成')) as HTMLButtonElement
+    confirm.click()
+    await flushPromises()
+    expect(convertLastMileContainerToInboundPlans).toHaveBeenCalledTimes(1)
+    expect(wrapper.text()).toContain(code)
+    expect(wrapper.text()).toContain(`request-${code}`)
+    expect(wrapper.text()).toContain(`trace-${code}`)
+  })
+
+  it('keeps the latest cabinet preview when an older request resolves last', async () => {
+    let resolveFirst!: (value: typeof preview) => void
+    let resolveSecond!: (value: typeof preview) => void
+    vi.mocked(getContainerInboundPlanPreview).mockImplementation((id) => new Promise((resolve) => {
+      if (id === bookingId) resolveFirst = resolve
+      else resolveSecond = resolve
+    }) as never)
+    const wrapper = await openPending()
+    await openContainerDialog(wrapper)
+    const selects = wrapper.findAllComponents({ name: 'ElSelect' })
+    const containerSelect = selects[selects.length - 1]
+    containerSelect.vm.$emit('update:modelValue', bookingId)
+    containerSelect.vm.$emit('change', bookingId)
+    await wrapper.vm.$nextTick()
+    containerSelect.vm.$emit('update:modelValue', '2092873463568597002')
+    containerSelect.vm.$emit('change', '2092873463568597002')
+    await wrapper.vm.$nextTick()
+    resolveSecond({ ...preview, sourceContainerBookingId: '2092873463568597002', containerNo: 'CONT-NEW', pendingPalletCount: 2 })
+    await flushPromises()
+    expect(document.body.querySelector('.container-preview__identity')?.textContent).toContain('CONT-NEW')
+    resolveFirst(preview)
+    await flushPromises()
+    expect(document.body.querySelector('.container-preview__identity')?.textContent).toContain('CONT-NEW')
+  })
+
+  it('reuses the same idempotency key when an uncertain confirmation is retried', async () => {
+    vi.mocked(convertLastMileContainerToInboundPlans)
+      .mockRejectedValueOnce(new Error('network uncertain'))
+      .mockResolvedValueOnce([{ planNo: 'LIP-RETRY', pallets: [{ id: 'PALLET-R', palletNo: 'PLT-RETRY' }] }] as never)
+    const wrapper = await openPending()
+    await openContainerDialog(wrapper)
+    await chooseContainer(wrapper)
+    const findConfirm = () => [...document.body.querySelectorAll('button')]
+      .find((item) => item.textContent?.includes('确认生成')) as HTMLButtonElement
+    findConfirm().click()
+    await flushPromises()
+    findConfirm().click()
+    await flushPromises()
+    expect(convertLastMileContainerToInboundPlans).toHaveBeenCalledTimes(2)
+    expect(vi.mocked(convertLastMileContainerToInboundPlans).mock.calls[0][1]).toBe(
+      vi.mocked(convertLastMileContainerToInboundPlans).mock.calls[1][1],
+    )
+    expect(document.body.textContent).toContain('PLT-RETRY')
+  })
+
+  it('renders all cabinets as an arrival-ordered workbench with the remaining inbound-code count', async () => {
+    const nullArrival = { ...summary, sourceContainerBookingId: '2092873463568597002', containerNo: 'CONT-NULL', plannedArrivalAt: null, planCount: 0, pendingPlanCount: 15 }
+    vi.mocked(listContainerPlanProgress).mockResolvedValueOnce({ records: [summary, nullArrival], page: 1, size: 10, total: 2, pages: 1 })
+    const wrapper = await mountView()
+    await openHiddenContainerWorkbench(wrapper)
+    expect(listContainerPlanProgress).toHaveBeenLastCalledWith({ page: 1, size: 10, containerNo: undefined, createdFrom: undefined, createdTo: undefined })
+    expect(wrapper.text()).not.toContain('柜子工作台（2）')
+    expect(wrapper.text()).toContain('货柜工作台')
+    expect(wrapper.text()).toContain('按柜查看和修改海外接柜仓；整柜计划齐全后自动生成托盘码')
+    expect(wrapper.text()).toContain('5个入仓码待生成计划')
+    expect(wrapper.text()).toContain('共 15 个入仓码')
+    expect(wrapper.text()).not.toContain('待补入仓码')
+    expect(wrapper.text()).not.toContain('缺入仓码')
+    expect(wrapper.text()).not.toContain('已生成 10 个计划')
+    expect(wrapper.text()).not.toContain('存在5票尚未生成有效入库计划')
+    expect(wrapper.text()).toContain('2 个货柜')
+    expect(wrapper.text().indexOf('CONT-15')).toBeLessThan(wrapper.text().indexOf('CONT-NULL'))
+  })
+
+  it('presents a resource-pending cabinet as an exceptional pallet-code retry', async () => {
+    const ready = {
+      ...summary,
+      planCount: summary.inboundCodeCount,
+      plannedInboundCodeCount: summary.inboundCodeCount,
+      pendingPlanCount: 0,
+      resourcePendingPlanCount: 1,
+      allPlansReady: true,
+      blockingReason: null,
+    }
+    vi.mocked(listContainerPlanProgress).mockResolvedValueOnce({ records: [ready], page: 1, size: 10, total: 1, pages: 1 })
+    const wrapper = await mountView()
+    await openHiddenContainerWorkbench(wrapper)
+    expect(wrapper.text()).toContain('CONT-15')
+    expect(wrapper.text()).toContain('0个入仓码待生成计划')
+    expect(wrapper.text()).toContain('托盘码自动生成异常，可重试')
+    expect(wrapper.text()).not.toContain('待补真实托盘')
+    expect((button(wrapper, '重试生成托盘码')!.element as HTMLButtonElement).disabled).toBe(false)
+    expect((button(wrapper, '修改接柜仓')!.element as HTMLButtonElement).disabled).toBe(false)
+  })
+
+  it('renders the all-cabinet empty state and unit', async () => {
+    vi.mocked(listContainerPlanProgress).mockResolvedValueOnce({ records: [], page: 1, size: 10, total: 0, pages: 0 })
+    const wrapper = await mountView()
+    await openHiddenContainerWorkbench(wrapper)
+    expect(wrapper.text()).toContain('暂无货柜数据')
+    expect(wrapper.text()).not.toContain('已全部生成计划的柜不再展示')
+  })
+
+  it('uses independent cabinet pagination and opens the complete long-id detail in a dialog', async () => {
+    vi.mocked(listContainerPlanProgress).mockResolvedValue({ records: [summary], page: 1, size: 10, total: 21, pages: 3 })
+    const wrapper = await mountView()
+    await openHiddenContainerWorkbench(wrapper)
+    const pagination = wrapper.findComponent({ name: 'ElPagination' })
+    pagination.vm.$emit('current-change', 2)
+    await flushPromises()
+    expect(listContainerPlanProgress).toHaveBeenLastCalledWith(expect.objectContaining({ page: 2, size: 10 }))
+    await wrapper.get('.container-workbench-card__detail').trigger('click')
+    await flushPromises()
+    expect(getContainerPlanProgress).toHaveBeenCalledWith(bookingId)
+    expect(document.body.textContent).toContain('柜子详情 · CONT-15')
+    expect(document.body.textContent).toContain('LMO-1')
+    expect(document.body.textContent).toContain('IN-1')
+    expect(document.body.textContent).toContain('LIP-1')
+    expect(document.body.textContent).toContain('已生成入库计划')
+    expect(document.body.textContent).toContain('待收货')
+    expect(document.body.textContent).not.toContain('INBOUND_PLANNED')
+    expect(document.body.textContent).not.toContain('PENDING_RECEIVING')
+    expect(document.body.querySelector('.el-dialog')).not.toBeNull()
+    expect(document.body.querySelector('.el-drawer')).toBeNull()
+  })
+
+  it('starts cabinet plan generation directly from the workbench card', async () => {
+    const wrapper = await mountView()
+    await openHiddenContainerWorkbench(wrapper)
+    await button(wrapper, '生成入库计划')!.trigger('click')
+    await flushPromises()
+    expect(document.body.textContent).toContain('头程已有 4 个托盘码，海外仓补充 1 个，最终生成 5 个托盘')
+    expect(document.body.textContent).toContain('头程已有 4 托 / 海外仓补充 1 托')
+    const confirm = [...document.body.querySelectorAll('button')].find((item) => item.textContent?.includes('确认生成')) as HTMLButtonElement
+    expect(confirm.disabled).toBe(false)
+    confirm.click()
+    await flushPromises()
+    expect(convertLastMileContainerToInboundPlans).toHaveBeenCalledWith({
+      sourceContainerBookingId: bookingId,
+      snapshotVersion: 9,
+      snapshotHash: 'a'.repeat(64),
+    }, expect.stringContaining('container-inbound-plan-'))
+    expect(getContainerPlanProgress).not.toHaveBeenCalled()
+  })
+
+  it('keeps an invalid historical cabinet readable while blocking plan generation', async () => {
+    const invalid = {
+      ...summary,
+      overseasWarehouseId: null,
+      overseasWarehouseCode: null,
+      overseasWarehouseName: null,
+      blockingReason: '柜内接柜仓业务快照不一致',
+    }
+    vi.mocked(listContainerPlanProgress).mockResolvedValueOnce({ records: [invalid], page: 1, size: 10, total: 1, pages: 1 } as never)
+    vi.mocked(getContainerPlanProgress).mockResolvedValueOnce({ summary: invalid, orders: [] } as never)
+    const wrapper = await mountView()
+    await openHiddenContainerWorkbench(wrapper)
+
+    expect(wrapper.text()).toContain('柜内接柜仓业务快照不一致')
+    expect((button(wrapper, '生成入库计划')!.element as HTMLButtonElement).disabled).toBe(true)
+    await wrapper.get('.container-workbench-card__detail').trigger('click')
+    await flushPromises()
+    expect(getContainerPlanProgress).toHaveBeenCalledWith(bookingId)
+    expect(document.body.textContent).toContain('柜子详情 · CONT-15')
+    expect(convertLastMileContainerToInboundPlans).not.toHaveBeenCalled()
+  })
+
+  it('shows the receiving warehouse and changes it from ACTIVE OVERSEAS master data with versioning', async () => {
+    vi.mocked(listAllPlatformWarehouses).mockResolvedValueOnce([currentReceivingWarehouse, receivingWarehouse] as never)
+    const wrapper = await mountView()
+    await openHiddenContainerWorkbench(wrapper)
+    expect(wrapper.text()).toContain('海外接柜仓')
+    expect(wrapper.text()).toContain('LAX01 · 洛杉矶接柜仓')
+    expect(wrapper.get('.container-workbench-card__warehouse strong').attributes('title')).toBe('LAX01 · 洛杉矶接柜仓')
+    expect(listAllPlatformWarehouses).not.toHaveBeenCalled()
+    await button(wrapper, '修改接柜仓')!.trigger('click')
+    await flushPromises()
+    const receivingDialog = wrapper.findAllComponents(AppDialog).find((item) => item.props('title') === '修改海外接柜仓')!
+    expect(receivingDialog.props('width')).toBe('min(600px, calc(100vw - 28px))')
+    expect(listAllPlatformWarehouses).toHaveBeenLastCalledWith({ warehouseType: 'OVERSEAS', status: 'ACTIVE' })
+    expect(listAllPlatformWarehouses).toHaveBeenCalledTimes(1)
+    const warehouseSelect = wrapper.findAllComponents({ name: 'ElSelect' }).find((item) => item.props('placeholder') === '请选择 ACTIVE 海外接柜仓')!
+    expect(warehouseSelect.props('modelValue')).toBe('')
+    expect(wrapper.text()).not.toContain('9007199254740995')
+    const warehouseOptions = wrapper.findAllComponents({ name: 'ElOption' })
+    expect(warehouseOptions.find((item) => item.props('value') === summary.overseasWarehouseId)?.props('disabled')).toBe(true)
+    const confirm = [...document.body.querySelectorAll('button')].find((item) => item.textContent?.includes('确认修改')) as HTMLButtonElement
+    warehouseSelect.vm.$emit('update:modelValue', summary.overseasWarehouseId)
+    await wrapper.vm.$nextTick()
+    expect(confirm.disabled).toBe(true)
+    expect(wrapper.text()).toContain('新的海外接柜仓必须与当前仓不同')
+    warehouseSelect.vm.$emit('update:modelValue', '9007199254740996')
+    await wrapper.vm.$nextTick()
+    expect(confirm.disabled).toBe(false)
+    confirm.click()
+    await flushPromises()
+    expect(changeContainerReceivingWarehouse).toHaveBeenCalledWith(bookingId, {
+      overseasWarehouseId: '9007199254740996', expectedVersion: 7, remark: undefined,
+    }, expect.stringMatching(/^container-receiving-warehouse-/))
+    expect(listContainerPlanProgress).toHaveBeenCalledTimes(2)
+  })
+
+  it('keeps the receiving-warehouse confirmation disabled while candidates are loading', async () => {
+    let resolveCandidates!: (value: typeof receivingWarehouse[]) => void
+    vi.mocked(listAllPlatformWarehouses).mockReturnValueOnce(new Promise((resolve) => { resolveCandidates = resolve }) as never)
+    const wrapper = await mountView()
+    await openHiddenContainerWorkbench(wrapper)
+    await button(wrapper, '修改接柜仓')!.trigger('click')
+    await wrapper.vm.$nextTick()
+    const confirm = [...document.body.querySelectorAll('button')].find((item) => item.textContent?.includes('确认修改')) as HTMLButtonElement
+    expect(confirm.disabled).toBe(true)
+    expect(listAllPlatformWarehouses).toHaveBeenCalledTimes(1)
+    resolveCandidates([receivingWarehouse])
+    await flushPromises()
+    expect(confirm.disabled).toBe(true)
+  })
+
+  it('keeps a disabled receiving-warehouse action discoverable when the server locks the container', async () => {
+    vi.mocked(listContainerPlanProgress).mockResolvedValueOnce({
+      records: [{ ...summary, canChangeReceivingWarehouse: false, receivingWarehouseLockReason: '海外仓已开始拆柜收货' }],
+      page: 1, size: 10, total: 1, pages: 1,
+    })
+    const wrapper = await mountView()
+    await openHiddenContainerWorkbench(wrapper)
+    expect(wrapper.text()).toContain('海外仓已开始拆柜收货')
+    const changeButton = button(wrapper, '修改接柜仓')!
+    expect(changeButton.exists()).toBe(true)
+    expect((changeButton.element as HTMLButtonElement).disabled).toBe(true)
+    expect(changeButton.attributes('title')).toBe('海外仓已开始拆柜收货')
+    expect(changeContainerReceivingWarehouse).not.toHaveBeenCalled()
+  })
+
+  it('keeps a disabled receiving-warehouse action discoverable without edit permission', async () => {
+    canAccess.mockImplementation((permissionCode: string) => permissionCode !== 'platform:overseas-warehouse:last-mile-order:edit')
+    const wrapper = await mountView()
+    await openHiddenContainerWorkbench(wrapper)
+    const changeButton = button(wrapper, '修改接柜仓')!
+    expect(changeButton.exists()).toBe(true)
+    expect((changeButton.element as HTMLButtonElement).disabled).toBe(true)
+    expect(changeButton.attributes('title')).toBe('暂无修改接柜仓权限，请联系管理员开通尾程订单编辑权限')
+    await changeButton.trigger('click')
+    expect(listAllPlatformWarehouses).not.toHaveBeenCalled()
+    expect(changeContainerReceivingWarehouse).not.toHaveBeenCalled()
+  })
+
+  it('keeps conflict metadata visible and refreshes the stale container summary', async () => {
+    vi.mocked(listAllPlatformWarehouses).mockResolvedValueOnce([receivingWarehouse] as never)
+    vi.mocked(changeContainerReceivingWarehouse).mockRejectedValueOnce(new ApiResponseError(
+      'version conflict', 'A0409', 200, undefined, 'request-receiving', 'trace-receiving',
+    ))
+    const wrapper = await mountView()
+    await openHiddenContainerWorkbench(wrapper)
+    await button(wrapper, '修改接柜仓')!.trigger('click')
+    await flushPromises()
+    const warehouseSelect = wrapper.findAllComponents({ name: 'ElSelect' }).find((item) => item.props('placeholder') === '请选择 ACTIVE 海外接柜仓')!
+    warehouseSelect.vm.$emit('update:modelValue', '9007199254740996')
+    await wrapper.vm.$nextTick()
+    const confirm = [...document.body.querySelectorAll('button')].find((item) => item.textContent?.includes('确认修改')) as HTMLButtonElement
+    confirm.click()
+    await flushPromises()
+    expect(wrapper.text()).toContain('接柜仓信息已被其他操作更新，请刷新后重试')
+    expect(wrapper.text()).toContain('request-receiving')
+    expect(wrapper.text()).toContain('trace-receiving')
+    expect(listContainerPlanProgress).toHaveBeenCalledTimes(2)
+  })
+
+  it('renders an explicit empty state when there are no ACTIVE OVERSEAS receiving warehouses', async () => {
+    vi.mocked(listAllPlatformWarehouses).mockResolvedValueOnce([])
+    const wrapper = await mountView()
+    await openHiddenContainerWorkbench(wrapper)
+    await button(wrapper, '修改接柜仓')!.trigger('click')
+    await flushPromises()
+    expect(document.body.textContent).toContain('暂无可用的 ACTIVE 海外接柜仓')
+    expect(changeContainerReceivingWarehouse).not.toHaveBeenCalled()
+  })
+
+  it('keeps receiving-warehouse candidate failure metadata visible without an FBA fallback', async () => {
+    vi.mocked(listAllPlatformWarehouses).mockRejectedValueOnce(new ApiResponseError(
+      'receiving warehouse candidate failed', 'A0503', 200, undefined, 'request-receiving-options', 'trace-receiving-options',
+    ))
+    const wrapper = await mountView()
+    await openHiddenContainerWorkbench(wrapper)
+    await button(wrapper, '修改接柜仓')!.trigger('click')
+    await flushPromises()
+    expect(document.body.textContent).toContain('request-receiving-options')
+    expect(document.body.textContent).toContain('trace-receiving-options')
+    expect(document.body.textContent).not.toContain('请选择目的 FBA 仓')
+    expect(changeContainerReceivingWarehouse).not.toHaveBeenCalled()
+  })
+
+  it('keeps dense cabinet fields and actions on one line with ellipsis at 1920px', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/overseas-warehouse/pages/LastMileOrdersView.vue'), 'utf8')
+    expect(source).toContain('.container-detail-summary > span { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }')
+    expect(source).toContain('.container-workbench-card__warehouse strong { min-width: 0; overflow: hidden; color: var(--cc-text); font-size: var(--admin-font-section); text-overflow: ellipsis; white-space: nowrap; }')
+    expect(source).toContain('.container-workbench-card__actions { display: flex; justify-content: flex-end; padding-top: 2px; white-space: nowrap; }')
+    expect(source).toContain("{ key: 'actions', label: '操作', width: 330, fixed: 'left'")
+  })
+
+  it('loads only active FBA master data and submits exact string fields for a cross-customer transfer', async () => {
+    const wrapper = await openPending()
+    await selectRows(wrapper, [selectedRow(), selectedRow({ id: '2092873463568596995', customerId: '2092618717861048322' })])
+    await button(wrapper, '转仓')!.trigger('click')
+    await flushPromises()
+    expect(listAllPlatformWarehouses).toHaveBeenCalledWith({ warehouseType: 'FBA', status: 'ACTIVE' })
+    const warehouseSelect = wrapper.findAllComponents({ name: 'ElSelect' }).find((item) => item.props('placeholder') === '请选择目的 FBA 仓')!
+    expect(warehouseSelect).toBeDefined()
+    const option = wrapper.findAllComponents({ name: 'ElOption' }).find((item) => item.props('value') === '9007199254740993')!
+    expect(option.props('label')).toBe('ONT8 · Ontario FBA · CA / Ontario')
+    warehouseSelect.vm.$emit('update:modelValue', '9007199254740993')
+    await wrapper.vm.$nextTick()
+    const confirm = [...document.body.querySelectorAll('button')].find((item) => item.textContent?.includes('确认转仓')) as HTMLButtonElement
+    expect(confirm.disabled).toBe(false)
+    confirm.click()
+    await flushPromises()
+    expect(transferLastMileOrders).toHaveBeenCalledWith({
+      orderIds: ['2092873463568596994', '2092873463568596995'],
+      warehouseId: '9007199254740993', warehouseCode: 'ONT8', warehouseName: 'Ontario FBA', remark: undefined,
+    })
+    expect(vi.mocked(transferLastMileOrders).mock.calls[0]?.[0].warehouseId).toBeTypeOf('string')
+    expect(wrapper.html()).not.toContain('请输入目的仓 ID')
+  })
+
+  it('clears all selected warehouse facts when the FBA candidate is cleared', async () => {
+    const wrapper = await openPending()
+    await selectRows(wrapper, [selectedRow()])
+    await button(wrapper, '转仓')!.trigger('click')
+    await flushPromises()
+    const warehouseSelect = wrapper.findAllComponents({ name: 'ElSelect' }).find((item) => item.props('placeholder') === '请选择目的 FBA 仓')!
+    warehouseSelect.vm.$emit('update:modelValue', '9007199254740993')
+    await wrapper.vm.$nextTick()
+    warehouseSelect.vm.$emit('update:modelValue', '')
+    await wrapper.vm.$nextTick()
+    const confirm = [...document.body.querySelectorAll('button')].find((item) => item.textContent?.includes('确认转仓')) as HTMLButtonElement
+    expect(confirm.disabled).toBe(true)
+    expect(transferLastMileOrders).not.toHaveBeenCalled()
+  })
+
+  it('renders an explicit empty state when there are no active FBA candidates', async () => {
+    vi.mocked(listAllPlatformWarehouses).mockResolvedValueOnce([])
+    const wrapper = await openPending()
+    await selectRows(wrapper, [selectedRow()])
+    await button(wrapper, '转仓')!.trigger('click')
+    await flushPromises()
+    expect(document.body.textContent).toContain('暂无可用 FBA 仓候选')
+    expect(transferLastMileOrders).not.toHaveBeenCalled()
+  })
+
+  it('keeps candidate load request metadata visible and prevents free-form fallback', async () => {
+    vi.mocked(listAllPlatformWarehouses).mockRejectedValueOnce(new ApiResponseError(
+      'FBA candidate failed', 'A0503', 200, undefined, 'request-fba', 'trace-fba',
+    ))
+    const wrapper = await openPending()
+    await selectRows(wrapper, [selectedRow()])
+    await button(wrapper, '转仓')!.trigger('click')
+    await flushPromises()
+    expect(document.body.textContent).toContain('A0503')
+    expect(document.body.textContent).toContain('request-fba')
+    expect(document.body.textContent).toContain('trace-fba')
+    expect(wrapper.html()).not.toContain('请输入目的仓 ID')
+    expect(wrapper.html()).not.toContain('请输入目的仓代码')
+    expect(wrapper.html()).not.toContain('请输入目的仓名称')
+    expect(transferLastMileOrders).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/modules/overseas-warehouse/pages/LastMileOrdersView.vue b/src/modules/overseas-warehouse/pages/LastMileOrdersView.vue
new file mode 100644
index 00000000..1f684e14
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/LastMileOrdersView.vue
@@ -0,0 +1,1058 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, reactive, ref, watch } from 'vue'
+import { Download, Pencil, MoreHorizontal } from '@lucide/vue'
+import { ElMessage } from 'element-plus'
+import { useRouter } from 'vue-router'
+import { listAllPlatformWarehouses, type PlatformWarehouseSummaryResource } from '@/modules/warehouses'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import OperationErrorToast from '@/shared/components/OperationErrorToast.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import { changeContainerReceivingWarehouse, convertLastMileContainerToInboundPlans, createManualInboundPlan, downloadLastMileOrders, getContainerInboundPlanPreview, getContainerPlanProgress, getLastMileOrderManualNodes, listContainerPlanProgress, listLastMileOrders, transferLastMileOrders, updateLastMileOrderHold, updateLastMileOrderManualNodes, type ContainerInboundPlanPreviewDto, type ContainerInboundPlanPreviewGroupDto, type ContainerInboundPlanPreviewOrderDto, type ContainerPlanProgressDetailDto, type ContainerPlanProgressSummaryDto, type ManualNodeCode } from '../api/lastMileOrders'
+import OrderReferenceText from '../components/OrderReferenceText.vue'
+import WarehouseTransferReviewDialog from '../components/WarehouseTransferReviewDialog.vue'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { overseasWarehousePermissions as permission } from '../permissions'
+import { lastMileStatusLabel, toLastMileOrderListItem } from '../lastMilePresentation'
+import type { LastMileOrderListItem } from '../types'
+import { saveCsv } from '@/shared/downloadCsv'
+
+const rows = ref<LastMileOrderListItem[]>([])
+const access = useAccessPreviewStore()
+const loading = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const router = useRouter()
+const page = ref(1)
+const pageSize = ref(10)
+const total = ref(0)
+const containerTotal = ref(0)
+const containerRows = ref<ContainerPlanProgressSummaryDto[]>([])
+const containerDetailOpen = ref(false)
+const containerDetailLoading = ref(false)
+const containerDetailError = ref<ApiErrorDetails | null>(null)
+const containerDetail = ref<ContainerPlanProgressDetailDto | null>(null)
+const transferReviewOpen = ref(false)
+const transferReviewTarget = ref<LastMileOrderListItem | null>(null)
+const selectedRows = ref<LastMileOrderListItem[]>([])
+const actionLoading = ref(false)
+const exportLoading = ref(false)
+async function exportOrders() { exportLoading.value = true; try { const { createdAt: range, ...rest } = filters.value; saveCsv(await downloadLastMileOrders({ ...rest, createdFrom: Array.isArray(range) && range[0] ? `${String(range[0]).slice(0, 10)}T00:00:00` : undefined, createdTo: Array.isArray(range) && range[1] ? `${String(range[1]).slice(0, 10)}T23:59:59` : undefined }) as Blob, '尾程订单.csv') } catch (cause) { ElMessage.error(getApiErrorDetails(cause, '尾程订单导出失败，请重试').message) } finally { exportLoading.value = false } }
+const actionError = ref<ApiErrorDetails | null>(null)
+const actionTarget = ref<LastMileOrderListItem | null>(null)
+const inboundPlanOpen = ref(false)
+const inboundPlanWarehouseLabel = computed(() => [actionTarget.value?.overseasWarehouseCode, actionTarget.value?.warehouse]
+  .filter((value) => value && value !== '—')
+  .join(' · '))
+const inboundPlanMinimumPalletCount = ref(1)
+const inboundPlanSourcePalletCount = ref<number | null>(null)
+const inboundPlanPreviewLoading = ref(false)
+const inboundPlanPreviewError = ref('')
+const inboundPlanIsDropship = computed(() => actionTarget.value?.orderTypeCode === 'ONE_CLICK_DROPSHIP')
+const inboundPlanSubmitDisabled = computed(() => !actionTarget.value?.estimatedWarehouseAt
+  || (inboundPlanIsDropship.value
+    && (inboundPlanPreviewLoading.value || inboundPlanSourcePalletCount.value == null
+      || inboundPlanSourcePalletCount.value <= 0)))
+const inboundPlanForm = reactive({ inboundCode: '', palletCount: 1, palletType: 'WOOD' as 'STANDARD' | 'WOOD' | 'PAPER', assigned: false, mergeRequired: false, urgent: false, remark: '' })
+const inboundPlanExpectedArrival = computed(() => actionTarget.value?.warehouseEta || '—')
+const holdOpen = ref(false)
+const holdForm = reactive({ held: true, chargeable: true, reason: '' })
+const manualNodesOpen = ref(false)
+const manualNodesLoading = ref(false)
+const manualNodesVersion = ref(0)
+const manualNodeDefinitions: Array<{ code: ManualNodeCode; label: string }> = [
+  { code: 'DOMESTIC_CUSTOMS_COMPLETED', label: '国内报关完成' },
+  { code: 'ESTIMATED_DEPARTURE', label: '预计开船' },
+  { code: 'ACTUAL_DEPARTURE', label: '实际开船' },
+  { code: 'ESTIMATED_ARRIVAL', label: '预计到港' },
+  { code: 'OVERSEAS_CUSTOMS_COMPLETED', label: '国外清关完成' },
+  { code: 'ACTUAL_ARRIVAL_WAITING_UNLOAD', label: '实际到港等待卸船' },
+  { code: 'PICKUP_APPOINTED', label: '预约提柜' },
+  { code: 'UNLOADED', label: '卸柜' },
+]
+const manualNodeValues = reactive<Record<ManualNodeCode, string | null>>(Object.fromEntries(manualNodeDefinitions.map(({ code }) => [code, null])) as Record<ManualNodeCode, string | null>)
+const transferOpen = ref(false)
+const transferWarehouseLoading = ref(false)
+const transferWarehouseError = ref<ApiErrorDetails | null>(null)
+const transferWarehouseOptions = ref<TransferWarehouseOption[]>([])
+const transferForm = reactive({ warehouseId: '', warehouseCode: '', warehouseName: '', remark: '' })
+const containerConvertOpen = ref(false)
+const containerOptions = ref<ContainerPlanProgressSummaryDto[]>([])
+const containerOptionsLoading = ref(false)
+const containerLoadError = ref<ApiErrorDetails | null>(null)
+const selectedContainerBookingId = ref('')
+const containerPreview = ref<ContainerInboundPlanPreviewDto | null>(null)
+const containerPreviewLoading = ref(false)
+const containerPreviewError = ref('')
+type ContainerConversionPlan = Awaited<ReturnType<typeof convertLastMileContainerToInboundPlans>>[number]
+interface ContainerConversionResult {
+  plans: ContainerConversionPlan[]
+  existingPlanNos: Set<string>
+  newPlanCount: number
+  existingPlanCount: number
+}
+const containerConversionResult = ref<ContainerConversionResult | null>(null)
+let containerPreviewRequest = 0
+let containerPreviewLoadingBookingId = ''
+let containerConversionIdempotencyKey = ''
+const containerConfirmDisabled = computed(() => !containerPreview.value?.ready
+  || containerPreview.value.pendingOrderCount <= 0
+  || containerPreviewLoading.value
+  || actionLoading.value
+  || Boolean(containerConversionResult.value))
+const receivingWarehouseOpen = ref(false)
+const receivingWarehouseLoading = ref(false)
+const receivingWarehouseError = ref<ApiErrorDetails | null>(null)
+const receivingWarehouseActionError = ref<ApiErrorDetails | null>(null)
+const receivingWarehouseOptions = ref<TransferWarehouseOption[]>([])
+const receivingWarehouseTarget = ref<ContainerPlanProgressSummaryDto | null>(null)
+const receivingWarehouseForm = reactive({ warehouseId: '', remark: '' })
+let receivingWarehouseIdempotencyKey = ''
+let containerOptionRequest = 0
+const statusTab = ref<'全部' | '待分配' | '柜子'>('全部')
+const filters = ref<QueryModel>({ orderNo: '', relabelNo: '', orderType: '', warehouse: '', inboundCode: '', lxCode: '', sourceOrderNo: '', containerNo: '', status: '', transferWarehouseCode: '', abnormal: '', detained: '', createdAt: [] })
+const allFields: QueryField[] = [
+  { key: 'orderNo', type: 'input', label: '尾程单号', width: 190, placeholder: '请输入尾程单号' },
+  { key: 'relabelNo', type: 'input', label: '换标单号', width: 190, placeholder: '请输入换标单号' },
+  { key: 'inboundCode', type: 'input', label: '入仓码', width: 180, placeholder: '请输入入仓码' },
+  { key: 'lxCode', type: 'input', label: 'LX代码', width: 180, placeholder: '请输入LX代码' },
+  { key: 'orderType', type: 'select', label: '订单类型', width: 170, placeholder: '全部类型', options: [
+    { label: '头程订单', value: 'FIRST_LEG' }, { label: '换标下单', value: 'RELABEL_APPLICATION' },
+    { label: '仓储转运', value: 'WAREHOUSE_TRANSFER' }, { label: '本土散板', value: 'LOCAL_LOOSEBOARD' },
+    { label: '退货换标', value: 'RETURN_RELABEL' }, { label: '一件代发', value: 'ONE_CLICK_DROPSHIP' },
+    { label: '货物废弃订单', value: 'CARGO_DISCARD' },
+  ] },
+  { key: 'warehouse', type: 'input', label: '海外仓', width: 210, placeholder: '请输入仓库名称或编码' },
+  { key: 'sourceOrderNo', type: 'input', label: '来源订单号', width: 190, placeholder: '请输入来源订单号' },
+  { key: 'containerNo', type: 'input', label: '集装箱号', width: 180, placeholder: '请输入集装箱号' },
+  { key: 'transferWarehouseCode', type: 'input', label: '转仓代码', width: 170, placeholder: '请输入转仓代码' },
+  { key: 'status', type: 'select', label: '当前状态', width: 160, placeholder: '全部状态', options: [
+    { label: '待分配', value: 'PENDING_ASSIGNMENT' },
+    { label: '待入库', value: 'PENDING_INBOUND' },
+    { label: '入库完成', value: 'INBOUND_COMPLETED' },
+    { label: '待派送', value: 'PENDING_DELIVERY' },
+    { label: '派送中', value: 'DELIVERING' },
+    { label: '派送完成', value: 'DELIVERED' },
+  ] },
+  { key: 'abnormal', type: 'select', label: '是否异常', width: 140, placeholder: '全部', options: [{ label: '是', value: 'true' }, { label: '否', value: 'false' }] },
+  { key: 'detained', type: 'select', label: '是否暂扣', width: 140, placeholder: '全部', options: [{ label: '是', value: 'true' }, { label: '否', value: 'false' }] },
+  { key: 'createdAt', type: 'daterange', label: '创建时间', width: 280 },
+]
+const fields = computed<QueryField[]>(() => statusTab.value === '柜子'
+  ? allFields.filter((field) => ['containerNo', 'createdAt'].includes(field.key))
+  : allFields)
+const selectedContainer = computed(() => containerOptions.value.find((row) => row.sourceContainerBookingId === selectedContainerBookingId.value))
+const selectedReceivingWarehouse = computed(() => receivingWarehouseOptions.value.find((row) => (
+  row.warehouseId === receivingWarehouseForm.warehouseId
+  && row.warehouseId !== receivingWarehouseTarget.value?.overseasWarehouseId
+)))
+
+interface TransferWarehouseOption {
+  warehouseId: string
+  warehouseCode: string
+  warehouseName: string
+  region: string
+  label: string
+}
+
+function warehouseRegion(warehouse: PlatformWarehouseSummaryResource) {
+  const addressRegion = [warehouse.primaryAddress?.stateProvince, warehouse.primaryAddress?.city]
+    .map((value) => String(value || '').trim())
+    .filter(Boolean)
+    .join(' / ')
+  return addressRegion || String(warehouse.addressSummary || warehouse.countryCode || '').trim()
+}
+
+function toTransferWarehouseOption(warehouse: PlatformWarehouseSummaryResource): TransferWarehouseOption {
+  const warehouseId = String(warehouse.id)
+  const warehouseCode = warehouse.warehouseCode.trim()
+  const warehouseName = warehouse.warehouseName.trim()
+  const region = warehouseRegion(warehouse)
+  return {
+    warehouseId,
+    warehouseCode,
+    warehouseName,
+    region,
+    label: [warehouseCode, warehouseName, region].filter(Boolean).join(' · '),
+  }
+}
+
+function receivingWarehouseLabel(container: ContainerPlanProgressSummaryDto | null | undefined) {
+  if (!container) return '—'
+  const code = String(container.overseasWarehouseCode || '').trim()
+  const name = String(container.overseasWarehouseName || '').trim()
+  return [code, name].filter(Boolean).join(' · ') || '—'
+}
+
+function receivingWarehouseChangeDisabledReason(container: ContainerPlanProgressSummaryDto) {
+  if (!access.can(permission.lastMileOrderTransfer)) return '暂无修改接柜仓权限，请联系管理员开通尾程订单编辑权限'
+  if (!container.canChangeReceivingWarehouse) return container.receivingWarehouseLockReason || '当前柜已锁定，不能修改接柜仓'
+  return ''
+}
+
+function newReceivingWarehouseIdempotencyKey() {
+  return `container-receiving-warehouse-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`
+}
+const columns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 330, fixed: 'left', slotName: 'actions' },
+  { key: 'selection', type: 'selection', width: 48, fixed: 'left' },
+  { key: 'orderNo', prop: 'orderNo', label: '尾程单号', minWidth: 170, slotName: 'orderNo' },
+  { key: 'consolidated', prop: 'consolidated', label: '合托标记', width: 100, hideable: false },
+  { key: 'palletMergeRelation', prop: 'palletMergeRelation', label: '合托关联入仓单', minWidth: 220, hideable: false },
+  { key: 'warning', prop: 'warning', label: '预警', width: 90 },
+  { key: 'orderType', prop: 'orderType', label: '订单类型', minWidth: 110 },
+  { key: 'rejectedAt', prop: 'rejectedAt', label: '拒收时间', minWidth: 150 },
+  { key: 'inboundCode', prop: 'inboundCode', label: '入仓码', minWidth: 140 },
+  { key: 'lxCode', prop: 'lxCode', label: 'LX代码', minWidth: 150 },
+  { key: 'owner', prop: 'owner', label: '货主', minWidth: 150 },
+  { key: 'warehouse', prop: 'warehouse', label: '海外仓', minWidth: 170 },
+  { key: 'transferWarehouse', prop: 'transferWarehouse', label: '转仓', minWidth: 140 },
+  { key: 'fbaWarehouse', prop: 'fbaWarehouse', label: 'FBA仓库', minWidth: 130 },
+  { key: 'containerNo', prop: 'containerNo', label: '集装箱号', minWidth: 150 },
+  { key: 'abnormal', prop: 'abnormal', label: '是否异常', width: 100 },
+  { key: 'held', prop: 'held', label: '是否暂扣', width: 100 },
+  { key: 'pallets', prop: 'pallets', label: '托数', width: 80, align: 'right' },
+  { key: 'cartons', prop: 'cartons', label: '箱数', width: 80, align: 'right' },
+  { key: 'volume', prop: 'volume', label: '体积(m³)', width: 100, align: 'right' },
+  { key: 'quantity', prop: 'quantity', label: '数量', width: 80, align: 'right' },
+  { key: 'volumeWeight', prop: 'volumeWeight', label: '体积重量', width: 100, align: 'right' },
+  { key: 'portEta', prop: 'portEta', label: '预计到港时间', minWidth: 150 },
+  { key: 'portAta', prop: 'portAta', label: '实际到港时间', minWidth: 150 },
+  { key: 'warehouseEta', prop: 'warehouseEta', label: '预计到仓', minWidth: 140 },
+  { key: 'inboundOrderNo', prop: 'inboundOrderNo', label: '入库单号', minWidth: 150 },
+  { key: 'dispatchStatus', prop: 'dispatchStatus', label: '排车状态', width: 110 },
+  { key: 'outboundOrderNo', prop: 'outboundOrderNo', label: '出库单号', minWidth: 150 },
+  { key: 'dispatchOrderNo', prop: 'dispatchOrderNo', label: '派送单号', minWidth: 150 },
+  { key: 'relabelOrderNo', prop: 'relabelOrderNo', label: '换标单号', minWidth: 150 },
+  { key: 'relabelStatus', prop: 'relabelStatus', label: '换标状态', width: 110 },
+  { key: 'status', prop: 'status', label: '当前状态', width: 110 },
+  { key: 'createdAt', prop: 'createdAt', label: '创建时间', minWidth: 170 },
+  { key: 'internalRemark', prop: 'internalRemark', label: '备注(仅自己)', minWidth: 160 },
+  { key: 'customerRemark', prop: 'customerRemark', label: '备注(客户)', minWidth: 160 },
+  { key: 'warehouseRemark', prop: 'warehouseRemark', label: '备注(仓库)', minWidth: 160 },
+]
+const containerDetailColumns: DataTableColumn[] = [
+  { key: 'orderNo', prop: 'orderNo', label: '尾程单号', minWidth: 170 },
+  { key: 'inboundCode', prop: 'inboundCode', label: '入仓码', minWidth: 150 },
+  { key: 'orderStatus', prop: 'orderStatus', label: '订单状态', width: 130, slotName: 'orderStatus' },
+  { key: 'planNo', prop: 'planNo', label: '独立入库计划', minWidth: 170 },
+  { key: 'planStatus', prop: 'planStatus', label: '计划状态', width: 130, slotName: 'planStatus' },
+  { key: 'plannedArrivalAt', prop: 'plannedArrivalAt', label: '计划到仓时间', minWidth: 170, slotName: 'plannedArrivalAt' },
+]
+
+function formatDateTime(value: string | null | undefined) {
+  return value ? value.replace('T', ' ').slice(0, 19) : '—'
+}
+function inboundPlanStatusLabel(value: unknown) {
+  const code = String(value ?? '').trim()
+  return ({
+    PENDING_ASSIGNMENT: '待入库',
+    ASSIGNED: '待入库',
+    PDA_PENDING: '待入库',
+    PENDING_RECEIVING: '待收货',
+    PICKING: '拣货中',
+    PARTIAL_INBOUND: '部分入库',
+    COMPLETED: '全部入库',
+    CANCELLED: '已取消',
+  } as Record<string, string>)[code] || (code ? '未知状态' : '—')
+}
+function canGenerateContainerPlans(container: ContainerPlanProgressSummaryDto) {
+  return Boolean(container.containerNo
+    && container.overseasWarehouseId
+    && container.overseasWarehouseCode
+    && container.overseasWarehouseName
+    && container.assignmentVersion >= 0
+    && (container.pendingPlanCount > 0 || container.resourcePendingPlanCount > 0))
+}
+function containerSnapshotBlockReason(container: ContainerPlanProgressSummaryDto) {
+  if (!container.containerNo) return container.blockingReason || '来源柜真实集装箱号缺失、格式无效或存在漂移'
+  if (!container.overseasWarehouseId || !container.overseasWarehouseCode
+    || !container.overseasWarehouseName || container.assignmentVersion < 0) {
+    return '柜内接柜仓业务快照不一致'
+  }
+  return ''
+}
+function pendingInboundCodeCount(container: ContainerPlanProgressSummaryDto) {
+  return Math.max(0, container.inboundCodeCount - container.plannedInboundCodeCount)
+}
+function changeContainerPage(value: number) {
+  page.value = value
+  void load()
+}
+function changeContainerPageSize(value: number) {
+  pageSize.value = value
+  page.value = 1
+  void load()
+}
+async function load(model: QueryModel = filters.value) {
+  Object.assign(filters.value, model)
+  loading.value = true
+  loadError.value = null
+  if (statusTab.value === '柜子') {
+    const dateRange = Array.isArray(filters.value.createdAt) ? filters.value.createdAt.map(String) : []
+    try {
+      const result = await listContainerPlanProgress({
+        page: page.value,
+        size: pageSize.value,
+        containerNo: String(filters.value.containerNo || '').trim() || undefined,
+        createdFrom: dateRange[0] ? `${dateRange[0]}T00:00:00` : undefined,
+        createdTo: dateRange[1] ? `${dateRange[1]}T23:59:59` : undefined,
+      })
+      containerRows.value = result.records
+      containerTotal.value = result.total
+    } catch (error) {
+      containerRows.value = []
+      containerTotal.value = 0
+      loadError.value = getApiErrorDetails(error, '柜级入库计划进度加载失败，请重试')
+    } finally {
+      loading.value = false
+    }
+    return
+  }
+  try {
+    const dateRange = Array.isArray(filters.value.createdAt) ? filters.value.createdAt.map(String) : []
+    const booleanValue = (value: unknown) => value === 'true' ? true : value === 'false' ? false : undefined
+    const result = await listLastMileOrders({
+      page: page.value,
+      size: pageSize.value,
+      orderNo: String(filters.value.orderNo || '').trim() || undefined,
+      relabelNo: String(filters.value.relabelNo || '').trim() || undefined,
+      orderType: String(filters.value.orderType || '').trim() || undefined,
+      warehouse: String(filters.value.warehouse || '').trim() || undefined,
+      inboundCode: String(filters.value.inboundCode || '').trim() || undefined,
+      lxCode: String(filters.value.lxCode || '').trim() || undefined,
+      sourceOrderNo: String(filters.value.sourceOrderNo || '').trim() || undefined,
+      containerNo: String(filters.value.containerNo || '').trim() || undefined,
+      currentStatus: statusTab.value === '待分配' ? 'PENDING_ASSIGNMENT' : String(filters.value.status || '').trim() || undefined,
+      transferWarehouseCode: String(filters.value.transferWarehouseCode || '').trim() || undefined,
+      abnormal: booleanValue(filters.value.abnormal),
+      detained: booleanValue(filters.value.detained),
+      createdFrom: dateRange[0] ? `${dateRange[0]}T00:00:00` : undefined,
+      createdTo: dateRange[1] ? `${dateRange[1]}T23:59:59` : undefined,
+    })
+    rows.value = result.records.map(toLastMileOrderListItem)
+    total.value = result.total
+  } catch (error) {
+    rows.value = []
+    total.value = 0
+    loadError.value = error instanceof Error && error.message === '当前环境未签发海外访问令牌'
+      ? { message: error.message }
+      : getApiErrorDetails(error, '尾程订单加载失败，请重试')
+  } finally {
+    loading.value = false
+  }
+}
+
+function search(model: QueryModel) { page.value = 1; void load(model) }
+function reset(model: QueryModel) { page.value = 1; void load(model) }
+function changeStatusTab() {
+  selectedRows.value = []
+  page.value = 1
+  void load()
+}
+
+async function openContainerDetail(row: ContainerPlanProgressSummaryDto) {
+  containerDetailOpen.value = true
+  containerDetailLoading.value = true
+  containerDetailError.value = null
+  containerDetail.value = null
+  try {
+    containerDetail.value = await getContainerPlanProgress(row.sourceContainerBookingId)
+  } catch (error) {
+    containerDetailError.value = getApiErrorDetails(error, '柜级详情加载失败，请重试')
+  } finally {
+    containerDetailLoading.value = false
+  }
+}
+async function loadReceivingWarehouseOptions() {
+  receivingWarehouseLoading.value = true
+  receivingWarehouseError.value = null
+  receivingWarehouseOptions.value = []
+  try {
+    const warehouses = await listAllPlatformWarehouses({ warehouseType: 'OVERSEAS', status: 'ACTIVE' })
+    receivingWarehouseOptions.value = warehouses.map(toTransferWarehouseOption)
+  } catch (error) {
+    receivingWarehouseError.value = getApiErrorDetails(error, '海外接柜仓候选加载失败，请重试')
+  } finally {
+    receivingWarehouseLoading.value = false
+  }
+}
+function openReceivingWarehouseChange(container: ContainerPlanProgressSummaryDto) {
+  const disabledReason = receivingWarehouseChangeDisabledReason(container)
+  if (disabledReason) {
+    ElMessage.warning(disabledReason)
+    return
+  }
+  receivingWarehouseTarget.value = container
+  Object.assign(receivingWarehouseForm, { warehouseId: '', remark: '' })
+  receivingWarehouseIdempotencyKey = newReceivingWarehouseIdempotencyKey()
+  receivingWarehouseOptions.value = []
+  receivingWarehouseError.value = null
+  receivingWarehouseActionError.value = null
+  actionError.value = null
+  receivingWarehouseOpen.value = true
+  void loadReceivingWarehouseOptions()
+}
+async function submitReceivingWarehouseChange() {
+  const target = receivingWarehouseTarget.value
+  const selected = selectedReceivingWarehouse.value
+  if (!target || !selected) {
+    ElMessage.warning('请选择与当前仓不同的有效海外接柜仓')
+    return
+  }
+  actionLoading.value = true
+  actionError.value = null
+  receivingWarehouseActionError.value = null
+  try {
+    await changeContainerReceivingWarehouse(target.sourceContainerBookingId, {
+      overseasWarehouseId: selected.warehouseId,
+      expectedVersion: target.assignmentVersion,
+      remark: receivingWarehouseForm.remark.trim() || undefined,
+    }, receivingWarehouseIdempotencyKey)
+    receivingWarehouseOpen.value = false
+    receivingWarehouseTarget.value = null
+    ElMessage.success('海外接柜仓修改成功')
+    await load()
+  } catch (error) {
+    const details = getApiErrorDetails(error, '海外接柜仓修改失败，请重试')
+    receivingWarehouseActionError.value = details.code === 'A0409'
+      ? { ...details, message: '接柜仓信息已被其他操作更新，请刷新后重试' }
+      : details
+    actionError.value = receivingWarehouseActionError.value
+    if (details.code === 'A0409') {
+      receivingWarehouseOpen.value = false
+      receivingWarehouseTarget.value = null
+      await load()
+    }
+  } finally {
+    actionLoading.value = false
+  }
+}
+function onSelectionChange(selection: object[]) { selectedRows.value = selection as LastMileOrderListItem[] }
+async function loadTransferWarehouseOptions() {
+  transferWarehouseLoading.value = true
+  transferWarehouseError.value = null
+  transferWarehouseOptions.value = []
+  try {
+    const warehouses = await listAllPlatformWarehouses({ warehouseType: 'FBA', status: 'ACTIVE' })
+    transferWarehouseOptions.value = warehouses.map(toTransferWarehouseOption)
+  } catch (error) {
+    transferWarehouseError.value = getApiErrorDetails(error, 'FBA 仓候选加载失败，请重试')
+  } finally {
+    transferWarehouseLoading.value = false
+  }
+}
+function selectTransferWarehouse(warehouseId: string) {
+  const selected = transferWarehouseOptions.value.find((warehouse) => warehouse.warehouseId === String(warehouseId || ''))
+  Object.assign(transferForm, selected
+    ? { warehouseId: selected.warehouseId, warehouseCode: selected.warehouseCode, warehouseName: selected.warehouseName }
+    : { warehouseId: '', warehouseCode: '', warehouseName: '' })
+}
+function openTransfer() {
+  if (!selectedRows.value.length) { ElMessage.warning('请至少选择 1 条尾程订单'); return }
+  Object.assign(transferForm, { warehouseId: '', warehouseCode: '', warehouseName: '', remark: '' })
+  transferWarehouseOptions.value = []
+  transferWarehouseError.value = null
+  actionError.value = null
+  transferOpen.value = true
+  void loadTransferWarehouseOptions()
+}
+async function submitTransfer() {
+  const selectedWarehouse = transferWarehouseOptions.value.find((warehouse) => warehouse.warehouseId === transferForm.warehouseId)
+  if (!selectedWarehouse) {
+    ElMessage.warning('请选择目的 FBA 仓')
+    return
+  }
+  actionLoading.value = true; actionError.value = null
+  try {
+    await transferLastMileOrders({
+      orderIds: selectedRows.value.map((row) => String(row.id)),
+      warehouseId: selectedWarehouse.warehouseId,
+      warehouseCode: selectedWarehouse.warehouseCode,
+      warehouseName: selectedWarehouse.warehouseName,
+      remark: transferForm.remark.trim() || undefined,
+    })
+    transferOpen.value = false; selectedRows.value = []; ElMessage.success('转仓成功'); await load()
+  } catch (error) { actionError.value = getApiErrorDetails(error, '转仓失败，请重试') }
+  finally { actionLoading.value = false }
+}
+function idempotencyKey(prefix: string) {
+  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`
+}
+function openInboundPlan(source?: object) {
+  const target = source ? source as LastMileOrderListItem : (selectedRows.value.length === 1 ? selectedRows.value[0] : null)
+  if (!target) { ElMessage.warning('生成入库计划时请选择 1 条尾程订单'); return }
+  if (target.detained) { ElMessage.warning('订单处于暂扣状态，解除暂扣后才能生成入库计划'); return }
+  actionTarget.value = target
+  const volumeMinimum = typeof target.volume === 'number' && target.volume > 0 ? Math.ceil(target.volume / 2) : 1
+  inboundPlanMinimumPalletCount.value = Math.max(1, volumeMinimum,
+    typeof target.pallets === 'number' ? target.pallets : 0)
+  inboundPlanSourcePalletCount.value = null
+  inboundPlanPreviewError.value = ''
+  Object.assign(inboundPlanForm, { inboundCode: target.inboundCode === '—' ? '' : target.inboundCode, palletCount: inboundPlanMinimumPalletCount.value, palletType: 'WOOD', assigned: false, mergeRequired: false, urgent: false, remark: '' })
+  actionError.value = null
+  inboundPlanOpen.value = true
+  void refreshManualPalletMinimum(target)
+}
+async function refreshManualPalletMinimum(target: LastMileOrderListItem) {
+  if (!target.sourceContainerBookingId) return
+  inboundPlanPreviewLoading.value = true
+  inboundPlanPreviewError.value = ''
+  try {
+    const preview = await getContainerInboundPlanPreview(target.sourceContainerBookingId)
+    if (actionTarget.value?.id !== target.id || !inboundPlanOpen.value) return
+    const order = preview.groups.flatMap((group) => group.orders).find((item) => item.orderId === target.id)
+    if (target.orderTypeCode === 'ONE_CLICK_DROPSHIP') {
+      const sourcePalletCount = Number(order?.sourcePalletCount || 0)
+      if (sourcePalletCount <= 0) throw new Error('一件代发订单缺少头程封托托盘快照')
+      inboundPlanSourcePalletCount.value = sourcePalletCount
+      inboundPlanMinimumPalletCount.value = sourcePalletCount
+      inboundPlanForm.palletCount = sourcePalletCount
+      return
+    }
+    const suggested = Number(order?.suggestedPalletCount || 0)
+    inboundPlanMinimumPalletCount.value = Math.max(inboundPlanMinimumPalletCount.value, suggested)
+    inboundPlanForm.palletCount = Math.max(inboundPlanForm.palletCount, inboundPlanMinimumPalletCount.value)
+  } catch (error) {
+    if (actionTarget.value?.id === target.id && inboundPlanOpen.value) {
+      inboundPlanPreviewError.value = getApiErrorDetails(error, '柜级托盘预览加载失败，请重试').message
+    }
+  } finally {
+    if (actionTarget.value?.id === target.id) inboundPlanPreviewLoading.value = false
+  }
+}
+async function submitInboundPlan() {
+  const row = actionTarget.value
+  const frozenInboundCode = String(row?.inboundCode || '').trim()
+  if (inboundPlanIsDropship.value && (inboundPlanSourcePalletCount.value == null
+    || inboundPlanForm.palletCount !== inboundPlanSourcePalletCount.value)) {
+    ElMessage.warning('一件代发必须按头程已封托托盘数整体生成入库计划')
+    return
+  }
+  if (!row || !row.overseasWarehouseId || !row.estimatedWarehouseAt || !frozenInboundCode || frozenInboundCode === '—' || inboundPlanForm.palletCount < inboundPlanMinimumPalletCount.value) {
+    ElMessage.warning('当前柜须已分配接柜仓、具备预计到仓时间，并完整填写托数')
+    return
+  }
+  actionLoading.value = true; actionError.value = null
+  try {
+    const result = await createManualInboundPlan({
+      customerId: row.customerId, orderId: row.id, expectedOrderVersion: row.version,
+      palletCount: inboundPlanForm.palletCount,
+      palletType: inboundPlanForm.palletType, assigned: inboundPlanForm.assigned,
+      mergeRequired: inboundPlanForm.mergeRequired, urgent: inboundPlanForm.urgent,
+      remark: inboundPlanForm.remark.trim() || undefined,
+    }, idempotencyKey('manual-inbound-plan'))
+    const palletCodesReady = result.pallets?.length === result.palletCount
+      && result.pallets.every((pallet) => Boolean(pallet.warehousePalletId && pallet.palletNo))
+    inboundPlanOpen.value = false; selectedRows.value = []
+    ElMessage.success(palletCodesReady
+      ? '入库计划和托盘码已自动生成'
+      : '入库计划已保存，整柜计划齐全后将自动生成托盘码')
+    await load()
+  } catch (error) { actionError.value = getApiErrorDetails(error, '生成入库计划失败，请重试') }
+  finally { actionLoading.value = false }
+}
+function openHold(source: object) {
+  const row = source as LastMileOrderListItem
+  actionTarget.value = row
+  Object.assign(holdForm, { held: !row.detained, chargeable: row.detained ? false : true, reason: '' })
+  actionError.value = null
+  holdOpen.value = true
+}
+async function submitHold() {
+  const row = actionTarget.value
+  if (!row || !holdForm.reason.trim()) { ElMessage.warning('请输入变更原因'); return }
+  actionLoading.value = true; actionError.value = null
+  try {
+    await updateLastMileOrderHold(row.id, { held: holdForm.held, chargeable: holdForm.chargeable, reason: holdForm.reason.trim(), expectedVersion: row.version }, idempotencyKey('last-mile-hold'))
+    holdOpen.value = false; ElMessage.success(holdForm.held ? '订单已暂扣' : '订单已解除暂扣'); await load()
+  } catch (error) { actionError.value = getApiErrorDetails(error, '暂扣状态保存失败，请重试') }
+  finally { actionLoading.value = false }
+}
+async function openManualNodes(source: object) {
+  const row = source as LastMileOrderListItem
+  actionTarget.value = row
+  manualNodesOpen.value = true
+  manualNodesLoading.value = true
+  actionError.value = null
+  manualNodeDefinitions.forEach(({ code }) => { manualNodeValues[code] = null })
+  try {
+    const result = await getLastMileOrderManualNodes(row.id)
+    manualNodesVersion.value = result.version
+    result.nodes.forEach((node) => { manualNodeValues[node.nodeCode] = node.nodeAt })
+  } catch (error) { actionError.value = getApiErrorDetails(error, '人工节点加载失败，请重试') }
+  finally { manualNodesLoading.value = false }
+}
+async function submitManualNodes() {
+  const row = actionTarget.value
+  if (!row || !manualNodeDefinitions.some(({ code }) => Boolean(manualNodeValues[code]))) { ElMessage.warning('请至少填写一个节点时间'); return }
+  actionLoading.value = true; actionError.value = null
+  try {
+    await updateLastMileOrderManualNodes(row.id, manualNodesVersion.value, manualNodeDefinitions.map(({ code }) => ({ nodeCode: code, nodeAt: manualNodeValues[code] })), idempotencyKey('last-mile-manual-nodes'))
+    manualNodesOpen.value = false; ElMessage.success('人工节点已保存，该订单不再继承柜级节点'); await load()
+  } catch (error) { actionError.value = getApiErrorDetails(error, '人工节点保存失败，请重试') }
+  finally { actionLoading.value = false }
+}
+async function loadContainerOptions(containerNo = '') {
+  const request = ++containerOptionRequest
+  containerOptionsLoading.value = true
+  containerLoadError.value = null
+  try {
+    const result = await listContainerPlanProgress({
+      page: 1,
+      size: 50,
+      containerNo: containerNo.trim() || undefined,
+    })
+    if (request !== containerOptionRequest) return
+    containerOptions.value = result.records
+  } catch (error) {
+    if (request !== containerOptionRequest) return
+    containerOptions.value = []
+    containerLoadError.value = getApiErrorDetails(error, '待分配柜列表加载失败，请重试')
+  } finally {
+    if (request === containerOptionRequest) containerOptionsLoading.value = false
+  }
+}
+function openContainerConversion() {
+  selectedContainerBookingId.value = ''
+  containerOptions.value = []
+  containerLoadError.value = null
+  containerPreview.value = null
+  containerPreviewError.value = ''
+  containerConversionResult.value = null
+  containerConversionIdempotencyKey = ''
+  actionError.value = null
+  containerConvertOpen.value = true
+  void loadContainerOptions()
+}
+function openContainerConversionFor(container: ContainerPlanProgressSummaryDto) {
+  selectedContainerBookingId.value = container.sourceContainerBookingId
+  containerOptions.value = [container]
+  containerLoadError.value = null
+  containerPreview.value = null
+  containerPreviewError.value = ''
+  containerConversionResult.value = null
+  containerConversionIdempotencyKey = ''
+  actionError.value = null
+  containerConvertOpen.value = true
+  void loadContainerPreview(container.sourceContainerBookingId)
+}
+async function loadContainerPreview(sourceContainerBookingId = selectedContainerBookingId.value, preserveResult = false) {
+  if (containerPreviewLoading.value && containerPreviewLoadingBookingId === sourceContainerBookingId) return
+  if (containerPreview.value?.sourceContainerBookingId === sourceContainerBookingId) return
+  const request = ++containerPreviewRequest
+  containerPreview.value = null
+  containerPreviewError.value = ''
+  if (!preserveResult) {
+    containerConversionResult.value = null
+    containerConversionIdempotencyKey = ''
+  }
+  if (!sourceContainerBookingId) {
+    containerPreviewLoading.value = false
+    containerPreviewLoadingBookingId = ''
+    return
+  }
+  containerPreviewLoading.value = true
+  containerPreviewLoadingBookingId = sourceContainerBookingId
+  try {
+    const preview = await getContainerInboundPlanPreview(sourceContainerBookingId)
+    if (request !== containerPreviewRequest || selectedContainerBookingId.value !== sourceContainerBookingId || !containerConvertOpen.value) return
+    containerPreview.value = preview
+    if (!preserveResult) containerConversionIdempotencyKey = idempotencyKey('container-inbound-plan')
+  } catch (error) {
+    if (request !== containerPreviewRequest || selectedContainerBookingId.value !== sourceContainerBookingId || !containerConvertOpen.value) return
+    containerPreviewError.value = getApiErrorDetails(error, '加载整柜入库计划预览失败，请重试').message
+  } finally {
+    if (request === containerPreviewRequest) {
+      containerPreviewLoading.value = false
+      containerPreviewLoadingBookingId = ''
+    }
+  }
+}
+
+async function confirmContainerInboundPlans() {
+  const preview = containerPreview.value
+  if (!preview?.ready || preview.pendingOrderCount <= 0 || actionLoading.value) return
+  if (!containerConversionIdempotencyKey) containerConversionIdempotencyKey = idempotencyKey('container-inbound-plan')
+  const bookingId = preview.sourceContainerBookingId
+  const existingPlanNos = new Set(preview.groups.flatMap((group) => group.orders)
+    .filter((order) => order.readiness !== 'READY' && order.existingPlanNo)
+    .map((order) => String(order.existingPlanNo)))
+  actionLoading.value = true
+  actionError.value = null
+  try {
+    const plans = await convertLastMileContainerToInboundPlans({
+      sourceContainerBookingId: bookingId,
+      snapshotVersion: preview.snapshotVersion,
+      snapshotHash: preview.snapshotHash,
+    }, containerConversionIdempotencyKey)
+    if (selectedContainerBookingId.value !== bookingId || !containerConvertOpen.value) return
+    const existingPlanCount = plans.filter((plan) => existingPlanNos.has(plan.planNo)).length
+    containerConversionResult.value = {
+      plans,
+      existingPlanNos,
+      newPlanCount: plans.length - existingPlanCount,
+      existingPlanCount,
+    }
+    ElMessage.success(`已生成 ${plans.length - existingPlanCount} 个入库计划`)
+    containerPreview.value = null
+    await Promise.all([load(), loadContainerPreview(bookingId, true)])
+  } catch (error) {
+    actionError.value = getApiErrorDetails(error, '按柜生成入库计划失败，请使用原操作重试')
+  } finally {
+    actionLoading.value = false
+  }
+}
+
+function previewGroupTitle(group: ContainerInboundPlanPreviewGroupDto) {
+  if (group.destinationType === 'FBA') return `${group.destinationWarehouseName || group.destinationWarehouseCode || '未配置目的仓'} FBA仓`
+  return group.destinationType === 'ONE_CLICK_DROPSHIP' ? '一件代发' : '私人地址'
+}
+
+function destinationText(order: { destinationWarehouseCode?: string | null; destinationWarehouseName?: string | null }) {
+  return [order.destinationWarehouseCode, order.destinationWarehouseName].filter(Boolean).join(' / ') || '—'
+}
+
+function orderTypeText(orderType: string) {
+  const labels: Record<string, string> = {
+    FIRST_LEG: '头程订单',
+    RELABEL_APPLICATION: '换标下单',
+    WAREHOUSE_TRANSFER: '仓储转运',
+    LOCAL_LOOSEBOARD: '本土散板',
+    RETURN_RELABEL: '退货换标',
+    ONE_CLICK_DROPSHIP: '一件代发',
+    CARGO_DISCARD: '货物废弃订单',
+  }
+  return labels[orderType] || orderType
+}
+
+function readinessText(readiness: ContainerInboundPlanPreviewOrderDto['readiness']) {
+  return readiness === 'READY' ? '可生成' : readiness === 'RESOURCE_PENDING' ? '将自动补齐' : readiness === 'PLANNED' ? '已有计划' : '已阻断'
+}
+
+function readinessType(readiness: ContainerInboundPlanPreviewOrderDto['readiness']) {
+  return readiness === 'READY' || readiness === 'RESOURCE_PENDING' ? 'success' : readiness === 'PLANNED' ? 'info' : 'danger'
+}
+
+function blockerText(blockers: string[]) {
+  const labels: Record<string, string> = {
+    MISSING_INBOUND_CODE: '缺少入仓码',
+    ORDER_DETAINED: '订单已暂扣',
+    ORDER_STATUS_NOT_READY: '订单状态未就绪',
+    CONTAINER_NO_INCONSISTENT: '货柜号不一致',
+    RECEIVING_WAREHOUSE_INCONSISTENT: '收货仓不一致',
+    DESTINATION_NOT_READY: '目的地未就绪',
+    CARGO_FACT_INVALID: '货物数据无效',
+    PLAN_ALREADY_STARTED: '已有计划已开始作业，不能再补生成托盘',
+    PLAN_PALLET_BINDING_INCOMPLETE: '已有计划只绑定了部分真实托盘，请联系管理员处理',
+    DROPSHIP_PALLET_SNAPSHOT_MISSING: '缺少一件代发托盘快照',
+    DROPSHIP_PALLET_COUNT_MISMATCH: '一件代发计划托数与头程已封托托盘数不一致，请重新走单',
+    PALLET_COUNT_NOT_READY: '计划托数暂未就绪',
+  }
+  return [...new Set(blockers.map((code) => labels[code] || '计划数据暂未就绪，请刷新或联系管理员'))].join('；') || '—'
+}
+
+watch(containerConvertOpen, (open) => {
+  if (open) return
+  containerPreviewRequest += 1
+  containerPreviewLoadingBookingId = ''
+  containerPreviewLoading.value = false
+  containerPreview.value = null
+  containerPreviewError.value = ''
+  containerConversionResult.value = null
+  containerConversionIdempotencyKey = ''
+})
+
+function rowActionCount(source: object) {
+  const row = source as LastMileOrderListItem
+  return 1
+    + Number(access.can(permission.warehouseTransferApprove) && row.orderTypeCode === 'WAREHOUSE_TRANSFER' && row.currentStatusCode === 'PENDING_REVIEW')
+    + Number(access.can(permission.inboundOrderCreate))
+    + (access.can(permission.lastMileOrderTransfer) ? 2 : 0)
+}
+function openDetail(source: object) {
+  const row = source as LastMileOrderListItem
+  void router.push({ name: 'overseas-last-mile-order-detail', params: { orderId: row.id } })
+}
+
+function openTransferReview(source: object) {
+  transferReviewTarget.value = source as LastMileOrderListItem
+  transferReviewOpen.value = true
+}
+
+onMounted(() => { void load() })
+</script>
+
+<template>
+  <AdminPage class="admin-density"><OperationErrorToast :details="actionError" /><ListPageLayout aria-label="尾程订单列表">
+    <template #toolbar>
+      <section class="surface-panel last-mile-toolbar" aria-label="尾程订单状态与筛选">
+        <el-radio-group v-model="statusTab" aria-label="尾程订单状态" @change="changeStatusTab">
+          <el-radio-button value="全部">全部</el-radio-button>
+          <el-radio-button value="待分配">待分配</el-radio-button>
+          <!-- 柜子工作台入口暂时隐藏，保留现有实现便于后续恢复。 -->
+          <!-- <el-radio-button value="柜子">柜子工作台（{{ containerTotal }}）</el-radio-button> -->
+        </el-radio-group>
+        <QueryToolbar v-model="filters" :fields="fields" :available-fields="allFields" :loading="loading" ariaLabel="尾程订单筛选" preference-key="overseas-last-mile-orders-query" :search-on-reset="false" @search="search" @reset="reset" />
+      </section>
+    </template>
+    <template v-if="loadError" #state>
+      <LoadErrorState title="尾程订单加载失败" :message="loadError.message" :loading="loading" @retry="load">
+        <template #details><ApiErrorMeta :details="loadError" /></template>
+      </LoadErrorState>
+    </template>
+    <LoadErrorState v-if="actionError" title="尾程订单操作失败" :message="actionError.message" compact>
+      <template #details><ApiErrorMeta :details="actionError" /></template>
+    </LoadErrorState>
+    <section v-if="!loadError && statusTab === '柜子'" class="surface-panel container-workbench" :aria-busy="loading">
+      <header class="container-workbench__header">
+        <div><strong>货柜工作台</strong><span>按柜查看和修改海外接柜仓；整柜计划齐全后自动生成托盘码</span></div>
+        <el-tag type="warning" effect="plain">{{ containerTotal }} 个货柜</el-tag>
+      </header>
+      <div v-if="containerRows.length" class="container-workbench__grid">
+        <article v-for="container in containerRows" :key="container.sourceContainerBookingId" class="container-workbench-card">
+          <span class="container-workbench-card__top"><strong :title="container.containerNo || '柜号待补充'">{{ container.containerNo || '柜号待补充' }}</strong></span>
+          <span class="container-workbench-card__warehouse">
+            <small>海外接柜仓</small><strong :title="receivingWarehouseLabel(container)">{{ receivingWarehouseLabel(container) }}</strong>
+            <small v-if="containerSnapshotBlockReason(container)" class="is-locked" :title="containerSnapshotBlockReason(container)">{{ containerSnapshotBlockReason(container) }}</small>
+            <small v-else-if="!container.canChangeReceivingWarehouse && container.receivingWarehouseLockReason" class="is-locked" :title="container.receivingWarehouseLockReason">{{ container.receivingWarehouseLockReason }}</small>
+          </span>
+          <span class="container-workbench-card__arrival"><small>计划到仓</small><strong>{{ formatDateTime(container.plannedArrivalAt) }}</strong></span>
+          <span class="container-workbench-card__pending">
+            <strong>{{ pendingInboundCodeCount(container) }}</strong><span>个入仓码待生成计划</span>
+          </span>
+          <span class="container-workbench-card__facts">
+            <span>共 {{ container.inboundCodeCount }} 个入仓码</span>
+            <span v-if="container.resourcePendingPlanCount">托盘码自动生成异常，可重试</span>
+          </span>
+          <span class="container-workbench-card__actions density-actions">
+            <el-button class="container-workbench-card__detail" plain @click="openContainerDetail(container)">查看详情</el-button>
+            <el-tooltip :content="receivingWarehouseChangeDisabledReason(container)" :disabled="!receivingWarehouseChangeDisabledReason(container)" placement="top">
+              <span><el-button plain :title="receivingWarehouseChangeDisabledReason(container) || '修改接柜仓'" :disabled="Boolean(receivingWarehouseChangeDisabledReason(container))" @click="openReceivingWarehouseChange(container)"><Pencil :size="15" />修改接柜仓</el-button></span>
+            </el-tooltip>
+            <el-button v-if="access.can(permission.inboundOrderCreate)" type="primary" :disabled="actionLoading || !canGenerateContainerPlans(container)" @click="openContainerConversionFor(container)">{{ container.resourcePendingPlanCount && !container.pendingPlanCount ? '重试生成托盘码' : '生成入库计划' }}</el-button>
+          </span>
+        </article>
+      </div>
+      <el-empty v-else-if="!loading" description="暂无货柜数据" />
+      <div v-if="containerTotal" class="container-workbench__pagination">
+        <span>共 {{ containerTotal }} 个货柜</span>
+        <el-pagination :current-page="page" :page-size="pageSize" :page-sizes="[10, 20, 50]" :total="containerTotal" layout="sizes, prev, pager, next" background @current-change="changeContainerPage" @size-change="changeContainerPageSize" />
+      </div>
+    </section>
+    <section v-else-if="!loadError" class="surface-panel table-panel"><DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :loading="loading" :total="total" preference-key="overseas-last-mile-orders" row-key="id" empty-text="暂无尾程订单" @selection-change="onSelectionChange" @update:page="load()" @update:page-size="page = 1; load()">
+      <template #toolbar-actions><el-button v-if="access.can(permission.lastMileOrderExport)" plain :loading="exportLoading" @click="exportOrders"><Download :size="16" />导出订单</el-button><el-button v-if="access.can(permission.lastMileOrderTransfer)" plain :disabled="!selectedRows.length || actionLoading" @click="openTransfer">转仓</el-button><el-button v-if="access.can(permission.inboundOrderCreate)" type="primary" plain :disabled="selectedRows.length !== 1 || actionLoading" @click="openInboundPlan()">生成入库计划</el-button><el-button v-if="statusTab === '待分配' && access.can(permission.inboundOrderCreate)" type="primary" :disabled="actionLoading" @click="openContainerConversion">按柜批量生成</el-button></template>
+      <template #actions="{ row }"><div class="row-actions density-actions"><el-button class="density-action" data-tone="neutral" size="small" @click="openDetail(row)">查看</el-button><el-button class="density-action" data-tone="warning" v-if="access.can(permission.warehouseTransferApprove) && row.orderTypeCode === 'WAREHOUSE_TRANSFER' && row.currentStatusCode === 'PENDING_REVIEW'" size="small" @click="openTransferReview(row)">审核</el-button><el-button class="density-action" data-tone="neutral" v-if="access.can(permission.inboundOrderCreate)" :disabled="row.detained" size="small" @click="openInboundPlan(row)">入库计划</el-button><template v-if="rowActionCount(row) <= 3 && access.can(permission.lastMileOrderTransfer)"><el-button class="density-action" data-tone="warning" size="small" @click="openHold(row)">{{ row.detained ? '解除暂扣' : '暂扣订单' }}</el-button><el-button class="density-action" data-tone="neutral" size="small" @click="openManualNodes(row)">人工修改节点</el-button></template><el-dropdown v-if="rowActionCount(row) > 3" trigger="click"><el-button class="density-action" :aria-label="`更多操作 · ${row.orderNo || row.dispatchNo || '当前记录'}`" title="更多操作" data-tone="neutral" size="small" ><MoreHorizontal aria-hidden="true" :size="15" /></el-button><template #dropdown><el-dropdown-menu><el-dropdown-item v-if="access.can(permission.lastMileOrderTransfer)" @click="openHold(row)">{{ row.detained ? '解除暂扣' : '暂扣订单' }}</el-dropdown-item><el-dropdown-item v-if="access.can(permission.lastMileOrderTransfer)" @click="openManualNodes(row)">人工修改节点</el-dropdown-item></el-dropdown-menu></template></el-dropdown></div></template>
+      <template #orderNo="{ row }"><OrderReferenceText :value="String(row.orderNo || '')" copyable /></template>
+      <template #pagination-left>共 {{ total }} 条尾程订单 · 已选 {{ selectedRows.length }} 条</template>
+    </DataTable></section>
+  </ListPageLayout></AdminPage>
+  <WarehouseTransferReviewDialog v-if="transferReviewTarget" v-model="transferReviewOpen" :customer-id="transferReviewTarget.customerId" :customer-name="transferReviewTarget.owner" :transfer-no="transferReviewTarget.orderNo" @reviewed="load()" />
+  <AppDialog class="admin-density-dialog" v-model="transferOpen" title="转仓" confirm-text="确认转仓" :loading="transferWarehouseLoading" :confirm-loading="actionLoading" :confirm-disabled="!transferForm.warehouseId || Boolean(transferWarehouseError)" @confirm="submitTransfer">
+    <LoadErrorState v-if="transferWarehouseError" title="FBA 仓候选加载失败" :message="transferWarehouseError.message" compact @retry="loadTransferWarehouseOptions">
+      <template #details><ApiErrorMeta :details="transferWarehouseError" /></template>
+    </LoadErrorState>
+    <el-form class="density-form" v-else label-position="top">
+      <el-form-item label="目的 FBA 仓" required>
+        <el-select v-model="transferForm.warehouseId" filterable clearable placeholder="请选择目的 FBA 仓" @update:model-value="selectTransferWarehouse">
+          <el-option v-for="warehouse in transferWarehouseOptions" :key="warehouse.warehouseId" :label="warehouse.label" :value="warehouse.warehouseId" />
+        </el-select>
+      </el-form-item>
+      <el-alert v-if="!transferWarehouseLoading && !transferWarehouseOptions.length" title="暂无可用 FBA 仓候选" type="info" :closable="false" show-icon />
+      <el-form-item label="备注"><el-input v-model="transferForm.remark" type="textarea" maxlength="500" placeholder="请输入转仓备注（选填）" /></el-form-item>
+    </el-form>
+  </AppDialog>
+  <AppDialog class="admin-density-dialog" v-model="containerConvertOpen" title="按柜生成入库计划预览" width="min(1240px, calc(100vw - 80px))" :confirm-text="containerConversionResult ? '已生成' : '确认生成'" :loading="containerOptionsLoading || containerPreviewLoading" :confirm-loading="actionLoading" :confirm-disabled="containerConfirmDisabled" @confirm="confirmContainerInboundPlans">
+    <p class="container-convert-hint">先读取服务端全柜预览，确认分组、托数和阻断原因；确认后整柜只提交一次生成命令。</p>
+    <LoadErrorState v-if="containerLoadError" title="待分配柜加载失败" :message="containerLoadError.message" compact @retry="loadContainerOptions()">
+      <template #details><ApiErrorMeta :details="containerLoadError" /></template>
+    </LoadErrorState>
+    <el-form class="density-form" v-else label-position="top">
+      <el-form-item label="选择待分配柜" required>
+        <el-select v-model="selectedContainerBookingId" filterable remote clearable :remote-method="loadContainerOptions" :loading="containerOptionsLoading" :disabled="actionLoading" placeholder="输入柜号搜索并选择" @change="loadContainerPreview">
+          <el-option v-for="container in containerOptions" :key="container.sourceContainerBookingId" :value="container.sourceContainerBookingId" :label="`${container.containerNo || '柜号缺失'} · ${container.totalOrderCount} 票`" />
+        </el-select>
+      </el-form-item>
+    </el-form>
+    <el-alert v-if="containerPreviewError" class="container-convert-alert" type="error" :closable="false" show-icon :title="containerPreviewError" />
+    <div v-if="containerPreview" class="container-preview">
+      <div class="container-preview__context">
+        <div class="container-preview__identity text-ellipsis" :title="containerPreview.containerNo || containerPreview.sourceContainerBookingId">{{ containerPreview.containerNo || '未录入货柜号' }}</div>
+        <div class="container-preview__warehouse text-ellipsis" :title="[containerPreview.overseasWarehouseCode, containerPreview.overseasWarehouseName].filter(Boolean).join(' / ') || '未关联海外仓'">{{ [containerPreview.overseasWarehouseCode, containerPreview.overseasWarehouseName].filter(Boolean).join(' / ') || '未关联海外仓' }}</div>
+      </div>
+      <div class="container-preview__metrics">
+        <div class="container-preview__metric"><span>头程已有托盘码</span><strong>{{ containerPreview.sourcePalletCount }}</strong></div>
+        <div class="container-preview__metric container-preview__metric--primary"><span>海外仓补充托盘码</span><strong>{{ containerPreview.supplementPalletCount }}</strong></div>
+        <div class="container-preview__metric"><span>最终生成托盘</span><strong>{{ containerPreview.pendingPalletCount }}</strong></div>
+        <div class="container-preview__metric"><span>本次处理订单</span><strong>{{ containerPreview.pendingOrderCount }}</strong></div>
+      </div>
+      <el-alert v-if="containerPreview.blockedOrderCount > 0" class="container-convert-alert" type="error" :closable="false" show-icon title="存在阻断订单，暂不可确认生成；请按下方原因处理后重新预览。" />
+      <el-alert v-else-if="!containerConversionResult" class="container-convert-alert" type="success" :closable="false" show-icon :title="`预览已就绪：头程已有 ${containerPreview.sourcePalletCount} 个托盘码，海外仓补充 ${containerPreview.supplementPalletCount} 个，最终生成 ${containerPreview.pendingPalletCount} 个托盘。`" />
+      <section v-if="containerConversionResult" class="container-conversion-result">
+        <header><strong>生成完成</strong><span>新建 {{ containerConversionResult.newPlanCount }} 个 / 已有 {{ containerConversionResult.existingPlanCount }} 个</span></header>
+        <div class="container-conversion-result__plans">
+          <article v-for="plan in containerConversionResult.plans" :key="plan.planNo" class="container-conversion-result__plan">
+            <div><strong class="text-ellipsis" :title="plan.planNo">{{ plan.planNo }}</strong><el-tag size="small" :type="containerConversionResult.existingPlanNos.has(plan.planNo) ? 'info' : 'success'">{{ containerConversionResult.existingPlanNos.has(plan.planNo) ? '已有计划' : '本次新建' }}</el-tag></div>
+            <p v-if="plan.pallets.length"><span v-for="pallet in plan.pallets" :key="pallet.id" class="container-conversion-result__pallet" :title="pallet.palletNo || '托盘码暂未返回'">{{ pallet.palletNo || '—' }}</span></p>
+            <p v-else class="container-conversion-result__empty">暂无托盘码</p>
+          </article>
+        </div>
+      </section>
+      <div class="container-preview__scroll">
+        <section v-for="group in containerPreview.groups" :key="`${group.destinationType}-${group.destinationWarehouseId || group.destinationWarehouseCode || 'default'}`" class="container-preview__group">
+          <header class="container-preview__group-header">
+            <strong class="text-ellipsis" :title="previewGroupTitle(group)">{{ previewGroupTitle(group) }}：最终 {{ group.pendingPalletCount }} 托</strong>
+            <span>头程已有 {{ group.sourcePalletCount }} 托 / 海外仓补充 {{ group.supplementPalletCount }} 托 / 本次处理 {{ group.pendingOrderCount }} 票</span>
+          </header>
+          <el-table :data="group.orders" size="small" border>
+            <el-table-column label="入仓码" min-width="148" show-overflow-tooltip><template #default="{ row }">{{ row.inboundCode || '—' }}</template></el-table-column>
+            <el-table-column prop="businessOrderNo" label="订单号" min-width="150" show-overflow-tooltip />
+            <el-table-column label="客户" min-width="140" show-overflow-tooltip><template #default="{ row }">{{ row.customerName || '—' }}</template></el-table-column>
+            <el-table-column label="业务类型" min-width="112" show-overflow-tooltip><template #default="{ row }">{{ orderTypeText(row.orderType) }}</template></el-table-column>
+            <el-table-column label="目的地" min-width="190" show-overflow-tooltip><template #default="{ row }">{{ destinationText(row) }}</template></el-table-column>
+            <el-table-column label="头程已有" width="94" align="right"><template #default="{ row }">{{ row.sourcePalletCount }}</template></el-table-column>
+            <el-table-column label="海外仓补充" width="102" align="right"><template #default="{ row }">{{ row.supplementPalletCount }}</template></el-table-column>
+            <el-table-column label="最终托数" width="94" align="right"><template #default="{ row }">{{ row.targetPalletCount }}</template></el-table-column>
+            <el-table-column label="已有计划托数" width="118" align="right"><template #default="{ row }">{{ row.plannedPalletCount ?? '—' }}</template></el-table-column>
+            <el-table-column label="可生成性" width="104"><template #default="{ row }"><el-tag :type="readinessType(row.readiness)" effect="light">{{ readinessText(row.readiness) }}</el-tag></template></el-table-column>
+            <el-table-column label="阻断原因" min-width="210" show-overflow-tooltip><template #default="{ row }">{{ blockerText(row.blockers) }}</template></el-table-column>
+          </el-table>
+        </section>
+      </div>
+    </div>
+  </AppDialog>
+  <AppDialog class="admin-density-dialog" v-model="containerDetailOpen" :title="`柜子详情 · ${containerDetail?.summary.containerNo || '加载中'}`" width="min(1120px, calc(100vw - 40px))" :loading="containerDetailLoading" :show-footer="false">
+    <LoadErrorState v-if="containerDetailError" title="柜级详情加载失败" :message="containerDetailError.message" compact>
+      <template #details><ApiErrorMeta :details="containerDetailError" /></template>
+    </LoadErrorState>
+    <template v-else-if="containerDetail">
+      <div class="container-detail-summary">
+        <span>柜号：{{ containerDetail.summary.containerNo || '—' }}</span>
+        <span :title="`海外接柜仓：${receivingWarehouseLabel(containerDetail.summary)}`">海外接柜仓：{{ receivingWarehouseLabel(containerDetail.summary) }}</span>
+        <span>计划到仓：{{ formatDateTime(containerDetail.summary.plannedArrivalAt) }}</span>
+        <span>订单：{{ containerDetail.summary.totalOrderCount }}</span>
+        <span>入仓码：{{ containerDetail.summary.inboundCodeCount }}</span>
+        <span>入库计划：{{ containerDetail.summary.planCount }}，待生成 {{ pendingInboundCodeCount(containerDetail.summary) }}</span>
+        <span v-if="!containerDetail.summary.canChangeReceivingWarehouse">修改状态：{{ containerDetail.summary.receivingWarehouseLockReason || '当前已锁定' }}</span>
+      </div>
+      <DataTable :data="containerDetail.orders" :columns="containerDetailColumns" :loading="containerDetailLoading" preference-key="overseas-last-mile-container-detail" row-key="orderId" :total="undefined" empty-text="该柜暂无尾程订单">
+        <template #orderStatus="{ row }">{{ lastMileStatusLabel((row as ContainerPlanProgressDetailDto['orders'][number]).orderStatus) }}</template>
+        <template #planStatus="{ row }">{{ inboundPlanStatusLabel((row as ContainerPlanProgressDetailDto['orders'][number]).planStatus) }}</template>
+        <template #plannedArrivalAt="{ row }">{{ formatDateTime((row as ContainerPlanProgressDetailDto['orders'][number]).plannedArrivalAt) }}</template>
+      </DataTable>
+    </template>
+  </AppDialog>
+  <AppDialog class="admin-density-dialog" v-model="receivingWarehouseOpen" title="修改海外接柜仓" width="min(600px, calc(100vw - 28px))" confirm-text="确认修改" :loading="receivingWarehouseLoading" :confirm-loading="actionLoading" :confirm-disabled="!selectedReceivingWarehouse || Boolean(receivingWarehouseError)" @confirm="submitReceivingWarehouseChange">
+    <LoadErrorState v-if="receivingWarehouseError" title="海外接柜仓候选加载失败" :message="receivingWarehouseError.message" compact @retry="loadReceivingWarehouseOptions">
+      <template #details><ApiErrorMeta :details="receivingWarehouseError" /></template>
+    </LoadErrorState>
+    <el-form class="density-form" v-else label-position="top">
+      <el-form-item label="当前海外接柜仓"><el-input :model-value="receivingWarehouseLabel(receivingWarehouseTarget)" readonly /></el-form-item>
+      <el-form-item label="新的海外接柜仓" required>
+        <el-select v-model="receivingWarehouseForm.warehouseId" filterable clearable placeholder="请选择 ACTIVE 海外接柜仓">
+          <el-option v-for="warehouse in receivingWarehouseOptions" :key="warehouse.warehouseId" :label="warehouse.label" :value="warehouse.warehouseId" :disabled="warehouse.warehouseId === receivingWarehouseTarget?.overseasWarehouseId" />
+        </el-select>
+      </el-form-item>
+      <el-alert v-if="receivingWarehouseForm.warehouseId === receivingWarehouseTarget?.overseasWarehouseId" title="新的海外接柜仓必须与当前仓不同" type="warning" :closable="false" show-icon />
+      <el-alert v-if="!receivingWarehouseLoading && !receivingWarehouseOptions.length" title="暂无可用的 ACTIVE 海外接柜仓" type="info" :closable="false" show-icon />
+      <el-form-item label="备注"><el-input v-model="receivingWarehouseForm.remark" type="textarea" :rows="3" maxlength="500" show-word-limit placeholder="请输入修改备注（选填）" /></el-form-item>
+      <LoadErrorState v-if="receivingWarehouseActionError" title="海外接柜仓修改失败" :message="receivingWarehouseActionError.message" compact>
+        <template #details><ApiErrorMeta :details="receivingWarehouseActionError" /></template>
+      </LoadErrorState>
+    </el-form>
+  </AppDialog>
+  <AppDialog class="admin-density-dialog" v-model="inboundPlanOpen" title="入库计划" width="min(720px, calc(100vw - 28px))" confirm-text="保存并生成入库单" :loading="inboundPlanPreviewLoading" :confirm-loading="actionLoading" :confirm-disabled="inboundPlanSubmitDisabled" @confirm="submitInboundPlan">
+    <el-alert title="保存后生成入库单；清关完成后入库计划不可更改。" type="info" :closable="false" show-icon />
+    <el-alert v-if="inboundPlanPreviewError" class="container-convert-alert" :title="inboundPlanPreviewError" type="error" :closable="false" show-icon />
+    <el-form class="command-form density-form" label-position="top">
+      <div class="command-form__grid"><el-form-item label="预计到仓时间"><el-input :model-value="inboundPlanExpectedArrival" disabled placeholder="当前柜预计到仓时间" /><small>取整柜预计到仓时间，同柜所有入库计划保持一致。</small></el-form-item><el-form-item label="计划入库仓"><el-input :model-value="inboundPlanWarehouseLabel" disabled placeholder="当前柜接柜仓" /><small>接柜仓按柜统一；如需变更，请在柜子工作台执行“变更接柜仓”。</small></el-form-item><el-form-item label="入仓码"><el-input :model-value="inboundPlanForm.inboundCode" disabled placeholder="订单冻结入仓码" /></el-form-item><el-form-item label="托数" required><el-input-number v-model="inboundPlanForm.palletCount" :min="inboundPlanMinimumPalletCount" :max="inboundPlanIsDropship ? inboundPlanMinimumPalletCount : 999" :disabled="inboundPlanIsDropship" controls-position="right" placeholder="请输入托数" /><small v-if="inboundPlanIsDropship">一件代发固定按头程已封托托盘数整体入库，不可增减。</small><small v-else>按柜级预览至少 {{ inboundPlanMinimumPalletCount }} 托，可增加，不能减少。</small></el-form-item><el-form-item label="托盘类型"><el-select v-model="inboundPlanForm.palletType" placeholder="请选择托盘类型"><el-option label="标准托盘" value="STANDARD" /><el-option label="木托盘" value="WOOD" /><el-option label="纸托盘" value="PAPER" /></el-select></el-form-item><el-form-item label="是否分配"><el-switch v-model="inboundPlanForm.assigned" inline-prompt active-text="是" inactive-text="否" /></el-form-item><el-form-item label="允许合托"><el-switch v-model="inboundPlanForm.mergeRequired" inline-prompt active-text="是" inactive-text="否" /><small>仅作为现场可选提示，不强制工人合托。</small></el-form-item><el-form-item label="是否加急"><el-switch v-model="inboundPlanForm.urgent" inline-prompt active-text="是" inactive-text="否" /></el-form-item></div>
+      <el-form-item label="备注"><el-input v-model="inboundPlanForm.remark" type="textarea" :rows="3" maxlength="1000" show-word-limit placeholder="请输入备注（选填）" /></el-form-item>
+    </el-form>
+  </AppDialog>
+  <AppDialog class="admin-density-dialog" v-model="holdOpen" :title="holdForm.held ? '暂扣订单' : '解除暂扣'" width="min(620px, calc(100vw - 28px))" confirm-text="保存" :confirm-loading="actionLoading" @confirm="submitHold">
+    <el-alert :title="holdForm.held ? '暂扣后不可创建出库计划；解除暂扣后恢复出库计划操作。' : '解除暂扣后恢复该订单的出库计划操作。'" type="warning" :closable="false" show-icon />
+    <el-form class="command-form density-form" label-position="top"><div class="command-form__grid"><el-form-item label="暂扣状态" required><el-radio-group v-model="holdForm.held"><el-radio :value="true">暂扣</el-radio><el-radio :value="false">解除暂扣</el-radio></el-radio-group></el-form-item><el-form-item label="是否计费" required><el-radio-group v-model="holdForm.chargeable"><el-radio :value="true">是</el-radio><el-radio :value="false">否</el-radio></el-radio-group></el-form-item></div><el-form-item label="变更原因" required><el-input v-model="holdForm.reason" type="textarea" :rows="4" maxlength="500" show-word-limit placeholder="请输入暂扣或解除暂扣原因" /></el-form-item></el-form>
+  </AppDialog>
+  <AppDialog class="admin-density-dialog" v-model="manualNodesOpen" title="人工修改节点" width="min(700px, calc(100vw - 28px))" confirm-text="保存" :loading="manualNodesLoading" :confirm-loading="actionLoading" @confirm="submitManualNodes">
+    <div class="manual-node-order"><span>尾程单号</span><strong>{{ actionTarget?.orderNo || '—' }}</strong></div>
+    <el-alert title="保存后该订单只显示人工节点，不再跟随柜级节点；请至少填写一个节点时间。" type="warning" :closable="false" show-icon />
+    <div class="manual-node-table"><div class="manual-node-table__head"><span>节点</span><span>节点时间</span></div><div v-for="node in manualNodeDefinitions" :key="node.code" class="manual-node-table__row"><span>{{ node.label }}</span><el-date-picker v-model="manualNodeValues[node.code]" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" placeholder="年/月/日 --:--" /></div></div>
+  </AppDialog>
+</template>
+
+<style scoped>
+.last-mile-toolbar { padding: var(--admin-space-5) var(--admin-space-5) 0; }
+.row-actions { white-space: nowrap; }
+.command-form { margin-top: var(--admin-space-5); }
+.command-form__grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 0 var(--admin-space-5); }
+.command-form :deep(.el-select), .command-form :deep(.el-date-editor), .command-form :deep(.el-input-number) { width: 100%; }
+.manual-node-order { display: flex; justify-content: space-between; gap: var(--admin-space-5); margin-bottom: var(--admin-space-5); padding: var(--admin-space-5) var(--admin-space-5); border: 1px solid var(--cc-border); border-radius: var(--admin-radius); background: var(--cc-surface); }
+.manual-node-table { max-height: 420px; margin-top: var(--admin-space-5); overflow: auto; border: 1px solid var(--cc-border); border-radius: var(--admin-radius); }
+.manual-node-table__head, .manual-node-table__row { display: grid; grid-template-columns: minmax(0, 42fr) minmax(0, 58fr); align-items: center; gap: var(--admin-space-5); padding: var(--admin-space-4) var(--admin-space-5); }
+.manual-node-table__head { position: sticky; top: 0; z-index: 1; background: var(--cc-surface); color: var(--cc-muted); font-size: var(--admin-font-body); font-weight: 600; }
+.manual-node-table__row { border-top: 1px solid var(--cc-border); }
+.manual-node-table__row :deep(.el-date-editor) { width: 100%; }
+.last-mile-toolbar :deep(.query-toolbar) { margin-top: var(--admin-space-5); padding: var(--admin-space-5) 0 var(--admin-space-5); border: 0; border-top: 1px solid var(--cc-border); border-radius: 0; }
+.container-convert-hint { margin: 0 0 var(--admin-space-5); color: var(--cc-muted); line-height: 1.6; }
+.container-convert-alert { margin-top: var(--admin-space-5); }
+.container-preview { margin-top: var(--admin-space-5); }
+.container-preview__context, .container-preview__group-header { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-5); }
+.container-preview__identity { color: var(--cc-text); font-size: var(--admin-font-title); font-weight: 700; }
+.container-preview__warehouse, .container-preview__group-header span { color: var(--cc-muted); font-size: var(--admin-font-body); }
+.container-preview__metric span { color: var(--cc-muted); font-size: var(--admin-font-body); }
+.container-preview__metric--primary { border-color: var(--cc-primary); background: #f3f6ff; }
+.container-preview__metric--primary strong { color: var(--cc-primary); }
+.container-preview__metric--danger strong { color: var(--el-color-danger); }
+.container-preview__scroll { max-height: 48vh; margin-top: var(--admin-space-5); padding-right: var(--admin-space-2); overflow-y: auto; }
+.container-preview__group + .container-preview__group { margin-top: var(--admin-space-5); }
+.container-preview__group-header { min-height: 42px; padding: 0 var(--admin-space-5); border: 1px solid var(--cc-border); border-bottom: 0; border-radius: 8px 8px 0 0; background: var(--cc-surface); }
+.container-preview__group-header strong { min-width: 0; color: var(--cc-text); }
+.container-conversion-result { margin-top: var(--admin-space-5); padding: var(--admin-space-5); border: 1px solid #86efac; border-radius: var(--admin-radius); background: #f0fdf4; }
+.container-conversion-result > header { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-5); color: #166534; }
+.container-conversion-result__plans { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: var(--admin-space-3); margin-top: var(--admin-space-5); }
+.container-conversion-result__plan { min-width: 0; padding: var(--admin-space-4) var(--admin-space-5); border: 1px solid #bbf7d0; border-radius: var(--admin-radius); background: #fff; }
+.container-conversion-result__plan > div { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-4); }
+.container-conversion-result__plan p { display: flex; flex-wrap: wrap; gap: var(--admin-space-2); margin: var(--admin-space-3) 0 0; }
+.container-conversion-result__pallet { max-width: 100%; padding: 3px 7px; overflow: hidden; border-radius: var(--admin-radius); background: #dcfce7; color: #166534; font-size: var(--admin-font-caption); text-overflow: ellipsis; white-space: nowrap; }
+.container-conversion-result__empty { color: var(--cc-muted); font-size: var(--admin-font-caption); }
+.text-ellipsis { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.container-detail-summary { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: var(--admin-space-3) var(--admin-space-5); margin-bottom: var(--admin-space-5); padding: var(--admin-space-5) var(--admin-space-5); border: 1px solid var(--cc-border); border-radius: var(--admin-radius); background: var(--cc-surface); font-size: var(--admin-font-body); }
+.container-detail-summary > span { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.container-workbench { padding: var(--admin-space-5); }
+.container-workbench__header { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-5); margin-bottom: var(--admin-space-5); }
+.container-workbench__header > div { display: grid; gap: var(--admin-space-1); }
+.container-workbench__header strong { color: var(--cc-text); font-size: var(--admin-font-section); }
+.container-workbench__header span { color: var(--cc-muted); font-size: var(--admin-font-body); }
+.container-workbench__grid { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: var(--admin-space-5); }
+.container-workbench-card { display: grid; min-width: 0; gap: var(--admin-space-5); padding: var(--admin-space-5); border: 1px solid var(--cc-border); border-radius: var(--admin-radius); background: #fff; color: inherit; font: inherit; text-align: left; transition: border-color .16s ease, box-shadow .16s ease; }
+.container-workbench-card:hover { border-color: var(--cc-primary); box-shadow: none; }
+.container-workbench-card__top { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-5); }
+.container-workbench-card__top strong { min-width: 0; overflow: hidden; color: var(--cc-text); font-size: var(--admin-font-section); text-overflow: ellipsis; white-space: nowrap; }
+.container-workbench-card__top > span { flex: 0 0 auto; color: var(--cc-primary); font-size: var(--admin-font-body); }
+.container-workbench-card__arrival { display: grid; gap: var(--admin-space-1); }
+.container-workbench-card__arrival small { color: var(--cc-muted); font-size: var(--admin-font-caption); }
+.container-workbench-card__arrival strong { color: var(--cc-text); font-size: var(--admin-font-section); }
+.container-workbench-card__warehouse { display: grid; gap: var(--admin-space-1); }
+.container-workbench-card__warehouse small { color: var(--cc-muted); font-size: var(--admin-font-caption); }
+.container-workbench-card__warehouse strong { min-width: 0; overflow: hidden; color: var(--cc-text); font-size: var(--admin-font-section); text-overflow: ellipsis; white-space: nowrap; }
+.container-workbench-card__warehouse .is-locked { min-width: 0; overflow: hidden; color: #c2410c; text-overflow: ellipsis; white-space: nowrap; }
+.container-workbench-card__pending { display: flex; align-items: baseline; gap: var(--admin-space-3); padding: var(--admin-space-5) var(--admin-space-5); border-left: 3px solid #f59e0b; background: #fffaf0; }
+.container-workbench-card__pending strong { color: #b45309; font-size: var(--admin-font-title); line-height: 1; }
+.container-workbench-card__pending span { color: #92400e; font-size: var(--admin-font-body); }
+.container-workbench-card__facts { display: flex; flex-wrap: wrap; gap: var(--admin-space-2) var(--admin-space-5); color: var(--cc-muted); font-size: var(--admin-font-caption); }
+.container-workbench-card__facts .is-warning { color: #c2410c; }
+.container-workbench-card__actions { display: flex; justify-content: flex-end; padding-top: 2px; white-space: nowrap; }
+.container-workbench__pagination { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-5); margin-top: var(--admin-space-5); padding-top: var(--admin-space-5); border-top: 1px solid var(--cc-border); color: var(--cc-muted); font-size: var(--admin-font-body); }
+@media (max-width: 1380px) { .container-workbench__grid { grid-template-columns: repeat(2, minmax(0, 1fr)); } }
+
+.container-preview__metrics { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 0; margin: var(--admin-space-5) 0; border: 1px solid var(--cc-border); }
+.container-preview__metric { display: flex; min-height: var(--admin-row-height); padding: var(--admin-space-5) var(--admin-space-5); border: 0; border-radius: 0; background: var(--admin-surface); flex-direction: row; justify-content: flex-start; align-items: baseline; gap: var(--admin-space-3); border-right: 1px solid var(--cc-border); }
+.container-preview__metric:last-child { border-right: 0; }
+.container-preview__metric strong { margin-top: var(--admin-space-1); color: var(--cc-text); font-size: var(--admin-font-body); line-height: 20px; margin: 0; }
+
+</style>
diff --git a/src/modules/overseas-warehouse/pages/OutboundDetailView.test.ts b/src/modules/overseas-warehouse/pages/OutboundDetailView.test.ts
new file mode 100644
index 00000000..7ad5c149
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/OutboundDetailView.test.ts
@@ -0,0 +1,108 @@
+import ElementPlus from 'element-plus'
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { getOutbound } from '../api/outbounds'
+import OutboundDetailView from './OutboundDetailView.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+
+const canPermission = vi.hoisted(() => vi.fn((_code: string) => false))
+vi.mock('@/core/access/accessPreview', () => ({ useAccessPreviewStore: () => ({ can: canPermission }) }))
+vi.mock('vue-router', () => ({ useRoute: () => ({ params: { outboundNo: 'OUT/1' } }), useRouter: () => ({ push: vi.fn() }) }))
+vi.mock('../api/outbounds', () => ({ getOutbound: vi.fn(), cancelOutbound: vi.fn() }))
+
+describe('OutboundDetailView', () => {
+  it.each([
+    ['WAIT_PICK', '待拣货', 'warning'], ['WAIT_OUTBOUND', '待出库', 'warning'], ['PICKING', '拣货中', 'info'],
+    ['PICKED', '已拣货', 'warning'], ['OUTBOUNDED', '已出库', 'success'], ['CANCELLED', '已取消', 'danger'],
+  ])('uses the same shared status tone as the list for %s', async (status, label, tone) => {
+    vi.mocked(getOutbound).mockResolvedValueOnce({ outbound: { id: '1', outboundNo: 'OUT/1', status }, pallets: [], deliveries: [] })
+    const wrapper = mount(OutboundDetailView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    const badge = wrapper.findComponent(StatusBadge)
+    expect(badge.text()).toBe(label)
+    expect(badge.classes()).toContain(`is-${tone}`)
+    wrapper.unmount()
+  })
+
+  beforeEach(() => {
+    canPermission.mockReset().mockReturnValue(false)
+    vi.mocked(getOutbound).mockReset().mockResolvedValue({
+      outbound: { id: '1', outboundNo: 'OUT/1', dispatchNo: 'PC-1', status: 'PICKED', palletCount: 2, packageCount: 20, createdAt: '2026-09-01T10:00:00' },
+      pallets: [{ palletNo: 'IP-ACY2-20260907-597057-P001', inboundCode: 'NYEXX2609060063', destinationWarehouseCode: 'ONT8', destinationWarehouseName: 'Amazon ONT8', skuCode: 'SKU-001', packageCount: 20 }],
+      deliveries: [
+        { version: 2, allowedActions: ['START_DELIVERY'], id: '2', customerId: 'customer-1', deliveryNo: 'DEL-ONT8', outboundNo: 'OUT/1', dispatchNo: 'PC-1', status: 'WAIT_DELIVERY', destinationWarehouseCode: 'ONT8', palletCount: 1, packageCount: 10, createdAt: '2026-09-01T10:00:00' },
+        { version: 2, allowedActions: ['START_DELIVERY'], id: '3', customerId: 'customer-1', deliveryNo: 'DEL-ACY2', outboundNo: 'OUT/1', dispatchNo: 'PC-1', status: 'WAIT_DELIVERY', destinationWarehouseCode: 'ACY2', palletCount: 1, packageCount: 10, createdAt: '2026-09-01T10:00:00' },
+      ],
+    })
+  })
+
+  it('loads by encoded business outbound number and remains read-only without cancel permission', async () => {
+    const wrapper = mount(OutboundDetailView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(getOutbound).toHaveBeenCalledWith('OUT/1')
+    expect(wrapper.text()).toContain('OUT/1')
+    expect(wrapper.text()).toContain('PC-1')
+    expect(wrapper.text()).toContain('DEL-ONT8')
+    expect(wrapper.text()).toContain('DEL-ACY2')
+    expect(wrapper.text()).toContain('ACY2')
+    expect(wrapper.text()).toContain('出库托盘')
+    expect(wrapper.text()).toContain('IP-ACY2-20260907-597057-P001')
+    expect(wrapper.text()).toContain('NYEXX2609060063')
+    expect(wrapper.text()).toContain('Amazon ONT8')
+    expect(wrapper.text()).toContain('SKU-001')
+    expect(wrapper.findAll('.outbound-pallet-table .data-table__single-line-cell').length).toBeGreaterThanOrEqual(6)
+    expect(wrapper.text()).not.toContain('取消出库单')
+    wrapper.unmount()
+  })
+
+  it('renders pallet missing values consistently and keeps the empty state in the table', async () => {
+    vi.mocked(getOutbound).mockResolvedValueOnce({
+      outbound: { id: '1', outboundNo: 'OUT/1', status: 'OUTBOUNDED' },
+      pallets: [{ palletNo: null, inboundCode: null, destinationWarehouseCode: null, destinationWarehouseName: null, skuCode: null, packageCount: null }],
+      deliveries: [],
+    })
+    const wrapper = mount(OutboundDetailView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(wrapper.get('.outbound-pallet-table').text()).toContain('—')
+    expect(wrapper.text()).toContain('暂无关联派送单')
+    wrapper.unmount()
+
+    vi.mocked(getOutbound).mockResolvedValueOnce({
+      outbound: { id: '1', outboundNo: 'OUT/1', status: 'OUTBOUNDED' },
+      pallets: [],
+      deliveries: [],
+    })
+    const emptyWrapper = mount(OutboundDetailView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(emptyWrapper.text()).toContain('暂无出库托盘')
+    emptyWrapper.unmount()
+  })
+
+  it('shows cancellation only before picking with the independent permission', async () => {
+    canPermission.mockImplementation((code: string) => code === 'platform:overseas-warehouse:outbound:cancel')
+    vi.mocked(getOutbound).mockResolvedValueOnce({ outbound: { id: '1', outboundNo: 'OUT/1', status: 'WAIT_PICK' }, pallets: [], deliveries: [] })
+    const wrapper = mount(OutboundDetailView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(wrapper.text()).toContain('取消出库单')
+    wrapper.unmount()
+  })
+
+  it.each([
+    ['warehouse-internal-id', '洛杉矶仓', '洛杉矶仓'],
+    ['warehouse-internal-id', null, '—'],
+    ['another-warehouse-id', '其他仓库', '—'],
+  ])('uses a matching warehouse name and never displays internal IDs (%s, %s)', async (deliveryWarehouseId, name, expected) => {
+    vi.mocked(getOutbound).mockResolvedValueOnce({
+      outbound: { id: '1', outboundNo: 'OUT/1', overseasWarehouseId: 'warehouse-internal-id' },
+      deliveries: [{ id: '2', customerId: 'customer-1', deliveryNo: 'DEL-1', outboundNo: 'OUT/1', dispatchNo: 'PC-1', status: 'WAIT_DELIVERY', palletCount: 2, packageCount: 20, createdAt: '2026-09-01T10:00:00', version: 1, allowedActions: [], overseasWarehouseId: deliveryWarehouseId, overseasWarehouseName: name }],
+    })
+    const wrapper = mount(OutboundDetailView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    const labels = wrapper.findAll('.el-descriptions__label')
+    const label = labels.find(item => item.text() === '海外仓')!
+    expect(label.element.nextElementSibling?.textContent?.trim()).toBe(expected)
+    expect(wrapper.text()).not.toContain('warehouse-internal-id')
+    expect(wrapper.text()).not.toContain('another-warehouse-id')
+    wrapper.unmount()
+  })
+})
diff --git a/src/modules/overseas-warehouse/pages/OutboundDetailView.vue b/src/modules/overseas-warehouse/pages/OutboundDetailView.vue
new file mode 100644
index 00000000..6f917163
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/OutboundDetailView.vue
@@ -0,0 +1,71 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, ref, watch } from 'vue'
+import { ArrowLeft, XCircle } from '@lucide/vue'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import { useRoute, useRouter } from 'vue-router'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import DetailPageLayout from '@/shared/components/DetailPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import OperationErrorToast from '@/shared/components/OperationErrorToast.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { cancelOutbound, getOutbound, type OutboundDetail } from '../api/outbounds'
+import { formatOverseasDateTime } from '../lastMilePresentation'
+import { overseasWarehousePermissions as permission } from '../permissions'
+
+const route = useRoute(); const router = useRouter(); const access = useAccessPreviewStore()
+const outboundNo = computed(() => String(route.params.outboundNo || '').trim())
+const detail = ref<OutboundDetail | null>(null); const loading = ref(false); const cancelling = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null); const mutationError = ref<ApiErrorDetails | null>(null)
+const statusLabels: Record<string, string> = { WAIT_PICK: '待拣货', WAIT_OUTBOUND: '待出库', PICKING: '拣货中', PICKED: '已拣货', OUTBOUNDED: '已出库', CANCELLED: '已取消' }
+const palletColumns: DataTableColumn[] = [
+  { key: 'palletNo', label: '托盘码', width: 220 },
+  { key: 'inboundCode', label: '入仓码', width: 190 },
+  { key: 'destinationWarehouseCode', label: '目的仓编码', width: 150 },
+  { key: 'destinationWarehouseName', label: '目的仓名称', minWidth: 180 },
+  { key: 'skuCode', label: '商品 SKU', width: 170 },
+  { key: 'cartonMarks', label: '箱唛', minWidth: 220 },
+  { key: 'packageCount', label: '箱数', width: 100, align: 'right' },
+  { key: 'pickedPackageCount', label: '已拣箱数', width: 110, align: 'right' },
+  { key: 'status', label: '状态', width: 110 },
+]
+function show(value: unknown) { const text = String(value ?? '').trim(); return text || '—' }
+// A warehouse ID is only a join key; never render it as a warehouse name.
+const warehouseLabel = computed(() => {
+  const outboundWarehouseId = detail.value?.outbound.overseasWarehouseId
+  const delivery = detail.value?.deliveries?.find(item => item.overseasWarehouseId === outboundWarehouseId)
+  return outboundWarehouseId && delivery?.overseasWarehouseId === outboundWarehouseId ? show(delivery.overseasWarehouseName) : '—'
+})
+function statusLabel(value: unknown) { const code = String(value || ''); return statusLabels[code] || show(code) }
+function outboundTypeLabel(value?: string | null) { return value === 'ONE_CLICK_DROPSHIP' ? '一件代发出库' : value === 'RETURN_OUTBOUND' ? '退货出库' : value === 'DISPATCH_DELIVERY' ? '派送出库' : show(value) }
+const canCancel = computed(() => access.can(permission.outboundCancel) && ['WAIT_PICK', 'WAIT_OUTBOUND'].includes(String(detail.value?.outbound.status || '')))
+async function load() { if (!outboundNo.value) { loadError.value = { message: '详情缺少出库单号，请从出库单列表重新进入' }; return } loading.value = true; loadError.value = null; try { detail.value = await getOutbound(outboundNo.value) } catch (cause) { detail.value = null; loadError.value = getApiErrorDetails(cause, '出库单详情加载失败，请重试') } finally { loading.value = false } }
+async function cancel() { if (!canCancel.value || cancelling.value) return; let reason = ''; try { const result = await ElMessageBox.prompt(`确认取消出库单 ${outboundNo.value}？`, '取消出库单', { customClass: 'admin-density-confirm', inputType: 'textarea', inputPlaceholder: '请输入取消原因', inputPattern: /\S+/, inputErrorMessage: '请输入取消原因', confirmButtonText: '确认取消', cancelButtonText: '返回', type: 'warning' }); reason = result.value.trim() } catch { return } cancelling.value = true; mutationError.value = null; try { await cancelOutbound(outboundNo.value, reason); ElMessage.success('出库单已取消'); await load() } catch (cause) { mutationError.value = getApiErrorDetails(cause, '取消出库单失败，请重试') } finally { cancelling.value = false } }
+function back() { void router.push({ name: 'overseas-outbounds' }) }
+watch(outboundNo, () => { void load() }, { immediate: true })
+</script>
+
+<template>
+  <AdminPage class="admin-density"><DetailPageLayout aria-label="出库单详情">
+    <template #header><div class="detail-heading"><el-button class="density-back" link aria-label="返回出库单列表" @click="back"><ArrowLeft :size="16" />返回</el-button><div class="detail-title"><div><h1>出库单详情</h1><p>出库单号 {{ outboundNo }}</p></div><StatusBadge v-if="detail" :status="statusLabel(detail.outbound.status)" /></div><el-button v-if="canCancel" type="danger" plain :loading="cancelling" @click="cancel"><XCircle :size="16" />取消出库单</el-button></div></template>
+    <OperationErrorToast :details="mutationError" />
+    <LoadErrorState v-if="loadError" title="出库单详情加载失败" :message="loadError.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="loadError" /></template></LoadErrorState>
+    <template v-else-if="detail"><section class="surface-panel detail-section"><h2>出库信息</h2><el-descriptions class="density-descriptions" :column="4" border><el-descriptions-item label="出库单号">{{ show(detail.outbound.outboundNo) }}</el-descriptions-item><el-descriptions-item label="出库类型">{{ outboundTypeLabel(detail.outbound.outboundType) }}</el-descriptions-item><el-descriptions-item label="关联排车单">{{ show(detail.outbound.dispatchNo) }}</el-descriptions-item><el-descriptions-item label="状态">{{ statusLabel(detail.outbound.status) }}</el-descriptions-item><el-descriptions-item label="海外仓">{{ warehouseLabel }}</el-descriptions-item><el-descriptions-item label="托盘数">{{ detail.outbound.palletCount ?? '—' }}</el-descriptions-item><el-descriptions-item label="箱数">{{ detail.outbound.packageCount ?? '—' }}</el-descriptions-item><el-descriptions-item label="创建时间">{{ formatOverseasDateTime(detail.outbound.createdAt) }}</el-descriptions-item></el-descriptions></section><section class="surface-panel detail-section"><h2>出库托盘</h2><DataTable class="outbound-pallet-table" aria-label="出库托盘" :data="detail.pallets || []" :columns="palletColumns" stripe column-settings-mode="hide" empty-text="暂无出库托盘" /></section><section class="surface-panel detail-section"><h2>关联派送</h2><el-empty v-if="!detail.deliveries?.length" description="暂无关联派送单" :image-size="56" /><div v-else class="delivery-list"><el-descriptions v-for="delivery in detail.deliveries" :key="delivery.deliveryNo" class="density-descriptions" :column="4" border><el-descriptions-item label="目的 FBA 仓">{{ show(delivery.destinationWarehouseCode || delivery.destinationWarehouseName) }}</el-descriptions-item><el-descriptions-item label="派送单号">{{ show(delivery.deliveryNo) }}</el-descriptions-item><el-descriptions-item label="派送状态">{{ statusLabel(delivery.status) }}</el-descriptions-item><el-descriptions-item label="运单号">{{ show(delivery.waybillNo) }}</el-descriptions-item><el-descriptions-item label="承运商">{{ show(delivery.carrierName) }}</el-descriptions-item><el-descriptions-item label="司机">{{ show(delivery.driverName) }}</el-descriptions-item><el-descriptions-item label="车牌">{{ show(delivery.vehiclePlate) }}</el-descriptions-item><el-descriptions-item label="计划派送">{{ formatOverseasDateTime(delivery.plannedDeliveryAt) }}</el-descriptions-item><el-descriptions-item label="托盘数">{{ delivery.palletCount }}</el-descriptions-item><el-descriptions-item label="箱数">{{ delivery.packageCount }}</el-descriptions-item><el-descriptions-item label="备注" :span="2">{{ show(delivery.remark) }}</el-descriptions-item></el-descriptions></div></section></template>
+  </DetailPageLayout></AdminPage>
+</template>
+
+<style scoped>.detail-heading{display:flex;min-width:0;align-items:center;gap:var(--admin-space-5)}.detail-section h2{margin:0 0 var(--admin-space-5);font-size:var(--admin-font-section)}.detail-section+.detail-section{margin-top:var(--admin-space-5)}.delivery-list{display:grid;gap:var(--admin-space-4)}@media(max-width:1200px){.detail-section :deep(.el-descriptions__body .el-descriptions__table){table-layout:auto}}@media(max-width:720px){.detail-heading,.detail-title{align-items:flex-start;flex-direction:column}}
+:deep(.detail-page-layout) { gap: 0; background: var(--admin-surface); border: 1px solid var(--cc-border); }
+:deep(.detail-page-layout__header) { padding: var(--admin-space-5); border-bottom: 1px solid var(--cc-border); }
+.detail-title {display:flex;min-width:0;flex:1;align-items:center; justify-content: flex-start;gap:var(--admin-space-5); }
+.detail-title > div { display: flex; align-items: baseline; gap: var(--admin-space-5); flex-wrap: wrap; }
+.detail-title h1 {margin:0; font-size: var(--admin-font-section); font-weight: 500; }
+.detail-title p { margin: 0;color:var(--cc-muted); font-size: var(--admin-font-title); font-weight: 600; overflow-wrap: anywhere; }
+.detail-section {padding:var(--admin-space-5); border: 0; border-radius: 0; }
+.detail-section + .detail-section { margin-top: 0; border-top: 1px solid var(--cc-border); }
+
+</style>
diff --git a/src/modules/overseas-warehouse/pages/OutboundsView.selection.test.ts b/src/modules/overseas-warehouse/pages/OutboundsView.selection.test.ts
new file mode 100644
index 00000000..52967e4f
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/OutboundsView.selection.test.ts
@@ -0,0 +1,144 @@
+import ElementPlus, { ElCheckbox, ElInput, ElPagination, ElSelect } from 'element-plus'
+import { flushPromises, mount, type VueWrapper } from '@vue/test-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import OutboundsView from './OutboundsView.vue'
+
+const api = vi.hoisted(() => ({ candidates: vi.fn(), create: vi.fn(), warehouses: vi.fn() }))
+vi.mock('@/core/access/accessPreview', () => ({ useAccessPreviewStore: () => ({ can: () => true }) }))
+vi.mock('vue-router', () => ({ useRouter: () => ({ push: vi.fn() }) }))
+vi.mock('@/modules/iam', () => ({ listPlatformTenants: vi.fn().mockResolvedValue({ records: [] }) }))
+vi.mock('@/modules/warehouses', () => ({ listPlatformWarehouses: api.warehouses }))
+vi.mock('../api/outbounds', () => ({
+  listOutbounds: vi.fn().mockResolvedValue({ records: [], total: 0 }),
+  listOneClickOutboundCandidates: api.candidates,
+  createOneClickDropshipOutbound: api.create,
+  cancelOutbound: vi.fn(), createReturnOutbound: vi.fn(), listReturnOutboundCandidates: vi.fn(),
+}))
+
+const fixtures = Array.from({ length: 7 }, (_, index) => ({
+  inventoryPositionId: `position-${index}`, orderNo: `ORDER-${index}`, customerId: 'customer-a',
+  customerName: '客户甲', overseasWarehouseId: 'warehouse-a', palletNo: `PALLET-${index}`,
+  inboundCode: `IN-${index}`, skuCode: index < 6 ? 'MATCH' : 'OTHER', productName: '测试品名', availablePackages: index + 1,
+}))
+let wrapper: VueWrapper
+async function clickButton(text: string) {
+  const button = wrapper.findAll('button').find(item => item.text().includes(text))
+  expect(button, text).toBeDefined()
+  await button!.trigger('click')
+  await flushPromises()
+}
+async function openCreate() {
+  wrapper = mount(OutboundsView, { global: { plugins: [ElementPlus], stubs: {
+    AppDialog: { props: ['modelValue'], emits: ['confirm'], template: '<section v-if="modelValue"><slot /><button data-test="submit-outbound" @click="$emit(\'confirm\')">提交出库</button></section>' },
+  } } })
+  await flushPromises()
+  await clickButton('新建出库单')
+}
+function candidatePagination() { return wrapper.findAllComponents(ElPagination).find(item => item.props('total') === 7)! }
+function pageCheckbox() { return wrapper.findAllComponents(ElCheckbox).find(item => item.props('ariaLabel') === '全选本页订单')! }
+async function selectBothPages() {
+  pageCheckbox().vm.$emit('change', true)
+  await flushPromises()
+  candidatePagination().vm.$emit('update:current-page', 2)
+  await flushPromises()
+  pageCheckbox().vm.$emit('change', true)
+  await flushPromises()
+}
+
+describe('outbound candidate search and selection', () => {
+  beforeEach(() => {
+    vi.stubGlobal('ResizeObserver', class { observe() {} unobserve() {} disconnect() {} })
+    vi.stubGlobal('localStorage', { getItem: () => null, setItem: () => undefined, removeItem: () => undefined })
+    api.candidates.mockReset().mockResolvedValue(fixtures.map(item => ({ ...item })))
+    api.create.mockReset().mockResolvedValue({})
+    api.warehouses.mockReset().mockResolvedValue({ records: [
+      { id: 'warehouse-a', warehouseName: '洛杉矶仓', warehouseCode: 'US-LAX-01', warehouseType: 'OVERSEAS', status: 'ACTIVE' },
+      { id: 'warehouse-b', warehouseName: '纽约仓', warehouseCode: 'US-NY-01', warehouseType: 'OVERSEAS', status: 'ACTIVE' },
+    ] })
+  })
+  afterEach(() => { wrapper?.unmount(); vi.unstubAllGlobals() })
+
+  it('selects and deselects the current page while preserving other pages, then submits all selected quantities', async () => {
+    await openCreate()
+    pageCheckbox().vm.$emit('change', true)
+    await flushPromises()
+    expect(wrapper.text()).toContain('已选择 5 条')
+    candidatePagination().vm.$emit('update:current-page', 2)
+    await flushPromises()
+    expect(pageCheckbox().props('modelValue')).toBe(false)
+    pageCheckbox().vm.$emit('change', true)
+    await flushPromises()
+    expect(wrapper.text()).toContain('已选择 7 条')
+    pageCheckbox().vm.$emit('change', false)
+    await flushPromises()
+    expect(wrapper.text()).toContain('已选择 5 条')
+    await wrapper.get('[data-test="submit-outbound"]').trigger('click')
+    await flushPromises()
+    expect(api.create).toHaveBeenCalledWith('customer-a', expect.objectContaining({
+      items: fixtures.slice(0, 5).map(item => ({ inventoryPositionId: item.inventoryPositionId, packages: item.availablePackages, sku: item.skuCode, cartonMarks: [] })),
+    }))
+  })
+
+  it('keeps searches on one row without bulk buttons and preserves filtered selection across pages', async () => {
+    await openCreate()
+    expect(wrapper.get('.dropship-search-row').findAll('.el-form-item')).toHaveLength(2)
+    expect(wrapper.find('.candidate-selection').exists()).toBe(false)
+    expect(wrapper.text()).not.toContain('全选筛选结果')
+    expect(wrapper.text()).not.toContain('清空选择')
+    const query = wrapper.findAllComponents(ElInput).find(item => item.props('ariaLabel') === '搜索可出库订单')!
+    await query.get('input').setValue('MATCH')
+    await flushPromises()
+    expect(candidatePagination().props('total')).toBe(7)
+    await query.get('input').trigger('keyup', { key: 'Enter' })
+    await flushPromises()
+    const filteredPagination = wrapper.findAllComponents(ElPagination).find(item => item.props('total') === 6)!
+    expect(filteredPagination).toBeDefined()
+    pageCheckbox().vm.$emit('change', true)
+    await flushPromises()
+    filteredPagination.vm.$emit('update:current-page', 2)
+    await flushPromises()
+    pageCheckbox().vm.$emit('change', true)
+    await flushPromises()
+    expect(wrapper.text()).toContain('已选择 6 条')
+    await wrapper.get('.candidate-query').findAll('button').find(item => item.text() === '重置')!.trigger('click')
+    await flushPromises()
+    candidatePagination().vm.$emit('update:current-page', 2)
+    await flushPromises()
+    expect(pageCheckbox().props('indeterminate')).toBe(true)
+    pageCheckbox().vm.$emit('change', false)
+    await flushPromises()
+    expect(wrapper.get('.candidate-pagination').text()).toContain('已选择 5 条')
+  })
+
+  it('resets the page after page-size changes and clears selection when changing searchable warehouses', async () => {
+    await openCreate()
+    await selectBothPages()
+    const pagination = candidatePagination()
+    pagination.vm.$emit('update:current-page', 2)
+    await flushPromises()
+    pagination.vm.$emit('update:page-size', 20)
+    pagination.vm.$emit('size-change', 20)
+    await flushPromises()
+    expect(pagination.props('currentPage')).toBe(1)
+    expect(wrapper.text()).toContain('第 1 / 1 页')
+    expect(wrapper.text()).toContain('已选择 7 条')
+    const warehouse = wrapper.findAllComponents(ElSelect).find(item => item.props('ariaLabel') === '搜索海外仓')!
+    expect(warehouse.props('filterable')).toBe(true)
+    warehouse.vm.$emit('update:modelValue', 'warehouse-b')
+    warehouse.vm.$emit('change', 'warehouse-b')
+    await flushPromises()
+    expect(api.candidates).toHaveBeenLastCalledWith(undefined, { warehouseId: 'warehouse-b' })
+    expect(wrapper.text()).toContain('已选择 0 条')
+  })
+
+  it('warns about a multi-customer bulk selection and preserves the submit restriction', async () => {
+    api.candidates.mockResolvedValue([{ ...fixtures[0] }, { ...fixtures[1], customerId: 'customer-b', customerName: '客户乙' }])
+    await openCreate()
+    pageCheckbox().vm.$emit('change', true)
+    await flushPromises()
+    expect(wrapper.text()).toContain('当前选择包含多个客户')
+    await wrapper.get('[data-test="submit-outbound"]').trigger('click')
+    await flushPromises()
+    expect(api.create).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/modules/overseas-warehouse/pages/OutboundsView.test.ts b/src/modules/overseas-warehouse/pages/OutboundsView.test.ts
new file mode 100644
index 00000000..30e9700d
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/OutboundsView.test.ts
@@ -0,0 +1,84 @@
+import ElementPlus from 'element-plus'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { listOutbounds } from '../api/outbounds'
+import OutboundsView from './OutboundsView.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+
+const canPermission = vi.hoisted(() => vi.fn((_code: string) => true))
+const routerPush = vi.hoisted(() => vi.fn())
+vi.mock('@/core/access/accessPreview', () => ({ useAccessPreviewStore: () => ({ can: canPermission }) }))
+vi.mock('vue-router', () => ({ useRouter: () => ({ push: routerPush }) }))
+vi.mock('../api/outbounds', () => ({ listOutbounds: vi.fn(), cancelOutbound: vi.fn(), createOneClickDropshipOutbound: vi.fn() }))
+vi.mock('../api/inventory', () => ({ listInventoryBalances: vi.fn(), listInventoryPositions: vi.fn() }))
+
+class ResizeObserverStub { observe() {} unobserve() {} disconnect() {} }
+
+describe('OutboundsView permissions and navigation', () => {
+  it('distinguishes outbound stages and does not present unknown states as picking', async () => {
+    const statuses = [
+      ['WAIT_PICK', '待拣货', 'warning'], ['WAIT_OUTBOUND', '待出库', 'warning'], ['PICKING', '拣货中', 'info'],
+      ['PICKED', '已拣货', 'warning'], ['OUTBOUNDED', '已出库', 'success'],
+      ['CANCELLED', '已取消', 'danger'], ['FUTURE_STATE', '未知状态', 'neutral'],
+    ]
+    vi.mocked(listOutbounds).mockResolvedValueOnce({ records: statuses.map(([status], index) => ({ id: String(index), outboundNo: `OUT-${index}`, status })), page: 1, size: 20, total: statuses.length, pages: 1 })
+    const wrapper = mount(OutboundsView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    const badges = wrapper.findAllComponents(StatusBadge).filter(badge => badge.element.closest('tbody'))
+    expect(badges).toHaveLength(statuses.length)
+    statuses.forEach(([, label, tone], index) => {
+      expect(badges[index].text()).toBe(label)
+      expect(badges[index].classes()).toContain(`is-${tone}`)
+    })
+    wrapper.unmount()
+  })
+
+  beforeEach(() => {
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+    vi.stubGlobal('localStorage', { getItem: () => null, setItem: () => undefined, removeItem: () => undefined })
+    vi.mocked(listOutbounds).mockReset().mockResolvedValue({ records: [{ id: '1', outboundNo: 'OUT-1', dispatchNo: 'PC-1', status: 'WAIT_PICK', palletCount: 1, packageCount: 2 }], page: 1, size: 20, total: 1, pages: 1 })
+    canPermission.mockReset().mockReturnValue(true)
+    routerPush.mockReset()
+  })
+
+  it('uses list access for detail and independent create/cancel permissions', async () => {
+    canPermission.mockImplementation((code: string) => code.endsWith(':list'))
+    const wrapper = mount(OutboundsView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(wrapper.text()).toContain('详情')
+    expect(wrapper.text()).not.toContain('新建出库单')
+    expect(wrapper.text()).not.toContain('取消')
+    expect(OutboundsView.__file).toContain('OutboundsView.vue')
+    wrapper.unmount()
+  })
+
+  it('shows outbound creation and cancellation only with their exact permissions', async () => {
+    canPermission.mockImplementation((code: string) => ['platform:overseas-warehouse:outbound:create', 'platform:overseas-warehouse:outbound:cancel'].includes(code))
+    const wrapper = mount(OutboundsView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(wrapper.text()).toContain('新建出库单')
+    expect(wrapper.text()).toContain('取消')
+    wrapper.unmount()
+  })
+
+  it('loads one-click candidates across customers and loads return inventory after customer selection', async () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/overseas-warehouse/pages/OutboundsView.vue'), 'utf8')
+    expect(source).toContain('v-model="selectedCustomerId"')
+    expect(source).toContain('listOneClickOutboundCandidates(selectedCustomerId.value || undefined')
+    expect(source).toContain('if (selectedCustomerId.value && selectedWarehouseId.value) await loadReturnCandidates()')
+    expect(source).toContain("createOneClickDropshipOutbound([...customerIds][0] || ''")
+  })
+
+  it('applies batched return filters only through explicit search and exposes page sizes', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/overseas-warehouse/pages/OutboundsView.vue'), 'utf8')
+    expect(source).toContain('returnSkuQueryInput')
+    expect(source).toContain('returnCartonQueryInput')
+    expect(source).toContain("item.replace(/\\s+/g, '')")
+    expect(source).toContain('@click="searchReturnSkus"')
+    expect(source).toContain('@click="searchReturnCartons"')
+    expect(source).toContain(':page-sizes="[5, 10, 20, 50]"')
+    expect(source).toContain('width="min(1320px, calc(100vw - 32px))"')
+  })
+})
diff --git a/src/modules/overseas-warehouse/pages/OutboundsView.vue b/src/modules/overseas-warehouse/pages/OutboundsView.vue
new file mode 100644
index 00000000..004c23e7
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/OutboundsView.vue
@@ -0,0 +1,245 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, ref } from 'vue'
+import { Plus, Search } from '@lucide/vue'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import { useRouter } from 'vue-router'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import OperationErrorToast from '@/shared/components/OperationErrorToast.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { cancelOutbound, createOneClickDropshipOutbound, createReturnOutbound, listOneClickOutboundCandidates, listReturnOutboundCandidates, listOutbounds, type OneClickOutboundCandidate, type OutboundRow, type ReturnOutboundCandidate } from '../api/outbounds'
+import { type InventoryBalanceDto, type InventoryPositionDto } from '../api/inventory'
+import { formatOverseasDateTime } from '../lastMilePresentation'
+import { overseasWarehousePermissions as permission } from '../permissions'
+import { listPlatformTenants, type PlatformTenantResource } from '@/modules/iam'
+import { listPlatformWarehouses, type PlatformWarehouseSummaryResource } from '@/modules/warehouses'
+import { getReturnCarton, listReturnCartons, listReturnStock, type ReturnCartonDetail, type ReturnCartonRow, type ReturnStockRow } from '../api/returnInventory'
+
+const router = useRouter(); const access = useAccessPreviewStore()
+const rows = ref<OutboundRow[]>([]); const page = ref(1); const pageSize = ref(20); const total = ref(0); const loading = ref(false); const error = ref<ApiErrorDetails | null>(null); const mutationError = ref<ApiErrorDetails | null>(null)
+const filters = ref<QueryModel>({ documentNo: '', lxCode: '', warehouseId: '', status: '', outboundType: '' }); const createOpen = ref(false); const saving = ref(false); const recipient = ref(''); const remark = ref(''); const quantity = ref<number | undefined>(); const cartonMarks = ref(''); const selectedReturnMarks = ref<string[]>([]); const selectedCustomerId = ref(''); const selectedPositionId = ref(''); const positionOptions = ref<Array<{ balance: InventoryBalanceDto; position: InventoryPositionDto }>>([]); const dropshipCandidates = ref<OneClickOutboundCandidate[]>([]); const selectedDropshipIds = ref<string[]>([]); const returnCandidates = ref<ReturnOutboundCandidate[]>([]); const selectedWarehouseId = ref(''); const selectedReturnNo = ref(''); const outboundType = ref<'ONE_CLICK_DROPSHIP' | 'RETURN_OUTBOUND'>('ONE_CLICK_DROPSHIP'); const inventoryLoading = ref(false); const dropshipQueryInput = ref(''); const dropshipQuery = ref(''); const dropshipPage = ref(1); const dropshipPageSize = ref(5)
+const tenantOptions = ref<PlatformTenantResource[]>([])
+const warehouseOptionsSource = ref<PlatformWarehouseSummaryResource[]>([])
+const returnStockRows = ref<ReturnStockRow[]>([])
+const returnCartonRows = ref<ReturnCartonRow[]>([])
+const selectedReturnSkus = ref<string[]>([])
+const returnSkuQueryInput = ref(''); const returnSkuQuery = ref('')
+const returnCartonQueryInput = ref(''); const returnCartonQuery = ref('')
+const returnSkuPage = ref(1); const returnCartonPage = ref(1)
+const returnSkuPageSize = ref(5); const returnCartonPageSize = ref(5)
+const returnCartonDetails = ref<Record<string, ReturnCartonDetail>>({})
+const customerOptions = computed(() => {
+  const customers = new Map<string, string>()
+  tenantOptions.value.forEach((item) => {
+    if (item.status !== 'ACTIVE') return
+    const name = item.tenantName?.trim() || '客户名称待补充'
+    const phone = item.contactPhone?.trim()
+    customers.set(String(item.id), phone ? `${name}-${phone}` : name)
+  })
+  positionOptions.value.forEach(({ balance }) => customers.set(balance.customerId, balance.customerName?.trim() || '客户名称待补充'))
+  return [...customers].map(([value, label]) => ({ value, label }))
+})
+const availablePositionOptions = computed(() => positionOptions.value.filter(({ balance }) => balance.customerId === selectedCustomerId.value))
+const warehouseOptions = computed(() => warehouseOptionsSource.value.filter((item) => item.status === 'ACTIVE' && item.warehouseType === 'OVERSEAS').map((item) => ({ value: String(item.id), label: [item.warehouseName || '仓库名称待补充', item.warehouseCode].filter(Boolean).join(' · ') })))
+const selectedReturnStock = computed(() => returnStockRows.value.filter((item) => Number(item.availableQuantity || 0) > 0))
+const selectedReturnCartons = computed(() => returnCartonRows.value.filter((item) => item.status === 'AVAILABLE'))
+const queryTokens = (value: string) => value.split(/[,，\n]+/).map((item) => item.replace(/\s+/g, '').toLowerCase()).filter(Boolean)
+const matchesAnyToken = (value: string, query: string) => { const tokens = queryTokens(query); const normalized = value.replace(/\s+/g, '').toLowerCase(); return !tokens.length || tokens.some((token) => normalized.includes(token)) }
+const filteredReturnStocks = computed(() => selectedReturnStock.value.filter((item) => matchesAnyToken(`${item.skuCode},${item.productNameZh || ''}`, returnSkuQuery.value)))
+const filteredReturnCartons = computed(() => selectedReturnCartons.value.filter((item) => {
+  const detailSkus = returnCartonDetails.value[item.cartonMark]?.items?.map((detail) => detail.skuCode).join(',') || ''
+  return matchesAnyToken(`${item.cartonMark},${item.fbaCartonMark || ''},${detailSkus}`, returnCartonQuery.value)
+}))
+const pagedReturnStocks = computed(() => filteredReturnStocks.value.slice((returnSkuPage.value - 1) * returnSkuPageSize.value, returnSkuPage.value * returnSkuPageSize.value))
+const pagedReturnCartons = computed(() => filteredReturnCartons.value.slice((returnCartonPage.value - 1) * returnCartonPageSize.value, returnCartonPage.value * returnCartonPageSize.value))
+const effectiveReturnMarks = computed(() => [...new Set(selectedReturnMarks.value)].filter(Boolean) as string[])
+const returnMarksModel = computed({ get: () => selectedReturnMarks.value, set: (value: string[]) => { selectedReturnMarks.value = value } })
+const filteredDropshipCandidates = computed(() => dropshipCandidates.value.filter(item => !dropshipQuery.value.trim() || [item.orderNo, item.inboundCode, item.customerName, item.palletNo, item.skuCode, item.productName].join(' ').toLowerCase().includes(dropshipQuery.value.trim().toLowerCase())))
+const pagedDropshipCandidates = computed(() => filteredDropshipCandidates.value.slice((dropshipPage.value - 1) * dropshipPageSize.value, dropshipPage.value * dropshipPageSize.value))
+const selectedDropshipKeys = computed(() => new Set(selectedDropshipIds.value))
+const selectedPageCount = computed(() => pagedDropshipCandidates.value.filter(item => selectedDropshipKeys.value.has(dropshipCandidateKey(item))).length)
+const allPageSelected = computed(() => pagedDropshipCandidates.value.length > 0 && selectedPageCount.value === pagedDropshipCandidates.value.length)
+const somePageSelected = computed(() => selectedPageCount.value > 0 && !allPageSelected.value)
+const selectedDropshipCustomerCount = computed(() => new Set(dropshipCandidates.value.filter(item => selectedDropshipKeys.value.has(dropshipCandidateKey(item))).map(item => item.customerId).filter(Boolean)).size)
+const oneClickMarks = computed(() => typeof cartonMarks.value === 'string' ? cartonMarks.value.split(/[,\n，]+/).map(value => value.trim()).filter(Boolean) : [])
+const columns: DataTableColumn[] = [{ key: 'actions', label: '操作', width: 180, fixed: 'left', slotName: 'actions' }, { key: 'outboundNo', prop: 'outboundNo', label: '出库单号', minWidth: 180 }, { key: 'outboundType', prop: 'outboundType', label: '出库类型', width: 150, slotName: 'outboundType' }, { key: 'lxCodes', prop: 'lxCodes', label: 'LX代码', minWidth: 180 }, { key: 'dispatchNo', prop: 'dispatchNo', label: '关联排车单', minWidth: 160 }, { key: 'status', prop: 'status', label: '状态', width: 130, slotName: 'status' }, { key: 'palletCount', prop: 'palletCount', label: '托盘数', width: 100 }, { key: 'packageCount', prop: 'packageCount', label: '箱数', width: 100 }, { key: 'createdAt', prop: 'createdAt', label: '创建时间', minWidth: 180 }]
+const fields: QueryField[] = [{ key: 'documentNo', type: 'input', label: '出库单号', placeholder: '请输入出库单号', width: 220 }, { key: 'lxCode', type: 'input', label: 'LX代码', placeholder: '请输入领星入库单代码', width: 220 }, { key: 'warehouseId', type: 'input', label: '目的仓', placeholder: '请输入目的仓', width: 220 }, { key: 'status', type: 'select', label: '状态', placeholder: '全部状态', width: 160, options: [{ label: '全部', value: '' }, { label: '待拣货', value: 'WAIT_PICK' }, { label: '拣货中', value: 'PICKING' }, { label: '已拣货', value: 'PICKED' }, { label: '待出库', value: 'WAIT_OUTBOUND' }, { label: '已出库', value: 'OUTBOUNDED' }, { label: '已取消', value: 'CANCELLED' }] }, { key: 'outboundType', type: 'select', label: '出库类型', placeholder: '全部出库类型', width: 170, options: [{ label: '全部', value: '' }, { label: '一件代发出库', value: 'ONE_CLICK_DROPSHIP' }, { label: '退货出库', value: 'RETURN_OUTBOUND' }, { label: '派送出库', value: 'DISPATCH_DELIVERY' }] }]
+
+async function load(model: QueryModel = filters.value) { Object.assign(filters.value, model); loading.value = true; error.value = null; try { const result = await listOutbounds({ page: page.value, size: pageSize.value, documentNo: String(filters.value.documentNo || '').trim() || undefined, lxCode: String(filters.value.lxCode || '').trim() || undefined, warehouseId: String(filters.value.warehouseId || '').trim() || undefined, status: String(filters.value.status || '').trim() || undefined, outboundType: String(filters.value.outboundType || '').trim() || undefined }); rows.value = result.records.map((row) => ({ ...row, createdAt: formatOverseasDateTime(row.createdAt) })); total.value = result.total } catch (cause) { error.value = getApiErrorDetails(cause, '出库单列表加载失败') } finally { loading.value = false } }
+function outboundTypeLabel(value?: string | null) { return value === 'ONE_CLICK_DROPSHIP' ? '一件代发出库' : value === 'RETURN_OUTBOUND' ? '退货出库' : value === 'DISPATCH_DELIVERY' ? '派送出库' : value || '—' }
+async function loadInventoryOptions() {
+  inventoryLoading.value = true
+  try {
+    const [tenants, warehouses] = await Promise.allSettled([
+      listPlatformTenants({ page: 1, size: 200, status: 'ACTIVE' }),
+      listPlatformWarehouses({ page: 1, size: 200, warehouseType: 'OVERSEAS', status: 'ACTIVE' }),
+    ])
+    if (tenants.status === 'fulfilled') tenantOptions.value = tenants.value.records
+    else ElMessage.error(getApiErrorDetails(tenants.reason, '客户列表加载失败').message)
+    if (warehouses.status === 'fulfilled') {
+      warehouseOptionsSource.value = warehouses.value.records
+      if (!selectedWarehouseId.value) {
+        const lax = warehouses.value.records.find((item) => item.warehouseCode === 'US-LAX-01' || item.warehouseName?.includes('洛杉矶'))
+        selectedWarehouseId.value = String(lax?.id || warehouses.value.records[0]?.id || '')
+      }
+    } else ElMessage.error(getApiErrorDetails(warehouses.reason, '海外仓列表加载失败').message)
+  } finally { inventoryLoading.value = false }
+}
+async function openCreate() { createOpen.value = true; outboundType.value = 'ONE_CLICK_DROPSHIP'; selectedCustomerId.value = ''; selectedWarehouseId.value = ''; selectedDropshipIds.value = []; dropshipCandidates.value = []; dropshipQueryInput.value = ''; dropshipQuery.value = ''; dropshipPage.value = 1; returnSkuQueryInput.value = ''; returnSkuQuery.value = ''; returnCartonQueryInput.value = ''; returnCartonQuery.value = ''; returnSkuPage.value = 1; returnCartonPage.value = 1; await loadInventoryOptions(); await loadDropshipCandidates() }
+async function loadDropshipCandidates() { if (!selectedWarehouseId.value) { dropshipCandidates.value = []; return }; dropshipPage.value = 1; inventoryLoading.value = true; try { dropshipCandidates.value = await listOneClickOutboundCandidates(selectedCustomerId.value || undefined, { warehouseId: selectedWarehouseId.value }) } catch (cause) { dropshipCandidates.value = []; ElMessage.error(getApiErrorDetails(cause, '一件代发订单加载失败').message) } finally { inventoryLoading.value = false } }
+async function changeDropshipWarehouse() { selectedDropshipIds.value = []; await loadDropshipCandidates() }
+async function selectCustomer() { selectedPositionId.value = ''; selectedDropshipIds.value = []; selectedReturnNo.value = ''; selectedReturnMarks.value = []; selectedReturnSkus.value = []; returnCandidates.value = []; returnStockRows.value = []; returnCartonRows.value = []; returnCartonDetails.value = {}; dropshipCandidates.value = []; dropshipPage.value = 1; if (outboundType.value === 'RETURN_OUTBOUND') { if (selectedCustomerId.value && selectedWarehouseId.value) await loadReturnCandidates(); return }; await loadDropshipCandidates() }
+async function changeOutboundType() { selectedReturnNo.value = ''; selectedReturnMarks.value = []; selectedReturnSkus.value = []; returnCandidates.value = []; returnStockRows.value = []; returnCartonRows.value = []; returnCartonDetails.value = {}; selectedDropshipIds.value = []; dropshipCandidates.value = []; if (outboundType.value === 'ONE_CLICK_DROPSHIP') await loadDropshipCandidates() }
+async function loadReturnCandidates() { if (!selectedCustomerId.value || !selectedWarehouseId.value) return; inventoryLoading.value = true; try { const [candidates, stock, cartons] = await Promise.all([listReturnOutboundCandidates(selectedCustomerId.value, selectedWarehouseId.value), listReturnStock({ page: 1, size: 200, customerId: selectedCustomerId.value, overseasWarehouseId: selectedWarehouseId.value, status: 'AVAILABLE' }), listReturnCartons({ page: 1, size: 200, customerId: selectedCustomerId.value, overseasWarehouseId: selectedWarehouseId.value, status: 'AVAILABLE' })]); returnCandidates.value = candidates; returnStockRows.value = stock.records; returnCartonRows.value = cartons.records; const details = await Promise.all(cartons.records.map(async (row) => [row.cartonMark, await getReturnCarton(row.cartonMark)] as const)); returnCartonDetails.value = Object.fromEntries(details); selectedReturnSkus.value = []; selectedReturnMarks.value = [] } catch (cause) { ElMessage.error(getApiErrorDetails(cause, '客户库存加载失败').message) } finally { inventoryLoading.value = false } }
+function dropshipCandidateKey(item: OneClickOutboundCandidate) { return `${item.inventoryPositionId}:${item.skuCode || ''}` }
+function isDropshipSelected(item: OneClickOutboundCandidate) { return selectedDropshipIds.value.includes(dropshipCandidateKey(item)) }
+function toggleDropshipCandidate(item: OneClickOutboundCandidate, checked: boolean | string | number) { const key = dropshipCandidateKey(item); selectedDropshipIds.value = checked ? [...new Set([...selectedDropshipIds.value, key])] : selectedDropshipIds.value.filter(value => value !== key) }
+function selectDropshipRows(items: OneClickOutboundCandidate[], checked: boolean | string | number) {
+  const keys = new Set(items.map(dropshipCandidateKey))
+  selectedDropshipIds.value = checked
+    ? [...new Set([...selectedDropshipIds.value, ...keys])]
+    : selectedDropshipIds.value.filter(key => !keys.has(key))
+}
+function searchDropshipCandidates() { dropshipQuery.value = dropshipQueryInput.value.trim(); dropshipPage.value = 1 }
+function resetDropshipCandidates() { dropshipQueryInput.value = ''; dropshipQuery.value = ''; dropshipPage.value = 1 }
+function normalizeBatchQuery(value: string) { return value.split(/[,，\n]+/).map((item) => item.replace(/\s+/g, '')).filter(Boolean).join(',') }
+function searchReturnSkus() { returnSkuQueryInput.value = normalizeBatchQuery(returnSkuQueryInput.value); returnSkuQuery.value = returnSkuQueryInput.value; returnSkuPage.value = 1 }
+function searchReturnCartons() { returnCartonQueryInput.value = normalizeBatchQuery(returnCartonQueryInput.value); returnCartonQuery.value = returnCartonQueryInput.value; returnCartonPage.value = 1 }
+function toggleReturnSku(sku: string, checked: boolean | string | number) { selectedReturnSkus.value = checked ? [...new Set([...selectedReturnSkus.value, sku])] : selectedReturnSkus.value.filter((value) => value !== sku) }
+function toggleReturnCarton(cartonMark: string, checked: boolean | string | number) { selectedReturnMarks.value = checked ? [...new Set([...selectedReturnMarks.value, cartonMark])] : selectedReturnMarks.value.filter((value) => value !== cartonMark) }
+async function submit() { const marks = String(cartonMarks.value).split(/[,\n，]+/).map(value => value.trim()).filter(Boolean); if (!selectedWarehouseId.value) { ElMessage.warning('请选择海外仓'); return }; if (outboundType.value === 'RETURN_OUTBOUND' && !selectedCustomerId.value) { ElMessage.warning('请选择客户'); return }; saving.value = true; try { if (outboundType.value === 'RETURN_OUTBOUND') { if (!recipient.value.trim() || !selectedReturnNo.value || !selectedReturnMarks.value.length) { ElMessage.warning('请填写收件信息并选择退货单和箱唛'); return }; await createReturnOutbound(selectedCustomerId.value, { recipient: recipient.value.trim(), overseasWarehouseId: selectedWarehouseId.value, returnNo: selectedReturnNo.value, cartonMarks: selectedReturnMarks.value, remark: remark.value.trim() || undefined, idempotencyKey: `web-return-${Date.now()}` }); ElMessage.success('退货出库单已创建并推送PDA箱唛拣货任务') } else { const selected = dropshipCandidates.value.filter(item => selectedDropshipIds.value.includes(dropshipCandidateKey(item))); if (!selected.length) { ElMessage.warning('请至少选择一个已完成入库的一件代发订单'); return }; const customerIds = new Set(selected.map(item => item.customerId).filter(Boolean)); if (customerIds.size !== 1) { ElMessage.warning('一张出库单只能选择同一个客户的订单'); return }; const warehouses = new Set(selected.map(item => item.overseasWarehouseId).filter(Boolean)); if (warehouses.size > 1 || (warehouses.size === 1 && !warehouses.has(selectedWarehouseId.value))) { ElMessage.warning('所选订单必须属于当前海外仓'); return }; const items = selected.map(item => ({ inventoryPositionId: item.inventoryPositionId, packages: item.availablePackages, sku: item.skuCode || '', cartonMarks: [] as string[] })); await createOneClickDropshipOutbound([...customerIds][0] || '', { recipient: '一件代发订单直出', items, remark: remark.value.trim() || undefined, idempotencyKey: `web-dropship-${Date.now()}` }); ElMessage.success(`已按订单生成 ${selected.length} 个托盘出库明细并推送PDA拣货任务`) } createOpen.value = false; await load() } catch (cause) { ElMessage.error(getApiErrorDetails(cause, '出库单创建失败').message) } finally { saving.value = false } }
+function openDetail(row: OutboundRow) { void router.push({ name: 'overseas-outbound-detail', params: { outboundNo: row.outboundNo } }) }
+function canCancel(row: OutboundRow) { return access.can(permission.outboundCancel) && ['WAIT_PICK', 'WAIT_OUTBOUND'].includes(String(row.status || '')) }
+async function cancel(row: OutboundRow) { if (!canCancel(row)) return; let reason = ''; try { const result = await ElMessageBox.prompt(`出库单 ${row.outboundNo} · 出库数量 ${row.packageCount ?? 0}`, '取消出库单', { customClass: 'admin-density-confirm', inputType: 'textarea', inputPlaceholder: '请输入取消原因', inputPattern: /\S+/, inputErrorMessage: '请输入取消原因', confirmButtonText: '确认取消', cancelButtonText: '返回', type: 'warning' }); reason = result.value.trim() } catch { return }; mutationError.value = null; try { await cancelOutbound(row.outboundNo, reason); ElMessage.success('出库单已取消，库存及关联单据已回滚'); await load() } catch (cause) { mutationError.value = getApiErrorDetails(cause, '取消出库单失败') } }
+function search(model: QueryModel) { page.value = 1; void load(model) }
+function reset(model: QueryModel) { page.value = 1; void load(model) }
+onMounted(load)
+</script>
+<template>
+  <AdminPage class="admin-density"><ListPageLayout aria-label="出库单">
+    <OperationErrorToast :details="mutationError" />
+    <template #toolbar><QueryToolbar v-model="filters" :fields="fields" :loading="loading" ariaLabel="出库单筛选" preference-key="overseas-outbounds-query" :search-on-reset="false" @search="search" @reset="reset" /></template>
+    <template v-if="error" #state><LoadErrorState title="出库单列表加载失败" :message="error.message" @retry="load"><template #details><ApiErrorMeta :details="error" /></template></LoadErrorState></template>
+    <section v-if="!error" class="surface-panel table-panel"><DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :loading="loading" :total="total" preference-key="overseas-outbounds" row-key="id" empty-text="暂无出库单" @update:page="load()" @update:page-size="page = 1; load()">
+      <template #toolbar-actions><el-button v-if="access.can(permission.outboundCreate)" type="primary" @click="openCreate"><Plus :size="16" />新建出库单</el-button></template>
+      <template #actions="{ row }"><div class="density-actions"><el-button class="density-action" data-tone="neutral" size="small" @click="openDetail(row as OutboundRow)">详情</el-button><el-button class="density-action" data-tone="danger" v-if="canCancel(row as OutboundRow)" size="small" @click="cancel(row as OutboundRow)">取消</el-button></div></template>
+      <template #outboundType="{ row }">{{ outboundTypeLabel(row.outboundType) }}</template>
+      <template #status="{ row }"><StatusBadge :status="row.status === 'CANCELLED' ? '已取消' : row.status === 'OUTBOUNDED' ? '已出库' : row.status === 'PICKED' ? '已拣货' : row.status === 'WAIT_OUTBOUND' ? '待出库' : row.status === 'PICKING' ? '拣货中' : row.status === 'WAIT_PICK' ? '待拣货' : '未知状态'" /></template>
+    </DataTable></section>
+  </ListPageLayout></AdminPage>
+  <AppDialog class="admin-density-dialog" v-model="createOpen" title="新建出库单" width="min(1320px, calc(100vw - 32px))" confirm-text="生成出库单并推送PDA" :confirm-loading="saving" @confirm="submit">
+    <el-form class="create-outbound-form density-form" label-position="top">
+      <el-form-item label="出库类型" required>
+        <el-radio-group v-model="outboundType" @change="changeOutboundType">
+          <el-radio-button label="ONE_CLICK_DROPSHIP">一件代发出库</el-radio-button>
+          <el-radio-button label="RETURN_OUTBOUND">退货出库</el-radio-button>
+        </el-radio-group>
+      </el-form-item>
+      <el-form-item v-if="outboundType === 'RETURN_OUTBOUND'" label="客户" required>
+        <el-select v-model="selectedCustomerId" :loading="inventoryLoading" clearable filterable placeholder="请选择客户" @change="selectCustomer">
+          <el-option v-for="item in customerOptions" :key="item.value" :value="item.value" :label="item.label" />
+        </el-select>
+      </el-form-item>
+      <template v-if="outboundType !== 'RETURN_OUTBOUND'">
+        <div class="dropship-search-row">
+        <el-form-item label="海外仓" required>
+          <el-select v-model="selectedWarehouseId" filterable clearable default-first-option aria-label="搜索海外仓" placeholder="输入仓库名称或编码搜索" @change="changeDropshipWarehouse">
+            <el-option v-for="item in warehouseOptions" :key="item.value" :value="item.value" :label="item.label" />
+          </el-select>
+        </el-form-item>
+        <el-form-item label="一件代发订单">
+          <div class="candidate-query">
+            <el-input v-model="dropshipQueryInput" :prefix-icon="Search" clearable aria-label="搜索可出库订单" placeholder="订单号 / 入库单号 / 客户 / 托盘 / SKU / 品名" @keyup.enter="searchDropshipCandidates" />
+            <el-button type="primary" :loading="inventoryLoading" @click="searchDropshipCandidates">查询</el-button>
+            <el-button @click="resetDropshipCandidates">重置</el-button>
+          </div>
+        </el-form-item>
+        </div>
+        <section class="candidate-results" aria-label="已完成入库的一件代发订单">
+          <el-table v-loading="inventoryLoading" :data="pagedDropshipCandidates" border stripe class="dropship-candidate-table" max-height="360">
+            <el-table-column label="选择" width="68" align="center">
+              <template #header><el-checkbox aria-label="全选本页订单" :model-value="allPageSelected" :indeterminate="somePageSelected" :disabled="inventoryLoading || !pagedDropshipCandidates.length" @change="selectDropshipRows(pagedDropshipCandidates, $event)" /></template>
+              <template #default="{ row }"><el-checkbox :aria-label="`选择 ${row.orderNo || '订单'} / ${row.palletNo || '托盘'} / ${row.skuCode || 'SKU'}`" :model-value="isDropshipSelected(row as OneClickOutboundCandidate)" @change="toggleDropshipCandidate(row as OneClickOutboundCandidate, $event)" /></template>
+            </el-table-column>
+            <el-table-column prop="customerName" label="客户" min-width="150" show-overflow-tooltip />
+            <el-table-column prop="orderNo" label="尾程订单号" min-width="170" show-overflow-tooltip />
+            <el-table-column prop="inboundCode" label="入库单号" min-width="160" show-overflow-tooltip />
+            <el-table-column prop="palletNo" label="托盘号" min-width="140" show-overflow-tooltip />
+            <el-table-column prop="skuCode" label="SKU" min-width="140" show-overflow-tooltip />
+            <el-table-column prop="productName" label="品名" min-width="140" show-overflow-tooltip />
+            <el-table-column prop="availablePackages" label="可出箱数" width="95" align="right" />
+          </el-table>
+          <div v-if="!inventoryLoading && !filteredDropshipCandidates.length" class="form-hint">暂无可直接出库的已完成入库订单</div>
+          <div class="candidate-pagination">
+            <span aria-live="polite" title="翻页保留选择">已选择 {{ selectedDropshipIds.length }} 条 · 第 {{ dropshipPage }} / {{ Math.max(1, Math.ceil(filteredDropshipCandidates.length / dropshipPageSize)) }} 页</span>
+            <el-pagination v-model:current-page="dropshipPage" v-model:page-size="dropshipPageSize" :page-sizes="[5, 10, 20, 50]" :pager-count="5" :total="filteredDropshipCandidates.length" layout="total, sizes, prev, pager, next, jumper" @size-change="dropshipPage = 1" />
+          </div>
+          <el-alert v-if="selectedDropshipCustomerCount > 1" title="当前选择包含多个客户，请按客户搜索后选择；一张出库单只能属于同一客户。" type="warning" :closable="false" />
+          <p v-else class="candidate-hint">按托盘与 SKU 选择，默认出库全部可用箱数；仅限同一客户、同一海外仓，翻页保留选择。</p>
+        </section>
+      </template>
+      <template v-else>
+        <el-form-item label="收件信息" required><el-input v-model="recipient" placeholder="请输入收件人、电话和地址" /></el-form-item>
+        <el-form-item label="海外仓" required><el-select v-model="selectedWarehouseId" :disabled="!selectedCustomerId" filterable placeholder="请选择海外仓" @change="loadReturnCandidates"><el-option v-for="item in warehouseOptions" :key="item.value" :value="item.value" :label="item.label" /></el-select></el-form-item>
+        <div class="return-lists">
+          <section class="return-list-card">
+            <div class="list-title"><span>SKU库存</span><small>支持多个 SKU，用英文逗号分隔</small></div>
+            <div class="candidate-query"><el-input v-model="returnSkuQueryInput" clearable placeholder="如：SKU001,SKU002" /><el-button type="primary" @click="searchReturnSkus">查询</el-button></div>
+            <el-table :data="pagedReturnStocks" border stripe class="return-result-table" max-height="400"><el-table-column label="选择" width="60" align="center"><template #default="{ row }"><el-checkbox :model-value="selectedReturnSkus.includes(row.skuCode)" @change="toggleReturnSku(row.skuCode, $event)" /></template></el-table-column><el-table-column prop="skuCode" label="SKU" min-width="150" show-overflow-tooltip /><el-table-column prop="productNameZh" label="品名" min-width="150" show-overflow-tooltip /><el-table-column prop="availableQuantity" label="可用数量" width="100" align="right" /></el-table>
+            <div class="return-pagination"><span>已选择 {{ selectedReturnSkus.length }} 个 SKU</span><el-pagination v-model:current-page="returnSkuPage" v-model:page-size="returnSkuPageSize" :page-sizes="[5, 10, 20, 50]" :total="filteredReturnStocks.length" layout="total, sizes, prev, pager, next" @size-change="returnSkuPage = 1" /></div>
+          </section>
+          <section class="return-list-card">
+            <div class="list-title"><span>箱号列表</span><small>支持多个箱号或 SKU，用英文逗号分隔</small></div>
+            <div class="candidate-query"><el-input v-model="returnCartonQueryInput" clearable placeholder="如：RC001,RC002 或 SKU001,SKU002" /><el-button type="primary" @click="searchReturnCartons">查询</el-button></div>
+            <el-table :data="pagedReturnCartons" border stripe class="return-result-table" max-height="400"><el-table-column label="选择" width="60" align="center"><template #default="{ row }"><el-checkbox :model-value="selectedReturnMarks.includes(row.cartonMark)" @change="toggleReturnCarton(row.cartonMark, $event)" /></template></el-table-column><el-table-column prop="cartonMark" label="箱号" min-width="190" show-overflow-tooltip /><el-table-column label="箱内SKU及数量" min-width="230"><template #default="{ row }">{{ returnCartonDetails[row.cartonMark]?.items?.map((item) => `${item.skuCode} × ${item.quantity}`).join('，') || '加载中' }}</template></el-table-column></el-table>
+            <div class="return-pagination"><span>已选择 {{ selectedReturnMarks.length }} 个箱号</span><el-pagination v-model:current-page="returnCartonPage" v-model:page-size="returnCartonPageSize" :page-sizes="[5, 10, 20, 50]" :total="filteredReturnCartons.length" layout="total, sizes, prev, pager, next" @size-change="returnCartonPage = 1" /></div>
+          </section>
+        </div>
+        <el-alert title="退货出库支持按客户选择单个或多个箱子；SKU数量直接从所选箱唛明细扣减。" type="info" :closable="false" />
+      </template>
+      <el-form-item label="备注"><el-input v-model="remark" type="textarea" :autosize="{ minRows: 1, maxRows: 3 }" placeholder="请输入备注（选填）" /></el-form-item>
+    </el-form>
+  </AppDialog>
+</template>
+
+<style scoped>
+.create-outbound-form { padding: 0 var(--admin-space-1); }
+.create-outbound-form :deep(.el-form-item__content > .el-input), .create-outbound-form :deep(.el-form-item__content > .el-select), .create-outbound-form :deep(.el-form-item__content > .el-input-number) { width: 100%; }
+.form-hint { margin-top: var(--admin-space-2); color: var(--cc-muted); font-size: var(--admin-font-caption); }
+.candidate-list { display: grid; gap: var(--admin-space-3); max-height: 300px; overflow: auto; padding: var(--admin-space-3) 0; }
+.candidate-list :deep(.el-checkbox) { margin-right: 0; }
+.candidate-row { display: grid; grid-template-columns: minmax(120px, 1fr) minmax(150px, 1fr) auto; gap: var(--admin-space-5); align-items: center; width: min(700px, 100%); }
+.candidate-row span, .candidate-row em { color: var(--cc-muted); font-style: normal; font-size: var(--admin-font-caption); }
+.candidate-query { display: flex; width: 100%; gap: var(--admin-space-4); }
+.candidate-query :deep(.el-input) { flex: 1; }
+.candidate-query :deep(.el-button) { flex: 0 0 auto; min-width: 78px; margin-left: 0; }
+.dropship-search-row { display: grid; grid-template-columns: minmax(0, 280px) minmax(0, 640px); align-items: end; gap: var(--admin-space-5); }
+.dropship-search-row :deep(.el-form-item) { min-width: 0; margin-bottom: var(--admin-space-3); }
+.candidate-results { min-width: 0; }
+.candidate-hint { margin: 0 0 var(--admin-space-3); color: var(--cc-muted); font-size: var(--admin-font-caption); line-height: 1.5; }
+.dropship-candidate-table { width: 100%; }
+.candidate-pagination { display: flex; width: 100%; align-items: center; justify-content: space-between; gap: var(--admin-space-5); padding: var(--admin-space-5) 0; color: var(--cc-muted); font-size: var(--admin-font-caption); }
+.candidate-pagination, .return-pagination { flex-wrap: wrap; }
+.candidate-pagination > span, .return-pagination > span { flex-shrink: 0; white-space: nowrap; }
+.candidate-pagination :deep(.el-pagination), .return-pagination :deep(.el-pagination) { min-width: 0; max-width: 100%; flex-wrap: wrap; gap: var(--admin-space-2); justify-content: flex-end; }
+.candidate-pagination :deep(.el-pagination__sizes), .return-pagination :deep(.el-pagination__sizes) { flex: 0 0 128px; }
+.candidate-pagination :deep(.el-pagination__sizes .el-select), .return-pagination :deep(.el-pagination__sizes .el-select) { width: 128px; }
+.candidate-pagination :deep(.el-pagination__jump .el-input) { width: 56px; }
+.return-lists { display: grid; grid-template-columns: minmax(0, 1fr) minmax(0, 1fr); gap: var(--admin-space-5); width: 100%; margin: var(--admin-space-1) 0 var(--admin-space-5); }
+.return-list-card { min-width: 0; padding: var(--admin-space-5); border: 1px solid var(--el-border-color-light); border-radius: var(--admin-radius); background: var(--el-fill-color-extra-light); }
+.list-title { display: flex; align-items: baseline; justify-content: space-between; gap: var(--admin-space-5); margin-bottom: var(--admin-space-5); }
+.list-title span { color: var(--el-text-color-primary); font-size: var(--admin-font-section); font-weight: 650; }
+.list-title small { color: var(--cc-muted); font-size: var(--admin-font-caption); font-weight: 400; }
+.return-result-table { width: 100%; margin-top: var(--admin-space-5); background: var(--el-bg-color); }
+.return-pagination { display: flex; min-height: 44px; align-items: center; justify-content: space-between; gap: var(--admin-space-5); padding-top: var(--admin-space-5); color: var(--cc-muted); font-size: var(--admin-font-caption); }
+.return-pagination :deep(.el-pagination) { flex-wrap: wrap; justify-content: flex-end; }
+@media (max-width: 980px) { .return-lists { grid-template-columns: 1fr; }.return-pagination { align-items: flex-start; flex-direction: column; } }
+</style>
diff --git a/src/modules/overseas-warehouse/pages/PalletDetailView.test.ts b/src/modules/overseas-warehouse/pages/PalletDetailView.test.ts
new file mode 100644
index 00000000..e634c745
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/PalletDetailView.test.ts
@@ -0,0 +1,45 @@
+import ElementPlus from 'element-plus'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { getPallet, listReceivingOverseasWarehouses } from '../api/pallets'
+import PalletDetailView from './PalletDetailView.vue'
+
+vi.mock('vue-router', () => ({
+  useRoute: () => ({ params: { palletId: 'internal-pallet-id' }, query: { warehouseId: 'internal-warehouse-id' } }),
+  useRouter: () => ({ push: vi.fn() }),
+}))
+vi.mock('../api/pallets', () => ({ getPallet: vi.fn(), listReceivingOverseasWarehouses: vi.fn() }))
+enableAutoUnmount(afterEach)
+
+describe('PalletDetailView business identifiers', () => {
+  beforeEach(() => {
+    vi.mocked(getPallet).mockReset()
+    vi.mocked(listReceivingOverseasWarehouses).mockResolvedValue({ records: [], page: 1, size: 200, total: 0, pages: 0 })
+  })
+
+  it('does not expose the route ID while loading or after a failed load', async () => {
+    let rejectLoad!: (cause: Error) => void
+    vi.mocked(getPallet).mockReturnValue(new Promise((_, reject) => { rejectLoad = reject }))
+    const wrapper = mount(PalletDetailView, { global: { plugins: [ElementPlus] } })
+    expect(wrapper.get('.overseas-detail-title').text()).toContain('—')
+    expect(wrapper.text()).not.toContain('internal-pallet-id')
+    rejectLoad(new Error('暂时无法加载'))
+    await flushPromises()
+    expect(wrapper.text()).toContain('托盘详情加载失败')
+    expect(wrapper.text()).not.toContain('internal-pallet-id')
+  })
+
+  it('renders the pallet code inside the dense detail and keeps unavailable location codes empty', async () => {
+    vi.mocked(getPallet).mockResolvedValue({
+      id: 'internal-pallet-id', warehouseId: 'internal-warehouse-id', customerId: 'customer-1',
+      locationId: 'internal-location-id', palletCode: 'PALLET-LAX-001', palletType: 'WOOD',
+      fbaWarehouseCode: 'ONT8', capacityCbm: 2, unitPrice: 10, status: 'IDLE', version: 1,
+    })
+    const wrapper = mount(PalletDetailView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(wrapper.get('.admin-density .overseas-detail-title').text()).toContain('PALLET-LAX-001')
+    const location = wrapper.findAll('.density-fields dt').find(item => item.text() === '库位')!
+    expect(location.element.nextElementSibling?.textContent).toBe('—')
+    expect(wrapper.text()).not.toMatch(/internal-(pallet|warehouse|location)-id/)
+  })
+})
diff --git a/src/modules/overseas-warehouse/pages/PalletDetailView.vue b/src/modules/overseas-warehouse/pages/PalletDetailView.vue
new file mode 100644
index 00000000..2ebfd009
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/PalletDetailView.vue
@@ -0,0 +1,48 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, ref } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { getPallet, listReceivingOverseasWarehouses, type PalletDto } from '../api/pallets'
+import { formatOverseasDateTime } from '../lastMilePresentation'
+import OverseasReadOnlyDetail from '../components/OverseasReadOnlyDetail.vue'
+
+const route = useRoute()
+const router = useRouter()
+const palletId = computed(() => String(route.params.palletId || '—'))
+const warehouseId = computed(() => String(route.query.warehouseId || ''))
+const detail = ref<PalletDto | null>(null)
+const warehouseName = ref('—')
+const loading = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const groups = [
+  { title: '基础信息', fields: ['托盘编码', '托盘类型', '仓库', '容积(m³)', '采购价格', '所属FBA仓', '状态'] },
+  { title: '使用信息', fields: ['库位', '创建时间', '更新时间', '备注'] },
+]
+const values = computed(() => ({
+  托盘编码: detail.value?.palletCode || '—', 托盘类型: detail.value?.palletType || '—', 仓库: warehouseName.value,
+  '容积(m³)': detail.value?.capacityCbm ?? '—', 采购价格: detail.value?.unitPrice ?? '—', 所属FBA仓: detail.value?.fbaWarehouseCode || '—', 状态: detail.value?.status || '—',
+  库位: '—', 创建时间: formatOverseasDateTime(detail.value?.createdAt), 更新时间: formatOverseasDateTime(detail.value?.updatedAt), 备注: detail.value?.remark || '—',
+}))
+
+async function load() {
+  if (!warehouseId.value || palletId.value === '—') { loadError.value = getApiErrorDetails(new Error('托盘详情缺少仓库参数')); return }
+  loading.value = true; loadError.value = null
+  try {
+    const [pallet, warehouses] = await Promise.all([getPallet(warehouseId.value, palletId.value), listReceivingOverseasWarehouses()])
+    detail.value = pallet
+    const warehouse = warehouses.records.find((item) => String(item.id) === warehouseId.value)
+    warehouseName.value = warehouse ? `${warehouse.warehouseName}（${warehouse.warehouseCode}）` : '—'
+  } catch (error) { loadError.value = getApiErrorDetails(error, '托盘详情加载失败，请重试') }
+  finally { loading.value = false }
+}
+
+function back() { void router.push({ name: 'overseas-pallets' }) }
+onMounted(load)
+</script>
+
+<template><OverseasReadOnlyDetail class="admin-density" dense title="托盘详情" reference-label="托盘编码" :reference-value="detail?.palletCode || '—'" back-label="返回托盘管理" domain="托盘详情" :groups="groups" :field-values="values" :pending="false" status-text="真实数据" :loading="loading" :show-content="!loadError" @back="back">
+  <template v-if="loadError" #state><LoadErrorState title="托盘详情加载失败" :message="loadError.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="loadError" /></template></LoadErrorState></template>
+</OverseasReadOnlyDetail></template>
diff --git a/src/modules/overseas-warehouse/pages/PalletsView.test.ts b/src/modules/overseas-warehouse/pages/PalletsView.test.ts
new file mode 100644
index 00000000..36039717
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/PalletsView.test.ts
@@ -0,0 +1,124 @@
+import ElementPlus from 'element-plus'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { listAllPlatformWarehouses } from '@/modules/warehouses'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import QueryToolbar from '@/shared/components/QueryToolbar.vue'
+import { createPallet, getPallet, getPalletLabelPdf, getPalletSummary, listPallets, listReceivingOverseasWarehouses, updatePallet } from '../api/pallets'
+import PalletsView from './PalletsView.vue'
+
+vi.mock('vue-router', () => ({ useRouter: () => ({ push: vi.fn() }) }))
+vi.mock('@/core/access/accessPreview', () => ({ useAccessPreviewStore: () => ({ can: () => true }) }))
+vi.mock('@/modules/warehouses', () => ({ listAllPlatformWarehouses: vi.fn() }))
+vi.mock('../api/pallets', () => ({ createPallet: vi.fn(), getPallet: vi.fn(), getPalletLabelPdf: vi.fn(), getPalletSummary: vi.fn(), listPallets: vi.fn(), listReceivingOverseasWarehouses: vi.fn(), updatePallet: vi.fn() }))
+
+class ResizeObserverStub implements ResizeObserver { observe() {} unobserve() {} disconnect() {} }
+function memoryStorage(): Storage { const values = new Map<string, string>(); return { get length() { return values.size }, clear: () => values.clear(), getItem: (key) => values.get(key) ?? null, key: (index) => [...values.keys()][index] ?? null, removeItem: (key) => values.delete(key), setItem: (key, value) => values.set(key, value) } }
+enableAutoUnmount(afterEach)
+afterAll(() => vi.unstubAllGlobals())
+
+describe('PalletsView', () => {
+  beforeEach(() => {
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+    vi.stubGlobal('localStorage', memoryStorage())
+    vi.mocked(listReceivingOverseasWarehouses).mockReset().mockResolvedValue({ records: [{ id: '200', customerId: '0', warehouseCode: 'LAX', warehouseName: '洛杉矶仓', warehouseType: 'OVERSEAS', status: 'ACTIVE' }], page: 1, size: 200, total: 1, pages: 1 })
+    vi.mocked(listAllPlatformWarehouses).mockReset().mockResolvedValue([{ id: '300', warehouseCode: 'ABE3', warehouseName: 'ABE3', warehouseType: 'FBA', status: 'ACTIVE' } as never])
+    const pallet = { id: '9007199254740993', customerId: '0', warehouseId: '200', locationId: null, palletCode: 'PLT-1', palletType: 'WOOD', fbaWarehouseCode: 'ABE3', capacityCbm: 2, unitPrice: 10, status: 'IDLE', remark: null, version: 7 }
+    vi.mocked(listPallets).mockReset().mockResolvedValue({ records: [pallet], page: 1, size: 10, total: 1, pages: 1 })
+    vi.mocked(getPalletSummary).mockReset().mockResolvedValue({ totalCount: 1, idleCount: 1, occupiedCount: 0, scrappedCount: 0 })
+    vi.mocked(getPallet).mockReset().mockResolvedValue(pallet)
+    vi.mocked(createPallet).mockReset()
+    vi.mocked(getPalletLabelPdf).mockReset()
+    vi.mocked(updatePallet).mockReset().mockResolvedValue(null)
+  })
+
+  it('loads the all-warehouse pallet list and summary when the page opens', async () => {
+    vi.mocked(getPalletSummary).mockResolvedValueOnce({ totalCount: 250, idleCount: 100, occupiedCount: 98, scrappedCount: 52 })
+
+    const wrapper = mount(PalletsView, { attachTo: document.body, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    expect(listPallets).toHaveBeenCalledWith('', { page: 1, size: 10, keyword: undefined, palletType: undefined, status: undefined })
+    expect(getPalletSummary).toHaveBeenCalledWith('', { page: 1, size: 10, keyword: undefined, palletType: undefined, status: undefined })
+    expect(wrapper.get('[aria-label="托盘管理列表"]').text()).toContain('PLT-1')
+    expect(wrapper.get('[aria-label="托盘管理列表"]').text()).not.toContain('请先选择仓库后查询')
+    expect(wrapper.get('[aria-label="海外托盘数量概览"]').text()).toContain('托盘总数250')
+    expect(wrapper.get('[aria-label="海外托盘数量概览"]').text()).toContain('闲置托盘100')
+    expect(wrapper.get('[aria-label="海外托盘数量概览"]').text()).toContain('占用托盘98')
+    expect(wrapper.get('[aria-label="海外托盘数量概览"]').text()).toContain('已报废52')
+  })
+
+  it('prints one pallet from the all-warehouse list and allows retry after failure', async () => {
+    const pdf = new Blob(['%PDF-label'], { type: 'application/pdf' })
+    vi.mocked(getPalletLabelPdf).mockRejectedValueOnce(new Error('打印服务暂不可用')).mockResolvedValueOnce(pdf)
+    const createUrl = vi.fn(() => 'blob:pallet-label')
+    vi.stubGlobal('URL', Object.assign(URL, { createObjectURL: createUrl, revokeObjectURL: vi.fn() }))
+    const downloads: string[] = []
+    const click = vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(function (this: HTMLAnchorElement) { downloads.push(this.download) })
+    try {
+      const wrapper = mount(PalletsView, { attachTo: document.body, global: { plugins: [ElementPlus] } })
+      await flushPromises()
+      const button = wrapper.findAll('button').filter((item) => item.text() === '打印').at(-1)!
+      await button.trigger('click')
+      await flushPromises()
+      expect(createUrl).not.toHaveBeenCalled()
+      expect(button.attributes('disabled')).toBeUndefined()
+      await button.trigger('click')
+      await flushPromises()
+      expect(getPalletLabelPdf).toHaveBeenNthCalledWith(2, '200', '9007199254740993')
+      expect(createUrl).toHaveBeenCalledWith(pdf)
+      expect(downloads).toEqual(['PLT-1-托盘码.pdf'])
+      expect(createPallet).not.toHaveBeenCalled()
+      expect(updatePallet).not.toHaveBeenCalled()
+    } finally { click.mockRestore() }
+  })
+
+  it('reloads all warehouses when the filters are reset', async () => {
+    const wrapper = mount(PalletsView, { attachTo: document.body, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    vi.mocked(listPallets).mockClear()
+
+    wrapper.findComponent(QueryToolbar).vm.$emit('reset', { warehouseId: '', code: '', type: '', status: '' })
+    await flushPromises()
+
+    expect(listPallets).toHaveBeenCalledWith('', { page: 1, size: 10, keyword: undefined, palletType: undefined, status: undefined })
+  })
+
+  it('loads the current detail version and keeps the edit open on a conflict', async () => {
+    vi.mocked(updatePallet).mockRejectedValueOnce(Object.assign(new Error('version conflict'), { code: 'A0409' }))
+    const wrapper = mount(PalletsView, { attachTo: document.body, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    wrapper.findComponent(QueryToolbar).vm.$emit('search', { warehouseId: '200', code: '', type: '', status: '' })
+    await flushPromises()
+    await wrapper.findAll('button.el-button--small').filter((button) => button.text().includes('编辑')).at(-1)!.trigger('click')
+    await flushPromises()
+    const dialog = wrapper.findComponent(AppDialog)
+    dialog.vm.$emit('confirm')
+    await flushPromises()
+
+    expect(getPallet).toHaveBeenCalledWith('200', '9007199254740993')
+    expect(updatePallet).toHaveBeenCalledWith('200', '9007199254740993', expect.objectContaining({
+      palletCode: 'PLT-1', fbaWarehouseCode: 'ABE3', version: 7,
+    }))
+    expect(dialog.props('modelValue')).toBe(true)
+    expect(createPallet).not.toHaveBeenCalled()
+  })
+
+  it('creates an IDLE ABE3 pallet under the selected Los Angeles warehouse id', async () => {
+    vi.mocked(createPallet).mockResolvedValueOnce('9007199254740994')
+    const wrapper = mount(PalletsView, { attachTo: document.body, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    await wrapper.findAll('button').find((button) => button.text().includes('新增托盘'))!.trigger('click')
+    await flushPromises()
+
+    const view = wrapper.vm as unknown as { form: { warehouseId: string; fbaWarehouseCode: string; code: string } }
+    Object.assign(view.form, { warehouseId: '200', fbaWarehouseCode: 'ABE3', code: 'PLT-LAX-ABE3' })
+    await flushPromises()
+    wrapper.findComponent(AppDialog).vm.$emit('confirm')
+    await flushPromises()
+
+    expect(createPallet).toHaveBeenCalledWith('200', expect.objectContaining({
+      palletCode: 'PLT-LAX-ABE3', fbaWarehouseCode: 'ABE3', status: 'IDLE',
+    }))
+  })
+})
diff --git a/src/modules/overseas-warehouse/pages/PalletsView.vue b/src/modules/overseas-warehouse/pages/PalletsView.vue
new file mode 100644
index 00000000..f175abfd
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/PalletsView.vue
@@ -0,0 +1,182 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, reactive, ref } from 'vue'
+import { Plus } from '@lucide/vue'
+import { ElMessage } from 'element-plus'
+import { useRouter } from 'vue-router'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { listAllPlatformWarehouses, type PlatformWarehouseResource } from '@/modules/warehouses'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import OperationErrorToast from '@/shared/components/OperationErrorToast.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import { createPallet, getPallet, getPalletLabelPdf, getPalletSummary, listPallets, listReceivingOverseasWarehouses, updatePallet, type PalletDto, type PalletSummaryDto, type ReceivingOverseasWarehouseDto } from '../api/pallets'
+import { overseasWarehousePermissions as permission } from '../permissions'
+import type { PalletListItem } from '../types'
+
+const access = useAccessPreviewStore()
+const router = useRouter()
+const warehouses = ref<ReceivingOverseasWarehouseDto[]>([])
+const fbaWarehouses = ref<PlatformWarehouseResource[]>([])
+const rows = ref<PalletListItem[]>([])
+const loading = ref(false)
+const contextLoading = ref(false)
+const saving = ref(false)
+const printingId = ref('')
+const loadError = ref<ApiErrorDetails | null>(null)
+const mutationError = ref<ApiErrorDetails | null>(null)
+const loadErrorKind = ref<'context' | 'list'>('context')
+const page = ref(1)
+const pageSize = ref(10)
+const total = ref(0)
+const summary = ref<PalletSummaryDto>({ totalCount: 0, idleCount: 0, occupiedCount: 0, scrappedCount: 0 })
+const filters = ref<QueryModel>({ warehouseId: '', code: '', type: '', status: '' })
+const fields = computed<QueryField[]>(() => [
+  { key: 'warehouseId', type: 'select', label: '仓库', width: 240, placeholder: contextLoading.value ? '仓库加载中' : '全部仓库', options: warehouses.value.map((item) => ({ label: `${item.warehouseName}（${item.warehouseCode}）`, value: String(item.id) })), props: { filterable: true, clearable: true, disabled: contextLoading.value } },
+  { key: 'code', type: 'input', label: '托盘编码', placeholder: '请输入托盘编码', width: 180 },
+  { key: 'type', type: 'select', label: '托盘类型', placeholder: '全部类型', width: 160, options: ['WOOD', 'PLASTIC', 'METAL', 'PAPER', 'FUMIGATION_FREE'].map((value) => ({ label: palletTypeLabel(value), value })) },
+  { key: 'status', type: 'select', label: '状态', placeholder: '全部状态', width: 140, options: [{ label: '闲置', value: 'IDLE' }, { label: '占用', value: 'OCCUPIED' }, { label: '已报废', value: 'SCRAPPED' }] },
+])
+const columns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 180, fixed: 'left', slotName: 'actions' },
+  { key: 'code', prop: 'code', label: '托盘编码', minWidth: 160 }, { key: 'type', prop: 'type', label: '托盘类型', minWidth: 130 },
+  { key: 'warehouse', prop: 'warehouse', label: '仓库', minWidth: 180 }, { key: 'volume', prop: 'volume', label: '容积(m³)', width: 110, align: 'right' },
+  { key: 'purchasePrice', prop: 'purchasePrice', label: '采购价格', width: 120, align: 'right' }, { key: 'fbaWarehouse', prop: 'fbaWarehouse', label: '所属FBA仓', minWidth: 140 },
+  { key: 'status', prop: 'status', label: '状态', width: 100 }, { key: 'remark', prop: 'remark', label: '备注', minWidth: 180 },
+]
+const dialogOpen = ref(false)
+const dialogMode = ref<'create' | 'edit'>('create')
+const form = reactive({ id: '', warehouseId: '', fbaWarehouseCode: '', code: '', type: 'WOOD', volume: 2, purchasePrice: 0, status: 'IDLE', remark: '', version: 0 })
+
+function text(value: unknown) { const normalized = String(value ?? '').trim(); return normalized || '—' }
+function number(value: unknown) { const normalized = Number(value); return Number.isFinite(normalized) ? normalized : 0 }
+function palletTypeLabel(value: string) { return ({ WOOD: '木托盘', PLASTIC: '塑料托盘', METAL: '金属托盘', PAPER: '纸托盘', FUMIGATION_FREE: '免熏蒸托盘' } as Record<string, string>)[value] || value }
+function statusLabel(value: string) { return ({ IDLE: '闲置', OCCUPIED: '占用', SCRAPPED: '已报废' } as Record<string, string>)[value] || value }
+function warehouseName(id: string) { const warehouse = warehouses.value.find((item) => String(item.id) === id); return warehouse ? `${warehouse.warehouseName}（${warehouse.warehouseCode}）` : '—' }
+function fbaWarehouseName(code: string) { const warehouse = fbaWarehouses.value.find((item) => item.warehouseCode === code); return warehouse ? `${warehouse.warehouseName}（${warehouse.warehouseCode}）` : text(code) }
+function toRow(dto: PalletDto): PalletListItem { return { id: String(dto.id), customerId: String(dto.customerId), warehouseId: String(dto.warehouseId), locationId: text(dto.locationId), code: text(dto.palletCode), type: palletTypeLabel(dto.palletType), warehouse: warehouseName(String(dto.warehouseId)), volume: number(dto.capacityCbm), purchasePrice: number(dto.unitPrice), fbaWarehouse: fbaWarehouseName(dto.fbaWarehouseCode), status: statusLabel(dto.status), remark: text(dto.remark) } }
+
+async function loadWarehouses() {
+  warehouses.value = []; filters.value.warehouseId = ''; rows.value = []; total.value = 0
+  contextLoading.value = true; loadError.value = null; loadErrorKind.value = 'context'
+  try {
+    const [warehousePage, platformFbaWarehouses] = await Promise.all([
+      listReceivingOverseasWarehouses(),
+      listAllPlatformWarehouses({ warehouseType: 'FBA', status: 'ACTIVE' }),
+    ])
+    warehouses.value = warehousePage.records
+    fbaWarehouses.value = platformFbaWarehouses
+  }
+  catch (error) { loadError.value = getApiErrorDetails(error, '海外仓列表加载失败，请重试') }
+  finally { contextLoading.value = false }
+}
+
+async function load(model: QueryModel = filters.value) {
+  Object.assign(filters.value, model)
+  const warehouseId = String(filters.value.warehouseId || '')
+  loading.value = true; loadError.value = null; loadErrorKind.value = 'list'
+  try {
+    const query = { page: page.value, size: pageSize.value, keyword: String(filters.value.code || '').trim() || undefined, palletType: String(filters.value.type || '') || undefined, status: String(filters.value.status || '') || undefined }
+    const [result, summaryResult] = await Promise.all([listPallets(warehouseId, query), getPalletSummary(warehouseId, query)])
+    rows.value = result.records.map(toRow); total.value = result.total
+    summary.value = summaryResult
+  } catch (error) { rows.value = []; total.value = 0; loadError.value = getApiErrorDetails(error, '托盘列表加载失败，请重试') }
+  finally { loading.value = false }
+}
+
+function retryLoad() {
+  if (loading.value || contextLoading.value) return
+  if (loadErrorKind.value === 'list') void load()
+  else void loadWarehouses()
+}
+
+function openCreate() {
+  dialogMode.value = 'create'; Object.assign(form, { id: '', warehouseId: '', fbaWarehouseCode: '', code: '', type: 'WOOD', volume: 2, purchasePrice: 0, status: 'IDLE', remark: '', version: 0 }); mutationError.value = null; dialogOpen.value = true
+}
+
+async function openEdit(source: object) {
+  const row = source as PalletListItem; saving.value = true; mutationError.value = null
+  try {
+    const detail = await getPallet(row.warehouseId, row.id)
+    dialogMode.value = 'edit'; Object.assign(form, { id: String(detail.id), warehouseId: String(detail.warehouseId), fbaWarehouseCode: detail.fbaWarehouseCode, code: detail.palletCode, type: detail.palletType, volume: number(detail.capacityCbm), purchasePrice: number(detail.unitPrice), status: detail.status, remark: detail.remark || '', version: detail.version }); dialogOpen.value = true
+  } catch (error) { mutationError.value = getApiErrorDetails(error, '托盘详情加载失败，请重试') }
+  finally { saving.value = false }
+}
+
+async function save() {
+  if (!form.warehouseId || !form.code.trim() || !form.type || !form.fbaWarehouseCode || form.volume <= 0 || form.purchasePrice < 0 || !form.status) { ElMessage.warning('请完整填写仓库、托盘编码、类型、容积、采购价格、所属 FBA 仓和状态'); return }
+  saving.value = true; mutationError.value = null
+  const payload = { palletCode: form.code.trim(), palletType: form.type, fbaWarehouseCode: form.fbaWarehouseCode, capacityCbm: form.volume, unitPrice: form.purchasePrice, status: form.status, locationId: null, remark: form.remark.trim() || null }
+  try {
+    if (dialogMode.value === 'edit') await updatePallet(form.warehouseId, form.id, { ...payload, version: form.version })
+    else await createPallet(form.warehouseId, payload)
+    dialogOpen.value = false; ElMessage.success(dialogMode.value === 'edit' ? '托盘已更新' : '托盘已新增'); await load()
+  } catch (error) { mutationError.value = getApiErrorDetails(error, '托盘保存失败，请重试') }
+  finally { saving.value = false }
+}
+
+function search(model: QueryModel) { page.value = 1; void load(model) }
+async function printPallet(source: object) {
+  if (printingId.value) return
+  const row = source as PalletListItem
+  printingId.value = row.id; mutationError.value = null
+  try {
+    const blob = await getPalletLabelPdf(row.warehouseId, row.id)
+    const url = URL.createObjectURL(blob)
+    try {
+      const link = document.createElement('a')
+      link.href = url; link.download = `${row.code}-托盘码.pdf`; link.click()
+    } finally { window.setTimeout(() => URL.revokeObjectURL(url), 0) }
+    ElMessage.success('已生成 1 张托盘标签 PDF')
+  } catch (error) { mutationError.value = getApiErrorDetails(error, '托盘标签打印失败，请重试') }
+  finally { printingId.value = '' }
+}
+function resetSearch(model: QueryModel) { page.value = 1; void load(model) }
+function openDetail(source: object) { const row = source as PalletListItem; void router.push({ name: 'overseas-pallet-detail', params: { palletId: row.id }, query: { warehouseId: row.warehouseId } }) }
+async function initialize() { await loadWarehouses(); if (!loadError.value) await load() }
+onMounted(initialize)
+</script>
+
+<template>
+  <AdminPage class="admin-density"><OperationErrorToast :details="mutationError" />
+  <section class="summary-grid" aria-label="海外托盘数量概览"><article><span>托盘总数</span><strong>{{ summary.totalCount }}</strong></article><article><span>闲置托盘</span><strong class="idle">{{ summary.idleCount }}</strong></article><article><span>占用托盘</span><strong class="occupied">{{ summary.occupiedCount }}</strong></article><article><span>已报废</span><strong>{{ summary.scrappedCount }}</strong></article></section>
+  <ListPageLayout aria-label="托盘管理列表">
+    <template #toolbar><QueryToolbar v-model="filters" class="surface-panel" :fields="fields" :loading="loading || contextLoading" ariaLabel="托盘筛选" preference-key="overseas-pallets-query" @search="search" @reset="resetSearch" /></template>
+    <template v-if="loadError" #state><LoadErrorState title="托盘数据加载失败" :message="loadError.message" :loading="loading || contextLoading" @retry="retryLoad"><template #details><ApiErrorMeta :details="loadError" /></template></LoadErrorState></template>
+    <section v-if="!loadError" class="surface-panel table-panel"><DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :loading="loading" :total="total" preference-key="overseas-pallets" row-key="id" empty-text="暂无托盘" @update:page="load()" @update:page-size="page = 1; load()">
+      <template #toolbar-actions><el-button v-if="access.can(permission.palletCreate)" type="primary" @click="openCreate"><Plus :size="16" />新增托盘</el-button></template>
+      <template #actions="{ row }"><div class="density-actions"><el-button class="density-action" data-tone="neutral" size="small" @click="openDetail(row)">查看</el-button><el-button v-if="access.can(permission.palletList)" class="density-action" data-tone="neutral" size="small" :loading="printingId === row.id" :disabled="Boolean(printingId) && printingId !== row.id" @click="printPallet(row)">打印</el-button><el-button class="density-action" data-tone="neutral" v-if="access.can(permission.palletEdit)" size="small" @click="openEdit(row)">编辑</el-button></div></template>
+      <template #pagination-left>共 {{ total }} 条托盘</template>
+    </DataTable></section>
+  </ListPageLayout>
+  <AppDialog class="admin-density-dialog" v-model="dialogOpen" :title="dialogMode === 'create' ? '新增托盘' : '编辑托盘'" width="min(760px, calc(100vw - 28px))" confirm-text="保存" :confirm-loading="saving" @confirm="save">
+    <el-form class="density-form" label-position="top"><el-row :gutter="16">
+      <el-col :span="12"><el-form-item label="托盘编码" required><el-input v-model="form.code" maxlength="128" placeholder="请输入托盘编码" /></el-form-item></el-col>
+      <el-col :span="12"><el-form-item label="托盘类型" required><el-select v-model="form.type" placeholder="请选择托盘类型"><el-option v-for="value in ['WOOD', 'PLASTIC', 'METAL', 'PAPER', 'FUMIGATION_FREE']" :key="value" :label="palletTypeLabel(value)" :value="value" /></el-select></el-form-item></el-col>
+      <el-col :span="12"><el-form-item label="容积(m³)" required><el-input-number v-model="form.volume" :min="0.0001" :precision="4" controls-position="right" placeholder="请输入容积" /></el-form-item></el-col>
+      <el-col :span="12"><el-form-item label="采购价格(USD)" required><el-input-number v-model="form.purchasePrice" :min="0" :precision="2" controls-position="right" placeholder="请输入采购价格" /></el-form-item></el-col>
+      <el-col :span="12"><el-form-item label="仓库" required><el-select v-model="form.warehouseId" filterable :disabled="dialogMode === 'edit'" placeholder="请选择海外仓"><el-option v-for="item in warehouses" :key="item.id" :label="`${item.warehouseName}（${item.warehouseCode}）`" :value="String(item.id)" /></el-select></el-form-item></el-col>
+      <el-col :span="12"><el-form-item label="所属 FBA 仓" required><el-select v-model="form.fbaWarehouseCode" filterable placeholder="请选择所属 FBA 仓"><el-option v-for="item in fbaWarehouses" :key="String(item.id)" :label="`${item.warehouseName}（${item.warehouseCode}）`" :value="item.warehouseCode" /></el-select></el-form-item></el-col>
+      <el-col :span="12"><el-form-item label="状态" required><el-select v-model="form.status" placeholder="请选择托盘状态"><el-option label="闲置" value="IDLE" /><el-option label="占用" value="OCCUPIED" /><el-option label="已报废" value="SCRAPPED" /></el-select></el-form-item></el-col>
+      <el-col :span="24"><el-form-item label="备注"><el-input v-model="form.remark" type="textarea" :rows="3" maxlength="500" placeholder="请输入备注（选填）" /></el-form-item></el-col>
+    </el-row></el-form>
+  </AppDialog>
+  </AdminPage>
+</template>
+
+<style scoped>
+.summary-grid span { color:var(--cc-muted); font-size:var(--admin-font-caption); }.summary-grid .idle { color:var(--el-color-success); }.summary-grid .occupied { color:var(--el-color-warning); }
+.el-form :deep(.el-row) { margin-left: 0 !important; margin-right: 0 !important; }
+.el-form :deep(.el-input), .el-form :deep(.el-select), .el-form :deep(.el-input-number) { width: 100%; }
+
+.summary-grid { display: flex; gap: 0; flex-wrap: wrap; border: 1px solid var(--cc-border); background: var(--admin-surface); }
+.summary-grid article { display: flex; gap: var(--admin-space-3); padding: var(--admin-space-3) var(--admin-space-5); border: 0; border-radius: 0; background:#fff; flex: 1 1 200px; align-items: baseline; border-right: 1px solid var(--cc-border); }
+.summary-grid article:last-child { border-right: 0; }
+.summary-grid strong { font-size: var(--admin-font-body); }
+
+</style>
diff --git a/src/modules/overseas-warehouse/pages/ProductDetailView.vue b/src/modules/overseas-warehouse/pages/ProductDetailView.vue
new file mode 100644
index 00000000..c1e913df
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/ProductDetailView.vue
@@ -0,0 +1,17 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import OverseasReadOnlyDetail from '../components/OverseasReadOnlyDetail.vue'
+
+const route = useRoute()
+const router = useRouter()
+const productId = computed(() => String(route.params.productId || '—'))
+const groups = [
+  { title: '基础信息', fields: ['商品SKU', '中文品名', '英文品名', '产品分类'] },
+  { title: '包装信息', fields: ['长(cm)', '宽(cm)', '高(cm)', '重量(kg)', '包装体积(m³)'] },
+  { title: '其他信息', fields: ['创建时间', '更新时间', '备注'] },
+]
+function back() { void router.push({ name: 'overseas-products' }) }
+</script>
+
+<template><OverseasReadOnlyDetail title="产品详情" reference-label="商品SKU" :reference-value="productId" back-label="返回产品库" domain="产品详情" :groups="groups" @back="back" /></template>
diff --git a/src/modules/overseas-warehouse/pages/ProductsView.vue b/src/modules/overseas-warehouse/pages/ProductsView.vue
new file mode 100644
index 00000000..6cd80208
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/ProductsView.vue
@@ -0,0 +1,65 @@
+<script setup lang="ts">
+import { reactive, ref } from 'vue'
+import { Eye, Pencil, Plus } from '@lucide/vue'
+import { useRouter } from 'vue-router'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import ContractPendingNotice from '../components/ContractPendingNotice.vue'
+import ContractPendingFormDialog from '../components/ContractPendingFormDialog.vue'
+import { overseasWarehousePermissions as permission } from '../permissions'
+import type { ProductListItem } from '../types'
+
+const access = useAccessPreviewStore()
+const router = useRouter()
+const rows = ref<ProductListItem[]>([])
+const page = ref(1)
+const pageSize = ref(10)
+const filters = ref<QueryModel>({ sku: '', productName: '', category: '' })
+const fields: QueryField[] = [
+  { key: 'sku', type: 'input', label: '商品SKU', placeholder: '请输入商品SKU', width: 180 },
+  { key: 'productName', type: 'input', label: '中文品名', placeholder: '请输入中文品名', width: 190 },
+  { key: 'category', type: 'select', label: '品类', placeholder: '全部品类', width: 150, options: ['电子', '家居', '服饰', '户外'].map((value) => ({ label: value, value })) },
+]
+const columns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 180, fixed: 'left', slotName: 'actions' },
+  { key: 'sku', label: '商品SKU', minWidth: 150 }, { key: 'productName', label: '中文品名', minWidth: 180 },
+  { key: 'englishName', label: '英文品名', minWidth: 180 }, { key: 'category', label: '品类', width: 120 },
+  { key: 'length', label: '长(cm)', width: 100, align: 'right' }, { key: 'width', label: '宽(cm)', width: 100, align: 'right' },
+  { key: 'height', label: '高(cm)', width: 100, align: 'right' }, { key: 'weight', label: '重量(kg)', width: 110, align: 'right' },
+]
+const dialogOpen = ref(false)
+const dialogMode = ref<'create' | 'edit'>('create')
+const form = reactive({ sku: '', productName: '', englishName: '', category: '', length: undefined as number | undefined, width: undefined as number | undefined, height: undefined as number | undefined, weight: undefined as number | undefined })
+
+function optionalNumber(value: unknown) { const number = Number(value); return value === '' || value == null || !Number.isFinite(number) ? undefined : number }
+function openForm(mode: 'create' | 'edit', source?: object) { const row = source as ProductListItem | undefined; dialogMode.value = mode; Object.assign(form, { sku: '', productName: '', englishName: '', category: '', length: undefined, width: undefined, height: undefined, weight: undefined }); if (mode === 'edit' && row) Object.assign(form, { sku: String(row.sku || ''), productName: String(row.productName || ''), englishName: String(row.englishName || ''), category: String(row.category || ''), length: optionalNumber(row.length), width: optionalNumber(row.width), height: optionalNumber(row.height), weight: optionalNumber(row.weight) }); dialogOpen.value = true }
+function openDetail(source: object) { const row = source as ProductListItem; void router.push({ name: 'overseas-product-detail', params: { productId: String(row.sku) } }) }
+</script>
+
+<template>
+  <AdminPage><ListPageLayout aria-label="产品库列表">
+    <template #toolbar><QueryToolbar v-model="filters" class="surface-panel" :fields="fields" ariaLabel="产品筛选" preference-key="overseas-products-query" @search="page = 1" /></template>
+    <template #state><ContractPendingNotice domain="产品库" /></template>
+    <section class="surface-panel table-panel"><DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :total="0" preference-key="overseas-products" row-key="sku" empty-text="海外区域产品查询契约待接入">
+      <template #toolbar-actions><el-button v-if="access.can(permission.productCreate)" type="primary" @click="openForm('create')"><Plus :size="16" />新增产品</el-button></template>
+      <template #actions="{ row }"><el-button size="small" plain type="primary" @click="openDetail(row)"><Eye :size="15" />查看</el-button><el-button v-if="access.can(permission.productEdit)" size="small" plain @click="openForm('edit', row)"><Pencil :size="15" />编辑</el-button></template>
+      <template #pagination-left>共 0 条产品</template>
+    </DataTable></section>
+  </ListPageLayout>
+  <ContractPendingFormDialog v-model="dialogOpen" :title="dialogMode === 'create' ? '新增产品' : '编辑产品'" width="min(560px, calc(100vw - 28px))" domain="产品" confirm-text="确定">
+    <el-form label-width="110px" label-position="right">
+      <el-form-item label="商品SKU" required><el-input v-model="form.sku" placeholder="如 SKU-A1001" /></el-form-item>
+      <el-form-item label="中文品名" required><el-input v-model="form.productName" placeholder="请输入中文品名" /></el-form-item>
+      <el-form-item label="英文品名"><el-input v-model="form.englishName" placeholder="请输入英文品名" /></el-form-item>
+      <el-form-item label="品类" required><el-select v-model="form.category" placeholder="请选择品类"><el-option v-for="value in ['电子', '家居', '服饰', '户外']" :key="value" :label="value" :value="value" /></el-select></el-form-item>
+      <el-form-item label="长(cm)"><el-input-number v-model="form.length" :min="0" :precision="2" controls-position="right" placeholder="请输入长度" /></el-form-item>
+      <el-form-item label="宽(cm)"><el-input-number v-model="form.width" :min="0" :precision="2" controls-position="right" placeholder="请输入宽度" /></el-form-item>
+      <el-form-item label="高(cm)"><el-input-number v-model="form.height" :min="0" :precision="2" controls-position="right" placeholder="请输入高度" /></el-form-item>
+      <el-form-item label="重量(kg)"><el-input-number v-model="form.weight" :min="0" :precision="3" controls-position="right" placeholder="请输入重量" /></el-form-item>
+    </el-form>
+  </ContractPendingFormDialog>
+  </AdminPage>
+</template>
diff --git a/src/modules/overseas-warehouse/pages/RelabelOrderDetailView.test.ts b/src/modules/overseas-warehouse/pages/RelabelOrderDetailView.test.ts
new file mode 100644
index 00000000..f6c0b348
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/RelabelOrderDetailView.test.ts
@@ -0,0 +1,16 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/overseas-warehouse/pages/RelabelOrderDetailView.vue'), 'utf8')
+
+describe('RelabelOrderDetailView', () => {
+  it('renders carton relabel mappings as a row list instead of summary form fields', () => {
+    expect(source).toContain('<template #content-after>')
+    expect(source).toContain('<h2>箱唛换标信息</h2>')
+    expect(source).toContain('v-for="item in detail?.items || []"')
+    expect(source).toContain('text(item.cartonMark)')
+    expect(source).toContain('text(item.fbaCartonMark)')
+    expect(source).not.toContain("{ title: '箱唛换标信息', fields:")
+  })
+})
diff --git a/src/modules/overseas-warehouse/pages/RelabelOrderDetailView.vue b/src/modules/overseas-warehouse/pages/RelabelOrderDetailView.vue
new file mode 100644
index 00000000..f6ca525c
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/RelabelOrderDetailView.vue
@@ -0,0 +1,149 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, ref, onBeforeUnmount } from 'vue'
+import { Eye, FileUp, Undo2 } from '@lucide/vue'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { overseasWarehousePermissions as permission } from '../permissions'
+import { getRelabelReviewTask, returnRelabelForRework } from '../api/relabelOrders'
+import { useRoute, useRouter } from 'vue-router'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { downloadRelabelCompletionPhoto, downloadRelabelPdf, getRelabelOrder, uploadRelabelPdf, type RelabelDetailDto } from '../api/relabelOrders'
+import { formatOverseasDateTime } from '../lastMilePresentation'
+import OverseasReadOnlyDetail from '../components/OverseasReadOnlyDetail.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+
+const route = useRoute()
+const router = useRouter()
+const orderId = computed(() => String(route.params.orderId || ''))
+const detail = ref<RelabelDetailDto | null>(null)
+const loading = ref(false)
+const access = useAccessPreviewStore()
+const returning = ref(false)
+async function returnForRework() {
+  if (returning.value) return
+  returning.value = true
+  try {
+    const task = await getRelabelReviewTask(orderId.value)
+    const { value } = await ElMessageBox.prompt('填写退回原因，PDA 将展示此备注并重新逐箱作业、上传照片。', '退回重新贴标', { customClass: 'admin-density-confirm', inputType: 'textarea', inputValidator: (value) => Boolean(value?.trim()) && value.trim().length <= 1000 || '请填写 1 至 1000 字退回原因', confirmButtonText: '确认退回' })
+    await returnRelabelForRework(orderId.value, task.version, value.trim(), crypto.randomUUID())
+    ElMessage.success('已退回 PDA 重新贴标'); await load()
+  } catch (error) { if (error !== 'cancel' && error !== 'close') ElMessage.error(getApiErrorDetails(error, '退回失败，请刷新后重试').message) }
+  finally { returning.value = false }
+}
+const loadError = ref<ApiErrorDetails | null>(null)
+const uploading = ref(false)
+const previewUrl = ref('')
+const previewTitle = ref('')
+const previewOpen = ref(false)
+const groups = [
+  { title: '单据信息', fields: ['换标单号', '关联订单', '状态', '资金状态', '创建时间', '更新时间'] },
+  { title: '商品信息', fields: ['商品SKU', '中文品名', '箱数', '预算总价'] },
+  { title: '作业要求', fields: ['贴标要求', '上传文件', '备注'] },
+  { title: '费用明细', fields: ['换标费总计', '资金异常说明'] },
+]
+function text(value: unknown) { return String(value ?? '').trim() || '—' }
+function status(value: unknown) {
+  if (value === 'CUSTOMER_CONFIRM_PENDING') return '待客户确认'
+  if (value === 'PROCESSING') return '处理中'
+  return ['READY_FOR_OUTBOUND', 'COMPLETED'].includes(String(value || '')) ? '换标完成' : '待处理'
+}
+function walletStatus(value: unknown) { return ({ FREEZE_PENDING: '冻结中', FROZEN: '已冻结', SETTLE_PENDING: '结算中', SETTLED: '已结算', RELEASE_PENDING: '释放中', RELEASED: '已释放', FREEZE_FAILED: '冻结失败', SETTLE_FAILED: '结算失败', RELEASE_FAILED: '释放失败' } as Record<string,string>)[String(value || '')] || text(value) }
+const referenceValue = computed(() => text(detail.value?.application.relabelNo || '换标单号待补充'))
+const fieldValues = computed<Record<string, string | number>>(() => {
+  const value = detail.value
+  const items = value?.items || []
+  return {
+    换标单号: text(value?.application.relabelNo),
+    关联订单: text(value?.application.lastlegOrderNo || value?.application.customerOrderNo),
+    状态: status(value?.application.status),
+    资金状态: walletStatus(value?.application.walletStatus),
+    创建时间: formatOverseasDateTime(value?.application.createdAt),
+    更新时间: value?.history.length ? formatOverseasDateTime(value.history[value.history.length - 1]?.createdAt) : '—',
+    商品SKU: items.map((item) => text(item.skuCode)).join('、') || '—',
+    中文品名: items.map((item) => text(item.productNameZh)).join('、') || '—',
+    箱数: Number(value?.application.totalPackageCount || 0),
+    预算总价: '—',
+    贴标要求: items.map((item) => text(item.labelRequirement)).join('；') || '—',
+    上传文件: items.map((item) => text(item.relabelFileName)).filter((item) => item !== '—').join('、') || '—',
+    备注: text(value?.remark),
+    换标费总计: value?.application.chargeAmount == null ? '—' : `${Number(value.application.chargeAmount).toFixed(2)} ${value.application.chargeCurrency || 'USD'}`,
+    资金异常说明: text(value?.application.walletErrorMessage),
+  }
+})
+async function load() {
+  if (!orderId.value) { loadError.value = { message: '详情缺少换标单号，请从换标单列表重新进入' }; return }
+  loading.value = true; loadError.value = null
+  try { detail.value = await getRelabelOrder(orderId.value) }
+  catch (error) { loadError.value = getApiErrorDetails(error, '换标单详情加载失败，请重试') }
+  finally { loading.value = false }
+}
+function back() { void router.push({ name: 'overseas-relabel-orders' }) }
+onMounted(load)
+onBeforeUnmount(() => { if (previewUrl.value) URL.revokeObjectURL(previewUrl.value) })
+async function uploadPdf(event: Event, scope: 'TOTAL' | 'ITEM', itemId?: string) {
+  const input = event.target as HTMLInputElement; const file = input.files?.[0]; input.value = ''
+  if (!file || !detail.value) return
+  if (file.type !== 'application/pdf' && !file.name.toLowerCase().endsWith('.pdf')) { ElMessage.warning('只支持PDF文件'); return }
+  if (file.size > 50 * 1024 * 1024) { ElMessage.warning('PDF文件不能超过50MB'); return }
+  uploading.value = true
+  try { detail.value = await uploadRelabelPdf(orderId.value, file, scope, itemId); ElMessage.success(scope === 'TOTAL' ? '总PDF上传成功' : '明细PDF上传成功') }
+  catch (error) { ElMessage.error(getApiErrorDetails(error, 'PDF上传失败').message) }
+  finally { uploading.value = false }
+}
+async function previewPdf(fileId: string | null | undefined, name: string, scope: 'TOTAL' | 'ITEM', itemId?: string) {
+  if (!fileId) return
+  try { const blob = await downloadRelabelPdf(orderId.value, fileId, scope, itemId); if (previewUrl.value) URL.revokeObjectURL(previewUrl.value); previewUrl.value = URL.createObjectURL(blob); previewTitle.value = name; previewOpen.value = true }
+  catch (error) { ElMessage.error(getApiErrorDetails(error, 'PDF预览加载失败').message) }
+}
+async function previewCompletionPhoto(fileId: string) {
+  try { const blob = await downloadRelabelCompletionPhoto(orderId.value, fileId); const url = URL.createObjectURL(blob); window.open(url, '_blank', 'noopener,noreferrer'); window.setTimeout(() => URL.revokeObjectURL(url), 60_000) }
+  catch (error) { ElMessage.error(getApiErrorDetails(error, '完工照片加载失败').message) }
+}
+</script>
+
+<template>
+  <OverseasReadOnlyDetail class="admin-density" dense title="换标单详情" reference-label="换标单号" :reference-value="referenceValue" back-label="返回换标单" domain="换标单详情" :groups="groups" :field-values="fieldValues" :pending="false" :status-text="detail ? status(detail.application.status) : '加载中'" :loading="loading" :show-content="!loadError" @back="back">
+    <template #state><LoadErrorState v-if="loadError" title="换标单详情加载失败" :message="loadError.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="loadError" /></template></LoadErrorState></template>
+    <template #content-after>
+      <section v-if="access.can(permission.relabelOrderStatus) && ['CUSTOMER_CONFIRM_PENDING', 'PROCESSING'].includes(detail?.application.status || '') && detail?.completionEvidence?.photoFileIds?.length" class="relabel-document-panel"><el-button type="warning" :loading="returning" @click="returnForRework"><Undo2 :size="15" />退回重新贴标</el-button></section>
+      <section class="relabel-document-panel" aria-label="PDA换标完工证据"><div class="relabel-mark-list__head"><h2>PDA 换标完工证据</h2><span>{{ detail?.completionEvidence?.reviewerName ? `复核人：${detail.completionEvidence.reviewerName}` : '等待仓库作业' }}</span></div><div v-if="detail?.completionEvidence?.photoFileIds?.length" class="document-row"><strong>共 {{ detail.completionEvidence.photoFileIds.length }} 张完工照片</strong><span class="document-actions density-actions"><el-button class="density-action" data-tone="neutral" v-for="(fileId, index) in detail.completionEvidence.photoFileIds" :key="fileId" size="small" @click="previewCompletionPhoto(fileId)"><Eye :size="14" />照片 {{ index + 1 }}</el-button></span></div><div v-else class="attachment-empty">暂未上传完工照片</div></section>
+      <section class="relabel-document-panel" aria-label="总换标文件"><div class="relabel-mark-list__head"><h2>总换标 PDF</h2><label class="file-picker"><FileUp :size="15" />{{ uploading ? '上传中' : (detail?.application.totalFileName ? '更换PDF' : '上传PDF') }}<input type="file" accept="application/pdf,.pdf" :disabled="uploading" @change="uploadPdf($event, 'TOTAL')" /></label></div><div v-if="detail?.application.totalFileId" class="document-row"><strong>{{ detail.application.totalFileName }}</strong><el-button class="density-action" data-tone="neutral" size="small" @click="previewPdf(detail.application.totalFileId, detail.application.totalFileName || '总换标PDF', 'TOTAL')"><Eye :size="14" />直接预览</el-button></div><div v-else class="attachment-empty">暂未上传总换标PDF</div></section>
+      <section class="relabel-mark-list" aria-label="箱唛换标信息">
+        <div class="relabel-mark-list__head"><h2>箱唛换标信息</h2><span>共 {{ detail?.items.length || 0 }} 条</span></div>
+        <div class="relabel-mark-list__scroll">
+          <table class="density-table">
+            <thead><tr><th>我方箱唛</th><th>FBA 箱唛</th><th>商品 SKU</th><th>中文品名</th><th>FBA 货件编号</th><th>换标新 SKU</th><th>目的仓</th><th>明细PDF</th></tr></thead>
+            <tbody>
+              <tr v-for="item in detail?.items || []" :key="item.id"><td class="mark-code">{{ text(item.cartonMark) }}</td><td class="mark-code">{{ text(item.fbaCartonMark) }}</td><td>{{ text(item.skuCode) }}</td><td>{{ text(item.productNameZh) }}</td><td>{{ text(item.shipmentNo) }}</td><td>{{ text(item.newSkuCode) }}</td><td>{{ text(item.destinationWarehouseId) }}</td><td><span v-if="item.relabelFileName" class="document-actions density-actions"><strong>{{ item.relabelFileName }}</strong><el-button class="density-action" data-tone="neutral" size="small" @click="previewPdf(item.relabelFileId, item.relabelFileName, 'ITEM', item.id)">预览</el-button></span><label v-else class="inline-file-picker"><FileUp :size="14" />上传<input type="file" accept="application/pdf,.pdf" :disabled="uploading" @change="uploadPdf($event, 'ITEM', item.id)" /></label></td></tr>
+              <tr v-if="!detail?.items.length"><td class="empty-cell" colspan="8">暂无箱唛换标信息</td></tr>
+            </tbody>
+          </table>
+        </div>
+      </section>
+    </template>
+  </OverseasReadOnlyDetail>
+  <AppDialog class="admin-density-dialog" v-if="previewUrl" v-model="previewOpen" :title="previewTitle" width="min(900px, calc(100vw - 28px))" :show-footer="false"><div class="pdf-preview"><iframe :src="previewUrl" :title="`${previewTitle}预览`" /></div></AppDialog>
+</template>
+
+<style scoped>
+.relabel-mark-list { min-width: 0; grid-column: 1 / -1; padding: var(--admin-space-5); }
+.relabel-mark-list__head { display: flex; align-items: center; justify-content: space-between; margin-bottom: var(--admin-space-5); }
+.relabel-mark-list__head h2 { margin: 0; color: var(--cc-text); font-size: var(--admin-font-section); }
+.relabel-mark-list__head span { color: var(--cc-muted); font-size: var(--admin-font-caption); }
+.relabel-mark-list__scroll { overflow-x: auto; border: 1px solid var(--cc-border); border-radius: var(--admin-radius); }
+table { min-width: 1120px; }
+.mark-code { color: #245b9e; font-weight: 600; }
+.relabel-document-panel { grid-column: 1 / -1; padding: var(--admin-space-5); border-bottom: 1px solid var(--cc-border); }
+.document-row { display:flex; align-items:center; justify-content:space-between; gap:var(--admin-space-5); padding:var(--admin-space-5); border:1px solid var(--cc-border); border-radius:var(--admin-radius); }
+.file-picker, .inline-file-picker { display:inline-flex; align-items:center; gap:var(--admin-space-2); color:var(--el-color-primary); cursor:pointer; }
+.file-picker input, .inline-file-picker input { display:none; }
+.pdf-preview { overflow:hidden; border:1px solid var(--cc-border); border-radius:var(--admin-radius); background:#f5f7fa; }
+.pdf-preview iframe { display:block; width:100%; height:min(72vh,760px); border:0; background:#fff; }
+
+.empty-cell { height: var(--admin-empty-height); color: var(--cc-muted); text-align: center; }
+.document-row strong { min-width: 0; overflow-wrap: anywhere; }
+
+</style>
diff --git a/src/modules/overseas-warehouse/pages/RelabelOrdersView.test.ts b/src/modules/overseas-warehouse/pages/RelabelOrdersView.test.ts
new file mode 100644
index 00000000..4b5cfcd3
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/RelabelOrdersView.test.ts
@@ -0,0 +1,139 @@
+import ElementPlus from 'element-plus'
+import { enableAutoUnmount, flushPromises, mount, type VueWrapper } from '@vue/test-utils'
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { listPlatformTenants } from '@/modules/iam'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import {
+  changeRelabelOrderStatus,
+  createRelabelOrder,
+  listRelabelOrders,
+  listRelabelWarehouseOptions,
+} from '../api/relabelOrders'
+import RelabelOrdersView from './RelabelOrdersView.vue'
+
+vi.mock('vue-router', () => ({ useRouter: () => ({ push: vi.fn() }) }))
+vi.mock('@/core/access/accessPreview', () => ({ useAccessPreviewStore: () => ({ can: () => true }) }))
+vi.mock('@/modules/iam', () => ({ listPlatformTenants: vi.fn() }))
+vi.mock('../api/relabelOrders', () => ({
+  changeRelabelOrderStatus: vi.fn(),
+  createRelabelOrder: vi.fn(),
+  listRelabelOrders: vi.fn(),
+  listRelabelWarehouseOptions: vi.fn(),
+}))
+
+class ResizeObserverStub implements ResizeObserver { observe() {} unobserve() {} disconnect() {} }
+function memoryStorage(): Storage { const values = new Map<string, string>(); return { get length() { return values.size }, clear: () => values.clear(), getItem: (key) => values.get(key) ?? null, key: (index) => [...values.keys()][index] ?? null, removeItem: (key) => values.delete(key), setItem: (key, value) => values.set(key, value) } }
+function formItem(wrapper: VueWrapper<any>, label: string) {
+  const item = wrapper.findAllComponents({ name: 'ElFormItem' }).find((candidate) => candidate.props('label') === label)
+  if (!item) throw new Error(`Missing form item: ${label}`)
+  return item
+}
+
+function select(wrapper: VueWrapper<any>, placeholder: string) {
+  const target = wrapper.findAllComponents({ name: 'ElSelect' }).find((candidate) => candidate.props('placeholder') === placeholder)
+  if (!target) throw new Error(`Missing select: ${placeholder}`)
+  return target
+}
+
+enableAutoUnmount(afterEach)
+afterAll(() => vi.unstubAllGlobals())
+
+describe('RelabelOrdersView', () => {
+  beforeEach(() => {
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+    vi.stubGlobal('localStorage', memoryStorage())
+    vi.mocked(listPlatformTenants).mockReset().mockResolvedValue({ records: [{ id: '10001', tenantName: '客户甲', status: 'ACTIVE' } as never], page: 1, size: 200, total: 1, pages: 1 })
+    vi.mocked(listRelabelOrders).mockReset().mockResolvedValue({ records: [], page: 1, size: 10, total: 0, pages: 0 })
+    vi.mocked(listRelabelWarehouseOptions).mockReset()
+    vi.mocked(createRelabelOrder).mockReset()
+    vi.mocked(changeRelabelOrderStatus).mockReset()
+  })
+
+  it('loads shared receiving warehouse options independently from the selected customer', async () => {
+    vi.mocked(listRelabelWarehouseOptions).mockResolvedValue({ records: [{ id: 'WH-B', customerId: '0', warehouseCode: 'B', warehouseName: 'B仓', warehouseType: 'OVERSEAS', status: 'ACTIVE' }], page: 1, size: 200, total: 1, pages: 1 })
+    const wrapper = mount(RelabelOrdersView, { attachTo: document.body, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    await wrapper.findAll('button').find((button) => button.text().includes('新增换标单'))!.trigger('click')
+    await flushPromises()
+
+    const customer = select(wrapper, '请选择 ACTIVE 客户')
+    customer.vm.$emit('update:modelValue', '10001'); customer.vm.$emit('change', '10001')
+    await flushPromises()
+
+    const labels = wrapper.findAllComponents({ name: 'ElOption' }).map((option) => option.props('label'))
+    expect(listRelabelWarehouseOptions).toHaveBeenCalledOnce()
+    expect(labels).toContain('B仓 · B')
+  })
+
+  it('reuses one idempotency key after a failed create retry', async () => {
+    vi.mocked(listRelabelWarehouseOptions).mockResolvedValue({ records: [{ id: 'WH-1', customerId: '10001', warehouseCode: 'LAX', warehouseName: '洛杉矶仓', warehouseType: 'OVERSEAS', status: 'ACTIVE' }], page: 1, size: 200, total: 1, pages: 1 })
+    vi.mocked(createRelabelOrder).mockRejectedValueOnce(new Error('temporary')).mockResolvedValueOnce({ application: { id: '1', relabelNo: 'RL-1' }, items: [], history: [] })
+    const wrapper = mount(RelabelOrdersView, { attachTo: document.body, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    await wrapper.findAll('button').find((button) => button.text().includes('新增换标单'))!.trigger('click')
+    await flushPromises()
+
+    const customer = select(wrapper, '请选择 ACTIVE 客户')
+    customer.vm.$emit('update:modelValue', '10001'); customer.vm.$emit('change', '10001')
+    await flushPromises()
+    const warehouse = select(wrapper, '请选择 ACTIVE+RECEIVING 海外仓')
+    warehouse.vm.$emit('update:modelValue', 'WH-1')
+    formItem(wrapper, '关联订单').findComponent({ name: 'ElInput' }).vm.$emit('update:modelValue', 'CO-1')
+    formItem(wrapper, '商品SKU').findComponent({ name: 'ElInput' }).vm.$emit('update:modelValue', 'SKU-1')
+    formItem(wrapper, '中文品名').findComponent({ name: 'ElInput' }).vm.$emit('update:modelValue', '商品一')
+    formItem(wrapper, '箱数').findComponent({ name: 'ElInputNumber' }).vm.$emit('update:modelValue', 2)
+    formItem(wrapper, '换标费用（CNY）').findComponent({ name: 'ElInputNumber' }).vm.$emit('update:modelValue', 20)
+    formItem(wrapper, '截止时间').findComponent({ name: 'ElDatePicker' }).vm.$emit('update:modelValue', '2026-08-30T10:00:00')
+    formItem(wrapper, '联系人').findComponent({ name: 'ElInput' }).vm.$emit('update:modelValue', '张三')
+    formItem(wrapper, '联系电话').findComponent({ name: 'ElInput' }).vm.$emit('update:modelValue', '13800000000')
+    formItem(wrapper, '贴标要求').findComponent({ name: 'ElSelect' }).vm.$emit('update:modelValue', '换SKU标')
+    formItem(wrapper, '货件号').findComponent({ name: 'ElInput' }).vm.$emit('update:modelValue', 'SHIP-1')
+    formItem(wrapper, '新SKU').findComponent({ name: 'ElInput' }).vm.$emit('update:modelValue', 'SKU-2')
+    await flushPromises()
+
+    const dialog = wrapper.findComponent(AppDialog)
+    dialog.vm.$emit('confirm')
+    await flushPromises()
+    expect(dialog.props('modelValue')).toBe(true)
+    dialog.vm.$emit('confirm')
+    await flushPromises()
+
+    expect(createRelabelOrder).toHaveBeenCalledTimes(2)
+    const firstKey = vi.mocked(createRelabelOrder).mock.calls[0]![1].idempotencyKey
+    const retryKey = vi.mocked(createRelabelOrder).mock.calls[1]![1].idempotencyKey
+    expect(firstKey).toBeTruthy()
+    expect(retryKey).toBe(firstKey)
+    expect(createRelabelOrder).toHaveBeenLastCalledWith('10001', expect.objectContaining({
+      customerOrderNo: 'CO-1', overseasWarehouseId: 'WH-1', idempotencyKey: firstKey,
+      items: [expect.objectContaining({ skuCode: 'SKU-1', newSkuCode: 'SKU-2', labelRequirement: '换SKU标' })],
+    }))
+  })
+
+  it('offers only backend-allowed audit transitions', async () => {
+    vi.mocked(listRelabelOrders).mockResolvedValueOnce({
+      records: [{ id: '1', relabelNo: 'RL-1', customerOrderNo: 'CO-1', skuCodes: 'SKU-1', totalPackageCount: 2, status: 'PENDING_PROCESSING' }],
+      page: 1, size: 10, total: 1, pages: 1,
+    })
+    const wrapper = mount(RelabelOrdersView, { attachTo: document.body, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    await wrapper.findAll('button').find((button) => button.text().includes('审核'))!.trigger('click')
+    await flushPromises()
+
+    const labels = formItem(wrapper, '目标状态').findAllComponents({ name: 'ElOption' }).map((option) => option.props('label'))
+    expect(labels).toEqual(expect.arrayContaining(['处理中', '已驳回', '已取消']))
+    expect(labels).not.toContain('已完成')
+  })
+
+  it('passes the relabel order number search to the backend', async () => {
+    const wrapper = mount(RelabelOrdersView, { attachTo: document.body, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    const input = wrapper.find('input[placeholder="请输入换标单号"]')
+    expect(input.exists()).toBe(true)
+    await input.setValue('FBR202608272092853218068373506')
+    await wrapper.findAll('button').find((button) => button.text().includes('查询'))!.trigger('click')
+    await flushPromises()
+    expect(listRelabelOrders).toHaveBeenLastCalledWith(expect.objectContaining({
+      relabelNo: 'FBR202608272092853218068373506',
+    }))
+  })
+})
diff --git a/src/modules/overseas-warehouse/pages/RelabelOrdersView.vue b/src/modules/overseas-warehouse/pages/RelabelOrdersView.vue
new file mode 100644
index 00000000..a2ac6a4a
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/RelabelOrdersView.vue
@@ -0,0 +1,225 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, reactive, ref, watch } from 'vue'
+import { Plus } from '@lucide/vue'
+import { ElMessage } from 'element-plus'
+import { useRouter } from 'vue-router'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { listPlatformTenants, type PlatformTenantResource } from '@/modules/iam'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import { changeRelabelOrderStatus, createRelabelOrder, listRelabelOrders, listRelabelWarehouseOptions, type RelabelWarehouseOptionDto } from '../api/relabelOrders'
+import { overseasWarehousePermissions as permission } from '../permissions'
+import { formatOverseasDateTime, relabelBusinessStatusLabel } from '../lastMilePresentation'
+import type { RelabelOrderListItem } from '../types'
+
+const access = useAccessPreviewStore()
+const router = useRouter()
+const rows = ref<RelabelOrderListItem[]>([])
+const loading = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const customers = ref<PlatformTenantResource[]>([])
+const customersLoading = ref(false)
+const warehouses = ref<RelabelWarehouseOptionDto[]>([])
+const warehousesLoading = ref(false)
+const page = ref(1)
+const pageSize = ref(10)
+const total = ref(0)
+const filters = ref<QueryModel>({ relabelNo: '', sku: '', status: '' })
+const fields = computed<QueryField[]>(() => [
+  { key: 'relabelNo', type: 'input', label: '换标单号', placeholder: '请输入换标单号', width: 220 },
+  { key: 'sku', type: 'input', label: '商品SKU', placeholder: '请输入商品SKU', width: 180 },
+  { key: 'status', type: 'select', label: '状态', placeholder: '全部状态', width: 160, options: [{ label: '待处理', value: 'PENDING_PROCESSING' }, { label: '处理中', value: 'PROCESSING' }, { label: '换标完成', value: 'COMPLETED' }] },
+])
+const columns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 180, fixed: 'left', slotName: 'actions' },
+  { key: 'orderNo', label: '换标单号', minWidth: 170 },
+  { key: 'sku', label: '商品SKU', minWidth: 150 },
+  { key: 'productName', label: '中文品名', minWidth: 180 },
+  { key: 'cartons', label: '箱数', width: 90, align: 'right' },
+  { key: 'budgetTotal', label: '预算总价', width: 120, align: 'right' },
+  { key: 'relabelCost', label: '换标费用', width: 120, align: 'right' },
+  { key: 'walletStatus', label: '资金状态', width: 120 },
+  { key: 'labelRequirement', label: '贴标要求', minWidth: 150 },
+  { key: 'fileName', label: '上传文件', minWidth: 160 },
+  { key: 'status', label: '状态', width: 110 },
+  { key: 'createdAt', label: '创建时间', minWidth: 170 },
+]
+const dialogOpen = ref(false)
+const dialogMode = ref<'create' | 'edit'>('create')
+const submitting = ref(false)
+const editSourceStatus = ref('')
+const form = reactive({ orderNo: '', customerId: '', relatedOrderNo: '', sku: '', productName: '', cartons: undefined as number | undefined, budgetTotal: undefined as number | undefined, status: 'PENDING_PROCESSING', labelRequirement: '', relabelCost: undefined as number | undefined, remark: '', warehouseId: '', labelDeadline: '', contactName: '', contactPhone: '', shipmentNo: '', newSkuCode: '' })
+const createIdempotencyKey = ref('')
+const allowedStatusOptions = computed(() => {
+  if (editSourceStatus.value === 'PENDING_PROCESSING') return ['PROCESSING', 'REJECTED', 'CANCELLED']
+  if (editSourceStatus.value === 'PROCESSING') return ['COMPLETED', 'REJECTED', 'CANCELLED']
+  return []
+})
+
+function optionalNumber(value: unknown) { const number = Number(value); return value === '' || value == null || !Number.isFinite(number) ? undefined : number }
+function openForm(mode: 'create' | 'edit', source?: object) {
+  const row = source as RelabelOrderListItem | undefined
+  dialogMode.value = mode
+  Object.assign(form, { orderNo: '', customerId: '', relatedOrderNo: '', sku: '', productName: '', cartons: undefined, budgetTotal: undefined, status: 'PENDING_PROCESSING', labelRequirement: '', relabelCost: undefined, remark: '', warehouseId: '', labelDeadline: '', contactName: '', contactPhone: '', shipmentNo: '', newSkuCode: '' })
+  editSourceStatus.value = ''
+  if (mode === 'edit' && row) {
+    editSourceStatus.value = row.rawStatus || relabelStatusCode(row.status)
+    Object.assign(form, { orderNo: String(row.orderNo || ''), relatedOrderNo: String(row.relatedOrderNo || ''), sku: String(row.sku || ''), productName: String(row.productName || ''), cartons: optionalNumber(row.cartons), budgetTotal: optionalNumber(row.budgetTotal), status: '', labelRequirement: String(row.labelRequirement || ''), relabelCost: optionalNumber(row.relabelCost), remark: String(row.remark || '') })
+  }
+  if (mode === 'create') {
+    createIdempotencyKey.value = globalThis.crypto?.randomUUID?.() || `admin-relabel-${Date.now()}`
+    warehouses.value = []
+    void loadCustomers()
+    void loadWarehouses()
+  }
+  dialogOpen.value = true
+}
+
+async function loadCustomers() {
+  customersLoading.value = true
+  try {
+    const records: PlatformTenantResource[] = []
+    let currentPage = 1
+    let pages = 1
+    do {
+      const result = await listPlatformTenants({ page: currentPage, size: 200, status: 'ACTIVE' })
+      records.push(...result.records.filter((item) => item.status === 'ACTIVE'))
+      pages = Math.max(1, result.pages)
+      currentPage += 1
+    } while (currentPage <= pages)
+    customers.value = records
+  } catch (error) { customers.value = []; ElMessage.error(getApiErrorDetails(error, '客户列表加载失败，请重试').message) }
+  finally { customersLoading.value = false }
+}
+
+async function loadWarehouses() {
+  form.warehouseId = ''
+  warehouses.value = []
+  warehousesLoading.value = true
+  try {
+    const records = (await listRelabelWarehouseOptions()).records.filter((item) => item.status === 'ACTIVE')
+    warehouses.value = records
+  } catch (error) {
+    ElMessage.error(getApiErrorDetails(error, '公共海外收货仓加载失败，请重试').message)
+  } finally {
+    warehousesLoading.value = false
+  }
+}
+
+async function submitForm() {
+  if (submitting.value) return
+  try {
+    if (dialogMode.value === 'create') {
+      if (!form.customerId || !form.warehouseId) { ElMessage.warning('请选择客户和公共海外收货仓'); return }
+      if (!form.relatedOrderNo.trim() || !form.sku.trim() || !form.productName.trim() || !form.cartons || !form.relabelCost || form.relabelCost <= 0 || !form.labelDeadline || !form.contactName.trim() || !form.contactPhone.trim() || !form.shipmentNo.trim() || !form.newSkuCode.trim() || !form.labelRequirement) {
+        ElMessage.warning('请完整填写换标单必填信息')
+        return
+      }
+      submitting.value = true
+      await createRelabelOrder(form.customerId, { customerOrderNo: form.relatedOrderNo.trim(), overseasWarehouseId: form.warehouseId, labelDeadline: form.labelDeadline, contactName: form.contactName.trim(), contactPhone: form.contactPhone.trim(), chargeAmount: Number(form.relabelCost), remark: form.remark.trim() || undefined, idempotencyKey: createIdempotencyKey.value, items: [{ skuCode: form.sku.trim(), productNameZh: form.productName.trim(), totalPackageCount: Number(form.cartons), notifiedPackageCount: Number(form.cartons), shipmentNo: form.shipmentNo.trim(), newSkuCode: form.newSkuCode.trim(), labelRequirement: form.labelRequirement }] })
+      ElMessage.success('换标单已创建')
+    } else {
+      if (!allowedStatusOptions.value.includes(form.status)) { ElMessage.warning('当前状态没有可提交的审核流转'); return }
+      submitting.value = true
+      await changeRelabelOrderStatus(form.orderNo, form.status, form.remark || undefined)
+      ElMessage.success('状态已更新')
+    }
+    dialogOpen.value = false
+    createIdempotencyKey.value = ''
+    await load()
+  } catch (error) { ElMessage.error(getApiErrorDetails(error, '操作失败，请重试').message) }
+  finally { submitting.value = false }
+}
+
+function openDetail(source: object) {
+  const row = source as RelabelOrderListItem
+  void router.push({ name: 'overseas-relabel-order-detail', params: { orderId: String(row.orderNo) } })
+}
+
+function relabelStatus(value: unknown) {
+  return relabelBusinessStatusLabel(value)
+}
+function relabelAuditStatusLabel(value: string) {
+  return ({
+    PROCESSING: '处理中',
+    REJECTED: '已驳回',
+    CANCELLED: '已取消',
+    COMPLETED: '已完成',
+  } as Record<string, string>)[value] || relabelStatus(value)
+}
+function relabelStatusCode(value: unknown) {
+  const codes: Record<string, string> = { 待处理: 'PENDING_PROCESSING', 处理中: 'PROCESSING', 换标完成: 'COMPLETED' }
+  return codes[String(value || '')] || String(value || 'PENDING_PROCESSING')
+}
+function walletStatus(value: unknown) { return ({ FREEZE_PENDING: '冻结中', FROZEN: '已冻结', SETTLE_PENDING: '结算中', SETTLED: '已结算', RELEASE_PENDING: '释放中', RELEASED: '已释放', FREEZE_FAILED: '冻结失败', SETTLE_FAILED: '结算失败', RELEASE_FAILED: '释放失败' } as Record<string,string>)[String(value || '')] || String(value || '—') }
+function canAudit(source: object) {
+  const row = source as RelabelOrderListItem
+  return ['PENDING_PROCESSING', 'PROCESSING'].includes(row.rawStatus || relabelStatusCode(row.status))
+}
+async function load(model: QueryModel = filters.value) {
+  Object.assign(filters.value, model)
+  loading.value = true; loadError.value = null
+  try {
+    const result = await listRelabelOrders({ page: page.value, size: pageSize.value, relabelNo: String(filters.value.relabelNo || '').trim() || undefined, skuCode: String(filters.value.sku || '').trim() || undefined, status: String(filters.value.status || '').trim() || undefined })
+    rows.value = result.records.map((item) => ({
+      customerId: '', orderNo: String(item.relabelNo), relatedOrderNo: String(item.lastlegOrderNo || item.customerOrderNo || '—'), sku: String(item.skuCodes || '—'),
+      productName: '—', cartons: Number(item.totalPackageCount || 0), budgetTotal: null, relabelCost: Number(item.chargeAmount || 0), walletStatus: walletStatus(item.walletStatus), walletErrorMessage: item.walletErrorMessage || '', labelRequirement: '—', fileName: '—', status: relabelStatus(item.status), rawStatus: String(item.status || ''), remark: '',
+      createdAt: formatOverseasDateTime(item.createdAt),
+    }))
+    total.value = result.total
+  } catch (error) { rows.value = []; total.value = 0; loadError.value = getApiErrorDetails(error, '换标单加载失败，请重试') }
+  finally { loading.value = false }
+}
+function search(model: QueryModel) { page.value = 1; void load(model) }
+function reset(model: QueryModel) { page.value = 1; void load(model) }
+onMounted(load)
+watch(dialogOpen, (open) => { if (!open) createIdempotencyKey.value = '' })
+</script>
+
+<template>
+  <AdminPage class="admin-density"><ListPageLayout aria-label="换标单列表">
+    <template #toolbar><QueryToolbar v-model="filters" class="surface-panel" :fields="fields" :loading="loading" ariaLabel="换标单筛选" preference-key="overseas-relabel-orders-query" :search-on-reset="false" @search="search" @reset="reset" /></template>
+    <template v-if="loadError" #state><LoadErrorState title="换标单加载失败" :message="loadError.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="loadError" /></template></LoadErrorState></template>
+    <section v-if="!loadError" class="surface-panel table-panel"><DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :loading="loading" :total="total" preference-key="overseas-relabel-orders" row-key="orderNo" empty-text="暂无换标单" @update:page="load()" @update:page-size="page = 1; load()">
+      <template #toolbar-actions><el-button v-if="access.can(permission.relabelOrderCreate)" type="primary" @click="openForm('create')"><Plus :size="16" />新增换标单</el-button></template>
+      <template #actions="{ row }"><div class="density-actions"><el-button class="density-action" data-tone="neutral" size="small" @click="openDetail(row)">查看</el-button><el-button class="density-action" data-tone="warning" v-if="access.can(permission.relabelOrderStatus) && canAudit(row)" size="small" @click="openForm('edit', row)">审核</el-button></div></template>
+      <template #pagination-left>共 {{ total }} 条换标单</template>
+    </DataTable></section>
+  </ListPageLayout>
+  <AppDialog class="admin-density-dialog" v-model="dialogOpen" :title="dialogMode === 'create' ? '新增换标单' : '审核换标单'" width="min(760px, calc(100vw - 28px))" :confirm-text="dialogMode === 'create' ? '保存换标单' : '提交审核'" :confirm-loading="submitting" @confirm="submitForm">
+    <el-form class="density-form" label-position="top"><h3>订单信息</h3><el-row :gutter="16">
+      <el-col :span="12"><el-form-item label="换标单号"><el-input :model-value="dialogMode === 'create' ? '系统自动生成' : form.orderNo || '—'" readonly /></el-form-item></el-col>
+      <el-col :span="12"><el-form-item label="关联订单" required><el-input v-model="form.relatedOrderNo" :disabled="dialogMode === 'edit'" placeholder="请输入关联订单号" /></el-form-item></el-col>
+      <el-col v-if="dialogMode === 'create'" :span="12"><el-form-item label="客户" required><el-select v-model="form.customerId" filterable :loading="customersLoading" placeholder="请选择 ACTIVE 客户"><el-option v-for="item in customers" :key="String(item.id)" :label="item.tenantName" :value="String(item.id)" /></el-select></el-form-item></el-col>
+      <el-col v-if="dialogMode === 'create'" :span="12"><el-form-item label="公共海外收货仓" required><el-select v-model="form.warehouseId" filterable :loading="warehousesLoading" placeholder="请选择 ACTIVE+RECEIVING 海外仓"><el-option v-for="item in warehouses" :key="item.id" :label="`${item.warehouseName} · ${item.warehouseCode}`" :value="String(item.id)" /></el-select></el-form-item></el-col>
+      <el-col :span="12"><el-form-item label="商品SKU" required><el-input v-model="form.sku" :disabled="dialogMode === 'edit'" placeholder="请输入商品SKU" /></el-form-item></el-col>
+      <el-col :span="12"><el-form-item label="中文品名" required><el-input v-model="form.productName" :disabled="dialogMode === 'edit'" placeholder="请输入中文品名" /></el-form-item></el-col>
+      <el-col :span="12"><el-form-item label="箱数" required><el-input-number v-model="form.cartons" :disabled="dialogMode === 'edit'" :min="1" :precision="0" controls-position="right" placeholder="请输入箱数" /></el-form-item></el-col>
+      <el-col v-if="dialogMode === 'create'" :span="12"><el-form-item label="截止时间" required><el-date-picker v-model="form.labelDeadline" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" placeholder="请选择截止时间" /></el-form-item></el-col>
+      <el-col v-if="dialogMode === 'create'" :span="12"><el-form-item label="联系人" required><el-input v-model="form.contactName" placeholder="请输入联系人" /></el-form-item></el-col>
+      <el-col v-if="dialogMode === 'create'" :span="12"><el-form-item label="联系电话" required><el-input v-model="form.contactPhone" placeholder="请输入联系电话" /></el-form-item></el-col>
+      <el-col v-if="dialogMode === 'edit'" :span="12"><el-form-item label="目标状态"><el-select v-model="form.status" placeholder="请选择目标状态"><el-option v-for="value in allowedStatusOptions" :key="value" :label="relabelAuditStatusLabel(value)" :value="value" /></el-select></el-form-item></el-col>
+    </el-row><h3>作业要求</h3><el-row :gutter="16">
+      <el-col :span="12"><el-form-item label="贴标要求" required><el-select v-model="form.labelRequirement" :disabled="dialogMode === 'edit'" placeholder="请选择贴标要求"><el-option v-for="value in ['换箱唛', '换SKU标', '换箱唛和SKU标']" :key="value" :label="value" :value="value" /></el-select></el-form-item></el-col>
+      <el-col :span="12"><el-form-item label="货件号" required><el-input v-model="form.shipmentNo" :disabled="dialogMode === 'edit'" placeholder="请输入货件号" /></el-form-item></el-col>
+      <el-col :span="12"><el-form-item label="新SKU" required><el-input v-model="form.newSkuCode" :disabled="dialogMode === 'edit'" placeholder="请输入新SKU" /></el-form-item></el-col>
+      <el-col :span="12"><el-form-item label="换标费用（CNY）" required><el-input-number v-model="form.relabelCost" :disabled="dialogMode === 'edit'" :min="0.01" :precision="2" controls-position="right" placeholder="请输入换标费用" /></el-form-item></el-col>
+      <el-col :span="24"><el-form-item label="备注"><el-input v-model="form.remark" type="textarea" :rows="3" maxlength="500" show-word-limit placeholder="请输入备注（选填）" /></el-form-item></el-col>
+    </el-row></el-form>
+  </AppDialog>
+  </AdminPage>
+</template>
+
+<style scoped>
+h3 { margin: 0 0 var(--admin-space-5); color: var(--cc-text); font-size: var(--admin-font-section); }
+h3:not(:first-child) { margin-top: var(--admin-space-1); padding-top: var(--admin-space-5); border-top: 1px solid var(--cc-border); }
+.el-form :deep(.el-row) { margin-left: 0 !important; margin-right: 0 !important; }
+.el-form :deep(.el-input), .el-form :deep(.el-select), .el-form :deep(.el-input-number), .el-form :deep(.el-date-editor) { width: 100%; }
+</style>
diff --git a/src/modules/overseas-warehouse/pages/ReturnInventoryManagementView.vue b/src/modules/overseas-warehouse/pages/ReturnInventoryManagementView.vue
new file mode 100644
index 00000000..7b0ef710
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/ReturnInventoryManagementView.vue
@@ -0,0 +1,61 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, reactive, ref } from 'vue'
+import { Search } from '@lucide/vue'
+import { ElMessage } from 'element-plus'
+import { listPlatformTenants, listSharedReceivingOverseasWarehouseOptions, type PlatformTenantResource } from '@/modules/iam'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import { getReturnCarton, getReturnCartonLabel, listReturnCartons, listReturnInventoryMovements, listReturnStock, type ReturnCartonDetail, type ReturnCartonRow, type ReturnInventoryMovement, type ReturnStockRow } from '../api/returnInventory'
+const props = defineProps<{ mode: 'inventory' | 'cartons' }>()
+const loading = ref(false), total = ref(0), detailOpen = ref(false)
+const stockRows = ref<ReturnStockRow[]>([]), cartonRows = ref<ReturnCartonRow[]>([]), detail = ref<ReturnCartonDetail>()
+const inventoryTab = ref<'stock' | 'movements'>('stock')
+const movementRows = ref<ReturnInventoryMovement[]>([])
+const customers = ref<PlatformTenantResource[]>([])
+const warehouses = ref<Array<{ id: string; warehouseName: string }>>([])
+const optionsLoading = ref(false)
+const query = reactive({ page: 1, size: 20, customerId: '', overseasWarehouseId: '', skuCode: '', cartonMark: '', returnNo: '', status: 'AVAILABLE' })
+function params() { return { ...query, customerId: query.customerId || undefined, overseasWarehouseId: query.overseasWarehouseId || undefined, skuCode: query.skuCode || undefined, cartonMark: query.cartonMark || undefined, returnNo: query.returnNo || undefined, status: query.status || undefined } }
+async function load() { loading.value = true; try { if (props.mode === 'inventory') { if (inventoryTab.value === 'stock') { const page = await listReturnStock(params()); stockRows.value = page.records; total.value = page.total } else { const page = await listReturnInventoryMovements(params()); movementRows.value = page.records; total.value = page.total } } else { const page = await listReturnCartons(params()); cartonRows.value = page.records; total.value = page.total } } finally { loading.value = false } }
+function search() { query.page = 1; void load() }
+function changeInventoryTab() { query.page = 1; void load() }
+const customerOptions = computed(() => customers.value.filter((item) => item.status === 'ACTIVE').map((item) => ({ label: item.tenantName, value: String(item.id) })))
+const warehouseOptions = computed(() => warehouses.value.map((item) => ({ label: item.warehouseName, value: String(item.id) })))
+function customerName(customerId?: string) { return customers.value.find((item) => String(item.id) === String(customerId))?.tenantName || '客户名称待补充' }
+function warehouseName(warehouseId?: string) { return warehouses.value.find((item) => String(item.id) === String(warehouseId))?.warehouseName || '海外仓名称待补充' }
+function statusLabel(status?: string) { return status === 'AVAILABLE' ? '可用' : status === 'MERGED' ? '已合箱' : '—' }
+async function loadOptions() {
+  optionsLoading.value = true
+  try {
+    const [customerResult, warehouseResult] = await Promise.allSettled([
+      listPlatformTenants({ page: 1, size: 200, status: 'ACTIVE' }),
+      listSharedReceivingOverseasWarehouseOptions(),
+    ])
+    if (customerResult.status === 'fulfilled') customers.value = customerResult.value.records
+    else customers.value = []
+    if (warehouseResult.status === 'fulfilled') warehouses.value = warehouseResult.value
+    else warehouses.value = []
+    if (customerResult.status === 'rejected' || warehouseResult.status === 'rejected') {
+      const failed = customerResult.status === 'rejected' ? '客户' : '海外仓'
+      ElMessage.warning(`${failed}筛选数据加载失败，请检查服务或数据库迁移`)
+    }
+  } catch (error) {
+    ElMessage.warning(error instanceof Error ? `筛选名称加载失败：${error.message}` : '筛选名称加载失败')
+  } finally { optionsLoading.value = false }
+}
+async function openCarton(mark: string) { try { detail.value = await getReturnCarton(mark); detailOpen.value = true } catch (e) { ElMessage.error(e instanceof Error ? e.message : '箱号详情加载失败') } }
+async function printLabel(mark: string) { try { const label = await getReturnCartonLabel(mark); const popup = window.open('', '_blank'); if (!popup) return ElMessage.warning('请允许浏览器打开打印窗口'); popup.opener = null; popup.document.open(); popup.document.write(label.printableHtml); popup.document.close(); popup.focus(); popup.print() } catch (e) { ElMessage.error(e instanceof Error ? e.message : '箱唛加载失败') } }
+onMounted(() => { void load(); void loadOptions() })
+</script>
+
+<template><AdminPage as="div" class="business-page return-inventory-page admin-density">
+  <el-tabs class="density-element-tabs" v-if="mode==='inventory'" v-model="inventoryTab" @tab-change="changeInventoryTab"><el-tab-pane name="stock" ><template #label><span class="density-tab-icon" aria-hidden="true">🏷️</span><span>退货库存</span></template></el-tab-pane><el-tab-pane name="movements" ><template #label><span class="density-tab-icon" aria-hidden="true">📝</span><span>退货进销存明细</span></template></el-tab-pane></el-tabs>
+  <section class="surface-panel query-panel"><el-select v-model="query.customerId" clearable filterable placeholder="全部客户" :loading="optionsLoading"><el-option v-for="item in customerOptions" :key="item.value" :label="item.label" :value="item.value" /></el-select><el-select v-model="query.overseasWarehouseId" clearable filterable placeholder="全部海外仓" :loading="optionsLoading"><el-option v-for="item in warehouseOptions" :key="item.value" :label="item.label" :value="item.value" /></el-select><el-input v-model="query.skuCode" clearable placeholder="SKU" @keyup.enter="search" /><el-input v-if="mode==='cartons'" v-model="query.cartonMark" clearable placeholder="箱号/箱唛" @keyup.enter="search" /><el-input v-if="mode==='cartons'" v-model="query.returnNo" clearable placeholder="退货单号" @keyup.enter="search" /><el-select v-if="mode==='cartons'" v-model="query.status" clearable placeholder="箱状态"><el-option label="可用" value="AVAILABLE" /><el-option label="已合箱" value="MERGED" /></el-select><el-button type="primary" @click="search"><Search :size="16" />查询</el-button></section>
+  <section class="surface-panel table-panel"><el-table v-if="mode==='inventory' && inventoryTab==='stock'" v-loading="loading" :data="stockRows"><el-table-column label="客户" min-width="180"><template #default="{row}">{{ customerName(row.customerId) }}</template></el-table-column><el-table-column label="海外仓" min-width="180"><template #default="{row}">{{ warehouseName(row.overseasWarehouseId) }}</template></el-table-column><el-table-column prop="skuCode" label="SKU" min-width="170" /><el-table-column prop="productNameZh" label="中文品名" min-width="180" /><el-table-column prop="totalQuantity" label="总库存" align="right" /><el-table-column prop="availableQuantity" label="可用库存" align="right" /><el-table-column prop="updatedAt" label="更新时间" min-width="180" /></el-table>
+  <el-table v-else-if="mode==='inventory'" v-loading="loading" :data="movementRows"><el-table-column label="客户" min-width="180"><template #default="{row}">{{ customerName(row.customerId) }}</template></el-table-column><el-table-column label="海外仓" min-width="180"><template #default="{row}">{{ warehouseName(row.overseasWarehouseId) }}</template></el-table-column><el-table-column prop="skuCode" label="SKU" min-width="170" /><el-table-column prop="productNameZh" label="中文品名" min-width="180" /><el-table-column label="业务类型" min-width="120"><template #default="{row}">{{ row.movementType === 'RECEIPT' ? '退货签收' : row.movementType === 'MERGE' ? '退货合箱' : '退货出库' }}</template></el-table-column><el-table-column prop="referenceNo" label="关联单号/箱号" min-width="220" /><el-table-column prop="totalDelta" label="总库存变动" align="right" /><el-table-column prop="availableDelta" label="可用库存变动" align="right" /><el-table-column prop="occurredAt" label="发生时间" min-width="180" /></el-table>
+  <el-table v-else v-loading="loading" :data="cartonRows"><el-table-column label="操作" width="140" fixed="left"><template #default="{row}"><div class="density-actions"><el-button class="density-action" data-tone="neutral" @click="openCarton(row.cartonMark)">详情</el-button><el-button class="density-action" data-tone="neutral" @click="printLabel(row.cartonMark)">箱唛</el-button></div></template></el-table-column><el-table-column prop="cartonMark" label="箱号" min-width="220" /><el-table-column label="客户" min-width="180"><template #default="{row}">{{ customerName(row.customerId) }}</template></el-table-column><el-table-column label="海外仓" min-width="180"><template #default="{row}">{{ warehouseName(row.overseasWarehouseId) }}</template></el-table-column><el-table-column prop="sourceReturnNo" label="来源退货单" min-width="220" /><el-table-column prop="fbaCartonMark" label="FBA箱唛" min-width="180" /><el-table-column label="目的仓" min-width="180"><template #default="{row}">{{ row.destinationWarehouseCode || row.destinationWarehouseName || '—' }}</template></el-table-column><el-table-column prop="relabelNo" label="换标单号" min-width="200" /><el-table-column label="换标状态" width="110"><template #default="{row}">{{ row.relabelStatus === 'COMPLETED' ? '已完成' : row.relabelStatus === 'BOUND' ? '已绑定' : row.relabelStatus || '未绑定' }}</template></el-table-column><el-table-column label="状态" width="100"><template #default="{row}">{{ statusLabel(row.status) }}</template></el-table-column><el-table-column prop="skuTypes" label="SKU种类" align="right" /><el-table-column prop="totalQuantity" label="总件数" align="right" /><el-table-column label="箱规" min-width="190"><template #default="{row}">{{ row.length ? `${row.length}×${row.width}×${row.height} cm` : '—' }}</template></el-table-column><el-table-column prop="weight" label="重量(kg)" align="right" /><el-table-column prop="createdAt" label="创建时间" min-width="180" /></el-table>
+  <el-pagination v-model:current-page="query.page" v-model:page-size="query.size" :total="total" layout="total, sizes, prev, pager, next" :page-sizes="[20,50,100]" @current-change="load" @size-change="query.page=1;load()" /></section>
+  <AppDialog class="admin-density-dialog" v-model="detailOpen" title="退货箱号详情" width="min(1080px, calc(100vw - 56px))" :show-footer="false"><template v-if="detail"><el-descriptions class="density-descriptions" :column="2" border><el-descriptions-item label="箱号">{{detail.cartonMark}}</el-descriptions-item><el-descriptions-item label="客户">{{customerName(detail.customerId)}}</el-descriptions-item><el-descriptions-item label="海外仓">{{warehouseName(detail.overseasWarehouseId)}}</el-descriptions-item><el-descriptions-item label="来源退货单">{{detail.sourceReturnNo||'—'}}</el-descriptions-item><el-descriptions-item label="FBA箱唛">{{detail.fbaCartonMark||'—'}}</el-descriptions-item><el-descriptions-item label="目的仓">{{detail.destinationWarehouseCode||detail.destinationWarehouseName||'—'}}</el-descriptions-item><el-descriptions-item label="换标单号">{{detail.relabelNo||'—'}}</el-descriptions-item><el-descriptions-item label="换标状态">{{detail.relabelStatus === 'COMPLETED' ? '已完成' : detail.relabelStatus === 'BOUND' ? '已绑定' : detail.relabelStatus || '未绑定'}}</el-descriptions-item><el-descriptions-item label="状态">{{statusLabel(detail.status)}}</el-descriptions-item><el-descriptions-item label="箱规">{{detail.length?`${detail.length}×${detail.width}×${detail.height} cm`:'—'}}</el-descriptions-item><el-descriptions-item label="重量">{{detail.weight?`${detail.weight} kg`:'—'}}</el-descriptions-item></el-descriptions><el-table :data="detail.items" class="detail-items"><el-table-column prop="skuCode" label="SKU" /><el-table-column prop="productNameZh" label="中文品名" /><el-table-column prop="quantity" label="数量" align="right" /></el-table></template></AppDialog>
+</AdminPage></template>
+<style scoped>.return-inventory-page{display:grid;gap:var(--admin-space-5)}.query-panel{display:flex;gap:var(--admin-space-4);flex-wrap:wrap;padding:var(--admin-space-5)}.query-panel .el-input,.query-panel .el-select{width:180px}.table-panel{padding:var(--admin-space-5)}.el-pagination{justify-content:flex-end;margin-top:var(--admin-space-5)}.detail-items{margin-top:var(--admin-space-5)}</style>
diff --git a/src/modules/overseas-warehouse/pages/containerPlanPreviewContract.test.ts b/src/modules/overseas-warehouse/pages/containerPlanPreviewContract.test.ts
new file mode 100644
index 00000000..ddbd5c6c
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/containerPlanPreviewContract.test.ts
@@ -0,0 +1,49 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const apiSource = readFileSync(resolve(process.cwd(), 'src/modules/overseas-warehouse/api/lastMileOrders.ts'), 'utf8')
+const pageSource = readFileSync(resolve(process.cwd(), 'src/modules/overseas-warehouse/pages/LastMileOrdersView.vue'), 'utf8')
+
+describe('container inbound plan preview contract', () => {
+  it('uses the backend preview endpoint with the stable container booking id', () => {
+    expect(apiSource).toContain("'/platform/v1/last-leg/inbound-plans/container-preview'")
+    expect(apiSource).toContain('{ params: { sourceContainerBookingId } }')
+  })
+
+  it('renders backend groups, pallet totals, readiness and blockers without local grouping or sorting', () => {
+    expect(pageSource).toContain('containerPreview.pendingPalletCount')
+    expect(pageSource).toContain('containerPreview.sourcePalletCount')
+    expect(pageSource).toContain('containerPreview.supplementPalletCount')
+    expect(pageSource).toContain('v-for="group in containerPreview.groups"')
+    expect(pageSource).toContain('readinessText(row.readiness)')
+    expect(pageSource).toContain("RESOURCE_PENDING' ? '将自动补齐'")
+    expect(pageSource).toContain('blockerText(row.blockers)')
+    expect(pageSource).not.toContain('containerPreview.groups.sort(')
+  })
+
+  it('requests one preview per selection and submits one atomic snapshot command', () => {
+    expect(pageSource.match(/await getContainerInboundPlanPreview\(sourceContainerBookingId\)/g)).toHaveLength(1)
+    expect(pageSource).toContain('containerPreviewLoadingBookingId === sourceContainerBookingId')
+    expect(pageSource).toContain('request !== containerPreviewRequest || selectedContainerBookingId.value !== sourceContainerBookingId || !containerConvertOpen.value')
+    expect(pageSource).toContain('containerPreviewRequest += 1')
+    expect(pageSource.match(/await convertLastMileContainerToInboundPlans\(\{/g)).toHaveLength(1)
+    expect(pageSource).toContain('snapshotVersion: preview.snapshotVersion')
+    expect(pageSource).toContain('snapshotHash: preview.snapshotHash')
+    expect(pageSource).toContain('containerConversionIdempotencyKey')
+    expect(pageSource).toContain(':confirm-disabled="containerConfirmDisabled"')
+  })
+
+  it('shows returned plan numbers and real pallet numbers then refreshes the page and preview', () => {
+    expect(pageSource).toContain('containerConversionResult.plans')
+    expect(pageSource).toContain('plan.pallets')
+    expect(pageSource).toContain('pallet.palletNo')
+    expect(pageSource).toContain('Promise.all([load(), loadContainerPreview(bookingId, true)])')
+  })
+
+  it('translates known blockers and never exposes unknown internal blocker codes', () => {
+    expect(pageSource).toContain("PALLET_COUNT_NOT_READY: '计划托数暂未就绪'")
+    expect(pageSource).toContain("labels[code] || '计划数据暂未就绪，请刷新或联系管理员'")
+    expect(pageSource).not.toContain('labels[code] || code')
+  })
+})
diff --git a/src/modules/overseas-warehouse/pages/phase5Behavior.test.ts b/src/modules/overseas-warehouse/pages/phase5Behavior.test.ts
new file mode 100644
index 00000000..802af7d6
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/phase5Behavior.test.ts
@@ -0,0 +1,54 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+function source(name: string) { return readFileSync(resolve(process.cwd(), `src/modules/overseas-warehouse/pages/${name}`), 'utf8') }
+
+function expectOperationColumnFirst(name: string) {
+  const value = source(name)
+  if (!value.includes("key: 'actions', label: '操作'")) return
+  expect(value).toMatch(/const columns:[\s\S]*?= \[\s*\{ key: 'actions', label: '操作'/)
+}
+
+describe('phase-five outbound, delivery, exception and visit behavior', () => {
+  it('keeps outbound detail and cancellation scoped only by outboundNo', () => {
+    const list = source('OutboundsView.vue')
+    const detail = source('OutboundDetailView.vue')
+    expect(list).toContain("params: { outboundNo: row.outboundNo }")
+    expect(list).toContain('access.can(permission.outboundCreate)')
+    expect(list).toContain('access.can(permission.outboundCancel)')
+    expect(detail).toContain('getOutbound(outboundNo.value)')
+    expect(detail).toContain('cancelOutbound(outboundNo.value, reason)')
+    expect(detail).not.toContain('customerId')
+    expect(list).toContain("createOneClickDropshipOutbound([...customerIds][0] || ''")
+    expectOperationColumnFirst('OutboundsView.vue')
+  })
+
+  it('keeps delivery return and status operations on real APIs with independent permissions', () => {
+    const value = source('DeliveryOrdersView.vue')
+    expect(value).toContain('permission.deliveryStatus')
+    expect(value).toContain('permission.deliveryReturn')
+    expect(value).toContain('updateDeliveryOrderStatus')
+    expect(value).toContain('markDeliveryReturn')
+    expect(value).toContain('listDeliveryReturnInboundOptions')
+    expectOperationColumnFirst('DeliveryOrdersView.vue')
+  })
+
+  it('keeps exception creation and relation resolution on real APIs', () => {
+    const value = source('ExceptionOrdersView.vue')
+    expect(value).toContain('permission.exceptionOrderCreate')
+    expect(value).toContain('resolveExceptionRelation')
+    expect(value).toContain('createExceptionOrder')
+    expect(value).toContain('getApiErrorDetails')
+    expectOperationColumnFirst('ExceptionOrdersView.vue')
+  })
+
+  it('keeps customer visit updates and attachments behind edit permission', () => {
+    const value = source('CustomerVisitsView.vue')
+    expect(value).toContain('permission.customerVisitEdit')
+    expect(value).toContain('saveCustomerVisit')
+    expect(value).toContain('uploadCustomerVisitAttachment')
+    expect(value).toContain('getApiErrorDetails')
+    expectOperationColumnFirst('CustomerVisitsView.vue')
+  })
+})
diff --git a/src/modules/overseas-warehouse/pages/phase5TestStubs.ts b/src/modules/overseas-warehouse/pages/phase5TestStubs.ts
new file mode 100644
index 00000000..26e9ca6b
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/phase5TestStubs.ts
@@ -0,0 +1,83 @@
+import { defineComponent, h, type Component, type PropType } from 'vue'
+
+export const DataTableStub = defineComponent({
+  name: 'DataTable',
+  props: { data: { type: Array as PropType<object[]>, default: () => [] } },
+  setup(props, { slots }) {
+    return () => h('div', { 'data-testid': 'data-table' }, [
+      slots['toolbar-actions']?.(),
+      ...props.data.flatMap(row => slots.actions?.({ row }) || []),
+    ])
+  },
+})
+
+export const AppDialogStub = defineComponent({
+  name: 'AppDialog',
+  props: { title: { type: String, required: true }, confirmText: { type: String, default: '确定' } },
+  emits: ['confirm'],
+  setup(props, { emit, slots }) {
+    return () => h('section', { 'data-dialog': props.title }, [
+      slots.default?.(),
+      h('button', { class: 'dialog-confirm', onClick: () => emit('confirm') }, props.confirmText),
+    ])
+  },
+})
+
+export const ModelInputStub = defineComponent({
+  name: 'ElInput',
+  inheritAttrs: false,
+  props: { modelValue: { type: [String, Number], default: '' }, type: { type: String, default: 'text' } },
+  emits: ['update:modelValue', 'blur'],
+  setup(props, { attrs, emit }) {
+    return () => h(props.type === 'textarea' ? 'textarea' : 'input', {
+      ...attrs,
+      value: props.modelValue,
+      onInput: (event: Event) => emit('update:modelValue', (event.target as HTMLInputElement).value),
+      onBlur: () => emit('blur'),
+    })
+  },
+})
+
+export const ModelSelectStub = defineComponent({
+  name: 'ElSelect',
+  props: { modelValue: { type: [String, Number], default: '' } },
+  emits: ['update:modelValue'],
+  setup(props, { emit, slots }) {
+    return () => h('select', {
+      value: props.modelValue,
+      onChange: (event: Event) => emit('update:modelValue', (event.target as HTMLSelectElement).value),
+    }, slots.default?.())
+  },
+})
+
+export const OptionStub = defineComponent({
+  name: 'ElOption',
+  props: { value: { type: [String, Number], required: true }, label: { type: String, required: true } },
+  setup(props) { return () => h('option', { value: props.value }, props.label) },
+})
+
+export const ModelNumberStub = defineComponent({
+  name: 'ElInputNumber',
+  props: { modelValue: { type: Number, default: undefined } },
+  emits: ['update:modelValue'],
+  setup(props, { emit }) {
+    return () => h('input', {
+      type: 'number',
+      value: props.modelValue,
+      onInput: (event: Event) => {
+        const value = (event.target as HTMLInputElement).value
+        emit('update:modelValue', value === '' ? undefined : Number(value))
+      },
+    })
+  },
+})
+
+export const commonPhase5Stubs: Record<string, Component> = {
+  DataTable: DataTableStub,
+  AppDialog: AppDialogStub,
+  QueryToolbar: defineComponent({ name: 'QueryToolbar', setup: () => () => h('div') }),
+  ElInput: ModelInputStub,
+  ElSelect: ModelSelectStub,
+  ElOption: OptionStub,
+  ElInputNumber: ModelNumberStub,
+}
diff --git a/src/modules/overseas-warehouse/pages/prototypeContract.test.ts b/src/modules/overseas-warehouse/pages/prototypeContract.test.ts
new file mode 100644
index 00000000..18da2ff2
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/prototypeContract.test.ts
@@ -0,0 +1,410 @@
+import { readFileSync, readdirSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+function source(fileName: string) {
+  return readFileSync(resolve(process.cwd(), 'src/modules/overseas-warehouse/pages', fileName), 'utf8')
+}
+
+function columnKeys(fileName: string) {
+  const value = source(fileName)
+  const start = value.indexOf('const columns: DataTableColumn[]')
+  const end = value.indexOf('\n]', start)
+  return [...value.slice(start, end).matchAll(/\{ key: '([^']+)'/g)].map((match) => match[1])
+}
+
+describe('overseas warehouse first-batch prototype contract', () => {
+  it('shows warehouse transfer review only for pending transfers with its dedicated authority', () => {
+    const value = source('LastMileOrdersView.vue')
+    expect(value).toContain('access.can(permission.warehouseTransferApprove)')
+    expect(value).toContain("row.orderTypeCode === 'WAREHOUSE_TRANSFER'")
+    expect(value).toContain("row.currentStatusCode === 'PENDING_REVIEW'")
+    expect(value).toContain('<WarehouseTransferReviewDialog')
+  })
+
+  it('gives every formal list query toolbar a unique stable preference key', () => {
+    const expected = new Map([
+      ['LastMileOrdersView.vue', 'overseas-last-mile-orders-query'],
+      ['InboundOrdersView.vue', 'overseas-inbound-orders-query'],
+      ['DispatchesView.vue', 'overseas-dispatches-query'],
+      ['DeliveryOrdersView.vue', 'overseas-delivery-orders-query'],
+      ['CustomerVisitsView.vue', 'overseas-customer-visits-query'],
+      ['ExceptionOrdersView.vue', 'overseas-exception-orders-query'],
+      ['OutboundsView.vue', 'overseas-outbounds-query'],
+      ['InventoryView.vue', 'overseas-inventory-query'],
+      ['InventoryTransactionsView.vue', 'overseas-inventory-transactions-query'],
+      ['RelabelOrdersView.vue', 'overseas-relabel-orders-query'],
+      ['PalletsView.vue', 'overseas-pallets-query'],
+      ['CartonsView.vue', 'overseas-cartons-query'],
+      ['ProductsView.vue', 'overseas-products-query'],
+    ])
+    const keys = [...expected.entries()].map(([fileName, preferenceKey]) => {
+      const value = source(fileName)
+      const toolbar = value.match(/<QueryToolbar\b[^>]*\/>/)?.[0]
+      expect(toolbar, `${fileName} should render a QueryToolbar`).toBeDefined()
+      expect(toolbar).toContain(`preference-key="${preferenceKey}"`)
+      return preferenceKey
+    })
+    const queryToolbarPages = readdirSync(resolve(process.cwd(), 'src/modules/overseas-warehouse/pages'))
+      .filter((fileName) => fileName.endsWith('.vue') && source(fileName).includes('<QueryToolbar'))
+
+    expect(queryToolbarPages.sort()).toEqual([...expected.keys()].sort())
+    expect(new Set(keys).size).toBe(expected.size)
+  })
+
+  it('keeps the operation column first on every business list', () => {
+    for (const fileName of ['LastMileOrdersView.vue', 'InboundOrdersView.vue', 'DispatchesView.vue', 'InventoryView.vue', 'RelabelOrdersView.vue', 'PalletsView.vue', 'CartonsView.vue', 'ProductsView.vue']) {
+      const value = source(fileName)
+      const columns = value.slice(value.indexOf('const columns: DataTableColumn[]'))
+      expect(columns.match(/\{\s*key: '([^']+)'/)?.[1]).toBe('actions')
+    }
+  })
+
+  it('preserves the prototype dialog carriers and desktop widths', () => {
+    const expected = [
+      ['CartonsView.vue', '860px', '新增箱号', '编辑箱号'],
+      ['ProductsView.vue', '560px', '新增产品', '编辑产品'],
+    ]
+    for (const [fileName, width, createTitle, editTitle] of expected) {
+      const value = source(fileName)
+      expect(value).toContain('<ContractPendingFormDialog')
+      expect(value).toContain(width)
+      expect(value).toContain(createTitle)
+      expect(value).toContain(editTitle)
+      expect(value).not.toContain('AppDrawer')
+    }
+    const relabel = source('RelabelOrdersView.vue')
+    expect(relabel).toContain('<AppDialog')
+    expect(relabel).toContain('760px')
+    expect(relabel).toContain('新增换标单')
+    expect(relabel).toContain('审核换标单')
+    expect(relabel).not.toContain('AppDrawer')
+    const pallets = source('PalletsView.vue')
+    expect(pallets).toContain('<AppDialog')
+    expect(pallets).toContain('760px')
+    expect(pallets).toContain('新增托盘')
+    expect(pallets).toContain('编辑托盘')
+    expect(pallets).not.toContain('AppDrawer')
+  })
+
+  it('implements all second-batch details as formal parameterized pages', () => {
+    for (const fileName of ['RelabelOrderDetailView.vue', 'PalletDetailView.vue', 'CartonDetailView.vue', 'ProductDetailView.vue']) {
+      const value = source(fileName)
+      expect(value).toContain('<OverseasReadOnlyDetail')
+      expect(value).toContain('@back="back"')
+      expect(value).not.toContain('AppDrawer')
+      if (fileName !== 'RelabelOrderDetailView.vue') expect(value).not.toContain('AppDialog')
+    }
+    const relabel = source('RelabelOrderDetailView.vue')
+    expect(relabel).toContain('<AppDialog class="admin-density-dialog" v-if="previewUrl"')
+    expect(relabel).toContain('<iframe :src="previewUrl"')
+  })
+
+  it('keeps second-batch forms non-submitting until overseas write contracts exist', () => {
+    const dialog = readFileSync(resolve(process.cwd(), 'src/modules/overseas-warehouse/components/ContractPendingFormDialog.vue'), 'utf8')
+    expect(dialog).toContain('confirm-disabled')
+    expect(dialog).toContain('不可提交')
+    expect(dialog).not.toContain('@confirm=')
+    for (const fileName of ['CartonsView.vue', 'ProductsView.vue']) {
+      const value = source(fileName)
+      expect(value).not.toContain('ElMessage.success')
+      expect(value).not.toMatch(/https?:\/\//)
+    }
+    const relabel = source('RelabelOrdersView.vue')
+    expect(relabel).toContain('createRelabelOrder')
+    expect(relabel).toContain('changeRelabelOrderStatus')
+    expect(relabel).toContain('ElMessage.success')
+    const pallets = source('PalletsView.vue')
+    expect(pallets).toContain('createPallet')
+    expect(pallets).toContain('updatePallet')
+    expect(pallets).toContain('ElMessage.success')
+  })
+
+  it('implements prototype-defined details as formal pages', () => {
+    for (const fileName of ['LastMileOrderDetailView.vue', 'InboundOrderDetailView.vue', 'DispatchDetailView.vue', 'InventoryDetailView.vue']) {
+      const value = source(fileName)
+      expect(value).toContain('<OverseasDetailShell')
+      expect(value).toContain('@back="back"')
+      expect(value).not.toContain('AppDrawer')
+      if (fileName === 'LastMileOrderDetailView.vue') expect(value).toContain('title="新增费用"')
+      else expect(value).not.toContain('AppDialog')
+    }
+  })
+
+  it('does not expose outbound planning or delivery actions from the last-mile detail', () => {
+    const value = source('LastMileOrderDetailView.vue')
+    expect(value).not.toContain('计划出库日期')
+    expect(value).not.toContain('派送方式')
+    expect(value).not.toContain('保存并生成出库单')
+    expect(value).not.toContain('海外派送')
+  })
+
+  it('renders and copies the server-provided tail-leg short number in list and detail', () => {
+    const list = source('LastMileOrdersView.vue')
+    const detail = source('LastMileOrderDetailView.vue')
+    expect(list).toContain('<OrderReferenceText :value="String(row.orderNo || \'\')" copyable />')
+    expect(detail).toContain('lastMileOrderReference(detail.value?.order.orderNo')
+    expect(detail).toContain('<OrderReferenceText :value="referenceValue" copyable compact />')
+    expect(list).not.toMatch(/padStart|LMO-\$\{|slice\([^)]*orderNo/)
+    expect(detail).not.toMatch(/padStart|LMO-\$\{|slice\([^)]*orderNo/)
+  })
+
+  it('connects the tail-leg detail to the real overseas API and keeps missing contracts pending', () => {
+    const tailLeg = source('LastMileOrderDetailView.vue')
+    expect(tailLeg).toContain('getLastMileOrder')
+    expect(tailLeg).toContain(':data="cargo"')
+    expect(tailLeg).toContain('<LoadErrorState')
+    expect(tailLeg).toContain('createLastMileOrderFee')
+    expect(tailLeg).toContain('<span>费用明细</span>')
+    expect(tailLeg).toContain('<span>操作记录</span>')
+    expect(tailLeg).toContain('title="新增费用"')
+    expect(tailLeg).toContain('lastMileOrderReference(detail.value?.order.orderNo')
+    expect(tailLeg).toContain('<OrderReferenceText :value="referenceValue" copyable compact />')
+    const inbound = source('InboundOrderDetailView.vue')
+    expect(inbound).toContain('getInboundPlan')
+    expect(inbound).not.toContain('detail.value?.sourceOrderId')
+    expect(inbound).toContain('<LoadErrorState')
+    const inventory = source('InventoryDetailView.vue')
+    expect(inventory).toContain('listInventoryPositions')
+    expect(inventory).toContain(':data="locationRows"')
+    expect(inventory).toContain('balance.value?.skuCode')
+    expect(inventory).toContain('inventoryProductName(balance.value)')
+    expect(inventory).not.toContain('当前流水接口未返回 SKU')
+    expect(inventory).not.toContain('ElMessage.success')
+    const inventoryList = source('InventoryView.vue')
+    expect(inventoryList).toContain('access.can(overseasWarehousePermissions.warehouseList)')
+    expect(inventoryList).toContain('if (!access.can(overseasWarehousePermissions.warehouseList)) return')
+    expect(inventoryList).not.toContain('请先选择客户后查询')
+  })
+
+  it('connects only the prototype-defined pallet create and edit actions', () => {
+    const value = source('PalletsView.vue')
+    expect(value).toContain('<AppDialog')
+    expect(value).toContain('760px')
+    expect(value).toContain("dialogMode === 'create' ? '新增托盘' : '编辑托盘'")
+    expect(value).toContain('createPallet')
+    expect(value).toContain('listAllPlatformWarehouses({ warehouseType: \'FBA\', status: \'ACTIVE\' })')
+    expect(value).toContain('placeholder="请选择海外仓"')
+    expect(value).toContain('!form.warehouseId')
+    expect(value).toContain('updatePallet')
+    expect(value).not.toContain('deletePallet')
+    expect(value).toContain('v-if="access.can(permission.palletCreate)"')
+    expect(value).toContain('version: detail.version')
+    expect(value).toContain('{ ...payload, version: form.version }')
+    expect(value).toContain('v-model="form.fbaWarehouseCode"')
+    expect(value).toContain("warehouseType: 'FBA'")
+    expect(value).toContain('listAllPlatformWarehouses')
+    expect(value).toContain('function retryLoad()')
+    expect(value).toContain('if (loading.value || contextLoading.value) return')
+    expect(value).toContain('palletCode: form.code.trim()')
+    expect(value).not.toContain(':readonly="dialogMode === \'edit\'"')
+    expect(value).not.toContain('ContractPendingFormDialog')
+  })
+
+  it('connects inbound order pagination and FBA appointment selection to the real overseas API', () => {
+    const value = source('InboundOrdersView.vue')
+    expect(value).toContain('listInboundOrders')
+    expect(value).toContain("key: 'selection', type: 'selection'")
+    expect(value).toContain('@selection-change="onSelectionChange"')
+    expect(value).toContain('createFbaAppointment')
+    expect(value).toContain('预计装车时间')
+    expect(value).toContain('所选入库单必须属于同一 FBA 仓库')
+    expect(value).toContain('anchor.customerId === row.customerId')
+    expect(value).toContain('<CalendarCheck2 :size="16" />预约')
+    expect(value).toContain('<Truck :size="16" />智能排车')
+    expect(value).toContain('type="primary" @click="openSmartDispatch"')
+    expect(value).not.toContain('type="primary" :disabled="!selectedRows.length" @click="openSmartDispatch"')
+    expect(value).toContain('access.can(permission.inboundOrderAppointment)')
+    expect(value).toContain('access.can(permission.inboundOrderSmartDispatch)')
+    expect(value).toContain('<SmartDispatchDialog')
+    expect(value).toContain("key: 'assigned', prop: 'assigned', label: '分配'")
+    expect(value).toContain("key: 'mergeAllowed', prop: 'mergeAllowed', label: '合托'")
+    expect(value).toContain("key: 'urgent', prop: 'urgent', label: '加急'")
+    expect(value).toContain("dto.mergeAllowed ? '可合托' : '不合托'")
+    expect(value).not.toContain('ContractPendingNotice')
+  })
+
+  it('keeps the six overseas warehouse lists connected to server-side pagination', () => {
+    for (const fileName of [
+      'LastMileOrdersView.vue',
+      'InboundOrdersView.vue',
+      'DispatchesView.vue',
+      'RelabelOrdersView.vue',
+      'PalletsView.vue',
+      'InventoryView.vue',
+    ]) {
+      const value = source(fileName)
+      expect(value).toContain('const page = ref(1)')
+      expect(value).toContain('const pageSize = ref(10)')
+      expect(value).toContain('const total = ref(0)')
+      expect(value).toContain('page: page.value')
+      expect(value).toContain('size: pageSize.value')
+      expect(value).toMatch(/total\.value = \w+\.total/)
+      expect(value).toContain('v-model:page="page"')
+      expect(value).toContain('v-model:page-size="pageSize"')
+      expect(value).toContain(':total="total"')
+      expect(value).toContain('@update:page="load()"')
+      expect(value).toContain('@update:page-size="page = 1; load()"')
+    }
+  })
+
+  it('connects intelligent dispatch without a frontend customerId constraint', () => {
+    const dialog = source('../components/SmartDispatchDialog.vue')
+    expect(dialog).toContain('listDispatchCandidates')
+    expect(dialog).toContain('preArrangeDispatch')
+    expect(dialog).toContain('planPalletIds: assignedIds.value')
+    expect(dialog).toContain('lockDispatchDraftPallet')
+    expect(dialog).toContain('unlockDispatchDraftPallet')
+    expect(dialog).not.toContain('releaseDispatchDraft')
+    expect(dialog).toContain('排车明细已同步到预排列表')
+    expect(dialog).toContain("router.push({ name: 'overseas-dispatches' })")
+    expect(dialog).not.toContain('customerId:')
+    expect(dialog).toContain("planIds: planIds.value.length ? planIds.value.join(',') : undefined")
+    expect(dialog).toContain('v-model="query.fbaWarehouseCode" clearable')
+    expect(dialog).not.toContain(':model-value="fbaWarehouseCode" readonly')
+    expect(dialog).toContain("sourceStage: 'RECEIVED'")
+    expect(dialog).toContain('一次排车只能装同一客户的托盘')
+    expect(dialog).toContain('该托盘尚未关联海外仓，不能排车')
+    expect(dialog).toContain('所选托盘中存在尚未关联海外仓的托盘')
+    expect(dialog).toContain('function ensureDraftToken()')
+    expect(dialog).toContain('lockDispatchDraftPallet(id, ensureDraftToken(), target.id)')
+    expect(dialog).toContain('function hydrateDraftPallets()')
+    expect(dialog).toContain('@click="removePallet(id)"')
+    expect(dialog).not.toContain('removePallet(candidates.find')
+    expect(dialog).toContain('洛杉矶')
+    expect(dialog).toContain('纽约')
+    expect(dialog).toContain("value: 'ALL', label: '全部'")
+    expect(dialog).toContain('换标下单')
+    expect(dialog).toContain('退货换标')
+    expect(dialog).toContain('本土散板')
+    expect(dialog).toContain('仓储转运')
+    expect(dialog).toContain('relabelCartonMarks(item)')
+    expect(dialog).toContain('type="warning">换标</el-tag>')
+    expect(dialog).not.toContain('function cartonMarks(')
+    expect(dialog).not.toContain('`normal-${mark}`')
+    expect(dialog).not.toContain('暂无箱唛')
+    expect(dialog).toContain('class="warehouse-tabs density-tabs"')
+    expect(dialog).toContain('dispatchVehicleSpecs')
+    const vehicleSpecs = source('../dispatchVehicleSpecs.ts')
+    expect(vehicleSpecs).toContain("label: '大车（30托）'")
+    expect(vehicleSpecs).toContain("label: '小车（15托）'")
+    expect(vehicleSpecs).not.toContain('14托')
+    expect(vehicleSpecs).not.toContain('12托')
+    expect(dialog).not.toContain('排车路线（选填）')
+    expect(dialog).not.toContain('v-model="route"')
+    const dispatches = source('DispatchesView.vue')
+    expect(dispatches).toContain('v-model="editForm.route" readonly')
+    expect(dispatches).not.toContain('route: editForm.route.trim()')
+  })
+
+  it('adds the prototype inventory transaction page as a read-only inventory route', () => {
+    const inventory = source('InventoryView.vue')
+    const transactions = source('InventoryTransactionsView.vue')
+    expect(inventory).toContain("name: 'overseas-inventory-transactions'")
+    expect(transactions).toContain('进销存记录筛选')
+    expect(transactions).toContain('业务订单号')
+    expect(transactions).toContain('入库单号')
+    expect(transactions).toContain('出库单号')
+    expect(transactions).toContain('不提供出库单跳转或库存变更操作')
+    expect(transactions).not.toContain('当前流水 DTO')
+    expect(transactions).toContain("router.push({ name: 'overseas-inventory' })")
+    expect(transactions).not.toContain('保存')
+    expect(transactions).not.toContain('ElMessage.success')
+    expect(transactions).not.toMatch(/router\.push\([^)]*outbound/)
+  })
+
+  it('uses module presentation models instead of untyped records', () => {
+    for (const fileName of ['LastMileOrdersView.vue', 'InboundOrdersView.vue', 'InventoryView.vue', 'RelabelOrdersView.vue', 'PalletsView.vue', 'CartonsView.vue', 'ProductsView.vue', 'InventoryTransactionsView.vue']) {
+      const value = source(fileName)
+      expect(value).toContain("from '../types'")
+      expect(value).not.toContain('ref<Record<string, unknown>[]>')
+    }
+  })
+
+  it('keeps every formal list connected to its read-only detail route', () => {
+    const expected = [
+      ['LastMileOrdersView.vue', 'overseas-last-mile-order-detail'],
+      ['InboundOrdersView.vue', 'overseas-inbound-order-detail'],
+      ['DispatchesView.vue', 'overseas-dispatch-detail'],
+      ['InventoryView.vue', 'overseas-inventory-detail'],
+      ['RelabelOrdersView.vue', 'overseas-relabel-order-detail'],
+      ['PalletsView.vue', 'overseas-pallet-detail'],
+      ['CartonsView.vue', 'overseas-carton-detail'],
+      ['ProductsView.vue', 'overseas-product-detail'],
+    ]
+    for (const [fileName, routeName] of expected) {
+      const value = source(fileName)
+      expect(value).toContain(routeName)
+      expect(value).toMatch(/@click="openDetail\(row(?: as [^"]+)?\)">(?:<Eye :size="15" \/>)?查看<\/el-button>/)
+    }
+  })
+
+  it('connects the dispatch prototype detail to the real overseas API', () => {
+    const detail = source('DispatchDetailView.vue')
+    expect(detail).toContain('getDispatch')
+    expect(detail).toContain('车辆信息')
+    expect(detail).toContain('排车信息')
+    expect(detail).toContain('单据信息')
+    expect(detail).toContain('关联订单明细')
+    expect(detail).toContain(':data="relatedOrders"')
+    expect(detail).toContain("router.push({ name: 'overseas-dispatches' })")
+    expect(detail).not.toContain('ElMessage.success')
+  })
+
+  it('preserves last-mile status tabs and read-only outbound association columns without links', () => {
+    const value = source('LastMileOrdersView.vue')
+    expect(value).toContain("listAllPlatformWarehouses({ warehouseType: 'FBA', status: 'ACTIVE' })")
+    expect(value).toContain('请选择目的 FBA 仓')
+    expect(value).toContain('aria-label="尾程订单状态"')
+    expect(value).toContain('<el-radio-button value="全部">全部</el-radio-button>')
+    expect(value).toContain('<el-radio-button value="待分配">待分配</el-radio-button>')
+    const columns = value.slice(value.indexOf('const columns:'), value.indexOf('const selectedContainerIds'))
+    expect(columns.indexOf("label: '入库单号'")).toBeLessThan(columns.indexOf("label: '出库单号'"))
+    expect(columns.indexOf("label: '出库单号'")).toBeLessThan(columns.indexOf("label: '派送单号'"))
+    expect(columns.indexOf("label: '派送单号'")).toBeLessThan(columns.indexOf("label: '换标单号'"))
+    expect(value).not.toMatch(/router\.push\([^)]*(outbound|dispatch)/)
+  })
+
+  it('keeps outbound cartons read-only and uses the prototype product confirmation copy', () => {
+    const cartons = source('CartonsView.vue')
+    const products = source('ProductsView.vue')
+    expect(cartons).toContain("function canEditCarton(source: object)")
+    expect(cartons).toContain("=== '在库'")
+    expect(cartons).toContain('access.can(permission.cartonEdit) && canEditCarton(row)')
+    expect(products).toContain('confirm-text="确定"')
+  })
+
+  it('keeps every prototype list column in its frozen order', () => {
+    expect(columnKeys('LastMileOrdersView.vue')).toEqual([
+      'actions', 'selection', 'orderNo', 'consolidated', 'palletMergeRelation', 'warning', 'orderType', 'rejectedAt', 'inboundCode', 'lxCode', 'owner', 'warehouse',
+      'transferWarehouse', 'fbaWarehouse', 'containerNo', 'abnormal', 'held', 'pallets',
+      'cartons', 'volume', 'quantity', 'volumeWeight', 'portEta', 'portAta', 'warehouseEta', 'inboundOrderNo',
+      'dispatchStatus', 'outboundOrderNo', 'dispatchOrderNo', 'relabelOrderNo', 'relabelStatus', 'status',
+      'createdAt', 'internalRemark', 'customerRemark', 'warehouseRemark',
+    ])
+    expect(columnKeys('InboundOrdersView.vue')).toEqual([
+      'actions', 'selection', 'orderNo', 'inboundCode', 'lxCode', 'type', 'warehouse', 'fbaWarehouse', 'owner', 'cartons', 'pickedCartons', 'volume',
+      'pallets', 'assigned', 'mergeAllowed', 'urgent', 'status', 'appointmentStatus', 'dispatchStatus', 'createdAt',
+    ])
+    expect(columnKeys('InventoryView.vue')).toEqual([
+      'actions', 'owner', 'warehouse', 'sku', 'productName', 'location', 'onHand', 'available', 'held', 'looseboard',
+      'inTransit', 'updatedAt',
+    ])
+    expect(columnKeys('RelabelOrdersView.vue')).toEqual([
+      'actions', 'orderNo', 'sku', 'productName', 'cartons', 'budgetTotal', 'relabelCost', 'walletStatus', 'labelRequirement', 'fileName', 'status', 'createdAt',
+    ])
+    expect(columnKeys('PalletsView.vue')).toEqual([
+      'actions', 'code', 'type', 'warehouse', 'volume', 'purchasePrice', 'fbaWarehouse', 'status', 'remark',
+    ])
+    expect(columnKeys('CartonsView.vue')).toEqual([
+      'actions', 'cartonNo', 'fbaWarehouse', 'sku', 'productName', 'quantity', 'weight', 'status',
+    ])
+    expect(columnKeys('ProductsView.vue')).toEqual([
+      'actions', 'sku', 'productName', 'englishName', 'category', 'length', 'width', 'height', 'weight',
+    ])
+    expect(columnKeys('InventoryTransactionsView.vue')).toEqual([
+      'actions', 'occurredAt', 'owner', 'warehouse', 'sku', 'productName', 'businessType', 'businessOrderNo',
+      'inboundCode', 'inboundOrderNo', 'outboundOrderNo', 'inboundQuantity', 'outboundQuantity', 'balance', 'operator', 'remark',
+    ])
+  })
+})
diff --git a/src/modules/overseas-warehouse/pages/realApiMount.test.ts b/src/modules/overseas-warehouse/pages/realApiMount.test.ts
new file mode 100644
index 00000000..72127e22
--- /dev/null
+++ b/src/modules/overseas-warehouse/pages/realApiMount.test.ts
@@ -0,0 +1,84 @@
+import ElementPlus from 'element-plus'
+import { createPinia } from 'pinia'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { listPlatformTenants } from '@/modules/iam'
+import DataTable from '@/shared/components/DataTable.vue'
+import { listInboundOrders } from '../api/inboundOrders'
+import { getInboundPlan } from '../api/inboundPlans'
+import { listInventoryLedger } from '../api/inventory'
+import { getLastMileOrder } from '../api/lastMileOrders'
+import InboundOrderDetailView from './InboundOrderDetailView.vue'
+import InboundOrdersView from './InboundOrdersView.vue'
+import InventoryTransactionsView from './InventoryTransactionsView.vue'
+import LastMileOrderDetailView from './LastMileOrderDetailView.vue'
+
+const routing = vi.hoisted(() => ({ push: vi.fn(), route: { params: {} as Record<string, string>, query: {} as Record<string, string> } }))
+vi.mock('vue-router', () => ({ useRoute: () => routing.route, useRouter: () => ({ push: routing.push }) }))
+vi.mock('@/modules/iam', () => ({ listPlatformTenants: vi.fn() }))
+vi.mock('../api/inboundOrders', () => ({
+  listInboundOrders: vi.fn(), createFbaAppointment: vi.fn(), getFbaAppointment: vi.fn(),
+  updateFbaAppointment: vi.fn(), updateInboundPlan: vi.fn(),
+}))
+vi.mock('../api/inboundPlans', () => ({ getInboundPlan: vi.fn() }))
+vi.mock('../api/inventory', () => ({ listInventoryLedger: vi.fn() }))
+vi.mock('../api/lastMileOrders', () => ({ getLastMileOrder: vi.fn(), createLastMileOrderFee: vi.fn() }))
+class ResizeObserverStub implements ResizeObserver { observe() {} unobserve() {} disconnect() {} }
+function memoryStorage(): Storage { const values = new Map<string, string>(); return { get length() { return values.size }, clear: () => values.clear(), getItem: (key) => values.get(key) ?? null, key: (index) => [...values.keys()][index] ?? null, removeItem: (key) => values.delete(key), setItem: (key, value) => values.set(key, value) } }
+enableAutoUnmount(afterEach); afterAll(() => vi.unstubAllGlobals())
+
+describe('overseas warehouse mounted real API pages', () => {
+  beforeEach(() => {
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub); vi.stubGlobal('localStorage', memoryStorage()); routing.push.mockReset(); routing.route.params = {}; routing.route.query = {}
+    vi.mocked(listPlatformTenants).mockReset().mockResolvedValue({ records: [{ id: '10001', tenantName: '客户甲', status: 'ACTIVE' } as never], page: 1, size: 200, total: 1, pages: 1 })
+    vi.mocked(listInboundOrders).mockReset().mockResolvedValue({ records: [], page: 1, size: 10, total: 0, pages: 0 })
+    vi.mocked(getInboundPlan).mockReset().mockResolvedValue({ id: '9007199254740993', planNo: 'IP-1', customerId: '10001', sourceOrderId: '9007199254740995', sourceOrderNo: 'FL-WH-20260911-000001', customerName: '客户甲', orderType: 'ONE_CLICK_DROPSHIP', overseasWarehouseCode: 'US-LAX-01', overseasWarehouseName: '洛杉矶接柜仓', status: 'PENDING_ASSIGNMENT', lineCount: 1, palletCount: 1, totalVolumeCbm: 2, createdAt: '2026-09-11T10:00:00', updatedAt: '2026-09-11T10:10:00', remark: '页面验收', lines: [{ id: '1', orderId: '9007199254740995', inboundCode: 'IN-1', fbaWarehouseCode: 'ABE3', destinationWarehouseCode: 'ABE3', destinationWarehouseName: 'ABE3目的仓', volumeCbm: 2, requiredPackageCount: 10, plannedPalletCount: 1 }], pallets: [], allocations: [] })
+    vi.mocked(listInventoryLedger).mockReset().mockResolvedValue({ records: [{ id: '9007199254740997', customerId: '10001', customerName: '客户甲', destinationWarehouseCode: 'LAX', inboundCode: 'NYEXX2608300001', inboundOrderNo: 'IP-1', businessType: 'STOCK_IN', beforePackages: 0, deltaPackages: 10, afterPackages: 10, occurredAt: '2026-08-20T10:00:00' }], page: 1, size: 20, total: 1, pages: 1 })
+    vi.mocked(getLastMileOrder).mockReset().mockResolvedValue({ order: { id: '9007199254740999', customerId: '10001', customerName: '华远贸易', orderNo: 'LMO-260827-0001', inboundCode: 'NYEXX2608280033', containerNo: 'TSTU0000061', containerNode: 'PICKUP_READY', currentStatus: 'PENDING_ASSIGNMENT' }, cargo: [], statusHistory: [], fees: [], operationHistory: [] })
+  })
+  it('keeps receiving warehouse and FBA warehouse independent in the inbound-plan list', async () => {
+    vi.mocked(listInboundOrders).mockResolvedValue({
+      records: [
+        { lineId: '1', planId: '11', planNo: 'IP-1', customerId: '10001', orderId: '21', inboundCode: 'IN-1', overseasWarehouseCode: 'US-LAX-01', overseasWarehouseName: '洛杉矶接柜仓', warehouseId: '31', warehouseCode: 'ABE3', warehouseName: 'ABE3目的仓', fbaWarehouseCode: 'ABE3' },
+        { lineId: '2', planId: '12', planNo: 'IP-2', customerId: '10001', orderId: '22', inboundCode: 'IN-2', overseasWarehouseCode: null, overseasWarehouseName: '不充整接柜仓', warehouseId: '32', warehouseCode: 'ONT8', warehouseName: 'ONT8目的仓', fbaWarehouseCode: 'ONT8' },
+      ], page: 1, size: 10, total: 2, pages: 1,
+    })
+    const wrapper = mount(InboundOrdersView, { global: { plugins: [createPinia(), ElementPlus] } })
+    await flushPromises()
+    const rows = wrapper.findComponent(DataTable).props('data') as Array<{ warehouse: string; fbaWarehouse: string; destinationWarehouseName: string }>
+    expect(rows[0]).toMatchObject({ warehouse: 'US-LAX-01 · 洛杉矶接柜仓', fbaWarehouse: 'ABE3', destinationWarehouseName: 'ABE3目的仓' })
+    expect(rows[1]).toMatchObject({ warehouse: '—', fbaWarehouse: 'ONT8', destinationWarehouseName: 'ONT8目的仓' })
+  })
+  it('mounts inbound detail with business references and independent receiving and FBA warehouse references', async () => { routing.route.params = { orderId: 'IP-1' }; routing.route.query = { customerId: '10001' }; const wrapper = mount(InboundOrderDetailView, { global: { plugins: [ElementPlus] } }); await flushPromises(); expect(getInboundPlan).toHaveBeenCalledWith('IP-1', '10001'); expect(wrapper.text()).toContain('IP-1'); expect(wrapper.text()).toContain('IN-1'); expect(wrapper.text()).not.toContain('9007199254740995'); expect(wrapper.text()).toContain('FL-WH-20260911-000001'); expect(wrapper.text()).toContain('客户甲'); expect(wrapper.text()).toContain('一件代发'); expect(wrapper.text()).toContain('2026-09-11 10:00'); expect(wrapper.text()).toContain('页面验收'); expect(wrapper.text()).toContain('US-LAX-01 · 洛杉矶接柜仓'); expect(wrapper.text()).toContain('ABE3'); expect(wrapper.text()).not.toContain('ABE3目的仓') })
+  it('shows the real pallet and owner plan for a cross-plan merged allocation', async () => {
+    vi.mocked(getInboundPlan).mockResolvedValueOnce({ id: '101', planNo: 'IP-CURRENT', customerId: '10001', sourceOrderId: '1', overseasWarehouseCode: 'US-LAX-01', overseasWarehouseName: '洛杉矶接柜仓', status: 'PICKING', lineCount: 1, palletCount: 1, totalVolumeCbm: 2, lines: [{ id: '201', orderId: '1', inboundCode: 'EXXHK2609100014', fbaWarehouseCode: 'ACY2', requiredPackageCount: 150, plannedPalletCount: 1 }], pallets: [{ id: '301', palletNo: 'DRYU2309389-101-005', sequenceNo: 1, actualPackageCount: 0 }], allocations: [{ lineId: '201', palletId: '302', palletNo: 'DRYU2309389-101-006', palletOwnerPlanNo: 'IP-OWNER', palletOwnedByCurrentPlan: false, plannedPackageCount: 150, countedPackageCount: 150, pickedPackageCount: 150, status: 'PICKED', version: 0 }] })
+    routing.route.params = { orderId: 'IP-CURRENT' }; routing.route.query = { customerId: '10001' }
+
+    const wrapper = mount(InboundOrderDetailView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    const rows = wrapper.findComponent(DataTable).props('data') as Array<{ palletNo: string; palletOwner: string; packageCount: number }>
+    expect(rows).toEqual([expect.objectContaining({ palletNo: 'DRYU2309389-101-006', palletOwner: 'IP-OWNER（跨计划合托）', packageCount: 150 })])
+    expect(wrapper.text()).not.toContain('DRYU2309389-101-005（跨计划合托）')
+  })
+  it('shows an empty receiving warehouse when either frozen field is missing without falling back to destination data', async () => {
+    vi.mocked(getInboundPlan).mockResolvedValueOnce({ id: '1', planNo: 'IP-2', customerId: '10001', sourceOrderId: '2', overseasWarehouseCode: null, overseasWarehouseName: '不充整接柜仓', status: 'PENDING_ASSIGNMENT', lineCount: 1, palletCount: 0, totalVolumeCbm: 0, lines: [{ id: '3', orderId: '2', inboundCode: 'IN-2', fbaWarehouseCode: 'ABE3', destinationWarehouseCode: 'ABE3', destinationWarehouseName: 'ABE3目的仓', requiredPackageCount: 1, plannedPalletCount: 0 }], pallets: [], allocations: [] })
+    routing.route.params = { orderId: 'IP-2' }; routing.route.query = { customerId: '10001' }
+    const wrapper = mount(InboundOrderDetailView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    const field = (label: string) => wrapper.findAll('dt').find((item) => item.text() === label)?.element.parentElement?.querySelector('dd')?.textContent
+    expect(field('海外仓')).toBe('—')
+    expect(field('FBA仓库')).toBe('ABE3')
+    expect(wrapper.text()).not.toContain('ABE3目的仓')
+  })
+  it('does not expose a numeric route id as an inbound business number when scope is missing', async () => {
+    routing.route.params = { orderId: '9007199254740995' }
+    routing.route.query = {}
+    const wrapper = mount(InboundOrderDetailView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(wrapper.text()).toContain('详情缺少客户范围')
+    expect(wrapper.text()).not.toContain('9007199254740995')
+  })
+  it('mounts inventory ledger as localized read-only business facts without exposing internal ids', async () => { const wrapper = mount(InventoryTransactionsView, { global: { plugins: [createPinia(), ElementPlus] } }); await flushPromises(); expect(listInventoryLedger).toHaveBeenCalledWith(expect.objectContaining({ page: 1, size: 10 })); expect(listInventoryLedger).not.toHaveBeenCalledWith(expect.objectContaining({ customerId: expect.anything() })); expect(wrapper.text()).toContain('客户甲'); expect(wrapper.text()).toContain('NYEXX2608300001'); expect(wrapper.text()).not.toContain('10001'); expect(wrapper.text()).toContain('IP-1'); expect(wrapper.text()).toContain('10'); expect(wrapper.text()).toContain('入库'); expect(wrapper.text()).not.toContain('STOCK_IN'); expect(wrapper.text()).toContain('不提供出库单跳转'); expect(wrapper.text()).not.toContain('当前流水 DTO'); expect(wrapper.text()).not.toContain('操作人名称待补充') })
+  it('renders complete business references with single-line ellipsis and titles', async () => { routing.route.params = { orderId: '9007199254740999' }; const wrapper = mount(LastMileOrderDetailView, { global: { plugins: [createPinia(), ElementPlus] } }); await flushPromises(); expect(getLastMileOrder).toHaveBeenCalledWith('9007199254740999'); expect(wrapper.text()).toContain('华远贸易'); expect(wrapper.text()).toContain('LMO-260827-0001'); expect(wrapper.text()).toContain('货柜节点'); expect(wrapper.text()).toContain('已清关、可提柜'); expect(wrapper.text()).not.toContain('清关状态'); expect(wrapper.get('.order-reference-text').attributes('title')).toBe('LMO-260827-0001'); const businessValues = wrapper.findAll('.detail-field-value--business'); expect(businessValues.map((item) => item.attributes('title'))).toEqual(expect.arrayContaining(['NYEXX2608280033', 'TSTU0000061'])); expect(businessValues.every((item) => item.text().length > 0)).toBe(true) })
+})
diff --git a/src/modules/overseas-warehouse/permissions.ts b/src/modules/overseas-warehouse/permissions.ts
new file mode 100644
index 00000000..14de1e43
--- /dev/null
+++ b/src/modules/overseas-warehouse/permissions.ts
@@ -0,0 +1,51 @@
+export const overseasWarehousePermissions = {
+  lastMileOrderList: 'platform:overseas-warehouse:last-mile-order:list',
+  lastMileOrderExport: 'platform:overseas-warehouse:last-mile-order:export',
+  lastMileOrderTransfer: 'platform:overseas-warehouse:last-mile-order:edit',
+  warehouseTransferApprove: 'platform:overseas-warehouse:warehouse-transfer:approve',
+  inboundOrderList: 'platform:overseas-warehouse:inbound-order:list',
+  inboundOrderCreate: 'platform:overseas-warehouse:inbound-order:create',
+  inboundOrderEdit: 'platform:overseas-warehouse:inbound-order:edit',
+  inboundOrderAppointment: 'platform:overseas-warehouse:inbound-order:fba-appointment',
+  inboundOrderSmartDispatch: 'platform:overseas-warehouse:inbound-order:smart-dispatch',
+  dispatchList: 'platform:overseas-warehouse:dispatch:list',
+  dispatchEdit: 'platform:overseas-warehouse:dispatch:edit',
+  dispatchCancel: 'platform:overseas-warehouse:dispatch:cancel',
+  dispatchTransferDelivery: 'platform:overseas-warehouse:dispatch:transfer-delivery',
+  outboundList: 'platform:overseas-warehouse:outbound:list',
+  outboundCreate: 'platform:overseas-warehouse:outbound:create',
+  outboundCancel: 'platform:overseas-warehouse:outbound:cancel',
+  deliveryList: 'platform:overseas-warehouse:delivery:list',
+  exceptionOrderList: 'platform:overseas-warehouse:exception-order:list',
+  exceptionOrderCreate: 'platform:overseas-warehouse:exception-order:create',
+  deliveryReturn: 'platform:overseas-warehouse:delivery:return',
+  deliveryStatus: 'platform:overseas-warehouse:delivery:status',
+  deliveryDocuments: 'platform:overseas-warehouse:delivery:documents',
+  customerVisitList: 'platform:overseas-warehouse:customer-visit:list',
+  customerVisitEdit: 'platform:overseas-warehouse:customer-visit:edit',
+  inventoryList: 'platform:overseas-warehouse:inventory:list',
+  inventoryExport: 'platform:overseas-warehouse:inventory:export',
+  inventoryEdit: 'platform:overseas-warehouse:inventory:edit',
+  inventoryAdjust: 'platform:overseas-warehouse:inventory:adjust',
+  returnInventoryList: 'platform:overseas-warehouse:return-inventory:list',
+  returnCartonsList: 'platform:overseas-warehouse:return-cartons:list',
+  relabelOrderList: 'platform:overseas-warehouse:relabel-order:list',
+  relabelOrderCreate: 'platform:overseas-warehouse:relabel-order:create',
+  relabelOrderStatus: 'platform:overseas-warehouse:relabel-order:status',
+  locationList: 'platform:overseas-warehouse:location:list',
+  locationCreate: 'platform:overseas-warehouse:location:create',
+  locationEdit: 'platform:overseas-warehouse:location:edit',
+  locationDelete: 'platform:overseas-warehouse:location:delete',
+  warehouseList: 'platform:overseas-warehouse:warehouse:list',
+  palletList: 'platform:overseas-warehouse:pallet:list',
+  palletCreate: 'platform:overseas-warehouse:pallet:create',
+  palletEdit: 'platform:overseas-warehouse:pallet:edit',
+  palletDelete: 'platform:overseas-warehouse:pallet:delete',
+  // 箱号、产品库本期暂缓；权限常量随保留源码留存，但不再由模块正式路由引用。
+  cartonList: 'platform:overseas-warehouse:carton:list',
+  cartonCreate: 'platform:overseas-warehouse:carton:create',
+  cartonEdit: 'platform:overseas-warehouse:carton:edit',
+  productList: 'platform:overseas-warehouse:product:list',
+  productCreate: 'platform:overseas-warehouse:product:create',
+  productEdit: 'platform:overseas-warehouse:product:edit',
+} as const
diff --git a/src/modules/overseas-warehouse/routes.test.ts b/src/modules/overseas-warehouse/routes.test.ts
new file mode 100644
index 00000000..3b7f7c54
--- /dev/null
+++ b/src/modules/overseas-warehouse/routes.test.ts
@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest'
+import { overseasWarehouseRoutes } from './routes'
+import { overseasWarehousePermissions as permission } from './permissions'
+
+describe('overseas warehouse routes', () => {
+  it('uses list permission for each list and read-only detail route', () => {
+    expect(overseasWarehouseRoutes.map((route) => [route.path, route.meta.permission])).toEqual([
+      ['overseas-warehouse/last-mile-orders', permission.lastMileOrderList],
+      ['overseas-warehouse/last-mile-orders/:orderId', permission.lastMileOrderList],
+      ['overseas-warehouse/inbound-orders', permission.inboundOrderList],
+      ['overseas-warehouse/inbound-orders/:orderId', permission.inboundOrderList],
+      ['overseas-warehouse/dispatches', permission.dispatchList],
+      ['overseas-warehouse/dispatches/:dispatchNo', permission.dispatchList],
+      ['overseas-warehouse/outbounds', permission.outboundList],
+      ['overseas-warehouse/outbounds/:outboundNo', permission.outboundList],
+      ['overseas-warehouse/delivery-orders', permission.deliveryList],
+      ['overseas-warehouse/delivery-orders/:deliveryNo', permission.deliveryList],
+      ['overseas-warehouse/exception-orders', permission.exceptionOrderList],
+      ['overseas-warehouse/customer-visits', permission.customerVisitList],
+      ['overseas-warehouse/inventory', permission.inventoryList],
+      ['overseas-warehouse/return-inventory', permission.returnInventoryList],
+      ['overseas-warehouse/return-cartons', permission.returnCartonsList],
+      ['overseas-warehouse/inventory-transactions', permission.inventoryList],
+      ['overseas-warehouse/inventory/:inventoryId', permission.inventoryList],
+      ['overseas-warehouse/relabel-orders', permission.relabelOrderList],
+      ['overseas-warehouse/relabel-orders/:orderId', permission.relabelOrderList],
+      ['overseas-warehouse/pallets', permission.palletList],
+      ['overseas-warehouse/pallets/:palletId', permission.palletList],
+    ])
+  })
+
+  it('keeps all details as formal parameterized pages', () => {
+    const details = overseasWarehouseRoutes.filter((route) => route.path.includes('/:'))
+    expect(details).toHaveLength(8)
+    expect(details.every((route) => route.meta.showPageHeading === false)).toBe(true)
+  })
+
+  it('keeps deferred carton and product page sources outside the formal route set', () => {
+    const paths = overseasWarehouseRoutes.map((route) => route.path)
+    expect(paths.some((path) => path.includes('/cartons'))).toBe(false)
+    expect(paths.some((path) => path.includes('/products'))).toBe(false)
+  })
+
+  it('retains independent write permissions for current and deferred page sources', () => {
+    expect(new Set([
+      permission.relabelOrderCreate, permission.relabelOrderStatus,
+      permission.palletCreate, permission.palletEdit,
+      permission.cartonCreate, permission.cartonEdit,
+      permission.productCreate, permission.productEdit,
+      permission.exceptionOrderCreate, permission.deliveryReturn, permission.deliveryStatus,
+      permission.customerVisitEdit,
+      permission.dispatchEdit, permission.dispatchCancel, permission.dispatchTransferDelivery,
+      permission.outboundCancel, permission.outboundCreate,
+      permission.warehouseTransferApprove,
+    ]).size).toBe(18)
+  })
+})
diff --git a/src/modules/overseas-warehouse/routes.ts b/src/modules/overseas-warehouse/routes.ts
new file mode 100644
index 00000000..4394c76d
--- /dev/null
+++ b/src/modules/overseas-warehouse/routes.ts
@@ -0,0 +1,133 @@
+import type { RouteRecordRaw } from 'vue-router'
+import { overseasWarehousePermissions as permission } from './permissions'
+
+export const overseasWarehouseRoutes = [
+  {
+    path: 'overseas-warehouse/last-mile-orders',
+    name: 'overseas-last-mile-orders',
+    component: () => import('./pages/LastMileOrdersView.vue'),
+    meta: { title: '尾程订单', description: '管理海外接柜后的尾程订单与入仓衔接', permission: permission.lastMileOrderList },
+  },
+  {
+    path: 'overseas-warehouse/last-mile-orders/:orderId',
+    name: 'overseas-last-mile-order-detail',
+    component: () => import('./pages/LastMileOrderDetailView.vue'),
+    meta: { title: '尾程订单详情', description: '查看尾程订单、计划、货物和操作记录', permission: permission.lastMileOrderList, showPageHeading: false },
+  },
+  {
+    path: 'overseas-warehouse/inbound-orders',
+    name: 'overseas-inbound-orders',
+    component: () => import('./pages/InboundOrdersView.vue'),
+    meta: { title: '入库单', description: '管理海外合作仓入库、预约与排车衔接', permission: permission.inboundOrderList },
+  },
+  {
+    path: 'overseas-warehouse/inbound-orders/:orderId',
+    name: 'overseas-inbound-order-detail',
+    component: () => import('./pages/InboundOrderDetailView.vue'),
+    meta: { title: '入库单详情', description: '查看海外仓入库单与应收费用', permission: permission.inboundOrderList, showPageHeading: false },
+  },
+  {
+    path: 'overseas-warehouse/dispatches',
+    name: 'overseas-dispatches',
+    component: () => import('./pages/DispatchesView.vue'),
+    meta: { title: '排车列表', description: '查看海外仓车辆调度、预约与发车状态', permission: permission.dispatchList },
+  },
+  {
+    path: 'overseas-warehouse/dispatches/:dispatchNo',
+    name: 'overseas-dispatch-detail',
+    component: () => import('./pages/DispatchDetailView.vue'),
+    meta: { title: '排车详情', description: '查看排车、车辆和关联订单明细', permission: permission.dispatchList, showPageHeading: false },
+  },
+  {
+    path: 'overseas-warehouse/outbounds',
+    name: 'overseas-outbounds',
+    component: () => import('./pages/OutboundsView.vue'),
+    meta: { title: '出库单', description: '查询海外仓出库单并创建一件代发出库', permission: permission.outboundList },
+  },
+  {
+    path: 'overseas-warehouse/outbounds/:outboundNo',
+    name: 'overseas-outbound-detail',
+    component: () => import('./pages/OutboundDetailView.vue'),
+    meta: { title: '出库单详情', description: '查看海外仓出库单与关联派送信息', permission: permission.outboundList, showPageHeading: false },
+  },
+  {
+    path: 'overseas-warehouse/delivery-orders',
+    name: 'overseas-delivery-orders',
+    component: () => import('./pages/DeliveryOrdersView.vue'),
+    meta: { title: '派送单列表', description: '查询海外仓派送订单及履约信息', permission: permission.deliveryList },
+  },
+  {
+    path: 'overseas-warehouse/delivery-orders/:deliveryNo',
+    name: 'overseas-delivery-order-detail',
+    component: () => import('./pages/DeliveryOrderDetailView.vue'),
+    meta: { title: '派送单详情', description: '查看派送订单、SKU、费用和操作记录', permission: permission.deliveryList, showPageHeading: false },
+  },
+  {
+    path: 'overseas-warehouse/exception-orders',
+    name: 'overseas-exception-orders',
+    component: () => import('./pages/ExceptionOrdersView.vue'),
+    meta: { title: '异常订单', description: '查询和新增海外仓异常、拒收及退货单据', permission: permission.exceptionOrderList },
+  },
+  {
+    path: 'overseas-warehouse/customer-visits',
+    name: 'overseas-customer-visits',
+    component: () => import('./pages/CustomerVisitsView.vue'),
+    meta: { title: '客户回访', description: '跟进已完成派送单并维护入仓单维度回访资料', permission: permission.customerVisitList },
+  },
+  {
+    path: 'overseas-warehouse/inventory',
+    name: 'overseas-inventory',
+    component: () => import('./pages/InventoryView.vue'),
+    meta: { title: '库存管理', description: '查看海外仓库存汇总、可用量和库内分布', permission: permission.inventoryList },
+  },
+  {
+    path: 'overseas-warehouse/return-inventory',
+    name: 'overseas-return-inventory',
+    component: () => import('./pages/ReturnInventoryManagementView.vue'),
+    props: { mode: 'inventory' },
+    meta: { title: '退货库存管理', description: '按客户和 SKU 查询退货签收后的可用库存', permission: permission.returnInventoryList },
+  },
+  {
+    path: 'overseas-warehouse/return-cartons',
+    name: 'overseas-return-cartons',
+    component: () => import('./pages/ReturnInventoryManagementView.vue'),
+    props: { mode: 'cartons' },
+    meta: { title: '退货箱号管理', description: '查询合箱后的箱号、箱规和箱内 SKU', permission: permission.returnCartonsList },
+  },
+  {
+    path: 'overseas-warehouse/inventory-transactions',
+    name: 'overseas-inventory-transactions',
+    component: () => import('./pages/InventoryTransactionsView.vue'),
+    meta: { title: '进销存记录', description: '查看海外仓库存的只读变动流水', permission: permission.inventoryList },
+  },
+  {
+    path: 'overseas-warehouse/inventory/:inventoryId',
+    name: 'overseas-inventory-detail',
+    component: () => import('./pages/InventoryDetailView.vue'),
+    meta: { title: '库存详情', description: '查看商品、库位、托盘箱号和进销存明细', permission: permission.inventoryList, showPageHeading: false },
+  },
+  {
+    path: 'overseas-warehouse/relabel-orders',
+    name: 'overseas-relabel-orders',
+    component: () => import('./pages/RelabelOrdersView.vue'),
+    meta: { title: '换标单', description: '管理海外仓换标作业要求与费用信息', permission: permission.relabelOrderList },
+  },
+  {
+    path: 'overseas-warehouse/relabel-orders/:orderId',
+    name: 'overseas-relabel-order-detail',
+    component: () => import('./pages/RelabelOrderDetailView.vue'),
+    meta: { title: '换标单详情', description: '查看换标单、作业要求与费用明细', permission: permission.relabelOrderList, showPageHeading: false },
+  },
+  {
+    path: 'overseas-warehouse/pallets',
+    name: 'overseas-pallets',
+    component: () => import('./pages/PalletsView.vue'),
+    meta: { title: '托盘管理', description: '管理海外仓托盘主数据与使用状态', permission: permission.palletList },
+  },
+  {
+    path: 'overseas-warehouse/pallets/:palletId',
+    name: 'overseas-pallet-detail',
+    component: () => import('./pages/PalletDetailView.vue'),
+    meta: { title: '托盘详情', description: '查看托盘基础信息与使用信息', permission: permission.palletList, showPageHeading: false },
+  },
+] satisfies RouteRecordRaw[]
diff --git a/src/modules/overseas-warehouse/types.test.ts b/src/modules/overseas-warehouse/types.test.ts
new file mode 100644
index 00000000..00932201
--- /dev/null
+++ b/src/modules/overseas-warehouse/types.test.ts
@@ -0,0 +1,25 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/overseas-warehouse/types.ts'), 'utf8')
+
+describe('overseas warehouse presentation contracts', () => {
+  it('covers every formal list without freezing an API transport', () => {
+    for (const name of [
+      'LastMileOrderListItem', 'InboundOrderListItem', 'DispatchListItem', 'InventoryListItem',
+      'RelabelOrderListItem', 'PalletListItem', 'CartonListItem',
+      'ProductListItem', 'InventoryTransactionListItem',
+    ]) expect(source).toContain(`interface ${name}`)
+    expect(source).not.toContain('axios')
+    expect(source).not.toContain("from '@/shared/api/http'")
+    expect(source).not.toMatch(/https?:\/\//)
+    expect(source).not.toContain('tenantId')
+  })
+
+  it('marks outbound references as read-only inventory facts', () => {
+    expect(source.match(/Read-only inventory fact/g)).toHaveLength(2)
+    expect(source).not.toContain('createOutbound')
+    expect(source).not.toContain('updateOutbound')
+  })
+})
diff --git a/src/modules/overseas-warehouse/types.ts b/src/modules/overseas-warehouse/types.ts
new file mode 100644
index 00000000..6591f76c
--- /dev/null
+++ b/src/modules/overseas-warehouse/types.ts
@@ -0,0 +1,212 @@
+/**
+ * Prototype-derived presentation models for the Admin pages in this module.
+ * These types intentionally do not freeze overseas API URLs, pagination envelopes,
+ * identifiers, timestamps, money precision, or mutation request contracts.
+ */
+export interface LastMileOrderListItem {
+  id: string
+  customerId: string
+  sourceContainerBookingId: string
+  orderNo: string
+  orderTypeCode: string
+  currentStatusCode: string
+  warning: string
+  orderType: string
+  rejectedAt: string
+  inboundCode: string
+  lxCode: string
+  owner: string
+  overseasWarehouseId: string
+  overseasWarehouseCode: string
+  warehouse: string
+  transferWarehouse: string
+  fbaWarehouse: string
+  containerNo: string
+  containerNode: string
+  abnormal: string
+  held: string
+  detained: boolean
+  holdChargeable: boolean
+  holdReason: string
+  manualNodeOverride: boolean
+  version: number
+  pallets: number | '—'
+  cartons: number | '—'
+  volume: number | '—'
+  quantity: number | '—'
+  volumeWeight: number | '—'
+  portEta: string
+  portAta: string
+  estimatedWarehouseAt: string
+  warehouseEta: string
+  inboundOrderNo: string
+  dispatchStatus: string
+  /** Read-only association fact; this module does not implement the outbound workflow. */
+  outboundOrderNo: string
+  /** Read-only association fact; this module does not implement overseas delivery. */
+  dispatchOrderNo: string
+  relabelOrderNo: string
+  relabelStatus: string
+  consolidated: string
+  palletMergeFlag: string
+  palletMergeRelation: string
+  status: string
+  internalRemark: string
+  customerRemark: string
+  warehouseRemark: string
+  createdAt: string
+}
+
+export interface InboundOrderListItem {
+  lineId: string
+  planId: string
+  customerId: string
+  orderId: string
+  warehouseId: string
+  destinationWarehouseCode: string
+  destinationWarehouseName: string
+  orderNo: string
+  inboundCode: string
+  lxCode: string
+  type: string
+  warehouse: string
+  fbaWarehouse: string
+  owner: string
+  cartons: number
+  pickedCartons: number
+  volume: number
+  pallets: number
+  assigned: string
+  mergeAllowed: string
+  urgent: string
+  status: string
+  appointmentNo: string
+  appointmentStatus: string
+  appointmentAt: string
+  expectedLoadingAt: string
+  dispatchStatus: string
+  createdAt: string
+  version: number
+}
+
+export interface DispatchListItem {
+  id: string
+  dispatchNo: string
+  vehiclePlate: string
+  driverName: string
+  driverPhone: string
+  carrierName: string
+  orderNos: string
+  route: string
+  overseasWarehouse: string
+  departAt: string
+  fbaAppointment: string
+  vehicleAppointment: string
+  estimatedArrivalAt: string
+  status: string
+  statusCode: string
+  palletCount: number
+  packageCount: number
+  createdAt: string
+}
+
+export interface InventoryListItem {
+  id: string
+  customerId: string
+  warehouseId: string
+  inboundOrderNo: string
+  inboundCode: string
+  owner: string
+  warehouse: string
+  sku: string
+  productName: string
+  location: string
+  onHand: number
+  available: number
+  held: number
+  looseboard: number | string | null
+  inTransit: number
+  purchase: number
+  status: string
+  updatedAt: string
+}
+
+export interface RelabelOrderListItem {
+  customerId: string
+  orderNo: string
+  relatedOrderNo: string
+  sku: string
+  productName: string
+  cartons: number
+  budgetTotal: number | null
+  labelRequirement: string
+  relabelCost?: number
+  walletStatus?: string
+  walletErrorMessage?: string
+  fileName: string
+  status: string
+  rawStatus?: string
+  remark: string
+  createdAt: string
+}
+
+export interface PalletListItem {
+  id: string
+  customerId: string
+  warehouseId: string
+  locationId: string
+  code: string
+  type: string
+  warehouse: string
+  volume: number
+  purchasePrice: number
+  fbaWarehouse: string
+  status: string
+  remark: string
+}
+
+export interface CartonListItem {
+  cartonNo: string
+  fbaWarehouse: string
+  sku: string
+  productName: string
+  quantity: number
+  weight: number
+  status: string
+  palletNo: string
+  inboundOrderNo: string
+  /** Read-only inventory fact; this module does not implement the outbound workflow. */
+  outboundOrderNo: string
+  remark: string
+}
+
+export interface ProductListItem {
+  sku: string
+  productName: string
+  englishName: string
+  category: string
+  length: number
+  width: number
+  height: number
+  weight: number
+}
+
+export interface InventoryTransactionListItem {
+  id: string
+  occurredAt: string
+  owner: string
+  warehouse: string
+  sku: string
+  productName: string
+  businessType: string
+  businessOrderNo: string
+  inboundCode: string
+  inboundOrderNo: string
+  /** Read-only inventory fact; it is not an outbound-workflow link. */
+  outboundOrderNo: string
+  inboundQuantity: number
+  outboundQuantity: number
+  balance: number
+  operator: string
+  remark: string
+}
diff --git a/src/modules/port-schedules/api/platformCarrierScheduleQueries.test.ts b/src/modules/port-schedules/api/platformCarrierScheduleQueries.test.ts
new file mode 100644
index 00000000..dce67e21
--- /dev/null
+++ b/src/modules/port-schedules/api/platformCarrierScheduleQueries.test.ts
@@ -0,0 +1,65 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import { appendCarrierScheduleManualNode, getCarrierScheduleQuery, listCarrierScheduleQueries } from './platformCarrierScheduleQueries'
+
+vi.mock('@/shared/api/http', async () => {
+  const actual = await vi.importActual<typeof import('@/shared/api/http')>('@/shared/api/http')
+  return { ...actual, http: { get: vi.fn(), post: vi.fn() } }
+})
+
+const query = {
+  id: 9007199254740993n,
+  queryNo: 'CSQ-1',
+  customerId: 101,
+  oceanBookingId: 202,
+  containerBookingId: 303,
+  carrierCode: 'COSCO',
+  trackingType: 'CONTAINER_NO',
+  trackingNo: 'CSNU1234567',
+  status: 'MANUAL_REQUIRED',
+  triggerSource: 'OUTBOUND_CONFIRM',
+  latestActualNode: 'DEPARTED_WAREHOUSE',
+  latestActualAt: '2026-08-20T10:00:00',
+  accessMode: 'DYNAMIC_IFRAME',
+  lastErrorCode: 'DYNAMIC_IFRAME_REQUIRED',
+  lastErrorMessage: '必须人工查询',
+  resultPortScheduleId: 404,
+  version: '3',
+}
+
+describe('platformCarrierScheduleQueries', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it('filters by real booking/container relations and preserves long ids as strings', async () => {
+    vi.mocked(http.get).mockResolvedValue({ code: '200', data: { records: [{ query, expired: true }], page: '1', size: '200', total: '1', pages: '1' } })
+    const result = await listCarrierScheduleQueries({ page: 1, size: 200, oceanBookingId: '202', containerBookingId: '303' })
+    expect(vi.mocked(http.get)).toHaveBeenCalledWith('/platform/v1/carrier-schedule-queries', { params: { page: 1, size: 200, oceanBookingId: '202', containerBookingId: '303' } })
+    expect(result.records[0]).toMatchObject({ query: { id: '9007199254740993', customerId: '101', oceanBookingId: '202', containerBookingId: '303', resultPortScheduleId: '404', accessMode: 'DYNAMIC_IFRAME', triggerSource: 'OUTBOUND_CONFIRM', latestActualNode: 'DEPARTED_WAREHOUSE', latestActualAt: '2026-08-20T10:00:00', lastErrorCode: 'DYNAMIC_IFRAME_REQUIRED', lastErrorMessage: '必须人工查询', version: 3 }, expired: true })
+  })
+
+  it('normalizes standard node facts and immutable business history', async () => {
+    vi.mocked(http.get).mockResolvedValue({ code: '200', data: { query: { query: { ...query, status: 'READY', latestActualNode: 'ARRIVED_DESTINATION_PORT' }, expired: false }, nodes: [{ id: 1, providerCode: 'COSCO', providerEventId: 'provider-event-1', providerNodeCode: 'ARR', standardNode: 'ARRIVED_DESTINATION_PORT', nodeSequence: '60', observedAt: '2026-08-20T12:00:00', estimatedAt: null, actualAt: '2026-08-20T11:55:00', locationCode: 'USLAX', locationName: 'Los Angeles', sourceReference: 'provider-event-1', rawPayloadHash: 'a'.repeat(64), createdAt: '2026-08-20T12:01:00' }], exceptions: [{ id: 3, providerCode: 'COSCO', providerEventId: 'hold-1', providerStatus: 'CUSTOMS HOLD', exceptionCode: 'CUSTOMS_HOLD', active: true, observedAt: '2026-08-20T12:05:00', locationCode: 'USLAX', locationName: 'Los Angeles', sourceReference: 'provider-hold-1', rawPayloadHash: 'c'.repeat(64), createdAt: '2026-08-20T12:06:00' }], histories: [{ id: 2, action: 'NODE_OBSERVED', fromVersion: '1', toVersion: '2', reason: 'ARRIVED_DESTINATION_PORT', operatorId: 808 }] } })
+    const result = await getCarrierScheduleQuery('9007199254740993')
+    expect(vi.mocked(http.get)).toHaveBeenCalledWith('/platform/v1/carrier-schedule-queries/9007199254740993')
+    expect(result.nodes[0]).toMatchObject({ id: '1', standardNode: 'ARRIVED_DESTINATION_PORT', nodeSequence: 60, actualAt: '2026-08-20T11:55:00', locationCode: 'USLAX' })
+    expect(result.exceptions[0]).toMatchObject({ id: '3', providerEventId: 'hold-1', providerStatus: 'CUSTOMS HOLD', active: true })
+    expect(result.histories[0]).toMatchObject({ id: '2', action: 'NODE_OBSERVED', fromVersion: 1, toVersion: 2, operatorId: '808' })
+  })
+
+  it('preserves nullable DTO fields instead of fabricating false or zero values', async () => {
+    vi.mocked(http.get).mockResolvedValue({ code: '200', data: { query: { query: { ...query, containerBookingId: null, resultPortScheduleId: null, latestActualNode: null, latestActualAt: null, stoppedAt: null, stopReason: null }, expired: true }, nodes: [{ id: 1, providerCode: 'FIRSTLEG', providerEventId: 'outbound-1', providerNodeCode: 'OUTBOUND_CONFIRM', standardNode: 'DEPARTED_WAREHOUSE', nodeSequence: 10, observedAt: '2026-08-20T10:00:00', estimatedAt: null, actualAt: null, locationCode: null, locationName: null, sourceReference: null, rawPayloadHash: 'b'.repeat(64), createdAt: null }], exceptions: [], histories: [{ id: 2, action: 'AUTO_CREATE', fromVersion: null, toVersion: 0, reason: null, operatorId: null, operatorName: null, createdAt: null }] } })
+    const result = await getCarrierScheduleQuery('9007199254740993')
+    expect(result.query.query).toMatchObject({ containerBookingId: null, resultPortScheduleId: null, latestActualNode: null, latestActualAt: null, stoppedAt: null, stopReason: null })
+    expect(result.nodes[0]).toMatchObject({ estimatedAt: null, actualAt: null, locationCode: null, locationName: null, sourceReference: null, createdAt: null })
+    expect(result.histories[0]).toMatchObject({ fromVersion: null, operatorId: null, operatorName: null, createdAt: null })
+  })
+
+  it('passes the dialog-scoped idempotency key to the frozen manual-node endpoint', async () => {
+    const detail = { query: { query: { ...query, status: 'READY' }, expired: false }, nodes: [], exceptions: [], histories: [] }
+    vi.mocked(http.post).mockResolvedValue({ code: '200', data: detail })
+    const request = { expectedVersion: 3, standardNode: 'IN_TRANSIT' as const, observedAt: '2026-08-21T10:00:00', estimatedAt: '2026-08-22T10:00:00', actualAt: null, locationCode: 'PACIFIC', locationName: 'Pacific Ocean', reason: '船司官网人工核验' }
+    await appendCarrierScheduleManualNode('9007199254740993', 'manual-session-key', request)
+    expect(vi.mocked(http.post)).toHaveBeenCalledWith('/platform/v1/carrier-schedule-queries/9007199254740993/manual-nodes', request, { headers: { 'Idempotency-Key': 'manual-session-key' } })
+  })
+
+})
diff --git a/src/modules/port-schedules/api/platformCarrierScheduleQueries.ts b/src/modules/port-schedules/api/platformCarrierScheduleQueries.ts
new file mode 100644
index 00000000..f3a51a72
--- /dev/null
+++ b/src/modules/port-schedules/api/platformCarrierScheduleQueries.ts
@@ -0,0 +1,67 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import type {
+  CarrierScheduleQueryDetail,
+  CarrierScheduleExceptionFact,
+  CarrierScheduleQueryFilter,
+  CarrierScheduleQueryHistory,
+  CarrierScheduleNodeFact,
+  CarrierScheduleQueryPage,
+  CarrierScheduleQueryResource,
+  CarrierScheduleQueryView,
+  CarrierScheduleManualNodeRequest,
+} from '../types'
+
+const basePath = '/platform/v1/carrier-schedule-queries'
+
+function optionalId(value: unknown): string | null { return value == null ? null : String(value) }
+function numberValue(value: unknown, fallback = 0): number { const parsed = Number(value); return Number.isFinite(parsed) ? parsed : fallback }
+
+function resource(raw: CarrierScheduleQueryResource): CarrierScheduleQueryResource {
+  return {
+    ...raw,
+    id: String(raw.id),
+    customerId: String(raw.customerId),
+    oceanBookingId: String(raw.oceanBookingId),
+    containerBookingId: optionalId(raw.containerBookingId),
+    resultPortScheduleId: optionalId(raw.resultPortScheduleId),
+    version: numberValue(raw.version),
+  }
+}
+
+function view(raw: CarrierScheduleQueryView): CarrierScheduleQueryView {
+  return { ...raw, query: resource(raw.query) }
+}
+
+function node(raw: CarrierScheduleNodeFact): CarrierScheduleNodeFact {
+  return { ...raw, id: String(raw.id), nodeSequence: numberValue(raw.nodeSequence) }
+}
+
+function exception(raw: CarrierScheduleExceptionFact): CarrierScheduleExceptionFact {
+  return { ...raw, id: String(raw.id), active: Boolean(raw.active) }
+}
+
+function history(raw: CarrierScheduleQueryHistory): CarrierScheduleQueryHistory {
+  return { ...raw, id: String(raw.id), fromVersion: raw.fromVersion == null ? null : numberValue(raw.fromVersion), toVersion: raw.toVersion == null ? null : numberValue(raw.toVersion), operatorId: optionalId(raw.operatorId) }
+}
+
+export async function listCarrierScheduleQueries(filter: CarrierScheduleQueryFilter): Promise<CarrierScheduleQueryPage> {
+  const response = await http.get<ApiEnvelope<CarrierScheduleQueryPage>, ApiEnvelope<CarrierScheduleQueryPage>>(basePath, { params: filter })
+  const result = unwrapApiResponse(response)
+  return { ...result, records: (result.records || []).map(view), page: numberValue(result.page, filter.page), size: numberValue(result.size, filter.size), total: numberValue(result.total), pages: numberValue(result.pages) }
+}
+
+export async function getCarrierScheduleQuery(queryId: string): Promise<CarrierScheduleQueryDetail> {
+  const response = await http.get<ApiEnvelope<CarrierScheduleQueryDetail>, ApiEnvelope<CarrierScheduleQueryDetail>>(`${basePath}/${encodeURIComponent(queryId)}`)
+  const result = unwrapApiResponse(response)
+  return { ...result, query: view(result.query), nodes: (result.nodes || []).map(node), exceptions: (result.exceptions || []).map(exception), histories: (result.histories || []).map(history) }
+}
+
+export async function appendCarrierScheduleManualNode(queryId: string, idempotencyKey: string, request: CarrierScheduleManualNodeRequest): Promise<CarrierScheduleQueryDetail> {
+  const response = await http.post<ApiEnvelope<CarrierScheduleQueryDetail>, ApiEnvelope<CarrierScheduleQueryDetail>>(
+    `${basePath}/${encodeURIComponent(queryId)}/manual-nodes`,
+    request,
+    { headers: { 'Idempotency-Key': idempotencyKey } },
+  )
+  const result = unwrapApiResponse(response)
+  return { ...result, query: view(result.query), nodes: (result.nodes || []).map(node), exceptions: (result.exceptions || []).map(exception), histories: (result.histories || []).map(history) }
+}
diff --git a/src/modules/port-schedules/api/platformContainerShippingNodes.ts b/src/modules/port-schedules/api/platformContainerShippingNodes.ts
new file mode 100644
index 00000000..01941fef
--- /dev/null
+++ b/src/modules/port-schedules/api/platformContainerShippingNodes.ts
@@ -0,0 +1,18 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import type { ContainerManualNodeRequest, ContainerShippingNodeDetail } from '../types'
+
+const basePath = '/platform/v1/container-shipping-nodes'
+
+function normalize(raw: ContainerShippingNodeDetail): ContainerShippingNodeDetail {
+  return { ...raw, containerBookingId: String(raw.containerBookingId), nodes: (raw.nodes || []).map((item) => ({ ...item, id: String(item.id), nodeSequence: Number(item.nodeSequence) })) }
+}
+
+export async function getContainerShippingNodes(containerBookingId: string): Promise<ContainerShippingNodeDetail> {
+  const response = await http.get<ApiEnvelope<ContainerShippingNodeDetail>, ApiEnvelope<ContainerShippingNodeDetail>>(`${basePath}/${encodeURIComponent(containerBookingId)}`)
+  return normalize(unwrapApiResponse(response))
+}
+
+export async function appendContainerShippingNode(containerBookingId: string, idempotencyKey: string, request: ContainerManualNodeRequest): Promise<ContainerShippingNodeDetail> {
+  const response = await http.post<ApiEnvelope<ContainerShippingNodeDetail>, ApiEnvelope<ContainerShippingNodeDetail>>(`${basePath}/${encodeURIComponent(containerBookingId)}`, request, { headers: { 'Idempotency-Key': idempotencyKey } })
+  return normalize(unwrapApiResponse(response))
+}
diff --git a/src/modules/port-schedules/api/platformPortSchedules.test.ts b/src/modules/port-schedules/api/platformPortSchedules.test.ts
new file mode 100644
index 00000000..20fc0643
--- /dev/null
+++ b/src/modules/port-schedules/api/platformPortSchedules.test.ts
@@ -0,0 +1,6 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import { createPortSchedule, listPortSchedules, updatePortSchedule } from './platformPortSchedules'
+vi.mock('@/shared/api/http', async () => { const actual = await vi.importActual<typeof import('@/shared/api/http')>('@/shared/api/http'); return { ...actual, http: { get: vi.fn(), post: vi.fn(), put: vi.fn() } } })
+const data = { customerId: '1', oceanBookingId: '2', sourceType: 'MANUAL', sourceName: '美森', sourceRef: 'web', vesselName: 'MATSON', voyageNo: 'V1', departurePortCode: 'CNSHA', destinationPortCode: 'USLAX', observedAt: '2026-08-11T10:00:00', expiresAt: '2026-08-14T10:00:00' }
+describe('platformPortSchedules', () => { beforeEach(() => vi.clearAllMocks()); it('normalizes long ids in pages', async () => { vi.mocked(http.get).mockResolvedValue({ code: '200', data: { records: [{ schedule: { ...data, id: 9, scheduleNo: 'PS1', customerId: 1, oceanBookingId: 2, version: '3' }, expired: false }], page: 1, size: 20, total: 1, pages: 1 } }); const result = await listPortSchedules({ page: 1, size: 20 }); expect(result.records[0]?.schedule).toMatchObject({ id: '9', customerId: '1', oceanBookingId: '2', version: 3 }) }); it('uses idempotency and expectedVersion for writes', async () => { vi.mocked(http.post).mockResolvedValue({ code: '200', data: { portSchedule: { schedule: { ...data, id: 9, scheduleNo: 'PS1', version: 0 }, expired: false }, histories: [] } }); vi.mocked(http.put).mockResolvedValue({ code: '200', data: { portSchedule: { schedule: { ...data, id: 9, scheduleNo: 'PS1', version: 2 }, expired: false }, histories: [] } }); await createPortSchedule(data); await updatePortSchedule('9', { expectedVersion: 1, data }); expect(vi.mocked(http.post).mock.calls[0]?.[2]).toMatchObject({ headers: { 'Idempotency-Key': expect.any(String) } }); expect(vi.mocked(http.put).mock.calls[0]?.[1]).toMatchObject({ expectedVersion: 1 }) }) })
diff --git a/src/modules/port-schedules/api/platformPortSchedules.ts b/src/modules/port-schedules/api/platformPortSchedules.ts
new file mode 100644
index 00000000..16d95d8c
--- /dev/null
+++ b/src/modules/port-schedules/api/platformPortSchedules.ts
@@ -0,0 +1,24 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import type { PortScheduleData, PortScheduleDetail, PortSchedulePage, PortScheduleQuery, PortScheduleResource, PortScheduleSaveRequest, PortScheduleView } from '../types'
+
+const basePath = '/platform/v1/port-schedules'
+const ids = ['id', 'customerId', 'oceanBookingId', 'containerBookingId'] as const
+function resource(raw: PortScheduleResource): PortScheduleResource {
+  const value = { ...raw } as PortScheduleResource & Record<string, unknown>
+  for (const key of ids) if (value[key] != null) value[key] = String(value[key])
+  value.version = Number(value.version ?? 0)
+  return value
+}
+function view(raw: PortScheduleView): PortScheduleView { return { ...raw, schedule: resource(raw.schedule) } }
+function detail(raw: PortScheduleDetail): PortScheduleDetail {
+  return { ...raw, portSchedule: view(raw.portSchedule), histories: (raw.histories || []).map((item) => ({ ...item, id: String(item.id) })) }
+}
+function idem() { return `port-schedule-${Date.now()}-${Math.random().toString(36).slice(2)}` }
+export async function listPortSchedules(query: PortScheduleQuery) {
+  const response = await http.get<ApiEnvelope<PortSchedulePage>, ApiEnvelope<PortSchedulePage>>(basePath, { params: query })
+  const data = unwrapApiResponse(response)
+  return { ...data, records: (data.records || []).map(view), page: Number(data.page), size: Number(data.size), total: Number(data.total), pages: Number(data.pages) }
+}
+export async function getPortSchedule(id: string) { const response = await http.get<ApiEnvelope<PortScheduleDetail>, ApiEnvelope<PortScheduleDetail>>(`${basePath}/${encodeURIComponent(id)}`); return detail(unwrapApiResponse(response)) }
+export async function createPortSchedule(data: PortScheduleData) { const response = await http.post<ApiEnvelope<PortScheduleDetail>, ApiEnvelope<PortScheduleDetail>>(basePath, { expectedVersion: 0, data }, { headers: { 'Idempotency-Key': idem() } }); return detail(unwrapApiResponse(response)) }
+export async function updatePortSchedule(id: string, request: PortScheduleSaveRequest) { const response = await http.put<ApiEnvelope<PortScheduleDetail>, ApiEnvelope<PortScheduleDetail>>(`${basePath}/${encodeURIComponent(id)}`, request, { headers: { 'Idempotency-Key': idem() } }); return detail(unwrapApiResponse(response)) }
diff --git a/src/modules/port-schedules/components/CarrierScheduleQueryPanel.behavior.test.ts b/src/modules/port-schedules/components/CarrierScheduleQueryPanel.behavior.test.ts
new file mode 100644
index 00000000..de85cf94
--- /dev/null
+++ b/src/modules/port-schedules/components/CarrierScheduleQueryPanel.behavior.test.ts
@@ -0,0 +1,293 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { flushPromises, mount } from '@vue/test-utils'
+import ElementPlus from 'element-plus'
+import { createPinia, setActivePinia } from 'pinia'
+import CarrierScheduleQueryPanel from './CarrierScheduleQueryPanel.vue'
+import { getCarrierScheduleQuery, listCarrierScheduleQueries } from '../api/platformCarrierScheduleQueries'
+import { appendContainerShippingNode, getContainerShippingNodes } from '../api/platformContainerShippingNodes'
+import { getPortSchedule } from '../api/platformPortSchedules'
+import { useAuthStore } from '@/core/auth/auth'
+import { ApiResponseError } from '@/shared/api/http'
+
+vi.mock('../api/platformCarrierScheduleQueries', () => ({
+  listCarrierScheduleQueries: vi.fn(),
+  getCarrierScheduleQuery: vi.fn(),
+}))
+vi.mock('../api/platformContainerShippingNodes', () => ({ getContainerShippingNodes: vi.fn(), appendContainerShippingNode: vi.fn() }))
+vi.mock('../api/platformPortSchedules', () => ({ getPortSchedule: vi.fn() }))
+
+const queryView = {
+  query: {
+    id: '11', queryNo: 'CSQ11', customerId: '1', oceanBookingId: '2', containerBookingId: '3',
+    carrierCode: 'COSCO', trackingType: 'CONTAINER_NO', trackingNo: 'CSNU1234567',
+    officialUrl: 'https://elines.coscoshipping.com/ebusiness/', accessMode: 'DYNAMIC_IFRAME',
+    status: 'MANUAL_REQUIRED' as const, triggerSource: 'OUTBOUND_CONFIRM',
+    latestActualNode: 'DEPARTED_WAREHOUSE' as const, latestActualAt: '2026-08-20T10:00:00',
+    lastErrorCode: 'DYNAMIC_IFRAME_REQUIRED', lastErrorMessage: '必须人工查询',
+    resultPortScheduleId: '21', version: 1,
+  },
+  expired: true,
+}
+
+describe('CarrierScheduleQueryPanel loading states', () => {
+  let pinia: ReturnType<typeof createPinia>
+  beforeEach(() => { vi.clearAllMocks(); pinia = createPinia(); setActivePinia(pinia); useAuthStore().permissions = ['platform:firstleg:port-schedule-query:manual']; vi.mocked(getContainerShippingNodes).mockResolvedValue({ containerBookingId: '3', currentNode: null, currentNodeAt: null, nodes: [] }) })
+
+  it('keeps list facts visible when history and linked schedule both fail', async () => {
+    vi.mocked(listCarrierScheduleQueries).mockResolvedValue({ records: [queryView], page: 1, size: 200, total: 1, pages: 1 })
+    vi.mocked(getCarrierScheduleQuery).mockRejectedValue(new Error('detail unavailable'))
+    vi.mocked(getPortSchedule).mockRejectedValue(new Error('schedule unavailable'))
+
+    const wrapper = mount(CarrierScheduleQueryPanel, { props: { oceanBookingId: '2', containerBookingId: '3' }, global: { plugins: [ElementPlus, pinia] } })
+    await flushPromises()
+
+    expect(listCarrierScheduleQueries).toHaveBeenCalledWith({ page: 1, size: 200, oceanBookingId: '2', containerBookingId: '3' })
+    expect(getCarrierScheduleQuery).toHaveBeenCalledWith('11')
+    expect(getPortSchedule).toHaveBeenCalledWith('21')
+    expect(wrapper.text()).toContain('CSQ11')
+    expect(wrapper.text()).toContain('标准节点与变更历史暂不可用')
+    expect(wrapper.text()).toContain('关联船期结果暂不可用')
+    expect(wrapper.text()).toContain('DYNAMIC_IFRAME_REQUIRED')
+  })
+
+  it('shows an explicit non-fabricated empty state and performs no detail reads', async () => {
+    vi.mocked(listCarrierScheduleQueries).mockResolvedValue({ records: [], page: 1, size: 200, total: 0, pages: 0 })
+    const wrapper = mount(CarrierScheduleQueryPanel, { props: { oceanBookingId: '2', warehouseTimeline: [{ eventType: 'PDA_COMPLETE_LOADING', detail: 'complete-key-technical', operatorName: '仓库员', occurredAt: '2026-08-20T08:00:00' }] }, global: { plugins: [ElementPlus, pinia] } })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('货柜履约轨迹')
+    expect(wrapper.text()).toContain('完成装柜')
+    expect(wrapper.text()).toContain('仓内操作')
+    expect(wrapper.text()).toContain('当前未开启跟踪任务')
+    expect(wrapper.findAll('.tracking-prompt')).toHaveLength(1)
+    expect(getCarrierScheduleQuery).not.toHaveBeenCalled()
+    expect(getPortSchedule).not.toHaveBeenCalled()
+  })
+
+  it('shows manual entry without creating a tracking task', async () => {
+    vi.mocked(listCarrierScheduleQueries).mockResolvedValue({ records: [], page: 1, size: 200, total: 0, pages: 0 })
+    const wrapper = mount(CarrierScheduleQueryPanel, { props: { oceanBookingId: '2', containerBookingId: '3' }, global: { plugins: [ElementPlus, pinia] } })
+    await flushPromises()
+
+    const button = wrapper.findAll('button').find((item) => item.text().includes('人工补录节点'))
+    expect(button).toBeTruthy()
+    await button!.trigger('click')
+    await flushPromises()
+
+    expect(getContainerShippingNodes).toHaveBeenCalledWith('3')
+    expect(wrapper.findComponent({ name: 'AppDialog' }).props('modelValue')).toBe(true)
+    const pickers = wrapper.findAllComponents({ name: 'ElDatePicker' })
+    expect(pickers).toHaveLength(2)
+    expect(pickers[0]!.props('modelValue')).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$/)
+    expect(pickers[1]!.props('modelValue')).toBe(pickers[0]!.props('modelValue'))
+  })
+
+  it('filters large no-op status batches, keeps real actions, deduplicates only adjacent explicit event keys and sorts newest first', async () => {
+    vi.mocked(listCarrierScheduleQueries).mockResolvedValue({ records: [], page: 1, size: 200, total: 0, pages: 0 })
+    const noops = Array.from({ length: 40 }, (_, index) => ({
+      eventType: 'STATUS_UPDATE', action: 'STATUS_UPDATE', fromStatus: 'EDITING', toStatus: 'EDITING',
+      detail: index % 2 ? null : '预装柜中→预装柜中', eventId: `2092438843630398${String(index).padStart(3, '0')}`,
+      operatorName: '系统', occurredAt: `2026-08-27T09:${String(index).padStart(2, '0')}:00`,
+    }))
+    const timeline = [
+      ...noops,
+      { eventType: 'STATUS_UPDATE', action: 'STATUS_UPDATE', fromStatus: 'EDITING', toStatus: 'LOADING', detail: null, eventId: '2092438843630399001', operatorName: '调度员', occurredAt: '2026-08-27T10:00:00' },
+      { eventType: 'STATUS_UPDATE', action: 'STATUS_UPDATE', fromStatus: 'LOADING', toStatus: 'LOADING', detail: null, changedFields: ['containerNo'], eventId: '2092438843630399002', operatorName: '调度员', occurredAt: '2026-08-27T10:01:00' },
+      { eventType: 'STATUS_UPDATE', action: 'PUSH_PRELOAD', fromStatus: 'EDITING', toStatus: 'EDITING', detail: null, eventId: '2092438843630399003', operatorName: '调度员', occurredAt: '2026-08-27T10:02:00' },
+      { eventType: 'PDA_BATCH', action: 'PDA_BATCH', fromStatus: 'LOADING', toStatus: 'LOADING', detail: '提交拣货结果', eventId: '2092438843630399004', operatorName: '仓库员', occurredAt: '2026-08-27T10:03:00' },
+      { eventType: 'PDA_BATCH', action: 'PDA_BATCH', fromStatus: 'LOADING', toStatus: 'LOADING', detail: '提交拣货结果', eventId: '2092438843630399004', operatorName: '仓库员', occurredAt: '2026-08-27T10:04:00' },
+      { eventType: 'STATUS_UPDATE', action: 'CONFIRM_PRELOAD', fromStatus: 'EDITING', toStatus: 'EDITING', detail: null, idempotencyKey: '2092438843630399005', operatorName: '复核员', occurredAt: '2026-08-27T10:05:00' },
+      { eventType: 'TRANSPORT_UPDATE', action: 'TRANSPORT_UPDATE', detail: '更新集装箱号', eventId: '2092438843630399006', operatorName: '操作员甲', occurredAt: '2026-08-27T10:06:00' },
+      { eventType: 'TRANSPORT_UPDATE', action: 'TRANSPORT_UPDATE', detail: '更新集装箱号', eventId: '2092438843630399007', operatorName: '操作员乙', occurredAt: '2026-08-27T10:07:00' },
+    ]
+    const wrapper = mount(CarrierScheduleQueryPanel, { props: { oceanBookingId: '2', warehouseTimeline: timeline }, global: { plugins: [ElementPlus, pinia] } })
+    await flushPromises()
+
+    expect(wrapper.find('.history-count').text()).toBe('仓内 7 条 · 共 7 条')
+    const rows = wrapper.findAll('.fulfillment-timeline li')
+    expect(rows).toHaveLength(7)
+    expect(rows[0]?.text()).toContain('操作员乙')
+    expect(rows[6]?.text()).toContain('预装柜中 → 拣货中')
+    expect(rows.filter((row) => row.text().includes('提交拣货结果'))).toHaveLength(1)
+    expect(wrapper.text()).toContain('推送预装清单')
+    expect(wrapper.text()).toContain('确认预装清单')
+    expect(wrapper.text()).toContain('业务字段已更新')
+    expect(wrapper.text()).not.toContain('2092438843630398000')
+    expect(rows.filter((row) => row.text().includes('更新集装箱号'))).toHaveLength(2)
+  })
+
+  it('falls back to the booking/container task when an automatic task has no linked port schedule', async () => {
+    vi.mocked(listCarrierScheduleQueries).mockResolvedValue({ records: [{ ...queryView, query: { ...queryView.query, resultPortScheduleId: null } }], page: 1, size: 200, total: 1, pages: 1 })
+    vi.mocked(getCarrierScheduleQuery).mockResolvedValue({ query: { ...queryView, query: { ...queryView.query, resultPortScheduleId: null } }, nodes: [], exceptions: [], histories: [] })
+    const wrapper = mount(CarrierScheduleQueryPanel, { props: { oceanBookingId: '2', containerBookingId: '3', portScheduleId: '99' }, global: { plugins: [ElementPlus, pinia] } })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('CSQ11')
+    expect(getCarrierScheduleQuery).toHaveBeenCalledWith('11')
+    expect(getPortSchedule).not.toHaveBeenCalled()
+  })
+
+  it('does not expose a circuit-breaker exception name stored by an earlier scheduler attempt', async () => {
+    const failed = { ...queryView.query, lastErrorCode: 'PROVIDER_CALL_FAILED', lastErrorMessage: 'NoFallbackAvailableException', resultPortScheduleId: null }
+    vi.mocked(listCarrierScheduleQueries).mockResolvedValue({ records: [{ ...queryView, query: failed }], page: 1, size: 200, total: 1, pages: 1 })
+    vi.mocked(getCarrierScheduleQuery).mockResolvedValue({ query: { ...queryView, query: failed }, nodes: [], exceptions: [], histories: [] })
+    const wrapper = mount(CarrierScheduleQueryPanel, { props: { containerBookingId: '3' }, global: { plugins: [ElementPlus, pinia] } })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('轨迹供应商暂时不可用，请稍后重试或人工补录节点。')
+    expect(wrapper.text()).not.toContain('NoFallbackAvailableException')
+  })
+
+  it('renders canonical node location, actual time, source and empty-return stop facts from detail DTO', async () => {
+    vi.mocked(listCarrierScheduleQueries).mockResolvedValue({ records: [{ ...queryView, query: { ...queryView.query, status: 'STOPPED', latestActualNode: 'EMPTY_RETURNED', latestActualAt: '2026-08-20T17:45:00', stoppedAt: '2026-08-20T18:00:00', stopReason: '已还柜', resultPortScheduleId: null }, expired: false }], page: 1, size: 200, total: 1, pages: 1 })
+    vi.mocked(getCarrierScheduleQuery).mockResolvedValue({
+      query: { query: { ...queryView.query, status: 'STOPPED', latestActualNode: 'EMPTY_RETURNED', latestActualAt: '2026-08-20T17:45:00', stoppedAt: '2026-08-20T18:00:00', stopReason: '已还柜', resultPortScheduleId: null }, expired: false },
+      nodes: [{ id: '31', providerCode: 'COSCO', providerEventId: 'provider-event-31', providerNodeCode: 'EMPTY_RETURN', standardNode: 'EMPTY_RETURNED', nodeSequence: 100, observedAt: '2026-08-20T17:50:00', estimatedAt: null, actualAt: '2026-08-20T17:45:00', locationCode: 'USLAX', locationName: 'Los Angeles', sourceReference: 'provider-event-31', rawPayloadHash: 'a'.repeat(64), createdAt: '2026-08-20T17:51:00' }],
+      exceptions: [],
+      histories: [{ id: '41', action: 'STOP', fromVersion: 4, toVersion: 5, reason: '已还柜', operatorId: null, operatorName: '系统', createdAt: '2026-08-20T18:00:00' }],
+    })
+    const wrapper = mount(CarrierScheduleQueryPanel, { props: { oceanBookingId: '2', containerBookingId: '3' }, global: { plugins: [ElementPlus, pinia] } })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('已停止 · 已还柜')
+    expect(wrapper.text()).toContain('USLAX · Los Angeles')
+    expect(wrapper.text()).toContain('2026-08-20 17:45')
+    expect(wrapper.text()).toContain('COSCO')
+    expect(wrapper.text()).toContain('已还柜')
+  })
+
+  it('labels forecast-only facts as estimated without promoting latest actual progress', async () => {
+    vi.mocked(listCarrierScheduleQueries).mockResolvedValue({ records: [{ ...queryView, query: { ...queryView.query, latestActualNode: 'DEPARTED_WAREHOUSE', latestActualAt: '2026-08-20T08:55:00', resultPortScheduleId: null }, expired: false }], page: 1, size: 200, total: 1, pages: 1 })
+    vi.mocked(getCarrierScheduleQuery).mockResolvedValue({
+      query: { query: { ...queryView.query, latestActualNode: 'DEPARTED_WAREHOUSE', latestActualAt: '2026-08-20T08:55:00', resultPortScheduleId: null }, expired: false },
+      nodes: [
+        { id: '11', providerCode: 'FIRSTLEG', providerEventId: 'outbound-11', providerNodeCode: 'OUTBOUND_CONFIRM', standardNode: 'DEPARTED_WAREHOUSE', nodeSequence: 10, observedAt: '2026-08-20T09:00:00', estimatedAt: null, actualAt: '2026-08-20T08:55:00', locationCode: null, locationName: null, sourceReference: null, rawPayloadHash: 'b'.repeat(64), createdAt: '2026-08-20T09:00:01' },
+        { id: '12', providerCode: 'HEDE', providerEventId: 'hede-estimate-12', providerNodeCode: '预抵', standardNode: 'ARRIVED_DESTINATION_PORT', nodeSequence: 60, observedAt: '2026-08-20T10:00:00', estimatedAt: '2026-08-28T12:00:00', actualAt: null, locationCode: 'USLAX', locationName: 'Los Angeles', sourceReference: 'hede-estimate', rawPayloadHash: 'c'.repeat(64), createdAt: '2026-08-20T10:00:01' },
+      ], exceptions: [{ id: '51', providerCode: 'HEDE', providerEventId: 'hold-51', providerStatus: 'Customs hold', exceptionCode: 'CUSTOMS_HOLD', active: true, observedAt: '2026-08-20T11:00:00', locationCode: 'USLAX', locationName: 'Los Angeles', sourceReference: 'hede-hold', rawPayloadHash: 'd'.repeat(64), createdAt: '2026-08-20T11:00:01' }], histories: [],
+    })
+    const wrapper = mount(CarrierScheduleQueryPanel, { props: { oceanBookingId: '2', containerBookingId: '3' }, global: { plugins: [ElementPlus, pinia] } })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('最新实际节点已离开国内仓库')
+    expect(wrapper.text()).toContain('预计 2026-08-28 12:00')
+    expect(wrapper.text()).not.toContain('最新实际节点船舶已到目的港')
+    expect(wrapper.text()).toContain('异常')
+    expect(wrapper.text()).toContain('海关扣留 · 发生')
+    expect(wrapper.text()).toContain('Customs hold')
+    expect(wrapper.text()).toContain('船运跟踪 · HEDE · hede-hold')
+  })
+
+  it('merges warehouse, actual, estimated, manual and exception facts with stable ordering and deduplication', async () => {
+    vi.mocked(listCarrierScheduleQueries).mockResolvedValue({ records: [{ ...queryView, query: { ...queryView.query, resultPortScheduleId: null }, expired: false }], page: 1, size: 200, total: 1, pages: 1 })
+    const actual = { id: '61', providerCode: 'COSCO', providerEventId: 'actual-61', providerNodeCode: 'LOAD', standardNode: 'LOADED_ON_VESSEL' as const, nodeSequence: 30, observedAt: '2026-08-21T10:05:00', estimatedAt: null, actualAt: '2026-08-21T10:00:00', locationCode: 'CNNGB', locationName: '宁波港', sourceReference: 'actual-source', rawPayloadHash: 'e'.repeat(64), createdAt: '2026-08-21T10:06:00' }
+    const estimated = { id: '62', providerCode: 'COSCO', providerEventId: 'estimate-62', providerNodeCode: 'ETA', standardNode: 'ARRIVED_DESTINATION_PORT' as const, nodeSequence: 60, observedAt: '2026-08-20T10:00:00', estimatedAt: '2026-08-21T10:00:00', actualAt: null, locationCode: 'USLAX', locationName: 'Los Angeles', sourceReference: 'estimate-source', rawPayloadHash: 'f'.repeat(64), createdAt: '2026-08-20T10:01:00' }
+    const manual = { id: '63', providerCode: 'MANUAL', providerEventId: 'manual-63', providerNodeCode: 'TRANSIT', standardNode: 'IN_TRANSIT' as const, nodeSequence: 50, observedAt: '2026-08-21T09:00:00', estimatedAt: null, actualAt: '2026-08-21T09:00:00', locationCode: null, locationName: '太平洋', sourceReference: '人工核验', rawPayloadHash: 'g'.repeat(64), createdAt: '2026-08-21T09:01:00' }
+    vi.mocked(getCarrierScheduleQuery).mockResolvedValue({ query: { ...queryView, query: { ...queryView.query, resultPortScheduleId: null }, expired: false }, nodes: [estimated, actual, { ...actual, id: '64' }, manual], exceptions: [{ id: '65', providerCode: 'COSCO', providerEventId: 'hold-65', providerStatus: 'Terminal hold', exceptionCode: 'TERMINAL_HOLD', active: true, observedAt: '2026-08-21T08:30:00', locationCode: 'USLAX', locationName: 'Los Angeles', sourceReference: 'hold-source', rawPayloadHash: 'h'.repeat(64), createdAt: '2026-08-21T08:31:00' }], histories: [{ id: '66', action: 'MANUAL_NODE', fromVersion: 1, toVersion: 2, reason: '人工核验', operatorId: '1', operatorName: '管理员', createdAt: '2026-08-21T09:01:00' }] })
+    const wrapper = mount(CarrierScheduleQueryPanel, { props: { oceanBookingId: '2', warehouseTimeline: [{ eventType: 'PDA_COMPLETE_LOADING', detail: '装柜完成', operatorName: '仓库员', occurredAt: '2026-08-20T08:00:00' }] }, global: { plugins: [ElementPlus, pinia] } })
+    await flushPromises()
+    const rows = wrapper.findAll('.fulfillment-timeline li')
+    expect(rows.filter((row) => row.text().includes('已装船'))).toHaveLength(1)
+    expect(rows[0]?.text()).toContain('已装船')
+    expect(rows[1]?.text()).toContain('预计 2026-08-21 10:00')
+    expect(rows[1]?.text()).toContain('船运节点')
+    expect(rows.map((row) => row.text()).join('|')).toContain('人工补录')
+    expect(rows.map((row) => row.text()).join('|')).toContain('码头扣留 · 发生')
+    expect(wrapper.text()).toContain('查询任务摘要、异常与变更历史')
+    expect(wrapper.text()).toContain('人工补录标准节点')
+  })
+
+  it('shows only the latest duplicate actual node in the primary trajectory and keeps the older fact expandable', async () => {
+    const task = { ...queryView.query, latestActualNode: 'PICKED_UP' as const, latestActualAt: '2026-09-24T10:00:00', resultPortScheduleId: null }
+    const older = { id: 'pickup-1', providerCode: 'MANUAL', providerEventId: 'pickup-old', providerNodeCode: 'PICKED_UP', standardNode: 'PICKED_UP' as const, nodeSequence: 90, observedAt: '2026-09-09T10:05:00', estimatedAt: null, actualAt: '2026-09-09T10:00:00', locationCode: 'USLAX', locationName: 'Los Angeles', sourceReference: '人工提柜-旧', rawPayloadHash: '1'.repeat(64), createdAt: '2026-09-09T10:06:00' }
+    const latest = { ...older, id: 'pickup-2', providerEventId: 'pickup-latest', observedAt: '2026-09-24T10:05:00', actualAt: '2026-09-24T10:00:00', sourceReference: '人工提柜-最新', rawPayloadHash: '2'.repeat(64), createdAt: '2026-09-24T10:06:00' }
+    vi.mocked(listCarrierScheduleQueries).mockResolvedValue({ records: [{ ...queryView, query: task, expired: false }], page: 1, size: 200, total: 1, pages: 1 })
+    vi.mocked(getCarrierScheduleQuery).mockResolvedValue({ query: { ...queryView, query: task, expired: false }, nodes: [older, latest], exceptions: [], histories: [] })
+    const wrapper = mount(CarrierScheduleQueryPanel, { props: { oceanBookingId: '2', containerBookingId: '3' }, global: { plugins: [ElementPlus, pinia] } })
+    await flushPromises()
+
+    const primaryPickupRows = wrapper.findAll('.fulfillment-timeline li').filter((row) => row.text().includes('已提柜'))
+    expect(primaryPickupRows).toHaveLength(1)
+    expect(primaryPickupRows[0]!.text()).toContain('2026-09-24 10:00')
+    expect(primaryPickupRows[0]!.text()).not.toContain('2026-09-09 10:00')
+    expect(wrapper.find('.duplicate-node-history').text()).toContain('历史重复实际节点（1）')
+    expect(wrapper.find('.duplicate-node-history').text()).toContain('2026-09-09 10:00')
+    expect(wrapper.find('.duplicate-node-history').text()).toContain('人工提柜-旧')
+  })
+
+  it('allows correcting the current node without sequence restrictions', async () => {
+    const task = { ...queryView.query, latestActualNode: 'PICKED_UP' as const, latestActualAt: '2026-09-24T10:00:00', resultPortScheduleId: null }
+    vi.mocked(listCarrierScheduleQueries).mockResolvedValue({ records: [{ ...queryView, query: task, expired: false }], page: 1, size: 200, total: 1, pages: 1 })
+    vi.mocked(getCarrierScheduleQuery).mockResolvedValue({ query: { ...queryView, query: task, expired: false }, nodes: [], exceptions: [], histories: [] })
+    const wrapper = mount(CarrierScheduleQueryPanel, { props: { oceanBookingId: '2', containerBookingId: '3' }, global: { plugins: [ElementPlus, pinia] } })
+    await flushPromises()
+
+    await wrapper.findAll('button').find((button) => button.text().includes('人工补录节点'))!.trigger('click')
+    const pickers = wrapper.findAllComponents({ name: 'ElDatePicker' })
+    pickers[1]!.vm.$emit('update:modelValue', '2026-09-25T10:00:00')
+    await flushPromises()
+    const options = wrapper.findAllComponents({ name: 'ElOption' })
+    expect(options.find((option) => option.props('value') === 'DEPARTED_WAREHOUSE')!.props('disabled')).toBeFalsy()
+    expect(options.find((option) => option.props('value') === 'PICKED_UP')!.props('disabled')).toBeFalsy()
+    expect(options.find((option) => option.props('value') === 'EMPTY_RETURNED')!.props('disabled')).toBe(false)
+
+    wrapper.findComponent({ name: 'ElSelect' }).vm.$emit('update:modelValue', 'PICKED_UP')
+    wrapper.findAllComponents({ name: 'ElInput' }).find((input) => input.props('type') === 'textarea')!.vm.$emit('update:modelValue', '重复提柜事实')
+    await wrapper.findComponent({ name: 'AppDialog' }).vm.$emit('confirm'); await flushPromises()
+    expect(appendContainerShippingNode).toHaveBeenCalled()
+  })
+
+  it('hides the manual action without the frozen permission while retaining fulfillment facts', async () => {
+    useAuthStore().permissions = []
+    vi.mocked(listCarrierScheduleQueries).mockResolvedValue({ records: [{ ...queryView, query: { ...queryView.query, resultPortScheduleId: null }, expired: false }], page: 1, size: 200, total: 1, pages: 1 })
+    vi.mocked(getCarrierScheduleQuery).mockResolvedValue({ query: { ...queryView, query: { ...queryView.query, resultPortScheduleId: null }, expired: false }, nodes: [], exceptions: [], histories: [] })
+    const wrapper = mount(CarrierScheduleQueryPanel, { props: { oceanBookingId: '2', warehouseTimeline: [{ eventType: 'PDA_BATCH', detail: '拣货结果已提交', operatorName: '仓库员', occurredAt: '2026-08-20T07:00:00' }] }, global: { plugins: [ElementPlus, pinia] } })
+    await flushPromises()
+    expect(wrapper.text()).toContain('提交拣货结果')
+    expect(wrapper.findAll('button').some((button) => button.text().includes('人工补录节点'))).toBe(false)
+  })
+
+  it('keeps the form context and dialog-scoped idempotency key when a conflict is retried', async () => {
+    vi.mocked(listCarrierScheduleQueries).mockResolvedValue({ records: [{ ...queryView, query: { ...queryView.query, resultPortScheduleId: null }, expired: false }], page: 1, size: 200, total: 1, pages: 1 })
+    const currentDetail = { containerBookingId: '3', currentNode: null, currentNodeAt: null, nodes: [] }
+    vi.mocked(getCarrierScheduleQuery).mockResolvedValue({ query: { ...queryView, query: { ...queryView.query, resultPortScheduleId: null } }, nodes: [], exceptions: [], histories: [] })
+    vi.mocked(appendContainerShippingNode)
+      .mockRejectedValueOnce(new ApiResponseError('版本冲突', 'A0409', 409, null, 'req-409', 'trace-409'))
+      .mockResolvedValueOnce(currentDetail)
+    const wrapper = mount(CarrierScheduleQueryPanel, { props: { oceanBookingId: '2', containerBookingId: '3' }, global: { plugins: [ElementPlus, pinia] } })
+    await flushPromises()
+
+    await wrapper.findAll('button').find((button) => button.text().includes('人工补录节点'))!.trigger('click')
+    const select = wrapper.findComponent({ name: 'ElSelect' }); select.vm.$emit('update:modelValue', 'IN_TRANSIT')
+    const pickers = wrapper.findAllComponents({ name: 'ElDatePicker' }); pickers[0]!.vm.$emit('update:modelValue', '2026-08-22T10:00:00'); pickers[1]!.vm.$emit('update:modelValue', '')
+    const inputs = wrapper.findAllComponents({ name: 'ElInput' })
+    inputs.find((input) => input.props('placeholder') === '可选，如 USLAX')!.vm.$emit('update:modelValue', 'PACIFIC')
+    inputs.find((input) => String(input.props('maxlength')) === '128')!.vm.$emit('update:modelValue', 'Pacific Ocean')
+    inputs.find((input) => input.props('type') === 'textarea')!.vm.$emit('update:modelValue', '船司官网人工核验')
+    await wrapper.findComponent({ name: 'AppDialog' }).vm.$emit('confirm'); await flushPromises()
+    expect(wrapper.text()).toContain('补录未成功，已保留当前填写内容')
+    expect(wrapper.text()).toContain('req-409'); expect(wrapper.text()).toContain('trace-409')
+    await wrapper.findComponent({ name: 'AppDialog' }).vm.$emit('confirm'); await flushPromises()
+
+    const first = vi.mocked(appendContainerShippingNode).mock.calls[0]!
+    const second = vi.mocked(appendContainerShippingNode).mock.calls[1]!
+    expect(first[1]).toBeTruthy(); expect(second[1]).toBe(first[1])
+    expect(second[2]).toEqual(first[2])
+    expect(second[2]).toMatchObject({ standardNode: 'IN_TRANSIT', estimatedAt: '2026-08-22T10:00:00', actualAt: null, locationCode: 'PACIFIC', locationName: 'Pacific Ocean', reason: '船司官网人工核验', observedAt: expect.any(String) })
+  })
+
+  it('requires an estimated or actual time before calling the manual-node adapter', async () => {
+    vi.mocked(listCarrierScheduleQueries).mockResolvedValue({ records: [{ ...queryView, query: { ...queryView.query, resultPortScheduleId: null }, expired: false }], page: 1, size: 200, total: 1, pages: 1 })
+    vi.mocked(getCarrierScheduleQuery).mockResolvedValue({ query: { ...queryView, query: { ...queryView.query, resultPortScheduleId: null } }, nodes: [], exceptions: [], histories: [] })
+    const wrapper = mount(CarrierScheduleQueryPanel, { props: { oceanBookingId: '2', containerBookingId: '3' }, global: { plugins: [ElementPlus, pinia] } })
+    await flushPromises()
+
+    await wrapper.findAll('button').find((button) => button.text().includes('人工补录节点'))!.trigger('click')
+    wrapper.findComponent({ name: 'ElSelect' }).vm.$emit('update:modelValue', 'PICKUP_READY')
+    for (const picker of wrapper.findAllComponents({ name: 'ElDatePicker' })) picker.vm.$emit('update:modelValue', '')
+    wrapper.findAllComponents({ name: 'ElInput' }).find((input) => input.props('type') === 'textarea')!.vm.$emit('update:modelValue', '人工核验可提柜')
+    await wrapper.findComponent({ name: 'AppDialog' }).vm.$emit('confirm'); await flushPromises()
+
+    expect(wrapper.text()).toContain('预计时间和实际时间至少填写一项')
+    expect(appendContainerShippingNode).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/modules/port-schedules/components/CarrierScheduleQueryPanel.test.ts b/src/modules/port-schedules/components/CarrierScheduleQueryPanel.test.ts
new file mode 100644
index 00000000..4882fd9f
--- /dev/null
+++ b/src/modules/port-schedules/components/CarrierScheduleQueryPanel.test.ts
@@ -0,0 +1,86 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/port-schedules/components/CarrierScheduleQueryPanel.vue'), 'utf8')
+const apiSource = readFileSync(resolve(process.cwd(), 'src/modules/port-schedules/api/platformCarrierScheduleQueries.ts'), 'utf8')
+
+describe('CarrierScheduleQueryPanel', () => {
+  it('uses the existing relation filters and never creates or executes polling tasks', () => {
+    expect(source).toContain('listCarrierScheduleQueries({ page: 1, size: 200')
+    expect(source).toContain('oceanBookingId: props.oceanBookingId')
+    expect(source).toContain('containerBookingId: props.containerBookingId')
+    expect(source).not.toContain('createCarrierSchedule')
+    expect(source).not.toContain(['attempt', 'CarrierSchedule'].join(''))
+  })
+
+  it('shows source, observation/update times, history, failures and expiry truthfully', () => {
+    expect(source).toContain('最新来源')
+    expect(source).toContain('观测时间')
+    expect(source).toContain('来源参考')
+    expect(source).toContain('providerCode')
+    expect(source).toContain('sourceReference')
+    expect(source).toContain('实际发生时间')
+    expect(source).toContain('变更历史')
+    expect(source).toContain('query?.lastErrorMessage')
+    expect(source).toContain('query.lastErrorCode')
+    expect(source).toContain("queryView?.expired ? '结果已过期' : '结果有效'")
+  })
+
+  it('keeps query-history and linked-schedule partial failures independently visible', () => {
+    expect(source).toContain('queryDetailError')
+    expect(source).toContain('scheduleError')
+    expect(source).toContain('标准节点与变更历史暂不可用')
+    expect(source).toContain('关联船期结果暂不可用')
+  })
+
+  it('shows all ten canonical nodes and stops only on actual empty return', () => {
+    for (const node of ['DEPARTED_WAREHOUSE', 'AT_ORIGIN_PORT', 'LOADED_ON_VESSEL', 'DEPARTED_ORIGIN_PORT', 'IN_TRANSIT', 'ARRIVED_DESTINATION_PORT', 'DISCHARGED_FROM_VESSEL', 'PICKUP_READY', 'PICKED_UP', 'EMPTY_RETURNED']) expect(source).toContain(node)
+    expect(source).not.toMatch(new RegExp(`\\b${['ARR', 'IVED'].join('')}:`))
+    expect(source).toContain("latestActualNode === 'EMPTY_RETURNED'")
+    expect(source).toContain("'已停止 · 已还柜'")
+    expect(source).toContain('当前未开启跟踪任务')
+    expect(source).not.toContain('/' + 'scheduler')
+    expect(source).not.toContain('/' + 'attempts')
+  })
+
+  it('uses a compact no-task state without the large empty illustration', () => {
+    expect(source).toContain('class="tracking-prompt"')
+    expect(source).not.toContain('<el-empty v-else-if="!query"')
+    expect(source).toContain('当前未开启跟踪任务')
+  })
+
+  it('keeps estimated facts labelled and separate from actual progress', () => {
+    expect(source).toContain("actual ? `实际")
+    expect(source).toContain("item.estimatedAt ? `预计")
+    expect(source).toContain('latestActualNode')
+    expect(source).toContain('item.actualAt')
+  })
+
+  it('keeps historical immutable facts while allowing current-node correction', () => {
+    expect(source).not.toContain('isManualActualNodeAllowed')
+    expect(source).toContain('primaryNodeFacts')
+    expect(source).toContain('supersededActualNodes')
+    expect(source).toContain('历史重复实际节点')
+  })
+
+  it('uses the frozen manual-node permission and keeps exceptions separate', () => {
+    expect(source).toContain("access.can('platform:firstleg:port-schedule-query:manual')")
+    expect(source).toContain('appendContainerShippingNode')
+    expect(source).toContain('manualIdempotencyKey')
+    expect(source).toContain("type: '异常'")
+    expect(source).toContain('船运跟踪')
+    expect(source).toContain('item.providerStatus')
+    expect(source).not.toContain('/' + 'manual-results')
+  })
+
+  it('keeps retired progress fields and forbidden write endpoints out of the panel and adapter', () => {
+    const productionSource = `${source}\n${apiSource}`
+    expect(productionSource).not.toContain(['latest', 'StandardNode'].join(''))
+    expect(productionSource).not.toContain(['latest', 'NodeObservedAt'].join(''))
+    expect(productionSource).not.toContain('/' + 'attempts')
+    expect(productionSource).not.toContain('/' + 'manual-results')
+    expect(productionSource).not.toContain('/' + 'scheduler')
+    expect(apiSource).toContain('/manual-nodes')
+  })
+})
diff --git a/src/modules/port-schedules/components/CarrierScheduleQueryPanel.vue b/src/modules/port-schedules/components/CarrierScheduleQueryPanel.vue
new file mode 100644
index 00000000..7de6de30
--- /dev/null
+++ b/src/modules/port-schedules/components/CarrierScheduleQueryPanel.vue
@@ -0,0 +1,290 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, reactive, ref, watch } from 'vue'
+import { Plus } from '@lucide/vue'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { getCarrierScheduleQuery, listCarrierScheduleQueries } from '../api/platformCarrierScheduleQueries'
+import { appendContainerShippingNode, getContainerShippingNodes } from '../api/platformContainerShippingNodes'
+import { getPortSchedule } from '../api/platformPortSchedules'
+import type { CarrierScheduleExceptionFact, CarrierScheduleNodeFact, CarrierScheduleQueryDetail, CarrierScheduleQueryView, CarrierScheduleStandardNode, ContainerManualNodeRequest, ContainerShippingNodeDetail, PortScheduleView } from '../types'
+
+type WarehouseTimelineEntry = {
+  id?: string | null; eventId?: string | null; idempotencyKey?: string | null
+  eventType: string; action?: string | null; fromStatus?: string | null; toStatus?: string | null
+  detail?: string | null; summary?: string | null; changeSummary?: string | null; reason?: string | null
+  changedFields?: unknown; fieldChanges?: unknown; changes?: unknown
+  operatorName?: string | null; occurredAt?: string | null
+}
+type FulfillmentEvent = { key: string; time: string; type: '仓内操作' | '确认离仓' | '船运节点' | '人工补录' | '异常'; title: string; summary: string; source: string; actual: boolean }
+const props = defineProps<{ dense?: boolean; oceanBookingId?: string | null; containerBookingId?: string | null; portScheduleId?: string | null; warehouseTimeline?: WarehouseTimelineEntry[] }>()
+const access = useAccessPreviewStore()
+const loading = ref(false)
+const error = ref<ApiErrorDetails | null>(null)
+const queryDetailError = ref<ApiErrorDetails | null>(null)
+const scheduleError = ref<ApiErrorDetails | null>(null)
+const selected = ref<CarrierScheduleQueryView | null>(null)
+const detail = ref<CarrierScheduleQueryDetail | null>(null)
+const containerNodes = ref<ContainerShippingNodeDetail | null>(null)
+const latestSchedule = ref<PortScheduleView | null>(null)
+const manualDialogOpen = ref(false)
+const manualIdempotencyKey = ref('')
+const manualObservedAt = ref('')
+const manualSaving = ref(false)
+const manualError = ref<ApiErrorDetails | null>(null)
+const manualValidationError = ref('')
+const manualForm = reactive({ standardNode: '' as CarrierScheduleStandardNode | '', estimatedAt: '', actualAt: '', locationCode: '', locationName: '', reason: '' })
+
+const query = computed(() => detail.value?.query.query || selected.value?.query || null)
+const queryView = computed(() => detail.value?.query || selected.value)
+const statusText = computed(() => {
+  if (!query.value) return '未建立'
+  if (query.value.status === 'STOPPED' && query.value.latestActualNode === 'EMPTY_RETURNED' && query.value.latestActualAt) return '已停止 · 已还柜'
+  if (query.value.status === 'STOPPED') return '任务已停止'
+  return ({ READY: '运行中', MANUAL_REQUIRED: '待人工处理' } as Record<string, string>)[query.value.status] || query.value.status
+})
+const statusType = computed<'success' | 'warning' | 'danger' | 'info'>(() => {
+  if (query.value?.status === 'STOPPED') return 'info'
+  if (queryView.value?.expired || query.value?.status === 'MANUAL_REQUIRED') return 'danger'
+  return 'warning'
+})
+const nodes = computed(() => containerNodes.value?.nodes?.length ? containerNodes.value.nodes : detail.value?.nodes || [])
+const exceptions = computed(() => [...(detail.value?.exceptions || [])].reverse())
+const latestActualNodeFact = computed(() => [...nodes.value].reverse().find((item) => item.standardNode === query.value?.latestActualNode && item.actualAt === query.value?.latestActualAt)
+  || [...nodes.value].reverse().find((item) => item.standardNode === query.value?.latestActualNode && item.actualAt)
+  || null)
+const latestSource = computed(() => latestActualNodeFact.value?.providerCode || latestSchedule.value?.schedule.sourceName || query.value?.carrierCode || '—')
+const sourceReference = computed(() => latestActualNodeFact.value?.sourceReference || latestSchedule.value?.schedule.sourceRef || query.value?.officialUrl || '—')
+const latestObservation = computed(() => latestActualNodeFact.value?.observedAt || null)
+const histories = computed(() => [...(detail.value?.histories || [])].reverse())
+const standardNodes: CarrierScheduleStandardNode[] = ['DEPARTED_WAREHOUSE', 'AT_ORIGIN_PORT', 'LOADED_ON_VESSEL', 'DEPARTED_ORIGIN_PORT', 'IN_TRANSIT', 'ARRIVED_DESTINATION_PORT', 'DISCHARGED_FROM_VESSEL', 'PICKUP_READY', 'PICKED_UP', 'EMPTY_RETURNED']
+
+function compareActualFacts(left: CarrierScheduleNodeFact, right: CarrierScheduleNodeFact) {
+  for (const field of ['actualAt', 'observedAt', 'createdAt'] as const) {
+    const compared = String(left[field] || '').localeCompare(String(right[field] || ''))
+    if (compared) return compared
+  }
+  return left.id.localeCompare(right.id)
+}
+const latestActualFactsByNode = computed(() => {
+  const result = new Map<CarrierScheduleStandardNode, CarrierScheduleNodeFact>()
+  for (const item of nodes.value) {
+    if (!item.actualAt) continue
+    const current = result.get(item.standardNode)
+    if (!current || compareActualFacts(item, current) > 0) result.set(item.standardNode, item)
+  }
+  return result
+})
+const supersededActualNodes = computed(() => nodes.value
+  .filter((item) => item.actualAt && latestActualFactsByNode.value.get(item.standardNode)?.id !== item.id)
+  .sort((left, right) => compareActualFacts(right, left)))
+const primaryNodeFacts = computed(() => nodes.value.filter((item) => !item.actualAt || latestActualFactsByNode.value.get(item.standardNode)?.id === item.id))
+
+function formatTime(value?: string | null) { return value ? value.replace('T', ' ').slice(0, 16) : '—' }
+function trackingTypeText(value: string) { return ({ BOOKING_NO: '订舱号', BILL_OF_LADING: '提单号', CONTAINER_NO: '集装箱号' } as Record<string, string>)[value] || value }
+function triggerSourceText(value?: string | null) { return ({ OUTBOUND_CONFIRM: '国内出仓确认自动建立', MANUAL: '平台人工建立' } as Record<string, string>)[value || ''] || value || '—' }
+function nodeText(value?: CarrierScheduleStandardNode | null) { return ({ DEPARTED_WAREHOUSE: '已离开国内仓库', AT_ORIGIN_PORT: '重箱已进入起运港', LOADED_ON_VESSEL: '已装船', DEPARTED_ORIGIN_PORT: '船舶已离开起运港', IN_TRANSIT: '海运途中', ARRIVED_DESTINATION_PORT: '船舶已到目的港', DISCHARGED_FROM_VESSEL: '已卸船、未清关', PICKUP_READY: '已清关、可提柜', PICKED_UP: '已提柜', EMPTY_RETURNED: '已还柜' } as Record<string, string>)[value || ''] || value || '—' }
+function nodeLocation(item?: CarrierScheduleNodeFact | null) { return item ? [item.locationCode, item.locationName].filter(Boolean).join(' · ') || '—' : '—' }
+function exceptionLocation(item: CarrierScheduleExceptionFact) { return [item.locationCode, item.locationName].filter(Boolean).join(' · ') || '—' }
+function nodeTimeText(item: CarrierScheduleNodeFact) { return item.actualAt ? `实际 ${formatTime(item.actualAt)}` : item.estimatedAt ? `预计 ${formatTime(item.estimatedAt)}` : `观测 ${formatTime(item.observedAt)}` }
+function exceptionText(value: CarrierScheduleExceptionFact['exceptionCode']) { return ({ CUSTOMS_HOLD: '海关扣留', TERMINAL_HOLD: '码头扣留', DOCUMENT_HOLD: '单证扣留', UNKNOWN_HOLD: '其他扣留' } as Record<string, string>)[value] || value }
+function providerErrorText(value?: string | null) {
+  const message = nonBlank(value)
+  if (!message) return '自动查询暂不可用，需要人工补充可靠结果。'
+  if (/(?:NoFallbackAvailableException|FeignException|ConnectException|SocketTimeoutException)/i.test(message)) {
+    return '轨迹供应商暂时不可用，请稍后重试或人工补录节点。'
+  }
+  return message
+}
+function historyText(action: string) { return ({ AUTO_CREATE: '国内出仓自动建任务', CREATE: '人工建立查询任务', NODE_OBSERVED: '记录标准节点', PROVIDER_QUERY: '船司查询', MANUAL_NODE: '人工补录标准节点', STOP: '停止查询' } as Record<string, string>)[action] || action }
+function warehouseEventText(value: string) { return ({ STATUS_UPDATE: '状态更新', PUSH_PRELOAD: '推送预装清单', CONFIRM_PRELOAD: '确认预装清单', TRANSPORT_UPDATE: '更新运输信息', PDA_CLAIM: '领取 PDA 任务', PDA_BATCH: '提交拣货结果', PDA_COMPLETE_LOADING: '完成装柜' } as Record<string, string>)[value] || value || '状态更新' }
+function nonBlank(value: unknown) { return typeof value === 'string' ? value.trim() : '' }
+function hasStructuredChanges(value: unknown) {
+  if (Array.isArray(value)) return value.length > 0
+  if (value && typeof value === 'object') return Object.keys(value as Record<string, unknown>).length > 0
+  return Boolean(nonBlank(value))
+}
+function statusLabel(value?: string | null) {
+  return ({ WAIT_LOADING: '待装柜', EDITING: '预装柜中', LOADING: '拣货中', COMPLETED: '装柜完成' } as Record<string, string>)[value || ''] || nonBlank(value)
+}
+function isStatusEcho(detail: string, fromStatus?: string | null, toStatus?: string | null) {
+  const from = nonBlank(fromStatus); const to = nonBlank(toStatus)
+  if (!from || !to) return false
+  const compact = detail.replace(/\s+/g, '')
+  return [[from, to], [statusLabel(from), statusLabel(to)]].some(([left, right]) =>
+    [`${left}→${right}`, `${left}->${right}`].includes(compact))
+}
+function warehouseAction(entry: WarehouseTimelineEntry) { return nonBlank(entry.action) || nonBlank(entry.eventType) }
+function hasEffectiveWarehouseChange(entry: WarehouseTimelineEntry) {
+  if (hasStructuredChanges(entry.changedFields) || hasStructuredChanges(entry.fieldChanges) || hasStructuredChanges(entry.changes)) return true
+  if ([entry.summary, entry.changeSummary, entry.reason].some((value) => nonBlank(value))) return true
+  const detail = nonBlank(entry.detail)
+  return Boolean(detail && !isStatusEcho(detail, entry.fromStatus, entry.toStatus))
+}
+function isMeaningfulWarehouseAction(entry: WarehouseTimelineEntry) {
+  return [entry.action, entry.eventType].some((value) => /^(?:PUSH_PRELOAD|PDA(?:_|$)|CONFIRM(?:_|$))/.test(nonBlank(value)))
+}
+function isNoopWarehouseStatus(entry: WarehouseTimelineEntry) {
+  if (isMeaningfulWarehouseAction(entry)) return false
+  return warehouseAction(entry) === 'STATUS_UPDATE'
+    && nonBlank(entry.fromStatus) !== ''
+    && nonBlank(entry.fromStatus) === nonBlank(entry.toStatus)
+    && !hasEffectiveWarehouseChange(entry)
+}
+function eventIdentity(entry: WarehouseTimelineEntry) { return nonBlank(entry.eventId) || nonBlank(entry.idempotencyKey) }
+function eventSignature(entry: WarehouseTimelineEntry) {
+  return JSON.stringify([warehouseAction(entry), entry.fromStatus || null, entry.toStatus || null, entry.summary || null, entry.changeSummary || null, entry.reason || null, entry.detail || null, entry.changedFields || null, entry.fieldChanges || null, entry.changes || null])
+}
+function sameExplicitEvent(left: WarehouseTimelineEntry, right: WarehouseTimelineEntry) {
+  const sameId = nonBlank(left.eventId) && nonBlank(left.eventId) === nonBlank(right.eventId)
+  const sameKey = nonBlank(left.idempotencyKey) && nonBlank(left.idempotencyKey) === nonBlank(right.idempotencyKey)
+  return Boolean((sameId || sameKey) && eventSignature(left) === eventSignature(right))
+}
+const filteredWarehouseTimeline = computed(() => {
+  const sorted = (props.warehouseTimeline || []).map((entry, index) => ({ entry, index }))
+    .filter(({ entry }) => entry.occurredAt && !['MARK', 'CANCEL'].includes(warehouseAction(entry)) && !isNoopWarehouseStatus(entry))
+    .sort((left, right) => {
+      const time = Date.parse(right.entry.occurredAt || '') - Date.parse(left.entry.occurredAt || '')
+      return time || left.index - right.index
+    })
+  const result: WarehouseTimelineEntry[] = []
+  for (const { entry } of sorted) {
+    const previous = result[result.length - 1]
+    if (previous && sameExplicitEvent(previous, entry)) continue
+    result.push(entry)
+  }
+  return result
+})
+function warehouseEventSummary(entry: WarehouseTimelineEntry) {
+  const value = nonBlank(entry.summary) || nonBlank(entry.changeSummary) || nonBlank(entry.reason) || nonBlank(entry.detail)
+  if (value && value.length <= 120 && !/(?:operation|idempot|claim-|pda-submit|complete-)/i.test(value)) return value
+  const from = nonBlank(entry.fromStatus); const to = nonBlank(entry.toStatus)
+  if (from && to && from !== to) return `${statusLabel(from)} → ${statusLabel(to)}`
+  if (hasStructuredChanges(entry.changedFields) || hasStructuredChanges(entry.fieldChanges) || hasStructuredChanges(entry.changes)) return '业务字段已更新'
+  return '操作已记录'
+}
+const fulfillmentEvents = computed<FulfillmentEvent[]>(() => {
+  const values: FulfillmentEvent[] = []
+  for (const [index, item] of filteredWarehouseTimeline.value.entries()) {
+    const action = warehouseAction(item)
+    const departure = /OUTBOUND|DISPATCH|DEPARTED_WAREHOUSE/.test(action)
+    values.push({ key: `warehouse-${eventIdentity(item) || `${action}-${item.occurredAt}-${index}`}`, time: item.occurredAt!, type: departure ? '确认离仓' : '仓内操作', title: warehouseEventText(action), summary: warehouseEventSummary(item), source: item.operatorName || '系统', actual: true })
+  }
+  const nodeKeys = new Set<string>()
+  for (const item of primaryNodeFacts.value) {
+    const actual = Boolean(item.actualAt)
+    const time = item.actualAt || item.estimatedAt || item.observedAt
+    const key = JSON.stringify([item.standardNode, item.actualAt || null, item.estimatedAt || null, item.locationCode || null, item.locationName || null, item.providerCode, item.sourceReference || null])
+    if (nodeKeys.has(key)) continue
+    nodeKeys.add(key)
+    const manual = /MANUAL|PLATFORM/i.test(item.providerCode)
+    const timing = actual ? `实际 ${formatTime(item.actualAt)}` : item.estimatedAt ? `预计 ${formatTime(item.estimatedAt)}` : `观测 ${formatTime(item.observedAt)}`
+    const expected = actual && item.estimatedAt ? ` · 原预计 ${formatTime(item.estimatedAt)}` : ''
+    const type = manual ? '人工补录' : item.standardNode === 'DEPARTED_WAREHOUSE' && actual ? '确认离仓' : '船运节点'
+    values.push({ key: `node-${key}`, time, type, title: nodeText(item.standardNode), summary: `${timing}${expected} · ${nodeLocation(item)}`, source: [item.providerCode, item.sourceReference].filter(Boolean).join(' · ') || '—', actual })
+  }
+  for (const item of exceptions.value) values.push({ key: `exception-${item.id}`, time: item.observedAt, type: '异常', title: `${exceptionText(item.exceptionCode)} · ${item.active ? '发生' : '已解除'}`, summary: `${exceptionLocation(item)} · ${item.providerStatus}`, source: `船运跟踪 · ${[item.providerCode, item.sourceReference].filter(Boolean).join(' · ')}`, actual: true })
+  return values.sort((left, right) => {
+    const time = Date.parse(right.time) - Date.parse(left.time)
+    if (time) return time
+    const actual = Number(right.actual) - Number(left.actual)
+    return actual || left.key.localeCompare(right.key)
+  })
+})
+function eventTagType(type: FulfillmentEvent['type']) { return ({ '仓内操作': 'info', '确认离仓': 'success', '船运节点': 'primary', '人工补录': 'warning', '异常': 'danger' } as const)[type] }
+
+function resetManualForm(initialTime = '') {
+  Object.assign(manualForm, { standardNode: '', estimatedAt: initialTime, actualAt: initialTime, locationCode: '', locationName: '', reason: '' })
+  manualError.value = null; manualValidationError.value = ''
+}
+function createIdempotencyKey() { return globalThis.crypto?.randomUUID?.() || `carrier-node-${Date.now()}-${Math.random().toString(16).slice(2)}` }
+function localDateTimeNow() {
+  const now = new Date()
+  return new Date(now.getTime() - now.getTimezoneOffset() * 60_000).toISOString().slice(0, 19)
+}
+function openManualDialog() {
+  if (!props.containerBookingId) return
+  const now = localDateTimeNow()
+  resetManualForm(now); manualIdempotencyKey.value = createIdempotencyKey(); manualObservedAt.value = now; manualDialogOpen.value = true
+}
+async function submitManualNode() {
+  manualValidationError.value = ''
+  if (!props.containerBookingId || !manualForm.standardNode) { manualValidationError.value = '请选择标准节点'; return }
+  if (!manualForm.estimatedAt && !manualForm.actualAt) { manualValidationError.value = '预计时间和实际时间至少填写一项'; return }
+  if (!manualForm.reason.trim()) { manualValidationError.value = '请输入补录原因'; return }
+  const base = { standardNode: manualForm.standardNode, observedAt: manualObservedAt.value, locationCode: manualForm.locationCode.trim() || null, locationName: manualForm.locationName.trim() || null, reason: manualForm.reason.trim() }
+  const request: ContainerManualNodeRequest = manualForm.actualAt
+    ? { ...base, actualAt: manualForm.actualAt, estimatedAt: manualForm.estimatedAt || null }
+    : { ...base, estimatedAt: manualForm.estimatedAt, actualAt: null }
+  manualSaving.value = true; manualError.value = null
+  try {
+    containerNodes.value = await appendContainerShippingNode(props.containerBookingId, manualIdempotencyKey.value, request)
+    manualDialogOpen.value = false; manualIdempotencyKey.value = ''; manualObservedAt.value = ''; resetManualForm()
+  } catch (cause) { manualError.value = getApiErrorDetails(cause, '人工节点补录失败') }
+  finally { manualSaving.value = false }
+}
+
+async function load() {
+  selected.value = null; detail.value = null; containerNodes.value = null; latestSchedule.value = null; error.value = null; queryDetailError.value = null; scheduleError.value = null
+  if (!props.oceanBookingId && !props.containerBookingId) return
+  loading.value = true
+  try {
+    if (props.containerBookingId) containerNodes.value = await getContainerShippingNodes(props.containerBookingId)
+    const page = await listCarrierScheduleQueries({ page: 1, size: 200, oceanBookingId: props.oceanBookingId || undefined, containerBookingId: props.containerBookingId || undefined })
+    const matching = props.portScheduleId ? page.records.filter((item) => item.query.resultPortScheduleId === String(props.portScheduleId)) : page.records
+    selected.value = matching[0] || page.records[0] || null
+    if (!selected.value) return
+    const [queryResult] = await Promise.allSettled([getCarrierScheduleQuery(selected.value.query.id)])
+    if (queryResult.status === 'fulfilled') detail.value = queryResult.value
+    else queryDetailError.value = getApiErrorDetails(queryResult.reason, '查询历史加载失败')
+    const resultPortScheduleId = detail.value?.query.query.resultPortScheduleId || selected.value.query.resultPortScheduleId
+    if (resultPortScheduleId) {
+      try { latestSchedule.value = (await getPortSchedule(resultPortScheduleId)).portSchedule }
+      catch (cause) { scheduleError.value = getApiErrorDetails(cause, '最新船期结果加载失败') }
+    }
+  } catch (cause) { error.value = getApiErrorDetails(cause, '船节点查询状态加载失败') }
+  finally { loading.value = false }
+}
+
+watch(() => [props.oceanBookingId, props.containerBookingId, props.portScheduleId], () => void load(), { immediate: true })
+watch(manualDialogOpen, (open) => { if (!open && !manualSaving.value) { manualIdempotencyKey.value = ''; manualObservedAt.value = '' } })
+</script>
+
+<template>
+  <section class="carrier-query" :class="{ 'admin-density': dense }" aria-label="货柜履约轨迹">
+    <header><div><h2>货柜履约轨迹</h2><p>统一展示仓内操作、确认离仓与船运节点；预计节点不会推进实际进度。</p></div><div class="header-actions"><span class="history-count">仓内 {{ filteredWarehouseTimeline.length }} 条 · 共 {{ fulfillmentEvents.length }} 条</span><el-button v-if="props.containerBookingId && access.can('platform:firstleg:port-schedule-query:manual')" :class="{ 'density-action': dense }" data-tone="primary" size="small" type="primary" plain @click="openManualDialog"><Plus v-if="!dense" :size="15" />人工补录节点</el-button><el-tag v-if="query" :type="statusType" effect="light">{{ statusText }}</el-tag></div></header>
+    <LoadErrorState v-if="error" compact title="船节点查询状态加载失败" :message="error.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="error" /></template></LoadErrorState>
+    <div v-else-if="loading" class="loading-state"><el-skeleton :rows="1" animated /></div>
+    <template v-else>
+      <el-alert v-if="query?.lastErrorMessage || query?.status === 'MANUAL_REQUIRED'" type="error" :closable="false" show-icon :title="providerErrorText(query?.lastErrorMessage || query?.manualReason)" />
+      <el-alert v-if="query?.status === 'STOPPED'" type="info" :closable="false" show-icon :title="query.stopReason || '船节点查询已停止。'" />
+      <el-alert v-if="queryDetailError" type="warning" :closable="false" show-icon title="标准节点与变更历史暂不可用"><template #default><ApiErrorMeta :details="queryDetailError" /></template></el-alert>
+      <el-alert v-if="scheduleError" type="warning" :closable="false" show-icon title="关联船期结果暂不可用"><template #default><ApiErrorMeta :details="scheduleError" /></template></el-alert>
+      <div v-if="latestSchedule" class="latest-result"><strong>{{ latestSchedule.schedule.vesselName }} / {{ latestSchedule.schedule.voyageNo }}</strong><span>{{ latestSchedule.schedule.departurePortName || latestSchedule.schedule.departurePortCode }} → {{ latestSchedule.schedule.destinationPortName || latestSchedule.schedule.destinationPortCode }}</span><span>预计开船 {{ formatTime(latestSchedule.schedule.etdAt) }} · 预计到港 {{ formatTime(latestSchedule.schedule.etaAt) }}</span></div>
+      <ol v-if="fulfillmentEvents.length" class="fulfillment-timeline"><li v-for="item in fulfillmentEvents" :key="item.key"><time>{{ formatTime(item.time) }}</time><el-tag size="small" :type="eventTagType(item.type)">{{ item.type }}</el-tag><strong>{{ item.title }}</strong><span>{{ item.summary }}</span><small>{{ item.source }}</small></li></ol>
+      <p v-else class="empty-line">暂无货柜履约记录</p>
+      <p v-if="!query" class="tracking-prompt">当前未开启跟踪任务；可独立使用人工补录修改货柜当前节点。</p>
+      <details v-if="supersededActualNodes.length" class="technical-details duplicate-node-history"><summary>历史重复实际节点（{{ supersededActualNodes.length }}）</summary><ol class="technical-history"><li v-for="item in supersededActualNodes" :key="item.id"><span>{{ nodeTimeText(item) }}</span><strong>{{ nodeText(item.standardNode) }}</strong><small>{{ nodeLocation(item) }} · {{ item.providerCode }}<template v-if="item.sourceReference"> · {{ item.sourceReference }}</template></small></li></ol></details>
+      <details v-if="query" class="technical-details"><summary>查询任务摘要、异常与变更历史</summary><dl class="query-facts" :class="{ 'density-fields': dense }"><div><dt>查询任务</dt><dd>{{ query.queryNo || query.id }}</dd></div><div><dt>跟踪标识</dt><dd>{{ trackingTypeText(query.trackingType) }} · {{ query.trackingNo || '—' }}</dd></div><div><dt>任务状态</dt><dd>{{ statusText }}</dd></div><div><dt>建立来源</dt><dd>{{ triggerSourceText(query.triggerSource) }}</dd></div><div><dt>最新实际节点</dt><dd>{{ nodeText(query.latestActualNode) }}</dd></div><div><dt>实际发生时间</dt><dd>{{ formatTime(query.latestActualAt) }}</dd></div><div><dt>最新来源</dt><dd>{{ latestSource }}</dd></div><div><dt>来源参考</dt><dd class="break-value">{{ sourceReference }}</dd></div><div><dt>观测时间</dt><dd>{{ formatTime(latestObservation) }}</dd></div><div><dt>最近成功</dt><dd>{{ formatTime(query.lastSuccessAt) }}</dd></div><div><dt>结果有效性</dt><dd>{{ queryView?.expired ? '结果已过期' : '结果有效' }}</dd></div><div v-if="query.lastErrorCode"><dt>最近错误码</dt><dd>{{ query.lastErrorCode }}</dd></div></dl><h3>任务变更历史</h3><p v-if="!histories.length" class="empty-line">暂无变更历史</p><ol v-else class="technical-history"><li v-for="item in histories" :key="item.id"><span>{{ formatTime(item.createdAt) }}</span><strong>{{ historyText(item.action) }}</strong><small>{{ item.operatorName || '系统' }}<template v-if="item.reason"> · {{ item.reason }}</template></small></li></ol></details>
+    </template>
+    <AppDialog :class="{ 'admin-density-dialog': dense }" v-model="manualDialogOpen" title="人工补录船节点" width="min(620px, calc(100vw - 28px))" confirm-text="确认补录" :confirm-loading="manualSaving" @confirm="submitManualNode">
+      <el-alert v-if="manualError" type="error" :closable="false" show-icon title="补录未成功，已保留当前填写内容"><template #default><ApiErrorMeta :details="manualError" /></template></el-alert>
+      <el-alert v-if="manualValidationError" type="warning" :closable="false" show-icon :title="manualValidationError" />
+      <el-alert type="info" :closable="false" title="观测时间按提交时刻记录；预计事实不推进实际进度，既有事实不可编辑或删除。" />
+      <el-form label-position="top" class="manual-form">
+        <el-form-item label="标准节点" required><el-select v-model="manualForm.standardNode" placeholder="请选择标准节点" style="width:100%"><el-option v-for="node in standardNodes" :key="node" :label="nodeText(node)" :value="node" /></el-select></el-form-item>
+        <div class="manual-form-grid"><el-form-item label="预计时间"><el-date-picker v-model="manualForm.estimatedAt" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" placeholder="可选" style="width:100%" /></el-form-item><el-form-item label="实际时间"><el-date-picker v-model="manualForm.actualAt" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" placeholder="可选，填写后推进实际节点" style="width:100%" /></el-form-item></div>
+        <div class="manual-form-grid"><el-form-item label="地点编码"><el-input v-model="manualForm.locationCode" maxlength="32" placeholder="可选，如 USLAX" /></el-form-item><el-form-item label="地点名称"><el-input v-model="manualForm.locationName" maxlength="128" placeholder="可选" /></el-form-item></div>
+        <el-form-item label="补录原因" required><el-input v-model="manualForm.reason" type="textarea" :rows="3" maxlength="1000" show-word-limit placeholder="请输入事实来源与补录原因" /></el-form-item>
+      </el-form>
+    </AppDialog>
+  </section>
+</template>
+
+<style scoped>
+.history-count{color:var(--cc-muted);font-size:var(--admin-font-caption, 12px);white-space:nowrap}
+.carrier-query{display:grid;gap:9px;padding-top:2px}.carrier-query>header{display:flex;align-items:flex-start;justify-content:space-between;gap:var(--admin-space-5, 12px)}.header-actions{display:flex;align-items:center;gap:var(--admin-space-3, 8px)}.carrier-query h2{margin:0;font-size:var(--admin-font-section, 15px)}.carrier-query header p{margin:3px 0 0;color:var(--cc-muted);font-size:var(--admin-font-caption, 12px)}.loading-state{padding:var(--admin-space-2, 6px) 0}.latest-result{display:flex;flex-wrap:wrap;align-items:center;gap:var(--admin-space-2, 6px) var(--admin-space-6, 16px);padding:7px var(--admin-space-4, 10px);border-left:3px solid var(--el-color-primary);background:var(--el-color-primary-light-9);font-size:var(--admin-font-caption, 12px)}.fulfillment-timeline{display:grid;margin:0;padding:0;list-style:none}.fulfillment-timeline li{display:grid;grid-template-columns:130px 86px 150px minmax(180px,1fr) minmax(120px,.8fr);align-items:center;gap:7px;padding:var(--admin-space-2, 6px) 2px;border-top:1px solid var(--cc-border);font-size:var(--admin-font-caption, 12px)}.fulfillment-timeline time,.fulfillment-timeline span,.fulfillment-timeline small{overflow:hidden;color:var(--cc-muted);text-overflow:ellipsis;white-space:nowrap}.tracking-prompt{margin:0;padding:7px var(--admin-space-4, 10px);border-left:3px solid var(--el-color-info);background:var(--cc-bg-subtle,#f7f8fa);color:var(--cc-muted);font-size:var(--admin-font-caption, 12px)}.empty-line{margin:0;color:var(--cc-muted);font-size:var(--admin-font-caption, 12px)}.technical-details{border-top:1px solid var(--cc-border);font-size:var(--admin-font-caption, 12px)}.technical-details summary{padding:7px 2px;color:var(--cc-primary);cursor:pointer}.query-facts:not(.density-fields){display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:var(--admin-space-3, 8px) var(--admin-space-6, 16px);margin:4px 0 var(--admin-space-4, 10px)}.query-facts:not(.density-fields)>div{min-width:0}.query-facts:not(.density-fields) dt{color:var(--cc-muted);font-size:var(--admin-font-caption, 11px)}.query-facts:not(.density-fields) dd{margin:2px 0 0;font-size:var(--admin-font-caption, 12px)}.break-value{overflow-wrap:anywhere}.technical-details h3{margin:var(--admin-space-3, 8px) 0 5px;font-size:var(--admin-font-caption, 12px)}.technical-history{margin:0;padding:0;list-style:none}.technical-history li{display:grid;grid-template-columns:130px 150px minmax(0,1fr);gap:var(--admin-space-3, 8px);padding:5px 0;border-top:1px solid var(--cc-border)}.technical-history small{color:var(--cc-muted)}.manual-form{display:grid;gap:2px;margin-top:var(--admin-space-5, 12px)}.manual-form-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:var(--admin-space-5, 12px)}@media(max-width:1200px){.query-facts{grid-template-columns:repeat(2,minmax(0,1fr))}.fulfillment-timeline li{grid-template-columns:120px 82px 140px minmax(0,1fr)}.fulfillment-timeline small{grid-column:4}}@media(max-width:720px){.carrier-query>header{align-items:flex-start;flex-direction:column}.query-facts,.manual-form-grid{grid-template-columns:1fr}.fulfillment-timeline li{grid-template-columns:90px minmax(0,1fr)}.fulfillment-timeline strong,.fulfillment-timeline span,.fulfillment-timeline small{grid-column:2}.technical-history li{grid-template-columns:1fr}}.carrier-query.admin-density .fulfillment-timeline :is(time,span,small){overflow:visible;white-space:normal;overflow-wrap:anywhere}.carrier-query.admin-density .technical-history small{overflow-wrap:anywhere}
+</style>
diff --git a/src/modules/port-schedules/index.ts b/src/modules/port-schedules/index.ts
new file mode 100644
index 00000000..08215876
--- /dev/null
+++ b/src/modules/port-schedules/index.ts
@@ -0,0 +1,3 @@
+export { portScheduleRoutes } from './routes'
+export { default as CarrierScheduleQueryPanel } from './components/CarrierScheduleQueryPanel.vue'
+export * from './types'
diff --git a/src/modules/port-schedules/pages/PortSchedulesView.test.ts b/src/modules/port-schedules/pages/PortSchedulesView.test.ts
new file mode 100644
index 00000000..696ec8b0
--- /dev/null
+++ b/src/modules/port-schedules/pages/PortSchedulesView.test.ts
@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+const source = readFileSync(resolve(process.cwd(), 'src/modules/port-schedules/pages/PortSchedulesView.vue'), 'utf8')
+describe('PortSchedulesView', () => {
+  it('uses calibrated desktop widths for customer, composite keyword and validity', () => {
+    expect(source).toContain("key: 'customerId', type: 'select', label: '客户', placeholder: '全部客户', width: 220")
+    expect(source).toContain("key: 'keyword', type: 'input', label: '关键词', placeholder: '船期号/船名/航次/港口', width: 260")
+    expect(source).toContain("key: 'expired', type: 'select', label: '有效性', width: 160")
+  })
+  it('uses standard list components and a left action column', () => {
+    expect(source).toContain('QueryToolbar')
+    expect(source).toContain('DataTable')
+    expect(source).toContain("fixed: 'left'")
+    expect(source).toContain('AppDialog')
+  })
+
+  it('lets QueryToolbar issue only one search when reset', () => {
+    expect(source).toContain('@search="search"')
+    expect(source).not.toContain('@reset="search"')
+  })
+
+  it('keeps view mode read-only without a save entry', () => {
+    expect(source).toContain("openSchedule(row.schedule.id, 'view')")
+    expect(source).toContain("openSchedule(row.schedule.id, 'edit')")
+    expect(source).toContain(':show-confirm="!dialogReadonly"')
+    expect(source).toContain(':disabled="dialogReadonly"')
+    expect(source).toContain('if (dialogReadonly.value ||')
+  })
+
+  it('selects real customers and customer-scoped ocean bookings', () => {
+    expect(source).toContain("from '@/modules/iam'")
+    expect(source).toContain("from '@/modules/ocean-bookings'")
+    expect(source).toContain("listPlatformTenants({ page: currentPage, size: 200, status: 'ACTIVE' })")
+    expect(source).toContain('while (currentPage <= pages)')
+    expect(source).toContain('listOceanBookings({ page: 1, size: 200, customerId })')
+    expect(source).toContain("customerId: String(query.customerId || '') || undefined")
+    expect(source).toContain('function customerLabel(customer: PlatformTenantResource) { return customer.tenantName }')
+    expect(source).not.toContain('customer.tenantCode')
+    expect(source).toContain("form.oceanBookingId = ''")
+    expect(source).not.toContain('label="客户 ID"')
+    expect(source).not.toContain('label="订舱 ID"')
+  })
+
+  it('hides inactive customers while preserving the customer bound to an existing schedule', () => {
+    expect(source).toContain("customer.status === 'ACTIVE' || String(customer.id) === String(form.customerId)")
+    expect(source).toContain('v-for="customer in selectableCustomers"')
+    expect(source).not.toContain(':disabled="customer.status !== \'ACTIVE\'')
+  })
+
+  it('protects candidate requests and exposes loading, empty, error and retry states', () => {
+    expect(source).toContain('customerRequestSerial')
+    expect(source).toContain('bookingRequestSerial')
+    expect(source).toContain(':loading="customersLoading"')
+    expect(source).toContain(':loading="bookingsLoading"')
+    expect(source).toContain('no-data-text="暂无可用客户"')
+    expect(source).toContain('no-data-text="该客户暂无订舱记录"')
+    expect(source).toContain('@click="loadCustomers"')
+    expect(source).toContain('@click="loadBookings()"')
+  })
+
+  it('gives business fields actionable placeholders', () => {
+    expect(source).toContain('placeholder="请输入船名"')
+    expect(source).toContain('placeholder="请输入航次"')
+    expect(source).toContain('placeholder="例如 CNSHA"')
+    expect(source).toContain('placeholder="请选择预计开船时间"')
+    expect(source).toContain('placeholder="请输入船期补充说明（可选）"')
+  })
+
+  it('exposes expiry and conflict handling', () => {
+    expect(source).toContain("query.expired === 'true'")
+    expect(source).toContain("actionError.value.code === 'A0409'")
+    expect(source).toContain('ApiErrorMeta')
+  })
+  it('shows ETA and backend update time in the list', () => {
+    expect(source).toContain("prop: 'schedule.etaAt'")
+    expect(source).toContain("prop: 'schedule.updatedAt'")
+  })
+  it('formats observed and update times and keeps the editor within the viewport', () => {
+    expect(source).toContain('formatDateTime(row.schedule.observedAt)')
+    expect(source).toContain('formatDateTime(row.schedule.updatedAt)')
+    expect(source).toContain('width:min(820px,calc(100vw - 28px))!important')
+    expect(source).toContain('max-height:90vh')
+  })
+  it('uses bordered business action buttons while keeping retry actions as links', () => {
+    expect(source).toContain('size="small" type="primary" plain')
+    expect(source).toContain('size="small" @click="openSchedule')
+    expect(source).not.toContain("port-schedule:view')\" link")
+    expect(source).toContain('<el-button link type="primary" @click="loadCustomers"')
+    expect(source).toContain(':total="total" stripe row-key="schedule.id"')
+  })
+  it('shows query facts only inside the existing read-only schedule dialog', () => {
+    expect(source).toContain('CarrierScheduleQueryPanel')
+    expect(source).toContain('v-if="dialogReadonly && form.oceanBookingId"')
+    expect(source).toContain(':port-schedule-id="editingId"')
+  })
+})
diff --git a/src/modules/port-schedules/pages/PortSchedulesView.vue b/src/modules/port-schedules/pages/PortSchedulesView.vue
new file mode 100644
index 00000000..ddfad4b7
--- /dev/null
+++ b/src/modules/port-schedules/pages/PortSchedulesView.vue
@@ -0,0 +1,78 @@
+<script setup lang="ts">
+import { computed, onMounted, reactive, ref, watch } from 'vue'
+import { ElMessage, type FormInstance, type FormRules } from 'element-plus'
+import { Eye, Pencil, Plus } from '@lucide/vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import DataTable from '@/shared/components/DataTable.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { listPlatformTenants, type PlatformTenantResource } from '@/modules/iam'
+import { listOceanBookings, type OceanBookingResource } from '@/modules/ocean-bookings'
+import CarrierScheduleQueryPanel from '../components/CarrierScheduleQueryPanel.vue'
+import { createPortSchedule, getPortSchedule, listPortSchedules, updatePortSchedule } from '../api/platformPortSchedules'
+import type { PortScheduleData, PortScheduleView } from '../types'
+
+const access = useAccessPreviewStore()
+const rows = ref<PortScheduleView[]>([]); const loading = ref(false); const error = ref<ApiErrorDetails | null>(null)
+const page = ref(1); const pageSize = ref(20); const total = ref(0)
+const query = reactive<QueryModel>({ customerId: '', keyword: '', expired: '' })
+const fields = computed<QueryField[]>(() => [{ key: 'customerId', type: 'select', label: '客户', placeholder: '全部客户', width: 220, options: customers.value.filter((customer) => customer.status === 'ACTIVE').map((customer) => ({ label: customerLabel(customer), value: String(customer.id) })), props: { filterable: true, loading: customersLoading.value } }, { key: 'keyword', type: 'input', label: '关键词', placeholder: '船期号/船名/航次/港口', width: 260 }, { key: 'expired', type: 'select', label: '有效性', width: 160, options: [{ label: '有效', value: 'false' }, { label: '已过期', value: 'true' }] }])
+const columns = [
+  { key: 'actions', label: '操作', fixed: 'left', width: 165, slotName: 'actions', hideable: false, movable: false },
+  { prop: 'schedule.scheduleNo', label: '船期编号', minWidth: 145 }, { prop: 'schedule.sourceName', label: '信息来源', minWidth: 130 },
+  { prop: 'schedule.vesselName', label: '船名/航次', minWidth: 155, slotName: 'vessel' }, { prop: 'schedule.departurePortName', label: '起运港', minWidth: 120 },
+  { prop: 'schedule.destinationPortName', label: '目的港', minWidth: 120 }, { prop: 'schedule.etdAt', label: '预计开船', minWidth: 160 },
+  { prop: 'schedule.etaAt', label: '预计到港', minWidth: 160 }, { prop: 'schedule.observedAt', label: '查询时间', minWidth: 160, slotName: 'observedAt' }, { prop: 'schedule.updatedAt', label: '更新时间', minWidth: 160, slotName: 'updatedAt' }, { prop: 'expired', label: '有效性', width: 95, slotName: 'expired' },
+]
+function formatDateTime(value?: string | null) { return value ? value.replace('T', ' ').slice(0, 16) : '—' }
+function blank(): PortScheduleData { const now = new Date().toISOString().slice(0, 19); return { customerId: '', oceanBookingId: '', containerBookingId: null, sourceType: 'MANUAL', sourceName: '', sourceRef: '', vesselName: '', voyageNo: '', departurePortCode: '', departurePortName: '', destinationPortCode: '', destinationPortName: '', etdAt: null, etaAt: null, bookingCutoffAt: null, customsCutoffAt: null, portCutoffAt: null, observedAt: now, expiresAt: now, remark: '' } }
+type DialogMode = 'create' | 'view' | 'edit'
+const dialogOpen = ref(false); const dialogMode = ref<DialogMode>('create'); const saving = ref(false); const editingId = ref(''); const expectedVersion = ref(0); const formRef = ref<FormInstance>(); const form = reactive<PortScheduleData>(blank()); const actionError = ref<ApiErrorDetails | null>(null)
+const rules: FormRules = { customerId: [{ required: true, message: '请选择客户', trigger: 'change' }], oceanBookingId: [{ required: true, message: '请选择订舱记录', trigger: 'change' }], sourceName: [{ required: true, message: '请输入信息来源', trigger: 'blur' }], sourceRef: [{ required: true, message: '请输入来源链接或参考号', trigger: 'blur' }], vesselName: [{ required: true, message: '请输入船名', trigger: 'blur' }], voyageNo: [{ required: true, message: '请输入航次', trigger: 'blur' }], departurePortCode: [{ required: true, message: '请输入起运港代码', trigger: 'blur' }], destinationPortCode: [{ required: true, message: '请输入目的港代码', trigger: 'blur' }], observedAt: [{ required: true, message: '请选择查询时间', trigger: 'change' }], expiresAt: [{ required: true, message: '请选择过期时间', trigger: 'change' }] }
+const customers = ref<PlatformTenantResource[]>([]); const customersLoading = ref(false); const customersError = ref<ApiErrorDetails | null>(null); let customerRequestSerial = 0
+const bookings = ref<OceanBookingResource[]>([]); const bookingsLoading = ref(false); const bookingsError = ref<ApiErrorDetails | null>(null); let bookingRequestSerial = 0
+const selectableCustomers = computed(() => customers.value.filter((customer) => (
+  customer.status === 'ACTIVE' || String(customer.id) === String(form.customerId)
+)))
+const canCreate = computed(() => access.can('platform:firstleg:port-schedule:create'))
+const dialogTitle = computed(() => dialogMode.value === 'create' ? '新增船期' : dialogMode.value === 'edit' ? '编辑船期' : '查看船期')
+const dialogReadonly = computed(() => dialogMode.value === 'view')
+function customerLabel(customer: PlatformTenantResource) { return customer.tenantName }
+function bookingLabel(booking: OceanBookingResource) { return [booking.bookingNo || '待生成订舱号', [booking.vesselName, booking.voyageNo].filter(Boolean).join(' / '), [booking.departurePortCode, booking.destinationPortCode].filter(Boolean).join(' → ')].filter(Boolean).join(' · ') }
+async function loadCustomers() { const serial = ++customerRequestSerial; customersLoading.value = true; customersError.value = null; try { const records: PlatformTenantResource[] = []; let currentPage = 1; let pages = 1; do { const result = await listPlatformTenants({ page: currentPage, size: 200, status: 'ACTIVE' }); records.push(...result.records); pages = Math.max(1, result.pages); currentPage += 1 } while (currentPage <= pages); if (serial === customerRequestSerial) customers.value = records } catch (cause) { if (serial === customerRequestSerial) customersError.value = getApiErrorDetails(cause, '客户候选加载失败') } finally { if (serial === customerRequestSerial) customersLoading.value = false } }
+async function loadBookings(customerId = String(form.customerId || '')) { const serial = ++bookingRequestSerial; bookings.value = []; bookingsError.value = null; if (!customerId) { bookingsLoading.value = false; return } bookingsLoading.value = true; try { const result = await listOceanBookings({ page: 1, size: 200, customerId }); if (serial === bookingRequestSerial && customerId === String(form.customerId || '')) bookings.value = result.records } catch (cause) { if (serial === bookingRequestSerial && customerId === String(form.customerId || '')) bookingsError.value = getApiErrorDetails(cause, '订舱候选加载失败') } finally { if (serial === bookingRequestSerial) bookingsLoading.value = false } }
+function handleCustomerChange(value: string) { form.customerId = String(value || ''); form.oceanBookingId = ''; void formRef.value?.clearValidate('oceanBookingId'); void loadBookings(form.customerId) }
+async function load() { loading.value = true; error.value = null; try { const result = await listPortSchedules({ page: page.value, size: pageSize.value, customerId: String(query.customerId || '') || undefined, keyword: String(query.keyword || '') || undefined, expired: query.expired === '' ? undefined : query.expired === 'true' }); rows.value = result.records; total.value = result.total } catch (cause) { error.value = getApiErrorDetails(cause) } finally { loading.value = false } }
+function search() { if (page.value === 1) void load(); else page.value = 1 }
+function openCreate() { dialogMode.value = 'create'; editingId.value = ''; expectedVersion.value = 0; Object.assign(form, blank()); bookings.value = []; bookingsError.value = null; actionError.value = null; dialogOpen.value = true; if (!customers.value.length) void loadCustomers() }
+async function openSchedule(id: string, mode: Extract<DialogMode, 'view' | 'edit'>) { actionError.value = null; try { const result = await getPortSchedule(id); dialogMode.value = mode; editingId.value = id; expectedVersion.value = result.portSchedule.schedule.version; Object.assign(form, result.portSchedule.schedule); dialogOpen.value = true; if (!customers.value.length) void loadCustomers(); void loadBookings(String(form.customerId || '')) } catch (cause) { error.value = getApiErrorDetails(cause) } }
+async function save() { if (dialogReadonly.value || !await formRef.value?.validate().catch(() => false)) return; saving.value = true; actionError.value = null; try { if (editingId.value) await updatePortSchedule(editingId.value, { expectedVersion: expectedVersion.value, data: { ...form }, reason: '后台维护船期' }); else await createPortSchedule({ ...form }); ElMessage.success(editingId.value ? '船期已更新' : '船期已新增'); dialogOpen.value = false; await load() } catch (cause) { actionError.value = getApiErrorDetails(cause); if (actionError.value.code === 'A0409' && editingId.value) await openSchedule(editingId.value, 'edit') } finally { saving.value = false } }
+watch([page, pageSize], () => void load()); onMounted(() => { void load(); void loadCustomers() })
+</script>
+<template>
+  <AdminPage as="div"><ListPageLayout aria-label="船期列表">
+    <template #toolbar><QueryToolbar v-model="query" class="surface-panel" ariaLabel="船期筛选" :fields="fields" @search="search" /></template>
+    <template v-if="error" #state><LoadErrorState title="船期列表加载失败" :message="error.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="error" /></template></LoadErrorState></template>
+    <section v-if="!error" class="surface-panel table-panel"><DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :loading="loading" :total="total" stripe row-key="schedule.id" preference-key="port-schedules" empty-text="暂无符合条件的船期">
+      <template #toolbar-actions><el-button v-if="canCreate" type="primary" @click="openCreate"><Plus :size="16" />新增船期</el-button></template>
+      <template #actions="{ row }"><div class="table-actions"><el-button v-if="access.can('platform:firstleg:port-schedule:view')" size="small" type="primary" plain @click="openSchedule(row.schedule.id, 'view')"><Eye :size="15" />查看</el-button><el-button v-if="access.can('platform:firstleg:port-schedule:edit')" size="small" @click="openSchedule(row.schedule.id, 'edit')"><Pencil :size="15" />编辑</el-button></div></template>
+      <template #vessel="{ row }">{{ row.schedule.vesselName }} / {{ row.schedule.voyageNo }}</template><template #observedAt="{ row }">{{ formatDateTime(row.schedule.observedAt) }}</template><template #updatedAt="{ row }">{{ formatDateTime(row.schedule.updatedAt) }}</template><template #expired="{ row }"><el-tag :type="row.expired ? 'danger' : 'success'">{{ row.expired ? '已过期' : '有效' }}</el-tag></template>
+    </DataTable></section>
+  </ListPageLayout>
+  <AppDialog v-model="dialogOpen" :title="dialogTitle" width="820px" :confirm-loading="saving" :show-confirm="!dialogReadonly" :cancel-text="dialogReadonly ? '关闭' : '取消'" @confirm="save"><div class="schedule-dialog-body"><el-alert v-if="actionError" type="error" :closable="false"><ApiErrorMeta :details="actionError" /></el-alert><div v-if="customersError" class="selector-error"><span>{{ customersError.message }}</span><el-button link type="primary" @click="loadCustomers">重新加载客户</el-button></div><div v-if="bookingsError" class="selector-error"><span>{{ bookingsError.message }}</span><el-button link type="primary" @click="loadBookings()">重新加载订舱</el-button></div><el-form ref="formRef" :model="form" :rules="rules" :disabled="dialogReadonly" label-position="top" class="schedule-form"><el-row :gutter="16">
+    <el-col :xs="24" :sm="12"><el-form-item label="客户" prop="customerId"><el-select :model-value="form.customerId" filterable placeholder="请选择客户" :loading="customersLoading" no-data-text="暂无可用客户" style="width:100%" @update:model-value="handleCustomerChange(String($event || ''))"><el-option v-for="customer in selectableCustomers" :key="String(customer.id)" :label="customerLabel(customer)" :value="String(customer.id)" /></el-select></el-form-item></el-col>
+    <el-col :xs="24" :sm="12"><el-form-item label="订舱记录" prop="oceanBookingId"><el-select v-model="form.oceanBookingId" filterable placeholder="请先选择客户，再选择订舱记录" :loading="bookingsLoading" :disabled="!form.customerId" no-data-text="该客户暂无订舱记录" style="width:100%"><el-option v-for="booking in bookings" :key="booking.id" :label="bookingLabel(booking)" :value="booking.id" /></el-select></el-form-item></el-col>
+    <el-col :xs="24" :sm="12"><el-form-item label="信息来源" prop="sourceName"><el-input v-model="form.sourceName" placeholder="如美森官网" /></el-form-item></el-col><el-col :xs="24" :sm="12"><el-form-item label="来源参考" prop="sourceRef"><el-input v-model="form.sourceRef" placeholder="查询链接或参考号" /></el-form-item></el-col>
+    <el-col :xs="24" :sm="12"><el-form-item label="船名" prop="vesselName"><el-input v-model="form.vesselName" placeholder="请输入船名" /></el-form-item></el-col><el-col :xs="24" :sm="12"><el-form-item label="航次" prop="voyageNo"><el-input v-model="form.voyageNo" placeholder="请输入航次" /></el-form-item></el-col>
+    <el-col :xs="24" :sm="12"><el-form-item label="起运港代码" prop="departurePortCode"><el-input v-model="form.departurePortCode" placeholder="例如 CNSHA" /></el-form-item></el-col><el-col :xs="24" :sm="12"><el-form-item label="目的港代码" prop="destinationPortCode"><el-input v-model="form.destinationPortCode" placeholder="例如 USLAX" /></el-form-item></el-col>
+    <el-col :xs="24" :sm="12"><el-form-item label="预计开船"><el-date-picker v-model="form.etdAt" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" placeholder="请选择预计开船时间" style="width:100%" /></el-form-item></el-col><el-col :xs="24" :sm="12"><el-form-item label="预计到港"><el-date-picker v-model="form.etaAt" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" placeholder="请选择预计到港时间" style="width:100%" /></el-form-item></el-col>
+    <el-col :xs="24" :sm="12"><el-form-item label="查询时间" prop="observedAt"><el-date-picker v-model="form.observedAt" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" placeholder="请选择本次查询时间" style="width:100%" /></el-form-item></el-col><el-col :xs="24" :sm="12"><el-form-item label="过期时间" prop="expiresAt"><el-date-picker v-model="form.expiresAt" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" placeholder="请选择结果过期时间" style="width:100%" /></el-form-item></el-col>
+    <el-col :xs="24"><el-form-item label="备注"><el-input v-model="form.remark" type="textarea" :rows="3" maxlength="500" show-word-limit placeholder="请输入船期补充说明（可选）" /></el-form-item></el-col>
+  </el-row></el-form><CarrierScheduleQueryPanel v-if="dialogReadonly && form.oceanBookingId" class="schedule-query-panel" :ocean-booking-id="form.oceanBookingId" :container-booking-id="form.containerBookingId" :port-schedule-id="editingId" /></div></AppDialog></AdminPage>
+</template>
+<style scoped>.schedule-dialog-body{max-height:65vh;overflow:auto;padding-inline:2px}.schedule-query-panel{margin-top:4px;padding-top:16px;border-top:1px solid var(--cc-border)}.selector-error{display:flex;align-items:center;justify-content:space-between;gap:8px;margin-bottom:8px;padding:6px 10px;border-radius:var(--cc-radius-sm);background:var(--cc-danger-soft);color:var(--el-color-danger);font-size:12px;line-height:20px}.selector-error span{overflow-wrap:anywhere}:global(.el-dialog:has(.schedule-form)){width:min(820px,calc(100vw - 28px))!important;max-height:90vh;overflow:hidden}@media(max-width:720px){.schedule-dialog-body{max-height:68vh}}</style>
diff --git a/src/modules/port-schedules/routes.ts b/src/modules/port-schedules/routes.ts
new file mode 100644
index 00000000..9faf8a2f
--- /dev/null
+++ b/src/modules/port-schedules/routes.ts
@@ -0,0 +1,2 @@
+import type { RouteRecordRaw } from 'vue-router'
+export const portScheduleRoutes = [{ path: 'port-schedules', name: 'port-schedules', component: () => import('./pages/PortSchedulesView.vue'), meta: { title: '船期信息', description: '维护船公司船期、查询时间与过期标识', permission: 'platform:firstleg:port-schedule:list' } }] satisfies RouteRecordRaw[]
diff --git a/src/modules/port-schedules/types.test.ts b/src/modules/port-schedules/types.test.ts
new file mode 100644
index 00000000..da5244d8
--- /dev/null
+++ b/src/modules/port-schedules/types.test.ts
@@ -0,0 +1,27 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/port-schedules/types.ts'), 'utf8')
+
+describe('phase-4 carrier node types', () => {
+  it('locks the canonical ten-node model without the retired destination alias', () => {
+    const declaration = source.match(/export type CarrierScheduleStandardNode = ([^\n]+)/)?.[1] || ''
+    for (const node of ['DEPARTED_WAREHOUSE', 'AT_ORIGIN_PORT', 'LOADED_ON_VESSEL', 'DEPARTED_ORIGIN_PORT', 'IN_TRANSIT', 'ARRIVED_DESTINATION_PORT', 'DISCHARGED_FROM_VESSEL', 'PICKUP_READY', 'PICKED_UP', 'EMPTY_RETURNED']) expect(declaration).toContain(`'${node}'`)
+    expect(declaration).not.toContain(`'${['ARR', 'IVED'].join('')}'`)
+  })
+
+  it('freezes exception facts separately from monotonic node facts', () => {
+    for (const code of ['CUSTOMS_HOLD', 'TERMINAL_HOLD', 'DOCUMENT_HOLD', 'UNKNOWN_HOLD']) expect(source).toContain(`'${code}'`)
+    expect(source).toContain('export interface CarrierScheduleExceptionFact')
+    expect(source).not.toContain('latestExceptionNode')
+  })
+
+  it('requires at least one estimated or actual time for a future manual-node request', () => {
+    expect(source).toContain("| { actualAt: string; estimatedAt?: string | null }")
+    expect(source).toContain("| { estimatedAt: string; actualAt?: string | null }")
+    expect(source).toContain('expectedVersion: number')
+    expect(source).toContain('observedAt: string')
+    expect(source).toContain('reason: string')
+  })
+})
diff --git a/src/modules/port-schedules/types.ts b/src/modules/port-schedules/types.ts
new file mode 100644
index 00000000..0228a2c5
--- /dev/null
+++ b/src/modules/port-schedules/types.ts
@@ -0,0 +1,160 @@
+export interface PortScheduleResource {
+  id: string
+  scheduleNo: string
+  customerId: string
+  oceanBookingId: string
+  containerBookingId?: string | null
+  sourceType: string
+  sourceName: string
+  sourceRef: string
+  vesselName: string
+  voyageNo: string
+  departurePortCode: string
+  departurePortName?: string | null
+  destinationPortCode: string
+  destinationPortName?: string | null
+  etdAt?: string | null
+  etaAt?: string | null
+  bookingCutoffAt?: string | null
+  customsCutoffAt?: string | null
+  portCutoffAt?: string | null
+  observedAt: string
+  expiresAt: string
+  remark?: string | null
+  version: number
+  updatedAt?: string | null
+}
+
+export interface PortScheduleView { schedule: PortScheduleResource; expired: boolean }
+export interface PortScheduleHistory { id: string; action: string; fromVersion?: number | null; toVersion?: number | null; reason?: string | null; operatorName?: string | null; createdAt: string }
+export interface PortScheduleDetail { portSchedule: PortScheduleView; histories: PortScheduleHistory[] }
+export interface PortSchedulePage { records: PortScheduleView[]; page: number; size: number; total: number; pages: number }
+export interface PortScheduleQuery { page: number; size: number; customerId?: string; keyword?: string; expired?: boolean }
+export type PortScheduleData = Omit<PortScheduleResource, 'id' | 'scheduleNo' | 'version' | 'updatedAt'>
+export interface PortScheduleSaveRequest { expectedVersion: number; data: PortScheduleData; reason?: string | null }
+
+export type CarrierScheduleQueryStatus = 'READY' | 'MANUAL_REQUIRED' | 'STOPPED'
+export type CarrierScheduleStandardNode = 'DEPARTED_WAREHOUSE' | 'AT_ORIGIN_PORT' | 'LOADED_ON_VESSEL' | 'DEPARTED_ORIGIN_PORT' | 'IN_TRANSIT' | 'ARRIVED_DESTINATION_PORT' | 'DISCHARGED_FROM_VESSEL' | 'PICKUP_READY' | 'PICKED_UP' | 'EMPTY_RETURNED'
+export type CarrierScheduleExceptionCode = 'CUSTOMS_HOLD' | 'TERMINAL_HOLD' | 'DOCUMENT_HOLD' | 'UNKNOWN_HOLD'
+
+export interface CarrierScheduleQueryResource {
+  id: string
+  queryNo: string
+  customerId: string
+  oceanBookingId: string
+  containerBookingId?: string | null
+  carrierCode: string
+  trackingType: string
+  trackingNo: string
+  officialUrl?: string | null
+  accessMode?: string | null
+  status: CarrierScheduleQueryStatus
+  triggerSource?: string | null
+  latestActualNode?: CarrierScheduleStandardNode | null
+  latestActualAt?: string | null
+  lastSuccessAt?: string | null
+  sourceUpdatedAt?: string | null
+  expiresAt?: string | null
+  resultPortScheduleId?: string | null
+  manualReason?: string | null
+  lastErrorCode?: string | null
+  lastErrorMessage?: string | null
+  stoppedAt?: string | null
+  stopReason?: string | null
+  version: number
+}
+
+export interface CarrierScheduleQueryView {
+  query: CarrierScheduleQueryResource
+  expired: boolean
+}
+
+export interface CarrierScheduleNodeFact {
+  id: string
+  providerCode: string
+  providerEventId: string
+  providerNodeCode: string
+  standardNode: CarrierScheduleStandardNode
+  nodeSequence: number
+  observedAt: string
+  estimatedAt?: string | null
+  actualAt?: string | null
+  locationCode?: string | null
+  locationName?: string | null
+  sourceReference?: string | null
+  rawPayloadHash: string
+  createdAt?: string | null
+}
+
+export interface CarrierScheduleExceptionFact {
+  id: string
+  providerCode: string
+  providerEventId: string
+  providerStatus: string
+  exceptionCode: CarrierScheduleExceptionCode
+  active: boolean
+  observedAt: string
+  locationCode?: string | null
+  locationName?: string | null
+  sourceReference?: string | null
+  rawPayloadHash: string
+  createdAt: string
+}
+
+type CarrierScheduleManualNodeBase = {
+  expectedVersion: number
+  standardNode: CarrierScheduleStandardNode
+  observedAt: string
+  locationCode?: string | null
+  locationName?: string | null
+  reason: string
+}
+export type CarrierScheduleManualNodeRequest = CarrierScheduleManualNodeBase & (
+  | { actualAt: string; estimatedAt?: string | null }
+  | { estimatedAt: string; actualAt?: string | null }
+)
+
+export type ContainerManualNodeRequest = Omit<CarrierScheduleManualNodeBase, 'expectedVersion'> & (
+  | { actualAt: string; estimatedAt?: string | null }
+  | { estimatedAt: string; actualAt?: string | null }
+)
+
+export interface ContainerShippingNodeDetail {
+  containerBookingId: string
+  currentNode?: CarrierScheduleStandardNode | null
+  currentNodeAt?: string | null
+  nodes: CarrierScheduleNodeFact[]
+}
+
+export interface CarrierScheduleQueryHistory {
+  id: string
+  action: string
+  fromVersion?: number | null
+  toVersion?: number | null
+  reason?: string | null
+  operatorId?: string | null
+  operatorName?: string | null
+  createdAt?: string | null
+}
+
+export interface CarrierScheduleQueryDetail {
+  query: CarrierScheduleQueryView
+  nodes: CarrierScheduleNodeFact[]
+  exceptions: CarrierScheduleExceptionFact[]
+  histories: CarrierScheduleQueryHistory[]
+}
+
+export interface CarrierScheduleQueryPage {
+  records: CarrierScheduleQueryView[]
+  page: number
+  size: number
+  total: number
+  pages: number
+}
+
+export interface CarrierScheduleQueryFilter {
+  page: number
+  size: number
+  oceanBookingId?: string
+  containerBookingId?: string
+}
diff --git a/src/modules/suppliers/api/platformSuppliers.test.ts b/src/modules/suppliers/api/platformSuppliers.test.ts
new file mode 100644
index 00000000..592dee42
--- /dev/null
+++ b/src/modules/suppliers/api/platformSuppliers.test.ts
@@ -0,0 +1,47 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import { changeSupplierStatus, createSupplier, getSupplier, getSupplierStats, listSuppliers, updateSupplier } from '@/modules/suppliers/api/platformSuppliers'
+import type { SaveSupplierRequest } from '@/modules/suppliers/types'
+
+vi.mock('@/shared/api/http', async (original) => ({
+  ...await original<typeof import('@/shared/api/http')>(),
+  http: { get: vi.fn(), post: vi.fn(), put: vi.fn(), patch: vi.fn() },
+}))
+
+const payload: SaveSupplierRequest = { name: '测试供应商', category: 'BOOKING', truckingScope: null, carrierCodes: ['MATSON', 'SML'], region: '宁波', legalRepresentative: '张三', contactName: '李四', phone: '13800000000', email: null, address: null, businessLicenseNo: null, licenseFileId: '9007199254740995', status: 'ACTIVE', settlementPeriod: 'MONTHLY_30', remark: null }
+const resource = { id: 9007199254740993, tenantId: 0, ...payload, createdBy: 9007199254740994, createdAt: '2026-08-13T10:00:00', updatedBy: null, updatedAt: '2026-08-13T10:00:00', deleted: false, version: 1 }
+
+describe('platform supplier API', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it('uses real list and stats endpoints and preserves long identifiers as strings', async () => {
+    vi.mocked(http.get)
+      .mockResolvedValueOnce({ code: '200', data: { records: [resource], page: 1, size: 20, total: 1, pages: 1 } })
+      .mockResolvedValueOnce({ code: '200', data: { booking: 1, customs: 2, trucking: 3, certificate: 4 } })
+    const page = await listSuppliers({ page: 1, size: 20, category: 'BOOKING', keyword: '测试', carrierCode: 'MATSON' })
+    expect(http.get).toHaveBeenNthCalledWith(1, '/platform/v1/suppliers', { params: expect.objectContaining({ category: 'BOOKING', keyword: '测试', carrierCode: 'MATSON' }) })
+    expect(vi.mocked(http.get).mock.calls[0]?.[1]?.params).not.toHaveProperty('scope')
+    expect(page.records[0]).toMatchObject({ id: expect.any(String), tenantId: '0', carrierCodes: ['MATSON', 'SML'], licenseFileId: expect.any(String), createdBy: expect.any(String) })
+    expect(await getSupplierStats()).toEqual({ booking: 1, customs: 2, trucking: 3, certificate: 4 })
+    expect(http.get).toHaveBeenNthCalledWith(2, '/platform/v1/suppliers/stats')
+  })
+
+  it('sends tenantId=0 on detail and every write', async () => {
+    vi.mocked(http.get).mockResolvedValue({ code: '200', data: resource })
+    vi.mocked(http.post).mockResolvedValue({ code: '200', data: '77' })
+    vi.mocked(http.put).mockResolvedValue({ code: '200', data: null })
+    vi.mocked(http.patch).mockResolvedValue({ code: '200', data: null })
+    await getSupplier('77'); await createSupplier(payload); await updateSupplier('77', payload); await changeSupplierStatus('77', 'INACTIVE')
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/suppliers/77', { params: { tenantId: 0 } })
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/suppliers', payload, { params: { tenantId: 0 } })
+    expect(http.put).toHaveBeenCalledWith('/platform/v1/suppliers/77', payload, { params: { tenantId: 0 } })
+    expect(http.patch).toHaveBeenCalledWith('/platform/v1/suppliers/77/status', { status: 'INACTIVE' }, { params: { tenantId: 0 } })
+  })
+  it('passes the trucking scope filter and keeps the authoritative type in resources', async () => {
+    vi.mocked(http.get).mockResolvedValue({ code: '200', data: { records: [{ ...resource, category: 'TRUCKING', carrierCodes: [], truckingScope: 'OVERSEAS' }], page: 1, size: 20, total: 1, pages: 1 } })
+    const page = await listSuppliers({ category: 'TRUCKING', truckingScope: 'OVERSEAS', status: 'ACTIVE' })
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/suppliers', { params: expect.objectContaining({ category: 'TRUCKING', truckingScope: 'OVERSEAS', status: 'ACTIVE' }) })
+    expect(page.records[0]?.truckingScope).toBe('OVERSEAS')
+  })
+
+})
diff --git a/src/modules/suppliers/api/platformSuppliers.ts b/src/modules/suppliers/api/platformSuppliers.ts
new file mode 100644
index 00000000..0b19f7bf
--- /dev/null
+++ b/src/modules/suppliers/api/platformSuppliers.ts
@@ -0,0 +1,55 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import type { SaveSupplierRequest, Supplier, SupplierPage, SupplierQuery, SupplierStats, SupplierStatus } from '@/modules/suppliers/types'
+
+const basePath = '/platform/v1/suppliers'
+const platformScope = 0
+const id = (value: string | number | null | undefined) => value == null ? null : String(value)
+
+function normalizeSupplier(raw: Supplier): Supplier {
+  return {
+    ...raw,
+    id: String(raw.id), tenantId: String(raw.tenantId),
+    carrierCodes: [...(raw.carrierCodes || [])],
+    licenseFileId: id(raw.licenseFileId), createdBy: id(raw.createdBy), updatedBy: id(raw.updatedBy),
+    version: Number(raw.version), deleted: Boolean(raw.deleted),
+  }
+}
+
+export async function listSuppliers(query: SupplierQuery): Promise<SupplierPage> {
+  const response = await http.get<ApiEnvelope<SupplierPage>, ApiEnvelope<SupplierPage>>(basePath, {
+    params: {
+      page: query.page ?? 1, size: query.size ?? 20, category: query.category,
+      region: query.region?.trim() || undefined,
+      status: query.status || undefined, keyword: query.keyword?.trim() || undefined,
+      carrierCode: query.carrierCode || undefined, truckingScope: query.truckingScope,
+    },
+  })
+  const data = unwrapApiResponse(response)
+  return { records: data.records.map(normalizeSupplier), page: Number(data.page), size: Number(data.size), total: Number(data.total), pages: Number(data.pages) }
+}
+
+export async function getSupplierStats(): Promise<SupplierStats> {
+  const response = await http.get<ApiEnvelope<SupplierStats>, ApiEnvelope<SupplierStats>>(`${basePath}/stats`)
+  const data = unwrapApiResponse(response)
+  return { booking: Number(data.booking), customs: Number(data.customs), trucking: Number(data.trucking), certificate: Number(data.certificate) }
+}
+
+export async function getSupplier(supplierId: string): Promise<Supplier> {
+  const response = await http.get<ApiEnvelope<Supplier>, ApiEnvelope<Supplier>>(`${basePath}/${encodeURIComponent(supplierId)}`, { params: { tenantId: platformScope } })
+  return normalizeSupplier(unwrapApiResponse(response))
+}
+
+export async function createSupplier(payload: SaveSupplierRequest): Promise<string> {
+  const response = await http.post<ApiEnvelope<string | number>, ApiEnvelope<string | number>>(basePath, payload, { params: { tenantId: platformScope } })
+  return String(unwrapApiResponse(response))
+}
+
+export async function updateSupplier(supplierId: string, payload: SaveSupplierRequest): Promise<null> {
+  const response = await http.put<ApiEnvelope<null>, ApiEnvelope<null>>(`${basePath}/${encodeURIComponent(supplierId)}`, payload, { params: { tenantId: platformScope } })
+  return unwrapApiResponse(response)
+}
+
+export async function changeSupplierStatus(supplierId: string, status: SupplierStatus): Promise<null> {
+  const response = await http.patch<ApiEnvelope<null>, ApiEnvelope<null>>(`${basePath}/${encodeURIComponent(supplierId)}/status`, { status }, { params: { tenantId: platformScope } })
+  return unwrapApiResponse(response)
+}
diff --git a/src/modules/suppliers/components/SupplierLicenseDialog.vue b/src/modules/suppliers/components/SupplierLicenseDialog.vue
new file mode 100644
index 00000000..f6f9ea53
--- /dev/null
+++ b/src/modules/suppliers/components/SupplierLicenseDialog.vue
@@ -0,0 +1,38 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import type { Supplier } from '@/modules/suppliers/types'
+
+defineProps<{ supplier: Supplier | null }>()
+const open = defineModel<boolean>({ default: false })
+</script>
+
+<template>
+  <AppDialog class="admin-density-dialog" v-model="open" :title="`营业执照查看${supplier ? ` - ${supplier.name}` : ''}`" width="min(560px, calc(100vw - 24px))" :show-confirm="false" cancel-text="关闭">
+    <div v-if="supplier" class="license-dialog">
+      <p class="license-dialog__supplier">供应商：<strong>{{ supplier.name }}</strong></p>
+      <section class="license-card" aria-label="营业执照信息">
+        <h2>营业执照</h2><p class="license-card__copy">（副本）</p>
+        <dl>
+          <div><dt>名称：</dt><dd>{{ supplier.name }}</dd></div>
+          <div><dt>法定代表人：</dt><dd>{{ supplier.legalRepresentative }}</dd></div>
+          <div><dt>统一社会信用代码：</dt><dd>{{ supplier.businessLicenseNo || '—' }}</dd></div>
+          <div><dt>资质文件：</dt><dd>{{ supplier.licenseFileId ? '已关联' : '未上传' }}</dd></div>
+        </dl>
+      </section>
+      <el-alert v-if="supplier.licenseFileId" class="license-dialog__notice" type="info" :closable="false" show-icon title="资质文件已保留；平台公共供应商文件读取接口尚未提供，暂无法展示原始影像。" />
+    </div>
+  </AppDialog>
+</template>
+
+<style scoped>
+.license-dialog__supplier { margin: 0 0 var(--admin-space-5); color: var(--cc-muted); font-size: var(--admin-font-body); }
+.license-card { max-width: 460px; margin: 0 auto; padding: var(--admin-space-7) var(--admin-space-7); border: 2px solid #c0392b; border-radius: var(--admin-radius); background: #fff; box-shadow: 0 4px 16px rgba(192,57,43,.12); }
+.license-card h2 { margin: 0; color: #c0392b; font-size: 22px; letter-spacing: 6px; text-align: center; }
+.license-card__copy { margin: 2px 0 var(--admin-space-6); color: #c0392b; font-size: var(--admin-font-caption); text-align: center; }
+.license-card dl { margin: 0; }
+.license-card dl div { display: grid; grid-template-columns: 126px minmax(0, 1fr); margin-bottom: var(--admin-space-4); font-size: var(--admin-font-body); }
+.license-card dt { color: #444; font-weight: 700; }.license-card dd { min-width: 0; margin: 0; overflow-wrap: anywhere; }
+.license-dialog__notice { margin-top: var(--admin-space-6); }
+@media (max-width: 480px) { .license-card { padding: 20px 16px; } .license-card dl div { grid-template-columns: 1fr; gap: 3px; } .license-card h2 { font-size: 19px; } }
+</style>
diff --git a/src/modules/suppliers/index.ts b/src/modules/suppliers/index.ts
new file mode 100644
index 00000000..846c5946
--- /dev/null
+++ b/src/modules/suppliers/index.ts
@@ -0,0 +1,3 @@
+export { listSuppliers } from './api/platformSuppliers'
+export { categoryLabels } from './types'
+export type { Supplier, SupplierPage, SupplierQuery, SupplierCategory } from './types'
diff --git a/src/modules/suppliers/pages/SupplierDetailView.vue b/src/modules/suppliers/pages/SupplierDetailView.vue
new file mode 100644
index 00000000..3429080b
--- /dev/null
+++ b/src/modules/suppliers/pages/SupplierDetailView.vue
@@ -0,0 +1,67 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, ref, watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { ArrowLeft, FileText, Pencil } from '@lucide/vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import DetailPageLayout from '@/shared/components/DetailPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import SupplierLicenseDialog from '@/modules/suppliers/components/SupplierLicenseDialog.vue'
+import { getSupplier } from '@/modules/suppliers/api/platformSuppliers'
+import { formatTruckingScope, categoryLabels, formatCarrierCodes, settlementLabels, statusLabels, type Supplier } from '@/modules/suppliers/types'
+
+const route = useRoute(); const router = useRouter(); const access = useAccessPreviewStore()
+const canView = computed(() => access.can('platform:supplier:list'))
+const supplierId = computed(() => typeof route.params.id === 'string' ? route.params.id : '')
+const supplier = ref<Supplier | null>(null); const loading = ref(false); const error = ref<ApiErrorDetails | null>(null); const licenseOpen = ref(false)
+let loadSequence = 0
+const items = computed(() => supplier.value ? [
+  ['供应商名称', supplier.value.name], ['供应商类别', categoryLabels[supplier.value.category]], ['可代理船公司', supplier.value.category === 'BOOKING' ? formatCarrierCodes(supplier.value.carrierCodes) : '—'], ['地区', supplier.value.region],
+  ...(supplier.value.category === 'TRUCKING' ? [['拖车类型', formatTruckingScope(supplier.value.truckingScope)]] : []),
+  ['法人代表', supplier.value.legalRepresentative], ['联系人', supplier.value.contactName], ['联系电话', supplier.value.phone], ['电子邮箱', supplier.value.email || '—'],
+  ['营业执照号', supplier.value.businessLicenseNo || '—'], ['结算周期', settlementLabels[supplier.value.settlementPeriod]], ['公司地址', supplier.value.address || '—'], ['备注', supplier.value.remark || '—'],
+] : [])
+async function load() {
+  const requestedId = supplierId.value
+  const sequence = ++loadSequence
+  if (!canView.value || !requestedId) { supplier.value = null; loading.value = false; error.value = null; return }
+  supplier.value = null
+  loading.value = true
+  error.value = null
+  try {
+    const result = await getSupplier(requestedId)
+    if (sequence !== loadSequence || requestedId !== supplierId.value) return
+    supplier.value = result
+  } catch (cause) {
+    if (sequence !== loadSequence || requestedId !== supplierId.value) return
+    error.value = getApiErrorDetails(cause, '供应商详情加载失败')
+  } finally {
+    if (sequence === loadSequence) loading.value = false
+  }
+}
+watch(supplierId, () => { void load() }, { immediate: true })
+</script>
+
+<template>
+  <AdminPage class="admin-density" ><DetailPageLayout class="density-detail-layout surface-panel" aria-label="供应商详情">
+    <template #header><div class="density-detail-header"><div class="density-detail-heading"><el-button link class="density-back" @click="router.push({ name: 'supplier-list' })"><ArrowLeft :size="16" />返回列表</el-button><h1 class="density-detail-title">{{ supplier?.name || '供应商详情' }}</h1><StatusBadge v-if="supplier" :status="statusLabels[supplier.status]" /></div><el-button v-if="supplier && access.can('platform:supplier:edit')" type="primary" @click="router.push({ name: 'supplier-edit', params: { id: supplier.id } })"><Pencil :size="16" />编辑</el-button></div></template>
+    <LoadErrorState v-if="!canView" title="暂无供应商查看权限" message="请联系管理员开通供应商查看权限。" :show-retry="false" />
+    <LoadErrorState v-else-if="error" title="供应商详情加载失败" :message="error.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="error" /></template></LoadErrorState>
+    <section v-else v-loading="loading" class="detail-panel">
+      <dl v-if="supplier" class="detail-grid density-fields"><div v-for="item in items" :key="item[0]" :class="{ 'wide-field': ['可代理船公司', '公司地址', '备注'].includes(item[0]) }"><dt>{{ item[0] }}</dt><dd>{{ item[1] }}</dd></div></dl>
+      <div v-if="supplier" class="license-row"><div><strong>营业执照</strong><span>{{ supplier.licenseFileId ? '已关联资质文件' : '未上传资质文件' }}</span></div><el-button type="primary" plain @click="licenseOpen = true"><FileText :size="16" />查看营业执照</el-button></div>
+    </section>
+    <SupplierLicenseDialog v-model="licenseOpen" :supplier="supplier" />
+  </DetailPageLayout></AdminPage>
+</template>
+
+<style scoped>
+.detail-actions :deep(.el-button + .el-button) { margin-left: 0; }
+.detail-panel { min-width: 0; }
+.detail-grid .wide-field { grid-column: span 2; }.license-row { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-6); margin-top: var(--admin-space-7); padding: var(--admin-space-6); border: 1px dashed var(--cc-border); border-radius: var(--admin-radius); background: #fafafa; }.license-row strong,.license-row span { display: block; }.license-row span { margin-top: var(--admin-space-1); color: var(--cc-muted); font-size: var(--admin-font-caption); }
+@media (max-width: 720px) { .detail-header,.license-row { align-items: stretch; flex-direction: column; }.detail-actions { display: grid !important; grid-template-columns: 1fr 1fr; }.detail-actions :deep(.el-button) { min-height: 44px; }.detail-grid { grid-template-columns: 1fr; }.detail-grid div,.detail-grid div:nth-child(3n) { border-right: 0; }.detail-panel { padding: 16px; } }
+</style>
diff --git a/src/modules/suppliers/pages/SupplierFormView.vue b/src/modules/suppliers/pages/SupplierFormView.vue
new file mode 100644
index 00000000..121c45de
--- /dev/null
+++ b/src/modules/suppliers/pages/SupplierFormView.vue
@@ -0,0 +1,143 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onActivated, onDeactivated, reactive, ref, watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { ElMessage, type FormInstance, type FormRules } from 'element-plus'
+import { ArrowLeft, FileText, Save } from '@lucide/vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import OperationErrorToast from '@/shared/components/OperationErrorToast.vue'
+import DetailPageLayout from '@/shared/components/DetailPageLayout.vue'
+import FormSection from '@/shared/components/FormSection.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useUnsavedWorkRegistration } from '@/core/unsaved-work/useUnsavedWorkRegistration'
+import { createSupplier, getSupplier, updateSupplier } from '@/modules/suppliers/api/platformSuppliers'
+import { truckingScopeLabels, carrierCodeOptions, categoryLabels, settlementLabels, statusLabels, type TruckingScope, type SaveSupplierRequest } from '@/modules/suppliers/types'
+
+const route = useRoute()
+const router = useRouter()
+const access = useAccessPreviewStore()
+const supplierId = computed(() => typeof route.params.id === 'string' ? route.params.id : '')
+const editing = computed(() => Boolean(supplierId.value))
+const requiredPermission = computed(() => editing.value ? 'platform:supplier:edit' : 'platform:supplier:create')
+const formRef = ref<FormInstance>()
+const loading = ref(false)
+const saving = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const submitError = ref<ApiErrorDetails | null>(null)
+const initial = (): SaveSupplierRequest => ({ name: '', category: 'BOOKING', truckingScope: null, carrierCodes: [], region: '', legalRepresentative: '', contactName: '', phone: '', email: null, address: null, businessLicenseNo: null, licenseFileId: null, status: 'ACTIVE', settlementPeriod: 'MONTHLY_30', remark: null })
+const form = reactive(initial())
+const saveAttempted = ref(false)
+const truckingScopeError = computed(() => saveAttempted.value && form.category === 'TRUCKING' && !form.truckingScope ? '请选择国内拖车或海外车队' : '')
+const rules: FormRules<SaveSupplierRequest> = {
+  name: [{ required: true, message: '请输入供应商名称', trigger: 'blur' }], category: [{ required: true, message: '请选择供应商类别', trigger: 'change' }],
+  truckingScope: [{ required: true, type: 'enum', enum: ['DOMESTIC', 'OVERSEAS'], message: '请选择国内拖车或海外车队', trigger: 'change' }],
+  carrierCodes: [{ validator: (_rule, value, callback) => form.category === 'BOOKING' && (!Array.isArray(value) || value.length === 0) ? callback(new Error('请至少选择一家可代理船公司')) : callback(), trigger: 'change' }],
+  region: [{ required: true, message: '请输入地区', trigger: 'blur' }], legalRepresentative: [{ required: true, message: '请输入法人代表', trigger: 'blur' }],
+  contactName: [{ required: true, message: '请输入联系人', trigger: 'blur' }], phone: [{ required: true, message: '请输入联系电话', trigger: 'blur' }],
+  email: [{ type: 'email', message: '请输入正确的邮箱地址', trigger: 'blur' }], status: [{ required: true, message: '请选择合作状态', trigger: 'change' }],
+  settlementPeriod: [{ required: true, message: '请选择结算周期', trigger: 'change' }],
+}
+const { captureBaseline } = useUnsavedWorkRegistration({ key: 'supplier-editor', label: computed(() => editing.value ? '编辑供应商' : '新增供应商'), isOpen: computed(() => true), model: form, requiredPermission })
+
+function optional(value: string | null) { return value?.trim() || null }
+function payload(): SaveSupplierRequest {
+  const { carrierCodes, ...fields } = form
+  const normalized = { ...fields, truckingScope: form.category === 'TRUCKING' ? form.truckingScope : null, name: form.name.trim(), region: form.region.trim(), legalRepresentative: form.legalRepresentative.trim(), contactName: form.contactName.trim(), phone: form.phone.trim(), email: optional(form.email), address: optional(form.address), businessLicenseNo: optional(form.businessLicenseNo), licenseFileId: form.licenseFileId, remark: optional(form.remark) }
+  return form.category === 'BOOKING' ? { ...normalized, carrierCodes: [...(carrierCodes || [])] } : normalized
+}
+let loadSequence = 0
+function resetForm() { Object.assign(form, initial()); saveAttempted.value = false }
+async function load() {
+  const requestedId = supplierId.value
+  const sequence = ++loadSequence
+  resetForm()
+  loadError.value = null
+  submitError.value = null
+  saving.value = false
+  if (!requestedId || !access.can(requiredPermission.value)) { loading.value = false; captureBaseline(); return }
+  loading.value = true
+  try {
+    const data = await getSupplier(requestedId)
+    if (sequence !== loadSequence || requestedId !== supplierId.value) return
+    Object.assign(form, { name: data.name, category: data.category, truckingScope: data.truckingScope, carrierCodes: data.category === 'BOOKING' ? [...data.carrierCodes] : [], region: data.region, legalRepresentative: data.legalRepresentative, contactName: data.contactName, phone: data.phone, email: data.email, address: data.address, businessLicenseNo: data.businessLicenseNo, licenseFileId: data.licenseFileId, status: data.status, settlementPeriod: data.settlementPeriod, remark: data.remark })
+    captureBaseline()
+  } catch (error) {
+    if (sequence === loadSequence && requestedId === supplierId.value) loadError.value = getApiErrorDetails(error, '供应商详情加载失败')
+  } finally { if (sequence === loadSequence) loading.value = false }
+}
+async function save() {
+  if (!access.can(requiredPermission.value)) return
+  saveAttempted.value = true
+  if (truckingScopeError.value) return
+  if (!await formRef.value?.validate().catch(() => false)) return
+  saving.value = true; submitError.value = null
+  try {
+    if (editing.value) await updateSupplier(supplierId.value, payload())
+    else await createSupplier(payload())
+    captureBaseline(); ElMessage.success(editing.value ? '供应商修改成功' : '供应商新增成功')
+    await router.push({ name: 'supplier-list' })
+  } catch (error) { submitError.value = getApiErrorDetails(error, editing.value ? '供应商修改失败' : '供应商新增失败') } finally { saving.value = false }
+}
+
+let active = true
+let activatedOnce = false
+watch(supplierId, () => { if (active) void load() }, { immediate: true })
+onActivated(() => {
+  active = true
+  if (activatedOnce) void load()
+  else activatedOnce = true
+})
+onDeactivated(() => { active = false })
+watch(() => form.category, (category) => { if (category !== 'BOOKING') form.carrierCodes = []; if (category !== 'TRUCKING') form.truckingScope = null })
+</script>
+
+<template>
+  <AdminPage class="admin-density" >
+    <OperationErrorToast :details="submitError" />
+    <DetailPageLayout class="density-detail-layout surface-panel" :aria-label="editing ? '编辑供应商' : '新增供应商'">
+      <template #header><div class="density-detail-header"><div class="density-detail-heading"><el-button link class="density-back" @click="router.push({ name: 'supplier-list' })"><ArrowLeft :size="16" />返回列表</el-button><h1 class="density-detail-title">{{ editing ? '编辑供应商' : '新增供应商' }}</h1></div></div></template>
+      <LoadErrorState v-if="!access.can(requiredPermission)" title="暂无操作权限" :message="`请联系管理员开通${editing ? '供应商编辑' : '供应商新增'}权限。`" :show-retry="false" />
+      <LoadErrorState v-else-if="loadError" title="供应商加载失败" :message="loadError.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="loadError" /></template></LoadErrorState>
+      <section v-else v-loading="loading" class="supplier-form-panel">
+        <el-form class="density-form" ref="formRef" :model="form" :rules="rules" label-position="top" :disabled="saving">
+          <FormSection class="density-form-section" title="基础信息">
+            <div class="form-grid">
+              <el-form-item label="供应商名称" prop="name"><el-input v-model="form.name" maxlength="160" placeholder="请输入供应商名称" /></el-form-item>
+              <el-form-item label="供应商类别" prop="category"><el-select v-model="form.category"><el-option v-for="(label, value) in categoryLabels" :key="value" :label="label" :value="value" /></el-select></el-form-item>
+              <el-form-item v-if="form.category === 'BOOKING'" label="可代理船公司" prop="carrierCodes"><el-select v-model="form.carrierCodes" multiple collapse-tags collapse-tags-tooltip placeholder="请选择可代理船公司"><el-option v-for="option in carrierCodeOptions" :key="option.value" :label="option.label" :value="option.value" /></el-select></el-form-item>
+              <el-form-item v-if="form.category === 'TRUCKING'" label="拖车类型" prop="truckingScope" :error="truckingScopeError" required><el-radio-group :model-value="form.truckingScope ?? undefined" @update:model-value="form.truckingScope = $event as TruckingScope"><el-radio v-for="(label, value) in truckingScopeLabels" :key="value" :value="value">{{ label }}</el-radio></el-radio-group></el-form-item>
+              <el-form-item label="地区" prop="region"><el-input v-model="form.region" maxlength="80" placeholder="请输入地区" /></el-form-item>
+              <el-form-item label="法人代表" prop="legalRepresentative"><el-input v-model="form.legalRepresentative" maxlength="80" placeholder="请输入法人代表" /></el-form-item>
+              <el-form-item label="联系人" prop="contactName"><el-input v-model="form.contactName" maxlength="80" placeholder="请输入联系人" /></el-form-item>
+              <el-form-item label="联系电话" prop="phone"><el-input v-model="form.phone" maxlength="40" placeholder="请输入联系电话" /></el-form-item>
+              <el-form-item label="电子邮箱" prop="email"><el-input v-model="form.email" maxlength="160" placeholder="请输入邮箱" /></el-form-item>
+              <el-form-item label="合作状态" prop="status"><el-select v-model="form.status"><el-option v-for="(label, value) in statusLabels" :key="value" :label="label" :value="value" /></el-select></el-form-item>
+              <el-form-item label="结算周期" prop="settlementPeriod"><el-select v-model="form.settlementPeriod"><el-option v-for="(label, value) in settlementLabels" :key="value" :label="label" :value="value" /></el-select></el-form-item>
+              <el-form-item class="span-2" label="公司地址" prop="address"><el-input v-model="form.address" maxlength="255" placeholder="请输入公司地址" /></el-form-item>
+            </div>
+          </FormSection>
+          <FormSection class="density-form-section" title="营业执照">
+            <div class="form-grid">
+              <el-form-item label="营业执照号" prop="businessLicenseNo"><el-input v-model="form.businessLicenseNo" maxlength="64" placeholder="统一社会信用代码" /></el-form-item>
+              <el-form-item label="资质文件"><div class="file-placeholder"><FileText :size="24" /><span>{{ form.licenseFileId ? '已保留现有营业执照文件' : '暂无营业执照文件' }}</span><small>平台公共供应商资质上传接口尚未提供，当前不能新增或替换文件。</small></div></el-form-item>
+            </div>
+          </FormSection>
+          <FormSection class="density-form-section" title="其他信息"><el-form-item label="备注" prop="remark"><el-input v-model="form.remark" type="textarea" :rows="3" maxlength="500" show-word-limit placeholder="请输入备注" /></el-form-item></FormSection>
+        </el-form>
+        <footer class="form-actions"><el-button type="primary" :loading="saving" @click="save"><Save :size="16" />保存</el-button><el-button :disabled="saving" @click="router.push({ name: 'supplier-list' })">取消</el-button></footer>
+      </section>
+    </DetailPageLayout>
+  </AdminPage>
+</template>
+
+<style scoped>
+.supplier-form-panel { min-width: 0; }.form-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 0 var(--admin-space-7); }.span-2 { grid-column: 1 / -1; }
+.form-grid :deep(.el-select) { width: 100%; }.file-placeholder { display: flex; width: 100%; min-height: 96px; align-items: center; justify-content: center; flex-direction: column; gap: var(--admin-space-2); padding: var(--admin-space-6); border: 1px dashed #d9d9d9; border-radius: var(--admin-radius); background: #fafafa; color: var(--cc-muted); text-align: center; }.file-placeholder small { max-width: 420px; line-height: 1.5; }
+.form-actions { display: flex; justify-content: center; gap: var(--admin-space-5); padding: var(--admin-space-6) 0 0; border-top: 1px solid var(--cc-border); }.form-actions :deep(.el-button) { min-width: 112px; margin-left: 0; }
+@media (min-width: 1600px) { .form-grid { grid-template-columns: repeat(4, minmax(0, 1fr)); } }
+@media (min-width: 1280px) and (max-width: 1599px) { .form-grid { grid-template-columns: repeat(3, minmax(0, 1fr)); } }
+@media (max-width: 720px) { .supplier-form-panel { padding: 16px; } .form-grid { grid-template-columns: 1fr; }.span-2 { grid-column: auto; }.form-page-header { align-items: stretch; flex-direction: column; }.form-actions { flex-direction: column; }.form-actions :deep(.el-button) { width: 100%; min-height: 44px; } }
+</style>
diff --git a/src/modules/suppliers/pages/SupplierRouteReuse.behavior.test.ts b/src/modules/suppliers/pages/SupplierRouteReuse.behavior.test.ts
new file mode 100644
index 00000000..05270b13
--- /dev/null
+++ b/src/modules/suppliers/pages/SupplierRouteReuse.behavior.test.ts
@@ -0,0 +1,175 @@
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { defineComponent, reactive, nextTick, ref } from 'vue'
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
+import ElementPlus from 'element-plus'
+import type { Component } from 'vue'
+import type { Supplier } from '@/modules/suppliers/types'
+
+const mocks = vi.hoisted(() => ({
+  route: null as null | { params: { id: string } },
+  push: vi.fn(), getSupplier: vi.fn(), updateSupplier: vi.fn(), createSupplier: vi.fn(),
+  listSuppliers: vi.fn(), getSupplierStats: vi.fn(), changeSupplierStatus: vi.fn(),
+  can: vi.fn((permission: string) => permission === 'platform:supplier:list' || permission === 'platform:supplier:edit' || permission === 'platform:supplier:create'),
+}))
+const routeState = reactive({ params: { id: 'A' } })
+mocks.route = routeState
+let SupplierFormView: Component
+let SupplierDetailView: Component
+let SuppliersView: Component
+
+vi.mock('vue-router', () => ({ useRoute: () => mocks.route, useRouter: () => ({ push: mocks.push }) }))
+vi.mock('@/core/access/accessPreview', () => ({ useAccessPreviewStore: () => ({ can: mocks.can }) }))
+vi.mock('@/core/unsaved-work/useUnsavedWorkRegistration', () => ({ useUnsavedWorkRegistration: () => ({ captureBaseline: vi.fn() }) }))
+vi.mock('@/modules/suppliers/api/platformSuppliers', () => ({
+  getSupplier: mocks.getSupplier, updateSupplier: mocks.updateSupplier, createSupplier: mocks.createSupplier,
+  listSuppliers: mocks.listSuppliers, getSupplierStats: mocks.getSupplierStats, changeSupplierStatus: mocks.changeSupplierStatus,
+}))
+
+function supplier(id: string, name: string): Supplier {
+  return { id, tenantId: '0', name, category: 'BOOKING', truckingScope: null, carrierCodes: ['MATSON', 'SML'], region: '宁波', legalRepresentative: '法人', contactName: '联系人', phone: '13800000000', email: null, address: null, businessLicenseNo: null, licenseFileId: null, status: 'ACTIVE', settlementPeriod: 'MONTHLY_30', remark: null, createdBy: null, createdAt: '', updatedBy: null, updatedAt: '', deleted: false, version: 1 }
+}
+
+function deferred<T>() {
+  let resolve!: (value: T) => void
+  const promise = new Promise<T>((next) => { resolve = next })
+  return { promise, resolve }
+}
+
+const stubs = {
+  AdminPage: { template: '<main><slot /></main>' },
+  DetailPageLayout: { template: '<article><slot name="header"/><slot /></article>' },
+  FormSection: { template: '<section><slot /></section>' },
+  ApiErrorMeta: { template: '<span />' },
+  LoadErrorState: { template: '<div class="load-error"><slot name="details" /></div>' },
+  SupplierLicenseDialog: { template: '<div />' },
+  ListPageLayout: { template: '<section><slot name="toolbar"/><slot name="state"/><slot/></section>' },
+  QueryToolbar: { template: '<div />' },
+  DataTable: { template: '<div><slot name="toolbar-actions"/></div>' },
+  StatusBadge: { template: '<span />' },
+}
+enableAutoUnmount(afterEach)
+
+describe('supplier route reuse', () => {
+  beforeAll(async () => {
+    SupplierFormView = (await import('@/modules/suppliers/pages/SupplierFormView.vue')).default
+    SupplierDetailView = (await import('@/modules/suppliers/pages/SupplierDetailView.vue')).default
+    SuppliersView = (await import('@/modules/suppliers/pages/SuppliersView.vue')).default
+  })
+  beforeEach(() => {
+    routeState.params.id = 'A'
+    mocks.push.mockReset(); mocks.getSupplier.mockReset(); mocks.updateSupplier.mockReset().mockResolvedValue(null); mocks.createSupplier.mockReset().mockResolvedValue('99')
+    mocks.listSuppliers.mockReset().mockResolvedValue({ records: [], page: 1, size: 20, total: 0, pages: 0 })
+    mocks.getSupplierStats.mockReset().mockResolvedValue({ booking: 0, customs: 0, trucking: 0, certificate: 0 })
+    mocks.changeSupplierStatus.mockReset().mockResolvedValue(null)
+    mocks.can.mockClear()
+  })
+
+  it('retains all supplier facts with long values and the original back target', async () => {
+    const name = '供应商完整长名称'.repeat(6)
+    const address = '浙江省宁波市完整详细地址'.repeat(8)
+    mocks.getSupplier.mockResolvedValue({ ...supplier('A', name), address, remark: '备注'.repeat(50) })
+    const wrapper = mount(SupplierDetailView, { global: { plugins: [ElementPlus], stubs } })
+    await flushPromises()
+    expect(wrapper.get('.density-detail-title').text()).toBe(name)
+    expect(wrapper.get('.density-fields').findAll('dt')).toHaveLength(12)
+    expect(wrapper.get('.density-fields').text()).toContain(address)
+    expect(wrapper.findAll('.wide-field')).toHaveLength(3)
+    await wrapper.get('.density-back').trigger('click')
+    expect(mocks.push).toHaveBeenCalledWith({ name: 'supplier-list' })
+  })
+
+  it('reloads form A to B, ignores late A, and submits B', async () => {
+    const requestA = deferred<Supplier>(); const requestB = deferred<Supplier>()
+    mocks.getSupplier.mockImplementation((id: string) => id === 'A' ? requestA.promise : requestB.promise)
+    const wrapper = mount(SupplierFormView, { global: { plugins: [ElementPlus], stubs } })
+    expect(mocks.getSupplier).toHaveBeenCalledWith('A')
+
+    routeState.params.id = 'B'
+    await nextTick()
+    expect(mocks.getSupplier).toHaveBeenLastCalledWith('B')
+    requestB.resolve(supplier('B', '供应商B')); await flushPromises()
+    expect((wrapper.find('input').element as HTMLInputElement).value).toBe('供应商B')
+    requestA.resolve(supplier('A', '供应商A')); await flushPromises()
+    expect((wrapper.find('input').element as HTMLInputElement).value).toBe('供应商B')
+    expect((wrapper.find('input').element as HTMLInputElement).value).not.toBe('供应商A')
+
+    const saveButton = wrapper.findAll('button').find((button) => button.text().includes('保存'))
+    expect(saveButton).toBeDefined()
+    await saveButton!.trigger('click')
+    await flushPromises()
+    expect(mocks.updateSupplier).toHaveBeenCalledWith('B', expect.objectContaining({ name: '供应商B', carrierCodes: ['MATSON', 'SML'] }))
+    expect(mocks.push).toHaveBeenCalledWith({ name: 'supplier-list' })
+  })
+
+  it('reloads detail A to B when the route is reused', async () => {
+    const requestA = deferred<Supplier>(); const requestB = deferred<Supplier>()
+    mocks.getSupplier.mockImplementation((id: string) => id === 'A' ? requestA.promise : requestB.promise)
+    const wrapper = mount(SupplierDetailView, { global: { plugins: [ElementPlus], stubs } })
+    routeState.params.id = 'B'; await nextTick()
+    requestB.resolve(supplier('B', '供应商B')); await flushPromises()
+    expect(wrapper.text()).toContain('供应商B')
+    requestA.resolve(supplier('A', '供应商A')); await flushPromises()
+    expect(wrapper.text()).toContain('供应商B')
+    expect(wrapper.text()).not.toContain('供应商A')
+  })
+
+  it('resets a cached create form every time it is activated', async () => {
+    routeState.params.id = ''
+    const active = ref(true)
+    const Host = defineComponent({
+      components: { SupplierFormView },
+      setup: () => ({ active }),
+      template: '<KeepAlive><SupplierFormView v-if="active" /></KeepAlive>',
+    })
+    const wrapper = mount(Host, { global: { plugins: [ElementPlus], stubs } })
+    await nextTick()
+    const name = wrapper.find('input[placeholder="请输入供应商名称"]')
+    await name.setValue('上一次新增的数据')
+    expect((name.element as HTMLInputElement).value).toBe('上一次新增的数据')
+
+    active.value = false; await nextTick()
+    active.value = true; await nextTick()
+
+    expect((wrapper.find('input[placeholder="请输入供应商名称"]').element as HTMLInputElement).value).toBe('')
+    expect(mocks.getSupplier).not.toHaveBeenCalled()
+  })
+
+  it('reloads the cached supplier list every time it is activated', async () => {
+    routeState.params.id = ''
+    const active = ref(true)
+    const Host = defineComponent({
+      components: { SuppliersView },
+      setup: () => ({ active }),
+      template: '<KeepAlive><SuppliersView v-if="active" /></KeepAlive>',
+    })
+    mount(Host, { global: { plugins: [ElementPlus], stubs } })
+    await flushPromises()
+    expect(mocks.listSuppliers).toHaveBeenCalledTimes(1)
+
+    active.value = false; await nextTick()
+    active.value = true; await flushPromises()
+
+    expect(mocks.listSuppliers).toHaveBeenCalledTimes(2)
+    expect(mocks.getSupplierStats).toHaveBeenCalledTimes(2)
+  })
+  it('requires one trucking type, saves overseas and clears the type after changing category', async () => {
+    mocks.getSupplier.mockResolvedValue({ ...supplier('A', '车队'), category: 'TRUCKING', carrierCodes: [], truckingScope: null })
+    const wrapper = mount(SupplierFormView, { global: { plugins: [ElementPlus], stubs } })
+    await flushPromises()
+    const save = wrapper.findAll('button').find((button) => button.text().includes('保存'))!
+    await save.trigger('click'); await flushPromises()
+    expect(mocks.updateSupplier).not.toHaveBeenCalled()
+    expect(wrapper.findAllComponents({ name: 'ElFormItem' }).find(item => item.props('prop') === 'truckingScope')?.props('error')).toBe('请选择国内拖车或海外车队')
+    const radios = wrapper.findComponent({ name: 'ElRadioGroup' })
+    expect(radios.text()).toContain('国内拖车')
+    expect(radios.text()).toContain('海外车队')
+    radios.vm.$emit('update:modelValue', 'OVERSEAS')
+    await flushPromises(); await save.trigger('click'); await flushPromises()
+    expect(mocks.updateSupplier).toHaveBeenLastCalledWith('A', expect.objectContaining({ category: 'TRUCKING', truckingScope: 'OVERSEAS' }))
+    wrapper.findAllComponents({ name: 'ElSelect' })[0]!.vm.$emit('update:modelValue', 'CUSTOMS')
+    await flushPromises(); await save.trigger('click'); await flushPromises()
+    expect(wrapper.findComponent({ name: 'ElRadioGroup' }).exists()).toBe(false)
+    expect(mocks.updateSupplier).toHaveBeenLastCalledWith('A', expect.objectContaining({ category: 'CUSTOMS', truckingScope: null }))
+  })
+
+})
diff --git a/src/modules/suppliers/pages/SuppliersView.test.ts b/src/modules/suppliers/pages/SuppliersView.test.ts
new file mode 100644
index 00000000..73ccdd24
--- /dev/null
+++ b/src/modules/suppliers/pages/SuppliersView.test.ts
@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/suppliers/pages/SuppliersView.vue'), 'utf8')
+const formSource = readFileSync(resolve(process.cwd(), 'src/modules/suppliers/pages/SupplierFormView.vue'), 'utf8')
+const detailSource = readFileSync(resolve(process.cwd(), 'src/modules/suppliers/pages/SupplierDetailView.vue'), 'utf8')
+const routesSource = readFileSync(resolve(process.cwd(), 'src/modules/suppliers/routes.ts'), 'utf8')
+
+describe('supplier formal pages', () => {
+  it('clamps long supplier and represented-carrier names with the shared component', () => {
+    expect(source).toContain("LineClampText from '@/shared/components/LineClampText.vue'")
+    expect(source).toContain('<template #name="{ row }"><LineClampText :content="row.name" /></template>')
+    expect(source).toContain('<template #carrierCodes="{ row }"><LineClampText')
+    expect(source).not.toContain('class="supplier-name"')
+  })
+
+  it('keeps actions first and fixed left while guarding all operations with backend permissions', () => {
+    expect(source).toContain("{ key: 'actions', label: '操作', width: 260, fixed: 'left'")
+    expect(source).toContain("access.can('platform:supplier:create')")
+    expect(source).toContain("access.can('platform:supplier:edit')")
+    expect(source).toContain("access.can('platform:supplier:status')")
+    expect(source).toContain("access.can('platform:supplier:list')")
+    expect(source).toContain('class="density-action"')
+    expect(source).toContain('class="row-actions density-actions"')
+    expect(source).toContain("statusLabels[supplierRow(row).status] ?? '—'")
+  })
+
+  it('matches the prototype statistics, category tabs and search sequence', () => {
+    expect(source).toContain('class="supplier-list-top"')
+    expect(source).toContain('class="supplier-query-panel"')
+    expect(source).toContain('class="supplier-query-toolbar"')
+    expect(source).toContain('class="supplier-tabs density-tabs"')
+    expect(source).toContain('（{{ item.value }}）')
+    expect(source).not.toContain('class="supplier-metrics"')
+    expect(source).toContain('@click="switchCategory(item.category)"')
+    expect(source).not.toContain('订舱范围')
+    expect(source).not.toContain('国内/国外')
+    expect(formSource).not.toContain('form.scope')
+    expect(formSource).not.toContain('prop="scope"')
+    expect(detailSource).not.toContain('国内/国外')
+  })
+
+  it('uses independent routes for list, detail, create and edit', () => {
+    expect(routesSource).toContain("path: 'suppliers/new'")
+    expect(routesSource).toContain("path: 'suppliers/:id'")
+    expect(routesSource).toContain("path: 'suppliers/:id/edit'")
+    expect(routesSource).toContain("permission: 'platform:supplier:create'")
+    expect(routesSource).toContain("permission: 'platform:supplier:edit'")
+    expect(routesSource).toContain("permission: 'platform:supplier:list'")
+    expect(routesSource).not.toContain('platform:supplier:view')
+    expect(detailSource).toContain('供应商详情')
+  })
+
+  it('does not simulate supplier data or license upload and retains API errors', () => {
+    expect(source).not.toContain('supplierData')
+    expect(formSource).not.toContain('type="file"')
+    expect(formSource).toContain('平台公共供应商资质上传接口尚未提供')
+    expect(formSource).toContain('<ApiErrorMeta')
+    expect(detailSource).toContain('<ApiErrorMeta')
+  })
+
+  it('uses a fixed multi-select for booking supplier carrier codes and sends no legacy scalar', () => {
+    expect(formSource).toContain('v-if="form.category === \'BOOKING\'"')
+    expect(formSource).toContain('v-for="option in carrierCodeOptions"')
+    expect(formSource).toContain('v-model="form.carrierCodes" multiple')
+    expect(formSource).toContain("if (category !== 'BOOKING') form.carrierCodes = []")
+    expect(formSource).toContain("carrierCodes: [...(carrierCodes || [])]")
+    expect(formSource).not.toMatch(/form\.carrierCode(?!s)/)
+    expect(source).toContain("label: '可代理船公司'")
+    expect(source).toContain("carrierCode: activeCategory.value === 'BOOKING' ? applied.value.carrierCode || undefined : undefined")
+    expect(detailSource).toContain("['可代理船公司', supplier.value.category === 'BOOKING' ? formatCarrierCodes(supplier.value.carrierCodes) : '—']")
+  })
+
+  it('reloads detail data when the reused route id changes and protects the newer request', () => {
+    expect(detailSource).toContain("watch(supplierId, () => { void load() }, { immediate: true })")
+    expect(detailSource).toContain('const requestedId = supplierId.value')
+    expect(detailSource).toContain('if (sequence !== loadSequence || requestedId !== supplierId.value) return')
+    expect(detailSource).toContain("params: { id: supplier.id }")
+  })
+
+  it('refreshes cached lists and resets cached create forms on activation', () => {
+    expect(source).toContain('onMounted(load)')
+    expect(source).toContain('if (activatedOnce) void load()')
+    expect(formSource).toContain('if (activatedOnce) void load()')
+    expect(formSource).toContain('onDeactivated(() => { active = false })')
+    expect(formSource).toContain("watch(supplierId, () => { if (active) void load() }, { immediate: true })")
+  })
+})
diff --git a/src/modules/suppliers/pages/SuppliersView.vue b/src/modules/suppliers/pages/SuppliersView.vue
new file mode 100644
index 00000000..b93a2309
--- /dev/null
+++ b/src/modules/suppliers/pages/SuppliersView.vue
@@ -0,0 +1,173 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onActivated, onMounted, ref, watch } from 'vue'
+import { useRouter } from 'vue-router'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import { Plus } from '@lucide/vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import LineClampText from '@/shared/components/LineClampText.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import SupplierLicenseDialog from '@/modules/suppliers/components/SupplierLicenseDialog.vue'
+import { changeSupplierStatus, getSupplierStats, listSuppliers } from '@/modules/suppliers/api/platformSuppliers'
+import { truckingScopeOptions, formatTruckingScope, type TruckingScope, carrierCodeOptions, categoryLabels, formatCarrierCodes, settlementLabels, statusLabels, type CarrierCode, type Supplier, type SupplierCategory, type SupplierStats, type SupplierStatus } from '@/modules/suppliers/types'
+
+const router = useRouter()
+const access = useAccessPreviewStore()
+const canView = computed(() => access.can('platform:supplier:list'))
+const loading = ref(false)
+const rows = ref<Supplier[]>([])
+const stats = ref<SupplierStats>({ booking: 0, customs: 0, trucking: 0, certificate: 0 })
+const activeCategory = ref<SupplierCategory>('BOOKING')
+const page = ref(1)
+const pageSize = ref(20)
+const total = ref(0)
+const loadError = ref<ApiErrorDetails | null>(null)
+const actionId = ref('')
+const licenseOpen = ref(false)
+const licenseSupplier = ref<Supplier | null>(null)
+type Filters = QueryModel & { status: SupplierStatus | ''; region: string; keyword: string; carrierCode: CarrierCode | ''; truckingScope: TruckingScope | '' }
+const filters = ref<Filters>({ status: '', region: '', keyword: '', carrierCode: '', truckingScope: '' })
+const applied = ref<Filters>({ ...filters.value })
+let sequence = 0
+
+const queryFields = computed<QueryField[]>(() => [
+  { key: 'status', type: 'select', label: '状态', placeholder: '全部状态', width: 150, options: [{ label: '合作中', value: 'ACTIVE' }, { label: '停用', value: 'INACTIVE' }] },
+  ...(activeCategory.value === 'BOOKING' ? [{ key: 'carrierCode', type: 'select' as const, label: '可代理船公司', placeholder: '全部船公司', width: 190, options: carrierCodeOptions }] : []),
+  ...(activeCategory.value === 'TRUCKING' ? [{ key: 'truckingScope', type: 'select' as const, label: '拖车类型', placeholder: '全部拖车类型', width: 170, options: truckingScopeOptions }] : []),
+  { key: 'region', type: 'input', label: '地区', placeholder: '请输入地区', width: 170, props: { maxlength: 80 } },
+  { key: 'keyword', type: 'input', label: '名称或联系人', placeholder: '供应商名称/联系人', width: 220, props: { maxlength: 160 } },
+])
+
+const columns = computed<DataTableColumn[]>(() => [
+  { key: 'actions', label: '操作', width: 260, fixed: 'left', slotName: 'actions' },
+  { key: 'name', label: '供应商名称', minWidth: 200, slotName: 'name' },
+  { key: 'category', label: '类别', width: 70, slotName: 'category' },
+  ...(activeCategory.value === 'BOOKING' ? [{ key: 'carrierCodes', label: '可代理船公司', minWidth: 200, slotName: 'carrierCodes' }] : []),
+  ...(activeCategory.value === 'TRUCKING' ? [{ key: 'truckingScope', label: '拖车类型', width: 110, slotName: 'truckingScope' }] : []),
+  { key: 'region', label: '地区', minWidth: 100 },
+  { key: 'legalRepresentative', label: '法人', minWidth: 100 },
+  { key: 'contactName', label: '联系人', minWidth: 120 },
+  { key: 'phone', label: '联系电话', minWidth: 120 },
+  { key: 'businessLicenseNo', label: '营业执照号', minWidth: 120 },
+  { key: 'license', label: '营业执照', width: 125, slotName: 'license' },
+  { key: 'status', label: '状态', width: 100, slotName: 'status' },
+  { key: 'settlementPeriod', label: '结算周期', width: 120, slotName: 'settlement' },
+])
+const metricItems = computed(() => [
+  { category: 'BOOKING' as const, label: '订舱供应商', value: stats.value.booking },
+  { category: 'CUSTOMS' as const, label: '报关供应商', value: stats.value.customs },
+  { category: 'TRUCKING' as const, label: '拖车供应商', value: stats.value.trucking },
+  { category: 'CERTIFICATE' as const, label: '证书供应商', value: stats.value.certificate },
+])
+
+async function load() {
+  if (!canView.value) return
+  const current = ++sequence
+  loading.value = true
+  loadError.value = null
+  try {
+    const [result, counts] = await Promise.all([
+      listSuppliers({ page: page.value, size: pageSize.value, category: activeCategory.value, status: applied.value.status, region: applied.value.region, keyword: applied.value.keyword, truckingScope: activeCategory.value === 'TRUCKING' ? applied.value.truckingScope || undefined : undefined, carrierCode: activeCategory.value === 'BOOKING' ? applied.value.carrierCode || undefined : undefined }),
+      getSupplierStats(),
+    ])
+    if (current !== sequence) return
+    rows.value = result.records
+    total.value = result.total
+    stats.value = counts
+  } catch (error) {
+    if (current !== sequence) return
+    rows.value = []; total.value = 0
+    loadError.value = getApiErrorDetails(error, '供应商列表加载失败')
+  } finally { if (current === sequence) loading.value = false }
+}
+
+function search() { applied.value = { ...filters.value }; page.value = 1; void load() }
+function switchCategory(category: SupplierCategory) {
+  activeCategory.value = category
+  page.value = 1
+  void load()
+}
+function showLicense(row: Supplier) { licenseSupplier.value = row; licenseOpen.value = true }
+function supplierRow(row: object) { return row as Supplier }
+async function toggleStatus(row: Supplier) {
+  const next: SupplierStatus = row.status === 'ACTIVE' ? 'INACTIVE' : 'ACTIVE'
+  const verb = next === 'ACTIVE' ? '启用' : '停用'
+  try {
+    await ElMessageBox.confirm(`确认${verb}供应商“${row.name}”吗？`, `${verb}供应商`, { customClass: 'admin-density-confirm', type: 'warning', confirmButtonText: `确认${verb}`, cancelButtonText: '取消' })
+    actionId.value = row.id
+    await changeSupplierStatus(row.id, next)
+    ElMessage.success(`供应商已${verb}`)
+    await load()
+  } catch (error) {
+    if (error === 'cancel' || error === 'close') return
+    const details = getApiErrorDetails(error, `${verb}供应商失败`)
+    ElMessage.error(details.requestId ? `${details.message}（requestId: ${details.requestId}）` : details.message)
+  } finally { actionId.value = '' }
+}
+
+watch([page, pageSize], ([newPage, newSize], [oldPage, oldSize]) => { if (newPage !== oldPage || newSize !== oldSize) void load() })
+let activatedOnce = false
+onMounted(load)
+onActivated(() => {
+  if (activatedOnce) void load()
+  else activatedOnce = true
+})
+</script>
+
+<template>
+  <AdminPage class="admin-density">
+    <ListPageLayout aria-label="供应商列表">
+      <template #toolbar>
+        <div class="supplier-list-top">
+          <div class="supplier-query-panel">
+            <nav class="supplier-tabs density-tabs" role="tablist" aria-label="供应商分类统计">
+              <button role="tab" :aria-selected="activeCategory === item.category" v-for="item in metricItems" :key="item.category" type="button" :class="{ active: activeCategory === item.category }" @click="switchCategory(item.category)"><span class="density-tab-icon" aria-hidden="true">{{ ({ BOOKING: '🚢', CUSTOMS: '📋', TRUCKING: '🚚', CERTIFICATE: '📄' })[item.category] }}</span>{{ categoryLabels[item.category] }}（{{ item.value }}）</button>
+            </nav>
+            <QueryToolbar v-model="filters" class="supplier-query-toolbar" ariaLabel="供应商筛选" :fields="queryFields" @search="search" />
+          </div>
+        </div>
+      </template>
+      <template #state>
+        <LoadErrorState v-if="!canView" title="暂无供应商查看权限" message="请联系管理员开通供应商查看权限。" :show-retry="false" />
+        <LoadErrorState v-else-if="loadError" title="供应商加载失败" :message="loadError.message" :loading="loading" @retry="load">
+          <template #details><ApiErrorMeta :details="loadError" /></template>
+        </LoadErrorState>
+      </template>
+      <section v-if="canView" class="surface-panel table-panel">
+        <DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :loading="loading" :total="total" empty-text="暂无供应商数据" preference-key="supplier-list">
+          <template #toolbar-actions>
+            <el-button v-if="access.can('platform:supplier:create')" type="primary" @click="router.push({ name: 'supplier-create' })"><Plus :size="16" />新增供应商</el-button>
+          </template>
+          <template #actions="{ row }">
+            <div class="row-actions density-actions">
+              <el-button data-tone="neutral" class="density-action" size="small"   @click="router.push({ name: 'supplier-detail', params: { id: row.id } })">详情</el-button>
+              <el-button data-tone="neutral" class="density-action" v-if="access.can('platform:supplier:edit')" size="small"   @click="router.push({ name: 'supplier-edit', params: { id: row.id } })">编辑</el-button>
+              <el-button class="density-action" v-if="access.can('platform:supplier:status')" size="small"  :data-tone="row.status === 'ACTIVE' ? 'danger' : 'success'" :loading="actionId === row.id" @click="toggleStatus(supplierRow(row))">{{ row.status === 'ACTIVE' ? '停用' : '启用' }}</el-button>
+            </div>
+          </template>
+          <template #name="{ row }"><LineClampText :content="row.name" /></template>
+          <template #category="{ row }">{{ categoryLabels[row.category as SupplierCategory] }}</template>
+          <template #truckingScope="{ row }">{{ formatTruckingScope(supplierRow(row).truckingScope) }}</template>
+          <template #carrierCodes="{ row }"><LineClampText :content="supplierRow(row).category === 'BOOKING' ? formatCarrierCodes(supplierRow(row).carrierCodes) : null" /></template>
+          <template #license="{ row }"><el-button data-tone="neutral" class="density-action" size="small"   @click="showLicense(supplierRow(row))">查看</el-button></template>
+          <template #status="{ row }"><StatusBadge :status="statusLabels[supplierRow(row).status] ?? '—'" /></template>
+          <template #settlement="{ row }">{{ settlementLabels[supplierRow(row).settlementPeriod] }}</template>
+        </DataTable>
+      </section>
+    </ListPageLayout>
+    <SupplierLicenseDialog v-model="licenseOpen" :supplier="licenseSupplier" />
+  </AdminPage>
+</template>
+
+<style scoped>
+ .supplier-list-top { display: grid; gap: var(--admin-space-6); }.supplier-query-panel { overflow: hidden; border: 1px solid var(--cc-border); border-radius: var(--admin-radius); background: #fff; }.supplier-query-toolbar { border: 0; }
+@media (max-width: 720px) { .supplier-metrics { grid-template-columns: repeat(2, minmax(0, 1fr)); } }
+@media (max-width: 380px) { .supplier-metrics { grid-template-columns: 1fr; } }
+</style>
diff --git a/src/modules/suppliers/routes.ts b/src/modules/suppliers/routes.ts
new file mode 100644
index 00000000..d88500d1
--- /dev/null
+++ b/src/modules/suppliers/routes.ts
@@ -0,0 +1,8 @@
+import type { RouteRecordRaw } from 'vue-router'
+
+export const supplierRoutes = [
+  { path: 'suppliers', name: 'supplier-list', component: () => import('@/modules/suppliers/pages/SuppliersView.vue'), meta: { title: '供应商列表', description: '维护平台公共订舱、报关、拖车和证书供应商', permission: 'platform:supplier:list' } },
+  { path: 'suppliers/new', name: 'supplier-create', component: () => import('@/modules/suppliers/pages/SupplierFormView.vue'), meta: { title: '新增供应商', showPageHeading: false, description: '新增平台公共供应商档案', permission: 'platform:supplier:create' } },
+  { path: 'suppliers/:id', name: 'supplier-detail', component: () => import('@/modules/suppliers/pages/SupplierDetailView.vue'), meta: { title: '供应商详情', showPageHeading: false, description: '查看平台公共供应商完整档案', permission: 'platform:supplier:list' } },
+  { path: 'suppliers/:id/edit', name: 'supplier-edit', component: () => import('@/modules/suppliers/pages/SupplierFormView.vue'), meta: { title: '编辑供应商', showPageHeading: false, description: '编辑平台公共供应商档案', permission: 'platform:supplier:edit' } },
+] satisfies RouteRecordRaw[]
diff --git a/src/modules/suppliers/types.ts b/src/modules/suppliers/types.ts
new file mode 100644
index 00000000..85529c0b
--- /dev/null
+++ b/src/modules/suppliers/types.ts
@@ -0,0 +1,86 @@
+export type SupplierCategory = 'BOOKING' | 'CUSTOMS' | 'TRUCKING' | 'CERTIFICATE'
+export type TruckingScope = 'DOMESTIC' | 'OVERSEAS'
+export const truckingScopeLabels: Record<TruckingScope, string> = { DOMESTIC: '国内拖车', OVERSEAS: '海外车队' }
+export const truckingScopeOptions = Object.entries(truckingScopeLabels).map(([value, label]) => ({ value, label }))
+export function formatTruckingScope(scope: TruckingScope | null) { return scope ? truckingScopeLabels[scope] : '—' }
+export type SupplierStatus = 'ACTIVE' | 'INACTIVE'
+export type SettlementPeriod = 'MONTHLY_30' | 'MONTHLY_45' | 'MONTHLY_60' | 'MONTHLY_90' | 'PER_TRANSACTION' | 'IMMEDIATE'
+export type CarrierCode = 'MATSON' | 'SML' | 'ZIM' | 'COSCO' | 'EMC' | 'HEDE' | 'OTHER'
+
+export interface Supplier {
+  id: string
+  tenantId: string
+  name: string
+  category: SupplierCategory
+  truckingScope: TruckingScope | null
+  carrierCodes: CarrierCode[]
+  region: string
+  legalRepresentative: string
+  contactName: string
+  phone: string
+  email: string | null
+  address: string | null
+  businessLicenseNo: string | null
+  licenseFileId: string | null
+  status: SupplierStatus
+  settlementPeriod: SettlementPeriod
+  remark: string | null
+  createdBy: string | null
+  createdAt: string
+  updatedBy: string | null
+  updatedAt: string
+  deleted: boolean
+  version: number
+}
+
+export interface SupplierPage {
+  records: Supplier[]
+  page: number
+  size: number
+  total: number
+  pages: number
+}
+
+export interface SupplierStats { booking: number; customs: number; trucking: number; certificate: number }
+
+export interface SupplierQuery {
+  page?: number
+  size?: number
+  category?: SupplierCategory
+  truckingScope?: TruckingScope
+  region?: string
+  status?: SupplierStatus | ''
+  keyword?: string
+  carrierCode?: CarrierCode
+}
+
+export interface SaveSupplierRequest {
+  name: string
+  category: SupplierCategory
+  truckingScope: TruckingScope | null
+  carrierCodes?: CarrierCode[]
+  region: string
+  legalRepresentative: string
+  contactName: string
+  phone: string
+  email: string | null
+  address: string | null
+  businessLicenseNo: string | null
+  licenseFileId: string | null
+  status: SupplierStatus
+  settlementPeriod: SettlementPeriod
+  remark: string | null
+}
+
+export const categoryLabels: Record<SupplierCategory, string> = { BOOKING: '订舱', CUSTOMS: '报关', TRUCKING: '拖车', CERTIFICATE: '证书' }
+export const carrierCodeLabels: Record<CarrierCode, string> = {
+  MATSON: '美森', SML: 'SML', ZIM: '以星', COSCO: '中远', EMC: '长荣', HEDE: '合德', OTHER: '其他',
+}
+export const carrierCodeOptions = (Object.entries(carrierCodeLabels) as [CarrierCode, string][]).map(([value, name]) => ({ value, label: `${name} (${value})` }))
+export function formatCarrierCodes(codes: CarrierCode[] | null | undefined) {
+  return codes?.length ? codes.map((code) => `${carrierCodeLabels[code]} (${code})`).join('、') : '—'
+}
+export const statusLabels: Record<SupplierStatus, string> = { ACTIVE: '合作中', INACTIVE: '停用' }
+export const settlementLabels: Record<SettlementPeriod, string> = {
+  MONTHLY_30: '月结30天', MONTHLY_45: '月结45天', MONTHLY_60: '月结60天', MONTHLY_90: '月结90天', PER_TRANSACTION: '票结', IMMEDIATE: '现结',
+}
diff --git a/src/modules/trucking/api/platformTrucking.test.ts b/src/modules/trucking/api/platformTrucking.test.ts
new file mode 100644
index 00000000..aa1cc580
--- /dev/null
+++ b/src/modules/trucking/api/platformTrucking.test.ts
@@ -0,0 +1,111 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import { createTruckAppointment, deleteTruckAppointmentAttachment, getTruckAppointment, listTruckAppointmentAttachments, listTruckAppointmentCandidates, listTruckAppointmentHistory, listTruckAppointments, performTruckAppointmentAction, referenceTruckAppointmentAttachment, rescheduleTruckAppointment, uploadTruckAppointmentAttachment } from './platformTrucking'
+
+vi.mock('@/shared/api/http', () => ({ http: { get: vi.fn(), post: vi.fn(), put: vi.fn(), patch: vi.fn(), delete: vi.fn() }, unwrapApiResponse: (response: { data: unknown }) => response.data }))
+
+describe('truck appointment API', () => {
+  beforeEach(() => { vi.clearAllMocks() })
+
+  it('normalizes page values and maps filters', async () => {
+    vi.mocked(http.get).mockResolvedValue({ data: { records: [{ id: 1, oceanBookingId: 2, warehouseId: 4, shippingCompanyId: 5, bookingAgentId: 6, oceanBookingNo: 'OB-1', warehouseName: '义乌仓', shippingCompanyName: '船公司', bookingAgentName: '订舱代理', attachmentCount: '2' }], page: '2', size: '20', total: '21', pages: '2' } })
+    await expect(listTruckAppointments({ page: 2, size: 20, keyword: '  BY ', status: 'DISPATCHED', oceanBookingId: '77' })).resolves.toMatchObject({ page: 2, total: 21, pages: 2, records: [{ id: '1', oceanBookingId: '2', warehouseId: '4', shippingCompanyId: '5', bookingAgentId: '6', oceanBookingNo: 'OB-1', attachmentCount: 2 }] })
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/truck-appointments', { params: { page: 2, size: 20, keyword: 'BY', status: 'DISPATCHED', oceanBookingId: '77' } })
+  })
+
+  it('uses the server-owned create candidate contract without rebuilding availability', async () => {
+    vi.mocked(http.get).mockResolvedValue({ data: { records: [{ oceanBookingId: 11, oceanBookingNo: 'OB-11', billOfLadingNo: 'BL-11', warehouseId: 12, warehouseName: '义乌仓', channelCode: 'SEA', channelName: '海运', bookingDocumentReady: true }], page: '1', size: '200', total: '1', pages: '1' } })
+    await expect(listTruckAppointmentCandidates({ keyword: ' OB ', page: 1, size: 200 })).resolves.toMatchObject({
+      records: [{ oceanBookingId: '11', warehouseId: '12', bookingDocumentReady: true }],
+      total: 1,
+    })
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/truck-appointments/candidates', { params: { keyword: 'OB', page: 1, size: 200 } })
+  })
+
+  it('uses detail, create, and status contracts', async () => {
+    vi.mocked(http.get).mockResolvedValue({ data: { id: '9001', status: 'DRAFT' } })
+    vi.mocked(http.post).mockResolvedValue({ data: '9001' })
+    vi.mocked(http.post).mockResolvedValue({ data: { id: '9001', status: 'DISPATCHED' } })
+    await expect(getTruckAppointment('9001')).resolves.toMatchObject({ id: '9001' })
+    await expect(createTruckAppointment({ carrierId: '200', oceanBookingId: '300', plannedLoadingAt: '2026-08-10T10:00:00', expectedVersion: 0 })).resolves.toMatchObject({ id: '9001' })
+    expect(http.post).toHaveBeenNthCalledWith(1, '/platform/v1/truck-appointments', { carrierId: '200', oceanBookingId: '300', plannedLoadingAt: '2026-08-10T10:00:00', currency: 'RMB', expectedVersion: 0 })
+    await expect(performTruckAppointmentAction('9001', 'DISPATCH', { expectedVersion: 2 })).resolves.toMatchObject({ status: 'DISPATCHED' })
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/truck-appointments/9001/dispatch', { expectedVersion: 2, reason: null }, { headers: { 'Idempotency-Key': expect.stringContaining('truck-appointment-dispatch-9001-') } })
+  })
+
+  it('keeps pickup booking-scoped without sending container identity', async () => {
+    vi.mocked(http.post).mockResolvedValue({ data: { id: '9001', status: 'PICKUP_IN_PROGRESS' } })
+    await performTruckAppointmentAction('9001', 'PICKUP', { expectedVersion: 3 })
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/truck-appointments/9001/pickup', {
+      expectedVersion: 3, reason: null,
+    }, { headers: { 'Idempotency-Key': expect.stringContaining('truck-appointment-pickup-9001-') } })
+  })
+
+  it.each(['SUBMIT', 'DISPATCH', 'PICKUP'] as const)('sends %s without any container field', async (action) => {
+    vi.mocked(http.post).mockResolvedValue({ data: { id: '9001', status: 'PENDING_DISPATCH' } })
+    await performTruckAppointmentAction('9001', action, { expectedVersion: 4, reason: '演示流转' })
+    const body = vi.mocked(http.post).mock.calls.at(-1)?.[1] as Record<string, unknown>
+    expect(body).toEqual({ expectedVersion: 4, reason: '演示流转' })
+    expect(body).not.toHaveProperty('containerNo')
+    expect(body).not.toHaveProperty('containerBookingId')
+    expect(body).not.toHaveProperty('loadingPlanId')
+  })
+
+  it('drops legacy customer fields instead of forwarding hidden compatibility data', async () => {
+    vi.mocked(http.post).mockResolvedValueOnce({ data: { id: '9001', status: 'DRAFT', attachmentCount: 0 } })
+    const payload = { carrierId: '200', oceanBookingId: '300', containerBookingId: '400', loadingPlanId: '500', plannedLoadingAt: '2026-08-10T10:00:00', expectedVersion: 0, currency: 'EUR', receivableAmount: '999.00', customerId: 'legacy-customer', customerName: '旧客户快照' }
+    await createTruckAppointment(payload as never)
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/truck-appointments', {
+      carrierId: '200', oceanBookingId: '300', plannedLoadingAt: '2026-08-10T10:00:00', currency: 'RMB', expectedVersion: 0,
+    })
+  })
+
+  it('sends the required idempotency header for rescheduling', async () => {
+    vi.mocked(http.post).mockResolvedValue({ data: { id: '9001', status: 'RESCHEDULED' } })
+    await expect(rescheduleTruckAppointment('9001', '2026-08-20T10:00:00', 2, '调整时间')).resolves.toMatchObject({ status: 'RESCHEDULED' })
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/truck-appointments/9001/reschedule', { expectedVersion: 2, reason: '调整时间' }, {
+      params: { plannedLoadingAt: '2026-08-20T10:00:00' },
+      headers: { 'Idempotency-Key': expect.stringContaining('truck-appointment-reschedule-9001-') },
+    })
+  })
+
+  it('uses scoped attachment and immutable history contracts', async () => {
+    vi.mocked(http.get)
+      .mockResolvedValueOnce({ data: [{ id: 1, fileId: 9007199254740993, fileName: '派车单.pdf' }] })
+      .mockResolvedValueOnce({ data: [{ id: 2, action: 'DISPATCH', fromStatus: 'PENDING_DISPATCH', toStatus: 'DISPATCHED', operatorId: 3 }] })
+    vi.mocked(http.post).mockResolvedValue({ data: { id: '1', fileId: '9007199254740993', fileName: '派车单.pdf' } })
+    vi.mocked(http.delete).mockResolvedValue({ data: null })
+
+    await expect(listTruckAppointmentAttachments('77')).resolves.toMatchObject([{ id: '1', fileName: '派车单.pdf' }])
+    await expect(listTruckAppointmentHistory('77')).resolves.toMatchObject([{ id: '2', operatorId: '3', action: 'DISPATCH' }])
+    await referenceTruckAppointmentAttachment('77', { fileId: '9007199254740993', fileName: '派车单.pdf' })
+    await deleteTruckAppointmentAttachment('77', '1')
+
+    expect(http.get).toHaveBeenNthCalledWith(1, '/platform/v1/truck-appointments/77/attachments')
+    expect(http.get).toHaveBeenNthCalledWith(2, '/platform/v1/truck-appointments/77/history')
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/truck-appointments/77/attachments', { fileId: '9007199254740993', fileName: '派车单.pdf' })
+    expect(http.delete).toHaveBeenCalledWith('/platform/v1/truck-appointments/77/attachments/1')
+  })
+
+  it('uploads an attachment through the frozen multipart endpoint', async () => {
+    vi.mocked(http.post).mockResolvedValue({ data: { id: '1', fileId: '2', fileName: '派车单.pdf' } })
+    const file = new File(['dispatch'], '派车单.pdf', { type: 'application/pdf' })
+    await uploadTruckAppointmentAttachment('77', file, 'DISPATCH_ORDER')
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/truck-appointments/77/attachments/upload', expect.any(FormData), { headers: { 'Content-Type': 'multipart/form-data' } })
+    const form = vi.mocked(http.post).mock.calls[0]?.[1] as FormData
+    expect(form.get('file')).toBe(file)
+    expect(form.get('attachmentType')).toBe('DISPATCH_ORDER')
+  })
+
+  it('never forwards a legacy booking document type into truck attachments', async () => {
+    vi.mocked(http.post).mockResolvedValue({ data: { id: '1', fileId: '2', fileName: 'legacy.pdf' } })
+    await referenceTruckAppointmentAttachment('77', { fileId: '2', fileName: 'legacy.pdf', attachmentType: 'BILL_OF_LADING' as never })
+    expect(http.post).toHaveBeenLastCalledWith('/platform/v1/truck-appointments/77/attachments', { fileId: '2', fileName: 'legacy.pdf' })
+
+    const file = new File(['legacy'], 'legacy.pdf', { type: 'application/pdf' })
+    await uploadTruckAppointmentAttachment('77', file, 'BILL_OF_LADING' as never)
+    const form = vi.mocked(http.post).mock.calls.at(-1)?.[1] as FormData
+    expect(form.get('file')).toBe(file)
+    expect(form.has('attachmentType')).toBe(false)
+  })
+})
diff --git a/src/modules/trucking/api/platformTrucking.ts b/src/modules/trucking/api/platformTrucking.ts
new file mode 100644
index 00000000..7048ab93
--- /dev/null
+++ b/src/modules/trucking/api/platformTrucking.ts
@@ -0,0 +1,171 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import { TRUCK_APPOINTMENT_SAVE_FIELDS, isTruckAttachmentType, normalizeTruckAppointmentCurrency } from '../types'
+import type {
+  SaveTruckAppointmentRequest,
+  TruckAppointmentPage,
+  TruckAppointmentQuery,
+  TruckAppointmentResource,
+  TruckAppointmentActionRequest,
+  TruckAppointmentCandidate,
+  TruckAppointmentCandidatePage,
+  TruckAppointmentCandidateQuery,
+  TruckAppointmentStatusHistory,
+  TruckAttachmentReference,
+  TruckAttachmentType,
+} from '../types'
+
+const basePath = '/platform/v1/truck-appointments'
+function operationId(action: string, id: string | number) {
+  return `truck-appointment-${action.toLowerCase()}-${id}-${Date.now()}-${Math.random().toString(36).slice(2)}`
+}
+
+function dtoPayload(payload: SaveTruckAppointmentRequest) {
+  return Object.fromEntries(TRUCK_APPOINTMENT_SAVE_FIELDS.flatMap((key) => {
+    const value = key === 'currency' ? normalizeTruckAppointmentCurrency(payload[key]) : payload[key]
+    return value === undefined ? [] : [[key, value === '' ? null : value]]
+  })) as unknown as SaveTruckAppointmentRequest
+}
+
+type PagePayload = Omit<TruckAppointmentPage, 'page' | 'size' | 'total' | 'pages'> & {
+  page: number | string
+  size: number | string
+  total: number | string
+  pages?: number | string
+}
+
+function normalizePage(payload: PagePayload): TruckAppointmentPage {
+  const page = Number(payload.page || 1)
+  const size = Number(payload.size || 20)
+  const total = Number(payload.total || 0)
+  return { records: (payload.records || []).map(normalizeResource), page, size, total, pages: Number(payload.pages || Math.max(Math.ceil(total / size), 1)) }
+}
+
+function normalizeResource(resource: TruckAppointmentResource): TruckAppointmentResource {
+  const idKeys = ['id', 'outboundOrderId', 'oceanBookingId', 'warehouseId', 'shippingCompanyId', 'bookingAgentId', 'carrierId']
+  const normalized = { ...resource } as Record<string, unknown>
+  for (const key of idKeys) {
+    if (normalized[key] !== null && normalized[key] !== undefined) normalized[key] = String(normalized[key])
+  }
+  normalized.attachmentCount = Number(normalized.attachmentCount ?? 0)
+  return normalized as unknown as TruckAppointmentResource
+}
+
+export async function listTruckAppointments(query: TruckAppointmentQuery = {}) {
+  const response = await http.get<ApiEnvelope<PagePayload>, ApiEnvelope<PagePayload>>(basePath, {
+    params: {
+      ...query,
+      keyword: query.keyword?.trim() || undefined,
+      status: query.status || undefined,
+      oceanBookingId: query.oceanBookingId || undefined,
+    },
+  })
+  return normalizePage(unwrapApiResponse(response))
+}
+
+type CandidatePagePayload = Omit<TruckAppointmentCandidatePage, 'records' | 'page' | 'size' | 'total' | 'pages'> & {
+  records?: Array<TruckAppointmentCandidate & Record<string, unknown>>
+  page: number | string
+  size: number | string
+  total: number | string
+  pages?: number | string
+}
+
+function normalizeCandidate(candidate: TruckAppointmentCandidate & Record<string, unknown>): TruckAppointmentCandidate {
+  const normalized = { ...candidate } as Record<string, unknown>
+  for (const key of ['oceanBookingId', 'warehouseId']) {
+    if (normalized[key] !== null && normalized[key] !== undefined) normalized[key] = String(normalized[key])
+  }
+  normalized.bookingDocumentReady = normalized.bookingDocumentReady === true
+  return normalized as unknown as TruckAppointmentCandidate
+}
+
+export async function listTruckAppointmentCandidates(query: TruckAppointmentCandidateQuery = {}) {
+  const response = await http.get<ApiEnvelope<CandidatePagePayload>, ApiEnvelope<CandidatePagePayload>>(`${basePath}/candidates`, {
+    params: { keyword: query.keyword?.trim() || undefined, page: query.page || 1, size: query.size || 200 },
+  })
+  const payload = unwrapApiResponse(response)
+  const page = Number(payload.page || 1)
+  const size = Number(payload.size || 200)
+  const total = Number(payload.total || 0)
+  return {
+    records: (payload.records || []).map(normalizeCandidate),
+    page,
+    size,
+    total,
+    pages: Number(payload.pages || Math.max(Math.ceil(total / size), 1)),
+  } satisfies TruckAppointmentCandidatePage
+}
+
+export async function getTruckAppointment(id: string | number) {
+  const response = await http.get<ApiEnvelope<TruckAppointmentResource>, ApiEnvelope<TruckAppointmentResource>>(`${basePath}/${id}`)
+  return normalizeResource(unwrapApiResponse(response))
+}
+
+export async function listTruckAppointmentHistory(id: string | number) {
+  const response = await http.get<ApiEnvelope<TruckAppointmentStatusHistory[] | { records?: TruckAppointmentStatusHistory[] }>, ApiEnvelope<TruckAppointmentStatusHistory[] | { records?: TruckAppointmentStatusHistory[] }>>(`${basePath}/${id}/history`)
+  const payload = unwrapApiResponse(response)
+  const records = Array.isArray(payload) ? payload : payload?.records || []
+  return records.map((item) => ({ ...item, id: item.id == null ? item.id : String(item.id), operatorId: item.operatorId == null ? item.operatorId : String(item.operatorId) }))
+}
+
+export async function listTruckAppointmentAttachments(id: string | number) {
+  const response = await http.get<ApiEnvelope<TruckAttachmentReference[]>, ApiEnvelope<TruckAttachmentReference[]>>(`${basePath}/${id}/attachments`)
+  return unwrapApiResponse(response).map((item) => ({ ...item, id: item.id == null ? item.id : String(item.id), fileId: String(item.fileId), uploadedBy: item.uploadedBy == null ? item.uploadedBy : String(item.uploadedBy) }))
+}
+
+export async function referenceTruckAppointmentAttachment(id: string | number, payload: { fileId: string; attachmentType?: TruckAttachmentType | null; fileName?: string | null; fileHash?: string | null }) {
+  const { attachmentType, ...rest } = payload
+  const body = { ...rest, ...(isTruckAttachmentType(attachmentType) ? { attachmentType } : {}) }
+  const response = await http.post<ApiEnvelope<TruckAttachmentReference>, ApiEnvelope<TruckAttachmentReference>>(`${basePath}/${id}/attachments`, body)
+  return unwrapApiResponse(response)
+}
+
+export async function uploadTruckAppointmentAttachment(id: string | number, file: File, attachmentType?: TruckAttachmentType | null) {
+  const form = new FormData()
+  form.append('file', file)
+  if (isTruckAttachmentType(attachmentType)) form.append('attachmentType', attachmentType)
+  const response = await http.post<ApiEnvelope<TruckAttachmentReference>, ApiEnvelope<TruckAttachmentReference>>(`${basePath}/${id}/attachments/upload`, form, { headers: { 'Content-Type': 'multipart/form-data' } })
+  return unwrapApiResponse(response)
+}
+
+export async function deleteTruckAppointmentAttachment(id: string | number, attachmentId: string | number) {
+  await http.delete<ApiEnvelope<unknown>, ApiEnvelope<unknown>>(`${basePath}/${id}/attachments/${attachmentId}`)
+}
+
+export async function createTruckAppointment(payload: SaveTruckAppointmentRequest) {
+  const response = await http.post<ApiEnvelope<TruckAppointmentResource>, ApiEnvelope<TruckAppointmentResource>>(basePath, dtoPayload(payload))
+  return normalizeResource(unwrapApiResponse(response))
+}
+
+export async function updateTruckAppointment(id: string | number, payload: SaveTruckAppointmentRequest) {
+  const response = await http.put<ApiEnvelope<TruckAppointmentResource>, ApiEnvelope<TruckAppointmentResource>>(`${basePath}/${id}`, dtoPayload(payload))
+  return unwrapApiResponse(response)
+}
+
+export type TruckAppointmentAction = 'SUBMIT' | 'DISPATCH' | 'PICKUP' | 'ARRIVE' | 'LOAD' | 'EXCEPTION' | 'CANCEL'
+
+export async function performTruckAppointmentAction(
+  id: string | number,
+  action: TruckAppointmentAction,
+  payload: TruckAppointmentActionRequest,
+  idempotencyKey?: string,
+  requestHash?: string,
+) {
+  const operationKey = idempotencyKey || operationId(action, id)
+  const body = {
+    expectedVersion: payload.expectedVersion,
+    reason: payload.reason || null,
+  }
+  const response = await http.post<ApiEnvelope<TruckAppointmentResource>, ApiEnvelope<TruckAppointmentResource>>(`${basePath}/${id}/${action.toLowerCase()}`, body, {
+    headers: { 'Idempotency-Key': operationKey, ...(requestHash ? { 'X-Request-Hash': requestHash } : {}) },
+  })
+  return unwrapApiResponse(response)
+}
+
+export async function rescheduleTruckAppointment(id: string | number, plannedLoadingAt: string, expectedVersion: number, reason?: string) {
+  const response = await http.post<ApiEnvelope<TruckAppointmentResource>, ApiEnvelope<TruckAppointmentResource>>(`${basePath}/${id}/reschedule`, { expectedVersion, reason: reason || null }, {
+    params: { plannedLoadingAt },
+    headers: { 'Idempotency-Key': operationId('RESCHEDULE', id) },
+  })
+  return unwrapApiResponse(response)
+}
diff --git a/src/modules/trucking/components/TruckAppointmentForm.behavior.test.ts b/src/modules/trucking/components/TruckAppointmentForm.behavior.test.ts
new file mode 100644
index 00000000..275bb8f0
--- /dev/null
+++ b/src/modules/trucking/components/TruckAppointmentForm.behavior.test.ts
@@ -0,0 +1,218 @@
+import ElementPlus from 'element-plus'
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { ApiResponseError } from '@/shared/api/http'
+import TruckAppointmentForm from './TruckAppointmentForm.vue'
+import type { SaveTruckAppointmentRequest, TruckAppointmentResource } from '../types'
+import { listSuppliers } from '@/modules/suppliers'
+import { getOceanBooking } from '@/modules/ocean-bookings'
+import { listTruckAppointmentCandidates } from '../api/platformTrucking'
+
+vi.mock('@/modules/suppliers', () => ({
+  listSuppliers: vi.fn().mockResolvedValue({ records: [{ id: 'carrier-1', name: '平台拖车公司', category: 'TRUCKING', truckingScope: 'DOMESTIC', status: 'ACTIVE', contactName: '张调度', phone: '13800000001' }, { id: 'carrier-2', name: '第二车队', category: 'TRUCKING', truckingScope: 'DOMESTIC', status: 'ACTIVE', contactName: '李调度', phone: '13800000002' }, { id: 'overseas-1', name: '海外车队候选', category: 'TRUCKING', truckingScope: 'OVERSEAS', status: 'ACTIVE' }] }),
+}))
+vi.mock('@/modules/ocean-bookings', () => ({
+  getOceanBooking: vi.fn(),
+}))
+vi.mock('../api/platformTrucking', () => ({ listTruckAppointmentCandidates: vi.fn() }))
+
+const model: SaveTruckAppointmentRequest = {
+  expectedVersion: 0,
+  oceanBookingId: null,
+  carrierId: null,
+  plannedLoadingAt: null,
+}
+const candidates = [
+  { oceanBookingId: 'booking-1', oceanBookingNo: 'OB-1', billOfLadingNo: 'BL-1', warehouseId: 'WH-1', warehouseName: '义乌仓', channelCode: 'SEA', channelName: '海运', bookingDocumentReady: true },
+  { oceanBookingId: 'booking-2', oceanBookingNo: 'OB-2', billOfLadingNo: 'BL-2', warehouseId: 'WH-2', warehouseName: '东莞仓', channelCode: 'SEA', channelName: '海运', bookingDocumentReady: true },
+]
+function detail(id: string) {
+  const candidate = candidates.find((item) => item.oceanBookingId === id)!
+  return {
+    id, bookingNo: candidate.oceanBookingNo, status: 'RELEASED', billOfLadingNo: candidate.billOfLadingNo, warehouseId: candidate.warehouseId, warehouseName: candidate.warehouseName,
+    documents: [{ id: `doc-${id}`, documentType: 'BILL_OF_LADING', valid: true }],
+    containers: [],
+  }
+}
+function resource(id: string, bookingId: string): TruckAppointmentResource {
+  const candidate = candidates.find((item) => item.oceanBookingId === bookingId)!
+  return { id, status: 'DRAFT', oceanBookingId: bookingId, oceanBookingNo: candidate.oceanBookingNo, billOfLadingNo: candidate.billOfLadingNo, warehouseId: candidate.warehouseId, warehouseName: candidate.warehouseName }
+}
+
+describe('TruckAppointmentForm booking-only behavior', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.mocked(listTruckAppointmentCandidates).mockResolvedValue({ records: candidates, page: 1, size: 200, total: candidates.length, pages: 1 })
+    vi.mocked(getOceanBooking).mockImplementation(async (id) => detail(id) as never)
+  })
+
+  it('selects only server-approved released bookings and never exposes container identity', async () => {
+    const wrapper = mount(TruckAppointmentForm, { props: { modelValue: { ...model } }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    const selects = wrapper.findAllComponents({ name: 'ElSelect' })
+    selects[0]!.vm.$emit('update:modelValue', 'booking-1')
+    await flushPromises()
+
+    expect(listTruckAppointmentCandidates).toHaveBeenCalledWith({ page: 1, size: 200 })
+    expect(getOceanBooking).not.toHaveBeenCalled()
+    const labels = wrapper.findAllComponents({ name: 'ElOption' }).map((option) => String(option.props('label') || ''))
+    expect(labels.some((label) => label.includes('OB-1') && label.includes('BL-1'))).toBe(true)
+    expect(labels.some((label) => label.includes('CAB-'))).toBe(false)
+    expect(candidates[0]).not.toHaveProperty('containerBookingId')
+    const emitted = wrapper.emitted('update:modelValue')?.at(-1)?.[0] as SaveTruckAppointmentRequest
+    expect(emitted.oceanBookingId).toBe('booking-1')
+    expect(emitted.billOfLadingNo).toBe('BL-1')
+    expect(emitted).not.toHaveProperty('customerId')
+    expect(emitted).not.toHaveProperty('customerName')
+    wrapper.unmount()
+  })
+
+  it('keeps only the latest candidate response when option reloads overlap', async () => {
+    let resolveSlow!: (value: Awaited<ReturnType<typeof listTruckAppointmentCandidates>>) => void
+    let resolveFast!: (value: Awaited<ReturnType<typeof listTruckAppointmentCandidates>>) => void
+    vi.mocked(listTruckAppointmentCandidates)
+      .mockResolvedValueOnce({ records: candidates, page: 1, size: 200, total: candidates.length, pages: 1 })
+      .mockImplementationOnce(() => new Promise((resolve) => { resolveSlow = resolve }))
+      .mockImplementationOnce(() => new Promise((resolve) => { resolveFast = resolve }))
+    const wrapper = mount(TruckAppointmentForm, { props: { modelValue: { ...model } }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    const vm = wrapper.vm as unknown as { loadOptions: () => Promise<void> }
+    const slow = vm.loadOptions()
+    const fast = vm.loadOptions()
+    resolveFast({ records: [candidates[1]!], page: 1, size: 200, total: 1, pages: 1 })
+    await fast
+    resolveSlow({ records: [candidates[0]!], page: 1, size: 200, total: 1, pages: 1 })
+    await slow
+    await flushPromises()
+
+    const labels = wrapper.findAllComponents({ name: 'ElOption' }).map((option) => String(option.props('label') || ''))
+    expect(labels.some((label) => label.includes('OB-2'))).toBe(true)
+    expect(labels.some((label) => label.includes('OB-1'))).toBe(false)
+    wrapper.unmount()
+  })
+
+  it('replaces frozen booking snapshots when switching the selected booking', async () => {
+    const wrapper = mount(TruckAppointmentForm, { props: { modelValue: { ...model } }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    const selects = wrapper.findAllComponents({ name: 'ElSelect' })
+    selects[0]!.vm.$emit('update:modelValue', 'booking-1')
+    await flushPromises()
+    selects[0]!.vm.$emit('update:modelValue', 'booking-2')
+    await flushPromises()
+    const emitted = wrapper.emitted('update:modelValue')?.at(-1)?.[0] as SaveTruckAppointmentRequest
+    expect(emitted.oceanBookingId).toBe('booking-2')
+    expect(emitted.billOfLadingNo).toBe('BL-2')
+    expect(emitted.warehouseId).toBe('WH-2')
+    const labels = wrapper.findAllComponents({ name: 'ElOption' }).map((option) => String(option.props('label') || ''))
+    expect(labels.some((label) => label.includes('OB-2'))).toBe(true)
+    wrapper.unmount()
+  })
+
+  it('ignores stale current-booking details when a cached edit route changes', async () => {
+    let resolveFirst!: (value: ReturnType<typeof detail>) => void
+    let resolveSecond!: (value: ReturnType<typeof detail>) => void
+    vi.mocked(getOceanBooking).mockImplementation((id) => new Promise((resolve) => {
+      if (id === 'booking-1') resolveFirst = resolve as typeof resolveFirst
+      else resolveSecond = resolve as typeof resolveSecond
+    }) as never)
+    const firstResource = resource('appointment-1', 'booking-1')
+    const secondResource = resource('appointment-2', 'booking-2')
+    const wrapper = mount(TruckAppointmentForm, { props: { modelValue: { ...model, oceanBookingId: 'booking-1' }, resource: firstResource }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    await wrapper.setProps({ modelValue: { ...model, oceanBookingId: 'booking-2' }, resource: secondResource })
+    await flushPromises()
+
+    resolveSecond(detail('booking-2'))
+    await flushPromises()
+    resolveFirst({ ...detail('booking-1'), documents: [] })
+    await flushPromises()
+
+    const labels = wrapper.findAllComponents({ name: 'ElOption' }).map((option) => String(option.props('label') || ''))
+    expect(labels.some((label) => label.includes('OB-2') && label.includes('不可重选'))).toBe(true)
+    expect(labels.some((label) => label.includes('OB-1'))).toBe(false)
+    expect(wrapper.text()).not.toContain('所选订舱缺少有效的订舱确认文件或提单文件')
+    expect(listTruckAppointmentCandidates).not.toHaveBeenCalled()
+    wrapper.unmount()
+  })
+
+  it('preserves the business code and request trace when booking readiness fails', async () => {
+    vi.mocked(getOceanBooking).mockRejectedValueOnce(new ApiResponseError('订舱版本冲突', 'A0409', 409, undefined, 'req-booking', 'trace-booking'))
+    const current = resource('appointment-1', 'booking-1')
+    const wrapper = mount(TruckAppointmentForm, { props: { modelValue: { ...model, oceanBookingId: 'booking-1' }, resource: current }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(wrapper.text()).toContain('订舱版本冲突')
+    expect(wrapper.text()).toContain('A0409')
+    expect(wrapper.text()).toContain('req-booking')
+    expect(wrapper.text()).toContain('trace-booking')
+    wrapper.unmount()
+  })
+
+  it('flags an edit binding whose booking has become unreleased without adding it to create candidates', async () => {
+    vi.mocked(getOceanBooking).mockResolvedValueOnce({ ...detail('booking-1'), status: 'DRAFT' } as never)
+    const current = resource('appointment-1', 'booking-1')
+    const wrapper = mount(TruckAppointmentForm, { props: { modelValue: { ...model, oceanBookingId: 'booking-1' }, resource: current }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(wrapper.text()).toContain('当前绑定订舱已不是放舱状态')
+    expect(listTruckAppointmentCandidates).not.toHaveBeenCalled()
+    wrapper.unmount()
+  })
+
+  it('starts with five main fields and optional collapsed dispatch information', async () => {
+    const wrapper = mount(TruckAppointmentForm, { props: { modelValue: { ...model } }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(wrapper.findAll('.appointment-grid > .el-form-item').filter(item => !item.element.closest('details'))).toHaveLength(5)
+    expect((wrapper.get('details').element as HTMLDetailsElement).open).toBe(false)
+    for (const label of ['门店名称', '司机身份证号', '毛重（kg）', '体积（m³）', '在途分钟', '托盘数量', '查看附件引用']) expect(wrapper.text()).not.toContain(label)
+    expect(wrapper.findAllComponents({ name: 'ElSelect' })).toHaveLength(2)
+    expect(wrapper.text()).toContain('元')
+    expect(wrapper.text()).toContain('保存预约')
+    wrapper.unmount()
+  })
+
+  it('copies supplier contacts and replaces or clears them when switching suppliers', async () => {
+    const wrapper = mount(TruckAppointmentForm, { props: { modelValue: { ...model } }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(listSuppliers).toHaveBeenCalledWith({ page: 1, size: 200, category: 'TRUCKING', truckingScope: 'DOMESTIC', status: 'ACTIVE' })
+    const supplier = wrapper.findAllComponents({ name: 'ElSelect' })[1]!
+    expect(supplier.findAllComponents({ name: 'ElOption' }).map(option => option.props('value'))).not.toContain('overseas-1')
+    supplier.vm.$emit('update:modelValue', 'carrier-1')
+    await flushPromises()
+    expect(wrapper.emitted('update:modelValue')!.at(-1)![0]).toMatchObject({ carrierId: 'carrier-1', fleetContact: '张调度', fleetPhone: '13800000001', currency: 'RMB' })
+    expect(wrapper.get('[aria-label="车队联系方式"]').text()).toContain('张调度')
+    supplier.vm.$emit('update:modelValue', 'carrier-2')
+    await flushPromises()
+    expect(wrapper.emitted('update:modelValue')!.at(-1)![0]).toMatchObject({ carrierId: 'carrier-2', fleetContact: '李调度', fleetPhone: '13800000002' })
+    supplier.vm.$emit('update:modelValue', '')
+    await flushPromises()
+    expect(wrapper.emitted('update:modelValue')!.at(-1)![0]).toMatchObject({ carrierId: null, carrierName: null, fleetContact: null, fleetPhone: null })
+    wrapper.unmount()
+  })
+
+  it('preserves saved contact overrides and supplementary values when editing', async () => {
+    const wrapper = mount(TruckAppointmentForm, { props: { modelValue: { ...model, oceanBookingId: 'booking-1', carrierId: 'carrier-1', fleetContact: '本次调度', fleetPhone: '13900000000', storeName: '目的门店', grossWeightKg: '120.00' }, resource: resource('appointment-1', 'booking-1') }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    wrapper.findAllComponents({ name: 'ElSelect' })[1]!.vm.$emit('update:modelValue', 'carrier-1')
+    await flushPromises()
+    expect(wrapper.get('[aria-label="车队联系方式"]').text()).toContain('本次调度')
+    expect(wrapper.text()).toContain('其他已存资料')
+    expect(wrapper.findAllComponents({ name: 'ElInput' }).some(input => input.props('modelValue') === '目的门店')).toBe(true)
+    wrapper.unmount()
+  })
+
+  it('keeps amount validation at two decimal places on the displayed field', async () => {
+    const valid = { ...model, oceanBookingId: 'booking-1', carrierId: 'carrier-1', plannedLoadingAt: '2026-09-19T09:00:00', payableAmount: '100.00' }
+    const wrapper = mount(TruckAppointmentForm, { props: { modelValue: valid }, global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    await wrapper.setProps({ modelValue: { ...valid, billOfLadingNo: 'BL-1', payableAmount: '100.001' } })
+    await flushPromises()
+    expect(wrapper.findAllComponents({ name: 'ElInput' }).find(input => input.props('placeholder') === '请输入应付拖车费')?.props('modelValue')).toBe('100.001')
+    const rule = wrapper.findComponent({ name: 'ElForm' }).props('rules').payableAmount[0]
+    const reject = vi.fn()
+    rule.validator(null, '100.001', reject)
+    expect(reject).toHaveBeenCalledWith(expect.objectContaining({ message: expect.stringContaining('应付拖车费') }))
+    const accept = vi.fn()
+    rule.validator(null, '100.00', accept)
+    expect(accept).toHaveBeenCalledWith(undefined)
+    wrapper.unmount()
+  })
+})
diff --git a/src/modules/trucking/components/TruckAppointmentForm.test.ts b/src/modules/trucking/components/TruckAppointmentForm.test.ts
new file mode 100644
index 00000000..15a29951
--- /dev/null
+++ b/src/modules/trucking/components/TruckAppointmentForm.test.ts
@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/trucking/components/TruckAppointmentForm.vue'), 'utf8')
+const typesSource = readFileSync(resolve(process.cwd(), 'src/modules/trucking/types.ts'), 'utf8')
+
+describe('TruckAppointmentForm interaction contract', () => {
+  it('requires one server-approved released booking without exposing a container selector', () => {
+    expect(source).toContain('listTruckAppointmentCandidates({ page: 1, size: 200 })')
+    expect(source).toContain("oceanBookingId: [{ required: true, message: '请选择已放舱订舱'")
+    expect(source).not.toContain('prop="containerBookingId"')
+    expect(source).not.toContain('label="柜次"')
+    expect(source).not.toContain('关联订舱（可选）')
+    expect(source).not.toContain('关联柜次（可选）')
+  })
+
+  it('uses only server-owned booking candidates and never rebuilds availability from booking detail', () => {
+    expect(source).toContain('candidates.value = results[1].value.records')
+    expect(source).toContain('new Map<string')
+    expect(source).not.toContain('booking.containers')
+    expect(source).not.toContain('listOceanBookings')
+    expect(source).not.toContain('isIso6346ContainerNumber')
+    expect(source).not.toContain('listContainers')
+  })
+
+  it('does not write legacy container or loading-plan fields', () => {
+    expect(source).not.toContain('draft.containerBookingId')
+    expect(source).not.toContain('draft.loadingPlanId')
+    expect(typesSource).not.toContain("'containerBookingId', 'loadingPlanId'")
+  })
+
+  it('freezes warehouse and bill of lading snapshots without retaining customer data', () => {
+    expect(source).toContain('draft.warehouseId = item.warehouseId')
+    expect(source).toContain('draft.billOfLadingNo = item.billOfLadingNo')
+    expect(source).not.toContain('customerId')
+    expect(source).not.toContain('customerName')
+    expect(source).not.toContain('label="客户"')
+  })
+
+  it('keeps server-side validation authoritative and preserves recoverable option errors', () => {
+    expect(source).toContain('所选订舱缺少有效的订舱确认文件或提单文件')
+    expect(source).toContain('所选订舱缺少有效提单号')
+    expect(source).toContain("booking.status !== 'RELEASED'")
+    expect(source).toContain('bookingContainersError')
+    expect(source).toContain("getApiErrorDetails(cause, '当前绑定订舱资料加载失败，请重试')")
+    expect(source).toContain('<ApiErrorMeta :details="bookingContainersError" />')
+    expect(source).toContain('重新加载选项')
+    expect(source).toContain('重新加载')
+    expect(source).toContain('请选择有效的合作中拖车供应商')
+  })
+
+  it('freezes the current edit booking and marks its fallback option as non-selectable', () => {
+    expect(source).toContain('const relationLocked = computed(() => Boolean(props.resource))')
+    expect(source).toContain('（当前绑定，不可重选）')
+    expect(source).toContain(':disabled="relationLocked"')
+    expect(source).not.toContain('selectedContainerFallback')
+  })
+
+  it('guards current booking detail loads against stale route reuse responses', () => {
+    expect(source).toContain('const sequence = ++bookingLoadSequence')
+    expect(source).toContain("sequence !== bookingLoadSequence || String(draft.oceanBookingId || '') !== bookingId")
+    expect(source).toContain('const sequence = ++optionsLoadSequence')
+    expect(source).toContain('if (sequence !== optionsLoadSequence) return')
+    expect(source).toContain("watch(() => props.resource?.id")
+  })
+
+  it('keeps container identity out of the booking-scoped form', () => {
+    expect(source).not.toContain('柜次')
+    expect(source).not.toContain('装柜计划')
+    expect(source).not.toContain('集装箱号')
+  })
+
+  it('keeps the form usable at 390px', () => {
+    expect(source).toContain('@media (max-width:480px)')
+    expect(source).toContain('min-height:40px')
+  })
+
+  it('suppresses duplicate submits and truncates long booking or container labels', () => {
+    expect(source).toContain('if (props.submitting) return')
+    expect(source).toContain(':deep(.el-select__selected-item)')
+    expect(source).toContain('text-overflow:ellipsis')
+  })
+
+  it('shows fixed yuan beside the amount without an unnecessary currency selector', () => {
+    expect(typesSource).toContain("TRUCK_APPOINTMENT_CURRENCIES = ['RMB']")
+    expect(source).toContain('<template #append>元</template>')
+    expect(source).not.toContain('placeholder="请选择币种"')
+    expect(source).not.toContain('receivableAmount')
+    expect(source).toContain('aria-label="订舱带入信息"')
+    expect(source).not.toContain('label="提单号"')
+  })
+
+  it('keeps the compact appointment fields in two columns without horizontal overflow', () => {
+    expect(source).toContain('grid-template-columns:repeat(2,minmax(0,1fr))')
+    expect(source).toContain('max-width:1040px')
+    expect(source).toContain('grid-column:1 / -1')
+    expect(source).not.toContain('overflow-x:auto')
+  })
+})
diff --git a/src/modules/trucking/components/TruckAppointmentForm.vue b/src/modules/trucking/components/TruckAppointmentForm.vue
new file mode 100644
index 00000000..a2e49740
--- /dev/null
+++ b/src/modules/trucking/components/TruckAppointmentForm.vue
@@ -0,0 +1,271 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, reactive, ref, watch } from 'vue'
+import type { FormInstance, FormRules } from 'element-plus'
+import { Eye, Save } from '@lucide/vue'
+import { normalizeTruckAppointmentCurrency, type SaveTruckAppointmentRequest, type TruckAppointmentCandidate, type TruckAppointmentResource } from '../types'
+import { listTruckAppointmentCandidates } from '../api/platformTrucking'
+import { listSuppliers, type Supplier } from '@/modules/suppliers'
+import { getOceanBooking, type OceanBookingDocument } from '@/modules/ocean-bookings'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+
+const props = defineProps<{ modelValue: SaveTruckAppointmentRequest; resource?: TruckAppointmentResource | null; readonly?: boolean; submitting?: boolean; submitBlocked?: boolean }>()
+const emit = defineEmits<{ 'update:modelValue': [SaveTruckAppointmentRequest]; submit: []; attachments: [] }>()
+const formRef = ref<FormInstance>()
+const relationWarning = ref('')
+const dispatchDetailsOpen = ref(false)
+const bookingContainersLoading = ref(false)
+const bookingContainersError = ref<ApiErrorDetails | null>(null)
+const bookingDocuments = ref<OceanBookingDocument[]>([])
+const relationLocked = computed(() => Boolean(props.resource))
+const defaults: Partial<SaveTruckAppointmentRequest> = { expectedVersion: 0, currency: 'RMB', payableAmount: '0.00' }
+function normalizeDraft(value: SaveTruckAppointmentRequest): SaveTruckAppointmentRequest { return { ...defaults, ...value, currency: normalizeTruckAppointmentCurrency(value.currency) } }
+const draft = reactive<SaveTruckAppointmentRequest>(normalizeDraft(props.modelValue))
+watch(() => props.modelValue, (value) => Object.assign(draft, normalizeDraft(value)), { deep: true })
+watch(draft, (value) => emit('update:modelValue', { ...value }), { deep: true })
+const nonNegative = (label: string, integer = false, precision = 3) => ({ validator: (_rule: unknown, value: unknown, callback: (error?: Error) => void) => {
+  if (value === null || value === undefined || value === '') return callback()
+  const text = String(value).trim(); const valid = integer ? /^\d+$/.test(text) : new RegExp(`^\\d+(?:\\.\\d{1,${precision}})?$`).test(text)
+  callback(valid ? undefined : new Error(`${label}请输入${integer ? '非负整数' : '非负数字'}`))
+}, trigger: ['blur', 'change'] })
+const phoneRule = (label: string) => ({ validator: (_rule: unknown, value: unknown, callback: (error?: Error) => void) => {
+  if (!value || /^[0-9+()\-\s]{6,32}$/.test(String(value).trim())) callback()
+  else callback(new Error(`${label}格式不正确`))
+}, trigger: 'blur' })
+const rules: FormRules = {
+  oceanBookingId: [{ required: true, message: '请选择已放舱订舱', trigger: 'change' }, { validator: (_rule, value, callback) => {
+    if (!(bookings.value.some((item) => item.id === String(value)) || (relationLocked.value && selectedBookingFallback.value?.id === String(value)))) return callback(new Error('请选择可创建拖车单的已放舱订舱'))
+    if (bookingContainersError.value) return callback(new Error('订舱资料状态加载失败，请重试'))
+    if (!draft.billOfLadingNo?.trim()) return callback(new Error('所选订舱缺少有效提单号'))
+    return callback(bookingDocumentReady.value ? undefined : new Error('所选订舱缺少有效的订舱确认文件或提单文件'))
+  }, trigger: 'change' }],
+  carrierId: [{ required: true, message: '请选择拖车供应商', trigger: 'change' }, { validator: (_rule, value, callback) => callback(selectableCarriers.value.some((item) => String(item.id) === String(value)) ? undefined : new Error('请选择有效的合作中拖车供应商')), trigger: 'change' }],
+  plannedLoadingAt: [{ required: true, message: '请选择预约装柜时间', trigger: 'change' }],
+  fleetPhone: [phoneRule('车队电话')], driverPhone: [phoneRule('司机电话')], storePhone: [phoneRule('门店电话')],
+  packageCount: [nonNegative('件数', true)], palletCount: [nonNegative('托盘数量', true)], transitMinutes: [nonNegative('在途分钟', true)],
+  grossWeightKg: [nonNegative('毛重')], volumeCbm: [nonNegative('体积')], payableAmount: [nonNegative('应付拖车费', false, 2)],
+}
+const carriers = ref<Supplier[]>([])
+const candidates = ref<TruckAppointmentCandidate[]>([])
+const optionsLoading = ref(false)
+const optionsError = ref('')
+let bookingLoadSequence = 0
+let optionsLoadSequence = 0
+const selectableCarriers = computed(() => carriers.value.filter((item) => (
+  item.status === 'ACTIVE' && item.truckingScope === 'DOMESTIC'
+)))
+const bookings = computed(() => {
+  const result = new Map<string, { id: string; bookingNo: string; billOfLadingNo: string | null; warehouseId: string; warehouseName: string | null; bookingDocumentReady: boolean }>()
+  for (const item of candidates.value) if (!result.has(item.oceanBookingId)) result.set(item.oceanBookingId, {
+    id: item.oceanBookingId,
+    bookingNo: item.oceanBookingNo,
+    billOfLadingNo: item.billOfLadingNo,
+    warehouseId: item.warehouseId,
+    warehouseName: item.warehouseName,
+    bookingDocumentReady: item.bookingDocumentReady,
+  })
+  return [...result.values()]
+})
+const selectedReleasedBooking = computed(() => bookings.value.find((item) => item.id === draft.oceanBookingId) || null)
+const bookingDocumentReady = computed(() => relationLocked.value
+  ? bookingDocuments.value.some((document) => document.valid && ['BOOKING_CONFIRMATION', 'BILL_OF_LADING'].includes(document.documentType))
+  : Boolean(selectedReleasedBooking.value?.bookingDocumentReady))
+const selectedBookingFallback = computed(() => {
+  const id = draft.oceanBookingId
+  const snapshot = props.resource
+  if (!id || !relationLocked.value || String(snapshot?.oceanBookingId) !== String(id)) return null
+  return { id: String(id), label: `${snapshot?.oceanBookingNo || '订舱号缺失'}（当前绑定，不可重选）` }
+})
+function selectCarrier(carrierId: string) {
+  if (String(draft.carrierId || '') === carrierId) return
+  const carrier = selectableCarriers.value.find((item) => String(item.id) === carrierId)
+  draft.carrierId = carrier?.id || null
+  draft.carrierName = carrier?.name || null
+  draft.fleetContact = carrier?.contactName || null
+  draft.fleetPhone = carrier?.phone || null
+}
+function toggleDispatchDetails(event: Event) {
+  dispatchDetailsOpen.value = (event.target as HTMLDetailsElement).open
+}
+async function loadCurrentBookingContext(bookingId: string) {
+  const sequence = ++bookingLoadSequence
+  bookingContainersLoading.value = true
+  bookingContainersError.value = null
+  try {
+    const booking = await getOceanBooking(bookingId)
+    if (sequence !== bookingLoadSequence || String(draft.oceanBookingId || '') !== bookingId) return
+    if (booking.status !== 'RELEASED') {
+      bookingDocuments.value = []
+      bookingContainersError.value = { message: '当前绑定订舱已不是放舱状态，请刷新后处理' }
+      return
+    }
+    draft.warehouseId = booking.warehouseId
+    draft.billOfLadingNo = booking.billOfLadingNo
+    bookingDocuments.value = booking.documents || []
+  } catch (cause) {
+    if (sequence !== bookingLoadSequence || String(draft.oceanBookingId || '') !== bookingId) return
+    bookingDocuments.value = []
+    bookingContainersError.value = getApiErrorDetails(cause, '当前绑定订舱资料加载失败，请重试')
+  } finally {
+    if (sequence === bookingLoadSequence) bookingContainersLoading.value = false
+  }
+}
+async function selectBooking(bookingId: string) {
+  bookingLoadSequence += 1
+  const item = bookings.value.find((entry) => entry.id === bookingId)
+  draft.oceanBookingId = item?.id || null
+  bookingDocuments.value = []
+  relationWarning.value = ''
+  if (!item) {
+    draft.warehouseId = null
+    draft.billOfLadingNo = null
+    return
+  }
+  draft.warehouseId = item.warehouseId
+  draft.billOfLadingNo = item.billOfLadingNo
+}
+async function loadOptions() {
+  const sequence = ++optionsLoadSequence
+  optionsLoading.value = true; optionsError.value = ''
+  candidates.value = []
+  const results = await Promise.allSettled([
+    listSuppliers({ page: 1, size: 200, category: 'TRUCKING', truckingScope: 'DOMESTIC', status: 'ACTIVE' }),
+    relationLocked.value ? Promise.resolve({ records: [] as TruckAppointmentCandidate[] }) : listTruckAppointmentCandidates({ page: 1, size: 200 }),
+  ])
+  if (sequence !== optionsLoadSequence) return
+  if (results[0].status === 'fulfilled') carriers.value = results[0].value.records.filter((item) => item.category === 'TRUCKING' && item.status === 'ACTIVE' && item.truckingScope === 'DOMESTIC')
+  if (results[1].status === 'fulfilled') candidates.value = results[1].value.records
+  const failed = ['拖车供应商', '可用订舱'].filter((_, index) => results[index]?.status === 'rejected')
+  if (failed.length) optionsError.value = `${failed.join('、')}选项加载失败`
+  optionsLoading.value = false
+  if (relationLocked.value && draft.oceanBookingId) await loadCurrentBookingContext(String(draft.oceanBookingId))
+  else if (draft.oceanBookingId) {
+    const candidate = candidates.value.find((item) => item.oceanBookingId === draft.oceanBookingId)
+    if (candidate) {
+      draft.warehouseId = candidate.warehouseId
+      draft.billOfLadingNo = candidate.billOfLadingNo
+    } else {
+      draft.oceanBookingId = null
+    }
+  }
+}
+async function validate() {
+  try { return await formRef.value?.validate() }
+  catch (fields) {
+    if (fields && typeof fields === 'object' && ('fleetPhone' in fields || 'driverPhone' in fields)) dispatchDetailsOpen.value = true
+    return false
+  }
+}
+async function submitForm() { if (props.submitting) return; if (await validate()) emit('submit') }
+defineExpose({ validate, loadOptions })
+onMounted(() => { void loadOptions() })
+watch(() => props.readonly, (readonly) => { if (!readonly && !carriers.value.length) void loadOptions() })
+watch(() => props.resource?.id, (id, previous) => { if (id && id !== previous) void loadOptions() })
+</script>
+
+<template>
+  <el-form ref="formRef" :model="draft" :rules="rules" label-position="top" :disabled="readonly || submitting" class="truck-form admin-density density-form" :class="{ 'truck-form--create': !resource }">
+    <div class="relation-note">
+      <span>选择订舱和拖车供应商，约定装柜时间即可保存预约。</span>
+      <div v-if="$slots['relation-note-actions']" class="relation-note__actions"><slot name="relation-note-actions" /></div>
+    </div>
+    <el-alert v-if="relationWarning" type="warning" :closable="false" show-icon :title="relationWarning" class="relation-alert" />
+    <el-alert v-if="optionsError" type="warning" :closable="false" show-icon :title="optionsError" class="relation-alert"><el-button link type="warning" :loading="optionsLoading" @click="loadOptions">重新加载选项</el-button></el-alert>
+    <div class="appointment-grid">
+      <el-form-item label="订舱" prop="oceanBookingId">
+        <el-select :model-value="draft.oceanBookingId" filterable :disabled="relationLocked" placeholder="请选择已放舱订舱" :loading="optionsLoading" no-data-text="暂无可创建拖车单的已放舱订舱" @update:model-value="selectBooking(String($event || ''))">
+          <el-option v-if="selectedBookingFallback" :key="selectedBookingFallback.id" :label="selectedBookingFallback.label" :value="selectedBookingFallback.id" disabled />
+          <el-option v-for="item in bookings" :key="item.id" :label="`${item.bookingNo || '订舱号缺失'} / 提单号：${item.billOfLadingNo || '缺失'}`" :value="item.id" />
+        </el-select>
+        <dl v-if="draft.oceanBookingId" class="selection-summary" aria-label="订舱带入信息">
+          <div><dt>仓库</dt><dd>{{ selectedReleasedBooking?.warehouseName || resource?.warehouseName || '—' }}</dd></div>
+          <div><dt>提单号</dt><dd>{{ draft.billOfLadingNo || '—' }}</dd></div>
+        </dl>
+        <div v-if="bookingContainersError" class="field-error"><span>{{ bookingContainersError.message }}</span><ApiErrorMeta :details="bookingContainersError" /><el-button link type="primary" :loading="bookingContainersLoading" @click="draft.oceanBookingId && loadCurrentBookingContext(String(draft.oceanBookingId))">重新加载</el-button></div>
+      </el-form-item>
+      <el-form-item label="拖车供应商" prop="carrierId">
+        <el-select :model-value="draft.carrierId" filterable clearable placeholder="请选择拖车供应商" :loading="optionsLoading" no-data-text="暂无可用拖车供应商" @update:model-value="selectCarrier(String($event || ''))">
+          <el-option v-if="draft.carrierId && !selectableCarriers.some((item) => String(item.id) === String(draft.carrierId))" :label="draft.carrierName || '当前供应商（需重新选择）'" :value="String(draft.carrierId)" disabled />
+          <el-option v-for="item in selectableCarriers" :key="String(item.id)" :label="item.name" :value="String(item.id)" />
+        </el-select>
+        <dl v-if="draft.carrierId" class="selection-summary" aria-label="车队联系方式">
+          <div><dt>联系人</dt><dd>{{ draft.fleetContact || '—' }}</dd></div>
+          <div><dt>电话</dt><dd>{{ draft.fleetPhone || '—' }}</dd></div>
+        </dl>
+      </el-form-item>
+      <div v-if="draft.oceanBookingId && !bookingContainersLoading && !bookingContainersError" class="appointment-grid__wide readiness-alerts">
+        <el-alert v-if="!draft.billOfLadingNo?.trim()" title="所选订舱缺少有效提单号，暂不能创建或保存拖车预约" type="warning" :closable="false" show-icon />
+        <el-alert v-if="!bookingDocumentReady" title="所选订舱缺少有效的订舱确认文件或提单文件，暂不能创建或保存拖车预约" type="warning" :closable="false" show-icon />
+      </div>
+      <el-form-item label="预约装柜时间" prop="plannedLoadingAt"><el-date-picker v-model="draft.plannedLoadingAt" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" placeholder="请选择预约装柜时间" /></el-form-item>
+      <el-form-item label="拖车费" prop="payableAmount"><el-input v-model="draft.payableAmount" inputmode="decimal" placeholder="请输入应付拖车费"><template #append>元</template></el-input><div class="field-hint">人民币；离仓完成后计入应付。</div></el-form-item>
+      <el-form-item class="appointment-grid__wide" label="备注（选填）"><el-input v-model="draft.remark" type="textarea" :rows="2" maxlength="1000" placeholder="例如到仓时间要求、装柜注意事项" /></el-form-item>
+    </div>
+    <details class="dispatch-details" :open="dispatchDetailsOpen" @toggle="toggleDispatchDetails">
+      <summary>派车信息<span>选填，司机和车辆确定后可补充</span></summary>
+      <div class="appointment-grid dispatch-grid">
+        <el-form-item label="车队联系人"><el-input v-model="draft.fleetContact" maxlength="64" placeholder="选择供应商后带入，可修改" /></el-form-item>
+        <el-form-item label="车队电话" prop="fleetPhone"><el-input v-model="draft.fleetPhone" maxlength="32" placeholder="选择供应商后带入，可修改" /></el-form-item>
+        <el-form-item label="司机"><el-input v-model="draft.driverName" maxlength="64" placeholder="司机姓名" /></el-form-item>
+        <el-form-item label="司机电话" prop="driverPhone"><el-input v-model="draft.driverPhone" maxlength="32" placeholder="司机联系电话" /></el-form-item>
+        <el-form-item label="车牌号"><el-input v-model="draft.vehicleNo" maxlength="32" placeholder="车牌或车头号" /></el-form-item>
+      </div>
+    </details>
+    <details v-if="resource" class="dispatch-details">
+      <summary>其他已存资料</summary>
+      <el-row :gutter="16">
+      <el-col :xs="24" :sm="12"><el-form-item label="司机身份证号"><el-input v-model="draft.driverIdCard" placeholder="请输入司机身份证号" /></el-form-item></el-col>
+      <el-col v-if="resource" :xs="24" :sm="12"><el-form-item label="实际装箱时间"><el-input :model-value="resource.actualLoadingAt || ''" disabled /></el-form-item></el-col>
+      <el-col :xs="24" :sm="8"><el-form-item label="件数" prop="packageCount"><el-input v-model="draft.packageCount" inputmode="numeric" placeholder="请输入件数" /></el-form-item></el-col>
+      <el-col :xs="24" :sm="8"><el-form-item label="毛重（kg）" prop="grossWeightKg"><el-input v-model="draft.grossWeightKg" inputmode="decimal" placeholder="请输入毛重" /></el-form-item></el-col>
+      <el-col :xs="24" :sm="8"><el-form-item label="体积（m³）" prop="volumeCbm"><el-input v-model="draft.volumeCbm" inputmode="decimal" placeholder="请输入体积" /></el-form-item></el-col>
+      <el-col :xs="24" :sm="8"><el-form-item label="托盘数量" prop="palletCount"><el-input v-model="draft.palletCount" inputmode="numeric" placeholder="请输入托盘数量" /></el-form-item></el-col>
+      <el-col :xs="24" :sm="8"><el-form-item label="在途分钟" prop="transitMinutes"><el-input v-model="draft.transitMinutes" inputmode="numeric" placeholder="请输入预计在途分钟" /></el-form-item></el-col>
+      <el-col :xs="24" :sm="12"><el-form-item label="门店名称"><el-input v-model="draft.storeName" placeholder="请输入目的门店名称" /></el-form-item></el-col>
+      <el-col class="wide-column" :xs="24" :sm="12"><el-form-item label="门店地址"><el-input v-model="draft.storeAddress" placeholder="请输入目的门店地址" /></el-form-item></el-col>
+      <el-col :xs="24" :sm="12"><el-form-item label="门店联系人"><el-input v-model="draft.storeContact" placeholder="请输入门店联系人" /></el-form-item></el-col>
+      <el-col :xs="24" :sm="12"><el-form-item label="门店电话" prop="storePhone"><el-input v-model="draft.storePhone" placeholder="请输入门店联系电话" maxlength="32" show-word-limit /></el-form-item></el-col>
+      <el-col :xs="24" :sm="12"><el-form-item label="城市"><el-input v-model="draft.storeCity" placeholder="请输入城市" /></el-form-item></el-col>
+      <el-col :xs="24" :sm="12"><el-form-item label="邮编"><el-input v-model="draft.storeZipcode" placeholder="请输入邮政编码" /></el-form-item></el-col>
+      <el-col class="wide-column" :xs="24" :sm="12"><el-form-item label="PO"><el-input v-model="draft.poNo" placeholder="请输入采购订单号（可选）" /></el-form-item></el-col>
+      </el-row>
+    </details>
+    <div class="form-actions"><el-button v-if="resource" :disabled="submitting" @click="emit('attachments')"><Eye :size="16" />查看附件引用</el-button><el-button v-if="!readonly" type="primary" :loading="submitting" :disabled="submitBlocked" @click="submitForm"><Save :size="16" />{{ resource ? '保存' : '保存预约' }}</el-button></div>
+  </el-form>
+</template>
+
+<style scoped>
+.truck-form { min-width:0; padding-bottom:var(--admin-space-1); }
+.truck-form--create { max-width:1040px; margin-inline:auto; }
+.relation-note { display:flex; align-items:center; justify-content:space-between; gap:var(--admin-space-4); margin-bottom:var(--admin-space-5); color:var(--cc-muted); font-size:var(--admin-font-caption); line-height:1.5; }
+.relation-note__actions { display:flex; flex:0 0 auto; }
+.relation-alert { margin-bottom:var(--admin-space-5); }
+.appointment-grid { display:grid; grid-template-columns:repeat(2,minmax(0,1fr)); column-gap:var(--admin-space-6); }
+.appointment-grid__wide { grid-column:1 / -1; }
+:deep(.el-form-item), :deep(.el-form-item__content) { min-width:0; }
+:deep(.el-select), :deep(.el-date-editor), :deep(.el-input), :deep(.el-textarea) { width:100%; max-width:100%; }
+:deep(.el-select__selected-item) { min-width:0; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+.selection-summary { display:flex; flex-wrap:wrap; gap:var(--admin-space-1) var(--admin-space-5); width:100%; margin:var(--admin-space-2) 0 0; color:var(--cc-muted); font-size:var(--admin-font-caption); line-height:1.5; }
+.selection-summary div { display:flex; min-width:0; gap:var(--admin-space-2); }
+.selection-summary dt { flex-shrink:0; }
+.selection-summary dd { margin:0; color:var(--el-text-color-regular); overflow-wrap:anywhere; }
+.field-error,.field-hint { width:100%; display:flex; flex-wrap:wrap; gap:var(--admin-space-2); margin-top:var(--admin-space-1); color:var(--cc-muted); font-size:var(--admin-font-caption); line-height:1.5; }
+.field-error { color:var(--el-color-danger); }
+.readiness-alerts:empty { display:none; }
+.readiness-alerts :deep(.el-alert) { margin-bottom:var(--admin-space-4); }
+.dispatch-details { border-top:1px solid var(--el-border-color-lighter); }
+.dispatch-details summary { padding:var(--admin-space-4) 0; cursor:pointer; font-size:var(--admin-font-body); font-weight:600; color:var(--el-text-color-primary); }
+.dispatch-details summary span { margin-left:var(--admin-space-3); color:var(--cc-muted); font-size:var(--admin-font-caption); font-weight:400; }
+.dispatch-details summary:focus-visible { outline:2px solid var(--cc-primary); outline-offset:2px; }
+.dispatch-grid { grid-template-columns:repeat(3,minmax(0,1fr)); }
+.form-actions { display:flex; justify-content:flex-end; gap:var(--admin-space-3); padding-top:var(--admin-space-4); border-top:1px solid var(--el-border-color-lighter); }
+@media (max-width:720px) {
+  .appointment-grid,.dispatch-grid { grid-template-columns:minmax(0,1fr); }
+  .dispatch-details summary span { display:block; margin-left:var(--admin-space-4); }
+}
+@media (max-width:480px) {
+  .form-actions { position:sticky; bottom:0; background:var(--el-bg-color); padding-bottom:var(--admin-space-3); z-index:2; }
+  .form-actions :deep(.el-button) { flex:1; min-height:40px; }
+}
+</style>
diff --git a/src/modules/trucking/components/TruckAttachmentDialog.test.ts b/src/modules/trucking/components/TruckAttachmentDialog.test.ts
new file mode 100644
index 00000000..470d3311
--- /dev/null
+++ b/src/modules/trucking/components/TruckAttachmentDialog.test.ts
@@ -0,0 +1,43 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/trucking/components/TruckAttachmentDialog.vue'), 'utf8')
+
+describe('TruckAttachmentDialog interaction governance', () => {
+  it('shows existing attachments without exposing file-service internals', () => {
+    expect(source).toContain('预约附件')
+    expect(source).toContain('attachmentTypeLabel(item.attachmentType)')
+    expect(source).not.toContain('文件 ID')
+    expect(source).not.toContain('item.objectKey')
+  })
+
+  it('provides scoped upload and deletion without exposing manual file ids', () => {
+    expect(source).not.toContain("BILL_OF_LADING: '提单文件'")
+    expect(source).toContain("DISPATCH_ORDER: '派车单'")
+    expect(source).not.toContain('referenceTruckAppointmentAttachment')
+    expect(source).not.toContain('输入文件服务 ID')
+    expect(source).toContain('uploadTruckAppointmentAttachment')
+    expect(source).toContain('上传并关联')
+    expect(source).toContain('deleteTruckAppointmentAttachment')
+    expect(source).toContain("confirmButtonText: '确认', cancelButtonText: '取消'")
+    expect(source).toContain('@click="remove(item)">删除</el-button>')
+    expect(source).toContain('size="small" type="danger" plain')
+    expect(source).not.toContain(' text type="danger"')
+  })
+
+  it('keeps list-only access read-only and preserves traced mutation failures', () => {
+    expect(source).toContain('v-if="props.canManage" class="upload-panel"')
+    expect(source).toContain('props.appointmentId && props.canManage && item.id')
+    expect(source).toContain('if (busy.value || !props.appointmentId || !selectedFile.value || !props.canManage) return')
+    expect(source).toContain('if (busy.value || !props.appointmentId || !item.id || !props.canManage) return')
+    expect(source).toContain("getApiErrorDetails(cause, '附件上传失败，请稍后重试')")
+    expect(source).toContain("getApiErrorDetails(cause, '附件删除失败，请稍后重试')")
+    expect(source).toContain('<ApiErrorMeta :details="error" />')
+  })
+
+  it('wraps long Unicode file names without hiding the actions', () => {
+    expect(source).toContain('overflow-wrap:anywhere')
+    expect(source).toContain('.attachment-row>div{min-width:0}')
+  })
+})
diff --git a/src/modules/trucking/components/TruckAttachmentDialog.vue b/src/modules/trucking/components/TruckAttachmentDialog.vue
new file mode 100644
index 00000000..74b57e62
--- /dev/null
+++ b/src/modules/trucking/components/TruckAttachmentDialog.vue
@@ -0,0 +1,39 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { ref } from 'vue'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import { FileUp } from '@lucide/vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { deleteTruckAppointmentAttachment, uploadTruckAppointmentAttachment } from '../api/platformTrucking'
+import type { TruckAttachmentReference, TruckAttachmentType } from '../types'
+const props = defineProps<{ modelValue: boolean; appointmentId?: string; attachments: TruckAttachmentReference[]; canManage?: boolean }>()
+const emit = defineEmits<{ 'update:modelValue': [boolean]; changed: [] }>()
+const busy = ref(false)
+const error = ref<ApiErrorDetails | null>(null)
+const selectedFile = ref<File | null>(null)
+const selectedType = ref<TruckAttachmentType>('OTHER')
+const attachmentTypeLabels: Record<TruckAttachmentType, string> = { DISPATCH_ORDER: '派车单', DRIVER_DOCUMENT: '司机证件', VEHICLE_DOCUMENT: '车辆证件', OTHER: '其他附件' }
+function attachmentTypeLabel(value: string | null | undefined) { return value && value in attachmentTypeLabels ? attachmentTypeLabels[value as TruckAttachmentType] : '业务附件' }
+function selectFile(upload: { raw?: File }) { selectedFile.value = upload.raw || null }
+async function upload() { if (busy.value || !props.appointmentId || !selectedFile.value || !props.canManage) return; busy.value = true; error.value = null; try { await uploadTruckAppointmentAttachment(props.appointmentId, selectedFile.value, selectedType.value); selectedFile.value = null; emit('changed'); ElMessage.success('附件上传成功') } catch (cause) { error.value = getApiErrorDetails(cause, '附件上传失败，请稍后重试') } finally { busy.value = false } }
+async function remove(item: TruckAttachmentReference) { if (busy.value || !props.appointmentId || !item.id || !props.canManage) return; busy.value = true; error.value = null; try { await ElMessageBox.confirm('确认删除该附件引用？', '删除确认', { customClass: 'admin-density-confirm', confirmButtonText: '确认', cancelButtonText: '取消', type: 'warning' }); await deleteTruckAppointmentAttachment(props.appointmentId, item.id); emit('changed'); ElMessage.success('附件引用已删除') } catch (cause) { if (cause === 'cancel' || cause === 'close') return; error.value = getApiErrorDetails(cause, '附件删除失败，请稍后重试') } finally { busy.value = false } }
+</script>
+<template>
+  <el-dialog class="admin-density-dialog" :model-value="props.modelValue" title="预约附件" width="min(640px, 94vw)" @update:model-value="emit('update:modelValue', $event)">
+    <el-alert v-if="error" type="error" :closable="true" show-icon @close="error = null"><template #title>{{ error.message }}</template><ApiErrorMeta :details="error" /></el-alert>
+    <div v-if="props.canManage" class="upload-panel"><el-select v-model="selectedType" aria-label="附件类型" style="width:160px"><el-option v-for="(label, type) in attachmentTypeLabels" :key="type" :label="label" :value="type" /></el-select><el-upload :auto-upload="false" :limit="1" :show-file-list="true" :on-change="selectFile" :on-remove="() => { selectedFile = null }"><el-button><FileUp :size="15" />选择附件</el-button></el-upload><el-button type="primary" :loading="busy" :disabled="!selectedFile" @click="upload">上传并关联</el-button></div>
+    <el-empty v-if="attachments.length === 0" description="暂无预约附件" :image-size="72" />
+    <div v-for="item in attachments" :key="item.fileId" class="attachment-row">
+      <div><strong>{{ item.fileName || '未命名文件' }}</strong><small>{{ attachmentTypeLabel(item.attachmentType) }}{{ item.uploadedAt ? ` · ${item.uploadedAt}` : '' }}</small></div>
+      <el-button data-tone="danger" class="density-action" v-if="props.appointmentId && props.canManage && item.id" size="small" type="danger" plain :loading="busy" @click="remove(item)">删除</el-button>
+    </div>
+    <template #footer><el-button type="primary" @click="emit('update:modelValue', false)">关闭</el-button></template>
+  </el-dialog>
+</template>
+<style scoped>
+.upload-panel { display:flex; align-items:center; flex-wrap:wrap; gap:var(--admin-space-3); margin-bottom:var(--admin-space-5); }
+.attachment-row { display:flex; justify-content:space-between; gap:var(--admin-space-5); overflow-wrap:anywhere; margin:0; padding:var(--admin-space-3) 0; border:0; border-bottom:1px solid var(--cc-border); border-radius:0; }.attachment-row small { display:block; margin-top:var(--admin-space-1); color:var(--el-text-color-secondary); }
+.attachment-row>div{min-width:0}.attachment-row strong{overflow-wrap:anywhere}
+@media (max-width: 560px) { .attachment-row { flex-direction:column; margin:0; padding:var(--admin-space-3) 0; border:0; border-bottom:1px solid var(--cc-border); border-radius:0; } }
+</style>
diff --git a/src/modules/trucking/index.ts b/src/modules/trucking/index.ts
new file mode 100644
index 00000000..da61e1dd
--- /dev/null
+++ b/src/modules/trucking/index.ts
@@ -0,0 +1,2 @@
+export * from './types'
+export * from './api/platformTrucking'
diff --git a/src/modules/trucking/iso6346.test.ts b/src/modules/trucking/iso6346.test.ts
new file mode 100644
index 00000000..5e0c2bc6
--- /dev/null
+++ b/src/modules/trucking/iso6346.test.ts
@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest'
+import { isIso6346ContainerNumber, normalizeIso6346ContainerNumber } from './iso6346'
+
+describe('ISO 6346 container numbers', () => {
+  it('normalizes whitespace and validates the equipment category and check digit', () => {
+    expect(normalizeIso6346ContainerNumber(' mscu 663987 0 ')).toBe('MSCU6639870')
+    expect(isIso6346ContainerNumber('MSCU6639870')).toBe(true)
+    expect(isIso6346ContainerNumber('MSCA6639870')).toBe(false)
+    expect(isIso6346ContainerNumber('MSCU6639871')).toBe(false)
+    expect(isIso6346ContainerNumber('MSCU663987')).toBe(false)
+  })
+})
diff --git a/src/modules/trucking/iso6346.ts b/src/modules/trucking/iso6346.ts
new file mode 100644
index 00000000..d1f0f550
--- /dev/null
+++ b/src/modules/trucking/iso6346.ts
@@ -0,0 +1,17 @@
+const letterValues = [10, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 34, 35, 36, 37, 38]
+
+export function normalizeIso6346ContainerNumber(value: string | null | undefined) {
+  return value?.replace(/[\s\u00a0\u3000]+/g, '').toUpperCase() || ''
+}
+
+export function isIso6346ContainerNumber(value: string | null | undefined) {
+  const normalized = normalizeIso6346ContainerNumber(value)
+  if (!/^[A-Z]{3}[UJZ][0-9]{7}$/.test(normalized)) return false
+  let sum = 0
+  for (let index = 0; index < 10; index += 1) {
+    const current = normalized[index]!
+    const number = /[0-9]/.test(current) ? Number(current) : letterValues[current.charCodeAt(0) - 65]!
+    sum += number * (2 ** index)
+  }
+  return Number(normalized[10]) === (sum % 11) % 10
+}
diff --git a/src/modules/trucking/pages/TruckAppointmentCreateView.behavior.test.ts b/src/modules/trucking/pages/TruckAppointmentCreateView.behavior.test.ts
new file mode 100644
index 00000000..cd382a40
--- /dev/null
+++ b/src/modules/trucking/pages/TruckAppointmentCreateView.behavior.test.ts
@@ -0,0 +1,129 @@
+import ElementPlus from 'element-plus'
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { ApiResponseError } from '@/shared/api/http'
+import TruckAppointmentCreateView from './TruckAppointmentCreateView.vue'
+import { createTruckAppointment, listTruckAppointments } from '../api/platformTrucking'
+import type { SaveTruckAppointmentRequest, TruckAppointmentResource } from '../types'
+
+const routing = vi.hoisted(() => ({ query: {} as Record<string, string>, replace: vi.fn(), push: vi.fn() }))
+vi.mock('vue-router', () => ({ useRoute: () => ({ query: routing.query }), useRouter: () => ({ replace: routing.replace, push: routing.push }) }))
+vi.mock('../api/platformTrucking', () => ({ createTruckAppointment: vi.fn(), listTruckAppointments: vi.fn() }))
+
+const existing = (status: TruckAppointmentResource['status']): TruckAppointmentResource => ({
+  id: 'appointment-1', appointmentNo: 'TA-260901-0003', status, oceanBookingId: 'booking-1', attachments: [],
+})
+const page = (records: TruckAppointmentResource[]) => ({ records, page: 1, size: 20, total: records.length, pages: 1 })
+const formStub = {
+  name: 'TruckAppointmentForm',
+  props: ['modelValue', 'submitting', 'submitBlocked'],
+  emits: ['update:modelValue', 'submit', 'attachments'],
+  template: '<div data-form :data-blocked="String(submitBlocked)"><button data-submit @click="$emit(\'submit\')">保存</button></div>',
+}
+type ViewModel = {
+  form: SaveTruckAppointmentRequest
+  submit: () => Promise<void>
+  lookupExistingAppointment: (id: string, autoNavigate?: boolean) => Promise<void>
+  existingAppointment: TruckAppointmentResource | null
+  existingLookupError: { message: string } | null
+  checkedOceanBookingId: string
+}
+
+function mountView() {
+  return mount(TruckAppointmentCreateView, { global: { plugins: [ElementPlus], stubs: { TruckAppointmentForm: formStub, TruckAttachmentDialog: true } } })
+}
+
+describe('TruckAppointmentCreateView existing appointment reuse', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    for (const key of Object.keys(routing.query)) delete routing.query[key]
+    routing.replace.mockResolvedValue(undefined)
+    routing.push.mockResolvedValue(undefined)
+    vi.mocked(listTruckAppointments).mockResolvedValue(page([]))
+    vi.mocked(createTruckAppointment).mockResolvedValue(existing('DRAFT'))
+  })
+
+  it('automatically reuses a DRAFT appointment for a query-prefilled booking', async () => {
+    Object.assign(routing.query, { oceanBookingId: 'booking-1' })
+    vi.mocked(listTruckAppointments).mockResolvedValue(page([existing('DRAFT')]))
+    const wrapper = mountView()
+    await flushPromises()
+    expect(listTruckAppointments).toHaveBeenCalledWith({ oceanBookingId: 'booking-1', page: 1, size: 20 })
+    expect(routing.replace).toHaveBeenCalledWith({ name: 'trucking-detail', params: { id: 'appointment-1' }, query: { edit: '1' } })
+    expect(createTruckAppointment).not.toHaveBeenCalled()
+    wrapper.unmount()
+  })
+
+  it.each(['CANCELLED', 'EXCEPTION'] as const)('allows a new appointment after terminal status %s', async (status) => {
+    Object.assign(routing.query, { oceanBookingId: 'booking-1' })
+    vi.mocked(listTruckAppointments).mockResolvedValue(page([existing(status)]))
+    const wrapper = mountView()
+    await flushPromises()
+    await (wrapper.vm as unknown as ViewModel).submit()
+    expect(createTruckAppointment).toHaveBeenCalledTimes(1)
+    wrapper.unmount()
+  })
+
+  it('opens a completed appointment without allowing another charge', async () => {
+    Object.assign(routing.query, { oceanBookingId: 'booking-1' })
+    vi.mocked(listTruckAppointments).mockResolvedValue(page([existing('COMPLETED')]))
+    const wrapper = mountView()
+    await flushPromises()
+    await (wrapper.vm as unknown as ViewModel).submit()
+    expect(createTruckAppointment).not.toHaveBeenCalled()
+    expect(routing.replace).toHaveBeenCalledWith(expect.objectContaining({ name: 'trucking-detail', query: undefined }))
+    wrapper.unmount()
+  })
+
+  it('keeps request evidence and retry state when existing-appointment lookup fails', async () => {
+    Object.assign(routing.query, { oceanBookingId: 'booking-1' })
+    vi.mocked(listTruckAppointments).mockRejectedValue(new ApiResponseError('预约查询失败', 'A0500', 500, undefined, 'req-existing', 'trace-existing'))
+    const wrapper = mountView()
+    await flushPromises()
+    expect(wrapper.text()).toContain('预约查询失败')
+    expect(wrapper.text()).toContain('req-existing')
+    expect(wrapper.text()).toContain('trace-existing')
+    await (wrapper.vm as unknown as ViewModel).submit()
+    expect(createTruckAppointment).not.toHaveBeenCalled()
+    wrapper.unmount()
+  })
+
+  it('ignores a stale lookup response after the selected booking changes', async () => {
+    let resolveFirst!: (value: ReturnType<typeof page>) => void
+    let resolveSecond!: (value: ReturnType<typeof page>) => void
+    vi.mocked(listTruckAppointments).mockImplementation((query = {}) => new Promise((resolve) => {
+      const { oceanBookingId } = query
+      if (oceanBookingId === 'booking-1') resolveFirst = resolve
+      else resolveSecond = resolve
+    }))
+    const wrapper = mountView()
+    const vm = wrapper.vm as unknown as ViewModel
+    vm.form.oceanBookingId = 'booking-1'
+    await wrapper.vm.$nextTick()
+    vm.form.oceanBookingId = 'booking-2'
+    await wrapper.vm.$nextTick()
+    resolveSecond(page([]))
+    await flushPromises()
+    resolveFirst(page([existing('DRAFT')]))
+    await flushPromises()
+    expect(vm.checkedOceanBookingId).toBe('booking-2')
+    expect(vm.existingAppointment).toBeNull()
+    expect(routing.replace).not.toHaveBeenCalled()
+    wrapper.unmount()
+  })
+
+  it('suppresses duplicate create clicks while the first request is pending', async () => {
+    Object.assign(routing.query, { oceanBookingId: 'booking-1' })
+    let resolveCreate!: (value: TruckAppointmentResource) => void
+    vi.mocked(createTruckAppointment).mockImplementation(() => new Promise((resolve) => { resolveCreate = resolve }))
+    const wrapper = mountView()
+    await flushPromises()
+    const vm = wrapper.vm as unknown as ViewModel
+    const first = vm.submit()
+    const second = vm.submit()
+    expect(createTruckAppointment).toHaveBeenCalledTimes(1)
+    resolveCreate(existing('DRAFT'))
+    await Promise.all([first, second])
+    wrapper.unmount()
+  })
+})
diff --git a/src/modules/trucking/pages/TruckAppointmentCreateView.test.ts b/src/modules/trucking/pages/TruckAppointmentCreateView.test.ts
new file mode 100644
index 00000000..facee0a5
--- /dev/null
+++ b/src/modules/trucking/pages/TruckAppointmentCreateView.test.ts
@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/trucking/pages/TruckAppointmentCreateView.vue'), 'utf8')
+
+describe('TruckAppointmentCreateView booking-bound creation contract', () => {
+  it('starts with only the required booking choice empty until the user selects it', () => {
+    expect(source).toContain('carrierId: null')
+    expect(source).not.toContain('customerId')
+    expect(source).toContain('oceanBookingId: initialOceanBookingId || null, plannedLoadingAt: null')
+    expect(source).not.toContain('initialContainerBookingId')
+    expect(source).toContain('plannedLoadingAt: null')
+    expect(source).toContain("payableAmount: '0.00', currency: 'RMB'")
+    expect(source).not.toContain('receivableAmount')
+    expect(source).toContain('createTruckAppointment({ ...form })')
+  })
+
+  it('keeps the form visible and exposes the real backend error details', () => {
+    expect(source).toContain("getApiErrorDetails(err, '创建失败，请稍后重试')")
+    expect(source).toContain('<ApiErrorMeta :details="error" />')
+    expect(source).toContain('<TruckAppointmentForm :model-value="form"')
+    expect(source).toContain('@update:model-value="updateForm"')
+  })
+
+  it('suppresses duplicate submits while the first create request is pending', () => {
+    expect(source).toContain('if (saving.value || existingLookupLoading.value) return')
+  })
+
+  it('reuses non-terminal appointments by booking and separates lookup failures from booking-file errors', () => {
+    expect(source).toContain("listTruckAppointments({ oceanBookingId: normalizedId, page: 1, size: 20 })")
+    expect(source).toContain("new Set(['CANCELLED', 'EXCEPTION'])")
+    expect(source).toContain('该订舱已有拖车单')
+    expect(source).toContain("getApiErrorDetails(cause, '已有拖车预约查询失败，请稍后重试')")
+    expect(source).toContain('<ApiErrorMeta :details="existingLookupError" />')
+    expect(source).toContain("router.replace({ name: 'trucking-detail'")
+    expect(source).toContain('serial !== lookupSerial')
+  })
+
+  it('places lightweight return navigation beside the new appointment heading', () => {
+    expect(source).toContain('class="density-back"')
+    expect(source).toContain('<ArrowLeft :size="16" />返回列表')
+    expect(source).toContain('<template #header><header class="create-heading surface-panel">')
+    expect(source).not.toContain('class="editor-actions"')
+  })
+})
diff --git a/src/modules/trucking/pages/TruckAppointmentCreateView.vue b/src/modules/trucking/pages/TruckAppointmentCreateView.vue
new file mode 100644
index 00000000..ca95e276
--- /dev/null
+++ b/src/modules/trucking/pages/TruckAppointmentCreateView.vue
@@ -0,0 +1,80 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, reactive, ref, watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { ElMessage } from 'element-plus'
+import { ArrowLeft } from '@lucide/vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import DetailPageLayout from '@/shared/components/DetailPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import TruckAppointmentForm from '../components/TruckAppointmentForm.vue'
+import { createTruckAppointment, listTruckAppointments } from '../api/platformTrucking'
+import { truckAppointmentStatusLabel, type SaveTruckAppointmentRequest, type TruckAppointmentResource } from '../types'
+const route = useRoute(); const router = useRouter(); const saving = ref(false); const error = ref<ApiErrorDetails | null>(null)
+const initialOceanBookingId = String(route.query.oceanBookingId || '').trim()
+const form = reactive<SaveTruckAppointmentRequest>({ expectedVersion: 0, carrierId: null, oceanBookingId: initialOceanBookingId || null, plannedLoadingAt: null, payableAmount: '0.00', currency: 'RMB' })
+const existingAppointment = ref<TruckAppointmentResource | null>(null)
+const existingLookupLoading = ref(false)
+const existingLookupError = ref<ApiErrorDetails | null>(null)
+const checkedOceanBookingId = ref('')
+const navigatingToExisting = ref(false)
+let lookupSerial = 0
+const replaceableStatuses = new Set(['CANCELLED', 'EXCEPTION'])
+const existingCanEdit = computed(() => ['DRAFT', 'PENDING_DISPATCH', 'RESCHEDULED'].includes(existingAppointment.value?.status || ''))
+const submitBlocked = computed(() => existingLookupLoading.value || Boolean(existingLookupError.value) || Boolean(existingAppointment.value))
+function updateForm(value: SaveTruckAppointmentRequest) { Object.assign(form, value) }
+
+async function openExisting() {
+  if (!existingAppointment.value || navigatingToExisting.value) return
+  navigatingToExisting.value = true
+  try { await router.replace({ name: 'trucking-detail', params: { id: existingAppointment.value.id }, query: existingCanEdit.value ? { edit: '1' } : undefined }) }
+  finally { navigatingToExisting.value = false }
+}
+async function lookupExistingAppointment(oceanBookingId: string, autoNavigate = false) {
+  const normalizedId = oceanBookingId.trim()
+  const serial = ++lookupSerial
+  existingAppointment.value = null
+  existingLookupError.value = null
+  checkedOceanBookingId.value = ''
+  if (!normalizedId) { existingLookupLoading.value = false; return }
+  existingLookupLoading.value = true
+  try {
+    const result = await listTruckAppointments({ oceanBookingId: normalizedId, page: 1, size: 20 })
+    if (serial !== lookupSerial || String(form.oceanBookingId || '') !== normalizedId) return
+    checkedOceanBookingId.value = normalizedId
+    existingAppointment.value = result.records.find((item) => !replaceableStatuses.has(item.status)) || null
+    if (autoNavigate && existingAppointment.value) await openExisting()
+  } catch (cause) {
+    if (serial !== lookupSerial || String(form.oceanBookingId || '') !== normalizedId) return
+    checkedOceanBookingId.value = normalizedId
+    existingLookupError.value = getApiErrorDetails(cause, '已有拖车预约查询失败，请稍后重试')
+  } finally {
+    if (serial === lookupSerial) existingLookupLoading.value = false
+  }
+}
+async function submit() {
+  if (saving.value || existingLookupLoading.value) return
+  const oceanBookingId = String(form.oceanBookingId || '')
+  if (oceanBookingId && checkedOceanBookingId.value !== oceanBookingId) await lookupExistingAppointment(oceanBookingId)
+  if (String(form.oceanBookingId || '') !== oceanBookingId || existingLookupLoading.value || existingAppointment.value || existingLookupError.value) return
+  saving.value = true; error.value = null
+  try { await createTruckAppointment({ ...form }); ElMessage.success('拖车预约已创建'); router.push({ name: 'trucking' }) }
+  catch (err) { error.value = getApiErrorDetails(err, '创建失败，请稍后重试') }
+  finally { saving.value = false }
+}
+watch(() => form.oceanBookingId, (value) => { void lookupExistingAppointment(String(value || ''), Boolean(initialOceanBookingId && String(value || '') === initialOceanBookingId)) }, { immediate: true })
+defineExpose({ form, submit, lookupExistingAppointment, existingAppointment, existingLookupError, checkedOceanBookingId })
+</script>
+<template>
+  <AdminPage as="div" class="truck-editor-page admin-density">
+    <DetailPageLayout aria-label="新增拖车预约"><template #header><header class="create-heading surface-panel"><el-button link class="density-back" @click="router.push({ name: 'trucking' })"><ArrowLeft :size="16" />返回列表</el-button><h1>新增拖车预约</h1></header></template>
+      <LoadErrorState v-if="error" title="拖车预约创建失败" :message="error.message" :show-retry="false"><template #details><ApiErrorMeta :details="error" /></template></LoadErrorState>
+      <el-alert v-if="existingAppointment" type="warning" :closable="false" show-icon><template #title>该订舱已有拖车单 {{ existingAppointment.appointmentNo || '—' }}（{{ truckAppointmentStatusLabel(existingAppointment.status) }}）</template><el-button type="primary" link :loading="navigatingToExisting" @click="openExisting">{{ existingCanEdit ? '继续编辑' : '查看拖车单' }}</el-button></el-alert>
+      <LoadErrorState v-if="existingLookupError" title="已有拖车单查询失败" :message="existingLookupError.message" compact @retry="lookupExistingAppointment(String(form.oceanBookingId || ''))"><template #details><ApiErrorMeta :details="existingLookupError" /></template></LoadErrorState>
+      <section class="surface-panel form-panel"><TruckAppointmentForm :model-value="form" :submitting="saving" :submit-blocked="submitBlocked" @update:model-value="updateForm" @submit="submit"></TruckAppointmentForm></section>
+    </DetailPageLayout>
+  </AdminPage>
+</template>
+<style scoped>.truck-editor-page { min-width: 0; }.form-panel { padding:var(--admin-space-6); } @media (max-width:720px) { .form-panel { padding:16px; } } .create-heading{display:flex;align-items:center;gap:var(--admin-space-5);padding:var(--admin-space-3) var(--admin-space-5)} .create-heading h1{margin:0;font-size:var(--admin-font-title)}</style>
diff --git a/src/modules/trucking/pages/TruckAppointmentDetailView.test.ts b/src/modules/trucking/pages/TruckAppointmentDetailView.test.ts
new file mode 100644
index 00000000..c23645d0
--- /dev/null
+++ b/src/modules/trucking/pages/TruckAppointmentDetailView.test.ts
@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/trucking/pages/TruckAppointmentDetailView.vue'), 'utf8')
+
+describe('TruckAppointmentDetailView status contract', () => {
+  it('merges identity, status and relation snapshot into a compact overview', () => {
+    expect(source).toContain('class="truck-overview surface-panel"')
+    expect(source).toContain('class="truck-overview__heading"')
+    expect(source).toContain('class="truck-overview__identity"')
+    expect(source).toContain('class="truck-overview__status"')
+    expect(source).toContain('class="relation-snapshot"')
+    expect(source).toContain("const relationSnapshot = computed(() => resource.value ?")
+    expect(source).not.toContain('class="surface-panel status-panel"')
+    expect(source).not.toContain('class="status-bar"')
+    expect(source).not.toContain('class="detail-identity"')
+    expect(source).not.toContain('PageToolbar')
+  })
+
+  it('spaces independent form and history sections without nested overview cards', () => {
+    expect(source).toContain('.truck-detail-page :deep(.detail-page-layout__content) { display:grid; min-width:0; gap:var(--admin-space-5); }')
+    expect(source).toContain('.form-panel { padding:var(--admin-space-5); }')
+    expect(source).toContain('.history-section { padding:var(--admin-space-5); }')
+  })
+
+  it('uses domestic departure completion instead of manual departure and completion buttons', () => {
+    expect(source).not.toContain("LOADING: 'DEPARTED'")
+    expect(source).not.toContain("DEPARTED: 'COMPLETED'")
+    expect(source).toContain('订舱全部货柜确认国内离仓后，自动完成拖车并生成应付费用')
+  })
+
+  it('matches the backend edit lifecycle and avoids a self-transition action', () => {
+    expect(source).toContain('const targets: TruckAppointmentStatus[] =')
+    expect(source).not.toContain('const targets: string[] =')
+    expect(source).toContain("['DRAFT', 'PENDING_DISPATCH', 'RESCHEDULED'].includes(resource.value?.status || '')")
+    expect(source).toContain("status !== resource.value?.status")
+    expect(source).toContain("statuses.indexOf(status) === index")
+  })
+
+  it('initializes the required booking association explicitly', () => {
+    expect(source).toContain("carrierId: null, oceanBookingId: null, plannedLoadingAt: null")
+    expect(source).not.toContain('containerBookingId')
+    expect(source).not.toContain('customerId')
+    expect(source).toContain('TRUCK_APPOINTMENT_SAVE_FIELDS.map')
+    expect(source).toContain('normalizeTruckAppointmentCurrency(result.currency)')
+    expect(source).not.toContain('Object.assign(form, { ...result')
+    expect(source).toContain("error.value = getApiErrorDetails(err, '保存失败，请稍后重试')")
+  })
+
+  it('blocks dispatch until the released booking and frozen documents are present', () => {
+    expect(source).toContain("return '确认派车前必须关联已放舱订舱'")
+    expect(source).not.toContain('关联柜次')
+    expect(source).toContain("return '确认派车前所选订舱必须填写提单号'")
+    expect(source).toContain("return '确认派车前所选订舱必须上传有效的订舱确认文件或提单文件'")
+    expect(source).toContain('getOceanBooking(resource.value.oceanBookingId)')
+    expect(source).toContain("status === 'DISPATCHED' && dispatchBlockReason.value")
+    expect(source).not.toContain("item.attachmentType === 'BILL_OF_LADING'")
+  })
+
+  it('keeps pickup booking-scoped and leaves real container maintenance to container/preload flows', () => {
+    expect(source).not.toContain('ElMessageBox.prompt')
+    expect(source).not.toContain('normalizeIso6346ContainerNumber')
+    expect(source).toContain('performTruckAppointmentAction(id.value, action, { expectedVersion: form.expectedVersion || 0 })')
+    expect(source).toContain('await ElMessageBox.confirm(`确认将状态改为“${truckAppointmentStatusLabels[status]}”？`')
+  })
+
+  it('keeps the main detail available when attachments or history fail', () => {
+    expect(source).toContain('Promise.allSettled([')
+    expect(source).toContain("attachments.status === 'fulfilled'")
+    expect(source).toContain("histories.status === 'fulfilled'")
+    expect(source).toContain('主详情数据不受影响；派车时仍由服务端最终校验')
+    expect(source).toContain('v-if="relatedError"')
+  })
+
+  it('never exposes container identity or operator database ids', () => {
+    expect(source).not.toContain('cabinetNo')
+    expect(source).not.toContain('containerNo')
+    expect(source).not.toContain('containerBookingId')
+    expect(source).not.toContain('loadingPlanId')
+    expect(source).not.toContain('item.operatorId')
+  })
+
+  it('reloads a cached detail after an error without showing stale resource data', () => {
+    expect(source).toContain("resource.value = null; bookingReadiness.value = null; history.value = []; relatedError.value = ''")
+    expect(source).toContain('onActivated(() => {')
+    expect(source).toMatch(/if \(activatedOnce\) \{\s+void load\(\)/)
+  })
+})
diff --git a/src/modules/trucking/pages/TruckAppointmentDetailView.vue b/src/modules/trucking/pages/TruckAppointmentDetailView.vue
new file mode 100644
index 00000000..a4145deb
--- /dev/null
+++ b/src/modules/trucking/pages/TruckAppointmentDetailView.vue
@@ -0,0 +1,115 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onActivated, onMounted, reactive, ref } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import { ArrowLeft } from '@lucide/vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import DetailPageLayout from '@/shared/components/DetailPageLayout.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { getOceanBooking, type OceanBookingDetail } from '@/modules/ocean-bookings'
+import { getTruckAppointment, listTruckAppointmentAttachments, listTruckAppointmentHistory, performTruckAppointmentAction, rescheduleTruckAppointment, updateTruckAppointment, type TruckAppointmentAction } from '../api/platformTrucking'
+import TruckAppointmentForm from '../components/TruckAppointmentForm.vue'
+import TruckAttachmentDialog from '../components/TruckAttachmentDialog.vue'
+import { TRUCK_APPOINTMENT_SAVE_FIELDS, normalizeTruckAppointmentCurrency, truckAppointmentActionLabel, truckAppointmentStatusLabel, truckAppointmentStatusLabels, type SaveTruckAppointmentRequest, type TruckAppointmentResource, type TruckAppointmentStatus, type TruckAppointmentStatusHistory } from '../types'
+const route = useRoute(); const router = useRouter(); const loading = ref(false); const saving = ref(false); const statusSaving = ref(false); const attachmentOpen = ref(false); const resource = ref<TruckAppointmentResource | null>(null); const error = ref<ApiErrorDetails | null>(null); const form = reactive<SaveTruckAppointmentRequest>({ expectedVersion: 0, carrierId: null, oceanBookingId: null, plannedLoadingAt: null })
+const history = ref<TruckAppointmentStatusHistory[]>([])
+const bookingReadiness = ref<OceanBookingDetail | null>(null)
+const relatedError = ref('')
+let activatedOnce = false
+const access = useAccessPreviewStore(); const editing = computed(() => route.query.edit === '1'); const id = computed(() => String(route.params.id)); const canEdit = computed(() => access.can('platform:firstleg:truck-appointment:edit') && ['DRAFT', 'PENDING_DISPATCH', 'RESCHEDULED'].includes(resource.value?.status || '') && editing.value); const canChangeStatus = computed(() => access.can('platform:firstleg:truck-appointment:operate')); const canManageAttachments = computed(() => access.can('platform:firstleg:truck-appointment:edit'))
+const relationSnapshot = computed(() => resource.value ? [resource.value.oceanBookingNo, resource.value.billOfLadingNo, resource.value.warehouseName].filter(Boolean).join(' / ') || '无订舱关联' : '')
+async function loadRelated() {
+  if (!resource.value) return
+  relatedError.value = ''
+  const [attachments, histories, booking] = await Promise.allSettled([
+    listTruckAppointmentAttachments(id.value),
+    listTruckAppointmentHistory(id.value),
+    resource.value.oceanBookingId ? getOceanBooking(resource.value.oceanBookingId) : Promise.reject(new Error('拖车预约缺少订舱关联')),
+  ])
+  if (attachments.status === 'fulfilled') resource.value.attachments = attachments.value
+  if (histories.status === 'fulfilled') history.value = histories.value
+  if (booking.status === 'fulfilled') bookingReadiness.value = booking.value
+  if (attachments.status === 'rejected' || histories.status === 'rejected' || booking.status === 'rejected') relatedError.value = '附件、状态历史或订舱资料状态暂时未能加载，主详情数据不受影响；派车时仍由服务端最终校验。'
+}
+async function load() { loading.value = true; error.value = null; resource.value = null; bookingReadiness.value = null; history.value = []; relatedError.value = ''; try { const result = await getTruckAppointment(id.value); resource.value = result; const draft = Object.fromEntries(TRUCK_APPOINTMENT_SAVE_FIELDS.map((key) => [key, key === 'expectedVersion' ? result.version ?? 0 : key === 'currency' ? normalizeTruckAppointmentCurrency(result.currency) : result[key as keyof TruckAppointmentResource]])); Object.assign(form, draft); await loadRelated() } catch (err) { error.value = getApiErrorDetails(err, '详情加载失败，请稍后重试') } finally { loading.value = false } }
+async function submit() { if (saving.value) return; saving.value = true; error.value = null; try { await updateTruckAppointment(id.value, form); ElMessage.success('拖车预约已保存'); await load() } catch (err) { error.value = getApiErrorDetails(err, '保存失败，请稍后重试') } finally { saving.value = false } }
+const actionByTarget: Partial<Record<TruckAppointmentStatus, TruckAppointmentAction>> = { PENDING_DISPATCH: 'SUBMIT', DISPATCHED: 'DISPATCH', PICKUP_IN_PROGRESS: 'PICKUP', ARRIVED_WAREHOUSE: 'ARRIVE', LOADING: 'LOAD', EXCEPTION: 'EXCEPTION', CANCELLED: 'CANCEL' }
+const primaryTargetByStatus: Partial<Record<TruckAppointmentStatus, TruckAppointmentStatus>> = { DRAFT: 'PENDING_DISPATCH', PENDING_DISPATCH: 'DISPATCHED', RESCHEDULED: 'DISPATCHED', DISPATCHED: 'PICKUP_IN_PROGRESS', PICKUP_IN_PROGRESS: 'ARRIVED_WAREHOUSE', ARRIVED_WAREHOUSE: 'LOADING' }
+const availableTargets = computed<TruckAppointmentStatus[]>(() => {
+  if (!resource.value || ['COMPLETED', 'CANCELLED'].includes(resource.value.status)) return []
+  const primary = primaryTargetByStatus[resource.value.status]
+  const targets: TruckAppointmentStatus[] = [...(primary ? [primary] : []), 'RESCHEDULED', 'EXCEPTION', 'CANCELLED']
+  return targets
+    .filter((status, index, statuses) => status !== resource.value?.status && statuses.indexOf(status) === index)
+})
+const dispatchBlockReason = computed(() => {
+  if (!resource.value || !['PENDING_DISPATCH', 'RESCHEDULED'].includes(resource.value.status)) return ''
+  if (!form.oceanBookingId) return '确认派车前必须关联已放舱订舱'
+  if (bookingReadiness.value && bookingReadiness.value.status !== 'RELEASED') return '确认派车前必须关联已放舱订舱'
+  if (!form.billOfLadingNo?.trim()) return '确认派车前所选订舱必须填写提单号'
+  if (bookingReadiness.value && !bookingReadiness.value.documents.some((document) => document.valid && ['BOOKING_CONFIRMATION', 'BILL_OF_LADING'].includes(document.documentType))) return '确认派车前所选订舱必须上传有效的订舱确认文件或提单文件'
+  return ''
+})
+async function confirmStatusChange(status: TruckAppointmentStatus) {
+  await ElMessageBox.confirm(`确认将状态改为“${truckAppointmentStatusLabels[status]}”？`, '状态变更确认', { customClass: 'admin-density-confirm', confirmButtonText: '确认', cancelButtonText: '取消', type: 'warning' })
+}
+async function changeStatus(status: TruckAppointmentStatus) {
+  if (!resource.value || status === resource.value.status || statusSaving.value) return
+  if (status === 'DISPATCHED' && dispatchBlockReason.value) { error.value = { message: dispatchBlockReason.value }; return }
+  try { await confirmStatusChange(status); statusSaving.value = true; if (status === 'RESCHEDULED') { await rescheduleTruckAppointment(id.value, form.plannedLoadingAt || '', form.expectedVersion || 0, '后台改约') } else { const action = actionByTarget[status]; if (!action) throw new Error('当前状态没有可用动作'); await performTruckAppointmentAction(id.value, action, { expectedVersion: form.expectedVersion || 0 }) } ElMessage.success('状态已更新'); await load() } catch (err) { if (err !== 'cancel' && !(err instanceof Error && err.message === 'cancel')) error.value = getApiErrorDetails(err, '状态更新失败，请稍后重试') } finally { statusSaving.value = false }
+}
+onMounted(load)
+onActivated(() => {
+  if (activatedOnce) {
+    void load()
+    return
+  }
+  activatedOnce = true
+})
+</script>
+<template>
+  <AdminPage as="div" class="truck-detail-page admin-density">
+    <DetailPageLayout aria-label="拖车预约详情">
+      <template #header>
+        <section class="truck-overview surface-panel" aria-label="拖车预约概览">
+          <div class="truck-overview__heading">
+            <el-button link class="density-back" type="primary" @click="router.push({ name: 'trucking' })"><ArrowLeft :size="16" />返回列表</el-button>
+            <div class="truck-overview__identity"><h1>{{ resource?.appointmentNo || '拖车预约详情' }}</h1><p>{{ resource ? [resource.oceanBookingNo, resource.billOfLadingNo, resource.orderNo].filter(Boolean).join(' · ') || '订舱信息缺失' : '查看拖车预约详情' }}</p></div>
+            <span v-if="resource" class="truck-overview__status">当前状态：<strong>{{ truckAppointmentStatusLabel(resource.status) }}</strong></span>
+            <div v-if="resource && canChangeStatus" class="status-actions"><el-button v-for="status in availableTargets" :key="status" size="small" :type="status === 'CANCELLED' ? 'danger' : status === 'EXCEPTION' ? 'warning' : 'primary'" plain :loading="statusSaving" @click="changeStatus(status)">{{ truckAppointmentStatusLabels[status] }}</el-button></div>
+          </div>
+          <template v-if="resource">
+            <p class="relation-snapshot"><strong>历史关联快照：</strong>{{ relationSnapshot }} · 订舱全部货柜确认国内离仓后，自动完成拖车并生成应付费用。</p>
+            <el-alert v-if="dispatchBlockReason" :title="dispatchBlockReason" type="warning" :closable="false" show-icon />
+            <el-alert v-if="relatedError" :title="relatedError" type="warning" :closable="false" show-icon />
+            <ApiErrorMeta v-if="error" :details="error" />
+          </template>
+        </section>
+      </template>
+      <LoadErrorState v-if="error && !resource" title="详情加载失败" :message="error.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="error" /></template></LoadErrorState>
+      <template v-else-if="resource">
+        <section class="surface-panel form-panel"><TruckAppointmentForm v-model="form" :resource="resource" :readonly="!canEdit" :submitting="saving" @submit="submit" @attachments="attachmentOpen = true" /></section>
+        <section class="surface-panel history-section"><h3>状态历史</h3><table class="density-table truck-history-table"><thead><tr><th>时间</th><th>事件</th><th>状态变化</th><th>操作人</th><th>备注</th></tr></thead><tbody><tr v-for="(item, index) in history" :key="item.id || `${item.createdAt}-${index}`"><td>{{ item.createdAt || item.occurredAt || '—' }}</td><td>{{ truckAppointmentActionLabel(item.action) }}</td><td>{{ truckAppointmentStatusLabel(item.fromStatus) }} → {{ truckAppointmentStatusLabel(item.toStatus) }}</td><td>{{ item.operatorName || '系统' }}</td><td>{{ item.reason || '—' }}</td></tr><tr v-if="!history.length"><td colspan="5">暂无状态历史</td></tr></tbody></table></section>
+        <TruckAttachmentDialog v-model="attachmentOpen" :appointment-id="id" :attachments="resource.attachments || []" :can-manage="canManageAttachments" @changed="loadRelated" />
+      </template>
+    </DetailPageLayout>
+  </AdminPage>
+</template>
+<style scoped>
+.truck-overview { overflow:hidden; }
+.truck-overview__heading { display:grid; grid-template-columns:auto minmax(260px, 1fr) auto auto; align-items:center; gap:var(--admin-space-5) var(--admin-space-6); padding:var(--admin-space-5) var(--admin-space-5); }
+.truck-overview__identity { min-width:0; }.truck-overview__identity h1 { margin:0; color:var(--cc-text); font-size:var(--admin-font-title); line-height:1.35; white-space:normal; overflow-wrap:anywhere; }.truck-overview__identity p { margin:2px 0 0; color:var(--cc-muted); font-size:var(--admin-font-caption); white-space:normal; overflow-wrap:anywhere; }
+.truck-overview__status { font-size:var(--admin-font-body); white-space:nowrap; }.truck-overview__status strong { margin-left:var(--admin-space-1); font-size:var(--admin-font-section); }
+.status-actions { display:flex; flex-wrap:wrap; gap:var(--admin-space-3); }.status-actions :deep(.el-button) { margin-left:0; }
+.relation-snapshot { margin:0; padding:9px var(--admin-space-5); border-top:1px solid var(--cc-border); color:var(--cc-muted); font-size:var(--admin-font-caption); line-height:1.5; }.relation-snapshot strong { margin-right:var(--admin-space-1); color:var(--cc-text); }
+.truck-detail-page { min-width:0; }.truck-detail-page :deep(.detail-page-layout__content) { display:grid; min-width:0; gap:var(--admin-space-5); }.form-panel { padding:var(--admin-space-5); }.history-section { padding:var(--admin-space-5); }.history-section h3 { margin:0 0 var(--admin-space-5); font-size:var(--admin-font-section); }
+@media (max-width: 640px) { .history-section { padding:16px; } }
+.truck-history-table th:nth-child(1){width:180px}
+.truck-history-table th:nth-child(2){width:130px}
+.truck-history-table th:nth-child(3){width:240px}
+.truck-history-table th:nth-child(4){width:130px}
+</style>
diff --git a/src/modules/trucking/pages/TruckAppointmentsView.test.ts b/src/modules/trucking/pages/TruckAppointmentsView.test.ts
new file mode 100644
index 00000000..24ecb2a8
--- /dev/null
+++ b/src/modules/trucking/pages/TruckAppointmentsView.test.ts
@@ -0,0 +1,202 @@
+import ElementPlus from 'element-plus'
+import { createPinia, setActivePinia } from 'pinia'
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { ApiResponseError } from '@/shared/api/http'
+import TruckAppointmentsView from './TruckAppointmentsView.vue'
+import { listTruckAppointments } from '../api/platformTrucking'
+import type { TruckAppointmentResource } from '../types'
+import { useAuthStore } from '@/core/auth/auth'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/trucking/pages/TruckAppointmentsView.vue'), 'utf8')
+
+vi.mock('../api/platformTrucking', () => ({
+  listTruckAppointments: vi.fn(),
+}))
+vi.mock('@/modules/iam', () => ({
+  listPlatformTenants: vi.fn().mockResolvedValue({ records: [], page: 1, size: 200, total: 0, pages: 0 }),
+}))
+
+const row: TruckAppointmentResource = {
+  id: '9001', appointmentNo: 'TA-9001', status: 'DISPATCHED', orderNo: 'ORD-1', oceanBookingNo: 'OB-1', billOfLadingNo: 'BL-1',
+  warehouseName: '义乌仓', shippingCompanyName: '船公司A', bookingAgentName: '代理A', carrierName: '宁波运输', driverName: '王强', vehicleNo: '浙B12345',
+  plannedLoadingAt: '2026-08-10T10:00:00', payableAmount: '3200.00', currency: 'RMB', attachmentCount: 2, attachments: [],
+}
+
+describe('TruckAppointmentsView', () => {
+  beforeEach(() => {
+    vi.mocked(listTruckAppointments).mockReset().mockResolvedValue({ records: [row], page: 1, size: 20, total: 1, pages: 1 })
+    setActivePinia(createPinia())
+    useAuthStore().permissions = [
+      'platform:firstleg:truck-appointment:view',
+      'platform:firstleg:truck-appointment:edit',
+    ]
+  })
+
+  it('loads the real list and renders relationship snapshots', async () => {
+    const wrapper = mount(TruckAppointmentsView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(listTruckAppointments).toHaveBeenCalledWith({ page: 1, size: 20, keyword: '', status: '' })
+    expect(wrapper.text()).toContain('TA-9001')
+    expect(wrapper.text()).toContain('OB-1')
+    expect(wrapper.text()).toContain('BL-1')
+    expect(wrapper.text()).toContain('义乌仓')
+    expect(wrapper.text()).toContain('船公司A')
+    expect(wrapper.text()).toContain('代理A')
+    expect(wrapper.text()).toContain('宁波运输')
+    expect(wrapper.find('button[aria-label="查看 TA-9001"]').exists()).toBe(true)
+  })
+
+  it('uses stable accessible labels when appointment identifiers are missing', async () => {
+    vi.mocked(listTruckAppointments).mockResolvedValue({
+      records: [
+        { ...row, id: '9002', appointmentNo: '' },
+        { ...row, id: undefined, appointmentNo: null } as unknown as TruckAppointmentResource,
+      ],
+      page: 1,
+      size: 20,
+      total: 2,
+      pages: 1,
+    })
+    const wrapper = mount(TruckAppointmentsView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+
+    expect(wrapper.find('button[aria-label="查看拖车预约详情"]').exists()).toBe(true)
+    const labels = wrapper.findAll('button[aria-label]').map((button) => button.attributes('aria-label'))
+    expect(labels.every((label) => Boolean(label) && !/undefined|null/.test(label ?? ''))).toBe(true)
+    expect(labels.every((label) => !label?.includes('9002'))).toBe(true)
+    expect(source).toContain("appointmentActionLabel('编辑', row as TruckAppointmentResource)")
+  })
+
+  it('does not expose a technical carrier id when the business name is unavailable', async () => {
+    vi.mocked(listTruckAppointments).mockResolvedValue({
+      records: [{ ...row, carrierName: '', carrierId: 'carrier-77' }],
+      page: 1,
+      size: 20,
+      total: 1,
+      pages: 1,
+    })
+    const wrapper = mount(TruckAppointmentsView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(wrapper.text()).toContain('已关联承运商')
+    expect(wrapper.text()).not.toContain('carrier-77')
+  })
+
+  it('uses the table toolbar for create and keeps a single empty state', () => {
+    expect(source).toContain('<template #toolbar-actions>')
+    expect(source).not.toContain('<template #toolbar-start>')
+    expect(source).not.toContain('PageToolbar')
+    expect(source).not.toContain('empty-hint')
+    expect(source.match(/empty-text=/g)).toHaveLength(1)
+  })
+
+  it('renders the server empty state', async () => {
+    vi.mocked(listTruckAppointments).mockResolvedValue({ records: [], page: 1, size: 20, total: 0, pages: 1 })
+    const wrapper = mount(TruckAppointmentsView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(wrapper.text()).toContain('暂无符合筛选条件的拖车预约')
+  })
+
+  it('marks the table busy while the list request is pending', async () => {
+    let resolveLoad!: (value: Awaited<ReturnType<typeof listTruckAppointments>>) => void
+    vi.mocked(listTruckAppointments).mockImplementationOnce(() => new Promise((resolve) => { resolveLoad = resolve }))
+    const wrapper = mount(TruckAppointmentsView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(wrapper.find('section[aria-busy="true"]').exists()).toBe(true)
+    resolveLoad({ records: [row], page: 1, size: 20, total: 1, pages: 1 })
+    await flushPromises()
+    expect(wrapper.find('section[aria-busy="false"]').exists()).toBe(true)
+  })
+
+  it('keeps a recoverable load error and retries without losing the page', async () => {
+    vi.mocked(listTruckAppointments).mockRejectedValueOnce(new ApiResponseError('候选服务暂不可用', 'A0503', 503, undefined, 'req-truck', 'trace-truck'))
+    const wrapper = mount(TruckAppointmentsView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(wrapper.text()).toContain('候选服务暂不可用')
+    expect(wrapper.text()).toContain('req-truck')
+    vi.mocked(listTruckAppointments).mockResolvedValueOnce({ records: [row], page: 1, size: 20, total: 1, pages: 1 })
+    await wrapper.get('button').trigger('click')
+    await flushPromises()
+    expect(listTruckAppointments).toHaveBeenCalledTimes(2)
+    expect(wrapper.text()).toContain('TA-9001')
+  })
+
+  it('shows create only with the independent create permission', async () => {
+    let wrapper = mount(TruckAppointmentsView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(wrapper.text()).not.toContain('新增拖车')
+    wrapper.unmount()
+    useAuthStore().permissions = ['platform:firstleg:truck-appointment:list', 'platform:firstleg:truck-appointment:create']
+    wrapper = mount(TruckAppointmentsView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(wrapper.text()).toContain('新增拖车')
+  })
+
+  it('shows the two frequent row actions directly without a more menu', () => {
+    expect(source).toContain("{ key: 'actions', label: '操作', width: 180, fixed: 'left', slotName: 'actions', hideable: false, movable: false }")
+    expect(source).toContain('flex-wrap:nowrap')
+    expect(source).toContain('white-space:nowrap')
+    expect(source).toContain('flex:0 0 auto')
+    expect(source).not.toContain('platform:firstleg:truck-appointment:view')
+    expect(source).toContain("access.can('platform:firstleg:truck-appointment:edit') && ['DRAFT', 'PENDING_DISPATCH', 'RESCHEDULED'].includes(row.status)")
+    expect(source).toContain('@click="openDetail(row as TruckAppointmentResource)">详情</el-button>')
+    expect(source).toContain('编辑</el-button>')
+    expect(source).not.toContain('MoreHorizontal')
+  })
+
+  it('hides edit for completed appointments rejected by the backend edit contract', async () => {
+    vi.mocked(listTruckAppointments).mockResolvedValue({
+      records: [{ ...row, status: 'COMPLETED' }],
+      page: 1,
+      size: 20,
+      total: 1,
+      pages: 1,
+    })
+    const wrapper = mount(TruckAppointmentsView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(wrapper.find('button[aria-label="编辑 TA-9001"]').exists()).toBe(false)
+  })
+
+  it('shows the detail action with the list permission', async () => {
+    useAuthStore().permissions = ['platform:firstleg:truck-appointment:list']
+    const wrapper = mount(TruckAppointmentsView, { global: { plugins: [ElementPlus] } })
+    await flushPromises()
+    expect(wrapper.find('button[aria-label="查看 TA-9001"]').exists()).toBe(true)
+  })
+
+  it('shows the prototype-backed trucking fee snapshots in the list', () => {
+    expect(source).not.toContain("key: 'customerName'")
+    expect(source).toContain("key: 'updatedAt'")
+    expect(source).toContain("key: 'payableAmount', label: '应付拖车费'")
+    expect(source.indexOf("key: 'store'")).toBeLessThan(source.indexOf("key: 'payableAmount'"))
+    expect(source.indexOf("key: 'payableAmount'")).toBeLessThan(source.indexOf("key: 'plannedLoadingAt'"))
+    expect(source).not.toContain('receivableAmount')
+    expect(source).not.toContain('应收拖车费')
+    expect(source).not.toContain("key: 'containerNo'")
+    expect(source).not.toContain("key: 'cabinetNo'")
+    expect(source).toContain("toLocaleString('zh-CN', { minimumFractionDigits: 2, maximumFractionDigits: 2 })")
+    expect(source).toContain("key: 'attachmentCount'")
+  })
+  it('does not expose customer filtering or snapshots', () => {
+    expect(source).not.toContain('listPlatformTenants')
+    expect(source).not.toContain("key: 'customerId'")
+    expect(source).not.toContain("label: '客户'")
+    expect(source).not.toContain('customerId:')
+    expect(source).not.toContain('customerName')
+  })
+  it('uses bordered list actions instead of text links', () => {
+    expect(source).toContain('size="small" type="primary" plain')
+    expect(source).toContain('size="small" :aria-label="appointmentActionLabel(\'编辑\'')
+    expect(source).not.toContain("truck-appointment:view')\" link")
+    expect(source).toContain(':total="total" stripe preference-key="trucking-appointments"')
+  })
+
+  it('uses unified container types and a wider composite keyword field', () => {
+    expect(source).toContain("key: 'keyword', type: 'input', label: '关键词', placeholder: '派车单号、车牌号、运输公司', width: 280")
+    expect(source).toContain("key: 'status', type: 'select', label: '状态', placeholder: '全部状态', width: 160")
+    expect(source).toContain("key: 'containerType', type: 'select', label: '柜型', placeholder: '全部柜型', width: 160")
+    expect(source).toContain('CONTAINER_SPECIFICATIONS.map')
+  })
+})
diff --git a/src/modules/trucking/pages/TruckAppointmentsView.vue b/src/modules/trucking/pages/TruckAppointmentsView.vue
new file mode 100644
index 00000000..c15c7865
--- /dev/null
+++ b/src/modules/trucking/pages/TruckAppointmentsView.vue
@@ -0,0 +1,87 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, ref } from 'vue'
+import { useRouter } from 'vue-router'
+import { Plus } from '@lucide/vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { CONTAINER_SPECIFICATIONS } from '@/shared/domain/containerSpecifications'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { listTruckAppointments } from '../api/platformTrucking'
+import { TRUCK_APPOINTMENT_STATUSES, truckAppointmentStatusLabel, truckAppointmentStatusLabels, type TruckAppointmentQuery, type TruckAppointmentResource, type TruckAppointmentStatus } from '../types'
+
+const router = useRouter(); const rows = ref<TruckAppointmentResource[]>([]); const loading = ref(false); const page = ref(1); const pageSize = ref(20); const total = ref(0); const loadError = ref<ApiErrorDetails | null>(null)
+const access = useAccessPreviewStore()
+const filters = ref({ keyword: '', status: '' as TruckAppointmentStatus | '' }); const applied = ref({ ...filters.value })
+const fields = computed<QueryField[]>(() => [
+  { key: 'keyword', type: 'input', label: '关键词', placeholder: '派车单号、车牌号、运输公司', width: 280 },
+  { key: 'status', type: 'select', label: '状态', placeholder: '全部状态', width: 160, options: TRUCK_APPOINTMENT_STATUSES.map((value) => ({ value, label: truckAppointmentStatusLabels[value] })) },
+  { key: 'containerType', type: 'select', label: '柜型', placeholder: '全部柜型', width: 160, options: CONTAINER_SPECIFICATIONS.map(({ type }) => ({ value: type, label: type })) },
+])
+const columns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 180, fixed: 'left', slotName: 'actions', hideable: false, movable: false },
+  { key: 'appointmentNo', prop: 'appointmentNo', label: '派车单号', minWidth: 170 },
+  { key: 'oceanBookingNo', prop: 'oceanBookingNo', label: '订舱号', minWidth: 150, formatter: (row: TruckAppointmentResource) => row.oceanBookingNo || '—' },
+  { key: 'billOfLadingNo', prop: 'billOfLadingNo', label: '提单号', minWidth: 160, formatter: (row: TruckAppointmentResource) => row.billOfLadingNo || '—' },
+  { key: 'warehouseName', prop: 'warehouseName', label: '装柜仓库', minWidth: 150, formatter: (row: TruckAppointmentResource) => row.warehouseName || '—' },
+  { key: 'shippingCompanyName', prop: 'shippingCompanyName', label: '船公司', minWidth: 150, formatter: (row: TruckAppointmentResource) => row.shippingCompanyName || '—' },
+  { key: 'bookingAgentName', prop: 'bookingAgentName', label: '订舱代理', minWidth: 150, formatter: (row: TruckAppointmentResource) => row.bookingAgentName || '—' },
+  { key: 'company', label: '运输公司', minWidth: 160, slotName: 'company' },
+  { key: 'driver', label: '司机', minWidth: 130, slotName: 'driver' },
+  { key: 'vehicleNo', prop: 'vehicleNo', label: '车头号', minWidth: 120, formatter: (row: TruckAppointmentResource) => row.vehicleNo || '—' },
+  { key: 'store', label: '门店', minWidth: 140, slotName: 'store' },
+  { key: 'payableAmount', label: '应付拖车费', minWidth: 130, align: 'right', formatter: (row: TruckAppointmentResource) => formatAmount(row.payableAmount, row.currency) },
+  { key: 'plannedLoadingAt', label: '预计装箱日期', minWidth: 170, formatter: (row: TruckAppointmentResource) => formatDateTime(row.plannedLoadingAt) },
+  { key: 'status', label: '状态', width: 130, slotName: 'status' },
+  { key: 'attachmentCount', label: '附件', width: 90, align: 'right', formatter: (row: TruckAppointmentResource) => String(Number(row.attachmentCount ?? 0)) },
+  { key: 'updatedAt', label: '更新时间', minWidth: 160, formatter: (row: TruckAppointmentResource) => formatDateTime(row.updatedAt) },
+]
+function formatDateTime(value?: string | null) { return value ? value.replace('T', ' ').slice(0, 16) : '—' }
+function formatAmount(value?: string | null, currency?: string | null) {
+  if (value == null || value === '') return '—'
+  const amount = Number(value)
+  const display = Number.isFinite(amount) ? amount.toLocaleString('zh-CN', { minimumFractionDigits: 2, maximumFractionDigits: 2 }) : value
+  return currency ? `${display} ${currency}` : display
+}
+function appointmentActionLabel(action: '查看' | '编辑', row: TruckAppointmentResource) {
+  const identifier = String(row.appointmentNo ?? '').trim()
+  return identifier ? `${action} ${identifier}` : `${action}拖车预约详情`
+}
+function statusLabel(value: unknown) {
+  return truckAppointmentStatusLabel(typeof value === 'string' ? value : null)
+}
+async function load() { loading.value = true; loadError.value = null; try { const result = await listTruckAppointments({ page: page.value, size: pageSize.value, ...applied.value } as TruckAppointmentQuery); rows.value = result.records; total.value = result.total } catch (error) { rows.value = []; total.value = 0; loadError.value = getApiErrorDetails(error, '拖车预约加载失败，请稍后重试') } finally { loading.value = false } }
+function search(model: QueryModel) { applied.value = { keyword: String(model.keyword || ''), status: (model.status || '') as TruckAppointmentStatus | '' }; if (page.value === 1) void load(); else page.value = 1 }
+onMounted(() => { void load() })
+function openDetail(row: TruckAppointmentResource, edit = false) { router.push({ name: 'trucking-detail', params: { id: String(row.id) }, query: edit ? { edit: '1' } : undefined }) }
+</script>
+<template>
+  <AdminPage as="div" class="trucking-page admin-density">
+    <ListPageLayout aria-label="拖车预约列表">
+      <template #toolbar><QueryToolbar v-model="filters" class="surface-panel" ariaLabel="拖车预约查询" :fields="fields" preference-key="trucking-query" @search="search" /></template>
+      <template v-if="loadError" #state><LoadErrorState title="拖车预约列表暂时无法加载" :message="loadError.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="loadError" /></template></LoadErrorState></template>
+      <section v-if="!loadError" class="surface-panel table-panel" :aria-busy="loading">
+    <DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :loading="loading" :total="total" stripe preference-key="trucking-appointments" aria-label="拖车预约列表" empty-text="暂无符合筛选条件的拖车预约">
+      <template #toolbar-actions><el-button v-if="access.can('platform:firstleg:truck-appointment:create')" type="primary" :disabled="loading" @click="router.push({ name: 'trucking-new' })"><Plus :size="16" />新增拖车</el-button></template>
+      <template #company="{ row }">{{ row.carrierName || (row.carrierId ? '已关联承运商' : '—') }}</template>
+      <template #driver="{ row }">{{ row.driverName || '—' }}<small>{{ row.driverPhone || '—' }}</small></template>
+      <template #store="{ row }">{{ row.storeName || '—' }}</template>
+      <template #status="{ row }"><StatusBadge :status="statusLabel(row.status)" /></template>
+      <template #actions="{ row }"><div class="table-actions density-actions"><el-button class="density-action" size="small" type="primary" plain :aria-label="appointmentActionLabel('查看', row as TruckAppointmentResource)" @click="openDetail(row as TruckAppointmentResource)">详情</el-button><el-button class="density-action" v-if="access.can('platform:firstleg:truck-appointment:edit') && ['DRAFT', 'PENDING_DISPATCH', 'RESCHEDULED'].includes(row.status)" size="small" :aria-label="appointmentActionLabel('编辑', row as TruckAppointmentResource)" @click="openDetail(row as TruckAppointmentResource, true)">编辑</el-button></div></template>
+    </DataTable>
+      </section>
+    </ListPageLayout>
+  </AdminPage>
+</template>
+<style scoped>
+.trucking-page { min-width: 0; }
+.table-panel { overflow:hidden; }
+small { display:block; color:var(--el-text-color-secondary); margin-top:3px; }
+.table-actions { flex-wrap:nowrap; white-space:nowrap; }.table-actions :deep(.el-button) { flex:0 0 auto; margin-left:0; }
+</style>
diff --git a/src/modules/trucking/routes.ts b/src/modules/trucking/routes.ts
new file mode 100644
index 00000000..d1ba74ed
--- /dev/null
+++ b/src/modules/trucking/routes.ts
@@ -0,0 +1,23 @@
+import type { RouteRecordRaw } from 'vue-router'
+
+export const truckingRoutes = [
+  {
+    path: 'trucking',
+    name: 'trucking',
+    component: () => import('./pages/TruckAppointmentsView.vue'),
+    meta: { title: '拖车预约', description: '维护拖车预约及派车状态', permission: 'platform:firstleg:truck-appointment:list' },
+  },
+  {
+    path: 'trucking/new',
+    name: 'trucking-new',
+    component: () => import('./pages/TruckAppointmentCreateView.vue'),
+    meta: { title: '新增拖车预约', description: '创建拖车预约', permission: 'platform:firstleg:truck-appointment:create' },
+  },
+  {
+    path: 'trucking/:id',
+    name: 'trucking-detail',
+    component: () => import('./pages/TruckAppointmentDetailView.vue'),
+    props: true,
+    meta: { title: '拖车预约详情', description: '查看和编辑拖车预约', permission: 'platform:firstleg:truck-appointment:list' },
+  },
+] satisfies RouteRecordRaw[]
diff --git a/src/modules/trucking/status.test.ts b/src/modules/trucking/status.test.ts
new file mode 100644
index 00000000..2e23165a
--- /dev/null
+++ b/src/modules/trucking/status.test.ts
@@ -0,0 +1,11 @@
+import { describe, expect, it } from 'vitest'
+import { truckAppointmentActionLabel, truckAppointmentStatusLabel } from './types'
+
+describe('truck appointment status labels', () => {
+  it('translates status history without exposing backend enum values', () => {
+    expect(truckAppointmentStatusLabel('DISPATCHED')).toBe('已派车')
+    expect(truckAppointmentStatusLabel('NEW_STATUS')).toBe('未知状态')
+    expect(truckAppointmentActionLabel('DISPATCH')).toBe('确认派车')
+    expect(truckAppointmentActionLabel('NEW_ACTION')).toBe('状态更新')
+  })
+})
diff --git a/src/modules/trucking/types.ts b/src/modules/trucking/types.ts
new file mode 100644
index 00000000..b7ab370c
--- /dev/null
+++ b/src/modules/trucking/types.ts
@@ -0,0 +1,226 @@
+export const TRUCK_APPOINTMENT_STATUSES = [
+  'DRAFT',
+  'PENDING_DISPATCH',
+  'DISPATCHED',
+  'PICKUP_IN_PROGRESS',
+  'ARRIVED_WAREHOUSE',
+  'LOADING',
+  'COMPLETED',
+  'RESCHEDULED',
+  'EXCEPTION',
+  'CANCELLED',
+] as const
+
+export type TruckAppointmentStatus = typeof TRUCK_APPOINTMENT_STATUSES[number]
+
+export const truckAppointmentStatusLabels: Record<TruckAppointmentStatus, string> = {
+  DRAFT: '草稿',
+  PENDING_DISPATCH: '待派车',
+  DISPATCHED: '已派车',
+  PICKUP_IN_PROGRESS: '提柜中',
+  ARRIVED_WAREHOUSE: '已到仓',
+  LOADING: '装柜中',
+  COMPLETED: '已完成',
+  RESCHEDULED: '已改期',
+  EXCEPTION: '异常',
+  CANCELLED: '已取消',
+}
+
+export function truckAppointmentStatusLabel(status: string | null | undefined, emptyLabel = '—') {
+  if (!status) return emptyLabel
+  return truckAppointmentStatusLabels[status as TruckAppointmentStatus] || '未知状态'
+}
+
+export const truckAppointmentActionLabels: Record<string, string> = {
+  CREATE: '创建预约',
+  SUBMIT: '提交派车',
+  DISPATCH: '确认派车',
+  PICKUP: '开始提柜',
+  ARRIVE: '到达仓库',
+  LOAD: '开始装柜',
+  AUTO_COMPLETE: '国内离仓自动完成',
+  RESCHEDULE: '预约改期',
+  EXCEPTION: '标记异常',
+  CANCEL: '取消预约',
+}
+
+export function truckAppointmentActionLabel(action: string | null | undefined) {
+  if (!action) return '状态更新'
+  return truckAppointmentActionLabels[action] || '状态更新'
+}
+
+export const TRUCK_ATTACHMENT_TYPES = ['DISPATCH_ORDER', 'DRIVER_DOCUMENT', 'VEHICLE_DOCUMENT', 'OTHER'] as const
+export type TruckAttachmentType = typeof TRUCK_ATTACHMENT_TYPES[number]
+export function isTruckAttachmentType(value: unknown): value is TruckAttachmentType {
+  return TRUCK_ATTACHMENT_TYPES.includes(value as TruckAttachmentType)
+}
+export const TRUCK_APPOINTMENT_CURRENCIES = ['RMB'] as const
+export type TruckAppointmentCurrency = typeof TRUCK_APPOINTMENT_CURRENCIES[number]
+export function normalizeTruckAppointmentCurrency(value: unknown): TruckAppointmentCurrency {
+  const normalized = String(value ?? '').trim().toUpperCase()
+  return TRUCK_APPOINTMENT_CURRENCIES.includes(normalized as TruckAppointmentCurrency) ? normalized as TruckAppointmentCurrency : 'RMB'
+}
+
+export interface TruckAttachmentReference {
+  id?: string
+  fileId: string
+  fileName: string
+  attachmentType?: TruckAttachmentType | null
+  fileHash?: string | null
+  visibility?: string | null
+  uploadedBy?: string | null
+  uploadedAt?: string | null
+  objectKey?: string | null
+}
+
+export interface TruckAppointmentStatusHistory {
+  id?: string
+  revision?: number | null
+  action: string
+  fromStatus?: TruckAppointmentStatus | string | null
+  toStatus: TruckAppointmentStatus | string | null
+  reason?: string | null
+  operatorId?: string | null
+  operatorName?: string | null
+  requestId?: string | null
+  createdAt?: string | null
+  occurredAt?: string | null
+}
+
+export interface TruckAppointmentResource {
+  id: string
+  appointmentNo?: string | null
+  status: TruckAppointmentStatus
+  version?: number | null
+  revision?: number | null
+  outboundOrderId?: string | null
+  oceanBookingId?: string | null
+  oceanBookingNo?: string | null
+  warehouseId?: string | null
+  warehouseName?: string | null
+  shippingCompanyId?: string | null
+  shippingCompanyName?: string | null
+  bookingAgentId?: string | null
+  bookingAgentName?: string | null
+  carrierId?: string | null
+  carrierName?: string | null
+  billOfLadingNo?: string | null
+  fleetContact?: string | null
+  fleetPhone?: string | null
+  driverName?: string | null
+  driverPhone?: string | null
+  driverIdCard?: string | null
+  vehicleNo?: string | null
+  storeName?: string | null
+  storeContact?: string | null
+  storePhone?: string | null
+  storeAddress?: string | null
+  storeCity?: string | null
+  storeZipcode?: string | null
+  plannedLoadingAt?: string | null
+  actualLoadingAt?: string | null
+  transitMinutes?: number | string | null
+  packageCount?: number | string | null
+  grossWeightKg?: string | null
+  volumeCbm?: string | null
+  palletCount?: number | string | null
+  payableAmount?: string | null
+  currency?: TruckAppointmentCurrency | null
+  poNo?: string | null
+  remark?: string | null
+  orderId?: string | null
+  orderNo?: string | null
+  entrustingPartyName?: string | null
+  attachments?: TruckAttachmentReference[] | null
+  attachmentCount?: number | string | null
+  statusHistory?: TruckAppointmentStatusHistory[] | null
+  createdAt?: string | null
+  updatedAt?: string | null
+}
+
+export interface SaveTruckAppointmentRequest {
+  outboundOrderId?: string | null
+  oceanBookingId: string | null
+  warehouseId?: string | null
+  carrierId: string | null
+  carrierName?: string | null
+  billOfLadingNo?: string | null
+  fleetContact?: string | null
+  fleetPhone?: string | null
+  driverName?: string | null
+  driverPhone?: string | null
+  driverIdCard?: string | null
+  vehicleNo?: string | null
+  storeName?: string | null
+  storeContact?: string | null
+  storePhone?: string | null
+  storeAddress?: string | null
+  storeCity?: string | null
+  storeZipcode?: string | null
+  plannedLoadingAt: string | null
+  transitMinutes?: number | string | null
+  packageCount?: number | string | null
+  grossWeightKg?: string | null
+  volumeCbm?: string | null
+  palletCount?: number | string | null
+  payableAmount?: string | null
+  currency?: TruckAppointmentCurrency | null
+  poNo?: string | null
+  remark?: string | null
+  expectedVersion: number
+}
+
+export const TRUCK_APPOINTMENT_SAVE_FIELDS = [
+  'outboundOrderId', 'oceanBookingId', 'warehouseId',
+  'carrierId', 'carrierName', 'billOfLadingNo', 'fleetContact', 'fleetPhone', 'driverName',
+  'driverPhone', 'driverIdCard', 'vehicleNo', 'storeName', 'storeContact', 'storePhone',
+  'storeAddress', 'storeCity', 'storeZipcode', 'plannedLoadingAt', 'transitMinutes', 'packageCount',
+  'grossWeightKg', 'volumeCbm', 'palletCount', 'payableAmount', 'currency',
+  'poNo', 'remark', 'expectedVersion',
+] as const satisfies readonly (keyof SaveTruckAppointmentRequest)[]
+
+export interface TruckAppointmentQuery {
+  page?: number
+  size?: number
+  keyword?: string
+  status?: TruckAppointmentStatus | ''
+  oceanBookingId?: string | ''
+}
+
+export interface TruckAppointmentCandidateQuery {
+  page?: number
+  size?: number
+  keyword?: string
+}
+
+export interface TruckAppointmentCandidate {
+  oceanBookingId: string
+  oceanBookingNo: string
+  billOfLadingNo: string | null
+  warehouseId: string
+  warehouseName: string | null
+  channelCode: string | null
+  channelName: string | null
+  bookingDocumentReady: boolean
+}
+
+export interface TruckAppointmentCandidatePage {
+  records: TruckAppointmentCandidate[]
+  page: number
+  size: number
+  total: number
+  pages: number
+}
+
+export interface TruckAppointmentActionRequest {
+  expectedVersion: number
+  reason?: string | null
+}
+
+export interface TruckAppointmentPage {
+  records: TruckAppointmentResource[]
+  page: number
+  size: number
+  total: number
+  pages: number
+}
diff --git a/src/modules/unified-orders/api/coLoadGroups.test.ts b/src/modules/unified-orders/api/coLoadGroups.test.ts
new file mode 100644
index 00000000..23242413
--- /dev/null
+++ b/src/modules/unified-orders/api/coLoadGroups.test.ts
@@ -0,0 +1,61 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import { cancelPlatformCoLoadGroup, createPlatformCoLoadGroup, getPlatformCoLoadGroupByInboundCode } from './coLoadGroups'
+
+const group = {
+  groupId: 2093000000000000001n, groupNo: 'CLG-2093000000000000001', status: 'ACTIVE',
+  warehouseId: 2093000000000000002n, channelCode: 'NY-EXX', lockedPlanId: null,
+  version: 0, fullPackageCount: 18, createdAt: '2026-08-29T10:00:00', updatedAt: '2026-08-29T10:00:00',
+  members: [
+    { tenantId: 2093000000000000004n, orderId: 2093000000000000005n, inboundId: 2093000000000000006n, fullPackageCount: 8 },
+    { tenantId: 2093000000000000007n, orderId: 2093000000000000008n, inboundId: 2093000000000000009n, fullPackageCount: 10 },
+  ],
+}
+
+describe('co-load group API', () => {
+  beforeEach(() => vi.restoreAllMocks())
+
+  it('creates one group from two stable order ids with idempotency', async () => {
+    const post = vi.spyOn(http, 'post').mockResolvedValue({ code: '200', message: 'ok', data: group })
+    const orderIds = ['2093000000000000005', '2093000000000000008']
+    const result = await createPlatformCoLoadGroup(orderIds)
+    expect(post).toHaveBeenCalledWith('/platform/v1/first-leg/coload-groups', { orderIds }, { headers: { 'Idempotency-Key': expect.any(String) } })
+    expect(result.groupId).toBe('2093000000000000001')
+    expect(result.members.map((member) => member.orderId)).toEqual(orderIds)
+    expect(result.members.map((member) => member.tenantId)).toEqual(['2093000000000000004', '2093000000000000007'])
+  })
+
+  it('cancels the whole group by its visible inbound code without exposing group identifiers', async () => {
+    const post = vi.spyOn(http, 'post').mockResolvedValue({ code: '200', message: 'ok', data: { ...group, status: 'CANCELLED', version: 1 } })
+    await cancelPlatformCoLoadGroup('NYEXX2608310001', '路线调整')
+    expect(post).toHaveBeenCalledWith(
+      '/platform/v1/first-leg/coload-groups/by-inbound-code/NYEXX2608310001/cancel',
+      { reason: '路线调整' },
+      { headers: { 'Idempotency-Key': expect.any(String) } },
+    )
+  })
+
+  it('loads the business-only group summary by inbound code without platform batch-query', async () => {
+    const get = vi.spyOn(http, 'get').mockResolvedValue({ code: '200', message: 'ok', data: {
+      status: 'LOCKED', memberCount: '2', members: [{ inboundCode: ' NYEXX2608310001 ' }, { inboundCode: 'NYEXX2608310002' }],
+    } })
+    const post = vi.spyOn(http, 'post')
+    const result = await getPlatformCoLoadGroupByInboundCode('NYEXX2608310001')
+    expect(get).toHaveBeenCalledWith('/platform/v1/first-leg/coload-groups/by-inbound-code/NYEXX2608310001')
+    expect(result).toEqual({ status: 'LOCKED', memberCount: 2, members: [{ inboundCode: 'NYEXX2608310001' }, { inboundCode: 'NYEXX2608310002' }] })
+    expect(post).not.toHaveBeenCalled()
+  })
+
+  it('normalizes missing and blank member inbound codes without exposing technical ids as fallbacks', async () => {
+    const incompleteSummary = {
+      status: 'ACTIVE', memberCount: 4,
+      members: [
+        { inboundCode: undefined }, { inboundCode: null }, { inboundCode: '   ' }, { inboundCode: ' NYEXX2608310003 ' },
+      ],
+    }
+    vi.spyOn(http, 'get').mockResolvedValue({ code: '200', message: 'ok', data: incompleteSummary })
+    const result = await getPlatformCoLoadGroupByInboundCode('NYEXX2608310001')
+    expect(result.members.map((member) => member.inboundCode)).toEqual(['', '', '', 'NYEXX2608310003'])
+    expect(result.members.map((member) => member.inboundCode)).not.toContain('2093000000000000012')
+  })
+})
diff --git a/src/modules/unified-orders/api/coLoadGroups.ts b/src/modules/unified-orders/api/coLoadGroups.ts
new file mode 100644
index 00000000..051b290c
--- /dev/null
+++ b/src/modules/unified-orders/api/coLoadGroups.ts
@@ -0,0 +1,106 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+
+export type CoLoadGroupStatus = 'ACTIVE' | 'LOCKED' | 'CONSUMED' | 'CANCELLED'
+
+export interface CoLoadGroupMember {
+  tenantId: string
+  orderId: string
+  inboundId: string
+  fullPackageCount: number
+}
+
+export interface CoLoadGroup {
+  groupId: string
+  groupNo: string
+  status: CoLoadGroupStatus
+  warehouseId: string
+  channelCode: string
+  lockedPlanId: string | null
+  version: number
+  members: CoLoadGroupMember[]
+  fullPackageCount: number
+  createdAt: string
+  updatedAt: string
+}
+
+export interface CoLoadBusinessMember {
+  inboundCode: string
+}
+
+export interface CoLoadBusinessSummary {
+  status: CoLoadGroupStatus
+  memberCount: number
+  members: CoLoadBusinessMember[]
+}
+
+type RawId = string | number
+type RawCoLoadGroupMember = Omit<CoLoadGroupMember, 'tenantId' | 'orderId' | 'inboundId'> & {
+  tenantId: RawId
+  orderId: RawId
+  inboundId: RawId
+}
+type RawCoLoadGroup = Omit<CoLoadGroup, 'groupId' | 'warehouseId' | 'lockedPlanId' | 'members'> & {
+  groupId: RawId
+  warehouseId: RawId
+  lockedPlanId: RawId | null
+  members: RawCoLoadGroupMember[]
+}
+type RawCoLoadBusinessSummary = Omit<CoLoadBusinessSummary, 'memberCount' | 'members'> & {
+  memberCount: number | string
+  members: Array<{ inboundCode?: string | null }>
+}
+
+const basePath = '/platform/v1/first-leg/coload-groups'
+const optionalId = (value: RawId | null) => value == null ? null : String(value)
+const operationId = (prefix: string) => `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`
+
+function normalizeGroup(raw: RawCoLoadGroup): CoLoadGroup {
+  return {
+    ...raw,
+    groupId: String(raw.groupId),
+    warehouseId: String(raw.warehouseId),
+    lockedPlanId: optionalId(raw.lockedPlanId),
+    version: Number(raw.version),
+    fullPackageCount: Number(raw.fullPackageCount),
+    members: (raw.members || []).map((member) => ({
+      ...member,
+      tenantId: String(member.tenantId),
+      orderId: String(member.orderId),
+      inboundId: String(member.inboundId),
+      fullPackageCount: Number(member.fullPackageCount),
+    })),
+  }
+}
+
+export async function createPlatformCoLoadGroup(orderIds: string[]) {
+  const response = await http.post<ApiEnvelope<RawCoLoadGroup>, ApiEnvelope<RawCoLoadGroup>>(
+    basePath,
+    { orderIds },
+    { headers: { 'Idempotency-Key': operationId('admin-coload-create') } },
+  )
+  return normalizeGroup(unwrapApiResponse(response))
+}
+
+export async function cancelPlatformCoLoadGroup(inboundCode: string, reason?: string | null) {
+  const response = await http.post<ApiEnvelope<RawCoLoadGroup>, ApiEnvelope<RawCoLoadGroup>>(
+    `${basePath}/by-inbound-code/${encodeURIComponent(inboundCode)}/cancel`,
+    { reason: reason?.trim() || null },
+    { headers: { 'Idempotency-Key': operationId('admin-coload-cancel') } },
+  )
+  return normalizeGroup(unwrapApiResponse(response))
+}
+
+export async function getPlatformCoLoadGroupByInboundCode(inboundCode: string) {
+  const response = await http.get<ApiEnvelope<RawCoLoadBusinessSummary>, ApiEnvelope<RawCoLoadBusinessSummary>>(
+    `${basePath}/by-inbound-code/${encodeURIComponent(inboundCode)}`,
+  )
+  const raw = unwrapApiResponse(response)
+  const members = (raw.members || []).map((member) => ({
+    inboundCode: typeof member.inboundCode === 'string' ? member.inboundCode.trim() : '',
+  }))
+  return {
+    status: raw.status,
+    memberCount: Number(raw.memberCount),
+    members,
+  } satisfies CoLoadBusinessSummary
+}
diff --git a/src/modules/unified-orders/api/inboundFeeDetails.test.ts b/src/modules/unified-orders/api/inboundFeeDetails.test.ts
new file mode 100644
index 00000000..5bed6536
--- /dev/null
+++ b/src/modules/unified-orders/api/inboundFeeDetails.test.ts
@@ -0,0 +1,88 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import {
+  adjustInboundFeeDetail, createInboundFeeDetail, deleteInboundFeeDetail, listInboundFeeDetails,
+  listInboundFeeItemOptions, listInboundFeeSupplierOptions, reviewInboundFeeDetail,
+  updateInboundFeeDetail, uploadInboundFeePaymentVoucher, voidInboundFeeDetail, type SaveInboundFeeDetailRequest,
+} from './inboundFeeDetails'
+
+vi.mock('@/shared/api/http', async () => {
+  const actual = await vi.importActual<typeof import('@/shared/api/http')>('@/shared/api/http')
+  return { ...actual, http: { get: vi.fn(), post: vi.fn(), put: vi.fn(), delete: vi.fn() } }
+})
+
+describe('inbound fee-detail API', () => {
+  beforeEach(() => vi.clearAllMocks())
+  it.each(['', ' ', 'null', 'undefined'])('rejects invalid inboundId %j without issuing HTTP', async (inboundId) => {
+    await expect(listInboundFeeDetails('100', inboundId)).rejects.toThrow('inboundId is required')
+    expect(http.get).not.toHaveBeenCalled()
+  })
+
+  it('maps the complete write contract and optimistic version', async () => {
+    const payload: SaveInboundFeeDetailRequest = { feeItemId: '31', direction: 'PAYABLE', businessDate: '2026-08-12', unitPrice: 12.5, currency: 'CNY', amount: 125, supplierId: '41', settlementMode: 'DIRECT_PAID', paidAt: '2026-08-12T10:30:00', paymentMethod: 'BANK_TRANSFER', paymentReferenceNo: 'BANK-31', paymentVoucherFileIds: ['9001'], remark: '验收' }
+    vi.mocked(http.get).mockResolvedValue({ code: '200', message: 'success', data: [] })
+    vi.mocked(http.post).mockResolvedValue({ code: '200', message: 'success', data: null })
+    vi.mocked(http.put).mockResolvedValue({ code: '200', message: 'success', data: payload })
+    vi.mocked(http.delete).mockResolvedValue({ code: '200', message: 'success', data: null })
+    await listInboundFeeDetails('100', '88'); await createInboundFeeDetail('100', '88', payload)
+    await updateInboundFeeDetail('100', '88', '11', payload); await reviewInboundFeeDetail('100', '88', '11', 'approve')
+    await reviewInboundFeeDetail('100', '88', '11', 'reject', '金额有误'); await adjustInboundFeeDetail('100', '88', '11', 3, payload)
+    await voidInboundFeeDetail('100', '88', '11', 3); await deleteInboundFeeDetail('100', '88', '11')
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/inbounds/88/fee-details', { params: { accountId: '100' } })
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/inbounds/88/fee-details/11/adjust', payload, { params: { accountId: '100', expectedSourceVersion: 3 } })
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/inbounds/88/fee-details/11/void', { expectedSourceVersion: 3 }, { params: { accountId: '100' } })
+    expect(http.delete).toHaveBeenCalledWith('/platform/v1/inbounds/88/fee-details/11', { params: { accountId: '100' } })
+  })
+
+  it('reuses the scoped FINANCE_VOUCHER upload and fails closed on customer mismatch', async () => {
+    vi.mocked(http.post).mockResolvedValueOnce({ code: '200', data: { fileId: 9001, tenantId: 100, fileName: '付款凭证.pdf' } })
+    await expect(uploadInboundFeePaymentVoucher('100', new File(['x'], '付款凭证.pdf'))).resolves.toEqual({ fileId: '9001', fileName: '付款凭证.pdf' })
+    expect(http.post).toHaveBeenCalledWith('/platform/finance/v1/vouchers', expect.any(FormData), { params: { customerId: '100' }, headers: { 'Content-Type': 'multipart/form-data' } })
+    vi.mocked(http.post).mockResolvedValueOnce({ code: '200', data: { fileId: 9002, tenantId: 101, fileName: '错客户.pdf' } })
+    await expect(uploadInboundFeePaymentVoucher('100', new File(['x'], '错客户.pdf'))).rejects.toThrow('付款凭证与当前客户不匹配')
+  })
+
+  it('keeps an empty supplier category as null and rejects an unknown non-empty category', async () => {
+    vi.mocked(http.get).mockResolvedValue({ code: '200', data: { records: [
+      { id: 31, feeTypeName: '拖车费', feeCode: 'TRUCKING', supplierCategory: 'TRUCKING', warehousePayable: true },
+      { id: 33, feeTypeName: '缺少类别', feeCode: 'MISSING', warehousePayable: true },
+    ] } })
+    await expect(listInboundFeeItemOptions()).resolves.toMatchObject([
+      { id: 31, feeCode: 'TRUCKING', supplierCategory: 'TRUCKING' },
+      { id: 33, feeCode: 'MISSING', supplierCategory: null },
+    ])
+    vi.mocked(http.get).mockResolvedValue({ code: '200', data: { records: [
+      { id: 32, feeTypeName: '未知费用', feeCode: 'UNMAPPED', supplierCategory: 'UNKNOWN', warehousePayable: true },
+    ] } })
+    await expect(listInboundFeeItemOptions()).rejects.toThrow('Unsupported supplierCategory: UNKNOWN')
+  })
+
+  it('requests and retains only ACTIVE suppliers in the required category', async () => {
+    vi.mocked(http.get).mockResolvedValue({ code: '200', data: { records: [
+      { id: 41, tenantId: 0, name: '承运商A', category: 'TRUCKING', status: 'ACTIVE', version: 1, deleted: false },
+      { id: 42, tenantId: 0, name: '停用承运商', category: 'TRUCKING', status: 'INACTIVE', version: 1, deleted: false },
+      { id: 43, tenantId: 0, name: '报关行', category: 'CUSTOMS', status: 'ACTIVE', version: 1, deleted: false },
+    ], page: 1, size: 200, total: 3, pages: 1 } })
+    await expect(listInboundFeeSupplierOptions('TRUCKING')).resolves.toEqual([
+      { id: '41', supplierName: '承运商A', category: 'TRUCKING' },
+    ])
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/suppliers', { params: {
+      page: 1, size: 200, category: 'TRUCKING', region: undefined, status: 'ACTIVE', keyword: undefined,
+    } })
+  })
+
+  it('requests all categories and retains every ACTIVE supplier when the category is empty', async () => {
+    vi.mocked(http.get).mockResolvedValue({ code: '200', data: { records: [
+      { id: 41, tenantId: 0, name: '承运商A', category: 'TRUCKING', status: 'ACTIVE', version: 1, deleted: false },
+      { id: 42, tenantId: 0, name: '停用承运商', category: 'TRUCKING', status: 'INACTIVE', version: 1, deleted: false },
+      { id: 43, tenantId: 0, name: '报关行', category: 'CUSTOMS', status: 'ACTIVE', version: 1, deleted: false },
+    ], page: 1, size: 200, total: 3, pages: 1 } })
+    await expect(listInboundFeeSupplierOptions(null)).resolves.toEqual([
+      { id: '41', supplierName: '承运商A', category: 'TRUCKING' },
+      { id: '43', supplierName: '报关行', category: 'CUSTOMS' },
+    ])
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/suppliers', { params: {
+      page: 1, size: 200, category: undefined, region: undefined, status: 'ACTIVE', keyword: undefined,
+    } })
+  })
+})
diff --git a/src/modules/unified-orders/api/inboundFeeDetails.ts b/src/modules/unified-orders/api/inboundFeeDetails.ts
new file mode 100644
index 00000000..f8d77e4f
--- /dev/null
+++ b/src/modules/unified-orders/api/inboundFeeDetails.ts
@@ -0,0 +1,149 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import { listSuppliers, type SupplierCategory } from '@/modules/suppliers'
+
+export type InboundFeeDirection = 'RECEIVABLE' | 'PAYABLE'
+export type InboundFeeReviewStatus = 'PENDING' | 'APPROVED' | 'REJECTED'
+export type FeeSettlementMode = 'ON_ACCOUNT' | 'DIRECT_PAID'
+export type FeePaymentMethod = 'ONLINE' | 'BANK_TRANSFER' | 'CASH' | 'OTHER'
+
+export interface InboundFeeDetail {
+  id: string | number
+  inboundId: string | number
+  feeItemId: string | number
+  sourceType: string
+  sourceFeeVersion: number
+  inboundCode: string | null
+  direction: InboundFeeDirection
+  supplierId: string | number | null
+  supplierName: string | null
+  supplierCategory: SupplierCategory | null
+  settlementMode?: FeeSettlementMode | null
+  paidAt?: string | null
+  paymentMethod?: FeePaymentMethod | null
+  paymentReferenceNo?: string | null
+  paymentVoucherFileIds?: Array<string | number> | null
+  businessDate: string
+  customerName: string | null
+  feeTypeNameSnapshot: string
+  unitPrice: number
+  currency: string
+  amount: number
+  remark: string | null
+  reviewStatus: InboundFeeReviewStatus
+  reviewReason: string | null
+  reviewerName: string | null
+  reviewedAt: string | null
+  publicationStatus: string
+}
+
+export interface SaveInboundFeeDetailRequest {
+  feeItemId: string | number
+  direction: InboundFeeDirection
+  businessDate: string
+  unitPrice: number
+  currency: string
+  amount: number
+  supplierId: string | number | null
+  settlementMode: FeeSettlementMode | null
+  paidAt: string | null
+  paymentMethod: FeePaymentMethod | null
+  paymentReferenceNo: string | null
+  paymentVoucherFileIds: Array<string | number> | null
+  remark: string | null
+}
+
+export interface InboundFeeItemOption {
+  id: string | number
+  feeTypeName: string
+  feeCode: string
+  supplierCategory: SupplierCategory | null
+  warehousePayable: boolean
+  warehouseReceivable: boolean
+}
+
+export interface InboundFeeSupplierOption { id: string; supplierName: string; category: SupplierCategory }
+export interface FeePaymentVoucher { fileId: string; fileName: string }
+
+const supplierCategories: SupplierCategory[] = ['BOOKING', 'CUSTOMS', 'TRUCKING', 'CERTIFICATE']
+
+function supplierCategory(value: unknown): SupplierCategory | null {
+  if (value == null || value === '') return null
+  if (supplierCategories.includes(value as SupplierCategory)) return value as SupplierCategory
+  throw new TypeError(`Unsupported supplierCategory: ${String(value)}`)
+}
+
+function basePath(inboundId: string) {
+  const identifier = String(inboundId ?? '').trim()
+  if (!identifier || identifier === 'null' || identifier === 'undefined') throw new TypeError('inboundId is required')
+  return `/platform/v1/inbounds/${encodeURIComponent(identifier)}/fee-details`
+}
+const config = (accountId: string) => ({ params: { accountId } })
+
+export async function listInboundFeeDetails(accountId: string, inboundId: string) {
+  const response = await http.get<unknown, ApiEnvelope<InboundFeeDetail[]>>(basePath(inboundId), config(accountId))
+  return unwrapApiResponse(response) || []
+}
+
+export async function createInboundFeeDetail(accountId: string, inboundId: string, payload: SaveInboundFeeDetailRequest) {
+  return unwrapApiResponse(await http.post<unknown, ApiEnvelope<InboundFeeDetail>>(basePath(inboundId), payload, config(accountId)))
+}
+
+export async function updateInboundFeeDetail(accountId: string, inboundId: string, detailId: string, payload: SaveInboundFeeDetailRequest) {
+  return unwrapApiResponse(await http.put<unknown, ApiEnvelope<InboundFeeDetail>>(`${basePath(inboundId)}/${encodeURIComponent(detailId)}`, payload, config(accountId)))
+}
+
+export async function deleteInboundFeeDetail(accountId: string, inboundId: string, detailId: string) {
+  return unwrapApiResponse(await http.delete<unknown, ApiEnvelope<null>>(`${basePath(inboundId)}/${encodeURIComponent(detailId)}`, config(accountId)))
+}
+
+export async function reviewInboundFeeDetail(accountId: string, inboundId: string, detailId: string, action: 'approve' | 'reject', reason?: string) {
+  return unwrapApiResponse(await http.post<unknown, ApiEnvelope<null>>(
+    `${basePath(inboundId)}/${encodeURIComponent(detailId)}/${action}`,
+    action === 'reject' ? { reason } : undefined, config(accountId),
+  ))
+}
+
+export async function adjustInboundFeeDetail(accountId: string, inboundId: string, detailId: string, expectedSourceVersion: number, payload: SaveInboundFeeDetailRequest) {
+  return unwrapApiResponse(await http.post<unknown, ApiEnvelope<InboundFeeDetail>>(
+    `${basePath(inboundId)}/${encodeURIComponent(detailId)}/adjust`, payload,
+    { params: { accountId, expectedSourceVersion } },
+  ))
+}
+
+export async function voidInboundFeeDetail(accountId: string, inboundId: string, detailId: string, expectedSourceVersion: number) {
+  return unwrapApiResponse(await http.post<unknown, ApiEnvelope<null>>(
+    `${basePath(inboundId)}/${encodeURIComponent(detailId)}/void`, { expectedSourceVersion }, config(accountId),
+  ))
+}
+
+export async function listInboundFeeItemOptions() {
+  const response = await http.get<unknown, ApiEnvelope<{ records: Record<string, unknown>[] }>>(
+    '/platform/v1/fee-items', { params: { status: 'ACTIVE', page: 1, size: 200 } },
+  )
+  return (unwrapApiResponse(response).records || []).map((raw): InboundFeeItemOption => ({
+    id: raw.id as string | number,
+    feeTypeName: String(raw.feeTypeName || ''),
+    feeCode: String(raw.feeCode || ''),
+    supplierCategory: supplierCategory(raw.supplierCategory),
+    warehousePayable: Boolean(raw.warehousePayable),
+    warehouseReceivable: Boolean(raw.warehouseReceivable),
+  }))
+}
+
+export async function listInboundFeeSupplierOptions(category: SupplierCategory | null) {
+  const page = await listSuppliers({ status: 'ACTIVE', category: category ?? undefined, page: 1, size: 200 })
+  return page.records.filter((supplier) => supplier.status === 'ACTIVE' && (!category || supplier.category === category)).map((supplier): InboundFeeSupplierOption => ({
+    id: supplier.id, supplierName: supplier.name, category: supplier.category,
+  }))
+}
+
+export async function uploadInboundFeePaymentVoucher(customerId: string, file: File): Promise<FeePaymentVoucher> {
+  const body = new FormData(); body.append('file', file)
+  const raw = unwrapApiResponse(await http.post<unknown, ApiEnvelope<Record<string, unknown>>>('/platform/finance/v1/vouchers', body, {
+    params: { customerId }, headers: { 'Content-Type': 'multipart/form-data' },
+  }))
+  const fileId = raw.fileId == null ? '' : String(raw.fileId)
+  const echoedCustomerId = raw.tenantId == null ? String(raw.customerId ?? customerId) : String(raw.tenantId)
+  if (!fileId || echoedCustomerId !== customerId) throw new Error('付款凭证与当前客户不匹配')
+  return { fileId, fileName: String(raw.fileName || raw.file_name || file.name) }
+}
diff --git a/src/modules/unified-orders/api/orderFulfillment.test.ts b/src/modules/unified-orders/api/orderFulfillment.test.ts
new file mode 100644
index 00000000..b4030a47
--- /dev/null
+++ b/src/modules/unified-orders/api/orderFulfillment.test.ts
@@ -0,0 +1,50 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import { getPlatformOrderFulfillmentTree, normalizeOrderFulfillmentTree } from './orderFulfillment'
+
+vi.mock('@/shared/api/http', () => ({
+  http: { get: vi.fn() },
+  unwrapApiResponse: <T>(response: { data: T }) => response.data,
+}))
+
+describe('single-remainder order fulfillment contract', () => {
+  beforeEach(() => vi.mocked(http.get).mockReset())
+
+  it('normalizes the new source-fragment plus one remainder model without double counting', () => {
+    const tree = normalizeOrderFulfillmentTree({
+      rootOrderId: '10', rootOrderNo: 'CC-10', rootVersion: 3,
+      originalPackageCount: 4, cumulativeLoadedPackageCount: 2, currentRemainderPackageCount: 2,
+      fragments: [
+        { orderId: '10', orderNo: 'CC-10', splitSequence: 0, splitRole: 'COMPLETED_FRAGMENT', plannedPackageCount: 4, pickedPackageCount: 1, unpickedPackageCount: 0 },
+        { orderId: '11', orderNo: 'CC-10-1', splitSequence: 1, splitRole: 'COMPLETED_FRAGMENT', plannedPackageCount: 3, pickedPackageCount: 1, unpickedPackageCount: 0 },
+        { orderId: '12', orderNo: 'CC-10-2', splitSequence: 2, splitRole: 'ACTIVE_REMAINDER', plannedPackageCount: 2, pickedPackageCount: 0, unpickedPackageCount: 2 },
+      ],
+    }, '10')
+    expect(tree).toMatchObject({
+      rootOrderId: '10', originalPackageCount: 4,
+      cumulativeLoadedPackageCount: 2, currentRemainderPackageCount: 2,
+      historicalTwoChildModel: false,
+    })
+    expect(tree.fragments.at(-1)).toMatchObject({ orderNo: 'CC-10-2', pickedPackageCount: 0, unpickedPackageCount: 2 })
+  })
+
+  it('keeps historical LOADED plus REMAINDER trees readable and marks them as historical', () => {
+    const tree = normalizeOrderFulfillmentTree({
+      parentOrderId: 10, parentOrderNo: 'CC-10', parentVersion: 2,
+      allocatedPackageCount: 1, remainingPackageCount: 3,
+      children: [
+        { orderId: 11, orderNo: 'CC-10-1', splitSequence: 1, splitRole: 'LOADED', packageCount: 1, sourceOrderId: 10 },
+        { orderId: 12, orderNo: 'CC-10-2', splitSequence: 2, splitRole: 'REMAINDER', packageCount: 3, sourceOrderId: 10 },
+      ],
+    }, '10')
+    expect(tree.historicalTwoChildModel).toBe(true)
+    expect(tree.originalPackageCount).toBe(4)
+    expect(tree.fragments.map((item) => [item.pickedPackageCount, item.unpickedPackageCount])).toEqual([[1, 0], [0, 3]])
+  })
+
+  it('queries the real platform fulfillment-tree with tenant isolation', async () => {
+    vi.mocked(http.get).mockResolvedValue({ data: { rootOrderId: '10', fragments: [] } })
+    await expect(getPlatformOrderFulfillmentTree('20', '10')).resolves.toMatchObject({ rootOrderId: '10' })
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/orders/10/fulfillment-tree', { params: { tenantId: '20' } })
+  })
+})
diff --git a/src/modules/unified-orders/api/orderFulfillment.ts b/src/modules/unified-orders/api/orderFulfillment.ts
new file mode 100644
index 00000000..c4e35921
--- /dev/null
+++ b/src/modules/unified-orders/api/orderFulfillment.ts
@@ -0,0 +1,123 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+
+export interface UnifiedOrderFulfillmentFragment {
+  orderId: string
+  orderNo: string | null
+  splitSequence: number | null
+  splitRole: string | null
+  plannedPackageCount: number | null
+  pickedPackageCount: number | null
+  unpickedPackageCount: number | null
+  loadingPlanId: string | null
+  containerBookingId: string | null
+  sourceOrderId: string | null
+  status: string | null
+  historical: boolean
+}
+
+export interface UnifiedOrderFulfillmentTree {
+  rootOrderId: string
+  rootOrderNo: string | null
+  rootVersion: number | null
+  originalPackageCount: number | null
+  cumulativeLoadedPackageCount: number | null
+  currentRemainderPackageCount: number | null
+  fragments: UnifiedOrderFulfillmentFragment[]
+  historicalTwoChildModel: boolean
+}
+
+type UnknownRecord = Record<string, unknown>
+
+function record(value: unknown): UnknownRecord {
+  return value && typeof value === 'object' ? value as UnknownRecord : {}
+}
+
+function stringValue(value: unknown) {
+  return value === null || value === undefined || value === '' ? null : String(value)
+}
+
+function numberValue(value: unknown) {
+  if (value === null || value === undefined || value === '') return null
+  const parsed = Number(value)
+  return Number.isFinite(parsed) ? Math.trunc(parsed) : null
+}
+
+function firstNumber(source: UnknownRecord, keys: string[]) {
+  for (const key of keys) {
+    const value = numberValue(source[key])
+    if (value !== null) return value
+  }
+  return null
+}
+
+function firstString(source: UnknownRecord, keys: string[]) {
+  for (const key of keys) {
+    const value = stringValue(source[key])
+    if (value !== null) return value
+  }
+  return null
+}
+
+export function normalizeOrderFulfillmentTree(payload: unknown, fallbackOrderId: string): UnifiedOrderFulfillmentTree {
+  const raw = record(payload)
+  const rootOrderId = firstString(raw, ['rootOrderId', 'parentOrderId', 'orderId']) || fallbackOrderId
+  const rootOrderNo = firstString(raw, ['rootOrderNo', 'parentOrderNo', 'orderNo'])
+  const children = Array.isArray(raw.fragments) ? raw.fragments : Array.isArray(raw.children) ? raw.children : []
+  const legacy = raw.historicalTwoChildModel === true
+    || children.some((item) => {
+      const child = record(item)
+      const role = firstString(child, ['splitRole', 'role'])
+      const childId = firstString(child, ['orderId', 'childOrderId'])
+      const sourceId = firstString(child, ['sourceOrderId', 'parentOrderId'])
+      return role === 'LOADED' && childId !== null && sourceId !== null && childId !== sourceId
+    })
+  const original = firstNumber(raw, ['originalPackageCount', 'sourcePackageCount'])
+    ?? (() => {
+      const allocated = firstNumber(raw, ['cumulativeLoadedPackageCount', 'allocatedPackageCount', 'loadedPackageCount'])
+      const remainder = firstNumber(raw, ['currentRemainderPackageCount', 'remainingPackageCount'])
+      return allocated === null || remainder === null ? null : allocated + remainder
+    })()
+  const cumulativeLoaded = firstNumber(raw, ['cumulativeLoadedPackageCount', 'allocatedPackageCount', 'loadedPackageCount'])
+  const currentRemainder = firstNumber(raw, ['currentRemainderPackageCount', 'remainingPackageCount'])
+  const fragments = children.map((item): UnifiedOrderFulfillmentFragment => {
+    const child = record(item)
+    const role = firstString(child, ['splitRole', 'fragmentRole', 'role'])
+    const planned = firstNumber(child, ['plannedPackageCount', 'sourcePackageCount', 'packageCount'])
+    const picked = firstNumber(child, ['pickedPackageCount', 'loadedPackageCount'])
+      ?? (role === 'LOADED' ? firstNumber(child, ['packageCount']) : 0)
+    const unpicked = firstNumber(child, ['unpickedPackageCount', 'remainingPackageCount'])
+      ?? (planned === null || picked === null ? null : Math.max(0, planned - picked))
+    return {
+      orderId: firstString(child, ['orderId', 'childOrderId', 'sourceOrderId']) || '',
+      orderNo: firstString(child, ['orderNo', 'childOrderNo', 'sourceOrderNo']),
+      splitSequence: firstNumber(child, ['splitSequence', 'sequence']),
+      splitRole: role,
+      plannedPackageCount: planned,
+      pickedPackageCount: picked,
+      unpickedPackageCount: unpicked,
+      loadingPlanId: firstString(child, ['loadingPlanId']),
+      containerBookingId: firstString(child, ['containerBookingId']),
+      sourceOrderId: firstString(child, ['sourceOrderId', 'parentOrderId']),
+      status: firstString(child, ['status', 'orderStatus', 'processStatus']),
+      historical: legacy,
+    }
+  }).filter((item) => item.orderId)
+  return {
+    rootOrderId,
+    rootOrderNo,
+    rootVersion: firstNumber(raw, ['rootVersion', 'parentVersion']),
+    originalPackageCount: original,
+    cumulativeLoadedPackageCount: cumulativeLoaded,
+    currentRemainderPackageCount: currentRemainder,
+    fragments,
+    historicalTwoChildModel: legacy,
+  }
+}
+
+export async function getPlatformOrderFulfillmentTree(tenantId: string, orderId: string) {
+  const response = await http.get<ApiEnvelope<unknown>, ApiEnvelope<unknown>>(
+    `/platform/v1/orders/${encodeURIComponent(orderId)}/fulfillment-tree`,
+    { params: { tenantId } },
+  )
+  return normalizeOrderFulfillmentTree(unwrapApiResponse(response), orderId)
+}
diff --git a/src/modules/unified-orders/api/unifiedOrders.test.ts b/src/modules/unified-orders/api/unifiedOrders.test.ts
new file mode 100644
index 00000000..a22c8d7d
--- /dev/null
+++ b/src/modules/unified-orders/api/unifiedOrders.test.ts
@@ -0,0 +1,216 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import {
+  approvePlatformUnifiedOrder,
+  batchApprovePlatformUnifiedOrders,
+  getPlatformUnifiedOrderBatchApprovalPreview,
+  updatePlatformUnifiedOrderRemarks,
+  getPlatformUnifiedOrder,
+  downloadPlatformProductImage,
+  listPlatformUnifiedOrders,
+  listPlatformUnifiedOrderFeeDetails,
+  updatePlatformUnifiedOrderDeclaration,
+  updatePlatformUnifiedOrderPlanning,
+} from './unifiedOrders'
+
+vi.mock('@/shared/api/http', () => ({
+  http: { get: vi.fn(), post: vi.fn(), put: vi.fn() },
+  unwrapApiResponse: <T>(response: { data: T }) => response.data,
+}))
+
+describe('unified orders API contract', () => {
+  beforeEach(() => {
+    vi.mocked(http.get).mockReset()
+    vi.mocked(http.post).mockReset()
+    vi.mocked(http.put).mockReset()
+  })
+
+  it('uses the C02 platform orders endpoint and contract filters', async () => {
+    vi.mocked(http.get).mockResolvedValue({ data: { records: [], page: '2', size: '20', total: '0', pages: '0' } })
+    await expect(listPlatformUnifiedOrders({
+      keyword: 'CC', orderNo: 'CC-1', mainStatus: 'WAIT_SPLIT', customerId: '30001',
+      receivingWarehouseId: '11', destinationWarehouseId: '22', inboundCode: 'RK-1', internalOrderStatus: 'ACCEPTED',
+      expectedArrivalDate: '2026-08-10', feeReviewStatus: 'APPROVED', channelName: '海运', containerNo: 'CONT-1',
+      cabinetNo: 'CAB-1', sailingDate: '2026-08-12', loaded: true, fullContainer: false,
+      measurementReviewStatus: 'PENDING', fbaCode: 'FBA-1', createdFrom: '2026-08-01T00:00:00',
+      createdTo: '2026-08-31T23:59:59', page: 2, size: 20,
+    })).resolves.toMatchObject({ page: 2, size: 20, total: 0, pages: 0 })
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/orders', {
+      params: {
+        keyword: 'CC', orderNo: 'CC-1', mainStatus: 'WAIT_SPLIT', customerId: '30001',
+        receivingWarehouseId: '11', destinationWarehouseId: '22', inboundCode: 'RK-1', internalOrderStatus: 'ACCEPTED',
+        expectedArrivalDate: '2026-08-10', feeReviewStatus: 'APPROVED', channelName: '海运', containerNo: 'CONT-1',
+        cabinetNo: 'CAB-1', sailingDate: '2026-08-12', loaded: true, fullContainer: false,
+        measurementReviewStatus: 'PENDING', fbaCode: 'FBA-1', createdFrom: '2026-08-01T00:00:00',
+        createdTo: '2026-08-31T23:59:59', page: 2, size: 20,
+      },
+    })
+  })
+
+  it('omits empty optional filters while preserving false boolean values', async () => {
+    vi.mocked(http.get).mockResolvedValue({ data: { records: [], page: 1, size: 20, total: 0, pages: 0 } })
+    await listPlatformUnifiedOrders({ keyword: '', loaded: false, fullContainer: false, page: 1, size: 20 })
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/orders', {
+      params: { loaded: false, fullContainer: false, page: 1, size: 20 },
+    })
+  })
+
+  it('forwards every main-status tab with search and pagination unchanged', async () => {
+    const statuses = [
+      'PENDING_REVIEW', 'WAIT_MEASURE', 'WAIT_PALLETIZE', 'WAIT_SPLIT',
+      'LOADING', 'LOADED', 'DELIVERED', 'COMPLETED',
+    ] as const
+    vi.mocked(http.get).mockResolvedValue({ data: { records: [], page: 3, size: 20, total: 0, pages: 0 } })
+
+    for (const mainStatus of statuses) {
+      await listPlatformUnifiedOrders({ keyword: 'CC-2026', orderNo: 'FL-77', mainStatus, page: 3, size: 20 })
+    }
+
+    expect(vi.mocked(http.get).mock.calls).toEqual(statuses.map((mainStatus) => [
+      '/platform/v1/orders',
+      { params: { keyword: 'CC-2026', orderNo: 'FL-77', mainStatus, page: 3, size: 20 } },
+    ]))
+  })
+
+  it('normalizes C02 row IDs and keeps inboundId for measurement routing', async () => {
+    vi.mocked(http.get).mockResolvedValue({ data: {
+      records: [{ orderId: '90001', orderVersion: '7', tenantId: '208', inboundId: '77', inboundVersion: 3, mainStatus: 'WAIT_MEASURE', channelCode: ' NY_EXX ', channelName: '纽约渠道', holdFlag: true, currentHoldReason: '待核对货款', locationCodes: 'A0-01, B2-03', estimatedVolumeCbm: '0.4', expectedVolumeCbm: '0.45', actualGrossWeightKg: '12.5', actualVolumeCbm: '0.46', totalPalletCount: '3', totalNetWeightKg: '11.2', chargeableVolumeCbm: '0.5', totalQuantity: '48', skuNos: ['SKU-1', ''], requestedPickupAt: '2026-08-18T09:30:00', customerRemark: '客户备注', latestInternalNote: '最新内部备注', relation: { role: 'PARENT', rootOrderId: 90001, parentOrderId: null, splitSequence: null, childCount: '2' }, measurement: null, preload: null, loading: null, delivery: null, transport: null }],
+      page: 1, size: 20, total: 1, pages: 1,
+    } })
+    await expect(listPlatformUnifiedOrders({ page: 1, size: 20 })).resolves.toMatchObject({
+      records: [{ orderId: '90001', orderVersion: 7, tenantId: '208', inboundId: '77', inboundVersion: 3, channelCode: 'NY_EXX', holdFlag: true, currentHoldReason: '待核对货款', locationCodes: 'A0-01, B2-03', estimatedVolumeCbm: 0.4, expectedVolumeCbm: 0.45, actualGrossWeightKg: 12.5, actualVolumeCbm: 0.46, totalPalletCount: 3, totalNetWeightKg: 11.2, chargeableVolumeCbm: 0.5, totalQuantity: 48, skuNos: ['SKU-1'], requestedPickupAt: '2026-08-18T09:30:00', customerRemark: '客户备注', latestInternalNote: '最新内部备注', relation: { role: 'PARENT', rootOrderId: '90001', childCount: 2 } }],
+    })
+  })
+
+  it('loads the C02 detail shape and passes tenantId only on the detail boundary', async () => {
+    vi.mocked(http.get).mockResolvedValue({ data: {
+      summary: { orderId: '90001', tenantId: '208', mainStatus: 'WAIT_SPLIT' },
+      order: { order: {}, cargoes: [], parties: [], internalNotes: [], statusHistory: [] },
+      timeline: [],
+    } })
+    await expect(getPlatformUnifiedOrder('208', '90001')).resolves.toMatchObject({
+      summary: { orderId: '90001' }, order: { internalNotes: [] }, timeline: [],
+    })
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/orders/90001', { params: { tenantId: '208' } })
+  })
+
+  it('downloads a tenant-scoped product image for platform order details', async () => {
+    const image = new Blob(['image'], { type: 'image/png' })
+    vi.mocked(http.get).mockResolvedValue(image)
+
+    await expect(downloadPlatformProductImage('208/1', '90001')).resolves.toBe(image)
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/files/product-images/208%2F1/90001', { responseType: 'blob' })
+  })
+
+  it('uses the explicit first-leg approval boundary for pending review', async () => {
+    vi.mocked(http.post).mockResolvedValue({ data: null })
+
+    await approvePlatformUnifiedOrder('208', '90001')
+
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/orders/first-leg/90001/approve', undefined, { params: { tenantId: '208' } })
+  })
+
+  it('keeps split rows bound to their own current-container schedule and preserves effective-time semantics', async () => {
+    vi.mocked(http.get).mockResolvedValue({ data: {
+      records: [
+        { orderId: '90001', tenantId: '208', inboundId: '701', mainStatus: 'LOADED', relation: { role: 'PARENT', rootOrderId: '90001', parentOrderId: null, splitSequence: null, childCount: 1 }, transport: { cabinetNo: 'OLD-CAB', estimatedSailingAt: '2026-08-20T08:00:00', actualSailingAt: '2026-08-21T09:00:00', effectiveSailingAt: '2026-08-21T09:00:00', effectiveSailingAtEstimated: false, estimatedPortArrivalAt: '2026-09-01T08:00:00', actualPortArrivalAt: null, effectivePortArrivalAt: '2026-09-01T08:00:00', effectivePortArrivalAtEstimated: true } },
+        { orderId: '90002', tenantId: '208', inboundId: '702', mainStatus: 'LOADED', relation: { role: 'CHILD', rootOrderId: '90001', parentOrderId: '90001', splitSequence: 1, childCount: 0 }, transport: { cabinetNo: 'NEW-CAB', estimatedSailingAt: '2026-08-25T08:00:00', actualSailingAt: null, effectiveSailingAt: '2026-08-25T08:00:00', effectiveSailingAtEstimated: true, estimatedPortArrivalAt: null, actualPortArrivalAt: null, effectivePortArrivalAt: null, effectivePortArrivalAtEstimated: null } },
+      ],
+      page: 1, size: 20, total: 2, pages: 1,
+    } })
+
+    const result = await listPlatformUnifiedOrders({ page: 1, size: 20 })
+
+    expect(result.records.map((row) => ({ inboundId: row.inboundId, transport: row.transport }))).toMatchObject([
+      { inboundId: '701', transport: { cabinetNo: 'OLD-CAB', effectiveSailingAt: '2026-08-21T09:00:00', effectiveSailingAtEstimated: false, effectivePortArrivalAt: '2026-09-01T08:00:00', effectivePortArrivalAtEstimated: true } },
+      { inboundId: '702', transport: { cabinetNo: 'NEW-CAB', effectiveSailingAt: '2026-08-25T08:00:00', effectiveSailingAtEstimated: true, effectivePortArrivalAt: null, effectivePortArrivalAtEstimated: null } },
+    ])
+  })
+
+  it('uses the tenant-scoped batch approval contract and preserves long IDs', async () => {
+    vi.mocked(http.post).mockResolvedValue({ data: {
+      total: 2, successCount: 1, failureCount: 1,
+      successOrderIds: ['2089223263733518337'],
+      failedOrders: [{ orderId: '2089223263733518338', code: 'A0409', message: '订单状态已变化' }],
+    } })
+
+    await expect(batchApprovePlatformUnifiedOrders('2089176869176389634', [
+      { orderId: '2089223263733518337', orderVersion: 3 },
+      { orderId: '2089223263733518338', orderVersion: 8 },
+    ])).resolves.toMatchObject({ successCount: 1, failureCount: 1 })
+    expect(http.post).toHaveBeenCalledWith(
+      '/platform/v1/orders/first-leg/batch-approve',
+      { items: [
+        { orderId: '2089223263733518337', orderVersion: 3 },
+        { orderId: '2089223263733518338', orderVersion: 8 },
+      ] },
+      { params: { tenantId: '2089176869176389634' } },
+    )
+  })
+
+  it('loads one batch-review preview with Chinese goods and normalizes long IDs', async () => {
+    vi.mocked(http.post).mockResolvedValue({ data: {
+      total: 1,
+      approvableCount: 1,
+      items: [{
+        orderId: '2089223263733518337', orderVersion: '3', inboundCode: 'NYEXX2609080001',
+        customerId: '2089176869176389634', customerName: '测试客户', chineseGoodsNames: [' 蓝牙音箱 ', ''],
+        channelCode: 'NY_EXX', channelName: '纽约海运', destinationWarehouseCode: 'ONT8',
+        destinationWarehouseName: 'ONT8 亚马逊仓', canApprove: true, blockReason: null,
+      }],
+    } })
+    const items = [{ orderId: '2089223263733518337', orderVersion: 3 }]
+
+    await expect(getPlatformUnifiedOrderBatchApprovalPreview('2089176869176389634', items)).resolves.toMatchObject({
+      total: 1, approvableCount: 1,
+      items: [{ orderId: '2089223263733518337', orderVersion: 3, chineseGoodsNames: ['蓝牙音箱'] }],
+    })
+    expect(http.post).toHaveBeenCalledWith(
+      '/platform/v1/orders/first-leg/batch-review-preview',
+      { items },
+      { params: { tenantId: '2089176869176389634' } },
+    )
+  })
+
+  it('updates the three editable remarks while keeping customer remark outside the request', async () => {
+    const request = { expectedVersion: 7, internalRemark: '内部', warehouseRemark: '仓库', customerServiceRemark: '客服' }
+    vi.mocked(http.put).mockResolvedValue({ data: { ...request, version: 8, customerRemark: '客户只读' } })
+    await expect(updatePlatformUnifiedOrderRemarks('208', '90001', request)).resolves.toMatchObject({ version: 8 })
+    expect(http.put).toHaveBeenCalledWith('/platform/v1/orders/90001/remarks', request, { params: { tenantId: '208' } })
+  })
+
+  it('updates customer declaration fields through the versioned tenant-scoped contract', async () => {
+    const request = {
+      expectedVersion: 7, customerRemark: '易碎', expectedArrivalAt: '2026-09-06T10:00:00',
+      channelCode: 'US-SEA', channelName: '美西海运',
+      cargoes: [{ itemNo: 1, cargoName: '台灯', packageCount: 2, totalQuantity: 20, lengthCm: 40, widthCm: 30, heightCm: 20, grossWeightKg: 18, volumeCbm: 0.048 }],
+    }
+    vi.mocked(http.put).mockResolvedValue({ data: { orderNo: 'FL-1', inboundCode: 'RK-1', previousVersion: 7, version: 8, channelChangedBefore: false, channelChanged: true, changes: [] } })
+
+    await expect(updatePlatformUnifiedOrderDeclaration('208', '90001', request)).resolves.toMatchObject({ version: 8, channelChanged: true })
+    expect(http.put).toHaveBeenCalledWith('/platform/v1/orders/90001/declaration', request, { params: { tenantId: '208' } })
+  })
+
+  it('updates arrival and operator-estimated volume through the dedicated versioned contract', async () => {
+    const request = {
+      expectedVersion: 7,
+      expectedArrivalAt: '2026-09-10T18:30:00',
+      estimatedVolumeCbm: 0.625,
+    }
+    vi.mocked(http.put).mockResolvedValue({ data: { previousVersion: 7, version: 8, changes: [] } })
+
+    await expect(updatePlatformUnifiedOrderPlanning('2089176869176389634', '2089223263733518337', request))
+      .resolves.toMatchObject({ version: 8 })
+    expect(http.put).toHaveBeenCalledWith(
+      '/platform/v1/orders/2089223263733518337/planning',
+      request,
+      { params: { tenantId: '2089176869176389634' } },
+    )
+  })
+
+  it('loads fee detail rows from the inbound fee-detail contract', async () => {
+    vi.mocked(http.get).mockResolvedValue({ data: [{ id: '1', inboundId: '88', reviewStatus: 'APPROVED', amount: 100 }] })
+    await expect(listPlatformUnifiedOrderFeeDetails('208', '88')).resolves.toHaveLength(1)
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/inbounds/88/fee-details', { params: { accountId: '208' } })
+  })
+})
diff --git a/src/modules/unified-orders/api/unifiedOrders.ts b/src/modules/unified-orders/api/unifiedOrders.ts
new file mode 100644
index 00000000..f24bcca3
--- /dev/null
+++ b/src/modules/unified-orders/api/unifiedOrders.ts
@@ -0,0 +1,640 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+
+export const unifiedOrdersApiPath = '/platform/v1/orders'
+
+export type UnifiedOrderMainStatus =
+  | 'PENDING_REVIEW'
+  | 'WAIT_MEASURE'
+  | 'WAIT_PALLETIZE'
+  | 'WAIT_SPLIT'
+  | 'LOADING'
+  | 'LOADED'
+  | 'DELIVERED'
+  | 'COMPLETED'
+
+export const unifiedOrderStatusOptions: Array<{ value: UnifiedOrderMainStatus; label: string }> = [
+  { value: 'PENDING_REVIEW', label: '待审核' },
+  { value: 'WAIT_MEASURE', label: '待测量数据' },
+  { value: 'WAIT_PALLETIZE', label: '待一件代发组托' },
+  { value: 'WAIT_SPLIT', label: '待分柜' },
+  { value: 'LOADING', label: '装柜中' },
+  { value: 'LOADED', label: '装柜完成' },
+  { value: 'DELIVERED', label: '派送完成' },
+  { value: 'COMPLETED', label: '已完成' },
+]
+
+export interface UnifiedOrderMeasurementSummary {
+  reviewStatus: string | null
+  actualGrossWeightKg: number | null
+  actualVolumeCbm: number | null
+  chargeableWeightKg: number | null
+  completedAt: string | null
+}
+
+export interface UnifiedOrderPreloadSummary {
+  status: string | null
+  version: number | null
+  itemCount: number | null
+  updatedAt: string | null
+}
+
+export interface UnifiedOrderLoadingSummary {
+  status: string | null
+  loadingVersion: number | null
+  pickingVersion: number | null
+  expectedCount: number | null
+  pickedCount: number | null
+  evidenceCount: number | null
+  sealNo: string | null
+  updatedAt: string | null
+}
+
+export interface UnifiedOrderDeliverySummary {
+  status: string | null
+  completedAt: string | null
+  trackingNo: string | null
+}
+
+export interface UnifiedOrderTransportSummary {
+  loadingStatus: string | null
+  containerNo: string | null
+  cabinetNo: string | null
+  vesselName: string | null
+  voyageNo: string | null
+  estimatedSailingAt: string | null
+  actualSailingAt: string | null
+  effectiveSailingAt: string | null
+  effectiveSailingAtEstimated: boolean | null
+  estimatedPortArrivalAt: string | null
+  actualPortArrivalAt: string | null
+  effectivePortArrivalAt: string | null
+  effectivePortArrivalAtEstimated: boolean | null
+}
+
+export interface UnifiedOrderRelationSummary {
+  role: 'PARENT' | 'CHILD'
+  rootOrderId: number | string | null
+  parentOrderId: number | string | null
+  splitSequence: number | null
+  childCount: number
+}
+
+export interface UnifiedOrderCoLoadGroupSummary {
+  status: string
+  memberCount: number
+  memberInboundCodes: string[]
+}
+
+export interface UnifiedOrderResource {
+  orderId: number | string
+  orderVersion?: number | null
+  tenantId: number | string
+  orderNo: string | null
+  mainStatus: UnifiedOrderMainStatus
+  nextAction: string | null
+  relation: UnifiedOrderRelationSummary | null
+  internalOrderStatus: string | null
+  customerId: number | string | null
+  customerName: string | null
+  channelCode: string | null
+  channelName: string | null
+  channelChanged?: boolean
+  receivingWarehouseId: number | string | null
+  receivingWarehouseName: string | null
+  destinationWarehouseId: number | string | null
+  destinationWarehouseName: string | null
+  inboundId: number | string | null
+  inboundVersion: number | null
+  inboundCode: string | null
+  expectedShipDate: string | null
+  totalPackageCount: number | null
+  estimatedVolumeCbm?: number | null
+  expectedVolumeCbm?: number | null
+  locationCodes: string | null
+  actualGrossWeightKg: number | null
+  actualVolumeCbm: number | null
+  measurement: UnifiedOrderMeasurementSummary | null
+  preload: UnifiedOrderPreloadSummary | null
+  loading: UnifiedOrderLoadingSummary | null
+  delivery: UnifiedOrderDeliverySummary | null
+  transport: UnifiedOrderTransportSummary | null
+  coLoadGroup: UnifiedOrderCoLoadGroupSummary | null
+  createdAt: string | null
+  updatedAt: string | null
+  expectedArrivalAt: string | null
+  feeReviewStatus: string | null
+  holdFlag: boolean | null
+  currentHoldReason: string | null
+  companyName?: string | null
+  businessType?: string | null
+  fulfillmentType?: string | null
+  pickupMethod?: string | null
+  requestedPickupAt: string | null
+  pickupAt?: string | null
+  pickupContactPhone?: string | null
+  pickupAddress?: string | null
+  pickupPostalCode?: string | null
+  pickupContactEmail?: string | null
+  taxMode?: string | null
+  fullContainer?: boolean | null
+  customsInspection?: boolean | null
+  totalPalletCount: number | null
+  chargeableVolumeCbm: number | null
+  volumetricWeightKg: number | null
+  totalNetWeightKg: number | null
+  location?: string | null
+  destinationType?: string | null
+  destinationAddress?: string | null
+  destinationPostalCode?: string | null
+  destinationContact?: string | null
+  destinationContactPhone?: string | null
+  measurementCompletedAt: string | null
+  inboundCompletedAt: string | null
+  associatedFiles?: string[] | null
+  markFiles?: string[] | null
+  pcOrderFiles?: string[] | null
+  expressCompany: string | null
+  expressTrackingNo: string | null
+  skuNos: string[] | null
+  totalQuantity: number | null
+  shipmentId: string | null
+  referenceId: string | null
+  remark?: string | null
+  customerRemark?: string | null
+  latestInternalNote?: string | null
+  internalRemark?: string | null
+  warehouseRemark?: string | null
+  customerServiceRemark?: string | null
+  createdBy?: string | null
+}
+
+export interface UnifiedOrderTimelineEvent {
+  source: string | null
+  eventType: string | null
+  mainStatus: UnifiedOrderMainStatus | null
+  action: string | null
+  remark: string | null
+  operatorId: number | string | null
+  operatorName: string | null
+  occurredAt: string | null
+}
+
+export interface UnifiedOrderDetailOrderSnapshot {
+  id: number | string | null
+  version: number | null
+  tenantId: number | string | null
+  orderNo: string | null
+  customerId: number | string | null
+  customerName: string | null
+  transportMode: string | null
+  tradeTerm?: string | null
+  destinationCountryCode: string | null
+  destinationWarehouseId: number | string | null
+  destinationWarehouseName: string | null
+  expectedShipDate: string | null
+  customerRemark?: string | null
+  pickupMethod?: string | null
+  receivingWarehouseId: number | string | null
+  receivingWarehouseName: string | null
+  receivingWarehouseAddress?: string | null
+  receivingTime?: string | null
+  channelCode?: string | null
+  channelName: string | null
+  carrierId: number | string | null
+  carrierName: string | null
+  taxMode?: string | null
+  containerMode?: string | null
+  customsInspection?: boolean | null
+  destinationType?: string | null
+  amazonWarehouseCode?: string | null
+  shipmentId?: string | null
+  referenceId?: string | null
+  expressCompany?: string | null
+  expressTrackingNo?: string | null
+  submittedAt?: string | null
+  completedAt?: string | null
+  createdAt: string | null
+  updatedAt: string | null
+}
+
+export interface UnifiedOrderDetailOrderResource {
+  order: UnifiedOrderDetailOrderSnapshot | null
+  cargoes: Array<Record<string, unknown>>
+  parties: Array<Record<string, unknown>>
+  internalNotes: UnifiedOrderInternalNoteResource[]
+  statusHistory: UnifiedOrderStatusHistoryResource[]
+}
+
+export interface UnifiedOrderInternalNoteResource {
+  id: number | string
+  content: string
+  createdBy: number | string | null
+  createdAt: string | null
+}
+
+export interface UnifiedOrderStatusHistoryResource {
+  id: number | string
+  fromStatus: string | null
+  toStatus: string | null
+  action: string | null
+  reason: string | null
+  operatorId: number | string | null
+  operatorName: string | null
+  occurredAt: string | null
+}
+
+export interface UnifiedOrderDetailResource {
+  summary: UnifiedOrderResource
+  order: UnifiedOrderDetailOrderResource
+  timeline: UnifiedOrderTimelineEvent[]
+}
+
+export interface UnifiedOrderFeeDetailResource {
+  id: number | string
+  sourceFeeId?: number | string | null
+  sourceFeeVersion?: number | null
+  inboundId: number | string
+  inboundCode: string | null
+  reviewStatus: string | null
+  direction: string | null
+  customerName: string | null
+  invoiceTitle: string | null
+  businessDate: string | null
+  channelName: string | null
+  destinationName: string | null
+  fbaNo?: string | null
+  packageCount: number | null
+  actualGrossWeightKg: number | null
+  actualVolumeCbm: number | null
+  feeTypeNameSnapshot: string | null
+  currency: string | null
+  amount: number | null
+  chargeableQuantity: number | null
+  chargeUnit: string | null
+  unitPrice: number | null
+  inboundedAt: string | null
+  outboundAt?: string | null
+  storageDays?: number | null
+  billNo?: string | null
+  settlementStartDate?: string | null
+  settlementEndDate?: string | null
+}
+
+export interface UnifiedOrderPageResource {
+  records: UnifiedOrderResource[]
+  page: number
+  size: number
+  total: number
+  pages: number
+}
+
+export interface UnifiedOrderQuery {
+  tenantId?: string
+  keyword?: string
+  orderNo?: string
+  mainStatus?: UnifiedOrderMainStatus
+  customerId?: string
+  receivingWarehouseId?: string
+  destinationWarehouseId?: string
+  inboundCode?: string
+  internalOrderStatus?: string
+  expectedArrivalDate?: string
+  feeReviewStatus?: string
+  channelName?: string
+  containerNo?: string
+  cabinetNo?: string
+  sailingDate?: string
+  loaded?: boolean
+  fullContainer?: boolean
+  measurementReviewStatus?: string
+  fbaCode?: string
+  createdFrom?: string
+  createdTo?: string
+  page: number
+  size: number
+}
+
+type PagePayload = Omit<UnifiedOrderPageResource, 'page' | 'size' | 'total' | 'pages'> & {
+  page: number | string
+  size: number | string
+  total: number | string
+  pages: number | string
+}
+
+function integer(value: number | string | null | undefined, fallback: number) {
+  const parsed = Number(value)
+  return Number.isFinite(parsed) && parsed >= 0 ? Math.trunc(parsed) : fallback
+}
+
+function nullableInteger(value: number | string | null | undefined) {
+  if (value === null || value === undefined || value === '') return null
+  return integer(value, 0)
+}
+
+function numberValue(value: number | string | null | undefined) {
+  if (value === null || value === undefined || value === '') return null
+  const parsed = Number(value)
+  return Number.isFinite(parsed) ? parsed : null
+}
+
+function id(value: number | string | null | undefined) {
+  return value === null || value === undefined || value === '' ? null : String(value)
+}
+
+export interface UnifiedOrderDeclarationCargo {
+  itemNo: number
+  cargoName: string
+  cargoNameEn?: string | null
+  skuNo?: string | null
+  model?: string | null
+  packageCount: number
+  totalQuantity: number
+  lengthCm: number
+  widthCm: number
+  heightCm: number
+  grossWeightKg: number
+  volumeCbm: number
+  netWeightKg?: number | null
+  hsCode?: string | null
+  customsHsCode?: string | null
+  unitsPerPackage?: number | null
+  unitDeclaredValue?: number | null
+  declaredValue?: number | null
+  currency?: string | null
+  material?: string | null
+  usage?: string | null
+  brand?: string | null
+  cargoRemark?: string | null
+}
+
+export interface UpdateUnifiedOrderDeclarationRequest {
+  expectedVersion: number
+  customerRemark?: string | null
+  expectedArrivalAt?: string | null
+  estimatedVolumeCbm?: number | null
+  channelCode: string
+  channelName: string
+  cargoes: UnifiedOrderDeclarationCargo[]
+}
+
+export interface UnifiedOrderDeclarationChange {
+  itemNo: number | null
+  field: string
+  beforeValue: string | null
+  afterValue: string | null
+}
+
+export interface UpdateUnifiedOrderDeclarationResult {
+  orderNo: string | null
+  inboundCode: string | null
+  previousVersion: number
+  version: number
+  channelChangedBefore: boolean
+  channelChanged: boolean
+  changes: UnifiedOrderDeclarationChange[]
+}
+
+export interface UpdateUnifiedOrderPlanningRequest {
+  expectedVersion: number
+  expectedArrivalAt?: string | null
+  estimatedVolumeCbm?: number | null
+}
+
+function optionalText(value: string | null | undefined) {
+  const normalized = value?.trim()
+  return normalized || null
+}
+
+function queryParams(query: UnifiedOrderQuery) {
+  return Object.fromEntries(Object.entries(query).filter(([, value]) => value !== undefined && value !== ''))
+}
+
+function normalizeRow(raw: UnifiedOrderResource): UnifiedOrderResource {
+  return {
+    ...raw,
+    orderId: String(raw.orderId),
+    orderVersion: nullableInteger(raw.orderVersion),
+    tenantId: String(raw.tenantId),
+    customerId: id(raw.customerId),
+    channelCode: optionalText(raw.channelCode),
+    receivingWarehouseId: id(raw.receivingWarehouseId),
+    destinationWarehouseId: id(raw.destinationWarehouseId),
+    inboundId: id(raw.inboundId),
+    holdFlag: raw.holdFlag === null || raw.holdFlag === undefined ? null : Boolean(raw.holdFlag),
+    currentHoldReason: optionalText(raw.currentHoldReason),
+    inboundVersion: nullableInteger(raw.inboundVersion),
+    relation: raw.relation ? {
+      ...raw.relation,
+      rootOrderId: id(raw.relation.rootOrderId),
+      parentOrderId: id(raw.relation.parentOrderId),
+      splitSequence: nullableInteger(raw.relation.splitSequence),
+      childCount: integer(raw.relation.childCount, 0),
+    } : null,
+    totalPackageCount: nullableInteger(raw.totalPackageCount),
+    estimatedVolumeCbm: numberValue(raw.estimatedVolumeCbm),
+    expectedVolumeCbm: numberValue(raw.expectedVolumeCbm),
+    channelChanged: Boolean(raw.channelChanged),
+    actualGrossWeightKg: numberValue(raw.actualGrossWeightKg),
+    actualVolumeCbm: numberValue(raw.actualVolumeCbm),
+    totalPalletCount: nullableInteger(raw.totalPalletCount),
+    chargeableVolumeCbm: numberValue(raw.chargeableVolumeCbm),
+    volumetricWeightKg: numberValue(raw.volumetricWeightKg),
+    totalNetWeightKg: numberValue(raw.totalNetWeightKg),
+    totalQuantity: nullableInteger(raw.totalQuantity),
+    skuNos: raw.skuNos?.filter((value) => value.trim()) ?? null,
+    locationCodes: raw.locationCodes ?? raw.location ?? null,
+    measurement: raw.measurement ? {
+      ...raw.measurement,
+      actualGrossWeightKg: numberValue(raw.measurement.actualGrossWeightKg),
+      actualVolumeCbm: numberValue(raw.measurement.actualVolumeCbm),
+      chargeableWeightKg: numberValue(raw.measurement.chargeableWeightKg),
+    } : null,
+    preload: raw.preload ? { ...raw.preload, version: nullableInteger(raw.preload.version), itemCount: nullableInteger(raw.preload.itemCount) } : null,
+    loading: raw.loading ? {
+      ...raw.loading,
+      loadingVersion: nullableInteger(raw.loading.loadingVersion),
+      pickingVersion: nullableInteger(raw.loading.pickingVersion),
+      expectedCount: nullableInteger(raw.loading.expectedCount),
+      pickedCount: nullableInteger(raw.loading.pickedCount),
+      evidenceCount: nullableInteger(raw.loading.evidenceCount),
+    } : null,
+    transport: raw.transport ? { ...raw.transport } : null,
+    coLoadGroup: raw.coLoadGroup ? {
+      status: String(raw.coLoadGroup.status || ''),
+      memberCount: integer(raw.coLoadGroup.memberCount, 0),
+      memberInboundCodes: (raw.coLoadGroup.memberInboundCodes || [])
+        .map((value) => typeof value === 'string' ? value.trim() : '')
+        .filter(Boolean),
+    } : null,
+  }
+}
+
+export async function listPlatformUnifiedOrders(query: UnifiedOrderQuery) {
+  const response = await http.get<ApiEnvelope<PagePayload>, ApiEnvelope<PagePayload>>(unifiedOrdersApiPath, {
+    params: queryParams(query),
+  })
+  const result = unwrapApiResponse(response)
+  return {
+    ...result,
+    records: (result.records || []).map(normalizeRow),
+    page: integer(result.page, query.page),
+    size: integer(result.size, query.size),
+    total: integer(result.total, 0),
+    pages: integer(result.pages, 0),
+  } satisfies UnifiedOrderPageResource
+}
+
+export async function getPlatformUnifiedOrder(tenantId: string, orderId: string) {
+  const response = await http.get<ApiEnvelope<UnifiedOrderDetailResource>, ApiEnvelope<UnifiedOrderDetailResource>>(
+    `${unifiedOrdersApiPath}/${orderId}`,
+    { params: { tenantId } },
+  )
+  const result = unwrapApiResponse(response)
+  return {
+    ...result,
+    summary: normalizeRow(result.summary),
+    order: {
+      ...result.order,
+      order: result.order.order ? { ...result.order.order, version: nullableInteger(result.order.order.version) } : null,
+    },
+  }
+}
+
+export function updatePlatformUnifiedOrderDeclaration(
+  tenantId: string,
+  orderId: string,
+  request: UpdateUnifiedOrderDeclarationRequest,
+) {
+  return http.put<ApiEnvelope<UpdateUnifiedOrderDeclarationResult>, ApiEnvelope<UpdateUnifiedOrderDeclarationResult>>(
+    `${unifiedOrdersApiPath}/${orderId}/declaration`,
+    request,
+    { params: { tenantId } },
+  ).then(unwrapApiResponse)
+}
+
+export function updatePlatformUnifiedOrderPlanning(
+  tenantId: string,
+  orderId: string,
+  request: UpdateUnifiedOrderPlanningRequest,
+) {
+  return http.put<ApiEnvelope<UpdateUnifiedOrderDeclarationResult>, ApiEnvelope<UpdateUnifiedOrderDeclarationResult>>(
+    `${unifiedOrdersApiPath}/${orderId}/planning`,
+    request,
+    { params: { tenantId } },
+  ).then(unwrapApiResponse)
+}
+
+export function downloadPlatformProductImage(tenantId: string, fileId: string) {
+  return http.get<Blob, Blob>(
+    `/platform/v1/files/product-images/${encodeURIComponent(tenantId)}/${encodeURIComponent(fileId)}`,
+    { responseType: 'blob' },
+  )
+}
+
+export function approvePlatformUnifiedOrder(tenantId: string, orderId: string) {
+  return http.post<ApiEnvelope<void>, ApiEnvelope<void>>(
+    `/platform/v1/orders/first-leg/${orderId}/approve`,
+    undefined,
+    { params: { tenantId } },
+  ).then(unwrapApiResponse)
+}
+
+export interface UnifiedOrderBatchApprovalResult {
+  total: number
+  successCount: number
+  failureCount: number
+  successOrderIds: Array<number | string>
+  failedOrders: Array<{ orderId: number | string; code: string; message: string }>
+}
+
+export interface UnifiedOrderBatchReviewItem {
+  orderId: string
+  orderVersion: number
+}
+
+export interface UnifiedOrderBatchApprovalPreviewItem extends UnifiedOrderBatchReviewItem {
+  inboundCode: string | null
+  customerId: string | null
+  customerName: string | null
+  chineseGoodsNames: string[]
+  channelCode: string | null
+  channelName: string | null
+  destinationWarehouseCode: string | null
+  destinationWarehouseName: string | null
+  canApprove: boolean
+  blockReason: string | null
+}
+
+export interface UnifiedOrderBatchApprovalPreview {
+  total: number
+  approvableCount: number
+  items: UnifiedOrderBatchApprovalPreviewItem[]
+}
+
+function normalizeBatchApprovalPreview(result: UnifiedOrderBatchApprovalPreview): UnifiedOrderBatchApprovalPreview {
+  return {
+    ...result,
+    total: integer(result.total, 0),
+    approvableCount: integer(result.approvableCount, 0),
+    items: (result.items || []).map((item) => ({
+      ...item,
+      orderId: String(item.orderId),
+      orderVersion: integer(item.orderVersion, 0),
+      customerId: id(item.customerId),
+      chineseGoodsNames: (item.chineseGoodsNames || []).map((name) => name.trim()).filter(Boolean),
+      canApprove: Boolean(item.canApprove),
+    })),
+  }
+}
+
+export async function getPlatformUnifiedOrderBatchApprovalPreview(tenantId: string, items: UnifiedOrderBatchReviewItem[]) {
+  const response = await http.post<ApiEnvelope<UnifiedOrderBatchApprovalPreview>, ApiEnvelope<UnifiedOrderBatchApprovalPreview>>(
+    '/platform/v1/orders/first-leg/batch-review-preview',
+    { items },
+    { params: { tenantId } },
+  )
+  return normalizeBatchApprovalPreview(unwrapApiResponse(response))
+}
+
+export function batchApprovePlatformUnifiedOrders(tenantId: string, items: UnifiedOrderBatchReviewItem[]) {
+  return http.post<ApiEnvelope<UnifiedOrderBatchApprovalResult>, ApiEnvelope<UnifiedOrderBatchApprovalResult>>(
+    '/platform/v1/orders/first-leg/batch-approve',
+    { items },
+    { params: { tenantId } },
+  ).then(unwrapApiResponse)
+}
+
+export interface UnifiedOrderRemarksUpdateRequest {
+  expectedVersion: number
+  internalRemark: string | null
+  warehouseRemark: string | null
+  customerServiceRemark: string | null
+}
+
+export interface UnifiedOrderRemarksUpdateResponse {
+  version: number
+  customerRemark: string | null
+  internalRemark: string | null
+  warehouseRemark: string | null
+  customerServiceRemark: string | null
+}
+
+export function updatePlatformUnifiedOrderRemarks(tenantId: string, orderId: string, request: UnifiedOrderRemarksUpdateRequest) {
+  return http.put<ApiEnvelope<UnifiedOrderRemarksUpdateResponse>, ApiEnvelope<UnifiedOrderRemarksUpdateResponse>>(
+    `${unifiedOrdersApiPath}/${orderId}/remarks`,
+    request,
+    { params: { tenantId } },
+  ).then(unwrapApiResponse)
+}
+
+export async function listPlatformUnifiedOrderFeeDetails(accountId: string, inboundId: string) {
+  const response = await http.get<ApiEnvelope<UnifiedOrderFeeDetailResource[]>, ApiEnvelope<UnifiedOrderFeeDetailResource[]>>(
+    `/platform/v1/inbounds/${encodeURIComponent(inboundId)}/fee-details`,
+    { params: { accountId } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export function unifiedOrderStatusLabel(status: UnifiedOrderMainStatus) {
+  return unifiedOrderStatusOptions.find((item) => item.value === status)?.label || '未知状态'
+}
diff --git a/src/modules/unified-orders/components/InboundFeeDetailManager.test.ts b/src/modules/unified-orders/components/InboundFeeDetailManager.test.ts
new file mode 100644
index 00000000..74da0e97
--- /dev/null
+++ b/src/modules/unified-orders/components/InboundFeeDetailManager.test.ts
@@ -0,0 +1,290 @@
+import ElementPlus from 'element-plus'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { createPinia, setActivePinia } from 'pinia'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+import { ApiResponseError } from '@/shared/api/http'
+import {
+  adjustInboundFeeDetail, createInboundFeeDetail, deleteInboundFeeDetail,
+  listInboundFeeDetails, listInboundFeeItemOptions, listInboundFeeSupplierOptions,
+  reviewInboundFeeDetail, updateInboundFeeDetail, uploadInboundFeePaymentVoucher, voidInboundFeeDetail,
+} from '@/modules/unified-orders/api/inboundFeeDetails'
+import InboundFeeDetailManager from './InboundFeeDetailManager.vue'
+import type { InboundFeeDetail } from '@/modules/unified-orders/api/inboundFeeDetails'
+
+vi.mock('@/modules/unified-orders/api/inboundFeeDetails', () => ({
+  listInboundFeeDetails: vi.fn(), listInboundFeeItemOptions: vi.fn(), listInboundFeeSupplierOptions: vi.fn(),
+  createInboundFeeDetail: vi.fn(), updateInboundFeeDetail: vi.fn(), deleteInboundFeeDetail: vi.fn(),
+  reviewInboundFeeDetail: vi.fn(), adjustInboundFeeDetail: vi.fn(), uploadInboundFeePaymentVoucher: vi.fn(), voidInboundFeeDetail: vi.fn(),
+}))
+
+const pending: InboundFeeDetail = {
+  id: '11', inboundId: '88', feeItemId: '31', sourceType: 'MANUAL', sourceFeeVersion: 1,
+  inboundCode: 'RK-88', direction: 'RECEIVABLE', supplierId: null, supplierName: null, supplierCategory: null,
+  settlementMode: null, paidAt: null, paymentMethod: null, paymentReferenceNo: null, paymentVoucherFileIds: null,
+  businessDate: '2026-08-12', customerName: '测试客户', feeTypeNameSnapshot: '操作费',
+  unitPrice: 10, currency: 'CNY', amount: 100, remark: 'marker', reviewStatus: 'PENDING',
+  reviewReason: null, reviewerName: null, reviewedAt: null, publicationStatus: 'DRAFT',
+}
+const approved: InboundFeeDetail = { ...pending, id: '12', sourceFeeVersion: 3, reviewStatus: 'APPROVED', publicationStatus: 'PUBLISHED' }
+const source = readFileSync(join(process.cwd(), 'src/modules/unified-orders/components/InboundFeeDetailManager.vue'), 'utf8')
+
+enableAutoUnmount(afterEach)
+
+function mountManager(permissions: string[]) {
+  const pinia = createPinia(); setActivePinia(pinia)
+  const auth = useAuthStore(); auth.token = 'token'; auth.permissions = permissions
+  useAccessPreviewStore().initializeAfterLogin()
+  return mount(InboundFeeDetailManager, { attachTo: document.body, props: { accountId: '100', inboundId: '88' }, global: { plugins: [pinia, ElementPlus] } })
+}
+
+describe('InboundFeeDetailManager', () => {
+  beforeEach(() => {
+    vi.clearAllMocks(); document.body.innerHTML = ''
+    vi.mocked(listInboundFeeDetails).mockResolvedValue([pending, approved])
+    vi.mocked(listInboundFeeItemOptions).mockResolvedValue([{ id: '31', feeTypeName: '操作费', feeCode: 'OPERATION', supplierCategory: 'TRUCKING', warehouseReceivable: true, warehousePayable: true }])
+    vi.mocked(listInboundFeeSupplierOptions).mockResolvedValue([{ id: '41', supplierName: '测试供应商', category: 'TRUCKING' }])
+    vi.mocked(createInboundFeeDetail).mockResolvedValue(pending)
+    vi.mocked(updateInboundFeeDetail).mockResolvedValue(pending)
+    vi.mocked(adjustInboundFeeDetail).mockResolvedValue({ ...approved, reviewStatus: 'PENDING' })
+    vi.mocked(uploadInboundFeePaymentVoucher).mockResolvedValue({ fileId: '9001', fileName: '付款凭证.pdf' })
+    vi.mocked(reviewInboundFeeDetail).mockResolvedValue(null)
+    vi.mocked(deleteInboundFeeDetail).mockResolvedValue(null)
+    vi.mocked(voidInboundFeeDetail).mockResolvedValue(null)
+  })
+
+  it('renders actions from backend status and exact permissions', async () => {
+    const wrapper = mountManager(['firstleg:inbound:fee-detail:view', 'firstleg:inbound:fee-detail:edit', 'firstleg:inbound:fee-detail:delete', 'firstleg:inbound:fee-detail:review'])
+    await flushPromises()
+    expect(listInboundFeeDetails).toHaveBeenCalledWith('100', '88')
+    const first = wrapper.findAll('.el-table__row')[0]!.text()
+    const second = wrapper.findAll('.el-table__row')[1]!.text()
+    const secondButtons = wrapper.findAll('.el-table__row')[1]!.findAll('button').map((button) => button.text())
+    expect(first).toContain('编辑'); expect(first).toContain('审核'); expect(first).toContain('驳回')
+    expect(first).toContain('草稿')
+    expect(second).toContain('已发布')
+    expect(second).toContain('调整'); expect(second).toContain('作废'); expect(secondButtons).not.toContain('审核')
+    expect(wrapper.find('th').text()).toContain('操作')
+    expect(source).not.toMatch(/<el-button[^>]+link[^>]+(?:编辑|审核|驳回|调整|作废)/)
+    expect(wrapper.findAll('.el-table__row')[0]!.findAll('.density-actions button').map(button => button.attributes('data-tone'))).toEqual(['neutral', 'warning', 'warning', 'neutral'])
+    expect(wrapper.findAll('.el-table__row')[1]!.findAll('.density-actions button').map(button => button.attributes('data-tone'))).toEqual(['neutral', 'danger'])
+  })
+
+  it.each([
+    [[], [], false],
+    [['delete'], ['删除'], false],
+    [['edit', 'delete'], ['编辑', '删除'], false],
+    [['review', 'delete'], ['审核', '驳回', '删除'], false],
+    [['edit', 'review'], ['编辑', '审核', '驳回'], false],
+    [['edit', 'review', 'delete'], ['编辑', '审核', '驳回', ''], true],
+  ])('folds pending fee actions only when more than three are available: %j', async (actions, labels, overflow) => {
+    vi.mocked(listInboundFeeDetails).mockResolvedValue([pending])
+    const wrapper = mountManager(['firstleg:inbound:fee-detail:view', ...actions.map(action => 'firstleg:inbound:fee-detail:' + action)])
+    await flushPromises()
+    const row = wrapper.get('.el-table__row .density-actions')
+    expect(row.findAll('button').map(button => button.text().trim())).toEqual(labels)
+    expect(row.find('.el-dropdown').exists()).toBe(overflow)
+    if (overflow) expect(row.get('.el-dropdown button').attributes('aria-label')).toContain('操作费')
+  })
+
+  it.each(['编辑', '驳回'])('styles the native %s fee dialog at its own root', async action => {
+    const wrapper = mountManager(['firstleg:inbound:fee-detail:view', 'firstleg:inbound:fee-detail:edit', 'firstleg:inbound:fee-detail:review', 'firstleg:fee-item:view'])
+    await flushPromises()
+    await wrapper.get('.el-table__row .density-actions').findAll('button').find(button => button.text().trim() === action)!.trigger('click')
+    await flushPromises()
+    const dialog = document.querySelector<HTMLElement>('.el-dialog.admin-density-dialog')!
+    expect(dialog).not.toBeNull()
+    expect(dialog.querySelector('.density-form')).not.toBeNull()
+    expect(dialog.style.getPropertyValue('--el-dialog-width')).toBe(action === '编辑' ? 'min(680px, calc(100vw - 28px))' : 'min(560px, calc(100vw - 28px))')
+    if (action === '驳回') {
+      const confirm = [...dialog.querySelectorAll<HTMLButtonElement>('button')].find(button => button.textContent?.trim() === '确认驳回')!
+      confirm.click()
+      await flushPromises()
+      expect(reviewInboundFeeDetail).not.toHaveBeenCalled()
+      expect(dialog.querySelector('textarea')?.value).toBe('')
+    } else expect(dialog.textContent).toContain('业务发生日')
+  })
+
+  it('keeps FBA_PRICING rows derived and read-only regardless of write permissions', async () => {
+    vi.mocked(listInboundFeeDetails).mockResolvedValue([{ ...approved, sourceType: 'FBA_PRICING' }])
+    const wrapper = mountManager(['firstleg:inbound:fee-detail:view', 'firstleg:inbound:fee-detail:edit', 'firstleg:inbound:fee-detail:delete', 'firstleg:inbound:fee-detail:review'])
+    await flushPromises()
+    const row = wrapper.find('.el-table__row')
+    expect(row.text()).toContain('头程派生')
+    const buttons = row.findAll('button').map((button) => button.text())
+    for (const action of ['编辑', '审核', '驳回', '调整', '作废', '删除']) expect(buttons).not.toContain(action)
+  })
+
+  it('shows payable settlement meaning and a DIRECT_PAID summary without changing fee direction', async () => {
+    vi.mocked(listInboundFeeDetails).mockResolvedValue([{ ...pending, direction: 'PAYABLE', supplierId: '41', supplierName: '测试供应商', settlementMode: 'DIRECT_PAID', paidAt: '2026-08-12T10:00:00', paymentMethod: 'BANK_TRANSFER', paymentReferenceNo: 'BANK-11', paymentVoucherFileIds: ['9001'] }])
+    const wrapper = mountManager(['firstleg:inbound:fee-detail:view'])
+    await flushPromises()
+    expect(wrapper.text()).toContain('应付'); expect(wrapper.text()).toContain('已付成本'); expect(wrapper.text()).toContain('银行转账'); expect(wrapper.text()).toContain('BANK-11')
+  })
+
+  it('does not request or expose fee rows without view permission', async () => {
+    mountManager([]); await flushPromises()
+    expect(listInboundFeeDetails).not.toHaveBeenCalled()
+    expect(document.body.textContent).toContain('没有查看费用明细的权限')
+  })
+
+  it.each(['', ' ', 'null', 'undefined'])('does not request fee rows for invalid inboundId %j', async (inboundId) => {
+    const pinia = createPinia(); setActivePinia(pinia)
+    const auth = useAuthStore(); auth.token = 'token'; auth.permissions = ['firstleg:inbound:fee-detail:view']
+    useAccessPreviewStore().initializeAfterLogin()
+    mount(InboundFeeDetailManager, {
+      props: { accountId: '100', inboundId },
+      global: { plugins: [pinia, ElementPlus] },
+    })
+    await flushPromises()
+    expect(listInboundFeeDetails).not.toHaveBeenCalled()
+  })
+
+  it('approves a pending fee then refreshes rows and emits changed', async () => {
+    const wrapper = mountManager(['firstleg:inbound:fee-detail:view', 'firstleg:inbound:fee-detail:review'])
+    await flushPromises()
+    wrapper.findAll('button').find((button) => button.text().includes('审核'))?.trigger('click')
+    await flushPromises()
+    expect(reviewInboundFeeDetail).toHaveBeenCalledWith('100', '88', '11', 'approve')
+    expect(listInboundFeeDetails).toHaveBeenCalledTimes(2)
+    expect(wrapper.emitted('changed')).toHaveLength(1)
+  })
+
+  it('preserves request and trace IDs when a write fails', async () => {
+    vi.mocked(reviewInboundFeeDetail).mockRejectedValue(new ApiResponseError('状态冲突', 'A0409', 409, null, 'request-fee', 'trace-fee'))
+    const wrapper = mountManager(['firstleg:inbound:fee-detail:view', 'firstleg:inbound:fee-detail:review'])
+    await flushPromises()
+    wrapper.findAll('button').find((button) => button.text().includes('审核'))?.trigger('click')
+    await flushPromises()
+    expect(document.body.textContent).toContain('request-fee')
+    expect(document.body.textContent).toContain('trace-fee')
+  })
+
+  it('keeps currency fixed to CNY in the form and write payload', async () => {
+    const wrapper = mountManager(['firstleg:inbound:fee-detail:view', 'firstleg:inbound:fee-detail:edit', 'firstleg:fee-item:view'])
+    await flushPromises()
+    await wrapper.findAll('button').find((button) => button.text().includes('新增费用'))?.trigger('click')
+    await flushPromises()
+    const currency = document.querySelector<HTMLInputElement>('input[aria-label="货币 CNY"]')
+    expect(currency?.readOnly).toBe(true)
+    expect(currency?.value).toBe('CNY')
+  })
+
+  it('uses only the Element Plus table scroller without an outer horizontal scrollbar', async () => {
+    const wrapper = mountManager(['firstleg:inbound:fee-detail:view'])
+    await flushPromises()
+    expect(wrapper.find('.fee-table-shell').exists()).toBe(true)
+    expect(wrapper.find('.detail-table-wrap').exists()).toBe(false)
+    expect(source).toContain('<el-table :data="rows" border stripe')
+  })
+
+  it('spins only the refresh icon while fee rows are loading', () => {
+    expect(source).toContain('class="fee-refresh-button" circle aria-label="刷新费用明细"')
+    expect(source).toContain(':aria-busy="loading" :disabled="loading"')
+    expect(source).toContain(`<RefreshCw :size="16" :class="{ 'is-spinning': loading }" />`)
+    expect(source).not.toMatch(/aria-label="刷新费用明细"[^>]*:loading=/)
+    expect(source).toContain('@keyframes fee-refresh-spin')
+  })
+
+  it('loads RECEIVABLE fee items without requesting suppliers', async () => {
+    const wrapper = mountManager(['firstleg:inbound:fee-detail:view', 'firstleg:inbound:fee-detail:edit', 'firstleg:fee-item:view'])
+    await flushPromises()
+    await wrapper.findAll('button').find((button) => button.text().includes('新增费用'))?.trigger('click')
+    await flushPromises()
+    expect(listInboundFeeItemOptions).toHaveBeenCalledTimes(1)
+    expect(listInboundFeeSupplierOptions).not.toHaveBeenCalled()
+    expect(document.body.textContent).toContain('缺少供应商查看权限')
+    expect(document.body.textContent).toContain('应收费用不受影响')
+  })
+
+  it('does not expose the editor without fee-item view permission', async () => {
+    const wrapper = mountManager(['firstleg:inbound:fee-detail:view', 'firstleg:inbound:fee-detail:edit'])
+    await flushPromises()
+    expect(wrapper.findAll('button').some((button) => button.text().includes('新增费用'))).toBe(false)
+    expect(listInboundFeeItemOptions).not.toHaveBeenCalled()
+  })
+
+  it('keeps fee items usable but blocks payable save when the supplier request fails', async () => {
+    vi.mocked(listInboundFeeDetails).mockResolvedValue([{ ...pending, direction: 'PAYABLE', supplierId: '41', supplierName: '测试供应商', supplierCategory: 'TRUCKING', settlementMode: 'ON_ACCOUNT' }])
+    vi.mocked(listInboundFeeSupplierOptions).mockRejectedValue(new ApiResponseError('供应商不可用', 'A0403', 403, null, 'request-supplier', 'trace-supplier'))
+    const wrapper = mountManager([
+      'firstleg:inbound:fee-detail:view', 'firstleg:inbound:fee-detail:edit',
+      'firstleg:fee-item:view', 'platform:supplier:list',
+    ])
+    await flushPromises()
+    await wrapper.findAll('button').find((button) => button.text().includes('编辑'))?.trigger('click')
+    await flushPromises()
+    expect(listInboundFeeItemOptions).toHaveBeenCalledTimes(1)
+    expect(listInboundFeeSupplierOptions).toHaveBeenCalledWith('TRUCKING')
+    expect(document.body.textContent).toContain('当前账号无权访问该数据')
+    expect(document.body.textContent).toContain('A0403')
+    expect(document.body.textContent).toContain('request-supplier')
+    expect(document.body.textContent).toContain('trace-supplier')
+    expect(document.querySelector('.fee-form .el-select')?.classList.contains('is-disabled')).toBe(false)
+  })
+
+  it('allows any loaded ACTIVE supplier when a payable fee item has no supplier category', async () => {
+    vi.mocked(listInboundFeeItemOptions).mockResolvedValue([{ id: '31', feeTypeName: '未映射费用', feeCode: 'UNMAPPED', supplierCategory: null, warehouseReceivable: false, warehousePayable: true }])
+    vi.mocked(listInboundFeeSupplierOptions).mockResolvedValue([{ id: '41', supplierName: '测试供应商', category: 'CUSTOMS' }])
+    const wrapper = mountManager([
+      'firstleg:inbound:fee-detail:view', 'firstleg:inbound:fee-detail:edit',
+      'firstleg:fee-item:view', 'platform:supplier:list',
+    ])
+    await flushPromises()
+    await wrapper.findAll('button').find((button) => button.text().includes('新增费用'))?.trigger('click')
+    await flushPromises()
+    const state = (wrapper.vm.$ as unknown as { setupState: { save(): Promise<void>; form: { direction: string; feeItemId: string; supplierId: string | null; settlementMode: string | null; amount: number } } }).setupState
+    state.form.direction = 'PAYABLE'; state.form.feeItemId = '31'; await flushPromises(); state.form.supplierId = '41'; state.form.settlementMode = 'ON_ACCOUNT'; state.form.amount = 100
+    await state.save(); await flushPromises()
+    expect(listInboundFeeSupplierOptions).toHaveBeenCalledWith(null)
+    expect(createInboundFeeDetail).toHaveBeenCalledWith('100', '88', expect.objectContaining({ direction: 'PAYABLE', supplierId: '41', settlementMode: 'ON_ACCOUNT', paidAt: null, paymentMethod: null, paymentReferenceNo: null, paymentVoucherFileIds: null }))
+  })
+
+  it('clears settlement and paid fields when switching to RECEIVABLE or ON_ACCOUNT', async () => {
+    const wrapper = mountManager(['firstleg:inbound:fee-detail:view', 'firstleg:inbound:fee-detail:edit', 'firstleg:fee-item:view', 'platform:supplier:list'])
+    await flushPromises(); await wrapper.findAll('button').find((button) => button.text().includes('新增费用'))?.trigger('click'); await flushPromises()
+    const state = (wrapper.vm.$ as unknown as { setupState: { form: { direction: string; settlementMode: string | null; paidAt: string | null; paymentMethod: string | null; paymentReferenceNo: string | null; paymentVoucherFileIds: string[] | null } } }).setupState
+    Object.assign(state.form, { direction: 'PAYABLE', settlementMode: 'DIRECT_PAID', paidAt: '2026-08-12T10:00:00', paymentMethod: 'CASH', paymentReferenceNo: 'CASH-1', paymentVoucherFileIds: ['9001'] }); await flushPromises()
+    state.form.settlementMode = 'ON_ACCOUNT'; await flushPromises()
+    expect(state.form).toMatchObject({ settlementMode: 'ON_ACCOUNT', paidAt: null, paymentMethod: null, paymentReferenceNo: null, paymentVoucherFileIds: null })
+    state.form.direction = 'RECEIVABLE'; await flushPromises()
+    expect(state.form).toMatchObject({ direction: 'RECEIVABLE', settlementMode: null, paidAt: null, paymentMethod: null, paymentReferenceNo: null, paymentVoucherFileIds: null })
+  })
+
+  it('requires complete DIRECT_PAID evidence and submits uploaded voucher IDs only after scoped upload succeeds', async () => {
+    const wrapper = mountManager(['firstleg:inbound:fee-detail:view', 'firstleg:inbound:fee-detail:edit', 'firstleg:fee-item:view', 'platform:supplier:list'])
+    await flushPromises(); await wrapper.findAll('button').find((button) => button.text().includes('新增费用'))?.trigger('click'); await flushPromises()
+    const state = (wrapper.vm.$ as unknown as { setupState: { save(): Promise<void>; selectVoucher(event: Event): Promise<void>; form: { direction: string; feeItemId: string; supplierId: string | null; settlementMode: string | null; paidAt: string | null; paymentMethod: string | null; paymentReferenceNo: string | null; amount: number } } }).setupState
+    Object.assign(state.form, { direction: 'PAYABLE', feeItemId: '31' }); await flushPromises()
+    Object.assign(state.form, { supplierId: '41', settlementMode: 'DIRECT_PAID', paidAt: '2026-08-12T10:00:00', paymentMethod: 'BANK_TRANSFER', paymentReferenceNo: null, amount: 100 }); await flushPromises()
+    await state.save(); expect(createInboundFeeDetail).not.toHaveBeenCalled()
+    const input = document.createElement('input'); Object.defineProperty(input, 'files', { value: [new File(['x'], '付款凭证.pdf')] })
+    await state.selectVoucher({ target: input } as unknown as Event); await state.save()
+    expect(uploadInboundFeePaymentVoucher).toHaveBeenCalledWith('100', expect.objectContaining({ name: '付款凭证.pdf' }))
+    expect(createInboundFeeDetail).toHaveBeenCalledWith('100', '88', expect.objectContaining({ settlementMode: 'DIRECT_PAID', paymentMethod: 'BANK_TRANSFER', paymentVoucherFileIds: ['9001'] }))
+  })
+
+  it('keeps DIRECT_PAID save closed and exposes feedback when voucher upload fails', async () => {
+    vi.mocked(uploadInboundFeePaymentVoucher).mockRejectedValue(new ApiResponseError('File服务不可用', 'A0503', 503, null, 'request-file', 'trace-file'))
+    const wrapper = mountManager(['firstleg:inbound:fee-detail:view', 'firstleg:inbound:fee-detail:edit', 'firstleg:fee-item:view', 'platform:supplier:list'])
+    await flushPromises(); await wrapper.findAll('button').find((button) => button.text().includes('新增费用'))?.trigger('click'); await flushPromises()
+    const state = (wrapper.vm.$ as unknown as { setupState: { save(): Promise<void>; selectVoucher(event: Event): Promise<void>; form: { direction: string; feeItemId: string; supplierId: string | null; settlementMode: string | null; paidAt: string | null; paymentMethod: string | null; paymentReferenceNo: string | null; amount: number } } }).setupState
+    Object.assign(state.form, { direction: 'PAYABLE', feeItemId: '31' }); await flushPromises()
+    Object.assign(state.form, { supplierId: '41', settlementMode: 'DIRECT_PAID', paidAt: '2026-08-12T10:00:00', paymentMethod: 'ONLINE', paymentReferenceNo: 'ONLINE-1', amount: 100 }); await flushPromises()
+    const input = document.createElement('input'); Object.defineProperty(input, 'files', { value: [new File(['x'], '失败凭证.png')] })
+    await state.selectVoucher({ target: input } as unknown as Event); await state.save(); await flushPromises()
+    expect(createInboundFeeDetail).not.toHaveBeenCalled(); expect(document.body.textContent).toContain('request-file'); expect(document.body.textContent).toContain('trace-file')
+  })
+
+  it('refreshes fee rows and the order detail after every successful write', () => {
+    expect(source).toMatch(/async function finishAction\(message: string\) \{\r?\n  await load\(\); emit\('changed'\)/)
+    expect(source).toMatch(/createInboundFeeDetail[\s\S]*updateInboundFeeDetail[\s\S]*adjustInboundFeeDetail[\s\S]*await finishAction\(/)
+    expect(source).toMatch(/deleteInboundFeeDetail[\s\S]*await finishAction\('费用明细已删除'\)/)
+    expect(source).toMatch(/reviewInboundFeeDetail[\s\S]*await finishAction\('费用审核通过'\)/)
+    expect(source).toMatch(/reviewInboundFeeDetail[\s\S]*rejectReason[\s\S]*await finishAction\('费用已驳回'\)/)
+    expect(source).toMatch(/voidInboundFeeDetail[\s\S]*await finishAction\('费用明细已作废'\)/)
+  })
+})
diff --git a/src/modules/unified-orders/components/InboundFeeDetailManager.vue b/src/modules/unified-orders/components/InboundFeeDetailManager.vue
new file mode 100644
index 00000000..c1b3f520
--- /dev/null
+++ b/src/modules/unified-orders/components/InboundFeeDetailManager.vue
@@ -0,0 +1,378 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, reactive, ref, watch } from 'vue'
+import { ElMessage, ElMessageBox, type FormInstance, type FormRules } from 'element-plus'
+import { FileUp, MoreHorizontal, Plus, RefreshCw, X } from '@lucide/vue'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import {
+  adjustInboundFeeDetail, createInboundFeeDetail, deleteInboundFeeDetail,
+  listInboundFeeDetails, listInboundFeeItemOptions, listInboundFeeSupplierOptions,
+  reviewInboundFeeDetail, updateInboundFeeDetail, uploadInboundFeePaymentVoucher, voidInboundFeeDetail,
+} from '@/modules/unified-orders/api/inboundFeeDetails'
+import type {
+  InboundFeeDetail, InboundFeeItemOption,
+  InboundFeeSupplierOption, SaveInboundFeeDetailRequest,
+} from '@/modules/unified-orders/api/inboundFeeDetails'
+
+const props = defineProps<{ accountId: string; inboundId: string; destinationType?: string | null }>()
+interface OtherFeeSummary { currency: string; approvedReceivable: number; approvedPayable: number }
+const emit = defineEmits<{ changed: []; summary: [value: OtherFeeSummary] }>()
+const access = useAccessPreviewStore()
+const rows = ref<InboundFeeDetail[]>([])
+const feeItems = ref<InboundFeeItemOption[]>([])
+const suppliers = ref<InboundFeeSupplierOption[]>([])
+const feeItemsLoading = ref(false)
+const suppliersLoading = ref(false)
+const loadedSupplierCategory = ref<string | null | undefined>(undefined)
+const feeItemsError = ref<ApiErrorDetails | null>(null)
+const suppliersError = ref<ApiErrorDetails | null>(null)
+const loading = ref(false)
+const saving = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const actionError = ref<ApiErrorDetails | null>(null)
+const editorOpen = ref(false)
+const editorMode = ref<'create' | 'edit' | 'adjust'>('create')
+const target = ref<InboundFeeDetail | null>(null)
+const formRef = ref<FormInstance>()
+const rejectOpen = ref(false)
+const rejectReason = ref('')
+const voucherFiles = ref<Array<{ fileId: string; fileName: string }>>([])
+const voucherUploading = ref(false)
+const voucherError = ref<ApiErrorDetails | null>(null)
+let supplierLoadSequence = 0
+
+const emptyForm = (): SaveInboundFeeDetailRequest => ({
+  feeItemId: '', direction: 'RECEIVABLE', businessDate: new Date().toISOString().slice(0, 10),
+  unitPrice: 0, currency: 'CNY', amount: 0,
+  supplierId: null, settlementMode: null, paidAt: null, paymentMethod: null,
+  paymentReferenceNo: null, paymentVoucherFileIds: null, remark: null,
+})
+const form = reactive<SaveInboundFeeDetailRequest>(emptyForm())
+const settlementModeModel = computed<string>({
+  get: () => form.settlementMode ?? '',
+  set: (value) => { form.settlementMode = value === 'ON_ACCOUNT' || value === 'DIRECT_PAID' ? value : null },
+})
+const rules: FormRules = {
+  feeItemId: [{ required: true, message: '请选择费用项目', trigger: 'change' }],
+  businessDate: [{ required: true, message: '请选择业务发生日', trigger: 'change' }],
+  unitPrice: [{ required: true, type: 'number', min: 0, message: '单价不能小于 0', trigger: 'change' }],
+  amount: [{ required: true, type: 'number', min: 0, message: '金额不能小于 0', trigger: 'change' }],
+  currency: [{ required: true, pattern: /^[A-Z]{3}$/, message: '货币须为三个大写字母', trigger: 'blur' }],
+}
+const canView = computed(() => access.can('firstleg:inbound:fee-detail:view'))
+const normalizedInboundId = computed(() => {
+  const identifier = String(props.inboundId ?? '').trim()
+  return identifier && identifier !== 'null' && identifier !== 'undefined' ? identifier : ''
+})
+const canViewFeeItems = computed(() => access.can('firstleg:fee-item:view'))
+const canViewSuppliers = computed(() => access.can('platform:supplier:list'))
+const directionOptions = computed(() => [
+  { label: '应收', value: 'RECEIVABLE' },
+  { label: '应付', value: 'PAYABLE', disabled: !canViewSuppliers.value },
+])
+const privateDeliveryFeeCode = 'PRIVATE_LAST_MILE_DELIVERY'
+const applicableItems = computed(() => feeItems.value.filter((item) => {
+  if (item.feeCode === privateDeliveryFeeCode && props.destinationType !== 'PRIVATE') return false
+  return form.direction === 'RECEIVABLE' ? item.warehouseReceivable : item.warehousePayable
+}))
+const selectedFeeItem = computed(() => feeItems.value.find((item) => String(item.id) === String(form.feeItemId)))
+
+function isManual(row: InboundFeeDetail) { return row.sourceType === 'MANUAL' }
+function canEdit(row: InboundFeeDetail) { return isManual(row) && access.can('firstleg:inbound:fee-detail:edit') && row.reviewStatus === 'PENDING' }
+function canDelete(row: InboundFeeDetail) { return isManual(row) && access.can('firstleg:inbound:fee-detail:delete') && row.reviewStatus === 'PENDING' }
+function canReview(row: InboundFeeDetail) { return isManual(row) && access.can('firstleg:inbound:fee-detail:review') && row.reviewStatus === 'PENDING' }
+function canAdjust(row: InboundFeeDetail) { return isManual(row) && access.can('firstleg:inbound:fee-detail:edit') && row.reviewStatus === 'APPROVED' && row.publicationStatus !== 'VOIDED' }
+function canVoid(row: InboundFeeDetail) { return isManual(row) && access.can('firstleg:inbound:fee-detail:review') && row.reviewStatus === 'APPROVED' && row.publicationStatus !== 'VOIDED' }
+function rowActionCount(row: InboundFeeDetail) {
+  return Number(canEdit(row)) + 2 * Number(canReview(row)) + Number(canAdjust(row)) + Number(canVoid(row)) + Number(canDelete(row))
+}
+function reviewLabel(value: string) { return ({ PENDING: '待审核', APPROVED: '已审核', REJECTED: '已驳回' } as Record<string, string>)[value] || value }
+function publicationLabel(value: string) {
+  return ({ DRAFT: '草稿', PUBLISHED: '已发布', SUPERSEDED: '已被替代', VOIDED: '已作废' } as Record<string, string>)[value] || value || '未知状态'
+}
+function directionLabel(value: string) { return value === 'RECEIVABLE' ? '应收' : '应付' }
+function settlementLabel(row: InboundFeeDetail) { return row.direction !== 'PAYABLE' ? '—' : row.settlementMode === 'DIRECT_PAID' ? '已付成本' : row.settlementMode === 'ON_ACCOUNT' ? '账期应付' : '未设置' }
+function paymentMethodLabel(value: string | null | undefined) { return ({ ONLINE: '线上支付', BANK_TRANSFER: '银行转账', CASH: '现金', OTHER: '其他' } as Record<string, string>)[value || ''] || '—' }
+function paidSummary(row: InboundFeeDetail) {
+  if (row.settlementMode !== 'DIRECT_PAID') return '—'
+  const evidence = row.paymentReferenceNo || (row.paymentVoucherFileIds?.length ? `${row.paymentVoucherFileIds.length} 个凭证` : '凭证缺失')
+  return `${row.paidAt?.replace('T', ' ').slice(0, 16) || '时间缺失'} · ${paymentMethodLabel(row.paymentMethod)} · ${evidence}`
+}
+function clearPaidFields() {
+  form.paidAt = null; form.paymentMethod = null; form.paymentReferenceNo = null; form.paymentVoucherFileIds = null
+  voucherFiles.value = []; voucherError.value = null
+}
+
+async function load() {
+  if (!canView.value || !normalizedInboundId.value) {
+    rows.value = []
+    return
+  }
+  loading.value = true; loadError.value = null
+  try {
+    rows.value = await listInboundFeeDetails(props.accountId, normalizedInboundId.value)
+    const approved = rows.value.filter((row) => isManual(row) && row.reviewStatus === 'APPROVED' && row.publicationStatus !== 'VOIDED')
+    emit('summary', {
+      currency: approved.find((row) => row.currency)?.currency || 'CNY',
+      approvedReceivable: approved.filter((row) => row.direction === 'RECEIVABLE').reduce((sum, row) => sum + Number(row.amount || 0), 0),
+      approvedPayable: approved.filter((row) => row.direction === 'PAYABLE').reduce((sum, row) => sum + Number(row.amount || 0), 0),
+    })
+  }
+  catch (error) { loadError.value = getApiErrorDetails(error, '费用明细加载失败') }
+  finally { loading.value = false }
+}
+
+async function loadFeeItems() {
+  if (!canViewFeeItems.value || feeItemsLoading.value) return
+  feeItemsLoading.value = true; feeItemsError.value = null
+  try { feeItems.value = await listInboundFeeItemOptions() }
+  catch (error) { feeItemsError.value = getApiErrorDetails(error, '费用项目加载失败') }
+  finally { feeItemsLoading.value = false }
+}
+
+async function loadSuppliers() {
+  const sequence = ++supplierLoadSequence
+  const item = selectedFeeItem.value
+  suppliers.value = []; loadedSupplierCategory.value = undefined; suppliersError.value = null
+  if (!canViewSuppliers.value || form.direction !== 'PAYABLE' || !item) return
+  const requestedCategory = item.supplierCategory
+  suppliersLoading.value = true
+  try {
+    const result = await listInboundFeeSupplierOptions(requestedCategory)
+    if (sequence === supplierLoadSequence && form.direction === 'PAYABLE' && selectedFeeItem.value?.supplierCategory === requestedCategory) {
+      suppliers.value = result
+      loadedSupplierCategory.value = requestedCategory
+    }
+  }
+  catch (error) { if (sequence === supplierLoadSequence) suppliersError.value = getApiErrorDetails(error, '供应商加载失败') }
+  finally { if (sequence === supplierLoadSequence) suppliersLoading.value = false }
+}
+
+function assignForm(row?: InboundFeeDetail) {
+  Object.assign(form, row ? {
+    feeItemId: row.feeItemId, direction: row.direction, businessDate: row.businessDate,
+    unitPrice: Number(row.unitPrice), currency: row.currency, amount: Number(row.amount),
+    supplierId: row.supplierId, settlementMode: row.settlementMode ?? null, paidAt: row.paidAt ?? null,
+    paymentMethod: row.paymentMethod ?? null, paymentReferenceNo: row.paymentReferenceNo ?? null,
+    paymentVoucherFileIds: row.paymentVoucherFileIds ?? null, remark: row.remark,
+  } : emptyForm())
+  voucherFiles.value = (row?.paymentVoucherFileIds || []).map((fileId) => ({ fileId: String(fileId), fileName: `凭证 ${String(fileId)}` }))
+  voucherError.value = null
+}
+
+async function openEditor(mode: 'create' | 'edit' | 'adjust', row?: InboundFeeDetail) {
+  editorMode.value = mode; target.value = row || null; assignForm(row); actionError.value = null
+  feeItemsError.value = null; suppliersError.value = null
+  editorOpen.value = true
+  if (!feeItems.value.length) await loadFeeItems()
+  if (form.direction === 'PAYABLE') await loadSuppliers()
+}
+
+function normalizePayload(): SaveInboundFeeDetailRequest {
+  const directPaid = form.direction === 'PAYABLE' && form.settlementMode === 'DIRECT_PAID'
+  return { ...form, currency: 'CNY', supplierId: form.direction === 'PAYABLE' ? form.supplierId : null,
+    settlementMode: form.direction === 'PAYABLE' ? form.settlementMode : null,
+    paidAt: directPaid ? form.paidAt : null, paymentMethod: directPaid ? form.paymentMethod : null,
+    paymentReferenceNo: directPaid ? form.paymentReferenceNo?.trim() || null : null,
+    paymentVoucherFileIds: directPaid && voucherFiles.value.length ? voucherFiles.value.map((item) => item.fileId) : null,
+    remark: form.remark?.trim() || null }
+}
+
+async function selectVoucher(event: Event) {
+  const input = event.target as HTMLInputElement
+  const file = input.files?.[0]
+  input.value = ''
+  if (!file || voucherUploading.value) return
+  if (voucherFiles.value.length >= 20) { voucherError.value = { message: '付款凭证最多上传 20 个' }; return }
+  voucherUploading.value = true; voucherError.value = null
+  try {
+    const uploaded = await uploadInboundFeePaymentVoucher(props.accountId, file)
+    if (!voucherFiles.value.some((item) => item.fileId === uploaded.fileId)) voucherFiles.value.push(uploaded)
+    form.paymentVoucherFileIds = voucherFiles.value.map((item) => item.fileId)
+  } catch (error) { voucherError.value = getApiErrorDetails(error, '付款凭证上传或校验失败') }
+  finally { voucherUploading.value = false }
+}
+function removeVoucher(fileId: string) {
+  voucherFiles.value = voucherFiles.value.filter((item) => item.fileId !== fileId)
+  form.paymentVoucherFileIds = voucherFiles.value.length ? voucherFiles.value.map((item) => item.fileId) : null
+}
+
+async function finishAction(message: string) {
+  await load(); emit('changed'); ElMessage.success(message)
+}
+
+async function save() {
+  if (!await formRef.value?.validate()) return
+  if (!canViewFeeItems.value) { actionError.value = { message: '当前账号缺少费用项目查看权限，无法保存费用' }; return }
+  const selectedItem = feeItems.value.find((item) => String(item.id) === String(form.feeItemId))
+  if (form.direction === 'PAYABLE' && !canViewSuppliers.value) { actionError.value = { message: '当前账号缺少供应商查看权限，无法维护应付费用' }; return }
+  if (form.direction === 'PAYABLE' && suppliersError.value) { actionError.value = { message: '供应商列表加载失败，无法校验应付费用供应商' }; return }
+  if (form.direction === 'PAYABLE' && loadedSupplierCategory.value !== selectedItem?.supplierCategory) { actionError.value = { message: '供应商候选尚未按费用项目类别加载完成，无法保存' }; return }
+  if (form.direction === 'PAYABLE' && !form.supplierId) { actionError.value = { message: '应付费用必须选择供应商' }; return }
+  const selectedSupplier = suppliers.value.find((supplier) => supplier.id === String(form.supplierId))
+  if (form.direction === 'PAYABLE' && (!selectedSupplier || (selectedItem?.supplierCategory && selectedSupplier.category !== selectedItem.supplierCategory))) { actionError.value = { message: '所选供应商与费用项目要求的供应商类别不匹配' }; return }
+  if (form.direction === 'PAYABLE' && !form.settlementMode) { actionError.value = { message: '应付费用必须选择结算方式' }; return }
+  if (voucherUploading.value || voucherError.value) { actionError.value = { message: voucherUploading.value ? '付款凭证正在上传，请稍候' : '付款凭证上传或校验失败，请处理后再保存' }; return }
+  if (form.settlementMode === 'DIRECT_PAID' && (!form.paidAt || !form.paymentMethod || (!form.paymentReferenceNo?.trim() && !voucherFiles.value.length))) {
+    actionError.value = { message: '直接已付必须填写已付时间、付款方式，并提供流水号或付款凭证' }; return
+  }
+  saving.value = true; actionError.value = null
+  try {
+    const payload = normalizePayload()
+    if (editorMode.value === 'create') await createInboundFeeDetail(props.accountId, normalizedInboundId.value, payload)
+    else if (editorMode.value === 'edit' && target.value) await updateInboundFeeDetail(props.accountId, normalizedInboundId.value, String(target.value.id), payload)
+    else if (target.value) await adjustInboundFeeDetail(props.accountId, normalizedInboundId.value, String(target.value.id), target.value.sourceFeeVersion, payload)
+    editorOpen.value = false
+    await finishAction(editorMode.value === 'adjust' ? '费用调整已提交审核' : '费用明细已保存')
+  } catch (error) { actionError.value = getApiErrorDetails(error, '费用明细保存失败') }
+  finally { saving.value = false }
+}
+
+async function remove(row: InboundFeeDetail) {
+  try {
+    await ElMessageBox.confirm('删除后无法恢复，是否继续？', '删除费用明细', { customClass: 'admin-density-confirm', type: 'warning', confirmButtonText: '删除' })
+    await deleteInboundFeeDetail(props.accountId, normalizedInboundId.value, String(row.id)); await finishAction('费用明细已删除')
+  } catch (error) { if (error !== 'cancel' && error !== 'close') actionError.value = getApiErrorDetails(error, '费用明细删除失败') }
+}
+
+async function approve(row: InboundFeeDetail) {
+  try { await reviewInboundFeeDetail(props.accountId, normalizedInboundId.value, String(row.id), 'approve'); await finishAction('费用审核通过') }
+  catch (error) { actionError.value = getApiErrorDetails(error, '费用审核失败') }
+}
+
+function openReject(row: InboundFeeDetail) { target.value = row; rejectReason.value = ''; actionError.value = null; rejectOpen.value = true }
+async function reject() {
+  if (!target.value || !rejectReason.value.trim()) { actionError.value = { message: '请填写驳回原因' }; return }
+  saving.value = true
+  try { await reviewInboundFeeDetail(props.accountId, normalizedInboundId.value, String(target.value.id), 'reject', rejectReason.value.trim()); rejectOpen.value = false; await finishAction('费用已驳回') }
+  catch (error) { actionError.value = getApiErrorDetails(error, '费用驳回失败') }
+  finally { saving.value = false }
+}
+
+async function voidRow(row: InboundFeeDetail) {
+  try {
+    await ElMessageBox.confirm('作废会同步撤销尚未结算的财务费用来源，是否继续？', '作废费用明细', { customClass: 'admin-density-confirm', type: 'warning', confirmButtonText: '作废' })
+    await voidInboundFeeDetail(props.accountId, normalizedInboundId.value, String(row.id), row.sourceFeeVersion); await finishAction('费用明细已作废')
+  } catch (error) { if (error !== 'cancel' && error !== 'close') actionError.value = getApiErrorDetails(error, '费用作废失败') }
+}
+
+watch(() => [props.accountId, normalizedInboundId.value], () => void load())
+watch(() => form.direction, (direction) => {
+  if (direction === 'RECEIVABLE') { supplierLoadSequence += 1; form.supplierId = null; form.settlementMode = null; clearPaidFields(); suppliers.value = []; loadedSupplierCategory.value = undefined; suppliersError.value = null; suppliersLoading.value = false }
+  else void loadSuppliers()
+})
+watch(() => form.settlementMode, (mode) => { if (mode !== 'DIRECT_PAID') clearPaidFields() })
+watch(() => form.feeItemId, () => { form.supplierId = null; suppliers.value = []; loadedSupplierCategory.value = undefined; suppliersError.value = null; if (form.direction === 'PAYABLE') void loadSuppliers() })
+onMounted(() => void load())
+</script>
+
+<template>
+  <section class="fee-detail-manager admin-density" aria-label="运单费用维护">
+    <div class="fee-toolbar">
+      <span>共 {{ rows.length }} 条应收应付费用明细</span>
+      <div>
+        <el-tooltip content="刷新费用明细" placement="top"><el-button class="fee-refresh-button" circle aria-label="刷新费用明细" :aria-busy="loading" :disabled="loading" @click="load"><RefreshCw :size="16" :class="{ 'is-spinning': loading }" /></el-button></el-tooltip>
+        <el-button v-if="access.can('firstleg:inbound:fee-detail:edit') && canViewFeeItems" type="primary" @click="openEditor('create')"><Plus :size="16" />新增费用</el-button>
+      </div>
+    </div>
+    <el-alert v-if="!canView" title="当前账号没有查看费用明细的权限" type="warning" :closable="false" show-icon />
+    <LoadErrorState v-else-if="loadError" title="费用明细加载失败" :message="loadError.message" :loading="loading" @retry="load"><template #details><ApiErrorMeta :details="loadError" /></template></LoadErrorState>
+    <template v-else>
+      <el-alert v-if="actionError && !editorOpen && !rejectOpen" type="error" :closable="true" @close="actionError = null"><template #title>{{ actionError.message }}</template><ApiErrorMeta :details="actionError" /></el-alert>
+      <div v-loading="loading" class="fee-table-shell">
+        <el-table :data="rows" border stripe empty-text="暂无费用数据" row-key="id">
+          <el-table-column label="操作" fixed="left" width="250">
+            <template #default="{ row }">
+              <div class="density-actions">
+                <el-button v-if="canEdit(row as InboundFeeDetail)" class="density-action" data-tone="neutral" @click="openEditor('edit', row as InboundFeeDetail)">编辑</el-button>
+                <el-button v-if="canReview(row as InboundFeeDetail)" class="density-action" data-tone="warning" @click="approve(row as InboundFeeDetail)">审核</el-button>
+                <el-button v-if="canReview(row as InboundFeeDetail)" class="density-action" data-tone="warning" @click="openReject(row as InboundFeeDetail)">驳回</el-button>
+                <el-button v-if="canAdjust(row as InboundFeeDetail)" class="density-action" data-tone="neutral" @click="openEditor('adjust', row as InboundFeeDetail)">调整</el-button>
+                <el-button v-if="canVoid(row as InboundFeeDetail)" class="density-action" data-tone="danger" @click="voidRow(row as InboundFeeDetail)">作废</el-button>
+                <el-button v-if="canDelete(row as InboundFeeDetail) && rowActionCount(row as InboundFeeDetail) <= 3" class="density-action" data-tone="danger" @click="remove(row as InboundFeeDetail)">删除</el-button>
+                <el-dropdown v-if="canDelete(row as InboundFeeDetail) && rowActionCount(row as InboundFeeDetail) > 3" trigger="click">
+                  <el-button class="density-action" data-tone="neutral" :aria-label="(row.feeTypeNameSnapshot || '当前费用') + '的更多操作'" title="更多操作"><MoreHorizontal aria-hidden="true" :size="15" /></el-button>
+                  <template #dropdown><el-dropdown-menu>
+                    <el-dropdown-item @click="remove(row as InboundFeeDetail)">删除</el-dropdown-item>
+                  </el-dropdown-menu></template>
+                </el-dropdown>
+              </div>
+            </template>
+          </el-table-column>
+          <el-table-column label="审核状态" width="120"><template #default="{ row }"><StatusBadge :status="reviewLabel(row.reviewStatus)" /></template></el-table-column>
+          <el-table-column label="来源" width="120"><template #default="{ row }">{{ row.sourceType === 'FBA_PRICING' ? '头程派生' : '人工录入' }}</template></el-table-column>
+          <el-table-column label="应收/应付" width="110"><template #default="{ row }">{{ directionLabel(row.direction) }}</template></el-table-column>
+          <el-table-column label="结算方式" width="120"><template #default="{ row }">{{ settlementLabel(row as InboundFeeDetail) }}</template></el-table-column>
+          <el-table-column label="已付摘要" min-width="290" show-overflow-tooltip><template #default="{ row }">{{ paidSummary(row as InboundFeeDetail) }}</template></el-table-column>
+          <el-table-column label="费用类型" min-width="190" show-overflow-tooltip><template #default="{ row }"><span>{{ row.feeTypeNameSnapshot }}</span><el-tag v-if="row.feeTypeNameSnapshot === '私人仓尾程派送费'" class="private-delivery-tag" size="small" type="warning" effect="light">仅私人仓</el-tag></template></el-table-column>
+          <el-table-column label="供应商/客户" min-width="170"><template #default="{ row }">{{ row.direction === 'PAYABLE' ? row.supplierName : row.customerName || '—' }}</template></el-table-column>
+          <el-table-column prop="businessDate" label="业务发生日" width="130" />
+          <el-table-column prop="currency" label="货币" width="90" />
+          <el-table-column label="金额" min-width="120"><template #default="{ row }">{{ Number(row.amount).toFixed(2) }}</template></el-table-column>
+          <el-table-column label="单价" min-width="110"><template #default="{ row }">{{ Number(row.unitPrice).toFixed(4) }}</template></el-table-column>
+          <el-table-column prop="sourceFeeVersion" label="版本" width="85" />
+          <el-table-column label="发布状态" min-width="110"><template #default="{ row }"><StatusBadge :status="publicationLabel(row.publicationStatus)" /></template></el-table-column>
+          <el-table-column prop="reviewReason" label="驳回原因" min-width="180" show-overflow-tooltip />
+          <el-table-column prop="remark" label="备注" min-width="180" show-overflow-tooltip />
+        </el-table>
+      </div>
+    </template>
+
+    <AppDialog class="admin-density-dialog" v-model="editorOpen" :title="editorMode === 'create' ? '新增费用' : editorMode === 'adjust' ? '调整已审核费用' : '编辑费用'" width="min(680px, calc(100vw - 28px))" :confirm-loading="saving" confirm-text="保存" @confirm="save">
+      <el-alert v-if="editorMode === 'adjust'" title="调整将生成新版本并重新进入待审核状态" type="warning" :closable="false" show-icon />
+      <el-alert v-if="selectedFeeItem?.feeCode === privateDeliveryFeeCode" title="私人仓尾程派送费仅适用于目的仓类型为“私人仓”的订单，最终资格由服务端校验。" type="info" :closable="false" show-icon />
+      <el-alert v-if="!canViewFeeItems" title="当前账号缺少费用项目查看权限，无法新增或修改费用" type="warning" :closable="false" show-icon />
+      <el-alert v-if="!canViewSuppliers" title="当前账号缺少供应商查看权限，应付费用不可维护；应收费用不受影响" type="warning" :closable="false" show-icon />
+      <el-alert v-if="feeItemsError" type="error" :closable="true" @close="feeItemsError = null"><template #title>{{ feeItemsError.message }}</template><ApiErrorMeta :details="feeItemsError" /></el-alert>
+      <el-alert v-if="suppliersError" type="error" :closable="true" @close="suppliersError = null"><template #title>{{ suppliersError.message }}</template><ApiErrorMeta :details="suppliersError" /></el-alert>
+      <el-alert v-if="actionError" type="error" :closable="true" @close="actionError = null"><template #title>{{ actionError.message }}</template><ApiErrorMeta :details="actionError" /></el-alert>
+      <el-form ref="formRef" :model="form" :rules="rules" label-position="top" class="fee-form density-form">
+        <el-form-item label="应收/应付" prop="direction"><el-segmented v-model="form.direction" :options="directionOptions" /></el-form-item>
+        <el-form-item label="费用项目" prop="feeItemId"><el-select v-model="form.feeItemId" filterable :loading="feeItemsLoading" :disabled="!canViewFeeItems"><el-option v-for="item in applicableItems" :key="item.id" :label="item.feeTypeName" :value="item.id" /></el-select></el-form-item>
+        <el-form-item v-if="form.direction === 'PAYABLE'" label="供应商" required><el-select v-model="form.supplierId" filterable :loading="suppliersLoading" :disabled="!canViewSuppliers || !selectedFeeItem || !!suppliersError" placeholder="请先选择费用项目"><el-option v-for="supplier in suppliers" :key="supplier.id" :label="supplier.supplierName" :value="supplier.id" /></el-select></el-form-item>
+        <el-form-item v-if="form.direction === 'PAYABLE'" label="结算方式" required><el-radio-group v-model="settlementModeModel"><el-radio-button value="ON_ACCOUNT">账期应付</el-radio-button><el-radio-button value="DIRECT_PAID">已付成本</el-radio-button></el-radio-group></el-form-item>
+        <template v-if="form.direction === 'PAYABLE' && form.settlementMode === 'DIRECT_PAID'">
+          <el-form-item label="已付时间" required><el-date-picker v-model="form.paidAt" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" placeholder="请选择实际付款时间" /></el-form-item>
+          <el-form-item label="付款方式" required><el-select v-model="form.paymentMethod" placeholder="请选择付款方式"><el-option label="线上支付" value="ONLINE" /><el-option label="银行转账" value="BANK_TRANSFER" /><el-option label="现金" value="CASH" /><el-option label="其他" value="OTHER" /></el-select></el-form-item>
+          <el-form-item label="付款流水号"><el-input v-model="form.paymentReferenceNo" maxlength="128" placeholder="流水号与付款凭证至少填写一项" /></el-form-item>
+          <el-form-item label="付款凭证" class="voucher-field">
+            <div class="voucher-control"><label class="voucher-picker" :class="{ 'is-disabled': voucherUploading }"><FileUp :size="15" /><span>{{ voucherUploading ? '上传并校验中' : '选择凭证' }}</span><input type="file" accept=".pdf,.jpg,.jpeg,.png,application/pdf,image/jpeg,image/png" :disabled="voucherUploading" @change="selectVoucher" /></label><span class="voucher-hint">FINANCE_VOUCHER · 最多 20 个</span></div>
+            <el-alert v-if="voucherError" type="error" :closable="true" show-icon @close="voucherError = null"><template #title>{{ voucherError.message }}</template><ApiErrorMeta :details="voucherError" /></el-alert>
+            <div v-if="voucherFiles.length" class="voucher-list"><span v-for="file in voucherFiles" :key="file.fileId"><span :title="file.fileName">{{ file.fileName }}</span><button type="button" :aria-label="`移除${file.fileName}`" @click="removeVoucher(file.fileId)"><X :size="14" /></button></span></div>
+          </el-form-item>
+        </template>
+        <el-form-item label="业务发生日" prop="businessDate"><el-date-picker v-model="form.businessDate" type="date" value-format="YYYY-MM-DD" /></el-form-item>
+          <el-form-item label="货币" prop="currency"><el-input model-value="CNY" readonly aria-label="货币 CNY" /></el-form-item>
+        <el-form-item label="单价" prop="unitPrice"><el-input-number v-model="form.unitPrice" :min="0" :precision="4" placeholder="请输入单价" /></el-form-item>
+        <el-form-item label="金额" prop="amount"><el-input-number v-model="form.amount" :min="0" :precision="2" placeholder="请输入金额" /></el-form-item>
+        <el-form-item label="备注"><el-input v-model="form.remark" type="textarea" :rows="3" maxlength="500" show-word-limit placeholder="请输入备注（选填）" /></el-form-item>
+      </el-form>
+    </AppDialog>
+    <AppDialog class="admin-density-dialog" v-model="rejectOpen" title="驳回费用" :confirm-loading="saving" confirm-text="确认驳回" confirm-type="warning" @confirm="reject">
+      <el-alert v-if="actionError" type="error" :closable="true" @close="actionError = null"><template #title>{{ actionError.message }}</template><ApiErrorMeta :details="actionError" /></el-alert>
+      <el-form class="density-form" label-position="top"><el-form-item label="驳回原因" required><el-input v-model="rejectReason" type="textarea" :rows="4" maxlength="500" show-word-limit placeholder="请输入驳回原因" /></el-form-item></el-form>
+    </AppDialog>
+  </section>
+</template>
+
+<style scoped>
+.fee-detail-manager { display: grid; min-width: 0; max-width: 100%; gap: var(--admin-space-5); }
+.fee-toolbar { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-5); color: var(--el-text-color-secondary); font-size: var(--admin-font-body); }
+.fee-toolbar > div { display: flex; flex-wrap: wrap; gap: var(--admin-space-3); }
+.fee-toolbar :deep(.el-button + .el-button) { margin-left: 0; }
+.fee-refresh-button .is-spinning { animation: fee-refresh-spin 0.8s linear infinite; }
+.fee-form { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 0 var(--admin-space-6); margin-top: var(--admin-space-5); }
+.fee-form :deep(.el-select), .fee-form :deep(.el-date-editor), .fee-form :deep(.el-input-number) { width: 100%; }
+.fee-form :deep(.el-form-item:last-child) { grid-column: 1 / -1; }
+.voucher-field { grid-column: 1 / -1; }.voucher-control { display: flex; align-items: center; flex-wrap: wrap; gap: var(--admin-space-4); width: 100%; }.voucher-picker { display: inline-flex; align-items: center; gap: var(--admin-space-2); padding: var(--admin-space-2) var(--admin-space-5); border: 1px solid var(--cc-border); border-radius: var(--admin-radius); color: var(--el-color-primary); cursor: pointer; }.voucher-picker.is-disabled { cursor: not-allowed; opacity: .6; }.voucher-picker input { position: absolute; width: 1px; height: 1px; opacity: 0; }.voucher-hint { color: var(--cc-muted); font-size: var(--admin-font-caption); }.voucher-list { display: grid; width: 100%; gap: var(--admin-space-2); margin-top: var(--admin-space-3); }.voucher-list > span { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-3); padding: var(--admin-space-2) var(--admin-space-3); border-radius: var(--admin-radius); background: var(--el-fill-color-light); }.voucher-list > span > span { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }.voucher-list button { display: inline-flex; padding: 2px; border: 0; background: transparent; color: var(--el-color-danger); cursor: pointer; }
+.fee-table-shell { min-width: 0; max-width: 100%; overflow: hidden; }
+.fee-table-shell :deep(.el-table) { width: 100%; max-width: 100%; }
+.private-delivery-tag { margin-left: var(--admin-space-2); vertical-align: middle; }
+@keyframes fee-refresh-spin { to { transform: rotate(360deg); } }
+@media (max-width: 720px) { .fee-toolbar { align-items: flex-start; flex-direction: column; } .fee-form { grid-template-columns: 1fr; } .fee-form :deep(.el-form-item:last-child) { grid-column: auto; } }
+</style>
diff --git a/src/modules/unified-orders/components/OrderDeclarationEditorDialog.test.ts b/src/modules/unified-orders/components/OrderDeclarationEditorDialog.test.ts
new file mode 100644
index 00000000..13569bc7
--- /dev/null
+++ b/src/modules/unified-orders/components/OrderDeclarationEditorDialog.test.ts
@@ -0,0 +1,151 @@
+import ElementPlus, { ElMessage, ElMessageBox } from 'element-plus'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { updatePlatformUnifiedOrderDeclaration } from '@/modules/unified-orders/api/unifiedOrders'
+import { listWarehouseLogisticsChannels } from '@/modules/ocean-bookings'
+import OrderDeclarationEditorDialog from './OrderDeclarationEditorDialog.vue'
+
+vi.mock('@/modules/unified-orders/api/unifiedOrders', () => ({ updatePlatformUnifiedOrderDeclaration: vi.fn() }))
+vi.mock('@/modules/ocean-bookings', () => ({ listWarehouseLogisticsChannels: vi.fn() }))
+
+const detail = {
+  summary: {
+    orderId: '90001', tenantId: '208', inboundCode: 'RK-001', mainStatus: 'WAIT_MEASURE',
+    receivingWarehouseId: '700000000000000001', receivingWarehouseName: '深圳仓', destinationWarehouseName: '洛杉矶中转仓',
+    channelCode: 'OLD', channelName: '原渠道', channelChanged: false,
+    expectedArrivalAt: '2026-09-06T10:00:00', estimatedVolumeCbm: 0.625, customerRemark: '原备注',
+  },
+  order: {
+    order: { version: 7, receivingWarehouseId: '700000000000000001', channelCode: 'OLD', channelName: '原渠道', customerRemark: '原备注' },
+    cargoes: [{ itemNo: 1, cargoName: '台灯', packageCount: 2, totalQuantity: 20, lengthCm: 40, widthCm: 30, heightCm: 20, grossWeightKg: 18, volumeCbm: 0.048, currency: 'USD', material: '铝', productUsage: '照明' }],
+    parties: [], internalNotes: [], statusHistory: [],
+  },
+  timeline: [],
+} as never
+
+function createWrapper(realDialogs = false) {
+  return mount(OrderDeclarationEditorDialog, {
+    attachTo: realDialogs ? document.body : undefined,
+    props: { modelValue: true, detail },
+    global: {
+      plugins: [ElementPlus],
+      stubs: {
+        AppDialog: realDialogs ? false : {
+          props: ['modelValue', 'confirmLoading', 'confirmDisabled'], emits: ['confirm', 'update:modelValue'],
+          template: '<section v-if="modelValue"><slot /><button data-testid="save" :disabled="confirmDisabled" @click="$emit(\'confirm\')">保存</button></section>',
+        },
+        LoadErrorState: { props: ['title', 'message'], template: '<div class="load-error">{{ title }} {{ message }}<slot name="details" /></div>' },
+        ApiErrorMeta: true,
+      },
+    },
+  })
+}
+
+enableAutoUnmount(afterEach)
+afterEach(() => { document.body.innerHTML = '' })
+
+describe('OrderDeclarationEditorDialog', () => {
+  beforeEach(() => {
+    vi.mocked(updatePlatformUnifiedOrderDeclaration).mockReset()
+    vi.mocked(listWarehouseLogisticsChannels).mockReset()
+    vi.mocked(listWarehouseLogisticsChannels).mockResolvedValue([
+      { channelCode: 'OLD', channelName: '原渠道' },
+      { channelCode: 'NEW', channelName: '新渠道' },
+    ])
+    vi.spyOn(ElMessageBox, 'confirm').mockResolvedValue('confirm' as never)
+    vi.spyOn(ElMessage, 'success').mockImplementation(() => ({ close: vi.fn() }) as never)
+  })
+
+  it('styles both native dialog roots and retains all cargo fields before applying a local edit', async () => {
+    createWrapper(true)
+    await flushPromises()
+    const parent = document.querySelector<HTMLElement>('.el-dialog.admin-density-dialog')!
+    expect(parent.style.getPropertyValue('--el-dialog-width')).toBe('min(1180px, calc(100vw - 36px))')
+    expect(parent.querySelector('.density-descriptions')).not.toBeNull()
+    parent.querySelector<HTMLButtonElement>('.cargo-table .density-action')!.click()
+    await flushPromises()
+    const dialogs = document.querySelectorAll<HTMLElement>('.el-dialog.admin-density-dialog')
+    expect(dialogs).toHaveLength(2)
+    const cargo = dialogs[1]!
+    expect(cargo.style.getPropertyValue('--el-dialog-width')).toBe('min(980px, calc(100vw - 36px))')
+    expect(cargo.querySelectorAll('.cargo-editor-grid > label')).toHaveLength(22)
+    const name = cargo.querySelector<HTMLInputElement>('input[placeholder="请输入中文品名"]')!
+    expect(name.value).toBe('台灯')
+    name.value = '编辑后的台灯'
+    name.dispatchEvent(new Event('input', { bubbles: true }))
+    await flushPromises()
+    const apply = [...cargo.querySelectorAll<HTMLButtonElement>('button')].find(button => button.textContent?.trim() === '应用本项')!
+    apply.click()
+    await flushPromises()
+    expect(parent.textContent).toContain('编辑后的台灯')
+    expect(updatePlatformUnifiedOrderDeclaration).not.toHaveBeenCalled()
+  })
+
+  it('loads formal warehouse channels and submits the code/name pair from one selected option', async () => {
+    vi.mocked(updatePlatformUnifiedOrderDeclaration).mockResolvedValue({ version: 8 } as never)
+    const wrapper = createWrapper()
+    await flushPromises()
+    expect(listWarehouseLogisticsChannels).toHaveBeenCalledWith('700000000000000001')
+    expect(wrapper.text()).toContain('国内收货仓和中转仓不可修改，如需变更请重新下单')
+    expect(wrapper.text()).toContain('RK-001')
+    const channelSelect = wrapper.findAllComponents({ name: 'ElSelect' })[0]!
+    channelSelect.vm.$emit('update:modelValue', 'NEW')
+    channelSelect.vm.$emit('change', 'NEW')
+    await wrapper.vm.$nextTick()
+    await wrapper.get('[data-testid="save"]').trigger('click')
+    await flushPromises()
+
+    expect(ElMessageBox.confirm).toHaveBeenCalledWith(expect.stringContaining('原箱码继续有效，无需更换已打印箱唛'), '确认变更渠道', expect.any(Object))
+    expect(ElMessageBox.confirm).toHaveBeenCalledWith(expect.stringContaining('纸面上的旧渠道文字不会自动变化'), '确认变更渠道', expect.any(Object))
+    expect(updatePlatformUnifiedOrderDeclaration).toHaveBeenCalledWith('208', '90001', expect.objectContaining({
+      expectedVersion: 7,
+      estimatedVolumeCbm: 0.625,
+      channelCode: 'NEW',
+      channelName: '新渠道',
+      cargoes: [expect.objectContaining({ itemNo: 1, usage: '照明' })],
+    }))
+    expect(ElMessage.success).toHaveBeenCalledWith(expect.stringContaining('订单已标记为“曾变更渠道”'))
+    expect(wrapper.emitted('updated')).toHaveLength(1)
+    expect(wrapper.emitted('update:modelValue')).toContainEqual([false])
+  })
+
+  it('does not expose free-text channel inputs and presents cargoes as a compact table with row editing', async () => {
+    const wrapper = createWrapper()
+    await flushPromises()
+
+    expect(wrapper.find('input[aria-label="渠道编码"]').attributes('readonly')).toBeDefined()
+    expect(wrapper.findAllComponents({ name: 'ElSelect' })).toHaveLength(1)
+    expect(wrapper.find('.cargo-table').exists()).toBe(true)
+    expect(wrapper.text()).toContain('箱数 / 数量')
+    expect(wrapper.text()).toContain('材质 / 用途')
+    expect(wrapper.text()).toContain('铝 / 照明')
+    expect(wrapper.text()).toContain('2 箱 / 20')
+
+    const editButton = wrapper.findAll('button').find((button) => button.text() === '编辑')!
+    await editButton.trigger('click')
+    expect(wrapper.find('input[aria-label="币种"]').attributes('readonly')).toBeDefined()
+    expect(wrapper.findAllComponents({ name: 'ElInput' }).some((input) => input.props('modelValue') === '照明')).toBe(true)
+  })
+
+  it('preserves the editor when the versioned update fails', async () => {
+    vi.mocked(updatePlatformUnifiedOrderDeclaration).mockRejectedValue(new Error('订单版本已变化，请刷新详情后重试'))
+    const wrapper = createWrapper()
+    await flushPromises()
+    await wrapper.get('[data-testid="save"]').trigger('click')
+    await flushPromises()
+
+    expect(wrapper.find('.load-error').exists()).toBe(true)
+    expect(wrapper.text()).toContain('原渠道')
+    expect(wrapper.emitted('update:modelValue')).toBeUndefined()
+  })
+
+  it('fails closed and keeps API error evidence when formal channel candidates cannot load', async () => {
+    vi.mocked(listWarehouseLogisticsChannels).mockRejectedValue(Object.assign(new Error('无权限'), { requestId: 'req-1', traceId: 'trace-1' }))
+    const wrapper = createWrapper()
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('渠道候选加载失败')
+    expect(wrapper.get('[data-testid="save"]').attributes('disabled')).toBeDefined()
+    expect(updatePlatformUnifiedOrderDeclaration).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/modules/unified-orders/components/OrderDeclarationEditorDialog.vue b/src/modules/unified-orders/components/OrderDeclarationEditorDialog.vue
new file mode 100644
index 00000000..5ecb7183
--- /dev/null
+++ b/src/modules/unified-orders/components/OrderDeclarationEditorDialog.vue
@@ -0,0 +1,316 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, reactive, ref, watch } from 'vue'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { listWarehouseLogisticsChannels, type OceanLogisticsChannel } from '@/modules/ocean-bookings'
+import {
+  updatePlatformUnifiedOrderDeclaration,
+  type UnifiedOrderDeclarationCargo,
+  type UnifiedOrderDetailResource,
+} from '@/modules/unified-orders/api/unifiedOrders'
+
+const props = defineProps<{
+  modelValue: boolean
+  detail: UnifiedOrderDetailResource
+}>()
+const emit = defineEmits<{
+  'update:modelValue': [value: boolean]
+  updated: []
+}>()
+
+type EditableCargo = UnifiedOrderDeclarationCargo & { key: string }
+const saving = ref(false)
+const submitError = ref<ApiErrorDetails | null>(null)
+const channels = ref<OceanLogisticsChannel[]>([])
+const channelsLoading = ref(false)
+const channelsError = ref<ApiErrorDetails | null>(null)
+let channelRequestSerial = 0
+const cargoEditorOpen = ref(false)
+const cargoEditorIndex = ref(-1)
+const cargoDraft = ref<EditableCargo | null>(null)
+const originalChannel = reactive({ code: '', name: '' })
+const form = reactive({
+  expectedVersion: 0,
+  customerRemark: '',
+  expectedArrivalAt: '',
+  estimatedVolumeCbm: null as number | null,
+  channelCode: '',
+  channelName: '',
+  cargoes: [] as EditableCargo[],
+})
+
+function text(row: Record<string, unknown>, key: string) {
+  const value = row[key]
+  return value === null || value === undefined ? '' : String(value)
+}
+
+function number(row: Record<string, unknown>, key: string, fallback = 0) {
+  const parsed = Number(row[key])
+  return Number.isFinite(parsed) ? parsed : fallback
+}
+
+function optionalNumber(row: Record<string, unknown>, key: string) {
+  const value = row[key]
+  if (value === null || value === undefined || value === '') return null
+  const parsed = Number(value)
+  return Number.isFinite(parsed) ? parsed : null
+}
+
+function receivingWarehouseId() {
+  return String(props.detail.order.order?.receivingWarehouseId || props.detail.summary.receivingWarehouseId || '').trim()
+}
+
+function resetForm() {
+  const snapshot = props.detail.order.order
+  form.expectedVersion = Number(snapshot?.version ?? 0)
+  form.customerRemark = snapshot?.customerRemark || props.detail.summary.customerRemark || ''
+  form.expectedArrivalAt = props.detail.summary.expectedArrivalAt || ''
+  form.estimatedVolumeCbm = props.detail.summary.estimatedVolumeCbm ?? null
+  form.channelCode = snapshot?.channelCode || props.detail.summary.channelCode || ''
+  form.channelName = snapshot?.channelName || props.detail.summary.channelName || ''
+  originalChannel.code = form.channelCode.trim()
+  originalChannel.name = form.channelName.trim()
+  form.cargoes = props.detail.order.cargoes.map((source, index) => {
+    const row = source as Record<string, unknown>
+    const itemNo = number(row, 'itemNo', index + 1)
+    return {
+      key: `${itemNo}-${index}`,
+      itemNo,
+      cargoName: text(row, 'cargoName'), cargoNameEn: text(row, 'cargoNameEn'),
+      skuNo: text(row, 'skuNo'), model: text(row, 'model'),
+      packageCount: number(row, 'packageCount'), totalQuantity: number(row, 'totalQuantity'),
+      lengthCm: number(row, 'lengthCm'), widthCm: number(row, 'widthCm'), heightCm: number(row, 'heightCm'),
+      grossWeightKg: number(row, 'grossWeightKg'), volumeCbm: number(row, 'volumeCbm'),
+      netWeightKg: optionalNumber(row, 'netWeightKg'),
+      hsCode: text(row, 'hsCode'), customsHsCode: text(row, 'customsHsCode'),
+      unitsPerPackage: optionalNumber(row, 'unitsPerPackage'),
+      unitDeclaredValue: optionalNumber(row, 'unitDeclaredValue'), declaredValue: optionalNumber(row, 'declaredValue'),
+      currency: text(row, 'currency'), material: text(row, 'material'), usage: text(row, 'productUsage'),
+      brand: text(row, 'brand'), cargoRemark: text(row, 'cargoRemark') || text(row, 'remark'),
+    }
+  })
+  submitError.value = null
+}
+
+const selectedChannel = computed(() => channels.value.find((item) => item.channelCode === form.channelCode) || null)
+
+async function loadChannels() {
+  const warehouseId = receivingWarehouseId()
+  const serial = ++channelRequestSerial
+  channels.value = []
+  channelsError.value = null
+  if (!warehouseId) {
+    channelsError.value = getApiErrorDetails(new Error('订单缺少国内收货仓，无法加载正式渠道候选'), '渠道候选加载失败')
+    return
+  }
+  channelsLoading.value = true
+  try {
+    const result = await listWarehouseLogisticsChannels(warehouseId)
+    if (serial !== channelRequestSerial) return
+    channels.value = result
+    const current = result.find((item) => item.channelCode === form.channelCode)
+    if (current) form.channelName = current.channelName
+  } catch (error) {
+    if (serial !== channelRequestSerial) return
+    channelsError.value = getApiErrorDetails(error, '正式渠道候选加载失败，请重试')
+  } finally {
+    if (serial === channelRequestSerial) channelsLoading.value = false
+  }
+}
+
+watch(() => props.modelValue, (open) => {
+  if (!open) return
+  resetForm()
+  void loadChannels()
+}, { immediate: true })
+
+function selectChannel(channelCode: string) {
+  const channel = channels.value.find((item) => item.channelCode === channelCode)
+  form.channelCode = channel?.channelCode || ''
+  form.channelName = channel?.channelName || ''
+}
+
+function editCargo(index: number) {
+  cargoEditorIndex.value = index
+  cargoDraft.value = { ...form.cargoes[index]! }
+  cargoEditorOpen.value = true
+}
+
+function cargoValidation(cargo: EditableCargo) {
+  if (!cargo.cargoName.trim()) return `第 ${cargo.itemNo} 项中文品名不能为空`
+  if (cargo.packageCount < 1 || cargo.totalQuantity < 1) return `第 ${cargo.itemNo} 项箱数和总数量必须大于 0`
+  if ([cargo.lengthCm, cargo.widthCm, cargo.heightCm, cargo.grossWeightKg, cargo.volumeCbm].some((value) => !(value > 0))) {
+    return `第 ${cargo.itemNo} 项尺寸、毛重和体积必须大于 0`
+  }
+  return ''
+}
+
+function applyCargo() {
+  if (!cargoDraft.value || cargoEditorIndex.value < 0) return
+  const message = cargoValidation(cargoDraft.value)
+  if (message) { ElMessage.warning(message); return }
+  Object.assign(form.cargoes[cargoEditorIndex.value]!, cargoDraft.value)
+  cargoEditorOpen.value = false
+}
+
+function nullable(value: string | null | undefined) {
+  return value?.trim() || null
+}
+
+function validate() {
+  if (channelsError.value) return '正式渠道候选尚未加载成功，请重试'
+  if (!selectedChannel.value || selectedChannel.value.channelName !== form.channelName) return '请选择当前国内收货仓的正式渠道'
+  if (!form.cargoes.length) return '订单缺少货品明细，不能保存'
+  for (const cargo of form.cargoes) {
+    const message = cargoValidation(cargo)
+    if (message) return message
+  }
+  return ''
+}
+
+async function save() {
+  const validationMessage = validate()
+  if (validationMessage) { ElMessage.warning(validationMessage); return }
+  const channelChanged = form.channelCode.trim() !== originalChannel.code || form.channelName.trim() !== originalChannel.name
+  if (channelChanged) {
+    try {
+      await ElMessageBox.confirm(
+        '渠道变更后，系统会重新校验分柜、同柜及计费约束。原箱码继续有效，无需更换已打印箱唛；纸面上的旧渠道文字不会自动变化，请以系统当前渠道为准。订单将标记为“曾变更渠道”。确认继续吗？',
+        '确认变更渠道',
+        { customClass: 'admin-density-confirm', type: 'warning', confirmButtonText: '确认变更', cancelButtonText: '返回检查' },
+      )
+    } catch { return }
+  }
+  const snapshot = props.detail.order.order
+  if (!snapshot?.version && snapshot?.version !== 0) { ElMessage.error('订单版本缺失，请刷新详情后重试'); return }
+  saving.value = true
+  submitError.value = null
+  try {
+    await updatePlatformUnifiedOrderDeclaration(String(props.detail.summary.tenantId), String(props.detail.summary.orderId), {
+      expectedVersion: form.expectedVersion,
+      customerRemark: nullable(form.customerRemark),
+      expectedArrivalAt: nullable(form.expectedArrivalAt),
+      estimatedVolumeCbm: form.estimatedVolumeCbm,
+      channelCode: form.channelCode.trim(),
+      channelName: form.channelName.trim(),
+      cargoes: form.cargoes.map(({ key: _key, ...cargo }) => ({
+        ...cargo,
+        cargoName: cargo.cargoName.trim(), cargoNameEn: nullable(cargo.cargoNameEn),
+        skuNo: nullable(cargo.skuNo), model: nullable(cargo.model), hsCode: nullable(cargo.hsCode),
+        customsHsCode: nullable(cargo.customsHsCode), currency: nullable(cargo.currency)?.toUpperCase() || null,
+        material: nullable(cargo.material), usage: nullable(cargo.usage), brand: nullable(cargo.brand),
+        cargoRemark: nullable(cargo.cargoRemark),
+      })),
+    })
+    ElMessage.success(channelChanged
+      ? '渠道已更新，订单已标记为“曾变更渠道”；原箱码继续有效，无需更换已打印箱唛'
+      : '客户申报资料已更新')
+    emit('update:modelValue', false)
+    emit('updated')
+  } catch (error) {
+    submitError.value = getApiErrorDetails(error, '客户申报资料保存失败，请核对权限、订单状态或刷新版本后重试')
+  } finally {
+    saving.value = false
+  }
+}
+</script>
+
+<template>
+  <AppDialog class="admin-density-dialog"
+    :model-value="modelValue"
+    title="编辑客户申报资料"
+    width="min(1180px, calc(100vw - 36px))"
+    confirm-text="保存申报资料"
+    :confirm-loading="saving"
+    :confirm-disabled="channelsLoading || Boolean(channelsError) || !selectedChannel"
+    :close-on-click-modal="false"
+    @update:model-value="emit('update:modelValue', $event)"
+    @confirm="save"
+  >
+    <div class="declaration-editor">
+      <el-alert type="warning" :closable="false" title="仅修改客户原始申报资料；仓库/PDA 实测数据不会被覆盖。变更渠道不作废原箱码，订单会标记为“曾变更渠道”。国内收货仓和中转仓不可修改，如需变更请重新下单。" />
+      <LoadErrorState v-if="submitError" compact title="保存失败，当前填写内容已保留" :message="submitError.message" :show-retry="false">
+        <template #details><ApiErrorMeta :details="submitError" /></template>
+      </LoadErrorState>
+      <LoadErrorState v-if="channelsError" compact title="渠道候选加载失败" :message="channelsError.message" @retry="loadChannels">
+        <template #details><ApiErrorMeta :details="channelsError" /></template>
+      </LoadErrorState>
+
+      <el-descriptions :column="4" border class="readonly-facts density-descriptions">
+        <el-descriptions-item label="入仓码">{{ detail.summary.inboundCode || '—' }}</el-descriptions-item>
+        <el-descriptions-item label="国内收货仓">{{ detail.summary.receivingWarehouseName || '—' }}</el-descriptions-item>
+        <el-descriptions-item label="目的仓/中转仓">{{ detail.summary.destinationWarehouseName || '—' }}</el-descriptions-item>
+        <el-descriptions-item label="版本">{{ form.expectedVersion }}</el-descriptions-item>
+      </el-descriptions>
+
+      <el-form label-position="top" class="order-fields density-form">
+        <el-row :gutter="14">
+          <el-col :span="7"><el-form-item label="渠道名称" required><el-select v-model="form.channelCode" aria-label="渠道名称" filterable clearable :loading="channelsLoading" placeholder="请选择正式渠道" @change="selectChannel"><el-option v-for="channel in channels" :key="channel.channelCode" :label="`${channel.channelName} · ${channel.channelCode}`" :value="channel.channelCode" /></el-select></el-form-item></el-col>
+          <el-col :span="4"><el-form-item label="渠道编码"><el-input :model-value="form.channelCode" readonly aria-label="渠道编码" /></el-form-item></el-col>
+          <el-col :span="4"><el-form-item label="预估体积(m³)"><el-input-number v-model="form.estimatedVolumeCbm" :min="0.0001" :precision="4" :controls="false" placeholder="请输入预估体积（选填）" /></el-form-item></el-col>
+          <el-col :span="5"><el-form-item label="预计到货时间"><el-date-picker v-model="form.expectedArrivalAt" type="datetime" value-format="YYYY-MM-DDTHH:mm:ss" format="YYYY-MM-DD HH:mm" clearable /></el-form-item></el-col>
+          <el-col :span="4"><el-form-item label="客户备注"><el-input v-model="form.customerRemark" maxlength="1000" show-word-limit placeholder="请输入客户备注（选填）" /></el-form-item></el-col>
+        </el-row>
+      </el-form>
+
+      <h3>货品申报明细 <small>不允许新增、删除或调整明细序号</small></h3>
+      <el-table :data="form.cargoes" border stripe size="small" class="cargo-table">
+        <el-table-column label="操作" width="82" fixed="left"><template #default="{ $index }"><el-button class="density-action" data-tone="neutral" @click="editCargo($index)">编辑</el-button></template></el-table-column>
+        <el-table-column prop="itemNo" label="项" width="58" align="center" />
+        <el-table-column label="货品" min-width="190"><template #default="{ row }"><strong class="cell-primary" :title="row.cargoName">{{ row.cargoName }}</strong><small :title="row.cargoNameEn || row.skuNo">{{ row.cargoNameEn || row.skuNo || '—' }}</small></template></el-table-column>
+        <el-table-column label="箱数 / 数量" width="118" align="right"><template #default="{ row }">{{ row.packageCount }} 箱 / {{ row.totalQuantity }}</template></el-table-column>
+        <el-table-column label="申报尺寸(cm)" width="148"><template #default="{ row }">{{ row.lengthCm }} × {{ row.widthCm }} × {{ row.heightCm }}</template></el-table-column>
+        <el-table-column label="毛重 / 净重(kg)" width="145"><template #default="{ row }">{{ row.grossWeightKg }} / {{ row.netWeightKg ?? '—' }}</template></el-table-column>
+        <el-table-column prop="volumeCbm" label="体积(m³)" width="100" align="right" />
+        <el-table-column label="申报金额" width="125" align="right"><template #default="{ row }">{{ row.currency || '—' }} {{ row.declaredValue ?? '—' }}</template></el-table-column>
+        <el-table-column label="材质 / 用途" min-width="170"><template #default="{ row }"><span :title="[row.material, row.usage].filter(Boolean).join(' / ')">{{ [row.material, row.usage].filter(Boolean).join(' / ') || '—' }}</span></template></el-table-column>
+      </el-table>
+    </div>
+  </AppDialog>
+
+  <AppDialog class="admin-density-dialog" v-model="cargoEditorOpen" title="编辑货品申报" width="min(980px, calc(100vw - 36px))" confirm-text="应用本项" :close-on-click-modal="false" @confirm="applyCargo">
+    <div v-if="cargoDraft" class="cargo-editor-grid">
+      <label><span>中文品名 *</span><el-input v-model="cargoDraft.cargoName" maxlength="128" placeholder="请输入中文品名" /></label>
+      <label><span>英文品名</span><el-input v-model="cargoDraft.cargoNameEn" maxlength="128" placeholder="请输入英文品名（选填）" /></label>
+      <label><span>SKU NO.</span><el-input v-model="cargoDraft.skuNo" maxlength="64" placeholder="请输入 SKU（选填）" /></label>
+      <label><span>型号</span><el-input v-model="cargoDraft.model" maxlength="64" placeholder="请输入型号（选填）" /></label>
+      <label><span>箱数 *</span><el-input-number v-model="cargoDraft.packageCount" :min="1" :precision="0" controls-position="right" placeholder="请输入箱数" /></label>
+      <label><span>总数量 *</span><el-input-number v-model="cargoDraft.totalQuantity" :min="1" :precision="0" controls-position="right" placeholder="请输入总数量" /></label>
+      <label><span>每箱数量</span><el-input-number v-model="cargoDraft.unitsPerPackage" :min="1" :precision="0" controls-position="right" placeholder="请输入每箱数量（选填）" /></label>
+      <label><span>币种</span><el-input :model-value="cargoDraft.currency || '—'" readonly aria-label="币种" /></label>
+      <label><span>长(cm) *</span><el-input-number v-model="cargoDraft.lengthCm" :min="0.01" :precision="2" controls-position="right" placeholder="请输入长度" /></label>
+      <label><span>宽(cm) *</span><el-input-number v-model="cargoDraft.widthCm" :min="0.01" :precision="2" controls-position="right" placeholder="请输入宽度" /></label>
+      <label><span>高(cm) *</span><el-input-number v-model="cargoDraft.heightCm" :min="0.01" :precision="2" controls-position="right" placeholder="请输入高度" /></label>
+      <label><span>体积(m³) *</span><el-input-number v-model="cargoDraft.volumeCbm" :min="0.0001" :precision="4" controls-position="right" placeholder="请输入体积" /></label>
+      <label><span>毛重(kg) *</span><el-input-number v-model="cargoDraft.grossWeightKg" :min="0.001" :precision="3" controls-position="right" placeholder="请输入毛重" /></label>
+      <label><span>净重(kg)</span><el-input-number v-model="cargoDraft.netWeightKg" :min="0.001" :precision="3" controls-position="right" placeholder="请输入净重（选填）" /></label>
+      <label><span>单价</span><el-input-number v-model="cargoDraft.unitDeclaredValue" :min="0" :precision="2" controls-position="right" placeholder="请输入申报单价（选填）" /></label>
+      <label><span>申报总价</span><el-input-number v-model="cargoDraft.declaredValue" :min="0" :precision="2" controls-position="right" placeholder="请输入申报总价（选填）" /></label>
+      <label><span>报关 HS CODE</span><el-input v-model="cargoDraft.hsCode" maxlength="20" placeholder="请输入报关 HS CODE（选填）" /></label>
+      <label><span>清关 HS CODE</span><el-input v-model="cargoDraft.customsHsCode" maxlength="20" placeholder="请输入清关 HS CODE（选填）" /></label>
+      <label><span>材质</span><el-input v-model="cargoDraft.material" maxlength="128" placeholder="请输入材质（选填）" /></label>
+      <label><span>用途</span><el-input v-model="cargoDraft.usage" maxlength="128" placeholder="请输入用途（选填）" /></label>
+      <label><span>品牌</span><el-input v-model="cargoDraft.brand" maxlength="64" placeholder="请输入品牌（选填）" /></label>
+      <label class="wide"><span>货品备注</span><el-input v-model="cargoDraft.cargoRemark" maxlength="500" placeholder="请输入货品备注（选填）" /></label>
+    </div>
+  </AppDialog>
+</template>
+
+<style scoped>
+.declaration-editor { display: grid; gap: var(--admin-space-5); }
+.readonly-facts { margin-top: 2px; }
+.order-fields :deep(.el-date-editor), .order-fields :deep(.el-input) { width: 100%; }
+h3 { margin: 0; color: #344054; font-size: var(--admin-font-section); } h3 small { margin-left: var(--admin-space-3); color: #98a2b3; font-weight: 400; }
+.cargo-table { width: 100%; }
+.cargo-table small, .cargo-table .cell-primary { display: block; max-width: 100%; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.cargo-table small { margin-top: 3px; color: #98a2b3; }
+.cargo-editor-grid { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: var(--admin-space-5) var(--admin-space-5); }
+.cargo-editor-grid label { display: grid; min-width: 0; gap: var(--admin-space-1); color: #667085; font-size: var(--admin-font-caption); }
+.cargo-editor-grid label.wide { grid-column: span 3; }
+.cargo-editor-grid :deep(.el-input-number), .cargo-editor-grid :deep(.el-input), .order-fields :deep(.el-select) { width: 100%; }
+@media (max-width: 900px) { .cargo-editor-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); } .cargo-editor-grid label.wide { grid-column: span 2; } }
+</style>
diff --git a/src/modules/unified-orders/components/OrderFulfillmentTreePanel.test.ts b/src/modules/unified-orders/components/OrderFulfillmentTreePanel.test.ts
new file mode 100644
index 00000000..38191028
--- /dev/null
+++ b/src/modules/unified-orders/components/OrderFulfillmentTreePanel.test.ts
@@ -0,0 +1,39 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/unified-orders/components/OrderFulfillmentTreePanel.vue'), 'utf8')
+
+describe('OrderFulfillmentTreePanel contract', () => {
+  it('shows root conservation fields and fragment picking quantities', () => {
+    for (const label of ['原始总量', '累计已装', '当前余量', '本单计划', '已拣', '未拣']) {
+      expect(source).toContain(label)
+    }
+    expect(source).toContain('历史双子单模型')
+    expect(source).toContain('新拆分不会再生成已装子单')
+    expect(source).toContain('inboundCode?: string | null')
+    expect(source).toContain("props.inboundCode || '暂缺'")
+    expect(source).not.toContain('tree.rootOrderNo')
+    expect(source).not.toContain('tree.rootOrderId')
+    expect(source).not.toContain('row.orderNo')
+  })
+
+  it('covers loading, error, empty and responsive states', () => {
+    expect(source).toContain('正在加载拆分履约')
+    expect(source).toContain('拆分履约暂时无法加载')
+    expect(source).toContain('<ApiErrorMeta')
+    expect(source).toContain('暂无拆分分片')
+    expect(source).toContain('@media (max-width: 720px)')
+  })
+
+  it('translates fragment roles and statuses instead of exposing backend enums', () => {
+    expect(source).toContain('unifiedOrderFulfillmentRoleLabel(row.splitRole)')
+    expect(source).toContain('unifiedOrderFulfillmentStatusLabel(row.status, row.splitRole)')
+    expect(source).not.toContain(':status="row.status')
+    expect(source).not.toContain('return role ||')
+  })
+
+  it('renders fulfillment fragments with the native table grid contract', () => {
+    expect(source).toContain('row-key="orderId" border stripe')
+  })
+})
diff --git a/src/modules/unified-orders/components/OrderFulfillmentTreePanel.vue b/src/modules/unified-orders/components/OrderFulfillmentTreePanel.vue
new file mode 100644
index 00000000..e66c1cbe
--- /dev/null
+++ b/src/modules/unified-orders/components/OrderFulfillmentTreePanel.vue
@@ -0,0 +1,63 @@
+<script setup lang="ts">
+import { onMounted, ref } from 'vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import { getPlatformOrderFulfillmentTree, type UnifiedOrderFulfillmentTree } from '../api/orderFulfillment'
+import { unifiedOrderFulfillmentRoleLabel, unifiedOrderFulfillmentStatusLabel } from '../status'
+
+const props = defineProps<{ tenantId: string; orderId: string; inboundCode?: string | null; compact?: boolean }>()
+const tree = ref<UnifiedOrderFulfillmentTree | null>(null)
+const loading = ref(false)
+const error = ref<ApiErrorDetails | null>(null)
+
+async function load() {
+  loading.value = true
+  error.value = null
+  try { tree.value = await getPlatformOrderFulfillmentTree(props.tenantId, props.orderId) }
+  catch (cause) { error.value = getApiErrorDetails(cause) }
+  finally { loading.value = false }
+}
+
+onMounted(() => { void load() })
+</script>
+
+<template>
+  <div class="fulfillment-tree-panel" :class="{ compact }" aria-label="拆分履约聚合">
+    <LoadErrorState v-if="error" title="拆分履约暂时无法加载" :message="error.message" :loading="loading" @retry="load">
+      <ApiErrorMeta :details="error" />
+    </LoadErrorState>
+    <div v-else-if="loading" class="tree-loading" aria-live="polite">正在加载拆分履约…</div>
+    <template v-else-if="tree">
+      <div class="tree-summary">
+        <div><span>入仓码</span><strong>{{ props.inboundCode || '暂缺' }}</strong></div>
+        <div><span>原始总量</span><strong>{{ tree.originalPackageCount ?? '—' }} 箱</strong></div>
+        <div><span>累计已装</span><strong>{{ tree.cumulativeLoadedPackageCount ?? '—' }} 箱</strong></div>
+        <div><span>当前余量</span><strong>{{ tree.currentRemainderPackageCount ?? '—' }} 箱</strong></div>
+      </div>
+      <el-alert v-if="tree.historicalTwoChildModel" type="info" :closable="false" show-icon title="该记录使用历史双子单模型，仅兼容展示；新拆分不会再生成已装子单。" />
+      <el-table :data="tree.fragments" row-key="orderId" border stripe empty-text="暂无拆分分片">
+        <el-table-column label="分片" min-width="180"><template #default="{ row }"><strong>{{ unifiedOrderFulfillmentRoleLabel(row.splitRole) }}</strong><small v-if="row.splitSequence != null"> · 第 {{ row.splitSequence }} 次</small></template></el-table-column>
+        <el-table-column label="类型" width="120"><template #default="{ row }">{{ unifiedOrderFulfillmentRoleLabel(row.splitRole) }}</template></el-table-column>
+        <el-table-column label="本单计划" width="100"><template #default="{ row }">{{ row.plannedPackageCount ?? '—' }} 箱</template></el-table-column>
+        <el-table-column label="已拣" width="90"><template #default="{ row }">{{ row.pickedPackageCount ?? '—' }}</template></el-table-column>
+        <el-table-column label="未拣" width="90"><template #default="{ row }">{{ row.unpickedPackageCount ?? '—' }}</template></el-table-column>
+        <el-table-column label="状态" width="130"><template #default="{ row }"><StatusBadge :status="unifiedOrderFulfillmentStatusLabel(row.status, row.splitRole)" /></template></el-table-column>
+        <el-table-column label="柜次" min-width="150"><template #default="{ row }">{{ row.containerBookingId ? '已关联柜次' : '—' }}</template></el-table-column>
+      </el-table>
+    </template>
+    <el-empty v-else description="暂无拆分履约数据" :image-size="64" />
+  </div>
+</template>
+
+<style scoped>
+.fulfillment-tree-panel { display: grid; gap: 16px; }
+.tree-summary { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 12px; padding: 14px; border: 1px solid var(--cc-border); border-radius: 8px; background: var(--cc-surface-muted); }
+.tree-summary div { display: grid; gap: 4px; min-width: 0; }
+.tree-summary span { color: var(--cc-muted); font-size: 12px; }
+.tree-summary strong { overflow: hidden; color: var(--cc-text); text-overflow: ellipsis; white-space: nowrap; }
+.tree-loading { min-height: 120px; display: grid; place-items: center; color: var(--cc-muted); }
+small { color: var(--cc-muted); font-weight: 400; }
+@media (max-width: 720px) { .tree-summary { grid-template-columns: repeat(2, minmax(0, 1fr)); } }
+</style>
diff --git a/src/modules/unified-orders/index.ts b/src/modules/unified-orders/index.ts
new file mode 100644
index 00000000..81057d42
--- /dev/null
+++ b/src/modules/unified-orders/index.ts
@@ -0,0 +1,25 @@
+export {
+  listPlatformUnifiedOrderFeeDetails,
+  listPlatformUnifiedOrders,
+  type UnifiedOrderFeeDetailResource,
+  type UnifiedOrderResource,
+} from './api/unifiedOrders'
+export {
+  cancelPlatformCoLoadGroup,
+  createPlatformCoLoadGroup,
+  getPlatformCoLoadGroupByInboundCode,
+  type CoLoadBusinessMember,
+  type CoLoadBusinessSummary,
+  type CoLoadGroup,
+  type CoLoadGroupMember,
+  type CoLoadGroupStatus,
+} from './api/coLoadGroups'
+
+export {
+  unifiedOrderFulfillmentRoleLabel,
+  unifiedOrderFulfillmentStatusLabel,
+  unifiedOrderHistoryActionLabel,
+  unifiedOrderLoadingStatusLabel,
+  unifiedOrderReviewStatusLabel,
+  unifiedOrderStatusLabel,
+} from './status'
diff --git a/src/modules/unified-orders/pages/UnifiedOrdersView.coLoad.test.ts b/src/modules/unified-orders/pages/UnifiedOrdersView.coLoad.test.ts
new file mode 100644
index 00000000..3852fc22
--- /dev/null
+++ b/src/modules/unified-orders/pages/UnifiedOrdersView.coLoad.test.ts
@@ -0,0 +1,272 @@
+import { flushPromises, shallowMount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { ElMessageBox } from 'element-plus'
+import { ApiResponseError } from '@/shared/api/http'
+import { listPlatformUnifiedOrders, type UnifiedOrderResource } from '@/modules/unified-orders/api/unifiedOrders'
+import { cancelPlatformCoLoadGroup, createPlatformCoLoadGroup, getPlatformCoLoadGroupByInboundCode } from '@/modules/unified-orders/api/coLoadGroups'
+import UnifiedOrdersView from './UnifiedOrdersView.vue'
+
+vi.mock('vue-router', () => ({ useRoute: () => ({ params: {}, query: {} }), useRouter: () => ({ push: vi.fn() }) }))
+vi.mock('@/core/access/accessPreview', () => ({ useAccessPreviewStore: () => ({ can: () => true }) }))
+vi.mock('@/modules/iam', () => ({ listPlatformTenants: vi.fn().mockResolvedValue({ records: [], page: 1, size: 200, total: 0, pages: 0 }) }))
+vi.mock('@/modules/warehouses', () => ({ listAllPlatformWarehouses: vi.fn().mockResolvedValue([]) }))
+vi.mock('@/modules/inbounds', () => ({ downloadWeightImage: vi.fn(), getInboundMeasurement: vi.fn() }))
+vi.mock('@/modules/unified-orders/workflows', () => ({ UnifiedOrderWorkflowPanel: { template: '<div />' } }))
+vi.mock('@/modules/unified-orders/api/unifiedOrders', () => ({
+  updatePlatformUnifiedOrderRemarks: vi.fn(), approvePlatformUnifiedOrder: vi.fn(), batchApprovePlatformUnifiedOrders: vi.fn(),
+  getPlatformUnifiedOrder: vi.fn(), listPlatformUnifiedOrderFeeDetails: vi.fn(), listPlatformUnifiedOrders: vi.fn(),
+  unifiedOrderStatusOptions: [{ value: 'WAIT_SPLIT', label: '待分柜' }],
+}))
+vi.mock('@/modules/unified-orders/api/coLoadGroups', () => ({
+  cancelPlatformCoLoadGroup: vi.fn(), createPlatformCoLoadGroup: vi.fn(), getPlatformCoLoadGroupByInboundCode: vi.fn(),
+}))
+
+const rows: UnifiedOrderResource[] = ['5001', '5002'].map((orderId, index) => ({
+  orderId, tenantId: `600${index}`, orderNo: `ORD-${index + 1}`, mainStatus: 'WAIT_SPLIT' as const, nextAction: null,
+  relation: null, internalOrderStatus: 'WAIT_SPLIT', customerId: `600${index}`, customerName: `客户${index + 1}`,
+  channelCode: 'NY_EXX', channelName: '纽约渠道', receivingWarehouseId: '8', receivingWarehouseName: '义乌仓', destinationWarehouseId: '9', destinationWarehouseName: 'ONT8',
+  inboundId: `700${index}`, inboundVersion: 1, inboundCode: `IN-${index + 1}`, expectedShipDate: null, totalPackageCount: 5,
+  holdFlag: false, currentHoldReason: null,
+  locationCodes: null, actualGrossWeightKg: 10, actualVolumeCbm: 1, measurement: null, preload: null, loading: null, delivery: null, transport: null,
+  createdAt: null, updatedAt: null, expectedArrivalAt: null, feeReviewStatus: null, requestedPickupAt: null, totalPalletCount: null,
+  chargeableVolumeCbm: null, volumetricWeightKg: null, totalNetWeightKg: null, measurementCompletedAt: null, inboundCompletedAt: null,
+  expressCompany: null, expressTrackingNo: null, skuNos: null, totalQuantity: null, shipmentId: null, referenceId: null,
+  coLoadGroup: null,
+}))
+function mountView() {
+  return shallowMount(UnifiedOrdersView, {
+    global: { directives: { loading: () => undefined }, stubs: {
+      AdminPage: { template: '<main><slot /></main>' },
+      ListPageLayout: { template: '<section><slot name="toolbar" /><slot name="state" /><slot /></section>' },
+      QueryToolbar: { template: '<div />' },
+      DataTable: { name: 'DataTable', props: ['data', 'columns'], emits: ['selection-change'], template: '<section><slot name="toolbar-actions" /><button data-testid="select" @click="$emit(\'selection-change\', data)">勾选两票</button><template v-for="row in data" :key="row.orderId"><slot name="actions" :row="row" /><slot name="inboundCode" :row="row" /></template></section>' },
+      AppDialog: { name: 'AppDialog', props: ['modelValue', 'confirmText', 'confirmDisabled', 'confirmLoading'], emits: ['confirm', 'update:modelValue'], methods: { close() { this.$emit('update:modelValue', false) } }, template: '<section v-if="modelValue"><slot /><slot name="footer" :close="close" :submitting="confirmLoading"><button data-testid="dialog-confirm" :disabled="confirmDisabled" @click="$emit(\'confirm\')">{{ confirmText }}</button></slot></section>' },
+      ApiErrorMeta: { props: ['details'], template: '<div>{{ details.code }} {{ details.requestId }} {{ details.traceId }}</div>' },
+      CopyButton: { props: ['value', 'label'], template: '<button :data-copy="value">复制 ID</button>' },
+      'el-button': { props: ['disabled', 'loading'], emits: ['click'], template: '<button :disabled="disabled" @click="$emit(\'click\')"><slot /></button>' },
+      'el-tag': { template: '<span><slot /></span>' },
+      'el-alert': { props: ['title'], template: '<div>{{ title }}</div>' },
+    } },
+  })
+}
+
+describe('UnifiedOrdersView co-load group behavior', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.mocked(listPlatformUnifiedOrders).mockResolvedValue({ records: rows, page: 1, size: 20, total: 2, pages: 1 })
+    vi.spyOn(ElMessageBox, 'confirm').mockResolvedValue({ action: 'confirm', value: '' } as never)
+  })
+
+  it('keeps both selected orders and backend tracing evidence when create validation fails', async () => {
+    vi.mocked(createPlatformCoLoadGroup).mockRejectedValue(new ApiResponseError('成员路线不一致', 'A0409', 409, undefined, 'request-coload', 'trace-coload'))
+    const wrapper = mountView()
+    await flushPromises()
+    await wrapper.get('[data-testid="select"]').trigger('click')
+    await wrapper.findAll('button').find((button) => button.text().includes('合柜报关'))!.trigger('click')
+    await wrapper.get('[data-testid="dialog-confirm"]').trigger('click')
+    await flushPromises()
+    expect(createPlatformCoLoadGroup).toHaveBeenCalledWith(['5001', '5002'])
+    expect(wrapper.text()).toContain('合柜报关（2）')
+    expect(wrapper.text()).toContain('成员路线不一致')
+    expect(wrapper.text()).toContain('A0409 request-coload trace-coload')
+    expect(wrapper.text()).not.toContain('5001')
+    expect(wrapper.text()).not.toContain('5002')
+    expect(listPlatformUnifiedOrders).toHaveBeenCalledTimes(1)
+  })
+
+  it.each([
+    ['平台收货仓不同', [{ ...rows[0], receivingWarehouseId: '8', receivingWarehouseName: '义乌仓' }, { ...rows[1], receivingWarehouseId: '9', receivingWarehouseName: '东莞仓' }], '所选订单的平台收货仓不同：IN-1（仓库：义乌仓；渠道：纽约渠道）、IN-2（仓库：东莞仓；渠道：纽约渠道），不能设为同柜组'],
+    ['渠道不同', [{ ...rows[0], channelCode: 'NY_EXX', channelName: '纽约渠道' }, { ...rows[1], channelCode: 'LA_SEA', channelName: '洛杉矶渠道' }], '所选订单的渠道不同：IN-1（仓库：义乌仓；渠道：纽约渠道）、IN-2（仓库：义乌仓；渠道：洛杉矶渠道），不能设为同柜组'],
+    ['已有同柜组', [rows[0], { ...rows[1], coLoadGroup: { status: 'ACTIVE', memberCount: 2, memberInboundCodes: ['IN-2', 'IN-3'] } }], '以下入仓码已有同柜组：IN-2（仓库：义乌仓；渠道：纽约渠道），请先解除原同柜组'],
+  ])('blocks a bypassed invalid create when %s without rendering qualification errors', async (_case, selectedRows, reason) => {
+    vi.mocked(listPlatformUnifiedOrders).mockResolvedValue({ records: selectedRows, page: 1, size: 20, total: 2, pages: 1 })
+    const wrapper = mountView()
+    await flushPromises()
+    await wrapper.get('[data-testid="select"]').trigger('click')
+    const createButton = wrapper.findAll('button').find((button) => button.text().includes('合柜报关'))!
+    expect(createButton.attributes('disabled')).toBeDefined()
+    expect(wrapper.text()).not.toContain(reason)
+    await createButton.trigger('click')
+    expect(createPlatformCoLoadGroup).not.toHaveBeenCalled()
+  })
+
+  it('keeps zero-selection and one-selection silent while the create button stays disabled', async () => {
+    const wrapper = mountView()
+    await flushPromises()
+    expect(wrapper.text()).not.toContain('请至少勾选 2 票订单后再设为同柜组')
+    expect(wrapper.findAll('button').find((button) => button.text().includes('合柜报关'))!.attributes('disabled')).toBeDefined()
+
+    ;(wrapper.vm as unknown as { handleOrderSelectionChange: (selected: typeof rows) => void }).handleOrderSelectionChange([rows[0]])
+    await wrapper.vm.$nextTick()
+    expect(wrapper.text()).not.toContain('当前仅选择 1 票')
+    expect(wrapper.findAll('button').find((button) => button.text().includes('合柜报关'))!.attributes('disabled')).toBeDefined()
+    expect(wrapper.text()).not.toContain('5001')
+    expect(wrapper.text()).not.toContain('7000')
+  })
+
+  it.each([
+    ['平台收货仓', [{ ...rows[0], receivingWarehouseId: null, receivingWarehouseName: null }, rows[1]], '以下入仓码缺少平台收货仓：IN-1（仓库：未配置仓库；渠道：纽约渠道），请刷新后重试'],
+    ['渠道', [{ ...rows[0], channelCode: null, channelName: null }, rows[1]], '以下入仓码缺少渠道：IN-1（仓库：义乌仓；渠道：未配置渠道），请刷新后重试'],
+  ])('keeps a bypassed missing-field selection disabled and silent when %s is missing', async (_case, selectedRows, reason) => {
+    vi.mocked(listPlatformUnifiedOrders).mockResolvedValue({ records: selectedRows, page: 1, size: 20, total: 2, pages: 1 })
+    const wrapper = mountView()
+    await flushPromises()
+    await wrapper.get('[data-testid="select"]').trigger('click')
+    expect(wrapper.text()).not.toContain(reason)
+    expect(createPlatformCoLoadGroup).not.toHaveBeenCalled()
+  })
+
+  it('allows different display names for the same channel code', async () => {
+    vi.mocked(listPlatformUnifiedOrders).mockResolvedValue({ records: [rows[0], { ...rows[1], channelName: '纽约渠道（新名称）' }], page: 1, size: 20, total: 2, pages: 1 })
+    vi.mocked(createPlatformCoLoadGroup).mockResolvedValue({ groupId: '9001', groupNo: 'CLG-1', status: 'ACTIVE', warehouseId: '8', channelCode: 'NY_EXX', lockedPlanId: null, version: 1, members: [], fullPackageCount: 10, createdAt: '', updatedAt: '' })
+    const wrapper = mountView()
+    await flushPromises()
+    await wrapper.get('[data-testid="select"]').trigger('click')
+    await wrapper.findAll('button').find((button) => button.text().includes('合柜报关'))!.trigger('click')
+    await wrapper.get('[data-testid="dialog-confirm"]').trigger('click')
+    await flushPromises()
+    expect(createPlatformCoLoadGroup).toHaveBeenCalledWith(['5001', '5002'])
+  })
+
+  it('blocks identical display names when channel codes differ', async () => {
+    vi.mocked(listPlatformUnifiedOrders).mockResolvedValue({ records: [rows[0], { ...rows[1], channelCode: 'LA_SEA', channelName: '纽约渠道' }], page: 1, size: 20, total: 2, pages: 1 })
+    const wrapper = mountView()
+    await flushPromises()
+    await wrapper.get('[data-testid="select"]').trigger('click')
+    expect(wrapper.findAll('button').find((button) => button.text().includes('合柜报关'))!.attributes('disabled')).toBeDefined()
+    expect(wrapper.text()).not.toContain('所选订单的渠道不同')
+    expect(createPlatformCoLoadGroup).not.toHaveBeenCalled()
+  })
+
+  it('keeps every row selectable for shared batch actions while only disabling invalid co-load creation', async () => {
+    const selectedRows: UnifiedOrderResource[] = [
+      { ...rows[0], mainStatus: 'PENDING_REVIEW', nextAction: 'APPROVE_ORDER', receivingWarehouseId: '8' },
+      { ...rows[1], mainStatus: 'PENDING_REVIEW', nextAction: 'APPROVE_ORDER', receivingWarehouseId: '9' },
+      { ...rows[1], orderId: '5003', inboundCode: 'IN-3', mainStatus: 'PENDING_REVIEW', nextAction: 'APPROVE_ORDER', receivingWarehouseId: '10', channelCode: 'LA_SEA' },
+    ]
+    vi.mocked(listPlatformUnifiedOrders).mockResolvedValue({ records: selectedRows, page: 1, size: 20, total: 3, pages: 1 })
+    const wrapper = mountView()
+    await flushPromises()
+    const table = wrapper.findComponent({ name: 'DataTable' })
+    const selectable = (table.props('columns') as Array<{ key: string; selectable?: (row: UnifiedOrderResource) => boolean }>).find((column) => column.key === 'selection')!.selectable!
+    const missingChannel = { ...rows[1], channelCode: null, channelName: null }
+    const grouped = { ...rows[1], coLoadGroup: { status: 'ACTIVE', memberCount: 2, memberInboundCodes: ['IN-2', 'IN-3'] } }
+
+    expect(selectedRows.every((row) => selectable(row))).toBe(true)
+    expect(selectable(missingChannel)).toBe(true)
+    expect(selectable(grouped)).toBe(true)
+    await table.vm.$emit('selection-change', selectedRows)
+    await flushPromises()
+    expect(wrapper.findAll('button').find((button) => button.text().includes('批量审核通过'))!.attributes('disabled')).toBeUndefined()
+    expect(wrapper.findAll('button').find((button) => button.text().includes('批量审核通过'))!.text()).toContain('（3）')
+    expect(wrapper.findAll('button').find((button) => button.text().includes('合柜报关'))!.attributes('disabled')).toBeDefined()
+    expect(wrapper.text()).not.toContain('平台收货仓不同')
+    expect(wrapper.text()).not.toContain('渠道不同')
+  })
+
+  it('uses inbound codes as the only row identifier and shows an explicit pending state', async () => {
+    vi.mocked(listPlatformUnifiedOrders).mockResolvedValue({ records: [rows[0], { ...rows[1], inboundCode: null }], page: 1, size: 20, total: 2, pages: 1 })
+    const wrapper = mountView()
+    await flushPromises()
+    expect(wrapper.text()).toContain('IN-1')
+    expect(wrapper.text()).toContain('待生成入仓码')
+    expect(wrapper.text()).not.toContain('ORD-1')
+    expect(wrapper.text()).not.toContain('ORD-2')
+    expect(wrapper.text()).not.toContain('5001')
+    expect(wrapper.text()).not.toContain('7000')
+    expect(wrapper.text()).not.toContain('履约详情')
+    expect(wrapper.text()).not.toContain('关联数据')
+  })
+
+  it('shows a business-only group summary and all server-provided inbound codes in the dialog', async () => {
+    const rowsWithGroup = rows.map((row) => ({ ...row, coLoadGroup: { status: 'ACTIVE', memberCount: 2, memberInboundCodes: ['IN-1', 'IN-1-B', 'IN-2'] } }))
+    vi.mocked(listPlatformUnifiedOrders).mockResolvedValue({ records: rowsWithGroup, page: 1, size: 20, total: 2, pages: 1 })
+    vi.mocked(getPlatformCoLoadGroupByInboundCode).mockResolvedValue({ status: 'ACTIVE', memberCount: 3, members: [{ inboundCode: 'IN-1' }, { inboundCode: 'IN-1-B' }, { inboundCode: 'IN-2' }] })
+    const wrapper = mountView()
+    await flushPromises()
+    expect(wrapper.text()).toContain('同柜组 · 2 票 · 未锁定')
+    expect(wrapper.text()).not.toContain('CLG-9001')
+    await wrapper.get('[aria-label="查看同柜组 · 2 票 · 未锁定成员"]').trigger('click')
+    await flushPromises()
+    expect(getPlatformCoLoadGroupByInboundCode).toHaveBeenCalledWith('IN-1')
+    expect(wrapper.text()).toContain('3 个成员')
+    expect(wrapper.text()).toContain('IN-1')
+    expect(wrapper.text()).toContain('IN-1-B')
+    expect(wrapper.text()).toContain('IN-2')
+    expect(wrapper.text()).not.toContain('ORD-1')
+    expect(wrapper.text()).not.toContain('ORD-2')
+    expect(wrapper.text()).not.toContain('7003')
+    expect(wrapper.text()).not.toContain('5001')
+  })
+
+  it('cancels an ACTIVE group by the clicked member inbound code and preserves dialog error evidence', async () => {
+    const rowsWithGroup = rows.map((row) => ({ ...row, coLoadGroup: { status: 'ACTIVE', memberCount: 2, memberInboundCodes: ['IN-1', 'IN-2'] } }))
+    vi.mocked(listPlatformUnifiedOrders).mockResolvedValue({ records: rowsWithGroup, page: 1, size: 20, total: 2, pages: 1 })
+    vi.mocked(getPlatformCoLoadGroupByInboundCode).mockResolvedValue({ status: 'ACTIVE', memberCount: 2, members: [{ inboundCode: 'IN-1' }, { inboundCode: 'IN-2' }] })
+    vi.mocked(cancelPlatformCoLoadGroup).mockRejectedValueOnce(new ApiResponseError('组已被并发锁定', 'A0409', 409, undefined, 'request-cancel', 'trace-cancel'))
+    const wrapper = mountView()
+    await flushPromises()
+    await wrapper.get('[aria-label="查看同柜组 · 2 票 · 未锁定成员"]').trigger('click')
+    await flushPromises()
+    const cancelButton = wrapper.findAll('button').find((button) => button.text() === '解除同柜组')!
+    expect(cancelButton.exists()).toBe(true)
+    await cancelButton.trigger('click')
+    await flushPromises()
+
+    expect(ElMessageBox.confirm).toHaveBeenCalledWith(expect.stringContaining('解除整个同柜组'), '解除同柜组', expect.objectContaining({ confirmButtonText: '确认解除' }))
+    expect(cancelPlatformCoLoadGroup).toHaveBeenCalledWith('IN-1', '重新调整同柜组成员')
+    expect(wrapper.text()).toContain('组已被并发锁定')
+    expect(wrapper.text()).toContain('A0409 request-cancel trace-cancel')
+    expect(wrapper.findAllComponents({ name: 'AppDialog' }).some((dialog) => dialog.props('modelValue') === true)).toBe(true)
+    expect(wrapper.text()).not.toContain('CLG-')
+    expect(wrapper.text()).not.toContain('5001')
+  })
+
+  it('closes and refreshes after one successful whole-group cancellation request', async () => {
+    const rowsWithGroup = rows.map((row) => ({ ...row, coLoadGroup: { status: 'ACTIVE', memberCount: 2, memberInboundCodes: ['IN-1', 'IN-2'] } }))
+    vi.mocked(listPlatformUnifiedOrders).mockResolvedValue({ records: rowsWithGroup, page: 1, size: 20, total: 2, pages: 1 })
+    vi.mocked(getPlatformCoLoadGroupByInboundCode).mockResolvedValue({ status: 'ACTIVE', memberCount: 2, members: [{ inboundCode: 'IN-1' }, { inboundCode: 'IN-2' }] })
+    vi.mocked(cancelPlatformCoLoadGroup).mockResolvedValue({} as never)
+    const wrapper = mountView()
+    await flushPromises()
+    await wrapper.get('[aria-label="查看同柜组 · 2 票 · 未锁定成员"]').trigger('click')
+    await flushPromises()
+    await wrapper.findAll('button').find((button) => button.text() === '解除同柜组')!.trigger('click')
+    await flushPromises()
+
+    expect(cancelPlatformCoLoadGroup).toHaveBeenCalledTimes(1)
+    expect(cancelPlatformCoLoadGroup).toHaveBeenCalledWith('IN-1', '重新调整同柜组成员')
+    expect(listPlatformUnifiedOrders).toHaveBeenCalledTimes(2)
+    expect(wrapper.findAllComponents({ name: 'AppDialog' }).every((dialog) => dialog.props('modelValue') !== true)).toBe(true)
+  })
+
+  it.each(['LOCKED', 'CONSUMED'])('does not offer group cancellation for %s', async (status) => {
+    const rowsWithGroup = rows.map((row) => ({ ...row, coLoadGroup: { status, memberCount: 2, memberInboundCodes: ['IN-1', 'IN-2'] } }))
+    vi.mocked(listPlatformUnifiedOrders).mockResolvedValue({ records: rowsWithGroup, page: 1, size: 20, total: 2, pages: 1 })
+    vi.mocked(getPlatformCoLoadGroupByInboundCode).mockResolvedValue({ status: status as 'LOCKED' | 'CONSUMED', memberCount: 2, members: [{ inboundCode: 'IN-1' }, { inboundCode: 'IN-2' }] })
+    const wrapper = mountView()
+    await flushPromises()
+    await wrapper.get(`[aria-label="查看同柜组 · 2 票 · ${status === 'LOCKED' ? '已锁定' : '已消费'}成员"]`).trigger('click')
+    await flushPromises()
+    expect(wrapper.findAll('button').some((button) => button.text() === '解除同柜组')).toBe(false)
+    expect(cancelPlatformCoLoadGroup).not.toHaveBeenCalled()
+  })
+
+  it.each([
+    ['undefined', undefined],
+    ['null', null],
+    ['blank', '   '],
+  ])('keeps the member dialog readable when a normalized inbound code is %s', async (_case, inboundCode) => {
+    const rowsWithGroup = rows.map((row) => ({ ...row, coLoadGroup: { status: 'ACTIVE', memberCount: 2, memberInboundCodes: ['IN-1', 'IN-2'] } }))
+    vi.mocked(listPlatformUnifiedOrders).mockResolvedValue({ records: rowsWithGroup, page: 1, size: 20, total: 2, pages: 1 })
+    vi.mocked(getPlatformCoLoadGroupByInboundCode).mockResolvedValue({ status: 'ACTIVE', memberCount: 2, members: [{ inboundCode: inboundCode as unknown as string }, { inboundCode: 'IN-2' }] })
+    const wrapper = mountView()
+    await flushPromises()
+    await wrapper.get('[aria-label="查看同柜组 · 2 票 · 未锁定成员"]').trigger('click')
+    await flushPromises()
+    expect(wrapper.text()).toContain('同柜组成员入仓码尚未返回，请刷新后重试')
+    expect(wrapper.text()).not.toContain('CLG-9001')
+    expect(wrapper.text()).not.toContain('ORD-1')
+    expect(wrapper.text()).not.toContain('5001')
+  })
+})
diff --git a/src/modules/unified-orders/pages/UnifiedOrdersView.fulfillment.test.ts b/src/modules/unified-orders/pages/UnifiedOrdersView.fulfillment.test.ts
new file mode 100644
index 00000000..08be6a85
--- /dev/null
+++ b/src/modules/unified-orders/pages/UnifiedOrdersView.fulfillment.test.ts
@@ -0,0 +1,428 @@
+import { flushPromises, shallowMount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { getLoadingAssociationSummary, getOverseasInboundCodeRelationship } from '@/shared/api/inboundCodeRelations'
+import { downloadPlatformProductImage, getPlatformUnifiedOrder, listPlatformUnifiedOrders } from '@/modules/unified-orders/api/unifiedOrders'
+import { downloadPlatformInboundHoldEvidence, getPlatformInboundHold, holdPlatformInbound, releasePlatformInbound, uploadPlatformInboundHoldEvidence } from '@/modules/inbounds'
+import UnifiedOrdersView from './UnifiedOrdersView.vue'
+
+vi.mock('vue-router', () => ({
+  useRoute: () => ({ params: { orderId: '5001' }, query: { tenantId: '6001' } }),
+  useRouter: () => ({ push: vi.fn() }),
+}))
+const { canPermission } = vi.hoisted(() => ({ canPermission: vi.fn((..._permissions: string[]) => true) }))
+vi.mock('@/core/access/accessPreview', () => ({ useAccessPreviewStore: () => ({ can: canPermission }) }))
+vi.mock('@/modules/iam', () => ({ listPlatformTenants: vi.fn().mockResolvedValue({ records: [], page: 1, size: 200, total: 0, pages: 0 }) }))
+vi.mock('@/modules/warehouses', () => ({ listAllPlatformWarehouses: vi.fn().mockResolvedValue([]) }))
+vi.mock('@/modules/inbounds', () => ({
+  downloadWeightImage: vi.fn(), getInboundMeasurement: vi.fn(),
+  downloadPlatformInboundHoldEvidence: vi.fn(), getPlatformInboundHold: vi.fn(), holdPlatformInbound: vi.fn(), releasePlatformInbound: vi.fn(), uploadPlatformInboundHoldEvidence: vi.fn(),
+  InboundFeePanel: { template: '<div />' }, InboundMeasurementDialog: { template: '<div />' }, MeasurementEvidenceThumbnail: { template: '<div />' },
+}))
+vi.mock('@/modules/unified-orders/workflows', () => ({ UnifiedOrderWorkflowPanel: { template: '<div />' } }))
+vi.mock('@/modules/unified-orders/api/coLoadGroups', () => ({
+  createPlatformCoLoadGroup: vi.fn(), getPlatformCoLoadGroupByInboundCode: vi.fn(),
+}))
+vi.mock('@/shared/api/inboundCodeRelations', () => ({
+  getLoadingAssociationSummary: vi.fn(), getOverseasInboundCodeRelationship: vi.fn(),
+}))
+vi.mock('@/modules/unified-orders/api/unifiedOrders', () => ({
+  updatePlatformUnifiedOrderRemarks: vi.fn(), approvePlatformUnifiedOrder: vi.fn(), batchApprovePlatformUnifiedOrders: vi.fn(),
+  downloadPlatformProductImage: vi.fn(),
+  getPlatformUnifiedOrder: vi.fn(), listPlatformUnifiedOrderFeeDetails: vi.fn(), listPlatformUnifiedOrders: vi.fn(),
+  unifiedOrderStatusOptions: [],
+}))
+
+const detail = {
+  summary: {
+    orderId: '5001', tenantId: '6001', orderNo: 'ORD-HIDDEN', mainStatus: 'WAIT_SPLIT', nextAction: null, relation: null,
+    internalOrderStatus: 'WAIT_SPLIT', customerId: '6001', customerName: '测试客户', channelName: '纽约渠道',
+    receivingWarehouseId: '8', receivingWarehouseName: '义乌仓', destinationWarehouseId: '9', destinationWarehouseName: 'ONT8',
+    inboundId: '7001', inboundVersion: 1, inboundCode: 'NYEXX2608310001', expectedShipDate: null, totalPackageCount: 2,
+    holdFlag: false, currentHoldReason: null,
+    locationCodes: null, actualGrossWeightKg: null, actualVolumeCbm: null, measurement: null, preload: null, loading: null, delivery: null, transport: null,
+    coLoadGroup: null, createdAt: null, updatedAt: null, expectedArrivalAt: null, feeReviewStatus: null, requestedPickupAt: null,
+    totalPalletCount: null, chargeableVolumeCbm: null, volumetricWeightKg: null, totalNetWeightKg: null,
+    measurementCompletedAt: null, inboundCompletedAt: null, expressCompany: null, expressTrackingNo: null, skuNos: null,
+    totalQuantity: null, shipmentId: null, referenceId: null,
+  },
+  order: { order: null, cargoes: [], parties: [], internalNotes: [], statusHistory: [] },
+  timeline: [],
+}
+
+function mountDetail() {
+  return shallowMount(UnifiedOrdersView, {
+    global: {
+      directives: { loading: () => undefined },
+      stubs: {
+        AdminPage: { template: '<main><slot /></main>' },
+        DetailPageLayout: { template: '<section><slot /></section>' },
+        OrderFulfillmentTreePanel: { template: '<div data-testid="fulfillment-tree" />' },
+        LoadErrorState: { props: ['title', 'message'], template: '<div>{{ title }} {{ message }}<slot name="details" /></div>' },
+        ApiErrorMeta: true,
+        StatusBadge: true,
+        'el-button': { template: '<button @click="$emit(\'click\')"><slot /></button>' },
+        'el-table': { props: ['data'], template: '<div><slot /></div>' },
+        'el-table-column': { template: '<div />' },
+        'el-tag': { template: '<span><slot /></span>' },
+        'el-empty': { props: ['description'], template: '<div>{{ description }}</div>' },
+        'el-alert': { props: ['title'], template: '<div>{{ title }}</div>' },
+      },
+    },
+  })
+}
+
+describe('UnifiedOrdersView downstream fulfillment detail', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    canPermission.mockImplementation(() => true)
+    vi.mocked(getPlatformUnifiedOrder).mockResolvedValue(detail as never)
+    vi.mocked(downloadPlatformProductImage).mockResolvedValue(new Blob(['image'], { type: 'image/png' }))
+    vi.mocked(listPlatformUnifiedOrders).mockResolvedValue({ records: [], page: 1, size: 20, total: 0, pages: 0 })
+    vi.mocked(uploadPlatformInboundHoldEvidence).mockResolvedValue({
+      fileId: '9007199254740999', fileName: '扣货说明.pdf', contentType: 'application/pdf', sizeBytes: 8,
+    })
+    vi.mocked(downloadPlatformInboundHoldEvidence).mockResolvedValue(new Blob(['evidence'], { type: 'application/pdf' }))
+    vi.mocked(getPlatformInboundHold).mockResolvedValue({
+      inboundId: '7001', tenantId: '6001', holdFlag: false, currentHoldReason: null, version: 3,
+      canHold: true, canRelease: false, actionBlockReason: null,
+      history: [{ id: '8801', action: 'RELEASE', reason: '货款已核对', evidenceFileId: '9901', operatorName: '操作员A', operatedAt: '2026-09-07T10:00:00' }],
+    })
+    vi.mocked(holdPlatformInbound).mockResolvedValue({
+      inboundId: '7001', tenantId: '6001', holdFlag: true, currentHoldReason: '等待客户补款', version: 4,
+      canHold: false, canRelease: true, actionBlockReason: null, history: [],
+    })
+    vi.mocked(releasePlatformInbound).mockResolvedValue({
+      inboundId: '7001', tenantId: '6001', holdFlag: false, currentHoldReason: null, version: 4,
+      canHold: true, canRelease: false, actionBlockReason: null, history: [],
+    })
+    vi.mocked(getLoadingAssociationSummary).mockResolvedValue({
+      inboundId: '7001', inboundCode: 'NYEXX2608310001', loadingPlanId: null, loadingPlanNo: null,
+      containerBookingId: null, cabinetNo: null, containerNo: null, loadingStatus: null, taskId: null,
+      pdaTaskStatus: null, coLoadGroupId: null, coLoadGroupNo: null, items: [],
+    })
+    vi.mocked(getOverseasInboundCodeRelationship).mockResolvedValue({
+      inboundCode: 'NYEXX2608310001', found: false, customer: null, overseasWarehouse: null,
+      overseasReceivingStatus: null, taillegOrders: [], inboundPlans: [], palletCodes: [], inventory: [],
+    })
+  })
+
+  it('downloads one preview for cargo rows sharing the same product image', async () => {
+    vi.mocked(getPlatformUnifiedOrder).mockResolvedValue({
+      ...detail,
+      order: {
+        ...detail.order,
+        cargoes: [1, 2, 3, 4].map((itemNo) => ({ itemNo, productImageFileId: '9901' })),
+      },
+    } as never)
+    mountDetail()
+    await flushPromises()
+    expect(downloadPlatformProductImage).toHaveBeenCalledTimes(1)
+    expect(downloadPlatformProductImage).toHaveBeenCalledWith('6001', '9901')
+  })
+
+  it('shows a compact empty state in order detail when no downstream relationship exists', async () => {
+    const wrapper = mountDetail()
+    await flushPromises()
+    await wrapper.findAll('.detail-tabs button').find((button) => button.text().includes('拆分履约'))!.trigger('click')
+    await flushPromises()
+    expect(getLoadingAssociationSummary).toHaveBeenCalledWith('NYEXX2608310001')
+    expect(getOverseasInboundCodeRelationship).toHaveBeenCalledWith('NYEXX2608310001')
+    expect(wrapper.text()).toContain('暂无后续履约数据')
+    expect(wrapper.text()).not.toContain('新增关联')
+  })
+
+  it('renders actual loading and overseas business identifiers inside order detail', async () => {
+    vi.mocked(getLoadingAssociationSummary).mockResolvedValue({
+      inboundId: '7001', inboundCode: 'NYEXX2608310001', loadingPlanId: '9001', loadingPlanNo: 'LP-260831-001',
+      containerBookingId: '9002', cabinetNo: 'CAB-260831-001', containerNo: 'MSCU1234567', loadingStatus: 'LOADING',
+      taskId: '9003', pdaTaskStatus: 'IN_PROGRESS', coLoadGroupId: null, coLoadGroupNo: null, items: [],
+    })
+    vi.mocked(getOverseasInboundCodeRelationship).mockResolvedValue({
+      inboundCode: 'NYEXX2608310001', found: true, customer: null,
+      overseasWarehouse: { warehouseId: '9004', warehouseCode: 'LAX', warehouseName: '洛杉矶海外仓' },
+      overseasReceivingStatus: 'RECEIVING', taillegOrders: [{ orderNo: 'LL-260831-001' }],
+      inboundPlans: [{ planNo: 'IP-260831-001' }], palletCodes: ['PLT-LAX-001'],
+      inventory: [{ skuCode: 'SKU-001', packageCount: 2 }],
+    })
+    const wrapper = mountDetail()
+    await flushPromises()
+    await wrapper.findAll('.detail-tabs button').find((button) => button.text().includes('拆分履约'))!.trigger('click')
+    await flushPromises()
+    expect(wrapper.text()).toContain('LP-260831-001')
+    expect(wrapper.text()).toContain('MSCU1234567')
+    expect(wrapper.text()).toContain('LL-260831-001')
+    expect(wrapper.text()).toContain('IP-260831-001')
+    expect(wrapper.text()).toContain('PLT-LAX-001')
+    expect(wrapper.text()).not.toContain('9001')
+    expect(wrapper.text()).not.toContain('9004')
+  })
+
+  it('loads server hold capabilities and history only after opening the other tab', async () => {
+    const wrapper = mountDetail()
+    await flushPromises()
+    expect(getPlatformInboundHold).not.toHaveBeenCalled()
+    await wrapper.findAll('.detail-tabs button').find((button) => button.text().includes('其他'))!.trigger('click')
+    await flushPromises()
+    expect(getPlatformInboundHold).toHaveBeenCalledWith('6001', '7001')
+    expect(wrapper.text()).toContain('未扣货')
+    const loaded = (wrapper.vm as unknown as { holdDetail: { history: Array<{ reason: string; evidenceFileId: string }> } }).holdDetail
+    expect(loaded.history).toEqual([expect.objectContaining({ reason: '货款已核对', evidenceFileId: '9901' })])
+    expect(wrapper.findAll('button').map((button) => button.text())).toContain('扣货')
+  })
+
+  it('submits the required reason and server version, then refreshes detail and list', async () => {
+    const wrapper = mountDetail()
+    await flushPromises()
+    await wrapper.findAll('.detail-tabs button').find((button) => button.text().includes('其他'))!.trigger('click')
+    await flushPromises()
+    const vm = wrapper.vm as unknown as { holdReason: string; openHoldDialog(action: 'HOLD'): void; submitHoldAction(): Promise<void> }
+    vm.openHoldDialog('HOLD')
+    vm.holdReason = ' 等待客户补款 '
+    await vm.submitHoldAction()
+    expect(holdPlatformInbound).toHaveBeenCalledWith('6001', '7001', { expectedVersion: 3, reason: '等待客户补款' })
+    expect(getPlatformUnifiedOrder).toHaveBeenCalledTimes(2)
+    expect(listPlatformUnifiedOrders).toHaveBeenCalledTimes(1)
+  })
+
+  it('exposes loading, empty and error states for the lazy hold request', async () => {
+    let resolveHold!: (value: Awaited<ReturnType<typeof getPlatformInboundHold>>) => void
+    vi.mocked(getPlatformInboundHold).mockImplementationOnce(() => new Promise((resolve) => { resolveHold = resolve }))
+    const wrapper = mountDetail()
+    await flushPromises()
+    await wrapper.findAll('.detail-tabs button').find((button) => button.text().includes('其他'))!.trigger('click')
+    expect((wrapper.vm as unknown as { holdLoading: boolean }).holdLoading).toBe(true)
+    resolveHold({
+      inboundId: '7001', tenantId: '6001', holdFlag: false, currentHoldReason: null, version: 3,
+      canHold: true, canRelease: false, actionBlockReason: null, history: [],
+    })
+    await flushPromises()
+    const loadedVm = wrapper.vm as unknown as { holdLoading: boolean; holdDetail: { history: unknown[] } }
+    expect(loadedVm.holdLoading).toBe(false)
+    expect(loadedVm.holdDetail.history).toEqual([])
+    expect(wrapper.text()).toContain('扣货历史')
+
+    vi.mocked(getPlatformInboundHold).mockRejectedValueOnce(new Error('网络断开'))
+    await (wrapper.vm as unknown as { loadHoldDetail(force: boolean): Promise<void> }).loadHoldDetail(true)
+    expect(wrapper.text()).toContain('扣货状态与历史加载失败')
+    expect((wrapper.vm as unknown as { holdError: { message: string } }).holdError.message).toBe('扣货状态与历史加载失败')
+  })
+
+  it('rejects blank and over-limit reasons while accepting exactly 1000 characters', async () => {
+    const wrapper = mountDetail()
+    await flushPromises()
+    await wrapper.findAll('.detail-tabs button').find((button) => button.text().includes('其他'))!.trigger('click')
+    await flushPromises()
+    const vm = wrapper.vm as unknown as {
+      holdReason: string
+      openHoldDialog(action: 'HOLD'): void
+      submitHoldAction(): Promise<void>
+    }
+    vm.openHoldDialog('HOLD')
+    vm.holdReason = '   '
+    await vm.submitHoldAction()
+    vm.holdReason = 'a'.repeat(1001)
+    await vm.submitHoldAction()
+    expect(holdPlatformInbound).not.toHaveBeenCalled()
+
+    vm.holdReason = 'a'.repeat(1000)
+    await vm.submitHoldAction()
+    expect(holdPlatformInbound).toHaveBeenCalledOnce()
+    expect(holdPlatformInbound).toHaveBeenCalledWith('6001', '7001', {
+      expectedVersion: 3,
+      reason: 'a'.repeat(1000),
+    })
+  })
+
+  it('prevents duplicate submissions while the hold request is pending', async () => {
+    let resolveCommand!: (value: Awaited<ReturnType<typeof holdPlatformInbound>>) => void
+    vi.mocked(holdPlatformInbound).mockImplementationOnce(() => new Promise((resolve) => { resolveCommand = resolve }))
+    const wrapper = mountDetail()
+    await flushPromises()
+    await wrapper.findAll('.detail-tabs button').find((button) => button.text().includes('其他'))!.trigger('click')
+    await flushPromises()
+    const vm = wrapper.vm as unknown as {
+      holdReason: string
+      holdSaving: boolean
+      openHoldDialog(action: 'HOLD'): void
+      submitHoldAction(): Promise<void>
+    }
+    vm.openHoldDialog('HOLD')
+    vm.holdReason = '等待客户补款'
+    const first = vm.submitHoldAction()
+    const duplicate = vm.submitHoldAction()
+    await duplicate
+    expect(vm.holdSaving).toBe(true)
+    expect(holdPlatformInbound).toHaveBeenCalledOnce()
+    resolveCommand({
+      inboundId: '7001', tenantId: '6001', holdFlag: true, currentHoldReason: '等待客户补款', version: 4,
+      canHold: false, canRelease: true, actionBlockReason: null, history: [],
+    })
+    await first
+    expect(vm.holdSaving).toBe(false)
+  })
+
+  it('keeps the dialog and reason when a stale-version submission fails', async () => {
+    vi.mocked(holdPlatformInbound).mockRejectedValueOnce(Object.assign(new Error('扣货状态已变化，请刷新后重试'), { code: 'A0409' }))
+    const wrapper = mountDetail()
+    await flushPromises()
+    await wrapper.findAll('.detail-tabs button').find((button) => button.text().includes('其他'))!.trigger('click')
+    await flushPromises()
+    const vm = wrapper.vm as unknown as {
+      holdReason: string
+      holdDialogOpen: boolean
+      openHoldDialog(action: 'HOLD'): void
+      submitHoldAction(): Promise<void>
+    }
+    vm.openHoldDialog('HOLD')
+    vm.holdReason = '等待客户补款'
+    await vm.submitHoldAction()
+    expect(holdPlatformInbound).toHaveBeenCalledWith('6001', '7001', { expectedVersion: 3, reason: '等待客户补款' })
+    expect(vm.holdDialogOpen).toBe(true)
+    expect(vm.holdReason).toBe('等待客户补款')
+    expect(getPlatformUnifiedOrder).toHaveBeenCalledOnce()
+    expect(listPlatformUnifiedOrders).not.toHaveBeenCalled()
+  })
+
+  it('does not submit the command when evidence upload fails and preserves the form', async () => {
+    vi.mocked(uploadPlatformInboundHoldEvidence).mockRejectedValueOnce(new Error('文件服务不可用'))
+    const wrapper = mountDetail()
+    await flushPromises()
+    await wrapper.findAll('.detail-tabs button').find((button) => button.text().includes('其他'))!.trigger('click')
+    await flushPromises()
+    const evidence = new File(['evidence'], '扣货说明.pdf', { type: 'application/pdf' })
+    const vm = wrapper.vm as unknown as {
+      holdReason: string
+      holdDialogOpen: boolean
+      holdEvidenceFile: File | null
+      holdEvidenceError: { message: string } | null
+      openHoldDialog(action: 'HOLD'): void
+      selectHoldEvidenceFile(upload: { raw: File }): void
+      submitHoldAction(): Promise<void>
+    }
+    vm.openHoldDialog('HOLD')
+    vm.holdReason = '等待客户补款'
+    vm.selectHoldEvidenceFile({ raw: evidence })
+    await vm.submitHoldAction()
+    expect(uploadPlatformInboundHoldEvidence).toHaveBeenCalledWith('6001', '7001', evidence)
+    expect(holdPlatformInbound).not.toHaveBeenCalled()
+    expect(vm.holdDialogOpen).toBe(true)
+    expect(vm.holdReason).toBe('等待客户补款')
+    expect(vm.holdEvidenceFile).toBe(evidence)
+    expect(vm.holdEvidenceError?.message).toBe('关联文件上传失败，请稍后重试')
+  })
+
+  it('uploads optional evidence once and submits its long identifier', async () => {
+    const wrapper = mountDetail()
+    await flushPromises()
+    await wrapper.findAll('.detail-tabs button').find((button) => button.text().includes('其他'))!.trigger('click')
+    await flushPromises()
+    const evidence = new File(['evidence'], '扣货说明.pdf', { type: 'application/pdf' })
+    const vm = wrapper.vm as unknown as {
+      holdReason: string
+      openHoldDialog(action: 'HOLD'): void
+      selectHoldEvidenceFile(upload: { raw: File }): void
+      submitHoldAction(): Promise<void>
+    }
+    vm.openHoldDialog('HOLD')
+    vm.holdReason = '等待客户补款'
+    vm.selectHoldEvidenceFile({ raw: evidence })
+    await vm.submitHoldAction()
+    expect(uploadPlatformInboundHoldEvidence).toHaveBeenCalledOnce()
+    expect(holdPlatformInbound).toHaveBeenCalledWith('6001', '7001', {
+      expectedVersion: 3,
+      reason: '等待客户补款',
+      evidenceFileId: '9007199254740999',
+    })
+  })
+
+  it('rejects unsafe evidence extensions, empty files and files over 10MB', async () => {
+    const wrapper = mountDetail()
+    await flushPromises()
+    await wrapper.findAll('.detail-tabs button').find((button) => button.text().includes('其他'))!.trigger('click')
+    await flushPromises()
+    const vm = wrapper.vm as unknown as {
+      holdEvidenceFile: File | null
+      holdEvidenceError: { code: string } | null
+      openHoldDialog(action: 'HOLD'): void
+      selectHoldEvidenceFile(upload: { raw: File }): void
+    }
+    vm.openHoldDialog('HOLD')
+    vm.selectHoldEvidenceFile({ raw: new File(['run'], '恶意程序.exe') })
+    expect(vm.holdEvidenceFile).toBeNull()
+    expect(vm.holdEvidenceError?.code).toBe('FILE_TYPE_INVALID')
+
+    vm.selectHoldEvidenceFile({ raw: new File([], '空文件.txt', { type: 'text/plain' }) })
+    expect(vm.holdEvidenceError?.code).toBe('FILE_SIZE_INVALID')
+    const oversized = new File(['x'], '过大文件.png', { type: 'image/png' })
+    Object.defineProperty(oversized, 'size', { value: 10 * 1024 * 1024 + 1 })
+    vm.selectHoldEvidenceFile({ raw: oversized })
+    expect(vm.holdEvidenceError?.code).toBe('FILE_SIZE_INVALID')
+    expect(uploadPlatformInboundHoldEvidence).not.toHaveBeenCalled()
+  })
+
+  it('downloads associated evidence once while a repeated click is pending', async () => {
+    let resolveDownload!: (value: Blob) => void
+    vi.mocked(downloadPlatformInboundHoldEvidence).mockImplementationOnce(() => new Promise((resolve) => { resolveDownload = resolve }))
+    Object.defineProperty(URL, 'createObjectURL', { configurable: true, value: vi.fn(() => 'blob:hold-evidence') })
+    Object.defineProperty(URL, 'revokeObjectURL', { configurable: true, value: vi.fn() })
+    const click = vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(() => undefined)
+    const wrapper = mountDetail()
+    await flushPromises()
+    const vm = wrapper.vm as unknown as { downloadHoldEvidence(fileId: string): Promise<void>; holdDownloadingFileId: string }
+    const first = vm.downloadHoldEvidence('9007199254740999')
+    const duplicate = vm.downloadHoldEvidence('9007199254740999')
+    await duplicate
+    expect(downloadPlatformInboundHoldEvidence).toHaveBeenCalledOnce()
+    expect(vm.holdDownloadingFileId).toBe('9007199254740999')
+    resolveDownload(new Blob(['evidence'], { type: 'application/pdf' }))
+    await first
+    expect(downloadPlatformInboundHoldEvidence).toHaveBeenCalledWith('6001', '7001', '9007199254740999')
+    expect(click).toHaveBeenCalledOnce()
+    expect(URL.revokeObjectURL).toHaveBeenCalledWith('blob:hold-evidence')
+    expect(vm.holdDownloadingFileId).toBe('')
+  })
+
+  it('submits release with the current server version and refreshes detail and list', async () => {
+    vi.mocked(getPlatformInboundHold).mockResolvedValueOnce({
+      inboundId: '7001', tenantId: '6001', holdFlag: true, currentHoldReason: '等待客户补款', version: 8,
+      canHold: false, canRelease: true, actionBlockReason: null, history: [],
+    })
+    const wrapper = mountDetail()
+    await flushPromises()
+    await wrapper.findAll('.detail-tabs button').find((button) => button.text().includes('其他'))!.trigger('click')
+    await flushPromises()
+    const vm = wrapper.vm as unknown as {
+      holdReason: string
+      openHoldDialog(action: 'RELEASE'): void
+      submitHoldAction(): Promise<void>
+    }
+    vm.openHoldDialog('RELEASE')
+    vm.holdReason = '货款已核对'
+    await vm.submitHoldAction()
+    expect(releasePlatformInbound).toHaveBeenCalledWith('6001', '7001', { expectedVersion: 8, reason: '货款已核对' })
+    expect(getPlatformUnifiedOrder).toHaveBeenCalledTimes(2)
+    expect(listPlatformUnifiedOrders).toHaveBeenCalledTimes(1)
+  })
+
+  it('stays read-only without the independent hold permission', async () => {
+    canPermission.mockImplementation((...permissions: string[]) => permissions[0] !== 'platform:firstleg:inbound:hold')
+    const wrapper = mountDetail()
+    await flushPromises()
+    await wrapper.findAll('.detail-tabs button').find((button) => button.text().includes('其他'))!.trigger('click')
+    await flushPromises()
+    expect(getPlatformInboundHold).toHaveBeenCalledWith('6001', '7001')
+    expect(wrapper.text()).toContain('未扣货')
+    expect(wrapper.findAll('button').map((button) => button.text())).not.toEqual(expect.arrayContaining(['扣货', '解除扣货']))
+  })
+
+  it('stays read-only and does not request hold detail before an inbound exists', async () => {
+    vi.mocked(getPlatformUnifiedOrder).mockResolvedValue({ ...detail, summary: { ...detail.summary, inboundId: null, inboundCode: null, holdFlag: null, currentHoldReason: null } } as never)
+    const wrapper = mountDetail()
+    await flushPromises()
+    await wrapper.findAll('.detail-tabs button').find((button) => button.text().includes('其他'))!.trigger('click')
+    await flushPromises()
+    expect(getPlatformInboundHold).not.toHaveBeenCalled()
+    expect(wrapper.text()).toContain('订单尚未生成入库单，扣货状态仅可查看')
+    expect(wrapper.findAll('button').map((button) => button.text())).not.toEqual(expect.arrayContaining(['扣货', '解除扣货']))
+  })
+})
diff --git a/src/modules/unified-orders/pages/UnifiedOrdersView.requests.test.ts b/src/modules/unified-orders/pages/UnifiedOrdersView.requests.test.ts
new file mode 100644
index 00000000..f9ecc135
--- /dev/null
+++ b/src/modules/unified-orders/pages/UnifiedOrdersView.requests.test.ts
@@ -0,0 +1,258 @@
+import { flushPromises, shallowMount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { listPlatformUnifiedOrders, updatePlatformUnifiedOrderPlanning } from '@/modules/unified-orders/api/unifiedOrders'
+import { createPlatformExportTask } from '@/modules/downloads'
+import { showExportTaskCreatedDialog } from '@/shared/components/exportTaskCreatedDialog'
+import { ApiResponseError } from '@/shared/api/http'
+import { ElMessage } from 'element-plus'
+import UnifiedOrdersView from './UnifiedOrdersView.vue'
+
+vi.mock('vue-router', () => ({
+  useRoute: () => ({ params: {}, query: {} }),
+  useRouter: () => ({ push: vi.fn() }),
+}))
+vi.mock('@/core/access/accessPreview', () => ({ useAccessPreviewStore: () => ({ can: () => true }) }))
+vi.mock('@/modules/iam', () => ({ listPlatformTenants: vi.fn().mockResolvedValue({ records: [], page: 1, size: 200, total: 0, pages: 0 }) }))
+vi.mock('@/modules/warehouses', () => ({ listAllPlatformWarehouses: vi.fn().mockResolvedValue([]) }))
+vi.mock('@/modules/inbounds', () => ({ downloadWeightImage: vi.fn(), getInboundMeasurement: vi.fn() }))
+vi.mock('@/modules/downloads', () => ({ createPlatformExportTask: vi.fn() }))
+vi.mock('@/shared/components/exportTaskCreatedDialog', () => ({ showExportTaskCreatedDialog: vi.fn() }))
+vi.mock('@/modules/unified-orders/workflows', () => ({ UnifiedOrderWorkflowPanel: { template: '<div />' } }))
+vi.mock('@/modules/unified-orders/api/coLoadGroups', () => ({
+  cancelPlatformCoLoadGroup: vi.fn(),
+  createPlatformCoLoadGroup: vi.fn(),
+  getPlatformCoLoadGroupByInboundCode: vi.fn(),
+}))
+vi.mock('@/modules/unified-orders/api/unifiedOrders', () => ({
+  updatePlatformUnifiedOrderRemarks: vi.fn(),
+  approvePlatformUnifiedOrder: vi.fn(),
+  getPlatformUnifiedOrder: vi.fn(),
+  listPlatformUnifiedOrderFeeDetails: vi.fn(),
+  listPlatformUnifiedOrders: vi.fn(),
+  updatePlatformUnifiedOrderPlanning: vi.fn(),
+  unifiedOrderStatusOptions: [
+    { value: 'PENDING_REVIEW', label: '待审核' },
+    { value: 'WAIT_MEASURE', label: '待测量数据' },
+    { value: 'WAIT_SPLIT', label: '待分柜' },
+    { value: 'LOADING', label: '装柜中' },
+    { value: 'LOADED', label: '装柜完成' },
+    { value: 'DELIVERED', label: '派送完成' },
+    { value: 'COMPLETED', label: '已完成' },
+  ],
+}))
+
+function emptyPage() {
+  return { records: [], page: 1, size: 20, total: 0, pages: 0 }
+}
+
+function mountView() {
+  return shallowMount(UnifiedOrdersView, {
+    global: {
+      directives: { loading: () => undefined },
+      stubs: {
+        AdminPage: { template: '<main><slot /></main>' },
+        ListPageLayout: { template: '<section><slot name="toolbar" /><slot name="state" /><slot /></section>' },
+        QueryToolbar: { name: 'QueryToolbar', props: ['modelValue'], emits: ['update:modelValue', 'search', 'reset'], template: '<div data-testid="query-toolbar" />' },
+        DataTable: { name: 'DataTable', props: ['page', 'pageSize', 'data'], emits: ['update:page', 'update:pageSize', 'selection-change'], template: '<div data-testid="data-table"><slot name="toolbar-actions" /><div v-for="row in data" :key="row.orderId" class="test-row"><slot name="estimatedVolume" :row="row" /><slot name="expectedArrival" :row="row" /></div></div>' },
+        'el-button': { template: '<button><slot /></button>' },
+        'el-input-number': { name: 'ElInputNumber', props: ['modelValue', 'disabled'], emits: ['update:modelValue', 'change'], template: '<input class="number-input" :value="modelValue" :disabled="disabled" @change="$emit(\'change\')" />' },
+        'el-date-picker': { name: 'ElDatePicker', props: ['modelValue', 'disabled'], emits: ['update:modelValue', 'change'], template: '<input class="date-input" :value="modelValue" :disabled="disabled" @change="$emit(\'change\')" />' },
+        ApiErrorMeta: { props: ['details'], template: '<code class="api-meta">{{ details.code }} {{ details.requestId }} {{ details.traceId }}</code>' },
+      },
+    },
+  })
+}
+
+describe('UnifiedOrdersView list request coordination', () => {
+  beforeEach(() => {
+    vi.mocked(listPlatformUnifiedOrders).mockReset().mockResolvedValue(emptyPage())
+    vi.mocked(updatePlatformUnifiedOrderPlanning).mockReset()
+    vi.mocked(createPlatformExportTask).mockReset().mockResolvedValue({ taskName: '国内仓订单', taskNo: 'EXP-1' } as never)
+    vi.mocked(showExportTaskCreatedDialog).mockReset().mockResolvedValue(false)
+  })
+
+  it('loads once initially and once for query, reset, status tab and pagination', async () => {
+    const wrapper = mountView()
+    await flushPromises()
+    expect(listPlatformUnifiedOrders).toHaveBeenCalledTimes(1)
+
+    const toolbar = wrapper.getComponent({ name: 'QueryToolbar' })
+    toolbar.vm.$emit('search')
+    await flushPromises()
+    expect(listPlatformUnifiedOrders).toHaveBeenCalledTimes(2)
+
+    toolbar.vm.$emit('reset')
+    await flushPromises()
+    expect(listPlatformUnifiedOrders).toHaveBeenCalledTimes(3)
+
+    await wrapper.findAll('.status-tab')[1]!.trigger('click')
+    await flushPromises()
+    expect(listPlatformUnifiedOrders).toHaveBeenCalledTimes(4)
+
+    wrapper.getComponent({ name: 'DataTable' }).vm.$emit('update:page', 2)
+    await flushPromises()
+    expect(listPlatformUnifiedOrders).toHaveBeenCalledTimes(5)
+  })
+
+  it('does not apply draft filters to pagination until query is submitted', async () => {
+    const wrapper = mountView()
+    await flushPromises()
+    const toolbar = wrapper.getComponent({ name: 'QueryToolbar' })
+    const draft = { ...toolbar.props('modelValue'), inboundCode: ' DRAFT-CODE ' }
+    toolbar.vm.$emit('update:modelValue', draft)
+    await wrapper.vm.$nextTick()
+
+    wrapper.getComponent({ name: 'DataTable' }).vm.$emit('update:page', 2)
+    await flushPromises()
+    expect(listPlatformUnifiedOrders).toHaveBeenLastCalledWith(expect.objectContaining({ page: 2, inboundCode: undefined }))
+
+    toolbar.vm.$emit('search')
+    await flushPromises()
+    expect(listPlatformUnifiedOrders).toHaveBeenCalledTimes(3)
+    expect(listPlatformUnifiedOrders).toHaveBeenLastCalledWith(expect.objectContaining({ page: 1, inboundCode: 'DRAFT-CODE' }))
+  })
+
+  it('resets a later page and changes page size with one request per interaction', async () => {
+    const wrapper = mountView()
+    await flushPromises()
+    const table = wrapper.getComponent({ name: 'DataTable' })
+    const toolbar = wrapper.getComponent({ name: 'QueryToolbar' })
+
+    table.vm.$emit('update:page', 3)
+    await flushPromises()
+    expect(listPlatformUnifiedOrders).toHaveBeenCalledTimes(2)
+
+    toolbar.vm.$emit('reset')
+    await flushPromises()
+    expect(listPlatformUnifiedOrders).toHaveBeenCalledTimes(3)
+    expect(listPlatformUnifiedOrders).toHaveBeenLastCalledWith(expect.objectContaining({ page: 1 }))
+
+    table.vm.$emit('update:pageSize', 50)
+    table.vm.$emit('update:page', 1)
+    await flushPromises()
+    expect(listPlatformUnifiedOrders).toHaveBeenCalledTimes(4)
+    expect(listPlatformUnifiedOrders).toHaveBeenLastCalledWith(expect.objectContaining({ page: 1, size: 50 }))
+  })
+
+  it('does not turn a cleared full-container filter into false', async () => {
+    const wrapper = mountView()
+    await flushPromises()
+    const toolbar = wrapper.getComponent({ name: 'QueryToolbar' })
+    const selected = { ...toolbar.props('modelValue'), fullContainer: 'true' }
+    toolbar.vm.$emit('update:modelValue', selected)
+    toolbar.vm.$emit('search')
+    await flushPromises()
+    expect(listPlatformUnifiedOrders).toHaveBeenLastCalledWith(expect.objectContaining({ fullContainer: true }))
+
+    toolbar.vm.$emit('update:modelValue', { ...selected, fullContainer: undefined })
+    toolbar.vm.$emit('search')
+    await flushPromises()
+    expect(listPlatformUnifiedOrders).toHaveBeenLastCalledWith(expect.objectContaining({ fullContainer: undefined }))
+  })
+
+  it('exports the selected business order numbers without loading other pages', async () => {
+    const wrapper = mountView()
+    await flushPromises()
+    wrapper.getComponent({ name: 'DataTable' }).vm.$emit('selection-change', [
+      { orderId: '1', orderNo: 'ORDER-1', tenantId: '8' },
+      { orderId: '2', orderNo: 'ORDER-2', tenantId: '8' },
+    ])
+    await wrapper.vm.$nextTick()
+
+    await wrapper.findAll('button').find((button) => button.text().includes('导出'))!.trigger('click')
+    await flushPromises()
+
+    expect(createPlatformExportTask).toHaveBeenCalledWith({
+      exportType: 'DOMESTIC_WAREHOUSE_ORDER_LIST', format: 'XLSX', taskName: '国内仓订单-已选2票',
+      parameters: { selectedOrderNos: ['ORDER-1', 'ORDER-2'] },
+    })
+    expect(listPlatformUnifiedOrders).toHaveBeenCalledTimes(1)
+  })
+
+  it('exports every result matching the applied filters instead of the current page', async () => {
+    const wrapper = mountView()
+    await flushPromises()
+    const toolbar = wrapper.getComponent({ name: 'QueryToolbar' })
+    toolbar.vm.$emit('update:modelValue', {
+      ...toolbar.props('modelValue'), inboundCode: ' IN-8 ', loaded: 'false', createdRange: ['2026-08-01', '2026-08-31'],
+    })
+    toolbar.vm.$emit('search')
+    await flushPromises()
+
+    await wrapper.findAll('button').find((button) => button.text() === '导出')!.trigger('click')
+    await flushPromises()
+
+    expect(createPlatformExportTask).toHaveBeenCalledWith(expect.objectContaining({
+      exportType: 'DOMESTIC_WAREHOUSE_ORDER_LIST', taskName: '国内仓订单-当前筛选',
+      parameters: expect.objectContaining({
+        inboundCode: 'IN-8', loaded: false,
+        createdFrom: '2026-08-01T00:00:00', createdTo: '2026-08-31T23:59:59',
+      }),
+    }))
+    expect(createPlatformExportTask).not.toHaveBeenCalledWith(expect.objectContaining({
+      parameters: expect.objectContaining({ page: expect.anything(), size: expect.anything() }),
+    }))
+  })
+
+  it('edits arrival and estimated volume and reports compact failure evidence through a message', async () => {
+    const errorMessage = vi.spyOn(ElMessage, 'error').mockImplementation(() => undefined as never)
+    vi.mocked(listPlatformUnifiedOrders).mockResolvedValue({
+      records: [{
+        orderId: '2089223263733518337', orderVersion: 7, tenantId: '2089176869176389634',
+        internalOrderStatus: 'SUBMITTED',
+        inboundCode: 'NYEXX2609030001', expectedArrivalAt: '2026-09-10T08:30:00', estimatedVolumeCbm: 0.25,
+      }], page: 1, size: 20, total: 1, pages: 1,
+    } as never)
+    vi.mocked(updatePlatformUnifiedOrderPlanning)
+      .mockResolvedValueOnce({ version: 8 } as never)
+      .mockRejectedValueOnce(new ApiResponseError('订单版本已变化', 'A0409', 200, undefined, 'req-planning', 'trace-planning'))
+
+    const wrapper = mountView()
+    await flushPromises()
+    const volume = wrapper.getComponent({ name: 'ElInputNumber' })
+    volume.vm.$emit('update:modelValue', 0.5)
+    volume.vm.$emit('change', 0.5)
+    await flushPromises()
+
+    expect(updatePlatformUnifiedOrderPlanning).toHaveBeenNthCalledWith(1,
+      '2089176869176389634', '2089223263733518337', {
+        expectedVersion: 7, expectedArrivalAt: '2026-09-10T08:30:00', estimatedVolumeCbm: 0.5,
+      })
+
+    const arrival = wrapper.getComponent({ name: 'ElDatePicker' })
+    arrival.vm.$emit('update:modelValue', '2026-09-12T16:00:00')
+    arrival.vm.$emit('change', '2026-09-12T16:00:00')
+    await flushPromises()
+
+    expect(updatePlatformUnifiedOrderPlanning).toHaveBeenNthCalledWith(2,
+      '2089176869176389634', '2089223263733518337', {
+        expectedVersion: 8, expectedArrivalAt: '2026-09-12T16:00:00', estimatedVolumeCbm: 0.5,
+      })
+    expect(wrapper.getComponent({ name: 'ElDatePicker' }).props('modelValue')).toBe('2026-09-12T16:00:00')
+    expect(wrapper.text()).not.toContain('订单版本已变化')
+    expect(wrapper.find('.planning-error').exists()).toBe(false)
+    expect(errorMessage).toHaveBeenCalledWith(expect.objectContaining({
+      message: '订单版本已变化（错误码 A0409；Request ID req-planning；Trace ID trace-planning）',
+      showClose: true,
+    }))
+  })
+
+  it('shows planning values without editors after the order enters irreversible fulfillment', async () => {
+    vi.mocked(listPlatformUnifiedOrders).mockResolvedValue({
+      records: [{
+        orderId: '2099751993783402497', orderVersion: 7, tenantId: '2097708157074210818',
+        internalOrderStatus: 'PROCESSING', mainStatus: 'LOADED', inboundCode: 'AT0E9B5BF2839C6944CFA3',
+        expectedArrivalAt: '2026-10-15T00:00:00', estimatedVolumeCbm: 220,
+      }], page: 1, size: 20, total: 1, pages: 1,
+    } as never)
+
+    const wrapper = mountView()
+    await flushPromises()
+
+    expect(wrapper.findComponent({ name: 'ElInputNumber' }).exists()).toBe(false)
+    expect(wrapper.findComponent({ name: 'ElDatePicker' }).exists()).toBe(false)
+    expect(wrapper.text()).toContain('220')
+    expect(wrapper.text()).toContain('2026-10-15 00:00')
+    expect(updatePlatformUnifiedOrderPlanning).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/modules/unified-orders/pages/UnifiedOrdersView.test.ts b/src/modules/unified-orders/pages/UnifiedOrdersView.test.ts
new file mode 100644
index 00000000..bb13bce3
--- /dev/null
+++ b/src/modules/unified-orders/pages/UnifiedOrdersView.test.ts
@@ -0,0 +1,687 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { unifiedOrderStatusOptions } from '../api/unifiedOrders'
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/unified-orders/pages/UnifiedOrdersView.vue'), 'utf8').replace(/\r\n/g, '\n')
+const routeSource = readFileSync(resolve(process.cwd(), 'src/modules/unified-orders/routes.ts'), 'utf8').replace(/\r\n/g, '\n')
+
+const densitySource = readFileSync(resolve(process.cwd(), 'src/styles/adminDensity.css'), 'utf8')
+
+describe('UnifiedOrdersView contract', () => {
+  it('exposes desktop pallet printing only for one-click dropship orders', () => {
+    expect(source).toContain("detail.value?.summary.fulfillmentType === 'ONE_CLICK_DROPSHIP'")
+    expect(source).toContain("{ key: 'dropship-print', label: '托盘打印', icon: '🖨️' }")
+    expect(source).toContain("activeDetailTab === 'dropship-print'")
+    expect(source).toContain('<DropshipPalletPrintPanel')
+    expect(source).toContain("can('platform:firstleg:inbound:list')")
+  })
+
+  it('loads the reference unit price and lets the backend enforce the combined final lock', () => {
+    const openDialogSource = source.slice(source.indexOf('async function openFeeConfirmDialog()'), source.indexOf('async function executeConfirmAndSendFee()'))
+    const sendFeeSource = source.slice(source.indexOf('async function executeConfirmAndSendFee()'), source.indexOf('function handleOrderSelectionChange'))
+    expect(openDialogSource).toContain('getLatestInboundFee')
+    expect(sendFeeSource).not.toContain('getLatestInboundFee')
+    expect(sendFeeSource).toContain('adjustPublishedInboundFee')
+    expect(source).toContain('价格表参考单价')
+    expect(source).toContain('本次对客单价')
+    expect(sendFeeSource).toContain("ElMessage.error(getApiErrorDetails(error, '确认费用发送失败').message)")
+  })
+
+  it('prevents duplicate confirm-and-send chains and reuses one attempt idempotency key set', () => {
+    const sendFeeSource = source.slice(source.indexOf('async function executeConfirmAndSendFee()'), source.indexOf('function handleOrderSelectionChange'))
+
+    expect(sendFeeSource).toContain('if (confirmFeeSending.value) return')
+    expect(sendFeeSource).toContain('const attempt = currentFeeConfirmAttempt(selectedWeightKg, selectedVolumeCbm, selectedUnitPrice)')
+    expect(sendFeeSource).toContain('attempt.calculateKey')
+    expect(sendFeeSource).toContain('attempt.adjustKey')
+    expect(sendFeeSource).toContain('attempt.confirmKey')
+    expect(sendFeeSource).toContain('attempt.sendKey')
+    expect(sendFeeSource).toContain("if (snapshot.feeStatus === 'SENT')")
+    expect(source).toContain('feeConfirmAttempt = null\n  feeConfirmOpen.value = true')
+  })
+
+  it('exposes the product main statuses including dropship palletizing', () => {
+    expect(unifiedOrderStatusOptions.map((item) => item.label)).toEqual([
+      '待审核', '待测量数据', '待一件代发组托', '待分柜', '装柜中', '装柜完成', '派送完成',
+    ])
+    for (const legacyLabel of ['待客户确认', '差异处理中', '派送中', '进入分柜']) {
+      expect(source).not.toContain(legacyLabel)
+    }
+  })
+
+  it('renders accessible current-status tabs with keyboard navigation', () => {
+    expect(source).toContain('role="tablist"')
+    expect(source).toContain('role="tab"')
+    expect(source).toContain(':aria-selected="selectedStatus === tab.value"')
+    expect(source).toContain("event.key === 'ArrowRight'")
+    expect(source).toContain("event.key === 'ArrowLeft'")
+    expect(source).toContain("event.key === 'Home'")
+    expect(source).toContain("event.key === 'End'")
+  })
+
+  it('provides labeled prototype-aligned advanced filters backed by real query fields', () => {
+    for (const key of [
+      'receivingWarehouseId', 'destinationWarehouseId', 'inboundCode', 'expectedArrivalDate',
+      'feeReviewStatus', 'containerNo', 'cabinetNo', 'channelName', 'sailingDate', 'loaded', 'fullContainer',
+      'measurementReviewStatus', 'fbaCode', 'createdRange',
+    ]) expect(source).toContain(`key: '${key}'`)
+    for (const label of ['定位仓库', '交货仓', '费用审核状态', '是否已配载', '是否整柜', '测量数据审核状态', '商品 SKU 编码']) {
+      expect(source).toContain(`label: '${label}'`)
+    }
+    expect(source).toContain('listAllPlatformWarehouses')
+    expect(source).toContain("{ status: 'ACTIVE' }")
+    expect(source).toContain("warehouse.warehouseType === 'DOMESTIC'")
+    expect(source).toContain("loaded: optionalBoolean(activeFilters.loaded)")
+    expect(source).toContain("fullContainer: optionalBoolean(activeFilters.fullContainer)")
+    expect(source).toContain("{ value: 'UNRECORDED', label: '未录入' }")
+    expect(source).not.toContain("{ value: 'DRAFT', label: '草稿' }")
+    expect(source).not.toContain("{ value: 'CANCELLED', label: '已取消' }")
+    expect(source.match(/key: 'inboundCode', type: 'input'/g)).toHaveLength(1)
+    expect(source).not.toContain("key: 'orderNo', type:")
+    expect(source).not.toContain('internalOrderStatus: filters.value.internalOrderStatus')
+    expect(source).not.toContain("key: 'keyword'")
+    const prototypeFieldOrder = [
+      'receivingWarehouseId', 'destinationWarehouseId', 'inboundCode', 'expectedArrivalDate',
+      'feeReviewStatus', 'tenantId', 'containerNo', 'cabinetNo', 'channelName', 'sailingDate', 'loaded',
+      'fullContainer', 'measurementReviewStatus', 'fbaCode', 'createdRange',
+    ]
+    const fieldPositions = prototypeFieldOrder.map((key) => source.indexOf(`key: '${key}'`))
+    expect(fieldPositions).toEqual([...fieldPositions].sort((left, right) => left - right))
+    expect(source).toContain('preference-key="unified-orders-query-v2"')
+  })
+
+  it('keeps unified filters aligned with the formal query contract and does not expose hold filters', () => {
+    const filterSource = source.slice(source.indexOf('const primaryQueryFields'), source.indexOf('const columns:'))
+    for (const key of ['expectedArrivalDate', 'feeReviewStatus', 'measurementReviewStatus', 'fbaCode', 'loaded', 'fullContainer']) {
+      expect(filterSource).toContain(`key: '${key}'`)
+    }
+    expect(filterSource).not.toContain("key: 'holdCargo'")
+    expect(filterSource).not.toContain("key: 'holdReason'")
+    expect(filterSource).toContain("key: 'fbaCode', type: 'input', width: 220, label: '商品 SKU 编码'")
+    expect(filterSource).not.toContain("label: '商品 FBA 编码'")
+    expect(source).toContain('expectedArrivalDate: activeFilters.expectedArrivalDate || undefined')
+    expect(source).toContain('feeReviewStatus: activeFilters.feeReviewStatus || undefined')
+    expect(source).toContain('measurementReviewStatus: activeFilters.measurementReviewStatus || undefined')
+    expect(source).toContain('fbaCode: trimmed(activeFilters.fbaCode)')
+  })
+
+  it('keeps hold state in the other tab and consumes only frozen server capabilities', () => {
+    for (const marker of [
+      'summary.holdFlag', 'summary.currentHoldReason', 'getPlatformInboundHold',
+      'holdDetail.value?.canHold', 'holdDetail.value?.canRelease', "can('platform:firstleg:inbound:hold')",
+      '扣货历史', '下载凭证', '订单尚未生成入库单，扣货状态仅可查看',
+      'uploadPlatformInboundHoldEvidence', 'downloadPlatformInboundHoldEvidence',
+      '仅支持 TXT、PDF、JPG、PNG，单文件不超过 10MB',
+    ]) expect(source).toContain(marker)
+    expect(source).toContain("await Promise.all([loadDetail(true), loadOrders()])")
+    expect(source).not.toContain('detail.summary.holdCargo')
+    expect(source).not.toContain('detail.summary.holdReason')
+    expect(source).toContain('evidenceFileId: holdUploadedEvidenceFileId.value')
+  })
+
+  it('uses tabs as the only order-status filter and keeps advanced controls inside QueryToolbar', () => {
+    expect(source).toContain('mainStatus: selectedStatus.value || undefined')
+    expect(source).toContain('<template #actions>')
+    expect(source).toContain(':aria-expanded="showAdvancedFilters"')
+    expect(source).not.toContain('class="filter-mode-actions"')
+    expect(source).not.toContain('.filter-mode-actions')
+    expect(source).not.toContain('请选择订单状态')
+  })
+
+  it('covers real list states and keeps operation column first and left-fixed', () => {
+    expect(source).toMatch(/\{ key: 'actions', label: '操作', width: \d+, fixed: 'left'/)
+    expect(source).toContain("key: 'selection', type: 'selection'")
+    expect(source).not.toContain('批量审核接口待接入')
+    expect(source).toContain('@selection-change="handleOrderSelectionChange"')
+    expect(source).toContain('batchApprovePlatformUnifiedOrders')
+    expect(source).toContain('getPlatformUnifiedOrderBatchApprovalPreview')
+    expect(source).toContain('中文品名')
+    expect(source).toContain('确认批量审核')
+    expect(source).toContain('批量审核通过')
+    expect(source).toContain('title="订单列表暂时无法加载"')
+    expect(source).toContain('empty-text="暂无符合条件的订单"')
+    expect(source).toContain(':loading="loading"')
+    expect(source).toContain('v-model:page="page"')
+    expect(source).toContain('v-model:page-size="pageSize"')
+    const columnSource = source.slice(source.indexOf('const columns ='), source.indexOf('function emptyFilters'))
+    const expectedColumnKeys = [
+      'actions', 'inboundCode', 'mainStatus', 'customerName', 'receivingWarehouseName',
+      'destinationWarehouseName', 'channelName', 'totalPackageCount', 'totalPalletCount', 'requestedPickupAt', 'locationCodes', 'measurementReviewStatus', 'actualGrossWeightKg',
+      'actualVolumeCbm', 'totalNetWeightKg', 'chargeableWeightKg', 'chargeableVolumeCbm', 'expectedShipDate',
+      'estimatedVolumeCbm', 'expectedVolumeCbm', 'expectedArrivalAt', 'feeReviewStatus', 'skuNos', 'totalQuantity', 'expressCompany', 'expressTrackingNo',
+      'shipmentId', 'referenceId', 'containerNo', 'cabinetNo',
+      'effectiveSailingAt', 'effectivePortArrivalAt', 'customerRemark', 'latestInternalNote', 'createdAt', 'updatedAt',
+    ]
+    for (const key of expectedColumnKeys) expect(columnSource).toContain(`key: '${key}'`)
+    for (const uncontractedKey of [
+      'internalOrderStatus', 'holdCargo', 'companyName', 'pickupMethod', 'associatedFiles', 'createdBy',
+    ]) expect(columnSource).not.toContain(`key: '${uncontractedKey}'`)
+    const actionsColumnIndex = columnSource.indexOf("key: 'actions'")
+    const selectionColumnIndex = columnSource.indexOf("key: 'selection'")
+    const inboundCodeColumnIndex = columnSource.indexOf("key: 'inboundCode'")
+    expect(actionsColumnIndex).toBeGreaterThanOrEqual(0)
+    expect(selectionColumnIndex).toBeGreaterThan(actionsColumnIndex)
+    expect(inboundCodeColumnIndex).toBeGreaterThan(selectionColumnIndex)
+    expect(columnSource).not.toContain("key: 'coLoadGroup'")
+    expect(columnSource).not.toContain("key: 'orderNo'")
+    expect(columnSource).toContain("key: 'inboundCode', prop: 'inboundCode', label: '入仓码', minWidth: 160, slotName: 'inboundCode'")
+    expect(columnSource).toContain("{ key: 'mainStatus', prop: 'mainStatus', label: '订单主状态'")
+    expect(columnSource).not.toContain("key: 'loadingStatus'")
+    expect(columnSource).not.toContain("key: 'businessDate'")
+    expect(columnSource).not.toContain("label: '业务日期'")
+    expect(columnSource).not.toContain("label: '配载状态'")
+    expect(columnSource).not.toContain("key: 'recommendedPalletType'")
+    expect(columnSource).toContain("key: 'requestedPickupAt', prop: 'requestedPickupAt', label: '预约提货时间'")
+    expect(columnSource.match(/defaultVisible: false/g)).toHaveLength(13)
+    expect(columnSource).toContain("key: 'expectedArrivalAt', prop: 'expectedArrivalAt', label: '预计到货时间', minWidth: 170, slotName: 'expectedArrival' }")
+    expect(columnSource).toContain("key: 'estimatedVolumeCbm', prop: 'estimatedVolumeCbm', label: '预估体积(m³)', minWidth: 120, slotName: 'estimatedVolume' }")
+    expect(columnSource).toContain("key: 'expectedVolumeCbm', prop: 'expectedVolumeCbm', label: '下单体积(m³)', minWidth: 130, slotName: 'field' }")
+    const planningColumnPositions = [
+      columnSource.indexOf("key: 'expectedArrivalAt'"),
+      columnSource.indexOf("key: 'estimatedVolumeCbm'"),
+      columnSource.indexOf("key: 'expectedVolumeCbm'"),
+      columnSource.indexOf("key: 'actualVolumeCbm'"),
+    ]
+    expect(planningColumnPositions).toEqual([...planningColumnPositions].sort((left, right) => left - right))
+    expect(source).toContain("can('platform:order:declaration:edit')")
+    expect(source).toContain('updatePlatformUnifiedOrderPlanning(String(row.tenantId), String(row.orderId)')
+    expect(source).toContain('expectedVersion: row.orderVersion!')
+    expect(source).toContain('type="datetime"')
+    expect(source).toContain('value-format="YYYY-MM-DDTHH:mm:ss"')
+    expect(source).toContain('format="YYYY-MM-DD HH:mm"')
+    expect(source).toContain('ElMessage.error({')
+    expect(source).toContain('Request ID ${details.requestId}')
+    expect(source).not.toContain('class="planning-error"')
+    expect(columnSource).toContain("key: 'effectiveSailingAt', prop: 'effectiveSailingAt', label: '开船时间', minWidth: 180, slotName: 'field' }")
+    expect(columnSource).toContain("key: 'effectivePortArrivalAt', prop: 'effectivePortArrivalAt', label: '到港时间', minWidth: 180, slotName: 'field' }")
+    expect(source).toContain('preference-key="unified-orders-table-v2"')
+    expect(source).toContain("property === 'requestedPickupAt' && (row.pickupMethod !== 'PICKUP' || !value)")
+    expect(source).toContain("property === 'skuNos' ? value.join('、')")
+    expect(source).not.toContain('<dt>推荐托盘类型</dt>')
+    expect(source).toContain("estimated === true ? '预计 ' : ''")
+    expect(source).toContain('row.transport?.effectiveSailingAtEstimated')
+    expect(source).toContain('row.transport?.effectivePortArrivalAtEstimated')
+    expect(source).not.toContain("transport.sailingAt")
+    expect(source).not.toContain("transport.portArrivalAt")
+    expect(source).toMatch(/\.table-card \{[^}]*overflow: hidden;/)
+    expect(source).toContain('slotName: \'measurementReviewStatus\'')
+    expect(source).toContain('unifiedOrderReviewStatusLabel(value, \'未录入\')')
+    expect(source).toContain("{ key: 'customerRemark', prop: 'customerRemark', label: '客户备注'")
+    expect(source).toContain("{ key: 'latestInternalNote', prop: 'latestInternalNote', label: '内部备注'")
+    expect(source.match(/<LineClampText v-if="column\.key === 'remark'"/g)).toHaveLength(3)
+    expect(source).toContain("detail.summary.internalRemark || detail.summary.latestInternalNote || '—'")
+  })
+
+  it('uses ListPageLayout regions for one 16px query-to-table gap', () => {
+    expect(source).toContain('<ListPageLayout ariaLabel="统一订单列表">')
+    expect(source).toContain('<template #toolbar>')
+    expect(source).toContain('<template v-if="loadError" #state>')
+    expect(source).toContain('<template #default>')
+    expect(source).toContain('v-if="!loadError" id="unified-orders-results" class="surface-panel table-panel table-card"')
+    expect(source).not.toContain('class="orders-load-error"')
+    expect(source).not.toContain('.orders-load-error { margin-top: 0; }')
+  })
+
+  it('counts detail in the three directly visible row actions', () => {
+    expect(source).toContain('unifiedOrderSecondaryActions(row).slice(0, 2)')
+    expect(source).toContain('unifiedOrderSecondaryActions(row).slice(2)')
+    expect(source).toContain('@click="openDetail(row as UnifiedOrderResource)">详情</el-button>')
+    expect(source).toContain('v-if="moreUnifiedOrderActions(row as UnifiedOrderResource).length"')
+  })
+
+  it('opens smart loading from the order table toolbar with its own permission', () => {
+    expect(source).toContain("can('platform:firstleg:smart-loading:list')")
+    expect(source).toContain('#toolbar-actions')
+    expect(source).toContain('@click="smartLoadingOpen = true"')
+    expect(source).toContain('<SmartLoadingDialog v-model="smartLoadingOpen" />')
+  })
+
+  it('uses one asynchronous export entry for either selected orders or the applied filter snapshot', () => {
+    expect(source).toContain("exportType: 'DOMESTIC_WAREHOUSE_ORDER_LIST'")
+    expect(source).toContain("parameters: selectedOrderNos.length")
+    expect(source).toContain('? { selectedOrderNos }')
+    expect(source).toContain(': exportFilterParameters()')
+    expect(source).toContain("can('platform:order:export') && can('platform:download:list')")
+    expect(source).not.toContain('page: page.value,\n      size: pageSize.value,\n    })\n    const task = await createPlatformExportTask')
+  })
+
+  it('states only the domestic warehouse and channel qualification without local destination or split blocking', () => {
+    const createSource = source.slice(source.indexOf('function openCoLoadCreate'), source.indexOf('async function batchApproveOrders'))
+    const dialogSource = source.slice(source.indexOf('v-model="coLoadCreateOpen"'), source.indexOf('<AppDrawer v-model="relationOpen"'))
+    expect(dialogSource).toContain('同一国内仓、同一渠道')
+    expect(dialogSource).toContain('目的仓或目的港可以不同')
+    expect(dialogSource).toContain('资格由服务端按完整入仓片段校验')
+    expect(dialogSource).not.toContain('拆子单')
+    expect(createSource).not.toContain('destinationWarehouse')
+    expect(createSource).not.toContain('destinationPort')
+    expect(createSource).not.toContain('splitStatus')
+    expect(createSource).not.toContain('relation')
+    expect(createSource).toContain('createPlatformCoLoadGroup(selectedOrders.value.map((row) => String(row.orderId)))')
+    expect(source).toContain(':disabled="loading || !canCreateCoLoadGroup"')
+    expect(source).toContain('所选订单的平台收货仓不同：')
+    expect(source).toContain('所选订单的渠道不同：')
+    expect(source).toContain('row.channelCode!.trim()')
+    expect(source).not.toContain('String(row.channelName || \'\').trim()')
+    expect(source).not.toContain('请至少勾选 2 票订单后再设为同柜组')
+    expect(source).not.toContain('当前仅选择 1 票：')
+    expect(source).toContain('以下入仓码已有同柜组：')
+    expect(source).toContain('selectable: () => !batchApprovalSaving.value && !coLoadSaving.value')
+    expect(source).not.toContain('isCoLoadRowSelectable')
+    expect(source).not.toContain('<small v-if="coLoadSelectionProblem"')
+  })
+
+  it('uses inbound code as the only list identifier and opens a business-only group dialog', () => {
+    expect(source).not.toContain("{ key: 'coLoadGroup', label: '同柜组'")
+    expect(source).not.toContain('<template #orderNo=')
+    expect(source).toContain('<template #inboundCode="{ row }">')
+    expect(source).toContain("inboundCode || '待生成入仓码'")
+    expect(source).toContain('class="coload-tag-trigger"')
+    expect(source).toContain('coLoadGroupSummary(coLoadGroup(row as UnifiedOrderResource)!)')
+    expect(source).not.toContain('coLoadDetailGroup')
+    expect(source).not.toContain('<span v-else>—</span></template>\n        <template #orderStatus')
+    expect(source).toContain('v-for="member in coLoadDetailMembers"')
+    expect(source).toContain('<thead><tr><th>入仓码</th></tr></thead>')
+    expect(source).toContain('{{ member.inboundCode }}')
+    expect(source).toContain('同柜组成员入仓码尚未返回，请刷新后重试')
+    expect(source).toContain('coLoadDetailHasMissingInboundCodes')
+    expect(source).not.toContain('visibleInboundCode')
+    expect(source).not.toContain('visibleOrderNo')
+    expect(source).not.toContain('<th>订单编码</th>')
+    expect(source).not.toContain('客户 ID')
+    expect(source).toContain("coLoadDetailSummary?.status === 'ACTIVE'")
+    expect(source).toContain('解除同柜组')
+    expect(source).toContain('cancelPlatformCoLoadGroup(inboundCode')
+    expect(source).toContain('<ApiErrorMeta :details="coLoadCancelError"')
+  })
+
+  it('does not expose a generic relationship probe in list rows', () => {
+    expect(source).not.toContain('>履约详情</el-button>')
+    expect(source).not.toContain('>关联数据</el-button>')
+    expect(source).not.toContain('openInboundRelationship')
+    expect(source).not.toContain('inboundRelationshipDialogOpen')
+    expect(source).not.toContain('<InboundCodeRelationshipDialog')
+  })
+
+  it('keeps editable query values separate from the applied list request', () => {
+    expect(source).toContain('const appliedFilters = ref<FilterModel>(emptyFilters())')
+    expect(source).toContain('const activeFilters = appliedFilters.value')
+    expect(source).toContain('appliedFilters.value = cloneFilters(filters.value)')
+    expect(source).toContain('appliedFilters.value = emptyFilters()')
+    expect(source).not.toContain('filters.value.mainStatus')
+  })
+
+  it('keeps only confirmed business actions as explicit boundaries', () => {
+    expect(source).toContain('nextActionBoundary')
+    expect(source).not.toContain('class="action-boundary"')
+    expect(source).toContain("can('platform:firstleg:inbound:measure:view')")
+    expect(source).toContain('openMeasurement')
+    expect(source).toContain('<InboundMeasurementDialog')
+    expect(source).toContain('measurementDialogOpen.value = true')
+    expect(source).toContain('@updated="handleMeasurementUpdated"')
+    expect(source).toContain('@submitted="handleMeasurementSubmitted"')
+    expect(source).not.toContain('<InboundMeasurementPanel')
+    expect(source).not.toContain('class="inbound-task-dialog"')
+    expect(source).not.toContain("name: 'inbound-order-detail'")
+    expect(source).not.toContain('openInboundFromDetail')
+    expect(source).not.toContain('inbound-code-link')
+    expect(source).not.toContain('待接入：智能分柜')
+    expect(source).not.toContain('updateMainStatus')
+    expect(source).not.toContain('人工进入分柜')
+    expect(source).not.toContain('performPlatformUnifiedOrderAction')
+    expect(source).not.toContain('/actions/')
+  })
+
+  it('treats WAIT_SPLIT as a display/filter state without inventing a split action', () => {
+    expect(source).toContain('...unifiedOrderStatusOptions')
+    expect(source).toContain('function nextActionBoundary(row: UnifiedOrderResource)')
+    expect(source).toContain("return row.nextAction === 'CONFIRM_MEASUREMENT' ? '待完成测量' : ''")
+    expect(source).not.toContain('人工进入分柜')
+    expect(source).not.toContain("action === 'split'")
+    expect(source).not.toContain("nextAction === 'SMART_SPLIT'")
+  })
+
+  it('approves pending review orders without exposing an order carrier assignment', () => {
+    expect(source).toContain("row.nextAction === 'APPROVE_ORDER'")
+    expect(source).toContain("can('platform:order:approve')")
+    expect(source).toContain('await approvePlatformUnifiedOrder(tenantId, orderId)')
+    expect(source).toContain('title="审核订单"')
+    expect(source).toContain('confirm-text="审核通过"')
+    expect(source).not.toContain('assignPlatformUnifiedOrderCarrier')
+    expect(source).not.toContain('listPlatformPartners')
+    expect(source).not.toContain('指派承运商')
+    expect(source).not.toContain('待平台指派')
+  })
+
+  it('provides unified detail, history and internal note states', () => {
+    expect(source).toContain('getPlatformUnifiedOrder')
+    expect(source).toContain('aria-label="状态历史"')
+    expect(source).toContain('aria-label="内部备注"')
+    expect(source).toContain('订单详情暂时无法加载')
+    expect(source).toContain('一、客户下单数据')
+    expect(source).toContain('二、外箱规数据')
+    expect(source).toContain('三、实际测量数据')
+    expect(source).toContain('measurementCollapsed = reactive({ customer: false, outer: false, actual: false })')
+    expect(source).toContain('function toggleMeasurementSection(section: keyof typeof measurementCollapsed)')
+    expect(source).toContain(':aria-expanded="!measurementCollapsed.customer"')
+    expect(source).toContain(':aria-expanded="!measurementCollapsed.outer"')
+    expect(source).toContain(':aria-expanded="!measurementCollapsed.actual"')
+    expect(source).toContain('class="measurement-section-summary"')
+    expect(source).toContain('<ChevronUp v-if="!measurementCollapsed.customer"')
+    expect(source).toContain('<ChevronDown v-else :size="18" />')
+    expect(source).toContain("{ key: 'girthCm', label: '箱规周长(cm)' }")
+    expect(source).toContain('label="#" prop="itemNo"')
+    expect(source).toContain("const actualMeasuredColumns = measuredColumns.filter((column) => column.key !== 'itemNo')")
+    expect(source).toContain('v-for="column in actualMeasuredColumns"')
+    expect(source).toContain('仓库修改外箱（长）')
+    expect(source).toContain('仓库修改外箱（宽）')
+    expect(source).toContain('仓库修改外箱（高）')
+    expect(source.match(/class="measurement-outer-dimension-input"/g)).toHaveLength(3)
+    expect(source.match(/label="仓库修改外箱（[长宽高]）" width="190" align="center"/g)).toHaveLength(3)
+    expect(source).toContain('.measurement-outer-dimension-input { width: 128px; max-width: 100%; }')
+    expect(source).toContain('saveWarehouseOuterDimensions')
+    expect(source).toContain("'PREPARING', 'WAIT_MEASURE', 'MEASURING', 'MEASURE_REJECTED'")
+    expect(source.match(/v-if="measurementStrategyEditable"/g)).toHaveLength(4)
+    expect(source).toContain('updateMeasurementOuterDimensions')
+    expect(source).not.toContain('await saveInboundMeasurementDraft(String(summary.tenantId), String(summary.inboundId)')
+    expect(source).not.toContain('请至少输入一项需要修改的外箱尺寸')
+    expect(source).toContain(".map((value) => value == null || value === '' ? null : Number(value))")
+    expect(source).toContain('相关数值已重新计算')
+    expect(source).toContain('runMoreAction($event, row as UnifiedOrderResource)')
+    expect(source).toContain(':aria-label="moreUnifiedOrderActionsLabel(row as UnifiedOrderResource)"')
+    expect(source).toContain(':title="moreUnifiedOrderActionsLabel(row as UnifiedOrderResource)"')
+    expect(source).toContain("can('platform:order:note')")
+    expect(source).toContain('await loadOrders()')
+    expect(source).toContain('orderStatusLabel(detail.summary.internalOrderStatus || detail.summary.mainStatus)')
+    expect(source).toContain('feeReviewLabel(detail.summary.feeReviewStatus)')
+    expect(source).toContain('unifiedOrderLoadingStatusLabel(detail.summary.transport?.loadingStatus)')
+    expect(source).not.toContain("value.replaceAll('_', ' ')")
+  })
+
+  it('keeps customer remarks read-only and edits the three collaboration remarks together', () => {
+    expect(source).toContain('title="编辑订单备注"')
+    expect(source).toContain('label="客户备注（只读）"')
+    expect(source).toContain(':model-value="noteOrder?.customerRemark')
+    expect(source).toContain('v-model="noteForm.internalRemark"')
+    expect(source).toContain('v-model="noteForm.warehouseRemark"')
+    expect(source).toContain('v-model="noteForm.customerServiceRemark"')
+    expect(source).toContain('await updatePlatformUnifiedOrderRemarks')
+  })
+
+  it('keeps the customer order package count independent from measured inbound totals', () => {
+    expect(source).toContain("{ source: '客户下单数据', count: customerTotals.count")
+    expect(source).not.toContain("{ source: '客户下单数据', count: summary?.totalPackageCount")
+  })
+
+  it('uses the inbound measurement girth formula for cargo dimensions', () => {
+    expect(source).toContain('formatNumber(length + 2 * (width + height))')
+    expect(source).not.toContain('formatNumber(2 * (width + height))')
+  })
+
+  it('shows the matched dimension addition and enabled multiplier in calculation choices', () => {
+    expect(source).toContain('getCustomerDimensionConfig')
+    expect(source).toContain('matchingDimensionRule')
+    expect(source).toContain('|| rules[rules.length - 1]')
+    expect(source).toContain('`原尺寸 + ${Number(values[0]) * 2}cm（单边 +${values[0]}cm）`')
+    expect(source).toContain('`原尺寸 × ${rule.lengthFactor}`')
+    expect(source).toContain('label="箱规尺寸" value="ADD"')
+    expect(source).toContain('label="箱规系数" value="MULTIPLY"')
+  })
+
+  it('keeps preview modes independent and persists outer-carton strategy through its dedicated endpoint', () => {
+    expect(source).toContain("measurementSectionModes = reactive<Record<MeasurementSection, MeasurementCalculationMode>>")
+    expect(source).toContain(':model-value="measurementSectionModes.customer"')
+    expect(source).toContain(':model-value="measurementSectionModes.outer"')
+    expect(source).toContain(':model-value="measurementSectionModes.actual"')
+    expect(source).toContain("updateMeasurementSectionMode('customer', $event)")
+    expect(source).toContain("updateMeasurementSectionMode('actual', $event)")
+    expect(source).not.toContain("updateMeasurementSectionMode('outer', $event)")
+    expect(source.match(/@change="selectAndSaveOuterMeasurementMode\(\$event\)"/g)).toHaveLength(1)
+    expect(source).not.toContain('@visible-change="handleOuterModeDropdownVisibleChange($event)"')
+    expect(source.match(/:disabled="Boolean\(measurementStrategySavingId\) \|\| !measurementStrategyEditable"/g)).toHaveLength(1)
+    expect(source).toContain('const measurementStrategyEditable = computed')
+    expect(source).toContain('客户已确认且该票已装柜完成后，箱规计算规则将冻结')
+    expect(source).toContain('if (!measurementStrategyEditable.value)')
+    expect(source).toContain('const previousMode = measurementSectionModes.outer')
+    expect(source).toContain('if (!saved) measurementSectionModes.outer = previousMode')
+    expect(source).not.toContain('handleOuterModeDropdownVisibleChange')
+    expect(source).toContain('const saved = await updateMeasurementCalculationMode(null, mode, ruleId)')
+    expect(source).toContain('calculatedMeasurementRow(row, measurementSectionModes.customer, true)')
+    expect(source).toContain('calculatedMeasurementRow(source, measurementSectionModes.outer)')
+    expect(source).toContain('calculatedMeasurementRow(row as unknown as Record<string, unknown>, measurementSectionModes.actual, false, false)')
+    expect(source).toContain("return Number(hasOuterOverride && override != null && override !== '' ? override : value)")
+    expect(source).toContain("const hasOuterOverride = useWarehouseOuterOverrides && !customerSource")
+    expect(source).not.toContain("!customerSource && mode !== 'ACTUAL'")
+    expect(source).toContain('rawDimensions.map((value) => value + rule.edgeAdditionCm * 2)')
+    expect(source).toContain('matchedSpecificationCoefficient(chargeRule, calculationSource)')
+    expect(source).toContain(".find((item) => item.id === boundChargeRuleId && item.status === 'ACTIVE')")
+    expect(source).toContain('listCustomerChargeRules(customerId, tenantId)')
+    expect(source).toContain('matchedDimensions.map((value) => roundedUp(value * specificationCoefficient, 3))')
+    expect(source).toContain('outerLengthCm: dimensions[0]')
+    expect(source).toContain('outerWidthCm: dimensions[1]')
+    expect(source).toContain('outerHeightCm: dimensions[2]')
+    expect(source).not.toContain('[chargeRule.lengthFactor, chargeRule.widthFactor, chargeRule.heightFactor]')
+    expect(source).not.toContain('column.key === \'coefficientMode\'')
+    expect(source).not.toContain('@change="updateMeasurementCalculationMode(null, $event)"')
+  })
+
+  it('confirms customer billing from the saved outer-carton totals', () => {
+    expect(source).toContain('const outerTotals = measurementTotals(outerMeasurementRows.value)')
+    expect(source).toContain("ElMessage.warning('外箱规数据不完整，请先保存外箱规尺寸和计算规则')")
+    expect(source).toContain("weightSource: 'ACTUAL'")
+    expect(source).toContain("volumeSource: 'ACTUAL'")
+    expect(source).not.toContain('测量审核通过后才能确认并发送费用')
+    expect(source).not.toContain("reviewStatus !== 'APPROVED'")
+    expect(source).toContain('const hasActualMeasurementData = computed(() => (measurementDetail.value?.items?.length ?? 0) > 0)')
+    expect(source).toContain("暂无实际测量数据，不能确认并发送费用")
+    expect(source).not.toContain(':disabled="confirmFeeSending || measurementLoading || !hasActualMeasurementData"')
+    expect(source).toContain('selectAndSaveOuterMeasurementMode($event)')
+    expect(source).toContain('const saved = await updateMeasurementCalculationMode(null, mode, ruleId)')
+    expect(source).toContain('coefficientMode: mode')
+    expect(source).toContain('const savedDraft = await updateMeasurementCalculationStrategy')
+    expect(source).toContain('version: savedDraft.version')
+    expect(source).toContain('waitForSavedMeasurementVersion(')
+    expect(source).toContain('Number(refreshed.version) >= savedVersion')
+    expect(source).toContain('setTimeout(resolve, 250)')
+    expect(source).toContain("chargeRuleId: mode === 'MULTIPLY' ? activeRule!.id : null")
+    expect(source).toContain('calculatedOuterLengthCm: null')
+    expect(source).not.toContain('计算策略保存后回读不一致，请刷新后重试')
+    expect(source).toContain('已保存并绑定计算规则，体积已重新计算')
+    expect(source).toContain('const measuredGrossWeight = Number(measurementDetail.value?.actualGrossWeightKg)')
+    expect(source).toContain('const measuredNetWeight = Number(measurementDetail.value?.actualNetWeightKg)')
+    expect(source).not.toContain('const actualVolume = Number(measurementDetail.value?.actualVolumeCbm)')
+    expect(source).toContain('feeConfirmWeight.value = Number(actualTotals.gross) > 0')
+    expect(source).toContain('feeConfirmVolume.value = Number(actualTotals.volume) > 0')
+    expect(source).toContain("{ source: '实际测量数据', count: actualTotals.count, weight: actualWeight, volume: actualVolume }")
+    const sendFeeSource = source.slice(source.indexOf('async function executeConfirmAndSendFee()'), source.indexOf('function handleOrderSelectionChange'))
+    expect(sendFeeSource).not.toContain('saveInboundMeasurementDraft')
+    expect(sendFeeSource).not.toContain('updateMeasurementCalculationMode')
+    expect(source.slice(source.indexOf('async function openFeeConfirmDialog()'), source.indexOf('async function executeConfirmAndSendFee()'))).toContain('getLatestInboundFee')
+  })
+
+  it('clears an invalidated measurement loading state before refreshing order details', () => {
+    const detailLoaderSource = source.slice(source.indexOf('async function loadDetail(force = false)'), source.indexOf('watch([page, pageSize]'))
+    expect(detailLoaderSource).toMatch(/measurementRequestSerial \+= 1\r?\n\s+measurementLoading\.value = false/)
+  })
+
+  it('restores the saved outer-carton rule and server-calculated dimensions on re-entry', () => {
+    expect(source).toContain('const savedModes = [...new Set(response.items.map((item) => item.coefficientMode)')
+    expect(source).toContain('measurementSectionModes.outer = savedModes.length === 1')
+    expect(source).toContain('? savedModes[0]!')
+    expect(source).toContain("configuredMode === 'ADD' ? 'ADD' : 'ACTUAL'")
+    expect(source).toContain('row.calculatedOuterLengthCm')
+    expect(source).toContain('measurementCalculationModeForRow(source) === measurementSectionModes.outer')
+    expect(source).toContain("String(row.calculationRuleVersion || '').startsWith('WAREHOUSE_OUTER_OVERRIDE_')")
+    expect(source).toContain('warehouseOuterOverride')
+    expect(source).toContain('Math.abs(Number(value) - Number(recalculatedDimensions[index])) < 0.001')
+    expect(source).toContain('lengthCm: Number(savedDimensions[0])')
+  })
+
+  it('binds dimension and weight evidence to their formal server records without mixing galleries', () => {
+    expect(source).toContain('<el-table :data="actualMeasurementRows" row-key="id"')
+    expect(source).toContain('<el-table-column label="箱号" prop="boxCode"')
+    expect(source).toContain("row.boxCode || '—'")
+    expect(source).toContain("`箱号 ${row.boxCode || row.itemNo || '箱规编码待补充'} 的尺寸图片`")
+    expect(source).not.toContain('row.boxCode || row.itemNo || row.id')
+    expect(source).toContain('label="尺寸图片"')
+    expect(source).toContain(':file-id="row.intelligentImageFileId"')
+    expect(source).toContain('openMeasurementEvidence(row.intelligentImageFileId')
+    expect(source).toContain('v-for="weightResult in measurementDetail.weightResults"')
+    expect(source).toContain(':file-id="weightResult.fileId"')
+    expect(source).toContain('openMeasurementEvidence(weightResult.fileId')
+    expect(source).toContain('measurementDetail?.actualGrossWeightKg')
+    expect(source).toContain('weightResult.grossWeightKg')
+    expect(source).toContain('weightResult.netWeightKg')
+    expect(source).toContain("weightResult.palletType || '未记录类型'")
+    expect(source).not.toContain('weightResult.palletCode')
+    expect(source).not.toContain('measurementImageUrls')
+    expect(source).not.toContain('const fileIds = [...measurementDetail.value.items')
+  })
+
+  it('keeps authenticated evidence loading, original preview, permission and error states', () => {
+    expect(source).toContain('<MeasurementEvidenceThumbnail')
+    expect(source).toContain("downloadWeightImage(String(summary.tenantId), String(summary.inboundId), fileId)")
+    expect(source).toContain('measurementPreviewError')
+    expect(source).toContain('测量原图暂时无法读取')
+    expect(source).toContain("can('platform:firstleg:inbound:measure:view')")
+  })
+
+  it('shows parent-child markers only for related rows and keeps the aggregate in detail', () => {
+    expect(source).not.toContain("type: 'expand'")
+    expect(source).toContain('v-if="(row as UnifiedOrderResource).relation"')
+    expect(source).toContain('父单 · ${row.relation.childCount} 个子单')
+    expect(source).toContain('子单 · 第 ${row.relation.splitSequence} 次')
+    expect(source).toContain('title="父子订单关联"')
+    expect(source).toContain('@click="openOrderRelation(row as UnifiedOrderResource)"')
+    expect(source).toContain("{ key: 'fulfillment', label: '拆分履约', icon: '🧩' }")
+    expect(source).toContain("activeDetailTab === 'fulfillment'")
+    expect(source).toContain('根单、已完成分片与当前余量')
+  })
+
+  it('distinguishes overflow action buttons by row and keeps a stable missing-field fallback', () => {
+    expect(source).toContain('function moreUnifiedOrderActionsLabel(row: UnifiedOrderResource)')
+    expect(source).toContain("String(row.inboundCode || '').trim() || '当前入仓单'")
+    expect(source).not.toContain('compatibleOrder.orderNo')
+    expect(source).not.toContain('aria-label="更多订单操作"')
+    expect(source).not.toContain('title="更多操作"')
+  })
+
+  it('batch prints stable carton labels from the list toolbar instead of adding another row action', () => {
+    expect(source).toContain('downloadInboundCartonLabelsBatch')
+    expect(source).toContain('const selectedCartonLabelOrders = computed')
+    expect(source).toContain('@click="printSelectedCartonLabels"')
+    expect(source).toContain('批量箱唛-${selectedCartonLabelOrders.value.length}单.pdf')
+    expect(source).not.toContain("type UnifiedOrderRowAction = 'note' | 'approve' | 'printCartonLabels'")
+  })
+
+  it('renders order detail as a routed full page instead of a drawer', () => {
+    expect(source).toContain('<template v-if="isDetailRoute">')
+    expect(source).toContain('class="order-detail-header density-detail-header"')
+    expect(source).toContain('aria-label="订单详情模块"')
+    expect(source).toContain("{ key: 'basic', label: '基本信息'")
+    expect(source).toContain("{ key: 'measurement', label: '测量数据'")
+    expect(source).not.toContain('detailOpen')
+    expect(source).toContain('watch(detailRouteKey,')
+    expect(source).toContain('requestKey !== detailRouteKey.value')
+  })
+
+  it('keeps the basic information compact and maps available order fields', () => {
+    expect(source).toContain('grid-template-columns: repeat(4, minmax(0, 1fr))')
+    for (const label of ['业务类型', '买单 / 退税', '提货方式', '配载状态', '目的仓类型', '客户申报净重', '客户申报总体积', '商检验', '提货联系人', '目的地地址']) {
+      expect(source).toContain(`<dt>${label}</dt>`)
+    }
+    expect(source).toContain("['actualVolumeCbm', 'chargeableVolumeCbm'].includes(property)")
+    expect(source).toContain("partyValue(detail.order.parties, 'SENDER', 'phone')")
+    expect(source).toContain("partyValue(detail.order.parties, 'RECEIVER', 'phone')")
+    expect(source).not.toContain("partyValue(detail.order.parties, 'CONSIGNEE'")
+    expect(source).toContain("cargoTotal(detail.order.cargoes, 'netWeightKg')")
+    expect(source).toContain('InboundFeePanel')
+    expect(source).toContain('InboundFeeDetailManager')
+    expect(source).toContain(':customer-id="String(detail.summary.tenantId)"')
+    expect(source).toContain('compact')
+    expect(source).toContain('display-only')
+    expect(source).toContain(':key="`fee-${normalizedInboundId}-${feePanelRevision}`"')
+    expect(source).toContain('feePanelRevision.value += 1')
+    expect(source).not.toContain('<h3 class="fee-section-title">头程自动初算</h3>')
+    expect(source).toContain('其他费用明细')
+    expect(source).toContain('@changed="loadDetail(true)"')
+    expect(source).toContain('firstLegTransportModeLabel(detail.order.order?.transportMode)')
+    expect(source).toContain('firstLegPickupMethodLabel(detail.order.order?.pickupMethod)')
+    expect(source).toContain('firstLegDestinationTypeLabel(detail.order.order?.destinationType)')
+  })
+
+  it('does not mount fee consumers until a real inboundId exists', () => {
+    const feeSection = source.slice(source.indexOf("activeDetailTab === 'fees'"), source.indexOf("activeDetailTab === 'history'"))
+    expect(source).toContain('const normalizedInboundId = computed(() => normalizedIdentifier(detail.value?.summary.inboundId))')
+    expect(feeSection).toContain('v-if="!normalizedInboundId" description="订单尚未生成入库单，暂无入仓费用"')
+    expect(feeSection.match(/:inbound-id="normalizedInboundId"/g)).toHaveLength(2)
+    expect(feeSection).not.toContain('String(detail.summary.inboundId)')
+  })
+
+  it('keeps downstream work out of each order detail after the order is linked to a container', () => {
+    expect(source).not.toContain('UnifiedOrderWorkflowPanel')
+    expect(source).not.toContain("key: 'workflow'")
+    expect(source).not.toContain('后半程作业')
+    expect(source).not.toContain("activeDetailTab === 'workflow'")
+    expect(routeSource).not.toContain('unified-order-workflow')
+  })
+
+  it('only exposes declaration editing before loading and marks channel changes', () => {
+    expect(source).toContain("new Set(['DRAFT', 'REJECTED', 'SUBMITTED', 'APPROVED'])")
+    expect(source).toContain("planningEditableOrderStatuses.has(row.internalOrderStatus || '')")
+    expect(source).toContain('v-if="canEditPlanning(row as UnifiedOrderResource)"')
+    expect(source).toContain("new Set<UnifiedOrderMainStatus>(['PENDING_REVIEW', 'WAIT_MEASURE', 'WAIT_SPLIT'])")
+    expect(source).toContain('declarationEditableStatuses.has(detail.value.summary.mainStatus)')
+    expect(source).not.toContain("detail.value.summary.mainStatus === 'WAIT_MEASURE'")
+    expect(source).toContain("can('platform:order:declaration:edit')")
+    expect(source).toContain('编辑客户申报资料')
+    expect(source).toContain('<OrderDeclarationEditorDialog')
+    expect(source).toContain('曾变更渠道')
+    expect(source).toContain('@updated="handleDeclarationUpdated"')
+  })
+
+  it('supports the measurement-review deep link with an inbound-code lookup and recoverable return path', () => {
+    expect(routeSource).toContain("name: 'unified-order-detail-by-inbound-code'")
+    expect(routeSource.indexOf("path: 'orders/inbound/:inboundCode'")).toBeLessThan(routeSource.indexOf("path: 'orders/:orderId'"))
+    expect(source).toContain("route.query.tab === 'measurement'")
+    expect(source).toContain("route.query.from === 'measurement-review'")
+    expect(source).toContain('getPlatformInboundCodeAssociation(inboundCode)')
+    expect(source).toContain("activeDetailTab.value = 'measurement'")
+    expect(source).toContain('await loadMeasurementDetails()')
+    expect(source).toContain("router.push({ name: 'inbound-measurement-reviews' })")
+    expect(source).toContain('router.back()')
+    expect(source).toContain('可能无权查看或目标已不存在')
+    expect(source).toContain('返回测量审核列表')
+  })
+
+  it('keeps detail tabs compact on one horizontally scrollable row', () => {
+    expect(source).toContain('class="detail-tabs density-tabs"')
+    expect(densitySource).toContain('overflow-x: auto; overflow-y: hidden;')
+    expect(densitySource).toContain('min-height: var(--admin-tab-height)')
+    expect(source).not.toContain('grid-template-columns: repeat(6, minmax(124px, 1fr))')
+    expect(source).not.toContain('.detail-tabs { grid-template-columns: repeat(6, 132px); }')
+  })
+
+  it('matches the prototype table grid and distinguishes container identifiers', () => {
+    expect(source).toContain('row-key="orderId" border stripe')
+    expect(source).toContain('<el-table :data="customerMeasurementRows" border stripe')
+    expect(source).toContain('<el-table :data="outerMeasurementRows" border stripe')
+    expect(source).toContain('<el-table :data="actualMeasurementRows" row-key="id" border stripe')
+    expect(source).toContain('<el-table :data="customerMeasurementRows" border stripe empty-text="暂无客户下单数据"')
+    expect(densitySource).toContain('--el-table-border-color: var(--admin-table-border)')
+    expect(densitySource).toContain('--el-table-row-hover-bg-color: var(--admin-row-hover)')
+    expect(densitySource).toContain('.el-table__body tr.el-table__row--striped')
+    expect(source).toContain("label: '真实集装箱号'")
+    expect(source).toContain("label: '内部柜次号'")
+    expect(source).toContain('<dt>真实集装箱号</dt>')
+    expect(source).toContain('<dt>内部柜次号</dt>')
+  })
+
+  it('uses outlined semantic buttons for row business actions while keeping detail navigation explicit', () => {
+    const rowActions = source.slice(source.indexOf('<template #actions'), source.indexOf('<template #inboundCode'))
+    expect(rowActions).toContain('density-action')
+    expect(rowActions).not.toContain('v-for="action in directUnifiedOrderActions(row as UnifiedOrderResource)" :key="action" link')
+    expect(rowActions).toContain('@click="openDetail(row as UnifiedOrderResource)">详情</el-button>')
+    expect(source).toContain('<el-button link class="back-button density-back"')
+  })
+})
diff --git a/src/modules/unified-orders/pages/UnifiedOrdersView.vue b/src/modules/unified-orders/pages/UnifiedOrdersView.vue
new file mode 100644
index 00000000..73d08f1c
--- /dev/null
+++ b/src/modules/unified-orders/pages/UnifiedOrdersView.vue
@@ -0,0 +1,3034 @@
+<script setup lang="ts">
+import { computed, nextTick, onBeforeUnmount, onMounted, reactive, ref, watch } from 'vue'
+import { ElMessage, ElMessageBox, type UploadFile } from 'element-plus'
+import { ArrowLeft, ChevronDown, ChevronUp, CircleCheck, Download, FileUp, GitBranch, Link2, MoreHorizontal, PackageOpen, Printer, Send, ShieldAlert, SlidersHorizontal, StickyNote, Undo2 } from '@lucide/vue'
+import { useRoute, useRouter } from 'vue-router'
+import {
+  getPlatformUnifiedOrder,
+  downloadPlatformProductImage,
+  approvePlatformUnifiedOrder,
+  batchApprovePlatformUnifiedOrders,
+  getPlatformUnifiedOrderBatchApprovalPreview,
+  updatePlatformUnifiedOrderRemarks,
+  listPlatformUnifiedOrders,
+  updatePlatformUnifiedOrderPlanning,
+  unifiedOrderStatusOptions,
+  type UnifiedOrderDetailResource,
+  type UnifiedOrderCoLoadGroupSummary,
+  type UnifiedOrderMainStatus,
+  type UnifiedOrderResource,
+  type UnifiedOrderBatchApprovalPreviewItem,
+  type UnifiedOrderBatchReviewItem,
+} from '@/modules/unified-orders/api/unifiedOrders'
+import { cancelPlatformCoLoadGroup, createPlatformCoLoadGroup, getPlatformCoLoadGroupByInboundCode, type CoLoadBusinessSummary, type CoLoadGroup } from '@/modules/unified-orders/api/coLoadGroups'
+import OrderFulfillmentTreePanel from '@/modules/unified-orders/components/OrderFulfillmentTreePanel.vue'
+import InboundFeeDetailManager from '@/modules/unified-orders/components/InboundFeeDetailManager.vue'
+import OrderDeclarationEditorDialog from '@/modules/unified-orders/components/OrderDeclarationEditorDialog.vue'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { listPlatformTenants, type PlatformTenantResource } from '@/modules/iam'
+import { listAllPlatformWarehouses, type PlatformWarehouseSummaryResource } from '@/modules/warehouses'
+import { getApiErrorDetails, getApiErrorMessage, type ApiErrorDetails } from '@/shared/api/http'
+import { createPlatformExportTask } from '@/modules/downloads'
+import { showExportTaskCreatedDialog } from '@/shared/components/exportTaskCreatedDialog'
+import { getLoadingAssociationSummary, getOverseasInboundCodeRelationship, getPlatformInboundCodeAssociation, type LoadingAssociationSummary, type OverseasInboundCodeRelationship } from '@/shared/api/inboundCodeRelations'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import AppDrawer from '@/shared/components/AppDrawer.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import DetailPageLayout from '@/shared/components/DetailPageLayout.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import LineClampText from '@/shared/components/LineClampText.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import StatusBadge from '@/shared/components/StatusBadge.vue'
+import {
+  firstLegBusinessTypeLabel,
+  firstLegContainerModeLabel,
+  firstLegDestinationTypeLabel,
+  firstLegPickupMethodLabel,
+  firstLegTaxModeLabel,
+  firstLegTradeTermLabel,
+  firstLegTransportModeLabel,
+} from '@/shared/utils/firstLegBusinessLabels'
+import { SmartLoadingDialog } from '@/modules/container-loading'
+import {
+  unifiedOrderHistoryActionLabel,
+  unifiedOrderLoadingStatusLabel,
+  unifiedOrderReviewStatusLabel,
+  unifiedOrderStatusLabel,
+} from '@/modules/unified-orders/status'
+import {
+  adjustPublishedInboundFee,
+  downloadWeightImage,
+  calculateInboundFee,
+  confirmInboundFee,
+  createFeeAdjustmentIdempotencyKey,
+  createFeeActionIdempotencyKey,
+  getLatestInboundFee,
+  getInboundMeasurement,
+  getPlatformInboundHold,
+  downloadInboundCartonLabelsBatch,
+  downloadPlatformInboundHoldEvidence,
+  holdPlatformInbound,
+  releasePlatformInbound,
+  uploadPlatformInboundHoldEvidence,
+  updateMeasurementCalculationStrategy,
+  updateMeasurementOuterDimensions,
+  InboundFeePanel,
+  InboundMeasurementDialog,
+  MeasurementEvidenceThumbnail,
+  DropshipPalletPrintPanel,
+  sendInboundFee,
+  type InboundFeeSnapshot,
+  type InboundMeasurementDetail,
+  type InboundHoldDetail,
+} from '@/modules/inbounds'
+import { listCustomerChargeRules, type CustomerChargeRule } from '@/modules/fba-pricing'
+import { getCustomerDimensionConfig, type CustomerDimensionConfig, type CustomerDimensionRule } from '@/modules/dimension-config'
+
+type FilterModel = QueryModel & {
+  tenantId: string
+  receivingWarehouseId: string
+  destinationWarehouseId: string
+  inboundCode: string
+  expectedArrivalDate: string
+  feeReviewStatus: string
+  channelName: string
+  containerNo: string
+  cabinetNo: string
+  sailingDate: string
+  loaded: string
+  fullContainer: string
+  measurementReviewStatus: string
+  fbaCode: string
+  createdRange: string[]
+}
+
+const route = useRoute()
+const router = useRouter()
+const access = useAccessPreviewStore()
+const records = ref<UnifiedOrderResource[]>([])
+const customers = ref<PlatformTenantResource[]>([])
+const warehouses = ref<PlatformWarehouseSummaryResource[]>([])
+const page = ref(1)
+const pageSize = ref(20)
+const total = ref(0)
+const loading = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+type PlanningDraft = {
+  expectedArrivalAt: string
+  estimatedVolumeCbm: number | null
+  savedExpectedArrivalAt: string
+  savedEstimatedVolumeCbm: number | null
+  saving: boolean
+}
+const planningDrafts = reactive<Record<string, PlanningDraft | undefined>>({})
+const customerLoading = ref(false)
+const customerLoadError = ref<ApiErrorDetails | null>(null)
+const warehouseLoading = ref(false)
+const warehouseLoadError = ref<ApiErrorDetails | null>(null)
+const detail = ref<UnifiedOrderDetailResource | null>(null)
+const detailLoading = ref(false)
+const detailError = ref<ApiErrorDetails | null>(null)
+const declarationEditorOpen = ref(false)
+const activeDetailTab = ref('basic')
+const automaticFee = ref<AutomaticFeeSummary | null>(null)
+const feePanelRevision = ref(0)
+const otherFeeSummary = ref<OtherFeeSummary>({ currency: 'CNY', approvedReceivable: 0, approvedPayable: 0 })
+const customerFeeTotal = computed(() => (
+  (automaticFee.value?.feeStatus === 'SENT' ? Number(automaticFee.value.totalAmount || 0) : 0)
+  + otherFeeSummary.value.approvedReceivable
+))
+function feeMoney(value: number) {
+  return new Intl.NumberFormat('zh-CN', { style: 'currency', currency: otherFeeSummary.value.currency || 'CNY' }).format(value)
+}
+function feeConfirmMoney(value: number, currency = 'CNY') {
+  return new Intl.NumberFormat('zh-CN', {
+    style: 'currency',
+    currency,
+  }).format(value)
+}
+
+type OtherFeeSummary = { currency: string; approvedReceivable: number; approvedPayable: number }
+type AutomaticFeeSummary = { feeStatus: string; totalAmount: number }
+const approvalOpen = ref(false)
+const approvalLoadingId = ref('')
+const approvalSaving = ref(false)
+const batchApprovalSaving = ref(false)
+const batchApprovalLoading = ref(false)
+const batchApprovalOpen = ref(false)
+const batchApprovalError = ref<ApiErrorDetails | null>(null)
+const batchApprovalPreviewRows = ref<UnifiedOrderBatchApprovalPreviewItem[]>([])
+const batchApprovalSelectedRows = ref<UnifiedOrderBatchApprovalPreviewItem[]>([])
+const batchApprovalTableRef = ref<{ toggleRowSelection: (row: UnifiedOrderBatchApprovalPreviewItem, selected?: boolean) => void }>()
+const exportSubmitting = ref(false)
+const printingCartonLabels = ref(false)
+const selectedApprovalOrders = ref<UnifiedOrderResource[]>([])
+const selectedOrders = ref<UnifiedOrderResource[]>([])
+const selectedCartonLabelOrders = computed(() => selectedOrders.value.filter((row) => row.inboundId != null))
+const coLoadCreateOpen = ref(false)
+const coLoadDetailOpen = ref(false)
+const coLoadDetailInboundCode = ref('')
+const coLoadDetailSummary = ref<CoLoadBusinessSummary | null>(null)
+const coLoadDetailLoading = ref(false)
+const coLoadDetailError = ref<ApiErrorDetails | null>(null)
+const coLoadCancelError = ref<ApiErrorDetails | null>(null)
+const coLoadCancelSaving = ref(false)
+const coLoadSaving = ref(false)
+const coLoadError = ref<ApiErrorDetails | null>(null)
+const approvalOrder = ref<UnifiedOrderResource | null>(null)
+const noteOpen = ref(false)
+const noteSaving = ref(false)
+const noteForm = reactive({ internalRemark: '', warehouseRemark: '', customerServiceRemark: '' })
+const noteOrder = ref<UnifiedOrderResource | null>(null)
+const holdDetail = ref<InboundHoldDetail | null>(null)
+const holdLoading = ref(false)
+const holdError = ref<ApiErrorDetails | null>(null)
+const holdLoadedKey = ref('')
+const holdDialogOpen = ref(false)
+const holdSaving = ref(false)
+const holdAction = ref<'HOLD' | 'RELEASE'>('HOLD')
+const holdReason = ref('')
+const holdEvidenceFile = ref<File | null>(null)
+const holdEvidenceUploadKey = ref(0)
+const holdUploadedEvidenceFileId = ref('')
+const holdEvidenceError = ref<ApiErrorDetails | null>(null)
+const holdDownloadingFileId = ref('')
+const relationOpen = ref(false)
+const relationOrder = ref<UnifiedOrderResource | null>(null)
+const measurementDetail = ref<InboundMeasurementDetail | null>(null)
+const measurementLoading = ref(false)
+const measurementError = ref<ApiErrorDetails | null>(null)
+const measurementLoadedKey = ref('')
+const measurementChargeRules = ref<CustomerChargeRule[]>([])
+const measurementChargeRulesLoading = ref(false)
+const measurementChargeRulesLoadedKey = ref('')
+const measurementDimensionConfig = ref<CustomerDimensionConfig | null>(null)
+const measurementDimensionConfigLoading = ref(false)
+const measurementDimensionConfigLoadedKey = ref('')
+const measurementStrategySavingId = ref('')
+const measurementOuterSavingId = ref('')
+const measurementPreviewOpen = ref(false)
+const measurementPreviewLoading = ref(false)
+const measurementPreviewError = ref<ApiErrorDetails | null>(null)
+const measurementPreviewUrl = ref('')
+const measurementPreviewTitle = ref('测量图片')
+const measurementCollapsed = reactive({ customer: false, outer: false, actual: false })
+type MeasurementSection = keyof typeof measurementCollapsed
+type MeasurementCalculationMode = 'ACTUAL' | 'ADD' | 'MULTIPLY'
+const measurementSectionModes = reactive<Record<MeasurementSection, MeasurementCalculationMode>>({
+  customer: 'ACTUAL', outer: 'ACTUAL', actual: 'ACTUAL',
+})
+const measurementDraftEditableStatuses = new Set([
+  'PREPARING', 'WAIT_MEASURE', 'MEASURING', 'MEASURE_REJECTED',
+])
+const measurementDraftEditable = computed(() => (
+  can('platform:firstleg:inbound:measure:edit')
+  && measurementDraftEditableStatuses.has(measurementDetail.value?.processStatus || '')
+))
+const measurementStrategyEditable = computed(() => (
+  can('platform:firstleg:inbound:measure:edit')
+  && Boolean(measurementDetail.value?.measurementId)
+  && measurementDetail.value?.version != null
+))
+const measurementStrategyLockedHint = computed(() => {
+  if (!can('platform:firstleg:inbound:measure:edit')) return '当前账号缺少测量编辑权限'
+  if (!measurementDetail.value?.measurementId) return '当前没有可修改的测量批次'
+  return '客户已确认且该票已装柜完成后，箱规计算规则将冻结'
+})
+const cargoImagePreviewUrls = new Set<string>()
+const measurementDialogOpen = ref(false)
+const openWarehouseSuggestionOnMeasurementLoad = ref(false)
+const confirmFeeSending = ref(false)
+const feeConfirmOpen = ref(false)
+const feeConfirmWeight = ref<number | null>(null)
+const feeConfirmVolume = ref<number | null>(null)
+const feeConfirmReferenceLoading = ref(false)
+const feeConfirmReference = ref<InboundFeeSnapshot | null>(null)
+const feeConfirmUnitPrice = ref<number | null>(null)
+const feeConfirmPriceReason = ref('')
+type FeeConfirmAttempt = {
+  fingerprint: string
+  calculateKey: string
+  adjustKey: string
+  confirmKey: string
+  sendKey: string
+}
+let feeConfirmAttempt: FeeConfirmAttempt | null = null
+const feeConfirmPriceChanged = computed(() => {
+  const reference = Number(feeConfirmReference.value?.unitPrice)
+  const current = Number(feeConfirmUnitPrice.value)
+  return reference >= 0 && current >= 0 && Math.abs(reference - current) > 0.000001
+})
+const feeConfirmPriceUnit = computed(() => {
+  const snapshot = feeConfirmReference.value
+  return snapshot ? `${snapshot.currency} / ${snapshot.chargeUnit}` : '—'
+})
+const feeConfirmEstimatedTotal = computed(() => {
+  const snapshot = feeConfirmReference.value
+  const unitPrice = Number(feeConfirmUnitPrice.value)
+  if (!snapshot || !(unitPrice >= 0)) return null
+  return Number(snapshot.chargeableQuantity || 0) * unitPrice + Number(snapshot.additionalAmount || 0)
+})
+const feeConfirmRows = computed(() => {
+  const summary = detail.value?.summary
+  const measuredGrossWeight = Number(measurementDetail.value?.actualGrossWeightKg)
+  const measuredNetWeight = Number(measurementDetail.value?.actualNetWeightKg)
+  const actualTotals = measurementTotals(actualMeasurementRows.value)
+  const actualWeight = Number(actualTotals.gross) > 0
+    ? actualTotals.gross
+    : measuredGrossWeight > 0 ? measuredGrossWeight : measuredNetWeight > 0 ? measuredNetWeight : null
+  const actualVolume = Number(actualTotals.volume) > 0 ? actualTotals.volume : null
+  const customerTotals = measurementTotals(customerMeasurementRows.value)
+  return [
+    { source: '客户下单数据', count: customerTotals.count, weight: customerTotals.gross, volume: customerTotals.volume ?? summary?.expectedVolumeCbm },
+    { source: '外箱规数据', count: measurementTotals(outerMeasurementRows.value).count, weight: measurementTotals(outerMeasurementRows.value).gross, volume: measurementTotals(outerMeasurementRows.value).volume },
+    { source: '实际测量数据', count: actualTotals.count, weight: actualWeight, volume: actualVolume },
+  ]
+})
+const smartLoadingOpen = ref(false)
+const measurementOrder = ref<UnifiedOrderResource | null>(null)
+const loadingAssociation = ref<LoadingAssociationSummary | null>(null)
+const overseasRelationship = ref<OverseasInboundCodeRelationship | null>(null)
+const loadingAssociationError = ref<ApiErrorDetails | null>(null)
+const overseasRelationshipError = ref<ApiErrorDetails | null>(null)
+const subsequentFulfillmentLoading = ref(false)
+const resolvedDetailTarget = ref<{ orderId: string; tenantId: string } | null>(null)
+let detailLoadingKey = ''
+let detailRequestSerial = 0
+let detailAssociationRequestSerial = 0
+let measurementRequestSerial = 0
+let measurementPreviewRequestSerial = 0
+let subsequentFulfillmentRequestSerial = 0
+let holdRequestSerial = 0
+const showAdvancedFilters = ref(false)
+const filters = ref<FilterModel>(emptyFilters())
+const appliedFilters = ref<FilterModel>(emptyFilters())
+const selectedStatus = ref<UnifiedOrderMainStatus | ''>('')
+const businessInboundCode = computed(() => route.name === 'unified-order-detail-by-inbound-code' && typeof route.params.inboundCode === 'string'
+  ? route.params.inboundCode.trim()
+  : '')
+const orderId = computed(() => typeof route.params.orderId === 'string' ? route.params.orderId : resolvedDetailTarget.value?.orderId || '')
+const detailTenantId = computed(() => typeof route.query.tenantId === 'string' ? route.query.tenantId : resolvedDetailTarget.value?.tenantId || '')
+const detailRouteKey = computed(() => orderId.value ? `${detailTenantId.value}:${orderId.value}` : '')
+const isDetailRoute = computed(() => Boolean(orderId.value || businessInboundCode.value))
+const requestedDetailTab = computed(() => route.query.tab === 'measurement' ? 'measurement' : 'basic')
+const fromMeasurementReview = computed(() => route.query.from === 'measurement-review')
+function normalizedIdentifier(value: unknown) {
+  const identifier = String(value ?? '').trim()
+  return identifier && identifier !== 'null' && identifier !== 'undefined' ? identifier : ''
+}
+const normalizedInboundId = computed(() => normalizedIdentifier(detail.value?.summary.inboundId))
+const currentHoldFlag = computed(() => holdDetail.value ? holdDetail.value.holdFlag : detail.value?.summary.holdFlag ?? null)
+const currentHoldReason = computed(() => holdDetail.value ? holdDetail.value.currentHoldReason : detail.value?.summary.currentHoldReason ?? null)
+const canHoldInbound = computed(() => Boolean(
+  normalizedInboundId.value
+  && can('platform:firstleg:inbound:hold')
+  && holdDetail.value?.canHold,
+))
+const canReleaseInbound = computed(() => Boolean(
+  normalizedInboundId.value
+  && can('platform:firstleg:inbound:hold')
+  && holdDetail.value?.canRelease,
+))
+
+const isDropshipOrder = computed(() => detail.value?.summary.fulfillmentType === 'ONE_CLICK_DROPSHIP')
+const detailTabs = computed(() => [
+  { key: 'basic', label: '基本信息', icon: '📋' },
+  { key: 'cargo', label: '货品信息', icon: '📦' },
+  { key: 'fees', label: '费用信息', icon: '💰' },
+  { key: 'history', label: '状态历史', icon: '📝' },
+  { key: 'measurement', label: '测量数据', icon: '📐' },
+  ...(isDropshipOrder.value ? [{ key: 'dropship-print', label: '托盘打印', icon: '🖨️' }] : []),
+  { key: 'other', label: '其他', icon: '🗂️' },
+  { key: 'fulfillment', label: '拆分履约', icon: '🧩' },
+])
+
+const customerMeasurementColumns = [
+  { key: 'itemNo', label: '#' }, { key: 'lengthCm', label: '箱规长(cm)' }, { key: 'widthCm', label: '箱规宽(cm)' },
+  { key: 'heightCm', label: '箱规高(cm)' }, { key: 'packageCount', label: '箱数' }, { key: 'unitWeightKg', label: '每箱毛重' },
+  { key: 'unitVolumeCbm', label: '每箱体积' }, { key: 'remark', label: '备注' },
+]
+const measuredColumns = [
+  ...customerMeasurementColumns.slice(0, 7), { key: 'girthCm', label: '箱规周长(cm)' }, { key: 'totalWeightKg', label: '总毛重(T.K.GW)' },
+  { key: 'totalVolumeCbm', label: '总体积(T.CBM)' }, { key: 'volumeWeightKg', label: '总材积' },
+  { key: 'remark', label: '备注' },
+]
+const outerColumns = measuredColumns
+const actualMeasuredColumns = measuredColumns.filter((column) => column.key !== 'itemNo')
+
+function sortedDimensions(row: Record<string, unknown>) {
+  const values = [Number(row.lengthCm), Number(row.widthCm), Number(row.heightCm)]
+  return values.every((value) => Number.isFinite(value) && value > 0)
+    ? values.sort((left, right) => right - left)
+    : null
+}
+
+function matchingDimensionRule(row: Record<string, unknown>): CustomerDimensionRule | null {
+  const measured = sortedDimensions(row)
+  if (!measured) return null
+  const rules = [...(measurementDimensionConfig.value?.rules || [])]
+    .sort((left, right) => (
+      left.innerLengthCm * left.innerWidthCm * left.innerHeightCm
+      - right.innerLengthCm * right.innerWidthCm * right.innerHeightCm
+    ))
+  if (!rules.length) return null
+  return rules.find((rule) => {
+    const inner = [rule.innerLengthCm, rule.innerWidthCm, rule.innerHeightCm].sort((left, right) => right - left)
+    return measured.every((value, index) => value <= inner[index])
+  }) || rules[rules.length - 1]
+}
+
+function addCoefficientLabel(row?: Record<string, unknown>) {
+  const rows = row ? [row] : (measurementDetail.value?.items || []) as unknown as Record<string, unknown>[]
+  const values = [...new Set(rows.map((item) => matchingDimensionRule(item)?.edgeAdditionCm).filter((value) => value != null))]
+  if (values.length === 1) return `原尺寸 + ${Number(values[0]) * 2}cm（单边 +${values[0]}cm）`
+  if (measurementDimensionConfigLoading.value) return '原尺寸 + 加载中…'
+  return values.length > 1 ? '原尺寸 + 按箱规匹配' : '原尺寸 + 未匹配箱规'
+}
+
+function multiplyCoefficientLabel() {
+  const rule = measurementChargeRules.value.find((item) => item.defaultRule && item.status === 'ACTIVE')
+  if (rule) return `原尺寸 × ${rule.lengthFactor}`
+  return measurementChargeRulesLoading.value ? '原尺寸 × 加载中…' : '原尺寸 × 未启用系数'
+}
+
+function matchedSpecificationCoefficient(rule: CustomerChargeRule, row: Record<string, unknown>) {
+  const tiers = [...(rule.remark || '').matchAll(
+    /(SMALL|MEDIUM|LARGE|EXTRA_LARGE):(\d+(?:\.\d+)?),(\d+(?:\.\d+)?),(\d+(?:\.\d+)?)；系数:(\d+(?:\.\d+)?)(?:；重量:(\d+(?:\.\d+)?))?/g,
+  )].map((match) => ({
+    dimensions: [Number(match[2]), Number(match[3]), Number(match[4])].sort((left, right) => right - left),
+    coefficient: Number(match[5]),
+    maxWeightKg: match[6] == null ? null : Number(match[6]),
+  })).filter((tier) => tier.dimensions.every((value) => Number.isFinite(value) && value > 0)
+    && Number.isFinite(tier.coefficient) && tier.coefficient > 0
+    && (tier.maxWeightKg == null || (Number.isFinite(tier.maxWeightKg) && tier.maxWeightKg > 0)))
+    .sort((left, right) => left.dimensions.reduce((total, value) => total * value, 1)
+      - right.dimensions.reduce((total, value) => total * value, 1))
+  if (!tiers.length) return Number(rule.lengthFactor || 1)
+  const measured = [Number(row.lengthCm), Number(row.widthCm), Number(row.heightCm)]
+    .sort((left, right) => right - left)
+  const unitWeight = Number(row.unitWeightKg)
+  const matched = tiers.find((tier) => measured.every((value, index) => value <= tier.dimensions[index])
+    && (tier.maxWeightKg == null || !Number.isFinite(unitWeight) || unitWeight <= tier.maxWeightKg))
+  return (matched || tiers[tiers.length - 1]).coefficient
+}
+
+// 系数模式可使用客户名下任一启用规则；默认规则仅用于优先选择，不作为唯一条件。
+const activeMeasurementChargeRule = computed(() => measurementChargeRules.value
+  .find((rule) => rule.defaultRule && rule.status === 'ACTIVE')
+  || measurementChargeRules.value.find((rule) => rule.status === 'ACTIVE')
+  || null)
+const boundOuterMeasurementChargeRule = computed(() => {
+  const boundId = outerMeasurementRows.value
+    .map((row) => String(row.chargeRuleId || ''))
+    .find((id) => id)
+  return boundId
+    ? measurementChargeRules.value.find((rule) => rule.id === boundId && rule.status === 'ACTIVE') || null
+    : null
+})
+const activeMeasurementChargeRules = computed(() => measurementChargeRules.value.filter((rule) => rule.status === 'ACTIVE'))
+const multiplyModeDisabled = computed(() => !measurementChargeRulesLoading.value && !activeMeasurementChargeRule.value)
+
+function roundedUp(value: number, digits: number) {
+  const factor = 10 ** digits
+  return Math.ceil((value - Number.EPSILON) * factor) / factor
+}
+
+function calculatedMeasurementRow(
+  source: Record<string, unknown>,
+  mode: MeasurementCalculationMode,
+  customerSource = false,
+  useWarehouseOuterOverrides = true,
+): Record<string, unknown> {
+  const outerOverrides = [source.outerLengthCm, source.outerWidthCm, source.outerHeightCm]
+  const hasOuterOverride = useWarehouseOuterOverrides && !customerSource
+    && outerOverrides.some((value) => value != null && value !== '')
+  const rawDimensions = [source.lengthCm, source.widthCm, source.heightCm].map((value, index) => {
+    const override = outerOverrides[index]
+    return Number(hasOuterOverride && override != null && override !== '' ? override : value)
+  })
+  const calculationSource = {
+    ...source,
+    lengthCm: rawDimensions[0],
+    widthCm: rawDimensions[1],
+    heightCm: rawDimensions[2],
+  }
+  const rule = matchingDimensionRule(calculationSource)
+  if (!rawDimensions.every((value) => Number.isFinite(value) && value > 0)) return { ...source }
+
+  const matchedDimensions = mode === 'ADD' && rule
+    ? rawDimensions.map((value) => value + rule.edgeAdditionCm * 2)
+    : rawDimensions
+  const boundChargeRuleId = String(source.chargeRuleId || '')
+  const chargeRule = measurementChargeRules.value
+    .find((item) => item.id === boundChargeRuleId && item.status === 'ACTIVE')
+    || activeMeasurementChargeRule.value
+  const specificationCoefficient = mode === 'MULTIPLY' && chargeRule
+    ? matchedSpecificationCoefficient(chargeRule, calculationSource)
+    : 1
+  const strategyDimensions = matchedDimensions.map((value) => roundedUp(value * specificationCoefficient, 3))
+  const [lengthCm, widthCm, heightCm] = strategyDimensions
+  const packageCount = Number(source.packageCount)
+  const unitVolumeCbm = mode === 'ADD' && rule && !hasOuterOverride
+    ? Math.round((lengthCm * widthCm * heightCm / 1_000_000) * 1000) / 1000
+    : roundedUp(lengthCm * widthCm * heightCm / 1_000_000, 4)
+  const totalVolumeCbm = Number.isFinite(packageCount) ? roundedUp(unitVolumeCbm * packageCount, 4) : null
+  const fallbackMeasuredUnitWeight = !customerSource && Number.isFinite(Number(measurementDetail.value?.actualGrossWeightKg))
+    && Number(measurementDetail.value?.actualPackageCount) > 0
+    ? Number(measurementDetail.value?.actualGrossWeightKg) / Number(measurementDetail.value?.actualPackageCount)
+    : null
+  const sourceUnitWeight = customerSource
+    ? Number(source.grossWeightKg) / packageCount
+    : Number(source.unitWeightKg) > 0 ? Number(source.unitWeightKg) : fallbackMeasuredUnitWeight
+  const unitWeightKg = Number.isFinite(sourceUnitWeight) ? sourceUnitWeight : null
+  const totalWeightKg = unitWeightKg != null && Number.isFinite(packageCount) ? unitWeightKg * packageCount : null
+  return {
+    ...source,
+    lengthCm, widthCm, heightCm, unitWeightKg, unitVolumeCbm, totalWeightKg, totalVolumeCbm,
+    girthCm: roundedUp(lengthCm + 2 * (widthCm + heightCm), 3),
+    volumeWeightKg: totalVolumeCbm == null ? null : roundedUp(totalVolumeCbm * 167, 3),
+    remark: customerSource ? source.cargoRemark : source.remark,
+  }
+}
+
+const customerMeasurementRows = computed(() => (detail.value?.order.cargoes || []).map((row) => (
+  calculatedMeasurementRow(row, measurementSectionModes.customer, true)
+)))
+const outerMeasurementRows = computed(() => (measurementDetail.value?.items || []).map((row) => {
+  const source = row as unknown as Record<string, unknown>
+  const recalculated = calculatedMeasurementRow(source, measurementSectionModes.outer)
+  const savedDimensions = [row.calculatedOuterLengthCm, row.calculatedOuterWidthCm, row.calculatedOuterHeightCm]
+  const recalculatedDimensions = [recalculated.lengthCm, recalculated.widthCm, recalculated.heightCm]
+  const warehouseOuterOverride = String(row.calculationRuleVersion || '').startsWith('WAREHOUSE_OUTER_OVERRIDE_')
+  if (savedDimensions.every((value) => Number.isFinite(Number(value)) && Number(value) > 0)
+    && (warehouseOuterOverride
+      || savedDimensions.every((value, index) => Math.abs(Number(value) - Number(recalculatedDimensions[index])) < 0.001))
+    && measurementCalculationModeForRow(source) === measurementSectionModes.outer) {
+    const packageCount = Number(row.packageCount)
+    const unitWeightKg = Number(row.unitWeightKg) > 0
+      ? Number(row.unitWeightKg)
+      : Number.isFinite(Number(measurementDetail.value?.actualGrossWeightKg))
+        && Number(measurementDetail.value?.actualPackageCount) > 0
+        ? Number(measurementDetail.value?.actualGrossWeightKg) / Number(measurementDetail.value?.actualPackageCount)
+        : null
+    return {
+      ...source,
+      lengthCm: Number(savedDimensions[0]),
+      widthCm: Number(savedDimensions[1]),
+      heightCm: Number(savedDimensions[2]),
+      unitWeightKg,
+      totalWeightKg: unitWeightKg != null && Number.isFinite(packageCount) ? unitWeightKg * packageCount : null,
+    }
+  }
+  return recalculated
+}))
+const actualMeasurementRows = computed(() => (measurementDetail.value?.items || []).map((row) => (
+  calculatedMeasurementRow(row as unknown as Record<string, unknown>, measurementSectionModes.actual, false, false)
+)))
+const hasActualMeasurementData = computed(() => (measurementDetail.value?.items?.length ?? 0) > 0)
+
+function updateMeasurementSectionMode(section: MeasurementSection, mode: MeasurementCalculationMode) {
+  if (mode === 'MULTIPLY' && !activeMeasurementChargeRule.value) {
+    ElMessage.warning('该客户尚未启用系数配置，请先到客户计费规则中设置默认规则')
+    return
+  }
+  measurementSectionModes[section] = mode
+}
+
+async function selectAndSaveOuterMeasurementMode(mode: MeasurementCalculationMode, ruleId?: string) {
+  if (measurementStrategySavingId.value) return
+  if (!measurementStrategyEditable.value) {
+    ElMessage.warning(measurementStrategyLockedHint.value)
+    return
+  }
+  const previousMode = measurementSectionModes.outer
+  if (mode === 'MULTIPLY' && !activeMeasurementChargeRule.value) {
+    ElMessage.warning('该客户尚未启用系数配置，请先到客户计费规则中设置默认规则')
+    return
+  }
+  measurementSectionModes.outer = mode
+  const saved = await updateMeasurementCalculationMode(null, mode, ruleId)
+  if (!saved) measurementSectionModes.outer = previousMode
+}
+
+async function waitForSavedMeasurementVersion(tenantId: string, inboundId: string, savedVersion: number) {
+  for (let attempt = 0; attempt < 6; attempt += 1) {
+    try {
+      const refreshed = await getInboundMeasurement(tenantId, inboundId)
+      if (Number(refreshed.version) >= savedVersion) return refreshed
+    } catch {
+      // 保存结果已由 PUT 确认，短暂的详情读取失败只影响同步等待。
+    }
+    await new Promise((resolve) => setTimeout(resolve, 250))
+  }
+  return null
+}
+
+const statusTabs = computed(() => [
+  { value: '' as const, label: '全部' },
+  ...unifiedOrderStatusOptions,
+])
+
+const warehouseOptions = computed(() => warehouses.value.map((warehouse) => ({
+  value: String(warehouse.id),
+  label: `${warehouse.warehouseName}（${warehouse.warehouseCode}）`,
+})))
+const receivingWarehouseOptions = computed(() => warehouses.value
+  .filter((warehouse) => warehouse.warehouseType === 'DOMESTIC')
+  .map((warehouse) => ({ value: String(warehouse.id), label: `${warehouse.warehouseName}（${warehouse.warehouseCode}）` })))
+
+const primaryQueryFields = computed<QueryField[]>(() => [
+  { key: 'receivingWarehouseId', type: 'select', width: 220, label: '定位仓库', placeholder: warehouseLoadError.value ? '仓库加载失败' : '请选择定位仓库', options: receivingWarehouseOptions.value, props: { 'aria-label': '定位仓库', filterable: true, loading: warehouseLoading.value, disabled: Boolean(warehouseLoadError.value) } },
+  { key: 'destinationWarehouseId', type: 'select', width: 220, label: '交货仓', placeholder: warehouseLoadError.value ? '仓库加载失败' : '请选择交货仓', options: warehouseOptions.value, props: { 'aria-label': '交货仓', filterable: true, loading: warehouseLoading.value, disabled: Boolean(warehouseLoadError.value) } },
+  { key: 'inboundCode', type: 'input', width: 220, label: '入仓码', placeholder: '请输入入仓码', props: { 'aria-label': '入仓码' } },
+])
+
+const advancedQueryFields = computed<QueryField[]>(() => [
+  { key: 'expectedArrivalDate', type: 'date', width: 190, label: '预计到达时间', placeholder: '请选择预计到达日期', props: { 'aria-label': '预计到达时间' } },
+  { key: 'feeReviewStatus', type: 'select', width: 190, label: '费用审核状态', placeholder: '请选择费用审核状态', options: [
+    { value: 'UNRECORDED', label: '未录入' }, { value: 'PENDING', label: '待审核' },
+    { value: 'APPROVED', label: '审核通过' }, { value: 'REJECTED', label: '审核驳回' },
+  ], props: { 'aria-label': '费用审核状态' } },
+  {
+    key: 'tenantId',
+    type: 'select',
+    width: 220,
+    label: '公司',
+    placeholder: customerLoadError.value ? '客户列表加载失败' : customerLoading.value ? '正在加载客户' : '请选择公司',
+    options: customers.value.map((customer) => ({
+      value: String(customer.id),
+      label: customer.legalName?.trim() || customer.tenantName,
+    })),
+    props: { 'aria-label': '公司', filterable: true, loading: customerLoading.value, disabled: Boolean(customerLoadError.value) },
+  },
+  { key: 'containerNo', type: 'input', width: 210, label: '真实集装箱号', placeholder: '请输入真实集装箱号', props: { 'aria-label': '真实集装箱号' } },
+  { key: 'cabinetNo', type: 'input', width: 190, label: '内部柜次号', placeholder: '请输入内部柜次号', props: { 'aria-label': '内部柜次号' } },
+  { key: 'channelName', type: 'input', width: 210, label: '渠道', placeholder: '请输入渠道名称', props: { 'aria-label': '渠道' } },
+  { key: 'sailingDate', type: 'date', width: 190, label: '船期', placeholder: '请选择船期', props: { 'aria-label': '船期' } },
+  { key: 'loaded', type: 'select', width: 180, label: '是否已配载', placeholder: '请选择配载状态', options: [{ value: 'true', label: '已配载' }, { value: 'false', label: '未配载' }], props: { 'aria-label': '是否已配载' } },
+  { key: 'fullContainer', type: 'select', width: 180, label: '是否整柜', placeholder: '请选择装柜方式', options: [{ value: 'true', label: '整柜' }, { value: 'false', label: '拼箱' }], props: { 'aria-label': '是否整柜' } },
+  { key: 'measurementReviewStatus', type: 'select', width: 220, label: '测量数据审核状态', placeholder: '请选择测量审核状态', options: [
+    { value: 'UNRECORDED', label: '未录入' }, { value: 'PENDING', label: '待审核' },
+    { value: 'APPROVED', label: '审核通过' }, { value: 'REJECTED', label: '审核驳回' },
+  ], props: { 'aria-label': '测量数据审核状态' } },
+  { key: 'fbaCode', type: 'input', width: 220, label: '商品 SKU 编码', placeholder: '请输入商品 SKU 编码', props: { 'aria-label': '商品 SKU 编码' } },
+  { key: 'createdRange', type: 'daterange', width: 300, label: '创建日期', placeholder: '创建日期范围', props: { 'aria-label': '创建日期范围' } },
+])
+
+const allQueryFields = computed(() => [...primaryQueryFields.value, ...advancedQueryFields.value])
+const queryFields = computed(() => showAdvancedFilters.value
+  ? allQueryFields.value
+  : primaryQueryFields.value)
+
+const columns = computed<DataTableColumn[]>(() => [
+  // 业务表格保持操作列第一；批量选择列仅在有对应权限时紧随其后。
+  { key: 'actions', label: '操作', width: 260, fixed: 'left', slotName: 'actions' },
+  ...(can('platform:order:approve') || can('platform:firstleg:smart-loading:assign') || can('platform:order:export') || can('platform:firstleg:inbound:view') ? [{
+    key: 'selection', type: 'selection', width: 48, fixed: 'left',
+    selectable: () => !batchApprovalSaving.value && !coLoadSaving.value && !exportSubmitting.value,
+  } satisfies DataTableColumn] : []),
+  { key: 'inboundCode', prop: 'inboundCode', label: '入仓码', minWidth: 160, slotName: 'inboundCode' },
+  { key: 'mainStatus', prop: 'mainStatus', label: '订单主状态', minWidth: 120, slotName: 'mainStatus' },
+  { key: 'customerName', prop: 'customerName', label: '客户', minWidth: 120, slotName: 'field' },
+  { key: 'receivingWarehouseName', prop: 'receivingWarehouseName', label: '平台收货仓', minWidth: 100, slotName: 'field' },
+  { key: 'destinationWarehouseName', prop: 'destinationWarehouseName', label: '目的仓', minWidth: 100, slotName: 'field' },
+  { key: 'channelName', prop: 'channelName', label: '渠道', minWidth: 140, slotName: 'channel' },
+  { key: 'totalPackageCount', prop: 'totalPackageCount', label: '总箱数', minWidth: 80, slotName: 'field' },
+  { key: 'expectedArrivalAt', prop: 'expectedArrivalAt', label: '预计到货时间', minWidth: 170, slotName: 'expectedArrival' },
+  { key: 'estimatedVolumeCbm', prop: 'estimatedVolumeCbm', label: '预估体积(m³)', minWidth: 120, slotName: 'estimatedVolume' },
+  { key: 'expectedVolumeCbm', prop: 'expectedVolumeCbm', label: '下单体积(m³)', minWidth: 130, slotName: 'field' },
+  { key: 'actualVolumeCbm', prop: 'actualVolumeCbm', label: '实测体积(m³)', minWidth: 130, slotName: 'field' },
+  { key: 'totalPalletCount', prop: 'totalPalletCount', label: '总托数', minWidth: 90, slotName: 'field' },
+  { key: 'requestedPickupAt', prop: 'requestedPickupAt', label: '预约提货时间', minWidth: 140, slotName: 'field' },
+  { key: 'locationCodes', prop: 'locationCodes', label: '库位位置', minWidth: 160, slotName: 'field', defaultVisible: false },
+  { key: 'measurementReviewStatus', prop: 'measurementReviewStatus', label: '测量数据审核状态', minWidth: 150, slotName: 'measurementReviewStatus' },
+  { key: 'actualGrossWeightKg', prop: 'actualGrossWeightKg', label: '实测毛重(kg)', minWidth: 120, slotName: 'field' },
+  { key: 'totalNetWeightKg', prop: 'totalNetWeightKg', label: '货物净重(kg)', minWidth: 120, slotName: 'field' },
+  { key: 'chargeableWeightKg', prop: 'chargeableWeightKg', label: '计费毛重', minWidth: 120, slotName: 'field' },
+  { key: 'chargeableVolumeCbm', prop: 'chargeableVolumeCbm', label: '计费体积(m³)', minWidth: 130, slotName: 'field' },
+  { key: 'expectedShipDate', prop: 'expectedShipDate', label: '预计出运日期', minWidth: 150, slotName: 'field' },
+  { key: 'feeReviewStatus', prop: 'feeReviewStatus', label: '费用审核状态', minWidth: 140, slotName: 'field', defaultVisible: false },
+  { key: 'skuNos', prop: 'skuNos', label: 'SKU 编码', minWidth: 180, slotName: 'field', defaultVisible: false },
+  { key: 'totalQuantity', prop: 'totalQuantity', label: '货物总数量', minWidth: 120, slotName: 'field', defaultVisible: false },
+  { key: 'expressCompany', prop: 'expressCompany', label: '快递公司', minWidth: 140, slotName: 'field', defaultVisible: false },
+  { key: 'expressTrackingNo', prop: 'expressTrackingNo', label: '快递单号', minWidth: 170, slotName: 'field', defaultVisible: false },
+  { key: 'shipmentId', prop: 'shipmentId', label: 'Shipment ID', minWidth: 160, slotName: 'field', defaultVisible: false },
+  { key: 'referenceId', prop: 'referenceId', label: 'Reference ID', minWidth: 160, slotName: 'field', defaultVisible: false },
+  { key: 'containerNo', prop: 'containerNo', label: '真实集装箱号', minWidth: 160, slotName: 'field', defaultVisible: false },
+  { key: 'cabinetNo', prop: 'cabinetNo', label: '内部柜次号', minWidth: 150, slotName: 'field', defaultVisible: false },
+  { key: 'effectiveSailingAt', prop: 'effectiveSailingAt', label: '开船时间', minWidth: 180, slotName: 'field' },
+  { key: 'effectivePortArrivalAt', prop: 'effectivePortArrivalAt', label: '到港时间', minWidth: 180, slotName: 'field' },
+  { key: 'customerRemark', prop: 'customerRemark', label: '客户备注', minWidth: 180, slotName: 'field', defaultVisible: false },
+  { key: 'latestInternalNote', prop: 'latestInternalNote', label: '内部备注', minWidth: 180, slotName: 'field', defaultVisible: false },
+  { key: 'createdAt', prop: 'createdAt', label: '创建时间', minWidth: 150, slotName: 'field', defaultVisible: false },
+  { key: 'updatedAt', prop: 'updatedAt', label: '更新时间', minWidth: 150, slotName: 'field' },
+])
+
+function emptyFilters(): FilterModel {
+  return {
+    tenantId: '', receivingWarehouseId: '', destinationWarehouseId: '',
+    inboundCode: '', expectedArrivalDate: '', feeReviewStatus: '', channelName: '',
+    containerNo: '', cabinetNo: '', sailingDate: '', loaded: '', fullContainer: '', measurementReviewStatus: '',
+    fbaCode: '', createdRange: [],
+  }
+}
+
+function cloneFilters(source: FilterModel): FilterModel {
+  return { ...source, createdRange: [...source.createdRange] }
+}
+
+function trimmed(value: string) {
+  return value.trim() || undefined
+}
+
+function optionalBoolean(value: string | null | undefined) {
+  if (value === 'true') return true
+  if (value === 'false') return false
+  return undefined
+}
+
+function selectStatus(status: UnifiedOrderMainStatus | '') {
+  if (selectedStatus.value === status) return
+  selectedStatus.value = status
+  if (page.value === 1) void loadOrders()
+  else page.value = 1
+}
+
+function handleTabKeydown(event: KeyboardEvent, index: number) {
+  let nextIndex = index
+  if (event.key === 'ArrowRight') nextIndex = (index + 1) % statusTabs.value.length
+  else if (event.key === 'ArrowLeft') nextIndex = (index - 1 + statusTabs.value.length) % statusTabs.value.length
+  else if (event.key === 'Home') nextIndex = 0
+  else if (event.key === 'End') nextIndex = statusTabs.value.length - 1
+  else return
+  event.preventDefault()
+  const tab = statusTabs.value[nextIndex]
+  if (!tab) return
+  selectStatus(tab.value)
+  const buttons = (event.currentTarget as HTMLElement).parentElement?.querySelectorAll<HTMLElement>('[role="tab"]')
+  buttons?.[nextIndex]?.focus()
+}
+
+function can(permission: string) {
+  return access.can(permission)
+}
+
+function planningDraft(row: UnifiedOrderResource) {
+  const key = String(row.orderId)
+  let draft = planningDrafts[key]
+  if (!draft) {
+    draft = {
+      expectedArrivalAt: row.expectedArrivalAt || '',
+      estimatedVolumeCbm: row.estimatedVolumeCbm ?? null,
+      savedExpectedArrivalAt: row.expectedArrivalAt || '',
+      savedEstimatedVolumeCbm: row.estimatedVolumeCbm ?? null,
+      saving: false,
+    }
+    planningDrafts[key] = draft
+  }
+  return draft
+}
+
+async function savePlanning(row: UnifiedOrderResource) {
+  const draft = planningDraft(row)
+  if (!canEditPlanning(row) || draft.saving) return
+  const estimatedVolumeCbm = draft.estimatedVolumeCbm ?? null
+  draft.estimatedVolumeCbm = estimatedVolumeCbm
+  if (!Number.isInteger(row.orderVersion)) {
+    ElMessage.error('订单版本缺失，请刷新列表后重试')
+    return
+  }
+  if (estimatedVolumeCbm !== null && (!Number.isFinite(estimatedVolumeCbm) || estimatedVolumeCbm <= 0)) {
+    ElMessage.warning('预估体积必须大于 0，或清空该值')
+    return
+  }
+  if (draft.expectedArrivalAt === draft.savedExpectedArrivalAt
+    && estimatedVolumeCbm === draft.savedEstimatedVolumeCbm) return
+
+  draft.saving = true
+  try {
+    const result = await updatePlatformUnifiedOrderPlanning(String(row.tenantId), String(row.orderId), {
+      expectedVersion: row.orderVersion!,
+      expectedArrivalAt: draft.expectedArrivalAt || null,
+      estimatedVolumeCbm,
+    })
+    row.orderVersion = result.version
+    row.expectedArrivalAt = draft.expectedArrivalAt || null
+    row.estimatedVolumeCbm = estimatedVolumeCbm
+    draft.savedExpectedArrivalAt = draft.expectedArrivalAt
+    draft.savedEstimatedVolumeCbm = estimatedVolumeCbm
+    ElMessage.success('订单运营预估已更新')
+  } catch (error) {
+    const details = getApiErrorDetails(error, '订单运营预估保存失败')
+    const evidence = [
+      details.code ? `错误码 ${details.code}` : '',
+      details.requestId ? `Request ID ${details.requestId}` : '',
+      details.traceId ? `Trace ID ${details.traceId}` : '',
+    ].filter(Boolean).join('；')
+    ElMessage.error({
+      message: evidence ? `${details.message}（${evidence}）` : details.message,
+      duration: 6_000,
+      showClose: true,
+    })
+  } finally {
+    draft.saving = false
+  }
+}
+
+const planningEditableOrderStatuses = new Set(['DRAFT', 'REJECTED', 'SUBMITTED', 'APPROVED'])
+
+function canEditPlanning(row: UnifiedOrderResource) {
+  return can('platform:order:declaration:edit')
+    && planningEditableOrderStatuses.has(row.internalOrderStatus || '')
+}
+
+const declarationEditableStatuses = new Set<UnifiedOrderMainStatus>(['PENDING_REVIEW', 'WAIT_MEASURE', 'WAIT_SPLIT'])
+const canEditDeclaration = computed(() => Boolean(
+  detail.value
+  && declarationEditableStatuses.has(detail.value.summary.mainStatus)
+  && detail.value.order.order?.version !== null
+  && detail.value.order.order?.version !== undefined
+  && can('platform:order:declaration:edit'),
+))
+
+async function handleDeclarationUpdated() {
+  activeDetailTab.value = 'basic'
+  await loadDetail(true)
+}
+
+function customerName(row: UnifiedOrderResource) {
+  return row.customerName?.trim() || customers.value.find((item) => String(item.id) === String(row.tenantId))?.tenantName || '客户名称待补充'
+}
+
+function orderRelationLabel(row: UnifiedOrderResource) {
+  if (row.relation?.role === 'PARENT') return `父单 · ${row.relation.childCount} 个子单`
+  if (row.relation?.role === 'CHILD' && row.relation.splitSequence !== null) {
+    return `子单 · 第 ${row.relation.splitSequence} 次`
+  }
+  return '子单'
+}
+
+function openOrderRelation(row: UnifiedOrderResource) {
+  relationOrder.value = row
+  relationOpen.value = true
+}
+
+function formatDate(value: string | null | undefined) {
+  return value ? value.replace('T', ' ').slice(0, 16) : '—'
+}
+
+function formatNumber(value: number | null | undefined, digits = 2) {
+  return value === null || value === undefined ? '—' : value.toLocaleString('zh-CN', { maximumFractionDigits: digits })
+}
+
+function partyValue(parties: Array<Record<string, unknown>>, type: 'SENDER' | 'RECEIVER', key: string) {
+  const party = parties.find((item) => String(item.partyType || '').toUpperCase() === type)
+  const value = party?.[key]
+  return value === null || value === undefined || value === '' ? '—' : String(value)
+}
+
+function partyAddress(parties: Array<Record<string, unknown>>, type: 'SENDER' | 'RECEIVER') {
+  const party = parties.find((item) => String(item.partyType || '').toUpperCase() === type)
+  if (!party) return '—'
+  return ['province', 'city', 'district', 'addressLine'].map((key) => party[key]).filter((value) => typeof value === 'string' && value.trim()).join(' ') || '—'
+}
+
+function cargoTotal(cargoes: Array<Record<string, unknown>>, key: string) {
+  const total = cargoes.reduce((sum, cargo) => {
+    const value = Number(cargo[key])
+    return Number.isFinite(value) ? sum + value : sum
+  }, 0)
+  return total > 0 ? total : null
+}
+
+function displayBoolean(value: boolean | null | undefined) {
+  return value === null || value === undefined ? '—' : value ? '是' : '否'
+}
+
+function formatEffectiveTransportTime(value: string | null | undefined, estimated: boolean | null | undefined) {
+  if (!value) return '—'
+  return `${estimated === true ? '预计 ' : ''}${formatDate(value)}`
+}
+
+function displayField(row: UnifiedOrderResource, property: string | undefined) {
+  if (!property) return '—'
+  const source = row as unknown as Record<string, unknown>
+  const nested: Record<string, string> = {
+    measurementReviewStatus: 'measurement.reviewStatus', expectedArrivalAt: 'expectedArrivalAt',
+    containerNo: 'transport.containerNo', cabinetNo: 'transport.cabinetNo',
+    effectiveSailingAt: 'transport.effectiveSailingAt', effectivePortArrivalAt: 'transport.effectivePortArrivalAt',
+    chargeableWeightKg: 'measurement.chargeableWeightKg', measurementCompletedAt: 'measurement.completedAt',
+    expressTrackingNo: 'delivery.trackingNo',
+  }
+  const path = nested[property] || property
+  let value = path.split('.').reduce<unknown>((current, key) => (
+    current && typeof current === 'object' ? (current as Record<string, unknown>)[key] : undefined
+  ), source)
+  if ((value === null || value === undefined || value === '') && property === 'internalOrderStatus') value = source.mainStatus
+  if (property === 'requestedPickupAt' && (row.pickupMethod !== 'PICKUP' || !value)) return '—'
+  if (property === 'effectiveSailingAt') return formatEffectiveTransportTime(row.transport?.effectiveSailingAt, row.transport?.effectiveSailingAtEstimated)
+  if (property === 'effectivePortArrivalAt') return formatEffectiveTransportTime(row.transport?.effectivePortArrivalAt, row.transport?.effectivePortArrivalAtEstimated)
+  if (value === null || value === undefined || value === '') return '—'
+  if (typeof value === 'boolean') return value ? '是' : '否'
+  if (Array.isArray(value)) return value.length ? (property === 'skuNos' ? value.join('、') : `${value.length} 个文件`) : '—'
+  if (typeof value === 'number') {
+    if (['actualVolumeCbm', 'chargeableVolumeCbm'].includes(property)) return formatNumber(value, 3)
+    return formatNumber(value)
+  }
+  if (property.endsWith('At') || property.endsWith('Date')) return formatDate(String(value))
+  if (property === 'measurementReviewStatus') return measurementStatusLabel(String(value))
+  if (property === 'internalOrderStatus') return orderStatusLabel(String(value))
+  if (property === 'feeReviewStatus') return feeReviewLabel(String(value))
+  if (property === 'businessType') return firstLegBusinessTypeLabel(String(value))
+  if (property === 'pickupMethod') return firstLegPickupMethodLabel(String(value))
+  if (property === 'taxMode') return firstLegTaxModeLabel(String(value))
+  if (property === 'destinationType') return firstLegDestinationTypeLabel(String(value))
+  return String(value)
+}
+
+function statusLabel(value: UnifiedOrderMainStatus | string | null) {
+  return unifiedOrderStatusLabel(value, '状态更新')
+}
+
+function historyActionLabel(value: string | null | undefined) {
+  return unifiedOrderHistoryActionLabel(value)
+}
+
+function measurementStatusLabel(value: string | null | undefined) {
+  return unifiedOrderReviewStatusLabel(value, '未录入')
+}
+
+function orderStatusLabel(value: string | null | undefined) {
+  return unifiedOrderStatusLabel(value)
+}
+
+function cargoValue(cargo: Record<string, unknown>, key: string) {
+  const value = cargo[key]
+  if (key === 'circumferenceCm') {
+    const length = Number(cargo.lengthCm)
+    const width = Number(cargo.widthCm)
+    const height = Number(cargo.heightCm)
+    return Number.isFinite(length) && Number.isFinite(width) && Number.isFinite(height)
+      ? formatNumber(length + 2 * (width + height))
+      : '—'
+  }
+  if (value === null || value === undefined || value === '') return '—'
+  if (typeof value === 'number') return formatNumber(value)
+  return String(value)
+}
+
+function cargoImage(cargo: Record<string, unknown>) {
+  const value = cargo.imageUrl || cargo.cargoImageUrl || cargo.image
+  return typeof value === 'string' && value ? value : ''
+}
+
+function releaseCargoImagePreviews() {
+  cargoImagePreviewUrls.forEach((url) => URL.revokeObjectURL(url))
+  cargoImagePreviewUrls.clear()
+}
+
+async function loadCargoImagePreviews(resource: UnifiedOrderDetailResource, serial: number) {
+  const tenantId = String(resource.summary.tenantId || '')
+  if (!tenantId) return
+  const cargoesByFileId = new Map<string, typeof resource.order.cargoes>()
+  for (const cargo of resource.order?.cargoes ?? []) {
+    const fileId = cargo.productImageFileId === null || cargo.productImageFileId === undefined
+      ? ''
+      : String(cargo.productImageFileId)
+    if (!fileId) continue
+    const cargoes = cargoesByFileId.get(fileId) ?? []
+    cargoes.push(cargo)
+    cargoesByFileId.set(fileId, cargoes)
+  }
+  await Promise.all([...cargoesByFileId.entries()].map(async ([fileId, cargoes]) => {
+    try {
+      const blob = await downloadPlatformProductImage(tenantId, fileId)
+      if (serial !== detailRequestSerial || detailRouteKey.value !== `${tenantId}:${orderId.value}`) return
+      const url = URL.createObjectURL(blob)
+      cargoes.forEach((cargo) => { cargo.imageUrl = url })
+      cargoImagePreviewUrls.add(url)
+    } catch {
+      // Historical files may have been removed; keep the remaining cargo fields visible.
+    }
+  }))
+}
+
+function feeReviewLabel(value: string | null | undefined) {
+  return unifiedOrderReviewStatusLabel(value)
+}
+
+function measurementValue(row: Record<string, unknown>, key: string, customerSource = false, outerSource = false) {
+  if (key === 'coefficientMode') return measurementCalculationLabel(row)
+  if (outerSource && ['lengthCm', 'widthCm', 'heightCm'].includes(key)) {
+    const outerValue = row[`outer${key[0].toUpperCase()}${key.slice(1)}`]
+    return outerValue == null ? '—' : formatNumber(Number(outerValue), 6)
+  }
+  if (customerSource && key === 'unitWeightKg') {
+    const total = Number(row.grossWeightKg)
+    const count = Number(row.packageCount)
+    return Number.isFinite(total) && Number.isFinite(count) && count > 0 ? formatNumber(total / count, 4) : '—'
+  }
+  if (key === 'unitWeightKg') {
+    const value = Number(row[key])
+    return Number.isFinite(value) ? formatNumber(value, 4) : '—'
+  }
+  if (customerSource && key === 'unitVolumeCbm') {
+    const total = Number(row.volumeCbm)
+    const count = Number(row.packageCount)
+    return Number.isFinite(total) && Number.isFinite(count) && count > 0 ? formatNumber(total / count, 6) : '—'
+  }
+  if (customerSource && key === 'remark') return String(row.cargoRemark || '—')
+  const value = row[key]
+  if (value === null || value === undefined || value === '') return '—'
+  return typeof value === 'number' ? formatNumber(value, 6) : String(value)
+}
+
+function measurementCalculationLabel(row: Record<string, unknown>) {
+  if (measurementCalculationModeForRow(row) === 'MULTIPLY') {
+    return `乘以${measurementChargeRuleName(row.chargeRuleId)}`
+  }
+  if (measurementCalculationModeForRow(row) === 'ACTUAL') return '实测原尺寸（不调整）'
+  return addCoefficientLabel(row).replace('原尺寸 + ', '加')
+}
+
+function measurementCalculationModeForRow(row: Record<string, unknown>): MeasurementCalculationMode {
+  if (row.coefficientMode === 'MULTIPLY') return 'MULTIPLY'
+  if (row.coefficientMode === 'ADD') return 'ADD'
+  const itemNo = normalizedIdentifier(row.itemNo)
+  const measuredItem = measurementDetail.value?.items.find((item) => normalizedIdentifier(item.itemNo) === itemNo)
+  return measuredItem?.coefficientMode === 'MULTIPLY' ? 'MULTIPLY' : measuredItem?.coefficientMode === 'ADD' ? 'ADD' : 'ACTUAL'
+}
+
+async function updateMeasurementCalculationMode(row: Record<string, unknown> | null, mode: MeasurementCalculationMode, selectedRuleId?: string): Promise<boolean> {
+  const summary = detail.value?.summary
+  const measurement = measurementDetail.value
+  if (!summary?.inboundId || !measurement?.measurementId || measurement.version == null || !measurementStrategyEditable.value) return false
+  const itemId = normalizedIdentifier(row?.id)
+  const itemNo = normalizedIdentifier(row?.itemNo)
+  const targetIds = new Set(measurement.items
+    .filter((item) => !row || (itemId ? String(item.id) === itemId : normalizedIdentifier(item.itemNo) === itemNo))
+    .map((item) => String(item.id)))
+  if (!targetIds.size) {
+    ElMessage.warning('当前数据尚未关联实测明细，暂不能设置计算方式')
+    return false
+  }
+  measurementStrategySavingId.value = row ? (itemId || `item-${itemNo}`) : 'all'
+  try {
+    await Promise.all([loadMeasurementChargeRules(), loadMeasurementDimensionConfig()])
+    const existingRuleId = selectedRuleId || measurement.items
+      .map((item) => String(item.chargeRuleId || ''))
+      .find((id) => id)
+    const activeRule = measurementChargeRules.value.find((rule) => rule.id === existingRuleId && rule.status === 'ACTIVE')
+      || activeMeasurementChargeRule.value
+    if (mode === 'MULTIPLY' && selectedRuleId && !activeRule) {
+      ElMessage.warning('请选择当前客户已启用的计费规则')
+      return false
+    }
+    const requiresMultiply = measurement.items.some((item) => (
+      targetIds.has(String(item.id)) ? mode : item.coefficientMode
+    ) === 'MULTIPLY')
+    if (requiresMultiply && !activeRule) {
+      ElMessage.warning('该客户尚未启用系数配置，请先到客户计费规则中设置默认规则')
+      return false
+    }
+    const savedDraft = await updateMeasurementCalculationStrategy(String(summary.tenantId), String(summary.inboundId), {
+      measurementId: String(measurement.measurementId),
+      version: measurement.version,
+      coefficientMode: mode,
+      chargeRuleId: mode === 'MULTIPLY' ? activeRule!.id : null,
+    })
+    // PUT 返回的新版本已经代表事务保存成功。详情查询可能经过读副本并短暂返回旧版本，
+    // 不能用紧随其后的旧数据否定本次成功保存；先按新版本和本次规则更新本地视图。
+    measurementDetail.value = {
+      ...measurement,
+      version: savedDraft.version,
+      measurementStatus: savedDraft.status,
+      items: measurement.items.map((item) => targetIds.has(String(item.id)) ? {
+        ...item,
+        coefficientMode: mode,
+        chargeRuleId: mode === 'MULTIPLY' ? activeRule!.id : null,
+        calculatedOuterLengthCm: null,
+        calculatedOuterWidthCm: null,
+        calculatedOuterHeightCm: null,
+      } : item),
+    }
+    measurementSectionModes.outer = mode
+    const refreshed = await waitForSavedMeasurementVersion(
+      String(summary.tenantId), String(summary.inboundId), savedDraft.version,
+    )
+    if (refreshed) measurementDetail.value = refreshed
+    measurementSectionModes.outer = mode
+    measurementLoadedKey.value = ''
+    ElMessage.success(`${row ? '当前数据' : '全部测量数据'}已保存并绑定计算规则，体积已重新计算`)
+    return true
+  } catch (error) {
+    measurementLoadedKey.value = ''
+    await loadMeasurementDetails()
+    ElMessage.error(getApiErrorDetails(error, '计算方式更新失败').message)
+    return false
+  } finally {
+    measurementStrategySavingId.value = ''
+  }
+}
+
+async function saveWarehouseOuterDimensions(row: Record<string, unknown>) {
+  const summary = detail.value?.summary
+  const measurement = measurementDetail.value
+  if (!summary?.inboundId || !measurement?.measurementId || measurement.version == null
+    || !measurementStrategyEditable.value) return
+  const dimensions = [row.outerLengthCm, row.outerWidthCm, row.outerHeightCm]
+    .map((value) => value == null || value === '' ? null : Number(value))
+  if (dimensions.some((value) => value != null && (!Number.isFinite(value) || value <= 0))) {
+    ElMessage.warning('仓库修改外箱尺寸必须大于 0')
+    return
+  }
+  measurementOuterSavingId.value = String(row.id)
+  try {
+    const saved = await updateMeasurementOuterDimensions(
+      String(summary.tenantId), String(summary.inboundId), String(row.id), {
+      measurementId: String(measurement.measurementId),
+      version: measurement.version,
+      outerLengthCm: dimensions[0],
+      outerWidthCm: dimensions[1],
+      outerHeightCm: dimensions[2],
+    })
+    measurementDetail.value = {
+      ...measurement,
+      version: saved.version,
+      measurementStatus: saved.status,
+      items: measurement.items.map((item) => String(item.id) === String(row.id) ? {
+        ...item,
+        outerLengthCm: dimensions[0],
+        outerWidthCm: dimensions[1],
+        outerHeightCm: dimensions[2],
+        calculatedOuterLengthCm: dimensions[0],
+        calculatedOuterWidthCm: dimensions[1],
+        calculatedOuterHeightCm: dimensions[2],
+      } : item),
+    }
+    const refreshed = await waitForSavedMeasurementVersion(
+      String(summary.tenantId), String(summary.inboundId), saved.version,
+    )
+    if (refreshed) measurementDetail.value = refreshed
+    measurementLoadedKey.value = ''
+    ElMessage.success(`序号 ${row.itemNo || '—'} 的外箱规已更新，相关数值已重新计算`)
+  } catch (error) {
+    measurementLoadedKey.value = ''
+    await loadMeasurementDetails()
+    ElMessage.error(getApiErrorDetails(error, '仓库外箱尺寸保存失败').message)
+  } finally {
+    measurementOuterSavingId.value = ''
+  }
+}
+
+function measurementChargeRuleName(ruleId: unknown) {
+  const normalizedRuleId = normalizedIdentifier(ruleId)
+  const selected = normalizedRuleId
+    ? measurementChargeRules.value.find((rule) => rule.id === normalizedRuleId)
+    : null
+  const fallback = measurementChargeRules.value.find((rule) => rule.defaultRule && rule.status === 'ACTIVE')
+    || measurementChargeRules.value.find((rule) => rule.status === 'ACTIVE')
+  const rule = selected || fallback
+  if (rule) {
+    const remark = rule.remark?.trim()
+    return `系数 ${rule.lengthFactor}${remark ? ` · ${remark}` : ''}${rule.defaultRule ? '（默认）' : ''}`
+  }
+  if (measurementChargeRulesLoading.value) return '加载中…'
+  return normalizedRuleId || '未配置'
+}
+
+async function loadMeasurementChargeRules() {
+  const tenantId = normalizedIdentifier(detail.value?.summary.tenantId)
+  const customerId = normalizedIdentifier(detail.value?.summary.customerId) || tenantId
+  const loadedKey = `${tenantId}:${customerId}`
+  if (!customerId || measurementChargeRulesLoadedKey.value === loadedKey || measurementChargeRulesLoading.value) return
+  measurementChargeRulesLoading.value = true
+  try {
+    measurementChargeRules.value = await listCustomerChargeRules(customerId, tenantId)
+    measurementChargeRulesLoadedKey.value = loadedKey
+  } catch {
+    measurementChargeRules.value = []
+  } finally {
+    measurementChargeRulesLoading.value = false
+  }
+}
+
+async function loadMeasurementDimensionConfig(force = false) {
+  const tenantId = normalizedIdentifier(detail.value?.summary.tenantId)
+  if (!tenantId || (!force && measurementDimensionConfigLoadedKey.value === tenantId) || measurementDimensionConfigLoading.value) return
+  measurementDimensionConfigLoading.value = true
+  try {
+    measurementDimensionConfig.value = await getCustomerDimensionConfig(tenantId)
+    measurementDimensionConfigLoadedKey.value = tenantId
+  } catch {
+    measurementDimensionConfig.value = null
+  } finally {
+    measurementDimensionConfigLoading.value = false
+  }
+}
+
+interface MeasurementTotals {
+  count: number
+  gross: number
+  volume: number
+  volumetric: number
+}
+
+function measurementTotals(rows: Record<string, unknown>[], customerSource = false) {
+  const values = rows.reduce<MeasurementTotals>((result, row) => {
+    const count = Number(row.packageCount)
+    const gross = Number(customerSource ? row.grossWeightKg : row.totalWeightKg)
+    const volume = Number(customerSource ? row.volumeCbm : row.totalVolumeCbm)
+    const volumetric = Number(row.volumeWeightKg)
+    if (Number.isFinite(count)) result.count += count
+    if (Number.isFinite(gross)) result.gross += gross
+    if (Number.isFinite(volume)) result.volume += volume
+    if (Number.isFinite(volumetric)) result.volumetric += volumetric
+    return result
+  }, { count: 0, gross: 0, volume: 0, volumetric: 0 })
+  return {
+    count: values.count || null, gross: values.gross || null, volume: values.volume || null,
+    volumetric: values.volumetric || null, weightVolume: values.volume || null,
+  }
+}
+
+function releaseMeasurementPreview() {
+  measurementPreviewRequestSerial += 1
+  if (measurementPreviewUrl.value) URL.revokeObjectURL(measurementPreviewUrl.value)
+  measurementPreviewUrl.value = ''
+  measurementPreviewLoading.value = false
+  measurementPreviewError.value = null
+}
+
+async function openMeasurementEvidence(fileId: string | null, title: string) {
+  const summary = detail.value?.summary
+  if (!fileId || !summary?.inboundId) return
+  releaseMeasurementPreview()
+  const serial = ++measurementPreviewRequestSerial
+  measurementPreviewTitle.value = title
+  measurementPreviewOpen.value = true
+  measurementPreviewLoading.value = true
+  try {
+    const blob = await downloadWeightImage(String(summary.tenantId), String(summary.inboundId), fileId)
+    if (serial !== measurementPreviewRequestSerial) return
+    measurementPreviewUrl.value = URL.createObjectURL(blob)
+  } catch (error) {
+    if (serial !== measurementPreviewRequestSerial) return
+    measurementPreviewError.value = getApiErrorDetails(error, '测量原图读取失败，请稍后重试')
+  } finally {
+    if (serial === measurementPreviewRequestSerial) measurementPreviewLoading.value = false
+  }
+}
+
+async function loadMeasurementDetails() {
+  const summary = detail.value?.summary
+  if (!summary?.inboundId || !can('platform:firstleg:inbound:measure:view')) return
+  const key = `${summary.tenantId}:${summary.inboundId}`
+  if (measurementLoadedKey.value === key || measurementLoading.value) return
+  const serial = ++measurementRequestSerial
+  measurementLoading.value = true
+  measurementError.value = null
+  try {
+    const [response] = await Promise.all([
+      getInboundMeasurement(String(summary.tenantId), String(summary.inboundId)),
+      loadMeasurementChargeRules(),
+      loadMeasurementDimensionConfig(true),
+    ])
+    if (serial !== measurementRequestSerial) return
+    measurementDetail.value = response
+    const configuredMode = measurementDimensionConfig.value?.defaultCalculationMode
+    const savedModes = [...new Set(response.items.map((item) => item.coefficientMode)
+      .filter((mode): mode is MeasurementCalculationMode => (
+        mode === 'ACTUAL' || mode === 'ADD' || mode === 'MULTIPLY'
+      )))]
+    // 订单测量明细中已落库的规则是本次计费快照，必须优先于客户当前默认规则。
+    // 客户默认值只用于尚未绑定规则的新测量数据，避免保存后又被覆盖回 ACTUAL。
+    measurementSectionModes.outer = savedModes.length === 1
+      ? savedModes[0]!
+      : configuredMode === 'MULTIPLY' && activeMeasurementChargeRule.value
+        ? 'MULTIPLY' : configuredMode === 'ADD' ? 'ADD' : 'ACTUAL'
+    measurementSectionModes.customer = configuredMode === 'MULTIPLY' && activeMeasurementChargeRule.value
+      ? 'MULTIPLY' : configuredMode === 'ADD' ? 'ADD' : 'ACTUAL'
+    measurementSectionModes.actual = 'ACTUAL'
+    measurementLoadedKey.value = key
+  } catch (error) {
+    if (serial !== measurementRequestSerial) return
+    if (!measurementDetail.value) measurementDetail.value = null
+    measurementError.value = getApiErrorDetails(error, '测量数据加载失败，请稍后重试')
+  } finally {
+    if (serial === measurementRequestSerial) measurementLoading.value = false
+  }
+}
+
+async function loadHoldDetail(force = false) {
+  const inboundId = normalizedInboundId.value
+  const tenantId = normalizedIdentifier(detail.value?.summary.tenantId)
+  const key = inboundId && tenantId ? `${tenantId}:${inboundId}` : ''
+  if (!key || !can('platform:firstleg:inbound:list')) {
+    holdDetail.value = null
+    holdError.value = null
+    holdLoadedKey.value = ''
+    return
+  }
+  if (!force && (holdLoading.value || holdLoadedKey.value === key)) return
+  const serial = ++holdRequestSerial
+  holdLoading.value = true
+  holdError.value = null
+  try {
+    const result = await getPlatformInboundHold(tenantId, inboundId)
+    if (serial !== holdRequestSerial) return
+    holdDetail.value = result
+    holdLoadedKey.value = key
+  } catch (error) {
+    if (serial !== holdRequestSerial) return
+    holdDetail.value = null
+    holdLoadedKey.value = ''
+    holdError.value = getApiErrorDetails(error, '扣货状态与历史加载失败')
+  } finally {
+    if (serial === holdRequestSerial) holdLoading.value = false
+  }
+}
+
+function selectDetailTab(key: string) {
+  activeDetailTab.value = key
+  if (key === 'measurement') void loadMeasurementDetails()
+  if (key === 'fulfillment') void loadSubsequentFulfillment()
+  if (key === 'other') void loadHoldDetail()
+}
+
+const hasLoadingAssociation = computed(() => Boolean(loadingAssociation.value
+  && (loadingAssociation.value.loadingPlanNo || loadingAssociation.value.containerNo || loadingAssociation.value.cabinetNo
+    || loadingAssociation.value.loadingStatus || loadingAssociation.value.pdaTaskStatus)))
+const hasOverseasRelationship = computed(() => Boolean(overseasRelationship.value?.found
+  && (overseasRelationship.value.overseasWarehouse || overseasRelationship.value.overseasReceivingStatus
+    || overseasRelationship.value.taillegOrders.length || overseasRelationship.value.inboundPlans.length
+    || overseasRelationship.value.palletCodes.length || overseasRelationship.value.inventory.length)))
+const hasSubsequentFulfillment = computed(() => hasLoadingAssociation.value || hasOverseasRelationship.value)
+
+async function loadSubsequentFulfillment() {
+  const inboundCode = detail.value?.summary.inboundCode?.trim() || ''
+  const serial = ++subsequentFulfillmentRequestSerial
+  loadingAssociation.value = null
+  overseasRelationship.value = null
+  loadingAssociationError.value = null
+  overseasRelationshipError.value = null
+  if (!inboundCode) return
+  subsequentFulfillmentLoading.value = true
+  const tasks: Promise<void>[] = []
+  if (can('platform:firstleg:smart-loading:list')) tasks.push(getLoadingAssociationSummary(inboundCode)
+    .then((value) => { if (serial === subsequentFulfillmentRequestSerial) loadingAssociation.value = value })
+    .catch((error) => { if (serial === subsequentFulfillmentRequestSerial) loadingAssociationError.value = getApiErrorDetails(error, '装柜与PDA履约数据加载失败') }))
+  if (can('platform:overseas-warehouse:inventory:list')) tasks.push(getOverseasInboundCodeRelationship(inboundCode)
+    .then((value) => { if (serial === subsequentFulfillmentRequestSerial) overseasRelationship.value = value })
+    .catch((error) => { if (serial === subsequentFulfillmentRequestSerial) overseasRelationshipError.value = getApiErrorDetails(error, '尾程与库存履约数据加载失败') }))
+  await Promise.all(tasks)
+  if (serial === subsequentFulfillmentRequestSerial) subsequentFulfillmentLoading.value = false
+}
+
+function toggleMeasurementSection(section: keyof typeof measurementCollapsed) {
+  measurementCollapsed[section] = !measurementCollapsed[section]
+}
+
+function nextActionBoundary(row: UnifiedOrderResource) {
+  return row.nextAction === 'CONFIRM_MEASUREMENT' ? '待完成测量' : ''
+}
+
+function canApprove(row: UnifiedOrderResource) {
+  return row.mainStatus === 'PENDING_REVIEW' && row.nextAction === 'APPROVE_ORDER' && can('platform:order:approve')
+}
+
+function openApproval(row: UnifiedOrderResource) {
+  if (!canApprove(row)) return
+  approvalOrder.value = row
+  approvalOpen.value = true
+}
+
+function closeApproval() {
+  if (approvalSaving.value) return
+  approvalOpen.value = false
+  approvalOrder.value = null
+}
+
+async function approveOrder() {
+  if (!approvalOrder.value) return
+  const order = approvalOrder.value
+  const orderId = String(order.orderId)
+  const tenantId = String(order.tenantId)
+  approvalSaving.value = true
+  approvalLoadingId.value = orderId
+  try {
+    await approvePlatformUnifiedOrder(tenantId, orderId)
+    approvalOpen.value = false
+    await loadOrders()
+    if (detail.value?.summary.orderId === order.orderId) await loadDetail()
+    approvalOrder.value = null
+    ElMessage.success('订单审核通过')
+  } catch (error) {
+    ElMessage.error(getApiErrorDetails(error, '订单审核失败，请稍后重试').message)
+  } finally {
+    approvalSaving.value = false
+    approvalLoadingId.value = ''
+  }
+}
+
+function openNoteDialog(order?: UnifiedOrderResource) {
+  if (!can('platform:order:note')) return
+  const target = order || detail.value?.summary || null
+  if (!target) return
+  noteOrder.value = target
+  noteForm.internalRemark = target.latestInternalNote || target.internalRemark || ''
+  noteForm.warehouseRemark = target.warehouseRemark || ''
+  noteForm.customerServiceRemark = target.customerServiceRemark || ''
+  noteOpen.value = true
+}
+
+async function saveNote() {
+  if (!noteOrder.value) return
+  noteSaving.value = true
+  try {
+    const target = noteOrder.value
+    await updatePlatformUnifiedOrderRemarks(String(target.tenantId), String(target.orderId), {
+      expectedVersion: Number(target.orderVersion || 0),
+      internalRemark: noteForm.internalRemark.trim() || null,
+      warehouseRemark: noteForm.warehouseRemark.trim() || null,
+      customerServiceRemark: noteForm.customerServiceRemark.trim() || null,
+    })
+    noteOpen.value = false
+    await loadOrders()
+    if (detail.value?.summary.orderId === target.orderId) await loadDetail(true)
+    noteOrder.value = null
+    ElMessage.success('订单备注已保存')
+  } catch (error) {
+    ElMessage.error(getApiErrorDetails(error, '订单备注保存失败，请稍后重试').message)
+  } finally {
+    noteSaving.value = false
+  }
+}
+
+function openHoldDialog(action: 'HOLD' | 'RELEASE') {
+  const allowed = action === 'HOLD' ? canHoldInbound.value : canReleaseInbound.value
+  if (!allowed || !holdDetail.value) return
+  holdAction.value = action
+  holdReason.value = ''
+  holdEvidenceFile.value = null
+  holdUploadedEvidenceFileId.value = ''
+  holdEvidenceError.value = null
+  holdEvidenceUploadKey.value += 1
+  holdDialogOpen.value = true
+}
+
+const holdEvidenceMaxBytes = 10 * 1024 * 1024
+const holdEvidenceExtensions = new Set(['txt', 'pdf', 'jpg', 'jpeg', 'png'])
+
+function selectHoldEvidenceFile(upload: UploadFile) {
+  const file = upload.raw || null
+  holdEvidenceFile.value = null
+  holdUploadedEvidenceFileId.value = ''
+  holdEvidenceError.value = null
+  if (!file) return
+  const extension = file.name.split('.').pop()?.toLowerCase() || ''
+  if (!holdEvidenceExtensions.has(extension)) {
+    holdEvidenceError.value = { code: 'FILE_TYPE_INVALID', message: '关联文件仅支持 TXT、PDF、JPG、PNG' }
+    holdEvidenceUploadKey.value += 1
+    return
+  }
+  if (file.size <= 0 || file.size > holdEvidenceMaxBytes) {
+    holdEvidenceError.value = { code: 'FILE_SIZE_INVALID', message: '关联文件不能为空且不能超过 10MB' }
+    holdEvidenceUploadKey.value += 1
+    return
+  }
+  holdEvidenceFile.value = file
+}
+
+function removeHoldEvidenceFile() {
+  holdEvidenceFile.value = null
+  holdUploadedEvidenceFileId.value = ''
+  holdEvidenceError.value = null
+}
+
+async function submitHoldAction() {
+  if (holdSaving.value) return
+  const allowed = holdAction.value === 'HOLD' ? canHoldInbound.value : canReleaseInbound.value
+  if (!allowed) return
+  const reason = holdReason.value.trim()
+  const inboundId = normalizedInboundId.value
+  const tenantId = normalizedIdentifier(detail.value?.summary.tenantId)
+  if (!holdDetail.value || !inboundId || !tenantId) return
+  if (!reason) {
+    ElMessage.warning(holdAction.value === 'HOLD' ? '请填写扣货原因' : '请填写解除原因')
+    return
+  }
+  if (reason.length > 1000) {
+    ElMessage.warning('原因不能超过 1000 个字符')
+    return
+  }
+  holdSaving.value = true
+  try {
+    if (holdEvidenceFile.value && !holdUploadedEvidenceFileId.value) {
+      try {
+        holdEvidenceError.value = null
+        const uploaded = await uploadPlatformInboundHoldEvidence(tenantId, inboundId, holdEvidenceFile.value)
+        holdUploadedEvidenceFileId.value = uploaded.fileId
+      } catch (error) {
+        holdEvidenceError.value = getApiErrorDetails(error, '关联文件上传失败，请稍后重试')
+        ElMessage.error(holdEvidenceError.value.message)
+        return
+      }
+    }
+    const command = {
+      expectedVersion: holdDetail.value.version,
+      reason,
+      ...(holdUploadedEvidenceFileId.value ? { evidenceFileId: holdUploadedEvidenceFileId.value } : {}),
+    }
+    holdDetail.value = holdAction.value === 'HOLD'
+      ? await holdPlatformInbound(tenantId, inboundId, command)
+      : await releasePlatformInbound(tenantId, inboundId, command)
+    holdDialogOpen.value = false
+    await Promise.all([loadDetail(true), loadOrders()])
+    ElMessage.success(holdAction.value === 'HOLD' ? '扣货成功' : '解除扣货成功')
+  } catch (error) {
+    ElMessage.error(getApiErrorDetails(error, holdAction.value === 'HOLD' ? '扣货失败' : '解除扣货失败').message)
+  } finally {
+    holdSaving.value = false
+  }
+}
+
+async function downloadHoldEvidence(fileId: string) {
+  const inboundId = normalizedInboundId.value
+  const tenantId = normalizedIdentifier(detail.value?.summary.tenantId)
+  if (!fileId || !inboundId || !tenantId || holdDownloadingFileId.value || !can('platform:firstleg:inbound:list')) return
+  holdDownloadingFileId.value = fileId
+  try {
+    const blob = await downloadPlatformInboundHoldEvidence(tenantId, inboundId, fileId)
+    const extension = blob.type === 'application/pdf' ? '.pdf'
+      : blob.type === 'image/png' ? '.png'
+        : blob.type === 'image/jpeg' ? '.jpg'
+          : blob.type === 'text/plain' ? '.txt' : ''
+    const url = URL.createObjectURL(blob)
+    const anchor = document.createElement('a')
+    anchor.href = url
+    anchor.download = `扣货凭证${extension}`
+    document.body.appendChild(anchor)
+    anchor.click()
+    anchor.remove()
+    URL.revokeObjectURL(url)
+  } catch (error) {
+    ElMessage.error(getApiErrorDetails(error, '扣货凭证下载失败，请稍后重试').message)
+  } finally {
+    holdDownloadingFileId.value = ''
+  }
+}
+
+async function loadCustomers() {
+  customerLoading.value = true
+  customerLoadError.value = null
+  try {
+    const records: PlatformTenantResource[] = []
+    let currentPage = 1
+    let pages = 1
+    do {
+      const result = await listPlatformTenants({ page: currentPage, size: 200, status: 'ACTIVE' })
+      records.push(...result.records)
+      pages = Math.max(1, result.pages)
+      currentPage += 1
+    } while (currentPage <= pages)
+    customers.value = records
+  } catch (error) {
+    customers.value = []
+    customerLoadError.value = getApiErrorDetails(error, '客户列表加载失败，暂时无法按客户筛选')
+  } finally {
+    customerLoading.value = false
+  }
+}
+
+async function loadWarehouses() {
+  warehouseLoading.value = true
+  warehouseLoadError.value = null
+  try {
+    warehouses.value = await listAllPlatformWarehouses({ status: 'ACTIVE' })
+  } catch (error) {
+    warehouses.value = []
+    warehouseLoadError.value = getApiErrorDetails(error, '平台仓库加载失败，暂时无法按仓库筛选')
+  } finally {
+    warehouseLoading.value = false
+  }
+}
+
+async function loadOrders() {
+  selectedApprovalOrders.value = []
+  selectedOrders.value = []
+  loading.value = true
+  loadError.value = null
+  coLoadError.value = null
+  Object.keys(planningDrafts).forEach((key) => delete planningDrafts[key])
+  try {
+    const activeFilters = appliedFilters.value
+    const range = activeFilters.createdRange
+    const result = await listPlatformUnifiedOrders({
+      tenantId: activeFilters.tenantId || undefined,
+      mainStatus: selectedStatus.value || undefined,
+      receivingWarehouseId: activeFilters.receivingWarehouseId || undefined,
+      destinationWarehouseId: activeFilters.destinationWarehouseId || undefined,
+      inboundCode: trimmed(activeFilters.inboundCode),
+      expectedArrivalDate: activeFilters.expectedArrivalDate || undefined,
+      feeReviewStatus: activeFilters.feeReviewStatus || undefined,
+      channelName: trimmed(activeFilters.channelName),
+      containerNo: trimmed(activeFilters.containerNo),
+      cabinetNo: trimmed(activeFilters.cabinetNo),
+      sailingDate: activeFilters.sailingDate || undefined,
+      loaded: optionalBoolean(activeFilters.loaded),
+      fullContainer: optionalBoolean(activeFilters.fullContainer),
+      measurementReviewStatus: activeFilters.measurementReviewStatus || undefined,
+      fbaCode: trimmed(activeFilters.fbaCode),
+      createdFrom: range.length === 2 ? `${range[0]}T00:00:00` : undefined,
+      createdTo: range.length === 2 ? `${range[1]}T23:59:59` : undefined,
+      page: page.value,
+      size: pageSize.value,
+    })
+    records.value = result.records
+    total.value = result.total
+  } catch (error) {
+    records.value = []
+    total.value = 0
+    loadError.value = getApiErrorDetails(error, '统一订单列表加载失败，请检查 C02 统一查询接口和订单权限')
+  } finally {
+    loading.value = false
+  }
+}
+
+function search() {
+  appliedFilters.value = cloneFilters(filters.value)
+  if (page.value !== 1) {
+    page.value = 1
+    return
+  }
+  void loadOrders()
+}
+
+function reset() {
+  filters.value = emptyFilters()
+  appliedFilters.value = emptyFilters()
+  if (page.value === 1) void loadOrders()
+  else page.value = 1
+}
+
+async function openDetail(row: UnifiedOrderResource) {
+  await router.push({ name: 'unified-order-detail', params: { orderId: String(row.orderId) }, query: { tenantId: String(row.tenantId) } })
+  await nextTick()
+  window.scrollTo({ top: 0 })
+}
+
+function openMeasurement(row: UnifiedOrderResource) {
+  if (!row.inboundId || !can('platform:firstleg:inbound:measure:view')) return
+  measurementOrder.value = row
+  measurementDialogOpen.value = true
+}
+
+async function openFeeConfirmDialog() {
+  const summary = detail.value?.summary
+  if (!summary?.inboundId) {
+    ElMessage.warning('当前单据缺少入仓信息，暂不能发送费用')
+    return
+  }
+  if (!hasActualMeasurementData.value) {
+    ElMessage.warning('暂无实际测量数据，不能确认并发送费用')
+    return
+  }
+  if (confirmFeeSending.value) {
+    return
+  }
+  if (measurementStrategySavingId.value) {
+    ElMessage.warning('外箱规计算规则正在保存，请稍后再发送费用')
+    return
+  }
+  const outerTotals = measurementTotals(outerMeasurementRows.value)
+  if (!outerMeasurementRows.value.length || !(Number(outerTotals.volume) > 0)) {
+    ElMessage.warning('外箱规数据不完整，请先保存外箱规尺寸和计算规则')
+    return
+  }
+  const actualTotals = measurementTotals(actualMeasurementRows.value)
+  const measuredGrossWeight = Number(measurementDetail.value?.actualGrossWeightKg)
+  const measuredNetWeight = Number(measurementDetail.value?.actualNetWeightKg)
+  feeConfirmWeight.value = Number(actualTotals.gross) > 0
+    ? Number(actualTotals.gross)
+    : measuredGrossWeight > 0 ? measuredGrossWeight : measuredNetWeight > 0 ? measuredNetWeight : null
+  feeConfirmVolume.value = Number(actualTotals.volume) > 0 ? Number(actualTotals.volume) : null
+  feeConfirmReference.value = null
+  feeConfirmUnitPrice.value = null
+  feeConfirmPriceReason.value = ''
+  feeConfirmAttempt = null
+  feeConfirmOpen.value = true
+  feeConfirmReferenceLoading.value = true
+  try {
+    const tenantId = String(summary.tenantId)
+    const inboundId = String(summary.inboundId)
+    let snapshot: InboundFeeSnapshot
+    try {
+      snapshot = await getLatestInboundFee(tenantId, inboundId)
+    } catch (error) {
+      const details = getApiErrorDetails(error, '价格表参考单价加载失败')
+      if (details.code !== 'A0404') throw error
+      snapshot = await calculateInboundFee(tenantId, inboundId, {
+        selectedWeightKg: Number(feeConfirmWeight.value),
+        selectedVolumeCbm: Number(feeConfirmVolume.value),
+        weightSource: 'ACTUAL',
+        volumeSource: 'ACTUAL',
+      }, createFeeActionIdempotencyKey('calculate'))
+    }
+    feeConfirmReference.value = snapshot
+    feeConfirmUnitPrice.value = Number(snapshot.unitPrice)
+  } catch (error) {
+    ElMessage.error(getApiErrorDetails(error, '价格表参考单价加载失败，暂不能推送费用').message)
+    feeConfirmOpen.value = false
+  } finally {
+    feeConfirmReferenceLoading.value = false
+  }
+}
+
+function currentFeeConfirmAttempt(
+  selectedWeightKg: number,
+  selectedVolumeCbm: number,
+  selectedUnitPrice: number,
+) {
+  const fingerprint = JSON.stringify([
+    selectedWeightKg,
+    selectedVolumeCbm,
+    selectedUnitPrice,
+    feeConfirmPriceReason.value.trim(),
+  ])
+  if (!feeConfirmAttempt || feeConfirmAttempt.fingerprint !== fingerprint) {
+    feeConfirmAttempt = {
+      fingerprint,
+      calculateKey: createFeeActionIdempotencyKey('calculate'),
+      adjustKey: createFeeAdjustmentIdempotencyKey(),
+      confirmKey: createFeeActionIdempotencyKey('confirm'),
+      sendKey: createFeeActionIdempotencyKey('send'),
+    }
+  }
+  return feeConfirmAttempt
+}
+
+async function executeConfirmAndSendFee() {
+  if (confirmFeeSending.value) return
+  const summary = detail.value?.summary
+  if (!summary?.inboundId) return
+  const selectedWeightKg = Number(feeConfirmWeight.value)
+  const selectedVolumeCbm = Number(feeConfirmVolume.value)
+  const selectedUnitPrice = Number(feeConfirmUnitPrice.value)
+  if (!(selectedWeightKg > 0) || !(selectedVolumeCbm > 0)) {
+    ElMessage.warning('计费毛重和计费体积必须大于 0')
+    return
+  }
+  if (!(selectedUnitPrice > 0)) {
+    ElMessage.warning('对客单价必须大于 0')
+    return
+  }
+  if (feeConfirmPriceChanged.value && feeConfirmPriceReason.value.trim().length < 2) {
+    ElMessage.warning('人工修改参考单价后，请填写至少 2 个字符的调整原因')
+    return
+  }
+  const attempt = currentFeeConfirmAttempt(selectedWeightKg, selectedVolumeCbm, selectedUnitPrice)
+  confirmFeeSending.value = true
+  try {
+    const tenantId = String(summary.tenantId)
+    const inboundId = String(summary.inboundId)
+    let snapshot = await calculateInboundFee(tenantId, inboundId, {
+      selectedWeightKg,
+      selectedVolumeCbm,
+      weightSource: 'ACTUAL',
+      volumeSource: 'ACTUAL',
+    }, attempt.calculateKey)
+    const calculatedUnitPrice = Number(snapshot.unitPrice)
+    if (Math.abs(selectedUnitPrice - calculatedUnitPrice) > 0.000001) {
+      snapshot = await adjustPublishedInboundFee(tenantId, inboundId, {
+        expectedFeeVersion: snapshot.feeVersion,
+        chargeableQuantity: Number(snapshot.chargeableQuantity),
+        unitPrice: selectedUnitPrice,
+        additionalAmount: Number(snapshot.additionalAmount || 0),
+        reason: feeConfirmPriceReason.value.trim() || '推送前按已展示参考单价人工确认',
+        toleranceConfirmed: true,
+      }, attempt.adjustKey)
+    }
+    snapshot = await confirmInboundFee(tenantId, inboundId, attempt.confirmKey)
+    if (snapshot.feeStatus === 'CONFIRMED') {
+      snapshot = await sendInboundFee(tenantId, inboundId, attempt.sendKey)
+    }
+    if (snapshot.feeStatus === 'SENT') {
+      automaticFee.value = { feeStatus: snapshot.feeStatus, totalAmount: Number(snapshot.totalAmount || 0) }
+      feePanelRevision.value += 1
+      ElMessage.success('计费量和单价已确认并发送给客户')
+      feeConfirmOpen.value = false
+      feeConfirmAttempt = null
+      await loadDetail(true)
+      return
+    }
+    ElMessage.warning('当前费用状态不允许发送，请刷新后重试')
+  } catch (error) {
+    ElMessage.error(getApiErrorDetails(error, '确认费用发送失败').message)
+  } finally {
+    confirmFeeSending.value = false
+  }
+}
+
+function handleOrderSelectionChange(rows: UnifiedOrderResource[]) {
+  selectedOrders.value = rows
+  selectedApprovalOrders.value = rows.filter(canApprove)
+}
+
+function coLoadSelectionMemberLabel(row: UnifiedOrderResource) {
+  const inboundCode = row.inboundCode?.trim() || '待生成入仓码'
+  const warehouseName = row.receivingWarehouseName?.trim() || '未配置仓库'
+  const channelName = row.channelName?.trim() || '未配置渠道'
+  return `${inboundCode}（仓库：${warehouseName}；渠道：${channelName}）`
+}
+
+function coLoadSelectionMembersLabel(rows: UnifiedOrderResource[]) {
+  return rows.map(coLoadSelectionMemberLabel).join('、')
+}
+
+const coLoadSelectionProblem = computed(() => {
+  if (selectedOrders.value.length < 2) return null
+  const groupedRows = selectedOrders.value.filter((row) => row.coLoadGroup && row.coLoadGroup.status !== 'CANCELLED')
+  if (groupedRows.length) return `以下入仓码已有同柜组：${coLoadSelectionMembersLabel(groupedRows)}，请先解除原同柜组`
+  const missingWarehouseRows = selectedOrders.value.filter((row) => !String(row.receivingWarehouseId || '').trim())
+  if (missingWarehouseRows.length) return `以下入仓码缺少平台收货仓：${coLoadSelectionMembersLabel(missingWarehouseRows)}，请刷新后重试`
+  const warehouseIds = selectedOrders.value.map((row) => String(row.receivingWarehouseId).trim())
+  if (new Set(warehouseIds).size > 1) return `所选订单的平台收货仓不同：${coLoadSelectionMembersLabel(selectedOrders.value)}，不能设为同柜组`
+  const missingChannelRows = selectedOrders.value.filter((row) => !row.channelCode?.trim())
+  if (missingChannelRows.length) return `以下入仓码缺少渠道：${coLoadSelectionMembersLabel(missingChannelRows)}，请刷新后重试`
+  const channelCodes = selectedOrders.value.map((row) => row.channelCode!.trim())
+  if (new Set(channelCodes).size > 1) return `所选订单的渠道不同：${coLoadSelectionMembersLabel(selectedOrders.value)}，不能设为同柜组`
+  return null
+})
+const canCreateCoLoadGroup = computed(() => selectedOrders.value.length >= 2 && !coLoadSelectionProblem.value)
+
+function coLoadGroup(row: UnifiedOrderResource) {
+  return row.coLoadGroup || null
+}
+
+function coLoadGroupMemberLabel(group: CoLoadGroup) {
+  const orderCount = new Set(group.members.map((member) => member.orderId)).size
+  return group.members.length === orderCount
+    ? `${orderCount} 票`
+    : `${orderCount} 票 · ${group.members.length} 个入仓片段`
+}
+
+function coLoadGroupStatusLabel(group: { status: string }) {
+  return group.status === 'ACTIVE' ? '未锁定' : group.status === 'LOCKED' ? '已锁定' : group.status === 'CONSUMED' ? '已消费' : '已取消'
+}
+
+function coLoadGroupSummary(group: UnifiedOrderCoLoadGroupSummary | CoLoadBusinessSummary) {
+  return `同柜组 · ${group.memberCount} 票 · ${coLoadGroupStatusLabel(group)}`
+}
+
+function hasCoLoadMemberInboundCode(member: CoLoadBusinessSummary['members'][number]) {
+  return typeof member.inboundCode === 'string' && Boolean(member.inboundCode.trim())
+}
+
+const coLoadDetailMembers = computed(() => coLoadDetailSummary.value?.members.filter(hasCoLoadMemberInboundCode) || [])
+const coLoadDetailHasMissingInboundCodes = computed(() => Boolean(coLoadDetailSummary.value)
+  && (coLoadDetailMembers.value.length !== coLoadDetailSummary.value!.memberCount
+    || coLoadDetailSummary.value!.members.some((member) => !hasCoLoadMemberInboundCode(member))))
+
+async function loadCoLoadDetail() {
+  const inboundCode = coLoadDetailInboundCode.value
+  if (!inboundCode || coLoadDetailLoading.value) return
+  coLoadDetailLoading.value = true
+  coLoadDetailError.value = null
+  coLoadDetailSummary.value = null
+  try {
+    coLoadDetailSummary.value = await getPlatformCoLoadGroupByInboundCode(inboundCode)
+  } catch (error) {
+    coLoadDetailError.value = getApiErrorDetails(error, '同柜组成员加载失败，请刷新后重试')
+  } finally {
+    coLoadDetailLoading.value = false
+  }
+}
+
+function openCoLoadDetail(row: UnifiedOrderResource) {
+  coLoadDetailInboundCode.value = row.inboundCode?.trim() || ''
+  coLoadDetailOpen.value = true
+  coLoadDetailSummary.value = null
+  coLoadCancelError.value = null
+  coLoadDetailError.value = coLoadDetailInboundCode.value ? null : getApiErrorDetails(new Error('同柜组成员入仓码尚未返回'), '同柜组成员入仓码尚未返回，请刷新后重试')
+  if (coLoadDetailInboundCode.value) void loadCoLoadDetail()
+}
+
+function openCoLoadCreate() {
+  if (!canCreateCoLoadGroup.value) return
+  coLoadError.value = null
+  coLoadCreateOpen.value = true
+}
+
+async function createCoLoadGroup() {
+  if (!canCreateCoLoadGroup.value || coLoadSaving.value) return
+  coLoadSaving.value = true
+  coLoadError.value = null
+  try {
+    const group = await createPlatformCoLoadGroup(selectedOrders.value.map((row) => String(row.orderId)))
+    coLoadCreateOpen.value = false
+    ElMessage.success(`已创建同柜不可拆组，共 ${coLoadGroupMemberLabel(group)}`)
+    await loadOrders()
+  } catch (error) {
+    coLoadError.value = getApiErrorDetails(error, '创建同柜不可拆组失败')
+  } finally {
+    coLoadSaving.value = false
+  }
+}
+
+async function cancelCoLoadGroup() {
+  const inboundCode = coLoadDetailInboundCode.value
+  if (!inboundCode || coLoadDetailSummary.value?.status !== 'ACTIVE' || coLoadCancelSaving.value) return
+  try {
+    await ElMessageBox.confirm(
+      '确认解除整个同柜组吗？解除后这些订单可重新选择成员建组；不会拆分订单或子单。',
+      '解除同柜组',
+      { customClass: 'admin-density-confirm', confirmButtonText: '确认解除', cancelButtonText: '取消', type: 'warning' },
+    )
+  } catch (error) {
+    if (error === 'cancel' || error === 'close') return
+    throw error
+  }
+  coLoadCancelSaving.value = true
+  coLoadCancelError.value = null
+  try {
+    await cancelPlatformCoLoadGroup(inboundCode, '重新调整同柜组成员')
+    coLoadDetailOpen.value = false
+    ElMessage.success('同柜组已整组解除')
+    await loadOrders()
+  } catch (error) {
+    coLoadCancelError.value = getApiErrorDetails(error, '解除同柜组失败')
+  } finally {
+    coLoadCancelSaving.value = false
+  }
+}
+
+function batchReviewItem(order: UnifiedOrderResource): UnifiedOrderBatchReviewItem {
+  return { orderId: String(order.orderId), orderVersion: Number(order.orderVersion || 0) }
+}
+
+function handleBatchApprovalSelection(rows: UnifiedOrderBatchApprovalPreviewItem[]) {
+  batchApprovalSelectedRows.value = rows
+}
+
+async function openBatchApproval() {
+  const selected = [...selectedApprovalOrders.value]
+  if (!selected.length || batchApprovalLoading.value || batchApprovalSaving.value) return
+  batchApprovalOpen.value = true
+  batchApprovalLoading.value = true
+  batchApprovalError.value = null
+  batchApprovalPreviewRows.value = []
+  batchApprovalSelectedRows.value = []
+  try {
+    const groups = new Map<string, UnifiedOrderResource[]>()
+    selected.forEach((order) => {
+      const tenantId = String(order.tenantId)
+      groups.set(tenantId, [...(groups.get(tenantId) || []), order])
+    })
+    const previews = await Promise.all([...groups].map(([tenantId, orders]) => (
+      getPlatformUnifiedOrderBatchApprovalPreview(tenantId, orders.map(batchReviewItem))
+    )))
+    batchApprovalPreviewRows.value = previews.flatMap((preview) => preview.items)
+    await nextTick()
+    batchApprovalPreviewRows.value.forEach((row) => {
+      if (row.canApprove) batchApprovalTableRef.value?.toggleRowSelection(row, true)
+    })
+  } catch (error) {
+    batchApprovalError.value = getApiErrorDetails(error, '批量审核预览加载失败，请刷新订单后重试')
+  } finally {
+    batchApprovalLoading.value = false
+  }
+}
+
+async function batchApproveOrders() {
+  const selected = [...batchApprovalSelectedRows.value]
+  if (!selected.length || batchApprovalSaving.value) return
+  batchApprovalSaving.value = true
+  try {
+    const groups = new Map<string, UnifiedOrderBatchApprovalPreviewItem[]>()
+    selected.forEach((order) => {
+      const tenantId = String(order.customerId)
+      groups.set(tenantId, [...(groups.get(tenantId) || []), order])
+    })
+    let successCount = 0
+    let failureCount = 0
+    const failures: string[] = []
+    for (const [tenantId, orders] of groups) {
+      try {
+        const result = await batchApprovePlatformUnifiedOrders(tenantId, orders.map((order) => ({
+          orderId: order.orderId,
+          orderVersion: order.orderVersion,
+        })))
+        successCount += result.successCount
+        failureCount += result.failureCount
+        failures.push(...result.failedOrders.map((failure) => failure.message))
+      } catch (error) {
+        failureCount += orders.length
+        failures.push(getApiErrorDetails(error, '该客户订单批量审核失败').message)
+      }
+    }
+    batchApprovalOpen.value = false
+    await loadOrders()
+    const reason = [...new Set(failures.filter(Boolean))].slice(0, 3).join('；')
+    if (!failureCount) ElMessage.success(`已批量审核通过 ${successCount} 个订单`)
+    else if (successCount) ElMessage.warning(`批量审核完成：成功 ${successCount} 个，失败 ${failureCount} 个${reason ? `。${reason}` : ''}`)
+    else ElMessage.error(`批量审核失败：${failureCount} 个订单未通过${reason ? `。${reason}` : ''}`)
+  } finally {
+    batchApprovalSaving.value = false
+  }
+}
+
+function handleMeasurementUpdated() {
+  void loadOrders()
+}
+
+function handleMeasurementSubmitted() {
+  void loadOrders()
+}
+
+function clearMeasurementOrder() {
+  measurementOrder.value = null
+  openWarehouseSuggestionOnMeasurementLoad.value = false
+}
+
+type UnifiedOrderRowAction = 'note' | 'approve' | 'measurement'
+function unifiedOrderSecondaryActions(row: UnifiedOrderResource): UnifiedOrderRowAction[] {
+  return [
+    ...(canApprove(row) ? ['approve' as const] : []),
+    ...(['PENDING_REVIEW', 'WAIT_MEASURE'].includes(row.mainStatus) && row.inboundId && can('platform:firstleg:inbound:measure:view') ? ['measurement' as const] : []),
+    ...(can('platform:order:note') ? ['note' as const] : []),
+  ]
+}
+function directUnifiedOrderActions(row: UnifiedOrderResource) {
+  return unifiedOrderSecondaryActions(row).slice(0, 2)
+}
+function moreUnifiedOrderActions(row: UnifiedOrderResource) {
+  return unifiedOrderSecondaryActions(row).slice(2)
+}
+function moreUnifiedOrderActionsLabel(row: UnifiedOrderResource) {
+  return `更多订单操作：${String(row.inboundCode || '').trim() || '当前入仓单'}`
+}
+function unifiedOrderActionLabel(action: UnifiedOrderRowAction) {
+  if (action === 'note') return '备注'
+  if (action === 'approve') return '通过'
+  return '测量'
+}
+function runMoreAction(command: string | number | object, row: UnifiedOrderResource) {
+  if (command === 'note') openNoteDialog(row)
+  if (command === 'approve') openApproval(row)
+  if (command === 'measurement') openMeasurement(row)
+}
+
+async function printSelectedCartonLabels() {
+  if (!selectedCartonLabelOrders.value.length || printingCartonLabels.value) return
+  printingCartonLabels.value = true
+  try {
+    const blob = await downloadInboundCartonLabelsBatch(selectedCartonLabelOrders.value.map((row) => ({
+      tenantId: String(row.tenantId),
+      inboundId: String(row.inboundId),
+    })))
+    const url = URL.createObjectURL(blob)
+    const anchor = document.createElement('a')
+    anchor.href = url
+    anchor.download = `批量箱唛-${selectedCartonLabelOrders.value.length}单.pdf`
+    document.body.appendChild(anchor)
+    anchor.click()
+    anchor.remove()
+    URL.revokeObjectURL(url)
+    const skipped = selectedOrders.value.length - selectedCartonLabelOrders.value.length
+    if (skipped > 0) ElMessage.warning(`箱唛已开始下载；已跳过 ${skipped} 个尚未生成入库单的订单`)
+    else ElMessage.success('批量箱唛已生成并开始下载')
+  } catch (error) {
+    ElMessage.error(getApiErrorDetails(error, '批量箱唛生成失败，请稍后重试').message)
+  } finally {
+    printingCartonLabels.value = false
+  }
+}
+
+function closeDetail() {
+  releaseCargoImagePreviews()
+  detail.value = null
+  detailError.value = null
+  void router.push({ name: 'unified-orders' })
+}
+
+function returnToMeasurementReviews() {
+  if (window.history.length > 1) router.back()
+  else void router.push({ name: 'inbound-measurement-reviews' })
+}
+
+async function resolveBusinessDetailTarget() {
+  const inboundCode = businessInboundCode.value
+  const serial = ++detailAssociationRequestSerial
+  resolvedDetailTarget.value = null
+  detail.value = null
+  detailError.value = null
+  if (!inboundCode) {
+    detailError.value = { message: '入仓码缺失，无法定位对应订单' }
+    return
+  }
+  detailLoading.value = true
+  try {
+    const association = await getPlatformInboundCodeAssociation(inboundCode)
+    if (serial !== detailAssociationRequestSerial || inboundCode !== businessInboundCode.value) return
+    if (!association.orderId || !association.customerId) {
+      detailError.value = { message: `未找到入仓码 ${inboundCode} 对应的订单，请返回测量审核列表重新打开` }
+      return
+    }
+    resolvedDetailTarget.value = { orderId: String(association.orderId), tenantId: String(association.customerId) }
+  } catch (error) {
+    if (serial !== detailAssociationRequestSerial || inboundCode !== businessInboundCode.value) return
+    detailError.value = getApiErrorDetails(error, `入仓码 ${inboundCode} 的订单关联加载失败，可能无权查看或目标已不存在`)
+  } finally {
+    if (serial === detailAssociationRequestSerial && !resolvedDetailTarget.value) detailLoading.value = false
+  }
+}
+
+function exportFilterParameters() {
+  const activeFilters = appliedFilters.value
+  const range = activeFilters.createdRange
+  return {
+    tenantId: activeFilters.tenantId || undefined,
+    mainStatus: selectedStatus.value || undefined,
+    receivingWarehouseId: activeFilters.receivingWarehouseId || undefined,
+    destinationWarehouseId: activeFilters.destinationWarehouseId || undefined,
+    inboundCode: trimmed(activeFilters.inboundCode),
+    expectedArrivalDate: activeFilters.expectedArrivalDate || undefined,
+    feeReviewStatus: activeFilters.feeReviewStatus || undefined,
+    channelName: trimmed(activeFilters.channelName),
+    containerNo: trimmed(activeFilters.containerNo),
+    cabinetNo: trimmed(activeFilters.cabinetNo),
+    sailingDate: activeFilters.sailingDate || undefined,
+    loaded: optionalBoolean(activeFilters.loaded),
+    fullContainer: optionalBoolean(activeFilters.fullContainer),
+    measurementReviewStatus: activeFilters.measurementReviewStatus || undefined,
+    fbaCode: trimmed(activeFilters.fbaCode),
+    createdFrom: range.length === 2 ? `${range[0]}T00:00:00` : undefined,
+    createdTo: range.length === 2 ? `${range[1]}T23:59:59` : undefined,
+  }
+}
+
+async function exportOrders() {
+  if (exportSubmitting.value) return
+  const selectedOrderNos = selectedOrders.value.map((row) => row.orderNo?.trim() || '')
+  if (selectedOrderNos.some((orderNo) => !orderNo)) {
+    ElMessage.error('所选订单缺少订单号，请刷新列表后重试')
+    return
+  }
+  exportSubmitting.value = true
+  try {
+    const task = await createPlatformExportTask({
+      exportType: 'DOMESTIC_WAREHOUSE_ORDER_LIST',
+      format: 'XLSX',
+      taskName: selectedOrderNos.length ? `国内仓订单-已选${selectedOrderNos.length}票` : '国内仓订单-当前筛选',
+      parameters: selectedOrderNos.length
+        ? { selectedOrderNos }
+        : exportFilterParameters(),
+    })
+    const openDownloadCenter = await showExportTaskCreatedDialog({ taskName: task.taskName, taskNo: task.taskNo })
+    if (openDownloadCenter) await router.push({ name: 'download-center' })
+  } catch (error) {
+    ElMessage.error(getApiErrorMessage(error, '订单导出任务创建失败'))
+  } finally {
+    exportSubmitting.value = false
+  }
+}
+
+async function loadDetail(force = false) {
+  if (!orderId.value) return
+  const tenantId = detailTenantId.value
+  if (!tenantId) {
+    detailError.value = { message: '订单详情缺少客户标识，请从订单列表重新打开' }
+    return
+  }
+  const requestKey = `${tenantId}:${orderId.value}`
+  if (!force && (detailLoadingKey === requestKey || detail.value?.summary.orderId === orderId.value && String(detail.value.summary.tenantId) === tenantId)) return
+  const serial = ++detailRequestSerial
+  detailLoadingKey = requestKey
+  measurementRequestSerial += 1
+  measurementLoading.value = false
+  // 刷新详情时保留现有测量数据，避免请求期间列表被清空。
+  if (!force) measurementDetail.value = null
+  measurementError.value = null
+  measurementLoadedKey.value = ''
+  measurementSectionModes.customer = 'ACTUAL'
+  measurementSectionModes.outer = 'ACTUAL'
+  measurementSectionModes.actual = 'ACTUAL'
+  if (measurementChargeRulesLoadedKey.value !== tenantId) {
+    measurementChargeRules.value = []
+    measurementChargeRulesLoadedKey.value = ''
+  }
+  measurementDimensionConfig.value = null
+  measurementDimensionConfigLoadedKey.value = ''
+  measurementPreviewOpen.value = false
+  holdRequestSerial += 1
+  holdDetail.value = null
+  holdError.value = null
+  holdLoadedKey.value = ''
+  holdLoading.value = false
+  releaseMeasurementPreview()
+  releaseCargoImagePreviews()
+  detailLoading.value = true
+  detailError.value = null
+  try {
+    const response = await getPlatformUnifiedOrder(tenantId, orderId.value)
+    if (serial !== detailRequestSerial || requestKey !== detailRouteKey.value) return
+    detail.value = response
+    await loadCargoImagePreviews(response, serial)
+    if (activeDetailTab.value === 'other') await loadHoldDetail()
+    if (requestedDetailTab.value === 'measurement') {
+      activeDetailTab.value = 'measurement'
+      await loadMeasurementDetails()
+    }
+  } catch (error) {
+    if (serial !== detailRequestSerial || requestKey !== detailRouteKey.value) return
+    detail.value = null
+    detailError.value = getApiErrorDetails(error, '统一订单详情加载失败，请检查 C02 统一详情接口和订单权限')
+  } finally {
+    if (serial === detailRequestSerial) detailLoading.value = false
+    if (serial === detailRequestSerial && detailLoadingKey === requestKey) detailLoadingKey = ''
+  }
+}
+
+watch([page, pageSize], () => { void loadOrders() })
+watch(businessInboundCode, (value) => {
+  detailAssociationRequestSerial += 1
+  resolvedDetailTarget.value = null
+  if (value) void resolveBusinessDetailTarget()
+}, { immediate: true })
+watch(detailRouteKey, (value) => {
+  if (value) {
+    activeDetailTab.value = requestedDetailTab.value
+    detail.value = null
+    detailError.value = null
+    void loadDetail()
+  } else if (!businessInboundCode.value) {
+    detailRequestSerial += 1
+    subsequentFulfillmentRequestSerial += 1
+    detail.value = null
+    detailError.value = null
+    detailLoading.value = false
+  }
+}, { immediate: true })
+watch(measurementPreviewOpen, (open) => {
+  if (!open) releaseMeasurementPreview()
+})
+onMounted(() => {
+  void loadCustomers()
+  void loadWarehouses()
+  if (!isDetailRoute.value) void loadOrders()
+})
+onBeforeUnmount(() => {
+  detailAssociationRequestSerial += 1
+  measurementRequestSerial += 1
+  holdRequestSerial += 1
+  releaseMeasurementPreview()
+  releaseCargoImagePreviews()
+})
+</script>
+
+<template>
+  <AdminPage>
+  <section class="business-page unified-orders-page admin-density">
+    <AppDialog class="admin-density-dialog" v-model="feeConfirmOpen" title="编辑计费数据" confirm-text="确认并发送" :confirm-loading="confirmFeeSending || feeConfirmReferenceLoading" width="min(920px, 94vw)" :teleported="false" @confirm="executeConfirmAndSendFee">
+      <el-alert class="fee-confirm-price-alert" title="价格表单价仅作为参考；本次对客单价可人工修改，客户将一次确认计费量、单价和费用合计。" type="info" :closable="false" show-icon />
+      <el-form label-position="top" class="fee-confirm-form">
+        <el-form-item label="入仓码"><el-input :model-value="detail?.summary.inboundCode || '—'" disabled /></el-form-item>
+        <el-form-item label="渠道"><el-input :model-value="detail?.summary.channelName || detail?.summary.channelCode || '—'" disabled /></el-form-item>
+        <el-form-item label="计费毛重"><div class="fee-confirm-number-wrap"><el-input-number v-model="feeConfirmWeight" :min="0" :precision="3" :controls="false" class="fee-confirm-number" placeholder="请输入计费毛重" /><span class="fee-confirm-unit">kg</span></div></el-form-item>
+        <el-form-item label="计费体积"><div class="fee-confirm-number-wrap"><el-input-number v-model="feeConfirmVolume" :min="0" :precision="6" :controls="false" class="fee-confirm-number" placeholder="请输入计费体积" /><span class="fee-confirm-unit">m³</span></div></el-form-item>
+        <el-form-item label="价格表参考单价"><div class="fee-confirm-number-wrap"><el-input-number :model-value="feeConfirmReference?.unitPrice == null ? undefined : Number(feeConfirmReference.unitPrice)" :precision="4" :controls="false" disabled class="fee-confirm-number" placeholder="正在读取参考单价" /><span class="fee-confirm-unit">{{ feeConfirmPriceUnit }}</span></div></el-form-item>
+        <el-form-item label="本次对客单价"><div class="fee-confirm-number-wrap"><el-input-number v-model="feeConfirmUnitPrice" :min="0" :precision="4" :controls="false" :disabled="feeConfirmReferenceLoading" class="fee-confirm-number" placeholder="请输入对客单价" /><span class="fee-confirm-unit">{{ feeConfirmPriceUnit }}</span></div></el-form-item>
+        <el-form-item v-if="feeConfirmPriceChanged" label="单价调整原因" class="fee-confirm-price-reason"><el-input v-model="feeConfirmPriceReason" type="textarea" :rows="2" maxlength="500" show-word-limit placeholder="请说明本次人工改单价的原因" /></el-form-item>
+      </el-form>
+      <dl v-if="feeConfirmReference" class="fee-confirm-price-summary">
+        <div><dt>参考计费量</dt><dd>{{ formatNumber(Number(feeConfirmReference.chargeableQuantity), feeConfirmReference.roundingScale) }} {{ feeConfirmReference.chargeUnit }}</dd></div>
+        <div><dt>固定附加费</dt><dd>{{ feeConfirmMoney(Number(feeConfirmReference.additionalAmount || 0), feeConfirmReference.currency) }}</dd></div>
+        <div><dt>按当前单价预计合计</dt><dd>{{ feeConfirmEstimatedTotal == null ? '—' : feeConfirmMoney(feeConfirmEstimatedTotal, feeConfirmReference.currency) }}</dd></div>
+      </dl>
+      <h4 class="fee-confirm-reference-title">参考数据</h4>
+      <el-table :data="feeConfirmRows" border size="small">
+        <el-table-column prop="source" label="数据来源" />
+        <el-table-column prop="count" label="件数" />
+        <el-table-column label="总毛重(T.K.GW)" align="right"><template #default="{ row }">{{ row.weight == null ? '—' : formatNumber(row.weight, 2) }}</template></el-table-column>
+        <el-table-column label="总体积(m³)"><template #default="{ row }">{{ row.volume == null ? '—' : formatNumber(row.volume, 4) }}</template></el-table-column>
+        <el-table-column label="总材积重"><template #default="{ row }">{{ row.volume == null ? '—' : formatNumber(Number(row.volume) * 167, 2) }}</template></el-table-column>
+      </el-table>
+    </AppDialog>
+    <template v-if="isDetailRoute">
+      <DetailPageLayout ariaLabel="统一订单详情">
+      <header class="order-detail-header density-detail-header">
+        <div class="order-detail-heading density-detail-heading">
+          <el-button link class="back-button density-back" @click="fromMeasurementReview ? returnToMeasurementReviews() : closeDetail()"><ArrowLeft :size="16" />{{ fromMeasurementReview ? '返回测量审核列表' : '返回列表' }}</el-button>
+          <div class="order-title">
+            <h1 class="density-detail-title">{{ detail?.summary.inboundCode || '入仓码暂缺' }}</h1>
+          </div>
+          <StatusBadge v-if="detail" :status="statusLabel(detail.summary.mainStatus)" />
+        </div>
+        <div v-if="detail && canApprove(detail.summary)" class="detail-header-actions">
+          <el-button v-if="canApprove(detail.summary)" type="success" plain :loading="approvalLoadingId === String(detail.summary.orderId)" @click="openApproval(detail.summary)"><CircleCheck :size="15" />审核通过</el-button>
+        </div>
+      </header>
+
+      <LoadErrorState v-if="detailError" class="detail-load-error" title="订单详情暂时无法加载" :message="detailError.message" :loading="detailLoading" @retry="businessInboundCode ? resolveBusinessDetailTarget() : loadDetail(true)">
+        <template #details><ApiErrorMeta :details="detailError" /></template>
+        <template v-if="fromMeasurementReview" #actions><el-button type="primary" plain :loading="detailLoading" @click="businessInboundCode ? resolveBusinessDetailTarget() : loadDetail(true)">重新加载</el-button><el-button @click="returnToMeasurementReviews">返回测量审核列表</el-button></template>
+      </LoadErrorState>
+
+      <div v-else v-loading="detailLoading" class="order-detail-content">
+        <template v-if="detail">
+          <dl class="detail-overview density-detail-overview" aria-label="订单概览">
+            <div><dt>客户</dt><dd>{{ customerName(detail.summary) }}</dd></div>
+            <div><dt>渠道</dt><dd>{{ detail.summary.channelName || '未配置渠道' }}</dd></div>
+            <div><dt>总箱数</dt><dd>{{ detail.summary.totalPackageCount ?? '—' }} 箱 <small>（{{ detail.order.cargoes.length }} 条货品）</small></dd></div>
+            <div><dt>实测毛重</dt><dd>{{ formatNumber(detail.summary.measurement?.actualGrossWeightKg) }} kg</dd></div>
+            <div><dt>实测体积</dt><dd>{{ formatNumber(detail.summary.measurement?.actualVolumeCbm, 3) }} m³</dd></div>
+            <div><dt>测量审核</dt><dd>{{ measurementStatusLabel(detail.summary.measurement?.reviewStatus) }}</dd></div>
+            <div><dt>最近更新</dt><dd>{{ formatDate(detail.summary.updatedAt) }}</dd></div>
+          </dl>
+
+          <div class="detail-tabs density-tabs" role="tablist" aria-label="订单详情模块">
+             <button v-for="tab in detailTabs" :id="`order-detail-tab-${tab.key}`" :key="tab.key" type="button" role="tab" :class="{ active: activeDetailTab === tab.key }" :aria-selected="activeDetailTab === tab.key" :aria-controls="`order-detail-panel-${tab.key}`" :tabindex="activeDetailTab === tab.key ? 0 : -1" @click="selectDetailTab(tab.key)"><span class="density-tab-icon" aria-hidden="true">{{ tab.icon }}</span><span>{{ tab.label }}</span></button>
+          </div>
+
+          <section :id="`order-detail-panel-${activeDetailTab}`" class="detail-panel" role="tabpanel" :aria-labelledby="`order-detail-tab-${activeDetailTab}`" tabindex="0">
+            <template v-if="activeDetailTab === 'basic'">
+              <dl class="order-info-grid density-fields">
+                <div><dt>公司</dt><dd>{{ customerName(detail.summary) }}</dd></div>
+                <div><dt>运输方式</dt><dd>{{ firstLegTransportModeLabel(detail.order.order?.transportMode) }}</dd></div>
+                <div><dt>当前状态</dt><dd><StatusBadge :status="statusLabel(detail.summary.mainStatus)" /></dd></div>
+                <div><dt>内部订单状态</dt><dd>{{ orderStatusLabel(detail.summary.internalOrderStatus || detail.summary.mainStatus) }}</dd></div>
+                <div><dt>平台收货仓</dt><dd>{{ detail.summary.receivingWarehouseName || '—' }}</dd></div>
+                <div class="wide"><dt>收货仓地址</dt><dd>{{ detail.order.order?.receivingWarehouseAddress || '—' }}</dd></div>
+                <div><dt>目的仓</dt><dd>{{ detail.summary.destinationWarehouseName || '—' }}</dd></div>
+                <div><dt>目的国家</dt><dd>{{ detail.order.order?.destinationCountryCode || '—' }}</dd></div>
+                <div class="wide"><dt>目的仓地址</dt><dd>{{ detail.summary.destinationAddress || '—' }}</dd></div>
+                <div><dt>目的仓邮编</dt><dd>{{ detail.summary.destinationPostalCode || '—' }}</dd></div>
+                <div><dt>目的仓联系人</dt><dd>{{ detail.summary.destinationContact || '—' }}</dd></div>
+                <div><dt>目的仓联系人电话</dt><dd>{{ detail.summary.destinationContactPhone || '—' }}</dd></div>
+                <div><dt>渠道</dt><dd>{{ detail.summary.channelName || '—' }} <el-tag v-if="detail.summary.channelChanged" size="small" type="warning">曾变更渠道</el-tag></dd></div>
+                <div><dt>业务类型</dt><dd>{{ firstLegBusinessTypeLabel(detail.summary.businessType) }}</dd></div>
+                <div><dt>贸易条款</dt><dd>{{ firstLegTradeTermLabel(detail.order.order?.tradeTerm) }}</dd></div>
+                <div><dt>买单 / 退税</dt><dd>{{ firstLegTaxModeLabel(detail.order.order?.taxMode) }}</dd></div>
+                <div><dt>费用审核状态</dt><dd>{{ feeReviewLabel(detail.summary.feeReviewStatus) }}</dd></div>
+                <div><dt>提货方式</dt><dd>{{ firstLegPickupMethodLabel(detail.order.order?.pickupMethod) }}</dd></div>
+                <div><dt>提货时间</dt><dd>{{ formatDate(detail.summary.pickupAt) }}</dd></div>
+                <div><dt>到仓时间</dt><dd>{{ detail.order.order?.receivingTime || '—' }}</dd></div>
+                <div><dt>货物到仓时间</dt><dd>{{ formatDate(detail.summary.expectedArrivalAt || detail.summary.inboundCompletedAt) }}</dd></div>
+                <div><dt>预计出运</dt><dd>{{ formatDate(detail.summary.expectedShipDate) }}</dd></div>
+                <div><dt>预计到达时间</dt><dd>{{ formatDate(detail.summary.expectedArrivalAt) }}</dd></div>
+                <div><dt>真实集装箱号</dt><dd>{{ detail.summary.transport?.containerNo || '—' }}</dd></div>
+                <div><dt>内部柜次号</dt><dd>{{ detail.summary.transport?.cabinetNo || '—' }}</dd></div>
+                <div><dt>船名 / 航次</dt><dd>{{ detail.summary.transport?.vesselName || '—' }} / {{ detail.summary.transport?.voyageNo || '—' }}</dd></div>
+                <div><dt>开船时间</dt><dd>{{ formatEffectiveTransportTime(detail.summary.transport?.effectiveSailingAt, detail.summary.transport?.effectiveSailingAtEstimated) }}</dd></div>
+                <div><dt>到港时间</dt><dd>{{ formatEffectiveTransportTime(detail.summary.transport?.effectivePortArrivalAt, detail.summary.transport?.effectivePortArrivalAtEstimated) }}</dd></div>
+                <div><dt>配载状态</dt><dd>{{ unifiedOrderLoadingStatusLabel(detail.summary.transport?.loadingStatus) }}</dd></div>
+                <div><dt>目的仓类型</dt><dd>{{ firstLegDestinationTypeLabel(detail.order.order?.destinationType) }}</dd></div>
+                <div><dt>是否整柜</dt><dd>{{ firstLegContainerModeLabel(detail.order.order?.containerMode) }}</dd></div>
+                <div><dt>商检验</dt><dd>{{ displayBoolean(detail.order.order?.customsInspection) }}</dd></div>
+                <div><dt>总箱数</dt><dd>{{ detail.summary.totalPackageCount ?? '—' }} 箱</dd></div>
+                <div><dt>客户申报毛重</dt><dd>{{ formatNumber(cargoTotal(detail.order.cargoes, 'grossWeightKg')) }} kg</dd></div>
+                <div><dt>客户申报净重</dt><dd>{{ formatNumber(cargoTotal(detail.order.cargoes, 'netWeightKg')) }} kg</dd></div>
+                <div><dt>客户申报总体积</dt><dd>{{ formatNumber(cargoTotal(detail.order.cargoes, 'volumeCbm'), 3) }} m³</dd></div>
+                <div><dt>计费毛重</dt><dd>{{ formatNumber(detail.summary.measurement?.chargeableWeightKg) }} kg</dd></div>
+                <div><dt>计费体积</dt><dd>{{ formatNumber(detail.summary.chargeableVolumeCbm, 3) }} m³</dd></div>
+                <div><dt>总材积重</dt><dd>{{ formatNumber(detail.summary.volumetricWeightKg) }} kg</dd></div>
+                <div><dt>总材积量</dt><dd>{{ formatNumber(detail.summary.volumetricWeightKg) }}</dd></div>
+                <div><dt>库位位置</dt><dd>{{ detail.summary.locationCodes || '—' }}</dd></div>
+                <div><dt>创建时间</dt><dd>{{ formatDate(detail.summary.createdAt) }}</dd></div>
+                <div><dt>入库完成时间</dt><dd>{{ formatDate(detail.summary.inboundCompletedAt) }}</dd></div>
+                <div><dt>测量完成时间</dt><dd>{{ formatDate(detail.summary.measurementCompletedAt || detail.summary.measurement?.completedAt) }}</dd></div>
+                <div class="wide"><dt>提货联系人</dt><dd>{{ partyValue(detail.order.parties, 'SENDER', 'contactName') }} · {{ detail.summary.pickupContactPhone || partyValue(detail.order.parties, 'SENDER', 'phone') }} · {{ detail.summary.pickupContactEmail || partyValue(detail.order.parties, 'SENDER', 'email') }}</dd></div>
+                <div class="wide"><dt>提货地址</dt><dd>{{ detail.summary.pickupAddress || partyAddress(detail.order.parties, 'SENDER') }} · {{ detail.summary.pickupPostalCode || partyValue(detail.order.parties, 'SENDER', 'postalCode') }}</dd></div>
+                <div class="wide"><dt>目的地联系人</dt><dd>{{ partyValue(detail.order.parties, 'RECEIVER', 'contactName') }} · {{ partyValue(detail.order.parties, 'RECEIVER', 'phone') }} · {{ partyValue(detail.order.parties, 'RECEIVER', 'email') }}</dd></div>
+                <div><dt>目的仓联系人邮箱</dt><dd>{{ partyValue(detail.order.parties, 'RECEIVER', 'email') }}</dd></div>
+                <div class="wide"><dt>目的地地址</dt><dd>{{ partyAddress(detail.order.parties, 'RECEIVER') }} · {{ partyValue(detail.order.parties, 'RECEIVER', 'postalCode') }}</dd></div>
+                <div class="wide"><dt>备注</dt><dd>{{ detail.order.order?.customerRemark || '—' }}</dd></div>
+                <div class="wide"><dt>关联文件</dt><dd>{{ detail.summary.associatedFiles?.join('、') || '—' }}</dd></div>
+                <div class="wide"><dt>唛头文件</dt><dd>{{ detail.summary.markFiles?.join('、') || '—' }}</dd></div>
+                <div class="wide"><dt>PC 端下单文件</dt><dd>{{ detail.summary.pcOrderFiles?.join('、') || '—' }}</dd></div>
+                <div><dt>快递公司</dt><dd>{{ detail.summary.expressCompany || detail.order.order?.expressCompany || '—' }}</dd></div>
+                <div><dt>快递单号</dt><dd>{{ detail.summary.expressTrackingNo || detail.order.order?.expressTrackingNo || '—' }}</dd></div>
+                <div class="wide"><dt>客服内部备注</dt><dd>{{ detail.summary.internalRemark || detail.summary.latestInternalNote || '—' }}</dd></div>
+                <div><dt>创建人</dt><dd>{{ detail.summary.createdBy || '—' }}</dd></div>
+                <div><dt>下一步</dt><dd>{{ canApprove(detail.summary) ? '审核订单' : nextActionBoundary(detail.summary) || '—' }}</dd></div>
+              </dl>
+            </template>
+
+            <template v-else-if="activeDetailTab === 'cargo'">
+              <div class="panel-title"><p>共 {{ detail.order.cargoes.length }} 条货品</p><el-button v-if="canEditDeclaration" type="primary" size="small" @click="declarationEditorOpen = true">编辑客户申报资料</el-button></div>
+              <div class="detail-table-wrap">
+                <el-table :data="detail.order.cargoes" border stripe empty-text="暂无货品信息">
+                  <el-table-column prop="itemNo" label="#" width="64" />
+                  <el-table-column label="报关HS_CODE" min-width="130"><template #default="{ row }">{{ cargoValue(row as Record<string, unknown>, 'hsCode') }}</template></el-table-column>
+                  <el-table-column label="货品图片" width="110"><template #default="{ row }"><el-image v-if="cargoImage(row as Record<string, unknown>)" :src="cargoImage(row as Record<string, unknown>)" :preview-src-list="[cargoImage(row as Record<string, unknown>)]" preview-teleported fit="contain" class="cargo-image" /><span v-else>—</span></template></el-table-column>
+                  <el-table-column label="SKU NO." min-width="150"><template #default="{ row }">{{ cargoValue(row as Record<string, unknown>, 'skuNo') }}</template></el-table-column>
+                  <el-table-column label="中文品名" min-width="170"><template #default="{ row }">{{ cargoValue(row as Record<string, unknown>, 'cargoName') }}</template></el-table-column>
+                  <el-table-column label="英文品名" min-width="170"><template #default="{ row }">{{ cargoValue(row as Record<string, unknown>, 'cargoNameEn') }}</template></el-table-column>
+                  <el-table-column label="清关HS_CODE" min-width="130"><template #default="{ row }">{{ cargoValue(row as Record<string, unknown>, 'customsHsCode') }}</template></el-table-column>
+                  <el-table-column label="箱规长(cm)" align="right" min-width="110"><template #default="{ row }">{{ cargoValue(row as Record<string, unknown>, 'lengthCm') }}</template></el-table-column>
+                  <el-table-column label="箱规宽(cm)" align="right" min-width="110"><template #default="{ row }">{{ cargoValue(row as Record<string, unknown>, 'widthCm') }}</template></el-table-column>
+                  <el-table-column label="箱规高(cm)" align="right" min-width="110"><template #default="{ row }">{{ cargoValue(row as Record<string, unknown>, 'heightCm') }}</template></el-table-column>
+                  <el-table-column label="箱规周长(cm)" align="right" min-width="120"><template #default="{ row }">{{ cargoValue(row as Record<string, unknown>, 'circumferenceCm') }}</template></el-table-column>
+                  <el-table-column label="每箱产品数量" align="right" min-width="130"><template #default="{ row }">{{ cargoValue(row as Record<string, unknown>, 'unitsPerPackage') }}</template></el-table-column>
+                  <el-table-column label="箱数" align="right" width="90"><template #default="{ row }">{{ cargoValue(row as Record<string, unknown>, 'packageCount') }}</template></el-table-column>
+                  <el-table-column label="总毛重(T.KGW)" align="right" min-width="140"><template #default="{ row }">{{ cargoValue(row as Record<string, unknown>, 'grossWeightKg') }}</template></el-table-column>
+                  <el-table-column label="总净重(T.KNW)" align="right" min-width="140"><template #default="{ row }">{{ cargoValue(row as Record<string, unknown>, 'netWeightKg') }}</template></el-table-column>
+                </el-table>
+              </div>
+            </template>
+
+            <template v-else-if="activeDetailTab === 'fees'">
+              <el-empty v-if="!normalizedInboundId" description="订单尚未生成入库单，暂无入仓费用" :image-size="64" />
+              <template v-else>
+              <dl class="fee-overview" aria-label="费用汇总">
+                <div><dt>对客费用合计</dt><dd>{{ feeMoney(customerFeeTotal) }}</dd><small>已发布头程费用 + 已审核其他应收</small></div>
+                <div><dt>已审核其他应付</dt><dd>{{ feeMoney(otherFeeSummary.approvedPayable) }}</dd><small>单列展示，不计入对客费用</small></div>
+              </dl>
+              <InboundFeePanel
+                :key="`fee-${normalizedInboundId}-${feePanelRevision}`"
+                :customer-id="String(detail.summary.tenantId)"
+                :inbound-id="normalizedInboundId"
+                compact
+                display-only
+                @loaded="automaticFee = $event"
+              />
+              <h3 class="fee-section-title fee-section-title--secondary">其他费用明细</h3>
+              <InboundFeeDetailManager
+                :account-id="String(detail.summary.tenantId)"
+                :inbound-id="normalizedInboundId"
+                :destination-type="detail.summary.destinationType"
+                @summary="otherFeeSummary = $event"
+                @changed="loadDetail(true)"
+              />
+              </template>
+            </template>
+
+            <template v-else-if="activeDetailTab === 'history'">
+              <div class="panel-title"><p>共 {{ detail.timeline.length }} 条记录</p></div>
+              <el-table :data="detail.timeline" class="history-table" border stripe empty-text="暂无状态历史" aria-label="状态历史">
+                <el-table-column label="时间" width="172"><template #default="{ row }">{{ formatDate(row.occurredAt) }}</template></el-table-column>
+                <el-table-column label="事件" min-width="180"><template #default="{ row }">{{ historyActionLabel(row.action || row.eventType) }}</template></el-table-column>
+                <el-table-column label="状态" width="166"><template #default="{ row }"><StatusBadge :status="statusLabel(row.mainStatus)" /></template></el-table-column>
+                <el-table-column label="操作人" min-width="160"><template #default="{ row }">{{ row.operatorName || '系统' }}</template></el-table-column>
+                <el-table-column label="备注" min-width="300"><template #default="{ row }">{{ row.remark || '—' }}</template></el-table-column>
+              </el-table>
+            </template>
+
+            <template v-else-if="activeDetailTab === 'fulfillment'">
+              <div class="panel-title"><p>根单、已完成分片与当前余量</p></div>
+              <OrderFulfillmentTreePanel :tenant-id="String(detail.summary.tenantId)" :order-id="String(detail.summary.orderId)" :inbound-code="detail.summary.inboundCode" />
+              <section v-loading="subsequentFulfillmentLoading" class="subsequent-fulfillment" aria-label="后续履约数据">
+                <h3>后续履约数据</h3>
+                <LoadErrorState v-if="loadingAssociationError" title="装柜与PDA履约数据加载失败" :message="loadingAssociationError.message" @retry="loadSubsequentFulfillment"><template #details><ApiErrorMeta :details="loadingAssociationError" /></template></LoadErrorState>
+                <LoadErrorState v-if="overseasRelationshipError" title="尾程与库存履约数据加载失败" :message="overseasRelationshipError.message" @retry="loadSubsequentFulfillment"><template #details><ApiErrorMeta :details="overseasRelationshipError" /></template></LoadErrorState>
+                <dl v-if="hasLoadingAssociation" class="fulfillment-facts">
+                  <div><dt>装柜计划</dt><dd>{{ loadingAssociation?.loadingPlanNo || '—' }}</dd></div>
+                  <div><dt>柜号</dt><dd>{{ loadingAssociation?.containerNo || loadingAssociation?.cabinetNo || '—' }}</dd></div>
+                  <div><dt>装柜状态</dt><dd>{{ loadingAssociation?.loadingStatus || '—' }}</dd></div>
+                  <div><dt>PDA状态</dt><dd>{{ loadingAssociation?.pdaTaskStatus || '—' }}</dd></div>
+                </dl>
+                <dl v-if="hasOverseasRelationship" class="fulfillment-facts">
+                  <div><dt>海外仓</dt><dd>{{ overseasRelationship?.overseasWarehouse?.warehouseName || '尚未分配海外仓' }}</dd></div>
+                  <div><dt>海外收货状态</dt><dd>{{ overseasRelationship?.overseasReceivingStatus || '—' }}</dd></div>
+                  <div class="wide"><dt>尾程订单</dt><dd>{{ overseasRelationship?.taillegOrders.map((item) => item.orderNo).join('、') || '—' }}</dd></div>
+                  <div class="wide"><dt>入库计划</dt><dd>{{ overseasRelationship?.inboundPlans.map((item) => item.planNo).join('、') || '—' }}</dd></div>
+                  <div class="wide"><dt>托盘码</dt><dd>{{ overseasRelationship?.palletCodes.join('、') || '—' }}</dd></div>
+                  <div><dt>库存SKU</dt><dd>{{ overseasRelationship?.inventory.length || 0 }} 个</dd></div>
+                </dl>
+                <p v-if="!subsequentFulfillmentLoading && !loadingAssociationError && !overseasRelationshipError && !hasSubsequentFulfillment" class="fulfillment-empty">暂无后续履约数据</p>
+              </section>
+            </template>
+
+            <template v-else-if="activeDetailTab === 'dropship-print'">
+              <el-empty v-if="!normalizedInboundId" description="订单尚未生成入库单，暂无托盘码可打印" :image-size="64" />
+              <el-alert v-else-if="!can('platform:firstleg:inbound:list')" title="当前账号缺少入库单查看权限，无法打印托盘码" type="warning" :closable="false" show-icon />
+              <DropshipPalletPrintPanel
+                v-else
+                :customer-id="String(detail.summary.tenantId)"
+                :inbound-id="normalizedInboundId"
+                :inbound-code="detail.summary.inboundCode"
+              />
+            </template>
+
+             <template v-else-if="activeDetailTab === 'measurement'">
+               <div class="panel-title">
+                 <p>{{ detail.summary.measurement?.completedAt ? `测量完成于 ${formatDate(detail.summary.measurement.completedAt)}` : '尚未完成测量' }}</p>
+                 <div class="measurement-title-actions">
+                   <el-button
+                     v-if="can('firstleg:inbound:confirm-send-fee') && automaticFee?.feeStatus !== 'SENT' && !['LOADED', 'DELIVERED'].includes(detail.summary.mainStatus)"
+                     type="primary"
+                     :loading="confirmFeeSending"
+                     title="确认并发送费用"
+                     data-testid="confirm-send-fee-button"
+                     @click="openFeeConfirmDialog"
+                   ><Send :size="15" />确认计费重发送</el-button>
+                 </div>
+               </div>
+               <el-alert v-if="!can('platform:firstleg:inbound:measure:view')" title="当前账号缺少测量查看权限" type="warning" :closable="false" show-icon />
+               <LoadErrorState v-else-if="measurementError" title="测量数据暂时无法加载" :message="measurementError.message" :loading="measurementLoading" @retry="loadMeasurementDetails">
+                 <template #details><ApiErrorMeta :details="measurementError" /></template>
+                 <template v-if="fromMeasurementReview" #actions><el-button type="primary" plain :loading="measurementLoading" @click="loadMeasurementDetails">重新加载</el-button><el-button @click="returnToMeasurementReviews">返回测量审核列表</el-button></template>
+               </LoadErrorState>
+               <template v-else>
+               <section class="measurement-section">
+                <div class="measurement-section-title"><button type="button" class="measurement-section-toggle" :aria-expanded="!measurementCollapsed.customer" @click="toggleMeasurementSection('customer')"><h3>一、客户下单数据</h3><span v-if="measurementCollapsed.customer" class="measurement-section-summary"><span>总件数：{{ measurementTotals(customerMeasurementRows).count ?? '—' }}</span><span>总毛重：{{ formatNumber(measurementTotals(customerMeasurementRows).gross) }}</span><span>总体积：{{ formatNumber(measurementTotals(customerMeasurementRows).volume, 6) }}</span><span>总材积重：{{ formatNumber(measurementTotals(customerMeasurementRows).volumetric) }}</span><span>重量体积：{{ formatNumber(measurementTotals(customerMeasurementRows).weightVolume, 6) }}</span></span><ChevronUp v-if="!measurementCollapsed.customer" :size="18" /><ChevronDown v-else :size="18" /></button><el-select class="measurement-section-mode" :model-value="measurementSectionModes.customer" aria-label="客户下单数据计算方式" @change="updateMeasurementSectionMode('customer', $event)"><el-option label="实测原尺寸（不调整）" value="ACTUAL" /><el-option label="箱规尺寸" value="ADD" /><el-option label="箱规系数" value="MULTIPLY" :disabled="multiplyModeDisabled" /></el-select></div>
+                <div v-if="!measurementCollapsed.customer">
+                  <div class="detail-table-wrap"><el-table :data="customerMeasurementRows" border stripe empty-text="暂无客户下单数据"><el-table-column v-for="column in customerMeasurementColumns" :key="column.key" :label="column.label" :prop="column.key" min-width="120"><template #default="{ row }"><LineClampText v-if="column.key === 'remark'" :content="measurementValue(row as Record<string, unknown>, column.key)" /><template v-else>{{ measurementValue(row as Record<string, unknown>, column.key) }}</template></template></el-table-column></el-table></div>
+                  <div class="measurement-total"><strong>合计</strong><span>箱数：{{ measurementTotals(customerMeasurementRows).count ?? '—' }}</span><span>总毛重：{{ formatNumber(measurementTotals(customerMeasurementRows).gross) }}</span><span>总体积：{{ formatNumber(measurementTotals(customerMeasurementRows).volume, 6) }}</span><span>总材积重：{{ formatNumber(measurementTotals(customerMeasurementRows).volumetric) }}</span><span>重量体积：{{ formatNumber(measurementTotals(customerMeasurementRows).weightVolume, 6) }}</span></div>
+                </div>
+              </section>
+               <section class="measurement-section">
+                <div class="measurement-section-title"><button type="button" class="measurement-section-toggle" :aria-expanded="!measurementCollapsed.outer" @click="toggleMeasurementSection('outer')"><h3>二、外箱规数据</h3><span v-if="measurementCollapsed.outer" class="measurement-section-summary"><span>总件数：{{ measurementTotals(outerMeasurementRows).count ?? '—' }}</span><span>总毛重：{{ formatNumber(measurementTotals(outerMeasurementRows).gross) }}</span><span>总体积：{{ formatNumber(measurementTotals(outerMeasurementRows).volume, 6) }}</span><span>总材积重：{{ formatNumber(measurementTotals(outerMeasurementRows).volumetric) }}</span><span>重量体积：{{ formatNumber(measurementTotals(outerMeasurementRows).weightVolume, 6) }}</span></span><ChevronUp v-if="!measurementCollapsed.outer" :size="18" /><ChevronDown v-else :size="18" /></button></div>
+                <div v-if="!measurementCollapsed.outer">
+                  <div v-loading="measurementLoading" class="detail-table-wrap"><el-table :data="outerMeasurementRows" border stripe empty-text="暂无外箱规数据"><el-table-column label="#" prop="itemNo" min-width="70" /><el-table-column v-for="column in outerColumns.filter((item) => item.key !== 'itemNo')" :key="column.key" :label="column.label" :prop="column.key" min-width="150"><template #default="{ row }"><LineClampText v-if="column.key === 'remark'" :content="measurementValue(row as Record<string, unknown>, column.key)" /><template v-else>{{ measurementValue(row as Record<string, unknown>, column.key) }}</template></template></el-table-column></el-table></div>
+                  <div class="measurement-total"><strong>合计</strong><span>箱数：{{ measurementTotals(outerMeasurementRows).count ?? '—' }}</span><span>总毛重：{{ formatNumber(measurementTotals(outerMeasurementRows).gross) }}</span><span>总体积：{{ formatNumber(measurementTotals(outerMeasurementRows).volume, 6) }}</span><span>总材积重：{{ formatNumber(measurementTotals(outerMeasurementRows).volumetric) }}</span><span>重量体积：{{ formatNumber(measurementTotals(outerMeasurementRows).weightVolume, 6) }}</span></div>
+                </div>
+              </section>
+              <div class="measurement-rule-selector">
+                <span class="measurement-rule-selector__label">箱规计算规则选择</span>
+                <el-tooltip :content="measurementStrategyLockedHint" :disabled="measurementStrategyEditable"><span><el-select class="measurement-rule-selector__control" :model-value="measurementSectionModes.outer" aria-label="外箱规数据计算方式" :loading="Boolean(measurementStrategySavingId)" :disabled="Boolean(measurementStrategySavingId) || !measurementStrategyEditable" @change="selectAndSaveOuterMeasurementMode($event)">
+                  <el-option label="实测原尺寸（不调整）" value="ACTUAL" />
+                  <el-option label="箱规尺寸" value="ADD" />
+                  <el-option label="箱规系数" value="MULTIPLY" :disabled="multiplyModeDisabled" />
+                </el-select></span></el-tooltip>
+                <span class="measurement-rule-selector__hint">{{ measurementStrategyEditable ? '规则参数来源：客户管理' : measurementStrategyLockedHint }}</span>
+              </div>
+              <section class="measurement-section">
+                <div class="measurement-section-title"><button type="button" class="measurement-section-toggle" :aria-expanded="!measurementCollapsed.actual" @click="toggleMeasurementSection('actual')"><h3>三、实际测量数据</h3><span v-if="measurementCollapsed.actual" class="measurement-section-summary"><span>总件数：{{ measurementTotals(actualMeasurementRows).count ?? '—' }}</span><span>总毛重：{{ formatNumber(measurementTotals(actualMeasurementRows).gross) }}</span><span>总体积：{{ formatNumber(measurementTotals(actualMeasurementRows).volume, 6) }}</span><span>总材积重：{{ formatNumber(measurementTotals(actualMeasurementRows).volumetric) }}</span><span>重量体积：{{ formatNumber(measurementTotals(actualMeasurementRows).weightVolume, 6) }}</span></span><ChevronUp v-if="!measurementCollapsed.actual" :size="18" /><ChevronDown v-else :size="18" /></button><el-select class="measurement-section-mode" :model-value="measurementSectionModes.actual" aria-label="实际测量数据计算方式" @change="updateMeasurementSectionMode('actual', $event)"><el-option label="实测原尺寸（不调整）" value="ACTUAL" /><el-option label="箱规尺寸" value="ADD" /><el-option label="箱规系数" value="MULTIPLY" :disabled="multiplyModeDisabled" /></el-select></div>
+                <div v-if="!measurementCollapsed.actual">
+                  <div v-loading="measurementLoading" class="detail-table-wrap">
+                    <el-table :data="actualMeasurementRows" row-key="id" border stripe empty-text="暂无实际测量数据">
+                      <el-table-column v-if="measurementStrategyEditable" label="操作" width="110" fixed="left">
+                        <template #default="{ row }"><el-button type="primary" plain size="small" :loading="measurementOuterSavingId === String(row.id)" :disabled="Boolean(measurementOuterSavingId)" @click="saveWarehouseOuterDimensions(row as Record<string, unknown>)">保存外箱</el-button></template>
+                      </el-table-column>
+                      <el-table-column label="箱号" prop="boxCode" min-width="190" fixed="left" show-overflow-tooltip>
+                        <template #default="{ row }"><strong class="measurement-box-code">{{ row.boxCode || '—' }}</strong></template>
+                      </el-table-column>
+                      <el-table-column label="#" prop="itemNo" min-width="70" fixed="left" />
+                      <el-table-column label="仓库修改外箱（长）" width="190" align="center">
+                        <template #default="{ row }"><el-input-number v-if="measurementStrategyEditable" v-model="row.outerLengthCm" class="measurement-outer-dimension-input" aria-label="仓库修改外箱长" :min="0.001" :precision="3" :controls="false" placeholder="不修改" /><template v-else>{{ formatNumber(row.outerLengthCm) }}</template></template>
+                      </el-table-column>
+                      <el-table-column label="仓库修改外箱（宽）" width="190" align="center">
+                        <template #default="{ row }"><el-input-number v-if="measurementStrategyEditable" v-model="row.outerWidthCm" class="measurement-outer-dimension-input" aria-label="仓库修改外箱宽" :min="0.001" :precision="3" :controls="false" placeholder="不修改" /><template v-else>{{ formatNumber(row.outerWidthCm) }}</template></template>
+                      </el-table-column>
+                      <el-table-column label="仓库修改外箱（高）" width="190" align="center">
+                        <template #default="{ row }"><el-input-number v-if="measurementStrategyEditable" v-model="row.outerHeightCm" class="measurement-outer-dimension-input" aria-label="仓库修改外箱高" :min="0.001" :precision="3" :controls="false" placeholder="不修改" /><template v-else>{{ formatNumber(row.outerHeightCm) }}</template></template>
+                      </el-table-column>
+
+                      <el-table-column v-for="column in actualMeasuredColumns" :key="column.key" :label="column.label" :prop="column.key" min-width="120">
+                        <template #default="{ row }"><LineClampText v-if="column.key === 'remark'" :content="measurementValue(row as Record<string, unknown>, column.key)" /><template v-else>{{ measurementValue(row as Record<string, unknown>, column.key) }}</template></template>
+                      </el-table-column>
+                      <el-table-column label="尺寸图片" min-width="148">
+                        <template #default="{ row }">
+                          <MeasurementEvidenceThumbnail
+                            :customer-id="String(detail.summary.tenantId)"
+                            :inbound-id="String(detail.summary.inboundId)"
+                            :file-id="row.intelligentImageFileId"
+                            :alt="`箱号 ${row.boxCode || row.itemNo || '箱规编码待补充'} 的尺寸图片`"
+                            empty-text="未绑定尺寸图片"
+                            @open="openMeasurementEvidence(row.intelligentImageFileId, `尺寸图片 · ${row.boxCode || row.itemNo || '箱规编码待补充'}`)"
+                          />
+                        </template>
+                      </el-table-column>
+                    </el-table>
+                  </div>
+                  <div class="measurement-total"><strong>合计</strong><span>箱数：{{ measurementTotals(actualMeasurementRows).count ?? '—' }}</span><span>总毛重：{{ formatNumber(measurementTotals(actualMeasurementRows).gross) }}</span><span>总体积：{{ formatNumber(measurementTotals(actualMeasurementRows).volume, 6) }}</span><span>总材积重：{{ formatNumber(measurementTotals(actualMeasurementRows).volumetric) }}</span><span>重量体积：{{ formatNumber(measurementTotals(actualMeasurementRows).weightVolume, 6) }}</span></div>
+                  <section class="weight-evidence" aria-label="称重图片与服务端确认重量">
+                    <div class="weight-evidence__heading">
+                      <div><h4>称重图片与确认重量</h4><p>称重图片独立展示；重量值直接采用服务端确认结果。</p></div>
+                      <dl><dt>实际总毛重</dt><dd>{{ formatNumber(measurementDetail?.actualGrossWeightKg) }} kg</dd></dl>
+                    </div>
+                    <div v-if="measurementDetail?.weightResults.length" class="weight-evidence-grid">
+                      <article v-for="weightResult in measurementDetail.weightResults" :key="weightResult.id" class="weight-evidence-card">
+                        <MeasurementEvidenceThumbnail
+                          :customer-id="String(detail.summary.tenantId)"
+                          :inbound-id="String(detail.summary.inboundId)"
+                          :file-id="weightResult.fileId"
+                          :alt="`称重结果 ${weightResult.id} 的称重图片`"
+                          empty-text="未绑定称重图片"
+                          @open="openMeasurementEvidence(weightResult.fileId, `称重图片 · ${weightResult.palletType || '未记录类型'}`)"
+                        />
+                        <dl>
+                          <div><dt>托盘类型</dt><dd>{{ weightResult.palletType || '未记录类型' }}</dd></div>
+                          <div><dt>服务端确认毛重</dt><dd>{{ formatNumber(weightResult.grossWeightKg) }} kg</dd></div>
+                          <div><dt>托盘皮重</dt><dd>{{ formatNumber(weightResult.palletTareWeightKg) }} kg</dd></div>
+                          <div><dt>货物重量</dt><dd>{{ formatNumber(weightResult.netWeightKg) }} kg</dd></div>
+                        </dl>
+                      </article>
+                    </div>
+                    <p v-else class="compact-empty">暂无称重图片与确认结果</p>
+                  </section>
+                </div>
+               </section>
+               </template>
+             </template>
+
+            <template v-else>
+              <section class="hold-section" aria-label="订单扣货控制">
+                <div class="panel-title"><div><h2>扣货控制</h2><p>扣货状态独立于快递、箱子计费和内部备注维护</p></div><ShieldAlert :size="19" /></div>
+                <el-empty v-if="!normalizedInboundId" description="订单尚未生成入库单，扣货状态仅可查看" :image-size="56" />
+                <template v-else>
+                  <div class="hold-summary">
+                    <dl><div><dt>当前状态</dt><dd><el-tag :type="currentHoldFlag === true ? 'danger' : currentHoldFlag === false ? 'success' : 'info'" effect="plain">{{ currentHoldFlag === true ? '已扣货' : currentHoldFlag === false ? '未扣货' : '状态未知' }}</el-tag></dd></div><div><dt>当前原因</dt><dd>{{ currentHoldReason || '—' }}</dd></div></dl>
+                    <div class="hold-actions"><el-button v-if="canHoldInbound" type="danger" :loading="holdSaving" @click="openHoldDialog('HOLD')"><ShieldAlert :size="15" />扣货</el-button><el-button v-if="canReleaseInbound" type="primary" plain :loading="holdSaving" @click="openHoldDialog('RELEASE')"><Undo2 :size="15" />解除扣货</el-button></div>
+                  </div>
+                  <el-alert v-if="!can('platform:firstleg:inbound:list')" title="当前账号只能查看订单返回的扣货状态，无法读取扣货历史" type="info" :closable="false" show-icon />
+                  <LoadErrorState v-else-if="holdError" title="扣货状态与历史加载失败" :message="holdError.message" :loading="holdLoading" @retry="loadHoldDetail(true)"><template #details><ApiErrorMeta :details="holdError" /></template></LoadErrorState>
+                  <template v-else>
+                    <p v-if="holdDetail?.actionBlockReason && !canHoldInbound && !canReleaseInbound" class="hold-block-reason">{{ holdDetail.actionBlockReason }}</p>
+                    <h3 class="hold-history-title">扣货历史</h3>
+                    <div v-loading="holdLoading" class="hold-history-table"><el-table :data="holdDetail?.history || []" border stripe empty-text="暂无扣货历史"><el-table-column label="操作" width="110"><template #default="{ row }"><el-tag :type="row.action === 'HOLD' ? 'danger' : 'success'" effect="plain">{{ row.action === 'HOLD' ? '扣货' : '解除扣货' }}</el-tag></template></el-table-column><el-table-column prop="reason" label="原因" min-width="260" /><el-table-column label="凭证" width="150"><template #default="{ row }"><el-button v-if="row.evidenceFileId" link type="primary" :loading="holdDownloadingFileId === row.evidenceFileId" @click="downloadHoldEvidence(row.evidenceFileId)"><Download :size="14" />下载凭证</el-button><span v-else>—</span></template></el-table-column><el-table-column label="操作人" width="150"><template #default="{ row }">{{ row.operatorName || '系统' }}</template></el-table-column><el-table-column label="操作时间" width="180"><template #default="{ row }">{{ formatDate(row.operatedAt) }}</template></el-table-column></el-table></div>
+                  </template>
+                </template>
+              </section>
+              <section class="other-notes-section" aria-label="内部备注">
+                <div class="panel-title"><div><h2>内部备注</h2><p>仅平台内部可见，独立保存</p></div><el-button v-if="can('platform:order:note')" type="primary" size="small" @click="openNoteDialog()"><StickyNote :size="15" />添加备注</el-button></div>
+                <p v-if="detail.order.internalNotes.length === 0" class="compact-empty">暂无内部备注</p>
+                <ul v-else class="notes-list" aria-label="内部备注"><li v-for="item in detail.order.internalNotes" :key="String(item.id)"><p>{{ item.content }}</p><span>操作人 {{ item.createdBy || '系统' }} · {{ formatDate(item.createdAt) }}</span></li></ul>
+              </section>
+            </template>
+          </section>
+        </template>
+      </div>
+      </DetailPageLayout>
+    </template>
+
+    <template v-else>
+    <ListPageLayout ariaLabel="统一订单列表">
+    <template #toolbar>
+    <div class="orders-query-panel">
+      <div class="status-tabs" role="tablist" aria-label="订单主状态">
+        <button
+          v-for="(tab, index) in statusTabs"
+          :key="tab.value || 'ALL'"
+          type="button"
+          role="tab"
+          :aria-selected="selectedStatus === tab.value"
+          aria-controls="unified-orders-results"
+          :tabindex="selectedStatus === tab.value ? 0 : -1"
+          :class="['status-tab', { 'is-active': selectedStatus === tab.value }]"
+          @click="selectStatus(tab.value)"
+          @keydown="handleTabKeydown($event, index)"
+        >{{ tab.label }}</button>
+      </div>
+
+      <QueryToolbar id="unified-orders-advanced-filters" v-model="filters" class="orders-query-toolbar" ariaLabel="订单列表筛选" :fields="queryFields" :available-fields="allQueryFields" preference-key="unified-orders-query-v2" :search-on-reset="false" @search="search" @reset="reset">
+        <template #actions>
+          <el-button :aria-expanded="showAdvancedFilters" aria-controls="unified-orders-advanced-filters" @click="showAdvancedFilters = !showAdvancedFilters">
+            <SlidersHorizontal :size="16" />{{ showAdvancedFilters ? '收起筛选' : '高级筛选' }}
+            <ChevronUp v-if="showAdvancedFilters" :size="15" /><ChevronDown v-else :size="15" />
+          </el-button>
+        </template>
+      </QueryToolbar>
+    </div>
+    </template>
+
+    <template v-if="loadError" #state>
+    <LoadErrorState title="订单列表暂时无法加载" :message="loadError.message" :loading="loading" @retry="loadOrders">
+      <template #details><ApiErrorMeta :details="loadError" /></template>
+    </LoadErrorState>
+    </template>
+
+    <template #default>
+    <div v-if="!loadError" id="unified-orders-results" class="surface-panel table-panel table-card" role="tabpanel">
+      <div v-if="coLoadError" class="coload-error" role="alert"><span>{{ coLoadError.message }}</span><ApiErrorMeta :details="coLoadError" /></div>
+      <DataTable v-model:page="page" v-model:page-size="pageSize" :data="records" :columns="columns" preference-key="unified-orders-table-v2" :loading="loading" :total="total" :page-sizes="[20, 50, 100]" row-key="orderId" border stripe empty-text="暂无符合条件的订单" aria-label="统一订单列表" @selection-change="handleOrderSelectionChange">
+        <template #toolbar-actions>
+          <el-button v-if="can('platform:order:export') && can('platform:download:list')" :loading="exportSubmitting" :disabled="loading || exportSubmitting" @click="exportOrders"><Download :size="16" />导出<span v-if="selectedOrders.length">（已选 {{ selectedOrders.length }}）</span></el-button>
+          <el-button v-if="can('platform:order:approve')" type="success" :loading="batchApprovalLoading || batchApprovalSaving" :disabled="loading || !selectedApprovalOrders.length" @click="openBatchApproval"><CircleCheck :size="16" />批量审核通过<span v-if="selectedApprovalOrders.length">（{{ selectedApprovalOrders.length }}）</span></el-button>
+          <div v-if="can('platform:firstleg:smart-loading:assign')" class="coload-toolbar-action">
+            <el-button type="primary" plain :loading="coLoadSaving" :disabled="loading || !canCreateCoLoadGroup" aria-label="合柜报关" @click="openCoLoadCreate"><Link2 :size="16" />合柜报关<span v-if="selectedOrders.length">（{{ selectedOrders.length }}）</span></el-button>
+          </div>
+          <el-button v-if="can('platform:firstleg:inbound:view')" :loading="printingCartonLabels" :disabled="loading || printingCartonLabels || !selectedCartonLabelOrders.length" @click="printSelectedCartonLabels"><Printer :size="16" />打印箱唛<span v-if="selectedCartonLabelOrders.length">（{{ selectedCartonLabelOrders.length }}）</span></el-button>
+          <el-button v-if="can('platform:firstleg:smart-loading:list')" type="primary" @click="smartLoadingOpen = true"><PackageOpen :size="16" />智能装柜</el-button>
+        </template>
+        <template #actions="{ row }">
+          <div class="row-actions density-actions">
+            <el-button class="density-action" size="small" @click="openDetail(row as UnifiedOrderResource)">详情</el-button>
+            <el-button v-for="action in directUnifiedOrderActions(row as UnifiedOrderResource)" :key="action" class="density-action" :data-tone="action === 'approve' ? 'warning' : action === 'measurement' ? 'purple' : 'neutral'" size="small" :loading="action === 'approve' && approvalLoadingId === String((row as UnifiedOrderResource).orderId)" @click="runMoreAction(action, row as UnifiedOrderResource)">{{ unifiedOrderActionLabel(action) }}</el-button>
+            <el-dropdown v-if="moreUnifiedOrderActions(row as UnifiedOrderResource).length" trigger="click" @command="runMoreAction($event, row as UnifiedOrderResource)">
+              <el-button class="density-action" size="small" :aria-label="moreUnifiedOrderActionsLabel(row as UnifiedOrderResource)" :title="moreUnifiedOrderActionsLabel(row as UnifiedOrderResource)"><MoreHorizontal :size="17" aria-hidden="true" /></el-button>
+              <template #dropdown>
+                <el-dropdown-menu>
+                  <el-dropdown-item v-for="action in moreUnifiedOrderActions(row as UnifiedOrderResource)" :key="action" :command="action">{{ unifiedOrderActionLabel(action) }}</el-dropdown-item>
+                </el-dropdown-menu>
+              </template>
+            </el-dropdown>
+          </div>
+        </template>
+        <template #inboundCode="{ row }">
+          <div class="inbound-relation-cell order-code-cell">
+            <strong class="inbound-code-value" :title="(row as UnifiedOrderResource).inboundCode || '待生成入仓码'">{{ (row as UnifiedOrderResource).inboundCode || '待生成入仓码' }}</strong>
+            <button v-if="coLoadGroup(row as UnifiedOrderResource)" type="button" class="coload-tag-trigger" :aria-label="`查看${coLoadGroupSummary(coLoadGroup(row as UnifiedOrderResource)!)}成员`" @click.stop="openCoLoadDetail(row as UnifiedOrderResource)"><el-tag size="small" :type="coLoadGroup(row as UnifiedOrderResource)?.status === 'ACTIVE' ? 'warning' : 'info'">{{ coLoadGroupSummary(coLoadGroup(row as UnifiedOrderResource)!) }}</el-tag></button>
+            <el-button
+              v-if="(row as UnifiedOrderResource).relation"
+              class="order-relation-link"
+              link
+              type="primary"
+              :aria-label="`查看${orderRelationLabel(row as UnifiedOrderResource)}关联`"
+              @click="openOrderRelation(row as UnifiedOrderResource)"
+            ><GitBranch :size="14" />{{ orderRelationLabel(row as UnifiedOrderResource) }}</el-button>
+          </div>
+        </template>
+        <template #orderStatus="{ row }"><StatusBadge :status="orderStatusLabel((row as UnifiedOrderResource).internalOrderStatus || (row as UnifiedOrderResource).mainStatus)" /></template>
+        <template #measurementReviewStatus="{ row }"><StatusBadge :status="measurementStatusLabel((row as UnifiedOrderResource).measurement?.reviewStatus)" /></template>
+        <template #channel="{ row }"><div class="channel-cell"><LineClampText :content="(row as UnifiedOrderResource).channelName" /><el-tag v-if="(row as UnifiedOrderResource).channelChanged" size="small" type="warning">曾变更渠道</el-tag></div></template>
+        <template #estimatedVolume="{ row }">
+          <div class="planning-cell">
+            <el-input-number
+              v-if="canEditPlanning(row as UnifiedOrderResource)"
+              v-model="planningDraft(row as UnifiedOrderResource).estimatedVolumeCbm"
+              class="planning-volume-input"
+              :min="0.0001"
+              :precision="4"
+              :controls="false"
+              :disabled="planningDraft(row as UnifiedOrderResource).saving"
+              placeholder="填写预估体积"
+              :aria-label="`修改 ${(row as UnifiedOrderResource).inboundCode || '当前订单'} 预估体积`"
+              @change="savePlanning(row as UnifiedOrderResource)"
+            />
+            <span v-else>{{ formatNumber((row as UnifiedOrderResource).estimatedVolumeCbm, 4) }}</span>
+            <small v-if="planningDraft(row as UnifiedOrderResource).saving">保存中…</small>
+          </div>
+        </template>
+        <template #expectedArrival="{ row }">
+          <div class="planning-cell">
+            <el-date-picker
+              style="width: 100%;"
+              v-if="canEditPlanning(row as UnifiedOrderResource)"
+              v-model="planningDraft(row as UnifiedOrderResource).expectedArrivalAt"
+              class="planning-arrival-input"
+              type="datetime"
+              value-format="YYYY-MM-DDTHH:mm:ss"
+              format="YYYY-MM-DD HH:mm"
+              clearable
+              :disabled="planningDraft(row as UnifiedOrderResource).saving"
+              placeholder="选择预计到货时间"
+              :aria-label="`修改 ${(row as UnifiedOrderResource).inboundCode || '当前订单'} 预计到货时间`"
+              @change="savePlanning(row as UnifiedOrderResource)"
+            />
+            <span v-else>{{ formatDate((row as UnifiedOrderResource).expectedArrivalAt) }}</span>
+            <small v-if="planningDraft(row as UnifiedOrderResource).saving">保存中…</small>
+          </div>
+        </template>
+        <template #field="{ row, column }"><LineClampText v-if="column.property === 'customerName'" :content="displayField(row as UnifiedOrderResource, column.property)" /><LineClampText v-else-if="['customerRemark', 'latestInternalNote'].includes(String(column.property))" :content="displayField(row as UnifiedOrderResource, column.property)" :lines="2" /><template v-else>{{ displayField(row as UnifiedOrderResource, column.property) }}</template></template>
+        <template #mainStatus="{ row }"><StatusBadge :status="statusLabel((row as UnifiedOrderResource).mainStatus)" /></template>
+        <template #customer="{ row }"><div class="primary-cell"><strong>{{ customerName(row as UnifiedOrderResource) }}</strong></div></template>
+        <template #receivingWarehouseName="{ row }">{{ (row as UnifiedOrderResource).receivingWarehouseName || '—' }}</template>
+        <template #destinationWarehouseName="{ row }">{{ (row as UnifiedOrderResource).destinationWarehouseName || '—' }}</template>
+        <template #transport="{ row }"><div class="primary-cell"><strong>{{ (row as UnifiedOrderResource).transport?.containerNo || unifiedOrderLoadingStatusLabel((row as UnifiedOrderResource).transport?.loadingStatus) }}</strong><span v-if="(row as UnifiedOrderResource).transport?.vesselName">{{ (row as UnifiedOrderResource).transport?.vesselName }} · {{ (row as UnifiedOrderResource).transport?.voyageNo || '—' }}</span></div></template>
+        <template #cargo="{ row }"><span>{{ (row as UnifiedOrderResource).totalPackageCount ?? '—' }} 箱</span><span v-if="(row as UnifiedOrderResource).measurement?.actualGrossWeightKg !== null && (row as UnifiedOrderResource).measurement?.actualGrossWeightKg !== undefined"> · {{ formatNumber((row as UnifiedOrderResource).measurement?.actualGrossWeightKg) }} kg</span><span v-if="(row as UnifiedOrderResource).measurement?.actualVolumeCbm !== null && (row as UnifiedOrderResource).measurement?.actualVolumeCbm !== undefined"> · {{ formatNumber((row as UnifiedOrderResource).measurement?.actualVolumeCbm, 3) }} m³</span></template>
+        <template #expectedShipDate="{ row }">{{ formatDate((row as UnifiedOrderResource).expectedShipDate) }}</template>
+        <template #updatedAt="{ row }">{{ formatDate((row as UnifiedOrderResource).updatedAt) }}</template>
+        <template #pagination-left="{ total: tableTotal }"><span>共 {{ tableTotal }} 条</span></template>
+      </DataTable>
+    </div>
+    </template>
+    </ListPageLayout>
+    <SmartLoadingDialog v-model="smartLoadingOpen" />
+    <AppDialog class="admin-density-dialog" v-model="batchApprovalOpen" title="批量审核订单" confirm-text="确认批量审核" confirm-type="success" width="min(1100px, calc(100vw - 28px))" :loading="batchApprovalLoading" :confirm-loading="batchApprovalSaving" :confirm-disabled="batchApprovalLoading || !batchApprovalSelectedRows.length" destroy-on-close @confirm="batchApproveOrders">
+      <el-alert title="请逐票核对入仓码、客户、中文品名、渠道和目的仓；审核通过后订单进入待测量。" type="info" :closable="false" show-icon />
+      <LoadErrorState v-if="batchApprovalError" compact title="批量审核预览加载失败" :message="batchApprovalError.message" :loading="batchApprovalLoading" @retry="openBatchApproval"><template #details><ApiErrorMeta :details="batchApprovalError" /></template></LoadErrorState>
+      <template v-else>
+        <div class="batch-approval-summary"><span>预览 {{ batchApprovalPreviewRows.length }} 票</span><strong>已勾选 {{ batchApprovalSelectedRows.length }} 票</strong></div>
+        <el-table ref="batchApprovalTableRef" class="batch-approval-table" :data="batchApprovalPreviewRows" row-key="orderId" border stripe max-height="520" empty-text="暂无可审核订单" @selection-change="handleBatchApprovalSelection">
+          <el-table-column type="selection" width="48" fixed="left" :selectable="(row: UnifiedOrderBatchApprovalPreviewItem) => row.canApprove" />
+          <el-table-column label="入仓码" min-width="160" show-overflow-tooltip><template #default="{ row }"><strong>{{ row.inboundCode || '—' }}</strong></template></el-table-column>
+          <el-table-column label="客户" min-width="150" show-overflow-tooltip><template #default="{ row }">{{ row.customerName || '—' }}</template></el-table-column>
+          <el-table-column label="中文品名" min-width="220" show-overflow-tooltip><template #default="{ row }">{{ row.chineseGoodsNames.length ? row.chineseGoodsNames.join('、') : '—' }}</template></el-table-column>
+          <el-table-column label="渠道" min-width="160" show-overflow-tooltip><template #default="{ row }">{{ row.channelName || row.channelCode || '—' }}</template></el-table-column>
+          <el-table-column label="目的仓" min-width="180" show-overflow-tooltip><template #default="{ row }">{{ row.destinationWarehouseName || row.destinationWarehouseCode || '—' }}</template></el-table-column>
+          <el-table-column label="校验结果" min-width="180" show-overflow-tooltip><template #default="{ row }"><el-tag :type="row.canApprove ? 'success' : 'danger'" effect="light">{{ row.canApprove ? '可审核' : row.blockReason || '不可审核' }}</el-tag></template></el-table-column>
+        </el-table>
+      </template>
+    </AppDialog>
+    <AppDialog class="admin-density-dialog" v-model="coLoadCreateOpen" title="合柜报关" confirm-text="确认建组" :confirm-loading="coLoadSaving" :confirm-disabled="!canCreateCoLoadGroup" @confirm="createCoLoadGroup">
+      <el-alert type="warning" :closable="false" show-icon :title="`所选 ${selectedOrders.length} 票须属于同一国内仓、同一渠道，并全量进入同一柜；目的仓或目的港可以不同。资格由服务端按完整入仓片段校验。`" />
+      <div class="coload-selection"><span v-for="row in selectedOrders" :key="String(row.orderId)">{{ row.inboundCode || '待生成入仓码' }}</span></div>
+      <div v-if="coLoadError" class="coload-error" role="alert"><span>{{ coLoadError.message }}</span><ApiErrorMeta :details="coLoadError" /></div>
+    </AppDialog>
+    <AppDialog class="admin-density-dialog" v-model="coLoadDetailOpen" title="同柜组成员" :show-confirm="false" cancel-text="关闭" width="min(720px, 94vw)" :loading="coLoadDetailLoading" :confirm-loading="coLoadCancelSaving">
+      <LoadErrorState v-if="coLoadDetailError" title="同柜组成员加载失败" :message="coLoadDetailError.message" :loading="coLoadDetailLoading" @retry="loadCoLoadDetail"><template #details><ApiErrorMeta :details="coLoadDetailError" /></template></LoadErrorState>
+      <template v-else-if="coLoadDetailSummary">
+        <div class="coload-detail-summary"><el-tag size="small" :type="coLoadDetailSummary.status === 'ACTIVE' ? 'warning' : 'info'">{{ coLoadGroupSummary(coLoadDetailSummary) }}</el-tag><span>{{ coLoadDetailSummary.memberCount }} 个成员</span></div>
+        <el-alert v-if="coLoadDetailHasMissingInboundCodes" type="error" :closable="false" show-icon title="同柜组成员入仓码尚未返回，请刷新后重试" />
+        <div v-else-if="coLoadDetailMembers.length" class="coload-detail-scroll">
+          <table class="coload-detail-table">
+            <thead><tr><th>入仓码</th></tr></thead>
+            <tbody><tr v-for="member in coLoadDetailMembers" :key="member.inboundCode"><td><strong :title="member.inboundCode">{{ member.inboundCode }}</strong></td></tr></tbody>
+          </table>
+        </div>
+        <el-empty v-else description="暂无同柜组成员" :image-size="56" />
+        <div v-if="coLoadCancelError" class="coload-error" role="alert"><span>{{ coLoadCancelError.message }}</span><ApiErrorMeta :details="coLoadCancelError" /></div>
+      </template>
+      <template #footer="{ close }"><div class="app-dialog__footer"><el-button :disabled="coLoadCancelSaving" @click="close">关闭</el-button><el-button v-if="coLoadDetailSummary?.status === 'ACTIVE' && can('platform:firstleg:smart-loading:assign')" type="danger" :loading="coLoadCancelSaving" @click="cancelCoLoadGroup">解除同柜组</el-button></div></template>
+    </AppDialog>
+    </template>
+
+    <AppDrawer class="admin-density-drawer" v-model="relationOpen" title="父子订单关联" size="min(860px, 94vw)" :show-footer="false" destroy-on-close>
+      <OrderFulfillmentTreePanel
+        v-if="relationOrder"
+        :tenant-id="String(relationOrder.tenantId)"
+        :order-id="String(relationOrder.orderId)"
+        :inbound-code="relationOrder.inboundCode"
+      />
+    </AppDrawer>
+
+    <AppDialog class="admin-density-dialog" v-model="noteOpen" title="编辑订单备注" width="min(680px, calc(100vw - 28px))" confirm-text="保存备注" :confirm-loading="noteSaving" @confirm="saveNote">
+      <el-form label-position="top" class="order-remarks-form">
+        <el-form-item label="客户备注（只读）"><el-input :model-value="noteOrder?.customerRemark || '—'" disabled /></el-form-item>
+        <el-form-item label="内部备注"><el-input v-model="noteForm.internalRemark" type="textarea" :rows="3" maxlength="1000" show-word-limit placeholder="可填写、修改或清空内部备注" /></el-form-item>
+        <el-form-item label="仓库备注"><el-input v-model="noteForm.warehouseRemark" type="textarea" :rows="3" maxlength="1000" show-word-limit placeholder="可填写、修改或清空仓库备注" /></el-form-item>
+        <el-form-item label="客服备注"><el-input v-model="noteForm.customerServiceRemark" type="textarea" :rows="3" maxlength="1000" show-word-limit placeholder="可填写、修改或清空客服备注" /></el-form-item>
+      </el-form>
+    </AppDialog>
+
+    <AppDialog class="admin-density-dialog" v-model="holdDialogOpen" :title="holdAction === 'HOLD' ? '确认扣货' : '确认解除扣货'" :confirm-text="holdAction === 'HOLD' ? '确认扣货' : '确认解除'" :confirm-type="holdAction === 'HOLD' ? 'danger' : 'primary'" :confirm-loading="holdSaving" :confirm-disabled="!holdReason.trim() || holdReason.trim().length > 1000" width="min(600px, calc(100vw - 28px))" destroy-on-close @confirm="submitHoldAction">
+      <el-alert :title="holdAction === 'HOLD' ? '扣货后服务端将阻止后续实物履约操作。' : '解除后是否可继续履约仍以服务端状态为准。'" :type="holdAction === 'HOLD' ? 'warning' : 'info'" :closable="false" show-icon />
+      <el-form label-position="top" class="hold-command-form"><el-form-item :label="holdAction === 'HOLD' ? '扣货原因' : '解除原因'" required><el-input v-model="holdReason" type="textarea" :rows="4" maxlength="1000" show-word-limit :placeholder="holdAction === 'HOLD' ? '请输入扣货原因' : '请输入解除扣货原因'" aria-label="扣货操作原因" /></el-form-item><el-form-item label="关联文件（选填）"><el-upload :key="holdEvidenceUploadKey" :auto-upload="false" :limit="1" accept=".txt,.pdf,.jpg,.jpeg,.png,text/plain,application/pdf,image/jpeg,image/png" :disabled="holdSaving" :on-change="selectHoldEvidenceFile" :on-remove="removeHoldEvidenceFile"><el-button :disabled="holdSaving"><FileUp :size="15" />选择文件</el-button><template #tip><div class="el-upload__tip">仅支持 TXT、PDF、JPG、PNG，单文件不超过 10MB；服务端将校验文件真实内容。</div></template></el-upload></el-form-item><LoadErrorState v-if="holdEvidenceError" compact title="关联文件处理失败" :message="holdEvidenceError.message" :show-retry="false"><template #details><ApiErrorMeta :details="holdEvidenceError" /></template></LoadErrorState></el-form>
+    </AppDialog>
+
+    <AppDialog class="admin-density-dialog" v-model="approvalOpen" title="审核订单" confirm-text="审核通过" confirm-type="success" :confirm-loading="approvalSaving" destroy-on-close @confirm="approveOrder" @cancel="closeApproval">
+      <dl v-if="approvalOrder" class="approval-facts">
+        <div><dt>入仓码</dt><dd>{{ approvalOrder.inboundCode || '—' }}</dd></div>
+        <div><dt>客户</dt><dd>{{ customerName(approvalOrder) }}</dd></div>
+        <div><dt>渠道</dt><dd>{{ approvalOrder.channelName || '—' }}</dd></div>
+        <div><dt>目的仓</dt><dd>{{ approvalOrder.destinationWarehouseName || '—' }}</dd></div>
+        <div><dt>总箱数</dt><dd>{{ approvalOrder.totalPackageCount ?? '—' }} 箱</dd></div>
+      </dl>
+      <p class="approval-hint">确认订单资料无误后审核通过，订单将进入待测量阶段。</p>
+    </AppDialog>
+
+    <OrderDeclarationEditorDialog
+      v-if="detail"
+      v-model="declarationEditorOpen"
+      :detail="detail"
+      @updated="handleDeclarationUpdated"
+    />
+
+    <AppDialog
+      class="admin-density-dialog"
+      v-model="measurementPreviewOpen"
+      :title="measurementPreviewTitle"
+      width="min(920px, calc(100vw - 28px))"
+      :loading="measurementPreviewLoading"
+      :show-footer="false"
+      destroy-on-close
+    >
+      <LoadErrorState v-if="measurementPreviewError" title="测量原图暂时无法读取" :message="measurementPreviewError.message">
+        <template #details><ApiErrorMeta :details="measurementPreviewError" /></template>
+      </LoadErrorState>
+      <img v-else-if="measurementPreviewUrl" class="measurement-original-preview" :src="measurementPreviewUrl" :alt="measurementPreviewTitle" />
+      <el-empty v-else-if="!measurementPreviewLoading" description="该记录未返回可预览的图片" :image-size="56" />
+    </AppDialog>
+
+    <InboundMeasurementDialog
+      class="admin-density-dialog"
+      v-if="measurementOrder?.inboundId"
+      v-model="measurementDialogOpen"
+      :customer-id="String(measurementOrder.tenantId)"
+      :inbound-id="String(measurementOrder.inboundId)"
+      :inbound-code="measurementOrder.inboundCode"
+      :open-warehouse-suggestion="openWarehouseSuggestionOnMeasurementLoad"
+      @updated="handleMeasurementUpdated"
+      @submitted="handleMeasurementSubmitted"
+      @closed="clearMeasurementOrder"
+    />
+
+  </section>
+  </AdminPage>
+</template>
+
+<style scoped>
+.detail-tabs { border: 1px solid var(--cc-border); border-block: 0; }
+
+.panel-title > div:first-child { display: flex; align-items: baseline; flex-wrap: wrap; gap: var(--admin-space-1, 4px) var(--admin-space-5, 12px); }
+.compact-empty { margin: 0; padding: 14px var(--admin-space-4, 10px); color: var(--cc-muted); text-align: center; font-size: var(--admin-font-body, 13px); }
+.approval-facts { margin: 0; border-top: 1px solid var(--cc-border); }
+.approval-facts > div { display: grid; grid-template-columns: 88px minmax(0, 1fr); gap: var(--admin-space-5, 12px); padding: var(--admin-space-3, 8px) 0; border-bottom: 1px solid var(--cc-border); }
+.approval-facts dt { color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); }
+.approval-facts dd { min-width: 0; margin: 0; overflow-wrap: anywhere; font-size: var(--admin-font-body, 13px); }
+.approval-hint { margin: var(--admin-space-5, 12px) 0 0; color: #475467; font-size: var(--admin-font-body, 13px); }
+.detail-panel :deep(.el-table) { font-size: var(--admin-font-body, 13px); --el-table-header-bg-color: var(--admin-label-bg, #f8fafc); }
+.detail-panel :deep(.el-table__cell) { height: var(--admin-row-height, 36px); padding: var(--admin-space-1, 4px) 0; }
+.detail-panel :deep(.el-table .cell) { line-height: 22px; overflow-wrap: anywhere; }
+.detail-panel :deep(.el-table__empty-block) { min-height: 44px; }
+.detail-panel :deep(.el-table__empty-text) { line-height: 44px; }
+.history-table :deep(.cell) { white-space: normal; }
+.measurement-section-title:has([aria-expanded="false"]) { border-bottom: 1px solid var(--cc-border); }
+.fulfillment-facts + .fulfillment-facts { border-top: 0; }
+@media (min-width: 961px) {
+  .table-card :deep(.data-table__pagination) { min-height: 44px; padding: var(--admin-space-2, 6px) var(--admin-space-5, 12px); }
+}
+
+.unified-orders-page { min-width: 0; gap: var(--admin-space-5, 12px); --cc-list-table-font-size: 13px; --cc-list-query-font-size: 13px; --cc-list-action-font-size: 13px; }
+.page-intro { display: flex; align-items: flex-start; justify-content: space-between; gap: var(--admin-space-6, 16px); margin-bottom: var(--admin-space-6, 16px); }
+.page-intro h1 { margin: 0; color: var(--cc-text); font-size: 22px; line-height: 1.35; }
+.page-intro p { margin: 5px 0 0; color: var(--cc-muted); font-size: var(--admin-font-body, 13px); line-height: 1.6; }
+.page-intro :deep(.el-button) { flex: 0 0 auto; }
+.orders-query-panel { overflow: hidden; border: 1px solid var(--cc-border); border-radius: var(--admin-radius, 4px); background: var(--admin-surface, #fff); }
+.status-tabs { display: flex; max-width: 100%; overflow-x: auto; margin-bottom: 0; border-bottom: 1px solid var(--admin-table-border, #e5e7eb); background: #f9fafb; scrollbar-width: thin; }
+.status-tab { position: relative; flex: 0 0 auto; min-height: var(--admin-tab-height, 38px); padding: 0 var(--admin-space-6, 16px); border: 0; background: transparent; color: var(--cc-muted); font: inherit; font-size: var(--admin-font-body, 13px); cursor: pointer; }
+.status-tab::after { position: absolute; right: 12px; bottom: 0; left: 12px; height: 3px; background: transparent; content: ''; }
+.status-tab:hover { color: var(--cc-primary); background: #f6f9fd; }
+.status-tab:focus-visible { outline: 2px solid var(--cc-primary); outline-offset: -2px; }
+.status-tab.is-active { color: var(--cc-primary); font-weight: 600; }
+.status-tab.is-active::after { background: var(--cc-primary); }
+.orders-query-toolbar { border: 0; padding: var(--admin-space-4, 10px) var(--admin-space-5, 12px); }
+.table-card { overflow: hidden; border-radius: var(--admin-radius, 4px); box-shadow: none; }
+.coload-error { margin: var(--admin-space-3, 8px) var(--admin-space-5, 12px); padding: var(--admin-space-3, 8px) var(--admin-space-4, 10px); border: 1px solid var(--el-color-danger-light-5); border-radius: var(--admin-radius, 4px); background: var(--el-color-danger-light-9); color: var(--el-color-danger); font-size: var(--admin-font-caption, 12px); }
+.coload-error :deep(.api-error-meta) { margin-top: 5px; }
+.order-code-cell { display: grid; justify-items: start; gap: var(--admin-space-1, 4px); }
+.coload-tag-trigger { margin: 0; padding: 0; border: 0; background: transparent; cursor: pointer; }
+.coload-tag-trigger:focus-visible { outline: 2px solid var(--el-color-primary); outline-offset: 2px; border-radius: 3px; }
+.coload-selection { display: flex; flex-wrap: wrap; gap: var(--admin-space-2, 6px); margin-top: var(--admin-space-5, 12px); }
+.coload-selection > span { padding: var(--admin-space-1, 4px) 7px; border: 1px solid var(--cc-border); border-radius: var(--admin-radius, 4px); background: var(--cc-surface-muted); font-size: var(--admin-font-caption, 12px); }
+.coload-detail-summary { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-5, 12px); margin-bottom: var(--admin-space-4, 10px); }
+.coload-detail-scroll { overflow-x: auto; border: 1px solid var(--cc-border); border-radius: var(--admin-radius, 4px); }
+.coload-detail-table { width: 100%; border-collapse: collapse; font-size: var(--admin-font-caption, 12px); }
+.coload-detail-table th,.coload-detail-table td { padding: var(--admin-space-3, 8px) var(--admin-space-4, 10px); border-bottom: 1px solid var(--cc-border); text-align: left; vertical-align: top; }
+.coload-detail-table th { background: var(--cc-surface-muted); color: var(--cc-muted); font-weight: 600; }
+.coload-detail-table tbody tr:last-child td { border-bottom: 0; }
+.coload-detail-table td { min-width: 210px; }
+.coload-detail-table td:last-child { min-width: 80px; white-space: nowrap; }
+.coload-detail-table td strong,.coload-detail-table td span { display: block; overflow-wrap: anywhere; }
+.coload-detail-table td span { color: var(--cc-muted); }
+.coload-detail-table :deep(.el-button) { min-height: 24px; padding: 2px 0; }
+.coload-toolbar-action { display: flex; min-width: 0; align-items: center; gap: var(--admin-space-3, 8px); }
+.subsequent-fulfillment { margin-top: var(--admin-space-5, 12px); padding-top: var(--admin-space-4, 10px); border-top: 1px solid var(--cc-border); }
+.subsequent-fulfillment h3 { margin: 0 0 var(--admin-space-3, 8px); font-size: var(--admin-font-section, 14px); }
+.fulfillment-facts { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); margin: 0; border-top: 1px solid var(--cc-border); border-left: 1px solid var(--cc-border); overflow: hidden; }
+.batch-approval-summary { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-6, 16px); margin: var(--admin-space-5, 12px) 0 var(--admin-space-3, 8px); color: var(--cc-muted); font-size: var(--admin-font-body, 13px); white-space: nowrap; }
+.batch-approval-summary strong { color: var(--cc-text); }
+.batch-approval-table :deep(.cell) { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.fulfillment-facts > div { display: flex; align-items: baseline; gap: var(--admin-space-4, 10px); min-width: 0; padding: var(--admin-space-3, 8px) var(--admin-space-4, 10px); border-right: 1px solid var(--cc-border); border-bottom: 1px solid var(--cc-border); background: var(--admin-surface, #fff); }
+.fulfillment-facts > div.wide { grid-column: span 2; }
+.fulfillment-facts dt { flex: 0 0 auto; color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); }
+.fulfillment-facts dd { min-width: 0; margin: 0; overflow-wrap: anywhere; font-size: var(--admin-font-body, 13px); }
+.fulfillment-empty { margin: 0; padding: var(--admin-space-5, 12px); border: 1px dashed var(--cc-border); border-radius: 6px; color: var(--cc-muted); text-align: center; }
+.row-actions { display: flex; align-items: center; gap: var(--admin-space-2, 6px); white-space: nowrap; }
+.row-actions :deep(.el-button) { margin-left: 0; }
+.table-card :deep(.data-table__system-cell .row-actions .el-dropdown) { margin-left: 0; }
+.planning-cell { display: grid; min-width: 0; gap: var(--admin-space-1, 4px); }
+.planning-cell > small { color: var(--cc-muted); font-size: var(--admin-font-caption, 11px); }
+.planning-volume-input,.planning-arrival-input { width: 100%; max-width: 100%; }
+.planning-cell :deep(.el-input__wrapper) { min-height: var(--admin-control-height, 32px); padding-right: 9px; padding-left: 9px; }
+.planning-cell :deep(.el-input__inner) { min-width: 0; text-align: left; }
+.inbound-relation-cell { display: grid; min-width: 0; gap: 5px; }
+.inbound-code-value { display: block; max-width: 100%; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.order-relation-link { width: fit-content; max-width: 100%; height: auto; justify-content: flex-start; padding: 0; font-size: var(--admin-font-caption, 12px); }
+.order-relation-link :deep(span) { min-width: 0; white-space: normal; text-align: left; }
+.primary-cell { display: grid; min-width: 0; gap: var(--admin-space-1, 4px); }
+.primary-cell strong { overflow-wrap: anywhere; }
+.primary-cell span { color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); overflow-wrap: anywhere; }
+.order-detail-header { border: 1px solid var(--cc-border); border-bottom: 0; border-radius: 4px 4px 0 0; }
+
+.back-button { flex: 0 0 auto; padding: 0; }
+.order-title { min-width: 0; }
+
+.detail-header-actions { display: flex; flex: 0 0 auto; gap: var(--admin-space-3, 8px); }
+.detail-header-actions :deep(.el-button + .el-button) { margin-left: 0; }
+.detail-load-error { min-height: 280px; }
+.order-detail-content { min-width: 0; }
+.detail-overview { border: 1px solid var(--cc-border); border-top: 0; }
+.detail-panel { min-width: 0; padding: var(--admin-space-5, 12px); border: 1px solid var(--cc-border); border-radius: 0 0 4px 4px; background: var(--admin-surface, #fff); }
+.panel-title { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-5, 12px); min-height: var(--admin-action-height, 28px); margin-bottom: var(--admin-space-3, 8px); }
+.panel-title h2 { margin: 0; color: #344054; font-size: var(--admin-font-section, 14px); font-weight: 600; }
+.panel-title p { margin: 0; color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); line-height: 1.5; }
+.panel-title > svg { color: var(--cc-primary); }
+.measurement-title-actions { display: flex; flex-wrap: wrap; justify-content: flex-end; gap: var(--admin-space-3, 8px); }
+.measurement-title-actions :deep(.el-button) { margin-left: 0; }
+.fee-confirm-form { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 0 22px; }
+.fee-confirm-price-alert { margin-bottom: 14px; }
+.fee-confirm-number-wrap { position: relative; width: 100%; }
+.fee-confirm-number { width: 100%; }
+.fee-confirm-number :deep(.el-input__wrapper) { padding-right: 92px; }
+.fee-confirm-unit { position: absolute; top: 50%; right: 12px; z-index: 1; transform: translateY(-50%); color: var(--cc-muted); pointer-events: none; }
+.fee-confirm-reference-title { margin: var(--admin-space-3, 8px) 0 var(--admin-space-5, 12px); color: var(--cc-text); font-size: var(--admin-font-section, 14px); }
+.fee-confirm-price-reason { grid-column: 1 / -1; }
+.fee-confirm-price-summary { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); margin: 0 0 var(--admin-space-6, 16px); border: 1px solid var(--cc-border); background: var(--admin-label-bg, #f8fafc); }
+.fee-confirm-price-summary > div { min-width: 0; padding: var(--admin-space-4, 10px) var(--admin-space-5, 12px); }
+.fee-confirm-price-summary > div + div { border-left: 1px solid var(--cc-border); }
+.fee-confirm-price-summary dt { color: var(--cc-muted); font-size: var(--admin-font-caption, 11px); }
+.fee-confirm-price-summary dd { margin: var(--admin-space-1, 4px) 0 0; color: var(--cc-text); font-size: var(--admin-font-body, 13px); font-weight: 650; }
+@media (max-width: 680px) { .fee-confirm-form { grid-template-columns: 1fr; } .fee-confirm-unit { right: 12px; } }
+.fee-section-title { margin: var(--admin-space-5, 12px) 0 var(--admin-space-3, 8px); color: #344054; font-size: var(--admin-font-section, 14px); line-height: 1.4; }
+.fee-overview { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); margin: 0; border: 1px solid var(--cc-border); }
+.fee-overview > div { display: flex; flex-wrap: wrap; align-items: baseline; gap: var(--admin-space-1, 4px) var(--admin-space-5, 12px); padding: var(--admin-space-3, 8px) var(--admin-space-4, 10px); }
+.fee-overview > div + div { border-left: 1px solid var(--cc-border); }
+.fee-overview dt, .fee-overview small { color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); }
+.fee-overview dd { margin: 0; font-size: var(--admin-font-title, 16px); font-weight: 600; font-variant-numeric: tabular-nums; }
+.fee-overview small { margin-left: auto; }
+.fee-section-title--secondary { margin-top: var(--admin-space-5, 12px); padding-top: var(--admin-space-4, 10px); border-top: 1px solid var(--cc-border); }
+.order-info-grid { grid-template-columns: repeat(4, minmax(0, 1fr)); margin: 0; }
+.order-info-grid > div.wide { grid-column: span 2; }
+.detail-table-wrap { overflow-x: auto; }
+.detail-table-wrap :deep(.el-table) { min-width: 720px; --el-table-header-bg-color: var(--admin-label-bg, #f8fafc); }
+.cargo-image { width: 40px; height: var(--admin-control-height, 32px); border: 1px solid var(--cc-border); border-radius: 2px; background: var(--admin-label-bg, #f8fafc); cursor: zoom-in; }
+.measurement-grid { grid-template-columns: repeat(4, minmax(0, 1fr)); margin: 0; }
+.measurement-section { margin-top: var(--admin-space-5, 12px); }
+.measurement-section-title { display: flex; width: 100%; min-height: var(--admin-row-height, 36px); align-items: center; gap: var(--admin-space-5, 12px); padding: var(--admin-space-1, 4px) var(--admin-space-4, 10px); border: 1px solid var(--cc-border); border-bottom: 0; background: var(--admin-label-bg, #f8fafc); color: var(--cc-text); }
+.measurement-section-title:hover { background: #f2f6fb; }
+.measurement-section-title h3 { flex: 0 0 auto; margin: 0; color: var(--cc-text); font-size: var(--admin-font-body, 13px); font-weight: 600; }
+.measurement-section-summary { display: flex; min-width: 0; flex: 1; flex-wrap: wrap; align-items: center; justify-content: flex-end; gap: var(--admin-space-1, 4px) var(--admin-space-6, 16px); color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); }
+.measurement-section-toggle { display: flex; min-width: 0; min-height: var(--admin-action-height, 28px); flex: 1; align-items: center; gap: var(--admin-space-6, 16px); padding: 0; border: 0; background: transparent; color: inherit; font: inherit; text-align: left; cursor: pointer; }
+.measurement-section-toggle:focus-visible { outline: 2px solid var(--cc-primary); outline-offset: 2px; }
+.measurement-section-toggle > svg { flex: 0 0 auto; margin-left: auto; color: var(--cc-muted); }
+.measurement-section-mode { flex: 0 0 190px; }
+.measurement-section-title > .measurement-section-mode { display: none; }
+.measurement-rule-selector { display: flex; flex-wrap: wrap; align-items: center; gap: var(--admin-space-4, 10px); margin: 0; padding: var(--admin-space-3, 8px) var(--admin-space-4, 10px); border: 1px solid var(--cc-border); border-top: 0; background: var(--admin-surface, #fff); }
+.measurement-rule-selector__label { color: var(--cc-text); font-size: var(--admin-font-caption, 12px); font-weight: 650; white-space: nowrap; }
+.measurement-rule-selector__control { width: 270px; }
+.measurement-rule-selector__hint { color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); }
+.measurement-outer-dimension-input { width: 128px; max-width: 100%; }
+.measurement-total { display: flex; min-height: var(--admin-control-height, 32px); flex-wrap: wrap; align-items: center; justify-content: flex-end; gap: var(--admin-space-1, 4px) 20px; padding: var(--admin-space-2, 6px) var(--admin-space-4, 10px); border: 1px solid var(--cc-border); border-top: 0; background: var(--admin-label-bg, #f8fafc); color: #475467; font-size: var(--admin-font-caption, 12px); font-variant-numeric: tabular-nums; }
+
+.measurement-total strong { margin-right: auto; color: var(--cc-text); font-size: var(--admin-font-body, 13px); }
+.weight-evidence { margin-top: var(--admin-space-5, 12px); padding: var(--admin-space-4, 10px) 0 0; border-top: 1px solid var(--cc-border); background: var(--admin-surface, #fff); }
+.weight-evidence__heading { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-6, 16px); margin-bottom: var(--admin-space-3, 8px); }
+.weight-evidence__heading h4 { margin: 0; color: var(--cc-text); font-size: var(--admin-font-section, 14px); }
+.weight-evidence__heading p { margin: 5px 0 0; color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); }
+.weight-evidence__heading dl { margin: 0; text-align: right; }
+.weight-evidence__heading dt { color: var(--cc-muted); font-size: var(--admin-font-caption, 11px); }
+.weight-evidence__heading dd { margin: 0; color: var(--cc-text); font-size: var(--admin-font-body, 13px); font-weight: 600; }
+.weight-evidence-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(280px, 1fr)); gap: var(--admin-space-3, 8px); }
+.weight-evidence-card { display: grid; grid-template-columns: 96px minmax(0, 1fr); align-items: center; min-width: 0; padding: var(--admin-space-3, 8px); border: 1px solid var(--cc-border); background: var(--admin-surface, #fff); }
+.weight-evidence-card > dl { display: grid; gap: var(--admin-space-1, 4px); margin: 0; padding: 0 0 0 var(--admin-space-3, 8px); }
+.weight-evidence-card > dl > div { display: flex; min-width: 0; justify-content: space-between; gap: var(--admin-space-5, 12px); }
+.weight-evidence-card dt { color: var(--cc-muted); font-size: var(--admin-font-caption, 11px); }
+.weight-evidence-card dd { min-width: 0; margin: 0; color: var(--cc-text); font-size: var(--admin-font-caption, 12px); font-weight: 650; text-align: right; overflow-wrap: anywhere; }
+.measurement-original-preview { display: block; width: 100%; max-height: min(72vh, 760px); object-fit: contain; border-radius: 8px; background: #f2f4f7; }
+.hold-section { padding-bottom: var(--admin-space-5, 12px); border-bottom: 1px solid var(--cc-border); }
+.other-notes-section { padding-top: var(--admin-space-4, 10px); }
+.hold-summary { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-6, 16px); padding: var(--admin-space-3, 8px) var(--admin-space-4, 10px); border: 1px solid var(--cc-border); background: var(--admin-surface, #fff); }
+.hold-summary dl { display: grid; min-width: 0; flex: 1; grid-template-columns: 210px minmax(280px, 1fr); gap: var(--admin-space-5, 12px); margin: 0; }
+.hold-summary dl > div { display: flex; align-items: baseline; gap: var(--admin-space-4, 10px); min-width: 0; }
+.hold-summary dt { flex: 0 0 auto; margin: 0; color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); }
+.hold-summary dd { margin: 0; color: var(--cc-text); font-size: var(--admin-font-body, 13px); overflow-wrap: anywhere; }
+.hold-actions { display: flex; flex: 0 0 auto; gap: var(--admin-space-3, 8px); }
+.hold-actions :deep(.el-button) { margin-left: 0; }
+.hold-block-reason { margin: var(--admin-space-5, 12px) 0 0; padding: 9px var(--admin-space-5, 12px); border: 1px solid var(--el-color-warning-light-5); border-radius: var(--admin-radius, 4px); background: var(--el-color-warning-light-9); color: var(--el-color-warning-dark-2); font-size: var(--admin-font-caption, 12px); }
+.hold-history-title { margin: var(--admin-space-6, 16px) 0 var(--admin-space-3, 8px); color: #344054; font-size: var(--admin-font-section, 14px); }
+.hold-history-table { min-width: 0; overflow-x: auto; }
+.hold-command-form { margin-top: var(--admin-space-6, 16px); }
+.hold-evidence-hint { margin: -var(--admin-space-1, 4px) 0 0; color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); }
+.notes-list { display: grid; gap: 0; margin: 0; padding: 0; list-style: none; }
+.notes-list p { margin: var(--admin-space-1, 4px) 0 0; color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); line-height: 1.55; overflow-wrap: anywhere; }
+.notes-list li { padding: 14px 0; border-bottom: 1px solid #edf0f4; }
+.notes-list li:first-child { padding-top: 0; }
+.notes-list li:last-child { padding-bottom: 0; border-bottom: 0; }
+.notes-list li > p { margin: 0; color: var(--cc-text); font-size: var(--admin-font-body, 13px); }
+.notes-list span { display: block; margin-top: 5px; color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); }
+@media (max-width: 960px) { .order-info-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); } .measurement-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); } }
+@media (max-width: 720px) { .page-intro { align-items: stretch; flex-direction: column; } .page-intro :deep(.el-button) { width: 100%; min-height: 44px; } .status-tab { min-height: 46px; padding: 0 14px; } .table-actions :deep(.el-button) { width: 100%; min-height: 40px; } .row-actions { flex-wrap: wrap; } .order-detail-header { align-items: stretch; flex-direction: column; } .order-detail-heading { flex-wrap: wrap; } .detail-header-actions { display: grid; grid-template-columns: 1fr; } .detail-header-actions :deep(.el-button) { min-height: 40px; } .order-info-grid, .measurement-grid { grid-template-columns: 1fr; } .order-info-grid > div.wide { grid-column: auto; } .detail-tabs button { padding: 0 18px; } .detail-panel { padding: 16px; } .measurement-section-title { align-items: flex-start; flex-wrap: wrap; padding: 12px; } .measurement-section-summary { width: 100%; flex-basis: calc(100% - 34px); flex-wrap: wrap; justify-content: flex-start; gap: 6px 16px; white-space: normal; } .measurement-section-title > svg { margin-left: auto; } .measurement-total { flex-wrap: wrap; justify-content: flex-start; gap: 6px 16px; } .measurement-total strong { width: 100%; } }
+@media (max-width: 720px) { .weight-evidence__heading { flex-direction: column; } .weight-evidence__heading dl { text-align: left; } }
+@media (max-width: 720px) { .fee-overview { grid-template-columns: 1fr; } .fee-overview > div + div { border-top: 1px solid var(--cc-border); border-left: 0; } }
+@media (max-width: 720px) { .measurement-section-title { align-items: stretch; flex-direction: column; } .measurement-section-toggle { align-items: flex-start; flex-wrap: wrap; } .measurement-section-toggle > svg { margin-left: auto; } .measurement-section-mode { width: 100%; flex-basis: auto; } }
+@media (max-width: 420px) { .weight-evidence { padding: 10px; } .weight-evidence-grid { grid-template-columns: 1fr; } }
+</style>
+
+<style src="@/styles/adminDensity.css"></style>
+<style src="../styles/orderDensity.css"></style>
diff --git a/src/modules/unified-orders/routes.ts b/src/modules/unified-orders/routes.ts
new file mode 100644
index 00000000..ecfc2db8
--- /dev/null
+++ b/src/modules/unified-orders/routes.ts
@@ -0,0 +1,37 @@
+import type { RouteRecordRaw } from 'vue-router'
+
+export const unifiedOrderRoutes = [
+  {
+    path: 'orders',
+    name: 'unified-orders',
+    component: () => import('./pages/UnifiedOrdersView.vue'),
+    meta: {
+      title: '订单列表',
+      description: '围绕同一订单主线跟进审核、测量、分柜、装柜和派送',
+      permission: 'platform:order:list',
+      permissionAnyOf: ['platform:firstleg:inbound:list'],
+    },
+  },
+  {
+    path: 'orders/inbound/:inboundCode',
+    name: 'unified-order-detail-by-inbound-code',
+    component: () => import('./pages/UnifiedOrdersView.vue'),
+    meta: {
+      title: '订单详情',
+      description: '按入仓码查看订单测量数据和履约详情',
+      permission: 'platform:order:view',
+      permissionAnyOf: ['platform:order:list', 'platform:firstleg:inbound:view'],
+    },
+  },
+  {
+    path: 'orders/:orderId',
+    name: 'unified-order-detail',
+    component: () => import('./pages/UnifiedOrdersView.vue'),
+    meta: {
+      title: '订单详情',
+      description: '查看订单主状态、状态历史和平台备注',
+      permission: 'platform:order:view',
+      permissionAnyOf: ['platform:order:list', 'platform:firstleg:inbound:view'],
+    },
+  },
+] satisfies RouteRecordRaw[]
diff --git a/src/modules/unified-orders/status.test.ts b/src/modules/unified-orders/status.test.ts
new file mode 100644
index 00000000..fa39593f
--- /dev/null
+++ b/src/modules/unified-orders/status.test.ts
@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest'
+import {
+  unifiedOrderFulfillmentRoleLabel,
+  unifiedOrderFulfillmentStatusLabel,
+  unifiedOrderHistoryActionLabel,
+  unifiedOrderLoadingStatusLabel,
+  unifiedOrderReviewStatusLabel,
+  unifiedOrderStatusLabel,
+} from './status'
+
+describe('unified order status labels', () => {
+  it('maps order, review and loading statuses to domain-specific Chinese', () => {
+    expect(unifiedOrderStatusLabel('WAIT_PALLETIZE')).toBe('待一件代发组托')
+    expect(unifiedOrderStatusLabel('WAIT_SPLIT')).toBe('待分柜')
+    expect(unifiedOrderReviewStatusLabel('APPROVED')).toBe('审核通过')
+    expect(unifiedOrderLoadingStatusLabel('LOADED')).toBe('已配载')
+    expect(unifiedOrderHistoryActionLabel('DECLARATION_UPDATE')).toBe('客户申报资料变更')
+  })
+
+  it('never exposes unknown backend enums', () => {
+    expect(unifiedOrderStatusLabel('NEW_ORDER_STATE')).toBe('未知状态')
+    expect(unifiedOrderReviewStatusLabel('NEW_REVIEW_STATE')).toBe('未知状态')
+    expect(unifiedOrderLoadingStatusLabel('NEW_LOADING_STATE')).toBe('未知状态')
+    expect(unifiedOrderHistoryActionLabel('NEW_ACTION')).toBe('状态更新')
+    expect(unifiedOrderFulfillmentRoleLabel('NEW_ROLE')).toBe('未知类型')
+    expect(unifiedOrderFulfillmentStatusLabel('NEW_FRAGMENT_STATE', 'REMAINDER')).toBe('未知状态')
+  })
+
+  it('uses the fragment role when a fulfillment status is absent', () => {
+    expect(unifiedOrderFulfillmentStatusLabel(null, 'ACTIVE_REMAINDER')).toBe('当前余量')
+    expect(unifiedOrderFulfillmentStatusLabel(undefined, 'COMPLETED_FRAGMENT')).toBe('已完成分片')
+  })
+})
diff --git a/src/modules/unified-orders/status.ts b/src/modules/unified-orders/status.ts
new file mode 100644
index 00000000..d1b0adbb
--- /dev/null
+++ b/src/modules/unified-orders/status.ts
@@ -0,0 +1,99 @@
+const orderStatusLabels: Record<string, string> = {
+  DRAFT: '草稿',
+  SUBMITTED: '待审核',
+  APPROVED: '已审核',
+  ACCEPTED: '已受理',
+  REJECTED: '已驳回',
+  PROCESSING: '处理中',
+  COMPLETED: '已完成',
+  CANCELLED: '已取消',
+  PENDING_REVIEW: '待审核',
+  WAIT_MEASURE: '待测量数据',
+  WAIT_PALLETIZE: '待一件代发组托',
+  WAIT_SPLIT: '待分柜',
+  LOADING: '装柜中',
+  LOADED: '装柜完成',
+  DELIVERED: '派送完成',
+}
+
+const reviewStatusLabels: Record<string, string> = {
+  NOT_SUBMITTED: '未提交',
+  UNRECORDED: '未录入',
+  PENDING: '待审核',
+  APPROVED: '审核通过',
+  REJECTED: '审核驳回',
+  CONFIRMED: '已确认',
+}
+
+const loadingStatusLabels: Record<string, string> = {
+  NOT_LOADED: '未配载',
+  WAIT_LOADING: '待配载',
+  EDITING: '预装柜中',
+  LOADING: '配载中',
+  LOADED: '已配载',
+  COMPLETED: '装柜完成',
+}
+
+const historyActionLabels: Record<string, string> = {
+  CREATE: '创建订单',
+  CREATED: '创建订单',
+  SUBMITTED: '提交订单',
+  APPROVED: '审核通过',
+  ORDER_APPROVED: '订单审核通过',
+  REJECTED: '审核驳回',
+  MEASURE_APPROVE: '测量审核通过',
+  MEASURE_REJECT: '测量审核驳回',
+  INBOUND_BEGIN: '开始入库',
+  INBOUND_COMPLETE: '入库完成',
+  UI_FIXTURE_MEASURE_APPROVE: '测量数据审核通过',
+  UI_FIXTURE_INBOUND_BEGIN: '开始入库',
+  STATUS_UPDATE: '状态更新',
+  DECLARATION_UPDATE: '客户申报资料变更',
+}
+
+const fulfillmentRoleLabels: Record<string, string> = {
+  REMAINDER: '当前余量',
+  ACTIVE_REMAINDER: '当前余量',
+  LOADED: '已完成分片',
+  COMPLETED_FRAGMENT: '已完成分片',
+  SOURCE_COMPLETED: '已完成分片',
+}
+
+function normalized(value: string | null | undefined) {
+  return value?.trim().toUpperCase() || ''
+}
+
+function statusLabel(value: string | null | undefined, labels: Record<string, string>, emptyLabel = '—') {
+  const status = normalized(value)
+  if (!status) return emptyLabel
+  return labels[status] || '未知状态'
+}
+
+export function unifiedOrderStatusLabel(value: string | null | undefined, emptyLabel = '—') {
+  return statusLabel(value, orderStatusLabels, emptyLabel)
+}
+
+export function unifiedOrderReviewStatusLabel(value: string | null | undefined, emptyLabel = '—') {
+  return statusLabel(value, reviewStatusLabels, emptyLabel)
+}
+
+export function unifiedOrderLoadingStatusLabel(value: string | null | undefined, emptyLabel = '—') {
+  return statusLabel(value, loadingStatusLabels, emptyLabel)
+}
+
+export function unifiedOrderHistoryActionLabel(value: string | null | undefined) {
+  const action = normalized(value)
+  if (!action) return '状态更新'
+  return historyActionLabels[action] || '状态更新'
+}
+
+export function unifiedOrderFulfillmentRoleLabel(value: string | null | undefined) {
+  const role = normalized(value)
+  if (!role) return '分片'
+  return fulfillmentRoleLabels[role] || '未知类型'
+}
+
+export function unifiedOrderFulfillmentStatusLabel(status: string | null | undefined, role: string | null | undefined) {
+  if (!status) return unifiedOrderFulfillmentRoleLabel(role)
+  return unifiedOrderStatusLabel(status)
+}
diff --git a/src/modules/unified-orders/styles/orderDensity.css b/src/modules/unified-orders/styles/orderDensity.css
new file mode 100644
index 00000000..af6086f4
--- /dev/null
+++ b/src/modules/unified-orders/styles/orderDensity.css
@@ -0,0 +1,38 @@
+/* Order-specific sections. Shared density lives in styles/adminDensity.css. */
+.unified-orders-page .inbound-fee-panel .fee-summary {
+  grid-template-columns: minmax(230px, 1.3fr) repeat(4, minmax(150px, 1fr));
+  border-top: 0;
+}
+.unified-orders-page .inbound-fee-panel .fee-total,
+.unified-orders-page .inbound-fee-panel .fee-summary-item { padding: var(--admin-space-3, 8px) var(--admin-space-4, 10px); gap: var(--admin-space-1, 4px); }
+.unified-orders-page .inbound-fee-panel .fee-summary span,
+.unified-orders-page .inbound-fee-panel .fee-summary small { font-size: var(--admin-font-caption, 12px); }
+.unified-orders-page .inbound-fee-panel .fee-total strong { font-size: 17px; }
+.unified-orders-page .inbound-fee-panel .fee-summary-item strong { font-size: var(--admin-font-section, 14px); }
+.unified-orders-page .inbound-fee-panel .calculation-flow > div { min-height: var(--admin-row-height, 36px); padding: var(--admin-space-2, 6px) var(--admin-space-4, 10px); }
+.unified-orders-page .inbound-fee-panel .calculation-flow span { font-size: var(--admin-font-caption, 12px); }
+.unified-orders-page .inbound-fee-panel .fee-detail-grid > section { padding: var(--admin-space-4, 10px) var(--admin-space-5, 12px) var(--admin-space-4, 10px) 0; }
+.unified-orders-page .inbound-fee-panel .fee-detail-grid > section + section { padding-right: 0; padding-left: var(--admin-space-5, 12px); }
+.unified-orders-page .inbound-fee-panel .fee-detail-grid dl { margin-top: var(--admin-space-3, 8px); }
+.unified-orders-page .inbound-fee-panel .fee-detail-grid dl > div { padding: var(--admin-space-2, 6px) 0; }
+.unified-orders-page .inbound-fee-panel .fee-timeline ol { margin-top: var(--admin-space-3, 8px); }
+.unified-orders-page .inbound-fee-panel .fee-advanced > summary { padding: var(--admin-space-3, 8px) 2px; }
+.unified-orders-page .fee-detail-manager { gap: var(--admin-space-3, 8px); }
+.unified-orders-page .fulfillment-tree-panel { gap: var(--admin-space-3, 8px); }
+.unified-orders-page .fulfillment-tree-panel .tree-summary {
+  display: flex; flex-wrap: wrap; gap: var(--admin-space-2, 6px) 28px; padding: var(--admin-space-3, 8px) var(--admin-space-4, 10px);
+  border-radius: 0; background: var(--admin-surface, #fff);
+}
+.unified-orders-page .fulfillment-tree-panel .tree-summary > div { display: flex; align-items: baseline; gap: var(--admin-space-3, 8px); }
+.unified-orders-page .fulfillment-tree-panel .tree-summary strong { overflow: visible; white-space: normal; overflow-wrap: anywhere; font-size: var(--admin-font-body, 13px); font-weight: 600; }
+
+.admin-density-dialog.el-dialog .batch-approval-table .cell { white-space: normal; overflow-wrap: anywhere; }
+.admin-density-dialog.el-dialog .batch-approval-table .el-tag { height: auto; min-height: 24px; white-space: normal; line-height: 20px; }
+
+@media (max-width: 960px) {
+  .unified-orders-page .inbound-fee-panel .fee-summary { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+}
+@media (max-width: 720px) {
+  .unified-orders-page .inbound-fee-panel .fee-summary { grid-template-columns: 1fr; }
+  .unified-orders-page .inbound-fee-panel .fee-detail-grid > section { padding: 10px 0; }
+}
diff --git a/src/modules/unified-orders/workflows/README.md b/src/modules/unified-orders/workflows/README.md
new file mode 100644
index 00000000..c0bf8023
--- /dev/null
+++ b/src/modules/unified-orders/workflows/README.md
@@ -0,0 +1,17 @@
+# C06 Admin 后半程作业
+
+本目录只承载统一订单详情的后半程作业接入点，供 C05 统一订单列表在详情抽屉或作业页中装配。
+
+真实接口均使用 `/api/platform/v1/inbounds/{inboundId}`：
+
+- `POST /split/smart`：智能分柜/保存预装清单
+- `GET /preload`：单票预装状态与明细只读查询；整份计划的确认统一在预装清单真实 `loadingPlan` 详情完成
+- `GET/POST /loading/picking`、`/loading/picking/start`、`/loading/picking/complete`：拣货
+- `POST /platform/v1/files/loading-evidence/{tenantId}/{inboundId}`：上传真实装柜证据文件
+- `GET/POST /loading/evidence`：查询并登记五类装柜证据及锁码
+- `POST /loading/evidence/{evidenceId}/void`：按原因作废错误照片并保留审计
+- `POST /loading/complete`：完成装柜
+
+所有 Firstleg 写请求带 `Idempotency-Key` 和服务端要求的 `expectedVersion`。`loading/complete` 使用入库单版本；拣货使用拣货任务版本。国内端不提供在线冲正、回退或推进 `DELIVERED`。
+
+权限码、状态流转和请求字段以 Firstleg Controller/DTO 为准；本模块不新增“进入分柜”操作，也不定义通用 `/actions/{ACTION}` 接口。
diff --git a/src/modules/unified-orders/workflows/api.test.ts b/src/modules/unified-orders/workflows/api.test.ts
new file mode 100644
index 00000000..ebe9d0fd
--- /dev/null
+++ b/src/modules/unified-orders/workflows/api.test.ts
@@ -0,0 +1,147 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import {
+  adjustSmartLoadingItem,
+  assignSmartLoadingItem,
+  completeLoading,
+  deleteSmartLoadingItem,
+  downloadEvidenceFile,
+  getContainerBooking,
+  getOutboundDispatch,
+  getPicking,
+  getPreload,
+  listSmartLoadingCandidates,
+  recommendSmartLoading,
+  smartSplit,
+  uploadEvidenceFile,
+  voidEvidence,
+} from './api'
+
+vi.mock('@/shared/api/http', () => ({
+  http: { get: vi.fn(), post: vi.fn(), patch: vi.fn(), delete: vi.fn() },
+  unwrapApiResponse: <T>(response: { data: T }) => response.data,
+}))
+
+describe('unified order workflow API contract', () => {
+  beforeEach(() => {
+    vi.mocked(http.get).mockReset()
+    vi.mocked(http.post).mockReset()
+    vi.mocked(http.patch).mockReset()
+    vi.mocked(http.delete).mockReset()
+  })
+
+  it('uses the C03 preload endpoints and expected version', async () => {
+    vi.mocked(http.get).mockResolvedValue({ data: { id: 1, inboundId: 8, tenantId: 2, status: 'PENDING', version: 3, items: [] } })
+    vi.mocked(http.post).mockResolvedValue({ data: { mainStatus: 'WAIT_SPLIT', preloadPlan: null } })
+    await getPreload('2', '8')
+    await smartSplit('2', '8', { expectedVersion: 3, items: [] })
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/inbounds/8/preload', { params: { tenantId: '2' } })
+    expect(http.post).toHaveBeenCalledWith(
+      '/platform/v1/inbounds/8/split/smart', { expectedVersion: 3, items: [] },
+      expect.objectContaining({ params: { tenantId: '2' }, headers: { 'Idempotency-Key': expect.any(String) } }),
+    )
+  })
+
+  it('uses C04 picking and loading paths without a generic action endpoint', async () => {
+    vi.mocked(http.get).mockResolvedValue({ data: { id: 1, inboundId: 8, status: 'PICKING', version: 4 } })
+    vi.mocked(http.post).mockResolvedValue({ data: { mainStatus: 'LOADED', evidences: null } })
+    await getPicking('2', '8')
+    await completeLoading('2', '8', { expectedVersion: 7 })
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/inbounds/8/loading/picking', { params: { tenantId: '2' } })
+    expect(http.post).toHaveBeenCalledWith(
+      '/platform/v1/inbounds/8/loading/complete', { expectedVersion: 7 },
+      expect.objectContaining({ params: { tenantId: '2' }, headers: { 'Idempotency-Key': expect.any(String) } }),
+    )
+    expect(vi.mocked(http.post).mock.calls.some(([url]) => String(url).includes('/actions/'))).toBe(false)
+  })
+
+  it('does not swallow non-success responses', async () => {
+    vi.mocked(http.get).mockRejectedValue(new Error('无权限'))
+    await expect(getPreload('2', '8')).rejects.toThrow('无权限')
+  })
+
+  it('uploads a real evidence file and voids evidence through audited endpoints', async () => {
+    vi.mocked(http.post)
+      .mockResolvedValueOnce({ data: { fileId: '88', fileName: 'empty.jpg' } })
+      .mockResolvedValueOnce({ data: { mainStatus: 'LOADING', evidences: { inboundId: '8', evidences: [] } } })
+    await uploadEvidenceFile('2', '8', 'PHOTO_STEP_1', new File(['photo'], 'empty.jpg', { type: 'image/jpeg' }))
+    await voidEvidence('2', '8', '33', { expectedVersion: 2, reason: '照片错误' })
+    expect(http.post).toHaveBeenNthCalledWith(1,
+      '/platform/v1/files/loading-evidence/2/8', expect.any(FormData),
+      { headers: { 'Content-Type': 'multipart/form-data' } },
+    )
+    expect(http.post).toHaveBeenNthCalledWith(2,
+      '/platform/v1/inbounds/8/loading/evidence/33/void', { expectedVersion: 2, reason: '照片错误' },
+      expect.objectContaining({ params: { tenantId: '2' }, headers: { 'Idempotency-Key': expect.any(String) } }),
+    )
+  })
+
+  it('downloads loading evidence through the tenant and inbound scoped file endpoint', async () => {
+    const blob = new Blob(['photo'], { type: 'image/jpeg' })
+    vi.mocked(http.get).mockResolvedValue(blob)
+    await expect(downloadEvidenceFile('2', '8', '88')).resolves.toBe(blob)
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/files/loading-evidence/2/8/88', { responseType: 'blob' })
+  })
+
+  it('normalizes smart-loading long identifiers as strings', async () => {
+    vi.mocked(http.get)
+      .mockResolvedValueOnce({ data: { id: '2086085512165634050', warehouseId: '2086085512165634051', capacityCbm: '68', maxWeightKg: '25000', version: 2 } })
+      .mockResolvedValueOnce({ data: [{
+        accountId: '2086085512165634052', inboundId: '2086085512165634053', inboundDetailId: '2086085512165634054',
+        orderId: '2086085512165634055', warehouseId: '2086085512165634051', availablePackageCount: '12',
+        unitWeightKg: '10.5', unitVolumeCbm: '0.25',
+      }] })
+    const container = await getContainerBooking('2086085512165634050')
+    const candidates = await listSmartLoadingCandidates(container.id, container.warehouseId!)
+    expect(http.get).toHaveBeenLastCalledWith('/platform/v1/first-leg/smart-loading/candidates', { params: { bookingId: container.id, warehouseId: container.warehouseId } })
+    expect(container).toMatchObject({ id: '2086085512165634050', warehouseId: '2086085512165634051', capacityCbm: 68 })
+    expect(candidates[0]).toMatchObject({
+      accountId: '2086085512165634052', inboundId: '2086085512165634053',
+      inboundDetailId: '2086085512165634054', orderId: '2086085512165634055', availablePackageCount: 12,
+    })
+  })
+
+  it('normalizes preload and outbound aggregate identifiers as strings', async () => {
+    vi.mocked(http.get)
+      .mockResolvedValueOnce({ data: {
+        id: '2086085512165634050', inboundId: '2086085512165634051', tenantId: '2086085512165634052',
+        status: 'PENDING', version: 1, items: [],
+      } })
+      .mockResolvedValueOnce({ data: [{
+        orderId: '2086085512165634053', inboundId: '2086085512165634051',
+        containerBookingId: '2086085512165634054', loadingPlanId: '2086085512165634055',
+        oceanBookingId: '2086085512165634056', truckAppointmentId: '2086085512165634057', gate: null,
+      }] })
+    const preload = await getPreload('2086085512165634052', '2086085512165634051')
+    const dispatch = await getOutboundDispatch('2086085512165634052', '2086085512165634053', '2086085512165634051')
+    expect(preload).toMatchObject({ id: '2086085512165634050', inboundId: '2086085512165634051', tenantId: '2086085512165634052' })
+    expect(dispatch).toMatchObject({
+      orderId: '2086085512165634053', containerBookingId: '2086085512165634054',
+      loadingPlanId: '2086085512165634055', oceanBookingId: '2086085512165634056', truckAppointmentId: '2086085512165634057',
+    })
+  })
+
+  it('uses optimistic locks and operation identifiers for smart-loading mutations', async () => {
+    const plan = { id: '91', bookingId: '81', status: 'EDITING', version: 4, items: [] }
+    vi.mocked(http.post).mockResolvedValue({ data: plan })
+    vi.mocked(http.patch).mockResolvedValue({ data: plan })
+    vi.mocked(http.delete).mockResolvedValue({ data: plan })
+    await assignSmartLoadingItem('91', { inboundId: '71', inboundDetailId: '72', packageCount: 3, expectedVersion: 4 })
+    await recommendSmartLoading('91', 4)
+    await adjustSmartLoadingItem('91', '92', { packageCount: 2, expectedPlanVersion: 4, expectedItemVersion: 1 })
+    await deleteSmartLoadingItem('91', '92', { expectedPlanVersion: 4, expectedItemVersion: 1 })
+    expect(http.post).toHaveBeenNthCalledWith(1, '/platform/v1/first-leg/smart-loading/plans/91/assignments', {
+      inboundId: '71', inboundDetailId: '72', packageCount: 3, expectedVersion: 4,
+      operationId: expect.stringContaining('smart-loading-assign'),
+    })
+    expect(http.post).toHaveBeenNthCalledWith(2, '/platform/v1/first-leg/smart-loading/plans/91/recommend', {
+      expectedVersion: 4, operationId: expect.stringContaining('smart-loading-recommend'),
+    })
+    expect(http.patch).toHaveBeenCalledWith('/platform/v1/first-leg/smart-loading/plans/91/items/92', expect.objectContaining({
+      expectedPlanVersion: 4, expectedItemVersion: 1, operationId: expect.stringContaining('smart-loading-adjust'),
+    }))
+    expect(http.delete).toHaveBeenCalledWith('/platform/v1/first-leg/smart-loading/plans/91/items/92', {
+      data: expect.objectContaining({ expectedPlanVersion: 4, expectedItemVersion: 1, operationId: expect.stringContaining('smart-loading-delete') }),
+    })
+  })
+})
diff --git a/src/modules/unified-orders/workflows/api.ts b/src/modules/unified-orders/workflows/api.ts
new file mode 100644
index 00000000..a7646567
--- /dev/null
+++ b/src/modules/unified-orders/workflows/api.ts
@@ -0,0 +1,533 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+
+const inboundBasePath = '/platform/v1/inbounds'
+
+export interface OutboundGateItem { code: string; name: string; passed: boolean; actual?: string | null; requirement?: string | null }
+export interface OutboundDispatchAggregate {
+  orderId: string | null
+  orderNo: string | null
+  inboundId: string | null
+  inboundCode: string | null
+  containerBookingId: string | null
+  containerNo: string | null
+  loadingPlanId: string | null
+  loadingPlanStatus: string | null
+  oceanBookingId: string | null
+  oceanBookingStatus: string | null
+  truckAppointmentId: string | null
+  truckAppointmentStatus: string | null
+  customsStatus?: string | null
+  sailingStatus?: string | null
+  gate: { passed: boolean; items: OutboundGateItem[] } | null
+}
+
+export interface ContainerBooking {
+  id: string
+  containerNo: string | null
+  cabinetNo: string | null
+  warehouseId: string | null
+  warehouseName: string | null
+  destinationWarehouseCode: string | null
+  destinationWarehouseName: string | null
+  capacityCbm: number | null
+  maxWeightKg: number | null
+  version: number
+}
+
+export interface SmartLoadingCandidate {
+  accountId: string
+  inboundId: string
+  inboundDetailId: string
+  orderId: string
+  orderNo: string | null
+  inboundCode: string | null
+  warehouseId: string
+  destinationWarehouseId: string | null
+  destinationWarehouseCode: string | null
+  destinationWarehouseName: string | null
+  customerName: string | null
+  goodsName: string | null
+  availablePackageCount: number
+  unitWeightKg: number
+  unitVolumeCbm: number
+}
+
+export interface SmartLoadingPlanItem {
+  id: string
+  loadingPlanId: string
+  accountId: string
+  customerName: string | null
+  inboundId: string
+  inboundDetailId: string
+  orderId: string
+  orderNo: string | null
+  inboundCode: string | null
+  destinationWarehouseCode: string | null
+  destinationWarehouseName: string | null
+  skuCode: string | null
+  productNameZh: string | null
+  packageCount: number
+  grossWeightKg: number
+  volumeCbm: number
+  loadSequence: number | null
+  version: number
+}
+
+export interface SmartLoadingPlan {
+  id: string
+  planNo: string | null
+  status: string
+  bookingId: string
+  containerNo: string | null
+  voyageNo: string | null
+  version: number
+  items: SmartLoadingPlanItem[]
+}
+
+export interface CreateSmartLoadingPlanRequest { bookingId: string; remark?: string }
+export interface AssignSmartLoadingItemRequest {
+  inboundId: string
+  inboundDetailId: string
+  packageCount: number
+  expectedVersion: number
+  operationId: string
+}
+export interface RecommendSmartLoadingRequest { expectedVersion: number; operationId: string }
+export interface AdjustSmartLoadingItemRequest {
+  packageCount: number
+  expectedPlanVersion: number
+  expectedItemVersion: number
+  operationId: string
+}
+export interface DeleteSmartLoadingItemRequest {
+  expectedPlanVersion: number
+  expectedItemVersion: number
+  operationId: string
+}
+
+export type PreloadStatus = 'PENDING' | 'CONFIRMING' | 'CONFIRMED' | string
+/** 五类装柜取证。旧接口仍使用 PHOTO_STEP_* / SEAL 编码，页面统一映射为业务名称。 */
+export type EvidenceType = 'PHOTO_STEP_1' | 'PHOTO_STEP_2' | 'PHOTO_STEP_3' | 'PHOTO_STEP_4' | 'SEAL'
+
+export interface PreloadItem {
+  containerCode: string | null
+  cargoReference: string | null
+  packageCount: number | null
+  volumeCbm: number | null
+  remark: string | null
+}
+
+export interface PreloadPlan {
+  id: string
+  inboundId: string
+  tenantId: string
+  status: PreloadStatus
+  version: number
+  items: PreloadItem[]
+  remark: string | null
+  createdAt: string | null
+  updatedAt: string | null
+}
+
+export interface SplitActionResponse {
+  mainStatus: string
+  preloadPlan: PreloadPlan | null
+}
+
+export interface PickingTask {
+  id: number | string
+  inboundId: number | string
+  status: string
+  version: number
+  expectedCount: number | null
+  pickedCount: number | null
+  remark: string | null
+}
+
+export interface Evidence {
+  id: number | string
+  inboundId: number | string
+  tenantId: number | string
+  evidenceType: EvidenceType
+  fileId: number | string | null
+  fileName: string | null
+  sealNo: string | null
+  remark: string | null
+  version: number
+  status: 'ACTIVE' | 'VOIDED' | string
+  createdAt: string | null
+  updatedAt: string | null
+  voidReason?: string | null
+  voidedBy?: number | string | null
+  voidedByName?: string | null
+  voidedAt?: string | null
+}
+
+export interface EvidenceList {
+  inboundId: number | string
+  evidences: Evidence[]
+}
+
+export interface LoadingActionResponse {
+  mainStatus: string
+  evidences: EvidenceList | null
+}
+
+export interface PickingRequest {
+  expectedVersion: number
+  expectedCount: number
+  pickedCount: number
+  remark?: string
+}
+
+export interface SmartSplitRequest {
+  expectedVersion: number
+  items: PreloadItem[]
+  remark?: string
+}
+
+export interface UpsertEvidenceRequest {
+  expectedVersion: number
+  evidenceType: EvidenceType
+  fileId?: number | string
+  fileName?: string
+  sealNo?: string
+  remark?: string
+}
+
+export interface UploadEvidenceResult {
+  fileId: number | string
+  fileName: string | null
+  contentType?: string | null
+  sizeBytes?: number | null
+}
+
+export interface VoidEvidenceRequest {
+  expectedVersion: number
+  reason: string
+}
+
+export interface CompleteLoadingRequest {
+  expectedVersion: number
+  remark?: string
+}
+
+
+function query(tenantId: string | number) {
+  return { tenantId: String(tenantId) }
+}
+
+function idempotencyKey(operation: string, inboundId: string | number) {
+  return `admin-${operation}-${inboundId}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+}
+
+function operationId(operation: string, resourceId: string | number) {
+  return `admin-${operation}-${resourceId}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`
+}
+
+function nullableId(value: number | string | null | undefined) {
+  return value === null || value === undefined || value === '' ? null : String(value)
+}
+
+function numberValue(value: number | string | null | undefined, fallback = 0) {
+  const parsed = Number(value)
+  return Number.isFinite(parsed) ? parsed : fallback
+}
+
+function normalizeContainer(raw: Record<string, unknown>): ContainerBooking {
+  return {
+    id: String(raw.id),
+    containerNo: raw.containerNo == null ? null : String(raw.containerNo),
+    cabinetNo: raw.cabinetNo == null ? null : String(raw.cabinetNo),
+    warehouseId: nullableId(raw.warehouseId as number | string | null),
+    warehouseName: raw.warehouseName == null ? null : String(raw.warehouseName),
+    destinationWarehouseCode: raw.destinationWarehouseCode == null ? null : String(raw.destinationWarehouseCode),
+    destinationWarehouseName: raw.destinationWarehouseName == null ? null : String(raw.destinationWarehouseName),
+    capacityCbm: raw.capacityCbm == null ? null : numberValue(raw.capacityCbm as number | string),
+    maxWeightKg: raw.maxWeightKg == null ? null : numberValue(raw.maxWeightKg as number | string),
+    version: numberValue(raw.version as number | string),
+  }
+}
+
+function normalizeCandidate(raw: Record<string, unknown>): SmartLoadingCandidate {
+  return {
+    accountId: String(raw.accountId), inboundId: String(raw.inboundId), inboundDetailId: String(raw.inboundDetailId),
+    orderId: String(raw.orderId), orderNo: raw.orderNo == null ? null : String(raw.orderNo),
+    inboundCode: raw.inboundCode == null ? null : String(raw.inboundCode), warehouseId: String(raw.warehouseId),
+    destinationWarehouseId: nullableId(raw.destinationWarehouseId as number | string | null),
+    destinationWarehouseCode: raw.destinationWarehouseCode == null ? null : String(raw.destinationWarehouseCode),
+    destinationWarehouseName: raw.destinationWarehouseName == null ? null : String(raw.destinationWarehouseName),
+    customerName: raw.customerName == null ? null : String(raw.customerName),
+    goodsName: raw.goodsName == null ? null : String(raw.goodsName),
+    availablePackageCount: numberValue(raw.availablePackageCount as number | string),
+    unitWeightKg: numberValue(raw.unitWeightKg as number | string), unitVolumeCbm: numberValue(raw.unitVolumeCbm as number | string),
+  }
+}
+
+function normalizeSmartLoadingItem(raw: Record<string, unknown>): SmartLoadingPlanItem {
+  return {
+    id: String(raw.id), loadingPlanId: String(raw.loadingPlanId), accountId: String(raw.accountId),
+    customerName: raw.customerName == null ? null : String(raw.customerName), inboundId: String(raw.inboundId),
+    inboundDetailId: String(raw.inboundDetailId), orderId: String(raw.orderId),
+    orderNo: raw.orderNo == null ? null : String(raw.orderNo), inboundCode: raw.inboundCode == null ? null : String(raw.inboundCode),
+    destinationWarehouseCode: raw.destinationWarehouseCode == null ? null : String(raw.destinationWarehouseCode),
+    destinationWarehouseName: raw.destinationWarehouseName == null ? null : String(raw.destinationWarehouseName),
+    skuCode: raw.skuCode == null ? null : String(raw.skuCode), productNameZh: raw.productNameZh == null ? null : String(raw.productNameZh),
+    packageCount: numberValue(raw.packageCount as number | string), grossWeightKg: numberValue(raw.grossWeightKg as number | string),
+    volumeCbm: numberValue(raw.volumeCbm as number | string), loadSequence: raw.loadSequence == null ? null : numberValue(raw.loadSequence as number | string),
+    version: numberValue(raw.version as number | string),
+  }
+}
+
+function normalizeSmartLoadingPlan(raw: Record<string, unknown>): SmartLoadingPlan {
+  return {
+    id: String(raw.id), planNo: raw.planNo == null ? null : String(raw.planNo), status: String(raw.status || ''),
+    bookingId: String(raw.bookingId), containerNo: raw.containerNo == null ? null : String(raw.containerNo),
+    voyageNo: raw.voyageNo == null ? null : String(raw.voyageNo), version: numberValue(raw.version as number | string),
+    items: Array.isArray(raw.items) ? raw.items.map((item) => normalizeSmartLoadingItem(item as Record<string, unknown>)) : [],
+  }
+}
+
+function normalizeOutboundDispatch(raw: Record<string, unknown>): OutboundDispatchAggregate {
+  return {
+    orderId: nullableId(raw.orderId as number | string | null),
+    orderNo: raw.orderNo == null ? null : String(raw.orderNo),
+    inboundId: nullableId(raw.inboundId as number | string | null),
+    inboundCode: raw.inboundCode == null ? null : String(raw.inboundCode),
+    containerBookingId: nullableId(raw.containerBookingId as number | string | null),
+    containerNo: raw.containerNo == null ? null : String(raw.containerNo),
+    loadingPlanId: nullableId(raw.loadingPlanId as number | string | null),
+    loadingPlanStatus: raw.loadingPlanStatus == null ? null : String(raw.loadingPlanStatus),
+    oceanBookingId: nullableId(raw.oceanBookingId as number | string | null),
+    oceanBookingStatus: raw.oceanBookingStatus == null ? null : String(raw.oceanBookingStatus),
+    truckAppointmentId: nullableId(raw.truckAppointmentId as number | string | null),
+    truckAppointmentStatus: raw.truckAppointmentStatus == null ? null : String(raw.truckAppointmentStatus),
+    customsStatus: raw.customsStatus == null ? null : String(raw.customsStatus),
+    sailingStatus: raw.sailingStatus == null ? null : String(raw.sailingStatus),
+    gate: raw.gate == null ? null : raw.gate as OutboundDispatchAggregate['gate'],
+  }
+}
+
+function normalizePreloadPlan(raw: Record<string, unknown>): PreloadPlan {
+  return {
+    id: String(raw.id), inboundId: String(raw.inboundId), tenantId: String(raw.tenantId),
+    status: String(raw.status || ''), version: numberValue(raw.version as number | string),
+    items: Array.isArray(raw.items) ? raw.items.map((item) => ({ ...(item as PreloadItem) })) : [],
+    remark: raw.remark == null ? null : String(raw.remark),
+    createdAt: raw.createdAt == null ? null : String(raw.createdAt),
+    updatedAt: raw.updatedAt == null ? null : String(raw.updatedAt),
+  }
+}
+
+function normalizeSplitAction(raw: Record<string, unknown>): SplitActionResponse {
+  return {
+    mainStatus: String(raw.mainStatus || ''),
+    preloadPlan: raw.preloadPlan == null ? null : normalizePreloadPlan(raw.preloadPlan as Record<string, unknown>),
+  }
+}
+
+const smartLoadingBasePath = '/platform/v1/first-leg/smart-loading'
+
+export async function getContainerBooking(bookingId: string | number) {
+  const response = await http.get<ApiEnvelope<Record<string, unknown>>, ApiEnvelope<Record<string, unknown>>>(
+    `/platform/v1/containers/${bookingId}`,
+  )
+  return normalizeContainer(unwrapApiResponse(response))
+}
+
+export async function listSmartLoadingCandidates(bookingId: string | number, warehouseId: string | number) {
+  const response = await http.get<ApiEnvelope<Record<string, unknown>[]>, ApiEnvelope<Record<string, unknown>[]>>(
+    `${smartLoadingBasePath}/candidates`, { params: { bookingId: String(bookingId), warehouseId: String(warehouseId) } },
+  )
+  return unwrapApiResponse(response).map(normalizeCandidate)
+}
+
+export async function getSmartLoadingPlan(planId: string | number) {
+  const response = await http.get<ApiEnvelope<Record<string, unknown>>, ApiEnvelope<Record<string, unknown>>>(
+    `${smartLoadingBasePath}/plans/${planId}`,
+  )
+  return normalizeSmartLoadingPlan(unwrapApiResponse(response))
+}
+
+export async function getSmartLoadingPlanByBooking(bookingId: string | number) {
+  const response = await http.get<ApiEnvelope<Record<string, unknown>>, ApiEnvelope<Record<string, unknown>>>(
+    `${smartLoadingBasePath}/plans/by-booking/${bookingId}`,
+  )
+  return normalizeSmartLoadingPlan(unwrapApiResponse(response))
+}
+
+export async function assignSmartLoadingItem(planId: string | number, request: Omit<AssignSmartLoadingItemRequest, 'operationId'>) {
+  const response = await http.post<ApiEnvelope<Record<string, unknown>>, ApiEnvelope<Record<string, unknown>>>(
+    `${smartLoadingBasePath}/plans/${planId}/assignments`,
+    { ...request, operationId: operationId('smart-loading-assign', planId) },
+  )
+  return normalizeSmartLoadingPlan(unwrapApiResponse(response))
+}
+
+export async function recommendSmartLoading(planId: string | number, expectedVersion: number) {
+  const response = await http.post<ApiEnvelope<Record<string, unknown>>, ApiEnvelope<Record<string, unknown>>>(
+    `${smartLoadingBasePath}/plans/${planId}/recommend`,
+    { expectedVersion, operationId: operationId('smart-loading-recommend', planId) },
+  )
+  return normalizeSmartLoadingPlan(unwrapApiResponse(response))
+}
+
+export async function adjustSmartLoadingItem(
+  planId: string | number,
+  itemId: string | number,
+  request: Omit<AdjustSmartLoadingItemRequest, 'operationId'>,
+) {
+  const response = await http.patch<ApiEnvelope<Record<string, unknown>>, ApiEnvelope<Record<string, unknown>>>(
+    `${smartLoadingBasePath}/plans/${planId}/items/${itemId}`,
+    { ...request, operationId: operationId('smart-loading-adjust', itemId) },
+  )
+  return normalizeSmartLoadingPlan(unwrapApiResponse(response))
+}
+
+export async function deleteSmartLoadingItem(
+  planId: string | number,
+  itemId: string | number,
+  request: Omit<DeleteSmartLoadingItemRequest, 'operationId'>,
+) {
+  const response = await http.delete<ApiEnvelope<Record<string, unknown>>, ApiEnvelope<Record<string, unknown>>>(
+    `${smartLoadingBasePath}/plans/${planId}/items/${itemId}`,
+    { data: { ...request, operationId: operationId('smart-loading-delete', itemId) } },
+  )
+  return normalizeSmartLoadingPlan(unwrapApiResponse(response))
+}
+
+function writeOptions(operation: string, inboundId: string | number, tenantId: string | number) {
+  return { params: query(tenantId), headers: { 'Idempotency-Key': idempotencyKey(operation, inboundId) } }
+}
+
+export async function getPreload(tenantId: string | number, inboundId: string | number) {
+  const response = await http.get<ApiEnvelope<Record<string, unknown>>, ApiEnvelope<Record<string, unknown>>>(
+    `${inboundBasePath}/${inboundId}/preload`, { params: query(tenantId) },
+  )
+  return normalizePreloadPlan(unwrapApiResponse(response))
+}
+
+export async function getOutboundDispatch(tenantId: string | number, orderId?: string | number, inboundId?: string | number) {
+  const response = await http.get<ApiEnvelope<Record<string, unknown>[]>, ApiEnvelope<Record<string, unknown>[]>>(
+    '/platform/v1/first-leg/outbound-dispatches',
+    { params: { tenantId: String(tenantId), ...(orderId ? { orderId: String(orderId) } : {}), ...(inboundId ? { inboundId: String(inboundId) } : {}) } },
+  )
+  const result = unwrapApiResponse(response)
+  return result?.[0] ? normalizeOutboundDispatch(result[0]) : null
+}
+
+export async function smartSplit(
+  tenantId: string | number,
+  inboundId: string | number,
+  request: SmartSplitRequest,
+) {
+  const response = await http.post<ApiEnvelope<Record<string, unknown>>, ApiEnvelope<Record<string, unknown>>>(
+    `${inboundBasePath}/${inboundId}/split/smart`, request, writeOptions('smart-split', inboundId, tenantId),
+  )
+  return normalizeSplitAction(unwrapApiResponse(response))
+}
+
+export async function getPicking(tenantId: string | number, inboundId: string | number) {
+  const response = await http.get<ApiEnvelope<PickingTask>, ApiEnvelope<PickingTask>>(
+    `${inboundBasePath}/${inboundId}/loading/picking`, { params: query(tenantId) },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function startPicking(
+  tenantId: string | number,
+  inboundId: string | number,
+  request: PickingRequest,
+) {
+  const response = await http.post<ApiEnvelope<PickingTask>, ApiEnvelope<PickingTask>>(
+    `${inboundBasePath}/${inboundId}/loading/picking/start`, request,
+    writeOptions('picking-start', inboundId, tenantId),
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function completePicking(
+  tenantId: string | number,
+  inboundId: string | number,
+  request: PickingRequest,
+) {
+  const response = await http.post<ApiEnvelope<PickingTask>, ApiEnvelope<PickingTask>>(
+    `${inboundBasePath}/${inboundId}/loading/picking/complete`, request,
+    writeOptions('picking-complete', inboundId, tenantId),
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function getEvidence(tenantId: string | number, inboundId: string | number) {
+  const response = await http.get<ApiEnvelope<EvidenceList>, ApiEnvelope<EvidenceList>>(
+    `${inboundBasePath}/${inboundId}/loading/evidence`, { params: query(tenantId) },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function upsertEvidence(
+  tenantId: string | number,
+  inboundId: string | number,
+  request: UpsertEvidenceRequest,
+) {
+  const response = await http.post<ApiEnvelope<LoadingActionResponse>, ApiEnvelope<LoadingActionResponse>>(
+    `${inboundBasePath}/${inboundId}/loading/evidence`, request,
+    writeOptions(`evidence-${request.evidenceType}`, inboundId, tenantId),
+  )
+  return unwrapApiResponse(response)
+}
+
+/** 真实 File 服务上传；返回的 fileId 才能提交证据，不接受本地文件名冒充。 */
+export async function uploadEvidenceFile(
+  tenantId: string | number,
+  inboundId: string | number,
+  evidenceType: EvidenceType,
+  file: File,
+) {
+  const body = new FormData()
+  body.append('evidenceType', evidenceType)
+  body.append('file', file)
+  const response = await http.post<ApiEnvelope<UploadEvidenceResult>, ApiEnvelope<UploadEvidenceResult>>(
+    `/platform/v1/files/loading-evidence/${tenantId}/${inboundId}`,
+    body,
+    { headers: { 'Content-Type': 'multipart/form-data' } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export function downloadEvidenceFile(
+  tenantId: string | number,
+  inboundId: string | number,
+  fileId: string | number,
+) {
+  return http.get<Blob, Blob>(
+    `/platform/v1/files/loading-evidence/${encodeURIComponent(String(tenantId))}/${encodeURIComponent(String(inboundId))}/${encodeURIComponent(String(fileId))}`,
+    { responseType: 'blob' },
+  )
+}
+
+export async function voidEvidence(
+  tenantId: string | number,
+  inboundId: string | number,
+  evidenceId: string | number,
+  request: VoidEvidenceRequest,
+) {
+  const response = await http.post<ApiEnvelope<LoadingActionResponse>, ApiEnvelope<LoadingActionResponse>>(
+    `${inboundBasePath}/${inboundId}/loading/evidence/${evidenceId}/void`,
+    request,
+    writeOptions('evidence-void', inboundId, tenantId),
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function completeLoading(
+  tenantId: string | number,
+  inboundId: string | number,
+  request: CompleteLoadingRequest,
+) {
+  const response = await http.post<ApiEnvelope<LoadingActionResponse>, ApiEnvelope<LoadingActionResponse>>(
+    `${inboundBasePath}/${inboundId}/loading/complete`, request,
+    writeOptions('loading-complete', inboundId, tenantId),
+  )
+  return unwrapApiResponse(response)
+}
diff --git a/src/modules/unified-orders/workflows/components/SmartLoadingWorkbench.test.ts b/src/modules/unified-orders/workflows/components/SmartLoadingWorkbench.test.ts
new file mode 100644
index 00000000..93e94fef
--- /dev/null
+++ b/src/modules/unified-orders/workflows/components/SmartLoadingWorkbench.test.ts
@@ -0,0 +1,25 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/unified-orders/workflows/components/SmartLoadingWorkbench.vue'), 'utf8')
+
+describe('SmartLoadingWorkbench business actions', () => {
+  it('keeps the automatically-created preload plan editable without a legacy push action', () => {
+    expect(source).toContain("const editable = computed(() => plan.value?.status === 'EDITING')")
+    expect(source).toContain('自动预装计划缺失')
+    expect(source).not.toContain('canPush')
+    expect(source).not.toContain('推送预装')
+    expect(source).not.toContain('!container?.containerNo')
+  })
+
+  it('uses semantic outlined buttons and keeps narrow action cells usable', () => {
+    expect(source).toContain('size="small" plain type="primary"')
+    expect(source).toContain('size="small" plain type="danger"')
+    expect(source).toContain('<Pencil :size="14" />调整')
+    expect(source).toContain('<Trash2 :size="13" />移除')
+    expect(source).toContain('<Plus :size="14" />加入')
+    expect(source).not.toContain('<el-button link type="primary" :disabled="!canAssign || !editable')
+    expect(source).toContain('@media (max-width: 360px)')
+  })
+})
diff --git a/src/modules/unified-orders/workflows/components/SmartLoadingWorkbench.vue b/src/modules/unified-orders/workflows/components/SmartLoadingWorkbench.vue
new file mode 100644
index 00000000..69a93b30
--- /dev/null
+++ b/src/modules/unified-orders/workflows/components/SmartLoadingWorkbench.vue
@@ -0,0 +1,368 @@
+<script setup lang="ts">
+import { computed, onMounted, ref, watch } from 'vue'
+import { Pencil, Plus, RefreshCw, Sparkles, Trash2 } from '@lucide/vue'
+import { ElMessage } from 'element-plus'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import { ApiResponseError, getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import {
+  adjustSmartLoadingItem,
+  assignSmartLoadingItem,
+  deleteSmartLoadingItem,
+  getContainerBooking,
+  getSmartLoadingPlanByBooking,
+  listSmartLoadingCandidates,
+  recommendSmartLoading,
+  type ContainerBooking,
+  type SmartLoadingCandidate,
+  type SmartLoadingPlan,
+  type SmartLoadingPlanItem,
+} from '@/modules/unified-orders/workflows/api'
+
+const props = defineProps<{
+  bookingId: string
+  highlightInboundId?: string | number | null
+  readOnly?: boolean
+}>()
+
+const emit = defineEmits<{ updated: [] }>()
+const access = useAccessPreviewStore()
+const container = ref<ContainerBooking | null>(null)
+const plan = ref<SmartLoadingPlan | null>(null)
+const candidates = ref<SmartLoadingCandidate[]>([])
+const loading = ref(false)
+const action = ref('')
+const loadError = ref<ApiErrorDetails | null>(null)
+const actionError = ref<ApiErrorDetails | null>(null)
+const conflictRefreshed = ref(false)
+const assignOpen = ref(false)
+const adjustOpen = ref(false)
+const removeOpen = ref(false)
+const selectedCandidate = ref<SmartLoadingCandidate | null>(null)
+const selectedItem = ref<SmartLoadingPlanItem | null>(null)
+const packageCount = ref(1)
+const filters = ref<QueryModel>({ keyword: '', eligibility: '' })
+const appliedFilters = ref<QueryModel>({ ...filters.value })
+
+const canView = computed(() => access.can('platform:firstleg:smart-loading:list'))
+const canAssign = computed(() => !props.readOnly && access.can('platform:firstleg:smart-loading:assign'))
+const canDelete = computed(() => !props.readOnly && access.can('platform:firstleg:smart-loading:delete'))
+const editable = computed(() => plan.value?.status === 'EDITING')
+const usedVolume = computed(() => plan.value?.items.reduce((sum, item) => sum + item.volumeCbm, 0) ?? 0)
+const usedWeight = computed(() => plan.value?.items.reduce((sum, item) => sum + item.grossWeightKg, 0) ?? 0)
+const totalPackages = computed(() => plan.value?.items.reduce((sum, item) => sum + item.packageCount, 0) ?? 0)
+const volumeRate = computed(() => utilization(usedVolume.value, container.value?.capacityCbm))
+const weightRate = computed(() => utilization(usedWeight.value, container.value?.maxWeightKg))
+
+const queryFields: QueryField[] = [
+  { key: 'keyword', type: 'input', label: '候选货物', placeholder: '入仓码、客户或品名', props: { 'aria-label': '候选货物关键词' } },
+  {
+    key: 'eligibility', type: 'select', label: '可装状态', placeholder: '全部状态',
+    options: [{ label: '可加入', value: 'ELIGIBLE' }, { label: '存在冲突', value: 'CONFLICT' }],
+  },
+]
+
+const candidateColumns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 92, fixed: 'left', slotName: 'actions' },
+  { key: 'priority', label: '推荐顺序', width: 92, slotName: 'priority' },
+  { key: 'order', label: '订单/入仓码', minWidth: 180, slotName: 'order' },
+  { key: 'customerName', prop: 'customerName', label: '客户', minWidth: 140 },
+  { key: 'goodsName', prop: 'goodsName', label: '品名', minWidth: 160 },
+  { key: 'destination', label: '目的仓', minWidth: 150, slotName: 'destination' },
+  { key: 'availablePackageCount', prop: 'availablePackageCount', label: '可用箱数', width: 100 },
+  { key: 'unitVolumeCbm', label: '单箱体积(m³)', width: 120, slotName: 'unitVolume' },
+  { key: 'unitWeightKg', label: '单箱重量(kg)', width: 120, slotName: 'unitWeight' },
+  { key: 'explanation', label: '建议与冲突说明', minWidth: 270, slotName: 'explanation' },
+]
+
+const itemColumns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 150, fixed: 'left', slotName: 'actions' },
+  { key: 'loadSequence', prop: 'loadSequence', label: '装柜顺序', width: 100 },
+  { key: 'order', label: '订单/入仓码', minWidth: 180, slotName: 'order' },
+  { key: 'customerName', prop: 'customerName', label: '客户', minWidth: 140 },
+  { key: 'productNameZh', prop: 'productNameZh', label: '品名', minWidth: 160 },
+  { key: 'skuCode', prop: 'skuCode', label: 'SKU', minWidth: 130 },
+  { key: 'packageCount', prop: 'packageCount', label: '箱数', width: 90 },
+  { key: 'grossWeightKg', label: '毛重(kg)', width: 110, slotName: 'weight' },
+  { key: 'volumeCbm', label: '体积(m³)', width: 110, slotName: 'volume' },
+  { key: 'destination', label: '目的仓', minWidth: 150, slotName: 'destination' },
+]
+
+function utilization(used: number, capacity: number | null | undefined) {
+  return capacity && capacity > 0 ? Math.round(used / capacity * 1000) / 10 : null
+}
+
+function formatNumber(value: number, precision = 3) {
+  return Number.isFinite(value) ? value.toLocaleString('zh-CN', { maximumFractionDigits: precision }) : '—'
+}
+
+function planStatusLabel(status?: string | null) {
+  return ({ EDITING: '预装柜中', LOADING: '拣货装柜中', COMPLETED: '装柜完成' } as Record<string, string>)[status || '']
+    || (status ? '未知状态' : '尚未创建')
+}
+
+function routeMatches(candidate: SmartLoadingCandidate) {
+  const target = container.value?.destinationWarehouseCode
+  return !target || candidate.destinationWarehouseCode === target
+}
+
+function fittingCount(candidate: SmartLoadingCandidate) {
+  if (!routeMatches(candidate) || candidate.availablePackageCount <= 0) return 0
+  const volumeLeft = (container.value?.capacityCbm ?? 0) - usedVolume.value
+  const weightLeft = (container.value?.maxWeightKg ?? 0) - usedWeight.value
+  if (!container.value?.capacityCbm || !container.value.maxWeightKg) return 0
+  const byVolume = candidate.unitVolumeCbm > 0 ? Math.floor(Math.max(volumeLeft, 0) / candidate.unitVolumeCbm) : candidate.availablePackageCount
+  const byWeight = candidate.unitWeightKg > 0 ? Math.floor(Math.max(weightLeft, 0) / candidate.unitWeightKg) : candidate.availablePackageCount
+  return Math.max(0, Math.min(candidate.availablePackageCount, byVolume, byWeight))
+}
+
+function candidateExplanation(candidate: SmartLoadingCandidate) {
+  if (!routeMatches(candidate)) return `不可装：目的仓与柜次 ${container.value?.destinationWarehouseName || container.value?.destinationWarehouseCode || '目的仓'} 不一致`
+  if (!container.value?.capacityCbm || !container.value.maxWeightKg) return '不可装：柜次容量或最大承重尚未配置'
+  const count = fittingCount(candidate)
+  if (count <= 0) return '不可装：剩余容积或承重不足'
+  return `可装 ${count} 箱；同仓同目的仓，按入库完成时间先进先出推荐`
+}
+
+const filteredCandidates = computed(() => {
+  const keyword = String(appliedFilters.value.keyword || '').trim().toLowerCase()
+  const eligibility = String(appliedFilters.value.eligibility || '')
+  return candidates.value.filter((candidate) => {
+    const searchable = [candidate.inboundCode, candidate.customerName, candidate.goodsName].join(' ').toLowerCase()
+    if (keyword && !searchable.includes(keyword)) return false
+    const eligible = fittingCount(candidate) > 0
+    return !eligibility || (eligibility === 'ELIGIBLE' ? eligible : !eligible)
+  })
+})
+
+function isConflict(error: unknown) {
+  const details = getApiErrorDetails(error)
+  return error instanceof ApiResponseError && error.code === 'A0409'
+    || details.code === 'A0409'
+    || /版本|并发|已被其他人修改/.test(details.message)
+}
+
+async function load() {
+  if (!canView.value || !props.bookingId) return
+  loading.value = true
+  loadError.value = null
+  try {
+    const nextContainer = await getContainerBooking(props.bookingId)
+    container.value = nextContainer
+    try {
+      plan.value = await getSmartLoadingPlanByBooking(props.bookingId)
+    } catch (error) {
+      const details = getApiErrorDetails(error)
+      if (error instanceof ApiResponseError && ['A0404', 'NOT_FOUND'].includes(error.code)) plan.value = null
+      else throw Object.assign(error instanceof Error ? error : new Error(details.message), { details })
+    }
+    candidates.value = nextContainer.warehouseId ? await listSmartLoadingCandidates(nextContainer.id, nextContainer.warehouseId) : []
+  } catch (error) {
+    container.value = null
+    plan.value = null
+    candidates.value = []
+    loadError.value = getApiErrorDetails(error, '智能排柜数据加载失败，请稍后重试')
+  } finally {
+    loading.value = false
+  }
+}
+
+async function runAction(name: string, operation: () => Promise<SmartLoadingPlan>, success: string) {
+  action.value = name
+  actionError.value = null
+  conflictRefreshed.value = false
+  try {
+    plan.value = await operation()
+    ElMessage.success(success)
+    emit('updated')
+    if (container.value?.warehouseId) candidates.value = await listSmartLoadingCandidates(container.value.id, container.value.warehouseId)
+    return true
+  } catch (error) {
+    actionError.value = getApiErrorDetails(error, `${success}失败，请重试`)
+    if (isConflict(error)) {
+      await load()
+      conflictRefreshed.value = true
+    }
+    return false
+  } finally {
+    action.value = ''
+  }
+}
+
+async function recommend() {
+  if (!plan.value) return
+  await runAction('recommend', () => recommendSmartLoading(plan.value!.id, plan.value!.version), '智能建议已生成')
+}
+
+function openAssign(candidate: SmartLoadingCandidate) {
+  selectedCandidate.value = candidate
+  packageCount.value = Math.max(1, fittingCount(candidate))
+  assignOpen.value = true
+}
+
+async function confirmAssign() {
+  if (!plan.value || !selectedCandidate.value) return
+  const candidate = selectedCandidate.value
+  const success = await runAction('assign', () => assignSmartLoadingItem(plan.value!.id, {
+    inboundId: candidate.inboundId,
+    inboundDetailId: candidate.inboundDetailId,
+    packageCount: packageCount.value,
+    expectedVersion: plan.value!.version,
+  }), '候选货物已加入装柜计划')
+  if (success) assignOpen.value = false
+}
+
+function openAdjust(item: SmartLoadingPlanItem) {
+  selectedItem.value = item
+  packageCount.value = item.packageCount
+  adjustOpen.value = true
+}
+
+async function confirmAdjust() {
+  if (!plan.value || !selectedItem.value) return
+  const item = selectedItem.value
+  const success = await runAction('adjust', () => adjustSmartLoadingItem(plan.value!.id, item.id, {
+    packageCount: packageCount.value,
+    expectedPlanVersion: plan.value!.version,
+    expectedItemVersion: item.version,
+  }), '装柜箱数已调整')
+  if (success) adjustOpen.value = false
+}
+
+function openRemove(item: SmartLoadingPlanItem) {
+  selectedItem.value = item
+  removeOpen.value = true
+}
+
+async function confirmRemove() {
+  if (!plan.value || !selectedItem.value) return
+  const item = selectedItem.value
+  const success = await runAction('remove', () => deleteSmartLoadingItem(plan.value!.id, item.id, {
+    expectedPlanVersion: plan.value!.version,
+    expectedItemVersion: item.version,
+  }), '装柜明细已移除')
+  if (success) removeOpen.value = false
+}
+
+function applyFilters(model: QueryModel) {
+  appliedFilters.value = { keyword: model.keyword || '', eligibility: model.eligibility || '' }
+}
+
+watch(() => [props.bookingId, access.permissionSignature], () => { void load() })
+onMounted(() => { void load() })
+</script>
+
+<template>
+  <section class="smart-loading" aria-label="智能排柜工作台">
+    <header class="smart-loading__heading">
+      <div class="smart-loading__context"><span>当前柜次</span><strong>{{ container?.cabinetNo || container?.containerNo || '柜次信息待补充' }}</strong><small>{{ container?.warehouseName || '仓库待加载' }}</small></div>
+      <div class="smart-loading__actions">
+        <el-button circle :loading="loading" aria-label="刷新智能排柜" @click="load"><RefreshCw :size="16" /></el-button>
+        <el-tag v-if="!plan" type="danger">自动预装计划缺失</el-tag>
+        <el-button v-if="plan" :disabled="!canAssign || !editable || Boolean(action)" :loading="action === 'recommend'" @click="recommend"><Sparkles :size="15" />生成智能建议</el-button>
+      </div>
+    </header>
+
+    <el-alert v-if="!canView" type="warning" :closable="false" show-icon>当前账号无智能排柜查询权限。</el-alert>
+    <LoadErrorState v-else-if="loadError" title="智能排柜暂时无法加载" :message="loadError.message" :loading="loading" @retry="load">
+      <template #details><ApiErrorMeta :details="loadError" /></template>
+    </LoadErrorState>
+    <template v-else>
+      <el-alert v-if="actionError" class="smart-loading__error" type="error" :closable="false" show-icon>
+        <template #title>{{ actionError.message }}</template>
+        <p v-if="conflictRefreshed">系统已刷新最新计划，当前输入仍保留，请核对后重新提交。</p>
+        <ApiErrorMeta :details="actionError" />
+      </el-alert>
+
+      <div v-if="container" class="smart-loading__summary">
+        <div><span>计划状态</span><strong>{{ planStatusLabel(plan?.status) }}</strong></div>
+        <div><span>已装箱数</span><strong>{{ totalPackages }}</strong></div>
+        <div><span>容积</span><strong>{{ formatNumber(usedVolume) }} / {{ formatNumber(container.capacityCbm || 0) }} m³</strong><small>{{ volumeRate == null ? '容量待配置' : `${volumeRate}%` }}</small></div>
+        <div><span>重量</span><strong>{{ formatNumber(usedWeight) }} / {{ formatNumber(container.maxWeightKg || 0) }} kg</strong><small>{{ weightRate == null ? '承重待配置' : `${weightRate}%` }}</small></div>
+      </div>
+
+      <section v-if="plan" class="smart-loading__section surface-panel table-panel">
+        <div class="smart-loading__section-title"><h4>当前装柜方案</h4><span>版本 {{ plan.version }} · {{ plan.planNo || '—' }}</span></div>
+        <DataTable :data="plan.items" :columns="itemColumns" :loading="loading" empty-text="装柜草稿暂无明细">
+          <template #actions="{ row }">
+            <el-button size="small" plain type="primary" :disabled="!canAssign || !editable || Boolean(action)" @click="openAdjust(row as SmartLoadingPlanItem)"><Pencil :size="14" />调整</el-button>
+            <el-button size="small" plain type="danger" :disabled="!canDelete || !editable || Boolean(action)" @click="openRemove(row as SmartLoadingPlanItem)"><Trash2 :size="13" />移除</el-button>
+          </template>
+          <template #order="{ row }"><strong>{{ (row as SmartLoadingPlanItem).inboundCode || '—' }}</strong></template>
+          <template #weight="{ row }">{{ formatNumber((row as SmartLoadingPlanItem).grossWeightKg) }}</template>
+          <template #volume="{ row }">{{ formatNumber((row as SmartLoadingPlanItem).volumeCbm) }}</template>
+          <template #destination="{ row }">{{ (row as SmartLoadingPlanItem).destinationWarehouseName || (row as SmartLoadingPlanItem).destinationWarehouseCode || '—' }}</template>
+        </DataTable>
+      </section>
+
+      <section class="smart-loading__section">
+        <div class="smart-loading__section-title"><h4>候选货物</h4><span>后端按入库完成时间排序</span></div>
+        <ListPageLayout ariaLabel="智能排柜候选货物">
+          <template #toolbar><QueryToolbar v-model="filters" ariaLabel="候选货物筛选" :fields="queryFields" @search="applyFilters" /></template>
+          <section class="surface-panel table-panel">
+        <DataTable :data="filteredCandidates" :columns="candidateColumns" :loading="loading" empty-text="当前柜次仓库暂无可用候选货物">
+          <template #actions="{ row }"><el-button size="small" plain type="primary" :disabled="!plan || !canAssign || !editable || fittingCount(row as SmartLoadingCandidate) <= 0 || Boolean(action)" @click="openAssign(row as SmartLoadingCandidate)"><Plus :size="14" />加入</el-button></template>
+          <template #priority="{ $index }"><span class="priority">{{ Number($index) + 1 }}</span></template>
+          <template #order="{ row }"><strong>{{ (row as SmartLoadingCandidate).inboundCode || '—' }}</strong></template>
+          <template #destination="{ row }">{{ (row as SmartLoadingCandidate).destinationWarehouseName || (row as SmartLoadingCandidate).destinationWarehouseCode || '—' }}</template>
+          <template #unitVolume="{ row }">{{ formatNumber((row as SmartLoadingCandidate).unitVolumeCbm) }}</template>
+          <template #unitWeight="{ row }">{{ formatNumber((row as SmartLoadingCandidate).unitWeightKg) }}</template>
+          <template #explanation="{ row }"><el-tag size="small" :type="fittingCount(row as SmartLoadingCandidate) > 0 ? 'success' : 'danger'">{{ fittingCount(row as SmartLoadingCandidate) > 0 ? '可加入' : '冲突' }}</el-tag><span>{{ candidateExplanation(row as SmartLoadingCandidate) }}</span></template>
+        </DataTable>
+          </section>
+        </ListPageLayout>
+      </section>
+    </template>
+
+    <AppDialog v-model="assignOpen" title="加入装柜方案" :confirm-loading="action === 'assign'" :confirm-disabled="packageCount < 1 || packageCount > (selectedCandidate ? fittingCount(selectedCandidate) : 0)" confirm-text="确认加入" @confirm="confirmAssign">
+      <p>{{ selectedCandidate?.inboundCode || '入仓码暂缺' }} · 最多可加入 {{ selectedCandidate ? fittingCount(selectedCandidate) : 0 }} 箱</p>
+      <el-input-number v-model="packageCount" :min="1" :max="selectedCandidate ? fittingCount(selectedCandidate) : 1" controls-position="right" aria-label="加入箱数" placeholder="请输入箱数" />
+      <ApiErrorMeta v-if="actionError" :details="actionError" />
+    </AppDialog>
+
+    <AppDialog v-model="adjustOpen" title="调整装柜箱数" :confirm-loading="action === 'adjust'" :confirm-disabled="packageCount < 1" confirm-text="保存调整" @confirm="confirmAdjust">
+      <p>{{ selectedItem?.inboundCode || '入仓码暂缺' }} · 当前 {{ selectedItem?.packageCount || 0 }} 箱</p>
+      <el-input-number v-model="packageCount" :min="1" controls-position="right" aria-label="调整后箱数" placeholder="请输入箱数" />
+      <ApiErrorMeta v-if="actionError" :details="actionError" />
+    </AppDialog>
+
+    <AppDialog v-model="removeOpen" title="移除装柜明细" confirm-type="danger" confirm-text="确认移除" :confirm-loading="action === 'remove'" @confirm="confirmRemove">
+      <p>将从当前草稿移除 {{ selectedItem?.inboundCode || '该入仓单' }} 的 {{ selectedItem?.packageCount || 0 }} 箱货物。此操作会写入审计历史。</p>
+      <ApiErrorMeta v-if="actionError" :details="actionError" />
+    </AppDialog>
+
+  </section>
+</template>
+
+<style scoped>
+.smart-loading { display: grid; gap: 14px; }
+.smart-loading__heading, .smart-loading__actions, .smart-loading__section-title { display: flex; align-items: center; flex-wrap: wrap; gap: 10px; }
+.smart-loading__heading, .smart-loading__section-title { justify-content: space-between; }
+.smart-loading__section-title h4 { margin: 0; font-size: 15px; }
+.smart-loading__context { display: grid; min-width: 0; gap: 3px; }
+.smart-loading__context span { color: var(--cc-text-secondary, #64748b); font-size: 11px; }
+.smart-loading__context strong { overflow: hidden; font-size: 14px; text-overflow: ellipsis; white-space: nowrap; }
+.smart-loading__section-title span, .smart-loading small { display: block; margin: 3px 0 0; color: var(--cc-text-secondary, #64748b); font-size: 12px; }
+.smart-loading__summary { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 8px; }
+.smart-loading__summary > div { min-width: 0; padding: 10px; border: 1px solid var(--cc-border); border-radius: 5px; background: var(--el-fill-color-extra-light); }
+.smart-loading__summary span { display: block; margin-bottom: 4px; color: var(--cc-text-secondary, #64748b); font-size: 12px; }
+.smart-loading__summary strong { display: block; overflow-wrap: anywhere; font-size: 13px; }
+.smart-loading__section { display: grid; min-width: 0; gap: 10px; padding-top: 4px; overflow: hidden; }
+.smart-loading__error p { margin: 6px 0 0; }
+.smart-loading :deep(.el-table__cell small), .smart-loading :deep(.el-table__cell strong) { display: block; }
+.smart-loading :deep(.el-table__cell small) { margin-top: 2px; color: var(--cc-text-secondary, #64748b); }
+.smart-loading :deep(.el-table__cell .el-tag + span) { margin-left: 6px; }
+.priority { display: inline-grid; width: 26px; height: 26px; place-items: center; border-radius: 50%; background: var(--el-color-primary-light-9); color: var(--el-color-primary); font-weight: 700; }
+@media (max-width: 760px) {
+  .smart-loading__summary { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+  .smart-loading__actions { width: 100%; }
+  .smart-loading__actions :deep(.el-button:not(.is-circle)) { flex: 1 1 150px; margin-left: 0; }
+}
+@media (max-width: 420px) { .smart-loading__summary { grid-template-columns: 1fr; } }
+@media (max-width: 360px) { .smart-loading :deep(.el-table__cell .el-button) { width: 100%; min-height: 40px; } }
+</style>
diff --git a/src/modules/unified-orders/workflows/components/UnifiedOrderWorkflowPanel.test.ts b/src/modules/unified-orders/workflows/components/UnifiedOrderWorkflowPanel.test.ts
new file mode 100644
index 00000000..b5b2df05
--- /dev/null
+++ b/src/modules/unified-orders/workflows/components/UnifiedOrderWorkflowPanel.test.ts
@@ -0,0 +1,232 @@
+import ElementPlus, { ElMessageBox } from 'element-plus'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { createPinia, setActivePinia } from 'pinia'
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { useAuthStore } from '@/core/auth/auth'
+import { ApiResponseError } from '@/shared/api/http'
+import UnifiedOrderWorkflowPanel from './UnifiedOrderWorkflowPanel.vue'
+import {
+  getEvidence,
+  getOutboundDispatch,
+  getPicking,
+  getPreload,
+  smartSplit,
+  voidEvidence,
+} from '../api'
+
+vi.mock('../api', async (importOriginal) => {
+  const original = await importOriginal<typeof import('../api')>()
+  return {
+    ...original,
+    getEvidence: vi.fn(),
+    getOutboundDispatch: vi.fn(),
+    getPicking: vi.fn(),
+    getPreload: vi.fn(),
+    smartSplit: vi.fn(),
+    voidEvidence: vi.fn(),
+  }
+})
+
+function preload(cargoReference: string, version = 3) {
+  return {
+    id: '2086085512165634050', inboundId: '2086085512165634051', tenantId: '2086085512165634052',
+    status: 'PENDING', version,
+    items: [{ containerCode: 'CAB-01', cargoReference, packageCount: 2, volumeCbm: 1.25, remark: null }],
+    remark: null, createdAt: null, updatedAt: null,
+  }
+}
+
+function mountPanel(permissions: string[], mainStatus: 'WAIT_SPLIT' | 'LOADING' | 'LOADED' = 'WAIT_SPLIT') {
+  const pinia = createPinia()
+  setActivePinia(pinia)
+  useAuthStore().permissions = permissions
+  return mount(UnifiedOrderWorkflowPanel, {
+    props: {
+      tenantId: '2086085512165634052', inboundId: '2086085512165634051', orderId: '2086085512165634053',
+      inboundCode: 'NYEXX2608300001',
+      mainStatus, inboundVersion: 4,
+    },
+    global: { plugins: [pinia, ElementPlus] },
+  })
+}
+
+describe('UnifiedOrderWorkflowPanel preload editor', () => {
+  beforeEach(() => {
+    vi.mocked(getOutboundDispatch).mockReset().mockResolvedValue(null as never)
+    vi.mocked(getEvidence).mockReset().mockResolvedValue({ inboundId: '2086085512165634051', evidences: [] })
+    vi.mocked(getPicking).mockReset().mockResolvedValue({ id: '51', inboundId: '2086085512165634051', status: 'PICKING', version: 2, expectedCount: 10, pickedCount: 4, remark: null })
+    vi.mocked(getPreload).mockReset().mockResolvedValue(preload('REF-OLD'))
+    vi.mocked(smartSplit).mockReset()
+    vi.mocked(voidEvidence).mockReset()
+  })
+
+  it('uses the inbound code as the visible workflow identifier', async () => {
+    const wrapper = mountPanel([])
+    await flushPromises()
+    expect(wrapper.text()).toContain('入库作业')
+    expect(wrapper.text()).toContain('NYEXX2608300001')
+    expect(wrapper.text()).not.toContain('#2086085512165634051')
+  })
+
+  it('keeps workflow business actions as outlined semantic buttons with icons', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/unified-orders/workflows/components/UnifiedOrderWorkflowPanel.vue'), 'utf8')
+    expect(source).toContain('size="small" plain type="primary"')
+    expect(source).toContain('size="small" plain type="danger"')
+    expect(source).toContain('<Pencil :size="14" />编辑')
+    expect(source).toContain('<Eye :size="14" />查看')
+    expect(source).toContain('<Trash2 :size="14" />作废')
+    expect(source).not.toContain('<el-button link type="primary" :disabled="!canSplit')
+    expect(source).not.toContain('<el-button link type="danger" :disabled="!canSplit')
+  })
+
+  it('renders the formal preload table and keeps the operation column first', async () => {
+    const wrapper = mountPanel(['firstleg:inbound:preload-view', 'firstleg:inbound:split'])
+    await flushPromises()
+    expect(getPreload).toHaveBeenCalledWith('2086085512165634052', '2086085512165634051')
+    expect(wrapper.text()).toContain('入库预装清单')
+    expect(wrapper.text()).toContain('REF-OLD')
+    const headers = wrapper.findAll('.el-table__header-wrapper th').map((node) => node.text())
+    expect(headers[0]).toContain('操作')
+    expect(wrapper.find('button[aria-label="编辑第 1 条预装明细"]').exists()).toBe(true)
+  })
+
+  it('keeps single-order preload confirmation read-only and links to the plan list', async () => {
+    const wrapper = mountPanel(['firstleg:inbound:preload-view', 'platform:firstleg:preload:list'])
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('计划级预装确认')
+    expect(wrapper.text()).toContain('从实际预装计划详情确认整份计划')
+    expect(wrapper.text()).toContain('前往预装清单')
+    expect(wrapper.text()).not.toContain('提交确认')
+    expect(wrapper.text()).not.toContain('确认预装清单')
+
+    const source = readFileSync(resolve(process.cwd(), 'src/modules/unified-orders/workflows/components/UnifiedOrderWorkflowPanel.vue'), 'utf8')
+    expect(source).toContain("router.push({ name: 'loading-plans' })")
+  })
+
+  it('does not query or expose editing controls without permission', async () => {
+    const wrapper = mountPanel([])
+    await flushPromises()
+    expect(getPreload).not.toHaveBeenCalled()
+    expect(wrapper.text()).toContain('当前账号无预装清单查询权限')
+    expect(wrapper.find('button[aria-label="编辑第 1 条预装明细"]').exists()).toBe(false)
+  })
+
+  it('blocks an empty list before calling the real endpoint', async () => {
+    vi.mocked(getPreload).mockResolvedValue({ ...preload('REF-OLD'), items: [] })
+    const wrapper = mountPanel(['firstleg:inbound:preload-view', 'firstleg:inbound:split'])
+    await flushPromises()
+    const save = wrapper.findAll('button').find((button) => button.text().includes('保存分柜清单'))
+    expect(save).toBeTruthy()
+    await save!.trigger('click')
+    expect(smartSplit).not.toHaveBeenCalled()
+    expect(wrapper.text()).toContain('请至少添加一条预装明细')
+  })
+
+  it('refreshes the version but preserves submitted rows after a conflict', async () => {
+    vi.mocked(getPreload)
+      .mockResolvedValueOnce(preload('REF-OLD', 3))
+      .mockResolvedValueOnce(preload('REF-SERVER', 4))
+    vi.mocked(smartSplit).mockRejectedValue(new ApiResponseError('数据已被其他人修改，请刷新后重试', 'A0409', 409))
+    const wrapper = mountPanel(['firstleg:inbound:preload-view', 'firstleg:inbound:split'])
+    await flushPromises()
+    const save = wrapper.findAll('button').find((button) => button.text().includes('保存分柜清单'))
+    await save!.trigger('click')
+    await flushPromises()
+    expect(getPreload).toHaveBeenCalledTimes(2)
+    expect(wrapper.text()).toContain('系统已刷新最新数据，请核对后重新提交')
+    expect(wrapper.text()).toContain('REF-OLD')
+    expect(wrapper.text()).not.toContain('REF-SERVER')
+  })
+
+  it('keeps completed loading evidence visible and renders every active photo', async () => {
+    vi.mocked(getEvidence).mockResolvedValue({
+      inboundId: '2086085512165634051',
+      evidences: [
+        { id: '1', inboundId: '2086085512165634051', tenantId: '2086085512165634052', evidenceType: 'PHOTO_STEP_1', fileId: '11', fileName: 'empty-1.jpg', sealNo: null, remark: null, version: 0, status: 'ACTIVE', createdAt: null, updatedAt: null },
+        { id: '2', inboundId: '2086085512165634051', tenantId: '2086085512165634052', evidenceType: 'PHOTO_STEP_1', fileId: '12', fileName: 'empty-2.jpg', sealNo: null, remark: null, version: 0, status: 'ACTIVE', createdAt: null, updatedAt: null },
+      ],
+    })
+    const wrapper = mountPanel(['platform:firstleg:inbound:loading:view'], 'LOADED')
+    await flushPromises()
+
+    expect(getEvidence).toHaveBeenCalledWith('2086085512165634052', '2086085512165634051')
+    expect(wrapper.text()).toContain('empty-1.jpg')
+    expect(wrapper.text()).toContain('empty-2.jpg')
+    expect(wrapper.text()).toContain('2 张')
+    expect(wrapper.text()).not.toContain('完成装柜')
+    expect(wrapper.findAll('button').some((button) => button.text() === '作废')).toBe(false)
+  })
+
+  it('uses a validated dialog when voiding evidence', async () => {
+    vi.mocked(getEvidence).mockResolvedValue({
+      inboundId: '2086085512165634051',
+      evidences: [
+        { id: '1', inboundId: '2086085512165634051', tenantId: '2086085512165634052', evidenceType: 'PHOTO_STEP_1', fileId: '11', fileName: 'wrong.jpg', sealNo: null, remark: null, version: 2, status: 'ACTIVE', createdAt: null, updatedAt: null },
+      ],
+    })
+    vi.mocked(voidEvidence).mockResolvedValue({} as never)
+    const prompt = vi.spyOn(ElMessageBox, 'prompt').mockResolvedValue({ value: '照片上传错误' } as never)
+    const wrapper = mountPanel(['platform:firstleg:inbound:loading:view', 'platform:firstleg:inbound:loading:edit'], 'LOADING')
+    await flushPromises()
+
+    const voidButton = wrapper.findAll('button').find((button) => button.text() === '作废')
+    expect(voidButton).toBeTruthy()
+    await voidButton!.trigger('click')
+    await flushPromises()
+
+    expect(prompt).toHaveBeenCalledWith(
+      '作废后照片仍会保留在审计记录中。',
+      '作废证据照片',
+      expect.objectContaining({
+        inputType: 'textarea',
+        inputPlaceholder: '请输入作废原因',
+        type: 'warning',
+      }),
+    )
+    const options = prompt.mock.calls[0]?.[2]
+    expect(options?.inputValidator?.('   ')).toBe('作废原因不能为空')
+    expect(voidEvidence).toHaveBeenCalledWith(
+      '2086085512165634052',
+      '2086085512165634051',
+      '1',
+      { expectedVersion: 2, reason: '照片上传错误' },
+    )
+    prompt.mockRestore()
+  })
+
+  it('renders booking, trucking and picking backend statuses as business Chinese', async () => {
+    vi.mocked(getOutboundDispatch).mockResolvedValue({
+      orderId: '1', orderNo: 'ORD-1', inboundId: '2', inboundCode: 'IN-2', containerBookingId: '3', containerNo: 'CONT-3',
+      loadingPlanId: '4', loadingPlanStatus: 'LOADING', oceanBookingId: '5', oceanBookingStatus: 'RELEASED',
+      truckAppointmentId: '6', truckAppointmentStatus: 'PICKUP_IN_PROGRESS', gate: { passed: false, items: [] },
+    })
+    const wrapper = mountPanel(['platform:firstleg:inbound:picking:view'], 'LOADING')
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('已放舱')
+    expect(wrapper.text()).toContain('提柜中')
+    expect(wrapper.text()).toContain('拣货中')
+    expect(wrapper.text()).not.toContain('RELEASED')
+    expect(wrapper.text()).not.toContain('PICKUP_IN_PROGRESS')
+    expect(wrapper.text()).not.toContain('PICKING')
+  })
+
+  it('does not expose unknown backend enum values', async () => {
+    vi.mocked(getOutboundDispatch).mockResolvedValue({
+      orderId: '1', orderNo: 'ORD-1', inboundId: '2', inboundCode: 'IN-2', containerBookingId: null, containerNo: null,
+      loadingPlanId: null, loadingPlanStatus: null, oceanBookingId: '5', oceanBookingStatus: 'NEW_BOOKING_STATE',
+      truckAppointmentId: '6', truckAppointmentStatus: 'NEW_TRUCK_STATE', gate: { passed: false, items: [] },
+    })
+    vi.mocked(getPicking).mockResolvedValue({ id: '51', inboundId: '2', status: 'NEW_PICK_STATE', version: 2, expectedCount: null, pickedCount: null, remark: null })
+    const wrapper = mountPanel(['platform:firstleg:inbound:picking:view'], 'LOADING')
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('未知状态')
+    expect(wrapper.text()).not.toContain('NEW_BOOKING_STATE')
+    expect(wrapper.text()).not.toContain('NEW_TRUCK_STATE')
+    expect(wrapper.text()).not.toContain('NEW_PICK_STATE')
+  })
+})
diff --git a/src/modules/unified-orders/workflows/components/UnifiedOrderWorkflowPanel.vue b/src/modules/unified-orders/workflows/components/UnifiedOrderWorkflowPanel.vue
new file mode 100644
index 00000000..22099f6e
--- /dev/null
+++ b/src/modules/unified-orders/workflows/components/UnifiedOrderWorkflowPanel.vue
@@ -0,0 +1,598 @@
+<script setup lang="ts">
+import { computed, onMounted, ref, watch } from 'vue'
+import { ElMessageBox } from 'element-plus'
+import { RefreshCw, Save, Check, Play, Camera, Eye, Plus, Pencil, Trash2 } from '@lucide/vue'
+import { useRouter } from 'vue-router'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { ApiResponseError, getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import SmartLoadingWorkbench from '@/modules/unified-orders/workflows/components/SmartLoadingWorkbench.vue'
+import { oceanBookingStatusLabel } from '@/modules/ocean-bookings'
+import { truckAppointmentStatusLabel } from '@/modules/trucking'
+import { sanitizePreloadItem, validatePreloadItem, validatePreloadItems } from '@/modules/unified-orders/workflows/preloadForm'
+import {
+  completeLoading,
+  completePicking,
+  downloadEvidenceFile,
+  getEvidence,
+  getOutboundDispatch,
+  getPicking,
+  getPreload,
+  smartSplit,
+  startPicking,
+  upsertEvidence,
+  uploadEvidenceFile,
+  voidEvidence,
+  type Evidence,
+  type EvidenceType,
+  type PickingTask,
+  type PreloadItem,
+  type PreloadPlan,
+  type OutboundDispatchAggregate,
+} from '@/modules/unified-orders/workflows/api'
+import type { UnifiedOrderMainStatus } from '@/modules/unified-orders/api/unifiedOrders'
+
+const props = withDefaults(defineProps<{
+  tenantId: string
+  inboundId: string | number
+  inboundCode?: string | null
+  orderId?: string | number | null
+  mainStatus: UnifiedOrderMainStatus
+  inboundVersion?: number | null
+  pickingVersion?: number | null
+  readOnly?: boolean
+}>(), {
+  inboundVersion: null,
+  pickingVersion: null,
+  readOnly: false,
+})
+
+const emit = defineEmits<{ updated: [] }>()
+const access = useAccessPreviewStore()
+const router = useRouter()
+const preload = ref<PreloadPlan | null>(null)
+const preloadItems = ref<PreloadItem[]>([])
+const picking = ref<PickingTask | null>(null)
+const evidences = ref<Evidence[]>([])
+const dispatch = ref<OutboundDispatchAggregate | null>(null)
+const loadingRemark = ref('')
+const sealNoDraft = ref('')
+const splitRemark = ref('')
+const busy = ref('')
+const loading = ref(false)
+const error = ref('')
+const errorDetails = ref<ApiErrorDetails | null>(null)
+const preloadLoadError = ref<ApiErrorDetails | null>(null)
+const notice = ref('')
+const preloadDialogOpen = ref(false)
+const preloadDialogMode = ref<'create' | 'edit'>('create')
+const editingPreloadIndex = ref<number | null>(null)
+const preloadDraft = ref<PreloadItem>(itemTemplate())
+const preloadDraftError = ref('')
+
+const evidenceTypes: Array<{ type: EvidenceType; label: string }> = [
+  { type: 'PHOTO_STEP_1', label: '空仓照' },
+  { type: 'PHOTO_STEP_2', label: '半仓照' },
+  { type: 'PHOTO_STEP_3', label: '满仓照' },
+  { type: 'PHOTO_STEP_4', label: '锁仓照' },
+  { type: 'SEAL', label: '带锁码照' },
+]
+
+const isSplit = computed(() => props.mainStatus === 'WAIT_SPLIT')
+const isLoading = computed(() => props.mainStatus === 'LOADING')
+const isLoaded = computed(() => props.mainStatus === 'LOADED')
+const preloadVersion = computed(() => preload.value?.version ?? 0)
+const pickingExpectedVersion = computed(() => picking.value?.version ?? props.pickingVersion ?? null)
+const inboundExpectedVersion = computed(() => props.inboundVersion)
+const canSplit = computed(() => !props.readOnly && access.can('firstleg:inbound:split'))
+const canPreloadView = computed(() => access.can('firstleg:inbound:preload-view'))
+const canViewLoadingPlans = computed(() => access.can('platform:firstleg:preload:list'))
+const canPicking = computed(() => !props.readOnly && access.can('platform:firstleg:inbound:picking:edit'))
+const canPickingView = computed(() => access.can('platform:firstleg:inbound:picking:view'))
+// 操作员、理货员由 IAM 授予 loading:edit；拣货员仅能在 PDA 现场采集，不授予该权限。
+const canEvidence = computed(() => !props.readOnly && isLoading.value && access.can('platform:firstleg:inbound:loading:edit'))
+const canEvidenceView = computed(() => access.can('platform:firstleg:inbound:loading:view'))
+const canLoadingComplete = computed(() => !props.readOnly && !isLoaded.value && access.can('platform:firstleg:inbound:loading:complete'))
+const evidenceReady = computed(() => evidenceTypes.every(({ type }) => activeEvidences(type).some((item) => (
+  Boolean(item.fileId) && (type !== 'SEAL' || Boolean(item.sealNo?.trim()))
+))))
+
+const preloadColumns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 132, fixed: 'left', slotName: 'actions' },
+  { key: 'containerCode', prop: 'containerCode', label: '柜号', minWidth: 150 },
+  { key: 'cargoReference', prop: 'cargoReference', label: '货物引用', minWidth: 180 },
+  { key: 'packageCount', prop: 'packageCount', label: '箱数', width: 90 },
+  { key: 'volumeCbm', label: '体积(m³)', width: 110, slotName: 'volume' },
+  { key: 'remark', prop: 'remark', label: '备注', minWidth: 180, showOverflowTooltip: true },
+]
+
+function itemTemplate(): PreloadItem {
+  return { containerCode: '', cargoReference: '', packageCount: null, volumeCbm: 0, remark: '' }
+}
+
+function addItem() {
+  preloadDialogMode.value = 'create'
+  editingPreloadIndex.value = null
+  preloadDraft.value = itemTemplate()
+  preloadDraftError.value = ''
+  preloadDialogOpen.value = true
+}
+
+function editItem(index: number) {
+  preloadDialogMode.value = 'edit'
+  editingPreloadIndex.value = index
+  preloadDraft.value = { ...preloadItems.value[index] }
+  preloadDraftError.value = ''
+  preloadDialogOpen.value = true
+}
+
+function saveItem() {
+  const validation = validatePreloadItem(preloadDraft.value)
+  if (!validation.valid) {
+    preloadDraftError.value = validation.message
+    return
+  }
+  const next = sanitizePreloadItem(preloadDraft.value)
+  if (preloadDialogMode.value === 'edit' && editingPreloadIndex.value !== null) {
+    preloadItems.value.splice(editingPreloadIndex.value, 1, next)
+  } else {
+    preloadItems.value.push(next)
+  }
+  preloadDialogOpen.value = false
+}
+
+function removeItem(index: number) {
+  preloadItems.value.splice(index, 1)
+}
+
+function preloadStatusLabel(status?: string | null) {
+  return workflowStatusLabel(status, { PENDING: '待提交', CONFIRMING: '确认中', CONFIRMED: '已确认' }, '尚未生成')
+}
+
+function workflowStatusLabel(value: string | null | undefined, labels: Record<string, string>, emptyLabel: string) {
+  if (!value) return emptyLabel
+  return labels[value] || '未知状态'
+}
+
+function pickingStatusLabel(status?: string | null) {
+  return workflowStatusLabel(status, {
+    PENDING: '待拣货', PICKING: '拣货中', IN_PROGRESS: '拣货中', AWAITING_REVIEW: '待复核',
+    COMPLETED: '已完成', CANCELLED: '已取消',
+  }, '暂无数据')
+}
+
+function formatVolume(value: number | null) {
+  return value === null || !Number.isFinite(Number(value)) ? '—' : Number(value).toFixed(3)
+}
+
+function activeEvidences(type: EvidenceType) {
+  return evidences.value.filter((item) => item.evidenceType === type && item.status === 'ACTIVE')
+}
+
+function idempotentMessage(action: string) {
+  return busy.value === action ? '正在提交，请勿重复点击' : ''
+}
+
+function gateItemName(code: string, fallback: string) {
+  return code === 'LOADING_EVIDENCE_COMPLETE' ? '五类装柜证据与锁码完整' : fallback
+}
+
+async function run<T>(action: string, operation: () => Promise<T>, message: string, restoreAfterConflict?: () => void) {
+  busy.value = action
+  error.value = ''
+  errorDetails.value = null
+  notice.value = ''
+  try {
+    const result = await operation()
+    notice.value = message
+    emit('updated')
+    return result
+  } catch (cause) {
+    const details = getApiErrorDetails(cause, '操作失败，请重试')
+    error.value = details.message
+    errorDetails.value = details
+    if (details.code === 'A0409' || /版本|并发|已被其他人修改/.test(details.message)) {
+      await refresh()
+      restoreAfterConflict?.()
+      notice.value = '系统已刷新最新数据，请核对后重新提交'
+    }
+    return null
+  } finally {
+    busy.value = ''
+  }
+}
+
+async function loadPreload() {
+  if (!canPreloadView.value || !props.inboundId) return
+  loading.value = true
+  error.value = ''
+  errorDetails.value = null
+  preloadLoadError.value = null
+  try {
+    preload.value = await getPreload(props.tenantId, props.inboundId)
+    preloadItems.value = preload.value.items?.map((item) => ({ ...item })) || []
+  } catch (cause) {
+    preload.value = null
+    preloadItems.value = []
+    const missing = cause instanceof ApiResponseError
+      && (cause.status === 404 || cause.code === 'A0404' || cause.code === 'NOT_FOUND')
+    if (!missing) {
+      preloadLoadError.value = getApiErrorDetails(cause, '预装清单加载失败，请重试')
+    }
+  } finally {
+    loading.value = false
+  }
+}
+
+async function loadLoading() {
+  loading.value = true
+  error.value = ''
+  errorDetails.value = null
+  const messages: string[] = []
+  if (canPickingView.value) {
+    try {
+      picking.value = await getPicking(props.tenantId, props.inboundId)
+    } catch (cause) {
+      picking.value = null
+      const details = getApiErrorDetails(cause, '拣货任务加载失败')
+      messages.push(details.message)
+      errorDetails.value ||= details
+    }
+  }
+  if (canEvidenceView.value) {
+    try {
+      evidences.value = (await getEvidence(props.tenantId, props.inboundId)).evidences || []
+    } catch (cause) {
+      evidences.value = []
+      const details = getApiErrorDetails(cause, '装柜证据加载失败')
+      messages.push(details.message)
+      errorDetails.value ||= details
+    }
+  }
+  error.value = messages.join('；')
+  loading.value = false
+}
+
+async function loadDispatch() {
+  try {
+    dispatch.value = await getOutboundDispatch(props.tenantId, props.orderId || undefined, props.inboundId)
+  } catch {
+    dispatch.value = null
+  }
+}
+
+async function refresh() {
+  await loadDispatch()
+  if (isSplit.value) await loadPreload()
+  if (isLoading.value || isLoaded.value) await loadLoading()
+}
+
+async function runSmartSplit() {
+  const validation = validatePreloadItems(preloadItems.value)
+  if (!validation.valid) {
+    error.value = validation.message
+    errorDetails.value = null
+    return
+  }
+  const submittedItems = preloadItems.value.map((item) => sanitizePreloadItem(item))
+  const submittedRemark = splitRemark.value
+  const result = await run('smart-split', () => smartSplit(props.tenantId, props.inboundId, {
+    expectedVersion: preloadVersion.value,
+    items: submittedItems,
+    remark: submittedRemark.trim() || undefined,
+  }), '分柜清单已保存', () => {
+    preloadItems.value = submittedItems.map((item) => ({ ...item }))
+    splitRemark.value = submittedRemark
+  })
+  if (result) {
+    preload.value = result.preloadPlan
+    preloadItems.value = result.preloadPlan?.items?.map((item) => ({ ...item })) || []
+  }
+}
+
+function openPreloadPlans() {
+  void router.push({ name: 'loading-plans' })
+}
+
+function pickingRequest(): { expectedVersion: number; expectedCount: number; pickedCount: number; remark?: string } | null {
+  if (pickingExpectedVersion.value === null) {
+    error.value = '拣货版本缺失，请刷新订单详情后重试'
+    return null
+  }
+  return {
+    expectedVersion: pickingExpectedVersion.value,
+    expectedCount: picking.value?.expectedCount ?? 0,
+    pickedCount: picking.value?.pickedCount ?? 0,
+    remark: loadingRemark.value || undefined,
+  }
+}
+
+async function startPickingTask() {
+  const request = pickingRequest()
+  if (!request) return
+  const result = await run('picking-start', () => startPicking(props.tenantId, props.inboundId, request), '拣货任务已开始')
+  if (result) picking.value = result
+}
+
+async function completePickingTask() {
+  const request = pickingRequest()
+  if (!request) return
+  const result = await run('picking-complete', () => completePicking(props.tenantId, props.inboundId, request), '拣货已完成')
+  if (result) picking.value = result
+}
+
+async function uploadAndSaveEvidence(type: EvidenceType, event: Event) {
+  const input = event.target as HTMLInputElement
+  const file = input.files?.[0]
+  input.value = ''
+  if (!file || !canEvidence.value) return
+  const sealNo = sealNoDraft.value.trim()
+  if (type === 'SEAL' && !sealNo) {
+    error.value = '上传带锁码照前必须填写锁码'
+    errorDetails.value = null
+    return
+  }
+  const uploaded = await run(`evidence-upload-${type}`, () => uploadEvidenceFile(props.tenantId, props.inboundId, type, file), '文件已上传，正在登记证据')
+  if (!uploaded) return
+  const result = await run(`evidence-${type}`, () => upsertEvidence(props.tenantId, props.inboundId, {
+    expectedVersion: 0,
+    evidenceType: type,
+    fileId: uploaded.fileId,
+    sealNo: type === 'SEAL' ? sealNo : undefined,
+  }), `${type === 'SEAL' ? '带锁码照' : '证据'}已登记`)
+  if (result?.evidences) {
+    evidences.value = result.evidences.evidences || []
+    if (type === 'SEAL') sealNoDraft.value = ''
+  }
+}
+
+async function markEvidenceVoided(item: Evidence) {
+  if (!canEvidence.value || !item.id || String(item.id).startsWith('draft-')) return
+  let reason = ''
+  try {
+    const result = await ElMessageBox.prompt('作废后照片仍会保留在审计记录中。', '作废证据照片', {
+      inputType: 'textarea',
+      inputPlaceholder: '请输入作废原因',
+      inputValidator: (value) => Boolean(value?.trim()) || '作废原因不能为空',
+      confirmButtonText: '确认作废',
+      cancelButtonText: '取消',
+      type: 'warning',
+    })
+    reason = result.value.trim()
+  } catch (cause) {
+    if (cause === 'cancel' || cause === 'close') return
+    throw cause
+  }
+  const result = await run(`evidence-void-${item.id}`, () => voidEvidence(props.tenantId, props.inboundId, item.id, {
+    expectedVersion: item.version,
+    reason,
+  }), '证据已作废')
+  if (result?.evidences) evidences.value = result.evidences.evidences || []
+}
+
+async function previewEvidence(item: Evidence) {
+  if (!canEvidenceView.value || !item.fileId) return
+  busy.value = `evidence-preview-${item.id}`
+  error.value = ''
+  errorDetails.value = null
+  try {
+    const blob = await downloadEvidenceFile(props.tenantId, props.inboundId, item.fileId)
+    const url = URL.createObjectURL(blob)
+    window.open(url, '_blank', 'noopener,noreferrer')
+    window.setTimeout(() => URL.revokeObjectURL(url), 60_000)
+  } catch (cause) {
+    const details = getApiErrorDetails(cause, '证据照片加载失败，请重试')
+    error.value = details.message
+    errorDetails.value = details
+  } finally {
+    busy.value = ''
+  }
+}
+
+async function finishLoading() {
+  const expectedVersion = inboundExpectedVersion.value
+  if (expectedVersion === null) {
+    error.value = '入库单版本缺失，刷新订单详情后才能确认装柜完成'
+    return
+  }
+  const result = await run('loading-complete', () => completeLoading(props.tenantId, props.inboundId, {
+    expectedVersion,
+    remark: loadingRemark.value || undefined,
+  }), '装柜完成已提交')
+  if (result) await refresh()
+}
+
+watch(() => props.mainStatus, () => { void refresh() })
+onMounted(() => { void refresh() })
+</script>
+
+<template>
+  <section class="workflow-panel" aria-label="订单后半程作业">
+    <div class="workflow-heading" aria-label="订单作业上下文">
+      <div class="workflow-context"><span>入库作业</span><strong>{{ props.inboundCode || '入仓码待补充' }}</strong></div>
+      <el-tooltip content="刷新作业数据" placement="top"><el-button text :loading="loading" aria-label="刷新作业数据" @click="refresh"><RefreshCw :size="15" /></el-button></el-tooltip>
+    </div>
+
+    <el-alert v-if="error" class="workflow-alert" type="error" :closable="false" show-icon>
+      <template #title>{{ error }}</template>
+      <ApiErrorMeta v-if="errorDetails" :details="errorDetails" />
+      <el-button link type="danger" @click="refresh">重试</el-button>
+    </el-alert>
+    <el-alert v-if="notice" class="workflow-alert" type="success" :closable="false" show-icon>{{ notice }}</el-alert>
+    <el-alert v-if="busy" class="workflow-alert" type="info" :closable="false">{{ idempotentMessage(busy) }}</el-alert>
+    <el-alert v-if="props.readOnly" class="workflow-alert" type="info" :closable="false" show-icon>当前为只读查看，不能修改作业数据。</el-alert>
+
+    <el-card v-if="dispatch" shadow="never" class="workflow-card">
+      <template #header><div class="card-title"><span>子流程与门禁摘要</span><el-tag :type="dispatch.gate?.passed ? 'success' : 'warning'">{{ dispatch.gate?.passed ? '已通过' : '待补齐' }}</el-tag></div></template>
+      <div class="gate-grid">
+        <div><span>订舱</span><strong>{{ oceanBookingStatusLabel(dispatch.oceanBookingStatus, '未关联') }}</strong></div>
+        <div><span>拖车</span><strong>{{ truckAppointmentStatusLabel(dispatch.truckAppointmentStatus, '未关联') }}</strong></div>
+        <div><span>柜号</span><strong>{{ dispatch.containerNo || '暂无数据' }}</strong></div>
+        <div v-for="item in dispatch.gate?.items || []" :key="item.code"><span>{{ gateItemName(item.code, item.name) }}</span><el-tag size="small" :type="item.passed ? 'success' : 'danger'">{{ item.passed ? '已满足' : '待补齐' }}</el-tag></div>
+      </div>
+      <p class="workflow-hint">此处为订舱、拖车、PDA、报关、证据和船期的只读摘要；装柜完成仍以服务端 LOADED 门禁为准。</p>
+    </el-card>
+
+    <template v-if="isSplit">
+      <el-card shadow="never" class="workflow-card surface-panel table-panel">
+        <template #header><div class="card-title"><span>入库预装清单</span><el-tag>{{ preloadStatusLabel(preload?.status) }}</el-tag></div></template>
+        <el-alert v-if="!canPreloadView" type="warning" :closable="false" show-icon>当前账号无预装清单查询权限。</el-alert>
+        <LoadErrorState v-else-if="preloadLoadError" title="预装清单暂时无法加载" :message="preloadLoadError.message" :loading="loading" @retry="loadPreload">
+          <template #details><ApiErrorMeta :details="preloadLoadError" /></template>
+        </LoadErrorState>
+        <template v-else>
+          <DataTable :data="preloadItems" :columns="preloadColumns" :loading="loading" empty-text="暂无预装明细，请先新增">
+            <template #actions="{ $index }">
+              <el-button size="small" plain type="primary" :disabled="!canSplit || Boolean(busy)" :aria-label="`编辑第 ${Number($index) + 1} 条预装明细`" @click="editItem(Number($index))"><Pencil :size="14" />编辑</el-button>
+              <el-button size="small" plain type="danger" :disabled="!canSplit || Boolean(busy)" :aria-label="`删除第 ${Number($index) + 1} 条预装明细`" @click="removeItem(Number($index))"><Trash2 :size="14" />删除</el-button>
+            </template>
+            <template #volume="{ row }">{{ formatVolume((row as PreloadItem).volumeCbm) }}</template>
+            <template #toolbar-actions><el-button :disabled="!canSplit || Boolean(busy)" @click="addItem"><Plus :size="15" />新增明细</el-button></template>
+          </DataTable>
+          <el-input v-model="splitRemark" :disabled="!canSplit || Boolean(busy)" class="workflow-remark" type="textarea" :rows="2" maxlength="1000" show-word-limit aria-label="分柜备注" placeholder="分柜备注（可选）" />
+        </template>
+        <div class="workflow-actions">
+          <el-button :disabled="!canSplit || Boolean(busy) || Boolean(preloadLoadError)" :loading="busy === 'smart-split'" @click="runSmartSplit"><Save :size="15" />保存分柜清单</el-button>
+        </div>
+        <div class="preload-confirmation-guide">
+          <div><strong>计划级预装确认</strong><span>当前单票状态：{{ preloadStatusLabel(preload?.status) }}。请前往预装清单，从实际预装计划详情确认整份计划。</span></div>
+          <el-button v-if="canViewLoadingPlans" type="primary" plain @click="openPreloadPlans"><Eye :size="15" />前往预装清单</el-button>
+          <span v-else class="workflow-hint">当前账号无预装清单列表权限。</span>
+        </div>
+      </el-card>
+
+      <el-card v-if="dispatch?.containerBookingId" shadow="never" class="workflow-card">
+        <SmartLoadingWorkbench
+          :booking-id="String(dispatch.containerBookingId)"
+          :highlight-inbound-id="props.inboundId"
+          :read-only="props.readOnly"
+          @updated="refresh"
+        />
+      </el-card>
+      <el-alert v-else type="info" :closable="false" show-icon>
+        当前订单尚未关联柜次装柜计划；请先在货柜智能排柜工作台选择柜次并分配货物。
+      </el-alert>
+    </template>
+
+    <template v-if="isLoading">
+      <el-card shadow="never" class="workflow-card">
+        <template #header><div class="card-title"><span>拣货与装柜</span><el-tag type="warning">装柜中</el-tag></div></template>
+        <el-descriptions v-if="picking" :column="2" border>
+          <el-descriptions-item label="拣货状态">{{ pickingStatusLabel(picking.status) }}</el-descriptions-item>
+          <el-descriptions-item label="拣货版本">{{ picking.version }}</el-descriptions-item>
+          <el-descriptions-item label="应拣件数">{{ picking.expectedCount ?? '—' }}</el-descriptions-item>
+          <el-descriptions-item label="已拣件数">{{ picking.pickedCount ?? '—' }}</el-descriptions-item>
+        </el-descriptions>
+        <el-empty v-else-if="!loading" description="暂无拣货任务" />
+        <div class="workflow-actions">
+          <el-button :disabled="!canPicking || !picking || Boolean(busy)" :loading="busy === 'picking-start'" @click="startPickingTask"><Play :size="15" />开始拣货</el-button>
+          <el-button :disabled="!canPicking || !picking || Boolean(busy)" :loading="busy === 'picking-complete'" @click="completePickingTask"><Check :size="15" />完成拣货</el-button>
+        </div>
+        <el-input v-model="loadingRemark" :disabled="props.readOnly" class="workflow-remark" type="textarea" :rows="2" aria-label="装柜备注" placeholder="装柜备注（可选）" />
+      </el-card>
+
+    </template>
+
+    <el-card v-if="isLoading || isLoaded" v-loading="loading" shadow="never" class="workflow-card">
+        <template #header><div class="card-title"><span>装柜五类证据与锁码</span><el-tag :type="evidenceReady ? 'success' : 'info'">{{ evidenceReady ? '证据齐全' : '五类必传' }}</el-tag></div></template>
+        <el-alert v-if="!canEvidenceView" type="warning" :closable="false" show-icon>当前账号无装柜证据查询权限。</el-alert>
+        <div class="evidence-grid">
+          <div v-for="entry in evidenceTypes" :key="entry.type" class="evidence-item">
+            <strong><Camera :size="15" />{{ entry.label }}<el-tag size="small" :type="activeEvidences(entry.type).length ? 'success' : 'danger'">{{ activeEvidences(entry.type).length }} 张</el-tag></strong>
+            <div class="evidence-control">
+              <el-input v-if="entry.type === 'SEAL' && canEvidence" v-model="sealNoDraft" maxlength="64" show-word-limit aria-label="下一张照片的锁码" placeholder="先填写锁码，再上传带锁码照" />
+              <label v-if="canEvidence" class="file-picker"><Camera :size="14" />追加照片<input type="file" accept="image/*" @change="uploadAndSaveEvidence(entry.type, $event)" /></label>
+            </div>
+            <div v-if="canEvidenceView" class="evidence-files">
+              <div v-for="item in activeEvidences(entry.type)" :key="String(item.id)" class="evidence-file">
+                <span>{{ item.fileName || '证据文件名待补充' }}<template v-if="item.sealNo"> · 锁码 {{ item.sealNo }}</template></span>
+                <div class="evidence-file__actions">
+                  <el-button size="small" plain type="primary" :disabled="Boolean(busy)" @click="previewEvidence(item)"><Eye :size="14" />查看</el-button>
+                  <el-button v-if="canEvidence" size="small" plain type="danger" :disabled="Boolean(busy)" @click="markEvidenceVoided(item)"><Trash2 :size="14" />作废</el-button>
+                </div>
+              </div>
+              <span v-if="activeEvidences(entry.type).length === 0" class="workflow-hint">尚未上传有效照片</span>
+            </div>
+          </div>
+        </div>
+        <p class="workflow-hint">五类证据各至少一张有效照片；锁码文本与带锁码照同时必填。错误照片只能作废并保留审计记录。</p>
+        <div v-if="isLoading" class="workflow-actions">
+          <el-button type="primary" :disabled="!canLoadingComplete || !evidenceReady || inboundExpectedVersion === null || Boolean(busy)" :loading="busy === 'loading-complete'" @click="finishLoading"><Check :size="15" />完成装柜</el-button>
+          <span v-if="!evidenceReady" class="workflow-hint">五类有效照片及锁码齐全后可提交；其他门禁仍由服务端校验</span>
+          <span v-if="inboundExpectedVersion === null" class="workflow-hint">缺少入库版本，刷新订单详情后可提交</span>
+        </div>
+    </el-card>
+
+    <el-alert v-if="isLoaded" class="workflow-alert" type="success" :closable="false" show-icon>
+      已装柜完成。国内端不提供在线冲正、回退或推进派送完成，后续状态仅接受海外/尾程可信回传。
+    </el-alert>
+
+    <AppDialog
+      v-model="preloadDialogOpen"
+      :title="preloadDialogMode === 'create' ? '新增预装明细' : '编辑预装明细'"
+      confirm-text="保存明细"
+      :confirm-disabled="Boolean(busy)"
+      @confirm="saveItem"
+    >
+      <el-form label-position="top" @submit.prevent>
+        <el-form-item label="柜号" required :error="preloadDraftError === '柜号不能为空' ? preloadDraftError : ''">
+          <el-input v-model="preloadDraft.containerCode" maxlength="64" placeholder="请输入柜号" @input="preloadDraftError = ''" />
+        </el-form-item>
+        <el-form-item label="货物引用" required :error="preloadDraftError === '货物引用不能为空' ? preloadDraftError : ''">
+          <el-input v-model="preloadDraft.cargoReference" maxlength="128" placeholder="入仓码或业务引用" @input="preloadDraftError = ''" />
+        </el-form-item>
+        <div class="preload-dialog-grid">
+          <el-form-item label="箱数" required><el-input-number v-model="preloadDraft.packageCount" :min="1" :step="1" step-strictly controls-position="right" @change="preloadDraftError = ''" placeholder="请输入计划装柜箱数" /></el-form-item>
+          <el-form-item label="体积(m³)"><el-input-number v-model="preloadDraft.volumeCbm" :min="0" :precision="3" controls-position="right" @change="preloadDraftError = ''" placeholder="请输入计划体积（选填）" /></el-form-item>
+        </div>
+        <el-form-item label="明细备注"><el-input v-model="preloadDraft.remark" type="textarea" :rows="3" maxlength="500" show-word-limit placeholder="请输入明细备注（选填）" /></el-form-item>
+        <el-alert v-if="preloadDraftError" type="error" :closable="false" show-icon>{{ preloadDraftError }}</el-alert>
+      </el-form>
+    </AppDialog>
+  </section>
+</template>
+
+<style scoped>
+.workflow-panel { display: grid; gap: 14px; }
+.workflow-heading, .card-title, .workflow-actions { display: flex; align-items: center; gap: 10px; flex-wrap: wrap; }
+.workflow-heading { justify-content: space-between; }
+.workflow-context { display: grid; min-width: 0; gap: 3px; }
+.workflow-context span { color: var(--cc-text-secondary, #64748b); font-size: 11px; }
+.workflow-context strong { overflow: hidden; color: var(--cc-text, #1f2937); font-size: 14px; text-overflow: ellipsis; white-space: nowrap; }
+.workflow-card { border-radius: 12px; }
+.card-title { justify-content: space-between; }
+.preload-dialog-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 14px; }
+.workflow-actions { margin-top: 14px; }
+.workflow-remark { margin-top: 10px; }
+.preload-confirmation-guide { display: flex; align-items: center; justify-content: space-between; gap: 12px; margin-top: 12px; padding: 12px 14px; border: 1px solid var(--cc-border); border-radius: 6px; background: #f8fafc; }
+.preload-confirmation-guide > div { display: grid; min-width: 0; gap: 4px; }
+.preload-confirmation-guide strong { color: var(--cc-text, #1f2937); font-size: 13px; }
+.preload-confirmation-guide span { color: var(--cc-text-secondary, #64748b); font-size: 12px; line-height: 1.5; }
+.preload-confirmation-guide > .el-button { flex: 0 0 auto; }
+.evidence-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 12px; }
+.evidence-item { display: grid; min-width: 0; gap: 8px; align-content: start; padding: 12px; border: 1px solid var(--cc-border); border-radius: 6px; }
+.evidence-item strong { display: inline-flex; align-items: center; gap: 5px; white-space: nowrap; }
+.evidence-control { display: flex; min-width: 0; align-items: center; gap: 8px; }
+.evidence-files { display: grid; gap: 4px; }
+.evidence-file { display: flex; min-width: 0; align-items: center; justify-content: space-between; gap: 8px; color: var(--cc-text-secondary, #64748b); font-size: 12px; }
+.evidence-file span { min-width: 0; overflow-wrap: anywhere; }
+.evidence-file__actions { display: flex; flex: 0 0 auto; align-items: center; gap: 4px; }
+.gate-grid { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 8px; }
+.gate-grid > div { display: flex; min-height: 34px; align-items: center; justify-content: space-between; gap: 8px; padding: 7px 9px; border: 1px solid var(--cc-border); border-radius: 5px; }
+.gate-grid span { color: var(--cc-text-secondary, #64748b); font-size: 12px; }
+.gate-grid strong { color: var(--cc-text, #1f2937); font-size: 12px; }
+.file-picker { display: inline-flex; align-items: center; gap: 4px; color: var(--cc-primary); font-size: 12px; cursor: pointer; white-space: nowrap; }
+.file-picker input { display: none; }
+.workflow-alert { margin-bottom: 0; }
+.workflow-hint { color: var(--cc-text-secondary, #64748b); font-size: 12px; }
+@media (max-width: 640px) {
+  .preload-dialog-grid, .evidence-grid { grid-template-columns: 1fr; }
+  .preload-dialog-grid { gap: 0; }
+  .preload-confirmation-guide { align-items: stretch; flex-direction: column; }
+  .evidence-item, .gate-grid { grid-template-columns: 1fr; }
+  .workflow-actions > .el-button { flex: 1 1 150px; }
+}
+</style>
diff --git a/src/modules/unified-orders/workflows/index.ts b/src/modules/unified-orders/workflows/index.ts
new file mode 100644
index 00000000..91c3317e
--- /dev/null
+++ b/src/modules/unified-orders/workflows/index.ts
@@ -0,0 +1,3 @@
+export { default as UnifiedOrderWorkflowPanel } from './components/UnifiedOrderWorkflowPanel.vue'
+export { default as UnifiedOrderWorkflowView } from './pages/UnifiedOrderWorkflowView.vue'
+export * from './api'
diff --git a/src/modules/unified-orders/workflows/pages/UnifiedOrderWorkflowView.vue b/src/modules/unified-orders/workflows/pages/UnifiedOrderWorkflowView.vue
new file mode 100644
index 00000000..cf3139db
--- /dev/null
+++ b/src/modules/unified-orders/workflows/pages/UnifiedOrderWorkflowView.vue
@@ -0,0 +1,65 @@
+<script setup lang="ts">
+import { computed, onMounted, ref } from 'vue'
+import { useRoute } from 'vue-router'
+import { getPlatformUnifiedOrder, type UnifiedOrderDetailResource } from '@/modules/unified-orders/api/unifiedOrders'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import UnifiedOrderWorkflowPanel from '@/modules/unified-orders/workflows/components/UnifiedOrderWorkflowPanel.vue'
+
+const route = useRoute()
+const detail = ref<UnifiedOrderDetailResource | null>(null)
+const loading = ref(false)
+const error = ref<ApiErrorDetails | null>(null)
+
+const orderId = computed(() => String(route.params.orderId || ''))
+const tenantId = computed(() => typeof route.query.tenantId === 'string' ? route.query.tenantId : '')
+const summary = computed(() => detail.value?.summary || null)
+
+async function load() {
+  if (!orderId.value || !tenantId.value) {
+    error.value = { message: '订单作业上下文不完整' }
+    return
+  }
+  loading.value = true
+  error.value = null
+  try {
+    detail.value = await getPlatformUnifiedOrder(tenantId.value, orderId.value)
+  } catch (cause) {
+    detail.value = null
+    error.value = getApiErrorDetails(cause, '订单作业上下文加载失败')
+  } finally {
+    loading.value = false
+  }
+}
+
+onMounted(() => { void load() })
+</script>
+
+<template>
+  <AdminPage>
+  <section class="workflow-page">
+    <LoadErrorState v-if="error" title="后半程作业暂时无法加载" :message="error.message" :loading="loading" @retry="load">
+      <template #details><ApiErrorMeta :details="error" /></template>
+    </LoadErrorState>
+    <UnifiedOrderWorkflowPanel
+      v-else-if="summary && summary.inboundId"
+      :tenant-id="tenantId"
+      :inbound-id="summary.inboundId"
+      :inbound-code="summary.inboundCode"
+      :order-id="summary.orderId"
+      :main-status="summary.mainStatus"
+      :inbound-version="summary.inboundVersion"
+      :picking-version="summary.loading?.pickingVersion"
+      @updated="load"
+    />
+    <el-empty v-else-if="!loading" description="该订单尚未生成入库作业，暂无后半程操作" />
+    <el-skeleton v-else :rows="5" animated />
+  </section>
+  </AdminPage>
+</template>
+
+<style scoped>
+.workflow-page { display: grid; gap: 16px; }
+</style>
diff --git a/src/modules/unified-orders/workflows/preloadForm.test.ts b/src/modules/unified-orders/workflows/preloadForm.test.ts
new file mode 100644
index 00000000..c9330022
--- /dev/null
+++ b/src/modules/unified-orders/workflows/preloadForm.test.ts
@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest'
+import { sanitizePreloadItem, validatePreloadItem, validatePreloadItems } from './preloadForm'
+
+describe('preload form contract', () => {
+  it('requires a meaningful row before submitting the real smart-split endpoint', () => {
+    expect(validatePreloadItems([])).toEqual({ valid: false, message: '请至少添加一条预装明细' })
+    expect(validatePreloadItem({ containerCode: '', cargoReference: 'SKU-1', packageCount: 1, volumeCbm: 0, remark: null }).message)
+      .toBe('柜号不能为空')
+    expect(validatePreloadItem({ containerCode: 'C-1', cargoReference: '', packageCount: 1, volumeCbm: 0, remark: null }).message)
+      .toBe('货物引用不能为空')
+    expect(validatePreloadItem({ containerCode: 'C-1', cargoReference: 'SKU-1', packageCount: 1.5, volumeCbm: 0, remark: null }).message)
+      .toBe('箱数必须为大于 0 的整数')
+  })
+
+  it('normalizes whitespace and numeric values without changing identifier strings', () => {
+    expect(sanitizePreloadItem({
+      containerCode: ' 2086085512165634050 ', cargoReference: ' REF-1 ', packageCount: 2, volumeCbm: 1.25, remark: ' note ',
+    })).toEqual({
+      containerCode: '2086085512165634050', cargoReference: 'REF-1', packageCount: 2, volumeCbm: 1.25, remark: 'note',
+    })
+  })
+})
diff --git a/src/modules/unified-orders/workflows/preloadForm.ts b/src/modules/unified-orders/workflows/preloadForm.ts
new file mode 100644
index 00000000..a6f27e43
--- /dev/null
+++ b/src/modules/unified-orders/workflows/preloadForm.ts
@@ -0,0 +1,38 @@
+import type { PreloadItem } from './api'
+
+export interface PreloadItemValidation {
+  valid: boolean
+  message: string
+}
+
+export function validatePreloadItem(item: PreloadItem): PreloadItemValidation {
+  if (!item.containerCode?.trim()) return { valid: false, message: '柜号不能为空' }
+  if (!item.cargoReference?.trim()) return { valid: false, message: '货物引用不能为空' }
+  if (!Number.isInteger(item.packageCount) || Number(item.packageCount) <= 0) {
+    return { valid: false, message: '箱数必须为大于 0 的整数' }
+  }
+  if (item.volumeCbm !== null && (!Number.isFinite(Number(item.volumeCbm)) || Number(item.volumeCbm) < 0)) {
+    return { valid: false, message: '体积不能小于 0' }
+  }
+  if ((item.remark?.length || 0) > 500) return { valid: false, message: '明细备注不能超过 500 个字符' }
+  return { valid: true, message: '' }
+}
+
+export function validatePreloadItems(items: PreloadItem[]): PreloadItemValidation {
+  if (!items.length) return { valid: false, message: '请至少添加一条预装明细' }
+  for (let index = 0; index < items.length; index += 1) {
+    const result = validatePreloadItem(items[index])
+    if (!result.valid) return { valid: false, message: `第 ${index + 1} 条：${result.message}` }
+  }
+  return { valid: true, message: '' }
+}
+
+export function sanitizePreloadItem(item: PreloadItem): PreloadItem {
+  return {
+    containerCode: item.containerCode?.trim() || null,
+    cargoReference: item.cargoReference?.trim() || null,
+    packageCount: Number(item.packageCount),
+    volumeCbm: item.volumeCbm === null ? 0 : Number(item.volumeCbm),
+    remark: item.remark?.trim() || null,
+  }
+}
diff --git a/src/modules/warehouse-resources/locations/api/platformLocations.test.ts b/src/modules/warehouse-resources/locations/api/platformLocations.test.ts
new file mode 100644
index 00000000..84b03eee
--- /dev/null
+++ b/src/modules/warehouse-resources/locations/api/platformLocations.test.ts
@@ -0,0 +1,110 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import {
+  changePlatformLocationStatus,
+  createPlatformLocation,
+  deletePlatformLocation,
+  getPlatformLocation,
+  listPlatformLocations,
+  updatePlatformLocation,
+  type SavePlatformLocationRequest,
+} from './platformLocations'
+
+vi.mock('@/shared/api/http', () => ({
+  http: { get: vi.fn(), post: vi.fn(), put: vi.fn(), patch: vi.fn(), delete: vi.fn() },
+  unwrapApiResponse: <T>(response: { data: T }) => response.data,
+}))
+
+const payload: SavePlatformLocationRequest = {
+  warehouseId: '190000000000000101',
+  zoneCode: 'A',
+  zoneName: '常规区',
+  locationCode: 'A1-01',
+  locationName: 'A1 区 01 位',
+  locationType: 'SHELF',
+  maxWeightKg: 500,
+  status: 'AVAILABLE',
+  remark: null,
+  version: 3,
+}
+
+describe('platform location API', () => {
+  beforeEach(() => {
+    vi.mocked(http.get).mockReset()
+    vi.mocked(http.post).mockReset()
+    vi.mocked(http.put).mockReset()
+    vi.mocked(http.patch).mockReset()
+    vi.mocked(http.delete).mockReset()
+  })
+
+  it('uses the implemented paged list and detail contracts', async () => {
+    const page = { records: [], page: '2', size: '20', total: '21', pages: '2' }
+    const detail = { location: { id: '19001' }, warehouseCode: 'CN-YW-01', warehouseName: '义乌仓' }
+    vi.mocked(http.get)
+      .mockResolvedValueOnce({ code: '200', message: 'success', data: page })
+      .mockResolvedValueOnce({ code: '200', message: 'success', data: detail })
+
+    await expect(listPlatformLocations({
+      page: 2,
+      size: 20,
+      warehouseId: '190000000000000101',
+      zoneCode: ' A ',
+      locationCode: ' A1 ',
+      locationType: 'SHELF',
+      status: 'AVAILABLE',
+    })).resolves.toEqual({ records: [], page: 2, size: 20, total: 21, pages: 2 })
+    await expect(getPlatformLocation('190000000000000101', '19001')).resolves.toEqual(detail)
+
+    expect(http.get).toHaveBeenNthCalledWith(1, '/platform/v1/locations', {
+      params: {
+        page: 2, size: 20, warehouseId: '190000000000000101',
+        zoneCode: 'A', locationCode: 'A1', locationType: 'SHELF', status: 'AVAILABLE',
+      },
+    })
+    expect(http.get).toHaveBeenNthCalledWith(2, '/platform/v1/locations/19001', {
+      params: { tenantId: 0, warehouseId: '190000000000000101' },
+    })
+  })
+
+  it('omits empty customer, warehouse, and filter values from all-customer list requests', async () => {
+    const page = { records: [], page: 1, size: 20, total: 0, pages: 0 }
+    vi.mocked(http.get).mockResolvedValue({ code: '200', message: 'success', data: page })
+
+    await expect(listPlatformLocations({
+      page: 1,
+      size: 20,
+      warehouseId: '',
+      zoneCode: '',
+      locationCode: '',
+      locationType: '',
+      status: '',
+    })).resolves.toEqual(page)
+
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/locations', {
+      params: { page: 1, size: 20 },
+    })
+  })
+
+  it('sends versioned create, update, status, and delete requests', async () => {
+    vi.mocked(http.post).mockResolvedValue({ code: '200', message: 'success', data: '19001' })
+    vi.mocked(http.put).mockResolvedValue({ code: '200', message: 'success', data: null })
+    vi.mocked(http.patch).mockResolvedValue({ code: '200', message: 'success', data: null })
+    vi.mocked(http.delete).mockResolvedValue({ code: '200', message: 'success', data: null })
+
+    await expect(createPlatformLocation(payload)).resolves.toBe('19001')
+    await expect(updatePlatformLocation(payload.warehouseId, '19001', payload)).resolves.toBeNull()
+    await expect(changePlatformLocationStatus(payload.warehouseId, '19001', 'DISABLED', 3)).resolves.toBeNull()
+    await expect(deletePlatformLocation(payload.warehouseId, '19001', 4)).resolves.toBeNull()
+
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/locations', payload, { params: { tenantId: 0 } })
+    expect(http.put).toHaveBeenCalledWith('/platform/v1/locations/19001', payload, {
+      params: { tenantId: 0, warehouseId: payload.warehouseId },
+    })
+    expect(http.patch).toHaveBeenCalledWith('/platform/v1/locations/19001/status', { status: 'DISABLED', version: 3 }, {
+      params: { tenantId: 0, warehouseId: payload.warehouseId },
+    })
+    expect(http.delete).toHaveBeenCalledWith('/platform/v1/locations/19001', {
+      params: { tenantId: 0, warehouseId: payload.warehouseId, version: 4 },
+    })
+  })
+})
diff --git a/src/modules/warehouse-resources/locations/api/platformLocations.ts b/src/modules/warehouse-resources/locations/api/platformLocations.ts
new file mode 100644
index 00000000..d898511d
--- /dev/null
+++ b/src/modules/warehouse-resources/locations/api/platformLocations.ts
@@ -0,0 +1,143 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+
+export type PlatformLocationStatus = 'AVAILABLE' | 'RESERVED' | 'OCCUPIED' | 'DISABLED'
+export type EditablePlatformLocationStatus = 'AVAILABLE' | 'DISABLED'
+export type PlatformLocationType = 'SHELF' | 'PALLET' | 'FLOOR' | 'FLOW_RACK'
+
+export interface PlatformLocationResource {
+  id: number | string
+  tenantId: number | string
+  warehouseId: number | string
+  warehouseCode?: string | null
+  warehouseName?: string | null
+  zoneCode: string
+  zoneName: string
+  locationCode: string
+  locationName: string | null
+  locationType: PlatformLocationType
+  maxWeightKg: number | string | null
+  sharedOverflow: boolean | null
+  status: PlatformLocationStatus
+  remark: string | null
+  version: number
+  createdAt?: string | null
+  updatedAt?: string | null
+}
+
+export interface PlatformLocationDetail {
+  location: PlatformLocationResource
+  warehouseCode: string
+  warehouseName: string
+}
+
+export interface PlatformLocationPage {
+  records: PlatformLocationResource[]
+  page: number
+  size: number
+  total: number
+  pages: number
+}
+
+export interface PlatformLocationQuery {
+  page?: number
+  size?: number
+  warehouseId?: number | string
+  zoneCode?: string
+  locationCode?: string
+  locationType?: PlatformLocationType | ''
+  status?: PlatformLocationStatus | ''
+}
+
+export interface SavePlatformLocationRequest {
+  warehouseId: number | string
+  zoneCode: string
+  zoneName: string
+  locationCode: string
+  locationName: string | null
+  locationType: PlatformLocationType
+  maxWeightKg: number | null
+  status: EditablePlatformLocationStatus
+  remark: string | null
+  version?: number
+}
+
+const basePath = '/platform/v1/locations'
+const platformResourceScope = 0
+
+export async function listPlatformLocations(query: PlatformLocationQuery) {
+  const zoneCode = query.zoneCode?.trim()
+  const locationCode = query.locationCode?.trim()
+  const response = await http.get<ApiEnvelope<PlatformLocationPage>, ApiEnvelope<PlatformLocationPage>>(basePath, {
+    params: {
+      page: query.page ?? 1,
+      size: query.size ?? 20,
+      ...(query.warehouseId ? { warehouseId: query.warehouseId } : {}),
+      ...(zoneCode ? { zoneCode } : {}),
+      ...(locationCode ? { locationCode } : {}),
+      ...(query.locationType ? { locationType: query.locationType } : {}),
+      ...(query.status ? { status: query.status } : {}),
+    },
+  })
+  const result = unwrapApiResponse(response)
+  return {
+    ...result,
+    page: Number(result.page),
+    size: Number(result.size),
+    total: Number(result.total),
+    pages: Number(result.pages),
+  }
+}
+
+export async function getPlatformLocation(
+  warehouseId: number | string,
+  id: number | string,
+) {
+  const response = await http.get<ApiEnvelope<PlatformLocationDetail>, ApiEnvelope<PlatformLocationDetail>>(
+    `${basePath}/${id}`,
+    { params: { tenantId: platformResourceScope, warehouseId } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function createPlatformLocation(payload: SavePlatformLocationRequest) {
+  const response = await http.post<ApiEnvelope<number | string>, ApiEnvelope<number | string>>(basePath, payload, {
+    params: { tenantId: platformResourceScope },
+  })
+  return unwrapApiResponse(response)
+}
+
+export async function updatePlatformLocation(
+  warehouseId: number | string,
+  id: number | string,
+  payload: SavePlatformLocationRequest,
+) {
+  const response = await http.put<ApiEnvelope<null>, ApiEnvelope<null>>(`${basePath}/${id}`, payload, {
+    params: { tenantId: platformResourceScope, warehouseId },
+  })
+  return unwrapApiResponse(response)
+}
+
+export async function changePlatformLocationStatus(
+  warehouseId: number | string,
+  id: number | string,
+  status: EditablePlatformLocationStatus,
+  version: number,
+) {
+  const response = await http.patch<ApiEnvelope<null>, ApiEnvelope<null>>(
+    `${basePath}/${id}/status`,
+    { status, version },
+    { params: { tenantId: platformResourceScope, warehouseId } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function deletePlatformLocation(
+  warehouseId: number | string,
+  id: number | string,
+  version: number,
+) {
+  const response = await http.delete<ApiEnvelope<null>, ApiEnvelope<null>>(`${basePath}/${id}`, {
+    params: { tenantId: platformResourceScope, warehouseId, version },
+  })
+  return unwrapApiResponse(response)
+}
diff --git a/src/modules/warehouse-resources/locations/pages/LocationsView.test.ts b/src/modules/warehouse-resources/locations/pages/LocationsView.test.ts
new file mode 100644
index 00000000..93d546d6
--- /dev/null
+++ b/src/modules/warehouse-resources/locations/pages/LocationsView.test.ts
@@ -0,0 +1,411 @@
+import ElementPlus from 'element-plus'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { createPinia, setActivePinia } from 'pinia'
+import { enableAutoUnmount, flushPromises, mount, type VueWrapper } from '@vue/test-utils'
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+import {
+  createPlatformLocation,
+  getPlatformLocation,
+  listPlatformLocations,
+  type PlatformLocationResource,
+} from '../api/platformLocations'
+import { listAllPlatformWarehouses, type PlatformWarehouseResource } from '../../../warehouses/api/platformWarehouses'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import DataTable from '@/shared/components/DataTable.vue'
+import LocationsView from './LocationsView.vue'
+
+const locationsSource = readFileSync(resolve(process.cwd(), 'src/modules/warehouse-resources/locations/pages/LocationsView.vue'), 'utf8')
+
+vi.mock('../../../warehouses/api/platformWarehouses', () => ({ listAllPlatformWarehouses: vi.fn() }))
+vi.mock('../api/platformLocations', () => ({
+  listPlatformLocations: vi.fn(),
+  getPlatformLocation: vi.fn(),
+  createPlatformLocation: vi.fn(),
+  updatePlatformLocation: vi.fn(),
+  changePlatformLocationStatus: vi.fn(),
+  deletePlatformLocation: vi.fn(),
+}))
+
+class ResizeObserverStub implements ResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+
+function createMemoryStorage(): Storage {
+  const values = new Map<string, string>()
+  return {
+    get length() { return values.size },
+    clear: () => values.clear(),
+    getItem: (key) => values.get(key) ?? null,
+    key: (index) => [...values.keys()][index] ?? null,
+    removeItem: (key) => values.delete(key),
+    setItem: (key, value) => values.set(key, value),
+  }
+}
+
+const tenantId = '0'
+const warehouseId = '9223372036854775805'
+const warehouse: PlatformWarehouseResource = {
+  id: warehouseId,
+  tenantId,
+  warehouseCode: 'CN-YW-01',
+  internalCode: null,
+  warehouseName: '义乌收货仓',
+  warehouseType: 'DOMESTIC',
+  countryCode: 'CN',
+  timezone: 'Asia/Shanghai',
+  contactName: null,
+  contactPhone: null,
+  contactEmail: null,
+  status: 'ACTIVE',
+  remark: null,
+}
+
+const fbaWarehouse: PlatformWarehouseResource = {
+  ...warehouse,
+  id: '9223372036854775802',
+  warehouseCode: 'FBA-ONT8',
+  internalCode: '154',
+  warehouseName: 'ONT8 FBA 仓',
+  warehouseType: 'FBA',
+}
+
+const overseasWarehouse: PlatformWarehouseResource = {
+  ...warehouse,
+  id: '9223372036854775801',
+  warehouseCode: 'US-LAX-01',
+  internalCode: null,
+  warehouseName: '洛杉矶海外仓',
+  warehouseType: 'OVERSEAS',
+}
+
+const availableLocation: PlatformLocationResource = {
+  id: '9223372036854775804',
+  tenantId,
+  warehouseId,
+  zoneCode: 'A',
+  zoneName: '常规区',
+  locationCode: 'A1-01',
+  locationName: 'A1 区 01 位',
+  locationType: 'SHELF',
+  maxWeightKg: '500.000',
+  sharedOverflow: false,
+  status: 'AVAILABLE',
+  remark: '靠近入库口',
+  version: 3,
+  updatedAt: '2026-08-04T10:20:00',
+}
+
+const occupiedLocation: PlatformLocationResource = {
+  ...availableLocation,
+  id: '9223372036854775803',
+  locationCode: 'A1-02',
+  locationName: 'A1 区 02 位',
+  status: 'OCCUPIED',
+  version: 5,
+}
+
+async function mountView(permissions = [
+  'platform:location:list',
+  'platform:location:create',
+  'platform:location:edit',
+  'platform:location:status',
+  'platform:location:delete',
+]) {
+  vi.stubGlobal('localStorage', createMemoryStorage())
+  vi.stubGlobal('sessionStorage', createMemoryStorage())
+  const pinia = createPinia()
+  setActivePinia(pinia)
+  const auth = useAuthStore()
+  auth.token = 'token'
+  auth.permissions = permissions
+  useAccessPreviewStore().initializeAfterLogin()
+  const wrapper = mount(LocationsView, {
+    attachTo: document.body,
+    global: { plugins: [pinia, ElementPlus] },
+  })
+  await flushPromises()
+  return wrapper
+}
+
+async function selectScope(wrapper: VueWrapper) {
+  const toolbar = wrapper.findComponent(QueryToolbar)
+  toolbar.vm.$emit('update:modelValue', { ...(toolbar.props('modelValue') as QueryModel), warehouseId })
+  await flushPromises()
+  const searchButton = toolbar.findAll('button').find((button) => button.text().trim() === '查询')
+  await searchButton!.trigger('click')
+  await flushPromises()
+}
+
+enableAutoUnmount(afterEach)
+afterAll(() => vi.unstubAllGlobals())
+
+const densitySource = readFileSync(resolve(process.cwd(), 'src/styles/adminDensity.css'), 'utf8')
+
+describe('LocationsView', () => {
+  it('uses bordered striped tables and explicit semantic row actions', () => {
+    expect(locationsSource).toContain('border')
+    expect(locationsSource).toContain('stripe')
+    expect(locationsSource).toMatch(/size="small"\s+class="density-action"/)
+    expect(locationsSource).toContain(':data-tone="(row as PlatformLocationResource).status === \'AVAILABLE\' ? \'danger\' : \'success\'"')
+    expect(locationsSource).toContain('class="density-action" data-tone="danger"')
+    expect(locationsSource).not.toContain('<Eye :size="15" />')
+    expect(locationsSource).not.toContain('<Pencil :size="15" />')
+    expect(locationsSource).not.toContain('<Power :size="15" />')
+    expect(locationsSource).not.toContain('<Trash2 :size="15" />')
+    expect(locationsSource).toContain('@media (max-width: 720px)')
+  })
+  it('uses the prototype-sized centered editor without a detail drawer or section cards', () => {
+    expect(locationsSource).not.toContain('AppDrawer')
+    expect(locationsSource).not.toContain('FormSection')
+    expect(locationsSource).toContain('width="min(560px, calc(100vw - 28px))"')
+    expect(densitySource).toContain('.admin-density-dialog.el-dialog .el-dialog__body { min-height: 0; overflow-y: auto;')
+    expect(locationsSource).toContain('.editor-field-grid { grid-template-columns: minmax(0, 1fr); }')
+  })
+  beforeEach(() => {
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+    document.body.innerHTML = ''
+    vi.mocked(listAllPlatformWarehouses).mockReset().mockResolvedValue([warehouse, fbaWarehouse, overseasWarehouse])
+    vi.mocked(listPlatformLocations).mockReset().mockResolvedValue({
+      records: [availableLocation, occupiedLocation], page: 1, size: 20, total: 2, pages: 1,
+    })
+    vi.mocked(getPlatformLocation).mockReset().mockResolvedValue({
+      location: availableLocation, warehouseCode: warehouse.warehouseCode, warehouseName: warehouse.warehouseName,
+    })
+    vi.mocked(createPlatformLocation).mockReset()
+  })
+
+  it('loads only domestic warehouse candidates for querying and writes', async () => {
+    const wrapper = await mountView()
+    const toolbar = wrapper.findComponent(QueryToolbar)
+    const fields = toolbar.props('fields') as QueryField[]
+
+    expect(wrapper.find('[aria-label="所属企业"]').exists()).toBe(false)
+    expect(fields[0]?.placeholder).toBe('全部仓库')
+    expect(fields[0]?.options).toEqual([
+      { value: warehouseId, label: '义乌收货仓（CN-YW-01）' },
+    ])
+    expect(fields.map(({ key, width }) => [key, width])).toEqual([
+      ['warehouseId', 300], ['zoneCode', 210],
+      ['locationCode', 220], ['locationType', 170], ['status', 160],
+    ])
+    expect(listAllPlatformWarehouses).toHaveBeenCalledWith({ warehouseType: 'DOMESTIC' })
+    expect(listPlatformLocations).toHaveBeenCalledWith({
+      page: 1,
+      size: 20,
+      zoneCode: '',
+      locationCode: '',
+      locationType: '',
+      status: '',
+    })
+    const searchButton = toolbar.findAll('button').find((button) => button.text().trim() === '查询')
+    await searchButton!.trigger('click')
+    await flushPromises()
+    expect(listPlatformLocations).toHaveBeenCalledTimes(2)
+    expect(wrapper.text()).not.toContain('请选择客户')
+    expect(wrapper.text()).not.toContain('请选择所属企业')
+    expect(wrapper.text()).not.toContain('租户')
+    expect(wrapper.text()).not.toContain('企业 ID')
+  })
+
+  it('filters by the selected warehouse without exposing or sending a customer id', async () => {
+    const wrapper = await mountView()
+    await selectScope(wrapper)
+
+    const tableToolbar = wrapper.find('.table-panel .data-table__toolbar')
+    expect(tableToolbar.exists()).toBe(true)
+    expect(tableToolbar.text()).toContain('新增库位')
+    expect(tableToolbar.text()).not.toContain('库位列表')
+    expect(tableToolbar.text()).not.toContain('共 2 个库位')
+    expect(wrapper.find('.data-table__pagination-left').text()).toContain('共 2 个库位')
+    expect(wrapper.findComponent(QueryToolbar).text()).not.toContain('新增库位')
+    expect(listAllPlatformWarehouses).toHaveBeenCalledWith({ warehouseType: 'DOMESTIC' })
+    expect(listPlatformLocations).toHaveBeenLastCalledWith({
+      page: 1,
+      size: 20,
+      warehouseId,
+      zoneCode: '',
+      locationCode: '',
+      locationType: '',
+      status: '',
+    })
+    expect(wrapper.text()).toContain('义乌收货仓')
+    expect(wrapper.text()).toContain('A1-01')
+    expect(wrapper.findAll('thead th').map((item) => item.text().trim())).toEqual([
+      '操作', '库位编码', '所属仓库', '库区', '库位类型', '状态',
+    ])
+  })
+
+  it('opens creation without a list filter and requires the warehouse inside the form', async () => {
+    const wrapper = await mountView()
+    const createButton = wrapper.find('.table-panel .data-table__toolbar').findAll('button').find((button) => button.text().trim() === '新增库位')
+
+    expect(createButton?.attributes('disabled')).toBeUndefined()
+    await createButton!.trigger('click')
+    await flushPromises()
+
+    expect(document.body.textContent).toContain('新增库位')
+    expect(document.body.textContent).toContain('所属仓库')
+    expect(document.body.textContent).toContain('请选择国内仓')
+  })
+
+  it('does not use an FBA warehouse filter as the creation scope', async () => {
+    const wrapper = await mountView()
+    const toolbar = wrapper.findComponent(QueryToolbar)
+    toolbar.vm.$emit('update:modelValue', { ...(toolbar.props('modelValue') as QueryModel), warehouseId: fbaWarehouse.id })
+    await flushPromises()
+    const createButton = wrapper.find('.table-panel .data-table__toolbar').findAll('button').find((button) => button.text().trim() === '新增库位')
+    await createButton!.trigger('click')
+    await flushPromises()
+
+    const saveButton = [...document.body.querySelectorAll('button')].find((button) => button.textContent?.trim() === '保存库位')
+    saveButton?.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+    await flushPromises()
+
+    expect(createPlatformLocation).not.toHaveBeenCalled()
+  })
+
+  it('keeps the operation column first and hides edit actions for occupied resources', async () => {
+    const wrapper = await mountView()
+    await selectScope(wrapper)
+    const headings = wrapper.findAll('thead th').map((item) => item.text().trim())
+    expect(headings[0]).toBe('操作')
+
+    const bodyRows = wrapper.findAll('tbody tr')
+    expect(bodyRows[0]?.text()).toContain('编辑')
+    expect(bodyRows[1]?.text()).not.toContain('详情')
+    expect(bodyRows[1]?.text()).not.toContain('编辑')
+    expect(bodyRows[1]?.text()).not.toContain('更多')
+  })
+
+  it('shows all available actions directly when a row has no more than three', async () => {
+    const wrapper = await mountView(['platform:location:list', 'platform:location:status'])
+    const row = wrapper.find('tbody tr')
+
+    expect(row.text()).not.toContain('详情')
+    expect(row.text()).toContain('停用')
+    expect(row.text()).not.toContain('更多')
+  })
+
+  it('shows edit, status, and delete directly for a disabled location', async () => {
+    vi.mocked(listPlatformLocations).mockResolvedValue({
+      records: [{ ...availableLocation, status: 'DISABLED' }], page: 1, size: 20, total: 1, pages: 1,
+    })
+    const wrapper = await mountView()
+    const row = wrapper.find('tbody tr')
+
+    expect(row.text()).not.toContain('详情')
+    expect(row.text()).toContain('编辑')
+    expect(row.text()).toContain('启用')
+    expect(row.text()).toContain('删除')
+    expect(row.text()).not.toContain('更多')
+  })
+
+  it('does not offer editing for a location outside a domestic warehouse', async () => {
+    vi.mocked(listPlatformLocations).mockResolvedValue({
+      records: [{ ...availableLocation, warehouseId: fbaWarehouse.id }, availableLocation], page: 1, size: 20, total: 2, pages: 1,
+    })
+    const wrapper = await mountView()
+
+    const bodyRows = wrapper.findAll('tbody tr')
+    expect(bodyRows[0]?.text()).not.toContain('详情')
+    expect(bodyRows[0]?.text()).not.toContain('编辑')
+    expect(bodyRows[1]?.text()).toContain('编辑')
+  })
+
+  it('loads the latest authenticated detail before opening the editor', async () => {
+    const wrapper = await mountView()
+    const editButton = wrapper.findAll('.el-table__body-wrapper tbody tr button').find((button) => button.text().trim() === '编辑')
+    await editButton!.trigger('click')
+    await flushPromises()
+
+    expect(getPlatformLocation).toHaveBeenCalledWith(warehouseId, availableLocation.id)
+    expect(document.body.textContent).toContain('编辑库位')
+    expect(document.body.textContent).toContain('A1 区 01 位')
+    expect(document.body.textContent).not.toContain('所属企业')
+    expect(document.body.textContent).not.toContain('企业 ID')
+    expect(document.body.querySelector('.el-drawer')).toBeNull()
+    expect(document.body.querySelector('.location-editor-dialog .el-form-item:first-child input')?.hasAttribute('disabled')).toBe(true)
+  })
+
+  it('does not provide a detail or edit entry for occupied locations', async () => {
+    const wrapper = await mountView()
+    const occupiedRow = wrapper.findAll('tbody tr')[1]
+
+    expect(occupiedRow?.text()).not.toContain('详情')
+    expect(occupiedRow?.text()).not.toContain('编辑')
+    expect(occupiedRow?.findAll('button')).toHaveLength(0)
+  })
+
+  it('clears the warehouse on reset and immediately restores the full query', async () => {
+    const wrapper = await mountView()
+    await selectScope(wrapper)
+    const toolbar = wrapper.findComponent(QueryToolbar)
+    const resetButton = toolbar.findAll('button').find((button) => button.text().trim() === '重置')
+
+    await resetButton!.trigger('click')
+    await flushPromises()
+
+    const model = wrapper.findComponent(QueryToolbar).props('modelValue') as QueryModel
+    expect(model.warehouseId).toBe('')
+    expect(listPlatformLocations).toHaveBeenLastCalledWith({
+      page: 1,
+      size: 20,
+      zoneCode: '',
+      locationCode: '',
+      locationType: '',
+      status: '',
+    })
+    expect(wrapper.text()).not.toContain('请选择客户')
+  })
+
+  it('paginates the all-customer list without adding customer or warehouse IDs', async () => {
+    vi.mocked(listPlatformLocations).mockResolvedValue({
+      records: [availableLocation, occupiedLocation], page: 1, size: 20, total: 40, pages: 2,
+    })
+    const wrapper = await mountView()
+    wrapper.findComponent(DataTable).vm.$emit('update:page', 2)
+    await flushPromises()
+
+    expect(listPlatformLocations).toHaveBeenLastCalledWith({
+      page: 2,
+      size: 20,
+      zoneCode: '',
+      locationCode: '',
+      locationType: '',
+      status: '',
+    })
+  })
+
+  it('keeps the latest editor request when an older location request finishes last', async () => {
+    const secondLocation = { ...availableLocation, id: '9223372036854775800', locationCode: 'A1-03' }
+    const firstDetail = { location: availableLocation, warehouseCode: warehouse.warehouseCode, warehouseName: warehouse.warehouseName }
+    const secondDetail = { location: secondLocation, warehouseCode: warehouse.warehouseCode, warehouseName: warehouse.warehouseName }
+    let resolveFirst!: (value: typeof firstDetail) => void
+    let resolveSecond!: (value: typeof secondDetail) => void
+    vi.mocked(getPlatformLocation).mockImplementation((_warehouseId, locationId) => new Promise((resolve) => {
+      if (String(locationId) === String(availableLocation.id)) resolveFirst = resolve
+      else resolveSecond = resolve
+    }))
+    const wrapper = await mountView()
+    const vm = wrapper.vm as unknown as {
+      editorOpen: boolean
+      form: { locationCode: string }
+      openEdit(row: PlatformLocationResource): Promise<void>
+    }
+
+    void vm.openEdit(availableLocation)
+    void vm.openEdit(secondLocation)
+    resolveSecond(secondDetail)
+    await flushPromises()
+    resolveFirst(firstDetail)
+    await flushPromises()
+
+    expect(vm.editorOpen).toBe(true)
+    expect(vm.form.locationCode).toBe('A1-03')
+  })
+})
diff --git a/src/modules/warehouse-resources/locations/pages/LocationsView.vue b/src/modules/warehouse-resources/locations/pages/LocationsView.vue
new file mode 100644
index 00000000..50845b46
--- /dev/null
+++ b/src/modules/warehouse-resources/locations/pages/LocationsView.vue
@@ -0,0 +1,708 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, reactive, ref, watch } from 'vue'
+import { ElMessage, ElMessageBox, type FormInstance, type FormRules } from 'element-plus'
+import { MapPin, Plus, Save } from '@lucide/vue'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useUnsavedWorkRegistration } from '@/core/unsaved-work/useUnsavedWorkRegistration'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import {
+  changePlatformLocationStatus,
+  createPlatformLocation,
+  deletePlatformLocation,
+  getPlatformLocation,
+  listPlatformLocations,
+  updatePlatformLocation,
+  type EditablePlatformLocationStatus,
+  type PlatformLocationQuery,
+  type PlatformLocationResource,
+  type PlatformLocationStatus,
+  type PlatformLocationType,
+  type SavePlatformLocationRequest,
+} from '../api/platformLocations'
+import { listAllPlatformWarehouses, type PlatformWarehouseResource } from '../../../warehouses/api/platformWarehouses'
+
+type EditorMode = 'create' | 'edit'
+type LocationFilters = QueryModel & {
+  warehouseId: string
+  zoneCode: string
+  locationCode: string
+  locationType: PlatformLocationType | ''
+  status: PlatformLocationStatus | ''
+}
+type AppliedLocationFilters = {
+  warehouseId: string
+  zoneCode: string
+  locationCode: string
+  locationType: PlatformLocationType | ''
+  status: PlatformLocationStatus | ''
+}
+
+const access = useAccessPreviewStore()
+const warehouses = ref<PlatformWarehouseResource[]>([])
+const warehouseLoading = ref(false)
+const warehouseError = ref<ApiErrorDetails | null>(null)
+const loading = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const rows = ref<PlatformLocationResource[]>([])
+const page = ref(1)
+const pageSize = ref(20)
+const total = ref(0)
+const editorOpen = ref(false)
+const editorMode = ref<EditorMode>('create')
+const editorLoading = ref(false)
+const saving = ref(false)
+const actionLoadingIds = ref(new Set<string>())
+const formRef = ref<FormInstance>()
+let warehouseLoadSequence = 0
+let locationLoadSequence = 0
+let editorLoadSequence = 0
+
+const filters = ref<LocationFilters>({ warehouseId: '', zoneCode: '', locationCode: '', locationType: '', status: '' })
+const appliedFilters = ref<AppliedLocationFilters>({ warehouseId: '', zoneCode: '', locationCode: '', locationType: '', status: '' })
+const selectedWarehouseId = computed(() => String(filters.value.warehouseId || ''))
+const queryFields = computed<QueryField[]>(() => [
+  {
+    key: 'warehouseId',
+    type: 'select',
+    label: '所属仓库',
+    width: 300,
+    placeholder: warehouseLoading.value ? '仓库加载中' : '全部仓库',
+    props: {
+      'aria-label': '所属仓库',
+      filterable: true,
+      disabled: selectionDisabled.value || warehouseLoading.value || Boolean(warehouseError.value),
+    },
+    options: warehouses.value.map((warehouse) => ({
+      value: String(warehouse.id),
+      label: `${warehouse.warehouseName}（${warehouse.warehouseCode}）`,
+    })),
+  },
+  { key: 'zoneCode', type: 'input', width: 210, label: '库区编码', placeholder: '库区编码', props: { maxlength: 50, 'aria-label': '库区编码' } },
+  { key: 'locationCode', type: 'input', width: 220, label: '库位编码', placeholder: '库位编码', props: { maxlength: 50, 'aria-label': '库位编码' } },
+  {
+    key: 'locationType', type: 'select', width: 170, label: '库位类型', placeholder: '全部类型', props: { 'aria-label': '库位类型' },
+    options: [
+      { label: '货架位', value: 'SHELF' },
+      { label: '托盘位', value: 'PALLET' },
+      { label: '地堆位', value: 'FLOOR' },
+      { label: '流利架', value: 'FLOW_RACK' },
+    ],
+  },
+  {
+    key: 'status', type: 'select', width: 160, label: '库位状态', placeholder: '全部状态', props: { 'aria-label': '库位状态' },
+    options: [
+      { label: '可用', value: 'AVAILABLE' },
+      { label: '已预占', value: 'RESERVED' },
+      { label: '已占用', value: 'OCCUPIED' },
+      { label: '已停用', value: 'DISABLED' },
+    ],
+  },
+])
+
+const emptyForm = () => ({
+  id: '',
+  warehouseId: '',
+  zoneCode: '',
+  zoneName: '',
+  locationCode: '',
+  locationName: '',
+  locationType: 'SHELF' as PlatformLocationType,
+  maxWeightKg: null as number | null,
+  status: 'AVAILABLE' as EditablePlatformLocationStatus,
+  remark: '',
+  version: 0,
+})
+const form = reactive(emptyForm())
+const rules: FormRules<typeof form> = {
+  warehouseId: [{ required: true, message: '请选择国内仓', trigger: 'change' }],
+  zoneCode: [{ required: true, message: '请输入库区编码', trigger: 'blur' }],
+  zoneName: [{ required: true, message: '请输入库区名称', trigger: 'blur' }],
+  locationCode: [
+    { required: true, message: '请输入库位编码', trigger: 'blur' },
+    {
+      validator: (_rule, value: string, callback) => {
+        if (value.trim().toUpperCase() === 'A0') callback(new Error('A0 是系统共享溢出位保留编码'))
+        else callback()
+      },
+      trigger: 'blur',
+    },
+  ],
+  locationType: [{ required: true, message: '请选择库位类型', trigger: 'change' }],
+  status: [{ required: true, message: '请选择状态', trigger: 'change' }],
+}
+
+const selectedWarehouse = computed(() => warehouses.value.find((item) => String(item.id) === form.warehouseId) ?? null)
+const domesticWarehouses = computed(() => warehouses.value.filter((warehouse) => (
+  warehouse.warehouseType === 'DOMESTIC' && warehouse.status === 'ACTIVE'
+)))
+const editorTitle = computed(() => editorMode.value === 'create' ? '新增库位' : '编辑库位')
+const editorPermission = computed(() => editorMode.value === 'create' ? 'platform:location:create' : 'platform:location:edit')
+const selectionDisabled = computed(() => editorOpen.value || editorLoading.value || saving.value || actionLoadingIds.value.size > 0)
+const filtered = computed(() => Object.values(appliedFilters.value).some((value) => String(value || '').trim()))
+const emptyDescription = computed(() => filtered.value ? '暂无符合筛选条件的库位' : '暂无库位数据')
+
+const { captureBaseline } = useUnsavedWorkRegistration({
+  key: 'location-editor',
+  label: editorTitle,
+  isOpen: editorOpen,
+  model: form,
+  requiredPermission: editorPermission,
+})
+
+const statusMeta: Record<PlatformLocationStatus, { label: string; type: 'success' | 'warning' | 'danger' | 'info' }> = {
+  AVAILABLE: { label: '可用', type: 'success' },
+  RESERVED: { label: '已预占', type: 'warning' },
+  OCCUPIED: { label: '已占用', type: 'danger' },
+  DISABLED: { label: '已停用', type: 'info' },
+}
+const typeLabels: Record<PlatformLocationType, string> = {
+  SHELF: '货架位',
+  PALLET: '托盘位',
+  FLOOR: '地堆位',
+  FLOW_RACK: '流利架',
+}
+
+const columns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 240, fixed: 'left', slotName: 'actions' },
+  { key: 'location', label: '库位编码', minWidth: 190, slotName: 'location' },
+  { key: 'warehouse', label: '所属仓库', minWidth: 210, slotName: 'warehouse' },
+  { key: 'zone', label: '库区', minWidth: 150, slotName: 'zone' },
+  { key: 'locationType', label: '库位类型', width: 120, slotName: 'locationType' },
+  { key: 'maxWeightKg', label: '最大承重（kg）', minWidth: 140, slotName: 'maxWeightKg', defaultVisible: false },
+  { key: 'status', label: '状态', width: 110, slotName: 'status' },
+  { key: 'remark', label: '备注', minWidth: 220, slotName: 'remark', defaultVisible: false },
+]
+
+function apiId(value: string) {
+  return value
+}
+
+function optionalText(value: string) {
+  return value.trim() || null
+}
+
+function formatWeight(value: number | string | null) {
+  if (value === null || value === '') return '—'
+  const numeric = Number(value)
+  return Number.isFinite(numeric) ? `${numeric.toLocaleString('zh-CN', { maximumFractionDigits: 3 })} kg` : `${value} kg`
+}
+
+function canEdit(row: PlatformLocationResource) {
+  return access.can('platform:location:edit')
+    && isDomesticWarehouse(row.warehouseId)
+    && !row.sharedOverflow
+    && (row.status === 'AVAILABLE' || row.status === 'DISABLED')
+}
+
+function canChangeStatus(row: PlatformLocationResource) {
+  return access.can('platform:location:status')
+    && !row.sharedOverflow
+    && (row.status === 'AVAILABLE' || row.status === 'DISABLED')
+}
+
+function canDelete(row: PlatformLocationResource) {
+  return access.can('platform:location:delete') && !row.sharedOverflow && row.status === 'DISABLED'
+}
+
+function actionError(error: unknown, fallback: string) {
+  const details = getApiErrorDetails(error, fallback)
+  ElMessage.error(details.requestId ? `${details.message}（requestId: ${details.requestId}）` : details.message)
+}
+
+function isDomesticWarehouse(warehouseId: number | string) {
+  return warehouses.value.some((warehouse) => (
+    String(warehouse.id) === String(warehouseId)
+    && warehouse.warehouseType === 'DOMESTIC'
+  ))
+}
+
+function isActiveDomesticWarehouse(warehouseId: number | string) {
+  return domesticWarehouses.value.some((warehouse) => String(warehouse.id) === String(warehouseId))
+}
+
+function requireCreateScope() {
+  if (!selectedWarehouse.value || !form.warehouseId) {
+    ElMessage.warning('请选择国内仓')
+    return null
+  }
+  return { warehouseId: apiId(form.warehouseId) }
+}
+
+function recordScope(row: PlatformLocationResource) {
+  return { warehouseId: apiId(String(row.warehouseId)) }
+}
+
+async function loadWarehouses() {
+  const sequence = ++warehouseLoadSequence
+  warehouseLoading.value = true
+  warehouseError.value = null
+  warehouses.value = []
+  try {
+    // 库位只属于国内仓，查询候选仓库时直接限制仓库类型，避免把 FBA/海外仓带入页面。
+    const records = await listAllPlatformWarehouses({ warehouseType: 'DOMESTIC' })
+    if (sequence !== warehouseLoadSequence) return
+    // 保留前端兜底过滤，避免旧接口或异常响应返回其他仓库类型。
+    warehouses.value = records.filter((warehouse) => warehouse.warehouseType === 'DOMESTIC')
+  } catch (error) {
+    if (sequence !== warehouseLoadSequence) return
+    warehouseError.value = getApiErrorDetails(error, '仓库列表加载失败，请稍后重试')
+  } finally {
+    if (sequence === warehouseLoadSequence) warehouseLoading.value = false
+  }
+}
+
+async function loadLocations() {
+  const sequence = ++locationLoadSequence
+  loading.value = true
+  loadError.value = null
+  try {
+    const query: PlatformLocationQuery = {
+      page: page.value,
+      size: pageSize.value,
+      zoneCode: appliedFilters.value.zoneCode,
+      locationCode: appliedFilters.value.locationCode,
+      locationType: appliedFilters.value.locationType,
+      status: appliedFilters.value.status,
+    }
+    if (appliedFilters.value.warehouseId) query.warehouseId = apiId(appliedFilters.value.warehouseId)
+    const result = await listPlatformLocations(query)
+    if (sequence !== locationLoadSequence) return
+    rows.value = result.records
+    total.value = result.total
+  } catch (error) {
+    if (sequence !== locationLoadSequence) return
+    rows.value = []
+    total.value = 0
+    loadError.value = getApiErrorDetails(error, '库位列表加载失败，请稍后重试')
+  } finally {
+    if (sequence === locationLoadSequence) loading.value = false
+  }
+}
+
+function applyFilters(model: QueryModel) {
+  appliedFilters.value = {
+    warehouseId: String(model.warehouseId || ''),
+    zoneCode: String(model.zoneCode || ''),
+    locationCode: String(model.locationCode || ''),
+    locationType: (model.locationType || '') as PlatformLocationType | '',
+    status: (model.status || '') as PlatformLocationStatus | '',
+  }
+  if (page.value === 1) void loadLocations()
+  else page.value = 1
+}
+
+function assignForm(resource: PlatformLocationResource) {
+  Object.assign(form, {
+    id: String(resource.id),
+    warehouseId: String(resource.warehouseId),
+    zoneCode: resource.zoneCode,
+    zoneName: resource.zoneName,
+    locationCode: resource.locationCode,
+    locationName: resource.locationName ?? '',
+    locationType: resource.locationType,
+    maxWeightKg: resource.maxWeightKg === null ? null : Number(resource.maxWeightKg),
+    status: resource.status as EditablePlatformLocationStatus,
+    remark: resource.remark ?? '',
+    version: resource.version,
+  })
+}
+
+function openCreate() {
+  editorLoadSequence += 1
+  Object.assign(form, emptyForm())
+  form.warehouseId = isActiveDomesticWarehouse(selectedWarehouseId.value) ? selectedWarehouseId.value : ''
+  form.status = selectedWarehouse.value?.status === 'INACTIVE' ? 'DISABLED' : 'AVAILABLE'
+  editorMode.value = 'create'
+  captureBaseline()
+  editorOpen.value = true
+  void formRef.value?.clearValidate()
+}
+
+async function openEdit(row: PlatformLocationResource) {
+  if (!isDomesticWarehouse(row.warehouseId)) {
+    ElMessage.warning('仅支持编辑国内仓库位')
+    return
+  }
+  const sequence = ++editorLoadSequence
+  const scope = recordScope(row)
+  editorLoading.value = true
+  try {
+    const result = await getPlatformLocation(scope.warehouseId, row.id)
+    if (sequence !== editorLoadSequence) return
+    editorMode.value = 'edit'
+    assignForm(result.location)
+    captureBaseline()
+    editorOpen.value = true
+    void formRef.value?.clearValidate()
+  } catch (error) {
+    if (sequence !== editorLoadSequence) return
+    actionError(error, '库位资料加载失败，请稍后重试')
+  } finally {
+    if (sequence === editorLoadSequence) editorLoading.value = false
+  }
+}
+
+function buildPayload(): SavePlatformLocationRequest {
+  return {
+    warehouseId: apiId(form.warehouseId),
+    zoneCode: form.zoneCode.trim(),
+    zoneName: form.zoneName.trim(),
+    locationCode: form.locationCode.trim(),
+    locationName: optionalText(form.locationName),
+    locationType: form.locationType,
+    maxWeightKg: form.maxWeightKg,
+    status: form.status,
+    remark: optionalText(form.remark),
+    ...(form.id ? { version: form.version } : {}),
+  }
+}
+
+async function saveLocation() {
+  const valid = await formRef.value?.validate().catch(() => false)
+  if (!valid) return
+  const warehouseAllowed = form.id
+    ? isDomesticWarehouse(form.warehouseId)
+    : isActiveDomesticWarehouse(form.warehouseId)
+  if (!warehouseAllowed) {
+    ElMessage.error(form.id ? '库位仅支持归属国内仓' : '新增库位仅支持选择启用的国内仓')
+    return
+  }
+  const scope = form.id ? { warehouseId: apiId(form.warehouseId) } : requireCreateScope()
+  if (!scope) return
+  saving.value = true
+  try {
+    const payload = buildPayload()
+    if (form.id) await updatePlatformLocation(scope.warehouseId, form.id, payload)
+    else await createPlatformLocation(payload)
+    editorOpen.value = false
+    ElMessage.success(form.id ? '库位资料已更新' : '库位已创建')
+    await loadLocations()
+  } catch (error) {
+    actionError(error, '库位保存失败，请检查后重试')
+    if (form.id) await loadLocations()
+  } finally {
+    saving.value = false
+  }
+}
+
+function setActionLoading(id: number | string, active: boolean) {
+  const next = new Set(actionLoadingIds.value)
+  if (active) next.add(String(id))
+  else next.delete(String(id))
+  actionLoadingIds.value = next
+}
+
+async function toggleStatus(row: PlatformLocationResource) {
+  const scope = recordScope(row)
+  if (!canChangeStatus(row)) return
+  const nextStatus: EditablePlatformLocationStatus = row.status === 'AVAILABLE' ? 'DISABLED' : 'AVAILABLE'
+  const action = nextStatus === 'AVAILABLE' ? '启用' : '停用'
+  try {
+    await ElMessageBox.confirm(
+      nextStatus === 'DISABLED'
+        ? `确定停用“${row.locationCode}”吗？停用前后端会再次检查是否存在活动预占或占用。`
+        : `确定重新启用“${row.locationCode}”吗？仅启用仓库中的库位可以恢复可用。`,
+      `${action}库位`,
+      { customClass: 'admin-density-confirm', type: nextStatus === 'AVAILABLE' ? 'success' : 'warning', confirmButtonText: `确认${action}`, cancelButtonText: '取消' },
+    )
+  } catch {
+    return
+  }
+  setActionLoading(row.id, true)
+  try {
+    await changePlatformLocationStatus(scope.warehouseId, row.id, nextStatus, row.version)
+    ElMessage.success(`库位 ${row.locationCode} 已${action}`)
+    await loadLocations()
+  } catch (error) {
+    actionError(error, `${action}库位失败`)
+    await loadLocations()
+  } finally {
+    setActionLoading(row.id, false)
+  }
+}
+
+async function removeLocation(row: PlatformLocationResource) {
+  const scope = recordScope(row)
+  if (!canDelete(row)) return
+  try {
+    await ElMessageBox.confirm(
+      `确定删除已停用库位“${row.locationCode}”吗？系统会保留审计记录，此操作不能直接恢复。`,
+      '删除库位',
+      { customClass: 'admin-density-confirm', type: 'warning', confirmButtonText: '确认删除', cancelButtonText: '取消' },
+    )
+  } catch {
+    return
+  }
+  setActionLoading(row.id, true)
+  try {
+    await deletePlatformLocation(scope.warehouseId, row.id, row.version)
+    ElMessage.success(`库位 ${row.locationCode} 已删除`)
+    await loadLocations()
+  } catch (error) {
+    actionError(error, '删除库位失败')
+    await loadLocations()
+  } finally {
+    setActionLoading(row.id, false)
+  }
+}
+
+watch(
+  () => access.can(editorPermission.value),
+  (allowed) => {
+    if (allowed || !editorOpen.value) return
+    editorOpen.value = false
+  },
+  { flush: 'sync' },
+)
+
+watch([page, pageSize], () => { void loadLocations() })
+watch(editorOpen, (open) => {
+  if (open) return
+  editorLoadSequence += 1
+  editorLoading.value = false
+})
+watch(() => form.warehouseId, (warehouseId) => {
+  if (editorMode.value !== 'create') return
+  const warehouse = warehouses.value.find((item) => String(item.id) === warehouseId)
+  form.status = warehouse?.status === 'INACTIVE' ? 'DISABLED' : 'AVAILABLE'
+})
+
+onMounted(() => {
+  void loadWarehouses()
+  void loadLocations()
+})
+</script>
+
+<template>
+  <AdminPage as="div" class="location-page admin-density">
+    <ListPageLayout aria-label="库位列表页面">
+      <template #toolbar>
+        <QueryToolbar
+          v-model="filters"
+          ariaLabel="库位筛选"
+          :fields="queryFields"
+          preference-key="locations-query"
+          @search="applyFilters"
+        />
+      </template>
+      <template #state>
+        <LoadErrorState
+          v-if="warehouseError"
+          title="仓库列表加载失败"
+          :message="warehouseError.message"
+          :loading="warehouseLoading"
+          @retry="loadWarehouses"
+        />
+        <el-alert v-else-if="!warehouseLoading && domesticWarehouses.length === 0" type="info" :closable="false" show-icon title="暂无可选国内仓">
+          请先在仓库管理中建立国内仓，再维护库位。
+        </el-alert>
+        <LoadErrorState
+          v-else-if="loadError"
+          title="库位列表加载失败"
+          :message="loadError.message"
+          :loading="loading"
+          @retry="loadLocations"
+        />
+      </template>
+
+      <section v-if="!loadError" class="surface-panel table-panel" aria-label="库位列表区域">
+      <DataTable
+        v-model:page="page"
+        v-model:page-size="pageSize"
+        :data="rows"
+        :columns="columns"
+        border
+        stripe
+        preference-key="locations-table"
+        :loading="loading"
+        :total="total"
+        :page-sizes="[20, 50, 100, 200]"
+        row-key="id"
+        aria-label="库位列表"
+        :empty-text="emptyDescription"
+      >
+        <template #toolbar-actions><el-button v-if="access.can('platform:location:create')" type="primary" @click="openCreate"><Plus :size="16" />新增库位</el-button></template>
+        <template #actions="{ row }">
+          <div class="location-actions density-actions">
+            <el-button
+              v-if="canEdit(row as PlatformLocationResource)"
+              size="small"
+              class="density-action"
+              :loading="editorLoading"
+              :disabled="loading || editorLoading"
+              @click="openEdit(row as PlatformLocationResource)"
+            >编辑</el-button>
+            <el-button
+              v-if="canChangeStatus(row as PlatformLocationResource)"
+              size="small"
+              class="density-action"
+              :data-tone="(row as PlatformLocationResource).status === 'AVAILABLE' ? 'danger' : 'success'"
+              :disabled="loading || actionLoadingIds.has(String((row as PlatformLocationResource).id))"
+              @click="toggleStatus(row as PlatformLocationResource)"
+            >{{ (row as PlatformLocationResource).status === 'AVAILABLE' ? '停用' : '启用' }}</el-button>
+            <el-button
+              v-if="canDelete(row as PlatformLocationResource)"
+              size="small"
+              class="density-action" data-tone="danger"
+              :disabled="loading || actionLoadingIds.has(String((row as PlatformLocationResource).id))"
+              @click="removeLocation(row as PlatformLocationResource)"
+            >删除</el-button>
+          </div>
+        </template>
+        <template #location="{ row }">
+          <div class="location-cell">
+            <span><MapPin :size="17" /></span>
+            <div>
+              <strong>{{ (row as PlatformLocationResource).locationCode }}</strong>
+              <small>{{ (row as PlatformLocationResource).locationName || '未命名库位' }}</small>
+            </div>
+            <el-tag v-if="(row as PlatformLocationResource).sharedOverflow" size="small" type="warning">系统位</el-tag>
+          </div>
+        </template>
+        <template #zone="{ row }">
+          <div class="stacked-value"><strong>{{ (row as PlatformLocationResource).zoneName }}</strong><small>{{ (row as PlatformLocationResource).zoneCode }}</small></div>
+        </template>
+        <template #warehouse="{ row }">
+          <div class="stacked-value">
+            <strong>{{ (row as PlatformLocationResource).warehouseName || warehouses.find((item) => String(item.id) === String((row as PlatformLocationResource).warehouseId))?.warehouseName || '—' }}</strong>
+            <small>{{ (row as PlatformLocationResource).warehouseCode || warehouses.find((item) => String(item.id) === String((row as PlatformLocationResource).warehouseId))?.warehouseCode || '—' }}</small>
+          </div>
+        </template>
+        <template #locationType="{ row }">{{ typeLabels[(row as PlatformLocationResource).locationType] }}</template>
+        <template #maxWeightKg="{ row }">{{ formatWeight((row as PlatformLocationResource).maxWeightKg) }}</template>
+        <template #status="{ row }">
+          <el-tag :type="statusMeta[(row as PlatformLocationResource).status].type" effect="light">
+            {{ statusMeta[(row as PlatformLocationResource).status].label }}
+          </el-tag>
+        </template>
+        <template #remark="{ row }"><span class="remark-cell">{{ (row as PlatformLocationResource).remark || '—' }}</span></template>
+        <template #empty>
+          <el-empty v-if="!loading" :description="emptyDescription">
+            <el-button
+              v-if="!filtered && access.can('platform:location:create')"
+              type="primary"
+              @click="openCreate"
+            ><Plus :size="16" />新增第一个库位</el-button>
+          </el-empty>
+        </template>
+        <template #pagination-left="{ total: tableTotal }"><span>共 {{ tableTotal }} 个库位</span></template>
+      </DataTable>
+      </section>
+    </ListPageLayout>
+
+    <AppDialog
+      v-model="editorOpen"
+      :title="editorTitle"
+      width="min(560px, calc(100vw - 28px))"
+      class="location-editor-dialog admin-density-dialog"
+      :confirm-loading="saving"
+      :close-on-click-modal="false"
+      :close-on-press-escape="!saving"
+      :show-close="!saving"
+      :show-confirm="false"
+      destroy-on-close
+    >
+      <el-form ref="formRef" :model="form" :rules="rules" label-position="top" class="editor-form" :disabled="saving">
+        <div class="editor-field-grid">
+          <el-form-item label="所属仓库" prop="warehouseId" required>
+            <el-select v-model="form.warehouseId" filterable placeholder="请选择国内仓" :loading="warehouseLoading" :disabled="editorMode === 'edit'">
+              <el-option
+                v-for="warehouse in domesticWarehouses"
+                :key="String(warehouse.id)"
+                :label="`${warehouse.warehouseName}（${warehouse.warehouseCode}）`"
+                :value="String(warehouse.id)"
+              />
+            </el-select>
+          </el-form-item>
+          <el-form-item label="库位编码" prop="locationCode" required>
+            <el-input v-model.trim="form.locationCode" maxlength="50" placeholder="例如 A1-01" />
+          </el-form-item>
+        </div>
+        <div class="editor-field-grid">
+          <el-form-item label="库位名称">
+            <el-input v-model.trim="form.locationName" maxlength="100" placeholder="例如 A1 区 01 位" />
+          </el-form-item>
+          <el-form-item label="库区编码" prop="zoneCode" required>
+            <el-input v-model.trim="form.zoneCode" maxlength="50" placeholder="例如 A" />
+          </el-form-item>
+        </div>
+        <div class="editor-field-grid">
+          <el-form-item label="库区名称" prop="zoneName" required>
+            <el-input v-model.trim="form.zoneName" maxlength="100" placeholder="例如 常规区" />
+          </el-form-item>
+          <el-form-item label="库位类型" prop="locationType" required>
+            <el-select v-model="form.locationType" placeholder="请选择库位类型">
+              <el-option label="货架位" value="SHELF" />
+              <el-option label="托盘位" value="PALLET" />
+              <el-option label="地堆位" value="FLOOR" />
+              <el-option label="流利架" value="FLOW_RACK" />
+            </el-select>
+          </el-form-item>
+        </div>
+        <div class="editor-field-grid">
+          <el-form-item label="最大承重（kg）">
+            <el-input-number v-model="form.maxWeightKg" :min="0.001" :precision="3" :step="10" controls-position="right" placeholder="选填" />
+          </el-form-item>
+          <el-form-item label="状态" prop="status" required>
+            <el-select v-model="form.status" :disabled="editorMode === 'edit'" placeholder="请选择状态">
+              <el-option label="可用" value="AVAILABLE" :disabled="selectedWarehouse?.status !== 'ACTIVE'" />
+              <el-option label="停用" value="DISABLED" />
+            </el-select>
+          </el-form-item>
+        </div>
+        <el-form-item label="备注" class="editor-remark-field">
+          <el-input v-model.trim="form.remark" maxlength="500" show-word-limit placeholder="选填" />
+        </el-form-item>
+      </el-form>
+
+      <template #footer>
+        <div class="editor-footer">
+          <span><i aria-hidden="true">*</i> 为必填项</span>
+          <div>
+            <el-button :disabled="saving" @click="editorOpen = false">取消</el-button>
+            <el-button type="primary" :loading="saving" @click="saveLocation"><Save :size="16" />保存库位</el-button>
+          </div>
+        </div>
+      </template>
+    </AppDialog>
+  </AdminPage>
+</template>
+
+<style scoped>
+.state-alert p { margin: var(--admin-space-2, 6px) 0 0; line-height: 1.55; }
+.state-alert .el-button { margin-top: var(--admin-space-4, 10px); }
+.location-actions { white-space: nowrap; }
+.location-cell { display: flex; min-width: 0; align-items: center; gap: var(--admin-space-4, 10px); }
+.location-cell > span { display: grid; width: 20px; height: 20px; flex: 0 0 20px; place-items: center; border-radius: 7px; background: #eef3fa; color: var(--cc-primary); }
+.location-cell > div, .stacked-value { display: flex; min-width: 0; flex-direction: column; gap: 3px; }
+.location-cell strong, .stacked-value strong { overflow-wrap: anywhere; }
+.location-cell small, .stacked-value small { color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); }
+.remark-cell { display: -webkit-box; overflow: hidden; line-height: 1.5; -webkit-box-orient: vertical; -webkit-line-clamp: 2; }
+.editor-form { padding: 0; }
+.editor-field-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 0 14px; }
+.editor-form :deep(.el-input-number), .editor-form :deep(.el-select) { width: 100%; }
+.editor-form :deep(.el-form-item) { margin-bottom: 14px; }
+.editor-form :deep(.el-form-item__label) { padding-bottom: var(--admin-space-1, 4px); color: #344054; font-size: var(--admin-font-caption, 12px); font-weight: 650; line-height: 1.4; }
+.editor-remark-field { margin-bottom: 0 !important; }
+.editor-footer { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-3, 8px); }
+.editor-footer > span { color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); }
+.editor-footer > span i { color: var(--el-color-danger); font-style: normal; }
+.editor-footer > div { display: flex; gap: var(--admin-space-3, 8px); }
+.editor-footer :deep(.el-button + .el-button) { margin-left: 0; }
+
+@media (max-width: 720px) {
+  .editor-form { padding-right: 16px; padding-left: 16px; }
+  .editor-field-grid { grid-template-columns: minmax(0, 1fr); }
+  .editor-footer { display: block; }
+  .editor-footer > span { display: none; }
+  .editor-footer > div { display: grid; grid-template-columns: 1fr 1fr; }
+  .editor-footer :deep(.el-button) { min-height: 44px; margin-left: 0; }
+}
+</style>
diff --git a/src/modules/warehouse-resources/pallets/api/platformPallets.test.ts b/src/modules/warehouse-resources/pallets/api/platformPallets.test.ts
new file mode 100644
index 00000000..acdbc4ca
--- /dev/null
+++ b/src/modules/warehouse-resources/pallets/api/platformPallets.test.ts
@@ -0,0 +1,78 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import {
+  createPlatformPallet,
+  deletePlatformPallet,
+  getPlatformPallet,
+  listPlatformPallets,
+  updatePlatformPallet,
+  type SavePlatformPalletRequest,
+} from './platformPallets'
+
+vi.mock('@/shared/api/http', () => ({
+  http: { get: vi.fn(), post: vi.fn(), put: vi.fn(), delete: vi.fn() },
+  unwrapApiResponse: <T>(response: { data: T }) => response.data,
+}))
+
+const payload: SavePlatformPalletRequest = {
+  warehouseId: '19001',
+  palletType: '木托盘',
+  capacityCbm: 1.2,
+  weightKg: 8,
+  color: '黄色',
+  remark: null,
+}
+
+describe('platform pallet API', () => {
+  beforeEach(() => {
+    vi.mocked(http.get).mockReset()
+    vi.mocked(http.post).mockReset()
+    vi.mocked(http.put).mockReset()
+    vi.mocked(http.delete).mockReset()
+  })
+
+  it('uses the real page contract and normalizes long pagination fields', async () => {
+    vi.mocked(http.get).mockResolvedValue({
+      code: '200', message: 'success', data: { records: [], page: '2', size: '20', total: '41', pages: '3' },
+    })
+
+    await expect(listPlatformPallets({
+      page: 2, size: 20, warehouseId: '19001', palletCode: ' TP ', palletType: ' 木托盘 ',
+    })).resolves.toEqual({ records: [], page: 2, size: 20, total: 41, pages: 3 })
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/pallets', {
+      params: {
+        page: 2, size: 20, warehouseId: '19001', palletCode: 'TP', palletType: '木托盘',
+      },
+    })
+  })
+
+  it('omits the customer parameter for an all-customer page query', async () => {
+    vi.mocked(http.get).mockResolvedValue({
+      code: '200', message: 'success', data: { records: [], page: 1, size: 20, total: 0, pages: 0 },
+    })
+
+    await listPlatformPallets({ page: 2, size: 20 })
+
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/pallets', {
+      params: { page: 2, size: 20 },
+    })
+    expect(vi.mocked(http.get).mock.calls[0]?.[1]?.params).not.toHaveProperty('tenantId')
+  })
+
+  it('uses tenant and warehouse scope for detail, update, and delete', async () => {
+    vi.mocked(http.get).mockResolvedValue({ code: '200', data: { id: '20001' } })
+    vi.mocked(http.post).mockResolvedValue({ code: '200', data: '20001' })
+    vi.mocked(http.put).mockResolvedValue({ code: '200', data: null })
+    vi.mocked(http.delete).mockResolvedValue({ code: '200', data: null })
+
+    await expect(getPlatformPallet('19001', '20001')).resolves.toEqual({ id: '20001' })
+    await expect(createPlatformPallet(payload)).resolves.toBe('20001')
+    await expect(updatePlatformPallet('19001', '20001', payload)).resolves.toBeNull()
+    await expect(deletePlatformPallet('19001', '20001')).resolves.toBeNull()
+
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/pallets/20001', { params: { tenantId: 0, warehouseId: '19001' } })
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/pallets', payload, { params: { tenantId: 0 } })
+    expect(http.put).toHaveBeenCalledWith('/platform/v1/pallets/20001', payload, { params: { tenantId: 0, warehouseId: '19001' } })
+    expect(http.delete).toHaveBeenCalledWith('/platform/v1/pallets/20001', { params: { tenantId: 0, warehouseId: '19001' } })
+  })
+})
diff --git a/src/modules/warehouse-resources/pallets/api/platformPallets.ts b/src/modules/warehouse-resources/pallets/api/platformPallets.ts
new file mode 100644
index 00000000..3a60da25
--- /dev/null
+++ b/src/modules/warehouse-resources/pallets/api/platformPallets.ts
@@ -0,0 +1,107 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+
+export interface PlatformPalletResource {
+  id: number | string
+  tenantId: number | string
+  warehouseId: number | string
+  palletCode: string
+  palletType: string
+  capacityCbm: number | string
+  weightKg: number | string | null
+  color: string
+  remark: string | null
+  createdAt: string | null
+  updatedAt: string | null
+}
+
+export interface PlatformPalletPage {
+  records: PlatformPalletResource[]
+  page: number
+  size: number
+  total: number
+  pages: number
+}
+export interface PlatformPalletSummary { totalCount: number; idleCount: number; occupiedCount: number }
+
+export interface PlatformPalletQuery {
+  page: number
+  size: number
+  warehouseId?: number | string
+  palletCode?: string
+  palletType?: string
+}
+
+export interface SavePlatformPalletRequest {
+  warehouseId: number | string
+  palletType: string
+  capacityCbm: number
+  weightKg: number
+  color: string
+  remark: string | null
+}
+
+const basePath = '/platform/v1/pallets'
+const platformResourceScope = 0
+
+export async function listPlatformPallets(query: PlatformPalletQuery) {
+  const response = await http.get<ApiEnvelope<PlatformPalletPage>, ApiEnvelope<PlatformPalletPage>>(basePath, {
+    params: {
+      page: query.page,
+      size: query.size,
+      ...(query.warehouseId === undefined || query.warehouseId === '' ? {} : { warehouseId: query.warehouseId }),
+      ...(query.palletCode?.trim() ? { palletCode: query.palletCode.trim() } : {}),
+      ...(query.palletType?.trim() ? { palletType: query.palletType.trim() } : {}),
+    },
+  })
+  const result = unwrapApiResponse(response)
+  return {
+    ...result,
+    page: Number(result.page),
+    size: Number(result.size),
+    total: Number(result.total),
+    pages: Number(result.pages),
+  }
+}
+export async function getPlatformPalletSummary(query: PlatformPalletQuery) {
+  const response = await http.get<ApiEnvelope<PlatformPalletSummary>, ApiEnvelope<PlatformPalletSummary>>(`${basePath}/summary`, { params: { tenantId: platformResourceScope, warehouseId: query.warehouseId || undefined, palletCode: query.palletCode?.trim() || undefined, palletType: query.palletType?.trim() || undefined, page: 1, size: 1 } })
+  const value = unwrapApiResponse(response); return { totalCount: Number(value.totalCount), idleCount: Number(value.idleCount), occupiedCount: Number(value.occupiedCount) }
+}
+
+export async function getPlatformPallet(
+  warehouseId: number | string,
+  id: number | string,
+) {
+  const response = await http.get<ApiEnvelope<PlatformPalletResource>, ApiEnvelope<PlatformPalletResource>>(
+    `${basePath}/${id}`,
+    { params: { tenantId: platformResourceScope, warehouseId } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function createPlatformPallet(payload: SavePlatformPalletRequest) {
+  const response = await http.post<ApiEnvelope<number | string>, ApiEnvelope<number | string>>(basePath, payload, {
+    params: { tenantId: platformResourceScope },
+  })
+  return unwrapApiResponse(response)
+}
+
+export async function updatePlatformPallet(
+  warehouseId: number | string,
+  id: number | string,
+  payload: SavePlatformPalletRequest,
+) {
+  const response = await http.put<ApiEnvelope<null>, ApiEnvelope<null>>(`${basePath}/${id}`, payload, {
+    params: { tenantId: platformResourceScope, warehouseId },
+  })
+  return unwrapApiResponse(response)
+}
+
+export async function deletePlatformPallet(
+  warehouseId: number | string,
+  id: number | string,
+) {
+  const response = await http.delete<ApiEnvelope<null>, ApiEnvelope<null>>(`${basePath}/${id}`, {
+    params: { tenantId: platformResourceScope, warehouseId },
+  })
+  return unwrapApiResponse(response)
+}
diff --git a/src/modules/warehouse-resources/pallets/pages/PalletsView.test.ts b/src/modules/warehouse-resources/pallets/pages/PalletsView.test.ts
new file mode 100644
index 00000000..31db58b7
--- /dev/null
+++ b/src/modules/warehouse-resources/pallets/pages/PalletsView.test.ts
@@ -0,0 +1,383 @@
+import ElementPlus from 'element-plus'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { createPinia, setActivePinia } from 'pinia'
+import { enableAutoUnmount, flushPromises, mount, type VueWrapper } from '@vue/test-utils'
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+import { listAllPlatformWarehouses, type PlatformWarehouseResource } from '@/modules/warehouses'
+import DataTable from '@/shared/components/DataTable.vue'
+import QueryToolbar from '@/shared/components/QueryToolbar.vue'
+import {
+  createPlatformPallet,
+  getPlatformPallet,
+  getPlatformPalletSummary,
+  listPlatformPallets,
+  type PlatformPalletResource,
+} from '../api/platformPallets'
+import PalletsView from './PalletsView.vue'
+
+const palletsSource = readFileSync(resolve(process.cwd(), 'src/modules/warehouse-resources/pallets/pages/PalletsView.vue'), 'utf8')
+
+vi.mock('@/modules/warehouses', () => ({ listAllPlatformWarehouses: vi.fn() }))
+vi.mock('../api/platformPallets', () => ({
+  listPlatformPallets: vi.fn(),
+  getPlatformPalletSummary: vi.fn(),
+  getPlatformPallet: vi.fn(),
+  createPlatformPallet: vi.fn(),
+  updatePlatformPallet: vi.fn(),
+  deletePlatformPallet: vi.fn(),
+}))
+
+class ResizeObserverStub implements ResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+
+function createMemoryStorage(): Storage {
+  const values = new Map<string, string>()
+  return {
+    get length() { return values.size },
+    clear: () => values.clear(),
+    getItem: (key) => values.get(key) ?? null,
+    key: (index) => [...values.keys()][index] ?? null,
+    removeItem: (key) => values.delete(key),
+    setItem: (key, value) => values.set(key, value),
+  }
+}
+
+const warehouse: PlatformWarehouseResource = {
+  id: '19001', tenantId: 0, warehouseCode: 'CN-YW-01', internalCode: null, warehouseName: '义乌收货仓',
+  warehouseType: 'DOMESTIC', countryCode: 'CN', timezone: 'Asia/Shanghai', contactName: null,
+  contactPhone: null, contactEmail: null, status: 'ACTIVE', remark: null,
+}
+
+const fbaWarehouse: PlatformWarehouseResource = {
+  ...warehouse,
+  id: '19002',
+  warehouseCode: 'FBA-ONT8',
+  internalCode: '154',
+  warehouseName: 'ONT8 FBA 仓',
+  warehouseType: 'FBA',
+}
+
+const overseasWarehouse: PlatformWarehouseResource = {
+  ...warehouse,
+  id: '19003',
+  warehouseCode: 'US-LAX-01',
+  internalCode: null,
+  warehouseName: '洛杉矶海外仓',
+  warehouseType: 'OVERSEAS',
+}
+
+const pallet: PlatformPalletResource = {
+  id: '20001', tenantId: 0, warehouseId: '19001', palletCode: 'TP-001', palletType: '木托盘',
+  capacityCbm: '1.200000', weightKg: '8.000', color: '黄色', remark: '标准川字托盘', createdAt: '2026-08-04T09:00:00', updatedAt: '2026-08-04T10:00:00',
+}
+
+async function mountView(permissions = [
+  'platform:pallet:list', 'platform:pallet:create', 'platform:pallet:edit', 'platform:pallet:delete',
+]) {
+  vi.stubGlobal('localStorage', createMemoryStorage())
+  vi.stubGlobal('sessionStorage', createMemoryStorage())
+  const pinia = createPinia()
+  setActivePinia(pinia)
+  const auth = useAuthStore()
+  auth.token = 'token'
+  auth.permissions = permissions
+  useAccessPreviewStore().initializeAfterLogin()
+  const wrapper = mount(PalletsView, { attachTo: document.body, global: { plugins: [pinia, ElementPlus] } })
+  await flushPromises()
+  return wrapper
+}
+
+async function setWarehouseFilter(wrapper: VueWrapper, warehouseId = '') {
+  wrapper.findComponent(QueryToolbar).vm.$emit('update:modelValue', {
+    warehouseId,
+    palletCode: '',
+    palletType: '',
+  })
+  await flushPromises()
+}
+
+async function loadRows(wrapper: VueWrapper, warehouseId = '') {
+  await setWarehouseFilter(wrapper, warehouseId)
+  wrapper.findComponent(QueryToolbar).vm.$emit('search', {
+    warehouseId,
+    palletCode: '',
+    palletType: '',
+  })
+  await flushPromises()
+}
+
+enableAutoUnmount(afterEach)
+afterAll(() => vi.unstubAllGlobals())
+
+const densitySource = readFileSync(resolve(process.cwd(), 'src/styles/adminDensity.css'), 'utf8')
+
+describe('PalletsView', () => {
+  it('uses bordered striped tables and explicit semantic row actions', () => {
+    expect(palletsSource).toContain('border')
+    expect(palletsSource).toContain('stripe')
+    expect(palletsSource).toContain('class="density-action" size="small" title="编辑托盘"')
+    expect(palletsSource).toContain('class="density-action" data-tone="danger"')
+    expect(palletsSource).not.toContain('<Eye :size="15" />')
+    expect(palletsSource).not.toContain('<Pencil :size="15" />')
+    expect(palletsSource).not.toContain('<Trash2 :size="15" />')
+    expect(palletsSource).toContain('@media (max-width: 720px)')
+  })
+  it('uses the prototype-sized centered editor without an extra detail drawer', () => {
+    expect(palletsSource).not.toContain('<AppDrawer')
+    expect(palletsSource).toContain('<AppDialog v-model="editorOpen" :title="editorTitle" width="min(560px, calc(100vw - 28px))"')
+    expect(palletsSource).not.toContain('<el-drawer v-model="editorOpen"')
+    expect(densitySource).toContain('.admin-density-dialog.el-dialog .el-dialog__body { min-height: 0; overflow-y: auto;')
+    expect(palletsSource).toContain('.editor-field-grid { grid-template-columns: minmax(0, 1fr); }')
+  })
+  beforeEach(() => {
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+    document.body.innerHTML = ''
+    vi.mocked(listAllPlatformWarehouses).mockReset().mockResolvedValue([warehouse, fbaWarehouse, overseasWarehouse])
+    vi.mocked(listPlatformPallets).mockReset().mockResolvedValue({ records: [pallet], page: 1, size: 20, total: 1, pages: 1 })
+    vi.mocked(getPlatformPalletSummary).mockReset().mockResolvedValue({ totalCount: 1, idleCount: 1, occupiedCount: 0 })
+    vi.mocked(getPlatformPallet).mockReset().mockResolvedValue(pallet)
+    vi.mocked(createPlatformPallet).mockReset().mockResolvedValue('20002')
+  })
+
+  it('starts with enabled domestic warehouse candidates for querying using compact filters', async () => {
+    const wrapper = await mountView()
+    const toolbar = wrapper.findComponent(QueryToolbar)
+    const fields = toolbar.props('fields')
+
+    expect(toolbar.props('modelValue')).toMatchObject({ warehouseId: '' })
+    expect(fields.map((field) => [field.key, field.width])).toEqual([
+      ['warehouseId', 300],
+      ['palletCode', 240],
+      ['palletType', 180],
+    ])
+    expect(wrapper.find('.pallet-filter-toolbar').exists()).toBe(true)
+    expect(fields.find((field) => field.key === 'warehouseId')?.placeholder).toBe('全部仓库')
+    expect(fields.find((field) => field.key === 'warehouseId')?.options).toEqual([
+      { label: '义乌收货仓（CN-YW-01）', value: '19001' },
+    ])
+    expect(listAllPlatformWarehouses).toHaveBeenCalledWith()
+    expect(listPlatformPallets).toHaveBeenCalledWith({
+      page: 1, size: 20,
+    })
+  })
+
+  it('loads all warehouses independently and omits an empty warehouse id when searching', async () => {
+    const wrapper = await mountView()
+    await loadRows(wrapper)
+
+    expect(listAllPlatformWarehouses).toHaveBeenCalledTimes(1)
+    expect(listAllPlatformWarehouses).toHaveBeenCalledWith()
+    expect(listPlatformPallets).toHaveBeenCalledWith({
+      page: 1, size: 20,
+    })
+    expect(wrapper.text()).toContain('TP-001')
+    expect(wrapper.text()).toContain('义乌收货仓')
+    expect(wrapper.text()).toContain('CN-YW-01')
+    expect(wrapper.text()).toContain('木托盘')
+    expect(wrapper.text()).toContain('1.2 m³')
+    expect(wrapper.text()).toContain('8 kg')
+    expect(wrapper.find('.data-table').text()).not.toContain('黄色')
+    expect(wrapper.find('.data-table').text()).not.toContain('标准川字托盘')
+    expect(wrapper.text()).not.toContain('更新时间')
+    const tableToolbar = wrapper.find('.table-panel .data-table__toolbar')
+    expect(tableToolbar.exists()).toBe(true)
+    expect(tableToolbar.text()).toContain('新增托盘')
+    expect(tableToolbar.text()).not.toContain('托盘列表')
+    expect(wrapper.find('.data-table__pagination-left').text()).toContain('共 1 个托盘')
+    expect(wrapper.text()).not.toContain('启停托盘')
+    expect(wrapper.text()).not.toContain('全部状态')
+    expect(wrapper.text()).toContain('全部托盘类型')
+    expect(wrapper.find('input[aria-label="客户"]').exists()).toBe(false)
+    expect(wrapper.find('input[aria-label="所属仓库"]').exists()).toBe(true)
+    expect(wrapper.find('.platform-tenant-selector').exists()).toBe(false)
+    expect(wrapper.text()).not.toContain('租户')
+    expect(wrapper.find('.data-table').exists()).toBe(true)
+    expect(wrapper.find('.density-actions.pallet-row-actions').exists()).toBe(true)
+    expect(wrapper.findAll('thead th').map((item) => item.text().trim())).toEqual([
+      '操作', '托盘编码', '所属仓库', '托盘类型', '托盘容积（m³）', '托盘重量（kg）',
+    ])
+  })
+
+  it('queries all customers explicitly without adding a customer id', async () => {
+    vi.mocked(listPlatformPallets).mockResolvedValue({ records: [pallet], page: 1, size: 20, total: 41, pages: 3 })
+    const wrapper = await mountView()
+    const toolbar = wrapper.findComponent(QueryToolbar)
+
+    toolbar.vm.$emit('search', { warehouseId: '', palletCode: '', palletType: '' })
+    await flushPromises()
+    expect(listPlatformPallets).toHaveBeenLastCalledWith({
+      page: 1, size: 20,
+    })
+
+  })
+
+  it('resets the warehouse filter without sending an empty id', async () => {
+    const wrapper = await mountView()
+    await setWarehouseFilter(wrapper, '19001')
+    const toolbar = wrapper.findComponent(QueryToolbar)
+
+    toolbar.vm.reset()
+    await flushPromises()
+
+    expect(toolbar.props('modelValue')).toMatchObject({ warehouseId: '' })
+    expect(listPlatformPallets).toHaveBeenCalledTimes(2)
+    expect(listPlatformPallets).toHaveBeenLastCalledWith({
+      page: 1, size: 20,
+    })
+    expect(toolbar.props('fields').find((field) => field.key === 'warehouseId')?.placeholder).toBe('全部仓库')
+  })
+
+  it('does not expose customer ownership in warehouse choices', async () => {
+    const wrapper = await mountView()
+    const warehouseField = wrapper.findComponent(QueryToolbar).props('fields').find((field) => field.key === 'warehouseId')
+
+    expect(listAllPlatformWarehouses).toHaveBeenCalledTimes(1)
+    expect(warehouseField?.options).toEqual([
+      { label: '义乌收货仓（CN-YW-01）', value: '19001' },
+    ])
+  })
+
+  it('does not offer editing for a pallet outside a domestic warehouse', async () => {
+    vi.mocked(listPlatformPallets).mockResolvedValue({
+      records: [{ ...pallet, id: '20002', warehouseId: fbaWarehouse.id }, pallet], page: 1, size: 20, total: 2, pages: 1,
+    })
+    const wrapper = await mountView()
+
+    const bodyRows = wrapper.findAll('.el-table__body-wrapper tbody tr')
+    expect(bodyRows[0]?.text()).not.toContain('编辑')
+    expect(bodyRows[1]?.text()).toContain('编辑')
+  })
+
+  it('applies pallet filters only after search', async () => {
+    const wrapper = await mountView()
+    await setWarehouseFilter(wrapper, '19001')
+    await wrapper.find('input[placeholder="托盘编码（模糊查询）"]').setValue('TP-00')
+    expect(listPlatformPallets).toHaveBeenCalledTimes(1)
+
+    wrapper.findComponent(QueryToolbar).vm.$emit('search', {
+      warehouseId: '19001', palletCode: 'TP-00', palletType: '木托盘',
+    })
+    await flushPromises()
+
+    expect(listPlatformPallets).toHaveBeenLastCalledWith({
+      page: 1, size: 20, warehouseId: 19001, palletCode: 'TP-00', palletType: '木托盘',
+    })
+  })
+
+  it('creates a pallet in the selected warehouse with the real request fields', async () => {
+    const wrapper = await mountView()
+    await setWarehouseFilter(wrapper, '19001')
+    const createButton = wrapper.findAll('button').find((button) => button.text().trim() === '新增托盘')
+    await createButton?.trigger('click')
+    await flushPromises()
+
+    const palletTypeItem = wrapper.findAll('.el-form-item').find((item) => item.text().includes('托盘类型'))
+    palletTypeItem?.findComponent({ name: 'ElSelect' }).vm.$emit('update:modelValue', '塑料托盘')
+    const inputNumbers = wrapper.findAllComponents({ name: 'ElInputNumber' })
+    inputNumbers[0]?.vm.$emit('update:modelValue', 1.5)
+    inputNumbers[1]?.vm.$emit('update:modelValue', 10)
+    await wrapper.find('input[placeholder="例如 黄色"]').setValue('黑色')
+    await wrapper.find('input[placeholder="选填"]').setValue('标准托盘')
+    const saveButton = wrapper.findAll('button').find((button) => button.text().trim() === '保存托盘')
+    await saveButton?.trigger('click')
+    await flushPromises()
+
+    expect(createPlatformPallet).toHaveBeenCalledWith({
+      warehouseId: 19001, palletType: '塑料托盘', capacityCbm: 1.5, weightKg: 10, color: '黑色', remark: '标准托盘',
+    })
+  })
+
+  it('uses a compact three-row two-column editor', async () => {
+    const wrapper = await mountView()
+    const createButton = wrapper.findAll('button').find((button) => button.text().trim() === '新增托盘')
+    await createButton?.trigger('click')
+    await flushPromises()
+
+    const editorDialog = document.body.querySelector('.pallet-editor-dialog')
+    expect(editorDialog?.textContent).toContain('新增托盘')
+    expect(editorDialog?.querySelector('.el-dialog__title')?.textContent).toBe('新增托盘')
+    expect(document.body.querySelectorAll('.editor-field-grid')).toHaveLength(3)
+    expect(document.body.querySelector('.editor-section')).toBeNull()
+    expect(document.body.querySelector('.editor-context')).toBeNull()
+    expect(document.body.querySelector('.pallet-editor-footer')?.textContent).toContain('为必填项')
+  })
+
+  it('hides all write actions without write permissions', async () => {
+    const wrapper = await mountView(['platform:pallet:list'])
+
+    expect(wrapper.find('.panel-heading button').exists()).toBe(false)
+    const actions = wrapper.find('.pallet-row-actions').text()
+    expect(actions).not.toContain('编辑')
+    expect(actions).not.toContain('删除')
+    expect(actions).not.toContain('查看')
+  })
+
+  it('shows a recoverable list failure instead of demo data', async () => {
+    vi.mocked(listPlatformPallets).mockRejectedValueOnce(new Error('Gateway unavailable'))
+    const wrapper = await mountView()
+
+    expect(wrapper.text()).toContain('托盘列表暂时无法加载')
+    expect(wrapper.text()).not.toContain('Gateway unavailable')
+    expect(wrapper.text()).toContain('重新加载')
+    expect(wrapper.text()).not.toContain('TP-001')
+  })
+
+  it('keeps platform warehouse and pallet queries independent from customer names', async () => {
+    const wrapper = await mountView()
+
+    expect(wrapper.text()).not.toContain('客户列表暂时无法加载')
+    expect(wrapper.text()).not.toContain('所属企业')
+    expect(listAllPlatformWarehouses).toHaveBeenCalledWith()
+    expect(listPlatformPallets).toHaveBeenCalledWith({
+      page: 1, size: 20,
+    })
+  })
+
+  it('keeps the list limited to fields exposed by the backend contract', async () => {
+    const publicPallet = { ...pallet, tenantId: '0' }
+    vi.mocked(listPlatformPallets).mockResolvedValue({ records: [publicPallet], page: 1, size: 20, total: 1, pages: 1 })
+    vi.mocked(getPlatformPallet).mockResolvedValue(publicPallet)
+    const wrapper = await mountView()
+    await loadRows(wrapper)
+    expect(wrapper.findComponent(DataTable).props('data')).toEqual([publicPallet])
+    const tableText = wrapper.find('.data-table').text()
+    expect(tableText).toContain('托盘编码')
+    expect(tableText).toContain('托盘类型')
+    expect(tableText).toContain('托盘容积')
+    expect(tableText).not.toContain('所属企业')
+    expect(tableText).not.toContain('企业 ID')
+    expect(tableText).not.toContain('租户')
+    expect(tableText).not.toContain('托盘状态')
+    expect(tableText).not.toContain('最大承重')
+  })
+
+  it('keeps the latest pallet selected for editing', async () => {
+    const secondPallet = { ...pallet, id: '20002', palletCode: 'TP-002', color: '蓝色' }
+    let resolveFirst!: (value: PlatformPalletResource) => void
+    let resolveSecond!: (value: PlatformPalletResource) => void
+    vi.mocked(getPlatformPallet).mockImplementation((_warehouseId, palletId) => new Promise((resolve) => {
+      if (String(palletId) === String(pallet.id)) resolveFirst = resolve
+      else resolveSecond = resolve
+    }))
+    const wrapper = await mountView()
+    const vm = wrapper.vm as unknown as {
+      form: { palletCode: string; color: string }
+      openEdit(row: PlatformPalletResource): Promise<void>
+    }
+
+    void vm.openEdit(pallet)
+    void vm.openEdit(secondPallet)
+    resolveSecond(secondPallet)
+    await flushPromises()
+    resolveFirst(pallet)
+    await flushPromises()
+
+    expect(vm.form).toMatchObject({ palletCode: 'TP-002', color: '蓝色' })
+  })
+})
diff --git a/src/modules/warehouse-resources/pallets/pages/PalletsView.vue b/src/modules/warehouse-resources/pallets/pages/PalletsView.vue
new file mode 100644
index 00000000..d8b50dce
--- /dev/null
+++ b/src/modules/warehouse-resources/pallets/pages/PalletsView.vue
@@ -0,0 +1,523 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, reactive, ref, watch } from 'vue'
+import { ElMessage, ElMessageBox, type FormInstance, type FormRules } from 'element-plus'
+import { Boxes, Plus, Save, Warehouse as WarehouseIcon } from '@lucide/vue'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useUnsavedWorkRegistration } from '@/core/unsaved-work/useUnsavedWorkRegistration'
+import { listAllPlatformWarehouses, type PlatformWarehouseResource } from '@/modules/warehouses'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import {
+  createPlatformPallet,
+  deletePlatformPallet,
+  getPlatformPallet,
+  getPlatformPalletSummary,
+  listPlatformPallets,
+  updatePlatformPallet,
+  type PlatformPalletResource,
+  type PlatformPalletSummary,
+  type SavePlatformPalletRequest,
+} from '../api/platformPallets'
+
+const access = useAccessPreviewStore()
+const warehouses = ref<PlatformWarehouseResource[]>([])
+const warehouseLoading = ref(false)
+const warehouseError = ref<ApiErrorDetails | null>(null)
+const rows = ref<PlatformPalletResource[]>([])
+const loading = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const page = ref(1)
+const pageSize = ref(20)
+const total = ref(0)
+const summary = ref<PlatformPalletSummary>({ totalCount: 0, idleCount: 0, occupiedCount: 0 })
+const editorOpen = ref(false)
+const saving = ref(false)
+const deletingIds = ref(new Set<string>())
+const formRef = ref<FormInstance>()
+let warehouseSequence = 0
+let palletSequence = 0
+let editorSequence = 0
+
+type PalletFilters = QueryModel & { warehouseId: string; palletCode: string; palletType: string }
+type AppliedPalletFilters = Pick<PalletFilters, 'warehouseId' | 'palletCode' | 'palletType'>
+const filters = ref<PalletFilters>({ warehouseId: '', palletCode: '', palletType: '' })
+const appliedFilters = ref<AppliedPalletFilters>({ warehouseId: '', palletCode: '', palletType: '' })
+const palletTypeOptions = ['木托盘', '塑料托盘', '金属托盘', '纸托盘', '免熏蒸托盘']
+const queryFields = computed<QueryField[]>(() => [
+  {
+    key: 'warehouseId',
+    type: 'select',
+    label: '所属仓库',
+    width: 300,
+    placeholder: warehouseLoading.value ? '正在加载所属仓库' : warehouseError.value ? '所属仓库加载失败' : '全部仓库',
+    options: domesticWarehouses.value.map((warehouse) => ({
+      label: `${warehouse.warehouseName}（${warehouse.warehouseCode}）`,
+      value: String(warehouse.id),
+    })),
+    props: {
+      filterable: true,
+      disabled: contextLocked.value || warehouseLoading.value || Boolean(warehouseError.value),
+      'aria-label': '所属仓库',
+    },
+  },
+  { key: 'palletCode', type: 'input', width: 240, label: '托盘编码', placeholder: '托盘编码（模糊查询）', props: { maxlength: 50, 'aria-label': '托盘编码' } },
+  {
+    key: 'palletType',
+    type: 'select',
+    label: '托盘类型',
+    width: 180,
+    placeholder: '全部托盘类型',
+    options: palletTypeOptions.map((value) => ({ label: value, value })),
+    props: { filterable: true, allowCreate: true, defaultFirstOption: true, 'aria-label': '托盘类型' },
+  },
+])
+
+const emptyForm = () => ({ id: '', warehouseId: '', palletCode: '', palletType: '', capacityCbm: null as number | null, weightKg: null as number | null, color: '', remark: '' })
+const form = reactive(emptyForm())
+const rules: FormRules<typeof form> = {
+  warehouseId: [{ required: true, message: '请选择国内仓', trigger: 'change' }],
+  palletType: [
+    { required: true, message: '请输入托盘类型', trigger: 'blur' },
+    { max: 32, message: '托盘类型不能超过 32 个字符', trigger: 'blur' },
+  ],
+  capacityCbm: [{
+    validator: (_rule, value, callback) => {
+      if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) callback(new Error('请输入大于 0 的托盘容积'))
+      else callback()
+    },
+    trigger: 'change',
+  }],
+  weightKg: [{
+    validator: (_rule, value, callback) => {
+      if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) callback(new Error('请输入大于 0 的托盘重量'))
+      else callback()
+    },
+    trigger: 'change',
+  }],
+  color: [
+    { required: true, message: '请输入托盘颜色', trigger: 'blur' },
+    { max: 32, message: '托盘颜色不能超过 32 个字符', trigger: 'blur' },
+  ],
+  remark: [{ max: 500, message: '备注不能超过 500 个字符', trigger: 'blur' }],
+}
+
+const editorWarehouse = computed(() => warehouses.value.find((item) => String(item.id) === form.warehouseId) || null)
+const domesticWarehouses = computed(() => warehouses.value.filter((warehouse) => (
+  warehouse.warehouseType === 'DOMESTIC' && warehouse.status === 'ACTIVE'
+)))
+const editorTitle = computed(() => form.id ? '编辑托盘' : '新增托盘')
+const editorPermission = computed(() => form.id ? 'platform:pallet:edit' : 'platform:pallet:create')
+const contextLocked = computed(() => editorOpen.value || saving.value || deletingIds.value.size > 0)
+const filtered = computed(() => Object.values(appliedFilters.value).some((value) => String(value || '').trim()))
+
+const { captureBaseline } = useUnsavedWorkRegistration({
+  key: 'pallet-editor',
+  label: editorTitle,
+  isOpen: editorOpen,
+  model: form,
+  requiredPermission: editorPermission,
+})
+
+const columns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', minWidth: 160, fixed: 'left', slotName: 'actions' },
+  { key: 'pallet', label: '托盘编码', minWidth: 190, slotName: 'pallet' },
+  { key: 'warehouse', label: '所属仓库', minWidth: 210, slotName: 'warehouse' },
+  { key: 'palletType', prop: 'palletType', label: '托盘类型', minWidth: 140 },
+  { key: 'capacity', label: '托盘容积（m³）', minWidth: 160, slotName: 'capacity' },
+  { key: 'weight', label: '托盘重量（kg）', minWidth: 160, slotName: 'weight' },
+  { key: 'color', prop: 'color', label: '颜色', minWidth: 120, defaultVisible: false },
+  { key: 'remark', label: '备注', minWidth: 220, slotName: 'remark', defaultVisible: false },
+]
+
+function apiId(value: string) {
+  const numeric = Number(value)
+  return Number.isSafeInteger(numeric) ? numeric : value
+}
+
+function formatCapacity(value: number | string) {
+  const numeric = Number(value)
+  if (!Number.isFinite(numeric)) return String(value)
+  return `${numeric.toLocaleString('zh-CN', { maximumFractionDigits: 6 })} m³`
+}
+
+function formatWeight(value: number | string | null) {
+  if (value === null) return '—'
+  const numeric = Number(value)
+  if (!Number.isFinite(numeric)) return String(value)
+  return `${numeric.toLocaleString('zh-CN', { maximumFractionDigits: 3 })} kg`
+}
+
+function warehouseFor(warehouseId: number | string) {
+  return warehouses.value.find((item) => String(item.id) === String(warehouseId)) || null
+}
+
+function isDomesticWarehouse(warehouseId: number | string) {
+  return warehouseFor(warehouseId)?.warehouseType === 'DOMESTIC'
+}
+
+function isActiveDomesticWarehouse(warehouseId: number | string) {
+  return domesticWarehouses.value.some((warehouse) => String(warehouse.id) === String(warehouseId))
+}
+
+function errorMessage(details: ApiErrorDetails) {
+  return details.requestId ? `${details.message}（requestId: ${details.requestId}）` : details.message
+}
+
+async function loadWarehouses() {
+  const sequence = ++warehouseSequence
+  warehouses.value = []
+  warehouseError.value = null
+  warehouseLoading.value = true
+  try {
+    const records = await listAllPlatformWarehouses()
+    if (sequence !== warehouseSequence) return
+    warehouses.value = records
+  } catch (error) {
+    if (sequence !== warehouseSequence) return
+    warehouseError.value = getApiErrorDetails(error, '仓库列表加载失败，请稍后重试')
+  } finally {
+    if (sequence === warehouseSequence) warehouseLoading.value = false
+  }
+}
+
+async function loadPallets() {
+  const sequence = ++palletSequence
+  loadError.value = null
+  loading.value = true
+  try {
+    const query = {
+      page: page.value,
+      size: pageSize.value,
+      ...(appliedFilters.value.warehouseId ? { warehouseId: apiId(appliedFilters.value.warehouseId) } : {}),
+      ...(appliedFilters.value.palletCode ? { palletCode: appliedFilters.value.palletCode } : {}),
+      ...(appliedFilters.value.palletType ? { palletType: appliedFilters.value.palletType } : {}),
+    }
+    const [result, summaryResult] = await Promise.all([listPlatformPallets(query), getPlatformPalletSummary(query)])
+    if (sequence !== palletSequence) return
+    rows.value = result.records
+    total.value = result.total
+    summary.value = summaryResult
+  } catch (error) {
+    if (sequence !== palletSequence) return
+    loadError.value = getApiErrorDetails(error, '托盘列表加载失败，请稍后重试')
+  } finally {
+    if (sequence === palletSequence) loading.value = false
+  }
+}
+
+function applyFilters(model: QueryModel) {
+  appliedFilters.value = {
+    warehouseId: String(model.warehouseId || ''),
+    palletCode: String(model.palletCode || ''),
+    palletType: String(model.palletType || ''),
+  }
+  if (page.value === 1) void loadPallets()
+  else page.value = 1
+}
+
+function resetFilters() {
+  appliedFilters.value = { warehouseId: '', palletCode: '', palletType: '' }
+  if (page.value === 1) void loadPallets()
+  else page.value = 1
+}
+
+function openCreate() {
+  editorSequence += 1
+  Object.assign(form, emptyForm())
+  form.warehouseId = isActiveDomesticWarehouse(filters.value.warehouseId) ? filters.value.warehouseId : ''
+  editorOpen.value = true
+  captureBaseline()
+  void formRef.value?.clearValidate()
+}
+
+function assignForm(resource: PlatformPalletResource) {
+  Object.assign(form, {
+    id: String(resource.id),
+    warehouseId: String(resource.warehouseId),
+    palletCode: resource.palletCode,
+    palletType: resource.palletType,
+    capacityCbm: Number(resource.capacityCbm),
+    weightKg: resource.weightKg === null ? null : Number(resource.weightKg),
+    color: resource.color || '',
+    remark: resource.remark || '',
+  })
+  editorOpen.value = true
+  captureBaseline()
+  void formRef.value?.clearValidate()
+}
+
+async function fetchDetail(row: PlatformPalletResource) {
+  return getPlatformPallet(apiId(String(row.warehouseId)), row.id)
+}
+
+async function openEdit(row: PlatformPalletResource) {
+  if (!isDomesticWarehouse(row.warehouseId)) {
+    ElMessage.warning('仅支持编辑国内仓托盘')
+    return
+  }
+  const sequence = ++editorSequence
+  try {
+    const result = await fetchDetail(row)
+    if (sequence !== editorSequence) return
+    assignForm(result)
+  } catch (error) {
+    if (sequence !== editorSequence) return
+    ElMessage.error(errorMessage(getApiErrorDetails(error, '托盘详情加载失败，请稍后重试')))
+  }
+}
+
+async function savePallet() {
+  if (!await formRef.value?.validate().catch(() => false) || form.capacityCbm === null || form.weightKg === null) return
+  const warehouse = editorWarehouse.value
+  const warehouseAllowed = form.id
+    ? warehouse?.warehouseType === 'DOMESTIC'
+    : warehouse?.warehouseType === 'DOMESTIC' && warehouse.status === 'ACTIVE'
+  if (!warehouse || !warehouseAllowed) {
+    ElMessage.error(form.id ? '托盘仅支持归属国内仓' : '新增托盘仅支持选择启用的国内仓')
+    return
+  }
+  saving.value = true
+  const payload: SavePlatformPalletRequest = {
+    warehouseId: apiId(form.warehouseId),
+    palletType: form.palletType.trim(),
+    capacityCbm: form.capacityCbm,
+    weightKg: form.weightKg,
+    color: form.color.trim(),
+    remark: form.remark.trim() || null,
+  }
+  try {
+    if (form.id) await updatePlatformPallet(apiId(form.warehouseId), form.id, payload)
+    else await createPlatformPallet(payload)
+    ElMessage.success(form.id ? '托盘已更新' : '托盘已新增')
+    editorOpen.value = false
+    await loadPallets()
+  } catch (error) {
+    ElMessage.error(errorMessage(getApiErrorDetails(error, '托盘保存失败，请稍后重试')))
+  } finally {
+    saving.value = false
+  }
+}
+
+async function removePallet(row: PlatformPalletResource) {
+  try {
+    await ElMessageBox.confirm(
+      `确定删除托盘“${row.palletCode}”吗？已预占或已占用的托盘无法删除。`,
+      '删除托盘',
+      { customClass: 'admin-density-confirm', confirmButtonText: '删除', cancelButtonText: '取消', type: 'warning', confirmButtonClass: 'el-button--danger' },
+    )
+  } catch {
+    return
+  }
+  const id = String(row.id)
+  deletingIds.value = new Set([...deletingIds.value, id])
+  try {
+    await deletePlatformPallet(apiId(String(row.warehouseId)), row.id)
+    ElMessage.success('托盘已删除')
+    if (rows.value.length === 1 && page.value > 1) page.value -= 1
+    else await loadPallets()
+  } catch (error) {
+    ElMessage.error(errorMessage(getApiErrorDetails(error, '托盘删除失败，请稍后重试')))
+  } finally {
+    const next = new Set(deletingIds.value)
+    next.delete(id)
+    deletingIds.value = next
+  }
+}
+
+watch([page, pageSize], ([nextPage, nextSize], [previousPage, previousSize]) => {
+  if (nextPage === previousPage && nextSize === previousSize) return
+  void loadPallets()
+})
+watch(() => access.can(editorPermission.value), (canWrite) => {
+  if (!canWrite && editorOpen.value) editorOpen.value = false
+}, { flush: 'sync' })
+onMounted(() => {
+  void loadWarehouses()
+  void loadPallets()
+})
+</script>
+
+<template>
+  <AdminPage as="div" class="pallet-page admin-density">
+    <section class="summary-grid" aria-label="托盘数量概览">
+      <article><span>托盘总数</span><strong>{{ summary.totalCount }}</strong></article>
+      <article><span>闲置托盘</span><strong class="idle">{{ summary.idleCount }}</strong></article>
+      <article><span>占用托盘</span><strong class="occupied">{{ summary.occupiedCount }}</strong></article>
+    </section>
+    <ListPageLayout aria-label="托盘列表页面">
+      <template #toolbar>
+        <QueryToolbar
+          v-model="filters"
+          class="surface-panel pallet-filter-toolbar"
+          ariaLabel="托盘筛选"
+          :fields="queryFields"
+          preference-key="pallets-query"
+          :search-on-reset="false"
+          @search="applyFilters"
+          @reset="resetFilters"
+        />
+      </template>
+      <template #state>
+        <LoadErrorState
+          v-if="warehouseError"
+          title="仓库列表暂时无法加载"
+          :message="warehouseError.message"
+          :loading="warehouseLoading"
+          @retry="loadWarehouses"
+        />
+        <LoadErrorState
+          v-else-if="loadError"
+          title="托盘列表暂时无法加载"
+          :message="loadError.message"
+          :loading="loading"
+          @retry="loadPallets"
+        />
+      </template>
+
+      <section v-if="!loadError" class="table-panel surface-panel" aria-label="托盘列表区域">
+      <DataTable
+        v-model:page="page"
+        v-model:page-size="pageSize"
+        :data="rows"
+        :columns="columns"
+        border
+        stripe
+        preference-key="pallets-table"
+        :loading="loading || warehouseLoading"
+        :total="total"
+        row-key="id"
+        :empty-text="filtered ? '暂无符合筛选条件的托盘' : '暂无托盘数据'"
+        aria-label="托盘列表"
+      >
+        <template #toolbar-actions><el-button v-if="access.can('platform:pallet:create')" type="primary" @click="openCreate"><Plus :size="16" />新增托盘</el-button></template>
+        <template #actions="{ row }">
+          <div class="pallet-row-actions density-actions">
+            <el-button v-if="access.can('platform:pallet:edit') && isDomesticWarehouse((row as PlatformPalletResource).warehouseId)" class="density-action" size="small" title="编辑托盘" @click="openEdit(row as PlatformPalletResource)">编辑</el-button>
+            <el-button
+              v-if="access.can('platform:pallet:delete')"
+              size="small"
+              class="density-action" data-tone="danger"
+              title="删除托盘"
+              :loading="deletingIds.has(String((row as PlatformPalletResource).id))"
+              @click="removePallet(row as PlatformPalletResource)"
+            >删除</el-button>
+          </div>
+        </template>
+        <template #pallet="{ row }">
+          <div class="pallet-cell"><span><Boxes :size="18" /></span><strong>{{ (row as PlatformPalletResource).palletCode }}</strong></div>
+        </template>
+        <template #warehouse="{ row }">
+          <div class="stacked-value"><strong>{{ warehouseFor((row as PlatformPalletResource).warehouseId)?.warehouseName || '—' }}</strong><small>{{ warehouseFor((row as PlatformPalletResource).warehouseId)?.warehouseCode || '—' }}</small></div>
+        </template>
+        <template #capacity="{ row }"><strong>{{ formatCapacity((row as PlatformPalletResource).capacityCbm) }}</strong></template>
+        <template #weight="{ row }"><strong>{{ formatWeight((row as PlatformPalletResource).weightKg) }}</strong></template>
+        <template #remark="{ row }"><span class="remark-text">{{ (row as PlatformPalletResource).remark || '—' }}</span></template>
+        <template #pagination-left="{ total: tableTotal }"><span>共 {{ tableTotal }} 个托盘</span></template>
+      </DataTable>
+      </section>
+    </ListPageLayout>
+
+    <AppDialog v-model="editorOpen" :title="editorTitle" width="min(560px, calc(100vw - 28px))" class="pallet-editor-dialog admin-density-dialog" :close-on-click-modal="false" :confirm-loading="saving" :show-confirm="false" destroy-on-close>
+      <el-form ref="formRef" :model="form" :rules="rules" label-position="top" class="editor-form">
+        <div class="editor-field-grid">
+          <el-form-item label="所属仓库" prop="warehouseId" required>
+            <el-select v-model="form.warehouseId" filterable placeholder="请选择国内仓" :loading="warehouseLoading">
+              <el-option
+                v-for="warehouse in domesticWarehouses"
+                :key="String(warehouse.id)"
+                :label="`${warehouse.warehouseName}（${warehouse.warehouseCode}）`"
+                :value="String(warehouse.id)"
+              />
+            </el-select>
+          </el-form-item>
+          <el-form-item label="托盘类型" prop="palletType" required>
+              <el-select
+                v-model="form.palletType"
+                filterable
+                allow-create
+                default-first-option
+                placeholder="请选择或输入托盘类型"
+                aria-label="编辑托盘类型"
+              >
+                <el-option v-for="type in palletTypeOptions" :key="type" :label="type" :value="type" />
+              </el-select>
+          </el-form-item>
+        </div>
+        <div class="editor-field-grid">
+          <el-form-item label="托盘容积（m³）" prop="capacityCbm" required>
+              <el-input-number v-model="form.capacityCbm" :min="0.000001" :max="999999999999.999999" :precision="6" :step="0.1" controls-position="right" aria-label="托盘容积" placeholder="请输入托盘容积" />
+          </el-form-item>
+          <el-form-item label="托盘重量（kg）" prop="weightKg" required>
+              <el-input-number v-model="form.weightKg" :min="0.001" :max="999999999999999.999" :precision="3" :step="0.5" controls-position="right" aria-label="托盘重量" placeholder="请输入托盘重量" />
+          </el-form-item>
+        </div>
+        <div class="editor-field-grid">
+          <el-form-item label="颜色" prop="color" required>
+            <el-input v-model="form.color" maxlength="32" show-word-limit placeholder="例如 黄色" />
+          </el-form-item>
+          <el-form-item label="备注" prop="remark" class="editor-remark-field">
+            <el-input v-model="form.remark" maxlength="500" show-word-limit placeholder="选填" />
+          </el-form-item>
+        </div>
+      </el-form>
+      <template #footer>
+        <div class="drawer-footer pallet-editor-footer">
+          <span><i aria-hidden="true">*</i> 为必填项</span>
+          <div><el-button :disabled="saving" @click="editorOpen = false">取消</el-button><el-button type="primary" :loading="saving" @click="savePallet"><Save :size="16" />保存托盘</el-button></div>
+        </div>
+      </template>
+    </AppDialog>
+  </AdminPage>
+</template>
+
+<style scoped>
+.pallet-page { display: grid; min-width: 0; gap: var(--admin-space-6, 16px); }
+.summary-grid { display:flex; flex-wrap:wrap; gap:var(--admin-space-3, 8px) 28px; padding:var(--admin-space-3, 8px) var(--admin-space-5, 12px); border:1px solid var(--cc-border); background:var(--admin-surface, #fff); }
+.summary-grid article { display:flex; align-items:baseline; gap:var(--admin-space-3, 8px); }
+.summary-grid span { color:var(--cc-muted); font-size:var(--admin-font-caption, 12px); }.summary-grid strong { font-size:var(--admin-font-section, 14px); }.summary-grid .idle { color:var(--el-color-success); }.summary-grid .occupied { color:var(--el-color-warning); }
+.surface-panel { overflow: hidden; border: 1px solid var(--cc-border); border-radius: var(--admin-radius, 4px); background: var(--admin-surface, #fff); }
+.table-panel { min-width: 0; }
+.context-empty { padding: var(--admin-space-6, 16px); color: var(--cc-muted); text-align: center; }
+.pallet-row-actions { white-space: nowrap; }
+.pallet-cell { display: flex; align-items: center; gap: var(--admin-space-4, 10px); }
+.stacked-value { display: grid; min-width: 0; gap: 3px; }
+.stacked-value strong, .stacked-value small { overflow-wrap: anywhere; }
+.stacked-value small { color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); }
+.pallet-cell > span { display: inline-flex; align-items: center; justify-content: center; flex: 0 0 auto; border-radius: 8px; background: var(--el-color-primary-light-9); color: var(--cc-primary); }
+.pallet-cell > span { width: 20px; height: 20px; }
+.remark-text { display: -webkit-box; overflow: hidden; -webkit-box-orient: vertical; -webkit-line-clamp: 2; line-height: 1.55; }
+.editor-form { padding: 0; }
+.editor-field-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 0 14px; }
+.editor-form :deep(.el-input-number), .editor-form :deep(.el-select) { width: 100%; }
+.editor-form :deep(.el-form-item) { margin-bottom: 14px; }
+.editor-form :deep(.el-form-item__label) { padding-bottom: var(--admin-space-1, 4px); color: #344054; font-size: var(--admin-font-caption, 12px); font-weight: 650; line-height: 1.4; }
+@media (max-width: 720px) {
+  .summary-grid { grid-template-columns:1fr; }
+  .editor-field-grid { grid-template-columns: minmax(0, 1fr); }
+}
+.editor-remark-field { margin-bottom: 0 !important; }
+.field-help { margin: var(--admin-space-2, 6px) 0 0; color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); line-height: 1.5; }
+.drawer-footer { display: flex; justify-content: flex-end; gap: var(--admin-space-3, 8px); }
+.drawer-footer :deep(.el-button + .el-button) { margin-left: 0; }
+.pallet-editor-footer { align-items: center; justify-content: space-between; }
+.pallet-editor-footer > span { color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); }
+.pallet-editor-footer > span i { color: var(--el-color-danger); font-style: normal; }
+.pallet-editor-footer > div { display: flex; gap: var(--admin-space-3, 8px); }
+.pallet-editor-footer > div :deep(.el-button + .el-button) { margin-left: 0; }
+
+@media (max-width: 720px) {
+  .pallet-row-actions :deep(.el-button) { min-height: 36px; padding-inline: 5px; }
+  .editor-form { padding-right: 16px; padding-left: 16px; }
+  .editor-field-grid { grid-template-columns: 1fr; }
+  .pallet-editor-footer { display: block; }
+  .pallet-editor-footer > span { display: none; }
+  .pallet-editor-footer > div { display: grid; grid-template-columns: 1fr 1fr; }
+  .pallet-editor-footer :deep(.el-button) { min-height: 44px; margin-left: 0; }
+}
+</style>
diff --git a/src/modules/warehouse-resources/routes.ts b/src/modules/warehouse-resources/routes.ts
new file mode 100644
index 00000000..a661cfcb
--- /dev/null
+++ b/src/modules/warehouse-resources/routes.ts
@@ -0,0 +1,24 @@
+import type { RouteRecordRaw } from 'vue-router'
+
+export const warehouseResourceRoutes = [
+  {
+    path: 'master-data/locations',
+    name: 'locations',
+    component: () => import('./locations/pages/LocationsView.vue'),
+    meta: {
+      title: '库位管理',
+      description: '维护平台仓库库位和可用状态',
+      permission: 'platform:location:list',
+    },
+  },
+  {
+    path: 'master-data/pallets',
+    name: 'pallets',
+    component: () => import('./pallets/pages/PalletsView.vue'),
+    meta: {
+      title: '托盘管理',
+      description: '维护平台仓库托盘和可用容积',
+      permission: 'platform:pallet:list',
+    },
+  },
+] satisfies RouteRecordRaw[]
diff --git a/src/modules/warehouses/api/platformWarehouses.test.ts b/src/modules/warehouses/api/platformWarehouses.test.ts
new file mode 100644
index 00000000..4871ab90
--- /dev/null
+++ b/src/modules/warehouses/api/platformWarehouses.test.ts
@@ -0,0 +1,259 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from '@/shared/api/http'
+import {
+  changePlatformWarehouseStatus,
+  createFbaWarehouse,
+  createPlatformWarehouse,
+  getPlatformWarehouse,
+  importWarehouses,
+  listAllPlatformWarehouses,
+  listPlatformWarehouses,
+  updatePlatformWarehouse,
+  type SavePlatformWarehouseRequest,
+} from './platformWarehouses'
+
+vi.mock('@/shared/api/http', () => ({
+  http: { get: vi.fn(), post: vi.fn(), put: vi.fn(), patch: vi.fn() },
+  unwrapApiResponse: <T>(response: { data: T }) => response.data,
+}))
+
+const payload: SavePlatformWarehouseRequest = {
+  warehouseCode: 'CN-YW-01',
+  internalCode: null,
+  warehouseName: '义乌收货仓',
+  warehouseType: 'DOMESTIC',
+  countryCode: 'CN',
+  timezone: 'UTC+8',
+  contactName: '仓库客服',
+  contactPhone: '0579-12345678',
+  contactEmail: null,
+  status: 'ACTIVE',
+  remark: null,
+  address: {
+    addressType: 'OPERATING',
+    countryCode: 'CN',
+    stateProvince: '浙江省',
+    city: '义乌市',
+    district: null,
+    postalCode: null,
+    addressLine1: '北苑街道 1 号库',
+    addressLine2: null,
+    latitude: null,
+    longitude: null,
+  },
+  capabilities: [{
+    capabilityCode: 'RECEIVING',
+    capabilityName: '收货服务',
+    enabled: true,
+    cutoffTime: null,
+    description: '周一至周六 08:30-18:00',
+  }],
+}
+
+describe('platform warehouse API', () => {
+  beforeEach(() => {
+    vi.mocked(http.get).mockReset()
+    vi.mocked(http.post).mockReset()
+    vi.mocked(http.put).mockReset()
+    vi.mocked(http.patch).mockReset()
+  })
+
+  it('lists server-paged platform warehouses and normalizes summary fields', async () => {
+    const page = {
+      records: [{
+        id: '1',
+        tenantId: 0,
+        warehouseCode: 'LAX9',
+        internalCode: '154',
+        warehouseName: 'LAX9',
+        warehouseType: 'FBA',
+        countryCode: 'US',
+        timezone: 'UTC-8',
+        contactName: null,
+        contactPhone: null,
+        contactEmail: null,
+        status: 'ACTIVE',
+        remark: null,
+      }],
+      page: '1',
+      size: '20',
+      total: '1',
+      pages: '1',
+    }
+    const detail = { warehouse: {}, addresses: [], capabilities: [] }
+    vi.mocked(http.get)
+      .mockResolvedValueOnce({ code: '200', message: 'success', data: page })
+      .mockResolvedValueOnce({ code: '200', message: 'success', data: detail })
+
+    await expect(listPlatformWarehouses({ page: 1, size: 20, keyword: 'LAX', warehouseType: 'FBA', status: 'ACTIVE' })).resolves.toEqual({
+      records: [{ ...page.records[0], primaryAddress: null, addressSummary: null }],
+      page: 1,
+      size: 20,
+      total: 1,
+      pages: 1,
+    })
+    await expect(getPlatformWarehouse('19001')).resolves.toEqual(detail)
+    expect(http.get).toHaveBeenNthCalledWith(1, '/platform/v1/warehouse-admin', {
+      params: { page: 1, size: 20, keyword: 'LAX', warehouseType: 'FBA', status: 'ACTIVE' },
+    })
+    expect(http.get).toHaveBeenNthCalledWith(2, '/platform/v1/warehouse-admin/19001', {
+      params: { tenantId: 0 },
+    })
+  })
+
+  it('lists all platform warehouses without a customer filter', async () => {
+    const page = { records: [], page: 1, size: 200, total: 0, pages: 0 }
+    vi.mocked(http.get).mockResolvedValue({ code: '200', data: page })
+
+    await listPlatformWarehouses()
+
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/warehouse-admin', {
+      params: { page: 1, size: 200 },
+    })
+  })
+
+  it('passes the confirmed overseas partner warehouse type through list and save contracts', async () => {
+    vi.mocked(http.get).mockResolvedValue({
+      code: '200',
+      data: { records: [], page: 1, size: 20, total: 0, pages: 0 },
+    })
+    vi.mocked(http.post).mockResolvedValue({ code: '200', data: '19020' })
+    const partnerPayload: SavePlatformWarehouseRequest = {
+      ...payload,
+      warehouseCode: 'PARTNER-US-01',
+      warehouseName: '洛杉矶合作仓',
+      warehouseType: 'OVERSEAS_PARTNER',
+      countryCode: 'US',
+      timezone: 'UTC-8',
+      address: { ...payload.address, countryCode: 'US', stateProvince: 'CA', city: 'Los Angeles' },
+    }
+
+    await listPlatformWarehouses({ page: 1, size: 20, warehouseType: 'OVERSEAS_PARTNER' })
+    await expect(createPlatformWarehouse(partnerPayload)).resolves.toBe('19020')
+
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/warehouse-admin', {
+      params: { page: 1, size: 20, warehouseType: 'OVERSEAS_PARTNER' },
+    })
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/warehouse-admin', {
+      ...partnerPayload,
+      tenantId: 0,
+    })
+  })
+
+  it('loads every warehouse page for complete resource selectors', async () => {
+    const firstRecord = { id: '1', warehouseCode: 'ABE2', warehouseType: 'FBA' }
+    const domesticRecord = { id: '201', warehouseCode: 'CN-YIWU-01', warehouseType: 'DOMESTIC' }
+    vi.mocked(http.get)
+      .mockResolvedValueOnce({
+        code: '200',
+        data: { records: [firstRecord], page: 1, size: 200, total: 201, pages: 2 },
+      })
+      .mockResolvedValueOnce({
+        code: '200',
+        data: { records: [domesticRecord], page: 2, size: 200, total: 201, pages: 2 },
+      })
+
+    await expect(listAllPlatformWarehouses()).resolves.toEqual([
+      { ...firstRecord, primaryAddress: null, addressSummary: null },
+      { ...domesticRecord, primaryAddress: null, addressSummary: null },
+    ])
+    expect(http.get).toHaveBeenNthCalledWith(1, '/platform/v1/warehouse-admin', {
+      params: { page: 1, size: 200 },
+    })
+    expect(http.get).toHaveBeenNthCalledWith(2, '/platform/v1/warehouse-admin', {
+      params: { page: 2, size: 200 },
+    })
+  })
+
+  it('uses the implemented create, update, and status routes', async () => {
+    vi.mocked(http.post).mockResolvedValue({ code: '200', message: 'success', data: '19001' })
+    vi.mocked(http.put).mockResolvedValue({ code: '200', message: 'success', data: null })
+    vi.mocked(http.patch).mockResolvedValue({ code: '200', message: 'success', data: null })
+
+    await expect(createPlatformWarehouse(payload)).resolves.toBe('19001')
+    await expect(updatePlatformWarehouse('19001', payload)).resolves.toBeNull()
+    await expect(changePlatformWarehouseStatus('19001', 'INACTIVE')).resolves.toBeNull()
+
+    expect(http.post).toHaveBeenCalledWith('/platform/v1/warehouse-admin', { ...payload, tenantId: 0 })
+    expect(http.put).toHaveBeenCalledWith('/platform/v1/warehouse-admin/19001', { ...payload, tenantId: 0 }, {
+      params: { tenantId: 0 },
+    })
+    expect(http.patch).toHaveBeenCalledWith('/platform/v1/warehouse-admin/19001/status', undefined, {
+      params: { tenantId: 0, status: 'INACTIVE' },
+    })
+  })
+
+  it('uses the FBA fast-create defaults and implemented import routes without client-side success simulation', async () => {
+    vi.mocked(http.post)
+      .mockResolvedValueOnce({ code: '200', message: 'success', data: '19002' })
+      .mockResolvedValueOnce({
+        code: '200',
+        message: 'success',
+        data: {
+          fileName: 'fba.xlsx',
+          totalRows: '3',
+          createdRows: '1',
+          updatedRows: '1',
+          unchangedRows: '0',
+          success: false,
+          committed: false,
+          errors: [{ row: '3', field: '仓库编码', message: '编码重复' }],
+        },
+      })
+
+    await expect(createFbaWarehouse({
+      warehouseCode: 'LAX9',
+      internalCode: '154',
+      stateProvince: 'CA',
+      city: 'Long Beach',
+      postalCode: '90802',
+      addressLine1: '2400 E Spring St',
+    })).resolves.toBe('19002')
+
+    const file = new File(['content'], 'warehouses.xlsx')
+    await expect(importWarehouses(file, true, 'CREATE_ONLY')).resolves.toMatchObject({
+      totalRows: 3,
+      validRows: 2,
+      createCount: 1,
+      updateCount: 1,
+      unchangedCount: 0,
+      errorCount: 1,
+      committed: false,
+      errors: [{ row: 3, field: '仓库编码', message: '编码重复' }],
+    })
+
+    expect(http.post).toHaveBeenNthCalledWith(1, '/platform/v1/warehouse-admin', {
+      warehouseCode: 'LAX9',
+      internalCode: '154',
+      warehouseName: 'LAX9',
+      warehouseType: 'FBA',
+      countryCode: 'US',
+      timezone: '',
+      contactName: null,
+      contactPhone: null,
+      contactEmail: null,
+      status: 'ACTIVE',
+      remark: null,
+      address: {
+        addressType: 'OPERATING',
+        countryCode: 'US',
+        stateProvince: 'CA',
+        city: 'Long Beach',
+        district: null,
+        postalCode: '90802',
+        addressLine1: '2400 E Spring St',
+        addressLine2: null,
+        latitude: null,
+        longitude: null,
+      },
+      capabilities: [],
+      tenantId: 0,
+    })
+    expect(http.post).toHaveBeenNthCalledWith(
+      2,
+      '/platform/v1/warehouse-admin/import',
+      expect.any(FormData),
+      { params: { tenantId: 0, dryRun: true, mode: 'CREATE_ONLY' } },
+    )
+  })
+})
diff --git a/src/modules/warehouses/api/platformWarehouses.ts b/src/modules/warehouses/api/platformWarehouses.ts
new file mode 100644
index 00000000..2c248249
--- /dev/null
+++ b/src/modules/warehouses/api/platformWarehouses.ts
@@ -0,0 +1,314 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+
+export type PlatformWarehouseStatus = 'ACTIVE' | 'INACTIVE'
+
+export type WarehouseType = 'DOMESTIC' | 'FBA' | 'OVERSEAS' | 'OVERSEAS_PARTNER'
+
+export interface PlatformWarehouseResource {
+  id: number | string
+  tenantId: number | string
+  warehouseCode: string
+  internalCode: string | null
+  warehouseName: string
+  warehouseType: WarehouseType
+  countryCode: string
+  timezone: string
+  contactName: string | null
+  contactPhone: string | null
+  contactEmail: string | null
+  status: PlatformWarehouseStatus
+  remark: string | null
+  createdAt?: string | null
+  updatedAt?: string | null
+}
+
+export interface PlatformWarehouseAddressResource {
+  id: number | string
+  tenantId: number | string
+  warehouseId: number | string
+  addressType: string
+  countryCode: string
+  stateProvince: string | null
+  city: string
+  district: string | null
+  postalCode: string | null
+  addressLine1: string
+  addressLine2: string | null
+  latitude: number | string | null
+  longitude: number | string | null
+}
+
+export interface PlatformWarehouseCapabilityResource {
+  id: number | string
+  tenantId: number | string
+  warehouseId: number | string
+  capabilityCode: string
+  capabilityName: string
+  enabled: boolean | null
+  cutoffTime: string | null
+  description: string | null
+}
+
+export interface PlatformWarehouseDetailResource {
+  warehouse: PlatformWarehouseResource
+  addresses: PlatformWarehouseAddressResource[]
+  capabilities: PlatformWarehouseCapabilityResource[]
+}
+
+export interface PlatformWarehouseSummaryResource extends PlatformWarehouseResource {
+  primaryAddress?: PlatformWarehouseAddressResource | null
+  addressSummary?: string | null
+}
+
+export interface PlatformWarehousePage {
+  records: PlatformWarehouseSummaryResource[]
+  page: number
+  size: number
+  total: number
+  pages: number
+}
+
+type PlatformWarehousePagePayload = Omit<PlatformWarehousePage, 'page' | 'size' | 'total' | 'pages'> & {
+  page: number | string
+  size: number | string
+  total: number | string
+  pages: number | string
+}
+
+export interface PlatformWarehouseQuery {
+  page: number
+  size: number
+  keyword?: string
+  warehouseType?: WarehouseType
+  status?: PlatformWarehouseStatus
+}
+
+export interface PlatformWarehouseAddressRequest {
+  addressType: string
+  countryCode: string
+  stateProvince: string | null
+  city: string
+  district: string | null
+  postalCode: string | null
+  addressLine1: string
+  addressLine2: string | null
+  latitude: number | string | null
+  longitude: number | string | null
+}
+
+export interface PlatformWarehouseCapabilityRequest {
+  capabilityCode: string
+  capabilityName: string
+  enabled: boolean
+  cutoffTime: string | null
+  description: string | null
+}
+
+export interface SavePlatformWarehouseRequest {
+  warehouseCode: string
+  internalCode: string | null
+  warehouseName: string
+  warehouseType: WarehouseType
+  countryCode: string
+  timezone: string
+  contactName: string | null
+  contactPhone: string | null
+  contactEmail: string | null
+  status: PlatformWarehouseStatus
+  remark: string | null
+  address: PlatformWarehouseAddressRequest
+  capabilities: PlatformWarehouseCapabilityRequest[]
+}
+
+export interface CreateFbaWarehouseRequest {
+  warehouseCode: string
+  internalCode: string | null
+  stateProvince: string
+  city: string
+  postalCode: string
+  addressLine1: string
+  timezone?: string | null
+}
+
+export type WarehouseImportMode = 'CREATE_ONLY' | 'UPSERT'
+
+export interface WarehouseImportError {
+  row: number
+  field: string
+  code?: string | null
+  message: string
+}
+
+export interface WarehouseImportResult {
+  fileName: string
+  totalRows: number
+  validRows: number
+  createCount: number
+  updateCount: number
+  unchangedCount: number
+  errorCount: number
+  committed: boolean
+  errors: WarehouseImportError[]
+}
+
+const basePath = '/platform/v1/warehouse-admin'
+const platformResourceScope = 0
+
+type PlatformWarehouseApiSaveRequest = SavePlatformWarehouseRequest & { tenantId: number }
+type WarehouseImportErrorPayload = Omit<WarehouseImportError, 'row'> & { row: number | string }
+type WarehouseImportResultPayload = Partial<Omit<
+  WarehouseImportResult,
+  'totalRows' | 'validRows' | 'createCount' | 'updateCount' | 'unchangedCount' | 'errorCount' | 'committed' | 'errors'
+>> & {
+  totalRows: number | string
+  validRows?: number | string
+  createCount?: number | string
+  createdRows?: number | string
+  updateCount?: number | string
+  updatedRows?: number | string
+  unchangedCount?: number | string
+  unchangedRows?: number | string
+  errorCount?: number | string
+  success?: boolean
+  committed?: boolean
+  errors?: WarehouseImportErrorPayload[] | null
+}
+
+function withPlatformScope(payload: SavePlatformWarehouseRequest): PlatformWarehouseApiSaveRequest {
+  return { ...payload, tenantId: platformResourceScope }
+}
+
+function toNumber(value: number | string | undefined) {
+  return Number(value ?? 0)
+}
+
+function normalizeWarehouseImportResult(result: WarehouseImportResultPayload, dryRun: boolean): WarehouseImportResult {
+  const errors = (result.errors || []).map((error) => ({ ...error, row: toNumber(error.row) }))
+  const errorCount = toNumber(result.errorCount) || errors.length
+  const totalRows = toNumber(result.totalRows)
+  return {
+    ...result,
+    fileName: result.fileName || '',
+    totalRows,
+    validRows: toNumber(result.validRows) || Math.max(totalRows - errorCount, 0),
+    createCount: toNumber(result.createCount ?? result.createdRows),
+    updateCount: toNumber(result.updateCount ?? result.updatedRows),
+    unchangedCount: toNumber(result.unchangedCount ?? result.unchangedRows),
+    errorCount,
+    committed: result.committed ?? (!dryRun && Boolean(result.success) && errorCount === 0),
+    errors,
+  }
+}
+
+export async function listPlatformWarehouses(query?: PlatformWarehouseQuery): Promise<PlatformWarehousePage>
+export async function listPlatformWarehouses(page?: number, size?: number): Promise<PlatformWarehousePage>
+export async function listPlatformWarehouses(pageOrQuery: number | PlatformWarehouseQuery = 1, size = 200) {
+  const query = typeof pageOrQuery === 'number'
+    ? { page: pageOrQuery, size }
+    : pageOrQuery
+  const response = await http.get<ApiEnvelope<PlatformWarehousePagePayload>, ApiEnvelope<PlatformWarehousePagePayload>>(basePath, {
+    params: query,
+  })
+  const result = unwrapApiResponse(response)
+  return {
+    ...result,
+    records: result.records.map((warehouse) => ({
+      ...warehouse,
+      primaryAddress: warehouse.primaryAddress ?? null,
+      addressSummary: warehouse.addressSummary ?? null,
+    })),
+    page: Number(result.page),
+    size: Number(result.size),
+    total: Number(result.total),
+    pages: Number(result.pages),
+  }
+}
+
+export async function listAllPlatformWarehouses(
+  filters: Omit<PlatformWarehouseQuery, 'page' | 'size'> = {},
+): Promise<PlatformWarehouseSummaryResource[]> {
+  const size = 200
+  const firstPage = await listPlatformWarehouses({ ...filters, page: 1, size })
+  if (firstPage.pages <= 1) return firstPage.records
+
+  const remainingPages = await Promise.all(
+    Array.from({ length: firstPage.pages - 1 }, (_, index) => (
+      listPlatformWarehouses({ ...filters, page: index + 2, size })
+    )),
+  )
+  return [firstPage, ...remainingPages].flatMap((page) => page.records)
+}
+
+export async function getPlatformWarehouse(warehouseId: number | string) {
+  const response = await http.get<ApiEnvelope<PlatformWarehouseDetailResource>, ApiEnvelope<PlatformWarehouseDetailResource>>(
+    `${basePath}/${warehouseId}`,
+    { params: { tenantId: platformResourceScope } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function createPlatformWarehouse(payload: SavePlatformWarehouseRequest) {
+  const response = await http.post<ApiEnvelope<number | string>, ApiEnvelope<number | string>>(basePath, withPlatformScope(payload))
+  return unwrapApiResponse(response)
+}
+
+export async function createFbaWarehouse(payload: CreateFbaWarehouseRequest) {
+  return createPlatformWarehouse({
+    warehouseCode: payload.warehouseCode,
+    internalCode: payload.internalCode,
+    warehouseName: payload.warehouseCode,
+    warehouseType: 'FBA',
+    countryCode: 'US',
+    timezone: payload.timezone?.trim() || '',
+    contactName: null,
+    contactPhone: null,
+    contactEmail: null,
+    status: 'ACTIVE',
+    remark: null,
+    address: {
+      addressType: 'OPERATING',
+      countryCode: 'US',
+      stateProvince: payload.stateProvince,
+      city: payload.city,
+      district: null,
+      postalCode: payload.postalCode,
+      addressLine1: payload.addressLine1,
+      addressLine2: null,
+      latitude: null,
+      longitude: null,
+    },
+    capabilities: [],
+  })
+}
+
+export async function downloadWarehouseImportTemplate() {
+  return http.get<Blob, Blob>(`${basePath}/import-template`, { responseType: 'blob' })
+}
+
+export async function importWarehouses(file: File, dryRun: boolean, mode: WarehouseImportMode) {
+  const form = new FormData()
+  form.append('file', file)
+  const response = await http.post<ApiEnvelope<WarehouseImportResultPayload>, ApiEnvelope<WarehouseImportResultPayload>>(
+    `${basePath}/import`,
+    form,
+    { params: { tenantId: platformResourceScope, dryRun, mode } },
+  )
+  return normalizeWarehouseImportResult(unwrapApiResponse(response), dryRun)
+}
+
+export async function updatePlatformWarehouse(warehouseId: number | string, payload: SavePlatformWarehouseRequest) {
+  const response = await http.put<ApiEnvelope<null>, ApiEnvelope<null>>(`${basePath}/${warehouseId}`, withPlatformScope(payload), {
+    params: { tenantId: platformResourceScope },
+  })
+  return unwrapApiResponse(response)
+}
+
+export async function changePlatformWarehouseStatus(
+  warehouseId: number | string,
+  status: PlatformWarehouseStatus,
+) {
+  const response = await http.patch<ApiEnvelope<null>, ApiEnvelope<null>>(`${basePath}/${warehouseId}/status`, undefined, {
+    params: { tenantId: platformResourceScope, status },
+  })
+  return unwrapApiResponse(response)
+}
diff --git a/src/modules/warehouses/index.ts b/src/modules/warehouses/index.ts
new file mode 100644
index 00000000..91424db1
--- /dev/null
+++ b/src/modules/warehouses/index.ts
@@ -0,0 +1 @@
+export * from './api/platformWarehouses'
diff --git a/src/modules/warehouses/pages/WarehousesView.test.ts b/src/modules/warehouses/pages/WarehousesView.test.ts
new file mode 100644
index 00000000..1e2c90c5
--- /dev/null
+++ b/src/modules/warehouses/pages/WarehousesView.test.ts
@@ -0,0 +1,592 @@
+import ElementPlus from 'element-plus'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { createPinia, setActivePinia } from 'pinia'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import DataTable from '@/shared/components/DataTable.vue'
+import QueryToolbar from '@/shared/components/QueryToolbar.vue'
+import {
+  createFbaWarehouse,
+  createPlatformWarehouse,
+  getPlatformWarehouse,
+  importWarehouses,
+  listPlatformWarehouses,
+  updatePlatformWarehouse,
+  type PlatformWarehouseDetailResource,
+  type PlatformWarehouseSummaryResource,
+  type WarehouseImportResult,
+} from '@/modules/warehouses/api/platformWarehouses'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import { useAuthStore } from '@/core/auth/auth'
+import WarehousesView from './WarehousesView.vue'
+
+const warehousesSource = readFileSync(resolve(process.cwd(), 'src/modules/warehouses/pages/WarehousesView.vue'), 'utf8')
+
+vi.mock('@/modules/warehouses/api/platformWarehouses', () => ({
+  listPlatformWarehouses: vi.fn(),
+  getPlatformWarehouse: vi.fn(),
+  createPlatformWarehouse: vi.fn(),
+  createFbaWarehouse: vi.fn(),
+  updatePlatformWarehouse: vi.fn(),
+  changePlatformWarehouseStatus: vi.fn(),
+  downloadWarehouseImportTemplate: vi.fn(),
+  importWarehouses: vi.fn(),
+}))
+
+class ResizeObserverStub implements ResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+
+function createMemoryStorage(initial: Record<string, string> = {}): Storage {
+  const values = new Map(Object.entries(initial))
+  return {
+    get length() { return values.size },
+    clear: () => values.clear(),
+    getItem: (key) => values.get(key) ?? null,
+    key: (index) => [...values.keys()][index] ?? null,
+    removeItem: (key) => values.delete(key),
+    setItem: (key, value) => values.set(key, value),
+  }
+}
+
+const domesticAddress = {
+  id: '19002',
+  tenantId: 0,
+  warehouseId: '19001',
+  addressType: 'OPERATING',
+  countryCode: 'CN',
+  stateProvince: '浙江省',
+  city: '义乌市',
+  district: '北苑街道',
+  postalCode: '322000',
+  addressLine1: '真实物流园 1 号库',
+  addressLine2: 'A 栋',
+  latitude: '29.3',
+  longitude: '120.0',
+}
+
+const domesticWarehouse: PlatformWarehouseSummaryResource = {
+  id: '19001',
+  tenantId: 0,
+  warehouseCode: 'CN-YW-01',
+  internalCode: null,
+  warehouseName: '义乌收货仓',
+  warehouseType: 'DOMESTIC',
+  countryCode: 'CN',
+  timezone: 'UTC+8',
+  contactName: '仓库客服',
+  contactPhone: '0579-12345678',
+  contactEmail: 'warehouse@example.com',
+  status: 'ACTIVE',
+  remark: '测试环境数据',
+  updatedAt: '2026-07-31T10:20:00',
+  addressSummary: '浙江省义乌市北苑街道 1 号库',
+  primaryAddress: domesticAddress,
+}
+
+const fbaAddress = {
+  id: '19012',
+  tenantId: 0,
+  warehouseId: '19011',
+  addressType: 'OPERATING',
+  countryCode: 'US',
+  stateProvince: 'OH',
+  city: 'Canton',
+  district: null,
+  postalCode: '44705',
+  addressLine1: '4747 Rebar Ave NE',
+  addressLine2: null,
+  latitude: null,
+  longitude: null,
+}
+
+const fbaWarehouse: PlatformWarehouseSummaryResource = {
+  id: '19011',
+  tenantId: 0,
+  warehouseCode: 'AKR1',
+  internalCode: '154',
+  warehouseName: 'AKR1',
+  warehouseType: 'FBA',
+  countryCode: 'US',
+  timezone: 'UTC-5',
+  contactName: null,
+  contactPhone: null,
+  contactEmail: null,
+  status: 'ACTIVE',
+  remark: null,
+  updatedAt: '2026-07-31T10:20:00',
+  addressSummary: 'OH · Canton',
+  primaryAddress: fbaAddress,
+}
+
+const fbaDetail: PlatformWarehouseDetailResource = {
+  warehouse: fbaWarehouse,
+  addresses: [fbaAddress],
+  capabilities: [],
+}
+
+const partnerWarehouse: PlatformWarehouseSummaryResource = {
+  ...fbaWarehouse,
+  id: '19021',
+  warehouseCode: 'PARTNER-US-01',
+  internalCode: null,
+  warehouseName: '洛杉矶合作仓',
+  warehouseType: 'OVERSEAS_PARTNER',
+}
+
+const partnerDetail: PlatformWarehouseDetailResource = {
+  warehouse: partnerWarehouse,
+  addresses: [{ ...fbaAddress, id: '19022', warehouseId: '19021', stateProvince: 'CA', city: 'Los Angeles' }],
+  capabilities: [],
+}
+
+const detail: PlatformWarehouseDetailResource = {
+  warehouse: domesticWarehouse,
+  addresses: [domesticAddress],
+  capabilities: [
+    { id: '19003', tenantId: 0, warehouseId: '19001', capabilityCode: 'RECEIVING', capabilityName: '收货服务', enabled: true, cutoffTime: '17:00:00', description: '周一至周六 08:30-18:00' },
+    { id: '19004', tenantId: 0, warehouseId: '19001', capabilityCode: 'STORAGE', capabilityName: '仓储', enabled: true, cutoffTime: null, description: '托盘仓储' },
+  ],
+}
+
+const importPreview: WarehouseImportResult = {
+  fileName: 'warehouses.xlsx',
+  totalRows: 4,
+  validRows: 3,
+  createCount: 2,
+  updateCount: 1,
+  unchangedCount: 0,
+  errorCount: 1,
+  committed: false,
+  errors: [{ row: 4, field: '仓库编码', code: 'DUPLICATE_CODE', message: '文件内编码重复' }],
+}
+
+async function mountView(permissions = ['platform:warehouse:list', 'platform:warehouse:create', 'platform:warehouse:edit', 'platform:warehouse:status']) {
+  vi.stubGlobal('localStorage', createMemoryStorage())
+  vi.stubGlobal('sessionStorage', createMemoryStorage())
+  const pinia = createPinia()
+  setActivePinia(pinia)
+  const auth = useAuthStore()
+  auth.token = 'token'
+  auth.permissions = permissions
+  useAccessPreviewStore().initializeAfterLogin()
+  const wrapper = mount(WarehousesView, {
+    attachTo: document.body,
+    global: { plugins: [pinia, ElementPlus] },
+  })
+  await flushPromises()
+  return wrapper
+}
+
+function setField(selector: string, value: string) {
+  const field = document.querySelector<HTMLInputElement | HTMLTextAreaElement>(selector)
+  expect(field).not.toBeNull()
+  field!.value = value
+  field!.dispatchEvent(new Event('input', { bubbles: true }))
+}
+
+enableAutoUnmount(afterEach)
+afterAll(() => vi.unstubAllGlobals())
+
+describe('WarehousesView', () => {
+  it('uses bordered striped tables and semantic operation buttons', () => {
+    expect(warehousesSource).toContain('border')
+    expect(warehousesSource).toContain('stripe')
+    expect(warehousesSource).toContain('data-tone="neutral" class="density-action"')
+    expect(warehousesSource).toMatch(/:data-tone=/)
+    expect(warehousesSource).toContain('>编辑</el-button>')
+    expect(warehousesSource).toContain(':data-tone=')
+    for (const label of ['仓库名称', '仓库编码', '内部编号', '州/省', '城市', '邮编']) expect(warehousesSource).toContain(`label: '${label}'`)
+    expect(warehousesSource).toContain('@media (max-width: 720px)')
+  })
+  it('uses the prototype-sized centered warehouse editor with a fixed footer', () => {
+    expect(warehousesSource).toContain('<AppDialog v-model="editorOpen" :title="editorLabel" width="min(650px, calc(100vw - 28px))"')
+    expect(warehousesSource).not.toContain('<AppDrawer v-model="editorOpen"')
+    expect(warehousesSource).toContain(':global(.warehouse-editor-dialog .el-dialog__body) { min-height: 0; overflow-y: auto; }')
+    expect(warehousesSource).toContain('.density-form :deep(.form-grid.two-cols) { grid-template-columns: minmax(0, 1fr); }')
+  })
+  beforeEach(() => {
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+    document.body.innerHTML = ''
+    vi.mocked(listPlatformWarehouses).mockReset().mockResolvedValue({ records: [domesticWarehouse], page: 1, size: 20, total: 1, pages: 1 })
+    vi.mocked(getPlatformWarehouse).mockReset().mockResolvedValue(detail)
+    vi.mocked(createPlatformWarehouse).mockReset().mockResolvedValue('19005')
+    vi.mocked(createFbaWarehouse).mockReset().mockResolvedValue('19006')
+    vi.mocked(updatePlatformWarehouse).mockReset().mockResolvedValue(null)
+    vi.mocked(importWarehouses).mockReset().mockResolvedValue(importPreview)
+  })
+
+  it('loads a server-paged warehouse list with backend address summaries and no row detail fan-out', async () => {
+    const wrapper = await mountView()
+
+    expect(listPlatformWarehouses).toHaveBeenCalledWith({
+      page: 1,
+      size: 20,
+      keyword: undefined,
+      warehouseType: undefined,
+      status: undefined,
+    })
+    expect(getPlatformWarehouse).not.toHaveBeenCalled()
+    expect(wrapper.text()).toContain('义乌收货仓')
+    expect(wrapper.find('.data-table').text()).not.toContain('浙江省义乌市北苑街道 1 号库')
+    expect(wrapper.text()).toContain('国内收货仓')
+    expect(wrapper.text()).toContain('中国 CN')
+    expect(wrapper.find('.data-table').text()).not.toContain('UTC+8')
+    expect(wrapper.text()).toContain('共 1 个公共仓库')
+    expect(wrapper.find('.data-table').exists()).toBe(true)
+    const editButton = wrapper.findAll('.table-actions button').find((button) => button.text().trim() === '编辑')
+    await editButton?.trigger('click')
+    await flushPromises()
+    expect((wrapper.find('textarea[placeholder*="街道"]').element as HTMLTextAreaElement).value).toBe('真实物流园 1 号库')
+    expect(document.body.textContent).toContain('UTC+8')
+  })
+
+  it('submits filters and pagination to the API instead of filtering rows locally', async () => {
+    vi.mocked(listPlatformWarehouses).mockResolvedValue({ records: [domesticWarehouse], page: 1, size: 20, total: 45, pages: 3 })
+    const wrapper = await mountView()
+
+    wrapper.findComponent(QueryToolbar).vm.$emit('search', {
+      keyword: 'FBA',
+      warehouseType: 'FBA',
+      status: 'ACTIVE',
+    })
+    await flushPromises()
+
+    expect(listPlatformWarehouses).toHaveBeenLastCalledWith({
+      page: 1,
+      size: 20,
+      keyword: 'FBA',
+      warehouseType: 'FBA',
+      status: 'ACTIVE',
+    })
+
+    wrapper.findComponent(DataTable).vm.$emit('update:page', 2)
+    await flushPromises()
+
+    expect(listPlatformWarehouses).toHaveBeenLastCalledWith({
+      page: 2,
+      size: 20,
+      keyword: 'FBA',
+      warehouseType: 'FBA',
+      status: 'ACTIVE',
+    })
+  })
+
+  it('submits the current keyword once when Enter is pressed in the text filter', async () => {
+    const wrapper = await mountView()
+    const keywordInput = wrapper.find('input[placeholder="仓库名称、编码、城市或地址"]')
+
+    await keywordInput.setValue('AKR1')
+    await keywordInput.trigger('keyup', { key: 'Enter' })
+    await flushPromises()
+
+    expect(listPlatformWarehouses).toHaveBeenCalledTimes(2)
+    expect(listPlatformWarehouses).toHaveBeenLastCalledWith({
+      page: 1,
+      size: 20,
+      keyword: 'AKR1',
+      warehouseType: undefined,
+      status: undefined,
+    })
+    expect(wrapper.findComponent(QueryToolbar).props('loading')).toBe(false)
+  })
+
+  it('shows a recoverable API error without falling back to demo warehouses', async () => {
+    vi.mocked(listPlatformWarehouses).mockRejectedValueOnce(new Error('Gateway unavailable'))
+    const wrapper = await mountView()
+
+    expect(wrapper.text()).toContain('仓库数据加载失败')
+    expect(wrapper.text()).not.toContain('Gateway unavailable')
+    expect(wrapper.text()).toContain('重新查询')
+    expect(wrapper.text()).not.toContain('演示物流园')
+    expect(wrapper.find('.table-panel .data-table').exists()).toBe(false)
+  })
+
+  it('keeps create actions behind permissions and preserves a read-only table state', async () => {
+    const wrapper = await mountView(['platform:warehouse:list'])
+
+    expect(wrapper.text()).not.toContain('新增仓库')
+    expect(wrapper.text()).not.toContain('导入仓库')
+    expect(wrapper.text()).toContain('仅查看')
+  })
+
+  it('creates an FBA address from the fast path with selectable state and timezone values', async () => {
+    const wrapper = await mountView()
+
+    wrapper.findComponent({ name: 'ElDropdown' }).vm.$emit('command', 'FBA')
+    await flushPromises()
+
+    const dialogText = document.querySelector('.warehouse-editor-dialog')?.textContent || ''
+    expect(dialogText).toContain('新增FBA 地址')
+    expect(dialogText).toContain('国家或地区')
+    expect(dialogText).not.toContain('时区覆盖')
+    expect(dialogText).not.toContain('联系人')
+    expect(dialogText).not.toContain('收货时间')
+    const countrySelect = wrapper.findAllComponents({ name: 'ElSelect' })
+      .find((select) => select.props('placeholder') === '美国 US')
+    expect(countrySelect).toBeDefined()
+    expect(countrySelect!.props('modelValue')).toBe('US')
+    expect(countrySelect!.props('disabled')).toBe(true)
+
+    const stateSelect = wrapper.findAllComponents({ name: 'ElSelect' })
+      .find((select) => select.props('placeholder') === '请选择州')
+    expect(stateSelect).toBeDefined()
+
+    setField('input[placeholder="例如 LAX9"]', 'lax9')
+    setField('input[placeholder="例如 154 或 CADF"]', '154')
+    stateSelect!.vm.$emit('update:modelValue', 'CA')
+    stateSelect!.vm.$emit('change', 'CA')
+    await flushPromises()
+    setField('input[placeholder="例如 Long Beach"]', 'Long Beach')
+    setField('input[placeholder="例如 90802"]', '90802')
+    setField('textarea[placeholder="请输入街道和门牌信息"]', '2400 E Spring St')
+
+    const saveButton = [...document.querySelectorAll('button')].find((button) => button.textContent?.trim() === '确认新增')
+    expect(saveButton).toBeDefined()
+    saveButton!.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+    await flushPromises()
+
+    expect(createFbaWarehouse).toHaveBeenCalledWith({
+      warehouseCode: 'LAX9',
+      internalCode: '154',
+      stateProvince: 'CA',
+      city: 'Long Beach',
+      postalCode: '90802',
+      addressLine1: '2400 E Spring St',
+      timezone: 'UTC-8',
+    })
+    expect(createPlatformWarehouse).not.toHaveBeenCalled()
+  })
+
+  it('hides domestic country, timezone and type inputs while submitting fixed CN and UTC+8 defaults', async () => {
+    const wrapper = await mountView()
+
+    wrapper.findComponent({ name: 'ElDropdown' }).vm.$emit('command', 'DOMESTIC')
+    await flushPromises()
+
+    const dialogText = document.querySelector('.warehouse-editor-dialog')?.textContent || ''
+    expect(dialogText).not.toContain('国家或地区')
+    expect(dialogText).not.toContain('时区')
+    expect(dialogText).not.toContain('仓库类型')
+
+    setField('input[placeholder="请输入仓库名称"]', '义乌新仓')
+    setField('input[placeholder="例如 浙江省"]', '浙江省')
+    setField('input[placeholder="例如 义乌市"]', '义乌市')
+    setField('textarea[placeholder="请输入街道、园区、楼栋及门牌信息"]', '稠州北路 100 号')
+
+    const saveButton = [...document.querySelectorAll('button')].find((button) => button.textContent?.trim() === '确认新增')
+    expect(saveButton).toBeDefined()
+    saveButton!.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+    await flushPromises()
+
+    expect(createPlatformWarehouse).toHaveBeenCalledOnce()
+    expect(vi.mocked(createPlatformWarehouse).mock.calls[0][0]).toMatchObject({
+      warehouseName: '义乌新仓',
+      warehouseType: 'DOMESTIC',
+      countryCode: 'CN',
+      timezone: 'UTC+8',
+      address: expect.objectContaining({ countryCode: 'CN', city: '义乌市' }),
+    })
+  })
+
+  it('uses country and state selectors for overseas warehouse creation and auto-fills timezone when safe', async () => {
+    const wrapper = await mountView()
+
+    wrapper.findComponent({ name: 'ElDropdown' }).vm.$emit('command', 'OVERSEAS')
+    await flushPromises()
+
+    const countrySelect = wrapper.findAllComponents({ name: 'ElSelect' })
+      .find((select) => select.props('placeholder') === '请选择国家或地区')
+    expect(countrySelect).toBeDefined()
+    expect(countrySelect!.props('modelValue')).toBe('US')
+
+    const stateSelect = wrapper.findAllComponents({ name: 'ElSelect' })
+      .find((select) => select.props('placeholder') === '请选择州')
+    expect(stateSelect).toBeDefined()
+    const timezoneSelect = wrapper.findAllComponents({ name: 'ElSelect' })
+      .find((select) => select.props('placeholder') === '请选择时区')
+    expect(timezoneSelect).toBeDefined()
+    expect(wrapper.findAllComponents({ name: 'ElOption' }).some((option) => option.props('value') === 'UTC-8')).toBe(true)
+
+    setField('input[placeholder="请输入仓库名称"]', '洛杉矶海外仓')
+    stateSelect!.vm.$emit('update:modelValue', 'CA')
+    stateSelect!.vm.$emit('change', 'CA')
+    setField('input[placeholder="例如 Long Beach"]', 'Long Beach')
+    setField('textarea[placeholder="请输入街道、园区、楼栋及门牌信息"]', '2400 E Spring St')
+
+    const saveButton = [...document.querySelectorAll('button')].find((button) => button.textContent?.trim() === '确认新增')
+    expect(saveButton).toBeDefined()
+    saveButton!.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+    await flushPromises()
+
+    expect(createPlatformWarehouse).toHaveBeenCalledOnce()
+    expect(vi.mocked(createPlatformWarehouse).mock.calls[0][0]).toMatchObject({
+      warehouseName: '洛杉矶海外仓',
+      warehouseType: 'OVERSEAS',
+      countryCode: 'US',
+      timezone: 'UTC-8',
+      address: expect.objectContaining({ stateProvince: 'CA' }),
+    })
+  })
+
+  it('creates and filters the confirmed overseas partner warehouse type through the existing warehouse page', async () => {
+    const wrapper = await mountView()
+
+    wrapper.findComponent(QueryToolbar).vm.$emit('search', {
+      keyword: '',
+      warehouseType: 'OVERSEAS_PARTNER',
+      status: 'ACTIVE',
+    })
+    await flushPromises()
+    expect(listPlatformWarehouses).toHaveBeenLastCalledWith({
+      page: 1,
+      size: 20,
+      keyword: undefined,
+      warehouseType: 'OVERSEAS_PARTNER',
+      status: 'ACTIVE',
+    })
+
+    wrapper.findComponent({ name: 'ElDropdown' }).vm.$emit('command', 'OVERSEAS_PARTNER')
+    await flushPromises()
+    expect(document.querySelector('.warehouse-editor-dialog')?.textContent).toContain('新增海外仓合作仓')
+
+    const stateSelect = wrapper.findAllComponents({ name: 'ElSelect' })
+      .find((select) => select.props('placeholder') === '请选择州')
+    setField('input[placeholder="请输入仓库名称"]', '洛杉矶合作仓')
+    stateSelect!.vm.$emit('update:modelValue', 'CA')
+    stateSelect!.vm.$emit('change', 'CA')
+    setField('input[placeholder="例如 Long Beach"]', 'Los Angeles')
+    setField('textarea[placeholder="请输入街道、园区、楼栋及门牌信息"]', '100 Partner Ave')
+
+    const saveButton = [...document.querySelectorAll('button')].find((button) => button.textContent?.trim() === '确认新增')
+    saveButton!.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+    await flushPromises()
+
+    expect(createPlatformWarehouse).toHaveBeenCalledWith(expect.objectContaining({
+      warehouseCode: expect.stringMatching(/^PARTNER-WH-/),
+      warehouseName: '洛杉矶合作仓',
+      warehouseType: 'OVERSEAS_PARTNER',
+      countryCode: 'US',
+      timezone: 'UTC-8',
+      address: expect.objectContaining({ stateProvince: 'CA', city: 'Los Angeles' }),
+    }))
+  })
+
+  it('edits an existing overseas partner warehouse without converting it to an ordinary overseas warehouse', async () => {
+    vi.mocked(listPlatformWarehouses).mockResolvedValueOnce({ records: [partnerWarehouse], page: 1, size: 20, total: 1, pages: 1 })
+    vi.mocked(getPlatformWarehouse).mockResolvedValueOnce(partnerDetail)
+    const wrapper = await mountView()
+
+    await wrapper.find('.el-table__body-wrapper .table-actions button').trigger('click')
+    await flushPromises()
+    expect(document.querySelector('.warehouse-editor-dialog')?.textContent).toContain('编辑海外仓合作仓')
+
+    const saveButton = [...document.querySelectorAll('button')].find((button) => button.textContent?.trim() === '保存修改')
+    saveButton!.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+    await flushPromises()
+
+    expect(updatePlatformWarehouse).toHaveBeenCalledWith('19021', expect.objectContaining({
+      warehouseCode: 'PARTNER-US-01',
+      warehouseName: '洛杉矶合作仓',
+      warehouseType: 'OVERSEAS_PARTNER',
+    }))
+  })
+
+  it('edits FBA warehouses with selectors for country, timezone and state', async () => {
+    vi.mocked(listPlatformWarehouses).mockResolvedValueOnce({ records: [fbaWarehouse, domesticWarehouse], page: 1, size: 20, total: 2, pages: 1 })
+    vi.mocked(getPlatformWarehouse).mockResolvedValueOnce(fbaDetail)
+    const wrapper = await mountView()
+
+    const editButton = wrapper.find('.el-table__body-wrapper .table-actions button')
+    expect(editButton).toBeDefined()
+    await editButton.trigger('click')
+    await flushPromises()
+
+    const dialogText = document.querySelector('.warehouse-editor-dialog')?.textContent || ''
+    expect(dialogText).toContain('编辑FBA 地址')
+    expect(dialogText).not.toContain('例如 US')
+    expect(dialogText).not.toContain('例如 UTC-8')
+
+    const countrySelect = wrapper.findAllComponents({ name: 'ElSelect' })
+      .find((select) => select.props('placeholder') === '请选择国家或地区')
+    const stateSelect = wrapper.findAllComponents({ name: 'ElSelect' })
+      .find((select) => select.props('placeholder') === '请选择州')
+    const timezoneSelect = wrapper.findAllComponents({ name: 'ElSelect' })
+      .find((select) => select.props('placeholder') === '请选择时区')
+    expect(countrySelect?.props('modelValue')).toBe('US')
+    expect(stateSelect?.props('modelValue')).toBe('OH')
+    expect(timezoneSelect?.props('modelValue')).toBe('UTC-5')
+    expect(countrySelect).toBeDefined()
+    expect((wrapper.find('input[placeholder="例如 154 或 CADF"]').element as HTMLInputElement).value).toBe('154')
+
+    const saveButton = [...document.querySelectorAll('button')].find((button) => button.textContent?.trim() === '保存修改')
+    expect(saveButton).toBeDefined()
+    saveButton!.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+    await flushPromises()
+
+    expect(updatePlatformWarehouse).toHaveBeenCalledOnce()
+    const [, payload] = vi.mocked(updatePlatformWarehouse).mock.calls[0]
+    expect(payload).toMatchObject({
+      warehouseType: 'FBA',
+      internalCode: '154',
+      countryCode: 'US',
+      timezone: 'UTC-5',
+      address: expect.objectContaining({ stateProvince: 'OH' }),
+    })
+  })
+
+  it('edits existing records with full fields and preserves backend-only capabilities', async () => {
+    const wrapper = await mountView()
+
+    const editButton = wrapper.find('.el-table__body-wrapper .table-actions button')
+    expect(editButton).toBeDefined()
+    await editButton.trigger('click')
+    await flushPromises()
+
+    const saveButton = [...document.querySelectorAll('button')].find((button) => button.textContent?.trim() === '保存修改')
+    expect(saveButton).toBeDefined()
+    saveButton!.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+    await flushPromises()
+
+    expect(getPlatformWarehouse).toHaveBeenCalledWith('19001')
+    expect(updatePlatformWarehouse).toHaveBeenCalledOnce()
+    const [, payload] = vi.mocked(updatePlatformWarehouse).mock.calls[0]
+    expect(payload.contactEmail).toBe('warehouse@example.com')
+    expect(payload.capabilities).toContainEqual(expect.objectContaining({
+      capabilityCode: 'RECEIVING',
+      cutoffTime: '17:00:00',
+      description: '周一至周六 08:30-18:00',
+    }))
+    expect(payload.capabilities).toContainEqual(expect.objectContaining({ capabilityCode: 'STORAGE', description: '托盘仓储' }))
+  })
+
+  it('renders FBA import precheck totals and row-level errors without committing by default', async () => {
+    expect(warehousesSource).toContain('<el-table v-if="importResult.errors.length" :data="importResult.errors" max-height="260" size="small">')
+    expect(warehousesSource).not.toContain('importResult.errors" max-height="260" size="small" border stripe')
+    const wrapper = await mountView()
+
+    await wrapper.findAll('button').find((button) => button.text().trim() === '导入仓库')?.trigger('click')
+    await flushPromises()
+
+    const upload = wrapper.findComponent({ name: 'ElUpload' })
+    const file = new File(['content'], 'fba.xlsx', { type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' })
+    upload.props('onChange')({ name: file.name, raw: file })
+    await flushPromises()
+
+    const precheckButton = [...document.querySelectorAll('button')].find((button) => button.textContent?.trim() === '预检文件')
+    expect(precheckButton).toBeDefined()
+    precheckButton!.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+    await flushPromises()
+
+    expect(importWarehouses).toHaveBeenCalledWith(file, true, 'CREATE_ONLY')
+    expect(document.body.textContent).toContain('新增')
+    expect(document.body.textContent).toContain('更新')
+    expect(document.body.textContent).toContain('无变化')
+    expect(document.body.textContent).toContain('错误')
+    expect(document.body.textContent).toContain('文件内编码重复')
+    expect(importWarehouses).toHaveBeenCalledTimes(1)
+  })
+})
diff --git a/src/modules/warehouses/pages/WarehousesView.vue b/src/modules/warehouses/pages/WarehousesView.vue
new file mode 100644
index 00000000..7b8698af
--- /dev/null
+++ b/src/modules/warehouses/pages/WarehousesView.vue
@@ -0,0 +1,902 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, onMounted, reactive, ref, watch } from 'vue'
+import { ElMessage, ElMessageBox, type UploadFile } from 'element-plus'
+import { ChevronDown, Download, FileSpreadsheet, FileUp, MapPin, Plus, Save, Warehouse as WarehouseIcon } from '@lucide/vue'
+import AdminPage from '@/shared/components/AdminPage.vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import DataTable, { type DataTableColumn } from '@/shared/components/DataTable.vue'
+import FormSection from '@/shared/components/FormSection.vue'
+import ListPageLayout from '@/shared/components/ListPageLayout.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
+import { useUnsavedWorkRegistration } from '@/core/unsaved-work/useUnsavedWorkRegistration'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import {
+  changePlatformWarehouseStatus,
+  createFbaWarehouse,
+  createPlatformWarehouse,
+  downloadWarehouseImportTemplate,
+  getPlatformWarehouse,
+  importWarehouses,
+  listPlatformWarehouses,
+  updatePlatformWarehouse,
+  type WarehouseImportMode,
+  type WarehouseImportResult,
+  type PlatformWarehouseDetailResource,
+  type PlatformWarehouseSummaryResource,
+  type SavePlatformWarehouseRequest,
+  type WarehouseType,
+} from '@/modules/warehouses/api/platformWarehouses'
+import { useAccessPreviewStore } from '@/core/access/accessPreview'
+import type { Warehouse } from '@/modules/warehouses/types'
+
+const warehouseTypeLabels: Record<WarehouseType, string> = {
+  DOMESTIC: '国内收货仓',
+  FBA: 'FBA 地址',
+  OVERSEAS: '海外仓',
+  OVERSEAS_PARTNER: '海外仓合作仓',
+}
+const timezoneOptions = [
+  'UTC-12', 'UTC-11', 'UTC-10', 'UTC-9', 'UTC-8', 'UTC-7', 'UTC-6', 'UTC-5', 'UTC-4', 'UTC-3',
+  'UTC-2', 'UTC-1', 'UTC+0', 'UTC+1', 'UTC+2', 'UTC+3', 'UTC+4', 'UTC+5', 'UTC+6', 'UTC+7',
+  'UTC+8', 'UTC+9', 'UTC+10', 'UTC+11', 'UTC+12', 'UTC+13', 'UTC+14',
+]
+const countryOptions = [
+  { label: '美国 US', value: 'US' },
+  { label: '加拿大 CA', value: 'CA' },
+  { label: '英国 GB', value: 'GB' },
+  { label: '德国 DE', value: 'DE' },
+  { label: '法国 FR', value: 'FR' },
+  { label: '意大利 IT', value: 'IT' },
+  { label: '西班牙 ES', value: 'ES' },
+  { label: '日本 JP', value: 'JP' },
+  { label: '澳大利亚 AU', value: 'AU' },
+]
+const countryDisplayLabels: Record<string, string> = {
+  CN: '中国',
+  US: '美国',
+  CA: '加拿大',
+  GB: '英国',
+  DE: '德国',
+  FR: '法国',
+  IT: '意大利',
+  ES: '西班牙',
+  JP: '日本',
+  AU: '澳大利亚',
+}
+const usStateOptions = [
+  { label: 'AL Alabama', value: 'AL', timezone: 'UTC-6' },
+  { label: 'AK Alaska', value: 'AK', timezone: 'UTC-9' },
+  { label: 'AZ Arizona', value: 'AZ', timezone: 'UTC-7' },
+  { label: 'AR Arkansas', value: 'AR', timezone: 'UTC-6' },
+  { label: 'CA California', value: 'CA', timezone: 'UTC-8' },
+  { label: 'CO Colorado', value: 'CO', timezone: 'UTC-7' },
+  { label: 'CT Connecticut', value: 'CT', timezone: 'UTC-5' },
+  { label: 'DE Delaware', value: 'DE', timezone: 'UTC-5' },
+  { label: 'FL Florida', value: 'FL', timezone: null },
+  { label: 'GA Georgia', value: 'GA', timezone: 'UTC-5' },
+  { label: 'HI Hawaii', value: 'HI', timezone: 'UTC-10' },
+  { label: 'IA Iowa', value: 'IA', timezone: 'UTC-6' },
+  { label: 'ID Idaho', value: 'ID', timezone: null },
+  { label: 'IL Illinois', value: 'IL', timezone: 'UTC-6' },
+  { label: 'IN Indiana', value: 'IN', timezone: null },
+  { label: 'KS Kansas', value: 'KS', timezone: null },
+  { label: 'KY Kentucky', value: 'KY', timezone: null },
+  { label: 'LA Louisiana', value: 'LA', timezone: 'UTC-6' },
+  { label: 'MA Massachusetts', value: 'MA', timezone: 'UTC-5' },
+  { label: 'MD Maryland', value: 'MD', timezone: 'UTC-5' },
+  { label: 'ME Maine', value: 'ME', timezone: 'UTC-5' },
+  { label: 'MI Michigan', value: 'MI', timezone: null },
+  { label: 'MN Minnesota', value: 'MN', timezone: 'UTC-6' },
+  { label: 'MO Missouri', value: 'MO', timezone: 'UTC-6' },
+  { label: 'MS Mississippi', value: 'MS', timezone: 'UTC-6' },
+  { label: 'MT Montana', value: 'MT', timezone: 'UTC-7' },
+  { label: 'NC North Carolina', value: 'NC', timezone: 'UTC-5' },
+  { label: 'ND North Dakota', value: 'ND', timezone: null },
+  { label: 'NE Nebraska', value: 'NE', timezone: null },
+  { label: 'NH New Hampshire', value: 'NH', timezone: 'UTC-5' },
+  { label: 'NJ New Jersey', value: 'NJ', timezone: 'UTC-5' },
+  { label: 'NM New Mexico', value: 'NM', timezone: 'UTC-7' },
+  { label: 'NV Nevada', value: 'NV', timezone: 'UTC-8' },
+  { label: 'NY New York', value: 'NY', timezone: 'UTC-5' },
+  { label: 'OH Ohio', value: 'OH', timezone: 'UTC-5' },
+  { label: 'OK Oklahoma', value: 'OK', timezone: 'UTC-6' },
+  { label: 'OR Oregon', value: 'OR', timezone: null },
+  { label: 'PA Pennsylvania', value: 'PA', timezone: 'UTC-5' },
+  { label: 'RI Rhode Island', value: 'RI', timezone: 'UTC-5' },
+  { label: 'SC South Carolina', value: 'SC', timezone: 'UTC-5' },
+  { label: 'SD South Dakota', value: 'SD', timezone: null },
+  { label: 'TN Tennessee', value: 'TN', timezone: null },
+  { label: 'TX Texas', value: 'TX', timezone: null },
+  { label: 'VA Virginia', value: 'VA', timezone: 'UTC-5' },
+  { label: 'VT Vermont', value: 'VT', timezone: 'UTC-5' },
+  { label: 'WA Washington', value: 'WA', timezone: 'UTC-8' },
+  { label: 'WI Wisconsin', value: 'WI', timezone: 'UTC-6' },
+  { label: 'WV West Virginia', value: 'WV', timezone: 'UTC-5' },
+  { label: 'WY Wyoming', value: 'WY', timezone: 'UTC-7' },
+]
+
+const access = useAccessPreviewStore()
+const editorOpen = ref(false)
+const editorMode = ref<'CREATE' | 'EDIT'>('CREATE')
+const createType = ref<WarehouseType>('FBA')
+const saving = ref(false)
+const loading = ref(false)
+const editLoading = ref(false)
+const page = ref(1)
+const pageSize = ref(20)
+const total = ref(0)
+const loaded = ref(false)
+const loadError = ref<ApiErrorDetails | null>(null)
+const statusLoadingIds = ref(new Set<string>())
+const importOpen = ref(false)
+const importFile = ref<File | null>(null)
+const importMode = ref<WarehouseImportMode>('CREATE_ONLY')
+const importResult = ref<WarehouseImportResult | null>(null)
+const importing = ref(false)
+const downloadingTemplate = ref(false)
+
+type WarehouseFilters = QueryModel & { keyword: string; warehouseType: WarehouseType | ''; status: Warehouse['status'] | '' }
+const filters = ref<WarehouseFilters>({ keyword: '', warehouseType: '', status: '' })
+const appliedFilters = ref<WarehouseFilters>({ ...filters.value })
+const queryFields: QueryField[] = [
+  { key: 'keyword', type: 'input', label: '仓库关键词', placeholder: '仓库名称、编码、城市或地址' },
+  {
+    key: 'warehouseType', type: 'select', label: '仓库类型', placeholder: '全部仓库类型', options: [
+      { label: warehouseTypeLabels.DOMESTIC, value: 'DOMESTIC' },
+      { label: warehouseTypeLabels.FBA, value: 'FBA' },
+      { label: warehouseTypeLabels.OVERSEAS, value: 'OVERSEAS' },
+      { label: warehouseTypeLabels.OVERSEAS_PARTNER, value: 'OVERSEAS_PARTNER' },
+    ],
+  },
+  {
+    key: 'status', type: 'select', label: '状态', placeholder: '全部状态', options: [
+      { label: '启用', value: 'ACTIVE' },
+      { label: '停用', value: 'INACTIVE' },
+    ],
+  },
+]
+let loadSequence = 0
+
+interface WarehouseRow extends Warehouse {
+  warehouseType: WarehouseType
+  internalCode: string
+  countryCode: string
+  timezone: string
+  postalCode: string
+  detail: PlatformWarehouseDetailResource | null
+}
+
+const rows = ref<WarehouseRow[]>([])
+const warehouseColumns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', width: 180, fixed: 'left', slotName: 'actions' },
+  { key: 'warehouse', label: '仓库名称', minWidth: 190, slotName: 'warehouse' },
+  { key: 'code', prop: 'code', label: '仓库编码', minWidth: 145 },
+  { key: 'internalCode', prop: 'internalCode', label: '内部编号', minWidth: 120 },
+  { key: 'warehouseType', label: '仓库类型', width: 120, slotName: 'warehouseType' },
+  { key: 'countryCode', label: '国家/地区', width: 140, slotName: 'countryCode' },
+  { key: 'timezone', prop: 'timezone', label: '时区', width: 110, defaultVisible: false },
+  { key: 'province', prop: 'province', label: '州/省', minWidth: 130 },
+  { key: 'city', prop: 'city', label: '城市', minWidth: 140 },
+  { key: 'postalCode', prop: 'postalCode', label: '邮编', minWidth: 110 },
+  { key: 'address', label: '地址', minWidth: 280, slotName: 'address', defaultVisible: false },
+  { key: 'contact', label: '联系人', minWidth: 150, slotName: 'contact', defaultVisible: false },
+  { key: 'status', label: '状态', width: 100, slotName: 'status' },
+]
+
+type WarehouseForm = Omit<Warehouse, 'updatedAt'> & {
+  warehouseType: WarehouseType
+  internalCode: string
+  countryCode: string
+  timezone: string
+  postalCode: string
+  receivingCutoffTime: string
+}
+
+function generatedCode(type: WarehouseType) {
+  const prefix = type === 'DOMESTIC' ? 'CN' : type === 'FBA' ? 'FBA' : type === 'OVERSEAS_PARTNER' ? 'PARTNER' : 'US'
+  return `${prefix}-WH-${Date.now().toString(36).slice(-7).toUpperCase()}`
+}
+
+const emptyForm = (type: WarehouseType = 'FBA'): WarehouseForm => ({
+  id: '',
+  code: type === 'FBA' ? '' : generatedCode(type),
+  internalCode: '',
+  name: '',
+  province: '',
+  city: '',
+  address: '',
+  postalCode: '',
+  contactName: '',
+  contactPhone: '',
+  businessHours: '',
+  warehouseType: type,
+  countryCode: type === 'DOMESTIC' ? 'CN' : 'US',
+  timezone: type === 'DOMESTIC' ? 'UTC+8' : '',
+  receivingCutoffTime: type === 'FBA' ? '' : '18:00:00',
+  status: 'ACTIVE',
+  remark: '',
+})
+
+const form = reactive(emptyForm())
+type WarehouseRequiredField = 'code' | 'name' | 'province' | 'countryCode' | 'timezone' | 'city' | 'postalCode' | 'address'
+const requiredFieldMessages: Record<WarehouseRequiredField, string> = {
+  code: '请输入仓库编码',
+  name: '请输入仓库名称',
+  province: '请选择或输入州/省',
+  countryCode: '请选择国家或地区',
+  timezone: '请输入时区',
+  city: '请输入城市',
+  postalCode: '请输入邮编',
+  address: '请输入详细地址',
+}
+const formErrors = reactive<Record<WarehouseRequiredField, string>>({
+  code: '', name: '', province: '', countryCode: '', timezone: '', city: '', postalCode: '', address: '',
+})
+const editorLabel = computed(() => editorMode.value === 'EDIT'
+  ? `编辑${warehouseTypeLabels[form.warehouseType]}`
+  : `新增${warehouseTypeLabels[createType.value]}`)
+const editorPermission = computed(() => editorMode.value === 'EDIT' ? 'platform:warehouse:edit' : 'platform:warehouse:create')
+const isFbaCreate = computed(() => editorMode.value === 'CREATE' && createType.value === 'FBA')
+const isDomesticCreate = computed(() => editorMode.value === 'CREATE' && createType.value === 'DOMESTIC')
+const activeWarehouseType = computed(() => editorMode.value === 'EDIT' ? form.warehouseType : createType.value)
+const isDomesticForm = computed(() => activeWarehouseType.value === 'DOMESTIC')
+const usesUsStateSelect = computed(() => !isDomesticForm.value && form.countryCode === 'US')
+const addressRegionLabel = computed(() => usesUsStateSelect.value || isFbaCreate.value ? '州' : '省 / 州')
+const regionPlaceholder = computed(() => isDomesticForm.value ? '例如 浙江省' : usesUsStateSelect.value ? '请选择州' : '例如 Ontario')
+const cityPlaceholder = computed(() => isDomesticForm.value ? '例如 义乌市' : '例如 Long Beach')
+const addressPlaceholder = computed(() => isFbaCreate.value ? '请输入街道和门牌信息' : '请输入街道、园区、楼栋及门牌信息')
+const canCommitImport = computed(() => Boolean(
+  importFile.value
+  && importResult.value
+  && !importResult.value.committed
+  && importResult.value.errorCount === 0
+  && (importMode.value === 'CREATE_ONLY' || access.can('platform:warehouse:edit')),
+))
+const { captureBaseline } = useUnsavedWorkRegistration({
+  key: 'warehouse-editor',
+  label: editorLabel,
+  isOpen: editorOpen,
+  model: form,
+  requiredPermission: editorPermission,
+})
+
+const warehouseReady = computed(() => loaded.value && !loading.value)
+const loadErrorDescription = computed(() => {
+  if (!loadError.value) return ''
+  const references = [
+    loadError.value.code ? `错误码 ${loadError.value.code}` : '',
+    loadError.value.requestId ? `requestId ${loadError.value.requestId}` : '',
+    loadError.value.traceId ? `traceId ${loadError.value.traceId}` : '',
+  ].filter(Boolean)
+  return [loadError.value.message, references.join(' · ')].filter(Boolean).join(' ')
+})
+
+watch(
+  () => access.can(editorPermission.value),
+  (canWrite) => {
+    if (canWrite || !editorOpen.value) return
+    editorOpen.value = false
+    Object.assign(form, emptyForm())
+  },
+  { flush: 'sync' },
+)
+watch([page, pageSize], ([nextPage, nextSize], [previousPage, previousSize]) => {
+  if (nextPage === previousPage && nextSize === previousSize) return
+  void loadWarehouses()
+})
+watch(importMode, () => { importResult.value = null })
+watch(activeWarehouseType, (type) => {
+  if (type === 'DOMESTIC') {
+    form.countryCode = 'CN'
+    form.timezone = 'UTC+8'
+  } else if (form.countryCode === 'CN') {
+    form.countryCode = 'US'
+    form.province = ''
+    form.timezone = ''
+  }
+  if (type !== 'FBA') form.internalCode = ''
+  clearFieldError('countryCode')
+  clearFieldError('timezone')
+})
+
+function toRow(warehouse: PlatformWarehouseSummaryResource): WarehouseRow {
+  const address = warehouse.primaryAddress
+  const addressText = warehouse.addressSummary
+    || [address?.district, address?.addressLine1, address?.addressLine2].filter(Boolean).join(' ')
+  return {
+    id: String(warehouse.id),
+    code: warehouse.warehouseCode,
+    internalCode: warehouse.internalCode || '',
+    name: warehouse.warehouseName,
+    warehouseType: warehouse.warehouseType,
+    countryCode: warehouse.countryCode,
+    timezone: warehouse.timezone,
+    province: address?.stateProvince || '',
+    city: address?.city || '',
+    address: addressText,
+    postalCode: address?.postalCode || '',
+    contactName: warehouse.contactName || '',
+    contactPhone: digitsOnly(warehouse.contactPhone),
+    businessHours: '',
+    status: warehouse.status,
+    remark: warehouse.remark || '',
+    updatedAt: warehouse.updatedAt?.replace('T', ' ').slice(0, 16) || '',
+    detail: null,
+  }
+}
+
+function queryWarehouses(model: QueryModel) {
+  appliedFilters.value = {
+    keyword: String(model.keyword || ''),
+    warehouseType: (model.warehouseType || '') as WarehouseType | '',
+    status: (model.status || '') as Warehouse['status'] | '',
+  }
+  if (page.value === 1) void loadWarehouses()
+  else page.value = 1
+}
+
+function clearWarehouseFormErrors() {
+  for (const field of Object.keys(formErrors) as WarehouseRequiredField[]) formErrors[field] = ''
+}
+
+function clearFieldError(field: WarehouseRequiredField) {
+  if (formErrors[field]) formErrors[field] = ''
+}
+
+function formatCountryDisplay(countryCode: string) {
+  const code = countryCode.trim().toUpperCase()
+  if (!code) return '-'
+  const label = countryDisplayLabels[code]
+  return label ? `${label} ${code}` : code
+}
+
+function validateFields(fields: WarehouseRequiredField[]) {
+  return fields.map((field) => {
+    formErrors[field] = form[field].trim() ? '' : requiredFieldMessages[field]
+    return !formErrors[field]
+  }).every(Boolean)
+}
+
+function validateWarehouseForm() {
+  if (isFbaCreate.value) return validateFields(['code', 'province', 'city', 'postalCode', 'timezone', 'address'])
+  const fields: WarehouseRequiredField[] = ['code', 'name', 'countryCode', 'timezone', 'city', 'address']
+  if (usesUsStateSelect.value) fields.splice(4, 0, 'province')
+  return validateFields(fields)
+}
+
+function onCountryChange(value: string) {
+  form.countryCode = value.toUpperCase()
+  clearFieldError('countryCode')
+  if (!usesUsStateSelect.value) {
+    form.province = ''
+    form.timezone = ''
+    clearFieldError('province')
+    return
+  }
+  const matchedState = usStateOptions.find((state) => state.value === form.province.toUpperCase())
+  if (!matchedState) {
+    form.province = ''
+    form.timezone = ''
+    return
+  }
+  onRegionChange(matchedState.value)
+}
+
+function onRegionChange(value: string) {
+  form.province = value.toUpperCase()
+  clearFieldError('province')
+  if (!usesUsStateSelect.value) return
+  const matchedState = usStateOptions.find((state) => state.value === form.province)
+  if (matchedState?.timezone) {
+    form.timezone = matchedState.timezone
+    clearFieldError('timezone')
+  } else {
+    form.timezone = ''
+  }
+}
+
+async function loadWarehouses() {
+  const sequence = ++loadSequence
+  loading.value = true
+  loadError.value = null
+  try {
+    const result = await listPlatformWarehouses({
+      page: page.value,
+      size: pageSize.value,
+      keyword: appliedFilters.value.keyword.trim() || undefined,
+      warehouseType: appliedFilters.value.warehouseType || undefined,
+      status: appliedFilters.value.status || undefined,
+    })
+    if (sequence !== loadSequence) return
+    rows.value = result.records.map(toRow)
+    total.value = result.total
+    loaded.value = true
+  } catch (error) {
+    if (sequence !== loadSequence) return
+    loadError.value = getApiErrorDetails(error, '仓库数据加载失败，请稍后重试')
+  } finally {
+    if (sequence === loadSequence) loading.value = false
+  }
+}
+
+function requireWarehouseReady() {
+  if (!warehouseReady.value) {
+    ElMessage.warning('仓库数据尚未加载完成，请稍后重试')
+    return false
+  }
+  return true
+}
+
+function openCreate(type: WarehouseType) {
+  if (!requireWarehouseReady()) return
+  editorMode.value = 'CREATE'
+  createType.value = type
+  Object.assign(form, emptyForm(type))
+  clearWarehouseFormErrors()
+  captureBaseline()
+  editorOpen.value = true
+}
+
+async function ensureDetail(warehouse: WarehouseRow) {
+  if (warehouse.detail) return warehouse.detail
+  if (!requireWarehouseReady()) return null
+  try {
+    const detail = await getPlatformWarehouse(warehouse.id)
+    warehouse.detail = detail
+    return detail
+  } catch (error) {
+    const details = getApiErrorDetails(error, '仓库详情加载失败，请重试')
+    ElMessage.error(details.requestId ? `${details.message}（requestId: ${details.requestId}）` : details.message)
+    return null
+  }
+}
+
+async function openEdit(warehouse: WarehouseRow) {
+  editLoading.value = true
+  try {
+    const detail = await ensureDetail(warehouse)
+    if (!detail || !loaded.value) return
+    const address = detail.addresses[0]
+    const receiving = detail.capabilities.find((item) => item.capabilityCode === 'RECEIVING')
+    editorMode.value = 'EDIT'
+    Object.assign(form, {
+      id: String(detail.warehouse.id),
+      code: detail.warehouse.warehouseCode,
+      internalCode: detail.warehouse.internalCode || '',
+      name: detail.warehouse.warehouseName,
+      warehouseType: detail.warehouse.warehouseType,
+      countryCode: detail.warehouse.countryCode,
+      timezone: detail.warehouse.timezone,
+      province: address?.stateProvince || '',
+      city: address?.city || '',
+      address: address?.addressLine1 || '',
+      postalCode: address?.postalCode || '',
+      contactName: detail.warehouse.contactName || '',
+      contactPhone: digitsOnly(detail.warehouse.contactPhone),
+      receivingCutoffTime: receiving?.cutoffTime || '',
+      status: detail.warehouse.status,
+      remark: detail.warehouse.remark || '',
+    })
+    clearWarehouseFormErrors()
+    captureBaseline()
+    editorOpen.value = true
+  } finally {
+    editLoading.value = false
+  }
+}
+
+function nullable(value: string) {
+  return value.trim() || null
+}
+
+function digitsOnly(value: unknown) {
+  return String(value || '').replace(/\D/g, '').slice(0, 32)
+}
+
+function buildSaveRequest(): SavePlatformWarehouseRequest {
+  const existing = form.id ? rows.value.find((item) => item.id === form.id)?.detail : null
+  const warehouse = existing?.warehouse
+  const currentAddress = existing?.addresses[0]
+  const countryCode = isDomesticForm.value ? 'CN' : form.countryCode.trim().toUpperCase()
+  const timezone = isDomesticForm.value ? 'UTC+8' : form.timezone.trim()
+  const capabilities = (existing?.capabilities || []).map((capability) => ({
+    capabilityCode: capability.capabilityCode,
+    capabilityName: capability.capabilityName,
+    enabled: capability.enabled ?? true,
+    cutoffTime: capability.capabilityCode === 'RECEIVING' ? nullable(form.receivingCutoffTime) : capability.cutoffTime,
+    description: capability.description,
+  }))
+  if (form.warehouseType !== 'FBA' && !capabilities.some((item) => item.capabilityCode === 'RECEIVING')) {
+    capabilities.push({
+      capabilityCode: 'RECEIVING', capabilityName: '收货服务', enabled: true, cutoffTime: null,
+      description: null,
+    })
+  }
+  return {
+    warehouseCode: form.code.trim().toUpperCase(),
+    internalCode: form.warehouseType === 'FBA' ? nullable(form.internalCode)?.toUpperCase() || null : null,
+    warehouseName: form.name.trim(),
+    warehouseType: form.warehouseType,
+    countryCode,
+    timezone,
+    contactName: nullable(form.contactName),
+    contactPhone: nullable(form.contactPhone),
+    contactEmail: warehouse?.contactEmail || null,
+    status: form.status,
+    remark: nullable(form.remark),
+    address: {
+      addressType: currentAddress?.addressType || 'OPERATING',
+      countryCode,
+      stateProvince: nullable(form.province),
+      city: form.city.trim(),
+      district: currentAddress?.district || null,
+      postalCode: nullable(form.postalCode),
+      addressLine1: form.address.trim(),
+      addressLine2: currentAddress?.addressLine2 || null,
+      latitude: currentAddress?.latitude || null,
+      longitude: currentAddress?.longitude || null,
+    },
+    capabilities,
+  }
+}
+
+async function saveWarehouse() {
+  if (!requireWarehouseReady() || !validateWarehouseForm()) return
+  saving.value = true
+  try {
+    if (isFbaCreate.value) {
+      await createFbaWarehouse({
+        warehouseCode: form.code.trim().toUpperCase(),
+        internalCode: nullable(form.internalCode)?.toUpperCase() || null,
+        stateProvince: form.province.trim().toUpperCase(),
+        city: form.city.trim(),
+        postalCode: form.postalCode.trim(),
+        addressLine1: form.address.trim(),
+        timezone: form.timezone.trim() || null,
+      })
+    } else {
+      const payload = buildSaveRequest()
+      if (editorMode.value === 'EDIT') await updatePlatformWarehouse(form.id, payload)
+      else await createPlatformWarehouse(payload)
+    }
+    editorOpen.value = false
+    ElMessage.success(editorMode.value === 'EDIT' ? '仓库资料已更新' : `${warehouseTypeLabels[createType.value]}已创建`)
+    if (page.value === 1) await loadWarehouses()
+    else page.value = 1
+  } catch (error) {
+    const details = getApiErrorDetails(error, '仓库保存失败，请检查后重试')
+    ElMessage.error(details.requestId ? `${details.message}（requestId: ${details.requestId}）` : details.message)
+  } finally {
+    saving.value = false
+  }
+}
+
+async function toggleStatus(warehouse: WarehouseRow) {
+  if (!requireWarehouseReady()) return
+  const target = warehouse.status === 'ACTIVE' ? 'INACTIVE' : 'ACTIVE'
+  const targetText = target === 'ACTIVE' ? '启用' : '停用'
+  try {
+    await ElMessageBox.confirm(
+      target === 'INACTIVE'
+        ? `停用“${warehouse.name}”后，客户新建头程订单时将无法选择该公共仓库。`
+        : `确认重新启用“${warehouse.name}”供客户下单选择吗？`,
+      `${targetText}公共仓库`,
+      { customClass: 'admin-density-confirm', confirmButtonText: `确认${targetText}`, cancelButtonText: '取消', type: target === 'INACTIVE' ? 'warning' : 'info' },
+    )
+    statusLoadingIds.value = new Set(statusLoadingIds.value).add(warehouse.id)
+    await changePlatformWarehouseStatus(warehouse.id, target)
+    warehouse.status = target
+    if (warehouse.detail) warehouse.detail.warehouse.status = target
+    ElMessage.success(`仓库已${targetText}`)
+  } catch (error) {
+    if (error === 'cancel' || error === 'close') return
+    const details = getApiErrorDetails(error, `仓库${targetText}失败，请重试`)
+    ElMessage.error(details.requestId ? `${details.message}（requestId: ${details.requestId}）` : details.message)
+  } finally {
+    const next = new Set(statusLoadingIds.value)
+    next.delete(warehouse.id)
+    statusLoadingIds.value = next
+  }
+}
+
+function openImport() {
+  importFile.value = null
+  importMode.value = 'CREATE_ONLY'
+  importResult.value = null
+  importOpen.value = true
+}
+
+function selectImportFile(uploadFile: UploadFile) {
+  const file = uploadFile.raw ?? null
+  if (!file) return
+  if (!file.name.toLowerCase().endsWith('.xlsx')) {
+    importFile.value = null
+    ElMessage.error('请选择标准 XLSX 文件')
+    return
+  }
+  if (file.size > 5 * 1024 * 1024) {
+    importFile.value = null
+    ElMessage.error('文件不得超过 5MB')
+    return
+  }
+  importFile.value = file
+  importResult.value = null
+}
+
+function removeImportFile() {
+  importFile.value = null
+  importResult.value = null
+}
+
+function saveBlob(blob: Blob, fileName: string) {
+  const url = URL.createObjectURL(blob)
+  const anchor = document.createElement('a')
+  anchor.href = url
+  anchor.download = fileName
+  anchor.click()
+  URL.revokeObjectURL(url)
+}
+
+async function downloadTemplate() {
+  downloadingTemplate.value = true
+  try {
+    const blob = await downloadWarehouseImportTemplate()
+    saveBlob(blob, '公共仓库导入模板.xlsx')
+  } catch (error) {
+    ElMessage.error(getApiErrorDetails(error, '模板下载失败，请稍后重试').message)
+  } finally {
+    downloadingTemplate.value = false
+  }
+}
+
+async function runImport(dryRun: boolean) {
+  if (!importFile.value) {
+    ElMessage.warning('请先选择 XLSX 文件')
+    return
+  }
+  importing.value = true
+  try {
+    importResult.value = await importWarehouses(importFile.value, dryRun, importMode.value)
+    if (dryRun) {
+      ElMessage.success(importResult.value.errorCount ? '预检完成，请处理错误后重新上传' : '预检通过，可以提交导入')
+    } else if (importResult.value.committed) {
+      ElMessage.success('公共仓库已导入')
+      if (page.value === 1) await loadWarehouses()
+      else page.value = 1
+    }
+  } catch (error) {
+    ElMessage.error(getApiErrorDetails(error, dryRun ? '文件预检失败，请检查后重试' : '公共仓库导入失败，请重试').message)
+  } finally {
+    importing.value = false
+  }
+}
+
+function downloadImportErrors() {
+  if (!importResult.value?.errors.length) return
+  const escape = (value: string | number) => `"${String(value).replaceAll('"', '""')}"`
+  const lines = ['行号,字段,错误码,原因', ...importResult.value.errors.map((error) => (
+    [error.row, error.field, error.code || '-', error.message].map(escape).join(',')
+  ))]
+  saveBlob(new Blob([`\uFEFF${lines.join('\r\n')}`], { type: 'text/csv;charset=utf-8' }), '公共仓库导入错误清单.csv')
+}
+
+function formatImportErrorCode(row: WarehouseImportResult['errors'][number]) {
+  return row.code || '-'
+}
+
+onMounted(() => void loadWarehouses())
+</script>
+
+<template>
+  <AdminPage class="admin-density" as="div">
+    <ListPageLayout aria-label="仓库列表页面">
+      <template #toolbar>
+        <QueryToolbar v-model="filters" class="surface-panel" ariaLabel="仓库筛选" :fields="queryFields" :loading="loading" preference-key="warehouses-query" @search="queryWarehouses" />
+      </template>
+      <template v-if="loadError" #state>
+        <LoadErrorState
+          title="仓库数据加载失败"
+          :message="loadErrorDescription"
+          :loading="loading"
+          retry-text="重新查询"
+          @retry="loadWarehouses"
+        />
+      </template>
+
+      <section v-if="!loadError" class="surface-panel table-panel" aria-live="polite">
+      <DataTable
+        v-model:page="page"
+        v-model:page-size="pageSize"
+        :data="rows"
+        :columns="warehouseColumns"
+        border
+        stripe
+        preference-key="warehouses-table"
+        :loading="loading"
+        :total="total"
+        :page-sizes="[20, 50, 100]"
+        row-key="id"
+        aria-label="公共仓库列表"
+        :empty-text="loaded ? '暂无符合筛选条件的仓库' : '仓库数据暂不可用，请重新加载'"
+      >
+        <template #toolbar-actions>
+          <div v-if="access.can('platform:warehouse:create')" class="warehouse-primary-actions">
+            <el-button :disabled="!warehouseReady" @click="openImport"><FileUp :size="16" />导入仓库</el-button>
+            <el-dropdown popper-class="admin-density warehouse-create-menu" trigger="click" :disabled="!warehouseReady" @command="openCreate($event as WarehouseType)">
+              <el-button type="primary" :disabled="!warehouseReady"><Plus :size="16" />新增仓库<ChevronDown :size="15" /></el-button>
+              <template #dropdown><el-dropdown-menu><el-dropdown-item command="FBA"><FileSpreadsheet :size="15" />新增 FBA 地址</el-dropdown-item><el-dropdown-item command="DOMESTIC"><WarehouseIcon :size="15" />新增国内仓</el-dropdown-item><el-dropdown-item command="OVERSEAS"><MapPin :size="15" />新增海外仓</el-dropdown-item><el-dropdown-item command="OVERSEAS_PARTNER"><MapPin :size="15" />新增海外仓合作仓</el-dropdown-item></el-dropdown-menu></template>
+            </el-dropdown>
+          </div>
+        </template>
+        <template #actions="{ row }">
+          <div v-if="access.can('platform:warehouse:edit') || access.can('platform:warehouse:status')" class="table-actions density-actions">
+            <el-button data-tone="neutral" class="density-action" v-if="access.can('platform:warehouse:edit')" size="small" :disabled="!warehouseReady || editLoading" @click="openEdit(row as WarehouseRow)">编辑</el-button>
+            <el-button class="density-action"
+              v-if="access.can('platform:warehouse:status')"
+              size="small"
+
+              :data-tone="(row as WarehouseRow).status === 'ACTIVE' ? 'danger' : 'success'"
+              :disabled="!warehouseReady"
+              :loading="statusLoadingIds.has((row as WarehouseRow).id)"
+              @click="toggleStatus(row as WarehouseRow)"
+            >{{ (row as WarehouseRow).status === 'ACTIVE' ? '停用' : '启用' }}</el-button>
+          </div>
+          <span v-else class="warehouse-subline">仅查看</span>
+        </template>
+        <template #warehouse="{ row }"><div class="warehouse-cell"><div><strong>{{ (row as WarehouseRow).name }}</strong></div></div></template>
+        <template #warehouseType="{ row }"><el-tag effect="plain">{{ warehouseTypeLabels[(row as WarehouseRow).warehouseType] }}</el-tag></template>
+        <template #countryCode="{ row }">{{ formatCountryDisplay((row as WarehouseRow).countryCode) }}</template>
+        <template #address="{ row }"><div class="warehouse-address"><MapPin :size="15" /><span>{{ (row as WarehouseRow).address || '-' }}</span></div></template>
+        <template #contact="{ row }"><strong>{{ (row as WarehouseRow).contactName || '-' }}</strong><span class="warehouse-subline">{{ (row as WarehouseRow).contactPhone || '-' }}</span></template>
+        <template #status="{ row }"><el-tag :type="(row as WarehouseRow).status === 'ACTIVE' ? 'success' : 'info'" effect="light">{{ (row as WarehouseRow).status === 'ACTIVE' ? '启用' : '停用' }}</el-tag></template>
+        <template #pagination-left="{ total: tableTotal }">共 {{ tableTotal }} 个公共仓库</template>
+      </DataTable>
+      </section>
+    </ListPageLayout>
+
+    <AppDialog v-model="editorOpen" :title="editorLabel" width="min(650px, calc(100vw - 28px))" class="warehouse-editor-dialog admin-density-dialog" :close-on-click-modal="false" :confirm-loading="saving" :show-confirm="false" destroy-on-close>
+      <el-form :model="form" label-position="top" class="density-form" :disabled="saving">
+        <FormSection class="density-form-section" title="基础信息">
+          <div class="form-grid two-cols">
+            <el-form-item v-if="isFbaCreate" label="FBA 编码" required :class="{ 'has-field-error': formErrors.code }"><el-input v-model="form.code" maxlength="50" placeholder="例如 LAX9" @input="form.code = String($event).toUpperCase(); clearFieldError('code')" /><p v-if="formErrors.code" class="field-error" role="alert">{{ formErrors.code }}</p></el-form-item>
+            <el-form-item v-if="isFbaCreate" label="国家或地区" required>
+              <el-select v-model="form.countryCode" disabled placeholder="美国 US">
+                <el-option label="美国 US" value="US" />
+              </el-select>
+            </el-form-item>
+            <template v-else>
+              <el-form-item label="仓库名称" required :class="{ 'has-field-error': formErrors.name }"><el-input v-model="form.name" maxlength="120" placeholder="请输入仓库名称" @input="clearFieldError('name')" /><p v-if="formErrors.name" class="field-error" role="alert">{{ formErrors.name }}</p></el-form-item>
+              <el-form-item v-if="editorMode === 'EDIT'" label="仓库类型" required><el-select v-model="form.warehouseType"><el-option v-for="(label, value) in warehouseTypeLabels" :key="value" :label="label" :value="value" /></el-select></el-form-item>
+              <el-form-item v-if="!isDomesticCreate" label="国家或地区" required :class="{ 'has-field-error': formErrors.countryCode }">
+                <el-select v-if="isDomesticForm" v-model="form.countryCode" disabled placeholder="中国 CN"><el-option label="中国 CN" value="CN" /></el-select>
+                <el-select v-else v-model="form.countryCode" filterable placeholder="请选择国家或地区" @change="onCountryChange"><el-option v-for="country in countryOptions" :key="country.value" :label="country.label" :value="country.value" /></el-select>
+                <p v-if="formErrors.countryCode" class="field-error" role="alert">{{ formErrors.countryCode }}</p>
+              </el-form-item>
+              <el-form-item v-if="!isDomesticCreate" label="时区" required :class="{ 'has-field-error': formErrors.timezone }">
+                <el-select v-if="isDomesticForm" v-model="form.timezone" disabled placeholder="UTC+8"><el-option label="UTC+8" value="UTC+8" /></el-select>
+                <el-select v-else v-model="form.timezone" filterable placeholder="请选择时区" @change="clearFieldError('timezone')"><el-option v-for="timezone in timezoneOptions" :key="timezone" :label="timezone" :value="timezone" /></el-select>
+                <p v-if="formErrors.timezone" class="field-error" role="alert">{{ formErrors.timezone }}</p>
+              </el-form-item>
+            </template>
+            <el-form-item v-if="activeWarehouseType === 'FBA'" label="内部编号"><el-input v-model="form.internalCode" maxlength="16" placeholder="例如 154 或 CADF" @input="form.internalCode = String($event ?? '').replace(/[^a-zA-Z0-9]/g, '').toUpperCase().slice(0, 16)" /></el-form-item>
+          </div>
+        </FormSection>
+
+        <FormSection class="density-form-section" title="地址信息">
+          <div class="form-grid two-cols">
+            <el-form-item :label="addressRegionLabel" :required="isFbaCreate || usesUsStateSelect" :class="{ 'has-field-error': formErrors.province }">
+              <el-select v-if="usesUsStateSelect" v-model="form.province" filterable :placeholder="regionPlaceholder" @change="onRegionChange"><el-option v-for="state in usStateOptions" :key="state.value" :label="state.label" :value="state.value" /></el-select>
+              <el-input v-else v-model="form.province" maxlength="100" :placeholder="regionPlaceholder" @input="isFbaCreate && (form.province = String($event).toUpperCase()); clearFieldError('province')" />
+              <p v-if="formErrors.province" class="field-error" role="alert">{{ formErrors.province }}</p>
+            </el-form-item>
+            <el-form-item label="城市" required :class="{ 'has-field-error': formErrors.city }"><el-input v-model="form.city" maxlength="100" :placeholder="cityPlaceholder" @input="clearFieldError('city')" /><p v-if="formErrors.city" class="field-error" role="alert">{{ formErrors.city }}</p></el-form-item>
+            <el-form-item label="邮编" :required="isFbaCreate" :class="{ 'has-field-error': formErrors.postalCode }"><el-input v-model="form.postalCode" maxlength="20" :placeholder="isDomesticForm ? '例如 322000' : '例如 90802'" @input="clearFieldError('postalCode')" /><p v-if="formErrors.postalCode" class="field-error" role="alert">{{ formErrors.postalCode }}</p></el-form-item>
+          </div>
+          <el-form-item label="详细地址" required :class="{ 'has-field-error': formErrors.address }"><el-input v-model="form.address" maxlength="255" type="textarea" :rows="3" :placeholder="addressPlaceholder" @input="clearFieldError('address')" /><p v-if="formErrors.address" class="field-error" role="alert">{{ formErrors.address }}</p></el-form-item>
+        </FormSection>
+
+        <FormSection class="density-form-section" v-if="!isFbaCreate" title="编码与状态">
+          <div class="form-grid two-cols compact-grid">
+            <el-form-item label="仓库编码" :class="{ 'has-field-error': formErrors.code }"><el-input v-model="form.code" maxlength="50" placeholder="系统自动生成" @input="form.code = String($event).toUpperCase(); clearFieldError('code')" /><p v-if="formErrors.code" class="field-error" role="alert">{{ formErrors.code }}</p></el-form-item>
+            <el-form-item label="状态"><el-radio-group v-model="form.status" class="warehouse-status-toggle"><el-radio-button value="ACTIVE">启用</el-radio-button><el-radio-button value="INACTIVE">停用</el-radio-button></el-radio-group></el-form-item>
+          </div>
+        </FormSection>
+
+        <FormSection class="density-form-section" v-if="!isFbaCreate" title="联系信息">
+          <div class="form-grid two-cols compact-grid">
+            <el-form-item label="联系人"><el-input v-model="form.contactName" maxlength="64" placeholder="选填" /></el-form-item>
+            <el-form-item label="联系电话"><el-input v-model="form.contactPhone" maxlength="32" inputmode="numeric" placeholder="选填" @input="form.contactPhone = digitsOnly($event)" /></el-form-item>
+            <el-form-item label="收货时间"><el-time-picker v-model="form.receivingCutoffTime" value-format="HH:mm:ss" format="HH:mm" placeholder="请选择收货截止时间" /></el-form-item>
+          </div>
+          <el-form-item label="备注"><el-input v-model="form.remark" maxlength="500" type="textarea" :rows="3" show-word-limit placeholder="选填" /></el-form-item>
+        </FormSection>
+      </el-form>
+      <template #footer><div class="drawer-footer"><el-button :disabled="saving" @click="editorOpen = false">取消</el-button><el-button type="primary" :loading="saving" @click="saveWarehouse"><Save :size="16" />{{ editorMode === 'EDIT' ? '保存修改' : '确认新增' }}</el-button></div></template>
+    </AppDialog>
+
+    <el-dialog class="admin-density-dialog" v-model="importOpen" title="导入公共仓库" width="min(760px, calc(100vw - 32px))" :close-on-click-modal="!importing" :close-on-press-escape="!importing">
+      <div class="import-content">
+        <div class="import-toolbar">
+          <el-button :loading="downloadingTemplate" @click="downloadTemplate"><Download :size="16" />下载 XLSX 模板</el-button>
+          <el-radio-group v-model="importMode" :disabled="importing">
+            <el-radio-button value="CREATE_ONLY">仅新增</el-radio-button>
+            <el-radio-button value="UPSERT" :disabled="!access.can('platform:warehouse:edit')">新增并更新</el-radio-button>
+          </el-radio-group>
+        </div>
+        <el-upload accept=".xlsx" :auto-upload="false" :limit="1" :on-change="selectImportFile" :on-remove="removeImportFile">
+          <el-button><FileUp :size="16" />选择 XLSX 文件</el-button>
+          <template #tip><div class="el-upload__tip">最多 5MB、1000 行；请使用标准模板，FBA 名称可不填并默认使用编码。</div></template>
+        </el-upload>
+        <div v-if="importResult" class="import-result" role="status">
+          <dl class="import-summary density-detail-overview">
+            <div><dt>总行数</dt><dd>{{ importResult.totalRows }}</dd></div>
+            <div><dt>有效</dt><dd>{{ importResult.validRows }}</dd></div>
+            <div><dt>新增</dt><dd>{{ importResult.createCount }}</dd></div>
+            <div><dt>更新</dt><dd>{{ importResult.updateCount }}</dd></div>
+            <div><dt>无变化</dt><dd>{{ importResult.unchangedCount }}</dd></div>
+            <div><dt>错误</dt><dd :class="{ 'is-error': importResult.errorCount }">{{ importResult.errorCount }}</dd></div>
+          </dl>
+          <div class="import-result-heading"><strong>{{ importResult.committed ? '导入已提交' : (importResult.errorCount ? '预检未通过，未写入数据' : '预检通过，尚未写入数据') }}</strong><el-button v-if="importResult.errors.length" size="small" @click="downloadImportErrors"><Download :size="15" />下载错误清单</el-button></div>
+          <el-table v-if="importResult.errors.length" :data="importResult.errors" max-height="260" size="small">
+            <el-table-column prop="row" label="行号" width="70" /><el-table-column prop="field" label="字段" width="110" /><el-table-column prop="code" label="错误码" width="130" :formatter="formatImportErrorCode" /><el-table-column prop="message" label="原因" min-width="220" />
+          </el-table>
+        </div>
+      </div>
+      <template #footer><el-button :disabled="importing" @click="importOpen = false">关闭</el-button><el-button :loading="importing" :disabled="!importFile" @click="runImport(true)">预检文件</el-button><el-button type="primary" :loading="importing" :disabled="!canCommitImport" @click="runImport(false)"><FileUp :size="16" />确认导入</el-button></template>
+    </el-dialog>
+  </AdminPage>
+</template>
+
+<style scoped>
+.state-alert p { margin: var(--admin-space-2) 0 var(--admin-space-4); line-height: 1.55; }
+.warehouse-heading { gap: var(--admin-space-6); }
+.warehouse-primary-actions, .import-toolbar, .import-result-heading { display: flex; flex-wrap: wrap; align-items: center; gap: var(--admin-space-4); }
+.warehouse-cell { display: flex; align-items: center; gap: var(--admin-space-4); }
+.warehouse-cell > span { display: grid; width: 34px; height: 34px; flex: 0 0 34px; place-items: center; border-radius: var(--admin-radius); background: #eef3fa; color: var(--cc-primary); }
+.warehouse-cell > div { display: flex; min-width: 0; flex-direction: column; gap: 3px; }
+.warehouse-cell strong { overflow-wrap: anywhere; }
+.warehouse-cell small, .warehouse-subline, .warehouse-address small { display: block; color: var(--cc-muted); font-size: var(--admin-font-caption); }
+.warehouse-address { display: flex; align-items: flex-start; gap: 7px; line-height: 1.55; overflow-wrap: anywhere; }
+.warehouse-address svg { flex: 0 0 15px; margin-top: 2px; color: var(--cc-muted); }
+.warehouse-address span { min-width: 0; }
+.field-error { width: 100%; margin: var(--admin-space-2) 0 0; color: var(--el-color-danger); font-size: var(--admin-font-caption); line-height: 1.35; overflow-wrap: anywhere; }
+.compact-grid { row-gap: var(--admin-space-4); }
+:global(.warehouse-editor-dialog) { max-height: min(800px, calc(100vh - 32px)); display: flex; flex-direction: column; }
+:global(.warehouse-editor-dialog .el-dialog__body) { min-height: 0; overflow-y: auto; }
+:global(.warehouse-editor-dialog .el-dialog__footer) { flex: 0 0 auto; }
+.warehouse-status-toggle :deep(.el-radio-button__inner) { min-width: 74px; }
+@media (max-width: 720px) {
+  .density-form :deep(.form-grid.two-cols) { grid-template-columns: minmax(0, 1fr); }
+}
+.import-content { display: grid; gap: var(--admin-space-7); }
+.import-toolbar { justify-content: space-between; }
+.import-result { display: grid; gap: var(--admin-space-5); padding-top: var(--admin-space-6); border-top: 1px solid var(--cc-border); }
+.import-result-heading { justify-content: space-between; }
+
+:deep(.has-field-error .el-input__wrapper) { box-shadow: 0 0 0 1px var(--el-color-danger) inset; }
+:deep(.has-field-error .el-textarea__inner) { box-shadow: 0 0 0 1px var(--el-color-danger) inset; }
+:global(.warehouse-create-menu .el-dropdown-menu__item) { gap: var(--admin-space-3); }
+
+@media (max-width: 720px) {
+  .warehouse-heading { align-items: stretch; }
+  .warehouse-primary-actions { width: 100%; }
+  .warehouse-primary-actions > .el-button, .warehouse-primary-actions > .el-dropdown { flex: 1 1 150px; }
+  .warehouse-primary-actions :deep(.el-dropdown .el-button) { width: 100%; min-height: 44px; }
+  .warehouse-primary-actions > .el-button { min-height: 44px; }
+  .import-toolbar { align-items: stretch; flex-direction: column; }
+  .import-summary { grid-template-columns: repeat(3, minmax(0, 1fr)); }
+  .import-summary div:nth-child(3) { border-right: 0; }
+  .import-summary div:nth-child(-n+3) { border-bottom: 1px solid var(--cc-border); }
+}
+
+@media (max-width: 420px) {
+  .warehouse-primary-actions { flex-direction: column; }
+  .warehouse-primary-actions > .el-button, .warehouse-primary-actions > .el-dropdown { width: 100%; flex-basis: auto; }
+  .import-summary { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+  .import-summary div:nth-child(3) { border-right: 1px solid var(--cc-border); }
+  .import-summary div:nth-child(2n) { border-right: 0; }
+  .import-summary div:nth-child(-n+4) { border-bottom: 1px solid var(--cc-border); }
+}
+</style>
diff --git a/src/modules/warehouses/routes.ts b/src/modules/warehouses/routes.ts
new file mode 100644
index 00000000..612f2e3c
--- /dev/null
+++ b/src/modules/warehouses/routes.ts
@@ -0,0 +1,10 @@
+import type { RouteRecordRaw } from 'vue-router'
+
+export const warehouseRoutes = [
+  {
+    path: 'warehouses',
+    name: 'warehouses',
+    component: () => import('@/modules/warehouses/pages/WarehousesView.vue'),
+    meta: { title: '仓库管理', description: '统一维护国内收货仓、FBA 仓和海外仓', permission: 'platform:warehouse:list' },
+  },
+] satisfies RouteRecordRaw[]
diff --git a/src/modules/warehouses/types.ts b/src/modules/warehouses/types.ts
new file mode 100644
index 00000000..3b76aabe
--- /dev/null
+++ b/src/modules/warehouses/types.ts
@@ -0,0 +1,3 @@
+import type { PlatformReceivingWarehouse } from '@chongchong/shared'
+
+export type Warehouse = PlatformReceivingWarehouse
diff --git a/src/navigation/adminNavigation.test.ts b/src/navigation/adminNavigation.test.ts
deleted file mode 100644
index 8d3f0825..00000000
--- a/src/navigation/adminNavigation.test.ts
+++ /dev/null
@@ -1,111 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import {
-  adminNavigation,
-  filterAdminNavigation,
-  getFirstNavigationLeaf,
-  getNavigationLeaves,
-  type AdminNavigationNode,
-} from './adminNavigation'
-
-describe('adminNavigation', () => {
-  it('keeps phase-one pages grouped without exposing the deferred dashboard', () => {
-    expect(adminNavigation.map((item) => item.title)).toEqual([
-      '业务管理',
-      '基础资料',
-      '系统管理',
-    ])
-    expect(adminNavigation[0].children?.map((item) => item.title)).toEqual([
-      '客户管理',
-      '企业审核',
-      '仓库管理',
-      '头程订单',
-    ])
-    expect(adminNavigation[1].children?.map((item) => item.title)).toEqual(['快递公司', '往来单位'])
-    expect(adminNavigation[2].children?.map((item) => item.title)).toEqual([
-      '内部用户',
-      '角色管理',
-      '菜单权限',
-    ])
-  })
-
-  it('assigns every page a unique path and permission code', () => {
-    const leaves = getNavigationLeaves(adminNavigation)
-    const paths = leaves.map((item) => item.path)
-    const permissions = leaves.map((item) => item.permission)
-
-    expect(paths).toEqual([
-      '/customers',
-      '/customers/reviews',
-      '/warehouses',
-      '/orders/first-leg',
-      '/master-data/express-companies',
-      '/master-data/counterparties',
-      '/system/users',
-      '/system/roles',
-      '/system/permissions',
-    ])
-    expect(new Set(paths).size).toBe(paths.length)
-    expect(new Set(permissions).size).toBe(permissions.length)
-    expect(leaves.every((item) => Boolean(item.icon))).toBe(true)
-  })
-
-  it('recursively filters leaves without mutating the source tree', () => {
-    const sourceSnapshot = JSON.stringify(adminNavigation, (key, value) => key === 'icon' ? '[icon]' : value)
-    const filtered = filterAdminNavigation(adminNavigation, new Set(['platform:permission:list']))
-
-    expect(getNavigationLeaves(filtered).map((item) => item.path)).toEqual(['/system/permissions'])
-    expect(filtered).not.toBe(adminNavigation)
-    expect(filtered[0]).not.toBe(adminNavigation[2])
-    expect(JSON.stringify(adminNavigation, (key, value) => key === 'icon' ? '[icon]' : value)).toBe(sourceSnapshot)
-  })
-
-  it('keeps directories based on accessible descendants instead of a directory permission', () => {
-    const nodes: AdminNavigationNode[] = [{
-      key: 'operations',
-      title: '运营管理',
-      icon: adminNavigation[0].icon,
-      permission: 'directory:denied',
-      children: [{
-        key: 'tracking',
-        title: '轨迹管理',
-        icon: adminNavigation[0].icon,
-        path: '/tracking',
-        permission: 'tracking:list',
-      }],
-    }]
-
-    const filtered = filterAdminNavigation(nodes, new Set(['tracking:list']))
-
-    expect(filtered).toHaveLength(1)
-    expect(filtered[0].children?.[0].path).toBe('/tracking')
-  })
-
-  it('selects the first fallback leaf in strict depth-first configuration order', () => {
-    const nodes: AdminNavigationNode[] = [{
-      key: 'level-one',
-      title: '一级目录',
-      icon: adminNavigation[0].icon,
-      children: [{
-        key: 'level-two',
-        title: '二级目录',
-        icon: adminNavigation[0].icon,
-        children: [{
-          key: 'tracking',
-          title: '轨迹管理',
-          icon: adminNavigation[0].icon,
-          path: '/tracking',
-          permission: 'tracking:list',
-        }],
-      }, {
-        key: 'reports',
-        title: '报表管理',
-        icon: adminNavigation[0].icon,
-        path: '/reports',
-        permission: 'reports:list',
-      }],
-    }]
-
-    expect(getNavigationLeaves(nodes).map((item) => item.path)).toEqual(['/tracking', '/reports'])
-    expect(getFirstNavigationLeaf(nodes)?.path).toBe('/tracking')
-  })
-})
diff --git a/src/navigation/adminNavigation.ts b/src/navigation/adminNavigation.ts
deleted file mode 100644
index dd1f2daf..00000000
--- a/src/navigation/adminNavigation.ts
+++ /dev/null
@@ -1,89 +0,0 @@
-import type { Component } from 'vue'
-import {
-  BriefcaseBusiness,
-  Building2,
-  ContactRound,
-  ClipboardList,
-  Database,
-  FileCheck2,
-  KeyRound,
-  Settings,
-  ShieldCheck,
-  Truck,
-  Users,
-  Warehouse as WarehouseIcon,
-} from '@lucide/vue'
-
-export interface AdminNavigationNode {
-  key: string
-  title: string
-  icon: Component
-  path?: string
-  permission?: string
-  children?: AdminNavigationNode[]
-}
-
-export interface AdminNavigationLeaf extends AdminNavigationNode {
-  path: string
-  permission: string
-  children?: never
-}
-
-export const adminNavigation: AdminNavigationNode[] = [
-  {
-    key: 'business',
-    title: '业务管理',
-    icon: BriefcaseBusiness,
-    children: [
-      { key: 'customers', title: '客户管理', icon: Building2, path: '/customers', permission: 'platform:customer:list' },
-      { key: 'enterprise-reviews', title: '企业审核', icon: FileCheck2, path: '/customers/reviews', permission: 'platform:customer:review' },
-      { key: 'warehouses', title: '仓库管理', icon: WarehouseIcon, path: '/warehouses', permission: 'platform:warehouse:list' },
-      { key: 'first-leg-orders', title: '头程订单', icon: ClipboardList, path: '/orders/first-leg', permission: 'platform:order:list' },
-    ],
-  },
-  {
-    key: 'master-data',
-    title: '基础资料',
-    icon: Database,
-    children: [
-      { key: 'express-companies', title: '快递公司', icon: Truck, path: '/master-data/express-companies', permission: 'platform:express:list' },
-      { key: 'counterparties', title: '往来单位', icon: ContactRound, path: '/master-data/counterparties', permission: 'platform:counterparty:list' },
-    ],
-  },
-  {
-    key: 'system',
-    title: '系统管理',
-    icon: Settings,
-    children: [
-      { key: 'internal-users', title: '内部用户', icon: Users, path: '/system/users', permission: 'platform:user:list' },
-      { key: 'roles', title: '角色管理', icon: ShieldCheck, path: '/system/roles', permission: 'platform:role:list' },
-      { key: 'permissions', title: '菜单权限', icon: KeyRound, path: '/system/permissions', permission: 'platform:permission:list' },
-    ],
-  },
-]
-
-export function getNavigationLeaves(nodes: AdminNavigationNode[]): AdminNavigationLeaf[] {
-  return nodes.flatMap((node) => {
-    if (node.children?.length) return getNavigationLeaves(node.children)
-    if (!node.path || !node.permission) return []
-    return [node as AdminNavigationLeaf]
-  })
-}
-
-export function filterAdminNavigation(
-  nodes: AdminNavigationNode[],
-  permissionCodes: ReadonlySet<string>,
-): AdminNavigationNode[] {
-  return nodes.flatMap((node) => {
-    if (node.children?.length) {
-      const children = filterAdminNavigation(node.children, permissionCodes)
-      return children.length ? [{ ...node, children }] : []
-    }
-    if (!node.path || !node.permission || !permissionCodes.has(node.permission)) return []
-    return [{ ...node }]
-  })
-}
-
-export function getFirstNavigationLeaf(nodes: AdminNavigationNode[]): AdminNavigationLeaf | null {
-  return getNavigationLeaves(nodes)[0] ?? null
-}
diff --git a/src/prototype/components/PrototypeModuleView.vue b/src/prototype/components/PrototypeModuleView.vue
new file mode 100644
index 00000000..9c1e3f0d
--- /dev/null
+++ b/src/prototype/components/PrototypeModuleView.vue
@@ -0,0 +1,30 @@
+<script setup lang="ts">
+defineProps<{
+  title: string
+  description: string
+}>()
+</script>
+
+<template>
+  <div class="business-page prototype-module-page">
+    <section class="surface-panel prototype-module-panel">
+      <div>
+        <h2>{{ title }}</h2>
+        <p>{{ description }}</p>
+      </div>
+      <div class="prototype-module-empty" role="status">
+        <strong>暂无业务数据</strong>
+        <span>页面基础已就绪，后续按对应业务契约接入。</span>
+      </div>
+    </section>
+  </div>
+</template>
+
+<style scoped>
+.prototype-module-panel { display: grid; min-height: 260px; align-content: start; gap: 28px; padding: 24px; }
+.prototype-module-panel h2 { margin: 0; color: var(--cc-text); font-size: 18px; line-height: 1.4; }
+.prototype-module-panel p { margin: 8px 0 0; color: var(--cc-muted); font-size: 13px; line-height: 1.65; }
+.prototype-module-empty { display: grid; min-height: 120px; place-items: center; align-content: center; gap: 6px; border: 1px dashed var(--cc-border); color: var(--cc-muted); text-align: center; }
+.prototype-module-empty strong { color: var(--cc-text); font-size: 14px; }
+.prototype-module-empty span { font-size: 13px; }
+</style>
diff --git a/src/prototype/modules/container-management/ModuleView.vue b/src/prototype/modules/container-management/ModuleView.vue
new file mode 100644
index 00000000..4ac0c610
--- /dev/null
+++ b/src/prototype/modules/container-management/ModuleView.vue
@@ -0,0 +1,5 @@
+<script setup lang="ts">
+import PrototypeModuleView from '@/prototype/components/PrototypeModuleView.vue'
+defineProps<{ title: string; description: string }>()
+</script>
+<template><PrototypeModuleView v-bind="$props" /></template>
diff --git a/src/prototype/modules/customer-management/ModuleView.vue b/src/prototype/modules/customer-management/ModuleView.vue
new file mode 100644
index 00000000..4ac0c610
--- /dev/null
+++ b/src/prototype/modules/customer-management/ModuleView.vue
@@ -0,0 +1,5 @@
+<script setup lang="ts">
+import PrototypeModuleView from '@/prototype/components/PrototypeModuleView.vue'
+defineProps<{ title: string; description: string }>()
+</script>
+<template><PrototypeModuleView v-bind="$props" /></template>
diff --git a/src/prototype/modules/dashboard/ModuleView.vue b/src/prototype/modules/dashboard/ModuleView.vue
new file mode 100644
index 00000000..4ac0c610
--- /dev/null
+++ b/src/prototype/modules/dashboard/ModuleView.vue
@@ -0,0 +1,5 @@
+<script setup lang="ts">
+import PrototypeModuleView from '@/prototype/components/PrototypeModuleView.vue'
+defineProps<{ title: string; description: string }>()
+</script>
+<template><PrototypeModuleView v-bind="$props" /></template>
diff --git a/src/prototype/modules/domestic-warehouse/ModuleView.vue b/src/prototype/modules/domestic-warehouse/ModuleView.vue
new file mode 100644
index 00000000..4ac0c610
--- /dev/null
+++ b/src/prototype/modules/domestic-warehouse/ModuleView.vue
@@ -0,0 +1,5 @@
+<script setup lang="ts">
+import PrototypeModuleView from '@/prototype/components/PrototypeModuleView.vue'
+defineProps<{ title: string; description: string }>()
+</script>
+<template><PrototypeModuleView v-bind="$props" /></template>
diff --git a/src/prototype/modules/fba-returns/ModuleView.vue b/src/prototype/modules/fba-returns/ModuleView.vue
new file mode 100644
index 00000000..4ac0c610
--- /dev/null
+++ b/src/prototype/modules/fba-returns/ModuleView.vue
@@ -0,0 +1,5 @@
+<script setup lang="ts">
+import PrototypeModuleView from '@/prototype/components/PrototypeModuleView.vue'
+defineProps<{ title: string; description: string }>()
+</script>
+<template><PrototypeModuleView v-bind="$props" /></template>
diff --git a/src/prototype/modules/finance/ModuleView.vue b/src/prototype/modules/finance/ModuleView.vue
new file mode 100644
index 00000000..4ac0c610
--- /dev/null
+++ b/src/prototype/modules/finance/ModuleView.vue
@@ -0,0 +1,5 @@
+<script setup lang="ts">
+import PrototypeModuleView from '@/prototype/components/PrototypeModuleView.vue'
+defineProps<{ title: string; description: string }>()
+</script>
+<template><PrototypeModuleView v-bind="$props" /></template>
diff --git a/src/prototype/modules/general/ModuleView.vue b/src/prototype/modules/general/ModuleView.vue
new file mode 100644
index 00000000..4ac0c610
--- /dev/null
+++ b/src/prototype/modules/general/ModuleView.vue
@@ -0,0 +1,5 @@
+<script setup lang="ts">
+import PrototypeModuleView from '@/prototype/components/PrototypeModuleView.vue'
+defineProps<{ title: string; description: string }>()
+</script>
+<template><PrototypeModuleView v-bind="$props" /></template>
diff --git a/src/prototype/modules/messages/ModuleView.vue b/src/prototype/modules/messages/ModuleView.vue
new file mode 100644
index 00000000..4ac0c610
--- /dev/null
+++ b/src/prototype/modules/messages/ModuleView.vue
@@ -0,0 +1,5 @@
+<script setup lang="ts">
+import PrototypeModuleView from '@/prototype/components/PrototypeModuleView.vue'
+defineProps<{ title: string; description: string }>()
+</script>
+<template><PrototypeModuleView v-bind="$props" /></template>
diff --git a/src/prototype/modules/overseas-business/ModuleView.vue b/src/prototype/modules/overseas-business/ModuleView.vue
new file mode 100644
index 00000000..4ac0c610
--- /dev/null
+++ b/src/prototype/modules/overseas-business/ModuleView.vue
@@ -0,0 +1,5 @@
+<script setup lang="ts">
+import PrototypeModuleView from '@/prototype/components/PrototypeModuleView.vue'
+defineProps<{ title: string; description: string }>()
+</script>
+<template><PrototypeModuleView v-bind="$props" /></template>
diff --git a/src/prototype/modules/overseas-delivery/AcceptanceWorkbench.vue b/src/prototype/modules/overseas-delivery/AcceptanceWorkbench.vue
new file mode 100644
index 00000000..a4da69f2
--- /dev/null
+++ b/src/prototype/modules/overseas-delivery/AcceptanceWorkbench.vue
@@ -0,0 +1,119 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { ClipboardCheck, PackageCheck, Truck, Warehouse, Zap } from '@lucide/vue'
+import { ElMessage } from 'element-plus'
+
+type BizType = '一件代发' | '海外目的仓' | 'FBA仓' | '换标下单' | '仓储转运' | '退货换标'
+type FlowStatus = '待推送' | '待分配' | '待入库' | '入库完成' | '待排车' | '已排车' | '待出库' | '已出库'
+interface Order {
+  id: number
+  no: string
+  type: BizType
+  container: string
+  sku: string
+  cartons: number
+  qty: number
+  status: FlowStatus
+  inbound: string
+  outbound: string
+  delivery: string
+}
+
+const typeOptions: BizType[] = ['一件代发', '海外目的仓', 'FBA仓', '换标下单', '仓储转运', '退货换标']
+const statuses: FlowStatus[] = ['待推送', '待分配', '待入库', '入库完成', '待排车', '已排车', '待出库', '已出库']
+type TagType = 'success' | 'warning' | 'primary' | 'info' | 'danger' | ''
+const typeColor: Record<BizType, TagType> = { '一件代发': 'warning', '海外目的仓': 'success', 'FBA仓': 'primary', '换标下单': 'info', '仓储转运': '', '退货换标': 'danger' }
+const statusColor: Record<FlowStatus, TagType> = { '待推送': 'info', '待分配': 'warning', '待入库': 'warning', '入库完成': 'success', '待排车': 'warning', '已排车': 'primary', '待出库': 'warning', '已出库': 'success' }
+const orders = ref<Order[]>(Array.from({ length: 18 }, (_, i) => {
+  const type = typeOptions[i % typeOptions.length]
+  const status = statuses[Math.min(7, Math.floor(i / 3) + 1)]
+  return { id: i + 1, no: `LL20260827${String(i + 1).padStart(4, '0')}`, type, container: `MSCU${String(9023100 + i)}`, sku: `SKU-${type === 'FBA仓' ? 'FBA' : 'OW'}-${String(i + 11).padStart(3, '0')}`, cartons: 8 + (i % 7), qty: 96 + i * 12, status, inbound: `RK202608${String(i + 1).padStart(4, '0')}`, outbound: i > 8 ? `CK202608${String(i + 1).padStart(4, '0')}` : '-', delivery: i > 11 ? `PS202608${String(i + 1).padStart(4, '0')}` : '-' }
+}))
+
+const activeType = ref<'全部' | BizType>('全部')
+const pushTypes = ref<BizType[]>([...typeOptions])
+const keyword = ref('')
+const selected = ref<Order[]>([])
+const dialog = ref<'push' | 'inbound' | 'dispatch' | 'outbound' | 'other' | 'inventory' | null>(null)
+const pdaMode = ref<'入库' | '出库'>('入库')
+const generatedCount = ref(6)
+const truckCount = ref(3)
+const inventoryChecked = ref(false)
+
+const filteredOrders = computed(() => orders.value.filter((item) => (activeType.value === '全部' || item.type === activeType.value) && (!keyword.value || `${item.no}${item.sku}${item.container}`.includes(keyword.value))))
+const metrics = computed(() => ({ total: orders.value.length, waiting: orders.value.filter((o) => ['待分配', '待入库', '待排车', '待出库'].includes(o.status)).length, inbound: orders.value.filter((o) => o.status === '入库完成').length, outbound: orders.value.filter((o) => o.status === '已出库').length }))
+
+function toggle(item: Order) { selected.value = selected.value.some((row) => row.id === item.id) ? selected.value.filter((row) => row.id !== item.id) : [...selected.value, item] }
+function selectAll() { selected.value = selected.value.length === filteredOrders.value.length ? [] : [...filteredOrders.value] }
+function open(flow: typeof dialog.value) { dialog.value = flow }
+function pushOrders() {
+  const target = selected.value.length ? selected.value : orders.value.filter((o) => o.status === '待推送').slice(0, generatedCount.value)
+  target.forEach((o) => { o.status = '待分配' })
+  selected.value = []; dialog.value = null; ElMessage.success(`已推送 ${target.length} 条尾程订单，状态变更为“待分配”`)
+}
+function receiveInbound() {
+  const target = selected.value.length ? selected.value : orders.value.filter((o) => o.status === '待入库')
+  target.forEach((o) => { o.status = '入库完成' })
+  selected.value = []; dialog.value = null; ElMessage.success(`PDA 已完成 ${target.length} 条入库单扫码、上架`)
+}
+function smartDispatch() {
+  const target = selected.value.length ? selected.value : orders.value.filter((o) => o.status === '入库完成').slice(0, truckCount.value * 2)
+  target.forEach((o) => { o.status = '已排车'; o.delivery = `PS202608${String(o.id).padStart(4, '0')}` })
+  selected.value = []; dialog.value = null; ElMessage.success(`智能排车完成，生成 ${Math.max(1, Math.ceil(target.length / 2))} 张派送单`)
+}
+function outboundPick() {
+  const target = selected.value.length ? selected.value : orders.value.filter((o) => o.status === '已排车')
+  target.forEach((o) => { o.status = '已出库'; o.outbound = `CK202608${String(o.id).padStart(4, '0')}` })
+  selected.value = []; dialog.value = null; ElMessage.success(`PDA 已拣货出库 ${target.length} 条，库存已扣减`)
+}
+function completeOther() { dialog.value = null; ElMessage.success('海外换标、转仓、退货换标单据已批量生成并进入对应作业队列') }
+function checkInventory() { inventoryChecked.value = true; dialog.value = null; ElMessage.success('库存验收通过：可用库存、占用库存与出库流水一致') }
+</script>
+
+<template>
+  <div class="business-page acceptance-page">
+    <section class="workbench-head surface-panel">
+      <div><div class="eyebrow">四期海外仓 · 验收模式</div><h2>尾程业务全流程验收工作台</h2><p>按装柜完成 → 推送 → 入库 → 排车 → 出库 → 库存核对逐步验收，所有单据均为中文枚举。</p></div>
+      <el-tag type="success" effect="dark">验收数据 · {{ orders.length }} 单</el-tag>
+    </section>
+    <section class="metric-grid">
+      <div class="metric surface-panel"><span>尾程订单</span><strong>{{ metrics.total }}</strong><small>覆盖 6 种业务类型</small></div>
+      <div class="metric surface-panel"><span>待处理节点</span><strong>{{ metrics.waiting }}</strong><small>待分配 / 入库 / 排车 / 出库</small></div>
+      <div class="metric surface-panel"><span>已入库</span><strong>{{ metrics.inbound }}</strong><small>含 PDA 扫码上架</small></div>
+      <div class="metric surface-panel"><span>已出库</span><strong>{{ metrics.outbound }}</strong><small>库存已扣减</small></div>
+    </section>
+    <section class="flow surface-panel">
+      <div class="flow-title"><div><h3>验收操作</h3><span>每个按钮打开独立对话框，可同时核对不同节点</span></div><el-button type="primary" plain @click="open('inventory')"><ClipboardCheck :size="16" />最终库存验收</el-button></div>
+      <div class="flow-actions">
+        <el-button @click="open('push')"><Zap :size="16" />1. 装柜完成 / 推送尾程</el-button>
+        <el-button @click="open('inbound')"><PackageCheck :size="16" />2. PDA 拣货入库</el-button>
+        <el-button @click="open('dispatch')"><Truck :size="16" />3. 智能排车</el-button>
+        <el-button @click="open('outbound')"><Warehouse :size="16" />4. PDA 拣货出库</el-button>
+        <el-button @click="open('other')">5. 其他海外业务单据</el-button>
+      </div>
+    </section>
+    <section class="surface-panel order-panel">
+      <div class="list-head"><div><h3>验收单据明细</h3><span>已选 {{ selected.length }} 条，可对选中单据执行节点操作</span></div><el-input v-model="keyword" clearable placeholder="搜索尾程单号 / SKU / 柜号" style="width: 270px" /></div>
+      <div class="type-tabs"><button :class="{active: activeType === '全部'}" @click="activeType = '全部'">全部</button><button v-for="type in typeOptions" :key="type" :class="{active: activeType === type}" @click="activeType = type">{{ type }}</button></div>
+      <div class="table-wrap"><table><thead><tr><th><input type="checkbox" :checked="selected.length === filteredOrders.length && filteredOrders.length > 0" @change="selectAll" /></th><th>尾程单号</th><th>业务类型</th><th>集装箱号</th><th>SKU</th><th>箱数</th><th>数量</th><th>入库单号</th><th>出库单号</th><th>派送单号</th><th>当前状态</th></tr></thead><tbody><tr v-for="item in filteredOrders" :key="item.id"><td><input type="checkbox" :checked="selected.some((row) => row.id === item.id)" @change="toggle(item)" /></td><td class="mono">{{ item.no }}</td><td><el-tag :type="typeColor[item.type] as any" effect="plain">{{ item.type }}</el-tag></td><td class="mono">{{ item.container }}</td><td class="mono">{{ item.sku }}</td><td>{{ item.cartons }}</td><td>{{ item.qty }}</td><td class="mono">{{ item.inbound }}</td><td class="mono">{{ item.outbound }}</td><td class="mono">{{ item.delivery }}</td><td><el-tag :type="statusColor[item.status] as any" effect="light">{{ item.status }}</el-tag></td></tr></tbody></table></div>
+    </section>
+
+    <el-dialog :model-value="Boolean(dialog)" @update:model-value="dialog = $event ? dialog : null" title="装柜完成 / 推送尾程订单" width="560px" destroy-on-close v-if="dialog === 'push'"><p class="dialog-tip">头程柜号 <b>MSCU9023100</b> 已装柜完成，按业务类型批量生成尾程订单并推送到“待分配”。</p><el-form label-position="top"><el-form-item label="生成数量"><el-input-number v-model="generatedCount" :min="1" :max="18" /></el-form-item><el-form-item label="业务类型"><el-checkbox-group v-model="pushTypes"><el-checkbox v-for="type in typeOptions" :key="type" :label="type">{{ type }}</el-checkbox></el-checkbox-group></el-form-item></el-form><template #footer><el-button @click="dialog = null">取消</el-button><el-button type="primary" @click="pushOrders">确认推送</el-button></template></el-dialog>
+    <el-dialog :model-value="Boolean(dialog)" @update:model-value="dialog = $event ? dialog : null" title="PDA 拣货入库" width="560px" destroy-on-close v-if="dialog === 'inbound'"><p class="dialog-tip">扫描柜号、箱码后完成收货、分配库位和上架。当前待入库 {{ orders.filter((o) => o.status === '待入库').length }} 条。</p><el-alert title="已启用 PDA 幂等校验与海外实际仓绑定" type="info" :closable="false" /><template #footer><el-button @click="dialog = null">取消</el-button><el-button type="primary" @click="receiveInbound">完成 PDA 入库</el-button></template></el-dialog>
+    <el-dialog :model-value="Boolean(dialog)" @update:model-value="dialog = $event ? dialog : null" title="智能排车 / 生成派送单" width="560px" destroy-on-close v-if="dialog === 'dispatch'"><p class="dialog-tip">系统按目的仓、预约时间和托盘体积随机预排，确认后生成派送单与出库单。</p><el-form label-position="top"><el-form-item label="车辆数"><el-input-number v-model="truckCount" :min="1" :max="10" /></el-form-item><el-form-item label="排车策略"><el-radio-group model-value="随机预排"><el-radio value="随机预排">随机预排</el-radio><el-radio value="按目的仓合并">按目的仓合并</el-radio></el-radio-group></el-form-item></el-form><template #footer><el-button @click="dialog = null">取消</el-button><el-button type="primary" @click="smartDispatch">确认生成派送单</el-button></template></el-dialog>
+    <el-dialog :model-value="Boolean(dialog)" @update:model-value="dialog = $event ? dialog : null" title="PDA 拣货出库" width="560px" destroy-on-close v-if="dialog === 'outbound'"><p class="dialog-tip">根据推送的出库清单逐箱扫码拣货，完成复核后扣减可用库存并关闭出库单。</p><el-steps :active="2" finish-status="success" simple><el-step title="领取清单" /><el-step title="逐箱拣货" /><el-step title="复核出库" /></el-steps><template #footer><el-button @click="dialog = null">取消</el-button><el-button type="primary" @click="outboundPick">完成 PDA 出库</el-button></template></el-dialog>
+    <el-dialog :model-value="Boolean(dialog)" @update:model-value="dialog = $event ? dialog : null" title="其他海外业务单据" width="620px" destroy-on-close v-if="dialog === 'other'"><p class="dialog-tip">一次性生成并核对其他海外本土业务单据，单据状态使用中文枚举。</p><el-table :data="[{type:'换标下单', count:4, status:'待作业'}, {type:'仓储转运', count:3, status:'待分配'}, {type:'退货换标', count:2, status:'待收货'}, {type:'本土散板', count:3, status:'待排车'}]" size="small"><el-table-column prop="type" label="业务类型" /><el-table-column prop="count" label="单据数" /><el-table-column prop="status" label="当前状态" /></el-table><template #footer><el-button @click="dialog = null">取消</el-button><el-button type="primary" @click="completeOther">生成并进入作业队列</el-button></template></el-dialog>
+    <el-dialog :model-value="Boolean(dialog)" @update:model-value="dialog = $event ? dialog : null" title="最终库存验收" width="620px" destroy-on-close v-if="dialog === 'inventory'"><div class="inventory-check"><div><span>账面可用库存</span><b>{{ orders.reduce((sum, item) => sum + item.qty, 0) }}</b></div><div><span>出库扣减</span><b>{{ orders.filter((o) => o.status === '已出库').reduce((sum, item) => sum + item.qty, 0) }}</b></div><div><span>库存流水</span><b>一致</b></div></div><el-alert title="核对范围：入库上架、锁定库存、PDA 出库、派送单关联、异常单据" type="success" :closable="false" /><template #footer><el-button @click="dialog = null">关闭</el-button><el-button type="primary" @click="checkInventory">确认验收通过</el-button></template></el-dialog>
+  </div>
+</template>
+
+<style scoped>
+.acceptance-page { display: grid; gap: 16px; }
+.surface-panel { background: var(--cc-surface); border: 1px solid var(--cc-border); border-radius: var(--cc-radius-md); box-shadow: var(--cc-shadow-sm); }
+.workbench-head { display:flex; justify-content:space-between; align-items:flex-start; padding:22px 24px; }.eyebrow { color:var(--cc-primary); font-size:12px; font-weight:700; letter-spacing:1px; }.workbench-head h2 { margin:6px 0; font-size:22px; color:var(--cc-text); }.workbench-head p,.flow-title span,.list-head span { margin:0; color:var(--cc-muted); font-size:13px; }
+.metric-grid { display:grid; grid-template-columns:repeat(4,1fr); gap:12px; }.metric { padding:16px 18px; }.metric span,.metric small { display:block; color:var(--cc-muted); font-size:12px; }.metric strong { display:block; margin:4px 0; color:var(--cc-text); font-size:26px; }
+.flow,.order-panel { padding:18px 20px; }.flow-title,.list-head { display:flex; justify-content:space-between; align-items:center; gap:16px; }.flow h3,.order-panel h3 { margin:0 0 4px; font-size:15px; }.flow-actions { display:flex; flex-wrap:wrap; gap:10px; margin-top:16px; }.flow-actions .el-button { min-height:40px; }
+.type-tabs { display:flex; gap:4px; margin:16px 0 12px; border-bottom:1px solid var(--cc-border); }.type-tabs button { padding:9px 14px; border:0; background:transparent; color:var(--cc-muted); cursor:pointer; }.type-tabs button.active { color:var(--cc-primary); border-bottom:2px solid var(--cc-primary); font-weight:700; }
+.table-wrap { overflow:auto; } table { width:100%; border-collapse:collapse; font-size:12px; white-space:nowrap; } th,td { padding:10px 9px; border-bottom:1px solid var(--cc-border); text-align:left; } th { background:var(--cc-surface-muted); color:var(--cc-muted); font-weight:600; } .mono { font-family:ui-monospace, SFMono-Regular, Consolas, monospace; color:var(--cc-text-secondary); }.dialog-tip { padding:12px 14px; margin:0 0 16px; background:var(--cc-surface-muted); color:var(--cc-text-secondary); line-height:1.6; }.inventory-check { display:grid; grid-template-columns:repeat(3,1fr); gap:10px; margin-bottom:16px; }.inventory-check div { padding:14px; background:var(--cc-surface-muted); }.inventory-check span,.inventory-check b { display:block; }.inventory-check span { color:var(--cc-muted); font-size:12px; }.inventory-check b { margin-top:6px; color:var(--cc-text); font-size:20px; }
+</style>
+
diff --git a/src/prototype/modules/overseas-delivery/ModuleView.vue b/src/prototype/modules/overseas-delivery/ModuleView.vue
new file mode 100644
index 00000000..4ac0c610
--- /dev/null
+++ b/src/prototype/modules/overseas-delivery/ModuleView.vue
@@ -0,0 +1,5 @@
+<script setup lang="ts">
+import PrototypeModuleView from '@/prototype/components/PrototypeModuleView.vue'
+defineProps<{ title: string; description: string }>()
+</script>
+<template><PrototypeModuleView v-bind="$props" /></template>
diff --git a/src/prototype/modules/overseas-inventory/ModuleView.vue b/src/prototype/modules/overseas-inventory/ModuleView.vue
new file mode 100644
index 00000000..4ac0c610
--- /dev/null
+++ b/src/prototype/modules/overseas-inventory/ModuleView.vue
@@ -0,0 +1,5 @@
+<script setup lang="ts">
+import PrototypeModuleView from '@/prototype/components/PrototypeModuleView.vue'
+defineProps<{ title: string; description: string }>()
+</script>
+<template><PrototypeModuleView v-bind="$props" /></template>
diff --git a/src/prototype/modules/overseas-warehouse-orders/ModuleView.vue b/src/prototype/modules/overseas-warehouse-orders/ModuleView.vue
new file mode 100644
index 00000000..4ac0c610
--- /dev/null
+++ b/src/prototype/modules/overseas-warehouse-orders/ModuleView.vue
@@ -0,0 +1,5 @@
+<script setup lang="ts">
+import PrototypeModuleView from '@/prototype/components/PrototypeModuleView.vue'
+defineProps<{ title: string; description: string }>()
+</script>
+<template><PrototypeModuleView v-bind="$props" /></template>
diff --git a/src/prototype/modules/reports/ModuleView.vue b/src/prototype/modules/reports/ModuleView.vue
new file mode 100644
index 00000000..4ac0c610
--- /dev/null
+++ b/src/prototype/modules/reports/ModuleView.vue
@@ -0,0 +1,5 @@
+<script setup lang="ts">
+import PrototypeModuleView from '@/prototype/components/PrototypeModuleView.vue'
+defineProps<{ title: string; description: string }>()
+</script>
+<template><PrototypeModuleView v-bind="$props" /></template>
diff --git a/src/prototype/modules/sales/ModuleView.vue b/src/prototype/modules/sales/ModuleView.vue
new file mode 100644
index 00000000..4ac0c610
--- /dev/null
+++ b/src/prototype/modules/sales/ModuleView.vue
@@ -0,0 +1,5 @@
+<script setup lang="ts">
+import PrototypeModuleView from '@/prototype/components/PrototypeModuleView.vue'
+defineProps<{ title: string; description: string }>()
+</script>
+<template><PrototypeModuleView v-bind="$props" /></template>
diff --git a/src/prototype/modules/service-center/ModuleView.vue b/src/prototype/modules/service-center/ModuleView.vue
new file mode 100644
index 00000000..4ac0c610
--- /dev/null
+++ b/src/prototype/modules/service-center/ModuleView.vue
@@ -0,0 +1,5 @@
+<script setup lang="ts">
+import PrototypeModuleView from '@/prototype/components/PrototypeModuleView.vue'
+defineProps<{ title: string; description: string }>()
+</script>
+<template><PrototypeModuleView v-bind="$props" /></template>
diff --git a/src/prototype/modules/supplier-center/ModuleView.vue b/src/prototype/modules/supplier-center/ModuleView.vue
new file mode 100644
index 00000000..4ac0c610
--- /dev/null
+++ b/src/prototype/modules/supplier-center/ModuleView.vue
@@ -0,0 +1,5 @@
+<script setup lang="ts">
+import PrototypeModuleView from '@/prototype/components/PrototypeModuleView.vue'
+defineProps<{ title: string; description: string }>()
+</script>
+<template><PrototypeModuleView v-bind="$props" /></template>
diff --git a/src/prototype/modules/system-management/ModuleView.vue b/src/prototype/modules/system-management/ModuleView.vue
new file mode 100644
index 00000000..4ac0c610
--- /dev/null
+++ b/src/prototype/modules/system-management/ModuleView.vue
@@ -0,0 +1,5 @@
+<script setup lang="ts">
+import PrototypeModuleView from '@/prototype/components/PrototypeModuleView.vue'
+defineProps<{ title: string; description: string }>()
+</script>
+<template><PrototypeModuleView v-bind="$props" /></template>
diff --git a/src/prototype/modules/vehicle-management/ModuleView.vue b/src/prototype/modules/vehicle-management/ModuleView.vue
new file mode 100644
index 00000000..4ac0c610
--- /dev/null
+++ b/src/prototype/modules/vehicle-management/ModuleView.vue
@@ -0,0 +1,5 @@
+<script setup lang="ts">
+import PrototypeModuleView from '@/prototype/components/PrototypeModuleView.vue'
+defineProps<{ title: string; description: string }>()
+</script>
+<template><PrototypeModuleView v-bind="$props" /></template>
diff --git a/src/prototype/routes.ts b/src/prototype/routes.ts
new file mode 100644
index 00000000..a12b9194
--- /dev/null
+++ b/src/prototype/routes.ts
@@ -0,0 +1,138 @@
+import type { RouteRecordRaw } from 'vue-router'
+import type { Component } from 'vue'
+
+type PrototypeRoute = readonly [path: string, name: string, title: string]
+type ModuleView = () => Promise<Component>
+
+const moduleViews = {
+  customerManagement: () => import('@/prototype/modules/customer-management/ModuleView.vue'),
+  domesticWarehouse: () => import('@/prototype/modules/domestic-warehouse/ModuleView.vue'),
+  overseasDelivery: () => import('@/prototype/modules/overseas-delivery/ModuleView.vue'),
+  overseasAcceptance: () => import('@/prototype/modules/overseas-delivery/AcceptanceWorkbench.vue'),
+  overseasInventory: () => import('@/prototype/modules/overseas-inventory/ModuleView.vue'),
+  serviceCenter: () => import('@/prototype/modules/service-center/ModuleView.vue'),
+  supplierCenter: () => import('@/prototype/modules/supplier-center/ModuleView.vue'),
+  containerManagement: () => import('@/prototype/modules/container-management/ModuleView.vue'),
+  overseasBusiness: () => import('@/prototype/modules/overseas-business/ModuleView.vue'),
+  overseasWarehouseOrders: () => import('@/prototype/modules/overseas-warehouse-orders/ModuleView.vue'),
+  fbaReturns: () => import('@/prototype/modules/fba-returns/ModuleView.vue'),
+  finance: () => import('@/prototype/modules/finance/ModuleView.vue'),
+  vehicleManagement: () => import('@/prototype/modules/vehicle-management/ModuleView.vue'),
+  reports: () => import('@/prototype/modules/reports/ModuleView.vue'),
+  general: () => import('@/prototype/modules/general/ModuleView.vue'),
+  sales: () => import('@/prototype/modules/sales/ModuleView.vue'),
+  messages: () => import('@/prototype/modules/messages/ModuleView.vue'),
+  systemManagement: () => import('@/prototype/modules/system-management/ModuleView.vue'),
+} satisfies Record<string, ModuleView>
+
+function createRoutes(view: ModuleView, routes: PrototypeRoute[]): RouteRecordRaw[] {
+  return routes.map(([path, name, title]) => ({
+    path,
+    name,
+    component: view,
+    props: { title, description: `用于承载${title}相关业务信息` },
+    meta: { title, description: `用于承载${title}相关业务信息` },
+  }))
+}
+
+export const prototypeModuleRoutes: RouteRecordRaw[] = [
+  {
+    path: 'prototype/overseas-delivery/acceptance-workbench',
+    name: 'overseas-acceptance-workbench',
+    component: moduleViews.overseasAcceptance,
+    props: { title: '尾程业务全流程验收', description: '覆盖尾程订单、海外入库、排车、出库与库存验收' },
+    meta: { title: '尾程业务全流程验收', description: '覆盖尾程订单、海外入库、排车、出库与库存验收' },
+  },
+  ...createRoutes(moduleViews.customerManagement, [
+    ['prototype/customer-management/warehouse-tier-fee', 'warehouse-tier-fee', '海外仓阶梯费用'],
+  ]),
+  ...createRoutes(moduleViews.domesticWarehouse, [
+    ['prototype/domestic-warehouse/inbound-list', 'inbound-list', '入库单列表'],
+    ['prototype/domestic-warehouse/inbound-dedup', 'inbound-dedup', '入库单测量'],
+    ['prototype/domestic-warehouse/inbound-measure', 'inbound-measure', '测量数据审核'],
+    ['prototype/domestic-warehouse/inbound-receive', 'inbound-receive', '接收审核'],
+    ['prototype/domestic-warehouse/location-management', 'domestic-location-management', '库位管理'],
+    ['prototype/domestic-warehouse/pallet-management', 'domestic-pallet-management', '托盘管理'],
+  ]),
+  ...createRoutes(moduleViews.overseasDelivery, [
+    ['prototype/overseas-delivery/dispatch-list', 'outbound-dispatch', '派送单列表'],
+    ['prototype/overseas-delivery/vehicle-scheduling', 'outbound-vehicle', '排车列表'],
+    ['prototype/overseas-delivery/bol', 'outbound-bol', 'BOL'],
+    ['prototype/overseas-delivery/self-pickup', 'outbound-selfpick', '自提单'],
+  ]),
+  ...createRoutes(moduleViews.overseasInventory, [
+    ['prototype/overseas-inventory/stock-list', 'overseas-stock', '暂扣库存'],
+    ['prototype/overseas-inventory/inbound-orders', 'overseas-inbound', '海外入库单'],
+    ['prototype/overseas-inventory/outbound-orders', 'overseas-outbound', '出库单'],
+    ['prototype/overseas-inventory/relabel-orders', 'overseas-relabel', '换标订单'],
+  ]),
+  ...createRoutes(moduleViews.serviceCenter, [
+    ['prototype/service-center/booking-list', 'booking-list', '订舱列表'],
+    ['prototype/service-center/truck-list', 'truck-list', '拖车列表'],
+  ]),
+  ...createRoutes(moduleViews.supplierCenter, [
+    ['prototype/supplier-center/supplier-list', 'supplier-list', '供应商列表'],
+  ]),
+  ...createRoutes(moduleViews.containerManagement, [
+    ['prototype/container-management/container-list', 'container-list', '货柜列表'],
+    ['prototype/container-management/manifest', 'container-manifest', '装柜清单'],
+    ['prototype/container-management/preload-list', 'container-preload', '预装清单'],
+  ]),
+  ...createRoutes(moduleViews.overseasBusiness, [
+    ['prototype/overseas-business/users', 'overseas-users', '用户管理'],
+    ['prototype/overseas-business/purchase-orders', 'overseas-purchase', '采购订单'],
+    ['prototype/overseas-business/local-truck', 'overseas-truck', '本土卡车'],
+    ['prototype/overseas-business/local-looseboard', 'overseas-looseboard', '本土散板'],
+  ]),
+  ...createRoutes(moduleViews.overseasWarehouseOrders, [
+    ['prototype/overseas-warehouse-orders/return-inbound', 'overseas-order-inbound', '退货入库'],
+    ['prototype/overseas-warehouse-orders/return-relabel', 'overseas-order-relabel', '退货换标'],
+    ['prototype/overseas-warehouse-orders/return-outbound', 'overseas-order-outbound', '退货出库'],
+  ]),
+  ...createRoutes(moduleViews.fbaReturns, [
+    ['prototype/fba-returns/inbound-orders', 'fba-inbound-order', '入库单'],
+    ['prototype/fba-returns/relabel-orders', 'fba-relabel-order', '换标单'],
+    ['prototype/fba-returns/outbound-orders', 'fba-outbound-order', '出库单'],
+    ['prototype/fba-returns/pallet-management', 'fba-pallet', '托盘管理'],
+    ['prototype/fba-returns/carton-management', 'fba-carton', '箱号管理'],
+    ['prototype/fba-returns/product-catalog', 'fba-product', '产品库'],
+    ['prototype/fba-returns/return-stock', 'fba-return-stock', '退货库存'],
+  ]),
+  ...createRoutes(moduleViews.finance, [
+    ['prototype/finance/customer-arap', 'customer-arap', '客户应收应付'],
+    ['prototype/finance/customer-reconciliation', 'customer-recon-stmt', '客户对账单'],
+    ['prototype/finance/settlement-ar', 'settlement-ar', '结算单应收'],
+    ['prototype/finance/settlement-ap', 'settlement-ap', '结算单应付'],
+    ['prototype/finance/cost-analysis', 'finance-cost', '费用分析'],
+    ['prototype/finance/profit-report', 'profit', '利润表'],
+  ]),
+  ...createRoutes(moduleViews.vehicleManagement, [
+    ['prototype/vehicle-management/vehicle-list', 'vehicle-list', '车辆列表'],
+  ]),
+  ...createRoutes(moduleViews.reports, [
+    ['prototype/reports/overview', 'report-overview', '报表总览'],
+    ['prototype/reports/income-expense', 'report-income', '收支报表'],
+    ['prototype/reports/ar-aging', 'report-ar-aging', '应收账龄分析'],
+    ['prototype/reports/cost-composition', 'report-cost', '费用构成分析'],
+    ['prototype/reports/freight', 'report-freight', '运费报表'],
+    ['prototype/reports/business-statistics', 'report-business', '业务统计报表'],
+  ]),
+  ...createRoutes(moduleViews.general, [
+    ['prototype/general/product-information', 'general-product', '产品信息'],
+    ['prototype/general/fee-items', 'general-fee', '费用项目'],
+    ['prototype/general/pallet-management', 'general-pallet', '托盘管理'],
+    ['prototype/general/location-management', 'general-location', '库位/货架管理'],
+  ]),
+  ...createRoutes(moduleViews.sales, [
+    ['prototype/sales/visit-records', 'sales-visits', '拜访记录'],
+    ['prototype/sales/commission', 'sales-commission', '销售提成'],
+  ]),
+  ...createRoutes(moduleViews.messages, [
+    ['prototype/messages/management', 'message-management', '消息管理'],
+    ['prototype/messages/templates', 'message-template', '模板管理'],
+  ]),
+  ...createRoutes(moduleViews.systemManagement, [
+    ['prototype/system-management/tenant-management', 'tenant-management', '租户管理'],
+    ['prototype/system-management/brand-settings', 'brand-settings', '品牌设置'],
+  ]),
+]
diff --git a/src/router/index.test.ts b/src/router/index.test.ts
deleted file mode 100644
index 8b961028..00000000
--- a/src/router/index.test.ts
+++ /dev/null
@@ -1,50 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import router from './index'
-
-describe('admin router access metadata', () => {
-  it('uses the root route only as a permission-aware entry point', () => {
-    const home = router.getRoutes().find((route) => route.name === 'home')
-
-    expect(home?.path).toBe('/')
-    expect(home?.meta.permission).toBeUndefined()
-    expect(router.getRoutes().some((route) => route.name === 'dashboard')).toBe(false)
-  })
-
-  it('protects warehouse management with its stable list permission', () => {
-    const warehouseRoute = router.getRoutes().find((route) => route.name === 'warehouses')
-
-    expect(warehouseRoute?.path).toBe('/warehouses')
-    expect(warehouseRoute?.meta.permission).toBe('platform:warehouse:list')
-  })
-
-  it('protects express company records with a stable master-data permission', () => {
-    const route = router.getRoutes().find((item) => item.name === 'express-companies')
-
-    expect(route?.path).toBe('/master-data/express-companies')
-    expect(route?.meta.permission).toBe('platform:express:list')
-  })
-
-  it('protects counterparty records with a stable master-data permission', () => {
-    const route = router.getRoutes().find((item) => item.name === 'counterparties')
-    expect(route?.path).toBe('/master-data/counterparties')
-    expect(route?.meta.permission).toBe('platform:counterparty:list')
-  })
-
-  it('protects enterprise reviews with the backend review menu permission', () => {
-    const route = router.getRoutes().find((item) => item.name === 'enterprise-reviews')
-
-    expect(route?.path).toBe('/customers/reviews')
-    expect(route?.meta.permission).toBe('platform:customer:review')
-  })
-
-  it('keeps forbidden inside the authenticated layout without a business permission', () => {
-    const authenticatedLayout = router.options.routes.find((route) => route.path === '/')
-    const forbidden = authenticatedLayout?.children?.find((route) => route.name === 'forbidden')
-    const resolved = router.resolve('/403')
-
-    expect(authenticatedLayout?.meta?.requiresAuth).toBe(true)
-    expect(forbidden?.path).toBe('403')
-    expect(forbidden?.meta?.permission).toBeUndefined()
-    expect(resolved.matched.some((record) => record.meta.requiresAuth)).toBe(true)
-  })
-})
diff --git a/src/router/index.ts b/src/router/index.ts
deleted file mode 100644
index 517b84ba..00000000
--- a/src/router/index.ts
+++ /dev/null
@@ -1,125 +0,0 @@
-import { createRouter, createWebHistory } from 'vue-router'
-import AppLayout from '@/layouts/AppLayout.vue'
-import { decideRouteAccess } from '@/router/accessDecision'
-import { useAccessPreviewStore } from '@/stores/accessPreview'
-import { useAuthStore } from '@/stores/auth'
-
-const router = createRouter({
-  history: createWebHistory(),
-  routes: [
-    {
-      path: '/login',
-      name: 'login',
-      component: () => import('@/views/LoginView.vue'),
-      meta: { title: '登录' },
-    },
-    {
-      path: '/',
-      component: AppLayout,
-      meta: { requiresAuth: true },
-      children: [
-        {
-          path: '',
-          name: 'home',
-          component: () => import('@/views/ModuleView.vue'),
-          meta: { title: '进入管理后台', description: '正在进入当前角色可访问的业务页面' },
-        },
-        {
-          path: 'customers',
-          name: 'customers',
-          component: () => import('@/views/CustomersView.vue'),
-          meta: { title: '客户管理', description: '维护客户企业资料、合作状态和注册审核', permission: 'platform:customer:list' },
-        },
-        {
-          path: 'customers/reviews',
-          name: 'enterprise-reviews',
-          component: () => import('@/views/EnterpriseReviewsView.vue'),
-          meta: { title: '企业审核', description: '核验企业资质并维护客户下单资格', permission: 'platform:customer:review' },
-        },
-        {
-          path: 'warehouses',
-          name: 'warehouses',
-          component: () => import('@/views/WarehousesView.vue'),
-          meta: { title: '仓库管理', description: '维护客户头程下单可选择的平台收货仓', permission: 'platform:warehouse:list' },
-        },
-        {
-          path: 'orders/first-leg',
-          name: 'first-leg-orders',
-          component: () => import('@/views/FirstLegOrdersView.vue'),
-          meta: { title: '头程订单', description: '创建、受理和跟进客户提交的头程运输订单', permission: 'platform:order:list' },
-        },
-        {
-          path: 'master-data/express-companies',
-          name: 'express-companies',
-          component: () => import('@/views/ExpressCompaniesView.vue'),
-          meta: { title: '快递公司', description: '查询平台可用的快递公司档案与公开联系信息', permission: 'platform:express:list' },
-        },
-        {
-          path: 'master-data/counterparties',
-          name: 'counterparties',
-          component: () => import('@/views/CounterpartiesView.vue'),
-          meta: { title: '往来单位', description: '维护供应商、客户、承运商、报关行及收发货单位档案', permission: 'platform:counterparty:list' },
-        },
-        {
-          path: 'system/users',
-          name: 'users',
-          component: () => import('@/views/InternalUsersView.vue'),
-          meta: { title: '内部用户', description: '管理平台内部员工账号、状态和角色', permission: 'platform:user:list' },
-        },
-        {
-          path: 'system/roles',
-          name: 'roles',
-          component: () => import('@/views/RolesView.vue'),
-          meta: { title: '角色管理', description: '维护平台角色并配置菜单及操作权限', permission: 'platform:role:list' },
-        },
-        {
-          path: 'system/permissions',
-          name: 'permissions',
-          component: () => import('@/views/PermissionsView.vue'),
-          meta: { title: '菜单权限', description: '维护菜单、页面、按钮和接口权限编码', permission: 'platform:permission:list' },
-        },
-        {
-          path: '403',
-          name: 'forbidden',
-          component: () => import('@/views/ForbiddenView.vue'),
-          meta: { title: '权限不足', description: '当前权限预览角色无法访问此页面' },
-        },
-      ],
-    },
-    { path: '/:pathMatch(.*)*', redirect: '/' },
-  ],
-})
-
-router.beforeEach((to) => {
-  document.title = to.meta.title ? `${to.meta.title} - 虫虫出海管理后台` : '虫虫出海管理后台'
-  const auth = useAuthStore()
-  if (to.name === 'login' && auth.isAuthenticated) {
-    return { name: 'home' }
-  }
-  if (!auth.isAuthenticated && !to.meta.requiresAuth) return true
-
-  const access = useAccessPreviewStore()
-  if (auth.isAuthenticated) access.initializeAfterLogin()
-  const decision = decideRouteAccess({
-    requiresAuth: to.meta.requiresAuth,
-    isAuthenticated: auth.isAuthenticated,
-    fullPath: to.fullPath,
-    permission: to.meta.permission,
-    hasPermission: to.meta.permission ? access.can(to.meta.permission) : true,
-  })
-
-  if (decision.type === 'login') {
-    return { name: 'login', query: { redirect: decision.redirect } }
-  }
-  if (decision.type === 'forbidden') {
-    return { name: 'forbidden', query: { from: decision.from }, replace: true }
-  }
-  if (to.name === 'home') {
-    return access.firstAccessiblePath
-      ? { path: access.firstAccessiblePath, replace: true }
-      : { name: 'forbidden', replace: true }
-  }
-  return true
-})
-
-export default router
diff --git a/src/shared/api/AGENTS.md b/src/shared/api/AGENTS.md
new file mode 100644
index 00000000..315b232b
--- /dev/null
+++ b/src/shared/api/AGENTS.md
@@ -0,0 +1,25 @@
+# Admin Shared API Instructions
+
+## 适用范围与入口
+
+- 本文件适用于 `src/shared/api/` 及其测试。业务模块只通过领域 `api/` 适配层调用这里的客户端，不在页面和组件直接创建 Axios 实例。
+- 国内 API 客户端为 `http.ts`；海外 API 客户端为 `overseasHttp.ts`。认证会话编排在 `../../core/auth/auth.ts`，不得在本目录复制登录状态。
+
+## 国内与海外请求
+
+- `http` 使用 `VITE_API_BASE_URL`，默认走国内代理；国内登录、刷新和退出仍由统一 Auth 处理。
+- `overseasHttp` 使用 `VITE_OVERSEAS_API_BASE_URL`，默认 `/overseas-api`；Vite 将该前缀改写为海外 Gateway 的 `/api`。代理上游由开发环境配置，不在源码或指引中记录真实地址。
+- 登录和刷新响应一次性返回国内 Token、`overseasAccessToken`、`overseasExpiresIn`；`core/auth/auth.ts` 必须原子替换两套访问凭据。不得恢复 Token 兑换端点或让业务模块单独刷新海外 Token。
+- 海外 Token 只由 `replaceOverseasAccessToken`、`clearOverseasAccessToken` 管理；业务模块不得读写缓存、LocalStorage 或手工拼装 `Authorization`。
+- 国内、海外 401 共用统一会话刷新编排。海外请求最多统一刷新一次并重放一次；刷新失败按会话失效处理，不循环重试或回退假数据。
+
+## 领域调用边界
+
+- 国内业务领域 API 使用 `http`；海外尾程、海外仓资源和海外本土业务使用 `overseasHttp`，不得经国内 Gateway 中转。
+- 页面只调用所属模块的 API 封装；模块 API 负责路径、DTO 和错误适配，不把 Axios 响应或区域选择泄漏到页面。
+- 跨区域 Token、Audience、JWKS 和服务通信公共契约读取 `../../../../../docs/跨区域认证与服务通信契约.md`。
+
+## 修改与验证
+
+- 修改客户端、拦截器、刷新、Token 生命周期或 Base URL 时，联查 `http.test.ts`、`overseasHttp.test.ts`、`core/auth/auth.test.ts`、Vite 代理、`.env.example` 和全部实际消费者。
+- 至少运行相关 API/Auth 测试和 `pnpm typecheck`；交付前按项目指引运行完整测试与构建。
diff --git a/src/shared/api/http.safe-integer.test.ts b/src/shared/api/http.safe-integer.test.ts
new file mode 100644
index 00000000..b820c4e8
--- /dev/null
+++ b/src/shared/api/http.safe-integer.test.ts
@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest'
+import { parseApiJsonResponse, parseJsonWithSafeIntegers } from '@chongchong/shared'
+
+describe('safe integer API parsing', () => {
+  it('preserves backend long IDs as strings', () => {
+    expect(parseJsonWithSafeIntegers('{"id":2082674456475418625,"page":1}')).toEqual({
+      id: '2082674456475418625',
+      page: 1,
+    })
+  })
+
+  it('leaves non-JSON responses untouched', () => {
+    expect(parseApiJsonResponse('plain text')).toBe('plain text')
+  })
+})
diff --git a/src/shared/api/http.test.ts b/src/shared/api/http.test.ts
new file mode 100644
index 00000000..15b361fb
--- /dev/null
+++ b/src/shared/api/http.test.ts
@@ -0,0 +1,212 @@
+import axios, { AxiosHeaders } from 'axios'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  ApiResponseError,
+  getApiErrorDetails,
+  http,
+  registerAuthRefreshHandler,
+  registerAuthSessionExpiredHandler,
+  unwrapApiResponse,
+} from './http'
+
+const originalAdapter = http.defaults.adapter
+
+afterEach(() => {
+  http.defaults.adapter = originalAdapter
+  registerAuthRefreshHandler(async () => { throw new Error('refresh handler is not configured') })
+  registerAuthSessionExpiredHandler(() => undefined)
+})
+
+describe('API error diagnostics', () => {
+  it('does not attach a stale access token to anonymous authentication requests', async () => {
+    localStorage.setItem('cc-admin-token', 'stale-large-token')
+    let authorization: unknown
+    http.defaults.adapter = async (config) => {
+      authorization = config.headers.Authorization
+      return {
+        status: 200,
+        statusText: 'OK',
+        headers: {},
+        config,
+        data: { code: '200', message: 'success', data: null },
+      }
+    }
+
+    await http.post('/auth/login', { loginId: 'operator', password: 'secret' })
+
+    expect(authorization).toBeUndefined()
+    localStorage.removeItem('cc-admin-token')
+  })
+
+  it('treats only body code 200 as success', () => {
+    expect(unwrapApiResponse({ code: '200', message: 'success', data: { id: '1' } }))
+      .toEqual({ id: '1' })
+    expect(() => unwrapApiResponse({ code: '0', message: 'legacy success code', data: null }))
+      .toThrow(ApiResponseError)
+  })
+
+  it('keeps business request and trace identifiers when unwrapping fails', () => {
+    expect(() => unwrapApiResponse({
+      code: 'A0403',
+      message: '无权限',
+      data: null,
+      requestId: 'request-1',
+      traceId: 'trace-1',
+    })).toThrow(ApiResponseError)
+
+    try {
+      unwrapApiResponse({ code: 'A0403', message: '无权限', data: null, requestId: 'request-1', traceId: 'trace-1' })
+    } catch (error) {
+      expect(getApiErrorDetails(error)).toEqual({
+        message: '当前账号无权访问该数据，请联系管理员确认权限',
+        code: 'A0403',
+        requestId: 'request-1',
+        traceId: 'trace-1',
+      })
+    }
+  })
+
+  it('translates notification recipient error codes into actionable Chinese messages', () => {
+    expect(getApiErrorDetails(new ApiResponseError('NOTIFICATION_RECIPIENT_FORBIDDEN', 'A0400')).message)
+      .toBe('角色编码不存在或当前账号无权使用该角色，请检查后重试')
+    expect(getApiErrorDetails(new ApiResponseError('NOTIFICATION_RECIPIENT_EMPTY', 'A0400')).message)
+      .toBe('该角色下暂无可接收消息的有效用户，请先为角色分配启用中的成员')
+  })
+
+  it('preserves a backend credential error for an explicit login request', () => {
+    const error = new ApiResponseError(
+      '用户名或密码错误',
+      'A0401',
+      undefined,
+      null,
+      'request-login',
+      'trace-login',
+    )
+
+    expect(getApiErrorDetails(error, '登录失败', { preserveAuthenticationMessage: true })).toEqual({
+      message: '用户名或密码错误',
+      code: 'A0401',
+      requestId: 'request-login',
+      traceId: 'trace-login',
+    })
+    expect(getApiErrorDetails(error).message).toBe('登录状态已失效，请重新登录')
+  })
+
+  it('extracts identifiers from an HTTP error envelope', () => {
+    const error = new axios.AxiosError('Request failed', 'ERR_BAD_RESPONSE', undefined, undefined, {
+      status: 503,
+      statusText: 'Service Unavailable',
+      headers: {},
+      config: { headers: new AxiosHeaders() },
+      data: { code: 'S0503', message: '服务不可用', requestId: 'request-2', traceId: 'trace-2' },
+    })
+
+    expect(getApiErrorDetails(error)).toEqual({
+      message: '服务暂时不可用，请稍后重试',
+      code: 'S0503',
+      requestId: 'request-2',
+      traceId: 'trace-2',
+    })
+  })
+
+  it('uses safe actionable messages for HTTP authentication and permission failures', () => {
+    const createError = (status: number, data: unknown) => new axios.AxiosError('Request failed', 'ERR_BAD_RESPONSE', undefined, undefined, {
+      status,
+      statusText: 'Request failed',
+      headers: {},
+      config: { headers: new AxiosHeaders() },
+      data,
+    })
+
+    expect(getApiErrorDetails(createError(401, { message: 'token parse stack' })).message)
+      .toBe('登录状态已失效，请重新登录')
+    expect(getApiErrorDetails(createError(403, { message: 'policy engine details' })).message)
+      .toBe('当前账号无权访问该数据，请联系管理员确认权限')
+    expect(getApiErrorDetails(createError(502, '<html>upstream failed</html>')).message)
+      .toBe('服务暂时不可用，请稍后重试')
+  })
+
+  it('explains a proxy 413 response without a JSON error envelope', () => {
+    const error = new axios.AxiosError('Request failed', 'ERR_BAD_REQUEST', undefined, undefined, {
+      status: 413,
+      statusText: 'Payload Too Large',
+      headers: {},
+      config: { headers: new AxiosHeaders() },
+      data: '<html>Request Entity Too Large</html>',
+    })
+
+    expect(getApiErrorDetails(error)).toEqual({
+      message: '上传文件的请求体过大，服务器已拒绝；请压缩后重试，如文件未超过 5MB，请联系管理员检查网关上传限制',
+      code: 'HTTP_413',
+      requestId: undefined,
+      traceId: undefined,
+    })
+  })
+
+  it('does not expose local exception text in user-facing diagnostics', () => {
+    expect(getApiErrorDetails(new Error('Error: socket failed\\n    at internal/request.ts:42'))).toEqual({
+      message: '接口请求失败', code: undefined, requestId: undefined, traceId: undefined,
+    })
+  })
+
+  it('notifies session expiry once when concurrent 401 requests share a failed refresh', async () => {
+    const refresh = vi.fn(async () => { throw new Error('refresh token expired') })
+    const expired = vi.fn()
+    registerAuthRefreshHandler(refresh)
+    registerAuthSessionExpiredHandler(expired)
+    http.defaults.adapter = async (config) => {
+      throw new axios.AxiosError('Unauthorized', 'ERR_BAD_REQUEST', config, undefined, {
+        status: 401,
+        statusText: 'Unauthorized',
+        headers: {},
+        config,
+        data: { code: 'A0401', message: '登录状态已过期' },
+      })
+    }
+
+    const results = await Promise.allSettled([
+      http.get('/platform/v1/orders'),
+      http.get('/platform/v1/warehouses'),
+    ])
+
+    expect(results.every((result) => result.status === 'rejected')).toBe(true)
+    expect(refresh).toHaveBeenCalledTimes(1)
+    expect(expired).toHaveBeenCalledTimes(1)
+  })
+
+  it('refreshes once and replays the original request with the rotated access token', async () => {
+    const refresh = vi.fn(async () => 'access-rotated')
+    const expired = vi.fn()
+    let orderRequests = 0
+    let replayAuthorization: unknown
+    registerAuthRefreshHandler(refresh)
+    registerAuthSessionExpiredHandler(expired)
+    http.defaults.adapter = async (config) => {
+      if (config.url === '/platform/v1/orders' && orderRequests++ === 0) {
+        throw new axios.AxiosError('Unauthorized', 'ERR_BAD_REQUEST', config, undefined, {
+          status: 401,
+          statusText: 'Unauthorized',
+          headers: {},
+          config,
+          data: { code: 'A0401', message: '登录状态已过期' },
+        })
+      }
+      replayAuthorization = config.headers.Authorization
+      return {
+        status: 200,
+        statusText: 'OK',
+        headers: {},
+        config,
+        data: { code: '200', message: 'success', data: [{ id: 'order-1' }] },
+      }
+    }
+
+    const response = await http.get('/platform/v1/orders')
+
+    expect(refresh).toHaveBeenCalledTimes(1)
+    expect(expired).not.toHaveBeenCalled()
+    expect(orderRequests).toBe(2)
+    expect(replayAuthorization).toBe('Bearer access-rotated')
+    expect(response).toEqual({ code: '200', message: 'success', data: [{ id: 'order-1' }] })
+  })
+})
diff --git a/src/shared/api/http.ts b/src/shared/api/http.ts
new file mode 100644
index 00000000..15e9d239
--- /dev/null
+++ b/src/shared/api/http.ts
@@ -0,0 +1,180 @@
+import axios, { type InternalAxiosRequestConfig } from 'axios'
+import { parseApiJsonResponse } from '@chongchong/shared'
+
+export interface ApiEnvelope<T> {
+  code: string
+  message: string
+  data: T
+  requestId?: string | null
+  traceId?: string | null
+  timestamp?: string
+}
+
+export class ApiResponseError extends Error {
+  readonly code: string
+  readonly status?: number
+  readonly details?: unknown
+  readonly requestId?: string
+  readonly traceId?: string
+
+  constructor(message: string, code: string, status?: number, details?: unknown, requestId?: string | null, traceId?: string | null) {
+    super(message)
+    this.name = 'ApiResponseError'
+    this.code = code
+    this.status = status
+    this.details = details
+    this.requestId = requestId || undefined
+    this.traceId = traceId || undefined
+  }
+}
+
+export interface ApiErrorDetails {
+  message: string
+  code?: string
+  requestId?: string
+  traceId?: string
+}
+
+export interface ApiErrorDetailsOptions {
+  preserveAuthenticationMessage?: boolean
+}
+
+export const http = axios.create({
+  baseURL: import.meta.env.VITE_API_BASE_URL || '/api',
+  timeout: 15_000,
+  transformResponse: [(data: unknown) => parseApiJsonResponse(data)],
+})
+
+type RetryableRequestConfig = InternalAxiosRequestConfig & { _authRetry?: boolean }
+type AuthRefreshHandler = () => Promise<string>
+type AuthSessionExpiredHandler = () => void | Promise<void>
+
+let authRefreshHandler: AuthRefreshHandler | null = null
+let authSessionExpiredHandler: AuthSessionExpiredHandler | null = null
+let activeRefresh: Promise<string> | null = null
+
+const businessErrorMessages: Record<string, string> = {
+  NOTIFICATION_RECIPIENT_FORBIDDEN: '角色编码不存在或当前账号无权使用该角色，请检查后重试',
+  NOTIFICATION_RECIPIENT_EMPTY: '该角色下暂无可接收消息的有效用户，请先为角色分配启用中的成员',
+}
+
+function friendlyBusinessMessage(message?: string | null) {
+  return (message && businessErrorMessages[message]) || message || undefined
+}
+
+export function registerAuthRefreshHandler(handler: AuthRefreshHandler) {
+  authRefreshHandler = handler
+}
+
+export function registerAuthSessionExpiredHandler(handler: AuthSessionExpiredHandler) {
+  authSessionExpiredHandler = handler
+}
+
+export async function refreshAuthenticatedSession(): Promise<string> {
+  if (!authRefreshHandler) throw new Error('认证刷新处理器尚未初始化')
+  if (!activeRefresh) {
+    activeRefresh = authRefreshHandler()
+      .catch(async (refreshError) => {
+        try {
+          await authSessionExpiredHandler?.()
+        } catch {
+          // 会话已清理，跳转失败不应覆盖原始认证错误。
+        }
+        throw refreshError
+      })
+      .finally(() => { activeRefresh = null })
+  }
+  return activeRefresh
+}
+
+http.interceptors.request.use((config) => {
+  const token = localStorage.getItem('cc-admin-token')
+  const isAnonymousAuthEndpoint = typeof config.url === 'string'
+    && ['/auth/login', '/auth/refresh', '/auth/register'].includes(config.url)
+  if (token && !isAnonymousAuthEndpoint) {
+    config.headers.Authorization = `Bearer ${token}`
+  }
+  return config
+})
+
+http.interceptors.response.use(
+  (response) => response.data,
+  async (error) => {
+    const config = error.config as RetryableRequestConfig | undefined
+    const isAuthEndpoint = typeof config?.url === 'string' && config.url.startsWith('/auth/')
+    if (error.response?.status !== 401 || !config || config._authRetry || isAuthEndpoint || !authRefreshHandler) {
+      return Promise.reject(error)
+    }
+
+    config._authRetry = true
+    try {
+      const nextToken = await refreshAuthenticatedSession()
+      config.headers.Authorization = `Bearer ${nextToken}`
+      return http.request(config)
+    } catch {
+      return Promise.reject(error)
+    }
+  },
+)
+
+export function unwrapApiResponse<T>(response: ApiEnvelope<T>): T {
+  if (response?.code !== '200') {
+    throw new ApiResponseError(
+      response?.message || '接口请求失败',
+      response?.code || 'UNKNOWN',
+      undefined,
+      response?.data,
+      response?.requestId,
+      response?.traceId,
+    )
+  }
+  return response.data
+}
+
+export function getApiErrorDetails(
+  error: unknown,
+  fallback = '接口请求失败',
+  options: ApiErrorDetailsOptions = {},
+): ApiErrorDetails {
+  if (error instanceof ApiResponseError) {
+    const message = error.code === 'A0401' && !options.preserveAuthenticationMessage
+      ? '登录状态已失效，请重新登录'
+      : error.code === 'A0403'
+        ? '当前账号无权访问该数据，请联系管理员确认权限'
+        : error.code.startsWith('S05')
+          ? '服务暂时不可用，请稍后重试'
+          : friendlyBusinessMessage(error.message) || '接口请求失败'
+    return { message, code: error.code, requestId: error.requestId, traceId: error.traceId }
+  }
+  if (axios.isAxiosError(error)) {
+    const response = error.response?.data as {
+      code?: string
+      message?: string
+      error?: string
+      requestId?: string | null
+      traceId?: string | null
+    } | undefined
+    const status = error.response?.status
+    const statusMessage = status === 401
+      ? '登录状态已失效，请重新登录'
+      : status === 403
+        ? '当前账号无权访问该数据，请联系管理员确认权限'
+        : status === 413
+          ? '上传文件的请求体过大，服务器已拒绝；请压缩后重试，如文件未超过 5MB，请联系管理员检查网关上传限制'
+          : status && status >= 500
+            ? '服务暂时不可用，请稍后重试'
+            : undefined
+    return {
+      message: statusMessage || friendlyBusinessMessage(response?.message || response?.error) || fallback,
+      code: response?.code || (error.response?.status ? `HTTP_${error.response.status}` : undefined),
+      requestId: response?.requestId || undefined,
+      traceId: response?.traceId || undefined,
+    }
+  }
+  // Local/runtime errors are not user-facing API messages and may contain stack details.
+  return { message: fallback }
+}
+
+export function getApiErrorMessage(error: unknown, fallback = '接口请求失败'): string {
+  return getApiErrorDetails(error, fallback).message
+}
diff --git a/src/shared/api/inboundCodeRelations.test.ts b/src/shared/api/inboundCodeRelations.test.ts
new file mode 100644
index 00000000..6afe83c3
--- /dev/null
+++ b/src/shared/api/inboundCodeRelations.test.ts
@@ -0,0 +1,27 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { http } from './http'
+import { overseasHttp } from './overseasHttp'
+import { getLoadingAssociationSummary, getOverseasInboundCodeRelationship, getPlatformInboundCodeAssociation } from './inboundCodeRelations'
+
+vi.mock('./http', async (original) => ({ ...(await original<typeof import('./http')>()), http: { get: vi.fn() } }))
+vi.mock('./overseasHttp', () => ({ overseasHttp: { get: vi.fn() } }))
+
+describe('inbound-code relationship APIs', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it('uses the frozen domestic and overseas read models and encodes the business code', async () => {
+    vi.mocked(http.get).mockResolvedValue({ code: '200', data: { inboundCode: 'IN/01', orderNo: 'ORD-1' } })
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', data: { inboundCode: 'IN/01', found: false, taillegOrders: [], inboundPlans: [], palletCodes: [], inventory: [] } })
+    await getPlatformInboundCodeAssociation('IN/01')
+    await getLoadingAssociationSummary('IN/01')
+    await getOverseasInboundCodeRelationship('IN/01')
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/orders/first-leg/inbound-code-associations/IN%2F01')
+    expect(http.get).toHaveBeenCalledWith('/platform/v1/first-leg/loading-associations/summary', { params: { inboundCode: 'IN/01' } })
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/inventory/inbound-code-relationships/IN%2F01')
+  })
+
+  it('does not accept customer or internal ids as lookup parameters', () => {
+    const source = `${getPlatformInboundCodeAssociation}${getLoadingAssociationSummary}${getOverseasInboundCodeRelationship}`
+    expect(source).not.toMatch(/customerId|inboundId|orderId|warehouseId/)
+  })
+})
diff --git a/src/shared/api/inboundCodeRelations.ts b/src/shared/api/inboundCodeRelations.ts
new file mode 100644
index 00000000..5362f252
--- /dev/null
+++ b/src/shared/api/inboundCodeRelations.ts
@@ -0,0 +1,75 @@
+import { http, unwrapApiResponse, type ApiEnvelope } from './http'
+import { overseasHttp } from './overseasHttp'
+
+export interface PlatformInboundCodeAssociation {
+  inboundCode: string
+  orderNo: string
+  orderStatus?: string | null
+  orderId: string
+  customerId: string
+  customerName: string
+  destinationType?: string | null
+  destinationCountryCode?: string | null
+  destinationWarehouseId?: string | null
+  destinationWarehouseCode?: string | null
+  destinationWarehouseName?: string | null
+}
+
+export interface OverseasInboundCodeRelationship {
+  inboundCode: string
+  found: boolean
+  customer: { customerId: string; customerName: string } | null
+  overseasWarehouse: { warehouseId: string; warehouseCode: string; warehouseName: string } | null
+  overseasReceivingStatus?: string | null
+  taillegOrders: Array<{ orderNo: string; orderStatus?: string | null }>
+  inboundPlans: Array<{ planNo: string; planStatus?: string | null; receivingStatus?: string | null }>
+  palletCodes: string[]
+  inventory: Array<{ skuCode: string; productNameZh?: string | null; productNameEn?: string | null; packageCount: number }>
+}
+
+export interface LoadingAssociationSummary {
+  inboundId: string
+  inboundCode: string
+  orderNo?: string | null
+  loadingPlanId?: string | null
+  loadingPlanNo?: string | null
+  containerBookingId?: string | null
+  cabinetNo?: string | null
+  containerNo?: string | null
+  loadingStatus?: string | null
+  taskId?: string | null
+  pdaTaskStatus?: string | null
+  coLoadGroupId?: string | null
+  coLoadGroupNo?: string | null
+  items: Array<{ itemId: string }>
+}
+
+export async function getPlatformInboundCodeAssociation(inboundCode: string) {
+  const response = await http.get<ApiEnvelope<PlatformInboundCodeAssociation>, ApiEnvelope<PlatformInboundCodeAssociation>>(
+    `/platform/v1/orders/first-leg/inbound-code-associations/${encodeURIComponent(inboundCode)}`,
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function getLoadingAssociationSummary(inboundCode: string) {
+  const response = await http.get<ApiEnvelope<LoadingAssociationSummary>, ApiEnvelope<LoadingAssociationSummary>>(
+    '/platform/v1/first-leg/loading-associations/summary',
+    { params: { inboundCode } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function getLoadingAssociationSummaryByInboundId(inboundId: string) {
+  const response = await http.get<ApiEnvelope<LoadingAssociationSummary>, ApiEnvelope<LoadingAssociationSummary>>(
+    '/platform/v1/first-leg/loading-associations/summary',
+    { params: { inboundId } },
+  )
+  return unwrapApiResponse(response)
+}
+
+export async function getOverseasInboundCodeRelationship(inboundCode: string) {
+  const response = await overseasHttp.get<ApiEnvelope<OverseasInboundCodeRelationship>, ApiEnvelope<OverseasInboundCodeRelationship>>(
+    `/platform/v1/last-leg/inventory/inbound-code-relationships/${encodeURIComponent(inboundCode)}`,
+  )
+  return unwrapApiResponse(response)
+}
diff --git a/src/shared/api/overseasHttp.test.ts b/src/shared/api/overseasHttp.test.ts
new file mode 100644
index 00000000..9c5f4846
--- /dev/null
+++ b/src/shared/api/overseasHttp.test.ts
@@ -0,0 +1,99 @@
+import axios, { type InternalAxiosRequestConfig } from 'axios'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { registerAuthRefreshHandler } from './http'
+import { clearOverseasAccessToken, overseasHttp, replaceOverseasAccessToken } from './overseasHttp'
+
+const originalOverseasAdapter = overseasHttp.defaults.adapter
+
+function success(config: InternalAxiosRequestConfig, data: unknown) {
+  return Promise.resolve({ status: 200, statusText: 'OK', headers: {}, config, data })
+}
+
+describe('overseas HTTP client', () => {
+  beforeEach(() => {
+    localStorage.setItem('cc-admin-token', 'domestic-token')
+    clearOverseasAccessToken()
+    registerAuthRefreshHandler(async () => 'domestic-token')
+  })
+
+  afterEach(() => {
+    overseasHttp.defaults.adapter = originalOverseasAdapter
+    localStorage.clear()
+    clearOverseasAccessToken()
+  })
+
+  it('uses the overseas token supplied by the login session for concurrent requests', async () => {
+    replaceOverseasAccessToken('overseas-token', 900)
+    const authorizations: unknown[] = []
+    overseasHttp.defaults.adapter = async (config) => {
+      authorizations.push(config.headers.Authorization)
+      return success(config, { code: '200', message: 'success', data: [] })
+    }
+
+    await Promise.all([
+      overseasHttp.get('/platform/v1/last-leg/orders'),
+      overseasHttp.get('/platform/v1/warehouse-admin'),
+    ])
+
+    expect(authorizations).toEqual(['Bearer overseas-token', 'Bearer overseas-token'])
+  })
+
+  it('refreshes the unified session once and replays once after an overseas 401', async () => {
+    replaceOverseasAccessToken('overseas-1', 900)
+    const refresh = vi.fn(async () => {
+      replaceOverseasAccessToken('overseas-2', 900)
+      return 'domestic-2'
+    })
+    registerAuthRefreshHandler(refresh)
+    let requests = 0
+    const authorizations: unknown[] = []
+    overseasHttp.defaults.adapter = async (config) => {
+      authorizations.push(config.headers.Authorization)
+      if (requests++ === 0) {
+        throw new axios.AxiosError('Unauthorized', 'ERR_BAD_REQUEST', config, undefined, {
+          status: 401,
+          statusText: 'Unauthorized',
+          headers: {},
+          config,
+          data: { code: 'A0401', message: '海外令牌失效' },
+        })
+      }
+      return success(config, { code: '200', message: 'success', data: [] })
+    }
+
+    await overseasHttp.get('/platform/v1/last-leg/orders')
+
+    expect(refresh).toHaveBeenCalledTimes(1)
+    expect(requests).toBe(2)
+    expect(authorizations).toEqual(['Bearer overseas-1', 'Bearer overseas-2'])
+  })
+
+  it('refreshes the unified session when no usable overseas token is present', async () => {
+    const refresh = vi.fn(async () => {
+      replaceOverseasAccessToken('overseas-refreshed', 900)
+      return 'domestic-refreshed'
+    })
+    registerAuthRefreshHandler(refresh)
+    let authorization: unknown
+    overseasHttp.defaults.adapter = async (config) => {
+      authorization = config.headers.Authorization
+      return success(config, { code: '200', message: 'success', data: [] })
+    }
+
+    await overseasHttp.get('/platform/v1/last-leg/orders')
+
+    expect(refresh).toHaveBeenCalledTimes(1)
+    expect(authorization).toBe('Bearer overseas-refreshed')
+  })
+
+  it('fails before sending a business request when refresh is domestic-only', async () => {
+    const refresh = vi.fn(async () => 'domestic-only')
+    registerAuthRefreshHandler(refresh)
+    const adapter = vi.fn(async (config: InternalAxiosRequestConfig) => success(config, { code: '200', message: 'success', data: [] }))
+    overseasHttp.defaults.adapter = adapter
+
+    await expect(overseasHttp.get('/platform/v1/last-leg/orders')).rejects.toThrow('当前环境未签发海外访问令牌')
+    expect(refresh).toHaveBeenCalledTimes(1)
+    expect(adapter).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/shared/api/overseasHttp.ts b/src/shared/api/overseasHttp.ts
new file mode 100644
index 00000000..a2206a1c
--- /dev/null
+++ b/src/shared/api/overseasHttp.ts
@@ -0,0 +1,77 @@
+import axios, { type InternalAxiosRequestConfig } from 'axios'
+import { parseApiJsonResponse } from '@chongchong/shared'
+import { refreshAuthenticatedSession } from './http'
+
+interface CachedOverseasToken {
+  accessToken: string
+  refreshAfter: number
+}
+
+type RetryableOverseasRequestConfig = InternalAxiosRequestConfig & { _overseasAuthRetry?: boolean }
+
+const TOKEN_REFRESH_SAFETY_WINDOW_MS = 30_000
+
+let cachedToken: CachedOverseasToken | null = null
+
+export const overseasHttp = axios.create({
+  baseURL: import.meta.env.VITE_OVERSEAS_API_BASE_URL || '/overseas-api',
+  timeout: 15_000,
+  transformResponse: [(data: unknown) => parseApiJsonResponse(data)],
+})
+
+function currentOverseasAccessToken() {
+  return cachedToken && cachedToken.refreshAfter > Date.now() ? cachedToken.accessToken : ''
+}
+
+async function requireOverseasAccessToken() {
+  const current = currentOverseasAccessToken()
+  if (current) return current
+  await refreshAuthenticatedSession()
+  const refreshed = currentOverseasAccessToken()
+  if (!refreshed) throw new Error('当前环境未签发海外访问令牌')
+  return refreshed
+}
+
+export function replaceOverseasAccessToken(accessToken: string | null, expiresIn: number) {
+  if (!accessToken && expiresIn === 0) {
+    cachedToken = null
+    return
+  }
+  if (!accessToken || !Number.isFinite(expiresIn) || expiresIn <= 0) {
+    throw new Error('海外访问令牌响应无效')
+  }
+  cachedToken = {
+    accessToken,
+    refreshAfter: Date.now() + Math.max(0, expiresIn * 1000 - TOKEN_REFRESH_SAFETY_WINDOW_MS),
+  }
+}
+
+export function clearOverseasAccessToken() {
+  cachedToken = null
+}
+
+overseasHttp.interceptors.request.use(async (config) => {
+  const accessToken = await requireOverseasAccessToken()
+  config.headers.Authorization = `Bearer ${accessToken}`
+  return config
+})
+
+overseasHttp.interceptors.response.use(
+  (response) => response.data,
+  async (error) => {
+    const config = error.config as RetryableOverseasRequestConfig | undefined
+    if (error.response?.status !== 401 || !config || config._overseasAuthRetry) {
+      return Promise.reject(error)
+    }
+    config._overseasAuthRetry = true
+    clearOverseasAccessToken()
+    try {
+      await refreshAuthenticatedSession()
+      const accessToken = await requireOverseasAccessToken()
+      config.headers.Authorization = `Bearer ${accessToken}`
+      return overseasHttp.request(config)
+    } catch {
+      return Promise.reject(error)
+    }
+  },
+)
diff --git a/src/shared/components/AGENTS.md b/src/shared/components/AGENTS.md
new file mode 100644
index 00000000..14ab4f1b
--- /dev/null
+++ b/src/shared/components/AGENTS.md
@@ -0,0 +1,34 @@
+# Admin Shared Components Instructions
+
+## 适用范围
+
+- 本文件适用于 `src/shared/components/` 及其直接测试。业务页面使用这些组件时，同时遵守 `../../../AGENTS.md` 和 `../../../../../docs/Admin-Client前端原型还原验收规则.md`。
+- 这里只放与具体业务无关、已被多个模块真实复用的后台组件；纯业务字段、状态和流程留在所属模块。
+
+## 标准列表组合
+
+- 标准列表使用 `ListPageLayout` 组织查询区和表格区，保持单一 `16px` 间距；不叠加页面级空白操作区或重复面板间距。
+- 查询与筛选使用 `QueryToolbar.vue`，通过 `fields`、`v-model`、`search`、`reset` 接入；查询即刷新当前结果，不另设独立刷新按钮。
+- 数据列表使用 `DataTable.vue`，通过 `columns`、命名插槽、`v-model:page`、`v-model:page-size` 和 `total` 接入，不重复拼装 `el-table` 与分页器。
+- “操作”列放在第一列，需要固定时固定在左侧。单行操作不超过 3 个时直接显示“图标 + 文案”；第 4 个起使用 `MoreHorizontal` 菜单，并优先直接保留详情、编辑、下载等高频操作。
+- 新增、导入、导出和批量操作放入 `DataTable` 的 `toolbar-actions`；不放入查询栏，不用 `toolbar-start` 重复列表标题、数量或说明，数量统一放在 `pagination-left`。
+- 路由标题和说明默认由 `AppLayout` 的 `page-heading` 根据路由元数据展示；标准列表正文不重复标题。只有明确关闭路由页头的详情页或工作台才自带独立页头。
+
+## 复用入口
+
+- XLSX 批量导入使用 `BatchImportDialog.vue`；页面只提供模板下载、导入调用和成功后刷新，不复制文件校验、上传状态、错误报告或弹窗 CSS。
+- 模态框和抽屉优先使用 `AppDialog.vue`、`AppDrawer.vue`；但独立页面、弹框或抽屉的选择必须服从对应原型，不因已有组件方便而替换承载方式。
+- `AppDialog` 未提供自定义 `#header` 时保留 Element 原生 `title` 标题栏；`fullscreenable` 只在原标题栏追加全屏控件，不得仅为标题或全屏按钮再造一层 header。只有原型确有复合标题结构时才使用 `#header`。
+- 加载失败组合 `LoadErrorState.vue` 与 `ApiErrorMeta.vue`，保留重试和 `requestId`/`traceId`；状态与复制优先使用 `StatusBadge.vue`、`CopyButton.vue`。
+- 参考页面：查询和表格见 `../../modules/master-data/express-companies/pages/ExpressCompaniesView.vue`，批量导入见该页面与 `../../modules/master-data/counterparties/pages/PartnersView.vue`，抽屉见 `../../modules/downloads/pages/DownloadCenterView.vue`。
+
+## 图标、状态与可访问性
+
+- 原型已定义图标时复用原型资源；原型未定义时使用 Lucide：查看 `Eye`、编辑 `Pencil`、更多 `MoreHorizontal`、新增 `Plus`、删除 `Trash2`、启停 `Power`、刷新 `RefreshCw`、导入 `FileUp`、导出/下载 `Download`、返回 `ArrowLeft`、保存 `Save`、复制 `Copy`。
+- 危险操作保留明确文案、危险色、确认过程和成功/失败反馈，不只显示图标。
+- 组件按适用语义覆盖加载、空数据、错误、禁用和无权限状态；保留键盘操作、可见焦点、表单标签、图标按钮名称和颜色对比度，不只用颜色表达状态。
+
+## 修改与验证
+
+- 扩展公共组件前定向检查全部消费者；通用能力扩展公共组件，纯业务特例留在模块，不用页面级 CSS 覆盖破坏公共契约。
+- 至少运行组件测试、直接受影响页面测试和 `pnpm typecheck`；交付前按项目指引运行完整测试与构建。
diff --git a/src/shared/components/AdminPage.vue b/src/shared/components/AdminPage.vue
new file mode 100644
index 00000000..6c111776
--- /dev/null
+++ b/src/shared/components/AdminPage.vue
@@ -0,0 +1,33 @@
+<script setup lang="ts">
+withDefaults(defineProps<{
+  as?: string
+  width?: 'full' | 'comfortable'
+  spacing?: 'compact' | 'normal' | 'relaxed'
+}>(), {
+  as: 'main',
+  width: 'full',
+  spacing: 'normal',
+})
+</script>
+
+<template>
+  <component :is="as" class="admin-page" :class="[`is-width-${width}`, `is-spacing-${spacing}`]">
+    <slot />
+  </component>
+</template>
+
+<style scoped>
+.admin-page { display: flex; min-width: 0; flex-direction: column; margin: 0 auto; }
+.admin-page.is-width-comfortable { width: min(100%, 1440px); }
+.admin-page.is-spacing-compact { gap: 12px; }
+.admin-page.is-spacing-normal { gap: 16px; }
+.admin-page.is-spacing-relaxed { gap: 20px; }
+
+@media (min-width: 1920px) {
+  .admin-page.is-spacing-normal { gap: 12px; }
+
+  .admin-page.is-width-comfortable {
+    width: min(100%, 1920px);
+  }
+}
+</style>
diff --git a/src/shared/components/ApiErrorMeta.vue b/src/shared/components/ApiErrorMeta.vue
new file mode 100644
index 00000000..4e697014
--- /dev/null
+++ b/src/shared/components/ApiErrorMeta.vue
@@ -0,0 +1,29 @@
+<script setup lang="ts">
+import type { ApiErrorDetails } from '@/shared/api/http'
+import CopyButton from '@/shared/components/CopyButton.vue'
+
+const props = defineProps<{ details: ApiErrorDetails }>()
+</script>
+
+<template>
+  <div v-if="details.code || details.requestId || details.traceId" class="api-error-meta" aria-label="接口错误追踪信息">
+    <span v-if="details.code" class="api-error-code">{{ details.code }}</span>
+    <CopyButton v-if="details.requestId" class="api-error-copy" :value="props.details.requestId" label="请求 ID">
+      <span class="api-error-copy__label">请求 ID</span><code>{{ props.details.requestId }}</code>
+    </CopyButton>
+    <CopyButton v-if="details.traceId" class="api-error-copy" :value="props.details.traceId" label="Trace ID">
+      <span class="api-error-copy__label">Trace ID</span><code>{{ props.details.traceId }}</code>
+    </CopyButton>
+  </div>
+</template>
+
+<style scoped>
+.api-error-meta { display: flex; min-width: 0; flex-wrap: wrap; align-items: center; gap: 6px; margin-top: 8px; }
+.api-error-code { padding: 3px 7px; border-radius: 4px; background: #fee4e2; color: #912018; font-size: 10px; font-weight: 750; }
+.api-error-meta :deep(.api-error-copy) { display: inline-flex; min-width: 0; max-width: 100%; min-height: 30px; align-items: center; gap: 6px; padding: 4px 7px; border-color: #fecdca; border-radius: 4px; background: #fff; color: #7a271a; }
+.api-error-meta :deep(.api-error-copy:hover) { border-color: #fda29b; background: #fff5f4; color: #7a271a; }
+.api-error-meta :deep(.api-error-copy > span) { min-width: 0; gap: 6px; }
+.api-error-copy__label { flex: 0 0 auto; font-size: 10px; font-weight: 700; }
+.api-error-meta code { min-width: 0; overflow: hidden; color: #b42318; font-family: "Cascadia Code", Consolas, monospace; font-size: 10px; text-overflow: ellipsis; white-space: nowrap; }
+.api-error-meta :deep(svg) { flex: 0 0 auto; }
+</style>
diff --git a/src/shared/components/AppDialog.test.ts b/src/shared/components/AppDialog.test.ts
new file mode 100644
index 00000000..df83280c
--- /dev/null
+++ b/src/shared/components/AppDialog.test.ts
@@ -0,0 +1,104 @@
+import { defineComponent } from 'vue'
+import { mount } from '@vue/test-utils'
+import { describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import AppDialog from './AppDialog.vue'
+
+const ElDialogStub = defineComponent({
+  props: {
+    modelValue: Boolean,
+    title: String,
+    showClose: Boolean,
+    closeOnClickModal: Boolean,
+    closeOnPressEscape: Boolean,
+    fullscreen: Boolean,
+  },
+  template: '<section data-testid="dialog"><h2 v-if="!$slots.header" data-testid="native-title">{{ title }}</h2><slot name="header" /><slot /><slot name="footer" /></section>',
+})
+
+const ElButtonStub = defineComponent({
+  props: {
+    disabled: Boolean,
+    loading: Boolean,
+  },
+  emits: ['click'],
+  template: '<button type="button" :disabled="disabled" @click="$emit(\'click\')"><slot /></button>',
+})
+
+function mountDialog(props: Record<string, unknown> = {}) {
+  return mount(AppDialog, {
+    props: { modelValue: true, title: '编辑资料', ...props },
+    slots: { default: '<p>弹框内容</p>' },
+    global: {
+      stubs: { ElDialog: ElDialogStub, ElButton: ElButtonStub },
+      directives: { loading: {} },
+    },
+  })
+}
+
+describe('AppDialog', () => {
+  it('provides default cancel and confirm actions', async () => {
+    const wrapper = mountDialog()
+    const buttons = wrapper.findAll('button')
+
+    expect(buttons.map((button) => button.text())).toEqual(['取消', '确定'])
+    await buttons[1].trigger('click')
+    expect(wrapper.emitted('confirm')).toHaveLength(1)
+
+    await buttons[0].trigger('click')
+    expect(wrapper.emitted('cancel')).toHaveLength(1)
+    expect(wrapper.emitted('update:modelValue')).toEqual([[false]])
+  })
+
+  it('prevents accidental closing while confirmation is submitting', () => {
+    const wrapper = mountDialog({ confirmLoading: true })
+    const dialog = wrapper.getComponent(ElDialogStub)
+    const cancelButton = wrapper.findAll('button')[0]
+
+    expect(dialog.props('showClose')).toBe(false)
+    expect(dialog.props('closeOnClickModal')).toBe(false)
+    expect(dialog.props('closeOnPressEscape')).toBe(false)
+    expect(cancelButton.attributes('disabled')).toBeDefined()
+  })
+
+  it('can render a content-only dialog without footer actions', () => {
+    const wrapper = mountDialog({ showFooter: false })
+    expect(wrapper.findAll('button')).toHaveLength(0)
+  })
+
+  it('provides opt-in fullscreen controls without changing ordinary dialogs', async () => {
+    const ordinary = mountDialog()
+    expect(ordinary.getComponent(ElDialogStub).props('fullscreen')).toBe(false)
+    expect(ordinary.find('button[aria-label="展开全屏"]').exists()).toBe(false)
+
+    const wrapper = mountDialog({ fullscreenable: true, defaultFullscreen: true })
+    expect(wrapper.getComponent(ElDialogStub).props('fullscreen')).toBe(true)
+    expect(wrapper.get('[data-testid="native-title"]').text()).toBe('编辑资料')
+    expect(wrapper.find('.app-dialog__header').exists()).toBe(false)
+    expect(wrapper.find('.app-dialog__native-fullscreen-control').exists()).toBe(true)
+    expect(wrapper.find('button[aria-label="退出全屏"]').exists()).toBe(true)
+
+    await wrapper.get('button[aria-label="退出全屏"]').trigger('click')
+    expect(wrapper.getComponent(ElDialogStub).props('fullscreen')).toBe(false)
+    expect(wrapper.find('button[aria-label="展开全屏"]').exists()).toBe(true)
+  })
+
+  it('keeps the dialog chrome fixed while long content scrolls in the body', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/shared/components/AppDialog.vue'), 'utf8')
+
+    expect(source).toContain(':global(.app-dialog.el-dialog) { position: relative; display: flex;')
+    expect(source).toContain('width: 100%; max-width: 100%; height: 100vh;')
+    expect(source).toContain(':global(.app-dialog .el-dialog__body) { min-height: 0; overflow-y: auto;')
+    expect(source).toContain('max-height: calc(100svh - 20px)')
+  })
+
+  it('keeps the native title bar when fullscreen is enabled without a custom header', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/shared/components/AppDialog.vue'), 'utf8')
+
+    expect(source).toContain('<template v-if="$slots.header" #header>')
+    expect(source).not.toContain('<template v-if="$slots.header || fullscreenable" #header>')
+    expect(source).toContain("fullscreenable && !$slots.header")
+    expect(source).toContain('app-dialog__native-fullscreen-control')
+  })
+})
diff --git a/src/shared/components/AppDialog.vue b/src/shared/components/AppDialog.vue
new file mode 100644
index 00000000..bf1bdc27
--- /dev/null
+++ b/src/shared/components/AppDialog.vue
@@ -0,0 +1,145 @@
+<script setup lang="ts">
+import { Maximize2, Minimize2 } from '@lucide/vue'
+import { computed, ref, watch } from 'vue'
+
+export type DialogConfirmType = 'primary' | 'success' | 'warning' | 'danger' | 'info'
+
+defineOptions({ inheritAttrs: false })
+
+const props = withDefaults(defineProps<{
+  title: string
+  width?: string | number
+  loading?: boolean
+  confirmLoading?: boolean
+  confirmDisabled?: boolean
+  confirmText?: string
+  cancelText?: string
+  confirmType?: DialogConfirmType
+  showFooter?: boolean
+  showCancel?: boolean
+  showConfirm?: boolean
+  showClose?: boolean
+  closeOnClickModal?: boolean
+  closeOnPressEscape?: boolean
+  destroyOnClose?: boolean
+  lockWhileSubmitting?: boolean
+  fullscreenable?: boolean
+  defaultFullscreen?: boolean
+}>(), {
+  width: 'min(560px, calc(100vw - 28px))',
+  loading: false,
+  confirmLoading: false,
+  confirmDisabled: false,
+  confirmText: '确定',
+  cancelText: '取消',
+  confirmType: 'primary',
+  showFooter: true,
+  showCancel: true,
+  showConfirm: true,
+  showClose: true,
+  closeOnClickModal: false,
+  closeOnPressEscape: true,
+  destroyOnClose: false,
+  lockWhileSubmitting: true,
+  fullscreenable: false,
+  defaultFullscreen: false,
+})
+
+const open = defineModel<boolean>({ default: false })
+const fullscreen = ref(props.defaultFullscreen)
+const emit = defineEmits<{
+  confirm: []
+  cancel: []
+}>()
+const submittingLocked = computed(() => props.lockWhileSubmitting && props.confirmLoading)
+
+watch(open, (value) => {
+  if (value) fullscreen.value = props.defaultFullscreen
+})
+
+function toggleFullscreen() {
+  fullscreen.value = !fullscreen.value
+}
+
+function closeDialog() {
+  if (submittingLocked.value) return
+  open.value = false
+  emit('cancel')
+}
+</script>
+
+<template>
+  <el-dialog
+    v-bind="$attrs"
+    v-model="open"
+    class="app-dialog"
+    :title="title"
+    :width="width"
+    :show-close="showClose && !submittingLocked"
+    :close-on-click-modal="closeOnClickModal && !submittingLocked"
+    :close-on-press-escape="closeOnPressEscape && !submittingLocked"
+    :destroy-on-close="destroyOnClose"
+    :fullscreen="fullscreenable && fullscreen"
+    :class="{ 'has-native-fullscreen-control': fullscreenable && !$slots.header }"
+  >
+    <template v-if="$slots.header" #header>
+      <div class="app-dialog__header">
+        <div class="app-dialog__header-content">
+          <slot name="header" :fullscreen="fullscreen" :toggle-fullscreen="toggleFullscreen" />
+        </div>
+        <el-tooltip v-if="fullscreenable" :content="fullscreen ? '退出全屏' : '展开全屏'" placement="bottom">
+          <el-button text :aria-label="fullscreen ? '退出全屏' : '展开全屏'" @click="toggleFullscreen">
+            <Minimize2 v-if="fullscreen" :size="18" />
+            <Maximize2 v-else :size="18" />
+          </el-button>
+        </el-tooltip>
+      </div>
+    </template>
+    <el-tooltip v-if="fullscreenable && !$slots.header" :content="fullscreen ? '退出全屏' : '展开全屏'" placement="bottom">
+      <el-button
+        class="app-dialog__native-fullscreen-control"
+        :class="{ 'is-without-close': !showClose || submittingLocked }"
+        text
+        :aria-label="fullscreen ? '退出全屏' : '展开全屏'"
+        @click="toggleFullscreen"
+      >
+        <Minimize2 v-if="fullscreen" :size="18" />
+        <Maximize2 v-else :size="18" />
+      </el-button>
+    </el-tooltip>
+    <div v-loading="loading" class="app-dialog__body" :aria-busy="loading || confirmLoading">
+      <slot />
+    </div>
+    <template v-if="showFooter" #footer>
+      <slot name="footer" :close="closeDialog" :submitting="confirmLoading">
+        <div class="app-dialog__footer">
+          <el-button v-if="showCancel" :disabled="submittingLocked" @click="closeDialog">{{ cancelText }}</el-button>
+          <el-button
+            v-if="showConfirm"
+            :type="confirmType"
+            :loading="confirmLoading"
+            :disabled="loading || confirmDisabled"
+            @click="emit('confirm')"
+          >{{ confirmText }}</el-button>
+        </div>
+      </slot>
+    </template>
+  </el-dialog>
+</template>
+
+<style scoped>
+:global(.app-dialog.el-dialog) { position: relative; display: flex; max-height: min(90vh, 900px); flex-direction: column; overflow: hidden; }
+:global(.app-dialog.el-dialog.is-fullscreen) { width: 100%; max-width: 100%; height: 100vh; max-height: 100vh; margin: 0 !important; border-radius: 0; }
+:global(.app-dialog .el-dialog__header), :global(.app-dialog .el-dialog__footer) { flex: 0 0 auto; }
+:global(.app-dialog .el-dialog__body) { min-height: 0; overflow-y: auto; overscroll-behavior: contain; }
+:global(.app-dialog.has-native-fullscreen-control .el-dialog__title) { display: block; padding-right: 44px; }
+.app-dialog__header { display: flex; width: 100%; min-width: 0; align-items: center; justify-content: space-between; gap: 12px; color: var(--cc-text); font-size: 18px; font-weight: 600; line-height: 24px; }
+.app-dialog__header-content { min-width: 0; flex: 1; }
+.app-dialog__header > :deep(.el-button) { flex: 0 0 auto; margin-right: 24px; color: var(--cc-muted); }
+.app-dialog__native-fullscreen-control { position: absolute; z-index: 2; top: 10px; right: 48px; color: var(--cc-muted); }
+.app-dialog__native-fullscreen-control.is-without-close { right: 12px; }
+.app-dialog__body { min-height: 0; }
+.app-dialog__footer { display: flex; flex-wrap: wrap; justify-content: flex-end; gap: 10px; }
+.app-dialog__footer :deep(.el-button) { margin-left: 0; }
+@media (max-width: 720px) { :global(.app-dialog.el-dialog) { max-height: calc(100svh - 20px); margin-block: 10px !important; } .app-dialog__footer :deep(.el-button) { min-height: 44px; } }
+</style>
diff --git a/src/shared/components/AppDrawer.test.ts b/src/shared/components/AppDrawer.test.ts
new file mode 100644
index 00000000..0578d15f
--- /dev/null
+++ b/src/shared/components/AppDrawer.test.ts
@@ -0,0 +1,66 @@
+import { defineComponent } from 'vue'
+import { mount } from '@vue/test-utils'
+import { describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import AppDrawer from './AppDrawer.vue'
+
+const ElDrawerStub = defineComponent({
+  props: {
+    modelValue: Boolean,
+    showClose: Boolean,
+    closeOnClickModal: Boolean,
+    closeOnPressEscape: Boolean,
+  },
+  template: '<section data-testid="drawer"><slot name="header" /><slot /><slot name="footer" /></section>',
+})
+
+const ElButtonStub = defineComponent({
+  props: { disabled: Boolean, loading: Boolean },
+  emits: ['click'],
+  template: '<button type="button" :disabled="disabled" @click="$emit(\'click\')"><slot /></button>',
+})
+
+function mountDrawer(props: Record<string, unknown> = {}) {
+  return mount(AppDrawer, {
+    props: { modelValue: true, title: '编辑资料', ...props },
+    slots: { default: '<p>抽屉内容</p>' },
+    global: {
+      stubs: { ElDrawer: ElDrawerStub, ElButton: ElButtonStub },
+      directives: { loading: {} },
+    },
+  })
+}
+
+describe('AppDrawer', () => {
+  it('provides default cancel and confirm actions', async () => {
+    const wrapper = mountDrawer()
+    const buttons = wrapper.findAll('button')
+
+    expect(buttons.map((button) => button.text())).toEqual(['取消', '确定'])
+    await buttons[1].trigger('click')
+    expect(wrapper.emitted('confirm')).toHaveLength(1)
+
+    await buttons[0].trigger('click')
+    expect(wrapper.emitted('cancel')).toHaveLength(1)
+    expect(wrapper.emitted('update:modelValue')).toEqual([[false]])
+  })
+
+  it('prevents accidental closing while confirmation is submitting', () => {
+    const wrapper = mountDrawer({ confirmLoading: true })
+    const drawer = wrapper.getComponent(ElDrawerStub)
+    const cancelButton = wrapper.findAll('button')[0]
+
+    expect(drawer.props('showClose')).toBe(false)
+    expect(drawer.props('closeOnClickModal')).toBe(false)
+    expect(drawer.props('closeOnPressEscape')).toBe(false)
+    expect(cancelButton.attributes('disabled')).toBeDefined()
+  })
+
+  it('keeps the drawer chrome fixed while long content scrolls in the body', () => {
+    const source = readFileSync(resolve(process.cwd(), 'src/shared/components/AppDrawer.vue'), 'utf8')
+
+    expect(source).toContain(':global(.app-drawer .el-drawer__body) { min-height: 0; overflow-y: auto;')
+    expect(source).toContain('max-width: 94vw')
+  })
+})
diff --git a/src/shared/components/AppDrawer.vue b/src/shared/components/AppDrawer.vue
new file mode 100644
index 00000000..aae5ad47
--- /dev/null
+++ b/src/shared/components/AppDrawer.vue
@@ -0,0 +1,97 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import type { DialogConfirmType } from './AppDialog.vue'
+
+defineOptions({ inheritAttrs: false })
+
+const props = withDefaults(defineProps<{
+  title: string
+  size?: string | number
+  loading?: boolean
+  confirmLoading?: boolean
+  confirmDisabled?: boolean
+  confirmText?: string
+  cancelText?: string
+  confirmType?: DialogConfirmType
+  showFooter?: boolean
+  showCancel?: boolean
+  showConfirm?: boolean
+  showClose?: boolean
+  closeOnClickModal?: boolean
+  closeOnPressEscape?: boolean
+  destroyOnClose?: boolean
+  lockWhileSubmitting?: boolean
+}>(), {
+  size: 'min(680px, 94vw)',
+  loading: false,
+  confirmLoading: false,
+  confirmDisabled: false,
+  confirmText: '确定',
+  cancelText: '取消',
+  confirmType: 'primary',
+  showFooter: true,
+  showCancel: true,
+  showConfirm: true,
+  showClose: true,
+  closeOnClickModal: false,
+  closeOnPressEscape: true,
+  destroyOnClose: false,
+  lockWhileSubmitting: true,
+})
+
+const open = defineModel<boolean>({ default: false })
+const emit = defineEmits<{
+  confirm: []
+  cancel: []
+}>()
+const submittingLocked = computed(() => props.lockWhileSubmitting && props.confirmLoading)
+
+function closeDrawer() {
+  if (submittingLocked.value) return
+  open.value = false
+  emit('cancel')
+}
+</script>
+
+<template>
+  <el-drawer
+    v-bind="$attrs"
+    v-model="open"
+    class="app-drawer"
+    :title="title"
+    :size="size"
+    :show-close="showClose && !submittingLocked"
+    :close-on-click-modal="closeOnClickModal && !submittingLocked"
+    :close-on-press-escape="closeOnPressEscape && !submittingLocked"
+    :destroy-on-close="destroyOnClose"
+  >
+    <template v-if="$slots.header" #header><slot name="header" /></template>
+    <div v-loading="loading" class="app-drawer__body" :aria-busy="loading || confirmLoading">
+      <slot />
+    </div>
+    <template v-if="showFooter" #footer>
+      <slot name="footer" :close="closeDrawer" :submitting="confirmLoading">
+        <div class="app-drawer__footer">
+          <el-button v-if="showCancel" :disabled="submittingLocked" @click="closeDrawer">{{ cancelText }}</el-button>
+          <el-button
+            v-if="showConfirm"
+            :type="confirmType"
+            :loading="confirmLoading"
+            :disabled="loading || confirmDisabled"
+            @click="emit('confirm')"
+          >{{ confirmText }}</el-button>
+        </div>
+      </slot>
+    </template>
+  </el-drawer>
+</template>
+
+<style scoped>
+:global(.app-drawer) { max-width: calc(100vw - 20px); }
+:global(.app-drawer .el-drawer__header), :global(.app-drawer .el-drawer__footer) { flex: 0 0 auto; }
+:global(.app-drawer .el-drawer__body) { min-height: 0; overflow-y: auto; overscroll-behavior: contain; }
+.app-drawer__body { min-height: 0; }
+.app-drawer__footer { display: flex; flex-wrap: wrap; justify-content: flex-end; gap: 10px; }
+.app-drawer__footer :deep(.el-button) { margin-left: 0; }
+@media (max-width: 720px) { :global(.app-drawer) { max-width: 94vw; } .app-drawer__footer :deep(.el-button) { min-height: 44px; } }
+</style>
diff --git a/src/shared/components/BatchImportDialog.test.ts b/src/shared/components/BatchImportDialog.test.ts
new file mode 100644
index 00000000..6b06424f
--- /dev/null
+++ b/src/shared/components/BatchImportDialog.test.ts
@@ -0,0 +1,92 @@
+import ElementPlus from 'element-plus'
+import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import BatchImportDialog, { type BatchImportResult } from './BatchImportDialog.vue'
+
+class ResizeObserverStub implements ResizeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+
+function button(label: string) {
+  return [...document.body.querySelectorAll('button')].find((item) => item.textContent?.trim() === label)
+}
+
+async function chooseFile(file: File) {
+  const input = document.body.querySelector<HTMLInputElement>('input[type="file"]')!
+  Object.defineProperty(input, 'files', { configurable: true, value: [file] })
+  input.dispatchEvent(new Event('change', { bubbles: true }))
+  await flushPromises()
+}
+
+enableAutoUnmount(afterEach)
+
+describe('BatchImportDialog', () => {
+  afterEach(() => {
+    document.body.innerHTML = ''
+    vi.unstubAllGlobals()
+  })
+
+  it.each([false, true])('uses the shared two-step flow and submits a validated XLSX file (dense: %s)', async (dense) => {
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+    const result: BatchImportResult = {
+      fileName: 'partners.xlsx', totalRows: 2, importedRows: 2, success: true, errors: [],
+    }
+    const importFile = vi.fn().mockResolvedValue(result)
+    const wrapper = mount(BatchImportDialog, {
+      attrs: { class: dense ? 'admin-density-dialog' : undefined },
+      attachTo: document.body,
+      props: {
+        modelValue: true,
+        title: '批量导入往来单位',
+        entityLabel: '往来单位',
+        templateFileName: '往来单位导入模板-v1.xlsx',
+        downloadTemplate: vi.fn(),
+        importFile,
+      },
+      global: { plugins: [ElementPlus] },
+    })
+    await flushPromises()
+
+    expect(document.querySelector('.batch-import-dialog')?.classList.contains('admin-density-dialog')).toBe(dense)
+    expect(document.body.textContent).toContain('下载标准模板')
+    expect(document.body.textContent).toContain('选择填写后的文件')
+    expect(button('开始导入')?.hasAttribute('disabled')).toBe(true)
+
+    const file = new File(['xlsx'], 'partners.xlsx', {
+      type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    })
+    await chooseFile(file)
+    expect(button('开始导入')?.hasAttribute('disabled')).toBe(false)
+    button('开始导入')?.click()
+    await flushPromises()
+
+    expect(importFile).toHaveBeenCalledWith(file)
+    expect(wrapper.emitted('success')?.[0]).toEqual([result])
+    expect(document.body.textContent).toContain('导入完成：成功新增 2 条往来单位')
+  })
+
+  it('rejects files that do not use the XLSX template format', async () => {
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+    const importFile = vi.fn()
+    mount(BatchImportDialog, {
+      attachTo: document.body,
+      props: {
+        modelValue: true,
+        title: '批量导入快递公司',
+        entityLabel: '快递公司',
+        templateFileName: '快递公司批量导入模板-v1.xlsx',
+        downloadTemplate: vi.fn(),
+        importFile,
+      },
+      global: { plugins: [ElementPlus] },
+    })
+    await flushPromises()
+
+    await chooseFile(new File(['csv'], 'companies.csv', { type: 'text/csv' }))
+
+    expect(button('开始导入')?.hasAttribute('disabled')).toBe(true)
+    expect(importFile).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/shared/components/BatchImportDialog.vue b/src/shared/components/BatchImportDialog.vue
new file mode 100644
index 00000000..9b7501f2
--- /dev/null
+++ b/src/shared/components/BatchImportDialog.vue
@@ -0,0 +1,245 @@
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue'
+import { Download, FileSpreadsheet, Upload } from '@lucide/vue'
+import { ElMessage } from 'element-plus'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+
+export interface BatchImportError {
+  row: number
+  field: string
+  message: string
+}
+
+export interface BatchImportResult {
+  fileName: string
+  totalRows: number
+  importedRows: number
+  success: boolean
+  errors: BatchImportError[]
+}
+
+const props = withDefaults(defineProps<{
+  title: string
+  entityLabel: string
+  successUnit?: string
+  templateFileName: string
+  errorReportFileName?: string
+  maxFileSizeMb?: number
+  maxRows?: number
+  downloadTemplate: () => Promise<Blob>
+  importFile: (file: File) => Promise<BatchImportResult>
+}>(), {
+  successUnit: '条',
+  errorReportFileName: '',
+  maxFileSizeMb: 5,
+  maxRows: 1000,
+})
+
+const open = defineModel<boolean>({ required: true })
+const emit = defineEmits<{
+  success: [result: BatchImportResult]
+}>()
+
+const fileInputRef = ref<HTMLInputElement>()
+const selectedFile = ref<File | null>(null)
+const downloadingTemplate = ref(false)
+const importing = ref(false)
+const result = ref<BatchImportResult | null>(null)
+const importError = ref<ApiErrorDetails | null>(null)
+const displayedErrors = computed(() => result.value?.errors.slice(0, 100) || [])
+
+watch(open, (isOpen) => {
+  if (isOpen) resetState()
+})
+
+function resetFileInput() {
+  if (fileInputRef.value) fileInputRef.value.value = ''
+}
+
+function resetState() {
+  selectedFile.value = null
+  result.value = null
+  importError.value = null
+  resetFileInput()
+}
+
+function saveBlob(blob: Blob, fileName: string) {
+  const url = URL.createObjectURL(blob)
+  const anchor = document.createElement('a')
+  anchor.href = url
+  anchor.download = fileName
+  anchor.click()
+  URL.revokeObjectURL(url)
+}
+
+async function downloadTemplateFile() {
+  downloadingTemplate.value = true
+  try {
+    saveBlob(await props.downloadTemplate(), props.templateFileName)
+  } catch (error) {
+    const details = getApiErrorDetails(error, '导入模板下载失败，请稍后重试')
+    ElMessage.error(details.requestId ? `${details.message}（requestId: ${details.requestId}）` : details.message)
+  } finally {
+    downloadingTemplate.value = false
+  }
+}
+
+function selectFile(event: Event) {
+  const input = event.target as HTMLInputElement
+  const file = input.files?.[0] || null
+  result.value = null
+  importError.value = null
+  if (!file) {
+    selectedFile.value = null
+    return
+  }
+  if (!file.name.toLowerCase().endsWith('.xlsx')) {
+    selectedFile.value = null
+    resetFileInput()
+    ElMessage.error('请选择 .xlsx 格式的标准模板文件')
+    return
+  }
+  if (file.size > props.maxFileSizeMb * 1024 * 1024) {
+    selectedFile.value = null
+    resetFileInput()
+    ElMessage.error(`导入文件不能超过 ${props.maxFileSizeMb}MB`)
+    return
+  }
+  selectedFile.value = file
+}
+
+async function startImport() {
+  if (!selectedFile.value) {
+    ElMessage.warning('请先选择填写完成的 XLSX 文件')
+    return
+  }
+  importing.value = true
+  importError.value = null
+  result.value = null
+  try {
+    const importResult = await props.importFile(selectedFile.value)
+    result.value = importResult
+    if (importResult.success) {
+      selectedFile.value = null
+      resetFileInput()
+      ElMessage.success(`成功导入 ${importResult.importedRows} ${props.successUnit}${props.entityLabel}`)
+      emit('success', importResult)
+    }
+  } catch (error) {
+    importError.value = getApiErrorDetails(error, `${props.entityLabel}导入失败，请稍后重试`)
+  } finally {
+    importing.value = false
+  }
+}
+
+function downloadErrors() {
+  if (!result.value?.errors.length) return
+  const csvCell = (value: string | number) => `"${String(value).replaceAll('"', '""')}"`
+  const lines = [
+    ['行号', '字段', '错误原因'].map(csvCell).join(','),
+    ...result.value.errors.map((item) => [item.row || '文件', item.field, item.message].map(csvCell).join(',')),
+  ]
+  const fallbackName = `${result.value.fileName.replace(/\.xlsx$/i, '') || props.entityLabel}-错误报告.csv`
+  saveBlob(new Blob([`\ufeff${lines.join('\r\n')}`], { type: 'text/csv;charset=utf-8' }), props.errorReportFileName || fallbackName)
+}
+</script>
+
+<template>
+  <el-dialog
+    v-model="open"
+    :title="title"
+    width="min(720px, calc(100vw - 32px))"
+    :close-on-click-modal="!importing"
+    :close-on-press-escape="!importing"
+    :show-close="!importing"
+    class="batch-import-dialog"
+  >
+    <div class="batch-import-flow">
+      <section class="batch-import-step">
+        <div class="batch-import-step__heading">
+          <span>1</span>
+          <div><strong>下载标准模板</strong><p>请勿修改模板版本或表头，仅填写模板中的数据行。</p></div>
+        </div>
+        <el-button :loading="downloadingTemplate" @click="downloadTemplateFile"><Download :size="16" />下载模板</el-button>
+      </section>
+
+      <section class="batch-import-step">
+        <div class="batch-import-step__heading">
+          <span>2</span>
+          <div><strong>选择填写后的文件</strong><p>仅支持 .xlsx，最大 {{ maxFileSizeMb }}MB、{{ maxRows }} 行；当前仅新增，不更新已有档案。</p></div>
+        </div>
+        <label class="batch-import-file" :class="{ disabled: importing }">
+          <input ref="fileInputRef" type="file" accept=".xlsx,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" :disabled="importing" @change="selectFile" />
+          <FileSpreadsheet :size="20" />
+          <span>{{ selectedFile?.name || '选择 XLSX 文件' }}</span>
+        </label>
+      </section>
+
+      <el-alert type="info" :closable="false" show-icon title="整批校验通过后才会写入；任一行有误时整批不写入。" />
+      <el-alert v-if="importError" type="error" :closable="false" show-icon title="导入请求失败">
+        <p>{{ importError.message }}</p>
+        <ApiErrorMeta :details="importError" />
+      </el-alert>
+      <el-alert v-if="result?.success" type="success" :closable="false" show-icon :title="`导入完成：成功新增 ${result.importedRows} ${successUnit}${entityLabel}`" />
+
+      <section v-if="result && !result.success" class="batch-import-errors" aria-live="polite">
+        <div class="batch-import-errors__heading">
+          <div><strong>校验未通过，未写入任何数据</strong><p>发现 {{ result.errors.length }} 项问题，请修正后重新上传。</p></div>
+          <el-button size="small" @click="downloadErrors"><Download :size="14" />下载错误报告</el-button>
+        </div>
+        <div class="batch-import-errors__list">
+          <div v-for="(item, index) in displayedErrors" :key="`${item.row}-${item.field}-${index}`" class="batch-import-error">
+            <span>{{ item.row > 0 ? `第 ${item.row} 行` : '文件' }}</span>
+            <strong>{{ item.field }}</strong>
+            <p>{{ item.message }}</p>
+          </div>
+          <p v-if="result.errors.length > displayedErrors.length" class="batch-import-errors__overflow">
+            仅展示前 {{ displayedErrors.length }} 项，完整内容请下载错误报告。
+          </p>
+        </div>
+      </section>
+    </div>
+
+    <template #footer>
+      <div class="batch-import-footer">
+        <el-button :disabled="importing" @click="open = false">关闭</el-button>
+        <el-button type="primary" :loading="importing" :disabled="!selectedFile" @click="startImport"><Upload :size="16" />开始导入</el-button>
+      </div>
+    </template>
+  </el-dialog>
+</template>
+
+<style scoped>
+.batch-import-flow { display: grid; gap: var(--admin-space-5, 16px); }
+.batch-import-step { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-6, 20px); padding: var(--admin-space-5, 16px); border: 1px solid var(--cc-border); border-radius: var(--admin-radius, 8px); background: #fafbfc; }
+.batch-import-step__heading { display: flex; min-width: 0; align-items: flex-start; gap: var(--admin-space-5, 12px); }
+.batch-import-step__heading > span { display: grid; width: 24px; height: 24px; flex: 0 0 24px; place-items: center; border-radius: 50%; background: var(--cc-primary); color: #fff; font-size: var(--admin-font-caption, 12px); font-weight: 700; }
+.batch-import-step__heading strong, .batch-import-errors__heading strong { color: var(--cc-text); font-size: var(--admin-font-section, 14px); }
+.batch-import-step__heading p, .batch-import-errors__heading p { margin: var(--admin-space-1, 4px) 0 0; color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); line-height: 1.55; }
+.batch-import-file { display: inline-flex; min-width: 190px; max-width: 280px; align-items: center; justify-content: center; gap: var(--admin-space-3, 8px); padding: var(--admin-space-2, 9px) var(--admin-space-5, 14px); border: 1px solid var(--cc-border); border-radius: var(--admin-radius, 6px); background: #fff; color: var(--cc-primary); cursor: pointer; }
+.batch-import-file:hover { border-color: var(--cc-primary); }
+.batch-import-file:focus-within { outline: 2px solid color-mix(in srgb, var(--cc-primary) 28%, transparent); outline-offset: 2px; }
+.batch-import-file.disabled { cursor: not-allowed; opacity: .6; }
+.batch-import-file input { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); clip-path: inset(50%); white-space: nowrap; }
+.batch-import-file span { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.batch-import-flow :deep(.el-alert p) { margin: var(--admin-space-1, 5px) 0 0; }
+.batch-import-errors { overflow: hidden; border: 1px solid #f4c7c7; border-radius: var(--admin-radius, 8px); }
+.batch-import-errors__heading { display: flex; align-items: center; justify-content: space-between; gap: var(--admin-space-5, 16px); padding: var(--admin-space-5, 14px) var(--admin-space-5, 16px); background: #fff5f5; }
+.batch-import-errors__list { max-height: 220px; overflow: auto; }
+.batch-import-error { display: grid; grid-template-columns: 72px 130px minmax(0, 1fr); gap: var(--admin-space-4, 10px); padding: var(--admin-space-4, 10px) var(--admin-space-5, 16px); border-top: 1px solid #f4dddd; font-size: var(--admin-font-caption, 12px); }
+.batch-import-error span { color: #b42318; font-weight: 600; }
+.batch-import-error p { margin: 0; overflow-wrap: anywhere; }
+.batch-import-errors__overflow { margin: 0; padding: var(--admin-space-4, 10px) var(--admin-space-5, 16px); border-top: 1px solid #f4dddd; color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); }
+.batch-import-footer { display: flex; justify-content: flex-end; gap: var(--admin-space-4, 10px); }
+.batch-import-footer :deep(.el-button + .el-button) { margin-left: 0; }
+
+@media (max-width: 720px) {
+  .batch-import-step, .batch-import-errors__heading { align-items: stretch; flex-direction: column; }
+  .batch-import-file, .batch-import-step > :deep(.el-button) { width: 100%; max-width: none; min-height: 44px; }
+  .batch-import-error { grid-template-columns: 64px minmax(0, 1fr); }
+  .batch-import-error p { grid-column: 1 / -1; }
+  .batch-import-footer { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); }
+  .batch-import-footer :deep(.el-button) { width: 100%; min-height: 44px; }
+}
+</style>
diff --git a/src/shared/components/CopyButton.vue b/src/shared/components/CopyButton.vue
new file mode 100644
index 00000000..f0da8972
--- /dev/null
+++ b/src/shared/components/CopyButton.vue
@@ -0,0 +1,62 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { Copy } from '@lucide/vue'
+import { ElMessage } from 'element-plus'
+import { copyText } from '@/shared/utils/copyText'
+
+defineOptions({ inheritAttrs: false })
+
+const props = withDefaults(defineProps<{
+  value: string | number | null | undefined
+  label?: string
+  buttonText?: string
+  successText?: string
+  errorText?: string
+  disabled?: boolean
+  notify?: boolean
+}>(), {
+  label: '内容',
+  buttonText: '复制',
+  successText: undefined,
+  errorText: undefined,
+  disabled: false,
+  notify: true,
+})
+
+const emit = defineEmits<{
+  copied: [value: string]
+  'copy-error': [error: unknown]
+}>()
+
+const copying = ref(false)
+const copyValue = computed(() => props.value == null ? '' : String(props.value))
+const isDisabled = computed(() => props.disabled || copying.value || copyValue.value.length === 0)
+
+async function handleCopy() {
+  if (isDisabled.value) return
+  copying.value = true
+  try {
+    await copyText(copyValue.value)
+    if (props.notify) ElMessage.success(props.successText || `${props.label}已复制`)
+    emit('copied', copyValue.value)
+  } catch (error) {
+    if (props.notify) ElMessage.error(props.errorText || `${props.label}复制失败，请手动选择复制`)
+    emit('copy-error', error)
+  } finally {
+    copying.value = false
+  }
+}
+</script>
+
+<template>
+  <el-button
+    v-bind="$attrs"
+    :disabled="isDisabled"
+    :aria-label="`复制${label}`"
+    :title="`复制${label}`"
+    @click="handleCopy"
+  >
+    <Copy :size="14" aria-hidden="true" />
+    <slot :copying="copying">{{ buttonText }}</slot>
+  </el-button>
+</template>
diff --git a/src/shared/components/DataTable.test.ts b/src/shared/components/DataTable.test.ts
new file mode 100644
index 00000000..5b81f500
--- /dev/null
+++ b/src/shared/components/DataTable.test.ts
@@ -0,0 +1,386 @@
+import { computed, defineComponent } from 'vue'
+import { shallowMount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it } from 'vitest'
+import DataTable, { createPaginationItems, normalizePage, normalizePageSizes, normalizeTotal, type DataTableColumn } from './DataTable.vue'
+import LayoutPreferenceList from './LayoutPreferenceList.vue'
+import { UI_PREFERENCE_SCOPE, preferenceStorageKey } from '@/shared/utils/uiLayoutPreference'
+
+const TableStub = defineComponent({
+  props: { border: Boolean, stripe: Boolean, maxHeight: [String, Number], emptyText: String },
+  template: '<div class="table-stub" :data-border="String(border)" :data-stripe="String(stripe)" :data-max-height="String(maxHeight)" :data-empty-text="emptyText"><slot /></div>',
+  methods: { doLayout() {} },
+})
+const ColumnStub = defineComponent({
+  inheritAttrs: false,
+  props: { label: String, prop: String, fixed: [String, Boolean], showOverflowTooltip: Boolean, className: String },
+  template: '<div class="column-stub" :data-label="label" :data-prop="prop" :data-fixed="String(fixed || \'\')" :data-overflow-tooltip="String(showOverflowTooltip)" :data-class-name="className"><slot /></div>',
+})
+const ButtonStub = defineComponent({ template: '<button type="button"><slot /></button>' })
+const PopoverStub = defineComponent({ template: '<div><slot name="reference" /><slot /></div>' })
+
+const configurableColumns: DataTableColumn[] = [
+  { key: 'actions', label: '操作', fixed: 'left' },
+  { key: 'name', prop: 'name', label: '名称' },
+  { key: 'status', prop: 'status', label: '状态' },
+]
+
+function mountTable() {
+  return shallowMount(DataTable, {
+    props: { data: [], columns: configurableColumns, preferenceKey: 'orders-table', columnSettingsMode: 'show' },
+    global: {
+      provide: { [UI_PREFERENCE_SCOPE as symbol]: computed(() => 'user-1') },
+      stubs: {
+        ElTable: TableStub,
+        ElTableColumn: ColumnStub,
+        ElButton: ButtonStub,
+        ElPopover: PopoverStub,
+      },
+      directives: { loading: {} },
+    },
+  })
+}
+
+describe('DataTable pagination helpers', () => {
+  it('normalizes page-size options', () => {
+    expect(normalizePageSizes([20, 10, 20, 0, -1, 0.8, 10.8])).toEqual([20, 10])
+    expect(normalizePageSizes([])).toEqual([10])
+  })
+
+  it('keeps the page inside the available range', () => {
+    expect(normalizePage(0, 8)).toBe(1)
+    expect(normalizePage(12, 8)).toBe(8)
+    expect(normalizePage(3.8, 8)).toBe(3)
+    expect(normalizePage(Number.NaN, 8)).toBe(1)
+    expect(normalizePage(4, 0)).toBe(1)
+    expect(normalizePage(4, Number.NaN)).toBe(1)
+  })
+
+  it('does not create page buttons for an empty result', () => {
+    expect(createPaginationItems(1, 0)).toEqual([])
+  })
+
+  it('normalizes totals serialized as JSON strings before calculating pages', () => {
+    expect(normalizeTotal('30')).toBe(30)
+    expect(normalizeTotal(' 30 ')).toBe(30)
+    expect(normalizeTotal(30)).toBe(30)
+    expect(normalizeTotal('')).toBe(0)
+    expect(normalizeTotal('invalid')).toBe(0)
+  })
+
+  it('renders page navigation when the API total is a numeric string', () => {
+    const wrapper = shallowMount(DataTable, {
+      props: { data: [], columns: configurableColumns, total: '30', page: 1, pageSize: 20 },
+      global: {
+        stubs: { ElTable: TableStub, ElTableColumn: ColumnStub, ElButton: ButtonStub, ElPopover: PopoverStub },
+        directives: { loading: {} },
+      },
+    })
+
+    expect(wrapper.get('.data-table__page-buttons').text()).toContain('1')
+    expect(wrapper.get('.data-table__page-buttons').text()).toContain('2')
+  })
+
+  it('shows all pages for a short result set', () => {
+    expect(createPaginationItems(3, 5)).toEqual([1, 2, 3, 4, 5])
+  })
+
+  it('keeps first and last pages visible for long result sets', () => {
+    expect(createPaginationItems(1, 30)).toEqual([1, 2, 3, 4, 5, 'ellipsis-end', 30])
+    expect(createPaginationItems(15, 30)).toEqual([1, 'ellipsis-start', 14, 15, 16, 'ellipsis-end', 30])
+    expect(createPaginationItems(30, 30)).toEqual([1, 'ellipsis-start', 26, 27, 28, 29, 30])
+  })
+})
+
+describe('DataTable column preferences', () => {
+  beforeEach(() => localStorage.clear())
+
+  it('enables bordered striped business tables by default and allows explicit opt-out', () => {
+    const defaultTable = shallowMount(DataTable, {
+      props: { data: [], columns: configurableColumns },
+      global: {
+        stubs: { ElTable: TableStub, ElTableColumn: ColumnStub, ElButton: ButtonStub, ElPopover: PopoverStub },
+        directives: { loading: {} },
+      },
+    })
+    expect(defaultTable.get('.table-stub').attributes()).toMatchObject({ 'data-border': 'true', 'data-stripe': 'true' })
+
+    const plainTable = shallowMount(DataTable, {
+      props: { data: [], columns: configurableColumns, border: false, stripe: false },
+      global: {
+        stubs: { ElTable: TableStub, ElTableColumn: ColumnStub, ElButton: ButtonStub, ElPopover: PopoverStub },
+        directives: { loading: {} },
+      },
+    })
+    expect(plainTable.get('.table-stub').attributes()).toMatchObject({ 'data-border': 'false', 'data-stripe': 'false' })
+  })
+
+  it('keeps table bodies within the viewport by default and allows a custom height', () => {
+    const defaultTable = mountTable()
+    expect(defaultTable.get('.table-stub').attributes('data-max-height')).toBe('calc(100vh - 300px)')
+
+    const customTable = shallowMount(DataTable, {
+      props: { data: [], columns: configurableColumns, maxHeight: 420 },
+      global: {
+        stubs: { ElTable: TableStub, ElTableColumn: ColumnStub, ElButton: ButtonStub, ElPopover: PopoverStub },
+        directives: { loading: {} },
+      },
+    })
+    expect(customTable.get('.table-stub').attributes('data-max-height')).toBe('420')
+  })
+
+  it('keeps fixed actions, long text, empty state, and pagination in the shared list contract', () => {
+    const wrapper = shallowMount(DataTable, {
+      props: {
+        data: [],
+        columns: [
+          { key: 'actions', label: '操作', fixed: 'left', slotName: 'actions' },
+          { key: 'description', label: '长文本', showOverflowTooltip: true },
+        ],
+        emptyText: '暂无符合条件的数据',
+        total: 0,
+      },
+      global: {
+        stubs: { ElTable: TableStub, ElTableColumn: ColumnStub, ElButton: ButtonStub, ElPopover: PopoverStub },
+        directives: { loading: {} },
+      },
+    })
+
+    const columns = wrapper.findAll('.column-stub')
+    expect(columns[0].attributes('data-fixed')).toBe('left')
+    expect(columns[1].attributes('data-overflow-tooltip')).toBe('true')
+    expect(wrapper.get('.table-stub').attributes('data-empty-text')).toBe('暂无符合条件的数据')
+    expect(wrapper.get('.data-table__pagination').text()).toContain('共 0 条')
+  })
+
+  it('keeps ordinary cells on one line with overflow tooltips and exempts system columns', () => {
+    const wrapper = shallowMount(DataTable, {
+      props: {
+        data: [],
+        columnSettingsMode: 'hide',
+        columns: [
+          { key: 'actions', label: '操作', fixed: 'left', slotName: 'actions' },
+          { key: 'customerName', label: '客户' },
+          { key: 'remark', label: '备注', singleLine: false },
+        ],
+      },
+      global: {
+        stubs: { ElTable: TableStub, ElTableColumn: ColumnStub, ElButton: ButtonStub, ElPopover: PopoverStub, ElSelect: true, ElOption: true },
+        directives: { loading: {} },
+      },
+    })
+
+    const columns = wrapper.findAll('.column-stub')
+    expect(columns[0].attributes()).toMatchObject({
+      'data-overflow-tooltip': 'undefined',
+      'data-class-name': 'data-table__system-cell',
+    })
+    expect(columns[1].attributes()).toMatchObject({
+      'data-overflow-tooltip': 'true',
+      'data-class-name': 'data-table__single-line-cell',
+    })
+    expect(columns[2].attributes('data-overflow-tooltip')).toBe('undefined')
+    expect(columns[2].attributes('data-class-name')).toBe('')
+  })
+
+  it('uses key as the data property for ordinary columns only', () => {
+    const wrapper = shallowMount(DataTable, {
+      props: {
+        data: [{ customerName: '客户A', explicitName: '显式字段' }],
+        columns: [
+          { key: 'actions', label: '操作', slotName: 'actions' },
+          { key: 'customerName', label: '客户' },
+          { key: 'name', prop: 'explicitName', label: '显式字段' },
+          { key: 'selection', type: 'selection', label: '选择' },
+        ],
+      },
+      global: {
+        stubs: { ElTable: TableStub, ElTableColumn: ColumnStub, ElButton: ButtonStub, ElPopover: PopoverStub },
+        directives: { loading: {} },
+      },
+    })
+
+    const columns = wrapper.findAll('.column-stub')
+    expect(columns.map((column) => column.attributes('data-prop'))).toEqual([undefined, 'customerName', 'explicitName', undefined])
+  })
+
+  it('restores column order and visibility while locking the actions column', async () => {
+    localStorage.setItem(preferenceStorageKey('table', 'user-1', 'orders-table'), JSON.stringify({
+      version: 1,
+      order: ['status', 'name', 'actions'],
+      hidden: ['name', 'actions'],
+    }))
+    const wrapper = mountTable()
+    expect(wrapper.findAll('.column-stub').map((column) => column.attributes('data-label'))).toEqual(['操作', '状态'])
+
+    const settings = wrapper.findComponent(LayoutPreferenceList)
+    const items = settings.props('items') as Array<{ key: string; movable: boolean; hideable: boolean }>
+    expect(items.find((item) => item.key === 'actions')).toMatchObject({ movable: false, hideable: false })
+
+    settings.vm.$emit('visibility', 'name', true)
+    settings.vm.$emit('move', 'name', 0)
+    await wrapper.vm.$nextTick()
+    expect(wrapper.findAll('.column-stub').map((column) => column.attributes('data-label'))).toEqual(['操作', '名称', '状态'])
+  })
+
+  it('keeps a newly introduced default-hidden column hidden for an existing preference', () => {
+    localStorage.setItem(preferenceStorageKey('table', 'user-1', 'orders-table'), JSON.stringify({
+      version: 1,
+      order: ['actions', 'name', 'status'],
+      hidden: [],
+    }))
+    const wrapper = shallowMount(DataTable, {
+      props: {
+        data: [],
+        columns: [...configurableColumns, { key: 'internalCode', label: '内部编码', defaultVisible: false }],
+        preferenceKey: 'orders-table',
+        columnSettingsMode: 'show',
+      },
+      global: {
+        provide: { [UI_PREFERENCE_SCOPE as symbol]: computed(() => 'user-1') },
+        stubs: { ElTable: TableStub, ElTableColumn: ColumnStub, ElButton: ButtonStub, ElPopover: PopoverStub },
+        directives: { loading: {} },
+      },
+    })
+
+    expect(wrapper.findAll('.column-stub').map((column) => column.attributes('data-label'))).toEqual(['操作', '名称', '状态'])
+  })
+
+  it('keeps business actions, column settings, and trailing controls in one toolbar', () => {
+    const wrapper = shallowMount(DataTable, {
+      props: { data: [], columns: configurableColumns, preferenceKey: 'orders-table', columnSettingsMode: 'show' },
+      slots: {
+        'toolbar-start': '<h2>订单列表</h2>',
+        'toolbar-actions': '<button>新增订单</button>',
+        'toolbar-end': '<button>辅助操作</button>',
+      },
+      global: {
+        provide: { [UI_PREFERENCE_SCOPE as symbol]: computed(() => 'user-1') },
+        stubs: {
+          ElTable: TableStub,
+          ElTableColumn: ColumnStub,
+          ElButton: ButtonStub,
+          ElPopover: PopoverStub,
+        },
+        directives: { loading: {} },
+      },
+    })
+
+    expect(wrapper.findAll('.data-table__toolbar')).toHaveLength(1)
+    expect(wrapper.get('.data-table__toolbar').classes()).not.toContain('is-compact')
+    expect(wrapper.get('.data-table__toolbar-start').text()).toBe('订单列表')
+    expect(wrapper.get('.data-table__toolbar-actions').text()).toContain('新增订单')
+    expect(wrapper.get('.data-table__toolbar-actions').text()).toContain('辅助操作')
+    expect(wrapper.get('.data-table__business-actions').text()).toBe('新增订单')
+    expect(wrapper.get('.data-table__utility-actions').text()).toContain('辅助操作')
+    expect(wrapper.get('.data-table__toolbar-end').text()).toBe('辅助操作')
+  })
+
+  it('uses a compact right-aligned toolbar when no leading content is provided', () => {
+    const wrapper = shallowMount(DataTable, {
+      props: { data: [], columns: configurableColumns, preferenceKey: 'orders-table', columnSettingsMode: 'show' },
+      slots: { 'toolbar-actions': '<button>新增订单</button>' },
+      global: {
+        provide: { [UI_PREFERENCE_SCOPE as symbol]: computed(() => 'user-1') },
+        stubs: {
+          ElTable: TableStub,
+          ElTableColumn: ColumnStub,
+          ElButton: ButtonStub,
+          ElPopover: PopoverStub,
+        },
+        directives: { loading: {} },
+      },
+    })
+
+    expect(wrapper.get('.data-table__toolbar').classes()).toContain('is-compact')
+    expect(wrapper.find('.data-table__toolbar-start').exists()).toBe(false)
+    expect(wrapper.get('.data-table__toolbar-actions').classes()).toContain('has-business-actions')
+    expect(wrapper.get('.data-table__business-actions').text()).toBe('新增订单')
+  })
+
+  it('keeps business actions in a separate mobile-wrappable group from column settings', () => {
+    const wrapper = shallowMount(DataTable, {
+      props: { data: [], columns: configurableColumns, preferenceKey: 'orders-table', columnSettingsMode: 'show' },
+      slots: { 'toolbar-actions': '<button class="create-action">新增快递公司</button>' },
+      global: {
+        provide: { [UI_PREFERENCE_SCOPE as symbol]: computed(() => 'user-1') },
+        stubs: {
+          ElTable: TableStub,
+          ElTableColumn: ColumnStub,
+          ElButton: ButtonStub,
+          ElPopover: PopoverStub,
+        },
+        directives: { loading: {} },
+      },
+    })
+    const toolbarActions = wrapper.get('.data-table__toolbar-actions')
+    const businessActions = toolbarActions.get('.data-table__business-actions')
+
+    expect(toolbarActions.classes()).toContain('has-business-actions')
+    expect(businessActions.get('.create-action').text()).toBe('新增快递公司')
+    expect(toolbarActions.find('.data-table__utility-actions').exists()).toBe(true)
+    expect(toolbarActions.find('button[aria-label="列设置"]').exists()).toBe(true)
+  })
+
+  it('can hide column settings for compact tables without leaving an empty toolbar', () => {
+    const wrapper = shallowMount(DataTable, {
+      props: { data: [], columns: configurableColumns, preferenceKey: 'summary-table', columnSettingsMode: 'hide' },
+      global: {
+        provide: { [UI_PREFERENCE_SCOPE as symbol]: computed(() => 'user-1') },
+        stubs: { ElTable: TableStub, ElTableColumn: ColumnStub, ElButton: ButtonStub, ElPopover: PopoverStub },
+        directives: { loading: {} },
+      },
+    })
+
+    expect(wrapper.find('button[aria-label="列设置"]').exists()).toBe(false)
+    expect(wrapper.find('.data-table__toolbar').exists()).toBe(false)
+  })
+
+  it('shows every column when column settings are hidden', () => {
+    localStorage.setItem('cc:ui-layout:user-1:table:summary-table', JSON.stringify({
+      version: 1,
+      order: configurableColumns.map((column) => String(column.key)),
+      hidden: ['status'],
+    }))
+    const wrapper = shallowMount(DataTable, {
+      props: { data: [], columns: configurableColumns, preferenceKey: 'summary-table', columnSettingsMode: 'hide' },
+      global: {
+        provide: { [UI_PREFERENCE_SCOPE as symbol]: computed(() => 'user-1') },
+        stubs: { ElTable: TableStub, ElTableColumn: ColumnStub, ElButton: ButtonStub, ElPopover: PopoverStub },
+        directives: { loading: {} },
+      },
+    })
+
+    expect(wrapper.findAllComponents(ColumnStub)).toHaveLength(configurableColumns.length)
+  })
+
+  it('hides column settings by default for four or fewer configurable business columns', () => {
+    const wrapper = shallowMount(DataTable, {
+      props: { data: [], columns: configurableColumns, preferenceKey: 'compact-table' },
+      global: {
+        provide: { [UI_PREFERENCE_SCOPE as symbol]: computed(() => 'user-1') },
+        stubs: { ElTable: TableStub, ElTableColumn: ColumnStub, ElButton: ButtonStub, ElPopover: PopoverStub },
+        directives: { loading: {} },
+      },
+    })
+
+    expect(wrapper.find('button[aria-label="列设置"]').exists()).toBe(false)
+    expect(wrapper.find('.data-table__toolbar').exists()).toBe(false)
+  })
+
+  it('keeps column settings by default for complex tables', () => {
+    const complexColumns: DataTableColumn[] = [
+      { key: 'actions', label: '操作' },
+      ...Array.from({ length: 5 }, (_, index) => ({ key: `field-${index}`, label: `字段 ${index + 1}` })),
+    ]
+    const wrapper = shallowMount(DataTable, {
+      props: { data: [], columns: complexColumns, preferenceKey: 'complex-table' },
+      global: {
+        provide: { [UI_PREFERENCE_SCOPE as symbol]: computed(() => 'user-1') },
+        stubs: { ElTable: TableStub, ElTableColumn: ColumnStub, ElButton: ButtonStub, ElPopover: PopoverStub },
+        directives: { loading: {} },
+      },
+    })
+
+    expect(wrapper.find('button[aria-label="列设置"]').exists()).toBe(true)
+  })
+})
diff --git a/src/shared/components/DataTable.vue b/src/shared/components/DataTable.vue
new file mode 100644
index 00000000..fd23c201
--- /dev/null
+++ b/src/shared/components/DataTable.vue
@@ -0,0 +1,423 @@
+<script lang="ts">
+export interface DataTableColumn {
+  key?: string | number
+  label?: string
+  prop?: string
+  property?: string
+  columnKey?: string
+  slotName?: string
+  headerSlotName?: string
+  hideable?: boolean
+  movable?: boolean
+  defaultVisible?: boolean
+  singleLine?: boolean
+  showOverflowTooltip?: boolean
+  className?: string
+  [attribute: string]: unknown
+}
+
+export type PaginationItem = number | 'ellipsis-start' | 'ellipsis-end'
+
+export function normalizePageSizes(values: readonly number[]) {
+  const sizes = values
+    .filter((value) => Number.isFinite(value))
+    .map((value) => Math.trunc(value))
+    .filter((value) => value > 0)
+  const uniqueSizes = [...new Set(sizes)]
+  return uniqueSizes.length > 0 ? uniqueSizes : [10]
+}
+
+export function normalizePage(value: number, pageCount: number) {
+  const maximum = Number.isFinite(pageCount) && pageCount > 0 ? Math.trunc(pageCount) : 1
+  if (!Number.isFinite(value)) return 1
+  return Math.min(Math.max(Math.trunc(value), 1), maximum)
+}
+
+export function normalizeTotal(value: unknown) {
+  const numericValue = typeof value === 'string' && value.trim() !== '' ? Number(value) : value
+  return typeof numericValue === 'number' && Number.isFinite(numericValue) && numericValue > 0
+    ? Math.trunc(numericValue)
+    : 0
+}
+
+export function createPaginationItems(page: number, pageCount: number): PaginationItem[] {
+  if (pageCount <= 0) return []
+  if (pageCount <= 7) return Array.from({ length: pageCount }, (_, index) => index + 1)
+  if (page <= 4) return [1, 2, 3, 4, 5, 'ellipsis-end', pageCount]
+  if (page >= pageCount - 3) {
+    return [1, 'ellipsis-start', pageCount - 4, pageCount - 3, pageCount - 2, pageCount - 1, pageCount]
+  }
+  return [1, 'ellipsis-start', page - 1, page, page + 1, 'ellipsis-end', pageCount]
+}
+</script>
+
+<script setup lang="ts">
+import { computed, inject, nextTick, ref, useSlots, watch } from 'vue'
+import { ChevronLeft, ChevronRight, Settings2 } from '@lucide/vue'
+import LayoutPreferenceList, { type LayoutPreferenceItem } from './LayoutPreferenceList.vue'
+import {
+  UI_PREFERENCE_SCOPE,
+  readLayoutPreference,
+  removeLayoutPreference,
+  writeLayoutPreference,
+  type LayoutPreferenceSnapshot,
+} from '@/shared/utils/uiLayoutPreference'
+
+defineOptions({ inheritAttrs: false })
+
+const props = withDefaults(defineProps<{
+  data: object[]
+  columns: DataTableColumn[]
+  loading?: boolean
+  emptyText?: string
+  total?: number | string
+  pageSizes?: number[]
+  maxHeight?: string | number
+  preferenceKey?: string
+  columnSettingsMode?: 'auto' | 'show' | 'hide'
+  border?: boolean
+  stripe?: boolean
+}>(), {
+  loading: false,
+  emptyText: '暂无数据',
+  total: undefined,
+  pageSizes: () => [10, 20, 50, 100],
+  maxHeight: 'calc(100vh - 300px)',
+  columnSettingsMode: 'auto',
+  border: true,
+  stripe: true,
+})
+
+const page = defineModel<number>('page', { default: 1 })
+const pageSize = defineModel<number>('pageSize', { default: 10 })
+const slots = useSlots()
+const preferenceScope = inject(UI_PREFERENCE_SCOPE, computed(() => 'anonymous'))
+const preference = ref<LayoutPreferenceSnapshot>({ version: 1, order: [], hidden: [] })
+const tableRef = ref<{ doLayout: () => void }>()
+
+function columnId(column: DataTableColumn) {
+  const value = column.key ?? column.columnKey ?? column.prop ?? column.property
+  return value === undefined || value === null || value === '' ? undefined : String(value)
+}
+
+function systemColumn(column: DataTableColumn) {
+  const id = columnId(column)
+  return id === 'actions'
+    || column.fixed === 'left'
+    || ['selection', 'expand', 'index'].includes(String(column.type || ''))
+}
+
+function columnMovable(column: DataTableColumn) {
+  return column.movable ?? !systemColumn(column)
+}
+
+function columnHideable(column: DataTableColumn) {
+  return column.hideable ?? !systemColumn(column)
+}
+
+const configurableColumns = computed(() => props.columns.filter((column) => columnId(column)))
+const columnKeys = computed(() => configurableColumns.value.map((column) => columnId(column) as string))
+const columnSettingsVisible = computed(() => (
+  props.columnSettingsMode === 'auto'
+    ? configurableColumns.value.filter(columnHideable).length > 4
+    : props.columnSettingsMode === 'show'
+))
+const preferenceEnabled = computed(() => Boolean(props.preferenceKey && columnSettingsVisible.value))
+
+function anchorSystemColumns(order: readonly string[]) {
+  const columnsByKey = new Map(configurableColumns.value.map((column) => [columnId(column) as string, column]))
+  const movableKeys = order.filter((key) => {
+    const column = columnsByKey.get(key)
+    return column && columnMovable(column)
+  })
+  let movableIndex = 0
+  return configurableColumns.value.map((column) => (
+    columnMovable(column) ? movableKeys[movableIndex++] : columnId(column) as string
+  ))
+}
+
+function applyPreference() {
+  const defaultHidden = configurableColumns.value.flatMap((column) => column.defaultVisible === false ? [columnId(column) as string] : [])
+  const snapshot = readLayoutPreference(
+    'table',
+    preferenceScope.value,
+    props.preferenceKey || '',
+    columnKeys.value,
+    defaultHidden,
+  )
+  preference.value = { ...snapshot, order: anchorSystemColumns(snapshot.order) }
+}
+
+watch(
+  [preferenceScope, () => props.preferenceKey, () => columnKeys.value.join('\u0000')],
+  applyPreference,
+  { immediate: true },
+)
+
+const orderedColumns = computed(() => {
+  if (!preferenceEnabled.value) return props.columns
+  const columnsByKey = new Map(configurableColumns.value.map((column) => [columnId(column) as string, column]))
+  return preference.value.order.flatMap((key) => {
+    const column = columnsByKey.get(key)
+    return column ? [column] : []
+  })
+})
+const visibleColumns = computed(() => orderedColumns.value.filter((column) => {
+  const id = columnId(column)
+  return !preferenceEnabled.value || !id || !columnHideable(column) || !preference.value.hidden.includes(id)
+}))
+const visibleHideableCount = computed(() => visibleColumns.value.filter(columnHideable).length)
+const preferenceItems = computed<LayoutPreferenceItem[]>(() => orderedColumns.value.flatMap((column) => {
+  const key = columnId(column)
+  if (!key) return []
+  const visible = !preference.value.hidden.includes(key)
+  const hideable = columnHideable(column)
+  return [{
+    key,
+    label: column.label || (String(column.type || '') === 'selection' ? '选择' : key),
+    visible,
+    hideable,
+    movable: columnMovable(column),
+    hideDisabled: visible && hideable && visibleHideableCount.value <= 1,
+  }]
+}))
+
+function persistPreference(order: string[], hidden = preference.value.hidden) {
+  preference.value = { version: 1, order, hidden }
+  writeLayoutPreference('table', preferenceScope.value, props.preferenceKey || '', preference.value)
+}
+
+function moveColumn(key: string, targetIndex: number) {
+  const movableKeys = orderedColumns.value.filter(columnMovable).map((column) => columnId(column) as string)
+  const currentIndex = movableKeys.indexOf(key)
+  if (currentIndex < 0) return
+  movableKeys.splice(currentIndex, 1)
+  movableKeys.splice(Math.min(Math.max(targetIndex, 0), movableKeys.length), 0, key)
+  const movableSet = new Set(movableKeys)
+  let nextMovableIndex = 0
+  const order = orderedColumns.value.map((column) => {
+    const id = columnId(column) as string
+    return movableSet.has(id) ? movableKeys[nextMovableIndex++] : id
+  })
+  persistPreference(order)
+}
+
+function setColumnVisibility(key: string, visible: boolean) {
+  const column = configurableColumns.value.find((candidate) => columnId(candidate) === key)
+  if (!column || !columnHideable(column)) return
+  if (!visible && visibleHideableCount.value <= 1) return
+  const hidden = visible
+    ? preference.value.hidden.filter((id) => id !== key)
+    : [...new Set([...preference.value.hidden, key])]
+  persistPreference(preference.value.order, hidden)
+}
+
+function resetPreference() {
+  removeLayoutPreference('table', preferenceScope.value, props.preferenceKey || '')
+  applyPreference()
+}
+
+watch(visibleColumns, () => {
+  void nextTick(() => tableRef.value?.doLayout())
+})
+const normalizedTotal = computed(() => normalizeTotal(props.total))
+const normalizedPageSizes = computed(() => normalizePageSizes(props.pageSizes))
+const effectivePageSize = computed(() => (
+  normalizedPageSizes.value.includes(pageSize.value) ? pageSize.value : normalizedPageSizes.value[0]
+))
+const pageCount = computed(() => (
+  normalizedTotal.value === 0 ? 0 : Math.ceil(normalizedTotal.value / effectivePageSize.value)
+))
+const currentPage = computed(() => normalizePage(page.value, pageCount.value))
+const paginationItems = computed(() => createPaginationItems(currentPage.value, pageCount.value))
+
+watch([pageSize, normalizedPageSizes], ([value, sizes]) => {
+  const integerValue = Number.isFinite(value) ? Math.trunc(value) : sizes[0]
+  const nextValue = sizes.includes(integerValue) ? integerValue : sizes[0]
+  if (value === nextValue) return
+  pageSize.value = nextValue
+  page.value = 1
+}, { immediate: true })
+
+watch([page, pageCount], ([value, count]) => {
+  const nextValue = normalizePage(value, count)
+  if (value !== nextValue) page.value = nextValue
+}, { immediate: true })
+
+function columnAttrs({ key, slotName, headerSlotName, hideable, movable, defaultVisible, singleLine, ...attrs }: DataTableColumn) {
+  const hasDataProperty = attrs.prop !== undefined || attrs.property !== undefined
+  const isSpecialColumn = slotName || ['selection', 'expand', 'index'].includes(String(attrs.type || ''))
+  if (hasDataProperty || isSpecialColumn || key === undefined || key === null || key === '') return attrs
+  const label = String(attrs.label || '')
+  return {
+    ...attrs,
+    prop: String(key),
+    formatter: attrs.formatter || ((_row: unknown, _column: unknown, value: unknown) => {
+      if (value === null || value === undefined || value === '') return '—'
+      if (typeof value === 'number' && /CNY|金额|应收|应付|已收|已付|未收|待收|待付|开账/.test(label)) return value.toFixed(2)
+      return String(value)
+    }),
+  }
+}
+
+function singleLineColumn(column: DataTableColumn) {
+  return column.singleLine !== false && !systemColumn(column)
+}
+
+function columnOverflowTooltip(column: DataTableColumn) {
+  return singleLineColumn(column) ? column.showOverflowTooltip ?? true : column.showOverflowTooltip
+}
+
+function columnClassName(column: DataTableColumn) {
+  return [
+    column.className,
+    systemColumn(column) ? 'data-table__system-cell' : '',
+    singleLineColumn(column) ? 'data-table__single-line-cell' : '',
+  ].filter(Boolean).join(' ')
+}
+
+function columnRenderKey(column: DataTableColumn, index: number) {
+  return String(column.key ?? column.columnKey ?? column.prop ?? column.property ?? index)
+}
+
+function hasSlot(name?: string) {
+  return Boolean(name && slots[name])
+}
+
+function updatePageSize(value: number) {
+  const nextValue = normalizedPageSizes.value.includes(value) ? value : normalizedPageSizes.value[0]
+  if (nextValue === pageSize.value) return
+  pageSize.value = nextValue
+  page.value = 1
+}
+
+function setPage(value: number) {
+  page.value = normalizePage(value, pageCount.value)
+}
+</script>
+
+<template>
+  <div class="data-table">
+    <div
+      v-if="$slots['toolbar-start'] || $slots['toolbar-actions'] || preferenceEnabled || $slots['toolbar-end']"
+      class="data-table__toolbar"
+      :class="{ 'is-compact': !$slots['toolbar-start'] }"
+    >
+      <div v-if="$slots['toolbar-start']" class="data-table__toolbar-start"><slot name="toolbar-start" /></div>
+      <div class="data-table__toolbar-actions" :class="{ 'has-business-actions': $slots['toolbar-actions'] }">
+        <div v-if="$slots['toolbar-actions']" class="data-table__business-actions"><slot name="toolbar-actions" /></div>
+        <div v-if="preferenceEnabled || $slots['toolbar-end']" class="data-table__utility-actions">
+          <el-popover v-if="preferenceEnabled" placement="bottom-end" :width="340" trigger="click" popper-class="cc-layout-preference-popper">
+            <template #reference>
+              <el-button aria-label="列设置" title="列设置"><Settings2 :size="16" /></el-button>
+            </template>
+            <LayoutPreferenceList
+              :items="preferenceItems"
+              allow-visibility
+              @move="moveColumn"
+              @visibility="setColumnVisibility"
+              @reset="resetPreference"
+            />
+          </el-popover>
+          <div v-if="$slots['toolbar-end']" class="data-table__toolbar-end"><slot name="toolbar-end" /></div>
+        </div>
+      </div>
+    </div>
+    <el-table ref="tableRef" v-bind="$attrs" v-loading="loading" :data="data" :empty-text="emptyText" :border="border" :stripe="stripe" :max-height="maxHeight" :aria-busy="loading">
+      <el-table-column
+        v-for="(column, index) in visibleColumns"
+        :key="columnRenderKey(column, index)"
+        v-bind="columnAttrs(column)"
+        :class-name="columnClassName(column)"
+        :show-overflow-tooltip="columnOverflowTooltip(column)"
+      >
+        <template v-if="hasSlot(column.headerSlotName)" #header="scope">
+          <slot :name="column.headerSlotName" v-bind="scope" />
+        </template>
+        <template v-if="hasSlot(column.slotName)" #default="scope">
+          <slot :name="column.slotName" v-bind="scope" />
+        </template>
+      </el-table-column>
+      <template v-if="$slots.empty" #empty><slot name="empty" /></template>
+    </el-table>
+    <footer v-if="total !== undefined" class="data-table__pagination" aria-label="表格分页">
+      <div class="data-table__pagination-left">
+        <slot name="pagination-left" :total="normalizedTotal" :page="currentPage" :page-size="effectivePageSize" :page-count="pageCount">
+          <span v-if="pageCount > 0">共 {{ normalizedTotal }} 条 · 第 {{ currentPage }} / {{ pageCount }} 页</span>
+          <span v-else>共 0 条</span>
+        </slot>
+      </div>
+      <div class="data-table__pagination-controls">
+        <label class="data-table__page-size">
+          <span>每页</span>
+          <el-select :model-value="effectivePageSize" :disabled="loading" aria-label="每页条数" @update:model-value="updatePageSize">
+            <el-option v-for="size in normalizedPageSizes" :key="size" :label="String(size)" :value="size" />
+          </el-select>
+          <span>条</span>
+        </label>
+        <nav v-if="pageCount > 0" class="data-table__page-buttons" aria-label="页码">
+          <el-button class="data-table__page-button" :disabled="loading || currentPage <= 1" aria-label="上一页" title="上一页" @click="setPage(currentPage - 1)"><ChevronLeft :size="16" /></el-button>
+          <template v-for="item in paginationItems" :key="item">
+            <span v-if="typeof item !== 'number'" class="data-table__page-ellipsis" aria-hidden="true">...</span>
+            <el-button
+              v-else
+              class="data-table__page-button"
+              :type="item === currentPage ? 'primary' : undefined"
+              :disabled="loading"
+              :aria-current="item === currentPage ? 'page' : undefined"
+              :aria-label="`第 ${item} 页`"
+              :title="`第 ${item} 页`"
+              @click="setPage(item)"
+            >{{ item }}</el-button>
+          </template>
+          <el-button class="data-table__page-button" :disabled="loading || currentPage >= pageCount" aria-label="下一页" title="下一页" @click="setPage(currentPage + 1)"><ChevronRight :size="16" /></el-button>
+        </nav>
+      </div>
+    </footer>
+  </div>
+</template>
+
+<style scoped>
+.data-table { min-width: 0; }
+.data-table :deep(.el-table) { font-size: var(--cc-list-table-font-size); }
+.data-table :deep(.el-table th.el-table__cell) { font-size: var(--cc-list-table-font-size); font-weight: var(--cc-list-table-header-font-weight); }
+.data-table :deep(.el-table .el-button) { font-size: var(--cc-list-action-font-size); }
+.data-table :deep(.el-table__empty-text) { font-size: var(--cc-list-table-font-size); }
+.data-table__toolbar { display: flex; min-height: 44px; align-items: center; justify-content: space-between; gap: var(--admin-space-5, 12px); padding: var(--admin-space-2, 6px) var(--admin-space-5, 12px); border-bottom: 1px solid var(--cc-border); }
+.data-table__toolbar.is-compact { justify-content: flex-end; }
+.data-table__toolbar-start { min-width: 0; flex: 1; }
+.data-table__toolbar-start :deep(h2) { margin: 0; color: var(--cc-text); font-size: 16px; line-height: 1.4; }
+.data-table__toolbar-start :deep(p) { margin: 4px 0 0; color: var(--cc-muted); font-size: 12px; line-height: 1.5; }
+.data-table__toolbar-actions { display: flex; flex: 0 0 auto; align-items: center; flex-wrap: wrap; justify-content: flex-end; gap: 8px; }
+.data-table__business-actions, .data-table__utility-actions, .data-table__toolbar-end { display: flex; min-width: 0; align-items: center; flex-wrap: wrap; justify-content: flex-end; gap: 8px; }
+.data-table__utility-actions { flex: 0 0 auto; }
+.data-table__toolbar-actions :deep(.el-button + .el-button) { margin-left: 0; }
+.data-table__pagination { display: flex; min-height: 58px; align-items: center; justify-content: space-between; gap: 16px; padding: 12px 18px; border-top: 1px solid var(--cc-border); color: var(--cc-muted); font-size: var(--cc-list-pagination-font-size); }
+.data-table__pagination-left { display: flex; min-width: 0; flex: 1; align-items: center; gap: 8px; }
+.data-table__pagination-controls, .data-table__page-size, .data-table__page-buttons { display: flex; align-items: center; gap: 8px; }
+.data-table__pagination-controls { min-width: 0; flex-wrap: wrap; justify-content: flex-end; }
+.data-table__page-size :deep(.el-select) { width: 82px; }
+.data-table__page-buttons { gap: 4px; }
+.data-table__page-button { width: 32px; min-width: 32px; height: 32px; padding: 0; margin-left: 0; font-size: var(--cc-list-page-button-font-size); }
+.data-table__page-ellipsis { display: inline-flex; width: 24px; height: 32px; align-items: center; justify-content: center; }
+.data-table :deep(.data-table__single-line-cell .cell) { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.data-table :deep(.data-table__system-cell .cell) { white-space: nowrap; }
+.data-table :deep(.data-table__system-cell .el-button + .el-button),
+.data-table :deep(.data-table__system-cell .el-button + .el-dropdown) { margin-left: var(--cc-list-action-sibling-margin, 8px); }
+
+@media (min-width: 1920px) {
+  .data-table__toolbar-actions,
+  .data-table__business-actions,
+  .data-table__utility-actions,
+  .data-table__toolbar-end { gap: 6px; }
+  .data-table__pagination { min-height: 52px; gap: 12px; padding: 10px 14px; }
+  .data-table__pagination-left,
+  .data-table__pagination-controls,
+  .data-table__page-size,
+  .data-table__page-buttons { gap: 6px; }
+  .data-table__page-button { width: 30px; min-width: 30px; height: 30px; }
+  .data-table__page-ellipsis { width: 22px; height: 30px; }
+}
+
+@media (max-width: 720px) { .data-table__toolbar, .data-table__toolbar.is-compact { min-height: 0; align-items: stretch; flex-direction: column; padding: 14px; } .data-table__toolbar-actions { width: 100%; align-items: flex-start; flex-wrap: wrap; justify-content: flex-start; } .data-table__toolbar-actions.has-business-actions { display: grid; grid-template-columns: minmax(0, 1fr) auto; } .data-table__business-actions { justify-content: flex-start; } .data-table__utility-actions { align-items: flex-start; justify-content: flex-end; } .data-table__toolbar-end { justify-content: flex-start; } .data-table__toolbar-actions :deep(.el-button) { max-width: 100%; min-height: 40px; } .data-table__pagination { align-items: flex-start; flex-direction: column; } .data-table__pagination-left, .data-table__pagination-controls, .data-table__page-buttons { width: 100%; } .data-table__pagination-controls { justify-content: flex-start; } .data-table__page-buttons { flex-wrap: wrap; } .data-table__page-button { width: 44px; min-width: 44px; height: 44px; } .data-table__page-ellipsis { height: 44px; } }
+</style>
diff --git a/src/shared/components/DetailPageLayout.vue b/src/shared/components/DetailPageLayout.vue
new file mode 100644
index 00000000..ffbb7f6a
--- /dev/null
+++ b/src/shared/components/DetailPageLayout.vue
@@ -0,0 +1,25 @@
+<script setup lang="ts">
+withDefaults(defineProps<{
+  ariaLabel?: string
+}>(), {
+  ariaLabel: '详情页面',
+})
+</script>
+
+<template>
+  <article class="detail-page-layout" :aria-label="ariaLabel">
+    <header v-if="$slots.header" class="detail-page-layout__header"><slot name="header" /></header>
+    <div v-if="$slots.summary" class="detail-page-layout__summary"><slot name="summary" /></div>
+    <div class="detail-page-layout__content"><slot /></div>
+    <footer v-if="$slots.footer" class="detail-page-layout__footer"><slot name="footer" /></footer>
+  </article>
+</template>
+
+<style scoped>
+.detail-page-layout { display: flex; min-width: 0; flex-direction: column; gap: 16px; }
+.detail-page-layout__header, .detail-page-layout__summary, .detail-page-layout__content, .detail-page-layout__footer { min-width: 0; }
+
+@media (min-width: 1920px) {
+  .detail-page-layout { gap: 12px; }
+}
+</style>
diff --git a/src/shared/components/FormSection.vue b/src/shared/components/FormSection.vue
new file mode 100644
index 00000000..17830bdb
--- /dev/null
+++ b/src/shared/components/FormSection.vue
@@ -0,0 +1,37 @@
+<script setup lang="ts">
+withDefaults(defineProps<{
+  title: string
+  description?: string
+  bordered?: boolean
+}>(), {
+  description: '',
+  bordered: true,
+})
+</script>
+
+<template>
+  <section class="form-section" :class="{ 'is-bordered': bordered }">
+    <div class="form-section__heading">
+      <h2>{{ title }}</h2>
+      <p v-if="description">{{ description }}</p>
+    </div>
+    <div class="form-section__content"><slot /></div>
+  </section>
+</template>
+
+<style scoped>
+.form-section { min-width: 0; padding: 20px 0; }
+.form-section.is-bordered { border-bottom: 1px solid var(--cc-border, #e3e8ef); }
+.form-section:first-child { padding-top: 0; }
+.form-section:last-child { padding-bottom: 0; border-bottom: 0; }
+.form-section__heading { margin-bottom: 16px; }
+.form-section__heading h2 { margin: 0; color: var(--cc-text, #172033); font-size: 14px; line-height: 1.4; }
+.form-section__heading p { margin: 4px 0 0; color: var(--cc-muted, #667085); font-size: 12px; line-height: 1.5; }
+
+@media (min-width: 1920px) {
+  .form-section { padding: 14px 0; }
+  .form-section:first-child { padding-top: 0; }
+  .form-section:last-child { padding-bottom: 0; }
+  .form-section__heading { margin-bottom: 10px; }
+}
+</style>
diff --git a/src/shared/components/InboundCodeRelationshipDialog.test.ts b/src/shared/components/InboundCodeRelationshipDialog.test.ts
new file mode 100644
index 00000000..1ca7373e
--- /dev/null
+++ b/src/shared/components/InboundCodeRelationshipDialog.test.ts
@@ -0,0 +1,243 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { defineComponent } from 'vue'
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import ElementPlus from 'element-plus'
+import {
+  getLoadingAssociationSummary,
+  getOverseasInboundCodeRelationship,
+  getPlatformInboundCodeAssociation,
+} from '@/shared/api/inboundCodeRelations'
+import InboundCodeRelationshipDialog from './InboundCodeRelationshipDialog.vue'
+
+vi.mock('@/shared/api/inboundCodeRelations', () => ({
+  getLoadingAssociationSummary: vi.fn(),
+  getOverseasInboundCodeRelationship: vi.fn(),
+  getPlatformInboundCodeAssociation: vi.fn(),
+}))
+
+const source = readFileSync(resolve(process.cwd(), 'src/shared/components/InboundCodeRelationshipDialog.vue'), 'utf8')
+const AppDialogStub = defineComponent({
+  props: { modelValue: Boolean, title: String, loading: Boolean },
+  emits: ['update:modelValue'],
+  template: '<aside><h2>{{ title }}</h2><slot /></aside>',
+})
+
+function mountDialog() {
+  return mount(InboundCodeRelationshipDialog, {
+    props: {
+      modelValue: true,
+      inboundCode: 'NYEXX2608300027',
+      canReadBase: true,
+      canReadLoading: true,
+      canReadOverseas: true,
+    },
+    global: {
+      stubs: {
+        AppDialog: AppDialogStub,
+        ApiErrorMeta: true,
+        LoadErrorState: { props: ['title', 'message'], template: '<div>{{ title }} · {{ message }}</div>' },
+        StatusBadge: true,
+        'el-alert': true,
+        'el-empty': { props: ['description'], template: '<p>{{ description }}</p>' },
+        'el-table': { props: ['data'], template: '<div>{{ data[0]?.skuCode }}<slot /></div>' },
+        'el-table-column': true,
+      },
+    },
+  })
+}
+
+describe('InboundCodeRelationshipDialog contract', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.mocked(getPlatformInboundCodeAssociation).mockResolvedValue({
+      inboundCode: 'NYEXX2608300027', orderNo: 'FL2093975748931063810', orderStatus: 'APPROVED',
+      orderId: '90071992547409931', customerId: '90071992547409932', customerName: '纽约客户',
+      destinationType: 'FBA', destinationWarehouseId: '90071992547409933', destinationWarehouseCode: 'ABE3', destinationWarehouseName: '亚马逊 ABE3 仓',
+    })
+    vi.mocked(getLoadingAssociationSummary).mockResolvedValue({
+      inboundId: '90071992547409934', inboundCode: 'NYEXX2608300027', orderNo: 'FL2093975748931063810',
+      loadingPlanId: '90071992547409935', loadingPlanNo: 'LP-260830-0016', containerBookingId: '90071992547409936',
+      cabinetNo: 'CAB-260830-0016', containerNo: null, loadingStatus: 'LOADING', taskId: '90071992547409937',
+      pdaTaskStatus: 'IN_PROGRESS', coLoadGroupId: null, coLoadGroupNo: null, items: [{ itemId: '90071992547409938' }],
+    })
+    vi.mocked(getOverseasInboundCodeRelationship).mockResolvedValue({
+      inboundCode: 'NYEXX2608300027', found: true,
+      customer: { customerId: '90071992547409932', customerName: '纽约客户' },
+      overseasWarehouse: { warehouseId: '90071992547409939', warehouseCode: 'LAX', warehouseName: '洛杉矶海外仓' },
+      overseasReceivingStatus: 'RECEIVING', taillegOrders: [{ orderNo: 'LL-260830-0001', orderStatus: 'PENDING' }],
+      inboundPlans: [{ planNo: 'IP-260830-0001', planStatus: 'READY', receivingStatus: 'WAITING' }],
+      palletCodes: ['PLT-LAX-001'], inventory: [{ skuCode: 'SKU-001', productNameZh: '测试商品', packageCount: 12 }],
+    })
+  })
+
+  it('loads all three sections on an initially open mount and reloads after closing and reopening', async () => {
+    const wrapper = mountDialog()
+    await flushPromises()
+
+    expect(getPlatformInboundCodeAssociation).toHaveBeenCalledWith('NYEXX2608300027')
+    expect(getLoadingAssociationSummary).toHaveBeenCalledWith('NYEXX2608300027')
+    expect(getOverseasInboundCodeRelationship).toHaveBeenCalledWith('NYEXX2608300027')
+    expect(wrapper.text()).toContain('FL2093975748931063810')
+    expect(wrapper.text()).toContain('LP-260830-0016')
+    expect(wrapper.text()).toContain('CAB-260830-0016')
+    expect(wrapper.text()).toContain('纽约客户')
+    expect(wrapper.text()).toContain('洛杉矶海外仓')
+    expect(wrapper.text()).toContain('LL-260830-0001')
+    expect(wrapper.text()).toContain('IP-260830-0001')
+    expect(wrapper.text()).toContain('PLT-LAX-001')
+    expect(wrapper.text()).toContain('SKU-001')
+    expect(wrapper.text()).not.toMatch(/9007199254740993[1-9]/)
+    expect(wrapper.find('.relationship-sections').exists()).toBe(true)
+    expect(wrapper.findAll('.relationship-section')).toHaveLength(3)
+    expect(wrapper.findAll('.relationship-status')).toHaveLength(3)
+
+    await wrapper.setProps({ modelValue: false })
+    await wrapper.setProps({ modelValue: true })
+    await flushPromises()
+    expect(getPlatformInboundCodeAssociation).toHaveBeenCalledTimes(2)
+    expect(getLoadingAssociationSummary).toHaveBeenCalledTimes(2)
+    expect(getOverseasInboundCodeRelationship).toHaveBeenCalledTimes(2)
+  })
+
+  it('keeps a server-declared overseas miss as a local empty state', async () => {
+    vi.mocked(getOverseasInboundCodeRelationship).mockResolvedValueOnce({
+      inboundCode: 'NYEXX2608300027', found: false, customer: null, overseasWarehouse: null,
+      overseasReceivingStatus: null, taillegOrders: [], inboundPlans: [], palletCodes: [], inventory: [],
+    })
+    const wrapper = mountDialog()
+    await flushPromises()
+    expect(wrapper.text()).toContain('服务端未找到该入仓码的海外关联数据')
+    expect(wrapper.text()).toContain('FL2093975748931063810')
+    expect(wrapper.text()).toContain('LP-260830-0016')
+  })
+
+  it('keeps a failed section local while the other successful sections stay visible', async () => {
+    vi.mocked(getOverseasInboundCodeRelationship).mockRejectedValueOnce(new Error('overseas unavailable'))
+    const wrapper = mountDialog()
+    await flushPromises()
+    expect(wrapper.text()).toContain('海外关联加载失败')
+    expect(wrapper.text()).toContain('FL2093975748931063810')
+    expect(wrapper.text()).toContain('LP-260830-0016')
+    expect(wrapper.text()).not.toContain('洛杉矶海外仓')
+  })
+
+  it('distinguishes an unassigned overseas warehouse from a missing warehouse name', async () => {
+    vi.mocked(getOverseasInboundCodeRelationship).mockResolvedValueOnce({
+      inboundCode: 'NYEXX2608300027', found: true,
+      customer: { customerId: '90071992547409932', customerName: '纽约客户' }, overseasWarehouse: null,
+      overseasReceivingStatus: 'PENDING_ASSIGNMENT', taillegOrders: [], inboundPlans: [], palletCodes: [], inventory: [],
+    })
+    const unassigned = mountDialog()
+    await flushPromises()
+    expect(unassigned.text()).toContain('尚未分配海外仓')
+    expect(unassigned.text()).not.toContain('仓库名称待补充')
+    unassigned.unmount()
+
+    vi.mocked(getOverseasInboundCodeRelationship).mockResolvedValueOnce({
+      inboundCode: 'NYEXX2608300027', found: true,
+      customer: { customerId: '90071992547409932', customerName: '纽约客户' },
+      overseasWarehouse: { warehouseId: '90071992547409939', warehouseCode: 'LAX', warehouseName: '' },
+      overseasReceivingStatus: 'PENDING_ASSIGNMENT', taillegOrders: [], inboundPlans: [], palletCodes: [], inventory: [],
+    })
+    const missingName = mountDialog()
+    await flushPromises()
+    expect(missingName.text()).toContain('仓库名称待补充')
+    expect(missingName.text()).not.toContain('尚未分配海外仓')
+    missingName.unmount()
+  })
+
+  it('loads only permission-authorized server read models and keeps failures isolated', () => {
+    expect(source).toContain('props.canReadBase')
+    expect(source).toContain('props.canReadLoading')
+    expect(source).toContain('props.canReadOverseas')
+    expect(source).toContain('getPlatformInboundCodeAssociation(code)')
+    expect(source).toContain('getLoadingAssociationSummary(code)')
+    expect(source).toContain('getOverseasInboundCodeRelationship(code)')
+    expect(source).toContain('await Promise.all(tasks)')
+    expect(source).toContain('{ immediate: true }')
+    expect(source).toContain('<ApiErrorMeta :details="baseError"')
+    expect(source).toContain('<ApiErrorMeta :details="overseasError"')
+    expect(source).toContain('服务端未找到该入仓码的海外关联数据')
+    expect(source).not.toMatch(/listPlatform|customerId\)|warehouseId\)/)
+  })
+
+  it('shows business numbers and names without rendering internal ids', () => {
+    expect(source).toContain('baseAssociation.inboundCode')
+    expect(source).toContain('baseAssociation.orderNo')
+    expect(source).toContain('baseAssociation.customerName')
+    expect(source).toContain('baseAssociation.destinationWarehouseName')
+    expect(source).not.toContain('{{ baseAssociation.orderId')
+    expect(source).not.toContain('{{ baseAssociation.customerId')
+    expect(source).not.toContain('{{ baseAssociation.destinationWarehouseId')
+    expect(source).toContain('text-overflow:ellipsis')
+    expect(source).toContain(':title="display(baseAssociation.inboundCode)"')
+  })
+
+  it('keeps sections and status badges within the dialog at desktop and narrow widths', () => {
+    expect(source).toContain('class="inbound-relationship-dialog"')
+    expect(source).toContain('width="min(1060px, 94vw)"')
+    expect(source).toContain(':global(.inbound-relationship-dialog .el-dialog__body){box-sizing:border-box;min-width:0;max-height:calc(90vh - 112px);overflow-x:hidden;overflow-y:auto;padding-right:28px}')
+    expect(source).toContain(':global(.inbound-relationship-dialog .app-dialog__body){box-sizing:border-box;width:auto;max-width:100%;min-width:0;overflow-x:hidden}')
+    expect(source).toContain('.relationship-sections{display:grid;width:auto;max-width:100%;min-width:0;grid-template-columns:minmax(0,1fr)')
+    expect(source).toContain('.relationship-section{box-sizing:border-box;width:100%;min-width:0')
+    expect(source).toContain('flex-wrap:wrap')
+    expect(source).toContain('.relationship-section h3{flex:1 1 auto;min-width:0')
+    expect(source).toContain('.relationship-status{flex:0 0 auto;max-width:100%}')
+    expect(source).toContain('.inventory-table{width:100%;max-width:100%;min-width:0')
+  })
+
+  it('mounts the containment class through the real AppDialog and Element Plus dialog DOM', async () => {
+    const wrapper = mount(InboundCodeRelationshipDialog, {
+      attachTo: document.body,
+      props: {
+        modelValue: true,
+        inboundCode: 'NYEXX2608300027',
+        canReadBase: true,
+        canReadLoading: true,
+        canReadOverseas: true,
+      },
+      global: { plugins: [ElementPlus] },
+    })
+    await flushPromises()
+
+    const dialog = document.querySelector('.inbound-relationship-dialog')
+    const elementBody = dialog?.querySelector('.el-dialog__body')
+    const appBody = dialog?.querySelector('.app-dialog__body')
+    expect(dialog).not.toBeNull()
+    expect(elementBody).not.toBeNull()
+    expect(appBody).not.toBeNull()
+    expect(appBody?.querySelectorAll('.relationship-section')).toHaveLength(3)
+    expect(appBody?.querySelectorAll('.relationship-status')).toHaveLength(3)
+    expect(dialog?.querySelector('.el-drawer__body')).toBeNull()
+
+    wrapper.unmount()
+  })
+
+  it('removes the retired Drawer component and keeps the Dialog only in confirmed Admin consumers', () => {
+    const root = process.cwd()
+    expect(existsSync(resolve(root, 'src/shared/components/InboundCodeRelationshipDrawer.vue'))).toBe(false)
+    expect(existsSync(resolve(root, 'src/shared/components/InboundCodeRelationshipDrawer.test.ts'))).toBe(false)
+    const dialogConsumerFiles = [
+      'src/modules/inbounds/pages/InboundOrdersView.vue',
+      'src/modules/overseas-warehouse/pages/InventoryTransactionsView.vue',
+    ]
+    const consumerSources = dialogConsumerFiles.map((file) => readFileSync(resolve(root, file), 'utf8'))
+    const consumers = consumerSources.join('\n')
+    expect(consumers).not.toContain('InboundCodeRelationshipDrawer')
+    expect(consumers).not.toMatch(/relationshipOpen|relationshipInboundCode|inboundRelationshipOpen/)
+    consumerSources.forEach((consumer) => {
+      expect(consumer).toContain("import InboundCodeRelationshipDialog from '@/shared/components/InboundCodeRelationshipDialog.vue'")
+      expect(consumer).toContain('<InboundCodeRelationshipDialog')
+    })
+
+    const inboundTasks = readFileSync(resolve(root, 'src/modules/inbounds/components/InboundTaskList.vue'), 'utf8')
+    expect(inboundTasks).not.toContain('InboundCodeRelationshipDrawer')
+    expect(inboundTasks).not.toContain('InboundCodeRelationshipDialog')
+
+    const unifiedOrders = readFileSync(resolve(root, 'src/modules/unified-orders/pages/UnifiedOrdersView.vue'), 'utf8')
+    expect(unifiedOrders).not.toContain('InboundCodeRelationshipDrawer')
+    expect(unifiedOrders).not.toContain('InboundCodeRelationshipDialog')
+  })
+})
diff --git a/src/shared/components/InboundCodeRelationshipDialog.vue b/src/shared/components/InboundCodeRelationshipDialog.vue
new file mode 100644
index 00000000..1ef1d4d9
--- /dev/null
+++ b/src/shared/components/InboundCodeRelationshipDialog.vue
@@ -0,0 +1,105 @@
+<script setup lang="ts">
+import '@/styles/adminDensity.css'
+import { computed, ref, watch } from 'vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { getLoadingAssociationSummary, getOverseasInboundCodeRelationship, getPlatformInboundCodeAssociation, type LoadingAssociationSummary, type OverseasInboundCodeRelationship, type PlatformInboundCodeAssociation } from '@/shared/api/inboundCodeRelations'
+import ApiErrorMeta from './ApiErrorMeta.vue'
+import AppDialog from './AppDialog.vue'
+import LoadErrorState from './LoadErrorState.vue'
+import StatusBadge from './StatusBadge.vue'
+
+const props = defineProps<{ dense?: boolean; modelValue: boolean; inboundCode: string; canReadBase: boolean; canReadLoading: boolean; canReadOverseas: boolean }>()
+const emit = defineEmits<{ 'update:modelValue': [value: boolean] }>()
+const baseAssociation = ref<PlatformInboundCodeAssociation | null>(null)
+const overseas = ref<OverseasInboundCodeRelationship | null>(null)
+const loadingAssociation = ref<LoadingAssociationSummary | null>(null)
+const baseError = ref<ApiErrorDetails | null>(null)
+const overseasError = ref<ApiErrorDetails | null>(null)
+const loadingAssociationError = ref<ApiErrorDetails | null>(null)
+const loading = ref(false)
+let serial = 0
+
+const canReadBase = computed(() => props.canReadBase)
+const canReadLoading = computed(() => props.canReadLoading)
+const canReadOverseas = computed(() => props.canReadOverseas)
+const normalizedCode = computed(() => props.inboundCode.trim())
+
+function display(value: unknown, fallback = '—') { return String(value ?? '').trim() || fallback }
+function overseasWarehouseName(value: OverseasInboundCodeRelationship['overseasWarehouse']) {
+  return value ? display(value.warehouseName, '仓库名称待补充') : '尚未分配海外仓'
+}
+function close(value: boolean) { emit('update:modelValue', value) }
+
+async function load() {
+  const code = normalizedCode.value
+  const request = ++serial
+  baseAssociation.value = null; overseas.value = null; loadingAssociation.value = null; baseError.value = null; overseasError.value = null; loadingAssociationError.value = null
+  if (!code || (!canReadBase.value && !canReadLoading.value && !canReadOverseas.value)) return
+  loading.value = true
+  const tasks: Promise<void>[] = []
+  if (canReadBase.value) tasks.push(getPlatformInboundCodeAssociation(code).then((value) => { if (request === serial) baseAssociation.value = value }).catch((cause) => { if (request === serial) baseError.value = getApiErrorDetails(cause, '订单基础关联数据加载失败') }))
+  if (canReadLoading.value) tasks.push(getLoadingAssociationSummary(code).then((value) => { if (request === serial) loadingAssociation.value = value }).catch((cause) => { if (request === serial) loadingAssociationError.value = getApiErrorDetails(cause, '装柜与PDA关联数据加载失败') }))
+  if (canReadOverseas.value) tasks.push(getOverseasInboundCodeRelationship(code).then((value) => { if (request === serial) overseas.value = value }).catch((cause) => { if (request === serial) overseasError.value = getApiErrorDetails(cause, '海外入仓关联数据加载失败') }))
+  await Promise.all(tasks)
+  if (request === serial) loading.value = false
+}
+
+watch(() => [props.modelValue, props.inboundCode, props.canReadBase, props.canReadLoading, props.canReadOverseas] as const, ([open]) => {
+  if (open) void load()
+  else serial += 1
+}, { immediate: true })
+</script>
+
+<template>
+  <AppDialog class="inbound-relationship-dialog" :class="{ 'admin-density-dialog': dense }" :model-value="modelValue" :title="`入仓码关联数据 · ${normalizedCode || '未提供'}`" width="min(1060px, 94vw)" :loading="loading" :show-footer="false" destroy-on-close @update:model-value="close">
+    <el-alert v-if="!normalizedCode" type="warning" :closable="false" show-icon title="缺少入仓码，已停止查询关联数据。" />
+    <el-alert v-else-if="!canReadBase && !canReadLoading && !canReadOverseas" type="warning" :closable="false" show-icon title="当前账号无入仓关联数据查看权限。" />
+
+    <div v-else class="relationship-sections">
+      <section v-if="canReadBase" class="relationship-section" aria-label="订单基础关联">
+        <header><h3>订单基础信息</h3><StatusBadge v-if="baseAssociation?.orderStatus" class="relationship-status" :status="baseAssociation.orderStatus" /></header>
+        <LoadErrorState v-if="baseError" title="订单基础关联加载失败" :message="baseError.message" @retry="load"><template #details><ApiErrorMeta :details="baseError" /></template></LoadErrorState>
+        <dl v-else-if="baseAssociation" class="compact-facts" :class="{ 'density-fields': dense }">
+          <div><dt>入仓码</dt><dd :title="display(baseAssociation.inboundCode)">{{ display(baseAssociation.inboundCode) }}</dd></div><div><dt>订单编码</dt><dd :title="display(baseAssociation.orderNo, '订单编码待补充')">{{ display(baseAssociation.orderNo, '订单编码待补充') }}</dd></div>
+          <div><dt>客户</dt><dd :title="display(baseAssociation.customerName, '客户名称待补充')">{{ display(baseAssociation.customerName, '客户名称待补充') }}</dd></div><div><dt>目的类型</dt><dd>{{ display(baseAssociation.destinationType) }}</dd></div>
+          <div><dt>目的国家</dt><dd>{{ display(baseAssociation.destinationCountryCode) }}</dd></div><div><dt>目的仓</dt><dd>{{ display(baseAssociation.destinationWarehouseName, '目的仓名称待补充') }}<small v-if="baseAssociation.destinationWarehouseCode">{{ baseAssociation.destinationWarehouseCode }}</small></dd></div>
+        </dl>
+      </section>
+
+      <section v-if="canReadLoading" class="relationship-section" aria-label="装柜与PDA关联">
+        <header><h3>装柜与PDA</h3><StatusBadge v-if="loadingAssociation?.loadingStatus" class="relationship-status" :status="loadingAssociation.loadingStatus" /></header>
+        <LoadErrorState v-if="loadingAssociationError" title="装柜关联加载失败" :message="loadingAssociationError.message" @retry="load"><template #details><ApiErrorMeta :details="loadingAssociationError" /></template></LoadErrorState>
+        <dl v-else-if="loadingAssociation" class="compact-facts" :class="{ 'density-fields': dense }">
+          <div><dt>订单编码</dt><dd :title="display(loadingAssociation.orderNo, '订单编码待补充')">{{ display(loadingAssociation.orderNo, '订单编码待补充') }}</dd></div><div><dt>装柜计划</dt><dd :title="display(loadingAssociation.loadingPlanNo, '尚未进入装柜')">{{ display(loadingAssociation.loadingPlanNo, '尚未进入装柜') }}</dd></div>
+          <div><dt>柜号</dt><dd :title="display(loadingAssociation.containerNo || loadingAssociation.cabinetNo, '尚未关联柜号')">{{ display(loadingAssociation.containerNo || loadingAssociation.cabinetNo, '尚未关联柜号') }}</dd></div><div><dt>同柜组</dt><dd :title="display(loadingAssociation.coLoadGroupNo)">{{ display(loadingAssociation.coLoadGroupNo) }}</dd></div>
+          <div><dt>装柜状态</dt><dd>{{ display(loadingAssociation.loadingStatus) }}</dd></div><div><dt>PDA任务状态</dt><dd>{{ display(loadingAssociation.pdaTaskStatus, '尚未生成PDA任务') }}</dd></div>
+        </dl>
+      </section>
+
+      <section v-if="canReadOverseas" class="relationship-section" aria-label="海外入仓关联">
+        <header><h3>海外入仓与库存</h3><StatusBadge v-if="overseas?.overseasReceivingStatus" class="relationship-status" :status="overseas.overseasReceivingStatus" /></header>
+        <LoadErrorState v-if="overseasError" title="海外关联加载失败" :message="overseasError.message" @retry="load"><template #details><ApiErrorMeta :details="overseasError" /></template></LoadErrorState>
+        <el-empty v-else-if="overseas && !overseas.found" description="服务端未找到该入仓码的海外关联数据" :image-size="56" />
+        <template v-else-if="overseas">
+          <dl class="compact-facts" :class="{ 'density-fields': dense }"><div><dt>客户</dt><dd>{{ display(overseas.customer?.customerName, '客户名称待补充') }}</dd></div><div><dt>海外仓</dt><dd>{{ overseasWarehouseName(overseas.overseasWarehouse) }}<small v-if="overseas.overseasWarehouse?.warehouseCode">{{ overseas.overseasWarehouse.warehouseCode }}</small></dd></div></dl>
+          <div class="compact-list"><strong>尾程订单</strong><span :title="overseas.taillegOrders.map((item) => item.orderNo).join('、')">{{ overseas.taillegOrders.map((item) => `${item.orderNo}${item.orderStatus ? `（${item.orderStatus}）` : ''}`).filter(Boolean).join('、') || '—' }}</span></div>
+          <div class="compact-list"><strong>入库计划</strong><span :title="overseas.inboundPlans.map((item) => item.planNo).join('、')">{{ overseas.inboundPlans.map((item) => `${item.planNo}${item.planStatus ? `（${item.planStatus}）` : ''}${item.receivingStatus ? ` · ${item.receivingStatus}` : ''}`).join('、') || '—' }}</span></div>
+          <div class="compact-list"><strong>托盘号</strong><span :title="overseas.palletCodes.join('、')">{{ overseas.palletCodes.join('、') || '—' }}</span></div>
+          <el-table v-if="overseas.inventory.length" :data="overseas.inventory" size="small" border class="inventory-table">
+            <el-table-column prop="skuCode" label="SKU编码" min-width="150" /><el-table-column label="产品名称" min-width="190"><template #default="{ row }">{{ display(row.productNameZh || row.productNameEn) }}</template></el-table-column><el-table-column prop="packageCount" label="库存箱数" width="110" align="right" />
+          </el-table>
+        </template>
+      </section>
+    </div>
+  </AppDialog>
+</template>
+
+<style scoped>
+:global(.inbound-relationship-dialog.el-dialog){width:min(1060px,94vw);max-width:94vw}:global(.inbound-relationship-dialog .el-dialog__body){box-sizing:border-box;min-width:0;max-height:calc(90vh - 112px);overflow-x:hidden;overflow-y:auto;padding-right:28px}:global(.inbound-relationship-dialog .app-dialog__body){box-sizing:border-box;width:auto;max-width:100%;min-width:0;overflow-x:hidden}.relationship-sections{display:grid;width:auto;max-width:100%;min-width:0;grid-template-columns:minmax(0,1fr);gap:12px}.relationship-section{box-sizing:border-box;width:100%;min-width:0;border:1px solid var(--cc-border);border-radius:8px;padding:12px;background:var(--cc-surface)}.relationship-section>header{display:flex;min-width:0;align-items:center;justify-content:space-between;flex-wrap:wrap;gap:8px 12px;margin-bottom:10px}.relationship-section h3{flex:1 1 auto;min-width:0;margin:0;font-size:15px}.relationship-status{flex:0 0 auto;max-width:100%}.compact-facts:not(.density-fields){display:grid;min-width:0;grid-template-columns:repeat(2,minmax(0,1fr));gap:1px;margin:0;background:var(--cc-border)}.compact-facts:not(.density-fields)>div{display:grid;min-width:0;grid-template-columns:92px minmax(0,1fr);gap:8px;padding:8px 10px;background:var(--cc-surface)}.compact-facts:not(.density-fields) dt{color:var(--cc-muted)}.compact-facts:not(.density-fields) dd{min-width:0;margin:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.compact-facts:not(.density-fields) small{display:block;overflow:hidden;color:var(--cc-muted);margin-top:2px;text-overflow:ellipsis;white-space:nowrap}.compact-list{display:grid;min-width:0;grid-template-columns:92px minmax(0,1fr);gap:8px;padding:8px 10px;border-top:1px solid var(--cc-border)}.compact-list span{min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.inventory-table{width:100%;max-width:100%;min-width:0;margin-top:8px}@media(max-width:720px){:global(.inbound-relationship-dialog .el-dialog__body){padding-right:20px}.compact-facts:not(.density-fields){grid-template-columns:1fr}}
+
+:global(.inbound-relationship-dialog.admin-density-dialog .el-dialog__body) { padding: var(--admin-space-5) var(--admin-space-6); max-height: none; }
+:global(.inbound-relationship-dialog.admin-density-dialog .relationship-section) { padding: 0; border: 0; border-radius: 0; }
+:global(.inbound-relationship-dialog.admin-density-dialog .relationship-section h3) { font-size: var(--admin-font-section); }
+:global(.inbound-relationship-dialog.admin-density-dialog .density-fields) { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+:global(.inbound-relationship-dialog.admin-density-dialog .compact-list span) { white-space: normal; overflow-wrap: anywhere; }
+</style>
diff --git a/src/shared/components/LayoutPreferenceList.test.ts b/src/shared/components/LayoutPreferenceList.test.ts
new file mode 100644
index 00000000..2b627cb9
--- /dev/null
+++ b/src/shared/components/LayoutPreferenceList.test.ts
@@ -0,0 +1,14 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const source = readFileSync(resolve(process.cwd(), 'src/shared/components/LayoutPreferenceList.vue'), 'utf8')
+
+describe('LayoutPreferenceList overflow layout', () => {
+  it('keeps long item collections inside a viewport-bounded scroll area', () => {
+    expect(source).toContain('grid-template-rows: auto minmax(0, 1fr) auto')
+    expect(source).toContain('max-height: min(520px, calc(100dvh - 120px))')
+    expect(source).toContain('.layout-preference-list__scroll { min-height: 0;')
+    expect(source).toContain('overflow-y: auto')
+  })
+})
diff --git a/src/shared/components/LayoutPreferenceList.vue b/src/shared/components/LayoutPreferenceList.vue
new file mode 100644
index 00000000..55c66995
--- /dev/null
+++ b/src/shared/components/LayoutPreferenceList.vue
@@ -0,0 +1,119 @@
+<script setup lang="ts">
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import Sortable from 'sortablejs'
+import { ChevronDown, ChevronUp, GripVertical, RotateCcw } from '@lucide/vue'
+
+export interface LayoutPreferenceItem {
+  key: string
+  label: string
+  visible: boolean
+  hideable: boolean
+  movable: boolean
+  hideDisabled?: boolean
+}
+
+const props = withDefaults(defineProps<{
+  items: LayoutPreferenceItem[]
+  allowVisibility?: boolean
+}>(), {
+  allowVisibility: false,
+})
+
+const emit = defineEmits<{
+  move: [key: string, targetIndex: number]
+  visibility: [key: string, visible: boolean]
+  reset: []
+}>()
+
+const sortableList = ref<HTMLElement>()
+const movableItems = computed(() => props.items.filter((item) => item.movable))
+const lockedItems = computed(() => props.items.filter((item) => !item.movable))
+let sortable: Sortable | undefined
+
+function syncSortableOrder() {
+  void nextTick(() => sortable?.sort(movableItems.value.map((item) => item.key), false))
+}
+
+function createSortable() {
+  if (!sortableList.value) return
+  sortable?.destroy()
+  sortable = Sortable.create(sortableList.value, {
+    animation: 150,
+    handle: '.layout-preference-list__handle',
+    ghostClass: 'is-dragging',
+    dataIdAttr: 'data-key',
+    onEnd(event) {
+      if (event.oldIndex === undefined || event.newIndex === undefined || event.oldIndex === event.newIndex) return
+      const item = movableItems.value[event.oldIndex]
+      if (item) emit('move', item.key, event.newIndex)
+      syncSortableOrder()
+    },
+  })
+}
+
+function moveBy(key: string, offset: number) {
+  const index = movableItems.value.findIndex((item) => item.key === key)
+  if (index < 0) return
+  emit('move', key, index + offset)
+}
+
+onMounted(createSortable)
+onBeforeUnmount(() => sortable?.destroy())
+watch(() => props.items.map((item) => item.key), syncSortableOrder)
+</script>
+
+<template>
+  <div class="layout-preference-list">
+    <p class="layout-preference-list__hint">拖动调整顺序，也可使用上下移动按钮。</p>
+    <div class="layout-preference-list__scroll" tabindex="0" aria-label="布局项目">
+      <ul v-if="lockedItems.length" class="layout-preference-list__items is-locked" aria-label="固定项目">
+        <li v-for="item in lockedItems" :key="item.key" class="layout-preference-list__item is-locked">
+          <span class="layout-preference-list__handle is-disabled" aria-hidden="true"><GripVertical :size="16" /></span>
+          <el-checkbox v-if="allowVisibility" :model-value="item.visible" disabled>{{ item.label }}</el-checkbox>
+          <span v-else class="layout-preference-list__label">{{ item.label }}</span>
+          <span class="layout-preference-list__fixed">固定</span>
+        </li>
+      </ul>
+      <ul ref="sortableList" class="layout-preference-list__items" aria-label="可排序项目">
+        <li v-for="(item, index) in movableItems" :key="item.key" :data-key="item.key" class="layout-preference-list__item">
+          <button class="layout-preference-list__handle" type="button" :aria-label="`拖动${item.label}`" :title="`拖动${item.label}`">
+            <GripVertical :size="16" />
+          </button>
+          <el-checkbox
+            v-if="allowVisibility"
+            :model-value="item.visible"
+            :disabled="!item.hideable || item.hideDisabled"
+            @update:model-value="emit('visibility', item.key, Boolean($event))"
+          >{{ item.label }}</el-checkbox>
+          <span v-else class="layout-preference-list__label">{{ item.label }}</span>
+          <div class="layout-preference-list__moves">
+            <el-button text :disabled="index === 0" :aria-label="`上移${item.label}`" :title="`上移${item.label}`" @click="moveBy(item.key, -1)"><ChevronUp :size="16" /></el-button>
+            <el-button text :disabled="index === movableItems.length - 1" :aria-label="`下移${item.label}`" :title="`下移${item.label}`" @click="moveBy(item.key, 1)"><ChevronDown :size="16" /></el-button>
+          </div>
+        </li>
+      </ul>
+    </div>
+    <el-button class="layout-preference-list__reset" text @click="emit('reset')"><RotateCcw :size="15" />恢复默认</el-button>
+  </div>
+</template>
+
+<style scoped>
+.layout-preference-list { display: grid; max-height: min(520px, calc(100vh - 120px)); max-height: min(520px, calc(100dvh - 120px)); grid-template-rows: auto minmax(0, 1fr) auto; gap: 10px; overflow: hidden; }
+.layout-preference-list__hint { margin: 0; color: var(--cc-muted); font-size: 12px; line-height: 1.5; }
+.layout-preference-list__scroll { min-height: 0; padding-right: 4px; overflow-y: auto; overscroll-behavior: contain; scrollbar-gutter: stable; }
+.layout-preference-list__scroll:focus-visible { outline: 2px solid var(--cc-primary); outline-offset: 1px; }
+.layout-preference-list__items { display: grid; gap: 4px; margin: 0; padding: 0; list-style: none; }
+.layout-preference-list__items.is-locked { margin-bottom: 4px; padding-bottom: 8px; border-bottom: 1px solid var(--cc-border); }
+.layout-preference-list__item { display: grid; min-height: 38px; grid-template-columns: 28px minmax(0, 1fr) auto; align-items: center; gap: 6px; padding: 3px 4px; border: 1px solid transparent; background: #fff; }
+.layout-preference-list__item:hover { border-color: var(--cc-border); background: #f8fafc; }
+.layout-preference-list__item.is-dragging { border-color: var(--cc-primary); background: #eef5ff; }
+.layout-preference-list__handle { display: inline-flex; width: 28px; height: 28px; align-items: center; justify-content: center; padding: 0; border: 0; background: transparent; color: var(--cc-muted); cursor: grab; }
+.layout-preference-list__handle:focus-visible { outline: 2px solid var(--cc-primary); outline-offset: 1px; }
+.layout-preference-list__handle.is-disabled { cursor: default; opacity: .45; }
+.layout-preference-list__label { min-width: 0; overflow: hidden; color: var(--cc-text); font-size: 13px; text-overflow: ellipsis; white-space: nowrap; }
+.layout-preference-list__fixed { color: var(--cc-muted); font-size: 11px; }
+.layout-preference-list__moves { display: flex; gap: 0; }
+.layout-preference-list__moves :deep(.el-button) { width: 30px; height: 30px; margin-left: 0; padding: 0; }
+.layout-preference-list__reset { justify-self: start; margin-left: 0; }
+@media (max-width: 720px) { .layout-preference-list__item { min-height: 44px; } .layout-preference-list__moves :deep(.el-button) { width: 40px; height: 40px; } }
+</style>
diff --git a/src/shared/components/LineClampText.domestic-lists.test.ts b/src/shared/components/LineClampText.domestic-lists.test.ts
new file mode 100644
index 00000000..74cd2d5e
--- /dev/null
+++ b/src/shared/components/LineClampText.domestic-lists.test.ts
@@ -0,0 +1,50 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+const read = (path: string) => readFileSync(resolve(process.cwd(), path), 'utf8')
+
+describe('LineClampText domestic list consumers', () => {
+  it.each([
+    ['统一订单', 'src/modules/unified-orders/pages/UnifiedOrdersView.vue'],
+    ['入库任务', 'src/modules/inbounds/components/InboundTaskList.vue'],
+    ['入库单', 'src/modules/inbounds/pages/InboundOrdersView.vue'],
+    ['装柜清单', 'src/modules/loading-lists/components/LoadingListsView.vue'],
+    ['柜次智能装柜', 'src/modules/container-loading/pages/SmartLoadingWorkbenchView.vue'],
+    ['全局智能装柜', 'src/modules/container-loading/pages/GlobalSmartLoadingView.vue'],
+  ])('%s列表复用共享的行数省略组件', (_name, path) => {
+    expect(read(path)).toContain("LineClampText from '@/shared/components/LineClampText.vue'")
+  })
+
+  it('统一订单客户与渠道都使用一行省略，并保留渠道变更标记', () => {
+    const source = read('src/modules/unified-orders/pages/UnifiedOrdersView.vue')
+    expect(source).toContain("column.property === 'customerName'")
+    expect(source).toContain('<LineClampText :content="(row as UnifiedOrderResource).channelName" />')
+    expect(source).toContain('曾变更渠道')
+  })
+
+  it.each([
+    ['src/modules/inbounds/components/InboundTaskList.vue', '#customerName', '#channelName'],
+    ['src/modules/inbounds/pages/InboundOrdersView.vue', '#customerName', '#channelName'],
+  ])('入库列表客户与渠道均使用共享组件：%s', (path, customerSlot, channelSlot) => {
+    const source = read(path)
+    expect(source).toContain(`<template ${customerSlot}`)
+    expect(source).toContain(`<template ${channelSlot}`)
+    expect(source.match(/<LineClampText/g)?.length).toBeGreaterThanOrEqual(2)
+  })
+
+  it('装柜清单将多客户汇总限制为一行', () => {
+    const source = read('src/modules/loading-lists/components/LoadingListsView.vue')
+    expect(source).toContain('<template #customers="{ row }"><LineClampText')
+  })
+
+  it.each([
+    'src/modules/container-loading/pages/SmartLoadingWorkbenchView.vue',
+    'src/modules/container-loading/pages/GlobalSmartLoadingView.vue',
+  ])('智能装柜候选与已装载客户列使用相同的一行省略：%s', (path) => {
+    const source = read(path)
+    expect(source.match(/slotName: 'customerName'/g)).toHaveLength(2)
+    expect(source.match(/<template #customerName/g)).toHaveLength(2)
+    expect(source.match(/<LineClampText :content=/g)?.length).toBeGreaterThanOrEqual(2)
+  })
+})
diff --git a/src/shared/components/LineClampText.test.ts b/src/shared/components/LineClampText.test.ts
new file mode 100644
index 00000000..9da384e0
--- /dev/null
+++ b/src/shared/components/LineClampText.test.ts
@@ -0,0 +1,43 @@
+import { defineComponent } from 'vue'
+import { shallowMount } from '@vue/test-utils'
+import { describe, expect, it } from 'vitest'
+import LineClampText from './LineClampText.vue'
+
+const TooltipStub = defineComponent({
+  props: { content: String, disabled: Boolean, visible: Boolean },
+  template: '<div class="tooltip-stub" :data-content="content" :data-visible="visible"><slot /></div>',
+})
+
+describe('LineClampText', () => {
+  it('defaults to one line and exposes the full text to hover and focus', async () => {
+    const wrapper = shallowMount(LineClampText, {
+      props: { content: '第一行\n第二行' },
+      global: { stubs: { ElTooltip: TooltipStub } },
+    })
+    const text = wrapper.get('.line-clamp-text')
+    expect(text.attributes('style')).toContain('--cc-line-clamp: 1')
+    expect(text.attributes('aria-label')).toBe('第一行\n第二行')
+    expect(wrapper.get('.tooltip-stub').attributes('data-content')).toBe('第一行\n第二行')
+    expect(wrapper.get('.tooltip-stub').attributes('data-visible')).toBe('false')
+
+    await text.trigger('mouseenter')
+    expect(wrapper.get('.tooltip-stub').attributes('data-visible')).toBe('true')
+    await text.trigger('mouseleave')
+    expect(wrapper.get('.tooltip-stub').attributes('data-visible')).toBe('false')
+    await text.trigger('focus')
+    expect(wrapper.get('.tooltip-stub').attributes('data-visible')).toBe('true')
+    await text.trigger('blur')
+    expect(wrapper.get('.tooltip-stub').attributes('data-visible')).toBe('false')
+  })
+
+  it('accepts two and three line limits', () => {
+    expect(shallowMount(LineClampText, {
+      props: { content: 'text', lines: 2 },
+      global: { stubs: { ElTooltip: TooltipStub } },
+    }).get('.line-clamp-text').attributes('style')).toContain('--cc-line-clamp: 2')
+    expect(shallowMount(LineClampText, {
+      props: { content: 'text', lines: 3 },
+      global: { stubs: { ElTooltip: TooltipStub } },
+    }).get('.line-clamp-text').attributes('style')).toContain('--cc-line-clamp: 3')
+  })
+})
diff --git a/src/shared/components/LineClampText.vue b/src/shared/components/LineClampText.vue
new file mode 100644
index 00000000..88b992c1
--- /dev/null
+++ b/src/shared/components/LineClampText.vue
@@ -0,0 +1,48 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+
+const props = withDefaults(defineProps<{
+  content?: string | number | null
+  lines?: 1 | 2 | 3
+}>(), {
+  content: '',
+  lines: 1,
+})
+
+const text = computed(() => props.content === null || props.content === undefined ? '' : String(props.content))
+const lineStyle = computed(() => ({ '--cc-line-clamp': props.lines }))
+const tooltipVisible = ref(false)
+
+function showTooltip() {
+  if (text.value) tooltipVisible.value = true
+}
+
+function hideTooltip() {
+  tooltipVisible.value = false
+}
+</script>
+
+<template>
+  <el-tooltip
+    :content="text || '—'"
+    :disabled="!text"
+    :visible="Boolean(text) && tooltipVisible"
+    placement="top-start"
+  >
+    <span
+      class="line-clamp-text"
+      :style="lineStyle"
+      :tabindex="text ? 0 : undefined"
+      :aria-label="text || '—'"
+      @mouseenter="showTooltip"
+      @mouseleave="hideTooltip"
+      @focus="showTooltip"
+      @blur="hideTooltip"
+    >{{ text || '—' }}</span>
+  </el-tooltip>
+</template>
+
+<style scoped>
+.line-clamp-text { display: -webkit-box; min-width: 0; overflow: hidden; line-height: 1.5; -webkit-box-orient: vertical; -webkit-line-clamp: var(--cc-line-clamp); overflow-wrap: anywhere; white-space: pre-line; }
+.line-clamp-text:focus-visible { outline: 2px solid color-mix(in srgb, var(--cc-primary) 45%, transparent); outline-offset: 2px; }
+</style>
diff --git a/src/shared/components/ListPageLayout.vue b/src/shared/components/ListPageLayout.vue
new file mode 100644
index 00000000..00b5e82a
--- /dev/null
+++ b/src/shared/components/ListPageLayout.vue
@@ -0,0 +1,44 @@
+<script setup lang="ts">
+import { Comment, Fragment, Text, isVNode, useSlots } from 'vue'
+
+withDefaults(defineProps<{
+  ariaLabel?: string
+}>(), {
+  ariaLabel: '列表页面',
+})
+
+const slots = useSlots()
+type RegionName = 'toolbar' | 'metrics' | 'state' | 'default'
+
+function hasRenderableContent(value: unknown): boolean {
+  if (Array.isArray(value)) return value.some(hasRenderableContent)
+  if (!isVNode(value)) return typeof value === 'string' ? value.trim().length > 0 : value != null && typeof value !== 'boolean'
+  if (value.type === Comment) return false
+  if (value.type === Text) return hasRenderableContent(value.children)
+  if (value.type === Fragment) return hasRenderableContent(value.children)
+  return true
+}
+
+function hasRegion(name: RegionName) {
+  return hasRenderableContent(slots[name]?.())
+}
+</script>
+
+<template>
+  <section class="list-page-layout" :aria-label="ariaLabel">
+    <div v-if="hasRegion('toolbar')" class="list-page-layout__toolbar"><slot name="toolbar" /></div>
+    <div v-if="hasRegion('metrics')" class="list-page-layout__metrics"><slot name="metrics" /></div>
+    <div v-if="hasRegion('state')" class="list-page-layout__state"><slot name="state" /></div>
+    <div v-if="hasRegion('default')" class="list-page-layout__content"><slot /></div>
+  </section>
+</template>
+
+<style scoped>
+.list-page-layout { display: flex; min-width: 0; flex-direction: column; gap: 16px; }
+.list-page-layout__toolbar, .list-page-layout__metrics, .list-page-layout__state, .list-page-layout__content { min-width: 0; }
+.list-page-layout__toolbar:empty, .list-page-layout__metrics:empty, .list-page-layout__state:empty, .list-page-layout__content:empty { display: none; }
+
+@media (min-width: 1920px) {
+  .list-page-layout { gap: 12px; }
+}
+</style>
diff --git a/src/shared/components/LoadErrorState.vue b/src/shared/components/LoadErrorState.vue
new file mode 100644
index 00000000..3e2ef8a6
--- /dev/null
+++ b/src/shared/components/LoadErrorState.vue
@@ -0,0 +1,48 @@
+<script setup lang="ts">
+import { CircleAlert } from '@lucide/vue'
+
+withDefaults(defineProps<{
+  title: string
+  message?: string
+  loading?: boolean
+  retryText?: string
+  showRetry?: boolean
+  compact?: boolean
+}>(), {
+  message: '',
+  loading: false,
+  retryText: '重新加载',
+  showRetry: true,
+  compact: false,
+})
+
+defineEmits<{ retry: [] }>()
+</script>
+
+<template>
+  <section class="load-error-state" :class="{ 'is-compact': compact }" role="alert">
+    <CircleAlert class="load-error-state__icon" :size="20" aria-hidden="true" />
+    <div class="load-error-state__content">
+      <strong>{{ title }}</strong>
+      <p v-if="message">{{ message }}</p>
+      <slot name="details" />
+    </div>
+    <div v-if="showRetry || $slots.actions" class="load-error-state__actions">
+      <slot name="actions">
+        <el-button type="primary" plain :loading="loading" @click="$emit('retry')">{{ retryText }}</el-button>
+      </slot>
+    </div>
+  </section>
+</template>
+
+<style scoped>
+.load-error-state { display: flex; min-width: 0; align-items: flex-start; gap: 12px; padding: 16px; border: 1px solid var(--el-color-danger-light-7); border-radius: 8px; background: var(--el-color-danger-light-9); color: var(--el-text-color-primary); }
+.load-error-state.is-compact { padding: 12px; }
+.load-error-state__icon { flex: 0 0 auto; margin-top: 1px; color: var(--el-color-danger); }
+.load-error-state__content { min-width: 0; flex: 1; }
+.load-error-state__content strong { display: block; font-size: 14px; line-height: 1.5; }
+.load-error-state__content p { margin: 4px 0 0; color: var(--el-text-color-secondary); font-size: 13px; line-height: 1.6; overflow-wrap: anywhere; }
+.load-error-state__actions { display: flex; flex: 0 0 auto; flex-wrap: wrap; gap: 8px; }
+.load-error-state__actions :deep(.el-button) { margin-left: 0; }
+@media (max-width: 720px) { .load-error-state { flex-wrap: wrap; } .load-error-state__content { flex-basis: calc(100% - 36px); } .load-error-state__actions { width: 100%; padding-left: 32px; } .load-error-state__actions :deep(.el-button) { min-height: 44px; } }
+</style>
diff --git a/src/components/MetricStrip.vue b/src/shared/components/MetricStrip.vue
similarity index 100%
rename from src/components/MetricStrip.vue
rename to src/shared/components/MetricStrip.vue
diff --git a/src/shared/components/OperationErrorToast.test.ts b/src/shared/components/OperationErrorToast.test.ts
new file mode 100644
index 00000000..c8da0de0
--- /dev/null
+++ b/src/shared/components/OperationErrorToast.test.ts
@@ -0,0 +1,19 @@
+import { ElMessage } from 'element-plus'
+import { mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import OperationErrorToast from './OperationErrorToast.vue'
+
+describe('OperationErrorToast', () => {
+  beforeEach(() => vi.restoreAllMocks())
+
+  it('shows an operation error as a dismissible temporary message without page markup', async () => {
+    const error = vi.spyOn(ElMessage, 'error').mockImplementation(() => ({ close: vi.fn() }) as never)
+    const wrapper = mount(OperationErrorToast, { props: { details: { message: '箱号不存在', code: 'A0404' } } })
+
+    expect(error).toHaveBeenCalledWith({ message: '箱号不存在', showClose: true, duration: 4500 })
+    expect(wrapper.html()).toBe('')
+
+    await wrapper.setProps({ details: { message: '保存失败', code: 'A0500' } })
+    expect(error).toHaveBeenLastCalledWith({ message: '保存失败', showClose: true, duration: 4500 })
+  })
+})
diff --git a/src/shared/components/OperationErrorToast.vue b/src/shared/components/OperationErrorToast.vue
new file mode 100644
index 00000000..de9893b1
--- /dev/null
+++ b/src/shared/components/OperationErrorToast.vue
@@ -0,0 +1,24 @@
+<script setup lang="ts">
+import { watch } from 'vue'
+import { ElMessage } from 'element-plus'
+import type { ApiErrorDetails } from '@/shared/api/http'
+
+const props = withDefaults(defineProps<{
+  details?: ApiErrorDetails | null
+  message?: string | null
+}>(), {
+  details: null,
+  message: null,
+})
+
+watch(
+  () => props.details?.message || props.message || '',
+  (message, previousMessage) => {
+    if (!message || message === previousMessage) return
+    ElMessage.error({ message, showClose: true, duration: 4500 })
+  },
+  { immediate: true },
+)
+</script>
+
+<template></template>
diff --git a/src/shared/components/PageLayouts.test.ts b/src/shared/components/PageLayouts.test.ts
new file mode 100644
index 00000000..c6e5d1a4
--- /dev/null
+++ b/src/shared/components/PageLayouts.test.ts
@@ -0,0 +1,76 @@
+import { mount } from '@vue/test-utils'
+import { describe, expect, it } from 'vitest'
+import AdminPage from './AdminPage.vue'
+import DetailPageLayout from './DetailPageLayout.vue'
+import FormSection from './FormSection.vue'
+import ListPageLayout from './ListPageLayout.vue'
+import PageToolbar from './PageToolbar.vue'
+
+describe('admin page layout components', () => {
+  it('renders a semantic page root with stable layout classes', () => {
+    const wrapper = mount(AdminPage, {
+      props: { width: 'comfortable', spacing: 'compact' },
+      slots: { default: '<p>内容</p>' },
+    })
+    expect(wrapper.element.tagName).toBe('MAIN')
+    expect(wrapper.classes()).toEqual(expect.arrayContaining(['is-width-comfortable', 'is-spacing-compact']))
+    expect(wrapper.text()).toBe('内容')
+  })
+
+  it('keeps page title and actions in separate regions', () => {
+    const wrapper = mount(PageToolbar, {
+      props: { title: '客户管理', description: '维护客户资料' },
+      slots: { actions: '<button>新增</button>' },
+    })
+    expect(wrapper.get('h1').text()).toBe('客户管理')
+    expect(wrapper.get('.page-toolbar__description').text()).toBe('维护客户资料')
+    expect(wrapper.get('.page-toolbar__actions').text()).toBe('新增')
+  })
+
+  it('renders optional list regions only when supplied', () => {
+    const wrapper = mount(ListPageLayout, {
+      slots: { toolbar: '<div>筛选</div>', default: '<div>表格</div>' },
+    })
+    expect(wrapper.find('.list-page-layout__toolbar').exists()).toBe(true)
+    expect(wrapper.find('.list-page-layout__metrics').exists()).toBe(false)
+    expect(wrapper.text()).toContain('筛选')
+    expect(wrapper.text()).toContain('表格')
+  })
+
+  it('removes registered but empty list regions from flex layout', () => {
+    const wrapper = mount(ListPageLayout, {
+      slots: {
+        toolbar: '<div>筛选</div>',
+        state: '<template v-if="false"><div>错误</div></template>',
+        default: '<div>表格</div>',
+      },
+    })
+    expect(wrapper.find('.list-page-layout__state').exists()).toBe(false)
+    expect(wrapper.text()).toBe('筛选表格')
+  })
+
+  it('keeps plain-text list regions visible', () => {
+    const wrapper = mount(ListPageLayout, {
+      slots: { state: '正在同步', default: '表格内容' },
+    })
+
+    expect(wrapper.get('.list-page-layout__state').text()).toBe('正在同步')
+    expect(wrapper.get('.list-page-layout__content').text()).toBe('表格内容')
+  })
+
+  it('supports detail regions and form section descriptions', () => {
+    const detail = mount(DetailPageLayout, {
+      slots: { header: '<h1>详情</h1>', default: '<p>正文</p>', footer: '<button>保存</button>' },
+    })
+    expect(detail.find('.detail-page-layout__header').exists()).toBe(true)
+    expect(detail.find('.detail-page-layout__footer').text()).toBe('保存')
+
+    const form = mount(FormSection, {
+      props: { title: '基础信息', description: '填写必填字段' },
+      slots: { default: '<input aria-label="名称" />' },
+    })
+    expect(form.get('h2').text()).toBe('基础信息')
+    expect(form.get('.form-section__heading p').text()).toBe('填写必填字段')
+    expect(form.find('input').exists()).toBe(true)
+  })
+})
diff --git a/src/shared/components/PageToolbar.vue b/src/shared/components/PageToolbar.vue
new file mode 100644
index 00000000..54c23401
--- /dev/null
+++ b/src/shared/components/PageToolbar.vue
@@ -0,0 +1,46 @@
+<script setup lang="ts">
+withDefaults(defineProps<{
+  title: string
+  description?: string
+  eyebrow?: string
+  as?: 'header' | 'section'
+}>(), {
+  description: '',
+  eyebrow: '',
+  as: 'header',
+})
+</script>
+
+<template>
+  <component :is="as" class="page-toolbar">
+    <div class="page-toolbar__copy">
+      <p v-if="eyebrow" class="page-toolbar__eyebrow">{{ eyebrow }}</p>
+      <h1>{{ title }}</h1>
+      <p v-if="description" class="page-toolbar__description">{{ description }}</p>
+    </div>
+    <div v-if="$slots.default || $slots.actions" class="page-toolbar__actions">
+      <slot />
+      <slot name="actions" />
+    </div>
+  </component>
+</template>
+
+<style scoped>
+.page-toolbar { display: flex; min-width: 0; align-items: flex-start; justify-content: space-between; gap: 16px; }
+.page-toolbar__copy { min-width: 0; flex: 1; }
+.page-toolbar h1 { margin: 0; color: var(--cc-text, #172033); font-size: 20px; line-height: 1.35; }
+.page-toolbar__eyebrow { margin: 0 0 5px; color: var(--cc-primary); font-size: 11px; font-weight: 700; }
+.page-toolbar__description { margin: 5px 0 0; color: var(--cc-muted, #667085); font-size: 13px; line-height: 1.55; }
+.page-toolbar__actions { display: flex; flex: 0 0 auto; flex-wrap: wrap; justify-content: flex-end; gap: 8px; }
+.page-toolbar__actions :deep(.el-button + .el-button) { margin-left: 0; }
+
+@media (min-width: 1920px) {
+  .page-toolbar { gap: 12px; }
+  .page-toolbar__actions { gap: 6px; }
+}
+@media (max-width: 720px) {
+  .page-toolbar { flex-direction: column; }
+  .page-toolbar__actions { width: 100%; justify-content: flex-start; }
+  .page-toolbar__actions :deep(.el-button) { min-height: 44px; }
+}
+</style>
diff --git a/src/shared/components/QueryToolbar.test.ts b/src/shared/components/QueryToolbar.test.ts
new file mode 100644
index 00000000..ed4d8b5b
--- /dev/null
+++ b/src/shared/components/QueryToolbar.test.ts
@@ -0,0 +1,172 @@
+import { computed, defineComponent } from 'vue'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { shallowMount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it } from 'vitest'
+import QueryToolbar, { type QueryField } from './QueryToolbar.vue'
+import LayoutPreferenceList from './LayoutPreferenceList.vue'
+import { UI_PREFERENCE_SCOPE, preferenceStorageKey } from '@/shared/utils/uiLayoutPreference'
+
+const FieldStub = defineComponent({
+  inheritAttrs: false,
+  props: { placeholder: String },
+  emits: ['keyup'],
+  template: '<input :data-placeholder="placeholder" @keyup="$emit(\'keyup\', $event)" />',
+})
+const ButtonStub = defineComponent({
+  props: { disabled: Boolean, loading: Boolean },
+  template: '<button type="button" :disabled="disabled" :data-loading="String(loading)"><slot /></button>',
+})
+const PopoverStub = defineComponent({ template: '<div><slot name="reference" /><slot /></div>' })
+
+const fields: QueryField[] = [
+  { key: 'keyword', type: 'input', label: '关键词', placeholder: '关键词' },
+  { key: 'status', type: 'select', label: '状态', placeholder: '状态' },
+  { key: 'createdRange', type: 'daterange', label: '创建日期', placeholder: '创建日期' },
+]
+
+function mountToolbar(props: Record<string, unknown> = {}) {
+  return shallowMount(QueryToolbar, {
+    props: {
+      modelValue: { keyword: '', status: '', createdRange: [] },
+      'onUpdate:modelValue': () => undefined,
+      ariaLabel: '订单筛选',
+      fields,
+      preferenceKey: 'orders-query',
+      ...props,
+    },
+    global: {
+      provide: { [UI_PREFERENCE_SCOPE as symbol]: computed(() => 'user-1') },
+      stubs: {
+        ElInput: FieldStub,
+        ElSelect: FieldStub,
+        ElDatePicker: FieldStub,
+        ElButton: ButtonStub,
+        ElPopover: PopoverStub,
+      },
+    },
+  })
+}
+
+describe('QueryToolbar layout preferences', () => {
+  beforeEach(() => localStorage.clear())
+
+  it('restores and updates the user field order', async () => {
+    localStorage.setItem(preferenceStorageKey('query', 'user-1', 'orders-query'), JSON.stringify({
+      version: 1,
+      order: ['status', 'keyword', 'createdRange'],
+      hidden: [],
+    }))
+    const wrapper = mountToolbar()
+    expect(wrapper.findAll('input').map((input) => input.attributes('data-placeholder')))
+      .toEqual(['状态', '关键词', '创建日期'])
+
+    wrapper.findComponent(LayoutPreferenceList).vm.$emit('move', 'createdRange', 0)
+    await wrapper.vm.$nextTick()
+    expect(wrapper.findAll('input').map((input) => input.attributes('data-placeholder')))
+      .toEqual(['创建日期', '状态', '关键词'])
+  })
+
+  it('keeps desktop actions grouped with the final filter when the toolbar wraps', () => {
+    const wrapper = mountToolbar()
+    expect(wrapper.find('.query-toolbar__tail input').attributes('data-placeholder')).toBe('创建日期')
+    expect(wrapper.find('.query-toolbar__tail .query-toolbar__actions').exists()).toBe(true)
+
+    const source = readFileSync(resolve(process.cwd(), 'src/shared/components/QueryToolbar.vue'), 'utf8')
+    expect(source).toContain('.query-toolbar__tail { display: flex; width: auto; max-width: 100%; min-width: 0; flex: 0 1 auto; align-items: flex-end; flex-wrap: wrap; gap: 10px; }')
+    expect(source).not.toContain('.query-toolbar__filters { display: contents; }')
+  })
+
+  it('derives compact widths by field type while explicit business widths win', () => {
+    const compactFields: QueryField[] = [
+      { key: 'status', type: 'select', label: '短状态' },
+      { key: 'date', type: 'date', label: '日期' },
+      { key: 'keyword', type: 'input', label: '长关键词' },
+      { key: 'range', type: 'daterange', label: '日期范围' },
+      { key: 'warehouse', type: 'select', label: '业务显式宽度', width: 236 },
+    ]
+    const wrapper = mountToolbar({
+      modelValue: { status: '', date: '', keyword: '', range: [], warehouse: '' },
+      fields: compactFields,
+      availableFields: compactFields,
+    })
+    const styles = wrapper.findAll('.query-toolbar__field').map((field) => field.attributes('style'))
+    expect(styles).toEqual([
+      '--query-field-width: 180px;',
+      '--query-field-width: 180px;',
+      '--query-field-width: 260px;',
+      '--query-field-width: 300px;',
+      '--query-field-width: 236px;',
+    ])
+  })
+
+  it('keeps a short status and long keyword left aligned without stretching or desktop overflow', () => {
+    const mixedFields: QueryField[] = [
+      { key: 'status', type: 'select', label: '状态' },
+      { key: 'keyword', type: 'input', label: '订单号/入仓码/客户名称' },
+    ]
+    const wrapper = mountToolbar({
+      modelValue: { status: '', keyword: '' },
+      fields: mixedFields,
+      availableFields: mixedFields,
+    })
+    const renderedFields = wrapper.findAll('.query-toolbar__field')
+    expect(renderedFields[0].attributes('style')).toBe('--query-field-width: 180px;')
+    expect(renderedFields[1].attributes('style')).toBe('--query-field-width: 260px;')
+    expect(renderedFields[1].classes()).toContain('query-toolbar__tail')
+    expect(renderedFields[1].find('.query-toolbar__actions').exists()).toBe(true)
+
+    const source = readFileSync(resolve(process.cwd(), 'src/shared/components/QueryToolbar.vue'), 'utf8')
+    expect(source).toContain('justify-content: flex-start; flex-wrap: wrap;')
+    expect(source).toContain('flex: 0 0 var(--query-field-width)')
+    expect(source).toContain('overflow-x: clip')
+    expect(source).toContain('@media (max-width: 720px)')
+    expect(source).toContain('.query-toolbar__field { width: 100%; flex: 0 0 auto; }')
+    expect(source).toContain('.query-toolbar__control { width: 100%; flex: 0 0 auto; }')
+  })
+
+  it('submits the current filters once when Enter is released in a text input', async () => {
+    const wrapper = mountToolbar({ modelValue: { keyword: 'AKR1', status: 'ACTIVE', createdRange: [] } })
+    const textInput = wrapper.findAll('input')[0]
+
+    await textInput.trigger('keyup', { key: 'Enter' })
+
+    expect(wrapper.emitted('search')).toEqual([[
+      { keyword: 'AKR1', status: 'ACTIVE', createdRange: [] },
+    ]])
+  })
+
+  it('does not submit Enter from select or date controls, composition, or repeated key events', async () => {
+    const wrapper = mountToolbar()
+    const controls = wrapper.findAll('input')
+
+    await controls[1].trigger('keyup', { key: 'Enter' })
+    await controls[2].trigger('keyup', { key: 'Enter' })
+    await controls[0].trigger('keyup', { key: 'Enter', isComposing: true })
+    await controls[0].trigger('keyup', { key: 'Enter', repeat: true })
+
+    expect(wrapper.emitted('search')).toBeUndefined()
+  })
+
+  it('resets all filters once and blocks search and reset while loading', async () => {
+    const wrapper = mountToolbar({
+      modelValue: { keyword: 'AKR1', status: 'ACTIVE', createdRange: ['2026-08-01', '2026-08-14'] },
+    })
+
+    ;(wrapper.vm as unknown as { reset: () => void }).reset()
+    expect(wrapper.emitted('reset')).toEqual([[
+      { keyword: '', status: '', createdRange: [] },
+    ]])
+    expect(wrapper.emitted('search')).toEqual([[
+      { keyword: '', status: '', createdRange: [] },
+    ]])
+
+    await wrapper.setProps({ loading: true })
+    ;(wrapper.vm as unknown as { search: () => void; reset: () => void }).search()
+    ;(wrapper.vm as unknown as { search: () => void; reset: () => void }).reset()
+    expect(wrapper.emitted('search')).toHaveLength(1)
+    expect(wrapper.emitted('reset')).toHaveLength(1)
+    expect(wrapper.findAllComponents(ButtonStub)[0].props('loading')).toBe(true)
+    expect(wrapper.findAllComponents(ButtonStub)[1].props('disabled')).toBe(true)
+  })
+})
diff --git a/src/shared/components/QueryToolbar.vue b/src/shared/components/QueryToolbar.vue
new file mode 100644
index 00000000..4145b589
--- /dev/null
+++ b/src/shared/components/QueryToolbar.vue
@@ -0,0 +1,273 @@
+<script setup lang="ts">
+import { computed, inject, ref, watch } from 'vue'
+import { Search, RotateCcw, Settings2 } from '@lucide/vue'
+import LayoutPreferenceList, { type LayoutPreferenceItem } from './LayoutPreferenceList.vue'
+import {
+  UI_PREFERENCE_SCOPE,
+  readLayoutPreference,
+  removeLayoutPreference,
+  writeLayoutPreference,
+  type LayoutPreferenceSnapshot,
+} from '@/shared/utils/uiLayoutPreference'
+
+defineOptions({ inheritAttrs: false })
+
+export type QueryFieldType = 'input' | 'select' | 'date' | 'daterange'
+export type QueryValue = string | number | boolean | null | undefined | string[] | number[] | Date | Date[]
+export type QueryModel = Record<string, QueryValue>
+
+export interface QueryOption {
+  label: string
+  value: string | number | boolean
+  disabled?: boolean
+}
+
+export interface QueryField {
+  key: string
+  type: QueryFieldType
+  label: string
+  width?: string | number
+  placeholder?: string
+  options?: QueryOption[]
+  props?: Record<string, unknown>
+}
+
+const props = withDefaults(defineProps<{
+  ariaLabel: string
+  fields: QueryField[]
+  availableFields?: QueryField[]
+  preferenceKey?: string
+  searchText?: string
+  resetText?: string
+  searchOnReset?: boolean
+  searchOnClear?: boolean
+  loading?: boolean
+}>(), {
+  searchText: '查询',
+  resetText: '重置',
+  searchOnReset: true,
+  searchOnClear: true,
+  loading: false,
+})
+
+const model = defineModel<QueryModel>({ required: true })
+const emit = defineEmits<{
+  search: [model: QueryModel]
+  reset: [model: QueryModel]
+}>()
+const preferenceScope = inject(UI_PREFERENCE_SCOPE, computed(() => 'anonymous'))
+const preference = ref<LayoutPreferenceSnapshot>({ version: 1, order: [], hidden: [] })
+const preferenceFields = computed(() => props.availableFields ?? props.fields)
+const preferenceFieldKeys = computed(() => preferenceFields.value.map((field) => field.key))
+const preferenceEnabled = computed(() => Boolean(props.preferenceKey))
+
+function fieldLabel(field: QueryField) {
+  const ariaLabel = field.props?.['aria-label']
+  return field.label || (typeof ariaLabel === 'string' ? ariaLabel : '') || field.placeholder || field.key
+}
+
+function applyPreference() {
+  preference.value = readLayoutPreference(
+    'query',
+    preferenceScope.value,
+    props.preferenceKey || '',
+    preferenceFieldKeys.value,
+  )
+}
+
+watch(
+  [preferenceScope, () => props.preferenceKey, () => preferenceFieldKeys.value.join('\u0000')],
+  applyPreference,
+  { immediate: true },
+)
+
+const orderedPreferenceFields = computed(() => {
+  const fieldsByKey = new Map(preferenceFields.value.map((field) => [field.key, field]))
+  return preference.value.order.flatMap((key) => {
+    const field = fieldsByKey.get(key)
+    return field ? [field] : []
+  })
+})
+const orderedFields = computed(() => {
+  const visibleKeys = new Set(props.fields.map((field) => field.key))
+  return orderedPreferenceFields.value.filter((field) => visibleKeys.has(field.key))
+})
+const preferenceItems = computed<LayoutPreferenceItem[]>(() => orderedPreferenceFields.value.map((field) => ({
+  key: field.key,
+  label: fieldLabel(field),
+  visible: true,
+  hideable: false,
+  movable: true,
+})))
+
+function persistPreference(order: string[]) {
+  preference.value = { version: 1, order, hidden: [] }
+  writeLayoutPreference('query', preferenceScope.value, props.preferenceKey || '', preference.value)
+}
+
+function moveField(key: string, targetIndex: number) {
+  const order = [...preference.value.order]
+  const currentIndex = order.indexOf(key)
+  if (currentIndex < 0) return
+  order.splice(currentIndex, 1)
+  order.splice(Math.min(Math.max(targetIndex, 0), order.length), 0, key)
+  persistPreference(order)
+}
+
+function resetPreference() {
+  removeLayoutPreference('query', preferenceScope.value, props.preferenceKey || '')
+  applyPreference()
+}
+
+function updateField(key: string, value: QueryValue) {
+  model.value[key] = value
+}
+
+function defaultPlaceholder(field: QueryField) {
+  if (field.type === 'input') return '请输入关键词'
+  if (field.type === 'select') return '全部'
+  return field.type === 'daterange' ? '请选择日期范围' : '请选择日期'
+}
+
+function datePickerType(field: QueryField): 'date' | 'daterange' {
+  return field.type === 'daterange' ? 'daterange' : 'date'
+}
+
+const defaultFieldWidths: Record<QueryFieldType, number> = {
+  select: 180,
+  date: 180,
+  input: 260,
+  daterange: 300,
+}
+
+function fieldStyle(field: QueryField) {
+  const fieldWidth = field.width ?? defaultFieldWidths[field.type]
+  const width = typeof fieldWidth === 'number' ? `${fieldWidth}px` : fieldWidth
+  return { '--query-field-width': width }
+}
+
+function resetValue(field: QueryField): QueryValue {
+  return field.type === 'daterange' ? [] : ''
+}
+
+function search() {
+  if (props.loading) return
+  emit('search', model.value)
+}
+
+function clearInput() {
+  if (props.searchOnClear) search()
+}
+
+function reset() {
+  if (props.loading) return
+  for (const field of props.fields) model.value[field.key] = resetValue(field)
+  emit('reset', model.value)
+  if (props.searchOnReset) emit('search', model.value)
+}
+
+function searchFromTextInput(event: KeyboardEvent) {
+  if (event.isComposing || event.repeat) return
+  search()
+}
+
+defineExpose({ search, reset })
+</script>
+
+<template>
+  <section
+    v-bind="$attrs"
+    class="query-toolbar"
+    :aria-label="ariaLabel"
+  >
+    <div class="query-toolbar__filters">
+      <div
+        v-for="(field, index) in orderedFields"
+        :key="field.key"
+        :class="['query-toolbar__field', { 'query-toolbar__tail': index === orderedFields.length - 1 }]"
+        :style="fieldStyle(field)"
+      >
+        <div class="query-toolbar__control">
+          <el-input
+          v-if="field.type === 'input'"
+          :model-value="model[field.key] as string"
+          :placeholder="field.placeholder || defaultPlaceholder(field)"
+          clearable
+          v-bind="field.props"
+          @update:model-value="updateField(field.key, $event)"
+          @clear="clearInput"
+          @keyup.enter.exact="searchFromTextInput"
+          >
+            <template #prefix><Search :size="16" /></template>
+          </el-input>
+          <el-select
+          v-else-if="field.type === 'select'"
+          :model-value="model[field.key] as string | number | boolean | undefined"
+          :placeholder="field.placeholder || defaultPlaceholder(field)"
+          clearable
+          v-bind="field.props"
+          @update:model-value="updateField(field.key, $event)"
+          >
+            <el-option v-for="option in field.options || []" :key="String(option.value)" :label="option.label" :value="option.value" :disabled="option.disabled" />
+          </el-select>
+          <el-date-picker
+          v-else
+          :model-value="model[field.key] as string | string[] | undefined"
+          :type="datePickerType(field)"
+          :placeholder="field.placeholder || defaultPlaceholder(field)"
+          clearable
+          value-format="YYYY-MM-DD"
+          range-separator="至"
+          start-placeholder="开始日期"
+          end-placeholder="结束日期"
+          v-bind="field.props"
+            @update:model-value="updateField(field.key, $event)"
+          />
+        </div>
+        <div v-if="index === orderedFields.length - 1" class="query-toolbar__actions">
+          <el-button type="primary" :loading="loading" @click="search"><Search :size="16" />{{ searchText }}</el-button>
+          <el-button :disabled="loading" @click="reset"><RotateCcw :size="16" />{{ resetText }}</el-button>
+          <slot name="actions" />
+          <el-popover v-if="preferenceEnabled" placement="bottom-end" :width="340" trigger="click" popper-class="cc-layout-preference-popper">
+            <template #reference>
+              <el-button aria-label="调整筛选布局" title="调整筛选布局"><Settings2 :size="16" /></el-button>
+            </template>
+            <LayoutPreferenceList :items="preferenceItems" @move="moveField" @reset="resetPreference" />
+          </el-popover>
+        </div>
+      </div>
+    </div>
+    <div v-if="orderedFields.length === 0" class="query-toolbar__actions">
+      <el-button type="primary" :loading="loading" @click="search"><Search :size="16" />{{ searchText }}</el-button>
+      <el-button :disabled="loading" @click="reset"><RotateCcw :size="16" />{{ resetText }}</el-button>
+      <slot name="actions" />
+      <el-popover v-if="preferenceEnabled" placement="bottom-end" :width="340" trigger="click" popper-class="cc-layout-preference-popper">
+        <template #reference>
+          <el-button aria-label="调整筛选布局" title="调整筛选布局"><Settings2 :size="16" /></el-button>
+        </template>
+        <LayoutPreferenceList :items="preferenceItems" @move="moveField" @reset="resetPreference" />
+      </el-popover>
+    </div>
+  </section>
+</template>
+
+<style scoped>
+.query-toolbar { box-sizing: border-box; display: flex; width: 100%; min-width: 0; align-items: flex-end; justify-content: flex-start; flex-wrap: wrap; gap: 10px; overflow-x: clip; padding: 16px; border: 1px solid var(--cc-border); background: #fff; }
+.query-toolbar__filters { display: flex; width: 100%; min-width: 0; flex: 1 1 100%; align-items: flex-end; justify-content: flex-start; flex-wrap: wrap; gap: 12px 16px; }
+.query-toolbar__field { display: grid; width: var(--query-field-width); max-width: 100%; min-width: 0; flex: 0 0 var(--query-field-width); gap: 6px; }
+.query-toolbar__control { display: grid; width: var(--query-field-width); max-width: 100%; min-width: 0; flex: 0 0 var(--query-field-width); gap: 6px; }
+.query-toolbar__field :deep(.el-input), .query-toolbar__field :deep(.el-select), .query-toolbar__field :deep(.el-date-editor) { width: 100%; max-width: 100%; min-width: 0; }
+.query-toolbar__field :deep(.el-input__inner), .query-toolbar__field :deep(.el-select__selected-item), .query-toolbar__field :deep(.el-date-editor), .query-toolbar__actions :deep(.el-button) { font-size: var(--cc-list-query-font-size); }
+.query-toolbar__actions { display: flex; max-width: 100%; min-width: 0; flex: 0 0 auto; flex-wrap: wrap; justify-content: flex-start; gap: 8px; }
+.query-toolbar__actions :deep(.el-button + .el-button) { margin-left: 0; }
+:global(.cc-layout-preference-popper) { max-width: calc(100vw - 24px); }
+
+@media (min-width: 1920px) {
+  .query-toolbar { padding: 12px; gap: 8px; }
+  .query-toolbar__filters { gap: 8px 12px; }
+  .query-toolbar__field, .query-toolbar__control { gap: 4px; }
+  .query-toolbar__actions { gap: 6px; }
+}
+@media (min-width: 721px) { .query-toolbar__tail { display: flex; width: auto; max-width: 100%; min-width: 0; flex: 0 1 auto; align-items: flex-end; flex-wrap: wrap; gap: 10px; } .query-toolbar__tail > .query-toolbar__control { flex: 0 0 var(--query-field-width); } }
+@media (max-width: 720px) { .query-toolbar { align-items: stretch; flex-direction: column; } .query-toolbar__filters { width: 100%; flex-direction: column; } .query-toolbar__field { width: 100%; flex: 0 0 auto; } .query-toolbar__tail { display: contents; } .query-toolbar__control { width: 100%; flex: 0 0 auto; } .query-toolbar__actions { display: grid; grid-template-columns: repeat(auto-fit, minmax(120px, 1fr)); width: 100%; } .query-toolbar__actions :deep(.el-button) { min-height: 40px; margin-left: 0; } }
+</style>
diff --git a/src/shared/components/StatusBadge.vue b/src/shared/components/StatusBadge.vue
new file mode 100644
index 00000000..cd737b4b
--- /dev/null
+++ b/src/shared/components/StatusBadge.vue
@@ -0,0 +1,17 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+
+const props = defineProps<{ status: string }>()
+
+const tone = computed(() => {
+  if (['正常', '启用', '已完成', '已审核', '审核通过', '已入库', '已出库', '装柜完成', '派送完成', '已确认', '已放舱'].includes(props.status)) return 'success'
+  if (['待审核', '草稿', '待处理', '待分配', '未提交', '未录入', '待测量数据', '待分柜', '待装柜', '预装柜中', '待拣货', '待出库', '已拣货', '变更中'].includes(props.status)) return 'warning'
+  if (['已受理', '已订舱', '已提交', '运输中', '处理中', '拣货中', '装柜中'].includes(props.status)) return 'info'
+  if (['停用', '已取消', '已驳回', '审核驳回', '失败', '订舱失败'].includes(props.status)) return 'danger'
+  return 'neutral'
+})
+</script>
+
+<template>
+  <span class="status-badge" :class="`is-${tone}`"><i aria-hidden="true" />{{ status }}</span>
+</template>
diff --git a/src/shared/components/exportTaskCreatedDialog.test.ts b/src/shared/components/exportTaskCreatedDialog.test.ts
new file mode 100644
index 00000000..af5bcb33
--- /dev/null
+++ b/src/shared/components/exportTaskCreatedDialog.test.ts
@@ -0,0 +1,30 @@
+import { ElMessageBox } from 'element-plus'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { showExportTaskCreatedDialog } from './exportTaskCreatedDialog'
+
+describe('showExportTaskCreatedDialog', () => {
+  beforeEach(() => vi.restoreAllMocks())
+
+  it('offers a direct path to the download center with the task reference', async () => {
+    const confirm = vi.spyOn(ElMessageBox, 'confirm').mockResolvedValue({} as never)
+
+    await expect(showExportTaskCreatedDialog({ taskName: '客户列表', taskNo: 'EXP2084' })).resolves.toBe(true)
+    expect(confirm).toHaveBeenCalledWith(
+      expect.stringContaining('任务编号：EXP2084'),
+      '导出任务已创建',
+      expect.objectContaining({ confirmButtonText: '前往下载中心', cancelButtonText: '留在当前页' }),
+    )
+  })
+
+  it.each([false, true])('opts into the shared dialog style explicitly: %s', async (dense) => {
+    const confirm = vi.spyOn(ElMessageBox, 'confirm').mockResolvedValue({} as never)
+    await showExportTaskCreatedDialog({ taskName: '财务导出', dense })
+    expect(confirm).toHaveBeenCalledWith(expect.any(String), '导出任务已创建', expect.objectContaining({ customClass: dense ? 'admin-density-confirm' : undefined }))
+  })
+
+  it('keeps the user on the current page when the dialog is dismissed', async () => {
+    vi.spyOn(ElMessageBox, 'confirm').mockRejectedValue('cancel')
+
+    await expect(showExportTaskCreatedDialog({ taskName: '客户列表' })).resolves.toBe(false)
+  })
+})
diff --git a/src/shared/components/exportTaskCreatedDialog.ts b/src/shared/components/exportTaskCreatedDialog.ts
new file mode 100644
index 00000000..b53d152f
--- /dev/null
+++ b/src/shared/components/exportTaskCreatedDialog.ts
@@ -0,0 +1,28 @@
+import { ElMessageBox } from 'element-plus'
+
+export interface ExportTaskCreatedDialogOptions {
+  taskName: string
+  taskNo?: string | null
+  dense?: boolean
+}
+
+export async function showExportTaskCreatedDialog(options: ExportTaskCreatedDialogOptions) {
+  const taskReference = options.taskNo ? `\n任务编号：${options.taskNo}` : ''
+
+  try {
+    await ElMessageBox.confirm(
+      `${options.taskName}已进入后台生成队列。文件生成后可在下载中心查看并下载。${taskReference}`,
+      '导出任务已创建',
+      {
+        type: 'success',
+        customClass: options.dense ? 'admin-density-confirm' : undefined,
+        confirmButtonText: '前往下载中心',
+        cancelButtonText: '留在当前页',
+        distinguishCancelAndClose: true,
+      },
+    )
+    return true
+  } catch {
+    return false
+  }
+}
diff --git a/src/shared/domain/containerSpecifications.test.ts b/src/shared/domain/containerSpecifications.test.ts
new file mode 100644
index 00000000..12dd231f
--- /dev/null
+++ b/src/shared/domain/containerSpecifications.test.ts
@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest'
+import { CONTAINER_SPECIFICATIONS, DEFAULT_CONTAINER_TYPE, containerSpecification } from './containerSpecifications'
+
+describe('container specifications', () => {
+  it('uses the three confirmed container types and defaults to 40HQ', () => {
+    expect(CONTAINER_SPECIFICATIONS.map((item) => item.type)).toEqual(['40GP', '40HQ', '45HQ'])
+    expect(DEFAULT_CONTAINER_TYPE).toBe('40HQ')
+  })
+
+  it('keeps practical loading ranges and the common cargo weight limit', () => {
+    expect(CONTAINER_SPECIFICATIONS.map(({ type, recommendedMinCbm, capacityCbm, maxWeightKg }) => (
+      { type, recommendedMinCbm, capacityCbm, maxWeightKg }
+    ))).toEqual([
+      { type: '40GP', recommendedMinCbm: 56, capacityCbm: 58, maxWeightKg: 19500 },
+      { type: '40HQ', recommendedMinCbm: 65, capacityCbm: 68, maxWeightKg: 19500 },
+      { type: '45HQ', recommendedMinCbm: 82, capacityCbm: 86, maxWeightKg: 19500 },
+    ])
+    expect(containerSpecification('40hc')).toBeNull()
+  })
+})
diff --git a/src/shared/domain/containerSpecifications.ts b/src/shared/domain/containerSpecifications.ts
new file mode 100644
index 00000000..db0a5136
--- /dev/null
+++ b/src/shared/domain/containerSpecifications.ts
@@ -0,0 +1,24 @@
+export const CONTAINER_SPECIFICATIONS = [
+  { type: '40GP', recommendedMinCbm: 56, capacityCbm: 58, maxWeightKg: 19500, description: '美线电商较少使用，通常优先选择 40HQ' },
+  { type: '40HQ', recommendedMinCbm: 65, capacityCbm: 68, maxWeightKg: 19500, description: '轻泡货首选，适合家居、玩具、日用品' },
+  { type: '45HQ', recommendedMinCbm: 82, capacityCbm: 86, maxWeightKg: 19500, description: '抛货量大时考虑，底盘和海外仓预约资源较少' },
+] as const
+
+export const DEFAULT_CONTAINER_TYPE = '40HQ' as const
+
+export type ContainerSpecification = (typeof CONTAINER_SPECIFICATIONS)[number]
+export type ContainerType = ContainerSpecification['type']
+
+export function containerSpecification(containerType: string | null | undefined): ContainerSpecification | null {
+  const normalized = String(containerType || '').trim().toUpperCase()
+  return CONTAINER_SPECIFICATIONS.find((item) => item.type === normalized) || null
+}
+
+export function applyContainerSpecification<T extends { containerType: string; capacityCbm: number | null; maxWeightKg: number | null }>(target: T, containerType: string) {
+  const specification = containerSpecification(containerType)
+  if (!specification) return false
+  target.containerType = specification.type
+  target.capacityCbm = specification.capacityCbm
+  target.maxWeightKg = specification.maxWeightKg
+  return true
+}
diff --git a/src/shared/downloadCsv.ts b/src/shared/downloadCsv.ts
new file mode 100644
index 00000000..92c6832f
--- /dev/null
+++ b/src/shared/downloadCsv.ts
@@ -0,0 +1,6 @@
+export function saveCsv(blob: Blob, fileName: string) {
+  const url = URL.createObjectURL(blob)
+  const anchor = document.createElement('a')
+  try { anchor.href = url; anchor.download = fileName; anchor.click() }
+  finally { URL.revokeObjectURL(url) }
+}
diff --git a/src/shared/types/platformPermission.ts b/src/shared/types/platformPermission.ts
new file mode 100644
index 00000000..6a6c60f7
--- /dev/null
+++ b/src/shared/types/platformPermission.ts
@@ -0,0 +1,14 @@
+export interface PlatformPermissionResource {
+  id: number | string
+  tenantId: number | string
+  appCode: 'PLATFORM'
+  permissionType: 'MENU' | 'PAGE' | 'BUTTON' | 'API'
+  parentId: number | string
+  permissionCode: string
+  permissionName: string
+  routePath: string | null
+  httpMethod: string | null
+  sortNo: number
+  status: 'ACTIVE' | 'DISABLED' | 'INACTIVE'
+  builtIn?: boolean
+}
diff --git a/src/shared/utils/copyText.test.ts b/src/shared/utils/copyText.test.ts
new file mode 100644
index 00000000..59ef4ec0
--- /dev/null
+++ b/src/shared/utils/copyText.test.ts
@@ -0,0 +1,31 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { copyText } from './copyText'
+
+describe('copyText', () => {
+  afterEach(() => {
+    vi.restoreAllMocks()
+    vi.unstubAllGlobals()
+    Reflect.deleteProperty(document, 'execCommand')
+    document.querySelectorAll('textarea[aria-hidden="true"]').forEach((element) => element.remove())
+  })
+
+  it('uses the Clipboard API when it is available', async () => {
+    const writeText = vi.fn().mockResolvedValue(undefined)
+    vi.stubGlobal('navigator', { clipboard: { writeText } })
+
+    await copyText('request-123')
+
+    expect(writeText).toHaveBeenCalledWith('request-123')
+  })
+
+  it('falls back to a temporary textarea when Clipboard API access is denied', async () => {
+    vi.stubGlobal('navigator', { clipboard: { writeText: vi.fn().mockRejectedValue(new Error('denied')) } })
+    const execCommand = vi.fn().mockReturnValue(true)
+    Object.defineProperty(document, 'execCommand', { configurable: true, value: execCommand })
+
+    await copyText('trace-456')
+
+    expect(execCommand).toHaveBeenCalledWith('copy')
+    expect(document.querySelector('textarea[aria-hidden="true"]')).toBeNull()
+  })
+})
diff --git a/src/shared/utils/copyText.ts b/src/shared/utils/copyText.ts
new file mode 100644
index 00000000..bbc3acbd
--- /dev/null
+++ b/src/shared/utils/copyText.ts
@@ -0,0 +1,35 @@
+export async function copyText(value: string) {
+  if (typeof navigator !== 'undefined' && navigator.clipboard?.writeText) {
+    try {
+      await navigator.clipboard.writeText(value)
+      return
+    } catch {
+      // In insecure development contexts the Clipboard API may exist but reject.
+    }
+  }
+
+  if (typeof document === 'undefined' || !document.body) {
+    throw new Error('Clipboard is unavailable')
+  }
+
+  const textarea = document.createElement('textarea')
+  textarea.value = value
+  textarea.readOnly = true
+  textarea.setAttribute('aria-hidden', 'true')
+  Object.assign(textarea.style, {
+    position: 'fixed',
+    inset: '0 auto auto -9999px',
+    opacity: '0',
+    pointerEvents: 'none',
+  })
+  document.body.appendChild(textarea)
+  textarea.select()
+
+  try {
+    if (typeof document.execCommand !== 'function' || !document.execCommand('copy')) {
+      throw new Error('Clipboard copy failed')
+    }
+  } finally {
+    textarea.remove()
+  }
+}
diff --git a/src/shared/utils/firstLegBusinessLabels.test.ts b/src/shared/utils/firstLegBusinessLabels.test.ts
new file mode 100644
index 00000000..84d87469
--- /dev/null
+++ b/src/shared/utils/firstLegBusinessLabels.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+import {
+  firstLegBusinessTypeLabel, firstLegContainerModeLabel, firstLegDestinationTypeLabel,
+  firstLegPickupMethodLabel, firstLegTaxModeLabel, firstLegTradeTermLabel, firstLegTransportModeLabel,
+} from './firstLegBusinessLabels'
+
+describe('first-leg business labels', () => {
+  it('translates business codes using the customer order contract', () => {
+    expect(firstLegTransportModeLabel('SEA')).toBe('海运')
+    expect(firstLegTradeTermLabel('FOB')).toBe('FOB（离岸价）')
+    expect(firstLegPickupMethodLabel('PICKUP')).toBe('平台上门提货')
+    expect(firstLegTaxModeLabel('BUY_DECLARATION')).toBe('买单报关')
+    expect(firstLegContainerModeLabel('FULL_CONTAINER')).toBe('整柜')
+    expect(firstLegDestinationTypeLabel('OVERSEAS')).toBe('海外仓')
+    expect(firstLegBusinessTypeLabel('OVERSEAS_SEA')).toBe('海外仓海运')
+    expect(firstLegBusinessTypeLabel('PRIVATE_SEA')).toBe('私人地址海运')
+    expect(firstLegBusinessTypeLabel('EXPORT')).toBe('出口业务')
+  })
+
+  it('does not expose unknown backend codes', () => {
+    expect(firstLegTransportModeLabel('NEW_MODE')).toBe('未知类型')
+    expect(firstLegTaxModeLabel(null)).toBe('—')
+  })
+})
diff --git a/src/shared/utils/firstLegBusinessLabels.ts b/src/shared/utils/firstLegBusinessLabels.ts
new file mode 100644
index 00000000..f65d721c
--- /dev/null
+++ b/src/shared/utils/firstLegBusinessLabels.ts
@@ -0,0 +1,32 @@
+const businessTypeLabels: Record<string, string> = {
+  EXPORT: '出口业务', FIRST_LEG: '头程物流', FBA: 'FBA 头程', FBA_SEA: 'FBA 海运', OVERSEAS_SEA: '海外仓海运', PRIVATE_SEA: '私人地址海运',
+}
+const transportModeLabels: Record<string, string> = {
+  SEA: '海运', AIR: '空运', RAIL: '铁路运输', TRUCK: '卡车运输',
+}
+const tradeTermLabels: Record<string, string> = {
+  EXW: 'EXW（工厂交货）', FCA: 'FCA（货交承运人）', FOB: 'FOB（离岸价）',
+  CFR: 'CFR（成本加运费）', CIF: 'CIF（成本、保险费加运费）',
+  DDU: 'DDU（未完税交货）', DDP: 'DDP（完税后交货）',
+}
+const pickupMethodLabels: Record<string, string> = {
+  SELF_EXPRESS: '自行快递到仓', PICKUP: '平台上门提货', SELF_TRUCK: '自行送货到仓', WAREHOUSE: '送至平台仓库',
+}
+const taxModeLabels: Record<string, string> = {
+  BUY_DECLARATION: '买单报关', TAX_REFUND: '退税报关', TAX_INCLUDED: '包税', TAX_EXCLUDED: '不包税', DDP: '包税', DDU: '不包税',
+}
+const containerModeLabels: Record<string, string> = { FULL_CONTAINER: '整柜', FCL: '整柜', LCL: '拼箱' }
+const destinationTypeLabels: Record<string, string> = { FBA: 'FBA 仓', OVERSEAS: '海外仓', PRIVATE: '私人地址' }
+
+function label(value: string | null | undefined, labels: Record<string, string>) {
+  if (!value) return '—'
+  return labels[value.trim().toUpperCase()] || '未知类型'
+}
+
+export const firstLegBusinessTypeLabel = (value: string | null | undefined) => label(value, businessTypeLabels)
+export const firstLegTransportModeLabel = (value: string | null | undefined) => label(value, transportModeLabels)
+export const firstLegTradeTermLabel = (value: string | null | undefined) => label(value, tradeTermLabels)
+export const firstLegPickupMethodLabel = (value: string | null | undefined) => label(value, pickupMethodLabels)
+export const firstLegTaxModeLabel = (value: string | null | undefined) => label(value, taxModeLabels)
+export const firstLegContainerModeLabel = (value: string | null | undefined) => label(value, containerModeLabels)
+export const firstLegDestinationTypeLabel = (value: string | null | undefined) => label(value, destinationTypeLabels)
diff --git a/src/shared/utils/uiLayoutPreference.test.ts b/src/shared/utils/uiLayoutPreference.test.ts
new file mode 100644
index 00000000..87acf1ed
--- /dev/null
+++ b/src/shared/utils/uiLayoutPreference.test.ts
@@ -0,0 +1,65 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+import {
+  preferenceStorageKey,
+  readLayoutPreference,
+  reconcileOrder,
+  removeLayoutPreference,
+  writeLayoutPreference,
+} from './uiLayoutPreference'
+
+describe('UI layout preferences', () => {
+  beforeEach(() => localStorage.clear())
+
+  it('reconciles stored order with the current stable keys', () => {
+    expect(reconcileOrder(['actions', 'name', 'status', 'createdAt'], ['status', 'removed', 'name', 'status']))
+      .toEqual(['status', 'name', 'actions', 'createdAt'])
+  })
+
+  it('falls back safely when cached JSON is invalid', () => {
+    localStorage.setItem(preferenceStorageKey('table', 'user-1', 'customers'), '{broken')
+    expect(readLayoutPreference('table', 'user-1', 'customers', ['actions', 'name'], ['name']))
+      .toEqual({ version: 1, order: ['actions', 'name'], hidden: ['name'] })
+  })
+
+  it('hides newly introduced default-hidden fields without overriding existing visibility choices', () => {
+    writeLayoutPreference('table', 'user-1', 'roles', {
+      version: 1,
+      order: ['actions', 'role', 'status'],
+      hidden: ['status'],
+    })
+
+    expect(readLayoutPreference(
+      'table',
+      'user-1',
+      'roles',
+      ['actions', 'role', 'roleCode', 'status'],
+      ['roleCode', 'status'],
+    )).toEqual({
+      version: 1,
+      order: ['actions', 'role', 'status', 'roleCode'],
+      hidden: ['status', 'roleCode'],
+    })
+
+    writeLayoutPreference('table', 'user-1', 'roles', {
+      version: 1,
+      order: ['actions', 'role', 'roleCode', 'status'],
+      hidden: [],
+    })
+    expect(readLayoutPreference(
+      'table',
+      'user-1',
+      'roles',
+      ['actions', 'role', 'roleCode', 'status'],
+      ['roleCode'],
+    ).hidden).toEqual([])
+  })
+
+  it('keeps preferences isolated by user and removes them on reset', () => {
+    writeLayoutPreference('query', 'user-1', 'orders', { version: 1, order: ['status', 'keyword'], hidden: [] })
+    expect(readLayoutPreference('query', 'user-1', 'orders', ['keyword', 'status']).order).toEqual(['status', 'keyword'])
+    expect(readLayoutPreference('query', 'user-2', 'orders', ['keyword', 'status']).order).toEqual(['keyword', 'status'])
+
+    removeLayoutPreference('query', 'user-1', 'orders')
+    expect(readLayoutPreference('query', 'user-1', 'orders', ['keyword', 'status']).order).toEqual(['keyword', 'status'])
+  })
+})
diff --git a/src/shared/utils/uiLayoutPreference.ts b/src/shared/utils/uiLayoutPreference.ts
new file mode 100644
index 00000000..fed0dbb0
--- /dev/null
+++ b/src/shared/utils/uiLayoutPreference.ts
@@ -0,0 +1,83 @@
+import type { ComputedRef, InjectionKey } from 'vue'
+
+export type LayoutPreferenceKind = 'query' | 'table'
+
+export interface LayoutPreferenceSnapshot {
+  version: 1
+  order: string[]
+  hidden: string[]
+}
+
+export const UI_PREFERENCE_SCOPE: InjectionKey<ComputedRef<string>> = Symbol('ui-preference-scope')
+
+function uniqueKeys(values: readonly unknown[]) {
+  const seen = new Set<string>()
+  return values.flatMap((value) => {
+    if (typeof value !== 'string' || !value || seen.has(value)) return []
+    seen.add(value)
+    return [value]
+  })
+}
+
+export function preferenceStorageKey(kind: LayoutPreferenceKind, scope: string, preferenceKey: string) {
+  return `cc-admin-${kind}-layout:v1:${scope}:${preferenceKey}`
+}
+
+export function reconcileOrder(availableKeys: readonly string[], storedOrder: readonly string[]) {
+  const available = uniqueKeys(availableKeys)
+  const availableSet = new Set(available)
+  const retained = uniqueKeys(storedOrder).filter((key) => availableSet.has(key))
+  const retainedSet = new Set(retained)
+  return [...retained, ...available.filter((key) => !retainedSet.has(key))]
+}
+
+export function readLayoutPreference(
+  kind: LayoutPreferenceKind,
+  scope: string,
+  preferenceKey: string,
+  availableKeys: readonly string[],
+  defaultHidden: readonly string[] = [],
+): LayoutPreferenceSnapshot {
+  const fallback: LayoutPreferenceSnapshot = {
+    version: 1,
+    order: reconcileOrder(availableKeys, []),
+    hidden: uniqueKeys(defaultHidden).filter((key) => availableKeys.includes(key)),
+  }
+  if (!scope || !preferenceKey) return fallback
+  try {
+    const parsed = JSON.parse(localStorage.getItem(preferenceStorageKey(kind, scope, preferenceKey)) || 'null') as Partial<LayoutPreferenceSnapshot> | null
+    if (!parsed || parsed.version !== 1 || !Array.isArray(parsed.order) || !Array.isArray(parsed.hidden)) return fallback
+    const storedKeys = new Set(uniqueKeys(parsed.order))
+    const newlyDefaultHidden = uniqueKeys(defaultHidden).filter((key) => availableKeys.includes(key) && !storedKeys.has(key))
+    return {
+      version: 1,
+      order: reconcileOrder(availableKeys, parsed.order),
+      hidden: uniqueKeys([...parsed.hidden, ...newlyDefaultHidden]).filter((key) => availableKeys.includes(key)),
+    }
+  } catch {
+    return fallback
+  }
+}
+
+export function writeLayoutPreference(
+  kind: LayoutPreferenceKind,
+  scope: string,
+  preferenceKey: string,
+  snapshot: LayoutPreferenceSnapshot,
+) {
+  if (!scope || !preferenceKey) return
+  try {
+    localStorage.setItem(preferenceStorageKey(kind, scope, preferenceKey), JSON.stringify(snapshot))
+  } catch {
+    // Layout preferences are optional and must never block business workflows.
+  }
+}
+
+export function removeLayoutPreference(kind: LayoutPreferenceKind, scope: string, preferenceKey: string) {
+  if (!scope || !preferenceKey) return
+  try {
+    localStorage.removeItem(preferenceStorageKey(kind, scope, preferenceKey))
+  } catch {
+    // Ignore unavailable browser storage and keep the in-memory default layout.
+  }
+}
diff --git a/src/stores/accessPreview.test.ts b/src/stores/accessPreview.test.ts
deleted file mode 100644
index 80f26f8e..00000000
--- a/src/stores/accessPreview.test.ts
+++ /dev/null
@@ -1,200 +0,0 @@
-import { beforeEach, describe, expect, expectTypeOf, it, vi } from 'vitest'
-import { createPinia, setActivePinia } from 'pinia'
-import { nextTick } from 'vue'
-import { getNavigationLeaves } from '@/navigation/adminNavigation'
-import { useAdminDataStore } from '@/stores/adminData'
-import { PREVIEW_ROLE_KEY, useAccessPreviewStore } from '@/stores/accessPreview'
-
-function createMemoryStorage(): Storage {
-  const values = new Map<string, string>()
-
-  return {
-    get length() {
-      return values.size
-    },
-    clear() {
-      values.clear()
-    },
-    getItem(key) {
-      return values.get(key) ?? null
-    },
-    key(index) {
-      return [...values.keys()][index] ?? null
-    },
-    removeItem(key) {
-      values.delete(key)
-    },
-    setItem(key, value) {
-      values.set(key, value)
-    },
-  }
-}
-
-describe('access preview store', () => {
-  beforeEach(() => {
-    setActivePinia(createPinia())
-    vi.stubGlobal('localStorage', createMemoryStorage())
-  })
-
-  it('defaults to the enabled super admin with all enabled permissions', () => {
-    const preview = useAccessPreviewStore()
-
-    preview.initializeAfterLogin()
-
-    expect(preview.enabledRoles).toHaveLength(5)
-    expect(preview.currentRole?.code).toBe('SUPER_ADMIN')
-    expect(preview.can('system:permission:write')).toBe(true)
-    expect(preview.firstAccessiblePath).toBe('/customers')
-    expect(localStorage.getItem(PREVIEW_ROLE_KEY)).toBe('R001')
-  })
-
-  it('ignores disabled permission resources even when the selected role still holds their ids', () => {
-    const data = useAdminDataStore()
-    const preview = useAccessPreviewStore()
-    preview.initializeAfterLogin()
-    const customerList = data.permissions.find((item) => item.code === 'platform:customer:list')
-    expect(customerList).toBeDefined()
-
-    if (customerList) customerList.status = '停用'
-
-    expect(preview.can('platform:customer:list')).toBe(false)
-    expect(getNavigationLeaves(preview.filteredNavigation).map((item) => item.path)).not.toContain('/customers')
-    expect(preview.firstAccessiblePath).toBe('/customers/reviews')
-  })
-
-  it('does not cascade a disabled directory to enabled descendant leaves', () => {
-    const data = useAdminDataStore()
-    const preview = useAccessPreviewStore()
-    preview.initializeAfterLogin()
-    const businessDirectory = data.permissions.find((item) => item.code === 'business')
-    expect(businessDirectory).toBeDefined()
-
-    if (businessDirectory) businessDirectory.status = '停用'
-
-    expect(preview.can('business')).toBe(false)
-    expect(preview.can('platform:customer:list')).toBe(true)
-    expect(getNavigationLeaves(preview.filteredNavigation).map((item) => item.path)).toContain('/customers')
-  })
-
-  it('reacts immediately to permission id changes and falls back when the current role is disabled', async () => {
-    const data = useAdminDataStore()
-    const preview = useAccessPreviewStore()
-    preview.initializeAfterLogin()
-    expect(preview.commitRole('R003')).toBe(true)
-    const operator = data.roles.find((item) => item.id === 'R003')
-    expect(operator).toBeDefined()
-
-    if (operator) operator.permissionIds = ['P100']
-    expect(preview.can('first-leg:list')).toBe(false)
-    expect(preview.can('platform:customer:list')).toBe(true)
-    expect(preview.permissionSignature).toBe('platform:customer:list')
-
-    if (operator) operator.status = '停用'
-    await nextTick()
-
-    expect(preview.currentRole?.code).toBe('SUPER_ADMIN')
-    expect(localStorage.getItem(PREVIEW_ROLE_KEY)).toBe('R001')
-  })
-
-  it('falls back from an invalid persisted role and reset clears selection and persistence', () => {
-    localStorage.setItem(PREVIEW_ROLE_KEY, 'missing-role')
-    const preview = useAccessPreviewStore()
-
-    preview.initializeAfterLogin()
-    expect(preview.currentRole?.code).toBe('SUPER_ADMIN')
-
-    preview.reset()
-    expect(preview.initialized).toBe(false)
-    expect(preview.currentRole).toBeNull()
-    expect(localStorage.getItem(PREVIEW_ROLE_KEY)).toBeNull()
-  })
-
-  it('restores an enabled persisted role', () => {
-    localStorage.setItem(PREVIEW_ROLE_KEY, 'R003')
-    const preview = useAccessPreviewStore()
-
-    preview.initializeAfterLogin()
-
-    expect(preview.currentRole?.id).toBe('R003')
-    expect(localStorage.getItem(PREVIEW_ROLE_KEY)).toBe('R003')
-  })
-
-  it('does not reload an initialized role during guarded navigation', () => {
-    const preview = useAccessPreviewStore()
-    preview.initializeAfterLogin()
-    expect(preview.commitRole('R003')).toBe(true)
-
-    localStorage.setItem(PREVIEW_ROLE_KEY, 'R001')
-    preview.initializeAfterLogin()
-
-    expect(preview.currentRole?.id).toBe('R003')
-  })
-
-  it('has no role, permissions, or route when every role is disabled', () => {
-    const data = useAdminDataStore()
-    data.roles.forEach((role) => {
-      role.status = '停用'
-    })
-    const preview = useAccessPreviewStore()
-
-    preview.initializeAfterLogin()
-
-    expect(preview.currentRole).toBeNull()
-    expect([...preview.permissionCodes]).toEqual([])
-    expect(preview.filteredNavigation).toEqual([])
-    expect(preview.firstAccessiblePath).toBeNull()
-    expect(localStorage.getItem(PREVIEW_ROLE_KEY)).toBeNull()
-  })
-
-  it('does not recreate a default preview after reset when role data changes', async () => {
-    const data = useAdminDataStore()
-    const preview = useAccessPreviewStore()
-    preview.initializeAfterLogin()
-    preview.reset()
-
-    data.roles[0].status = '停用'
-    data.roles[1].status = '停用'
-    await nextTick()
-
-    expect(preview.initialized).toBe(false)
-    expect(preview.selectedRoleId).toBeNull()
-    expect(preview.currentRole).toBeNull()
-    expect(localStorage.getItem(PREVIEW_ROLE_KEY)).toBeNull()
-  })
-
-  it('previews candidates without committing and rejects disabled roles', () => {
-    const data = useAdminDataStore()
-    const preview = useAccessPreviewStore()
-    preview.initializeAfterLogin()
-    const candidate = preview.previewRole('R003')
-
-    expect(candidate.codes.has('first-leg:create')).toBe(true)
-    expect(candidate.firstPath).toBe('/warehouses')
-    expect(getNavigationLeaves(candidate.navigation).map((item) => item.path)).toContain('/orders/first-leg')
-    expectTypeOf(candidate.codes).toEqualTypeOf<ReadonlySet<string>>()
-    expectTypeOf(preview.permissionCodes).toEqualTypeOf<ReadonlySet<string>>()
-    expect(preview.currentRole?.id).toBe('R001')
-
-    const finance = data.roles.find((item) => item.id === 'R004')
-    if (finance) finance.status = '停用'
-    expect(preview.commitRole('R004')).toBe(false)
-    expect(preview.previewRole('R004').firstPath).toBeNull()
-    expect(preview.currentRole?.id).toBe('R001')
-  })
-
-  it('does not filter or mutate mock business data when switching data scopes', () => {
-    const data = useAdminDataStore()
-    const preview = useAccessPreviewStore()
-    preview.initializeAfterLogin()
-    const customerSnapshot = JSON.parse(JSON.stringify(data.customers)) as typeof data.customers
-    const orderSnapshot = JSON.parse(JSON.stringify(data.orders)) as typeof data.orders
-
-    expect(preview.commitRole('R003')).toBe(true)
-    expect(preview.currentRole?.dataScope).toBe('本部门数据')
-    expect(preview.commitRole('R005')).toBe(true)
-    expect(preview.currentRole?.dataScope).toBe('本人数据')
-
-    expect(data.customers).toEqual(customerSnapshot)
-    expect(data.orders).toEqual(orderSnapshot)
-  })
-})
diff --git a/src/stores/accessPreview.ts b/src/stores/accessPreview.ts
deleted file mode 100644
index ba5cd025..00000000
--- a/src/stores/accessPreview.ts
+++ /dev/null
@@ -1,155 +0,0 @@
-import { computed, ref, watch } from 'vue'
-import { defineStore } from 'pinia'
-import {
-  adminNavigation,
-  filterAdminNavigation,
-  getFirstNavigationLeaf,
-  type AdminNavigationNode,
-} from '@/navigation/adminNavigation'
-import { useAdminDataStore } from '@/stores/adminData'
-import { useAuthStore } from '@/stores/auth'
-
-export const PREVIEW_ROLE_KEY = 'cc-admin-preview-role'
-
-export interface RoleAccessPreview {
-  codes: ReadonlySet<string>
-  navigation: AdminNavigationNode[]
-  firstPath: string | null
-}
-
-const serverPermissionAliases: Record<string, string[]> = {
-  'customer:list': ['platform:customer:list'],
-  'warehouse:list': ['platform:warehouse:list'],
-  'first-leg:list': ['platform:order:list'],
-  'express-company:list': ['platform:express:list'],
-  'counterparty:list': ['platform:counterparty:list'],
-  'system:user:list': ['platform:user:list'],
-  'system:role:list': ['platform:role:list'],
-  'system:role:grant': ['platform:role:create', 'platform:role:grant'],
-  'system:permission:list': ['platform:permission:list'],
-  'system:permission:write': ['platform:permission:create'],
-}
-
-function withServerAliases(codes: ReadonlySet<string>): ReadonlySet<string> {
-  const result = new Set(codes)
-  codes.forEach((code) => serverPermissionAliases[code]?.forEach((alias) => result.add(alias)))
-  return result
-}
-
-export const useAccessPreviewStore = defineStore('access-preview', () => {
-  const data = useAdminDataStore()
-  const auth = useAuthStore()
-  const selectedRoleId = ref<string | null>(null)
-  const initialized = ref(false)
-
-  const enabledRoles = computed(() => data.roles.filter((role) => role.status === '启用'))
-  const enabledRoleIdsSignature = computed(() => enabledRoles.value
-    .map((role) => role.id)
-    .sort()
-    .join('|'))
-  const currentRole = computed(() => enabledRoles.value
-    .find((role) => role.id === selectedRoleId.value) ?? null)
-
-  function permissionCodesFor(roleId: string | null): ReadonlySet<string> {
-    const role = enabledRoles.value.find((item) => item.id === roleId)
-    if (!role) return new Set<string>()
-
-    const permissionIds = new Set(role.permissionIds)
-    return new Set(data.permissions
-      .filter((permission) => permission.status === '启用' && permissionIds.has(permission.id))
-      .map((permission) => permission.code))
-  }
-
-  const usesServerPermissions = computed(() => auth.isServerSession)
-  const permissionCodes = computed<ReadonlySet<string>>(() => usesServerPermissions.value
-    ? auth.permissionCodes
-    : withServerAliases(permissionCodesFor(selectedRoleId.value)))
-  const permissionSignature = computed(() => [...permissionCodes.value].sort().join('|'))
-  const filteredNavigation = computed(() => filterAdminNavigation(adminNavigation, permissionCodes.value))
-  const firstAccessiblePath = computed(() => getFirstNavigationLeaf(filteredNavigation.value)?.path ?? null)
-
-  function getDefaultRoleId(): string | null {
-    return enabledRoles.value.find((role) => role.code === 'SUPER_ADMIN')?.id
-      ?? enabledRoles.value[0]?.id
-      ?? null
-  }
-
-  function persistRole(roleId: string | null) {
-    if (roleId) {
-      localStorage.setItem(PREVIEW_ROLE_KEY, roleId)
-      return
-    }
-    localStorage.removeItem(PREVIEW_ROLE_KEY)
-  }
-
-  function initializeAfterLogin() {
-    if (usesServerPermissions.value) {
-      initialized.value = true
-      selectedRoleId.value = null
-      localStorage.removeItem(PREVIEW_ROLE_KEY)
-      return
-    }
-    if (initialized.value && currentRole.value) return
-    initialized.value = true
-    const persistedRoleId = localStorage.getItem(PREVIEW_ROLE_KEY)
-    const roleId = enabledRoles.value.some((role) => role.id === persistedRoleId)
-      ? persistedRoleId
-      : getDefaultRoleId()
-    selectedRoleId.value = roleId
-    persistRole(roleId)
-  }
-
-  function commitRole(roleId: string): boolean {
-    if (usesServerPermissions.value) return false
-    if (!enabledRoles.value.some((role) => role.id === roleId)) return false
-    selectedRoleId.value = roleId
-    persistRole(roleId)
-    return true
-  }
-
-  function previewRole(roleId: string): RoleAccessPreview {
-    const candidateCodes = withServerAliases(permissionCodesFor(roleId))
-    const candidateNavigation = filterAdminNavigation(adminNavigation, candidateCodes)
-
-    return {
-      codes: candidateCodes,
-      navigation: candidateNavigation,
-      firstPath: getFirstNavigationLeaf(candidateNavigation)?.path ?? null,
-    }
-  }
-
-  function can(permissionCode: string): boolean {
-    return permissionCodes.value.has(permissionCode)
-  }
-
-  function reset() {
-    initialized.value = false
-    selectedRoleId.value = null
-    localStorage.removeItem(PREVIEW_ROLE_KEY)
-  }
-
-  watch(enabledRoleIdsSignature, () => {
-    if (!initialized.value || currentRole.value) return
-    const fallbackRoleId = getDefaultRoleId()
-    selectedRoleId.value = fallbackRoleId
-    persistRole(fallbackRoleId)
-  })
-
-  return {
-    selectedRoleId,
-    initialized,
-    usesServerPermissions,
-    enabledRoles,
-    currentRole,
-    permissionCodes,
-    permissionSignature,
-    filteredNavigation,
-    firstAccessiblePath,
-    permissionCodesFor,
-    initializeAfterLogin,
-    commitRole,
-    previewRole,
-    can,
-    reset,
-  }
-})
diff --git a/src/stores/adminData.test.ts b/src/stores/adminData.test.ts
deleted file mode 100644
index a0bed3e0..00000000
--- a/src/stores/adminData.test.ts
+++ /dev/null
@@ -1,126 +0,0 @@
-import { beforeEach, describe, expect, it } from 'vitest'
-import { createPinia, setActivePinia } from 'pinia'
-import { adminNavigation, getNavigationLeaves } from '@/navigation/adminNavigation'
-import { useAdminDataStore } from '@/stores/adminData'
-import { buildPermissionTree } from '@/utils/permissionTree'
-
-describe('admin permission fixtures', () => {
-  beforeEach(() => {
-    setActivePinia(createPinia())
-  })
-
-  it('groups page permissions under business and system directories', () => {
-    const tree = buildPermissionTree(useAdminDataStore().permissions)
-
-    expect(tree.map((node) => node.name)).toEqual(['业务管理', '基础资料', '系统管理'])
-    expect(tree[0]?.children?.map((node) => node.name)).toEqual(['客户管理', '企业审核', '仓库管理', '头程订单'])
-    expect(tree[1]?.children?.map((node) => node.name)).toEqual(['快递公司', '往来单位'])
-    expect(tree[2]?.children?.map((node) => node.name)).toEqual(['内部用户', '角色管理', '菜单权限'])
-  })
-
-  it('keeps menu permission codes aligned with navigation leaves', () => {
-    const store = useAdminDataStore()
-    const menuCodes = store.permissions
-      .filter((item) => item.type === '菜单')
-      .map((item) => item.code)
-      .sort()
-    const navigationCodes = getNavigationLeaves(adminNavigation)
-      .map((item) => item.permission)
-      .sort()
-
-    expect(menuCodes).toEqual(navigationCodes)
-  })
-
-  it('does not guess API paths for static button permissions', () => {
-    const buttonPermissions = useAdminDataStore().permissions.filter((item) => item.type === '按钮')
-
-    expect(buttonPermissions.every((item) => item.path === '' && item.method === '-')).toBe(true)
-    expect(useAdminDataStore().permissions.some((item) => item.type === '接口')).toBe(false)
-  })
-
-  it('keeps every role permission id valid after regrouping', () => {
-    const store = useAdminDataStore()
-    const permissionIds = new Set(store.permissions.map((item) => item.id))
-
-    store.roles.forEach((role) => {
-      expect(role.permissionIds.every((id) => permissionIds.has(id))).toBe(true)
-    })
-  })
-
-  it('maintains platform receiving warehouses with unique normalized codes', () => {
-    const store = useAdminDataStore()
-    expect(store.warehouses).toHaveLength(6)
-    expect(store.activeWarehouses).toBe(5)
-
-    const id = store.saveWarehouse({
-      code: 'cn-hz-01', name: '杭州仓', province: '浙江省', city: '杭州市', address: '演示物流园 7 号库',
-      contactName: '仓库客服', contactPhone: '0571-****007', businessHours: '周一至周五 09:00-18:00',
-      status: 'ACTIVE', remark: '',
-    })
-    expect(store.warehouses.find((item) => item.id === id)?.code).toBe('CN-HZ-01')
-    expect(store.activeWarehouses).toBe(6)
-    expect(() => store.saveWarehouse({
-      code: 'CN-HZ-01', name: '重复仓', province: '', city: '杭州市', address: '重复地址',
-      contactName: '', contactPhone: '', businessHours: '', status: 'ACTIVE', remark: '',
-    })).toThrow('仓库编码已存在')
-
-    store.setWarehouseStatus(id, 'INACTIVE')
-    expect(store.activeWarehouses).toBe(5)
-  })
-
-  it('provides the express company records defined by the phase-one prototype', () => {
-    const store = useAdminDataStore()
-
-    expect(store.expressCompanies).toHaveLength(8)
-    expect(store.activeExpressCompanies).toBe(7)
-    expect(store.expressCompanies.find((item) => item.code === 'YTO')?.status).toBe('已终止')
-    expect(new Set(store.expressCompanies.map((item) => item.code)).size).toBe(store.expressCompanies.length)
-  })
-
-  it('validates express company uniqueness and counterparty multi-types', () => {
-    const store = useAdminDataStore()
-    expect(() => store.saveExpressCompany({ name: '顺丰速运', code: 'NEW-SF', website: '', phone: '', status: '合作中', remark: '' })).toThrow('快递公司名称已存在')
-    expect(() => store.saveExpressCompany({ name: '新快递', code: 'sf', website: '', phone: '', status: '合作中', remark: '' })).toThrow('快递公司编码已存在')
-    const id = store.saveCounterparty({ code: 'cp-test', name: '测试多角色单位', types: ['供应商', '发货单位'], contactName: '联系人', contactPhone: '13800000000', email: '', country: '中国', province: '浙江省', city: '义乌市', postalCode: '', address: '测试地址', status: '启用', remark: '' })
-    expect(store.counterparties.find((item) => item.id === id)?.types).toEqual(['供应商', '发货单位'])
-    expect(() => store.saveCounterparty({ code: 'CP-TEST', name: '重复单位', types: ['客户'], contactName: '联系人', contactPhone: '13800000000', email: '', country: '中国', province: '', city: '深圳市', postalCode: '', address: '测试地址', status: '启用', remark: '' })).toThrow('往来单位编码已存在')
-  })
-
-  it('keeps pending orders pending after admin edits and audits delivery maintenance', () => {
-    const store = useAdminDataStore()
-    const order = store.orders.find((item) => item.status === '待审核')!
-    const before = order.timeline.length
-    store.saveOrder({ ...order, id: order.id, remark: '后台补充资料' })
-    const updated = store.orders.find((item) => item.id === order.id)!
-    expect(updated.status).toBe('待审核')
-    expect(updated.timeline).toHaveLength(before + 1)
-    expect(updated.timeline.at(-1)?.title).toBe('后台修改待审核订单')
-    store.saveOrderDeliveryInfo(order.id, 'E001', 'DHL-20260730-001', '张伟')
-    expect(updated.deliveryInfo?.trackingNo).toBe('DHL-20260730-001')
-    expect(updated.timeline.at(-1)?.title).toBe('更新履约快递信息')
-  })
-
-  it('keeps the order warehouse snapshot stable when the warehouse master changes', () => {
-    const store = useAdminDataStore()
-    const order = store.orders[0]
-    const warehouse = store.warehouses.find((item) => item.id === order.receivingWarehouseId)
-    expect(warehouse).toBeDefined()
-    const originalSnapshot = order.receivingWarehouseSnapshot ? { ...order.receivingWarehouseSnapshot } : null
-
-    store.saveWarehouse({ ...warehouse!, name: '宁波仓（新名称）' })
-
-    expect(store.warehouses.find((item) => item.id === warehouse!.id)?.name).toBe('宁波仓（新名称）')
-    expect(order.receivingWarehouseSnapshot).toEqual(originalSnapshot)
-  })
-
-  it('rejects new orders that select an inactive receiving warehouse', () => {
-    const store = useAdminDataStore()
-    const template = store.orders[0]
-
-    expect(() => store.saveOrder({
-      ...template,
-      id: undefined,
-      receivingWarehouseId: 'WH006',
-    })).toThrow('所选收货仓当前不可用于新订单')
-  })
-})
diff --git a/src/stores/adminData.ts b/src/stores/adminData.ts
deleted file mode 100644
index 4661cea5..00000000
--- a/src/stores/adminData.ts
+++ /dev/null
@@ -1,389 +0,0 @@
-import { computed, ref } from 'vue'
-import { defineStore } from 'pinia'
-import {
-  createPlatformReceivingWarehouseSnapshot,
-  DEMO_PLATFORM_RECEIVING_WAREHOUSES,
-} from '@chongchong/shared'
-import type {
-  Customer,
-  Counterparty,
-  ExpressCompany,
-  FirstLegOrder,
-  InternalUser,
-  OrderStatus,
-  Permission,
-  Role,
-  Warehouse,
-} from '@/types/admin'
-
-const initialExpressCompanies: ExpressCompany[] = [
-  { id: 'E001', name: 'DHL', code: 'DHL', website: 'www.dhl.com', phone: '95380', status: '合作中', remark: '国际快递渠道。', updatedAt: '2026-07-28 09:10' },
-  { id: 'E002', name: 'FedEx', code: 'FDX', website: 'www.fedex.com', phone: '400-886-1888', status: '合作中', remark: '国际快递渠道。', updatedAt: '2026-07-28 09:12' },
-  { id: 'E003', name: 'UPS', code: 'UPS', website: 'www.ups.com', phone: '400-820-8388', status: '合作中', remark: '', updatedAt: '2026-07-28 09:15' },
-  { id: 'E004', name: '顺丰速运', code: 'SF', website: 'www.sf-express.com', phone: '95338', status: '合作中', remark: '国内收货常用渠道。', updatedAt: '2026-07-28 09:20' },
-  { id: 'E005', name: '中通快递', code: 'ZTO', website: 'www.zto.com', phone: '95311', status: '合作中', remark: '', updatedAt: '2026-07-28 09:22' },
-  { id: 'E006', name: '圆通速递', code: 'YTO', website: 'www.yto.net.cn', phone: '95554', status: '已终止', remark: '暂停新增引用，历史订单保留。', updatedAt: '2026-07-28 09:25' },
-  { id: 'E007', name: 'EMS', code: 'EMS', website: 'www.ems.com.cn', phone: '11183', status: '合作中', remark: '', updatedAt: '2026-07-28 09:28' },
-  { id: 'E008', name: '德邦快递', code: 'DPK', website: 'www.deppon.com', phone: '95353', status: '合作中', remark: '大件货物备选渠道。', updatedAt: '2026-07-28 09:30' },
-]
-
-const initialCounterparties: Counterparty[] = [
-  { id: 'CP001', code: 'CP-HY-001', name: '华远贸易有限公司', types: ['客户', '发货单位'], contactName: '张伟', contactPhone: '138****6789', email: 'zhangwei@huayuan.cn', country: '中国', province: '浙江省', city: '杭州市', postalCode: '310000', address: '滨江区江南大道 588 号', status: '启用', remark: '美线核心客户。', updatedAt: '2026-07-28 10:10' },
-  { id: 'CP002', code: 'CP-SD-002', name: '深圳速达供应链有限公司', types: ['供应商', '承运商', '发货单位'], contactName: '李明', contactPhone: '139****8901', email: 'liming@suda.cn', country: '中国', province: '广东省', city: '深圳市', postalCode: '518000', address: '盐田区深盐路 2028 号', status: '启用', remark: '欧洲线拼箱合作方。', updatedAt: '2026-07-28 10:15' },
-  { id: 'CP003', code: 'CP-CUS-003', name: 'HY GLOBAL LLC', types: ['客户', '收货单位'], contactName: 'Alice Chen', contactPhone: '+1 213 *** 8899', email: 'ops@hyglobal.example', country: '美国', province: 'California', city: 'Los Angeles', postalCode: '90001', address: '1200 S Alameda St', status: '启用', remark: '华远贸易美国收货方。', updatedAt: '2026-07-28 10:20' },
-  { id: 'CP004', code: 'CP-CB-004', name: '宁波海诚报关有限公司', types: ['供应商', '报关行'], contactName: '周海', contactPhone: '0574-****2211', email: 'service@haicheng.example', country: '中国', province: '浙江省', city: '宁波市', postalCode: '315800', address: '北仑区港兴路 36 号', status: '启用', remark: '宁波口岸报关服务。', updatedAt: '2026-07-28 10:25' },
-  { id: 'CP005', code: 'CP-OLD-005', name: '厦门远港运输有限公司', types: ['承运商'], contactName: '刘洋', contactPhone: '0592-****9812', email: 'dispatch@xm-old.example', country: '中国', province: '福建省', city: '厦门市', postalCode: '361000', address: '湖里区东港北路 31 号', status: '停用', remark: '合同到期，停止新增引用。', updatedAt: '2026-07-28 10:30' },
-]
-
-const initialCustomers: Customer[] = [
-  { id: 'T001', name: '华远贸易有限公司', creditCode: '91330100MA15XXXX91', contact: '张伟', phone: '138****6789', email: 'zhangwei@huayuan.cn', sales: '王建国', packageName: '企业版', period: 30, status: '正常', orders: 286, joinedAt: '2025-03-15', address: '浙江省杭州市滨江区江南大道 588 号', remark: '美线核心客户，优先处理订舱需求。' },
-  { id: 'T002', name: '深圳速达供应链有限公司', creditCode: '91440300MA95XXXX13', contact: '李明', phone: '139****8901', email: 'liming@suda.cn', sales: '李秀英', packageName: '专业版', period: 45, status: '正常', orders: 152, joinedAt: '2025-06-20', address: '广东省深圳市盐田区深盐路 2028 号', remark: '欧洲线拼箱客户。' },
-  { id: 'T003', name: '广州恒通物流有限公司', creditCode: '91440100MA32XXXX45', contact: '王芳', phone: '137****2345', email: 'wangfang@hengtong.cn', sales: '张志强', packageName: '专业版', period: 60, status: '正常', orders: 98, joinedAt: '2025-09-01', address: '广东省广州市白云区机场路 1688 号', remark: '空运及敏感货渠道客户。' },
-  { id: 'T004', name: '宁波远洋货运代理有限公司', creditCode: '91330200MA18XXXX38', contact: '陈强', phone: '136****4567', email: 'chenqiang@ocean-nb.cn', sales: '刘德海', packageName: '基础版', period: 90, status: '正常', orders: 45, joinedAt: '2026-01-10', address: '浙江省宁波市北仑区港兴路 88 号', remark: '' },
-  { id: 'T005', name: '北京国贸跨境供应链有限公司', creditCode: '91110100MA87XXXX23', contact: '赵雪', phone: '135****7890', email: 'zhaoxue@bjgmt.cn', sales: '陈美玲', packageName: '基础版', period: 30, status: '待审核', orders: 0, joinedAt: '2026-07-26', address: '北京市朝阳区建国路 93 号', remark: '营业执照已上传，等待审核。' },
-  { id: 'T006', name: '厦门港务货运有限公司', creditCode: '91350200MA12XXXX79', contact: '刘洋', phone: '133****0123', email: 'liuyang@xmgw.cn', sales: '赵晓东', packageName: '企业版', period: 45, status: '停用', orders: 73, joinedAt: '2024-11-01', address: '福建省厦门市湖里区东港北路 31 号', remark: '合同到期，暂时停用。' },
-]
-
-const initialUsers: InternalUser[] = [
-  { id: 'U001', account: 'admin', name: '系统管理员', department: '平台管理', phone: '13800000001', email: 'admin@ccglobal.cn', roleIds: ['R001'], status: '正常', lastLogin: '2026-07-27 17:56', createdAt: '2026-01-01' },
-  { id: 'U002', account: 'zhangwei', name: '张伟', department: '运营部', phone: '13800000002', email: 'zhangwei@ccglobal.cn', roleIds: ['R002'], status: '正常', lastLogin: '2026-07-27 16:30', createdAt: '2026-02-08' },
-  { id: 'U003', account: 'liming', name: '李明', department: '操作部', phone: '13800000003', email: 'liming@ccglobal.cn', roleIds: ['R003'], status: '正常', lastLogin: '2026-07-27 15:42', createdAt: '2026-02-18' },
-  { id: 'U004', account: 'wangfang', name: '王芳', department: '财务部', phone: '13800000004', email: 'wangfang@ccglobal.cn', roleIds: ['R004'], status: '正常', lastLogin: '2026-07-27 14:18', createdAt: '2026-03-02' },
-  { id: 'U005', account: 'chenqiang', name: '陈强', department: '销售部', phone: '13800000005', email: 'chenqiang@ccglobal.cn', roleIds: ['R005'], status: '正常', lastLogin: '2026-07-26 18:02', createdAt: '2026-04-15' },
-  { id: 'U006', account: 'zhaoting', name: '赵婷', department: '操作部', phone: '13800000006', email: 'zhaoting@ccglobal.cn', roleIds: ['R003'], status: '停用', lastLogin: '2026-07-18 10:10', createdAt: '2026-05-10' },
-]
-
-const initialPermissions: Permission[] = [
-  { id: 'P010', parentId: null, name: '业务管理', code: 'business', type: '目录', path: '', method: '-', status: '启用', sort: 20 },
-  { id: 'P100', parentId: 'P010', name: '客户管理', code: 'platform:customer:list', type: '菜单', path: '/customers', method: '-', status: '启用', sort: 10 },
-  { id: 'P101', parentId: 'P010', name: '企业审核', code: 'platform:customer:review', type: '菜单', path: '/customers/reviews', method: '-', status: '启用', sort: 15 },
-  { id: 'P102', parentId: 'P100', name: '新增客户', code: 'customer:create', type: '按钮', path: '', method: '-', status: '启用', sort: 10 },
-  { id: 'P103', parentId: 'P101', name: '审核通过', code: 'platform:customer:approve', type: '按钮', path: '', method: '-', status: '启用', sort: 10 },
-  { id: 'P104', parentId: 'P101', name: '审核驳回', code: 'platform:customer:reject', type: '按钮', path: '', method: '-', status: '启用', sort: 20 },
-  { id: 'P150', parentId: 'P010', name: '仓库管理', code: 'platform:warehouse:list', type: '菜单', path: '/warehouses', method: '-', status: '启用', sort: 20 },
-  { id: 'P152', parentId: 'P150', name: '维护仓库', code: 'warehouse:write', type: '按钮', path: '', method: '-', status: '启用', sort: 10 },
-  { id: 'P200', parentId: 'P010', name: '头程订单', code: 'platform:order:list', type: '菜单', path: '/orders/first-leg', method: '-', status: '启用', sort: 30 },
-  { id: 'P202', parentId: 'P200', name: '创建订单', code: 'first-leg:create', type: '按钮', path: '', method: '-', status: '启用', sort: 10 },
-  { id: 'P203', parentId: 'P200', name: '更新状态', code: 'first-leg:status', type: '按钮', path: '', method: '-', status: '启用', sort: 20 },
-  { id: 'P204', parentId: 'P200', name: '维护履约快递', code: 'first-leg:delivery', type: '按钮', path: '', method: '-', status: '启用', sort: 30 },
-  { id: 'P015', parentId: null, name: '基础资料', code: 'master-data', type: '目录', path: '', method: '-', status: '启用', sort: 25 },
-  { id: 'P160', parentId: 'P015', name: '快递公司', code: 'platform:express:list', type: '菜单', path: '/master-data/express-companies', method: '-', status: '启用', sort: 10 },
-  { id: 'P161', parentId: 'P160', name: '维护快递公司', code: 'express-company:write', type: '按钮', path: '', method: '-', status: '启用', sort: 10 },
-  { id: 'P162', parentId: 'P160', name: '导入快递公司', code: 'express-company:import', type: '按钮', path: '', method: '-', status: '启用', sort: 20 },
-  { id: 'P165', parentId: 'P015', name: '往来单位', code: 'platform:counterparty:list', type: '菜单', path: '/master-data/counterparties', method: '-', status: '启用', sort: 20 },
-  { id: 'P166', parentId: 'P165', name: '维护往来单位', code: 'counterparty:write', type: '按钮', path: '', method: '-', status: '启用', sort: 10 },
-  { id: 'P167', parentId: 'P165', name: '导入往来单位', code: 'counterparty:import', type: '按钮', path: '', method: '-', status: '启用', sort: 20 },
-  { id: 'P020', parentId: null, name: '系统管理', code: 'system', type: '目录', path: '', method: '-', status: '启用', sort: 30 },
-  { id: 'P300', parentId: 'P020', name: '内部用户', code: 'platform:user:list', type: '菜单', path: '/system/users', method: '-', status: '启用', sort: 10 },
-  { id: 'P302', parentId: 'P300', name: '维护用户', code: 'system:user:write', type: '按钮', path: '', method: '-', status: '启用', sort: 10 },
-  { id: 'P400', parentId: 'P020', name: '角色管理', code: 'platform:role:list', type: '菜单', path: '/system/roles', method: '-', status: '启用', sort: 20 },
-  { id: 'P402', parentId: 'P400', name: '角色授权', code: 'system:role:grant', type: '按钮', path: '', method: '-', status: '启用', sort: 10 },
-  { id: 'P500', parentId: 'P020', name: '菜单权限', code: 'platform:permission:list', type: '菜单', path: '/system/permissions', method: '-', status: '启用', sort: 30 },
-  { id: 'P502', parentId: 'P500', name: '维护权限', code: 'system:permission:write', type: '按钮', path: '', method: '-', status: '启用', sort: 10 },
-]
-
-const allPermissionIds = initialPermissions.map((item) => item.id)
-const initialRoles: Role[] = [
-  { id: 'R001', name: '超级管理员', code: 'SUPER_ADMIN', description: '平台最高权限，拥有全部菜单和数据权限。', userCount: 1, dataScope: '全部数据', status: '启用', permissionIds: allPermissionIds, builtIn: true },
-  { id: 'R002', name: '运营主管', code: 'OPS_MANAGER', description: '负责客户审核、仓库维护、基础资料、订单分派和运营监控。', userCount: 1, dataScope: '全部数据', status: '启用', permissionIds: ['P010', 'P100', 'P103', 'P150', 'P152', 'P200', 'P203', 'P204', 'P015', 'P160', 'P161', 'P162', 'P165', 'P166', 'P167'] },
-  { id: 'R003', name: '操作员', code: 'OPERATOR', description: '查看收货仓并处理头程订单和物流节点更新。', userCount: 2, dataScope: '本部门数据', status: '启用', permissionIds: ['P010', 'P150', 'P200', 'P202', 'P203', 'P204'] },
-  { id: 'R004', name: '财务', code: 'FINANCE', description: '查看订单应收并处理对账结算。', userCount: 1, dataScope: '本部门数据', status: '启用', permissionIds: ['P010', 'P200'] },
-  { id: 'R005', name: '销售', code: 'SALES', description: '维护客户、查看收货仓并跟进本人负责的订单。', userCount: 1, dataScope: '本人数据', status: '启用', permissionIds: ['P010', 'P100', 'P102', 'P150', 'P200'] },
-]
-
-function demoWarehouseSnapshot(id: string) {
-  const warehouse = DEMO_PLATFORM_RECEIVING_WAREHOUSES.find((item) => item.id === id)
-  if (!warehouse) throw new Error(`演示仓库不存在：${id}`)
-  return createPlatformReceivingWarehouseSnapshot(warehouse)
-}
-
-const initialOrders: FirstLegOrder[] = [
-  { id: 'O001', no: 'BY20260727001', customerId: 'T001', customerName: '华远贸易有限公司', referenceNo: 'HY-0727-01', transportMode: '海运整箱 FCL', businessType: '出口', origin: '宁波', destination: '洛杉矶', receivingWarehouseId: 'WH005', receivingWarehouseSnapshot: demoWarehouseSnapshot('WH005'), container: '40HQ x 2', etd: '2026-08-02', eta: '2026-08-18', amount: 48500, currency: 'CNY', status: '已受理', priority: '紧急', operator: '张伟', shipper: '华远贸易有限公司', consignee: 'HY GLOBAL LLC', cargoName: '家居用品', pieces: 1260, weight: 27800, volume: 62.5, createdAt: '2026-07-27 09:18', remark: '需要在截关日前完成报关资料确认。', timeline: [{ time: '2026-07-27 09:18', title: '客户提交订单', description: '客户完成货物与平台收货仓信息提交。', operator: '客户管理员' }, { time: '2026-07-27 10:02', title: '订单已受理', description: '运营审核资料完整，进入订舱准备。', operator: '张伟' }] },
-  { id: 'O002', no: 'BY20260726008', customerId: 'T002', customerName: '深圳速达供应链有限公司', referenceNo: 'SD-EU-558', transportMode: '海运拼箱 LCL', businessType: '出口', origin: '深圳', destination: '汉堡', receivingWarehouseId: 'WH002', receivingWarehouseSnapshot: demoWarehouseSnapshot('WH002'), container: 'LCL 8.6 CBM', etd: '2026-08-05', eta: '2026-09-06', amount: 12800, currency: 'CNY', status: '已订舱', priority: '普通', operator: '李明', shipper: '深圳速达供应链有限公司', consignee: 'SUDA EUROPE GMBH', cargoName: '电子配件', pieces: 286, weight: 5200, volume: 8.6, createdAt: '2026-07-26 15:42', remark: '', timeline: [{ time: '2026-07-26 15:42', title: '客户提交订单', description: '订单进入平台审核。', operator: '客户管理员' }, { time: '2026-07-27 08:55', title: '订舱完成', description: '已获得船公司舱位确认。', operator: '李明' }] },
-  { id: 'O003', no: 'BY20260726005', customerId: 'T003', customerName: '广州恒通物流有限公司', referenceNo: 'HT-AIR-0719', transportMode: '空运', businessType: '出口', origin: '广州', destination: '纽约', receivingWarehouseId: 'WH002', receivingWarehouseSnapshot: demoWarehouseSnapshot('WH002'), container: '500 KG', etd: '2026-07-30', eta: '2026-08-01', amount: 35600, currency: 'CNY', status: '运输中', priority: '加急', operator: '赵婷', shipper: '广州恒通物流有限公司', consignee: 'HENGTONG US INC.', cargoName: '服装样品', pieces: 36, weight: 500, volume: 2.8, createdAt: '2026-07-26 10:20', remark: '航班起飞后第一时间同步轨迹。', timeline: [{ time: '2026-07-26 10:20', title: '客户提交订单', description: '加急空运订单。', operator: '客户管理员' }, { time: '2026-07-27 16:30', title: '货物已起飞', description: '航班 CZ699 离港。', operator: '赵婷' }] },
-  { id: 'O004', no: 'BY20260725012', customerId: 'T004', customerName: '宁波远洋货运代理有限公司', referenceNo: 'NB-ROAD-201', transportMode: '陆运', businessType: '出口', origin: '宁波', destination: '霍尔果斯', receivingWarehouseId: 'WH005', receivingWarehouseSnapshot: demoWarehouseSnapshot('WH005'), container: '整车 x 3', etd: '2026-07-28', eta: '2026-08-08', amount: 18200, currency: 'CNY', status: '待审核', priority: '普通', operator: '未分配', shipper: '宁波远洋货运代理有限公司', consignee: 'ALATAU TRADING LLP', cargoName: '机械配件', pieces: 480, weight: 18500, volume: 46, createdAt: '2026-07-25 14:08', remark: '', timeline: [{ time: '2026-07-25 14:08', title: '客户提交订单', description: '等待平台审核与人员分派。', operator: '客户管理员' }] },
-  { id: 'O005', no: 'BY20260724009', customerId: 'T001', customerName: '华远贸易有限公司', referenceNo: 'HY-0724-06', transportMode: '海运整箱 FCL', businessType: '出口', origin: '上海', destination: '长滩', receivingWarehouseId: 'WH004', receivingWarehouseSnapshot: demoWarehouseSnapshot('WH004'), container: '20GP x 5', etd: '2026-07-28', eta: '2026-08-12', amount: 56000, currency: 'CNY', status: '已完成', priority: '普通', operator: '张伟', shipper: '华远贸易有限公司', consignee: 'HY GLOBAL LLC', cargoName: '户外用品', pieces: 3200, weight: 55000, volume: 135, createdAt: '2026-07-24 08:45', remark: '', timeline: [{ time: '2026-07-24 08:45', title: '客户提交订单', description: '订单资料提交。', operator: '客户管理员' }, { time: '2026-07-27 12:20', title: '订单已完成', description: '全部业务节点已确认。', operator: '张伟' }] },
-  { id: 'O006', no: 'BY20260723007', customerId: 'T002', customerName: '深圳速达供应链有限公司', referenceNo: 'SD-EU-552', transportMode: '海运拼箱 LCL', businessType: '出口', origin: '青岛', destination: '鹿特丹', receivingWarehouseId: 'WH003', receivingWarehouseSnapshot: demoWarehouseSnapshot('WH003'), container: 'LCL 12 CBM', etd: '2026-08-10', eta: '2026-09-15', amount: 15300, currency: 'CNY', status: '草稿', priority: '普通', operator: '未分配', shipper: '深圳速达供应链有限公司', consignee: 'SUDA EUROPE GMBH', cargoName: '厨房用品', pieces: 520, weight: 8500, volume: 12, createdAt: '2026-07-23 17:10', remark: '等待客户补充收货人税号。', timeline: [{ time: '2026-07-23 17:10', title: '保存草稿', description: '订单尚未提交审核。', operator: '客户管理员' }] },
-]
-
-export const useAdminDataStore = defineStore('admin-data', () => {
-  const customers = ref<Customer[]>(structuredClone(initialCustomers))
-  const users = ref<InternalUser[]>(structuredClone(initialUsers))
-  const roles = ref<Role[]>(structuredClone(initialRoles))
-  const permissions = ref<Permission[]>(structuredClone(initialPermissions))
-  const warehouses = ref<Warehouse[]>(DEMO_PLATFORM_RECEIVING_WAREHOUSES.map((item) => ({ ...item })))
-  const expressCompanies = ref<ExpressCompany[]>(structuredClone(initialExpressCompanies))
-  const counterparties = ref<Counterparty[]>(structuredClone(initialCounterparties))
-  const orders = ref<FirstLegOrder[]>(structuredClone(initialOrders))
-
-  const activeUsers = computed(() => users.value.filter((item) => item.status === '正常').length)
-  const pendingCustomers = computed(() => customers.value.filter((item) => item.status === '待审核').length)
-  const activeWarehouses = computed(() => warehouses.value.filter((item) => item.status === 'ACTIVE').length)
-  const activeExpressCompanies = computed(() => expressCompanies.value.filter((item) => item.status === '合作中').length)
-  const activeCounterparties = computed(() => counterparties.value.filter((item) => item.status === '启用').length)
-  const pendingOrders = computed(() => orders.value.filter((item) => ['待审核', '已受理'].includes(item.status)).length)
-
-  function nextId(prefix: string, rows: Array<{ id: string }>) {
-    const max = rows.reduce((value, item) => Math.max(value, Number(item.id.replace(/\D/g, '')) || 0), 0)
-    return `${prefix}${String(max + 1).padStart(3, '0')}`
-  }
-
-  function saveCustomer(payload: Omit<Customer, 'id' | 'orders' | 'joinedAt'> & { id?: string }) {
-    if (payload.id) {
-      const index = customers.value.findIndex((item) => item.id === payload.id)
-      if (index >= 0) customers.value[index] = { ...customers.value[index], ...payload } as Customer
-      return payload.id
-    }
-    const id = nextId('T', customers.value)
-    customers.value.unshift({ ...payload, id, orders: 0, joinedAt: new Date().toISOString().slice(0, 10) })
-    return id
-  }
-
-  function setCustomerStatus(id: string, status: Customer['status']) {
-    const customer = customers.value.find((item) => item.id === id)
-    if (customer) customer.status = status
-  }
-
-  function saveWarehouse(payload: Omit<Warehouse, 'id' | 'updatedAt'> & { id?: string }) {
-    const duplicate = warehouses.value.find((item) => item.code.toLowerCase() === payload.code.trim().toLowerCase() && item.id !== payload.id)
-    if (duplicate) throw new Error('仓库编码已存在')
-    const updatedAt = new Date().toISOString().slice(0, 16).replace('T', ' ')
-    if (payload.id) {
-      const index = warehouses.value.findIndex((item) => item.id === payload.id)
-      if (index >= 0) warehouses.value[index] = { ...warehouses.value[index], ...payload, code: payload.code.trim().toUpperCase(), updatedAt } as Warehouse
-      return payload.id
-    }
-    const id = nextId('WH', warehouses.value)
-    warehouses.value.unshift({ ...payload, id, code: payload.code.trim().toUpperCase(), updatedAt })
-    return id
-  }
-
-  function setWarehouseStatus(id: string, status: Warehouse['status']) {
-    const warehouse = warehouses.value.find((item) => item.id === id)
-    if (warehouse) {
-      warehouse.status = status
-      warehouse.updatedAt = new Date().toISOString().slice(0, 16).replace('T', ' ')
-    }
-  }
-
-  function saveExpressCompany(payload: Omit<ExpressCompany, 'id' | 'updatedAt'> & { id?: string }) {
-    const normalizedCode = payload.code.trim().toUpperCase()
-    const duplicateCode = expressCompanies.value.find((item) => item.code.toLowerCase() === normalizedCode.toLowerCase() && item.id !== payload.id)
-    if (duplicateCode) throw new Error('快递公司编码已存在')
-    const duplicateName = expressCompanies.value.find((item) => item.name.trim().toLowerCase() === payload.name.trim().toLowerCase() && item.id !== payload.id)
-    if (duplicateName) throw new Error('快递公司名称已存在')
-    const updatedAt = new Date().toISOString().slice(0, 16).replace('T', ' ')
-    if (payload.id) {
-      const index = expressCompanies.value.findIndex((item) => item.id === payload.id)
-      if (index >= 0) expressCompanies.value[index] = { ...expressCompanies.value[index], ...payload, code: normalizedCode, updatedAt } as ExpressCompany
-      return payload.id
-    }
-    const id = nextId('E', expressCompanies.value)
-    expressCompanies.value.unshift({ ...payload, id, code: normalizedCode, updatedAt })
-    return id
-  }
-
-  function setExpressCompanyStatus(id: string, status: ExpressCompany['status']) {
-    const company = expressCompanies.value.find((item) => item.id === id)
-    if (!company) return
-    company.status = status
-    company.updatedAt = new Date().toISOString().slice(0, 16).replace('T', ' ')
-  }
-
-  function saveCounterparty(payload: Omit<Counterparty, 'id' | 'updatedAt'> & { id?: string }) {
-    const normalizedCode = payload.code.trim().toUpperCase()
-    const duplicate = counterparties.value.find((item) => item.code.toLowerCase() === normalizedCode.toLowerCase() && item.id !== payload.id)
-    if (duplicate) throw new Error('往来单位编码已存在')
-    const updatedAt = new Date().toISOString().slice(0, 16).replace('T', ' ')
-    if (payload.id) {
-      const index = counterparties.value.findIndex((item) => item.id === payload.id)
-      if (index >= 0) counterparties.value[index] = { ...counterparties.value[index], ...payload, code: normalizedCode, types: [...payload.types], updatedAt } as Counterparty
-      return payload.id
-    }
-    const id = nextId('CP', counterparties.value)
-    counterparties.value.unshift({ ...payload, id, code: normalizedCode, types: [...payload.types], updatedAt })
-    return id
-  }
-
-  function setCounterpartyStatus(id: string, status: Counterparty['status']) {
-    const counterparty = counterparties.value.find((item) => item.id === id)
-    if (!counterparty) return
-    counterparty.status = status
-    counterparty.updatedAt = new Date().toISOString().slice(0, 16).replace('T', ' ')
-  }
-
-  function saveUser(payload: Omit<InternalUser, 'id' | 'lastLogin' | 'createdAt'> & { id?: string }) {
-    if (payload.id) {
-      const index = users.value.findIndex((item) => item.id === payload.id)
-      if (index >= 0) users.value[index] = { ...users.value[index], ...payload } as InternalUser
-      return payload.id
-    }
-    const id = nextId('U', users.value)
-    users.value.unshift({ ...payload, id, lastLogin: '-', createdAt: new Date().toISOString().slice(0, 10) })
-    syncRoleCounts()
-    return id
-  }
-
-  function setUserStatus(id: string, status: InternalUser['status']) {
-    const user = users.value.find((item) => item.id === id)
-    if (user && user.account !== 'admin') user.status = status
-  }
-
-  function saveRole(payload: Omit<Role, 'id' | 'userCount'> & { id?: string }) {
-    if (payload.id) {
-      const index = roles.value.findIndex((item) => item.id === payload.id)
-      if (index >= 0) roles.value[index] = { ...roles.value[index], ...payload } as Role
-      syncRoleCounts()
-      return payload.id
-    }
-    const id = nextId('R', roles.value)
-    roles.value.push({ ...payload, id, userCount: 0 })
-    return id
-  }
-
-  function removeRole(id: string) {
-    const role = roles.value.find((item) => item.id === id)
-    if (!role || role.builtIn || users.value.some((item) => item.roleIds.includes(id))) return false
-    roles.value = roles.value.filter((item) => item.id !== id)
-    return true
-  }
-
-  function syncRoleCounts() {
-    roles.value.forEach((role) => {
-      role.userCount = users.value.filter((user) => user.roleIds.includes(role.id)).length
-    })
-  }
-
-  function savePermission(payload: Omit<Permission, 'id'> & { id?: string }) {
-    if (payload.id) {
-      const index = permissions.value.findIndex((item) => item.id === payload.id)
-      if (index >= 0) permissions.value[index] = { ...permissions.value[index], ...payload } as Permission
-      return payload.id
-    }
-    const id = nextId('P', permissions.value)
-    permissions.value.push({ ...payload, id })
-    return id
-  }
-
-  function saveOrder(payload: Omit<FirstLegOrder, 'id' | 'no' | 'createdAt' | 'timeline' | 'receivingWarehouseSnapshot'> & { id?: string }) {
-    const existing = payload.id ? orders.value.find((item) => item.id === payload.id) : undefined
-    const warehouse = warehouses.value.find((item) => item.id === payload.receivingWarehouseId)
-    const keepsExistingWarehouse = existing?.receivingWarehouseId === payload.receivingWarehouseId
-    if (!warehouse || (warehouse.status !== 'ACTIVE' && !keepsExistingWarehouse)) throw new Error('所选收货仓当前不可用于新订单')
-    const receivingWarehouseSnapshot = keepsExistingWarehouse && existing?.receivingWarehouseSnapshot
-      ? existing.receivingWarehouseSnapshot
-      : createPlatformReceivingWarehouseSnapshot(warehouse)
-    if (payload.id) {
-      const index = orders.value.findIndex((item) => item.id === payload.id)
-      if (index >= 0) {
-        const previous = orders.value[index]
-        const keepsPendingReview = previous.status === '待审核'
-        const time = new Date().toISOString().slice(0, 16).replace('T', ' ')
-        const timeline = [...previous.timeline]
-        if (keepsPendingReview) timeline.push({
-          time,
-          title: '后台修改待审核订单',
-          description: '平台已修正订单资料，订单继续保持待审核；本次修改已记录审计。',
-          operator: payload.operator === '未分配' ? '平台管理员' : payload.operator,
-        })
-        orders.value[index] = {
-          ...previous,
-          ...payload,
-          status: keepsPendingReview ? '待审核' : payload.status,
-          receivingWarehouseSnapshot,
-          timeline,
-        } as FirstLegOrder
-      }
-      return payload.id
-    }
-    const id = nextId('O', orders.value)
-    const no = `BY${new Date().toISOString().slice(0, 10).replace(/-/g, '')}${String(orders.value.length + 1).padStart(3, '0')}`
-    orders.value.unshift({
-      ...payload,
-      receivingWarehouseSnapshot,
-      id,
-      no,
-      createdAt: new Date().toISOString().slice(0, 16).replace('T', ' '),
-      timeline: [{ time: new Date().toISOString().slice(0, 16).replace('T', ' '), title: '后台创建订单', description: '平台工作人员创建头程订单。', operator: '平台管理员' }],
-    })
-    return id
-  }
-
-  function updateOrderStatus(id: string, status: OrderStatus, operator: string, note: string) {
-    const order = orders.value.find((item) => item.id === id)
-    if (!order) return
-    const transitions: Record<OrderStatus, OrderStatus[]> = { 草稿: ['待审核', '已取消'], 待审核: ['已受理', '已取消'], 已受理: ['已订舱', '已取消'], 已订舱: ['运输中', '已取消'], 运输中: ['已完成', '已取消'], 已完成: [], 已取消: [] }
-    if (status !== order.status && !transitions[order.status].includes(status)) throw new Error(`订单不能从“${order.status}”直接变更为“${status}”`)
-    order.status = status
-    order.operator = operator || order.operator
-    order.timeline.push({
-      time: new Date().toISOString().slice(0, 16).replace('T', ' '),
-      title: `状态更新为${status}`,
-      description: note || '平台更新订单处理状态。',
-      operator: operator || '平台管理员',
-    })
-  }
-
-  function recordCustomerModificationContact(id: string, operator: string) {
-    const order = orders.value.find((item) => item.id === id)
-    if (!order || order.status !== '待审核') throw new Error('仅待审核订单可记录联系客户修改')
-    order.timeline.push({ time: new Date().toISOString().slice(0, 16).replace('T', ' '), title: '联系客户修改订单', description: '已联系客户补充或修正订单资料，订单继续保持待审核。', operator })
-  }
-
-  function saveOrderDeliveryInfo(id: string, expressCompanyId: string, trackingNo: string, operator: string) {
-    const order = orders.value.find((item) => item.id === id)
-    const company = expressCompanies.value.find((item) => item.id === expressCompanyId)
-    if (!order) throw new Error('订单不存在')
-    if (!company) throw new Error('快递公司不存在')
-    if (company.status !== '合作中' && order.deliveryInfo?.expressCompanyId !== company.id) throw new Error('停用快递公司不能新增到履约信息')
-    const time = new Date().toISOString().slice(0, 16).replace('T', ' ')
-    order.deliveryInfo = {
-      expressCompanyId: company.id,
-      expressCompanyCode: company.code,
-      expressCompanyName: company.name,
-      trackingNo: trackingNo.trim(),
-      updatedAt: time,
-      operator,
-    }
-    order.timeline.push({
-      time,
-      title: '更新履约快递信息',
-      description: `${company.name} · ${trackingNo.trim()}`,
-      operator,
-    })
-  }
-
-  return {
-    customers,
-    users,
-    roles,
-    permissions,
-    warehouses,
-    expressCompanies,
-    counterparties,
-    orders,
-    activeUsers,
-    pendingCustomers,
-    activeWarehouses,
-    activeExpressCompanies,
-    activeCounterparties,
-    pendingOrders,
-    saveCustomer,
-    setCustomerStatus,
-    saveWarehouse,
-    setWarehouseStatus,
-    saveExpressCompany,
-    setExpressCompanyStatus,
-    saveCounterparty,
-    setCounterpartyStatus,
-    saveUser,
-    setUserStatus,
-    saveRole,
-    removeRole,
-    savePermission,
-    saveOrder,
-    updateOrderStatus,
-    recordCustomerModificationContact,
-    saveOrderDeliveryInfo,
-  }
-})
diff --git a/src/stores/auth.ts b/src/stores/auth.ts
deleted file mode 100644
index c126bff6..00000000
--- a/src/stores/auth.ts
+++ /dev/null
@@ -1,150 +0,0 @@
-import { computed, ref } from 'vue'
-import { defineStore } from 'pinia'
-import type { CurrentUser } from '@chongchong/shared'
-import { http, registerAuthRefreshHandler, unwrapApiResponse, type ApiEnvelope } from '@/api/http'
-import { listPlatformPermissions, type PlatformPermissionResource } from '@/api/platformIam'
-import { decodeJwtClaims } from '@/utils/jwt'
-
-const TOKEN_KEY = 'cc-admin-token'
-const REFRESH_TOKEN_KEY = 'cc-admin-refresh-token'
-const PERMISSION_CODES_KEY = 'cc-admin-permission-codes'
-
-interface LoginResponse {
-  tokenType: string
-  accessToken: string
-  expiresIn: number
-  refreshToken: string
-  refreshExpiresIn: number
-}
-
-function sessionFromToken(token: string) {
-  const claims = decodeJwtClaims(token)
-  if (claims.app_code !== 'PLATFORM') throw new Error('账号不属于当前应用端')
-  if (claims.exp && claims.exp * 1000 <= Date.now()) throw new Error('登录状态已过期，请重新登录')
-  return {
-    user: {
-      id: String(claims.user_id ?? ''),
-      name: claims.username || '平台用户',
-      account: claims.username || '',
-      roles: claims.roles ?? [],
-    } satisfies CurrentUser,
-    permissions: claims.permissions ?? [],
-  }
-}
-
-export const useAuthStore = defineStore('admin-auth', () => {
-  const token = ref(localStorage.getItem(TOKEN_KEY) || '')
-  const refreshToken = ref(localStorage.getItem(REFRESH_TOKEN_KEY) || '')
-  const user = ref<CurrentUser | null>(null)
-  const permissions = ref<string[]>([])
-  const permissionResources = ref<PlatformPermissionResource[]>([])
-  const isServerSession = ref(false)
-
-  if (token.value) {
-    try {
-      const session = sessionFromToken(token.value)
-      const cachedPermissions = JSON.parse(localStorage.getItem(PERMISSION_CODES_KEY) || '[]') as unknown
-      if (!Array.isArray(cachedPermissions)) throw new Error('权限缓存格式无效')
-      user.value = session.user
-      permissions.value = session.permissions.filter((code) => cachedPermissions.includes(code))
-      isServerSession.value = true
-    } catch {
-      token.value = ''
-      refreshToken.value = ''
-      localStorage.removeItem(TOKEN_KEY)
-      localStorage.removeItem(REFRESH_TOKEN_KEY)
-      localStorage.removeItem(PERMISSION_CODES_KEY)
-    }
-  }
-
-  const isAuthenticated = computed(() => Boolean(token.value))
-  const permissionCodes = computed<ReadonlySet<string>>(() => new Set(permissions.value))
-
-  async function applySession(result: LoginResponse) {
-    const session = sessionFromToken(result.accessToken)
-    token.value = result.accessToken
-    refreshToken.value = result.refreshToken
-    user.value = session.user
-    isServerSession.value = true
-    localStorage.setItem(TOKEN_KEY, token.value)
-    localStorage.setItem(REFRESH_TOKEN_KEY, refreshToken.value)
-    try {
-      permissionResources.value = await listPlatformPermissions()
-      const activeResourceCodes = new Set(permissionResources.value
-        .filter((resource) => resource.status === 'ACTIVE')
-        .map((resource) => resource.permissionCode))
-      permissions.value = session.permissions.filter((code) => activeResourceCodes.has(code))
-      localStorage.setItem(PERMISSION_CODES_KEY, JSON.stringify(permissions.value))
-    } catch (error) {
-      clearSession()
-      throw error
-    }
-  }
-
-  function clearSession() {
-    token.value = ''
-    refreshToken.value = ''
-    user.value = null
-    permissions.value = []
-    permissionResources.value = []
-    isServerSession.value = false
-    localStorage.removeItem(TOKEN_KEY)
-    localStorage.removeItem(REFRESH_TOKEN_KEY)
-    localStorage.removeItem(PERMISSION_CODES_KEY)
-  }
-
-  async function login(account: string, password: string) {
-    const response = await http.post<ApiEnvelope<LoginResponse>, ApiEnvelope<LoginResponse>>(
-      '/auth/login',
-      { username: account, password },
-    )
-    const result = unwrapApiResponse<LoginResponse>(response)
-    await applySession(result)
-  }
-
-  async function refreshSession() {
-    if (!refreshToken.value) throw new Error('刷新令牌不存在，请重新登录')
-    try {
-      const response = await http.post<ApiEnvelope<LoginResponse>, ApiEnvelope<LoginResponse>>(
-        '/auth/refresh',
-        { refreshToken: refreshToken.value },
-      )
-      const result = unwrapApiResponse<LoginResponse>(response)
-      await applySession(result)
-    } catch (error) {
-      clearSession()
-      throw error
-    }
-  }
-
-  registerAuthRefreshHandler(async () => {
-    await refreshSession()
-    if (!token.value) throw new Error('登录状态刷新失败')
-    return token.value
-  })
-
-  function logout() {
-    const accessToken = token.value
-    const tokenToRevoke = refreshToken.value
-    clearSession()
-    if (accessToken && tokenToRevoke) {
-      void http.post('/auth/logout', { refreshToken: tokenToRevoke }, {
-        headers: { Authorization: `Bearer ${accessToken}` },
-      }).catch(() => undefined)
-    }
-  }
-
-  return {
-    token,
-    refreshToken,
-    user,
-    permissions,
-    permissionResources,
-    isServerSession,
-    permissionCodes,
-    isAuthenticated,
-    login,
-    refreshSession,
-    logout,
-  }
-})
diff --git a/src/stores/unsavedWork.ts b/src/stores/unsavedWork.ts
deleted file mode 100644
index 256637e7..00000000
--- a/src/stores/unsavedWork.ts
+++ /dev/null
@@ -1,40 +0,0 @@
-import { ref } from 'vue'
-import { defineStore } from 'pinia'
-
-export interface UnsavedWorkEntry {
-  key: string
-  label: string
-  dirty: boolean
-  requiredPermission: string | null
-}
-
-export const useUnsavedWorkStore = defineStore('unsaved-work', () => {
-  const entries = ref<UnsavedWorkEntry[]>([])
-
-  function upsert(entry: UnsavedWorkEntry) {
-    const index = entries.value.findIndex((item) => item.key === entry.key)
-    if (index === -1) {
-      entries.value.push(entry)
-      return
-    }
-    entries.value[index] = entry
-  }
-
-  function remove(key: string) {
-    const index = entries.value.findIndex((item) => item.key === key)
-    if (index !== -1) entries.value.splice(index, 1)
-  }
-
-  function findBlocking(candidatePermissions: ReadonlySet<string>, willLeave: boolean) {
-    return entries.value.filter((entry) => entry.dirty && (
-      willLeave
-      || (entry.requiredPermission !== null && !candidatePermissions.has(entry.requiredPermission))
-    ))
-  }
-
-  function clear() {
-    entries.value = []
-  }
-
-  return { entries, upsert, remove, findBlocking, clear }
-})
diff --git a/src/styles/adminDensity.css b/src/styles/adminDensity.css
new file mode 100644
index 00000000..14bdd2e4
--- /dev/null
+++ b/src/styles/adminDensity.css
@@ -0,0 +1,190 @@
+@import './adminDensityTokens.css';
+
+/* Explicit opt-in for approved dense business workspaces and teleported dialogs. */
+.admin-density, .admin-density-dialog, .admin-density-drawer {
+  --el-font-size-base: var(--admin-font-body);
+  --el-component-size: var(--admin-control-height);
+  --cc-list-table-font-size: var(--admin-font-body);
+  --cc-list-action-font-size: var(--admin-font-body);
+  --cc-list-query-font-size: var(--admin-font-body);
+  font-size: var(--admin-font-body, 13px);
+}
+.admin-density .surface-panel, .admin-density .query-toolbar {
+  border-radius: var(--admin-radius, 4px); box-shadow: none;
+}
+.admin-density .el-table, .admin-density-dialog .el-table {
+  --el-table-header-bg-color: var(--admin-label-bg);
+  --el-table-border-color: var(--admin-table-border);
+  --el-table-row-hover-bg-color: var(--admin-row-hover);
+  font-size: var(--admin-font-body, 13px);
+}
+.admin-density .el-table .el-table__cell, .admin-density .data-table .el-table .el-table__cell, .admin-density-dialog .el-table .el-table__cell { height: var(--admin-row-height, 36px); padding: var(--admin-space-1, 4px) 0; }
+.admin-density .el-table .cell, .admin-density-dialog .el-table .cell { line-height: 22px; }
+.admin-density .el-table .el-button--small, .admin-density-dialog .el-table .el-button--small { height: var(--admin-action-height, 28px); padding: var(--admin-space-1, 4px) var(--admin-space-3, 8px); }
+.admin-density .el-table__body tr.el-table__row--striped td.el-table__cell { background: var(--admin-row-stripe); }
+.admin-density .data-table .data-table__pagination { min-height: 48px; padding: var(--admin-space-3, 8px) var(--admin-space-5, 12px); }
+.admin-density .el-empty { padding: var(--admin-space-5, 12px) 0; }
+.admin-density .el-empty__image { display: none; }
+.admin-density .el-empty__description { margin-top: 0; }
+.admin-density .el-empty__description p { font-size: var(--admin-font-body, 13px); }
+.admin-density-dialog .el-form-item__label { line-height: 22px; }
+.admin-density-dialog .el-descriptions__label.el-descriptions__cell { font-size: var(--admin-font-caption, 12px); background: var(--admin-label-bg); }
+.admin-density-dialog .el-descriptions__content.el-descriptions__cell { font-size: var(--admin-font-body, 13px); overflow-wrap: anywhere; }
+.admin-density-dialog.el-dialog.is-fullscreen { width: 100%; max-width: 100%; height: 100vh; max-height: 100vh; margin: 0; border-radius: 0; }
+.admin-density-dialog.el-dialog.admin-density-workspace:not(.is-fullscreen) { height: 92vh; max-height: 92vh; margin-top: 4vh; }
+.admin-density-dialog .el-dialog__headerbtn { top: 0; }
+.admin-density-dialog .app-dialog__native-fullscreen-control { top: 6px; }
+.admin-density-confirm.el-message-box { --el-font-size-base: var(--admin-font-body); border-radius: var(--admin-radius, 4px); padding: var(--admin-space-5, 12px) var(--admin-space-6, 16px); }
+.admin-density-confirm .el-message-box__title { font-size: var(--admin-font-title, 16px); }
+
+/* Dialogs are teleported; opt in explicitly instead of styling all AppDialog instances. */
+.admin-density-dialog.el-dialog {
+  --el-font-size-base: var(--admin-font-body);
+  --el-component-size: var(--admin-control-height);
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  padding: 0;
+  border-radius: var(--admin-radius, 4px);
+}
+.admin-density-dialog.el-dialog:not(.is-fullscreen) { margin-top: 6vh; max-height: 88vh; }
+.admin-density-dialog.el-dialog .el-dialog__header { flex: 0 0 auto; margin: 0; padding: var(--admin-space-4, 10px) 48px var(--admin-space-4, 10px) var(--admin-space-6, 16px); border-bottom: 1px solid var(--cc-border); }
+.admin-density-dialog.el-dialog .el-dialog__title { font-size: var(--admin-font-title, 16px); line-height: 24px; font-weight: 600; }
+.admin-density-dialog.el-dialog .el-dialog__body { min-height: 0; overflow-y: auto; overscroll-behavior: contain; padding: var(--admin-space-5, 12px) var(--admin-space-6, 16px); }
+.admin-density-dialog.el-dialog .el-dialog__footer { flex: 0 0 auto; padding: var(--admin-space-3, 8px) var(--admin-space-6, 16px); border-top: 1px solid var(--cc-border); }
+.admin-density-dialog.el-dialog .el-table { font-size: var(--admin-font-body, 13px); }
+.admin-density-dialog.el-dialog .el-table__cell { height: var(--admin-row-height, 36px); padding: var(--admin-space-1, 4px) 0; }
+.admin-density-dialog.el-dialog .el-table .cell { line-height: 22px; }
+.admin-density-dialog.el-dialog .el-form-item { margin-bottom: 14px; }
+.admin-density-dialog.el-dialog .el-form-item__label { font-size: var(--admin-font-body, 13px); }
+.admin-density-dialog.el-dialog .el-alert { padding: var(--admin-space-3, 8px) var(--admin-space-4, 10px); border-radius: 3px; }
+.admin-density-dialog.el-dialog .el-empty { padding: var(--admin-space-5, 12px) 0; }
+.admin-density-dialog.el-dialog .el-empty__image { display: none; }
+.admin-density-dialog.el-dialog .el-empty__description { margin-top: 0; }
+
+/* Headers must keep units visible even when a saved column width is narrow. */
+.admin-density .el-table th.el-table__cell .cell,
+.admin-density-dialog .el-table th.el-table__cell .cell { white-space: normal; overflow-wrap: anywhere; text-overflow: clip; line-height: 18px; }
+
+/* Shared outlined business actions. Pages choose tone, never redefine paint/size. */
+:is(.admin-density, .admin-density-dialog) .el-button.density-action {
+  --action-color: var(--admin-action-neutral);
+  --action-border: var(--admin-action-neutral-border);
+  --action-hover-bg: var(--admin-label-bg);
+  --el-button-text-color: var(--action-color);
+  --el-button-border-color: var(--action-border);
+  --el-button-bg-color: var(--admin-surface);
+  --el-button-hover-text-color: var(--action-color);
+  --el-button-hover-border-color: var(--action-color);
+  --el-button-hover-bg-color: var(--action-hover-bg);
+  --el-button-active-text-color: var(--action-color);
+  --el-button-active-border-color: var(--action-color);
+  --el-button-active-bg-color: var(--action-hover-bg);
+  --el-button-disabled-text-color: #a1a1aa;
+  --el-button-disabled-border-color: var(--admin-table-border);
+  --el-button-disabled-bg-color: var(--admin-surface);
+  height: var(--admin-action-height); min-height: var(--admin-action-height);
+  padding: var(--admin-space-1) var(--admin-space-4); margin: 0;
+  border: 1px solid var(--action-border); border-radius: var(--admin-action-radius);
+  color: var(--action-color); background: var(--admin-surface);
+  font-size: var(--admin-font-body); font-weight: 600; box-shadow: none;
+}
+:is(.admin-density, .admin-density-dialog) .density-action[data-tone="warning"] { --action-color: var(--admin-action-warning); --action-border: var(--admin-action-warning-border); --action-hover-bg: var(--admin-action-warning-hover); }
+:is(.admin-density, .admin-density-dialog) .density-action[data-tone="purple"] { --action-color: var(--admin-action-purple); --action-border: var(--admin-action-purple-border); --action-hover-bg: var(--admin-action-purple-hover); }
+:is(.admin-density, .admin-density-dialog) .density-action[data-tone="primary"] { --action-color: var(--admin-action-primary); --action-border: var(--admin-action-primary-border); --action-hover-bg: var(--admin-action-primary-hover); }
+:is(.admin-density, .admin-density-dialog) .density-action[data-tone="success"] { --action-color: var(--admin-action-success); --action-border: var(--admin-action-success-border); --action-hover-bg: var(--admin-action-success-hover); }
+:is(.admin-density, .admin-density-dialog) .density-action[data-tone="danger"] { --action-color: var(--admin-action-danger); --action-border: var(--admin-action-danger-border); --action-hover-bg: var(--admin-action-danger-hover); }
+:is(.admin-density, .admin-density-dialog) .el-button.density-action:hover:not(:disabled) { color: var(--action-color); border-color: var(--action-color); background: var(--action-hover-bg); box-shadow: none; }
+:is(.admin-density, .admin-density-dialog) .el-button.density-action:disabled { color: var(--el-button-disabled-text-color); border-color: var(--el-button-disabled-border-color); background: var(--admin-surface); }
+:is(.admin-density, .admin-density-dialog) .el-button.density-action:focus-visible { outline: 2px solid var(--action-color); outline-offset: 2px; }
+
+/* Detail headings and summaries shared by domestic and overseas pages. */
+.admin-density .detail-page-layout.density-detail-layout { gap: 0; background: var(--admin-surface); }
+.admin-density .density-detail-layout > .detail-page-layout__header { border-bottom: 1px solid var(--cc-border); }
+.admin-density .density-detail-layout > .detail-page-layout__content { padding: var(--admin-space-5); }
+.admin-density .density-detail-header { display: flex; min-width: 0; min-height: 40px; align-items: center; justify-content: space-between; gap: var(--admin-space-5, 12px); margin-bottom: 0; padding: var(--admin-space-3, 8px) var(--admin-space-5, 12px); background: var(--admin-surface, #fff); }
+.admin-density .density-detail-heading { display: flex; min-width: 0; align-items: center; gap: var(--admin-space-4, 10px); }
+.admin-density .density-detail-title { min-width: 0; margin: 0; color: #172033; font-size: var(--admin-font-title, 16px); line-height: 1.5; overflow-wrap: anywhere; }
+:is(.admin-density, .admin-density-dialog) .density-detail-overview { border-bottom: 1px solid var(--cc-border); display: flex; flex-wrap: wrap; gap: var(--admin-space-2, 6px) var(--admin-space-7, 24px); margin: 0; padding: var(--admin-space-3, 8px) var(--admin-space-5, 12px); background: var(--admin-surface, #fff); }
+:is(.admin-density, .admin-density-dialog) .density-detail-overview > div { display: flex; min-width: 0; align-items: baseline; gap: var(--admin-space-2, 6px); }
+:is(.admin-density, .admin-density-dialog) .density-detail-overview dt { flex: 0 0 auto; color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); }
+:is(.admin-density, .admin-density-dialog) .density-detail-overview dd { min-width: 0; margin: 0; color: var(--cc-text); font-size: var(--admin-font-body, 13px); overflow-wrap: anywhere; font-variant-numeric: tabular-nums; }
+:is(.admin-density, .admin-density-dialog) .density-detail-overview small { color: var(--cc-muted); font-size: var(--admin-font-caption, 12px); }
+
+/* Back navigation stays in the detail heading, beside its business identifier. */
+.admin-density .el-button.density-back { height: var(--admin-control-height); padding: 0; border: 0; background: transparent; color: var(--cc-muted); font-size: var(--admin-font-body); font-weight: 400; box-shadow: none; }
+.admin-density .el-button.density-back:hover { color: var(--cc-primary); background: transparent; }
+.admin-density .el-button.density-back:focus-visible { outline: 2px solid var(--cc-primary); outline-offset: 2px; }
+
+/* Navigation tabs shared by customer/order details. Layout-specific borders stay local. */
+.admin-density .density-tabs { display: flex; gap: 0; overflow-x: auto; overflow-y: hidden; background: var(--admin-surface); scrollbar-width: thin; }
+.admin-density .density-tabs > button,
+.admin-density .density-element-tabs > .el-tabs__header .el-tabs__nav .el-tabs__item { position: relative; display: inline-flex; min-width: max-content; height: var(--admin-tab-height); min-height: var(--admin-tab-height); flex: 0 0 auto; align-items: center; justify-content: center; gap: var(--admin-space-2); padding: 0 var(--admin-space-6); border: 0; background: transparent; color: #475467; font-size: var(--admin-font-body); font-weight: 500; white-space: nowrap; cursor: pointer; }
+.admin-density .density-tabs > button::after,
+.admin-density .density-element-tabs > .el-tabs__header .el-tabs__nav .el-tabs__item::after { position: absolute; right: var(--admin-space-5); bottom: 0; left: var(--admin-space-5); height: 2px; background: transparent; content: ''; }
+.admin-density .density-tabs > button:hover,
+.admin-density .density-element-tabs > .el-tabs__header .el-tabs__nav .el-tabs__item:hover { background: #fafbff; color: #344054; }
+.admin-density .density-tabs > button.active,
+.admin-density .density-element-tabs > .el-tabs__header .el-tabs__nav .el-tabs__item.is-active { background: #f7f8ff; color: var(--cc-primary); font-weight: 600; }
+.admin-density .density-tabs > button.active::after,
+.admin-density .density-element-tabs > .el-tabs__header .el-tabs__nav .el-tabs__item.is-active::after { background: var(--cc-primary); }
+.admin-density .density-tabs > button:focus-visible,
+.admin-density .density-element-tabs > .el-tabs__header .el-tabs__nav .el-tabs__item:focus-visible { outline: 2px solid var(--cc-primary); outline-offset: -2px; }
+.admin-density .density-tab-icon { display: inline-flex; width: var(--admin-tab-icon-slot); height: var(--admin-tab-icon-slot); flex: 0 0 var(--admin-tab-icon-slot); align-items: center; justify-content: center; font: var(--admin-tab-icon-size)/1 "Segoe UI Emoji", "Apple Color Emoji", "Noto Color Emoji", sans-serif; }
+
+.admin-density-drawer .el-drawer__header { margin-bottom: 0; padding: var(--admin-space-5) var(--admin-space-6); border-bottom: 1px solid var(--cc-border); }
+.admin-density-drawer .el-drawer__title { font-size: var(--admin-font-title); }
+.admin-density-drawer .el-drawer__body { padding: var(--admin-space-5) var(--admin-space-6); }
+.admin-density-drawer .el-drawer__footer { padding: var(--admin-space-5) var(--admin-space-6); border-top: 1px solid var(--cc-border); }
+
+/* Reusable row action group; no business action names in the shared layer. */
+.admin-density .data-table .density-actions { --cc-list-action-sibling-margin: 0px; display: flex; align-items: center; gap: var(--admin-space-2); }
+.admin-density .data-table .density-actions > :is(.el-button, .el-dropdown) { margin-left: 0; }
+
+/* The same action spacing also applies to native tables and teleported content. */
+:is(.admin-density, .admin-density-dialog) .density-actions { display: flex; align-items: center; gap: var(--admin-space-2); }
+:is(.admin-density, .admin-density-dialog) .density-actions > :is(.el-button, .el-dropdown) { margin-left: 0; }
+
+.admin-density .density-detail-heading > .density-back { flex-shrink: 0; }
+
+/* Element tabs retain their keyboard handling and use the shared detail-tab scale. */
+.admin-density .density-element-tabs { min-width: 0; background: var(--admin-surface); border-bottom: 1px solid var(--admin-table-border); }
+.admin-density .density-element-tabs > .el-tabs__header { margin: 0; }
+.admin-density .density-element-tabs > .el-tabs__header .el-tabs__nav-wrap::after { height: 1px; background: var(--cc-border); }
+.admin-density .density-element-tabs > .el-tabs__header .el-tabs__active-bar { display: none; }
+.admin-density .density-element-tabs:not(.density-contained-tabs) > .el-tabs__content { display: none; }
+.admin-density .density-contained-tabs > .el-tabs__content { padding: var(--admin-space-5); }
+
+/* Explicit page descriptions share the teleported detail table scale. */
+:is(.admin-density, .admin-density-dialog) .density-descriptions .el-descriptions__label.el-descriptions__cell { width: var(--admin-label-width); font-size: var(--admin-font-caption); background: var(--admin-label-bg); }
+:is(.admin-density, .admin-density-dialog) .density-descriptions .el-descriptions__content.el-descriptions__cell { font-size: var(--admin-font-body); overflow-wrap: anywhere; }
+:is(.admin-density, .admin-density-dialog) .density-descriptions .el-descriptions__cell { height: var(--admin-row-height); padding: var(--admin-space-2) var(--admin-space-3); }
+
+/* Opted-in grouped forms use the same labels and spacing on pages and in dialogs. */
+:is(.admin-density, .admin-density-dialog) .density-form,
+.admin-density.density-form { --el-form-label-font-size: var(--admin-font-body); }
+:is(.admin-density, .admin-density-dialog) .density-form .el-form-item,
+.admin-density.density-form .el-form-item { margin-bottom: var(--admin-space-5); }
+
+/* Opted-in FormSection consumers share form headings without page-level paint. */
+:is(.admin-density, .admin-density-dialog) .form-section.density-form-section { padding: var(--admin-space-5) 0; }
+:is(.admin-density, .admin-density-dialog) .form-section.density-form-section:first-child { padding-top: 0; }
+:is(.admin-density, .admin-density-dialog) .form-section.density-form-section:last-child { padding-bottom: 0; }
+:is(.admin-density, .admin-density-dialog) .density-form-section .form-section__heading { margin-bottom: var(--admin-space-3); }
+:is(.admin-density, .admin-density-dialog) .density-form-section .form-section__heading h2 { font-size: var(--admin-font-section); }
+:is(.admin-density, .admin-density-dialog) .density-form-section .form-section__heading p { margin-top: var(--admin-space-1); font-size: var(--admin-font-caption); }
+:is(.admin-density, .admin-density-dialog) .density-form :is(.el-select, .el-input-number, .el-date-editor) { width: 100%; }
+
+/* Existing native data tables keep their business column widths and sticky cells. */
+:is(.admin-density, .admin-density-dialog) .density-table { width: 100%; border-collapse: collapse; font-size: var(--admin-font-body); }
+:is(.admin-density, .admin-density-dialog) .density-table :is(th, td) { height: var(--admin-row-height); padding: var(--admin-space-1) var(--admin-space-3); border: 1px solid var(--admin-table-border); text-align: left; vertical-align: middle; overflow-wrap: anywhere; }
+:is(.admin-density, .admin-density-dialog) .density-table th { background: var(--admin-label-bg); color: var(--cc-muted); font-weight: 600; }
+:is(.admin-density, .admin-density-dialog) .density-table td { background: var(--admin-surface); }
+:is(.admin-density, .admin-density-dialog) .density-table tbody tr:nth-child(even) td { background: var(--admin-row-stripe); }
+:is(.admin-density, .admin-density-dialog) .density-table tbody tr:hover td { background: var(--admin-row-hover); }
+
+/* Continuous description grid. Page owns column count and wide-field spans only. */
+:is(.admin-density, .admin-density-dialog) .density-fields { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 0; margin: 0; border-top: 1px solid var(--cc-border); border-left: 1px solid var(--cc-border); background: var(--admin-surface); }
+:is(.admin-density, .admin-density-dialog) .density-fields > div { display: grid; grid-template-columns: var(--admin-field-label-width, var(--admin-label-width)) minmax(0, 1fr); min-width: 0; min-height: var(--admin-row-height); gap: 0; padding: 0; border-right: 1px solid var(--cc-border); border-bottom: 1px solid var(--cc-border); border-radius: 0; background: var(--admin-surface); }
+:is(.admin-density, .admin-density-dialog) .density-fields dt { display: flex; align-items: center; margin: 0; padding: var(--admin-space-2) var(--admin-space-3); color: var(--cc-muted); background: var(--admin-label-bg); font-size: var(--admin-font-caption); line-height: 20px; }
+:is(.admin-density, .admin-density-dialog) .density-fields dd { align-self: center; min-width: 0; margin: 0; padding: var(--admin-space-2) var(--admin-space-3); color: #25324a; font-size: var(--admin-font-body); font-weight: 400; line-height: 20px; overflow-wrap: anywhere; white-space: normal; }
diff --git a/src/styles/adminDensity.test.ts b/src/styles/adminDensity.test.ts
new file mode 100644
index 00000000..0c0cac4e
--- /dev/null
+++ b/src/styles/adminDensity.test.ts
@@ -0,0 +1,508 @@
+import { readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import ts from 'typescript'
+import { describe, expect, it } from 'vitest'
+import { compileStyle, parse } from 'vue/compiler-sfc'
+
+// Approved entry/consumer inventory. Do not discover unrelated menus recursively.
+const cargoConsumers = [
+  'ocean-bookings/pages/OceanBookingsView.vue', 'ocean-bookings/pages/OceanBookingDetailView.vue',
+  'ocean-bookings/components/OceanBookingDocumentsPanel.vue', 'ocean-bookings/components/OceanBookingPrintDialog.vue',
+  'trucking/pages/TruckAppointmentsView.vue', 'trucking/pages/TruckAppointmentCreateView.vue',
+  'trucking/pages/TruckAppointmentDetailView.vue', 'trucking/components/TruckAppointmentForm.vue',
+  'trucking/components/TruckAttachmentDialog.vue', 'container-loading/pages/ContainersView.vue',
+  'container-loading/pages/ContainerDetailView.vue', 'container-loading/pages/SmartLoadingWorkbenchView.vue',
+  'container-loading/components/OceanBookingLinkDialog.vue', 'container-loading/components/ContainerOverviewPanel.vue',
+  'container-loading/components/ContainerCustomsPanel.vue', 'container-loading/components/ContainerLastLegFeesPanel.vue',
+  'loading-lists/components/ContainerFeesPanel.vue', 'port-schedules/components/CarrierScheduleQueryPanel.vue',
+]
+const overseasConsumers = [
+  'overseas-warehouse/pages/LastMileOrdersView.vue',
+  'overseas-warehouse/pages/LastMileOrderDetailView.vue',
+  'overseas-warehouse/pages/InboundOrdersView.vue',
+  'overseas-warehouse/pages/InboundOrderDetailView.vue',
+  'overseas-warehouse/pages/DispatchesView.vue',
+  'overseas-warehouse/pages/DispatchDetailView.vue',
+  'overseas-warehouse/pages/OutboundsView.vue',
+  'overseas-warehouse/pages/OutboundDetailView.vue',
+  'overseas-warehouse/pages/DeliveryOrdersView.vue',
+  'overseas-warehouse/pages/DeliveryOrderDetailView.vue',
+  'overseas-warehouse/pages/RelabelOrdersView.vue',
+  'overseas-warehouse/pages/RelabelOrderDetailView.vue',
+  'overseas-warehouse/pages/PalletsView.vue',
+  'overseas-warehouse/pages/PalletDetailView.vue',
+  'overseas-warehouse/pages/InventoryView.vue',
+  'overseas-warehouse/pages/InventoryDetailView.vue',
+  'overseas-warehouse/pages/InventoryTransactionsView.vue',
+  'overseas-warehouse/pages/ReturnInventoryManagementView.vue',
+  'overseas-warehouse/components/WarehouseTransferReviewDialog.vue',
+  'overseas-warehouse/components/SmartDispatchDialog.vue',
+  'overseas-warehouse/components/DeliveryDocumentsDialog.vue',
+]
+const overseasBusinessConsumers = [
+  'overseas-business/pages/PurchaseOrdersView.vue', 'overseas-business/pages/PurchaseOrderDetailView.vue',
+  'overseas-business/pages/PurchaseOrderEditView.vue', 'overseas-business/pages/TransportOrdersView.vue',
+  'overseas-business/pages/TransportOrderFormView.vue',
+]
+const customerServiceConsumers = [
+  'overseas-warehouse/pages/ExceptionOrdersView.vue', 'overseas-warehouse/pages/CustomerVisitsView.vue',
+]
+const financeConsumers = [
+  'finance/pages/FinanceCustomerAccountsView.vue', 'finance/pages/FinanceCustomerArapView.vue',
+  'finance/pages/FinanceCustomerStatementsView.vue', 'finance/pages/FinanceFormalSettlementPage.vue',
+  'finance/pages/FinanceReceivableStatisticsView.vue',
+]
+const generalCatalogConsumers = [
+  'suppliers/pages/SuppliersView.vue',
+  'suppliers/pages/SupplierDetailView.vue',
+  'suppliers/pages/SupplierFormView.vue',
+  'suppliers/components/SupplierLicenseDialog.vue',
+  'overseas-master-data/pages/ExchangeRatesView.vue',
+  'overseas-master-data/pages/OverseasQuotesView.vue',
+  'overseas-master-data/pages/VehiclesView.vue',
+  'overseas-master-data/pages/VehicleDetailView.vue',
+  'master-data/express-companies/pages/ExpressCompaniesView.vue',
+  'master-data/counterparties/pages/PartnersView.vue',
+  'fee-items/pages/FeeItemsView.vue',
+  'warehouses/pages/WarehousesView.vue',
+  'fba-pricing/carrier-rates/pages/CarrierRatesView.vue',
+  'fba-pricing/carrier-rates/pages/CarrierRateDetailView.vue',
+  'downloads/pages/DownloadCenterView.vue',
+]
+const notificationConsumers = [
+  'notifications/pages/PlatformNotificationsView.vue', 'notifications/pages/MessageManagementView.vue',
+  'notifications/pages/MessageTemplatesView.vue', 'notifications/components/MessageComposerDialog.vue',
+  'notifications/components/TemplateEditorDialog.vue',
+]
+const systemConsumers = ['iam/pages/InternalUsersView.vue', 'iam/pages/RolesView.vue', 'iam/pages/PermissionsView.vue']
+const consumers = [
+  ...notificationConsumers,
+  ...systemConsumers,
+  ...generalCatalogConsumers,
+  ...financeConsumers,
+  ...customerServiceConsumers,
+  ...overseasBusinessConsumers,
+  ...overseasConsumers,
+  ...cargoConsumers,
+  'customers/pages/CustomersView.vue', 'customers/pages/CustomerDetailView.vue',
+  'customers/pages/OverseasStorageFeesView.vue', 'customers/components/CustomerBillingRulesPanel.vue',
+  'unified-orders/components/InboundFeeDetailManager.vue', 'unified-orders/components/OrderDeclarationEditorDialog.vue',
+  'customers/CustomerOverseasStorageFeePanel.vue', 'unified-orders/pages/UnifiedOrdersView.vue',
+  'inbounds/core/DropshipPalletPrintPanel.vue',
+  'inbounds/components/InboundTaskList.vue', 'inbounds/measurement/InboundMeasurementDialog.vue',
+  'inbounds/measurement/InboundMeasurementPanel.vue', 'inbounds/review/MeasurementReviewPanel.vue',
+  'inbounds/weight/components/WeightOcrPanel.vue', 'loading-lists/pages/PreloadPlanDetailView.vue',
+  'loading-lists/components/LoadingListsView.vue', 'loading-lists/components/LoadingListDetailDrawer.vue',
+  'loading-lists/components/PalletLabelPrintDialog.vue', 'warehouse-resources/locations/pages/LocationsView.vue',
+  'warehouse-resources/pallets/pages/PalletsView.vue', 'domestic-containers/pages/DomesticContainersView.vue',
+  'domestic-containers/pages/DomesticContainerInventoryDetailView.vue',
+  'container-loading/components/ContainerSimulationCreate.vue', 'audit/components/CustomerAuditLogsPanel.vue',
+]
+const moduleCss = ['iam/iamDensity.css', 'finance/financeDensity.css', 'overseas-business/overseasBusinessDensity.css', 'customers/customerDensity.css', 'unified-orders/styles/orderDensity.css', 'inbounds/measurement/measurementDensity.css', 'domestic-containers/pages/domesticContainersSummary.css']
+const read = (file: string) => readFileSync(resolve(process.cwd(), 'src', file), 'utf8')
+const domesticPages = [
+  { title: '订单列表', path: '/orders', file: 'unified-orders/pages/UnifiedOrdersView.vue' },
+  { title: '订单测量', path: '/inbounds/measurements', file: 'inbounds/components/InboundTaskList.vue', entry: 'inbounds/pages/InboundMeasurementsView.vue', component: 'InboundTaskList', mode: 'measurement' },
+  { title: '测量数据审核', path: '/inbounds/measurement-reviews', file: 'inbounds/components/InboundTaskList.vue', entry: 'inbounds/pages/MeasurementReviewsView.vue', component: 'InboundTaskList', mode: 'review' },
+  { title: '预装清单', path: '/loading-plans', file: 'loading-lists/components/LoadingListsView.vue', entry: 'loading-lists/pages/PreloadPlansView.vue', component: 'LoadingListsView', mode: 'preload' },
+  { title: '库位管理', path: '/master-data/locations', file: 'warehouse-resources/locations/pages/LocationsView.vue' },
+  { title: '托盘管理', path: '/master-data/pallets', file: 'warehouse-resources/pallets/pages/PalletsView.vue' },
+  { title: '整柜业务', path: '/domestic-containers', file: 'domestic-containers/pages/DomesticContainersView.vue' },
+]
+const customerPages = [
+  { title: '客户列表', path: '/customers', file: 'customers/pages/CustomersView.vue' },
+  { title: '海外仓阶梯费用', path: '/customers/overseas-storage-fees', file: 'customers/pages/OverseasStorageFeesView.vue' },
+]
+const densityPages = [...new Set([
+  ...notificationConsumers.filter(file => file.includes('/pages/')),
+  ...systemConsumers,
+  ...generalCatalogConsumers.filter(file => file.includes('/pages/')),
+  ...financeConsumers,
+  ...customerServiceConsumers,
+  ...overseasBusinessConsumers,
+  ...overseasConsumers.filter(file => !file.endsWith('PalletDetailView.vue')),
+  ...cargoConsumers.filter(file => file.includes('/pages/') || ['ContainerOverviewPanel.vue', 'ContainerCustomsPanel.vue', 'ContainerLastLegFeesPanel.vue', 'ContainerFeesPanel.vue', 'OceanBookingDocumentsPanel.vue'].some(name => file.endsWith(name))),
+  ...domesticPages.map(page => page.file), 'loading-lists/pages/PreloadPlanDetailView.vue',
+  'loading-lists/components/LoadingListDetailDrawer.vue', 'domestic-containers/pages/DomesticContainerInventoryDetailView.vue',
+  ...customerPages.map(page => page.file), 'customers/pages/CustomerDetailView.vue', 'audit/components/CustomerAuditLogsPanel.vue',
+])]
+type TemplateNode = NonNullable<NonNullable<ReturnType<typeof parse>['descriptor']['template']>['ast']>['children'][number]
+type ElementNode = Extract<TemplateNode, { type: 1 }>
+const classesOf = (node: ElementNode, preload = true, dense = preload, workbench = 'DOMESTIC'): string[] => node.props.flatMap(prop => {
+  if (prop.type === 6 && prop.name === 'class') return prop.value?.content.split(/\s+/) ?? []
+  if (prop.type !== 7 || prop.name !== 'bind' || prop.arg?.type !== 4 || prop.arg.content !== 'class' || prop.exp?.type !== 4 || !prop.exp.content.includes('density')) return []
+  // Evaluate only the authored density class binding with the shared component's two modes.
+  const value = new Function('mode', 'isPreload', 'dense', 'isDomestic', 'isOverseas', `return (${prop.exp.content})`)(preload ? 'preload' : 'confirmed', preload, dense, workbench === 'DOMESTIC', workbench === 'OVERSEAS') as Record<string, boolean>
+  const flatten = (value: unknown): string[] => typeof value === 'string' ? value.split(/\s+/) : Array.isArray(value) ? value.flatMap(flatten) : value && typeof value === 'object' ? Object.entries(value).filter(([, enabled]) => enabled).flatMap(([names]) => names.split(/\s+/)) : []
+  return flatten(value)
+})
+const styles = [
+  ...parse(read('shared/components/BatchImportDialog.vue')).descriptor.styles.map(style => ({ file: 'BatchImportDialog.vue', css: style.content })),
+  ...consumers.flatMap(file => parse(read(`modules/${file}`)).descriptor.styles.map(style => ({ file, css: style.content }))),
+  ...moduleCss.map(file => ({ file, css: read(`modules/${file}`) })),
+]
+const shared = read('styles/adminDensity.css')
+const tokens = read('styles/adminDensityTokens.css')
+const cssRoot = (css: string) => {
+  const result = compileStyle({ source: css, filename: 'density.css', id: 'density-contract', trim: false })
+  expect(result.errors).toEqual([])
+  return result.rawResult!.root
+}
+
+describe('approved Admin density ownership', () => {
+  it('keeps dashboard visualizations outside detail-field table styling', () => {
+    const dashboard = read('modules/dashboard/pages/DashboardView.vue')
+    expect(dashboard).toContain('class="dashboard-metrics"')
+    expect(dashboard).toContain('class="dashboard-metric-mark"')
+    expect(dashboard).not.toContain('density-fields')
+  })
+
+  it('opts application-shell confirmations in even before a business page loads', () => {
+    const entries = ['app/layouts/AppLayout.vue', 'app/components/WorkspaceTabs.vue', 'app/router/index.ts', 'main.ts']
+    let count = 0
+    for (const file of entries) {
+      const source = read(file)
+      expect(source, file).toContain("@/styles/adminDensity.css")
+      const script = file.endsWith('.vue') ? parse(source).descriptor.scriptSetup!.content : source
+      const tree = ts.createSourceFile(file, script, ts.ScriptTarget.Latest, true)
+      const visit = (node: ts.Node) => {
+        if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.expression.getText(tree) === 'ElMessageBox') {
+          count += 1
+          const options = node.arguments[2]
+          expect(options && ts.isObjectLiteralExpression(options), file).toBe(true)
+          const customClass = options && ts.isObjectLiteralExpression(options) ? options.properties.find(prop => ts.isPropertyAssignment(prop) && prop.name.getText(tree) === 'customClass') : undefined
+          expect(customClass && ts.isPropertyAssignment(customClass) && ts.isStringLiteral(customClass.initializer) && customClass.initializer.text, file).toBe('admin-density-confirm')
+        }
+        ts.forEachChild(node, visit)
+      }
+      visit(tree)
+    }
+    expect(count).toBe(5)
+  })
+
+
+  it('checks dialog roots along actual static and dynamic Vue imports from approved consumers', () => {
+    const pending = consumers.map(file => resolve(process.cwd(), 'src/modules', file))
+    const seen = new Set<string>()
+    while (pending.length) {
+      const file = pending.shift()!
+      if (seen.has(file)) continue
+      seen.add(file)
+      const descriptor = parse(readFileSync(file, 'utf8')).descriptor
+      const enqueue = (reference: string) => {
+        if (!reference.endsWith('.vue')) return
+        if (reference.startsWith('@/')) pending.push(resolve(process.cwd(), 'src', reference.slice(2)))
+        else if (reference.startsWith('.')) pending.push(resolve(dirname(file), reference))
+      }
+      for (const script of [descriptor.script, descriptor.scriptSetup]) {
+        if (!script) continue
+        const ast = ts.createSourceFile(file, script.content, ts.ScriptTarget.Latest, true)
+        const visitImports = (node: ts.Node) => {
+          if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.expression.getText(ast) === 'ElMessageBox') {
+            expect(node.arguments[2]?.getText(ast), file + ': reachable confirmation').toContain('admin-density-confirm')
+          }
+          if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) enqueue(node.moduleSpecifier.text)
+          if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+            const reference = node.arguments[0]
+            if (reference && ts.isStringLiteral(reference)) enqueue(reference.text)
+          }
+          ts.forEachChild(node, visitImports)
+        }
+        visitImports(ast)
+      }
+      if (['AppDialog.vue', 'AppDrawer.vue', 'BatchImportDialog.vue'].some(name => file.endsWith(name))) continue
+      const visitTemplate = (nodes: TemplateNode[]) => {
+        for (const node of nodes) {
+          if (node.type !== 1) continue
+          if (['AppDialog', 'el-dialog', 'BatchImportDialog'].includes(node.tag)) expect(classesOf(node), `${file}: reachable modal`).toContain('admin-density-dialog')
+          if (['AppDrawer', 'el-drawer'].includes(node.tag)) expect(classesOf(node), `${file}: reachable drawer`).toContain('admin-density-drawer')
+          visitTemplate(node.children)
+        }
+      }
+      if (descriptor.template?.ast) visitTemplate(descriptor.template.ast.children)
+    }
+  })
+
+  it('keeps the supplier license dialog styled at its own teleported root', () => {
+    const source = read('modules/suppliers/components/SupplierLicenseDialog.vue')
+    expect(source).toContain('<AppDialog class="admin-density-dialog"')
+    expect(source).toContain('width="min(560px, calc(100vw - 24px))"')
+    expect(source).toContain('aria-label="营业执照信息"')
+  })
+
+  it('uses identical authored tab paint for native domestic and Element overseas tabs', () => {
+    const element = '.admin-density .density-element-tabs > .el-tabs__header .el-tabs__nav .el-tabs__item'
+    const rules: string[][] = []
+    cssRoot(shared).walkRules(rule => { rules.push(rule.selectors) })
+    for (const [nativeSuffix, elementSuffix] of [['', ''], ['::after', '::after'], [':hover', ':hover'], ['.active', '.is-active'], ['.active::after', '.is-active::after'], [':focus-visible', ':focus-visible']]) {
+      expect(rules.some(selectors => selectors.includes('.admin-density .density-tabs > button' + nativeSuffix) && selectors.includes(element + elementSuffix))).toBe(true)
+    }
+    const domestic = read('modules/unified-orders/pages/UnifiedOrdersView.vue')
+    const overseasShell = read('modules/overseas-warehouse/components/OverseasDetailShell.vue')
+    for (const className of ['density-detail-header', 'density-detail-heading', 'density-detail-title']) {
+      expect(domestic).toContain(className)
+      expect(overseasShell).toContain(className)
+    }
+    expect(domestic).toContain('density-detail-overview')
+    expect(read('modules/overseas-warehouse/pages/LastMileOrderDetailView.vue')).toContain('density-detail-overview')
+  })
+
+  it('covers all ten overseas warehouse menus, details and both return inventory modes', () => {
+    const navigation = read('core/navigation/adminNavigation.ts')
+    const section = navigation.slice(navigation.indexOf("key: 'overseas-inventory'"), navigation.indexOf("key: 'customer-service'"))
+    for (const path of ['last-mile-orders', 'inbound-orders', 'dispatches', 'outbounds', 'delivery-orders', 'relabel-orders', 'pallets', 'inventory', 'return-inventory', 'return-cartons']) expect(section).toContain("path: '/overseas-warehouse/" + path + "'")
+    expect([...section.matchAll(/path: '/g)]).toHaveLength(10)
+    const routes = read('modules/overseas-warehouse/routes.ts')
+    for (const mode of ['inventory', 'cartons']) expect(routes).toContain("mode: '" + mode + "'")
+    for (const file of overseasConsumers) {
+      const source = read('modules/' + file)
+      expect(source, file).toContain('@/styles/adminDensity.css')
+      expect(parse(source).errors, file).toEqual([])
+      if (file.endsWith('DetailView.vue') && !/OutboundDetail|DeliveryOrderDetail/.test(file)) {
+        const root = parse(source).descriptor.template!.ast!.children.find(node => node.type === 1) as ElementNode
+        expect(root.tag).toMatch(/^Overseas(?:DetailShell|ReadOnlyDetail)$/)
+        expect(root.props.some(prop => prop.type === 6 && prop.name === 'dense')).toBe(true)
+        expect(classesOf(root)).toContain('admin-density')
+      }
+    }
+  })
+
+  it('keeps contained overseas tab content and external cargo tab bodies separate', () => {
+    expect(shared).toContain('.density-element-tabs:not(.density-contained-tabs) > .el-tabs__content { display: none; }')
+    for (const file of ['LastMileOrderDetailView', 'DeliveryOrderDetailView']) {
+      const source = read('modules/overseas-warehouse/pages/' + file + '.vue')
+      const ast = parse(source).descriptor.template!.ast!
+      let panes = 0
+      const visit = (nodes: typeof ast.children) => { for (const node of nodes) {
+        if (node.type !== 1) continue
+        if (node.tag === 'el-tabs') expect(classesOf(node)).toContain('density-contained-tabs')
+        if (node.tag === 'el-tab-pane') {
+          panes++
+          expect(node.children.some(child => child.type === 1 && child.tag !== 'template'), file + ': pane retains body').toBe(true)
+          expect(node.loc.source).toContain('density-tab-icon')
+        }
+        visit(node.children)
+      } }
+      visit(ast.children)
+      expect(panes).toBe(file === 'LastMileOrderDetailView' ? 5 : 4)
+    }
+  })
+
+  it('opts shared overseas detail and relationship wrappers in only at approved callers', () => {
+    for (const file of ['modules/overseas-warehouse/components/OverseasDetailShell.vue', 'modules/overseas-warehouse/components/OverseasReadOnlyDetail.vue', 'shared/components/InboundCodeRelationshipDialog.vue']) {
+      const source = read(file)
+      expect(source).toContain('dense?: boolean')
+      const ast = parse(source).descriptor.template!.ast!
+      const root = ast.children.find(node => node.type === 1) as ElementNode
+      expect(classesOf(root, false, true).some(name => name.startsWith('admin-density')), file).toBe(true)
+      expect(classesOf(root, false, false).some(name => name.startsWith('admin-density')), file).toBe(false)
+    }
+    expect(read('modules/overseas-warehouse/components/OverseasReadOnlyDetail.vue')).toContain(':dense="dense"')
+    expect(read('modules/overseas-warehouse/pages/InventoryTransactionsView.vue')).toContain('<InboundCodeRelationshipDialog dense')
+    for (const file of ['CartonDetailView', 'ProductDetailView']) expect(read('modules/overseas-warehouse/pages/' + file + '.vue')).not.toContain(' dense')
+  })
+
+  it('covers four cargo menus, independent detail routes and both workbench modes', () => {
+    const navigation = read('core/navigation/adminNavigation.ts')
+    for (const path of ['/ocean-bookings', '/trucking', '/container-loading/domestic', '/container-loading/overseas']) expect(navigation).toContain(`path: '${path}'`)
+    for (const [prefix, workbench] of [['Domestic', 'DOMESTIC'], ['Overseas', 'OVERSEAS']]) {
+      for (const [suffix, component] of [['ContainersView', 'ContainersView'], ['ContainerDetailView', 'ContainerDetailView']]) {
+        expect(read(`modules/container-loading/pages/${prefix}${suffix}.vue`)).toContain(`<${component} workbench="${workbench}"`)
+        const ast = parse(read(`modules/container-loading/pages/${component}.vue`)).descriptor.template!.ast!
+        const root = ast.children.find(node => node.type === 1) as ElementNode
+        expect(classesOf(root, false, true, workbench)).toContain('admin-density')
+      }
+    }
+    const detail = read('modules/container-loading/pages/ContainerDetailView.vue')
+    for (const component of ['CarrierScheduleQueryPanel', 'LoadingListDetailDrawer', 'PalletLabelPrintDialog']) expect(detail).toContain(`<${component} dense`)
+    expect(read('modules/container-loading/pages/ContainersView.vue')).toContain('<ContainerSimulationCreate dense')
+    for (const file of cargoConsumers) expect(read(`modules/${file}`), `${file}: direct entry`).toContain('@/styles/adminDensity.css')
+  })
+
+  it('enables confirmed loading content and schedule overlays only for opted-in callers', () => {
+    for (const file of ['loading-lists/components/LoadingListDetailDrawer.vue', 'port-schedules/components/CarrierScheduleQueryPanel.vue']) {
+      const ast = parse(read(`modules/${file}`)).descriptor.template!.ast!
+      const root = ast.children.find(node => node.type === 1) as ElementNode
+      expect(classesOf(root, false, true)).toContain('admin-density')
+      expect(classesOf(root, false, false)).not.toContain('admin-density')
+      if (file.includes('CarrierSchedule')) {
+        const dialog = root.children.find(node => node.type === 1 && node.tag === 'AppDialog') as ElementNode
+        expect(classesOf(dialog, false, true)).toContain('admin-density-dialog')
+        expect(classesOf(dialog, false, false)).not.toContain('admin-density-dialog')
+      }
+    }
+  })
+
+  it('keeps cargo native tables, row actions and detail tabs connected to shared styles', () => {
+    for (const file of cargoConsumers) {
+      const ast = parse(read(`modules/${file}`)).descriptor.template!.ast!
+      const visit = (nodes: typeof ast.children, inCell = false, insideDensity = false) => {
+        for (const node of nodes) {
+          if (node.type !== 1) continue
+          const classes = classesOf(node)
+          const enabled = insideDensity || classes.some(name => ['admin-density', 'admin-density-dialog'].includes(name))
+          if (node.tag === 'table') {
+            expect(classes, `${file}: native table`).toContain('density-table')
+            expect(insideDensity, `${file}: native table ancestor`).toBe(true)
+          }
+          if (node.tag === 'el-tabs') expect(classes).toContain('density-element-tabs')
+          if (inCell && node.tag === 'el-button') {
+            expect(classes, `${file}: native row action`).toContain('density-action')
+            expect(node.children.some(child => child.type === 2 && child.content.trim() || child.type === 5), `${file}: empty action`).toBe(true)
+          }
+          visit(node.children, inCell || node.tag === 'td', enabled)
+        }
+      }
+      visit(ast.children)
+    }
+  })
+  it('keeps shared list actions and detail content inside a density-enabled page ancestor', () => {
+    for (const file of densityPages) {
+      const template = parse(read(`modules/${file}`)).descriptor.template!.ast!
+      let checked = 0
+      const visit = (nodes: typeof template.children, insideDensity = false) => {
+        for (const node of nodes) {
+          if (node.type !== 1) continue
+          const classes = classesOf(node)
+          if (node.tag === 'DataTable' || node.tag === 'LoadingListDetailDrawer' || classes.some(name => ['density-action', 'density-actions', 'density-tabs', 'density-fields', 'density-tab-icon', 'density-back'].includes(name))) {
+            expect(insideDensity, `${file}: ${classes.join(' ')} lacks its density ancestor`).toBe(true)
+            checked += 1
+          }
+          visit(node.children, insideDensity || classes.some(name => ['admin-density', 'admin-density-dialog'].includes(name)))
+        }
+      }
+      visit(template.children)
+      expect(checked, `${file}: no shared styles checked`).toBeGreaterThan(0)
+    }
+  })
+
+  it('covers all seven domestic menu entries and loads density CSS on direct entry', () => {
+    const navigation = read('core/navigation/adminNavigation.ts')
+    const domestic = navigation.slice(navigation.indexOf("key: 'domestic-warehouse'"), navigation.indexOf("key: 'overseas-delivery'"))
+    expect([...domestic.matchAll(/path: '/g)]).toHaveLength(domesticPages.length)
+    for (const page of domesticPages) {
+      expect(domestic).toContain(`title: '${page.title}'`)
+      expect(domestic).toContain(`path: '${page.path}'`)
+      if (page.entry) expect(read(`modules/${page.entry}`)).toContain(`<${page.component} mode="${page.mode}"`)
+    }
+    for (const file of densityPages) expect(read(`modules/${file}`), `${file}: direct entry CSS`).toContain('@/styles/adminDensity.css')
+  })
+
+  it('covers both customer menu entries and their shared detail primitives', () => {
+    const navigation = read('core/navigation/adminNavigation.ts')
+    const customers = navigation.slice(navigation.indexOf("key: 'customers'"), navigation.indexOf("key: 'domestic-warehouse'"))
+    expect([...customers.matchAll(/path: '/g)]).toHaveLength(customerPages.length)
+    for (const page of customerPages) {
+      expect(customers).toContain(`title: '${page.title}'`)
+      expect(customers).toContain(`path: '${page.path}'`)
+    }
+    expect(read('modules/customers/pages/CustomerDetailView.vue')).toContain('class="back-button density-back"')
+  })
+
+  it('uses shared outlined actions across domestic tables and explicit classes on teleported dialogs', () => {
+    for (const file of [...new Set([...densityPages, ...consumers])]) {
+      const template = parse(read(`modules/${file}`)).descriptor.template!.ast!
+      const visit = (nodes: typeof template.children, actionSlot = false, parentTag = '') => {
+        for (const node of nodes) {
+          if (node.type !== 1) continue
+          const isActionSlot = actionSlot || (parentTag === 'DataTable' && node.props.some(prop => prop.type === 7 && prop.name === 'slot' && prop.arg?.type === 4 && prop.arg.content === 'actions'))
+          if (densityPages.includes(file) && isActionSlot && node.tag === 'el-button') expect(classesOf(node), `${file}: row action`).toContain('density-action')
+          if (['AppDialog', 'el-dialog'].includes(node.tag)) expect(classesOf(node), `${file}: teleported dialog`).toContain('admin-density-dialog')
+          if (['AppDrawer', 'el-drawer'].includes(node.tag)) expect(classesOf(node), `${file}: teleported drawer`).toContain('admin-density-drawer')
+          visit(node.children, isActionSlot, node.tag)
+        }
+      }
+      visit(template.children)
+    }
+  })
+
+  it('keeps tokens and shared rules opt-in and free of business selectors', () => {
+    expect(shared).toContain("@import './adminDensityTokens.css'")
+    for (const css of [tokens, shared]) cssRoot(css).walkRules(rule => {
+      expect(rule.selector, `unscoped rule: ${rule.selector}`).toContain('.admin-density')
+      expect(rule.selector).not.toMatch(/customer-|order-|inbound-|preload-/)
+    })
+  })
+
+  it('defines every referenced density variable once, with local field width as the documented exception', () => {
+    const definitions = [...tokens.matchAll(/(--admin-[\w-]+)\s*:/g)].map(match => match[1])
+    expect(new Set(definitions).size).toBe(definitions.length)
+    const declared = new Set([...definitions, '--admin-field-label-width'])
+    for (const { file, css } of [...styles, { file: 'adminDensity.css', css: shared }]) {
+      for (const match of css.matchAll(/var\((--admin-[\w-]+)/g)) expect(declared.has(match[1]!), `${file}: ${match[1]}`).toBe(true)
+      for (const match of css.matchAll(/(--admin-[\w-]+)\s*:/g)) expect(match[1], `${file}: token redefinition`).toBe('--admin-field-label-width')
+    }
+  })
+
+  it('connects configurable surface colors and semantic hover states to their consumers', () => {
+    const root = cssRoot(shared)
+    const rules = new Map<string, Record<string, string>>()
+    root.walkRules(rule => {
+      const declarations: Record<string, string> = {}
+      rule.walkDecls(decl => { declarations[decl.prop] = decl.value })
+      rules.set(rule.selector, declarations)
+    })
+    expect(rules.get('.admin-density .el-table__body tr.el-table__row--striped td.el-table__cell')?.background).toBe('var(--admin-row-stripe)')
+    expect(rules.get('.admin-density-dialog .el-descriptions__label.el-descriptions__cell')?.background).toBe('var(--admin-label-bg)')
+    for (const tone of ['warning', 'purple', 'primary', 'success', 'danger']) {
+      expect(rules.get(`:is(.admin-density, .admin-density-dialog) .density-action[data-tone="${tone}"]`)?.['--action-hover-bg']).toBe(`var(--admin-action-${tone}-hover)`)
+    }
+    expect(rules.get(':is(.admin-density, .admin-density-dialog) .el-button.density-action:hover:not(:disabled)')?.background).toBe('var(--action-hover-bg)')
+  })
+
+  it('prevents page copies of action paint, tab primitives and desktop density dimensions', () => {
+    for (const { file, css } of styles) cssRoot(css).walkRules(rule => {
+      expect(rule.selector.trim(), file + ': empty selector').not.toBe('')
+      expect(rule.selector, file).not.toMatch(/customer-action-button|order-action-button|\.density-action|\.density-tab-icon/)
+      let desktop = true
+      for (let parent: typeof rule.parent | ReturnType<typeof cssRoot>['parent'] = rule.parent; parent; parent = parent.parent) {
+        if (parent.type === 'atrule' && /max-width|print/.test('params' in parent ? String(parent.params) : '')) desktop = false
+      }
+      rule.walkDecls(decl => {
+        expect(decl.prop, file).not.toMatch(/^--el-button-/)
+        if (desktop && decl.prop === 'font-size') expect(decl.value, `${file}: ${rule.selector}`).not.toMatch(/^(10|11|12|13|14|16)px$/)
+        if (desktop && /^(height|min-height)$/.test(decl.prop)) expect(decl.value, `${file}: ${rule.selector}`).not.toMatch(/^(28|32|36|38|64)px$/)
+      })
+    })
+  })
+
+  it('keeps desktop table toolbar dimensions owned by DataTable without cascade overrides', () => {
+    const tableCss = parse(read('shared/components/DataTable.vue')).descriptor.styles.map(style => style.content).join('\n')
+    const dimensions: Record<string, string[]> = { padding: [], 'min-height': [] }
+    cssRoot(tableCss).walkRules(rule => {
+      if (!rule.selectors.includes('.data-table__toolbar') && !rule.selectors.includes('.data-table__toolbar.is-compact')) return
+      // Preserve the existing mobile layout; the shared desktop dimensions have one owner.
+      if (rule.parent?.type === 'atrule' && /max-width/.test(rule.parent.params)) return
+      rule.walkDecls(decl => { if (dimensions[decl.prop]) dimensions[decl.prop].push(decl.value) })
+    })
+    expect(dimensions).toEqual({ padding: ['var(--admin-space-2, 6px) var(--admin-space-5, 12px)'], 'min-height': ['44px'] })
+    for (const { file, css } of [{ file: 'adminDensity.css', css: shared }, ...styles]) cssRoot(css).walkRules(rule => {
+      if (!/\.data-table__toolbar(?:\b|\.)/.test(rule.selector)) return
+      rule.walkDecls(decl => {
+        expect(decl.prop, `${file}: toolbar dimensions belong in DataTable`).not.toMatch(/^(padding(?:-.+)?|height|min-height)$/)
+      })
+    })
+  })
+
+  it('keeps conditional shared consumers opt-in instead of enabling other menus', () => {
+    expect(read('shared/components/DataTable.vue')).toContain('margin-left: var(--cc-list-action-sibling-margin, 8px)')
+    expect(shared).toContain('.density-actions { --cc-list-action-sibling-margin: 0px;')
+    expect(read('modules/loading-lists/components/LoadingListsView.vue')).toContain("'admin-density': isPreload")
+    expect(read('modules/loading-lists/components/PalletLabelPrintDialog.vue')).toContain("'admin-density-dialog': dense")
+    expect(read('modules/container-loading/components/ContainerSimulationCreate.vue')).toContain("'admin-density-dialog': dense")
+    for (const file of ['loading-lists/components/LoadingListsView.vue', 'loading-lists/components/LoadingListDetailDrawer.vue', 'loading-lists/components/PalletLabelPrintDialog.vue', 'container-loading/components/ContainerSimulationCreate.vue']) {
+      const template = parse(read(`modules/${file}`)).descriptor.template!.ast!
+      const visit = (nodes: typeof template.children) => {
+        for (const node of nodes) {
+          if (node.type !== 1) continue
+          expect(classesOf(node, false).filter(name => /^(admin-density|density-)/.test(name)), `${file}: unopted consumer`).toEqual([])
+          visit(node.children)
+        }
+      }
+      visit(template.children)
+    }
+    for (const file of ['customers/pages/CustomersView.vue', 'customers/pages/OverseasStorageFeesView.vue', 'unified-orders/pages/UnifiedOrdersView.vue']) {
+      expect(read(`modules/${file}`), file).toContain('density-action')
+    }
+  })
+})
diff --git a/src/styles/adminDensityTokens.css b/src/styles/adminDensityTokens.css
new file mode 100644
index 00000000..94efcaef
--- /dev/null
+++ b/src/styles/adminDensityTokens.css
@@ -0,0 +1,47 @@
+/* Single source for the approved domestic-warehouse/customer density scale.
+ * Opt-in only: loading this stylesheet never changes unrelated pages. */
+:where(.admin-density, .admin-density-dialog, .admin-density-drawer, .admin-density-confirm) {
+  --admin-font-body: 13px;
+  --admin-font-caption: 12px;
+  --admin-font-section: 14px;
+  --admin-font-title: 16px;
+  --admin-control-height: 32px;
+  --admin-row-height: 36px;
+  --admin-action-height: 28px;
+  --admin-tab-height: 38px;
+  --admin-tab-icon-size: 17px;
+  --admin-tab-icon-slot: 18px;
+  --admin-radius: 4px;
+  --admin-action-radius: 6px;
+  --admin-space-1: 4px;
+  --admin-space-2: 6px;
+  --admin-space-3: 8px;
+  --admin-space-4: 10px;
+  --admin-space-5: 12px;
+  --admin-space-6: 16px;
+  --admin-space-7: 24px;
+  --admin-label-width: 112px;
+  --admin-empty-height: 64px;
+  --admin-surface: #fff;
+  --admin-label-bg: #f8fafc;
+  --admin-table-border: #e5e7eb;
+  --admin-row-hover: #f3f7fb;
+  --admin-row-stripe: #fcfcfd;
+  --admin-action-neutral: #1777ff;
+  --admin-action-neutral-border: #dfe3ee;
+  --admin-action-warning: #c76500;
+  --admin-action-warning-border: #fed7aa;
+  --admin-action-warning-hover: #fff7ed;
+  --admin-action-purple: #7c3aed;
+  --admin-action-purple-border: #ddd6fe;
+  --admin-action-purple-hover: #f5f3ff;
+  --admin-action-primary: #1677cf;
+  --admin-action-primary-border: #bfdbfe;
+  --admin-action-primary-hover: #eff6ff;
+  --admin-action-success: #15803d;
+  --admin-action-success-border: #bbf7d0;
+  --admin-action-success-hover: #f0fdf4;
+  --admin-action-danger: #dc2626;
+  --admin-action-danger-border: #fecaca;
+  --admin-action-danger-hover: #fef2f2;
+}
diff --git a/src/styles/adminListTypography.test.ts b/src/styles/adminListTypography.test.ts
new file mode 100644
index 00000000..73830d32
--- /dev/null
+++ b/src/styles/adminListTypography.test.ts
@@ -0,0 +1,55 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+function source(path: string) {
+  return readFileSync(resolve(process.cwd(), path), 'utf8')
+}
+
+describe('Admin list typography baseline', () => {
+  it('freezes the UnifiedOrdersView desktop hierarchy as shared tokens', () => {
+    const foundation = source('src/styles/foundation.css')
+    for (const token of [
+      '--cc-list-page-title-font-size: 20px',
+      '--cc-list-page-description-font-size: 12px',
+      '--cc-list-query-font-size: 14px',
+      '--cc-list-table-font-size: 12px',
+      '--cc-list-primary-font-size: 12px',
+      '--cc-list-secondary-font-size: 12px',
+      '--cc-list-status-font-size: 11px',
+      '--cc-list-action-font-size: 12px',
+      '--cc-list-pagination-font-size: 12px',
+      '--cc-list-page-button-font-size: 14px',
+    ]) expect(foundation).toContain(token)
+  })
+
+  it('applies the tokens through shared page, query, table, status, action, empty, and pagination styles', () => {
+    const shell = source('src/styles/shell.css')
+    const global = source('src/styles/index.css')
+    const table = source('src/shared/components/DataTable.vue')
+    const query = source('src/shared/components/QueryToolbar.vue')
+    expect(shell).toContain('font-size: var(--cc-list-page-title-font-size)')
+    expect(shell).toContain('font-size: var(--cc-list-page-description-font-size)')
+    expect(query).toContain('font-size: var(--cc-list-query-font-size)')
+    expect(table).toContain('.data-table :deep(.el-table) { font-size: var(--cc-list-table-font-size); }')
+    expect(table).toContain('.data-table :deep(.el-table .el-button) { font-size: var(--cc-list-action-font-size); }')
+    expect(table).toContain('.data-table :deep(.el-table__empty-text) { font-size: var(--cc-list-table-font-size); }')
+    expect(table).toContain('font-size: var(--cc-list-pagination-font-size)')
+    expect(global).toContain('font-size: var(--cc-list-primary-font-size)')
+    expect(global).toContain('font-size: var(--cc-list-secondary-font-size)')
+    expect(global).toContain('font-size: var(--cc-list-status-font-size)')
+  })
+
+  it.each([
+    'src/modules/ocean-bookings/pages/OceanBookingsView.vue',
+    'src/modules/trucking/pages/TruckAppointmentsView.vue',
+    'src/modules/customs/pages/CustomsCasesView.vue',
+    'src/modules/outbound-dispatch/pages/OutboundDispatchesView.vue',
+    'src/modules/port-schedules/pages/PortSchedulesView.vue',
+  ])('keeps representative formal list %s on the shared components', (path) => {
+    const page = source(path)
+    expect(page).toContain('<ListPageLayout')
+    expect(page).toContain('<QueryToolbar')
+    expect(page).toContain('<DataTable')
+  })
+})
diff --git a/src/styles/foundation.css b/src/styles/foundation.css
new file mode 100644
index 00000000..eb3e0177
--- /dev/null
+++ b/src/styles/foundation.css
@@ -0,0 +1,92 @@
+:root {
+  font-family: "PingFang SC", "Microsoft YaHei", "Segoe UI", sans-serif;
+  color: #1d2939;
+  background: #f5f7fa;
+  font-synthesis: none;
+  /* Core palette: restrained blue for actions, neutral surfaces for scanning. */
+  --cc-primary: #667eea;
+  --cc-primary-hover: #764ba2;
+  --cc-primary-soft: #f0efff;
+  --cc-navy: #667eea;
+  --cc-topbar: rgba(102, 126, 234, .95);
+  --cc-menu-active: #667eea;
+  --cc-page: #f5f7fa;
+  --cc-surface: #ffffff;
+  --cc-surface-muted: #f8fafc;
+  --cc-border: #e4e7ec;
+  --cc-border-strong: #d0d5dd;
+  --cc-text: #1d2939;
+  --cc-text-secondary: #475467;
+  --cc-muted: #667085;
+  --cc-placeholder: #98a2b3;
+  --cc-success: #067647;
+  --cc-success-soft: #ecfdf3;
+  --cc-warning: #b54708;
+  --cc-warning-soft: #fffaeb;
+  --cc-danger: #b42318;
+  --cc-danger-soft: #fef3f2;
+  --cc-info: #175cd3;
+  --cc-info-soft: #eff8ff;
+  --cc-focus: rgba(102, 126, 234, .28);
+  --cc-radius-sm: 4px;
+  --cc-radius-md: 6px;
+  --cc-radius-lg: 8px;
+  --cc-radius-pill: 999px;
+  --cc-shadow-sm: 0 1px 2px rgba(16, 24, 40, .05);
+  --cc-shadow-md: 0 3px 12px rgba(15, 23, 42, .05);
+  --cc-shadow-shell: 0 1px 4px rgba(16, 24, 40, .08);
+  --cc-space-1: 4px;
+  --cc-space-2: 8px;
+  --cc-space-3: 12px;
+  --cc-space-4: 16px;
+  --cc-space-5: 20px;
+  --cc-space-6: 24px;
+  --cc-space-7: 32px;
+  /* Admin list typography: frozen from UnifiedOrdersView at 1920×1080 / 100%. */
+  --cc-list-page-title-font-size: 20px;
+  --cc-list-page-description-font-size: 12px;
+  --cc-list-query-font-size: 14px;
+  --cc-list-table-font-size: 12px;
+  --cc-list-table-header-font-weight: 600;
+  --cc-list-primary-font-size: 12px;
+  --cc-list-secondary-font-size: 12px;
+  --cc-list-status-font-size: 11px;
+  --cc-list-action-font-size: 12px;
+  --cc-list-pagination-font-size: 12px;
+  --cc-list-page-button-font-size: 14px;
+
+  --el-color-primary: var(--cc-primary);
+  --el-color-primary-light-3: #84adff;
+  --el-color-primary-light-5: #b2ccff;
+  --el-color-primary-light-7: #d5e3ff;
+  --el-color-primary-light-8: #e1ebff;
+  --el-color-primary-light-9: var(--cc-primary-soft);
+  --el-color-primary-dark-2: var(--cc-primary-hover);
+  --el-color-success: var(--cc-success);
+  --el-color-warning: var(--cc-warning);
+  --el-color-danger: var(--cc-danger);
+  --el-color-info: var(--cc-info);
+  --el-border-color: var(--cc-border);
+  --el-border-color-light: #eaecf0;
+  --el-border-color-lighter: #f2f4f7;
+  --el-fill-color-light: var(--cc-surface-muted);
+  --el-fill-color-lighter: #fbfcfd;
+  --el-bg-color: var(--cc-surface);
+  --el-bg-color-page: var(--cc-page);
+  --el-text-color-primary: var(--cc-text);
+  --el-text-color-regular: var(--cc-text-secondary);
+  --el-text-color-secondary: var(--cc-muted);
+  --el-text-color-placeholder: var(--cc-placeholder);
+  --el-border-radius-base: var(--cc-radius-md);
+  --el-border-radius-small: var(--cc-radius-sm);
+  --el-border-radius-round: var(--cc-radius-pill);
+  --el-box-shadow-light: var(--cc-shadow-md);
+}
+
+* { box-sizing: border-box; }
+html, body, #app { width: 100%; min-width: 0; min-height: 100%; margin: 0; }
+body { min-height: 100vh; background: var(--cc-page); }
+button, input, textarea, select { font: inherit; }
+button { letter-spacing: 0; }
+:focus-visible { outline: 3px solid var(--cc-focus); outline-offset: 2px; }
+.sr-only { position: absolute; width: 1px; height: 1px; padding: 0; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }
diff --git a/src/styles/index.css b/src/styles/index.css
index 8f3f225a..114cccb3 100644
--- a/src/styles/index.css
+++ b/src/styles/index.css
@@ -1,76 +1,5 @@
-:root {
-  font-family: "PingFang SC", "Microsoft YaHei", "Segoe UI", sans-serif;
-  color: #172033;
-  background: #f4f6f8;
-  font-synthesis: none;
-  --cc-primary: #155eef;
-  --cc-navy: #172a46;
-  --cc-border: #e3e8ef;
-  --cc-muted: #667085;
-}
-
-* { box-sizing: border-box; }
-html, body, #app { width: 100%; min-width: 0; min-height: 100%; margin: 0; }
-body { min-height: 100vh; background: #f4f6f8; }
-button, input, textarea, select { font: inherit; }
-button { letter-spacing: 0; }
-:focus-visible { outline: 3px solid rgba(21, 94, 239, .28); outline-offset: 2px; }
-.sr-only { position: absolute; width: 1px; height: 1px; padding: 0; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }
-
-.app-shell { min-width: 0; min-height: 100vh; }
-.app-sidebar { position: fixed; inset: 0 auto 0 0; z-index: 20; display: flex; width: 240px; flex-direction: column; background: var(--cc-navy); color: #fff; }
-.is-collapsed .app-sidebar { width: 76px; }
-.brand-block { display: flex; height: 72px; align-items: center; gap: 12px; padding: 0 18px; border-bottom: 1px solid rgba(255,255,255,.1); }
-.brand-mark { display: grid; width: 40px; height: 40px; flex: 0 0 auto; place-items: center; border-radius: 8px; background: #fff; color: var(--cc-navy); font-weight: 800; letter-spacing: 0; }
-.brand-copy { display: flex; min-width: 0; flex-direction: column; gap: 2px; }
-.brand-copy strong { font-size: 16px; }
-.brand-copy span { color: #aebbd0; font-size: 12px; }
-.side-nav { flex: 1; min-height: 0; overflow-y: auto; padding: 14px 10px; }
-.side-nav-menu {
-  width: 100%;
-  border-right: 0 !important;
-  background: transparent !important;
-  --el-menu-bg-color: transparent;
-  --el-menu-text-color: #bdc7d7;
-  --el-menu-active-color: var(--cc-navy);
-  --el-menu-hover-bg-color: rgba(255,255,255,.08);
-}
-.side-nav-menu.el-menu--collapse { width: 56px; }
-.side-nav-menu .el-menu-item,
-.side-nav-menu .el-sub-menu__title { height: 44px; margin: 3px 0; border-radius: 8px; line-height: 44px; }
-.side-nav-menu .el-menu-item:hover,
-.side-nav-menu .el-sub-menu__title:hover { color: #fff; }
-.side-nav-menu .el-menu-item.is-active { background: #fff; color: var(--cc-navy); font-weight: 650; }
-.side-nav-menu .el-sub-menu .el-menu-item { min-width: 0; padding-left: 48px !important; }
-.side-nav-menu .el-menu-item svg,
-.side-nav-menu .el-sub-menu__title svg { flex: 0 0 auto; margin-right: 12px; }
-.sidebar-toggle { display: flex; height: 52px; align-items: center; justify-content: center; gap: 8px; border: 0; border-top: 1px solid rgba(255,255,255,.1); background: transparent; color: #aebbd0; cursor: pointer; }
-.app-main { min-width: 0; min-height: 100vh; margin-left: 240px; }
-.is-collapsed .app-main { margin-left: 76px; }
-.app-header { position: sticky; top: 0; z-index: 15; display: flex; min-width: 0; min-height: 72px; align-items: center; gap: 16px; padding: 10px 28px; border-bottom: 1px solid var(--cc-border); background: rgba(255,255,255,.96); }
-.page-heading { min-width: 0; flex: 1; }
-.page-heading h1 { margin: 0; overflow: hidden; font-size: 20px; letter-spacing: 0; text-overflow: ellipsis; white-space: nowrap; }
-.page-heading p { margin: 4px 0 0; overflow: hidden; color: var(--cc-muted); font-size: 12px; text-overflow: ellipsis; white-space: nowrap; }
-.header-user { display: flex; min-width: 0; flex: 0 0 auto; align-items: center; gap: 10px; }
-.user-avatar { display: grid; width: 36px; height: 36px; place-items: center; border-radius: 50%; background: #eaf1ff; color: var(--cc-primary); font-weight: 700; }
-.user-copy { display: flex; flex-direction: column; }
-.user-copy strong { font-size: 13px; }
-.user-copy span { color: var(--cc-muted); font-size: 11px; }
-.mobile-menu-button { display: none; width: 44px; height: 44px; padding: 0; border: 0; background: none; cursor: pointer; }
-.header-user .el-button { width: 44px; height: 44px; }
-.page-container { padding: 24px 28px 40px; }
-
-/* Static permission preview */
-.app-header > .el-dropdown { min-width: 0; max-width: 320px; flex: 0 1 320px; }
-.role-preview-trigger { display: flex; width: 100%; min-width: 0; min-height: 44px; align-items: center; gap: 10px; padding: 6px 10px; border: 1px solid var(--cc-border); border-radius: 8px; background: #fff; color: #172033; text-align: left; cursor: pointer; }
-.role-preview-trigger:hover { border-color: #b8c6d9; background: #f8fafc; }
-.role-preview-trigger:focus-visible { border-color: var(--cc-primary); outline: 3px solid rgba(21, 94, 239, .2); outline-offset: 1px; }
-.role-preview-trigger:disabled, .role-preview-trigger[aria-disabled="true"] { cursor: not-allowed; opacity: .58; }
-.role-preview-trigger > svg { flex: 0 0 auto; }
-.role-preview-copy { display: flex; min-width: 0; flex: 1; flex-direction: column; gap: 2px; }
-.role-preview-copy strong, .role-preview-copy small { display: block; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
-.role-preview-copy strong { font-size: 12px; font-weight: 700; }
-.role-preview-copy small { color: var(--cc-muted); font-size: 10px; line-height: 1.35; }
+@import './foundation.css';
+@import './shell.css';
 
 .forbidden-page { display: flex; min-height: min(560px, calc(100vh - 136px)); align-items: center; justify-content: center; flex-direction: column; padding: clamp(28px, 7vw, 64px) clamp(18px, 6vw, 48px); border: 1px solid var(--cc-border); border-radius: 8px; background: #fff; text-align: center; }
 .forbidden-icon { display: grid; width: 56px; height: 56px; place-items: center; margin-bottom: 18px; border-radius: 8px; background: #fef3f2; color: #b42318; }
@@ -82,8 +11,8 @@ button { letter-spacing: 0; }
 
 .login-page { display: grid; min-height: 100vh; grid-template-columns: minmax(420px, 1.05fr) minmax(420px, .95fr); background: #fff; }
 .login-intro { display: flex; flex-direction: column; justify-content: space-between; padding: 46px clamp(42px, 7vw, 100px); background: var(--cc-navy); color: #fff; }
-.login-brand { display: flex; align-items: center; gap: 12px; font-weight: 700; }
-.login-brand span { display: grid; width: 42px; height: 42px; place-items: center; border-radius: 10px; background: #fff; color: var(--cc-navy); }
+.login-brand { display: flex; align-items: center; min-height: 64px; }
+.login-brand-logo { display: block; width: 205px; height: 64px; object-fit: contain; object-position: left center; }
 .eyebrow, .section-kicker { color: #3975e9; font-size: 11px; font-weight: 750; letter-spacing: 0; }
 .login-intro h1 { max-width: 680px; margin: 16px 0 22px; font-size: 52px; line-height: 1.16; letter-spacing: 0; }
 .intro-copy { max-width: 560px; color: #b9c6d8; font-size: 16px; line-height: 1.8; }
@@ -98,7 +27,6 @@ button { letter-spacing: 0; }
 .login-error { margin: 14px 0 0; color: #b42318; font-size: 13px; line-height: 1.5; }
 .login-error > p { margin: 0; }
 .api-error-alert-title { min-width: 0; }
-.demo-tip { margin-top: 18px; padding: 10px 12px; border: 1px solid #dce6f8; background: #f7faff; color: #64748b; font-size: 12px; }
 
 .dashboard-stack { display: flex; flex-direction: column; gap: 20px; }
 .welcome-panel, .content-card, .module-card { border: 1px solid var(--cc-border); background: #fff; }
@@ -158,18 +86,20 @@ button { letter-spacing: 0; }
 .panel-heading h2 { margin: 0; font-size: 16px; }
 .panel-heading p { margin: 5px 0 0; color: var(--cc-muted); font-size: 12px; line-height: 1.5; }
 .table-panel .el-table { --el-table-border-color: #edf0f4; --el-table-header-bg-color: #f8fafc; --el-table-row-hover-bg-color: #f8fbff; }
-.table-panel .el-table th.el-table__cell { height: 44px; color: #475467; font-size: 12px; font-weight: 650; }
+.table-panel .el-table { font-size: var(--cc-list-table-font-size); }
+.table-panel .el-table th.el-table__cell { height: 44px; color: #475467; font-size: var(--cc-list-table-font-size); font-weight: var(--cc-list-table-header-font-weight); }
 .table-panel .el-table td.el-table__cell { padding: 12px 0; }
 .primary-cell, .user-cell { display: flex; min-width: 0; flex-direction: column; gap: 4px; }
-.primary-cell strong, .user-cell strong { overflow: hidden; color: #172033; font-size: 13px; text-overflow: ellipsis; white-space: nowrap; }
-.primary-cell span, .user-cell span { overflow: hidden; color: var(--cc-muted); font-size: 11px; text-overflow: ellipsis; white-space: nowrap; }
+.primary-cell strong, .user-cell strong { overflow: hidden; color: #172033; font-size: var(--cc-list-primary-font-size); text-overflow: ellipsis; white-space: nowrap; }
+.primary-cell span, .user-cell span { overflow: hidden; color: var(--cc-muted); font-size: var(--cc-list-secondary-font-size); text-overflow: ellipsis; white-space: nowrap; }
 .user-cell { flex-direction: row; align-items: center; gap: 10px; }
 .user-cell > span:first-child, .detail-identity > span { display: grid; width: 34px; height: 34px; flex: 0 0 auto; place-items: center; border-radius: 50%; background: #eaf1ff; color: var(--cc-primary); font-weight: 700; }
 .user-cell > div { display: flex; min-width: 0; flex-direction: column; gap: 3px; }
 .table-actions { display: flex; align-items: center; white-space: nowrap; }
+.table-actions .el-button { font-size: var(--cc-list-action-font-size); }
 .table-actions .el-button + .el-button { margin-left: 10px; }
-.table-footer { display: flex; min-height: 58px; align-items: center; justify-content: space-between; gap: 16px; padding: 10px 16px; border-top: 1px solid var(--cc-border); color: var(--cc-muted); font-size: 12px; }
-.status-badge { display: inline-flex; min-height: 24px; align-items: center; gap: 6px; padding: 2px 8px; border-radius: 999px; background: #f2f4f7; color: #475467; font-size: 11px; font-weight: 650; white-space: nowrap; }
+.table-footer { display: flex; min-height: 58px; align-items: center; justify-content: space-between; gap: 16px; padding: 10px 16px; border-top: 1px solid var(--cc-border); color: var(--cc-muted); font-size: var(--cc-list-pagination-font-size); }
+.status-badge { display: inline-flex; min-height: 24px; align-items: center; gap: 6px; padding: 2px 8px; border-radius: 999px; background: #f2f4f7; color: #475467; font-size: var(--cc-list-status-font-size); font-weight: 650; white-space: nowrap; }
 .status-badge i { width: 6px; height: 6px; border-radius: 50%; background: currentColor; }
 .status-badge.is-success { background: #ecfdf3; color: #067647; }
 .status-badge.is-warning { background: #fffaeb; color: #b54708; }
@@ -283,12 +213,13 @@ button { letter-spacing: 0; }
   .app-sidebar { display: flex; width: min(280px, 86vw); transform: translateX(-100%); transition: transform .2s ease; }
   .is-mobile-open .app-sidebar { transform: translateX(0); }
   .is-collapsed .app-sidebar { width: min(280px, 86vw); }
-  .is-collapsed .brand-copy, .is-collapsed .sidebar-toggle span { display: flex; }
+  .is-collapsed .brand-logo-full { display: block; }
+  .is-collapsed .brand-logo-mark { display: none; }
+  .is-collapsed .sidebar-toggle span { display: flex; }
   .side-nav-menu, .side-nav-menu.el-menu--collapse { width: 100%; }
   .sidebar-toggle { display: none; }
   .sidebar-scrim { position: fixed; inset: 0 0 0 min(280px, 86vw); z-index: 19; display: block; border: 0; background: rgba(15, 23, 42, .46); }
   .app-main, .is-collapsed .app-main { margin-left: 0; }
-  .mobile-menu-button { display: inline-grid; place-items: center; }
   .app-header > .el-dropdown { width: 44px; max-width: 44px; flex: 0 0 44px; }
   .role-preview-trigger { width: 44px; height: 44px; justify-content: center; padding: 0; }
   .role-preview-copy, .role-preview-trigger > svg:last-child { display: none; }
@@ -341,11 +272,31 @@ button { letter-spacing: 0; }
 @media (max-width: 360px) {
   .app-header { gap: 6px; padding: 8px; }
   .page-heading h1 { max-width: 100%; font-size: 17px; }
-  .mobile-menu-button, .role-preview-trigger, .header-user .el-button { min-width: 44px; min-height: 44px; }
+  .shell-menu-button, .role-preview-trigger, .header-user .el-button { min-width: 44px; min-height: 44px; }
   .page-container { padding: 14px 8px 24px; }
   .forbidden-page { padding-right: 14px; padding-left: 14px; }
 }
 
+@media (min-width: 1920px) {
+  .business-page { gap: 12px; }
+  .metric-strip { gap: 12px; }
+  .metric-item { padding: 14px 16px; }
+  .metric-item span { margin-bottom: 6px; }
+  .filter-panel { padding: 10px 12px; gap: 12px; }
+  .filter-fields, .filter-actions { gap: 8px; }
+  .table-panel .el-table th.el-table__cell { height: 40px; }
+  .table-panel .el-table td.el-table__cell { padding: 10px 0; }
+  .panel-heading { min-height: 68px; padding: 12px 16px; gap: 14px; }
+  .panel-heading h2 { font-size: 15px; }
+  .table-footer { min-height: 52px; gap: 12px; padding: 8px 14px; }
+  .table-actions .el-button + .el-button { margin-left: 8px; }
+  .form-section { padding: 16px 0; }
+  .form-section h3, .detail-section h3 { margin-bottom: 12px; }
+  .form-grid { gap: 0 12px; }
+  .drawer-form .el-form-item { margin-bottom: 14px; }
+  .form-help { margin: -4px 0 14px; }
+}
+
 @media (prefers-reduced-motion: reduce) {
   .app-sidebar, .side-nav-item, .stat-card { transition: none !important; }
 }
diff --git a/src/styles/shell.css b/src/styles/shell.css
new file mode 100644
index 00000000..3163b498
--- /dev/null
+++ b/src/styles/shell.css
@@ -0,0 +1,76 @@
+.app-shell { min-width: 0; min-height: 100vh; }
+.app-sidebar { position: fixed; inset: 0 auto 0 0; z-index: 20; display: flex; width: 240px; flex-direction: column; border-right: 1px solid rgba(255,255,255,.3); background: rgba(255,255,255,.92); color: var(--cc-text-secondary); box-shadow: 4px 0 32px rgba(0,0,0,.08); backdrop-filter: blur(20px); }
+.is-collapsed .app-sidebar { width: 76px; }
+.brand-block { display: flex; height: 64px; flex: 0 0 64px; align-items: center; padding: 0 18px; background: var(--cc-topbar); }
+.brand-logo { display: block; object-fit: contain; object-position: left center; }
+.brand-logo-full { width: 184px; height: 50px; }
+.brand-logo-mark { display: none; width: 40px; height: 40px; }
+.is-collapsed .brand-logo-full { display: none; }
+.is-collapsed .brand-logo-mark { display: block; }
+.side-nav {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  padding: 12px 8px;
+  scrollbar-color: rgba(21, 94, 239, .22) transparent;
+  scrollbar-width: thin;
+}
+.side-nav::-webkit-scrollbar { width: 10px; }
+.side-nav::-webkit-scrollbar-track,
+.side-nav::-webkit-scrollbar-corner { background: transparent; }
+.side-nav::-webkit-scrollbar-thumb { border: 3px solid transparent; border-radius: var(--cc-radius-pill); background: rgba(21, 94, 239, .22); background-clip: padding-box; }
+.side-nav::-webkit-scrollbar-thumb:hover { background-color: rgba(21, 94, 239, .38); }
+.side-nav::-webkit-scrollbar-button,
+.side-nav::-webkit-scrollbar-button:single-button,
+.side-nav::-webkit-scrollbar-button:vertical:decrement,
+.side-nav::-webkit-scrollbar-button:vertical:increment { display: none; width: 0; height: 0; background: transparent; }
+.side-nav-menu {
+  width: 100%;
+  border-right: 0 !important;
+  background: transparent !important;
+  --el-menu-bg-color: transparent;
+  --el-menu-text-color: var(--cc-text-secondary);
+  --el-menu-active-color: var(--cc-menu-active);
+  --el-menu-hover-bg-color: var(--cc-primary-soft);
+}
+.side-nav-menu.el-menu--collapse { width: 56px; }
+.side-nav-menu .el-menu-item,
+.side-nav-menu .el-sub-menu__title { height: 44px; margin: 2px 0; border-radius: 0 var(--cc-radius-lg) var(--cc-radius-lg) 0; line-height: 44px; transition: color .16s ease, background .16s ease; }
+.side-nav-menu .el-menu-item:hover,
+.side-nav-menu .el-sub-menu__title:hover { color: var(--cc-menu-active); background: linear-gradient(135deg, rgba(102,126,234,.10), rgba(240,147,251,.08)); }
+.side-nav-menu .el-menu-item.is-active { background: linear-gradient(135deg, rgba(102,126,234,.18), rgba(240,147,251,.12)); color: var(--cc-menu-active); font-weight: 700; box-shadow: inset 3px 0 var(--cc-menu-active); }
+.side-nav-menu .el-sub-menu .el-menu { padding: 4px 0; background: var(--cc-surface-muted) !important; }
+.side-nav-menu .el-sub-menu .el-menu-item { min-width: 0; height: 40px; margin: 0 12px; padding-left: 54px !important; border-radius: var(--cc-radius-md); color: var(--cc-muted); line-height: 40px; }
+.side-nav-menu .el-sub-menu .el-menu-item:hover { background: rgba(102,126,234,.08); color: var(--cc-menu-active); }
+.side-nav-menu .el-sub-menu .el-menu-item.is-active { background: rgba(102,126,234,.12); box-shadow: none; color: var(--cc-menu-active); font-weight: 700; }
+.side-nav-menu .el-menu-item svg,
+.side-nav-menu .el-sub-menu__title svg { flex: 0 0 auto; margin-right: 12px; }
+.app-main { min-width: 0; min-height: 100vh; margin-left: 240px; }
+.is-collapsed .app-main { margin-left: 76px; }
+.app-header { position: sticky; top: 0; z-index: 15; display: flex; min-width: 0; min-height: 64px; align-items: center; gap: 16px; padding: 8px 20px; background: var(--cc-topbar); color: #fff; box-shadow: 0 8px 32px rgba(0,0,0,.15), 0 2px 8px rgba(0,0,0,.1); backdrop-filter: blur(20px); }
+.shell-menu-button { display: grid; width: 44px; height: 44px; flex: 0 0 44px; place-items: center; padding: 0; border: 0; border-radius: var(--cc-radius-md); background: transparent; color: #fff; cursor: pointer; transition: background .16s ease; }
+.shell-menu-button:hover { background: rgba(255,255,255,.12); }
+.shell-menu-button:focus-visible { outline-color: rgba(255,255,255,.8); }
+.page-heading { min-width: 0; flex: 1; }
+.page-heading h1 { margin: 0; overflow: hidden; font-size: var(--cc-list-page-title-font-size); letter-spacing: 0; text-overflow: ellipsis; white-space: nowrap; }
+.page-heading p { margin: 4px 0 0; overflow: hidden; color: rgba(255,255,255,.72); font-size: var(--cc-list-page-description-font-size); text-overflow: ellipsis; white-space: nowrap; }
+.header-user { display: flex; min-width: 0; flex: 0 0 auto; align-items: center; gap: 10px; }
+.user-avatar { display: grid; width: 36px; height: 36px; place-items: center; border-radius: 50%; background: #fff; color: var(--cc-primary); font-weight: 700; box-shadow: var(--cc-shadow-sm); }
+.user-copy { display: flex; flex-direction: column; }
+.user-copy strong { font-size: 13px; }
+.user-copy span { color: var(--cc-muted); font-size: 11px; }
+.header-user .el-button { width: 44px; height: 44px; color: #fff; }
+.header-user .el-button:hover { background: rgba(255,255,255,.15); color: #fff; }
+.page-container { padding: var(--cc-space-5) var(--cc-space-5) var(--cc-space-7); }
+
+/* Static permission preview */
+.app-header > .el-dropdown { min-width: 0; max-width: 320px; flex: 0 1 320px; }
+.role-preview-trigger { display: flex; width: 100%; min-width: 0; min-height: 44px; align-items: center; gap: 10px; padding: 6px 10px; border: 1px solid var(--cc-border); border-radius: var(--cc-radius-md); background: var(--cc-surface); color: var(--cc-text); text-align: left; cursor: pointer; }
+.role-preview-trigger:hover { border-color: var(--cc-border-strong); background: var(--cc-surface-muted); }
+.role-preview-trigger:focus-visible { border-color: var(--cc-primary); outline: 3px solid var(--cc-focus); outline-offset: 1px; }
+.role-preview-trigger:disabled, .role-preview-trigger[aria-disabled="true"] { cursor: not-allowed; opacity: .58; }
+.role-preview-trigger > svg { flex: 0 0 auto; }
+.role-preview-copy { display: flex; min-width: 0; flex: 1; flex-direction: column; gap: 2px; }
+.role-preview-copy strong, .role-preview-copy small { display: block; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.role-preview-copy strong { font-size: 12px; font-weight: 700; }
+.role-preview-copy small { color: var(--cc-muted); font-size: 10px; line-height: 1.35; }
diff --git a/src/types/admin.ts b/src/types/admin.ts
deleted file mode 100644
index 28f6eb1f..00000000
--- a/src/types/admin.ts
+++ /dev/null
@@ -1,147 +0,0 @@
-import type {
-  FirstLegOrderStatusLabel,
-  PlatformReceivingWarehouse,
-  PlatformReceivingWarehouseSnapshot,
-} from '@chongchong/shared'
-
-export type RecordStatus = '正常' | '停用'
-export type CustomerStatus = '正常' | '待审核' | '停用'
-export type RoleStatus = '启用' | '停用'
-export type PermissionType = '目录' | '菜单' | '按钮' | '接口'
-export type DataScope = '全部数据' | '本部门数据' | '本人数据' | '自定义'
-export type OrderStatus = FirstLegOrderStatusLabel
-export type Warehouse = PlatformReceivingWarehouse
-export type ExpressCompanyStatus = '合作中' | '已终止'
-export type CounterpartyStatus = '启用' | '停用'
-export type CounterpartyType = '供应商' | '客户' | '承运商' | '报关行' | '发货单位' | '收货单位'
-
-export interface ExpressCompany {
-  id: string
-  name: string
-  code: string
-  website: string
-  phone: string
-  status: ExpressCompanyStatus
-  remark: string
-  updatedAt: string
-}
-
-export interface Counterparty {
-  id: string
-  code: string
-  name: string
-  types: CounterpartyType[]
-  contactName: string
-  contactPhone: string
-  email: string
-  country: string
-  province: string
-  city: string
-  postalCode: string
-  address: string
-  status: CounterpartyStatus
-  remark: string
-  updatedAt: string
-}
-
-export interface FirstLegDeliveryInfo {
-  expressCompanyId: string
-  expressCompanyCode: string
-  expressCompanyName: string
-  trackingNo: string
-  updatedAt: string
-  operator: string
-}
-
-export interface Customer {
-  id: string
-  name: string
-  creditCode: string
-  contact: string
-  phone: string
-  email: string
-  sales: string
-  packageName: '基础版' | '专业版' | '企业版'
-  period: number
-  status: CustomerStatus
-  orders: number
-  joinedAt: string
-  address: string
-  remark: string
-}
-
-export interface InternalUser {
-  id: string
-  account: string
-  name: string
-  department: string
-  phone: string
-  email: string
-  roleIds: string[]
-  status: RecordStatus
-  lastLogin: string
-  createdAt: string
-}
-
-export interface Role {
-  id: string
-  name: string
-  code: string
-  description: string
-  userCount: number
-  dataScope: DataScope
-  status: RoleStatus
-  permissionIds: string[]
-  builtIn?: boolean
-}
-
-export interface Permission {
-  id: string
-  parentId: string | null
-  name: string
-  code: string
-  type: PermissionType
-  path: string
-  method: string
-  status: RoleStatus
-  sort: number
-}
-
-export interface OrderTimelineItem {
-  time: string
-  title: string
-  description: string
-  operator: string
-}
-
-export interface FirstLegOrder {
-  id: string
-  no: string
-  customerId: string
-  customerName: string
-  referenceNo: string
-  transportMode: '海运整箱 FCL' | '海运拼箱 LCL' | '空运' | '陆运'
-  businessType: '出口' | '进口'
-  origin: string
-  destination: string
-  receivingWarehouseId: string
-  receivingWarehouseSnapshot: PlatformReceivingWarehouseSnapshot | null
-  container: string
-  etd: string
-  eta: string
-  amount: number
-  currency: 'CNY' | 'USD'
-  status: OrderStatus
-  priority: '普通' | '紧急' | '加急'
-  operator: string
-  shipper: string
-  consignee: string
-  cargoName: string
-  pieces: number
-  weight: number
-  volume: number
-  createdAt: string
-  remark: string
-  deliveryInfo?: FirstLegDeliveryInfo | null
-  timeline: OrderTimelineItem[]
-}
diff --git a/src/utils/permissionTree.ts b/src/utils/permissionTree.ts
deleted file mode 100644
index eeeb42a5..00000000
--- a/src/utils/permissionTree.ts
+++ /dev/null
@@ -1,75 +0,0 @@
-import type { Permission } from '@/types/admin'
-
-export type PermissionTreeNode = Permission & { children?: PermissionTreeNode[] }
-export type PermissionMatcher = (permission: Permission) => boolean
-
-function groupByParent(permissions: Permission[]) {
-  const childrenByParent = new Map<string | null, Permission[]>()
-
-  permissions.forEach((permission) => {
-    const siblings = childrenByParent.get(permission.parentId) ?? []
-    siblings.push(permission)
-    childrenByParent.set(permission.parentId, siblings)
-  })
-
-  childrenByParent.forEach((siblings) => {
-    siblings.sort((left, right) => left.sort - right.sort)
-  })
-
-  return childrenByParent
-}
-
-export function buildPermissionTree(
-  permissions: Permission[],
-  matches: PermissionMatcher = () => true,
-): PermissionTreeNode[] {
-  const childrenByParent = groupByParent(permissions)
-
-  function buildNode(permission: Permission, ancestors: Set<string>): PermissionTreeNode | null {
-    if (ancestors.has(permission.id)) return null
-
-    const nextAncestors = new Set(ancestors).add(permission.id)
-    const children = (childrenByParent.get(permission.id) ?? [])
-      .map((child) => buildNode(child, nextAncestors))
-      .filter((child): child is PermissionTreeNode => child !== null)
-
-    if (!matches(permission) && children.length === 0) return null
-
-    return {
-      ...permission,
-      ...(children.length ? { children } : {}),
-    }
-  }
-
-  return (childrenByParent.get(null) ?? [])
-    .map((permission) => buildNode(permission, new Set()))
-    .filter((node): node is PermissionTreeNode => node !== null)
-}
-
-export function getDescendantIds(permissions: Permission[], permissionId: string): string[] {
-  const childrenByParent = groupByParent(permissions)
-  const visited = new Set([permissionId])
-  const descendants: string[] = []
-  const queue = [...(childrenByParent.get(permissionId) ?? [])]
-
-  while (queue.length) {
-    const current = queue.shift()
-    if (!current || visited.has(current.id)) continue
-
-    visited.add(current.id)
-    descendants.push(current.id)
-    queue.push(...(childrenByParent.get(current.id) ?? []))
-  }
-
-  return descendants
-}
-
-export function summarizePermissionSelection(permissions: Permission[], selectedIds: string[]) {
-  const selected = new Set(selectedIds)
-  const selectedPermissions = permissions.filter((permission) => selected.has(permission.id))
-
-  return {
-    menuCount: selectedPermissions.filter((permission) => permission.type === '菜单').length,
-    actionCount: selectedPermissions.filter((permission) => ['按钮', '接口'].includes(permission.type)).length,
-  }
-}
diff --git a/src/views/AccessControlledActions.test.ts b/src/views/AccessControlledActions.test.ts
deleted file mode 100644
index b09738be..00000000
--- a/src/views/AccessControlledActions.test.ts
+++ /dev/null
@@ -1,325 +0,0 @@
-import ElementPlus, { type MessageBoxData } from 'element-plus'
-import { createPinia, setActivePinia, type Pinia } from 'pinia'
-import { enableAutoUnmount, flushPromises, mount, type VueWrapper } from '@vue/test-utils'
-import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { nextTick } from 'vue'
-import { useAccessPreviewStore } from '@/stores/accessPreview'
-import { useUnsavedWorkStore } from '@/stores/unsavedWork'
-import CustomersView from './CustomersView.vue'
-import FirstLegOrdersView from './FirstLegOrdersView.vue'
-import InternalUsersView from './InternalUsersView.vue'
-import PermissionsView from './PermissionsView.vue'
-import RolesView from './RolesView.vue'
-import WarehousesView from './WarehousesView.vue'
-import { useAdminDataStore } from '@/stores/adminData'
-import { ElMessageBox } from 'element-plus'
-
-class ResizeObserverStub implements ResizeObserver {
-  observe() {}
-  unobserve() {}
-  disconnect() {}
-}
-
-function createMemoryStorage(): Storage {
-  const values = new Map<string, string>()
-  return {
-    get length() { return values.size },
-    clear: () => values.clear(),
-    getItem: (key) => values.get(key) ?? null,
-    key: (index) => [...values.keys()][index] ?? null,
-    removeItem: (key) => values.delete(key),
-    setItem: (key, value) => values.set(key, value),
-  }
-}
-
-async function mountForRole(
-  component: typeof CustomersView | typeof FirstLegOrdersView | typeof InternalUsersView | typeof RolesView | typeof PermissionsView | typeof WarehousesView,
-  roleId: string,
-) {
-  const pinia: Pinia = createPinia()
-  setActivePinia(pinia)
-  const access = useAccessPreviewStore()
-  access.initializeAfterLogin()
-  expect(access.commitRole(roleId)).toBe(true)
-  const wrapper = mount(component, {
-    attachTo: document.body,
-    global: { plugins: [pinia, ElementPlus] },
-  })
-  await flushPromises()
-  return { wrapper, access, unsaved: useUnsavedWorkStore() }
-}
-
-function buttonTexts(wrapper: VueWrapper) {
-  return wrapper.findAll('button').map((button) => button.text().trim())
-}
-
-async function clickButton(wrapper: VueWrapper, text: string) {
-  const button = wrapper.findAll('button').find((candidate) => candidate.text().trim() === text)
-  if (!button) throw new Error(`Button not found: ${text}`)
-  await button.trigger('click')
-  await flushPromises()
-}
-
-async function fillNativeInput(placeholder: string, value: string) {
-  const input = document.querySelector<HTMLInputElement>(`input[placeholder="${placeholder}"]`)
-  if (!input) throw new Error(`Input not found: ${placeholder}`)
-  input.value = value
-  input.dispatchEvent(new Event('input', { bubbles: true }))
-  await nextTick()
-}
-
-enableAutoUnmount(afterEach)
-afterAll(() => vi.unstubAllGlobals())
-
-describe('business action permissions', () => {
-  beforeEach(() => {
-    vi.stubGlobal('localStorage', createMemoryStorage())
-    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
-    document.body.innerHTML = ''
-  })
-
-  it('keeps review actions out of customer records now that reviews use a dedicated route', async () => {
-    const { wrapper } = await mountForRole(CustomersView, 'R002')
-    const texts = buttonTexts(wrapper)
-
-    expect(texts).not.toContain('新增客户')
-    expect(texts).not.toContain('审核')
-    expect(texts).toContain('编辑')
-  })
-
-  it('shows no audit or status action for a pending customer without audit permission', async () => {
-    const { wrapper } = await mountForRole(CustomersView, 'R005')
-    const pendingRow = wrapper.findAll('tr')
-      .find((row) => row.text().includes('北京国贸跨境供应链有限公司'))
-    expect(pendingRow).toBeDefined()
-
-    const actions = pendingRow?.findAll('button').map((button) => button.text().trim()) ?? []
-    expect(actions).not.toContain('审核')
-    expect(actions).not.toContain('停用')
-    expect(actions).not.toContain('启用')
-  })
-
-  it('lets sales create and edit customers while finance cannot update orders', async () => {
-    const sales = await mountForRole(CustomersView, 'R005')
-    expect(buttonTexts(sales.wrapper)).toContain('新增客户')
-    sales.wrapper.unmount()
-    document.body.innerHTML = ''
-
-    const finance = await mountForRole(FirstLegOrdersView, 'R004')
-    const texts = buttonTexts(finance.wrapper)
-    expect(texts).not.toContain('创建订单')
-    expect(texts).not.toContain('批量更新')
-    expect(texts).not.toContain('处理')
-    expect(texts).toContain('详情')
-    expect(texts).not.toContain('编辑')
-  })
-
-  it('shows create actions to the super administrator but no order status actions to sales', async () => {
-    const superAdmin = await mountForRole(FirstLegOrdersView, 'R001')
-    expect(buttonTexts(superAdmin.wrapper)).toContain('创建订单')
-    expect(buttonTexts(superAdmin.wrapper)).toContain('批量更新')
-    expect(buttonTexts(superAdmin.wrapper)).toContain('处理')
-    superAdmin.wrapper.unmount()
-    document.body.innerHTML = ''
-
-    const sales = await mountForRole(FirstLegOrdersView, 'R005')
-    const texts = buttonTexts(sales.wrapper)
-    expect(texts).not.toContain('批量更新')
-    expect(texts).not.toContain('处理')
-    expect(texts).not.toContain('编辑')
-  })
-
-  it('lets operations maintain warehouses while operators can only view them', async () => {
-    const operations = await mountForRole(WarehousesView, 'R002')
-    expect(buttonTexts(operations.wrapper)).toContain('新增仓库')
-    expect(buttonTexts(operations.wrapper)).toContain('编辑')
-    expect(buttonTexts(operations.wrapper)).toContain('停用')
-    operations.wrapper.unmount()
-    document.body.innerHTML = ''
-
-    const operator = await mountForRole(WarehousesView, 'R003')
-    expect(buttonTexts(operator.wrapper)).not.toContain('新增仓库')
-    expect(buttonTexts(operator.wrapper)).not.toContain('编辑')
-    expect(operator.wrapper.text()).toContain('仅查看')
-  })
-
-  it('registers a dirty customer draft and discards it when create permission is lost', async () => {
-    const { wrapper, access, unsaved } = await mountForRole(CustomersView, 'R001')
-    await clickButton(wrapper, '新增客户')
-    await fillNativeInput('请输入营业执照上的企业名称', '测试客户')
-
-    expect(unsaved.entries).toContainEqual({
-      key: 'customer-editor',
-      label: '新增客户',
-      dirty: true,
-      requiredPermission: 'customer:create',
-    })
-
-    expect(access.commitRole('R002')).toBe(true)
-    await flushPromises()
-
-    expect(unsaved.entries.find((entry) => entry.key === 'customer-editor')).toBeUndefined()
-    expect(document.body.textContent).not.toContain('请输入营业执照上的企业名称')
-  })
-
-  it.each([
-    [CustomersView, '新增客户'],
-    [FirstLegOrdersView, '创建订单'],
-    [InternalUsersView, '新增用户'],
-    [RolesView, '新增角色'],
-    [PermissionsView, '新增权限'],
-  ] as const)('keeps the role preview reachable while the %s editor is open', async (component, openText) => {
-    const { wrapper } = await mountForRole(component, 'R001')
-    await clickButton(wrapper, openText)
-
-    const editor = wrapper.findComponent({ name: 'ElDrawer' })
-    expect(editor.exists()).toBe(true)
-    expect(document.querySelector('.editor-drawer')).not.toBeNull()
-    expect(editor.props('modal')).toBe(false)
-    expect(editor.props('closeOnClickModal')).toBe(false)
-  })
-
-  it('keeps an existing customer editor open when create permission is lost', async () => {
-    const { wrapper, access, unsaved } = await mountForRole(CustomersView, 'R001')
-    await clickButton(wrapper, '编辑')
-
-    expect(unsaved.entries.find((entry) => entry.key === 'customer-editor')).toMatchObject({
-      label: '编辑客户',
-      requiredPermission: null,
-    })
-
-    expect(access.commitRole('R002')).toBe(true)
-    await flushPromises()
-
-    expect(unsaved.entries.find((entry) => entry.key === 'customer-editor')).toBeDefined()
-    expect(document.body.textContent).toContain('编辑客户')
-  })
-
-  it('discards only a new order editor when create permission is lost', async () => {
-    const { wrapper, access, unsaved } = await mountForRole(FirstLegOrdersView, 'R001')
-    await clickButton(wrapper, '创建订单')
-    await fillNativeInput('如 宁波', '上海')
-
-    expect(unsaved.entries.find((entry) => entry.key === 'first-leg-order-editor')).toMatchObject({
-      label: '创建头程订单',
-      dirty: true,
-      requiredPermission: 'first-leg:create',
-    })
-
-    expect(access.commitRole('R004')).toBe(true)
-    await flushPromises()
-    expect(unsaved.entries.find((entry) => entry.key === 'first-leg-order-editor')).toBeUndefined()
-
-    access.commitRole('R001')
-    await nextTick()
-    await clickButton(wrapper, '编辑')
-    expect(unsaved.entries.find((entry) => entry.key === 'first-leg-order-editor')).toMatchObject({
-      label: '编辑头程订单',
-      requiredPermission: null,
-    })
-
-    expect(access.commitRole('R004')).toBe(true)
-    await flushPromises()
-    expect(unsaved.entries.find((entry) => entry.key === 'first-leg-order-editor')).toBeDefined()
-    expect(document.body.textContent).toContain('编辑头程订单')
-  })
-
-  it.each([
-    [InternalUsersView, '系统管理员', ['编辑', '重置密码', '停用']],
-    [RolesView, '超级管理员', ['配置', '停用', '删除']],
-    [PermissionsView, '系统管理', ['编辑', '添加下级', '停用']],
-  ] as const)('hides every maintenance action on %s rows for the operations manager', async (component, rowText, actions) => {
-    const { wrapper } = await mountForRole(component, 'R002')
-    const row = wrapper.findAll('tr').find((candidate) => candidate.text().includes(rowText))
-    expect(row).toBeDefined()
-    const rowActions = row?.findAll('button').map((button) => button.text().trim()) ?? []
-    for (const action of actions) expect(rowActions).not.toContain(action)
-  })
-
-  it.each([
-    [InternalUsersView, '新增用户', '系统管理员', '编辑'],
-    [RolesView, '新增角色', '超级管理员', '配置'],
-    [PermissionsView, '新增权限', '系统管理', '添加下级'],
-  ] as const)('shows toolbar and row maintenance actions on %s for the super administrator', async (component, toolbarAction, rowText, rowAction) => {
-    const { wrapper } = await mountForRole(component, 'R001')
-    expect(buttonTexts(wrapper)).toContain(toolbarAction)
-    const row = wrapper.findAll('tr').find((candidate) => candidate.text().includes(rowText))
-    expect(row?.findAll('button').map((button) => button.text().trim())).toContain(rowAction)
-  })
-
-  it.each([
-    [InternalUsersView, '新增用户', null, null, 'internal-user-editor', '新增内部用户', 'system:user:write'],
-    [RolesView, '新增角色', null, null, 'role-editor', '新增角色', 'system:role:grant'],
-    [PermissionsView, '新增权限', '用户可理解的中文名称', '测试权限', 'permission-editor', '新增权限', 'system:permission:write'],
-  ] as const)('registers system editor dirty work with the maintenance permission on %s', async (component, openText, placeholder, value, key, label, requiredPermission) => {
-    const { wrapper, unsaved } = await mountForRole(component, 'R001')
-    await clickButton(wrapper, openText)
-    if (placeholder && value) await fillNativeInput(placeholder, value)
-    if (!placeholder) {
-      const nameInput = document.querySelector<HTMLInputElement>('.el-drawer input')
-      expect(nameInput).not.toBeNull()
-      if (nameInput) {
-        nameInput.value = `${label}测试内容`
-        nameInput.dispatchEvent(new Event('input', { bubbles: true }))
-        await nextTick()
-      }
-    }
-
-    expect(unsaved.entries.find((entry) => entry.key === key)).toMatchObject({
-      label,
-      dirty: true,
-      requiredPermission,
-    })
-    expect(buttonTexts(wrapper)).toContain(component === InternalUsersView ? '保存用户' : component === RolesView ? '保存角色' : '保存权限')
-  })
-
-  it('marks the role editor dirty when only a permission checkbox changes', async () => {
-    const { wrapper, unsaved } = await mountForRole(RolesView, 'R001')
-    await clickButton(wrapper, '配置')
-    const permissionCheckbox = document.querySelector<HTMLElement>('.el-drawer .el-tree .el-checkbox')
-    expect(permissionCheckbox).not.toBeNull()
-    permissionCheckbox?.click()
-    await flushPromises()
-
-    expect(unsaved.entries.find((entry) => entry.key === 'role-editor')).toMatchObject({
-      dirty: true,
-      requiredPermission: 'system:role:grant',
-    })
-  })
-
-  it.each([
-    [InternalUsersView, '保存用户'],
-    [RolesView, '保存角色'],
-    [PermissionsView, '保存权限'],
-  ] as const)('does not render a save entry on %s without maintenance permission', async (component, saveText) => {
-    const { wrapper } = await mountForRole(component, 'R002')
-    expect(buttonTexts(wrapper)).not.toContain(saveText)
-  })
-
-  it('warns that disabling a directory is non-cascading and preserves descendant statuses', async () => {
-    const confirm = vi.spyOn(ElMessageBox, 'confirm').mockResolvedValue({
-      value: '',
-      action: 'confirm',
-    } as unknown as MessageBoxData)
-    const { wrapper } = await mountForRole(PermissionsView, 'R001')
-    const data = useAdminDataStore()
-    const directory = data.permissions.find((permission) => permission.id === 'P020')
-    const descendant = data.permissions.find((permission) => permission.id === 'P300')
-    expect(directory?.status).toBe('启用')
-    expect(descendant?.status).toBe('启用')
-
-    const row = wrapper.findAll('tr').find((candidate) => candidate.text().includes('系统管理'))
-    const stop = row?.findAll('button').find((button) => button.text().trim() === '停用')
-    expect(stop).toBeDefined()
-    await stop?.trigger('click')
-    await flushPromises()
-
-    expect(confirm).toHaveBeenCalledWith(
-      expect.stringContaining('目录仅用于组织结构，停用不会级联影响已启用的下级菜单和操作。'),
-      '权限状态',
-      expect.any(Object),
-    )
-    expect(data.permissions.find((permission) => permission.id === 'P020')?.status).toBe('停用')
-    expect(data.permissions.find((permission) => permission.id === 'P300')?.status).toBe('启用')
-  })
-})
diff --git a/src/views/CounterpartiesView.vue b/src/views/CounterpartiesView.vue
deleted file mode 100644
index 49d32e32..00000000
--- a/src/views/CounterpartiesView.vue
+++ /dev/null
@@ -1,182 +0,0 @@
-<script setup lang="ts">
-import { computed, reactive, ref, watch } from 'vue'
-import { ElMessage, ElMessageBox } from 'element-plus'
-import { Building2, Eye, FileUp, MapPin, Pencil, Plus, RotateCcw, Search } from '@lucide/vue'
-import MetricStrip from '@/components/MetricStrip.vue'
-import StaticBatchImportDialog from '@/components/StaticBatchImportDialog.vue'
-import StatusBadge from '@/components/StatusBadge.vue'
-import { useUnsavedWorkRegistration } from '@/composables/useUnsavedWorkRegistration'
-import { useAccessPreviewStore } from '@/stores/accessPreview'
-import { useAdminDataStore } from '@/stores/adminData'
-import type { Counterparty, CounterpartyStatus, CounterpartyType } from '@/types/admin'
-
-const store = useAdminDataStore()
-const access = useAccessPreviewStore()
-const page = ref(1)
-const pageSize = 10
-const editorOpen = ref(false)
-const detailOpen = ref(false)
-const importOpen = ref(false)
-const selectedCounterparty = ref<Counterparty | null>(null)
-const filters = reactive({ keyword: '', type: '' as CounterpartyType | '', status: '' as CounterpartyStatus | '' })
-const counterpartyTypes: CounterpartyType[] = ['供应商', '客户', '承运商', '报关行', '发货单位', '收货单位']
-
-const emptyForm = (): Omit<Counterparty, 'updatedAt'> => ({
-  id: '', code: '', name: '', types: [], contactName: '', contactPhone: '', email: '',
-  country: '中国', province: '', city: '', postalCode: '', address: '', status: '启用', remark: '',
-})
-const form = reactive(emptyForm())
-const editorLabel = computed(() => form.id ? '编辑往来单位' : '新增往来单位')
-const { captureBaseline } = useUnsavedWorkRegistration({
-  key: 'counterparty-editor',
-  label: editorLabel,
-  isOpen: editorOpen,
-  model: form,
-  requiredPermission: computed(() => form.id ? null : 'counterparty:write'),
-})
-
-const filteredRows = computed(() => store.counterparties.filter((item) => {
-  const keyword = filters.keyword.trim().toLowerCase()
-  const keywordMatches = !keyword || [item.name, item.code, item.contactName, item.contactPhone, item.email]
-    .some((value) => value.toLowerCase().includes(keyword))
-  return keywordMatches && (!filters.type || item.types.includes(filters.type)) && (!filters.status || item.status === filters.status)
-}))
-const pagedRows = computed(() => filteredRows.value.slice((page.value - 1) * pageSize, page.value * pageSize))
-const metrics = computed(() => [
-  { label: '全部单位', value: store.counterparties.length, note: '当前静态数据范围' },
-  { label: '启用单位', value: store.activeCounterparties, note: '可供业务引用' },
-  { label: '多类型单位', value: store.counterparties.filter((item) => item.types.length > 1).length, note: '一个档案承担多个角色' },
-  { label: '收发货单位', value: store.counterparties.filter((item) => item.types.some((type) => ['发货单位', '收货单位'].includes(type))).length, note: '客户端只读选择范围' },
-])
-
-watch(filters, () => { page.value = 1 })
-
-function resetFilters() { Object.assign(filters, { keyword: '', type: '', status: '' }) }
-function openCreate() { Object.assign(form, emptyForm()); captureBaseline(); editorOpen.value = true }
-function openEdit(item: Counterparty) { Object.assign(form, { ...item, types: [...item.types] }); captureBaseline(); detailOpen.value = false; editorOpen.value = true }
-function openDetail(item: Counterparty) { selectedCounterparty.value = item; detailOpen.value = true }
-
-function saveCounterparty() {
-  if (!form.code.trim() || !form.name.trim() || form.types.length === 0 || !form.contactName.trim() || !form.contactPhone.trim() || !form.country.trim() || !form.city.trim() || !form.address.trim()) {
-    ElMessage.warning('请填写单位编码、名称、至少一种类型、联系人、电话及完整地址')
-    return
-  }
-  if (form.email && !/^\S+@\S+\.\S+$/.test(form.email)) {
-    ElMessage.warning('请输入正确的联系邮箱')
-    return
-  }
-  try {
-    store.saveCounterparty({ ...form, id: form.id || undefined, types: [...form.types] })
-    editorOpen.value = false
-    ElMessage.success(form.id ? '往来单位已更新' : '往来单位已创建')
-  } catch (error) {
-    ElMessage.error(error instanceof Error ? error.message : '往来单位保存失败')
-  }
-}
-
-async function toggleStatus(item: Counterparty) {
-  const target: CounterpartyStatus = item.status === '启用' ? '停用' : '启用'
-  try {
-    await ElMessageBox.confirm(
-      target === '停用' ? '停用后不能用于新订单，历史订单快照不受影响。' : '启用后可重新用于符合类型和数据范围的新订单。',
-      `${target}往来单位“${item.name}”`,
-      { confirmButtonText: target, cancelButtonText: '取消', type: 'warning' },
-    )
-    store.setCounterpartyStatus(item.id, target)
-    ElMessage.success(`往来单位已${target}`)
-  } catch {
-    // 用户取消，不需要反馈。
-  }
-}
-
-function addressText(item: Counterparty) {
-  return [item.country, item.province, item.city, item.address, item.postalCode].filter(Boolean).join(' · ')
-}
-</script>
-
-<template>
-  <!-- THESIS: 把多角色往来单位整理成可扫描、可维护的主数据目录，而不是复制原型的宽表。
-  OWN-WORLD: 延续 Admin 的海军蓝导航、白色数据面板、紧凑筛选区、状态标签与右侧抽屉。
-  STORY: 平台人员按类型和状态定位单位，核对联系地址，维护多类型档案或执行整批导入。
-  FIRST VIEWPORT: 四项运营摘要、三条件筛选、维护与导入动作、单位表格连续出现。
-  FORM: 现有 Operate 页面结构的扩展，类型用标签聚合，完整资料在抽屉中展开。
-  FINISH: unreviewed and undocumented is unfinished; this build ends with the finish review, the verdict, and DESIGN.md -->
-  <div class="business-page counterparty-page">
-    <MetricStrip :items="metrics" />
-
-    <section class="surface-panel filter-panel" aria-label="往来单位筛选">
-      <div class="filter-fields">
-        <el-input v-model="filters.keyword" clearable placeholder="单位名称、编码、联系人或电话" aria-label="往来单位关键词"><template #prefix><Search :size="16" /></template></el-input>
-        <el-select v-model="filters.type" clearable placeholder="全部类型" aria-label="往来单位类型"><el-option v-for="item in counterpartyTypes" :key="item" :label="item" :value="item" /></el-select>
-        <el-select v-model="filters.status" clearable placeholder="全部状态" aria-label="往来单位状态"><el-option label="启用" value="启用" /><el-option label="停用" value="停用" /></el-select>
-      </div>
-      <div class="filter-actions">
-        <el-button @click="resetFilters"><RotateCcw :size="16" />重置</el-button>
-        <el-button v-if="access.can('counterparty:import')" @click="importOpen = true"><FileUp :size="16" />批量导入</el-button>
-        <el-button v-if="access.can('counterparty:write')" type="primary" @click="openCreate"><Plus :size="16" />新增单位</el-button>
-      </div>
-    </section>
-
-    <section class="surface-panel table-panel">
-      <header class="panel-heading"><div><h2>往来单位档案</h2><p>平台维护完整主数据；企业客户端仅可只读选择已启用的发货单位和收货单位。</p></div></header>
-      <el-table :data="pagedRows" row-key="id" empty-text="没有符合条件的往来单位">
-        <el-table-column label="单位" min-width="230"><template #default="{ row }"><div class="counterparty-cell"><span><Building2 :size="17" /></span><div><strong>{{ (row as Counterparty).name }}</strong><small>{{ (row as Counterparty).code }}</small></div></div></template></el-table-column>
-        <el-table-column label="类型" min-width="220"><template #default="{ row }"><div class="type-tags"><el-tag v-for="type in (row as Counterparty).types" :key="type" size="small" effect="plain">{{ type }}</el-tag></div></template></el-table-column>
-        <el-table-column label="主要联系人" min-width="170"><template #default="{ row }"><div class="primary-cell"><strong>{{ (row as Counterparty).contactName }}</strong><span>{{ (row as Counterparty).contactPhone }}</span></div></template></el-table-column>
-        <el-table-column label="城市 / 地址" min-width="210"><template #default="{ row }"><div class="primary-cell"><strong>{{ (row as Counterparty).country }} · {{ (row as Counterparty).city }}</strong><span>{{ (row as Counterparty).address }}</span></div></template></el-table-column>
-        <el-table-column label="状态" width="90"><template #default="{ row }"><StatusBadge :status="(row as Counterparty).status" /></template></el-table-column>
-        <el-table-column label="操作" width="220" fixed="right"><template #default="{ row }"><div class="table-actions"><el-button link type="primary" @click="openDetail(row as Counterparty)"><Eye :size="15" />详情</el-button><el-button v-if="access.can('counterparty:write')" link type="primary" @click="openEdit(row as Counterparty)"><Pencil :size="15" />编辑</el-button><el-button v-if="access.can('counterparty:write')" link :type="(row as Counterparty).status === '启用' ? 'danger' : 'success'" @click="toggleStatus(row as Counterparty)">{{ (row as Counterparty).status === '启用' ? '停用' : '启用' }}</el-button></div></template></el-table-column>
-      </el-table>
-      <footer class="table-footer"><span>显示 {{ pagedRows.length }} 条，共 {{ filteredRows.length }} 条</span><el-pagination v-model:current-page="page" :page-size="pageSize" :total="filteredRows.length" layout="prev, pager, next" /></footer>
-    </section>
-
-    <el-drawer v-model="editorOpen" :title="form.id ? '编辑往来单位' : '新增往来单位'" size="760px" class="business-drawer editor-drawer" :modal="false" :close-on-click-modal="false">
-      <el-form label-position="top" class="drawer-form">
-        <div class="form-section"><h3>单位信息</h3><div class="form-grid two-cols">
-          <el-form-item label="单位编码" required><el-input v-model="form.code" placeholder="如 CP-SUP-001" maxlength="40" /></el-form-item>
-          <el-form-item label="单位名称" required><el-input v-model="form.name" placeholder="请输入营业执照或登记名称" maxlength="120" /></el-form-item>
-          <el-form-item class="wide-field" label="单位类型" required><el-select v-model="form.types" multiple collapse-tags :max-collapse-tags="3" placeholder="可多选"><el-option v-for="item in counterpartyTypes" :key="item" :label="item" :value="item" /></el-select></el-form-item>
-          <el-form-item label="状态"><el-radio-group v-model="form.status"><el-radio-button label="启用" value="启用" /><el-radio-button label="停用" value="停用" /></el-radio-group></el-form-item>
-        </div></div>
-        <div class="form-section"><h3>联系信息</h3><div class="form-grid two-cols">
-          <el-form-item label="联系人" required><el-input v-model="form.contactName" maxlength="60" /></el-form-item>
-          <el-form-item label="联系电话" required><el-input v-model="form.contactPhone" maxlength="32" /></el-form-item>
-          <el-form-item label="联系邮箱"><el-input v-model="form.email" maxlength="120" /></el-form-item>
-        </div></div>
-        <div class="form-section"><h3>主要地址</h3><div class="form-grid three-cols">
-          <el-form-item label="国家/地区" required><el-input v-model="form.country" maxlength="40" /></el-form-item>
-          <el-form-item label="省/州"><el-input v-model="form.province" maxlength="60" /></el-form-item>
-          <el-form-item label="城市" required><el-input v-model="form.city" maxlength="60" /></el-form-item>
-          <el-form-item label="邮政编码"><el-input v-model="form.postalCode" maxlength="20" /></el-form-item>
-          <el-form-item class="wide-field" label="详细地址" required><el-input v-model="form.address" maxlength="180" /></el-form-item>
-        </div><el-form-item label="内部备注"><el-input v-model="form.remark" type="textarea" :rows="3" maxlength="300" show-word-limit /></el-form-item></div>
-      </el-form>
-      <template #footer><div class="drawer-footer"><el-button @click="editorOpen = false">取消</el-button><el-button v-if="access.can('counterparty:write')" type="primary" @click="saveCounterparty">保存往来单位</el-button></div></template>
-    </el-drawer>
-
-    <el-drawer v-model="detailOpen" title="往来单位详情" size="620px" class="business-drawer">
-      <template v-if="selectedCounterparty">
-        <div class="detail-identity"><span><Building2 :size="20" /></span><div><h2>{{ selectedCounterparty.name }}</h2><p>{{ selectedCounterparty.code }} · {{ selectedCounterparty.id }}</p></div><StatusBadge :status="selectedCounterparty.status" /></div>
-        <div class="detail-section"><h3>单位角色</h3><div class="type-tags"><el-tag v-for="type in selectedCounterparty.types" :key="type" effect="plain">{{ type }}</el-tag></div></div>
-        <div class="detail-section"><h3>联系与地址</h3><el-descriptions :column="1" border><el-descriptions-item label="联系人">{{ selectedCounterparty.contactName }} · {{ selectedCounterparty.contactPhone }}</el-descriptions-item><el-descriptions-item label="邮箱">{{ selectedCounterparty.email || '—' }}</el-descriptions-item><el-descriptions-item label="完整地址"><span class="address-value"><MapPin :size="15" />{{ addressText(selectedCounterparty) }}</span></el-descriptions-item><el-descriptions-item label="更新时间">{{ selectedCounterparty.updatedAt }}</el-descriptions-item></el-descriptions></div>
-        <div class="detail-section"><h3>内部备注</h3><p class="detail-note">{{ selectedCounterparty.remark || '暂无内部备注。' }}</p></div>
-      </template>
-      <template #footer><div class="drawer-footer"><el-button @click="detailOpen = false">关闭</el-button><el-button v-if="access.can('counterparty:write') && selectedCounterparty" type="primary" @click="openEdit(selectedCounterparty)">编辑资料</el-button></div></template>
-    </el-drawer>
-
-    <StaticBatchImportDialog v-model="importOpen" entity-label="往来单位" template-url="/templates/counterparties-import-template.xlsx" template-file-name="往来单位导入标准模板-v1.xlsx" />
-  </div>
-</template>
-
-<style scoped>
-.counterparty-cell { display: flex; min-width: 0; align-items: center; gap: 10px; }
-.counterparty-cell > span { display: grid; width: 34px; height: 34px; flex: 0 0 34px; place-items: center; background: #eef3fa; color: var(--cc-primary); }
-.counterparty-cell > div { display: flex; min-width: 0; flex-direction: column; gap: 3px; }
-.counterparty-cell strong, .counterparty-cell small { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
-.counterparty-cell small { color: var(--cc-muted); font-size: 11px; }
-.type-tags { display: flex; flex-wrap: wrap; gap: 5px; }
-.wide-field { grid-column: span 2; }
-.address-value { display: inline-flex; align-items: flex-start; gap: 6px; line-height: 1.6; }
-.address-value svg { flex: 0 0 auto; margin-top: 2px; color: var(--cc-muted); }
-@media (max-width: 720px) { .wide-field { grid-column: auto; } }
-</style>
diff --git a/src/views/CustomersView.vue b/src/views/CustomersView.vue
deleted file mode 100644
index a411cbc5..00000000
--- a/src/views/CustomersView.vue
+++ /dev/null
@@ -1,190 +0,0 @@
-<script setup lang="ts">
-import { computed, reactive, ref, watch } from 'vue'
-import { ElMessage, ElMessageBox } from 'element-plus'
-import { Download, Eye, Pencil, Plus, RotateCcw, Search } from '@lucide/vue'
-import MetricStrip from '@/components/MetricStrip.vue'
-import StatusBadge from '@/components/StatusBadge.vue'
-import { useUnsavedWorkRegistration } from '@/composables/useUnsavedWorkRegistration'
-import { useAccessPreviewStore } from '@/stores/accessPreview'
-import { useAdminDataStore } from '@/stores/adminData'
-import type { Customer } from '@/types/admin'
-
-const store = useAdminDataStore()
-const access = useAccessPreviewStore()
-const page = ref(1)
-const pageSize = 10
-const editorOpen = ref(false)
-const detailOpen = ref(false)
-const currentCustomer = ref<Customer | null>(null)
-const filters = reactive({ keyword: '', status: '', packageName: '' })
-
-const emptyForm = (): Omit<Customer, 'orders' | 'joinedAt'> => ({
-  id: '', name: '', creditCode: '', contact: '', phone: '', email: '', sales: '',
-  packageName: '基础版', period: 30, status: '正常', address: '', remark: '',
-})
-const form = reactive(emptyForm())
-const editorLabel = computed(() => form.id ? '编辑客户' : '新增客户')
-const editorRequiredPermission = computed(() => form.id ? null : 'customer:create')
-const { captureBaseline } = useUnsavedWorkRegistration({
-  key: 'customer-editor',
-  label: editorLabel,
-  isOpen: editorOpen,
-  model: form,
-  requiredPermission: editorRequiredPermission,
-})
-
-const filteredRows = computed(() => store.customers.filter((item) => {
-  const keyword = filters.keyword.trim().toLowerCase()
-  const matchesKeyword = !keyword || [item.name, item.id, item.contact, item.phone, item.creditCode]
-    .some((value) => value.toLowerCase().includes(keyword))
-  return matchesKeyword && (!filters.status || item.status === filters.status) && (!filters.packageName || item.packageName === filters.packageName)
-}))
-const pagedRows = computed(() => filteredRows.value.slice((page.value - 1) * pageSize, page.value * pageSize))
-const metrics = computed(() => [
-  { label: '全部客户', value: store.customers.length, note: '已建立企业档案' },
-  { label: '正常合作', value: store.customers.filter((item) => item.status === '正常').length, note: '当前可正常下单' },
-  { label: '待审核', value: store.pendingCustomers, note: '需要平台处理' },
-  { label: '累计订单', value: store.customers.reduce((total, item) => total + item.orders, 0).toLocaleString(), note: '全部客户历史订单' },
-])
-
-watch(filters, () => { page.value = 1 })
-watch(
-  () => access.can('customer:create'),
-  (canCreate) => {
-    if (canCreate || !editorOpen.value || form.id) return
-    editorOpen.value = false
-    Object.assign(form, emptyForm())
-  },
-  { flush: 'sync' },
-)
-
-function resetFilters() {
-  Object.assign(filters, { keyword: '', status: '', packageName: '' })
-}
-
-function openCreate() {
-  Object.assign(form, emptyForm())
-  captureBaseline()
-  editorOpen.value = true
-}
-
-function openEdit(row: Customer) {
-  Object.assign(form, row)
-  captureBaseline()
-  editorOpen.value = true
-}
-
-function openDetail(row: Customer) {
-  currentCustomer.value = row
-  detailOpen.value = true
-}
-
-function saveCustomer() {
-  if (!form.name.trim() || !form.contact.trim() || !form.phone.trim()) {
-    ElMessage.warning('请填写企业名称、联系人和联系电话')
-    return
-  }
-  store.saveCustomer({ ...form, id: form.id || undefined })
-  editorOpen.value = false
-  ElMessage.success(form.id ? '客户资料已更新' : '客户已创建')
-}
-
-async function toggleStatus(row: Customer) {
-  const target = row.status === '停用' ? '正常' : '停用'
-  try {
-    await ElMessageBox.confirm(`确认将“${row.name}”设置为${target}吗？`, '变更客户状态', {
-      confirmButtonText: '确认变更', cancelButtonText: '取消',
-    })
-    store.setCustomerStatus(row.id, target)
-    ElMessage.success(`客户状态已更新为${target}`)
-  } catch {
-    // 用户取消，不需要反馈。
-  }
-}
-
-function exportCustomers() {
-  ElMessage.success(`已生成 ${filteredRows.value.length} 条客户数据的导出任务`)
-}
-</script>
-
-<template>
-  <div class="business-page">
-    <MetricStrip :items="metrics" />
-
-    <section class="surface-panel filter-panel" aria-label="客户筛选">
-      <div class="filter-fields">
-        <el-input v-model="filters.keyword" clearable placeholder="客户名称、编号、联系人或信用代码" aria-label="客户关键词">
-          <template #prefix><Search :size="16" /></template>
-        </el-input>
-        <el-select v-model="filters.status" clearable placeholder="全部状态" aria-label="客户状态">
-          <el-option label="正常" value="正常" /><el-option label="待审核" value="待审核" /><el-option label="停用" value="停用" />
-        </el-select>
-        <el-select v-model="filters.packageName" clearable placeholder="全部套餐" aria-label="客户套餐">
-          <el-option label="基础版" value="基础版" /><el-option label="专业版" value="专业版" /><el-option label="企业版" value="企业版" />
-        </el-select>
-      </div>
-      <div class="filter-actions">
-        <el-button @click="resetFilters"><RotateCcw :size="16" />重置</el-button>
-        <el-button v-if="!access.usesServerPermissions" @click="exportCustomers"><Download :size="16" />导出</el-button>
-        <el-button v-if="access.can('customer:create')" type="primary" @click="openCreate"><Plus :size="16" />新增客户</el-button>
-      </div>
-    </section>
-
-    <section class="surface-panel table-panel">
-      <header class="panel-heading">
-        <div><h2>客户档案</h2><p>共 {{ filteredRows.length }} 家企业，客户资料与注册审核统一管理。</p></div>
-      </header>
-      <el-table :data="pagedRows" row-key="id" empty-text="没有符合条件的客户">
-        <el-table-column prop="id" label="客户编号" width="96" />
-        <el-table-column label="企业信息" min-width="250">
-          <template #default="{ row }"><div class="primary-cell"><strong>{{ row.name }}</strong><span>{{ row.creditCode }}</span></div></template>
-        </el-table-column>
-        <el-table-column label="联系人" min-width="150"><template #default="{ row }"><div class="primary-cell"><strong>{{ row.contact }}</strong><span>{{ row.phone }}</span></div></template></el-table-column>
-        <el-table-column prop="sales" label="销售负责人" width="108" />
-        <el-table-column label="套餐/账期" width="130"><template #default="{ row }"><div class="primary-cell"><strong>{{ row.packageName }}</strong><span>{{ row.period }} 天账期</span></div></template></el-table-column>
-        <el-table-column prop="orders" label="订单数" width="86" align="right" />
-        <el-table-column label="状态" width="96"><template #default="{ row }"><StatusBadge :status="row.status" /></template></el-table-column>
-        <el-table-column label="操作" width="246" fixed="right">
-          <template #default="{ row }">
-            <div class="table-actions">
-              <el-button link type="primary" @click="openDetail(row as Customer)"><Eye :size="15" />详情</el-button>
-              <el-button v-if="!access.usesServerPermissions" link type="primary" @click="openEdit(row as Customer)"><Pencil :size="15" />编辑</el-button>
-              <el-button v-if="!access.usesServerPermissions && row.status !== '待审核'" link :type="row.status === '停用' ? 'success' : 'danger'" @click="toggleStatus(row as Customer)">{{ row.status === '停用' ? '启用' : '停用' }}</el-button>
-            </div>
-          </template>
-        </el-table-column>
-      </el-table>
-      <footer class="table-footer"><span>显示 {{ pagedRows.length }} 条，共 {{ filteredRows.length }} 条</span><el-pagination v-model:current-page="page" :page-size="pageSize" :total="filteredRows.length" layout="prev, pager, next" /></footer>
-    </section>
-
-    <el-drawer v-model="editorOpen" :title="form.id ? '编辑客户' : '新增客户'" size="680px" class="business-drawer editor-drawer" :modal="false" :close-on-click-modal="false">
-      <el-form label-position="top" class="drawer-form">
-        <div class="form-section"><h3>企业信息</h3><div class="form-grid two-cols">
-          <el-form-item label="企业名称" required><el-input v-model="form.name" placeholder="请输入营业执照上的企业名称" /></el-form-item>
-          <el-form-item label="统一社会信用代码"><el-input v-model="form.creditCode" placeholder="18 位统一社会信用代码" /></el-form-item>
-          <el-form-item label="套餐"><el-select v-model="form.packageName"><el-option label="基础版" value="基础版" /><el-option label="专业版" value="专业版" /><el-option label="企业版" value="企业版" /></el-select></el-form-item>
-          <el-form-item label="账期"><el-input-number v-model="form.period" :min="0" :max="180" controls-position="right" /><span class="field-suffix">天</span></el-form-item>
-          <el-form-item label="状态"><el-radio-group v-model="form.status"><el-radio-button label="正常" value="正常" /><el-radio-button label="待审核" value="待审核" /><el-radio-button label="停用" value="停用" /></el-radio-group></el-form-item>
-          <el-form-item label="销售负责人"><el-select v-model="form.sales" filterable allow-create placeholder="请选择或输入负责人"><el-option v-for="name in ['王建国','李秀英','张志强','刘德海','陈美玲']" :key="name" :label="name" :value="name" /></el-select></el-form-item>
-        </div></div>
-        <div class="form-section"><h3>联系资料</h3><div class="form-grid two-cols">
-          <el-form-item label="联系人" required><el-input v-model="form.contact" /></el-form-item>
-          <el-form-item label="联系电话" required><el-input v-model="form.phone" /></el-form-item>
-          <el-form-item label="联系邮箱"><el-input v-model="form.email" /></el-form-item>
-          <el-form-item label="注册地址"><el-input v-model="form.address" /></el-form-item>
-        </div><el-form-item label="内部备注"><el-input v-model="form.remark" type="textarea" :rows="3" placeholder="仅平台内部可见" /></el-form-item></div>
-      </el-form>
-      <template #footer><div class="drawer-footer"><el-button @click="editorOpen = false">取消</el-button><el-button v-if="!access.usesServerPermissions && (form.id || access.can('customer:create'))" type="primary" @click="saveCustomer">保存客户</el-button></div></template>
-    </el-drawer>
-
-    <el-drawer v-model="detailOpen" title="客户详情" size="620px" class="business-drawer">
-      <template v-if="currentCustomer">
-        <div class="detail-identity"><span>{{ currentCustomer.name.slice(0, 1) }}</span><div><h2>{{ currentCustomer.name }}</h2><p>{{ currentCustomer.id }} · {{ currentCustomer.creditCode }}</p></div><StatusBadge :status="currentCustomer.status" /></div>
-        <MetricStrip :items="[{ label: '历史订单', value: currentCustomer.orders }, { label: '账期', value: `${currentCustomer.period} 天` }, { label: '合作时长', value: currentCustomer.joinedAt.slice(0,4) + ' 至今' }]" />
-        <div class="detail-section"><h3>基本资料</h3><el-descriptions :column="1" border><el-descriptions-item label="套餐">{{ currentCustomer.packageName }}</el-descriptions-item><el-descriptions-item label="销售负责人">{{ currentCustomer.sales }}</el-descriptions-item><el-descriptions-item label="联系人">{{ currentCustomer.contact }} · {{ currentCustomer.phone }}</el-descriptions-item><el-descriptions-item label="邮箱">{{ currentCustomer.email }}</el-descriptions-item><el-descriptions-item label="地址">{{ currentCustomer.address }}</el-descriptions-item><el-descriptions-item label="入驻时间">{{ currentCustomer.joinedAt }}</el-descriptions-item></el-descriptions></div>
-        <div class="detail-section"><h3>内部备注</h3><p class="detail-note">{{ currentCustomer.remark || '暂无内部备注。' }}</p></div>
-      </template>
-      <template #footer><div class="drawer-footer"><el-button @click="detailOpen = false">关闭</el-button><el-button v-if="!access.usesServerPermissions" type="primary" @click="currentCustomer && openEdit(currentCustomer)">编辑资料</el-button></div></template>
-    </el-drawer>
-  </div>
-</template>
diff --git a/src/views/EnterpriseReviewsView.test.ts b/src/views/EnterpriseReviewsView.test.ts
deleted file mode 100644
index 3e764ccd..00000000
--- a/src/views/EnterpriseReviewsView.test.ts
+++ /dev/null
@@ -1,160 +0,0 @@
-import ElementPlus from 'element-plus'
-import { createPinia, setActivePinia } from 'pinia'
-import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import {
-  approveEnterpriseReview,
-  downloadTenantQualification,
-  listEnterpriseReviews,
-  listTenantQualifications,
-  rejectEnterpriseReview,
-  type EnterpriseReview,
-  type PlatformTenantQualification,
-} from '@/api/platformIam'
-import { useAccessPreviewStore } from '@/stores/accessPreview'
-import EnterpriseReviewsView from './EnterpriseReviewsView.vue'
-
-vi.mock('@/api/platformIam', () => ({
-  listEnterpriseReviews: vi.fn(),
-  listTenantQualifications: vi.fn(),
-  downloadTenantQualification: vi.fn(),
-  qualificationFileName: vi.fn(() => 'test.png'),
-  approveEnterpriseReview: vi.fn(),
-  rejectEnterpriseReview: vi.fn(),
-}))
-
-class ResizeObserverStub implements ResizeObserver {
-  observe() {}
-  unobserve() {}
-  disconnect() {}
-}
-
-const pendingReview: EnterpriseReview = {
-  id: 202607290005,
-  tenantId: 202607290002,
-  tenantName: '深圳测试跨境科技有限公司',
-  tenantCode: 'TEN202607290002',
-  qualificationId: 202607290004,
-  qualificationType: 'BUSINESS_LICENSE',
-  certificateNo: '91440300XXXXXXXXXX',
-  documentUrl: '/api/merchant/v1/files/qualifications/test.png',
-  contactName: '张三',
-  contactPhone: '13800138000',
-  contactEmail: 'test01@example.com',
-  submittedAt: '2026-07-29T10:00:00Z',
-  status: 'PENDING',
-}
-
-const pendingQualification: PlatformTenantQualification = {
-  id: 202607290004,
-  tenantId: pendingReview.tenantId,
-  qualificationType: 'BUSINESS_LICENSE',
-  certificateNo: '91440300XXXXXXXXXX',
-  documentUrl: '/api/merchant/v1/files/qualifications/test.png',
-  status: 'PENDING',
-  reviewComment: null,
-}
-
-async function mountView() {
-  const pinia = createPinia()
-  setActivePinia(pinia)
-  useAccessPreviewStore().initializeAfterLogin()
-  const wrapper = mount(EnterpriseReviewsView, {
-    attachTo: document.body,
-    global: { plugins: [pinia, ElementPlus] },
-  })
-  await flushPromises()
-  return wrapper
-}
-
-function buttonByText(text: string) {
-  return [...document.querySelectorAll<HTMLButtonElement>('button')]
-    .find((button) => button.textContent?.trim() === text)
-}
-
-enableAutoUnmount(afterEach)
-
-describe('EnterpriseReviewsView', () => {
-  beforeEach(() => {
-    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
-    vi.mocked(listEnterpriseReviews).mockReset()
-    vi.mocked(listTenantQualifications).mockReset()
-    vi.mocked(downloadTenantQualification).mockReset()
-    vi.mocked(approveEnterpriseReview).mockReset()
-    vi.mocked(rejectEnterpriseReview).mockReset()
-    document.body.innerHTML = ''
-  })
-
-  it('renders an honest empty state from the real review endpoint', async () => {
-    vi.mocked(listEnterpriseReviews).mockResolvedValue([])
-
-    const wrapper = await mountView()
-
-    expect(listEnterpriseReviews).toHaveBeenCalledTimes(1)
-    expect(wrapper.text()).toContain('暂无待审核企业')
-    expect(wrapper.text()).toContain('共 0 条待审记录')
-  })
-
-  it('shows review identity and submits approval with the review id', async () => {
-    vi.mocked(listEnterpriseReviews).mockResolvedValue([pendingReview])
-    vi.mocked(approveEnterpriseReview).mockResolvedValue(undefined)
-
-    const wrapper = await mountView()
-    expect(wrapper.text()).toContain('深圳测试跨境科技有限公司')
-    expect(wrapper.text()).toContain('91440300XXXXXXXXXX')
-
-    const approve = buttonByText('通过')
-    expect(approve).toBeDefined()
-    approve?.click()
-    await flushPromises()
-
-    const confirm = buttonByText('确认通过')
-    expect(confirm).toBeDefined()
-    confirm?.click()
-    await flushPromises()
-
-    expect(approveEnterpriseReview).toHaveBeenCalledWith(
-      pendingReview.id,
-      '营业执照清晰，企业资料审核通过',
-    )
-    expect(wrapper.text()).toContain('暂无待审核企业')
-    expect(wrapper.text()).toContain('共 0 条待审记录')
-  })
-
-  it('loads tenant qualifications when the reviewer opens the detail drawer', async () => {
-    vi.mocked(listEnterpriseReviews).mockResolvedValue([pendingReview])
-    vi.mocked(listTenantQualifications).mockResolvedValue([pendingQualification])
-
-    const wrapper = await mountView()
-    buttonByText('详情')?.click()
-    await flushPromises()
-
-    expect(listTenantQualifications).toHaveBeenCalledWith(pendingReview.tenantId)
-    expect(wrapper.text()).toContain('信用代码：91440300XXXXXXXXXX')
-    expect(buttonByText('查看文件')).toBeDefined()
-  })
-
-  it('keeps qualification loading recoverable without using a direct file link', async () => {
-    vi.mocked(listEnterpriseReviews).mockResolvedValue([pendingReview])
-    vi.mocked(listTenantQualifications).mockRejectedValue(new Error('qualification unavailable'))
-
-    const wrapper = await mountView()
-    buttonByText('详情')?.click()
-    await flushPromises()
-
-    expect(wrapper.text()).toContain('资质暂时无法加载')
-    expect(wrapper.text()).toContain('qualification unavailable')
-    expect(wrapper.find('a[href*="qualifications"]').exists()).toBe(false)
-    expect(buttonByText('重新加载')).toBeDefined()
-  })
-
-  it('keeps the page recoverable when the endpoint fails', async () => {
-    vi.mocked(listEnterpriseReviews).mockRejectedValue(new Error('IAM unavailable'))
-
-    const wrapper = await mountView()
-
-    expect(wrapper.get('[role="alert"]').text()).toContain('审核列表暂时无法加载')
-    expect(wrapper.get('[role="alert"]').text()).toContain('IAM unavailable')
-    expect(buttonByText('重新加载')).toBeDefined()
-  })
-})
diff --git a/src/views/EnterpriseReviewsView.vue b/src/views/EnterpriseReviewsView.vue
deleted file mode 100644
index 7364860b..00000000
--- a/src/views/EnterpriseReviewsView.vue
+++ /dev/null
@@ -1,360 +0,0 @@
-<script setup lang="ts">
-import { computed, onBeforeUnmount, onMounted, reactive, ref, watch } from 'vue'
-import { ElMessage } from 'element-plus'
-import { Eye, FileCheck2, RefreshCw, Search, ShieldCheck, ShieldX } from '@lucide/vue'
-import {
-  approveEnterpriseReview,
-  downloadTenantQualification,
-  listEnterpriseReviews,
-  listTenantQualifications,
-  qualificationFileName,
-  rejectEnterpriseReview,
-  type EnterpriseReview,
-  type PlatformTenantQualification,
-} from '@/api/platformIam'
-import { getApiErrorDetails, getApiErrorMessage, type ApiErrorDetails } from '@/api/http'
-import ApiErrorMeta from '@/components/ApiErrorMeta.vue'
-import MetricStrip from '@/components/MetricStrip.vue'
-import { useAccessPreviewStore } from '@/stores/accessPreview'
-
-const access = useAccessPreviewStore()
-const loading = ref(false)
-const loadError = ref<ApiErrorDetails | null>(null)
-const reviews = ref<EnterpriseReview[]>([])
-const keyword = ref('')
-const detailOpen = ref(false)
-const selectedReview = ref<EnterpriseReview | null>(null)
-const qualifications = ref<PlatformTenantQualification[]>([])
-const qualificationsLoading = ref(false)
-const qualificationsError = ref<ApiErrorDetails | null>(null)
-const previewLoadingId = ref<string>()
-const previewOpen = ref(false)
-const previewUrl = ref('')
-const previewName = ref('')
-const decisionOpen = ref(false)
-const submitting = ref(false)
-const decision = reactive({ type: 'approve' as 'approve' | 'reject', comment: '' })
-
-const filteredReviews = computed(() => {
-  const query = keyword.value.trim().toLowerCase()
-  if (!query) return reviews.value
-  return reviews.value.filter((review) => [
-    review.tenantName,
-    review.tenantCode,
-    review.certificateNo,
-    String(review.tenantId),
-    String(review.id),
-  ].some((value) => value?.toLowerCase().includes(query)))
-})
-
-const metrics = computed(() => [
-  { label: '待审核企业', value: reviews.value.length, note: '当前需要平台处理' },
-  { label: '营业执照', value: reviews.value.filter((item) => item.qualificationType === 'BUSINESS_LICENSE').length, note: '本期待核验资质' },
-  { label: '可通过', value: access.can('platform:customer:approve') ? reviews.value.length : 0, note: '按当前账号权限' },
-  { label: '当前结果', value: filteredReviews.value.length, note: keyword.value ? '符合搜索条件' : '全部待审记录' },
-])
-
-function displayText(value: unknown) {
-  return typeof value === 'string' && value.trim() ? value : '—'
-}
-
-function formatDate(value?: string | null) {
-  if (!value) return '—'
-  const date = new Date(value)
-  return Number.isNaN(date.getTime()) ? value : date.toLocaleString('zh-CN', { hour12: false })
-}
-
-function qualificationName(value?: string | null) {
-  return value === 'BUSINESS_LICENSE' ? '营业执照' : displayText(value)
-}
-
-function qualificationStatus(status: PlatformTenantQualification['status']) {
-  if (status === 'APPROVED') return { label: '已通过', tone: 'is-success' }
-  if (status === 'REJECTED') return { label: '已驳回', tone: 'is-danger' }
-  return { label: '待审核', tone: 'is-warning' }
-}
-
-async function loadReviews() {
-  loading.value = true
-  loadError.value = null
-  try {
-    reviews.value = await listEnterpriseReviews()
-  } catch (error) {
-    loadError.value = getApiErrorDetails(error, '审核列表加载失败，请稍后重试')
-  } finally {
-    loading.value = false
-  }
-}
-
-async function loadSelectedQualifications() {
-  const tenantId = selectedReview.value?.tenantId
-  if (!tenantId) return
-  qualificationsLoading.value = true
-  qualificationsError.value = null
-  qualifications.value = []
-  try {
-    const result = await listTenantQualifications(tenantId)
-    if (selectedReview.value?.tenantId === tenantId) qualifications.value = result
-  } catch (error) {
-    if (selectedReview.value?.tenantId === tenantId) {
-      qualificationsError.value = getApiErrorDetails(error, '资质列表加载失败，请稍后重试')
-    }
-  } finally {
-    if (selectedReview.value?.tenantId === tenantId) qualificationsLoading.value = false
-  }
-}
-
-function openDetail(review: EnterpriseReview) {
-  selectedReview.value = review
-  detailOpen.value = true
-  void loadSelectedQualifications()
-}
-
-function clearPreviewUrl() {
-  if (previewUrl.value) URL.revokeObjectURL(previewUrl.value)
-  previewUrl.value = ''
-  previewName.value = ''
-}
-
-async function previewQualification(qualification: PlatformTenantQualification) {
-  const tenantId = selectedReview.value?.tenantId
-  if (!tenantId || !qualification.documentUrl) return
-  previewLoadingId.value = String(qualification.id)
-  try {
-    const blob = await downloadTenantQualification(tenantId, qualification.documentUrl)
-    if (!blob.size) throw new Error('资质文件内容为空')
-    clearPreviewUrl()
-    previewUrl.value = URL.createObjectURL(blob)
-    previewName.value = qualificationFileName(qualification.documentUrl)
-    previewOpen.value = true
-  } catch (error) {
-    ElMessage.error(getApiErrorMessage(error, '资质文件加载失败，请稍后重试'))
-  } finally {
-    previewLoadingId.value = undefined
-  }
-}
-
-function openDecision(review: EnterpriseReview, type: 'approve' | 'reject') {
-  selectedReview.value = review
-  decision.type = type
-  decision.comment = type === 'approve' ? '营业执照清晰，企业资料审核通过' : ''
-  decisionOpen.value = true
-}
-
-async function submitDecision() {
-  const review = selectedReview.value
-  if (!review || submitting.value) return
-  if (!decision.comment.trim()) {
-    ElMessage.warning(decision.type === 'approve' ? '请填写审核说明' : '请填写驳回原因')
-    return
-  }
-
-  submitting.value = true
-  try {
-    if (decision.type === 'approve') {
-      await approveEnterpriseReview(review.id, decision.comment.trim())
-    } else {
-      await rejectEnterpriseReview(review.id, decision.comment.trim())
-    }
-    reviews.value = reviews.value.filter((item) => item.id !== review.id)
-    decisionOpen.value = false
-    detailOpen.value = false
-    ElMessage.success(decision.type === 'approve' ? '企业资料已审核通过' : '企业资料已驳回')
-  } catch (error) {
-    ElMessage.error(getApiErrorMessage(error, '审核提交失败，请稍后重试'))
-  } finally {
-    submitting.value = false
-  }
-}
-
-watch(
-  () => [access.can('platform:customer:approve'), access.can('platform:customer:reject')],
-  ([canApprove, canReject]) => {
-    if ((decision.type === 'approve' && !canApprove) || (decision.type === 'reject' && !canReject)) {
-      decisionOpen.value = false
-    }
-  },
-)
-
-watch(previewOpen, (open) => {
-  if (!open) clearPreviewUrl()
-})
-
-watch(detailOpen, (open) => {
-  if (!open) previewOpen.value = false
-})
-
-onMounted(loadReviews)
-onBeforeUnmount(clearPreviewUrl)
-</script>
-
-<template>
-  <!-- THESIS: 把企业审核组织成一条清晰的待办队列，而不是混在客户档案的模拟状态里。
-  OWN-WORLD: 延续 Admin 的海军蓝框架、白色数据面板、紧凑表格和克制状态色。
-  STORY: 审核员先识别待审企业，再核对营业执照与联系人，最后留下明确的通过或驳回意见。
-  FIRST VIEWPORT: 摘要、搜索和真实待审列表连续呈现，详情从右侧展开，决策在受保护的确认对话框中完成。
-  FORM: 现有 Operate 页面体系的直接扩展，不改变全局导航与品牌语言。
-  FINISH: unreviewed and undocumented is unfinished; this build ends with the finish review, the verdict, and DESIGN.md -->
-  <div class="business-page enterprise-review-page">
-    <MetricStrip :items="metrics" />
-
-    <section class="surface-panel review-toolbar" aria-label="企业审核筛选">
-      <el-input v-model="keyword" clearable placeholder="企业名称、企业编号、信用代码或审核单号" aria-label="企业审核关键词">
-        <template #prefix><Search :size="16" /></template>
-      </el-input>
-      <el-button :loading="loading" @click="loadReviews"><RefreshCw :size="16" />刷新</el-button>
-    </section>
-
-    <section v-if="loadError" class="surface-panel review-error" role="alert">
-      <ShieldX :size="22" />
-      <div><strong>审核列表暂时无法加载</strong><p>{{ loadError.message }}</p><ApiErrorMeta :details="loadError" /></div>
-      <el-button type="primary" @click="loadReviews">重新加载</el-button>
-    </section>
-
-    <section v-else class="surface-panel table-panel" :aria-busy="loading">
-      <header class="panel-heading">
-        <div><h2>企业资料审核</h2><p>仅展示后端返回的待审核记录，提交审核时使用审核单 ID。</p></div>
-      </header>
-      <el-table v-loading="loading" :data="filteredReviews" row-key="id" empty-text="暂无待审核企业">
-        <el-table-column label="企业" min-width="230">
-          <template #default="{ row }">
-            <div class="primary-cell"><strong>{{ displayText((row as EnterpriseReview).tenantName) }}</strong><span>{{ displayText((row as EnterpriseReview).tenantCode) }} · 租户 {{ (row as EnterpriseReview).tenantId }}</span></div>
-          </template>
-        </el-table-column>
-        <el-table-column label="资质" min-width="210">
-          <template #default="{ row }">
-            <div class="primary-cell"><strong>{{ qualificationName((row as EnterpriseReview).qualificationType) }}</strong><span>{{ displayText((row as EnterpriseReview).certificateNo) }}</span></div>
-          </template>
-        </el-table-column>
-        <el-table-column label="联系人" min-width="180">
-          <template #default="{ row }">
-            <div class="primary-cell"><strong>{{ displayText((row as EnterpriseReview).contactName) }}</strong><span>{{ displayText((row as EnterpriseReview).contactPhone) }}</span></div>
-          </template>
-        </el-table-column>
-        <el-table-column label="提交时间" min-width="175"><template #default="{ row }">{{ formatDate((row as EnterpriseReview).submittedAt ?? (row as EnterpriseReview).createdAt) }}</template></el-table-column>
-        <el-table-column label="状态" width="110"><template #default><span class="status-badge is-warning"><i />待审核</span></template></el-table-column>
-        <el-table-column label="操作" width="250" fixed="right">
-          <template #default="{ row }">
-            <div class="table-actions">
-              <el-button link type="primary" @click="openDetail(row as EnterpriseReview)"><Eye :size="15" />详情</el-button>
-              <el-button v-if="access.can('platform:customer:approve')" link type="success" @click="openDecision(row as EnterpriseReview, 'approve')"><ShieldCheck :size="15" />通过</el-button>
-              <el-button v-if="access.can('platform:customer:reject')" link type="danger" @click="openDecision(row as EnterpriseReview, 'reject')"><ShieldX :size="15" />驳回</el-button>
-            </div>
-          </template>
-        </el-table-column>
-      </el-table>
-      <footer class="table-footer"><span>共 {{ filteredReviews.length }} 条待审记录</span><span v-if="keyword">已按关键词筛选</span></footer>
-    </section>
-
-    <el-drawer v-model="detailOpen" title="企业审核详情" size="620px" class="business-drawer">
-      <template v-if="selectedReview">
-        <div class="detail-identity">
-          <span><FileCheck2 :size="20" /></span>
-          <div><h2>{{ displayText(selectedReview.tenantName) }}</h2><p>审核单 {{ selectedReview.id }} · 租户 {{ selectedReview.tenantId }}</p></div>
-          <span class="status-badge is-warning"><i />待审核</span>
-        </div>
-        <section class="detail-section">
-          <h3>企业与联系人</h3>
-          <el-descriptions :column="1" border>
-            <el-descriptions-item label="企业编号">{{ displayText(selectedReview.tenantCode) }}</el-descriptions-item>
-            <el-descriptions-item label="联系人">{{ displayText(selectedReview.contactName) }}</el-descriptions-item>
-            <el-descriptions-item label="联系电话">{{ displayText(selectedReview.contactPhone) }}</el-descriptions-item>
-            <el-descriptions-item label="联系邮箱">{{ displayText(selectedReview.contactEmail) }}</el-descriptions-item>
-          </el-descriptions>
-        </section>
-        <section class="detail-section">
-          <h3>资质文件</h3>
-          <div class="qualification-state" :aria-busy="qualificationsLoading">
-            <div v-if="qualificationsLoading" v-loading="true" class="qualification-loading">正在读取该企业资质…</div>
-            <div v-else-if="qualificationsError" class="qualification-error" role="alert">
-              <div><strong>资质暂时无法加载</strong><p>{{ qualificationsError.message }}</p><ApiErrorMeta :details="qualificationsError" /></div>
-              <el-button type="primary" plain @click="loadSelectedQualifications">重新加载</el-button>
-            </div>
-            <el-empty v-else-if="qualifications.length === 0" :image-size="64" description="该企业暂未提交资质" />
-            <div v-else class="qualification-list">
-              <article v-for="qualification in qualifications" :key="qualification.id" class="qualification-item">
-                <div class="qualification-copy">
-                  <div><strong>{{ qualificationName(qualification.qualificationType) }}</strong><span class="status-badge" :class="qualificationStatus(qualification.status).tone"><i />{{ qualificationStatus(qualification.status).label }}</span></div>
-                  <p>信用代码：{{ displayText(qualification.certificateNo) }}</p>
-                  <p v-if="qualification.reviewComment">审核意见：{{ qualification.reviewComment }}</p>
-                </div>
-                <el-button
-                  type="primary"
-                  plain
-                  :disabled="!qualification.documentUrl"
-                  :loading="previewLoadingId === String(qualification.id)"
-                  @click="previewQualification(qualification)"
-                ><Eye :size="15" />查看文件</el-button>
-              </article>
-            </div>
-          </div>
-          <p class="detail-note">请核对企业名称、统一社会信用代码和营业执照内容。通过后企业获得下单资格；驳回时必须说明原因。</p>
-        </section>
-      </template>
-      <template #footer>
-        <div class="drawer-footer">
-          <el-button @click="detailOpen = false">关闭</el-button>
-          <el-button v-if="selectedReview && access.can('platform:customer:reject')" type="danger" plain @click="openDecision(selectedReview, 'reject')">驳回</el-button>
-          <el-button v-if="selectedReview && access.can('platform:customer:approve')" type="success" @click="openDecision(selectedReview, 'approve')">审核通过</el-button>
-        </div>
-      </template>
-    </el-drawer>
-
-    <el-dialog v-model="previewOpen" :title="previewName || '查看资质文件'" width="min(860px, calc(100vw - 28px))" class="qualification-preview-dialog" destroy-on-close>
-      <div class="qualification-preview">
-        <img v-if="previewUrl" :src="previewUrl" :alt="`${previewName}预览`" />
-      </div>
-      <template #footer><el-button @click="previewOpen = false">关闭预览</el-button></template>
-    </el-dialog>
-
-    <el-dialog v-model="decisionOpen" :title="decision.type === 'approve' ? '确认审核通过' : '确认驳回企业资料'" width="min(520px, calc(100vw - 28px))" class="review-decision-dialog" :close-on-click-modal="false">
-      <div v-if="selectedReview" class="decision-summary">
-        <strong>{{ displayText(selectedReview.tenantName) }}</strong>
-        <span>审核单 {{ selectedReview.id }}</span>
-      </div>
-      <el-form label-position="top">
-        <el-form-item :label="decision.type === 'approve' ? '审核说明' : '驳回原因'" required>
-          <el-input v-model="decision.comment" type="textarea" :rows="4" maxlength="300" show-word-limit :placeholder="decision.type === 'approve' ? '请填写审核通过说明' : '请明确说明需要企业修改的内容'" />
-        </el-form-item>
-      </el-form>
-      <template #footer>
-        <div class="drawer-footer">
-          <el-button :disabled="submitting" @click="decisionOpen = false">取消</el-button>
-          <el-button :type="decision.type === 'approve' ? 'success' : 'danger'" :loading="submitting" @click="submitDecision">{{ decision.type === 'approve' ? '确认通过' : '确认驳回' }}</el-button>
-        </div>
-      </template>
-    </el-dialog>
-  </div>
-</template>
-
-<style scoped>
-.review-toolbar { display: flex; align-items: center; justify-content: space-between; gap: 12px; padding: 14px 16px; }
-.review-toolbar .el-input { width: min(460px, 100%); }
-.review-error { display: grid; grid-template-columns: auto minmax(0, 1fr) auto; align-items: center; gap: 14px; padding: 18px 20px; border-color: #fecdca; background: #fffafa; color: #b42318; }
-.review-error strong { color: #7a271a; font-size: 13px; }
-.review-error p { margin: 4px 0 0; color: #b54708; font-size: 12px; }
-.qualification-state { min-height: 112px; }
-.qualification-loading { display: grid; min-height: 112px; place-items: center; color: var(--cc-muted); font-size: 12px; }
-.qualification-error { display: flex; min-width: 0; align-items: center; justify-content: space-between; gap: 16px; padding: 14px; border: 1px solid #fecdca; border-radius: 6px; background: #fffafa; }
-.qualification-error strong { color: #7a271a; font-size: 13px; }
-.qualification-error p { margin: 4px 0 0; color: #b54708; font-size: 12px; overflow-wrap: anywhere; }
-.qualification-list { display: flex; flex-direction: column; gap: 10px; }
-.qualification-item { display: flex; min-width: 0; align-items: center; justify-content: space-between; gap: 16px; padding: 14px; border: 1px solid var(--cc-border); border-radius: 6px; background: #fff; }
-.qualification-copy { min-width: 0; }
-.qualification-copy > div { display: flex; min-width: 0; align-items: center; gap: 8px; }
-.qualification-copy strong { overflow-wrap: anywhere; font-size: 13px; }
-.qualification-copy p { margin: 5px 0 0; color: var(--cc-muted); font-size: 11px; line-height: 1.55; overflow-wrap: anywhere; }
-.qualification-preview { display: grid; max-height: min(70vh, 760px); min-height: 240px; place-items: center; overflow: auto; border: 1px solid var(--cc-border); border-radius: 6px; background: #f8fafc; }
-.qualification-preview img { display: block; max-width: 100%; height: auto; }
-.decision-summary { display: flex; align-items: center; justify-content: space-between; gap: 12px; margin-bottom: 18px; padding: 12px 14px; border-radius: 8px; background: #f8fafc; }
-.decision-summary strong { color: #172033; font-size: 13px; }
-.decision-summary span { color: var(--cc-muted); font-size: 11px; }
-@media (max-width: 720px) {
-  .review-toolbar { align-items: stretch; flex-direction: column; }
-  .review-toolbar .el-input { width: 100%; }
-  .review-error { grid-template-columns: auto minmax(0, 1fr); }
-  .review-error .el-button { grid-column: 1 / -1; min-height: 44px; }
-  .qualification-error, .qualification-item { align-items: stretch; flex-direction: column; }
-  .qualification-error .el-button, .qualification-item .el-button { min-height: 44px; }
-}
-</style>
diff --git a/src/views/ExpressCompaniesView.test.ts b/src/views/ExpressCompaniesView.test.ts
deleted file mode 100644
index e8bd925a..00000000
--- a/src/views/ExpressCompaniesView.test.ts
+++ /dev/null
@@ -1,78 +0,0 @@
-import ElementPlus from 'element-plus'
-import { createPinia, setActivePinia } from 'pinia'
-import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { nextTick } from 'vue'
-import ExpressCompaniesView from './ExpressCompaniesView.vue'
-
-class ResizeObserverStub implements ResizeObserver {
-  observe() {}
-  unobserve() {}
-  disconnect() {}
-}
-
-async function mountView() {
-  const pinia = createPinia()
-  setActivePinia(pinia)
-  const wrapper = mount(ExpressCompaniesView, {
-    attachTo: document.body,
-    global: { plugins: [pinia, ElementPlus] },
-  })
-  await flushPromises()
-  return wrapper
-}
-
-async function filterByKeyword(value: string) {
-  const input = document.querySelector<HTMLInputElement>('input[placeholder="公司名称、编码、官网或电话"]')
-  expect(input).not.toBeNull()
-  if (!input) return
-  input.value = value
-  input.dispatchEvent(new Event('input', { bubbles: true }))
-  await nextTick()
-}
-
-enableAutoUnmount(afterEach)
-
-describe('ExpressCompaniesView', () => {
-  beforeEach(() => {
-    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
-    document.body.innerHTML = ''
-  })
-
-  it('renders the prototype-backed company records and public fields', async () => {
-    const wrapper = await mountView()
-
-    expect(wrapper.text()).toContain('DHL')
-    expect(wrapper.text()).toContain('www.dhl.com')
-    expect(wrapper.text()).toContain('95380')
-    expect(wrapper.text()).toContain('已终止')
-    const actions = wrapper.findAll('button').map((button) => button.text().trim())
-    expect(actions).not.toContain('新增')
-    expect(actions).not.toContain('编辑')
-  })
-
-  it('filters by company name or code and renders an actionable empty state', async () => {
-    const wrapper = await mountView()
-
-    await filterByKeyword('YTO')
-    expect(wrapper.text()).toContain('圆通速递')
-    expect(wrapper.text()).not.toContain('顺丰速运')
-
-    await filterByKeyword('不存在的公司')
-    expect(wrapper.text()).toContain('没有符合条件的快递公司')
-    expect(wrapper.text()).toContain('共 0 条')
-  })
-
-  it('opens a detail drawer without exposing maintenance actions to an unauthorized role', async () => {
-    const wrapper = await mountView()
-    const detail = wrapper.findAll('button').find((button) => button.text().trim() === '详情')
-    expect(detail).toBeDefined()
-
-    await detail?.trigger('click')
-    await flushPromises()
-
-    expect(document.body.textContent).toContain('快递公司详情')
-    expect(document.body.textContent).toContain('公开联系信息')
-    expect(document.body.textContent).not.toContain('保存快递公司')
-  })
-})
diff --git a/src/views/ExpressCompaniesView.vue b/src/views/ExpressCompaniesView.vue
deleted file mode 100644
index 70d355ed..00000000
--- a/src/views/ExpressCompaniesView.vue
+++ /dev/null
@@ -1,153 +0,0 @@
-<script setup lang="ts">
-import { computed, reactive, ref, watch } from 'vue'
-import { ElMessage, ElMessageBox } from 'element-plus'
-import { ExternalLink, FileUp, Pencil, Phone, Plus, RotateCcw, Search, Truck } from '@lucide/vue'
-import MetricStrip from '@/components/MetricStrip.vue'
-import StaticBatchImportDialog from '@/components/StaticBatchImportDialog.vue'
-import StatusBadge from '@/components/StatusBadge.vue'
-import { useUnsavedWorkRegistration } from '@/composables/useUnsavedWorkRegistration'
-import { useAccessPreviewStore } from '@/stores/accessPreview'
-import { useAdminDataStore } from '@/stores/adminData'
-import type { ExpressCompany, ExpressCompanyStatus } from '@/types/admin'
-
-const store = useAdminDataStore()
-const access = useAccessPreviewStore()
-const detailOpen = ref(false)
-const editorOpen = ref(false)
-const importOpen = ref(false)
-const selectedCompany = ref<ExpressCompany | null>(null)
-const page = ref(1)
-const pageSize = 10
-const filters = reactive({ keyword: '', status: '' as ExpressCompanyStatus | '' })
-const emptyForm = (): Omit<ExpressCompany, 'updatedAt'> => ({ id: '', name: '', code: '', website: '', phone: '', status: '合作中', remark: '' })
-const form = reactive(emptyForm())
-const editorLabel = computed(() => form.id ? '编辑快递公司' : '新增快递公司')
-const { captureBaseline } = useUnsavedWorkRegistration({
-  key: 'express-company-editor',
-  label: editorLabel,
-  isOpen: editorOpen,
-  model: form,
-  requiredPermission: computed(() => form.id ? null : 'express-company:write'),
-})
-
-const filteredRows = computed(() => store.expressCompanies.filter((company) => {
-  const keyword = filters.keyword.trim().toLowerCase()
-  const matchesKeyword = !keyword || [company.name, company.code, company.website, company.phone]
-    .some((value) => value.toLowerCase().includes(keyword))
-  return matchesKeyword && (!filters.status || company.status === filters.status)
-}))
-const pagedRows = computed(() => filteredRows.value.slice((page.value - 1) * pageSize, page.value * pageSize))
-const metrics = computed(() => [
-  { label: '全部快递公司', value: store.expressCompanies.length, note: '平台快递档案' },
-  { label: '合作中', value: store.activeExpressCompanies, note: '可新增到履约信息' },
-  { label: '已终止', value: store.expressCompanies.length - store.activeExpressCompanies, note: '历史订单继续展示' },
-  { label: '官网已登记', value: store.expressCompanies.filter((item) => item.website).length, note: '公开查询入口' },
-])
-
-watch(filters, () => { page.value = 1 })
-
-function resetFilters() { filters.keyword = ''; filters.status = '' }
-function openDetail(company: ExpressCompany) { selectedCompany.value = company; detailOpen.value = true }
-function openCreate() { Object.assign(form, emptyForm()); captureBaseline(); editorOpen.value = true }
-function openEdit(company: ExpressCompany) { Object.assign(form, company); captureBaseline(); detailOpen.value = false; editorOpen.value = true }
-function websiteUrl(company: ExpressCompany) { return /^https?:\/\//i.test(company.website) ? company.website : `https://${company.website}` }
-
-function saveCompany() {
-  if (!form.name.trim() || !form.code.trim()) { ElMessage.warning('请填写快递公司名称和稳定编码'); return }
-  try {
-    store.saveExpressCompany({ ...form, id: form.id || undefined })
-    editorOpen.value = false
-    ElMessage.success(form.id ? '快递公司已更新' : '快递公司已创建')
-  } catch (error) {
-    ElMessage.error(error instanceof Error ? error.message : '快递公司保存失败')
-  }
-}
-
-async function toggleStatus(company: ExpressCompany) {
-  const target: ExpressCompanyStatus = company.status === '合作中' ? '已终止' : '合作中'
-  try {
-    await ElMessageBox.confirm(
-      target === '已终止' ? '停用后不能新增到订单履约信息，历史订单仍保留公司名称和编码。' : '启用后可重新用于订单履约信息。',
-      `${target === '已终止' ? '停用' : '启用'}快递公司“${company.name}”`,
-      { confirmButtonText: target === '已终止' ? '确认停用' : '确认启用', cancelButtonText: '取消', type: 'warning' },
-    )
-    store.setExpressCompanyStatus(company.id, target)
-    ElMessage.success(target === '已终止' ? '快递公司已停用' : '快递公司已启用')
-  } catch {
-    // 用户取消，不需要反馈。
-  }
-}
-</script>
-
-<template>
-  <!-- THESIS: 把快递档案升级为可维护、可批量校验的履约主数据，而不是停留在只读名录。
-  OWN-WORLD: 继承 Admin 的白色数据面板、海军蓝导航、紧凑表格、克制状态色和右侧抽屉。
-  STORY: 平台人员筛选档案，维护唯一编码与名称，控制启停，并按标准模板执行整批导入。
-  FIRST VIEWPORT: 摘要、双条件筛选、导入与新增动作、完整名录连续排列。
-  FORM: 现有 Operate 页面结构的深化，详情与编辑分层，导入使用受保护对话框。
-  FINISH: unreviewed and undocumented is unfinished; this build ends with the finish review, the verdict, and DESIGN.md -->
-  <div class="business-page express-company-page">
-    <MetricStrip :items="metrics" />
-
-    <section class="surface-panel filter-panel" aria-label="快递公司筛选">
-      <div class="filter-fields">
-        <el-input v-model="filters.keyword" clearable placeholder="公司名称、编码、官网或电话" aria-label="快递公司关键词"><template #prefix><Search :size="16" /></template></el-input>
-        <el-select v-model="filters.status" clearable placeholder="全部状态" aria-label="合作状态"><el-option label="合作中" value="合作中" /><el-option label="已终止" value="已终止" /></el-select>
-      </div>
-      <div class="filter-actions">
-        <el-button @click="resetFilters"><RotateCcw :size="16" />重置</el-button>
-        <el-button v-if="access.can('express-company:import')" @click="importOpen = true"><FileUp :size="16" />批量导入</el-button>
-        <el-button v-if="access.can('express-company:write')" type="primary" @click="openCreate"><Plus :size="16" />新增快递公司</el-button>
-      </div>
-    </section>
-
-    <section class="surface-panel table-panel">
-      <div class="panel-heading"><div><h2>快递公司名录</h2><p>编码和名称必须唯一；停用后不允许新增引用，历史订单快照不受影响。</p></div></div>
-      <el-table :data="pagedRows" row-key="id" empty-text="没有符合条件的快递公司">
-        <el-table-column label="公司名称" min-width="190"><template #default="{ row }"><div class="express-company-cell"><span><Truck :size="18" /></span><div><strong>{{ (row as ExpressCompany).name }}</strong><small>{{ (row as ExpressCompany).id }} · {{ (row as ExpressCompany).updatedAt }}</small></div></div></template></el-table-column>
-        <el-table-column label="编码" min-width="110"><template #default="{ row }"><code class="code-value">{{ (row as ExpressCompany).code }}</code></template></el-table-column>
-        <el-table-column label="官网" min-width="220"><template #default="{ row }"><a v-if="(row as ExpressCompany).website" class="company-link" :href="websiteUrl(row as ExpressCompany)" target="_blank" rel="noopener noreferrer">{{ (row as ExpressCompany).website }}<ExternalLink :size="14" /></a><span v-else>—</span></template></el-table-column>
-        <el-table-column label="客服电话" min-width="150"><template #default="{ row }"><span class="phone-value"><Phone :size="14" />{{ (row as ExpressCompany).phone || '—' }}</span></template></el-table-column>
-        <el-table-column label="状态" width="100"><template #default="{ row }"><StatusBadge :status="(row as ExpressCompany).status" /></template></el-table-column>
-        <el-table-column label="操作" width="220" fixed="right"><template #default="{ row }"><div class="table-actions"><el-button link type="primary" @click="openDetail(row as ExpressCompany)">详情</el-button><el-button v-if="access.can('express-company:write')" link type="primary" @click="openEdit(row as ExpressCompany)"><Pencil :size="15" />编辑</el-button><el-button v-if="access.can('express-company:write')" link :type="(row as ExpressCompany).status === '合作中' ? 'danger' : 'success'" @click="toggleStatus(row as ExpressCompany)">{{ (row as ExpressCompany).status === '合作中' ? '停用' : '启用' }}</el-button></div></template></el-table-column>
-      </el-table>
-      <div class="table-footer"><span>显示 {{ pagedRows.length }} 条，共 {{ filteredRows.length }} 条</span><el-pagination v-model:current-page="page" :page-size="pageSize" :total="filteredRows.length" layout="prev, pager, next" /></div>
-    </section>
-
-    <el-drawer v-model="editorOpen" :title="form.id ? '编辑快递公司' : '新增快递公司'" size="620px" class="business-drawer editor-drawer" :modal="false" :close-on-click-modal="false">
-      <el-form label-position="top" class="drawer-form"><div class="form-section"><h3>档案信息</h3><div class="form-grid two-cols">
-        <el-form-item label="公司名称" required><el-input v-model="form.name" placeholder="请输入快递公司名称" maxlength="80" /></el-form-item>
-        <el-form-item label="稳定编码" required><el-input v-model="form.code" placeholder="如 SF" maxlength="30" /></el-form-item>
-        <el-form-item label="官方查询网址"><el-input v-model="form.website" placeholder="如 www.sf-express.com" maxlength="160" /></el-form-item>
-        <el-form-item label="客服电话"><el-input v-model="form.phone" maxlength="40" /></el-form-item>
-        <el-form-item label="状态"><el-radio-group v-model="form.status"><el-radio-button label="合作中" value="合作中" /><el-radio-button label="已终止" value="已终止" /></el-radio-group></el-form-item>
-      </div><el-form-item label="内部备注"><el-input v-model="form.remark" type="textarea" :rows="3" maxlength="300" show-word-limit /></el-form-item></div></el-form>
-      <template #footer><div class="drawer-footer"><el-button @click="editorOpen = false">取消</el-button><el-button v-if="access.can('express-company:write')" type="primary" @click="saveCompany">保存快递公司</el-button></div></template>
-    </el-drawer>
-
-    <el-drawer v-model="detailOpen" title="快递公司详情" size="520px" class="business-drawer" :close-on-click-modal="false">
-      <template v-if="selectedCompany"><div class="detail-identity"><span><Truck :size="20" /></span><div><h2>{{ selectedCompany.name }}</h2><p>{{ selectedCompany.code }} · {{ selectedCompany.id }}</p></div><StatusBadge :status="selectedCompany.status" /></div><section class="detail-section"><h3>公开联系信息</h3><dl class="company-detail-list"><div><dt>公司官网</dt><dd><a v-if="selectedCompany.website" class="company-link" :href="websiteUrl(selectedCompany)" target="_blank" rel="noopener noreferrer">{{ selectedCompany.website }}<ExternalLink :size="14" /></a><span v-else>—</span></dd></div><div><dt>客服电话</dt><dd>{{ selectedCompany.phone || '—' }}</dd></div><div><dt>更新时间</dt><dd>{{ selectedCompany.updatedAt }}</dd></div></dl><p class="detail-note">{{ selectedCompany.remark || '暂无内部备注。' }}</p></section></template>
-      <template #footer><div class="drawer-footer"><el-button @click="detailOpen = false">关闭</el-button><el-button v-if="access.can('express-company:write') && selectedCompany" type="primary" @click="openEdit(selectedCompany)">编辑资料</el-button></div></template>
-    </el-drawer>
-
-    <StaticBatchImportDialog v-model="importOpen" entity-label="快递公司" template-url="/templates/express-companies-import-template.xlsx" template-file-name="快递公司导入标准模板-v1.xlsx" />
-  </div>
-</template>
-
-<style scoped>
-.express-company-cell { display: flex; min-width: 0; align-items: center; gap: 10px; }
-.express-company-cell > span { display: grid; width: 34px; height: 34px; flex: 0 0 34px; place-items: center; background: #eef3fa; color: var(--cc-primary); }
-.express-company-cell > div { display: flex; min-width: 0; flex-direction: column; gap: 3px; }
-.express-company-cell strong, .express-company-cell small { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
-.express-company-cell small { color: var(--cc-muted); font-size: 11px; }
-.company-link { display: inline-flex; max-width: 100%; align-items: center; gap: 5px; color: var(--cc-primary); text-decoration: none; overflow-wrap: anywhere; }
-.company-link:hover { text-decoration: underline; }
-.company-link:focus-visible { outline: 3px solid rgba(21, 94, 239, .2); outline-offset: 2px; }
-.phone-value { display: inline-flex; align-items: center; gap: 6px; color: #344054; }
-.phone-value svg { color: var(--cc-muted); }
-.company-detail-list { margin: 0; }
-.company-detail-list > div { display: grid; grid-template-columns: 92px minmax(0, 1fr); gap: 16px; padding: 14px 0; border-bottom: 1px solid var(--cc-border); }
-.company-detail-list dt { color: var(--cc-muted); font-size: 12px; }
-.company-detail-list dd { min-width: 0; margin: 0; color: #172033; font-size: 13px; font-weight: 650; }
-@media (max-width: 420px) { .company-detail-list > div { grid-template-columns: 1fr; gap: 6px; } }
-</style>
diff --git a/src/views/FirstLegOrdersView.vue b/src/views/FirstLegOrdersView.vue
deleted file mode 100644
index 7263990e..00000000
--- a/src/views/FirstLegOrdersView.vue
+++ /dev/null
@@ -1,241 +0,0 @@
-<script setup lang="ts">
-import { computed, reactive, ref, watch } from 'vue'
-import { ElMessage } from 'element-plus'
-import { ClipboardCheck, Download, Eye, PackageCheck, Pencil, Plus, RotateCcw, Search, Ship, UserRoundCheck } from '@lucide/vue'
-import { FIRST_LEG_ORDER_STATUSES } from '@chongchong/shared'
-import MetricStrip from '@/components/MetricStrip.vue'
-import StatusBadge from '@/components/StatusBadge.vue'
-import { useUnsavedWorkRegistration } from '@/composables/useUnsavedWorkRegistration'
-import { useAccessPreviewStore } from '@/stores/accessPreview'
-import { useAdminDataStore } from '@/stores/adminData'
-import type { FirstLegOrder, OrderStatus } from '@/types/admin'
-
-type OrderForm = Omit<FirstLegOrder, 'no' | 'createdAt' | 'timeline'>
-
-const store = useAdminDataStore()
-const access = useAccessPreviewStore()
-const page = ref(1)
-const pageSize = 10
-const editorOpen = ref(false)
-const detailOpen = ref(false)
-const statusDialogOpen = ref(false)
-const deliveryDialogOpen = ref(false)
-const currentOrder = ref<FirstLegOrder | null>(null)
-const selectedRows = ref<FirstLegOrder[]>([])
-const statusTargetIds = ref<string[]>([])
-const dateRange = ref<[string, string] | []>([])
-const filters = reactive({ keyword: '', status: '', mode: '', customerId: '' })
-const statusForm = reactive<{ status: OrderStatus; operator: string; note: string }>({ status: '已受理', operator: '', note: '' })
-const deliveryForm = reactive({ orderId: '', expressCompanyId: '', trackingNo: '', operator: '' })
-
-const emptyForm = (): OrderForm => ({
-  id: '', customerId: '', customerName: '', referenceNo: '', transportMode: '海运整箱 FCL', businessType: '出口',
-  origin: '', destination: '', receivingWarehouseId: '', receivingWarehouseSnapshot: null, container: '40HQ x 1', etd: '', eta: '', amount: 0, currency: 'CNY', status: '草稿',
-  priority: '普通', operator: '未分配', shipper: '', consignee: '', cargoName: '', pieces: 1, weight: 0, volume: 0, remark: '',
-})
-const form = reactive(emptyForm())
-const editorLabel = computed(() => form.id ? '编辑头程订单' : '创建头程订单')
-const editorRequiredPermission = computed(() => form.id ? null : 'first-leg:create')
-const { captureBaseline } = useUnsavedWorkRegistration({
-  key: 'first-leg-order-editor',
-  label: editorLabel,
-  isOpen: editorOpen,
-  model: form,
-  requiredPermission: editorRequiredPermission,
-})
-const statusOptions: OrderStatus[] = FIRST_LEG_ORDER_STATUSES.map((item) => item.label)
-const statusTransitions: Record<OrderStatus, OrderStatus[]> = { 草稿: ['待审核', '已取消'], 待审核: ['已受理', '已取消'], 已受理: ['已订舱', '已取消'], 已订舱: ['运输中', '已取消'], 运输中: ['已完成', '已取消'], 已完成: [], 已取消: [] }
-const availableStatusOptions = computed(() => {
-  if (statusTargetIds.value.length !== 1) return ['已取消'] as OrderStatus[]
-  const order = store.orders.find((item) => item.id === statusTargetIds.value[0])
-  return order ? [order.status, ...statusTransitions[order.status]] : []
-})
-const operatorOptions = computed(() => store.users.filter((item) => item.status === '正常' && ['运营部', '操作部', '平台管理'].includes(item.department)).map((item) => item.name))
-const selectableWarehouses = computed(() => store.warehouses.filter((item) => item.status === 'ACTIVE' || item.id === form.receivingWarehouseId))
-
-const filteredRows = computed(() => store.orders.filter((item) => {
-  const keyword = filters.keyword.trim().toLowerCase()
-  const keywordMatch = !keyword || [item.no, item.customerName, item.referenceNo, item.origin, item.destination].some((value) => value.toLowerCase().includes(keyword))
-  const dateMatch = dateRange.value.length !== 2 || (item.createdAt.slice(0, 10) >= dateRange.value[0] && item.createdAt.slice(0, 10) <= dateRange.value[1])
-  return keywordMatch && dateMatch && (!filters.status || item.status === filters.status) && (!filters.mode || item.transportMode === filters.mode) && (!filters.customerId || item.customerId === filters.customerId)
-}))
-const pagedRows = computed(() => filteredRows.value.slice((page.value - 1) * pageSize, page.value * pageSize))
-const metrics = computed(() => [
-  { label: '全部订单', value: store.orders.length, note: '当前数据范围' },
-  { label: '待审核/受理', value: store.pendingOrders, note: '需要运营处理' },
-  { label: '运输中', value: store.orders.filter((item) => item.status === '运输中').length, note: '正在履约' },
-  { label: '应收金额', value: `¥${store.orders.reduce((total, item) => total + (item.currency === 'CNY' ? item.amount : 0), 0).toLocaleString()}`, note: '人民币订单合计' },
-])
-
-watch(filters, () => { page.value = 1 })
-watch(dateRange, () => { page.value = 1 })
-watch(
-  () => access.can('first-leg:create'),
-  (canCreate) => {
-    if (canCreate || !editorOpen.value || form.id) return
-    editorOpen.value = false
-    Object.assign(form, emptyForm())
-  },
-  { flush: 'sync' },
-)
-
-function resetFilters() { Object.assign(filters, { keyword: '', status: '', mode: '', customerId: '' }); dateRange.value = [] }
-function openCreate() { Object.assign(form, emptyForm()); captureBaseline(); editorOpen.value = true }
-function openEdit(row: FirstLegOrder) { Object.assign(form, row); captureBaseline(); detailOpen.value = false; editorOpen.value = true }
-function openDetail(row: FirstLegOrder) { currentOrder.value = row; detailOpen.value = true }
-function handleCustomerChange(customerId: string) {
-  const customer = store.customers.find((item) => item.id === customerId)
-  if (!customer) return
-  form.customerName = customer.name
-  if (!form.shipper) form.shipper = customer.name
-}
-
-function saveOrder(status: '草稿' | '待审核') {
-  if (!form.customerId || !form.origin.trim() || !form.destination.trim() || !form.receivingWarehouseId || !form.cargoName.trim()) {
-    ElMessage.warning('请填写客户、起运地、目的地、平台收货仓和货物名称')
-    return
-  }
-  const customer = store.customers.find((item) => item.id === form.customerId)
-  try {
-    store.saveOrder({ ...form, id: form.id || undefined, customerName: customer?.name || form.customerName, status: form.id ? form.status : status })
-    editorOpen.value = false
-    ElMessage.success(status === '草稿' ? '订单草稿已保存' : '头程订单已创建并提交审核')
-  } catch (error) {
-    ElMessage.error(error instanceof Error ? error.message : '订单保存失败')
-  }
-}
-
-function openStatusDialog(rows: FirstLegOrder[]) {
-  if (rows.length === 0) return
-  statusTargetIds.value = rows.map((item) => item.id)
-  statusForm.status = rows.length === 1 ? rows[0].status : '已受理'
-  statusForm.operator = rows.length === 1 && rows[0].operator !== '未分配' ? rows[0].operator : ''
-  statusForm.note = ''
-  statusDialogOpen.value = true
-}
-
-function applyStatus() {
-  if (!statusForm.operator && !['草稿', '待审核', '已取消'].includes(statusForm.status)) {
-    ElMessage.warning('请指定订单负责人')
-    return
-  }
-  try { statusTargetIds.value.forEach((id) => store.updateOrderStatus(id, statusForm.status, statusForm.operator, statusForm.note)) } catch (error) { ElMessage.error(error instanceof Error ? error.message : '订单状态更新失败'); return }
-  statusDialogOpen.value = false
-  selectedRows.value = []
-  if (currentOrder.value) currentOrder.value = store.orders.find((item) => item.id === currentOrder.value?.id) || null
-  ElMessage.success(statusTargetIds.value.length > 1 ? `已更新 ${statusTargetIds.value.length} 笔订单` : '订单状态已更新')
-}
-
-function openDeliveryDialog(order: FirstLegOrder) {
-  currentOrder.value = order
-  Object.assign(deliveryForm, {
-    orderId: order.id,
-    expressCompanyId: order.deliveryInfo?.expressCompanyId || '',
-    trackingNo: order.deliveryInfo?.trackingNo || '',
-    operator: order.deliveryInfo?.operator || (order.operator === '未分配' ? '' : order.operator),
-  })
-  deliveryDialogOpen.value = true
-}
-
-function saveDeliveryInfo() {
-  if (!deliveryForm.expressCompanyId || !deliveryForm.trackingNo.trim() || !deliveryForm.operator) {
-    ElMessage.warning('请选择快递公司，并填写快递单号和操作人')
-    return
-  }
-  try {
-    store.saveOrderDeliveryInfo(deliveryForm.orderId, deliveryForm.expressCompanyId, deliveryForm.trackingNo, deliveryForm.operator)
-    currentOrder.value = store.orders.find((item) => item.id === deliveryForm.orderId) || null
-    deliveryDialogOpen.value = false
-    ElMessage.success('履约快递信息已保存')
-  } catch (error) {
-    ElMessage.error(error instanceof Error ? error.message : '履约快递信息保存失败')
-  }
-}
-
-function deliveryCompanies(order: FirstLegOrder | null) {
-  return store.expressCompanies.filter((item) => item.status === '合作中' || item.id === order?.deliveryInfo?.expressCompanyId)
-}
-
-function statusStep(status: OrderStatus) {
-  const index = ['待审核', '已受理', '已订舱', '运输中', '已完成'].indexOf(status)
-  return index < 0 ? 0 : index + 1
-}
-
-function contactCustomerForModification(order: FirstLegOrder) {
-  try { store.recordCustomerModificationContact(order.id, order.operator === '未分配' ? '平台管理员' : order.operator); currentOrder.value = store.orders.find((item) => item.id === order.id) || null; ElMessage.success('已记录联系客户修改，订单继续保持待审核') }
-  catch (error) { ElMessage.error(error instanceof Error ? error.message : '记录失败') }
-}
-
-function canEditOrder(order: FirstLegOrder) { return access.can('first-leg:status') || (order.status === '草稿' && access.can('first-leg:create')) }
-
-function exportOrders() { ElMessage.success(`已生成 ${filteredRows.value.length} 笔订单的导出任务`) }
-</script>
-
-<template>
-  <div class="business-page">
-    <MetricStrip :items="metrics" />
-    <section class="surface-panel filter-panel order-filter" aria-label="头程订单筛选">
-      <div class="filter-fields">
-        <el-input v-model="filters.keyword" clearable placeholder="订单号、客户、参考号或港口" aria-label="订单关键词"><template #prefix><Search :size="16" /></template></el-input>
-        <el-select v-model="filters.customerId" clearable filterable placeholder="全部客户" aria-label="订单客户"><el-option v-for="item in store.customers" :key="item.id" :label="item.name" :value="item.id" /></el-select>
-        <el-select v-model="filters.status" clearable placeholder="全部状态" aria-label="订单状态"><el-option v-for="item in statusOptions" :key="item" :label="item" :value="item" /></el-select>
-        <el-select v-model="filters.mode" clearable placeholder="全部运输方式" aria-label="运输方式"><el-option v-for="item in ['海运整箱 FCL','海运拼箱 LCL','空运','陆运']" :key="item" :label="item" :value="item" /></el-select>
-        <el-date-picker v-model="dateRange" type="daterange" value-format="YYYY-MM-DD" range-separator="至" start-placeholder="创建开始" end-placeholder="创建结束" aria-label="订单创建日期" />
-      </div>
-      <div class="filter-actions"><el-button @click="resetFilters"><RotateCcw :size="16" />重置</el-button><el-button v-if="access.can('first-leg:status')" :disabled="selectedRows.length === 0" @click="openStatusDialog(selectedRows)"><ClipboardCheck :size="16" />批量更新</el-button><el-button v-if="!access.usesServerPermissions" @click="exportOrders"><Download :size="16" />导出</el-button><el-button v-if="access.can('first-leg:create')" type="primary" @click="openCreate"><Plus :size="16" />创建订单</el-button></div>
-    </section>
-
-    <section class="surface-panel table-panel">
-      <header class="panel-heading"><div><h2>头程订单</h2><p>从审核、受理、订舱到运输完成，统一跟进订单状态与负责人。</p></div><span v-if="selectedRows.length" class="selection-note">已选择 {{ selectedRows.length }} 笔</span></header>
-      <el-table :data="pagedRows" row-key="id" empty-text="没有符合条件的头程订单" @selection-change="selectedRows = $event">
-        <el-table-column type="selection" width="44" />
-        <el-table-column label="订单信息" min-width="210"><template #default="{ row }"><div class="primary-cell"><strong class="order-no">{{ row.no }}</strong><span>{{ row.referenceNo || '无客户参考号' }} · {{ row.createdAt }}</span></div></template></el-table-column>
-        <el-table-column label="客户" min-width="185" show-overflow-tooltip><template #default="{ row }"><div class="primary-cell"><strong>{{ row.customerName }}</strong><span>{{ row.businessType }} · {{ row.priority }}</span></div></template></el-table-column>
-        <el-table-column label="运输方案" min-width="190"><template #default="{ row }"><div class="primary-cell"><strong>{{ row.transportMode }}</strong><span>{{ row.container }}</span></div></template></el-table-column>
-        <el-table-column label="路线" min-width="160"><template #default="{ row }"><div class="route-cell"><span>{{ row.origin }}</span><i>→</i><span>{{ row.destination }}</span></div></template></el-table-column>
-        <el-table-column label="平台收货仓" min-width="150"><template #default="{ row }"><div class="primary-cell"><strong>{{ row.receivingWarehouseSnapshot?.name || '-' }}</strong><span>{{ row.receivingWarehouseSnapshot?.code || '-' }}</span></div></template></el-table-column>
-        <el-table-column label="履约快递" min-width="160"><template #default="{ row }"><div class="primary-cell"><strong>{{ row.deliveryInfo?.expressCompanyName || '未维护' }}</strong><span>{{ row.deliveryInfo?.trackingNo || '—' }}</span></div></template></el-table-column>
-        <el-table-column label="应收" width="118" align="right"><template #default="{ row }"><strong>{{ row.currency === 'CNY' ? '¥' : '$' }}{{ row.amount.toLocaleString() }}</strong></template></el-table-column>
-        <el-table-column label="负责人" width="100"><template #default="{ row }"><span :class="{ 'muted-value': row.operator === '未分配' }">{{ row.operator }}</span></template></el-table-column>
-        <el-table-column label="状态" width="96"><template #default="{ row }"><StatusBadge :status="row.status" /></template></el-table-column>
-        <el-table-column label="操作" width="290" fixed="right"><template #default="{ row }"><div class="table-actions"><el-button link type="primary" @click="openDetail(row as FirstLegOrder)"><Eye :size="15" />详情</el-button><el-button v-if="canEditOrder(row as FirstLegOrder)" link type="primary" @click="openEdit(row as FirstLegOrder)"><Pencil :size="15" />编辑</el-button><el-button v-if="access.can('first-leg:delivery')" link type="primary" @click="openDeliveryDialog(row as FirstLegOrder)"><PackageCheck :size="15" />快递</el-button><el-button v-if="access.can('first-leg:status')" link type="success" @click="openStatusDialog([row as FirstLegOrder])"><UserRoundCheck :size="15" />处理</el-button></div></template></el-table-column>
-      </el-table>
-      <footer class="table-footer"><span>显示 {{ pagedRows.length }} 条，共 {{ filteredRows.length }} 条</span><el-pagination v-model:current-page="page" :page-size="pageSize" :total="filteredRows.length" layout="prev, pager, next" /></footer>
-    </section>
-
-    <el-drawer v-model="editorOpen" :title="form.id ? '编辑头程订单' : '创建头程订单'" size="780px" class="business-drawer editor-drawer order-editor" :modal="false" :close-on-click-modal="false">
-      <el-form label-position="top" class="drawer-form">
-        <div class="form-section"><h3>业务信息</h3><div class="form-grid three-cols"><el-form-item label="客户" required><el-select v-model="form.customerId" filterable placeholder="请选择客户" @change="handleCustomerChange"><el-option v-for="item in store.customers.filter((customer) => customer.status === '正常')" :key="item.id" :label="item.name" :value="item.id" /></el-select></el-form-item><el-form-item label="运输方式"><el-select v-model="form.transportMode"><el-option v-for="item in ['海运整箱 FCL','海运拼箱 LCL','空运','陆运']" :key="item" :label="item" :value="item" /></el-select></el-form-item><el-form-item label="业务类型"><el-radio-group v-model="form.businessType"><el-radio-button label="出口" value="出口" /><el-radio-button label="进口" value="进口" /></el-radio-group></el-form-item><el-form-item label="客户参考号"><el-input v-model="form.referenceNo" /></el-form-item><el-form-item label="优先级"><el-select v-model="form.priority"><el-option label="普通" value="普通" /><el-option label="紧急" value="紧急" /><el-option label="加急" value="加急" /></el-select></el-form-item><el-form-item label="负责人"><el-select v-model="form.operator" clearable placeholder="暂不分配"><el-option v-for="item in operatorOptions" :key="item" :label="item" :value="item" /></el-select></el-form-item></div></div>
-        <div class="form-section"><h3>运输信息</h3><div class="form-grid three-cols"><el-form-item label="起运地 / POL" required><el-input v-model="form.origin" placeholder="如 宁波" /></el-form-item><el-form-item label="目的地 / POD" required><el-input v-model="form.destination" placeholder="如 洛杉矶" /></el-form-item><el-form-item label="平台收货仓" required><el-select v-model="form.receivingWarehouseId" filterable placeholder="请选择收货仓"><el-option v-for="warehouse in selectableWarehouses" :key="warehouse.id" :label="`${warehouse.name} · ${warehouse.city}`" :value="warehouse.id" :disabled="warehouse.status !== 'ACTIVE'" /></el-select></el-form-item><el-form-item label="柜型 / 箱量"><el-input v-model="form.container" placeholder="如 40HQ x 2" /></el-form-item><el-form-item label="预计出发 ETD"><el-date-picker v-model="form.etd" type="date" value-format="YYYY-MM-DD" placeholder="选择日期" /></el-form-item><el-form-item label="预计到达 ETA"><el-date-picker v-model="form.eta" type="date" value-format="YYYY-MM-DD" placeholder="选择日期" /></el-form-item><el-form-item label="应收金额"><div class="amount-field"><el-select v-model="form.currency"><el-option label="CNY" value="CNY" /><el-option label="USD" value="USD" /></el-select><el-input-number v-model="form.amount" :min="0" :precision="2" controls-position="right" /></div></el-form-item></div></div>
-        <div class="form-section"><h3>货物与收发货方</h3><div class="form-grid three-cols"><el-form-item label="货物名称" required><el-input v-model="form.cargoName" /></el-form-item><el-form-item label="件数"><el-input-number v-model="form.pieces" :min="1" controls-position="right" /></el-form-item><el-form-item label="毛重 (kg)"><el-input-number v-model="form.weight" :min="0" :precision="2" controls-position="right" /></el-form-item><el-form-item label="体积 (m³)"><el-input-number v-model="form.volume" :min="0" :precision="2" controls-position="right" /></el-form-item><el-form-item label="发货方"><el-input v-model="form.shipper" /></el-form-item><el-form-item label="收货方"><el-input v-model="form.consignee" /></el-form-item></div><el-form-item label="内部备注"><el-input v-model="form.remark" type="textarea" :rows="3" placeholder="仅平台内部可见" /></el-form-item></div>
-      </el-form>
-      <template #footer><div class="drawer-footer"><el-button @click="editorOpen = false">取消</el-button><el-button v-if="!form.id && access.can('first-leg:create')" @click="saveOrder('草稿')">保存草稿</el-button><el-button v-if="form.id || access.can('first-leg:create')" type="primary" @click="saveOrder('待审核')">{{ form.id ? '保存修改' : '创建并提交' }}</el-button></div></template>
-    </el-drawer>
-
-    <el-drawer v-model="detailOpen" title="订单详情" size="720px" class="business-drawer">
-      <template v-if="currentOrder">
-        <div class="order-detail-head"><div><span>{{ currentOrder.transportMode }}</span><h2>{{ currentOrder.no }}</h2><p>{{ currentOrder.customerName }} · {{ currentOrder.referenceNo }}</p></div><StatusBadge :status="currentOrder.status" /></div>
-        <div class="order-progress"><el-steps :active="statusStep(currentOrder.status)" finish-status="success" align-center><el-step title="待审核" /><el-step title="已受理" /><el-step title="已订舱" /><el-step title="运输中" /><el-step title="已完成" /></el-steps></div>
-        <div class="detail-section"><h3>订单概要</h3><el-descriptions :column="2" border><el-descriptions-item label="运输路线">{{ currentOrder.origin }} → {{ currentOrder.destination }}</el-descriptions-item><el-descriptions-item label="业务类型">{{ currentOrder.businessType }}</el-descriptions-item><el-descriptions-item label="平台收货仓"><strong>{{ currentOrder.receivingWarehouseSnapshot?.name || '-' }}</strong><span v-if="currentOrder.receivingWarehouseSnapshot" class="warehouse-snapshot-detail">{{ currentOrder.receivingWarehouseSnapshot.code }} · {{ currentOrder.receivingWarehouseSnapshot.province }}{{ currentOrder.receivingWarehouseSnapshot.city }}{{ currentOrder.receivingWarehouseSnapshot.address }}</span></el-descriptions-item><el-descriptions-item label="柜型/箱量">{{ currentOrder.container }}</el-descriptions-item><el-descriptions-item label="负责人">{{ currentOrder.operator }}</el-descriptions-item><el-descriptions-item label="ETD / ETA">{{ currentOrder.etd || '-' }} / {{ currentOrder.eta || '-' }}</el-descriptions-item><el-descriptions-item label="应收金额">{{ currentOrder.currency === 'CNY' ? '¥' : '$' }}{{ currentOrder.amount.toLocaleString() }}</el-descriptions-item></el-descriptions></div>
-        <div class="detail-section"><h3>货物信息</h3><MetricStrip :items="[{ label: '品名', value: currentOrder.cargoName }, { label: '件数', value: currentOrder.pieces }, { label: '毛重', value: `${currentOrder.weight.toLocaleString()} kg` }, { label: '体积', value: `${currentOrder.volume} m³` }]" /><div class="party-grid"><div><span>发货方</span><strong>{{ currentOrder.shipper }}</strong></div><div><span>收货方</span><strong>{{ currentOrder.consignee }}</strong></div></div></div>
-        <div class="detail-section"><h3>履约快递</h3><el-empty v-if="!currentOrder.deliveryInfo" description="尚未维护快递公司和快递单号" :image-size="64" /><el-descriptions v-else :column="2" border><el-descriptions-item label="快递公司">{{ currentOrder.deliveryInfo.expressCompanyName }}（{{ currentOrder.deliveryInfo.expressCompanyCode }}）</el-descriptions-item><el-descriptions-item label="快递单号">{{ currentOrder.deliveryInfo.trackingNo }}</el-descriptions-item><el-descriptions-item label="维护人">{{ currentOrder.deliveryInfo.operator }}</el-descriptions-item><el-descriptions-item label="更新时间">{{ currentOrder.deliveryInfo.updatedAt }}</el-descriptions-item></el-descriptions></div>
-        <div class="detail-section"><h3>处理记录</h3><el-timeline><el-timeline-item v-for="item in [...currentOrder.timeline].reverse()" :key="`${item.time}-${item.title}`" :timestamp="`${item.time} · ${item.operator}`" placement="top"><strong>{{ item.title }}</strong><p>{{ item.description }}</p></el-timeline-item></el-timeline></div>
-      </template>
-      <template #footer><div class="drawer-footer"><el-button @click="detailOpen = false">关闭</el-button><el-button v-if="currentOrder && canEditOrder(currentOrder)" @click="openEdit(currentOrder)">编辑订单</el-button><el-button v-if="currentOrder?.status === '待审核' && access.can('first-leg:status')" @click="contactCustomerForModification(currentOrder)">联系客户修改</el-button><el-button v-if="access.can('first-leg:delivery')" @click="currentOrder && openDeliveryDialog(currentOrder)">维护快递</el-button><el-button v-if="access.can('first-leg:status')" type="primary" @click="currentOrder && openStatusDialog([currentOrder])">更新状态</el-button></div></template>
-    </el-drawer>
-
-    <el-dialog v-model="statusDialogOpen" :title="statusTargetIds.length > 1 ? `批量更新 ${statusTargetIds.length} 笔订单` : '处理订单'" width="520px" class="status-dialog">
-      <el-form label-position="top"><el-form-item label="订单状态"><el-select v-model="statusForm.status"><el-option v-for="item in availableStatusOptions" :key="item" :label="item" :value="item" /></el-select></el-form-item><el-form-item label="负责人"><el-select v-model="statusForm.operator" clearable placeholder="请选择负责人"><el-option v-for="item in operatorOptions" :key="item" :label="item" :value="item" /></el-select></el-form-item><el-form-item label="处理说明"><el-input v-model="statusForm.note" type="textarea" :rows="3" placeholder="记录本次状态变更的原因或下一步动作" /></el-form-item></el-form>
-      <template #footer><el-button @click="statusDialogOpen = false">取消</el-button><el-button v-if="access.can('first-leg:status')" type="primary" @click="applyStatus">确认更新</el-button></template>
-    </el-dialog>
-    <el-dialog v-model="deliveryDialogOpen" title="维护履约快递" width="520px">
-      <el-alert title="一期每个订单仅维护一组快递公司和快递单号；修改会覆盖当前值并追加审计记录。" type="info" :closable="false" show-icon />
-      <el-form label-position="top" class="delivery-form"><el-form-item label="快递公司" required><el-select v-model="deliveryForm.expressCompanyId" filterable placeholder="请选择合作中的快递公司"><el-option v-for="item in deliveryCompanies(currentOrder)" :key="item.id" :label="`${item.name} · ${item.code}`" :value="item.id" :disabled="item.status !== '合作中'" /></el-select></el-form-item><el-form-item label="快递单号" required><el-input v-model="deliveryForm.trackingNo" maxlength="80" placeholder="请输入完整快递单号" /></el-form-item><el-form-item label="操作人" required><el-select v-model="deliveryForm.operator" filterable placeholder="请选择操作人"><el-option v-for="item in operatorOptions" :key="item" :label="item" :value="item" /></el-select></el-form-item></el-form>
-      <template #footer><el-button @click="deliveryDialogOpen = false">取消</el-button><el-button v-if="access.can('first-leg:delivery')" type="primary" @click="saveDeliveryInfo">保存快递信息</el-button></template>
-    </el-dialog>
-  </div>
-</template>
-
-<style scoped>
-.warehouse-snapshot-detail { display: block; margin-top: 4px; color: var(--cc-muted); font-size: 11px; line-height: 1.5; }
-</style>
diff --git a/src/views/ForbiddenView.test.ts b/src/views/ForbiddenView.test.ts
deleted file mode 100644
index 4ae368b9..00000000
--- a/src/views/ForbiddenView.test.ts
+++ /dev/null
@@ -1,80 +0,0 @@
-import { createPinia, setActivePinia } from 'pinia'
-import { flushPromises, mount } from '@vue/test-utils'
-import { createMemoryHistory, createRouter } from 'vue-router'
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-import { useAccessPreviewStore } from '@/stores/accessPreview'
-import { useAdminDataStore } from '@/stores/adminData'
-import ForbiddenView from './ForbiddenView.vue'
-
-let pinia: ReturnType<typeof createPinia>
-
-function createMemoryStorage(): Storage {
-  const values = new Map<string, string>()
-  return {
-    get length() { return values.size },
-    clear: () => values.clear(),
-    getItem: (key) => values.get(key) ?? null,
-    key: (index) => [...values.keys()][index] ?? null,
-    removeItem: (key) => values.delete(key),
-    setItem: (key, value) => values.set(key, value),
-  }
-}
-
-async function mountForbidden(from: string) {
-  const router = createRouter({
-    history: createMemoryHistory(),
-    routes: [
-      { path: '/customers', component: { template: '<p>customers</p>' } },
-      { path: '/403', component: ForbiddenView },
-    ],
-  })
-  await router.push({ path: '/403', query: { from } })
-  await router.isReady()
-
-  const wrapper = mount(ForbiddenView, {
-    global: {
-      plugins: [pinia, router],
-      stubs: {
-        'el-button': {
-          template: '<button type="button" @click="$emit(\'click\')"><slot /></button>',
-        },
-      },
-    },
-  })
-  return { wrapper, router }
-}
-
-describe('ForbiddenView', () => {
-  beforeEach(() => {
-    vi.stubGlobal('localStorage', createMemoryStorage())
-    pinia = createPinia()
-    setActivePinia(pinia)
-  })
-
-  it('shows the preview role and replaces the route with the first accessible page', async () => {
-    const access = useAccessPreviewStore()
-    access.initializeAfterLogin()
-    const { wrapper, router } = await mountForbidden('/customers?status=pending')
-
-    expect(wrapper.text()).toContain('权限预览：超级管理员')
-    expect(wrapper.text()).toContain('来源页面：/customers?status=pending')
-    await wrapper.get('button').trigger('click')
-    await flushPromises()
-
-    expect(router.currentRoute.value.fullPath).toBe('/customers')
-  })
-
-  it('sanitizes an external-looking source and guides role switching when no role is available', async () => {
-    const data = useAdminDataStore()
-    data.roles.forEach((role) => { role.status = '停用' })
-    const access = useAccessPreviewStore()
-    access.initializeAfterLogin()
-    const { wrapper } = await mountForbidden('//example.com')
-
-    expect(wrapper.text()).toContain('来源页面：/')
-    expect(wrapper.text()).not.toContain('//example.com')
-    expect(wrapper.text()).toContain('当前无可用角色')
-    expect(wrapper.text()).toContain('请使用顶栏切换角色')
-    expect(wrapper.find('button').exists()).toBe(false)
-  })
-})
diff --git a/src/views/ForbiddenView.vue b/src/views/ForbiddenView.vue
deleted file mode 100644
index ea0858fc..00000000
--- a/src/views/ForbiddenView.vue
+++ /dev/null
@@ -1,37 +0,0 @@
-<script setup lang="ts">
-import { computed } from 'vue'
-import { ShieldX } from '@lucide/vue'
-import { useRoute, useRouter } from 'vue-router'
-import { sanitizeInternalPath } from '@/router/accessDecision'
-import { useAccessPreviewStore } from '@/stores/accessPreview'
-
-const route = useRoute()
-const router = useRouter()
-const access = useAccessPreviewStore()
-
-const sourcePath = computed(() => sanitizeInternalPath(route.query.from))
-const previewRoleLabel = computed(() => access.currentRole
-  ? `权限预览：${access.currentRole.name}`
-  : '当前无可用角色')
-
-async function returnToAccessiblePage() {
-  if (!access.firstAccessiblePath) return
-  await router.replace(access.firstAccessiblePath)
-}
-</script>
-
-<template>
-  <section class="forbidden-page" aria-labelledby="forbidden-title">
-    <div class="forbidden-icon" aria-hidden="true">
-      <ShieldX :size="32" />
-    </div>
-    <p class="section-kicker">403 · 权限不足</p>
-    <h2 id="forbidden-title">当前预览角色无法访问此页面</h2>
-    <p>{{ previewRoleLabel }}</p>
-    <p class="forbidden-source">来源页面：{{ sourcePath }}</p>
-    <el-button v-if="access.firstAccessiblePath" type="primary" @click="returnToAccessiblePage">
-      返回可访问页面
-    </el-button>
-    <p v-else>请使用顶栏切换角色，选择具有可访问菜单的角色。</p>
-  </section>
-</template>
diff --git a/src/views/InternalUsersView.vue b/src/views/InternalUsersView.vue
deleted file mode 100644
index 0c8ef0e9..00000000
--- a/src/views/InternalUsersView.vue
+++ /dev/null
@@ -1,128 +0,0 @@
-<script setup lang="ts">
-import { computed, reactive, ref, watch } from 'vue'
-import { ElMessage, ElMessageBox } from 'element-plus'
-import { KeyRound, Pencil, Plus, RotateCcw, Search, UserRoundCog } from '@lucide/vue'
-import MetricStrip from '@/components/MetricStrip.vue'
-import StatusBadge from '@/components/StatusBadge.vue'
-import { useUnsavedWorkRegistration } from '@/composables/useUnsavedWorkRegistration'
-import { useAccessPreviewStore } from '@/stores/accessPreview'
-import { useAdminDataStore } from '@/stores/adminData'
-import type { InternalUser } from '@/types/admin'
-
-const store = useAdminDataStore()
-const access = useAccessPreviewStore()
-const page = ref(1)
-const pageSize = 10
-const editorOpen = ref(false)
-const filters = reactive({ keyword: '', department: '', roleId: '', status: '' })
-const emptyForm = (): Omit<InternalUser, 'lastLogin' | 'createdAt'> => ({ id: '', account: '', name: '', department: '', phone: '', email: '', roleIds: [], status: '正常' })
-const form = reactive(emptyForm())
-const editorLabel = computed(() => form.id ? '编辑内部用户' : '新增内部用户')
-const requiredPermission = computed(() => 'system:user:write')
-const { captureBaseline } = useUnsavedWorkRegistration({
-  key: 'internal-user-editor',
-  label: editorLabel,
-  isOpen: editorOpen,
-  model: form,
-  requiredPermission,
-})
-
-const roleName = (id: string) => store.roles.find((role) => role.id === id)?.name || id
-const filteredRows = computed(() => store.users.filter((item) => {
-  const keyword = filters.keyword.trim().toLowerCase()
-  const matchesKeyword = !keyword || [item.account, item.name, item.phone, item.email].some((value) => value.toLowerCase().includes(keyword))
-  return matchesKeyword && (!filters.department || item.department === filters.department) && (!filters.roleId || item.roleIds.includes(filters.roleId)) && (!filters.status || item.status === filters.status)
-}))
-const pagedRows = computed(() => filteredRows.value.slice((page.value - 1) * pageSize, page.value * pageSize))
-const departments = computed(() => [...new Set(store.users.map((item) => item.department))])
-const metrics = computed(() => [
-  { label: '内部用户', value: store.users.length, note: '平台员工账号' },
-  { label: '正常账号', value: store.activeUsers, note: '当前可登录' },
-  { label: '已停用', value: store.users.filter((item) => item.status === '停用').length, note: '无法登录平台' },
-  { label: '角色覆盖', value: store.roles.length, note: '已配置角色' },
-])
-
-watch(filters, () => { page.value = 1 })
-
-function resetFilters() { Object.assign(filters, { keyword: '', department: '', roleId: '', status: '' }) }
-function openCreate() { Object.assign(form, emptyForm()); captureBaseline(); editorOpen.value = true }
-function openEdit(row: InternalUser) { Object.assign(form, { ...row, roleIds: [...row.roleIds] }); captureBaseline(); editorOpen.value = true }
-
-function saveUser() {
-  if (!form.account.trim() || !form.name.trim() || !form.department.trim() || form.roleIds.length === 0) {
-    ElMessage.warning('请填写账号、姓名、部门并至少分配一个角色')
-    return
-  }
-  if (!form.id && store.users.some((item) => item.account === form.account)) {
-    ElMessage.error('该登录账号已存在，请更换账号')
-    return
-  }
-  store.saveUser({ ...form, id: form.id || undefined, roleIds: [...form.roleIds] })
-  editorOpen.value = false
-  ElMessage.success(form.id ? '用户资料已更新' : '内部用户已创建')
-}
-
-async function resetPassword(row: InternalUser) {
-  try {
-    await ElMessageBox.confirm(`确认重置“${row.name}”的登录密码吗？`, '重置密码', { confirmButtonText: '确认重置', cancelButtonText: '取消', type: 'warning' })
-    ElMessage.success('密码已重置，请通知用户首次登录后修改密码')
-  } catch {
-    // 用户取消，不需要反馈。
-  }
-}
-
-async function toggleStatus(row: InternalUser) {
-  if (row.account === 'admin') { ElMessage.warning('系统管理员账号不能停用'); return }
-  const target = row.status === '正常' ? '停用' : '正常'
-  try {
-    await ElMessageBox.confirm(`确认${target === '停用' ? '停用' : '启用'}“${row.name}”的账号吗？`, '账号状态', { confirmButtonText: '确认', cancelButtonText: '取消' })
-    store.setUserStatus(row.id, target)
-    ElMessage.success(`账号已${target === '正常' ? '启用' : '停用'}`)
-  } catch {
-    // 用户取消，不需要反馈。
-  }
-}
-</script>
-
-<template>
-  <div class="business-page">
-    <MetricStrip :items="metrics" />
-    <section class="surface-panel filter-panel" aria-label="内部用户筛选">
-      <div class="filter-fields">
-        <el-input v-model="filters.keyword" clearable placeholder="账号、姓名、手机或邮箱" aria-label="用户关键词"><template #prefix><Search :size="16" /></template></el-input>
-        <el-select v-model="filters.department" clearable placeholder="全部部门" aria-label="用户部门"><el-option v-for="item in departments" :key="item" :label="item" :value="item" /></el-select>
-        <el-select v-model="filters.roleId" clearable placeholder="全部角色" aria-label="用户角色"><el-option v-for="item in store.roles" :key="item.id" :label="item.name" :value="item.id" /></el-select>
-        <el-select v-model="filters.status" clearable placeholder="全部状态" aria-label="用户状态"><el-option label="正常" value="正常" /><el-option label="停用" value="停用" /></el-select>
-      </div>
-      <div class="filter-actions"><el-button @click="resetFilters"><RotateCcw :size="16" />重置</el-button><el-button v-if="access.can('system:user:write')" type="primary" @click="openCreate"><Plus :size="16" />新增用户</el-button></div>
-    </section>
-
-    <section class="surface-panel table-panel">
-      <header class="panel-heading"><div><h2>内部用户</h2><p>维护平台员工账号，并通过角色控制菜单和操作权限。</p></div></header>
-      <el-table :data="pagedRows" row-key="id" empty-text="没有符合条件的内部用户">
-        <el-table-column label="用户" min-width="190"><template #default="{ row }"><div class="user-cell"><span>{{ row.name.slice(0,1) }}</span><div><strong>{{ row.name }}</strong><small>{{ row.account }}</small></div></div></template></el-table-column>
-        <el-table-column prop="department" label="部门" width="110" />
-        <el-table-column label="角色" min-width="190"><template #default="{ row }"><div class="tag-list"><el-tag v-for="roleId in row.roleIds" :key="roleId" effect="plain" size="small">{{ roleName(roleId) }}</el-tag></div></template></el-table-column>
-        <el-table-column label="联系方式" min-width="190"><template #default="{ row }"><div class="primary-cell"><strong>{{ row.phone }}</strong><span>{{ row.email }}</span></div></template></el-table-column>
-        <el-table-column prop="lastLogin" label="最后登录" width="150" />
-        <el-table-column label="状态" width="88"><template #default="{ row }"><StatusBadge :status="row.status" /></template></el-table-column>
-        <el-table-column label="操作" width="250" fixed="right"><template #default="{ row }"><div v-if="access.can('system:user:write')" class="table-actions"><el-button link type="primary" @click="openEdit(row as InternalUser)"><Pencil :size="15" />编辑</el-button><el-button link type="primary" @click="resetPassword(row as InternalUser)"><KeyRound :size="15" />重置密码</el-button><el-button link :type="row.status === '正常' ? 'danger' : 'success'" :disabled="row.account === 'admin'" @click="toggleStatus(row as InternalUser)">{{ row.status === '正常' ? '停用' : '启用' }}</el-button></div></template></el-table-column>
-      </el-table>
-      <footer class="table-footer"><span>显示 {{ pagedRows.length }} 条，共 {{ filteredRows.length }} 条</span><el-pagination v-model:current-page="page" :page-size="pageSize" :total="filteredRows.length" layout="prev, pager, next" /></footer>
-    </section>
-
-    <el-drawer v-model="editorOpen" :title="form.id ? '编辑内部用户' : '新增内部用户'" size="620px" class="business-drawer editor-drawer" :modal="false" :close-on-click-modal="false">
-      <el-form label-position="top" class="drawer-form">
-        <div class="form-section"><h3>账号信息</h3><div class="form-grid two-cols">
-          <el-form-item label="登录账号" required><el-input v-model="form.account" :disabled="Boolean(form.id)" placeholder="英文、数字或下划线" /></el-form-item>
-          <el-form-item label="姓名" required><el-input v-model="form.name" /></el-form-item>
-          <el-form-item label="所属部门" required><el-select v-model="form.department" filterable allow-create placeholder="请选择或输入部门"><el-option v-for="item in departments" :key="item" :label="item" :value="item" /></el-select></el-form-item>
-          <el-form-item label="账号状态"><el-radio-group v-model="form.status"><el-radio-button label="正常" value="正常" /><el-radio-button label="停用" value="停用" /></el-radio-group></el-form-item>
-        </div></div>
-        <div class="form-section"><h3>联系方式</h3><div class="form-grid two-cols"><el-form-item label="手机号"><el-input v-model="form.phone" /></el-form-item><el-form-item label="邮箱"><el-input v-model="form.email" /></el-form-item></div></div>
-        <div class="form-section"><h3>角色分配</h3><el-form-item label="平台角色" required><el-select v-model="form.roleIds" multiple collapse-tags placeholder="至少选择一个角色"><el-option v-for="item in store.roles.filter((role) => role.status === '启用')" :key="item.id" :label="item.name" :value="item.id" /></el-select></el-form-item><p class="form-help"><UserRoundCog :size="16" />用户最终权限为所分配角色权限的合集。</p></div>
-      </el-form>
-      <template #footer><div class="drawer-footer"><el-button @click="editorOpen = false">取消</el-button><el-button v-if="access.can('system:user:write')" type="primary" @click="saveUser">保存用户</el-button></div></template>
-    </el-drawer>
-  </div>
-</template>
diff --git a/src/views/LoginView.test.ts b/src/views/LoginView.test.ts
deleted file mode 100644
index c2e78049..00000000
--- a/src/views/LoginView.test.ts
+++ /dev/null
@@ -1,150 +0,0 @@
-import { createPinia, setActivePinia } from 'pinia'
-import { readFileSync } from 'node:fs'
-import { resolve } from 'node:path'
-import { flushPromises, mount } from '@vue/test-utils'
-import { createMemoryHistory, createRouter } from 'vue-router'
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-import { useAccessPreviewStore } from '@/stores/accessPreview'
-import { useAuthStore } from '@/stores/auth'
-import LoginView from './LoginView.vue'
-
-const loginSource = readFileSync(resolve(process.cwd(), 'src/views/LoginView.vue'), 'utf8')
-
-function createMemoryStorage(): Storage {
-  const values = new Map<string, string>()
-  return {
-    get length() { return values.size },
-    clear: () => values.clear(),
-    getItem: (key) => values.get(key) ?? null,
-    key: (index) => [...values.keys()][index] ?? null,
-    removeItem: (key) => values.delete(key),
-    setItem: (key, value) => values.set(key, value),
-  }
-}
-
-describe('LoginView access preview lifecycle', () => {
-  beforeEach(() => {
-    vi.stubGlobal('localStorage', createMemoryStorage())
-  })
-
-  it('only exposes the integration account hint through the development environment branch', () => {
-    expect(loginSource).toContain('const isDevelopment = import.meta.env.DEV')
-    expect(loginSource).toContain('v-if="developmentHint" class="demo-tip"')
-    expect(loginSource).toContain("account: isDevelopment ? 'platform_admin' : ''")
-    expect(loginSource).toContain("password: isDevelopment ? 'ChangeMe123!' : ''")
-  })
-
-  it('initializes preview access after login and before redirecting', async () => {
-    const pinia = createPinia()
-    setActivePinia(pinia)
-    const auth = useAuthStore()
-    const access = useAccessPreviewStore()
-    const router = createRouter({
-      history: createMemoryHistory(),
-      routes: [
-        { path: '/login', component: LoginView },
-        { path: '/', component: { template: '<p>home</p>' } },
-      ],
-    })
-    await router.push('/login')
-    await router.isReady()
-
-    const calls: string[] = []
-    vi.spyOn(auth, 'login').mockImplementation(async () => { calls.push('login') })
-    vi.spyOn(access, 'initializeAfterLogin').mockImplementation(() => { calls.push('access') })
-    vi.spyOn(router, 'replace').mockImplementation(async () => { calls.push('replace') })
-    const wrapper = mount(LoginView, {
-      global: {
-        plugins: [pinia, router],
-        stubs: {
-          'el-form': { template: '<form><slot /></form>' },
-          'el-form-item': { template: '<label><slot /></label>' },
-          'el-input': { template: '<input />' },
-          'el-button': { emits: ['click'], template: '<button type="button" @click="$emit(\'click\')"><slot /></button>' },
-        },
-      },
-    })
-
-    await wrapper.get('.login-submit').trigger('click')
-    await flushPromises()
-
-    expect(calls).toEqual(['login', 'access', 'replace'])
-  })
-
-  it.each([
-    ['/customers?page=2', '/customers?page=2'],
-    ['/customers/reviews', '/customers/reviews'],
-    ['//example.com', '/customers'],
-    ['https://example.com', '/customers'],
-    [['/customers', '/orders/first-leg'], '/customers'],
-    [null, '/customers'],
-  ])('sanitizes the post-login redirect %j to %s', async (redirect, expected) => {
-    const pinia = createPinia()
-    setActivePinia(pinia)
-    const auth = useAuthStore()
-    const router = createRouter({
-      history: createMemoryHistory(),
-      routes: [
-        { path: '/login', component: LoginView },
-        { path: '/', component: { template: '<p>home</p>' } },
-      ],
-    })
-    await router.push({ path: '/login', query: { redirect } })
-    await router.isReady()
-    vi.spyOn(auth, 'login').mockResolvedValue()
-    const replace = vi.spyOn(router, 'replace').mockResolvedValue()
-    const wrapper = mount(LoginView, {
-      global: {
-        plugins: [pinia, router],
-        stubs: {
-          'el-form': { template: '<form><slot /></form>' },
-          'el-form-item': { template: '<label><slot /></label>' },
-          'el-input': { template: '<input />' },
-          'el-button': { emits: ['click'], template: '<button type="button" @click="$emit(\'click\')"><slot /></button>' },
-        },
-      },
-    })
-
-    await wrapper.get('.login-submit').trigger('click')
-    await flushPromises()
-
-    expect(replace).toHaveBeenCalledWith(expected)
-  })
-
-  it('preserves the form and reports a recoverable error when login fails', async () => {
-    const pinia = createPinia()
-    setActivePinia(pinia)
-    const auth = useAuthStore()
-    const access = useAccessPreviewStore()
-    const router = createRouter({
-      history: createMemoryHistory(),
-      routes: [
-        { path: '/login', component: LoginView },
-        { path: '/customers', component: { template: '<p>customers</p>' } },
-      ],
-    })
-    await router.push('/login')
-    await router.isReady()
-    vi.spyOn(auth, 'login').mockRejectedValue(new Error('network unavailable'))
-    const initialize = vi.spyOn(access, 'initializeAfterLogin')
-    const replace = vi.spyOn(router, 'replace')
-    const wrapper = mount(LoginView, {
-      global: {
-        plugins: [pinia, router],
-        stubs: {
-          'el-form': { template: '<form><slot /></form>' },
-          'el-form-item': { template: '<label><slot /></label>' },
-          'el-input': { template: '<input />' },
-          'el-button': { emits: ['click'], template: '<button type="button" @click="$emit(\'click\')"><slot /></button>' },
-        },
-      },
-    })
-
-    await wrapper.get('.login-submit').trigger('click')
-    await flushPromises()
-
-    expect(wrapper.get('[role="alert"]').text()).toBe('network unavailable')
-    expect(initialize).not.toHaveBeenCalled()
-    expect(replace).not.toHaveBeenCalled()
-  })
-})
diff --git a/src/views/LoginView.vue b/src/views/LoginView.vue
deleted file mode 100644
index 4508862d..00000000
--- a/src/views/LoginView.vue
+++ /dev/null
@@ -1,87 +0,0 @@
-<script setup lang="ts">
-import { reactive, ref } from 'vue'
-import { useRoute, useRouter } from 'vue-router'
-import { ElMessage } from 'element-plus'
-import { ArrowRight, LockKeyhole, ShieldCheck, UserRound } from '@lucide/vue'
-import { getApiErrorDetails, type ApiErrorDetails } from '@/api/http'
-import ApiErrorMeta from '@/components/ApiErrorMeta.vue'
-import { sanitizeInternalPath } from '@/router/accessDecision'
-import { useAccessPreviewStore } from '@/stores/accessPreview'
-import { useAuthStore } from '@/stores/auth'
-
-const route = useRoute()
-const router = useRouter()
-const auth = useAuthStore()
-const access = useAccessPreviewStore()
-const loading = ref(false)
-const loginError = ref<ApiErrorDetails | null>(null)
-const isDevelopment = import.meta.env.DEV
-const developmentHint = isDevelopment ? '当前为前端开发环境，可使用预填账号进入。' : ''
-const form = reactive({
-  account: isDevelopment ? 'platform_admin' : '',
-  password: isDevelopment ? 'ChangeMe123!' : '',
-})
-
-async function submit() {
-  loginError.value = null
-  if (!form.account || !form.password) {
-    loginError.value = { message: '请输入账号和密码' }
-    ElMessage.warning(loginError.value.message)
-    return
-  }
-  loading.value = true
-  try {
-    await auth.login(form.account, form.password)
-    access.initializeAfterLogin()
-    ElMessage.success('登录成功')
-    const requestedPath = sanitizeInternalPath(route.query.redirect)
-    const targetPath = requestedPath === '/'
-      ? access.firstAccessiblePath ?? '/403'
-      : requestedPath
-    await router.replace(targetPath)
-  } catch (error) {
-    loginError.value = getApiErrorDetails(error, '登录失败，请检查账号和密码后重试')
-    ElMessage.error(loginError.value.message)
-  } finally {
-    loading.value = false
-  }
-}
-</script>
-
-<template>
-  <div class="login-page">
-    <section class="login-intro">
-      <div class="login-brand"><span>CC</span> 虫虫出海</div>
-      <div>
-        <p class="eyebrow">CHONGCHONG GLOBAL</p>
-        <h1>让跨境物流管理<br />清晰、可靠、可追踪</h1>
-        <p class="intro-copy">统一管理企业入驻、内部权限和头程订单，让每一次操作都有边界、有记录。</p>
-      </div>
-      <div class="security-note">
-        <ShieldCheck :size="22" />
-        <span>平台内部系统，请使用授权账号登录</span>
-      </div>
-    </section>
-
-    <section class="login-panel">
-      <div class="login-card">
-        <div class="login-card-icon"><LockKeyhole :size="24" /></div>
-        <h2>登录管理后台</h2>
-        <p>使用平台内部员工账号登录</p>
-        <el-form label-position="top" size="large" @submit.prevent="submit">
-          <el-form-item label="账号">
-            <el-input v-model.trim="form.account" placeholder="请输入账号" :prefix-icon="UserRound" autocomplete="username" maxlength="100" />
-          </el-form-item>
-          <el-form-item label="密码">
-            <el-input v-model="form.password" type="password" show-password placeholder="请输入密码" :prefix-icon="LockKeyhole" autocomplete="current-password" maxlength="128" @keyup.enter="submit" />
-          </el-form-item>
-          <el-button class="login-submit" type="primary" :loading="loading" @click="submit">
-            登录 <ArrowRight :size="17" />
-          </el-button>
-        </el-form>
-        <div v-if="loginError" class="login-error" role="alert"><p>{{ loginError.message }}</p><ApiErrorMeta :details="loginError" /></div>
-        <div v-if="developmentHint" class="demo-tip" role="note">{{ developmentHint }}</div>
-      </div>
-    </section>
-  </div>
-</template>
diff --git a/src/views/PermissionsView.test.ts b/src/views/PermissionsView.test.ts
deleted file mode 100644
index 4aa8bdd5..00000000
--- a/src/views/PermissionsView.test.ts
+++ /dev/null
@@ -1,80 +0,0 @@
-import { createPinia, setActivePinia } from 'pinia'
-import { flushPromises, shallowMount } from '@vue/test-utils'
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-import { listPlatformPermissions, type PlatformPermissionResource } from '@/api/platformIam'
-import { useAuthStore } from '@/stores/auth'
-import PermissionsView from './PermissionsView.vue'
-
-vi.mock('@/api/platformIam', () => ({
-  createPlatformPermission: vi.fn(),
-  listPlatformPermissions: vi.fn(),
-}))
-
-const permission: PlatformPermissionResource = {
-  id: 5100010,
-  tenantId: 0,
-  appCode: 'PLATFORM',
-  permissionType: 'MENU',
-  parentId: 5100000,
-  permissionCode: 'platform:customer:list',
-  permissionName: '企业客户',
-  routePath: '/customers',
-  httpMethod: null,
-  sortNo: 10,
-  status: 'ACTIVE',
-}
-
-function mountServerView() {
-  const pinia = createPinia()
-  setActivePinia(pinia)
-  const auth = useAuthStore()
-  auth.isServerSession = true
-  auth.permissions = ['platform:permission:list', 'platform:permission:create']
-  return shallowMount(PermissionsView, {
-    global: {
-      plugins: [pinia],
-      directives: { loading: () => undefined },
-      stubs: {
-        'el-alert': { props: ['title'], template: '<div role="alert">{{ title }}<slot name="title" /></div>' },
-        'el-input': true,
-        'el-option': true,
-        'el-select': true,
-        'el-button': true,
-        'el-table': true,
-        'el-table-column': true,
-        'el-input-number': true,
-        'el-radio-group': true,
-        'el-radio-button': true,
-        'el-drawer': { template: '<section><slot /><slot name="footer" /></section>' },
-        'el-form': { template: '<form><slot /></form>' },
-        'el-form-item': { template: '<label><slot /></label>' },
-      },
-    },
-  })
-}
-
-describe('PermissionsView IAM mode', () => {
-  beforeEach(() => {
-    vi.mocked(listPlatformPermissions).mockReset()
-  })
-
-  it('loads the platform permission resource tree from IAM', async () => {
-    vi.mocked(listPlatformPermissions).mockResolvedValue([permission])
-
-    const wrapper = mountServerView()
-    await flushPromises()
-
-    expect(listPlatformPermissions).toHaveBeenCalledTimes(1)
-    expect(wrapper.text()).toContain('权限资源列表和新增已接入 IAM')
-    expect(wrapper.text()).toContain('一期真实资源仅使用菜单和按钮类型')
-  })
-
-  it('shows a recoverable state when the permission list fails', async () => {
-    vi.mocked(listPlatformPermissions).mockRejectedValue(new Error('IAM unavailable'))
-
-    const wrapper = mountServerView()
-    await flushPromises()
-
-    expect(wrapper.findAll('[role="alert"]').map((item) => item.text()).join(' ')).toContain('IAM unavailable')
-  })
-})
diff --git a/src/views/PermissionsView.vue b/src/views/PermissionsView.vue
deleted file mode 100644
index 0807e21e..00000000
--- a/src/views/PermissionsView.vue
+++ /dev/null
@@ -1,180 +0,0 @@
-<script setup lang="ts">
-import { computed, onMounted, reactive, ref } from 'vue'
-import { ElMessage, ElMessageBox } from 'element-plus'
-import { Braces, FolderTree, Pencil, Plus, Search, ShieldCheck } from '@lucide/vue'
-import MetricStrip from '@/components/MetricStrip.vue'
-import StatusBadge from '@/components/StatusBadge.vue'
-import { createPlatformPermission, listPlatformPermissions, type PlatformPermissionResource } from '@/api/platformIam'
-import { getApiErrorDetails, getApiErrorMessage, type ApiErrorDetails } from '@/api/http'
-import ApiErrorMeta from '@/components/ApiErrorMeta.vue'
-import { useUnsavedWorkRegistration } from '@/composables/useUnsavedWorkRegistration'
-import { useAccessPreviewStore } from '@/stores/accessPreview'
-import { useAdminDataStore } from '@/stores/adminData'
-import type { Permission, PermissionType } from '@/types/admin'
-import { buildPermissionTree, getDescendantIds } from '@/utils/permissionTree'
-
-const store = useAdminDataStore()
-const access = useAccessPreviewStore()
-const editorOpen = ref(false)
-const serverPermissions = ref<Permission[]>([])
-const loading = ref(false)
-const saving = ref(false)
-const loadError = ref<ApiErrorDetails | null>(null)
-const filters = reactive({ keyword: '', type: '', status: '' })
-const emptyForm = (): Permission => ({ id: '', parentId: null, name: '', code: '', type: '菜单', path: '', method: '-', status: '启用', sort: 10 })
-const form = reactive(emptyForm())
-const editorLabel = computed(() => form.id ? '编辑权限' : '新增权限')
-const requiredPermission = computed(() => access.usesServerPermissions ? 'platform:permission:create' : 'system:permission:write')
-const { captureBaseline } = useUnsavedWorkRegistration({
-  key: 'permission-editor',
-  label: editorLabel,
-  isOpen: editorOpen,
-  model: form,
-  requiredPermission,
-})
-const permissionTypes: PermissionType[] = ['目录', '菜单', '按钮', '接口']
-const availablePermissionTypes = computed<PermissionType[]>(() => access.usesServerPermissions ? ['菜单', '按钮'] : permissionTypes)
-const permissions = computed(() => access.usesServerPermissions ? serverPermissions.value : store.permissions)
-const canCreate = computed(() => access.can('platform:permission:create'))
-
-function matches(item: Permission) {
-  const keyword = filters.keyword.trim().toLowerCase()
-  return (!keyword || [item.name, item.code, item.path].some((value) => value.toLowerCase().includes(keyword))) && (!filters.type || item.type === filters.type) && (!filters.status || item.status === filters.status)
-}
-const treeRows = computed(() => buildPermissionTree(permissions.value, matches))
-const blockedParentIds = computed(() => new Set(
-  form.id ? [form.id, ...getDescendantIds(permissions.value, form.id)] : [],
-))
-const parentOptions = computed(() => permissions.value.filter((item) => (
-  (access.usesServerPermissions ? item.type === '菜单' : ['目录', '菜单'].includes(item.type)) && !blockedParentIds.value.has(item.id)
-)))
-const metrics = computed(() => [
-  { label: '权限资源', value: permissions.value.length, note: access.usesServerPermissions ? 'IAM 返回的资源' : '全部权限编码' },
-  { label: '导航资源', value: permissions.value.filter((item) => ['目录','菜单'].includes(item.type)).length, note: '目录与页面入口' },
-  { label: '操作权限', value: permissions.value.filter((item) => item.type === '按钮').length, note: '控制页面操作' },
-  { label: '停用资源', value: permissions.value.filter((item) => item.status === '停用').length, note: '当前不可分配' },
-])
-
-function mapPlatformPermission(item: PlatformPermissionResource): Permission {
-  return {
-    id: String(item.id),
-    parentId: item.parentId === 0 ? null : String(item.parentId),
-    name: item.permissionName,
-    code: item.permissionCode,
-    type: item.permissionType === 'BUTTON' ? '按钮' : '菜单',
-    path: item.routePath ?? '',
-    method: item.httpMethod ?? '-',
-    status: item.status === 'ACTIVE' ? '启用' : '停用',
-    sort: item.sortNo,
-  }
-}
-
-async function loadPermissions() {
-  if (!access.usesServerPermissions) return
-  loading.value = true
-  loadError.value = null
-  serverPermissions.value = []
-  try {
-    serverPermissions.value = (await listPlatformPermissions()).map(mapPlatformPermission)
-  } catch (error) {
-    loadError.value = getApiErrorDetails(error, '权限资源加载失败，请稍后重试')
-  } finally {
-    loading.value = false
-  }
-}
-
-function openCreate(parentId: string | null = null) { Object.assign(form, emptyForm(), { parentId }); captureBaseline(); editorOpen.value = true }
-function openEdit(row: Permission) { if (access.usesServerPermissions) return; Object.assign(form, row); captureBaseline(); editorOpen.value = true }
-async function savePermission() {
-  if (!form.name.trim() || !form.code.trim()) { ElMessage.warning('请填写权限名称和权限编码'); return }
-  if (permissions.value.some((item) => item.code.toLowerCase() === form.code.toLowerCase() && item.id !== form.id)) { ElMessage.error('权限编码已经存在'); return }
-  if (access.usesServerPermissions) {
-    if (form.type === '菜单' && !form.path.trim()) { ElMessage.warning('请填写菜单路由'); return }
-    if (form.type === '按钮' && !form.parentId) { ElMessage.warning('按钮权限必须选择上级菜单'); return }
-    saving.value = true
-    try {
-      const created = await createPlatformPermission({
-        type: form.type === '按钮' ? 'BUTTON' : 'MENU',
-        code: form.code.trim(),
-        name: form.name.trim(),
-        parentId: form.parentId ? Number(form.parentId) : 0,
-        routePath: form.type === '菜单' ? form.path.trim() : null,
-        httpMethod: null,
-        sortNo: form.sort,
-      })
-      serverPermissions.value.push(mapPlatformPermission(created))
-      editorOpen.value = false
-      ElMessage.success('权限资源已创建')
-    } catch (error) {
-      ElMessage.error(getApiErrorMessage(error, '权限资源创建失败，请稍后重试'))
-    } finally {
-      saving.value = false
-    }
-    return
-  }
-  store.savePermission({ ...form, id: form.id || undefined })
-  editorOpen.value = false
-  ElMessage.success(form.id ? '权限资源已更新' : '权限资源已创建')
-}
-async function toggleStatus(row: Permission) {
-  const target = row.status === '启用' ? '停用' : '启用'
-  const directoryNotice = row.type === '目录' && target === '停用'
-    ? ' 目录仅用于组织结构，停用不会级联影响已启用的下级菜单和操作。'
-    : ''
-  try {
-    await ElMessageBox.confirm(`确认${target}权限“${row.name}”吗？${directoryNotice}`, '权限状态', { confirmButtonText: '确认', cancelButtonText: '取消' })
-    store.savePermission({ ...row, status: target })
-    ElMessage.success(`权限已${target}`)
-  } catch {
-    // 用户取消，不需要反馈。
-  }
-}
-function typeClass(type: PermissionType) { return { '目录': 'directory', '菜单': 'menu', '按钮': 'action', '接口': 'api' }[type] }
-
-onMounted(loadPermissions)
-</script>
-
-<template>
-  <div class="business-page">
-    <MetricStrip :items="metrics" />
-    <el-alert v-if="access.usesServerPermissions" type="warning" :closable="false" show-icon title="权限资源列表和新增已接入 IAM；一期真实资源仅使用菜单和按钮类型，编辑与启停接口尚未提供。" />
-    <el-alert v-if="loadError" type="error" :closable="false" show-icon role="alert"><template #title><div class="api-error-alert-title"><span>{{ loadError.message }}</span><ApiErrorMeta :details="loadError" /></div><el-button link type="danger" @click="loadPermissions">重新加载</el-button></template></el-alert>
-    <section class="surface-panel filter-panel" aria-label="权限筛选">
-      <div class="filter-fields"><el-input v-model="filters.keyword" clearable placeholder="权限名称、编码或路径" aria-label="权限关键词"><template #prefix><Search :size="16" /></template></el-input><el-select v-model="filters.type" clearable placeholder="全部类型" aria-label="权限类型"><el-option v-for="item in availablePermissionTypes" :key="item" :label="item" :value="item" /></el-select><el-select v-model="filters.status" clearable placeholder="全部状态" aria-label="权限状态"><el-option label="启用" value="启用" /><el-option label="停用" value="停用" /></el-select></div>
-      <div class="filter-actions"><el-button v-if="canCreate" type="primary" @click="openCreate(null)"><Plus :size="16" />新增权限</el-button></div>
-    </section>
-
-    <section class="surface-panel table-panel">
-      <header class="panel-heading"><div><h2>权限资源树</h2><p>目录组织菜单，按钮控制页面操作；接口权限将在服务端契约确定后补充。</p></div><div class="legend-list"><span><i class="is-menu" />目录 / 菜单</span><span><i class="is-action" />操作</span><span><i class="is-api" />接口预留</span></div></header>
-      <el-table v-loading="loading" :data="treeRows" row-key="id" default-expand-all :tree-props="{ children: 'children' }" empty-text="没有符合条件的权限资源">
-        <el-table-column label="权限名称" min-width="260"><template #default="{ row }"><div class="permission-name"><span :class="`is-${typeClass(row.type)}`"><FolderTree v-if="row.type === '目录' || row.type === '菜单'" :size="16" /><ShieldCheck v-else-if="row.type === '按钮'" :size="16" /><Braces v-else :size="16" /></span><strong>{{ row.name }}</strong></div></template></el-table-column>
-        <el-table-column label="权限编码" min-width="220"><template #default="{ row }"><code class="code-value">{{ row.code }}</code></template></el-table-column>
-        <el-table-column prop="type" label="类型" width="80" />
-        <el-table-column label="路由 / 接口" min-width="260"><template #default="{ row }"><div class="endpoint-cell"><span v-if="row.method !== '-'">{{ row.method }}</span><code>{{ row.path || '-' }}</code></div></template></el-table-column>
-        <el-table-column prop="sort" label="排序" width="72" align="right" />
-        <el-table-column label="状态" width="88"><template #default="{ row }"><StatusBadge :status="row.status" /></template></el-table-column>
-        <el-table-column label="操作" width="235" fixed="right"><template #default="{ row }"><div v-if="access.usesServerPermissions && canCreate" class="table-actions"><el-button v-if="row.type === '菜单'" link type="primary" @click="openCreate(row.id)"><Plus :size="15" />添加下级</el-button><span class="secondary-text">编辑接口待补齐</span></div><div v-else-if="access.can('system:permission:write')" class="table-actions"><el-button link type="primary" @click="openEdit(row as Permission)"><Pencil :size="15" />编辑</el-button><el-button v-if="row.type === '目录' || row.type === '菜单'" link type="primary" @click="openCreate(row.id)"><Plus :size="15" />添加下级</el-button><el-button link :type="row.status === '启用' ? 'danger' : 'success'" @click="toggleStatus(row as Permission)">{{ row.status === '启用' ? '停用' : '启用' }}</el-button></div></template></el-table-column>
-      </el-table>
-    </section>
-
-    <el-drawer v-model="editorOpen" :title="form.id ? '编辑权限资源' : '新增权限资源'" size="600px" class="business-drawer editor-drawer" :modal="false" :close-on-click-modal="false">
-      <el-form label-position="top" class="drawer-form">
-        <div class="form-section">
-          <h3>资源定义</h3>
-          <div class="form-grid two-cols">
-            <el-form-item label="权限名称" required><el-input v-model="form.name" placeholder="用户可理解的中文名称" maxlength="64" /></el-form-item>
-            <el-form-item label="权限编码" required><el-input v-model="form.code" placeholder="如 platform:customer:list" maxlength="128" /></el-form-item>
-            <el-form-item label="资源类型"><el-select v-model="form.type"><el-option v-for="item in availablePermissionTypes" :key="item" :label="item" :value="item" /></el-select></el-form-item>
-            <el-form-item label="上级资源"><el-select v-model="form.parentId" clearable placeholder="作为一级资源"><el-option v-for="item in parentOptions" :key="item.id" :label="`${item.name} (${item.code})`" :value="item.id" /></el-select></el-form-item>
-            <el-form-item v-if="form.type === '菜单' || !access.usesServerPermissions" label="路由或接口路径"><el-input v-model="form.path" placeholder="例如 /customers" /></el-form-item>
-            <el-form-item v-if="!access.usesServerPermissions" label="请求方法"><el-select v-model="form.method"><el-option v-for="item in ['-','GET','POST','PUT','PATCH','DELETE']" :key="item" :label="item" :value="item" /></el-select></el-form-item>
-            <el-form-item label="显示排序"><el-input-number v-model="form.sort" :min="0" :max="999" controls-position="right" /></el-form-item>
-            <el-form-item v-if="!access.usesServerPermissions" label="状态"><el-radio-group v-model="form.status"><el-radio-button label="启用" value="启用" /><el-radio-button label="停用" value="停用" /></el-radio-group></el-form-item>
-          </div>
-        </div>
-        <div class="form-callout"><Braces :size="18" /><div><strong>权限编码约定</strong><p>使用稳定的“业务域:资源:动作”编码；一期真实资源只创建菜单和按钮，接口鉴权由服务端实现。</p></div></div>
-      </el-form>
-      <template #footer><div class="drawer-footer"><el-button @click="editorOpen = false">取消</el-button><el-button v-if="access.usesServerPermissions ? canCreate : access.can('system:permission:write')" type="primary" :loading="saving" @click="savePermission">保存权限</el-button></div></template>
-    </el-drawer>
-  </div>
-</template>
diff --git a/src/views/RolesView.test.ts b/src/views/RolesView.test.ts
deleted file mode 100644
index 296cb1c3..00000000
--- a/src/views/RolesView.test.ts
+++ /dev/null
@@ -1,98 +0,0 @@
-import { createPinia, setActivePinia } from 'pinia'
-import { flushPromises, shallowMount } from '@vue/test-utils'
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-import { createPlatformRole, listPlatformRoles, type PlatformRoleResource } from '@/api/platformIam'
-import { useAuthStore } from '@/stores/auth'
-import RolesView from './RolesView.vue'
-
-vi.mock('@/api/platformIam', () => ({
-  createPlatformRole: vi.fn(),
-  listPlatformRoles: vi.fn(),
-}))
-
-const platformRole: PlatformRoleResource = {
-  id: 4000002,
-  tenantId: 0,
-  appCode: 'PLATFORM',
-  roleCode: 'CUSTOMER_REVIEWER',
-  roleName: '企业审核员',
-  roleType: 'SYSTEM',
-  status: 'ACTIVE',
-  description: '企业资料与入驻审核',
-}
-
-function mountView(pinia = createPinia()) {
-  setActivePinia(pinia)
-  return shallowMount(RolesView, {
-    global: {
-      plugins: [pinia],
-      directives: { loading: () => undefined },
-      stubs: {
-        'el-alert': { props: ['title'], template: '<div role="alert">{{ title }}<slot name="title" /></div>' },
-        'el-input': true,
-        'el-option': true,
-        'el-select': true,
-        'el-button': true,
-        'el-table': true,
-        'el-table-column': true,
-        'el-tag': true,
-        'el-radio-group': true,
-        'el-radio-button': true,
-        'el-drawer': {
-          props: ['modelValue'],
-          template: '<section><slot /><slot name="footer" /></section>',
-        },
-        'el-form': { template: '<form><slot /></form>' },
-        'el-form-item': { template: '<label><slot /></label>' },
-        'el-tree': {
-          props: { checkStrictly: Boolean },
-          template: '<div data-testid="permission-tree" :data-check-strictly="String(checkStrictly)" />',
-        },
-      },
-    },
-  })
-}
-
-describe('RolesView', () => {
-  beforeEach(() => {
-    setActivePinia(createPinia())
-    vi.mocked(listPlatformRoles).mockReset()
-    vi.mocked(createPlatformRole).mockReset()
-  })
-
-  it('keeps directory, menu, and action permissions independently checkable', () => {
-    const wrapper = mountView()
-
-    expect(wrapper.get('[data-testid="permission-tree"]').attributes('data-check-strictly')).toBe('true')
-  })
-
-  it('loads platform roles from IAM for a server session', async () => {
-    const pinia = createPinia()
-    setActivePinia(pinia)
-    const auth = useAuthStore()
-    auth.isServerSession = true
-    auth.permissions = ['platform:role:list', 'platform:role:create']
-    vi.mocked(listPlatformRoles).mockResolvedValue([platformRole])
-
-    const wrapper = mountView(pinia)
-    await flushPromises()
-
-    expect(listPlatformRoles).toHaveBeenCalledTimes(1)
-    expect(wrapper.text()).toContain('角色列表和新增角色已接入 IAM')
-    expect(wrapper.find('[data-testid="permission-tree"]').exists()).toBe(false)
-  })
-
-  it('keeps a failed IAM role list recoverable', async () => {
-    const pinia = createPinia()
-    setActivePinia(pinia)
-    const auth = useAuthStore()
-    auth.isServerSession = true
-    auth.permissions = ['platform:role:list']
-    vi.mocked(listPlatformRoles).mockRejectedValue(new Error('IAM unavailable'))
-
-    const wrapper = mountView(pinia)
-    await flushPromises()
-
-    expect(wrapper.findAll('[role="alert"]').map((item) => item.text()).join(' ')).toContain('IAM unavailable')
-  })
-})
diff --git a/src/views/RolesView.vue b/src/views/RolesView.vue
deleted file mode 100644
index 94f71382..00000000
--- a/src/views/RolesView.vue
+++ /dev/null
@@ -1,207 +0,0 @@
-<script setup lang="ts">
-import { computed, nextTick, onMounted, reactive, ref, watch } from 'vue'
-import { ElMessage, ElMessageBox } from 'element-plus'
-import { Pencil, Plus, RotateCcw, Search, ShieldCheck, Trash2 } from '@lucide/vue'
-import { createPlatformRole, listPlatformRoles, type PlatformRoleResource } from '@/api/platformIam'
-import { getApiErrorDetails, getApiErrorMessage, type ApiErrorDetails } from '@/api/http'
-import ApiErrorMeta from '@/components/ApiErrorMeta.vue'
-import MetricStrip from '@/components/MetricStrip.vue'
-import StatusBadge from '@/components/StatusBadge.vue'
-import { useUnsavedWorkRegistration } from '@/composables/useUnsavedWorkRegistration'
-import { useAccessPreviewStore } from '@/stores/accessPreview'
-import { useAdminDataStore } from '@/stores/adminData'
-import type { DataScope, Role } from '@/types/admin'
-import { buildPermissionTree, summarizePermissionSelection } from '@/utils/permissionTree'
-
-interface TreeController {
-  getCheckedKeys: (leafOnly?: boolean) => Array<string | number>
-  getHalfCheckedKeys: () => Array<string | number>
-  setCheckedKeys: (keys: string[]) => void
-}
-
-const store = useAdminDataStore()
-const access = useAccessPreviewStore()
-const editorOpen = ref(false)
-const treeRef = ref<TreeController | null>(null)
-const serverRoles = ref<Role[]>([])
-const loading = ref(false)
-const saving = ref(false)
-const loadError = ref<ApiErrorDetails | null>(null)
-const filters = reactive({ keyword: '', status: '', dataScope: '' })
-const emptyForm = (): Omit<Role, 'userCount'> => ({ id: '', name: '', code: '', description: '', dataScope: '本部门数据', status: '启用', permissionIds: [], builtIn: false })
-const form = reactive(emptyForm())
-const editorLabel = computed(() => form.id ? '配置角色' : '新增角色')
-const requiredPermission = computed(() => access.usesServerPermissions ? 'platform:role:create' : 'system:role:grant')
-const { captureBaseline } = useUnsavedWorkRegistration({
-  key: 'role-editor',
-  label: editorLabel,
-  isOpen: editorOpen,
-  model: form,
-  requiredPermission,
-})
-const dataScopes: DataScope[] = ['全部数据', '本部门数据', '本人数据', '自定义']
-
-const roles = computed(() => access.usesServerPermissions ? serverRoles.value : store.roles)
-const canCreate = computed(() => access.can('platform:role:create'))
-const filteredRows = computed(() => roles.value.filter((item) => {
-  const keyword = filters.keyword.trim().toLowerCase()
-  return (!keyword || [item.name, item.code, item.description].some((value) => value.toLowerCase().includes(keyword))) && (!filters.status || item.status === filters.status) && (!filters.dataScope || item.dataScope === filters.dataScope)
-}))
-const metrics = computed(() => [
-  { label: '角色总数', value: roles.value.length, note: access.usesServerPermissions ? 'IAM 返回的角色' : '平台角色模型' },
-  { label: '启用角色', value: roles.value.filter((item) => item.status === '启用').length, note: '当前可分配' },
-  { label: '授权用户', value: access.usesServerPermissions ? '—' : store.users.length, note: access.usesServerPermissions ? '成员关系待接口回显' : '已分配平台角色' },
-  { label: '权限资源', value: access.usesServerPermissions ? '—' : store.permissions.length, note: access.usesServerPermissions ? '角色授权待接口回显' : '菜单、按钮与接口' },
-])
-const permissionTree = computed(() => buildPermissionTree(store.permissions))
-
-watch(() => form.dataScope, () => undefined)
-
-function resetFilters() { Object.assign(filters, { keyword: '', status: '', dataScope: '' }) }
-
-function mapPlatformRole(role: PlatformRoleResource): Role {
-  return {
-    id: String(role.id),
-    name: role.roleName,
-    code: role.roleCode,
-    description: role.description ?? '暂无角色说明',
-    userCount: 0,
-    dataScope: '全部数据',
-    status: role.status === 'ACTIVE' ? '启用' : '停用',
-    permissionIds: [],
-    builtIn: role.roleType === 'SYSTEM',
-  }
-}
-
-async function loadRoles() {
-  if (!access.usesServerPermissions) return
-  loading.value = true
-  loadError.value = null
-  serverRoles.value = []
-  try {
-    serverRoles.value = (await listPlatformRoles()).map(mapPlatformRole)
-  } catch (error) {
-    loadError.value = getApiErrorDetails(error, '平台角色列表加载失败，请稍后重试')
-  } finally {
-    loading.value = false
-  }
-}
-
-function openCreate() {
-  Object.assign(form, emptyForm())
-  captureBaseline()
-  editorOpen.value = true
-  nextTick(() => treeRef.value?.setCheckedKeys([]))
-}
-function openEdit(row: Role) {
-  if (access.usesServerPermissions) return
-  Object.assign(form, { ...row, permissionIds: [...row.permissionIds] })
-  captureBaseline()
-  editorOpen.value = true
-  nextTick(() => treeRef.value?.setCheckedKeys([...row.permissionIds]))
-}
-
-function selectedPermissionIds() {
-  const checked = treeRef.value?.getCheckedKeys(false).map(String) || []
-  const halfChecked = treeRef.value?.getHalfCheckedKeys().map(String) || []
-  return [...new Set([...checked, ...halfChecked])]
-}
-
-function syncPermissionIds() {
-  form.permissionIds = selectedPermissionIds()
-}
-
-async function saveRole() {
-  if (!form.name.trim() || !form.code.trim()) { ElMessage.warning('请填写角色名称和角色编码'); return }
-  const normalizedCode = form.code.trim().toUpperCase()
-  const duplicate = roles.value.some((item) => item.code.toLowerCase() === normalizedCode.toLowerCase() && item.id !== form.id)
-  if (duplicate) { ElMessage.error('角色编码已经存在'); return }
-  if (access.usesServerPermissions) {
-    saving.value = true
-    try {
-      const created = await createPlatformRole({
-        roleCode: normalizedCode,
-        roleName: form.name.trim(),
-        description: form.description.trim(),
-      })
-      serverRoles.value.unshift(mapPlatformRole(created))
-      editorOpen.value = false
-      ElMessage.success('角色已创建')
-    } catch (error) {
-      ElMessage.error(getApiErrorMessage(error, '角色创建失败，请稍后重试'))
-    } finally {
-      saving.value = false
-    }
-    return
-  }
-  const permissionIds = selectedPermissionIds()
-  if (permissionIds.length === 0) { ElMessage.warning('请至少选择一项菜单权限'); return }
-  store.saveRole({ ...form, id: form.id || undefined, permissionIds })
-  editorOpen.value = false
-  ElMessage.success(form.id ? '角色及权限已更新' : '角色已创建')
-}
-
-async function removeRole(row: Role) {
-  if (row.builtIn) { ElMessage.warning('系统内置角色不能删除'); return }
-  if (row.userCount > 0) { ElMessage.warning('请先移除该角色下的用户'); return }
-  try {
-    await ElMessageBox.confirm(`确认删除角色“${row.name}”吗？`, '删除角色', { confirmButtonText: '删除', cancelButtonText: '取消', type: 'warning' })
-    if (store.removeRole(row.id)) ElMessage.success('角色已删除')
-  } catch {
-    // 用户取消，不需要反馈。
-  }
-}
-
-async function toggleStatus(row: Role) {
-  if (row.builtIn) { ElMessage.warning('系统内置角色不能停用'); return }
-  const target = row.status === '启用' ? '停用' : '启用'
-  try {
-    await ElMessageBox.confirm(`确认${target}角色“${row.name}”吗？`, '角色状态', { confirmButtonText: '确认', cancelButtonText: '取消' })
-    store.saveRole({ ...row, status: target })
-    ElMessage.success(`角色已${target}`)
-  } catch {
-    // 用户取消，不需要反馈。
-  }
-}
-
-function permissionSummary(row: Role) {
-  if (access.usesServerPermissions) return '待授权回显接口'
-  const { menuCount, actionCount } = summarizePermissionSelection(store.permissions, row.permissionIds)
-  return `${menuCount} 菜单 · ${actionCount} 操作`
-}
-
-onMounted(loadRoles)
-</script>
-
-<template>
-  <div class="business-page">
-    <MetricStrip :items="metrics" />
-    <el-alert v-if="access.usesServerPermissions" type="warning" :closable="false" show-icon title="角色列表和新增角色已接入 IAM；编辑、启停、删除及已有权限回显接口尚未提供，相关操作暂不开放。" />
-    <el-alert v-if="loadError" type="error" :closable="false" show-icon role="alert"><template #title><div class="api-error-alert-title"><span>{{ loadError.message }}</span><ApiErrorMeta :details="loadError" /></div><el-button link type="danger" @click="loadRoles">重新加载</el-button></template></el-alert>
-    <section class="surface-panel filter-panel" aria-label="角色筛选">
-      <div class="filter-fields"><el-input v-model="filters.keyword" clearable placeholder="角色名称、编码或描述" aria-label="角色关键词"><template #prefix><Search :size="16" /></template></el-input><el-select v-if="!access.usesServerPermissions" v-model="filters.dataScope" clearable placeholder="全部数据范围" aria-label="数据范围"><el-option v-for="item in ['全部数据','本部门数据','本人数据','自定义']" :key="item" :label="item" :value="item" /></el-select><el-select v-model="filters.status" clearable placeholder="全部状态" aria-label="角色状态"><el-option label="启用" value="启用" /><el-option label="停用" value="停用" /></el-select></div>
-      <div class="filter-actions"><el-button @click="resetFilters"><RotateCcw :size="16" />重置</el-button><el-button v-if="canCreate" type="primary" @click="openCreate"><Plus :size="16" />新增角色</el-button></div>
-    </section>
-
-    <section class="surface-panel table-panel">
-      <header class="panel-heading"><div><h2>角色与授权</h2><p>角色负责聚合菜单、操作和数据范围，内部用户可分配多个角色。</p></div></header>
-      <el-table v-loading="loading" :data="filteredRows" row-key="id" empty-text="没有符合条件的角色">
-        <el-table-column label="角色" min-width="210"><template #default="{ row }"><div class="role-cell"><span><ShieldCheck :size="18" /></span><div><strong>{{ row.name }}</strong><small>{{ row.code }}</small></div></div></template></el-table-column>
-        <el-table-column prop="description" label="说明" min-width="240" show-overflow-tooltip />
-        <el-table-column label="授权范围" min-width="170"><template #default="{ row }"><div class="primary-cell"><strong>{{ permissionSummary(row as Role) }}</strong><span>{{ access.usesServerPermissions ? '数据范围待接口提供' : row.dataScope }}</span></div></template></el-table-column>
-        <el-table-column label="用户数" width="86" align="right"><template #default="{ row }">{{ access.usesServerPermissions ? '—' : row.userCount }}</template></el-table-column>
-        <el-table-column label="类型" width="95"><template #default="{ row }"><el-tag :type="row.builtIn ? 'warning' : 'info'" effect="plain" size="small">{{ row.builtIn ? '系统内置' : '自定义' }}</el-tag></template></el-table-column>
-        <el-table-column label="状态" width="88"><template #default="{ row }"><StatusBadge :status="row.status" /></template></el-table-column>
-        <el-table-column label="操作" width="235" fixed="right"><template #default="{ row }"><span v-if="access.usesServerPermissions" class="secondary-text">接口待补齐</span><div v-else-if="access.can('system:role:grant')" class="table-actions"><el-button link type="primary" @click="openEdit(row as Role)"><Pencil :size="15" />配置</el-button><el-button link :type="row.status === '启用' ? 'danger' : 'success'" :disabled="row.builtIn" @click="toggleStatus(row as Role)">{{ row.status === '启用' ? '停用' : '启用' }}</el-button><el-button link type="danger" :disabled="row.builtIn || row.userCount > 0" @click="removeRole(row as Role)"><Trash2 :size="15" />删除</el-button></div></template></el-table-column>
-      </el-table>
-    </section>
-
-    <el-drawer v-model="editorOpen" :title="form.id ? '配置角色' : '新增角色'" size="760px" class="business-drawer editor-drawer" :modal="false" :close-on-click-modal="false">
-      <el-form label-position="top" class="drawer-form">
-        <div class="form-section"><h3>基本信息</h3><div class="form-grid two-cols"><el-form-item label="角色名称" required><el-input v-model="form.name" maxlength="64" /></el-form-item><el-form-item label="角色编码" required><el-input v-model="form.code" :disabled="Boolean(form.builtIn)" placeholder="如 OPS_MANAGER" maxlength="64" /></el-form-item><el-form-item v-if="!access.usesServerPermissions" label="数据范围"><el-select v-model="form.dataScope"><el-option v-for="item in dataScopes" :key="item" :label="item" :value="item" /></el-select></el-form-item><el-form-item v-if="!access.usesServerPermissions" label="状态"><el-radio-group v-model="form.status" :disabled="Boolean(form.builtIn)"><el-radio-button label="启用" value="启用" /><el-radio-button label="停用" value="停用" /></el-radio-group></el-form-item></div><el-form-item label="角色说明"><el-input v-model="form.description" type="textarea" :rows="2" maxlength="200" show-word-limit /></el-form-item></div>
-        <div v-if="!access.usesServerPermissions" class="form-section permission-section"><div class="section-heading-row"><div><h3>菜单与操作权限</h3><p>目录仅用于组织结构且独立授权；停用目录不会级联停用已启用的菜单和操作。</p></div><span>{{ form.permissionIds.length }} 项原有授权</span></div><el-tree ref="treeRef" class="permission-tree" :data="permissionTree" node-key="id" show-checkbox check-strictly default-expand-all :props="{ label: 'name', children: 'children' }" @check="syncPermissionIds"><template #default="{ data }"><div class="permission-node"><span>{{ data.name }}</span><code>{{ data.code }}</code></div></template></el-tree></div>
-      </el-form>
-      <template #footer><div class="drawer-footer"><el-button @click="editorOpen = false">取消</el-button><el-button v-if="access.usesServerPermissions ? canCreate : access.can('system:role:grant')" type="primary" :loading="saving" @click="saveRole">保存角色</el-button></div></template>
-    </el-drawer>
-  </div>
-</template>
diff --git a/src/views/WarehousesView.vue b/src/views/WarehousesView.vue
deleted file mode 100644
index fe4492bc..00000000
--- a/src/views/WarehousesView.vue
+++ /dev/null
@@ -1,165 +0,0 @@
-<script setup lang="ts">
-import { computed, reactive, ref, watch } from 'vue'
-import { ElMessage, ElMessageBox } from 'element-plus'
-import { MapPin, Pencil, Plus, Power, RotateCcw, Search, Warehouse as WarehouseIcon } from '@lucide/vue'
-import MetricStrip from '@/components/MetricStrip.vue'
-import { useUnsavedWorkRegistration } from '@/composables/useUnsavedWorkRegistration'
-import { useAccessPreviewStore } from '@/stores/accessPreview'
-import { useAdminDataStore } from '@/stores/adminData'
-import type { Warehouse } from '@/types/admin'
-
-const store = useAdminDataStore()
-const access = useAccessPreviewStore()
-const editorOpen = ref(false)
-const page = ref(1)
-const pageSize = 10
-const filters = reactive({ keyword: '', status: '' as Warehouse['status'] | '' })
-
-const emptyForm = (): Omit<Warehouse, 'updatedAt'> => ({
-  id: '', code: '', name: '', province: '', city: '', address: '', contactName: '', contactPhone: '',
-  businessHours: '周一至周六 08:30-18:00', status: 'ACTIVE', remark: '',
-})
-const form = reactive(emptyForm())
-const editorLabel = computed(() => form.id ? '编辑收货仓' : '新增收货仓')
-const editorPermission = computed(() => 'warehouse:write')
-const { captureBaseline } = useUnsavedWorkRegistration({
-  key: 'warehouse-editor',
-  label: editorLabel,
-  isOpen: editorOpen,
-  model: form,
-  requiredPermission: editorPermission,
-})
-
-const filteredRows = computed(() => store.warehouses.filter((warehouse) => {
-  const keyword = filters.keyword.trim().toLowerCase()
-  const matchesKeyword = !keyword || [warehouse.code, warehouse.name, warehouse.province, warehouse.city, warehouse.address]
-    .some((value) => value.toLowerCase().includes(keyword))
-  return matchesKeyword && (!filters.status || warehouse.status === filters.status)
-}))
-const pagedRows = computed(() => filteredRows.value.slice((page.value - 1) * pageSize, page.value * pageSize))
-const metrics = computed(() => [
-  { label: '全部收货仓', value: store.warehouses.length, note: '平台仓库档案' },
-  { label: '启用仓库', value: store.activeWarehouses, note: '客户当前可选择' },
-  { label: '暂停接单', value: store.warehouses.filter((item) => item.status === 'INACTIVE').length, note: '不出现在客户下单选项' },
-  { label: '覆盖城市', value: new Set(store.warehouses.map((item) => item.city)).size, note: '国内收货区域' },
-])
-
-watch(filters, () => { page.value = 1 })
-watch(
-  () => access.can('warehouse:write'),
-  (canWrite) => {
-    if (canWrite || !editorOpen.value) return
-    editorOpen.value = false
-    Object.assign(form, emptyForm())
-  },
-  { flush: 'sync' },
-)
-
-function resetFilters() {
-  filters.keyword = ''
-  filters.status = ''
-}
-
-function openCreate() {
-  Object.assign(form, emptyForm())
-  captureBaseline()
-  editorOpen.value = true
-}
-
-function openEdit(warehouse: Warehouse) {
-  Object.assign(form, warehouse)
-  captureBaseline()
-  editorOpen.value = true
-}
-
-function saveWarehouse() {
-  if (!form.code.trim() || !form.name.trim() || !form.city.trim() || !form.address.trim()) {
-    ElMessage.warning('请填写仓库编码、名称、城市和详细地址')
-    return
-  }
-  try {
-    store.saveWarehouse({ ...form, id: form.id || undefined })
-    editorOpen.value = false
-    ElMessage.success(form.id ? '仓库资料已更新' : '收货仓已创建')
-  } catch (error) {
-    ElMessage.error(error instanceof Error ? error.message : '仓库保存失败')
-  }
-}
-
-async function toggleStatus(warehouse: Warehouse) {
-  const target = warehouse.status === 'ACTIVE' ? 'INACTIVE' : 'ACTIVE'
-  const targetText = target === 'ACTIVE' ? '启用' : '停用'
-  try {
-    await ElMessageBox.confirm(
-      target === 'INACTIVE'
-        ? `停用“${warehouse.name}”后，客户新建头程订单时将无法选择该仓库。`
-        : `确认重新启用“${warehouse.name}”供客户下单选择吗？`,
-      `${targetText}收货仓`,
-      { confirmButtonText: `确认${targetText}`, cancelButtonText: '取消', type: target === 'INACTIVE' ? 'warning' : 'info' },
-    )
-    store.setWarehouseStatus(warehouse.id, target)
-    ElMessage.success(`仓库已${targetText}`)
-  } catch (error) {
-    if (error === 'cancel' || error === 'close') return
-    throw error
-  }
-}
-</script>
-
-<template>
-  <div class="business-page">
-    <MetricStrip :items="metrics" />
-
-    <section class="surface-panel filter-panel" aria-label="仓库筛选">
-      <div class="filter-fields">
-        <el-input v-model="filters.keyword" clearable placeholder="仓库名称、编码、城市或地址" aria-label="仓库关键词">
-          <template #prefix><Search :size="16" /></template>
-        </el-input>
-        <el-select v-model="filters.status" clearable placeholder="全部状态" aria-label="仓库状态">
-          <el-option label="启用" value="ACTIVE" /><el-option label="停用" value="INACTIVE" />
-        </el-select>
-      </div>
-      <div class="filter-actions">
-        <el-button @click="resetFilters"><RotateCcw :size="16" />重置</el-button>
-        <el-button v-if="access.can('warehouse:write')" type="primary" @click="openCreate"><Plus :size="16" />新增仓库</el-button>
-      </div>
-    </section>
-
-    <section class="surface-panel table-panel">
-      <div class="panel-heading"><div><h2>平台收货仓</h2><p>仅启用仓库会进入客户头程下单选项</p></div></div>
-      <el-table v-if="pagedRows.length" :data="pagedRows" row-key="id">
-        <el-table-column label="仓库" min-width="200">
-          <template #default="{ row }"><div class="warehouse-cell"><span><WarehouseIcon :size="18" /></span><div><strong>{{ (row as Warehouse).name }}</strong><small>{{ (row as Warehouse).code }}</small></div></div></template>
-        </el-table-column>
-        <el-table-column label="所在城市" min-width="130"><template #default="{ row }">{{ (row as Warehouse).province }} · {{ (row as Warehouse).city }}</template></el-table-column>
-        <el-table-column label="收货地址" min-width="260"><template #default="{ row }"><div class="warehouse-address"><MapPin :size="15" />{{ (row as Warehouse).address }}</div></template></el-table-column>
-        <el-table-column label="联系人" min-width="150"><template #default="{ row }"><strong>{{ (row as Warehouse).contactName || '-' }}</strong><span class="warehouse-subline">{{ (row as Warehouse).contactPhone || '-' }}</span></template></el-table-column>
-        <el-table-column label="收货时间" prop="businessHours" min-width="190" />
-        <el-table-column label="状态" width="100"><template #default="{ row }"><el-tag :type="(row as Warehouse).status === 'ACTIVE' ? 'success' : 'info'" effect="light">{{ (row as Warehouse).status === 'ACTIVE' ? '启用' : '停用' }}</el-tag></template></el-table-column>
-        <el-table-column label="操作" width="180">
-          <template #default="{ row }"><div v-if="access.can('warehouse:write')" class="table-actions"><el-button link type="primary" @click="openEdit(row as Warehouse)"><Pencil :size="15" />编辑</el-button><el-button link :type="(row as Warehouse).status === 'ACTIVE' ? 'danger' : 'success'" @click="toggleStatus(row as Warehouse)"><Power :size="15" />{{ (row as Warehouse).status === 'ACTIVE' ? '停用' : '启用' }}</el-button></div><span v-else class="warehouse-subline">仅查看</span></template>
-        </el-table-column>
-      </el-table>
-      <el-empty v-else description="没有符合条件的仓库" />
-      <div class="table-footer"><span>共 {{ filteredRows.length }} 个收货仓</span><el-pagination v-model:current-page="page" :page-size="pageSize" :total="filteredRows.length" layout="prev, pager, next" /></div>
-    </section>
-
-    <el-drawer v-model="editorOpen" :title="editorLabel" size="620px" class="business-drawer editor-drawer" :close-on-click-modal="false">
-      <el-form label-position="top" class="drawer-form">
-        <div class="form-section"><h3>仓库标识</h3><div class="form-grid two-cols"><el-form-item label="仓库编码" required><el-input v-model="form.code" maxlength="32" placeholder="例如 CN-NB-01" /></el-form-item><el-form-item label="仓库名称" required><el-input v-model="form.name" maxlength="100" placeholder="客户下单时显示的名称" /></el-form-item><el-form-item label="状态"><el-radio-group v-model="form.status"><el-radio-button value="ACTIVE">启用</el-radio-button><el-radio-button value="INACTIVE">停用</el-radio-button></el-radio-group></el-form-item></div></div>
-        <div class="form-section"><h3>地址与收货</h3><div class="form-grid two-cols"><el-form-item label="省份"><el-input v-model="form.province" maxlength="40" /></el-form-item><el-form-item label="城市" required><el-input v-model="form.city" maxlength="40" /></el-form-item><el-form-item label="联系人"><el-input v-model="form.contactName" maxlength="50" /></el-form-item><el-form-item label="联系电话"><el-input v-model="form.contactPhone" maxlength="30" /></el-form-item><el-form-item label="收货时间"><el-input v-model="form.businessHours" maxlength="100" /></el-form-item></div><el-form-item label="详细地址" required><el-input v-model="form.address" maxlength="300" type="textarea" :rows="3" /></el-form-item></div>
-        <div class="form-section"><h3>备注</h3><el-form-item label="客户可理解的收货说明"><el-input v-model="form.remark" maxlength="500" type="textarea" :rows="3" show-word-limit /></el-form-item></div>
-      </el-form>
-      <template #footer><div class="drawer-footer"><el-button @click="editorOpen = false">取消</el-button><el-button type="primary" @click="saveWarehouse">保存仓库</el-button></div></template>
-    </el-drawer>
-  </div>
-</template>
-
-<style scoped>
-.warehouse-cell { display: flex; align-items: center; gap: 10px; }
-.warehouse-cell > span { display: grid; width: 34px; height: 34px; flex: 0 0 34px; place-items: center; border-radius: 7px; background: #eef3fa; color: var(--cc-primary); }
-.warehouse-cell > div { display: flex; min-width: 0; flex-direction: column; gap: 3px; }
-.warehouse-cell small, .warehouse-subline { display: block; color: var(--cc-muted); font-size: 11px; }
-.warehouse-address { display: flex; align-items: flex-start; gap: 7px; line-height: 1.55; }
-.warehouse-address svg { flex: 0 0 15px; margin-top: 2px; color: var(--cc-muted); }
-</style>
diff --git a/vite.config.ts b/vite.config.ts
index e5d2d0ce..336c3c00 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -7,7 +7,11 @@ import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'
 
 export default defineConfig(({ mode }) => {
   const env = loadEnv(mode, process.cwd(), '')
-  const proxyTarget = env.API_PROXY_TARGET || 'http://localhost:8080'
+  const proxyTarget = process.env.API_PROXY_TARGET || env.API_PROXY_TARGET || 'http://localhost:8080'
+  const authProxyTarget = process.env.AUTH_API_PROXY_TARGET || env.AUTH_API_PROXY_TARGET || proxyTarget
+  const iamProxyTarget = process.env.IAM_API_PROXY_TARGET || env.IAM_API_PROXY_TARGET || proxyTarget
+  const warehouseProxyTarget = process.env.WAREHOUSE_API_PROXY_TARGET || env.WAREHOUSE_API_PROXY_TARGET || proxyTarget
+  const overseasProxyTarget = process.env.OVERSEAS_API_PROXY_TARGET || env.OVERSEAS_API_PROXY_TARGET || 'http://localhost:9300'
 
   return {
     plugins: [
@@ -27,10 +31,53 @@ export default defineConfig(({ mode }) => {
       },
     },
     server: {
+      strictPort: true,
       proxy: {
+        '/api/auth': {
+          target: authProxyTarget,
+          changeOrigin: true,
+          configure(proxy) {
+            proxy.on('proxyReq', (proxyRequest) => {
+              proxyRequest.removeHeader('origin')
+            })
+          },
+        },
+        '/api/platform/v1/iam': {
+          target: iamProxyTarget,
+          changeOrigin: true,
+          configure(proxy) {
+            proxy.on('proxyReq', (proxyRequest) => {
+              proxyRequest.removeHeader('origin')
+            })
+          },
+        },
+        '/api/platform/v1/warehouse-admin': {
+          target: warehouseProxyTarget,
+          changeOrigin: true,
+          configure(proxy) {
+            proxy.on('proxyReq', (proxyRequest) => {
+              proxyRequest.removeHeader('origin')
+            })
+          },
+        },
         '/api': {
           target: proxyTarget,
           changeOrigin: true,
+          configure(proxy) {
+            proxy.on('proxyReq', (proxyRequest) => {
+              proxyRequest.removeHeader('origin')
+            })
+          },
+        },
+        '/overseas-api': {
+          target: overseasProxyTarget,
+          changeOrigin: true,
+          rewrite: (path) => path.replace(/^\/overseas-api/, '/api'),
+          configure(proxy) {
+            proxy.on('proxyReq', (proxyRequest) => {
+              proxyRequest.removeHeader('origin')
+            })
+          },
         },
       },
     },
diff --git a/vitest.phase4-development.config.ts b/vitest.phase4-development.config.ts
new file mode 100644
index 00000000..d97a8405
--- /dev/null
+++ b/vitest.phase4-development.config.ts
@@ -0,0 +1,15 @@
+import { fileURLToPath, URL } from 'node:url'
+import { defineConfig } from 'vitest/config'
+import vue from '@vitejs/plugin-vue'
+
+export default defineConfig({
+  plugins: [vue()],
+  resolve: { alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) } },
+  test: {
+    environment: 'jsdom',
+    include: ['scripts/phase4-development-frontend.acceptance.ts'],
+    fileParallelism: false,
+    testTimeout: 120_000,
+    hookTimeout: 120_000,
+  },
+})