# 饲喂标准管理 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 饲喂标准管理 |
| 目标 | 对饲喂标准进行增删改查、附件与封面管理，并与知识库同步、发布生命周期衔接 |
| 关联系统 | 业务后台、知识库 |
| 流程修订依据 | **业务状态与生命周期**与《养殖标准管理功能需求》对齐（上架维度 × 知识库同步维度；下架回流、删除与知识库通知等语义一致） |

本文档仅描述本模块**饲喂标准管理**的功能需求与业务规则，不涉及库表结构、接口路径与字段命名等实现设计；与其它业务模块文档相互独立。

---

## 2. 术语与状态

### 2.1 标准类型（资讯类别编码，单选）

标准类型持久化与接口传参均为 **资讯类别编码**（`varchar`）。可选范围由资讯类别子节点维护，本模块取 `parentCode=001`、`categoryType=2`：

| 编码 | 名称（示例） |
| --- | --- |
| `001005` | 饲料配方 |
| `001006` | 牦牛投喂 |

新增/修改保存时编码须在上述有效集合内；列表筛选为 **编码精确匹配**。

### 2.2 业务状态（与养殖标准一致的两维模型）

业务状态拆成 **两个正交维度**，避免出现单一枚举无法表达的非法组合；具体如何在系统中持久化由实现阶段决定，本文档只约束**语义与合法组合**。

#### 2.2.1 上架状态（互斥，单值）

| 取值 | 含义概要 |
| --- | --- |
| **未发布** | 未对外发布阶段：含新建草稿、**未同步下编辑**、**已从已发布下架回流**等；**仅未发布且未同步**时可编辑；同步 / 移出 / 发布 / 删除规则见第 4～5 章 |
| **已发布** | 对外可见或可检索（与产品定义一致）；**不允许修改**；不可直接删除，须先执行 **下架** |

**下架：** 执行「下架」后，业务侧**不将本条单独持久化为「已下架」终态**。下架完成后，上架状态回到 **未发布**，知识库同步状态为 **已同步**。  
**产品定论（与养殖标准一致）：** 下架后知识库内**仍保留**与本标准对应的条目副本（条目不删除，可与「对外发布 / 检索可见」解耦），业务侧稳态为 **未发布 + 已同步**，允许**直接再次发布**；若需改内容须先 **移出知识库** → 未同步下编辑 → 再同步，**无须新建**一条饲喂标准。

> 若历史版本或数据字典曾使用「已下架」枚举仅作兼容或审计展示，须在实现说明中与「下架回流 = 未发布 + 已同步」的关系写清，避免与当前流程冲突。

#### 2.2.2 知识库同步状态（与上架状态正交，单值）

| 取值 | 含义概要 |
| --- | --- |
| **未同步** | 知识库中无对应有效条目（或已移出）；在满足矩阵规则下可执行手动「同步知识库」（仅当上架状态为 **未发布**） |
| **已同步** | 知识库侧**已有**与本条对应的条目；业务侧**禁止编辑**（须先移出后再改）；**未发布**时可 **发布**、**移出知识库** |

**已同步状态下若要改内容：** 须 **移出知识库** → **未同步** 下完成修改 → 再 **同步知识库** → **已同步**。

「移出知识库」见 **4.7**：执行后须将本维度置为 **未同步**。

#### 2.2.3 合法组合（上架 × 知识库）

以下组合**允许作为稳态存在**；其余组合（例如 **已发布 + 未同步**）视为 **非法**，不得在业务流程中出现。

| 上架状态 | 知识库同步 | 说明 |
| --- | --- | --- |
| 未发布 | 未同步 | 初始或移出后；可手动同步、可编辑；**未同步**条件下允许删除（见 **4.4**） |
| 未发布 | 已同步 | 已入库（含手动同步、或已发布下架回流）；**不可编辑**、可发布、可移出；删除规则见 **4.4** |
| 已发布 | 已同步 | 发布的前提为已同步（**4.8**）；对外展示中，不可改、不可删，仅可下架 |

**下架 vs 移出：** 下架**不删除**知识库条目，库内保留条目副本，业务 **`知识库同步` 仍为已同步**；若需从库内**彻底清除**条目，须在回到 **未发布 + 已同步** 后主动执行 **移出知识库**（**4.7**）。

---

## 3. 功能范围

- 饲喂标准的新增、修改、删除、分页列表查询、详情查看  
- 标准正文附件（非结构化文档）与封面图的上传、替换、展示及删除时的存储联动清理  
- 与知识库的同步、移出  
- 发布、下架及与知识库的一致性处理  
- 面向调用方或前端的错误信息形式约定（见第 6 章，不涉及接口设计细节）

### 3.1 业务流程概览（与养殖标准一致）

下列顺序描述**典型闭环**，便于评审与培训；具体操作禁忌以 **第 5 章矩阵** 为准。

1. **新建**：录入必填项并上传正文（及可选封面）→ 初始为 **未发布 + 未同步**。  
2. **首次入库**：在 **未发布 + 未同步** 下执行「同步知识库」→ **未发布 + 已同步**。  
3. **迭代编辑**：仅在 **未发布 + 未同步** 下允许修改；**已同步**须先移出（步骤 7）再编辑。**未同步**保存仅更新业务侧，仍依赖步骤 2。  
4. **发布**：仅在 **未发布 + 已同步** 下允许 → **已发布 + 已同步**。  
5. **下架**：仅在 **已发布** 下允许 → 回到 **未发布 + 已同步**（库内保留条目，非移出）。  
6. **再发布 / 纠错再入库**：已同步可直接重复步骤 4；若需改内容则 **移出 → 编辑 → 同步 → 发布**（**无须新建**记录）。  
7. **彻底移出知识库**：在 **未发布 + 已同步** 下主动「移出」→ **未发布 + 未同步**（与下架语义不同）。  
8. **删除**：仅在 **未同步** 下允许直接删除（含删文件与通知知识库删除）；若当前为 **未发布 + 已同步**，须先执行步骤 7 或在删除流程中 **原子联动** 完成库侧清理后再删（见 **4.4**）。

---

## 4. 详细功能需求

### 4.1 新增饲喂标准

| 字段 | 规则 |
| --- | --- |
| 标准名称 | 必填；长度 1～20 个字符（字符计数规则与项目全局一致，如按 Unicode 字符数或字节长度须单独约定） |
| 标准类型 | 必填；单选，取值须为第 **2.1** 节所列资讯类别编码之一 |
| 标准简介 | **选填**；若有内容，长度不超过 **50 字**（字数口径与项目全局一致，如是否含标点、中英文计数方式） |
| 标准内容 | **必填**；通过**单个**附件上传；允许后缀：`pdf`、`md`、`doc`、`docx`、`xls`、`xlsx`、`pptx`；单文件 ≤ **30 MB** |
| 封面 | **选填**；通过**单个**图片上传；允许后缀：`jpg`、`jpeg`、`png`（若产品要求支持 `webp` 等可追加）；单文件 ≤ **10 MB** |

**必填字段汇总：** 标准名称、标准类型、标准内容。

**校验：**  
须校验文件类型（如后缀与白名单 / MIME 策略以项目安全规范为准）一致，大小超限给出**可区分**的错误分类提示；若业务要求标准名称在适用范围（如租户 / 组织）内唯一，应在评审时单独约定并写入本节。

**初始状态：** 新建成功后，上架状态为 **未发布**，知识库同步状态为 **未同步**（除非产品与养殖标准另有统一的初始化规则）。

---

### 4.2 查询饲喂标准列表

- **关键字：** 对「标准名称」或「标准简介」**模糊**匹配（二者为 OR 关系）。  
- **标准类型：** **精确**匹配筛选。  
- **分页：** 支持分页；默认每页 **20** 条，首页为第一页；单页条数上限与全局列表规范一致（若有，例如上限 100）。  
- **排序：** 默认按 **创建时间倒序**（最新在前）；次要排序键若需约定（如相同创建时间按 `id` 倒序）由项目列表规范对齐。

列表宜展示与运维相关的状态信息（如上架状态、知识库同步状态），便于用户理解可执行操作。

---

### 4.3 修改饲喂标准

- **状态约束：** **仅未发布且未同步** 允许修改。**已发布**或 **已同步** 不允许修改（界面只读或无保存入口；须返回明确业务原因，如「知识库已同步状态不允许修改」）。  
- **可修改项：** 标准名称、标准类型、标准简介、标准内容（附件）、封面。  
- **保存约束：** 标准名称、标准类型、标准内容始终保持必填；标准简介仍为选填。  
- **与知识库一致性：** **未同步**状态下保存仅更新业务侧，不自动写入知识库，仍依赖用户触发 **4.6**。**已同步**须先 **移出知识库**（**4.7**）后再编辑。

---

### 4.4 删除饲喂标准

- 删除本条业务数据时，须**同步删除**关联存储中的标准内容文件与封面文件；并**通知知识库删除**对应饲喂标准条目（避免孤儿数据）。  
- **允许删除：** **未同步**的饲喂标准允许删除。  
- **不允许删除：** **已发布**；须先下架回到 **未发布** 后再按本条及「未发布且已同步」规则处理。  
- **未发布且已同步：** **不得**在知识库仍保留有效条目的情况下单独删除业务侧；须先 **移出知识库**（**4.7**）变为 **未同步** 后再删，或在删除流程中**原子联动**完成库侧条目删除后再删本地数据与文件。

---

### 4.5 查看饲喂标准详情

- **展示：** 标准名称、标准类型、标准简介、标准内容（附件下载或预览入口）、正文附件原始文件名、封面。  
- **已发布**或 **已同步**：详情只读，不提供保存类编辑。  
- **未发布且未同步**：在具备权限时可进入编辑流程。  
- 在线预览能力（如 PDF、图片）可作为迭代项单独列出。

---

### 4.6 同步至知识库（手动）

- **适用：** 饲喂标准为 **未发布** 且 **未同步** 时，用户可触发「同步知识库」，将当前标准**首次**写入知识库。**已发布**记录不适用本入口。  
- **结果：** 手动同步成功后，知识库同步状态为 **已同步**，为发布做准备；此后若需改内容须先 **移出知识库**（**4.7**）。  
- **失败：** 须支持用户根据明确原因重试。

---

### 4.7 移出知识库

- **语义：** 主动删除或下线知识库侧对应条目；与「下架」（**4.8**）不同——**下架不删除库内副本**。  
- **前置：** 仅 **未发布** 且 **已同步** 时可提供「移出知识库」。**已发布**不提供；须先下架回到 **未发布 + 已同步** 后，由用户再按需点击「移出」（下架不会自动移出）。  
- **结果：** 库侧条目删除或下线后，业务侧知识库同步状态须为 **未同步**。

---

### 4.8 发布与下架

- **发布**  
  - **仅当**饲喂标准 **已同步知识库** 且上架状态为 **未发布** 时允许发布。  
  - 发布后上架状态为 **已发布**。  

- **下架**  
  - **已发布**的饲喂标准可下架。  
  - 下架须完成与知识库的一致性处理：**结束对外发布 / 对外检索可见**（具体开关语义以对接文档为准），但**不删除**知识库内与本标准对应的条目——库内**保留可编辑副本**。  
  - **下架完成后的业务状态：** 上架状态 **未发布**，知识库同步状态 **已同步**；允许**直接再次发布**；若需改内容须先 **移出知识库** 再编辑、同步，**无须新建**。  
  - 若需彻底清除库侧条目，须在 **未发布 + 已同步** 下主动执行 **移出知识库**，而非由下架子流程替代。

---

## 5. 状态与操作矩阵（汇总）

下架完成后并入 **未发布且已同步** 行理解。

| 当前状态（上架 × 知识库） | 修改 | 同步知识库 | 移出知识库 | 发布 | 下架 | 删除 |
| --- | --- | --- | --- | --- | --- | --- |
| 未发布且未同步 | ✓ | ✓ | — | — | — | ✓ |
| 未发布且已同步 | ✗ | — | ✓ | ✓ | — | ✗（须先移出变为未同步，或删除流程联动移出/删库） |
| 已发布且已同步 | ✗ | — | — | — | ✓（回流为未发布+已同步） | ✗ |

**补充：** 从「已发布」下架后，记录进入 **未发布且已同步**，操作权限按上表第二行执行。

---

## 6. 错误与提示约定（不涉及接口设计）

- 业务与系统错误对外呈现时，宜采用统一结构（如 `code`、`msg`、`data`），与项目全局规范一致。  
- 文件类错误（格式不支持、大小超限、上传失败等）宜有可区分类型，便于前端提示与重试。

---

## 7. 非功能需求（建议）

| 类别 | 建议 |
| --- | --- |
| 权限 | 菜单与按钮级权限：新增、编辑、删除、发布、下架、同步、移出等是否分角色 |
| 审计 | 关键操作记录操作日志（发布、下架、手动同步、移出、删除） |
| 安全 | 上传文件类型校验、存储访问控制、下载鉴权 |
| 性能 | 列表避免低效查询模式；大附件若后续有需要再扩展直传或分片 |

---

## 8. 修订说明（相对原饲喂标准草稿）

- 将业务状态明确为与养殖标准一致的 **上架状态 × 知识库同步状态**，并给出合法组合与非法组合约束。  
- 理顺 **同步 / 发布 / 下架 / 移出 / 删除** 的先后顺序与互斥关系，并以矩阵汇总；**已同步禁止编辑**（与休药期/药物禁配对齐）。  
- 修正原稿编号重复（两条「10.」）；标准简介与养殖标准对齐为 **选填**，填写时仍受 50 字上限约束；**封面**明确为 **选填**。  
- 删除、下架、移出与知识库通知的语义与养殖标准章节对齐，避免「下架即删库」与「移出」混淆。  
- 去掉库表、接口路径等实现层描述；技术栈仅在项目层面另行约束时可引用全局规范，本文不展开。  
- 增补 **§3.1 业务流程概览**；字段口径与养殖标准正文对齐；补充「已下架」兼容说明脚注；**已同步禁止编辑**与休药期/药物禁配对齐。  
- **标准名称**长度由 **3～20** 调整为 **1～20** 个字符，与 `饲喂标准管理功能需求-草稿.md` 及养殖/疫病/生长出栏等标准模块对齐。
- **标准内容**正文附件白名单调整为：`pdf`、`md`、`doc`、`docx`、`xls`、`xlsx`、`pptx`（不再支持旧版 `ppt`）；与 `FeedingStandardRules` 及通用上传白名单（含 `md`）一致；**前端上传校验数组本次不调整**，以服务端校验为准。
