# 知识库模块 - 用户场景文档

> **版本**: v1.0  
> **最后更新**: 2026-02-25  
> **编写者**: Product Team

> 🚧 Draft：本文件为最小占位，待与 PRD/架构细化后完善。

---

## 📋 文档说明

本文档描述知识库模块的用户使用场景，帮助团队理解用户如何使用系统完成任务。

---

## 👥 用户角色

| 角色 | 描述 | 权限级别 |
|------|------|---------|
| 知识管理员 | 负责知识库配置与内容治理 | 管理员 |
| 知识贡献者 | 创建并维护知识内容 | 普通用户 |
| 普通用户 | 查阅与搜索知识 | 普通用户 |

---

## 🎯 场景 1: 搜索并查阅文档

### 场景描述

**用户角色**: 普通用户

**使用时机**: 需要快速获取某项政策/流程/技术说明

**目标**: 在最短时间找到可用的权威文档并访问原文

### 前置条件

- [ ] 用户已登录
- [ ] 用户拥有目标文档访问权限
- [ ] SharePoint 文档已同步到索引

### 正常路径

| 步骤 | 用户操作 | 系统响应 | 页面/状态 |
|------|---------|---------|----------|
| 1 | 进入知识库首页 | 展示搜索框与文档列表 | 知识库首页 |
| 2 | 输入关键词并搜索 | 返回匹配结果；标题与内容命中词高亮，内容行展示命中上下文片段；若命中文件夹名/路径，则在文件结果下方展示文件夹结果区 | 搜索结果列表 |
| 3 | 点击结果左侧标题/内容区域 | 直接跳转到原文（站内文章或 SharePoint） | 原文页面 |
| 4 | 点击右侧“预览”按钮 | 在当前页打开预览面板，展示内容与高亮命中 | 搜索结果页（预览面板打开） |
| 5 | 点击文件夹结果卡片 | 新标签页打开对应 SharePoint 文件夹 | SharePoint 文件夹页 |

> 说明：搜索结果允许包含草稿与已发布内容，但必须在列表中明确标注状态（Draft/Published）。

### 异常路径

#### 异常 1.1: 无搜索结果

**触发条件**: 索引中无匹配文档

**系统行为**: 返回空状态

**用户反馈**: 显示“未找到相关文档”提示

### 后置条件

- ✅ 用户可打开 SharePoint 文档
- ✅ 系统记录搜索行为日志

### 业务规则

1. **权限优先**: 无权限文档不得出现在结果中
2. **来源优先**: 同主题时优先展示权威级别高的文档
3. **可解释优先**: 结果列表必须展示与查询词直接相关的内容片段，并对命中词高亮
4. **主次动作分离**: 左侧信息区负责跳转原文，右侧按钮只负责预览，避免误触
5. **预览完整性优先**: 预览应尽量展示可获得的全部内容，无法完整展示时需保留打开原文入口
6. **交互可感知**: 左侧信息区悬停需显示手型光标，明确可点击

---

## 🎯 场景 2: AI 问答获取答案

### 场景描述

**用户角色**: 普通用户

**使用时机**: 需要快速获得答案而非完整阅读文档

**目标**: 得到可追溯的回答并查看来源

### 前置条件

- [ ] 用户已登录
- [ ] 问答功能已启用
- [ ] 用户拥有来源文档访问权限

### 正常路径

| 步骤 | 用户操作 | 系统响应 | 页面/状态 |
|------|---------|---------|----------|
| 1 | 输入问题并提交 | 触发检索与生成 | AI 问答面板 |
| 2 | 查看答案与引用 | 展示来源链接与片段 | AI 问答结果 |
| 3 | 点击引用 | 跳转 SharePoint | SharePoint 预览页 |

> 说明：引用列表允许包含草稿与已发布来源，但必须展示状态标签（Draft/Published）。

### 异常路径

#### 异常 2.1: 无可用答案

**触发条件**: 权限过滤后无可用文档

**系统行为**: 返回“暂无可用答案”

**用户反馈**: 提示可尝试调整关键词或权限范围

### 后置条件

- ✅ 答案包含引用与权限校验
- ✅ 记录问答日志

### 业务规则

1. **检索前过滤**: 必须先过滤权限，再检索
2. **可追溯**: 引用必须包含标题/链接/片段/版本/时间

---

## 🎯 场景 3: 贡献者提交原生文章

### 场景描述

**用户角色**: 知识贡献者

**使用时机**: 无 SharePoint 现成文档，需要补充知识

**目标**: 创建一篇原生文章并提交

### 前置条件

- [ ] 用户拥有创建权限
- [ ] 原生文章功能已启用（MVP 是否启用待确认）

### 正常路径

| 步骤 | 用户操作 | 系统响应 | 页面/状态 |
|------|---------|---------|----------|
| 1 | 点击“新建” | 打开 Outline 风格编辑器 | 文章编辑页 |
| 2 | 编写并保存 | 保存为草稿 | 草稿状态 |
| 3 | 提交发布 | 进入审核或发布 | 提交成功提示 |

### 异常路径

#### 异常 3.1: 无创建权限

**触发条件**: 用户角色无创建权限

**系统行为**: 禁用或隐藏新建入口

**用户反馈**: 权限不足提示

### 后置条件

- ✅ 草稿或已发布内容可检索

### 业务规则

1. **权限控制**: 仅有权限用户可创建
2. **生命周期**: 遵循文档状态流转

---

## 🔗 与功能的对应关系

| 场景 | 涉及功能 | 相关页面 | API 接口 |
|------|---------|---------|---------|
| 场景1 | 搜索与列表 | 知识库首页/列表 | `GET /knowledge-base/semantic-search` |
| 场景2 | AI 问答 | AI 问答面板 | `POST /knowledge-base/ask` |
| 场景3 | 原生文章 | 编辑页 | `POST /knowledge-base/articles` |