西藏巴青项目

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

1. 文档说明

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

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

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

2. 术语与业务对象

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

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

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

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

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

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

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

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

允许的状态迁移：

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 模块总览

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 典型运营顺序

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

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` 本次不改

综合牧业知识库管理功能需求.md 11KB Vēsture Neapstrādāts