baiyue-lastleg/AGENTS.md

海外尾程后端项目指引

适用范围

• 本文件适用于 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/、运行日志、临时联调脚本或本地密钥。