# 04 知识库与知识点管理 — 跨项目完整能力分析

> 项目角色分类：主链路参与者（iOS、主 API、数据库、COS——知识库 CRUD 必须经过这些项目）、上游支撑（Python RAG Worker——异步处理导入资料，不阻塞知识库管理操作）、运维可观测（Admin）。
> Rust Document Runtime 不参与知识库管理链路。Heavy Runtime 不参与此链路。
> 注意：Python RAG Worker 在本能力中是上游支撑（知识库 CRUD 不依赖它）；在"资料上传与处理"能力中是主链路参与者。

---

## 1. 能力目标

用户可以创建、组织、维护个人知识库，管理其中的知识点和来源资料，通过文件夹分类、排序、搜索、公开发现和订阅来高效组织和获取学习内容。

---

## 2. C 端入口

| 入口页面 | 触发方式 | 功能 |
|---------|---------|------|
| 知识库首页 | Tab "知识库" 默认 | 查看知识库列表、筛选、搜索入口、创建入口 |
| 知识库搜索页 | 搜索图标 | 搜索知识库和知识点 |
| 创建知识库页 | + 按钮 / 我的页学习资产 | 创建新知识库（封面、名称、描述） |
| 知识库详情页 | 点击知识库卡片 | 查看知识点列表/来源文件列表、管理操作 |
| 添加知识点页 | 操作菜单"添加" | 手动/文件模式添加知识点 |
| 知识点详情页 | 点击知识点条目 | 查看/收藏/笔记/原文 |
| 编辑知识点页 | 工具栏菜单 | 编辑标题和内容 |
| 文件夹管理 Sheet | 操作菜单"文件夹管理" | 创建/重命名/删除文件夹 |
| 导入资料页 | 操作菜单"上传" | 文件/相册/链接导入 |
| 导入候选审核页 | 导入完成后 | 审核 AI 提取的知识点候选 |
| 发现公开库页 | "我的"页"发现公开库" | 浏览/订阅公开知识库 |

---

## 3. 业务对象关系

```
知识库（KnowledgeBase）
├── 来源资料（KnowledgeSource）── 原始上传文件，含解析/索引/学习状态
├── 知识点（KnowledgeItem）── 知识库的基本内容单元
│   ├── 类型：章节(chapter)、课程(lesson)、概念(concept)、笔记(note)、导入文档(imported_doc)、AI生成(ai_generated)
│   ├── 层级：通过 parentId 形成树状结构
│   └── 关联：通过 sourceId 关联到来源资料
├── 文件夹（KnowledgeFolder）── 用于组织知识点
│   └── 同步创建 folder 类型的 KnowledgeItem（保证 iOS 兼容）
├── 知识分块（KnowledgeChunk）── 来源资料的语义分块，含向量嵌入
├── 导入候选（ImportCandidate）── AI 提取的知识点候选，等待审核
├── 测验（Quiz）── 基于知识库内容生成的测验
├── 订阅关系（KnowledgeBaseSubscription）── 用户对公开知识库的订阅
└── AI 会话范围（ChatScope）── AI 对话可限定在知识库范围
```

---

## 4. 用户主流程

### 4.1 创建知识库

用户点击创建按钮 → 输入名称（必填）和描述（必填）→ 可选上传封面图（从相册选择，自动裁剪为 512×512）→ 点击创建 → API 创建知识库记录（默认 private）→ 用户可在列表中看到新知识库。每个用户最多创建 20 个知识库。

### 4.2 浏览与筛选

用户进入知识库首页 → 查看知识库卡片列表（封面、名称、描述、日期、置顶标记、公开标记）→ 可通过分类筛选（全部/我的/已订阅/官方）切换视图 → 滚动到底部自动加载更多（分页 20 条/页）→ 下拉刷新。

### 4.3 添加资料

用户进入知识库详情页 → 点击操作菜单"上传" → 选择文件/相册/链接导入 → 文件上传至 COS → API 创建 KnowledgeSource → 自动创建 DocumentImport 任务 → Python RAG Worker 异步处理 → 用户可查看 AI 处理状态 → 审核 AI 提取的候选知识点。

### 4.4 手动添加知识点

用户进入添加知识点页 → 选择"手动"模式 → 输入标题和内容文字 → 保存 → API 创建 KnowledgeItem。

### 4.5 编辑与删除知识点

用户在知识库详情页点击知识点 → 进入知识点详情页查看内容 → 工具栏菜单选择编辑 → 修改标题/内容 → 保存。滑动或长按可删除知识点（单个或批量）。

### 4.6 批量操作

用户进入批量选择模式 → 逐选或全选知识点 → 点击批量删除 → 确认弹窗 → API 批量软删除。

### 4.7 文件夹管理

用户打开文件夹管理 Sheet → 查看已有文件夹列表 → 新建（输入名称）→ 重命名（滑动操作）→ 删除（滑动操作）。创建文件夹时同步创建 folder 类型的 KnowledgeItem。注意：重命名文件夹时仅更新 KnowledgeFolder 记录的 name 字段，不会同步更新对应 KnowledgeItem 的 title 字段。当前无文件夹数量上限。

### 4.8 排序

用户在知识库详情页点击排序菜单 → 选择排序方式（默认/文件大小/创建时间/更新时间）→ 知识点列表按所选方式重新排列。

### 4.9 搜索

用户点击搜索图标 → 进入搜索页 → 输入关键词。当前搜索逻辑未实现——搜索页仅展示空状态，输入关键词不触发 API 调用。

### 4.10 公开库发现与订阅

用户进入发现公开库页 → 查看所有公开知识库列表（含标题、描述、条目数）→ 点击订阅按钮 → API 创建订阅记录。用户可在知识库首页"已订阅"筛选中查看已订阅的知识库。用户不可订阅自己的知识库。取消订阅可随时操作。

### 4.11 删除知识库

用户在知识库详情页操作菜单点击"删除知识库"→ 确认弹窗 → API 软删除知识库（设置 deletedAt）。删除后知识点和来源资料仍保留在数据库中（软删除），但不再对用户可见。

---

## 5. 项目职责

### iOS — 主链路参与者

- 知识库列表展示（卡片、筛选、分页、下拉刷新）
- 创建知识库（封面选择与裁剪、名称/描述输入）
- 知识库详情（双 Tab：知识点 + 来源文件，排序，批量操作）
- 知识点详情（多格式渲染、收藏、笔记、原文）
- 添加/编辑知识点
- 文件夹管理 Sheet
- 搜索页（界面已搭建，逻辑未实现）
- 公开库发现与订阅
- 导入与候选审核

### 主 API — 主链路参与者

- 知识库 CRUD（创建/列表/详情/更新/软删除）
- 知识库所有权校验（私有 KB 对非所有者返回 404）
- 置顶切换
- 知识点 CRUD（创建/列表/详情/更新/单个删除/批量删除）
- 知识点排序
- 公开库发现（GET /knowledge-bases/discover，含搜索参数）
- 订阅管理（订阅/取消订阅/查看已订阅）
- 文件夹 CRUD（创建/列表/更新/删除）
- 知识库数量限制（每用户最多 20 个）
- 内容安全检查（KB 标题、标签）

### 数据库 — 主链路参与者

- 存储知识库、知识点、来源资料、文件夹、订阅、导入任务等核心业务数据
- 软删除支持（deletedAt 字段）
- 唯一约束（userId + knowledgeBaseId 订阅防重、userId + parentId + name 文件夹防重）

### COS — 主链路参与者

- 存储知识库封面图
- 存储知识点关联文件的内容（通过 COS URL 引用）

### Python RAG Worker — 上游支撑

- 不直接参与知识库 CRUD
- 异步处理导入资料，生成 KnowledgeChunk、ImportCandidate
- 用户在 RAG Worker 完成处理前即可查看和管理知识库及知识点

### Admin — 运维与可观测

- 知识库列表查看（全部 KB，含所属用户、条目数）
- 知识库详情抽屉（元数据 + 嵌套来源文件列表）
- 来源文件查看（全部来源，按 KB 和解析状态筛选）
- 来源文件引用追踪（查看哪些 AI 产物引用了该来源）
- 知识库删除
- 用户管理（查看/状态管理）
- 会员与配额管理

---

## 6. 权限与可见性

### 6.1 私有知识库

- **可见性：** 仅所有者可查看和操作。非所有者请求返回 404（隐藏存在性）。
- **所有者操作：** 全部 CRUD + 置顶 + 可见性切换 + 删除。
- **非所有者操作：** 无任何操作权限。

### 6.2 公开知识库

- **可见性：** 任何人可通过发现页查看和搜索。所有者仍可正常管理。
- **所有者操作：** 同私有知识库。
- **非所有者操作：** 可查看详情、订阅。不可编辑或删除。
- **订阅：** 用户可订阅公开知识库。不可订阅自己的知识库。

### 6.3 官方知识库

- **当前状态：** API 和数据库模型支持 ownerType 字段，但 iOS 端"官方"筛选返回空数组（TODO 注释：等后端支持）。
- **计划行为：** 由平台创建和维护的精选知识库，所有用户可查看和订阅。

### 6.4 删除权限

- **知识库删除：** 仅所有者可删除（软删除）。
- **知识点删除：** 所有者可单个或批量删除。
- **来源资料删除：** 服务层无所有权检查（代码缺陷），任何认证用户可通过 ID 删除任意来源。
- **文件夹删除：** 服务层无显式所有权检查（代码缺陷），但通过 KB 所有权间接保护。

### 6.5 资料访问权限

- **所有者：** 完整读写权限。可阅读原文件、使用 AI 对话（知识库范围）。
- **订阅者：** 可查看知识库内容。原文件阅读权限待确认（取决于 COS 文件访问控制）。
- **非所有者非订阅者：** 对私有 KB 无任何访问权限。对公开 KB 可查看详情和订阅。

---

## 7. 查询入口

### 用户查询

- **知识库列表：** iOS 知识库首页（卡片 + 筛选 + 分页）。
- **知识库详情：** iOS 知识库详情页（双 Tab + 排序）。
- **知识点详情：** iOS 知识点详情页（多格式渲染）。
- **搜索：** iOS 知识库搜索页（界面已搭建，逻辑未实现）。
- **公开库：** iOS 发现公开库页。
- **已订阅：** iOS 知识库首页"已订阅"筛选。

### Admin 查询

- **知识库列表：** Admin 知识库页（全部 KB，含所属用户、条目数）。
- **知识库详情抽屉：** 元数据 + 嵌套来源文件列表 + 引用追踪。
- **来源文件列表：** Admin 来源文件页（按 KB 和解析状态筛选）。
- **引用追踪：** 查看特定来源被哪些 AI 产物（测验、摘要等）引用。

### 系统内部查询

- **RAG 对话上下文：** API 从 KnowledgeItem 表按知识库 ID 查询最多 30 条，构建对话上下文。
- **导入任务关联：** API 创建 KnowledgeSource 时自动关联 DocumentImport。
- **订阅关系：** API 在订阅和已订阅列表查询时使用。

---

## 8. 修改入口

### 用户修改

- **创建知识库：** iOS 创建知识库页 → POST /knowledge-bases。
- **更新知识库：** iOS 知识库设置 → PATCH /knowledge-bases/:id。
- **置顶/取消置顶：** iOS 知识库卡片操作 → POST /knowledge-bases/:id/pin。
- **创建知识点：** iOS 添加知识点页 → POST /knowledge-items。
- **编辑知识点：** iOS 编辑知识点页 → PATCH /knowledge-items/:id。
- **删除知识点：** iOS 知识库详情页（单个/批量） → DELETE /knowledge-items/:id 或 POST /knowledge-items/batch-delete。
- **文件夹操作：** iOS 文件夹管理 Sheet → POST/PATCH/DELETE /knowledge-bases/:id/folders。
- **订阅/取消订阅：** iOS 发现公开库页 → POST/DELETE /knowledge-bases/:id/subscribe。
- **删除知识库：** iOS 知识库详情页 → DELETE /knowledge-bases/:id。

### Admin 修改

- **删除知识库：** Admin 知识库页删除按钮（危险确认弹窗）。
- **删除文件：** Admin 文件管理页。
- **重试导入：** Admin 导入监控页。

### 系统自动修改

- **itemCount 维护：** 创建/删除知识点时自动更新知识库的 itemCount。
- **软删除传播：** 删除文件夹时自动软删除子文件夹和对应的 KnowledgeItem。
- **内容安全检查：** KB 标题和标签自动进行敏感词匹配。

---

## 9. 删除影响

### 9.1 删除知识库

- **影响范围：** 知识库本身被软删除（设置 deletedAt）。
- **知识点：** 保留在数据库中（不被级联删除），但用户不可见。
- **来源资料：** 保留但关联的 KB 不可访问。
- **订阅：** 保留但已删除 KB 不出现在已订阅列表中。
- **测验：** 保留但关联的 KB 不可访问。
- **AI 会话：** 保留但知识库范围对话可能无法加载上下文。

### 9.2 删除来源资料

- **影响范围：** 来源资料被软删除。
- **关联知识点：** 保留（sourceId 变为悬空引用）。
- **关联分块：** KnowledgeChunk 保留，Qdrant 向量需手动或通过软删除标记清理。
- **关联候选：** ImportCandidate 保留但关联的 sourceId 不可访问。

### 9.3 删除知识点

- **影响范围：** 知识点被软删除，itemCount 递减。
- **子知识点：** 保留在数据库中（parentId 变为悬空引用）。
- **关联笔记：** 知识点详情页的笔记入口不可用。
- **AI 对话上下文：** 已删除知识点不再出现在上下文加载结果中。

### 9.4 删除文件夹

- **影响范围：** 文件夹被软删除，对应的 folder 类型 KnowledgeItem 也被软删除。
- **子文件夹：** 级联软删除。
- **文件夹内知识点：** 保留在数据库中（parentId 引用可能变为悬空）。

### 9.5 取消订阅

- **影响范围：** 订阅记录被删除。
- **已订阅列表：** 知识库从用户的已订阅筛选中消失。
- **其他数据：** 无影响。用户之前查看的知识库内容仍可查看（只要知识库保持公开）。

---

## 10. 当前完成状态

| 组件 | 状态 | 说明 |
|------|------|------|
| iOS 创建知识库 | 已完成 | 封面、名称、描述，API 创建 |
| iOS 知识库列表与筛选 | 部分完成 | 全部/我的/已订阅可用；"官方"筛选返回空 |
| iOS 知识库详情（双 Tab） | 已完成 | 知识点列表 + 来源文件列表 |
| iOS 手动添加知识点 | 已完成 | 标题 + 内容编辑 |
| iOS 文件模式添加知识点 | 已完成 | COS 上传 + 创建知识点 |
| iOS 知识点详情（多格式渲染） | 已完成 | 文本/Markdown/文件 |
| iOS 编辑知识点 | 已完成 | 标题 + 内容修改 |
| iOS 删除知识点（单个+批量） | 已完成 | 单个软删除 + 批量选择删除 |
| iOS 文件夹管理 | 已完成 | 创建/重命名/删除 |
| iOS 排序 | 已完成 | 4 种排序方式 |
| iOS 搜索 | 未完成 | 搜索页界面已搭建，搜索逻辑未实现 |
| iOS 公开库发现与订阅 | 已完成 | 查看/订阅/取消订阅 |
| iOS 删除知识库 | 已完成 | 确认弹窗 + API 软删除 |
| iOS 收藏知识点 | 部分完成 | UI 切换存在，后端 API 未支持（TODO） |
| iOS 重命名知识点 | 未完成 | 菜单项存在但 action 为空（TODO） |
| iOS 移动到文件夹 | 未完成 | 菜单项存在但 action 为空（TODO） |
| iOS 知识库管理页 | 未完成 | 操作菜单"知识库管理"按钮 action 为空（TODO） |
| API 知识库 CRUD | 已完成 | 创建/列表/详情/更新/软删除 |
| API 知识库所有权校验 | 已完成 | 私有 KB 对非所有者返回 404 |
| API 知识库数量限制 | 已完成 | 每用户最多 20 个 |
| API 置顶切换 | 已完成 | |
| API 公开库发现与搜索 | 已完成 | 支持标题+描述搜索 |
| API 订阅管理 | 已完成 | 订阅/取消订阅/已订阅列表 |
| API 知识点 CRUD | 已完成 | 创建/列表/详情/更新/单个删除/批量删除 |
| API 知识点排序 | 已完成 | createdAt/updatedAt/fileSize/orderIndex |
| API 文件夹 CRUD | 已完成 | 含 folder 类型 KnowledgeItem 同步；当前无文件夹数量限制 |
| API 内容安全检查 | 已完成 | KB 标题 + 标签 + 候选内容 |
| Admin 知识库查看 | 已完成 | 列表 + 详情抽屉 |
| Admin 来源文件查看 | 已完成 | 按 KB 和解析状态筛选 |
| Admin 来源文件引用追踪 | 已完成 | 查看 AI 产物引用了哪些来源 |
| Admin 知识库删除 | 已完成 | |
| 官方知识库 | 未完成 | API 模型支持但后端筛选未实现 |
| API 来源资料删除权限校验 | 暂未确认 | 代码中无所有权检查（疑似缺陷） |
| API 文件夹更新/删除权限校验 | 暂未确认 | 代码中无显式所有权检查 |