mydreamjob/后端联调前端实现.md

后端联调 · 前端实现说明

适用范围：有职（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:，勿擅自改名（会导致老用户本地态失效）。