提交文件

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,363 @@
+# 模板管理
+
+<cite>
+**本文引用的文件**
+- [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)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考量](#性能考量)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本章节面向“医院绩效系统”的“模板管理”功能，系统化阐述模板的设计与管理流程，覆盖模板类型定义、模板内容配置、模板版本管理、模板应用规则、模板初始化脚本、模板继承机制、模板自定义字段、模板发布流程、模板编辑器、模板预览、模板复制与批量应用、模板与指标体系的关联关系、模板使用统计以及模板更新机制等。
+
+## 项目结构
+模板管理功能由后端API路由、服务层、数据模型与前端页面协同实现，配合数据库迁移脚本完成模板相关表结构的演进与初始化数据注入。
+
+```mermaid
+graph TB
+subgraph "前端"
+FE_Templates["Templates.vue<br/>模板管理界面"]
+FE_API["template.js<br/>API封装"]
+end
+subgraph "后端"
+API["templates.py<br/>模板API路由"]
+SVC["template_service.py<br/>模板服务层"]
+MODELS["models.py<br/>数据模型"]
+SCHEMAS["schemas.py<br/>数据模式"]
+INIT["init_templates.py<br/>模板初始化脚本"]
+MIG["002_template.py<br/>数据库迁移"]
+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["前端页面<br/>Templates.vue"]
+FE --> API["FastAPI路由<br/>templates.py"]
+API --> SVC["模板服务层<br/>template_service.py"]
+SVC --> DB["数据库<br/>SQLAlchemy ORM"]
+DB --> MODELS["模型定义<br/>models.py"]
+INIT["初始化脚本<br/>init_templates.py"] --> DB
+MIG["迁移脚本<br/>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)