西藏巴青项目

养殖标准管理 — 技术方案

依据：养殖标准管理功能需求.md（同目录）

1. 技术架构

层级	说明
整体	RuoYi v3.9.2（springboot2 分支）单体后端 + 若依 Vue2 前端（与分支配套）
运行时	JDK 8、Spring Boot 2.x、Spring MVC、MyBatis、Druid
数据库	MySQL 5.7.39，存储引擎 InnoDB，字符集 utf8mb4
文件	复用 RuoYi 既有上传能力（本地/MinIO 等以项目现有配置为准）；业务表存访问 URL、存储路径、正文附件名称（见 2.1，不落库文件大小）
外部系统	知识库后台管理服务（HTTP）：养殖标准在同步、发布、下架等环节调用其接口完成知识库变更通知；用户侧问答另走其提示词查询接口（见第 4 章）。URL、鉴权、报文另附《知识库接口对接说明》。

后端分层（与若依一致）

Controller：参数校验、权限注解、返回 AjaxResult / TableDataInfo
Service：状态机校验、事务、知识库编排、删文件
Mapper + XML：持久化
domain：实体与枚举常量

一致性策略（与需求对齐，养殖标准管理功能需求.md §4.7～4.8）

修改：仅 publish_status=0 且 kb_sync_status=0；不在 kb_sync_status=1 时自动推库（与需求「已同步不可改」一致，改内容须先移出）。
下架（与「移出」区分）： 业务侧 publish_status 置回 0（未发布），kb_sync_status 保持 1（已同步）；知识库侧 不删除文档条目，仅完成「结束对外发布/对外检索可见」等（具体 HTTP 语义见 §4.2（5），可为可见性变更、DELETE 的对端否定操作由对接文档约定）。禁止将下架实现为与「移出」相同的库条目物理删除并再把本地 kb_sync 置 0（除非产品另行变更需求）。
移出知识库： 通知知识库删除/下线条目后，本地 kb_sync_status=0，清空 kb_doc_id（与下架不同）。
删除： kb_sync_status=0 允许删（删库 + 删附件 + 通知知识库删除，见 3.5）；未发布且已同步须先移出或接口内原子联动删库条目再删本地；已发布禁止删除。

2. 数据库设计

2.1 表：`biz_breeding_standard`（养殖标准主表）

单表承载业务字段 + 双维状态 + 知识库侧关联键（若有）。

字段名	类型	非空	默认值	说明
`id`	`bigint(20)`	Y	自增	主键
`standard_name`	`varchar(64)`	Y	—	标准名称，需求 1～20 字符，库宽略放大
`standard_type`	`varchar(32)`	Y	—	资讯类别编码，见 2.3
`introduction`	`varchar(200)`	N	NULL	简介，选填，≤50 字
`content_file_url`	`varchar(512)`	Y	—	正文附件访问 URL（与若依上传返回 `url` 等对齐，用于下载/预览）
`content_file_path`	`varchar(512)`	Y	—	正文文件在存储侧的存储路径（与若依上传返回 `fileName` 等对齐）
`content_file_name`	`varchar(256)`	Y	—	正文附件名称（用户上传时的原始文件名，用于列表/详情展示与下载展示名）
`cover_file_url`	`varchar(512)`	N	NULL	封面访问 URL，选填
`cover_file_path`	`varchar(512)`	N	NULL	封面在存储侧的存储路径，选填
`publish_status`	`tinyint(4)`	Y	`0`	上架状态，见 2.4
`kb_sync_status`	`tinyint(4)`	Y	`0`	知识库同步状态，见 2.5
`kb_doc_id`	`varchar(128)`	N	NULL	知识库文档/条目 ID，未同步可空
`publish_time`	`datetime`	N	NULL	发布时间
`offline_time`	`datetime`	N	NULL	下架时间
`create_by`	`varchar(64)`	N	—	若依惯例
`create_time`	`datetime`	N	—	若依惯例
`update_by`	`varchar(64)`	N	—	若依惯例
`update_time`	`datetime`	N	—	若依惯例
`remark`	`varchar(500)`	N	NULL	备注（可选）

索引

PRIMARY KEY (id)
KEY idx_create_time (create_time) — 列表 ORDER BY create_time DESC
KEY idx_type (standard_type)
KEY idx_pub_kb (publish_status, kb_sync_status) — 后台筛选

DDL 示例（MySQL 5.7）

CREATE TABLE `biz_breeding_standard` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键',
  `standard_name` varchar(64) NOT NULL COMMENT '标准名称（业务1～20字符）',
  `standard_type` varchar(32) NOT NULL COMMENT '标准类型编码，对应资讯类别 parentCode=001&categoryType=1',
  `introduction` varchar(200) DEFAULT NULL COMMENT '简介',
  `content_file_url` varchar(512) NOT NULL COMMENT '正文附件访问URL',
  `content_file_path` varchar(512) NOT NULL COMMENT '正文文件存储路径',
  `content_file_name` varchar(256) NOT NULL COMMENT '正文附件名称',
  `cover_file_url` varchar(512) DEFAULT NULL COMMENT '封面访问URL',
  `cover_file_path` varchar(512) DEFAULT NULL COMMENT '封面文件存储路径',
  `publish_status` tinyint(4) NOT NULL DEFAULT '0' COMMENT '上架 0未发布 1已发布（下架回流写回0，不用2作稳态）',
  `kb_sync_status` tinyint(4) NOT NULL DEFAULT '0' COMMENT '知识库 0未同步 1已同步',
  `kb_doc_id` varchar(128) DEFAULT NULL COMMENT '知识库文档ID',
  `publish_time` datetime DEFAULT NULL COMMENT '发布时间',
  `offline_time` datetime DEFAULT NULL COMMENT '下架时间',
  `create_by` varchar(64) DEFAULT '' COMMENT '创建者',
  `create_time` datetime DEFAULT NULL COMMENT '创建时间',
  `update_by` varchar(64) DEFAULT '' COMMENT '更新者',
  `update_time` datetime DEFAULT NULL COMMENT '更新时间',
  `remark` varchar(500) DEFAULT NULL COMMENT '备注',
  PRIMARY KEY (`id`),
  KEY `idx_create_time` (`create_time`),
  KEY `idx_type` (`standard_type`),
  KEY `idx_pub_kb` (`publish_status`,`kb_sync_status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='养殖标准';

已有表升级（示例）：先增加可空列并回填，再改为非空。

ALTER TABLE `biz_breeding_standard`
  ADD COLUMN `content_file_name` varchar(256) DEFAULT NULL COMMENT '正文附件名称' AFTER `content_file_path`;
-- 按 `content_file_path` 或业务规则 UPDATE 回填后：
ALTER TABLE `biz_breeding_standard`
  MODIFY COLUMN `content_file_name` varchar(256) NOT NULL COMMENT '正文附件名称';

合法组合（应用层强校验，与需求 §2.2.3 一致；禁止非法落库）

publish_status	kb_sync_status	说明
0 未发布	0 未同步	✓（含新建、移出后）
0 未发布	1 已同步	✓（含手动同步、已发布下架回流，库内保留副本）
1 已发布	1 已同步	✓
其余（如 1+0 等）	—	✗

应用层校验 仅允许上表三行 合法组合落库与流转。

2.3 标准类型与资讯类别

数据来源：GET /category/informationCategory/children?parentCode=001&categoryType=1；响应字段 code（编码）、name（展示名）。GET /category/informationCategory/tree 树节点字段同为 code、name、categoryType、children。
落库值：standard_type 存编码（如 001001）。
校验：BreedingStandardTypeValidator；非法编码返回「标准类型无效，请选择资讯类别中的类型」。

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

存量库迁移：执行 sql/biz_breeding_standard_alter_standard_type.sql（1→001001 … 4→001004）。

2.4 上架状态 `publish_status`

值	含义
`0`	未发布（含草稿、下架回流）
`1`	已发布

下架： 操作完成后须将本字段置 0，与需求「未发布 + 已同步」一致。

2.5 知识库同步 `kb_sync_status`

值	含义
`0`	未同步
`1`	已同步

3. 接口设计

统一响应：RuoYi 惯例 AjaxResult（code / msg / data）或分页 TableDataInfo；错误码与文案区分参数校验、状态非法、文件非法、知识库失败等。

Base Path（示例）：/breeding/standard（实际前缀与若依 context-path、模块路由对齐）

3.1 分页列表

项	说明
Method / URI	`GET /breeding/standard/list`
权限	`breeding:standard:list`
Query	`pageNum`（默认 1）、`pageSize`（默认 20）、`keyword`（名称/简介 OR 模糊）、`standardType`（精确，可空）
排序	默认 `create_time DESC`, `id DESC`
响应	`TableDataInfo` 行内字段：id、standardName、standardType、introduction、`contentFileName`（可选展示）、publishStatus、kbSyncStatus、createTime 等

3.2 详情

项	说明
Method / URI	`GET /breeding/standard/{id}`
权限	`breeding:standard:query`
响应	含 `standardName`、`introduction`、`contentFileUrl`、`contentFilePath`、`contentFileName`、`coverFileUrl`、`coverFilePath`、双维状态、时间等；附件下载可走若依 `/common/download` 或直链（需鉴权）

3.3 新增

项	说明
Method / URI	`POST /breeding/standard`
权限	`breeding:standard:add`
Body	JSON：`standardName`、`standardType`、`introduction`（可空）、`contentFileUrl`、`contentFilePath`、`contentFileName`（正文附件名称，与上传返回 `originalFilename` 对齐）、`coverFileUrl`、`coverFilePath`（封面可空）；正文须先上传
校验	名称长度 1～20；`standard_type` 为资讯类别有效编码（2.3）；简介字数、附件后缀与 ≤30MB、封面后缀与 ≤10MB
落库	`publish_status=0`，`kb_sync_status=0`，时间字段由若依填充

3.4 修改

项	说明
Method / URI	`PUT /breeding/standard`
权限	`breeding:standard:edit`
前置	仅 `publish_status=0` 且 `kb_sync_status=0`；否则返回业务错误（如「知识库已同步状态不允许修改」）
Body	含 `id`；可替换正文/封面的 `Url`、`Path` 及正文 `contentFileName`
逻辑	更新库表；不自动调用知识库（改内容须先移出后再手动同步）

3.5 删除

项	说明
Method / URI	`DELETE /breeding/standard/{ids}`
权限	`breeding:standard:remove`
规则	`publish_status=1` 禁止；`kb_sync_status=0` 允许删除；`publish_status=0` 且 `kb_sync_status=1` 须先移出（3.7）或本接口内原子联动删知识库条目再删本地
副作用	物理删记录 + 删除 OSS/磁盘上正文与封面文件 + 通知知识库删除对应条目（与需求 §4.4）

3.6 同步知识库（手动）

项	说明
Method / URI	`POST /breeding/standard/syncKb/{id}`
权限	`breeding:standard:syncKb`
前置	`publish_status=0` 且 `kb_sync_status=0`
结果	调知识库入库，`kb_sync_status=1`，写入 `kb_doc_id`

3.7 移出知识库

项	说明
Method / URI	`POST /breeding/standard/removeKb/{id}`
权限	`breeding:standard:removeKb`
前置	`publish_status=0` 且 `kb_sync_status=1`
结果	调知识库删除，`kb_sync_status=0`，`kb_doc_id` 清空

3.8 发布

项	说明
Method / URI	`POST /breeding/standard/publish/{id}`
权限	`breeding:standard:publish`
前置	`publish_status=0` 且 `kb_sync_status=1`
结果	`publish_status=1`，`publish_time=now()`

3.9 下架

项	说明
Method / URI	`POST /breeding/standard/offline/{id}`
权限	`breeding:standard:offline`
前置	`publish_status=1`
结果	调知识库完成「对外下架」语义（非移出删条目，见 §4.2（5））；本地 `publish_status=0`，`kb_sync_status=1`（保留 `kb_doc_id`）；`offline_time=now()`（审计下架时刻）；可选清空 `publish_time` 或由产品约定是否保留上次发布时间

4. 与知识库后台管理服务交互（流程）

本章约定：养殖标准业务服务（RuoYi 后端）与 知识库后台管理服务 之间通过 HTTP 交互；具体路径、Header（如 Authorization/X-Api-Key）、请求体字段以《知识库后台管理服务接口文档》为准，此处描述 调用时机、顺序职责与失败策略。

4.1 交互角色

角色	说明
养殖标准业务服务	在本模块内完成鉴权、状态机、落库后，按需调用知识库后台管理服务接口，驱动知识库侧文档/索引/可见性变更
知识库后台管理服务	接收变更通知，执行入库、更新、发布可见、下架移除等；可提供提示词查询能力供终端提问
终端用户（提问）	一般不经过养殖标准 CRUD 接口；通过前端或统一网关直接调用知识库后台管理服务的提示词查询接口完成问答（与养殖标准数据是否已发布、是否仍在库内等业务规则由知识库侧检索策略决定）

4.2 养殖标准触发的 HTTP 调用（知识库变更通知）

下列步骤中「调用知识库接口」均指 知识库后台管理服务 暴露的管理类 HTTP API（命名示例：/kb/admin/doc/...，以对接文档为准）。

变更通知统一必填语义（报文体）

每次调用变更通知接口时，须告知以下字段（字段名可与对接文档对齐，语义不变）：

字段语义	说明
操作类型	`添加`：首次同步入库、已同步后的保存更新（内容替换）、发布等对「库内需保留/更新该标准正文」的通知；`删除`：移出知识库、业务删除等对「库内需移除该标准条目」的通知。下架不等于删除条目：下架走「可见性/发布态」类接口（可能仍归类为扩展字段或单独 API，见 §4.2（5）），不应默认使用本表的 `删除` 语义清掉副本。（若对端要求枚举值为英文，可约定 `ADD` / `DELETE`）
标准名称	当前养殖标准 `standard_name`，与业务侧一致
标准 HTTP 下载地址	正文附件 `content_file_url`（可被浏览器或服务端拉取的 HTTP(S) 下载地址；对内下载网关则需对外亦为可达或可再由知识库回源拉取）

说明：

添加 类：content_file_url 指向最新可下载的正文；若同一业务反复推送更新，均为 添加 语义下的版本刷新（对端实现幂等或覆盖策略）。
删除 类：仍携带 标准名称 与 当时的 content_file_url（库内留存值），便于对端定位；若记录已删仅存快照，以对端约定为准。
其余扩展字段（业务主键 id、kb_doc_id、类型、简介等）可按《知识库接口对接说明》选填，不得弱化上述三项必填语义。

（1）同步至知识库（手动首次）

用户点击「同步」→ Service 校验 publish_status=0 且 kb_sync_status=0
  → HTTP：变更通知（操作类型=添加，标准名称，标准 HTTP 下载地址=content_file_url）
  ← 成功返回知识库文档 ID（写入 kb_doc_id）
  → 本地 kb_sync_status=1；失败则不打勾成功态，提示重试

（2）修改保存（仅未同步）

用户保存修改 → Service 校验 publish_status=0 且 kb_sync_status=0
  → 仅更新本地库表；不调用知识库
  ← 成功则提交；kb_sync_status=1 时接口拒绝

说明： 已同步记录须先 移出知识库（（3））后再走本流程，改完须再 手动同步（（1））。

（3）移出知识库（仅未发布且已同步）

用户点击「移出」→ HTTP：变更通知（操作类型=删除，标准名称，content_file_url）
  ← 成功 → 本地 kb_sync_status=0，清空 kb_doc_id

（4）发布

用户点击「发布」→ Service 校验未发布且已同步
  → HTTP：变更通知（操作类型=添加，标准名称，content_file_url；语义上可附带「发布可见」，以对端扩展字段为准）
  ← 成功 → 本地 publish_status=1，publish_time 落库

（5）下架（与「移出」区分）

用户点击「下架」→ Service 校验 publish_status=1
  → HTTP：按对接文档通知知识库「结束对外发布/检索可见」（语义可为 UPDATE 可见性、撤销发布位等；需求明确库内保留可编辑副本，不得等同于「移出」的 DELETE 整条）
  ← 成功 → 本地 publish_status=0，kb_sync_status=1，offline_time=now()；kb_doc_id 保留

若对端 仅支持「删除类」接口表达下架，须在《对接说明》中约定 二次入库/副本保留 策略，否则与需求「下架后仍为已同步」冲突，须产品书面确认。

（6）删除（未发布且已同步时的联动）

若删除流程内需先清库：在删本地记录前 HTTP：变更通知（操作类型=删除，标准名称，content_file_url），成功后再删库与删附件（与 3.5 规则一致）。

4.3 提示词查询接口（用户提问）

项	说明
调用方	业务前端、移动端或统一 API 网关（非养殖标准 Module 内必选依赖）
被调服务	知识库后台管理服务（或其对外的查询子域，以部署为准）提供的提示词查询 / 对话检索类 HTTP 接口
请求必填语义	`用户标识`：调用方传入当前提问用户的唯一标识（如用户 ID、统一账号 `sub`、企微 `openid` 等，格式与对端约定一致）；`问题内容`：用户输入的自然语言问题正文
用途	携带上述字段发起提问，返回基于知识库检索与模型编排的答案；可检索范围是否包含「仅已发布的养殖标准」等由知识库侧策略与标签过滤实现
与养殖标准的关系	养殖标准通过 4.2 保证入库、发布、下架时知识库内容与状态一致；问答链路独立调用查询接口，无需养殖标准 Controller 再转发（若产品要求经网关统一鉴权，可在网关层聚合）

4.4 实现要点（研发）

客户端封装：KbAdminClient（或同名 Bean），封装变更通知（操作类型 / 标准名称 / content_file_url）与查询请求（用户标识 / 问题内容）；超时、重试策略（慎用）、幂等键（若对端要求）、结构化日志（bizId、kbDocId、接口名、耗时）。
配置：kb.admin.base-url、kb.admin.token（或 OAuth 客户端配置）等写入 application-*.yml，区分环境。
安全：管理接口仅限服务端调用，禁止把管理密钥下发浏览器；提示词查询接口按产品要求做用户鉴权与限流。
联调：以对接文档中的错误码映射到前端 msg，与 3.x 业务接口返回风格一致。

5. 附件与上传（实现提示）

前端：先调若依现有 /common/upload（或项目封装接口），得到 url（写入 content_file_url / cover_file_url）、存储路径（写入 content_file_path / cover_file_path，一般为返回的 fileName 或项目约定字段）、原始文件名（写入 content_file_name，对应返回 originalFilename）；大小仅在提交前用于校验 ≤30MB / ≤10MB，不入库。
服务端：对白名单后缀与大小 二次校验（大小可由上传接口或临时读取流获取）；替换附件时按 path 删除旧物理文件避免残留。

6. 交付清单（研发勾选）

表 biz_breeding_standard DDL 与初始化脚本
Domain / Mapper / Service / Controller
菜单与按钮权限 SQL
知识库后台管理服务 Client（变更通知类接口）+ 配置项（§4）；对接文档中单列「提示词查询」接口供前端/网关引用
核心场景集成测试：同步、发布、下架、移出、删除与非法状态拦截；已同步修改被拒绝；与知识库后台 HTTP 联调记录

7. 修订记录

日期	说明
—	初稿，对齐 `养殖标准管理功能需求.md`
—	库表：删除 `content_file_size`、`cover_file_size`；正文侧增加 `content_file_path`（存储路径）；`cover_file_name`→`cover_file_path`（封面存储路径）；接口 Body 同步调整
—	库表：新增 `content_file_name`（正文附件名称）；接口增加 `contentFileName`
—	新增第 4 章：与知识库后台管理服务 HTTP 交互流程（同步、移出、发布、下架、删除联动）；已同步禁止修改；提示词查询接口供用户独立调用说明；原 §4～§6 顺延为 §5～§7
—	§4.2 变更通知统一携带：操作类型（添加/删除）、标准名称、标准 HTTP 下载地址（content_file_url）；§4.3 提问携带：用户标识、问题内容
—	对齐需求修订：下架回流为 `publish_status=0` + `kb_sync_status=1`，库内保留副本；下架 ≠ 移出；合法组合仅 (0,0)(0,1)(1,1)；删除规则与 3.5 / 3.9 同步更新

养殖标准管理技术方案.md 22KB 文件历史 原始文件