API-INFO-000 P0 | M8 里程碑总设计文档 #105

New Issue

wangdl · 2026-06-07T11:03:17+08:00

wangdl commented

2026-06-07 11:03:17 +08:00

M8：学习信息收集与基础分析闭环

审查修正后的执行顺序

第 0 批：数据源和协议修正（4个）
  #124 API-INFO-000 materialId 映射确认
  #106 API-INFO-001 阅读事件上传协议
  #125 API-INFO-004A 错误码 / 警告码

第 1 批：Schema 基础（4个）
  #107 API-INFO-002 ReadingEvent 表
  #108 API-INFO-003 MaterialReadingProgress 表
  #126 API-INFO-006A LearningSession 扩展
  #127 API-INFO-008A DailyLearningActivity 扩展

第 2 批：上报和校验（2个）
  #109 API-INFO-004 批量上报接口
  #110 API-INFO-005 去重与校验

第 3 批：聚合（3个）
  #111 API-INFO-006 聚合到 LearningSession
  #112 API-INFO-007 聚合到 MaterialReadingProgress
  #113 API-INFO-008 聚合到 DailyLearningActivity

第 4 批：查询接口（5个）
  #114 API-INFO-009 阅读进度查询
  #115 API-INFO-010 首页继续学习
  #116 API-INFO-011 summary
  #117 API-INFO-012 纯数据 trend
  #118 API-INFO-013 heatmap 日期过滤

第 5 批：收尾（4个）
  #120 API-INFO-015 懒清理 interrupted session
  #121 API-INFO-016 主链路 E2E 测试
  #122 API-INFO-017 防重复统计测试
  #123 API-INFO-018 文档

后置 P2:
  #119 API-INFO-014 LearningRecord 写入

核心设计决策

materialId = KnowledgeSource.id，不存在则 failed
activeSecondsDelta 由 iOS 做差值转换，API 只收增量
MaterialClosed 无 position 时不覆盖已存 position
上报接口不返回 latestProgress
activeSecondsDelta=0 合法，>300 截断不拒绝
同步聚合，不用 worker
不用 @nestjs/schedule，用写路径懒清理

最小验收链路

POST /reading-events/batch → ReadingEvent → LearningSession → 
MaterialReadingProgress → DailyLearningActivity → 
GET /learning/continue → GET /learning/summary

## M8：学习信息收集与基础分析闭环 ### 审查修正后的执行顺序 ``` 第 0 批：数据源和协议修正（4个） #124 API-INFO-000 materialId 映射确认 #106 API-INFO-001 阅读事件上传协议 #125 API-INFO-004A 错误码 / 警告码第 1 批：Schema 基础（4个） #107 API-INFO-002 ReadingEvent 表 #108 API-INFO-003 MaterialReadingProgress 表 #126 API-INFO-006A LearningSession 扩展 #127 API-INFO-008A DailyLearningActivity 扩展第 2 批：上报和校验（2个） #109 API-INFO-004 批量上报接口 #110 API-INFO-005 去重与校验第 3 批：聚合（3个） #111 API-INFO-006 聚合到 LearningSession #112 API-INFO-007 聚合到 MaterialReadingProgress #113 API-INFO-008 聚合到 DailyLearningActivity 第 4 批：查询接口（5个） #114 API-INFO-009 阅读进度查询 #115 API-INFO-010 首页继续学习 #116 API-INFO-011 summary #117 API-INFO-012 纯数据 trend #118 API-INFO-013 heatmap 日期过滤第 5 批：收尾（4个） #120 API-INFO-015 懒清理 interrupted session #121 API-INFO-016 主链路 E2E 测试 #122 API-INFO-017 防重复统计测试 #123 API-INFO-018 文档后置 P2: #119 API-INFO-014 LearningRecord 写入 ``` ### 核心设计决策 1. materialId = KnowledgeSource.id，不存在则 failed 2. activeSecondsDelta 由 iOS 做差值转换，API 只收增量 3. MaterialClosed 无 position 时不覆盖已存 position 4. 上报接口不返回 latestProgress 5. activeSecondsDelta=0 合法，>300 截断不拒绝 6. 同步聚合，不用 worker 7. 不用 @nestjs/schedule，用写路径懒清理 ### 最小验收链路 ``` POST /reading-events/batch → ReadingEvent → LearningSession → MaterialReadingProgress → DailyLearningActivity → GET /learning/continue → GET /learning/summary ```

wangdl added this to the M8：学习信息收集与基础分析闭环 milestone 2026-06-07 11:03:17 +08:00

~~wangdl referenced this issue 2026-06-07 11:03:38 +08:00~~

API-INFO-001 P0 | 阅读事件上传协议文档【status:todo】 #106

~~wangdl referenced this issue 2026-06-07 11:03:38 +08:00~~

API-INFO-003 P0 | 新增 ReadingEvent 表【status:todo】 #107

~~wangdl referenced this issue 2026-06-07 11:03:38 +08:00~~

API-INFO-004 P0 | 新增 MaterialReadingProgress 表【status:todo】 #108

~~wangdl referenced this issue 2026-06-07 11:03:38 +08:00~~

API-INFO-009 P0 | 实现批量上报阅读事件接口【status:todo】 #109

~~wangdl referenced this issue 2026-06-07 11:03:39 +08:00~~

API-INFO-010 P0 | 事件校验、去重、activeSecondsDelta 处理【status:todo】 #110

~~wangdl referenced this issue 2026-06-07 11:03:39 +08:00~~