huimv-baqing/doc/养殖标准体系/休药期标准/休药期标准管理功能需求.md

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

1. 文档说明

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

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

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

1.1 建议阅读顺序

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

---

2. 术语与业务状态

2.1 药物类型（单选）

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

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

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

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

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

---

3. 功能范围与流程

3.1 功能范围

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

3.2 状态迁移（示意）

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 条为技术备忘，不映射到本功能需求正文。