# Admin Shared API Instructions

## 适用范围与入口

- 本文件适用于 `src/shared/api/` 及其测试。业务模块只通过领域 `api/` 适配层调用这里的客户端，不在页面和组件直接创建 Axios 实例。
- 国内 API 客户端为 `http.ts`；海外 API 客户端为 `overseasHttp.ts`。认证会话编排在 `../../core/auth/auth.ts`，不得在本目录复制登录状态。

## 国内与海外请求

- `http` 使用 `VITE_API_BASE_URL`，默认走国内代理；国内登录、刷新和退出仍由统一 Auth 处理。
- `overseasHttp` 使用 `VITE_OVERSEAS_API_BASE_URL`，默认 `/overseas-api`；Vite 将该前缀改写为海外 Gateway 的 `/api`。代理上游由开发环境配置，不在源码或指引中记录真实地址。
- 登录和刷新响应一次性返回国内 Token、`overseasAccessToken`、`overseasExpiresIn`；`core/auth/auth.ts` 必须原子替换两套访问凭据。不得恢复 Token 兑换端点或让业务模块单独刷新海外 Token。
- 海外 Token 只由 `replaceOverseasAccessToken`、`clearOverseasAccessToken` 管理；业务模块不得读写缓存、LocalStorage 或手工拼装 `Authorization`。
- 国内、海外 401 共用统一会话刷新编排。海外请求最多统一刷新一次并重放一次；刷新失败按会话失效处理，不循环重试或回退假数据。

## 领域调用边界

- 国内业务领域 API 使用 `http`；四期海外尾程、海外仓资源和海外本土业务使用 `overseasHttp`，不得经国内 Gateway 中转。
- 页面只调用所属模块的 API 封装；模块 API 负责路径、DTO 和错误适配，不把 Axios 响应或区域选择泄漏到页面。
- 跨区域 Token、Audience、JWKS 和服务通信公共契约读取 `../../../../../docs/跨区域认证与服务通信契约.md`。

## 修改与验证

- 修改客户端、拦截器、刷新、Token 生命周期或 Base URL 时，联查 `http.test.ts`、`overseasHttp.test.ts`、`core/auth/auth.test.ts`、Vite 代理、`.env.example` 和全部实际消费者。
- 至少运行相关 API/Auth 测试和 `pnpm typecheck`；交付前按项目指引运行完整测试与构建。