# 考核管理接口

<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)