# 养殖标准管理 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 养殖标准管理 |
| 目标 | 对养殖标准进行增删改查、附件与封面管理，并与知识库同步、发布生命周期衔接 |
| 关联系统 | 业务后台（RuoYi）、知识库 |
| 流程修订依据 | 同目录 `养殖标准管理功能需求-草稿.md`：下架回流、删除与知识库通知等 |

---

## 2. 术语与状态

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

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

| 编码 | 名称（示例） |
| --- | --- |
| `001001` | 繁育作业 |
| `001002` | 饲养工作 |
| `001003` | 免疫程序 |
| `001004` | 环境调控 |

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

### 2.2 业务状态（便于实现状态机与权限）

业务状态宜拆成 **两个正交维度**（可用两个字段分别持久化，字段名与现有表结构对齐即可），避免出现「单枚举无法表达」的组合。

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

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

**下架与「已下架」：** 执行「下架」后，业务侧**不再将本条持久化为单独的「已下架」终态**（与历史「下架即终态」方案区分）。下架完成后，上架状态回到 **未发布**，知识库同步状态为 **已同步**（见 **4.8**）。**产品定论：** 下架后知识库内**仍保留**与本标准对应的**可编辑副本**（条目不删除，可与「对外发布/检索可见」解耦），故业务侧维持 **未发布 + 已同步**，允许再次修改并重新发布，**无须新建**一条养殖标准。

> 若库表仍保留「已下架」枚举值仅作兼容或审计展示，应在实现与数据字典中注明其与上述流程的关系，避免与「下架回流 = 未发布 + 已同步」冲突。

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

| 取值 | 含义概要 |
| --- | --- |
| **未同步** | 知识库中无对应有效条目（或已移出）；可执行手动「同步知识库」（仅当上架状态为 **未发布** 时，见 **4.6**） |
| **已同步** | 知识库中存在与本标准对应的条目；修改保存时可按 **4.3** 自动更新知识库（仅当上架状态仍为 **未发布** 时） |

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

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

以下组合**允许作为稳态存在**；其余组合（如 **已发布 + 未同步**）视为 **非法**，不得在数据层出现，接口须校验。

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

**说明：** 按 **4.8**，下架完成后目标稳态为 **未发布 + 已同步**：库内保留可编辑副本，**不再**单独保留「已下架 + 未同步」作为业务必经终态。与「移出知识库」（**4.7**，删除/下线库侧条目并置 **未同步**）区分实现。

**操作权限与按钮矩阵仍以第 5 节为准**；本节用于库表设计与状态校验。

---

## 3. 功能范围

- 养殖标准的新增、修改、删除、分页列表查询、详情查看  
- 标准正文附件（非结构化文档）与封面图的上传、替换、展示及删除时联动清理存储  
- 与知识库的同步、移出  
- 发布、下架及与知识库的一致性处理  
- 接口异常返回统一结构  

---

## 4. 详细功能需求

### 4.1 新增养殖标准

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

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

**校验：**  
服务端需校验 MIME/后缀与白名单一致，大小超限返回明确错误码与提示；同名策略（全局唯一或租户内唯一）若业务需要应在本节补充。

---

### 4.2 查询养殖标准列表

- **关键字：** 对「标准名称」或「标准简介」**模糊**匹配（OR 关系）。  
- **标准类型：** **精确**匹配筛选。  
- **分页：** 支持分页；默认 **每页 20 条**（`pageSize=20`），默认首页 `pageNum=1`；单页条数上限若需限制可与 RuoYi 列表规范对齐（例如上限 100）。  
- **排序：** 默认按 **创建时间倒序**（最新创建的在前）；次要排序键若需约定（如 `id` 倒序）可在接口文档中写明。

---

### 4.3 修改养殖标准

- **状态约束：** **仅未发布**（含未同步、已同步，**含已从已发布下架回流后的未发布**）允许修改。**已发布**状态下**不允许修改**（列表/详情不提供编辑入口或仅为只读；调用修改类接口须返回明确业务错误）。  
- 可修改项：**标准名称、标准类型、标准简介、标准内容（附件）、封面**。  
- **保存约束：** **标准名称、标准类型、标准内容** 始终保持必填（提交时不得为空、不得删除附件导致无正文）；**标准简介**仍为选填。  
- **与知识库一致性（已同步自动推送）：** 当标准当前为 **已同步至知识库** 且仍为 **未发布**（可编辑流程，**含下架回流场景**）时，用户修改并**保存成功**后，系统须 **自动** 将变更推送至知识库（更新知识库侧已有条目，字段范围与手动同步一致：如名称、类型、简介、正文附件、封面等以对接约定为准）。**未同步**状态下修改保存仅更新本地，不自动写入知识库，仍依赖用户触发 **4.6** 的「同步知识库」。  
- **失败处理：** 自动推送失败时返回明确 `code`/`msg`；本地库与知识库是否同事务回滚建议在实现前约定（推荐：**保存与推送一致**，推送失败则本次保存视为失败，避免两侧不一致）。

---

### 4.4 删除养殖标准

- 删除数据库记录时，**同步删除**关联存储中的标准内容文件与封面文件（对象存储或本地路径需与现有框架一致）；并**通知知识库删除**对应养殖标准条目（与对接文档一致，避免孤儿数据）。  
- **允许删除（与草稿对齐）：** **未同步**的养殖标准允许删除（含「未发布 + 未同步」等情形）。  
- **不允许删除：** **已发布**的养殖标准；须先执行「下架」（见 **4.8**），回到 **未发布** 后再按本条及「未发布且已同步」规则处理。  
- **未发布且已同步：** **不得在无知识库处理的前提下直接删除**；须先 **移出知识库**（见 **4.7**）使标准变为未同步后，再执行删除；或在删除接口内 **原子联动移出/删除知识库条目** 后删除本地记录与文件，避免知识库孤儿条目。

---

### 4.5 查看养殖标准详情

- 展示：**标准名称、标准类型、标准简介、标准内容（附件下载或预览入口）、正文附件原始名称（与上传文件名一致，便于识别）、封面**。**已发布**场景下详情为 **只读**（无保存类编辑）；**未发布**（含下架回流）在具备编辑权限时可进入编辑流程。  
- 预览能力（仅 PDF、图片在线预览等）若需要，可作为迭代项单列。

---

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

- **适用：** 养殖标准为**未发布**且**未同步**（或等价状态）时，由用户点击「同步知识库」，将当前标准**首次**写入知识库（或对接语义下的首次挂载）。**已发布**记录不适用本手动入口（须先下架回到未发布后再视同步维度操作）。  
- **已同步后的变更：** 已通过同步的标准，后续字段变更不在此按钮重复完成全量流程，而在 **4.3** 保存修改时 **自动** 更新知识库（见上文「已同步自动推送」）。  
- **结果：** 手动同步成功后，标准进入「已同步」状态（或等价标记），为后续发布做准备。  
- **失败：** 网络或知识库返回错误时，`code`、`msg` 明确可区分，支持用户重试。

---

### 4.7 移出知识库

- **语义区分：** 「移出知识库」为**主动**删除或下线知识库侧对应条目；与「下架」（**4.8**）不同——**下架不删除库内副本**，库内保留可编辑条目，业务侧仍为 **已同步**。  
- **前置：** 仅 **未发布** 且 **已同步** 时可提供「移出知识库」（与 **第 5 节**矩阵一致）。**已发布**记录不提供「移出」入口；须先 **下架** 回到 **未发布 + 已同步** 后，用户再按需点击「移出知识库」（并非下架动作自动移出）。  
- **结果：** 知识库侧对应条目删除或下线后，业务侧「知识库同步」维度须置为 **未同步**；合法组合与后续操作见 **第 5 节**矩阵。

---

### 4.8 发布与下架

- **发布：**  
  - **仅当**养殖标准**已同步知识库**且上架状态为 **未发布**时，允许执行「发布」（与草稿「只有已同步才能发布」一致）。  
  - 发布后上架状态为 **已发布**。  
- **下架：**  
  - **已发布**的养殖标准可「下架」。  
  - 下架时须完成与知识库的一致性处理：**结束对外发布/对外检索可见等**，但**不删除**知识库内与本标准对应的条目——库内**保留可编辑副本**，以便后续修改与再次发布（具体接口语义如「可见性开关 / 发布状态」以《技术方案》与对接文档为准）。  
  - **下架完成后的业务状态：** 上架状态置为 **未发布**，知识库同步状态为 **已同步**（与「库内仍保留副本」一致）；允许用户 **再次修改** 标准内容，并可在满足「已同步」前提下 **再次发布**，**无须新建**养殖标准。  
  - 若需从库内**彻底清除**条目，须由用户在回到 **未发布 + 已同步** 后主动执行 **移出知识库**（**4.7**），而非由下架子流程替代。

---

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

以下便于开发与测试用例编写（具体 boolean 以实现为准）。**已移除「已下架」作为独立矩阵行**：下架完成后回到 **未发布且已同步**（**库内保留可编辑副本**），与第二行合并理解。

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

**补充：** 从「已发布」下架后，记录进入 **未发布且已同步**，操作权限按上表第二行执行（可改、可发布、可移出；删除规则同 **4.4**）。

---

## 6. 接口与异常

- **异常返回：** 统一结构：`code`、`msg`、`data`（与现有 RuoYi / 全局规范一致）。  
- **文件相关错误：** 单独错误码或 `msg` 区分格式不支持、大小超限、上传失败等。

---

## 7. 技术栈约束

- **后端框架：** RuoYi **v3.9.2**，分支 **springboot2**  
- **数据库：** MySQL **5.7.39**  

---

## 8. 非功能需求（建议补充）

| 类别 | 建议 |
| --- | --- |
| 权限 | 菜单与按钮级权限：新增、编辑、删除、发布、下架、同步、移出等是否分角色 |
| 审计 | 关键操作记操作日志（发布、下架、手动同步、修改触发的自动同步、删除） |
| 安全 | 上传文件类型校验、存储路径不可预测、下载鉴权 |
| 性能 | 列表接口避免 N+1；大附件走直传或分片若后续有需要再扩展 |

---

## 9. 修订说明（相对原版）

- **2.2** 将业务状态拆为 **上架状态** 与 **知识库同步状态** 两维，并给出 **合法组合表**；非法组合（如已发布+未同步）禁止落库。  
- 拆分章节：术语、字段校验、列表、生命周期（同步 / 发布 / 下架 / 删除）分层描述，便于评审与测试用例映射。  
- 修正原版第 9 条末尾多余字符。  
- 对「删除」「发布」「下架与移出知识库」的关系做了矩阵汇总；**允许删除**与 `养殖标准管理功能需求-草稿.md` 对齐：**未同步**允许删除；**未发布且已同步**须先移出或删除联动知识库处理。  
- 补充分页、排序等实现要点；**仅已发布**不允许修改；**下架后回流为「未发布 + 已同步」**，可再次修改与发布（**替代**原「已下架终态、须新建重来」描述）。  
- **下架 vs 移出（产品定论）：** 下架**不删除**知识库条目，库内**保留可编辑副本**，故业务 **`kb_sync_status` 仍为已同步**；彻底清除库侧条目须用户主动 **移出知识库**（非下架自动完成）。  
- **删除**补充：**通知知识库删除**对应条目（与草稿一致）。  
- **标准简介**明确为选填；填写时仍受 50 字上限约束。  
- **标准名称、标准类型、标准内容**明确为必填（新增与修改保存均适用）。  
- 列表分页默认 **每页 20 条**；列表默认 **创建时间倒序**。  
- **已同步**标准在 **修改保存** 时 **自动更新知识库**；未同步标准仍用手动「同步知识库」。  
- **标准名称**长度由 **3～20** 调整为 **1～20** 个字符，与 `养殖标准管理功能需求-草稿.md` 及饲喂/疫病/生长出栏等标准模块字段规则对齐。
