# 模板管理
**本文引用的文件**
- [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/scripts/init_templates.py](file://backend/app/scripts/init_templates.py)
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py)
- [backend/app/models/models.py](file://backend/app/models/models.py)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py)
- [frontend/src/views/basic/Templates.vue](file://frontend/src/views/basic/Templates.vue)
- [frontend/src/api/template.js](file://frontend/src/api/template.js)
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本章节面向“医院绩效系统”的“模板管理”功能，系统化阐述模板的设计与管理流程，覆盖模板类型定义、模板内容配置、模板版本管理、模板应用规则、模板初始化脚本、模板继承机制、模板自定义字段、模板发布流程、模板编辑器、模板预览、模板复制与批量应用、模板与指标体系的关联关系、模板使用统计以及模板更新机制等。
## 项目结构
模板管理功能由后端API路由、服务层、数据模型与前端页面协同实现，配合数据库迁移脚本完成模板相关表结构的演进与初始化数据注入。
```mermaid
graph TB
subgraph "前端"
FE_Templates["Templates.vue
模板管理界面"]
FE_API["template.js
API封装"]
end
subgraph "后端"
API["templates.py
模板API路由"]
SVC["template_service.py
模板服务层"]
MODELS["models.py
数据模型"]
SCHEMAS["schemas.py
数据模式"]
INIT["init_templates.py
模板初始化脚本"]
MIG["002_template.py
数据库迁移"]
end
FE_Templates --> FE_API
FE_API --> API
API --> SVC
SVC --> MODELS
SVC --> SCHEMAS
INIT --> MODELS
MIG --> MODELS
```
图表来源
- [frontend/src/views/basic/Templates.vue](file://frontend/src/views/basic/Templates.vue#L1-L638)
- [frontend/src/api/template.js](file://frontend/src/api/template.js#L1-L62)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L1-L272)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L1-L293)
- [backend/app/models/models.py](file://backend/app/models/models.py#L375-L438)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L375-L437)
- [backend/app/scripts/init_templates.py](file://backend/app/scripts/init_templates.py#L1-L276)
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
章节来源
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L1-L272)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L1-L293)
- [backend/app/scripts/init_templates.py](file://backend/app/scripts/init_templates.py#L1-L276)
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L1-L96)
- [backend/app/models/models.py](file://backend/app/models/models.py#L375-L438)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L375-L437)
- [frontend/src/views/basic/Templates.vue](file://frontend/src/views/basic/Templates.vue#L1-L638)
- [frontend/src/api/template.js](file://frontend/src/api/template.js#L1-L62)
## 核心组件
- 模板API路由：提供模板列表、详情、创建、更新、删除、模板指标管理（增删改查、批量导入）等REST接口。
- 模板服务层：封装模板与模板指标的CRUD逻辑、分页查询、校验与去重、排序维护等。
- 数据模型：定义模板、模板指标关联、BSC维度、模板类型枚举等。
- 数据模式：定义请求/响应的数据结构与校验规则。
- 初始化脚本：按模板文档生成指标与模板数据，建立模板与指标的初始映射。
- 数据库迁移：定义模板表、模板指标关联表及指标表扩展字段。
- 前端页面：模板列表、详情、维度权重可视化、指标表格、新增/编辑弹窗、批量导入等。
章节来源
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L22-L170)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L20-L293)
- [backend/app/models/models.py](file://backend/app/models/models.py#L375-L438)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L375-L437)
- [backend/app/scripts/init_templates.py](file://backend/app/scripts/init_templates.py#L189-L276)
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
- [frontend/src/views/basic/Templates.vue](file://frontend/src/views/basic/Templates.vue#L1-L638)
## 架构总览
模板管理采用典型的三层架构：前端负责交互与展示；后端API路由处理请求与响应；服务层协调数据访问与业务规则；模型层定义持久化结构；迁移脚本与初始化脚本确保数据库结构与种子数据一致。
```mermaid
graph TB
Client["浏览器/移动端"] --> FE["前端页面
Templates.vue"]
FE --> API["FastAPI路由
templates.py"]
API --> SVC["模板服务层
template_service.py"]
SVC --> DB["数据库
SQLAlchemy ORM"]
DB --> MODELS["模型定义
models.py"]
INIT["初始化脚本
init_templates.py"] --> DB
MIG["迁移脚本
002_template.py"] --> DB
```
图表来源
- [frontend/src/views/basic/Templates.vue](file://frontend/src/views/basic/Templates.vue#L1-L638)
- [frontend/src/api/template.js](file://frontend/src/api/template.js#L1-L62)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L1-L272)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L1-L293)
- [backend/app/models/models.py](file://backend/app/models/models.py#L375-L438)
- [backend/app/scripts/init_templates.py](file://backend/app/scripts/init_templates.py#L189-L276)
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
## 详细组件分析
### 模板类型与维度
- 模板类型：通用模板、手术临床科室、非手术有病房科室、非手术无病房科室、医技科室、护理单元、行政科室、后勤科室。
- BSC维度：财务管理、顾客服务、内部流程、学习与成长，配套维度权重范围用于指导权重分配。
章节来源
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L45-L74)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L269-L293)
### 模板内容配置
- 模板基础信息：模板名称、模板编码、模板类型、描述、维度权重（JSON）、考核周期、启用状态。
- 模板指标：指标ID、分类、目标值/单位、权重、评分方法、评分参数、排序、备注。
- 前端支持：维度权重可视化、指标表格、评分方法枚举、目标值/单位输入、排序维护。
章节来源
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L77-L126)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L375-L437)
- [frontend/src/views/basic/Templates.vue](file://frontend/src/views/basic/Templates.vue#L61-L118)
### 模板版本管理
- 版本字段存在于“绩效计划”模型中，用于计划层面的版本控制；模板本身未显式版本字段。
- 建议在模板模型中增加版本字段与版本号递增策略，以支持模板演进与审计。
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L293-L296)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L520-L570)
### 模板应用规则
- 模板与指标通过“模板指标关联表”建立多对多关系，支持按模板类型匹配适用科室。
- 指标表扩展字段包含适用科室类型（JSON数组）、BSC维度、目标值单位、考核方法、扣分标准、数据来源、是否一票否决等，便于模板应用时的规则匹配与评分。
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L147)
- [backend/app/models/models.py](file://backend/app/models/models.py#L411-L437)
### 模板初始化脚本
- 初始化脚本按模板文档生成指标与模板数据，自动建立模板与指标的映射关系，并写入维度权重、排序等。
- 通过异步引擎连接数据库，避免重复创建，保证幂等性。
章节来源
- [backend/app/scripts/init_templates.py](file://backend/app/scripts/init_templates.py#L189-L276)
### 模板继承机制
- 当前代码未实现模板继承；模板间复用主要通过“批量添加模板指标”与“复制模板”实现。
- 建议引入模板继承字段（如父模板ID），在读取模板详情时合并父模板指标，以降低重复配置成本。
章节来源
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L252-L271)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L160-L206)
### 模板自定义字段
- 模板指标支持自定义字段：分类、目标值/单位、权重、评分方法、评分参数、排序、备注。
- 指标表扩展字段支持适用科室类型、BSC维度、目标值单位、考核方法、扣分标准、数据来源、是否一票否决等。
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L411-L437)
- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L147)
### 模板发布流程
- 发布即启用模板（is_active），前端提供开关切换；后端在更新模板时仅允许管理员或经理权限。
- 建议增加“发布/撤销发布”状态流转与审批流程，以满足正式发布的合规要求。
章节来源
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L145-L169)
- [frontend/src/views/basic/Templates.vue](file://frontend/src/views/basic/Templates.vue#L25-L29)
### 模板编辑器功能
- 前端提供模板编辑弹窗，支持维度权重输入、描述编辑、考核周期选择。
- 提供指标编辑弹窗，支持分类、目标值/单位、权重、评分方法、评分参数、备注等字段编辑。
章节来源
- [frontend/src/views/basic/Templates.vue](file://frontend/src/views/basic/Templates.vue#L122-L172)
- [frontend/src/views/basic/Templates.vue](file://frontend/src/views/basic/Templates.vue#L174-L232)
### 模板预览
- 前端在模板详情卡片中展示维度权重进度条、指标列表、评分方法标签等，便于快速预览模板构成。
章节来源
- [frontend/src/views/basic/Templates.vue](file://frontend/src/views/basic/Templates.vue#L69-L118)
### 模板复制与批量应用
- 批量添加模板指标：支持传入指标列表，自动维护排序，提升批量应用效率。
- 复制模板：建议在后端提供“复制模板”接口，克隆模板与指标映射，减少重复配置。
章节来源
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L252-L271)
### 模板与指标体系的关联关系
- 模板与指标通过“模板指标关联表”建立一对一映射（同一模板下同一指标仅出现一次），并支持排序与自定义权重。
- 指标表扩展字段支持适用科室类型、BSC维度等，便于模板按科室类型筛选适用指标。
```mermaid
erDiagram
INDICATOR_TEMPLATE {
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_INDICATOR {
int id PK
int template_id FK
int indicator_id FK
string category
numeric target_value
string target_unit
numeric weight
string scoring_method
text scoring_params
int sort_order
text remark
datetime created_at
datetime updated_at
}
INDICATOR {
int id PK
string name
string code UK
enum indicator_type
enum bs_dimension
numeric weight
numeric max_score
numeric 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
datetime created_at
datetime updated_at
}
INDICATOR_TEMPLATE ||--o{ TEMPLATE_INDICATOR : "包含"
INDICATOR ||--o{ TEMPLATE_INDICATOR : "被包含"
```
图表来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L387-L437)
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L387-L437)
### 模板使用统计与模板更新机制
- 使用统计：可在服务层扩展统计逻辑，统计各模板被应用次数、指标数量、维度权重分布等。
- 更新机制：当前通过更新模板接口进行，建议增加变更记录与版本对比，便于审计与回滚。
章节来源
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L30-L71)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L145-L156)
## 依赖关系分析
模板管理涉及前后端与数据库的多层依赖，需关注以下耦合点：
- 前端与后端API：通过统一的HTTP接口交互，前端依赖模板与指标的增删改查接口。
- 后端服务层与模型层：服务层依赖模型层的ORM定义与索引约束。
- 迁移脚本与初始化脚本：共同决定数据库结构与初始数据，需保持一致性。
```mermaid
graph LR
FE["Templates.vue"] --> API["templates.py"]
API --> SVC["template_service.py"]
SVC --> MODELS["models.py"]
SVC --> SCHEMAS["schemas.py"]
INIT["init_templates.py"] --> MODELS
MIG["002_template.py"] --> MODELS
```
图表来源
- [frontend/src/views/basic/Templates.vue](file://frontend/src/views/basic/Templates.vue#L1-L638)
- [frontend/src/api/template.js](file://frontend/src/api/template.js#L1-L62)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L1-L272)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L1-L293)
- [backend/app/models/models.py](file://backend/app/models/models.py#L375-L438)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L375-L437)
- [backend/app/scripts/init_templates.py](file://backend/app/scripts/init_templates.py#L1-L276)
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L1-L96)
章节来源
- [frontend/src/views/basic/Templates.vue](file://frontend/src/views/basic/Templates.vue#L1-L638)
- [frontend/src/api/template.js](file://frontend/src/api/template.js#L1-L62)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L1-L272)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L1-L293)
- [backend/app/models/models.py](file://backend/app/models/models.py#L375-L438)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L375-L437)
- [backend/app/scripts/init_templates.py](file://backend/app/scripts/init_templates.py#L1-L276)
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L1-L96)
## 性能考量
- 查询性能：模板列表与详情查询已使用索引（模板类型、启用状态、模板指标唯一索引），建议在高频查询场景下增加复合索引与缓存。
- 写入性能：批量添加模板指标时逐条插入，建议在服务层使用批量插入优化。
- 前端渲染：指标列表较多时建议虚拟滚动与懒加载，减少DOM压力。
## 故障排查指南
- 模板不存在：当更新或删除模板时若返回“模板不存在”，请检查模板ID与权限。
- 指标已存在：添加模板指标时若返回失败，请确认同一模板下指标不重复。
- 编码冲突：创建模板时若提示“模板编码已存在”，请更换唯一编码。
- 权限不足：模板管理接口需要管理员或经理权限，请确认当前用户角色。
章节来源
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L136-L142)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L153-L156)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L217-L220)
## 结论
模板管理功能围绕“模板—指标”关系展开，通过API路由、服务层与前端页面形成闭环。当前实现覆盖了模板类型、维度权重、指标配置、批量导入与前端可视化等关键能力。为进一步增强可维护性与合规性，建议补充模板版本管理、模板继承、发布审批流程与使用统计分析。
## 附录
### 模板API调用序列
```mermaid
sequenceDiagram
participant FE as "前端页面"
participant API as "模板API路由"
participant SVC as "模板服务层"
participant DB as "数据库"
FE->>API : GET /templates
API->>SVC : get_list()
SVC->>DB : 查询模板列表与总数
DB-->>SVC : 返回结果
SVC-->>API : 模板列表与总数
API-->>FE : 分页响应
FE->>API : GET /templates/{id}
API->>SVC : get_by_id()
SVC->>DB : 加载模板与指标
DB-->>SVC : 返回模板详情
SVC-->>API : 模板详情
API-->>FE : 详情响应
FE->>API : POST /templates
API->>SVC : create()
SVC->>DB : 插入模板与指标
DB-->>SVC : 提交成功
SVC-->>API : 返回模板ID
API-->>FE : 创建成功
```
图表来源
- [frontend/src/api/template.js](file://frontend/src/api/template.js#L3-L36)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L22-L170)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L92-L128)