与《知识库平台功能文档》的差距（Roadmap，诚实版）¶
本文回答一个问题：当前
docs.nfarms.cn与其功能文档（NF-26-007《Docs 知识库平台功能文档》）差多远？结论先行：它不是文档描述的那个系统。 线上是一个 MkDocs（Material 主题）静态文档站， 服务本仓库的规范与手册 Markdown；而功能文档描述的是一个 多源企业知识库应用 （Spring Boot + MySQL + Elasticsearch + Redis + MinIO + OAuth2 + 评论邮件闭环）。 两者在架构上不同源，因此下面的差距不是"待开发的小功能"，而是"需要新建一套系统"。
本文只做事实陈述与工作量级评估，不声称任何未实现的能力。
一、当前实际形态（可核对）¶
| 维度 | 现状 | 依据 |
|---|---|---|
| 站点类型 | MkDocs 静态站（Material 主题），构建产物 77 个文件 |
服务器 /opt/Cy/docs/site；build.sh |
| Nginx | root /opt/Cy/docs/site，try_files $uri $uri/ =404，无 /api/ 反代 |
/opt/Cy/services/nginx.d/docs-nfarms.conf |
| 访问控制 | 全站公开，无登录门禁（无 auth_request） |
同上；线上 GET / = 200 |
| 内容来源 | 仓库 deploy/docs-site/source/**（Markdown），人工/脚本重建 |
deploy/docs-site/mkdocs.yml 的 nav |
| 检索 | MkDocs search 插件（浏览器端索引，/search/search_index.json） |
mkdocs.yml plugins.search |
| 后端 | 无（无数据库、无对象存储、无消息队列） | 站点配置无 proxy_pass |
| 编辑 | 无编辑入口（静态产物本身不可编辑） | 站点形态使然 |
二、与功能文档逐条对照¶
标注说明：需引入组件 = 必须新增的系统/中间件；人日 为"从零到可用"的粗估区间（不含长期运维与内容治理）； 前置条件 = 必须先具备的东西（含决策与合规）。
2.1 多源导入与知识体系¶
| 文档要求 | 现状 | 需引入组件 | 人日 | 前置条件 |
|---|---|---|---|---|
| 深度集成飞书 / 腾讯文档 / 谷歌文档，增量同步与批量迁移 | 无任何第三方对接 | 三个平台的开放平台应用与凭据；后端服务（任一语言）+ 任务队列 | 15–30 | 各平台企业应用审批、回调可用性、数据出境合规评估（谷歌文档） |
| 统一文档入口 / 多级目录 / 标签体系 | MkDocs 静态导航，无标签 | 数据库（MySQL 或 PostgreSQL）+ 目录/标签模型 + 管理界面 | 10–20 | 上一条的后端服务 |
| Elasticsearch 毫秒级全文检索 + 多维筛选 | 浏览器端 lunr 索引，仅本站内容 | Elasticsearch（或 OpenSearch）+ 索引管道 + 检索 API | 8–15 | 部署与运维 ES 集群（内存/磁盘/备份） |
| 格式无损转换（富文本/二进制 → Markdown/HTML） | 无 | 转换服务（Pandoc / LibreOffice headless 等） | 5–10 | 转换保真度验收标准 |
| MinIO 对象存储 + 预签名 URL（按访问级别差异化有效期） | 无对象存储 | MinIO + 预签名签发逻辑 | 3–6 | 存储容量与冷备方案 |
评论邮件闭环（服务邮箱 docs-comments@nfarms.cn，写 comment_notification_log，支持重试） |
无评论系统、无邮件 | SMTP/SES 凭据 + 评论数据模型 + 通知服务 + 重试与状态追踪 | 6–12 | 邮箱授权码/发信域 SPF-DKIM；服务邮箱开通 |
2.2 分级鉴权与安全¶
| 文档要求 | 现状 | 需引入组件 | 人日 | 前置条件 |
|---|---|---|---|---|
| L1 公开 / L2 登录 / L3 隐私白名单 三级模型 | 全站公开 | 统一登录（平台已有 nfarmsd /auth/verify 可复用）+ access_policy 字段 + 网关鉴权 |
6–12 | 决定 L2/L3 的内容边界与标注责任 |
| L2/L3 列表内模糊标题 + 点击提示登录 | 无 | 前端改造（需有前端应用，当前无） | 3–6 | 上一行的后端 |
| 编辑权限统一关闭（含管理员），修改只走评论 | 已符合（静态站本就没有编辑入口） | —— | 0 | —— |
| 401/403 语义、PUT/PATCH/DELETE 直接拒绝 | 无 | 网关策略 + 审计 | 3–5 | 鉴权后端 |
L3 预览动态水印（user_id + timestamp + IP） |
无 | 文档流式返回 + 水印合成服务 | 5–10 | 文档预览服务（PDF/图片渲染） |
ES 文档级安全过滤（access_policy / allowed_user_ids） |
无 | ES 查询过滤器 + 字段建模 | 3–5 | ES 与鉴权后端 |
| L3 访问工单（理由/时长/承诺 → 审批 → 白名单 7 天自动过期） | 无 | 工单模型（平台已有 tickets 能力可复用）+ 定时过期任务 + 站内信/邮件 | 8–15 | 审批责任人定义；与平台工单/告警治理的关系确认 |
| RBAC（菜单/数据/操作三维度）+ 全量操作审计 | 无（docs 站无账号体系） | 复用 nfarmsd 用户/角色 + 审计表 | 6–10 | 与平台 RBAC 统一口径 |
| 外部分享限制 / 水印 / 操作日志"事前预防·事中控制·事后追溯" | 无 | 同上 | 含于上两行 | —— |
2.3 文档协作、评论与 AI¶
| 文档要求 | 现状 | 需引入组件 | 人日 | 前置条件 |
|---|---|---|---|---|
| 段落级评论、@提及、修订记录追溯 | 无 | 评论定位模型（文档版本 + 锚点）+ 通知 | 10–20 | 文档预览器的锚点能力 |
| 未登录访客可评论（需填昵称/邮箱，身份标"访客"，邮箱作 Reply-To） | 无 | 防滥用（验证码/限流）+ 邮件 Reply-To | 3–5 | 法务/风控对匿名评论的口径 |
| AI 问答（检索片段 → 组装 Prompt → LLM 流式返回） | 无 | 向量库或 ES 片段检索 + LLM 网关（平台已有 MCP 网关） | 8–15 | 模型/额度审批；答案准确性免责声明 |
| 编辑建议在源平台落实 → 触发增量导入 | 无 | 依赖多源导入（见 2.1） | 含于 2.1 | —— |
2.4 运维与系统设置¶
| 文档要求 | 现状 | 需引入组件 | 人日 | 前置条件 |
|---|---|---|---|---|
| 系统设置（存储/导入源/通知/备份/API/数据迁移），Redis Pub/Sub 热加载 | 无 | 配置中心 + Redis | 8–15 | 上列后端 |
| 定时备份（dump 数据库 + 打包对象存储） | 站点由 build.sh 重建，无数据备份概念 |
备份任务（可复用平台 nfos-backup 思路） |
2–4 | 数据库与对象存储就位 |
| 第三方 API Key + 签名/IP 白名单/速率限制 | 无 | 网关策略 | 3–6 | 鉴权后端 |
| 日志轮转（按日/月归档、保留期清理） | 平台层已有轮转机制，站点层无日志 | —— | 1–2 | —— |
三、如果要做，建议的推进顺序¶
- 先定边界（0.5–1 人日，纯决策）：L2/L3 到底指哪些内容？"编辑统一关闭"在源平台（飞书/腾讯/谷歌）如何落责？ 这一步不产出代码，但决定后面所有设计的对错。
- 后端骨架（5–8 人日）：文档/版本/目录/标签/权限四张核心表 + 上传/列表/详情/检索四个接口。 此步完成前，任何前端工作都是空转。
- 检索（3–5 人日）：接 ES，含文档级安全过滤。
- 鉴权（3–5 人日）：复用 nfarmsd 统一登录，落
access_policy，接 L3 工单（复用平台 tickets）。 - 评论与邮件闭环（4–6 人日）：评论 + 通知服务 +
comment_notification_log。 - 多源导入（10–20 人日，视平台审批速度）：逐个平台接，先在飞书打通。
- 预览与安全增强（5–10 人日）：PDF/Word 预览、L3 水印、预签名 URL。
- AI 问答（5–10 人日）：检索 + LLM 网关。
合计粗估：45–90 人日（不含内容治理、长期运维与合规评审），且必须新建后端服务与数据库—— 这不是在现有 MkDocs 静态站上"加功能"能完成的。
四、当前能做且已做的小事（避免误解为"什么都没做"）¶
- 文档站与仓库版本对齐：线上
mkdocs.yml长期停留在 9 月 12 日版本，与本仓库deploy/docs-site/mkdocs.yml不同步。本轮已把仓库版本同步到线上并重建站点（站点 200，产物核对通过）。 - 本页的存在：把"功能文档 vs 现状"的差距写成可排期的清单，而不是留作口头印象。
本文档由平台维护者在"按文档修正"任务中补充，内容以线上实际可核对的事实为准； 如后续真的启动了知识库应用建设，请把本文改为"已实现/进行中/未开始"三态清单，而不是继续沿用"差距"口径。