提交文件

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/API接口文档/考核管理接口.md
+++ b/.qoder/repowiki/zh/content/API接口文档/考核管理接口.md
@@ -0,0 +1,495 @@
+# 考核管理接口
+
+<cite>
+**本文档引用的文件**
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py)
+- [backend/app/api/v1/performance_plans.py](file://backend/app/api/v1/performance_plans.py)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py)
+- [backend/app/services/performance_plan_service.py](file://backend/app/services/performance_plan_service.py)
+- [backend/app/models/models.py](file://backend/app/models/models.py)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py)
+- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py)
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py)
+- [backend/app/api/v1/finance.py](file://backend/app/api/v1/finance.py)
+- [backend/app/services/finance_service.py](file://backend/app/services/finance_service.py)
+- [backend/app/models/finance.py](file://backend/app/models/finance.py)
+- [docs/详细设计.md](file://docs/详细设计.md)
+- [docs/api.md](file://docs/api.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+
+本项目是一个基于FastAPI的医院绩效管理系统，专注于构建完整的绩效考核管理接口。系统采用现代化的分层架构设计，包含三个核心功能模块：
+
+- **考核记录管理**：负责员工绩效考核的全流程管理，包括草稿保存、提交审核、审核通过、确认完成等状态转换
+- **考核明细处理**：管理具体的考核指标明细，支持批量操作和历史记录查询
+- **绩效计划管理**：涵盖医院级、科室级、个人级的多层次绩效计划制定、审批和执行
+
+系统实现了完整的绩效管理闭环，从指标定义到结果应用，支持与工资核算系统的深度集成，为医院建立科学的激励约束机制提供技术支撑。
+
+## 项目结构
+
+系统采用典型的三层架构设计，遵循RESTful API设计原则：
+
+```mermaid
+graph TB
+subgraph "表现层 (API层)"
+A[Assessment API]
+B[Performance Plan API]
+C[Salary API]
+D[Finance API]
+end
+subgraph "业务逻辑层 (Service层)"
+E[Assessment Service]
+F[Performance Plan Service]
+G[Salary Service]
+H[Finance Service]
+end
+subgraph "数据访问层 (Model层)"
+I[Assessment Model]
+J[Performance Plan Model]
+K[Salary Record Model]
+L[Finance Model]
+end
+A --> E
+B --> F
+C --> G
+D --> H
+E --> I
+F --> J
+G --> K
+H --> L
+I --> J
+K --> L
+```
+
+**图表来源**
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
+- [backend/app/api/v1/performance_plans.py](file://backend/app/api/v1/performance_plans.py#L1-L310)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
+- [backend/app/services/performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L1-L342)
+
+**章节来源**
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
+- [backend/app/api/v1/performance_plans.py](file://backend/app/api/v1/performance_plans.py#L1-L310)
+
+## 核心组件
+
+### 考核管理模块
+
+考核管理模块提供完整的绩效考核生命周期管理，支持多层级的状态流转和权限控制：
+
+- **状态管理**：草稿(draft) → 已提交(submitted) → 已审核(reviewed) → 已确认(finalized) → 已驳回(rejected)
+- **权限控制**：不同状态支持不同角色的操作权限
+- **批量操作**：支持批量创建考核记录和批量生成工资记录
+- **历史追踪**：完整的操作日志和状态变更记录
+
+### 绩效计划模块
+
+绩效计划模块实现多层次的计划管理体系：
+
+- **计划层级**：医院级(hospital) → 科室级(department) → 个人级(individual)
+- **状态流程**：草稿(draft) → 待审批(pending) → 已批准(approved) → 执行中(active) → 已完成(completed)
+- **指标关联**：支持计划与KPI指标的灵活关联和权重配置
+- **版本管理**：支持计划的版本控制和历史追溯
+
+### 工资核算模块
+
+工资核算模块与考核结果深度集成：
+
+- **自动计算**：基于考核得分自动计算绩效奖金
+- **系数应用**：结合员工绩效系数和个人基本工资
+- **批量处理**：支持科室级批量生成工资记录
+- **状态管理**：pending → confirmed 的确认流程
+
+**章节来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L45-L51)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L233-L242)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L231)
+
+## 架构概览
+
+系统采用分层架构设计，确保职责分离和代码可维护性：
+
+```mermaid
+sequenceDiagram
+participant Client as 客户端
+participant API as API层
+participant Service as 服务层
+participant Model as 模型层
+participant DB as 数据库
+Client->>API : 发起考核请求
+API->>Service : 调用业务逻辑
+Service->>Model : 操作数据模型
+Model->>DB : 执行数据库操作
+DB-->>Model : 返回查询结果
+Model-->>Service : 返回业务数据
+Service-->>API : 返回处理结果
+API-->>Client : 返回响应数据
+Note over Client,DB : 完整的CRUD操作流程
+```
+
+**图表来源**
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L80-L103)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L71-L108)
+
+系统还实现了异步数据库操作，支持高并发场景下的性能优化：
+
+```mermaid
+graph LR
+A[异步数据库连接池] --> B[SQLAlchemy AsyncSession]
+B --> C[查询操作]
+B --> D[事务处理]
+C --> E[结果返回]
+D --> E
+style A fill:#e1f5fe
+style B fill:#f3e5f5
+style E fill:#e8f5e8
+```
+
+**图表来源**
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L6-L8)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L11)
+
+## 详细组件分析
+
+### 考核记录管理
+
+#### 接口设计
+
+考核管理模块提供了完整的RESTful API接口：
+
+| 功能 | 方法 | 路径 | 描述 |
+|------|------|------|------|
+| 获取考核列表 | GET | `/assessments` | 支持多条件查询和分页 |
+| 获取考核详情 | GET | `/assessments/{id}` | 返回完整考核信息 |
+| 创建考核记录 | POST | `/assessments` | 创建新的考核记录 |
+| 更新考核记录 | PUT | `/assessments/{id}` | 更新现有考核记录 |
+| 提交考核 | POST | `/assessments/{id}/submit` | 提交待审核 |
+| 审核考核 | POST | `/assessments/{id}/review` | 审核通过或驳回 |
+| 确认考核 | POST | `/assessments/{id}/finalize` | 确认完成 |
+| 批量创建 | POST | `/assessments/batch-create` | 批量创建考核 |
+
+#### 状态转换流程
+
+```mermaid
+stateDiagram-v2
+[*] --> 草稿
+草稿 --> 已提交 : 提交考核
+已提交 --> 已审核 : 审核通过
+已提交 --> 已驳回 : 审核驳回
+已审核 --> 已确认 : 确认完成
+已确认 --> [*]
+已驳回 --> 草稿 : 修改后重新提交
+note right of 草稿 : 可编辑状态
+note right of 已提交 : 等待审核
+note right of 已审核 : 审核完成
+note right of 已确认 : 最终状态
+note right of 已驳回 : 需要修改
+```
+
+**图表来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L45-L51)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L159-L205)
+
+#### 评分计算逻辑
+
+系统实现了灵活的评分计算机制：
+
+```mermaid
+flowchart TD
+A[开始计算] --> B[遍历考核明细]
+B --> C[获取指标权重]
+C --> D[计算加权得分]
+D --> E[累加总分]
+E --> F[设置状态]
+F --> G[保存记录]
+G --> H[结束]
+D --> I[加权得分 = 明细得分 × 指标权重]
+E --> J[总分 = 所有明细得分之和]
+style I fill:#fff3e0
+style J fill:#fff3e0
+```
+
+**图表来源**
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L74-L84)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L129-L149)
+
+**章节来源**
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L20-L166)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L18-L263)
+
+### 绩效计划管理
+
+#### 计划层级结构
+
+系统支持多层级的绩效计划管理：
+
+```mermaid
+graph TD
+A[医院级计划] --> B[科室级计划]
+B --> C[个人级计划]
+A --> D[年度计划]
+A --> E[月度计划]
+B --> F[季度计划]
+B --> G[专项计划]
+C --> H[个人目标]
+C --> I[能力发展计划]
+style A fill:#ffebee
+style B fill:#e8f5e8
+style C fill:#e3f2fd
+```
+
+**图表来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L263-L268)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L233-L242)
+
+#### 计划审批流程
+
+```mermaid
+sequenceDiagram
+participant Creator as 计划创建者
+participant Manager as 科室负责人
+participant Leader as 分管院领导
+participant Office as 绩效办
+Creator->>Manager : 提交计划
+Manager->>Leader : 审批请求
+Leader->>Office : 最终审批
+Office->>Creator : 审批结果
+Note over Creator,Office : 多级审批流程
+```
+
+**图表来源**
+- [backend/app/api/v1/performance_plans.py](file://backend/app/api/v1/performance_plans.py#L194-L226)
+- [backend/app/services/performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L144-L182)
+
+**章节来源**
+- [backend/app/api/v1/performance_plans.py](file://backend/app/api/v1/performance_plans.py#L21-L310)
+- [backend/app/services/performance_plan_service.py](file://backend/app/services/performance_plan_service.py#L18-L342)
+
+### 工资核算集成
+
+#### 薪酬计算公式
+
+系统实现了标准化的薪酬计算机制：
+
+```mermaid
+flowchart LR
+A[基本工资] --> C[总薪酬计算]
+B[绩效奖金] --> C
+D[补贴] --> C
+E[扣款] --> C
+C --> F[应发工资 = 基本工资 + 绩效奖金 + 补贴 - 扣款]
+G[绩效得分] --> H[绩效奖金计算]
+I[绩效系数] --> H
+H --> B
+H --> J[绩效奖金 = 基础基数 × (绩效得分/100) × 绩效系数]
+style J fill:#fff8e1
+style F fill:#e8f5e8
+```
+
+**图表来源**
+- [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)
+
+#### 自动化生成流程
+
+```mermaid
+sequenceDiagram
+participant HR as 人事系统
+participant Perf as 绩效系统
+participant Payroll as 工资系统
+participant Finance as 财务系统
+HR->>Perf : 触发工资生成
+Perf->>Perf : 查询已确认考核
+Perf->>Perf : 计算绩效奖金
+Perf->>Payroll : 创建工资记录
+Payroll->>Finance : 生成发放清单
+Finance-->>HR : 薪资发放完成
+Note over HR,Finance : 完整的薪资发放流程
+```
+
+**图表来源**
+- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L96-L130)
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L127-L219)
+
+**章节来源**
+- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L20-L156)
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L14-L260)
+
+## 依赖关系分析
+
+系统采用清晰的依赖层次结构，确保模块间的松耦合：
+
+```mermaid
+graph TB
+subgraph "外部依赖"
+A[FastAPI]
+B[SQLAlchemy]
+C[AsyncIO]
+D[Pydantic]
+end
+subgraph "核心模块"
+E[API层]
+F[服务层]
+G[模型层]
+H[Schema层]
+end
+subgraph "数据库层"
+I[Assessment表]
+J[PerformancePlan表]
+K[SalaryRecord表]
+L[Finance表]
+end
+A --> E
+B --> F
+C --> F
+D --> H
+E --> F
+F --> G
+G --> H
+G --> I
+G --> J
+G --> K
+G --> L
+style A fill:#e3f2fd
+style B fill:#e8f5e8
+style E fill:#fff3e0
+style F fill:#f3e5f5
+style G fill:#e0f2f1
+```
+
+**图表来源**
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L17)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L11)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L14)
+
+### 权限控制机制
+
+系统实现了基于角色的权限控制(RBAC)：
+
+| 角色 | 权限范围 | 可执行操作 |
+|------|----------|------------|
+| staff | 普通员工 | 查看自己的考核记录 |
+| manager | 科室负责人 | 审核下级考核、管理科室计划 |
+| admin | 系统管理员 | 完全权限，包括数据维护 |
+
+**章节来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L124-L139)
+
+## 性能考虑
+
+### 数据库优化
+
+系统采用了多项性能优化策略：
+
+1. **索引优化**：为常用查询字段建立复合索引
+2. **异步操作**：使用async/await模式提高并发处理能力
+3. **连接池**：配置数据库连接池减少连接开销
+4. **分页查询**：默认每页20条记录，支持最大100条限制
+
+### 缓存策略
+
+```mermaid
+graph LR
+A[请求缓存] --> B[查询缓存]
+B --> C[会话缓存]
+C --> D[响应缓存]
+E[热点数据] --> F[内存缓存]
+F --> G[分布式缓存]
+style A fill:#e8f5e8
+style E fill:#fff3e0
+```
+
+### 并发处理
+
+系统支持高并发场景下的稳定运行：
+
+- **异步数据库操作**：避免阻塞主线程
+- **批量操作**：减少数据库往返次数
+- **状态锁机制**：防止并发状态冲突
+
+## 故障排除指南
+
+### 常见问题及解决方案
+
+| 问题类型 | 症状 | 可能原因 | 解决方案 |
+|----------|------|----------|----------|
+| 权限错误 | 403 Forbidden | 用户权限不足 | 检查用户角色和权限配置 |
+| 数据验证错误 | 422 Unprocessable Entity | 请求数据格式不正确 | 验证请求参数和数据类型 |
+| 资源不存在 | 404 Not Found | ID不存在或已被删除 | 确认资源ID的有效性 |
+| 状态冲突 | 400 Bad Request | 状态转换不符合规则 | 检查当前状态和允许的操作 |
+
+### 日志记录
+
+系统提供了完整的日志记录机制：
+
+```mermaid
+graph TD
+A[操作请求] --> B[请求日志]
+B --> C[业务日志]
+C --> D[错误日志]
+D --> E[性能日志]
+F[审计日志] --> G[操作追踪]
+G --> H[合规记录]
+style B fill:#e8f5e8
+style D fill:#ffebee
+style F fill:#f3e5f5
+```
+
+**章节来源**
+- [docs/api.md](file://docs/api.md#L540-L551)
+
+## 结论
+
+本绩效考核管理接口系统具有以下特点：
+
+1. **完整性**：覆盖了从指标定义到结果应用的完整生命周期
+2. **灵活性**：支持多层级、多类型的绩效管理需求
+3. **可扩展性**：模块化设计便于功能扩展和维护
+4. **安全性**：完善的权限控制和数据验证机制
+5. **集成性**：与工资核算系统无缝集成，实现数据共享
+
+系统采用先进的技术栈和架构设计，能够满足现代医院对绩效管理的复杂需求，为建立科学的激励约束机制提供强有力的技术支撑。
+
+## 附录
+
+### API接口规范
+
+系统遵循RESTful API设计原则，提供统一的接口规范：
+
+- **响应格式**：统一的JSON响应格式，包含状态码、消息和数据
+- **分页机制**：支持页码和每页数量的参数配置
+- **错误处理**：标准化的错误响应格式
+- **认证机制**：JWT Bearer Token认证方式
+
+### 数据模型设计
+
+系统采用关系型数据库设计，确保数据的一致性和完整性：
+
+- **主键设计**：使用自增主键确保唯一性
+- **外键约束**：建立合理的外键关系保证数据完整性
+- **索引优化**：为查询频繁的字段建立索引
+- **数据类型**：使用合适的数据类型确保数据精度
+
+### 集成接口
+
+系统支持与其他医院信息系统(HIS)的集成：
+
+- **数据同步**：支持定时或实时的数据同步机制
+- **接口适配**：提供标准化的接口适配器
+- **错误处理**：完善的异常处理和重试机制
+- **监控告警**：实时监控接口调用状态