diff --git a/docs/backend-development-roadmap.md b/docs/backend-development-roadmap.md new file mode 100644 index 0000000..05bbe23 --- /dev/null +++ b/docs/backend-development-roadmap.md @@ -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。 diff --git a/mydreamjob-server/docs/backend-development-roadmap.md b/mydreamjob-server/docs/backend-development-roadmap.md index 2ecb4ef..120326c 100644 --- a/mydreamjob-server/docs/backend-development-roadmap.md +++ b/mydreamjob-server/docs/backend-development-roadmap.md @@ -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。 +请勿在本目录维护第二份路线图，以避免接口、测试和发布基线发生漂移。