chenqi/hospital_performance
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

提交文件

Browse Source
This commit is contained in:
chenqi
2026-02-28 15:16:15 +08:00
parent 1a4e50e0a4
commit 44f250f58e
159 changed files with 61268 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

338
.qoder/repowiki/zh/content/核心功能模块/基础数据管理/员工管理.md Normal file
View File

@@ -0,0 +1,338 @@
# 员工管理
<cite>
**本文引用的文件**
- [staff.py](file://backend/app/api/v1/staff.py)
- [staff_service.py](file://backend/app/services/staff_service.py)
- [models.py](file://backend/app/models/models.py)
- [schemas.py](file://backend/app/schemas/schemas.py)
- [security.py](file://backend/app/core/security.py)
- [Staff.vue](file://frontend/src/views/basic/Staff.vue)
- [staff.js](file://frontend/src/api/staff.js)
- [request.js](file://frontend/src/api/request.js)
- [department.js](file://frontend/src/api/department.js)
- [api.md](file://docs/api.md)
- [database.md](file://docs/database.md)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件面向医院绩效系统的“员工管理”功能，系统化梳理员工信息的完整生命周期管理：从基本信息录入（姓名、性别、身份证号、联系方式）、职位与职称配置、基本工资与绩效系数设置，到所属科室关联、状态管理（在职、休假、离职、退休），以及部门调动、岗位变更等业务场景。同时覆盖员工档案维护、列表展示、搜索筛选、分页加载、数据同步、权限控制与数据验证规则，并给出批量导入导出、数据校验与异常处理建议。
## 项目结构
后端采用 FastAPI + SQLAlchemy 异步 ORM，前端采用 Vue 3 + Element Plus，通过 Axios 封装的请求模块统一访问后端 API。员工管理涉及以下关键模块：
- 后端 API 路由：负责接收请求、鉴权与返回标准化响应
- 服务层：封装业务逻辑，处理查询、分页、过滤与数据组装
- 数据模型：定义员工表结构、枚举类型与索引约束
- 数据模式：定义请求/响应的数据结构与字段校验
- 安全模块：提供 JWT 认证、权限校验（管理员/经理）
- 前端页面：员工列表、搜索筛选、分页、弹窗表单、增删改操作
- 前端 API 封装：统一请求与响应拦截、错误处理
```mermaid
graph TB
FE["前端页面<br/>Staff.vue"] --> API["后端API<br/>staff.py"]
API --> SVC["服务层<br/>staff_service.py"]
SVC --> DB["数据库模型<br/>models.py"]
API --> SEC["安全模块<br/>security.py"]
FE --> FE_API["前端API封装<br/>staff.js / request.js"]
FE --> DEPT_API["部门API<br/>department.js"]
```
图表来源
- [staff.py](file://backend/app/api/v1/staff.py#L1-L124)
- [staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
- [models.py](file://backend/app/models/models.py#L88-L115)
- [schemas.py](file://backend/app/schemas/schemas.py#L105-L149)
- [security.py](file://backend/app/core/security.py#L85-L110)
- [Staff.vue](file://frontend/src/views/basic/Staff.vue#L1-L313)
- [staff.js](file://frontend/src/api/staff.js#L1-L32)
- [request.js](file://frontend/src/api/request.js#L1-L66)
- [department.js](file://frontend/src/api/department.js#L1-L32)
章节来源
- [staff.py](file://backend/app/api/v1/staff.py#L1-L124)
- [staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
- [models.py](file://backend/app/models/models.py#L88-L115)
- [schemas.py](file://backend/app/schemas/schemas.py#L105-L149)
- [security.py](file://backend/app/core/security.py#L85-L110)
- [Staff.vue](file://frontend/src/views/basic/Staff.vue#L1-L313)
- [staff.js](file://frontend/src/api/staff.js#L1-L32)
- [request.js](file://frontend/src/api/request.js#L1-L66)
- [department.js](file://frontend/src/api/department.js#L1-L32)
## 核心组件
- 员工数据模型：包含工号、姓名、所属科室、职位、职称、联系方式、基本工资、绩效系数、状态、入职日期等字段，并定义了状态枚举与索引
- 员工数据模式：定义创建、更新、响应的数据结构与字段范围校验
- 员工服务层：提供列表查询、详情查询、按工号查询、创建、更新、删除、按科室查询等功能
- 员工 API 路由：提供获取列表、详情、创建、更新、删除、按科室查询接口，并集成权限校验
- 前端页面：员工列表、搜索筛选、分页、弹窗表单、增删改操作
- 前端 API 封装：统一请求头、Token 注入、错误拦截与提示
- 安全模块：JWT 解析、当前用户获取、活跃用户校验、管理员/经理权限校验
章节来源
- [models.py](file://backend/app/models/models.py#L88-L115)
- [schemas.py](file://backend/app/schemas/schemas.py#L105-L149)
- [staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
- [staff.py](file://backend/app/api/v1/staff.py#L17-L124)
- [Staff.vue](file://frontend/src/views/basic/Staff.vue#L1-L313)
- [staff.js](file://frontend/src/api/staff.js#L1-L32)
- [request.js](file://frontend/src/api/request.js#L1-L66)
- [security.py](file://backend/app/core/security.py#L85-L110)
## 架构总览
员工管理的端到端流程如下：
- 前端发起请求（含 Token），经请求拦截器注入 Authorization
- 后端 API 路由解析请求参数，进行权限校验（管理员/经理）
- 服务层执行数据库查询/写入，组装响应数据
- 返回标准化响应（code/message/data/total/page/page_size）
```mermaid
sequenceDiagram
participant FE as "前端页面"
participant API as "后端API"
participant SEC as "安全模块"
participant SVC as "服务层"
participant DB as "数据库模型"
FE->>API : GET /staff?page&page_size&department_id&status&keyword
API->>SEC : 校验当前用户与权限
SEC-->>API : 当前用户/权限通过
API->>SVC : 查询员工列表(含分页/过滤)
SVC->>DB : 执行SQL查询(含count/分页/联表)
DB-->>SVC : 结果集
SVC-->>API : 组装数据(附加科室名称)
API-->>FE : 标准化响应(code,message,data,total,page,page_size)
```
图表来源
- [staff.py](file://backend/app/api/v1/staff.py#L20-L49)
- [staff_service.py](file://backend/app/services/staff_service.py#L16-L49)
- [security.py](file://backend/app/core/security.py#L85-L110)
- [request.js](file://frontend/src/api/request.js#L14-L37)
章节来源
- [staff.py](file://backend/app/api/v1/staff.py#L20-L49)
- [staff_service.py](file://backend/app/services/staff_service.py#L16-L49)
- [security.py](file://backend/app/core/security.py#L85-L110)
- [request.js](file://frontend/src/api/request.js#L14-L37)
## 详细组件分析
### 数据模型与字段设计
- 员工表字段覆盖基本信息、职位职称、联系方式、薪资与绩效、状态与时间戳
- 状态枚举支持在职、休假、离职、退休；索引覆盖科室与状态，便于查询与筛选
- 外键关联科室表，支持联表查询并返回科室名称
```mermaid
erDiagram
STAFF {
int id PK
string employee_id UK
string name
int department_id FK
string position
string title
string phone
string email
numeric base_salary
numeric performance_ratio
enum status
datetime hire_date
datetime created_at
datetime updated_at
}
DEPARTMENTS {
int id PK
string name
string code UK
enum dept_type
int parent_id FK
int level
int sort_order
boolean is_active
text description
datetime created_at
datetime updated_at
}
STAFF }o--|| DEPARTMENTS : "所属科室"
```
图表来源
- [models.py](file://backend/app/models/models.py#L88-L115)
- [models.py](file://backend/app/models/models.py#L62-L86)
章节来源
- [models.py](file://backend/app/models/models.py#L88-L115)
- [models.py](file://backend/app/models/models.py#L62-L86)
### 数据模式与校验
- 员工创建模式：必填字段（工号、姓名、部门、职位），默认状态为在职，基本工资与绩效系数带范围校验
- 员工更新模式：允许部分字段更新，数值字段带范围校验
- 员工响应模式：包含基础字段与部门名称扩展字段
章节来源
- [schemas.py](file://backend/app/schemas/schemas.py#L105-L149)
### 服务层逻辑
- 列表查询：支持按科室、状态、关键词（姓名/工号）过滤，分页与总数统计，联表加载科室名称
- 详情查询：按ID查询并联表加载科室
- 按工号查询：用于唯一性校验
- 创建/更新/删除：封装 CRUD 操作，返回实体或布尔结果
章节来源
- [staff_service.py](file://backend/app/services/staff_service.py#L16-L112)
### API 路由与权限控制
- 获取列表：支持分页、过滤、关键词搜索，返回标准化分页响应
- 获取详情：返回员工详情并附加科室名称
- 创建/更新/删除：仅管理员或经理可操作，创建前进行工号唯一性校验
- 按科室查询：返回指定科室下的在职员工列表
章节来源
- [staff.py](file://backend/app/api/v1/staff.py#L20-L124)
- [security.py](file://backend/app/core/security.py#L85-L110)
### 前端页面与交互
- 列表展示：支持按关键字（姓名/工号）、科室树选择、状态筛选
- 分页加载：支持页码与每页数量切换
- 弹窗表单：支持新增/编辑，必填字段校验，数值范围校验
- 数据同步：调用后端 API 获取数据并刷新表格
章节来源
- [Staff.vue](file://frontend/src/views/basic/Staff.vue#L1-L313)
- [staff.js](file://frontend/src/api/staff.js#L1-L32)
- [department.js](file://frontend/src/api/department.js#L1-L32)
- [request.js](file://frontend/src/api/request.js#L1-L66)
### 数据验证与业务规则
- 员工唯一性：工号唯一，创建时进行重复校验
- 字段范围：基本工资与绩效系数带最小/最大值限制
- 状态枚举：仅允许预定义状态值
- 分页范围：每页数量限制在 1~100
章节来源
- [staff.py](file://backend/app/api/v1/staff.py#L75-L78)
- [schemas.py](file://backend/app/schemas/schemas.py#L116-L117)
- [staff_service.py](file://backend/app/services/staff_service.py#L26-L44)
### 权限控制机制
- 当前用户获取：从 JWT 中解析用户ID并查询用户
- 活跃用户校验：仅允许激活用户访问
- 管理员/经理权限：创建/更新/删除接口要求管理员或经理角色
章节来源
- [security.py](file://backend/app/core/security.py#L55-L110)
### 员工状态管理与业务场景
- 状态枚举：在职、休假、离职、退休
- 列表查询：支持按状态过滤
- 按科室查询：默认仅返回在职员工
- 业务场景建议：
- 部门调动：更新员工所属科室字段
- 岗位变更：更新职位/职称字段
- 状态变更：更新状态字段（如休假/退休）
章节来源
- [models.py](file://backend/app/models/models.py#L37-L43)
- [staff_service.py](file://backend/app/services/staff_service.py#L104-L111)
- [Staff.vue](file://frontend/src/views/basic/Staff.vue#L179-L184)
### 员工档案维护与数据同步
- 前端通过 API 获取员工列表与详情，支持分页与筛选
- 表单提交后刷新列表，确保前后端数据一致
- 错误拦截：统一处理 401/403/404/500 等状态码并提示
章节来源
- [Staff.vue](file://frontend/src/views/basic/Staff.vue#L194-L207)
- [request.js](file://frontend/src/api/request.js#L28-L63)
### 批量导入导出（建议实现）
- 导入：建议提供 Excel 模板，后端解析并批量校验与入库，支持事务回滚与错误行定位
- 导出：按筛选条件导出 Excel，包含工号、姓名、科室、职位、职称、基本工资、绩效系数、状态等字段
- 注意：导入需严格校验字段格式、唯一性与范围约束，避免破坏现有数据
（本节为通用实现建议，不直接对应具体源码）
## 依赖关系分析
- 前端依赖后端 API 提供的标准化响应结构
- 后端 API 依赖安全模块进行权限校验
- 服务层依赖数据模型进行数据库操作
- 前端 API 封装统一处理请求头与错误拦截
```mermaid
graph LR
FE_API["前端API封装"] --> BE_API["后端API"]
BE_API --> SEC["安全模块"]
BE_API --> SVC["服务层"]
SVC --> MODELS["数据模型"]
```
图表来源
- [staff.js](file://frontend/src/api/staff.js#L1-L32)
- [request.js](file://frontend/src/api/request.js#L1-L66)
- [staff.py](file://backend/app/api/v1/staff.py#L1-L124)
- [security.py](file://backend/app/core/security.py#L1-L110)
- [staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
- [models.py](file://backend/app/models/models.py#L1-L438)
章节来源
- [staff.js](file://frontend/src/api/staff.js#L1-L32)
- [request.js](file://frontend/src/api/request.js#L1-L66)
- [staff.py](file://backend/app/api/v1/staff.py#L1-L124)
- [security.py](file://backend/app/core/security.py#L1-L110)
- [staff_service.py](file://backend/app/services/staff_service.py#L1-L112)
- [models.py](file://backend/app/models/models.py#L1-L438)
## 性能考量
- 查询优化：列表查询使用联表加载科室名称，注意在大数据量场景下对过滤字段建立索引
- 分页策略：每页数量上限为 100，避免一次性返回过多数据
- 缓存建议：高频查询（如科室树）可在前端缓存，减少重复请求
- 并发与事务：批量导入建议使用事务，失败回滚保证一致性
（本节为通用性能建议，不直接对应具体源码）
## 故障排查指南
- 登录过期：响应拦截器检测 401 自动跳转登录
- 权限不足：403 提示需要管理员或经理权限
- 资源不存在：404 提示对象不存在
- 服务器错误：500 提示服务器错误
- 前端表单校验：必填字段与数值范围校验失败会阻止提交
- 后端唯一性冲突：创建时若工号重复会返回错误
章节来源
- [request.js](file://frontend/src/api/request.js#L28-L63)
- [staff.py](file://backend/app/api/v1/staff.py#L75-L78)
- [Staff.vue](file://frontend/src/views/basic/Staff.vue#L172-L177)
## 结论
员工管理模块在后端提供了完善的 CRUD、权限控制与数据校验，在前端实现了友好的列表展示、搜索筛选与分页体验。结合现有数据模型与服务层能力，可稳定支撑员工信息的全生命周期管理。建议后续补充批量导入导出能力与更丰富的状态流转场景，以进一步提升系统实用性与可维护性。
## 附录
### API 规范（摘自文档）
- 获取员工列表：支持按科室、状态、关键词过滤，返回分页数据
- 创建员工：必填字段与范围校验，工号唯一
- 更新/删除：管理员/经理权限
- 按科室查询：返回指定科室在职员工
章节来源
- [api.md](file://docs/api.md#L158-L238)
### 数据库表结构（摘自文档）
- 员工表字段与索引：包含工号唯一、基本工资与绩效系数范围、状态枚举、科室外键等
- 科室表字段与索引：支持树形结构与类型枚举
章节来源
- [database.md](file://docs/database.md#L117-L136)
- [database.md](file://docs/database.md#L99-L116)

634
.qoder/repowiki/zh/content/核心功能模块/基础数据管理/基础数据管理.md Normal file
View File

@@ -0,0 +1,634 @@
# 基础数据管理
<cite>
**本文档引用的文件**
- [models.py](file://backend/app/models/models.py)
- [schemas.py](file://backend/app/schemas/schemas.py)
- [departments.py](file://backend/app/api/v1/departments.py)
- [staff.py](file://backend/app/api/v1/staff.py)
- [indicators.py](file://backend/app/api/v1/indicators.py)
- [templates.py](file://backend/app/api/v1/templates.py)
- [department_service.py](file://backend/app/services/department_service.py)
- [staff_service.py](file://backend/app/services/staff_service.py)
- [indicator_service.py](file://backend/app/services/indicator_service.py)
- [template_service.py](file://backend/app/services/template_service.py)
- [Departments.vue](file://frontend/src/views/basic/Departments.vue)
- [Staff.vue](file://frontend/src/views/basic/Staff.vue)
- [Indicators.vue](file://frontend/src/views/basic/Indicators.vue)
- [Templates.vue](file://frontend/src/views/basic/Templates.vue)
- [department.js](file://frontend/src/api/department.js)
- [staff.js](file://frontend/src/api/staff.js)
- [indicator.js](file://frontend/src/api/indicator.js)
- [template.js](file://frontend/src/api/template.js)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 简介
基础数据管理模块是医院绩效系统的核心基础功能模块，负责维护医院运营所需的基础数据。该模块涵盖四个主要功能领域：
- **科室管理**：支持树形结构组织，实现多层级科室管理
- **员工信息管理**：维护员工基本信息、职位、职称和薪资数据
- **考核指标管理**：管理各类绩效考核指标及其属性
- **指标模板管理**：提供标准化的指标模板体系
该模块采用前后端分离架构，后端使用FastAPI + SQLAlchemy，前端使用Vue.js + Element Plus，实现了完整的CRUD操作、数据验证、权限控制和批量处理功能。
## 项目结构
基础数据管理模块遵循典型的三层架构设计：
```mermaid
graph TB
subgraph "前端层"
FE1[Departments.vue<br/>科室管理界面]
FE2[Staff.vue<br/>员工管理界面]
FE3[Indicators.vue<br/>指标管理界面]
FE4[Templates.vue<br/>模板管理界面]
FE5[API层<br/>department.js<br/>staff.js<br/>indicator.js<br/>template.js]
end
subgraph "后端层"
BE1[API路由层<br/>departments.py<br/>staff.py<br/>indicators.py<br/>templates.py]
BE2[服务层<br/>department_service.py<br/>staff_service.py<br/>indicator_service.py<br/>template_service.py]
BE3[数据模型层<br/>models.py]
BE4[数据验证层<br/>schemas.py]
end
subgraph "数据库层"
DB[(SQLite数据库)]
end
FE1 --> FE5
FE2 --> FE5
FE3 --> FE5
FE4 --> FE5
FE5 --> BE1
BE1 --> BE2
BE2 --> BE3
BE3 --> BE4
BE3 --> DB
```
**图表来源**
- [Departments.vue](file://frontend/src/views/basic/Departments.vue#L1-L290)
- [staff.py](file://backend/app/api/v1/staff.py#L1-L124)
- [models.py](file://backend/app/models/models.py#L1-L438)
**章节来源**
- [models.py](file://backend/app/models/models.py#L1-L438)
- [schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
## 核心组件
### 数据模型设计
系统采用SQLAlchemy ORM设计，建立了完整的数据模型层次：
```mermaid
classDiagram
class Department {
+int id
+string name
+string code
+DeptType dept_type
+int parent_id
+int level
+int sort_order
+bool is_active
+DateTime created_at
+DateTime updated_at
+Staff[] staff
+Department parent
+Department[] children
}
class Staff {
+int id
+string employee_id
+string name
+int department_id
+string position
+string title
+string phone
+string email
+float base_salary
+float performance_ratio
+StaffStatus status
+DateTime hire_date
+DateTime created_at
+DateTime updated_at
+Department department
+Assessment[] assessments
+SalaryRecord[] salary_records
}
class Indicator {
+int id
+string name
+string code
+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
+string applicable_dept_types
+bool is_veto
+bool is_active
+DateTime created_at
+DateTime updated_at
+AssessmentDetail[] assessment_details
}
class IndicatorTemplate {
+int id
+string template_name
+string template_code
+TemplateType template_type
+string description
+string dimension_weights
+string assessment_cycle
+bool is_active
+DateTime created_at
+DateTime updated_at
+TemplateIndicator[] indicators
}
class TemplateIndicator {
+int id
+int template_id
+int indicator_id
+string category
+float target_value
+string target_unit
+float weight
+string scoring_method
+string scoring_params
+int sort_order
+string remark
+DateTime created_at
+DateTime updated_at
+IndicatorTemplate template
+Indicator indicator
}
Department "1" <-- "many" Staff : "has"
Department "1" <-- "many" Department : "parent"
IndicatorTemplate "1" <-- "many" TemplateIndicator : "contains"
TemplateIndicator "1" <-- "1" Indicator : "references"
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L62-L438)
### API接口设计
系统提供了RESTful API接口，支持标准的CRUD操作：
| 功能模块 | HTTP方法 | 端点 | 描述 |
|---------|---------|------|------|
| 科室管理 | GET | `/departments` | 获取科室列表 |
| 科室管理 | GET | `/departments/tree` | 获取科室树形结构 |
| 科室管理 | GET | `/departments/{id}` | 获取科室详情 |
| 科室管理 | POST | `/departments` | 创建科室 |
| 科室管理 | PUT | `/departments/{id}` | 更新科室 |
| 科室管理 | DELETE | `/departments/{id}` | 删除科室 |
| 员工管理 | GET | `/staff` | 获取员工列表 |
| 员工管理 | GET | `/staff/{id}` | 获取员工详情 |
| 员工管理 | POST | `/staff` | 创建员工 |
| 员工管理 | PUT | `/staff/{id}` | 更新员工 |
| 员工管理 | DELETE | `/staff/{id}` | 删除员工 |
| 员工管理 | GET | `/staff/department/{id}` | 获取科室员工 |
| 指标管理 | GET | `/indicators` | 获取指标列表 |
| 指标管理 | GET | `/indicators/active` | 获取启用指标 |
| 指标管理 | GET | `/indicators/{id}` | 获取指标详情 |
| 指标管理 | POST | `/indicators` | 创建指标 |
| 指标管理 | PUT | `/indicators/{id}` | 更新指标 |
| 指标管理 | DELETE | `/indicators/{id}` | 删除指标 |
| 模板管理 | GET | `/templates` | 获取模板列表 |
| 模板管理 | GET | `/templates/types` | 获取模板类型 |
| 模板管理 | GET | `/templates/dimensions` | 获取BSC维度 |
| 模板管理 | GET | `/templates/{id}` | 获取模板详情 |
| 模板管理 | POST | `/templates` | 创建模板 |
| 模板管理 | PUT | `/templates/{id}` | 更新模板 |
| 模板管理 | DELETE | `/templates/{id}` | 删除模板 |
**章节来源**
- [departments.py](file://backend/app/api/v1/departments.py#L1-L108)
- [staff.py](file://backend/app/api/v1/staff.py#L1-L124)
- [indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
## 架构概览
系统采用分层架构设计，确保了良好的可维护性和扩展性：
```mermaid
sequenceDiagram
participant Client as "前端客户端"
participant API as "API路由层"
participant Service as "服务层"
participant Model as "数据模型层"
participant DB as "数据库"
Client->>API : HTTP请求
API->>Service : 调用业务逻辑
Service->>Model : 数据映射和验证
Model->>DB : SQL查询/操作
DB-->>Model : 查询结果
Model-->>Service : 处理后的数据
Service-->>API : 业务结果
API-->>Client : JSON响应
Note over Client,DB : 请求处理完整流程
```
**图表来源**
- [department_service.py](file://backend/app/services/department_service.py#L13-L150)
- [staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
### 权限控制机制
系统实现了基于角色的权限控制：
```mermaid
flowchart TD
A[用户访问] --> B{检查权限}
B --> |普通用户| C[仅读取权限]
B --> |管理员| D[完全权限]
B --> |经理| E[部分写权限]
C --> F[只允许GET操作]
D --> G[允许所有操作]
E --> H[允许CRUD操作]
F --> I[返回数据]
G --> I
H --> I
```
**图表来源**
- [departments.py](file://backend/app/api/v1/departments.py#L67-L107)
- [staff.py](file://backend/app/api/v1/staff.py#L68-L108)
- [indicators.py](file://backend/app/api/v1/indicators.py#L71-L111)
- [templates.py](file://backend/app/api/v1/templates.py#L129-L169)
## 详细组件分析
### 科室管理组件
#### 数据模型分析
科室管理采用自引用关系实现树形结构：
```mermaid
erDiagram
DEPARTMENTS {
int id PK
string name
string code UK
enum dept_type
int parent_id FK
int level
int sort_order
bool is_active
text description
datetime created_at
datetime updated_at
}
DEPARTMENTS }o--|| DEPARTMENTS : "parent"
DEPARTMENTS ||--o{ STAFF : "has"
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L62-L85)
#### 树形结构算法
系统实现了高效的树形结构构建算法：
```mermaid
flowchart TD
A[获取所有科室] --> B[构建ID到对象映射]
B --> C[遍历科室列表]
C --> D{检查是否有父节点}
D --> |是| E[将当前节点添加到父节点children]
D --> |否| F[添加到根节点列表]
E --> G[继续下一个科室]
F --> G
G --> H[返回根节点树形结构]
```
**图表来源**
- [department_service.py](file://backend/app/services/department_service.py#L112-L150)
#### 前端界面设计
前端采用Element Plus组件实现：
- **搜索功能**：支持按名称、编码、类型搜索
- **树形选择器**：用于上级科室选择
- **状态切换**：支持启用/禁用切换
- **分页显示**：支持大数据量分页
**章节来源**
- [Departments.vue](file://frontend/src/views/basic/Departments.vue#L1-L290)
- [department.js](file://frontend/src/api/department.js#L1-L32)
### 员工信息管理组件
#### 数据模型设计
员工信息管理涵盖了完整的员工档案：
```mermaid
erDiagram
STAFF {
int id PK
string employee_id UK
string name
int department_id FK
string position
string title
string phone
string email
decimal base_salary
decimal performance_ratio
enum status
datetime hire_date
datetime created_at
datetime updated_at
}
DEPARTMENTS ||--o{ STAFF : "belongs_to"
STAFF ||--o{ ASSESSMENTS : "creates"
STAFF ||--o{ SALARY_RECORDS : "has"
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L88-L114)
#### 数据验证规则
系统实现了严格的数据验证：
- **工号唯一性**：防止重复工号
- **基本工资范围**：0-∞
- **绩效系数范围**：0-5
- **状态枚举**：只能是预定义值
**章节来源**
- [Staff.vue](file://frontend/src/views/basic/Staff.vue#L1-L313)
- [staff.js](file://frontend/src/api/staff.js#L1-L32)
### 考核指标管理组件
#### 指标类型体系
系统支持多种类型的考核指标：
| 指标类型 | 描述 | 权重范围 | 最高分值范围 |
|---------|------|----------|-------------|
| 质量指标 | 医疗质量相关 | 0.1-10 | 0-1000 |
| 数量指标 | 工作量相关 | 0.1-10 | 0-1000 |
| 效率指标 | 工作效率相关 | 0.1-10 | 0-1000 |
| 服务指标 | 服务质量相关 | 0.1-10 | 0-1000 |
| 成本指标 | 成本控制相关 | 0.1-10 | 0-1000 |
#### BSC维度设计
平衡计分卡四个维度：
- **财务维度**：财务管理 (30%-40%)
- **客户维度**：顾客服务 (25%-35%)
- **内部流程维度**：内部流程 (20%-30%)
- **学习与成长维度**：学习与成长 (5%-15%)
**章节来源**
- [Indicators.vue](file://frontend/src/views/basic/Indicators.vue#L1-L296)
- [indicator.js](file://frontend/src/api/indicator.js#L1-L32)
### 指标模板管理组件
#### 模板类型体系
系统提供多种科室类型的标准化模板：
| 模板类型 | 适用科室 | 特点 |
|---------|---------|------|
| 通用模板 | 全院通用 | 基础通用指标 |
| 手术临床科室 | 外科系统 | 手术相关指标 |
| 非手术有病房科室 | 内科系统 | 病房管理指标 |
| 非手术无病房科室 | 门诊科室 | 门诊服务指标 |
| 医技科室 | 检验、放射等 | 医技服务指标 |
| 护理单元 | 护理部门 | 护理质量指标 |
| 行政科室 | 后勤、财务等 | 行政管理指标 |
| 后勤科室 | 总务、采购等 | 后勤保障指标 |
#### 模板指标管理
模板采用多对多关系管理：
```mermaid
erDiagram
INDICATOR_TEMPLATES {
int id PK
string template_name
string template_code UK
enum template_type
string description
string dimension_weights
string assessment_cycle
bool is_active
datetime created_at
datetime updated_at
}
TEMPLATE_INDICATORS {
int id PK
int template_id FK
int indicator_id FK
string category
decimal target_value
string target_unit
decimal weight
string scoring_method
text scoring_params
int sort_order
text remark
datetime created_at
datetime updated_at
}
INDICATORS {
int id PK
string name
string code UK
enum indicator_type
enum bs_dimension
decimal weight
decimal max_score
decimal target_value
string target_unit
text calculation_method
text assessment_method
text deduction_standard
string data_source
string applicable_dept_types
bool is_veto
bool is_active
datetime created_at
datetime updated_at
}
INDICATOR_TEMPLATES ||--o{ TEMPLATE_INDICATORS : "contains"
INDICATORS ||--o{ TEMPLATE_INDICATORS : "references"
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L387-L438)
**章节来源**
- [Templates.vue](file://frontend/src/views/basic/Templates.vue#L1-L638)
- [template.js](file://frontend/src/api/template.js#L1-L62)
## 依赖关系分析
系统采用了清晰的依赖层次结构：
```mermaid
graph TB
subgraph "外部依赖"
D1[FastAPI]
D2[SQLAlchemy]
D3[Element Plus]
D4[Vue.js]
end
subgraph "后端核心"
C1[models.py]
C2[schemas.py]
C3[department_service.py]
C4[staff_service.py]
C5[indicator_service.py]
C6[template_service.py]
end
subgraph "前端核心"
F1[Departments.vue]
F2[Staff.vue]
F3[Indicators.vue]
F4[Templates.vue]
F5[department.js]
F6[staff.js]
F7[indicator.js]
F8[template.js]
end
D1 --> C1
D2 --> C1
D3 --> F1
D4 --> F1
C1 --> C2
C3 --> C1
C4 --> C1
C5 --> C1
C6 --> C1
F5 --> D1
F6 --> D1
F7 --> D1
F8 --> D1
F1 --> F5
F2 --> F6
F3 --> F7
F4 --> F8
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L1-L13)
- [schemas.py](file://backend/app/schemas/schemas.py#L1-L8)
### 数据一致性保证
系统通过多种机制确保数据一致性：
1. **数据库约束**：唯一性约束、外键约束
2. **业务逻辑验证**：服务层数据验证
3. **事务处理**：关键操作的事务保证
4. **级联删除**：模板删除时自动清理关联数据
**章节来源**
- [models.py](file://backend/app/models/models.py#L82-L85)
- [models.py](file://backend/app/models/models.py#L143-L146)
## 性能考虑
### 查询优化策略
1. **索引设计**：为常用查询字段建立索引
2. **分页查询**：默认每页20条记录
3. **批量操作**：支持批量添加模板指标
4. **缓存策略**：模板类型和维度数据缓存
### 前端性能优化
1. **虚拟滚动**：大量数据时使用虚拟滚动
2. **懒加载**：树形组件懒加载
3. **防抖搜索**：搜索框输入防抖
4. **组件复用**：表单组件复用
## 故障排除指南
### 常见问题及解决方案
| 问题类型 | 症状 | 原因 | 解决方案 |
|---------|------|------|---------|
| 数据重复 | 创建失败，提示已存在 | 唯一性约束冲突 | 检查编码或名称唯一性 |
| 权限不足 | 操作被拒绝 | 角色权限限制 | 提升用户角色或联系管理员 |
| 外键约束 | 删除失败 | 存在外键引用 | 先删除子数据再删除父数据 |
| 数据验证 | 提交失败 | 字段格式不正确 | 检查必填字段和格式要求 |
### 错误处理机制
系统实现了完善的错误处理：
```mermaid
flowchart TD
A[请求到达] --> B{数据验证}
B --> |通过| C[业务处理]
B --> |失败| D[返回400错误]
C --> E{业务逻辑}
E --> |成功| F[返回200成功]
E --> |失败| G[返回500错误]
D --> H[错误详情]
F --> I[成功详情]
G --> H
H --> J[日志记录]
I --> J
```
**图表来源**
- [departments.py](file://backend/app/api/v1/departments.py#L74-L77)
- [staff.py](file://backend/app/api/v1/staff.py#L75-L78)
**章节来源**
- [departments.py](file://backend/app/api/v1/departments.py#L1-L108)
- [staff.py](file://backend/app/api/v1/staff.py#L1-L124)
## 结论
基础数据管理模块为医院绩效系统提供了坚实的数据基础。通过合理的架构设计、完善的数据模型和严格的权限控制，系统能够有效支撑医院的绩效管理工作。
### 主要优势
1. **模块化设计**：清晰的功能划分和职责分离
2. **数据完整性**：完善的约束和验证机制
3. **用户体验**：直观的界面和流畅的操作体验
4. **扩展性强**：灵活的模板系统支持定制化需求
5. **性能稳定**：合理的优化策略确保系统稳定性
### 发展建议
1. **增加审计日志**：记录所有数据变更历史
2. **完善权限粒度**：支持更细粒度的权限控制
3. **增强数据导入**：支持Excel批量导入功能
4. **优化移动端**：适配移动设备访问需求
5. **扩展统计分析**：增加更多维度的统计报表
该模块的成功实现为整个医院绩效系统的稳定运行奠定了重要基础，为后续功能扩展提供了良好的技术支撑。

363
.qoder/repowiki/zh/content/核心功能模块/基础数据管理/模板管理.md Normal file
View File

@@ -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)

400
.qoder/repowiki/zh/content/核心功能模块/基础数据管理/科室管理.md Normal file
View File

@@ -0,0 +1,400 @@
# 科室管理
<cite>
**本文引用的文件**
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py)
- [backend/app/models/models.py](file://backend/app/models/models.py)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py)
- [backend/app/main.py](file://backend/app/main.py)
- [frontend/src/api/department.js](file://frontend/src/api/department.js)
- [frontend/src/views/basic/Departments.vue](file://frontend/src/views/basic/Departments.vue)
- [docs/database.md](file://docs/database.md)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本章节面向“医院绩效系统”的“科室管理”功能，系统化阐述后端API、数据库模型、前端组件与服务层之间的协作关系，覆盖以下能力：
- 科室信息的增删改查（CRUD）
- 科室类型分类（手术临床、非手术有病房、非手术无病房、医技、医辅、护理单元、行政、财务、后勤保障）
- 树形层级结构管理（父子关系、层级level、排序sort_order）
- 科室状态控制（启用/禁用）
- 搜索过滤与分页
- 编码唯一性约束与上级科室关联校验
- 前端树形选择器、状态切换开关、搜索过滤与分页展示
## 项目结构
围绕“科室管理”，涉及后端三层（API-Service-Model）与前端单页面组件的协同：
- 后端
- API路由：负责请求参数解析、鉴权与返回格式化
- 服务层：封装业务逻辑（查询、树构建、创建、更新、删除）
- 模型层：定义数据库表结构、索引与关系
- Schema层：定义请求/响应数据结构与字段校验
- 前端
- API适配层：封装HTTP请求
- 视图组件：表格、分页、对话框、树形选择器、状态开关、搜索过滤
```mermaid
graph TB
subgraph "后端"
API["API路由<br/>departments.py"]
SVC["服务层<br/>department_service.py"]
MODEL["模型层<br/>models.py"]
SCHEMA["Schema层<br/>schemas.py"]
end
subgraph "前端"
FE_API["API适配层<br/>frontend/src/api/department.js"]
VIEW["视图组件<br/>frontend/src/views/basic/Departments.vue"]
end
FE_API --> API
VIEW --> FE_API
API --> SVC
SVC --> MODEL
SVC --> SCHEMA
```
图表来源
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L1-L108)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L1-L150)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L85)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L62-L103)
- [frontend/src/api/department.js](file://frontend/src/api/department.js#L1-L32)
- [frontend/src/views/basic/Departments.vue](file://frontend/src/views/basic/Departments.vue#L1-L290)
章节来源
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L1-L108)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L1-L150)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L85)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L62-L103)
- [frontend/src/api/department.js](file://frontend/src/api/department.js#L1-L32)
- [frontend/src/views/basic/Departments.vue](file://frontend/src/views/basic/Departments.vue#L1-L290)
## 核心组件
- 后端API路由
- 提供科室列表、树形结构、详情、创建、更新、删除等接口
- 支持按科室类型与状态过滤，支持分页
- 服务层
- 列表查询：支持类型与状态过滤、分页、排序
- 树形构建：手动构建树，避免懒加载问题
- 创建：自动计算层级level，校验编码唯一
- 更新：动态更新字段
- 删除：检查是否存在子节点，防止误删
- 模型层
- 科室表包含：编码唯一、类型枚举、父ID自关联、层级、排序、状态、描述、时间戳
- 索引：类型、父ID
- Schema层
- 定义创建、更新、响应、树形结构的数据模型
- 前端组件
- 表格：显示编码、名称、类型、层级、状态、创建时间、操作
- 分页：页码与每页数量
- 对话框：新增/编辑，含树形选择器、类型选择、排序输入、描述文本域
- 状态开关：启用/禁用
- 搜索：关键词（名称/编码）与类型筛选
章节来源
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L20-L107)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L17-L149)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L85)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L64-L103)
- [frontend/src/views/basic/Departments.vue](file://frontend/src/views/basic/Departments.vue#L17-L271)
## 架构概览
后端采用FastAPI + SQLAlchemy异步ORM，前端使用Vue3 + Element Plus。数据流从浏览器发起请求，经API路由进入服务层，访问数据库模型并返回标准化响应；前端通过API适配层调用后端接口，并渲染表格、树形选择器与状态开关。
```mermaid
sequenceDiagram
participant Browser as "浏览器"
participant FE as "前端组件<br/>Departments.vue"
participant API as "后端API<br/>departments.py"
participant SVC as "服务层<br/>department_service.py"
participant DB as "数据库模型<br/>models.py"
Browser->>FE : 打开页面/点击查询
FE->>API : GET /departments?keyword&dept_type&page&page_size
API->>SVC : get_list(dept_type, is_active, page, page_size)
SVC->>DB : 查询departments并统计总数
DB-->>SVC : 列表与总数
SVC-->>API : 返回列表与总数
API-->>FE : 标准化响应{code,message,data,total,page,page_size}
Browser->>FE : 点击树形选择器
FE->>API : GET /departments/tree?dept_type
API->>SVC : get_tree(dept_type)
SVC->>DB : 查询departments并构建树
DB-->>SVC : 列表
SVC-->>API : 树形结构
API-->>FE : 树形数据
Browser->>FE : 点击状态开关
FE->>API : PUT /departments/{id} {is_active}
API->>SVC : update(dept_id, {is_active})
SVC->>DB : 更新is_active
DB-->>SVC : 更新后的对象
SVC-->>API : 返回更新结果
API-->>FE : 成功消息
```
图表来源
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L20-L107)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L17-L149)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L85)
- [frontend/src/views/basic/Departments.vue](file://frontend/src/views/basic/Departments.vue#L168-L245)
## 详细组件分析
### 后端API路由（departments.py）
- 接口清单
- GET /departments：列表查询（支持类型、状态、分页）
- GET /departments/tree：树形结构（可选按类型过滤）
- GET /departments/{id}：详情
- POST /departments：创建（需管理员/经理权限，校验编码唯一）
- PUT /departments/{id}：更新（需管理员/经理权限）
- DELETE /departments/{id}：删除（需管理员/经理权限，禁止删除有子节点的科室）
- 权限与安全
- 使用依赖注入获取当前用户与权限校验
- 返回统一响应结构（code/message/data/total/page/page_size）
章节来源
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L20-L107)
### 服务层（department_service.py）
- 列表查询
- 过滤条件：类型、状态
- 排序：先按sort_order，再按id
- 分页：offset/limit
- 树形构建
- 查询所有科室并按sort_order/id排序
- 使用映射表构建树节点，处理父子关系
- 未找到父节点时作为根节点
- 创建
- 若存在parent_id，则计算level = parent.level + 1
- 写入数据库并刷新
- 更新
- 动态更新字段，支持部分字段更新
- 删除
- 检查是否存在子节点，若有则拒绝删除
```mermaid
flowchart TD
Start(["开始"]) --> Load["查询所有科室并排序"]
Load --> BuildMap["构建ID到节点映射"]
BuildMap --> ForEach["遍历每个科室"]
ForEach --> HasParent{"存在parent_id且父节点存在?"}
HasParent --> |是| AppendChild["将当前节点加入父节点children"]
HasParent --> |否| AddRoot["加入根节点列表"]
AppendChild --> Next["下一个科室"]
AddRoot --> Next
Next --> Done{"遍历结束?"}
Done --> |否| ForEach
Done --> |是| Return["返回根节点集合(树)"]
```
图表来源
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L113-L149)
章节来源
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L17-L149)
### 数据模型（models.py）
- 科室表字段
- 编码唯一（code）
- 类型枚举（DeptType）
- 自关联父ID（parent_id）
- 层级（level，默认1）
- 排序（sort_order，默认0）
- 状态（is_active，默认true）
- 时间戳（created_at/updated_at）
- 索引
- 类型索引、父ID索引
- 关系
- 与员工表的反向关系（backref）
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L85)
- [docs/database.md](file://docs/database.md#L99-L116)
### Schema定义（schemas.py）
- 数据模型
- DepartmentBase：基础字段
- DepartmentCreate：创建用
- DepartmentUpdate：更新用（可选字段）
- DepartmentResponse：响应用（含id、状态、时间戳）
- DepartmentTree：树形结构（children数组）
- 字段约束
- 类型枚举、长度限制、数值范围、可空性
章节来源
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L64-L103)
### 前端组件（Departments.vue）
- 功能点
- 搜索栏：关键词（名称/编码）、类型选择、查询/重置、新增按钮
- 表格：编码、名称、类型、层级、状态、创建时间、操作（编辑/删除）
- 分页：页码、每页数量、跳转
- 对话框：新增/编辑，含树形选择器、类型选择、排序、描述
- 状态开关：启用/禁用
- 交互流程
- 加载数据：GET /departments
- 加载树：GET /departments/tree
- 状态切换：PUT /departments/{id} {is_active}
- 新增/编辑：POST/PUT /departments
- 删除：DELETE /departments/{id}
```mermaid
sequenceDiagram
participant U as "用户"
participant V as "Departments.vue"
participant A as "API适配层"
participant S as "后端API"
U->>V : 输入关键词/类型并点击查询
V->>A : getDepartments({keyword,dept_type,page,page_size})
A->>S : GET /departments
S-->>A : 列表+总数
A-->>V : 渲染表格
U->>V : 点击状态开关
V->>A : updateDepartment(id,{is_active})
A->>S : PUT /departments/{id}
S-->>A : 成功
A-->>V : 提示成功
U->>V : 点击新增/编辑
V->>A : create/update
A->>S : POST/PUT /departments
S-->>A : 成功
A-->>V : 刷新列表与树
```
图表来源
- [frontend/src/views/basic/Departments.vue](file://frontend/src/views/basic/Departments.vue#L168-L266)
- [frontend/src/api/department.js](file://frontend/src/api/department.js#L4-L31)
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L20-L107)
章节来源
- [frontend/src/views/basic/Departments.vue](file://frontend/src/views/basic/Departments.vue#L1-L290)
- [frontend/src/api/department.js](file://frontend/src/api/department.js#L1-L32)
## 依赖关系分析
- 组件耦合
- API路由依赖服务层
- 服务层依赖模型层与Schema层
- 前端组件依赖API适配层
- 外部依赖
- FastAPI、SQLAlchemy、Element Plus
- 潜在循环依赖
- 当前结构清晰，无循环导入迹象
```mermaid
graph LR
FE["前端组件"] --> APIA["API适配层"]
APIA --> APIR["API路由"]
APIR --> SVCL["服务层"]
SVCL --> MDL["模型层"]
SVCL --> SCH["Schema层"]
```
图表来源
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L1-L108)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L1-L150)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L85)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L62-L103)
- [frontend/src/api/department.js](file://frontend/src/api/department.js#L1-L32)
- [frontend/src/views/basic/Departments.vue](file://frontend/src/views/basic/Departments.vue#L1-L290)
章节来源
- [backend/app/main.py](file://backend/app/main.py#L15-L51)
## 性能考虑
- 查询优化
- 列表查询按sort_order与id排序，结合分页，避免全表扫描
- 树形构建在内存中完成，减少多次数据库往返
- 索引策略
- 类型与父ID索引有助于过滤与自关联查询
- 前端优化
- 树形选择器使用一次性加载，避免频繁请求
- 分页与搜索联动，减少无效请求
## 故障排查指南
- 常见错误与处理
- 编码重复：创建时校验编码唯一，返回400
- 科室不存在：更新/删除时若找不到对象，返回404
- 存在子节点：删除时若仍有子节点，返回400
- 权限不足：仅管理员/经理可执行创建/更新/删除
- 前端提示
- 成功/失败消息提示
- 删除前二次确认
- 表单校验失败时阻止提交
章节来源
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L74-L77)
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L92-L93)
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L105-L106)
- [frontend/src/views/basic/Departments.vue](file://frontend/src/views/basic/Departments.vue#L227-L244)
## 结论
“科室管理”功能通过清晰的后端三层架构与前端组件化实现，提供了完善的增删改查、树形层级、状态控制与搜索分页能力。服务层对树形构建与层级计算进行了重点处理，确保数据一致性与性能表现。前端通过树形选择器、状态开关与搜索过滤提升了用户体验。建议后续可扩展批量操作与导入导出能力，进一步提升管理效率。
## 附录
### API接口定义（后端）
- 获取科室列表
- 方法：GET
- 路径：/departments
- 查询参数：keyword（名称/编码模糊）、dept_type（类型）、is_active（状态）、page、page_size
- 返回：code/message/data(total/page/page_size)
- 获取科室树
- 方法：GET
- 路径：/departments/tree
- 查询参数：dept_type（类型）
- 返回：code/message/data（树形结构）
- 获取科室详情
- 方法：GET
- 路径：/departments/{id}
- 返回：code/message/data
- 创建科室
- 方法：POST
- 路径：/departments
- 请求体：DepartmentCreate
- 返回：code/message/data
- 更新科室
- 方法：PUT
- 路径：/departments/{id}
- 请求体：DepartmentUpdate
- 返回：code/message/data
- 删除科室
- 方法：DELETE
- 路径：/departments/{id}
- 返回：code/message
章节来源
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L20-L107)
### 数据模型（关键字段）
- 科室表
- 字段：id、name、code（唯一）、dept_type、parent_id、level、sort_order、is_active、description、created_at、updated_at
- 索引：idx_dept_type、idx_dept_parent
- 关系
- 科室与员工：一对多（反向backref）
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L85)
- [docs/database.md](file://docs/database.md#L99-L116)
### 前端组件（关键交互）
- 搜索与分页
- 搜索关键词与类型筛选，分页参数联动
- 树形选择器
- 使用el-tree-select，check-strictly，绑定name/value
- 状态开关
- el-switch绑定is_active，触发PUT更新
- 表单校验
- 必填项校验，提交前验证
章节来源
- [frontend/src/views/basic/Departments.vue](file://frontend/src/views/basic/Departments.vue#L168-L266)

547
.qoder/repowiki/zh/content/核心功能模块/基础数据管理/考核指标管理.md Normal file
View File

@@ -0,0 +1,547 @@
# 考核指标管理
<cite>
**本文档引用的文件**
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py)
- [backend/app/models/models.py](file://backend/app/models/models.py)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py)
- [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/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py)
- [frontend/src/views/basic/Indicators.vue](file://frontend/src/views/basic/Indicators.vue)
- [frontend/src/views/basic/Templates.vue](file://frontend/src/views/basic/Templates.vue)
- [frontend/src/api/indicator.js](file://frontend/src/api/indicator.js)
- [frontend/src/api/template.js](file://frontend/src/api/template.js)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 简介
本文档详细介绍医院绩效系统的考核指标管理功能。该系统实现了完整的指标管理体系，包括指标分类（财务、客户、内部流程、学习成长四个维度）、指标层级结构、指标权重配置和计算公式设置。系统提供了指标模板管理、指标值域范围设定、评分标准制定和数据来源配置等功能。
系统支持指标审核流程、版本控制、批量导入导出和指标关联关系的技术实现，包含指标树形展示、动态计算、实时验证和历史记录追踪等功能。通过前后端分离架构，采用FastAPI作为后端框架，Vue.js作为前端框架，实现了高效、可扩展的绩效考核指标管理解决方案。
## 项目结构
该项目采用前后端分离的架构设计，主要分为以下层次：
```mermaid
graph TB
subgraph "前端层"
FE1[Vue.js 应用]
FE2[Element Plus UI 组件]
FE3[API 请求封装]
end
subgraph "后端层"
BE1[FastAPI 框架]
BE2[SQLAlchemy ORM]
BE3[异步数据库连接]
end
subgraph "数据层"
DB1[SQLite 数据库]
DB2[指标表]
DB3[模板表]
DB4[关联表]
end
FE1 --> FE2
FE2 --> FE3
FE3 --> BE1
BE1 --> BE2
BE2 --> BE3
BE3 --> DB1
DB1 --> DB2
DB1 --> DB3
DB1 --> DB4
```
**图表来源**
- [frontend/src/views/basic/Indicators.vue](file://frontend/src/views/basic/Indicators.vue#L1-L296)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L147)
**章节来源**
- [frontend/src/views/basic/Indicators.vue](file://frontend/src/views/basic/Indicators.vue#L1-L296)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L147)
## 核心组件
### 指标管理核心组件
系统的核心组件围绕指标管理展开，主要包括以下几个方面：
#### 指标数据模型
系统定义了完整的指标数据模型，支持多种指标类型和维度配置：
- **指标类型**：质量指标、数量指标、效率指标、服务指标、成本指标
- **平衡计分卡维度**：财务、客户、内部流程、学习成长
- **权重配置**：支持0.1-10的权重范围
- **评分配置**：最高分值、目标值、计量单位
#### 模板管理组件
系统提供了灵活的模板管理功能：
- **模板类型**：通用模板、手术临床科室、非手术有病房科室、非手术无病房科室、医技科室、护理单元、行政科室、后勤科室
- **维度权重**：支持BSC四个维度的权重配置
- **评分方法**：区间法、目标参照法、扣分法、加分法、一票否决
**章节来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L54-L61)
- [backend/app/models/models.py](file://backend/app/models/models.py#L29-L35)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L152-L192)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L698-L743)
## 架构概览
系统采用分层架构设计，确保了良好的可维护性和扩展性：
```mermaid
graph TB
subgraph "表现层"
UI1[指标管理界面]
UI2[模板管理界面]
UI3[统计报表界面]
end
subgraph "业务逻辑层"
BL1[指标服务层]
BL2[模板服务层]
BL3[统计服务层]
end
subgraph "数据访问层"
DAL1[指标数据访问]
DAL2[模板数据访问]
DAL3[统计数据访问]
end
subgraph "数据存储层"
DS1[SQLite 数据库]
DS2[指标表]
DS3[模板表]
DS4[关联表]
end
UI1 --> BL1
UI2 --> BL2
UI3 --> BL3
BL1 --> DAL1
BL2 --> DAL2
BL3 --> DAL3
DAL1 --> DS1
DAL2 --> DS1
DAL3 --> DS1
DS1 --> DS2
DS1 --> DS3
DS1 --> DS4
```
**图表来源**
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L13-L197)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L20-L293)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L17-L142)
系统架构的关键特点：
1. **分层清晰**：表现层、业务逻辑层、数据访问层职责明确
2. **异步处理**：使用async/await模式提高并发性能
3. **ORM映射**：通过SQLAlchemy实现对象关系映射
4. **API设计**：遵循RESTful API规范，提供标准化接口
**章节来源**
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L1-L272)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L1-L197)
## 详细组件分析
### 指标管理组件
#### 指标数据模型设计
```mermaid
classDiagram
class Indicator {
+int id
+string name
+string code
+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
+string applicable_dept_types
+bool is_veto
+bool is_active
+datetime created_at
+datetime updated_at
}
class IndicatorType {
<<enumeration>>
QUALITY
QUANTITY
EFFICIENCY
SERVICE
COST
}
class BSCDimension {
<<enumeration>>
FINANCIAL
CUSTOMER
INTERNAL_PROCESS
LEARNING_GROWTH
}
class AssessmentDetail {
+int id
+int assessment_id
+int indicator_id
+float actual_value
+float score
+string evidence
+string remark
+datetime created_at
+datetime updated_at
}
Indicator --> AssessmentDetail : "被评估"
AssessmentDetail --> Indicator : "关联"
```
**图表来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L147)
- [backend/app/models/models.py](file://backend/app/models/models.py#L181-L203)
#### 指标服务层实现
指标服务层提供了完整的CRUD操作和业务逻辑处理：
```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "指标API"
participant Service as "指标服务"
participant DB as "数据库"
Client->>API : GET /indicators
API->>Service : get_list()
Service->>DB : 查询指标列表
DB-->>Service : 返回指标数据
Service-->>API : 返回指标列表
API-->>Client : 返回JSON响应
Client->>API : POST /indicators
API->>Service : create()
Service->>DB : 插入新指标
DB-->>Service : 返回新ID
Service-->>API : 返回创建结果
API-->>Client : 返回创建成功
```
**图表来源**
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L20-L41)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L16-L46)
#### 前端界面实现
前端使用Vue.js和Element Plus构建了直观的用户界面：
```mermaid
flowchart TD
Start([用户访问指标管理页面]) --> LoadData[加载指标数据]
LoadData --> DisplayTable[显示指标表格]
DisplayTable --> SearchFilter[搜索和筛选]
SearchFilter --> AddIndicator[新增指标]
SearchFilter --> EditIndicator[编辑指标]
SearchFilter --> DeleteIndicator[删除指标]
SearchFilter --> StatusToggle[启用/禁用切换]
AddIndicator --> FormValidation[表单验证]
EditIndicator --> FormValidation
FormValidation --> SubmitData[提交数据到后端]
SubmitData --> UpdateTable[更新表格显示]
UpdateTable --> DisplayTable
StatusToggle --> UpdateStatus[更新状态]
UpdateStatus --> RefreshData[刷新数据]
RefreshData --> DisplayTable
```
**图表来源**
- [frontend/src/views/basic/Indicators.vue](file://frontend/src/views/basic/Indicators.vue#L179-L277)
- [frontend/src/api/indicator.js](file://frontend/src/api/indicator.js#L1-L32)
**章节来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L147)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L16-L104)
- [frontend/src/views/basic/Indicators.vue](file://frontend/src/views/basic/Indicators.vue#L1-L296)
### 模板管理组件
#### 模板数据模型设计
```mermaid
classDiagram
class IndicatorTemplate {
+int id
+string template_name
+string template_code
+TemplateType template_type
+string description
+string dimension_weights
+string assessment_cycle
+bool is_active
+datetime created_at
+datetime updated_at
}
class TemplateIndicator {
+int id
+int template_id
+int indicator_id
+string category
+float target_value
+string target_unit
+float weight
+string scoring_method
+string scoring_params
+int sort_order
+string remark
+datetime created_at
+datetime updated_at
}
class TemplateType {
<<enumeration>>
GENERAL
SURGICAL
NON_SURGICAL_WARD
NON_SURGICAL_NOWARD
MEDICAL_TECH
NURSING
ADMIN
LOGISTICS
}
IndicatorTemplate --> TemplateIndicator : "包含多个"
TemplateIndicator --> Indicator : "关联指标"
```
**图表来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L387-L404)
- [backend/app/models/models.py](file://backend/app/models/models.py#L411-L432)
#### 模板服务层实现
模板服务层提供了完整的模板生命周期管理：
```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "模板API"
participant Service as "模板服务"
participant DB as "数据库"
Client->>API : GET /templates
API->>Service : get_list()
Service->>DB : 查询模板列表
DB-->>Service : 返回模板数据
Service-->>API : 返回模板列表
API-->>Client : 返回JSON响应
Client->>API : POST /templates/{template_id}/indicators
API->>Service : add_indicator()
Service->>DB : 检查模板存在性
Service->>DB : 检查指标重复
Service->>DB : 插入模板指标关联
DB-->>Service : 返回新ID
Service-->>API : 返回添加结果
API-->>Client : 返回添加成功
```
**图表来源**
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L22-L42)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L160-L207)
#### 模板前端界面实现
前端模板管理界面提供了完整的模板编辑功能：
```mermaid
flowchart TD
Start([用户访问模板管理页面]) --> LoadTemplates[加载模板列表]
LoadTemplates --> SelectTemplate[选择模板]
SelectTemplate --> LoadTemplateDetails[加载模板详情]
LoadTemplateDetails --> DisplayTemplateInfo[显示模板信息]
DisplayTemplateInfo --> ManageIndicators[管理模板指标]
ManageIndicators --> AddIndicator[添加指标]
ManageIndicators --> EditIndicator[编辑指标]
ManageIndicators --> RemoveIndicator[移除指标]
AddIndicator --> IndicatorForm[指标表单]
EditIndicator --> IndicatorForm
IndicatorForm --> ValidateForm[验证表单]
ValidateForm --> SubmitToAPI[提交到API]
SubmitToAPI --> UpdateTemplate[更新模板显示]
UpdateTemplate --> ManageIndicators
RemoveIndicator --> ConfirmDelete[确认删除]
ConfirmDelete --> DeleteFromAPI[从API删除]
DeleteFromAPI --> UpdateTemplate
UpdateTemplate --> ManageIndicators
```
**图表来源**
- [frontend/src/views/basic/Templates.vue](file://frontend/src/views/basic/Templates.vue#L356-L572)
- [frontend/src/api/template.js](file://frontend/src/api/template.js#L1-L62)
**章节来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L387-L432)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L23-L293)
- [frontend/src/views/basic/Templates.vue](file://frontend/src/views/basic/Templates.vue#L1-L638)
### 数据库迁移和初始化
系统通过Alembic进行数据库版本管理，支持指标模板表的创建和字段扩展：
```mermaid
flowchart TD
Init([系统初始化]) --> CreateTables[创建基础表]
CreateTables --> AddTemplateTable[创建指标模板表]
AddTemplateTable --> AddColumns[添加新列]
AddColumns --> CheckColumn[检查列是否存在]
CheckColumn --> |存在| Skip[跳过]
CheckColumn --> |不存在| AddColumn[添加列]
AddColumn --> CheckColumn
Skip --> CheckColumn
CheckColumn --> Done([初始化完成])
```
**图表来源**
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L21-L92)
**章节来源**
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L1-L96)
## 依赖关系分析
系统各组件之间的依赖关系如下：
```mermaid
graph TB
subgraph "前端依赖"
FE_API[API封装层]
FE_INDICATORS[指标视图]
FE_TEMPLATES[模板视图]
end
subgraph "后端依赖"
API_INDICATORS[指标API]
API_TEMPLATES[模板API]
SERVICE_INDICATORS[指标服务]
SERVICE_TEMPLATES[模板服务]
MODELS[数据模型]
SCHEMAS[数据模式]
end
subgraph "数据库依赖"
DB_INDICATORS[指标表]
DB_TEMPLATES[模板表]
DB_TEMPLATE_INDICATORS[模板指标关联表]
end
FE_API --> API_INDICATORS
FE_API --> API_TEMPLATES
FE_INDICATORS --> FE_API
FE_TEMPLATES --> FE_API
API_INDICATORS --> SERVICE_INDICATORS
API_TEMPLATES --> SERVICE_TEMPLATES
SERVICE_INDICATORS --> MODELS
SERVICE_TEMPLATES --> MODELS
SERVICE_INDICATORS --> SCHEMAS
SERVICE_TEMPLATES --> SCHEMAS
MODELS --> DB_INDICATORS
MODELS --> DB_TEMPLATES
MODELS --> DB_TEMPLATE_INDICATORS
```
**图表来源**
- [frontend/src/api/indicator.js](file://frontend/src/api/indicator.js#L1-L32)
- [frontend/src/api/template.js](file://frontend/src/api/template.js#L1-L62)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L1-L272)
**章节来源**
- [frontend/src/api/indicator.js](file://frontend/src/api/indicator.js#L1-L32)
- [frontend/src/api/template.js](file://frontend/src/api/template.js#L1-L62)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
## 性能考虑
系统在设计时充分考虑了性能优化：
### 数据库性能优化
- **索引策略**：为常用查询字段建立索引，包括指标类型、模板类型、状态等
- **查询优化**：使用分页查询避免大量数据传输
- **连接池**：使用异步数据库连接池提高并发性能
### 前端性能优化
- **懒加载**：按需加载组件和数据
- **缓存机制**：合理使用浏览器缓存
- **虚拟滚动**：大数据量表格使用虚拟滚动技术
### 异步处理
- **异步API调用**：避免阻塞UI线程
- **并发请求**：合理组织并发请求提高响应速度
## 故障排除指南
### 常见问题及解决方案
#### API请求失败
**问题现象**：前端无法获取指标数据
**可能原因**：
- 后端服务未启动
- 网络连接问题
- 认证失败
**解决步骤**：
1. 检查后端服务状态
2. 验证API端点可用性
3. 确认认证信息正确
#### 数据库连接问题
**问题现象**：系统启动时报数据库连接错误
**可能原因**：
- 数据库文件损坏
- 权限不足
- 连接字符串错误
**解决步骤**：
1. 检查数据库文件完整性
2. 验证文件权限设置
3. 确认数据库配置正确
#### 前端界面异常
**问题现象**：指标管理界面显示异常
**可能原因**：
- JavaScript错误
- CSS样式冲突
- 组件状态异常
**解决步骤**：
1. 检查浏览器控制台错误
2. 清除浏览器缓存
3. 验证组件依赖关系
**章节来源**
- [frontend/src/views/basic/Indicators.vue](file://frontend/src/views/basic/Indicators.vue#L235-L253)
- [frontend/src/views/basic/Templates.vue](file://frontend/src/views/basic/Templates.vue#L441-L462)
## 结论
医院绩效系统的考核指标管理功能实现了完整的指标管理体系，具有以下特点：
1. **功能完整**：涵盖了指标创建、编辑、删除、查询等完整生命周期管理
2. **架构清晰**：采用分层架构设计，职责明确，易于维护和扩展
3. **用户体验良好**：提供直观的图形界面和丰富的交互功能
4. **技术先进**：采用现代Web技术栈，支持异步处理和高性能响应
5. **数据安全**：完善的权限控制和数据验证机制
系统通过指标模板管理、BSC维度配置、权重设置等功能，为医院绩效考核提供了强大的技术支持。未来可以进一步扩展功能，如增加指标计算引擎、报表分析工具等，以满足更复杂的绩效管理需求。