doublex001
4 weeks ago
1 changed files with 148 additions and 0 deletions
@ -0,0 +1,148 @@ |
|||
# 职来（有职）前端 × 后端 联调问题清单（致后端同事） |
|||
|
|||
> 生成时间：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. 第 1 节 11 项契约逐条确认（尤其：分页基准、错误码表、测评 version 冲突码、岗位 status 枚举、偏好缺「期望薪资/求职状态」）。 |
|||
2. 第 2 节 404 端点：是「未实现」还是「路径变更」？给出排期或确认砍掉。 |
|||
3. 第 3.2 节 400 端点：确认必填参数名。 |
|||
4. 第 4 节：提供可用的**企业端**与 **ADMIN** 测试账号。 |
|||
5. 第 1.8 / 2 节：是否需要后端补「岗位分经验段薪资」端点（前端已移除误调）。 |
|||
6. `GET /jobs/{jobId}` 对学生的 403 是否为预期（学生端是否只应走 `/jobs/public/{jobId}`）。 |
|||
Loading…
Reference in new issue