# 生长与出栏标准管理 — 功能需求 ## 1. 文档说明 | 项 | 说明 | | --- | --- | | 模块名称 | 生长与出栏标准管理 | | 目标 | 对生长与出栏标准进行增删改查、正文附件与封面管理，并与知识库同步、发布生命周期衔接 | | 关联系统 | 业务后台、知识库 | | 流程修订依据 | 同目录 `生长与出栏标准管理功能需求-草稿.md`；《**养殖标准管理功能需求**》中业务状态、生命周期、下架回流、删除与知识库通知等语义（本模块与之对齐，领域文案按生长与出栏调整） | 本文档仅描述**功能需求与业务规则**，不涉及库表结构、接口路径、请求体字段命名及技术栈选型。 --- ## 2. 术语与状态 ### 2.1 标准类型（资讯类别编码，单选） 标准类型持久化与接口传参均为 **资讯类别编码**（`varchar`）。可选范围由资讯类别子节点维护，本模块取 `parentCode=001`、`categoryType=4`： | 编码 | 名称（示例） | | --- | --- | | `001011` | 牦牛生长 | | `001012` | 牦牛出栏 | 新增/修改保存时编码须在上述有效集合内；列表筛选为 **编码精确匹配**。 ### 2.2 业务状态（与养殖标准一致的两维模型） 业务状态拆成 **上架状态** 与 **知识库同步状态** 两个**正交维度**，避免出现单一枚举无法表达的非法组合；两维度在系统中如何记录由实现决定，本文只约定**语义、合法组合与操作后果**。 #### 2.2.1 上架状态（互斥，单值） | 取值 | 含义概要 | | --- | --- | | **未发布** | 未对外发布阶段：含新建草稿、**未同步下编辑**、**已从已发布下架回流**等；**仅未发布且未同步**时可编辑；同步 / 移出 / 发布 / 删除规则见 **第 4～5 节** | | **已发布** | 对外可见或可检索（与产品定义一致）；**不允许修改**；不可直接删除，须先执行 **下架** | **下架与「已下架」稳态：** 执行「下架」后，业务侧**不将本条单独固化为「已下架」业务终态**。下架完成后，上架状态为 **未发布**，知识库同步状态为 **已同步**（见 **4.8**）。**产品定论（与养殖标准一致）：** 下架后知识库内**仍保留**与本标准对应的**可编辑副本**（条目不删除，可与「对外发布 / 检索可见」解耦），业务侧稳态为 **未发布 + 已同步**，允许**直接再次发布**；若需改内容须先 **移出知识库** → 未同步下编辑 → 再同步，**无须新建**一条生长与出栏标准。 > 若历史版本或展示层曾出现「已下架」表述，须在说明中与「下架回流 = 未发布 + 已同步」的关系写清，避免与当前流程冲突。 #### 2.2.2 知识库同步状态（与上架状态正交，单值） | 取值 | 含义概要 | | --- | --- | | **未同步** | 知识库中无对应有效条目（或已移出）；在满足矩阵规则下可执行手动「同步知识库」（仅当上架状态为 **未发布** 时，见 **4.6**） | | **已同步** | 知识库侧**已有**与本条对应的条目；业务侧**禁止编辑**（须先移出后再改）；**未发布**时可 **发布**、**移出知识库** | **已同步状态下若要改内容：** 须 **移出知识库** → **未同步** 下完成修改 → 再 **同步知识库** → **已同步**。 「移出知识库」见 **4.7**：执行后须将本维度置为 **未同步**。 #### 2.2.3 合法组合（上架 × 知识库） 以下组合**允许作为稳态存在**；其余组合（例如 **已发布 + 未同步**）视为 **非法**，不得在业务流程中作为稳态出现；各入口须拒绝导致非法组合的操作。 | 上架状态 | 知识库同步 | 说明 | | --- | --- | --- | | 未发布 | 未同步 | 初始或移出后；可手动同步、可编辑；**未同步**条件下允许删除（见 **4.4**） | | 未发布 | 已同步 | 已入库（含手动同步、或**已发布下架回流**）；**不可编辑**、可发布、可移出；删除规则见 **4.4** | | 已发布 | 已同步 | 发布的前提为已同步（**4.8**）；对外展示中，不可改、不可删，仅可下架 | **说明：** 按 **4.8**，下架完成后的目标稳态为 **未发布 + 已同步**（库内保留可编辑副本），**不**将「已下架 + 未同步」作为下架必经业务终态。须与「移出知识库」（**4.7**，库侧条目删除或下线并置 **未同步**）严格区分。 **操作可用性以第 5 节矩阵为准**。 --- ## 3. 功能范围 - 生长与出栏标准的新增、修改、删除、分页列表查询、详情查看 - 标准正文附件（非结构化文档）与封面图的上传、替换、展示及删除时的存储联动清理 - 与知识库的同步、移出 - 发布、下架及与知识库的一致性处理 - 面向使用方的错误信息呈现约定（见第 6 章） ### 3.1 业务流程概览（与养殖标准一致） 下列顺序描述**典型闭环**；具体操作禁忌以 **第 5 节矩阵** 为准。 1. **新建**：录入必填项并上传正文（及可选封面）→ 初始为 **未发布 + 未同步**。 2. **首次入库**：在 **未发布 + 未同步** 下执行「同步知识库」→ **未发布 + 已同步**。 3. **迭代编辑**：仅在 **未发布 + 未同步** 下允许修改；**已同步**须先移出（步骤 7）再编辑。**未同步**保存仅更新业务侧，仍依赖步骤 2。 4. **发布**：仅在 **未发布 + 已同步** 下允许 → **已发布 + 已同步**。 5. **下架**：仅在 **已发布** 下允许 → 回到 **未发布 + 已同步**（库内保留条目，非移出）。 6. **再发布 / 纠错再入库**：已同步可直接重复步骤 4；若需改内容则 **移出 → 编辑 → 同步 → 发布**（**无须新建**记录）。 7. **彻底移出知识库**：在 **未发布 + 已同步** 下主动「移出」→ **未发布 + 未同步**。 8. **删除**：在 **未同步** 下允许直接删除（含删存储文件与通知知识库删除侧条目）；若当前为 **未发布 + 已同步**，须先执行步骤 7，或在「删除」流程中 **原子联动** 完成库侧清理后再删（见 **4.4**）。 --- ## 4. 详细功能需求 ### 4.1 新增长生与出栏标准 | 字段 | 规则 | | --- | --- | | 标准名称 | 必填；长度 **1～20** 个字符（字符计数规则与项目全局一致） | | 标准类型 | 必填；单选，取值须为第 **2.1** 节所列资讯类别编码之一 | | 标准简介 | **选填**；若有内容，长度不超过 **50 字**（字数口径与项目全局一致） | | 标准内容 | **必填**；通过**单个**附件上传；允许后缀：`pdf`、`md`、`doc`、`docx`、`xls`、`xlsx`、`pptx`；单文件 ≤ **30 MB** | | 封面 | **选填**；通过**单个**图片上传；允许后缀：`jpg`、`jpeg`、`png`（若产品要求支持 `webp` 等可追加）；单文件 ≤ **10 MB** | **必填字段汇总：** 标准名称、标准类型、标准内容。 **校验：** 须校验文件类型（后缀与白名单 / MIME 策略以项目安全规范为准）与大小；超限或格式不符时给出**可区分**的错误分类提示。若业务要求标准名称在适用范围（如租户 / 组织）内唯一，应在评审时单独约定并写入本节。 **初始状态：** 新建成功后，上架状态为 **未发布**，知识库同步状态为 **未同步**（与养殖标准初始化规则一致，除非产品另有统一约定）。 --- ### 4.2 查询生长与出栏标准列表 - **关键字：** 对「标准名称」或「标准简介」**模糊**匹配（二者为 OR 关系）。 - **标准类型：** **精确**匹配筛选。 - **分页：** 支持分页；默认 **每页 20 条**，默认首页为第一页；单页条数上限与后台列表通用规范一致（若有）。 - **排序：** 默认按 **创建时间倒序**（最新在前）；次要排序键与项目列表规范一致（若有）。 列表宜展示上架状态、知识库同步状态，便于用户理解当前可执行操作。 --- ### 4.3 修改生长与出栏标准 - **状态约束：** **仅未发布且未同步** 允许修改。**已发布**或 **已同步** 不允许修改（须返回明确业务原因，如「知识库已同步状态不允许修改」）。 - **可修改项：** 标准名称、标准类型、标准简介、标准内容（附件）、封面。 - **保存约束：** **标准名称、标准类型、标准内容** 始终保持必填（提交时不得为空、不得因操作导致无正文附件）；**标准简介**仍为选填。 - **与知识库一致性：** **未同步**状态下保存仅更新业务侧，不自动写入知识库，仍依赖 **4.6**。**已同步**须先 **移出知识库**（**4.7**）后再编辑。 --- ### 4.4 删除生长与出栏标准 - 删除本条业务记录时，须**同步删除**关联存储中的标准内容文件与封面文件；并**通知知识库**删除与本标准对应的条目，避免孤儿数据。 - **允许删除：** **未同步** 的标准允许删除（典型为 **未发布 + 未同步**，含移出后的情形）。 - **不允许删除：** **已发布** 的标准；须先执行「下架」（**4.8**）回到 **未发布** 后再按本条处理。 - **未发布且已同步：** **不得**在无知识库处理的前提下直接删除；须先 **移出知识库**（**4.7**）使同步维度变为 **未同步** 后再删；或在「删除」流程内 **原子联动** 完成知识库侧删除 / 下线后再删除业务记录与文件。 --- ### 4.5 查看生长与出栏标准详情 - 展示：**标准名称、标准类型、标准简介、标准内容（附件下载或预览入口）、正文附件原始名称（与上传文件名一致，便于识别）、封面**；宜展示当前 **上架状态** 与 **知识库同步状态**。 - **已发布**或 **已同步** 场景下详情为 **只读**；**未发布且未同步** 在具备编辑权限时可进入编辑流程。 - 在线预览能力（如 PDF、图片）若需要，可作为迭代项单列。 --- ### 4.6 同步至知识库（手动） - **适用：** 标准为 **未发布** 且 **未同步** 时，由用户触发「同步知识库」，将当前标准**首次**写入知识库（或对接语义下的首次挂载）。**已发布** 不适用本入口（须先下架回到 **未发布** 后再视同步维度操作）。 - **结果：** 手动同步成功后，知识库同步维度为 **已同步**，为发布做准备；此后若需改内容须先 **移出知识库**（**4.7**）。 - **失败：** 须给出明确、可区分的失败原因，支持用户重试。 --- ### 4.7 移出知识库 - **语义区分：** 「移出知识库」为**主动**删除或下线知识库侧对应条目；与「下架」（**4.8**）不同——**下架不删除库内副本**，业务侧仍为 **已同步**。 - **前置：** 仅 **未发布** 且 **已同步** 时可提供「移出知识库」。**已发布** 不提供「移出」；须先 **下架** 回到 **未发布 + 已同步** 后，用户再按需执行「移出」（**非**下架自动移出）。 - **结果：** 知识库侧对应条目删除或下线完成后，业务侧知识库同步维度须为 **未同步**；后续操作见 **第 5 节** 矩阵。 --- ### 4.8 发布与下架 - **发布：** - **仅当**标准**已同步知识库**且上架状态为 **未发布** 时，允许「发布」。 - 发布后上架状态为 **已发布**，知识库同步状态为 **已同步**。 - **下架：** - **已发布** 的标准可「下架」。 - 下架时须完成与知识库的一致性处理：**结束对外发布 / 对外检索可见** 等，但**不删除**知识库内与本标准对应的条目——库内**保留可编辑副本**，以便后续修改与再次发布（知识库侧「可见性 / 发布态」**以与知识库的对接约定为准**）。 - **下架完成后的业务状态：** 上架状态为 **未发布**，知识库同步状态为 **已同步**；允许用户**直接再次发布**；若需改内容须先 **移出知识库**，**无须新建**记录。 - 若需从库内**彻底清除**条目，须由用户在 **未发布 + 已同步** 下主动执行 **移出知识库**（**4.7**），而非由下架子流程替代。 --- ## 5. 状态与操作矩阵（汇总） 以下便于评审与测试映射。**已移除「已下架」作为独立矩阵行**：下架完成后回到 **未发布且已同步**（库内保留可编辑副本），与第二行合并理解。 | 当前状态（示意） | 修改 | 同步知识库 | 移出知识库 | 发布 | 下架 | 删除 | | --- | --- | --- | --- | --- | --- | --- | | 未发布且未同步 | ✓ | ✓ | — | — | — | ✓（未同步允许删） | | 未发布且已同步 | ✗ | — | ✓ | ✓ | — | ✗（须先移出或删除时联动库侧清理） | | 已发布 | ✗ | — | — | — | ✓（回流为未发布+已同步） | ✗ | **补充：** 从「已发布」下架后，记录进入 **未发布且已同步**，操作权限按上表第二行执行（不可改、可发布、可移出；删除规则同 **4.4**）。 --- ## 6. 错误与提示约定 - 业务与系统错误宜采用项目统一的 **`code`、`msg`、`data`** 结构呈现，便于前端与运维识别（不涉及具体协议与路径设计）。 - 文件相关错误（格式不支持、大小超限、上传失败等）宜有可区分的错误分类或文案。 --- ## 7. 非功能需求（建议） | 类别 | 建议 | | --- | --- | | 权限 | 菜单与按钮级权限：新增、编辑、删除、发布、下架、同步、移出等是否分角色 | | 审计 | 关键操作记操作日志（发布、下架、手动同步、移出、删除） | | 安全 | 上传文件类型校验、存储路径不可预测、下载鉴权 | | 性能 | 列表查询避免低效模式；大附件若后续需直传或分片再扩展 | --- ## 8. 修订说明（相对目录内草稿） - 将业务状态与《养殖标准管理功能需求》对齐为 **上架状态 × 知识库同步状态**，给出 **合法 / 非法组合** 与 **下架 ≠ 移出** 产品定论；修正草稿中 **两条「10.」** 的编号问题。 - 增补 **§3.1 业务流程概览**、**§5 操作矩阵**；删除、同步、发布、下架与知识库通知语义与养殖标准对齐。 - **标准类型** 改为资讯类别编码（`001011` 牦牛生长、`001012` 牦牛出栏；`parentCode=001`、`categoryType=4`）。 - **标准简介**、**封面** 与养殖标准对齐为 **选填**；简介若有内容仍受 50 字上限约束。 - **标准名称** 长度为 **1～20** 字符（与同目录草稿及《养殖标准管理功能需求》一致）。 - **不**在本文展开技术栈、库表与接口设计；草稿第 11 条归入 **§6**；草稿第 12 条技术栈删除（由技术方案或项目统一说明）。 - **标准内容**正文附件白名单调整为：`pdf`、`md`、`doc`、`docx`、`xls`、`xlsx`、`pptx`（不再支持旧版 `ppt`）；与 `GrowthSlaughterStandardRules` 及通用上传白名单（含 `md`）一致；**前端上传校验数组本次不调整**，以服务端校验为准。