# 职来后端后续开发规划与 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 | **148 paths、182 operations** |
| Flyway | **V1–V36 已应用**；**V34 为 RIASEC 测评迁移（功能版本 V35）**；**V35 为四维能力测评迁移（功能版本 V36）**；**V36 为防刷风险概览与规则配置迁移（功能版本 V37）** |
| 全量测试 | **1389/1389 通过**（`mvn clean verify`，0 Failures / 0 Errors / 0 Skipped） |
| 已完成范围 | 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 统一求职进度聚合、**V35 RIASEC 职业兴趣测评（Flyway V34，已真实验收）**、**V36 四维能力测评（Flyway V35）**、**V37 防刷风险概览与运营规则配置（Flyway V36）**，及认证、资料、岗位、投递、面试、Offer、看板等核心闭环 |
| 当前结论 | V35 已通过真实 MySQL/Docker 验收（PASS=39/FAIL=0/SKIP=1；唯一 SKIP 为验收库无 INACTIVE 定义）。**V36 四维能力测评已通过真实 MySQL/Docker 验收（PASS=93/FAIL=0/SKIP=0）；V37 防刷风险治理已通过真实 MySQL/Docker 验收（PASS=76/FAIL=0/SKIP=0）。** V37 修复前 4 条 `RISK_EVENT_DETECTED.entity_id=NULL` 审计只作历史观察项，不回填、不影响修复后验收。运行时/静态 OpenAPI 均为 148/182，风险扫描不写候选评分引擎。 |
| 本规划范围 | 代码修复、新功能开发、接口契约、数据权限和治理能力 |

### 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 统一求职进度聚合、**V35 RIASEC 职业兴趣测评（Flyway V34，PASS=39/FAIL=0/SKIP=1）**、**V36 四维能力测评（Flyway V35，PASS=93/FAIL=0/SKIP=0）**、**V37 防刷风险概览与运营规则配置（Flyway V36，PASS=76/FAIL=0/SKIP=0）** |
| 已完成、待真实 MySQL/Docker 复验 | — |
| 已设计未编码 | 公平性检测、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 匿名。不宣称"支持隐私退出" |
| 求职进度 | `GET /profile/me/career-progress`（V34）已实现 | 已交付统一求职进度聚合接口（只读，含竞争力摘要与待办/通知计数） |
| Offer 对比 | `/offers/compare` 返回 Offer 字段 | 综合薪资、福利、发展空间当前由前端展示，后端不计算综合结论 |
| HR 评价详情 | `candidate_feedback` 已实现 | 不是结构化面试评分 |
| 企业评价管理 | 有评价审核和管理员决策 | 缺企业端评价管理、回复和运营动作 |
| 企业人才推荐 | 有候选人列表和评分 | 缺推荐排序、推荐理由和可解释结果 |
| 运营规则配置 | V37 `GET/PUT /admin/scoring/risk/rules` 已实现 | 仅 ADMIN；当前为确定性拒绝型安全审计规则，不做自动处置 |
| 防刷审计报告 | V37 风险概览、趋势、分布、事件与人工状态操作已实现 | 仅 ADMIN；不返回主体身份、原始审计内容、IP/UA 或凭据 |

### 4.3 完全缺失

- ~~霍兰德职业兴趣测评~~（已由 V35 实现：测评 + 结果 + 探索方向，Flyway V34）；
- ~~四维能力测评~~（已由 V36 实现：限时答题、进度保存、结果、短板和历史，Flyway V35）；
- 测评岗位推荐（V35/V36 已提供结果，但不根据结果推荐岗位，仍为缺失）；
- AI 简历诊断和优化；
- AI 模拟面试和面试题预测；
- 行业技能词云；
- 入职准备清单和公司知识介绍；
- 薪资计算器和薪资参考；
- 公平性检测；
- SHAP/规则解释；
- ~~ADMIN 防刷审计和规则配置~~（已由 V37 实现：仅 ADMIN 的确定性风险概览、规则配置和人工处置，Flyway V36）；
- 诚信积分和激励。
- 已非缺失（已实现）：个人数据导出（V30）、隐私设置（V27）、账号注销（V28/V29）、举报与屏蔽（V33）、结构化面试评分（V31）、同岗位竞争力排名（V32）、统一求职进度聚合（V34）、RIASEC 职业兴趣测评（V35）、四维能力测评（V36）、ADMIN 防刷审计与规则配置（V37）。

## 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. ~~霍兰德职业兴趣测评~~（V35 已完成）；
2. ~~四维能力测评、答题和进度保存~~（V36 已完成）；
3. ~~测评结果~~（V35/V36 已完成）；
4. 测评结果进入 ABILITY/GROWTH（需独立评审，当前未接入评分引擎）；
5. 根据测评结果推荐岗位。

建议接口：

```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、反刷审计

#### 防刷审计（V37 已完成）

仅 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/risk/rules
PUT /admin/scoring/risk/rules/{ruleCode}
POST /admin/scoring/risk/events/{eventId}/actions
```

禁止返回原始手机号、IP、设备指纹、密码、Token 等敏感信息。

建议表：

```text
scoring_risk_events
scoring_rule_configs
scoring_risk_actions
scoring_risk_scan_checkpoints
```

#### 公平性检测

第一阶段做统计检测：

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

#### 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 | 统一求职进度（V34 已完成） |
| P1 | 企业评价管理 |
| P1 | 企业人才推荐 |
| P1 | 公平性检测 |
| P1 | 公平性检测 |
| 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。