lxq/docs/backend-development-roadmap.md

职来后端后续开发规划与 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	139 paths、178 operations（N05 新增 4 paths / 6 operations）
Flyway	V1–V41 已存在（N04 新增 V38–V39；N05 新增 V40–V41）
全量测试	1516 个执行：1505 通过、2 失败、9 错误；失败仍集中在既有 CareerProgress、JobReviewDimension、LocalResumeStorage 测试，薪资专项 24/24 通过
已完成范围	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、V34 统一求职进度聚合，N04 入职清单与公司知识介绍，以及 N05 薪资计算器与历史记录；另含认证、资料、岗位、投递、面试、Offer、看板等核心闭环
当前结论	N05 薪资计算器已完成代码、24/24 专项测试和 OpenAPI/文档更新；N04 仍待真实 MySQL/Docker 验收，N05 也需补齐真实 MySQL 黑盒验收
本规划范围	代码修复、新功能开发、接口契约、数据权限和治理能力

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、V34 统一求职进度聚合
已完成、待真实 MySQL/Docker 验收	N04 入职清单与公司知识介绍（V38/V39，9 个接口；专项测试 96/96） N05 薪资计算器（V40/V41，6 个接口；专项测试 24/24，347 个城市为 PROVINCE_FALLBACK）
已设计未编码	测评系统（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*	已完成
入职清单与公司知识介绍	/onboarding/**（9 个接口）	实现完成，待真实 MySQL/Docker 验收
薪资计算器	/salary-calculator/**（6 个接口）	实现完成，待真实 MySQL/Docker 验收

4.2 部分完成或口径不一致

Figma 页面/功能	当前实现	差距
同岗位竞争力排名	GET /jobs/{jobId}/competition-ranking 已实现	已交付；最终口径：WITHDRAWN/REJECTED 退出候选人池（请求 403/2002）；无评分但有效投递返回 200 + null 分数；Top5 匿名。不宣称"支持隐私退出"
求职进度	GET /profile/me/career-progress（V34）已实现	已交付统一求职进度聚合接口（只读，含竞争力摘要与待办/通知计数）
Offer 对比	/offers/compare 返回 Offer 字段	综合薪资、福利、发展空间当前由前端展示，后端不计算综合结论
HR 评价详情	candidate_feedback 已实现	不是结构化面试评分
企业评价管理	有评价审核和管理员决策	缺企业端评价管理、回复和运营动作
企业人才推荐	有候选人列表和评分	缺推荐排序、推荐理由和可解释结果
运营规则配置	Figma 有页面	后端暂无规则配置接口
防刷审计报告	已有评价审核基础能力	不是风险等级、风险趋势、风险分布和事件审计报告

4.3 完全缺失

• 霍兰德职业兴趣测评；
• 四维能力测评；
• 测评结果和测评岗位推荐；
• AI 简历诊断和优化；
• AI 模拟面试和面试题预测；
• 行业技能词云；
• 薪资参考和行业薪资大数据；
• 公平性检测；
• SHAP/规则解释；
• ADMIN 防刷审计和规则配置；
• 诚信积分和激励。
• 已非缺失（已实现）：个人数据导出（V30）、隐私设置（V27）、账号注销（V28/V29）、举报与屏蔽（V33）、结构化面试评分（V31）、同岗位竞争力排名（V32）、统一求职进度聚合（V34）、入职清单和公司知识介绍（N04）、薪资计算器与历史记录（N05）。

5. 已有代码的优先修复项

5.1 CandidateFeedback 响应脱敏（第一项）

当前反馈响应不能向前端暴露以下字段：

• companyUserId；
• studentUserId；
• phone；
• email；
• passwordHash；
• resumeUrl。

建议使用白名单响应 DTO：

{
  "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：隐私设置

接口：

GET /profile/me/privacy
PUT /profile/me/privacy

落地现状（V27 Privacy 已实现，真实能力仅两项）：

• resumeVisibility（简历可见性）；
• contactVisible（企业是否可联系）。

以下为未来“企业人才推荐/细粒度授权”设计项，尚未实现，不得伪称已提供：

• 退出同岗位排名；
• 退出企业人才推荐。

⚠️ V27 隐私设置接口已验收；后续如需新增“退出同岗位排名 / 退出企业人才推荐”，属于新设计，需随“企业人才推荐/细粒度授权”一并评审，不得在未开发前宣称已支持。

建议表和迁移（如未来扩展）：

student_privacy_settings
（V27 已落地，未新增字段）

模块 1.2：账号注销

接口：

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：个人数据导出

接口：

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、验证码等认证敏感信息。

建议表和迁移：

personal_data_export_tasks
V28__personal_data_export.sql

阶段 2：结构化面试评分

结构化面试评分独立于 candidate_feedback。

接口：

POST /interviews/{interviewId}/score
GET /interviews/{interviewId}/score
PUT /interviews/{interviewId}/score
GET /interviews/{interviewId}/score/history

权限：

角色	权限
COMPANY	本企业面试可创建、修改、查看
STUDENT	只能查看本人面试评分
ADMIN	只读审计
其他用户	403

建议表和迁移：

interview_scores
interview_score_history
V29__interview_scoring.sql

阶段 3：同岗位竞争力排名

接口：

GET /jobs/{jobId}/competition-ranking

必须支持：

• 当前学生在指定岗位的排名；
• cohort 总数；
• 百分位；
• 维度百分位；
• Top 候选人；
• 改进建议；
• 样本不足；
• 无评分候选人；
• 投递状态过滤（WITHDRAWN/REJECTED 退出候选人池，请求返回 403/2002）；
• 候选人信息脱敏。

必须复用：

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. 根据测评结果推荐岗位。

建议接口：

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

建议表：

assessment_definitions
assessment_questions
assessment_attempts
assessment_answers
assessment_results

建议迁移：

V30__assessment.sql

阶段 5：公平性、SHAP、反刷审计

防刷审计

仅 ADMIN 可见：

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 等敏感信息。

建议表：

scoring_risk_events
scoring_rule_configs
scoring_risk_actions

公平性检测

第一阶段做统计检测：

• 不同群体平均分差异；
• 通过率差异；
• 排名差异；
• 样本不足提示；
• 异常分布提示。

SHAP/规则解释

先实现确定性规则解释，不让前端依赖 AI 模型结果：

{
  "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	统一求职进度（V34 已完成）
P1	企业评价管理
P1	企业人才推荐
P1	公平性检测
P1	ADMIN 防刷审计
P2	SHAP 高级解释
P2	AI 简历、AI 模拟面试
P2	技能词云、入职清单（N04 实现完成，待验收）、诚信积分

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 脱敏阶段的历史执行指令，不代表当前待办，后续开发以本路线图的“未开发/已设计未编码”分类为准。

当前先修复已有 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。