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 环境变量覆盖）
mock 开关	app.config.js + http.ts	extra.apiUseMock（默认 true）；isMockMode() 决定业务函数走 mock 还是真实请求；联调期置 false

业务端点按 mock 开关 分阶段落地：开发期（apiUseMock=true）返回本地数据不触网，联调期（false）直连后端。jobs / profile / messages 等 100+ mock 函数逐个替换为真实 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 用于联调报障

三、业务端点转换进度（mock 开关 + 全量 fetch 函数，2026-09-24 收口）

转换规则：保留函数签名与返回类型 T（即 AGENTS.md「保留签名、只换函数体」），if (isMockMode()) 分支保留本地数据，真实分支走 request<T>(path, { auth, query })。路径按规范 §7 重映射（旧 @url 多带 /api 前缀、未带 /v1，已校正）。

3.1 已落地真实端点（2026-09-28 经 OpenAPI 校正）

路径以 docs/联调路径校正映射.md 为权威逐函数表；下表仅列本次确认可直连的端点（ALIGNED + WRONG→REAL）。

函数	真实路径	鉴权	说明
fetchJobList	GET /jobs	否	分页信封 {items}
fetchJobDetail	GET /jobs/{id}	否	公开岗位详情
fetchJobPreference	GET /profile/me/preferences	是	原 /profile/me/job-preference 已校正
fetchFavorites	GET /jobs/favorites	是	原 /profile/me/favorites 已校正
fetchJobProgress	GET /profile/me/career-progress	否	原 /tools/job-progress 已校正
fetchEmployeeReviews	GET /jobs/{id}/reviews	否
createJobReview	POST /jobs/{id}/reviews	是	body {content}
fetchCompareData	GET /jobs/compare	否
fetchUserProfile	GET /profile/me	是
fetchResume	GET /profile/me/resume	是	原 /resume 已校正（修复双前缀 bug）
fetchConversations	GET /conversations	是	原 /messages/conversations 已校正
fetchNotifications	GET /notifications	是	原 /messages/notifications 已校正
fetchInterviews	GET /interviews/me	是	原 /messages/interviews 已校正
fetchConversation	GET /conversations/{id}	是	原 /chat/conversations/{id} 已校正
fetchRankData	GET /jobs/{jobId}/competition-ranking	否	原 /jobs/rank 已校正（修复 ${jobId} 未插值 bug）
fetchCandidateDetail	GET /company/candidates/{applicationId}	是	原 /enterprise/candidates 已校正
fetchInterviewScore	GET /interviews/{id}/score	是	原 /enterprise/interviews 已校正
fetchInterviewScoreDraft	PUT /interviews/{id}/score	是	草稿复用评分端点，原 /enterprise/.../draft 已校正
fetchOfferCompareData	GET /offers/compare	否	已对齐

写函数 saveJobPreference（PUT /profile/me/preferences）已校正路径；其余 saveResume* / saveWeightSettings / saveSalaryRecord 等经审计属「幽灵域」（后端无 OpenAPI 契约），已退回 mock-only。

3.1.2 幽灵域（本轮批量转换的其余 62 个 fetch 函数，2026-09-28 校正）

经 OpenAPI 审计，这 62 个函数所属域（/growth、/user、/tools、/game、/interview、/evaluation、/enterprise、/legal、/settings、/salary、/operation 等）后端均无契约。处理方式：保留 if(isMockMode()) mock 分支，真实态不再调用 request()（翻真实开关也不触网），待后端补齐契约后再接。原占位 【待确认】 标记已全部清除。逐函数明细见 docs/联调路径校正映射.md §三。

3.2 待转 / 明确不接后端

• 设备本地能力（保持 mock，无后端等价物）：fetchCacheSize（存储占用）、fetchCarrierPhone（运营商取号 SDK）、fetchWechatLoginResult（微信登录态）、fetchOnboardingProfile（本地引导资料唯一真相源）、fetchOnboardingChecklist（本地清单派生）、fetchDeleteAllData（本地清空）。
• 非 fetch 写函数（不在本次 fetch 范围，后续接）：sendChatMessage、saveResume* 系列、saveOnboardingProfile、toggleFavorite、saveJobPreference 等写操作——需 PUT/POST body 映射 + 保留本地 storage 回退作为真实后端未就绪时的兜底。

四、明确未做（写入类 + 实时能力，下一阶段）

• WebSocket：wss://job.youthome.com.cn/api/v1/ws 未接入（无对应实时功能）。
• 企业入驻状态机：/companies/me/onboarding 的 missingFields / allowedActions 驱动 UI 尚未接。
• 其余入口页角色纠正：仅密码登录页已接 /auth/me；微信登录、验证码登录等入口需在登录后补齐角色权威化。
• 写入类函数：见 §3.2 非 fetch 写函数（sendChatMessage / saveResume* / saveOnboardingProfile / toggleFavorite / saveJobPreference 等），需补 body 映射与本地 storage 兜底。

五、命名待确认（非阻塞）

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