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

New Issue

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

wangdl commented

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

目标

定义 API 接收的最终上传协议。Rust 事件和 API 上传事件不是同一个结构。

activeSecondsDelta 语义

Rust active_seconds 为累计值，API 只接收增量 activeSecondsDelta
转换由 iOS 适配层完成

上传结构

type ReadingEventUploadItem = {
  eventId, clientSessionId,
  readingTargetType: 'knowledge_source' | 'temporary_file',
  materialId, eventType, position?, activeSecondsDelta,
  clientTimestampMs, clientTimezoneOffsetMinutes?, sequence,
  platform, appVersion?
}

规则

activeSecondsDelta=0 合法，<0 非法，>300 截断并 warning
eventId 客户端生成用于幂等
materialId 不存在时 failed: MATERIAL_NOT_FOUND/EXPIRED

详见设计文档 API-INFO-000。

## 目标定义 API 接收的最终上传协议。Rust 事件和 API 上传事件不是同一个结构。 ### activeSecondsDelta 语义 - Rust active_seconds 为累计值，API 只接收增量 activeSecondsDelta - 转换由 iOS 适配层完成 ### 上传结构 ```ts type ReadingEventUploadItem = { eventId, clientSessionId, readingTargetType: 'knowledge_source' | 'temporary_file', materialId, eventType, position?, activeSecondsDelta, clientTimestampMs, clientTimezoneOffsetMinutes?, sequence, platform, appVersion? } ``` ### 规则 - activeSecondsDelta=0 合法，<0 非法，>300 截断并 warning - eventId 客户端生成用于幂等 - materialId 不存在时 failed: MATERIAL_NOT_FOUND/EXPIRED 详见设计文档 API-INFO-000。

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

wangdl changed title from ~~API-INFO-001 P0 | 定义阅读事件上传协议~~ to API-INFO-001 P0 | 阅读事件上传协议文档

2026-06-07 11:22:13 +08:00

wangdl changed title from ~~API-INFO-001 P0 | 阅读事件上传协议文档~~ to API-INFO-001 P0 | 阅读事件上传协议文档【status:todo】

2026-06-07 19:04:09 +08:00

wangdl commented

2026-06-07 19:04:09 +08:00

审查结论：当前 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:05:58 +08:00

完成报告

交付

docs/reading-event-api-protocol.md — 阅读事件上传协议文档，包含：

1. 端点定义

POST /reading/events
Authorization: Bearer <jwt>

2. 上传结构（TypeScript 类型）

interface ReadingEventUploadItem {
  eventId: string;              // UUID v4，幂等键
  clientSessionId: string;
  materialId: string;
  eventType: ReadingEventType;  // snake_case
  position?: ReadingPosition;   // camelCase, clamped
  activeSecondsDelta: number;   // 增量（非累计！）
  clientTimestampMs: number;
  sequence: number;
  readingTargetType: "knowledge_source" | "temporary_file";  // iOS 补充
  platform: string;             // iOS 补充
  appVersion?: string;          // iOS 补充
  clientTimezoneOffsetMinutes?: number; // iOS 补充
}

3. Rust → API 字段映射表（11 项）

4. activeSecondsDelta 规则

=0 ✅ 合法
0 <=300 ✅ 正常
300 ⚠️ 截断+warning
<0 ❌ 拒绝

5. 校验规则（8 项）

6. 响应格式（成功/部分失败）

7. 错误码（10 种）

8. 完整请求/响应示例

代码证据

// 核心原则：Rust 事件 ≠ API 上传事件
type ReadingEventUploadItem = {
  // Rust 字段（9 个）
  eventId, clientSessionId, materialId, eventType, position?,
  activeSecondsDelta, clientTimestampMs, sequence,
  // iOS 补充字段（4 个）
  readingTargetType, platform, appVersion?, clientTimezoneOffsetMinutes?
}

## 完成报告 ### 交付 `docs/reading-event-api-protocol.md` — 阅读事件上传协议文档，包含： **1. 端点定义** ``` POST /reading/events Authorization: Bearer <jwt> ``` **2. 上传结构（TypeScript 类型）** ```typescript interface ReadingEventUploadItem { eventId: string; // UUID v4，幂等键 clientSessionId: string; materialId: string; eventType: ReadingEventType; // snake_case position?: ReadingPosition; // camelCase, clamped activeSecondsDelta: number; // 增量（非累计！） clientTimestampMs: number; sequence: number; readingTargetType: "knowledge_source" | "temporary_file"; // iOS 补充 platform: string; // iOS 补充 appVersion?: string; // iOS 补充 clientTimezoneOffsetMinutes?: number; // iOS 补充 } ``` **3. Rust → API 字段映射表（11 项）** **4. activeSecondsDelta 规则** - =0 ✅ 合法 - >0 <=300 ✅ 正常 - >300 ⚠️ 截断+warning - <0 ❌ 拒绝 **5. 校验规则（8 项）** **6. 响应格式**（成功/部分失败） **7. 错误码（10 种）** **8. 完整请求/响应示例** ### 代码证据 ```typescript // 核心原则：Rust 事件 ≠ API 上传事件 type ReadingEventUploadItem = { // Rust 字段（9 个） eventId, clientSessionId, materialId, eventType, position?, activeSecondsDelta, clientTimestampMs, sequence, // iOS 补充字段（4 个） readingTargetType, platform, appVersion?, clientTimezoneOffsetMinutes? } ```

wangdl closed this issue

2026-06-08 20:05:58 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/api-server#106

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

目标

activeSecondsDelta 语义

上传结构

规则

完成报告

交付

代码证据

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