# 业务规则验证

<cite>
**本文引用的文件**
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py)
- [backend/app/services/performance_plan_service.py](file://backend/app/services/performance_plan_service.py)
- [backend/app/models/models.py](file://backend/app/models/models.py)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py)
- [backend/app/core/security.py](file://backend/app/core/security.py)
- [backend/app/main.py](file://backend/app/main.py)
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py)
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py)
- [AGENTS.md](file://AGENTS.md)
- [docs/frontend.md](file://docs/frontend.md)
- [frontend/DEBUG_GUIDE.md](file://frontend/DEBUG_GUIDE.md)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件聚焦于医院绩效系统的“业务规则验证”能力，系统性梳理并解释以下方面：
- 考核周期限制、重复数据检查、数据完整性校验与业务冲突处理
- 规则引擎实现、动态规则配置与扩展机制
- 异常数据处理策略、错误提示与用户反馈机制
- 业务规则的自定义配置、规则测试与维护指南

系统采用 FastAPI + SQLAlchemy 的后端架构，结合 Pydantic 数据模式进行输入输出校验；数据库层面通过索引与约束保证数据一致性；API 层对业务状态流转进行严格控制；前端通过统一错误处理与消息提示提升用户体验。

## 项目结构
后端采用分层架构：API 路由层负责请求接入与权限控制，服务层封装业务规则与状态机，模型层定义数据结构与约束，模式层定义输入输出结构。

```mermaid
graph TB
subgraph "API 层"
A1["/assessments<br/>考核管理"]
A2["/indicators<br/>指标管理"]
A3["/staff<br/>员工管理"]
end
subgraph "服务层"
S1["AssessmentService<br/>考核服务"]
S2["PerformancePlanService<br/>绩效计划服务"]
S3["IndicatorService<br/>指标服务"]
S4["StaffService<br/>员工服务"]
end
subgraph "模型层"
M1["Assessment<br/>考核记录"]
M2["AssessmentDetail<br/>考核明细"]
M3["Indicator<br/>考核指标"]
M4["Staff<br/>员工"]
M5["PerformancePlan<br/>绩效计划"]
end
subgraph "模式层"
P1["AssessmentCreate/Update/Response"]
P2["IndicatorCreate/Update/Response"]
P3["StaffCreate/Update/Response"]
end
A1 --> S1
A2 --> S3
A3 --> S4
S1 --> M1
S1 --> M2
S1 --> M3
S2 --> M5
S3 --> M3
S4 --> M4
S1 --> P1
S3 --> P2
S4 --> P3
```

图表来源
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L1-L124)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [backend/app/services/performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L1-L342)
- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L203)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L194-L311)

章节来源
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L1-L124)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [backend/app/services/performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L1-L342)
- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L203)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L194-L311)

## 核心组件
- 考核服务（AssessmentService）：实现考核记录的创建、更新、提交、审核、确认与批量创建；内置状态机与关键业务约束（如草稿/已提交/已审核/已确认状态流转限制、重复考核记录检查）。
- 绩效计划服务（PerformancePlanService）：实现计划的创建、提交、审批、激活与统计；支持 KPI 关联的增删改查。
- 指标服务（IndicatorService）：实现指标的 CRUD、模板导入与去重策略。
- 员工服务（StaffService）：实现员工的 CRUD、按科室检索与关键字搜索。
- 数据模型（models.py）：定义实体、枚举、索引与约束（如权重>0、唯一索引、外键关系）。
- 数据模式（schemas.py）：定义输入输出结构与 Pydantic 校验规则（范围、长度、枚举、必填等）。
- API 路由（assessments.py、indicators.py、staff.py）：暴露 REST 接口，集成权限依赖与错误处理。
- 安全模块（security.py）：JWT 解析、用户鉴权与角色权限控制。
- 主程序（main.py）：全局异常处理与日志记录。

章节来源
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
- [backend/app/services/performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L15-L342)
- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L203)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L194-L311)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L1-L124)
- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L110)
- [backend/app/main.py](file://backend/app/main.py#L58-L75)

## 架构总览
系统通过 API 路由接收请求，经由安全中间件与权限依赖进行身份与角色校验，随后调用对应服务层执行业务规则与状态机控制，最终持久化到数据库并通过模式层进行序列化返回。

```mermaid
sequenceDiagram
participant FE as "前端"
participant API as "API 路由"
participant SEC as "安全模块"
participant SVC as "服务层"
participant DB as "数据库"
FE->>API : "提交请求"
API->>SEC : "解析JWT/校验权限"
SEC-->>API : "返回当前用户"
API->>SVC : "调用业务方法"
SVC->>DB : "读写数据/执行约束"
DB-->>SVC : "返回结果"
SVC-->>API : "返回领域对象"
API-->>FE : "标准化响应"
```

图表来源
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L110)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L178)

## 详细组件分析

### 考核记录业务规则验证
- 状态机与流转控制
  - 草稿（draft）→ 提交（submitted）→ 审核（reviewed/rejected）→ 确认（finalized）
  - 仅允许特定状态下的操作，防止逆向或越权变更
- 重复数据检查
  - 批量创建时按“员工+年度+月份”组合检查是否存在重复记录
- 总分与加权得分计算
  - 总分：明细得分求和
  - 加权得分：明细得分×指标权重求和
- 明细完整性
  - 每条明细包含指标ID、实际值、得分、佐证材料、备注等字段

```mermaid
stateDiagram-v2
[*] --> 草稿
草稿 --> 已提交 : "提交"
已提交 --> 已审核 : "审核通过"
已提交 --> 已驳回 : "审核不通过"
已审核 --> 已确认 : "确认"
已确认 --> [*]
已驳回 --> [*]
```

图表来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L45-L51)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L158-L205)

章节来源
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L208-L262)
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L178)

### 绩效计划业务规则验证
- 计划状态机
  - 草稿（draft）→ 待审批（pending）→ 批准（approved）→ 执行中（active）→ 完成（completed）
- 审批与版本
  - 审批通过/拒绝时记录审批人、审批时间与意见
  - 激活后标记为生效
- KPI 关联管理
  - 支持增删改查 KPI 关联，包含目标值、权重、评分方法与参数

```mermaid
flowchart TD
Start(["创建计划"]) --> Draft["保存为草稿"]
Draft --> Pending["提交审批"]
Pending --> Approved{"审批通过?"}
Approved --> |是| Active["激活执行"]
Approved --> |否| Rejected["标记为已驳回"]
Active --> Completed["完成"]
Rejected --> End(["结束"])
Completed --> End
```

图表来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L270-L296)
- [backend/app/services/performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L130-L182)
- [backend/app/services/performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L195-L249)

章节来源
- [backend/app/services/performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L15-L342)
- [backend/app/models/models.py](file://backend/app/models/models.py#L270-L338)

### 指标与模板业务规则验证
- 指标唯一性
  - 指标编码唯一，创建前需检查重复
- 权重约束
  - 指标权重>0，数据库层通过 CheckConstraint 保证
- 模板导入
  - 支持覆盖或跳过已存在指标，避免重复创建
- 适用科室类型
  - 指标可标注适用科室类型集合（JSON 字符串），用于筛选与过滤

```mermaid
flowchart TD
Import["导入模板"] --> CheckCode["按编码检查是否已存在"]
CheckCode --> Exists{"已存在?"}
Exists --> |是且覆盖| Update["更新现有指标"]
Exists --> |是且不覆盖| Skip["跳过该指标"]
Exists --> |否| Create["创建新指标"]
Update --> Done["提交事务"]
Skip --> Done
Create --> Done
```

图表来源
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L128-L141)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L106-L154)
- [backend/app/models/models.py](file://backend/app/models/models.py#L143-L146)

章节来源
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L71-L112)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L67-L104)
- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L146)

### 员工业务规则验证
- 工号唯一性
  - 创建时检查工号是否已存在
- 关键字搜索
  - 支持姓名或工号模糊匹配
- 状态与部门过滤
  - 支持按部门与状态筛选

章节来源
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L68-L108)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L69-L112)

### 数据模型与约束
- 考核记录与明细
  - 考核记录：staff_id、period_year、period_month、status、assessor_id、reviewer_id 等
  - 明细：assessment_id、indicator_id、actual_value、score、evidence、remark
  - 索引：staff、period_year+month、status
- 指标
  - code 唯一；weight>0；bs_dimension、target_unit、assessment_method、deduction_standard、data_source、applicable_dept_types、is_veto
- 模板与关联
  - 模板：template_code 唯一；模板指标关联唯一约束（template_id, indicator_id）

章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L203)
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L87-L131)
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L21-L63)

### 规则引擎与动态配置
- 当前实现
  - 业务规则主要以内置服务方法与状态机形式实现，例如：状态流转限制、重复记录检查、权重>0 约束等
- 动态规则配置建议
  - 可引入“规则配置表”，存储规则表达式（如 JSON/脚本片段），在服务层按配置动态执行
  - 对于“一票否决”等强约束，可在模型层增加布尔标志并在服务层强制执行
- 扩展机制
  - 通过插件化或策略模式扩展不同科室类型的评分策略
  - 为 KPI 关联增加“评分参数（JSON）”字段，支持动态参数化评分

章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L133-L136)
- [backend/app/models/models.py](file://backend/app/models/models.py#L314-L338)
- [backend/app/services/performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L195-L249)

### 异常数据处理与用户反馈
- 后端异常处理
  - HTTP 异常与校验异常分别捕获并记录日志，保持接口稳定性
- 前端错误处理
  - 统一使用 Element Plus 的消息与确认框，区分成功/警告/错误场景
- 错误提示
  - 员工不存在、工号已存在、指标编码已存在、状态不允许等明确提示

章节来源
- [backend/app/main.py](file://backend/app/main.py#L58-L75)
- [AGENTS.md](file://AGENTS.md#L112-L134)
- [docs/frontend.md](file://docs/frontend.md#L291-L325)

## 依赖分析
- API 依赖安全模块进行用户鉴权与角色校验
- 服务层依赖模型层进行数据读写与约束校验
- 模式层为 API 与服务层提供输入输出结构与 Pydantic 校验
- 数据库迁移脚本定义表结构、索引与约束

```mermaid
graph LR
API_A["/assessments"] --> SEC["security.py"]
API_I["/indicators"] --> SEC
API_S["/staff"] --> SEC
SEC --> SVC_A["AssessmentService"]
SEC --> SVC_P["PerformancePlanService"]
SEC --> SVC_I["IndicatorService"]
SEC --> SVC_S["StaffService"]
SVC_A --> MODELS["models.py"]
SVC_P --> MODELS
SVC_I --> MODELS
SVC_S --> MODELS
MODELS --> SCHEMAS["schemas.py"]
```

图表来源
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L1-L124)
- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L110)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [backend/app/services/performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L1-L342)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L1-L743)

章节来源
- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L110)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [backend/app/services/performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L1-L342)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L1-L743)

## 性能考虑
- 查询优化
  - 使用 selectinload 预加载关联对象，减少 N+1 查询
  - 为高频查询字段建立索引（如 staff_id、period_year+month、status）
- 分页与总数统计
  - 使用子查询统计总数，避免重复扫描
- 并发与事务
  - 批量创建时使用 flush/commit 控制事务边界，确保一致性
- 缓存与热点
  - 对常用指标与模板可引入缓存层，降低数据库压力

章节来源
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L28-L55)
- [backend/app/services/performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L28-L59)
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L110-L112)

## 故障排查指南
- 后端健康检查
  - 访问 /health 确认服务可用
- 日志定位
  - 查看后端日志目录中的 app_*.log 与 error_*.log
- 常见问题
  - 404：检查路由前缀与接口路径
  - 500：查看后端异常堆栈与数据库约束冲突
  - CORS：确认前端代理与后端 CORS 配置一致
- 前端调试
  - 使用浏览器开发者工具查看 Console 与 Network 标签，确认请求头与响应体

章节来源
- [backend/app/main.py](file://backend/app/main.py#L54-L56)
- [frontend/DEBUG_GUIDE.md](file://frontend/DEBUG_GUIDE.md#L1-L60)

## 结论
系统在业务规则验证方面具备完善的层次化实现：API 层进行权限与输入校验，服务层执行状态机与关键约束，模型层通过索引与约束保障数据完整性。对于动态规则与扩展需求，建议引入规则配置表与参数化评分机制，以增强灵活性与可维护性。

## 附录
- 自定义配置建议
  - 新增“规则配置表”，支持按科室类型/指标类型配置评分策略
  - 为 KPI 关联增加“评分参数（JSON）”字段，支持动态参数化
- 规则测试
  - 单元测试覆盖状态机边界条件（草稿→提交→审核→确认）
  - 集成测试覆盖重复数据检查与约束触发场景
- 维护指南
  - 通过 Alembic 迁移管理数据库结构演进
  - 保持 Pydantic 模式与数据库约束同步，避免运行时异常