西藏巴青项目

养殖标准管理 — 功能需求

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.7：执行后须将本维度置为 未同步。

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

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

上架状态	知识库同步	说明
未发布	未同步	初始或移出后；可手动同步、可编辑；未同步条件下允许删除（见 4.4）
未发布	已同步	已入库（含手动同步、或已发布下架回流）；不可编辑、可发布、可移出；删除规则见 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 修改养殖标准

状态约束： 仅未发布且未同步（publish_status=0 且 kb_sync_status=0）允许修改。已发布或 已同步 状态下不允许修改（列表/详情不提供编辑入口或仅为只读；调用修改类接口须返回明确业务错误，如「知识库已同步状态不允许修改」）。
可修改项：标准名称、标准类型、标准简介、标准内容（附件）、封面。
保存约束： 标准名称、标准类型、标准内容 始终保持必填（提交时不得为空、不得删除附件导致无正文）；标准简介仍为选填。
与知识库一致性： 未同步状态下修改保存仅更新业务侧，不自动写入知识库，仍依赖用户触发 4.6 的「同步知识库」。已同步须先 移出知识库（4.7）后再编辑。

4.4 删除养殖标准

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

4.5 查看养殖标准详情

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

4.6 同步至知识库（手动）

适用： 养殖标准为未发布且未同步（或等价状态）时，由用户点击「同步知识库」，将当前标准首次写入知识库（或对接语义下的首次挂载）。已发布记录不适用本手动入口（须先下架回到未发布后再视同步维度操作）。
结果： 手动同步成功后，标准进入「已同步」状态（或等价标记），为后续发布做准备；此后若需改内容须先 移出知识库（4.7）。
失败： 网络或知识库返回错误时，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 及饲喂/疫病/生长出栏等标准模块字段规则对齐。

养殖标准管理功能需求.md 14KB История Исходник