front/docs/物流业务知识库设计方案.md

物流业务知识库设计方案

文档状态：产品 + 架构 + 表结构 + 接口 + 页面（评审已拍板关键决策，可开发）
编写日期：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 逻辑架构

┌──────────────┐  ┌──────────────┐  ┌─────────────────┐
│ 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　关键用户旅程

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 含 <script> 前端不执行
回归	AI Skill 管理、公告、客服入口、门户营销抽屉不受影响

---

13　工作量粗估（供排期）

项	人天（约）
表 + 仓储 + Admin/Portal API	3～4
管理端分类 + 文章页（含置顶）	3～4
PC 帮助抽屉 + 入口	2～3
H5 帮助	1.5～2
工作台/顶栏入口 + i18n（壳）+ 种子 FAQ	1
M2 检索注入 + 来源展示	2～3
M1 合计	约 10～14
M1+M2	约 12～17

---

14　已拍板结论（原待评审）

#	问题	结论
1	未登录是否可访问门户帮助？	不允许；必须客户登录
2	管理菜单挂载？	独立一级「知识库」
3	M1 语言？	先中文；不建英文字段
4	客户入口形态？	右侧抽屉（非独立 /help 主路径）
5	是否需要置顶/热门？	需要：IsPinned + /kb/portal/article/hot

---

15　修订记录

日期	说明
2026-08-04	初稿：M1 帮助中心 + M2 AI 检索 + M3 边界；与 AiSkill / 在线客服边界对齐
2026-08-04	拍板：禁止匿名、独立知识库菜单、仅中文、抽屉入口、置顶/热门；更新表结构与验收

---

文档结束。 关键决策已拍板，可按 M1 → M2 开工；页面开发须满足 docs/前端页面设计规范.md。