Explorar el Código

Merge remote-tracking branch 'origin/cfclub' into tmp/merge-S-cfc-308

Agnes Agent hace 4 días
padre
commit
4cc0f44803

+ 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 "";
+        }
+    }
+}

+ 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;
+    }
+}

+ 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));
+    }
+}