admin-web/src/modules/overseas-master-data/CONTRACT_GAPS.md

海外通用资料接口缺口

本文件记录 Admin 海外通用资料与当前 Java 契约之间的实际差距。前端页面类型只是原型展示模型，不是已经发布的服务端 DTO。

已确认的服务入口

• gateway-overseas 将 /api/platform/v1/last-leg/** 路由到 lastleg-service。
• gateway-overseas 将 /api/platform/v1/warehouses/**、/api/platform/v1/warehouse-admin/** 路由到 warehouse-overseas-service。
• 网关海外 Token Audience 为 lastleg-api。
• 两个海外服务没有提交对应业务的静态 OpenAPI YAML；运行时契约由 Springdoc 注解生成，网关暴露 /lastleg-service/v3/api-docs/** 和 /warehouse-overseas-service/v3/api-docs/**。

warehouse-overseas-service 已有实际海外仓聚合接口：

操作	端点	请求/响应	当前限制
仓库列表	GET /api/platform/v1/warehouse-admin	必填 customerId；page、size、countryCode、capabilityCode、status；返回 PageResult<WarehouseEntity>	仅校验平台身份，没有与本模块冻结权限对应的细粒度权限；按客户隔离，不能直接当作平台全局报价仓候选
仓库详情	GET /api/platform/v1/warehouse-admin/{id}	必填 customerId；返回仓库、地址、能力聚合	需要先冻结报价/车辆记录与客户、海外仓的外键口径
仓库新增/编辑/启停	POST、PUT /{id}、PATCH /{id}/status	WarehouseRequests.SaveRequest；状态仅 ACTIVE/INACTIVE	属于实际海外仓资源，不是国内公共合作仓类型，也不是报价、汇率或车辆主数据接口

上述接口不在本模块接入：它们是按客户隔离的实际海外仓资源，不是平台公共合作仓，也不是海外报价、汇率或车辆主数据。业务页面不得为了补候选数据而跨区域拼接这两类仓库资源。

国内 Warehouse 已正式支持公共类型 OVERSEAS_PARTNER，Admin 在现有 /api/platform/v1/warehouse-admin 仓库页完成筛选、新增和编辑。国内服务另有受 X-Internal-Service-Token 保护的 GET /internal/warehouses/overseas-partners，仅供未来海外报价服务内部读取 ACTIVE + OVERSEAS_PARTNER 候选；前端不得调用该内部端点，报价页面也不跨区域拉取国内合作仓列表。

页面与操作缺口

页面/操作	端点	DTO	权限	状态机/规则	结论
海外仓报价列表、筛选、详情	缺失	缺少报价概要、仓储费用、中转派送价格及分页 DTO	已冻结只读权限 platform:overseas-master-data:quote:list，服务端未实现	需定义生效区间、版本唯一性及当前有效版本规则	保持结构化空态
海外仓报价新增、编辑	缺失	缺少基础信息、费用明细、派送价格保存 DTO；海外仓必须使用真实 ID，不能只传名称	create/edit 动作权限未冻结	需定义并发版本、日期重叠、费用组合去重与金额精度	写按钮禁用
海外仓报价启停、删除、导出	缺失	缺少状态命令、删除约束和导出任务 DTO	status/delete/export 动作权限未冻结	需定义 ACTIVE/INACTIVE、历史引用后的删除规则和导出方式	写按钮禁用
汇率摘要、列表、详情	缺失	缺少 yyyy-MM、USD→CNY 月平均值、更新人/时间及备注 DTO	已冻结只读权限 platform:overseas-master-data:exchange-rate:list，服务端未实现	固定方向应为 1 USD = X CNY；需定义精度和月份时区	保持结构化空态
汇率新增、覆盖编辑	缺失	缺少月度汇率保存 DTO	edit 动作权限未冻结	需定义同月唯一、覆盖/乐观锁及下游引用后的修改规则	写按钮禁用
车辆列表、详情	缺失	缺少车辆档案、归属、区域、里程、司机/外派单位、派送订单与更换历史 DTO	已冻结只读权限 platform:overseas-master-data:vehicle:list，服务端未实现	需定义车辆状态及其与派送订单的关联来源	保持结构化空态
车辆新增、编辑、删除、导出	缺失	缺少车辆保存、删除约束和导出 DTO	create/edit/delete/export 动作权限未冻结	需定义车牌唯一性、归属变化、里程校验和被引用车辆删除规则	写按钮禁用

lastleg-service 的 GET /api/platform/v1/last-leg/us-truck-orders 等接口管理的是本土卡车业务订单，写操作权限为 lastleg:us-trucking:manage，状态从 PENDING_REVIEW 经收货、分配、派车、运输推进至 COMPLETED。它不是车辆档案，不得用订单字段拼装车辆主数据或复用其权限。

前端权限边界

• 海外仓报价：platform:overseas-master-data:quote:list
• 汇率管理：platform:overseas-master-data:exchange-rate:list
• 车辆列表/详情：platform:overseas-master-data:vehicle:list

新增、编辑、启停、删除、导出等写操作继续按动作使用独立权限。列表权限只包含对应列表、详情和只读辅助数据访问。