9.7 KiB
9.7 KiB
06 内容与对话项目矩阵
三项业务能力（资料上传与处理、知识库与知识点管理、AI 对话与知识库问答）在各项目中的职责分布。 项目角色：主链路参与者、上游支撑、下游消费、运维可观测。
一、资料上传与处理 — 项目参与矩阵
| 业务环节 | iOS | 主 API | COS | Python RAG Worker | Qdrant | Admin（运维可观测） |
|---|---|---|---|---|---|---|
| 文件选择 | 系统文件选择器/相册/链接输入 | — | — | — | — | — |
| 文件校验与压缩 | 校验类型；图片 >2MB 自动 JPEG 压缩 | 校验文件类型（8 种）和大小（≤20MB） | — | — | — | — |
| 上传授权 | 调用 API 获取预签名 URL | 生成 COS 预签名 PUT URL（1 小时有效），内容安全检查文件名 | 提供预签名 URL 能力 | — | — | — |
| 文件上传 | 直接 PUT 文件到 COS | — | 接收文件数据 | — | — | — |
| 上传确认 | 调用 API 确认 | 验证 COS 中文件存在，创建 UploadedFile 记录 | 供 headObject 验证 | — | — | — |
| 创建资料记录 | — | 创建 KnowledgeSource + DocumentImport（QUEUED），Redis 状态初始化 | — | — | — | — |
| 异步处理 | — | 管理导入任务状态，提供查询端点 | 存储原始文件供 Worker 下载 | 轮询→锁定→下载→解析→清洗→分块→嵌入→索引→生成候选 | 存储向量索引（zhixi_chunks 集合，1024 维） | 监控导入任务（步骤日志、重试） |
| 状态展示 | 资料详情页 AI 处理状态横幅 | 提供 parseStatus/indexStatus/learningStatus 查询 | — | 更新 KnowledgeSource 处理状态 | — | 查看来源文件状态 |
| 候选审核 | 接受/拒绝/批量接受候选 | 候选审核 API，内容安全检查 | — | 生成候选（DeepSeek 提取知识点） | — | 候选巡检 |
| 失败处理 | 展示错误提示 | 自动重试（最多 3 次）+ 过期任务回收 | — | 失败时更新状态和错误信息 | — | 手动重试导入 |
| 文件删除 | 来源文件删除 | 软删除；Admin 可从 COS 删除 | 删除对象 | — | 软删除向量标记 | 文件管理页删除 |
二、知识库与知识点管理 — 项目参与矩阵
| 业务环节 | iOS | 主 API | 数据库 | COS | Python RAG Worker | Admin（运维可观测） |
|---|---|---|---|---|---|---|
| 创建知识库 | 封面选择+裁剪、名称/描述输入 | 创建 KB 记录（默认 private），限制 20 个/用户 | 存储 KB 记录 | 存储封面图 | — | — |
| 知识库列表 | 卡片列表+筛选+分页+下拉刷新 | 分页查询，支持 visibility/ownerType 筛选 | 查询+排序 | — | — | 查看全部 KB |
| 知识库详情 | 双 Tab（知识点+来源文件）+排序 | 提供详情查询+知识点列表+来源列表 | 关联查询 | — | — | 详情抽屉+来源文件列表 |
| 知识库更新/删除 | 更新信息/确认弹窗删除 | 所有权校验，软删除 | 更新/软删除 | — | — | 可删除 KB |
| 添加知识点 | 手动模式（标题+内容）+文件模式 | 创建 KnowledgeItem | 存储记录 | 文件模式下存储内容 | — | — |
| 知识点编辑 | 标题+内容编辑 | 白名单字段更新 | 更新记录 | — | — | — |
| 知识点删除 | 单个删除+批量选择删除 | 单个软删除+批量软删除 | 软删除+itemCount 递减 | — | — | — |
| 文件夹管理 | Sheet 弹窗（创建/重命名/删除） | 文件夹 CRUD，同步创建 folder 类型 KnowledgeItem | 存储文件夹+同步 KnowledgeItem | — | — | — |
| 排序 | 排序菜单（4 种方式） | 排序参数查询 | ORDER BY 排序 | — | — | — |
| 搜索 | 搜索页界面（逻辑未实现） | 公开库支持标题+描述搜索 | 全文搜索未实现 | — | — | — |
| 公开库发现 | 公开库列表+订阅/取消订阅 | 发现 API，订阅管理 | 存储订阅关系 | — | — | — |
| 权限校验 | — | 所有权校验（私有 KB 返回 404） | — | — | — | Admin 权限分级 |
| 内容安全 | — | KB 标题+标签敏感词检查 | — | — | — | 敏感词库管理 |
三、AI 对话与知识库问答 — 项目参与矩阵
| 业务环节 | iOS | 主 API | DeepSeek 模型 | Python RAG Worker | Admin（运维可观测） |
|---|---|---|---|---|---|
| 会话创建/恢复 | 调用 API open-or-create | open-or-create 逻辑（相同范围复用） | — | — | — |
| 消息发送 | 输入文字，调用流式 API | 校验→内容安全→保存用户消息→加载上下文→构建提示→调用模型 | — | — | — |
| 上下文加载 | — | 按 scopeType 从 KnowledgeItem 表查询（最多 30 条×500 字符），完全不调用 Qdrant | — | 知识点内容来自 RAG 处理结果（间接供给） | — |
| 模型调用 | — | AiGateway 路由→DeepSeek Provider | 流式生成（content+reasoning_content） | — | — |
| 流式展示 | SSE 解析+实时渲染+思考过程折叠 | SSE 流式转发 | 提供流式响应 | — | — |
| 引用展示 | 消息气泡中展示引用 | 保存前 5 个上下文项为 ChatCitation | — | — | — |
| 会话管理 | 列表+搜索+切换+删除+归档+置顶 | 会话 CRUD+所有权校验 | — | — | — |
| 内容安全 | — | 输入消息+AI 输出敏感词匹配 | — | — | — |
| 模型路由 | — | AiGateway：tier 路由+回退+重试（最多 3 次） | — | — | — |
| Token 与成本 | — | 记录 ModelInvocationLog+每日聚合 | — | — | — |
| 用户 API Key | 设置页输入自己的 Key | 加密存储+测试+回退使用 | — | — | — |
| 联网搜索 | 暂未确认 | 暂未确认 | — | — | — |
| 文件附件 | 暂未确认 | 暂未确认 | — | — | — |
| 导图/分享/生成笔记 | 暂未确认 | 暂未确认 | — | — | — |
四、项目角色分类
主链路参与者
| 项目 | 资料上传与处理 | 知识库与知识点管理 | AI 对话与知识库问答 |
|---|---|---|---|
| iOS | 文件选择、校验、上传、候选审核 | 知识库/知识点/文件夹全界面 | 对话界面、会话管理、流式渲染 |
| 主 API | 上传授权、确认、资料记录、导入任务管理 | 全部 CRUD、权限校验、搜索（部分） | 会话管理、上下文加载、模型路由、SSE 转发、内容安全 |
| COS | 文件存储和预签名 URL | 封面图和文件内容存储 | — |
| 数据库 | UploadedFile/DocumentImport 记录 | KnowledgeBase/Item/Folder/Source 全部 | ChatSession/Message/Citation 记录 |
| DeepSeek | — | — | 模型推理（deepseek-v4-pro） |
上游支撑
| 项目 | 资料上传与处理 | 知识库与知识点管理 | AI 对话与知识库问答 |
|---|---|---|---|
| Python RAG Worker | 文档解析、分块、嵌入、候选生成 | 异步处理，不阻塞知识库 CRUD | 知识库内容供给（KnowledgeItem 来自 RAG 候选审核）；不参与对话上下文加载 |
| Qdrant | 向量索引存储 | — | 不参与对话上下文加载；当前仅 Admin RAG 调试页使用 |
下游消费
| 项目 | 资料上传与处理 | 知识库与知识点管理 | AI 对话与知识库问答 |
|---|---|---|---|
| Heavy Runtime | 不参与 | 不参与 | 不直接参与基础对话（负责异步 AI 分析） |
运维与可观测
| 项目 | 资料上传与处理 | 知识库与知识点管理 | AI 对话与知识库问答 |
|---|---|---|---|
| Admin | 文件管理、导入监控（步骤日志+重试）、候选巡检、分块管理 | KB 查看/删除、来源文件查看、引用追踪 | 会话日志、AI 网关管理、使用统计、成本管理、内容安全审核 |
五、关键架构发现
5.1 RAG 聊天的上下文不来自 Qdrant
所有 5 种 Scope（global、knowledge_base、folder、material、knowledge_item）的对话上下文均直接从 PostgreSQL 的 KnowledgeItem 表加载（最多 30 条，每条截取 500 字符，总计最多 4000 字符）。loadContextByScope 完全不调用 Qdrant，不存在任何 Scope 使用向量语义搜索。Qdrant 向量索引当前仅用于 Admin RAG 调试页的向量搜索测试。"RAG Chat"中的"RAG"指的是通过 scope 进行结构化检索（从 KnowledgeItem 表查询），而非向量语义搜索。
5.2 基础 AI 对话不经过 Heavy Runtime
对话链路：iOS → API → AiGateway → DeepSeek。Heavy Runtime 负责异步 AI 分析任务（学习状态分析、薄弱点识别、测验生成等），通过独立的作业轮询机制运作。
5.3 文件上传与处理是完全异步的
用户上传文件后立即返回，后续的解析、分块、嵌入、索引、候选生成全部由 Python RAG Worker 异步完成。用户可通过资料详情页查看处理状态。
5.4 Open-or-create 确保每个范围只有一个活跃会话
相同 scopeType + scopeId + userId 下只存在一个未归档未删除的会话。这意味着用户每次从同一知识库进入 AI 对话时，都会恢复之前的对话历史。
5.5 知识库范围对话不等待 RAG
即使 Python RAG Worker 尚未完成文档处理，知识库范围对话仍可使用——上下文来自用户已手动添加或已通过候选审核的知识点（KnowledgeItem 表），不需要等待 RAG 的向量索引完成。Qdrant 向量索引不参与任何 Scope 的对话上下文构建。