hospital_performance/.qoder/repowiki/zh/content/API接口文档/基础数据接口/考核指标管理接口.md

考核指标管理接口

**本文档引用的文件** - [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)

目录

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

简介

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

系统支持四个维度的平衡计分卡指标管理：

• 财务维度：关注医院的经济效益和成本控制
• 客户维度：关注患者满意度和服务质量
• 内部流程维度：关注医疗质量和运营效率
• 学习与成长维度：关注员工发展和能力提升

项目结构

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

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
• backend/app/api/v1/indicators.py

章节来源

• backend/app/main.py
• backend/app/api/v1/indicators.py

核心组件

指标管理核心组件

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

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
• backend/app/services/indicator_service.py
• backend/app/api/v1/indicators.py

指标类型和维度体系

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

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

平衡计分卡维度	权重范围	描述
financial	30%-40%	财务效益和成本控制
customer	25%-35%	患者满意度和市场地位
internal_process	20%-30%	内部流程效率和质量
learning_growth	5%-15%	员工能力和创新

章节来源

• backend/app/models/models.py
• backend/app/models/models.py
• backend/app/schemas/schemas.py

架构概览

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

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
• backend/app/services/indicator_service.py

详细组件分析

指标管理API接口

指标列表查询

接口定义

• 方法：GET
• 路径：/indicators
• 权限：所有用户

查询参数

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

响应结构

{
  "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
• 权限：所有用户

响应结构

{
  "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

响应结构

{
  "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
• 权限：管理员/经理

请求体结构

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

响应结构

{
  "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}
• 权限：管理员/经理

请求体结构

{
  "name": "更新后的指标名称",
  "weight": 1.5,
  "max_score": 120.0,
  "is_active": false
}

响应结构

{
  "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}
• 权限：管理员/经理

响应结构

{
  "code": 200,
  "message": "删除成功"
}

章节来源

• backend/app/api/v1/indicators.py
• docs/api.md

指标模板管理

模板列表查询

接口定义

• 方法：GET
• 路径：/templates
• 权限：所有用户

查询参数

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

模板类型列表

接口定义

• 方法：GET
• 路径：/templates/types
• 权限：所有用户

响应结构

{
  "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
• 权限：所有用户

响应结构

{
  "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

权重计算和评分规则

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

权重计算流程

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

图表来源

• backend/app/models/models.py
• backend/app/services/indicator_service.py

评分规则

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

章节来源

• backend/app/models/models.py
• docs/详细设计.md

指标模板使用方法

模板导入流程

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
• backend/app/services/indicator_service.py

自定义指标创建流程

步骤1：基础信息配置

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

步骤2：维度映射

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

步骤3：计算规则配置

• 计算方法：描述计算公式和步骤
• 目标值：设定期望达到的目标值
• 最高分值：设定指标满分对应的分值

步骤4：数据验证

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

章节来源

• backend/init_indicator_templates.py
• docs/详细设计.md

依赖关系分析

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

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
• backend/app/api/v1/indicators.py
• backend/app/services/indicator_service.py

章节来源

• backend/app/main.py
• backend/app/api/v1/indicators.py

性能考虑

数据库优化

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

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
• backend/app/api/v1/indicators.py

结论

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

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}	管理员/经理	删除指定模板

数据模型关系图

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
• backend/app/models/models.py