html/admin-web
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

优化

Browse Source
This commit is contained in:
ouyangxq
2026-09-14 10:02:39 +08:00
parent 8bc86c8567
commit 89dc3bf671
11 changed files with 115 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+6 -13
View File
@@ -33,6 +33,8 @@
## 模块快速路由
表中 `modules/`、`core/`、`shared/`、`app/` 和 `main.ts` 均相对 `src/`；裸文件名沿用同一单元格最近目录。模块细节只在最近指引维护，应用层保留入口。
| 业务 | Admin 入口 | 联查 |
|---|---|---|
| 登录、会话与双区域 Token | `modules/auth/`、`core/auth/` | 国内 `auth/`、`iam/`；海外请求客户端再读 `shared/api/AGENTS.md` |
@@ -49,7 +51,7 @@
| 入库扣货、解除与凭证历史 | `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/inbounds/pages/InboundOrdersView.vue`、详情工作区、`modules/inbounds/core/api.ts` | 列表展示服务端 `holdFlag/currentHoldReason` 并支持筛选；详情只按 `canHold/canRelease/actionBlockReason` 开放操作。扣货与解除提交当前 `version`、原因和独立幂等键，可选凭证先按明确客户与入库单上传；历史文件只调用专用下载入口，不把上传成功但未提交命令的文件冒充扣货证据 |
| 客户专属价格簿、柜级阶梯运费与受控调价 | `modules/fba-pricing/carrier-rates/`、`modules/inbounds/fee/`、`modules/unified-orders/components/InboundFeeDetailManager.vue` | 价格簿页面显式选择公共报价或具体客户；列表、上传、确认只作用于该 `customerId`，不得混合版本。计价优先消费客户专属 ACTIVE 版本，无专属版本才回退公共 ACTIVE；柜级阶梯金额和各客户分摊只展示服务端结果。调整计费量只能在服务端返回的上下 10% 范围内并提交当前费用版本、原因与二次确认；私人仓尾程派送费使用稳定 `PRIVATE_LAST_MILE_DELIVERY` 代码且只对 `PRIVATE` 目的地开放；一件代发须在预装确认前完成试算，计价后保持服务端 `WAIT_PALLETIZE` 状态 |
| 客户专属价格簿、柜级阶梯运费与受控调价 | 列表/上传 `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 最终完成前必须补齐；全买单柜继续使用 `complete-all-buy`。海外“清关提柜”只消费 `/containers/overseas`，承载船节点、目的港清关、DO/PU、码头车队、提柜和还空；还空截止事实由服务端基于卸柜完成时间加 72 小时计算，前端不重算。两端统一使用 `containerBookingId`，列表范围由服务端 `scope=ACTIVE/HISTORY` 分页，禁止浏览器筛选或本地推导写资格。后端为 `LoadingListService`、`firstleg/customs/container/`、`firstleg/terminaldrayage/`，文件归 `file/` |
| 合柜报关 / 同柜不可拆组 | `modules/unified-orders/api/coLoadGroups.ts`、`pages/UnifiedOrdersView.vue`；装柜消费 `modules/container-loading/pages/SmartLoadingWorkbenchView.vue` | 前端只提交订单 ID；Backend `firstleg/loading/coload/` 展开并冻结每票全部可用入仓片段。成员数是入仓片段数，不等于订单票数；只要求同国内仓、同渠道，允许跨客户及不同目的仓港；分配、移除、取消均整组处理 |
@@ -63,8 +65,8 @@
| 海外采购、卡车、散板 | `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/pages/DispatchesView.vue`、`DispatchDetailView.vue`、`OutboundsView.vue`、`DeliveryOrdersView.vue`、`DeliveryOrderDetailView.vue` | API 为 `dispatches.ts`、`outbounds.ts`、`deliveryOrders.ts`；Backend `lastleg-service/dispatch/`、`delivery/`、`dropship/`。一件代发独立出库，从服务端库存位置选择并携带幂等键；普通出库及换标单经头程排车转出库，按托盘快照绑定头程箱唛，PDA 按托盘作业，详情展示箱唛与已拣数量；排车转派送按稳定 `dispatchNo` 进入服务端命令，可在 `PENDING_DEPARTURE`、`PICKING`、`READY_TO_DEPART` 状态执行并须在 PDA 发车前生成待出库单 |
| 海外异常退回与客户回访 | `modules/overseas-warehouse/pages/ExceptionOrdersView.vue`、`CustomerVisitsView.vue` | API 为 `exceptionOrders.ts`、`customerVisits.ts`；Backend `lastleg-service/exceptionorder/`、`customervisit/`。异常处理只消费服务端 `allowedActions/version`；完成时至少上传一份异常证据。派送退回先从服务端原出库拣货事实选择入仓单和可退箱数，不允许自由填写 SKU/数量；退回海外仓时必须选择服务端校验的目标托盘和库位，库存恢复、异常完成与派送 `RETURNED` 由服务端原子推进。回访附件和派送完成/状态均走海外真实 API |
| 海外排车、出库与派送 | `modules/overseas-warehouse/AGENTS.md` | 按模块表定位排车、出库、派送页面及 API；履约边界在模块内维护 |
| 海外异常退回与客户回访 | `modules/overseas-warehouse/AGENTS.md` | 派送异常退回区别于退货库存；页面、API 与原子推进约束见模块指引 |
全量验收按业务从 `../../docs/订单与客户/`、`入库测量与计费/`、`国内货柜履约/`、`财务管理/` 选择最小契约；海外仓业务开发先读 `../../docs/海外仓业务/README.md`。进度、排期或验收状态问题再读取进度表和报告。
@@ -72,23 +74,14 @@
## 海外模块内部快速索引（海外仓全流程）
退货库存与退货箱号：`modules/overseas-warehouse/pages/ReturnInventoryManagementView.vue`、`api/returnInventory.ts`，由 `routes.ts` 的 `return-inventory/return-cartons` 分别以 `mode=inventory/cartons` 进入；只消费 Lastleg `returnreceipt/` 的平台库存、箱号、流水和标签接口。退货出库从 `pages/OutboundsView.vue` 进入，区别于 `ExceptionOrdersView.vue` 的派送异常退回。
- 海外仓的尾程订单控制与柜级入仓计划转换、退货库存、排车出库、异常回访：读取 `src/modules/overseas-warehouse/AGENTS.md`，字段与流程仅在该模块维护。
| 关键词 | 页面/路由入口 | API 与联查 |
|---|---|---|
| 尾程订单控制与柜级入仓计划转换 | `modules/overseas-warehouse/pages/LastMileOrdersView.vue`、`LastMileOrderDetailView.vue` | 柜子工作台按 `sourceContainerBookingId` 消费 `/orders/container-summaries`；服务端分页返回全部稳定来源柜，计划已经齐全的柜仍保留用于接柜仓查询和修改，并按冻结 `plannedArrivalAt` 升序、空值最后排序。详情返回全柜订单且不受列表分页截断；单票手工计划保存后，由服务端在整柜最后一票计划齐全时自动生成并绑定全柜托盘码，一票柜立即生成；`resourcePendingPlanCount` 只表示自动生成异常的重试入口，不是正常人工步骤。柜级确认弹框先调用 `/inbound-plans/container-preview`，按服务端 FBA/一件代发/私人地址分组展示头程已有、海外仓补充和最终托数以及 `readiness/blockers`；最终托数不得少于头程已有托盘码，差额连续补码且不阻断流程。前端不计算托数、不逐票建计划、不预占托盘，再把同一 `snapshotVersion/snapshotHash` 原样提交 `/inbound-plans/convert-container`，快照冲突后重新获取预览。服务端只为剩余订单逐票生成独立计划，并为异常遗留的人工计划补齐真实托盘，整批原子且重放不得产生第二批资源。单票完整入库计划、暂扣/解除和八行人工节点均从 `api/lastMileOrders.ts` 提交订单版本与幂等键；入仓码只读展示并提交订单冻结值，不允许人工改写，暂扣资格、接柜仓锁定原因和操作能力只消费服务端结果，人工节点一经保存不得回退柜级节点。转仓候选只取 `modules/iam/api/platformIam.ts` 的平台公共 `ACTIVE + FBA` 仓主档；Backend `lastleg-service/` |
| 入仓单、入仓计划、FBA 预约 | `modules/overseas-warehouse/pages/InboundOrdersView.vue`、`InboundOrderDetailView.vue` | 列表/预约 `modules/overseas-warehouse/api/inboundOrders.ts`，计划列表/详情 `inboundPlans.ts`；Backend `lastleg-service/inboundplan/` |
| 排车查询、智能预排与转派送 | `modules/overseas-warehouse/pages/DispatchesView.vue`、`DispatchDetailView.vue`、`components/SmartDispatchDialog.vue` | `modules/overseas-warehouse/api/dispatches.ts`；Backend `lastleg-service/dispatch/`、`delivery/`；覆盖详情、候选、草稿柜、托盘锁、`pre-arrange` 和 `transfer-delivery`。页面能力必须由正式路由、API 调用和测试共同证明 |
| 海外出库与派送 | `pages/OutboundsView.vue`、`OutboundDetailView.vue`、`DeliveryOrdersView.vue`、`DeliveryOrderDetailView.vue` | `api/outbounds.ts`、`deliveryOrders.ts`；出库列表按类型筛选并展示中文类型。一件代发新建弹窗直接跨客户加载服务端可用候选，不单独展示客户筛选，海外仓必选并优先默认洛杉矶仓；订单条件可按订单号、入库单号、客户、托盘号、SKU 或品名查询/重置，以托盘+SKU 行分页多选。提交时从所选行解析唯一客户，并校验所选行属于当前唯一海外仓，不要求先选客户。退货出库客户下拉同时展示客户名称与联系电话并支持手机号检索，客户和仓库选项独立容错加载；选择客户后须立即按当前默认/已选海外仓加载库存。SKU 与箱号查询均使用输入态/已查询态分离，只允许点击查询按钮后生效；支持英文逗号批量条件，查询时清除空格并按任一条件命中，左右列表分别提供每页 5/10/20/50 条选择。SKU 列表只展示 `availableQuantity > 0` 的未占用可用数量，合箱后已扣减为零的 SKU 不再作为可选库存显示，实际作业以可用箱唛选择和箱内 SKU 明细扣减为准。取消、派送列表/详情及退回入口对应 Backend `lastleg-service/delivery/`、`dropship/` |
| 异常退回与客户回访 | `pages/ExceptionOrdersView.vue`、`CustomerVisitsView.vue` | `api/exceptionOrders.ts`、`customerVisits.ts`；异常关系解析、异常建档、派送退回、完成/状态和回访附件对应 Backend `lastleg-service/exceptionorder/`、`customervisit/` |
| 库存余额、库位与流水 | `modules/overseas-warehouse/pages/InventoryView.vue`、`InventoryDetailView.vue`、`InventoryTransactionsView.vue` | `modules/overseas-warehouse/api/inventory.ts`；业务库存归 `lastleg-service/inventory/`，实物资源归 `warehouse-overseas-service/` |
| 托盘、箱唛、产品与换标 | `modules/overseas-warehouse/pages/PalletsView.vue`、`CartonsView.vue`、`ProductsView.vue`、`RelabelOrdersView.vue` 及详情页 | `modules/overseas-warehouse/api/pallets.ts`、`relabelOrders.ts`；换标详情展示 PDA 完工照片与复核人，状态区分待客户确认和待出库；路由是否公开以 `modules/overseas-warehouse/routes.ts` 为准 |
| 海外采购 | `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/` |
- 三个海外模块统一使用 `shared/api/overseasHttp.ts`；页面是否已接真实接口先查对应 `api/` 和挂载测试，不以 `PROTOTYPE_MATRIX.md` 或 `CONTRACT_GAPS.md` 代替当前代码与服务端契约。
## 业务、安全与共享装配
- 当前只有平台、客户两级；Admin 不显示“租户”。平台仓库是公共主数据，不与客户绑定；客户筛选不得缩小仓库候选。完整语义见平台客户层级与权限契约。