19 KiB
19 KiB
后端业务详细索引
本文件是同服务 AGENTS.md 的按需补充；命中业务后读取相应行/段，不默认全文加载。路径保持以后端仓库根为基准，各服务简写代码路径进入对应服务定位，不相对于本文件的 docs/ 目录。
服务路由（按关键词定位）
| 任务关键词 | 首选服务 | 先看入口 |
|---|---|---|
| 登录、Token、密码、注册与顶层授权快照 | auth/ |
auth/AGENTS.md；海外 Token 只携带稳定身份与版本，角色、权限和冻结海外仓从登录/刷新响应顶层快照读取，海外 Gateway 再按 IAM 安全投影失败关闭校验 |
| 客户档案、成员、审核、RBAC、授权快照 | iam/ |
iam/AGENTS.md |
| 客户建档默认箱规与权重系数初始化及补偿 | iam/、firstleg/ |
IAM CustomerDimensionRuleInitializationService 持久化意图、CustomerDimensionInitializationRelay 后台投递；Firstleg 内部入口 /internal/firstleg/v1/customer-dimension-configs/defaults 在同一事务生成四档尺寸和默认权重系数规则，未全部完成不得标记 READY 或审核通过 |
| 消息中心、站内通知、消息模板、收件箱 | iam/ |
iam/AGENTS.md，再按 src/main/java/com/baiyue/iam/notification/ 定位；业务事件生产者回到所属服务 |
| 订单、货物、快照、状态、幂等、Outbox | order/ |
order/AGENTS.md；统一列表由 UnifiedOrderQueryService 组合交易与履约投影，仍固定显示 PENDING_REVIEW 并提供审核动作：Order 为 SUBMITTED 时必须优先返回 PENDING_REVIEW/APPROVE_ORDER，不得被 Firstleg 准备中状态覆盖 |
| 客户头程订单中文批量导入 | order/ |
MerchantBatchImportService.java、MerchantWarehouseCatalogClient.java、MerchantPricingCatalogClient.java、order-v1.yaml；模板和导入都按当前客户读取动态地址、全部有效仓库与渠道，最多 50 行，只创建草稿，支持 PARTIAL/ATOMIC |
| 平台修改客户原始申报、履约渠道变更与跨服务同步 | order/、firstleg/ |
Order OrderDeclarationUpdateService.java、OrderInboundOutboxPublisher.java、order-v1.yaml；Firstleg OrderDeclarationSyncService.java、OrderDeclarationSyncMapper.java、firstleg-v1.yaml。只更新申报快照；渠道变化先失败关闭校验履约可逆性与重新计价，成功后由版本化 ORDER_DECLARATION_UPDATED_V1 幂等同步，不覆盖实测、箱码或已确认费用 |
| 平台订单批量审核预览 | order/ |
PlatformFirstLegOrderController.java 的 /batch-review-preview、BatchOrderReviewPreviewService.java、BatchOrderReviewPreviewResponse.java、order-v1.yaml；一次请求固定用订单与货物两次批量查询返回同序快照，不允许前端逐票请求详情，逐项资格以 canApprove/blockReason 为准 |
| 履约分配、入库、测量、箱规算法、审核、FBA 计费 | firstleg/ |
firstleg/AGENTS.md；客户四档箱规与 ADD/MULTIPLY 默认算法从 CustomerDimensionConfigService 进入，单箱测量和最终计价分别由 CustomerDimensionWeightingService、FbaPricingService 保存并消费服务端快照 |
| 入库单扣货、解除、凭证与履约门禁 | firstleg/、file/ |
Firstleg InboundHoldService、InboundHoldGuard、InboundHoldEvidenceService；平台接口 /api/platform/inbounds/{inboundId}/hold、/release、/evidence。扣货不改变 Order 主状态，命令使用入库聚合版本和幂等键；凭证只按客户、入库单及 INBOUND_HOLD_EVIDENCE 精确归属，所有装柜、PDA 拣货和国内出仓写入口统一复用门禁并失败关闭 |
| 称重确认、整票库位块与 PDA 资源结算 | firstleg/、warehouse/ |
Firstleg MeasurementLocationOccupationService.java、InboundMeasurementService.java、MeasurementSubmissionService.java、WarehousePalletLocationClient.java；Warehouse LocationBlockService.java 与 location-block-v1.yaml。称重确认尽力建块、提交时再次补齐，库位指引失败不阻断测量主流程；部分拣货整段转移给余量子单，整票拣完才整块释放，A0 共享资源按 reservationId 区分 |
| 客户专属价格簿、柜级阶梯运费与受控调价 | firstleg/ |
PlatformPriceBookService.java、ActivePriceBookEstimator.java、FbaPricingService.java、pricing/ContainerTierAmountAllocator.java、InboundFeeDetailService.java、fba-pricing-v1.yaml。customerId=0 为公共报价，正数为客户专属版本；计价优先专属 ACTIVE、缺失才回退公共 ACTIVE。同柜区域重量阶梯按实际成员计费量聚合命中并守恒分摊，装柜变化只重算未锁定客户费用；人工计费量调整限基准上下 10%，私人仓尾程派送费只绑定 PRIVATE 入库单；一件代发 WAIT_PALLETIZE 允许在预装确认前试算，写费用时必须保留托盘化状态 |
| Firstleg 内部模块化与依赖基线 | firstleg/ |
firstleg/docs/firstleg-internal-modularization-baseline.md、firstleg/scripts/analyze-firstleg-dependencies.mjs；价格簿查询和客户统计按端口/适配器切片，不改变服务与数据库边界 |
| Mapper 新增、移动、Bean 缺失与扫描遗漏 | 目标持久化服务 | 所有 Mapper 显式 @Mapper，启动类按服务根包注解过滤扫描；先运行 node scripts/mapper-scan-contract.mjs，再按目标模块执行 test-compile/test，不得等部署启动发现 |
| 脚本管理、全量验证、测试造数与诊断 | 仓库根 scripts/；服务专属脚本留在 <service>/scripts/ |
先读 scripts/AGENTS.md 和 scripts/README.md；Admin HTTP 内部模块继续读 scripts/admin-test-env-modules/README.md。新增入口必须登记用途、目标环境、数据副作用和报告位置，并通过 scripts/script-documentation-contract.test.mjs |
| 分柜、柜次、智能排柜、预装/装柜清单、真实柜号后补、PDA | firstleg/ |
firstleg/AGENTS.md，再按 split/、loading/、outbound/ 定位；创建柜次时原子生成唯一预装计划，加入入仓码时同步建立关联，不设推送步骤；预装/正式详情由 /loading-plans/{planId}/lifecycle 解析。真实集装箱号不阻塞订舱关联、计划确认或 PDA task 创建，可在 EDITING/LOADING 首次补录，但必须在 PDA 最终完成前存在。上传以幂等键绑定包含文件内容的请求哈希，完全重放不得再次调用 File |
| 合柜报关 / 同柜不可拆组、跨客户合柜、整组分配/移除 | firstleg/ |
loading/coload/controller/PlatformColoadGroupController.java、service/ColoadGroupService.java、persistence/ColoadGroupMapper.java、src/main/resources/openapi/coload-groups-v1.yaml；按订单建组并冻结全部可用入仓片段，仅要求同国内仓、同渠道 |
| 全局智能装柜候选、柜次、占位与移除 | firstleg/、order/ |
Firstleg controller/PlatformSmartLoadingController.java 的 /inbound-candidates、/containers、/plans/{planId}/inbound-assignments、/pending-review-assignments、/group-assignments、/unpicked-items，业务编排 service/SmartLoadingService.java；待审核事实由 client/PendingReviewOrderClient.java 经内部令牌查询 Order /internal/order/v1/pending-review-orders 与 PendingReviewOrderQueryService.java 的权威 SUBMITTED/PENDING_REVIEW 行。候选四态只用于筛选展示，资格以 canAssign 为准；待审核或待测量可先占位，确认预装和启动 PDA 前仍须进入 WAIT_SPLIT；计划明细总量/余量由 Order 原始申报或最新已审核测量补齐，调整时重验权威数量；人工加入允许跨渠道，智能推荐仍按柜次渠道；同柜组整组分页、分配和移除 |
| 客户入库结果与头程费用确认 | firstleg/ |
controller/MerchantInboundBillingController.java、service/MerchantInboundBillingService.java、FbaPricingService.java，接口 /api/merchant/v1/first-leg/orders/{orderId}/inbound-billing 与 /confirm；客户按登录态范围读取并以费用版本和幂等键确认当前 SENT 费用，确认后锁定 |
| 订舱资料/打印、船期、订舱级拖车、报关 | firstleg/ |
oceanbooking/、portschedule/、TruckAppointmentService.java、outbound/dispatch/、customs/；拖车只绑定 RELEASED 订舱，不携带客户、柜次、装柜计划或真实柜号，每订舱最多一张非终态预约，订舱文件联查 file/AGENTS.md |
| 目的港码头拖车与还空预警 | firstleg/ |
terminaldrayage/controller/PlatformTerminalDrayageController.java、service/TerminalDrayageService.java、src/main/resources/openapi/terminal-drayage-v1.yaml；按 containerBookingId 聚合并与订舱级拖车分离，引用 Warehouse ACTIVE + TRUCKING 供应商，提柜/还柜复用船节点，服务端按海外卸柜完成时间加 72 小时计算还空预警 |
| 客户账期、费用池、账单、入仓码联查、收款、成本、核销 | finance/ |
finance/AGENTS.md；客户账单行 inboundCode 由 FinanceQueryService 从费用来源快照提供，Client 复用头程入仓关系详情；费用来源和柜次成本快照再联查 firstleg/AGENTS.md，凭证再联查 file/AGENTS.md |
| 客户资金账户、充值、授信、冻结、结算与跨区资金指令 | finance/、lastleg-service/、common-event-contract/、event-bridge-service/ |
国内 FinanceWalletService.java 持有唯一 CNY 主账和不可变流水；平台、客户、内部入口见 PlatformFinanceWalletController.java、ClientFinanceWalletController.java、InternalFinanceWalletController.java 与 finance-wallet-v1.yaml。海外采购和换标由 Lastleg wallet/ 发布 WALLET_COMMAND_REQUESTED，Finance 冻结、结算或释放后发布 WALLET_COMMAND_COMPLETED 回传，不跨区域同步调用钱包 |
| 柜级公共费用跨客户分摊 | firstleg/、finance/ |
Firstleg PlatformContainerFeeDetailController.java、ContainerFeeDetailService.java、container-fees-v1.yaml 按柜内真实客户与订单原子创建 allocation-groups；金额合计必须等于总额，分组审核、驳回、调整、作废均整组处理，Finance 只消费各客户不可变来源快照 |
| 海外业务费用来源跨区入池 | lastleg-service/、common-event-contract/、event-bridge-service/、finance/ |
Lastleg financefee/ 审核五类海外费用并发布 BUSINESS_FEE_SOURCE_CHANGED 完整快照；Event Bridge 对 targetRegion=CN 定向投递 Finance /internal/finance/v1/business-fee-source-events；Finance 按事件 ID、Payload 哈希、来源系统/费用 ID/版本幂等入池，PAYABLE + DIRECT_PAID 单独形成已确认成本且不进入 AP 待结算 |
| 入库/柜次应付、直接已付、付款流水与凭证 | firstleg/、finance/、file/ |
业务费用与付款快照见 firstleg/AGENTS.md 的 FeePaymentSnapshotValidator；/api/platform/finance/v1/vouchers 上传凭证，File 按 FINANCE_VOUCHER 和客户范围校验 |
| 仓库、往来单位、快递、托盘、库位 | warehouse/ |
warehouse/AGENTS.md |
| 供应商、国内整柜库存与出入库 | warehouse/ |
warehouse/AGENTS.md；OpenAPI warehouse/src/main/resources/openapi/supplier-v1.yaml、domestic-container-v1.yaml |
| 客户运营统计、在途柜量 | firstleg/ |
firstleg/AGENTS.md；OpenAPI firstleg/src/main/resources/openapi/customer-statistics-v1.yaml |
| 平台操作日志与审计查询 | audit-service/ |
audit-service/AGENTS.md；平台查询接口 /api/platform/v1/audit/logs |
| 资质、导出、导出退避重试、测量图片、文件下载 | file/ |
file/AGENTS.md；法人身份证选填，可在已有营业执照后单独补传或替换；PENDING 且已有失败尝试的退避任务可人工立即到期并复用当前投递，不创建并发任务 |
| 路由、CORS、JWT 入口、访问域 | gateway/ |
gateway/AGENTS.md |
| 百度/Amazon/OCR/第三方适配 | integration-service/ |
integration-service/AGENTS.md |
| 海外 API 路由、海外 Token、Audience/JWKS | gateway-overseas/ |
gateway-overseas/AGENTS.md |
| 海外 IAM 状态与权限版本投影 | lastleg-service/security/ |
lastleg-service/AGENTS.md；内部入口 /internal/lastleg/security/v1/events、/validate；消费三类 IAM 安全事件并为海外 Gateway 提供 fail-closed 校验，投影表归 baiyue_lastleg |
| 尾程订单、海外入仓计划、换标、库存、采购、本土卡车 | lastleg-service/ |
lastleg-service/AGENTS.md，尾程订单控制从 LastlegOrderController.java、LastlegOrderCommandService.java 进入，再按 inboundplan/、relabel/、inventory/、procurement/、trucking/ 定位 |
| 尾程订单控制、柜级预览与入仓计划转换 | lastleg-service/、warehouse-overseas-service/ |
orders/container-summaries 按 sourceContainerBookingId 跨客户聚合并分页返回全部稳定来源柜，已完成计划转换的柜仍用于接柜仓查询与修改，生成资格由 allPlansReady/pendingPlanCount 表达，详情返回全柜数据。inbound-plans/container-preview 由 InboundPlanService.java 返回服务端分组、托数、阻断项及快照版本/哈希；ContainerInboundPlanConversionCoordinator.java 校验同一快照并以唯一 Saga 先向 WarehousePalletBatchService.java 批量预留真实托盘，再本地原子生成剩余独立计划并确认资源，失败只补偿未确认资源，同柜重放不得新建第二批。暂扣/解除和固定八行人工节点进入 LastlegOrderCommandService.java；命令按订单版本、客户范围和幂等键执行，暂扣中的订单不得进入排车或出库 |
| 海外入仓分页、FBA 预约、PDA 柜号签收与入仓 | lastleg-service/ |
平台入口 inboundplan/controller/InboundPlanController.java、InboundPlanQueryMapper.java、InboundFbaAppointmentService.java；PDA 公网入口 inboundplan/pda/controller/ReceivingContainerController.java、ReceivingContainerService.java，旧 planNo/allocationId Controller 已移除 |
| 海外仓排车查询、候选与智能预排 | lastleg-service/ |
dispatch/controller/DispatchQueryController.java、SmartDispatchController.java；草稿柜、托盘锁和预排归 dispatch/，只读排车和预排创建独立开关，不自动开放编辑、取消、发车、PDA 出库或派送 |
| 海外排车执行、PDA 出库、派送与一件代发 | lastleg-service/ |
dispatch/controller/DispatchController.java、dispatch/pda/controller/DispatchPdaController.java、delivery/controller/DeliveryTransferController.java、OutboundPdaController.java、MerchantDeliveryController.java，一件代发库存归 dropship/；统一经 gateway-overseas/，设备端正式入口继续查 ../apps/pda-overseas-uniapp/AGENTS.md |
| 海外异常退回、库存恢复与客户回访 | lastleg-service/、file/ |
exceptionorder/、inventory/command/、customervisit/；异常按版本和幂等键执行 PENDING → PROCESSING → COMPLETED，完成证据固定归 OVERSEAS_EXCEPTION_EVIDENCE。派送退回明细只能来自原出库拣货事实，退回海外仓时校验真实目标托盘/库位并以 RETURN_STOCK_IN 恢复库存后，原子完成异常单与派送 RETURNED；回访仍以 Lastleg 客户范围和派送状态为准 |
| 一件代发 SKU/箱唛与暂扣跨区协同 | order/、firstleg/、common-event-contract/、lastleg-service/ |
Order InternalOrderCargoController 提供强制 SKU 与每箱数量；Firstleg InboundCartonLabelService 冻结箱唛 SKU，DropshipPalletizationService 完成清点、组托和封托，智能排柜只按 SEALED 整托分配，并消费 OverseasInboundOrderDetainedChangedV1；Lastleg dropship/ 建立库存并发布暂扣变更 |
| 客户海外仓贴标、转运、废弃与退货换标 | lastleg-service/ |
relabel/、relabel/pda/、transfer/、discard/ 的 Merchant/PDA Controller 和 Service；换标下单按历史入仓库存选择，每个我方箱唛只形成一条箱任务，支持箱唛、SKU 和组合换标，SKU 子项不重复冻结。涉及箱唛换标时冻结派送方式，PDA 逐箱作业并上传完工照片，仓库复核后必须由客户查看证据确认，之后卡车进入预排车，自提/快递进入换标出库待创建；不伪造已入库单。Client 消费端 ../html/client-web/src/modules/overseas-warehouse/，统一经 gateway-overseas/ |
| 海外仓 PDA 盘点、移库、托盘、换标与查询 | lastleg-service/、warehouse-overseas-service/ |
Lastleg pda/stocktake/、pda/move/、pda/warehouse/、palletops/、relabel/pda/；托盘作业保留托盘-入仓单组成明细，合托通过入仓计划托盘分配和合托记录留痕；pallet-operations/relabel-disassemble 按换标单箱唛快照解析原库存仓位，在一个幂等事务内移动对应冻结箱数并绑定已扫码目标托盘，同时更新换标明细和未开始拣货的出库托盘/箱唛快照；出库可扫描托盘但后台按托盘下各入仓单箱数核平；契约 lastleg-service/src/main/resources/openapi/overseas-pda-operations-v1.yaml；物理托盘流转与补偿进入 Warehouse InternalPdaPalletTransitionController，设备端入口是否开放以 ../apps/pda-overseas-uniapp/AGENTS.md 为准 |
| 国内船节点向海外接柜门禁事件 | firstleg/、common-event-contract/、lastleg-service/ |
Firstleg portschedule/service/CarrierScheduleNodeOutboxService.java 发布 FirstLegContainerShippingNodeRecordedV1；Lastleg shipping/service/ContainerShippingNodeConsumer.java 单调消费，只有实际 PICKUP_READY 及以后节点允许海外 PDA 候选进入可收货 |
| 海外仓库目录、海外库位、海外托盘、资源锁 | 国内仓库目录归 warehouse/，海外资源归 warehouse-overseas-service/ |
warehouse/AGENTS.md、warehouse-overseas-service/AGENTS.md；海外库只保存国内 warehouseId 引用 |
| Lastleg 内部模块化与依赖基线 | lastleg-service/ |
lastleg-service/docs/lastleg-internal-modularization-baseline.md、lastleg-service/scripts/analyze-lastleg-dependencies.mjs；只用于约束服务内部依赖，不改变服务和数据库边界 |
| PDF 标签、审计、跨区双向事件 | print/、audit-service/、event-bridge-service/ |
事件模型先读 common-event-contract/AGENTS.md；国内真实生产验收 firstleg/.../TaillegRealProducerAcceptanceTest.java、海外真实消费验收 lastleg-service/.../TaillegRealConsumerAcceptanceTest.java；可靠投递与 CN/OVERSEAS 目标路由读 event-bridge-service/AGENTS.md |
散货托盘码与跨区传递：firstleg/ 的 LoadingPalletLabelService.java 生成冻结标签并调用 Print 输出 PDF，LoadingCompletedOutboxService.java 传递装柜快照；lastleg-service/ 通过 LastlegSourcePalletMapper.java 保存来源托盘，InboundPlanService.java 和 ContainerInboundPlanConversionCoordinator.java 消费。标签与资源预留的细节继续读对应服务指引。