提交文件

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,454 @@
+# 模板管理接口
+
+<cite>
+**本文档引用的文件**
+- [templates.py](file://backend/app/api/v1/templates.py)
+- [template_service.py](file://backend/app/services/template_service.py)
+- [models.py](file://backend/app/models/models.py)
+- [schemas.py](file://backend/app/schemas/schemas.py)
+- [template.js](file://frontend/src/api/template.js)
+- [Templates.vue](file://frontend/src/views/basic/Templates.vue)
+- [init_templates.py](file://backend/app/scripts/init_templates.py)
+- [002_template.py](file://backend/alembic/versions/002_template.py)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+
+## 简介
+
+模板管理接口是医院绩效管理系统的核心功能模块，负责管理各类绩效考核模板的完整生命周期。该系统实现了基于平衡计分卡理论的多维度绩效考核模板管理，支持通用模板、手术科室模板、医技科室模板等多种模板类型，为不同科室提供定制化的绩效考核方案。
+
+系统采用FastAPI框架构建，基于异步数据库连接，确保高并发场景下的性能表现。模板管理功能涵盖了从模板创建、配置到删除的完整流程，同时支持模板指标的精细化管理，包括指标权重设置、评分方法配置等高级功能。
+
+## 项目结构
+
+模板管理模块在项目中的组织结构如下：
+
+```mermaid
+graph TB
+subgraph "后端架构"
+API[API路由层<br/>templates.py]
+Service[服务层<br/>template_service.py]
+Model[数据模型层<br/>models.py]
+Schema[数据模式层<br/>schemas.py]
+end
+subgraph "前端架构"
+FrontAPI[前端API封装<br/>template.js]
+FrontView[模板管理界面<br/>Templates.vue]
+end
+subgraph "数据层"
+DB[(数据库)]
+Alembic[Alembic迁移<br/>002_template.py]
+end
+FrontAPI --> API
+FrontView --> FrontAPI
+API --> Service
+Service --> Model
+Model --> DB
+Schema --> API
+Alembic --> DB
+```
+
+**图表来源**
+- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
+- [template_service.py](file://backend/app/services/template_service.py#L1-L293)
+- [models.py](file://backend/app/models/models.py#L387-L437)
+
+**章节来源**
+- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
+- [template_service.py](file://backend/app/services/template_service.py#L1-L293)
+- [models.py](file://backend/app/models/models.py#L387-L437)
+
+## 核心组件
+
+### 数据模型组件
+
+系统采用三层架构的数据模型设计，包含以下核心实体：
+
+#### 模板实体 (IndicatorTemplate)
+- **主键**: 自增ID
+- **模板标识**: 唯一模板编码和名称
+- **模板类型**: 支持8种预定义类型
+- **配置属性**: 维度权重、考核周期、启用状态
+- **关联关系**: 一对多关联到模板指标
+
+#### 指标实体 (TemplateIndicator)
+- **主键**: 自增ID
+- **关联属性**: 模板ID、指标ID
+- **配置属性**: 分类、目标值、权重、评分方法
+- **排序机制**: 支持自定义排序顺序
+- **唯一约束**: 模板ID+指标ID组合唯一
+
+#### 枚举类型
+- **模板类型**: 通用、手术、非手术有病房、非手术无病房、医技、护理、行政、后勤
+- **BSC维度**: 财务管理、顾客服务、内部流程、学习与成长
+- **指标类型**: 质量、数量、效率、服务、成本
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L375-L437)
+- [schemas.py](file://backend/app/schemas/schemas.py#L640-L743)
+
+### 服务层组件
+
+#### TemplateService 类
+提供完整的模板管理业务逻辑：
+- **查询功能**: 列表查询、详情获取、按类型过滤
+- **CRUD操作**: 创建、更新、删除模板
+- **指标管理**: 添加、更新、删除模板指标
+- **批量操作**: 批量添加模板指标
+- **工具方法**: 类型标签转换、维度标签转换
+
+**章节来源**
+- [template_service.py](file://backend/app/services/template_service.py#L20-L293)
+
+### API路由组件
+
+#### 模板管理路由
+- **GET /templates**: 获取模板列表，支持类型过滤和分页
+- **GET /templates/types**: 获取模板类型列表
+- **GET /templates/dimensions**: 获取BSC维度列表
+- **GET /templates/{id}**: 获取模板详情
+- **POST /templates**: 创建模板
+- **PUT /templates/{id}**: 更新模板
+- **DELETE /templates/{id}**: 删除模板
+
+#### 模板指标管理路由
+- **GET /templates/{template_id}/indicators**: 获取模板指标列表
+- **POST /templates/{template_id}/indicators**: 添加模板指标
+- **PUT /templates/{template_id}/indicators/{indicator_id}**: 更新模板指标
+- **DELETE /templates/{template_id}/indicators/{indicator_id}**: 移除模板指标
+- **POST /templates/{template_id}/indicators/batch**: 批量添加模板指标
+
+**章节来源**
+- [templates.py](file://backend/app/api/v1/templates.py#L22-L272)
+
+## 架构概览
+
+系统采用分层架构设计，确保关注点分离和代码可维护性：
+
+```mermaid
+sequenceDiagram
+participant Client as 前端客户端
+participant API as API路由层
+participant Service as 服务层
+participant DB as 数据库
+participant Model as 数据模型
+Client->>API : GET /templates
+API->>Service : get_list()
+Service->>DB : 查询模板列表
+DB->>Service : 返回模板数据
+Service->>Service : 统计指标数量
+Service->>API : 返回处理后的数据
+API->>Client : JSON响应
+Note over Client,DB : 异步数据库操作，支持高并发
+```
+
+**图表来源**
+- [templates.py](file://backend/app/api/v1/templates.py#L22-L42)
+- [template_service.py](file://backend/app/services/template_service.py#L24-L71)
+
+### 数据流架构
+
+```mermaid
+flowchart TD
+subgraph "前端层"
+FE_API[前端API调用]
+FE_VIEW[模板管理界面]
+end
+subgraph "后端层"
+ROUTER[路由处理]
+SERVICE[业务逻辑]
+VALIDATION[数据验证]
+end
+subgraph "数据层"
+MODEL[ORM模型]
+DATABASE[(数据库)]
+end
+FE_API --> ROUTER
+FE_VIEW --> FE_API
+ROUTER --> VALIDATION
+VALIDATION --> SERVICE
+SERVICE --> MODEL
+MODEL --> DATABASE
+DATABASE --> MODEL
+MODEL --> SERVICE
+SERVICE --> ROUTER
+ROUTER --> FE_API
+```
+
+**图表来源**
+- [template.js](file://frontend/src/api/template.js#L1-L62)
+- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
+
+## 详细组件分析
+
+### 模板类型分类系统
+
+系统支持8种预定义的模板类型，每种类型针对特定的科室特点设计：
+
+#### 通用模板 (GENERAL)
+- **适用范围**: 全院各科室
+- **特点**: 基于平衡计分卡四维度设计
+- **典型权重**: 财务35%、客户30%、内部流程25%、学习成长10%
+
+#### 手术科室模板 (SURGICAL)
+- **适用范围**: 外科、妇科、眼科等手术科室
+- **特点**: 结合RBRVS和DRG理念
+- **重点指标**: DRG组数、CMI值、费用消耗指数
+
+#### 医技科室模板 (MEDICAL_TECH)
+- **适用范围**: 检验科、放射科、超声科等
+- **特点**: 质量效率双核心
+- **重点指标**: 报告准确率、危急值及时率
+
+#### 行政科室模板 (ADMIN)
+- **适用范围**: 院办、党办、医务科等
+- **特点**: 服务支持导向
+- **重点指标**: 服务态度、遵纪守法
+
+#### 后勤科室模板 (LOGISTICS)
+- **适用范围**: 总务科、设备科等
+- **特点**: 后勤保障核心
+- **重点指标**: 保障及时率、设备完好率
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L375-L384)
+- [schemas.py](file://backend/app/schemas/schemas.py#L642-L651)
+
+### 模板数据结构定义
+
+#### 模板基础结构
+| 字段名 | 类型 | 描述 | 必填 |
+|--------|------|------|------|
+| template_name | String | 模板名称 | 是 |
+| template_code | String | 模板编码 | 是 |
+| template_type | Enum | 模板类型 | 是 |
+| description | Text | 模板描述 | 否 |
+| dimension_weights | JSON | 维度权重配置 | 否 |
+| assessment_cycle | String | 考核周期 | 否 |
+| is_active | Boolean | 是否启用 | 否 |
+
+#### 模板指标结构
+| 字段名 | 类型 | 描述 | 必填 |
+|--------|------|------|------|
+| indicator_id | Integer | 指标ID | 是 |
+| category | String | 指标分类 | 否 |
+| target_value | Float | 目标值 | 否 |
+| target_unit | String | 目标值单位 | 否 |
+| weight | Float | 权重 | 否 |
+| scoring_method | String | 评分方法 | 否 |
+| scoring_params | JSON | 评分参数 | 否 |
+| sort_order | Integer | 排序 | 否 |
+| remark | Text | 备注 | 否 |
+
+**章节来源**
+- [schemas.py](file://backend/app/schemas/schemas.py#L698-L743)
+- [schemas.py](file://backend/app/schemas/schemas.py#L654-L696)
+
+### 模板继承与复用机制
+
+系统通过模板继承机制实现模板的复用和扩展：
+
+```mermaid
+classDiagram
+class IndicatorTemplate {
+Integer id
+String template_code
+String template_name
+TemplateType template_type
+String description
+String dimension_weights
+String assessment_cycle
+Boolean is_active
+DateTime created_at
+DateTime updated_at
+TemplateIndicator[] indicators
+}
+class TemplateIndicator {
+Integer id
+Integer template_id
+Integer indicator_id
+String category
+Float target_value
+String target_unit
+Float weight
+String scoring_method
+String scoring_params
+Integer sort_order
+String remark
+DateTime created_at
+DateTime updated_at
+}
+class Indicator {
+Integer id
+String code
+String name
+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
+Boolean is_veto
+Boolean is_active
+}
+IndicatorTemplate "1" -- "many" TemplateIndicator : "包含"
+TemplateIndicator "many" -- "1" Indicator : "关联"
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L387-L437)
+
+### 版本控制实现
+
+虽然模板管理接口没有直接的版本控制功能，但系统通过以下机制实现版本管理：
+
+1. **模板历史记录**: 每个模板都有创建时间和更新时间
+2. **状态管理**: 通过`is_active`字段控制模板启用状态
+3. **数据完整性**: 使用数据库约束确保数据一致性
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L391-L400)
+
+### 批量操作功能
+
+系统提供了完善的批量操作功能：
+
+#### 批量添加模板指标
+- **接口**: POST `/templates/{template_id}/indicators/batch`
+- **功能**: 支持一次性添加多个模板指标
+- **特性**: 自动设置排序顺序，支持部分字段配置
+
+#### 批量处理流程
+```mermaid
+flowchart TD
+Start([开始批量添加]) --> Validate["验证模板ID"]
+Validate --> Loop{"遍历指标数组"}
+Loop --> |是| CheckOrder["检查排序设置"]
+CheckOrder --> AddIndicator["添加模板指标"]
+AddIndicator --> UpdateCount["增加成功计数"]
+UpdateCount --> Loop
+Loop --> |否| ReturnResult["返回处理结果"]
+ReturnResult --> End([结束])
+```
+
+**图表来源**
+- [templates.py](file://backend/app/api/v1/templates.py#L252-L271)
+
+**章节来源**
+- [templates.py](file://backend/app/api/v1/templates.py#L252-L271)
+
+## 依赖关系分析
+
+### 组件耦合关系
+
+```mermaid
+graph TB
+subgraph "API层"
+TPL_API[templates.py]
+end
+subgraph "服务层"
+TPL_SERVICE[template_service.py]
+end
+subgraph "模型层"
+MODELS[models.py]
+ENUMS[枚举类型]
+end
+subgraph "数据层"
+SCHEMAS[schemas.py]
+DB[(数据库)]
+end
+TPL_API --> TPL_SERVICE
+TPL_SERVICE --> MODELS
+MODELS --> ENUMS
+MODELS --> DB
+TPL_API --> SCHEMAS
+SCHEMAS --> MODELS
+```
+
+**图表来源**
+- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
+- [template_service.py](file://backend/app/services/template_service.py#L1-L293)
+
+### 外部依赖
+
+系统主要依赖以下外部组件：
+- **FastAPI**: Web框架，提供异步API支持
+- **SQLAlchemy**: ORM框架，处理数据库操作
+- **Alembic**: 数据库迁移工具
+- **Pydantic**: 数据验证和序列化
+
+**章节来源**
+- [templates.py](file://backend/app/api/v1/templates.py#L1-L18)
+- [template_service.py](file://backend/app/services/template_service.py#L1-L18)
+
+## 性能考虑
+
+### 数据库优化策略
+
+1. **索引优化**: 模板类型和启用状态字段建立了复合索引
+2. **查询优化**: 使用分页查询避免大数据集加载
+3. **连接池**: 异步数据库连接池提高并发性能
+
+### 缓存策略
+
+系统目前采用懒加载策略，通过`selectinload`优化N+1查询问题，减少数据库访问次数。
+
+### 并发处理
+
+- **异步操作**: 所有数据库操作都是异步的
+- **事务管理**: 自动事务提交和回滚
+- **错误处理**: 完善的异常处理机制
+
+## 故障排除指南
+
+### 常见问题及解决方案
+
+#### 模板编码重复
+**问题**: 创建模板时报错"模板编码已存在"
+**原因**: 模板编码必须唯一
+**解决**: 修改模板编码或使用系统生成的新编码
+
+#### 模板不存在
+**问题**: 更新或删除模板时报错"模板不存在"
+**原因**: 模板ID无效或已被删除
+**解决**: 检查模板ID有效性或重新获取模板列表
+
+#### 指标已存在
+**问题**: 添加模板指标时报错"指标已存在"
+**原因**: 同一模板中重复添加相同指标
+**解决**: 移除重复指标或使用新的指标ID
+
+#### 权限不足
+**问题**: 访问受保护的模板管理功能被拒绝
+**原因**: 当前用户角色不满足管理员或经理权限要求
+**解决**: 登录具有相应权限的账户或联系系统管理员
+
+**章节来源**
+- [templates.py](file://backend/app/api/v1/templates.py#L136-L168)
+- [template_service.py](file://backend/app/services/template_service.py#L167-L182)
+
+## 结论
+
+模板管理接口为医院绩效管理系统提供了完整的模板生命周期管理能力。通过8种预定义的模板类型、灵活的指标配置和强大的批量操作功能，系统能够满足不同类型科室的绩效考核需求。
+
+系统采用现代化的架构设计，基于FastAPI和SQLAlchemy构建，确保了高性能和高可用性。模板继承机制和复用策略使得系统具有良好的扩展性和维护性。
+
+未来可以考虑的功能增强包括：
+- 模板版本控制功能
+- 模板复制和导入导出功能
+- 更丰富的模板指标评分算法
+- 模板使用统计和分析功能