diff --git a/AGENTS.md b/AGENTS.md index 7e8463b6..09a8334e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -63,9 +63,9 @@ | 报关协同 | `modules/customs/` | `firstleg/customs/`、`file/`；报关代理联查 `modules/suppliers/` 与 `warehouse/src/main/resources/openapi/supplier-v1.yaml`，服务端契约见 `firstleg/src/main/resources/openapi/customs-v1.yaml` | | 国内出仓确认 | `modules/outbound-dispatch/` | `firstleg/outbound/dispatch/` | | 主数据与下载 | `modules/master-data/`、`modules/downloads/` | `warehouse/`、`file/`；Finance 导出联查 `finance/` 内部 Export Provider 与 File 导出定义 | -| 四期海外仓接柜、入库与库内库存 | `modules/overseas-warehouse/`；先读 `../../docs/四期/README.md`，不得以 `src/prototype/` 作为业务实现 | 海外区域 API/服务；原型定向读取 `03-overseas-warehouse.html`。包含尾程订单、入库、换标、托盘、箱号、产品和库存，不包含海外仓出库及海外派送 | -| 四期海外业务 | `modules/overseas-business/`；先读 `../../docs/四期/README.md` | 海外区域 API/服务；原型定向读取 `07-overseas-business.html`；包含采购订单、本土卡车和本土散板 | -| 四期仓库与通用资料扩展 | 海外仓合作仓类型进入 `modules/warehouses/`；海外仓报价、汇率和车辆进入 `modules/overseas-master-data/` | 仓库类型联查 Backend `warehouse/`；海外报价、汇率和车辆联查海外区域 API/服务；原型定向读取 `10-general.html` | +| 四期海外仓接柜、入库与库内库存 | `modules/overseas-warehouse/`；先读 `../../docs/四期/README.md`，不得以 `src/prototype/` 作为业务实现 | 浏览器统一经 `gateway-overseas/`（RS256/JWKS，Audience=`lastleg-api`）；尾程订单、入仓计划、换标、产品/箱号快照和库存业务进入 `lastleg-service/`，海外仓库、地址、能力、库位、实物托盘和资源锁进入 `warehouse-overseas-service/`。原型读取 `03-overseas-warehouse.html`；不包含出库、派送及其他库存离仓能力 | +| 四期海外业务 | `modules/overseas-business/`；先读 `../../docs/四期/README.md` | 浏览器经 `gateway-overseas/` 进入 `lastleg-service/` 的 `procurement/`、`trucking/` 及本土散板稳定子域；不得接到国内 `gateway/`、`firstleg/` 或 `warehouse/`。原型读取 `07-overseas-business.html` | +| 四期仓库与通用资料扩展 | 海外仓合作仓类型进入 `modules/warehouses/`；海外仓报价、汇率和车辆进入 `modules/overseas-master-data/` | 国内 `warehouse/` 只维护“海外仓合作仓”公共主数据类型；实际海外仓、地址、能力、库位、托盘和资源锁进入 `warehouse-overseas-service/`，浏览器仍经 `gateway-overseas/`。报价、汇率和车辆的具体端点继续以海外服务 Controller/OpenAPI 为准；原型读取 `10-general.html` | | 四期国内出仓后船节点定时查询 | 现有 `CarrierScheduleQuery` 整体归此范围；入口为 `modules/port-schedules/`、`modules/ocean-bookings/` 及货柜详情，先读 `../../docs/四期/README.md` | `firstleg/portschedule/`、`integration-service/`；从确认离开国内仓库后查询，展示最新节点、来源、观测/更新时间和历史并衔接目的港提柜；不归三期或海外派送 | ## Admin 全量验收快速索引 @@ -91,6 +91,7 @@ - 供应商菜单、列表和详情固定只使用 `platform:supplier:list`，`platform:supplier:view` 必须停用/移除。修改 `modules/suppliers/`、`core/navigation/adminNavigation.ts` 或根路由时，不得恢复或兼容 `platform:supplier:view`。 - `core/navigation/adminNavigation.ts`、`app/router/index.ts` 和模块 `routes.ts` 属于共享装配文件；并行业务任务不得用局部模块结论覆盖菜单与权限总控已经确认的权限语义，发现重叠改动时保留并回传总控处理。 - 认证统一经过 `src/core/auth/auth.ts` 和 `src/shared/api/http.ts`；不要在页面中复制令牌读写或手工拼装 `Authorization`。 +- 四期海外浏览器请求必须使用统一认证/HTTP 层选择海外 API Base 和短时海外 Token，经 `gateway-overseas/` 发出；海外 Token 的 Audience 固定为 `lastleg-api`。业务页面不得直接复用国内 Base 绕到国内 `gateway/`，也不得把海外业务接口接到 `firstleg/` 或国内 `warehouse/`。 - 订舱代理、拖车承运商和报关代理必须提交服务端契约要求的供应商 ID，并从公共供应商列表选择 `ACTIVE` 且类别/范围匹配的记录；名称只作为展示或一致性提示，不得把名称输入当作 ID 的替代。修改这些请求参数时，必须同步检查 API 封装、类型、表单、详情展示、Mock/Fixture、契约测试和 Firstleg/Warehouse OpenAPI，不能只改页面或只改后端。 - 当前登录和部分数据仍可能是模拟实现。接入 `baiyue-firstleg` Gateway 真实接口时删除对应模拟路径，不允许让生产逻辑静默回退到假数据。 - 删除、停用、改权限等高风险操作必须有明确确认、处理中、成功和失败反馈；失败时保留用户上下文，避免误以为已生效。 diff --git a/src/modules/overseas-business/CONTRACT_GAPS.md b/src/modules/overseas-business/CONTRACT_GAPS.md index af81597e..19a3e9e7 100644 --- a/src/modules/overseas-business/CONTRACT_GAPS.md +++ b/src/modules/overseas-business/CONTRACT_GAPS.md @@ -1,14 +1,17 @@ # 海外业务待补契约 -当前仓库尚未提供海外区域 API Base、海外 Token 选择器或海外采购/本土运输正式端点。模块因此只冻结 TypeScript 请求/响应模型和页面结构，不创建临时 URL，不使用示例数据，也不模拟提交成功。 +后端服务边界已经确认：浏览器统一经 `gateway-overseas/`（Audience=`lastleg-api`）访问 `lastleg-service/`；海外采购进入 `procurement/`，本土卡车进入 `trucking/`，本土散板进入该服务的独立稳定子域。现有平台采购与美国卡车 Controller 是接口适配事实来源，不得将这些请求接到国内 `gateway/`、`firstleg/` 或 `warehouse/`。 + +模块当前仍只冻结 TypeScript 请求/响应模型和页面结构；在统一海外 Base/Token 选择与页面 DTO 适配完成前，不创建临时 URL，不使用示例数据，也不模拟提交成功。 后端接入前需冻结： -- 海外 Gateway Base 与统一认证层的海外 Token 选择方式； -- 采购订单、卡车订单、散板订单的列表、详情、创建与更新端点； +- 统一认证层对海外 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` 权限资源在海外服务端的鉴权落点。 -接入时应在统一双区域 HTTP/认证层完成 Base 与 Token 选择，业务页面不得自行读写 Token 或创建第二套登录。 +接入时应在统一双区域 HTTP/认证层完成 Base 与 Token 选择，业务页面不得自行读写 Token、创建第二套登录或绕回国内 Gateway。 diff --git a/src/modules/overseas-business/api/contracts.ts b/src/modules/overseas-business/api/contracts.ts index bdb479aa..4e00625c 100644 --- a/src/modules/overseas-business/api/contracts.ts +++ b/src/modules/overseas-business/api/contracts.ts @@ -13,8 +13,9 @@ import type { /** * 海外区域 API 的前端边界。 * - * 当前仓库尚未冻结海外 API Base、Token 选择和端点路径，因此这里只保存 - * 请求/响应形状，不创建 Axios 实例、不拼接临时 URL，也不提供模拟实现。 + * 服务边界固定为 gateway-overseas -> lastleg-service。当前统一海外 Base/Token + * 选择以及部分页面端点/DTO 尚未完成适配，因此这里只保存请求/响应形状， + * 不创建模块级 Axios 实例、不拼接临时 URL，也不提供模拟实现。 */ export interface OverseasBusinessApi { listPurchases(query: OverseasPurchaseQuery): Promise> diff --git a/src/modules/overseas-business/components/ContractPendingNotice.vue b/src/modules/overseas-business/components/ContractPendingNotice.vue index bb2132d3..5f9a21b7 100644 --- a/src/modules/overseas-business/components/ContractPendingNotice.vue +++ b/src/modules/overseas-business/components/ContractPendingNotice.vue @@ -5,7 +5,7 @@ withDefaults(defineProps<{ domain: string; compact?: boolean }>(), { compact: fa diff --git a/src/modules/overseas-master-data/CONTRACT_GAPS.md b/src/modules/overseas-master-data/CONTRACT_GAPS.md index 9ee8b3c3..b54d9e31 100644 --- a/src/modules/overseas-master-data/CONTRACT_GAPS.md +++ b/src/modules/overseas-master-data/CONTRACT_GAPS.md @@ -1,6 +1,8 @@ # 海外通用资料接口缺口 -当前仓库没有海外仓报价、汇率管理和车辆管理的已确认海外区域 API、请求/响应 DTO、错误码或写操作权限资源。 +海外浏览器请求的统一入口已确认为 `gateway-overseas/`（Audience=`lastleg-api`）。国内 `warehouse/` 只维护“海外仓合作仓”公共主数据类型；实际海外仓、地址、能力、库位、实物托盘和资源锁归 `warehouse-overseas-service/`。海外仓候选和仓储资源不得继续从国内 Warehouse API 读取。 + +当前仍缺少海外仓报价、汇率管理和车辆管理的已确认归属端点、请求/响应 DTO、错误码或写操作权限资源；统一海外 Base/Token 前端选择机制也尚未接入。 因此本模块当前只冻结正式路由、页面结构、字段、承载方式和只读权限，不包含内存示例数据或模拟成功： @@ -9,4 +11,3 @@ - 车辆列表/详情：`platform:overseas-master-data:vehicle:list` 新增、编辑、启停、删除、导出等写操作继续按动作使用独立权限，但编码与接口需等海外区域契约确认后再接入。列表权限只包含对应列表、详情和只读辅助数据访问。 - diff --git a/src/modules/overseas-master-data/components/ContractPendingNotice.vue b/src/modules/overseas-master-data/components/ContractPendingNotice.vue index 6ebba525..208fdf3a 100644 --- a/src/modules/overseas-master-data/components/ContractPendingNotice.vue +++ b/src/modules/overseas-master-data/components/ContractPendingNotice.vue @@ -5,11 +5,10 @@ withDefaults(defineProps<{ domain: string; detail?: boolean }>(), { detail: fals - diff --git a/src/modules/overseas-warehouse/CONTRACT_GAPS.md b/src/modules/overseas-warehouse/CONTRACT_GAPS.md index 1be95484..cbfc56d0 100644 --- a/src/modules/overseas-warehouse/CONTRACT_GAPS.md +++ b/src/modules/overseas-warehouse/CONTRACT_GAPS.md @@ -1,8 +1,10 @@ # 四期海外仓前端待补契约 -第一批正式页面只冻结路由、权限、字段与操作承载方式。以下后端/基础设施契约缺失前，页面不得用演示数据或本地成功提示替代真实调用： +第一批正式页面只冻结路由、权限、字段与操作承载方式。后端服务边界现已确认：浏览器请求统一进入 `gateway-overseas/`（RS256/JWKS，Audience=`lastleg-api`）；尾程订单、入仓计划、换标、产品/箱号快照和库存业务归 `lastleg-service/`；海外仓库、地址、能力、库位、实物托盘和资源锁归 `warehouse-overseas-service/`。国内 `warehouse/` 只维护“海外仓合作仓”公共主数据类型。 -- 海外区域 API Base、海外 Access Token 的存储/刷新/选择机制，以及与现有国内 `http` 客户端的统一错误处理。 +以下前端适配或页面级契约补齐前，页面不得用演示数据或本地成功提示替代真实调用： + +- 统一认证/HTTP 层对海外 API Base、短时海外 Access Token 的存储、刷新和自动选择，以及与现有国内 `http` 客户端一致的错误处理；业务页面不得自行读写 Token，也不得把请求发往国内 `gateway/`、`firstleg/` 或 `warehouse/`。 - 尾程订单分页查询、详情、导入模板、批量导入、异步导出、批量转仓和入库计划接口；分页查询需明确“全部 / 待分配”页签的请求映射，以及出库单号、派送单号只读关联字段。 - 入库单分页查询、详情、创建、编辑、预约、智能排车接口，以及状态机、幂等键和操作权限。 - 库存汇总、分页查询、详情、库位库存、托盘箱号和进销存记录接口。 @@ -15,4 +17,4 @@ 范围排除：海外仓出库、退货出库、海外派送和其他库存离仓接口。 -当前 `types.ts` 只冻结原型派生的页面展示字段，不是海外 API DTO；不得据此推导分页包络、URL、请求参数、时间/金额精度或写接口。待上述契约冻结后再建立实际 API 适配层，并逐页替换空态数据源。 +`lastleg-service` 已提供尾程订单、入仓计划、库存查询等 Controller，`warehouse-overseas-service` 已提供平台海外仓、库位和托盘 Controller；接入时以这些服务的 Controller/DTO/OpenAPI 为准。当前 `types.ts` 只冻结原型派生的页面展示字段，不是海外 API DTO；不得据此推导未覆盖页面的分页包络、URL、请求参数、时间/金额精度或写接口。统一区域客户端和对应页面契约完成后再建立实际 API 适配层，并逐页替换空态数据源。 diff --git a/src/modules/overseas-warehouse/components/ContractPendingNotice.vue b/src/modules/overseas-warehouse/components/ContractPendingNotice.vue index 4da1c798..b42eb653 100644 --- a/src/modules/overseas-warehouse/components/ContractPendingNotice.vue +++ b/src/modules/overseas-warehouse/components/ContractPendingNotice.vue @@ -5,7 +5,7 @@ defineProps<{ domain: string }>()