# 休药期标准管理 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 休药期标准管理 |
| 目标 | 维护休药期标准主数据，并与知识库建立或解除对应关系；删除时与知识库侧保持一致 |
| 依据 | 同目录 `休药期标准管理功能需求-草稿.md`（**本文不修改该草稿**，仅将其第 1～8 条整理为可验收表述） |

**本文范围：** 只写**功能需求、业务规则与流程**；不写库表、接口路径、报文结构等技术设计。

**边界（对齐草稿第 8 条）：** 本模块**不设「发布 / 下架」**；不采用养殖等模块的「上架 × 知识库」双维模型。业务上只显式管理 **知识库同步状态**：**未同步** / **已同步**。

### 1.1 建议阅读顺序

**第 2 章（状态）→ 第 3 章（流程与图）→ 第 5 章（矩阵）→ 第 4 章（分场景细则）**。

---

## 2. 术语与业务状态

### 2.1 药物类型（单选）

**抗生素类**、**抗原虫类**、**抗病毒类**、**激素类** 四选一。

### 2.2 知识库同步状态（唯一显式状态）

| 状态 | 含义 |
| --- | --- |
| **未同步** | 本条可在业务侧维护；知识库侧**无**与本条对应的有效条目（含新建、或移出成功后） |
| **已同步** | 知识库侧**已有**与本条对应的条目；业务侧**禁止编辑与删除**，仅可 **查看**、**移出知识库** |

**合法稳态：** 仅上述两种；本模块需求**不出现**「已发布 / 未发布」作为状态机用语。

**已同步状态下若要改内容：** 须 **移出知识库** → **未同步** 下完成修改 → 再 **同步知识库** → **已同步**。禁止在「已同步」下直接改业务数据并默认知识库已一致。

---

## 3. 功能范围与流程

### 3.1 功能范围

- 新增、修改、删除、分页列表、详情查看  
- 知识库：**同步**（建立对应关系）、**移出**（解除对应关系）  
- 删除与知识库侧一致性（见 **4.4**）  
- 错误与提示与项目统一习惯一致（不规定具体报文形态）

### 3.2 状态迁移（示意）

```mermaid
stateDiagram-v2
    [*] --> 未同步: 新建保存
    未同步 --> 已同步: 同步知识库成功
    已同步 --> 未同步: 移出知识库成功
    未同步 --> [*]: 删除成功
```

### 3.3 关键路径（文字）

1. **新建**：保存后 → **未同步**。  
2. **进入知识库**：**未同步** 下「同步知识库」成功 → **已同步**。  
3. **修改已入库内容**：**已同步** →「移出知识库」→ **未同步** → 本地修改保存 →「同步知识库」→ **已同步**。  
4. **删除**：仅 **未同步** 可删整条；细则见 **4.4**。

---

## 4. 详细功能需求

### 4.1 新增

| 内容项 | 规则 |
| --- | --- |
| 药物名称 | 必填；长度 **1～20** 字符（计数口径与项目全局一致）；**全表唯一**（保存前 trim 后精确匹配，与其它记录 `drug_name` 不可重复） |
| 药物类型 | 必填；**2.1** 四类之一 |
| 休药期 | 必填；**整数** **1～999**，单位 **天** |
| 使用指南 | 必填；**1～200** 个汉字（计数口径与项目全局一致） |
| 药物作用 | 必填；**1～200** 个汉字（同上） |

保存成功后：**未同步**。

---

### 4.2 列表查询

- **药物名称**：关键字 **模糊** 匹配。  
- **药物类型**：可选，**精确** 筛选。  
- **列表**：宜展示 **知识库同步状态**，便于对照 **第 5 节**判断可操作项。  
- **分页与排序**：支持分页；默认条数、排序方向（如最新在前）与**项目列表统一规范**一致，本文不约定技术参数名。

---

### 4.3 修改

- **条件：** 仅 **未同步** 可改（与草稿第 6、7 条一致：**已同步** 不可改）。  
- **可改项：** 药物名称、药物类型、休药期、使用指南、药物作用；保存时须仍满足 **4.1**（含药物名称唯一性，修改时排除本条 `id`）。  
- **失败：** 须有可读校验提示（如药物名称已存在、已同步不可改等）。

---

### 4.4 删除

- **条件：** 仅 **未同步** 允许删除整条。**已同步** 须先 **移出知识库** 回到 **未同步** 再删。  
- **与知识库：** 删除前已满足「仅 **未同步** 可删」，业务上通常表示库侧已无对应条目。  
  - **产品定论（从未同步过是否仍发删除通知）：** **仍宜发起「删除」类通知，且约定为幂等**——即知识库侧若本无本条对应数据，应**安全忽略**而不报错、不阻断本地删除；这样删除链路统一，也避免依赖「是否曾成功同步」的细粒度判断产生遗漏。若与知识库的协作协议明确规定「仅存在条目时才接收删除」，则改为**不发送**，但须在协议与验收中单独写明，并与草稿第 4 条「通知知识库删除」的表述对齐评审。  
- **交互：** 删除前宜二次确认；重要操作宜可追溯（与项目习惯一致）。

---

### 4.5 同步至知识库

- **条件：** **未同步**。  
- **结果：** 成功 → **已同步**；失败 → 仍为 **未同步**，提示可读并可重试。

---

### 4.6 移出知识库

- **条件：** **已同步**。  
- **结果：** 成功 → **未同步**；失败 → 仍为 **已同步**，提示可读并可重试。

---

### 4.7 查看详情

展示 **4.1** 全部业务字段，并宜展示 **知识库同步状态**。**已同步** 为只读；**未同步** 在有权时可进入编辑。

---

## 5. 操作矩阵

| 知识库同步 | 查看 | 修改 | 删除 | 同步知识库 | 移出知识库 |
| :---: | :---: | :---: | :---: | :---: | :---: |
| 未同步 | ✓ | ✓ | ✓ | ✓ | — |
| 已同步 | ✓ | ✗ | ✗ | — | ✓ |

---

## 6. 错误与提示

校验失败、知识库操作失败、网络或权限问题等，提示须**统一、可读**；宜区分「输入不合法」与「知识库暂不可用」，便于用户重试或求助。

---

## 7. 非功能（建议）

权限（同步、移出、删）、审计、列表性能等与项目同类模块对齐。

---

## 8. 与草稿的对应关系（不改草稿，仅说明）

| 草稿条款 | 本文位置 |
| --- | --- |
| 1 | **4.1** |
| 2 | **4.2** |
| 3 | **4.3**（并受 **2.2** 约束） |
| 4 | **4.4** |
| 5 | **4.7** |
| 6 | **2.2**、**5**（未同步行） |
| 7 | **2.2**、**5**（已同步行） |
| 8 | **§1 边界**、**2.2**、全文不出现发布/下架 |

草稿第 9～10 条为技术备忘，**不映射**到本功能需求正文。
