# 指标模板字段

<cite>
**本文档引用的文件**
- [models.py](file://backend/app/models/models.py)
- [schemas.py](file://backend/app/schemas/schemas.py)
- [templates.py](file://backend/app/api/v1/templates.py)
- [template_service.py](file://backend/app/services/template_service.py)
- [002_template.py](file://backend/alembic/versions/002_template.py)
- [init_templates.py](file://backend/app/scripts/init_templates.py)
- [init_indicator_templates.py](file://backend/init_indicator_templates.py)
- [Templates.vue](file://frontend/src/views/basic/Templates.vue)
- [template.js](file://frontend/src/api/template.js)
</cite>

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

## 简介
本文件聚焦于指标模板相关字段的数据字典，覆盖以下核心实体与关系：
- 指标模板表（IndicatorTemplate）
- 模板指标关联表（TemplateIndicator）
- 模板类型枚举（TemplateType）
- 指标与模板的多对多关联关系
- 维度权重配置与指标分类管理
- 模板版本管理与继承关系设计
- 激活状态与使用范围约束

本文件同时提供字段定义、约束说明、数据流向与前后端交互示例，帮助开发者与运维人员快速理解与使用模板系统。

## 项目结构
模板系统由后端模型与服务、API路由、前端页面与接口组成，形成“模型-服务-接口-视图”的完整链路。

```mermaid
graph TB
subgraph "后端"
M["models.py<br/>数据模型"]
S["template_service.py<br/>服务层"]
A["templates.py<br/>API路由"]
SC["schemas.py<br/>Pydantic模式"]
ALEMBIC["002_template.py<br/>迁移脚本"]
end
subgraph "前端"
V["Templates.vue<br/>模板管理页面"]
API["template.js<br/>模板API封装"]
end
V --> API
API --> A
A --> S
S --> M
M --> ALEMBIC
SC --> A
```

图表来源
- [models.py](file://backend/app/models/models.py#L387-L438)
- [template_service.py](file://backend/app/services/template_service.py#L20-L293)
- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
- [schemas.py](file://backend/app/schemas/schemas.py#L640-L743)
- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
- [Templates.vue](file://frontend/src/views/basic/Templates.vue#L1-L638)
- [template.js](file://frontend/src/api/template.js#L1-L62)

章节来源
- [models.py](file://backend/app/models/models.py#L387-L438)
- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
- [template_service.py](file://backend/app/services/template_service.py#L20-L293)
- [schemas.py](file://backend/app/schemas/schemas.py#L640-L743)
- [002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)
- [Templates.vue](file://frontend/src/views/basic/Templates.vue#L1-L638)
- [template.js](file://frontend/src/api/template.js#L1-L62)

## 核心组件
- 指标模板表（IndicatorTemplate）
  - 字段：id、template_name、template_code、template_type、description、dimension_weights、assessment_cycle、is_active、created_at、updated_at
  - 关系：与模板指标关联表一对多
  - 约束：唯一索引（template_code）、索引（template_type、is_active）

- 模板指标关联表（TemplateIndicator）
  - 字段：id、template_id、indicator_id、category、target_value、target_unit、weight、scoring_method、scoring_params、sort_order、remark、created_at、updated_at
  - 关系：与模板表、指标表多对一
  - 约束：唯一索引（template_id, indicator_id）、索引（template_id、indicator_id）

- 模板类型枚举（TemplateType）
  - 类型：general、surgical、nonsurgical_ward、nonsurgical_noward、medical_tech、nursing、admin、logistics

- 指标表（Indicator）
  - 字段：id、name、code、indicator_type、bs_dimension、weight、max_score、target_value、target_unit、calculation_method、assessment_method、deduction_standard、data_source、applicable_dept_types、is_veto、is_active、created_at、updated_at
  - 约束：CheckConstraint(weight > 0)

章节来源
- [models.py](file://backend/app/models/models.py#L387-L438)
- [models.py](file://backend/app/models/models.py#L117-L147)
- [models.py](file://backend/app/models/models.py#L375-L385)

## 架构总览
模板系统采用“模板-指标”多对多关系，通过模板指标关联表实现灵活配置。模板类型决定适用科室范围，维度权重用于汇总计算，指标分类用于二级归类，权重与评分方法用于最终得分计算。

```mermaid
erDiagram
INDICATOR_TEMPLATE {
int id PK
string template_name
string template_code UK
string 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
string indicator_type
string 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 : "被包含"
```

图表来源
- [models.py](file://backend/app/models/models.py#L387-L438)
- [models.py](file://backend/app/models/models.py#L117-L147)

## 详细组件分析

### 指标模板表（IndicatorTemplate）字段字典
- id
  - 类型：整数
  - 主键：是
  - 描述：模板主键
  - 约束：自增
  - 章节来源
    - [models.py](file://backend/app/models/models.py#L391-L391)

- template_name
  - 类型：字符串（最大长度200）
  - 描述：模板名称
  - 章节来源
    - [models.py](file://backend/app/models/models.py#L392-L392)
    - [schemas.py](file://backend/app/schemas/schemas.py#L699-L700)

- template_code
  - 类型：字符串（最大长度50）
  - 描述：模板编码（唯一）
  - 约束：唯一索引
  - 章节来源
    - [models.py](file://backend/app/models/models.py#L393-L393)
    - [002_template.py](file://backend/alembic/versions/002_template.py#L27-L36)
    - [schemas.py](file://backend/app/schemas/schemas.py#L700-L701)

- template_type
  - 类型：枚举（TemplateType）
  - 描述：模板类型
  - 取值：general、surgical、nonsurgical_ward、nonsurgical_noward、medical_tech、nursing、admin、logistics
  - 章节来源
    - [models.py](file://backend/app/models/models.py#L394-L394)
    - [schemas.py](file://backend/app/schemas/schemas.py#L702-L702)
    - [002_template.py](file://backend/alembic/versions/002_template.py#L28-L28)

- description
  - 类型：文本
  - 描述：模板描述
  - 章节来源
    - [models.py](file://backend/app/models/models.py#L395-L395)
    - [schemas.py](file://backend/app/schemas/schemas.py#L703-L703)

- dimension_weights
  - 类型：文本（JSON）
  - 描述：维度权重配置（财务、客户、内部流程、学习与成长）
  - 示例：{"financial": 35, "customer": 30, "internal_process": 25, "learning_growth": 10}
  - 章节来源
    - [models.py](file://backend/app/models/models.py#L396-L396)
    - [schemas.py](file://backend/app/schemas/schemas.py#L704-L704)
    - [init_templates.py](file://backend/app/scripts/init_templates.py#L88-L88)

- assessment_cycle
  - 类型：字符串（最大长度20）
  - 描述：考核周期（monthly/quarterly/annual）
  - 默认值：monthly
  - 章节来源
    - [models.py](file://backend/app/models/models.py#L397-L397)
    - [schemas.py](file://backend/app/schemas/schemas.py#L705-L705)
    - [init_templates.py](file://backend/app/scripts/init_templates.py#L89-L89)

- is_active
  - 类型：布尔
  - 描述：是否启用
  - 默认值：true
  - 章节来源
    - [models.py](file://backend/app/models/models.py#L398-L398)
    - [schemas.py](file://backend/app/schemas/schemas.py#L728-L728)
    - [002_template.py](file://backend/alembic/versions/002_template.py#L32-L32)

- created_at/updated_at
  - 类型：日期时间
  - 描述：创建与更新时间
  - 章节来源
    - [models.py](file://backend/app/models/models.py#L399-L400)
    - [models.py](file://backend/app/models/models.py#L400-L400)

- 关系与索引
  - 关系：与模板指标关联表一对多
  - 索引：template_type、is_active
  - 章节来源
    - [models.py](file://backend/app/models/models.py#L402-L408)
    - [002_template.py](file://backend/alembic/versions/002_template.py#L38-L39)

### 模板指标关联表（TemplateIndicator）字段字典
- id
  - 类型：整数
  - 主键：是
  - 描述：模板指标关联主键
  - 章节来源
    - [models.py](file://backend/app/models/models.py#L415-L415)

- template_id
  - 类型：整数
  - 外键：指向 indicator_templates.id
  - 描述：模板ID
  - 章节来源
    - [models.py](file://backend/app/models/models.py#L416-L416)
    - [002_template.py](file://backend/alembic/versions/002_template.py#L45-L57)

- indicator_id
  - 类型：整数
  - 外键：指向 indicators.id
  - 描述：指标ID
  - 章节来源
    - [models.py](file://backend/app/models/models.py#L417-L417)
    - [002_template.py](file://backend/alembic/versions/002_template.py#L46-L57)

- category
  - 类型：字符串（最大长度100）
  - 描述：指标分类（二级指标分类）
  - 示例：收支管理、患者满意度、质量与安全
  - 章节来源
    - [models.py](file://backend/app/models/models.py#L418-L418)
    - [schemas.py](file://backend/app/schemas/schemas.py#L657-L657)
    - [init_templates.py](file://backend/app/scripts/init_templates.py#L90-L108)

- target_value/target_unit
  - 类型：数值/字符串
  - 描述：目标值与单位
  - 章节来源
    - [models.py](file://backend/app/models/models.py#L419-L420)
    - [schemas.py](file://backend/app/schemas/schemas.py#L658-L659)

- weight
  - 类型：数值（默认1.0）
  - 描述：在模板内的权重
  - 章节来源
    - [models.py](file://backend/app/models/models.py#L421-L421)
    - [schemas.py](file://backend/app/schemas/schemas.py#L660-L660)
    - [init_templates.py](file://backend/app/scripts/init_templates.py#L91-L107)

- scoring_method/scoring_params
  - 类型：字符串/文本
  - 描述：评分方法与参数（JSON）
  - 方法：range、target、deduction、bonus、veto
  - 章节来源
    - [models.py](file://backend/app/models/models.py#L422-L423)
    - [schemas.py](file://backend/app/schemas/schemas.py#L661-L662)
    - [Templates.vue](file://frontend/src/views/basic/Templates.vue#L211-L217)

- sort_order
  - 类型：整数
  - 描述：排序
  - 默认值：0
  - 章节来源
    - [models.py](file://backend/app/models/models.py#L424-L424)
    - [template_service.py](file://backend/app/services/template_service.py#L191-L202)

- remark
  - 类型：文本
  - 描述：备注
  - 章节来源
    - [models.py](file://backend/app/models/models.py#L425-L425)

- created_at/updated_at
  - 类型：日期时间
  - 描述：创建与更新时间
  - 章节来源
    - [models.py](file://backend/app/models/models.py#L426-L427)

- 关系与索引
  - 关系：与模板表、指标表多对一
  - 索引：template_id、indicator_id、(template_id, indicator_id)唯一
  - 章节来源
    - [models.py](file://backend/app/models/models.py#L429-L437)
    - [002_template.py](file://backend/alembic/versions/002_template.py#L61-L63)

### 模板类型枚举（TemplateType）
- 取值与含义
  - general：通用模板
  - surgical：手术临床科室
  - nonsurgical_ward：非手术有病房科室
  - nonsurgical_noward：非手术无病房科室
  - medical_tech：医技科室
  - nursing：护理单元
  - admin：行政科室
  - logistics：后勤科室
- 使用场景
  - 用于区分模板适用科室类型，配合指标的适用科室类型字段实现过滤
- 章节来源
  - [models.py](file://backend/app/models/models.py#L375-L385)
  - [schemas.py](file://backend/app/schemas/schemas.py#L642-L652)

### 指标分类管理与维度权重配置
- 指标分类（category）
  - 作用：对模板内的指标进行二级分类，便于统计与展示
  - 示例：收支管理、患者满意度、质量与安全、内部服务效率等
  - 章节来源
    - [models.py](file://backend/app/models/models.py#L418-L418)
    - [init_templates.py](file://backend/app/scripts/init_templates.py#L90-L108)

- 维度权重（dimension_weights）
  - 结构：JSON对象，键为维度标识，值为百分比
  - 维度：financial、customer、internal_process、learning_growth
  - 用途：用于模板层面的维度汇总与权重分配
  - 章节来源
    - [models.py](file://backend/app/models/models.py#L396-L396)
    - [schemas.py](file://backend/app/schemas/schemas.py#L704-L704)
    - [init_templates.py](file://backend/app/scripts/init_templates.py#L88-L88)

- 指标维度（bs_dimension）
  - 作用：指标所属的平衡计分卡维度，与模板维度权重协同使用
  - 章节来源
    - [models.py](file://backend/app/models/models.py#L125-L125)
    - [init_templates.py](file://backend/init_indicator_templates.py#L28-L38)

### 模板与指标的多对多关联与权重分配机制
- 关联关系
  - 通过 TemplateIndicator 实现模板与指标的多对多绑定
  - 每个模板内的指标可独立设置权重、目标值、评分方法等
- 权重分配
  - 模板维度权重：用于模板层面的维度汇总
  - 指标权重：用于模板内指标的加权计算
- 章节来源
  - [models.py](file://backend/app/models/models.py#L411-L431)
  - [template_service.py](file://backend/app/services/template_service.py#L110-L124)

### 模板版本管理与继承关系
- 版本字段
  - 当前模型未内置版本字段；如需版本管理，可在模板表中扩展 version 字段
- 继承关系
  - 可通过模板类型与指标适用科室类型实现“继承”效果：通用模板可作为特定模板的父模板，再叠加差异字段
- 章节来源
  - [models.py](file://backend/app/models/models.py#L391-L400)
  - [init_templates.py](file://backend/app/scripts/init_templates.py#L82-L186)

### 激活状态与使用范围约束
- 激活状态（is_active）
  - 控制模板是否可用
  - 前端通过开关切换，后端接口支持批量更新
- 使用范围
  - 模板类型（template_type）限定适用科室类型
  - 指标的适用科室类型（applicable_dept_types）进一步限制
- 章节来源
  - [models.py](file://backend/app/models/models.py#L398-L398)
  - [models.py](file://backend/app/models/models.py#L134-L134)
  - [templates.py](file://backend/app/api/v1/templates.py#L22-L42)

## 依赖分析
模板系统的关键依赖关系如下：

```mermaid
graph LR
ENUM["TemplateType 枚举"] --> IT["IndicatorTemplate 模型"]
IT --> TI["TemplateIndicator 模型"]
IND["Indicator 模型"] --> TI
SVC["TemplateService 服务"] --> IT
SVC --> TI
API["templates.py 路由"] --> SVC
SCHEMA["schemas.py 模式"] --> API
FRONT["Templates.vue 页面"] --> API
API --> FRONT
```

图表来源
- [models.py](file://backend/app/models/models.py#L375-L385)
- [models.py](file://backend/app/models/models.py#L387-L438)
- [template_service.py](file://backend/app/services/template_service.py#L20-L293)
- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
- [schemas.py](file://backend/app/schemas/schemas.py#L640-L743)
- [Templates.vue](file://frontend/src/views/basic/Templates.vue#L1-L638)

章节来源
- [models.py](file://backend/app/models/models.py#L375-L385)
- [models.py](file://backend/app/models/models.py#L387-L438)
- [template_service.py](file://backend/app/services/template_service.py#L20-L293)
- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
- [schemas.py](file://backend/app/schemas/schemas.py#L640-L743)
- [Templates.vue](file://frontend/src/views/basic/Templates.vue#L1-L638)

## 性能考虑
- 查询优化
  - 模板列表按 template_type 与 is_active 进行过滤，建议保持索引有效
  - 模板详情加载时使用 selectinload 预加载关联指标，避免 N+1 查询
- 写入优化
  - 批量添加模板指标时，服务层会自动设置排序，减少重复计算
- 前端渲染
  - 前端对维度权重进行 JSON 解析与可视化展示，注意空值处理与错误捕获

## 故障排查指南
- 模板编码冲突
  - 现象：创建模板时报错“模板编码已存在”
  - 排查：检查唯一索引约束与迁移脚本
  - 章节来源
    - [templates.py](file://backend/app/api/v1/templates.py#L136-L139)
    - [002_template.py](file://backend/alembic/versions/002_template.py#L36-L36)

- 指标重复添加
  - 现象：添加模板指标返回失败
  - 排查：检查唯一索引（template_id, indicator_id）
  - 章节来源
    - [template_service.py](file://backend/app/services/template_service.py#L174-L182)
    - [002_template.py](file://backend/alembic/versions/002_template.py#L63-L63)

- 维度权重解析失败
  - 现象：前端维度权重显示异常
  - 排查：确认 JSON 格式正确，服务端/前端均做容错处理
  - 章节来源
    - [Templates.vue](file://frontend/src/views/basic/Templates.vue#L310-L317)

- 指标权重校验
  - 现象：指标权重小于等于0导致异常
  - 排查：数据库层有 CheckConstraint，前端也应限制输入范围
  - 章节来源
    - [models.py](file://backend/app/models/models.py#L145-L145)
    - [schemas.py](file://backend/app/schemas/schemas.py#L158-L158)

## 结论
指标模板系统通过清晰的模型设计与严格的约束，实现了模板类型、维度权重、指标分类与权重分配的灵活配置。模板与指标的多对多关系通过关联表实现解耦，支持按科室类型与适用范围进行精细化管理。建议后续在模板表中增加版本字段以完善版本管理能力，并在前端增强对 JSON 参数的校验与提示，提升系统的稳定性与易用性。