# AI-004 简历模块批量 AI 优化后端整合说明

日期：2026-10-29（Asia/Shanghai）；对应方案：AI-004 v1.1，用户已批准，并确认“优化简历”“AI一键优化”“一键全部优化”绑定同一流程。

本批后端侧交付为接口复核与对接契约：复用已有工作/实习、项目、自评AI接口，由前端统一队列逐条处理和确认。无新增后端生产/测试代码、数据库、依赖或配置，不能将本说明解释为前端已绑定、服务已部署或AI-003已经验收。

## 1. 仓库、结构与依赖状态

实际开发仓库：`D:/巴适/轻松聘-ai智能助手`；本轮核查HEAD为 `ff52692`（合并整合分支的既有提交）。根工作区 `D:/巴适/轻松聘/zhangshun` 为历史参考副本，不是本次代码整合目标。本轮未切换分支、fetch、合并、暂存、提交、推送或部署。

现有包 `mydreamjob-server/src/main/java/com/mydreamjob/resume/optimization/` 负责模型建议：WorkExperienceOptimizationController/Service及相关DTO处理工作和实习；ResumeSectionOptimizationController/Service及相关DTO处理项目与自评；各自Router、ModelClient、提示词处理建议；共享WorkExperienceCallLimiter负责真实调用原子额度和并发租约。

`onlineresume/OnlineResumeController`、`OnlineResumeService`、`OnlineResumeContent`、`OnlineResumeSaveRequest` 提供既有本人简历读取、条目及完整保存、revision并发控制。AI不写入这些服务，也不替代原评分、权限或保存逻辑。

仓库进入本任务前已有AI-003未提交文件（ResumeSection生产代码、四份提示词、八份测试）及docs/openapi-rc.json、docs/resume-api.md、docs/verify_openapi.py修改。本任务保留这些状态；不得把“本次未改代码”误解为仓库原本干净。

工作记录及AI-003 v1.2文档显示，其首轮新测试有两项Mockito测试设施错误、Redis环境跳过及旧安全集成测试接口数量适配问题，补充修复尚待单独审批。本批不修复、不提交这些文件，不冒充AI-004依赖已验收。

## 2. 接口与复用边界

AI路由均使用现有 `/api/v1/profile/me` 前缀和Bearer access-token、STUDENT本人权限：

- 工作/实习：GET `/work-experience-optimization/notice`，POST `/work-experience-optimization`。
- 项目：GET `/project-experience-optimization/notice`，POST `/project-experience-optimization`。
- 自评：GET `/self-evaluation-optimization/notice`，POST `/self-evaluation-optimization`。

工作/实习告知当前为v2，项目/自评各为v1；前端必须取notice.data.version。三种POST返回OPTIMIZED/NEED_MORE_INFO、optimizedDescription、suggestions、followUpQuestions、promptVersion及simulated，不新增批量响应或UNCHANGED。请求上限、完整示例及错误详见同编号前端对接方案。

页面“同时优化所有模块”落实为一次启动队列，执行上同用户串行。工作和实习对应同一接口及同一原条目集合，必须去重。每项返回立即可供用户确认/编辑，某项失败不抹除其他结果；采用后走原模块保存。页面评分、技能、教育、附件不扩展。

现有工作AI position≤100、description≤3000，与在线简历position≤120、description≤5000有差异；保留旧契约，超长项提示调整。项目/自评description≤5000。不得静默截断或修改旧限制。

当前告知要求每次请求明确同意，交付默认逐项授权，不默认一次点击总按钮即同意所有外传。统一批次授权需另行明确正式告知，不能只改前端文案就绕过既有规则。

## 3. 配置、启动与数据

无新增配置、依赖、表、迁移或独立服务；没有新的启动命令。继续按实际仓库README配置Java17/Maven及原MySQL/Redis/RabbitMQ/JWT环境。本轮不启停基础设施、不开启真实模式、不展示或写入凭据。

沿用 `ai.work-experience.mode`、`ai.project-experience.mode`、`ai.self-evaluation.mode`，取off/stub/deepseek。真实模式要求对应real-enabled=true及原有DeepSeek配置；默认关闭，不能为联调自动打开真实模型。工作入口仍有旧stub-enabled兼容开关，优先明确mode避免歧义。

沿用DEEPSEEK_API_KEY、DEEPSEEK_MODEL、DEEPSEEK_TIMEOUT_SECONDS，本轮不调整或核验型号能力和价格。供应商留存、训练用途及正式授权仍需既有开放流程核实。

限额继续取 `ai.work-experience.limits.*`，默认user-per-minute=3、user-per-day=20、global-per-day=200、global-concurrency=4，单用户在途上限1；项目、自评、工作、实习共享。Redis固定UTC时间窗口计数不等于北京时间自然日；Retry-After=60不能表达日额度剩余。批量增加调用量，仍可能限制其他AI入口的可用次数；不承诺零资源影响。

没有AI正文持久化。前端临时建议仅保存在本次内存任务，用户确认并通过原保存接口写入后，按原在线简历数据政策处理。本批不新增历史、缓存或数据导出字段。

## 4. 原保存整合

沿用GET `/api/v1/profile/me/online-resume` 返回revision/content。工作、实习使用原 `PUT /api/v1/profile/me/online-resume/work-experiences/{id}`；项目使用project-experiences/{id}。请求revision+完整entry，不能只提交description。

自评没有独立self-evaluation条目保存接口；原工具若使用完整PUT，必须传完整content，只替换selfEvaluation。完整PUT是原业务契约，不代表本页面需要改成整份编辑；未知的前端封装不在本任务凭空重建。

多个模块共享revision，前端原保存必须串行并以每次返回值更新版本。409/6002保留人工修改并重新读取合并；404/6003不自动创建替代条目。用户生成期间编辑或删除条目时，旧结果须过期，不按数组下标覆盖。原experienceType、公司、岗位、日期及其他字段全部保留。

## 5. 本批文件与Gitea交付

实际文件均在工作区根 `D:/巴适/轻松聘`：

- docs/AI-004-整份简历AI一键优化-实现方案.md：v1.1批准状态、三个入口和本次执行记录；文件名保留原链接，正文为模块批量流程。
- docs/AI-004-简历模块批量AI优化-前端对接方案.md：本次新增，提供前端调用、授权、调度、逐项确认与原保存规则。
- docs/AI-004-简历模块批量AI优化-后端整合说明.md：本次新增，即本文件。
- 工作记录.txt：追加本次审批、变更、验证和待办，保留旧记录。

实际仓库无本批生产代码diff，因此没有AI-004代码分支或提交可以声称已合入。用户未要求本次上传、推送或合并；文档保存在根docs，交付时将三份AI-004文档作为同一组提供给负责人。需要同步到Gitea时，依当时明确指令精确选择文件，不能git add -A把AI-003候选改动一并带入。

## 6. 验证结果与整合顺序

2026-10-29在实际仓库执行 `python ./docs/verify_openapi.py`：退出码0，217 paths / 265 operations，All checks passed。同时按源码核对六条AI路由、notice版本、请求DTO及响应DTO、异常映射、限流默认值和保存控制器。静态校验包含AI-003候选契约，不等于运行时或部署验收。

本批仅文档，无需为其运行整套Maven；本轮未运行单元/集成测试、未启动HTTP服务、未外呼模型，未执行真实Redis/MySQL或前端页面验收。历史测试结果仍以AI-003记录为准，不能标成本轮通过。

建议负责人依次：

1. 确认要联调的后端版本已包含并完成AI-003独立修复/验收；保留现有个人分支和未提交差异。
2. 在团队可用测试环境按既有方式启动服务，先使用各场景stub，不自动开放真实模式。
3. 将同编号前端对接方案交给前端负责人，实现三个入口共用队列和逐条确认；本助手本轮未发送消息给其他人。
4. 验证六路由鉴权与响应、模块映射、超长项、逐次同意、429/超时/取消、原单项按钮和原保存revision冲突。
5. 页面确认后保存再打开回读，并核对原评分、附件和其他字段未被影响。
6. 真实模型质量、费用、耗时、供应商正式告知及生产放行单独记录；先用合成数据评测，不默认上传真实资料。

## 7. 冲突、回滚和未完成事项

潜在冲突为AI-003未完成验收、多人共享OpenAPI文档、前端全局revision更新及共享AI额度。本批没有修改共享生产代码或契约，不为此合并或清理旧差异。

前端回滚可移除批量总入口绑定、恢复原单项入口；保留原简历保存及用户已确认写入的数据。后端无本批迁移或新增代码需要回滚。

已完成的是AI-004后端复用复核和两份交付文档。尚未完成的是前端三个入口的实际绑定和队列、前后端联调、AI-003独立验收、真实模型评测及生产开放。前端负责人只需确认当前模块数据和保存工具的必要调用契约，不要求提供完整前端仓库；如发现必须改后端才能满足的缺口，按新的精确方案审批，不扩大本批范围。