优化

AGENTS.md

@@ -3,7 +3,7 @@
 ## 项目定位
 
 - 本项目是入驻企业及其成员使用的客户工作台，所有业务数据都处于企业租户上下文中。
-- 当前范围包括注册、业务总览、企业资料、企业成员、企业角色与权限、头程订单，以及客户财务账单查询与客户确认。
+- 当前范围包括注册、业务总览、企业资料、企业成员、企业角色与权限、头程订单、客户财务账单查询与客户确认，以及海外仓贴标、转运、废弃和退货换标自助服务。
 - 用户可见的“平台—客户”层级语义读取 `../../docs/平台客户层级与权限契约.md`；涉及海外 API、海外 Token 或跨区域事件时读取 `../../docs/跨区域认证与服务通信契约.md`。本文件中的 `tenant` 仅表示服务端隔离上下文，不扩展用户可见产品层级。
 - 不在本项目实现平台内部运营管理、品牌官网、仓库 PDA 作业或仅属于原生移动端的能力。
 
@@ -26,7 +26,7 @@
 - 模块内 `store/`：该业务跨页面状态；局部表单状态仍留在页面或组件内。跨模块使用 store 时只能导入其公开 store 文件，不得读取模块内部页面或组件实现。
 - `src/api/`：只保留 HTTP、会话令牌、响应类型等全局请求基础设施；业务接口放入对应模块的 `api/`。页面不得直接创建独立 Axios 客户端。
 - 模块之间不得通过相对路径或内部目录穿透；确需协作时只能从目标模块的 `public.ts` 导入。模块内稳定契约放在 `contracts.ts`，稳定的跨应用模型仍应上移到 `@chongchong/shared`。
-- `VITE_API_BASE_URL` 控制浏览器请求前缀，`API_PROXY_TARGET` 控制 Vite 开发代理上游；后者只由开发服务器读取，不进入客户端构建。新增或变更环境变量时同步更新 `.env.example`，不得提交真实密钥或环境专属凭据。
+- `VITE_API_BASE_URL`、`VITE_OVERSEAS_API_BASE_URL` 分别控制国内和海外浏览器前缀；`API_PROXY_TARGET`、`OVERSEAS_API_PROXY_TARGET` 只由 Vite 开发代理读取，不进入客户端构建。新增或变更环境变量时同步更新 `.env.example`，不得提交真实密钥或环境专属凭据。
 - `src/styles/`：全局设计令牌和布局；优先复用现有 `--primary`、`--navy`、`--border`、`--muted`。
 - 本应用多个模块稳定复用的前端模型放到应用内 `shared/`，客户工作台专属类型保留在对应业务模块。不要链接应用目录之外的 TypeScript 包，服务端契约以 `baiyue-firstleg` Controller/OpenAPI 为准。
 
@@ -50,13 +50,14 @@
 | 头程下单、订单、箱唛与履约进度 | `src/modules/first-leg/`；箱唛下载消费者从 `views/FirstLegOrdersView.vue`、`api/firstLeg.ts` 进入 | Backend `order/`、`firstleg/`、`warehouse/`；稳定箱码与打印契约先读 Backend `firstleg/AGENTS.md` |
 | 统一订单展示 | `src/modules/order-management/` | `src/modules/first-leg/` 与对应后端订单契约 |
 | 客户财务账单、收款、未收余额与客户确认 | `src/modules/finance/`；确认入口 `views/FinanceBillsView.vue`、`api/finance.ts` | Backend `finance/`；只能查看登录态客户的已出账账单。出账或已出账调整后为 `PENDING_CONFIRMATION`，客户确认以登录成员、`expectedVersion` 和幂等键提交，成功后记录确认人姓名快照与时间 |
-| 跨境与海外仓候选能力 | `src/modules/cross-border/`、`src/modules/overseas-warehouse/` | 先核对各自 `routes.ts` 的发布状态与阶段范围，不自动扩展实现 |
+| 跨境候选能力 | `src/modules/cross-border/` | 先核对 `routes.ts` 的发布状态与阶段范围，不自动扩展实现 |
+| 海外仓贴标、仓储转运、货物废弃、退货换标 | `src/modules/overseas-warehouse/routes.ts`、`views/WarehouseServiceView.vue`、`api/warehouseServices.ts` | 四个路由均为 `active`；Backend `lastleg-service/` 的 `relabel/`、`transfer/`、`discard/`，请求统一经 `src/api/overseasHttp.ts` 与 `gateway-overseas/` |
 
 ## 租户、认证与数据安全
 
 - 任何查询和变更都必须以服务端确认的当前租户为边界；绝不从可篡改的前端参数推断授权租户。
 - 企业成员、角色和权限只能管理当前企业范围。前端隐藏不是安全控制，服务端必须重复校验租户与权限。
-- 认证统一经过 `src/modules/auth/store/auth.ts` 和 `src/api/http.ts`；不要在页面中复制令牌逻辑或持久化密码、敏感资质内容。
+- 认证统一经过 `src/modules/auth/store/auth.ts`、`src/api/http.ts`、`src/api/session.ts`；国内请求使用国内 Access Token，海外请求统一由 `src/api/overseasHttp.ts` 读取短时海外 Token。海外 Token 缺失或 401 时复用同一刷新编排并最多重放一次，页面不要复制令牌逻辑或持久化密码、敏感资质内容。
 - 当前认证仍包含模拟数据。接入真实 API 后移除对应模拟分支，生产环境不得回退为模拟成功。
 - 注册、上传资质、成员邀请和订单操作必须提供明确校验、幂等保护、提交中状态和可恢复的失败反馈。
 
@@ -104,6 +105,6 @@ pnpm build
 | 验收域 | Client 范围与代码入口 | 验收首读 |
 |---|---|---|---|
 | 客户基础与订单 | 登录/注册、企业资料与资质、成员/角色权限、工作台和订单 | `src/modules/auth/`、`tenant-management/`、`account/`、`system/`、`dashboard/`、`first-leg/`、`order-management/`；按客户可见契约核对权限、状态、幂等和错误处理 |
-| 履约与财务 | 入库计费、柜次进度、船期、消息和客户账单 | `src/modules/first-leg/`、`finance/`、`notifications/`；按服务端权限核对客户可见字段和只读/写入边界 |
+| 履约、海外仓与财务 | 入库计费、柜次进度、船期、海外仓贴标/转运/废弃/退货换标、消息和客户账单 | `src/modules/first-leg/`、`overseas-warehouse/`、`finance/`、`notifications/`；按服务端权限核对客户可见字段、客户隔离和只读/写入边界 |
 
 客户侧边界：仍以服务端权限和客户可见字段为准；PDA、平台后台操作和内部证据不因全量验收自动暴露到 Client。财务按 `../../docs/财务管理/` 与 `src/modules/finance/routes.ts` 定位。