Files

2026-02-28 15:16:15 +08:00

18 KiB

Raw Blame History

业务规则验证

**本文引用的文件** - [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)

简介

本文件聚焦于医院绩效系统的“业务规则验证”能力，系统性梳理并解释以下方面：

考核周期限制、重复数据检查、数据完整性校验与业务冲突处理
规则引擎实现、动态规则配置与扩展机制
异常数据处理策略、错误提示与用户反馈机制
业务规则的自定义配置、规则测试与维护指南

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

项目结构

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

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

图表来源

章节来源

核心组件

考核服务（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）：全局异常处理与日志记录。

章节来源

架构总览

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

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 : "标准化响应"

图表来源

详细组件分析

考核记录业务规则验证

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

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

图表来源

章节来源

绩效计划业务规则验证

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

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

图表来源

章节来源

指标与模板业务规则验证

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

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

图表来源

章节来源

员工业务规则验证

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

章节来源

数据模型与约束

考核记录与明细
- 考核记录：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）

章节来源

规则引擎与动态配置

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

章节来源

异常数据处理与用户反馈

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

章节来源

依赖分析

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

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"]

图表来源

章节来源

性能考虑

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

章节来源

故障排查指南

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

章节来源

结论

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

附录

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

18 KiB Raw Blame History Unescape Escape

业务规则验证

目录

简介

项目结构

核心组件

架构总览

详细组件分析

考核记录业务规则验证

绩效计划业务规则验证

指标与模板业务规则验证

员工业务规则验证

数据模型与约束

规则引擎与动态配置

异常数据处理与用户反馈

依赖分析

性能考虑

故障排查指南

结论

附录

18 KiB

Raw Blame History