admin-web/docs/business-index.md

Admin业务详细索引

本文件保存当前页面/API 入口及业务规则，是应用指引的按需补充。涉及字段、状态、权限、金额、资源或作业恢复时必须读取受影响条款，不作为普通定位任务的全文首读。

正文代码路径以工作区 apps/admin-web/ 应用根起算，源码包缩写与裸文件名沿对应条目的目录解释；明确标注“工作区”的路径从工作区根起算。Markdown 相对链接以本文件所在的 docs/ 为起点。已知文件直接定位；行为变更同时核对最近模块指引及服务端合同。

原条款在本文件维护，主 AGENTS 仅保留短入口和通用边界；不要将新业务细节复制回主指引。

模块快速路由

表中 modules/、core/、shared/、app/ 和 main.ts 均相对 src/；裸文件名沿用同一单元格最近目录。模块细节只在最近指引维护，应用层保留入口。

业务	Admin 入口	联查
登录、会话与统一 Token	modules/auth/、core/auth/	国内 auth/、iam/；海外请求客户端再读 shared/api/AGENTS.md
启动与懒加载资源恢复	main.ts、core/routing/navigationRecovery.ts	仅识别动态模块/Chunk 资源过期；30 秒内同目标最多自动恢复一次，存在未保存编辑时必须先确认
工作台与指标	modules/dashboard/	指标所属模块与服务端，不复制领域契约
自营销量、库存与数据采集	modules/self-operated/AGENTS.md	三个入口 /self-operated/sales、/self-operated/inventory、/self-operated/collection；后端 lastleg-service/selfoperated/analytics/，正式合同见 ../../docs/自营业务/README.md。
船期日历	modules/sailing-calendar/	当前日历入口覆盖渠道、周模板、单次船期、收货截止时间和按渠道货量统计；后端按 firstleg/ 船期接口定位，不读取已归档的货柜开发规划
预约管理、预约列表、跨客户同仓预约	modules/appointment-calendar/；入仓单预约沿 modules/overseas-warehouse/	统一规则见 ../../docs/海外仓业务/README.md 的预约送仓；同仓跨客户共用预约，客户归属在货物明细；到港只读 Firstleg，送仓归 Lastleg
FBA 无匹配价格、人工定价	modules/inbounds/fee/api.ts 的 createManualInboundQuote、types.ts；页面消费沿 InboundFeePanel.vue 核对	POST /manual-quote 提交计费重量、体积、单价、原因和 Idempotency-Key；Backend PlatformFbaPricingController.manualQuote → FbaPricingService.manualQuote，权限 firstleg:inbound:confirm-send-fee。仅 FBA、已有实际测量且当前价格未命中时允许，客户已确认费用禁止改价；MANUAL_QUOTE 快照允许价格记录与版本为空，不伪造价格簿关联。API 回归 modules/inbounds/fee/api.test.ts，不能以 API 存在代替页面接入完成
PDA版本、APK下载、WGT热更新发布与停发	modules/pda-releases/pages/PdaReleasesView.vue、modules/pda-releases/api/pdaReleases.ts、modules/pda-releases/routes.ts	系统菜单 /system/pda-releases；列表权限 platform:pda-release:list，上传/发布/停发权限 platform:pda-release:manage。国内/海外按 domestic/overseas 分开查询，上传只创建草稿，发布与停发需确认；管理请求使用国内 HTTP 的 /platform/v1/files/pda-releases，后端见 file/AGENTS.md，设备安装与重启查对应 PDA 的更新工具
客户、企业审核、客户统计	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；旧系统导入固定归属“IT测试公司”，前端不提交或选择客户，逐行结果展示入仓码与失败原因。图片读取归 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	规则见下文「货柜工作台规则」
合柜报关 / 同柜不可拆组	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/	订舱草稿按当前版本维护资料，放舱后预计到港经 /estimated-arrival 按编辑权限和版本单独维护，其余运输/预报/关系方/柜型/附件只读；客服实货量经 /actual-cargo 按编辑权限、版本、幂等键和原因补录；打印对草稿与已放舱订舱均开放，按当前已保存资料生成，托运单取委值，提单确认件取手工实值，未填显示“—”且不以委值回退。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/、lastleg-service/、warehouse-overseas-service/；与排车、出库、派送、异常退回和一件代发共同组成海外仓全流程
海外采购、卡车、散板	modules/overseas-business/	gateway/、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，已定位局部任务直接沿模块入口。进度、排期或验收状态问题再读取对应进度表和报告。

散货托盘码打印：modules/loading-lists/components/PalletLabelPrintDialog.vue、modules/loading-lists/api/platformLoadingLists.ts，由货柜详情与装柜清单详情进入；先调用 /pallet-labels/prepare 获取服务端按 FBA 仓分组的冻结清单，再通过 /pallet-labels/print 下载 PDF。托盘码使用“真实柜号-FBA 地址内部编号-三位序号”，页面同时展示 FBA 仓码和内部编号；支持全部打印或按仓指定张数补打，一件代发托盘不在该清单，前端不生成或重新编号托盘码。

货柜工作台规则

• 国内“送柜报关”只消费 /containers/domestic 与服务端 allowedActions，承载模拟柜、订舱关联、智能装柜；模拟柜创建选择与智能装柜一致的 9 类计划渠道，未关联订舱前实际渠道为空，订舱关联候选按计划渠道组匹配并同时展示订舱号与提单号、装柜清单页签、出口报关和国内出仓；创建柜次时自动生成唯一预装计划，预装详情先调用 /loading-plans/{planId}/lifecycle，完成后深链进入国内货柜详情的装柜清单页签，独立装柜清单导航 /loading-lists 复用已确认清单 API，查看进入独立详情路由 /loading-lists/:planId，保留返回列表和打印；独立清单详情与货柜清单页签共同使用 useLoadingListDetail.ts 加载、校验和处理错误，LoadingListDetailDrawer.vue 统一密度、摘要、明细、历史及打印入口，打印实现归 printLoadingList.ts，外层只保留返回目标与货柜专属 PDA/报关区域；货柜列表经 ContainerWorkbenchView.vue 在国内装柜与海外清关提柜之间按权限切换。订舱关联允许真实集装箱号为空，但确认预装和创建 PDA 任务前必须补齐；历史已建但缺号的任务仍可在预装详情首次补录，保存后恢复 PDA 可进入状态；全买单柜继续使用 complete-all-buy。海外“清关提柜”只消费 /containers/overseas，承载船节点、目的港清关、DO/PU、码头车队和还空；原预约/实际提柜展示位改为整柜预计/实际到仓，预计到仓在列表内人工快捷维护并经海外接口同步整柜尾程订单，实际到仓只读海外 PDA 首次开始收货时间。还空截止事实由服务端基于卸柜完成时间加 72 小时计算，前端不重算。两端统一使用 containerBookingId，列表范围由服务端 scope=ACTIVE/HISTORY 分页，禁止浏览器筛选或本地推导写资格。后端为 LoadingListService、firstleg/customs/container/、firstleg/terminaldrayage/ 和 lastleg-service/，文件归 file/

海外模块内部快速索引（海外仓全流程）

• 海外仓的尾程订单控制与柜级入仓计划转换、退货库存、排车出库、异常回访：读取 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/
司机档案、驾驶证、到期提醒与资格预览	modules/overseas-master-data/pages/DriversView.vue、DriverDetailView.vue；最近指引 modules/overseas-master-data/AGENTS.md	api/drivers.ts；Backend lastleg-service/fleet/driver/、File FLEET_DRIVER_LICENSE