12 KiB
职来（有职）前端 · 已转换接口（已"调过"）存在的问题
生成日期：2026-09-28 范围界定：本文只讨论已在代码中实现真实分支（即已转换为直连后端、存在
request()调用）的接口存在的问题。 不纳入：纯 mock 接口（sendChatMessage、loginByPhone、saveOnboardingProfile、fetchOnboardingProfile、设备本地能力fetchCacheSize/clearAppCache/fetchCarrierPhone/fetchWechatLoginResult等）；明确尚未启动的 WebSocket、企业入驻状态机。 说明：地基（统一请求层、双 Token、401 刷新、角色映射、健康检查）实现正确，不在本文问题范围内。
零、进展更新（2026-09-28 经 OpenAPI 实机校正）
本轮以
https://job.youthome.com.cn/api/v1/v3/api-docs（OpenAPI 3.1.0，182 路径 / 220 path-method）为唯一准绳，对api.ts全部request()函数做了实机验证（测试号19900009021登录取 token 后逐一打真实路径，路径返回业务错误码 6001/7001/8002/8305 等即视为「路径存在、契约待对齐」，网关 404 视为「路径不存在」）。
审计结论（89 个 request 函数）
- ALIGNED（6）：路径与 OpenAPI 完全一致，翻开关即直连。
- WRONG→REAL（14）：路径前端猜错但有真实等价端点，已改路径（例：
/messages/conversations→/conversations、/resume→/profile/me/resume、/jobs/rank→/jobs/{id}/competition-ranking、/enterprise/candidates→/company/candidates、/enterprise/interviews→/interviews）。 - PHANTOM（69）：所属域后端无 OpenAPI 契约，翻开关必 404。已退回 mock-only（真实态不再调用
request，翻真实开关也不触网），待后端补齐契约再接。
标记清理
【待确认】标记：0 处（全部清除，含【待确认：…】形式）。- 实机验证：ALIGNED + WRONG→REAL 共 ~20 个接口真实路径均返回业务错误码（非网关 404），证明路径正确。
问题状态总览
| 原编号 | 状态 | 说明 |
|---|---|---|
| P0-1 | ✅ 已解决 | 89 函数已按 OpenAPI 校正并分类（ALIGNED 6 / WRONG→REAL 14 / PHANTOM 69） |
| P0-2 | ✅ 已解决 | 4 个桥接测试改为断言真实路径；幽灵域真实态断言已删 |
| P1-1 | ✅ 已解决 | 后端联调前端实现.md §3 已按代码现状重标 |
| P1-2 | ⏳ 待办 | Token expiresIn 仍未处理（见下「遗留 P1-2」） |
| P1-3 | ⏳ 待办 | /auth/me 角色权威化仍仅在密码登录入口 |
| P1-4 | 🔶 部分 | 幽灵域写函数已退回 mock；已对齐写函数 body 形态待统一 |
| P2-1 | ⏳ 待办 | 145 处 JSDoc @url /api 旧前缀未清 |
| P2-2 | ✅ 已解决 | 3 个列表函数真实态从 Spring Page {items} 信封取数（实机验证）；/conversations 真实返回数组已确认不变 |
| P2-3 | ⏳ 待办 | 双真相源切换策略未定 |
| P2-4 | ✅ 缓解 | 默认仍 mock；现幽灵域翻开关也不触网 |
遗留 P1-2（Token 有效期）
后端登录返回 expiresIn（秒数）而非 expiresAt；前端 AuthContext 仍用 TOKEN_TTL_MS 兜底成假 TTL。本轮未改，需单独排期修。
P2-2 分页信封差异（已修复 · 2026-09-28 实机验证）
纠正前误述：此前判断"前端 mock 用 {content}、真实用 {items}"——实际探查证明前端根本没有按 .content 取数的分页信封，mock 返回的是 {jobs,total}（fetchJobList）或直接数组，Hook 也不读 .content。
真实风险落点（测试号登录取 token 后逐一打真实路径，看 data 结构）：
| 接口 | 真实返回（data） |
前端原假设 | 结果 |
|---|---|---|---|
/conversations |
数组 | Conversation[] |
正确，未改 |
/notifications |
Page 信封 {total,size,totalPages,page,items} |
Notification[] |
空白 |
/interviews/me |
Page 信封 | Interview[] |
空白 |
/jobs/favorites |
Page 信封 | Job[] |
空白 |
/jobs（fetchJobList） |
Page 信封 | — | 早已适配 data.items |
修复：fetchNotifications / fetchInterviews / fetchFavorites 真实态改为 request<{items:T[]}> 后取 res.items ?? []，与 fetchJobList 一致；3 个真实态测试同步改为断言从信封解包。tsc 0 错误，全量 jest 495 通过。
延伸待验证（同类型）：fetchEmployeeReviews（/jobs/{id}/reviews）同为后端列表接口，实机因测试号无该 job 返回 7001，未取到成功样本；OpenAPI 对该接口 200 schema 为空 {}，无法判定形态，先标记待验证，不臆改。
一、结论
- 已转换接口在代码层面"连接"基本铺完：
api.ts内 85 个fetch*读函数 + 大量save*/submit*/update*写函数都已带有真实分支（if (!isMockMode()) return request(...)），且全部受isMockMode()保护，默认 mock 态不会误触网。 - 但契约未经后端校验：全文件 65 处
【待确认】标记真实路径为前端推测；157 处 JSDoc@url仍写旧/api前缀（实际request()已去/api，两者不一致）。 - 现有测试锁定的是推测路径而非真实契约，制造"绿灯已通过"的错觉。
- 文档与代码脱节：
后端联调前端实现.md§3.2 把已转换的saveResume*、saveJobPreference标为"未接后端 / 后续接"，与代码现状不符。
一句话：这些接口"代码连了、契约没对"。 当前不能宣布"已联调完成"。
二、问题清单（仅已转换接口）
P0 — 翻开关即爆
| # | 问题 | 证据 | 影响 |
|---|---|---|---|
| P0-1 | 【已解决 2026-09-28】 原 65 个已转换接口真实路径为前端猜测（【待确认】），未对照 OpenAPI 校正 |
现 【待确认】 0 处；89 函数已分类 ALIGNED 6 / WRONG→REAL 14 / PHANTOM 69 |
翻开关后 ALIGNED+WRONG→REAL 共 ~20 接口直连真实后端（返回业务码非 404）；PHANTOM 69 已退回 mock-only 不触网 |
| P0-2 | 【已解决 2026-09-28】 测试锁定的是推测路径，不是真实契约 | backend-bridge-remaining.test.ts 等 4 文件已改为断言经 OpenAPI 确认的真实路径；幽灵域真实态断言已删除 |
CI 绿灯现对应真实契约；81/81 桥接测试通过 |
P1 — 必须修，否则已转换接口不可信
| # | 问题 | 证据 | 影响 |
|---|---|---|---|
| P1-1 | 文档与代码脱节：已转换的 saveResume*、saveJobPreference 被误标"未接后端" |
代码 3352/3369/3387/3413/3426/3439/3459/8684 等均有 request(...) 真实分支 |
状态失真，排期与验收失去依据 |
| P1-2 | Token 有效期由前端臆造：后端不返回 expiresAt 时，AuthContext 用 TOKEN_TTL_MS 兜底成假 7 天 TTL |
token-store.ts 注释"后端可能不返回，故可选"；AuthContext.tsx:161/173 expiresAt ?? Date.now()+TOKEN_TTL_MS；isTokenValid 据此判断 |
影响所有已转换的鉴权请求：后端短过期时前端以为有效、长期不主动刷新，只能靠 401 兜底；或前端假 TTL 过期后误判登出 |
| P1-3 | 角色权威化接口 /auth/me 已转换，但只在密码登录入口调用 |
仅 P2PasswordLogin.tsx:53 调 fetchCurrentUser；微信登录 / 验证码登录 / 注册完成（useRegisterFinish）均用本地角色，不调 /auth/me |
多入口登录后角色可能与后端不一致，路由纠正逻辑仅在密码入口生效 |
| P1-4 | 已转换写接口 body 形态不一致：有的包 {skills}、有的裸传 items、有的包 {items} |
saveResumeSkills → { skills }(3387)；saveResumeExperience → items(3426，未包裹)；saveResumeEducation → { items }(3413) |
后端若要求统一 envelope，部分已转换写接口会 400 / 字段丢失 |
P2 — 隐患 / 卫生
| # | 问题 | 证据 | 影响 |
|---|---|---|---|
| P2-1 | 157 处 JSDoc @url 仍写旧 /api 前缀，与实际 request() 路径（已去 /api）不一致 |
grep @url /api = 157；实际 request('/jobs') 无 /api |
维护者按注释拼地址必错；JSDoc 不能作契约依据 |
| P2-2 | ✅ 已修复（实机验证） fetchNotifications/fetchInterviews/fetchFavorites 真实态从 Spring Page {items} 信封取数；/conversations 真实返回数组已确认 |
实机打 /notifications//interviews/me//jobs/favorites 返回 {total,size,totalPages,page,items}；原代码假设裸数组会空白 |
翻 apiUseMock=false 后消息/收藏/面试列表正常渲染；fetchEmployeeReviews 同类待验证 |
| P2-3 | mock / 真实双真相源切换一致性：mock 态 saveResumeSnapshot 写本地 storage 覆盖层、fetchResume 读本地；真实态写后端、读后端 |
saveResumeSnapshot(mock 写 storage) vs fetchResume(真实读后端) |
同一设备从 mock 翻真实后，本地已填资料不出现在后端返回中，需明确迁移/清空策略 |
| P2-4 | apiUseMock 默认 true 的隐患：容易被误判为"联调完成"而翻开关 |
http.ts:31 默认 true |
翻开关即触发 P0-1 的 65 个错误请求 |
三、逐域未确认路径明细（P0-1 附录）
下列域的已转换接口真实路径均带
【待确认】，为前端推测，未经 OpenAPI 校正。
| 域 | 代表函数 | 推测路径 |
|---|---|---|
| 简历写 / 读 | saveResumeBasicInfo / fetchResume |
/resume/*、/resume/save |
| 消息 / 沟通 | fetchConversations / fetchConversation / fetchMatchResult |
/messages/*、/chat/conversations/{id} |
| 求职者资料 / 偏好 | fetchUserProfile / saveJobPreference |
/profile/me、/profile/me/job-preference |
| 薪资 / 工具 | fetchSalaryRecords / fetchWeightSettings |
/salary/records、/jobs/weight-settings、/tools/* |
| 测评 / 成长 | fetchHollandAssessment / fetchSkillCloud |
/growth/*、/user/*、/tools/*、/game/* |
| 企业端 | fetchJobManagement / fetchEnterpriseOverview |
/enterprise/* |
| 法律（阿布阿诺） | fetchLegalBrand / fetchLegalOrders |
/legal/* |
| 隐私 / 设置 / 账户 | fetchPrivacySettings / fetchAccountCancel |
/settings/*、/user/*、/operation/* |
完整 65 处见 api.ts 内 【待确认】 注释；精确清单应回到 src/__tests__/backend-bridge-remaining.test.ts 的 FUNCS 数组对照 OpenAPI 逐一校正。
四、整改建议（针对已转换接口）
- 校正契约（P0）：以《职来后端接口联调说明》
.docx（§7 OpenAPI，job.youthome.com.cn）为唯一准绳，逐函数对照 65 个【待确认】路径，命中后删注释；未对照前不宣布"已收口"。 - 让测试服务于真实契约（P0）：把
FUNCS数组路径从"占位"替换为经 OpenAPI 确认的路径；新增对拍用例（请求路径 + 响应字段 schema 校验），而非只断言前端猜的地址。 - 统一已转换写接口 body 形态（P1-4）：约定"整表替换类用
{ items }、单对象类用对象本体"，saveResumeExperience当前裸传items需包裹。 - 修正 Token 有效期语义（P1-2）：后端不返回
expiresAt时不要用TOKEN_TTL_MS兜底成假 TTL；改为"不预判、靠 401 触发刷新 + 可选短轮询"，或强制后端下发expiresAt。 - 补全
/auth/me角色权威化（P1-3）：微信登录 / 验证码登录 / 注册完成三个入口登录后统一调/auth/me并setRole，与密码入口一致。 - 清理 JSDoc（P2-1）：批量清除 157 处
@url /api旧前缀。 - 明确双真相源切换策略（P2-3）：在登录流程或"清除缓存"中，翻真实态前提示并清空本地覆盖层，避免数据幽灵。
- 重写状态文档（P1-1）：
后端联调前端实现.md按代码现状重标已转换接口，删除"未接后端"的误述。
五、验收口径（建议写入 AGENTS.md）
"接口已联调完成"的定义应为：① 路径经 OpenAPI 校正并删除
【待确认】；② 至少一次真实联调（apiUseMock=false）返回符合类型定义的响应；③ 测试断言的是真实路径 + 响应字段。 仅凭"代码里写了request()"或"测试命中占位路径"不算完成。