# AI-004 简历模块批量AI优化实现方案

版本：v1.1；日期：2026-10-29（Asia/Shanghai）；状态：2026-10-29用户已批准执行，并明确三个总入口绑定同一流程；本批后端复核及对接文档已交付，未修改代码，前端实施和联调待完成。

本版整体替代v1.0。为保留已有文档链接，沿用文件名“AI-004-整份简历AI一键优化-实现方案.md”，正文以本版模块批量编排为准；v1.0的整份草稿、整份模型调用、新增整份提示词、技能优化及两个新接口全部撤回，不属于本版范围。

## 1. 页面事实与目标

用户提供的两张页面设计图表明：简历按基本信息、求职意向、教育、工作、实习、项目、技能、自评和附件分模块展示及编辑；工作、实习已有AI优化入口，自评有AI润色入口。项目为空时未展示AI按钮，项目优化能力依据现有AI-003代码核查，不从截图推断已完成联调。技能只有添加入口，本任务不新增技能AI能力。

按用户明确说明，“优化简历”和底部“AI一键优化”是同一功能。用户已明确页面中间的“一键全部优化”入口也绑定同一流程，三个入口不另外设计不同功能。简历评分“暂未开放”不属于本任务，不引入评分接口或把优化结果当分数。

目标是一次触发所有已接入AI优化模块的批量处理，各条目分别生成建议、分别展示，用户可以逐一确认、修改、采用或取消，保存沿用各模块现有流程。不存在整份简历编辑草稿前提；仅在用户查看/修改某项建议时产生该模块临时待确认内容。

## 2. 建议实现与取舍

推荐第一版采用“前端统一队列，复用现有模块接口”。业务上一次启动全部优化，执行上依次调用、逐项返回，不将“同时调用”实现为无上限并发。理由是现有后端真实模型限流器对同一用户仅允许一个在途调用，直接Promise.all会使多数请求429；工作经历默认每分钟3次、每天20次，长队列也可能触发额度。第一版不为此调整旧限额或改变其他AI功能。

每次批量处理按页面顺序建立固定条目清单：工作经历→实习经历→项目经历→自我评价。同一模块多条经历逐条处理，结果携带前端已有条目映射，不合并多条正文交给单段接口。任务执行顺序不代表展示优先级，前端可边显示结果边处理下一项，用户不必确认完第一项才允许生成下一项。

本方案不新增后端批量路由、任务表、轮询接口或SSE；不在后端通过HTTP调用自己。直接复用原AI服务及提示词可避免重写一套语义、隐私校验和保存逻辑。后续若明确要求退出页面继续运行、后台任务恢复、服务端统一调度或大量条目快速处理，再单独设计后端批量任务，不提前建设。

代价：队列由前端负责人实现；页面关闭不保证继续，已发出的外呼不保证取消或退费；多条调用有多次耗时和成本，不能宣传一次总调用或无限次数。本工作区提供契约、批量规则和联调支持，不修改前端代码。

## 3. 后端复用清单与当前状态

实际Git开发仓库：D:/巴适/轻松聘-ai智能助手；本轮只读核查HEAD为ff52692，有AI-003未提交生产/测试/契约文件，不覆盖或清理。工作区zhangshun是较旧参考副本。正式开发前复核分支、指引和既有修改。

| 页面模块 | 复用POST（均加/api/v1） | 当前限制与状态 |
| --- | --- | --- |
| 工作经历 | /profile/me/work-experience-optimization | position≤100、description非空≤3000、targetPosition≤100；已有代码 |
| 实习经历 | /profile/me/work-experience-optimization | 同样是经历描述优化；保留原experienceType=INTERNSHIP和原条目身份，不另建实习AI服务 |
| 项目经历 | /profile/me/project-experience-optimization | description非空≤5000；projectName≤150、role≤120、targetPosition≤120；AI-003候选实现待验收 |
| 自我评价 | /profile/me/self-evaluation-optimization | description非空≤5000、targetPosition≤120；AI-003候选实现待验收 |

每条POST对应GET同路径/notice。全部使用现有Authorization: Bearer <access-token>，仅STUDENT本人；不传userId。使用现有ApiResponse，code/message/data/requestId/timestamp。同步JSON，无分页、无流式输出。

工作/实习字段与在线简历字段上限不完全一致（原position允许120、描述5000，AI仅100/3000）；批量调用不能截断或绕过校验。超出原AI预算的条目标记“内容超限，需单独调整后优化”，保留原文，其他合法项继续。若产品要求所有现有合法长度都能优化，必须单独修改旧AI契约并审批，不在本版暗改。

项目与自评已有候选实现并不代表完成交付：工作记录中AI-003有测试设施问题和待批准修复。本版不替代该审批，也不在未验收时把入口标记可用。批量上线以相关模块实际可用为前提。

## 4. 调用、告知和返回示例

本版无新增或修改后端接口。以下为复用契约的合成示例，不是新批量请求。

工作/实习请求：
```json
{"position":"后端开发实习生","description":"参与订单查询接口开发，补充接口测试。","targetPosition":"Java后端开发","externalProcessingConsent":true,"consentNoticeVersion":"work-experience-external-processing-v2"}
```
实际工作经历告知版本以GET /notice返回为准，客户端不硬编码本示例。

项目请求：
```json
{"projectName":"课程商城","role":"参与开发","description":"使用Java实现订单查询接口，尚未上线。","targetPosition":"Java后端开发","externalProcessingConsent":true,"consentNoticeVersion":"project-experience-external-processing-v1"}
```
自评请求：
```json
{"description":"学习Java和SQL，在课程项目中编写接口测试。","targetPosition":"Java后端开发","externalProcessingConsent":true,"consentNoticeVersion":"self-evaluation-external-processing-v1"}
```
成功响应示例：
```json
{"code":200,"message":"ok","data":{"status":"OPTIMIZED","optimizedDescription":"参与订单查询接口开发，并补充接口测试。","suggestions":[],"followUpQuestions":[],"promptVersion":"work-experience-deepseek-v2","simulated":false},"requestId":"example","timestamp":"2026-10-29T02:00:00Z"}
```
status、promptVersion与simulated以实际各模块返回为准；NEED_MORE_INFO时展示followUpQuestions，不采用空正文；simulated=true须标模拟，不宣称真实优化完成。实际工作经历schema和告知版本在交付前按对应源码/OpenAPI再次核对。

批量开始先获取清单涉及场景的notice，按场景展示用途、供应商、外传字段和当前版本。本次可以在一个清晰的确认界面列出全部条目及涉及场景，用户明确同意本次列出的处理后，逐条附带对应版本和原生布尔true；不能把一次同意变成长期授权，不包含后续新增条目。跨场景版本不能混用，过期时暂停受影响项并重新告知。告知是否允许统一批次确认还需核对现有各场景正式告知措辞；不能默默改变“每次调用确认”的既有约定。前端可先采用逐项确认，待告知条款确认后使用批次确认。

不传姓名、电话、邮箱、附件、账号信息或整份简历；项目名可用脱敏代称，正文不得包含凭据或他人资料。保留现有输入安全和输出校验，不新增提示词或供应商。真实模式仍以前置授权及供应商处理政策核实为开放条件，不默认用真实用户数据试验。

## 5. 批量流程与结果确认

1. 从当前页面已经读取的模块数据建立本次清单；必要时沿用原读取接口刷新，避免强制进入整份编辑。记录条目id、模块、原描述及当前版本供前端关联，不把这些身份字段强塞给现有AI DTO。
2. 只包含已接入AI的工作/实习/项目/自评。空模块、正文为空和“无”等无事实占位内容不自动生成，提示补充或标记跳过；不凭其他模块信息擅自生成空自评。未来跨模块生成是另一个契约。
3. 展示本次条目数量、外部处理告知及可能多次调用，用户启动后锁定批次清单。顶部、底部和中间总入口共用一个运行状态，避免重复创建队列；单项按钮与批量请求也需协调，避免同用户并发触发429。
4. 每完成一条立即显示原文/优化建议/补充问题，允许用户查看、修改、采用、取消；后台继续下一合法条目。不能只有最后全部结束才展示，也不把一个失败视为全批失败。
5. 采用前核对目标条目仍存在且描述仍与提交时一致；用户期间编辑、删除或切换条目时标记结果过期，不能按数组下标回填。临时关联对象仅存在前端，不新增后端历史表。
6. 采用后进入该模块原有编辑/保存流程。工作/实习/项目只修改description，自评修改selfEvaluation，保留其他字段。用户继续编辑后再保存，或沿用原页面明确的确认保存动作。
7. 原条目PUT为完整替换，要保留完整条目、id、experienceType、日期和最近revision；自评若沿用原整份保存工具，须由原工具保留其他模块，不能只提交selfEvaluation造成字段清空。任何新保存接口或改变原保存语义都不属于本任务。
8. 多项采用保存必须协调同一份在线简历的revision：每次成功后更新本地版本，再保存下一项，不能让所有保存使用同一个旧revision。409/6002保留待确认内容、重新读取并让用户处理冲突，不自动换版本覆盖。

逐一确认是交互要求，不要求模型输出每个token实时返回；复用单条HTTP响应即可实现逐项展示。

## 6. 失败、额度与取消规则

前端本地状态建议：待处理、处理中、待确认、需补充、已跳过、失败、已取消；属于队列展示状态，不冒充后端新增status。用户确认及保存状态与生成状态分别记录，生成成功不等于采用或保存。

单项400标记失败并继续其他合法项；502/504保留原文、允许用户单独重试，不自动再次计费；401停止队列走原登录流程；403停止并提示权限；503暂停并提示服务/模块不可用，不持续外呼。429停止当前自动派发，展示Retry-After和已完成结果，后续由用户选择继续，避免紧密循环重试；日额度耗尽不承诺等60秒一定恢复。重试与继续应覆盖当次有效告知范围，必要时重新确认。

空模块跳过；单项没有结果不影响已有建议；用户取消停止未开始的请求，已返回建议可保留供本人确认，但不继续自动调用。页面离开时停止调度，不承诺后台持续运行。前端不得为了避免429另换入口或账号，也不降低旧限流。

本版复用原模型调用、限流、输入校验和提示词，原单项契约不变；批量触发仍会消耗共享额度，属于必须明确的资源影响。无法在不改限额的前提下承诺任意多条一次点击全部成功；页面需要显示完成数、失败数和待处理数。

## 7. 文件、配置和职责范围

当前批次仅修订根文档和工作记录，不改生产/测试代码；无数据库、依赖、配置、外部服务、提示词或接口变化，无文件删除。

本轮实际修改：
- D:/巴适/轻松聘/docs/AI-004-整份简历AI一键优化-实现方案.md：v1.1整体替代旧设计。
- D:/巴适/轻松聘/工作记录.txt：追加本次纠正、证据和状态。

方案确认后后端侧拟交付：
- docs/AI-004-简历模块批量AI优化-前端对接方案.md：模块映射、请求示例、队列/采用/保存约束、错误与额度处理。
- docs/AI-004-简历模块批量AI优化-后端整合说明.md：现有接口复用、实际依赖状态、测试与联调证据、不新增代码的说明。

前端负责人实施统一队列、入口绑定、进度、逐项确认及原保存调用，本工作区不列出未知前端文件名，不要求完整前端仓库作为文档交付前置。待前端提供必要调用片段或契约后可继续核对。

AI-003修复/验收按其独立方案处理。本版不新增ResumeOptimization*生产类，不修改旧客户端、全局认证、评分、保存服务或OpenAPI；后续核查如发现确有后端缺口，先列明精确文件、影响和方案再审批。

## 8. 验证、验收与回滚

本轮已核对用户页面及说明、原在线简历分模块结构和保存契约、现有工作经历请求DTO、项目/自评场景类型。纯文档不运行整套后端测试；未调用模型，未开展页面联调或真实Redis/MySQL验收，不沿用历史通过数量宣称本次通过。

后续联调重点：总入口触发同一队列；工作与实习条目正确映射；多条逐项返回；空模块跳过；单项失败保留其他结果；429暂停；取消停止新派发；重复点击不重复调用；用户编辑/删除后旧结果不覆盖；逐项编辑/采用/保存使用原工具及正确revision；刷新后读取与用户确认一致；原单项AI按钮及其他业务行为保持。

AI-003测试、模型质量和供应商告知核实分别有证据才标通过，不用前端队列掩盖后端未交付状态。真实评测使用合成样本，需记录提示词/模型版本、事实漂移、延迟和调用消耗。

回滚由前端移除总入口队列绑定、恢复既有入口行为，保留单项AI和原保存；后端无新增表或代码需要回滚。不删除已经由用户确认保存的内容。任何后续代码批次按AGENTS.md先方案审批。

## 9. 本版结论与审批范围

“优化简历”“AI一键优化”（建议包括“一键全部优化”）统一为已有AI模块的批量入口，各条目复用原接口与提示词，逐条生成、逐条确认、允许修改、原工具保存。技术上采用受控串行队列，避免现有同用户并发限制导致大量失败。

本版取代v1.0，用户已批准执行并确认三个入口共用流程。批准本版不等于授权修改前端或修复AI-003；后端若无需新增代码，则主要交付对接契约和联调支持，不为了制造新接口重复建设。尚待确认的是前端原保存调用细节、批次告知措辞与AI-003最终可用状态，不阻塞当前方案修订。


## 10. 2026-10-29执行与交付记录

用户明确批准执行v1.1，并确认“一键全部优化”也绑定同一流程。按本版无新增后端代码的范围完成实际接口、告知、DTO、限流和保存契约复核，并生成同编号前端对接方案和后端整合说明。

复核纠正：工作经历当前告知版本为work-experience-external-processing-v2，前端必须读取notice.data.version；现有响应只支持OPTIMIZED/NEED_MORE_INFO，不使用v1.0的UNCHANGED；现有告知逐次同意，交付默认逐项明确授权，不把总入口点击当作所有外传同意。串行仍可能达到每分钟配额，对接文档补充默认额度下的调用节奏及429暂停/手动继续。

2026-10-29实际仓库运行python ./docs/verify_openapi.py，退出码0，217 paths/265 operations，All checks passed。此为静态验证，不是HTTP/页面验收。本轮未运行Maven、未启动服务、未调用模型、未改代码或配置、未提交推送部署。

交付：docs/AI-004-简历模块批量AI优化-前端对接方案.md、docs/AI-004-简历模块批量AI优化-后端整合说明.md。后端复核/文档范围已完成；前端三个按钮绑定、队列、联调、AI-003独立修复验收和真实模型生产放行仍未完成，不能标成页面功能已经上线。