huimv-baqing/doc/牧业养殖科技服务/综合牧业知识库/综合牧业知识库技术方案.md

综合牧业知识库 — 技术方案

依据：综合牧业知识库管理功能需求.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 /common/upload；表存正文 URL + 存储路径 + 原始文件名；不入库文件大小
知识库	复用项目 KnowledgeBaseClient（uploadFileByUrl / deleteFile）；分类常量建议 综合牧业知识

分层：Controller → Service（入库状态机、事务、知识库编排、删附件）→ Mapper/XML → domain + support（校验、规则）。

代码包（建议）：com.ruoyi.web.modules.farming（与「畜牧科技资源」同域）
初始化脚本：sql/biz_livestock_knowledge.sql

一致性（与功能需求对齐）

规则	实现要点
无发布态	不设 publish_status；仅以 kb_sync_status 表示入库
改删	仅 kb_sync_status=0 且 del_flag=0
已入库	拒绝 PUT、逻辑删除；仅 syncKb / removeKb
同步	kb_sync_status=0 → 调知识库上传成功 → 置 1 并写 kb_doc_id；失败不改状态
移出	kb_sync_status=1 → deleteFile(kb_doc_id) 成功 → 置 0 并清空 kb_doc_id
修改不推库	已入库不可编辑；未入库保存不自动调知识库
删除	逻辑删除 del_flag=2 + 删 content_file_path 物理文件；kb_sync_status=0 时一般无需调 deleteFile

---

2. 数据库设计

2.1 表 biz_livestock_knowledge（综合牧业知识条目）

字段	类型	非空	默认	说明
id	bigint(20)	Y	自增	主键
knowledge_title	varchar(64)	Y	—	知识标题（业务 1～20 字）
knowledge_topic	tinyint(4)	Y	—	知识主题，见 2.2
introduction	varchar(200)	N	NULL	知识简介，选填 ≤50 字
content_file_url	varchar(512)	Y	—	正文附件访问 URL
content_file_path	varchar(512)	Y	—	正文存储路径（上传 fileName）
content_file_name	varchar(256)	Y	—	正文原始文件名（列表/下载展示）
kb_sync_status	tinyint(4)	Y	0	入库状态：0 未入库，1 已入库
kb_doc_id	varchar(128)	N	NULL	知识库文档 ID（file_id）
del_flag	char(1)	Y	'0'	0 正常 / 2 逻辑删除
create_by / create_time / update_by / update_time	若依惯例	—	—	—
remark	varchar(500)	N	NULL	备注

索引：PRIMARY KEY (id)；KEY idx_create_time (create_time)；KEY idx_topic (knowledge_topic)；KEY idx_kb (kb_sync_status)；KEY idx_del (del_flag)。

DDL（MySQL 5.7）

CREATE TABLE `biz_livestock_knowledge` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键',
  `knowledge_title` varchar(64) NOT NULL COMMENT '知识标题（业务1～20字）',
  `knowledge_topic` tinyint(4) NOT NULL COMMENT '知识主题1-5',
  `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 '正文原始文件名',
  `kb_sync_status` tinyint(4) NOT NULL DEFAULT '0' COMMENT '0未入库1已入库',
  `kb_doc_id` varchar(128) DEFAULT NULL COMMENT '知识库文档ID',
  `del_flag` char(1) NOT NULL DEFAULT '0' COMMENT '0正常2删除',
  `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_topic` (`knowledge_topic`),
  KEY `idx_kb` (`kb_sync_status`),
  KEY `idx_del` (`del_flag`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='综合牧业知识条目';

2.2 枚举

knowledge_topic

值	含义
1	饲养管理
2	疫病管理
3	设备选型
4	牧场设计
5	政策解读

kb_sync_status（界面「入库状态」）

值	含义
0	未入库
1	已入库

del_flag：0 正常 / 2 逻辑删除；列表默认 del_flag=0。

---

3. 接口设计

统一响应：RuoYi AjaxResult（code / msg / data）或分页 TableDataInfo。

权限标识（示例）：techService:knowledge:list|query|add|edit|remove|syncKb|removeKb

Base Path（示例）：/techService/knowledge

#	说明	Method	URI	权限	要点
3.1	分页列表	GET	/techService/knowledge/list	techService:knowledge:list	Query：pageNum（默认 1）、pageSize（默认 20）、keyword（标题/简介 OR 模糊）、knowledgeTopic（精确，可空）、kbSyncStatus（0/1，可空）；del_flag=0；排序 create_time DESC, id DESC
3.2	详情	GET	/techService/knowledge/{id}	techService:knowledge:query	全字段；del_flag=2 可返回 404 或业务错误
3.3	新增	POST	/techService/knowledge	techService:knowledge:add	Body：knowledgeTitle、knowledgeTopic、introduction（可空）、contentFileUrl、contentFilePath、contentFileName；落库 kb_sync_status=0，kb_doc_id=null
3.4	修改	PUT	/techService/knowledge	techService:knowledge:edit	Body 含 id；仅 kb_sync_status=0 且未删除；替换附件后删旧 content_file_path 文件
3.5	删除	DELETE	/techService/knowledge/{ids}	techService:knowledge:remove	仅 kb_sync_status=0；逻辑删除 + 删正文物理文件；不调知识库（未入库无 kb_doc_id）
3.6	同步知识库	POST	/techService/knowledge/syncKb/{id}	techService:knowledge:syncKb	前置 kb_sync_status=0；KnowledgeBaseClient.uploadFileByUrl(contentFileUrl, "综合牧业知识", knowledgeTitle)；成功写 kb_sync_status=1、kb_doc_id
3.7	移出知识库	POST	/techService/knowledge/removeKb/{id}	techService:knowledge:removeKb	前置 kb_sync_status=1 且 kb_doc_id 非空；deleteFile(kb_doc_id) 成功后 kb_sync_status=0，清空 kb_doc_id

3.1 列表响应字段（示例）

id、knowledgeTitle、knowledgeTopic、introduction、contentFileName、kbSyncStatus、createTime。

3.2 校验（Service 层）

项	规则
knowledgeTitle	必填，trim 后长度 1～20
knowledgeTopic	必填，∈ {1,2,3,4,5}
introduction	选填，≤50 字
正文附件	必填；后缀 pdf,md,doc,docx,xls,xlsx,ppt,pptx；≤30MB（上传阶段 + 保存前二次校验）

3.3 业务错误（msg 示例）

场景	文案
已入库编辑/删除	已入库条目请先移出知识库后再操作
重复同步	该条目已入库
未入库移出	仅已入库条目可移出知识库
知识库失败	同步知识库失败：{原因} / 移出知识库失败：{原因}

---

4. 知识库交互（摘要）

同步：校验 kb_sync_status=0
  → uploadFileByUrl(content_file_url, category="综合牧业知识", description=knowledge_title)
  ← file_id → 本地 kb_doc_id，kb_sync_status=1

移出：校验 kb_sync_status=1
  → deleteFile(kb_doc_id)
  ← 成功 → kb_sync_status=0，kb_doc_id=NULL

• 配置：复用 KbApiProperties（kb.admin.base-url 等）。
  
• URL 可达性：content_file_url 须为知识库服务可 HTTP 拉取的地址（与饲喂/养殖标准一致，必要时经 KbFileUrlResolver 解析）。
  
• 事务：同步/移出建议「调知识库成功后再更新本地状态」；失败不改 kb_sync_status。
  
• 问答：终端提问走知识库查询接口，不经本模块 Controller 转发（与标准类模块一致）。

---

5. 附件与交付

• 上传：前端先 /common/upload，再提交 contentFileUrl / contentFilePath / contentFileName。
  
• 交付勾选：DDL + 菜单按钮权限 SQL；Domain / Mapper / Service / Controller；单元测试 + MockMvc（列表筛选、状态拦截、同步/移出）。

---

6. 修订记录

版本	说明
1.0	初稿：对齐功能需求 v2.0；单表 biz_livestock_knowledge；仅 kb_sync_status 无发布态；7 个 REST 接口