# 考核指标管理接口

<cite>
**本文档引用的文件**
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_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/init_indicator_templates.py](file://backend/init_indicator_templates.py)
- [docs/api.md](file://docs/api.md)
- [docs/详细设计.md](file://docs/详细设计.md)
- [frontend/src/api/indicator.js](file://frontend/src/api/indicator.js)
- [frontend/src/views/basic/Indicators.vue](file://frontend/src/views/basic/Indicators.vue)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介

本文件为医院绩效管理系统中的考核指标管理接口提供详细的API文档。系统基于平衡计分卡理论，实现了完整的指标生命周期管理，包括指标的创建、查询、更新、删除以及模板管理功能。

系统支持四个维度的平衡计分卡指标管理：
- **财务维度**：关注医院的经济效益和成本控制
- **客户维度**：关注患者满意度和服务质量
- **内部流程维度**：关注医疗质量和运营效率
- **学习与成长维度**：关注员工发展和能力提升

## 项目结构

后端采用FastAPI框架，遵循MVC架构模式，主要分为以下层次：

```mermaid
graph TB
subgraph "表现层"
Frontend[前端Vue.js应用]
end
subgraph "应用层"
API[API路由层]
Service[业务服务层]
end
subgraph "数据层"
Model[数据模型层]
Database[(PostgreSQL数据库)]
end
Frontend --> API
API --> Service
Service --> Model
Model --> Database
```

**图表来源**
- [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/main.py](file://backend/app/main.py#L15-L77)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)

## 核心组件

### 指标管理核心组件

系统的核心组件包括指标模型、服务层和API路由，形成了完整的指标管理功能体系。

```mermaid
classDiagram
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
+datetime created_at
+datetime updated_at
}
class IndicatorService {
+get_list() tuple
+get_by_id() Indicator
+get_active_indicators() List[Indicator]
+create() Indicator
+update() Indicator
+delete() bool
+import_template() int
+get_templates() List[Dict]
}
class IndicatorRouter {
+get_indicators() Response
+get_active_indicators() Response
+get_indicator() Response
+create_indicator() Response
+update_indicator() Response
+delete_indicator() Response
+get_indicator_templates() Response
+import_indicator_template() Response
}
IndicatorService --> Indicator : "管理"
IndicatorRouter --> IndicatorService : "调用"
```

**图表来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L147)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L13-L197)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L17-L142)

### 指标类型和维度体系

系统定义了完整的指标分类体系，支持多维度的指标管理：

| 指标类型 | 描述 | 示例 |
|---------|------|------|
| quality | 质量指标 | 病历合格率、满意度 |
| quantity | 数量指标 | 门诊量、手术量 |
| efficiency | 效率指标 | 平均住院日、床位使用率 |
| service | 服务指标 | 服务态度、响应时间 |
| cost | 成本指标 | 药品占比、能耗成本 |

| 平衡计分卡维度 | 权重范围 | 描述 |
|---------------|----------|------|
| financial | 30%-40% | 财务效益和成本控制 |
| customer | 25%-35% | 患者满意度和市场地位 |
| internal_process | 20%-30% | 内部流程效率和质量 |
| 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)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L39-L44)

## 架构概览

系统采用分层架构设计，确保了良好的可维护性和扩展性：

```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "API路由层"
participant Service as "服务层"
participant Model as "数据模型层"
participant DB as "数据库"
Client->>API : GET /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接口

#### 指标列表查询

**接口定义**
- 方法：GET
- 路径：`/indicators`
- 权限：所有用户

**查询参数**

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|-------|------|------|--------|------|
| indicator_type | string | 否 | 无 | 指标类型过滤 |
| bs_dimension | string | 否 | 无 | 平衡计分卡维度过滤 |
| is_active | boolean | 否 | 无 | 是否启用过滤 |
| page | int | 是 | 1 | 页码 |
| page_size | int | 是 | 20 | 每页数量 |

**响应结构**
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "name": "门诊量",
      "code": "IND001",
      "indicator_type": "quantity",
      "weight": 1.0,
      "max_score": 100.0,
      "target_value": 500.0,
      "unit": "人次",
      "calculation_method": "实际值/目标值*100",
      "description": "月度门诊接诊量",
      "is_active": true,
      "created_at": "2024-01-01T00:00:00",
      "updated_at": "2024-01-01T00:00:00"
    }
  ],
  "total": 20,
  "page": 1,
  "page_size": 20
}
```

#### 启用的指标查询

**接口定义**
- 方法：GET
- 路径：`/indicators/active`
- 权限：所有用户

**响应结构**
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "name": "门诊量",
      "code": "IND001",
      "indicator_type": "quantity",
      "weight": 1.0,
      "max_score": 100.0,
      "target_value": 500.0,
      "unit": "人次",
      "calculation_method": "实际值/目标值*100",
      "description": "月度门诊接诊量",
      "is_active": true,
      "created_at": "2024-01-01T00:00:00",
      "updated_at": "2024-01-01T00:00:00"
    }
  ]
}
```

#### 指标详情获取

**接口定义**
- 方法：GET
- 路径：`/indicators/{indicator_id}`
- 权限：所有用户

**路径参数**

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| indicator_id | int | 是 | 指标ID |

**响应结构**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "name": "门诊量",
    "code": "IND001",
    "indicator_type": "quantity",
    "weight": 1.0,
    "max_score": 100.0,
    "target_value": 500.0,
    "unit": "人次",
    "calculation_method": "实际值/目标值*100",
    "description": "月度门诊接诊量",
    "is_active": true,
    "created_at": "2024-01-01T00:00:00",
    "updated_at": "2024-01-01T00:00:00"
  }
}
```

#### 指标创建

**接口定义**
- 方法：POST
- 路径：`/indicators`
- 权限：管理员/经理

**请求体结构**
```json
{
  "name": "门诊量",
  "code": "IND001",
  "indicator_type": "quantity",
  "weight": 1.0,
  "max_score": 100.0,
  "target_value": 500.0,
  "unit": "人次",
  "calculation_method": "实际值/目标值*100",
  "description": "月度门诊接诊量"
}
```

**响应结构**
```json
{
  "code": 200,
  "message": "创建成功",
  "data": {
    "id": 1,
    "name": "门诊量",
    "code": "IND001",
    "indicator_type": "quantity",
    "weight": 1.0,
    "max_score": 100.0,
    "target_value": 500.0,
    "unit": "人次",
    "calculation_method": "实际值/目标值*100",
    "description": "月度门诊接诊量",
    "is_active": true,
    "created_at": "2024-01-01T00:00:00",
    "updated_at": "2024-01-01T00:00:00"
  }
}
```

#### 指标更新

**接口定义**
- 方法：PUT
- 路径：`/indicators/{indicator_id}`
- 权限：管理员/经理

**请求体结构**
```json
{
  "name": "更新后的指标名称",
  "weight": 1.5,
  "max_score": 120.0,
  "is_active": false
}
```

**响应结构**
```json
{
  "code": 200,
  "message": "更新成功",
  "data": {
    "id": 1,
    "name": "更新后的指标名称",
    "code": "IND001",
    "indicator_type": "quantity",
    "weight": 1.5,
    "max_score": 120.0,
    "target_value": 500.0,
    "unit": "人次",
    "calculation_method": "实际值/目标值*100",
    "description": "月度门诊接诊量",
    "is_active": false,
    "created_at": "2024-01-01T00:00:00",
    "updated_at": "2024-01-01T00:00:00"
  }
}
```

#### 指标删除

**接口定义**
- 方法：DELETE
- 路径：`/indicators/{indicator_id}`
- 权限：管理员/经理

**响应结构**
```json
{
  "code": 200,
  "message": "删除成功"
}
```

**章节来源**
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L20-L112)
- [docs/api.md](file://docs/api.md#L239-L296)

### 指标模板管理

#### 模板列表查询

**接口定义**
- 方法：GET
- 路径：`/templates`
- 权限：所有用户

**查询参数**

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|-------|------|------|--------|------|
| template_type | string | 否 | 无 | 模板类型过滤 |
| is_active | boolean | 否 | 无 | 是否启用过滤 |
| page | int | 是 | 1 | 页码 |
| page_size | int | 是 | 20 | 每页数量 |

#### 模板类型列表

**接口定义**
- 方法：GET
- 路径：`/templates/types`
- 权限：所有用户

**响应结构**
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {"value": "general", "label": "通用模板"},
    {"value": "surgical", "label": "手术临床科室"},
    {"value": "nonsurgical_ward", "label": "非手术有病房科室"},
    {"value": "nonsurgical_noward", "label": "非手术无病房科室"},
    {"value": "medical_tech", "label": "医技科室"},
    {"value": "nursing", "label": "护理单元"},
    {"value": "admin", "label": "行政科室"},
    {"value": "logistics", "label": "后勤科室"}
  ]
}
```

#### BSC维度列表

**接口定义**
- 方法：GET
- 路径：`/templates/dimensions`
- 权限：所有用户

**响应结构**
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {"value": "financial", "label": "财务管理", "weight_range": "30%-40%"},
    {"value": "customer", "label": "顾客服务", "weight_range": "25%-35%"},
    {"value": "internal_process", "label": "内部流程", "weight_range": "20%-30%"},
    {"value": "learning_growth", "label": "学习与成长", "weight_range": "5%-15%"}
  ]
}
```

**章节来源**
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L22-L74)

### 权重计算和评分规则

系统支持多种评分方法和权重计算方式：

#### 权重计算流程

```mermaid
flowchart TD
Start([开始计算]) --> GetIndicators["获取指标列表"]
GetIndicators --> CheckVeto{"是否包含一票否决"}
CheckVeto --> |是| ApplyVeto["应用一票否决规则"]
CheckVeto --> |否| CalcWeight["计算权重"]
ApplyVeto --> CalcWeight
CalcWeight --> CalcScore["计算指标得分"]
CalcScore --> CalcFinal["计算最终得分"]
CalcFinal --> End([结束])
```

**图表来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L134-L136)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L106-L154)

#### 评分规则

| 评分方法 | 适用场景 | 计算公式示例 |
|---------|----------|-------------|
| 目标参照法 | 有明确目标值的指标 | 得分 = min(100, 实际值/目标值 × 100) |
| 区间法 | 有合理区间范围的指标 | 根据区间位置线性计算得分 |
| 扣分法 | 违规或负面指标 | 得分 = 最高分 - 扣分标准 × 违规次数 |
| 加分法 | 表现优异的指标 | 得分 = 基础分 + 超额完成奖励 |
| 比较法 | 相对排名指标 | 根据相对排名计算得分 |

**章节来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L130-L133)
- [docs/详细设计.md](file://docs/详细设计.md#L96-L109)

### 指标模板使用方法

#### 模板导入流程

```mermaid
sequenceDiagram
participant Admin as "管理员"
participant API as "模板API"
participant Service as "模板服务"
participant DB as "数据库"
Admin->>API : POST /templates/import
API->>Service : import_template()
Service->>Service : 检查模板数据
Service->>DB : 查询现有指标
DB-->>Service : 查询结果
Service->>Service : 判断覆盖策略
Service->>DB : 批量插入指标
DB-->>Service : 插入结果
Service-->>API : 导入统计
API-->>Admin : 导入成功响应
```

**图表来源**
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L128-L141)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L106-L154)

#### 自定义指标创建流程

**步骤1：基础信息配置**
- 指标编码：唯一标识符，如 FIN001
- 指标名称：简洁明了的指标描述
- 指标类型：选择质量/数量/效率/服务/成本之一
- 权重设置：根据重要程度设置权重值

**步骤2：维度映射**
- 平衡计分卡维度：财务/客户/内部流程/学习成长
- 适用科室类型：选择适用的科室类型数组

**步骤3：计算规则配置**
- 计算方法：描述计算公式和步骤
- 目标值：设定期望达到的目标值
- 最高分值：设定指标满分对应的分值

**步骤4：数据验证**
- 数据来源：指定数据采集系统
- 扣分标准：设定违规或不达标时的扣分规则
- 一票否决：设置是否为强制性指标

**章节来源**
- [backend/init_indicator_templates.py](file://backend/init_indicator_templates.py#L22-L232)
- [docs/详细设计.md](file://docs/详细设计.md#L69-L81)

## 依赖关系分析

系统采用清晰的依赖层次结构，确保了模块间的松耦合：

```mermaid
graph TD
subgraph "外部依赖"
FastAPI[FastAPI框架]
SQLAlchemy[SQLAlchemy ORM]
PostgreSQL[PostgreSQL数据库]
end
subgraph "核心模块"
API[API路由层]
Service[服务层]
Model[模型层]
Schema[数据模式层]
end
subgraph "业务模块"
Indicator[指标管理]
Template[模板管理]
Assessment[考核管理]
PerformancePlan[绩效计划]
end
FastAPI --> API
SQLAlchemy --> Model
PostgreSQL --> Model
API --> Service
Service --> Model
Model --> Schema
Service --> Schema
API --> Indicator
API --> Template
API --> Assessment
API --> PerformancePlan
Indicator --> Template
Assessment --> PerformancePlan
```

**图表来源**
- [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-L17)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L1-L13)

**章节来源**
- [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-L17)

## 性能考虑

### 数据库优化

系统采用了多项数据库优化策略：

1. **索引优化**
   - 指标类型索引：加速指标类型查询
   - 科室类型索引：优化科室相关查询
   - 状态索引：快速筛选启用/停用指标

2. **查询优化**
   - 分页查询：避免一次性加载大量数据
   - 条件查询：支持多维度过滤查询
   - 异步查询：使用异步数据库连接池

3. **缓存策略**
   - 模板数据缓存：减少重复查询
   - 权重计算缓存：避免重复计算

### 前端性能优化

1. **懒加载**
   - 指标表格按需加载
   - 模态框内容延迟渲染

2. **虚拟滚动**
   - 大数据量表格的虚拟滚动支持

3. **请求去重**
   - 避免重复的相同查询请求

## 故障排除指南

### 常见问题及解决方案

**问题1：指标编码重复**
- 现象：创建指标时报错"指标编码已存在"
- 解决方案：使用唯一的指标编码，遵循系统约定的编码规则

**问题2：权限不足**
- 现象：更新或删除指标返回403权限错误
- 解决方案：确保当前用户具有管理员或经理权限

**问题3：指标不存在**
- 现象：查询特定ID指标返回404错误
- 解决方案：确认指标ID是否正确，检查数据库中是否存在该记录

**问题4：模板导入失败**
- 现象：模板导入接口报错
- 解决方案：检查模板数据格式，确认必填字段完整

### 日志和监控

系统提供了完善的日志记录机制：

1. **访问日志**：记录所有API请求的详细信息
2. **错误日志**：捕获和记录系统异常
3. **性能日志**：监控数据库查询性能
4. **审计日志**：记录关键业务操作

**章节来源**
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L78-L81)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L96-L98)

## 结论

本考核指标管理接口实现了完整的平衡计分卡指标管理体系，具有以下特点：

1. **完整的指标生命周期管理**：从创建到删除的全流程支持
2. **灵活的分类体系**：支持多维度、多类型的指标分类
3. **强大的模板功能**：支持标准化模板的创建和导入
4. **完善的权限控制**：基于角色的细粒度权限管理
5. **高性能的架构设计**：采用异步处理和数据库优化

系统为医院绩效管理提供了坚实的技术基础，能够满足不同科室和岗位的差异化考核需求。

## 附录

### API接口完整列表

| 接口名称 | 方法 | 路径 | 权限 | 功能描述 |
|---------|------|------|------|----------|
| 获取指标列表 | GET | /indicators | 所有用户 | 查询所有考核指标 |
| 获取启用指标 | GET | /indicators/active | 所有用户 | 获取所有启用的指标 |
| 获取指标详情 | GET | /indicators/{id} | 所有用户 | 获取指定指标详情 |
| 创建指标 | POST | /indicators | 管理员/经理 | 创建新的考核指标 |
| 更新指标 | PUT | /indicators/{id} | 管理员/经理 | 更新现有指标信息 |
| 删除指标 | DELETE | /indicators/{id} | 管理员/经理 | 删除指定指标 |
| 获取模板列表 | GET | /templates | 所有用户 | 查询指标模板列表 |
| 获取模板详情 | GET | /templates/{id} | 所有用户 | 获取模板详细信息 |
| 创建模板 | POST | /templates | 管理员/经理 | 创建新的指标模板 |
| 更新模板 | PUT | /templates/{id} | 管理员/经理 | 更新模板信息 |
| 删除模板 | DELETE | /templates/{id} | 管理员/经理 | 删除指定模板 |

### 数据模型关系图

```mermaid
erDiagram
INDICATORS {
int id PK
string name
string code UK
enum indicator_type
enum bs_dimension
decimal weight
decimal max_score
decimal target_value
string target_unit
string calculation_method
string assessment_method
string deduction_standard
string data_source
string applicable_dept_types
boolean is_veto
boolean is_active
datetime created_at
datetime updated_at
}
INDICATOR_TEMPLATES {
int id PK
string template_name
string template_code UK
enum template_type
text description
text dimension_weights
string assessment_cycle
boolean is_active
datetime created_at
datetime updated_at
}
TEMPLATE_INDICATORS {
int id PK
int template_id FK
int indicator_id FK
string category
decimal target_value
string target_unit
decimal weight
string scoring_method
text scoring_params
int sort_order
text remark
datetime created_at
datetime updated_at
}
INDICATORS ||--o{ TEMPLATE_INDICATORS : "包含"
INDICATOR_TEMPLATES ||--o{ TEMPLATE_INDICATORS : "定义"
```

**图表来源**
- [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-L437)