提交文件

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,626 @@
+# 考核管理接口
+
+<cite>
+**本文档引用的文件**
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_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/templates.py](file://backend/app/api/v1/templates.py)
+- [backend/app/services/template_service.py](file://backend/app/services/template_service.py)
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py)
+- [backend/app/core/security.py](file://backend/app/core/security.py)
+- [backend/app/main.py](file://backend/app/main.py)
+- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js)
+- [docs/api.md](file://docs/api.md)
+- [docs/详细设计.md](file://docs/详细设计.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+
+本文件详细说明医院绩效管理系统的考核管理接口，涵盖考核流程管理、考核记录和考核明细的API实现。文档重点解释考核状态流转机制、审批流程和权限控制，同时文档化考核模板的使用、指标计算和得分汇总。系统支持批量考核操作、历史记录查询和统计分析接口，详细介绍考核详情的数据结构、评分规则和权重计算。此外，文档还包含考核进度跟踪、提醒机制和报表生成功能，提供完整的考核生命周期管理、数据一致性保证和并发控制策略。
+
+## 项目结构
+
+后端采用FastAPI + SQLAlchemy 2.0架构，采用分层设计模式：
+
+```mermaid
+graph TB
+subgraph "表现层"
+Frontend[前端Vue.js应用]
+end
+subgraph "应用层"
+API[API路由层]
+Services[业务服务层]
+end
+subgraph "数据层"
+Models[ORM模型层]
+Database[(PostgreSQL数据库)]
+end
+Frontend --> API
+API --> Services
+Services --> Models
+Models --> Database
+```
+
+**图表来源**
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
+
+系统采用模块化设计，主要模块包括：
+- **认证模块**：JWT令牌管理和权限控制
+- **考核管理模块**：考核流程、状态管理和审批
+- **指标模板模块**：模板管理和指标配置
+- **统计分析模块**：报表和数据分析
+- **数据模型模块**：核心业务实体和关系
+
+**章节来源**
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [docs/详细设计.md](file://docs/详细设计.md#L27-L47)
+
+## 核心组件
+
+### 考核状态管理
+
+系统实现了完整的考核状态流转机制，支持四种状态：
+- **草稿 (draft)**：初始状态，允许修改
+- **已提交 (submitted)**：等待审核
+- **已审核 (reviewed)**：审核通过，等待确认
+- **已确认 (finalized)**：最终状态，不可修改
+- **已驳回 (rejected)**：审核不通过
+
+```mermaid
+stateDiagram-v2
+[*] --> 草稿
+草稿 --> 已提交 : "提交考核"
+已提交 --> 已审核 : "审核通过"
+已提交 --> 已驳回 : "审核驳回"
+已审核 --> 已确认 : "确认考核"
+已确认 --> [*]
+已驳回 --> 草稿 : "重新修改"
+```
+
+**图表来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L45-L52)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L158-L205)
+
+### 权限控制系统
+
+系统采用基于角色的权限控制（RBAC）：
+
+```mermaid
+graph LR
+subgraph "用户角色"
+Staff[普通员工]
+Manager[科室经理]
+Admin[系统管理员]
+end
+subgraph "权限级别"
+Read[只读权限]
+Write[写入权限]
+Approve[审批权限]
+Manage[管理权限]
+end
+Staff --> Read
+Manager --> Write
+Manager --> Approve
+Admin --> Manage
+```
+
+**图表来源**
+- [backend/app/core/security.py](file://backend/app/core/security.py#L94-L109)
+
+**章节来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L45-L52)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L94-L109)
+
+## 架构概览
+
+系统采用经典的三层架构模式，确保关注点分离和代码可维护性：
+
+```mermaid
+graph TB
+subgraph "API层"
+AssessmentsAPI[考核API]
+TemplatesAPI[模板API]
+StatsAPI[统计API]
+end
+subgraph "服务层"
+AssessmentService[考核服务]
+TemplateService[模板服务]
+StatsService[统计服务]
+end
+subgraph "数据层"
+AssessmentModel[考核模型]
+DetailModel[明细模型]
+IndicatorModel[指标模型]
+DepartmentModel[科室模型]
+end
+AssessmentsAPI --> AssessmentService
+TemplatesAPI --> TemplateService
+StatsAPI --> StatsService
+AssessmentService --> AssessmentModel
+AssessmentService --> DetailModel
+AssessmentService --> IndicatorModel
+TemplateService --> AssessmentModel
+TemplateService --> DetailModel
+TemplateService --> IndicatorModel
+StatsService --> AssessmentModel
+StatsService --> DetailModel
+StatsService --> IndicatorModel
+StatsService --> DepartmentModel
+```
+
+**图表来源**
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L203)
+
+## 详细组件分析
+
+### 考核管理API
+
+#### 考核列表查询
+
+支持多条件过滤和分页查询：
+
+| 查询参数 | 类型 | 描述 | 示例 |
+|---------|------|------|------|
+| staff_id | int | 员工ID | 1001 |
+| department_id | int | 科室ID | 501 |
+| period_year | int | 年度 | 2024 |
+| period_month | int | 月份 | 1 |
+| status | string | 状态 | "submitted" |
+| page | int | 页码 | 1 |
+| page_size | int | 每页数量 | 20 |
+
+#### 考核详情查询
+
+返回完整的考核信息，包括员工和科室名称以及指标名称：
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant API as "考核API"
+participant Service as "考核服务"
+participant DB as "数据库"
+Client->>API : GET /assessments/{id}
+API->>Service : get_by_id(assessment_id)
+Service->>DB : 查询考核记录
+DB-->>Service : 考核详情
+Service->>DB : 查询明细和指标
+DB-->>Service : 明细数据
+Service-->>API : 完整考核信息
+API-->>Client : 考核详情响应
+```
+
+**图表来源**
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L55-L77)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L58-L68)
+
+#### 考核状态流转
+
+```mermaid
+flowchart TD
+Start([开始]) --> Draft[草稿状态]
+Draft --> Submit{提交考核?}
+Submit --> |是| Submitted[已提交]
+Submit --> |否| Draft
+Submitted --> Review{审核结果}
+Review --> |通过| Reviewed[已审核]
+Review --> |驳回| Rejected[已驳回]
+Reviewed --> Finalize{确认考核?}
+Finalize --> |是| Finalized[已确认]
+Finalize --> |否| Reviewed
+Rejected --> Edit[修改后重新提交]
+Edit --> Draft
+Finalized --> End([结束])
+```
+
+**图表来源**
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L158-L205)
+
+**章节来源**
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L20-L52)
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L55-L77)
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L105-L145)
+
+### 指标模板管理
+
+#### 模板类型体系
+
+系统支持多种科室类型的指标模板：
+
+| 模板类型 | 适用科室 | 描述 |
+|---------|---------|------|
+| general | 通用模板 | 适用于所有科室的基础指标 |
+| surgical | 手术临床科室 | 适用于手术科室的特殊指标 |
+| nonsurgical_ward | 非手术有病房科室 | 适用于内科、儿科等有病房科室 |
+| nonsurgical_noward | 非手术无病房科室 | 适用于门诊科室 |
+| medical_tech | 医技科室 | 适用于检验、影像等医技科室 |
+| nursing | 护理单元 | 适用于护理部门 |
+| admin | 行政科室 | 适用于行政部门 |
+| logistics | 后勤科室 | 适用于后勤保障部门 |
+
+#### 模板指标关联
+
+```mermaid
+erDiagram
+INDICATOR_TEMPLATE ||--o{ TEMPLATE_INDICATOR : "包含"
+TEMPLATE_INDICATOR }o--|| INDICATOR : "关联"
+INDICATOR_TEMPLATE {
+int id PK
+string template_name
+string template_code
+string template_type
+text dimension_weights
+string assessment_cycle
+boolean is_active
+}
+TEMPLATE_INDICATOR {
+int id PK
+int template_id FK
+int indicator_id FK
+string category
+float target_value
+string target_unit
+float weight
+string scoring_method
+text scoring_params
+int sort_order
+text remark
+}
+INDICATOR {
+int id PK
+string name
+string code
+string indicator_type
+string bs_dimension
+float weight
+float max_score
+float target_value
+string target_unit
+text calculation_method
+text assessment_method
+text deduction_standard
+string data_source
+text applicable_dept_types
+boolean is_veto
+boolean is_active
+}
+```
+
+**图表来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L387-L437)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L147)
+
+**章节来源**
+- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L22-L42)
+- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L77-L126)
+- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L23-L71)
+
+### 统计分析接口
+
+#### BSC维度分析
+
+系统支持平衡计分卡四个维度的统计分析：
+
+| 维度 | 描述 | 权重范围 |
+|------|------|----------|
+| financial | 财务管理 | 30%-40% |
+| customer | 顾客服务 | 25%-35% |
+| internal_process | 内部流程 | 20%-30% |
+| learning_growth | 学习与成长 | 5%-15% |
+
+#### 绩效排名统计
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant StatsAPI as "统计API"
+participant StatsService as "统计服务"
+participant DB as "数据库"
+Client->>StatsAPI : GET /stats/ranking
+StatsAPI->>StatsService : get_ranking_stats(year, month, limit)
+StatsService->>DB : 查询最终状态的考核记录
+DB-->>StatsService : 排名数据
+StatsService->>DB : 关联员工和科室信息
+DB-->>StatsService : 员工详情
+StatsService-->>StatsAPI : 排名结果
+StatsAPI-->>Client : 排名列表
+```
+
+**图表来源**
+- [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#L202-L244)
+
+**章节来源**
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L17-L33)
+- [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#L19-L72)
+
+### 数据模型设计
+
+#### 核心实体关系
+
+```mermaid
+erDiagram
+ASSESSMENT {
+int id PK
+int staff_id FK
+int period_year
+int period_month
+string period_type
+float total_score
+float weighted_score
+string status
+int assessor_id FK
+int reviewer_id FK
+datetime submit_time
+datetime review_time
+text remark
+datetime created_at
+datetime updated_at
+}
+ASSESSMENT_DETAIL {
+int id PK
+int assessment_id FK
+int indicator_id FK
+float actual_value
+float score
+text evidence
+text remark
+datetime created_at
+datetime updated_at
+}
+INDICATOR {
+int id PK
+string name
+string code
+string indicator_type
+string bs_dimension
+float weight
+float max_score
+float target_value
+string target_unit
+text calculation_method
+text assessment_method
+text deduction_standard
+string data_source
+text applicable_dept_types
+boolean is_veto
+boolean is_active
+}
+STAFF {
+int id PK
+string employee_id
+string name
+int department_id FK
+string position
+string title
+string phone
+string email
+float base_salary
+float performance_ratio
+string status
+datetime hire_date
+datetime created_at
+datetime updated_at
+}
+DEPARTMENT {
+int id PK
+string name
+string code
+string dept_type
+int parent_id FK
+int level
+int sort_order
+boolean is_active
+text description
+datetime created_at
+datetime updated_at
+}
+ASSESSMENT ||--o{ ASSESSMENT_DETAIL : "包含"
+ASSESSMENT }o--|| STAFF : "属于"
+STAFF }o--|| DEPARTMENT : "隶属于"
+ASSESSMENT_DETAIL }o--|| INDICATOR : "对应"
+```
+
+**图表来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L203)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L147)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L114)
+
+**章节来源**
+- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L203)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L147)
+
+## 依赖关系分析
+
+### 模块依赖图
+
+```mermaid
+graph TB
+subgraph "外部依赖"
+FastAPI[FastAPI框架]
+SQLAlchemy[SQLAlchemy ORM]
+Postgres[PostgreSQL数据库]
+JWT[jwt库]
+Bcrypt[bcrypt加密]
+end
+subgraph "核心模块"
+Security[安全模块]
+Database[数据库模块]
+Logging[日志模块]
+end
+subgraph "业务模块"
+AssessmentAPI[考核API]
+AssessmentService[考核服务]
+TemplateAPI[模板API]
+TemplateService[模板服务]
+StatsAPI[统计API]
+StatsService[统计服务]
+end
+FastAPI --> AssessmentAPI
+FastAPI --> TemplateAPI
+FastAPI --> StatsAPI
+AssessmentAPI --> AssessmentService
+TemplateAPI --> TemplateService
+StatsAPI --> StatsService
+AssessmentService --> Database
+TemplateService --> Database
+StatsService --> Database
+AssessmentAPI --> Security
+TemplateAPI --> Security
+StatsAPI --> Security
+Security --> JWT
+Security --> Bcrypt
+Database --> Postgres
+```
+
+**图表来源**
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+
+### 数据一致性保证
+
+系统通过以下机制确保数据一致性：
+
+1. **事务管理**：所有数据库操作都在事务中执行
+2. **外键约束**：使用SQLAlchemy外键约束保证引用完整性
+3. **状态验证**：在状态转换前验证当前状态
+4. **并发控制**：使用数据库锁防止并发修改冲突
+
+**章节来源**
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L110-L156)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L178)
+
+## 性能考虑
+
+### 查询优化策略
+
+1. **索引优化**：为常用查询字段建立索引
+   - 考核记录：staff_id, period_year, period_month, status
+   - 明细记录：assessment_id, indicator_id
+   - 员工信息：department_id, status
+
+2. **分页查询**：默认每页20条记录，最大100条
+3. **批量操作**：支持批量创建和查询
+4. **缓存策略**：对于静态数据使用缓存
+
+### 并发控制
+
+系统采用以下并发控制策略：
+
+```mermaid
+flowchart TD
+Request[请求到达] --> CheckLock{检查锁}
+CheckLock --> |无锁| AcquireLock[获取锁]
+CheckLock --> |有锁| Wait[等待锁释放]
+AcquireLock --> Process[处理业务逻辑]
+Process --> ReleaseLock[释放锁]
+Wait --> CheckLock
+ReleaseLock --> Response[返回响应]
+```
+
+**图表来源**
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L110-L156)
+
+## 故障排除指南
+
+### 常见错误处理
+
+| 错误类型 | HTTP状态码 | 描述 | 处理建议 |
+|---------|-----------|------|----------|
+| 未授权 | 401 | JWT令牌无效或过期 | 重新登录获取新令牌 |
+| 权限不足 | 403 | 用户权限不够 | 检查用户角色和权限 |
+| 资源不存在 | 404 | 请求的资源不存在 | 确认ID是否正确 |
+| 参数错误 | 400 | 请求参数不合法 | 检查请求格式和参数类型 |
+| 数据验证失败 | 422 | 数据不符合验证规则 | 修正数据格式和范围 |
+
+### 日志记录
+
+系统提供完整的日志记录机制：
+
+```mermaid
+graph LR
+subgraph "日志级别"
+Info[信息日志]
+Warning[警告日志]
+Error[错误日志]
+Debug[调试日志]
+end
+subgraph "日志内容"
+Request[请求信息]
+Response[响应信息]
+ErrorDetail[错误详情]
+Performance[性能数据]
+end
+Info --> Request
+Warning --> ErrorDetail
+Error --> ErrorDetail
+Debug --> Performance
+```
+
+**图表来源**
+- [backend/app/main.py](file://backend/app/main.py#L58-L74)
+
+**章节来源**
+- [backend/app/main.py](file://backend/app/main.py#L58-L74)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L94-L109)
+
+## 结论
+
+本考核管理接口提供了完整的医院绩效管理系统解决方案，具有以下特点：
+
+1. **完整的生命周期管理**：从草稿到最终确认的全流程管理
+2. **灵活的权限控制**：基于角色的精细化权限管理
+3. **强大的统计分析**：多维度的报表和分析功能
+4. **可靠的并发控制**：确保数据一致性和系统稳定性
+5. **良好的扩展性**：模块化设计便于功能扩展和维护
+
+系统采用现代化的技术栈和设计模式，能够满足医院绩效管理的复杂需求，为提升医疗质量和效率提供有力支撑。
+
+## 附录
+
+### 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 | 科室经理 | 批量创建考核 |
+
+#### 统计分析接口
+
+| 方法 | 路径 | 权限要求 | 功能描述 |
+|------|------|----------|----------|
+| GET | /stats/bsc-dimension | 普通员工 | BSC维度分析 |
+| GET | /stats/department | 普通员工 | 科室绩效统计 |
+| GET | /stats/trend | 普通员工 | 趋势分析 |
+| GET | /stats/ranking | 普通员工 | 绩效排名 |
+| GET | /stats/completion | 普通员工 | 指标完成度 |
+
+**章节来源**
+- [docs/api.md](file://docs/api.md#L298-L468)
+- [docs/api.md](file://docs/api.md#L471-L537)