Просмотр исходного кода

docs(tdd): EVD-15 跨角色域剩余8SC契约核对(SC-X-03/08/11/14/15/16/17/18)— 端点载体实测回填3⚠项+2命名修正、登记契约缺口3项(X-G-1订单支付通知未挂接、X-G-2多端会话互斥、X-G-3小程序订阅消息)、新建 2026-11-07-cross-role-contract.md + API_REFERENCE 增补§4.64

Sisyphus 5 дней назад
Родитель
Сommit
88351964bd

+ 73 - 0
docs/superpowers/api/API_REFERENCE.md

@@ -3368,3 +3368,76 @@ W0.2 双配置中心合并:`product_config` 已并入 `service_config`(唯
 | SC-P-83 | 意见反馈/在线客服 | 反馈已存在(/api/health/feedback/*、/api/activity/feedback/*、/api/feedback/*);在线客服无专用端点 | 缺口 G-4,需产品侧确认 |
 | SC-P-85 | 多端登录/会话互斥 | 登录族 + SSO 票据存在;无单端互斥/旧 token 踢出(JWT 无状态) | 缺口 G-5,需产品侧确认 |
 *文档更新:2026-11-07(EVD-13 家长域剩余 30 SC 契约核对增补「家长域剩余」段落 4.63:家庭与成员 / 健康报告上传解析 / 食谱营养 / 测评类型与 AI 对话 / 成长记录 / 商城加购下单 / 联系人与社交 / 设置与通知 / 舌诊情绪·账号·活动·反馈·会话 + 已 GREEN 键复用登记 4 处 + 契约缺口 5 项。完整核验表见 `docs/superpowers/specs/2026-11-07-parent-rest-contract.md`)*
+
+### 4.64 跨角色域剩余(SC-X-03/08/11/14/15/16/17/18,EVD-15 契约核对增补)
+> 跨角色域 22 个 SC(SC-X-01~22)中已由既有开工包覆盖 13 个(测评-方案 EVD-8R:X-01/06/09;报告闭环 EVD-7R:X-02/10/13;任务-心愿 EVD-3:X-05;五维能量 EVD-5:X-19/20/21;商城-会员 EVD-4:X-07/12;家庭-成员 EVD-2:X-04;CF 值预估 TR-5:X-22);本批 = 剩余 8 个无键 SC,端点载体逐条实测核验。完整核验表与实现缺口见 `docs/superpowers/specs/2026-11-07-cross-role-contract.md`。
+> 约定:所有端点 `POST`;越权语义统一 403(`FamilyAccessInterceptor` enforcement 模式 + `canAccessFamily`)。
+> **命名回填**:SC-X-03 候选 `ParentController` 实为心愿单 `/api/parent/wishlist*`(非视角切换,视角切换 = `/api/family/member/switch` + `/api/auth/switch-role`);SC-X-08 候选 `AdminArticleController /api/admin/article/*` 实际为 `/api/admin/articles`(带 s)。
+#### 4.64.1 双角色数据隔离越权(SC-X-03)
+| 路径 | 说明 |
+|------|------|
+| `POST /api/family/member/add`、`/list`、`/switch`、`/kick`、`/leave`、`/recycle`、`/update`、`/rename-family`、`/editable`、`/logs` | 成员 CRUD/权限(`FamilyMembersController`,`canAccessFamily` 校验有效家庭集,越权 403;`/switch` 切成员/孩子上下文视角 `SwitchMemberVO`) |
+| `POST /api/family/teacher-bindings/pending`、`/approve`、`/reject`、`/my-requests`、`/cancel` | 规划师绑定审核(`TeacherFamilyBindingController`) |
+| `POST /api/auth/switch-role` | 角色切换(`switchRoleForLogin` 重签 token,权限提升须登录,JwtInterceptor 强制登录) |
+| `POST /api/parent/wishlist`、`/wishlist/list`、`/wishlist/family`、`/wishlist/{id}/approve`、`/wishlist/{id}/exchange` | 家庭主账号心愿单(`ParentController`——**命名回填:非视角切换**) |
+> 越权语义载体:`FamilyAccessInterceptor`(请求携带 familyId 必须属于调用者有效家庭集,enforcement 模式越权 → 403「无权访问该家庭数据」,注册于 `WebConfig.addInterceptors`)+ `FamilyMembersController.canAccessFamily`(控制器内 403)。
+#### 4.64.2 文章发布闭环(SC-X-08)
+| 路径 | 说明 |
+|------|------|
+| `POST /api/article/publish`、`/my-posts`、`/updated-since`、`/detail`、`/list`、`/featured`、`/record-read`、`/related`、`/related-products`、`/audio`、`/report-reading-time`、`/reading-stats`、`/daily-tip` | 文章发布/详情/列表(`ArticleController`,`/api/articles` 与 `/api/article` 双前缀兼容) |
+| `POST /api/articles/categories` | 文章分类(`ArticleCategoryController`) |
+| `POST /api/articles/comments/list`、`/create`、`/audit`、`/pending`、`/my`;`/quiz/generate`、`/quiz/submit` | 文章评论 + 答题(`ArticleCommentController`) |
+| `POST /api/admin/articles/list`、`/create`、`/update`、`/detail`、`/delete`、`/{id}/publish`、`/publish`、`/audit`、`/submit-review`、`/withdraw`、`/re-draft`、`/toggle-featured`、`/move`、`/upload/image`、`/upload/video`、`/comments/list`、`/categories/list`、`/categories/create`、`/categories/update`、`/categories/delete`、`/reading-records` | 文章管理端审核/上架/下架(`AdminArticleController`,**路径带 s:`/api/admin/articles`**) |
+| `POST /api/admin/review-center/summary` | 审核中心汇总(`ReviewCenterController`) |
+> 闭环 = 发布→审核→上架→评论,端点齐全 ✅。
+#### 4.64.3 消息通知闭环(SC-X-11)
+| 路径 | 说明 |
+|------|------|
+| `POST /api/notification/list`、`/read` | 站内消息查看 + 已读(`UserNotificationController`,已读闭环) |
+| `POST /api/admin/notification-template/list`、`/save`、`/delete` | 通知模板/通道配置(`AdminNotificationTemplateController`) |
+| `NotificationDispatchService.sendByTemplate(type,userId,vars,refType,refId,defaultTitle,defaultContent)` | 通知发送统一入口(W3 五通道:in_app/sms/wechat/gzh/phone;in_app + wechat-webhook 投产,sms/gzh/phone/wechat-订阅 预留禁用) |
+| `InAppNotificationChannel`(isEnabled=true) | 站内通道,写 `user_notifications` 表 |
+| `WebhookNotificationChannel`(channelType=wechat,isEnabled=true) | 微信待办 webhook 通道,复用 `WechatWaitMsgService.sendWaitMsg`(按用户手机号定向 msgLabel) |
+> 事件触发 = 10 个 service 调 sendByTemplate(`TaskService`/`PointsService`/`EnergyService`/`CfBalanceServiceImpl`/`CouponGiftService`/`DanReportUploadService`/`ProblemCompletionService`/`ProcurementTaskService`/`ReportTransferService`/`TaskReminderScheduledTask`)。**⚠ 部分存在**:订单/活动/支付事件(`ProductOrderController`/`ActivityOrderController`/`VirtualPayController`)未挂接统一分发;微信订阅消息通道未接入 → 缺口 X-G-1。
+#### 4.64.4 解绑/重分配跨角色协同(SC-X-14)
+| 路径 | 说明 |
+|------|------|
+| `POST /api/bind/accept`、`/guides`、`/unbind` | 家庭绑定/解绑(`BindController`) |
+| `POST /api/family/invite/generate`、`/validate`、`/request-join-by-code`、`/approve-request`、`/reject-request`、`/pending-requests`、`/my-request`、`/cancel-request`、`/bind-inviter`、`/accept`、`/check-family`、`/revoke`、`/transfer-admin` | 邀请重分配/管理员转移(`FamilyInviteController`) |
+| `POST /api/cf/transfer/send`、`/list` | CF 余额转移(`CfTransferController`) |
+> 协同 = 规划师/成员解绑(`/unbind`)+ 成员数据重分配(`/transfer-admin`、`/revoke`)+ CF 转移。
+#### 4.64.5 注销/数据导出跨角色(SC-X-15)
+| 路径 | 说明 |
+|------|------|
+| `POST /api/user/deactivate` | 账号注销(`AccountCleanupService.deactivateAccount`:匿名化主账号 openid 哈希 + realName/idCard/phone/unionid/nickname/avatar/address/sessionKey 清空 + deleted=1,匿名化关联 `family_member` 记录,处理 PaymentOrder(familyId)/AssessmentOrder(userId)) |
+| `POST /api/user/data-export` | 个保法可携带权导出(`AccountCleanupService.exportUserData`) |
+> 跨角色语义 = 家长注销后家庭成员记录/家庭订单处理。
+#### 4.64.6 活动名额并发(SC-X-16)⭐
+| 路径 | 说明 |
+|------|------|
+| `POST /api/activity/register`、`/cancel-registration`、`/my-registrations`、`/registration-roster`、`/checkin`、`/checkin-review` | 活动报名/取消/名单/签到(`ActivityController`) |
+| `ActivityRegistrationService.occupyQuota` | 原子占用名额:`UPDATE activity SET approved_count=approved_count+1 WHERE id=? AND approved_count<max_participants`(返回 rows>0,**多端并发报名不超发**;`releaseQuota` 原子回退) |
+| `POST /api/activity/order/create`、`/pay`、`/notify`、`/status` | 付费活动订单(`ActivityOrderController`) |
+> 并发语义 = 同名额多端并发报名不超发,载体 = `occupyQuota` 条件自增(DB 行锁)。
+#### 4.64.7 多端登录会话互斥(SC-X-17)
+| 路径 | 说明 |
+|------|------|
+| `POST /api/auth/wechat-login`、`/silent-login`、`/phone-login`、`/switch-role`、`/sso-ticket`、`/sso-login`、`/verify`、`/verifyToken` | 登录族 + token 签发/校验(`AuthController`) |
+| `POST /api/auth/wechat-web/qr`、`/scan`、`/poll` | 微信 web 登录(`WechatWebAuthController`) |
+| `JwtInterceptor` | token 签名/过期校验(无效/过期 → 401,公开路径降级匿名放行) |
+> **⚠ 互斥无载体**:无 token 互斥/单点踢下线(无 tokenVersion/kickout/blacklist/会话注册表;JWT 无状态;SSO 为一次性免登票据非互斥踢出)→ 缺口 X-G-2(同因 EVD-13 SC-P-85 G-5)。
+#### 4.64.8 推送跨端送达(SC-X-18)
+| 路径 | 说明 |
+|------|------|
+| `WechatService.sendTemplateMessage(toUserOpenid, templateId, keywordMap)` | 公众号模板消息(`/cgi-bin/message/template/send`,调用方 `WechatAlertTemplateService`/`PromotionTierEvalService`) |
+| `WechatWaitMsgService.sendWaitMsg(content, label)` | 微信待办 webhook 定向推送(调用方 `WebhookNotificationChannel`) |
+| `POST /api/internal/virtual-pay/notify`(GET URL 验证 + POST 签名校验) | 微信虚拟支付消息推送**接收**端点(`VirtualPayController`,非主动推送) |
+> **⚠ 部分存在**:小程序订阅消息(requestSubscribeMessage/subscribeMessage)前后端全仓 0 命中,`WechatNotificationChannel` isEnabled=false 预留禁用;cfc-langgraph 无推送载体 → 缺口 X-G-3。
+#### 4.64.9 契约缺口(无完整端点载体,需产品侧确认验收方式)
+| SC | 场景 | 现状 | 处置 |
+|----|------|------|------|
+| SC-X-11 | 消息通知闭环(事件挂接/订阅通道) | 五通道框架完整(in_app + wechat-webhook 投产);订单/活动/支付事件未挂接统一分发;微信订阅消息通道 `WechatNotificationChannel` 预留禁用 | 缺口 X-G-1,需产品侧确认 |
+| SC-X-17 | 多端登录会话互斥 | 登录族 + JwtInterceptor token 校验存在;无 token 互斥/单点踢出(JWT 无状态) | 缺口 X-G-2,需产品侧确认(同因 EVD-13 SC-P-85 G-5) |
+| SC-X-18 | 推送跨端送达 | 公众号模板消息 + 微信待办 webhook 已投产;小程序订阅消息(requestSubscribeMessage/subscribeMessage)前后端 0 命中,`WechatNotificationChannel` 预留禁用;cfc-langgraph 无推送 | 缺口 X-G-3,需产品侧确认 |
+> 本批仅登记缺口不实现,转产品/运维侧确认后由后续批次落地。
+*文档更新:2026-11-07(EVD-15 跨角色域剩余 8 SC 契约核对增补「跨角色域剩余」段落 4.64:双角色数据隔离越权 / 文章发布闭环 / 消息通知闭环 / 解绑重分配 / 注销数据导出 / 活动名额并发 / 多端登录互斥 / 推送跨端送达 + 命名回填 2 处 + 契约缺口 3 项。完整核验表见 `docs/superpowers/specs/2026-11-07-cross-role-contract.md`)*

+ 64 - 0
docs/superpowers/specs/2026-11-07-cross-role-contract.md

@@ -0,0 +1,64 @@
+# 跨角色域剩余批次 · 契约核对结论(X 域剩余 8 SC · 防假 RED)
+
+> 归属:契约补建计划 P0「跨角色域剩余」· 核对时间 2026-11-07(EVD-15)
+> 开工包:`docs/tdd/orchestration/cross-role-kickoff-20261107.md`(origin/cfclub @ `9f0da8727`)
+> 核对对象:origin/cfclub `cfc-backend` controller 源码(工作树 HEAD = origin/cfclub `9f0da8727`)
+> 核对方法:类级 `@RequestMapping` + 方法级 `@PostMapping` 逐一比对(`grep -rn '@RequestMapping|@PostMapping' cfc-backend/src/main/java/com/etotem/cfc/controller/` 实测定位,不假定包路径),逐端点记录存在性;对字面路径缺失者定位等价实现(防假 RED:契约声明的接口范围必须能在真实源码中找到实现)。开工包 3 个 ⚠ 待核实项(X-11 通知发送通道 / X-17 token 互斥 / X-18 推送通道)全部实测回填(含全仓 `grep -rlE "subscribeMessage|templateMessage|pushMessage|sendPush" cfc-backend/src/main/java` + `cfc-langgraph` 定位真实推送通道)。
+> 命名注意:X-11/X-18 的「通知发送/推送通道」载体按真实实现回填(`NotificationDispatchService` 五通道框架 + `WechatService.sendTemplateMessage` 公众号模板消息 + `WechatWaitMsgService.sendWaitMsg` 微信待办 webhook),不假定开工包候选类名。
+
+## 0. 结论摘要
+
+- **8 个 SC 中 6 个存在可用 HTTP 端点载体**(SC-X-03 / SC-X-08 / SC-X-14 / SC-X-15 / SC-X-16 端点齐全;SC-X-11 闭环框架完整但订单/活动/支付事件未挂接统一通知分发)。
+- **2 个 SC 存在实现缺口**:SC-X-17(多端登录**会话互斥**——token 互斥/单点踢出无载体,JWT 无状态,与 EVD-13 SC-P-85 缺口 G-5 一致)、SC-X-18(**小程序订阅消息**跨端推送——订阅消息/模板推送无载体,仅公众号模板消息 + 微信待办 webhook 投产)。按 O-7 标注「无完整端点载体,需产品侧确认验收方式」,本批仅登记缺口不落地实现。
+- 端点核对范围内 **无「假 RED」**:开工包 3 个 ⚠ 待核实项(X-11 / X-17 / X-18)逐一实测回填,其中 X-11 框架成立(⚠ 部分存在:订单/支付事件未挂接 + 订阅消息通道未接入)、X-17 缺口(互斥无载体)、X-18 部分存在(订阅消息缺口),详见 §1。
+- **命名回填 1 处**:SC-X-03 开工包候选 `ParentController`(家长视角切换)实为**心愿单**控制器 `/api/parent/wishlist*`;家长视角切换实际载体 = `FamilyMembersController /api/family/member/switch` + `AuthController /api/auth/switch-role`。SC-X-08 开工包候选 `AdminArticleController /api/admin/article/*` 实际为 `/api/admin/articles`(带 s)。
+- 无新增 DB 迁移、未改动业务代码与测试文件(本批次仅新增本核对文档 + API_REFERENCE 增补段落 + 端点核验表回填)。
+
+---
+
+## 1. 核对方法(开工包 ⚠ 待核实项回填)
+
+开工包 8 个 SC 中 3 个标注 ⚠,会话实测回填结论如下(含全仓推送通道定位结果):
+
+| ⚠ 项 | 场景 | 实测结论 |
+|------|------|----------|
+| SC-X-11 消息通知闭环(通知发送载体/推送通道) | 通知发送通道待核实 | **框架存在(部分挂接)**——通知发送统一入口 = `NotificationDispatchService.sendByTemplate()`(W3 五通道:in_app / sms / wechat / gzh / phone)。通道实现:`InAppNotificationChannel`(已投产 isEnabled=true,写 `user_notifications` 表)、`WebhookNotificationChannel`(channelType=wechat,**已投产 isEnabled=true**,复用 `WechatWaitMsgService.sendWaitMsg` 微信待办 webhook 定向推送)、`SmsNotificationChannel`/`GzhNotificationChannel`/`PhoneNotificationChannel`/`WechatNotificationChannel`(均 **isEnabled=false 预留禁用**,其中 Wechat 订阅消息通道标注「本期不支持,待接入微信小程序订阅消息网关后启用」)。**事件触发 = 10 个 service 调 sendByTemplate**(`TaskService`/`PointsService`/`EnergyService`/`CfBalanceServiceImpl`/`CouponGiftService`/`DanReportUploadService`/`ProblemCompletionService`/`ProcurementTaskService`/`ReportTransferService`/`TaskReminderScheduledTask`)。**已读闭环 = `UserNotificationController /api/notification/list|read`**;**模板配置 = `AdminNotificationTemplateController /api/admin/notification-template/list|save|delete`**。**⚠ 开工包候选不成立**:`ProductOrderController`(下单通知)/`ActivityOrderController`(报名通知)/`VirtualPayController`(支付通知)三个控制器**均无 sendByTemplate 调用**——订单/活动/支付事件**未挂接**统一通知分发;微信订阅消息通道未接入 → 见 §3 缺口 X-G-1 |
+| SC-X-17 多端登录会话互斥(token 互斥实现位置) | token 互斥待核实 | **互斥无载体(缺口)**——登录族端点存在(`AuthController /api/auth/*`:`wechat-login`/`silent-login`/`phone-login`/`switch-role`/`sso-ticket`/`sso-login` + `verifyToken` 校验;`WechatWebAuthController /api/auth/wechat-web/qr|scan|poll` 微信 web 登录);`JwtInterceptor` 仅做 token 签名/过期校验(无效/过期 → 401,公开路径降级匿名放行),**无 token 互斥/单点踢下线逻辑**。全仓无 `tokenVersion`/`token_version`/`kickout`/`blacklist`/Redis 会话注册表/设备会话表;JWT 无状态;SSO(`SsoService.issueTicket/consumeTicket` + `sso_ticket` 表)为**跨小程序单点登录一次性票据**(免登握手),**非**同账号多端互斥踢出 → 见 §3 缺口 X-G-2(与 EVD-13 SC-P-85 缺口 G-5 同因) |
+| SC-X-18 推送跨端送达(推送通道载体) | 推送通道待核实 | **部分存在(订阅消息缺口)**——全仓 `grep -rlE "subscribeMessage|templateMessage|pushMessage|sendPush" cfc-backend/src/main/java` = **0 命中**;`cfc-langgraph` 103 个 py 文件检索 subscribe/push/微信 = **0 命中**(推送不在 langgraph)。主动推送通道(已投产):`WechatService.sendTemplateMessage()`(公众号模板消息 `/cgi-bin/message/template/send`,调用方 `WechatAlertTemplateService`、`PromotionTierEvalService`)+ `WechatWaitMsgService.sendWaitMsg()`(微信待办 webhook,调用方 `WebhookNotificationChannel`)。接收侧:`VirtualPayController /api/internal/virtual-pay/notify`(微信虚拟支付**消息推送接收**端点,GET URL 验证 + POST 签名校验,非主动推送)。**小程序订阅消息(`requestSubscribeMessage`/`subscribeMessage`)前端后端全仓 0 命中**,`WechatNotificationChannel` isEnabled=false 预留禁用 → 订阅消息跨端(小程序/Web/服务端)无载体 → 见 §3 缺口 X-G-3 |
+
+---
+
+## 2. 端点核验表(8 SC)
+
+核验口径:`✅` = 候选/回填端点真实存在于工作树;`⚠` = 主场景有端点但存在子能力缺口(详见 §3 实现缺口清单)。
+
+| SC | 场景标题 | 端点载体(实测回填,origin/cfclub 工作树) | 核验 |
+|----|----------|--------------------------------------------|:----:|
+| SC-X-03 | 双角色数据隔离越权 | `FamilyMembersController` `/api/family/member/*`(`add`/`list`/`switch`/`kick`/`leave`/`recycle`/`update`/`rename-family`/`editable`/`logs`,`canAccessFamily` 校验有效家庭集,越权 403);`FamilyAccessInterceptor`(请求携带 familyId 必须属于调用者有效家庭集,enforcement 模式越权 → 403「无权访问该家庭数据」,注册于 `WebConfig.addInterceptors`);`TeacherFamilyBindingController` `/api/family/teacher-bindings/*`(`pending`/`approve`/`reject`/`my-requests`/`cancel`,规划师绑定);`AuthController` `/api/auth/switch-role`(角色切换,`switchRoleForLogin` 重签 token,权限提升须登录);`FamilyMembersController /api/family/member/switch`(切成员/孩子上下文视角,`SwitchMemberVO`)。**命名回填**:开工包候选 `ParentController`(家长视角切换)实为心愿单 `/api/parent/wishlist*`(`createParentWishlist`/`getParentWishlist`/`approveWishlist`/`exchangeParentWishlist`),**非**视角切换载体;越权 403 语义载体 = `FamilyAccessInterceptor` + `canAccessFamily`(开工包断言成立) | ✅ |
+| SC-X-08 | 文章发布闭环 | `ArticleController` `/api/article/*`(`publish`/`my-posts`/`updated-since`/`detail`/`list`/`featured`/`record-read`/`related`/`related-products`/`audio`/`report-reading-time`/`reading-stats`/`daily-tip`);`ArticleCategoryController` `/api/articles/categories`(分类);`ArticleCommentController` `/api/articles/comments/*`(`list`/`create`/`audit`/`pending`/`my`)+ `quiz/generate`/`quiz/submit`(评论+答题闭环);`AdminArticleController` `/api/admin/articles/*`(`list`/`create`/`update`/`detail`/`delete`/`{id}/publish`/`publish`/`audit`/`submit-review`/`withdraw`/`re-draft`/`toggle-featured`/`move`/`upload/image`/`upload/video`/`comments/list`/`categories/*`/`reading-records`,**审核/上架/下架**);`ReviewCenterController` `/api/admin/review-center/summary`(审核中心汇总)。闭环 = 发布→审核→上架→评论 ✅。**命名回填**:开工包候选 `AdminArticleController /api/admin/article/*` 实际为 `/api/admin/articles`(带 s) | ✅ |
+| SC-X-11 | 消息通知闭环 | `UserNotificationController` `/api/notification/list|read`(站内已读闭环);`AdminNotificationTemplateController` `/api/admin/notification-template/list|save|delete`(模板/通道配置);发送 = `NotificationDispatchService.sendByTemplate()`(五通道:in_app 投产 + wechat-webhook 投产,sms/gzh/phone/wechat-订阅 预留);事件触发 = 10 个 service(TaskService/PointsService/EnergyService/CfBalanceServiceImpl/CouponGiftService/DanReportUploadService/ProblemCompletionService/ProcurementTaskService/ReportTransferService/TaskReminderScheduledTask)。**⚠ 部分存在**:闭环框架完整,但订单/活动/支付事件(ProductOrder/ActivityOrder/VirtualPay)**未挂接**统一分发,微信订阅消息通道未接入 → 见 §3 X-G-1 | ⚠ |
+| SC-X-14 | 解绑/重分配跨角色协同 | `BindController` `/api/bind/accept|guides|unbind`(家庭绑定/解绑);`FamilyInviteController` `/api/family/invite/*`(`generate`/`validate`/`request-join-by-code`/`approve-request`/`reject-request`/`pending-requests`/`my-request`/`cancel-request`/`bind-inviter`/`accept`/`check-family`/`revoke`/`transfer-admin`,邀请重分配/管理员转移);`CfTransferController` `/api/cf/transfer/send|list`(CF 余额转移)。协同 = 规划师/成员解绑(`/unbind`)+ 成员数据重分配(`/transfer-admin`、`/revoke`)+ CF 转移 | ✅ |
+| SC-X-15 | 注销/数据导出跨角色 | `UserController` `POST /api/user/deactivate`(`AccountCleanupService.deactivateAccount`:匿名化主账号 openid 哈希 + realName/idCard/phone/unionid/nickname/avatar/address/sessionKey 清空 + deleted=1,并匿名化关联 `family_member` 记录、处理 PaymentOrder(familyId)/AssessmentOrder(userId))+ `POST /api/user/data-export`(`AccountCleanupService.exportUserData` 个保法可携带权导出)。跨角色语义 = 家长注销后家庭成员记录/家庭订单处理 | ✅ |
+| SC-X-16 | 活动名额并发 E2E ⭐ | `ActivityController` `POST /api/activity/register`(+`cancel-registration`/`my-registrations`/`registration-roster`/`checkin`/`checkin-review`);`ActivityRegistrationService.occupyQuota`(`@Transactional` 原子 UPDATE:`UPDATE activity SET approved_count=approved_count+1 WHERE id=? AND approved_count<max_participants`,返回 rows>0——**多端并发报名不超发**;`releaseQuota` 原子回退);`ActivityOrderController` `/api/activity/order/*`(`create`/`pay`/`notify`/`status` 付费活动);审核通过也走 `occupyQuota`(满员无法通过) | ✅ |
+| SC-X-17 | 多端登录会话互斥跨端 | `AuthController` `/api/auth/*`(`wechat-login`/`silent-login`/`phone-login`/`switch-role`/`sso-ticket`/`sso-login`/`verifyToken` 校验)+ `WechatWebAuthController` `/api/auth/wechat-web/qr|scan|poll`(微信 web 登录);`JwtInterceptor`(token 签名/过期校验,无效/过期 401,公开路径降级匿名)。**⚠ 互斥无载体**:无 token 互斥/单点踢下线(无 tokenVersion/kickout/blacklist/会话注册表;JWT 无状态;SSO 为一次性免登票据非互斥踢出)→ 见 §3 X-G-2 | ⚠ |
+| SC-X-18 | 推送跨端送达 | `WechatService.sendTemplateMessage()`(公众号模板消息,调用方 `WechatAlertTemplateService`/`PromotionTierEvalService`)+ `WechatWaitMsgService.sendWaitMsg()`(微信待办 webhook,调用方 `WebhookNotificationChannel`)+ `VirtualPayController /api/internal/virtual-pay/notify`(微信虚拟支付推送**接收**端点)。**⚠ 部分存在**:小程序订阅消息(requestSubscribeMessage/subscribeMessage)前后端全仓 0 命中,`WechatNotificationChannel` isEnabled=false 预留;cfc-langgraph 无推送 → 订阅消息跨端无载体 → 见 §3 X-G-3 | ⚠ |
+
+---
+
+## 3. 契约缺口(无完整端点载体,需产品侧确认验收方式;本批仅登记不实现)
+
+| SC | 场景 | 现状 | 处置 |
+|----|------|------|------|
+| SC-X-11 | 消息通知闭环(事件挂接/订阅通道) | 五通道框架完整(in_app + wechat-webhook 投产),但订单/活动/支付事件未挂接统一分发(ProductOrder/ActivityOrder/VirtualPay 无 sendByTemplate 调用);微信订阅消息通道 `WechatNotificationChannel` isEnabled=false 预留禁用 | 缺口 X-G-1:需产品侧确认订单/支付通知是否挂接统一分发 + 订阅消息通道是否本期启用 |
+| SC-X-17 | 多端登录会话互斥 | 登录族 + JwtInterceptor token 校验存在;无 token 互斥/单点踢出(JWT 无状态,无 tokenVersion/blacklist/会话注册表;SSO 为一次性免登票据非互斥) | 缺口 X-G-2:需产品侧确认多端互斥验收方式(同因 EVD-13 SC-P-85 G-5) |
+| SC-X-18 | 推送跨端送达 | 公众号模板消息 + 微信待办 webhook 已投产(服务端→微信);小程序订阅消息(requestSubscribeMessage/subscribeMessage)前后端 0 命中,`WechatNotificationChannel` 预留禁用;cfc-langgraph 无推送载体 | 缺口 X-G-3:需产品侧确认小程序订阅消息跨端送达验收方式 |
+
+> 本批仅登记缺口,不建伪实现任务;转产品/运维侧确认后由后续批次落地。
+
+---
+
+## 4. 交付说明
+
+- 本批新增/修改:`docs/superpowers/specs/2026-11-07-cross-role-contract.md`(本文件,新建)+ `docs/superpowers/api/API_REFERENCE.md`(增补 §4.64 跨角色域契约段)。
+- 未改动任何业务代码、未改动测试文件、未动 `.tdd/`、无新增 DB 迁移。
+- 端点核对范围 **无假 RED**:8 个 SC 端点载体全部在真实源码中实测定位(含 3 个 ⚠ 项回填与 2 处命名回填)。