# 风险因子设置 — 功能需求

## 1. 文档说明

| 项 | 说明 |
| --- | --- |
| 模块名称 | 风险因子设置（界面标题可为「风险因子权重」，见原型） |
| 目标 | 配置疾病风险评估模型中各因子的**权重**，保证五项权重均为正数且**合计为 1**，供后续风险计算或预警模块引用 |
| 关联系统 | 业务后台；与「疾病检测与上报」体系内疫情上报、实验室检测等模块的衔接由产品统一规划 |
| 修订依据 | 同目录 `风险因子设置-草稿.md`、界面原型 `风险因子设置.png` |

本文档仅描述**功能需求与业务规则**，不涉及库表结构、接口路径、请求体字段命名及技术栈选型。

---

## 2. 术语与因子说明

### 2.1 风险因子（固定五项）

本模块维护的因子集合**固定**为下表五项，用户**不可**新增、删除或重命名因子（若需扩展因子项，须单独修订需求与原型）。

| 序号 | 因子名称 | 业务含义（摘要） |
| --- | --- | --- |
| 1 | **养殖密度** | 养殖场所或区域单位面积/单位规模上的畜禽承载程度，密度越高通常意味着传播风险上升 |
| 2 | **交通流动性** | 人员、物资、畜禽调运等与外部交流的频繁程度 |
| 3 | **检疫强度** | 检疫、免疫、监测等防控措施的执行力度（强度越高，一般表示防控越严） |
| 4 | **气象适宜度** | 温湿度、降水等气象条件对病原体存活与传播的有利程度 |
| 5 | **既往发病水平** | 历史疫情、阳性检出、上报记录等反映的基线发病水平 |

### 2.2 权重

| 项 | 说明 |
| --- | --- |
| 含义 | 某因子在综合风险评分中的占比 |
| 取值 | **正数**；五项权重**之和必须等于 1**（见 **§2.3**） |
| 展示 | 建议以小数形式录入与展示（如 `0.20`）；是否同时展示百分比（如 `20%`）由界面统一，**录入口径以小数为准** |
| 精度 | 小数位数与项目全局数字规范一致（建议保留 **2～4** 位）；保存与「和为 1」校验须在**同一精度规则**下比较 |

### 2.3 权重合计约束（核心规则）

| 规则 | 说明 |
| --- | --- |
| **和为 1** | 五项权重相加的结果**必须等于 1**（在约定精度下比较，见下） |
| 精度比较 | 例如保留 4 位小数时，允许误差 `|Σ − 1| ≤ 0.0001`；具体容差须在实现前与产品确认并全文统一 |
| 实时提示 | 录入过程中宜在页面展示**当前合计**（如「当前合计：0.85」），并在合计 ≠ 1 时提示用户调整 |
| 保存拦截 | 合计不为 1 时**不允许保存**，并给出明确提示（如「五项权重之和须等于 1」） |

### 2.4 配置记录说明

- 本模块为**全局参数配置**，通常仅维护**一套**当前生效的权重（非分页台账、非按地区多套配置的复杂模型，除非产品另行约定「按区划多套权重」）。  
- 是否保留历史版本、回滚上一版权重，本期草稿与原型**未要求**；若需要须单独立项。  
- 权重保存成功后，下游风险计算宜使用**最新已保存**的权重；未保存前的临时输入**不得**参与正式计算。

---

## 3. 功能范围

**本期实现：**

- 风险因子权重**查看**（进入页面加载当前生效配置）  
- 风险因子权重**保存**（一次性提交五项权重）  
- 五项权重的必填、正数、合计为 1 等校验  
- 保存成功/失败的用户提示（见 **§8**）  

**本期不实现：**

- 因子项的新增、删除、排序、自定义名称  
- 按区域、牧场、疫情类型等维护**多套**权重方案（若需要另出需求）  
- 权重变更审批流、版本对比、定时生效  
- 基于权重自动跑分、地图预警等（属下游模块，不在本文档范围）  

---

## 4. 业务流程概览

```mermaid
flowchart LR
    A[进入风险因子设置页] --> B[加载当前权重]
    B --> C[查看/修改五项权重]
    C --> D{合计=1且各项为正数?}
    D -->|否| C
    D -->|是| E[点击保存]
    E --> F[保存成功]
    F --> B
```

1. **进入**：具备权限的用户打开「风险因子设置/风险因子权重」页面。  
2. **加载**：系统展示当前生效的五项权重；若从未配置，可按产品约定展示默认值（如各项 `0.2`）或空表单项并提示须完成首次配置。  
3. **调整**：用户修改一项或多项权重；页面实时刷新合计。  
4. **保存**：用户点击「保存」→ 通过校验后写入并提示成功；未通过校验则停留在当前页并标明原因。  
5. **使用**：其它业务模块读取**已保存**的权重参与风险相关计算（引用规则由下游需求定义）。

---

## 5. 详细功能需求

### 5.1 页面展示与加载

| 项 | 规则 |
| --- | --- |
| 页面标题 | 与原型一致，建议为 **「风险因子权重」** 或产品确认的等价文案 |
| 表单项 | 固定展示 **§2.1** 五项因子，每项对应一个权重输入框；标签与原型一致 |
| 占位提示 | 输入框占位符宜为「请输入权重」等与原型一致 |
| 辅助说明 | 每项输入旁或下方宜标注 **「正数」**（与原型一致）；页面底部或合计区标注 **「权重之和 = 1」** |
| 加载 | 进入页面时自动加载当前生效配置；加载中宜有等待态，失败时提示并可重试 |

**首次无数据（若存在）：**

- 五项可为空或预填建议默认值；**保存时仍须满足**正数且合计为 1。  
- 是否允许「全空不可保存」与「预填 0.2×5」由产品择一并在实现说明中固定。

---

### 5.2 权重录入与校验

| 因子 | 规则 |
| --- | --- |
| 养殖密度 | **必填**；**正数**（大于 0） |
| 交通流动性 | **必填**；**正数** |
| 检疫强度 | **必填**；**正数** |
| 气象适宜度 | **必填**；**正数** |
| 既往发病水平 | **必填**；**正数** |

**汇总校验：**

| 规则 | 说明 |
| --- | --- |
| 正数 | 拒绝 0、负数、非数字；是否拒绝「正无穷」等等价异常由实现约定 |
| 合计 | 五项之和 **= 1**（按 **§2.3** 精度规则） |
| 单项上限 | 因合计为 1 且各项为正，隐含每项 **< 1**；无需单独配置上限除非产品要求（如单项不得超过 0.8） |

**交互建议：**

- 修改任一项时，**实时计算并展示**五项合计。  
- 合计 ≠ 1 时，「保存」可置灰或点击后提示，避免误提交。  
- 各字段校验失败时，错误提示宜**可区分**（未填、非正数、合计不为 1）。

---

### 5.3 保存权重

| 项 | 规则 |
| --- | --- |
| 触发 | 用户点击 **「保存」** 按钮（与原型一致） |
| 前置校验 | 须先通过 **§5.2** 全部校验；未通过则不提交 |
| 确认 | 是否二次确认由产品约定；原型未要求弹窗确认，默认可**直接保存** |
| 成功 | 提示保存成功；页面展示与刚保存一致的权重；宜记录操作人、操作时间（若系统有审计字段） |
| 失败 | 提示失败原因（网络、权限、服务端业务错误等），**不**部分更新五项中的若干项（须保证五项作为一套配置原子更新） |

**并发与覆盖：**

- 若两人同时修改，以后保存者覆盖或提示「配置已被他人更新」由实现阶段约定；需求层要求：**避免**出现长期不一致的五项组合（如仅三项更新成功）。

---

### 5.4 查看与权限（无列表）

- 本模块**无**分页列表、详情弹窗、删除单条等台账操作。  
- **查看**即进入配置页阅读当前五项权重。  
- **修改**即在同一页面编辑并保存。  

在**已授权**前提下（菜单与按钮级权限按项目角色配置）：

| 操作 | 说明 |
| --- | --- |
| 查看/进入页面 | 具备查询或列表类权限即可进入并加载 |
| 保存 | 具备修改/保存类权限方可点击保存并成功提交 |

具体权限标识在权限配置文档中定义，本文档不展开。

---

## 6. 操作权限矩阵（汇总）

| 能力 | 查看当前权重 | 修改并保存 |
| --- | --- | --- |
| 有查询权限 | ✓ | — |
| 有保存/修改权限 | ✓ | ✓ |

> 若菜单仅配置一个「风险因子设置」入口，常见做法为：进入需 `list` 或 `query`，保存需 `edit` 或 `save`（实现时与后端权限命名对齐即可）。

---

## 7. 错误与提示约定

面向使用方的提示宜**语义明确、可区分**，例如：

| 场景 | 提示方向（示例） |
| --- | --- |
| 某项未填 | 「请填写【养殖密度】权重」 |
| 非正数 | 「【交通流动性】权重须为正数」 |
| 合计不为 1 | 「五项权重之和须等于 1，当前合计为 x.xx」 |
| 加载失败 | 「权重配置加载失败，请稍后重试」 |
| 保存成功 | 「保存成功」 |
| 无保存权限 | 「无权限修改风险因子权重」 |

本文档**不约定** HTTP 状态码、错误码字段名及接口报文结构（草稿中的统一 `code/msg/data` 属实现层，不写入本文档）。

---

## 8. 非功能需求（建议）

| 类别 | 建议 |
| --- | --- |
| 权限 | 仅管理员或业务配置角色可保存；普通用户只读或不可见菜单 |
| 审计 | 保存记操作日志：操作人、时间、变更前后权重（若系统支持） |
| 性能 | 单页五项数值，加载与保存响应满足后台常规体验即可 |
| 双语 | 因子名称与提示符合项目 i18n 规范（汉语 + 藏文，若适用） |
| 扩展 | 多套权重方案、因子项可配置、版本回滚、与风险评分的公式联动 |

---

## 9. 修订说明（相对草稿）

| 草稿条目 | 优化处理 |
| --- | --- |
| 仅列五项权重与「和=1」 | 扩展为 **§2** 因子含义、**§2.3** 精度与实时合计、**§5** 分节 |
| 编号跳跃（1 后直接 6、7） | 重整章节；移除技术栈与接口响应格式 |
| 「养殖标准管理」类笔误风险 | 模块定为 **风险因子设置**，与目录、原型一致 |
| 未说明是否列表/多版本 | 明确为**全局单套配置**（**§2.4**） |
| 无流程图 | 增补 **§4** 流程图与操作矩阵 |
| 原型「正数」 | 明确为 **> 0**，且与「和为 1」联立（**§5.2**） |

---

## 10. 功能需求追溯（自查）

| 能力 | 对应章节 |
| --- | --- |
| 五项因子固定展示 | §2.1、§5.1 |
| 正数、必填 | §5.2 |
| 权重之和 = 1 | §2.3、§5.2、§5.3 |
| 保存 | §5.3、§4 |
| 权限与提示 | §6、§7 |
| 不含接口/库表 | 全文 |

---

## 11. 与相关文档关系

| 文档 | 关系 |
| --- | --- |
| `风险因子设置-草稿.md` | 初稿功能列表 |
| `风险因子设置.png` | 界面原型 |
| 《风险因子设置技术方案》 | 库表、接口、权限标识 |
| 《疫情上报功能需求》等 | 同属「疾病检测与上报」，下游可引用本权重 |