优化

src/modules/overseas-business/CONTRACT_GAPS.md

@@ -1,17 +1,16 @@
-# 海外业务待补契约
+# 海外业务真实接口接入与剩余缺口
 
-后端服务边界已经确认：浏览器统一经 `gateway-overseas/`（Audience=`lastleg-api`）访问 `lastleg-service/`；海外采购进入 `procurement/`，本土卡车进入 `trucking/`，本土散板进入该服务的独立稳定子域。现有平台采购与美国卡车 Controller 是接口适配事实来源，不得将这些请求接到国内 `gateway/`、`firstleg/` 或 `warehouse/`。
+模块通过 `@/shared/api/overseasHttp` 访问海外 Gateway，业务路径只传 `/platform/v1/...`。页面不读取 Token、不调用兑换端点，也不感知区域 Base。已接入：
 
-模块当前仍只冻结 TypeScript 请求/响应模型和页面结构；在统一海外 Base/Token 选择与页面 DTO 适配完成前，不创建临时 URL，不使用示例数据，也不模拟提交成功。
+- 海外采购列表、详情及服务端允许字段的 `PATCH` 编辑；
+- 本土卡车列表及详情数据（详情只用于原型既有编辑页的数据承载，不新增详情路由）；
+- 长整型 ID、金额/重量/体积的字符串归一化，真实状态映射，以及加载、失败、重试和空态。
 
-后端接入前需冻结：
+仍缺少或明确不接入：
 
-- 统一认证层对海外 Gateway Base 与短时海外 Token 的自动选择方式；
-- 将采购订单映射到 `lastleg-service` 的 `/api/platform/v1/last-leg/overseas-procurements`，将卡车订单映射到 `/api/platform/v1/last-leg/us-truck-orders`，并补齐当前 Admin 原型所需动作与 DTO；
-- 本土散板的正式平台端点及 DTO；
-- 分页信封、长整型 ID 字符串透传、金额/币种精度和时间格式；
-- 状态机、允许编辑状态、乐观锁版本、幂等键及错误码；
-- 客户、采购仓库等只读候选接口与权限；
-- 对应 `list/create/edit` 权限资源在海外服务端的鉴权落点。
+- 海外采购：后端详情只有出库记录，没有原型“进销存明细”所需的完整入库/余额流水；客户与采购仓库候选接口尚未冻结。平台 `review` 与 `outbounds` 不在本专项接入范围。
+- 本土卡车：平台端只有列表、详情、状态流转和收托盘，没有平台新增或普通编辑接口；新增/编辑提交继续明确阻断，不借用 Merchant、状态流转或收托盘端点。
+- 本土散板：`lastleg-service` 尚无独立稳定 Controller/DTO/OpenAPI，列表、新增、编辑均保持缺口，不借用卡车端点。
+- 权限：前端冻结为 `platform:overseas-business:*`，当前海外服务端采购和卡车管理权限分别为 `lastleg:overseas-procurement:manage`、`lastleg:us-trucking:manage`。冲突只记录，页面不绕过；由共享权限总控统一收口。
 
-接入时应在统一双区域 HTTP/认证层完成 Base 与 Token 选择，业务页面不得自行读写 Token、创建第二套登录或绕回国内 Gateway。
+任何后续写接口都应继续以海外服务 Controller、DTO、OpenAPI 和状态机为准，不发明路径、不模拟成功、不连接国内 Gateway。