# 后端联调 · 前端实现说明

> 适用范围：`有职`（youzhi）App 前端对接《职来后端接口联调说明》（`job.youthome.com.cn` 规范）
> 关联文件：`src/api/http.ts`、`src/api/auth.ts`、`src/lib/token-store.ts`、`src/context/AuthContext.tsx`、`src/types/user.ts`
> 本文只记录**前端已落地的地基与契约映射**，完整接口字段以运行时 OpenAPI 为唯一依据（规范 §7）。

## 一、本次已落地（地基，不涉及业务端点）

| 层 | 文件 | 内容 |
|---|---|---|
| 请求层 | `src/api/http.ts` | 统一出口：`Base URL` + `Bearer` 注入 + 信封解析 + **401 单飞刷新** + `X-Request-Id` + 状态码语义 |
| 令牌 | `src/lib/token-store.ts` | `accessToken` + `refreshToken` 内存单例 + AsyncStorage 持久化 |
| 鉴权 | `src/api/auth.ts` | `sendSmsCode` / `loginByPassword` / `loginBySms` / `fetchCurrentUser` / `requestLogout` / `registerCompany` |
| 会话 | `src/context/AuthContext.tsx` | `setSession(access,refresh,expiresAt)`；启动时 `hydrateTokens`；注册 401 清会话回调 |
| 角色 | `src/types/user.ts` + `auth.ts` | `AppRole` 扩 `admin`；`mapBackendRole(STUDENT→candidate / COMPANY→enterprise / ADMIN→admin)` |
| 环境 | `app.config.js` | 默认 `apiBaseUrl = https://job.youthome.com.cn/api/v1`（保留 `API_BASE_URL` 环境变量覆盖） |

业务端点（`jobs` / `profile` / `messages` 等 100+ mock 函数）**仍走 mock**，按 AGENTS.md 约定后续逐个替换为真实 `request()` 调用即可，页面与 hook 零改动。

## 二、规范条款逐条对照

| 规范 | 前端现状 |
|---|---|
| §1 基地址 / 健康检查 / OpenAPI | 基地址已接 `API_BASE_URL`；`checkHealth()` 已实现对 `/health`（UP 判定）；OpenAPI 为后端准绳，前端不手抄 |
| §3 信封 `code/message/data/requestId/timestamp` | `request()` 解析 envelope；`code!==200` 抛 `ApiError`；后端 `message` 优先（更具体），无 message 时回退状态码文案 |
| §3 `Authorization: Bearer` | 自动注入；匿名接口（登录/短信/刷新）显式 `auth:false` 不带头 |
| §4 双 Token + `/auth/refresh` | `token-store` 持久化 `access+refresh`；401 触发刷新 |
| §4 一次串行刷新 + 重放 | 模块级 `refreshPromise` 单飞闸门：并发 401 只刷一次，成功后重放原请求 |
| §4 刷新失败清会话 | 清 Token + `unauthorizedHandler`（AuthContext 注册为清登录态） |
| §4 Token 不打印/上报/进 URL | 令牌仅在 `http.ts` 内层使用，错误对象不回吐原始 Token |
| §5 角色以后端 `/auth/me` 为准 | `fetchCurrentUser()` 返回映射后角色；密码登录页（`P2PasswordLogin`）登录后调 `/auth/me` 并 `setRole`，与本地选择不一致时纠正路由 |
| §6 企业注册 | `registerCompany()` 已实现对 `/auth/company/register`；客户端不提交 `userId/role/verified/passwordHash` |
| §8 状态码语义 | `pickHttpMessage` 覆盖 400/401/403/404/409/429/500/503；网络异常降级为 `httpStatus=0` |
| §10 安全 | 不写 Token/验证码/密码到日志或前端 DOM；`X-Request-Id` 用于联调报障 |

## 三、明确未做（下一阶段）

- **业务端点转真实**：`jobs`、`profile/me`、`companies/me/onboarding` 等仍 mock，需按 OpenAPI 逐个换 `request()`。
- **WebSocket**：`wss://job.youthome.com.cn/api/v1/ws` 未接入（无对应实时功能）。
- **企业入驻状态机**：`/companies/me/onboarding` 的 `missingFields` / `allowedActions` 驱动 UI 尚未接。
- **其余入口页角色纠正**：仅密码登录页已接 `/auth/me`；微信登录、验证码登录等入口需在登录后补齐角色权威化。

## 四、命名待确认（非阻塞）

- 域名 `youthome.com.cn`（青年家）与 App 品牌「有职 / youzhi」不一致；Storage 前缀仍为历史遗留 `qingsongpin:`，**勿擅自改名**（会导致老用户本地态失效）。