This commit is contained in:
2026-09-14 20:03:25 +08:00
parent ee5e83104c
commit 6e5f7c71eb
6 changed files with 73 additions and 4 deletions
+47
View File
@@ -0,0 +1,47 @@
# Admin 海外仓样式核对记录
## 范围与依据
本轮用户确认继续“海外仓”模块。范围以 `adminNavigation.ts` 的 `overseas-inventory` 分组为准,包含 10 个菜单、对应独立详情和实际调用的作业弹框。客户服务、海外业务、隐藏产品库和旧箱号页面不在范围内。
视觉采用 [Admin 高密度界面规范](Admin高密度界面规范.md),保留当前路由、字段、权限、服务端状态资格及操作承载方式。原型入口为 `悦/货代SAAS平台后台/prototype-src/modules/03-overseas-warehouse.html`;入库、出库、换标、托盘详情分别见 706、714、720、726 行,尾程列表/详情见 894/927 行,库存详情/流水见 974/1022 行。当前真实业务契约优先于历史原型占位。
## 修改前逐操作矩阵
页面文件均相对 `apps/admin-web/src/modules/overseas-warehouse/`。原型未覆盖的新操作保留现有承载方式,不新增业务流程。
| 菜单/入口 | 操作及源码证据 | 当前承载与尺寸 | 本轮结论 |
|---|---|---|---|
| 尾程订单 | `LastMileOrdersView` 查询、导出、查看、更多;`LastMileOrderDetailView` | 独立详情;基本/货物/计划/费用/日志页签 | 纯文字行内按钮、彩色页签、连续信息表、同行返回 |
| 尾程订单 | `transferOpen`、`inboundPlanOpen` | 转仓默认宽度、入库计划 720px 居中框 | 保留确认、候选、版本,接入弹框密度 |
| 尾程订单 | `containerConvertOpen`、`containerDetailOpen`、`receivingWarehouseOpen` | 预览 1240px、柜详情 1120px、接柜仓 600px | 保留逐柜预览/阻断及当前隐藏入口,不恢复隐藏菜单 |
| 尾程订单 | `holdOpen`、`manualNodesOpen` | 暂扣 620px、节点 700px | 保留原因、计费、节点原子提交,紧凑表单 |
| 尾程订单 | `WarehouseTransferReviewDialog` | 转运审核 920px | 保留审核/驳回、货物与打托实测、按钮资格 |
| 尾程详情 | `feeDialogOpen` | 新增费用 720px | 保留金额/币种/保存流程 |
| 入库单 | `InboundOrdersView` 查看、编辑计划、预约;`InboundOrderDetailView` | 独立详情;预约 1080px;计划编辑默认框 | 保留只读费用空态、预约模式,统一按钮与描述表 |
| 入库单 | `SmartDispatchDialog` | 1800px 三栏作业框;车型选择 360px | 保留拖拽、锁定、容量、超重与预排车;只压缩普通控件 |
| 排车列表 | `DispatchesView` 查看、BOL、更多、取消;`DispatchDetailView` | 独立详情;PDF 原打印流程;取消确认框 | 保留返回目标、直接操作及危险确认 |
| 排车列表 | `transferOpen`、`editOpen`、`removePallet` | 转派送 1120px;编辑 900px;移除确认框 | 保留费用/箱唛/托盘事实,描边行内操作 |
| 出库单 | `OutboundsView` 新建、查看、取消;`OutboundDetailView` | 新建 1320px;独立详情;取消原因框 | 保留一件代发/退货两模式、选择表、PDA 提交 |
| 派送单列表 | `DeliveryOrdersView` 查看、编辑状态、标记退货 | 独立详情;状态 520px;退货 720px | 保留原出库明细可退数量与去向;统一按钮 |
| 派送详情 | `DeliveryOrderDetailView` 四页签 | 订单/SKU/费用/操作,内容在页签内 | 彩色页签且所有正文保持可见,去重复正文标题 |
| 派送单资料 | `DeliveryDocumentsDialog` 上传、替换、删除、下载、保存、重新加载确认 | 1040px;关闭放弃未保存修改 | 保留文件生命周期,正文单一滚动区 |
| 换标单 | `RelabelOrdersView` 新增、审核、查看 | 760px 表单;独立详情 | 保留创建与审核模式、状态候选与必填字段 |
| 换标详情 | `RelabelOrderDetailView` 完工证据、总 PDF、明细 PDF 上传/预览 | 连续详情、预览 900px | 保留 PDF 物理预览尺寸与绑定数据,紧凑文件行 |
| 托盘管理 | `PalletsView` 汇总、新增、编辑、查看;`PalletDetailView` | 760px 表单;独立详情 | 汇总改紧凑行;保留仓库编辑限制 |
| 库存管理 | `InventoryView` 汇总、查看、导出;`InventoryDetailView` | 独立详情,库位/托盘箱号/流水表 | 连续汇总、信息表;不改变库存口径 |
| 库存流水 | `InventoryTransactionsView` 导出、返回、关联数据 | 列表深链;共享关联框 1060px | 只为本轮调用显式接入共享框,保留分区域只读权限 |
| 退货库存管理 | `ReturnInventoryManagementView mode=inventory` | 库存/流水页签、查询、分页 | 两页签保留各自数据和查询模式 |
| 退货箱号管理 | `ReturnInventoryManagementView mode=cartons` 查看、箱唛打印 | 详情 1080px;现有 HTML 打印 | 统一详情按钮/信息表,不修改打印内容或尺寸 |
## 共享边界和验收
- `OverseasDetailShell`、`OverseasReadOnlyDetail`、`InboundCodeRelationshipDialog` 显式 `dense` 接入;默认调用保持原样。
- 公共字号、间距、按钮、页签和键值表只使用公共密度变量与类;模块仅保留业务布局与作业区尺寸。
- 最终全量 `pnpm test --maxWorkers=4`:1,927 项通过;`pnpm typecheck`、`pnpm build` 通过;索引合同 1,050 项通过。新增合同核对 10 个导航入口、两种退货模式、详情祖先样式、Teleport 接入和共享组件关闭状态。
- 尾程与派送详情的 `density-contained-tabs` 保留所有页签正文;智能排车将原操作按钮移入固定 footer 插槽,保留预排车事件与原三栏作业区。
- 页面事件、请求和状态门禁保持原有业务逻辑;本轮没有部署或修改环境数据。复核修正托盘标题的内部 ID 回退,出库仓库名称仅采用同仓关联派送返回的名称;缺失或关联不一致时显示“—”。托盘 DTO 目前未返回库位编码,详情保留空值,不展示 `locationId`。
- 托盘汇总移除与页面 `gap` 叠加的底部间距;删除已被公共按钮组接管的局部间距及空样式规则。
- 默认高并发全量回归出现分散用例的偶发失败;失败项定向复跑通过,随后在不修改断言或超时的情况下限制为 4 并发,全量通过。托盘加载/失败时不展示内部 ID、出库仓库名称匹配/缺失/不一致均有组件回归证据。
- 本地 5173 端口的 Vite 服务进程指向当前 `chongchong-global/apps/admin-web` 工作区;这只证明服务路径,不代替页面视觉证据。
- 全部 10 个菜单及详情/弹框均 **待人工截图确认**,验收为 1920×1080、浏览器缩放 100%。
+8
View File
@@ -69,3 +69,11 @@
- `CarrierScheduleQueryPanel` 增加可选 `dense`;订舱和货柜详情开启,独立船期入口未开启;原有无密度模式用原尺寸兜底。
- 修改仅涉及样式、布局、图标及可选密度参数;不修改 API、业务权限、字段、提交资格或状态推导。图片原图、标签和 PDF 输出保持原功能。
- 密度合同显式登记 4 个菜单、独立新建/详情和实际子组件,分别检查 DOMESTIC/OVERSEAS 入口、共享组件开启/关闭及预装/已确认模式。原有国内仓与客户管理清单保留。
## 2026-09-14 代码验证结果
- 货柜、订舱、拖车、船期、清单与公共密度定向回归:53 个文件、485 项通过;补充的原生表、共享入口检查及智能装柜/双工作台回归 50 项通过。
- 最终全量 `pnpm test`:249 个文件、1918 项全部通过。首次全量运行中仅跨模块状态合同仍锁定拖车旧图标,更新外观断言后完整复跑通过;原权限、状态、路由和业务提交断言保留。
- `pnpm typecheck`、`pnpm build` 与 `git diff --check` 通过;AGENTS 索引合同 1050 项通过。
- 本轮业务脚本与修改前版本对比,仅增加样式导入、确认浮层类和可选密度参数,没有修改业务处理逻辑。实际浏览器加载、长数据布局、浮层普通/全屏/重开及各权限状态仍待 1920×1080、100% 缩放人工截图确认。
- 本轮未部署、未启动后端或修改业务数据。代码验证不替代实际业务写入及视觉验收。
+7 -3
View File
@@ -6,7 +6,7 @@
本规范固定该样板的视觉与密度规则。验收视口为 **1920×1080,浏览器缩放 100%**。其他页面采用本规范不等于其功能或视觉已验收。
这是一套后续 Admin 页面可复用的基线。新增菜单按“新模块接入规则”实施,不复制订单或客户模块 CSS;货柜管理的入口与共享组件边界见 [货柜管理核对记录](Admin货柜管理样式核对记录.md)。列入下一批入口不代表页面已完成改造或验收。
这是一套后续 Admin 页面可复用的基线。新增菜单按“新模块接入规则”实施,不复制订单或客户模块 CSS;货柜管理的入口与共享组件边界见 [货柜管理核对记录](Admin货柜管理样式核对记录.md)。海外仓的 10 个菜单及共享详情边界见 [海外仓核对记录](Admin海外仓样式核对记录.md)。列入下一批入口不代表页面已完成改造或验收。
当前推广范围包括 Admin 导航中的“国内仓”,以及本轮确认的“客户管理”两个入口:客户列表、海外仓阶梯费用,包含各入口实际使用的详情、页签、新增、编辑、审核、确认、图片/文件预览和其他业务弹框。客户管理下的海外仓阶梯费用属于客户费用配置,不扩大到海外仓作业菜单。跨菜单跳转应记录目标入口和共享组件影响;不因此把另一个菜单的全部页面自动加入改造范围。Client、PDA 与其他菜单采用规范时另行明确范围。
@@ -184,6 +184,10 @@
| 描边按钮外观、悬停/禁用/焦点状态 | `adminDensity.css` 的 `.density-action` | 只选择 `data-tone` 与业务事件 |
| 详情返回导航 | `.density-back` | 使用 `link`,保留返回事件和可访问名称;客户管理按纯文字约定保留返回文字 |
| 详情页签及彩色图标 | `.density-tabs`、`.density-tab-icon` | 保留标签、键盘事件和激活态;只配置业务内容 |
| 现有 Element 详情页签 | `.density-element-tabs` | 保留 `el-tabs` 的键盘处理、权限条件与切换事件,标签复用彩色图标 |
| 现有原生资料表、状态历史表 | `.density-table` | 保留字段、记录排序、业务列宽和固定操作列;不另写行高、边线和表头底色 |
| 分组页面与弹框表单 | `.density-form` | 显式接入统一标签字号和字段间距,模块只维护列数、跨列及字段顺序 |
| Element 描述表 | `.density-descriptions` | 页面显式接入统一标签/内容字号与行高;保留原字段及列数 |
| 连续信息表边框、标签底色、文字与内边距 | `.density-fields` | 只配置列数、跨列、字段顺序;特殊标签宽度使用局部 `--admin-field-label-width` |
| 弹框/抽屉标题、正文滚动、底部间距 | `.admin-density-dialog` / `.admin-density-drawer` | 容器显式接入,保留该业务已确认宽度与作业高度 |
| 客户资质列、测量对照列、预装信息布局 | 对应模块 CSS 或页面 `scoped` | 只保留业务列宽、列数、图片尺寸、定位与排列 |
@@ -247,7 +251,7 @@
</AdminPage>
```
此结构只说明样式接入,不授权新增审核等业务动作。详情复用页面根节点的 `admin-density`;原生详情页签用 `density-tabs` / `density-tab-icon`,连续信息表用 `density-fields`。返回按钮使用 `link class="density-back"`,跟编号、状态排在同一行。
此结构只说明样式接入,不授权新增审核等业务动作。详情复用页面根节点的 `admin-density`;原生详情页签用 `density-tabs` / `density-tab-icon`,连续信息表用 `density-fields`。既有 Element 页签使用 `density-element-tabs`;页签栏与正文分离时隐藏空内容容器。在 `el-tab-pane` 内承载正文的页面必须同时使用 `density-contained-tabs`,保留正文并由公共样式设置内容间距。不得依赖页面 CSS 覆盖隐藏规则。既有原生资料/历史表用 `density-table`,分组表单用 `density-form`。返回按钮使用 `link class="density-back"`,跟编号、状态排在同一行。
Teleport 弹框用 `admin-density-dialog`,抽屉框架用 `admin-density-drawer`,`ElMessageBox` 用 `customClass: 'admin-density-confirm'`;这些浮层必须各自声明,页面祖先不能替代。抽屉当前公共框架负责字号、标题和正文边距;其正文若复用页面级表格、信息表或按钮原语,在正文业务根节点显式接入 `admin-density`。不要把名为 Drawer 的嵌入组件当作实际抽屉,承载方式以模板和调用端为准。
@@ -255,6 +259,6 @@ Teleport 弹框用 `admin-density-dialog`,抽屉框架用 `admin-density-drawe
- 对每个共享组件列出真实调用方及模式。现有 `dense` 参数由调用入口显式传递;`mode` / `workbench` 属于业务范围,不能为了样式变更其含义。新增消费者后,对开启和关闭密度、国内和海外等实际模式分别回归。
- `adminDensity.test.ts` 中菜单清单、`densityPages`、`consumers`、`moduleCss` 分别覆盖导航、独立入口、子组件和模块 CSS。接入时补充受影响清单,不移除国内仓和客户管理基线,也不通过递归扫描全后台推导范围。
- 动态类检查目前显式执行预装/已确认两种模式。接入其他条件时补充真实上下文和对应开关用例,不能一律传 `preload`、强行把所有条件置真,或只断言出现过类名。
- 动态类检查显式执行预装/已确认、`dense` 开/关,以及 DOMESTIC/OVERSEAS 入口;货柜已确认清单与船期浮层有独立开关断言。接入其他条件时补充真实上下文和对应开关用例,不能一律传 `preload`、强行把所有条件置真,或只断言出现过类名。
- 检查必须同时覆盖 CSS 独立导入、公共原语的实际祖先、Teleport 容器自己的类、变量定义与消费、按钮间距、普通/悬停/焦点/禁用,以及原有业务行为。源码合同只防止已知结构退化,不能证明最终 CSS 优先级或布局视觉正确。
- 发布前的代码门禁为密度合同、受影响业务测试、类型检查、全量测试和构建;维护指引后运行 AGENTS 索引合同。人工按 1920×1080、100% 缩放检查独立打开/刷新、列表到详情、浮层普通/全屏/重开、长数据和权限状态。缺少对应截图时保留“待人工截图确认”。
+1
View File
@@ -24,6 +24,7 @@
- [Admin 客户管理样式核对记录](Admin客户管理样式核对记录.md):客户列表、海外仓阶梯费用及关联详情和弹框的样式与人工验收项。
- [Admin 国内仓样式核对记录](Admin国内仓样式核对记录.md):7 个菜单、关联详情与浮层的范围、样式复核和验收证据。
- [Admin 货柜管理样式核对记录](Admin货柜管理样式核对记录.md):订舱、拖车、送柜报关、清关提柜入口及共享组件边界。
- [Admin 海外仓样式核对记录](Admin海外仓样式核对记录.md):海外仓 10 个菜单、独立详情、作业弹框和共享组件显式接入边界。
- [AI 工程执行与协作约束](AI工程执行与协作约束.md):工作区、依赖、Git、部署、数据库、质量门禁和独立任务协作规则。
- [数据库中文注释维护规范](数据库注释维护规范.md):数据库注释口径、职责、迁移流程、自动门禁与实值验收要求。
- [测试环境 Jenkins 部署指南](测试环境Jenkins部署指南.md):测试环境持续部署授权、Job 参数、健康检查与失败处理。
+1 -1
View File
@@ -65,7 +65,7 @@
| 订单编排、分柜、同柜不可拆组与柜次 | `docs/国内货柜履约/README.md`、`docs/国内货柜履约/国内货柜履约需求确认表.md`、`docs/统一订单主状态与操作契约.md` | Admin `modules/unified-orders/api/coLoadGroups.ts`、`modules/unified-orders/`、`container-loading/`;Client `modules/first-leg/`;Backend `firstleg/loading/coload/`、`firstleg/split/`、`firstleg/loading/`、`order/`;同柜组按订单创建,由服务端冻结每票全部可用入仓片段,仅要求同国内仓、同渠道,允许跨客户及不同目的仓港 |
| 全局智能排柜、预装与真实集装箱号后补 | 同上 | Admin `modules/container-loading/components/SmartLoadingDialog.vue` 内嵌 `pages/GlobalSmartLoadingView.vue`,柜次页 `SmartLoadingWorkbenchView.vue`,预装详情 `loading-lists/pages/PreloadPlanDetailView.vue`;PDA `pages/picking/`;Backend `firstleg/` 的 `PlatformSmartLoadingController`、`SmartLoadingService`、`PendingReviewOrderClient`、`loading/`,待审核事实来自 Order `PendingReviewOrderQueryService`。全局候选覆盖 `PENDING_REVIEW/WAIT_MEASURE/WAIT_SPLIT/LOADING`,状态只用于筛选展示,能否加入以服务端 `canAssign` 为准;待审核/待测量可提前占位,但确认预装或启动 PDA 前必须进入 `WAIT_SPLIT`。暂估明细的 `totalPackageCount/remainingPackageCount` 在测量前取 Order 原始申报箱数,测量完成后取最新已审核测量箱数,读取补充失败只回退当前已分配数,写入调整仍重新校验权威数量。同柜不可拆组仅在全员命中状态集合时作为一个分页与分配单元;人工加入允许跨渠道,智能推荐仍按柜次渠道。计划可一次性移除全部未拣明细,但任一成员已拣的同柜组必须整组保留。创建柜次时原子生成唯一预装计划,加入入仓码即建立关联;真实柜号不阻塞订舱关联、预装确认或 PDA 建任务,但必须在 PDA 最终完成前补齐 |
| 客户入库结果与头程费用确认 | 入库测量与计费主流程、当前 Firstleg 契约 | Client `modules/first-leg/components/InboundBillingPanel.vue`、`api/inboundBilling.ts`;Backend `firstleg/` 的 `MerchantInboundBillingController`、`MerchantInboundBillingService`、`FbaPricingService` 与 `firstleg-v1.yaml`。客户仅能确认本客户 `SENT` 的最新费用版本,提交 `expectedFeeVersion` 与幂等键;确认记录当前成员和时间并永久锁定该版本,平台不得再修改 |
| 订舱资料、放舱、出仓前船期与订舱级拖车 | 国内货柜履约 README、需求确认和实施边界 | Admin `modules/ocean-bookings/`、`port-schedules/`、`trucking/`;Backend `firstleg/oceanbooking/`、`firstleg/portschedule/`、`TruckAppointmentService`。拖车预约由 `RELEASED` 订舱拥有,不按客户、柜次、装柜计划或真实柜号归属;每个订舱最多一张非终态拖车单,创建候选由服务端排除缺提单/有效订舱文件或已有有效拖车单的订舱;PDA 装柜完成不推进拖车状态 |
| 订舱资料、放舱、出仓前船期与订舱级拖车 | 国内货柜履约 README、需求确认和实施边界 | Admin `modules/ocean-bookings/`、`port-schedules/`、`trucking/`;Backend `firstleg/oceanbooking/`、`firstleg/portschedule/`、`TruckAppointmentService`。拖车预约由 `RELEASED` 订舱拥有,不按客户、柜次、装柜计划或真实柜号归属;每个订舱最多一张非终态拖车单,创建候选由服务端排除缺提单/有效订舱文件或已有有效拖车单的订舱;PDA 装柜完成不推进拖车状态;全部要求货柜确认国内离仓后自动完成,人民币拖车费按实装体积分摊为柜次应付并经 Finance Outbox 入池 |
| 目的港码头拖车与还空预警 | `docs/海外仓业务/README.md` | Admin 海外清关提柜列表/详情 `modules/container-loading/pages/OverseasContainersView.vue`、`modules/container-loading/pages/OverseasContainerDetailView.vue`、API `api/terminalDrayages.ts`;Backend `firstleg/terminaldrayage/`、`terminal-drayage-v1.yaml`。该能力按真实货柜 `containerBookingId` 聚合,与订舱级拖车预约是不同生命周期;货柜实际到港后从 Warehouse `ACTIVE + TRUCKING` 供应商选择车队,依次预约提柜、记录实际提柜和实际还柜。提柜/还柜复用标准船节点 `PICKED_UP/EMPTY_RETURNED`,还空截止与超时按服务端 `unloadingCompletedAt + 72h` 计算,前端只消费 `allowedActions` 和预警结果。车队邮件由 Firstleg 持久化排队,首次选择后手动发送,换队原子生成旧车队取消与新车队提柜请求;邮箱取 Warehouse,邮件模板与配置见 `baiyue-firstleg/firstleg/docs/terminal-drayage-mail.md`。 |
| 整柜报关资料与完成文件 | 国内货柜履约契约 | 装柜完成后由 Admin `modules/container-loading/components/ContainerCustomsPanel.vue` 管理整柜报关,Client `modules/first-leg/components/CustomsDocumentsDialog.vue`、`api/customs.ts` 按订单处理本客户退税资料;Backend `firstleg/customs/container/`、`customs-v1.yaml`,文件归 `file/`。客户资料可覆盖同柜多个退税入仓码,开始报关后冻结;平台逐资料回传完成文件,全买单柜走平台确认与明细导出 |
| 国内出仓确认 | 国内货柜履约契约 | Admin `modules/outbound-dispatch/`;Backend `firstleg/outbound/dispatch/` |
@@ -133,3 +133,12 @@ Firstleg Outbox 发布采用至少一次投递:指数退避(建议 10s、30s
成本与资金动作分离:同一来源版本按 `sourceSystem + sourceType + sourceFeeId + sourceVersion` 只识别一次成本。DIRECT_PAID 来源唯一物化为 `fin_cost` 已付成本事实;ON_ACCOUNT 成本仍由来源事实识别,正式 AP 仅承载负债、到期日和付款,不重复确认成本。总成本等于有效 ON_ACCOUNT 来源成本加有效 DIRECT_PAID 成本事实;待付金额只来自非作废正式 AP 的 `outstanding_amount`;已付金额等于 AP `paid_amount` 加 DIRECT_PAID 金额。旧来源版本被替代或作废时,对应 DIRECT_PAID 成本事实同步失效。
主要剩余风险:测试环境尚未完成 Firstleg Relay → Finance Inbox → `fin_fee_source` 的真实 HTTP 冒烟。产品已确认无历史财务数据,不需要历史事件回放方案。
## 国内拖车离仓应付来源
- 国内拖车由 `TruckAppointmentCompletionService` 消费同库真实离仓事实:订舱全部柜型要求数量必须关联齐全,每个有效货柜的装柜计划已完成,且柜内每个入仓绑定均已确认国内离仓。多柜订舱只在最后一个柜确认后完成;创建、编辑、提交或改约重新核验,覆盖先离仓后提交。
- `TruckAppointmentFeeService` 将拖车总额按已完成装柜明细的体积归属到真实客户、订单、入仓和货柜;重复订单明细先汇总体积,按最大余数分配到分,合计严格等于总额,零分摊不生成来源。零总额不生成费用,缺失有效体积或归属直接拒绝,不均分或丢弃金额。
- 使用现有 `FEE_TYPE_108` 拖车费项目、拖车单承运商(重新校验 ACTIVE/TRUCKING)、`PAYABLE + ON_ACCOUNT`、人民币(拖车单 RMB,来源 CNY);按柜创建分摊组并由系统确认发布。柜次费用备注记录拖车业务编号与原始总额,后续调整/作废沿现有柜次分摊组与来源版本流程。
- 完成状态、`AUTO_COMPLETE` 历史、柜次费用、不可变费用快照与 `FIRSTLEG_FEE_PUBLISHED` Outbox 同事务保存。Finance 复用 `CONTAINER_FEE` 接口和幂等消费,将各来源纳入应付候选,财务按现有应付结算与付款流程处理;不自动登记付款或伪造已付。
- 订舱行锁串行化并发离仓和拖车写入,完成单不再次发布;已完成拖车的订舱不得再创建另一张自动收费单。取消、异常预约不被自动恢复。手工 DEPART/COMPLETE 动作和 USD 拖车费用已移除。