# 知识库模块 - 变更日志

## v1.4.20 - 2026-02-28

### ♻️ 同步自愈增强：未变更文档增加远端健康检查

**变更说明**：

为避免“本地映射显示已完成，但远端 RAGFlow 文档已失效”导致检索缺失，新增未变更文档的远端健康检查与自愈策略：在健康检查窗口到期时，检查远端文档状态；若发现可恢复失效（如 `not found` / `don't own the document`），自动重传并重建映射。

**影响范围（文档）**：
| 文档 | 变更内容 |
|------|---------|
| `docs/modules/knowledge-base/03-architecture.md` | • 新增“2.6.3 远端映射健康检查与自愈”策略 |
| `docs/modules/knowledge-base/09-test-scenarios.md` | • 新增“场景 6.1 未变更文档远端失效自愈” |

## v1.4.19 - 2026-02-28

### 📁 搜索新增文件夹结果（位于文件结果下方）

**变更说明**：

知识库搜索结果新增 SharePoint 文件夹类型。用户可通过文件夹名/路径搜索到文件夹；结果区域固定为“文件结果在上、文件夹结果在下”。文件夹卡片仅展示文件夹名、路径、更新时间，整卡点击即可直接打开 SharePoint 文件夹，不提供单独按钮。

**影响范围（文档）**：
| 文档 | 变更内容 |
|------|---------|
| `docs/modules/knowledge-base/01-prd.md` | • 新增“4.3.8 文件夹结果展示”规则 |
| `docs/modules/knowledge-base/02-user-journey.md` | • 场景 1 增加文件夹结果展示与点击路径 |
| `docs/modules/knowledge-base/05-ui-interaction-spec.md` | • 明确结果分组顺序与文件夹卡片交互规范 |
| `docs/modules/knowledge-base/06-data-model.md` | • 新增 `sp_folder_index` 数据模型 |
| `docs/modules/knowledge-base/07-api.md` | • `semantic-search` 响应新增 `type=folder` 与 `folderPath` |
| `docs/modules/knowledge-base/09-test-scenarios.md` | • 新增“文件夹搜索与分组展示”测试场景 |

## v1.4.18 - 2026-02-25

### 👤 预览面板新增创建人展示

**变更说明**：

知识库搜索结果预览面板新增创建人（`createdBy`）元信息展示，便于用户在预览态识别文档所有者（谁创建）。

**影响范围（文档）**：
| 文档 | 变更内容 |
|------|---------|
| `docs/modules/knowledge-base/05-ui-interaction-spec.md` | • 预览元信息扩展为“来源 + 长度 + 创建人（有值时）” |
| `docs/modules/knowledge-base/09-test-scenarios.md` | • 场景 1 增加“预览面板创建人可见”断言 |

**影响范围（实现）**：
| 代码文件 | 变更内容 |
|------|---------|
| `frontend/src/app/(modules)/knowledge-base/page.tsx` | • 首页预览面板元信息增加 `createdBy` 展示 |
| `frontend/src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx` | • 语义搜索预览面板元信息增加 `createdBy` 展示 |

## v1.4.17 - 2026-02-25

### 🎯 搜索结果相关度改为常显（小号标签）

**变更说明**：

根据反馈，搜索结果中的“相关度”由可弱化策略调整为常显策略；展示位置统一为“预览”按钮左侧的小号标签，降低视觉干扰同时保留可观察性。

**影响范围（文档）**：
| 文档 | 变更内容 |
|------|---------|
| `docs/modules/knowledge-base/01-prd.md` | • 场景 4.3.6 新增“相关度常显 + 小号标签位置”规则 |
| `docs/modules/knowledge-base/05-ui-interaction-spec.md` | • 搜索结果交互新增“相关度常显位置规范” |
| `docs/modules/knowledge-base/09-test-scenarios.md` | • 场景 1 新增“相关度常显且位置正确”断言 |

**影响范围（实现）**：
| 代码文件 | 变更内容 |
|------|---------|
| `frontend/src/app/(modules)/knowledge-base/page.tsx` | • 首页结果卡片将相关度改为“预览按钮左侧小标签” |
| `frontend/src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx` | • 语义搜索结果卡片同步同一相关度展示策略 |

## v1.4.16 - 2026-02-25

### 👤 搜索结果新增创建人展示（文档所有者）

**变更说明**：

在知识库首页搜索结果卡片中新增“创建人（createdBy）”元信息展示，帮助用户在检索列表中直接识别文档所有者（谁创建）。

**影响范围（文档）**：
| 文档 | 变更内容 |
|------|---------|
| `docs/modules/knowledge-base/05-ui-interaction-spec.md` | • 场景“搜索操作”新增创建人元信息展示规则 |
| `docs/modules/knowledge-base/09-test-scenarios.md` | • 场景 1 增加“创建人可见”断言 |

**影响范围（实现）**：
| 代码文件 | 变更内容 |
|------|---------|
| `frontend/src/app/(modules)/knowledge-base/page.tsx` | • 结果元信息增加 `createdBy` 展示（复用现有 i18n `knowledgeBase.createdBy`） |

## v1.4.15 - 2026-02-25

### 🔍 预览可解释性增强：来源 + 字符数

**变更说明**：

在预览面板中新增“来源”和“长度”元信息，明确当前内容来自文章正文、检索分片聚合或摘要回退，并显示当前预览字符数，降低用户对“是否全文”的判断成本。

**影响范围（文档）**：
| 文档 | 变更内容 |
|------|---------|
| `docs/modules/knowledge-base/05-ui-interaction-spec.md` | • 结果预览新增“来源 + 长度”元信息要求 |

**影响范围（实现）**：
| 代码文件 | 变更内容 |
|------|---------|
| `frontend/src/locales/knowledgeBase/zh.ts` | • 新增来源/长度与来源类型文案 |
| `frontend/src/locales/knowledgeBase/en.ts` | • 新增来源/长度与来源类型文案 |
| `frontend/src/app/(modules)/knowledge-base/page.tsx` | • 预览面板渲染来源与字符数 |
| `frontend/src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx` | • 语义搜索预览面板渲染来源与字符数 |

## v1.4.14 - 2026-02-25

### 🧭 文件类型图标策略升级（MIME 优先 + 多分类兼容）

**变更说明**：

将知识库搜索结果图标识别从“少量扩展名判断”升级为“`mimeType` 优先、扩展名兜底、未知回退”策略，覆盖更多常见文件类型，提升不同文档类型的可识别性。

**影响范围（文档）**：
| 文档 | 变更内容 |
|------|---------|
| `docs/modules/knowledge-base/05-ui-interaction-spec.md` | • 增加图标识别优先级与多分类要求 |
| `docs/modules/knowledge-base/09-test-scenarios.md` | • 扩展图标断言覆盖范围（Office/媒体/压缩/代码） |

**影响范围（实现）**：
| 代码文件 | 变更内容 |
|------|---------|
| `frontend/src/app/(modules)/knowledge-base/_lib/documentTypeIcon.tsx` | • 引入 MIME 优先识别与多类型映射 |
| `frontend/src/app/(modules)/knowledge-base/_lib/api.ts` | • `SemanticSearchItem` 增加可选 `mimeType/fileExtension` 字段 |

## v1.4.13 - 2026-02-25

### 📖 文档预览增强：从摘要升级为扩展预览内容

**变更说明**：

修复“预览仅显示摘要片段”的问题。语义搜索结果新增可选字段 `previewContent`，由同文档多个命中分片聚合生成；前端预览面板优先渲染 `previewContent`，无该字段时再回退 `snippet`。

**影响范围（文档）**：
| 文档 | 变更内容 |
|------|---------|
| `docs/modules/knowledge-base/07-api.md` | • 语义搜索返回新增 `previewContent`（可选）字段说明 |

**影响范围（实现）**：
| 代码文件 | 变更内容 |
|------|---------|
| `backend/src/modules/knowledge-base/services/ragflow-search.service.ts` | • 语义搜索结果新增 `previewContent` 聚合逻辑 |
| `frontend/src/app/(modules)/knowledge-base/_lib/api.ts` | • `SemanticSearchItem` 新增 `previewContent` 字段 |
| `frontend/src/app/(modules)/knowledge-base/page.tsx` | • 预览文本优先使用 `previewContent` |
| `frontend/src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx` | • 预览文本优先使用 `previewContent` |

## v1.4.12 - 2026-02-25

### 🗂️ 搜索结果文件类型图标增强（Word / PPT / PDF）

**变更说明**：

知识库搜索结果卡片新增“按文件类型显示图标”能力，帮助用户在结果列表中快速识别 Word、PPT、PDF；无法识别类型时回退通用文档图标。

**影响范围（文档）**：
| 文档 | 变更内容 |
|------|---------|
| `docs/modules/knowledge-base/05-ui-interaction-spec.md` | • 新增搜索结果文件类型图标规则（Word/PPT/PDF + 回退） |
| `docs/modules/knowledge-base/09-test-scenarios.md` | • 场景 1 新增文件类型图标差异断言 |

**影响范围（实现）**：
| 代码文件 | 变更内容 |
|------|---------|
| `frontend/src/app/(modules)/knowledge-base/_lib/documentTypeIcon.tsx` | • 新增文件类型识别与图标映射工具 |
| `frontend/src/app/(modules)/knowledge-base/page.tsx` | • 首页搜索结果接入文件类型图标映射 |
| `frontend/src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx` | • 语义搜索结果接入同一图标映射 |

## v1.4.11 - 2026-02-25

### 🛠️ 预览面板修正：去除双预览块 + 标题语义优化

**变更说明**：

修复预览面板可用性问题：移除“内嵌 iframe + 文本”双块并行展示，统一为单一文本预览块；面板标题由通用“结果预览”调整为当前文档标题，并新增副标题说明。

**影响范围（实现）**：
| 代码文件 | 变更内容 |
|------|---------|
| `frontend/src/app/(modules)/knowledge-base/page.tsx` | • 预览改为单块正文展示<br>• 标题改为文档标题 |
| `frontend/src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx` | • 与首页保持一致的单块预览策略 |
| `frontend/src/locales/knowledgeBase/zh.ts` | • 新增预览副标题与“摘要说明”文案 |
| `frontend/src/locales/knowledgeBase/en.ts` | • 新增预览副标题与“摘要说明”文案 |

## v1.4.10 - 2026-02-25

### 🧩 预览增强：多文件类型兼容 + 全量内容优先 + 可点击光标反馈

**变更说明**：

在 v1.4.9 基础上，补充预览完整性与可交互反馈：预览按文件类型选择展示策略，尽量展示完整内容；左侧可点击区域增加手型光标反馈，减少误判。

**影响范围（文档）**：
| 文档 | 变更内容 |
|------|---------|
| `docs/modules/knowledge-base/01-prd.md` | • 4.3.6 增补“文件类型兼容 + 全量内容优先 + 手型光标反馈” |
| `docs/modules/knowledge-base/02-user-journey.md` | • 场景 1 业务规则补充预览完整性与可感知交互 |
| `docs/modules/knowledge-base/05-ui-interaction-spec.md` | • 结果预览补充分类型策略与不固定裁剪要求 |
| `docs/modules/knowledge-base/09-test-scenarios.md` | • 新增手型光标与分类型预览断言 |

## v1.4.9 - 2026-02-25

### 🔎 搜索结果交互重构：左侧直达原文 + 右侧预览面板

**变更说明**：

将搜索结果主次动作分离：左侧标题/内容/元信息区域改为可点击直达原文，右侧按钮由“查看”改为“预览”；预览在当前页右侧面板中打开，并支持命中关键词高亮。

**影响范围（文档）**：
| 文档 | 变更内容 |
|------|---------|
| `docs/modules/knowledge-base/01-prd.md` | • 新增“4.3.6 搜索结果主次动作分离”规则 |
| `docs/modules/knowledge-base/02-user-journey.md` | • 场景 1 正常路径补充“左侧跳转 + 右侧预览” |
| `docs/modules/knowledge-base/05-ui-interaction-spec.md` | • 搜索交互增加主次动作分离与预览面板规范 |
| `docs/modules/knowledge-base/09-test-scenarios.md` | • 场景 1 新增“预览面板打开且不跳转”断言 |

**影响范围（实现）**：
| 代码文件 | 变更内容 |
|------|---------|
| `frontend/src/app/(modules)/knowledge-base/page.tsx` | • 搜索结果左侧可点击跳转<br>• 右侧“预览”按钮 + 预览面板 |
| `frontend/src/app/(modules)/knowledge-base/_components/KBSemanticSearch.tsx` | • 语义搜索结果与首页保持一致交互 |
| `frontend/src/app/(modules)/knowledge-base/_lib/searchHighlight.tsx` | • 新增文章正文纯文本提取能力，用于预览高亮 |
| `frontend/src/locales/knowledgeBase/zh.ts` | • 新增预览相关文案 |
| `frontend/src/locales/knowledgeBase/en.ts` | • 新增预览相关文案 |

## v1.4.8 - 2026-02-25

### 🧭 首页新增快速开始模块（固定 3 篇引导文档）

**变更说明**：

在知识库首页新增“快速开始”模块，提供 Getting Started、How to、FAQ 三个固定入口，帮助用户快速访问高频引导文档。

**影响范围（文档）**：
| 文档 | 变更内容 |
|------|---------|
| `docs/modules/knowledge-base/05-ui-interaction-spec.md` | • 首页元素清单新增“快速开始模块”<br>• 新增快速开始交互说明 |
| `docs/modules/knowledge-base/09-test-scenarios.md` | • 新增首页快速开始模块 E2E 场景 |

**影响范围（实现）**：
| 代码文件 | 变更内容 |
|------|---------|
| `frontend/src/app/(modules)/knowledge-base/_components/KBQuickStart.tsx` | • 新增快速开始卡片组件 |
| `frontend/src/app/(modules)/knowledge-base/page.tsx` | • 首页接入快速开始模块 |
| `frontend/src/locales/knowledgeBase/zh.ts` | • 新增快速开始中文文案与链接配置 |
| `frontend/src/locales/knowledgeBase/en.ts` | • 新增快速开始英文文案与链接配置 |

## v1.4.7 - 2026-02-25

### 📝 搜索结果可解释性增强（命中片段 + 关键词高亮）

**变更说明**：

补记“知识库搜索结果展示优化”需求：搜索结果中的内容栏不再仅显示固定摘要，而是展示与查询词相关的上下文片段；标题与内容中的命中词需高亮，帮助用户快速判断结果相关性。

**影响范围（文档）**：
| 文档 | 变更内容 |
|------|---------|
| `docs/modules/knowledge-base/01-prd.md` | • 新增“4.3.5 搜索结果片段与命中高亮” |
| `docs/modules/knowledge-base/02-user-journey.md` | • 场景 1 正常路径与业务规则补充高亮与相关片段要求 |
| `docs/modules/knowledge-base/05-ui-interaction-spec.md` | • 搜索交互补充“内容片段展示 + 命中词高亮 + 裁剪省略号” |
| `docs/modules/knowledge-base/07-api.md` | • 增加 `snippet` 渲染约定（纯文本返回，前端渲染高亮） |
| `docs/modules/knowledge-base/09-test-scenarios.md` | • 场景 1 增加高亮与相关片段断言 |

**影响范围（评估不变更）**：
- `03-architecture.md`：无架构边界变化（仅前端展示层增强）
- `04-state-machine.md`：无状态流转变化
- `06-data-model.md`：无数据结构变化
- `08-error-codes.md`：无新增/变更错误码

## v1.4.6 - 2026-02-10

### ✅ 同步节省策略落地 + 同步消耗统计

**变更说明**：

落实“先比对元数据再下载”的节省策略，增加 ETag 记录、条件请求与内容哈希兜底；同步任务增加 token/chunk 统计，便于成本追踪。

**调整内容**：
- ✅ SharePoint 文档新增 ETag 记录
- ✅ 同步前比对 `etag/lastModified/size`，无变化跳过下载
- ✅ 条件请求（If-None-Match/If-Modified-Since）支持 304 跳过
- ✅ 同步任务记录 `processed_tokens/processed_chunks`
- ✅ 已处理明细记录 `token_count/chunk_count`
- ✅ embedding 授权/额度失败时终止任务，避免继续消耗

**影响范围**：
| 文档/配置 | 变更内容 |
|------|---------|
| `backend/prisma/schema/platform_knowledge.prisma` | • SP 文档 ETag；同步统计字段 |
| `backend/src/modules/knowledge-base/services/sharepoint-sync.service.ts` | • 元数据对比 + 条件请求 |
| `backend/src/modules/knowledge-base/services/ragflow-sync.service.ts` | • 跳过无变化 + 统计字段 + 额度保护 |
| `docs/modules/knowledge-base/03-architecture.md` | • 同步节省策略与额度提示 |
| `docs/modules/knowledge-base/06-data-model.md` | • 新增字段说明 |
| `docs/modules/knowledge-base/07-api.md` | • 同步任务返回字段更新 |

---

## v1.4.5 - 2026-02-04

### ✅ 同步任务明细页补齐（已处理/失败）+ 跳过原因可读化

**变更说明**：

补齐同步任务“已处理/失败/跳过”三类明细页与后端明细接口；跳过原因改为可读的失败原因描述，避免只显示 MIME 字段。

**调整内容**：
- ✅ 新增同步已处理明细页与失败明细页
- ✅ 新增同步明细接口：processed / failed
- ✅ 同步任务入库已处理/失败明细
- ✅ 跳过原因改为可读描述（扩展名/缺失类型等）

**影响范围**：
| 文档/配置 | 变更内容 |
|------|---------|
| `backend/prisma/schema/platform_knowledge.prisma` | • 新增已处理/失败明细表 |
| `backend/src/modules/knowledge-base/services/ragflow-sync.service.ts` | • 记录已处理/失败明细；优化跳过原因 |
| `backend/src/modules/knowledge-base/knowledge-base.controller.ts` | • 新增明细查询接口 |
| `frontend/src/app/(modules)/knowledge-base/sync-tasks/[taskId]/processed/page.tsx` | • 已处理明细页 |
| `frontend/src/app/(modules)/knowledge-base/sync-tasks/[taskId]/failed/page.tsx` | • 失败明细页 |
| `docs/modules/knowledge-base/05-ui-interaction-spec.md` | • 页面规范补齐 |
| `docs/modules/knowledge-base/07-api.md` | • 新增明细 API |
| `docs/modules/knowledge-base/06-data-model.md` | • 新增数据表说明 |

---

## v1.4.3 - 2026-02-04

### ✅ RAGFlow 同步：不支持类型自动跳过（不计失败）

**变更说明**：

对 SharePoint 同步增加“文件类型白名单”策略，无法识别或不支持的后缀不再进入 RAGFlow 同步流程，统一记录为跳过（不计为失败）。

**调整内容**：
- ✅ SharePoint 同步前按后缀与 MIME 类型判断可解析性
- ✅ 不支持类型直接跳过并记录日志（避免失败计数被污染）
- ✅ 同步任务增加 `skippedItems` 统计

---

## v1.4.4 - 2026-02-04

### 🧾 同步任务详情页 + 跳过明细入库

**变更说明**：

新增同步任务详情页，展示同步任务的状态与统计；同时将跳过明细入库，方便后续后台管理查看。

**调整内容**：
- ✅ 知识库新增同步任务详情页（状态/统计/错误）
- ✅ 跳过明细入库（`sync_task_skipped_items`）
- ✅ 同步任务列表页（最近任务 + 跳转详情）

**影响范围**：
| 文档/配置 | 变更内容 |
|------|---------|
| `frontend/src/app/(modules)/knowledge-base/sync-tasks/[taskId]/page.tsx` | • 新增任务详情页 |
| `backend/prisma/schema/platform_knowledge.prisma` | • 新增跳过明细表 |
| `backend/src/modules/knowledge-base/services/ragflow-sync.service.ts` | • 记录跳过明细 |
| `docs/modules/knowledge-base/05-ui-interaction-spec.md` | • 新增页面规范 |
| `docs/modules/knowledge-base/06-data-model.md` | • 新增数据表说明 |

**影响范围**：
| 文档/配置 | 变更内容 |
|------|---------|
| `backend/src/modules/knowledge-base/services/ragflow-sync.service.ts` | • 增加不支持文件类型跳过逻辑 |

---

## v1.4.2 - 2026-02-04

### 💬 RAGFlow 问答模型配置与引用解析修复

**变更说明**：

解决 RAGFlow Chat 默认模型未配置导致问答返回 `Model(@None) not authorized`，以及问答接口未解析新版本 `reference` 结构导致引用缺失的问题。

**调整内容**：
- ✅ RAGFlow 默认 Chat 模型配置（`qwen-turbo@Tongyi-Qianwen`）
- ✅ 问答服务兼容 RAGFlow `reference` 数组结构，正确回填引用来源

**影响范围**：
| 文档/配置 | 变更内容 |
|------|---------|
| `docker/ragflow/service_conf.yaml.template` | • 增加 `chat_model` 默认配置 |
| `backend/src/modules/knowledge-base/services/knowledge-qa.service.ts` | • 兼容 `reference` 数组结构 |

**实施状态**：🟡 需重启 RAGFlow 并复测问答引用

---

## v1.4.1 - 2026-02-04

### 🛠️ RAGFlow 存储与解析稳定性修复

**变更说明**：

解决 RAGFlow 文档解析时出现 `Embedding extraction from file path is not supported` 与 `This file is empty` 的问题，根因是 MinIO 单桶模式下 bucket 未预创建且本地文档读取路径使用了错误的 bucket 前缀。

**调整内容**：
- ✅ RAGFlow MinIO bucket 启动时自动创建（`ragflow`）
- ✅ 修正 RAGFlow 本地文档存储路径解析（优先使用 `doc.kb_id`）
- ✅ Docker 以 bind mount 方式注入修复文件
- ✅ SharePoint 下载校验（非二进制响应/空文件/OOXML 签名异常直接拦截）
- ✅ SharePoint 下载增加重试与 `/content` 兜底
- ✅ RAGFlow 解析错误包含 `package not found` 时自动重试
- ✅ 确保 RAGFlow Chat 绑定当前 dataset，避免问答 500
- ✅ 解析阶段补偿：遇到 `Documents not found` 时重传并重试解析

**影响范围**：
| 文档/配置 | 变更内容 |
|------|---------|
| `docker/ragflow/entrypoint.sh` | • 增加 MinIO bucket 初始化 |
| `thirdparty/ragflow/api/db/services/file2document_service.py` | • 修复文档存储地址解析 |
| `docker/docker-compose.yml` | • bind mount 修复文件 |

**实施状态**：🟡 代码已更新，需在环境中重新同步与验证

**注意**：
- 这是对第三方 RAGFlow 的必要补丁，生产环境建议通过自建镜像固化，避免仅靠 bind mount 影响可维护性。

---

## v1.4.0 - 2026-02-03

### 🔁 检索引擎切换为 RAGFlow

**变更说明**：

知识库检索/问答全面切换为 RAGFlow，移除原有 Qdrant + Embedding + 索引管道链路，并更新同步与数据模型。

**影响范围**：

| 文档 | 变更内容 |
|------|---------|
| **03-architecture.md** | • 数据层与部署说明改为 RAGFlow |
| **06-data-model.md** | • 新增 `ragflow_documents` 映射表<br>• 移除 `document_chunks` |
| **07-api.md** | • 删除 `/knowledge-base/search`、索引与增量同步接口 |

**实施状态**：🟡 代码与文档同步更新中

### ✅ 上线注意事项（必做）

- 停止并移除旧 Qdrant 容器（线上不再使用）
- 确认 `RAGFLOW_ES_PORT` 与现有端口无冲突
- `RAGFLOW_MYSQL_PORT` 为容器端口（3306），宿主机映射使用 `RAGFLOW_MYSQL_HOST_PORT`
- 内置 embedding 依赖 TEI 容器，需配置 `TEI_*` 与 `RAGFLOW_TEI_HOST`
- TEI 采用本地模型路径（`/data/models/bge-m3`），需预下载模型到 `ragflow_tei_data` 卷
- 启动 `knowledge` profile 后检查 RAGFlow/MySQL/MinIO/Redis/ES 健康状态

### ✅ 上线验收清单

**环境与容器**
- [ ] 旧 Qdrant 容器已移除（`docker rm`），避免端口/数据干扰
- [ ] RAGFlow 相关容器均为 `healthy`（ragflow/es/minio/mysql/redis）
- [ ] TEI 容器运行正常（`ragflow-tei`），embedding 模型可用
- [ ] TEI 已从本地模型路径加载（`/data/models/bge-m3`），避免在线拉取失败
- [ ] 端口映射与规划一致（3092/3093/3094/3095/3096/3097/3098/3099 或对应环境）

**配置与连通性**
- [ ] `RAGFLOW_BASE_URL`/`RAGFLOW_API_KEY` 生效，后端可访问 RAGFlow（API key 无效会导致检索/问答 500）
- [ ] 数据集与助手已创建或可自动创建（`RAGFLOW_DATASET_NAME`/`RAGFLOW_CHAT_NAME`）

**同步与索引**
- [ ] 触发全量同步成功（`/knowledge-base/sync/full`）
- [ ] 同步任务完成率、失败率可追踪（`/knowledge-base/sync/tasks/:taskId`）
- [ ] SharePoint 文档与 KB 文章均可在检索中出现

**检索与问答**
- [ ] `/knowledge-base/semantic-search` 返回结果包含文档与文章
- [ ] `/knowledge-base/ask` 能返回答案与引用来源

**回滚准备**
- [ ] 保留数据库迁移记录与配置变更备份

---

## v1.3.1 - 2026-01-05

### 📝 PRD 模块职责优化

**变更说明**：

基于 PRD v1.2.2 的模块依赖明确化，更新所有相关文档。

**优化内容**：

1. **术语库集成** (PRD 6.3)：
   - ✅ 明确文档编辑器功能由文档编辑引擎提供
   - ✅ 明确审批功能由审批引擎提供
   - ✅ 标注培训系统和翻译系统为可选功能（Phase 3+）

2. **架构文档同步** (03-architecture.md)：
   - ✅ 更新 SharePoint 功能矩阵
   - ✅ 添加版本控制职责划分（SharePoint vs 文档编辑引擎）
   - ✅ 添加 KB 文章编辑功能说明
   - ✅ 添加审批流程模块依赖
   - ✅ 更新依赖模块文档链接

3. **README 更新**：
   - ✅ 同步模块依赖关系
   - ✅ 保持与 PRD 一致

**影响范围**：

| 文档 | 变更内容 |
|------|---------|
| **01-prd.md** | • 6.3 术语库集成：添加"负责模块"列 |
| **03-architecture.md** | • 2.3 功能矩阵：明确版本控制、编辑、审批职责<br>• 10 相关文档：添加依赖模块链接<br>• 变更历史：记录 v1.1.0 |
| **99-changelog.md** | • 本文档，记录 v1.3.1 变更 |
| **README.md** | • 模块依赖：保持一致性 |

**设计原则**：
- 每个模块职责明确
- 依赖关系清晰可追溯
- 文档保持高度一致

---

## v1.3.0 - 2026-01-05

### 🏗️ 架构重构：文档编辑能力分离

**变更说明**：

将富文本编辑器从知识库模块中剥离，创建独立的**文档编辑引擎模块**。

**理由**：
- ✅ **复用性**：表单引擎、公告系统、评论系统等多个模块需要编辑能力
- ✅ **职责单一**：知识管理 ≠ 文档编辑
- ✅ **零技术债**：避免重复实现编辑器
- ✅ **可维护性**：独立测试、独立发版

**影响范围**：

| 文档 | 变更内容 |
|------|---------|
| **01-prd.md** | • 4.1.4 节：改为引用文档编辑引擎<br>• 添加插件机制说明（术语表插件等） |
| **03-architecture.md** | • 更新整体架构图，标注依赖关系<br>• 技术栈中改为引用文档编辑引擎 |
| **README.md** | • 添加模块依赖说明<br>• 更新技术栈列表 |
| **99-changelog.md** | • 本文档，记录架构变更 |

**相关文档**：
- [文档编辑引擎 PRD](../document-editor/01-prd.md)
- [文档编辑引擎架构](../document-editor/03-architecture.md)
- [文档编辑引擎 API](../document-editor/07-api.md)

**实施状态**：🟡 文档已更新，代码待实现

**设计原则**：
- 编辑器是通用能力，不是业务模块
- 通过插件机制支持业务定制
- 保持核心简洁，避免技术债

---

## v1.2.2 - PRD 落地细节深化说明（可评审版本）

### 📊 本次更新总览

基于专业反馈，补充了 **6 个运维/评审必问的关键细节**，使 PRD 达到可评审、可落地的标准。

---

## ✅ 已补充的 6 个关键细节

### 1. 权限映射边界明确 ✅

**问题**：只写 Group→Role 不够，Item-level 独立权限会被质疑

**补充内容**：
- ✅ **MVP 支持范围表**：
  - ✅ Site/Library/Folder 继承权限：完全支持
  - ✅ Item-level 独立权限：读取支持
  - ✅ SharePoint Group：完全支持
  - ✅ 基础共享链接：支持
  - ⚠️ 复杂共享链接组合：只读
  - ⚠️ 外部来宾混合权限：只读
  - ❌ 匿名链接：禁用（安全考虑）

**验收边界**：
- ✅ MVP 不追求"完美复刻 SharePoint 权限体系"
- ✅ 优先保证安全性和核心场景可用性

**文档位置**：`2.3.2 SharePoint 同步策略 - 权限映射规则`

---

### 2. Webhook 订阅与失效策略 ✅

**问题**：运维会问"不会掉变更吗？"

**补充内容**：
- ✅ **订阅有效期**：180 天（SP 标准），到期前 7 天自动续订
- ✅ **订阅管理**：自动续订 + 每日健康检查
- ✅ **失败重试**：指数退避（1s → 2s → 4s → 8s → 16s），最多 5 次
- ✅ **死信队列（DLQ）**：5 次失败后进 DLQ，人工介入或次日批量处理
- ✅ **轮询兜底**：每 15 分钟，回看最近 24 小时变更
- ✅ **监控告警**：Webhook 失败率 > 5% 自动告警

**可靠性保证**：
- ✅ Webhook + 轮询双保险，理论上不会遗漏变更
- ✅ 24 小时回看窗口，即使 Webhook 全部失败，最多延迟 24h

**文档位置**：`2.3.2 SharePoint 同步策略 - Webhook 可靠性保障`

---

### 3. 文本提取策略明确 ✅

**问题**：评审会问"怎么取？会不会丢格式？"

**补充内容**：
- ✅ **MVP 口径明确**：
  - 目标：提取可检索文本，支持全文搜索和基础问答
  - 方法：Microsoft Graph API 获取纯文本
  - 不追求：格式还原、精确布局、复杂结构（表格、图表）
  - 足够用于：关键词搜索、语义搜索、AI 问答

- ✅ **提取颗粒度演进**：
  - **MVP**：全文提取（扁平）- 快速上线，满足核心需求
  - **Phase 2**：结构化切分 - 按段落/标题/章节，提高引用颗粒度
  - **Phase 3+**：语义分块 - 基于语义边界，最佳 RAG 效果

**文档位置**：`2.3.2 SharePoint 同步策略 - 文本提取策略`

---

### 4. RAG 引用粒度与权限过滤验收条款 ✅

**问题**：答案中心的核心能力需要明确

**补充内容**：

#### 引用信息完整性（验收标准）：
- ✅ 必须包含：
  - 文档标题 + SharePoint 链接
  - 文档片段（snippet，100-200字）
  - 版本号 + 最后更新时间
  - 作者信息

#### 权限过滤时机（安全关键）：
- ✅ **检索前过滤**（非检索后）
- ✅ 确保检索结果 100% 来自用户有权访问的文档
- ✅ 禁止"先检索后过滤"（可能泄露标题）

#### 三重权限保障：
1. 检索前：用户只能检索到有权限的文档
2. 返回时：再次校验，确保引用链接可访问
3. 点击时：SharePoint 会再次校验权限

**示例输出**：包含完整引用信息的 JSON 格式

**文档位置**：`5.1.1 AI 智能问答 - 引用粒度与权限过滤`

---

### 5. 向量索引规模预估表 ✅

**问题**：缺少"随规模增长"的预期，会被问"1000+ 并发你怎么扛"

**补充内容**：

#### 规模预估表：

| 阶段 | 时间 | 文档数 | 平均长度 | Embedding 数 | 索引体积 | 每日增量 | 预计 QPS |
|------|------|-------|---------|------------|---------|---------|---------|
| MVP | Week 1 | 1,000 | 3,000字 | 150万向量 | 800MB | 20-50 | 5-10 |
| Month 3 | 3个月 | 5,000 | 3,500字 | 875万向量 | 4.2GB | 50-100 | 20-30 |
| Month 6 | 6个月 | 10,000 | 4,000字 | 2000万向量 | 9.6GB | 80-150 | 40-60 |
| Year 1 | 12个月 | 20,000 | 4,500字 | 4500万向量 | 21.6GB | 100-200 | 80-100 |

#### 计算依据：
- Embedding 数 = 文档数 × (平均长度 ÷ 200字/chunk) × 1.5（重叠）
- 索引体积 = Embedding 数 × 768维 × 4字节 × 1.3（索引开销）
- 每日增量 = 文档数 × 2-3%

---

## 🧩 其他文档对齐（2026-01-09）

- 原生文章编辑器对齐 Outline（ProseMirror），明确内容存储为 ProseMirror JSON 字符串
- 预计 QPS = 活跃用户数 × 0.1

#### 1000+ 并发应对方案：
1. **缓存层**：热门查询缓存（Redis），减少 80% 重复检索
2. **读写分离**：向量检索只读副本（3-5个），索引更新主节点（1个）
3. **负载均衡**：多个检索节点轮询，自动故障转移
4. **降级策略**：QPS > 阈值时，AI 问答降级为搜索

**文档位置**：`2.3.2 SharePoint 同步策略 - 向量索引规模预估`

---

### 6. MVP 元数据字段明确 ✅

**问题**：MVP 排除标签系统，但权威规则需要"官方/SOP/专家/已发布"等标记

**补充内容**：

#### 3 个核心元数据字段（替代复杂标签系统）：

1. **DocAuthorityLevel**（文档权威级别）
   - Official（官方政策/SOP）→ 权重 1.0
   - Expert（专家认证内容）→ 权重 0.9
   - Published（已发布知识）→ 权重 0.7
   - Draft（草稿/进行中）→ 权重 0.3

2. **DocLifecycleStatus**（生命周期状态）
   - Draft（草稿）
   - UnderReview（审核中）
   - Published（已发布）
   - Archived（已归档）
   - Deprecated（已废弃）

3. **DocType**（文档类型）
   - Policy（政策/制度）→ 权重加成 1.0
   - Manual（手册/指南）→ 权重加成 0.9
   - Tutorial（教程）→ 权重加成 0.7
   - FAQ（常见问题）→ 权重加成 0.6
   - General（一般文档）→ 权重 0.5

#### SharePoint 自定义字段配置指南：
提供完整的 SharePoint Site Columns 配置步骤

#### 数据抓手：
- ✅ 权威规则：DocAuthorityLevel + DocType
- ✅ 生命周期管理：DocLifecycleStatus
- ✅ 基础分类：DocType（够用，不需要复杂标签）

**文档位置**：`9.1 Phase 1: MVP - MVP 核心元数据字段`

---

## 📈 文档质量提升

### 从 v1.2.1 到 v1.2.2 的改进

| 改进维度 | v1.2.1 | v1.2.2 | 提升 |
|---------|--------|--------|------|
| **权限策略** | 基础映射 | MVP支持范围表 + 验收边界 | ✅ 评审可通过 |
| **同步可靠性** | Webhook + 轮询 | 完整失效策略 + DLQ + 24h回看 | ✅ 运维放心 |
| **文本提取** | "纯文本内容" | MVP口径 + 演进路径 | ✅ 预期明确 |
| **RAG能力** | "来源引用" | 引用完整性 + 权限过滤验收条款 | ✅ 核心能力明确 |
| **性能规划** | 存储成本对比 | 向量规模预估表 + 1000+ QPS方案 | ✅ 可扩展性证明 |
| **MVP设计** | 排除标签 | 3个核心字段 + SP配置指南 | ✅ 有数据抓手 |

---

## 🎯 现在可以做什么

### ✅ 文档已达到可评审标准

**可以立即安排评审会议**，重点讨论：

1. **11.1 落地关键点**（10分钟）

---

## ⚠️ 例外记录（需后续对齐文档）

### 2026-01-09 UI 风格例外（用户明确授权）

- **偏离点**：知识库编辑器页面采用飞书文档风格布局与视觉细节，不遵循 FF 设计系统的视觉规范。
- **偏离原因**：用户明确要求按飞书风格实现，并选择允许例外。
- **后续建议**：
  - 在 `docs/standards/DESIGN_SYSTEM.md` 或 `docs/modules/knowledge-base/05-ui-interaction-spec.md` 记录例外范围与恢复策略。
  - 若未来需统一品牌视觉，应规划替换为 FF 设计系统样式。
   - 快速过一遍 8 个关键点
   - 确认没有遗漏

2. **9.1 Phase 1 MVP**（15分钟）
   - 确认范围和验收标准
   - 确认 3 个核心元数据字段设计

3. **2.3.2 SharePoint 同步策略**（20分钟）
   - 确认技术方案可行性
   - 确认 Webhook 可靠性策略
   - 确认权限映射边界

4. **5.1.1 AI 问答**（15分钟）
   - 确认引用粒度和权限过滤
   - 确认权威规则数据抓手

5. **向量索引规模预估**（10分钟）
   - 确认性能预期
   - 确认 1000+ QPS 应对方案

### ✅ 可以开始的准备工作

1. **SharePoint 自定义字段配置**：
   - 在测试环境创建 3 个自定义列
   - 测试字段同步

2. **技术选型确认**：
   - Webhook 订阅测试
   - 向量数据库选型（Qdrant/Pinecone）
   - 文本提取 API 测试

3. **基线测量计划**：
   - 准备用户调研问卷
   - 安排文档相似度抽样
   - 收集 HR 数据

---

## 📊 6 个关键细节对比

| # | 关键细节 | v1.2.1 | v1.2.2 | 价值 |
|---|---------|--------|--------|------|
| 1 | 权限映射 | 基础映射 | MVP支持范围表 + 验收边界 | ✅ 避免"完美复刻SP权限"担忧 |
| 2 | Webhook | 基础描述 | 完整可靠性策略（订阅/重试/DLQ/回看） | ✅ 运维相信"不会掉变更" |
| 3 | 文本提取 | "纯文本" | MVP口径明确 + Phase演进路径 | ✅ 预期明确，不会被追问 |
| 4 | RAG引用 | "来源引用" | 引用完整性验收标准 + 权限过滤时机 | ✅ 答案中心能力明确 |
| 5 | 向量规模 | 存储成本 | MVP→Year1预估表 + 1000+ QPS方案 | ✅ 性能规划可信 |
| 6 | MVP元数据 | 排除标签 | 3个核心字段 + SP配置指南 | ✅ 权威规则有数据抓手 |

---

## 🎯 评审建议

### 重点关注（会被问到的）

1. ✅ **权限边界**："能不能完美支持 SP 所有权限？"
   - 回答：MVP 支持核心场景（继承+Item-level读取），复杂场景简化，安全优先

2. ✅ **同步可靠性**："Webhook 失败了怎么办？"
   - 回答：重试+DLQ+24h轮询兜底，三重保障

3. ✅ **文本提取**："格式会丢吗？"
   - 回答：MVP 不追求格式还原，只要可检索文本；Phase 2 结构化切分

4. ✅ **权限泄露**："会不会先检索再过滤导致泄露标题？"
   - 回答：检索前过滤，三重权限保障

5. ✅ **并发性能**："1000+ 用户同时搜索怎么办？"
   - 回答：缓存+读写分离+负载均衡+降级策略

6. ✅ **权威规则**："没有标签系统，怎么区分官方文档？"
   - 回答：3 个核心元数据字段（DocAuthorityLevel/DocLifecycleStatus/DocType）

### 次要关注（可能被问到）

- Webhook 订阅有效期和续订机制
- 向量索引增长预期和扩展方案
- SharePoint 自定义字段配置方法
- RAG 引用片段长度和格式

---

## 📞 联系方式

如有疑问，请联系产品团队：product@example.com

---

**文档版本**：PRD v1.2.2  
**更新日期**：2025-12-22  
**状态**：✅ 可评审版本  
**下一步**：安排评审会议