提交文件

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/数据库设计/数据字典/指标模板字段.md
+++ b/.qoder/repowiki/zh/content/数据库设计/数据字典/指标模板字段.md
@@ -0,0 +1,473 @@
+# 指标模板字段
+
+<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 参数的校验与提示，提升系统的稳定性与易用性。