481 lines
20 KiB
Markdown
481 lines
20 KiB
Markdown
# 物流业务知识库设计方案
|
||
|
||
> **文档状态**：产品 + 架构 + 表结构 + 接口 + 页面（**评审已拍板关键决策，可开发**）
|
||
> **编写日期**：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 含 `<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`。
|