Przeglądaj źródła

feat(team.star.digest): 月度星级简报 StarDigestService (S-cfc-70)

能力键 team.star.digest(规格 v0.7 §4.3.1 ③④ / §12-T8)TDD-GREEN 实现:

- 新增 com.etotem.cfc.service.StarDigestService
- digestTrend:升(+1)/持平(0)/降(-1) 三态分类;首期无上月快照(previous<=0)按持平,不虚报升降
- upgradeMessage:恭喜 + 新星级 + 解锁分佣份数(每层按星级拿份数)+ 星级权益
- downgradeMessage:滚动窗口滑出原因 + 距原级需补分
- flatMessage:距下一星差距 + 本月行动建议(复用 §4.3.1 ② 250/200/10 换算);六星顶格不虚构下一档
- starBenefits:星级徽章/培训与专家课优先/带教/领队/年度表彰,高星只多不少
- digestMonthly:读 team_star_snapshot 本月 vs 上月快照(uk_user_period)按三态出稿

team_star_snapshot 表契约已在库内(迁移461 + schema.sql uk_user_period),本次未新增 DB 迁移。

验证:mvn test -DskipTests=false -Dtest=TeamStarDigestContractTest → Tests run: 14, Failures: 0, Errors: 0
iwt 1 tydzień temu
rodzic
commit
0e9186d726

+ 288 - 0
cfc-backend/src/main/java/com/etotem/cfc/service/StarDigestService.java

@@ -0,0 +1,288 @@
+package com.etotem.cfc.service;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.etotem.cfc.entity.TeamStarSnapshot;
+import com.etotem.cfc.mapper.TeamStarSnapshotMapper;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+
+import javax.annotation.Resource;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Calendar;
+import java.util.List;
+
+/**
+ * 月度星级简报生成组件(能力键 {@code team.star.digest},§4.3.1 ③④ / §12-T8)。
+ *
+ * <p>规格:{@code docs/superpowers/specs/2026-11-07-referral-team-profit-sharing.md}
+ * §4.3.1 ③ 月度星级简报(每月 1 日重评后主动推送)+ ④ 星级权益可见;数据源为
+ * §7.6 {@code team_star_snapshot} 本月 vs 上月快照(唯一键 {@code uk_user_period})。</p>
+ *
+ * <p><b>三态简报</b>(§4.3.1 ③):</p>
+ * <ul>
+ *   <li>升星:恭喜 + 新星级 + 解锁分佣份数(每层按星级拿份数,§4.3 八份制)+ 星级权益</li>
+ *   <li>降星:提示 + 原因(滚动窗口滑出)+ 需补多少分回原级</li>
+ *   <li>持平:距下一星差多少 + 本月行动建议(复用 §4.3.1 ② 差距→行动换算)</li>
+ * </ul>
+ *
+ * <p><b>推送口径</b>:每月 1 日 00:30 重评落快照后触发({@code TeamProfitCronTask#reevaluateMonthlyStars}),
+ * 复用微信订阅消息模板;本组件只负责按快照对比出稿(纯文本),发送由通知渠道接入。</p>
+ *
+ * <p><b>实现说明</b>:出稿方法不依赖数据库({@link #digestTrend} / {@link #upgradeMessage} /
+ * {@link #downgradeMessage} / {@link #flatMessage} / {@link #starBenefits} 均为纯计算),
+ * 仅 {@link #digestMonthly} 需要读取快照表;因此在无 Spring 容器的契约单测中也能直接实例化调用。</p>
+ */
+@Slf4j
+@Service
+public class StarDigestService {
+
+    /** 能力键(任务 S-cfc-47 / 契约 TeamStarDigestContractTest)。 */
+    public static final String CAPABILITY_KEY = "team.star.digest";
+
+    /** 业绩分门槛换算:直接服务 250 分/次、团队带教 200 分/次、推荐消费 10 分/百元(§4.3.1 ②)。 */
+    private static final int SCORE_PER_DIRECT_SERVICE = 250;
+    private static final int SCORE_PER_TEAM_COACHING = 200;
+    private static final int SCORE_PER_HUNDRED_YUAN_REFERRAL = 10;
+
+    /** 六星为最高档(§4.3 顶流团队长)。 */
+    private static final int TOP_STAR = StarScoreCalculator.MAX_STAR;
+
+    /** 权益清单公共项(§4.3.1 ④,高星只多不少)。 */
+    private static final String BENEFIT_BADGE = "星级徽章";
+    private static final String BENEFIT_TRAINING = "培训与专家课优先";
+    private static final String BENEFIT_COACHING = "带教资格";
+    private static final String BENEFIT_LEADING = "领队资格";
+    private static final String BENEFIT_ANNUAL_AWARD = "年度表彰";
+
+    @Resource
+    private TeamStarSnapshotMapper teamStarSnapshotMapper;
+
+    @Resource
+    private StarScoreCalculator starScoreCalculator;
+
+    /** 无容器场景(契约单测)下的纯计算兜底;Spring 场景使用注入实例。 */
+    private final StarScoreCalculator fallbackCalculator = new StarScoreCalculator();
+
+    private StarScoreCalculator calculator() {
+        return starScoreCalculator != null ? starScoreCalculator : fallbackCalculator;
+    }
+
+    // ==================== 趋势分类(§4.3.1 ③) ====================
+
+    /**
+     * 升/降/持平分类:+1=升星 / 0=持平 / -1=降星。
+     *
+     * <p>首期无上月快照({@code previousStarLevel <= 0})按持平处理,不虚报升/降。</p>
+     */
+    public int digestTrend(int currentStarLevel, int previousStarLevel) {
+        if (previousStarLevel <= 0) {
+            return 0;
+        }
+        int current = clampStar(currentStarLevel);
+        int previous = clampStar(previousStarLevel);
+        if (current > previous) {
+            return 1;
+        }
+        if (current < previous) {
+            return -1;
+        }
+        return 0;
+    }
+
+    // ==================== 三态稿件(§4.3.1 ③) ====================
+
+    /**
+     * 升星稿件:恭喜 + 新星级 + 解锁分佣份数(每层按星级拿份数)+ 星级权益(§4.3.1 ③④)。
+     */
+    public String upgradeMessage(long userId, int newStarLevel) {
+        int star = clampStar(newStarLevel);
+        StringBuilder sb = new StringBuilder();
+        sb.append("【星级简报】恭喜!您本月升为 ").append(star).append("★(").append(starName(star)).append(")。");
+        sb.append("解锁分佣份数:每层按 ").append(star).append(" 份计算(八份制,单层最多 6 份)。");
+        sb.append("星级权益:").append(joinBenefits(starBenefits(star))).append("。");
+        sb.append("继续带教与推荐,星级越高份数越多。");
+        return sb.toString();
+    }
+
+    /**
+     * 降星稿件:提示 + 原因(滚动窗口滑出)+ 需补多少分回原级(§4.3.1 ③)。
+     */
+    public String downgradeMessage(long userId, int oldStarLevel, int currentStarLevel, int currentScore) {
+        int oldStar = clampStar(oldStarLevel);
+        int currentStar = clampStar(currentStarLevel);
+        int score = Math.max(currentScore, 0);
+        int gap = Math.max(calculator().thresholdOfStar(oldStar) - score, 0);
+        StringBuilder sb = new StringBuilder();
+        sb.append("【星级简报】您本月星级由 ").append(oldStar).append("★ 调整为 ")
+                .append(currentStar).append("★。");
+        sb.append("原因:滚动 12 个月窗口滑出,早期业绩不再计入当期业绩分。");
+        if (gap > 0) {
+            sb.append("当前业绩分 ").append(score).append(",距回到 ").append(oldStar)
+                    .append("★ 还差 ").append(gap).append(" 分,需补足后可回原级。");
+        } else {
+            sb.append("当前业绩分 ").append(score).append(" 已达标,需补足团队直推 ≥1 后即可回原级。");
+        }
+        sb.append("本月行动建议:").append(actionAdvice(gap)).append("。");
+        return sb.toString();
+    }
+
+    /**
+     * 持平稿件:距下一档差多少 + 本月行动建议(§4.3.1 ② 换算)。
+     *
+     * <p>六星已顶格,不再虚构「下一星」差距(§4.3 六星=最高档)。</p>
+     */
+    public String flatMessage(long userId, int currentStarLevel, int currentScore) {
+        int star = clampStar(currentStarLevel);
+        int score = Math.max(currentScore, 0);
+        StringBuilder sb = new StringBuilder();
+        sb.append("【星级简报】您本月保持 ").append(star).append("★(").append(starName(star)).append(")。");
+        if (star >= TOP_STAR) {
+            sb.append("已是六星顶格(最高档),本月行动建议:")
+                    .append("稳住团队服务与推荐消费,保持 6 份分佣与顶流权益。");
+            return sb.toString();
+        }
+        int gap = Math.max(calculator().thresholdOfStar(star + 1) - score, 0);
+        sb.append("当前业绩分 ").append(score).append(",距下一星(").append(star + 1)
+                .append("★)还差 ").append(gap).append(" 分");
+        if (gap == 0) {
+            sb.append("(业绩分已达标,待升级双门槛:团队直推 ≥1)");
+        }
+        sb.append("。");
+        sb.append("本月行动建议:").append(actionAdvice(gap)).append("。");
+        return sb.toString();
+    }
+
+    // ==================== 星级权益(§4.3.1 ④) ====================
+
+    /**
+     * 该星级的可感知权益清单(星级徽章 / 培训与专家课优先 / 带教与领队资格 / 年度表彰),
+     * 高星权益只多不少。
+     */
+    public List<String> starBenefits(int starLevel) {
+        int star = clampStar(starLevel);
+        List<String> benefits = new ArrayList<>();
+        benefits.add(BENEFIT_BADGE);
+        if (star >= 2) {
+            benefits.add(BENEFIT_TRAINING);
+        }
+        if (star >= 3) {
+            benefits.add(BENEFIT_COACHING);
+        }
+        if (star >= 4) {
+            benefits.add(BENEFIT_LEADING);
+        }
+        if (star >= 5) {
+            benefits.add(BENEFIT_ANNUAL_AWARD);
+        }
+        return benefits;
+    }
+
+    // ==================== 月度简报入口(§12-T8) ====================
+
+    /**
+     * 月度简报正文入口:取 {@code team_star_snapshot} 本月 vs 上月快照,按三态出稿。
+     *
+     * @param userId 成员用户 ID
+     * @param period 周期 {@code YYYYMM}(为空时取当前月)
+     * @return 简报正文;本月无快照时返回待重评提示
+     */
+    public String digestMonthly(long userId, String period) {
+        String currentPeriod = (period == null || period.trim().isEmpty()) ? currentPeriod() : period.trim();
+        TeamStarSnapshot current = findSnapshot(userId, currentPeriod);
+        if (current == null) {
+            return "【星级简报】" + currentPeriod + " 暂无您的星级快照,待每月 1 日星级重评后生成。";
+        }
+        TeamStarSnapshot previous = findSnapshot(userId, previousPeriod(currentPeriod));
+        int currentStar = current.getStarLevel() == null ? StarScoreCalculator.MIN_STAR : current.getStarLevel();
+        int previousStar = previous == null || previous.getStarLevel() == null
+                ? 0 : previous.getStarLevel();
+        int score = current.getScore() == null ? 0 : (int) Math.min(current.getScore(), Integer.MAX_VALUE);
+
+        int trend = digestTrend(currentStar, previousStar);
+        if (trend > 0) {
+            return upgradeMessage(userId, currentStar);
+        }
+        if (trend < 0) {
+            return downgradeMessage(userId, previousStar, currentStar, score);
+        }
+        return flatMessage(userId, currentStar, score);
+    }
+
+    // ==================== 内部辅助 ====================
+
+    private TeamStarSnapshot findSnapshot(long userId, String period) {
+        if (teamStarSnapshotMapper == null || period == null) {
+            return null;
+        }
+        try {
+            return teamStarSnapshotMapper.selectOne(new LambdaQueryWrapper<TeamStarSnapshot>()
+                    .eq(TeamStarSnapshot::getUserId, userId)
+                    .eq(TeamStarSnapshot::getPeriod, period)
+                    .last("LIMIT 1"));
+        } catch (Exception e) {
+            log.warn("星级简报读取快照失败(userId={}, period={}): {}", userId, period, e.getMessage());
+            return null;
+        }
+    }
+
+    /** 上一期周期(YYYYMM);无法解析时返回 null(按首期持平处理)。 */
+    private String previousPeriod(String period) {
+        if (period == null || period.length() < 6) {
+            return null;
+        }
+        try {
+            int year = Integer.parseInt(period.substring(0, 4));
+            int month = Integer.parseInt(period.substring(4, 6));
+            if (month < 1 || month > 12) {
+                return null;
+            }
+            if (month == 1) {
+                return String.format("%04d12", year - 1);
+            }
+            return String.format("%04d%02d", year, month - 1);
+        } catch (NumberFormatException e) {
+            return null;
+        }
+    }
+
+    private String currentPeriod() {
+        Calendar cal = Calendar.getInstance();
+        return String.format("%04d%02d", cal.get(Calendar.YEAR), cal.get(Calendar.MONTH) + 1);
+    }
+
+    /** 差距 → 行动建议(§4.3.1 ② 换算率:250 / 200 分/次、10 分/百元)。 */
+    private String actionAdvice(int gap) {
+        if (gap <= 0) {
+            return "业绩分已达标,重点补齐团队直推 ≥1,并稳住团队服务与推荐消费";
+        }
+        int directTimes = (int) Math.ceil(gap / (double) SCORE_PER_DIRECT_SERVICE);
+        int coachingTimes = (int) Math.ceil(gap / (double) SCORE_PER_TEAM_COACHING);
+        int referralHundreds = (int) Math.ceil(gap / (double) SCORE_PER_HUNDRED_YUAN_REFERRAL);
+        return "① 直接服务再 " + directTimes + " 次 1对1 咨询(" + SCORE_PER_DIRECT_SERVICE + " 分/次)"
+                + ";② 团队带教再 " + coachingTimes + " 次(" + SCORE_PER_TEAM_COACHING + " 分/次)"
+                + ";③ 推荐消费再 ¥" + (referralHundreds * 100L) + "("
+                + SCORE_PER_HUNDRED_YUAN_REFERRAL + " 分/百元)";
+    }
+
+    private String joinBenefits(List<String> benefits) {
+        StringBuilder sb = new StringBuilder();
+        for (int i = 0; i < benefits.size(); i++) {
+            if (i > 0) {
+                sb.append("、");
+            }
+            sb.append(benefits.get(i));
+        }
+        return sb.toString();
+    }
+
+    private String starName(int star) {
+        List<String> names = Arrays.asList("一星", "二星", "三星", "四星", "五星", "六星");
+        int index = clampStar(star) - 1;
+        return names.get(index);
+    }
+
+    private int clampStar(int star) {
+        return Math.min(Math.max(star, StarScoreCalculator.MIN_STAR), TOP_STAR);
+    }
+}