baiyue-firstleg/AGENTS.md

# 头程与海外仓后端项目指引

> 当前为单 TEST、统一 Gateway/Auth 会话/Nacos 与业务 Outbox 直接投递。架构规则及部署/验收状态唯一见 `../docs/测试环境单机部署与配置契约.md`、`../docs/统一认证与服务通信契约.md`。模块旧双区域说明不能覆盖这两份契约；构建、部署与整体验收分别核对。

根 POM 当前聚合 20 个模块（7 个公共/依赖模块、13 个服务），部署映射见 `deploy/service-map.yml`。`gateway-overseas/` 与 `event-bridge-service/` 为退役待清理源码，不是当前构建或部署单元。

## 适用范围与定位

- 本文件适用于 `baiyue-firstleg/` Maven 多模块仓库，包含国内头程与海外区域服务；进入具体服务后继续读取该服务的 `AGENTS.md`。
- 本层只负责：服务边界、跨服务契约、数据库部署总入口、阶段路由和通用验证。Controller、Service、DTO、SQL 细节以模块级指引为准。
- 普通任务先读本文件和目标模块指引；聚合构建/架构问题再读 `README.md`、`pom.xml`、`docs/头程项目目录结构与服务说明.md`。
- 平台/客户层级与权限公共语义见 `../docs/平台客户层级与权限契约.md`；统一 Token、API 和可靠直接投递公共契约见 `../docs/统一认证与服务通信契约.md`。本文件只保留后端执行所需摘要。

## 不可突破的产品与数据边界

- 当前产品只有“平台—客户”两级。`tenant_id=0` 是平台技术作用域；`tenant_id>0` 是客户隔离键，不得新增租户切换、租户选择或租户级 RBAC。
- 公共仓库、往来单位、快递、托盘、库位统一归属 `tenant_id=0`；订单、文件、费用等客户数据按客户 `tenant_id>0` 隔离。不得跨库 Join 或信任客户端客户 ID。
- 国内订单交易状态归 `order`，头程履约/入库状态归 `firstleg`，财务账期、账单、收款、成本与核销归 `finance`；全部仓库 ID、类型、状态、地址和能力主档归国内 `warehouse`，海外 `warehouse-overseas-service` 只维护引用同一国内 warehouseId 的库位、托盘和资源锁。海外尾程订单、入仓计划、库存业务与海外本土业务归 `lastleg-service`，所有端公网入口归 `gateway`。文件对象归 `file`，第三方适配归 `integration-service`；跨服务通过内部客户端、DTO、事件和服务令牌协作。
- 普通业务成功/失败使用 HTTP 200 + body `code`（成功为字符串 `"200"`）；认证、基础设施和网关拒绝可使用真实 401/403/503。

## 服务路由（按关键词定位）

本表只保留定位入口；命中业务后用 `rg -n -F '关键词' docs/backend-business-index.md` 读取对应行/段的详细约束，再沿代码引用追踪；不默认全文加载详细索引。已知目标文件时直接定位，并定向核对该业务约束。

### 后端任务最小读取集

- 单服务 Controller/Service/Mapper 任务：本文件、目标服务 `AGENTS.md`、目标类及其直接调用点。
- 跨服务 API/事件任务：在上述基础上增加直接调用方、被调用方及受影响的 OpenAPI/事件契约；公开路径、访问域或入口鉴权变化才增加 Gateway，内部调用和事件不经公网 Gateway。不因业务关键词自动加载整个业务专题。
- 只有状态、权限、数据库或验收边界无法从上述入口确定时，才读取 `docs/业务快速索引.md`、专题 README 或完整契约。
- 读取预算遵循工作区根指引：超过约 250 行或 8000 字符时先读职责、硬边界和验证章节，再检索任务命中段；不得仅因行数少而全文加载长业务表。聚合构建或架构任务才读取相关 `README.md`、`pom.xml` 和目录结构文档，已知单模块任务不增加概览文档。

| 任务关键词 | 首选服务 |
|---|---|
| 登录、Token、密码、注册与顶层授权快照 | `auth/` |
| 客户档案、成员、审核、RBAC、授权快照 | `iam/` |
| 客户建档默认箱规与权重系数初始化及补偿 | `iam/`、`firstleg/` |
| 消息中心、站内通知、消息模板、收件箱 | `iam/` |
| 订单、货物、快照、状态、幂等、Outbox | `order/` |
| 客户头程订单中文批量导入 | `order/` |
| 平台修改客户原始申报、履约渠道变更与跨服务同步 | `order/`、`firstleg/` |
| 平台订单批量审核预览 | `order/` |
| 履约分配、入库、测量、箱规算法、审核、FBA 计费 | `firstleg/` |
| 入库单扣货、解除、凭证与履约门禁 | `firstleg/`、`file/` |
| 称重确认、整票库位块与 PDA 资源结算 | `firstleg/`、`warehouse/` |
| 客户专属价格簿、柜级阶梯运费与受控调价 | `firstleg/` |
| Firstleg 内部模块化与依赖基线 | `firstleg/` |
| Mapper 新增、移动、Bean 缺失与扫描遗漏 | 目标持久化服务 |
| 脚本管理、全量验证、测试造数与诊断 | 仓库根 `scripts/`；服务专属脚本留在 `<service>/scripts/` |
| 分柜、柜次、智能排柜、预装/装柜清单、真实柜号后补、PDA | `firstleg/` |
| 合柜报关 / 同柜不可拆组、跨客户合柜、整组分配/移除 | `firstleg/` |
| 全局智能装柜候选、柜次、占位与移除 | `firstleg/`、`order/` |
| 客户入库结果与头程费用确认 | `firstleg/` |
| 订舱资料/打印、船期、订舱级拖车、报关 | `firstleg/` |
| 目的港码头拖车与还空预警 | `firstleg/` |
| 客户账期、费用池、账单、入仓码联查、收款、成本、核销 | `finance/` |
| 客户资金账户、充值、授信、冻结、结算与跨区资金指令 | `finance/`、`lastleg-service/`、`common-event-contract/` |
| 柜级公共费用跨客户分摊 | `firstleg/`、`finance/` |
| 海外业务费用来源跨区入池 | `lastleg-service/`、`common-event-contract/`、`finance/` |
| 入库/柜次应付、直接已付、付款流水与凭证 | `firstleg/`、`finance/`、`file/` |
| 仓库、往来单位、快递、托盘、库位 | `warehouse/` |
| 供应商、国内整柜库存与出入库 | `warehouse/` |
| 客户运营统计、在途柜量 | `firstleg/` |
| 平台操作日志与审计查询 | `audit-service/` |
| 资质、导出、导出退避重试、测量图片、文件下载 | `file/` |
| 路由、CORS、JWT 入口、访问域 | `gateway/` |
| 百度/Amazon/OCR/第三方适配 | `integration-service/` |
| 统一 API 路由、Token、Audience/JWKS | `gateway/`、`auth/`、`common-security/` |
| 统一会话与账号/客户权限撤销 | `auth/`、`iam/`、`common-security/` |
| 尾程订单、海外入仓计划、换标、库存、采购、本土卡车 | `lastleg-service/` |
| 尾程订单控制、柜级预览与入仓计划转换 | `lastleg-service/`、`warehouse-overseas-service/` |
| 海外入仓分页、FBA 预约、PDA 柜号签收与入仓 | `lastleg-service/` |
| 海外仓排车查询、候选与智能预排 | `lastleg-service/` |
| 海外排车执行、PDA 出库、派送与一件代发 | `lastleg-service/` |
| 海外异常退回、库存恢复与客户回访 | `lastleg-service/`、`file/` |
| 一件代发 SKU/箱唛与暂扣跨区协同 | `order/`、`firstleg/`、`common-event-contract/`、`lastleg-service/` |
| 客户海外仓贴标、转运、废弃与退货换标 | `lastleg-service/` |
| 海外仓 PDA 盘点、移库、托盘、换标与查询 | `lastleg-service/`、`warehouse-overseas-service/` |
| 国内船节点向海外接柜门禁事件 | `firstleg/`、`common-event-contract/`、`lastleg-service/` |
| 海外仓库目录、海外库位、海外托盘、资源锁 | 国内仓库目录归 `warehouse/`，海外资源归 `warehouse-overseas-service/` |
| Lastleg 内部模块化与依赖基线 | `lastleg-service/` |
| 自营领星采集、经营统计、SKU 日销量 | `lastleg-service/selfoperated/` 查询与采集编排；领星签名/分页/外部接口查 `integration-service/`，不因采集页面任务同时读取两服务 |
| 跨客户同仓预约、预约跟进、到港日历 | `lastleg-service/inboundplan/`、`appointmentplanning/`；到港事实查 `firstleg/portschedule/` |
| 车辆、司机证照、车次、外接预订、车队报价、出车记录 | `lastleg-service/fleet/`；先读 `lastleg-service/AGENTS.md` 对应入口，客户排车关联再沿 `dispatch/fleet/` 实际调用 |
| PDF 标签、审计、业务事件直投 | `print/`、`audit-service/`、`common-event-contract/` |

## 公共模块快速索引

| 关键词 | 模块与入口 |
|---|---|
| 公共依赖版本 | `platform-bom/pom.xml`；统一管理公共组件版本，不放业务实现 |
| 通用响应、分页、异常、基础实体与导出契约 | `common-core/`；从 `ApiResponse.java`、`PageResult.java`、`BizException.java`、`ExportContracts.java` 定位 |
| Web 异常、请求关联/Trace、同步出站传播、Long ID 序列化 | `common-web/`；从 `GlobalExceptionHandler.java`、`CorrelationIdFilter.java`、`TraceParent.java`、`FeignTraceRequestInterceptor.java`、`RestClientTraceInterceptor.java`、`LongIdJacksonConfiguration.java` 定位 |
| JWT、JWKS、会话校验与认证用户 | `common-security/`；从 `JwtAuthenticationFilter.java`、`JwtClaimsMapper.java`、`AccessTokenSessionValidator.java` 定位 |
| Springdoc/OpenAPI 自动配置 | `common-openapi/`；从 `BaiyueOpenApiAutoConfiguration.java`、`OpenApiProperties.java` 定位 |
| 业务审计注解、脱敏、Outbox 与投递 | `common-audit/`；从 `BusinessAudit.java`、`BusinessAuditAspect.java`、`SensitiveDataSanitizer.java`、`AuditOutboxPublisher.java` 定位 |
| 跨区域事件信封、Payload 与哈希 | `common-event-contract/`；继续读该目录 `AGENTS.md` |

## 全量验收路由

- 当前订单与客户、入库测量与计费、国内货柜履约、海外仓业务及财务统一进入全量验收；按本次链路读取对应业务域/专题文档，不以历史规划终点阻断跨服务联调或回归。
- `auth`、`iam`、`warehouse`、`order`、`firstleg`、`file`、`finance`、`integration-service` 及出仓相关能力按各自模块契约协作；状态、权限、数据库和 OpenAPI 以当前实现及已确认契约为准。

## 国内头程与海外仓协同

- Auth 是唯一用户账号与 Token 签发方；目标为各端共用 Gateway 和 Redis 会话，保留 RS256/JWKS、客户隔离、权限撤销、PDA 仓绑定及服务身份校验。当前源码已移除旧海外会话验证与 Lastleg 安全投影，改为 Auth 权威会话校验；本地验证不等于测试环境部署验收。
- 装柜、船节点、卸柜、暂扣、派送、费用与资金按统一通信契约的逐事件表直接投递。保留本地 Outbox、消费幂等、重试与失败处置，不携带用户 JWT；旧 Bridge 源码已退出聚合和发布清单，退役待清理；实际停机仍须替代链验证与授权，不得据源码状态认定已部署。
- `lastleg-service` 不读取头程数据库，`warehouse-overseas-service` 不读取尾程订单库。共用测试 MySQL 实例不改变服务数据归属。准确路由、ACK、撤销矩阵和切换门槛只维护在新的两份主契约中。

## 数据库访问与中文代码注释（所有服务及公共模块强制）

- 本节适用于全部后端服务和公共模块；新增代码遵守下列规范，存量分层仅在影响本次正确性或用户明确要求时整改，不因局部修改迁移整条链路；以上为目标规范，不代表存量均已达标。
- 生产代码的关系型数据库读写统一经 MyBatis/MyBatis-Plus Mapper 执行；Controller、Service、定时任务、消费者、编号生成器和公共基础组件不得直接使用 `JdbcTemplate`、`NamedParameterJdbcTemplate`、原生 JDBC/Connection/Statement 或其他通道执行 SQL。仅改成 Repository 包装 JDBC 不算整改，SQL 必须进入 Mapper；无数据库职责的模块不得为满足本条新增数据库访问。
- 正常业务数据库访问路径统一为 `Controller → Service → Repository → Mapper`，四层职责明确，不得省略 Repository，也不得由 Controller 直接调用 Repository/Mapper，或由 Service 直接调用 Mapper。定时任务、消费者等非 HTTP 入口从 Service 进入，同样经 Repository → Mapper 完成持久化访问。
- Controller 负责请求接收、参数校验、入口权限和响应转换；Service 负责业务规则、编排及业务事务；Repository 负责领域数据访问封装、查询组合与持久化模型转换，对 Service 提供有业务含义的数据操作；Mapper 负责 SQL 执行及数据库记录映射。Repository 不承载业务状态流转，不直接用 JDBC 执行 SQL；Service 不继承 MyBatis-Plus `ServiceImpl` 等方式绕过 Repository。
- 复杂查询、批量处理、原子计数、锁定读取、Outbox 和数据库监控查询同样经 Repository → Mapper，不以 SQL 特殊或实现方便为由跳层。公共模块需要数据库能力时，按现有模块边界定义 Repository/持久化接口，由所属服务的 Repository → Mapper 实现，禁止借此跨服务读库。
- 迁移数据库操作须保留客户隔离条件、事务传播、行锁、幂等和并发语义；`LAST_INSERT_ID()` 等连接级操作必须在同一事务连接完成，并明确关闭相关读取缓存，不能仅机械搬移 SQL。Mapper 注册及扫描仍遵守下文统一规范。
- 测试代码可用 `JdbcTemplate` 创建隔离测试表、准备数据及核对结果；被测生产路径仍必须调用实际 Mapper，不得把测试造数做法带入生产。数据库基线和迁移脚本按现有部署契约管理。
- 本次新增或修改的手写方法及构造器须有简短中文业务注释，通常 1—3 行；接口与 Mapper 方法优先用中文 Javadoc，覆盖方法同样适用，关键规则就地说明。不补齐未修改或自动生成方法的注释。
- 核心业务、复杂 SQL、状态流转、资金与库存变更、权限隔离、事务、锁、幂等、并发、重试和补偿逻辑，须在关键代码前增加适量中文注释，解释业务规则、处理原因、约束边界及失败影响；不逐行翻译代码，不添加无信息量或与实现不符的注释。
- 新增和修改的代码说明注释统一使用中文；必要的技术标识、协议名、类名可保留原文，第三方许可证和生成标记保持原样。修改方法时同步更新相关存量英文或过期说明；审查时同时核对 Controller → Service → Repository → Mapper 分层及中文方法、核心逻辑注释。

## 契约、数据库与验证入口

- 对外 Controller/API 新增、改名或删除时，同时核对调用端、统一 Gateway、OpenAPI 和权限；提交前运行 `node --test scripts/gateway-route-contract.test.mjs`，自动发现生产 Controller 并校验网关目标服务与内部路径隔离。失败不得提交或标记完成；网关配置变化必须列入部署清单，不以业务服务单测代替入口检查。

- 跨服务修改先检查调用方 `client/`、被调用方 Controller/DTO、`src/main/resources/openapi/` 和双方契约测试；禁止共享领域 Entity。
- 修改 Java 方法、构造器、Controller、Client、DTO 或 Mapper 参数签名时，先用 `rg` 定向查找符号及旧参数形态，并同步更新 `src/main/`、`src/test/`、Mock、Fixture、契约测试和脚本中的全部调用点。新增可选参数也必须补齐旧测试调用，不能因生产调用已更新就视为完成。
- 所有生产 MyBatis Mapper 接口必须显式标记 `@Mapper`；每个持久化服务只允许在启动类使用一次服务根包 `@MapperScan(..., annotationClass = Mapper.class)`，不得新增子域包白名单或分散的 `*MapperConfiguration`。新增、移动 Mapper 或修改扫描配置后运行 `node scripts/mapper-scan-contract.mjs`；全量后端回归已在 Maven 前执行该门禁时复用结果，输入未变不重复执行。
- 平台后台存在正式列表页时，`*:list` 同时授权列表、详情及只读辅助接口；`create`、`edit`、`delete`、`status`、`approve`、`review`、`export`、`upload`、`complete` 等操作保持独立。当前正式权限契约不保留旧独立 `*:view`；Controller 不得使用 `hasAnyAuthority(list, view)`，OpenAPI 和角色初始化只保留 `*:list`。若外部已有不可变权限契约，先按当前对话建立单独兼容规则。
- 供应商查询接口固定只使用 `platform:supplier:list`；IAM 中 `platform:supplier:list` 是正式菜单资源，`platform:supplier:view` 必须停用/移除，不得重新提升或兼容。
- 权限语义变更必须同步 Controller `@PreAuthorize`、OpenAPI、模块权限 SQL、IAM 菜单资源、统一增量脚本和契约测试。并行模块任务不得覆盖菜单与权限总控已写入共享 SQL 或权限契约的改动。
- 数据库只访问所属服务库。模块表结构位于 `<module>/src/main/resources/db/`；开发环境按最新模块基线和 `deploy/sql/头程数据库统一增量-MySQL8.sql` 收敛，不为历史开发数据新增兼容迁移。已有名称含 `migration` 的脚本仅作结构来源和追溯，部署说明见 `deploy/sql/README.md`；生产升级另按明确发布规则处理。
- 后端同样遵守根指引中的“开发数据和上传文件可丢弃”边界：不得为现有开发库孤儿文件、旧文件归属或历史部分失败新增删除补偿接口、兼容复用、回填或清理链路；只修复当前正式上传与持久化路径，既有开发文件由人工重新上传。
- 通用配置在 `config/nacos/test/`；服务日志、上传文件、`target/`、`reports/` 不属于源码。
- 后端本地验证默认使用 `scripts/backend-check.ps1`，必须显式指定 `-Modules`，不传模块直接拒绝；命令及参数见 `scripts/README.md` 的“后端分层检查”。入口自动经 `local-check.ps1` 限流，`-DryRun` 只检查选择范围，不代表测试通过。
- 开发迭代使用 `-Mode Focused -Tests <精确测试类名>`，覆盖修改行为及直接调用点；Java 签名变化至少使用 `-Mode Compile` 编译生产与测试源码（等价于 `mvn -pl <modules> -am test-compile`）。单服务行为变更收尾使用默认 `Module` 模式执行该服务及上游依赖测试；跨服务 DTO、接口或事件变化必须显式列入生产者和受影响消费者。`-am` 只补上游构建依赖，不自动包含下游服务或 HTTP/事件消费者；不能以单类测试代替模块收尾。
- 仅注释/文档调整不触发 Java 回归；脚本调整执行受影响脚本测试和登记合同。API、Mapper、AGENTS 等静态合同仍按各自触发条件执行。纯重构也应覆盖受影响行为，不能只用编译宣称回归通过。`-Dmaven.test.skip=true` 跳过测试编译，不得作为签名变更交付验证。
- 全仓回归只在以下情况触发：根 POM/统一依赖版本/聚合拓扑/测试基础配置变化；公共认证、序列化、基础模型等影响广泛且不能可靠限定消费者；跨多域批次集成验收；用户明确要求全量回归。使用 `scripts/backend-full-regression.ps1`，保留当前 CI 全量验证。普通单服务任务、单次提交或对话收尾不自动触发全仓；已明确消费者的公共或跨服务变更按受影响模块验证。同批同一相关输入只跑一次，输入变化后补跑受影响范围，触及上述全量条件再重跑全量。
- 不以缩短耗时为由删除金额、库存、权限隔离、状态流转、幂等和并发测试；冗余测试须根据重复场景及维护成本单独评估。不要在本地启动 Java/Nacos/数据库，除非用户明确要求。
- 同一批 `AGENTS.md` 索引修改完成后从后端根统一运行一次 `./scripts/agents-index-contract.ps1`；脚本只读源码目录和指定指引，不访问 HTTP、数据库或部署环境。
- Mapper 注册静态合同为 `scripts/mapper-scan-contract.mjs`、`mapper-scan-contract.test.mjs`：自动发现聚合模块、生产 `*Mapper` 接口、服务启动类和分散扫描配置，不启动 Spring、不连接数据库；遗漏注解、扫描根漂移或重新引入子域扫描时直接失败并输出类与文件路径。
- 单服务镜像构建/部署从 `Jenkinsfile.service`、`deploy/docker/Dockerfile`、`deploy/scripts/deploy-built-service.sh` 进入；新镜像启动失败或健康检查失败时只允许回滚到同服务先前镜像，并保持任务失败，离线合同见 `scripts/deploy-built-service-rollback.test.mjs`。实际部署仍须当前对话明确授权。

## 全量 HTTP 验收脚本路由

- 脚本管理的唯一总索引是 `scripts/README.md`，最近执行规则是 `scripts/AGENTS.md`。仓库级脚本、Admin 内部模块、服务局部合同和部署脚本的目录归属以这两个文件为准，不再通过无范围搜索猜测入口。
- 全量验收唯一指向测试环境 HTTP：平台端执行 `scripts/admin-test-env-acceptance.mjs`，客户端执行 `scripts/client-test-env-acceptance.mjs`；入库测量与计费专项场景才单独执行 `scripts/client-phase2-test-env-acceptance.mjs`，不替代客户端全量入口。
- Client 快速下单定向验收使用 `scripts/client-quick-order-test-env-acceptance.mjs`，只验证批量草稿接口、逐行隔离和幂等行为，不提交、不审核，也不替代 Client 全量入口。
- 固定客户待审核订单使用 `scripts/create-pending-review-orders.mjs`；固定“IT测试”与“义乌仓”、随机真实线路并推进至 `WAIT_SPLIT` 使用 `scripts/it-test-wait-split-bulk.mjs`。二者都是造数入口，不属于全量验证；会写目标环境且不自动清理成功数据。
- Admin 总入口默认按模块列表覆盖平台全链路；需要定位单个业务时使用 `--modules <name>`，模块名称和静态合同先查 `scripts/admin-test-env-modules/README.md`。
- 订舱与拖车跨服务完整状态链由 Admin 注册模块 `service-center-flow` 验证，必须复用本轮已放舱订舱并由总入口展开依赖，不得直接执行模块文件或借历史数据。
- 尾程公网控制由 `phase4-tail-order-controls` 在海外 PDA 前验证整柜接柜仓变更与恢复、单/批目的仓变更、单/批合托标记、CSV 导出、订单费用、暂扣/解除、八个人工节点和逐票人工计划；目的港码头拖车由 `phase5-terminal-drayage` 在卸柜后验证选车队、预约提柜、实际提柜和实际还柜，`phase4-carrier-nodes` 只读核验最终船节点终态。
- 这些脚本会创建、更新或最终停用测试数据；指定测试环境和服务后，本轮非破坏性写入复用一次授权，删除、重置、SQL、部署或发布仍逐项授权，并保存 JSON 报告；未授权不得请求 Gateway。
- 后端 Maven、前端 `pnpm test/typecheck`、PDA `node --test` 和数据库 Dry-run 都是本地质量检查，不属于全量 HTTP 验收。
- Java 模块、OpenAPI 覆盖、JaCoCo 与 SpotBugs 聚合摘要使用 `node scripts/java-quality-summary.mjs`；默认仅报告存量缺口，是否阻断由显式 `--require-*` 参数决定，输出位于 `target/` 时不得作为业务事实或提交物。
- HTTP 全量通过后，才进入 Admin/Client 真实页面调用、浏览器样式和 PDA 页面/设备验收；自动化 HTTP 通过不代表视觉验收完成。
- 修改脚本目录、入口或说明后，至少运行 `node --test scripts/script-documentation-contract.test.mjs`；修改 `AGENTS.md` 后继续运行 `./scripts/agents-index-contract.ps1`。两者均为离线只读合同，不能代替真实 HTTP 验收。

## 业务域文档入口

- 订单与客户：`../docs/订单与客户/README.md`、`../docs/订单与客户/订单与客户头程订单闭环设计.md`
- 入库测量与计费：`../docs/入库测量与计费/README.md`；流程细节按 `../docs/头程到尾程/README.md` 指向的当前阶段文档读取，需求确认和联调报告仅在历史追溯或验收证据任务中读取
- 国内货柜履约：`../docs/国内货柜履约/README.md`，报关规则变化再查 `../docs/国内货柜履约/报关资料与船期价格接入梳理.md`。规划、确认与验收材料按归档位置及文档角色判断，当前入口指定的有效规则仍按需核对，历史材料只用于追溯或证据任务
- 海外仓业务：`../docs/海外仓业务/README.md`；统一入口 `gateway/`，尾程与入仓库存 `lastleg-service/`，海外仓储资源 `warehouse-overseas-service/`
- 海外仓全流程：以正式 Controller、前端路由、权限、SQL 与跨区事件契约为范围依据；海外接柜、入仓、库存、库内服务、排车、出库、派送、一件代发、异常退回和客户回访进入 `lastleg-service/`，国内 SKU/箱唛及暂扣协同进入 `order/`、`firstleg/`、`common-event-contract/`
- 财务：`../docs/财务管理/README.md` 中已确认的范围、对象、状态和接口约束

全量验收需要证据时再读取对应阶段报告和证据矩阵；普通代码定位只读取当前链路涉及的范围、契约、模块指引和代码。