提交文件

2026-02-28 15:16:15 +08:00
parent 1a4e50e0a4
commit 44f250f58e
159 changed files with 61268 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/业务逻辑设计/业务规则验证.md
+++ b/.qoder/repowiki/zh/content/业务逻辑设计/业务规则验证.md
@@ -0,0 +1,384 @@
+# 业务规则验证
+
+<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 模式与数据库约束同步，避免运行时异常