2026-10-28-T29-B2-verification.md 13 KB

T29-B2 报告代传安全修复 — 独立核验报告(verification)

  • 核验对象:commit 751145b9d(feature/proxy-fix-b2-security,标题「T29-B2: 报告代传功能修复·第二批——权限越权与安全策略收敛 (B2-1~B2-6)」)
  • 核验基线:origin/cfclub(merge-base = cddcacd6e8246d76ea20d145a02a0898c85f7be0)
  • 规格依据:docs/superpowers/plans/2026-10-25-report-proxy-fix-plan.md §批次 B2(B2-1 ~ B2-6)
  • 核验方式:独立会话 —— 静态代码核查(codegraph/Read/diff)+ 单元测试 + 本地运行态实测(测试库 192.168.16.251:3306/zxyj)
  • 核验日期:2026-10-28
  • 总体结论:✅ B2-1 ~ B2-6 全部通过(代码级 + 测试级 + 运行态三向核验),无 P0;存在 1 项 P1 集成阻塞(非 B2 引入的合并冲突)与 3 项 P2 文档/一致性小问题(见「问题清单」)。

一、变更范围(diff 基线)

git diff --stat cddcacd6e 751145b9d → 13 文件,+893 / −37,全部为 B2 范围文件:

类别 文件
业务代码(7) FamilyAccessInterceptor.java、JwtInterceptor.java、HealthReportController.java、family/FamilyMembersController.java、FamilyMemberService.java、HealthReportService.java、UserService.java
测试(6) FamilyAccessInterceptorTest、JwtInterceptorLoginRequiredTest、HealthReportControllerProxyParseBindingTest、FamilyMembersControllerListTest、HealthReportServiceAuditConfirmTest、UserServiceEffectiveFamilyIdsTest
  • 无 DatabaseInitializer.java / schema.sql 变更 → B2 未引入任何 DB 迁移,符合规格「本任务不涉及新建表/迁移」。
  • 无 AGENTS.md 违规(接口统一 @PostMapping、MyBatis-Plus 参数化查询、@Resource 注入、未触碰 children 表废弃区)。

二、逐项验收表(B2-1 ~ B2-6)

# 验收项 结论 代码证据 运行态证据
B2-1 /api/family/member/list 支持 familyId + 行级隔离;删除 ensureUserFamily 静默建家庭 ✅ 通过 FamilyMembersController.listMembers(:63-94)经 ParamUtils.getLong 读 params.familyId → canAccessFamily()(:101-107,admin/operator/finance 直通,否则 getEffectiveFamilyIds(userId).contains(familyId) → 403「无权访问该家庭数据」);三个分支的 ensureUserFamily 调用全部移除;UserService.getVisibleMembers familyId 为 null → 空列表;FamilyMemberService.listMembersWithFamily → 空 map、listMembersOfFamily → 空列表 T1 空集用户 81315 + {"familyId":2009} → HTTP 403 {"code":403,"message":"无权访问该家庭数据"};T2 同用户不传 familyId → HTTP 200 {"code":200,"data":[]};T7 admin 1001 + {"familyId":2009} → 200 返回该家庭成员(平台直通)。查库:0 条 family 行以 81315 为 creator/teacher/butler,0 条 family_members 归属 81315,users.family_id 仍 NULL → 未建任何家庭行
B2-2 proxyParsePreview 显式 familyId 绑定校验(不依赖拦截器) ✅ 通过 HealthReportController.canProxyForFamily(userId, role, roles, familyId)(:2696)在角色校验 + null 校验之后、storeFile/createDraft 之前调用 → 不通过返回 Result.error("无权为该家庭代传报告")(code=500),无任何副作用 T5 未绑定 teacher 81315 multipart proxy-parse + familyId=2009:9083(enforcement)→ HTTP 403(拦截器层);9085(-Dfamily.access.mode=logging,暴露控制器层)→ HTTP 200 body {"code":500,"message":"无权为该家庭代传报告"} —— 第②层校验运行态实锤,且在 storeFile/建草稿前,无文件落盘
B2-3 proxyConfirm 校验草稿 familyId ↔ subjectId 归属一致 + 仅创建者/admin 可确认 ✅ 通过 HealthReportService.auditConfirm(draftId, subjectId, auditorId, isAdmin)(:2056):validateDraftOwnership(非 admin 必须 draft.getUserId() 相等 → IllegalArgumentException("无权确认他人创建的草稿"))+ validateSubjectFamily(family_members.family_id vs draft.familyId,users.id 路径经 resolveSubjectToMemberId → "所选成员不属于该草稿所属家庭");两校验均在任何写操作之前(:2063-2065 vs 写块 :2067+) T9a teacher 非创建者确认 draft 111 → {"code":500,"message":"确认失败: 无权确认他人创建的草稿"};T9b admin + 跨家庭 subjectId 1023(family 2)vs draft family 2009 → {"code":500,"message":"确认失败: 所选成员不属于该草稿所属家庭"};查库:draft 111 仍 pending、confirmed_report_id 仍 NULL,health_reports 无新增 → 校验先于写入
B2-4 FamilyAccessInterceptor 空有效家庭集拒绝;路由枚举逐条结论;回归不误伤无 familyId 请求 ✅ 通过 平台角色直通(`"admin".equals(role)
B2-5 proxy-parse / proxy-confirm 移入 LOGIN_REQUIRED_PATHS → 无 token 直接 401 ✅ 通过 JwtInterceptor.LOGIN_REQUIRED_PATHS(:85-86)已含 /api/health/report/proxy-parse 与 /api/health/report/proxy-confirm(该数组语义 = 无 token 直接 401) 无 token POST proxy-parse → HTTP 401 {"code":401,"message":"请先登录"};无 token POST proxy-confirm → HTTP 401(修复前为业务 code=500「无权限」)
B2-6 三层校验编排注释块 + 明确返回码 ✅ 通过 proxyParsePreview javadoc(:2712-2722)枚举:① 角色 isProxyUploader 失败 → code=500「无权限代上传报告…」;② familyId 绑定失败 → code=500「无权为该家庭代传报告」;③ 拦截器兜底 → HTTP 403 {"code":403,"message":"无权访问该家庭数据"} ①②③ 三层均已在运行态分别实测命中(T5 ②、T1 ③、无 token 401 为 B2-5 层),返回码与注释一致

补充核验:

  • 编译:mvn compile(cfc-backend,Java 8 + Spring Boot 2.7.18)→ BUILD SUCCESS(1955 源文件)。
  • 单元测试:6 个新增/扩展测试类 mvn test -DskipTests=false → Tests run: 37, Failures: 0, Errors: 0, Skipped: 0, BUILD SUCCESS(与 commit 声明一致)。
  • SQL 注入扫描:7 个业务变更文件的所有新增 DB 访问均为参数化 LambdaQueryWrapper(唯一常量 .last("LIMIT 20"));既有 JdbcTemplate 用法未被 diff 触碰 → 无注入面。

三、问题清单

级别 问题 说明 处置建议
P1 合并冲突(集成阻塞,非 B2 引入) merge-base 751145b9d vs origin/cfclub = cddcacd6e;COUPON-REG commit 055f6da25 是 origin/cfclub 祖先但不是 751145b9d 祖先,且改 UserService.java / DatabaseInitializer.java / schema.sql —— 与 B2 改动过的 UserService.java 直接冲突,另两文件因相邻上下文可能冲突 合入时以 origin/cfclub 为基 rebase 或 3-way merge,人工解决 UserService 冲突;不属 B2 范围蔓延,属集成编排事项
P2 B2-2 / B2-3 失败返回业务 code=500,非 HTTP 403 与 B2-4 拦截器的 HTTP 403 口径不一致(越权语义 403 更贴切) 可选:改为 Result.error(403, ...) 或 ResponseEntity,统一越权返回码;不影响功能正确性
P2 FamilyAccessInterceptor 类注释陈旧 :25 仍写「logging 模式(默认)」,但 isEnforcementMode()(:170)默认 enforcement —— 注释与实现相悖 更新 javadoc 默认模式说明
P2 cfc-backend/config/application.yml 覆盖 classpath application.yml 的 jwt.secret git 跟踪的 config/application.yml 优先级高于 classpath(file:./config/),有效密钥为 cfc-secret-key-2026-spring-boot-jwt-token 而非 ${JWT_SECRET:cfc-prod-jwt-secret-2026-keep-it-safe!} 默认值 部署脚注:该外部配置优先,改密钥需同步两处;建议在 config/application.yml 加注释说明

备注:未发现「正常业务依赖旧『空集放行』」的 P0(见第四节路由枚举结论 + R1/T8/T2 回归实测均未被误伤),故不触发规格「停下回报,不擅自白名单」。


四、B2-4 路由枚举结论(穷举带 familyId 的 controller 方法)

穷举 cfc-backend 全部 controller 中引用 familyId 的方法(共 231 处),按 familyId 来源 分类给出「空有效家庭集 + 携带 familyId」结论:

familyId 来源 代表路由 空集 + 带 familyId 结论
客户端可控(query/path/body 显式传) query:/api/health/report/proxy-parse、/api/assessment/plans/list、/api/wish/list、/api/dan-assessment/{order/family, record/current, record/family};path:/api/guide/families/{familyId}/members、/api/guide/**/{familyId}/**;body:/api/family/member/list、health report list/detail、family-platform 运营端点、orchestration、plan-review、innate-portrait 等 → 一律 403(enforcement) ✅ 安全收敛正确;这些正是需行级隔离的端点
@RequestAttribute("familyId")(JWT 注入,非客户端可控) 大多数业务端点(subscription、diet、promotion、indicator、energy、health-plan 等) familyId 由 JWT 从 user.family_id 注入,与请求参数无关 → 拦截器 collectFamilyIds 不采集,不受空集 403 影响 ✅ 不受影响(回归安全)
不携带 familyId 的既有请求 报告列表 / 成员列表 / 今日任务等 requestedFamilyIds 为空 → 放行(:74-76) ✅ 不被误伤(T2/T8/R1 实测)
  • 前端 cfc-frontend/pages/profile-extra/family-members.vue 对 /api/family/member/list 不发送 familyId(本地 familyId: 0 仅是页面数据默认值,不随请求发出)→ 前端无「会被新策略误伤」的路由。
  • 结论:未发现正常业务依赖旧「空集放行」,B2-4 全局策略变更不触发规格第 9 条停线条件。

五、测试数据与清理确认

检查项 结果
health_report_drafts 总数 74(与运行态测试前一致,无新增草稿)
health_reports 总数 22(无新增报告)
draft 111 状态 仍 pending / confirmed_report_id NULL(B2-3 负向测试未写入)
以 81315 为 creator/teacher/butler 的 family 行 0(无静默建家庭)
归属 81315 的 family_members 0
users.family_id for 81315 仍 NULL(未被篡改)
工作树 uploads/ 新增文件 0(最新文件仍为 20260820,无代传文件落盘)
user_operation_logs 验证审计行 已删除 id 63712–63730(共 16 行,主键范围 + 显式 id;未触碰其他会话行 62768)

本次核验未创建任何 users / family / family_members / draft / report 行;仅创建并已删除临时审计行。测试库无本次核验残留。复现账号 81315 / 81371 / 1001 均为既有数据,未修改。


六、核验环境与证据留存

  • 运行态:本会话启动两实例 —— 9083(enforcement 默认)、9085(-Dfamily.access.mode=logging);均已停止,端口已释放,无残留 java 进程。
  • 临时脚本:jwt_make.ps1(HS256,secret cfc-secret-key-2026-spring-boot-jwt-token)、runtime_tests*.ps1(逐次 HTTP 证据)、route_enum*.py(路由枚举)——均在 %TEMP%\opencode,核验后清理。
  • JWT 密钥说明:运行态实际生效密钥取自 git 跟踪的 cfc-backend/config/application.yml(优先于 classpath application.yml),已作为 P2 项记录。