Zhang Shun
2 months ago
2 changed files with 535 additions and 528 deletions
@ -0,0 +1,531 @@ |
|||
# 职来后端后续开发规划与 Figma 差距修复方案 |
|||
|
|||
> 文档状态：已确认，作为后续开发排期依据 |
|||
> |
|||
> 确认日期：2026-08-25 |
|||
> |
|||
> 适用项目：职来（mydreamjob-server） |
|||
|
|||
> **正式接口文档目录**：`C:\Users\15642\Desktop\zhilai\docs`（OpenAPI、前端联调、验收、各模块 API 文档的唯一正式目录）。 |
|||
> 本文档 `mydreamjob-server\docs\backend-development-roadmap.md` 仅保留为「路线图源文件」，不移动、不删除任何文档。 |
|||
|
|||
## 1. 文档目的 |
|||
|
|||
本文档用于统一 Figma UI、产品功能表和后端实现之间的差距，明确后端后续开发顺序。 |
|||
|
|||
本规划遵循以下原则： |
|||
|
|||
1. 先修复已经实现但存在安全或契约问题的内容； |
|||
2. 再开发完全缺失的新功能； |
|||
3. 不破坏已验收接口语义； |
|||
4. 不直接修改已有字段类型； |
|||
5. 每个模块由开发者完成代码、自动化测试、黑盒验收和文档更新； |
|||
6. 未经负责人确认，不开始下一模块。 |
|||
|
|||
## 2. 当前基线 |
|||
|
|||
| 项目 | 当前状态 | |
|||
|---|---| |
|||
| OpenAPI | **125 paths、159 operations** | |
|||
| Flyway | **V1–V33** 已存在 | |
|||
| 全量测试 | **1255/1255 通过**（本次 `mvn clean verify` 实际数量） | |
|||
| 已完成范围 | V24 Candidate Scoring、V25 Governance、V26 Offer Advance、V27 Privacy、V28/V29 Account Deletion、V30 Data Export、V31 Interview Score、V32 Competition Ranking、V33 Report/Block，及认证、资料、岗位、投递、面试、Offer、看板等核心闭环 | |
|||
| 当前结论 | 已达到已实现范围的 Release Candidate；V33 Report/Block 已完成真实 MySQL/Docker 黑盒验收并正式冻结 | |
|||
| 本规划范围 | 代码修复、新功能开发、接口契约、数据权限和治理能力 | |
|||
|
|||
### 2.0 模块状态分类 |
|||
|
|||
| 类别 | 模块 | |
|||
|---|---| |
|||
| 已完成并已验收 | V24 Candidate Scoring、V25 Governance、V26 Offer Advance、V27 Privacy、V28/V29 Account Deletion、V30 Data Export、V31 Interview Score、V32 Competition Ranking、V33 Report/Block | |
|||
| 已完成、待真实 MySQL/Docker 验收 | — | |
|||
| 已设计未编码 | 测评系统（Holland／能力测评）、公平性检测、SHAP／规则解释、防刷审计、企业评价管理、企业人才推荐、统一求职进度聚合 | |
|||
| 未开始 | AI 简历诊断／优化、AI 模拟面试、行业技能词云、入职准备清单、薪资计算器、诚信积分、消息撤回 | |
|||
|
|||
### 2.1 已确认的产品决策 |
|||
|
|||
| 事项 | 决策 | |
|||
|---|---| |
|||
| 同岗位竞争力排名 | 批准开发，排在隐私模块之后 | |
|||
| 结构化面试评分 | 批准独立开发，不复用 `candidate_feedback` | |
|||
| 隐私设置 | 批准 | |
|||
| 账号注销 | 已批准并统一为 **30 天**冷静期（`app.deletion.cooling-days` / `DELETION_COOLING_DAYS`，默认 30）。到期后完成账号 PII 脱敏并保留业务记录与审计轨迹。 | |
|||
| 个人数据导出 | 批准，采用异步导出任务 | |
|||
| 防刷审计报告 | 仅 ADMIN 可见 | |
|||
| 公平性检测 | 纳入后续范围 | |
|||
| SHAP/规则解释 | 纳入后续范围，后置实现 | |
|||
| 反刷能力 | 纳入后续范围，先做确定性规则型方案 | |
|||
| `skills` 字段 | 旧接口继续保持 String，后续可增加兼容字段 `skillsList` | |
|||
| Offer 综合比较 | 暂由前端展示，后续再决定是否由后端计算 | |
|||
| Figma 重复页面 | 视为同一功能的不同状态或设计稿，不新增重复接口 | |
|||
|
|||
## 3. 当前已实现功能 |
|||
|
|||
### 3.1 求职端 |
|||
|
|||
- 认证与登录； |
|||
- 个人资料、求职偏好； |
|||
- 岗位搜索、筛选、比较、收藏； |
|||
- 岗位评价和评价审核； |
|||
- 评价权重设置； |
|||
- 投递和投递时间线； |
|||
- Offer 基础与进阶功能； |
|||
- 面试流程； |
|||
- 通知中心、站内信和直聊； |
|||
- 双向匹配； |
|||
- 简历版本管理和简历导出； |
|||
- 求职者评分卡； |
|||
- Candidate Scoring Engine； |
|||
- 评分申诉、审核和回滚。 |
|||
|
|||
### 3.2 企业端 |
|||
|
|||
- 企业资料和企业认证； |
|||
- 岗位发布和管理； |
|||
- 企业公开主页； |
|||
- 企业候选人看板； |
|||
- 企业评分运营看板； |
|||
- 候选人评分详情； |
|||
- Offer 管理； |
|||
- 面试管理； |
|||
- 评价审核基础能力； |
|||
- 双向匹配、通知和直聊。 |
|||
|
|||
## 4. Figma 与后端覆盖结论 |
|||
|
|||
### 4.1 已完成或基本完成 |
|||
|
|||
| Figma 页面/功能 | 当前后端接口 | 状态 | |
|||
|---|---|---| |
|||
| 首页、岗位搜索、岗位详情 | `/jobs`、`/jobs/search`、`/jobs/filters`、`/jobs/{id}`、`/companies/{id}/jobs` | 已完成 | |
|||
| 岗位收藏 | `/jobs/favorites`、`POST/DELETE /jobs/{jobId}/favorite` | 已完成 | |
|||
| 岗位对比 | `/jobs/compare` | 已完成 | |
|||
| 岗位评价、评价详情 | `/jobs/{jobId}/reviews`、`/summary`、评价 CRUD | 基本完成 | |
|||
| 评价权重设置 | `/profile/me/review-weights`、`/review-weight-templates` | 已完成 | |
|||
| 通知中心 | `/notifications`、`/unread-count`、`/{id}/read`、`/read-all` | 已完成 | |
|||
| 站内信、HR 聊天 | `/conversations`、`/conversations/messages`、`/read` | 已完成 | |
|||
| 双向匹配 | 匹配规则、评分、`/applications/{id}/match`、会话接口 | 已完成 | |
|||
| 面试安排 | `/interviews*`、`/applications/{id}/interviews` | 已完成 | |
|||
| Offer 基础和进阶 | `/offers`、状态、时间线、提醒、还价、比较、统计 | 已完成基础能力 | |
|||
| 个人资料、求职偏好 | `/profile/me`、`PUT /profile/me`、`/profile/me/preferences` | 已完成 | |
|||
| 简历版本和简历导出 | `/profile/me/resume-versions`、`/resume-export-tasks` | 已完成，但不是个人数据导出 | |
|||
| 求职者评分卡 | `/profile/me/candidate-score-card`、`candidate-scoring*` | 已完成 | |
|||
| 评分申诉、审核、回滚 | `/profile/me/candidate-scoring/appeals`、`/admin/candidate-scoring/appeals*` | 已完成 | |
|||
| 企业候选人看板 | `/company/candidates`、`/company/candidates/{id}` | 已完成 | |
|||
| 企业评分看板 | `/company/scoring/dashboard/*` | 已完成 | |
|||
| 企业认证 | `/companies/me/verification`、`/admin/companies/verifications*` | 已完成 | |
|||
|
|||
### 4.2 部分完成或口径不一致 |
|||
|
|||
| Figma 页面/功能 | 当前实现 | 差距 | |
|||
|---|---|---| |
|||
| 同岗位竞争力排名 | `GET /jobs/{jobId}/competition-ranking` 已实现 | 已交付；最终口径：WITHDRAWN/REJECTED 退出候选人池（请求 403/2002）；无评分但有效投递返回 200 + null 分数；Top5 匿名。不宣称"支持隐私退出" | |
|||
| 求职进度 | applications、timeline、offers、interviews 可组合 | 缺统一的求职进度聚合接口 | |
|||
| Offer 对比 | `/offers/compare` 返回 Offer 字段 | 综合薪资、福利、发展空间当前由前端展示，后端不计算综合结论 | |
|||
| HR 评价详情 | `candidate_feedback` 已实现 | 不是结构化面试评分 | |
|||
| 企业评价管理 | 有评价审核和管理员决策 | 缺企业端评价管理、回复和运营动作 | |
|||
| 企业人才推荐 | 有候选人列表和评分 | 缺推荐排序、推荐理由和可解释结果 | |
|||
| 运营规则配置 | Figma 有页面 | 后端暂无规则配置接口 | |
|||
| 防刷审计报告 | 已有评价审核基础能力 | 不是风险等级、风险趋势、风险分布和事件审计报告 | |
|||
|
|||
### 4.3 完全缺失 |
|||
|
|||
- 霍兰德职业兴趣测评； |
|||
- 四维能力测评； |
|||
- 测评结果和测评岗位推荐； |
|||
- AI 简历诊断和优化； |
|||
- AI 模拟面试和面试题预测； |
|||
- 行业技能词云； |
|||
- 入职准备清单和公司知识介绍； |
|||
- 薪资计算器和薪资参考； |
|||
- 公平性检测； |
|||
- SHAP/规则解释； |
|||
- ADMIN 防刷审计和规则配置； |
|||
- 诚信积分和激励。 |
|||
- 已非缺失（已实现）：个人数据导出（V30）、隐私设置（V27）、账号注销（V28/V29）、举报与屏蔽（V33）、结构化面试评分（V31）、同岗位竞争力排名（V32）。 |
|||
|
|||
## 5. 已有代码的优先修复项 |
|||
|
|||
### 5.1 CandidateFeedback 响应脱敏（第一项） |
|||
|
|||
当前反馈响应不能向前端暴露以下字段： |
|||
|
|||
- `companyUserId`； |
|||
- `studentUserId`； |
|||
- `phone`； |
|||
- `email`； |
|||
- `passwordHash`； |
|||
- `resumeUrl`。 |
|||
|
|||
建议使用白名单响应 DTO： |
|||
|
|||
```json |
|||
{ |
|||
"id": 1, |
|||
"applicationId": 31, |
|||
"rating": 5, |
|||
"content": "沟通良好", |
|||
"tags": ["沟通良好"], |
|||
"createdAt": "2026-08-25T10:00:00" |
|||
} |
|||
``` |
|||
|
|||
修复约束： |
|||
|
|||
- 不修改请求格式； |
|||
- 不修改路径、权限和错误码； |
|||
- 不修改 `candidate_feedback` 表； |
|||
- 不新增 Flyway； |
|||
- 增加企业、学生、越权、未登录和脱敏测试； |
|||
- 更新 OpenAPI response schema 和前端联调文档。 |
|||
|
|||
### 5.2 只需统一文档，不应误改业务语义 |
|||
|
|||
| 内容 | 处理方式 | |
|||
|---|---| |
|||
| `skills` 为 String | 保持旧接口兼容，文档说明解析方式，后续再增加 `skillsList` | |
|||
| `PENDING`/`INSUFFICIENT_DATA` | 属于评分设计状态，不转成 0 分 | |
|||
| `/resume-export-tasks` | 明确为简历导出，不当作个人数据导出 | |
|||
| Offer 综合比较 | 暂由前端展示，不新增后端综合评分 | |
|||
| Figma 重复页面 | 作为同一接口的不同状态处理 | |
|||
|
|||
## 6. 后续模块设计与顺序 |
|||
|
|||
### 阶段 0：已有代码和契约修复 |
|||
|
|||
#### 模块 0.1：CandidateFeedback 脱敏 |
|||
|
|||
不新增接口、数据库表或 Flyway。完成后要求专项测试、全量测试、OpenAPI 校验和黑盒脱敏验证全部通过。 |
|||
|
|||
### 阶段 1：隐私与账户合规 |
|||
|
|||
#### 模块 1.1：隐私设置 |
|||
|
|||
接口： |
|||
|
|||
```text |
|||
GET /profile/me/privacy |
|||
PUT /profile/me/privacy |
|||
``` |
|||
|
|||
落地现状（V27 Privacy 已实现，真实能力**仅两项**）： |
|||
|
|||
- `resumeVisibility`（简历可见性）； |
|||
- `contactVisible`（企业是否可联系）。 |
|||
|
|||
以下为**未来“企业人才推荐/细粒度授权”设计项，尚未实现，不得伪称已提供**： |
|||
|
|||
- 退出同岗位排名； |
|||
- 退出企业人才推荐。 |
|||
|
|||
> ⚠️ V27 隐私设置接口已验收；后续如需新增“退出同岗位排名 / 退出企业人才推荐”，属于新设计，需随“企业人才推荐/细粒度授权”一并评审，不得在未开发前宣称已支持。 |
|||
|
|||
建议表和迁移（如未来扩展）： |
|||
|
|||
```text |
|||
student_privacy_settings |
|||
（V27 已落地，未新增字段） |
|||
``` |
|||
|
|||
#### 模块 1.2：账号注销 |
|||
|
|||
接口： |
|||
|
|||
```text |
|||
POST /profile/me/deletion |
|||
GET /profile/me/deletion |
|||
POST /profile/me/deletion/cancel |
|||
``` |
|||
|
|||
规则： |
|||
|
|||
- 申请后进入 `PENDING`； |
|||
- 冷静期统一为 **30 天**（`app.deletion.cooling-days` / `DELETION_COOLING_DAYS`，默认 30）；到期后执行账号 PII 脱敏，业务记录与审计轨迹按既有保留策略留存； |
|||
- 冷静期支持取消； |
|||
- 到期后执行删除、匿名化或保留策略； |
|||
- 全流程写入审计日志。 |
|||
|
|||
#### 模块 1.3：个人数据导出 |
|||
|
|||
接口： |
|||
|
|||
```text |
|||
POST /profile/me/data-export-tasks |
|||
GET /profile/me/data-export-tasks |
|||
GET /profile/me/data-export-tasks/{taskId} |
|||
GET /profile/me/data-export-tasks/{taskId}/download |
|||
``` |
|||
|
|||
要求： |
|||
|
|||
- 不复用 `/resume-export-tasks`； |
|||
- 使用异步任务； |
|||
- 不在 HTTP 请求内同步打包全部数据； |
|||
- 导出内容不得包含密码、JWT、验证码等认证敏感信息。 |
|||
|
|||
建议表和迁移： |
|||
|
|||
```text |
|||
personal_data_export_tasks |
|||
V28__personal_data_export.sql |
|||
``` |
|||
|
|||
### 阶段 2：结构化面试评分 |
|||
|
|||
结构化面试评分独立于 `candidate_feedback`。 |
|||
|
|||
接口： |
|||
|
|||
```text |
|||
POST /interviews/{interviewId}/score |
|||
GET /interviews/{interviewId}/score |
|||
PUT /interviews/{interviewId}/score |
|||
GET /interviews/{interviewId}/score/history |
|||
``` |
|||
|
|||
权限： |
|||
|
|||
| 角色 | 权限 | |
|||
|---|---| |
|||
| COMPANY | 本企业面试可创建、修改、查看 | |
|||
| STUDENT | 只能查看本人面试评分 | |
|||
| ADMIN | 只读审计 | |
|||
| 其他用户 | 403 | |
|||
|
|||
建议表和迁移： |
|||
|
|||
```text |
|||
interview_scores |
|||
interview_score_history |
|||
V29__interview_scoring.sql |
|||
``` |
|||
|
|||
### 阶段 3：同岗位竞争力排名 |
|||
|
|||
接口： |
|||
|
|||
```text |
|||
GET /jobs/{jobId}/competition-ranking |
|||
``` |
|||
|
|||
必须支持： |
|||
|
|||
- 当前学生在指定岗位的排名； |
|||
- cohort 总数； |
|||
- 百分位； |
|||
- 维度百分位； |
|||
- Top 候选人； |
|||
- 改进建议； |
|||
- 样本不足； |
|||
- 无评分候选人； |
|||
- 投递状态过滤（WITHDRAWN/REJECTED 退出候选人池，请求返回 403/2002）； |
|||
- 候选人信息脱敏。 |
|||
|
|||
必须复用： |
|||
|
|||
```text |
|||
CandidateScoringCalculator |
|||
candidate_dimension_scores |
|||
applications |
|||
jobs |
|||
``` |
|||
|
|||
> ⚠️ V32 已编码并验收。**最终口径**：仅 `SUBMITTED / VIEWED / INTERVIEW / HIRED` 有效投递可进入；`WITHDRAWN / REJECTED` 已退出候选人池（请求 403/2002）；无评分但有效投递返回 200 + `rank/overallScore/percentile=null`。**不宣称支持“隐私退出”**；排名不使用 `student_privacy_settings`。 |
|||
|
|||
初期可以不新增数据库表。 |
|||
|
|||
### 阶段 4：测评系统 |
|||
|
|||
开发顺序： |
|||
|
|||
1. 霍兰德职业兴趣测评； |
|||
2. 四维能力测评； |
|||
3. 测评答题和进度保存； |
|||
4. 测评结果； |
|||
5. 测评结果进入 ABILITY/GROWTH； |
|||
6. 根据测评结果推荐岗位。 |
|||
|
|||
建议接口： |
|||
|
|||
```text |
|||
GET /assessments/types |
|||
GET /assessments/{type}/questions |
|||
POST /assessments/attempts |
|||
POST /assessments/attempts/{id}/submit |
|||
GET /assessments/attempts/{id}/result |
|||
GET /profile/me/assessment-results |
|||
``` |
|||
|
|||
建议表： |
|||
|
|||
```text |
|||
assessment_definitions |
|||
assessment_questions |
|||
assessment_attempts |
|||
assessment_answers |
|||
assessment_results |
|||
``` |
|||
|
|||
建议迁移： |
|||
|
|||
```text |
|||
V30__assessment.sql |
|||
``` |
|||
|
|||
### 阶段 5：公平性、SHAP、反刷审计 |
|||
|
|||
#### 防刷审计 |
|||
|
|||
仅 ADMIN 可见： |
|||
|
|||
```text |
|||
GET /admin/scoring/risk/overview |
|||
GET /admin/scoring/risk/trend |
|||
GET /admin/scoring/risk/distribution |
|||
GET /admin/scoring/risk/events |
|||
GET /admin/scoring/rules |
|||
PUT /admin/scoring/rules/{id} |
|||
``` |
|||
|
|||
禁止返回原始手机号、IP、设备指纹、密码、Token 等敏感信息。 |
|||
|
|||
建议表： |
|||
|
|||
```text |
|||
scoring_risk_events |
|||
scoring_rule_configs |
|||
scoring_risk_actions |
|||
``` |
|||
|
|||
#### 公平性检测 |
|||
|
|||
第一阶段做统计检测： |
|||
|
|||
- 不同群体平均分差异； |
|||
- 通过率差异； |
|||
- 排名差异； |
|||
- 样本不足提示； |
|||
- 异常分布提示。 |
|||
|
|||
#### SHAP/规则解释 |
|||
|
|||
先实现确定性规则解释，不让前端依赖 AI 模型结果： |
|||
|
|||
```json |
|||
{ |
|||
"dimension": "EDUCATION", |
|||
"reasons": [ |
|||
"学历字段完整", |
|||
"学校信息缺失", |
|||
"毕业年份有效" |
|||
] |
|||
} |
|||
``` |
|||
|
|||
### 阶段 6：企业运营模块 |
|||
|
|||
开发顺序： |
|||
|
|||
1. 企业评价管理； |
|||
2. 企业评价回复； |
|||
3. 运营规则配置； |
|||
4. 企业人才推荐； |
|||
5. 推荐理由和解释； |
|||
6. 企业运营数据增强。 |
|||
|
|||
### 阶段 7：AI 和增值功能 |
|||
|
|||
- AI 简历诊断； |
|||
- AI 简历优化； |
|||
- AI 模拟面试； |
|||
- 面试题预测； |
|||
- 行业技能词云； |
|||
- 入职准备清单； |
|||
- 公司知识介绍； |
|||
- 简历查重； |
|||
- 诚信积分； |
|||
- 消息撤回。 |
|||
|
|||
## 7. 总体优先级 |
|||
|
|||
| 优先级 | 模块 | |
|||
|---|---| |
|||
| P0 | CandidateFeedback 脱敏 | |
|||
| P0 | 隐私设置 | |
|||
| P0 | 账号注销 | |
|||
| P0 | 个人数据导出 | |
|||
| P0 | 结构化面试评分 | |
|||
| P0/P1 | 同岗位竞争力排名 | |
|||
| P1 | 霍兰德和四维能力测评 | |
|||
| P1 | 统一求职进度 | |
|||
| P1 | 企业评价管理 | |
|||
| P1 | 企业人才推荐 | |
|||
| P1 | 公平性检测 | |
|||
| P1 | ADMIN 防刷审计 | |
|||
| P2 | SHAP 高级解释 | |
|||
| P2 | AI 简历、AI 模拟面试 | |
|||
| P2 | 技能词云、入职清单、诚信积分 | |
|||
|
|||
## 8. 每个模块的统一交付要求 |
|||
|
|||
每个模块必须交付： |
|||
|
|||
1. 接口设计； |
|||
2. 请求和响应 DTO； |
|||
3. Controller； |
|||
4. Service； |
|||
5. Repository； |
|||
6. Flyway 迁移； |
|||
7. 错误码； |
|||
8. 权限矩阵； |
|||
9. 脱敏规则； |
|||
10. 幂等设计； |
|||
11. 并发控制； |
|||
12. Service 单元测试； |
|||
13. MockMvc 测试； |
|||
14. 持久化测试； |
|||
15. Docker/MySQL 黑盒验收； |
|||
16. OpenAPI 更新； |
|||
17. 前端联调文档； |
|||
18. 已验收模块回归测试。 |
|||
|
|||
## 9. 历史执行指令（已完成，仅供追溯） |
|||
|
|||
以下是 CandidateFeedback 脱敏阶段的历史执行指令，不代表当前待办，后续开发以本路线图的“未开发/已设计未编码”分类为准。 |
|||
|
|||
```text |
|||
当前先修复已有 CandidateFeedback 接口的响应脱敏问题，不开发新业务模块。 |
|||
|
|||
问题： |
|||
CandidateFeedback 当前响应包含 companyUserId、studentUserId 等内部身份字段，不符合前端契约和数据脱敏要求。 |
|||
|
|||
要求： |
|||
1. 先检查 CandidateFeedbackController、CandidateFeedbackService、现有 View/DTO、Repository、测试和 OpenAPI。 |
|||
2. 新增白名单 CandidateFeedbackResponse DTO。 |
|||
3. 保持现有接口路径、请求参数、权限、错误码和数据库结构不变。 |
|||
4. 学生和企业响应都不得返回 companyUserId、studentUserId、phone、email、passwordHash、resumeUrl。 |
|||
5. 不修改 candidate_feedback 表。 |
|||
6. 不新增 Flyway。 |
|||
7. 不启动或停止 Docker。 |
|||
8. 补充 COMPANY、STUDENT、其他学生、其他企业、未登录和脱敏测试。 |
|||
9. 更新 OpenAPI response schema 和 frontend-integration.md。 |
|||
10. 执行 CandidateFeedback 专项测试、mvn test、mvn clean verify、python docs/verify_openapi.py。 |
|||
11. 完成后停止，不要继续开发隐私设置、面试评分或同岗位排名。 |
|||
|
|||
最后只输出：修改文件、测试结果、OpenAPI 路径数、脱敏验证结果、是否还有问题、等待下一步指令。 |
|||
``` |
|||
|
|||
## 10. 变更控制 |
|||
|
|||
未经负责人再次确认，不得： |
|||
|
|||
- 修改已验收接口的响应语义； |
|||
- 将 `skills` 从 String 改成数组； |
|||
- 把 CandidateFeedback 当作面试评分； |
|||
- 把 `/resume-export-tasks` 当作个人数据导出； |
|||
- 把 percentile 当作同岗位排行榜； |
|||
- 把评价审核当作完整防刷审计； |
|||
- 让 COMPANY 查看防刷审计报告； |
|||
- 新增未批准的 Flyway； |
|||
- 删除或清理业务数据； |
|||
- 启动或停止 Docker。 |
|||
@ -1,531 +1,7 @@ |
|||
# 职来后端后续开发规划与 Figma 差距修复方案 |
|||
# 路线图已迁移 |
|||
|
|||
> 文档状态：已确认，作为后续开发排期依据 |
|||
> |
|||
> 确认日期：2026-08-25 |
|||
> |
|||
> 适用项目：职来（mydreamjob-server） |
|||
正式的后端开发路线图已迁移至项目根目录： |
|||
|
|||
> **正式接口文档目录**：`C:\Users\15642\Desktop\zhilai\docs`（OpenAPI、前端联调、验收、各模块 API 文档的唯一正式目录）。 |
|||
> 本文档 `mydreamjob-server\docs\backend-development-roadmap.md` 仅保留为「路线图源文件」，不移动、不删除任何文档。 |
|||
[`docs/backend-development-roadmap.md`](../../docs/backend-development-roadmap.md) |
|||
|
|||
## 1. 文档目的 |
|||
|
|||
本文档用于统一 Figma UI、产品功能表和后端实现之间的差距，明确后端后续开发顺序。 |
|||
|
|||
本规划遵循以下原则： |
|||
|
|||
1. 先修复已经实现但存在安全或契约问题的内容； |
|||
2. 再开发完全缺失的新功能； |
|||
3. 不破坏已验收接口语义； |
|||
4. 不直接修改已有字段类型； |
|||
5. 每个模块由开发者完成代码、自动化测试、黑盒验收和文档更新； |
|||
6. 未经负责人确认，不开始下一模块。 |
|||
|
|||
## 2. 当前基线 |
|||
|
|||
| 项目 | 当前状态 | |
|||
|---|---| |
|||
| OpenAPI | **125 paths、159 operations** | |
|||
| Flyway | **V1–V33** 已存在 | |
|||
| 全量测试 | **1255/1255 通过**（本次 `mvn clean verify` 实际数量） | |
|||
| 已完成范围 | V24 Candidate Scoring、V25 Governance、V26 Offer Advance、V27 Privacy、V28/V29 Account Deletion、V30 Data Export、V31 Interview Score、V32 Competition Ranking、V33 Report/Block，及认证、资料、岗位、投递、面试、Offer、看板等核心闭环 | |
|||
| 当前结论 | 已达到已实现范围的 Release Candidate；V33 待负责人 MySQL/Docker 黑盒复验 | |
|||
| 本规划范围 | 代码修复、新功能开发、接口契约、数据权限和治理能力 | |
|||
|
|||
### 2.0 模块状态分类 |
|||
|
|||
| 类别 | 模块 | |
|||
|---|---| |
|||
| 已完成并已验收 | V24 Candidate Scoring、V25 Governance、V26 Offer Advance、V27 Privacy、V28/V29 Account Deletion、V30 Data Export、V31 Interview Score、V32 Competition Ranking | |
|||
| 已完成、待真实 MySQL/Docker 验收 | **V33 Report/Block**（自动化通过；限流/屏蔽拒发的拒绝型安全审计独立事务已实现。MySQL 黑盒：**待复验**——本次复验被凭据环境阻塞，需负责人提供既有启动配置后复验） | |
|||
| 已设计未编码 | 测评系统（Holland／能力测评）、公平性检测、SHAP／规则解释、防刷审计、企业评价管理、企业人才推荐、统一求职进度聚合 | |
|||
| 未开始 | AI 简历诊断／优化、AI 模拟面试、行业技能词云、入职准备清单、薪资计算器、诚信积分、消息撤回 | |
|||
|
|||
### 2.1 已确认的产品决策 |
|||
|
|||
| 事项 | 决策 | |
|||
|---|---| |
|||
| 同岗位竞争力排名 | 批准开发，排在隐私模块之后 | |
|||
| 结构化面试评分 | 批准独立开发，不复用 `candidate_feedback` | |
|||
| 隐私设置 | 批准 | |
|||
| 账号注销 | 已批准并统一为 **30 天**冷静期（`app.deletion.cooling-days` / `DELETION_COOLING_DAYS`，默认 30）。到期后完成账号 PII 脱敏并保留业务记录与审计轨迹。 | |
|||
| 个人数据导出 | 批准，采用异步导出任务 | |
|||
| 防刷审计报告 | 仅 ADMIN 可见 | |
|||
| 公平性检测 | 纳入后续范围 | |
|||
| SHAP/规则解释 | 纳入后续范围，后置实现 | |
|||
| 反刷能力 | 纳入后续范围，先做确定性规则型方案 | |
|||
| `skills` 字段 | 旧接口继续保持 String，后续可增加兼容字段 `skillsList` | |
|||
| Offer 综合比较 | 暂由前端展示，后续再决定是否由后端计算 | |
|||
| Figma 重复页面 | 视为同一功能的不同状态或设计稿，不新增重复接口 | |
|||
|
|||
## 3. 当前已实现功能 |
|||
|
|||
### 3.1 求职端 |
|||
|
|||
- 认证与登录； |
|||
- 个人资料、求职偏好； |
|||
- 岗位搜索、筛选、比较、收藏； |
|||
- 岗位评价和评价审核； |
|||
- 评价权重设置； |
|||
- 投递和投递时间线； |
|||
- Offer 基础与进阶功能； |
|||
- 面试流程； |
|||
- 通知中心、站内信和直聊； |
|||
- 双向匹配； |
|||
- 简历版本管理和简历导出； |
|||
- 求职者评分卡； |
|||
- Candidate Scoring Engine； |
|||
- 评分申诉、审核和回滚。 |
|||
|
|||
### 3.2 企业端 |
|||
|
|||
- 企业资料和企业认证； |
|||
- 岗位发布和管理； |
|||
- 企业公开主页； |
|||
- 企业候选人看板； |
|||
- 企业评分运营看板； |
|||
- 候选人评分详情； |
|||
- Offer 管理； |
|||
- 面试管理； |
|||
- 评价审核基础能力； |
|||
- 双向匹配、通知和直聊。 |
|||
|
|||
## 4. Figma 与后端覆盖结论 |
|||
|
|||
### 4.1 已完成或基本完成 |
|||
|
|||
| Figma 页面/功能 | 当前后端接口 | 状态 | |
|||
|---|---|---| |
|||
| 首页、岗位搜索、岗位详情 | `/jobs`、`/jobs/search`、`/jobs/filters`、`/jobs/{id}`、`/companies/{id}/jobs` | 已完成 | |
|||
| 岗位收藏 | `/jobs/favorites`、`POST/DELETE /jobs/{jobId}/favorite` | 已完成 | |
|||
| 岗位对比 | `/jobs/compare` | 已完成 | |
|||
| 岗位评价、评价详情 | `/jobs/{jobId}/reviews`、`/summary`、评价 CRUD | 基本完成 | |
|||
| 评价权重设置 | `/profile/me/review-weights`、`/review-weight-templates` | 已完成 | |
|||
| 通知中心 | `/notifications`、`/unread-count`、`/{id}/read`、`/read-all` | 已完成 | |
|||
| 站内信、HR 聊天 | `/conversations`、`/conversations/messages`、`/read` | 已完成 | |
|||
| 双向匹配 | 匹配规则、评分、`/applications/{id}/match`、会话接口 | 已完成 | |
|||
| 面试安排 | `/interviews*`、`/applications/{id}/interviews` | 已完成 | |
|||
| Offer 基础和进阶 | `/offers`、状态、时间线、提醒、还价、比较、统计 | 已完成基础能力 | |
|||
| 个人资料、求职偏好 | `/profile/me`、`PUT /profile/me`、`/profile/me/preferences` | 已完成 | |
|||
| 简历版本和简历导出 | `/profile/me/resume-versions`、`/resume-export-tasks` | 已完成，但不是个人数据导出 | |
|||
| 求职者评分卡 | `/profile/me/candidate-score-card`、`candidate-scoring*` | 已完成 | |
|||
| 评分申诉、审核、回滚 | `/profile/me/candidate-scoring/appeals`、`/admin/candidate-scoring/appeals*` | 已完成 | |
|||
| 企业候选人看板 | `/company/candidates`、`/company/candidates/{id}` | 已完成 | |
|||
| 企业评分看板 | `/company/scoring/dashboard/*` | 已完成 | |
|||
| 企业认证 | `/companies/me/verification`、`/admin/companies/verifications*` | 已完成 | |
|||
|
|||
### 4.2 部分完成或口径不一致 |
|||
|
|||
| Figma 页面/功能 | 当前实现 | 差距 | |
|||
|---|---|---| |
|||
| 同岗位竞争力排名 | `GET /jobs/{jobId}/competition-ranking` 已实现 | 已交付；最终口径：WITHDRAWN/REJECTED 退出候选人池（请求 403/2002）；无评分但有效投递返回 200 + null 分数；Top5 匿名。不宣称"支持隐私退出" | |
|||
| 求职进度 | applications、timeline、offers、interviews 可组合 | 缺统一的求职进度聚合接口 | |
|||
| Offer 对比 | `/offers/compare` 返回 Offer 字段 | 综合薪资、福利、发展空间当前由前端展示，后端不计算综合结论 | |
|||
| HR 评价详情 | `candidate_feedback` 已实现 | 不是结构化面试评分 | |
|||
| 企业评价管理 | 有评价审核和管理员决策 | 缺企业端评价管理、回复和运营动作 | |
|||
| 企业人才推荐 | 有候选人列表和评分 | 缺推荐排序、推荐理由和可解释结果 | |
|||
| 运营规则配置 | Figma 有页面 | 后端暂无规则配置接口 | |
|||
| 防刷审计报告 | 已有评价审核基础能力 | 不是风险等级、风险趋势、风险分布和事件审计报告 | |
|||
|
|||
### 4.3 完全缺失 |
|||
|
|||
- 霍兰德职业兴趣测评； |
|||
- 四维能力测评； |
|||
- 测评结果和测评岗位推荐； |
|||
- AI 简历诊断和优化； |
|||
- AI 模拟面试和面试题预测； |
|||
- 行业技能词云； |
|||
- 入职准备清单和公司知识介绍； |
|||
- 薪资计算器和薪资参考； |
|||
- 公平性检测； |
|||
- SHAP/规则解释； |
|||
- ADMIN 防刷审计和规则配置； |
|||
- 诚信积分和激励。 |
|||
- 已非缺失（已实现）：个人数据导出（V30）、隐私设置（V27）、账号注销（V28/V29）、举报与屏蔽（V33）、结构化面试评分（V31）、同岗位竞争力排名（V32）。 |
|||
|
|||
## 5. 已有代码的优先修复项 |
|||
|
|||
### 5.1 CandidateFeedback 响应脱敏（第一项） |
|||
|
|||
当前反馈响应不能向前端暴露以下字段： |
|||
|
|||
- `companyUserId`； |
|||
- `studentUserId`； |
|||
- `phone`； |
|||
- `email`； |
|||
- `passwordHash`； |
|||
- `resumeUrl`。 |
|||
|
|||
建议使用白名单响应 DTO： |
|||
|
|||
```json |
|||
{ |
|||
"id": 1, |
|||
"applicationId": 31, |
|||
"rating": 5, |
|||
"content": "沟通良好", |
|||
"tags": ["沟通良好"], |
|||
"createdAt": "2026-08-25T10:00:00" |
|||
} |
|||
``` |
|||
|
|||
修复约束： |
|||
|
|||
- 不修改请求格式； |
|||
- 不修改路径、权限和错误码； |
|||
- 不修改 `candidate_feedback` 表； |
|||
- 不新增 Flyway； |
|||
- 增加企业、学生、越权、未登录和脱敏测试； |
|||
- 更新 OpenAPI response schema 和前端联调文档。 |
|||
|
|||
### 5.2 只需统一文档，不应误改业务语义 |
|||
|
|||
| 内容 | 处理方式 | |
|||
|---|---| |
|||
| `skills` 为 String | 保持旧接口兼容，文档说明解析方式，后续再增加 `skillsList` | |
|||
| `PENDING`/`INSUFFICIENT_DATA` | 属于评分设计状态，不转成 0 分 | |
|||
| `/resume-export-tasks` | 明确为简历导出，不当作个人数据导出 | |
|||
| Offer 综合比较 | 暂由前端展示，不新增后端综合评分 | |
|||
| Figma 重复页面 | 作为同一接口的不同状态处理 | |
|||
|
|||
## 6. 后续模块设计与顺序 |
|||
|
|||
### 阶段 0：已有代码和契约修复 |
|||
|
|||
#### 模块 0.1：CandidateFeedback 脱敏 |
|||
|
|||
不新增接口、数据库表或 Flyway。完成后要求专项测试、全量测试、OpenAPI 校验和黑盒脱敏验证全部通过。 |
|||
|
|||
### 阶段 1：隐私与账户合规 |
|||
|
|||
#### 模块 1.1：隐私设置 |
|||
|
|||
接口： |
|||
|
|||
```text |
|||
GET /profile/me/privacy |
|||
PUT /profile/me/privacy |
|||
``` |
|||
|
|||
落地现状（V27 Privacy 已实现，真实能力**仅两项**）： |
|||
|
|||
- `resumeVisibility`（简历可见性）； |
|||
- `contactVisible`（企业是否可联系）。 |
|||
|
|||
以下为**未来“企业人才推荐/细粒度授权”设计项，尚未实现，不得伪称已提供**： |
|||
|
|||
- 退出同岗位排名； |
|||
- 退出企业人才推荐。 |
|||
|
|||
> ⚠️ V27 隐私设置接口已验收；后续如需新增“退出同岗位排名 / 退出企业人才推荐”，属于新设计，需随“企业人才推荐/细粒度授权”一并评审，不得在未开发前宣称已支持。 |
|||
|
|||
建议表和迁移（如未来扩展）： |
|||
|
|||
```text |
|||
student_privacy_settings |
|||
（V27 已落地，未新增字段） |
|||
``` |
|||
|
|||
#### 模块 1.2：账号注销 |
|||
|
|||
接口： |
|||
|
|||
```text |
|||
POST /profile/me/deletion |
|||
GET /profile/me/deletion |
|||
POST /profile/me/deletion/cancel |
|||
``` |
|||
|
|||
规则： |
|||
|
|||
- 申请后进入 `PENDING`； |
|||
- 冷静期统一为 **30 天**（`app.deletion.cooling-days` / `DELETION_COOLING_DAYS`，默认 30）；到期后执行账号 PII 脱敏，业务记录与审计轨迹按既有保留策略留存； |
|||
- 冷静期支持取消； |
|||
- 到期后执行删除、匿名化或保留策略； |
|||
- 全流程写入审计日志。 |
|||
|
|||
#### 模块 1.3：个人数据导出 |
|||
|
|||
接口： |
|||
|
|||
```text |
|||
POST /profile/me/data-export-tasks |
|||
GET /profile/me/data-export-tasks |
|||
GET /profile/me/data-export-tasks/{taskId} |
|||
GET /profile/me/data-export-tasks/{taskId}/download |
|||
``` |
|||
|
|||
要求： |
|||
|
|||
- 不复用 `/resume-export-tasks`； |
|||
- 使用异步任务； |
|||
- 不在 HTTP 请求内同步打包全部数据； |
|||
- 导出内容不得包含密码、JWT、验证码等认证敏感信息。 |
|||
|
|||
建议表和迁移： |
|||
|
|||
```text |
|||
personal_data_export_tasks |
|||
V28__personal_data_export.sql |
|||
``` |
|||
|
|||
### 阶段 2：结构化面试评分 |
|||
|
|||
结构化面试评分独立于 `candidate_feedback`。 |
|||
|
|||
接口： |
|||
|
|||
```text |
|||
POST /interviews/{interviewId}/score |
|||
GET /interviews/{interviewId}/score |
|||
PUT /interviews/{interviewId}/score |
|||
GET /interviews/{interviewId}/score/history |
|||
``` |
|||
|
|||
权限： |
|||
|
|||
| 角色 | 权限 | |
|||
|---|---| |
|||
| COMPANY | 本企业面试可创建、修改、查看 | |
|||
| STUDENT | 只能查看本人面试评分 | |
|||
| ADMIN | 只读审计 | |
|||
| 其他用户 | 403 | |
|||
|
|||
建议表和迁移： |
|||
|
|||
```text |
|||
interview_scores |
|||
interview_score_history |
|||
V29__interview_scoring.sql |
|||
``` |
|||
|
|||
### 阶段 3：同岗位竞争力排名 |
|||
|
|||
接口： |
|||
|
|||
```text |
|||
GET /jobs/{jobId}/competition-ranking |
|||
``` |
|||
|
|||
必须支持： |
|||
|
|||
- 当前学生在指定岗位的排名； |
|||
- cohort 总数； |
|||
- 百分位； |
|||
- 维度百分位； |
|||
- Top 候选人； |
|||
- 改进建议； |
|||
- 样本不足； |
|||
- 无评分候选人； |
|||
- 投递状态过滤（WITHDRAWN/REJECTED 退出候选人池，请求返回 403/2002）； |
|||
- 候选人信息脱敏。 |
|||
|
|||
必须复用： |
|||
|
|||
```text |
|||
CandidateScoringCalculator |
|||
candidate_dimension_scores |
|||
applications |
|||
jobs |
|||
``` |
|||
|
|||
> ⚠️ V32 已编码并验收。**最终口径**：仅 `SUBMITTED / VIEWED / INTERVIEW / HIRED` 有效投递可进入；`WITHDRAWN / REJECTED` 已退出候选人池（请求 403/2002）；无评分但有效投递返回 200 + `rank/overallScore/percentile=null`。**不宣称支持“隐私退出”**；排名不使用 `student_privacy_settings`。 |
|||
|
|||
初期可以不新增数据库表。 |
|||
|
|||
### 阶段 4：测评系统 |
|||
|
|||
开发顺序： |
|||
|
|||
1. 霍兰德职业兴趣测评； |
|||
2. 四维能力测评； |
|||
3. 测评答题和进度保存； |
|||
4. 测评结果； |
|||
5. 测评结果进入 ABILITY/GROWTH； |
|||
6. 根据测评结果推荐岗位。 |
|||
|
|||
建议接口： |
|||
|
|||
```text |
|||
GET /assessments/types |
|||
GET /assessments/{type}/questions |
|||
POST /assessments/attempts |
|||
POST /assessments/attempts/{id}/submit |
|||
GET /assessments/attempts/{id}/result |
|||
GET /profile/me/assessment-results |
|||
``` |
|||
|
|||
建议表： |
|||
|
|||
```text |
|||
assessment_definitions |
|||
assessment_questions |
|||
assessment_attempts |
|||
assessment_answers |
|||
assessment_results |
|||
``` |
|||
|
|||
建议迁移： |
|||
|
|||
```text |
|||
V30__assessment.sql |
|||
``` |
|||
|
|||
### 阶段 5：公平性、SHAP、反刷审计 |
|||
|
|||
#### 防刷审计 |
|||
|
|||
仅 ADMIN 可见： |
|||
|
|||
```text |
|||
GET /admin/scoring/risk/overview |
|||
GET /admin/scoring/risk/trend |
|||
GET /admin/scoring/risk/distribution |
|||
GET /admin/scoring/risk/events |
|||
GET /admin/scoring/rules |
|||
PUT /admin/scoring/rules/{id} |
|||
``` |
|||
|
|||
禁止返回原始手机号、IP、设备指纹、密码、Token 等敏感信息。 |
|||
|
|||
建议表： |
|||
|
|||
```text |
|||
scoring_risk_events |
|||
scoring_rule_configs |
|||
scoring_risk_actions |
|||
``` |
|||
|
|||
#### 公平性检测 |
|||
|
|||
第一阶段做统计检测： |
|||
|
|||
- 不同群体平均分差异； |
|||
- 通过率差异； |
|||
- 排名差异； |
|||
- 样本不足提示； |
|||
- 异常分布提示。 |
|||
|
|||
#### SHAP/规则解释 |
|||
|
|||
先实现确定性规则解释，不让前端依赖 AI 模型结果： |
|||
|
|||
```json |
|||
{ |
|||
"dimension": "EDUCATION", |
|||
"reasons": [ |
|||
"学历字段完整", |
|||
"学校信息缺失", |
|||
"毕业年份有效" |
|||
] |
|||
} |
|||
``` |
|||
|
|||
### 阶段 6：企业运营模块 |
|||
|
|||
开发顺序： |
|||
|
|||
1. 企业评价管理； |
|||
2. 企业评价回复； |
|||
3. 运营规则配置； |
|||
4. 企业人才推荐； |
|||
5. 推荐理由和解释； |
|||
6. 企业运营数据增强。 |
|||
|
|||
### 阶段 7：AI 和增值功能 |
|||
|
|||
- AI 简历诊断； |
|||
- AI 简历优化； |
|||
- AI 模拟面试； |
|||
- 面试题预测； |
|||
- 行业技能词云； |
|||
- 入职准备清单； |
|||
- 公司知识介绍； |
|||
- 简历查重； |
|||
- 诚信积分； |
|||
- 消息撤回。 |
|||
|
|||
## 7. 总体优先级 |
|||
|
|||
| 优先级 | 模块 | |
|||
|---|---| |
|||
| P0 | CandidateFeedback 脱敏 | |
|||
| P0 | 隐私设置 | |
|||
| P0 | 账号注销 | |
|||
| P0 | 个人数据导出 | |
|||
| P0 | 结构化面试评分 | |
|||
| P0/P1 | 同岗位竞争力排名 | |
|||
| P1 | 霍兰德和四维能力测评 | |
|||
| P1 | 统一求职进度 | |
|||
| P1 | 企业评价管理 | |
|||
| P1 | 企业人才推荐 | |
|||
| P1 | 公平性检测 | |
|||
| P1 | ADMIN 防刷审计 | |
|||
| P2 | SHAP 高级解释 | |
|||
| P2 | AI 简历、AI 模拟面试 | |
|||
| P2 | 技能词云、入职清单、诚信积分 | |
|||
|
|||
## 8. 每个模块的统一交付要求 |
|||
|
|||
每个模块必须交付： |
|||
|
|||
1. 接口设计； |
|||
2. 请求和响应 DTO； |
|||
3. Controller； |
|||
4. Service； |
|||
5. Repository； |
|||
6. Flyway 迁移； |
|||
7. 错误码； |
|||
8. 权限矩阵； |
|||
9. 脱敏规则； |
|||
10. 幂等设计； |
|||
11. 并发控制； |
|||
12. Service 单元测试； |
|||
13. MockMvc 测试； |
|||
14. 持久化测试； |
|||
15. Docker/MySQL 黑盒验收； |
|||
16. OpenAPI 更新； |
|||
17. 前端联调文档； |
|||
18. 已验收模块回归测试。 |
|||
|
|||
## 9. 第一阶段执行指令 |
|||
|
|||
下一步只执行 CandidateFeedback 脱敏，不开发隐私设置、面试评分或同岗位排名。 |
|||
|
|||
```text |
|||
当前先修复已有 CandidateFeedback 接口的响应脱敏问题，不开发新业务模块。 |
|||
|
|||
问题： |
|||
CandidateFeedback 当前响应包含 companyUserId、studentUserId 等内部身份字段，不符合前端契约和数据脱敏要求。 |
|||
|
|||
要求： |
|||
1. 先检查 CandidateFeedbackController、CandidateFeedbackService、现有 View/DTO、Repository、测试和 OpenAPI。 |
|||
2. 新增白名单 CandidateFeedbackResponse DTO。 |
|||
3. 保持现有接口路径、请求参数、权限、错误码和数据库结构不变。 |
|||
4. 学生和企业响应都不得返回 companyUserId、studentUserId、phone、email、passwordHash、resumeUrl。 |
|||
5. 不修改 candidate_feedback 表。 |
|||
6. 不新增 Flyway。 |
|||
7. 不启动或停止 Docker。 |
|||
8. 补充 COMPANY、STUDENT、其他学生、其他企业、未登录和脱敏测试。 |
|||
9. 更新 OpenAPI response schema 和 frontend-integration.md。 |
|||
10. 执行 CandidateFeedback 专项测试、mvn test、mvn clean verify、python docs/verify_openapi.py。 |
|||
11. 完成后停止，不要继续开发隐私设置、面试评分或同岗位排名。 |
|||
|
|||
最后只输出：修改文件、测试结果、OpenAPI 路径数、脱敏验证结果、是否还有问题、等待下一步指令。 |
|||
``` |
|||
|
|||
## 10. 变更控制 |
|||
|
|||
未经负责人再次确认，不得： |
|||
|
|||
- 修改已验收接口的响应语义； |
|||
- 将 `skills` 从 String 改成数组； |
|||
- 把 CandidateFeedback 当作面试评分； |
|||
- 把 `/resume-export-tasks` 当作个人数据导出； |
|||
- 把 percentile 当作同岗位排行榜； |
|||
- 把评价审核当作完整防刷审计； |
|||
- 让 COMPANY 查看防刷审计报告； |
|||
- 新增未批准的 Flyway； |
|||
- 删除或清理业务数据； |
|||
- 启动或停止 Docker。 |
|||
请勿在本目录维护第二份路线图，以避免接口、测试和发布基线发生漂移。 |
|||
|
|||
Loading…
Reference in new issue