# 物流业务知识库设计方案 > **文档状态**：产品 + 架构 + 表结构 + 接口 + 页面（**评审已拍板关键决策，可开发**） > **编写日期**：2026-08-04 > **仓库**：前端 `E:\oms0414`，后端 `oms0414-back` > **关联页面**：中后台「知识库」独立菜单（新建）、PC/H5 帮助抽屉、工作台入口、AI 顾问检索增强（二期） > **关联能力**：AI 顾问（`/xhs/ai/chat`、`AiAdvisorShell`）、在线客服（见关联文档）、站内信公告、`t_ai_skill`（**不复用**）、门户侧栏抽屉（可复用 `PortalSideDrawer` 模式） > **关联文档**：`docs/在线客服模块设计方案.md`、`docs/H5客户中心设计方案.md`、`docs/前端页面设计规范.md`、`docs/rbac系统设计-060801.md` > **目标读者**：产品、运营、前端、后端、测试 --- ## 0　阅读指引 | 角色 | 优先阅读 | | --- | --- | | 产品 / 运营 | §1～§3、§5、§6、§11 | | 前端 | §5、§6、§8、§10 | | 后端 / DBA | §4、§7～§9、§10 | | 测试 | §3、§7、§11、§12 | **分期对照** | 阶段 | 名称 | 交付物 | | --- | --- | --- | | **M1** | 帮助中心（主交付） | 分类/文章表、管理端 CRUD、客户侧帮助浏览与搜索、工作台/H5 入口 | | **M2** | AI 检索增强 | 问答时检索 Top-K 文章注入 prompt；回答带来源链接 | | **M3** | 运营闭环 | 未命中落库、坐席「沉淀为知识」、按国家/产品可见范围 | > 本文默认按 **M1 → M2** 落地；M3 列边界。 > **与在线客服文档关系**：客服方案 P0/P1 **不做**「机器人知识库编排、意图平台」；本文 M1 是独立内容资产，M2 再作为 AI/客服的检索源，不推翻客服分期。 --- ## 1　背景与目标 ### 1.1 现状与问题 | 现状 | 问题 | | --- | --- | | 计费、状态、问题件口径散落在运营口头 / 聊天记录 | 客户重复问，客服重复答，口径易漂 | | AI 顾问主要靠通用对话 + Skill 提示词 | **Skill ≠ 业务 FAQ**；缺可检索、可溯源的业务文案 | | 工作台有公告，无结构化帮助 | 公告偏通知，不适合「怎么查价 / 什么是计费重」类常驻说明 | | `t_ai_skill` 已存在 | 场景是价表风险、地址解析等**对内提示词**，不宜硬扩成客户知识库 | ### 1.2 建设目标 1. **可运营的内容资产**：分类 + 文章，支持草稿/发布/下线；**M1 只做中文**，英文字段预留到后续迭代。 2. **对客自助优先**：登录客户通过 **右侧抽屉** 浏览/搜索帮助，减少「纯靠问人」。 3. **可挂业务入口**：文章可链到查价、我的订单、充值等，形成闭环。 4. **为 AI 留接口**：M1 只做内容与检索 API；M2 再注入顾问，回答带来源。 5. **与 Skill 边界清晰**：Skill 管「怎么让模型做事」；知识库管「业务事实怎么写给人/模型看」。 ### 1.3 已拍板决策 | # | 决策 | 口径 | | --- | --- | --- | | 1 | 模型分离 | **新建 KB 表**，不扩展 `t_ai_skill` | | 2 | 首期检索 | **关键词 + 分类/标签**；不上向量库 | | 3 | 受众 | 文章带 `Audience`：`customer` / `internal`；客户接口只返回 customer | | 4 | 富文本 | M1 用 **Markdown**（或受限 HTML）；不做复杂 CMS 组件市场 | | 5 | 访问控制 | **必须客户登录**；门户接口不允许匿名 | | 6 | 管理菜单 | **独立一级「知识库」**（下挂分类、文章），不挂在系统/运营子菜单下 | | 7 | 语言 | **M1 仅中文**；表结构不强制英文字段 | | 8 | 客户入口 | **右侧抽屉**（非独立 `/help` 整页）；工作台/顶栏/H5 打开同一套帮助抽屉或 H5 等价页 | | 9 | 置顶 / 热门 | **需要**：`IsPinned` + 热门列表接口（可结合 `ViewCount`） | ### 1.4 设计原则 1. **先文案质量，后检索玄学**：50～100 条高质量 FAQ 优于空壳 RAG。 2. **结构化优于长文堆砌**：标题、摘要、标签、适用场景字段齐全。 3. **时效可控**：禁限运、清关类必须有「生效/过期」或「最后复核日」。 4. **不替代订单状态机**：知识库解释规则，不写业务真相（轨迹以订单接口为准）。 5. **对齐前端规范**：管理列表用 TablePro / FormPro；客户侧帮助页可略营销风，但色彩跟主色。 ### 1.5 非目标（M1 / M2 不做） - 完整意图识别平台、多轮对话编排器 - 向量库 / Embedding 流水线（M3+ 可议） - 企微/第三方知识库同步 - 客户可投稿（仅内部运营/坐席写入） - 把 OMS 设计文档（`docs/*.md`）自动全量灌入对客库 --- ## 2　概念与命名 | 术语 | 含义 | | --- | --- | | **分类** | `KbCategory`；树或扁平一级（M1 建议**扁平一级 + SortOrder**，降低复杂度） | | **文章** | `KbArticle`；一篇可发布的帮助正文 | | **受众** | `Audience`：`customer` 对客 / `internal` 仅内部 | | **标签** | 逗号或关联表；如 `计费重`、`问题件`、`美国` | | **发布状态** | `draft` 草稿 / `published` 已发布 / `offline` 下线 | | **置顶** | `IsPinned`；对客列表中置顶文优先展示 | | **热门** | 门户「热门」：优先置顶，其次按 `ViewCount` / 发布时间 | | **Skill** | `t_ai_skill`；平台提示词，**不属于本文实体** | 对客文案用「帮助中心 / 常见问题」；**管理端一级菜单名为「知识库」**。 --- ## 3　产品分期 ### 3.1 M1 — 帮助中心（约 1.5～2.5 周） **目标**：客户能搜、能看；运营能维护。 | 项 | 说明 | | --- | --- | | 管理端 | **独立一级菜单「知识库」**：分类、文章 CRUD、置顶、发布/下线、预览 | | 客户 PC | **右侧帮助抽屉**：分类浏览 + 搜索 + 热门 + 详情（需登录） | | 客户 H5 | 「我的 → 帮助中心」列表/详情（需登录；小屏用页而非宽抽屉亦可） | | 工作台 / 顶栏 | 「帮助」入口 → `openHelpDrawer()` | | 接口 | 管理 CRUD + 对客 list/get/search/hot（**禁止匿名**） | | 语言 | **仅中文** | | 不做 | AI 注入、未命中分析、按国家可见性细控、英文正文 | ### 3.2 M2 — AI 检索增强 **目标**：顾问回答可溯源。 | 项 | 说明 | | --- | --- | | 检索 | `POST /kb/search`（或内部服务）按关键词打分取 Top-K（建议 3） | | 注入 | `/xhs/ai/chat` 或统一 AI 网关在拼 prompt 时附带文章摘要 | | 展示 | 回答底部「参考：xxx」可点进帮助详情 | | 兜底 | 无命中 → 现有 AI 行为 + 引导转人工/帮助首页 | ### 3.3 M3 — 运营闭环（延后） - 搜索无结果 / AI 未命中写 `kb_miss_log` - 坐席工作台「沉淀为知识」草稿 - `VisibleCountryCodes` / `SalesProductIds` 可见范围 - 可选：简易向量检索替换关键词 --- ## 4　总体架构 ### 4.1 逻辑架构 ```text ┌──────────────┐ ┌──────────────┐ ┌─────────────────┐ │ PC 帮助抽屉 │ │ 一级菜单知识库 │ │ AI 顾问（M2） │ │ H5 帮助页 │ │ 分类/文章运营 │ │ chat + 检索注入 │ └───────┬──────┘ └──────┬───────┘ └────────┬────────┘ │ REST │ REST │ 内部检索 ▼ ▼ ▼ ┌─────────────────────────────────────────────────────┐ │ Oms Api：KbCategoryService / KbArticleService │ │ （门户接口强制登录 + Audience=customer） │ └──────────────────────────┬──────────────────────────┘ ▼ MySQL（t_kb_*） ``` ### 4.2 与现有模块关系 | 现有能力 | 关系 | | --- | --- | | `t_ai_skill` | **并列**；禁止混表 | | `/xhs/ai/chat`、AI 顾问壳 | M2 检索注入与「参考来源」展示 | | 在线客服 | M2/M3：答不上来转人工；坐席可沉淀知识 | | 工作台公告 | 通知向；帮助中心常驻说明；可互相链接 | | RBAC | 管理权限码见 §8.3 | | 文件上传 | 文章内图片可复用现有上传（folder：`kb`） | ### 4.3 内容域（运营初始类目建议） | 分类 Code（建议） | 名称 | 典型文章 | | --- | --- | --- | | `pricing` | 查价与计费 | 计费重、偏远、附加费、预报 vs 入库差额 | | `order` | 下单与轨迹 | 状态含义、待上网、如何查轨迹 | | `exception` | 问题件与售后 | 补资料、退件、索赔口径 | | `customs` | 禁限运与清关 | 品名、敏感国、电池等（强时效） | | `account` | 账户与充值 | 余额、充值、发票 | | `dropship` | 代发与店铺 | 授权、拉单、履约配对 | M1 种子数据可由运营导入 10～20 条高频 FAQ，不阻塞开发。 --- ## 5　页面与交互 ### 5.1 管理端（中后台） **菜单**：独立一级 **「知识库」**，子菜单建议： | 子菜单 | Path（建议） | 说明 | | --- | --- | --- | | 分类管理 | `/kb/category` | 列表：名称、Code、排序、启用；弹窗编辑 | | 文章管理 | `/kb/article` | 筛选：分类、状态、受众、关键词、是否置顶；TablePro | | 文章编辑 | 同页抽屉 | 标题、摘要、Markdown、标签、受众、置顶、状态、关联链接 | **编辑页字段** - 必填：`Title`、`CategoryId`、`Audience`、`Content`、`Status` - 选填：`Summary`、`Tags`、`RelatedPath`、`RelatedLabel`、`IsPinned`、`PublishTime`、`ExpireTime` - 操作：保存草稿、发布、下线、设为置顶/取消置顶、预览（按客户视角渲染） - **语言**：界面与正文字段均为中文，不提供英文字段录入 ### 5.2 客户 PC（帮助抽屉） | 入口 | 交互 | | --- | --- | | 顶栏 / 工作台「帮助」 | 打开右侧 `HelpSideDrawer`（宽度可对齐门户抽屉约 640px） | | 抽屉首页 | 搜索框 + 「热门」区（置顶优先）+ 分类芯片 + 文章列表 | | 详情 | 抽屉内二级页：标题、更新时间、正文、相关推荐、「去办理」；返回列表不关抽屉 | | 未登录 | 入口点击 → 跳转登录（抽屉接口本身 401） | > **不做**独立整页路由 `/help` 作为主路径；若需深链，可用 query 打开抽屉（如 `?helpArticle=12`），由布局层解析。 ### 5.3 客户 H5 - 「我的 → 帮助中心」→ 列表（分类 Tab + 热门）→ 详情（小屏用全屏页，体验等同抽屉信息架构） - 必须登录；遵循 H5 客户中心规范；Markdown 消毒渲染 ### 5.4 空态与权限 - 无文章：友好空态 + 联系客服入口 - `internal` 文章不对客户接口返回 - 匿名请求门户接口 → **401 / 未登录**，不返回数据 --- ## 6　关键用户旅程 ```mermaid flowchart LR A[客户遇计费疑问] --> B{打开帮助抽屉} B -->|搜到/热门| C[读文章] C --> D{能自行解决?} D -->|是| E[点关联入口去查价/下单] D -->|否| F[AI 顾问 / 联系客服] B -->|搜不到| F B -->|未登录| G[跳转登录] ``` M2 增强：`F` 中 AI 先检索 KB；有命中则引用；无命中再纯模型或转人工。 --- ## 7　表结构 > 库表前缀 `t_kb_`；SqlSugar 实体放 `Oms.Domain` 新聚合或 `System`/`Content` 域（实现时定）；审计字段对齐现有 `OmsAuditedAggregateRoot`。 ### 7.1 `t_kb_category` 分类 | 列 | 类型 | 说明 | | --- | --- | --- | | Id | INT PK AI | | | Code | VARCHAR(64) UK | 稳定键，如 `pricing` | | Name | VARCHAR(128) | 展示名（中文） | | SortOrder | INT | 越小越前 | | Enabled | TINYINT | 1 启用 | | IsDeleted | TINYINT | 软删 | | ConcurrencyStamp | CHAR(36) | | | CreateUserId / CreateTime / UpdateUserId / UpdateTime | | 审计 | > M1 **不建** `NameEn`；后续多语言另开迭代或加列。 索引：`uk_kb_category_code`；`idx_kb_category_enabled_sort (Enabled, SortOrder)`。 ### 7.2 `t_kb_article` 文章 | 列 | 类型 | 说明 | | --- | --- | --- | | Id | INT PK AI | | | CategoryId | INT | 分类 | | Title | VARCHAR(200) | 标题（中文） | | Summary | VARCHAR(500) NULL | 列表摘要 | | Content | LONGTEXT | Markdown 正文（中文） | | Audience | VARCHAR(16) | `customer` / `internal` | | Status | VARCHAR(16) | `draft` / `published` / `offline` | | Tags | VARCHAR(256) NULL | 逗号分隔 | | RelatedPath | VARCHAR(256) NULL | 站内 path，如 `/order/priceCheck` | | RelatedLabel | VARCHAR(64) NULL | 按钮文案，如「去查价」 | | IsPinned | TINYINT | **置顶**：1=是；对客列表优先 | | SortOrder | INT | 同类排序（置顶之后的次序） | | PublishTime | DATETIME NULL | 发布时间 | | ExpireTime | DATETIME NULL | 过期后对客不可见 | | ViewCount | INT DEFAULT 0 | 浏览次数（热门排序参考） | | IsDeleted | TINYINT | | | ConcurrencyStamp | CHAR(36) | | | 审计字段 | | | 索引： - `idx_kb_article_list (Status, Audience, CategoryId, IsPinned, SortOrder)` - `idx_kb_article_publish (Status, Audience, PublishTime)` - `idx_kb_article_hot (Status, Audience, IsPinned, ViewCount)` - 全文：M1 可用 `LIKE`；数据量大后再上 `FULLTEXT(Title, Summary, Tags)`（MySQL） ### 7.3 M3 预留（本稿不建表也可） | 表 | 用途 | | --- | --- | | `t_kb_miss_log` | 搜索词、来源（help/ai）、用户、时间 | | `t_kb_article_scope` | 国家/销售产品可见范围 | ### 7.4 SQL 脚本命名 建议：`sql/202608xx_kb_knowledge.sql`（按实际落库日命名）。 --- ## 8　接口设计 ### 8.1 约定 - 前缀建议：`/kb/*` - 统一业务包装：`{ code, msg, data }`（与现网一致） - 写操作校验 `ConcurrencyStamp`（若实体含） ### 8.2 管理端（需登录 + 权限） | 方法 | 路径 | 说明 | | --- | --- | --- | | GET | `/kb/admin/category/list` | 全部分类（含停用） | | POST | `/kb/admin/category/save` | 新增/编辑分类 | | POST | `/kb/admin/category/delete` | 软删（有文章时禁止或需迁移） | | GET | `/kb/admin/article/page` | 分页：keyword/categoryId/status/audience/isPinned | | GET | `/kb/admin/article/{id}` | 详情 | | POST | `/kb/admin/article/save` | 保存草稿或更新（含 `IsPinned`） | | POST | `/kb/admin/article/publish` | 发布（写 PublishTime） | | POST | `/kb/admin/article/offline` | 下线 | | POST | `/kb/admin/article/pin` | 设为置顶 / 取消置顶（可选独立接口，或并入 save） | | POST | `/kb/admin/article/delete` | 软删 | ### 8.3 权限码（建议） | 权限码 | 用途 | | --- | --- | | `Knowledge.Category.Query` / `Knowledge.Category.Edit` | 分类 | | `Knowledge.Article.Query` / `Knowledge.Article.Edit` / `Knowledge.Article.Publish` | 文章 | **菜单挂载**：**独立一级「知识库」**（子：分类管理、文章管理）；`meta.permission` 对齐 RBAC。路由 path 建议 `/kb/category`、`/kb/article`（camelCase 子路径按项目惯例可写成 `kbCategory`）。 ### 8.4 客户端（**必须客户登录，禁止匿名**） 门户 `/kb/portal/*` **一律要求登录**；未登录返回 401。不提供 `AllowAnonymous` 只读接口。 | 方法 | 路径 | 说明 | | --- | --- | --- | | GET | `/kb/portal/category/list` | 启用中的分类 | | GET | `/kb/portal/article/page` | 已发布 + customer + 未过期；支持 categoryId、keyword | | GET | `/kb/portal/article/{id}` | 详情；校验受众与状态；`ViewCount+1` | | GET | `/kb/portal/article/hot` | **热门**：`IsPinned` 优先，其次 `ViewCount`、`PublishTime`；默认 Top 10 | 搜索 / 列表排序规则（M1）： 1. `Status=published` 且 `Audience=customer` 2. `ExpireTime` 为空或 > now 3. `keyword` 匹配 `Title` / `Summary` / `Tags`（`LIKE`） 4. 排序：`IsPinned DESC` → `SortOrder ASC` → `PublishTime DESC` 5. 热门接口：`IsPinned DESC` → `ViewCount DESC` → `PublishTime DESC` ### 8.5 M2 内部检索 | 方法 | 路径 | 说明 | | --- | --- | --- | | POST | `/kb/internal/search` | Body：`{ query, topK, audience? }`；仅服务端/AI 网关调用 | 返回：`[{ id, title, summary, score, relatedPath }]`，正文可截断后注入 prompt（控制 token）。 --- ## 9　服务端实现要点 1. **门户接口硬过滤** `Audience` + `Status`，并校验登录态，防止匿名与 internal 泄漏。 2. **Markdown 渲染**：前端消毒（DOMPurify 或等价）；禁止任意脚本。 3. **图片**：上传走现有文件服务，`folder=kb`，正文存相对/绝对 URL。 4. **并发**：编辑带 `ConcurrencyStamp`。 5. **删除分类**：若仍有未删文章 → 返回业务错误。 6. **置顶**：同一分类可多篇置顶；列表统一 `IsPinned DESC`。 7. **缓存（可选）**：门户分类/热门短缓存 1～5 分钟；发布/下线/置顶时失效。 --- ## 10　前端实现要点 ### 10.1 管理端 - 独立一级菜单「知识库」+ 子路由；遵循 `docs/前端页面设计规范.md` - 权限：`hasPermission('Knowledge.Article.Edit')` 等控制按钮 - Markdown 编辑 + 预览；列表展示置顶标记 ### 10.2 客户帮助抽屉（PC） - 新建 `HelpSideDrawer`（可参考 `PortalSideDrawer`：固定宽、无整页路由） - `openHelpDrawer({ articleId? })` 供工作台、顶栏、深链调用 - 与个人中心/营销抽屉并存时注意互斥或叠层 z-index - i18n：壳文案用 `help.*`；**文章正文仅中文**，不做 `TitleEn` 切换 ### 10.3 工作台入口 - 「帮助」文字链或图标 → 打开帮助抽屉 - 不强制占营销四宫格 ### 10.4 H5 - 「我的 → 帮助中心」全屏列表/详情；登录态与 PC 同一套 portal API --- ## 11　验收标准 ### 11.1 M1 | # | 标准 | | --- | --- | | 1 | 独立一级菜单「知识库」可维护分类与文章（含置顶） | | 2 | **已登录**客户可从工作台/顶栏打开帮助抽屉：分类、搜索、热门、详情 | | 3 | **未登录**无法调用门户 KB 接口（401）；入口引导登录 | | 4 | `internal` / draft / offline / 过期文章客户不可见 | | 5 | 有 `RelatedPath` 时可从抽屉跳转业务页 | | 6 | 正文与管理界面为中文；无英文字段录入 | | 7 | 热门区置顶文优先于按浏览量排序的普通文 | ### 11.2 M2 | # | 标准 | | --- | --- | | 1 | 相关问题提问时，回答中可出现参考文章标题 | | 2 | 点击参考可进入帮助详情 | | 3 | 知识库全空时 AI 行为与现网一致（不报错） | --- ## 12　测试要点 | 类型 | 用例 | | --- | --- | | 权限 | 无 `Knowledge.Article.Edit` 不能 save；客户调 admin 403；**匿名调 portal 401** | | 过滤 | draft/offline/expired/internal 组合对 portal 不可见 | | 置顶/热门 | 置顶文排在热门与列表前部；取消置顶后顺序恢复 | | 搜索 | 中文关键词命中标题/标签；无结果空列表 | | 抽屉 | 列表↔详情切换不丢搜索条件；关闭后再开恢复首页 | | 并发 | 双人编辑同一文章 stamp 冲突 | | 安全 | Content 含 `