# 休药期标准管理 — 技术方案

> 依据：同目录 `休药期标准管理功能需求.md`。本模块**不设发布/下架**（无 `publish_status` 等字段）；仅 **知识库同步** 维度与 CRUD。库表、接口与其它标准模块实现相互独立。

---

## 1. 技术架构

| 项 | 说明 |
| --- | --- |
| **后端** | RuoYi **v3.9.2**（**springboot2** 分支）：JDK 8、Spring Boot 2.x、Spring MVC、MyBatis、Druid |
| **数据库** | MySQL **5.7.39**，InnoDB，`utf8mb4` |
| **前端** | 若依 Vue2（与分支配套；路由、权限、字典按项目惯例） |
| **知识库** | HTTP 调用知识库后台管理服务；鉴权、URL、报文见《知识库接口对接说明》；本模块仅涉及**添加/更新/删除（幂等）**类变更，**不涉及**发布/下架可见性接口 |

**分层**：`Controller` → `Service`（状态校验、事务、知识库编排）→ `Mapper`/XML → `domain`（小驼峰 JSON 与 Jackson 一致）。

**一致性（摘要）**

- **删除**：本地删除前须为 `kb_sync_status=0`；删除流程中按需求对知识库发**幂等删除**通知（无条目则对端忽略），失败策略（阻断本地删 vs 异步补偿）由与知识库约定二选一并在实现中固定。  
- **移出**：前置 `kb_sync_status=1`；成功后 `kb_sync_status=0`，清空 `kb_doc_id`。  
- **同步**：前置 `kb_sync_status=0`；成功后 `kb_sync_status=1`，写入 `kb_doc_id`（未对接 HTTP 时可占位 `LOCAL-{id}`，与项目其它标准模块占位策略一致）。

---

## 2. 数据库设计

### 2.1 表 `biz_withdrawal_period_standard`

| 字段 | 类型 | 非空 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `id` | `bigint(20)` | Y | 自增 | 主键 |
| `drug_name` | `varchar(64)` | Y | — | 药物名称（业务 1～20 字符；**全表唯一**，保存前 trim） |
| `drug_type` | `tinyint(4)` | Y | — | `1`抗生素 `2`抗原虫 `3`抗病毒 `4`激素 |
| `withdrawal_days` | `int(11)` | Y | — | 休药期天数，**1～999** |
| `usage_guide` | `varchar(600)` | Y | — | 使用指南（需求 1～200 汉字，宽度留余量） |
| `drug_effect` | `varchar(600)` | Y | — | 药物作用（同上） |
| `kb_sync_status` | `tinyint(4)` | Y | `0` | `0` 未同步，`1` 已同步 |
| `kb_doc_id` | `varchar(128)` | N | NULL | 知识库文档 ID |
| `create_by` / `create_time` / `update_by` / `update_time` | 若依惯例 | — | — | — |
| `remark` | `varchar(500)` | N | NULL | 备注 |

**索引**：`PRIMARY KEY (id)`；`UNIQUE KEY uk_drug_name (drug_name)`；`KEY idx_create_time (create_time)`；`KEY idx_drug_type (drug_type)`；`KEY idx_kb (kb_sync_status)`。

**合法 `kb_sync_status`**：仅 `0`、`1`；应用层禁止写入其它值。

**DDL 示例**

```sql
CREATE TABLE `biz_withdrawal_period_standard` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键',
  `drug_name` varchar(64) NOT NULL COMMENT '药物名称（1～20字）',
  `drug_type` tinyint(4) NOT NULL COMMENT '1抗生素2抗原虫3抗病毒4激素',
  `withdrawal_days` int(11) NOT NULL COMMENT '休药期天数1～999',
  `usage_guide` varchar(600) NOT NULL COMMENT '使用指南',
  `drug_effect` varchar(600) NOT NULL COMMENT '药物作用',
  `kb_sync_status` tinyint(4) NOT NULL DEFAULT '0' COMMENT '0未同步1已同步',
  `kb_doc_id` varchar(128) DEFAULT NULL COMMENT '知识库文档ID',
  `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`),
  UNIQUE KEY `uk_drug_name` (`drug_name`),
  KEY `idx_create_time` (`create_time`),
  KEY `idx_drug_type` (`drug_type`),
  KEY `idx_kb` (`kb_sync_status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='休药期标准';
```

### 2.2 枚举（后端/字典建议）

| 字段 | 值 | 含义 |
| --- | --- | --- |
| `drug_type` | `1`～`4` | 抗生素 / 抗原虫 / 抗病毒 / 激素（顺序与需求列举一致） |
| `kb_sync_status` | `0` | 未同步 |
| | `1` | 已同步 |

---

## 3. 接口设计

**统一响应**：`AjaxResult` / 分页 `TableDataInfo`（与 RuoYi 一致）。

**Base Path**：`/withdrawalPeriod/standard`（若项目有全局 `context-path` 或网关前缀，实际 URL 需拼接）。

**权限标识（建议）**：`withdrawalPeriod:standard:list|query|add|edit|remove|syncKb|removeKb`（**无** `publish` / `offline`）

| # | 说明 | Method | URI | 权限 | 要点 |
| --- | --- | --- | --- | --- | --- |
| 3.1 | 分页列表 | GET | `/withdrawalPeriod/standard/list` | `withdrawalPeriod:standard:list` | Query：`pageNum`、`pageSize`（默认与项目列表一致，如 20）、`keyword`（**仅** `drug_name` 模糊）、`drugType`（精确，可空）；排序建议 `create_time DESC, id DESC` |
| 3.2 | 详情 | GET | `/withdrawalPeriod/standard/{id}` | `withdrawalPeriod:standard:query` | 返回全字段含 `kbSyncStatus`、`kbDocId` |
| 3.3 | 新增 | POST | `/withdrawalPeriod/standard` | `withdrawalPeriod:standard:add` | Body：`drugName`、`drugType`、`withdrawalDays`、`usageGuide`、`drugEffect`；落库 `kb_sync_status=0`，`kb_doc_id` 空 |
| 3.4 | 修改 | PUT | `/withdrawalPeriod/standard` | `withdrawalPeriod:standard:edit` | Body 含 `id`；**仅** `kb_sync_status=0`；校验字段同需求 **4.1**；**不**在 `kb_sync_status=1` 时自动推库（与需求「已同步不可改」一致，改内容须先移出） |
| 3.5 | 删除 | DELETE | `/withdrawalPeriod/standard/{ids}` | `withdrawalPeriod:standard:remove` | **仅** `kb_sync_status=0`；`kb_sync_status=1` 须先 `removeKb`；删前/删后按约定调知识库**幂等删除**；再删本地记录 |
| 3.6 | 同步知识库 | POST | `/withdrawalPeriod/standard/syncKb/{id}` | `withdrawalPeriod:standard:syncKb` | 前置 `kb_sync_status=0`；成功则 `kb_sync_status=1`，写入 `kb_doc_id` |
| 3.7 | 移出知识库 | POST | `/withdrawalPeriod/standard/removeKb/{id}` | `withdrawalPeriod:standard:removeKb` | 前置 `kb_sync_status=1`；成功则 `kb_sync_status=0`，清空 `kb_doc_id` |

**校验（摘要）**：`drugName` 1～20 且 **全表唯一**（`countByDrugNameExcludeId`，修改时传 `excludeId`；重复提示「药物名称已存在」）；`drugType ∈ {1,2,3,4}`；`withdrawalDays` 整数 1～999；`usageGuide` / `drugEffect` 长度按需求汉字上限（`WithdrawalPeriodStandardValidation` + `BizWithdrawalPeriodStandardServiceImpl`）。

---

## 4. 与功能需求的对应（便于验收）

| 需求章节 | 技术落点 |
| --- | --- |
| 4.1 新增字段 | 表 **2.1** + POST **3.3** |
| 4.2 列表 | GET **3.1**（`keyword`→`drug_name`，`drugType`） |
| 4.3 修改 | PUT **3.4**（`kb_sync_status=0`） |
| 4.4 删除 | DELETE **3.5** + 知识库幂等删除 |
| 4.5 / 4.6 | POST **3.6** / **3.7** |
| 无发布/下架 | 无对应接口与表字段 |

---

## 5. 交付清单（勾选）

- [ ] DDL：`sql/biz_withdrawal_period_standard.sql`（与 **§2.1** 一致）及菜单按钮权限 SQL  
- [ ] Domain / Mapper / XML / Service / Controller（包路径与项目 `architecture` 模块惯例一致即可）  
- [ ] 单测：状态守卫、字段校验；接口测试：MockMvc 或集成环境  
- [ ] 与知识库真实 HTTP 对接（或占位策略）按《知识库接口对接说明》排期