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

feat(reading-checkin): 阅读打卡 T02 后端三模式判定——ArticleReadingTaskService+reportReadingTime/submitQuiz 钩子+completeTask 门控+2 端点+契约单测

Agnes Agent 16 часов назад
Родитель
Сommit
f7fec4a67c

+ 4 - 1
cfc-backend/src/main/java/com/etotem/cfc/config/JwtInterceptor.java

@@ -166,7 +166,10 @@ private static final String[] PUBLIC_PATHS = {
         "/api/coupon/gift/share/create",
         "/api/coupon/gift/share/create",
         "/api/coupon/gift/share/claim",
         "/api/coupon/gift/share/claim",
         "/api/coupon/gift/share/revoke",
         "/api/coupon/gift/share/revoke",
-        "/api/coupon/gift/share/list"
+        "/api/coupon/gift/share/list",
+        // 阅读打卡任务进度与未完成标记:成员私有数据,必须登录
+        "/api/articles/reading-task/progress",
+        "/api/articles/unfinished-ids"
     };
     };
 
 
     /**
     /**

+ 18 - 0
cfc-backend/src/main/java/com/etotem/cfc/controller/content/ArticleCommentController.java

@@ -10,6 +10,7 @@ import com.etotem.cfc.mapper.ArticleMapper;
 import com.etotem.cfc.mapper.ArticleQuizRecordMapper;
 import com.etotem.cfc.mapper.ArticleQuizRecordMapper;
 import com.etotem.cfc.mapper.ProfileSnapshotMapper;
 import com.etotem.cfc.mapper.ProfileSnapshotMapper;
 import com.etotem.cfc.service.ArticleCommentService;
 import com.etotem.cfc.service.ArticleCommentService;
+import com.etotem.cfc.service.ArticleReadingTaskService;
 import com.etotem.cfc.service.AiGateway;
 import com.etotem.cfc.service.AiGateway;
 import com.etotem.cfc.service.CfPathwayEarnService;
 import com.etotem.cfc.service.CfPathwayEarnService;
 import com.etotem.cfc.service.EnergyService;
 import com.etotem.cfc.service.EnergyService;
@@ -51,6 +52,9 @@ public class ArticleCommentController {
     @Resource
     @Resource
     private ProfileSnapshotMapper profileSnapshotMapper;
     private ProfileSnapshotMapper profileSnapshotMapper;
 
 
+    @Resource
+    private ArticleReadingTaskService articleReadingTaskService;
+
     @PostMapping("/comments/list")
     @PostMapping("/comments/list")
     public Result<List<Map<String, Object>>> listComments(@RequestBody Map<String, Object> params) {
     public Result<List<Map<String, Object>>> listComments(@RequestBody Map<String, Object> params) {
         Long articleId = ParamUtils.getLong(params.get("articleId"));
         Long articleId = ParamUtils.getLong(params.get("articleId"));
@@ -178,6 +182,8 @@ public class ArticleCommentController {
                                                   @RequestAttribute(value = "currentMemberId", required = false) Long currentMemberId) {
                                                   @RequestAttribute(value = "currentMemberId", required = false) Long currentMemberId) {
         Long recordId = ParamUtils.getLong(params.get("recordId"));
         Long recordId = ParamUtils.getLong(params.get("recordId"));
         Long memberId = ParamUtils.getLong(params.get("memberId"), currentMemberId);
         Long memberId = ParamUtils.getLong(params.get("memberId"), currentMemberId);
+        // 阅读打卡任务(可选,ARCH-CFC-READING-CHECKIN-001 §4.1):为空时走原逻辑(仅判分发奖)
+        Long taskId = ParamUtils.getLong(params.get("taskId"));
 
 
         ArticleQuizRecord record = articleQuizRecordMapper.selectById(recordId);
         ArticleQuizRecord record = articleQuizRecordMapper.selectById(recordId);
         if (record == null) return Result.error("答题记录不存在");
         if (record == null) return Result.error("答题记录不存在");
@@ -245,11 +251,23 @@ public class ArticleCommentController {
 
 
         updateQuizSummary(memberId, score, totalQuestions, dimStats);
         updateQuizSummary(memberId, score, totalQuestions, dimStats);
 
 
+        // 阅读打卡任务 A/C 钩子(ARCH-CFC-READING-CHECKIN-001 §4.1):
+        // 判分/CF/能量发放原样执行,仅在此追加任务判定;taskId 为空不触发,行为不变。
+        boolean quizPassed = articleReadingTaskService.isQuizPassed(taskId, score, totalQuestions);
+        boolean taskCompleted = false;
+        if (taskId != null) {
+            articleReadingTaskService.onQuizSubmitted(taskId, memberId, record.getArticleId(), score, totalQuestions);
+            // 任务是否已被后端自动完成(A 过题即完成 / C 达 target 完成)
+            taskCompleted = articleReadingTaskService.isTaskCompleted(taskId);
+        }
+
         Map<String, Object> result = new HashMap<>();
         Map<String, Object> result = new HashMap<>();
         result.put("correctCount", score);
         result.put("correctCount", score);
         result.put("totalQuestions", totalQuestions);
         result.put("totalQuestions", totalQuestions);
         result.put("cfEarned", cfEarned);
         result.put("cfEarned", cfEarned);
         result.put("energyEarned", energyEarned);
         result.put("energyEarned", energyEarned);
+        result.put("quizPassed", quizPassed);
+        result.put("taskCompleted", taskCompleted);
         return Result.success(result);
         return Result.success(result);
     }
     }
 
 

+ 37 - 1
cfc-backend/src/main/java/com/etotem/cfc/controller/content/ArticleController.java

@@ -8,6 +8,7 @@ import com.etotem.cfc.entity.User;
 import com.etotem.cfc.mapper.UserMapper;
 import com.etotem.cfc.mapper.UserMapper;
 import com.etotem.cfc.service.ArticleCategoryService;
 import com.etotem.cfc.service.ArticleCategoryService;
 import com.etotem.cfc.service.ArticleAudioService;
 import com.etotem.cfc.service.ArticleAudioService;
+import com.etotem.cfc.service.ArticleReadingTaskService;
 import com.etotem.cfc.service.ArticleService;
 import com.etotem.cfc.service.ArticleService;
 import com.etotem.cfc.service.ProductRecommendationService;
 import com.etotem.cfc.service.ProductRecommendationService;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Operation;
@@ -43,6 +44,9 @@ public class ArticleController {
     @Resource
     @Resource
     private ProductRecommendationService productRecommendationService;
     private ProductRecommendationService productRecommendationService;
 
 
+    @Resource
+    private ArticleReadingTaskService articleReadingTaskService;
+
     @PostMapping("/related-products")
     @PostMapping("/related-products")
     public Result<List<Map<String, Object>>> relatedProducts(@RequestBody Map<String, Object> body,
     public Result<List<Map<String, Object>>> relatedProducts(@RequestBody Map<String, Object> body,
                                                              @RequestAttribute(value = "userId", required = false) Long userId,
                                                              @RequestAttribute(value = "userId", required = false) Long userId,
@@ -251,11 +255,43 @@ public class ArticleController {
         int durationSeconds = body.get("durationSeconds") != null
         int durationSeconds = body.get("durationSeconds") != null
                 ? Integer.parseInt(body.get("durationSeconds").toString()) : 0;
                 ? Integer.parseInt(body.get("durationSeconds").toString()) : 0;
         Long memberId = ParamUtils.getLong(body.get("memberId"), currentMemberId);
         Long memberId = ParamUtils.getLong(body.get("memberId"), currentMemberId);
+        // 阅读打卡任务(可选):存在时写 article_reading_records.task_id,达标(模式 B)由后端自动完成
+        Long taskId = ParamUtils.getLong(body.get("taskId"));
 
 
-        articleService.reportReadingTime(articleId, userId, memberId, durationSeconds);
+        articleService.reportReadingTime(articleId, userId, memberId, durationSeconds, taskId);
         return Result.success(null);
         return Result.success(null);
     }
     }
 
 
+    /**
+     * 阅读打卡任务进度查询(ARCH-CFC-READING-CHECKIN-001 §4.2)。
+     * 返回 {@code {mode, done, target, quizPassed, readingCompleted, minSeconds, articleId}}:
+     * done=ledger count(C)或 0/1(A 是否过题、B 是否达标),前端据 mode 渲染进度条。
+     */
+    @PostMapping("/reading-task/progress")
+    public Result<Map<String, Object>> readingTaskProgress(@RequestBody Map<String, Object> body) {
+        Long taskId = ParamUtils.getLong(body.get("taskId"));
+        try {
+            return Result.success(articleReadingTaskService.getTaskProgress(taskId));
+        } catch (IllegalArgumentException e) {
+            return Result.error(e.getMessage());
+        }
+    }
+
+    /**
+     * 分享中心「未完成」标记(ARCH-CFC-READING-CHECKIN-001 §4.2)。
+     * 返回 {@code {completedArticleIds: [...], total: n}}:该成员已 reading_completed=1 的文章 id 集合,
+     * 前端置灰已读、高亮未读。
+     */
+    @PostMapping("/unfinished-ids")
+    public Result<Map<String, Object>> unfinishedArticleIds(@RequestBody Map<String, Object> body,
+                                                             @RequestAttribute(value = "currentMemberId", required = false) Long currentMemberId) {
+        Long memberId = ParamUtils.getLong(body.get("memberId"), currentMemberId);
+        if (memberId == null) {
+            return Result.error("memberId不能为空");
+        }
+        return Result.success(articleReadingTaskService.getUnfinishedArticleIds(memberId));
+    }
+
     @PostMapping("/reading-stats")
     @PostMapping("/reading-stats")
     public Result<ReadingStatsDTO> readingStats(@RequestBody Map<String, Object> body,
     public Result<ReadingStatsDTO> readingStats(@RequestBody Map<String, Object> body,
                                                 @RequestAttribute(value = "currentMemberId", required = false) Long currentMemberId) {
                                                 @RequestAttribute(value = "currentMemberId", required = false) Long currentMemberId) {

+ 564 - 0
cfc-backend/src/main/java/com/etotem/cfc/service/ArticleReadingTaskService.java

@@ -0,0 +1,564 @@
+package com.etotem.cfc.service;
+
+import com.alibaba.fastjson.JSON;
+import com.alibaba.fastjson.JSONObject;
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.etotem.cfc.entity.ArticleQuizRecord;
+import com.etotem.cfc.entity.ArticleReadingRecord;
+import com.etotem.cfc.entity.Task;
+import com.etotem.cfc.entity.TaskArticleProgress;
+import com.etotem.cfc.mapper.ArticleQuizRecordMapper;
+import com.etotem.cfc.mapper.ArticleReadingRecordMapper;
+import com.etotem.cfc.mapper.TaskArticleProgressMapper;
+import com.etotem.cfc.mapper.TaskMapper;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.dao.DuplicateKeyException;
+import org.springframework.stereotype.Service;
+
+import javax.annotation.Resource;
+import java.util.Collections;
+import java.util.Date;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+import java.util.Objects;
+import java.util.stream.Collectors;
+
+/**
+ * 「阅读打卡任务」三模式完成判定核心(ARCH-CFC-READING-CHECKIN-001 §5.1)。
+ *
+ * <p>承载三模式的门控校验与后端自动完成触发:</p>
+ * <ul>
+ *   <li><b>模式 A(ARTICLE)</b>:指定文章,读够时长(软前置,前端保障)+ 答题通过(score/total ≥ passRate)
+ *       → 后端自动 {@code completeTask};</li>
+ *   <li><b>模式 B(DURATION)</b>:按时长,{@code report-reading-time} 达标(reading_completed=1 且
+ *       duration ≥ minSeconds,按 {@code article_reading_records.task_id} 关联)→ 后端自动 {@code completeTask};</li>
+ *   <li><b>模式 C(COUNT)</b>:按数量,每篇过题 {@code task_article_progress} 记账 +1(唯一键防重),
+ *       达 target → 后端自动 {@code completeTask}。</li>
+ * </ul>
+ *
+ * <p>防绕过:{@code TaskService.completeTask} 以 {@code @Lazy} 注入本服务做轻量兜底门控
+ * ({@link #assertArticleTaskQualified(Task)}),非达标直接抛对应文案,前端无法绕过。</p>
+ *
+ * <p>注入方向:{@code ArticleReadingTaskService → TaskService}(单向),避免循环依赖由
+ * {@code TaskService} 侧 {@code @Lazy} 兜底;本服务不依赖 {@code ArticleService}。</p>
+ */
+@Slf4j
+@Service
+public class ArticleReadingTaskService {
+
+    // ==================== mode 常量(§11:ARTICLE/DURATION/COUNT,统一大写) ====================
+    public static final String MODE_ARTICLE = "ARTICLE";
+    public static final String MODE_DURATION = "DURATION";
+    public static final String MODE_COUNT = "COUNT";
+
+    /** quiz 通过阈值系统配置键;解析顺序:actionConfig.quizPassRate > 本配置 > {@link #DEFAULT_QUIZ_PASS_RATE} */
+    public static final String QUIZ_PASS_THRESHOLD_CONFIG_KEY = "quiz.pass_threshold";
+    /** 默认 quiz 通过阈值(无 actionConfig / 系统配置时) */
+    public static final double DEFAULT_QUIZ_PASS_RATE = 0.6;
+
+    // ==================== 错误文案常量(§11,前端直接 toast;集中定义) ====================
+    /** 模式 A/C:答题未通过,不允许完成 */
+    public static final String MSG_QUIZ_NOT_PASSED = "请先通过测试题后再完成";
+    /** 模式 B:阅读时长未达标,不允许完成 */
+    public static final String MSG_DURATION_NOT_ENOUGH = "阅读时长不足,请继续阅读";
+    /** 模式 C:已计篇数未达目标,不允许完成 */
+    public static final String MSG_PROGRESS_NOT_ENOUGH = "阅读进度不足";
+    /** action_config 解析失败 / 缺 mode 或必填字段 */
+    public static final String MSG_NO_CONFIG = "阅读任务缺少配置";
+    /** 模式 A 未选文章(创建时校验) */
+    public static final String MSG_ARTICLE_REQUIRED = "请选择文章";
+    /** 指定文章不存在或非 published(创建时校验) */
+    public static final String MSG_ARTICLE_UNAVAILABLE = "文章不存在或已下架";
+    /** minSeconds ≤ 0(创建时校验) */
+    public static final String MSG_INVALID_MIN_SECONDS = "请输入有效阅读时长";
+    /** targetCount ≤ 0 且 target_value ≤ 0(创建时校验) */
+    public static final String MSG_INVALID_TARGET_COUNT = "请输入有效阅读篇数";
+    /** quizPassRate 非法(0 < rate ≤ 1) */
+    public static final String MSG_QUIZ_RATE_INVALID = "答题通过率需大于0且不超过1";
+    /** 任务不存在(progress 端点) */
+    public static final String MSG_TASK_NOT_FOUND = "任务不存在";
+
+    @Resource
+    private TaskService taskService;
+    @Resource
+    private TaskMapper taskMapper;
+    @Resource
+    private ArticleReadingRecordMapper articleReadingRecordMapper;
+    @Resource
+    private ArticleQuizRecordMapper articleQuizRecordMapper;
+    @Resource
+    private TaskArticleProgressMapper taskArticleProgressMapper;
+    @Resource
+    private SysConfigService sysConfigService;
+
+    /**
+     * {@code action_config} 解析结果(§2 契约,键名统一 camelCase,JSON 字符串入库)。
+     * 缺失字段以默认值填充:minSeconds/targetCount=0,requireQuiz=true(A/C),quizPassRate 按
+     * actionConfig → sysConfig → 0.6 解析。
+     */
+    public static class ReadingTaskConfig {
+        /** ARTICLE / DURATION / COUNT(大小写敏感,统一大写;无法推断时为 null) */
+        public String mode;
+        /** 模式 A 指定文章 ID */
+        public Long articleId;
+        /** A/B 阅读达标秒数(0 表示取 tasks.min_duration_seconds) */
+        public int minSeconds;
+        /** C 目标篇数(0 表示取 tasks.target_value) */
+        public int targetCount;
+        /** A/C 默认 true;B 恒 false */
+        public boolean requireQuiz;
+        /** 0 < rate ≤ 1 */
+        public double quizPassRate;
+
+        public ReadingTaskConfig() {
+            this.requireQuiz = true;
+            this.quizPassRate = DEFAULT_QUIZ_PASS_RATE;
+        }
+    }
+
+    /**
+     * 解析 action_config,缺省按已填字段推断 mode;无配置 / 解析失败返回 null。
+     *
+     * <p>创建期必填校验常量({@link #MSG_ARTICLE_REQUIRED} / {@link #MSG_INVALID_MIN_SECONDS} /
+     * {@link #MSG_INVALID_TARGET_COUNT} / {@link #MSG_QUIZ_RATE_INVALID} / {@link #MSG_ARTICLE_UNAVAILABLE})
+     * 由 {@code TaskService.createTask} 的 {@code action_type='article'} 分支消费(同批次契约),
+     * 本服务仅负责运行期解析与门控。</p>
+     */
+    public ReadingTaskConfig parseConfig(Task task) {
+        if (task == null || task.getActionConfig() == null || task.getActionConfig().trim().isEmpty()) {
+            return null;
+        }
+        JSONObject cfg;
+        try {
+            cfg = JSON.parseObject(task.getActionConfig());
+        } catch (Exception e) {
+            log.warn("阅读打卡任务 action_config 解析失败: taskId={}, error={}", task.getId(), e.getMessage());
+            return null;
+        }
+        if (cfg == null) {
+            return null;
+        }
+        ReadingTaskConfig c = new ReadingTaskConfig();
+        String mode = cfg.getString("mode");
+        if (mode == null || mode.trim().isEmpty()) {
+            // 缺省推断:按已填字段(articleId → ARTICLE;targetCount → COUNT;minSeconds → DURATION)
+            if (cfg.getLong("articleId") != null) {
+                mode = MODE_ARTICLE;
+            } else if (cfg.getInteger("targetCount") != null) {
+                mode = MODE_COUNT;
+            } else if (cfg.getInteger("minSeconds") != null) {
+                mode = MODE_DURATION;
+            }
+        }
+        c.mode = mode == null ? null : mode.trim().toUpperCase(Locale.ROOT);
+        c.articleId = cfg.getLong("articleId");
+        c.minSeconds = cfg.getInteger("minSeconds") != null ? cfg.getInteger("minSeconds") : 0;
+        c.targetCount = cfg.getInteger("targetCount") != null ? cfg.getInteger("targetCount") : 0;
+        Boolean requireQuiz = cfg.getBoolean("requireQuiz");
+        c.requireQuiz = requireQuiz == null || requireQuiz; // A/C 默认 true
+        if (MODE_DURATION.equals(c.mode)) {
+            c.requireQuiz = false; // B 恒 false
+        }
+        c.quizPassRate = resolveQuizPassRate(cfg.getDouble("quizPassRate"));
+        return c;
+    }
+
+    /**
+     * 是否已通过该文章测试题(模式 A/C 门控核心):任一 {@code article_quiz_records}
+     * (article_id、member_id 匹配,已判分 score/total ≥ passRate)即视为通过。
+     */
+    public boolean articleQuizPassed(Long memberId, Long articleId, double passRate) {
+        if (memberId == null || articleId == null) {
+            return false;
+        }
+        List<ArticleQuizRecord> records = articleQuizRecordMapper.selectList(
+                new LambdaQueryWrapper<ArticleQuizRecord>()
+                        .eq(ArticleQuizRecord::getArticleId, articleId)
+                        .eq(ArticleQuizRecord::getMemberId, memberId)
+                        .isNotNull(ArticleQuizRecord::getScore));
+        for (ArticleQuizRecord r : records) {
+            if (r.getScore() != null && r.getTotalQuestions() != null && r.getTotalQuestions() > 0
+                    && (double) r.getScore() / r.getTotalQuestions() >= passRate) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * 模式 B 时长是否达标:存在 {@code article_reading_records}
+     * (task_id=taskId, member_id=memberId, reading_completed=1, duration_seconds ≥ minSeconds)。
+     */
+    public boolean durationQualified(Long taskId, Long memberId, int minSeconds) {
+        if (taskId == null || memberId == null || minSeconds <= 0) {
+            return false;
+        }
+        Long cnt = articleReadingRecordMapper.selectCount(
+                new LambdaQueryWrapper<ArticleReadingRecord>()
+                        .eq(ArticleReadingRecord::getTaskId, taskId)
+                        .eq(ArticleReadingRecord::getMemberId, memberId)
+                        .eq(ArticleReadingRecord::getReadingCompleted, true)
+                        .ge(ArticleReadingRecord::getDurationSeconds, minSeconds));
+        return cnt != null && cnt > 0;
+    }
+
+    /**
+     * 模式 C 已计篇数:{@code task_article_progress} 按 task_id 计数。
+     */
+    public int countArticleProgress(Long taskId) {
+        if (taskId == null) {
+            return 0;
+        }
+        Long cnt = taskArticleProgressMapper.selectCount(
+                new LambdaQueryWrapper<TaskArticleProgress>()
+                        .eq(TaskArticleProgress::getTaskId, taskId));
+        return cnt != null ? cnt.intValue() : 0;
+    }
+
+    /**
+     * 模式 C 记账 +1(INSERT 捕获唯一键 {@code uk_task_article(task_id, article_id)}
+     * 的 {@link DuplicateKeyException} 视为已计),返回是否新增。
+     */
+    public boolean recordArticleProgress(Long taskId, Long memberId, Long articleId) {
+        if (taskId == null || memberId == null || articleId == null) {
+            return false;
+        }
+        TaskArticleProgress p = new TaskArticleProgress();
+        p.setTaskId(taskId);
+        p.setArticleId(articleId);
+        p.setMemberId(memberId);
+        p.setCreatedAt(new Date());
+        try {
+            taskArticleProgressMapper.insert(p);
+            return true;
+        } catch (DuplicateKeyException e) {
+            return false; // 同任务同篇已计过,幂等跳过
+        }
+    }
+
+    /**
+     * 门控校验 + 自动完成(供 submitQuiz / reportReadingTime 调用;幂等)。
+     *
+     * <p>仅当对应模式达标才调用 {@link TaskService#completeTask};未达标静默返回(任务保持
+     * in_progress,不破坏 quiz / 阅读上报主流程)。completeTask 内部拒绝(时间窗守卫 / 兜底门控)
+     * 仅记录 warn,不向上抛,避免答题/阅读已成功后反被任务完成失败打断。</p>
+     */
+    public void tryCompleteArticleTask(Long taskId, Long memberId, Long articleId) {
+        if (taskId == null) {
+            return;
+        }
+        Task task = taskMapper.selectById(taskId);
+        if (task == null || !"article".equals(task.getActionType())) {
+            return;
+        }
+        ReadingTaskConfig cfg = parseConfig(task);
+        if (cfg == null) {
+            return;
+        }
+        Long effMemberId = memberId != null ? memberId : resolveMemberId(task);
+        if (effMemberId == null || !isQualified(cfg, task, effMemberId, articleId)) {
+            return;
+        }
+        try {
+            taskService.completeTask(taskId, effMemberId, null, null, null);
+        } catch (IllegalArgumentException e) {
+            // 时间窗守卫 / 兜底门控拒绝:进度已保留,任务保持未完成,不打断答题/阅读上报
+            log.warn("阅读打卡任务自动完成被拒(门控/时间窗): taskId={}, memberId={}, msg={}",
+                    taskId, effMemberId, e.getMessage());
+        } catch (Exception e) {
+            log.warn("阅读打卡任务自动完成异常: taskId={}, memberId={}, msg={}",
+                    taskId, effMemberId, e.getMessage());
+        }
+    }
+
+    /**
+     * quiz 提交后钩子(模式 A/C):A → 过题即自动完成;C → 记账 +1,达 target 即自动完成。
+     * 未过题不完成(保持 in_progress,前端据 quizPassed 提示重考)。
+     */
+    public void onQuizSubmitted(Long taskId, Long memberId, Long articleId, int score, int totalQuestions) {
+        if (taskId == null) {
+            return;
+        }
+        Task task = taskMapper.selectById(taskId);
+        if (task == null || !"article".equals(task.getActionType())) {
+            return;
+        }
+        ReadingTaskConfig cfg = parseConfig(task);
+        if (cfg == null) {
+            return;
+        }
+        Long effMemberId = memberId != null ? memberId : resolveMemberId(task);
+        if (MODE_ARTICLE.equals(cfg.mode)) {
+            // 仅处理该任务指定的文章;过题即自动完成
+            if (articleId != null && articleId.equals(cfg.articleId)
+                    && isQuizPassed(score, totalQuestions, cfg.quizPassRate)) {
+                tryCompleteArticleTask(taskId, effMemberId, articleId);
+            }
+        } else if (MODE_COUNT.equals(cfg.mode)) {
+            // 每篇过题记账 +1(唯一键防重);达 target 由 tryCompleteArticleTask 判定
+            if (isQuizPassed(score, totalQuestions, cfg.quizPassRate)) {
+                recordArticleProgress(taskId, effMemberId, articleId);
+                tryCompleteArticleTask(taskId, effMemberId, articleId);
+            }
+        }
+    }
+
+    /**
+     * 阅读记录达标钩子(模式 B):本次阅读上报使某记录 reading_completed=1 且任务为
+     * mode DURATION → 自动完成。
+     */
+    public void onReadingCompleted(Long taskId, Long memberId, Long recordId) {
+        if (taskId == null) {
+            return;
+        }
+        Task task = taskMapper.selectById(taskId);
+        if (task == null || !"article".equals(task.getActionType())) {
+            return;
+        }
+        ReadingTaskConfig cfg = parseConfig(task);
+        if (cfg == null || !MODE_DURATION.equals(cfg.mode)) {
+            return;
+        }
+        Long effMemberId = memberId != null ? memberId : resolveMemberId(task);
+        tryCompleteArticleTask(taskId, effMemberId, null);
+    }
+
+    /**
+     * 兜底门控({@code TaskService.completeTask} 调用,防前端绕过):
+     * {@code action_type='article'} 任务必须通过对应模式门控校验,否则抛对应错误文案。
+     * 非文章任务直接放行(不影响既有「读文章自动完成/无 quiz 阅读」行为)。
+     */
+    public void assertArticleTaskQualified(Task task) {
+        if (task == null || !"article".equals(task.getActionType())) {
+            return;
+        }
+        ReadingTaskConfig cfg = parseConfig(task);
+        if (cfg == null) {
+            throw new IllegalArgumentException(MSG_NO_CONFIG);
+        }
+        Long memberId = resolveMemberId(task);
+        if (MODE_ARTICLE.equals(cfg.mode)) {
+            if (cfg.articleId == null || cfg.articleId <= 0) {
+                throw new IllegalArgumentException(MSG_NO_CONFIG);
+            }
+            if (!articleQuizPassed(memberId, cfg.articleId, cfg.quizPassRate)) {
+                throw new IllegalArgumentException(MSG_QUIZ_NOT_PASSED);
+            }
+        } else if (MODE_DURATION.equals(cfg.mode)) {
+            int minSeconds = resolveMinSeconds(cfg, task);
+            if (minSeconds <= 0) {
+                throw new IllegalArgumentException(MSG_NO_CONFIG);
+            }
+            if (!durationQualified(task.getId(), memberId, minSeconds)) {
+                throw new IllegalArgumentException(MSG_DURATION_NOT_ENOUGH);
+            }
+        } else if (MODE_COUNT.equals(cfg.mode)) {
+            int target = resolveTargetCount(cfg, task);
+            if (target <= 0) {
+                throw new IllegalArgumentException(MSG_NO_CONFIG);
+            }
+            if (countArticleProgress(task.getId()) < target) {
+                throw new IllegalArgumentException(MSG_PROGRESS_NOT_ENOUGH);
+            }
+        } else {
+            throw new IllegalArgumentException(MSG_NO_CONFIG);
+        }
+    }
+
+    /**
+     * 任务进度查询({@code /api/articles/reading-task/progress})。
+     * 返回 {@code {mode, done, target, quizPassed, readingCompleted, minSeconds, articleId}}。
+     *
+     * @throws IllegalArgumentException 任务不存在 / 配置缺失(message 直出前端 toast)
+     */
+    public Map<String, Object> getTaskProgress(Long taskId) {
+        if (taskId == null) {
+            throw new IllegalArgumentException(MSG_TASK_NOT_FOUND);
+        }
+        Task task = taskMapper.selectById(taskId);
+        if (task == null) {
+            throw new IllegalArgumentException(MSG_TASK_NOT_FOUND);
+        }
+        ReadingTaskConfig cfg = parseConfig(task);
+        if (cfg == null) {
+            throw new IllegalArgumentException(MSG_NO_CONFIG);
+        }
+        Long memberId = resolveMemberId(task);
+        Map<String, Object> m = new HashMap<>();
+        m.put("mode", cfg.mode);
+        m.put("articleId", cfg.articleId);
+        if (MODE_ARTICLE.equals(cfg.mode)) {
+            boolean passed = cfg.articleId != null && articleQuizPassed(memberId, cfg.articleId, cfg.quizPassRate);
+            m.put("done", passed ? 1 : 0);
+            m.put("target", 1);
+            m.put("quizPassed", passed);
+            m.put("readingCompleted", isReadingCompleted(cfg.articleId, memberId));
+            m.put("minSeconds", resolveMinSeconds(cfg, task));
+        } else if (MODE_DURATION.equals(cfg.mode)) {
+            int minSeconds = resolveMinSeconds(cfg, task);
+            boolean qualified = durationQualified(taskId, memberId, minSeconds);
+            m.put("done", qualified ? 1 : 0);
+            m.put("target", 1);
+            m.put("quizPassed", false);
+            m.put("readingCompleted", qualified);
+            m.put("minSeconds", minSeconds);
+        } else if (MODE_COUNT.equals(cfg.mode)) {
+            int target = resolveTargetCount(cfg, task);
+            int done = countArticleProgress(taskId);
+            m.put("done", done);
+            m.put("target", target);
+            m.put("quizPassed", false);
+            m.put("readingCompleted", false);
+            m.put("minSeconds", 0);
+        } else {
+            throw new IllegalArgumentException(MSG_NO_CONFIG);
+        }
+        return m;
+    }
+
+    /**
+     * 分享中心「未完成」标记({@code /api/articles/unfinished-ids}):
+     * 返回 {@code {completedArticleIds: [...], total: n}},即该成员已 reading_completed=1 的文章 id 集合。
+     */
+    public Map<String, Object> getUnfinishedArticleIds(Long memberId) {
+        List<Long> completed = getCompletedArticleIds(memberId);
+        Map<String, Object> m = new HashMap<>();
+        m.put("completedArticleIds", completed);
+        m.put("total", completed.size());
+        return m;
+    }
+
+    /** 该成员已 reading_completed=1 的文章 id 集合(去重,按文章分组)。 */
+    public List<Long> getCompletedArticleIds(Long memberId) {
+        if (memberId == null) {
+            return Collections.emptyList();
+        }
+        List<ArticleReadingRecord> records = articleReadingRecordMapper.selectList(
+                new LambdaQueryWrapper<ArticleReadingRecord>()
+                        .select(ArticleReadingRecord::getArticleId)
+                        .eq(ArticleReadingRecord::getMemberId, memberId)
+                        .eq(ArticleReadingRecord::getReadingCompleted, true)
+                        .groupBy(ArticleReadingRecord::getArticleId));
+        return records.stream()
+                .map(ArticleReadingRecord::getArticleId)
+                .filter(Objects::nonNull)
+                .distinct()
+                .collect(Collectors.toList());
+    }
+
+    /**
+     * quiz 提交是否达到任务 passRate(供 submitQuiz 返回 quizPassed;taskId 为空按默认 0.6 判定)。
+     */
+    public boolean isQuizPassed(Long taskId, int score, int totalQuestions) {
+        double rate = DEFAULT_QUIZ_PASS_RATE;
+        if (taskId != null) {
+            Task task = taskMapper.selectById(taskId);
+            if (task != null) {
+                ReadingTaskConfig cfg = parseConfig(task);
+                if (cfg != null) {
+                    rate = cfg.quizPassRate;
+                }
+            }
+        }
+        return isQuizPassed(score, totalQuestions, rate);
+    }
+
+    /** 任务是否已置 completed(供 submitQuiz 返回 taskCompleted)。 */
+    public boolean isTaskCompleted(Long taskId) {
+        if (taskId == null) {
+            return false;
+        }
+        Task t = taskMapper.selectById(taskId);
+        return t != null && "completed".equals(t.getStatus());
+    }
+
+    // ==================== 内部工具 ====================
+
+    /** 当前模式是否满足门控条件(tryCompleteArticleTask / 兜底门控共用判定)。 */
+    private boolean isQualified(ReadingTaskConfig cfg, Task task, Long memberId, Long articleId) {
+        if (MODE_ARTICLE.equals(cfg.mode)) {
+            return articleId != null && articleId.equals(cfg.articleId)
+                    && articleQuizPassed(memberId, cfg.articleId, cfg.quizPassRate);
+        }
+        if (MODE_DURATION.equals(cfg.mode)) {
+            int minSeconds = resolveMinSeconds(cfg, task);
+            return minSeconds > 0 && durationQualified(task.getId(), memberId, minSeconds);
+        }
+        if (MODE_COUNT.equals(cfg.mode)) {
+            int target = resolveTargetCount(cfg, task);
+            return target > 0 && countArticleProgress(task.getId()) >= target;
+        }
+        return false;
+    }
+
+    /** 该成员是否已对指定文章 reading_completed=1(模式 A 进度展示用)。 */
+    private boolean isReadingCompleted(Long articleId, Long memberId) {
+        if (articleId == null || memberId == null) {
+            return false;
+        }
+        Long cnt = articleReadingRecordMapper.selectCount(
+                new LambdaQueryWrapper<ArticleReadingRecord>()
+                        .eq(ArticleReadingRecord::getArticleId, articleId)
+                        .eq(ArticleReadingRecord::getMemberId, memberId)
+                        .eq(ArticleReadingRecord::getReadingCompleted, true));
+        return cnt != null && cnt > 0;
+    }
+
+    /** 任务执行成员解析:familyMemberId → memberId(child_id) → executorId。 */
+    private Long resolveMemberId(Task task) {
+        if (task == null) {
+            return null;
+        }
+        if (task.getFamilyMemberId() != null) {
+            return task.getFamilyMemberId();
+        }
+        if (task.getMemberId() != null) {
+            return task.getMemberId();
+        }
+        return task.getExecutorId();
+    }
+
+    /** A/B 有效阅读秒数:actionConfig.minSeconds 优先,缺省 tasks.min_duration_seconds。 */
+    private int resolveMinSeconds(ReadingTaskConfig cfg, Task task) {
+        if (cfg.minSeconds > 0) {
+            return cfg.minSeconds;
+        }
+        Integer ms = task.getMinDurationSeconds();
+        return ms != null && ms > 0 ? ms : 0;
+    }
+
+    /** C 有效目标篇数:actionConfig.targetCount 优先,缺省 tasks.target_value。 */
+    private int resolveTargetCount(ReadingTaskConfig cfg, Task task) {
+        if (cfg.targetCount > 0) {
+            return cfg.targetCount;
+        }
+        Integer tv = task.getTargetValue();
+        return tv != null && tv > 0 ? tv : 0;
+    }
+
+    /** quiz 通过阈值解析:显式配置(0<rate≤1)→ 系统配置 → 默认 0.6;非法值回退下一优先级。 */
+    private double resolveQuizPassRate(Double configured) {
+        if (configured != null && configured > 0 && configured <= 1) {
+            return configured;
+        }
+        String sys = sysConfigService.getValue(QUIZ_PASS_THRESHOLD_CONFIG_KEY);
+        if (sys != null && !sys.trim().isEmpty()) {
+            try {
+                double v = Double.parseDouble(sys.trim());
+                if (v > 0 && v <= 1) {
+                    return v;
+                }
+            } catch (NumberFormatException ignored) {
+                // 系统配置非法,回落默认值
+            }
+        }
+        return DEFAULT_QUIZ_PASS_RATE;
+    }
+
+    /** score/total 是否达到 passRate。 */
+    private boolean isQuizPassed(int score, int totalQuestions, double passRate) {
+        return totalQuestions > 0 && (double) score / totalQuestions >= passRate;
+    }
+}

+ 26 - 1
cfc-backend/src/main/java/com/etotem/cfc/service/ArticleService.java

@@ -82,6 +82,9 @@ public class ArticleService {
     @Resource
     @Resource
     private ArticleQuizRecordMapper articleQuizRecordMapper;
     private ArticleQuizRecordMapper articleQuizRecordMapper;
 
 
+    @Resource
+    private ArticleReadingTaskService articleReadingTaskService;
+
     @Resource
     @Resource
     private UserMapper userMapper;
     private UserMapper userMapper;
 
 
@@ -626,7 +629,15 @@ public class ArticleService {
         return result;
         return result;
     }
     }
 
 
-    public void reportReadingTime(Long articleId, Long userId, Long memberId, int durationSeconds) {
+    /**
+     * 上报阅读时长(阅读打卡任务门控,ARCH-CFC-READING-CHECKIN-001 §4.1/§5.2)。
+     *
+     * <p>taskId 为空时行为与原逻辑完全一致(仅累计/新建阅读记录);taskId 存在时:
+     * ① 写入 {@code article_reading_records.task_id};② 若该记录本次达标
+     * (reading_completed=1)且任务为模式 B(DURATION),调
+     * {@link ArticleReadingTaskService#onReadingCompleted} 由后端自动 completeTask。</p>
+     */
+    public void reportReadingTime(Long articleId, Long userId, Long memberId, int durationSeconds, Long taskId) {
         if (memberId == null) return;
         if (memberId == null) return;
 
 
         // 查找当日已有记录(同文章+同家庭成员)
         // 查找当日已有记录(同文章+同家庭成员)
@@ -649,8 +660,15 @@ public class ArticleService {
                 existing.setReadingCompleted(existing.getDurationSeconds() >= minSeconds);
                 existing.setReadingCompleted(existing.getDurationSeconds() >= minSeconds);
                 isCompleted = existing.getReadingCompleted();
                 isCompleted = existing.getReadingCompleted();
             }
             }
+            if (taskId != null) {
+                existing.setTaskId(taskId);
+            }
             existing.setUpdatedAt(new Date());
             existing.setUpdatedAt(new Date());
             articleReadingRecordMapper.updateById(existing);
             articleReadingRecordMapper.updateById(existing);
+            // 阅读打卡任务 B 模式钩子:本次达标(reading_completed=1)且带任务上下文 → 判定自动完成
+            if (isCompleted && taskId != null) {
+                articleReadingTaskService.onReadingCompleted(taskId, memberId, existing.getId());
+            }
         } else {
         } else {
             // 新建记录
             // 新建记录
             ArticleReadingRecord record = new ArticleReadingRecord();
             ArticleReadingRecord record = new ArticleReadingRecord();
@@ -659,9 +677,16 @@ public class ArticleService {
             record.setMemberId(memberId);
             record.setMemberId(memberId);
             record.setDurationSeconds(durationSeconds);
             record.setDurationSeconds(durationSeconds);
             record.setReadingCompleted(durationSeconds >= minSeconds);
             record.setReadingCompleted(durationSeconds >= minSeconds);
+            if (taskId != null) {
+                record.setTaskId(taskId);
+            }
             record.setReadAt(new Date());
             record.setReadAt(new Date());
             record.setCreatedAt(new Date());
             record.setCreatedAt(new Date());
             articleReadingRecordMapper.insert(record);
             articleReadingRecordMapper.insert(record);
+            // 新记录一次性达标(首报即满时长)且带任务上下文 → 模式 B 钩子
+            if (Boolean.TRUE.equals(record.getReadingCompleted()) && taskId != null) {
+                articleReadingTaskService.onReadingCompleted(taskId, memberId, record.getId());
+            }
         }
         }
     }
     }
 
 

+ 17 - 0
cfc-backend/src/main/java/com/etotem/cfc/service/TaskService.java

@@ -94,6 +94,15 @@ public class TaskService implements TaskServiceInterface {
     @Resource
     @Resource
     private CfPathwayEarnService cfPathwayEarnService;
     private CfPathwayEarnService cfPathwayEarnService;
 
 
+    /**
+     * ARCH-CFC-READING-CHECKIN-001 §5.2:阅读打卡任务兜底门控(防前端绕过,非达标 article 任务拒绝完成)。
+     * <p>注入方向:{@code ArticleReadingTaskService → TaskService} 已单向;
+     * 此处以 {@code @Lazy} 代理反向注入破循环(首次使用时才解析真实 Bean)。</p>
+     */
+    @Resource
+    @Lazy
+    private ArticleReadingTaskService articleReadingTaskService;
+
     private static final int EARLY_BONUS = 1; // 提前完成奖励
     private static final int EARLY_BONUS = 1; // 提前完成奖励
     private static final int PENALTY_MAX_DAILY = 5; // 每日最多扣分
     private static final int PENALTY_MAX_DAILY = 5; // 每日最多扣分
     private static final int LATE_GRACE_MINUTES = 10; // 10分钟内不算迟到
     private static final int LATE_GRACE_MINUTES = 10; // 10分钟内不算迟到
@@ -836,6 +845,14 @@ public List<Task> getTodayTasks(Long memberId, String dimensionCode) {
             throw new IllegalArgumentException("已过截止时间 " + twFmt.format(task.getLatestEnd()) + ",无法提交");
             throw new IllegalArgumentException("已过截止时间 " + twFmt.format(task.getLatestEnd()) + ",无法提交");
         }
         }
 
 
+        // ===== 阅读打卡任务兜底门控(ARCH-CFC-READING-CHECKIN-001 §5.2,防前端绕过) =====
+        // action_type='article' 的任务必须通过对应模式门控校验(A 过题 / B 时长达标 / C 篇数达标),
+        // 否则拒绝完成(不落 completed、不发奖),错误文案直出前端 toast。
+        // 位置:时间窗守卫之后、需审核分支之前——不绕过时间窗,也不放行未达标任务提交审核。
+        if ("article".equals(task.getActionType())) {
+            articleReadingTaskService.assertArticleTaskQualified(task);
+        }
+
         // 需审核的任务:提交后进入待审核,审核通过后再发放积分
         // 需审核的任务:提交后进入待审核,审核通过后再发放积分
         if (task.getNeedReview() != null && task.getNeedReview() == 1) {
         if (task.getNeedReview() != null && task.getNeedReview() == 1) {
             return submitTaskForReview(task, memberId, now, content, contentType);
             return submitTaskForReview(task, memberId, now, content, contentType);

+ 618 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/ReadingCheckinContractTest.java

@@ -0,0 +1,618 @@
+package com.etotem.cfc.unit;
+
+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.core.conditions.Wrapper;
+import com.baomidou.mybatisplus.core.metadata.TableInfoHelper;
+import com.etotem.cfc.entity.ArticleQuizRecord;
+import com.etotem.cfc.entity.ArticleReadingRecord;
+import com.etotem.cfc.entity.Task;
+import com.etotem.cfc.entity.TaskArticleProgress;
+import com.etotem.cfc.mapper.ArticleQuizRecordMapper;
+import com.etotem.cfc.mapper.ArticleReadingRecordMapper;
+import com.etotem.cfc.mapper.FamilyMemberMapper;
+import com.etotem.cfc.mapper.TaskArticleProgressMapper;
+import com.etotem.cfc.mapper.TaskMapper;
+import com.etotem.cfc.service.ArticleReadingTaskService;
+import com.etotem.cfc.service.SysConfigService;
+import com.etotem.cfc.service.TaskService;
+import org.apache.ibatis.builder.MapperBuilderAssistant;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+import org.springframework.dao.DuplicateKeyException;
+
+import java.lang.reflect.Field;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+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.ArgumentMatchers.anyLong;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * 阅读打卡任务三模式完成判定契约测试(ARCH-CFC-READING-CHECKIN-001 §10 十个场景,纯 Mockito 无 Spring 上下文)。
+ *
+ * <p>测试对象(Group A):{@link ArticleReadingTaskService} —— 三模式门控 + 自动完成触发 +
+ * 进度查询;Group B:{@link TaskService#completeTask} 的 article 兜底门控(§5.2 防前端绕过)。
+ * 风格参考 {@code ShopCouponClaimContractTest}:{@code new X()} + 反射注入 mock,不启动 Spring。</p>
+ *
+ * <p>覆盖流(映射设计 §10):</p>
+ * <ul>
+ *   <li>场景 1:A 读够时长 + 答题通过 → completeTask 触发一次;进度 done=1/quizPassed=true;</li>
+ *   <li>场景 2:A 读够时长 + 答题不通过 → completeTask 不触发;quizPassed=false;</li>
+ *   <li>场景 3:A 读够时长但未答题 → completeTask 兜底门控拒绝「请先通过测试题后再完成」;</li>
+ *   <li>场景 4:B 选未完成文章读够时长 → report 达标 → completeTask 一次;done=1;</li>
+ *   <li>场景 5:B 选已完成文章(无新 task 记录)→ durationQualified=false,不完成;</li>
+ *   <li>场景 6:C 读 1 篇过题 → ledger +1 → 集满 N → completeTask 一次;进度返回 done/target;</li>
+ *   <li>场景 7:C 读 1 篇但答题不通过 → 不计入 ledger,不完成;</li>
+ *   <li>场景 8:A 文章下架/无答题记录 → 门控拒绝(不泄漏完成);</li>
+ *   <li>场景 9:重复记账(唯一键 DuplicateKeyException)→ 视为已计,不重复 +1;completeTask 幂等不重复发奖;</li>
+ *   <li>场景 10:任务过期(时间窗)→ tryCompleteArticleTask 自动完成被拒仅 warn 不抛,进度保留;每日型新 task_id 进度隔离。</li>
+ * </ul>
+ */
+class ReadingCheckinContractTest {
+
+    private static final Long TASK_ID = 1001L;
+    private static final Long MEMBER_ID = 2001L;
+    private static final Long ARTICLE_ID = 3001L;
+    private static final Long OTHER_ARTICLE_ID = 3002L;
+    private static final int MIN_SECONDS = 300;
+    private static final int TARGET_COUNT = 3;
+    private static final double PASS_RATE = 0.6;
+
+    /** 纯 Mockito 下 LambdaQueryWrapper / LambdaUpdateWrapper 需 TableInfo 缓存方能解析列名 */
+    @BeforeAll
+    static void initMpTableInfo() {
+        MapperBuilderAssistant assistant = new MapperBuilderAssistant(new MybatisConfiguration(), "");
+        TableInfoHelper.initTableInfo(assistant, Task.class);
+        TableInfoHelper.initTableInfo(assistant, ArticleReadingRecord.class);
+        TableInfoHelper.initTableInfo(assistant, ArticleQuizRecord.class);
+        TableInfoHelper.initTableInfo(assistant, TaskArticleProgress.class);
+    }
+
+    private ArticleReadingTaskService service;
+    private TaskService taskService;
+    private TaskMapper taskMapper;
+    private ArticleReadingRecordMapper articleReadingRecordMapper;
+    private ArticleQuizRecordMapper articleQuizRecordMapper;
+    private TaskArticleProgressMapper taskArticleProgressMapper;
+    private SysConfigService sysConfigService;
+    private ArticleReadingTaskService gateMock;
+
+    // ==================== Group A:ArticleReadingTaskService ====================
+
+    @BeforeEach
+    void setUp() throws Exception {
+        service = new ArticleReadingTaskService();
+        taskMapper = mock(TaskMapper.class);
+        articleReadingRecordMapper = mock(ArticleReadingRecordMapper.class);
+        articleQuizRecordMapper = mock(ArticleQuizRecordMapper.class);
+        taskArticleProgressMapper = mock(TaskArticleProgressMapper.class);
+        sysConfigService = mock(SysConfigService.class);
+        taskService = mock(TaskService.class);
+
+        inject(service, "taskService", taskService);
+        inject(service, "taskMapper", taskMapper);
+        inject(service, "articleReadingRecordMapper", articleReadingRecordMapper);
+        inject(service, "articleQuizRecordMapper", articleQuizRecordMapper);
+        inject(service, "taskArticleProgressMapper", taskArticleProgressMapper);
+        inject(service, "sysConfigService", sysConfigService);
+    }
+
+    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/2/3/8:模式 A(指定文章 + 答题) --------------------
+
+    private Task articleTask(String actionConfig) {
+        Task task = new Task();
+        task.setId(TASK_ID);
+        task.setActionType("article");
+        task.setActionConfig(actionConfig);
+        task.setFamilyMemberId(MEMBER_ID);
+        task.setMinDurationSeconds(MIN_SECONDS);
+        return task;
+    }
+
+    /** 已通过该文章测试题:score=3/total=5 ≥ 0.6 */
+    private void stubQuizPassed() {
+        ArticleQuizRecord record = new ArticleQuizRecord();
+        record.setArticleId(ARTICLE_ID);
+        record.setMemberId(MEMBER_ID);
+        record.setScore(3);
+        record.setTotalQuestions(5);
+        when(articleQuizRecordMapper.selectList(any(Wrapper.class)))
+                .thenReturn(Collections.singletonList(record));
+    }
+
+    @Test
+    @DisplayName("场景1:A 读够时长+答题通过 → tryCompleteArticleTask 触发 completeTask 一次")
+    void tryComplete_articleQualified_completes() {
+        Task task = articleTask("{\"mode\":\"ARTICLE\",\"articleId\":3001,\"minSeconds\":300,\"requireQuiz\":true,\"quizPassRate\":0.6}");
+        when(taskMapper.selectById(TASK_ID)).thenReturn(task);
+        stubQuizPassed();
+
+        service.tryCompleteArticleTask(TASK_ID, MEMBER_ID, ARTICLE_ID);
+
+        verify(taskService).completeTask(eq(TASK_ID), eq(MEMBER_ID), eq(null), eq(null), eq(null));
+    }
+
+    @Test
+    @DisplayName("场景1补充:A 查询进度 done=1 / quizPassed=true / readingCompleted=true")
+    void progress_articleDone() {
+        Task task = articleTask("{\"mode\":\"ARTICLE\",\"articleId\":3001,\"minSeconds\":300,\"requireQuiz\":true,\"quizPassRate\":0.6}");
+        when(taskMapper.selectById(TASK_ID)).thenReturn(task);
+        stubQuizPassed();
+        when(articleReadingRecordMapper.selectCount(any(Wrapper.class))).thenReturn(1L);
+
+        Map<String, Object> p = service.getTaskProgress(TASK_ID);
+
+        assertEquals("ARTICLE", p.get("mode"));
+        assertEquals(1, p.get("done"));
+        assertEquals(1, p.get("target"));
+        assertEquals(Boolean.TRUE, p.get("quizPassed"));
+        assertEquals(Boolean.TRUE, p.get("readingCompleted"));
+        assertEquals(300, p.get("minSeconds"));
+        assertEquals(ARTICLE_ID, p.get("articleId"));
+    }
+
+    @Test
+    @DisplayName("场景2:A 读够时长+答题不通过 → completeTask 不触发;quizPassed=false")
+    void tryComplete_articleQuizFailed_doesNotComplete() {
+        Task task = articleTask("{\"mode\":\"ARTICLE\",\"articleId\":3001,\"minSeconds\":300,\"requireQuiz\":true,\"quizPassRate\":0.6}");
+        when(taskMapper.selectById(TASK_ID)).thenReturn(task);
+        // 无过题记录(题目记录缺失/分数不足)
+        when(articleQuizRecordMapper.selectList(any(Wrapper.class)))
+                .thenReturn(Collections.singletonList(quizRecord(2, 5))); // 2/5 < 0.6
+
+        service.tryCompleteArticleTask(TASK_ID, MEMBER_ID, ARTICLE_ID);
+
+        verify(taskService, never()).completeTask(anyLong(), anyLong(), any(), any(), any());
+        assertFalse(service.isQuizPassed(TASK_ID, 2, 5));
+    }
+
+    @Test
+    @DisplayName("场景3:A 读够时长但未答题 → completeTask 兜底门控拒绝")
+    void gate_articleNoQuiz_throws() {
+        Task task = articleTask("{\"mode\":\"ARTICLE\",\"articleId\":3001,\"minSeconds\":300,\"requireQuiz\":true,\"quizPassRate\":0.6}");
+        when(taskMapper.selectById(TASK_ID)).thenReturn(task);
+        when(articleQuizRecordMapper.selectList(any(Wrapper.class))).thenReturn(Collections.emptyList());
+
+        IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
+                () -> service.assertArticleTaskQualified(task));
+        assertEquals(ArticleReadingTaskService.MSG_QUIZ_NOT_PASSED, ex.getMessage());
+        // 自动完成路径也不触发
+        service.tryCompleteArticleTask(TASK_ID, MEMBER_ID, ARTICLE_ID);
+        verify(taskService, never()).completeTask(anyLong(), anyLong(), any(), any(), any());
+    }
+
+    @Test
+    @DisplayName("场景8:A 文章已下架/无任何答题记录 → 门控拒绝(不泄漏完成)")
+    void gate_articleUnavailable_throws() {
+        Task task = articleTask("{\"mode\":\"ARTICLE\",\"articleId\":3999,\"minSeconds\":300,\"requireQuiz\":true,\"quizPassRate\":0.6}");
+        when(articleQuizRecordMapper.selectList(any(Wrapper.class))).thenReturn(Collections.emptyList());
+
+        IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
+                () -> service.assertArticleTaskQualified(task));
+        assertEquals(ArticleReadingTaskService.MSG_QUIZ_NOT_PASSED, ex.getMessage());
+    }
+
+    // -------------------- 场景 4/5:模式 B(按时长) --------------------
+
+    private Task durationTask(String actionConfig) {
+        Task task = new Task();
+        task.setId(TASK_ID);
+        task.setActionType("article");
+        task.setActionConfig(actionConfig);
+        task.setFamilyMemberId(MEMBER_ID);
+        task.setMinDurationSeconds(MIN_SECONDS);
+        return task;
+    }
+
+    @Test
+    @DisplayName("场景4:B 选未完成文章读够时长 → onReadingCompleted 触发 completeTask 一次;进度 done=1")
+    void onReadingCompleted_bQualified_completes() {
+        Task task = durationTask("{\"mode\":\"DURATION\",\"minSeconds\":300,\"requireQuiz\":false}");
+        when(taskMapper.selectById(TASK_ID)).thenReturn(task);
+        // reading_completed=1 且 duration ≥ 300 的记录存在(task_id 关联)
+        when(articleReadingRecordMapper.selectCount(any(Wrapper.class))).thenReturn(1L);
+
+        service.onReadingCompleted(TASK_ID, MEMBER_ID, 500L);
+
+        verify(taskService).completeTask(eq(TASK_ID), eq(MEMBER_ID), eq(null), eq(null), eq(null));
+
+        Map<String, Object> p = service.getTaskProgress(TASK_ID);
+        assertEquals("DURATION", p.get("mode"));
+        assertEquals(1, p.get("done"));
+        assertEquals(Boolean.TRUE, p.get("readingCompleted"));
+    }
+
+    @Test
+    @DisplayName("场景5:B 选已完成文章(无新 task 记录)→ 不达标不计数,任务保持 in_progress")
+    void onReadingCompleted_bNoTaskRecord_doesNotComplete() {
+        Task task = durationTask("{\"mode\":\"DURATION\",\"minSeconds\":300,\"requireQuiz\":false}");
+        when(taskMapper.selectById(TASK_ID)).thenReturn(task);
+        // 没有任何 task_id 关联的达标记录(按 task_id 隔离,已完成文章对本次任务无新记录)
+        when(articleReadingRecordMapper.selectCount(any(Wrapper.class))).thenReturn(0L);
+
+        service.onReadingCompleted(TASK_ID, MEMBER_ID, 500L);
+
+        verify(taskService, never()).completeTask(anyLong(), anyLong(), any(), any(), any());
+        Map<String, Object> p = service.getTaskProgress(TASK_ID);
+        assertEquals(0, p.get("done"));
+        assertEquals(Boolean.FALSE, p.get("readingCompleted"));
+    }
+
+    // -------------------- 场景 6/7/9:模式 C(按数量 ledger) --------------------
+
+    private Task countTask(String actionConfig) {
+        Task task = new Task();
+        task.setId(TASK_ID);
+        task.setActionType("article");
+        task.setActionConfig(actionConfig);
+        task.setFamilyMemberId(MEMBER_ID);
+        task.setTargetValue(TARGET_COUNT);
+        return task;
+    }
+
+    @Test
+    @DisplayName("场景6:C 过题记账+1 → 集满 N → completeTask 一次;进度返回 done/target")
+    void onQuizSubmitted_countQualified_recordsAndCompletes() {
+        Task task = countTask("{\"mode\":\"COUNT\",\"targetCount\":3,\"requireQuiz\":true,\"quizPassRate\":0.6}");
+        when(taskMapper.selectById(TASK_ID)).thenReturn(task);
+        // 本次过题记账后 ledger 达 target=3(selectCount 模拟 INSERT 后的当前值)
+        when(taskArticleProgressMapper.selectCount(any(Wrapper.class))).thenReturn(3L);
+
+        service.onQuizSubmitted(TASK_ID, MEMBER_ID, ARTICLE_ID, 4, 5);
+
+        // 记账 trigger(INSERT 成功)
+        ArgumentCaptor<TaskArticleProgress> captor = ArgumentCaptor.forClass(TaskArticleProgress.class);
+        verify(taskArticleProgressMapper).insert(captor.capture());
+        assertEquals(TASK_ID, captor.getValue().getTaskId());
+        assertEquals(ARTICLE_ID, captor.getValue().getArticleId());
+        assertEquals(MEMBER_ID, captor.getValue().getMemberId());
+        // 达 target → 自动完成一次
+        verify(taskService).completeTask(eq(TASK_ID), eq(MEMBER_ID), eq(null), eq(null), eq(null));
+
+        Map<String, Object> p = service.getTaskProgress(TASK_ID);
+        assertEquals("COUNT", p.get("mode"));
+        assertEquals(3, p.get("done"));
+        assertEquals(3, p.get("target"));
+    }
+
+    @Test
+    @DisplayName("场景6补充:C 未达 target 不完成(ledger 1/3),进度返回 done=1/target=3")
+    void onQuizSubmitted_countBelowTarget_noComplete() {
+        Task task = countTask("{\"mode\":\"COUNT\",\"targetCount\":3,\"requireQuiz\":true,\"quizPassRate\":0.6}");
+        when(taskMapper.selectById(TASK_ID)).thenReturn(task);
+        when(taskArticleProgressMapper.selectCount(any(Wrapper.class))).thenReturn(1L);
+
+        service.onQuizSubmitted(TASK_ID, MEMBER_ID, ARTICLE_ID, 4, 5);
+
+        verify(taskArticleProgressMapper).insert(any(TaskArticleProgress.class));
+        verify(taskService, never()).completeTask(anyLong(), anyLong(), any(), any(), any());
+    }
+
+    @Test
+    @DisplayName("场景7:C 过题未通过 → 不计入 ledger,不完成")
+    void onQuizSubmitted_countQuizFailed_doesNothing() {
+        Task task = countTask("{\"mode\":\"COUNT\",\"targetCount\":3,\"requireQuiz\":true,\"quizPassRate\":0.6}");
+        when(taskMapper.selectById(TASK_ID)).thenReturn(task);
+
+        service.onQuizSubmitted(TASK_ID, MEMBER_ID, ARTICLE_ID, 2, 5); // 2/5 < 0.6
+
+        verify(taskArticleProgressMapper, never()).insert(any(TaskArticleProgress.class));
+        verify(taskService, never()).completeTask(anyLong(), anyLong(), any(), any(), any());
+    }
+
+    @Test
+    @DisplayName("场景9:C 重复记账(唯一键冲突)→ 视为已计,不重复 +1,不重复完成")
+    void recordArticleProgress_duplicate_returnsFalse() {
+        when(taskArticleProgressMapper.insert(any(TaskArticleProgress.class)))
+                .thenThrow(new DuplicateKeyException("uk_task_article dup"));
+
+        boolean first = service.recordArticleProgress(TASK_ID, MEMBER_ID, ARTICLE_ID);
+
+        assertFalse(first);
+        verify(taskArticleProgressMapper).insert(any(TaskArticleProgress.class));
+    }
+
+    @SuppressWarnings("unchecked")
+    @Test
+    @DisplayName("countArticleProgress:SQL 段含 task_id 过滤(每日型按 task_id 天然隔离)")
+    void countArticleProgress_scopedByTaskId() {
+        when(taskArticleProgressMapper.selectCount(any(Wrapper.class))).thenReturn(2L);
+
+        int count = service.countArticleProgress(TASK_ID);
+
+        assertEquals(2, count);
+        ArgumentCaptor<Wrapper<TaskArticleProgress>> captor = ArgumentCaptor.forClass(Wrapper.class);
+        verify(taskArticleProgressMapper).selectCount(captor.capture());
+        assertTrue(captor.getValue().getSqlSegment().contains("task_id"),
+                "ledger 计数必须按 task_id 过滤(每日型新 task_id 进度隔离)");
+    }
+
+    // -------------------- 场景 10:过期 / 每日型隔离 --------------------
+
+    @Test
+    @DisplayName("场景10:任务过期(时间窗)→ tryComplete 自动完成被拒仅 warn 不抛;进度/进度台账保留")
+    void tryComplete_timeWindowRejected_swallowsException() {
+        Task task = durationTask("{\"mode\":\"DURATION\",\"minSeconds\":300,\"requireQuiz\":false}");
+        when(taskMapper.selectById(TASK_ID)).thenReturn(task);
+        when(articleReadingRecordMapper.selectCount(any(Wrapper.class))).thenReturn(1L);
+        when(taskService.completeTask(anyLong(), anyLong(), any(), any(), any()))
+                .thenThrow(new IllegalArgumentException("已过截止时间 23:00,无法提交"));
+
+        // 不向上抛(答题/阅读上报主流程不被打断)
+        service.tryCompleteArticleTask(TASK_ID, MEMBER_ID, null);
+
+        verify(taskService).completeTask(eq(TASK_ID), eq(MEMBER_ID), eq(null), eq(null), eq(null));
+        // 进度保留:ledger/reading record 仍可查
+        Map<String, Object> p = service.getTaskProgress(TASK_ID);
+        assertEquals(1, p.get("done"));
+    }
+
+    @Test
+    @DisplayName("场景10补充:每日型新 task_id → 进度按任务实例隔离,不跨任务累计")
+    void countArticleProgress_dailyIsolation() {
+        // 任务 A 已计 2 篇;任务 B(每日新实例)尚无进度
+        when(taskArticleProgressMapper.selectCount(any(Wrapper.class)))
+                .thenReturn(2L)
+                .thenReturn(0L);
+
+        assertEquals(2, service.countArticleProgress(TASK_ID));
+        assertEquals(0, service.countArticleProgress(TASK_ID + 1));
+    }
+
+    // -------------------- 门控(assertArticleTaskQualified)--------------------
+
+    @Test
+    @DisplayName("B 模式未达标 → 门控拒绝「阅读时长不足」")
+    void gate_durationNotQualified_throws() {
+        Task task = durationTask("{\"mode\":\"DURATION\",\"minSeconds\":300,\"requireQuiz\":false}");
+        when(articleReadingRecordMapper.selectCount(any(Wrapper.class))).thenReturn(0L);
+
+        IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
+                () -> service.assertArticleTaskQualified(task));
+        assertEquals(ArticleReadingTaskService.MSG_DURATION_NOT_ENOUGH, ex.getMessage());
+    }
+
+    @Test
+    @DisplayName("C 模式进度不足 → 门控拒绝「阅读进度不足」")
+    void gate_countNotEnough_throws() {
+        Task task = countTask("{\"mode\":\"COUNT\",\"targetCount\":3,\"requireQuiz\":true,\"quizPassRate\":0.6}");
+        when(taskArticleProgressMapper.selectCount(any(Wrapper.class))).thenReturn(1L);
+
+        IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
+                () -> service.assertArticleTaskQualified(task));
+        assertEquals(ArticleReadingTaskService.MSG_PROGRESS_NOT_ENOUGH, ex.getMessage());
+    }
+
+    @Test
+    @DisplayName("配置缺失/解析失败 → 门控拒绝「阅读任务缺少配置」")
+    void gate_noConfig_throws() {
+        Task task = articleTask(null);
+        IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
+                () -> service.assertArticleTaskQualified(task));
+        assertEquals(ArticleReadingTaskService.MSG_NO_CONFIG, ex.getMessage());
+
+        Task badJson = articleTask("{bad json");
+        IllegalArgumentException ex2 = assertThrows(IllegalArgumentException.class,
+                () -> service.assertArticleTaskQualified(badJson));
+        assertEquals(ArticleReadingTaskService.MSG_NO_CONFIG, ex2.getMessage());
+    }
+
+    @Test
+    @DisplayName("非 article 任务 / null 任务 → 门控放行")
+    void gate_nonArticle_skips() {
+        Task normal = new Task();
+        normal.setId(1L);
+        normal.setActionType(null);
+        service.assertArticleTaskQualified(normal); // 不抛即放行
+
+        service.assertArticleTaskQualified(null);
+    }
+
+    // -------------------- parseConfig / 工具 --------------------
+
+    @Test
+    @DisplayName("parseConfig:完整配置解析(ARTICLE)")
+    void parseConfig_article() {
+        Task task = articleTask("{\"mode\":\"ARTICLE\",\"articleId\":3001,\"minSeconds\":120,\"requireQuiz\":true,\"quizPassRate\":0.75}");
+        ArticleReadingTaskService.ReadingTaskConfig cfg = service.parseConfig(task);
+        assertNotNull(cfg);
+        assertEquals("ARTICLE", cfg.mode);
+        assertEquals(ARTICLE_ID, cfg.articleId);
+        assertEquals(120, cfg.minSeconds);
+        assertTrue(cfg.requireQuiz);
+        assertEquals(0.75, cfg.quizPassRate, 1e-9);
+    }
+
+    @Test
+    @DisplayName("parseConfig:缺 mode 时按已填字段推断")
+    void parseConfig_modeInference() {
+        ArticleReadingTaskService.ReadingTaskConfig byArticle = service.parseConfig(
+                articleTask("{\"articleId\":3001}"));
+        assertEquals("ARTICLE", byArticle.mode);
+
+        ArticleReadingTaskService.ReadingTaskConfig byTarget = service.parseConfig(
+                articleTask("{\"targetCount\":3}"));
+        assertEquals("COUNT", byTarget.mode);
+
+        ArticleReadingTaskService.ReadingTaskConfig bySeconds = service.parseConfig(
+                durationTask("{\"minSeconds\":300}"));
+        assertEquals("DURATION", bySeconds.mode);
+    }
+
+    @Test
+    @DisplayName("parseConfig:B 模式 requireQuiz 恒 false;quizPassRate 缺省取 sysConfig 再缺省 0.6")
+    void parseConfig_duration_requireQuizFalse_andRateFallback() {
+        when(sysConfigService.getValue(ArticleReadingTaskService.QUIZ_PASS_THRESHOLD_CONFIG_KEY)).thenReturn("0.8");
+        ArticleReadingTaskService.ReadingTaskConfig cfg = service.parseConfig(
+                durationTask("{\"mode\":\"DURATION\",\"minSeconds\":300}"));
+        assertEquals("DURATION", cfg.mode);
+        assertFalse(cfg.requireQuiz);
+        assertEquals(0.8, cfg.quizPassRate, 1e-9);
+
+        when(sysConfigService.getValue(ArticleReadingTaskService.QUIZ_PASS_THRESHOLD_CONFIG_KEY)).thenReturn(null);
+        ArticleReadingTaskService.ReadingTaskConfig cfg2 = service.parseConfig(
+                durationTask("{\"mode\":\"DURATION\",\"minSeconds\":300}"));
+        assertEquals(ArticleReadingTaskService.DEFAULT_QUIZ_PASS_RATE, cfg2.quizPassRate, 1e-9);
+    }
+
+    @Test
+    @DisplayName("articleQuizPassed:存在过题记录 → true;无记录/未达阈值 → false")
+    void articleQuizPassed() {
+        stubQuizPassed();
+        assertTrue(service.articleQuizPassed(MEMBER_ID, ARTICLE_ID, PASS_RATE));
+
+        when(articleQuizRecordMapper.selectList(any(Wrapper.class))).thenReturn(Collections.emptyList());
+        assertFalse(service.articleQuizPassed(MEMBER_ID, ARTICLE_ID, PASS_RATE));
+
+        assertFalse(service.articleQuizPassed(null, ARTICLE_ID, PASS_RATE));
+        assertFalse(service.articleQuizPassed(MEMBER_ID, null, PASS_RATE));
+    }
+
+    @Test
+    @DisplayName("durationQualified:达标 → true;时长不足/无关联记录 → false")
+    void durationQualified() {
+        when(articleReadingRecordMapper.selectCount(any(Wrapper.class))).thenReturn(1L);
+        assertTrue(service.durationQualified(TASK_ID, MEMBER_ID, MIN_SECONDS));
+
+        when(articleReadingRecordMapper.selectCount(any(Wrapper.class))).thenReturn(0L);
+        assertFalse(service.durationQualified(TASK_ID, MEMBER_ID, MIN_SECONDS));
+        assertFalse(service.durationQualified(TASK_ID, MEMBER_ID, 0));
+        assertFalse(service.durationQualified(null, MEMBER_ID, MIN_SECONDS));
+    }
+
+    @Test
+    @DisplayName("unfinished-ids:返回该成员已 reading_completed=1 的文章 id 集合与 total")
+    void unfinishedArticleIds() {
+        ArticleReadingRecord r1 = new ArticleReadingRecord();
+        r1.setArticleId(3001L);
+        ArticleReadingRecord r2 = new ArticleReadingRecord();
+        r2.setArticleId(3002L);
+        when(articleReadingRecordMapper.selectList(any(Wrapper.class)))
+                .thenReturn(Arrays.asList(r1, r2));
+
+        Map<String, Object> m = service.getUnfinishedArticleIds(MEMBER_ID);
+
+        @SuppressWarnings("unchecked")
+        List<Long> ids = (List<Long>) m.get("completedArticleIds");
+        assertEquals(2, ids.size());
+        assertEquals(2, m.get("total"));
+        assertTrue(ids.contains(3001L));
+        assertTrue(ids.contains(3002L));
+    }
+
+    @Test
+    @DisplayName("getTaskProgress:任务不存在 / 配置缺失 → 抛对应文案")
+    void progress_errors() {
+        when(taskMapper.selectById(TASK_ID)).thenReturn(null);
+        IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
+                () -> service.getTaskProgress(TASK_ID));
+        assertEquals(ArticleReadingTaskService.MSG_TASK_NOT_FOUND, ex.getMessage());
+
+        when(taskMapper.selectById(TASK_ID)).thenReturn(articleTask(null));
+        IllegalArgumentException ex2 = assertThrows(IllegalArgumentException.class,
+                () -> service.getTaskProgress(TASK_ID));
+        assertEquals(ArticleReadingTaskService.MSG_NO_CONFIG, ex2.getMessage());
+    }
+
+    @Test
+    @DisplayName("isTaskCompleted:completed → true;in_progress/不存在 → false")
+    void isTaskCompleted() {
+        Task done = new Task();
+        done.setId(TASK_ID);
+        done.setStatus("completed");
+        when(taskMapper.selectById(TASK_ID)).thenReturn(done);
+        assertTrue(service.isTaskCompleted(TASK_ID));
+
+        done.setStatus("in_progress");
+        assertFalse(service.isTaskCompleted(TASK_ID));
+        assertFalse(service.isTaskCompleted(null));
+    }
+
+    // ==================== Group B:TaskService.completeTask 兜底门控(§5.2) ====================
+
+    @Test
+    @DisplayName("§5.2:article 任务未过门控 → completeTask 抛对应文案(防前端绕过)")
+    void completeTask_articleGateRejected() throws Exception {
+        TaskService realTaskService = new TaskService();
+        TaskMapper tm = mock(TaskMapper.class);
+        FamilyMemberMapper fmm = mock(FamilyMemberMapper.class);
+        gateMock = mock(ArticleReadingTaskService.class);
+        inject(realTaskService, "taskMapper", tm);
+        inject(realTaskService, "familyMemberMapper", fmm);
+        inject(realTaskService, "articleReadingTaskService", gateMock);
+
+        Task task = new Task();
+        task.setId(TASK_ID);
+        task.setActionType("article");
+        task.setActionConfig("{\"mode\":\"DURATION\",\"minSeconds\":300,\"requireQuiz\":false}");
+        task.setStatus("pending");
+        task.setFamilyMemberId(MEMBER_ID);
+        when(tm.selectById(TASK_ID)).thenReturn(task);
+        org.mockito.Mockito.doThrow(new IllegalArgumentException(ArticleReadingTaskService.MSG_DURATION_NOT_ENOUGH))
+                .when(gateMock).assertArticleTaskQualified(task);
+
+        IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
+                () -> realTaskService.completeTask(TASK_ID, MEMBER_ID, null, null, null));
+        assertEquals(ArticleReadingTaskService.MSG_DURATION_NOT_ENOUGH, ex.getMessage());
+        verify(gateMock).assertArticleTaskQualified(task);
+    }
+
+    @Test
+    @DisplayName("§5.2:非 article 任务不触发门控(既有任务完成行为不变)")
+    void completeTask_nonArticleSkipsGate() throws Exception {
+        TaskService realTaskService = new TaskService();
+        TaskMapper tm = mock(TaskMapper.class);
+        FamilyMemberMapper fmm = mock(FamilyMemberMapper.class);
+        gateMock = mock(ArticleReadingTaskService.class);
+        // familyMemberMapper 供 T24-A 幂等结果取余额(此处返回 null 结余 0 即可)
+        inject(realTaskService, "taskMapper", tm);
+        inject(realTaskService, "familyMemberMapper", fmm);
+        inject(realTaskService, "articleReadingTaskService", gateMock);
+
+        // 任务已是完成态 → T24-A 幂等早返回,绝不应触达走阁门控
+        Task task = new Task();
+        task.setId(TASK_ID);
+        task.setActionType(null); // 非文章任务
+        task.setStatus("completed");
+        task.setFamilyMemberId(MEMBER_ID);
+        when(tm.selectById(TASK_ID)).thenReturn(task);
+
+        Map<String, Object> result = realTaskService.completeTask(TASK_ID, MEMBER_ID, null, null, null);
+
+        assertNotNull(result);
+        assertEquals(0, result.get("pointsEarned"));
+        verify(gateMock, never()).assertArticleTaskQualified(any(Task.class));
+    }
+
+    // ==================== 工具 ====================
+
+    private ArticleQuizRecord quizRecord(int score, int total) {
+        ArticleQuizRecord record = new ArticleQuizRecord();
+        record.setArticleId(ARTICLE_ID);
+        record.setMemberId(MEMBER_ID);
+        record.setScore(score);
+        record.setTotalQuestions(total);
+        return record;
+    }
+}