admin-web/src/shared/api/AGENTS.md

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；交付前按项目指引运行完整测试与构建。