chenqi/hospital_performance
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

提交文件

Browse Source
This commit is contained in:
chenqi
2026-02-28 15:16:15 +08:00
parent 1a4e50e0a4
commit 44f250f58e
159 changed files with 61268 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

350
.qoder/repowiki/zh/content/后端开发指南/服务层开发/工资服务.md Normal file
View File

@@ -0,0 +1,350 @@
# 工资服务
<cite>
**本文引用的文件**
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py)
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.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/services/assessment_service.py](file://backend/app/services/assessment_service.py)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py)
- [backend/app/core/database.py](file://backend/app/core/database.py)
- [backend/app/core/config.py](file://backend/app/core/config.py)
- [backend/init_db.py](file://backend/init_db.py)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [组件详解](#组件详解)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件面向“工资服务”的开发与维护，围绕 SalaryService 类的实现架构展开，系统性阐述以下内容：
- 绩效奖金计算算法：基础工资、绩效系数、考核等级对应的奖金计算逻辑
- 工资记录的数据结构、字段含义与业务规则
- 批量生成工资记录的机制：按月度、季度或年度的计算流程
- 与考核服务、员工服务的集成关系与数据一致性保障
- 异常处理、事务管理与性能优化策略
- 实际计算示例与边界条件处理
## 项目结构
后端采用分层架构：API 层负责路由与鉴权，Service 层封装业务逻辑，Model 层定义数据模型，Schema 层定义输入输出结构。工资服务位于 Service 层，与考核服务、员工服务协作，最终落库到 SalaryRecord。
```mermaid
graph TB
API["API 路由<br/>salary.py"] --> SVC["服务层<br/>salary_service.py"]
SVC --> MODEL["模型层<br/>models.py 中的 SalaryRecord/Assessment/Staff"]
SVC --> SCHEMA["Schema 定义<br/>schemas.py"]
SVC --> ASSESS_SVC["考核服务<br/>assessment_service.py"]
SVC --> STAFF_SVC["员工服务<br/>staff_service.py"]
SVC --> DB["数据库连接<br/>database.py"]
DB --> CONF["配置<br/>config.py"]
```
图表来源
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L1-L156)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L1-L260)
- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L230)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L272-L313)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
章节来源
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L1-L156)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L1-L260)
- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L230)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L272-L313)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
## 核心组件
- 工资服务（SalaryService）：提供查询、创建、更新、生成、确认、批量生成与批量确认等能力；核心算法集中在绩效奖金计算与总工资汇总。
- 工资记录模型（SalaryRecord）：持久化存储工资条目，包含基础工资、绩效得分、绩效奖金、扣款、补贴、应发工资、状态等字段。
- 考核服务（AssessmentService）：提供考核的创建、提交、审核、确认等流程，为工资生成提供“已确认”的考核数据。
- 员工服务（StaffService）：提供员工信息查询与维护，为工资生成提供基础工资与绩效系数。
- API 路由（salary.py）：对外暴露查询、生成、确认、批量生成与批量确认等接口，并进行权限校验。
章节来源
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L14-L260)
- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L230)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L1-L156)
## 架构总览
工资服务的调用链路如下：前端请求经 API 路由进入，由 SalaryService 执行业务逻辑；若需要从考核生成，则联动 AssessmentService 与 StaffService；最终写入数据库并返回结果。
```mermaid
sequenceDiagram
participant FE as "前端"
participant API as "API 路由<br/>salary.py"
participant SVC as "服务层<br/>salary_service.py"
participant ASSESS as "考核服务<br/>assessment_service.py"
participant STAFF as "员工服务<br/>staff_service.py"
participant DB as "数据库"
FE->>API : "POST /salary/generate"
API->>SVC : "generate_from_assessment(staff_id, year, month)"
SVC->>DB : "查询员工信息"
DB-->>SVC : "Staff"
SVC->>DB : "查询已确认考核"
DB-->>SVC : "Assessment(finalized)"
SVC->>SVC : "calculate_performance_bonus()"
SVC->>DB : "插入 SalaryRecord"
DB-->>SVC : "返回新记录"
SVC-->>API : "返回记录ID"
API-->>FE : "生成成功"
```
图表来源
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L96-L110)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L127-L190)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L195-L205)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L52-L59)
## 组件详解
### 工资记录数据模型与字段语义
- 表名：salary_records
- 字段与含义（节选）：
- staff_id：员工ID
- period_year / period_month：所属周期（年/月）
- base_salary：基本工资
- performance_score：绩效得分
- performance_bonus：绩效奖金
- allowance：补贴
- deduction：扣款
- total_salary：应发工资（base_salary + performance_bonus + allowance - deduction）
- status：状态（默认 pending，支持 confirmed）
- remark：备注
- created_at / updated_at：创建与更新时间
业务规则：
- 总工资由服务层在创建/更新时计算并入库
- 状态仅允许在“pending”状态下进行更新与确认
- 生成工资记录前需确保同一员工当月无重复记录
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L230)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L272-L313)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L77-L124)
### 绩效奖金计算算法
- 奖金基数：PERFORMANCE_BASE（静态常量）
- 计算公式：奖金 = 奖金基数 × (绩效得分/100) × 员工绩效系数
- 输入来源：
- 绩效得分：来自已确认的 Assessment.weighted_score
- 绩效系数：来自 Staff.performance_ratio
- 输出：performance_bonus，用于后续总工资计算
```mermaid
flowchart TD
Start(["开始"]) --> LoadAssess["加载已确认考核<br/>Assessment.finalized"]
LoadAssess --> LoadStaff["加载员工信息<br/>Staff.performance_ratio"]
LoadStaff --> CalcBonus["计算奖金<br/>奖金 = 奖金基数 × 得分/100 × 系数"]
CalcBonus --> SumTotal["汇总总工资<br/>总工资 = 基本工资 + 奖金 + 补贴 - 扣款"]
SumTotal --> Persist["持久化 SalaryRecord"]
Persist --> End(["结束"])
```
图表来源
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L71-L74)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L167-L170)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L173-L186)
章节来源
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L17-L18)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L71-L74)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L167-L170)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L173-L186)
### 工资记录生成与批量处理机制
- 单条生成：generate_from_assessment
- 校验员工存在
- 查询当期“已确认”的 Assessment
- 检查是否存在重复工资记录
- 计算奖金与总工资
- 插入 SalaryRecord（状态 pending）
- 批量生成：batch_generate_for_department
- 基于部门与周期，查询所有“已确认”的 Assessment
- 对每个评估逐条调用单条生成
- 批量确认：batch_confirm
- 按年/月筛选 pending 状态的记录
- 可选按部门过滤
- 将状态置为 confirmed 并返回确认数量
```mermaid
sequenceDiagram
participant API as "API 路由"
participant SVC as "SalaryService"
participant DB as "数据库"
API->>SVC : "batch_generate_for_department(dept_id, year, month)"
SVC->>DB : "查询已确认考核(按部门+周期)"
DB-->>SVC : "Assessments 列表"
loop 遍历每个 Assessment
SVC->>SVC : "generate_from_assessment()"
SVC->>DB : "插入 SalaryRecord"
end
SVC-->>API : "返回生成的记录列表"
```
图表来源
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L113-L129)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L193-L219)
章节来源
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L96-L129)
- [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#L193-L219)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L234-L259)
### 与考核服务、员工服务的集成关系
- 与考核服务（AssessmentService）：
- 生成工资记录的前提是存在“已确认”的 Assessment
- 通过 Assessment.status == "finalized" 进行筛选
- 与员工服务（StaffService）：
- 读取员工的基础工资与绩效系数
- 作为奖金计算的输入参数
- 数据一致性：
- 生成前检查重复记录，避免重复发薪
- 仅对 pending 状态的记录允许更新与确认
章节来源
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L134-L153)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L195-L205)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L52-L59)
### API 接口与权限控制
- 查询列表与详情：普通用户可访问
- 创建、更新、单条生成、确认：需要管理员或经理权限
- 批量生成、批量确认：需要管理员或经理权限
- 返回格式遵循统一响应结构（code/message/data）
章节来源
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L20-L156)
## 依赖关系分析
- SalaryService 依赖：
- SQLAlchemy 异步会话（AsyncSession）
- 模型：SalaryRecord、Staff、Assessment
- Schema：SalaryRecordCreate、SalaryRecordUpdate
- 服务：AssessmentService、StaffService
- 外部依赖：
- 数据库连接与事务管理（database.py）
- 应用配置（config.py）
```mermaid
classDiagram
class SalaryService {
+get_list(...)
+get_by_id(...)
+create(...)
+update(...)
+calculate_performance_bonus(...)
+generate_from_assessment(...)
+batch_generate_for_department(...)
+confirm(...)
+batch_confirm(...)
}
class AssessmentService {
+get_by_id(...)
+finalize(...)
}
class StaffService {
+get_by_id(...)
}
class SalaryRecord
class Staff
class Assessment
SalaryService --> AssessmentService : "查询已确认考核"
SalaryService --> StaffService : "读取员工信息"
SalaryService --> SalaryRecord : "创建/更新"
SalaryService --> Staff : "读取基础工资/系数"
SalaryService --> Assessment : "读取加权得分"
```
图表来源
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L14-L260)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L230)
章节来源
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L1-L260)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L230)
## 性能考量
- 数据库连接池与并发：
- 配置文件提供数据库连接池大小与溢出参数，建议结合业务峰值合理设置
- 查询优化：
- SalaryRecord 与 Assessment 均具备按 staff_id、period、status 的索引，有利于分页与筛选
- 批量生成时建议按部门分批处理，避免一次性加载过多记录
- 事务与回滚：
- 数据库会话在异常时自动回滚，确保数据一致性
- I/O 与序列化：
- API 层对响应进行统一包装，注意避免在高频接口中进行大量对象转换
章节来源
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L26)
- [backend/app/core/database.py](file://backend/app/core/database.py#L10-L20)
- [backend/app/models/models.py](file://backend/app/models/models.py#L227-L230)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L193-L219)
## 故障排查指南
- 无法生成工资记录
- 检查是否存在“已确认”的 Assessment
- 检查是否已存在同员工/同周期的工资记录
- 检查员工是否存在且基础工资/绩效系数有效
- 更新失败
- 仅允许对状态为“pending”的记录进行更新
- 确认失败
- 仅允许对状态为“pending”的记录进行确认
- 批量生成/确认
- 确认年/月参数正确
- 如指定部门，确认部门ID有效
- 数据库异常
- 查看会话依赖的回滚逻辑是否触发
- 检查连接池配置与数据库可用性
章节来源
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L104-L124)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L222-L231)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L234-L259)
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L96-L156)
- [backend/app/core/database.py](file://backend/app/core/database.py#L28-L39)
## 结论
SalaryService 提供了完整的工资核算闭环：从“已确认”的考核数据出发，结合员工基础信息，计算绩效奖金并生成工资记录；支持单条与批量生成、单条与批量确认，并通过严格的权限控制与状态约束保障业务正确性。配合合理的数据库索引与连接池配置，可在高并发场景下保持稳定与高效。
## 附录
### 实际计算示例与边界条件
- 示例场景
- 员工基础工资：10000，绩效系数：1.2
- 考核加权得分：90
- 奖金基数：3000
- 计算过程：奖金 = 3000 × (90/100) × 1.2；总工资 = 基础工资 + 奖金 + 补贴 - 扣款
- 边界条件
- 绩效得分/系数为 0：奖金为 0
- 补贴/扣款为负：不合法，应在输入层约束
- 已存在同周期记录：拒绝重复生成
- 非“已确认”考核：拒绝生成
- 非“pending”状态：拒绝更新/确认
章节来源
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L17-L18)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L71-L74)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L127-L190)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L272-L313)

546
.qoder/repowiki/zh/content/后端开发指南/服务层开发/指标模板服务.md Normal file
View File

@@ -0,0 +1,546 @@
# 指标模板服务
<cite>
**本文档引用的文件**
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py)
- [backend/app/services/template_service.py](file://backend/app/services/template_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/indicators.py](file://backend/app/api/v1/indicators.py)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py)
- [backend/app/scripts/init_templates.py](file://backend/app/scripts/init_templates.py)
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py)
- [backend/app/core/config.py](file://backend/app/core/config.py)
- [backend/app/main.py](file://backend/app/main.py)
- [docs/详细设计.md](file://docs/详细设计.md)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 简介
本文档详细阐述了医院绩效管理系统中的指标模板服务，重点分析了IndicatorService和TemplateService两个核心服务的实现细节。系统基于平衡计分卡理论，实现了完整的考核指标管理和模板管理功能，包括指标类型定义、权重设置、评分标准配置、BSC维度关联等。
系统采用FastAPI + SQLAlchemy 2.0 + PostgreSQL的技术栈，支持异步IO操作，具备良好的扩展性和性能表现。通过标准化的API接口和数据模型设计，为医院绩效管理提供了完整的技术解决方案。
## 项目结构
后端项目采用典型的分层架构设计：
```mermaid
graph TB
subgraph "表现层"
Frontend[前端应用]
end
subgraph "应用层"
API[API路由层]
Services[服务层]
end
subgraph "数据层"
Models[数据模型]
Schemas[数据模式]
Database[(PostgreSQL数据库)]
end
Frontend --> API
API --> Services
Services --> Models
Models --> Database
Schemas --> API
```
**图表来源**
- [backend/app/main.py](file://backend/app/main.py#L15-L77)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L1-L272)
**章节来源**
- [backend/app/main.py](file://backend/app/main.py#L15-L77)
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
## 核心组件
### 指标服务 (IndicatorService)
IndicatorService负责考核指标的全生命周期管理，包括查询、创建、更新、删除和模板导入等功能。
**主要功能特性：**
- 多条件查询和分页支持
- 指标模板导入和覆盖机制
- 激活指标的快速获取
- 完整的CRUD操作支持
### 模板服务 (TemplateService)
TemplateService专注于指标模板的管理，支持模板的创建、关联、更新和删除操作。
**核心能力：**
- 模板列表查询和类型过滤
- 模板指标的增删改查
- 模板类型和维度标签映射
- 批量指标添加功能
**章节来源**
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L13-L197)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L20-L293)
## 架构概览
系统采用分层架构，清晰分离了表现层、应用层、服务层和数据层：
```mermaid
graph TB
subgraph "表现层"
UI[Web界面]
Mobile[移动端应用]
end
subgraph "应用层"
Auth[认证中间件]
Validation[数据验证]
Logging[日志记录]
end
subgraph "服务层"
IndicatorSvc[指标服务]
TemplateSvc[模板服务]
AssessmentSvc[考核服务]
FinanceSvc[财务服务]
end
subgraph "数据层"
IndicatorModel[指标模型]
TemplateModel[模板模型]
AssessmentModel[考核模型]
UserModel[用户模型]
end
UI --> Auth
Mobile --> Auth
Auth --> Validation
Validation --> IndicatorSvc
Validation --> TemplateSvc
IndicatorSvc --> IndicatorModel
TemplateSvc --> TemplateModel
AssessmentSvc --> AssessmentModel
IndicatorModel --> UserModel
TemplateModel --> UserModel
```
**图表来源**
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L1-L272)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L13-L197)
## 详细组件分析
### 数据模型设计
系统采用SQLAlchemy ORM进行数据建模，建立了完整的指标和模板数据结构：
```mermaid
classDiagram
class Indicator {
+int id
+string code
+string name
+IndicatorType indicator_type
+BSCDimension bs_dimension
+float weight
+float max_score
+float target_value
+string target_unit
+string calculation_method
+string assessment_method
+string deduction_standard
+string data_source
+string applicable_dept_types
+bool is_veto
+bool is_active
+datetime created_at
+datetime updated_at
}
class IndicatorTemplate {
+int id
+string template_code
+string template_name
+TemplateType template_type
+string description
+string dimension_weights
+string assessment_cycle
+bool is_active
+datetime created_at
+datetime updated_at
}
class TemplateIndicator {
+int id
+int template_id
+int indicator_id
+string category
+float target_value
+string target_unit
+float weight
+string scoring_method
+string scoring_params
+int sort_order
+string remark
+datetime created_at
+datetime updated_at
}
IndicatorTemplate "1" -- "many" TemplateIndicator : "包含"
Indicator "many" -- "one" TemplateIndicator : "被关联"
```
**图表来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L147)
- [backend/app/models/models.py](file://backend/app/models/models.py#L387-L404)
- [backend/app/models/models.py](file://backend/app/models/models.py#L411-L432)
#### 指标类型枚举
系统定义了完整的指标类型体系，支持多种考核维度：
| 指标类型 | 描述 | 示例 |
|---------|------|------|
| quality | 质量指标 | 病历甲级率、院感发生率 |
| quantity | 数量指标 | 手术台次、门诊量 |
| efficiency | 效率指标 | 平均住院日、床位使用率 |
| service | 服务指标 | 满意度得分、投诉次数 |
| cost | 成本指标 | 药品比例、材料消耗 |
#### BSC维度配置
平衡计分卡四个维度的权重分配策略：
| 维度 | 编码 | 中文名称 | 典型权重范围 |
|------|------|----------|-------------|
| financial | financial | 财务管理 | 20%-40% |
| customer | customer | 顾客服务 | 25%-35% |
| internal_process | internal_process | 内部流程 | 20%-30% |
| learning_growth | learning_growth | 学习与成长 | 5%-15% |
**章节来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L54-L61)
- [backend/app/models/models.py](file://backend/app/models/models.py#L29-L35)
### API接口设计
系统提供RESTful API接口，支持完整的指标和模板管理操作：
```mermaid
sequenceDiagram
participant Client as 客户端
participant API as API接口
participant Service as 服务层
participant Model as 数据模型
participant DB as 数据库
Client->>API : GET /api/v1/indicators
API->>Service : get_list()
Service->>Model : 查询指标
Model->>DB : 执行SQL查询
DB-->>Model : 返回结果集
Model-->>Service : 映射实体
Service-->>API : 返回数据
API-->>Client : JSON响应
Note over Client,DB : 异步查询流程
```
**图表来源**
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L20-L41)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L16-L46)
#### 指标管理API
| 接口 | 方法 | 功能描述 | 权限要求 |
|------|------|----------|----------|
| /api/v1/indicators | GET | 获取指标列表 | 任意用户 |
| /api/v1/indicators/active | GET | 获取激活指标 | 任意用户 |
| /api/v1/indicators/{id} | GET/PUT/DELETE | 指标详情管理 | 管理员/经理 |
| /api/v1/indicators/templates/list | GET | 获取模板列表 | 任意用户 |
| /api/v1/indicators/templates/import | POST | 导入指标模板 | 管理员/经理 |
#### 模板管理API
| 接口 | 方法 | 功能描述 | 权限要求 |
|------|------|----------|----------|
| /api/v1/templates | GET/POST | 模板列表管理 | 任意用户/管理员 |
| /api/v1/templates/types | GET | 获取模板类型 | 任意用户 |
| /api/v1/templates/dimensions | GET | 获取BSC维度 | 任意用户 |
| /api/v1/templates/{id} | GET/PUT/DELETE | 模板详情管理 | 管理员/经理 |
| /api/v1/templates/{id}/indicators | GET/POST | 模板指标管理 | 管理员/经理 |
**章节来源**
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L1-L272)
### 业务流程实现
#### 指标模板导入流程
```mermaid
flowchart TD
Start([开始导入]) --> Validate[验证模板数据]
Validate --> CheckExisting{检查指标是否存在}
CheckExisting --> |存在且允许覆盖| UpdateExisting[更新现有指标]
CheckExisting --> |不存在| CreateNew[创建新指标]
CheckExisting --> |存在且不允许覆盖| Skip[跳过该指标]
UpdateExisting --> Next[处理下一个指标]
CreateNew --> Next
Skip --> Next
Next --> MoreIndicators{还有指标吗}
MoreIndicators --> |是| Validate
MoreIndicators --> |否| Commit[提交事务]
Commit --> End([导入完成])
```
**图表来源**
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L106-L154)
#### 模板指标管理流程
```mermaid
sequenceDiagram
participant Client as 客户端
participant API as 模板API
participant Service as 模板服务
participant DB as 数据库
Client->>API : POST /templates/{id}/indicators
API->>Service : add_indicator()
Service->>DB : 检查模板存在性
DB-->>Service : 模板存在
Service->>DB : 检查指标是否已关联
DB-->>Service : 未关联
Service->>DB : 获取最大排序号
DB-->>Service : 返回排序号
Service->>DB : 添加模板指标关联
DB-->>Service : 操作成功
Service-->>API : 返回关联ID
API-->>Client : 成功响应
```
**图表来源**
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L160-L206)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L209-L221)
**章节来源**
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L106-L154)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L160-L206)
### 配置示例
#### 数据库连接配置
```python
# 数据库URL格式
DATABASE_URL = "postgresql+asyncpg://username:password@host:port/database"
# 示例配置
DATABASE_URL = "postgresql+asyncpg://postgres:postgres@localhost:5432/hospital_performance"
```
#### 分页配置
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| DEFAULT_PAGE_SIZE | 20 | 默认每页显示条数 |
| MAX_PAGE_SIZE | 100 | 最大每页显示条数 |
| API_PREFIX | /api/v1 | API前缀 |
#### 权限配置
| 角色 | 权限范围 | 可执行操作 |
|------|----------|------------|
| staff | 普通员工 | 查看自己的考核结果 |
| manager | 科室负责人 | 管理本科室指标和模板 |
| admin | 系统管理员 | 完全权限，包括用户管理 |
**章节来源**
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L33)
## 依赖关系分析
系统采用模块化设计，各组件之间保持松耦合：
```mermaid
graph TB
subgraph "核心模块"
CoreConfig[配置模块]
Database[数据库模块]
Security[安全模块]
end
subgraph "业务模块"
IndicatorService[指标服务]
TemplateService[模板服务]
AssessmentService[考核服务]
StaffService[员工服务]
end
subgraph "数据模块"
Models[数据模型]
Schemas[数据模式]
end
subgraph "API模块"
IndicatorsAPI[指标API]
TemplatesAPI[模板API]
AssessmentAPI[考核API]
end
CoreConfig --> Database
CoreConfig --> Security
Database --> Models
Security --> Schemas
IndicatorService --> Models
TemplateService --> Models
AssessmentService --> Models
StaffService --> Models
IndicatorsAPI --> IndicatorService
TemplatesAPI --> TemplateService
AssessmentAPI --> AssessmentService
```
**图表来源**
- [backend/app/main.py](file://backend/app/main.py#L10-L12)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L9-L10)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L10-L17)
### 外部依赖
系统依赖的主要外部库：
| 依赖库 | 版本 | 用途 |
|--------|------|------|
| fastapi | 最新稳定版 | Web框架 |
| sqlalchemy | 2.x | ORM框架 |
| asyncpg | 最新稳定版 | PostgreSQL异步驱动 |
| alembic | 最新稳定版 | 数据库迁移 |
| pydantic | 最新稳定版 | 数据验证和序列化 |
| uvicorn | 最新稳定版 | ASGI服务器 |
**章节来源**
- [backend/app/main.py](file://backend/app/main.py#L1-L92)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L1-L11)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L1-L17)
## 性能考虑
### 数据库优化
系统采用了多项数据库优化策略：
1. **索引优化**
- 为常用查询字段建立索引
- 使用复合索引提高查询性能
- 合理使用唯一约束避免重复数据
2. **查询优化**
- 使用分页查询避免大数据量加载
- 实现延迟加载减少不必要的数据传输
- 优化复杂查询的执行计划
3. **连接池管理**
- 配置合适的连接池大小
- 启用连接复用机制
- 实现连接超时和重连机制
### 缓存策略
```mermaid
flowchart LR
Request[请求到达] --> CheckCache{检查缓存}
CheckCache --> |命中| ReturnCache[返回缓存数据]
CheckCache --> |未命中| QueryDB[查询数据库]
QueryDB --> ProcessData[处理数据]
ProcessData --> CacheData[缓存数据]
CacheData --> ReturnData[返回响应]
ReturnCache --> End[结束]
ReturnData --> End
```
**图表来源**
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L56-L64)
### 异步处理
系统充分利用异步IO特性：
- **异步数据库操作**：使用SQLAlchemy 2.0异步特性
- **异步文件处理**：支持大文件的异步导入导出
- **异步API调用**：减少等待时间，提高吞吐量
## 故障排除指南
### 常见问题及解决方案
#### 数据库连接问题
**问题症状：**
- 应用启动时报数据库连接错误
- API调用时出现连接超时
**解决步骤：**
1. 检查DATABASE_URL配置是否正确
2. 验证数据库服务是否正常运行
3. 确认网络连接和防火墙设置
4. 检查连接池配置参数
#### 权限不足问题
**问题症状：**
- API调用返回403权限错误
- 模板创建/更新操作失败
**解决步骤：**
1. 验证用户身份认证状态
2. 检查用户角色权限
3. 确认操作所需的最小权限级别
4. 重新登录获取新的访问令牌
#### 数据验证错误
**问题症状：**
- API返回422数据验证错误
- 指标创建/更新失败
**解决步骤：**
1. 检查请求数据格式是否正确
2. 验证必填字段是否完整
3. 确认数据类型和范围限制
4. 查看详细的错误信息提示
### 日志分析
系统提供了完善的日志记录机制：
```mermaid
graph TD
Request[请求处理] --> InfoLog[信息日志]
Request --> WarnLog[警告日志]
Request --> ErrorLog[错误日志]
Request --> DebugLog[调试日志]
InfoLog --> NormalOps[正常操作记录]
WarnLog --> PotentialIssues[潜在问题预警]
ErrorLog --> Failures[失败事件记录]
DebugLog --> Development[开发调试信息]
```
**图表来源**
- [backend/app/main.py](file://backend/app/main.py#L58-L74)
**章节来源**
- [backend/app/main.py](file://backend/app/main.py#L58-L74)
## 结论
本指标模板服务系统基于平衡计分卡理论，实现了完整的医院绩效管理功能。通过标准化的数据模型设计、清晰的分层架构和完善的API接口，为医院提供了灵活、可扩展的绩效管理解决方案。
系统的主要优势包括：
1. **完整的功能覆盖**：从指标定义到模板管理，涵盖绩效管理的全流程
2. **灵活的配置机制**：支持多种评分方法和权重设置
3. **良好的扩展性**：模块化设计便于功能扩展和定制
4. **高性能的实现**：异步IO和数据库优化确保系统性能
5. **完善的错误处理**：全面的日志记录和异常处理机制
通过持续的优化和迭代，该系统能够满足不同规模医院的绩效管理需求，为提升医疗质量和效率提供有力支撑。

503
.qoder/repowiki/zh/content/后端开发指南/服务层开发/服务层开发.md Normal file
View File

@@ -0,0 +1,503 @@
# 服务层开发
<cite>
**本文档引用的文件**
- [assessment_service.py](file://backend/app/services/assessment_service.py)
- [salary_service.py](file://backend/app/services/salary_service.py)
- [stats_service.py](file://backend/app/services/stats_service.py)
- [department_service.py](file://backend/app/services/department_service.py)
- [staff_service.py](file://backend/app/services/staff_service.py)
- [indicator_service.py](file://backend/app/services/indicator_service.py)
- [finance_service.py](file://backend/app/services/finance_service.py)
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py)
- [template_service.py](file://backend/app/services/template_service.py)
- [menu_service.py](file://backend/app/services/menu_service.py)
- [database.py](file://backend/app/core/database.py)
- [config.py](file://backend/app/core/config.py)
- [models.py](file://backend/app/models/models.py)
- [assessments.py](file://backend/app/api/v1/assessments.py)
- [salary.py](file://backend/app/api/v1/salary.py)
- [stats.py](file://backend/app/api/v1/stats.py)
- [departments.py](file://backend/app/api/v1/departments.py)
- [staff.py](file://backend/app/api/v1/staff.py)
- [indicators.py](file://backend/app/api/v1/indicators.py)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本指南面向医院绩效系统服务层开发，系统化阐述服务层架构设计、依赖注入模式、业务逻辑封装与协作机制。文档覆盖考核服务、工资服务、统计服务、部门服务、员工服务、指标服务、财务服务、绩效计划服务、模板服务与菜单服务等核心模块，提供方法实现模式、参数校验、返回值处理、事务管理、异常处理与日志记录规范，并给出单元测试编写方法与Mock对象使用建议，以及性能优化与并发处理策略。
## 项目结构
后端采用分层架构，服务层位于API层与数据访问层之间，负责业务规则封装与跨实体协调。核心目录与文件关系如下：
```mermaid
graph TB
subgraph "API 层"
A1["/api/v1/assessments.py"]
A2["/api/v1/salary.py"]
A3["/api/v1/stats.py"]
A4["/api/v1/departments.py"]
A5["/api/v1/staff.py"]
A6["/api/v1/indicators.py"]
end
subgraph "服务层"
S1["assessment_service.py"]
S2["salary_service.py"]
S3["stats_service.py"]
S4["department_service.py"]
S5["staff_service.py"]
S6["indicator_service.py"]
S7["finance_service.py"]
S8["performance_plan_service.py"]
S9["template_service.py"]
S10["menu_service.py"]
end
subgraph "核心配置"
C1["core/config.py"]
C2["core/database.py"]
C3["models/models.py"]
end
A1 --> S1
A2 --> S2
A3 --> S3
A4 --> S4
A5 --> S5
A6 --> S6
S1 --> C2
S2 --> C2
S3 --> C2
S4 --> C2
S5 --> C2
S6 --> C2
S7 --> C2
S8 --> C2
S9 --> C2
S10 --> C2
S1 --> C3
S2 --> C3
S3 --> C3
S4 --> C3
S5 --> C3
S6 --> C3
S7 --> C3
S8 --> C3
S9 --> C3
S10 --> C3
C1 --> C2
```
**图表来源**
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [salary.py](file://backend/app/api/v1/salary.py#L1-L156)
- [stats.py](file://backend/app/api/v1/stats.py#L1-L242)
- [departments.py](file://backend/app/api/v1/departments.py#L1-L108)
- [staff.py](file://backend/app/api/v1/staff.py#L1-L124)
- [indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [salary_service.py](file://backend/app/services/salary_service.py#L1-L260)
- [stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
- [department_service.py](file://backend/app/services/department_service.py#L1-L150)
- [staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
- [indicator_service.py](file://backend/app/services/indicator_service.py#L1-L197)
- [finance_service.py](file://backend/app/services/finance_service.py#L1-L368)
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L1-L342)
- [template_service.py](file://backend/app/services/template_service.py#L1-L293)
- [menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
- [database.py](file://backend/app/core/database.py#L1-L39)
- [config.py](file://backend/app/core/config.py#L1-L47)
- [models.py](file://backend/app/models/models.py#L1-L438)
**章节来源**
- [database.py](file://backend/app/core/database.py#L1-L39)
- [config.py](file://backend/app/core/config.py#L1-L47)
## 核心组件
服务层由10个核心服务组成，分别对应业务领域：
- 考核服务：AssessmentService（创建、更新、提交、审核、确认、批量创建）
- 工资服务：SalaryService（计算绩效奖金、生成工资、批量生成、确认、批量确认）
- 统计服务：StatsService（BSC维度分析、科室统计、趋势分析、排名、完成度）
- 部门服务：DepartmentService（列表、树形结构、增删改查）
- 员工服务：StaffService（列表、详情、增删改查、按科室查询）
- 指标服务：IndicatorService（列表、模板导入、模板列表）
- 财务服务：FinanceService（收支明细、收支汇总、分类统计、增删改查）
- 绩效计划服务：PerformancePlanService（计划生命周期管理、树形结构、统计）
- 模板服务：TemplateService（模板增删改查、指标关联、标签映射）
- 菜单服务：MenuService（菜单树、列表、增删改查、默认菜单初始化）
每个服务均采用静态方法设计，便于在FastAPI依赖注入中直接调用，保持无状态与线程安全。
**章节来源**
- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [salary_service.py](file://backend/app/services/salary_service.py#L1-L260)
- [stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
- [department_service.py](file://backend/app/services/department_service.py#L1-L150)
- [staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
- [indicator_service.py](file://backend/app/services/indicator_service.py#L1-L197)
- [finance_service.py](file://backend/app/services/finance_service.py#L1-L368)
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L1-L342)
- [template_service.py](file://backend/app/services/template_service.py#L1-L293)
- [menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
## 架构概览
服务层通过依赖注入从API层接收AsyncSession与当前用户上下文，执行业务逻辑并返回标准化响应。事务管理由数据库会话自动处理，异常通过HTTP异常抛出，日志通过应用日志框架记录。
```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "API路由"
participant Service as "服务层"
participant DB as "数据库会话"
participant Model as "ORM模型"
Client->>API : "HTTP请求"
API->>Service : "调用服务方法(AsyncSession, 参数)"
Service->>DB : "执行SQL查询/更新"
DB->>Model : "映射到ORM模型"
Model-->>DB : "返回结果"
DB-->>Service : "提交/回滚事务"
Service-->>API : "业务结果"
API-->>Client : "标准化响应"
```
**图表来源**
- [assessments.py](file://backend/app/api/v1/assessments.py#L20-L166)
- [salary.py](file://backend/app/api/v1/salary.py#L20-L156)
- [stats.py](file://backend/app/api/v1/stats.py#L17-L242)
- [database.py](file://backend/app/core/database.py#L28-L39)
## 详细组件分析
### 考核服务 AssessmentService
- 功能职责
- 列表查询：支持多条件过滤、分页、总数统计
- 详情查询：加载员工、部门、明细与指标
- 创建：计算总分与加权得分，批量写入明细
- 更新：仅草稿或被拒状态下允许修改；重建明细并重算分数
- 提交/审核/确认：状态机流转，记录操作人与时间戳
- 批量创建：按科室与指标集合批量生成考核记录
- 实现模式
- 使用selectinload预加载关联，减少N+1查询
- flush/refresh确保持久化与读取一致性
- 状态前置校验，防止非法状态变更
- 参数验证与返回值
- API层进行输入参数校验与权限控制
- 服务层返回实体或None，由API层抛出HTTP异常
- 事务管理
- 单次调用内统一commit/rollback，保证原子性
- 并发处理
- 批量创建时先查询是否存在，避免重复创建
- 建议在API层增加幂等键与锁机制
```mermaid
flowchart TD
Start(["开始"]) --> CheckState["检查状态是否允许更新"]
CheckState --> |不允许| ReturnNone["返回None"]
CheckState --> |允许| DeleteOld["删除旧明细"]
DeleteOld --> Recalc["遍历新明细计算总分与加权分"]
Recalc --> Save["保存更新后的实体"]
Save --> Refresh["刷新实体"]
Refresh --> End(["结束"])
ReturnNone --> End
```
**图表来源**
- [assessment_service.py](file://backend/app/services/assessment_service.py#L110-L156)
**章节来源**
- [assessment_service.py](file://backend/app/services/assessment_service.py#L18-L263)
- [assessments.py](file://backend/app/api/v1/assessments.py#L20-L166)
### 工资服务 SalaryService
- 功能职责
- 列表查询：支持按员工、科室、周期、状态过滤
- 详情查询：加载员工与部门信息
- 绩效奖金计算：奖金 = 基数 × (得分/100) × 绩效系数
- 创建/更新：计算总工资，仅待确认状态下允许更新
- 生成：从已确认考核生成工资记录
- 批量生成：按科室批量生成
- 确认/批量确认：变更状态并持久化
- 实现模式
- 通过员工信息读取基础工资与绩效系数
- 生成时检查重复，避免重复发薪
- 使用flush/refresh确保状态一致
- 参数验证与返回值
- API层校验周期与权限
- 服务层返回实体或None，API层处理错误
- 事务管理
- 单次操作内commit/rollback
- 性能优化
- 批量生成时一次查询所有已确认考核，减少往返
```mermaid
sequenceDiagram
participant API as "API"
participant SS as "SalaryService"
participant DB as "数据库"
API->>SS : "generate_from_assessment(staff_id, year, month)"
SS->>DB : "查询员工信息"
DB-->>SS : "员工信息"
SS->>DB : "查询已确认考核"
DB-->>SS : "考核记录"
SS->>SS : "计算绩效奖金"
SS->>DB : "创建工资记录"
DB-->>SS : "返回记录"
SS-->>API : "工资记录"
```
**图表来源**
- [salary_service.py](file://backend/app/services/salary_service.py#L127-L190)
- [salary.py](file://backend/app/api/v1/salary.py#L96-L129)
**章节来源**
- [salary_service.py](file://backend/app/services/salary_service.py#L21-L260)
- [salary.py](file://backend/app/api/v1/salary.py#L20-L156)
### 统计服务 StatsService
- 功能职责
- BSC维度统计：按维度汇总得分、权重与指标数量
- 科室统计：按科室汇总人数、总分、平均分、最高/最低分
- 趋势分析：月度趋势（支持跨年）
- 排名：员工与科室排名
- 完成度：指标平均分、目标完成率
- 实现模式
- 使用SQL聚合函数与分组，避免Python侧聚合
- 条件动态拼接，支持多维过滤
- 性能优化
- 合理使用索引与分页
- 趋势分析中对跨年场景进行区间合并
```mermaid
flowchart TD
Start(["开始"]) --> BuildCond["构建查询条件"]
BuildCond --> ExecQuery["执行聚合查询"]
ExecQuery --> GroupBy["按维度/科室/月份分组"]
GroupBy --> CalcAvg["计算平均分与完成率"]
CalcAvg --> Format["格式化输出"]
Format --> End(["结束"])
```
**图表来源**
- [stats_service.py](file://backend/app/services/stats_service.py#L19-L300)
**章节来源**
- [stats_service.py](file://backend/app/services/stats_service.py#L19-L300)
- [stats.py](file://backend/app/api/v1/stats.py#L17-L242)
### 部门服务 DepartmentService
- 功能职责
- 列表查询：按类型与启用状态过滤
- 树形结构：手动构建父子关系，避免懒加载问题
- 增删改查：层级计算、唯一性校验
- 实现模式
- 手动构建树形结构，确保序列化稳定
- 删除前检查子节点，防止破坏层级
- 错误处理
- 不存在或有子节点时返回False/None，由API层抛错
**章节来源**
- [department_service.py](file://backend/app/services/department_service.py#L16-L150)
- [departments.py](file://backend/app/api/v1/departments.py#L20-L108)
### 员工服务 StaffService
- 功能职责
- 列表查询：支持关键字搜索（姓名/工号）
- 详情查询：加载部门信息
- 增删改查：唯一性校验（工号）
- 按科室查询：返回在职员工
- 实现模式
- 使用ilike进行模糊匹配
- selectinload预加载部门
**章节来源**
- [staff_service.py](file://backend/app/services/staff_service.py#L16-L112)
- [staff.py](file://backend/app/api/v1/staff.py#L20-L124)
### 指标服务 IndicatorService
- 功能职责
- 列表查询：按类型、维度、启用状态过滤
- 模板导入：支持覆盖策略
- 模板列表：内置模板集合
- 实现模式
- JSON字段存储适用科室类型数组
- 导入时检查编码唯一性
**章节来源**
- [indicator_service.py](file://backend/app/services/indicator_service.py#L16-L197)
- [indicators.py](file://backend/app/api/v1/indicators.py#L20-L142)
### 财务服务 FinanceService
- 功能职责
- 收入/支出明细查询与汇总
- 收支结余计算
- 按类别统计收入/支出
- 增删改查财务记录
- 科室汇总：全院科室财务汇总
- 实现模式
- 类别标签映射，增强可读性
- 使用coalesce处理空值
**章节来源**
- [finance_service.py](file://backend/app/services/finance_service.py#L43-L368)
### 绩效计划服务 PerformancePlanService
- 功能职责
- 计划生命周期：草稿→待审批→批准→执行中→完成/取消
- 树形结构：支持层级关系
- 统计：按状态统计数量
- 指标关联：增删改查
- 实现模式
- 状态机严格控制流转
- 树形构建使用字典映射
**章节来源**
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L18-L342)
### 模板服务 TemplateService
- 功能职责
- 模板增删改查与指标关联
- 指标排序与去重
- 标签映射：类型与维度标签
- 实现模式
- 排序字段自动生成
- 关联唯一约束避免重复
**章节来源**
- [template_service.py](file://backend/app/services/template_service.py#L23-L293)
### 菜单服务 MenuService
- 功能职责
- 菜单树形结构与列表查询
- 增删改查与默认菜单初始化
- 实现模式
- 递归转字典，支持前端渲染
- 初始化时检查是否已有数据
**章节来源**
- [menu_service.py](file://backend/app/services/menu_service.py#L15-L137)
## 依赖分析
服务层依赖关系清晰，API层通过依赖注入获取AsyncSession与当前用户，服务层仅依赖数据库会话与模型定义，耦合度低、内聚性强。
```mermaid
graph TB
API_A["/api/v1/assessments.py"] --> SVC_A["AssessmentService"]
API_S["/api/v1/salary.py"] --> SVC_S["SalaryService"]
API_T["/api/v1/stats.py"] --> SVC_T["StatsService"]
API_D["/api/v1/departments.py"] --> SVC_D["DepartmentService"]
API_ST["/api/v1/staff.py"] --> SVC_ST["StaffService"]
API_I["/api/v1/indicators.py"] --> SVC_I["IndicatorService"]
SVC_A --> DB["get_db() AsyncSession"]
SVC_S --> DB
SVC_T --> DB
SVC_D --> DB
SVC_ST --> DB
SVC_I --> DB
SVC_A --> MODELS["models.py ORM"]
SVC_S --> MODELS
SVC_T --> MODELS
SVC_D --> MODELS
SVC_ST --> MODELS
SVC_I --> MODELS
```
**图表来源**
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [salary.py](file://backend/app/api/v1/salary.py#L1-L156)
- [stats.py](file://backend/app/api/v1/stats.py#L1-L242)
- [departments.py](file://backend/app/api/v1/departments.py#L1-L108)
- [staff.py](file://backend/app/api/v1/staff.py#L1-L124)
- [indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [salary_service.py](file://backend/app/services/salary_service.py#L1-L260)
- [stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
- [department_service.py](file://backend/app/services/department_service.py#L1-L150)
- [staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
- [indicator_service.py](file://backend/app/services/indicator_service.py#L1-L197)
- [database.py](file://backend/app/core/database.py#L28-L39)
- [models.py](file://backend/app/models/models.py#L1-L438)
**章节来源**
- [database.py](file://backend/app/core/database.py#L1-L39)
- [models.py](file://backend/app/models/models.py#L1-L438)
## 性能考虑
- 查询优化
- 使用selectinload预加载关联，避免N+1查询
- 合理使用索引（如staff、assessment、salary等表的复合索引）
- 分页参数限制，避免超大结果集
- 事务与并发
- 服务层单次调用内commit/rollback，保证一致性
- 批量操作使用flush减少往返
- 对重复创建场景增加存在性检查
- 缓存与降级
- 对只读统计结果可引入Redis缓存
- 对高频查询结果进行分页与限流
- 日志与监控
- 记录慢查询与异常堆栈
- 结合数据库慢查询日志定位瓶颈
## 故障排除指南
- 常见异常
- 未找到实体：返回None，API层抛出404
- 状态不允许：返回None，API层抛出400
- 唯一性冲突：编码重复导致创建失败，API层抛出400
- 事务回滚
- 数据库会话在异常时自动回滚，确保数据一致性
- 日志记录
- 应用日志与错误日志分离，便于排查
- 记录关键业务事件（创建、更新、状态变更）
**章节来源**
- [assessments.py](file://backend/app/api/v1/assessments.py#L60-L115)
- [salary.py](file://backend/app/api/v1/salary.py#L61-L142)
- [indicators.py](file://backend/app/api/v1/indicators.py#L76-L111)
- [database.py](file://backend/app/core/database.py#L31-L36)
## 结论
服务层通过清晰的职责划分、严格的参数校验与状态机控制、完善的事务与异常处理，有效支撑了医院绩效系统的业务闭环。建议在后续迭代中进一步完善单元测试覆盖率、引入缓存与监控告警，并持续优化查询性能与并发处理能力。
## 附录
### 服务方法实现模式清单
- 列表查询：支持多条件过滤、分页、总数统计
- 详情查询：加载关联实体，返回完整信息
- 创建/更新：参数校验、业务计算、flush/refresh
- 删除：前置检查（如子节点、状态）
- 批量操作：批量查询、循环处理、一次性commit
### 参数验证与返回值处理
- API层负责输入参数校验与权限控制
- 服务层返回实体或None，由API层统一抛出HTTP异常
- 响应体遵循统一结构（code/message/data/total/page/page_size）
### 事务管理与异常处理
- 服务层单次调用内commit/rollback
- 数据库异常自动回滚并抛出
- 建议在API层捕获并记录异常日志
### 日志记录规范
- 记录关键业务事件与异常堆栈
- 区分应用日志与错误日志
- 包含请求ID、用户ID、操作时间
### 单元测试编写方法与Mock对象使用
- Mock数据库会话：使用unittest.mock.patch替换get_db依赖
- Mock服务方法：对复杂业务逻辑进行隔离测试
- 测试用例覆盖正常路径、边界条件与异常分支
- 使用pytest与factory_boy生成测试数据
### 性能优化与并发处理
- 查询优化：预加载、索引、分页
- 事务优化：批量flush、减少往返
- 并发控制：幂等键、锁机制、重试策略
- 监控与告警：慢查询、错误率、吞吐量

568
.qoder/repowiki/zh/content/后端开发指南/服务层开发/系统管理服务.md Normal file
View File

@@ -0,0 +1,568 @@
# 系统管理服务
<cite>
**本文档引用的文件**
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py)
- [menu_service.py](file://backend/app/services/menu_service.py)
- [finance_service.py](file://backend/app/services/finance_service.py)
- [finance.py](file://backend/app/models/finance.py)
- [models.py](file://backend/app/models/models.py)
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py)
- [menus.py](file://backend/app/api/v1/menus.py)
- [finance.py](file://backend/app/api/v1/finance.py)
- [schemas.py](file://backend/app/schemas/schemas.py)
- [security.py](file://backend/app/core/security.py)
- [config.py](file://backend/app/core/config.py)
- [database.py](file://backend/app/core/database.py)
- [main.py](file://backend/app/main.py)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 简介
本文档详细阐述了医院绩效系统的三大核心管理服务：绩效计划服务、菜单服务和财务服务。这些服务构成了整个系统的管理中枢，负责组织架构管理、权限控制和财务核算等关键业务功能。
系统采用现代化的FastAPI + SQLAlchemy架构，支持异步IO操作，具备良好的扩展性和维护性。通过清晰的分层设计，实现了业务逻辑与数据访问的分离，确保了系统的稳定性和可测试性。
## 项目结构
后端项目采用典型的三层架构设计：
```mermaid
graph TB
subgraph "表现层 (API Layer)"
API[API路由]
Schemas[数据模式]
end
subgraph "服务层 (Service Layer)"
PerfService[绩效计划服务]
MenuService[菜单服务]
FinanceService[财务服务]
end
subgraph "数据访问层 (Data Access Layer)"
Models[数据模型]
DB[数据库]
end
subgraph "基础设施层"
Security[安全认证]
Config[系统配置]
Database[数据库连接]
end
API --> PerfService
API --> MenuService
API --> FinanceService
PerfService --> Models
MenuService --> Models
FinanceService --> Models
Models --> DB
Security --> API
Config --> API
Database --> Models
```
**图表来源**
- [main.py](file://backend/app/main.py#L15-L77)
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L1-L310)
- [menus.py](file://backend/app/api/v1/menus.py#L1-L164)
- [finance.py](file://backend/app/api/v1/finance.py#L1-L217)
**章节来源**
- [main.py](file://backend/app/main.py#L15-L77)
- [config.py](file://backend/app/core/config.py#L9-L47)
- [database.py](file://backend/app/core/database.py#L9-L39)
## 核心组件
### 绩效计划服务 (PerformancePlanService)
绩效计划服务是系统的核心业务组件，负责完整的绩效计划生命周期管理：
- **计划创建与管理**：支持多层级、多类型的绩效计划创建
- **状态流转控制**：严格的审批流程和状态管理
- **指标关联管理**：灵活的KPI指标配置和权重设置
- **统计分析功能**：提供全面的计划执行统计和分析
### 菜单服务 (MenuService)
菜单服务提供完整的前端导航管理能力：
- **树形结构管理**：支持多级菜单的层次化管理
- **权限控制集成**：与用户权限系统深度集成
- **动态菜单生成**：根据用户角色动态生成菜单树
- **默认菜单初始化**：系统启动时自动初始化基础菜单结构
### 财务服务 (FinanceService)
财务服务专注于医院经济核算管理：
- **收支管理**：完整的收入和支出记录管理
- **科室核算**：按科室维度的财务数据分析
- **预算控制**：支持预算执行情况跟踪
- **报表统计**：多维度的财务统计和分析报表
**章节来源**
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L15-L342)
- [menu_service.py](file://backend/app/services/menu_service.py#L12-L137)
- [finance_service.py](file://backend/app/services/finance_service.py#L17-L368)
## 架构概览
系统采用分层架构设计，确保关注点分离和职责明确：
```mermaid
graph TB
subgraph "应用入口"
Main[主应用]
Router[API路由器]
end
subgraph "认证与授权"
Security[安全模块]
Auth[认证中间件]
end
subgraph "业务服务层"
PerfSvc[绩效计划服务]
MenuSvc[菜单服务]
FinanceSvc[财务服务]
end
subgraph "数据模型层"
PerfModel[绩效模型]
MenuModel[菜单模型]
FinanceModel[财务模型]
end
subgraph "数据存储层"
DB[(PostgreSQL)]
Cache[(Redis)]
end
Main --> Router
Router --> Security
Security --> PerfSvc
Security --> MenuSvc
Security --> FinanceSvc
PerfSvc --> PerfModel
MenuSvc --> MenuModel
FinanceSvc --> FinanceModel
PerfModel --> DB
MenuModel --> DB
FinanceModel --> DB
DB --> Cache
```
**图表来源**
- [main.py](file://backend/app/main.py#L19-L51)
- [security.py](file://backend/app/core/security.py#L55-L110)
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L15-L342)
- [menu_service.py](file://backend/app/services/menu_service.py#L12-L137)
- [finance_service.py](file://backend/app/services/finance_service.py#L17-L368)
## 详细组件分析
### 绩效计划管理功能
#### 计划生命周期管理
```mermaid
stateDiagram-v2
[*] --> 草稿
草稿 --> 待审批 : 提交申请
待审批 --> 已批准 : 审批通过
待审批 --> 已驳回 : 审批驳回
已批准 --> 执行中 : 激活计划
执行中 --> 已完成 : 计划结束
执行中 --> 已取消 : 主动取消
已批准 --> 已取消 : 主动取消
已驳回 --> 草稿 : 修改后重新提交
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L233-L242)
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L131-L182)
#### KPI指标关联管理
绩效计划与KPI指标的关联管理提供了灵活的指标配置能力：
- **权重分配**：支持不同指标的权重设置
- **目标值设定**：为每个指标设置目标值和单位
- **评分方法**：支持自定义评分方法和参数
- **动态调整**：运行期可调整指标配置
**章节来源**
- [performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L196-L249)
- [models.py](file://backend/app/models/models.py#L314-L338)
### 菜单权限管理功能
#### 菜单树形结构管理
```mermaid
classDiagram
class Menu {
+int id
+int parent_id
+MenuType menu_type
+string menu_name
+string menu_icon
+string path
+string component
+string permission
+int sort_order
+bool is_visible
+bool is_active
+DateTime created_at
+DateTime updated_at
}
class MenuService {
+get_tree(visible_only) Dict[]
+get_list(menu_type, is_visible) Menu[]
+get_by_id(menu_id) Menu
+create(menu_data) Menu
+update(menu_id, menu_data) Menu
+delete(menu_id) bool
+init_default_menus() void
}
MenuService --> Menu : manages
Menu --> Menu : children
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L347-L372)
- [menu_service.py](file://backend/app/services/menu_service.py#L12-L137)
#### 权限控制机制
系统实现了基于角色的权限控制（RBAC）：
- **用户角色**：admin（管理员）、manager（经理）、staff（员工）
- **权限验证**：@get_current_active_user（普通用户）、@get_current_manager_user（管理员/经理）
- **菜单权限**：通过permission字段控制菜单显示和访问
- **操作权限**：针对不同操作设置不同的权限要求
**章节来源**
- [security.py](file://backend/app/core/security.py#L85-L110)
- [menus.py](file://backend/app/api/v1/menus.py#L98-L163)
### 财务相关功能
#### 科室财务核算
```mermaid
classDiagram
class DepartmentFinance {
+int id
+int department_id
+int period_year
+int period_month
+FinanceType finance_type
+string category
+float amount
+string source
+string remark
+DateTime created_at
+DateTime updated_at
}
class FinanceService {
+get_department_revenue(department_id, year, month) Dict[]
+get_department_expense(department_id, year, month) Dict[]
+get_department_balance(department_id, year, month) Dict
+get_revenue_by_category(department_id, year, month) Dict[]
+get_expense_by_category(department_id, year, month) Dict[]
+create_finance_record(params) DepartmentFinance
+update_finance_record(id, params) DepartmentFinance
+delete_finance_record(id) bool
+get_department_summary(year, month) Dict[]
}
FinanceService --> DepartmentFinance : manages
DepartmentFinance --> Department : belongs_to
```
**图表来源**
- [finance.py](file://backend/app/models/finance.py#L45-L74)
- [finance_service.py](file://backend/app/services/finance_service.py#L17-L368)
#### 财务类别管理
系统支持标准化的财务类别管理：
- **收入类别**：检查费、检验费、放射费、床位费、护理费、治疗费、手术费、注射费、吸氧费、其他
- **支出类别**：材料费、人员支出、维修费、水电费、其他
- **类别验证**：严格的类别有效性检查
- **标签本地化**：支持中文标签显示
**章节来源**
- [finance_service.py](file://backend/app/services/finance_service.py#L20-L41)
- [finance.py](file://backend/app/models/finance.py#L16-L43)
### 系统配置管理
#### 环境配置管理
系统采用集中式配置管理：
- **数据库配置**：支持PostgreSQL异步连接池
- **JWT配置**：Token过期时间和算法设置
- **CORS配置**：跨域资源共享设置
- **分页配置**：默认和最大分页大小设置
#### 数据库连接管理
```mermaid
sequenceDiagram
participant Client as 客户端
participant API as API服务
participant Session as 数据库会话
participant Pool as 连接池
participant DB as PostgreSQL
Client->>API : 请求数据
API->>Session : 获取数据库会话
Session->>Pool : 从连接池获取连接
Pool->>DB : 建立数据库连接
DB-->>Pool : 返回连接
Pool-->>Session : 返回连接
Session-->>API : 返回数据
API-->>Client : 响应数据
API->>Session : 提交事务
Session->>DB : 提交数据
DB-->>Session : 确认提交
Session->>Pool : 归还连接
```
**图表来源**
- [database.py](file://backend/app/core/database.py#L28-L39)
- [config.py](file://backend/app/core/config.py#L18-L26)
**章节来源**
- [config.py](file://backend/app/core/config.py#L9-L47)
- [database.py](file://backend/app/core/database.py#L9-L39)
## 依赖关系分析
### 服务间依赖关系
```mermaid
graph TD
subgraph "API层"
PerfAPI[绩效计划API]
MenuAPI[菜单API]
FinanceAPI[财务API]
end
subgraph "服务层"
PerfService[绩效计划服务]
MenuService[菜单服务]
FinanceService[财务服务]
end
subgraph "模型层"
PerfModel[绩效模型]
MenuModel[菜单模型]
FinanceModel[财务模型]
UserModel[用户模型]
end
subgraph "基础设施"
Security[安全模块]
DB[数据库]
Config[配置模块]
end
PerfAPI --> PerfService
MenuAPI --> MenuService
FinanceAPI --> FinanceService
PerfService --> PerfModel
MenuService --> MenuModel
FinanceService --> FinanceModel
PerfService --> UserModel
Security --> PerfService
Security --> MenuService
Security --> FinanceService
PerfModel --> DB
MenuModel --> DB
FinanceModel --> DB
UserModel --> DB
Config --> PerfAPI
Config --> MenuAPI
Config --> FinanceAPI
```
**图表来源**
- [performance_plans.py](file://backend/app/api/v1/performance_plans.py#L15-L16)
- [menus.py](file://backend/app/api/v1/menus.py#L11-L12)
- [finance.py](file://backend/app/api/v1/finance.py#L14-L16)
### 数据模型依赖关系
```mermaid
erDiagram
PERFORMANCE_PLANS {
int id PK
string plan_name
string plan_code UK
enum plan_level
int plan_year
int plan_month
enum status
int department_id FK
int staff_id FK
int parent_plan_id FK
bool is_active
datetime created_at
datetime updated_at
}
PLAN_KPI_RELATIONS {
int id PK
int plan_id FK
int indicator_id FK
float target_value
string target_unit
float weight
datetime created_at
datetime updated_at
}
MENUS {
int id PK
int parent_id FK
enum menu_type
string menu_name
string menu_icon
string path
string component
string permission
int sort_order
bool is_visible
bool is_active
datetime created_at
datetime updated_at
}
DEPARTMENT_FINANCES {
int id PK
int department_id FK
int period_year
int period_month
enum finance_type
string category
float amount
datetime created_at
datetime updated_at
}
USERS {
int id PK
string username UK
string password_hash
int staff_id FK
string role
bool is_active
datetime last_login
datetime created_at
datetime updated_at
}
PERFORMANCE_PLANS ||--o{ PLAN_KPI_RELATIONS : contains
MENUS ||--o{ MENUS : children
DEPARTMENT_FINANCES }o--|| DEPARTMENTS : belongs_to
PLAN_KPI_RELATIONS }o--|| INDICATORS : links_to
PERFORMANCE_PLANS }o--|| DEPARTMENTS : belongs_to
PERFORMANCE_PLANS }o--|| STAFF : responsible_for
PERFORMANCE_PLANS }o--|| USERS : submitted_by
DEPARTMENT_FINANCES }o--|| DEPARTMENTS : belongs_to
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L270-L338)
- [finance.py](file://backend/app/models/finance.py#L45-L74)
**章节来源**
- [models.py](file://backend/app/models/models.py#L62-L438)
- [finance.py](file://backend/app/models/finance.py#L16-L79)
## 性能考虑
### 数据库性能优化
系统采用了多项数据库性能优化策略：
- **索引优化**：为常用查询字段建立复合索引
- **连接池管理**：配置合理的连接池大小和溢出限制
- **异步操作**：使用SQLAlchemy异步引擎提升并发性能
- **查询优化**：采用selectinload进行N+1查询优化
### 缓存策略
```mermaid
flowchart TD
Request[请求到达] --> CheckCache{检查缓存}
CheckCache --> |命中| ReturnCache[返回缓存数据]
CheckCache --> |未命中| QueryDB[查询数据库]
QueryDB --> ProcessData[处理数据]
ProcessData --> UpdateCache[更新缓存]
UpdateCache --> ReturnData[返回数据]
ReturnCache --> End[请求结束]
ReturnData --> End
```
### 异步处理
系统充分利用异步特性：
- **异步数据库操作**：避免阻塞主线程
- **异步文件处理**：支持大文件上传和下载
- **异步任务队列**：后台任务处理（如报表生成）
## 故障排除指南
### 常见问题诊断
#### 认证失败问题
当遇到认证失败时，检查以下方面：
1. **Token有效性**：确认Token未过期且格式正确
2. **用户状态**：验证用户账户是否被激活
3. **权限级别**：确认用户具有执行操作的权限
4. **JWT配置**：检查密钥和算法配置
#### 数据库连接问题
```mermaid
flowchart TD
ConnectFail[连接失败] --> CheckURL{检查数据库URL}
CheckURL --> URLCorrect{URL格式正确?}
URLCorrect --> |否| FixURL[修复数据库URL]
URLCorrect --> |是| CheckPool{检查连接池配置}
CheckPool --> PoolOK{连接池正常?}
PoolOK --> |否| AdjustPool[调整连接池参数]
PoolOK --> |是| CheckAuth{检查认证信息}
CheckAuth --> AuthOK{认证成功?}
AuthOK --> |否| FixAuth[修复认证信息]
AuthOK --> |是| Success[连接成功]
```
#### 权限控制问题
当权限控制出现问题时：
1. **检查用户角色**：确认用户角色设置正确
2. **验证菜单权限**：检查菜单的permission字段
3. **审查API装饰器**：确认使用了正确的权限装饰器
4. **查看日志信息**：分析认证和授权日志
**章节来源**
- [security.py](file://backend/app/core/security.py#L55-L110)
- [database.py](file://backend/app/core/database.py#L28-L39)
## 结论
本系统通过精心设计的三层架构，成功实现了医院绩效管理的核心功能。三大管理服务各司其职，既保持了高度的内聚性，又确保了适当的耦合度。
系统的主要优势包括：
- **模块化设计**：清晰的职责分离便于维护和扩展
- **安全性保障**：完善的认证授权机制确保系统安全
- **性能优化**：异步架构和数据库优化提升系统性能
- **可扩展性**：灵活的数据模型支持业务发展需求
通过持续的优化和完善，该系统能够有效支撑医院的绩效管理工作，为提升医疗服务质量提供有力的技术保障。

448
.qoder/repowiki/zh/content/后端开发指南/服务层开发/统计分析服务.md Normal file
View File

@@ -0,0 +1,448 @@
# 统计分析服务
<cite>
**本文引用的文件**
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py)
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py)
- [backend/app/models/models.py](file://backend/app/models/models.py)
- [backend/app/core/database.py](file://backend/app/core/database.py)
- [backend/app/core/config.py](file://backend/app/core/config.py)
- [backend/app/main.py](file://backend/app/main.py)
- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py)
- [docs/详细设计.md](file://docs/详细设计.md)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件面向“统计分析服务”的开发与使用，围绕 StatsService 类的实现原理展开，系统阐述多维度统计分析、数据聚合与报表生成能力，重点覆盖以下主题：
- BSC（平衡计分卡）维度分析：财务、客户、内部流程、学习与成长四个维度的指标计算与聚合
- 科室绩效统计：按科室汇总、平均分、最高/最低分、人员列表与排序
- 趋势分析：按月度的时间序列趋势（平均分、加权分）
- 排名统计：按加权分的绩效排名
- 指标完成度：指标平均分、最大/最小分、完成率
- 数据库交互模式、查询优化与潜在缓存策略
- 统计结果的数据格式化、图表数据准备与 API 接口设计
- 具体统计场景示例与性能考虑
## 项目结构
后端采用 FastAPI + SQLAlchemy 2.x 异步 ORM 的架构，统计分析服务位于服务层，API 层负责请求参数解析与响应封装，模型层定义数据结构与枚举，数据库层提供异步连接与会话管理。
```mermaid
graph TB
subgraph "应用层"
API["API 路由<br/>stats.py"]
SVC["服务层<br/>stats_service.py"]
end
subgraph "模型层"
MODELS["数据模型与枚举<br/>models.py"]
end
subgraph "基础设施"
CFG["配置<br/>config.py"]
DB["数据库连接<br/>database.py"]
MAIN["应用入口<br/>main.py"]
end
API --> SVC
SVC --> MODELS
API --> DB
SVC --> DB
DB --> CFG
MAIN --> API
```
**图表来源**
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L242)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
- [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/core/config.py](file://backend/app/core/config.py#L1-L47)
- [backend/app/main.py](file://backend/app/main.py#L1-L92)
**章节来源**
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L242)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
- [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/core/config.py](file://backend/app/core/config.py#L1-L47)
- [backend/app/main.py](file://backend/app/main.py#L1-L92)
## 核心组件
- StatsService：提供 BSC 维度统计、科室统计、趋势分析、排名、指标完成度等统计方法
- API 路由 stats.py：定义 /stats 前缀下的统计接口，负责参数校验、默认值处理与统一响应包装
- 数据模型与枚举：包含 BSC 维度、评估状态、科室类型、指标类型等，支撑统计逻辑
- 数据库与配置：异步连接、会话工厂、数据库 URL 与池参数
**章节来源**
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L16-L300)
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L242)
- [backend/app/models/models.py](file://backend/app/models/models.py#L29-L52)
## 架构总览
统计分析服务遵循“API → 服务 → 模型/数据库”的分层架构。API 层负责输入参数与响应格式标准化；服务层执行复杂聚合与计算；模型层提供数据结构与枚举；数据库层提供异步连接与事务管理。
```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "API(stats.py)"
participant Svc as "StatsService"
participant DB as "AsyncSession"
participant Model as "ORM模型"
Client->>API : GET /api/v1/stats/bsc-dimension
API->>API : 参数校验与默认值处理
API->>Svc : 调用 get_bsc_dimension_stats(...)
Svc->>DB : 异步查询SQLAlchemy select + func
DB->>Model : 映射到 Assessment/AssessmentDetail/Indicator/Department/Staff
Svc-->>API : 返回聚合结果
API-->>Client : 统一响应 {code,message,data}
```
**图表来源**
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L17-L33)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L19-L72)
- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L181)
## 详细组件分析
### StatsService 类与方法族
- get_bsc_dimension_stats：按 BSC 四维度聚合得分、权重与指标数量，计算平均分
- get_department_stats：按科室汇总人员、总分、平均分、最高/最低分与人员列表，并整体排序
- get_trend_stats：按月度聚合平均分与加权分，支持跨年范围与科室过滤
- get_ranking_stats：按加权分排名前 N 的员工
- get_completion_stats：按指标统计平均分、最大/最小分、完成率与样本数
```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
}
class Assessment {
+int id
+int staff_id
+int period_year
+int period_month
+float total_score
+float weighted_score
+AssessmentStatus status
}
class AssessmentDetail {
+int id
+int assessment_id
+int indicator_id
+float actual_value
+float score
}
class Indicator {
+int id
+string name
+string code
+IndicatorType indicator_type
+BSCDimension bs_dimension
+float weight
+float max_score
+float target_value
}
class Department {
+int id
+string name
+string code
+DeptType dept_type
}
class Staff {
+int id
+string employee_id
+string name
+int department_id
}
StatsService --> Assessment : "查询"
StatsService --> AssessmentDetail : "连接"
StatsService --> Indicator : "按维度聚合"
StatsService --> Department : "科室汇总"
StatsService --> Staff : "关联人员"
```
**图表来源**
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L16-L300)
- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L181)
**章节来源**
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L19-L299)
#### BSC 维度分析（get_bsc_dimension_stats）
- 输入：可选科室 ID、年、月
- 过滤：仅统计已确认的考核记录
- 聚合：按 BSC 维度分组，计算总分（加权）、总权重、指标数量与平均分
- 输出：包含各维度的得分、权重、指标数与平均分，以及统计周期
```mermaid
flowchart TD
Start(["进入 get_bsc_dimension_stats"]) --> BuildCond["构建查询条件<br/>状态=FINALIZED(+年+月+科室)"]
BuildCond --> ExecSel["执行聚合查询<br/>按维度分组(sum(score*weight), sum(weight), count)"]
ExecSel --> Iterate["遍历结果<br/>填充维度字典"]
Iterate --> CalcAvg["计算平均分=总分/总权重"]
CalcAvg --> Ret["返回 {dimensions, period}"]
```
**图表来源**
- [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#L19-L72)
#### 科室绩效统计（get_department_stats）
- 输入：年、月
- 过滤：仅统计已确认的考核记录
- 聚合：按科室汇总人员数、总分、平均分、最高/最低分，并收集人员得分列表
- 排序：按平均分降序
```mermaid
flowchart TD
S(["进入 get_department_stats"]) --> Q["查询关联数据<br/>Staff→Assessment→Department"]
Q --> Group["按科室分组聚合<br/>计数/求和/记录人员列表"]
Group --> Compute["计算平均分=总分/人数"]
Compute --> Sort["按平均分降序排序"]
Sort --> R(["返回科室统计列表"])
```
**图表来源**
- [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#L74-L146)
#### 趋势分析（get_trend_stats）
- 输入：可选科室 ID、年（为空则使用当前年）、月份数（默认 6）
- 范围：若未指定年份，按当前年份与最近 N 个月推导起止月份，支持跨年
- 聚合：按月度 group by，计算平均分与加权分、样本数
```mermaid
flowchart TD
Enter(["进入 get_trend_stats"]) --> YearCheck{"是否指定年份?"}
YearCheck -- 否 --> SetCur["设置为当前年份"]
YearCheck -- 是 --> KeepYear["使用传入年份"]
SetCur --> Range["计算起始月=当前月-N+1<br/>处理跨年"]
KeepYear --> Range
Range --> Cond["构造月份范围条件"]
Cond --> Join["连接 Staff 并过滤 FINALIZED"]
Join --> GroupBy["按月分组聚合"]
GroupBy --> Out(["返回月度趋势列表"])
```
**图表来源**
- [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#L148-L199)
#### 排名统计（get_ranking_stats）
- 输入：年、月、限制条数
- 过滤：仅统计已确认的考核记录
- 排序：按加权分降序，返回前 N 条并标注排名
```mermaid
sequenceDiagram
participant API as "API"
participant Svc as "StatsService"
participant DB as "AsyncSession"
API->>Svc : get_ranking_stats(year, month, limit)
Svc->>DB : select Staff/Assessment/Department
DB-->>Svc : 结果集
Svc-->>API : 按加权分降序，标注 rank
API-->>API : 统一响应
```
**图表来源**
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L201-L244)
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L210-L224)
**章节来源**
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L201-L244)
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L210-L224)
#### 指标完成度（get_completion_stats）
- 输入：可选指标 ID、年、月
- 过滤：仅统计已确认的考核记录
- 聚合：按指标 group by，计算平均分、最大/最小分、样本数与完成率（平均分/目标值）
```mermaid
flowchart TD
In(["进入 get_completion_stats"]) --> Cond["构造条件<br/>FINALIZED(+年+月+指标ID?)"]
Cond --> Sel["select 指标字段 + avg/max/min/count"]
Sel --> Group["group by 指标"]
Group --> Rate["完成率=avg/max(target_value)"]
Rate --> Ret(["返回指标完成度列表"])
```
**图表来源**
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L246-L299)
**章节来源**
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L246-L299)
### API 接口设计与数据格式
- 统一响应结构：包含 code、message、data 字段
- 参数校验与默认值：
- 年/月未传时，趋势与周期统计接口会使用当前年/月
- 排名与周期统计支持 limit 控制返回数量
- 接口一览：
- GET /stats/bsc-dimension：BSC 维度分析
- GET /stats/department：科室绩效统计
- GET /stats/trend：趋势分析（月度）
- GET /stats/department-ranking：科室绩效排名（前 N）
- GET /stats/ranking：个人绩效排名（前 N）
- GET /stats/completion：指标完成度
- GET /stats/period：周期统计（含汇总）
- GET /stats/alerts、/stats/kpi-gauges、/stats/finance-trend：预留接口（当前返回模拟数据）
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Router as "FastAPI 路由"
participant Handler as "stats.py 处理函数"
participant Svc as "StatsService"
participant DB as "AsyncSession"
Client->>Router : GET /api/v1/stats/bsc-dimension?year&month&dept_id
Router->>Handler : 参数解析与默认值
Handler->>Svc : 调用对应统计方法
Svc->>DB : 异步查询
DB-->>Svc : 结果
Svc-->>Handler : 聚合结果
Handler-->>Client : {code,message,data}
```
**图表来源**
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L17-L242)
**章节来源**
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L17-L242)
### 数据模型与枚举（支撑统计）
- BSCDimension：financial、customer、internal_process、learning_growth
- AssessmentStatus：FINALIZED 等
- DeptType、IndicatorType 等枚举用于过滤与分类
- 关键实体：Assessment、AssessmentDetail、Indicator、Department、Staff
```mermaid
classDiagram
class BSCDimension {
<<enum>>
+FINANCIAL
+CUSTOMER
+INTERNAL_PROCESS
+LEARNING_GROWTH
}
class AssessmentStatus {
<<enum>>
+FINALIZED
}
class DeptType {
<<enum>>
+CLINICAL_SURGICAL
+...
}
class IndicatorType {
<<enum>>
+QUALITY
+QUANTITY
+EFFICIENCY
+SERVICE
+COST
}
```
**图表来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L29-L61)
**章节来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L29-L61)
## 依赖分析
- 统计服务依赖 SQLAlchemy 异步会话与 ORM 模型，通过 select + func 实现聚合
- API 层依赖服务层与数据库会话注入
- 配置层提供数据库连接参数与池大小，影响并发与吞吐
```mermaid
graph LR
API["api/v1/stats.py"] --> SVC["services/stats_service.py"]
SVC --> MODELS["models/models.py"]
API --> DB["core/database.py"]
SVC --> DB
DB --> CFG["core/config.py"]
```
**图表来源**
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L242)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
- [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/core/config.py](file://backend/app/core/config.py#L1-L47)
**章节来源**
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L242)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
## 性能考量
- 查询优化
- 使用 group by 与聚合函数（sum、avg、count）减少应用侧循环计算
- 通过索引字段过滤（Assessment.status、Assessment.period_year/month、Assessment.staff_id）降低扫描范围
- 趋势分析中按月分组，避免大结果集内存占用
- 数据库连接与并发
- 异步连接与会话工厂支持高并发；数据库池参数可在配置中调优
- 缓存策略（建议）
- 对高频但不频繁变化的统计结果（如 BSC 维度、指标完成度）引入短期缓存（如 Redis）
- 按参数组合生成缓存键（年、月、科室、指标等）
- 响应格式化
- 将数值统一为浮点并限制精度，便于前端图表渲染
- 提供图表友好的数组结构（时间序列、排名列表）
[本节为通用性能指导，不直接分析具体文件]
## 故障排查指南
- 常见问题
- 参数缺失：年/月未传导致默认值逻辑异常，检查 API 层默认值处理
- 权限与认证：确保请求携带有效 Token
- 数据缺失：仅统计已确认的考核记录，若无数据请检查 Assessment.status
- 日志与异常
- 应用层已注册全局异常处理器，便于定位错误
- 建议在服务层增加关键步骤的日志输出（如查询条件、聚合结果规模）
**章节来源**
- [backend/app/main.py](file://backend/app/main.py#L58-L75)
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L52-L70)
## 结论
统计分析服务以 StatsService 为核心，围绕 BSC 四维度、科室统计、趋势分析、排名与指标完成度构建了完整的多维统计能力。通过 SQLAlchemy 异步 ORM 与合理的查询策略，实现了高效的数据聚合与报表生成。建议在生产环境中引入缓存与更细粒度的索引优化，并持续完善财务、预警与仪表盘等预留接口的实际数据来源。
[本节为总结性内容，不直接分析具体文件]
## 附录
### 统计场景示例
- BSC 维度分析：按月查看财务、客户、内部流程、学习与成长四个维度的加权得分与平均分
- 科室绩效：按月汇总各科室平均分、最高/最低分与人员列表，用于科室排名与改进
- 趋势分析：查看近 6 个月的平均分与加权分变化，识别波动与改善趋势
- 排名统计：查看个人绩效排名前 10 的员工及其所在科室
- 指标完成度：查看各指标的平均分、完成率与样本数，辅助指标优化
[本节为概念性场景说明，不直接分析具体文件]
### 与系统设计文档的对应关系
- 系统设计强调“多维度考核”“科学量化”“流程自动化”“报表与分析中心”，统计分析服务正对应“报表与分析中心”的实现。
**章节来源**
- [docs/详细设计.md](file://docs/详细设计.md#L155-L164)

473
.qoder/repowiki/zh/content/后端开发指南/服务层开发/考核服务.md Normal file
View File

@@ -0,0 +1,473 @@
# 考核服务
<cite>
**本文档引用的文件**
- [assessment_service.py](file://backend/app/services/assessment_service.py)
- [models.py](file://backend/app/models/models.py)
- [schemas.py](file://backend/app/schemas/schemas.py)
- [assessments.py](file://backend/app/api/v1/assessments.py)
- [database.py](file://backend/app/core/database.py)
- [security.py](file://backend/app/core/security.py)
- [config.py](file://backend/app/core/config.py)
- [main.py](file://backend/app/main.py)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 简介
考核服务是医院绩效管理系统的核心模块，负责管理员工的绩效考核流程。该服务实现了完整的考核生命周期管理，包括考核记录的CRUD操作、状态管理和流程控制。系统采用基于平衡计分卡（BSC）的多维度考核体系，支持多种科室类型的差异化考核需求。
## 项目结构
考核服务位于后端应用的服务层，采用清晰的分层架构设计：
```mermaid
graph TB
subgraph "API层"
A[API路由]
B[认证中间件]
end
subgraph "服务层"
C[AssessmentService]
D[其他服务]
end
subgraph "数据层"
E[模型定义]
F[数据库]
end
subgraph "配置层"
G[数据库配置]
H[安全配置]
I[应用配置]
end
A --> C
B --> A
C --> E
E --> F
G --> F
H --> A
I --> A
```
**图表来源**
- [assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
- [models.py](file://backend/app/models/models.py#L149-L203)
- [database.py](file://backend/app/core/database.py#L9-L39)
**章节来源**
- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [models.py](file://backend/app/models/models.py#L1-L438)
## 核心组件
### AssessmentService 类
AssessmentService 是考核服务的核心类，提供了完整的考核管理功能：
#### 主要职责
- 考核记录的创建、读取、更新、删除
- 考核状态的流转管理
- 考核分数的自动计算
- 批量考核创建功能
#### 关键特性
- 异步数据库操作支持
- 完整的状态机管理
- 自动化的分数计算
- 权限控制集成
**章节来源**
- [assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
## 架构概览
考核服务采用经典的三层架构模式，确保了良好的关注点分离：
```mermaid
sequenceDiagram
participant Client as 客户端
participant API as API路由
participant Service as AssessmentService
participant DB as 数据库
participant Model as 数据模型
Client->>API : HTTP请求
API->>Service : 调用服务方法
Service->>DB : 执行数据库操作
DB->>Model : 映射数据模型
Model-->>DB : 返回实体对象
DB-->>Service : 返回查询结果
Service-->>API : 返回业务结果
API-->>Client : HTTP响应
```
**图表来源**
- [assessments.py](file://backend/app/api/v1/assessments.py#L20-L166)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L17-L263)
## 详细组件分析
### 数据模型设计
#### Assessment 模型
Assessment 模型代表一条完整的考核记录，包含以下关键字段：
```mermaid
classDiagram
class Assessment {
+int id
+int staff_id
+int period_year
+int period_month
+string period_type
+float total_score
+float weighted_score
+AssessmentStatus status
+int assessor_id
+int reviewer_id
+datetime submit_time
+datetime review_time
+string remark
+datetime created_at
+datetime updated_at
}
class AssessmentDetail {
+int id
+int assessment_id
+int indicator_id
+float actual_value
+float score
+string evidence
+string remark
+datetime created_at
+datetime updated_at
}
class Staff {
+int id
+string employee_id
+string name
+int department_id
+string position
+string title
+string phone
+string email
+float base_salary
+float performance_ratio
+StaffStatus status
+datetime hire_date
}
class Indicator {
+int id
+string name
+string code
+IndicatorType indicator_type
+BSCDimension bs_dimension
+float weight
+float max_score
+float target_value
+string target_unit
+string calculation_method
+string assessment_method
+string deduction_standard
+string data_source
+string applicable_dept_types
+bool is_veto
+bool is_active
}
Assessment "1" -- "many" AssessmentDetail : "包含"
Assessment "1" -- "1" Staff : "关联"
AssessmentDetail "1" -- "1" Indicator : "关联"
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L149-L203)
- [models.py](file://backend/app/models/models.py#L181-L203)
#### AssessmentStatus 状态枚举
考核状态采用严格的有限状态机设计：
```mermaid
stateDiagram-v2
[*] --> DRAFT : 创建
DRAFT --> SUBMITTED : 提交
SUBMITTED --> REVIEWED : 审核通过
SUBMITTED --> REJECTED : 审核驳回
REVIEWED --> FINALIZED : 确认
REJECTED --> DRAFT : 修改后重新提交
FINALIZED --> [*] : 结束
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L45-L52)
**章节来源**
- [models.py](file://backend/app/models/models.py#L149-L203)
- [models.py](file://backend/app/models/models.py#L45-L52)
### 核心业务方法详解
#### 1. 列表查询方法
`get_list()` 方法提供了灵活的考核记录查询功能：
**功能特点：**
- 多条件过滤支持（员工ID、科室ID、年度、月份、状态）
- 分页查询支持
- 性能优化的子查询统计
- 关联数据预加载
**查询逻辑：**
```mermaid
flowchart TD
Start([开始查询]) --> BuildQuery["构建基础查询"]
BuildQuery --> CheckFilters{"是否有过滤条件?"}
CheckFilters --> |是| ApplyFilters["应用过滤条件"]
CheckFilters --> |否| CountQuery["构建统计查询"]
ApplyFilters --> CountQuery
CountQuery --> Pagination["应用分页"]
Pagination --> ExecuteQuery["执行查询"]
ExecuteQuery --> ReturnResults["返回结果"]
ReturnResults --> End([结束])
```
**图表来源**
- [assessment_service.py](file://backend/app/services/assessment_service.py#L18-L56)
**章节来源**
- [assessment_service.py](file://backend/app/services/assessment_service.py#L18-L56)
#### 2. 详情获取方法
`get_by_id()` 方法提供了完整的考核详情查询：
**功能特点：**
- 关联员工信息查询
- 考核明细及指标信息加载
- 预加载优化减少N+1查询
**章节来源**
- [assessment_service.py](file://backend/app/services/assessment_service.py#L58-L68)
#### 3. 创建考核方法
`create()` 方法实现了完整的考核创建流程：
**核心算法：**
1. 计算总分：所有明细得分的简单求和
2. 计算加权得分：每个指标得分乘以其权重后的总和
3. 创建主记录和明细记录
4. 自动设置初始状态为草稿
**分数计算公式：**
- 总分 = Σ(明细得分)
- 加权得分 = Σ(明细得分 × 指标权重)
**章节来源**
- [assessment_service.py](file://backend/app/services/assessment_service.py#L71-L108)
#### 4. 更新考核方法
`update()` 方法提供了受控的考核更新功能：
**状态限制：**
- 仅允许草稿和被驳回状态的记录进行更新
- 更新时会删除旧的考核明细并重新创建
**更新流程：**
```mermaid
flowchart TD
Start([开始更新]) --> LoadAssessment["加载考核记录"]
LoadAssessment --> CheckStatus{"状态是否允许更新?"}
CheckStatus --> |否| ReturnNull["返回None"]
CheckStatus --> |是| DeleteOldDetails["删除旧明细"]
DeleteOldDetails --> RecalculateScores["重新计算分数"]
RecalculateScores --> UpdateFields["更新其他字段"]
UpdateFields --> SaveChanges["保存更改"]
SaveChanges --> ReturnAssessment["返回更新后的记录"]
ReturnNull --> End([结束])
ReturnAssessment --> End
```
**图表来源**
- [assessment_service.py](file://backend/app/services/assessment_service.py#L111-L156)
**章节来源**
- [assessment_service.py](file://backend/app/services/assessment_service.py#L111-L156)
#### 5. 流程控制方法
##### 提交方法 (`submit`)
将草稿状态的考核记录提交到审核流程。
##### 审核方法 (`review`)
管理员或经理对提交的考核进行审核：
- 通过：状态转为已审核
- 驳回：状态转为被驳回并可添加审核意见
##### 确认方法 (`finalize`)
最终确认已审核的考核记录，状态转为已确认。
**章节来源**
- [assessment_service.py](file://backend/app/services/assessment_service.py#L159-L205)
#### 6. 批量创建方法
`batch_create_for_department()` 实现了高效的批量考核创建：
**功能特点：**
- 为指定科室的所有在职员工批量创建考核
- 自动检查重复创建
- 为每个员工创建相同的考核指标模板
**使用场景：**
- 月末批量创建员工考核
- 新指标模板上线时的批量创建
- 年度考核周期开始时的批量初始化
**章节来源**
- [assessment_service.py](file://backend/app/services/assessment_service.py#L208-L262)
### API 接口设计
#### RESTful API 规范
| 接口 | 方法 | 权限 | 功能描述 |
|------|------|------|----------|
| `/assessments` | GET | 任意用户 | 获取考核列表 |
| `/assessments` | POST | 普通用户 | 创建考核记录 |
| `/assessments/{id}` | GET | 任意用户 | 获取考核详情 |
| `/assessments/{id}` | PUT | 普通用户 | 更新考核记录 |
| `/assessments/{id}/submit` | POST | 普通用户 | 提交考核 |
| `/assessments/{id}/review` | POST | 管理员/经理 | 审核考核 |
| `/assessments/{id}/finalize` | POST | 管理员/经理 | 确认考核 |
| `/assessments/batch-create` | POST | 管理员/经理 | 批量创建考核 |
**章节来源**
- [assessments.py](file://backend/app/api/v1/assessments.py#L20-L166)
## 依赖关系分析
### 外部依赖
```mermaid
graph LR
subgraph "核心依赖"
A[SQLAlchemy 2.0]
B[FastAPI]
C[Pydantic]
D[PostgreSQL]
end
subgraph "服务层"
E[AssessmentService]
F[其他业务服务]
end
subgraph "数据层"
G[模型定义]
H[数据库连接]
end
E --> A
E --> G
F --> A
G --> H
H --> D
B --> C
```
**图表来源**
- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L12)
- [database.py](file://backend/app/core/database.py#L4-L20)
### 内部依赖关系
```mermaid
graph TD
A[AssessmentService] --> B[Assessment 模型]
A --> C[AssessmentDetail 模型]
A --> D[Staff 模型]
A --> E[Indicator 模型]
A --> F[AssessmentStatus 枚举]
A --> G[数据库会话]
H[API路由] --> A
I[安全模块] --> H
J[配置模块] --> H
K[数据库配置] --> G
```
**图表来源**
- [assessment_service.py](file://backend/app/services/assessment_service.py#L10-L11)
- [assessments.py](file://backend/app/api/v1/assessments.py#L14-L15)
**章节来源**
- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L12)
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L17)
## 性能考虑
### 数据库优化策略
1. **索引优化**
- 考核记录按员工ID、年度月份、状态建立复合索引
- 考核明细按考核记录ID、指标ID建立索引
2. **查询优化**
- 使用 selectinload 进行关联数据预加载
- 子查询统计避免全表扫描
3. **连接池管理**
- 异步连接池配置
- 连接超时和重试机制
### 缓存策略
- 使用 LRU 缓存存储常用配置
- 数据库查询结果缓存（可选）
### 异步处理
- 全面采用异步数据库操作
- 避免阻塞式I/O操作
## 故障排除指南
### 常见问题及解决方案
#### 1. 考核状态错误
**问题：** 尝试在不允许的状态下更新或操作考核
**解决方案：** 检查当前状态是否符合操作要求
#### 2. 权限不足
**问题：** 审核或确认操作返回403错误
**解决方案：** 确认当前用户具有管理员或经理权限
#### 3. 数据库连接问题
**问题：** 数据库操作失败
**解决方案：** 检查数据库连接配置和网络连通性
#### 4. 分页查询异常
**问题：** 分页参数无效导致查询错误
**解决方案：** 验证页码和每页数量参数范围
**章节来源**
- [assessment_service.py](file://backend/app/services/assessment_service.py#L117-L118)
- [security.py](file://backend/app/core/security.py#L94-L109)
## 结论
考核服务通过精心设计的架构和完善的业务逻辑，为医院绩效管理提供了强大的技术支持。系统的主要优势包括：
1. **完整的生命周期管理**：从创建到确认的完整流程覆盖
2. **灵活的查询能力**：支持多维度、多条件的复杂查询
3. **严格的状态控制**：确保业务流程的合规性
4. **高效的批量处理**：支持大规模数据的批量操作
5. **完善的权限控制**：基于角色的精细化权限管理
该服务为后续的薪资计算、统计分析等功能奠定了坚实的基础，是整个绩效管理系统的核心支柱。

423
.qoder/repowiki/zh/content/后端开发指南/服务层开发/部门员工服务.md Normal file
View File

@@ -0,0 +1,423 @@
# 部门员工服务
<cite>
**本文引用的文件**
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py)
- [backend/app/models/models.py](file://backend/app/models/models.py)
- [backend/app/models/finance.py](file://backend/app/models/finance.py)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py)
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.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/core/config.py](file://backend/app/core/config.py)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件面向“部门与员工服务”的开发与运维，围绕 DepartmentService 与 StaffService 的实现架构进行系统化说明。内容涵盖：
- 部门管理：树形结构管理、层级关系维护、增删改查与有效性校验
- 员工管理：信息维护、职位与职称字段、基本工资与绩效系数、状态管理
- 数据模型关系映射：部门与员工的外键约束、索引与级联策略
- 高级能力：树形查询、分页与统计、权限控制、事务处理
- 实际业务场景示例与最佳实践
## 项目结构
后端采用 FastAPI + SQLAlchemy Async 异步 ORM 架构，服务层位于 app/services，API 路由位于 app/api/v1，数据模型位于 app/models，配置与安全位于 app/core。
```mermaid
graph TB
subgraph "API 层"
A1["/api/v1/departments.py"]
A2["/api/v1/staff.py"]
end
subgraph "服务层"
S1["services/department_service.py"]
S2["services/staff_service.py"]
end
subgraph "模型层"
M1["models/models.py"]
M2["models/finance.py"]
end
subgraph "基础设施"
C1["core/config.py"]
C2["core/database.py"]
C3["core/security.py"]
end
A1 --> S1
A2 --> S2
S1 --> M1
S2 --> M1
M1 --> C2
M2 --> C2
C1 --> C2
C1 --> C3
```
图表来源
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L1-L108)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L1-L124)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L1-L150)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L114)
- [backend/app/models/finance.py](file://backend/app/models/finance.py#L45-L74)
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
章节来源
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L1-L108)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L1-L124)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L1-L150)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L114)
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
## 核心组件
- DepartmentService：提供科室列表、树形结构、按编码/ID 查询、创建、更新、删除等能力；自动计算层级并校验删除前置条件（无子部门）
- StaffService：提供员工列表、按工号/ID 查询、创建、更新、删除、按科室查询在职员工等能力
- 数据模型 Department/Staff：定义字段、枚举、索引与关系；Department 与 Staff 通过外键建立一对多关系
- API 路由：提供 REST 接口，绑定权限装饰器，调用服务层并返回统一响应格式
- 安全与配置：JWT 认证、权限校验、数据库连接池与事务管理
章节来源
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L13-L150)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L114)
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L19-L107)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L20-L123)
- [backend/app/core/security.py](file://backend/app/core/security.py#L85-L110)
- [backend/app/core/database.py](file://backend/app/core/database.py#L28-L39)
## 架构总览
部门与员工服务遵循“API → 服务 → 模型 → 数据库”的分层架构，配合统一响应体与权限控制，确保数据一致性与安全性。
```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "FastAPI 路由"
participant Service as "服务层"
participant DB as "数据库"
Client->>API : "HTTP 请求"
API->>API : "权限校验(Active/Manager)"
API->>Service : "调用服务方法(参数校验)"
Service->>DB : "SQL 查询/写入(异步)"
DB-->>Service : "结果集/受影响行"
Service-->>API : "领域对象/聚合"
API-->>Client : "统一响应体(code,message,data,total/page/page_size)"
```
图表来源
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L19-L107)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L20-L123)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L16-L111)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L16-L101)
- [backend/app/core/database.py](file://backend/app/core/database.py#L28-L39)
## 详细组件分析
### 部门服务 DepartmentService
- 列表查询：支持按类型与启用状态过滤、分页与总数统计
- 树形结构：手动构建树，避免懒加载导致的 N+1 问题
- 创建逻辑：根据父级计算层级 level，插入后刷新实体
- 删除逻辑：先检查是否存在子部门，避免破坏树形结构
- 更新与查询：按 ID/编码查询，支持部分字段更新
```mermaid
classDiagram
class DepartmentService {
+get_list(db, dept_type, is_active, page, page_size) tuple
+get_by_id(db, dept_id) Department?
+get_by_code(db, code) Department?
+create(db, dept_data) Department
+update(db, dept_id, dept_data) Department?
+delete(db, dept_id) bool
+get_tree(db, dept_type) DepartmentTree[]
}
class Department {
+id : int
+name : string
+code : string
+dept_type : DeptType
+parent_id : int?
+level : int
+sort_order : int
+is_active : bool
+description : string?
+children : Department[]
+staff : Staff[]
}
DepartmentService --> Department : "读写/树构建"
```
图表来源
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L13-L150)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L85)
章节来源
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L16-L149)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L85)
### 员工服务 StaffService
- 列表查询：支持按科室、状态、关键词搜索；预加载部门关系
- 详情查询：按 ID 查询并注入部门名称
- 创建/更新/删除：基础 CRUD；删除不涉及子记录级联
- 按科室查询：筛选在职员工
```mermaid
classDiagram
class StaffService {
+get_list(db, department_id, status, keyword, page, page_size) tuple
+get_by_id(db, staff_id) Staff?
+get_by_employee_id(db, employee_id) Staff?
+create(db, staff_data) Staff
+update(db, staff_id, staff_data) Staff?
+delete(db, staff_id) bool
+get_by_department(db, department_id) Staff[]
}
class Staff {
+id : int
+employee_id : string
+name : string
+department_id : int
+position : string
+title : string?
+phone : string?
+email : string?
+base_salary : float
+performance_ratio : float
+status : StaffStatus
+hire_date : datetime?
+department : Department
+assessments : Assessment[]
+salary_records : SalaryRecord[]
}
StaffService --> Staff : "读写/关联查询"
```
图表来源
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L114)
章节来源
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L16-L111)
- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L114)
### 数据模型与关系映射
- Department 与 Staff：一对多外键关联，Department 作为父表，Staff 通过 department_id 关联
- 索引：部门表对类型与父级建立索引；员工表对部门与状态建立索引
- 枚举：科室类型、员工状态、考核状态、指标类型等
- 财务模型：DepartmentFinance 与 Department 建立一对多关系，用于科室财务核算
```mermaid
erDiagram
DEPARTMENTS {
int id PK
string name
string code UK
enum dept_type
int parent_id FK
int level
int sort_order
bool is_active
text description
datetime created_at
datetime updated_at
}
STAFF {
int id PK
string employee_id UK
string name
int department_id FK
string position
string title
string phone
string email
numeric base_salary
numeric performance_ratio
enum status
datetime hire_date
datetime created_at
datetime updated_at
}
DEPARTMENTS ||--o{ STAFF : "拥有"
```
图表来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L114)
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L114)
### API 路由与权限控制
- 部门路由：列表、树形、详情、创建、更新、删除；创建/更新/删除需管理员或经理权限
- 员工路由：列表、详情、创建、更新、删除、按科室查询；创建/更新/删除需管理员或经理权限
- 统一响应：code/message/data/total/page/page_size
- 权限装饰器：get_current_active_user 与 get_current_manager_user
```mermaid
sequenceDiagram
participant Client as "客户端"
participant DeptAPI as "部门路由"
participant StaffAPI as "员工路由"
participant Sec as "安全模块"
participant Svc as "服务层"
Client->>DeptAPI : "POST /api/v1/departments"
DeptAPI->>Sec : "get_current_manager_user()"
Sec-->>DeptAPI : "用户(管理员/经理)"
DeptAPI->>Svc : "DepartmentService.create()"
Svc-->>DeptAPI : "Department"
DeptAPI-->>Client : "统一响应"
Client->>StaffAPI : "POST /api/v1/staff"
StaffAPI->>Sec : "get_current_manager_user()"
Sec-->>StaffAPI : "用户(管理员/经理)"
StaffAPI->>Svc : "StaffService.create()"
Svc-->>StaffAPI : "Staff"
StaffAPI-->>Client : "统一响应"
```
图表来源
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L67-L80)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L68-L81)
- [backend/app/core/security.py](file://backend/app/core/security.py#L85-L110)
章节来源
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L19-L107)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L20-L123)
- [backend/app/core/security.py](file://backend/app/core/security.py#L85-L110)
### 处理流程与算法
#### 部门树形构建流程
```mermaid
flowchart TD
Start(["进入 get_tree"]) --> Query["查询所有部门并排序"]
Query --> BuildMap["构建 id->DepartmentTree 映射"]
BuildMap --> Iterate["遍历部门构造树节点"]
Iterate --> HasParent{"存在父节点?"}
HasParent --> |是| AppendChild["加入父节点 children"]
HasParent --> |否| AddRoot["加入根节点列表"]
AppendChild --> Next["下一个部门"]
AddRoot --> Next
Next --> Done(["返回根节点树"])
```
图表来源
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L113-L149)
章节来源
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L113-L149)
#### 删除部门前置校验流程
```mermaid
flowchart TD
Start(["进入 delete"]) --> Load["按 ID 加载部门"]
Load --> Exists{"是否存在?"}
Exists --> |否| Fail["返回 False"]
Exists --> |是| CountChildren["统计子部门数量"]
CountChildren --> HasChild{"是否有子部门?"}
HasChild --> |是| Block["返回 False(不可删除)"]
HasChild --> |否| Remove["删除部门并返回 True"]
```
图表来源
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L96-L110)
章节来源
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L96-L110)
## 依赖分析
- 服务层依赖模型层（ORM 映射）与数据库会话（异步）
- API 层依赖服务层与安全模块（权限校验）
- 配置模块提供数据库 URL、JWT 参数与分页默认值
- 数据库模块提供异步引擎与会话生命周期（commit/rollback/close）
```mermaid
graph LR
API_D["/api/v1/departments.py"] --> SVC_D["services/department_service.py"]
API_S["/api/v1/staff.py"] --> SVC_S["services/staff_service.py"]
SVC_D --> MODELS["models/models.py"]
SVC_S --> MODELS
MODELS --> DB["core/database.py"]
API_D --> SEC["core/security.py"]
API_S --> SEC
CFG["core/config.py"] --> DB
CFG --> SEC
```
图表来源
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L1-L108)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L1-L124)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L1-L150)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
- [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/core/security.py](file://backend/app/core/security.py#L1-L110)
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
章节来源
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
## 性能考虑
- 异步数据库：使用 AsyncSession 提升并发吞吐
- 分页与统计：列表查询先统计总数再分页，避免全量扫描
- 关系预加载：员工列表预加载部门关系，减少 N+1 查询
- 索引优化：部门类型与父级、员工部门与状态建立索引
- 事务边界：每个请求会话在依赖中 commit/rollback，异常自动回滚
- 连接池：配置池大小与溢出，避免高并发下的连接争用
章节来源
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L26-L49)
- [backend/app/models/models.py](file://backend/app/models/models.py#L82-L85)
- [backend/app/models/models.py](file://backend/app/models/models.py#L112-L114)
## 故障排查指南
- 404 未找到：查询员工或部门不存在时返回 404
- 400 编码冲突：创建部门/员工时编码或工号重复
- 400 无法删除：删除部门时存在子部门
- 403 权限不足：非管理员/经理用户尝试创建/更新/删除
- 500 服务器错误：数据库异常触发回滚并抛出
章节来源
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L62-L107)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L75-L108)
- [backend/app/core/security.py](file://backend/app/core/security.py#L94-L110)
- [backend/app/core/database.py](file://backend/app/core/database.py#L34-L36)
## 结论
DepartmentService 与 StaffService 通过清晰的分层与严格的权限控制，实现了部门与员工的基础管理能力，并以树形结构与分页查询满足了常见的组织管理需求。结合模型层的索引与关系设计，以及异步数据库与事务管理，系统具备良好的扩展性与稳定性。建议后续在批量导入导出、数据同步与审计日志方面继续完善。
## 附录
### 统一响应体与分页
- 响应体包含 code、message、data、total、page、page_size
- 分页参数默认值与最大值由配置提供
章节来源
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L49-L60)
- [backend/app/core/config.py](file://backend/app/core/config.py#L31-L33)
### 数据模型枚举参考
- 科室类型：临床、医技、护理、行政、财务、后勤等
- 员工状态：在职、休假、离职、退休
- 考核状态：草稿、已提交、已审核、已确认、已驳回
- 指标类型：质量、数量、效率、服务、成本
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L16-L52)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L12-L45)