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

feat(db): 阅读打卡 T01 数据层——task_article_progress 表(迁移499)+实体/Mapper+API_REFERENCE 契约登记

Agnes Agent 1 час назад
Родитель
Сommit
d10ed92675

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

@@ -3643,6 +3643,10 @@ insertSysConfigSeed("gift_membership_pay_price", "198000", "送会员商品达
         //          写入 product_order_auto_complete 27 字符 > 原列宽 20,触发 Data truncation,
         //          操作日志缺失)。幂等:MODIFY 可重复执行(已是 64 时语义等价 no-op)。
         widenUserOperationLogType();
+
+        // 迁移499: 阅读打卡任务——创建 task_article_progress 表(ARCH-CFC-READING-CHECKIN-001 §3.2):
+        // 模式C按数量记账,uk_task_article(task_id, article_id) 并发防重(每篇过题只计一次),幂等
+        createTaskArticleProgressTable();
     }
 
     /**
@@ -16754,4 +16758,29 @@ log.info("迁移298: 已为无 openid 的 child 账号补齐 family_members 记
                 "INT NULL COMMENT '草稿版本号(并发存两版草稿:后者覆盖且提示冲突)'");
         log.info("迁移496: growth_plans.draft_expires_at / draft_version 列已就绪(plan.draft.save / SC-P-81)");
     }
+
+    /**
+     * 迁移499: 创建阅读打卡任务进度记账表 task_article_progress(ARCH-CFC-READING-CHECKIN-001 §3.2)。
+     *
+     * <p>承载「模式 C 按数量」进度:孩子每读完并答对一篇,记一行 {@code (task_id, article_id, member_id)};
+     * 唯一键 {@code uk_task_article(task_id, article_id)} 保证并发/重复答题下同一任务同一篇文章只计一次
+     * (服务层 INSERT 捕获 {@code DuplicateKeyException} 视为已计,跳过)。幂等(CREATE TABLE IF NOT EXISTS)。</p>
+     */
+    private void createTaskArticleProgressTable() {
+        try {
+            jdbcTemplate.execute("CREATE TABLE IF NOT EXISTS task_article_progress ("
+                    + "id BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '主键ID', "
+                    + "task_id BIGINT NOT NULL COMMENT '任务实例ID(tasks.id)', "
+                    + "article_id BIGINT NOT NULL COMMENT '文章ID(articles.id)', "
+                    + "member_id BIGINT NOT NULL COMMENT '执行成员ID(family_members.id)', "
+                    + "created_at DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '记账时间', "
+                    + "UNIQUE KEY uk_task_article (task_id, article_id), "
+                    + "INDEX idx_task (task_id), "
+                    + "INDEX idx_member_article (member_id, article_id)"
+                    + ") ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='阅读打卡任务-已计入进度的文章'");
+            log.info("迁移499: task_article_progress 表已就绪(reading.checkin / ARCH-CFC-READING-CHECKIN-001)");
+        } catch (Exception e) {
+            log.warn("迁移499: task_article_progress 表创建失败(忽略): {}", e.getMessage());
+        }
+    }
 }

+ 45 - 0
cfc-backend/src/main/java/com/etotem/cfc/entity/TaskArticleProgress.java

@@ -0,0 +1,45 @@
+package com.etotem.cfc.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+import java.io.Serializable;
+import java.util.Date;
+
+/**
+ * 阅读打卡任务-已计入进度的文章(ledger 表)。
+ *
+ * <p>承载「模式 C 按数量」任务进度记账:孩子每读完并答对一篇指定/自由文章,
+ * 记一行 {@code (task_id, article_id, member_id)}。唯一键
+ * {@code uk_task_article(task_id, article_id)} 保证并发/重复答题下同一任务同一篇文章
+ * 只计一次(服务层 INSERT 捕获 {@code DuplicateKeyException} 视为已计,跳过)。</p>
+ *
+ * <p>每日型任务由 {@code RepeatTaskGenerator} 每日生成新任务实例(新 task_id),
+ * ledger 按 task_id 天然隔离,每日进度自动重置,无需额外逻辑。</p>
+ *
+ * <p>设计来源:ARCH-CFC-READING-CHECKIN-001 §3.2(迁移 499)。
+ * 模式 A(指定文章读+答题)与模式 B(按时长读)不落此表——
+ * A 用 {@code article_quiz_records} 存在性判定,B 用 {@code article_reading_records.task_id}
+ * 关联记录判定,仅模式 C 用本表累计篇数。</p>
+ */
+@Data
+@TableName("task_article_progress")
+public class TaskArticleProgress implements Serializable {
+
+    @TableId(type = IdType.AUTO)
+    private Long id;
+
+    /** 任务实例ID(tasks.id) */
+    private Long taskId;
+
+    /** 文章ID(articles.id) */
+    private Long articleId;
+
+    /** 执行成员ID(family_members.id) */
+    private Long memberId;
+
+    /** 记账时间 */
+    private Date createdAt;
+}

+ 16 - 0
cfc-backend/src/main/java/com/etotem/cfc/mapper/TaskArticleProgressMapper.java

@@ -0,0 +1,16 @@
+package com.etotem.cfc.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.etotem.cfc.entity.TaskArticleProgress;
+import org.apache.ibatis.annotations.Mapper;
+
+/**
+ * 阅读打卡任务-已计入进度的文章 Mapper。
+ *
+ * <p>继承 {@link BaseMapper},提供常规 CRUD;模式 C 记账走
+ * MyBatis-Plus insert(唯一键 {@code uk_task_article} 捕获
+ * {@code DuplicateKeyException} 幂等防重),无需自定义 XML。</p>
+ */
+@Mapper
+public interface TaskArticleProgressMapper extends BaseMapper<TaskArticleProgress> {
+}

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

@@ -4559,6 +4559,18 @@ CREATE TABLE IF NOT EXISTS article_quiz_records (
   INDEX idx_article (article_id)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='文章答题记录表';
 
+-- 阅读打卡任务-已计入进度的文章(模式C按数量记账,uk_task_article 并发防重,迁移499)
+CREATE TABLE IF NOT EXISTS task_article_progress (
+  id BIGINT AUTO_INCREMENT PRIMARY KEY,
+  task_id BIGINT NOT NULL COMMENT '任务实例ID(tasks.id)',
+  article_id BIGINT NOT NULL COMMENT '文章ID(articles.id)',
+  member_id BIGINT NOT NULL COMMENT '执行成员ID(family_members.id)',
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE KEY uk_task_article (task_id, article_id),
+  INDEX idx_task (task_id),
+  INDEX idx_member_article (member_id, article_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='阅读打卡任务-已计入进度的文章';
+
 -- ============================================================
 -- 统一报告汇总表(report_summary)
 -- ============================================================

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

@@ -765,6 +765,39 @@ find cfc-backend/src/main/java -name "*XxxService.java" -o -name "*XxxController
 | `POST /api/content-sections/list` | 区块列表 |
 | `POST /api/content/related-items` | 内容关联推荐:以活动/文章/商品任一为源(`sourceType`+`sourceId`),按共享标签一次返回 `data.articles / data.activities / data.products` 三组(支持 `size`/`page` 分页,游客可访问) |
 
+**阅读打卡任务(`/api/articles/*` 文章任务门控,ARCH-CFC-READING-CHECKIN-001 §4)**
+
+> 在既有任务系统 + 文章模块之上新增「阅读打卡任务」三种模式,不改动既有「读文章自动完成/无 quiz 阅读」行为。统一 `@PostMapping`、响应统一 `Result<T>`(code 200 成功 / 500 业务错误 / 401 未登录由拦截器返回),入参统一 `Map<String,Object>` + `ParamUtils`。契约先行登记,供 T02(后端三模式判定)/T03(前端三模式入口)并行开工。
+
+**① 改造(加可选入参,向后兼容,taskId 为空走原逻辑不变)**
+
+| 接口 | 改造点 | 说明 |
+|------|--------|------|
+| `POST /api/articles/report-reading-time` | 入参加 `taskId`(可选) | 当 taskId 存在:写入 `article_reading_records.task_id`;若该记录达标(reading_completed=1 且 duration ≥ minSeconds)且任务为模式 B(`mode:"DURATION"`)→ 后端自动 `completeTask` |
+| `POST /api/articles/quiz/submit` | 入参加 `taskId`(可选) | 当 taskId 存在且任务为模式 A/C:A(`mode:"ARTICLE"`)→ 答题通过(score/total ≥ passRate)即 `completeTask`;C(`mode:"COUNT"`)→ 记账 +1,达 target 即 `completeTask`;未过题 → 返回 `quizPassed:false` 供前端提示重考。返回值新增 `quizPassed` / `taskCompleted` |
+
+**② 新增端点**
+
+| 路径 | 登录 | 入参 | 返回 data | 主要错误(500 + message,前端原样 toast) |
+|------|------|------|-----------|------------------------------------------|
+| `POST /api/articles/reading-task/progress` | 是 | `{ taskId }` | `{ mode(ARTICLE/DURATION/COUNT), done, target, quizPassed, readingCompleted, minSeconds, articleId }`(done=ledger count(C)或 0/1(A 是否过题、B 是否达标)) | "阅读任务缺少配置"、"任务不存在" |
+| `POST /api/articles/unfinished-ids` | 是 | `{ memberId }` | `{ completedArticleIds: [..], total: n }`(该成员已 `reading_completed=1` 的文章 id 集合) | — |
+
+**③ action_config 键名契约(`action_type='article'`,JSON 字符串入库到 `tasks.action_config`,统一 camelCase)**
+
+| 键 | 类型 | A(ARTICLE) | B(DURATION) | C(COUNT) | 说明 |
+|----|------|:-:|:-:|:-:|------|
+| `mode` | String | ✓ | ✓ | ✓ | 必填;缺失则按 articleId/minSeconds/targetCount 推断 |
+| `articleId` | Long | ✓ | — | — | 必填,>0;存在且 status='published' |
+| `minSeconds` | Int | ✓ | ✓ | — | A/B 必填,>0;A/B 同时写 `tasks.min_duration_seconds` 冗余 |
+| `targetCount` | Int | — | — | ✓ | C 必填(或 `tasks.target_value`),>0 |
+| `requireQuiz` | Boolean | ✓ | — | ✓ | A/C 默认 true;B 恒 false |
+| `quizPassRate` | Double | 可选 | — | 可选 | 0 < rate ≤ 1;缺省取 `quiz.pass_threshold` 系统配置,再缺省 0.6 |
+
+错误文案:`阅读任务缺少配置` / `请选择文章` / `文章不存在或已下架` / `请输入有效阅读时长` / `请输入有效阅读篇数` / `答题通过率需大于0且不超过1`。
+
+---
+
 ### 4.13 管理员接口(`/api/admin/*`)
 
 > 管理员接口需 `role=admin`,详见 `AdminInterceptor`。