# 海外尾程后端项目指引

## 适用范围

- 本文件适用于 `baiyue-lastleg/` Maven 多模块仓库。修改具体服务前，继续读取该模块的 `AGENTS.md`。
- 本层维护服务边界、跨服务协作、数据库变更入口和通用验证；类、接口和表的入口以模块级指引为准。
- 海外服务不得跨库查询国内头程数据。跨区事实必须通过版本化事件和不可变快照传递。

## 服务路由

| 任务关键词 | 首选模块 | 模块指引 |
|---|---|---|
| RS256、JWKS、Audience、Claims、海外统一入口 | `gateway/` | `gateway/AGENTS.md` |
| 尾程订单、装柜完成事件、Inbox、订单明细、状态历史 | `lastleg/` | `lastleg/AGENTS.md` |
| 入仓计划、托盘分配、PDA 入仓作业、合托 | `lastleg/` | `lastleg/AGENTS.md` 的入仓计划索引 |
| 跨区事件接收、重试、死信、人工补投、投递记录 | `event-bridge-service/` | `event-bridge-service/AGENTS.md` |
| 海外仓、库位、托盘、资源锁定与释放 | `warehouse/` | `warehouse/AGENTS.md` |
| 文件、打印、审计、第三方集成 | `file/`、`print/`、`audit-service/`、`integration-service/` | 对应模块源码；补充业务能力时先新增模块指引 |

## 固定契约与边界

- 头程装柜完成事件固定为 `FirstLegLoadingPlanCompleted` V1，`CN -> OVERSEAS`，聚合类型为 `LOADING_PLAN`。
- 一个事件只承载一个 `tenantId/accountId`；`payload.orders` 中每个最终实装 `sourceInboundId` 独立生成一条尾程订单记录，不按 FBA 仓、渠道或海外仓再次合并。
- 尾程消费者不得回查头程。订单、明细、重量、体积、目的仓、SKU、FBA tracking 和 shipment 等均使用事件冻结快照。
- 事件幂等和业务幂等必须同时成立：相同 `eventId + payloadHash` 重投返回已有结果；`(tenant_id, source_region, source_inbound_id)` 防止重复建单。
- 内部事件接口必须校验 `X-Internal-Service-Token`。外部用户接口由海外网关校验 RS256/JWKS、`aud=lastleg-api` 和必要身份声明。
- 调用方不得通过请求参数任意扩大 `tenantId` 范围；租户范围必须来自可信认证身份或平台权限。

## 数据库与验证

- 模块基线 SQL 位于 `<module>/src/main/resources/db/`。已部署环境的后续字段、注释和索引变更统一追加到 `scripts/db/incremental.sql`，不得依赖修改 `CREATE TABLE IF NOT EXISTS` 自动更新旧表。
- SQL 必须可重复执行，新增索引前检查 `information_schema.statistics`，新增/修改字段前检查 `information_schema.columns`，并保留已有业务数据原文。
- 单模块优先运行 `mvn -pl <module> -am test`；跨事件链路至少运行 `lastleg` 与 `event-bridge-service` 的定向测试。
- 不提交 `target/`、运行日志、临时联调脚本或本地密钥。