9.9 KiB
职来（有职）前端 × 后端 联调问题清单（致后端同事）
生成时间：2026-09-30 前端仓库：
mydreamjob（React Native + Expo，包管理器 yarn） 后端基址：https://job.youthome.com.cn/api/v1文档口径：以《职来后端接口.md》（248 个端点）为准。scripts/openapi.json已过期（仅 220 个，缺/auth/identity/select等 28 个），后续请以 md 为准。 产生方式：① 覆盖审计（scripts/audit_coverage.py：md 端点 ↔ 前端request()双向比对）；② 实网探测（scripts/live_probe.py：真实学生账号登录后批量 GET）。
0. 结论速览
| 指标 | 数值 |
|---|---|
| 后端端点总数 | 248 |
| 前端已接入 | 80 |
| 前端未接入 | 168 |
| 前端「幽灵调用」（调了后端不存在的端点） | 0（本次已全部修正） |
| 实网可探测 GET 端点 | 142（另有 42 个因缺路径 id 未探测） |
| 实网探测 正常 / 异常 | 50 / 50 |
需后端配合的事项分三类：① 契约确认（第 1 节）② 端点缺失需补齐（第 2 节）③ 异常端点需关注（第 3 节）；测试账号问题见第 4 节；前端已自行修掉的问题见第 5 节。
1. 需要后端确认的接口契约
| # | 项目 | 前端现状（已按此实现） | 需后端确认 |
|---|---|---|---|
| 1 | 分页基准 | 按 0-based 传 page（Spring Data 默认），列表首页 page=0 |
全站是否统一 0-based？若个别端点从 1 开始，请指出 |
| 2 | 统一响应包 | 按 {code,message,data,requestId,timestamp}，code=0 成功（HTTP 200），失败读 message |
成功码是否恒为 0？requestId 是否用于排障回溯 |
| 3 | 鉴权 | Authorization: Bearer <accessToken>；401 时用 refreshToken 静默换新（双 Token） |
刷新端点与失效口径；刷新失败是否也返回 401 |
| 4 | 401 / 403 语义 | 401=未登录或 Token 失效；403=角色无权限 | 确认区分稳定（实网 403 返回 code=2002） |
| 5 | 错误码清单 | 已观测：2002=forbidden、6001=profile not found |
请提供完整业务错误码表（前端要按码做差异化提示，不能只靠文案） |
| 6 | 角色模型 | STUDENT / COMPANY / ADMIN；/companies/me/*、/company/*、/admin/* 对 STUDENT 一律 403 |
企业端角色是否单一 COMPANY？有无子角色 |
| 7 | 岗位状态枚举 | 前端把后端 status 映射为中文（如「招聘中」） |
请给 status 全量取值集合 |
| 8 | 求职偏好字段缺口 | 后端下发多值数组 + 英文 token（preferredJobTypes[]、employmentTypes:['FULL_TIME']），前端取首项并译中文 |
后端未下发「期望薪资」「求职状态」，前端只能显示「未设置」。是否补字段？ |
| 9 | 测评（assessment） | 按「答卷(attempt)」模型桥接：一次抽 30 题 → 批量保存 → 提交出结果；保存/提交带乐观锁 version，且 typeCode+version 锁定同一套题 |
并发冲突返回什么码/结构？前端需据此提示「题目已更新，请重试」 |
| 10 | 能力测评（ability） | 用 attemptQuestionId + selectedOptionId 提交，无 version |
与测评(9)不一致是否有意？能力测评是否也需要乐观锁 |
| 11 | 岗位详情口径 | 学生端公开详情走 GET /jobs/public/{jobId}；GET /jobs/{jobId} 是公司端看自己发布的岗位 |
确认：/jobs/{jobId} 对 STUDENT 返回 403 是预期（学生不该走这条） |
2. 后端未实现 / 缺失的端点（实网 404，需补齐）
以下端点前端已按接口文档实现调用，但实网返回 404 not found，对应页面因此无真实数据源：
| 端点 | 实网结果 | 受影响功能 | 建议 |
|---|---|---|---|
GET /salary-calculator/calculations、/cities、/cities/{cityCode}、/calculations/{id}、DELETE /calculations/{id} |
404 | 薪资计算器工具页 | 优先补齐，属求职者高频工具 |
GET /skills/word-cloud、/skills/match、/skills/learning-path |
404 | 成长域「技能词云 / 岗位匹配 / 学习路径」 | 补齐或明确砍掉（前端好同步摘页面） |
GET /onboarding/company/checklist-items、/onboarding/company/knowledge |
404 | 企业端入职准备 | 补齐 |
GET /account/deletion-request |
404 | 账号注销申请查询（POST 同路径待验） | 确认注销链路：查询端点是否存在 |
GET /admin/reviews/replies/pending、GET /company/review-reply/stats |
404 | 评价回复审核 / 统计 | 确认是否已实现 |
GET /profile/me/resume |
404（code=6001 profile not found） |
简历页 | 学生尚未创建简历时建议返回 200 + 空结构，否则前端把「未填写」当「请求失败」 |
另：GET /jobs/{jobId}/salary 在接口文档中不存在（salary-calculator 域也 404）。早期前端误调该端点，已在本次修正中移除。若产品需要「按经验段拆分的真实薪资」，请后端设计并给出端点。
3. 实网探测异常汇总（142 个 GET，50 个异常）
3.1 403 forbidden（角色权限，预期，但请复核清单）
/admin/** 全部（scoring / reviews / reports / companies / candidate-scoring）、
/companies/me/** 全部（jobs / talent-invitations / match-rule / onboarding / verification / job-reviews）、
/company/** 全部（applications / candidates / scoring）、
/jobs/{jobId}、/jobs/{jobId}/competition-ranking、/offers/statistics。
学生账号访问自然 403，属预期。唯一需要确认的是
/jobs/{jobId}：学生端应走/jobs/public/{jobId}，请确认这条 403 是设计如此。
3.2 400 missing parameter（前端需带参，请确认参数名与必填性）
| 端点 | 缺失参数 |
|---|---|
GET /jobs/compare |
ids |
GET /offers/compare |
ids |
GET /company/applications |
jobId |
GET /admin/scoring/fairness/overview |
period |
GET /admin/scoring/fairness/dimensions |
period |
GET /admin/scoring/risk/trend |
bucket |
GET /admin/companies/verifications/history |
verificationId |
3.3 404 not found（未实现）
见第 2 节。
4. 测试账号
| 账号 | 密码 | 实网结果 |
|---|---|---|
19900009021（学生） |
ZhilaiTest!2026#A |
✅ 可用，登录返回 role=STUDENT, userId=4 |
19900009801（企业） |
文档给的密码 | ❌ 登录 401 |
19900009802（企业） |
文档给的密码 | ❌ 登录 401 |
需后端提供一组可用的企业端测试账号（含正确口令），否则企业端 /companies/me/**、/company/** 无法联调（学生 token 一律 403）。同时请提供一组 ADMIN 测试账号用于后台域联调。
5. 前端已自行修复（无需后端改动）
| 问题 | 处理 |
|---|---|
分页基准错误：此前传 page=1，会静默丢掉第 1 页数据 |
改为 0-based page=0，并封装 toBackendPage/toFrontendPage |
岗位 DTO 字段名不一致（title/company.name/薪资单位「元」） |
新增映射：title→positionName、company.name→companyName、薪资「元→K」、status→中文 |
| 求职偏好结构不一致（后端多值数组+英文 token ↔ 前端单值中文） | API 层双向映射（取首项 / token↔label），并新增 EMPLOYMENT_TYPE_LABEL/EMPLOYMENT_TYPE_TOKEN |
岗位评分调了不存在的 GET /jobs/{id}/score |
改打真实端点 GET /jobs/{id}/personalized-review-score，新增 mapPersonalizedScore（后端 dimensionScores 对象 → 雷达图维度数组） |
岗位详情调了不存在的 GET /jobs/{id}/salary，且它在 Promise.all 中 → 404 会让整个详情页加载失败 |
移除该调用与「真实薪资区间」表；薪资仍由岗位对象的 salaryMin/salaryMax 展示 |
| 测评 / 能力测评的单题推进 UI 与后端「答卷模型」不同构 | Hook/API 层桥接（抽题→答题→提交→取果），沉淀 mapAttemptToAssessment 等 |
说明：当前
app.config.js的extra.apiUseMock = true，已接通的域走真实后端，未接通的域回落 mock，保证 App 随时可跑、不回归。遇 mock 数据即说明该域尚未接通，不是后端返回了假数据。
6. 覆盖率明细与后续排期
未接入 168 个端点，按域分布：
| 域 | 未接入数 | 性质 |
|---|---|---|
| admin | 34 | 前端未建后台页（后端应已实现） |
| profile | 32 | 部分前端未接（候选人评分/数据导出/推荐/隐私/权重等） |
| companies | 20 | 企业端未接 |
| offers | 12 | 前端未接（Offer 域） |
| company | 11 | 企业端候选人/评分 |
| onboarding | 9 | 含 2 个后端 404 |
| interviews | 9 | 面试评分域，前端未接 |
| applications | 7 | 投递域，前端未接 |
| jobs | 7 | 含比较/竞争排名等 |
| salary-calculator | 6 | 后端 404 |
| reviews | 4 | 评价回复域 |
| blocks | 3 | 屏蔽域 |
| reports | 3 | 举报域 |
| skills | 3 | 后端 404 |
前端后续接入优先级：
- P0：求职者核心闭环 ——
applications（投递）、interviews（面试）、offers（Offer） - P1：企业端
companies/**、company/**、reviews回复、blocks、reports - P2：
admin/**（后台）、profile剩余（候选人评分、数据导出、推荐）
7. 待后端回复的清单（速览）
- 第 1 节 11 项契约逐条确认（尤其：分页基准、错误码表、测评 version 冲突码、岗位 status 枚举、偏好缺「期望薪资/求职状态」）。
- 第 2 节 404 端点：是「未实现」还是「路径变更」？给出排期或确认砍掉。
- 第 3.2 节 400 端点：确认必填参数名。
- 第 4 节：提供可用的企业端与 ADMIN 测试账号。
- 第 1.8 / 2 节：是否需要后端补「岗位分经验段薪资」端点（前端已移除误调）。
GET /jobs/{jobId}对学生的 403 是否为预期（学生端是否只应走/jobs/public/{jobId}）。