Преглед изворни кода

merge: integrate origin/cfclub into task/S-cfc-299 (S-cfc-299 RED global.search.query)

E2E Test Bot пре 5 дана
родитељ
комит
86a9ab5c42
27 измењених фајлова са 3764 додато и 7 уклоњено
  1. 29 0
      cfc-backend/src/main/java/com/etotem/cfc/config/DatabaseInitializer.java
  2. 42 0
      cfc-backend/src/main/java/com/etotem/cfc/controller/ContentFilterController.java
  3. 69 0
      cfc-backend/src/main/java/com/etotem/cfc/controller/admin/AdminAfterSalesController.java
  4. 112 2
      cfc-backend/src/main/java/com/etotem/cfc/controller/admin/AdminProductOrderController.java
  5. 48 0
      cfc-backend/src/main/java/com/etotem/cfc/controller/admin/MindModelManageController.java
  6. 39 0
      cfc-backend/src/main/java/com/etotem/cfc/entity/MindModel.java
  7. 9 0
      cfc-backend/src/main/java/com/etotem/cfc/mapper/MindModelMapper.java
  8. 128 0
      cfc-backend/src/main/java/com/etotem/cfc/service/MindModelManageService.java
  9. 38 0
      cfc-backend/src/main/java/com/etotem/cfc/service/impl/HealthPlanServiceImpl.java
  10. 33 0
      cfc-backend/src/main/java/com/etotem/cfc/util/PlanContentSafetyUtil.java
  11. 14 0
      cfc-backend/src/main/resources/schema.sql
  12. 276 0
      cfc-backend/src/test/java/com/etotem/cfc/unit/ActivityCheckinBoostContractTest.java
  13. 381 0
      cfc-backend/src/test/java/com/etotem/cfc/unit/AdminFamilyRelationManageContractTest.java
  14. 286 0
      cfc-backend/src/test/java/com/etotem/cfc/unit/AuthSessionMutexContractTest.java
  15. 400 0
      cfc-backend/src/test/java/com/etotem/cfc/unit/DataExportGdprContractTest.java
  16. 280 0
      cfc-backend/src/test/java/com/etotem/cfc/unit/EnergyDailyLimitGuardContractTest.java
  17. 357 0
      cfc-backend/src/test/java/com/etotem/cfc/unit/FamilyChildContextSwitchContractTest.java
  18. 302 0
      cfc-backend/src/test/java/com/etotem/cfc/unit/GrowthLeaderboardViewContractTest.java
  19. 313 0
      cfc-backend/src/test/java/com/etotem/cfc/unit/NotificationCenterViewContractTest.java
  20. 267 0
      cfc-backend/src/test/java/com/etotem/cfc/unit/ShopCouponClaimContractTest.java
  21. 1 1
      cfc-web/.last_build_commit
  22. 2 2
      cfc-web/package-lock.json
  23. 1 1
      cfc-web/package.json
  24. 80 0
      cfc-web/public/CHANGELOG-v1.0.md
  25. 81 1
      cfc-web/public/CHANGELOG.md
  26. 1 0
      docs/superpowers/api/API_REFERENCE.md
  27. 175 0
      docs/tdd/orchestration/report-dev-2026-11-14-0522.md

+ 29 - 0
cfc-backend/src/main/java/com/etotem/cfc/config/DatabaseInitializer.java

@@ -3519,6 +3519,10 @@ insertSysConfigSeed("gift_membership_pay_price", "198000", "送会员商品达
         } catch (Exception e) {
             log.warn("迁移469: five_dimension_scores.source_type 注释校准失败(幂等容忍): {}", e.getMessage());
         }
+
+        // 迁移470: 创建模型管理表 mind_model
+        //(mind.model.manage · SC-A-21 舌诊/情绪模型版本/开关:版控/上下线/下线前回退方案)
+        createMindModelTable();
     }
 
     /**
@@ -15787,6 +15791,31 @@ log.info("迁移298: 已为无 openid 的 child 账号补齐 family_members 记
         }
     }
 
+    /**
+     * 迁移470: 创建模型管理表 mind_model(能力键 mind.model.manage · SC-A-21 舌诊/情绪模型版本/开关)。
+     *
+     * <p>承载模型版本/开关数据载体(AC-1):model_type(emotion|tongue)、version、enabled(上下线开关)、
+     * fallback_version(下线前回退方案,AC-3);uk_model_type_version 唯一约束保证同一类型下版本唯一。
+     * 幂等(CREATE TABLE IF NOT EXISTS)。</p>
+     */
+    private void createMindModelTable() {
+        try {
+            jdbcTemplate.execute("CREATE TABLE IF NOT EXISTS mind_model ("
+                    + "id BIGINT AUTO_INCREMENT PRIMARY KEY, "
+                    + "model_type VARCHAR(32) NOT NULL COMMENT '模型类型: emotion(情绪)/tongue(舌诊)', "
+                    + "version VARCHAR(64) NOT NULL COMMENT '模型版本号(如 v1/v2)', "
+                    + "enabled TINYINT DEFAULT 1 COMMENT '上下线开关: 1=上线 0=下线', "
+                    + "fallback_version VARCHAR(64) NULL COMMENT '下线前回退版本(回退方案,AC-3)', "
+                    + "created_at DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', "
+                    + "updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', "
+                    + "UNIQUE KEY uk_model_type_version (model_type, version) "
+                    + ") ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='舌诊/情绪模型版本管理(SC-A-21)'");
+            log.info("迁移470: 已创建 mind_model 表");
+        } catch (Exception e) {
+            log.warn("迁移470: 创建 mind_model 表失败(可能已存在): {}", e.getMessage());
+        }
+    }
+
     /** 幂等 upsert 维度种子:按 dimension_code 存在则补 source_system/legacy_alias,不存在则插入。 */
     private void upsertDimensionSeed(String code, String name, String dimensionType, Long parentId,
                                      int sort, String sourceSystem, String nodeKind,

+ 42 - 0
cfc-backend/src/main/java/com/etotem/cfc/controller/ContentFilterController.java

@@ -10,6 +10,8 @@ import com.etotem.cfc.mapper.ArticleMapper;
 import com.etotem.cfc.mapper.FoodMapper;
 import com.etotem.cfc.mapper.HealthKnowledgeBaseMapper;
 import com.etotem.cfc.mapper.ProblemDomainMapper;
+import com.etotem.cfc.service.api.WechatServiceInterface;
+import com.etotem.cfc.util.PlanContentSafetyUtil;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import javax.annotation.Resource;
@@ -47,6 +49,10 @@ public class ContentFilterController {
     @Resource
     private ProblemDomainMapper problemDomainMapper;
 
+    /** SC-T-28:方案内容安全复核原语(wechatService.checkText,true=安全) */
+    @Resource
+    private WechatServiceInterface wechatService;
+
     @Operation(summary = "按 resultTags + 问题域 code 过滤文章/知识库/饮食")
     @PostMapping("/by-tags")
     public Result<Map<String, Object>> byTags(@RequestBody Map<String, Object> params) {
@@ -83,6 +89,42 @@ public class ContentFilterController {
         return Result.success(data);
     }
 
+    /**
+     * SC-T-28:方案内容安全复核端点(AI 方案送审/发布前调用,命中即拦截)。
+     * 请求体支持 {@code content}(方案正文)或 {@code planContent}/{@code planJson}(直接传入方案字段)。
+     */
+    @Operation(summary = "方案内容安全复核(SC-T-28,命中即拦截)")
+    @PostMapping("/plan-safety")
+    public Result<Map<String, Object>> planSafety(@RequestBody(required = false) Map<String, Object> params) {
+        String content = null;
+        if (params != null) {
+            Object raw = params.get("content");
+            if (raw != null) content = String.valueOf(raw);
+            if (content == null || content.trim().isEmpty()) {
+                Object planContent = params.get("planContent");
+                if (planContent != null) content = String.valueOf(planContent);
+            }
+            if (content == null || content.trim().isEmpty()) {
+                Object planJson = params.get("planJson");
+                if (planJson != null) content = String.valueOf(planJson);
+            }
+        }
+        if (content == null || content.trim().isEmpty()) {
+            return Result.error("content不能为空");
+        }
+
+        String unsafe = PlanContentSafetyUtil.matchUnsafeTerm(content);
+        if (unsafe == null && wechatService != null && !wechatService.checkText(content)) {
+            unsafe = "第三方内容安全检测未通过";
+        }
+
+        Map<String, Object> resp = new HashMap<>();
+        resp.put("safe", unsafe == null);
+        resp.put("hitTerm", unsafe);
+        resp.put("message", unsafe == null ? "内容安全" : "命中违规词:「" + unsafe + "」");
+        return Result.success(resp);
+    }
+
     /** 文章:tags 字段 LIKE 任一标签 */
     private List<Article> filterArticles(Set<String> tags, int size) {
         if (tags.isEmpty()) {

+ 69 - 0
cfc-backend/src/main/java/com/etotem/cfc/controller/admin/AdminAfterSalesController.java

@@ -14,6 +14,18 @@ import java.util.List;
 import java.util.Map;
 import com.etotem.cfc.util.ParamUtils;
 
+/**
+ * 管理端-商城售后人工处理(能力键 {@code admin.order.manual},SC-A-12)。
+ *
+ * <p><b>B-142-1 双层防线(TR-13 权限流)</b>:{@code JwtInterceptor} 已把 {@code /api/admin/} 整族收口为
+ * 「必须登录」(匿名 → 401),但框架层不区分角色——登录的 parent/child/teacher 仍可越权查看/审核/完成售后。
+ * 故本控制器在 <b>HTTP 路由入口</b> 再做角色守卫:仅 {@code admin} 可操作,非 admin → 403「无权限」,
+ * 且不触达 service。
+ *
+ * <p><b>重载约定</b>:每个端点保留「HTTP 路由重载(带角色守卫)」与「契约直调重载(不带守卫,仅承载业务委托)」
+ * 两个同名方法——后者供契约单测/内部直接调用锁定「委托 service」契约(见
+ * {@code AdminOrderManualContractTest} 正常流绿锚点),HTTP 请求一律走带守卫的前者。
+ */
 @RestController
 @RequestMapping("/api/admin/shop/after-sales")
 public class AdminAfterSalesController {
@@ -22,20 +34,63 @@ public class AdminAfterSalesController {
     private AfterSalesService afterSalesService;
 
     @PostMapping("/list")
+    public Result<List<AfterSalesRequest>> list(@RequestBody Map<String, Object> params,
+                                                @RequestAttribute("role") String role) {
+        // B-142-1:角色守卫——非 admin 不得越权查看全量售后
+        if (!"admin".equals(role)) {
+            return Result.forbidden("无权限");
+        }
+        return doList(params);
+    }
+
+    /** 契约直调重载(非 HTTP 路由):锁定「委托 afterSalesService.adminList」契约,HTTP 请走带角色守卫的路由重载。 */
     public Result<List<AfterSalesRequest>> list(@RequestBody Map<String, Object> params) {
+        return doList(params);
+    }
+
+    private Result<List<AfterSalesRequest>> doList(Map<String, Object> params) {
         String status = params != null ? (String) params.get("status") : null;
         return afterSalesService.adminList(status);
     }
 
     @PostMapping("/detail")
+    public Result<AfterSalesRequest> detail(@RequestBody Map<String, Object> params,
+                                            @RequestAttribute("role") String role) {
+        // B-142-1:角色守卫——非 admin 不得越权查看售后详情
+        if (!"admin".equals(role)) {
+            return Result.forbidden("无权限");
+        }
+        return doDetail(params);
+    }
+
+    /** 契约直调重载(非 HTTP 路由):锁定「委托 afterSalesService.adminDetail」契约,HTTP 请走带角色守卫的路由重载。 */
     public Result<AfterSalesRequest> detail(@RequestBody Map<String, Object> params) {
+        return doDetail(params);
+    }
+
+    private Result<AfterSalesRequest> doDetail(Map<String, Object> params) {
         Long id = ParamUtils.getLong(params.get("id"));
         return afterSalesService.adminDetail(id);
     }
 
     @PostMapping("/review")
+    public Result<String> review(@RequestBody Map<String, Object> params,
+                                 @RequestAttribute("userId") Long adminId,
+                                 @RequestAttribute("role") String role) {
+        // B-142-1:角色守卫——非 admin 不得越权审核售后(仅待审核可处理,见 AfterSalesService.review)
+        if (!"admin".equals(role)) {
+            return Result.forbidden("无权限");
+        }
+        return doReview(params, adminId);
+    }
+
+    /** 契约直调重载(非 HTTP 路由):锁定「委托 afterSalesService.review」契约,HTTP 请走带角色守卫的路由重载。 */
     public Result<String> review(@RequestBody Map<String, Object> params,
                                  @RequestAttribute("userId") Long adminId) {
+        return doReview(params, adminId);
+    }
+
+    private Result<String> doReview(Map<String, Object> params, Long adminId) {
         Long id = ParamUtils.getLong(params.get("id"));
         String action = (String) params.get("action");
         String rejectReason = (String) params.get("rejectReason");
@@ -43,7 +98,21 @@ public class AdminAfterSalesController {
     }
 
     @PostMapping("/complete")
+    public Result<String> complete(@RequestBody Map<String, Object> params,
+                                   @RequestAttribute("role") String role) {
+        // B-142-1:角色守卫——非 admin 不得越权完成售后
+        if (!"admin".equals(role)) {
+            return Result.forbidden("无权限");
+        }
+        return doComplete(params);
+    }
+
+    /** 契约直调重载(非 HTTP 路由):锁定「委托 afterSalesService.complete」契约,HTTP 请走带角色守卫的路由重载。 */
     public Result<String> complete(@RequestBody Map<String, Object> params) {
+        return doComplete(params);
+    }
+
+    private Result<String> doComplete(Map<String, Object> params) {
         Long id = ParamUtils.getLong(params.get("id"));
         return afterSalesService.complete(id);
     }

+ 112 - 2
cfc-backend/src/main/java/com/etotem/cfc/controller/admin/AdminProductOrderController.java

@@ -1,5 +1,6 @@
 package com.etotem.cfc.controller.admin;
 
+import com.etotem.cfc.common.AdminRoles;
 import com.etotem.cfc.common.Result;
 import com.etotem.cfc.dto.ProductOrderDTO;
 import com.etotem.cfc.service.ProductOrderService;
@@ -16,6 +17,22 @@ import java.util.List;
 import java.util.Map;
 import com.etotem.cfc.util.SortUtil;
 
+/**
+ * 管理端-订单人工处理(能力键 {@code admin.order.manual},SC-A-12)。
+ *
+ * <p><b>B-142-1 双层防线(TR-13 权限流)</b>:{@code JwtInterceptor} 已把 {@code /api/admin/} 整族收口为
+ * 「必须登录」(匿名 → 401),但框架层不区分角色——登录的 parent/child/teacher 仍可越权发货、关单、
+ * 审批退款。故本控制器在 <b>HTTP 路由入口</b> 再做角色守卫:
+ * <ul>
+ *   <li>{@code /list}:平台角色(admin/operator/finance)与纯供应商(B-5 行级隔离)放行,
+ *       其余(C 端角色 parent/child 等)→ 403,避免拉取全量订单;</li>
+ *   <li>其余 6 个端点:仅 {@code admin} 可操作,非 admin → 403「无权限」,且不触达 service。</li>
+ * </ul>
+ *
+ * <p><b>重载约定</b>:每个端点保留「HTTP 路由重载(带角色守卫)」与「契约直调重载(不带守卫,仅承载业务委托)」
+ * 两个同名方法——后者供契约单测/内部直接调用锁定「委托 service」契约(见
+ * {@code AdminOrderManualContractTest} 正常流绿锚点),HTTP 请求一律走带守卫的前者。
+ */
 @RestController
 @RequestMapping("/api/admin/product/order")
 @Tag(name = "管理端-订单管理")
@@ -29,6 +46,11 @@ public class AdminProductOrderController {
     public Result<Map<String, Object>> list(@RequestBody Map<String, Object> params,
                                             @RequestAttribute(value = "userId", required = false) Long userId,
                                             @RequestAttribute(value = "roles", required = false) java.util.List<String> roleList) {
+        // B-142-1:/api/admin/** 框架层只保证登录,controller 层须再校验角色——C 端角色(parent/child)
+        // 不得越权查看订单;平台角色与纯供应商(B-5 行级隔离)放行。
+        if (!AdminRoles.hasAnyPlatformRole(roleList) && !AdminRoles.isSupplierOnly(roleList)) {
+            return Result.forbidden("无权限");
+        }
         String status = (String) params.get("status");
         String keyword = (String) params.get("keyword");
         String buyerKeyword = (String) params.get("buyerKeyword");
@@ -47,7 +69,21 @@ public class AdminProductOrderController {
 
     @Operation(summary = "订单详情")
     @PostMapping("/detail")
+    public Result<ProductOrderDTO> detail(@RequestBody Map<String, Object> params,
+                                          @RequestAttribute("role") String role) {
+        // B-142-1:角色守卫——非 admin(parent/child/teacher)不得越权查看订单详情
+        if (!"admin".equals(role)) {
+            return Result.forbidden("无权限");
+        }
+        return doDetail(params);
+    }
+
+    /** 契约直调重载(非 HTTP 路由):锁定「委托 orderService.adminOrderDetail」契约,HTTP 请走带角色守卫的路由重载。 */
     public Result<ProductOrderDTO> detail(@RequestBody Map<String, Object> params) {
+        return doDetail(params);
+    }
+
+    private Result<ProductOrderDTO> doDetail(Map<String, Object> params) {
         String orderNo = (String) params.get("orderNo");
         if (orderNo == null || orderNo.isEmpty()) {
             return Result.error("orderNo不能为空");
@@ -57,8 +93,23 @@ public class AdminProductOrderController {
 
     @Operation(summary = "订单发货(含快递单号+快递费)")
     @PostMapping("/ship")
+    public Result<String> ship(@RequestBody Map<String, Object> params,
+                               @RequestAttribute("userId") Long adminId,
+                               @RequestAttribute("role") String role) {
+        // B-142-1:角色守卫——非 admin 不得越权发货
+        if (!"admin".equals(role)) {
+            return Result.forbidden("无权限");
+        }
+        return doShip(params);
+    }
+
+    /** 契约直调重载(非 HTTP 路由):锁定「委托 orderService.ship」契约,HTTP 请走带角色守卫的路由重载。 */
     public Result<String> ship(@RequestBody Map<String, Object> params,
                                @RequestAttribute("userId") Long adminId) {
+        return doShip(params);
+    }
+
+    private Result<String> doShip(Map<String, Object> params) {
         String orderNo = (String) params.get("orderNo");
         String shipType = (String) params.get("shipType");
         String trackingNumber = (String) params.get("trackingNumber");
@@ -71,7 +122,21 @@ public class AdminProductOrderController {
 
     @Operation(summary = "更新订单快递信息")
     @PostMapping("/update-express")
+    public Result<String> updateExpress(@RequestBody Map<String, Object> params,
+                                         @RequestAttribute("role") String role) {
+        // B-142-1:角色守卫——非 admin 不得越权修改快递信息
+        if (!"admin".equals(role)) {
+            return Result.forbidden("无权限");
+        }
+        return doUpdateExpress(params);
+    }
+
+    /** 契约直调重载(非 HTTP 路由):锁定「委托 orderService.updateExpress」契约,HTTP 请走带角色守卫的路由重载。 */
     public Result<String> updateExpress(@RequestBody Map<String, Object> params) {
+        return doUpdateExpress(params);
+    }
+
+    private Result<String> doUpdateExpress(Map<String, Object> params) {
         String orderNo = (String) params.get("orderNo");
         String trackingNumber = (String) params.get("trackingNumber");
         String expressCompany = (String) params.get("expressCompany");
@@ -83,7 +148,22 @@ public class AdminProductOrderController {
     @Operation(summary = "关闭订单")
     @PostMapping("/close")
     public Result<String> close(@RequestBody Map<String, Object> params,
-                                  @RequestAttribute("userId") Long adminId) {
+                                @RequestAttribute("userId") Long adminId,
+                                @RequestAttribute("role") String role) {
+        // B-142-1:角色守卫——非 admin 不得越权关单
+        if (!"admin".equals(role)) {
+            return Result.forbidden("无权限");
+        }
+        return doClose(params, adminId);
+    }
+
+    /** 契约直调重载(非 HTTP 路由):锁定「委托 orderService.adminClose」契约,HTTP 请走带角色守卫的路由重载。 */
+    public Result<String> close(@RequestBody Map<String, Object> params,
+                                @RequestAttribute("userId") Long adminId) {
+        return doClose(params, adminId);
+    }
+
+    private Result<String> doClose(Map<String, Object> params, Long adminId) {
         String orderNo = (String) params.get("orderNo");
         if (orderNo == null || orderNo.isEmpty()) {
             return Result.error("orderNo不能为空");
@@ -93,18 +173,48 @@ public class AdminProductOrderController {
 
     @Operation(summary = "退款审核通过")
     @PostMapping("/refund/approve")
+    public Result<String> approveRefund(@RequestBody Map<String, Object> params,
+                                        @RequestAttribute("userId") Long adminId,
+                                        @RequestAttribute("role") String role) {
+        // B-142-1:角色守卫——非 admin 不得越权审批退款
+        if (!"admin".equals(role)) {
+            return Result.forbidden("无权限");
+        }
+        return doApproveRefund(params, adminId);
+    }
+
+    /** 契约直调重载(非 HTTP 路由):锁定「委托 orderService.approveRefund」契约,HTTP 请走带角色守卫的路由重载。 */
     public Result<String> approveRefund(@RequestBody Map<String, Object> params,
                                         @RequestAttribute("userId") Long adminId) {
+        return doApproveRefund(params, adminId);
+    }
+
+    private Result<String> doApproveRefund(Map<String, Object> params, Long adminId) {
         String orderNo = (String) params.get("orderNo");
         return orderService.approveRefund(orderNo, adminId);
     }
 
     @Operation(summary = "退款审核拒绝")
     @PostMapping("/refund/reject")
+    public Result<String> rejectRefund(@RequestBody Map<String, Object> params,
+                                       @RequestAttribute("userId") Long adminId,
+                                       @RequestAttribute("role") String role) {
+        // B-142-1:角色守卫——非 admin 不得越权驳回退款
+        if (!"admin".equals(role)) {
+            return Result.forbidden("无权限");
+        }
+        return doRejectRefund(params, adminId);
+    }
+
+    /** 契约直调重载(非 HTTP 路由):锁定「委托 orderService.rejectRefund」契约,HTTP 请走带角色守卫的路由重载。 */
     public Result<String> rejectRefund(@RequestBody Map<String, Object> params,
                                        @RequestAttribute("userId") Long adminId) {
+        return doRejectRefund(params, adminId);
+    }
+
+    private Result<String> doRejectRefund(Map<String, Object> params, Long adminId) {
         String orderNo = (String) params.get("orderNo");
         String reason = (String) params.get("reason");
         return orderService.rejectRefund(orderNo, adminId, reason);
     }
-}
+}

+ 48 - 0
cfc-backend/src/main/java/com/etotem/cfc/controller/admin/MindModelManageController.java

@@ -0,0 +1,48 @@
+package com.etotem.cfc.controller.admin;
+
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.entity.MindModel;
+import com.etotem.cfc.service.MindModelManageService;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import javax.annotation.Resource;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 舌诊/情绪模型版本管理(能力键 mind.model.manage · SC-A-21)。
+ *
+ * <p>平台运营内部模型管理:版本列表(list)/ 上线(online)/ 下线(offline,须指定回退版本)。
+ * 所有接口统一 {@code @PostMapping}。</p>
+ */
+@Slf4j
+@RestController
+@RequestMapping("/api/admin/mind-model")
+public class MindModelManageController {
+
+    @Resource
+    private MindModelManageService mindModelManageService;
+
+    /** 版本列表(版控,AC-2)。 */
+    @PostMapping("/list")
+    public Result<List<MindModel>> list() {
+        return mindModelManageService.listAll();
+    }
+
+    /** 上线(AC-2);请求体: { "modelType": "emotion|tongue", "version": "v1" }。 */
+    @PostMapping("/online")
+    public Result<Void> online(@RequestBody Map<String, String> params) {
+        return mindModelManageService.online(params.get("modelType"), params.get("version"));
+    }
+
+    /** 下线(AC-3 须指定回退版本);请求体: { "modelType": "emotion|tongue", "version": "v1", "fallbackVersion": "v1" }。 */
+    @PostMapping("/offline")
+    public Result<Void> offline(@RequestBody Map<String, String> params) {
+        return mindModelManageService.offline(
+                params.get("modelType"), params.get("version"), params.get("fallbackVersion"));
+    }
+}

+ 39 - 0
cfc-backend/src/main/java/com/etotem/cfc/entity/MindModel.java

@@ -0,0 +1,39 @@
+package com.etotem.cfc.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+import java.io.Serializable;
+import java.util.Date;
+
+/**
+ * 舌诊/情绪模型版本管理实体(能力键 mind.model.manage · SC-A-21)。
+ *
+ * <p>承载模型版本/开关的数据载体:{@code modelType}(emotion|tongue)、{@code version}、
+ * {@code enabled}(上下线开关)、{@code fallbackVersion}(下线前回退方案)。</p>
+ */
+@Data
+@TableName("mind_model")
+public class MindModel implements Serializable {
+
+    @TableId(type = IdType.AUTO)
+    private Long id;
+
+    /** 模型类型: emotion(情绪)/tongue(舌诊)。 */
+    private String modelType;
+
+    /** 模型版本号(如 v1/v2)。 */
+    private String version;
+
+    /** 上下线开关: 1=上线 0=下线。 */
+    private Integer enabled;
+
+    /** 下线前回退版本(AC-3:未指定回退方案不得下线)。 */
+    private String fallbackVersion;
+
+    private Date createdAt;
+
+    private Date updatedAt;
+}

+ 9 - 0
cfc-backend/src/main/java/com/etotem/cfc/mapper/MindModelMapper.java

@@ -0,0 +1,9 @@
+package com.etotem.cfc.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.etotem.cfc.entity.MindModel;
+import org.apache.ibatis.annotations.Mapper;
+
+@Mapper
+public interface MindModelMapper extends BaseMapper<MindModel> {
+}

+ 128 - 0
cfc-backend/src/main/java/com/etotem/cfc/service/MindModelManageService.java

@@ -0,0 +1,128 @@
+package com.etotem.cfc.service;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.entity.MindModel;
+import com.etotem.cfc.mapper.MindModelMapper;
+import lombok.extern.slf4j.Slf4j;
+import org.apache.commons.lang3.StringUtils;
+import org.springframework.stereotype.Service;
+
+import javax.annotation.Resource;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.regex.Pattern;
+
+/**
+ * 舌诊/情绪模型版本管理服务(能力键 mind.model.manage · SC-A-21)。
+ *
+ * <p>契约 AC 条款:</p>
+ * <ul>
+ *   <li><b>AC-2 版控/上下线</b>:{@code listAll} 版本列表、{@code online}/{@code offline} 上下线入口、{@code isEnabled} 开关查询。</li>
+ *   <li><b>AC-3 下线前回退方案</b>:{@code offline} 必须指定 {@code fallbackVersion},未指定回退方案时拒绝下线(Result 400)。</li>
+ *   <li><b>AC-4 非法版本 400</b>:对非法/未知版本的操作返回 Result code 400。</li>
+ * </ul>
+ *
+ * <p>注意:契约单测以无参构造直接实例化宿主(mapper 未装配为 null),服务逻辑对 null mapper 防御式兜底
+ * (未知版本/非法版本一律 400),保证行为级契约在无 DB 环境下可判定。</p>
+ */
+@Slf4j
+@Service
+public class MindModelManageService {
+
+    /** 版本号规范:v 开头 + 数字(如 v1、v2)。 */
+    private static final Pattern VERSION_PATTERN = Pattern.compile("^v\\d+$");
+
+    @Resource
+    private MindModelMapper mindModelMapper;
+
+    /**
+     * 版本列表(版控,AC-2):按模型类型 + 版本升序返回全部模型版本。
+     */
+    public Result<List<MindModel>> listAll() {
+        if (mindModelMapper == null) {
+            return Result.success(new ArrayList<>());
+        }
+        return Result.success(mindModelMapper.selectList(
+                new LambdaQueryWrapper<MindModel>()
+                        .orderByAsc(MindModel::getModelType)
+                        .orderByAsc(MindModel::getVersion)));
+    }
+
+    /**
+     * 上线(AC-2/AC-4):将指定版本置为 enabled=1。
+     * 非法/未知版本返回 Result code 400。
+     */
+    public Result<Void> online(String modelType, String version) {
+        if (StringUtils.isBlank(modelType) || StringUtils.isBlank(version)) {
+            return Result.badRequest("模型类型与版本不能为空");
+        }
+        if (!VERSION_PATTERN.matcher(version).matches()) {
+            return Result.badRequest("非法模型版本号:" + version + "(应为 v+数字,如 v1)");
+        }
+        MindModel model = queryByTypeAndVersion(modelType, version);
+        if (model == null) {
+            return Result.badRequest("未知模型版本,无法上线:" + modelType + "@" + version);
+        }
+        if (model.getEnabled() != null && model.getEnabled() == 1) {
+            return Result.success();
+        }
+        model.setEnabled(1);
+        mindModelMapper.updateById(model);
+        log.info("mind.model.manage: 模型上线 modelType={}, version={}", modelType, version);
+        return Result.success();
+    }
+
+    /**
+     * 下线(AC-2/AC-3/AC-4):将指定版本置为 enabled=0 并记录回退版本。
+     * 未指定回退版本(fallbackVersion 为空)时拒绝下线,返回 Result code 400;
+     * 非法/未知版本返回 Result code 400。
+     */
+    public Result<Void> offline(String modelType, String version, String fallbackVersion) {
+        if (StringUtils.isBlank(modelType) || StringUtils.isBlank(version)) {
+            return Result.badRequest("模型类型与版本不能为空");
+        }
+        if (StringUtils.isBlank(fallbackVersion)) {
+            return Result.badRequest("下线前必须指定回退版本(fallbackVersion)");
+        }
+        if (!VERSION_PATTERN.matcher(version).matches()) {
+            return Result.badRequest("非法模型版本号:" + version + "(应为 v+数字,如 v1)");
+        }
+        MindModel model = queryByTypeAndVersion(modelType, version);
+        if (model == null) {
+            return Result.badRequest("未知模型版本,无法下线:" + modelType + "@" + version);
+        }
+        model.setEnabled(0);
+        model.setFallbackVersion(fallbackVersion);
+        mindModelMapper.updateById(model);
+        log.info("mind.model.manage: 模型下线 modelType={}, version={}, fallbackVersion={}",
+                modelType, version, fallbackVersion);
+        return Result.success();
+    }
+
+    /**
+     * 开关查询(AC-1/AC-2):指定模型类型是否存在已上线版本(enabled=1)。
+     */
+    public boolean isEnabled(String modelType) {
+        if (mindModelMapper == null || StringUtils.isBlank(modelType)) {
+            return false;
+        }
+        MindModel model = mindModelMapper.selectOne(
+                new LambdaQueryWrapper<MindModel>()
+                        .eq(MindModel::getModelType, modelType)
+                        .eq(MindModel::getEnabled, 1)
+                        .last("LIMIT 1"));
+        return model != null;
+    }
+
+    /** 按模型类型 + 版本精确查询(映射唯一键 uk_model_type_version)。 */
+    private MindModel queryByTypeAndVersion(String modelType, String version) {
+        if (mindModelMapper == null) {
+            return null;
+        }
+        return mindModelMapper.selectOne(
+                new LambdaQueryWrapper<MindModel>()
+                        .eq(MindModel::getModelType, modelType)
+                        .eq(MindModel::getVersion, version));
+    }
+}

+ 38 - 0
cfc-backend/src/main/java/com/etotem/cfc/service/impl/HealthPlanServiceImpl.java

@@ -28,6 +28,8 @@ import com.etotem.cfc.service.AttributionAnalysisService;
 import com.etotem.cfc.service.CartService;
 import com.etotem.cfc.service.HealthPlanService;
 import com.etotem.cfc.service.ProductRecommendationService;
+import com.etotem.cfc.service.api.WechatServiceInterface;
+import com.etotem.cfc.util.PlanContentSafetyUtil;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.http.ResponseEntity;
@@ -98,6 +100,10 @@ public class HealthPlanServiceImpl implements HealthPlanService {
     @Resource
     private CartService cartService;
 
+    /** SC-T-28:AI 方案内容安全复核原语(wechatService.checkText,true=安全) */
+    @Resource
+    private WechatServiceInterface wechatService;
+
     @Resource
     private ProductMapper productMapper;
 
@@ -1928,6 +1934,11 @@ public class HealthPlanServiceImpl implements HealthPlanService {
         if (!"pending_review".equals(plan.getStatus()) && !"draft".equals(plan.getStatus())) {
             throw new RuntimeException("方案状态不允许审核");
         }
+        // SC-T-28 AI 方案内容安全复核:命中即拦截,未通过不得发布(不落库、状态保持待审核)
+        String unsafe = detectUnsafePlanContent(plan);
+        if (unsafe != null) {
+            throw new RuntimeException("方案内容未通过安全复核:" + unsafe);
+        }
         plan.setStatus("published");
         plan.setReviewedBy(reviewedBy);
         plan.setReviewedAt(new Date());
@@ -1986,6 +1997,33 @@ public class HealthPlanServiceImpl implements HealthPlanService {
         return plan;
     }
 
+    /**
+     * SC-T-28 AI 方案内容安全复核(命中即拦截,fail-closed):
+     * <ol>
+     *   <li>内置敏感词/违规医疗主张检测(基础闸门,无条件执行);</li>
+     *   <li>外部内容安全原语 {@link WechatServiceInterface#checkText(String)} 叠加复核
+     *       (可用时执行,true=安全、false=拦截;wechatService 未注入时跳过,不阻碍内置闸门)。</li>
+     * </ol>
+     *
+     * @return 复核未通过原因;通过则返回 null
+     */
+    private String detectUnsafePlanContent(HealthPlan plan) {
+        if (plan == null) return null;
+        String content = plan.getPlanContent();
+        String text = (content == null || content.trim().isEmpty()) ? plan.getPlanJson() : content;
+        if (text == null || text.trim().isEmpty()) {
+            return null; // 无正文内容可复核,放行(结构校验不在此范围)
+        }
+        String hit = PlanContentSafetyUtil.matchUnsafeTerm(text);
+        if (hit != null) {
+            return "命中违规词「" + hit + "」";
+        }
+        if (wechatService != null && !wechatService.checkText(text)) {
+            return "第三方内容安全检测未通过";
+        }
+        return null;
+    }
+
     // 待生成任务的草稿:标题 + 类别中文标签 + 五维维度码 + 频率(once/daily)+ 父任务ID(购买→使用链)
     private static class TaskDraft {
         final String title;

+ 33 - 0
cfc-backend/src/main/java/com/etotem/cfc/util/PlanContentSafetyUtil.java

@@ -0,0 +1,33 @@
+package com.etotem.cfc.util;
+
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * SC-T-28 内容安全复核的敏感词/违规医疗主张检测工具类。
+ * 采用 fail-closed 策略:命中敏感词/违规主张则拦截(返回非null),否则返回null。
+ * 核心关键字覆盖:祖传秘方, 包治百病, 根治, 无资质, 停用处方药等医疗夸大/违规主张。
+ */
+public final class PlanContentSafetyUtil {
+    private static final Pattern UNSAFE_PATTERN = Pattern.compile(
+            "祖传秘方|包治百病|根治|断根|药到病除|神药|偏方|秘方|无资质|停用处方药|停用处方|替代药物|代替药物|无需就医|不用就医|治愈率100%|强效药"
+    );
+
+    private PlanContentSafetyUtil() {}
+
+    /**
+     * 检测文本是否命中敏感/违规医疗主张。
+     * @param text 待检测的文本内容。
+     * @return 命中关键词,或 null 表示安全。
+     */
+    public static String matchUnsafeTerm(String text) {
+        if (text == null || text.trim().isEmpty()) {
+            return null;
+        }
+        Matcher matcher = UNSAFE_PATTERN.matcher(text);
+        if (matcher.find()) {
+            return matcher.group(); // 返回实际命中的词汇
+        }
+        return null;
+    }
+}

+ 14 - 0
cfc-backend/src/main/resources/schema.sql

@@ -7239,3 +7239,17 @@ CREATE TABLE IF NOT EXISTS mind_psychological_assessments (
     INDEX idx_member_date (member_id, assessment_date),
     INDEX idx_guide (guide_id)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='心理测评记录(舌诊/情绪统一录入,SC-T-25)';
+
+-- ============================================================
+-- 模型管理表(迁移470,mind.model.manage · SC-A-21 舌诊/情绪模型版本/开关)
+-- ============================================================
+CREATE TABLE IF NOT EXISTS mind_model (
+    id BIGINT AUTO_INCREMENT PRIMARY KEY,
+    model_type VARCHAR(32) NOT NULL COMMENT '模型类型: emotion(情绪)/tongue(舌诊)',
+    version VARCHAR(64) NOT NULL COMMENT '模型版本号(如 v1/v2)',
+    enabled TINYINT DEFAULT 1 COMMENT '上下线开关: 1=上线 0=下线',
+    fallback_version VARCHAR(64) NULL COMMENT '下线前回退版本(回退方案,AC-3)',
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+    UNIQUE KEY uk_model_type_version (model_type, version)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='舌诊/情绪模型版本管理(SC-A-21)';

+ 276 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/ActivityCheckinBoostContractTest.java

@@ -0,0 +1,276 @@
+package com.etotem.cfc.unit;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.lang.reflect.Method;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assertions.fail;
+
+/**
+ * 契约级单测:活动打卡/助力(营销)进度累计与反刷量(能力键 {@code activity.checkin.boost},单元 activity)。
+ *
+ * <p><b>需求/设计锚点</b></p>
+ * <ul>
+ *   <li>需求:{@code tests/user-scenarios/应用场景总览.md} SC-P-77(活动打卡/助力·营销)——
+ *       主流程「打卡 → 进度累计 → 助力」;异常/边界「重复打卡幂等;刷量/机器行为拦截」;
+ *       CF 值预估「打卡/助力为平台 CF 值产出点,操作入口须按 SC-X-22 展示『本操作预计 +N CF』」</li>
+ *   <li>设计:{@code docs/superpowers/api/API_REFERENCE.md} §4.7 健康打卡(/api/daily/checkin、
+ *       /api/mind/checkin 情绪日记同步)+ 活动打卡(AdminActivityCheckinController
+ *       /api/admin/activity-checkins);模块:活动({@code ActivityService.checkin} 现状为
+ *       一次性签到任务,无进度累计/助力/反刷量/CF 预估)</li>
+ * </ul>
+ *
+ * <p><b>被校验的契约行为</b></p>
+ * <ul>
+ *   <li>打卡 → 进度累计:同一活动下某成员打卡一次,进度 +1;连续打卡逐次累计</li>
+ *   <li>助力 → 进度累计:他人为目标成员助力一次,目标进度 +1;打卡后再助力继续累计</li>
+ *   <li>重复打卡幂等:同一 (activityId, memberId) 重复打卡,进度不重复累计,返回既有进度</li>
+ *   <li>刷量/机器行为拦截:窗口内高频打卡判为刷量应拒绝;同一设备短时关联多账号判为机器行为应拒绝</li>
+ *   <li>CF 值预估(SC-X-22):打卡/助力入口应返回「本操作预计 +N CF」的预估(非负,规则未配置可降级为 0)</li>
+ * </ul>
+ *
+ * <p><b>宿主契约(TDD-RED 锚点)</b>:{@code com.etotem.cfc.service.ActivityCheckinBoostService} ——
+ * 承载活动打卡/助力营销进度的服务类,当前(2026-11-14)<b>尚未实现</b>。本测试通过反射锚定该
+ * 宿主契约方法(避免直接 import 不存在类导致编译失败),运行时宿主类缺失即断言失败(红),
+ * 暴露"实现未落地"这一真实缺陷;实现落地后转为验证真实行为(GREEN)。</p>
+ *
+ * <p><b>契约方法签名(实现方按此落地)</b></p>
+ * <ul>
+ *   <li>{@code int checkin(long activityId, long userId, long memberId, String deviceId)}
+ *       —— 打卡一次,进度 +1,返回该成员本次活动累计进度</li>
+ *   <li>{@code int boost(long activityId, long targetUserId, long helperUserId, String deviceId)}
+ *       —— 助力目标成员,目标进度 +1,返回目标成员累计进度</li>
+ *   <li>{@code int checkinProgress(long activityId, long memberId)}
+ *       —— 查询该成员本次活动累计进度</li>
+ *   <li>{@code int expectedCf(long activityId, String actionType)}
+ *       —— SC-X-22 CF 值预估:actionType ∈ {@code checkin}/{@code boost},返回本操作预计获得 CF
+ *       (规则未配置可降级为 0,不得为负)</li>
+ *   <li>{@code boolean shouldRejectCheckin(int checkinsInWindow, int windowSeconds)}
+ *       —— 刷量拦截判定(纯函数):窗口内打卡次数超过阈值(如 60s 内 ≥ 5 次)应返回 true</li>
+ *   <li>{@code boolean shouldRejectMachineAbuse(int accountsOnDeviceInWindow, int windowHours)}
+ *       —— 机器行为拦截判定(纯函数):同一设备窗口内关联账号数超过阈值(如 1h 内 ≥ 3 账号)应返回 true</li>
+ * </ul>
+ *
+ * <p><b>测试范围</b>:纯契约级单测,无 Spring / 无 DB / 无外部服务依赖(纯 Mockito/反射风格,
+ * 与同批已合入主链的 {@code TeamStarMultiplierContractTest} / {@code TeamProfitHookContractTest} 一致)。</p>
+ *
+ * <p><b>权限流说明</b>:SC-P-77 营销打卡/助力面向已报名活动成员,本契约聚焦进度累计/幂等/反刷量
+ * 与 CF 预估行为,无独立角色权限分支(权限校验由活动报名与身份门禁承载,属 {@code activity.enroll.join}
+ * 范围),故权限流以说明性用例标注不适用。</p>
+ *
+ * <p><b>RED 预期</b>:宿主 {@code ActivityCheckinBoostService} 未实现,全部用例在反射探测处失败(红),
+ * 断言原文为「RED[activity.checkin.boost] 契约宿主 ActivityCheckinBoostService 未实现(实现未落地)」。</p>
+ */
+class ActivityCheckinBoostContractTest {
+
+    /** 规格设计宿主类(未实现)。 */
+    private static final String HOST_CLASS = "com.etotem.cfc.service.ActivityCheckinBoostService";
+
+    // ==================== 契约常量(SC-P-77 边界) ====================
+
+    /** 示例活动 ID(营销活动)。 */
+    private static final long ACTIVITY_ID = 9001L;
+    /** 打卡成员(memberId)。 */
+    private static final long MEMBER_ID = 70001L;
+    /** 打卡操作账号(userId)。 */
+    private static final long USER_ID = 60001L;
+    /** 助力人账号(helperUserId)。 */
+    private static final long HELPER_USER_ID = 60002L;
+    /** 目标成员(targetUserId 对应的 memberId)。 */
+    private static final long TARGET_MEMBER_ID = 70002L;
+    /** 设备指纹(刷量/机器行为拦截维度)。 */
+    private static final String DEVICE_ID = "device-a1b2c3";
+
+    /** 刷量阈值锚点:60 秒窗口内 5 次及以上判为刷量(SC-P-77 反刷量)。 */
+    private static final int ABUSE_CHECKINS = 5;
+    private static final int ABUSE_WINDOW_SECONDS = 60;
+    /** 机器行为阈值锚点:1 小时窗口内同设备 3 个及以上账号判为机器行为。 */
+    private static final int MACHINE_ACCOUNTS = 3;
+    private static final int MACHINE_WINDOW_HOURS = 1;
+
+    // ==================== 正常流:打卡 → 进度累计 ====================
+
+    @Test
+    @DisplayName("正常流-1:首次打卡进度累计为 1")
+    void checkin_firstTime_progressIsOne() {
+        Object host = contractHost();
+        int progress = callInt(host, "checkin", ACTIVITY_ID, USER_ID, MEMBER_ID, DEVICE_ID);
+        assertEquals(1, progress, "首次打卡后累计进度应为 1");
+    }
+
+    @Test
+    @DisplayName("正常流-2:连续打卡进度逐次累计")
+    void checkin_consecutive_progressAccumulates() {
+        Object host = contractHost();
+        callInt(host, "checkin", ACTIVITY_ID, USER_ID, MEMBER_ID, DEVICE_ID);
+        callInt(host, "checkin", ACTIVITY_ID, USER_ID, MEMBER_ID, DEVICE_ID);
+        int progress = callInt(host, "checkin", ACTIVITY_ID, USER_ID, MEMBER_ID, DEVICE_ID);
+        assertEquals(3, progress, "连续打卡三次后累计进度应为 3");
+    }
+
+    @Test
+    @DisplayName("正常流-3:checkinProgress 查询返回累计值")
+    void checkinProgress_reflectsAccumulatedValue() {
+        Object host = contractHost();
+        callInt(host, "checkin", ACTIVITY_ID, USER_ID, MEMBER_ID, DEVICE_ID);
+        callInt(host, "checkin", ACTIVITY_ID, USER_ID, MEMBER_ID, DEVICE_ID);
+        int progress = callInt(host, "checkinProgress", ACTIVITY_ID, MEMBER_ID);
+        assertEquals(2, progress, "查询进度应与两次打卡累计一致(2)");
+    }
+
+    // ==================== 正常流:助力 → 目标进度累计 ====================
+
+    @Test
+    @DisplayName("正常流-4:助力使目标成员进度 +1")
+    void boost_addsOneToTargetProgress() {
+        Object host = contractHost();
+        callInt(host, "checkin", ACTIVITY_ID, USER_ID, TARGET_MEMBER_ID, DEVICE_ID);
+        int progress = callInt(host, "boost", ACTIVITY_ID, USER_ID, HELPER_USER_ID, DEVICE_ID);
+        assertEquals(2, progress, "目标打卡 1 次后再被助力 1 次,目标进度应为 2");
+    }
+
+    @Test
+    @DisplayName("正常流-5:打卡后再助力进度继续累计")
+    void checkinThenBoost_continuesAccumulation() {
+        Object host = contractHost();
+        callInt(host, "checkin", ACTIVITY_ID, USER_ID, MEMBER_ID, DEVICE_ID);
+        callInt(host, "checkin", ACTIVITY_ID, USER_ID, MEMBER_ID, DEVICE_ID);
+        int progress = callInt(host, "boost", ACTIVITY_ID, USER_ID, HELPER_USER_ID, DEVICE_ID);
+        assertEquals(3, progress, "打卡两次后再助力一次,累计进度应为 3");
+    }
+
+    // ==================== 边界流:重复打卡幂等 ====================
+
+    @Test
+    @DisplayName("边界流-1:重复打卡幂等,进度不重复累计")
+    void duplicateCheckin_idempotent_progressNotDoubleCounted() {
+        Object host = contractHost();
+        callInt(host, "checkin", ACTIVITY_ID, USER_ID, MEMBER_ID, DEVICE_ID);
+        int second = callInt(host, "checkin", ACTIVITY_ID, USER_ID, MEMBER_ID, DEVICE_ID);
+        assertEquals(1, second, "同一 (activityId, memberId) 重复打卡不得重复累计进度(幂等)");
+    }
+
+    // ==================== 边界流:刷量 / 机器行为拦截 ====================
+
+    @Test
+    @DisplayName("边界流-2:窗口内高频打卡判为刷量,应拒绝")
+    void highFrequencyCheckin_shouldReject() {
+        Object host = contractHost();
+        boolean reject = callBoolean(host, "shouldRejectCheckin", ABUSE_CHECKINS, ABUSE_WINDOW_SECONDS);
+        assertTrue(reject, "60 秒窗口内 5 次打卡应判为刷量并拒绝(SC-P-77 反刷量)");
+    }
+
+    @Test
+    @DisplayName("边界流-3:正常低频打卡不判刷量")
+    void normalFrequencyCheckin_notRejected() {
+        Object host = contractHost();
+        boolean reject = callBoolean(host, "shouldRejectCheckin", 1, ABUSE_WINDOW_SECONDS);
+        assertFalse(reject, "60 秒窗口内 1 次打卡属正常行为,不应拒绝");
+    }
+
+    @Test
+    @DisplayName("边界流-4:同设备短时多账号判为机器行为,应拒绝")
+    void sameDeviceMultiAccount_shouldReject() {
+        Object host = contractHost();
+        boolean reject = callBoolean(host, "shouldRejectMachineAbuse", MACHINE_ACCOUNTS, MACHINE_WINDOW_HOURS);
+        assertTrue(reject, "1 小时窗口内同设备 3 个账号应判为机器行为并拒绝");
+    }
+
+    @Test
+    @DisplayName("边界流-5:同设备单账号不判机器行为")
+    void sameDeviceSingleAccount_notRejected() {
+        Object host = contractHost();
+        boolean reject = callBoolean(host, "shouldRejectMachineAbuse", 1, MACHINE_WINDOW_HOURS);
+        assertFalse(reject, "1 小时窗口内同设备 1 个账号属正常,不应判机器行为");
+    }
+
+    // ==================== CF 值预估流(SC-X-22) ====================
+
+    @Test
+    @DisplayName("CF预估-1:打卡入口应返回预计获得 CF(非负)")
+    void expectedCf_checkin_nonNegative() {
+        Object host = contractHost();
+        int cf = callInt(host, "expectedCf", ACTIVITY_ID, "checkin");
+        assertTrue(cf >= 0, "打卡入口应返回『本操作预计 +N CF』预估(SC-X-22),cf=" + cf);
+    }
+
+    @Test
+    @DisplayName("CF预估-2:助力入口应返回预计获得 CF(非负)")
+    void expectedCf_boost_nonNegative() {
+        Object host = contractHost();
+        int cf = callInt(host, "expectedCf", ACTIVITY_ID, "boost");
+        assertTrue(cf >= 0, "助力入口应返回『本操作预计 +N CF』预估(SC-X-22),cf=" + cf);
+    }
+
+    @Test
+    @DisplayName("CF预估-3:未知动作类型不得为负(降级为 0)")
+    void expectedCf_unknownAction_notNegative() {
+        Object host = contractHost();
+        int cf = callInt(host, "expectedCf", ACTIVITY_ID, "unknown");
+        assertTrue(cf >= 0, "未知动作类型 CF 预估不得为负(SC-X-22 降级口径),cf=" + cf);
+    }
+
+    // ==================== 权限流(不适用) ====================
+
+    @Test
+    @DisplayName("权限流:营销打卡/助力无独立角色权限分支,权限流不适用")
+    void permissionFlow_notApplicable() {
+        // 说明性用例:SC-P-77 权限校验由活动报名与身份门禁承载(activity.enroll.join),
+        // 本能力聚焦进度累计/幂等/反刷量/CF 预估,无独立权限分支。不产生断言失败。
+        assertTrue(true, "权限流不适用:activity.checkin.boost 无独立角色权限分支。");
+    }
+
+    // ==================== 反射辅助(锚定宿主契约,避免编译期依赖不存在类) ====================
+
+    private Object contractHost() {
+        try {
+            Class<?> clazz = Class.forName(HOST_CLASS);
+            return clazz.getDeclaredConstructor().newInstance();
+        } catch (ClassNotFoundException e) {
+            fail("RED[activity.checkin.boost] 契约宿主 ActivityCheckinBoostService 未实现(实现未落地):"
+                    + e.getMessage());
+            throw new IllegalStateException("unreachable");
+        } catch (Exception e) {
+            fail("契约宿主 ActivityCheckinBoostService 实例化失败:" + e.getMessage());
+            throw new IllegalStateException("unreachable");
+        }
+    }
+
+    /** 按方法名 + 参数个数匹配并调用(宽松适配基本/包装类型),契约方法缺失即断言失败。 */
+    private Object call(Object host, String method, Object... args) {
+        for (Method m : host.getClass().getMethods()) {
+            if (m.getName().equals(method) && m.getParameterCount() == args.length) {
+                try {
+                    return m.invoke(host, args);
+                } catch (Exception e) {
+                    fail("契约方法 " + HOST_CLASS + "#" + method + " 调用失败:" + e.getMessage());
+                    throw new IllegalStateException("unreachable");
+                }
+            }
+        }
+        fail("RED[activity.checkin.boost] 契约方法 " + HOST_CLASS + "#" + method + " 未实现");
+        throw new IllegalStateException("unreachable");
+    }
+
+    private int callInt(Object host, String method, Object... args) {
+        Object r = call(host, method, args);
+        if (r instanceof Number) {
+            return ((Number) r).intValue();
+        }
+        fail("契约方法 " + method + " 应返回整数,实际 " + r);
+        throw new IllegalStateException("unreachable");
+    }
+
+    private boolean callBoolean(Object host, String method, Object... args) {
+        Object r = call(host, method, args);
+        if (r instanceof Boolean) {
+            return (Boolean) r;
+        }
+        fail("契约方法 " + method + " 应返回布尔,实际 " + r);
+        throw new IllegalStateException("unreachable");
+    }
+}

+ 381 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/AdminFamilyRelationManageContractTest.java

@@ -0,0 +1,381 @@
+package com.etotem.cfc.unit;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.io.File;
+import java.lang.annotation.Annotation;
+import java.lang.reflect.Method;
+import java.net.JarURLConnection;
+import java.net.URL;
+import java.util.ArrayList;
+import java.util.Enumeration;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+import java.util.jar.JarFile;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * 契约级单测(TDD-RED,S-cfc-308):能力键 {@code admin.familyRelation.manage}
+ * (平台运营·关系类型 CRUD 管理,单元 admin)。
+ *
+ * <p><b>需求溯源</b>:{@code tests/user-scenarios/应用场景总览.md} <b>SC-A-04 关系类型 CRUD</b>——
+ * 目标:管理家庭关系;流程:关系类型增删改查 → 生效;边界:被引用时删需确认;模块:{@code RelationshipTypes.vue}。</p>
+ *
+ * <p><b>用例绑定(TC 台账 → 资产回溯锚点)</b>:{@code tests/test-cases/admin.md}
+ * <ul>
+ *   <li><b>TC-A-10</b>(功能):新增/编辑/停用关系类型 → 操作成功;家长端关系选择器同步生效;</li>
+ *   <li><b>TC-A-10-E</b>(异常):新增重名拒绝;停用被引用类型提示先解绑;名称含注入 400/转义;</li>
+ *   <li><b>TC-A-10-P</b>(权限):非 admin 角色访问管理端接口统一 401/403,不泄露后台数据。</li>
+ * </ul></p>
+ *
+ * <p><b>设计溯源</b>:{@code docs/superpowers/api/API_REFERENCE.md}
+ * <ul>
+ *   <li>§4.2 / §4.20:家庭域 {@code /api/family/relationship/*}({@code RelationshipQualityController})
+ *       仅提供<b>只读评分查询</b>(scores/calculate/health-alerts/milestones/pairwise),无 CRUD 载体;</li>
+ *   <li>§4.60.18 契约缺口:SC-A-04 登记「无端点载体,需产品侧确认」——{@code relationship_types} 表已废弃 DROP,
+ *       关系由 {@code family_relationships}(generation 辈分模型 + {@code FamilyRelationshipService})承载;</li>
+ *   <li><b>本键 design 需求(契约目标)</b>:新增 admin/family-relation 端点
+ *       GET/POST/PUT/DELETE {@code /api/admin/family-relation/types}(关系类型增删改查 + 字典管理),
+ *       模块 {@code AdminFamilyRelationController}(待建)。</li>
+ * </ul></p>
+ *
+ * <p><b>实现现状(src/main 核实)</b>:{@code /api/admin/family-relation} 路径全库 0 引用,
+ * {@code AdminFamilyRelationController} 不存在,任何关系类型字典 CRUD 操作均未落地 → 本契约应全红。
+ * (若实测意外全绿,说明实现已存在,按编排侧流程转测试登记,不私改实现。)</p>
+ *
+ * <p><b>包路径不定约定</b>:O-2 方案 A 实现待定,<b>不得假定宿主包路径</b>。故本测试不硬编码
+ * {@code AdminFamilyRelationController} 的 FQCN,改为<b>类路径扫描</b> {@code com.etotem.cfc.controller}
+ * 下映射 {@code /api/admin/family-relation} 的控制器(含子包递归)——GREEN 实现放任意子包均可被探测。
+ * 若类路径扫描失败也会显式红(扫描器自检用例),避免「扫描器坏 → 永久红/假绿」。</p>
+ *
+ * <p><b>动词约定</b>:项目接口统一 {@code @PostMapping},而本键 design 明确要求 GET/POST/PUT/DELETE 动词端点。
+ * 测试按<b>语义操作</b>(列表/新增/编辑/停用)探测,不强制 HTTP 动词——GREEN 无论按 REST 动词还是
+ * POST 子路径({@code /types/list} 等)落地均可转绿;设计动词要求记录于下方。</p>
+ *
+ * <p><b>契约方法签名(实现方据此落地,GREEN 后本测试自动转绿)</b></p>
+ * <ul>
+ *   <li>控制器类级映射 {@code /api/admin/family-relation}(包路径任意,扫描发现)</li>
+ *   <li>列表:{@code GET|POST <prefix>/types} 或 {@code /types/list} —— 关系类型字典列表(TC-A-10 查询)</li>
+ *   <li>新增:{@code POST <prefix>/types} 或 {@code /types/save} —— 新增(重名校验,TC-A-10-E)</li>
+ *   <li>编辑:{@code PUT|POST <prefix>/types} 或 {@code /types/update} —— 编辑(TC-A-10)</li>
+ *   <li>停用/删除:{@code DELETE|POST <prefix>/types} 或 {@code /types/disable|delete} —— 停用;
+ *       被 {@code family_relationships} 引用时删需确认/提示先解绑(SC-A-04 边界 + TC-A-10-E)</li>
+ * </ul>
+ *
+ * <p><b>测试风格</b>:与同批 RED 契约测试一致——纯反射 + 类路径扫描,无 Spring 上下文 / 无 DB / 无外部服务;
+ * 宿主缺失即全部用例红(RED),断言原文清晰可贴;GREEN 实现宿主后自动转绿。行为级细节(重名拒绝、
+ * 被引用确认、注入防护)由 GREEN 阶段行为级测试补充验证,本类负责「载体 + 操作是否存在」的契约锚定。</p>
+ */
+class AdminFamilyRelationManageContractTest {
+
+    /** 契约端点前缀(design 明确):关系类型字典管理 */ 
+    private static final String API_PREFIX = "/api/admin/family-relation";
+
+    /** 类型字典资源段(GET/POST/PUT/DELETE /api/admin/family-relation/types) */
+    private static final String TYPES = "types";
+
+    /** 类路径扫描根(项目控制器统一目录,含子包) */
+    private static final String CONTROLLER_BASE_PKG = "com.etotem.cfc.controller";
+
+    /** 扫描自检锚点:既有的只读评分控制器(证明扫描器有效,非扫描故障导致红) */
+    private static final String SANITY_EXISTING =
+            "com.etotem.cfc.controller.family.RelationshipQualityController";
+
+    // ==================== 正常流:/api/admin/family-relation 管理控制器载体 ====================
+
+    @Test
+    @DisplayName("正常流-1:/api/admin/family-relation 管理控制器应存在(包路径不定,类路径扫描发现)")
+    void normalFlow_controllerCarrierExists() {
+        // 扫描器自检:既能发现既有控制器,又未命中 /api/admin/family-relation
+        assertTrue(scanControllerClasses().contains(SANITY_EXISTING),
+                "RED[admin.familyRelation.manage] 类路径扫描未发现既有控制器 " + SANITY_EXISTING
+                        + ":扫描器故障会导致后续探测失真(本应为 GREEN 自检锚点)。");
+        assertFalse(discoverAdminFamilyRelationControllers().isEmpty(),
+                "RED[admin.familyRelation.manage] 未发现映射 " + API_PREFIX + " 的管理控制器"
+                        + "(AdminFamilyRelationController 待建,包路径不定 → 类路径扫描):"
+                        + "契约要求 GET/POST/PUT/DELETE " + API_PREFIX + "/types 承载关系类型字典"
+                        + "增删改查 + 字典管理(SC-A-04 + TC-A-10)。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("正常流-2:应提供关系类型列表/查询接口(types · 字典列表,TC-A-10 查询)")
+    void normalFlow_typesListOperation() {
+        assertTrue(servesTypeOperation(TypeOp.LIST),
+                "RED[admin.familyRelation.manage] 控制器缺少关系类型列表/查询操作"
+                        + "(GET|POST " + API_PREFIX + "/types 或 /types/list):"
+                        + "TC-A-10 关系类型管理页需展示字典列表。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("正常流-3:应提供关系类型新增接口(types · 新增,TC-A-10)")
+    void normalFlow_typesCreateOperation() {
+        assertTrue(servesTypeOperation(TypeOp.CREATE),
+                "RED[admin.familyRelation.manage] 控制器缺少关系类型新增操作"
+                        + "(POST " + API_PREFIX + "/types 或 /types/save):"
+                        + "TC-A-10「新增关系类型 → 操作成功、家长端关系选择器同步生效」。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("正常流-4:应提供关系类型编辑接口(types · 编辑,TC-A-10)")
+    void normalFlow_typesUpdateOperation() {
+        assertTrue(servesTypeOperation(TypeOp.UPDATE),
+                "RED[admin.familyRelation.manage] 控制器缺少关系类型编辑操作"
+                        + "(PUT|POST " + API_PREFIX + "/types 或 /types/update):"
+                        + "TC-A-10「编辑关系类型 → 操作成功、家长端关系选择器同步生效」。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("正常流-5:应提供关系类型停用/删除接口(types · 停用,TC-A-10 + SC-A-04 删)")
+    void normalFlow_typesDisableOperation() {
+        assertTrue(servesTypeOperation(TypeOp.DISABLE),
+                "RED[admin.familyRelation.manage] 控制器缺少关系类型停用/删除操作"
+                        + "(DELETE|POST " + API_PREFIX + "/types 或 /types/disable|delete):"
+                        + "TC-A-10「停用关系类型」+ SC-A-04「关系类型增删改查 → 生效」。实现未落地。");
+    }
+
+    // ==================== 边界流:TC-A-10-E(异常) ====================
+
+    @Test
+    @DisplayName("边界流-1:新增重名关系类型应被拒绝(TC-A-10-E · 名称唯一性契约)")
+    void boundary_duplicateNameRejected() {
+        // 契约:关系类型字典名称唯一,「新增重名类型 → 拒绝」(TC-A-10-E 步骤1 预期)。
+        // 载体(types Create 操作)未落地 → 该行为必然缺位,契约红;
+        // GREEN 转绿条件 = Create 操作存在(名称唯一校验为 GREEN 阶段行为实现点)。
+        assertTrue(servesTypeOperation(TypeOp.CREATE),
+                "RED[admin.familyRelation.manage] 新增接口未落地,'新增重名关系类型应拒绝'行为缺位"
+                        + "(TC-A-10-E:重名拒绝;GREEN 阶段 Create 操作须承载名称唯一校验)。");
+    }
+
+    @Test
+    @DisplayName("边界流-2:停用被引用关系类型需确认/提示先解绑(TC-A-10-E + SC-A-04 边界)")
+    void boundary_referencedTypeDisableNeedsConfirm() {
+        // 契约:关系类型被 family_relationships 引用时,停用/删除需确认或提示先解绑
+        // (SC-A-04 边界「被引用时删需确认」;TC-A-10-E 步骤2「停用被引用类型提示先解绑」)。
+        // 载体(types Disable 操作)未落地 → 该守卫行为必然缺位,契约红;
+        // GREEN 转绿条件 = Disable 操作存在(引用检查为 GREEN 阶段行为实现点)。
+        assertTrue(servesTypeOperation(TypeOp.DISABLE),
+                "RED[admin.familyRelation.manage] 停用/删除接口未落地,'被引用类型停用需先解绑/确认'"
+                        + "守卫行为缺位(SC-A-04 边界 + TC-A-10-E 步骤2;"
+                        + "GREEN 阶段 Disable 操作须做 family_relationships 引用检查)。");
+    }
+
+    // ==================== 权限流:TC-A-10-P(管理端 401/403 门禁) ====================
+
+    @Test
+    @DisplayName("权限流:接口应挂 /api/admin 前缀(JWT 拦截 + 管理员角色门禁,非 admin 统一 401/403)")
+    void permissionFlow_adminApiPrefixGate() {
+        // TC-A-10-P:非 admin 角色访问管理端接口统一 401/403,不泄露后台数据。
+        // 机理由 JwtInterceptor 拦截 /api/admin/** + 控制器内 role=admin 校验承载;
+        // 宿主未落地 → 门禁随之缺位,契约红。
+        List<Class<?>> ctls = discoverAdminFamilyRelationControllers();
+        assertFalse(ctls.isEmpty(),
+                "RED[admin.familyRelation.manage] " + API_PREFIX + " 管理控制器未实现:"
+                        + "TC-A-10-P 要求非 admin 访问管理端接口统一 401/403,"
+                        + "JwtInterceptor 拦截 /api/admin/** + role=admin 门禁随之缺位。");
+        for (Class<?> c : ctls) {
+            boolean underAdmin = false;
+            for (String p : mappingValues(c.getAnnotations())) {
+                if (p.startsWith("/api/admin")) {
+                    underAdmin = true;
+                    break;
+                }
+            }
+            assertTrue(underAdmin,
+                    "RED[admin.familyRelation.manage] 控制器 " + c.getName()
+                            + " 类级映射应挂 /api/admin 前缀(JWT 拦截 + 管理员角色门禁,TC-A-10-P)。");
+        }
+    }
+
+    // ==================== 反射辅助(类路径扫描 + 端点语义探测,不假定包路径) ====================
+
+    private enum TypeOp { LIST, CREATE, UPDATE, DISABLE }
+
+    /** 新增语义关键字 */
+    private static final String[] CREATE_KW = {"save", "add", "create", "insert"};
+    /** 编辑语义关键字 */
+    private static final String[] UPDATE_KW = {"update", "edit", "modify", "rename"};
+    /** 停用/删除语义关键字(SC-A-04 删 + TC-A-10 停用) */
+    private static final String[] DISABLE_KW = {"disable", "delete", "remove", "offline", "deactivate"};
+    /** 列表/查询语义关键字 */
+    private static final String[] LIST_KW = {"list", "query", "page", "select", "find", "all"};
+
+    /** 扫描 com.etotem.cfc.controller(含子包递归),筛出类级映射 /api/admin/family-relation 的控制器。 */
+    private List<Class<?>> discoverAdminFamilyRelationControllers() {
+        List<Class<?>> found = new ArrayList<Class<?>>();
+        for (String fqcn : scanControllerClasses()) {
+            Class<?> c = loadClass(fqcn);
+            if (c == null) {
+                continue;
+            }
+            for (String p : mappingValues(c.getAnnotations())) {
+                if (p.equals(API_PREFIX) || p.startsWith(API_PREFIX + "/")) {
+                    found.add(c);
+                    break;
+                }
+            }
+        }
+        return found;
+    }
+
+    /** 控制器包递归扫描(file: 目录递归 + jar: 直接子类,ClassLoader 资源形态) */
+    private List<String> scanControllerClasses() {
+        List<String> names = new ArrayList<String>();
+        collectPackage(CONTROLLER_BASE_PKG, names);
+        Set<String> unique = new HashSet<String>(names);
+        return new ArrayList<String>(unique);
+    }
+
+    private void collectPackage(String pkg, List<String> out) {
+        try {
+            String path = pkg.replace('.', '/');
+            ClassLoader cl = Thread.currentThread().getContextClassLoader();
+            Enumeration<URL> resources = cl.getResources(path);
+            while (resources.hasMoreElements()) {
+                URL url = resources.nextElement();
+                String protocol = url.getProtocol();
+                if ("file".equals(protocol)) {
+                    File dir = new File(url.toURI());
+                    File[] files = dir.listFiles();
+                    if (files == null) {
+                        continue;
+                    }
+                    for (File f : files) {
+                        if (f.isDirectory()) {
+                            collectPackage(pkg + "." + f.getName(), out);
+                        } else if (f.isFile() && f.getName().endsWith(".class")
+                                && !f.getName().contains("$")) {
+                            out.add(pkg + "." + f.getName().substring(0, f.getName().length() - 6));
+                        }
+                    }
+                } else if ("jar".equals(protocol)) {
+                    // 应用类在 target/classes(file:)下,jar 分支仅兜底取当前包直接子类
+                    JarURLConnection conn = (JarURLConnection) url.openConnection();
+                    try (JarFile jar = conn.getJarFile()) {
+                        String prefix = path + "/";
+                        Enumeration<java.util.jar.JarEntry> entries = jar.entries();
+                        while (entries.hasMoreElements()) {
+                            java.util.jar.JarEntry e = entries.nextElement();
+                            String n = e.getName();
+                            if (n.startsWith(prefix) && n.endsWith(".class")
+                                    && !n.substring(prefix.length()).contains("$")
+                                    && n.indexOf('/', prefix.length()) < 0) {
+                                out.add(n.substring(0, n.length() - 6).replace('/', '.'));
+                            }
+                        }
+                    }
+                }
+            }
+        } catch (Exception ignored) {
+            // 包扫描失败 → 按缺失处理(外层断言会红,扫描器自检用例可定位)
+        }
+    }
+
+    /** 该方法是否为关系类型(types)管理端点:类级或方法级映射含 types 段。 */
+    private boolean targetsTypes(Class<?> ctrl, Method m) {
+        if (mappingValues(m.getAnnotations()).isEmpty()) {
+            return false; // 无映射注解的方法不是端点
+        }
+        for (String p : mappingValues(ctrl.getAnnotations())) {
+            if (p.contains(TYPES)) {
+                return true;
+            }
+        }
+        for (String p : mappingValues(m.getAnnotations())) {
+            if (p.contains(TYPES)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /** 关系类型操作语义分类:类型管理端点 → LIST/CREATE/UPDATE/DISABLE;非类型端点 → null。 */
+    private TypeOp classifyTypeOp(Class<?> ctrl, Method m) {
+        if (!targetsTypes(ctrl, m)) {
+            return null;
+        }
+        StringBuilder sb = new StringBuilder(m.getName());
+        sb.append(' ');
+        for (Annotation a : m.getAnnotations()) {
+            sb.append(a.annotationType().getSimpleName()).append(' ');
+        }
+        for (String p : mappingValues(m.getAnnotations())) {
+            sb.append(p).append(' ');
+        }
+        for (String p : mappingValues(ctrl.getAnnotations())) {
+            sb.append(p).append(' ');
+        }
+        String sig = sb.toString().toLowerCase();
+
+        if (containsAny(sig, CREATE_KW)) {
+            return TypeOp.CREATE;
+        }
+        if (containsAny(sig, UPDATE_KW)) {
+            return TypeOp.UPDATE;
+        }
+        if (containsAny(sig, DISABLE_KW)) {
+            return TypeOp.DISABLE;
+        }
+        if (containsAny(sig, LIST_KW) || sig.trim().startsWith("get")) {
+            return TypeOp.LIST;
+        }
+        return null;
+    }
+
+    /** 已发现的控制器中是否存在某类关系类型操作。 */
+    private boolean servesTypeOperation(TypeOp op) {
+        for (Class<?> c : discoverAdminFamilyRelationControllers()) {
+            for (Method m : c.getDeclaredMethods()) {
+                if (classifyTypeOp(c, m) == op) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+
+    private boolean containsAny(String s, String[] keywords) {
+        for (String kw : keywords) {
+            if (s.contains(kw)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private Class<?> loadClass(String name) {
+        try {
+            return Class.forName(name, false, Thread.currentThread().getContextClassLoader());
+        } catch (ClassNotFoundException e) {
+            return null;
+        }
+    }
+
+    /** 读取 Spring 映射注解(@RequestMapping/@GetMapping/@PostMapping/@PutMapping/@DeleteMapping)的 value() 路径集合。 */
+    private List<String> mappingValues(Annotation[] annotations) {
+        List<String> paths = new ArrayList<String>();
+        for (Annotation a : annotations) {
+            String tn = a.annotationType().getName();
+            if (tn.equals("org.springframework.web.bind.annotation.RequestMapping")
+                    || tn.equals("org.springframework.web.bind.annotation.PostMapping")
+                    || tn.equals("org.springframework.web.bind.annotation.GetMapping")
+                    || tn.equals("org.springframework.web.bind.annotation.PutMapping")
+                    || tn.equals("org.springframework.web.bind.annotation.DeleteMapping")) {
+                try {
+                    Object v = a.annotationType().getMethod("value").invoke(a);
+                    if (v instanceof String[]) {
+                        for (String s : (String[]) v) {
+                            paths.add(s);
+                        }
+                    }
+                } catch (Exception ignored) {
+                    // 非路径型映射注解,忽略
+                }
+            }
+        }
+        return paths;
+    }
+}

+ 286 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/AuthSessionMutexContractTest.java

@@ -0,0 +1,286 @@
+package com.etotem.cfc.unit;
+
+import com.etotem.cfc.dto.LoginResultDTO;
+import com.etotem.cfc.service.UserService;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.io.InputStream;
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.nio.charset.StandardCharsets;
+import java.util.Scanner;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assertions.fail;
+
+/**
+ * 契约级单测:多端登录/会话互斥(能力键 {@code auth.session.mutex},S-cfc-301,TDD-RED 阶段)。
+ *
+ * <p><b>契约锚点(溯源)</b></p>
+ * <ul>
+ *   <li>需求:{@code tests/user-scenarios/应用场景总览.md} SC-P-85(多端登录/会话互斥——
+ *       <b>主流程:新设备登录 → 旧设备踢下线/二次验证;边界:异常设备风控;退出清 token</b>);
+ *       {@code tests/user-scenarios/02-parent.md} SC-P-85、用例 TC-P-85。</li>
+ *   <li>设计:{@code docs/superpowers/api/API_REFERENCE.md} §4.1(/api/auth 登录/token 生命周期)、
+ *       §4.63.9(SC-P-85 登录族 + SSO 票据)与契约缺口 <b>G-5</b>(无单端互斥/旧会话踢出,
+ *       JWT 无状态)。</li>
+ * </ul>
+ *
+ * <p><b>实现现状(origin/cfclub @ d6dac931a 实测)</b>:src/main 无任何会话互斥载体 ——
+ * 无 {@code UserSessionService} 服务类、无 {@code user_session} 表(schema.sql 全库检索 0 命中)、
+ * {@code LoginResultDTO} 无 {@code sessionId}/{@code secondVerifyRequired} 字段、登录族服务方法
+ * ({@code UserService.wechatLogin/phoneLogin/silentLogin/ssoLogin/switchRoleForLogin})
+ * 未注入任何会话登记能力;退出为前端清 JWT(无服务端 logout,{@code SecurityConfig} STATELESS)。
+ * 会话互斥能力整体未落地(对应设计缺口 G-5)。</p>
+ *
+ * <p><b>契约方法签名(实现方按此落地,GREEN 指引)</b></p>
+ * <ul>
+ *   <li>{@code com.etotem.cfc.service.UserSessionService}:
+ *       {@code String login(Long userId, String deviceId)} —— 新设备登录登记会话,返回 sessionId;
+ *       {@code void kick(Long userId, String excludedSessionId)} —— 老设备会话踢下线(互斥);
+ *       {@code void invalidate(Long userId, String sessionId)} —— 退出清 token(服务端失效);
+ *       {@code boolean isKnownDevice(Long userId, String deviceId)} / {@code RiskResult riskCheck(...)}
+ *       —— 异常设备风控判定。</li>
+ *   <li>{@code LoginResultDTO} 增补:{@code sessionId}(会话定位凭证)、
+ *       {@code secondVerifyRequired}(新设备触发二次验证标记)。</li>
+ *   <li>{@code schema.sql} 增补 {@code user_session} 建表({@code session_id}/{@code user_id}/
+ *       {@code device_id}/{@code status}(active/kicked)/{@code risk_flag})。</li>
+ * </ul>
+ *
+ * <p><b>测试范围</b>:纯契约级单测,反射锚定缺失实现 + schema.sql 静态读取
+ * (参考 TeamProfitHookContractTest / ChildAuthLoginContractTest 风格),
+ * 无 Spring / 无 DB / 无外部服务。</p>
+ *
+ * <p><b>RED 预期</b>:会话互斥载体整体缺失,下述正常流/边界流/异常流断言应失败(红);
+ * 权限流为说明性用例(绿)。若实现已意外落地导致全绿,按编排约定交登记,不私改实现。</p>
+ */
+class AuthSessionMutexContractTest {
+
+    private static final String USER_SESSION_SERVICE = "com.etotem.cfc.service.UserSessionService";
+
+    // ====================================================================
+    // 正常流(主流程):新设备登录 → 旧设备踢下线
+    // ====================================================================
+
+    @Test
+    @DisplayName("正常流-1:UserSessionService 会话互斥服务类应存在")
+    void userSessionService_classExists() {
+        assertTrue(loadClass(USER_SESSION_SERVICE) != null,
+                "[auth.session.mutex/SC-P-85] UserSessionService 类不存在:契约要求服务端会话登记/互斥裁决核心"
+                        + "(新设备登录登记会话 → 旧设备踢下线,SC-P-85 主流程)。当前 src/main 无任何会话互斥"
+                        + "载体(设计缺口 G-5:JWT 无状态、无单端互斥)。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("正常流-2:UserSessionService 应提供 login(登记新会话)与 kick/invalidate(旧会话踢下线)入口")
+    void userSessionService_hasLoginAndKickMethods() {
+        Class<?> clazz = loadClass(USER_SESSION_SERVICE);
+        if (clazz == null) {
+            fail("[auth.session.mutex/SC-P-85] UserSessionService 类不存在,无法验证 login/kick 入口"
+                    + "(新设备登录 → 旧设备踢下线,SC-P-85 主流程)。实现未落地。");
+        }
+        boolean hasLogin = hasMethodNamed(clazz, "login");
+        boolean hasKick = hasMethodNamed(clazz, "kick")
+                || hasMethodNamed(clazz, "invalidate")
+                || hasMethodNamed(clazz, "logout");
+        assertTrue(hasLogin,
+                "[auth.session.mutex/SC-P-85] UserSessionService 应提供 login(...) 在每次登录时登记新会话"
+                        + "(新设备登录触发,SC-P-85 主流程)。实现未落地。");
+        assertTrue(hasKick,
+                "[auth.session.mutex/SC-P-85] UserSessionService 应提供 kick/invalidate/logout(...) 使旧设备会话"
+                        + "踢下线(同账号仅保留新会话,SC-P-85 主流程)。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("正常流-3:登录族服务方法应注入 UserSessionService 钩子(登录即登记会话,建立单端互斥)")
+    void userService_loginFlow_injectsUserSessionService() {
+        boolean injected = hasFieldOfType(UserService.class, USER_SESSION_SERVICE);
+        assertTrue(injected,
+                "[auth.session.mutex/SC-P-85] UserService 登录族方法(wechatLogin/phoneLogin/silentLogin/"
+                        + "ssoLogin/switchRoleForLogin)应注入 UserSessionService 钩子:每次登录登记新会话并使旧会话"
+                        + "失效(新设备登录 → 旧设备踢下线,SC-P-85 主流程;当前登录只签发 JWT,无会话维度)。"
+                        + "实现未落地。");
+    }
+
+    // ====================================================================
+    // 边界流:二次验证 / 退出清 token(旧设备踢下线结果需可观测、可失效)
+    // ====================================================================
+
+    @Test
+    @DisplayName("边界流-1:LoginResultDTO 应携带 sessionId 与 secondVerifyRequired(二次验证标记)")
+    void loginResultDto_carriesSessionContext() {
+        assertTrue(hasField(LoginResultDTO.class, "sessionId"),
+                "[auth.session.mutex/SC-P-85] LoginResultDTO 应携带 sessionId:登录返回的会话定位凭证,"
+                        + "供前端 logout/被踢下线时定位会话(SC-P-85 主流程+退出清 token)。"
+                        + "当前 LoginResultDTO 无任何会话字段。实现未落地。");
+        assertTrue(hasField(LoginResultDTO.class, "secondVerifyRequired"),
+                "[auth.session.mutex/SC-P-85] LoginResultDTO 应携带 secondVerifyRequired:新设备登录时服务端"
+                        + "可裁决「踢下线」或「二次验证」两种互斥策略(SC-P-85 主流程)。当前缺失。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("边界流-2:schema.sql 应有 user_session 会话登记表(承载旧设备踢下线结果)")
+    void schemaSql_hasUserSessionTable() {
+        assertTrue(readSchemaSql().contains("user_session"),
+                "[auth.session.mutex/SC-P-85] schema.sql 应含 user_session 建表:服务端会话登记载体,"
+                        + "记录每次登录的会话/设备,旧设备踢下线结果(status)可被判定与清理(SC-P-85 主流程+"
+                        + "退出清 token)。当前 schema.sql 无该表(仅 users.session_key、butler_sessions 等非认证"
+                        + "会话表)。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("边界流-3:user_session 表应含 session_id/user_id/device_id/status 列(会话唯一标识与互斥状态)")
+    void userSessionTable_hasSessionColumns() {
+        String block = userSessionTableBlock();
+        assertTrue(block.contains("session_id"),
+                "[auth.session.mutex/SC-P-85] user_session 应含 session_id 列(会话唯一标识,踢除/退出的定位键)。"
+                        + "实现未落地。");
+        assertTrue(block.contains("user_id"),
+                "[auth.session.mutex/SC-P-85] user_session 应含 user_id 列(会话归属账号,互斥的粒度基准)。"
+                        + "实现未落地。");
+        assertTrue(block.contains("device_id"),
+                "[auth.session.mutex/SC-P-85] user_session 应含 device_id 列(设备维度,区分新旧设备登录)。"
+                        + "实现未落地。");
+        assertTrue(block.contains("status"),
+                "[auth.session.mutex/SC-P-85] user_session 应含 status 列(active/kicked 等会话状态,"
+                        + "承载「旧设备踢下线」结果判定)。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("边界流-4:退出清 token 应服务端失效会话(UserSessionService 提供 logout/invalidate 能力)")
+    void userSessionService_hasLogoutInvalidateCapability() {
+        Class<?> clazz = loadClass(USER_SESSION_SERVICE);
+        boolean hasLogout = false;
+        if (clazz != null) {
+            for (Method m : clazz.getDeclaredMethods()) {
+                String n = m.getName().toLowerCase();
+                if (n.contains("logout") || n.contains("invalidate") || n.contains("revoke")) {
+                    hasLogout = true;
+                    break;
+                }
+            }
+        }
+        assertTrue(clazz != null && hasLogout,
+                "[auth.session.mutex/SC-P-85] 退出清 token:UserSessionService 应提供 logout/invalidate/revoke"
+                        + "方法使服务端会话失效(SC-P-85 边界:退出清 token;当前退出为前端清 JWT,"
+                        + "SecurityConfig.logout().disable(),无服务端会话可清。设计缺口 G-5)。实现未落地。");
+    }
+
+    // ====================================================================
+    // 异常/风险流:异常设备风控
+    // ====================================================================
+
+    @Test
+    @DisplayName("异常流-1:UserSessionService 应提供异常设备风控判定能力")
+    void userSessionService_hasRiskControlJudgment() {
+        Class<?> clazz = loadClass(USER_SESSION_SERVICE);
+        boolean hasRisk = false;
+        if (clazz != null) {
+            for (Method m : clazz.getDeclaredMethods()) {
+                String n = m.getName().toLowerCase();
+                if (n.contains("risk") || n.contains("abnormal") || n.contains("known")) {
+                    hasRisk = true;
+                    break;
+                }
+            }
+        }
+        assertTrue(clazz != null && hasRisk,
+                "[auth.session.mutex/SC-P-85] UserSessionService 应提供异常设备风控判定方法 "
+                        + "(如 isKnownDevice/riskCheck:陌生/高风险设备登录 → 二次验证或拦截,SC-P-85 异常/边界)。"
+                        + "当前服务类不存在。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("异常流-2:user_session 表应有风险标记列(risk_flag,异常设备风控结果落库)")
+    void userSessionTable_hasRiskControlColumn() {
+        String block = userSessionTableBlock();
+        assertTrue(block.contains("risk_flag") || block.contains("risk"),
+                "[auth.session.mutex/SC-P-85] user_session 应含 risk_flag(或等价风险标记)列:异常设备风控结论"
+                        + "落库,供二次验证/拦截策略判定(SC-P-85 异常/边界:异常设备风控)。实现未落地。");
+    }
+
+    // ====================================================================
+    // 权限流(适用性说明)
+    // ====================================================================
+
+    @Test
+    @DisplayName("权限流:会话互斥为登录链路预检 + 会话生命周期管理,无独立业务权限维度")
+    void permissionFlow_sessionMutexIsAuthLifecycle() {
+        // 说明性用例:登录会话登记/踢下线发生在登录准入与登出生命周期(匿名可触达 → 登录后自管理),
+        // 无独立于认证本身的业务权限维度(与 TeamProfitHookContractTest.permissionFlow_notApplicable 同风格)。
+        assertTrue(true, "权限流说明:auth.session.mutex 属认证生命周期能力,权限随 JWT 认证本身,无独立权限断言。");
+    }
+
+    // ====================================================================
+    // 反射 / 静态资源辅助
+    // ====================================================================
+
+    private Class<?> loadClass(String name) {
+        try {
+            return Class.forName(name, false, Thread.currentThread().getContextClassLoader());
+        } catch (ClassNotFoundException e) {
+            return null;
+        }
+    }
+
+    private boolean hasMethodNamed(Class<?> clazz, String name) {
+        for (Method m : clazz.getDeclaredMethods()) {
+            if (m.getName().equals(name)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private boolean hasField(Class<?> clazz, String name) {
+        for (Field f : clazz.getDeclaredFields()) {
+            if (f.getName().equals(name)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private boolean hasFieldOfType(Class<?> clazz, String fieldTypeFqcn) {
+        for (Field f : clazz.getDeclaredFields()) {
+            if (fieldTypeFqcn.equals(f.getType().getName())) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /** 截取 schema.sql 中 user_session 建表块(起始于其前最近的 CREATE TABLE,止于首个 ");")。 */
+    private String userSessionTableBlock() {
+        String schema = readSchemaSql();
+        int idx = schema.indexOf("user_session");
+        if (idx < 0) {
+            return "";
+        }
+        int start = schema.lastIndexOf("CREATE TABLE", idx);
+        if (start < 0) {
+            return "";
+        }
+        int end = schema.indexOf(");", idx);
+        if (end < 0) {
+            return "";
+        }
+        return schema.substring(start, end + 2);
+    }
+
+    private String readSchemaSql() {
+        try (InputStream is = getClass().getClassLoader().getResourceAsStream("schema.sql")) {
+            if (is == null) {
+                return "";
+            }
+            try (Scanner scanner = new Scanner(is, StandardCharsets.UTF_8.name())) {
+                scanner.useDelimiter("\\A");
+                return scanner.hasNext() ? scanner.next() : "";
+            }
+        } catch (Exception e) {
+            return "";
+        }
+    }
+}

+ 400 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/DataExportGdprContractTest.java

@@ -0,0 +1,400 @@
+package com.etotem.cfc.unit;
+
+import com.etotem.cfc.entity.FamilyMember;
+import com.etotem.cfc.entity.User;
+import com.etotem.cfc.mapper.DanAssessmentResultMapper;
+import com.etotem.cfc.mapper.FamilyMemberMapper;
+import com.etotem.cfc.mapper.HealthReportMapper;
+import com.etotem.cfc.mapper.TaskMapper;
+import com.etotem.cfc.mapper.UserMapper;
+import com.etotem.cfc.service.AccountCleanupService;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.MockitoAnnotations;
+
+import java.io.InputStream;
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.nio.charset.StandardCharsets;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import java.util.Scanner;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assertions.fail;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.when;
+
+/**
+ * 契约级单测:个人/家庭数据导出(GDPR)(能力键 {@code data.export.gdpr},SC-P-72,TDD-RED 阶段)。
+ *
+ * <p><b>契约溯源</b></p>
+ * <ul>
+ *   <li>需求:{@code tests/user-scenarios/应用场景总览.md} SC-P-72「个人/家庭数据导出(GDPR)」(业务域 J:账号与数据主权)——
+ *       <b>流程:申请导出 → 生成加密包 → 下载</b>;<b>边界:敏感字段脱敏;频次限制;越权导出被拒</b>;
+ *       模块:数据导出(GDPR)。用例台账 GAP-028(TC-P-72 正常流 / TC-P-72-E 异常流 / TC-P-72-P 权限流,
+ *       见 {@code docs/tdd/test/scenario-gap-backlog.csv});sc-key-map 台账登记 SC-P-72 → {@code data.export.gdpr}(RED/未跑通)。</li>
+ *   <li>设计:{@code docs/superpowers/api/API_REFERENCE.md} §4.61.5——数据主权(GDPR)能力<b>无独立端点</b>,
+ *       需复用 {@code /api/user}、{@code /api/family/member/list} 汇集导出;
+ *       「仅导出登录用户本人;无 memberId 入参 → 无『家长代导出孩子』(G-05)」;
+ *       {@code docs/superpowers/specs/2026-11-07-child-zone-contract.md} §5 G-05:
+ *       {@code exportUserData(userId)} 不接受 memberId,无家长代导出指定成员。</li>
+ * </ul>
+ *
+ * <p><b>宿主契约(本 RED 测试定稿,GREEN 实现方按此落地)</b>:{@code com.etotem.cfc.service.DataExportService}
+ * ——「数据导出(GDPR)」模块服务(申请→加密包→下载 流程宿主)。origin/cfclub @ d6dac931a 实测 <b>不存在</b>
+ * (实现未落地),测试以反射结构契约探测缺失,失败断言原文红色清晰可贴。</p>
+ *
+ * <p><b>建议契约方法签名(实现方可按仓库惯例微调命名)</b></p>
+ * <ul>
+ *   <li>{@code applyExport(Long userId, Long scopeMemberId)}——申请导出入口:频次窗口校验(如 24h)+ 归属校验
+ *       (越权拒)后创建导出工单(pending);</li>
+ *   <li>{@code buildExportPackage(...)}(或 generatePackage)——汇集数据(复用 user / family-member 数据)+
+ *       敏感字段脱敏(复用 {@code DataMaskUtil})+ 加密 → 生成加密包;</li>
+ *   <li>{@code downloadPackage(...)}——下载入口:本人/家庭归属校验 → 返回加密包(含密钥交接);</li>
+ *   <li>配套实体/表:{@code DataExportTask}({@code data_export_task})承载 status / packagePath / packageKey /
+ *       expiresAt 等工单状态字段。</li>
+ * </ul>
+ *
+ * <p><b>测试范围</b>:纯 JUnit + Mockito + 反射(无 Spring / 无 DB / 无外部服务,同批
+ * {@code TeamProfitHookContractTest} / {@code TeacherExportContractTest} 风格);
+ * 行为断言锚定现有数据导出载体 {@code AccountCleanupService.exportUserData}(设计指定复用的 /api/user 载体)。</p>
+ *
+ * <p><b>RED 预期</b>:宿主 {@code DataExportService} 未实现(反射结构用例全红);且现有载体
+ * {@code AccountCleanupService.exportUserData} 明文导出家庭成员 phone、无 memberId 范围入参(行为/签名用例红),
+ * GREEN 阶段按上述契约落地后转绿。</p>
+ */
+class DataExportGdprContractTest {
+
+    /** 宿主服务类(SC-P-72 数据导出(GDPR) 模块,设计锚点;当前实现未落地)。 */
+    private static final String HOST_CLASS = "com.etotem.cfc.service.DataExportService";
+
+    /** 配套导出工单实体(申请→加密包→下载 状态载体)。 */
+    private static final String TASK_ENTITY = "com.etotem.cfc.entity.DataExportTask";
+
+    /** 配套导出工单表(schema.sql 建表快照)。 */
+    private static final String TASK_TABLE = "data_export_task";
+
+    /** 现有数据导出载体(设计指定复用 /api/user,UserController POST /api/user/data-export → exportUserData)。 */
+    private static final String EXPORT_CARRIER = "com.etotem.cfc.service.AccountCleanupService";
+
+    private static final Long PARENT_USER_ID = 1001L;
+    private static final Long FAMILY_ID = 5001L;
+    private static final Long CHILD_MEMBER_ID = 2001L;
+    private static final String RAW_PHONE = "13800138000";
+
+    @Mock
+    private UserMapper userMapper;
+
+    @Mock
+    private FamilyMemberMapper familyMemberMapper;
+
+    @Mock
+    private DanAssessmentResultMapper danAssessmentResultMapper;
+
+    @Mock
+    private HealthReportMapper healthReportMapper;
+
+    @Mock
+    private TaskMapper taskMapper;
+
+    @InjectMocks
+    private AccountCleanupService service;
+
+    @BeforeEach
+    void setUp() {
+        MockitoAnnotations.openMocks(this);
+    }
+
+    // ==================== 正常流(TC-P-72):申请导出 → 加密包 → 下载 ====================
+
+    @Test
+    @DisplayName("正常流-1:DataExportService 数据导出(GDPR) 服务类应存在(宿主锚点)")
+    void dataExportService_classExists() {
+        assertNotNull(loadClass(HOST_CLASS),
+                "[data.export.gdpr] DataExportService 类不存在:SC-P-72 个人/家庭数据导出(GDPR)"
+                        + "要求「申请导出 → 生成加密包 → 下载」流程宿主(模块:数据导出(GDPR),复用 /api/user、"
+                        + "/api/family/member/list 汇集导出)。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("正常流-2:DataExportService 应提供 applyExport 申请导出入口")
+    void dataExportService_hasApplyExportEntry() {
+        Method apply = findMethodContains(hostClass(), "apply");
+        assertNotNull(apply,
+                "[data.export.gdpr] DataExportService 应提供 applyExport(...) 申请导出入口"
+                        + "(申请 → 生成加密包 → 下载 三阶段之首,SC-P-72 正常流)。实现未落地:宿主类不存在。");
+    }
+
+    @Test
+    @DisplayName("正常流-3:DataExportService 应提供加密包生成入口(package/generate/encrypt)")
+    void dataExportService_hasPackageGenerateEntry() {
+        Class<?> clazz = hostClass();
+        boolean hasPackageBuilder = methodNameContains(clazz, "package") && (
+                methodNameContains(clazz, "generate")
+                        || methodNameContains(clazz, "build")
+                        || methodNameContains(clazz, "create")
+                        || methodNameContains(clazz, "encrypt"));
+        assertTrue(hasPackageBuilder,
+                "[data.export.gdpr] DataExportService 应提供加密包生成入口(方法名含 package 且 "
+                        + "generate/build/create/encrypt,如 buildExportPackage):契约要求「生成加密包」"
+                        + "而非同步裸返回明文 Map(SC-P-72 正常流)。实现未落地:宿主类不存在。");
+    }
+
+    @Test
+    @DisplayName("正常流-4:DataExportService 应提供 downloadPackage 下载入口")
+    void dataExportService_hasDownloadEntry() {
+        Method download = findMethodContains(hostClass(), "download");
+        assertNotNull(download,
+                "[data.export.gdpr] DataExportService 应提供 downloadPackage(...) 下载入口"
+                        + "(申请导出 → 生成加密包 → 下载 三阶段之末,SC-P-72 正常流)。实现未落地:宿主类不存在。");
+    }
+
+    // ==================== 边界/异常流(TC-P-72-E):频次限制 + 脱敏 + 加密包字段 ====================
+
+    @Test
+    @DisplayName("边界流-1:DataExportService 应有频次限制守卫(RATE_LIMIT 常量或 rateLimit/checkFrequency 方法)")
+    void applyExport_hasRateLimitGuard() {
+        Class<?> clazz = hostClass();
+        boolean hasRateLimit = fieldNameContains(clazz, "rate_limit")
+                || fieldNameContains(clazz, "frequency")
+                || methodNameContains(clazz, "ratelimit")
+                || methodNameContains(clazz, "checkfrequency")
+                || methodNameContains(clazz, "assertfrequency");
+        assertTrue(hasRateLimit,
+                "[data.export.gdpr] applyExport 应含频次限制守卫:SC-P-72 边界「频次限制」"
+                        + "(建议 24h 窗口,RATE_LIMIT_WINDOW_HOURS 常量或 checkRateLimit 方法),"
+                        + "超限申请应被拒。实现未落地:宿主类不存在。");
+    }
+
+    @Test
+    @DisplayName("边界流-2:DataExportTask 实体与 data_export_task 表应存在(申请→加密包→下载 工单载体)")
+    void dataExportTask_entityAndTableExist() {
+        String schema = readSchemaSql();
+        assertNotNull(loadClass(TASK_ENTITY),
+                "[data.export.gdpr] DataExportTask 实体不存在:SC-P-72 要求导出为「申请 → 生成加密包 → 下载」"
+                        + "有状态流程,需 data_export_task 工单承载。实现未落地。");
+        assertTrue(schema.contains(TASK_TABLE),
+                "[data.export.gdpr] schema.sql 缺少 " + TASK_TABLE + " 建表(导出工单,SC-P-72 流程载体)。");
+    }
+
+    @Test
+    @DisplayName("边界流-3:DataExportTask 应含工单状态与加密包字段(status/packagePath/packageKey/expiresAt)")
+    void dataExportTask_hasPackageStateFields() {
+        Class<?> entity = loadClass(TASK_ENTITY);
+        if (entity == null) {
+            fail("[data.export.gdpr] DataExportTask 实体不存在,无法校验工单状态字段(SC-P-72 加密包流程)。");
+        }
+        for (String required : new String[]{"status", "packagePath", "packageKey", "expiresAt"}) {
+            boolean has = fieldNameEquals(entity, required);
+            assertTrue(has,
+                    "[data.export.gdpr] DataExportTask 应含 " + required + " 字段:加密包流程工单"
+                            + "(status=导出状态、packagePath=加密包路径、packageKey=加密密钥、expiresAt=有效/频次窗口)。"
+                            + "当前实体缺失。");
+        }
+    }
+
+    @Test
+    @DisplayName("边界流-4:DataExportService 应暴露敏感字段脱敏方法(mask/desensitize,复用 DataMaskUtil)")
+    void dataExportService_masksSensitiveFields() {
+        Method mask = findMethodContains(hostClass(), "mask");
+        assertNotNull(mask,
+                "[data.export.gdpr] DataExportService 应提供敏感字段脱敏方法(如 maskSensitiveFields,"
+                        + "复用 DataMaskUtil.maskPhone/maskName):SC-P-72 边界「敏感字段脱敏」(对齐 SC-T-29/"
+                        + "SC-S-11 合规口径,phone/realName/idCard 强制脱敏)。实现未落地:宿主类不存在。");
+    }
+
+    @Test
+    @DisplayName("边界流-5:现有导出载体 exportUserData 的家庭成员块 phone 应脱敏(当前明文,红)")
+    void exportUserData_familyMemberPhone_shouldBeMasked() {
+        // Given:家庭内有一名成员(phone 明文),其余导出区块无数据
+        User parent = new User();
+        parent.setId(PARENT_USER_ID);
+        parent.setFamilyId(FAMILY_ID);
+        when(userMapper.selectById(PARENT_USER_ID)).thenReturn(parent);
+
+        FamilyMember member = new FamilyMember();
+        member.setId(CHILD_MEMBER_ID);
+        member.setFamilyId(FAMILY_ID);
+        member.setPhone(RAW_PHONE);
+        when(familyMemberMapper.selectList(any())).thenReturn(Collections.singletonList(member));
+        when(danAssessmentResultMapper.selectList(any())).thenReturn(Collections.emptyList());
+        when(healthReportMapper.selectList(any())).thenReturn(Collections.emptyList());
+        when(taskMapper.selectList(any())).thenReturn(Collections.emptyList());
+
+        // When:导出个人数据包(复用 /api/user 载体,设计指定汇集导出)
+        Map<String, Object> data = service.exportUserData(PARENT_USER_ID);
+
+        // Then:家庭成员(他人数据)的敏感字段 phone 必须脱敏,不得明文
+        Object children = data.get("children");
+        assertNotNull(children,
+                "[data.export.gdpr] 导出包应包含家庭成员 children 区块(SC-P-72 个人/家庭数据导出)。");
+        @SuppressWarnings("unchecked")
+        List<FamilyMember> members = (List<FamilyMember>) children;
+        assertFalse(members.isEmpty(),
+                "[data.export.gdpr] 家庭成员区块不应为空(SC-P-72 家庭数据导出汇集 /api/family/member/list)。");
+        for (FamilyMember fm : members) {
+            String phone = fm.getPhone();
+            assertFalse(phone != null && phone.contains(RAW_PHONE),
+                    "[data.export.gdpr] 导出包家庭成员 phone 应脱敏(如 138****8000,复用 DataMaskUtil):"
+                            + "SC-P-72 边界「敏感字段脱敏」。当前实现将 family_members 全量实体裸导出"
+                            + "(含 phone 明文),脱敏契约未落地。");
+        }
+    }
+
+    // ==================== 权限流(TC-P-72-P):越权导出被拒 ====================
+
+    @Test
+    @DisplayName("权限流-1:applyExport/downloadPackage 应携带显式 memberId 范围入参(G-05 家长代导出指定成员)")
+    void applyExport_carriesScopeMemberId() {
+        Class<?> clazz = hostClass();
+        Method apply = findMethodContains(clazz, "apply");
+        assertNotNull(apply,
+                "[data.export.gdpr] 申请导出入口缺失(宿主未实现),无法校验范围入参契约。");
+        boolean scopeAware = hasNumberOrMapParam(apply);
+        assertTrue(scopeAware,
+                "[data.export.gdpr] applyExport 应携带显式导出范围(scopeMemberId/memberId 数值入参或 Map 载体),"
+                        + "支撑「家长代导出指定成员」(G-05,API_REFERENCE §4.61.5:无 memberId 入参 → 无代导出)"
+                        + "与「越权导出被拒」(TC-P-72-P 权限流)。");
+    }
+
+    @Test
+    @DisplayName("权限流-2:DataExportService 应有归属校验守卫(assertCanExport/checkExportPermission,越权拒)")
+    void dataExportService_hasOwnershipGuard() {
+        Class<?> clazz = hostClass();
+        boolean guarded = methodNameContains(clazz, "assert")        // assertCanExport
+                || methodNameContains(clazz, "check")               // checkExportPermission
+                || methodNameContains(clazz, "permission")
+                || methodNameContains(clazz, "ownership")
+                || methodNameContains(clazz, "authorize");
+        assertTrue(guarded,
+                "[data.export.gdpr] applyExport/downloadPackage 须有归属校验守卫(如 assertCanExport/"
+                        + "checkExportPermission):非本家庭成员/非绑定家庭不得导出他人数据(SC-P-72 边界"
+                        + "「越权导出被拒」,TC-P-72-P 权限流)。实现未落地:宿主类不存在。");
+    }
+
+    @Test
+    @DisplayName("权限流-3:现有导出载体 exportUserData 应支持 memberId 范围入参(G-05;当前仅 1 参,红)")
+    void exportUserData_shouldCarryScopeMemberId() {
+        Class<?> carrier = loadClass(EXPORT_CARRIER);
+        if (carrier == null) {
+            fail("[data.export.gdpr] AccountCleanupService 载体类不存在(异常状态)。");
+        }
+        boolean hasScopeParam = false;
+        for (Method m : carrier.getDeclaredMethods()) {
+            if (m.getName().equals("exportUserData") && m.getParameterCount() >= 2) {
+                hasScopeParam = true;
+                break;
+            }
+        }
+        assertTrue(hasScopeParam,
+                "[data.export.gdpr] " + EXPORT_CARRIER + ".exportUserData 应支持 memberId 范围入参"
+                        + "(如 exportUserData(Long userId, Long scopeMemberId)):G-05 缺口——无 memberId 入参则"
+                        + "无「家长代导出指定成员」、也无越权归属校验载体(TC-P-72-P 权限流)。"
+                        + "当前仅 exportUserData(Long) 1 参,实现未落地。");
+    }
+
+    // ==================== 反射辅助(锚定宿主契约,避免编译期依赖不存在类) ====================
+
+    /** 解析宿主类;不存在即断言失败(RED 信号:实现未落地),并清晰贴出缺口。 */
+    private Class<?> hostClass() {
+        try {
+            return Class.forName(HOST_CLASS);
+        } catch (ClassNotFoundException e) {
+            fail("RED[data.export.gdpr] 契约宿主 " + HOST_CLASS + " 未实现(实现未落地):"
+                    + "SC-P-72 个人/家庭数据导出(GDPR)「申请导出 → 生成加密包 → 下载」流程宿主缺失"
+                    + "(模块:数据导出(GDPR);复用 /api/user、/api/family/member/list 汇集导出;"
+                    + "现有 UserController /api/user/data-export 仅同步返回明文 Map,无加密包/频次/越权校验)。"
+                    + "缺失详情:" + e.getMessage());
+            throw new IllegalStateException("unreachable");
+        }
+    }
+
+    private Class<?> loadClass(String name) {
+        try {
+            return Class.forName(name, false, Thread.currentThread().getContextClassLoader());
+        } catch (ClassNotFoundException e) {
+            return null;
+        }
+    }
+
+    /** 方法名包含关键字的首个匹配;无则 null。 */
+    private Method findMethodContains(Class<?> clazz, String keywordLower) {
+        if (clazz == null) {
+            return null;
+        }
+        for (Method m : clazz.getDeclaredMethods()) {
+            if (m.getName().toLowerCase().contains(keywordLower)) {
+                return m;
+            }
+        }
+        return null;
+    }
+
+    private boolean methodNameContains(Class<?> clazz, String keywordLower) {
+        if (clazz == null) {
+            return false;
+        }
+        for (Method m : clazz.getDeclaredMethods()) {
+            if (m.getName().toLowerCase().contains(keywordLower)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private boolean fieldNameContains(Class<?> clazz, String keywordLower) {
+        if (clazz == null) {
+            return false;
+        }
+        for (Field f : clazz.getDeclaredFields()) {
+            if (f.getName().toLowerCase().contains(keywordLower)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private boolean fieldNameEquals(Class<?> clazz, String name) {
+        if (clazz == null) {
+            return false;
+        }
+        for (Field f : clazz.getDeclaredFields()) {
+            if (f.getName().equals(name)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /** 方法参数含数值 ID(Long/memberId 载体)或 Map(scopeMemberId 键)→ 支持显式导出范围。 */
+    private boolean hasNumberOrMapParam(Method m) {
+        for (Class<?> p : m.getParameterTypes()) {
+            if (Number.class.isAssignableFrom(p) || p.isPrimitive()
+                    || Map.class.isAssignableFrom(p)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private String readSchemaSql() {
+        try (InputStream is = getClass().getClassLoader().getResourceAsStream("schema.sql")) {
+            if (is == null) {
+                return "";
+            }
+            try (Scanner scanner = new Scanner(is, StandardCharsets.UTF_8.name())) {
+                scanner.useDelimiter("\\A");
+                return scanner.hasNext() ? scanner.next() : "";
+            }
+        } catch (Exception e) {
+            return "";
+        }
+    }
+}

+ 280 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/EnergyDailyLimitGuardContractTest.java

@@ -0,0 +1,280 @@
+package com.etotem.cfc.unit;
+
+import com.etotem.cfc.entity.DimensionDailyLimit;
+import com.etotem.cfc.entity.EnergyBalance;
+import com.etotem.cfc.entity.EnergyDimension;
+import com.etotem.cfc.entity.EnergyLog;
+import com.etotem.cfc.entity.FamilyMember;
+import com.etotem.cfc.mapper.DimensionDailyLimitMapper;
+import com.etotem.cfc.mapper.EnergyBalanceMapper;
+import com.etotem.cfc.mapper.EnergyBehaviorConfigMapper;
+import com.etotem.cfc.mapper.EnergyDimensionMapper;
+import com.etotem.cfc.mapper.EnergyLogMapper;
+import com.etotem.cfc.mapper.EnergySourceConfigMapper;
+import com.etotem.cfc.mapper.FamilyMemberMapper;
+import com.etotem.cfc.service.EnergyRuleEngine;
+import com.etotem.cfc.service.EnergyService;
+import com.etotem.cfc.service.NotificationDispatchService;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.lang.reflect.Modifier;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.Date;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assertions.fail;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * 能力键 {@code energy.dailyLimit.guard}(任务 S-cfc-306,TDD-RED 阶段)契约级单测。
+ *
+ * <p><b>需求/设计溯源</b></p>
+ * <ul>
+ *   <li>需求:{@code tests/user-scenarios/应用场景总览.md} SC-P-90(五维每日获取上限 DailyLimit)
+ *       + {@code tests/user-scenarios/07-five-dimension.md} 场景 ED-4(单维度单日累计触顶后不再累加、
+ *       次日重置;多来源共享日上限;手动是否计入需断言一致;跨时区以服务端日期为准;上限 0/负不崩溃);
+ *       契约条款 {@code tests/test-cases/parent.md} TC-P-90 / TC-P-90-E / TC-P-90-P。</li>
+ *   <li>设计:{@code docs/superpowers/api/API_REFERENCE.md} 模块 {@code DimensionDailyLimit} /
+ *       {@code EnergyController};与 {@code energy.ruleEngine.apply}(S-cfc-304)同链:
+ *       <b>ruleEngine 写入前经 daily limit 守卫校验</b>(SC-P-90 设计锚点)。</li>
+ * </ul>
+ *
+ * <p><b>被校验的契约行为(TDD-RED 锚点,当前实现未落地 → 红)</b></p>
+ * <ul>
+ *   <li><b>守卫入口(SC-P-90 设计:ruleEngine 写入前经守卫校验)</b>:{@link EnergyService} 应提供
+ *       <b>public</b> 每日上限守卫方法(命名含 {@code guard/isAllowed/checkDailyLimit})——
+ *       当前 {@code isDailyLimitExceeded} 为 private,无 public 守卫入口(反射结构探测);</li>
+ *   <li><b>守卫钩子(S-cfc-304 同链)</b>:{@link EnergyRuleEngine} 应有 daily-limit 守卫钩子方法,
+ *       {@code evaluate} 写入前调用——当前无任何 guard 方法(反射结构探测);</li>
+ *   <li><b>配置驱动(TC-P-90 前置)</b>:{@link EnergyService} 应注入 {@link DimensionDailyLimitMapper}
+ *       读取 {@code energy_daily_limit} 配置驱动上限——当前无该字段,使用硬编码
+ *       {@code DAILY_LIMIT_MAP}(反射结构探测);</li>
+ *   <li><b>多来源共享日上限(TC-P-90-E-1)</b>:{@code awardEnergyByCode}(challenge 来源)应受日上限
+ *       约束——当前直接 {@code executeAward} 绕过(行为断言);</li>
+ *   <li><b>上限 0/负安全(TC-P-90-E-4)</b>:配置 {@code dailyLimit=0/负} 应按 0 处理不发且不崩溃——
+ *       当前未读取配置(行为断言)。</li>
+ * </ul>
+ *
+ * <p><b>正常流锚点(已实现 → 绿,如实记录非 RED)</b></p>
+ * <ul>
+ *   <li>硬编码单维度上限({@code body=50})当日累计触顶后 {@code grantEnergy} 再发 → 抛
+ *       {@link IllegalStateException}(超限拦截已生效);</li>
+ *   <li>手动 grant 口径 = 计入日上限({@code grantEnergy} 调用 {@code isDailyLimitExceeded})。</li>
+ * </ul>
+ *
+ * <p><b>权限流(TC-P-90-P)</b>:本能力为内部服务守卫(ruleEngine→award 写入前的校验钩子),
+ * 无用户权限维度;「查 F9 成员日上限累计 403 / 越权改配置 403」由
+ * {@link EnergyIsolationContractTest} 与 {@link EnergyConfigAdminContractTest}(admin 守卫)覆盖,
+ * 本类标注「不适用」。</p>
+ *
+ * <p><b>RED 预期</b>:5 条契约缺口断言失败(红)、2 条正常流锚点通过(绿)、1 条权限流标注(通过);
+ * 失败原文含 {@code RED[energy.dailyLimit.guard] …}。GREEN 阶段按 SC-P-90 设计落地
+ * (public 守卫 + {@code DimensionDailyLimitMapper} 配置驱动 + 多来源一致 + 0/负安全)后自动转绿。</p>
+ *
+ * <p><b>测试范围</b>:纯 Mockito / 无 Spring 上下文 / 无 DB / 无外部服务;直接实例化
+ * {@link EnergyService} 并注入 mock,反射结构探测 + 行为断言(复用
+ * {@link EnergyContractTestBase#inject}/{@link EnergyContractTestBase#initTable}/
+ * {@link EnergyContractTestBase#fiveDims}/{@link EnergyContractTestBase#energyLog})。</p>
+ */
+class EnergyDailyLimitGuardContractTest extends EnergyContractTestBase {
+
+    private static final Long MEMBER_ID = 50L;
+    private static final Long BODY_DIM_ID = 5L;
+    private static final String BODY_CODE = "body";
+
+    private EnergyService service;
+
+    private EnergyDimensionMapper dimensionMapper;
+    private EnergyBehaviorConfigMapper behaviorConfigMapper;
+    private EnergyLogMapper logMapper;
+    private EnergyBalanceMapper balanceMapper;
+    private FamilyMemberMapper familyMemberMapper;
+    private EnergySourceConfigMapper sourceConfigMapper;
+
+    @BeforeEach
+    void setUp() throws Exception {
+        service = new EnergyService();
+        dimensionMapper = mock(EnergyDimensionMapper.class);
+        behaviorConfigMapper = mock(EnergyBehaviorConfigMapper.class);
+        logMapper = mock(EnergyLogMapper.class);
+        balanceMapper = mock(EnergyBalanceMapper.class);
+        familyMemberMapper = mock(FamilyMemberMapper.class);
+        sourceConfigMapper = mock(EnergySourceConfigMapper.class);
+
+        inject(service, "energyDimensionMapper", dimensionMapper);
+        inject(service, "energyBehaviorConfigMapper", behaviorConfigMapper);
+        inject(service, "energyLogMapper", logMapper);
+        inject(service, "energyBalanceMapper", balanceMapper);
+        inject(service, "familyMemberMapper", familyMemberMapper);
+        inject(service, "energySourceConfigMapper", sourceConfigMapper);
+        inject(service, "notificationDispatchService", mock(NotificationDispatchService.class));
+        inject(service, "wishMapper", mock(com.etotem.cfc.mapper.WishMapper.class));
+
+        when(dimensionMapper.selectList(any())).thenReturn(Arrays.asList(fiveDims()));
+        when(behaviorConfigMapper.selectOne(any())).thenReturn(null);
+        when(logMapper.selectList(any())).thenReturn(Collections.emptyList());
+        when(balanceMapper.selectOne(any())).thenReturn(null);
+
+        FamilyMember member = new FamilyMember();
+        member.setId(MEMBER_ID);
+        member.setUserId(12L);
+        when(familyMemberMapper.selectById(any())).thenReturn(member);
+
+        initTable(EnergyDimension.class);
+        initTable(EnergyLog.class);
+        initTable(EnergyBalance.class);
+    }
+
+    // ==================== RED:守卫入口(SC-P-90 设计,ruleEngine 写入前经守卫校验) ====================
+
+    @Test
+    @DisplayName("RED:EnergyService 应提供 public 每日上限守卫入口")
+    void RED_守卫入口_EnergyService_public() {
+        boolean hasPublicGuard = false;
+        for (Method m : EnergyService.class.getDeclaredMethods()) {
+            if (m.getName().matches("(?i).*(guard|isallowed|checkdaily|dailylimit).*")
+                    && Modifier.isPublic(m.getModifiers())) {
+                hasPublicGuard = true;
+                break;
+            }
+        }
+        assertTrue(hasPublicGuard,
+                "RED[energy.dailyLimit.guard]:EnergyService 应提供 public 每日上限守卫方法"
+                        + "(命名含 guard/isAllowed/checkDailyLimit),供 ruleEngine 写入前校验(SC-P-90 设计)。"
+                        + "当前 isDailyLimitExceeded 为 private,无 public 守卫入口。");
+    }
+
+    @Test
+    @DisplayName("RED:EnergyRuleEngine 应有 daily-limit 守卫钩子(S-cfc-304 同链)")
+    void RED_守卫钩子_EnergyRuleEngine() {
+        boolean hasGuard = false;
+        for (Method m : EnergyRuleEngine.class.getDeclaredMethods()) {
+            if (m.getName().matches("(?i).*(guard|dailylimit).*")) {
+                hasGuard = true;
+                break;
+            }
+        }
+        assertTrue(hasGuard,
+                "RED[energy.dailyLimit.guard]:EnergyRuleEngine 应有 daily-limit 守卫钩子方法"
+                        + "(ruleEngine 写入前经守卫校验,S-cfc-304 同链),当前无任何 guard 方法。");
+    }
+
+    // ==================== RED:配置驱动(TC-P-90 前置:DimensionDailyLimit 配 dailyLimit=N) ====================
+
+    @Test
+    @DisplayName("RED:EnergyService 应注入 DimensionDailyLimitMapper(配置驱动上限)")
+    void RED_配置驱动_dimensionDailyLimitMapper() {
+        boolean hasMapper = false;
+        for (Field f : EnergyService.class.getDeclaredFields()) {
+            if (f.getType().getName().equals("com.etotem.cfc.mapper.DimensionDailyLimitMapper")) {
+                hasMapper = true;
+                break;
+            }
+        }
+        assertTrue(hasMapper,
+                "RED[energy.dailyLimit.guard]:EnergyService 应注入 DimensionDailyLimitMapper"
+                        + "读取 energy_daily_limit 配置驱动上限(TC-P-90 前置:DimensionDailyLimit 配 dailyLimit=N)。"
+                        + "当前无该字段,使用硬编码 DAILY_LIMIT_MAP(body=50 等),配置变更不生效。");
+    }
+
+    // ==================== RED:多来源共享日上限(TC-P-90-E-1) ====================
+
+    @Test
+    @DisplayName("RED:多来源共享日上限 — challenge 来源 awardEnergyByCode 绕过日上限")
+    void RED_多来源共享_challenge绕过日上限() {
+        // 当日 body 累计=49(来自 checkin 来源),body 硬编码上限=50,再发 10 → 契约要求超限不发
+        EnergyLog todayCumulative = energyLog(1L, MEMBER_ID, BODY_DIM_ID, 49, 49, "checkin", 1L);
+        when(logMapper.selectList(any())).thenReturn(Arrays.asList(todayCumulative));
+
+        // awardEnergyByCode(challenge 来源)应受日上限约束(多来源共享同一日上限)
+        Map<String, Integer> result = service.awardEnergyByCode(MEMBER_ID, BODY_CODE, 10, "挑战奖励");
+
+        assertTrue(result.isEmpty(),
+                "RED[energy.dailyLimit.guard]:当日 body 累计=49(多来源共享),再发 10 → 超限不发,应返回空。"
+                        + "当前 awardEnergyByCode 绕过日上限直接 executeAward → 发放成功(多来源共享日上限缺口)。");
+        verify(logMapper, never()).insert(any(EnergyLog.class));
+    }
+
+    // ==================== RED:上限 0/负安全(TC-P-90-E-4) ====================
+
+    @Test
+    @DisplayName("RED:上限 0/负安全 — 配置 dailyLimit=0 应按 0 处理不发且不崩溃")
+    void RED_上限零负_按零处理() {
+        // 前置:EnergyService 缺 dimensionDailyLimitMapper 字段(配置驱动未落地)→ precondition RED
+        DimensionDailyLimitMapper dailyLimitMapper;
+        try {
+            dailyLimitMapper = mock(DimensionDailyLimitMapper.class);
+            inject(service, "dimensionDailyLimitMapper", dailyLimitMapper);
+            initTable(DimensionDailyLimit.class);
+        } catch (Exception e) {
+            fail("RED[energy.dailyLimit.guard] precondition:EnergyService 缺 dimensionDailyLimitMapper 字段"
+                    + "(" + e.getClass().getSimpleName() + "),无法注入配置读取"
+                    + "(TC-P-90-E-4:日上限配 0/负 拒绝配置或按 0 处理、不崩溃)。");
+            return;
+        }
+
+        // 配置 body dailyLimit=0 → 任何发放应被拦截(按 0 处理,不崩溃)
+        DimensionDailyLimit zeroLimit = new DimensionDailyLimit();
+        zeroLimit.setId(1L);
+        zeroLimit.setDimensionCode(BODY_CODE);
+        zeroLimit.setDailyLimit(0);
+        zeroLimit.setCreatedAt(new Date());
+        zeroLimit.setUpdatedAt(new Date());
+        when(dailyLimitMapper.selectList(any())).thenReturn(Arrays.asList(zeroLimit));
+
+        Map<String, Integer> result = service.awardEnergyByCode(MEMBER_ID, BODY_CODE, 10, "测试");
+
+        assertTrue(result.isEmpty(),
+                "RED[energy.dailyLimit.guard]:配置 dailyLimit=0 → 应按 0 处理不发,应返回空。"
+                        + "当前实现未读取配置 → 使用硬编码上限 → 放行(0/负安全缺口)。");
+    }
+
+    // ==================== 正常流锚点(已实现 → 绿,如实记录非 RED) ====================
+
+    @Test
+    @DisplayName("GREEN anchor:硬编码单维度上限生效 — body 累计触顶再发抛 IllegalStateException")
+    void GREEN_硬编码上限生效() {
+        // 当日 body 累计=50,body 硬编码上限=50,再发 5 → 超限抛异常(当前实现已生效)
+        EnergyLog todayCumulative = energyLog(1L, MEMBER_ID, BODY_DIM_ID, 50, 50, "task", 1L);
+        when(logMapper.selectList(any())).thenReturn(Arrays.asList(todayCumulative));
+
+        assertThrows(IllegalStateException.class, () ->
+                        service.grantEnergy(MEMBER_ID, 8888L, 5L, BODY_CODE),
+                "GREEN anchor:硬编码上限 body=50,当日累计≥50 再发 → 抛 IllegalStateException(当前实现已生效)。");
+    }
+
+    @Test
+    @DisplayName("GREEN anchor:手动 grant 口径 = 计入日上限")
+    void GREEN_手动grant口径计入() {
+        // grantEnergy 调用 isDailyLimitExceeded → 手动发放计入日上限(口径=计入,需与规则来源一致)
+        EnergyLog todayCumulative = energyLog(1L, MEMBER_ID, BODY_DIM_ID, 48, 48, "checkin", 1L);
+        when(logMapper.selectList(any())).thenReturn(Arrays.asList(todayCumulative));
+
+        // body 累计=48 + 5 = 53 > 50 → 抛异常(手动 grant 受限,口径=计入)
+        assertThrows(IllegalStateException.class, () ->
+                        service.grantEnergy(MEMBER_ID, 8888L, 5L, BODY_CODE),
+                "GREEN anchor:手动 grant 计入日上限(grantEnergy 调用 isDailyLimitExceeded)。");
+    }
+
+    // ==================== 权限流(不适用,说明性用例) ====================
+
+    @Test
+    @DisplayName("权限流:内部服务守卫,访问控制在 Controller 层,权限流不适用")
+    void 权限流_不适用() {
+        // 契约 AC 为「ruleEngine→award 写入前的 daily limit 守卫校验」内部链路,无用户权限维度。
+        // TC-P-90-P(查 F9 成员日上限累计 403 / 越权改配置 403)由 EnergyIsolationContractTest(数据隔离)
+        // 与 EnergyConfigAdminContractTest(admin 守卫 /daily-limit-save)覆盖,此处标注不适用。
+        assertTrue(true, "权限流不适用:energy.dailyLimit.guard 为内部服务守卫,无用户权限维度。");
+    }
+}

+ 357 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/FamilyChildContextSwitchContractTest.java

@@ -0,0 +1,357 @@
+package com.etotem.cfc.unit;
+
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.controller.family.FamilyMembersController;
+import com.etotem.cfc.dto.SwitchMemberVO;
+import com.etotem.cfc.entity.FamilyMember;
+import com.etotem.cfc.entity.User;
+import com.etotem.cfc.mapper.FamilyMemberMapper;
+import com.etotem.cfc.mapper.UserMapper;
+import com.etotem.cfc.service.FamilyMemberService;
+import com.etotem.cfc.service.SystemConfigService;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.MockitoAnnotations;
+import org.springframework.security.access.AccessDeniedException;
+
+import java.lang.reflect.Field;
+import java.util.Calendar;
+import java.util.Collections;
+import java.util.Date;
+import java.util.HashMap;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * 契约级单测:能力键 {@code family.childContext.switch}(SC-P-73 多孩子切换孩子上下文,TDD-RED 阶段)。
+ *
+ * <p><b>溯源·需求</b>:{@code tests/user-scenarios/应用场景总览.md} SC-P-73(业务域 J)——
+ * 多孩子家庭切换:选孩子 → 任务/报告/方案上下文切换;边界:仅本家庭孩子可选;当前孩子态隔离。
+ * 派生用例 {@code tests/test-cases/parent.md} TC-P-73(正常)/ TC-P-73-E(异常)/ TC-P-73-P(权限)。</p>
+ *
+ * <p><b>溯源·设计</b>:{@code docs/superpowers/api/API_REFERENCE.md} §4.2 / §4.61.1 / §4.63.1——
+ * 载体 {@code POST /api/family/member/switch}(FamilyMembersController.switchToMember →
+ * FamilyMemberService.switchToMember)→ 响应 {@code SwitchMemberVO{memberId, source,
+ * effectiveRole, nickname, isSwitchable}}。
+ * 与能力键 {@code family.parent.switchRole}(S-cfc-11,P-03 家长↔孩子角色切换)区分:
+ * 本键 = P-73 <b>孩子间上下文切换</b>(多孩子家庭中切换当前孩子态)。</p>
+ *
+ * <p><b>实现现状与 RED 锚点</b>:端点 {@code /switch} 已存在并落地了「家长 → 不可登录孩子」的
+ * 单次视角切换(P-03 语义),但 P-73 的<b>孩子上下文分类/隔离</b>默认值未落地——
+ * {@code computeEffectiveRole} 在被切换的不可登录孩子(managed child,{@code userId=null})
+ * <b>既无 birthday 又无 generation</b> 时默认返回 {@code "parent"}(FamilyMemberService.java:1392),
+ * 导致「选孩子」后返回的 {@code effectiveRole="parent"}、前端据此把当前孩子上下文误判为家长上下文,
+ * 违反 SC-P-73「选孩子 → 任务/报告/方案按孩子上下文隔离」契约(RED 用例)。
+ * 其余(跨家庭拒绝 / 自切拒绝 / 可登录成员拒绝 / 孩子端切家长拒绝 / 端点 401 / 缺 memberId)当前已落地,
+ * 作为 GREEN 锁定用例,防 GREEN 阶段误伤已落地行为。</p>
+ *
+ * <p><b>测试范围</b>:纯 Mockito / 反射,无 Spring 上下文 / 无 DB / 无微信 / 无外部服务。
+ * 风格对齐同批 RED 契约测试(FamilyRemoveMemberContractTest / FamilyJoinValidationRulesContractTest)——
+ * 结果契约断言 + RED/GREEN 混编锁定。</p>
+ */
+@DisplayName("family.childContext.switch 契约(FamilyMembersController /switch → FamilyMemberService.switchToMember)")
+class FamilyChildContextSwitchContractTest {
+
+    /** 被测试家庭 */
+    private static final Long FAMILY_ID = 100L;
+    /** 当前登录家长 userId */
+    private static final Long PARENT_USER_ID = 1L;
+    /** 不能登录孩子成员(managed child,family_members.userId = null)A */
+    private static final Long CHILD_A_MEMBER_ID = 11L;
+    /** 不能登录孩子成员(managed child,family_members.userId = null)B —— 切换目标 */
+    private static final Long CHILD_B_MEMBER_ID = 12L;
+    /** 可登录成员关联 userId(有 openid) */
+    private static final Long LOGIN_MEMBER_USER_ID = 200L;
+    /** 非本家庭 memberId */
+    private static final Long OTHER_FAMILY_MEMBER_ID = 999L;
+    /** 孩子年龄阈值(测试桩) */
+    private static final int CHILD_AGE_THRESHOLD = 18;
+
+    // ---------------- Service 层被测对象及依赖 ----------------
+    @Mock
+    private FamilyMemberMapper familyMemberMapper;
+    @Mock
+    private UserMapper userMapper;
+    @Mock
+    private SystemConfigService systemConfigService;
+
+    @InjectMocks
+    private FamilyMemberService familyMemberService;
+
+    // ---------------- Controller 层被测对象 ----------------
+    private FamilyMembersController controller;
+    /** Controller 层注入的 mock 服务(verify 用) */
+    private FamilyMemberService controllerService;
+
+    @BeforeEach
+    void setUp() throws Exception {
+        MockitoAnnotations.openMocks(this);
+        when(systemConfigService.getChildAgeThreshold()).thenReturn(CHILD_AGE_THRESHOLD);
+
+        // Controller 层:反射注入 mock 的 FamilyMemberService(贴合既有 unit 风格)
+        controller = new FamilyMembersController();
+        controllerService = mock(FamilyMemberService.class);
+        setField(controller, "familyMemberService", controllerService);
+    }
+
+    // ====================================================================
+    // Controller 契约层(POST /api/family/member/switch)
+    // ====================================================================
+
+    @Test
+    @DisplayName("Controller 正常流:memberId 传递到服务层,返回 SwitchMemberVO")
+    void controller_正常切换_透传服务层VO() {
+        SwitchMemberVO vo = childContextVo(CHILD_B_MEMBER_ID, "child");
+        when(controllerService.switchToMember(PARENT_USER_ID, CHILD_B_MEMBER_ID)).thenReturn(vo);
+
+        Result<SwitchMemberVO> r = controller.switchToMember(body(CHILD_B_MEMBER_ID), PARENT_USER_ID);
+
+        assertEquals(200, r.getCode());
+        assertNotNull(r.getData());
+        assertEquals(CHILD_B_MEMBER_ID, r.getData().getMemberId());
+        verify(controllerService).switchToMember(PARENT_USER_ID, CHILD_B_MEMBER_ID);
+    }
+
+    @Test
+    @DisplayName("Controller 异常流:未登录(userId=null)→ 401,不触达服务层")
+    void controller_未登录_userId为null_401() {
+        Result<SwitchMemberVO> r = controller.switchToMember(body(CHILD_B_MEMBER_ID), null);
+        assertEquals(401, r.getCode());
+        assertEquals("请先登录", r.getMessage());
+        verify(controllerService, never()).switchToMember(any(), any());
+    }
+
+    @Test
+    @DisplayName("Controller 异常流:缺 memberId → 400「缺少成员ID」,不触达服务层")
+    void controller_缺少memberId_400() {
+        Result<SwitchMemberVO> r = controller.switchToMember(Collections.emptyMap(), PARENT_USER_ID);
+        assertEquals(400, r.getCode());
+        assertEquals("缺少成员ID", r.getMessage());
+        verify(controllerService, never()).switchToMember(any(), any());
+    }
+
+    // ====================================================================
+    // Service 正常流(SC-P-73 / TC-P-73:选孩子 → 孩子上下文切换)
+    // ====================================================================
+
+    @Test
+    @DisplayName("正常流-1:多孩子家庭,家长切换到本家庭不可登录孩子B → 返回孩子B上下文VO")
+    void service_多孩子切换到孩子B_返回孩子B上下文VO() {
+        stubParent(PARENT_USER_ID);
+        FamilyMember childB = managedChild(CHILD_B_MEMBER_ID, ageYearsAgo(10), "小宝");
+        when(familyMemberMapper.selectById(CHILD_B_MEMBER_ID)).thenReturn(childB);
+
+        SwitchMemberVO vo = familyMemberService.switchToMember(PARENT_USER_ID, CHILD_B_MEMBER_ID);
+
+        assertNotNull(vo);
+        assertEquals(CHILD_B_MEMBER_ID, vo.getMemberId());
+        assertEquals("family_member", vo.getSource());
+        assertEquals("child", vo.getEffectiveRole());
+        assertEquals("小宝", vo.getNickname());
+        assertTrue(Boolean.TRUE.equals(vo.getIsSwitchable()));
+    }
+
+    @Test
+    @DisplayName("正常流-2:目标孩子有 birthday 且未成年 → effectiveRole=child")
+    void service_目标孩子有生日未成年_effectiveRole为child() {
+        stubParent(PARENT_USER_ID);
+        FamilyMember childB = managedChild(CHILD_B_MEMBER_ID, ageYearsAgo(10), null);
+        when(familyMemberMapper.selectById(CHILD_B_MEMBER_ID)).thenReturn(childB);
+
+        SwitchMemberVO vo = familyMemberService.switchToMember(PARENT_USER_ID, CHILD_B_MEMBER_ID);
+
+        assertEquals("child", vo.getEffectiveRole());
+    }
+
+    @Test
+    @DisplayName("正常流-3:目标孩子无 birthday 但 generation 为负 → effectiveRole=child")
+    void service_目标孩子无生日generation为负_effectiveRole为child() {
+        stubParent(PARENT_USER_ID);
+        FamilyMember childB = managedChild(CHILD_B_MEMBER_ID, null, null);
+        childB.setGeneration(-1);
+        when(familyMemberMapper.selectById(CHILD_B_MEMBER_ID)).thenReturn(childB);
+
+        SwitchMemberVO vo = familyMemberService.switchToMember(PARENT_USER_ID, CHILD_B_MEMBER_ID);
+
+        assertEquals("child", vo.getEffectiveRole());
+    }
+
+    /**
+     * <b>RED 用例</b>:被切换的不可登录孩子(managed child,{@code userId=null})既无 birthday
+     * 又无 generation 时,切换返回的 {@code effectiveRole} 必须仍归为孩子上下文({@code child}),
+     * 以保证 SC-P-73「选孩子 → 任务/报告/方案按孩子上下文隔离」。
+     *
+     * <p><b>当前实现</b>:{@code computeEffectiveRole} 无 birthday、无 generation 时默认返回
+     * {@code "parent"}(FamilyMemberService.java:1392)——把 managed child 误判为家长上下文,
+     * 前端据此把当前孩子态置为家长,孩子上下文隔离失效。<b>预期失败(红)</b>;GREEN 阶段实现
+     * 「userId=null 的不可登录成员 = 孩子上下文」的默认分类后转绿。</p>
+     */
+    @Test
+    @DisplayName("RED-正常流-4:managed child 无生日无 generation,切换仍应归为孩子上下文(child)")
+    void service_managedChild无生日无generation_仍应归为孩子上下文() {
+        stubParent(PARENT_USER_ID);
+        // userId=null 的不可登录孩子,未填 birthday / generation(多孩子家庭常见数据边界)
+        FamilyMember childB = managedChild(CHILD_B_MEMBER_ID, null, null);
+        when(familyMemberMapper.selectById(CHILD_B_MEMBER_ID)).thenReturn(childB);
+
+        SwitchMemberVO vo = familyMemberService.switchToMember(PARENT_USER_ID, CHILD_B_MEMBER_ID);
+
+        assertNotNull(vo, "切换应成功返回孩子上下文VO");
+        assertEquals("child", vo.getEffectiveRole(),
+                "[family.childContext.switch] managed child(userId=null,无 birthday 无 generation)"
+                        + "切换后 effectiveRole 应为 child(孩子上下文),实际=" + vo.getEffectiveRole()
+                        + " —— SC-P-73 当前孩子态隔离契约未落地:computeEffectiveRole 无年龄数据时默认 parent,"
+                        + "未实现孩子上下文默认分类");
+    }
+
+    // ====================================================================
+    // Service 异常流(TC-P-73-E:非本家庭不可选;切换保持各孩子上下文隔离不串)
+    // ====================================================================
+
+    @Test
+    @DisplayName("异常流-1:非本家庭 memberId → AccessDenied(不泄露他人家庭信息)")
+    void service_非本家庭memberId_拒绝() {
+        stubParent(PARENT_USER_ID);
+        // 跨家庭:其他家庭的成员
+        FamilyMember otherFamilyChild = managedChild(OTHER_FAMILY_MEMBER_ID, ageYearsAgo(8), null);
+        otherFamilyChild.setFamilyId(888L);
+        when(familyMemberMapper.selectById(OTHER_FAMILY_MEMBER_ID)).thenReturn(otherFamilyChild);
+
+        AccessDeniedException ex = assertThrows(AccessDeniedException.class,
+                () -> familyMemberService.switchToMember(PARENT_USER_ID, OTHER_FAMILY_MEMBER_ID));
+        assertEquals("成员不存在或不属于您的家庭", ex.getMessage());
+    }
+
+    @Test
+    @DisplayName("异常流-2:切换到自己 → IllegalArgumentException「不能切换到自己」")
+    void service_切换到自己_拒绝() {
+        stubParent(PARENT_USER_ID);
+        // 家庭主账号成员(userId = 本人),走 family_members 段自切判定
+        FamilyMember selfMember = managedChild(CHILD_B_MEMBER_ID, ageYearsAgo(35), null);
+        selfMember.setUserId(PARENT_USER_ID);
+        when(familyMemberMapper.selectById(CHILD_B_MEMBER_ID)).thenReturn(selfMember);
+
+        IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
+                () -> familyMemberService.switchToMember(PARENT_USER_ID, CHILD_B_MEMBER_ID));
+        assertEquals("不能切换到自己", ex.getMessage());
+    }
+
+    @Test
+    @DisplayName("异常流-3:目标为可登录成员(有 openid)→ 拒绝「不能切换为TA的身份」")
+    void service_目标是可登录成员_拒绝() {
+        stubParent(PARENT_USER_ID);
+        // 可登录成员:userId 关联 User 有 openid
+        FamilyMember loginMember = managedChild(CHILD_B_MEMBER_ID, ageYearsAgo(12), null);
+        loginMember.setUserId(LOGIN_MEMBER_USER_ID);
+        when(familyMemberMapper.selectById(CHILD_B_MEMBER_ID)).thenReturn(loginMember);
+        User memberUser = new User();
+        memberUser.setId(LOGIN_MEMBER_USER_ID);
+        memberUser.setOpenid("wx_openid_" + LOGIN_MEMBER_USER_ID);
+        when(userMapper.selectById(LOGIN_MEMBER_USER_ID)).thenReturn(memberUser);
+
+        IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
+                () -> familyMemberService.switchToMember(PARENT_USER_ID, CHILD_B_MEMBER_ID));
+        assertEquals("该成员可通过微信登录,不能切换为TA的身份", ex.getMessage());
+    }
+
+    @Test
+    @DisplayName("异常流-4:用户未加入家庭 → IllegalArgumentException「用户未加入家庭」")
+    void service_用户未加入家庭_拒绝() {
+        User noFamily = new User();
+        noFamily.setId(PARENT_USER_ID);
+        noFamily.setFamilyId(null);
+        when(userMapper.selectById(PARENT_USER_ID)).thenReturn(noFamily);
+
+        IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
+                () -> familyMemberService.switchToMember(PARENT_USER_ID, CHILD_B_MEMBER_ID));
+        assertEquals("用户未加入家庭", ex.getMessage());
+    }
+
+    // ====================================================================
+    // Service 权限流(TC-P-73-P:双角色铁律——孩子端不能切回家长)
+    // ====================================================================
+
+    @Test
+    @DisplayName("权限流:直接登录孩子端(role=child)切换到家长 effectiveRole → AccessDenied")
+    void service_孩子端切换到家长视角_拒绝() {
+        // 操作者 = 直接登录的孩子(role=child,有 familyId)
+        User childOperator = new User();
+        childOperator.setId(PARENT_USER_ID);
+        childOperator.setFamilyId(FAMILY_ID);
+        childOperator.setRole("child");
+        when(userMapper.selectById(PARENT_USER_ID)).thenReturn(childOperator);
+        // 目标成员 effectiveRole=parent(成年生日),触发「孩子端不能切回家长」铁律
+        FamilyMember adultMember = managedChild(CHILD_B_MEMBER_ID, ageYearsAgo(30), null);
+        when(familyMemberMapper.selectById(CHILD_B_MEMBER_ID)).thenReturn(adultMember);
+
+        AccessDeniedException ex = assertThrows(AccessDeniedException.class,
+                () -> familyMemberService.switchToMember(PARENT_USER_ID, CHILD_B_MEMBER_ID));
+        assertEquals("家庭成员账号不能切换到本人视角", ex.getMessage());
+    }
+
+    // ====================================================================
+    // 辅助构造
+    // ====================================================================
+
+    /** 构造家长 User(role=parent,已加入 FAMILY_ID 家庭) */
+    private void stubParent(Long userId) {
+        User parent = new User();
+        parent.setId(userId);
+        parent.setFamilyId(FAMILY_ID);
+        parent.setRole("parent");
+        when(userMapper.selectById(userId)).thenReturn(parent);
+    }
+
+    /** 构造不可登录孩子成员(managed child,userId=null,归属 FAMILY_ID) */
+    private FamilyMember managedChild(Long memberId, Date birthday, String nickname) {
+        FamilyMember fm = new FamilyMember();
+        fm.setId(memberId);
+        fm.setFamilyId(FAMILY_ID);
+        fm.setUserId(null);
+        fm.setBirthday(birthday);
+        fm.setNickname(nickname);
+        return fm;
+    }
+
+    /** 构造孩子上下文 SwitchMemberVO(契约响应形态) */
+    private SwitchMemberVO childContextVo(Long memberId, String effectiveRole) {
+        SwitchMemberVO vo = new SwitchMemberVO();
+        vo.setMemberId(memberId);
+        vo.setSource("family_member");
+        vo.setEffectiveRole(effectiveRole);
+        vo.setNickname("小宝");
+        vo.setIsSwitchable(true);
+        return vo;
+    }
+
+    private Map<String, Object> body(Long memberId) {
+        Map<String, Object> b = new HashMap<>();
+        b.put("memberId", memberId);
+        return b;
+    }
+
+    /** 距今 N 年的生日 */
+    private Date ageYearsAgo(int years) {
+        Calendar c = Calendar.getInstance();
+        c.add(Calendar.YEAR, -years);
+        return c.getTime();
+    }
+
+    private static void setField(Object target, String name, Object value) throws Exception {
+        Field f = target.getClass().getDeclaredField(name);
+        f.setAccessible(true);
+        f.set(target, value);
+    }
+}

+ 302 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/GrowthLeaderboardViewContractTest.java

@@ -0,0 +1,302 @@
+package com.etotem.cfc.unit;
+
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.controller.GameRecordController;
+import com.etotem.cfc.controller.stats.StatsController;
+import com.etotem.cfc.entity.FamilyMember;
+import com.etotem.cfc.mapper.FamilyMemberMapper;
+import com.etotem.cfc.mapper.GameRecordMapper;
+import com.etotem.cfc.mapper.MemberBadgeMapper;
+import com.etotem.cfc.service.BadgeService;
+import com.etotem.cfc.service.GameRecordService;
+import org.apache.ibatis.annotations.Select;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.MockitoAnnotations;
+import org.springframework.data.redis.core.RedisTemplate;
+import org.springframework.web.bind.annotation.RequestAttribute;
+
+import java.lang.annotation.Annotation;
+import java.lang.reflect.Method;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyInt;
+import static org.mockito.ArgumentMatchers.isNull;
+import static org.mockito.Mockito.when;
+
+/**
+ * 契约级单测:能力键 {@code growth.leaderboard.view}(<b>TDD-RED / 契约登记批次</b>)。
+ *
+ * <p><b>契约锚点</b></p>
+ * <ul>
+ *   <li>需求:{@code tests/user-scenarios/应用场景总览.md} SC-P-86(成长打卡榜/家庭排行:
+ *       看榜 → 排名/进度;<b>边界:数据仅本家庭可见;排名实时性</b>);</li>
+ *   <li>用例:{@code tests/test-cases/parent.md} TC-P-86(正常流:看榜→排名/进度)、
+ *       TC-P-86-E(异常流:看他人家庭排行榜不可见 / 排名实时性滞后)、
+ *       TC-P-86-P(权限流:非归属家庭数据统一拦截);</li>
+ *   <li>设计:{@code docs/superpowers/api/API_REFERENCE.md} §4.61.3
+ *       {@code POST /api/game/leaderboard}(游戏排行榜)、§4.61.4
+ *       {@code POST /api/badges/ranking/family}(家庭勋章排行)、§4.60.2
+ *       {@code POST /api/stats/points/ranking}(积分排行);</li>
+ *   <li>编排登记:{@code docs/tdd/orchestration/sc-key-map.md} SC-P-86 →
+ *       growth.leaderboard.view → S-cfc-302。</li>
+ * </ul>
+ *
+ * <p><b>测试范围</b>:三个排行端点的<b>家庭隔离</b>与<b>进度字段</b>契约。
+ * 仅用 Mockito + 反射(无 Spring / 无 DB / 无 Redis / 无真实外部服务),断言不依赖真实数据源。
+ * 游戏排行的 Redis 路径用 {@code opsForZSet()} 未 stub(返回 null → NPE 被 try-catch 吞掉)
+ * 强制走 DB 回退分支,从而以 {@code gameRecordMapper} mock 精确驱动。</p>
+ *
+ * <p><b>基线状态(实测,TDD-RED 阶段实现未落地)</b>:</p>
+ * <ul>
+ *   <li><b>游戏排行榜无家庭隔离</b>:{@code GameRecordService.getLeaderboard(String, Integer)}
+ *       无 {@code familyId} 参数;{@code GameRecordMapper.selectLeaderboard} SQL 仅按
+ *       {@code game_code} 过滤(无家庭约束);{@code GameRecordController} 未消费
+ *       {@code @RequestAttribute familyId};Redis key {@code game:leaderboard:{gameCode}}
+ *       全局共享不区分家庭 —— 违反 SC-P-86「数据仅本家庭可见」;</li>
+ *   <li><b>排行项无进度字段</b>:三个排行端点返回项均只含
+ *       {@code rank/memberId/childName/points}(或 {@code child_id/total}),
+ *       缺 SC-P-86「看榜 → 排名/进度」中的<b>进度</b>维度。</li>
+ * </ul>
+ *
+ * <p><b>RED 预期</b>:上述缺口在 src/main 实现补齐前应失败(红);
+ * GREEN 阶段按契约补齐(游戏排行榜家庭隔离 + 排行项进度字段)后自动转绿。
+ * 若实测意外全绿,交编排侧核实能力键状态(转测试登记),不私改 src/main 实现。</p>
+ */
+class GrowthLeaderboardViewContractTest {
+
+    /** 测试家庭:family_members.family_id(会话家庭维度) */
+    private static final Long FAMILY_ID = 9L;
+
+    // ---------- 游戏排行榜(/api/game/leaderboard) ----------
+    @Mock
+    private GameRecordMapper gameRecordMapper;
+
+    /** 未 stub:opsForZSet() 返回 null → try-catch 吞掉 NPE → 强制走 DB 回退分支 */
+    @Mock
+    private RedisTemplate<String, Object> redisTemplate;
+
+    @InjectMocks
+    private GameRecordService gameRecordService;
+
+    // ---------- 积分排行(/api/stats/points/ranking) ----------
+    @Mock
+    private FamilyMemberMapper familyMemberMapper;
+
+    @InjectMocks
+    private StatsController statsController;
+
+    // ---------- 家庭勋章排行(/api/badges/ranking/family) ----------
+    @Mock
+    private MemberBadgeMapper memberBadgeMapper;
+
+    @InjectMocks
+    private BadgeService badgeService;
+
+    @BeforeEach
+    void setUp() {
+        MockitoAnnotations.openMocks(this);
+    }
+
+    // ================================================================
+    // 正常流:游戏排行榜家庭隔离(SC-P-86「数据仅本家庭可见」)
+    // ================================================================
+
+    @Test
+    @DisplayName("正常流-1:GameRecordService.getLeaderboard 应接受 familyId 参数(家庭隔离)")
+    void 游戏排行_service应接受familyId参数() {
+        Method m;
+        try {
+            m = GameRecordService.class.getDeclaredMethod("getLeaderboard", String.class, Integer.class);
+        } catch (NoSuchMethodException e) {
+            throw new AssertionError(
+                    "[growth.leaderboard.view] GameRecordService.getLeaderboard(String, Integer) 未按契约签名存在。", e);
+        }
+        boolean hasFamilyId = false;
+        for (Class<?> p : m.getParameterTypes()) {
+            if (p == Long.class || p == long.class) {
+                hasFamilyId = true;
+                break;
+            }
+        }
+        assertTrue(hasFamilyId,
+                "[growth.leaderboard.view] GameRecordService.getLeaderboard 缺 familyId 参数:游戏排行榜"
+                        + "按全局返回(Redis key game:leaderboard:{gameCode} 不区分家庭 + SQL 无家庭过滤),"
+                        + "违反 SC-P-86『数据仅本家庭可见』。GREEN 应新增 familyId 维度(会话家庭)。");
+    }
+
+    @Test
+    @DisplayName("正常流-2:GameRecordMapper.selectLeaderboard 的 SQL 应含 family_id 过滤")
+    void 游戏排行_mapperSQL应含family_id过滤() throws Exception {
+        Method m = GameRecordMapper.class.getDeclaredMethod("selectLeaderboard", String.class, int.class);
+        Select select = m.getAnnotation(Select.class);
+        assertNotNull(select,
+                "[growth.leaderboard.view] GameRecordMapper.selectLeaderboard 应以 @Select 声明(现状保留)。");
+        String sql = String.join(" ", select.value());
+        assertTrue(sql.contains("family_id"),
+                "[growth.leaderboard.view] selectLeaderboard SQL 未按家庭过滤(应加 fm.family_id = #{familyId}"
+                        + " 之类约束),返回跨家庭排行榜,违反 SC-P-86『数据仅本家庭可见』。实际 SQL: " + sql);
+    }
+
+    @Test
+    @DisplayName("正常流-3:GameRecordController.getLeaderboard 应消费 @RequestAttribute(\"familyId\")")
+    void 游戏排行_controller应读取会话familyId() throws Exception {
+        Method m = GameRecordController.class.getDeclaredMethod("getLeaderboard", Map.class);
+        boolean hasFamilyAttr = false;
+        for (Annotation[] anns : m.getParameterAnnotations()) {
+            for (Annotation a : anns) {
+                if (a instanceof RequestAttribute && "familyId".equals(((RequestAttribute) a).value())) {
+                    hasFamilyAttr = true;
+                    break;
+                }
+            }
+        }
+        assertTrue(hasFamilyAttr,
+                "[growth.leaderboard.view] GameRecordController.getLeaderboard 未消费 @RequestAttribute(\"familyId\"):"
+                        + "排行无法按会话家庭过滤,违反 SC-P-86『数据仅本家庭可见』"
+                        + "(badges/points 排行已按会话 familyId 隔离,game 排行需对齐)。");
+    }
+
+    // ================================================================
+    // 正常流:排行项应含进度字段(SC-P-86「看榜 → 排名/进度」)
+    // ================================================================
+
+    @Test
+    @DisplayName("正常流-4:游戏排行榜项应含进度字段(progress/totalMembers)")
+    void 游戏排行_项应含进度字段() {
+        Map<String, Object> row = new HashMap<>();
+        row.put("memberId", 1L);
+        row.put("score", 100);
+        row.put("rank", 1);
+        row.put("child_name", "小明");
+        List<Map<String, Object>> rows = new ArrayList<>();
+        rows.add(row);
+        when(gameRecordMapper.selectLeaderboard(isNull(), anyInt())).thenReturn(rows);
+
+        List<Map<String, Object>> board = gameRecordService.getLeaderboard(null, 10);
+
+        assertNotNull(board);
+        assertEquals(1, board.size());
+        assertCarriesProgress(board.get(0), "游戏排行榜");
+    }
+
+    @Test
+    @DisplayName("正常流-5:积分排行项应含进度字段(progress/totalMembers)")
+    void 积分排行_项应含进度字段() {
+        List<FamilyMember> members = new ArrayList<>();
+        members.add(familyMember(1L, "小明", 120));
+        members.add(familyMember(2L, "小红", 80));
+        when(familyMemberMapper.selectList(any())).thenReturn(members);
+
+        Result<List<Map<String, Object>>> res = statsController.pointsRanking(new HashMap<>(), FAMILY_ID);
+
+        List<Map<String, Object>> data = res.getData();
+        assertNotNull(data);
+        assertEquals(2, data.size());
+        for (Map<String, Object> item : data) {
+            assertCarriesProgress(item, "积分排行");
+        }
+    }
+
+    @Test
+    @DisplayName("正常流-6:家庭勋章排行项应含进度字段(progress/totalMembers)")
+    void 家庭勋章排行_项应含进度字段() {
+        List<Map<String, Object>> rows = new ArrayList<>();
+        rows.add(badgeRankRow(1L, 5L));
+        rows.add(badgeRankRow(2L, 3L));
+        when(memberBadgeMapper.selectFamilyRanking(FAMILY_ID)).thenReturn(rows);
+
+        List<Map<String, Object>> data = badgeService.getFamilyRanking(FAMILY_ID);
+
+        assertNotNull(data);
+        assertEquals(2, data.size());
+        for (Map<String, Object> item : data) {
+            assertCarriesProgress(item, "家庭勋章排行");
+        }
+    }
+
+    // ================================================================
+    // 异常流:跨家庭数据不得泄露(TC-P-86-E「看他人家庭排行榜不可见」)
+    // ================================================================
+
+    @Test
+    @DisplayName("异常流-1:跨家庭数据行注入后应被过滤到本家庭(不得原样返回)")
+    void 游戏排行_跨家庭数据行应被过滤() {
+        Map<String, Object> own = new HashMap<>();
+        own.put("memberId", 1L);
+        own.put("familyId", FAMILY_ID);
+        own.put("score", 90);
+        Map<String, Object> other = new HashMap<>();
+        other.put("memberId", 2L);
+        other.put("familyId", 77L);
+        other.put("score", 95);
+        List<Map<String, Object>> rows = new ArrayList<>();
+        rows.add(own);
+        rows.add(other);
+        when(gameRecordMapper.selectLeaderboard(isNull(), anyInt())).thenReturn(rows);
+
+        List<Map<String, Object>> board = gameRecordService.getLeaderboard(null, 10);
+
+        assertNotNull(board);
+        assertEquals(2, board.size(),
+                "[growth.leaderboard.view] 上游返回的跨家庭行应被服务端过滤(契约 GREEN 实现后此处应仅剩本家庭行)");
+        for (Map<String, Object> item : board) {
+            assertEquals(FAMILY_ID, ((Number) item.get("familyId")).longValue(),
+                    "[growth.leaderboard.view] 本家庭排行榜不得返回其他家庭(familyId=77)成员数据,"
+                            + "违反 SC-P-86『数据仅本家庭可见』(TC-P-86-E)。");
+        }
+    }
+
+    // ================================================================
+    // 权限流(说明性):SC-P-86-P 越权拦截
+    // ================================================================
+
+    @Test
+    @DisplayName("权限流(说明性):家庭勋章/积分排行已按会话 familyId 隔离;游戏排行隔离缺失由红断言覆盖")
+    void 权限流_说明性() {
+        // SC-P-86-P:非归属家庭数据统一 403/401、不泄露他人数据。
+        // 现状核实:/api/badges/ranking/family 与 /api/stats/points/ranking 的 Controller
+        // 均已 @RequestAttribute("familyId") 且未入家庭返回 noFamily(越权=无家庭)已拦截;
+        // /api/game/leaderboard 的家庭隔离缺失由正常流-1/2/3、异常流-1 红断言覆盖。
+        assertTrue(true,
+                "权限流不适用单独红断言:家庭隔离契约已由正常/异常流断言覆盖;"
+                        + "badges/points 排行会话 familyId 拦截已实现。");
+    }
+
+    // ==================== 辅助构造 ====================
+
+    /** 契约断言:排行项应携带进度信息(字段名宽松:progress / totalMembers / completionRate) */
+    private void assertCarriesProgress(Map<String, Object> item, String boardName) {
+        assertTrue(item.containsKey("progress") || item.containsKey("totalMembers")
+                        || item.containsKey("completionRate"),
+                "[growth.leaderboard.view] " + boardName + " 项缺进度维度:SC-P-86 流程为「看榜 → 排名/进度」,"
+                        + "排行项应携带进度信息(如 排名/总成员数、完成率)。实际 keys=" + item.keySet());
+    }
+
+    private FamilyMember familyMember(Long id, String nickname, Integer totalPoints) {
+        FamilyMember m = new FamilyMember();
+        m.setId(id);
+        m.setFamilyId(FAMILY_ID);
+        m.setNickname(nickname);
+        m.setTotalPoints(totalPoints);
+        return m;
+    }
+
+    private Map<String, Object> badgeRankRow(Long memberId, Long total) {
+        Map<String, Object> row = new HashMap<>();
+        row.put("child_id", memberId);
+        row.put("total", total);
+        return row;
+    }
+}

+ 313 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/NotificationCenterViewContractTest.java

@@ -0,0 +1,313 @@
+package com.etotem.cfc.unit;
+
+import com.baomidou.mybatisplus.core.conditions.Wrapper;
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.controller.UserNotificationController;
+import com.etotem.cfc.entity.UserNotification;
+import com.etotem.cfc.mapper.UserNotificationMapper;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+import org.springframework.web.bind.annotation.RequestAttribute;
+import org.springframework.web.bind.annotation.RequestBody;
+
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.Arrays;
+import java.util.Date;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * 契约级单测:消息中心/通知查看(能力键 {@code notification.center.view},SC-P-78)。
+ *
+ * <p><b>契约来源</b>(需求 → 设计 → 用例):</p>
+ * <ul>
+ *   <li>需求:{@code tests/user-scenarios/应用场景总览.md} SC-P-78 —— 打开消息中心 → 列表/已读;
+ *       边界:越权消息不可见;分页。模块:消息服务。</li>
+ *   <li>设计:{@code docs/superpowers/api/API_REFERENCE.md} §4.15 / §4.61.7 / §4.63.8 ——
+ *       {@code POST /api/notification/list}(通知列表,未读优先,倒序,{@code LIMIT 100})、
+ *       {@code POST /api/notification/read}(标记已读:{@code id} / {@code ids} / 空=全部已读)。</li>
+ *   <li>用例:{@code tests/test-cases/parent.md} TC-P-78 / TC-P-78-E / TC-P-78-P ——
+ *       正常流(列表/已读)、异常流(越权不可见 403、消息不存在 404、分页正常)、权限流(非归属数据 403/401)。</li>
+ * </ul>
+ *
+ * <p><b>实现现状(src/main 核实)</b>:{@code UserNotificationController}({@code /api/notification/list|read})
+ * 已在主链落地:{@code list} 按 {@code userId}(来自 JWT)过滤、未读优先倒序 {@code LIMIT 100};{@code read}
+ * 支持单条/批量/缺省全部,并对非本人通知不落已读。故「正常流/权限流」已实现(本测试作<b>回归钉</b>,GREEN)。</p>
+ *
+ * <p><b>本批次 RED 缺口</b>(断言契约所需行为缺失,GREEN 阶段实现使绿):</p>
+ * <ul>
+ *   <li><b>① 分页</b>(SC-P-78 边界「分页」、TC-P-78-E「分页正常」):当前 {@code list} 仅返回
+ *       {@code LIMIT 100} 的扁平数组,<b>无 {@code pageNum/pageSize} 入参、无分页结果</b>(无 {@code total/pageNum/pageSize})。</li>
+ *   <li><b>② 消息不存在 → 404</b>(TC-P-78-E「不存在 404」):当前 {@code read} 对不存在的 {@code id}
+ *       <b>静默返回 {@code success(true)}</b>,未返回 404。</li>
+ * </ul>
+ *
+ * <p><b>GREEN 升级指引</b>:实现者需 (a) 为 {@code /api/notification/list} 增加分页入参与分页结果
+ * ({@code pageNum/pageSize} → 返回含 {@code total/pageNum/pageSize} 的分页载体);(b) 为
+ * {@code /api/notification/read} 增加「消息不存在 → 404」({@code Result.notFound})。</p>
+ */
+class NotificationCenterViewContractTest extends AssessmentPlanContractTestBase {
+
+    static {
+        initTable(UserNotification.class);
+    }
+
+    // ==================================================================
+    // 正常流(已落地 · 回归钉 GREEN)
+    // ==================================================================
+
+    @Test
+    @DisplayName("SC-P-78 正常:通知列表 → 200 返回本人通知(未读优先倒序 LIMIT 100)")
+    void notificationList_正常_返回列表() throws Exception {
+        UserNotificationMapper mapper = mock(UserNotificationMapper.class);
+        UserNotificationController c = new UserNotificationController();
+        inject(c, "userNotificationMapper", mapper);
+
+        UserNotification unread = notif(1L, 10L, 0);
+        UserNotification read = notif(2L, 10L, 1);
+        when(mapper.selectList(any())).thenReturn(Arrays.asList(unread, read));
+
+        Result<List<UserNotification>> r = c.list(10L);
+        assertEquals(200, r.getCode());
+        assertEquals(2, r.getData().size());
+    }
+
+    @Test
+    @DisplayName("SC-P-78 正常:列表查询按 userId 过滤 + 未读优先(is_read ASC) + 倒序(created_at DESC) + LIMIT 100")
+    void notificationList_正常_未读优先倒序_LIMIT100() throws Exception {
+        UserNotificationMapper mapper = mock(UserNotificationMapper.class);
+        UserNotificationController c = new UserNotificationController();
+        inject(c, "userNotificationMapper", mapper);
+        when(mapper.selectList(any())).thenReturn(Arrays.asList());
+
+        c.list(10L);
+
+        @SuppressWarnings("unchecked")
+        ArgumentCaptor<Wrapper<UserNotification>> captor = ArgumentCaptor.forClass(Wrapper.class);
+        verify(mapper).selectList(captor.capture());
+        Wrapper<UserNotification> w = captor.getValue();
+
+        // 设计契约 §4.61.7:未读优先 + 倒序 + LIMIT 100
+        String seg = w.getSqlSegment().toLowerCase();
+        assertTrue(seg.contains("is_read"), "[notification.center.view] 列表应未读优先(is_read ASC)");
+        assertTrue(seg.contains("created_at"), "[notification.center.view] 列表应倒序(created_at DESC)");
+        String lastSql = lastSqlOf(w).toLowerCase();
+        assertTrue(lastSql.contains("limit 100"),
+                "[notification.center.view] 列表应 LIMIT 100(设计 §4.61.7),当前 lastSql=[" + lastSql + "]");
+    }
+
+    @Test
+    @DisplayName("SC-P-78 正常:单条标记已读(本人)→ 200 true,置已读并更新")
+    void notificationRead_正常_单条已读() throws Exception {
+        UserNotificationMapper mapper = mock(UserNotificationMapper.class);
+        UserNotificationController c = new UserNotificationController();
+        inject(c, "userNotificationMapper", mapper);
+
+        UserNotification n = notif(1L, 10L, 0);
+        when(mapper.selectById(1L)).thenReturn(n);
+
+        Map<String, Object> params = new HashMap<>();
+        params.put("id", 1L);
+        Result<Boolean> r = c.read(10L, params);
+        assertEquals(200, r.getCode());
+        assertEquals(1, n.getIsRead());
+        verify(mapper).updateById(n);
+    }
+
+    @Test
+    @DisplayName("SC-P-78 正常:批量 ids 标记已读(本人)→ 200 true")
+    void notificationRead_正常_批量ids已读() throws Exception {
+        UserNotificationMapper mapper = mock(UserNotificationMapper.class);
+        UserNotificationController c = new UserNotificationController();
+        inject(c, "userNotificationMapper", mapper);
+
+        UserNotification n1 = notif(1L, 10L, 0);
+        UserNotification n2 = notif(2L, 10L, 0);
+        when(mapper.selectById(1L)).thenReturn(n1);
+        when(mapper.selectById(2L)).thenReturn(n2);
+
+        Map<String, Object> params = new HashMap<>();
+        params.put("ids", Arrays.asList(1L, 2L));
+        Result<Boolean> r = c.read(10L, params);
+        assertEquals(200, r.getCode());
+        assertEquals(1, n1.getIsRead());
+        assertEquals(1, n2.getIsRead());
+        verify(mapper).updateById(n1);
+        verify(mapper).updateById(n2);
+    }
+
+    @Test
+    @DisplayName("SC-P-78 正常:缺省参数标记全部已读 → 200 true")
+    void notificationRead_正常_缺省全部已读() throws Exception {
+        UserNotificationMapper mapper = mock(UserNotificationMapper.class);
+        UserNotificationController c = new UserNotificationController();
+        inject(c, "userNotificationMapper", mapper);
+
+        UserNotification n1 = notif(1L, 10L, 0);
+        UserNotification n2 = notif(2L, 10L, 0);
+        when(mapper.selectList(any())).thenReturn(Arrays.asList(n1, n2));
+
+        Result<Boolean> r = c.read(10L, new HashMap<>());
+        assertEquals(200, r.getCode());
+        assertEquals(1, n1.getIsRead());
+        assertEquals(1, n2.getIsRead());
+        verify(mapper).updateById(n1);
+        verify(mapper).updateById(n2);
+    }
+
+    // ==================================================================
+    // 权限流(已落地 · 回归钉 GREEN)
+    // ==================================================================
+
+    @Test
+    @DisplayName("SC-P-78 权限:他人通知不可标记已读(越权不可见)→ 不改动且不更新")
+    void notificationRead_权限_他人通知不可见() throws Exception {
+        UserNotificationMapper mapper = mock(UserNotificationMapper.class);
+        UserNotificationController c = new UserNotificationController();
+        inject(c, "userNotificationMapper", mapper);
+
+        // 通知属于 999,当前用户是 10 → 越权,不得标记已读(与主链 SC-C-19 口径一致:200 但不改)
+        UserNotification other = notif(1L, 999L, 0);
+        when(mapper.selectById(1L)).thenReturn(other);
+
+        Map<String, Object> params = new HashMap<>();
+        params.put("id", 1L);
+        Result<Boolean> r = c.read(10L, params);
+        assertEquals(200, r.getCode());
+        assertEquals(0, other.getIsRead(), "非本人通知不得标记已读");
+        verify(mapper, never()).updateById(other);
+    }
+
+    @Test
+    @DisplayName("SC-P-78 权限:列表 userId 取自 JWT(@RequestAttribute),客户端不可注入 → 越权不可见")
+    void notificationList_权限_userId取自JWT() throws Exception {
+        boolean userIdFromJwt = false;
+        for (Method m : UserNotificationController.class.getDeclaredMethods()) {
+            if (!"list".equals(m.getName())) {
+                continue;
+            }
+            for (Parameter p : m.getParameters()) {
+                RequestAttribute ra = p.getAnnotation(RequestAttribute.class);
+                if (ra != null && "userId".equals(ra.value())) {
+                    userIdFromJwt = true;
+                }
+            }
+        }
+        assertTrue(userIdFromJwt,
+                "[notification.center.view] 通知列表的 userId 应来自 @RequestAttribute(\"userId\")(JWT),"
+                        + "客户端不可注入 → 越权消息不可见(SC-P-78 边界)。");
+    }
+
+    // ==================================================================
+    // 异常流(RED 缺口 ②:消息不存在 → 404)
+    // ==================================================================
+
+    @Test
+    @DisplayName("SC-P-78 异常:消息 id 不存在 → 404(TC-P-78-E「不存在 404」)")
+    void notificationRead_异常_消息不存在_应404() throws Exception {
+        UserNotificationMapper mapper = mock(UserNotificationMapper.class);
+        UserNotificationController c = new UserNotificationController();
+        inject(c, "userNotificationMapper", mapper);
+
+        when(mapper.selectById(999L)).thenReturn(null); // 不存在
+
+        Map<String, Object> params = new HashMap<>();
+        params.put("id", 999L);
+        Result<Boolean> r = c.read(10L, params);
+        assertEquals(404, r.getCode(),
+                "[notification.center.view] 消息 id 不存在应返回 404(TC-P-78-E),当前返回 code="
+                        + r.getCode() + "(静默 success,未实现 404)。");
+    }
+
+    // ==================================================================
+    // 边界流(RED 缺口 ①:分页)
+    // ==================================================================
+
+    @Test
+    @DisplayName("SC-P-78 边界:通知列表应支持分页(pageNum/pageSize 入参 + 分页结果)")
+    void notificationList_边界_应支持分页() {
+        boolean hasPageInput = false;
+        boolean hasPageOutput = false;
+        for (Method m : UserNotificationController.class.getDeclaredMethods()) {
+            if (!"list".equals(m.getName())) {
+                continue;
+            }
+            // 入参:分页参数(pageNum/pageSize)或请求体承载分页
+            if (m.getParameterCount() > 1) {
+                hasPageInput = true;
+            }
+            for (Parameter p : m.getParameters()) {
+                if (p.isAnnotationPresent(RequestBody.class)) {
+                    hasPageInput = true;
+                }
+                String pname = p.getName() == null ? "" : p.getName().toLowerCase();
+                if (pname.contains("page") || pname.contains("size")) {
+                    hasPageInput = true;
+                }
+            }
+            // 出参:分页结果(Page 或含 total/pageNum/pageSize 的分页载体)
+            String genericRet = m.getGenericReturnType().getTypeName().toLowerCase();
+            if (genericRet.contains("page")) {
+                hasPageOutput = true;
+            }
+        }
+        assertTrue(hasPageInput && hasPageOutput,
+                "[notification.center.view] 通知列表未支持分页(SC-P-78 边界「分页」/TC-P-78-E「分页正常」):"
+                        + "当前 list 仅返回 LIMIT 100 扁平数组,无 pageNum/pageSize 入参、无分页结果"
+                        + "(应返回含 total/pageNum/pageSize 的分页载体)。");
+    }
+
+    // ==================================================================
+    // helpers
+    // ==================================================================
+
+    private static UserNotification notif(Long id, Long userId, int isRead) {
+        UserNotification n = new UserNotification();
+        n.setId(id);
+        n.setUserId(userId);
+        n.setIsRead(isRead);
+        n.setCreatedAt(new Date());
+        return n;
+    }
+
+    /** 读取 MyBatis-Plus wrapper 的 lastSql(如 "LIMIT 100"),读取失败返回空串。 */
+    private static String lastSqlOf(Wrapper<?> w) {
+        try {
+            // 沿继承链找 AbstractWrapper 上的 lastSql 字段
+            Class<?> cls = w.getClass();
+            Field lastSqlField = null;
+            while (cls != null && lastSqlField == null) {
+                try {
+                    lastSqlField = cls.getDeclaredField("lastSql");
+                } catch (NoSuchFieldException e) {
+                    cls = cls.getSuperclass();
+                }
+            }
+            if (lastSqlField == null) {
+                return "";
+            }
+            lastSqlField.setAccessible(true);
+            Object shared = lastSqlField.get(w);
+            if (shared == null) {
+                return "";
+            }
+            Method getter = shared.getClass().getMethod("getStringValue");
+            Object v = getter.invoke(shared);
+            return v == null ? "" : v.toString();
+        } catch (Exception e) {
+            return "";
+        }
+    }
+}

+ 267 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/ShopCouponClaimContractTest.java

@@ -0,0 +1,267 @@
+package com.etotem.cfc.unit;
+
+import com.baomidou.mybatisplus.core.conditions.Wrapper;
+import com.etotem.cfc.entity.Coupon;
+import com.etotem.cfc.entity.FamilyCoupon;
+import com.etotem.cfc.entity.User;
+import com.etotem.cfc.mapper.CouponMapper;
+import com.etotem.cfc.mapper.FamilyCouponMapper;
+import com.etotem.cfc.mapper.UserMapper;
+import com.etotem.cfc.service.CouponService;
+import com.etotem.cfc.service.MembershipService;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+
+import java.lang.reflect.Field;
+import java.util.Date;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * 契约级单测:优惠券领取(能力键 {@code shop.coupon.claim},S-cfc-293)。
+ *
+ * <p>契约溯源:</p>
+ * <ul>
+ *   <li>需求:{@code tests/user-scenarios/应用场景总览.md} SC-P-75 优惠券领取(活动/分享)——
+ *       主流程:领券 → 入卡包;边界:库存为0 / 已领拦截;重复领幂等。业务域 K 营销/活动/优惠。</li>
+ *   <li>设计:{@code docs/superpowers/api/API_REFERENCE.md} §4.32 优惠券(家庭维度)
+ *       {@code POST /api/coupon/claim} 领取优惠券(发到家庭);与 available-templates 的
+ *       去重口径对齐(COUPON-C3:family_coupon 任意状态有记录即视为本家庭已领取)。</li>
+ *   <li>实现承载:{@code CouponController.claim} → {@link CouponService#claim(Long, Long)}
+ *       (领券发到当前用户家庭 {@code family_coupon},并同步 {@code coupon.used_count + 1})。</li>
+ * </ul>
+ *
+ * <p><b>实现现状(红转登记说明)</b>:执行本任务时检查 origin/cfclub,
+ * {@code CouponService.claim}(165 行起)与 {@code POST /api/coupon/claim} 端点
+ * 均已在主链落地,且 {@code CouponUseScP57ScP75ContractTest}(S-cfc-12)已覆盖部分
+ * 领取用例。故本测试实际为「契约测试登记」——运行结果 GREEN 而非预期 RED。
+ * 按任务约定在汇报中注明并交编排侧转测试登记,未改动 src/main 实现。</p>
+ *
+ * <p><b>覆盖流</b>(纯 Mockito,无 Spring 上下文 / 无 DB / 无外部服务):</p>
+ * <ul>
+ *   <li><b>正常流</b>:领取成功 →「领取成功」且券入本家庭卡包(family_coupon INSERT
+ *       familyId/couponId/Available),used_count +1;total_count 为空视为不限量可领;</li>
+ *   <li><b>边界/异常流</b>:库存为0(used_count &gt;= total_count)→「优惠券已领完」(不发券);
+ *       券不存在 / 已停用 / 未开始 / 已过期拦截;</li>
+ *   <li><b>去重/幂等流</b>:同家庭同券已有记录(任意状态,COUPON-C3)→「已领取过该优惠券」,
+ *       不重复发券、不递增 used_count(重复领幂等);</li>
+ *   <li><b>前置流</b>:未加入家庭(或用户不存在)→「未加入家庭」。</li>
+ * </ul>
+ */
+class ShopCouponClaimContractTest {
+
+    private CouponService service;
+    private UserMapper userMapper;
+    private CouponMapper couponMapper;
+    private FamilyCouponMapper familyCouponMapper;
+    private MembershipService membershipService;
+
+    @BeforeEach
+    void setUp() throws Exception {
+        service = new CouponService();
+        userMapper = mock(UserMapper.class);
+        couponMapper = mock(CouponMapper.class);
+        familyCouponMapper = mock(FamilyCouponMapper.class);
+        membershipService = mock(MembershipService.class);
+
+        inject(service, "userMapper", userMapper);
+        inject(service, "couponMapper", couponMapper);
+        inject(service, "familyCouponMapper", familyCouponMapper);
+        inject(service, "membershipService", membershipService);
+    }
+
+    private static void inject(Object target, String field, Object value) throws Exception {
+        Field f = target.getClass().getDeclaredField(field);
+        f.setAccessible(true);
+        f.set(target, value);
+    }
+
+    /** 用户 1 属于家庭 5 */
+    private void stubUserFamily(Long familyId) {
+        User user = new User();
+        user.setId(1L);
+        user.setFamilyId(familyId);
+        when(userMapper.selectById(1L)).thenReturn(user);
+    }
+
+    /** 在有效期内、有库存(total=100/used=50)、ACTIVE 的券模板 */
+    private Coupon activeCoupon() {
+        Coupon c = new Coupon();
+        c.setId(100L);
+        c.setName("领券中心测试券");
+        c.setType("CASH");
+        c.setStatus("ACTIVE");
+        c.setApplicableTo("ALL");
+        c.setTotalCount(100);
+        c.setUsedCount(50);
+        c.setValidFrom(new Date(System.currentTimeMillis() - 86400000L * 7));  // 7 天前开始
+        c.setValidUntil(new Date(System.currentTimeMillis() + 86400000L * 7));  // 7 天后到期
+        return c;
+    }
+
+    /** 未领取(selectCount=0)且 insert 回填 id 的桩 */
+    private void stubNotClaimedYet() {
+        when(familyCouponMapper.selectCount(any(Wrapper.class))).thenReturn(0L);
+        when(familyCouponMapper.insert(any(FamilyCoupon.class))).thenAnswer(inv -> {
+            FamilyCoupon fc = inv.getArgument(0);
+            fc.setId(500L);
+            return 1;
+        });
+    }
+
+    // ==================== 正常流(领券 → 入卡包) ====================
+
+    @Test
+    @DisplayName("正常流-1:领取成功 → 券入本家庭卡包(family_coupon),used_count +1")
+    void 正常流_领取成功入卡包() {
+        stubUserFamily(5L);
+        when(couponMapper.selectById(100L)).thenReturn(activeCoupon());
+        stubNotClaimedYet();
+
+        String result = service.claim(1L, 100L);
+
+        assertEquals("领取成功", result);
+        // 入卡包:family_coupon INSERT 到当前用户家庭,状态 AVAILABLE
+        ArgumentCaptor<FamilyCoupon> fcCaptor = ArgumentCaptor.forClass(FamilyCoupon.class);
+        verify(familyCouponMapper).insert(fcCaptor.capture());
+        assertEquals(Long.valueOf(5L), fcCaptor.getValue().getFamilyId(), "券应发到当前用户家庭(入卡包)");
+        assertEquals(Long.valueOf(100L), fcCaptor.getValue().getCouponId(), "券实例应关联领取的券模板");
+        assertEquals("AVAILABLE", fcCaptor.getValue().getStatus(), "新领券实例状态应为可用");
+        // 库存 used_count 同步 +1
+        ArgumentCaptor<Coupon> couponCaptor = ArgumentCaptor.forClass(Coupon.class);
+        verify(couponMapper).updateById(couponCaptor.capture());
+        assertEquals(Integer.valueOf(51), couponCaptor.getValue().getUsedCount(), "领取后 used_count 应 50 → 51");
+    }
+
+    @Test
+    @DisplayName("正常流-2:total_count 为空视为不限量模板,可正常领取")
+    void 正常流_不限量模板可领取() {
+        stubUserFamily(5L);
+        Coupon coupon = activeCoupon();
+        coupon.setTotalCount(null); // 不限量(与 available-templates 口径一致)
+        when(couponMapper.selectById(100L)).thenReturn(coupon);
+        stubNotClaimedYet();
+
+        String result = service.claim(1L, 100L);
+
+        assertEquals("领取成功", result, "total_count 为空的模板不校验库存,可领取");
+    }
+
+    // ==================== 边界流(库存为0 / 模板状态 / 有效期) ====================
+
+    @Test
+    @DisplayName("边界流-1:库存为0(used_count >= total_count)→「优惠券已领完」且不发券")
+    void 边界流_库存为0已领完() {
+        stubUserFamily(5L);
+        Coupon coupon = activeCoupon();
+        coupon.setUsedCount(100); // == totalCount,库存为0
+        when(couponMapper.selectById(100L)).thenReturn(coupon);
+
+        String result = service.claim(1L, 100L);
+
+        assertEquals("优惠券已领完", result);
+        verify(familyCouponMapper, never()).insert(any(FamilyCoupon.class));
+        verify(couponMapper, never()).updateById(any(Coupon.class));
+    }
+
+    @Test
+    @DisplayName("边界流-2:券模板不存在 →「优惠券不存在」")
+    void 边界流_券不存在() {
+        stubUserFamily(5L);
+        when(couponMapper.selectById(999L)).thenReturn(null);
+
+        assertEquals("优惠券不存在", service.claim(1L, 999L));
+    }
+
+    @Test
+    @DisplayName("边界流-3:券模板已停用(status 非 ACTIVE)→「优惠券已停用」")
+    void 边界流_券已停用() {
+        stubUserFamily(5L);
+        Coupon coupon = activeCoupon();
+        coupon.setStatus("DISABLED");
+        when(couponMapper.selectById(100L)).thenReturn(coupon);
+
+        assertEquals("优惠券已停用", service.claim(1L, 100L));
+        verify(familyCouponMapper, never()).insert(any(FamilyCoupon.class));
+    }
+
+    @Test
+    @DisplayName("边界流-4:未到开始时间 →「优惠券尚未开始」")
+    void 边界流_券未开始() {
+        stubUserFamily(5L);
+        Coupon coupon = activeCoupon();
+        coupon.setValidFrom(new Date(System.currentTimeMillis() + 86400000L)); // 明天开始
+        when(couponMapper.selectById(100L)).thenReturn(coupon);
+
+        assertEquals("优惠券尚未开始", service.claim(1L, 100L));
+        verify(familyCouponMapper, never()).insert(any(FamilyCoupon.class));
+    }
+
+    @Test
+    @DisplayName("边界流-5:已过有效期 →「优惠券已过期」")
+    void 边界流_券已过期() {
+        stubUserFamily(5L);
+        Coupon coupon = activeCoupon();
+        coupon.setValidUntil(new Date(System.currentTimeMillis() - 86400000L)); // 昨天到期
+        when(couponMapper.selectById(100L)).thenReturn(coupon);
+
+        assertEquals("优惠券已过期", service.claim(1L, 100L));
+        verify(familyCouponMapper, never()).insert(any(FamilyCoupon.class));
+    }
+
+    // ==================== 去重/幂等流(已领拦截;重复领幂等) ====================
+
+    @Test
+    @DisplayName("去重流-1:同家庭同券已有记录 →「已领取过该优惠券」,不重复发券、不递增库存")
+    void 去重流_已领取过拦截() {
+        stubUserFamily(5L);
+        when(couponMapper.selectById(100L)).thenReturn(activeCoupon());
+        when(familyCouponMapper.selectCount(any(Wrapper.class))).thenReturn(1L);
+
+        String result = service.claim(1L, 100L);
+
+        assertEquals("已领取过该优惠券", result);
+        verify(familyCouponMapper, never()).insert(any(FamilyCoupon.class));
+        verify(couponMapper, never()).updateById(any(Coupon.class));
+    }
+
+    @Test
+    @DisplayName("去重流-2:已领口径与券实例状态无关(COUPON-C3:任意状态有记录即排除)")
+    void 去重流_已领与实例状态无关() {
+        stubUserFamily(5L);
+        when(couponMapper.selectById(100L)).thenReturn(activeCoupon());
+        // 即使 family_coupon 行是 USED/EXPIRED 等已消费状态,本家庭也算「已领取」,不可重复领
+        when(familyCouponMapper.selectCount(any(Wrapper.class))).thenReturn(1L);
+
+        assertEquals("已领取过该优惠券", service.claim(1L, 100L),
+                "COUPON-C3:family_coupon 任意状态有记录即排除,重复领幂等");
+    }
+
+    // ==================== 前置流(资格) ====================
+
+    @Test
+    @DisplayName("前置流-1:未加入家庭(family_id 为空)→「未加入家庭」")
+    void 前置流_未加入家庭不可领取() {
+        stubUserFamily(null);
+        when(couponMapper.selectById(100L)).thenReturn(activeCoupon());
+
+        assertEquals("未加入家庭", service.claim(1L, 100L));
+        verify(familyCouponMapper, never()).insert(any(FamilyCoupon.class));
+    }
+
+    @Test
+    @DisplayName("前置流-2:用户不存在 →「未加入家庭」")
+    void 前置流_用户不存在不可领取() {
+        when(userMapper.selectById(1L)).thenReturn(null);
+
+        assertEquals("未加入家庭", service.claim(1L, 100L));
+        verify(familyCouponMapper, never()).insert(any(FamilyCoupon.class));
+    }
+}

+ 1 - 1
cfc-web/.last_build_commit

@@ -1 +1 @@
-d6dac931a577c1e90d9f2fdf454c28c4197ac0bf
+d571b5d92b43f9aed3075e260e9e8cdd8af16a4b

+ 2 - 2
cfc-web/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "cfc-web",
-  "version": "1.0.2465",
+  "version": "1.0.2468",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "cfc-web",
-      "version": "1.0.2465",
+      "version": "1.0.2468",
       "dependencies": {
         "@wangeditor/editor": "^5.1.23",
         "@wangeditor/editor-for-vue": "^1.0.2",

+ 1 - 1
cfc-web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cfc-web",
-  "version": "1.0.2466",
+  "version": "1.0.2469",
   "private": true,
   "scripts": {
     "dev": "vue-cli-service serve",

+ 80 - 0
cfc-web/public/CHANGELOG-v1.0.md

@@ -4,6 +4,86 @@
 
 ---
 
+## v1.0.2469 (2026-11-13)
+
+### 新功能
+- 舌诊/情绪模型版本管理实现(SC-A-21)
+- S-cfc-228 teacher.plan.review 使绿 - 方案内容安全复核(SC-T-28)落地
+
+### 其他
+- - MindModelManageService:listAll/online/offline/isEnabled,offline 三参含 fallbackVersion
+-   未指定回退方案拒绝下线(Result 400),非法/未知版本返回 400
+- - MindModelManageController(/api/admin/mind-model: list/online/offline,统一 @PostMapping)
+- - schema.sql 落地 mind_model 建表 + DatabaseInitializer 迁移470(幂等)
+- - API_REFERENCE §4.13 同步全新端点
+- 使 MindModelManageContractTest 11/11 转绿(RED 10 失败 → GREEN 0 失败)。
+- 
+- - HealthPlanServiceImpl 注入 WechatServiceInterface 并在 approveAndPublish 发布前做内容安全复核
+-   (内置敏感词/违规医疗主张检测 + wechatService.checkText 叠加,命中即拦截、不落库、状态保持待审核)
+- - 新增 ContentFilterController POST /api/content/plan-safety 方案内容安全复核端点
+- - 新增 PlanContentSafetyUtil 敏感词检测工具(fail-closed)
+- PlanContentSafetyReviewContractTest 9/9 转绿;关联 PlanReviewTeacherContractTest 19/19、
+- HealthPlanReviewGuardTest 10/10、PlanLifecycleParentContractTest 38/38、GuidePlanReviewControllerAuthTest 6/6 均绿。
+- 
+- 预期红(RED)契约测试,未改 src/main 实现。
+- 契约锚点(TC-P-90 / -E / -P + ED-4 + API_REFERENCE DimensionDailyLimit 模块,
+- 与 S-cfc-304 ruleEngine.apply 同链:ruleEngine 写入前经 daily limit 守卫校验):
+- - RED 守卫入口:EnergyService 应提供 public 每日上限守卫方法(当前 isDailyLimitExceeded 为 private)
+- - RED 守卫钩子:EnergyRuleEngine 应有 daily-limit 守卫钩子(ruleEngine 写入前校验)
+- - RED 配置驱动:EnergyService 应注入 DimensionDailyLimitMapper 读取 energy_daily_limit(当前硬编码 DAILY_LIMIT_MAP)
+- - RED 多来源共享:awardEnergyByCode(challenge 来源)绕过日上限(TC-P-90-E-1)
+- - RED 上限 0/负安全:配置 dailyLimit=0 应按 0 处理不发不崩溃(TC-P-90-E-4)
+- 实测:Tests run 8, Failures 5(红)/ 通过 3(2 正常流锚点 + 1 权限流标注不适用)。
+- 
+- 基线缺口(src/main 现状):
+- - /api/game/leaderboard 无家庭隔离(service 缺 familyId 参数、
+-   mapper SQL 无 family_id 过滤、controller 未消费 @RequestAttribute familyId);
+- - 游戏/积分/家庭勋章三个排行端点返回项均缺进度字段。
+- 7 条契约断言预期红(Tests: 8, Failures: 7),权限流说明性用例通过。
+- 
+
+### 测试
+- S-cfc-296 notification.center.view TDD-RED 契约单测(SC-P-78 消息中心/通知查看:列表/已读/越权回归钉 + 分页/消息不存在404 缺口)
+- S-cfc-306 energy.dailyLimit.guard TDD-RED 契约单测
+- family.childContext.switch RED 契约单测 12 例(1红11绿锁定)
+- 新增 admin.familyRelation.manage 契约级单测(SC-A-04 关系类型 CRUD,TDD-RED,8 断言预期红)
+- 新增 growth.leaderboard.view 契约级 RED 单测(S-cfc-302)
+
+
+## v1.0.2468 (2026-11-13)
+
+### 测试
+- RED 契约单测 data.export.gdpr(SC-P-72 个人/家庭数据导出 GDPR,申请->加密包->下载/脱敏/频次/越权)
+- 契约级单测 ShopCouponClaimContractTest(S-cfc-293,SC-P-75 优惠券领取)
+- S-cfc-301 auth.session.mutex 契约级 RED 单测(SC-P-85 多端登录/会话互斥)
+- RED 契约测试——活动打卡/助力进度累计+幂等+反刷量
+
+### 其他
+- 
+- 刷量/机器行为拦截;CF 值预估(SC-X-22)。
+- 契约宿主 ActivityCheckinBoostService 尚未实现,14 用例 13 红 1 标记不适用。
+- 
+
+
+## v1.0.2467 (2026-11-13)
+
+### 测试
+- RED 契约测试 assessment.result.view (S-cfc-278)
+
+### 其他
+- (查看测评结果:八类报告展示、结果未录入不展示、量纲标注)与
+- API_REFERENCE.md §4.10(POST /api/assessment/latest-result、/history)。
+- 纯 Mockito + 反射,无 Spring/DB/外部服务,沿用同批 RED 测试风格
+- (TeamProfitHookContractTest / FamilyJoinValidationRulesContractTest)。
+- - 边界一(对照,已落地):结果未录入返回 success(null) 不展示
+- - 边界二(红):AssessmentResultDTO 缺量纲标注(0-100 范围)字段
+- - 边界二(红):八类报告维度缺中文标签字段
+- - 边界三(红):分数超出 0-100 量纲未拒显(直接透传 code=200)
+- - 结构锚点:AssessmentResultController.getLatestResult 存在
+- 红测结果:Tests run 6, Failures 4, Errors 0(4 项契约缺口断言按预期失败)
+- 
+
+
 ## v1.0.2466 (2026-11-13)
 
 ### 文档

+ 81 - 1
cfc-web/public/CHANGELOG.md

@@ -1,6 +1,6 @@
 # 更新日志
 
-> 当前版本: v1.0.2466
+> 当前版本: v1.0.2469
 
 ## 历史版本
 
@@ -8,6 +8,86 @@
 
 ---
 
+## v1.0.2469 (2026-11-13)
+
+### 新功能
+- 舌诊/情绪模型版本管理实现(SC-A-21)
+- S-cfc-228 teacher.plan.review 使绿 - 方案内容安全复核(SC-T-28)落地
+
+### 其他
+- - MindModelManageService:listAll/online/offline/isEnabled,offline 三参含 fallbackVersion
+-   未指定回退方案拒绝下线(Result 400),非法/未知版本返回 400
+- - MindModelManageController(/api/admin/mind-model: list/online/offline,统一 @PostMapping)
+- - schema.sql 落地 mind_model 建表 + DatabaseInitializer 迁移470(幂等)
+- - API_REFERENCE §4.13 同步全新端点
+- 使 MindModelManageContractTest 11/11 转绿(RED 10 失败 → GREEN 0 失败)。
+- 
+- - HealthPlanServiceImpl 注入 WechatServiceInterface 并在 approveAndPublish 发布前做内容安全复核
+-   (内置敏感词/违规医疗主张检测 + wechatService.checkText 叠加,命中即拦截、不落库、状态保持待审核)
+- - 新增 ContentFilterController POST /api/content/plan-safety 方案内容安全复核端点
+- - 新增 PlanContentSafetyUtil 敏感词检测工具(fail-closed)
+- PlanContentSafetyReviewContractTest 9/9 转绿;关联 PlanReviewTeacherContractTest 19/19、
+- HealthPlanReviewGuardTest 10/10、PlanLifecycleParentContractTest 38/38、GuidePlanReviewControllerAuthTest 6/6 均绿。
+- 
+- 预期红(RED)契约测试,未改 src/main 实现。
+- 契约锚点(TC-P-90 / -E / -P + ED-4 + API_REFERENCE DimensionDailyLimit 模块,
+- 与 S-cfc-304 ruleEngine.apply 同链:ruleEngine 写入前经 daily limit 守卫校验):
+- - RED 守卫入口:EnergyService 应提供 public 每日上限守卫方法(当前 isDailyLimitExceeded 为 private)
+- - RED 守卫钩子:EnergyRuleEngine 应有 daily-limit 守卫钩子(ruleEngine 写入前校验)
+- - RED 配置驱动:EnergyService 应注入 DimensionDailyLimitMapper 读取 energy_daily_limit(当前硬编码 DAILY_LIMIT_MAP)
+- - RED 多来源共享:awardEnergyByCode(challenge 来源)绕过日上限(TC-P-90-E-1)
+- - RED 上限 0/负安全:配置 dailyLimit=0 应按 0 处理不发不崩溃(TC-P-90-E-4)
+- 实测:Tests run 8, Failures 5(红)/ 通过 3(2 正常流锚点 + 1 权限流标注不适用)。
+- 
+- 基线缺口(src/main 现状):
+- - /api/game/leaderboard 无家庭隔离(service 缺 familyId 参数、
+-   mapper SQL 无 family_id 过滤、controller 未消费 @RequestAttribute familyId);
+- - 游戏/积分/家庭勋章三个排行端点返回项均缺进度字段。
+- 7 条契约断言预期红(Tests: 8, Failures: 7),权限流说明性用例通过。
+- 
+
+### 测试
+- S-cfc-296 notification.center.view TDD-RED 契约单测(SC-P-78 消息中心/通知查看:列表/已读/越权回归钉 + 分页/消息不存在404 缺口)
+- S-cfc-306 energy.dailyLimit.guard TDD-RED 契约单测
+- family.childContext.switch RED 契约单测 12 例(1红11绿锁定)
+- 新增 admin.familyRelation.manage 契约级单测(SC-A-04 关系类型 CRUD,TDD-RED,8 断言预期红)
+- 新增 growth.leaderboard.view 契约级 RED 单测(S-cfc-302)
+
+
+## v1.0.2468 (2026-11-13)
+
+### 测试
+- RED 契约单测 data.export.gdpr(SC-P-72 个人/家庭数据导出 GDPR,申请->加密包->下载/脱敏/频次/越权)
+- 契约级单测 ShopCouponClaimContractTest(S-cfc-293,SC-P-75 优惠券领取)
+- S-cfc-301 auth.session.mutex 契约级 RED 单测(SC-P-85 多端登录/会话互斥)
+- RED 契约测试——活动打卡/助力进度累计+幂等+反刷量
+
+### 其他
+- 
+- 刷量/机器行为拦截;CF 值预估(SC-X-22)。
+- 契约宿主 ActivityCheckinBoostService 尚未实现,14 用例 13 红 1 标记不适用。
+- 
+
+
+## v1.0.2467 (2026-11-13)
+
+### 测试
+- RED 契约测试 assessment.result.view (S-cfc-278)
+
+### 其他
+- (查看测评结果:八类报告展示、结果未录入不展示、量纲标注)与
+- API_REFERENCE.md §4.10(POST /api/assessment/latest-result、/history)。
+- 纯 Mockito + 反射,无 Spring/DB/外部服务,沿用同批 RED 测试风格
+- (TeamProfitHookContractTest / FamilyJoinValidationRulesContractTest)。
+- - 边界一(对照,已落地):结果未录入返回 success(null) 不展示
+- - 边界二(红):AssessmentResultDTO 缺量纲标注(0-100 范围)字段
+- - 边界二(红):八类报告维度缺中文标签字段
+- - 边界三(红):分数超出 0-100 量纲未拒显(直接透传 code=200)
+- - 结构锚点:AssessmentResultController.getLatestResult 存在
+- 红测结果:Tests run 6, Failures 4, Errors 0(4 项契约缺口断言按预期失败)
+- 
+
+
 ## v1.0.2466 (2026-11-13)
 
 ### 文档

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

@@ -785,6 +785,7 @@ find cfc-backend/src/main/java -name "*XxxService.java" -o -name "*XxxController
 | `/api/admin/knowledge-base/*` | 知识库管理 |
 | `/api/admin/notices/*` | 公告管理 |
 | `/api/admin/innate-portrait-config/*` | 先天画像来源权重配置(list/update/invalidate) |
+| `/api/admin/mind-model/*` | 舌诊/情绪模型版本管理(mind.model.manage · SC-A-21):list 版本列表 / online 上线 / offline 下线(须指定 fallbackVersion 回退版本) |
 | `/api/admin/numsoul-detail-config/*` | 数字能量详细配置(list/create/update/delete) |
 | `/api/admin/package-templates/*` | 套餐模板 |
 | `/api/admin/ppoint-config/*` | P点配置(品类级比例+商品级固定值) |

+ 175 - 0
docs/tdd/orchestration/report-dev-2026-11-14-0522.md

@@ -0,0 +1,175 @@
+# 研发负责人工作汇报(第129轮 · 自动化错峰轮)
+
+> 本轮为「研发负责人」定时自动化轮(无人值守),基于 tdd-orchestrator skill 全自动闭环(--auto --role 开发),只认已推送远端 git 真理证据。填报时间 2026-11-14 05:22。
+
+---
+
+## 基本信息
+
+| 项目 | 内容 |
+|------|------|
+| 汇报人 | 研发负责人(AI 自动化错峰轮) |
+| 汇报周期 | 2026-11-14 03:58 ~ 05:22(第 129 轮,本自动化) |
+| 负责模块/单元范围 | 全量(CFC 用户场景端到端跑通闭环,开发侧实现使绿 + 派发 + 部署收口 + 场景台账) |
+
+---
+
+## 一、本轮工作数据汇总
+
+### 1.1 问题接收与处置
+
+| 指标 | 数量 | 填写说明 |
+|------|------|----------|
+| **收到的测试反馈问题数*** | 0 个 | 本轮无新增 `--mark-blocked` 登记;blockers.md 无新增研发侧待办(dev 角色只读,沿用 03:55 轮口径) |
+| **已解决问题数*** | 0 个 | 本轮为纯派发轮——无收口/无 mark-* 推进(RED/YELLOW 阶段流转依赖会话执行证据与测试侧 mark-green,dev 不代越) |
+| **待解决研发问题数** | 0 个新增 | 沿用历史遗留:RED 64 键缺实现/证据、YELLOW 123 键待测试 mark-green、部署 pending 30 归部署侧(O-24) |
+
+### 1.2 任务分发与会话管理
+
+| 指标 | 数量 | 填写说明 |
+|------|------|----------|
+| **分派任务数*** | 50 个 | 批量派发 pending 池(S-cfc-293~308 共 16 条 RED 契约测试 + S-cfc-313~346 共 34 条 GREEN 实现),任务池 347 = done243 / failed1 / **dispatched 103** / **pending 0**,池空收敛 |
+| **恢复智能体会话数*** | 0 个 | --resume --dry-run 识别 0 候选(prod-etotem 生产实例默认跳过;无 interrupted/wedged/swallowed/stalled/upstream_err/thrash 候选) |
+| **当前在用会话数** | 7-8 个 | 派发瞬时各实例 busy 1~4/10;5 实例全部可达,配额余量充足(lan-189/lan-204/local-lan-4090/mes-local-45278 各剩 8,pub-iwintrue 剩 9) |
+| **会话平均利用率** | 不估(派发轮) | 批量派发为瞬时动作,不进行时长利用率精算 |
+
+### 1.2b 各会话当前工作状态列表
+
+| 会话标签 | 会话 ID | 当前状态 | 当前任务 | 静默/空闲时长 | 工作目录 | 备注 |
+|----------|---------|----------|----------|---------------|----------|------|
+| lan-189 | ses_e297591dbff… | running | S-cfc-296/298/301/326/331 等 | 0min(刚派发) | .worktrees/task_S-cfc-* | 独立 worktree,完成后自 commit+push |
+| lan-204 | ses_e2964415bff… | running | S-cfc-315/316/318/327/328/329/332 等本轮派发 | 0min(刚派发) | .worktrees/task_S-cfc-* | 独立 worktree |
+| local-lan-4090 | ses_e29670f85ff… | running | S-cfc-293/302/314/320/322/333/334/336~346 等(并发承载最多) | 0min(刚派发) | .worktrees/task_S-cfc-* | ⚠️ 中途 1 次节点连接失败(WinError 10061)+ deepseek/agnes 双档冷却至 08:00,已自动重试成功 |
+| mes-local-45278 | ses_e2973cefeff… | running | S-cfc-294/297/300/303/304/305/307/308/316/319/321/323/330/335 等 | 0min(刚派发) | .worktrees/task_S-cfc-* | 独立 worktree |
+| pub-iwintrue | ses_e2975b1b3ff… | running | S-cfc-295/306/317/324/325 等 | 0min(刚派发) | .worktrees/task_S-cfc-* | 独立 worktree |
+| cfc-test(部署) | ses_e4804838af… | idle | 无新部署(本轮未派发部署任务) | — | — | 部署 pending 30 归部署侧 O-24 |
+| cfc-prod(部署) | ses_f719c9326f… | idle | 无生产部署(confirm 门) | — | — | 默认跳过 |
+
+> R2「不留空闲」:本自动化单轮实际完成 **50 条派发**(通过连续多轮 --auto 批装满配,远超单次 --limit 2),任务池 pending 归零;第 157 轮错峰(03:55)汇报刚推,本轮与其跨轮接力(S-cfc-309/311 由错峰轮派发)。
+
+### 1.3 变更感知与新任务建立
+
+| 指标 | 数量 | 填写说明 |
+|------|------|----------|
+| **感知需求/设计变更数*** | 1 次(--changes --days 7) | 检出 200 提交/161 文件:测试侧契约批次(S-cfc-197~245)+ 测试负责人 R178~R192 连续闭环 + SC 台账全映射;**无需求/设计口径变更** |
+| **新增入池任务数*** | 0 个 | 0 新增能力键(O-7:无合法 --add-task 候选,防假红稳态延续) |
+| **既有键状态流转数** | 0 次显式 mark-* | 本轮派发 RED 契约测试 16 + GREEN 实现 34(RED 任务已写契约单测预期红,实现任务使绿后由测试侧核验 mark-green;dev 不代越) |
+
+### 1.4 本轮 git 提交与推送证据(真理证据)
+
+| 提交 sha | 关联任务/能力键 | 阶段 | 触及文件类型 | 目标分支 | 已推送远端 | 备注 |
+|----------|-----------------|------|--------------|----------|------------|------|
+| 74fb9a355 | S-cfc-228 teacher.plan.review | GREEN | 实现 | cfclub | 是 | 本轮开局时已在 origin/cfclub(错峰轮产物),--auto 识别 |
+| 430cf73a6 | S-cfc-296 notification.center.view | RED | 测试契约 | cfclub | 是 | 本轮派发 S-cfc-296 后会话已产出契约单测(SC-P-78 消息中心) |
+| 1a1079293 | merge tmp/merge-S-cfc-308 | — | 合并 | cfclub | 是 | S-cfc-308 admin.familyRelation.manage 工作树合并 |
+| 2d4e4208b | Merge cfclub | — | 合并 | cfclub | 是 | auto-bump 上游合入 |
+
+> 本轮派发的 50 个任务会话正在独立 worktree 中产出(契约单测 / 实现代码),执行证据与 push 将在后续轮次由 --auto git 证据识别并核验。本轮自身无编排侧文件提交(派发仅更新本地 .tdd/state.json + tasks.json,不入库)。
+
+### 1.5 状态机阶段分布与部署状态
+
+| 阶段 | 键数 | 备注 |
+|------|------|------|
+| UNTRACKED | — | CFC 当前走 SC 台账 + 任务账本驱动,非 SRS ⏳ 口径 |
+| RED | 64 | 测试契约已写/实现未落的键(本轮新增 16 条 RED 契约测试任务派发,契约落盘后 --auto 将按证据认领) |
+| YELLOW | 123 | 实现使绿待测试校验(闭环最大卡点,待测试侧三类流证据 + mark-green) |
+| GREEN | 8 | 待部署验证 |
+| DONE | 15 | 闭环归档 |
+
+| 部署项 | 值 | 说明 |
+|--------|-----|------|
+| 本轮部署次数 | 0 次 | 本轮纯派发轮,未派发部署任务 |
+| 最新 last_deployed | confirmed 77 条 | 见 deploy_state.json(本轮未新增) |
+| GREEN 部署链验证 | 不通过(待收口) | deploy pending 30 条待编排侧 --deploy-done 确认(O-24) |
+
+### 1.6 数据源健康度
+
+| 数据源 | 读取键数 | 是否正常 | 备注 |
+|--------|----------|----------|------|
+| 需求侧(⏳ wish) | 0 | 正常(口径外) | CFC 当前走 SC 台账 + 任务账本驱动,0 为口径预期 |
+| 契约常量(contract) | 0 | 正常(口径外) | ops_file 标注用,不入池门槛 |
+| 测试用例引用(test_case_map) | 0 | 正常(口径外) | 目标池按 SC 台账 241 维护,sc-key-map.md 唯一 SC 行 241 零漂移 |
+| 执行结果回填(case_results) | 0 | 正常(口径外) | 测试侧 automation-status.md / blockers.md 已 push 维护中 |
+
+---
+
+## 场景覆盖矩阵(本轮必填增列)
+
+| 指标 | 数值 | 说明 |
+|------|------|------|
+| 场景总数 | 241 | sc-key-map.md 唯一 SC 行 241 零漂移(O-8 归一口径) |
+| 累计已跑通 | 15 | SC-G-01~12 游客域 + SC-G-02/G-06 + SC-P-03/P-10/P-11(O-3 收口,证据 sha 已核验) |
+| 本轮新增跑通 | 0 | 本轮无 SC 转正(RED 契约测试刚派发,尚未产证据;GREEN 实现须测试侧三类流证据 + mark-green) |
+| 失败 | 0 | — |
+| 阻塞 | 0 | blockers.md 当前无已登记阻塞 |
+| 未跟踪 | 226 | 18 有键未跑通 + 208 无键未契约化 |
+
+> 本轮推进的 SC 编号(派发契约测试/实现任务的场景锚点):SC-P-75(shop.coupon.claim)/ SC-P-76(activity.enroll.join)/ SC-P-77(activity.checkin.boost)/ SC-P-78(notification.center.view)/ SC-P-80(membership.plan.refund)/ SC-P-81(plan.draft.save)/ SC-P-82(global.search.query)/ SC-P-83(feedback.consult.submit)/ SC-P-84(share.link.generate)/ SC-P-85(auth.session.mutex)/ SC-P-86(growth.leaderboard.view)/ SC-P-87(energy.ruleEngine.apply)/ SC-P-89(energy.admin.adjust)/ SC-P-90(energy.dailyLimit.guard)/ SC-P-96(ui.profile.achievementLayout)/ SC-A-04(admin.familyRelation.manage,RED 契约测试);34 条 GREEN 实现对应 admin/child/supplier/ai.coach/teacher 域已契约化键(SC-A-02~21、SC-C-01~26、SC-S-01~11、SC-B、SC-T 子集)。契约测试落地后这些 SC 进入可核验轨道,转正仍待测试侧三类流证据 + mark-green。
+
+---
+
+## 二、下一步需要研发处理的事项
+
+| 序号 | 事项描述 | 依赖/前置条件 | 预估完成时间 | 优先级 | 状态 |
+|------|----------|---------------|--------------|--------|------|
+| 1 | 50 个已派发任务会话执行结果收集(16 RED 契约测试 + 34 GREEN 实现) | 各 worktree 会话完成 | 后续轮次持续 | P0 | 进行中 |
+| 2 | RED 契约测试产出落盘后 --auto 认领 red_sha,YELLOW 实现证据识别 | 会话 git push | 后续轮次 | P1 | 待执行 |
+| 3 | YELLOW 123 键对应 SC 转正(测试侧三类流证据 + mark-green) | 测试侧 | 本周内 | P1 | 待测试侧 |
+| 4 | deploy pending 30 条回执确认(O-24) | 部署会话 | 后续轮次 | P1 | 进行中 |
+| 5 | CI 管线首跑触发(when: manual → on_success,需主理人核实 runner JDK8) | 主理人 | 待定(延续 2026-11-06 起缺口) | P2 | 待主理人 |
+
+## 三、阻塞与风险
+
+| 阻塞项 | 影响范围 | 阻塞类型 | 处置进展 | 需要协调 |
+|--------|----------|----------|----------|----------|
+| 主工作树 924 处他人 WIP 未提交(clean-check exit=1) | 全局门禁提示 | 测试/其他 | O-3 判据③零交集,不阻塞派发;如实记录退出码 1 | 各会话自行收口(严禁 add -A) |
+| local-lan-4090 节点连接拒绝(WinError 10061)+ deepseek/agnes 双档模型冷却至 08:00 | 该实例派发 | 基础设施 | S-cfc-334 首派失败已自动重试成功;冷却时段该实例换档或换节点 | 机器侧节点探活 |
+| 统一维度体系双实现路由歧义(O-11) | 合并风险 | 设计 | 未动,待主理人裁决正本 | 主理人 |
+
+## 四、下轮工作规划
+
+| 计划项 | 预计完成时间 | 前置依赖 | 涉及会话标签 | 备注 |
+|--------|--------------|----------|--------------|------|
+| 回收 50 个派发任务执行证据(--auto) | 下轮 | 会话产出 push | 全实例 | 每轮 --limit 2 批量 |
+| 新增 RED 契约测试认领 + YELLOW 证据识别 | 下轮 | 会话 git push | 全实例 | — |
+| 无新键时保持池空稳态(O-7 防假红) | 下轮 | 0 新增能力键 | — | 不制造伪任务 |
+| webhook 发送(下一发送点 06:00–06:40 窗口) | 下轮 | 本轮素材(50 派发 + 工作量统计) | — | 6:00–22:00 每 4h 窗口规则 |
+
+---
+
+## 附录
+
+### 附录 A:收到的测试反馈问题明细
+
+| 问题 ID | 能力键/任务号 | 问题类型 | 来源 | 接收时间 | 处置状态 | 关联 sha |
+|---------|---------------|----------|------|----------|----------|----------|
+| (无) | — | — | — | — | — | 本轮无新增测试反馈问题 |
+
+### 附录 B:任务分派与会话恢复明细
+
+| 任务号 | 目标会话标签 | 任务类型 | 分派时间 | 当前状态 | 恢复会话标签 | 恢复原因 | 恢复时间 |
+|--------|--------------|----------|----------|----------|--------------|----------|----------|
+| S-cfc-293 | local-lan-4090 | RED 契约 | 04:0x | running | — | — | — |
+| S-cfc-294 | mes-local-45278 | RED 契约 | 04:0x | running | — | — | — |
+| S-cfc-295 | pub-iwintrue | RED 契约 | 04:0x | running | — | — | — |
+| S-cfc-296 | lan-189 | RED 契约 | 04:0x | running | — | — | — |
+| S-cfc-297~308 | 多实例混派 | RED 契约 ×12 | 04:0x~04:2x | running | — | — | — |
+| S-cfc-313~346 | 多实例混派 | GREEN 实现 ×34 | 04:2x~05:1x | running | — | — | — |
+| S-cfc-334 | local-lan-4090 | GREEN 实现 | 04:5x | running | 重试成功 | 首派 WinError 10061 节点拒绝 | 05:0x |
+| (无恢复) | — | — | — | — | — | — | — |
+
+> 共 50 条派发(16 RED + 34 GREEN),完整任务-实例-会话映射见 .workbuddy/tasks.json(本地私有)。
+
+### 附录 C:新增入池任务明细
+
+| 任务号 | 能力键 | 需求溯源 | 设计溯源 | 创建时间 | 状态 |
+|--------|--------|----------|----------|----------|------|
+| (无) | — | 0 新增能力键(O-7) | — | — | — |
+
+### 附录 D:变更感知明细(来自 `--changes`)
+
+| 变更文档 | 文档类型 | 变更日期 | 新增能力键 | 是否已入池 |
+|----------|----------|----------|------------|------------|
+| 测试侧契约批次(S-cfc-197~245) | 用例 | 2026-11-12~13 | 0(变化集中既有键) | 是 |
+| 测试负责人 R178~R192 闭环汇报 | 其他 | 2026-11-13 | 0 | 是 |
+| SC 台账全映射(160b9bd14) | 设计 | 2026-11-13 | 0 | 是 |