提交文件

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,753 @@
+# 考核指标管理接口
+
+<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)