Răsfoiți Sursa

fix(cf): 恢复 B-11 误覆盖删除的 /api/cf 三端点并补契约测试(S-cfc-24)

判定:44b2f0d42 与 3036a0bd4 把 CfBalanceController.java / promotion/index.vue /
api.js / profile.vue 整文件回滚到 dfc78e9d3 之前(git diff dfc78e9d3^ 44b2f0d42 对
这 4 个文件为空,逐字节相同),误覆盖删除了 /api/cf/stats、/api/cf/family-summary、
/api/cf/promotion-earnings + 前端 3 封装 + currentMemberId 成员解析,属误覆盖而非
有意精简(dfc78e9d3 为 'fix(cf): 财富中心/推广收益改读实时CF账本' 的有意修复,
且回滚后前端退回读停写的 family_earnings / 邀请表旧口径,违反 2026-10-25 单一账本口径)。

处置:
- 恢复 CfBalanceController 三端点与 currentMemberId 优先成员解析(= dfc78e9d3 语义);
- 恢复 promotion/index.vue;api.js 重加 3 个封装;profile.vue 定向还原 2 处(保留后续
  '我的成就' 重构的合法改动);
- 补契约测试:CfBalanceStatsTest / CfBalanceFamilySummaryTest / CfBalancePromotionEarningsTest
  (每端点正常流+鉴权流 >=2 例,共 11 例)+ 更新 CfBalanceControllerTest 适配双参签名;
- API_REFERENCE.md 登记三端点并附 B-11 变更记录(此前该文档从未收录三端点,属文档缺口,
  正是其可被静默删除的诱因之一)。

验证:mvn test 上述 4 类 19/19 绿;testCompile 0 错;前端 api.js/vue <script> 语法校验通过;
全量 1763 例中 69F/51E 均为基线(origin/cfclub 未改动)同样存在的既有失败(StatsController
familyCompletion_NoFamily 500 vs 5001、DB 集成类等),无任一失败类引用 CfBalanceController/api/cf。
Sisyphus 1 săptămână în urmă
părinte
comite
3f9d72ed5e

+ 197 - 13
cfc-backend/src/main/java/com/etotem/cfc/controller/CfBalanceController.java

@@ -5,9 +5,16 @@ import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
 import com.etotem.cfc.common.Result;
 import com.etotem.cfc.dto.CfBalanceLogVO;
 import com.etotem.cfc.dto.CfBalanceView;
+import com.etotem.cfc.dto.FamilyEarningsMemberDTO;
+import com.etotem.cfc.dto.FamilyEarningsSummaryDTO;
+import com.etotem.cfc.entity.CfBalance;
 import com.etotem.cfc.entity.CfBalanceLog;
 import com.etotem.cfc.entity.FamilyMember;
+import com.etotem.cfc.entity.User;
+import com.etotem.cfc.mapper.CfBalanceLogMapper;
+import com.etotem.cfc.mapper.CfBalanceMapper;
 import com.etotem.cfc.mapper.FamilyMemberMapper;
+import com.etotem.cfc.mapper.UserMapper;
 import com.etotem.cfc.service.CfBalanceService;
 import com.etotem.cfc.service.CouponService;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -17,28 +24,41 @@ import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
 import javax.annotation.Resource;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Calendar;
 import java.util.Collections;
+import java.util.Date;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 import java.util.stream.Collectors;
 
 /**
  * C 端 CF 值查询接口(只读)。
  *
  * <p>个人 CF 值账本为成员维度(family_members.id),本控制器把「登录 userId → memberId」
- * 的解析口径与 {@code CfEarnDispatchService}(F-3a)保持一致:按 user_id 在家庭内匹配,
- * 取最小 id 的一条(LIMIT 1);找不到对应家庭成员时返回明确错误码,不返回空数据。</p>
+ * 的解析口径与 {@code JwtInterceptor} 保持一致:优先使用拦截器按
+ * {@code users.family_id + family_members} 解析出的 {@code currentMemberId},
+ * 仅在缺失时回退到历史口径(user_id 最小一条)。</p>
  *
- * <p>仅提供三个只读接口:余额快照 / 流水分页 / 家庭共享优惠券列表,不提供任何写接口。
- * 余额与流水走统一账本 {@link CfBalanceService};家庭券复用 {@link CouponService#listMyCoupons}
- * (N3 家庭化口径:family_coupon + coupon 联合,家庭内成员共享可见)。</p>
+ * <p>仅提供只读接口:余额快照 / 流水分页 / 周期统计 / 家庭 CF 总览 / 推广类 CF 收益 /
+ * 家庭共享优惠券列表。余额与流水走统一账本 {@link CfBalanceService};
+ * 家庭券复用 {@link CouponService#listMyCoupons}(N3 家庭化口径:family_coupon + coupon 联合)。</p>
  *
- * <p>接口约定见 docs/superpowers/plans/2026-10-24-cf-value-unification-plan.md §七 F-7a。</p>
+ * <p>接口约定见 docs/superpowers/specs/2026-10-25-cf-value-single-source-of-truth.md §5/§6。</p>
  */
 @RestController
 @RequestMapping("/api/cf")
 public class CfBalanceController {
 
+    /** 推广类 CF 收益:推荐注册 F24 + 直接销售奖 F03a + 间接销售奖 F03b + 邀请里程碑 F11 */
+    private static final Set<String> PROMOTION_REF_TYPES = new HashSet<>(Arrays.asList(
+            "referral_register", "F03a", "F03b", "invite_milestone"));
+
     @Resource
     private CfBalanceService cfBalanceService;
 
@@ -48,12 +68,22 @@ public class CfBalanceController {
     @Resource
     private FamilyMemberMapper familyMemberMapper;
 
+    @Resource
+    private CfBalanceMapper cfBalanceMapper;
+
+    @Resource
+    private CfBalanceLogMapper cfBalanceLogMapper;
+
+    @Resource
+    private UserMapper userMapper;
+
     /**
      * 我的 CF 值快照:可用余额 / 冻结 / 累计获得 / 已提现 / 已兑换消费。
      */
     @GetMapping("/balance")
-    public Result<CfBalanceView> balance(@RequestAttribute("userId") Long userId) {
-        Long memberId = resolveMemberId(userId);
+    public Result<CfBalanceView> balance(@RequestAttribute("userId") Long userId,
+                                         @RequestAttribute(value = "currentMemberId", required = false) Long currentMemberId) {
+        Long memberId = resolveMemberId(userId, currentMemberId);
         if (memberId == null) {
             return Result.error(404, "未找到当前用户对应的家庭成员,无法查询 CF 值");
         }
@@ -65,9 +95,10 @@ public class CfBalanceController {
      */
     @GetMapping("/logs")
     public Result<Page<CfBalanceLogVO>> logs(@RequestAttribute("userId") Long userId,
+                                             @RequestAttribute(value = "currentMemberId", required = false) Long currentMemberId,
                                              @RequestParam(defaultValue = "1") Integer page,
                                              @RequestParam(defaultValue = "20") Integer size) {
-        Long memberId = resolveMemberId(userId);
+        Long memberId = resolveMemberId(userId, currentMemberId);
         if (memberId == null) {
             return Result.error(404, "未找到当前用户对应的家庭成员,无法查询 CF 流水");
         }
@@ -80,6 +111,151 @@ public class CfBalanceController {
         return Result.success(vo);
     }
 
+    /**
+     * 我的 CF 周期统计:今日 / 本月获得 + 累计获得(cf_balance.total_earned)。
+     */
+    @GetMapping("/stats")
+    public Result<Map<String, Object>> stats(@RequestAttribute("userId") Long userId,
+                                             @RequestAttribute(value = "currentMemberId", required = false) Long currentMemberId) {
+        Long memberId = resolveMemberId(userId, currentMemberId);
+        if (memberId == null) {
+            return Result.error(404, "未找到当前用户对应的家庭成员,无法查询 CF 统计");
+        }
+        CfBalanceView view = cfBalanceService.getBalance(memberId);
+
+        Calendar cal = Calendar.getInstance();
+        cal.set(Calendar.HOUR_OF_DAY, 0);
+        cal.set(Calendar.MINUTE, 0);
+        cal.set(Calendar.SECOND, 0);
+        cal.set(Calendar.MILLISECOND, 0);
+        Date startOfDay = cal.getTime();
+        cal.set(Calendar.DAY_OF_MONTH, 1);
+        Date startOfMonth = cal.getTime();
+
+        List<CfBalanceLog> monthLogs = cfBalanceLogMapper.selectList(new LambdaQueryWrapper<CfBalanceLog>()
+                .eq(CfBalanceLog::getMemberId, memberId)
+                .eq(CfBalanceLog::getType, "earn")
+                .ge(CfBalanceLog::getCreatedAt, startOfMonth));
+        int monthEarned = 0;
+        int todayEarned = 0;
+        for (CfBalanceLog log : monthLogs) {
+            int amount = log.getAmount() == null ? 0 : log.getAmount();
+            monthEarned += amount;
+            if (log.getCreatedAt() != null && !log.getCreatedAt().before(startOfDay)) {
+                todayEarned += amount;
+            }
+        }
+
+        Map<String, Object> data = new LinkedHashMap<>();
+        data.put("todayEarned", todayEarned);
+        data.put("monthEarned", monthEarned);
+        data.put("totalEarned", view.getTotalEarned() == null ? 0 : view.getTotalEarned());
+        data.put("available", view.getAvailable() == null ? 0 : view.getAvailable());
+        return Result.success(data);
+    }
+
+    /**
+     * 家庭 CF 总览(成员维度):全家累计 / 可用 / 已提现 / 已兑换 + 成员贡献榜。
+     *
+     * <p>替代已停写的 {@code family_earnings} 旧账本,数据源为 {@code cf_balance}。</p>
+     */
+    @GetMapping("/family-summary")
+    public Result<FamilyEarningsSummaryDTO> familySummary(@RequestAttribute("userId") Long userId,
+                                                          @RequestAttribute(value = "currentMemberId", required = false) Long currentMemberId) {
+        Long memberId = resolveMemberId(userId, currentMemberId);
+        if (memberId == null) {
+            return Result.error(404, "未找到当前用户对应的家庭成员,无法查询家庭 CF 总览");
+        }
+        FamilyMember self = familyMemberMapper.selectById(memberId);
+        Long familyId = self == null ? null : self.getFamilyId();
+
+        FamilyEarningsSummaryDTO summary = new FamilyEarningsSummaryDTO();
+        summary.setFamilyId(familyId);
+
+        List<CfBalance> balances = familyId == null ? Collections.emptyList()
+                : cfBalanceMapper.selectList(new LambdaQueryWrapper<CfBalance>()
+                        .eq(CfBalance::getFamilyId, familyId));
+
+        List<Long> memberIds = balances.stream()
+                .map(CfBalance::getMemberId).filter(id -> id != null)
+                .collect(Collectors.toList());
+        Map<Long, FamilyMember> memberMap = memberIds.isEmpty() ? Collections.emptyMap()
+                : familyMemberMapper.selectBatchIds(memberIds).stream()
+                        .collect(Collectors.toMap(FamilyMember::getId, m -> m, (a, b) -> a));
+
+        List<Long> userIds = balances.stream()
+                .map(CfBalance::getUserId).filter(id -> id != null)
+                .collect(Collectors.toList());
+        Map<Long, User> userMap = userIds.isEmpty() ? Collections.emptyMap()
+                : userMapper.selectBatchIds(userIds).stream()
+                        .collect(Collectors.toMap(User::getId, u -> u, (a, b) -> a));
+
+        long totalEarned = 0L;
+        long available = 0L;
+        long withdrawn = 0L;
+        long exchanged = 0L;
+        List<FamilyEarningsMemberDTO> members = new ArrayList<>();
+        for (CfBalance balance : balances) {
+            long memberTotal = balance.getTotalEarned() == null ? 0L : balance.getTotalEarned();
+            long memberAvailable = balance.getAvailable() == null ? 0L : balance.getAvailable();
+            FamilyMember member = memberMap.get(balance.getMemberId());
+            User user = balance.getUserId() == null ? null : userMap.get(balance.getUserId());
+
+            FamilyEarningsMemberDTO dto = new FamilyEarningsMemberDTO();
+            dto.setUserId(balance.getUserId());
+            dto.setNickname(user != null && user.getNickname() != null ? user.getNickname()
+                    : (member == null ? null : member.getNickname()));
+            dto.setAvatar(user != null && user.getAvatar() != null ? user.getAvatar()
+                    : (member == null ? null : member.getAvatar()));
+            dto.setAllocatedAmount(memberTotal);
+            dto.setAvailableAmount(memberAvailable);
+            dto.setConsumedAmount(Math.max(0L, memberTotal - memberAvailable));
+            dto.setIsAdmin(user != null && Boolean.TRUE.equals(user.getIsFamilyAdmin()));
+            // 新模型无家庭公共池,字段保留兼容前端;家庭内共享通过优惠券 / 成员转让实现
+            dto.setCanUseFamilyBalance(true);
+            members.add(dto);
+
+            totalEarned += memberTotal;
+            available += memberAvailable;
+            withdrawn += balance.getWithdrawn() == null ? 0L : balance.getWithdrawn();
+            exchanged += balance.getExchanged() == null ? 0L : balance.getExchanged();
+        }
+        members.sort((a, b) -> Long.compare(
+                b.getAllocatedAmount() == null ? 0L : b.getAllocatedAmount(),
+                a.getAllocatedAmount() == null ? 0L : a.getAllocatedAmount()));
+
+        summary.setTotalEarned(totalEarned);
+        summary.setAvailableAmount(available);
+        summary.setWithdrawnAmount(withdrawn);
+        summary.setDistributedAmount(exchanged);
+        summary.setMembers(members);
+        return Result.success(summary);
+    }
+
+    /**
+     * 推广类 CF 收益:F24 推荐注册 + F03a 直接销售奖 + F03b 间接销售奖 + F11 邀请里程碑。
+     *
+     * <p>仅统计本人当前成员的 {@code cf_balance_log}(type=earn)。</p>
+     */
+    @GetMapping("/promotion-earnings")
+    public Result<Map<String, Object>> promotionEarnings(@RequestAttribute("userId") Long userId,
+                                                         @RequestAttribute(value = "currentMemberId", required = false) Long currentMemberId) {
+        Long memberId = resolveMemberId(userId, currentMemberId);
+        if (memberId == null) {
+            return Result.error(404, "未找到当前用户对应的家庭成员,无法查询推广收益");
+        }
+        List<CfBalanceLog> logs = cfBalanceLogMapper.selectList(new LambdaQueryWrapper<CfBalanceLog>()
+                .eq(CfBalanceLog::getMemberId, memberId)
+                .eq(CfBalanceLog::getType, "earn")
+                .in(CfBalanceLog::getRefType, PROMOTION_REF_TYPES));
+        int total = logs.stream().mapToInt(log -> log.getAmount() == null ? 0 : log.getAmount()).sum();
+
+        Map<String, Object> data = new LinkedHashMap<>();
+        data.put("totalEarned", total);
+        data.put("refTypes", new ArrayList<>(PROMOTION_REF_TYPES));
+        return Result.success(data);
+    }
+
     /**
      * 家庭共享优惠券列表(N3 口径):按登录用户所属家庭查券实例 + 券模板,
      * 返回券名 / 状态 / 有效期 / 抵扣面额等展示字段,家庭内成员共享可见。
@@ -102,10 +278,18 @@ public class CfBalanceController {
     }
 
     /**
-     * 登录 userId → 家庭成员(family_members.id)。
-     * 口径与 {@code CfEarnDispatchService} 的 resolveMemberId 一致:user_id 匹配 +
-     * 按 id 升序取第一条(LIMIT 1),未命中返回 null。
+     * 登录 userId → 当前家庭成员(family_members.id)。
+     *
+     * <p>优先使用 {@code JwtInterceptor} 按 {@code users.family_id} 解析出的 currentMemberId;
+     * 缺失时回退到历史口径(user_id 匹配 + id 升序 LIMIT 1),保证无家庭用户兼容。</p>
      */
+    private Long resolveMemberId(Long userId, Long currentMemberId) {
+        if (currentMemberId != null && currentMemberId > 0) {
+            return currentMemberId;
+        }
+        return resolveMemberId(userId);
+    }
+
     private Long resolveMemberId(Long userId) {
         if (userId == null || userId <= 0) {
             return null;
@@ -116,4 +300,4 @@ public class CfBalanceController {
                 .last("LIMIT 1"));
         return member == null ? null : member.getId();
     }
-}
+}

+ 118 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/AbstractCfBalanceStatsTestBase.java

@@ -0,0 +1,118 @@
+package com.etotem.cfc.unit;
+
+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.core.metadata.TableInfoHelper;
+import com.etotem.cfc.controller.CfBalanceController;
+import com.etotem.cfc.dto.CfBalanceView;
+import com.etotem.cfc.entity.CfBalance;
+import com.etotem.cfc.entity.CfBalanceLog;
+import com.etotem.cfc.entity.FamilyMember;
+import com.etotem.cfc.mapper.CfBalanceLogMapper;
+import com.etotem.cfc.mapper.CfBalanceMapper;
+import com.etotem.cfc.mapper.FamilyMemberMapper;
+import com.etotem.cfc.mapper.UserMapper;
+import com.etotem.cfc.service.CfBalanceService;
+import com.etotem.cfc.service.CouponService;
+import org.apache.ibatis.builder.MapperBuilderAssistant;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.BeforeEach;
+
+import java.lang.reflect.Field;
+import java.util.Date;
+
+import static org.mockito.Mockito.mock;
+
+/**
+ * C 端 CF 三端点回归契约测试基类(B-11 处置)。
+ *
+ * <p>背景:{@code 44b2f0d42}(chore(sync) 遗留 WIP 收尾同步)与 {@code 3036a0bd4} 把
+ * {@code CfBalanceController} 整文件回滚到 {@code dfc78e9d3} 之前的历史版本,
+ * 静默删掉 {@code /api/cf/stats}、{@code /api/cf/family-summary}、{@code /api/cf/promotion-earnings}
+ * 三端点 + 前端 3 个封装 + {@code currentMemberId} 成员解析,且全套用例零转红(无任何用例覆盖)。
+ * 本组测试按「正常流 + 鉴权流」为每个端点各补 ≥2 例,锁死契约,防止再次被 WIP 覆盖静默删除。</p>
+ */
+abstract class AbstractCfBalanceStatsTestBase {
+
+    protected CfBalanceController controller;
+    protected CfBalanceService cfBalanceService;
+    protected CouponService couponService;
+    protected FamilyMemberMapper familyMemberMapper;
+    protected CfBalanceMapper cfBalanceMapper;
+    protected CfBalanceLogMapper cfBalanceLogMapper;
+    protected UserMapper userMapper;
+
+    @BeforeAll
+    static void initMybatisPlusTableInfo() {
+        // 初始化 MP TableInfo 缓存,使 LambdaQueryWrapper.getSqlSegment() 在无 Spring 上下文中可用
+        TableInfoHelper.initTableInfo(
+                new MapperBuilderAssistant(new MybatisConfiguration(), ""), FamilyMember.class);
+        TableInfoHelper.initTableInfo(
+                new MapperBuilderAssistant(new MybatisConfiguration(), ""), CfBalance.class);
+        TableInfoHelper.initTableInfo(
+                new MapperBuilderAssistant(new MybatisConfiguration(), ""), CfBalanceLog.class);
+    }
+
+    @BeforeEach
+    void setUp() throws Exception {
+        controller = new CfBalanceController();
+        cfBalanceService = mock(CfBalanceService.class);
+        couponService = mock(CouponService.class);
+        familyMemberMapper = mock(FamilyMemberMapper.class);
+        cfBalanceMapper = mock(CfBalanceMapper.class);
+        cfBalanceLogMapper = mock(CfBalanceLogMapper.class);
+        userMapper = mock(UserMapper.class);
+        inject(controller, "cfBalanceService", cfBalanceService);
+        inject(controller, "couponService", couponService);
+        inject(controller, "familyMemberMapper", familyMemberMapper);
+        inject(controller, "cfBalanceMapper", cfBalanceMapper);
+        inject(controller, "cfBalanceLogMapper", cfBalanceLogMapper);
+        inject(controller, "userMapper", userMapper);
+    }
+
+    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);
+    }
+
+    protected FamilyMember member(Long id, Long userId, Long familyId, String nickname) {
+        FamilyMember m = new FamilyMember();
+        m.setId(id);
+        m.setUserId(userId);
+        m.setFamilyId(familyId);
+        m.setNickname(nickname);
+        return m;
+    }
+
+    protected CfBalanceLog earnLog(Long id, Integer amount, String refType, Date createdAt) {
+        CfBalanceLog log = new CfBalanceLog();
+        log.setId(id);
+        log.setType("earn");
+        log.setRefType(refType);
+        log.setAmount(amount);
+        log.setCreatedAt(createdAt);
+        return log;
+    }
+
+    protected CfBalanceView view(Integer available, Integer totalEarned) {
+        CfBalanceView v = new CfBalanceView();
+        v.setMemberId(42L);
+        v.setAvailable(available);
+        v.setTotalEarned(totalEarned);
+        return v;
+    }
+
+    protected CfBalance balance(Long memberId, Long userId, Long familyId,
+                                Integer totalEarned, Integer available,
+                                Integer withdrawn, Integer exchanged) {
+        CfBalance b = new CfBalance();
+        b.setMemberId(memberId);
+        b.setUserId(userId);
+        b.setFamilyId(familyId);
+        b.setTotalEarned(totalEarned);
+        b.setAvailable(available);
+        b.setWithdrawn(withdrawn);
+        b.setExchanged(exchanged);
+        return b;
+    }
+}

+ 7 - 7
cfc-backend/src/test/java/com/etotem/cfc/unit/CfBalanceControllerTest.java

@@ -92,7 +92,7 @@ class CfBalanceControllerTest {
         view.setMemberId(42L);
         when(cfBalanceService.getBalance(42L)).thenReturn(view);
 
-        Result<CfBalanceView> r = controller.balance(7L);
+        Result<CfBalanceView> r = controller.balance(7L, null);
 
         assertEquals(200, r.getCode());
         assertEquals(42L, r.getData().getMemberId());
@@ -110,7 +110,7 @@ class CfBalanceControllerTest {
     void resolveMemberId_未命中_返回404且不查账本() {
         when(familyMemberMapper.selectOne(any())).thenReturn(null);
 
-        Result<CfBalanceView> r = controller.balance(99L);
+        Result<CfBalanceView> r = controller.balance(99L, null);
 
         assertEquals(404, r.getCode());
         verify(cfBalanceService, never()).getBalance(anyLong());
@@ -118,7 +118,7 @@ class CfBalanceControllerTest {
 
     @Test
     void resolveMemberId_userId非法_返回404() {
-        Result<CfBalanceView> r = controller.balance(-1L);
+        Result<CfBalanceView> r = controller.balance(-1L, null);
         assertEquals(404, r.getCode());
         verify(familyMemberMapper, never()).selectOne(any());
     }
@@ -137,7 +137,7 @@ class CfBalanceControllerTest {
         view.setExchanged(370);
         when(cfBalanceService.getBalance(42L)).thenReturn(view);
 
-        Result<CfBalanceView> r = controller.balance(7L);
+        Result<CfBalanceView> r = controller.balance(7L, null);
         CfBalanceView data = r.getData();
 
         assertEquals(200, r.getCode());
@@ -166,7 +166,7 @@ class CfBalanceControllerTest {
         raw.setRecords(Collections.singletonList(log));
         when(cfBalanceService.getLogs(42L, 1, 20)).thenReturn(raw);
 
-        Result<Page<CfBalanceLogVO>> r = controller.logs(7L, 1, 20);
+        Result<Page<CfBalanceLogVO>> r = controller.logs(7L, null, 1, 20);
 
         assertEquals(200, r.getCode());
         Page<CfBalanceLogVO> data = r.getData();
@@ -186,7 +186,7 @@ class CfBalanceControllerTest {
     void logs_未命中_返回404且不查流水() {
         when(familyMemberMapper.selectOne(any())).thenReturn(null);
 
-        Result<Page<CfBalanceLogVO>> r = controller.logs(99L, 1, 20);
+        Result<Page<CfBalanceLogVO>> r = controller.logs(99L, null, 1, 20);
 
         assertEquals(404, r.getCode());
         verify(cfBalanceService, never()).getLogs(anyLong(), anyInt(), anyInt());
@@ -199,7 +199,7 @@ class CfBalanceControllerTest {
         raw.setRecords(Collections.emptyList());
         when(cfBalanceService.getLogs(42L, 1, 20)).thenReturn(raw);
 
-        Result<Page<CfBalanceLogVO>> r = controller.logs(7L, 1, 20);
+        Result<Page<CfBalanceLogVO>> r = controller.logs(7L, null, 1, 20);
 
         assertEquals(200, r.getCode());
         assertNotNull(r.getData().getRecords());

+ 105 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/CfBalanceFamilySummaryTest.java

@@ -0,0 +1,105 @@
+package com.etotem.cfc.unit;
+
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.dto.FamilyEarningsMemberDTO;
+import com.etotem.cfc.dto.FamilyEarningsSummaryDTO;
+import com.etotem.cfc.entity.User;
+import org.junit.jupiter.api.Test;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+
+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.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * {@code GET /api/cf/family-summary} 契约回归:家庭 CF 总览(数据源 cf_balance 实时账本)。
+ * 正常流 + 鉴权流 + 空家庭账本 + 家庭成员缺失容错,共 4 例。
+ */
+class CfBalanceFamilySummaryTest extends AbstractCfBalanceStatsTestBase {
+
+    @Test
+    void familySummary_正常流_按家庭聚合并按贡献倒序() {
+        when(familyMemberMapper.selectOne(any())).thenReturn(member(42L, 7L, 9L, "妈妈"));
+        when(familyMemberMapper.selectById(42L)).thenReturn(member(42L, 7L, 9L, "妈妈"));
+        when(cfBalanceMapper.selectList(any())).thenReturn(Arrays.asList(
+                balance(42L, 7L, 9L, 500, 300, 100, 100),
+                balance(43L, 8L, 9L, 900, 800, 0, 100)));
+        when(familyMemberMapper.selectBatchIds(any())).thenReturn(Arrays.asList(
+                member(42L, 7L, 9L, "妈妈"), member(43L, 8L, 9L, "爸爸")));
+        User mom = new User();
+        mom.setId(7L);
+        mom.setNickname("妈妈");
+        mom.setIsFamilyAdmin(true);
+        User dad = new User();
+        dad.setId(8L);
+        dad.setNickname("爸爸");
+        when(userMapper.selectBatchIds(any())).thenReturn(Arrays.asList(mom, dad));
+
+        Result<FamilyEarningsSummaryDTO> r = controller.familySummary(7L, null);
+
+        assertEquals(200, r.getCode());
+        FamilyEarningsSummaryDTO data = r.getData();
+        assertEquals(9L, data.getFamilyId());
+        // 数据源为 cf_balance(实时账本),不是停写的 family_earnings
+        assertEquals(1400L, data.getTotalEarned());
+        assertEquals(1100L, data.getAvailableAmount());
+        assertEquals(100L, data.getWithdrawnAmount());
+        assertEquals(200L, data.getDistributedAmount());
+
+        List<FamilyEarningsMemberDTO> members = data.getMembers();
+        assertNotNull(members);
+        assertEquals(2, members.size());
+        assertEquals(8L, members.get(0).getUserId(), "贡献高者排前");
+        assertEquals(900L, members.get(0).getAllocatedAmount());
+        assertEquals(100L, members.get(0).getConsumedAmount());
+        assertEquals(7L, members.get(1).getUserId());
+        assertEquals(Boolean.TRUE, members.get(1).getIsAdmin(), "管理员标记透传");
+    }
+
+    @Test
+    void familySummary_鉴权流_用户无家庭成员返回404且不查账本() {
+        when(familyMemberMapper.selectOne(any())).thenReturn(null);
+
+        Result<FamilyEarningsSummaryDTO> r = controller.familySummary(99L, null);
+
+        assertEquals(404, r.getCode());
+        assertTrue(r.getMessage().contains("家庭 CF 总览"), "错误信息应指明家庭 CF 总览,实际: " + r.getMessage());
+        verify(cfBalanceMapper, never()).selectList(any());
+        verify(userMapper, never()).selectBatchIds(any());
+    }
+
+    @Test
+    void familySummary_家庭无账本记录_返回空成员列表() {
+        when(familyMemberMapper.selectOne(any())).thenReturn(member(42L, 7L, 9L, "妈妈"));
+        when(familyMemberMapper.selectById(42L)).thenReturn(member(42L, 7L, 9L, "妈妈"));
+        when(cfBalanceMapper.selectList(any())).thenReturn(Collections.emptyList());
+
+        Result<FamilyEarningsSummaryDTO> r = controller.familySummary(7L, null);
+
+        assertEquals(200, r.getCode());
+        assertEquals(9L, r.getData().getFamilyId());
+        assertEquals(0L, r.getData().getTotalEarned());
+        assertNotNull(r.getData().getMembers());
+        assertTrue(r.getData().getMembers().isEmpty());
+        verify(familyMemberMapper, never()).selectBatchIds(any());
+    }
+
+    @Test
+    void familySummary_家庭成员缺失容错_不抛异常() {
+        when(familyMemberMapper.selectOne(any())).thenReturn(member(42L, 7L, 9L, "妈妈"));
+        when(familyMemberMapper.selectById(42L)).thenReturn(null);
+
+        Result<FamilyEarningsSummaryDTO> r = controller.familySummary(7L, null);
+
+        assertEquals(200, r.getCode());
+        assertEquals(null, r.getData().getFamilyId());
+        assertTrue(r.getData().getMembers().isEmpty());
+    }
+}

+ 78 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/CfBalancePromotionEarningsTest.java

@@ -0,0 +1,78 @@
+package com.etotem.cfc.unit;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.entity.CfBalanceLog;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.Date;
+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.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * {@code GET /api/cf/promotion-earnings} 契约回归:推广类 CF 收益
+ * (referral_register / F03a / F03b / invite_milestone)。正常流 + 鉴权流 + 空流水,共 3 例。
+ */
+class CfBalancePromotionEarningsTest extends AbstractCfBalanceStatsTestBase {
+
+    @Test
+    void promotionEarnings_正常流_仅统计推广类refType的earn流水() {
+        when(familyMemberMapper.selectOne(any())).thenReturn(member(42L, 7L, 9L, "妈妈"));
+        when(cfBalanceLogMapper.selectList(any())).thenReturn(Arrays.asList(
+                earnLog(1L, 100, "F24", new Date()),
+                earnLog(2L, 250, "F03a", new Date()),
+                earnLog(3L, 30, "invite_milestone", new Date())));
+
+        Result<Map<String, Object>> r = controller.promotionEarnings(7L, null);
+
+        assertEquals(200, r.getCode());
+        assertEquals(380, r.getData().get("totalEarned"));
+        @SuppressWarnings("unchecked")
+        List<String> refTypes = (List<String>) r.getData().get("refTypes");
+        assertNotNull(refTypes);
+        assertTrue(refTypes.containsAll(
+                Arrays.asList("referral_register", "F03a", "F03b", "invite_milestone")));
+
+        // 口径:member_id + type=earn + ref_type 白名单
+        @SuppressWarnings("unchecked")
+        ArgumentCaptor<LambdaQueryWrapper<CfBalanceLog>> captor =
+                ArgumentCaptor.forClass(LambdaQueryWrapper.class);
+        verify(cfBalanceLogMapper).selectList(captor.capture());
+        String sql = captor.getValue().getSqlSegment().toUpperCase();
+        assertTrue(sql.contains("MEMBER_ID"), "应按 member_id 过滤,实际: " + sql);
+        assertTrue(sql.contains("REF_TYPE"), "应按 ref_type 白名单过滤,实际: " + sql);
+    }
+
+    @Test
+    void promotionEarnings_鉴权流_用户无家庭成员返回404且不查流水() {
+        when(familyMemberMapper.selectOne(any())).thenReturn(null);
+
+        Result<Map<String, Object>> r = controller.promotionEarnings(99L, null);
+
+        assertEquals(404, r.getCode());
+        assertTrue(r.getMessage().contains("推广收益"), "错误信息应指明推广收益,实际: " + r.getMessage());
+        verify(cfBalanceLogMapper, never()).selectList(any());
+    }
+
+    @Test
+    void promotionEarnings_无非推广流水_收益为0() {
+        when(familyMemberMapper.selectOne(any())).thenReturn(member(42L, 7L, 9L, "妈妈"));
+        when(cfBalanceLogMapper.selectList(any())).thenReturn(Collections.emptyList());
+
+        Result<Map<String, Object>> r = controller.promotionEarnings(7L, null);
+
+        assertEquals(200, r.getCode());
+        assertEquals(0, r.getData().get("totalEarned"));
+    }
+}

+ 105 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/CfBalanceStatsTest.java

@@ -0,0 +1,105 @@
+package com.etotem.cfc.unit;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.dto.CfBalanceView;
+import com.etotem.cfc.entity.CfBalanceLog;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+
+import java.util.Arrays;
+import java.util.Calendar;
+import java.util.Collections;
+import java.util.Date;
+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.ArgumentMatchers.anyLong;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * {@code GET /api/cf/stats} 契约回归:今日 / 本月获得 + 累计获得(cf_balance.total_earned)。
+ * 正常流 + 鉴权流 + 空流水 + currentMemberId 优先,共 4 例。
+ */
+class CfBalanceStatsTest extends AbstractCfBalanceStatsTestBase {
+
+    @Test
+    @SuppressWarnings("unchecked")
+    void stats_正常流_今日与本月获得按流水汇总() {
+        when(familyMemberMapper.selectOne(any())).thenReturn(member(42L, 7L, 9L, "妈妈"));
+        when(cfBalanceService.getBalance(42L)).thenReturn(view(300, 900));
+
+        Calendar cal = Calendar.getInstance();
+        cal.set(Calendar.HOUR_OF_DAY, 0);
+        cal.set(Calendar.MINUTE, 0);
+        cal.set(Calendar.SECOND, 0);
+        cal.set(Calendar.MILLISECOND, 0);
+        Date startOfDay = cal.getTime();
+        // 今天的一笔(100)+ 本月早些时候的一笔(50)
+        Date earlierThisMonth = new Date(startOfDay.getTime() - 24L * 60 * 60 * 1000);
+        when(cfBalanceLogMapper.selectList(any())).thenReturn(Arrays.asList(
+                earnLog(1L, 100, "F02", new Date(startOfDay.getTime() + 60_000L)),
+                earnLog(2L, 50, "F24", earlierThisMonth)));
+
+        Result<Map<String, Object>> r = controller.stats(7L, null);
+
+        assertEquals(200, r.getCode());
+        assertEquals(100, r.getData().get("todayEarned"));
+        assertEquals(150, r.getData().get("monthEarned"));
+        assertEquals(900, r.getData().get("totalEarned"));
+        assertEquals(300, r.getData().get("available"));
+
+        // 口径:只统计 type=earn、且不早于本月 1 日
+        ArgumentCaptor<LambdaQueryWrapper<CfBalanceLog>> captor =
+                ArgumentCaptor.forClass(LambdaQueryWrapper.class);
+        verify(cfBalanceLogMapper).selectList(captor.capture());
+        String sql = captor.getValue().getSqlSegment().toUpperCase();
+        assertTrue(sql.contains("MEMBER_ID"), "应按 member_id 过滤,实际: " + sql);
+        assertTrue(sql.contains("TYPE"), "应按 type 过滤,实际: " + sql);
+        assertTrue(sql.contains("CREATED_AT"), "应按 created_at 限定本月,实际: " + sql);
+    }
+
+    @Test
+    void stats_鉴权流_用户无家庭成员返回404且不查流水() {
+        when(familyMemberMapper.selectOne(any())).thenReturn(null);
+
+        Result<Map<String, Object>> r = controller.stats(99L, null);
+
+        assertEquals(404, r.getCode());
+        assertTrue(r.getMessage().contains("CF 统计"), "错误信息应指明 CF 统计,实际: " + r.getMessage());
+        verify(cfBalanceService, never()).getBalance(anyLong());
+        verify(cfBalanceLogMapper, never()).selectList(any());
+    }
+
+    @Test
+    void stats_空流水_统计归零但累计取账本快照() {
+        when(familyMemberMapper.selectOne(any())).thenReturn(member(42L, 7L, 9L, "妈妈"));
+        when(cfBalanceService.getBalance(42L)).thenReturn(view(0, 0));
+        when(cfBalanceLogMapper.selectList(any())).thenReturn(Collections.emptyList());
+
+        Result<Map<String, Object>> r = controller.stats(7L, null);
+
+        assertEquals(200, r.getCode());
+        assertEquals(0, r.getData().get("todayEarned"));
+        assertEquals(0, r.getData().get("monthEarned"));
+        assertEquals(0, r.getData().get("totalEarned"));
+        assertEquals(0, r.getData().get("available"));
+    }
+
+    @Test
+    void stats_currentMemberId优先_跳过user_id反查() {
+        when(cfBalanceService.getBalance(88L)).thenReturn(view(10, 20));
+        when(cfBalanceLogMapper.selectList(any())).thenReturn(Collections.emptyList());
+
+        Result<Map<String, Object>> r = controller.stats(7L, 88L);
+
+        assertEquals(200, r.getCode());
+        // JwtInterceptor 解析出的 currentMemberId 优先,不再走 user_id → member 反查
+        verify(familyMemberMapper, never()).selectOne(any());
+        verify(cfBalanceService).getBalance(88L);
+    }
+}

+ 3 - 3
cfc-frontend/pages/profile-main/profile.vue

@@ -366,7 +366,7 @@ import {
   getChildren, getFamilyMemberList,
   getTodayTasksByCategory, getChallengeList, getMyMembership,
   verifyPassword, getPointsBalance, getUserInfo,
-  cartCount, getOrderCounts, getReferralSummary,
+  cartCount, getOrderCounts, getCfPromotionEarnings,
   getProfileStats, getMyReferrer, getVendorTeamList, getVendorHierarchyInfo, getMyCoupons,
   getTeacherInfo, getTeacherPendingTasks, getTeacherUnreadCount,
   getReferralCode, extractReferralCode, getShareQrCode, getEnergySandbox,
@@ -624,9 +624,9 @@ export default {
 
     loadReferralEarnings() {
       var self = this
-      getReferralSummary().then(function(res) {
+      getCfPromotionEarnings().then(function(res) {
         if (res && res.code === 200 && res.data) {
-          self.referralEarnings = res.data.totalEarnings || 0
+          self.referralEarnings = res.data.totalEarned || 0
         }
       }).catch(function() {})
     },

+ 25 - 174
cfc-frontend/pages/promotion/index.vue

@@ -5,19 +5,19 @@
     <view class="family-earnings-card" v-if="familySummary">
       <view class="fe-header">
         <view class="fe-title-row">
-          <text class="fe-title">🏠 家庭公共收益</text>
+          <text class="fe-title">🏠 家庭CF总览</text>
           <text class="fe-badge" v-if="isAdmin">管理员</text>
         </view>
-        <text class="fe-subtitle">家庭成员共同努力的成果</text>
+        <text class="fe-subtitle">家庭成员 CF 贡献与余额</text>
       </view>
       <view class="fe-grid">
         <view class="fe-item">
           <text class="fe-value orange">{{ cfVal(familySummary.totalEarned) }}</text>
-          <text class="fe-label">累计推荐CF</text>
+          <text class="fe-label">家庭累计CF</text>
         </view>
         <view class="fe-item">
           <text class="fe-value blue">{{ cfVal(familySummary.availableAmount) }}</text>
-          <text class="fe-label">可支配CF</text>
+          <text class="fe-label">家庭可用CF</text>
         </view>
         <view class="fe-item">
           <text class="fe-value green">{{ cfVal(familySummary.withdrawnAmount) }}</text>
@@ -25,14 +25,9 @@
         </view>
         <view class="fe-item">
           <text class="fe-value purple">{{ cfVal(familySummary.distributedAmount) }}</text>
-          <text class="fe-label">已分配CF</text>
+          <text class="fe-label">已兑换CF</text>
         </view>
       </view>
-
-      <!-- 管理员操作按钮(仅管理员可见) -->
-      <view class="fe-actions" v-if="isAdmin">
-        <button class="fe-btn fe-btn-distribute" @click="showDistributeSheet = true">分配收益</button>
-      </view>
     </view>
 
     <!-- 成员贡献榜 -->
@@ -54,16 +49,12 @@
           <view class="member-info">
             <text class="member-name">{{ m.nickname || '用户' }}</text>
             <text class="member-role-tag" v-if="m.isAdmin">管理员</text>
-            <text class="member-balance-tag" v-if="m.canUseFamilyBalance">池可用</text>
-            <text class="member-balance-tag disabled-tag" v-else>池关闭</text>
           </view>
           <view class="member-amounts">
-            <text class="member-amount allocated">+{{ cfVal(m.allocatedAmount) }}</text>
-            <text class="member-amount consumed">-{{ cfVal(m.consumedAmount) }}</text>
-            <text class="member-amount available">={{ cfVal(m.availableAmount) }}</text>
+            <text class="member-amount allocated">累计 {{ cfVal(m.allocatedAmount) }}</text>
+            <text class="member-amount consumed">消费 {{ cfVal(m.consumedAmount) }}</text>
+            <text class="member-amount available">可用 {{ cfVal(m.availableAmount) }}</text>
           </view>
-          <!-- 管理员可切换成员池权限 -->
-          <switch v-if="isAdmin && !m.isAdmin" class="member-switch" :checked="m.canUseFamilyBalance" @change="toggleMemberAccess(m)" :color="primaryColor"></switch>
         </view>
       </view>
     </view>
@@ -84,15 +75,15 @@
     <!-- 统计卡片 -->
     <view class="stats-cards">
       <view class="stat-card today-card">
-        <text class="stat-value">{{ stats.todayCommission || 0 }}</text>
+        <text class="stat-value">{{ stats.todayEarned || 0 }}</text>
         <text class="stat-label">今日CF</text>
       </view>
       <view class="stat-card month-card">
-        <text class="stat-value">{{ stats.monthCommission || 0 }}</text>
+        <text class="stat-value">{{ stats.monthEarned || 0 }}</text>
         <text class="stat-label">本月CF</text>
       </view>
       <view class="stat-card total-card">
-        <text class="stat-value">{{ stats.totalCommission || 0 }}</text>
+        <text class="stat-value">{{ stats.totalEarned || 0 }}</text>
         <text class="stat-label">累计CF</text>
       </view>
     </view>
@@ -167,53 +158,26 @@
     <view style="height:40rpx"></view>
     </scroll-view>
 
-    <!-- iOS 修复:position: fixed 不能嵌套在 scroll-view 内,会导致固定定位失效。已移至 scroll-view 后 -->
-    <view class="sheet-mask" v-if="showDistributeSheet" @click="showDistributeSheet = false">
-      <view class="sheet-content" @click.stop>
-        <text class="sheet-title">分配收益</text>
-        <text class="sheet-hint">选择成员并输入分配CF值</text>
-        <picker class="sheet-picker" mode="selector" :range="memberOptions" :value="distributeMemberIdx" @change="onDistributeMemberChange">
-          <text>{{ distributeMemberIdx >= 0 ? memberOptions[distributeMemberIdx] : '选择成员' }}</text>
-        </picker>
-        <input class="sheet-input" type="digit" v-model="distributeAmount" placeholder="输入分配CF值" />
-        <view class="sheet-actions">
-          <button class="sheet-cancel" @click="showDistributeSheet = false">取消</button>
-          <button class="sheet-confirm" @click="doDistribute" :disabled="distributeMemberIdx < 0 || !distributeAmount || distributeAmount <= 0">确认分配</button>
-        </view>
-      </view>
-    </view>
-
   </view>
 </template>
 
 <script>
-import { BrandColors } from '@/utils/brand-colors.js'
-import { getReferralSummary, getCfSummary, getFamilyEarningsSummary, getFamilyEarningsMembers, getFamilyEarningsRecords, distributeToMember, toggleMemberBalance, withdrawFamilyEarnings, getReferralCode, extractReferralCode } from '../../utils/api.js'
+import { getCfBalance, getCfStats, getCfFamilySummary, getReferralCode, extractReferralCode } from '../../utils/api.js'
 import fontScaleMixin from '@/mixins/font-scale.js'
 
 export default {
   mixins: [fontScaleMixin],
   data() {
     return {
-      primaryColor: BrandColors.primary,
-      totalEarnings: '0.00',
-      availableAmount: '0.00',
       summary: null,
       stats: {},
       funnelData: {},
       funnelSteps: [],
-      // 家庭收益
+      // 家庭 CF 总览
       familySummary: null,
       members: [],
       membersExpanded: false,
       showAllRanks: false,
-      // 弹窗
-      showWithdrawSheet: false,
-      showDistributeSheet: false,
-      withdrawAmount: '',
-      distributeAmount: '',
-      distributeMemberIdx: -1,
-      memberOptions: [],
       // 分享推广码(用于右上角菜单分享)
       shareReferralCode: ''
     }
@@ -281,74 +245,34 @@ export default {
     },
     async loadData() {
       try {
-        var summaryRes = await getReferralSummary()
-        if (summaryRes.data) {
-          this.totalEarnings = summaryRes.data.totalEarnings || '0.00'
-        }
-      } catch (e) {
-        console.error('获取邀请统计失败', e)
-      }
-      try {
-        var comRes = await getCfSummary()
-        if (comRes.data) {
-          this.summary = comRes.data
-          this.availableAmount = comRes.data.available || '0.00'
+        var res = await getCfBalance()
+        if (res && res.data) {
+          this.summary = res.data
         }
       } catch (e) {
         console.error('获取 CF 总览失败', e)
       }
     },
     async loadFamilyData() {
-      if (this.isChild) {
-        // 成员只读:仅加载概要,不加载管理员功能
-        try {
-          var sRes = await getFamilyEarningsSummary()
-          if (sRes.data) {
-            this.familySummary = sRes.data
-            this.members = sRes.data.members || []
-          }
-        } catch (e) {
-          console.error('获取家庭收益概览失败', e)
-        }
-        return
-      }
       try {
-        var sRes = await getFamilyEarningsSummary()
-        if (sRes.data) {
+        var sRes = await getCfFamilySummary()
+        if (sRes && sRes.data) {
           this.familySummary = sRes.data
           this.members = sRes.data.members || []
-          // 构建picker选项
-          var opts = []
-          var arr = this.members
-          for (var i = 0; i < arr.length; i++) {
-            opts.push((arr[i].nickname || '用户' + arr[i].userId) + ' (余额:' + this.cfVal(arr[i].availableAmount) + ' CF)')
-          }
-          this.memberOptions = opts
         }
       } catch (e) {
-        console.error('获取家庭收益概览失败', e)
+        console.error('获取家庭 CF 总览失败', e)
       }
     },
-    loadStats() {
-      var self = this
-      var token = uni.getStorageSync('token')
-      var baseUrl = ''
+    async loadStats() {
       try {
-        var config = require('../../config.js')
-        baseUrl = config.default.baseUrl || config.baseUrl || ''
+        var res = await getCfStats()
+        if (res && res.data) {
+          this.stats = res.data
+        }
       } catch (e) {
-        baseUrl = ''
+        console.error('获取 CF 统计失败', e)
       }
-      uni.request({
-        url: baseUrl + '/api/commission/stats',
-        method: 'POST',
-        header: { 'Authorization': 'Bearer ' + token },
-        success: function(res) {
-          if (res.data && res.data.code === 200) {
-            self.stats = res.data.data || {}
-          }
-        }
-      })
     },
     loadFunnelData() {
       var self = this
@@ -390,79 +314,6 @@ export default {
       if (isNaN(num)) return '0'
       return String(num)
     },
-    // 管理员操作
-    toggleMemberAccess(m) {
-      var self = this
-      var enabled = !m.canUseFamilyBalance
-      uni.showLoading({ title: '操作中...' })
-      toggleMemberBalance({ userId: m.userId, enabled: enabled }).then(function(res) {
-        uni.hideLoading()
-        if (res.code === 200) {
-          m.canUseFamilyBalance = enabled
-          uni.showToast({ title: '操作成功', icon: 'success' })
-        } else {
-          uni.showToast({ title: res.message || '操作失败', icon: 'none' })
-        }
-      }).catch(function(e) {
-        uni.hideLoading()
-        uni.showToast({ title: '操作失败', icon: 'none' })
-      })
-    },
-    onDistributeMemberChange(e) {
-      this.distributeMemberIdx = e.detail.value
-    },
-    doDistribute() {
-      var idx = this.distributeMemberIdx
-      if (idx < 0 || !this.members[idx]) {
-        uni.showToast({ title: '请选择成员', icon: 'none' })
-        return
-      }
-      var amount = Number(this.distributeAmount)
-      if (!amount || amount <= 0) {
-        uni.showToast({ title: '请输入有效金额', icon: 'none' })
-        return
-      }
-      var self = this
-      uni.showLoading({ title: '分配中...' })
-      distributeToMember({ userId: this.members[idx].userId, amount: amount }).then(function(res) {
-        uni.hideLoading()
-        if (res.code === 200) {
-          uni.showToast({ title: '分配成功', icon: 'success' })
-          self.showDistributeSheet = false
-          self.distributeAmount = ''
-          self.distributeMemberIdx = -1
-          self.loadFamilyData()
-        } else {
-          uni.showToast({ title: res.message || '分配失败', icon: 'none' })
-        }
-      }).catch(function(e) {
-        uni.hideLoading()
-        uni.showToast({ title: '分配失败', icon: 'none' })
-      })
-    },
-    doWithdraw() {
-      var amount = Number(this.withdrawAmount)
-      if (!amount || amount <= 0) {
-        uni.showToast({ title: '请输入有效金额', icon: 'none' })
-        return
-      }
-      var self = this
-      uni.showLoading({ title: '提现中...' })
-      withdrawFamilyEarnings({ amount: amount }).then(function(res) {
-        uni.hideLoading()
-        if (res.code === 200) {
-          uni.showToast({ title: '提现申请已提交', icon: 'success' })
-          self.showWithdrawSheet = false
-          self.withdrawAmount = ''
-          self.loadFamilyData()
-        } else {
-          uni.showToast({ title: res.message || '提现失败', icon: 'none' })
-        }
-      }).catch(function(e) {
-        uni.hideLoading()
-        uni.showToast({ title: '提现失败', icon: 'none' })
-      })
-    },
     goRecords() {
       uni.navigateTo({ url: '/pages/promotion/records' })
     },

+ 4 - 0
cfc-frontend/utils/api.js

@@ -3168,6 +3168,10 @@ export const exchangeCouponByCf = (data) => request('/api/family-platform/exchan
 export const getCfBalance = () => request('/api/cf/balance', 'GET', {})
 export const getCfLogs = (params) => request('/api/cf/logs', 'GET', params || { page: 1, size: 20 })
 export const getFamilyCoupons = () => request('/api/cf/family-coupons', 'GET', {})
+// CF 周期统计(今日/本月/累计获得)与家庭 CF 总览 / 推广类 CF 收益
+export const getCfStats = () => request('/api/cf/stats', 'GET', {})
+export const getCfFamilySummary = () => request('/api/cf/family-summary', 'GET', {})
+export const getCfPromotionEarnings = () => request('/api/cf/promotion-earnings', 'GET', {})
 
 // ===== 站内通知 =====
 export const getNotificationList = () => request('/api/notification/list', 'POST', {})

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

@@ -71,7 +71,7 @@ find cfc-backend/src/main/java -name "*XxxService.java" -o -name "*XxxController
 | `StatsController` | `/api/stats` | 统计 | — |
 | `CfCommissionController` | `/api/commission/cf` | CF 分佣(团队规模/比例/钱包/流水) | — |
 | `CfTransferController` | `/api/cf/transfer` | CF 成员间转让 | — |
-| `CfBalanceController` | `/api/cf` | C 端 CF 查询(余额快照/流水/家庭券,只读) | F-7a |
+| `CfBalanceController` | `/api/cf` | C 端 CF 查询(余额快照/流水/周期统计/家庭 CF 总览/推广收益/家庭券,只读) | F-7a |
 | `AdminCfRateTierController` | `/api/admin/cf-rate-tier` | CF 返佣阶梯配置(admin) | — |
 | `ContactController` | `/api/contact` | 联系人 CRUD/互动/邀请入家庭 | — |
 | `ContactMatchController` | `/api/contact/match` | 联系人对接(send/accept/reject/列表) | — |
@@ -2315,10 +2315,20 @@ W0.2 双配置中心合并:`product_config` 已并入 `service_config`(唯
 |---|---|
 | `GET /api/cf/balance` | 我的 CF 值快照。按登录用户解析 memberId 后读 `cf_balance`,返回 `CfBalanceView`:`memberId` / `available`(可用) / `frozen`(冻结) / `totalEarned`(累计获得) / `totalWithdrawn`(已提现) / `exchanged`(已兑换消费)。无 `cf_balance` 记录时返回全 0 |
 | `GET /api/cf/logs?page=1&size=20` | 我的 CF 流水分页(时间倒序),复用 `CfBalanceService.getLogs(memberId, page, size)`,输出转 `CfBalanceLogVO`:`id` / `type`(earn/spend/freeze/unfreeze/withdraw/adjust/skip) / `refType`(规则编码或迁移标识) / `amount`(带符号变动) / `balanceAfter`(变动后可用余额) / `remark` / `createdAt`(ISO 8601)。返回 MyBatis-Plus `Page` 结构(current/size/total/pages/records) |
+| `GET /api/cf/stats` | 我的 CF 周期统计。读 `cf_balance` 快照 + `cf_balance_log`(`member_id` + `type='earn'` + 不早于本月 1 日)汇总,返回 `todayEarned`(今日获得) / `monthEarned`(本月获得) / `totalEarned`(累计获得,取 `cf_balance.total_earned`) / `available`(可用) |
+| `GET /api/cf/family-summary` | 家庭 CF 总览(成员维度,**数据源为实时账本 `cf_balance`**)。按登录成员 `family_id` 聚合全家 `total_earned` / `available` / `withdrawn` / `exchanged`,并输出成员贡献榜 `FamilyEarningsSummaryDTO`:`familyId` / `totalEarned` / `availableAmount` / `withdrawnAmount` / `distributedAmount` / `members[]`(`userId` / `nickname` / `avatar` / `allocatedAmount` / `availableAmount` / `consumedAmount` / `isAdmin` / `canUseFamilyBalance`,按贡献倒序)。**替代已停写的 `family_earnings` 旧账本读接口** `POST /api/earnings/family/summary`(后者只读历史表,数据不再实时更新) |
+| `GET /api/cf/promotion-earnings` | 推广类 CF 收益。统计本人当前成员 `cf_balance_log` 中 `type='earn'` 且 `ref_type` ∈ {`referral_register`(F24 推荐注册) / `F03a`(直接销售奖) / `F03b`(间接销售奖) / `invite_milestone`(F11 邀请里程碑)} 的流水,返回 `totalEarned`(合计) / `refTypes`(计入的规则编码清单)。**替代** `POST /api/invite/summary`(旧邀请表口径)作为推广收益展示数据源 |
 | `GET /api/cf/family-coupons` | 家庭共享优惠券列表(N3 口径)。复用 `CouponService.listMyCoupons(userId)`:按登录用户所属家庭查 `family_coupon` + `coupon` 联合数据(券家庭化全链路已切换至 `family_coupon`,`user_coupon` 为只读历史表),返回 `userCouponId` / `couponId` / `name`(券名) / `type` / `value`(面额,分) / `discountRate` / `minSpend` / `applicableTo` / `status`(AVAILABLE/USED/EXPIRED/DISABLED) / `validFrom` / `validUntil`(有效期) / `receivedAt` / `usedAt` / `orderId` / `productId`,家庭内成员共享可见 |
 
 - 实现走统一账本 `CfBalanceService` / `CouponService`,本控制器不直接写库、不提供任何写接口。
+- `userId → memberId` 解析优先使用 `JwtInterceptor` 解析出的 `currentMemberId`,缺失时才回退到 `user_id` 匹配 + `LIMIT 1`(保证无家庭用户兼容)。
 - 流水/余额响应结构单测:`cfc-backend/src/test/java/com/etotem/cfc/unit/CfBalanceControllerTest.java`(memberId 解析命中/未命中 + balance/logs 字段映射)。
+- 三端点(stats / family-summary / promotion-earnings)契约回归:`cfc-backend/src/test/java/com/etotem/cfc/unit/CfBalanceStatsTest.java`(每端点正常流 + 鉴权流 ≥2 例)。
+
+> ⚠️ **变更记录 2026-11-06(B-11 处置)**:`44b2f0d42`(2026-11-05 00:31 `chore(sync): 工作区遗留未提交 WIP 收尾同步`)与 `3036a0bd4`(2026-11-05 08:34)曾把 `CfBalanceController.java`、`cfc-frontend/pages/promotion/index.vue`、`cfc-frontend/utils/api.js`、`cfc-frontend/pages/profile-main/profile.vue`
+> **整文件回滚到 `dfc78e9d3`(2026-11-03 `fix(cf): 财富中心/推广收益改读实时CF账本`)之前的版本**(`git diff dfc78e9d3^ 44b2f0d42 -- <这4个文件>` 为空,逐字节相同),
+> 导致本段三个端点(`/api/cf/stats`、`/api/cf/family-summary`、`/api/cf/promotion-earnings`)+ 前端 3 个封装 + `currentMemberId` 成员解析被静默删除,
+> 前端推广页/个人页退回读停写的 `family_earnings` / 邀请表旧口径。**经判定为误覆盖(非有意精简)**,已恢复至 `dfc78e9d3` 语义并补上述契约测试。
 
 ### 4.56 管理端-素材库(`/api/admin/file-record/*`)