API-INFO-008 P0 | 定义 ReadingEvent 错误码与警告码【status:todo】 #125

New Issue

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

wangdl commented

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

目标

统一接口错误码和警告码，让 iOS 可根据 code 处理。

错误码

MATERIAL_NOT_FOUND, TEMPORARY_MATERIAL_NOT_FOUND, MATERIAL_ACCESS_DENIED,
TEMPORARY_MATERIAL_EXPIRED, INVALID_TARGET_TYPE, INVALID_EVENT_TYPE,
INVALID_TIMESTAMP, INVALID_POSITION, INVALID_ACTIVE_SECONDS,
BATCH_LIMIT_EXCEEDED

警告码

ACTIVE_SECONDS_CAPPED, CLIENT_TIMESTAMP_SKEWED, POSITION_IGNORED,
DUPLICATE_EVENT, OUT_OF_ORDER_EVENT, SOURCE_DELETED

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

## 目标统一接口错误码和警告码，让 iOS 可根据 code 处理。 ### 错误码 MATERIAL_NOT_FOUND, TEMPORARY_MATERIAL_NOT_FOUND, MATERIAL_ACCESS_DENIED, TEMPORARY_MATERIAL_EXPIRED, INVALID_TARGET_TYPE, INVALID_EVENT_TYPE, INVALID_TIMESTAMP, INVALID_POSITION, INVALID_ACTIVE_SECONDS, BATCH_LIMIT_EXCEEDED ### 警告码 ACTIVE_SECONDS_CAPPED, CLIENT_TIMESTAMP_SKEWED, POSITION_IGNORED, DUPLICATE_EVENT, OUT_OF_ORDER_EVENT, SOURCE_DELETED 详见设计文档 API-INFO-000。

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

wangdl changed title from ~~API-INFO-004A P0 | 定义 ReadingEvent 错误码与警告码~~ to API-INFO-008 P0 | 定义 ReadingEvent 错误码与警告码

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

wangdl changed title from ~~API-INFO-008 P0 | 定义 ReadingEvent 错误码与警告码~~ to API-INFO-008 P0 | 定义 ReadingEvent 错误码与警告码【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

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

wangdl commented

2026-06-08 20:11:23 +08:00

完成报告

交付

src/modules/reading-event/reading-event-codes.ts — 统一错误码与警告码定义：

错误码（12 种）— 事件被拒绝（status=failed）：

enum ReadingEventErrorCode {
  MATERIAL_NOT_FOUND              // knowledge_source 不存在
  TEMPORARY_MATERIAL_NOT_FOUND    // temporary_file 不存在
  MATERIAL_ACCESS_DENIED          // 不属于当前用户
  TEMPORARY_MATERIAL_EXPIRED      // 临时文件已过期
  INVALID_TARGET_TYPE             // 未知 readingTargetType
  INVALID_EVENT_TYPE              // 未知 eventType
  INVALID_TIMESTAMP               // 时间戳格式错误
  INVALID_POSITION                // position JSON 格式错误
  INVALID_ACTIVE_SECONDS          // delta < 0
  BATCH_LIMIT_EXCEEDED            // 超过批量上限
  MISSING_CLIENT_SESSION          // 缺少 clientSessionId
  MISSING_MATERIAL_ID             // 缺少 materialId
}

警告码（6 种）— 事件被接受但标记（status=processed + warning）：

enum ReadingEventWarningCode {
  ACTIVE_SECONDS_CAPPED           // delta > 300，已截断
  CLIENT_TIMESTAMP_SKEWED         // 时钟偏差 > 5 min
  POSITION_IGNORED                // position 存在但无效（不拒绝）
  DUPLICATE_EVENT                 // 幂等重放
  OUT_OF_ORDER_EVENT              // 乱序事件（不拒绝）
  SOURCE_DELETED                  // 来源已删除
}

代码证据

// 类型安全引用
import { ReadingEventErrorCode, ReadingEventWarningCode } from "./reading-event-codes";

if (delta < 0) return fail(ReadingEventErrorCode.INVALID_ACTIVE_SECONDS);
if (delta > 300) warning(ReadingEventWarningCode.ACTIVE_SECONDS_CAPPED);

## 完成报告 ### 交付 `src/modules/reading-event/reading-event-codes.ts` — 统一错误码与警告码定义： **错误码（12 种）— 事件被拒绝（status=failed）：** ```typescript enum ReadingEventErrorCode { MATERIAL_NOT_FOUND // knowledge_source 不存在 TEMPORARY_MATERIAL_NOT_FOUND // temporary_file 不存在 MATERIAL_ACCESS_DENIED // 不属于当前用户 TEMPORARY_MATERIAL_EXPIRED // 临时文件已过期 INVALID_TARGET_TYPE // 未知 readingTargetType INVALID_EVENT_TYPE // 未知 eventType INVALID_TIMESTAMP // 时间戳格式错误 INVALID_POSITION // position JSON 格式错误 INVALID_ACTIVE_SECONDS // delta < 0 BATCH_LIMIT_EXCEEDED // 超过批量上限 MISSING_CLIENT_SESSION // 缺少 clientSessionId MISSING_MATERIAL_ID // 缺少 materialId } ``` **警告码（6 种）— 事件被接受但标记（status=processed + warning）：** ```typescript enum ReadingEventWarningCode { ACTIVE_SECONDS_CAPPED // delta > 300，已截断 CLIENT_TIMESTAMP_SKEWED // 时钟偏差 > 5 min POSITION_IGNORED // position 存在但无效（不拒绝） DUPLICATE_EVENT // 幂等重放 OUT_OF_ORDER_EVENT // 乱序事件（不拒绝） SOURCE_DELETED // 来源已删除 } ``` ### 代码证据 ```typescript // 类型安全引用 import { ReadingEventErrorCode, ReadingEventWarningCode } from "./reading-event-codes"; if (delta < 0) return fail(ReadingEventErrorCode.INVALID_ACTIVE_SECONDS); if (delta > 300) warning(ReadingEventWarningCode.ACTIVE_SECONDS_CAPPED); ```

wangdl closed this issue

2026-06-08 20:11:23 +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#125

API-INFO-008 P0 | 定义 ReadingEvent 错误码与警告码 【status:todo】 #125

目标

错误码

警告码

完成报告

交付

代码证据

API-INFO-008 P0 | 定义 ReadingEvent 错误码与警告码【status:todo】 #125