wangdl/api-server
2
0
Fork 0
Code Issues 29 Pull Requests Actions Packages Projects Releases Wiki Activity

API-INFO-000 P0 | 学习信息收集总设计与实体映射 【status:todo】 #128

New Issue
Closed
opened 2026-06-07 11:22:53 +08:00 by wangdl · 2 comments
wangdl commented 2026-06-07 11:22:53 +08:00
Owner
Copy Link

目标

冻结学习信息收集的数据模型、实体映射、readingTargetType、核心聚合链路。

核心设计决策

readingTargetType

knowledge_source: materialId = KnowledgeSource.id, knowledgeBaseId = KnowledgeSource.knowledgeBaseId
temporary_file: materialId = TemporaryReadingMaterial.id, knowledgeBaseId = null (后续可补)

activeSecondsDelta

  • Rust active_seconds 为累计值，API 只收增量 activeSecondsDelta
  • 转换由 iOS 适配层完成，API 不做差值计算

核心链路

ReadingEvent → LearningSession → MaterialReadingProgress → DailyLearningActivity → LearningRecord → continue/summary/trend/heatmap/history

其他决策

  • 上报接口不返回 latestProgress，进度查询独立
  • activeSecondsDelta=0 合法，<0 非法，>300 截断
  • MaterialClosed 无 position 时不覆盖已有 position
  • 同步聚合（暂不用 worker）
  • 不用 @nestjs/schedule，用写路径懒清理

验收标准

  1. docs/learning-info-design.md 存在
  2. 明确 readingTargetType
  3. 明确 materialId 映射
  4. 明确权限校验方式
## 目标 冻结学习信息收集的数据模型、实体映射、readingTargetType、核心聚合链路。 ## 核心设计决策 ### readingTargetType ```text knowledge_source: materialId = KnowledgeSource.id, knowledgeBaseId = KnowledgeSource.knowledgeBaseId temporary_file: materialId = TemporaryReadingMaterial.id, knowledgeBaseId = null (后续可补) ``` ### activeSecondsDelta - Rust active_seconds 为累计值，API 只收增量 activeSecondsDelta - 转换由 iOS 适配层完成，API 不做差值计算 ### 核心链路 ``` ReadingEvent → LearningSession → MaterialReadingProgress → DailyLearningActivity → LearningRecord → continue/summary/trend/heatmap/history ``` ### 其他决策 - 上报接口不返回 latestProgress，进度查询独立 - activeSecondsDelta=0 合法，<0 非法，>300 截断 - MaterialClosed 无 position 时不覆盖已有 position - 同步聚合（暂不用 worker） - 不用 @nestjs/schedule，用写路径懒清理 ## 验收标准 1. docs/learning-info-design.md 存在 2. 明确 readingTargetType 3. 明确 materialId 映射 4. 明确权限校验方式
wangdl added this to the M8：学习信息收集与基础分析闭环 milestone 2026-06-07 11:22:53 +08:00
wangdl changed title from API-INFO-000 P0 | 学习信息收集总设计与实体映射 to API-INFO-000 P0 | 学习信息收集总设计与实体映射 【status:todo】 2026-06-07 19:04:08 +08:00
wangdl commented 2026-06-07 19:04:08 +08:00
Author
Owner
Copy Link

审查结论：当前 API 项目学习信息收集体系基本为全新建设。可复用：JWT Guard、LearningSession 基础表/CRUD、DailyLearningActivity 基础表、ActivityController 部分接口、LearningRecord schema。其余 ReadingEvent/TemporaryMaterial/Progress/批量上报/Processor/聚合/查询接口/错误码/去重/权限/测试/文档均不存在或仅部分存在。

本 Issue: 设计文档不存在。全新建设。

标签: audit:reviewed audit:api-info status:todo work:contract,work:docs

## 审查结论：当前 API 项目学习信息收集体系基本为全新建设。可复用：JWT Guard、LearningSession 基础表/CRUD、DailyLearningActivity 基础表、ActivityController 部分接口、LearningRecord schema。其余 ReadingEvent/TemporaryMaterial/Progress/批量上报/Processor/聚合/查询接口/错误码/去重/权限/测试/文档均不存在或仅部分存在。 **本 Issue**: 设计文档不存在。全新建设。 **标签**: audit:reviewed audit:api-info status:todo work:contract,work:docs
wangdl commented 2026-06-08 20:03:28 +08:00
Author
Owner
Copy Link

完成报告

交付

docs/learning-info-design.md — 学习信息收集总设计文档，包含：

1. readingTargetType 定义

  • knowledge_source: materialId = KnowledgeSource.id, knowledgeBaseId = KnowledgeSource.knowledgeBaseId
  • temporary_file: materialId = TemporaryReadingMaterial.id, knowledgeBaseId = null

2. 实体映射

  • 新增 3 表：ReadingEvent / MaterialReadingProgress / TemporaryReadingMaterial
  • 扩展 2 表：LearningSession (+6 字段) / DailyLearningActivity (+2 字段)
  • 复用 1 表：LearningRecord (不改 schema，扩 recordType)

3. 核心聚合链路

ReadingEvent → LearningSession → MaterialReadingProgress → DailyLearningActivity → LearningRecord → 查询接口

4. 设计决策

  • 同步聚合（暂不用 worker）
  • activeSecondsDelta=0 合法，<0 非法，>300 截断
  • MaterialClosed 无 position 不覆盖已有
  • 乱序事件不拒绝（容忍时钟漂移）

5. 错误码定义：8 种（DUPLICATE_EVENT/INVALID_DELTA/DELTA_EXCEEDED 等）

6. 权限校验：JWT guard + userId + 资源归属

7. 接口列表：8 个接口

## 完成报告 ### 交付 `docs/learning-info-design.md` — 学习信息收集总设计文档，包含： **1. readingTargetType 定义** - `knowledge_source`: materialId = KnowledgeSource.id, knowledgeBaseId = KnowledgeSource.knowledgeBaseId - `temporary_file`: materialId = TemporaryReadingMaterial.id, knowledgeBaseId = null **2. 实体映射** - 新增 3 表：ReadingEvent / MaterialReadingProgress / TemporaryReadingMaterial - 扩展 2 表：LearningSession (+6 字段) / DailyLearningActivity (+2 字段) - 复用 1 表：LearningRecord (不改 schema，扩 recordType) **3. 核心聚合链路** ``` ReadingEvent → LearningSession → MaterialReadingProgress → DailyLearningActivity → LearningRecord → 查询接口 ``` **4. 设计决策** - 同步聚合（暂不用 worker） - activeSecondsDelta=0 合法，<0 非法，>300 截断 - MaterialClosed 无 position 不覆盖已有 - 乱序事件不拒绝（容忍时钟漂移） **5. 错误码定义**：8 种（DUPLICATE_EVENT/INVALID_DELTA/DELTA_EXCEEDED 等） **6. 权限校验**：JWT guard + userId + 资源归属 **7. 接口列表**：8 个接口
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area:activity
活动/统计
area:admin
管理后台
area:admin-api
area:ai
AI/RAG
area:ai-runtime
AI Runtime / AI 分析体系相关
area:analytics
area:api
API 接口
area:auth
认证与授权
area:cos
对象存储
area:database
数据库/Migration
area:import
文件导入/解析
area:knowledge
知识库/知识点
area:learning-info
area:learning-session
area:quiz
测验/自测
area:reading-event
area:reading-progress
area:review
复习系统
area:security
安全相关
audit:api-admin-info
audit:api-info
audit:planned
已完成宏观规划，尚未代码审查
audit:reviewed
blocked-by:api-info-aggregation
blocked-by:api-info-core
blocked-by:api-info-ops
blocked-by:api-info-schema
blocked-by:processor
blocked-by:schema
priority:p0
最高优先级，阻塞发布
priority:p1
高优先级，里程碑必需
priority:p2
中优先级，后续版本
repo:api
API 仓库 Issue
status:blocked
被阻塞
status:done
已完成
status:partial
status:todo
type:aggregation
type:bug
缺陷修复
type:design
设计
type:docs
文档
type:feature
新功能
type:migration
type:refactor
重构
type:test
work:admin-api
work:aggregation
work:api
work:artifact
题目/卡片产物
work:audit
work:circuit-breaker
熔断
work:contract
work:design
架构/协议设计工作
work:docs
work:export
work:extend-existing
work:internal-api
Runtime 内部接口
work:job
Job 调度相关
work:new-module
work:new-table
work:ops
work:query
work:quota
额度/限流
work:schema
Prisma Schema 设计
work:security
work:service
Service 层实现
work:snapshot
Snapshot 构建
work:test
No Label
Milestone
No items
No Milestone M8：学习信息收集与基础分析闭环
Projects
Clear projects
No project
Assignees
Clear assignees
suyun-Claude wangdl
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: wangdl/api-server#128
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?