cfc/docs/superpowers/specs/2026-07-28-article-reading-time-tracking-design.md

文章阅读时长自动跟踪设计

概述

去除文章详情页的"阅读完成"按钮，改为自动跟踪阅读时长——用户进入页面即开始计时，离开/切后台时自动上报。纯统计用途，不涉及积分/任务/答题。

变更清单

数据库

表: article_reading_records

• 新增 article_id BIGINT COMMENT '文章ID'
• 新增 updated_at DATETIME
• 新增索引 INDEX idx_article_child_date (article_id, child_id, read_at)

后端

新 API: POST /api/articles/report-reading-time

请求体:

{
  "articleId": 123,
  "childId": 456,
  "durationSeconds": 185
}

逻辑:

1. 按 article_id + child_id + DATE(read_at) 查找当日已有记录
2. 找到 → UPDATE SET duration_seconds = duration_seconds + :duration, updated_at = NOW()
3. 未找到 → INSERT 新记录
4. 返回 { success: true }，无积分/任务逻辑

实体变更: ArticleReadingRecord.java 新增 articleId 字段

前端

页面: pages/article-center/article-detail.vue

删除:

• "阅读完成"按钮（read-btn）
• onReadComplete 方法
• loadQuiz、onSubmitQuiz、selectAnswer 等答题相关方法
• showQuiz、showResult、quizQuestions 等答题相关状态
• recordArticleRead API 调用（旧版一次性记录）

新增:

• 右上角/边侧阅读时长显示: "已读 3分12秒"
• 计时器按可见性控制:
  • onShow → 开始计时（或恢复）
  • onHide → 暂停计时，上报累计时长
  • onUnload → 最终上报
  • App 级 onShow/onHide 同样处理（小程序切后台）
• 每 30 秒自动同步一次
• 调用新 API /api/articles/report-reading-time

保留:

• 分享按钮
• 文章内容展示
• 底部占位区（只保留分享按钮）

时序

用户进入页面 → onLoad → 加载文章 → 开始计时 → 显示"已读 0秒"
                                                         ↓
                                              每30秒 → 上报当前累计时长
                                                         ↓
用户切后台/隐藏 → onHide → 暂停计时 → 上报累计时长
                    ↓
用户返回 → onShow → 恢复计时
                    ↓
用户离开页面 → onUnload → 最终上报

边界情况

• 未登录用户: 不上报（childId 不存在）
• 无 currentChildId: 不上报
• 网络失败: silent fail，不阻塞用户
• **累计时长": 同一用户同一天阅读同一篇文章，时长累加