M2-03 Material & Source Module #23

New Issue

wangdl · 2026-05-22T21:09:49+08:00

wangdl commented

2026-05-22 21:09:49 +08:00

目标

设计知习资料与来源模块，为 C 端用户提供上传材料的管理、版本控制和来源引用追踪能力。

本 Issue 只做模块架构设计，不直接实现代码。

背景说明

Material 是知习最核心的数据对象之一——用户上传的 PDF、DOCX、图片等资料。每个 Material 可以有多个 Source 版本（重新解析后生成新版本），解析后的 chunks 需要能追溯回 Material 的具体位置（页码/段落/坐标）。所有学习工件和 RAG 引用都必须能回溯到 Material 或 SourceReference。

模块职责

本模块负责：
- Material CRUD（名称、类型、COS 绑定、状态）
- KnowledgeSource 版本管理（每次解析生成新版本）
- SourceReference / CitationAnchor（页码、段落、坐标定位）
- MaterialSlice / KnowledgeChunk 关联
- ParsedDocument（解析后纯文本存储）
- 资料状态管理（上传中/解析中/就绪/失败）
本模块不负责：
- 文件上传和 COS 操作（走 File Storage Module）
- 文档解析和执行（走 Ingestion Module）
- chunk 的 embedding 和索引（走 Ingestion 和 Vector Module）
- 从资料生成知识点（走 Artifact Module）

候选数据对象

Material（资料对象）
KnowledgeSource（Source 版本）
SourceVersion
MaterialSlice（切片）
KnowledgeChunk（chunk）
SourceReference（来源引用）
CitationAnchor（引用锚点：页码/段落/坐标）
ParsedDocument（解析后纯文本）

基础设施依赖判断

MySQL：是（Material 元数据和版本信息）
Redis：否
BullMQ：否（但 Ingestion 模块会使用队列）
Qdrant：否（但 chunk 的向量在 Qdrant 中）
AI Gateway：否
COS：否（通过 File Storage 间接访问）
Content Safety：是（资料名称和解析后文本需要审核）

API 设计

CAPI：
- Material CRUD
- Material 列表（按知识库/文件夹筛选）
- Source 版本列表
- SourceReference 查询（按 chunk/artifact 反查源头）
AAPI：
- Material 全量查询
- Source 版本管理

Domain Event 设计

MaterialUploaded：资料上传完成
MaterialParsed：资料解析完成
SourceVersionCreated：新版本创建

交付检查

路由归属：CAPI + AAPI
是否需要 Prisma migration：是
是否需要 MySQL：是
是否需要 Redis：否
是否需要 BullMQ：否
是否需要 Content Safety：是
是否需要 AuditLog：否
是否需要 Domain Event：是
是否需要 Admin 视图：是

验收标准

Material / KnowledgeSource / SourceReference Prisma schema
资料状态机设计
Source 版本管理方案
CitationAnchor 数据结构设计（支持页码/段落/坐标多种定位方式）
Admin 视图设计
集成测试覆盖资料创建和版本管理

禁止事项

禁止 Material 删除不标记状态而物理删除（应软删除，关联清理异步进行）
禁止 SourceReference 丢失溯源信息
禁止 CitationAnchor 使用不精确的定位方式（如只用"前一页"描述）

不建议当前阶段实现

资料协作编辑
资料版本 diff 对比
资料标签自动生成

## 目标设计知习资料与来源模块，为 C 端用户提供上传材料的管理、版本控制和来源引用追踪能力。本 Issue 只做模块架构设计，不直接实现代码。 ## 背景说明 Material 是知习最核心的数据对象之一——用户上传的 PDF、DOCX、图片等资料。每个 Material 可以有多个 Source 版本（重新解析后生成新版本），解析后的 chunks 需要能追溯回 Material 的具体位置（页码/段落/坐标）。所有学习工件和 RAG 引用都必须能回溯到 Material 或 SourceReference。 ## 模块职责 1. 本模块负责： - Material CRUD（名称、类型、COS 绑定、状态） - KnowledgeSource 版本管理（每次解析生成新版本） - SourceReference / CitationAnchor（页码、段落、坐标定位） - MaterialSlice / KnowledgeChunk 关联 - ParsedDocument（解析后纯文本存储） - 资料状态管理（上传中/解析中/就绪/失败） 2. 本模块不负责： - 文件上传和 COS 操作（走 File Storage Module） - 文档解析和执行（走 Ingestion Module） - chunk 的 embedding 和索引（走 Ingestion 和 Vector Module） - 从资料生成知识点（走 Artifact Module） ## 候选数据对象 - Material（资料对象） - KnowledgeSource（Source 版本） - SourceVersion - MaterialSlice（切片） - KnowledgeChunk（chunk） - SourceReference（来源引用） - CitationAnchor（引用锚点：页码/段落/坐标） - ParsedDocument（解析后纯文本） ## 基础设施依赖判断 - MySQL：是（Material 元数据和版本信息） - Redis：否 - BullMQ：否（但 Ingestion 模块会使用队列） - Qdrant：否（但 chunk 的向量在 Qdrant 中） - AI Gateway：否 - COS：否（通过 File Storage 间接访问） - Content Safety：是（资料名称和解析后文本需要审核） ## API 设计 1. CAPI： - Material CRUD - Material 列表（按知识库/文件夹筛选） - Source 版本列表 - SourceReference 查询（按 chunk/artifact 反查源头） 2. AAPI： - Material 全量查询 - Source 版本管理 ## Domain Event 设计 - MaterialUploaded：资料上传完成 - MaterialParsed：资料解析完成 - SourceVersionCreated：新版本创建 ## 交付检查 - [ ] 路由归属：CAPI + AAPI - [ ] 是否需要 Prisma migration：是 - [ ] 是否需要 MySQL：是 - [ ] 是否需要 Redis：否 - [ ] 是否需要 BullMQ：否 - [ ] 是否需要 Content Safety：是 - [ ] 是否需要 AuditLog：否 - [ ] 是否需要 Domain Event：是 - [ ] 是否需要 Admin 视图：是 ## 验收标准 1. Material / KnowledgeSource / SourceReference Prisma schema 2. 资料状态机设计 3. Source 版本管理方案 4. CitationAnchor 数据结构设计（支持页码/段落/坐标多种定位方式） 5. Admin 视图设计 6. 集成测试覆盖资料创建和版本管理 ## 禁止事项 - 禁止 Material 删除不标记状态而物理删除（应软删除，关联清理异步进行） - 禁止 SourceReference 丢失溯源信息 - 禁止 CitationAnchor 使用不精确的定位方式（如只用"前一页"描述） ## 不建议当前阶段实现 - 资料协作编辑 - 资料版本 diff 对比 - 资料标签自动生成

wangdl added this to the M2：知识库主链路闭环（P1） milestone 2026-05-22 21:09:49 +08:00

wangdl self-assigned this 2026-05-22 21:09:49 +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#23