提交文件

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,449 @@
+# 业务逻辑设计
+
+<cite>
+**本文档引用的文件**
+- [backend/app/main.py](file://backend/app/main.py)
+- [backend/app/core/config.py](file://backend/app/core/config.py)
+- [backend/app/core/database.py](file://backend/app/core/database.py)
+- [backend/app/core/security.py](file://backend/app/core/security.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/__init__.py](file://backend/app/api/v1/__init__.py)
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py)
+- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py)
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py)
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py)
+- [backend/app/services/template_service.py](file://backend/app/services/template_service.py)
+- [backend/app/services/performance_plan_service.py](file://backend/app/services/performance_plan_service.py)
+</cite>
+
+## 目录
+1. [引言](#引言)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 引言
+
+本文件为医院绩效系统的业务逻辑设计文档，旨在全面阐述系统的业务规则、流程控制、状态转换、权限控制、并发处理和事务管理等核心机制。通过对考核流程、工资计算算法、统计分析逻辑以及权限控制机制的深入解析，帮助开发者和运维人员准确理解系统的设计思路与实现细节，并为后续的功能扩展、性能优化和维护提供指导。
+
+## 项目结构
+
+后端采用 FastAPI + SQLAlchemy 2.0 的异步架构，遵循分层设计模式，主要分为以下层次：
+
+- 应用入口层：负责应用实例创建、中间件配置、路由注册与异常处理
+- API 层：定义 REST 接口，处理请求参数校验与响应封装
+- 服务层：实现业务逻辑，协调数据访问与跨表操作
+- 数据模型层：定义数据库实体与关系映射
+- 核心配置层：提供数据库连接、安全认证、配置管理等基础设施
+
+```mermaid
+graph TB
+subgraph "应用入口层"
+MAIN["main.py<br/>应用实例创建"]
+ROUTER_INIT["api/v1/__init__.py<br/>路由注册"]
+end
+subgraph "API 层"
+ASSESSMENTS_API["assessments.py<br/>考核接口"]
+SALARY_API["salary.py<br/>工资接口"]
+STATS_API["stats.py<br/>统计接口"]
+AUTH_API["auth.py<br/>认证接口"]
+end
+subgraph "服务层"
+ASSESSMENT_SERVICE["assessment_service.py<br/>考核服务"]
+SALARY_SERVICE["salary_service.py<br/>工资服务"]
+STATS_SERVICE["stats_service.py<br/>统计服务"]
+TEMPLATE_SERVICE["template_service.py<br/>模板服务"]
+PLAN_SERVICE["performance_plan_service.py<br/>计划服务"]
+end
+subgraph "数据模型层"
+MODELS["models.py<br/>数据模型"]
+SCHEMAS["schemas.py<br/>数据模式"]
+end
+subgraph "核心配置层"
+CONFIG["config.py<br/>系统配置"]
+DATABASE["database.py<br/>数据库连接"]
+SECURITY["security.py<br/>安全认证"]
+end
+MAIN --> ROUTER_INIT
+ROUTER_INIT --> ASSESSMENTS_API
+ROUTER_INIT --> SALARY_API
+ROUTER_INIT --> STATS_API
+ROUTER_INIT --> AUTH_API
+ASSESSMENTS_API --> ASSESSMENT_SERVICE
+SALARY_API --> SALARY_SERVICE
+STATS_API --> STATS_SERVICE
+ASSESSMENT_SERVICE --> MODELS
+SALARY_SERVICE --> MODELS
+STATS_SERVICE --> MODELS
+TEMPLATE_SERVICE --> MODELS
+PLAN_SERVICE --> MODELS
+MODELS --> DATABASE
+ASSESSMENTS_API --> SECURITY
+SALARY_API --> SECURITY
+STATS_API --> SECURITY
+AUTH_API --> SECURITY
+CONFIG --> DATABASE
+CONFIG --> SECURITY
+```
+
+**图表来源**
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
+- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L1-L156)
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L242)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L1-L260)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
+- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L1-L293)
+- [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/config.py](file://backend/app/core/config.py#L1-L47)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+
+**章节来源**
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
+
+## 核心组件
+
+本节概述系统的核心业务组件及其职责边界：
+
+- 考核管理：支持个人与批量考核创建、状态流转（草稿→提交→审核→确认）、明细评分与加权计算
+- 工资核算：基于考核结果自动计算绩效奖金，支持单条与批量工资生成、确认与批量确认
+- 统计分析：提供 BSC 维度分析、科室与个人排名、趋势分析、指标完成度等多维统计
+- 权限控制：基于 JWT 的用户认证与授权，区分普通员工、管理员与经理权限
+- 模板管理：支持指标模板的创建、维护与关联，支撑不同科室类型的标准化考核
+- 绩效计划：支持医院级、科室级、个人级计划的生命周期管理与审批流程
+
+**章节来源**
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L14-L260)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L16-L300)
+- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L20-L293)
+- [backend/app/services/performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L15-L342)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L110)
+
+## 架构概览
+
+系统采用分层架构，API 层负责请求处理与响应封装，服务层承载业务规则，数据模型层抽象数据库实体，核心配置层提供基础设施能力。数据库连接采用异步 SQLAlchemy，确保高并发场景下的性能表现；安全认证基于 JWT，结合权限装饰器实现细粒度的访问控制。
+
+```mermaid
+graph TB
+CLIENT["客户端"]
+API["API 层<br/>FastAPI 路由"]
+SERVICE["服务层<br/>业务逻辑"]
+MODEL["数据模型层<br/>SQLAlchemy ORM"]
+DB["数据库<br/>PostgreSQL"]
+SEC["安全认证<br/>JWT + 权限"]
+CLIENT --> API
+API --> SEC
+API --> SERVICE
+SERVICE --> MODEL
+MODEL --> DB
+SEC --> DB
+```
+
+**图表来源**
+- [backend/app/main.py](file://backend/app/main.py#L19-L48)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L21-L53)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L10-L20)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
+
+## 详细组件分析
+
+### 考核流程设计
+
+考核流程围绕 Assessment 与 AssessmentDetail 实体展开，支持从草稿到确认的完整闭环。服务层提供创建、更新、提交、审核、确认等操作，并严格控制状态转换合法性。
+
+```mermaid
+stateDiagram-v2
+[*] --> 草稿
+草稿 --> 已提交 : "提交"
+已提交 --> 已审核 : "审核通过"
+已提交 --> 已驳回 : "审核驳回"
+已审核 --> 已确认 : "确认"
+已确认 --> [*]
+已驳回 --> [*]
+```
+
+**图表来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L45-L52)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L158-L206)
+
+关键实现要点：
+- 总分与加权得分计算：遍历明细项累加得分，并乘以对应指标权重得到加权得分
+- 状态校验：仅允许在特定状态下进行状态变更，防止非法状态转换
+- 批量创建：按科室批量生成考核记录，避免重复创建
+
+**章节来源**
+- [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#L110-L156)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L208-L262)
+
+### 工资计算算法
+
+工资计算基于考核结果与员工基本信息，采用固定基数与绩效系数相结合的方式计算绩效奖金，并据此生成最终工资。
+
+```mermaid
+flowchart TD
+Start(["开始"]) --> GetAssessment["获取已确认考核记录"]
+GetAssessment --> CheckExist{"是否存在？"}
+CheckExist --> |否| EndError["结束：无匹配记录"]
+CheckExist --> |是| CalcBonus["计算绩效奖金<br/>奖金 = 基数 × (加权得分/100) × 绩效系数"]
+CalcBonus --> CalcTotal["计算应发工资<br/>应发 = 基本工资 + 绩效奖金 + 补贴 - 扣款"]
+CalcTotal --> CreateRecord["创建工资记录"]
+CreateRecord --> EndSuccess["结束：生成成功"]
+```
+
+**图表来源**
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L127-L190)
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L70-L101)
+
+关键实现要点：
+- 绩效基数为可配置常量，便于统一调整
+- 单次生成时检查是否已存在对应期次的工资记录，避免重复
+- 批量生成支持按科室筛选已确认的考核记录
+
+**章节来源**
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L17-L26)
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L127-L190)
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L192-L219)
+
+### 统计分析逻辑
+
+统计服务提供多维度的分析能力，包括 BSC 维度分析、科室与个人排名、趋势分析、指标完成度等。
+
+```mermaid
+classDiagram
+class StatsService {
+get_bsc_dimension_stats(db, department_id, period_year, period_month) Dict
+get_department_stats(db, period_year, period_month) List
+get_trend_stats(db, department_id, period_year, months) List
+get_ranking_stats(db, period_year, period_month, limit) List
+get_completion_stats(db, indicator_id, period_year, period_month) Dict
+}
+```
+
+**图表来源**
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L16-L300)
+
+关键实现要点：
+- BSC 维度分析：按平衡计分卡四个维度聚合得分与权重，计算平均分
+- 科室统计：按科室汇总员工数量、总分、平均分、最高/最低分
+- 趋势分析：支持跨月度的趋势统计，考虑跨年场景
+- 排名统计：支持个人与科室的加权得分排名
+- 指标完成度：计算指标平均得分与目标值的完成率
+
+**章节来源**
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L19-L72)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L74-L146)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L148-L199)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L201-L244)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L246-L299)
+
+### 权限控制机制
+
+系统采用基于 JWT 的认证与授权机制，结合 FastAPI 的依赖注入实现细粒度的权限控制。
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant AuthAPI as "认证接口"
+participant Security as "安全模块"
+participant DB as "数据库"
+Client->>AuthAPI : POST /api/v1/auth/login
+AuthAPI->>Security : 验证用户名与密码
+Security->>DB : 查询用户信息
+DB-->>Security : 用户记录
+Security-->>AuthAPI : 生成访问令牌
+AuthAPI-->>Client : 返回令牌
+Client->>ProtectedAPI : 请求受保护资源
+ProtectedAPI->>Security : 解析与验证令牌
+Security-->>ProtectedAPI : 当前用户信息
+ProtectedAPI-->>Client : 返回业务数据
+```
+
+**图表来源**
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L82)
+
+关键实现要点：
+- 登录接口：校验用户名与密码，返回 JWT 令牌
+- 当前用户：从令牌解析用户 ID，查询数据库获取用户对象
+- 权限装饰器：提供获取激活用户、管理员与经理用户的依赖函数
+- 角色区分：普通员工、管理员、经理，不同操作需要不同权限级别
+
+**章节来源**
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L110)
+
+### 并发处理与事务管理
+
+系统采用异步 SQLAlchemy 连接池与依赖注入的会话管理，确保事务的正确提交与回滚。
+
+```mermaid
+flowchart TD
+Start(["请求进入"]) --> GetSession["获取异步会话"]
+GetSession --> ExecuteOps["执行数据库操作"]
+ExecuteOps --> CommitOrRollback{"操作成功？"}
+CommitOrRollback --> |是| Commit["提交事务"]
+CommitOrRollback --> |否| Rollback["回滚事务"]
+Commit --> CloseSession["关闭会话"]
+Rollback --> CloseSession
+CloseSession --> End(["请求结束"])
+```
+
+**图表来源**
+- [backend/app/core/database.py](file://backend/app/core/database.py#L28-L39)
+
+关键实现要点：
+- 会话工厂：配置异步引擎与会话参数，开启自动提交与回滚
+- 依赖注入：在每个请求中创建独立会话，确保线程安全
+- 异常处理：捕获异常并执行回滚，防止脏数据
+
+**章节来源**
+- [backend/app/core/database.py](file://backend/app/core/database.py#L28-L39)
+
+### 业务规则验证与状态转换
+
+业务规则通过服务层的状态校验与数据约束共同实现，确保流程的合规性与数据一致性。
+
+```mermaid
+flowchart TD
+Entry(["业务操作入口"]) --> ValidateInput["校验输入参数"]
+ValidateInput --> CheckStatus["检查当前状态"]
+CheckStatus --> StatusOK{"状态允许？"}
+StatusOK --> |否| Reject["拒绝操作并返回错误"]
+StatusOK --> |是| ApplyRule["应用业务规则"]
+ApplyRule --> Persist["持久化数据"]
+Persist --> UpdateState["更新状态"]
+UpdateState --> Success["返回成功响应"]
+Reject --> End(["结束"])
+Success --> End
+```
+
+**图表来源**
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L117-L118)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L176-L177)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L198-L199)
+
+关键实现要点：
+- 状态转换：仅在合法状态下允许下一步操作
+- 参数校验：对关键字段进行范围与格式校验
+- 数据一致性：通过事务保证多表写入的一致性
+
+**章节来源**
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L110-L156)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L158-L206)
+
+### 扩展点与自定义配置
+
+系统提供了丰富的扩展点与配置项，便于根据医院实际需求进行定制：
+
+- 配置扩展：数据库连接池大小、JWT 过期时间、分页参数等
+- 工资算法扩展：通过调整绩效基数与系数实现不同的激励策略
+- 统计维度扩展：新增统计指标与分析维度
+- 权限扩展：新增角色与权限标识，配合前端菜单控制
+
+**章节来源**
+- [backend/app/core/config.py](file://backend/app/core/config.py#L12-L33)
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L17-L18)
+
+## 依赖关系分析
+
+系统各层之间的依赖关系清晰，API 层依赖服务层，服务层依赖数据模型层，核心配置层为底层基础设施。
+
+```mermaid
+graph TB
+API_ASSESS["API: 考核接口"] --> SVC_ASSESS["服务: 考核服务"]
+API_SALARY["API: 工资接口"] --> SVC_SALARY["服务: 工资服务"]
+API_STATS["API: 统计接口"] --> SVC_STATS["服务: 统计服务"]
+API_AUTH["API: 认证接口"] --> SEC["安全模块"]
+SVC_ASSESS --> MODELS["数据模型"]
+SVC_SALARY --> MODELS
+SVC_STATS --> MODELS
+MODELS --> DB["数据库连接"]
+SEC --> DB
+```
+
+**图表来源**
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
+- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L1-L156)
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L242)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L1-L260)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
+
+**章节来源**
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
+- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L1-L156)
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L242)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L1-L260)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
+
+## 性能考虑
+
+- 异步 I/O：采用 SQLAlchemy 2.0 异步引擎与会话，提升高并发场景下的吞吐量
+- 连接池配置：通过配置文件调整连接池大小与溢出数量，平衡内存与性能
+- 查询优化：服务层使用 selectinload 进行关联加载，减少 N+1 查询问题
+- 分页与索引：API 层支持分页，模型层为常用查询字段建立索引，提升查询效率
+- 缓存策略：建议在统计分析层引入 Redis 缓存热点数据，降低数据库压力
+
+[本节为通用性能建议，不涉及具体文件分析]
+
+## 故障排除指南
+
+常见问题与排查步骤：
+- 认证失败：检查用户名与密码是否正确，确认用户状态为激活
+- 权限不足：确认当前用户角色是否满足操作要求（管理员/经理）
+- 状态转换错误：检查当前记录状态是否允许进行下一步操作
+- 数据库异常：查看日志文件，确认连接池配置与事务提交/回滚是否正常
+
+**章节来源**
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L30-L34)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L94-L109)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L117-L118)
+- [backend/app/core/database.py](file://backend/app/core/database.py#L34-L36)
+
+## 结论
+
+本系统通过清晰的分层架构与严格的业务规则实现了医院绩效管理的全流程自动化，涵盖考核、工资、统计与权限控制等核心功能。服务层的状态机设计与事务管理确保了业务流程的合规性与数据一致性，异步数据库连接提升了系统在高并发场景下的稳定性。未来可在统计分析与缓存策略方面进一步优化，以满足更大规模的应用需求。
+
+[本节为总结性内容，不涉及具体文件分析]
+
+## 附录
+
+- 数据模型概览：涵盖科室、员工、指标、考核、工资、计划、模板、菜单等核心实体
+- API 接口清单：提供各模块的 REST 接口说明与权限要求
+- 配置参数说明：数据库连接、JWT、分页等系统配置项
+
+**章节来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L438)
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L20-L166)
+- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L20-L156)
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L17-L242)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L74)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L12-L33)