# 药物禁配标准管理 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 药物禁配标准管理 |
| 目标 | 维护「主药—配伍禁忌药物集合—配伍结果说明」类标准主数据，并与知识库建立或解除对应关系；删除时与知识库侧保持一致 |
| 依据 | 同目录 `药物禁配标准管理功能需求-草稿.md`（**本文不修改该草稿**，仅将其可验收内容整理为正式需求表述） |

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

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

**说明：** 草稿第 8 条字面为「休药期标准…」，按业务语境理解为 **本模块（药物禁配标准）** 与休药期等标准类模块一致：**不做发布/下架**，与养殖类「双维」模型区分。

### 1.1 建议阅读顺序

**第 2 章（术语与状态）→ 第 3 章（范围与流程）→ 第 5 章（操作矩阵）→ 第 4 章（分场景细则）**。

### 1.2 编制原则（验收口径）

- **状态唯一：** 除「未同步 / 已同步」外，不在需求正文引入其它业务态用语（如已发布）。  
- **规则可判定：** 凡写「不得」「须」「至少」处，均可在测试用例中做布尔判定。  
- **列表默认检索：** 默认仅按 **主药名称** 关键字模糊检索；若产品扩展为「配伍名参与命中」，须在需求变更中单列并验收。

---

## 2. 术语与业务状态

### 2.1 业务对象

| 概念 | 说明 |
| --- | --- |
| **主药** | 本条禁配标准所针对的药物；在列表检索、详情与编辑中作为主维度展示（草稿中「药物名称」即主药名称） |
| **配伍组（一条标准）** | 系统内 **一条禁配标准记录** 即一个配伍组：同一主药、一组配伍药物、**一条**配伍结果说明 |
| **配伍药物** | 组内与主药存在禁配关系的药物；**一条标准下可有多条**，每条为一条「配伍药物名称」记录；界面可通过 **增加 / 减少** 行维护列表（与草稿「+ / -」一致）；条数与合法性约束见 **2.3** |
| **配伍结果** | 对该**配伍组**的简短文字说明；组内所有配伍药物共享该说明；**选填** |

**同一主药多条标准：** 允许 `main_drug_name` 相同的多条记录并存，分别表示不同配伍组及各自配伍结果（例如组1「链霉素+庆大霉素→禁止合用」，组2「维生素C→降低疗效」）。移动端用药工具按**命中药对所在组**或**分组展示**读取数据。

**列表与详情中的配伍药物：** 以有序列表形式展示；顺序在业务上有展示意义时，宜与保存顺序一致。

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

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

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

**已同步状态下若要改内容：** 须 **移出知识库** → **未同步** 下完成修改（主药、配伍列表、配伍结果）→ 再 **同步知识库** → **已同步**。禁止在「已同步」下直接改业务数据并默认知识库已一致。

### 2.3 配伍药物列表的完整性（逻辑约束）

- 一条标准须至少包含 **1** 条配伍药物（否则「禁配」无指向对象）。  
- 配伍药物名称 **不允许为空**；与主药名称使用 **相同的字符长度规则**（见 **4.1**）。  
- **同一标准内**：配伍药物名称之间 **不得重复**（避免同一条标准内出现两条完全相同的配伍药名）。  
- **配伍药物名称不得与主药名称完全相同**（主药与禁忌对象应区分）。  
- 用户可通过 **增加 / 减少** 配伍药物行进行操作；减少时须满足「至少保留一条」；增加后出现空行须在保存前完成填写或通过校验阻止保存。  
- **名称比较口径：** 先做 **首尾空白去除（trim）**，再判断长度、相等与去重；若项目对全角/半角等另有统一归一规则，**从其约定**，并在验收时与实现保持一致。

---

## 3. 功能范围与流程

### 3.1 功能范围

- 新增、修改、删除、分页列表、详情查看  
- 维护主药、配伍药物列表、配伍结果三类业务数据  
- 知识库：**同步至知识库**（建立对应关系）、**移出知识库**（解除对应关系）  
- 删除时与知识库侧一致性（见 **4.4**）  
- 错误与提示与**项目统一习惯**一致（不规定具体错误码或报文字段名）

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

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

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

1. **新建**：填写主药、至少一条配伍药物、可选配伍结果 → 保存后 → **未同步**。  
2. **进入知识库**：**未同步** 下「同步知识库」成功 → **已同步**。  
3. **修改已入库内容**：**已同步** →「移出知识库」→ **未同步** → 本地修改保存 →「同步知识库」→ **已同步**。  
4. **删除**：仅 **未同步** 可删整条；已同步须先移出；删除与知识库侧一致性见 **4.4**。

### 3.4 常见场景串联（便于评审对齐）

| 场景 | 状态起点 | 用户动作 | 状态终点 / 说明 |
| --- | --- | --- | --- |
| 仅建档 | — | 新增并保存 | **未同步**；可继续改、可删、可同步 |
| 入库后纠错 | 已同步 | 移出 → 修改 → 再同步 | 回到 **已同步**；知识库与业务一致 |
| 放弃入库 | 已同步 | 移出 → 删除 | 记录删除；须满足 **4.4** 删库约定 |
| 仅查询 | 任意 | 列表/详情 | 不改变状态 |

---

## 4. 详细功能需求

### 4.1 新增

| 内容项 | 规则 |
| --- | --- |
| 主药—药物名称 | 必填；长度 **1～20** 字符；**允许重复**（同一主药可新建多条标准，每条为一个配伍组） |
| 配伍药物列表 | **至少 1 条**；每条名称必填，长度 **1～20** 字符（口径同上）；同条标准内名称**互不相同**且**均不得与主药名称相同**（比较规则见 **2.3** 末款） |
| 配伍结果 | **选填**；若有内容，长度不超过 **50** 字符（口径与项目全局一致） |

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

---

### 4.2 列表查询

- **主药名称**：支持关键字 **模糊** 匹配（默认仅主药维度；不对单条配伍药名做列表级模糊检索，除非按 **1.2** 已做产品扩展并验收）。  
- **列表**：宜展示 **知识库同步状态**；**宜**展示配伍条目**数量**或等价摘要（便于了解禁忌范围大小，**不规定**具体 UI 形态）。  
- **分页与排序**：支持分页；默认条数、排序方向（如最新在前）与**项目列表统一规范**一致，本文不约定技术参数名。

---

### 4.3 修改

- **条件：** 仅 **未同步** 可改（**已同步** 不可改）。  
- **可改项：** 主药名称、配伍药物列表（增删行、改各条名称）、配伍结果；保存时须仍满足 **4.1** 与 **2.3**。  
- **一致性：** 保存成功后，用户在同一入口再次打开列表或详情，应看到与本次保存一致的主药、配伍顺序与配伍结果（**所见即所得**，与项目刷新习惯一致）。  
- **失败：** 须有可读校验提示（如条数不足、配伍重名、与主药同名、长度越界等）。

---

### 4.4 删除

- **条件：** 仅 **未同步** 允许删除整条。**已同步** 须先 **移出知识库** 回到 **未同步** 再删。  
- **批量（若产品提供）：** 与项目同类删除一致；**同一操作内** 任一选中项不满足「未同步可删」时，**整单失败**并提示，**不**出现部分删除成功、部分仍残留且与矩阵不一致的情况（除非项目另有明确「跳过失败项」规范并已单独评审）。  
- **与知识库：** 删除前已满足「仅 **未同步** 可删」后，仍宜按项目与知识库的协作约定发起 **删除类通知**，并约定为 **幂等**（知识库侧若本无对应数据则安全忽略、不阻断本地删除），以保证删除链路一致、可验收。若协议明确规定「仅存在条目时才接收删除」，则须在协议与验收说明中单列，并与「删除时通知知识库」的表述对齐评审。  
- **交互：** 删除前宜二次确认；重要操作宜可追溯（与项目习惯一致）。

---

### 4.5 同步至知识库

- **条件：** **未同步**。  
- **互斥：** **已同步** 下不得再次执行「同步」成功路径；须拒绝或明确提示（与 **第 5 章** 一致）。  
- **结果：** 成功 → **已同步**；失败 → 仍为 **未同步**，提示可读并可重试。

---

### 4.6 移出知识库

- **条件：** **已同步**。  
- **互斥：** **未同步** 下不得执行「移出」成功路径；须拒绝或明确提示（与 **第 5 章** 一致）。  
- **结果：** 成功 → **未同步**；失败 → 仍为 **已同步**，提示可读并可重试。

---

### 4.7 查看详情

展示 **4.1** 所涉全部业务内容：主药名称、配伍药物列表（顺序与保存一致）、配伍结果（若有），并宜展示 **知识库同步状态**。**已同步** 为只读；**未同步** 在有权时可进入编辑。

---

## 5. 操作矩阵

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

---

## 6. 错误与提示

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

---

## 7. 非功能（建议）

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

---

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

| 草稿条款 | 本文位置 |
| --- | --- |
| 1 | **4.1**、**2.1**、**2.3**（「+ / -」落为增加/减少行与列表完整性规则） |
| 2 | **4.2** |
| 3 | **4.3**（并受 **2.2**、**2.3** 约束） |
| 4 | **4.4** |
| 5 | **4.7** |
| 6 | **2.2**、**5**（未同步行） |
| 7 | **2.2**、**5**（已同步行） |
| 8 | **第 1 章边界**、**2.2**、全文不出现发布/下架；**第 1 章「说明」** 对草稿笔误作语义对齐 |

草稿第 9～10 条为技术/报文与栈备忘，**不纳入**本功能需求正文；异常与错误表现遵循 **第 6 章** 及项目统一约定即可。
