DOC-FULL-000 P0 | Document Runtime 完整架构文档 v2 【status:todo】 #49

New Issue

wangdl · 2026-06-07T11:33:10+08:00

wangdl commented

2026-06-07 11:33:10 +08:00

目标

docs/document-runtime-architecture.md

关键设计决策

D1: Rust 只保存 materialId，不保存 readingTargetType
D2: V1 保留 deprecated，V2 新增独立模块
D3: clientSessionId 由 Rust 生成 UUID
D4: iOS 控制 tick 节奏，Rust 计算 delta
D5: Position JSON 使用 camelCase
D6: progress clamp 到 0~1
D7: ack 后立即从 buffer 删除事件

必须包含

Rust/iOS/API 三端职责边界
ReadingMaterialRef 替代 ReadingTargetType
ReadingSessionV2 + ReadingEventV2
ActiveTimeTracker
EventBuffer ack 机制
V1→V2 迁移策略
与 API learning-info 协议映射

## 目标 docs/document-runtime-architecture.md ## 关键设计决策 D1: Rust 只保存 materialId，不保存 readingTargetType D2: V1 保留 deprecated，V2 新增独立模块 D3: clientSessionId 由 Rust 生成 UUID D4: iOS 控制 tick 节奏，Rust 计算 delta D5: Position JSON 使用 camelCase D6: progress clamp 到 0~1 D7: ack 后立即从 buffer 删除事件 ## 必须包含 1. Rust/iOS/API 三端职责边界 2. ReadingMaterialRef 替代 ReadingTargetType 3. ReadingSessionV2 + ReadingEventV2 4. ActiveTimeTracker 5. EventBuffer ack 机制 6. V1→V2 迁移策略 7. 与 API learning-info 协议映射

wangdl added this to the M-DOC-FULL：Document Runtime 完整阅读内核与学习事件协议 milestone 2026-06-07 11:33:10 +08:00

wangdl changed title from ~~DOC-FULL-000 P0 | Document Runtime 完整架构设计文档~~ to DOC-FULL-000 P0 | Document Runtime 完整架构文档 v2

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

wangdl changed title from ~~DOC-FULL-000 P0 | Document Runtime 完整架构文档 v2~~ to DOC-FULL-000 P0 | Document Runtime 完整架构文档 v2 【status:todo】

2026-06-07 19:14:59 +08:00

wangdl commented

2026-06-07 19:15:00 +08:00

审查结论：document runtime 当前有文件类型识别/MaterialType/PreviewMode/DocumentInfo(基本)/Markdown解析/Text解析/ImageMeta/Search(V1 Markdown+Text)/NoteAnchor(V1)/ReadingEvent(V1)/ReadingPosition(V1)/EventBuffer(V1基础)/iOS构建/UniFFI绑定/docs。但 V2 核心模型(ReadingSession/EventV2/ActiveTimeTracker)不存在，EventBuffer 缺 ack/failed，Position 缺 camelCase+clamp，PDF/EPUB/Office 为 stub，测试覆盖不足 V2。

本 Issue: docs/ 目录存在(7文件)，但缺架构总文档 document-runtime-architecture.md。需冻结 V1→V2 迁移策略和设计决策 D1-D7。

状态: status:todo
工作类型: work:docs

## 审查结论：document runtime 当前有文件类型识别/MaterialType/PreviewMode/DocumentInfo(基本)/Markdown解析/Text解析/ImageMeta/Search(V1 Markdown+Text)/NoteAnchor(V1)/ReadingEvent(V1)/ReadingPosition(V1)/EventBuffer(V1基础)/iOS构建/UniFFI绑定/docs。但 V2 核心模型(ReadingSession/EventV2/ActiveTimeTracker)不存在，EventBuffer 缺 ack/failed，Position 缺 camelCase+clamp，PDF/EPUB/Office 为 stub，测试覆盖不足 V2。 **本 Issue**: docs/ 目录存在(7文件)，但缺架构总文档 document-runtime-architecture.md。需冻结 V1→V2 迁移策略和设计决策 D1-D7。 **状态**: status:todo **工作类型**: work:docs

wangdl closed this issue

2026-06-07 19:24:13 +08:00

wangdl commented

2026-06-07 19:24:14 +08:00

完成

docs/document-runtime-architecture.md 已创建。包含：

三端职责边界
7 个设计决策 (D1-D7)
V2 核心模型 (ReadingMaterialRef/SessionV2/EventV2/ActiveTimeTracker/EventBuffer)
V1→V2 迁移策略
API 协议字段映射
项目结构
最终验收链路

## 完成 docs/document-runtime-architecture.md 已创建。包含： - 三端职责边界 - 7 个设计决策 (D1-D7) - V2 核心模型 (ReadingMaterialRef/SessionV2/EventV2/ActiveTimeTracker/EventBuffer) - V1→V2 迁移策略 - API 协议字段映射 - 项目结构 - 最终验收链路

wangdl commented

2026-06-07 19:30:33 +08:00

完成情况 ✅

交付物

docs/document-runtime-architecture.md (265行)

冻结的 7 个设计决策

决策	内容
D1	Rust 只保存 materialId，不保存 readingTargetType
D2	V1 保留 deprecated，V2 新增 events_v2 模块
D3	clientSessionId 由 Rust 生成 UUID
D4	iOS 控制 tick，Rust 计算 delta
D5	Position JSON 使用 camelCase
D6	progress clamp 到 0~1
D7	ack 按 eventId 删除

文档包含

三端职责边界 (Rust/iOS/API)
V2 核心模型定义 (ReadingMaterialRef/SessionV2/EventV2/ActiveTimeTracker/EventBuffer)
V1→V2 迁移策略 + 字段差异表
API 协议字段映射表 (Rust→API)
项目结构
最终验收链路

代码证据

git log --oneline | head -1
# 22276bd feat: DOC-FULL-000 完整架构文档 v2
ls docs/document-runtime-architecture.md  # ✅ 存在

后续依赖

本文档为 DOC-FULL-001~006 的实现依据。

## 完成情况 ✅ ### 交付物 `docs/document-runtime-architecture.md` (265行) ### 冻结的 7 个设计决策 | 决策 | 内容 | |------|------| | D1 | Rust 只保存 materialId，不保存 readingTargetType | | D2 | V1 保留 deprecated，V2 新增 events_v2 模块 | | D3 | clientSessionId 由 Rust 生成 UUID | | D4 | iOS 控制 tick，Rust 计算 delta | | D5 | Position JSON 使用 camelCase | | D6 | progress clamp 到 0~1 | | D7 | ack 按 eventId 删除 | ### 文档包含 - 三端职责边界 (Rust/iOS/API) - V2 核心模型定义 (ReadingMaterialRef/SessionV2/EventV2/ActiveTimeTracker/EventBuffer) - V1→V2 迁移策略 + 字段差异表 - API 协议字段映射表 (Rust→API) - 项目结构 - 最终验收链路 ### 代码证据 ```bash git log --oneline | head -1 # 22276bd feat: DOC-FULL-000 完整架构文档 v2 ls docs/document-runtime-architecture.md # ✅ 存在 ``` ### 后续依赖本文档为 DOC-FULL-001~006 的实现依据。

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/zhixi-document-runtime#49