lxq/docs/r01-a-request-context-implementation-instruction.md

R01-A 请求身份与 requestId 收束实施指令

一、任务性质

本轮只完成 R01-A 第一批，不进入异常映射、评分规则、百分位、消息未读、PersonalDataCollector 或推荐权重重构。

允许修改公共请求上下文组件、最多 8 个 Controller 及其测试和文档；禁止新增接口、ErrorCode、Flyway、表、索引或依赖。

二、开始前核查

在 C:\Users\15642\Desktop\zhilai 执行并记录：

git branch --show-current
git status --short
git diff --cached --name-only
git log -5 --oneline
git diff --check

分支必须为 refactor/r01-structure-performance，HEAD 必须包含 Q01 检查点 77dc624，暂存区必须为空。完整搜索适用的 AGENTS.md；保护全部历史未跟踪文件。

三、先写基线清单

列出所有私有 resolveUserId/userId/requireAdmin 与 requestId/getRequestId 方法，记录：文件、公开端点、当前异常、角色检查位置、资源归属检查位置、requestId 来源。

第一批只迁移以下 8 个 Controller：

1. AssessmentController
2. AbilityController
3. ProfileController
4. ResumeVersionController
5. PreferenceController
6. CompetitionRankingController
7. PersonalDataExportController
8. PrivacySettingsController

若其中存在与未提交修改重叠，停止并报告，不得改换到其它文件凑数。

四、身份组件

复用现有 CurrentUserAccessor，不要创建第二个身份解析器。Controller 通过构造器注入并调用 requireUserId()。

必须保持：

• null Authentication、AnonymousAuthenticationToken、anonymousUser、未认证、空白主体、Unicode 数字、带正负号、Long 溢出和 userId<=0 全部 401；
• 不回显主体内容、异常类或堆栈；
• 不接受请求参数中的 userId；
• 角色与资源归属仍由原 Service/Controller 的既有位置判断；
• 不将原 403 或 404 改成 401。

删除迁移 Controller 内的私有身份解析代码和不再使用的 SecurityContext 依赖。

五、requestId 组件

先完整阅读 common/logging/RequestIdFilter、RequestLoggingFilter、AuditContext 和 GlobalExceptionHandler。

新增 common/logging/RequestIdAccessor，提供 String get(HttpServletRequest request)。它必须复用过滤器产出的规范化 requestId；禁止重新生成第二个值，禁止直接信任超长/非法客户端头。

若 RequestIdFilter 当前没有 request attribute，允许增加一个常量属性并写入规范化后的值。响应头、MDC、Controller body、AuditContext 与异常响应必须保持同源。过滤器结束后仍清理 MDC。

只替换上述 8 个 Controller 的私有 requestId 方法。GlobalExceptionHandler 本轮只允许改为调用 accessor，不得重构 HTTP 状态映射。

六、必须先新增的测试

新增或加强：

• RequestIdAccessorTest
• RequestContextMigrationIntegrationTest
• 8 个 Controller 的既有权限回归

至少覆盖：

1. 合法客户端 requestId 原样使用；
2. 缺失、空白、超长、非法字符时使用过滤器规范化值；
3. 响应头、响应 body、MDC 日志与 AuditContext 同一值；
4. 并发请求不串 requestId；
5. 过滤器完成后 MDC 清理；
6. 八类非法 principal 均 401 而非 500；
7. 错误响应不包含 principal；
8. STUDENT/COMPANY/ADMIN 权限矩阵与改动前一致；
9. 拒绝请求无业务写入；
10. 反证：绕过 filter 直接传超长请求头时 accessor 不得返回原值。

禁止只 Mock 新组件后断言 Controller 返回 mock 值；至少一组测试必须使用真实 SecurityFilterChain、RequestIdFilter 和 MVC。

七、量化验收

整改前后分别统计：

rg -l "private (Long|long) resolveUserId|private .*userId\(\)" mydreamjob-server/src/main/java
rg -l "private String (getRequestId|requestId)\(" mydreamjob-server/src/main/java

第一批必须精确减少对应 8 个 Controller 的重复方法，不得声称全仓已完成。报告剩余数量和文件清单。

八、验证

依次运行定向测试、八个模块关联测试、mvn test、mvn clean verify、python ..\docs\verify_openapi.py、git diff --check。

预期 OpenAPI 保持 176/214；测试数量以实际为准，Failures=0、Errors=0、Skipped=0。

九、停止条件

完成 R01-A 第一批代码、测试和报告后停止。暂存区保持空；不得 commit/push；不得进入 R01-B/C/D/E。

最终状态只能写：

R01-A 第一批请求上下文收束完成，待独立代码复验。