fix(security): stop operator identity from reaching user endpoints; guard path rules

Continues the HTTP-semantics work. Fixing 401/403 exposed a worse defect on the
same axis: who is allowed to reach which endpoint.

Root cause chain:
- PlatformPrincipal has two implementations (OperatorPrincipal / UserPrincipal),
  chosen by JwtAuthFilter from the token type.
- `@AuthenticationPrincipal UserPrincipal` against an OperatorPrincipal is a type
  mismatch, and Spring Security returns null (errorOnInvalidType defaults to
  false) instead of failing.
- 244 uses of that annotation repo-wide; only 48 null-check. The rest NPE -> 500
  when reached with an operator identity.
- The fallback rule was `.authenticated()`, which an operator token satisfies, so
  such requests did reach user-facing controllers.

Adding ~196 null checks would be mechanical, easy to miss, and does nothing to
constrain future code. The mismatch is between identity type and endpoint, so it
is fixed once, at the authentication layer: the fallback becomes
`.hasRole("USER")` (operator -> ROLE_OPERATOR, user -> ROLE_USER, per JwtAuthFilter).
Operator requests to user endpoints now get 403 before any controller runs.

Trap worth recording: operator endpoints are not all under /operator/ —
/counseling/services/operator/queue, /content/operator/articles,
/activities/operator/checkin/scan, /service-appointments/operator/list and others
sit deeper inside business paths. The first attempt covered them with
`requestMatchers("/**/operator/**")`, which fails at runtime:

  PatternParseException: No more pattern data allowed after {*...} or ** pattern element

Spring's PathPattern permits `**` only as the final element. Worse, the symptom is
a 500 from the whole filter chain (Tomcat HTML error page, not our JSON), and E2E
went from 37 passed to 33 failed — an error far removed from its cause. Now the
nine prefixes are listed explicitly, each ending in /**.

Because explicit enumeration can be forgotten as endpoints are added, and because
the failure mode is "operators locked out of their own admin module" (invisible to
user-side tests), SecurityPathCoverageTest parses the OPERATOR rule prefixes out of
SecurityConfig source, walks every *Controller.java, joins class-level and
method-level mapping paths, and asserts every path containing /operator/ is
covered (/auth/operator/** excluded by design). Two things that would silently
neuter it, both handled: it must parse only the .hasRole("OPERATOR") chain — pulling
in the permitAll or fallback rules would mark everything covered — and the test
working directory is the repo root, not the Maven module root.

Verification: negatively validated by removing /content/operator/** -> exactly one
test turns red listing the six affected ContentController endpoints; restored.
E2E 40 passed (37 + 3 identity-isolation cases). Backend regression 664 / 0
failures / 0 errors / 3 skipped.

docs/HTTP语义检修报告-2026-09-18.md

@@ -139,11 +139,11 @@ config.setAllowCredentials(true);        // 允许携带凭证
 ### 3. 后端全量回归
 
 ```
-Tests run: 662, Failures: 0, Errors: 0, Skipped: 3   BUILD SUCCESS
+Tests run: 664, Failures: 0, Errors: 0, Skipped: 3   BUILD SUCCESS
 ```
 
-基线 656（Phase 23B 后），净 +6 为新增的
-`ApiResponseCodeHttpStatusTest`（6 条映射语义守卫）。
+基线 656（Phase 23B 后），净 +8：`ApiResponseCodeHttpStatusTest`（6 条映射语义守卫）
++ `SecurityPathCoverageTest`（2 条路径覆盖守卫，见第七节）。
 3 个 skip 均有显式原因，无一为空壳。
 
 首个回归轮次为 **662 / 3 failures**，三处失败均已判定为「测试断言了旧的错误行为」
@@ -185,13 +185,103 @@ Tests run: 662, Failures: 0, Errors: 0, Skipped: 3   BUILD SUCCESS
 
 ---
 
-## 七、结论
+## 七、补充：身份类型与路径规则的收敛（同日续做）
+
+修完 401/403 之后，顺着同一条线索继续查，发现一个**与错误响应质量直接相关**的更严重缺陷。
+
+### 1. 根因链条
+
+`PlatformPrincipal` 有两个实现：`OperatorPrincipal`（运营 token）与 `UserPrincipal`（用户 token），
+由 `JwtAuthFilter` 按 token 类型选择。
+
+而 `@AuthenticationPrincipal UserPrincipal` 遇到 `OperatorPrincipal` 时属**类型不匹配**，
+Spring Security 默认返回 **null**（`errorOnInvalidType=false`）。
+
+后果：全仓 **244 处**使用该注解，**仅 48 处**做了 null 检查。
+其余端点在运营身份访问时会直接 NPE → **500**。
+
+这不是理论风险——`SecurityConfig` 当时的兜底规则是 `authenticated()`，
+而运营 token 完全满足"已认证"，请求可以一路打进用户端 Controller。
+
+### 2. 为什么不补 null 检查
+
+补上百处 `if (principal == null)` 是机械劳动，还会遗漏、也无法约束将来新增的代码。
+根因是**身份类型与端点不匹配**，应该在认证层解决，而不是在每个端点重复防御。
+
+### 3. 修法：兜底规则从「已认证」收紧为「用户身份」
+
+```java
+.requestMatchers("/**").hasRole("USER")   // 原为 .authenticated()
+```
+
+运营身份访问用户端 → 403，请求根本进不到 Controller，196 处潜在 NPE 一次性消解。
+角色对应关系由 `JwtAuthFilter` 保证：运营 → `ROLE_OPERATOR`，用户 → `ROLE_USER`。
+
+### 4. ⚠️ 踩坑：`/**/operator/**` 是非法模式
+
+运营端点并非都在 `/operator/` 下——`/counseling/services/operator/queue`、
+`/content/operator/articles`、`/activities/operator/checkin/scan`、
+`/service-appointments/operator/list` 等嵌在业务路径深处。
+
+第一版试图用 `/**/operator/**` 一行通配，结果：
+
+```
+PatternParseException: No more pattern data allowed after {*...} or ** pattern element
+```
+
+**Spring 的 PathPattern 不允许 `**` 出现在中间**，只允许在末尾。
+更糟的是它的表现：整个过滤器链直接 **500**（Tomcat HTML 错误页，不是我们的 JSON），
+E2E 从 37 passed 变成 **33 failed**。
+
+改为显式枚举 9 个前缀（全部符合 PathPattern 语法）：
+
+```
+/operator/**  /admin/**
+/counseling/services/operator/**  /content/operator/**  /risk/operator/**
+/activities/operator/**  /service-appointments/operator/**
+/service-programs/operator/**  /referrals/operator/**
+```
+
+### 5. 机械守卫：`SecurityPathCoverageTest`
+
+显式枚举的代价是"将来新增会漏"，而漏掉的表现是
+**运营人员被自己的平台拒绝（管理端对应模块不可用）**——只跑用户侧测试根本看不出来。
+
+因此新增守卫，**从 `SecurityConfig` 源码解析出 OPERATOR 规则前缀**，
+再扫描全部 `*Controller.java`，把「类级路径 + 方法级路径」拼成完整路径，
+校验每个含 `/operator/` 的端点都被覆盖（`/auth/operator/**` 按设计排除）。
+
+两个必须注意的细节：
+
+- **只能解析 `.hasRole("OPERATOR")` 那条链的规则。** 若把 permitAll 或兜底的 `/**` 也收进来，
+  任何路径都会被判为"已覆盖"，守卫就退化成永远通过的摆设。
+- **工作目录是仓库根而非模块根**（同项目 `MigrationValidationTest` 也用 `backend/target/...` 形式），
+  故源码根需同时尝试两种候选路径。
+
+**负向验证**：摘掉 `/content/operator/**` 前缀后，恰好 1 个用例变红，
+并精确列出受影响的 6 个 `ContentController` 端点；恢复后全绿。
+
+### 6. 验证
+
+- E2E **40 passed**（原 37 + 3 条身份隔离用例：运营打用户端 403、
+  用户打运营端 403、嵌套运营端点仍要求 OPERATOR）。
+- 后端全量回归 **664 / 0 failures / 0 errors / 3 skipped**（本轮起点 662，净 +2 为新守卫），
+  `SecurityPathCoverageTest` 已并入常规回归。
+- 首个 E2E 轮次因非法路径模式导致 **33 failed**（过滤器链 500）；
+  修正为显式前缀后全部恢复，佐证了"`/**/operator/**` 不可用"这一结论。
+
+---
+
+## 八、结论
 
 本轮把「失败必须携带真实 HTTP 语义」从约定变成了机制：
 
 - 状态码的**唯一来源**是 `ApiResponseCode.httpStatus`，新增业务码不声明就编译不过；
 - 105 处 Controller 直返**零改动**即获得正确状态；
 - 未认证与无权限在 HTTP 层分离，小程序终于能触发重新登录；
-- CORS 默认从「放行任意来源」改为「默认拒绝」。
+- CORS 默认从「放行任意来源」改为「默认拒绝」；
+- 兜底访问规则从「已认证」收紧为「用户身份」，196 处潜在 NPE → 500 在认证层消解，
+  并有机械守卫防止将来新增运营端点时漏配规则。
 
-顺带修掉了一个当时就会伤害用户的缺陷：token 过期不再让用户卡死。
+顺带修掉了两个当时就会伤害真实用户的缺陷：
+**token 过期后用户卡死无法重登录**，以及**运营身份可打进用户端触发 500**。