# 综合牧业知识库 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 综合牧业知识库（牧业养殖科技服务） |
| 目标 | 在业务后台维护**牧业综合知识条目**（标题、主题、简介、正文附件），支持检索与**入库/移出**外部知识库，为智能问答、检索等下游能力提供知识素材 |
| 关联系统 | 业务后台；**外部知识库服务**（同步、移出、删除通知） |
| 修订依据 | 同目录 `综合牧业知识库管理功能需求-草稿.md`、界面原型（列表、新增表单） |

本文档**仅描述功能需求与业务规则**，不涉及数据库表结构、接口路径、请求体字段命名、HTTP 报文、权限标识命名及技术栈选型。

> **与「养殖标准」等模块的差异：** 本模块**不涉及**「发布 / 下架」对外展示生命周期；仅以**入库状态**（是否已写入外部知识库）控制可编辑性与操作按钮。

---

## 2. 术语与业务对象

### 2.1 知识条目（一条台账记录）

- 表示一条可独立检索、可同步至外部知识库的**牧业领域知识**。  
- 由授权用户在后台**手工维护**；批量导入、自动采集可在实施阶段扩展，**本期默认手工登记为主**。  
- 每条记录包含：展示用元数据（标题、主题、简介）及**知识内容**（非结构化文档附件，如 PDF、Office、Markdown 等）。

### 2.2 知识主题（固定五类，单选）

| 主题名称 | 说明 |
| --- | --- |
| **饲养管理** | 饲喂、营养、日常管理等 |
| **疫病管理** | 防疫、诊疗、生物安全等 |
| **设备选型** | 养殖与牧业相关设备 |
| **牧场设计** | 场区规划、设施布局等 |
| **政策解读** | 产业政策、法规要点等 |

用户**不可**自定义第六类或修改上述主题含义（扩展须单独立项）。列表筛选与表单均为**单选**。

### 2.3 入库状态（与外部知识库的关系）

用**入库状态**表示该条业务记录是否已在外部知识库中建立有效对应条目（界面可与「知识库同步状态」同义展示）。

| 状态 | 含义 | 外部知识库 | 后台维护（摘要） |
| --- | --- | --- | --- |
| **未入库** | 仅保存在业务后台 | 无对应有效条目（或已移出） | 可查看、**编辑**、**删除**、**同步知识库** |
| **已入库** | 已写入外部知识库 | 存在对应条目 | **仅可查看**、**移出知识库**；**不可编辑、不可删除** |

**允许的状态迁移：**

```mermaid
stateDiagram-v2
    [*] --> 未入库: 新增保存
    未入库 --> 已入库: 同步知识库
    已入库 --> 未入库: 移出知识库
    未入库 --> [*]: 删除
```

> **已入库**期间：任何修改、删除操作均应拒绝，并提示须先「移出知识库」后再维护。

### 2.4 删除与可见性

- 采用**逻辑删除**：删除后默认不在列表展示，数据保留供审计；**本期无**回收站。  
- **已入库**须先**移出知识库**变为 **未入库** 后，方可删除。  
- 删除 **未入库** 记录时，若外部知识库侧本无对应条目，则仅清理本地及附件；若对接要求仍发删除通知，以实现为准。  
- **已入库** 删除（拒绝）：不得绕过移出直接删本地。

### 2.5 列表筛选

| 筛选项 | 规则 |
| --- | --- |
| 关键词 | 选填；对**知识标题**、**知识简介** **模糊**匹配（二者为 **或** 关系，命中其一即可） |
| 知识主题 | 选填；**精确**匹配；空则不过滤 |
| 入库状态 | 选填；**未入库 / 已入库** 精确筛选；空则不过滤 |

---

## 3. 功能范围

### 3.1 本期实现

| 能力 | 说明 |
| --- | --- |
| 分页列表 | 关键词、主题、入库状态筛选；**§5.1** |
| 新增 | 保存为 **未入库**；**§5.2** |
| 修改 | 仅 **未入库**；**§5.3** |
| 查看 | 全状态只读；**§5.4** |
| 逻辑删除 | 仅 **未入库**；**§5.5** |
| 同步知识库 | 将条目**首次**写入外部知识库；**§5.6** |
| 移出知识库 | 从外部知识库移除对应条目；**§5.7** |
| 知识内容附件 | 单文件上传；**§5.2** |

### 3.2 本期不实现

- **发布 / 下架**（本模块无对外发布态，与养殖标准、科技资源等模块不同）  
- 知识内容在线预览（PDF 内嵌预览等，可后续迭代）  
- 批量导入导出、知识主题自定义  
- 版本历史、多人协同编辑、知识条目审批流  

---

## 4. 业务流程

### 4.1 模块总览

```mermaid
flowchart TD
    A[进入模块] --> B[列表查询]
    B --> C{操作}
    C --> D[新增 → 未入库]
    C --> E[查看]
    C --> F[编辑]
    C --> G[删除]
    C --> H[同步知识库]
    C --> I[移出知识库]
    F --> J{未入库?}
    J -->|否| K[拒绝]
    J -->|是| L[保存]
    G --> M{未入库?}
    M -->|否| N[拒绝]
    M -->|是| O[逻辑删除]
    H --> P[已入库]
    I --> Q[未入库]
```

### 4.2 典型运营顺序

1. **新增**知识条目并上传正文附件 → **未入库**。  
2. 校对无误后 **同步知识库** → **已入库**（可供下游问答/检索使用）。  
3. 内容需大改 → **移出知识库** → **编辑** → 再次 **同步知识库**。  
4. 废弃条目 → 若 **已入库** 先 **移出** → **删除**。  

### 4.3 与外部知识库的一致性原则

| 场景 | 业务侧 | 外部知识库 |
| --- | --- | --- |
| 新增保存 | 落库 **未入库** | 不自动写入 |
| 未入库下修改保存 | 仅更新本地 | 不自动写入 |
| 同步成功 | **已入库** | 创建/挂载对应条目 |
| 已入库 | 不可改本地业务字段 | 保持条目存在 |
| 移出成功 | **未入库** | 删除或下线对应条目 |
| 未入库删除 | 逻辑删除 + 清理附件 | 无条目或发删除通知（以实现为准） |

> **本期不做「已入库后保存即自动推库」**：与养殖标准不同；已入库后须先移出再改。

---

## 5. 详细功能需求

### 5.1 列表与查询

| 项 | 规则 |
| --- | --- |
| 分页 | 默认每页 **20** 条 |
| 排序 | 默认 **创建时间倒序** |
| 展示列 | 知识标题、知识主题、知识简介（可截断）、知识文件（名称或下载入口）、**入库状态**、操作 |
| 工具栏 | **搜索**、**重置**、**新增** |
| 操作列 | 见 **§6**；各状态均宜有 **查看** |

---

### 5.2 新增

| 字段 | 规则 |
| --- | --- |
| 知识标题 | **必填**；**1～20** 字 |
| 知识主题 | **必填**；**单选**；取值 **§2.2** 五类之一 |
| 知识简介 | **选填**；**≤50** 字 |
| 知识内容 | **必填**；**单文件**上传；允许后缀：**pdf、md、doc、docx、xls、xlsx、pptx**；**≤30MB** |
| 初始状态 | **未入库** |

**通用校验：**

- 文本按**字符**计；提交前 trim；空字符串视为未填。  
- 后缀、大小在服务端二次校验；超限或非法格式返回明确提示。  
- 须先完成上传再提交保存（业务表存访问地址与存储路径及**原始文件名**展示，具体落库方式由实现确定）。

---

### 5.3 修改

| 项 | 规则 |
| --- | --- |
| 允许 | **未入库** |
| 拒绝 | **已入库** → 「已入库条目请先移出知识库后再编辑」 |
| 范围 | 标题、主题、简介、知识内容附件均可改；校验同 **§5.2** |
| 保存后 | 仍为 **未入库**；**不**自动同步外部知识库 |

替换知识内容附件时，旧物理文件宜按平台文件管理惯例清理。

---

### 5.4 查看

- **任意入库状态**可查看。  
- 展示：知识标题、知识主题、知识简介、知识内容（下载或预览入口，若有）、正文**原始文件名**、入库状态、创建/更新等审计信息。  
- **已入库**：只读，无编辑入口；**未入库**：具备权限时可「编辑」。

---

### 5.5 逻辑删除

| 项 | 规则 |
| --- | --- |
| 允许 | **未入库** |
| 拒绝 | **已入库** → 「已入库条目请先移出知识库后再删除」 |
| 方式 | **本期单条**；二次确认；确认文案展示知识标题 |
| 副作用 | 逻辑删除标记；删除知识内容物理文件；按对接约定**通知外部知识库删除**（若库侧本无条目则跳过或幂等处理） |

---

### 5.6 同步知识库

| 项 | 规则 |
| --- | --- |
| 前置 | **未入库**；标题、主题、知识内容等校验通过 |
| 操作 | 用户点击「同步知识库」；宜二次确认 |
| 结果 | 外部知识库创建或挂载对应条目；业务侧变为 **已入库** |
| 失败 | 返回明确原因（网络、鉴权、知识库业务错误等）；**不**记为已入库，可重试 |
| 重复 | **已入库** 再次点击应拒绝：「该条目已入库」 |

同步字段范围（与对接约定一致，通常含）：标题、主题、简介、正文附件及元数据。

---

### 5.7 移出知识库

| 项 | 规则 |
| --- | --- |
| 前置 | **已入库** |
| 拒绝 | **未入库** → 「仅已入库条目可移出知识库」 |
| 操作 | 用户点击「移出知识库」；宜二次确认 |
| 结果 | 外部知识库删除或下线对应条目；业务侧变为 **未入库** |
| 失败 | 返回明确原因；**不**改变入库状态，可重试 |
| 移出后 | 可 **编辑**、**删除** 或再次 **同步知识库** |

---

## 6. 操作与权限矩阵

| 操作 | 未入库 | 已入库 |
| --- | --- | --- |
| 查看 | ✓ | ✓ |
| 编辑 | ✓ | — |
| 删除 | ✓ | — |
| 同步知识库 | ✓ | — |
| 移出知识库 | — | ✓ |

列表级 **新增**、**搜索**、**重置** 需对应权限。无权限时按钮不展示或禁用。

---

## 7. 与下游衔接

| 下游 | 本模块提供 |
| --- | --- |
| 外部知识库 / 智能问答 | **已入库** 条目的正文与元数据，供索引、检索、问答引用 |
| 运营审计 | 逻辑删除保留记录；同步/移出/删除宜记操作日志 |

---

## 8. 提示约定（示例）

| 场景 | 示例文案 |
| --- | --- |
| 必填/超长 | 「请填写【知识标题】」「【知识简介】不能超过 50 字」 |
| 附件 | 「请上传知识内容」「仅支持 pdf/md/doc/docx/xls/xlsx/pptx，且不超过 30MB」 |
| 入库态 | 「已入库条目请先移出知识库后再操作」「该条目已入库」「仅已入库条目可移出知识库」 |
| 同步/移出失败 | 「同步知识库失败：{原因}」「移出知识库失败：{原因}」 |

---

## 9. 非功能建议

- 按按钮粒度控制操作权限。  
- 同步知识库、移出知识库、删除记审计日志。  
- 列表在常规数据量下分页响应可接受。  
- 用语与原型、外部知识库对接文档一致；界面支持 i18n。

---

## 10. 修订记录

| 版本 | 说明 |
| --- | --- |
| 2.0 | 依据草稿与原型重写：入库状态机、操作矩阵、流程图；明确无发布/下架；未入库可编删、已入库仅查看与移出；剔除技术栈与接口表述 |
| 2.1 | **2026-05-20**：知识内容正文白名单调整为 `pdf`、`md`、`doc`、`docx`、`xls`、`xlsx`、`pptx`（不含 `ppt`）；与 `LivestockKnowledgeRules` 一致；前端 `contentFileExts` 本次不改 |