优化

AI工程执行与协作约束.md

@@ -0,0 +1,55 @@
+# AI 工程执行与协作约束
+
+## 读取条件
+
+- 运行、构建、依赖、临时目录、工作树、部署、数据库、跨模块改动或独立任务协作时读取本文件。
+- 普通代码定位仍先按根 `AGENTS.md` 的项目和业务路由进入最近的项目/模块指引；本文件不替代业务索引。
+
+## 根目录、临时目录与依赖复用
+
+- 根目录只保留 `apps/` 前端应用、`baiyue-firstleg/` 后端独立仓库、`docs/` 产品与契约文档三类业务事实来源；新增业务源码或服务不得直接放在根目录。
+- `.vscode/`、`.impeccable/`、`.superpowers/` 和根 `.codex-temp/` 属于本地工具或缓存，不作为业务入口；根 `.codex-temp/` 不得存放项目副本。
+- `output/`、`outputs/`、`dist/`、`target/`、日志和临时文件属于生成物，不纳入索引；空的临时产物目录应及时清理。
+- 启动服务、测试、类型检查和构建默认直接在目标项目目录执行，并复用现有 `node_modules/`、Maven 本地仓库及其他依赖缓存；不得仅为运行或验证创建 `.codex-temp/<task>`、`.codex-tmp/<task>` 或完整项目副本。
+- 不得复制、移动或手工链接现有 `node_modules/` 到临时目录。依赖缺失或锁文件变化时，在目标项目执行其声明的安装命令。
+- 只有验证干净基线、隔离不同分支，或隔离破坏性生成器时才可创建临时工作树；优先使用 Git worktree 或系统临时目录并放在目标项目之外，创建前说明原因、位置和清理条件，结束且无进程占用后立即清理。
+- 禁止在 `apps/*/`、`baiyue-firstleg/` 及业务模块内部新增 `.codex-temp/`、`.codex-tmp/`、`worktree/` 或类似项目副本。遗留目录须先确认没有运行进程和唯一证据，再按精确路径清理。
+- 端口冲突通过停止已知旧进程或指定其他端口解决，不得复制项目。普通验证应直接覆盖当前未提交修改，不为获得“干净目录”绕开真实变更。
+
+## 当前开发阶段
+
+- 项目尚未上线，没有需要兼容的生产存量数据、线上客户端或已发布接口版本；用户确认上线后应重新建立版本兼容和升级规则。
+- 对已确认目标直接收敛实现、接口、状态、权限、OpenAPI、前端消费者和初始化 SQL；旧实现冲突时直接修改或移除，不默认保留旧字段、接口、权限、状态或行为的兼容分支。
+- 当前不设计数据迁移、双写、灰度、回滚版本、旧客户端兼容或新旧协议并行，也不为历史开发数据新增迁移脚本；数据库结构以最新完整初始化 SQL 为准。
+- 已有历史 SQL 只用于开发追溯，不构成兼容依据；后端位于独立 Git 仓库 `../baiyue-firstleg/`，执行 Git 命令前确认当前工作目录。
+- “无需兼容和迁移”不授权自动重置数据库、删除数据、执行 SQL 或部署环境。
+
+## 联调、部署与数据库
+
+- 默认只准备代码、验证结果和人工部署步骤，不触发 Jenkins、不启动本地 Java/Nacos/数据库，也不修改测试环境数据。
+- 只有用户在当前轮明确授权指定环境、服务和提交时，才可部署或执行 HTTP 验收；测试环境数据库默认只读。
+- 环境地址、凭据和 Token 不写入源码或 `AGENTS.md`。接口不可用或契约不一致时记录路径、状态、错误码、`requestId`/`traceId` 和阻断原因，不回退到模拟成功。
+- 具体联调脚本、服务启动和验收命令以目标项目指引及 `测试环境Jenkins部署指南.md` 为准。
+
+## 通用工程与质量门禁
+
+- 保持变更小而聚焦，遵循目标项目现有命名、分层和格式，不顺手重构无关代码。
+- 优先复用现有依赖和公共能力；新增或升级依赖前说明必要性、影响范围和替代方案。
+- 不提交依赖目录、构建产物、运行日志、编辑器缓存或本地临时文件；不写入密钥、令牌、真实客户数据或环境特定地址。
+- 用户可见文案保持清晰一致；代码标识符使用英文，业务说明和文档可使用中文。
+- 仅运行目标项目实际声明的安装、检查、测试和构建命令。每次变更至少验证直接受影响的项目，跨项目变更还要验证对应消费者。
+- 修改方法、构造器、组件 Props、函数、接口、DTO 或请求/响应参数时，定向检索全部生产调用、测试调用、Mock、Fixture、契约测试和脚本引用，并同步修改。
+- 参数或类型签名变化必须运行会编译测试源码的最小检查；无法验证时明确列出未验证范围。
+- 修复缺陷优先增加复现测试；没有现成测试设施时不为小改动引入整套框架，应记录验证步骤和剩余风险。
+- UI 变更按受影响范围检查加载、空态、错误态、权限、目标视口和可访问性；Admin/Client 视觉细则查 `Admin-Client前端原型还原验收规则.md` 和目标应用指引。
+- 需求、技术栈或接口未确认时停在可逆设计阶段，不自行作出高成本平台决策。
+
+## 独立任务与多任务协作
+
+- 普通任务不读取协作登记。只有用户明确指定当前对话为总控，或要求检索历史任务、独立任务或跨对话通信时，才读取 `独立任务协作登记.md`。
+- 检索历史任务只使用本机 `~/.codex/session_index.jsonl`、`~/.codex/state_5.sqlite`、`~/.codex/sessions/` 和已知本地任务，不依赖聚合本地、远程主机或云端对话的列表接口。
+- 被指定为总控只授权规划、拆解、协调和复用已登记任务，不授权创建新的用户可见独立任务；临时并行默认使用当前对话或内部子代理。
+- 创建用户可见独立任务必须由用户在当前轮明确要求，并确认精确数量、稳定职责和所属总控；历史授权以及“继续处理”“拆分”“安排”“并行”等表述不构成创建授权。
+- 创建前必须查询登记表并优先复用职责匹配的 `task_id`；一次性缺陷、排障、部署、临时验收和只为提速的并行工作不得登记为长期任务。
+- 创建成功后先登记稳定 `task_id`、所属总控和唯一长期职责，再下发工作；不自动创建替代任务或归档、解档、恢复、迁移任务。
+- 并行前明确文件归属和共享契约。共享导航、根路由、权限初始化和统一 SQL 由已登记的对应总控统一集成；发生重叠时保留现有改动并跨任务协调。

Admin-Client前端原型还原验收规则.md

@@ -31,9 +31,18 @@ Admin 与 Client 已向客户讲解或确认过的页面，必须以对应原型
 - 表格按原型核对外边框、单元格边框、表头背景、斑马纹、行悬停背景、行高和横向滚动。
 - 原型没有的公司名称图标、下划线、卡片装饰、悬停上浮、缩放和渐变效果不得添加。
 
+### Admin 已确认布局基线
+
+- Admin 是高信息密度业务系统。保留原型字段、顺序、业务分组和交互语义，但普通短字段优先使用连续白底、多列键值网格、描述表或紧凑列表，不把“一个标签 + 一个值”做成独立卡片。
+- 详情页顶部尽量合并返回、标题、核心状态和主要操作；路由壳层已显示标题时正文不重复。状态或流程结论只保留一个主要视觉落点，除真实错误、阻断或危险外不叠加大面积彩色横幅。
+- 在 `1920×1080` 下短字段通常并排 `4–6` 组；长文本、地址、备注和异常原因可以跨列或换行。长编号集中省略说明列宽设计失败，应调整列数、宽度或跨列，不继续缩小字号。
+- 同一详情页使用一致的内容底色和容器语言；连续白底区域用分隔线和间距分区，同级独立卡片的背景、圆角、边框和外间距保持一致。
+- 高信息密度不授权缩小可点击区域、删除标签、强制截断关键值或牺牲可访问性。使用真实长编号、空值、状态徽标和多字段数据核对首屏。
+- 原型明确的承载方式和视觉细节优先；历史原型仅因大量字段卡片、重复状态块或过度留白与当前密度基线冲突时，收敛承载方式但不改变字段、分组和交互语义。
+
 ## 响应式与可访问性
 
-- 桌面布局以原型为准；同时检查 720px 与 320px，窄屏只做保证可用所需的最小退化，不改变桌面信息结构。
+- Admin、Client 当前只按 `1920×1080`、浏览器缩放 `100%` 验收；不检查或整改 `720px`、`320px` 等窄屏，也不删除已有响应式能力。用户恢复多视口验收后再统一调整。
 - 弹框正文超过视口时只滚动正文，标题和操作区保持可见；独立详情页按正常页面滚动。
 - 保留键盘操作、焦点、表单标签、图标按钮名称和足够对比度。可访问性调整不得改变原型的主要布局与视觉语义。
 
@@ -41,7 +50,7 @@ Admin 与 Client 已向客户讲解或确认过的页面，必须以对应原型
 
 1. 先提交逐页矩阵，不直接批量替换公共组件。
 2. 总控冻结该页结论后，任务只修改职责内模块，不触碰其他任务在途文件。
-3. 修改后提供桌面与 320px 截图或等价浏览器证据，并标注与原型仍存在的差异。
+3. 修改后由人工在 `1920×1080`、`100%` 缩放下操作并提供截图，标注与原型仍存在的差异；缺少截图时记录“待人工截图确认”，AI 不自行批量取证。
 4. 运行直接测试与类型检查；共享组件变更必须检查全部消费者。
 5. 不触发 Jenkins、不部署、不提交，除非当前对话另有明确授权。
 

README.md

@@ -12,6 +12,9 @@
 
 ## 跨阶段参考
 
+- [跨区域认证与服务通信契约](跨区域认证与服务通信契约.md)：统一账号、国内/海外 Token、双区域 API、JWKS、Outbox/Inbox 与服务身份边界。
+- [平台、客户层级与权限契约](平台客户层级与权限契约.md)：平台/客户两级产品语义、列表包含详情的只读权限和跨层同步要求。
+- [AI 工程执行与协作约束](AI工程执行与协作约束.md)：临时目录、依赖复用、当前开发阶段、部署数据库授权、质量门禁和独立任务协作规则。
 - [财务管理闭环盘点与范围建议](财务管理/README.md)：基于当前入库计费、财务原型和现有代码盘点财务闭环、缺口及建议的首期应收边界。
 - [墨家设备测量上传接口说明 V3](墨家设备测量上传接口说明-V3.md)：墨家测量设备经 Gateway 上传箱码、尺寸、重量和图片的开放接口契约。
 - [统一订单主状态与操作契约](统一订单主状态与操作契约.md)：统一订单七状态、操作编码、内部状态兼容映射，以及与三期一致的 `LOADED` 硬门禁和 `DELIVERED` 可信回传边界。

四期/四期后端缺口清单.md

@@ -0,0 +1,105 @@
+# 四期后端缺口清单
+
+更新日期：2026-08-19
+
+## 口径与边界
+
+- 本清单以当前四期范围、后端代码、静态 OpenAPI、数据库基线、IAM 初始化 SQL 和本地测试为依据。
+- “已实现”表示已有可定位的领域实现、持久化和直接测试，不代表已经部署或完成测试环境 HTTP 验收。
+- “部分实现”表示已有主体或单点能力，但缺少安全、契约、状态衔接或页面所需查询中的至少一项，不能作为稳定前端契约交付。
+- 明确排除海外仓出库、退货出库、海外派送及其他库存离仓履约。代码中的 `dispatch/`、`delivery/`、`ll_outbound_*` 不计入四期完成度。
+
+## 总览
+
+| 业务域 | 判定 | 当前事实 | 主要缺口或下一闭环 |
+|---|---|---|---|
+| 海外 Token 与 JWKS | 部分实现 | Auth 登录与刷新已同时返回国内 Token 和短时 RS256 海外 Token，海外 Token Claims 已统一为下划线命名；JWKS、海外网关和两个海外业务服务按 `lastleg-api` Audience 验签并使用 Claims 授权，不依赖国内 Redis 会话 | 仍缺 Auth—Gateway—Servlet 服务跨模块契约测试；`POST /auth/overseas/token` 仅保留为过渡兑换能力，不作为四期稳定前端契约 |
+| `gateway-overseas` 路由与入口安全 | 部分实现 | 已路由 `/api/*/v1/last-leg/**`、海外仓库、File/Print 等海外部署服务；可校验 Issuer、Audience、必要 Claims 和应用域，并清洗可信身份头 | 网关只做应用域，不做资源权限；静态路由未覆盖尚未实现的四期通用资料 API；可信身份头只传身份、不传权限是合理边界，资源权限必须由下游 JWT Claims 校验 |
+| 装柜完成跨区建单 | 已实现 | Firstleg Outbox、版本化装柜完成事件、Event Bridge Inbox/重试/死信式 `DEAD`、Lastleg Inbox 幂等和事务建单均有实现及测试 | 与四期到港/可提柜衔接是另一事件，当前缺失，不能复用装柜完成事件冒充到港 |
+| 尾程订单 | 部分实现 | 有事件建单、列表、详情、CSV 导出、目的仓单条/批量调整、客户隔离与状态历史 | 平台接口大多仅校验平台应用域，未按 `list/edit/export` 等资源权限闭环；IAM 仍保留独立 `detail` 权限，违反“列表包含详情只读”统一语义；缺静态 OpenAPI |
+| 海外接柜、卸货与入仓 | 部分实现 | 有入仓计划转换、FBA 预约、托盘分配、PDA 实收/上架/合托/完成以及实收后库存落账 | 缺“国内出仓后到港结果 → 海外可提柜/接柜任务”的事件或内部契约；缺接柜车辆/运抵/卸货节点聚合；入仓单列表和正式详情契约不足，现有 Controller 主要是转换与单号详情；权限资源和静态 OpenAPI 未闭环 |
+| 换标 | 部分实现 | 有换标申请、明细、状态历史和库存联动服务及测试 | 仅有平台接口且权限未闭环；状态机与前端四期页面字段尚无静态 OpenAPI；需确认换标完成后库存 SKU/箱唛快照的稳定查询形态 |
+| 海外仓托盘与库位 | 部分实现 | `warehouse-overseas-service` 有仓库、地址、能力、库位、托盘、绑定和资源锁；平台/商户及内部锁定接口均存在 | 平台资源接口要求显式 `customerId`，与“仓储资源可独立查询全部客户和仓库”的产品约定存在冲突；仅校验平台应用域，缺细粒度权限；缺静态 OpenAPI |
+| 箱号管理 | 部分实现 | 一件代发领域保存来源箱唛、箱级库存和箱流水，库存查询可返回部分箱/SKU事实 | 没有面向四期 Admin 的箱号列表、详情、筛选及只读权限契约；现有 Dropship 接口是内部接收口，不能直接作为平台箱号管理 API |
+| 产品库 | 缺失 | 现有 SKU 仅作为尾程明细、采购明细或一件代发库存快照存在 | 无独立产品主档、平台 CRUD/查询、唯一键/启停规则、静态 OpenAPI、权限和表结构 |
+| 库存及库内操作 | 部分实现 | 有余额、仓位、流水、汇总查询；有 hold/release/allocate/unallocate/pick/ship/adjust 命令幂等；PDA 实收后可入可用库存 | 四期排除库存离仓，因此 `pick/ship` 不应作为四期交付；其余平台命令有代码权限常量但 IAM 未初始化；查询接口缺只读权限；跨仓转移包含出仓动作，需把四期可验收部分限定为不离仓库内操作；缺静态 OpenAPI |
+| 海外采购订单 | 部分实现 | 商户下单、平台审核/管理、采购单据余量及测试已存在，PDA 实收才进入可用库存的边界已建立 | 页面需要的平台列表/详情/编辑字段需与现有 API 冻结；代码使用的 `lastleg:overseas-procurement:*` 未写入 IAM 种子；手工采购出库属于库存离仓，不纳入四期；缺静态 OpenAPI |
+| 本土卡车 | 部分实现 | 平台/商户订单、托盘明细、状态历史和测试存在 | 需确认该子域是四期“本土卡车”而非海外派送；平台只使用单一 `manage` 权限且 IAM 未初始化；缺列表只读/操作拆分和静态 OpenAPI |
+| 本土散板 | 缺失 | `lastleg-service` 无稳定子域、Controller、表或测试 | 新建独立领域，不能复用出库/派送表；先冻结状态、字段、权限和与库存的非离仓边界 |
+| 海外仓合作仓类型 | 已实现 | 国内 Warehouse 已新增正式类型码 `OVERSEAS_PARTNER`，与普通海外仓 `OVERSEAS` 明确区分；保存、查询筛选、列表响应、批量导入、Schema 注释、统一 SQL 和测试已同步；Admin 已完成列表筛选、新增/编辑及保存透传；内部服务令牌接口 `GET /internal/warehouses/overseas-partners` 仅供海外报价服务读取当前启用候选 | 实际环境 SQL 尚未执行；前端不得调用内部合作仓接口，也不跨区域为报价拉取国内候选 |
+| 海外仓报价 | 缺失 | 国内 Warehouse 有“海外仓阶梯仓租费”，但没有四期原型所指完整海外仓报价主数据；已冻结合作仓来源方案：海外报价服务仅在创建时通过内部服务身份读取国内 `ACTIVE + OVERSEAS_PARTNER` 列表并缓存 30 分钟 | 需实现报价维度、币种、有效期、服务项、仓库/客户作用域和权限/OpenAPI/SQL；报价保存合作仓 ID、编码、名称快照，缓存未命中时强制刷新一次后再拒绝 |
+| 汇率管理 | 缺失 | 四期目标服务中无汇率主档、接口、权限或表 | 汇率仅作为业务换算主数据；财务记账/结算汇率口径必须交财务总控冻结 |
+| 车辆列表/详情 | 缺失 | 卡车订单仅保存车辆字段快照，没有车辆主档 | 需独立车辆主数据、启停/证照字段、平台查询与权限；不得把订单快照当车辆主档 |
+| 国内出仓后船节点 | 部分实现 | Firstleg 已有 `CarrierScheduleQuery` 任务、尝试、历史、来源、过期、幂等、真实订舱/柜次关联和“3 天窗口最多 3 次”约束；船期及查询任务的列表、详情、历史、船司辅助查询已统一使用 `*:list`，旧 `*:view` 初始化资源已清理 | 当前适配器全部返回 `MANUAL_REQUIRED`，Integration 无船司/轨迹 DTO、内部接口或适配器；没有定时调度、任务租约、退避、失败重试、到港停止条件、最新标准节点事实或到港跨区事件；领域 SQL 文件仍沿用历史三期命名 |
+| 四期 IAM 权限 | 缺失 | 仅初始化少量尾程订单权限；代码内有库存、PDA、废弃、转仓、采购、卡车等权限常量 | 建立四期资源矩阵；所有正式列表用 `*:list` 覆盖详情和只读辅助接口，写操作独立；同步 Controller、OpenAPI、IAM 基线、统一 SQL 和契约测试 |
+| 四期静态 OpenAPI | 缺失 | 船节点已有静态 YAML；Lastleg、Overseas Warehouse、Auth 海外 Token、到港事件及四期主数据没有完整静态 OpenAPI | 按浏览器公网 API、内部 API、事件三类拆分契约，先于前端正式联调冻结 DTO 与错误码 |
+| 海外费用与 Finance | 跨总控依赖 | Lastleg 当前无四期费用事实 Outbox；Finance 口径不属于本总控 | 本总控只定义来源事件候选、业务键、币种/金额/来源快照与幂等字段，提交财务总控冻结入池条件、审核、结算和汇率口径后再实现生产者 |
+
+## 已确认可复用的实现
+
+1. `common-event-contract` 的版本化信封、事件 ID、区域、Payload 哈希和装柜完成 V1/V2。
+2. `event-bridge-service` 的 Inbox、投递尝试、租约式领取、重试上限、`DEAD` 和人工补投。
+3. `lastleg-service` 的装柜完成幂等建单、来源快照、入仓计划/PDA、库存余额/仓位/流水、换标、采购和本土卡车主体。
+4. `warehouse-overseas-service` 的海外仓档案、库位、实物托盘、业务绑定和资源锁。
+5. Firstleg `CarrierScheduleQuery` 的人工任务壳、尝试/历史/来源/过期和操作幂等。
+
+## 最小闭环实施批次
+
+### 批次 0：认证与契约门禁
+
+1. 收口海外 Token 下划线 Claims、Audience/JWKS 和 Claims 模式权限快照；增加 Auth—Gateway—Servlet 服务跨模块契约测试。
+2. 冻结四期 API 路径、DTO、错误码和权限矩阵；删除尾程/船节点旧独立详情权限，按 `list` 统一只读语义。
+3. 为 Lastleg、Overseas Warehouse、海外 Token 增加静态 OpenAPI；补齐 Gateway 路由合同测试。
+
+验收终点：平台/商户海外 Token 能分别访问正确应用域；错误 Audience、缺 Claim、过期/错签、伪造身份头和缺资源权限均稳定拒绝。
+
+### 批次 1：到港衔接与接柜入仓最小闭环
+
+1. 在 Integration 建立标准船节点查询请求/响应、供应商错误归一、超时/限流/重试配置和内部服务令牌接口。
+2. 在 Firstleg 增加出仓后自动建任务、到期任务租约领取、重试/退避、标准节点幂等落库、目的港到达停止条件。
+3. 新增“目的港到达/可提柜”版本化跨区事件；Lastleg Inbox 消费后建立接柜/入仓衔接事实。
+4. 补齐入仓单列表/详情、接柜/运抵/卸货状态，复用现有入仓计划、PDA 实收/上架和库存落账。
+
+验收终点：一条真实装柜/订舱/柜次链路从国内确认出仓，经节点查询，到港后在海外形成可操作入仓单，PDA 完成后生成库存；重复事件和重复任务不产生重复单或库存。
+
+### 批次 2：海外仓管理面闭环
+
+1. 冻结并实现产品主档与箱号平台查询；明确来源快照与可编辑主档的边界。
+2. 补齐换标、托盘、箱号、产品、库存查询及不离仓库内操作的权限/OpenAPI。
+3. 调整海外仓资源查询，不以客户筛选限制仓库候选；补细粒度资源权限和越权测试。
+
+验收终点：四期前端所需七类海外仓页面均有稳定的列表、详情和允许操作 API，且不暴露出库/派送能力。
+
+### 批次 3：海外业务闭环
+
+1. 收口采购订单与本土卡车的列表/详情/写操作权限和静态 OpenAPI，排除采购手工出库及派送语义。
+2. 新建本土散板领域、状态历史、幂等、权限、SQL、OpenAPI 和测试。
+
+验收终点：采购、本土卡车、本土散板均能独立建单、查询、推进本期允许状态，并与库存离仓业务隔离。
+
+### 批次 4：合作仓与通用资料
+
+1. 国内 Warehouse 与 Admin 的 `OVERSEAS_PARTNER` 主数据全链路已完成。
+2. 实现海外仓报价、汇率、车辆主数据及权限/OpenAPI/SQL。
+3. 将海外费用事件候选契约提交财务总控；只有财务口径冻结后才实现费用 Outbox。
+
+验收终点：合作仓、报价、汇率、车辆均可作为稳定主数据被四期业务引用；任何财务落账仍以财务总控确认契约为准。
+
+## 跨总控依赖
+
+| 接收方 | 需要冻结/确认 | 本总控交付 |
+|---|---|---|
+| 四期前端页面总控 | 合作仓类型码、各页面最小字段/筛选/动作、平台与商户 API 使用范围 | 稳定路径、DTO、枚举、权限码、错误码、分页/幂等约定和 OpenAPI；不修改前端共享导航/根路由 |
+| 财务改造总控 | 海外费用入池条件、审核与结算状态、记账/结算汇率、来源作废/调整规则 | 业务来源事件候选、不可变来源快照、业务键/版本/币种/金额/发生时间/区域和幂等语义；不改 Finance 状态机 |
+
+当前协同状态：四期前端总控已完成双 Token 原子适配，登录/刷新消费 `overseasAccessToken: string | null` 与秒单位 `overseasExpiresIn`；海外请求缺 Token、临近过期或收到 401 时统一触发一次国内刷新并使用响应中的新海外 Token 重放，不再依赖 `POST /auth/overseas/token`。共享认证定向 19 个测试已通过；前端后续全量 typecheck 与 build 也已通过。
+
+合作仓协同状态：Admin 已启用 `OVERSEAS_PARTNER` 的类型、筛选、新增、编辑与保存透传，普通 `OVERSEAS` 保持独立；前端定向 30 个测试、全量 1144 个测试、typecheck 与 build 均通过。前端不调用 `/internal/warehouses/overseas-partners`，该接口只属于未来海外报价服务的服务间契约。
+
+## 本轮直接收口
+
+- Auth 海外 Token Claims 改为与 Gateway、可信身份头和海外服务一致的 `user_id`、`tenant_id`、`membership_id`、`app_code`、`client_type`、`permission_version`，保留 `roles` 与 `authorities` 授权快照。
+- Auth 登录、刷新共用一次权限快照并同时签发国内 Token 与 `overseasAccessToken`；`overseasExpiresIn` 单位为秒。海外 JWT 未启用的本地配置下两字段分别为 `null`、`0`。
+- 港务船期与船司查询的只读 Controller、静态 OpenAPI、模块 SQL、统一 SQL 和契约测试统一使用 `*:list`；初始化脚本显式删除旧 `*:view` 角色关联与资源，不执行数据库操作。
+- 国内 Warehouse 新增 `OVERSEAS_PARTNER` 海外合作仓类型，覆盖保存、筛选、响应、导入和 SQL 注释，并提供受内部服务令牌保护的启用合作仓候选接口；`mvn -pl warehouse -am test` 通过（192 个测试）。海外报价创建读取合作仓采用内部服务调用与 30 分钟缓存，缓存未命中时强制刷新一次。
+- 验证：`mvn -pl auth,gateway-overseas -am test` 通过（33 个测试）；`mvn -pl firstleg -am test` 通过（781 个测试，0 失败、0 错误、2 个既有跳过）。

平台客户层级与权限契约.md

@@ -0,0 +1,27 @@
+# 平台、客户层级与权限契约
+
+## 产品层级
+
+- 当前产品只面向“平台、客户（企业）”两级，不把“租户”作为用户可见或需要运营选择的产品层级；多租户产品能力后续另行设计。
+- Admin 页面、菜单、筛选、表单和提示统一使用“客户”或“企业”文案，不新增“租户选择器”“目标租户”等交互。
+- 平台仓库属于平台公共主数据，不与客户绑定。托盘、库位等仓储资源页面应能独立查询全部客户和全部仓库，客户筛选不得控制仓库候选范围。
+- 后端仍存在 `tenantId` 等字段时，只作为现阶段接口隔离细节保留在 API 适配层，不据此扩展用户可见产品层级；改动真实隔离模型前仍需单独确认。
+
+## Admin 菜单与只读权限
+
+- 统一语义是“列表权限包含详情只读访问，操作权限独立”。存在正式列表页时，以稳定的 `*:list` 权限作为菜单、列表路由、详情路由、列表接口、详情接口及只读辅助接口的主权限。
+- `create`、`edit`、`delete`、`status`、`approve`、`review`、`export`、`upload`、`complete` 等会改变数据、状态或产生文件的操作继续使用各自独立权限，不得因拥有 `list` 自动放行。
+- 当前尚未上线；同一资源已有 `*:list` 时，不保留或新增独立 `*:view` 兼容分支。前端不得使用 `permissionAnyOf` 接受旧 `view`，后端不得使用 `hasAnyAuthority(list, view)`，初始化 SQL 应停用或删除旧 `view` 资源及其角色关联。
+- 供应商固定使用 `platform:supplier:list` 作为菜单、列表和详情唯一只读权限；`platform:supplier:view` 必须停用或移除，不得在导航、路由、页面、Controller、OpenAPI 或 SQL 中恢复兼容。
+
+## 跨层同步
+
+- 菜单结构、路由权限、页面按钮、Controller `@PreAuthorize`、OpenAPI 权限说明及 IAM 初始化/统一增量 SQL 必须同步核对，不能以局部测试通过替代跨层一致性。
+- 业务功能任务只维护所属页面与接口，不得根据局部旧上下文覆盖共享导航、根路由装配、IAM 菜单权限初始化或统一增量脚本中的已确认语义。
+- 发现共享文件与本契约冲突时，保留现有其他任务改动并交由对应总控统一收口；只有用户当前明确改变本契约时才能调整。
+
+## 维护入口
+
+- 前端执行入口：`../apps/admin-web/AGENTS.md`、`../apps/client-web/AGENTS.md`。
+- 后端执行入口：`../baiyue-firstleg/iam/AGENTS.md`、`../baiyue-firstleg/auth/AGENTS.md` 及目标业务服务最近的 `AGENTS.md`。
+- 本文件维护稳定产品语义；具体权限码、菜单路径、Controller 和 SQL 路径由最近的项目或模块索引维护。

独立任务协作登记.md

@@ -4,9 +4,10 @@
 
 ## 当前状态
 
-- 财务改造已启用一个总控和四个长期独立任务；只按下方登记的稳定 `task_id` 协作。
+- 当前已启用财务改造、四期前端页面和四期后端缺口三个平级总控；只按下方登记的稳定 `task_id` 协作。
+- 财务总控下登记五个长期专项，四期前端总控下登记四个长期专项；四期后端缺口暂由后端总控直接统筹，不自动拆分新的用户可见任务。
 - 其他普通工作仍采用“一个任务、一个对话、逐项修复”的方式，不根据历史名称或旧职责向未登记对话下发。
-- 侧栏其他旧任务不属于本轮财务协作，是否归档由用户人工决定，Codex 不自动归档、解档或恢复。
+- 侧栏其他旧任务不属于本轮已登记协作，是否归档由用户人工决定，Codex 不自动归档、解档或恢复。
 
 ## 重新启用门禁
 
@@ -22,8 +23,9 @@
 
 | task_id | 展示名称 | 长期职责 |
 |---|---|---|
-| `01a01490-08e6-7b11-b16f-0085e232d04c` | 财务改造总控 | 冻结财务共享产品契约、状态机、OpenAPI、权限与数据库边界；协调四个财务专项并统一集成共享导航、权限 SQL、跨任务回归和验收结论 |
+| `01a01490-08e6-7b11-b16f-0085e232d04c` | 财务改造总控 | 冻结财务共享产品契约、状态机、OpenAPI、权限与数据库边界；协调五个财务专项并统一集成共享导航、权限 SQL、跨任务回归和验收结论 |
 | `01a018cb-a435-7c61-91ca-4f3e484dca75` | 四期前端页面总控 | 负责四期 Admin 前端页面的统一规划、实现与集成：国内出仓后船节点查询、海外仓尾程订单/入库/换标/托盘/箱号/产品/库存、海外采购/本土卡车/本土散板、海外仓合作仓类型、海外仓报价/汇率/车辆；统一维护四期前端路由、导航、权限、原型还原和回归，不承接海外仓出库业务或后端实现 |
+| `01a0194a-259c-7171-8967-074731a27618` | 四期后端缺口总控 | 负责四期后端缺口的统一盘点、契约收口、实现集成与回归：海外区域 Gateway、尾程与海外仓服务，海外接柜入仓、库存与库内操作，海外采购/本土卡车/本土散板，合作仓与报价/汇率/车辆主数据，国内出仓后船节点定时查询，以及所需 IAM、海外 Token、OpenAPI、初始化 SQL 和跨区域事件契约；向四期前端总控提供稳定 API，涉及 Finance 口径时交由财务总控冻结；不承接海外仓出库、海外派送、前端页面或财务状态机 |
 
 长期独立任务：
 

跨区域认证与服务通信契约.md

@@ -0,0 +1,33 @@
+# 跨区域认证与服务通信契约
+
+## 适用范围
+
+- 本契约适用于 Admin、Client、国内头程服务、海外网关、尾程服务、海外仓资源服务及跨区域事件桥接。
+- 业务范围仍按对应阶段和模块文档确定；本文件只冻结跨区域账号、请求路由、服务鉴权和事件通信边界。
+
+## 统一账号与 Token
+
+- Admin、Client 只维护一套前端和一套用户账号体系；用户登录和 Token 签发统一归国内头程 Auth，不得为海外仓再创建独立登录、账号或权限体系。
+- 统一使用 RS256/JWKS 信任链，但区分 Token 用途：国内登录/刷新时由同一 Auth 同时签发国内 Token 和短时海外 Token；海外 Token 限定海外 Audience，并携带海外 API 所需身份、客户范围和权限快照。
+- 用户只登录一次，由前端统一认证模块按目标 API 自动选择 Token，不在页面或业务模块中分叉登录逻辑。
+- JWKS 只暴露公钥验证能力，不暴露私钥；国内服务验证登录 Token 并结合 Redis 会话实现即时退出和权限变更，海外服务不访问国内 Redis，只验证海外访问 Token 的签名、Issuer、Audience、有效期、应用域、客户范围和权限 Claims。
+
+## 区域 API 路由
+
+- 一套前端使用国内、海外两个区域 API Base：国内业务直连 `gateway/`，海外仓业务直连 `gateway-overseas/`，再由海外网关路由到 `lastleg-service/`、`warehouse-overseas-service/` 和海外部署的公共服务。
+- 日常海外请求不得经国内 Gateway 中转。区域地址、Token 选择和刷新由环境配置与统一 API/认证层处理，业务页面不得感知部署区域差异。
+- 海外浏览器请求的具体 Audience、Claim 和路由以前端项目、`auth/`、`gateway-overseas/` 最近的 `AGENTS.md` 与实际配置为准；修改其中任一项时必须联查全部生产者和消费者。
+
+## 跨区域事件与服务身份
+
+- 头程与海外仓的数据流转使用 MQ 的 Outbox → Inbox、事件幂等、重试和死信机制。
+- 事件使用版本化信封、事件 ID、业务键、来源/目标区域和 Payload 哈希，不携带用户 Access Token。
+- 费用由海外仓发布事件，头程 Finance 消费并按来源快照入账；财务状态机和结算口径仍由财务契约冻结，海外服务不得自行定义。
+- MQ 使用独立的服务身份、TLS 和 ACL；服务间事件鉴权与用户 JWT 鉴权分开。只有明确的同步 HTTP 内部接口才使用内部服务令牌。
+- 修改事件时联查 `common-event-contract/`、`event-bridge-service/`、生产服务、消费服务、幂等记录、重试/死信和契约测试。
+
+## 修改与验收
+
+- Token、Audience、Claim、JWKS、API Base 或刷新策略变化时，至少联查 Auth、IAM、Admin/Client 统一认证层、国内/海外 Gateway、`common-security/` 和目标海外服务。
+- 跨区域事件变化时同步检查事件版本、Payload 哈希、Outbox、Inbox、重复投递、失败重试、死信和全部实际消费者。
+- 本文件是跨区域通信的公共事实来源；项目和模块 `AGENTS.md` 只保留执行所需摘要及本文件入口，不复制完整协议。