# 需求文档

## 简介

知识库系统是一个基于 Laravel Filament 3.X 的文档管理平台，允许用户上传和管理 Word 文档。系统支持文档分类为全局知识库和专用知识库，并根据用户所属分组控制访问权限。用户只能查看全局知识库和自己分组的专用知识库，无法访问其他分组的专用知识库。

系统具备文档格式转换功能，自动将上传的 Word 文档（.doc/.docx）转换为 Markdown 格式存储，并通过 Meilisearch 搜索引擎提供强大的全文搜索能力。用户可以通过关键词快速检索文档内容，也可以在线预览文档的 Markdown 渲染内容，无需下载即可查看文档信息。

## 术语表

- **系统（System）**: 指知识库管理系统
- **用户（User）**: 使用系统的人员
- **分组（Group）**: 用户所属的组织单位
- **文档（Document）**: 用户上传的 Word 文件
- **全局知识库（Global Knowledge Base）**: 所有用户都可以查看的知识库
- **专用知识库（Dedicated Knowledge Base）**: 仅特定分组用户可以查看的知识库
- **文档分类（Document Category）**: 文档的类型标签，用于组织和检索
- **Markdown 内容（Markdown Content）**: 从 Word 文档转换后的 Markdown 格式文本
- **文档转换（Document Conversion）**: 将 Word 文档转换为 Markdown 格式的过程
- **全文搜索（Full-Text Search）**: 在文档内容中搜索关键词的功能
- **Meilisearch**: 用于实现全文搜索的搜索引擎
- **文档索引（Document Index）**: 在 Meilisearch 中存储的文档搜索数据
- **文档预览（Document Preview）**: 在线查看文档 Markdown 内容的功能

## 需求

### 需求 1

**用户故事：** 作为系统管理员，我想要上传 Word 文档到知识库，以便为用户提供知识资源

#### 验收标准

1. WHEN 管理员选择 Word 文档并点击上传按钮 THEN 系统 SHALL 验证文件格式为 .doc 或 .docx
2. WHEN 文档格式验证通过 THEN 系统 SHALL 将文档存储到服务器并记录文档元数据
3. WHEN 文档上传成功 THEN 系统 SHALL 显示成功消息并返回文档列表页面
4. IF 上传的文件不是 Word 格式 THEN 系统 SHALL 拒绝上传并显示错误提示信息
5. WHEN 文档上传过程中发生错误 THEN 系统 SHALL 回滚操作并保持数据一致性

### 需求 2

**用户故事：** 作为系统管理员，我想要为文档设置分类，以便组织和管理知识库内容

#### 验收标准

1. WHEN 管理员创建或编辑文档 THEN 系统 SHALL 提供选项将文档分类为全局知识库或专用知识库
2. WHERE 文档被分类为专用知识库 THEN 系统 SHALL 要求管理员指定关联的分组
3. WHEN 文档被分类为全局知识库 THEN 系统 SHALL 允许所有用户查看该文档
4. WHEN 文档分类信息被保存 THEN 系统 SHALL 更新数据库中的文档分类字段
5. WHEN 文档已关联分组 THEN 系统 SHALL 在文档列表中显示关联的分组名称

### 需求 3

**用户故事：** 作为普通用户，我想要查看知识库文档列表，以便找到我需要的知识资源

#### 验收标准

1. WHEN 用户访问知识库页面 THEN 系统 SHALL 显示该用户有权限查看的所有文档列表
2. WHEN 系统过滤文档列表 THEN 系统 SHALL 包含所有全局知识库文档
3. WHEN 系统过滤文档列表 THEN 系统 SHALL 包含用户所属分组的专用知识库文档
4. WHEN 系统过滤文档列表 THEN 系统 SHALL 排除其他分组的专用知识库文档
5. WHEN 文档列表显示 THEN 系统 SHALL 展示文档标题、分类类型、上传时间和所属分组信息

### 需求 4

**用户故事：** 作为普通用户，我想要下载或查看文档内容，以便获取知识信息

#### 验收标准

1. WHEN 用户点击有权限的文档 THEN 系统 SHALL 允许用户下载该文档
2. WHEN 用户尝试访问无权限的文档 THEN 系统 SHALL 拒绝访问并显示权限不足提示
3. WHEN 用户下载文档 THEN 系统 SHALL 记录下载日志包含用户信息和时间戳
4. WHEN 文档被下载 THEN 系统 SHALL 保持原始文件格式和内容完整性

### 需求 5

**用户故事：** 作为系统管理员，我想要管理用户分组，以便控制专用知识库的访问权限

#### 验收标准

1. WHEN 管理员创建新分组 THEN 系统 SHALL 保存分组名称和描述信息
2. WHEN 管理员将用户分配到分组 THEN 系统 SHALL 更新用户的分组关联关系
3. WHEN 用户被分配到分组 THEN 系统 SHALL 自动授予该用户访问该分组专用知识库的权限
4. WHEN 用户从分组中移除 THEN 系统 SHALL 撤销该用户访问该分组专用知识库的权限
5. WHEN 分组被删除 THEN 系统 SHALL 将该分组的专用知识库文档转换为孤立状态或重新分配

### 需求 6

**用户故事：** 作为系统管理员，我想要搜索和筛选文档，以便快速找到特定的知识资源

#### 验收标准

1. WHEN 管理员在搜索框输入关键词 THEN 系统 SHALL 在文档标题和内容中搜索匹配项
2. WHEN 管理员选择分类筛选器 THEN 系统 SHALL 仅显示选定分类的文档
3. WHEN 管理员选择分组筛选器 THEN 系统 SHALL 仅显示选定分组的文档
4. WHEN 搜索结果为空 THEN 系统 SHALL 显示无结果提示信息
5. WHEN 应用多个筛选条件 THEN 系统 SHALL 返回同时满足所有条件的文档

### 需求 7

**用户故事：** 作为系统，我想要确保数据安全和权限隔离，以便保护敏感知识资源

#### 验收标准

1. WHEN 系统执行权限检查 THEN 系统 SHALL 验证用户身份和分组归属
2. WHEN 用户尝试访问文档 THEN 系统 SHALL 在返回数据前验证访问权限
3. WHEN 权限验证失败 THEN 系统 SHALL 记录未授权访问尝试到安全日志
4. WHEN 文档数据被查询 THEN 系统 SHALL 应用行级安全策略确保数据隔离
5. WHEN 用户会话过期 THEN 系统 SHALL 要求重新认证后才能访问知识库

### 需求 8

**用户故事：** 作为系统，我想要提供中文界面，以便中文用户能够流畅使用系统

#### 验收标准

1. WHEN 系统加载任何页面 THEN 系统 SHALL 以简体中文显示所有界面元素
2. WHEN 系统显示表单标签 THEN 系统 SHALL 使用中文标签和占位符文本
3. WHEN 系统显示错误或成功消息 THEN 系统 SHALL 使用中文提示信息
4. WHEN 系统显示数据表格 THEN 系统 SHALL 使用中文列标题和操作按钮
5. WHEN 系统显示日期时间 THEN 系统 SHALL 使用中文日期格式

### 需求 9

**用户故事：** 作为系统管理员，我想要系统自动将上传的 Word 文档转换为 Markdown 格式，以便实现文档内容的全文搜索和在线预览

#### 验收标准

1. WHEN 用户上传 Word 文档并保存成功 THEN 系统 SHALL 自动将文档内容转换为 Markdown 格式
2. WHEN 文档转换完成 THEN 系统 SHALL 将 Markdown 内容存储到数据库的 markdown_content 字段
3. WHEN 文档转换失败 THEN 系统 SHALL 记录错误日志并保留原始文档，不影响文档的正常使用
4. WHEN 文档转换成功 THEN 系统 SHALL 保留原始 Word 文档供用户下载
5. WHEN 文档被更新或重新上传 THEN 系统 SHALL 重新执行转换流程并更新 Markdown 内容

### 需求 10

**用户故事：** 作为普通用户，我想要通过关键词搜索文档内容，以便快速找到包含特定信息的文档

#### 验收标准

1. WHEN 用户在搜索页面输入关键词 THEN 系统 SHALL 使用 Meilisearch 在文档的 Markdown 内容中搜索匹配项
2. WHEN 系统执行搜索 THEN 系统 SHALL 同时搜索文档标题、描述和 Markdown 内容
3. WHEN 搜索返回结果 THEN 系统 SHALL 只显示用户有权限访问的文档（全局文档和用户分组的专用文档）
4. WHEN 搜索结果显示 THEN 系统 SHALL 展示文档标题、匹配的内容片段、文档类型和上传时间
5. WHEN 搜索关键词为空 THEN 系统 SHALL 显示提示信息要求输入搜索关键词

### 需求 11

**用户故事：** 作为普通用户，我想要在线预览文档的 Markdown 内容，以便无需下载即可查看文档内容

#### 验收标准

1. WHEN 用户点击有权限的文档查看按钮 THEN 系统 SHALL 显示文档的 Markdown 内容渲染后的 HTML 页面
2. WHEN 系统渲染 Markdown 内容 THEN 系统 SHALL 正确处理标题、列表、表格、图片等 Markdown 元素
3. WHEN 用户尝试预览无权限的文档 THEN 系统 SHALL 拒绝访问并显示权限不足提示
4. WHEN 文档的 Markdown 内容为空 THEN 系统 SHALL 显示提示信息并提供下载原始文档的选项
5. WHEN 预览页面显示 THEN 系统 SHALL 提供下载原始 Word 文档的按钮

### 需求 12

**用户故事：** 作为系统，我想要将文档内容索引到 Meilisearch，以便提供快速准确的全文搜索功能

#### 验收标准

1. WHEN 文档的 Markdown 转换完成 THEN 系统 SHALL 将文档信息索引到 Meilisearch
2. WHEN 索引文档到 Meilisearch THEN 系统 SHALL 包含文档 ID、标题、描述、Markdown 内容、类型和分组 ID
3. WHEN 文档被更新 THEN 系统 SHALL 更新 Meilisearch 中对应的索引
4. WHEN 文档被删除 THEN 系统 SHALL 从 Meilisearch 中删除对应的索引
5. WHEN Meilisearch 索引操作失败 THEN 系统 SHALL 记录错误日志但不影响文档的正常保存和使用
