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

577
.qoder/repowiki/zh/content/API接口文档/基础数据接口/员工管理接口.md Normal file
View File

@@ -0,0 +1,577 @@
# 员工管理接口
<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)
- [database.py](file://backend/app/core/database.py)
- [staff.js](file://frontend/src/api/staff.js)
- [Staff.vue](file://frontend/src/views/basic/Staff.vue)
- [request.js](file://frontend/src/api/request.js)
- [api.md](file://docs/api.md)
- [backend.md](file://docs/backend.md)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [数据模型](#数据模型)
7. [API接口规范](#api接口规范)
8. [权限控制机制](#权限控制机制)
9. [员工状态管理](#员工状态管理)
10. [导入导出功能](#导入导出功能)
11. [性能考虑](#性能考虑)
12. [故障排除指南](#故障排除指南)
13. [结论](#结论)
## 简介
员工管理接口是医院绩效考核管理系统的核心功能模块，负责员工信息的完整生命周期管理。该系统采用现代化的前后端分离架构，后端基于FastAPI和SQLAlchemy，前端使用Vue.js和Element Plus，实现了完整的员工信息管理功能。
系统支持员工信息的增删改查、多条件筛选、分页查询、状态管理等功能，并集成了完善的权限控制机制和数据验证体系。
## 项目结构
```mermaid
graph TB
subgraph "后端架构"
A[API路由层] --> B[服务层]
B --> C[数据模型层]
C --> D[数据库]
A --> E[安全认证]
E --> F[JWT令牌]
G[前端界面] --> H[API接口]
H --> A
end
subgraph "核心模块"
I[员工管理] --> J[科室关联]
K[权限控制] --> L[角色管理]
M[数据验证] --> N[Pydantic模式]
end
```
**图表来源**
- [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)
**章节来源**
- [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)
## 核心组件
### 后端核心组件
系统采用经典的三层架构模式，包含以下核心组件：
1. **API路由层**：处理HTTP请求和响应，实现RESTful接口
2. **服务层**：封装业务逻辑，提供数据访问服务
3. **数据模型层**：定义数据库表结构和关系映射
4. **安全认证层**：实现JWT令牌认证和权限控制
### 前端核心组件
前端采用Vue.js单页面应用架构：
1. **员工管理界面**：提供员工信息的CRUD操作界面
2. **数据表格组件**：展示员工列表和操作功能
3. **表单组件**：处理员工信息的输入和验证
4. **API客户端**：封装HTTP请求和响应处理
**章节来源**
- [staff.py](file://backend/app/api/v1/staff.py#L17-L124)
- [staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
- [Staff.vue](file://frontend/src/views/basic/Staff.vue#L1-L313)
## 架构概览
```mermaid
sequenceDiagram
participant Client as 客户端
participant Frontend as 前端界面
participant API as API路由
participant Service as 服务层
participant Model as 数据模型
participant DB as 数据库
Client->>Frontend : 用户操作
Frontend->>API : HTTP请求
API->>Service : 业务逻辑调用
Service->>Model : 数据查询/更新
Model->>DB : SQL操作
DB-->>Model : 查询结果
Model-->>Service : 数据对象
Service-->>API : 处理结果
API-->>Frontend : JSON响应
Frontend-->>Client : 界面更新
```
**图表来源**
- [staff.py](file://backend/app/api/v1/staff.py#L20-L108)
- [staff_service.py](file://backend/app/services/staff_service.py#L16-L101)
## 详细组件分析
### 员工管理API路由
员工管理API路由实现了完整的RESTful接口，包含以下主要功能：
#### GET /staff - 获取员工列表
支持多条件筛选和分页查询：
- `department_id`：按科室ID筛选
- `status`：按员工状态筛选
- `keyword`：按姓名或工号模糊搜索
- `page`：页码，默认1
- `page_size`：每页数量，默认20，最大100
#### GET /staff/{id} - 获取员工详情
根据员工ID获取详细信息，包含科室名称关联。
#### POST /staff - 创建员工
需要管理员或经理权限，支持批量创建。
#### PUT /staff/{id} - 更新员工
需要管理员或经理权限，支持部分字段更新。
#### DELETE /staff/{id} - 删除员工
需要管理员或经理权限。
#### GET /staff/department/{department_id} - 获取科室员工
获取指定科室的所有在职员工。
**章节来源**
- [staff.py](file://backend/app/api/v1/staff.py#L20-L124)
### 服务层实现
服务层提供了员工数据访问和业务逻辑处理：
#### 核心方法
1. **get_list()**：实现多条件查询和分页
2. **get_by_id()**：按ID获取员工信息
3. **get_by_employee_id()**：按工号查询唯一员工
4. **create()**：创建新员工记录
5. **update()**：更新员工信息
6. **delete()**：删除员工记录
7. **get_by_department()**：获取科室员工列表
#### 查询优化
- 使用`selectinload`预加载关联的科室信息
- 实现条件动态构建，支持多种筛选组合
- 使用子查询统计总数，提高分页查询性能
**章节来源**
- [staff_service.py](file://backend/app/services/staff_service.py#L16-L112)
### 数据模型设计
员工数据模型采用SQLAlchemy ORM映射：
```mermaid
classDiagram
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
+assessments List[Assessment]
+salary_records List[SalaryRecord]
}
class Department {
+int id
+string name
+string code
+DeptType dept_type
+int parent_id
+int level
+int sort_order
+bool is_active
+string description
+datetime created_at
+datetime updated_at
+parent Department
+staff List[Staff]
}
Staff --> Department : "属于"
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L88-L115)
- [models.py](file://backend/app/models/models.py#L62-L81)
**章节来源**
- [models.py](file://backend/app/models/models.py#L88-L115)
## 数据模型
### 员工信息字段
| 字段名 | 类型 | 必填 | 描述 | 默认值 |
|--------|------|------|------|--------|
| id | int | 否 | 员工ID | 自增 |
| employee_id | string | 是 | 工号 | 唯一约束 |
| name | string | 是 | 姓名 | - |
| department_id | int | 是 | 所属科室ID | - |
| position | string | 是 | 职位 | - |
| title | string | 否 | 职称 | - |
| phone | string | 否 | 联系电话 | - |
| email | string | 否 | 邮箱 | - |
| base_salary | float | 是 | 基本工资 | 0 |
| performance_ratio | float | 是 | 绩效系数 | 1.0 |
| status | enum | 是 | 员工状态 | active |
| hire_date | datetime | 否 | 入职日期 | - |
| created_at | datetime | 否 | 创建时间 | 当前时间 |
| updated_at | datetime | 否 | 更新时间 | 当前时间 |
### 员工状态枚举
```mermaid
stateDiagram-v2
[*] --> ACTIVE
ACTIVE --> LEAVE : 休假
LEAVE --> ACTIVE : 返回
ACTIVE --> RESIGNED : 离职
ACTIVE --> RETIRED : 退休
RESIGNED --> [*]
RETIRED --> [*]
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L37-L43)
**章节来源**
- [models.py](file://backend/app/models/models.py#L88-L115)
- [schemas.py](file://backend/app/schemas/schemas.py#L24-L29)
## API接口规范
### 通用响应格式
所有API接口遵循统一的响应格式：
```json
{
"code": 200,
"message": "success",
"data": {},
"total": 0,
"page": 1,
"page_size": 20
}
```
### 员工管理接口详情
#### 获取员工列表
**请求**
```
GET /api/v1/staff
Authorization: Bearer {token}
```
**查询参数**
| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| department_id | int | 否 | 科室ID |
| status | string | 否 | 员工状态 |
| keyword | string | 否 | 搜索关键词 |
| page | int | 否 | 页码，默认1 |
| page_size | int | 否 | 每页数量，默认20 |
**响应示例**
```json
{
"code": 200,
"message": "success",
"data": [
{
"id": 1,
"employee_id": "EMP001",
"name": "张三",
"department_id": 1,
"department_name": "内科",
"position": "医师",
"title": "主治医师",
"phone": "13800138000",
"email": "zhangsan@example.com",
"base_salary": 5000.00,
"performance_ratio": 1.2,
"status": "active",
"hire_date": "2020-01-01T00:00:00",
"created_at": "2024-01-01T00:00:00",
"updated_at": "2024-01-01T00:00:00"
}
],
"total": 50,
"page": 1,
"page_size": 20
}
```
#### 创建员工
**请求**
```
POST /api/v1/staff
Authorization: Bearer {token}
Content-Type: application/json
```
**请求体**
```json
{
"employee_id": "EMP001",
"name": "张三",
"department_id": 1,
"position": "医师",
"title": "主治医师",
"phone": "13800138000",
"email": "zhangsan@example.com",
"base_salary": 5000.00,
"performance_ratio": 1.2,
"status": "active",
"hire_date": "2020-01-01T00:00:00"
}
```
#### 更新员工
**请求**
```
PUT /api/v1/staff/{id}
Authorization: Bearer {token}
Content-Type: application/json
```
**请求体**（可选字段）
```json
{
"name": "李四",
"department_id": 2,
"position": "副主任医师",
"title": "副主任医师",
"phone": "13900139000",
"email": "lisi@example.com",
"base_salary": 6000.00,
"performance_ratio": 1.3,
"status": "active"
}
```
#### 删除员工
**请求**
```
DELETE /api/v1/staff/{id}
Authorization: Bearer {token}
```
**章节来源**
- [api.md](file://docs/api.md#L158-L236)
- [staff.py](file://backend/app/api/v1/staff.py#L20-L124)
## 权限控制机制
### 角色权限体系
系统采用基于角色的访问控制（RBAC）机制：
```mermaid
graph LR
subgraph "用户角色"
A[普通员工] --> B[科室经理]
B --> C[系统管理员]
end
subgraph "权限级别"
D[只读权限] --> E[读写权限]
E --> F[管理权限]
end
A --> D
B --> E
C --> F
```
### 权限验证流程
```mermaid
flowchart TD
Start([请求到达]) --> CheckAuth["验证JWT令牌"]
CheckAuth --> TokenValid{"令牌有效?"}
TokenValid --> |否| Error401["返回401未授权"]
TokenValid --> |是| GetUser["获取用户信息"]
GetUser --> CheckActive{"用户激活?"}
CheckActive --> |否| Error400["返回400用户禁用"]
CheckActive --> |是| CheckRole["检查角色权限"]
CheckRole --> RoleValid{"权限足够?"}
RoleValid --> |否| Error403["返回403权限不足"]
RoleValid --> |是| ProcessReq["处理业务请求"]
ProcessReq --> Success["返回成功响应"]
Error401 --> End([结束])
Error400 --> End
Error403 --> End
Success --> End
```
**图表来源**
- [security.py](file://backend/app/core/security.py#L55-L110)
### 权限控制实现
1. **get_current_active_user()**：验证用户是否激活
2. **get_current_manager_user()**：验证是否为管理员或经理
3. **get_current_admin_user()**：验证是否为管理员
这些装饰器确保只有具备相应权限的用户才能执行敏感操作。
**章节来源**
- [security.py](file://backend/app/core/security.py#L85-L110)
- [staff.py](file://backend/app/api/v1/staff.py#L68-L108)
## 员工状态管理
### 状态流转图
```mermaid
stateDiagram-v2
[*] --> ACTIVE : 创建时默认
ACTIVE --> LEAVE : 主动申请
LEAVE --> ACTIVE : 返回工作
ACTIVE --> RESIGNED : 辞职
ACTIVE --> RETIRED : 退休
RESIGNED --> [*] : 离职结束
RETIRED --> [*] : 退休结束
LEAVE --> [*] : 休假结束
```
### 状态管理策略
1. **在职状态**：正常工作状态，参与绩效考核
2. **休假状态**：临时离岗，不影响数据完整性
3. **离职状态**：正式离开，不再参与考核
4. **退休状态**：达到退休年龄，不再参与考核
### 状态查询优化
系统在查询员工列表时，会自动过滤掉离职和退休状态的员工，确保统计数据的准确性。
**章节来源**
- [models.py](file://backend/app/models/models.py#L37-L43)
- [staff_service.py](file://backend/app/services/staff_service.py#L103-L112)
## 导入导出功能
### 导入功能
系统支持批量员工信息导入，建议采用以下最佳实践：
1. **数据准备**：确保Excel文件包含所有必填字段
2. **格式要求**：使用标准的CSV或Excel格式
3. **数据验证**：导入前进行数据完整性检查
4. **批量处理**：支持大量数据的分批导入
5. **错误处理**：对无效数据进行标记和报告
### 导出功能
系统支持员工信息的批量导出：
1. **筛选导出**：根据当前筛选条件导出结果
2. **全量导出**：支持导出所有员工信息
3. **格式选择**：支持Excel、CSV等多种格式
4. **字段定制**：可选择导出的字段范围
### 性能优化
- **分页处理**：大数据量时采用分页导出
- **并发处理**：支持多线程并发处理
- **进度反馈**：提供导入导出进度显示
## 性能考虑
### 数据库优化
1. **索引策略**：
- `idx_staff_dept`：按科室ID查询优化
- `idx_staff_status`：按状态查询优化
- `idx_dept_type`：按科室类型查询优化
2. **查询优化**：
- 使用`selectinload`预加载关联数据
- 实现条件动态构建，避免不必要的查询
- 使用子查询统计总数，减少查询次数
### 缓存策略
1. **会话缓存**：缓存活跃用户的权限信息
2. **数据缓存**：缓存常用的科室信息
3. **查询缓存**：缓存频繁访问的统计数据
### 异步处理
系统采用异步数据库连接，支持高并发场景下的性能表现。
## 故障排除指南
### 常见问题
1. **401 未授权**
- 检查JWT令牌是否正确传递
- 验证令牌是否过期
- 确认用户账户状态正常
2. **403 权限不足**
- 验证用户角色是否具备相应权限
- 检查操作是否需要管理员权限
- 确认用户是否被禁用
3. **404 资源不存在**
- 验证员工ID是否正确
- 检查数据库中是否存在该记录
- 确认查询条件是否准确
4. **400 参数错误**
- 检查请求参数格式
- 验证字段长度和范围
- 确认必填字段是否完整
### 调试建议
1. **前端调试**：使用浏览器开发者工具查看网络请求
2. **后端日志**：检查服务器日志获取详细错误信息
3. **数据库查询**：直接查询数据库验证数据状态
4. **API测试**：使用Postman或curl测试接口
**章节来源**
- [request.js](file://frontend/src/api/request.js#L28-L63)
## 结论
员工管理接口模块实现了完整的员工信息生命周期管理，具有以下特点：
1. **功能完整**：支持员工信息的增删改查、状态管理、权限控制
2. **性能优秀**：采用异步架构和数据库优化策略
3. **安全可靠**：完善的JWT认证和权限控制机制
4. **易于扩展**：清晰的架构设计便于功能扩展
5. **用户体验良好**：前后端分离，界面友好
该系统为医院的绩效考核管理提供了坚实的基础，能够满足现代医院对员工管理的各种需求。

463
.qoder/repowiki/zh/content/API接口文档/基础数据接口/基础数据接口.md Normal file
View File

@@ -0,0 +1,463 @@
# 基础数据接口
<cite>
**本文档引用的文件**
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py)
- [backend/app/models/models.py](file://backend/app/models/models.py)
- [backend/app/main.py](file://backend/app/main.py)
- [frontend/src/api/department.js](file://frontend/src/api/department.js)
- [frontend/src/api/staff.js](file://frontend/src/api/staff.js)
- [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. [结论](#结论)
## 简介
本文件为医院绩效管理系统的"基础数据管理接口"提供全面的API文档，覆盖以下四大模块：
- 科室管理：支持科室的增删改查、树形结构查询、层级计算与父子关系维护
- 员工管理：支持员工的增删改查、按科室筛选、状态管理与关联查询
- 考核指标管理：支持指标的增删改查、启用状态管理、模板导入与批量操作
- 指标模板管理：支持模板的增删改查、模板类型与BSC维度枚举、模板指标的增删改查与批量添加
文档详细说明每个模块的接口规范、数据验证规则、关联关系处理、级联操作、分页查询、搜索过滤、排序功能、数据导入导出与批量操作的使用方法。
## 项目结构
后端采用FastAPI + SQLAlchemy 2.0 + 异步数据库访问，遵循分层架构：
- API层：定义路由与请求/响应处理
- 服务层：封装业务逻辑与数据访问
- 模型层：定义数据库表结构与关系
- 模式层：定义Pydantic数据模式与枚举类型
- 前端层：通过统一请求封装调用后端接口
```mermaid
graph TB
subgraph "前端"
FE_API["前端API封装<br/>department.js / staff.js / indicator.js / template.js"]
end
subgraph "后端"
MAIN["FastAPI应用<br/>app/main.py"]
API_DEPT["科室API<br/>api/v1/departments.py"]
API_STAFF["员工API<br/>api/v1/staff.py"]
API_INDICATOR["指标API<br/>api/v1/indicators.py"]
API_TEMPLATE["模板API<br/>api/v1/templates.py"]
SVC_DEPT["科室服务<br/>services/department_service.py"]
SVC_STAFF["员工服务<br/>services/staff_service.py"]
SVC_INDICATOR["指标服务<br/>services/indicator_service.py"]
SVC_TEMPLATE["模板服务<br/>services/template_service.py"]
MODELS["数据模型<br/>models/models.py"]
SCHEMAS["数据模式<br/>schemas/schemas.py"]
end
FE_API --> MAIN
MAIN --> API_DEPT
MAIN --> API_STAFF
MAIN --> API_INDICATOR
MAIN --> API_TEMPLATE
API_DEPT --> SVC_DEPT
API_STAFF --> SVC_STAFF
API_INDICATOR --> SVC_INDICATOR
API_TEMPLATE --> SVC_TEMPLATE
SVC_DEPT --> MODELS
SVC_STAFF --> MODELS
SVC_INDICATOR --> MODELS
SVC_TEMPLATE --> MODELS
API_DEPT --> SCHEMAS
API_STAFF --> SCHEMAS
API_INDICATOR --> SCHEMAS
API_TEMPLATE --> SCHEMAS
```
**图表来源**
- [backend/app/main.py](file://backend/app/main.py#L15-L77)
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L17-L108)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L17-L124)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L17-L142)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L19-L272)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L13-L150)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
- [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/models/models.py](file://backend/app/models/models.py#L62-L200)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L10-L743)
**章节来源**
- [backend/app/main.py](file://backend/app/main.py#L15-L77)
## 核心组件
- 数据模型与枚举
- 科室类型：包含临床、医技、护理、行政、后勤等类型
- 员工状态：在职、休假、离职、退休
- 指标类型：质量、数量、效率、服务、成本
- 平衡计分卡维度：财务、客户、内部流程、学习与成长
- 考核状态：草稿、已提交、已审核、已确认、已驳回
- 数据模式
- 基础模式：定义字段约束、长度限制、取值范围
- 创建/更新模式：用于请求体校验
- 响应模式：用于序列化输出，包含额外字段如部门名称、指标名称等
- 服务层方法
- 列表查询：支持分页、过滤条件、排序
- 详情查询：支持关联加载
- 创建/更新/删除：包含唯一性校验与级联检查
- 树形结构：手动构建树避免懒加载问题
**章节来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L16-L61)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L10-L743)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L16-L150)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L16-L112)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L16-L197)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L23-L293)
## 架构概览
后端采用分层架构，API层负责路由与权限控制，服务层封装业务逻辑，模型层定义数据库结构，模式层定义数据校验与序列化。前端通过统一的请求封装调用后端接口。
```mermaid
sequenceDiagram
participant FE as "前端"
participant API as "API路由"
participant SVC as "服务层"
participant DB as "数据库"
FE->>API : 发起HTTP请求
API->>SVC : 调用业务方法
SVC->>DB : 执行SQL查询/更新
DB-->>SVC : 返回结果
SVC-->>API : 返回业务结果
API-->>FE : 返回标准化响应
```
**图表来源**
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L20-L108)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L20-L124)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L20-L142)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L22-L272)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L16-L150)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L16-L112)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L16-L197)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L23-L293)
## 详细组件分析
### 科室管理接口
- 接口列表
- GET /departments：获取科室列表（支持类型过滤、启用状态过滤、分页）
- GET /departments/tree：获取科室树形结构（支持类型过滤）
- GET /departments/{dept_id}：获取科室详情
- POST /departments：创建科室（需管理员或经理权限）
- PUT /departments/{dept_id}：更新科室（需管理员或经理权限）
- DELETE /departments/{dept_id}：删除科室（需管理员或经理权限，存在子科室时拒绝删除）
- 数据验证规则
- 编码唯一性：创建前检查编码是否已存在
- 层级计算：根据父级科室自动计算层级
- 权限控制：创建、更新、删除接口要求管理员或经理角色
- 关联关系与级联
- 科室与员工：一对多关系，删除前检查是否存在子科室
- 树形结构：手动构建避免懒加载问题
- 分页、搜索与排序
- 分页：页码与每页数量参数，支持最小1、最大100
- 过滤：类型、启用状态
- 排序：按排序字段与ID排序
- 响应结构
- 列表接口返回分页响应对象，包含总数、当前页、每页数量与数据数组
- 详情接口返回单个实体对象
```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "departments.py"
participant Service as "DepartmentService"
participant DB as "数据库"
Client->>API : GET /departments?dept_type=&is_active=&page=&page_size=
API->>Service : get_list(dept_type, is_active, page, page_size)
Service->>DB : 查询科室列表
DB-->>Service : 返回结果集
Service-->>API : 返回列表与总数
API-->>Client : 返回分页响应
Client->>API : POST /departments
API->>Service : create(dept_data)
Service->>DB : 插入新科室
DB-->>Service : 返回新记录
Service-->>API : 返回创建结果
API-->>Client : 返回成功响应
```
**图表来源**
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L20-L108)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L16-L150)
**章节来源**
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L20-L108)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L16-L150)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L86)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L64-L103)
### 员工管理接口
- 接口列表
- GET /staff：获取员工列表（支持科室ID、状态、关键词搜索、分页）
- GET /staff/{staff_id}：获取员工详情（包含部门名称）
- POST /staff：创建员工（需管理员或经理权限）
- PUT /staff/{staff_id}：更新员工（需管理员或经理权限）
- DELETE /staff/{staff_id}：删除员工（需管理员或经理权限）
- GET /staff/department/{department_id}：获取指定科室所有员工
- 数据验证规则
- 工号唯一性：创建前检查工号是否已存在
- 状态枚举：仅允许预定义状态
- 权限控制：创建、更新、删除接口要求管理员或经理角色
- 关联关系与级联
- 员工与科室：多对一关系，查询时加载部门信息
- 状态过滤：默认仅显示在职员工
- 分页、搜索与排序
- 分页：页码与每页数量参数，支持最小1、最大100
- 过滤：科室ID、状态
- 搜索：姓名或工号模糊匹配
- 排序：按ID倒序
- 响应结构
- 列表接口返回分页响应对象，数据数组中包含部门名称字段
- 详情接口返回单个实体对象，包含部门名称字段
```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "staff.py"
participant Service as "StaffService"
participant DB as "数据库"
Client->>API : GET /staff?department_id=&status=&keyword=&page=&page_size=
API->>Service : get_list(department_id, status, keyword, page, page_size)
Service->>DB : 查询员工列表含部门信息
DB-->>Service : 返回结果集
Service-->>API : 返回列表与总数
API-->>Client : 返回分页响应含部门名称
Client->>API : POST /staff
API->>Service : create(staff_data)
Service->>DB : 插入新员工
DB-->>Service : 返回新记录
Service-->>API : 返回创建结果
API-->>Client : 返回成功响应
```
**图表来源**
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L20-L124)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L16-L112)
**章节来源**
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L20-L124)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L16-L112)
- [backend/app/models/models.py](file://backend/app/models/models.py#L88-L115)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L107-L150)
### 考核指标管理接口
- 接口列表
- GET /indicators：获取指标列表（支持类型、BSC维度、启用状态、分页）
- GET /indicators/active：获取所有启用的指标
- GET /indicators/{indicator_id}：获取指标详情
- POST /indicators：创建指标（需管理员或经理权限）
- PUT /indicators/{indicator_id}：更新指标（需管理员或经理权限）
- DELETE /indicators/{indicator_id}：删除指标（需管理员或经理权限）
- GET /indicators/templates/list：获取指标模板列表
- POST /indicators/templates/import：导入指标模板（支持覆盖选项）
- 数据验证规则
- 编码唯一性：创建前检查编码是否已存在
- 权重范围：权重必须在合理范围内
- 启用状态：支持启用/禁用切换
- 权限控制：创建、更新、删除、模板导入接口要求管理员或经理角色
- 关联关系与级联
- 指标与考核明细：一对多关系，删除前需确保无关联明细
- 模板导入：支持覆盖现有指标或跳过
- 分页、搜索与排序
- 分页：页码与每页数量参数，支持最小1、最大100
- 过滤：类型、BSC维度、启用状态
- 排序：按类型与ID排序
- 响应结构
- 列表接口返回分页响应对象
- 详情接口返回单个实体对象
- 模板导入接口返回导入数量统计
```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "indicators.py"
participant Service as "IndicatorService"
participant DB as "数据库"
Client->>API : GET /indicators?indicator_type=&bs_dimension=&is_active=&page=&page_size=
API->>Service : get_list(...)
Service->>DB : 查询指标列表
DB-->>Service : 返回结果集
Service-->>API : 返回列表与总数
API-->>Client : 返回分页响应
Client->>API : POST /indicators/templates/import?overwrite=false
API->>Service : import_template(template_data, overwrite)
Service->>DB : 批量插入或更新指标
DB-->>Service : 返回插入数量
Service-->>API : 返回导入统计
API-->>Client : 返回成功响应含创建数量
```
**图表来源**
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L20-L142)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L16-L197)
**章节来源**
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L20-L142)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L16-L197)
- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L147)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L153-L193)
### 指标模板管理接口
- 接口列表
- GET /templates：获取模板列表（支持类型、启用状态、分页）
- GET /templates/types：获取模板类型列表
- GET /templates/dimensions：获取BSC维度列表
- GET /templates/{template_id}：获取模板详情（包含模板指标详情）
- POST /templates：创建模板（需管理员或经理权限）
- PUT /templates/{template_id}：更新模板（需管理员或经理权限）
- DELETE /templates/{template_id}：删除模板（需管理员或经理权限）
- GET /templates/{template_id}/indicators：获取模板指标列表
- POST /templates/{template_id}/indicators：添加模板指标（需管理员或经理权限）
- PUT /templates/{template_id}/indicators/{indicator_id}：更新模板指标（需管理员或经理权限）
- DELETE /templates/{template_id}/indicators/{indicator_id}：移除模板指标（需管理员或经理权限）
- POST /templates/{template_id}/indicators/batch：批量添加模板指标（需管理员或经理权限）
- 数据验证规则
- 模板编码唯一性：创建前检查编码是否已存在
- 权重范围：权重必须在合理范围内
- 排序字段：支持自定义排序，未提供时按最大排序+1
- 权限控制：所有模板相关接口要求管理员或经理角色
- 关联关系与级联
- 模板与模板指标：一对多关系，支持增删改查与批量添加
- 模板指标与指标：多对一关系，查询时加载指标详细信息
- 分页、搜索与排序
- 分页：页码与每页数量参数，支持最小1、最大100
- 过滤：类型、启用状态
- 排序：按类型与ID排序
- 响应结构
- 列表接口返回分页响应对象，包含指标数量统计
- 详情接口返回模板对象与指标详情数组
- 批量添加接口返回添加数量统计
```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "templates.py"
participant Service as "TemplateService"
participant DB as "数据库"
Client->>API : GET /templates?template_type=&is_active=&page=&page_size=
API->>Service : get_list(...)
Service->>DB : 查询模板列表含指标数量
DB-->>Service : 返回结果集
Service-->>API : 返回列表与总数
API-->>Client : 返回分页响应含指标数量
Client->>API : POST /templates/{template_id}/indicators/batch
API->>Service : batch_add_template_indicators(template_id, indicators_data)
Service->>DB : 批量插入模板指标
DB-->>Service : 返回插入结果
Service-->>API : 返回批量统计
API-->>Client : 返回成功响应含添加数量
```
**图表来源**
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L22-L272)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L23-L293)
**章节来源**
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L22-L272)
- [backend/app/services/template_service.py](file://backend/app/services/template_service.py#L23-L293)
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L200)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L640-L743)
## 依赖分析
- 模块耦合
- API层仅依赖服务层，不直接操作数据库
- 服务层依赖模型层进行数据库操作
- 模式层为API与服务层提供数据校验与序列化
- 外部依赖
- FastAPI：Web框架与路由装饰器
- SQLAlchemy 2.0：异步ORM与查询构建
- Pydantic：数据模式与验证
- 权限控制
- 部分接口要求管理员或经理角色
- 使用依赖注入获取当前用户并进行权限校验
```mermaid
graph TB
API["API层<br/>departments.py / staff.py / indicators.py / templates.py"]
SVC["服务层<br/>department_service.py / staff_service.py / indicator_service.py / template_service.py"]
MODELS["模型层<br/>models.py"]
SCHEMAS["模式层<br/>schemas.py"]
API --> SVC
SVC --> MODELS
API --> SCHEMAS
SVC --> SCHEMAS
```
**图表来源**
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L17-L108)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L17-L124)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L17-L142)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L19-L272)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L13-L150)
- [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
- [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/models/models.py](file://backend/app/models/models.py#L62-L200)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L10-L743)
**章节来源**
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L17-L108)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L17-L124)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L17-L142)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L19-L272)
## 性能考虑
- 分页与索引
- 列表查询均支持分页，避免一次性返回大量数据
- 数据库表建立了必要的索引以提升查询性能
- 关联查询
- 使用selectinload优化N+1查询问题
- 树形结构查询手动构建，避免懒加载导致的性能问题
- 数据验证
- Pydantic模式在请求进入业务层前完成数据验证
- 唯一性检查在创建前执行，减少无效写入
- 异步处理
- 使用异步数据库连接，提升并发处理能力
## 故障排除指南
- 常见错误与处理
- 404错误：资源不存在（科室、员工、指标、模板）
- 400错误：删除失败（存在子资源或状态不允许）
- 400错误：创建失败（编码已存在）
- 权限不足：需要管理员或经理角色
- 日志与异常
- 全局异常处理器记录异常信息
- HTTP异常与验证异常分别处理
- 前端调用参考
- 前端通过统一的API封装调用后端接口
- 支持分页参数传递与响应解析
**章节来源**
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L60-L107)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L58-L108)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L64-L111)
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L83-L169)
- [backend/app/main.py](file://backend/app/main.py#L58-L75)
- [frontend/src/api/department.js](file://frontend/src/api/department.js#L1-L32)
- [frontend/src/api/staff.js](file://frontend/src/api/staff.js#L1-L32)
- [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)
## 结论
本API文档全面覆盖了基础数据管理的四大模块，提供了详细的接口规范、数据验证规则、关联关系处理、分页查询、搜索过滤、排序功能以及批量操作的使用方法。通过清晰的分层架构与严格的权限控制，系统能够稳定地支撑医院绩效管理的各项业务需求。建议在生产环境中结合前端封装进行集成测试，确保接口调用的正确性与性能表现。

454
.qoder/repowiki/zh/content/API接口文档/基础数据接口/模板管理接口.md Normal file
View File

@@ -0,0 +1,454 @@
# 模板管理接口
<cite>
**本文档引用的文件**
- [templates.py](file://backend/app/api/v1/templates.py)
- [template_service.py](file://backend/app/services/template_service.py)
- [models.py](file://backend/app/models/models.py)
- [schemas.py](file://backend/app/schemas/schemas.py)
- [template.js](file://frontend/src/api/template.js)
- [Templates.vue](file://frontend/src/views/basic/Templates.vue)
- [init_templates.py](file://backend/app/scripts/init_templates.py)
- [002_template.py](file://backend/alembic/versions/002_template.py)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 简介
模板管理接口是医院绩效管理系统的核心功能模块，负责管理各类绩效考核模板的完整生命周期。该系统实现了基于平衡计分卡理论的多维度绩效考核模板管理，支持通用模板、手术科室模板、医技科室模板等多种模板类型，为不同科室提供定制化的绩效考核方案。
系统采用FastAPI框架构建，基于异步数据库连接，确保高并发场景下的性能表现。模板管理功能涵盖了从模板创建、配置到删除的完整流程，同时支持模板指标的精细化管理，包括指标权重设置、评分方法配置等高级功能。
## 项目结构
模板管理模块在项目中的组织结构如下：
```mermaid
graph TB
subgraph "后端架构"
API[API路由层<br/>templates.py]
Service[服务层<br/>template_service.py]
Model[数据模型层<br/>models.py]
Schema[数据模式层<br/>schemas.py]
end
subgraph "前端架构"
FrontAPI[前端API封装<br/>template.js]
FrontView[模板管理界面<br/>Templates.vue]
end
subgraph "数据层"
DB[(数据库)]
Alembic[Alembic迁移<br/>002_template.py]
end
FrontAPI --> API
FrontView --> FrontAPI
API --> Service
Service --> Model
Model --> DB
Schema --> API
Alembic --> DB
```
**图表来源**
- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
- [template_service.py](file://backend/app/services/template_service.py#L1-L293)
- [models.py](file://backend/app/models/models.py#L387-L437)
**章节来源**
- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
- [template_service.py](file://backend/app/services/template_service.py#L1-L293)
- [models.py](file://backend/app/models/models.py#L387-L437)
## 核心组件
### 数据模型组件
系统采用三层架构的数据模型设计，包含以下核心实体：
#### 模板实体 (IndicatorTemplate)
- **主键**: 自增ID
- **模板标识**: 唯一模板编码和名称
- **模板类型**: 支持8种预定义类型
- **配置属性**: 维度权重、考核周期、启用状态
- **关联关系**: 一对多关联到模板指标
#### 指标实体 (TemplateIndicator)
- **主键**: 自增ID
- **关联属性**: 模板ID、指标ID
- **配置属性**: 分类、目标值、权重、评分方法
- **排序机制**: 支持自定义排序顺序
- **唯一约束**: 模板ID+指标ID组合唯一
#### 枚举类型
- **模板类型**: 通用、手术、非手术有病房、非手术无病房、医技、护理、行政、后勤
- **BSC维度**: 财务管理、顾客服务、内部流程、学习与成长
- **指标类型**: 质量、数量、效率、服务、成本
**章节来源**
- [models.py](file://backend/app/models/models.py#L375-L437)
- [schemas.py](file://backend/app/schemas/schemas.py#L640-L743)
### 服务层组件
#### TemplateService 类
提供完整的模板管理业务逻辑：
- **查询功能**: 列表查询、详情获取、按类型过滤
- **CRUD操作**: 创建、更新、删除模板
- **指标管理**: 添加、更新、删除模板指标
- **批量操作**: 批量添加模板指标
- **工具方法**: 类型标签转换、维度标签转换
**章节来源**
- [template_service.py](file://backend/app/services/template_service.py#L20-L293)
### API路由组件
#### 模板管理路由
- **GET /templates**: 获取模板列表，支持类型过滤和分页
- **GET /templates/types**: 获取模板类型列表
- **GET /templates/dimensions**: 获取BSC维度列表
- **GET /templates/{id}**: 获取模板详情
- **POST /templates**: 创建模板
- **PUT /templates/{id}**: 更新模板
- **DELETE /templates/{id}**: 删除模板
#### 模板指标管理路由
- **GET /templates/{template_id}/indicators**: 获取模板指标列表
- **POST /templates/{template_id}/indicators**: 添加模板指标
- **PUT /templates/{template_id}/indicators/{indicator_id}**: 更新模板指标
- **DELETE /templates/{template_id}/indicators/{indicator_id}**: 移除模板指标
- **POST /templates/{template_id}/indicators/batch**: 批量添加模板指标
**章节来源**
- [templates.py](file://backend/app/api/v1/templates.py#L22-L272)
## 架构概览
系统采用分层架构设计，确保关注点分离和代码可维护性：
```mermaid
sequenceDiagram
participant Client as 前端客户端
participant API as API路由层
participant Service as 服务层
participant DB as 数据库
participant Model as 数据模型
Client->>API : GET /templates
API->>Service : get_list()
Service->>DB : 查询模板列表
DB->>Service : 返回模板数据
Service->>Service : 统计指标数量
Service->>API : 返回处理后的数据
API->>Client : JSON响应
Note over Client,DB : 异步数据库操作，支持高并发
```
**图表来源**
- [templates.py](file://backend/app/api/v1/templates.py#L22-L42)
- [template_service.py](file://backend/app/services/template_service.py#L24-L71)
### 数据流架构
```mermaid
flowchart TD
subgraph "前端层"
FE_API[前端API调用]
FE_VIEW[模板管理界面]
end
subgraph "后端层"
ROUTER[路由处理]
SERVICE[业务逻辑]
VALIDATION[数据验证]
end
subgraph "数据层"
MODEL[ORM模型]
DATABASE[(数据库)]
end
FE_API --> ROUTER
FE_VIEW --> FE_API
ROUTER --> VALIDATION
VALIDATION --> SERVICE
SERVICE --> MODEL
MODEL --> DATABASE
DATABASE --> MODEL
MODEL --> SERVICE
SERVICE --> ROUTER
ROUTER --> FE_API
```
**图表来源**
- [template.js](file://frontend/src/api/template.js#L1-L62)
- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
## 详细组件分析
### 模板类型分类系统
系统支持8种预定义的模板类型，每种类型针对特定的科室特点设计：
#### 通用模板 (GENERAL)
- **适用范围**: 全院各科室
- **特点**: 基于平衡计分卡四维度设计
- **典型权重**: 财务35%、客户30%、内部流程25%、学习成长10%
#### 手术科室模板 (SURGICAL)
- **适用范围**: 外科、妇科、眼科等手术科室
- **特点**: 结合RBRVS和DRG理念
- **重点指标**: DRG组数、CMI值、费用消耗指数
#### 医技科室模板 (MEDICAL_TECH)
- **适用范围**: 检验科、放射科、超声科等
- **特点**: 质量效率双核心
- **重点指标**: 报告准确率、危急值及时率
#### 行政科室模板 (ADMIN)
- **适用范围**: 院办、党办、医务科等
- **特点**: 服务支持导向
- **重点指标**: 服务态度、遵纪守法
#### 后勤科室模板 (LOGISTICS)
- **适用范围**: 总务科、设备科等
- **特点**: 后勤保障核心
- **重点指标**: 保障及时率、设备完好率
**章节来源**
- [models.py](file://backend/app/models/models.py#L375-L384)
- [schemas.py](file://backend/app/schemas/schemas.py#L642-L651)
### 模板数据结构定义
#### 模板基础结构
| 字段名 | 类型 | 描述 | 必填 |
|--------|------|------|------|
| template_name | String | 模板名称 | 是 |
| template_code | String | 模板编码 | 是 |
| template_type | Enum | 模板类型 | 是 |
| description | Text | 模板描述 | 否 |
| dimension_weights | JSON | 维度权重配置 | 否 |
| assessment_cycle | String | 考核周期 | 否 |
| is_active | Boolean | 是否启用 | 否 |
#### 模板指标结构
| 字段名 | 类型 | 描述 | 必填 |
|--------|------|------|------|
| indicator_id | Integer | 指标ID | 是 |
| category | String | 指标分类 | 否 |
| target_value | Float | 目标值 | 否 |
| target_unit | String | 目标值单位 | 否 |
| weight | Float | 权重 | 否 |
| scoring_method | String | 评分方法 | 否 |
| scoring_params | JSON | 评分参数 | 否 |
| sort_order | Integer | 排序 | 否 |
| remark | Text | 备注 | 否 |
**章节来源**
- [schemas.py](file://backend/app/schemas/schemas.py#L698-L743)
- [schemas.py](file://backend/app/schemas/schemas.py#L654-L696)
### 模板继承与复用机制
系统通过模板继承机制实现模板的复用和扩展：
```mermaid
classDiagram
class IndicatorTemplate {
+Integer id
+String template_code
+String template_name
+TemplateType template_type
+String description
+String dimension_weights
+String assessment_cycle
+Boolean is_active
+DateTime created_at
+DateTime updated_at
+TemplateIndicator[] indicators
}
class TemplateIndicator {
+Integer id
+Integer template_id
+Integer indicator_id
+String category
+Float target_value
+String target_unit
+Float weight
+String scoring_method
+String scoring_params
+Integer sort_order
+String remark
+DateTime created_at
+DateTime updated_at
}
class Indicator {
+Integer id
+String code
+String name
+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
+Boolean is_veto
+Boolean is_active
}
IndicatorTemplate "1" -- "many" TemplateIndicator : "包含"
TemplateIndicator "many" -- "1" Indicator : "关联"
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L387-L437)
### 版本控制实现
虽然模板管理接口没有直接的版本控制功能，但系统通过以下机制实现版本管理：
1. **模板历史记录**: 每个模板都有创建时间和更新时间
2. **状态管理**: 通过`is_active`字段控制模板启用状态
3. **数据完整性**: 使用数据库约束确保数据一致性
**章节来源**
- [models.py](file://backend/app/models/models.py#L391-L400)
### 批量操作功能
系统提供了完善的批量操作功能：
#### 批量添加模板指标
- **接口**: POST `/templates/{template_id}/indicators/batch`
- **功能**: 支持一次性添加多个模板指标
- **特性**: 自动设置排序顺序，支持部分字段配置
#### 批量处理流程
```mermaid
flowchart TD
Start([开始批量添加]) --> Validate["验证模板ID"]
Validate --> Loop{"遍历指标数组"}
Loop --> |是| CheckOrder["检查排序设置"]
CheckOrder --> AddIndicator["添加模板指标"]
AddIndicator --> UpdateCount["增加成功计数"]
UpdateCount --> Loop
Loop --> |否| ReturnResult["返回处理结果"]
ReturnResult --> End([结束])
```
**图表来源**
- [templates.py](file://backend/app/api/v1/templates.py#L252-L271)
**章节来源**
- [templates.py](file://backend/app/api/v1/templates.py#L252-L271)
## 依赖关系分析
### 组件耦合关系
```mermaid
graph TB
subgraph "API层"
TPL_API[templates.py]
end
subgraph "服务层"
TPL_SERVICE[template_service.py]
end
subgraph "模型层"
MODELS[models.py]
ENUMS[枚举类型]
end
subgraph "数据层"
SCHEMAS[schemas.py]
DB[(数据库)]
end
TPL_API --> TPL_SERVICE
TPL_SERVICE --> MODELS
MODELS --> ENUMS
MODELS --> DB
TPL_API --> SCHEMAS
SCHEMAS --> MODELS
```
**图表来源**
- [templates.py](file://backend/app/api/v1/templates.py#L1-L272)
- [template_service.py](file://backend/app/services/template_service.py#L1-L293)
### 外部依赖
系统主要依赖以下外部组件：
- **FastAPI**: Web框架，提供异步API支持
- **SQLAlchemy**: ORM框架，处理数据库操作
- **Alembic**: 数据库迁移工具
- **Pydantic**: 数据验证和序列化
**章节来源**
- [templates.py](file://backend/app/api/v1/templates.py#L1-L18)
- [template_service.py](file://backend/app/services/template_service.py#L1-L18)
## 性能考虑
### 数据库优化策略
1. **索引优化**: 模板类型和启用状态字段建立了复合索引
2. **查询优化**: 使用分页查询避免大数据集加载
3. **连接池**: 异步数据库连接池提高并发性能
### 缓存策略
系统目前采用懒加载策略，通过`selectinload`优化N+1查询问题，减少数据库访问次数。
### 并发处理
- **异步操作**: 所有数据库操作都是异步的
- **事务管理**: 自动事务提交和回滚
- **错误处理**: 完善的异常处理机制
## 故障排除指南
### 常见问题及解决方案
#### 模板编码重复
**问题**: 创建模板时报错"模板编码已存在"
**原因**: 模板编码必须唯一
**解决**: 修改模板编码或使用系统生成的新编码
#### 模板不存在
**问题**: 更新或删除模板时报错"模板不存在"
**原因**: 模板ID无效或已被删除
**解决**: 检查模板ID有效性或重新获取模板列表
#### 指标已存在
**问题**: 添加模板指标时报错"指标已存在"
**原因**: 同一模板中重复添加相同指标
**解决**: 移除重复指标或使用新的指标ID
#### 权限不足
**问题**: 访问受保护的模板管理功能被拒绝
**原因**: 当前用户角色不满足管理员或经理权限要求
**解决**: 登录具有相应权限的账户或联系系统管理员
**章节来源**
- [templates.py](file://backend/app/api/v1/templates.py#L136-L168)
- [template_service.py](file://backend/app/services/template_service.py#L167-L182)
## 结论
模板管理接口为医院绩效管理系统提供了完整的模板生命周期管理能力。通过8种预定义的模板类型、灵活的指标配置和强大的批量操作功能，系统能够满足不同类型科室的绩效考核需求。
系统采用现代化的架构设计，基于FastAPI和SQLAlchemy构建，确保了高性能和高可用性。模板继承机制和复用策略使得系统具有良好的扩展性和维护性。
未来可以考虑的功能增强包括：
- 模板版本控制功能
- 模板复制和导入导出功能
- 更丰富的模板指标评分算法
- 模板使用统计和分析功能

849
.qoder/repowiki/zh/content/API接口文档/基础数据接口/科室管理接口.md Normal file
View File

@@ -0,0 +1,849 @@
# 科室管理接口
<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/core/security.py](file://backend/app/core/security.py)
- [backend/app/core/database.py](file://backend/app/core/database.py)
- [backend/app/core/config.py](file://backend/app/core/config.py)
- [frontend/src/api/department.js](file://frontend/src/api/department.js)
- [frontend/public/test-api.html](file://frontend/public/test-api.html)
- [docs/api.md](file://docs/api.md)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细接口文档](#详细接口文档)
6. [树形结构查询实现原理](#树形结构查询实现原理)
7. [权限控制机制](#权限控制机制)
8. [数据模型](#数据模型)
9. [性能考虑](#性能考虑)
10. [故障排除指南](#故障排除指南)
11. [结论](#结论)
## 简介
本文档详细介绍了医院绩效管理系统的科室管理接口。该系统基于FastAPI构建，提供了完整的科室CRUD操作，包括获取科室列表（支持按类型和状态过滤）、获取树形结构、获取科室详情、创建科室、更新科室和删除科室。系统采用JWT认证机制，支持管理员和经理两种权限级别，并提供了完整的分页查询功能。
## 项目结构
后端采用分层架构设计，主要包含以下层次：
```mermaid
graph TB
subgraph "前端层"
FE[Vue.js 前端]
API[API 请求封装]
end
subgraph "接口层"
Router[FastAPI 路由器]
Auth[认证中间件]
end
subgraph "业务逻辑层"
Service[科室服务层]
Validation[数据验证]
end
subgraph "数据访问层"
Model[数据模型]
Schema[Pydantic 模式]
Security[安全认证]
end
subgraph "基础设施"
DB[(PostgreSQL 数据库)]
Config[配置管理]
end
FE --> API
API --> Router
Router --> Auth
Router --> Service
Service --> Model
Service --> Schema
Auth --> Security
Model --> DB
Config --> DB
```
**图表来源**
- [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/core/security.py](file://backend/app/core/security.py#L1-L110)
**章节来源**
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L1-L18)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L1-L150)
## 核心组件
### API路由器
- **位置**: `backend/app/api/v1/departments.py`
- **功能**: 定义所有科室管理相关的HTTP端点
- **标签**: "科室管理"
### 服务层
- **位置**: `backend/app/services/department_service.py`
- **职责**: 实现业务逻辑，包括数据查询、验证和操作
- **特点**: 异步操作，支持事务处理
### 数据模型
- **位置**: `backend/app/models/models.py`
- **实体**: Department（科室表）
- **特性**: 支持层级关系，自引用外键
### 数据验证
- **位置**: `backend/app/schemas/schemas.py`
- **用途**: Pydantic模型用于请求验证和响应序列化
- **类型**: DepartmentCreate, DepartmentUpdate, DepartmentResponse
**章节来源**
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L17-L18)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L13-L15)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L86)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L64-L103)
## 架构概览
系统采用经典的MVC架构模式，结合现代的异步编程：
```mermaid
sequenceDiagram
participant Client as 客户端
participant API as API路由器
participant Auth as 认证中间件
participant Service as 服务层
participant DB as 数据库
participant Model as 数据模型
Client->>API : HTTP请求
API->>Auth : 验证JWT令牌
Auth->>Auth : 验证用户权限
Auth-->>API : 通过验证
API->>Service : 调用业务逻辑
Service->>DB : 执行数据库操作
DB->>Model : 映射到模型
Model-->>DB : 返回数据
DB-->>Service : 查询结果
Service-->>API : 处理后的数据
API-->>Client : JSON响应
```
**图表来源**
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L20-L40)
- [backend/app/core/security.py](file://backend/app/core/security.py#L85-L109)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L16-L43)
## 详细接口文档
### 获取科室列表
**HTTP方法**: GET
**URL路径**: `/api/v1/departments`
**权限要求**: 需要激活用户权限
**查询参数**:
| 参数名 | 类型 | 必填 | 默认值 | 描述 |
|--------|------|------|--------|------|
| dept_type | string | 否 | 无 | 科室类型过滤 |
| is_active | boolean | 否 | 无 | 启用状态过滤 |
| page | int | 否 | 1 | 页码，最小值1 |
| page_size | int | 否 | 20 | 每页数量，范围1-100 |
**响应数据结构**:
```json
{
"code": 200,
"message": "success",
"data": [
{
"id": 1,
"name": "内科",
"code": "NK001",
"dept_type": "clinical_surgical",
"parent_id": null,
"level": 1,
"sort_order": 1,
"is_active": true,
"description": "内科描述",
"created_at": "2024-01-01T00:00:00",
"updated_at": "2024-01-01T00:00:00"
}
],
"total": 10,
"page": 1,
"page_size": 20
}
```
**请求示例**:
```bash
curl -X GET "http://localhost:8000/api/v1/departments?page=1&page_size=20&dept_type=clinical_surgical&is_active=true" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**响应示例**:
```json
{
"code": 200,
"message": "success",
"data": [
{
"id": 1,
"name": "内科",
"code": "NK001",
"dept_type": "clinical_surgical",
"parent_id": null,
"level": 1,
"sort_order": 1,
"is_active": true,
"description": "",
"created_at": "2024-01-01T00:00:00",
"updated_at": "2024-01-01T00:00:00"
}
],
"total": 1,
"page": 1,
"page_size": 20
}
```
**错误处理**:
- 401 未授权：无效或过期的JWT令牌
- 403 禁止：用户权限不足
- 404 未找到：无匹配的数据
**章节来源**
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L20-L40)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L17-L43)
### 获取科室树形结构
**HTTP方法**: GET
**URL路径**: `/api/v1/departments/tree`
**权限要求**: 需要激活用户权限
**查询参数**:
| 参数名 | 类型 | 必填 | 默认值 | 描述 |
|--------|------|------|--------|------|
| dept_type | string | 否 | 无 | 科室类型过滤 |
**响应数据结构**:
```json
{
"code": 200,
"message": "success",
"data": [
{
"id": 1,
"name": "医院",
"code": "HOSPITAL",
"dept_type": "admin",
"parent_id": null,
"level": 1,
"sort_order": 1,
"is_active": true,
"description": "",
"created_at": "2024-01-01T00:00:00",
"updated_at": "2024-01-01T00:00:00",
"children": [
{
"id": 2,
"name": "内科",
"code": "NK001",
"dept_type": "clinical_surgical",
"parent_id": 1,
"level": 2,
"sort_order": 1,
"is_active": true,
"description": "",
"created_at": "2024-01-01T00:00:00",
"updated_at": "2024-01-01T00:00:00",
"children": []
}
]
}
]
}
```
**请求示例**:
```bash
curl -X GET "http://localhost:8000/api/v1/departments/tree?dept_type=clinical_surgical" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**响应示例**:
```json
{
"code": 200,
"message": "success",
"data": [
{
"id": 1,
"name": "医院",
"code": "HOSPITAL",
"dept_type": "admin",
"parent_id": null,
"level": 1,
"sort_order": 1,
"is_active": true,
"description": "",
"created_at": "2024-01-01T00:00:00",
"updated_at": "2024-01-01T00:00:00",
"children": [
{
"id": 2,
"name": "内科",
"code": "NK001",
"dept_type": "clinical_surgical",
"parent_id": 1,
"level": 2,
"sort_order": 1,
"is_active": true,
"description": "",
"created_at": "2024-01-01T00:00:00",
"updated_at": "2024-01-01T00:00:00",
"children": []
}
]
}
]
}
```
**错误处理**:
- 401 未授权：无效或过期的JWT令牌
- 403 禁止：用户权限不足
**章节来源**
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L43-L51)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L112-L149)
### 获取科室详情
**HTTP方法**: GET
**URL路径**: `/api/v1/departments/{dept_id}`
**权限要求**: 需要激活用户权限
**路径参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| dept_id | int | 是 | 科室ID |
**响应数据结构**:
```json
{
"code": 200,
"message": "success",
"data": {
"id": 1,
"name": "内科",
"code": "NK001",
"dept_type": "clinical_surgical",
"parent_id": null,
"level": 1,
"sort_order": 1,
"is_active": true,
"description": "内科描述",
"created_at": "2024-01-01T00:00:00",
"updated_at": "2024-01-01T00:00:00"
}
}
```
**请求示例**:
```bash
curl -X GET "http://localhost:8000/api/v1/departments/1" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**响应示例**:
```json
{
"code": 200,
"message": "success",
"data": {
"id": 1,
"name": "内科",
"code": "NK001",
"dept_type": "clinical_surgical",
"parent_id": null,
"level": 1,
"sort_order": 1,
"is_active": true,
"description": "",
"created_at": "2024-01-01T00:00:00",
"updated_at": "2024-01-01T00:00:00"
}
}
```
**错误处理**:
- 401 未授权：无效或过期的JWT令牌
- 403 禁止：用户权限不足
- 404 未找到：科室不存在
**章节来源**
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L54-L64)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L46-L51)
### 创建科室
**HTTP方法**: POST
**URL路径**: `/api/v1/departments`
**权限要求**: 需要管理员或经理权限
**请求体参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| name | string | 是 | 科室名称，最大100字符 |
| code | string | 是 | 科室编码，最大20字符，必须唯一 |
| dept_type | string | 是 | 科室类型 |
| parent_id | int | 否 | 上级科室ID |
| level | int | 否 | 层级，默认1 |
| sort_order | int | 否 | 排序 |
| description | string | 否 | 描述 |
**响应数据结构**:
```json
{
"code": 200,
"message": "创建成功",
"data": {
"id": 1,
"name": "内科",
"code": "NK001",
"dept_type": "clinical_surgical",
"parent_id": null,
"level": 1,
"sort_order": 1,
"is_active": true,
"description": "",
"created_at": "2024-01-01T00:00:00",
"updated_at": "2024-01-01T00:00:00"
}
}
```
**请求示例**:
```bash
curl -X POST "http://localhost:8000/api/v1/departments" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "内科",
"code": "NK001",
"dept_type": "clinical_surgical",
"parent_id": null,
"sort_order": 1,
"description": "内科描述"
}'
```
**响应示例**:
```json
{
"code": 200,
"message": "创建成功",
"data": {
"id": 1,
"name": "内科",
"code": "NK001",
"dept_type": "clinical_surgical",
"parent_id": null,
"level": 1,
"sort_order": 1,
"is_active": true,
"description": "内科描述",
"created_at": "2024-01-01T00:00:00",
"updated_at": "2024-01-01T00:00:00"
}
}
```
**错误处理**:
- 400 错误请求：科室编码已存在
- 401 未授权：无效或过期的JWT令牌
- 403 禁止：用户权限不足
**章节来源**
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L67-L80)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L62-L78)
### 更新科室
**HTTP方法**: PUT
**URL路径**: `/api/v1/departments/{dept_id}`
**权限要求**: 需要管理员或经理权限
**路径参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| dept_id | int | 是 | 科室ID |
**请求体参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| name | string | 否 | 科室名称，最大100字符 |
| dept_type | string | 否 | 科室类型 |
| parent_id | int | 否 | 上级科室ID |
| sort_order | int | 否 | 排序 |
| is_active | boolean | 否 | 是否启用 |
| description | string | 否 | 描述 |
**响应数据结构**:
```json
{
"code": 200,
"message": "更新成功",
"data": {
"id": 1,
"name": "内科",
"code": "NK001",
"dept_type": "clinical_surgical",
"parent_id": null,
"level": 1,
"sort_order": 1,
"is_active": true,
"description": "更新后的描述",
"created_at": "2024-01-01T00:00:00",
"updated_at": "2024-01-01T00:00:00"
}
}
```
**请求示例**:
```bash
curl -X PUT "http://localhost:8000/api/v1/departments/1" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "内科",
"description": "更新后的描述"
}'
```
**响应示例**:
```json
{
"code": 200,
"message": "更新成功",
"data": {
"id": 1,
"name": "内科",
"code": "NK001",
"dept_type": "clinical_surgical",
"parent_id": null,
"level": 1,
"sort_order": 1,
"is_active": true,
"description": "更新后的描述",
"created_at": "2024-01-01T00:00:00",
"updated_at": "2024-01-01T00:00:00"
}
}
```
**错误处理**:
- 401 未授权：无效或过期的JWT令牌
- 403 禁止：用户权限不足
- 404 未找到：科室不存在
**章节来源**
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L83-L94)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L81-L93)
### 删除科室
**HTTP方法**: DELETE
**URL路径**: `/api/v1/departments/{dept_id}`
**权限要求**: 需要管理员或经理权限
**路径参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| dept_id | int | 是 | 科室ID |
**响应数据结构**:
```json
{
"code": 200,
"message": "删除成功"
}
```
**请求示例**:
```bash
curl -X DELETE "http://localhost:8000/api/v1/departments/1" \
-H "Authorization: Bearer YOUR_TOKEN"
```
**响应示例**:
```json
{
"code": 200,
"message": "删除成功"
}
```
**错误处理**:
- 400 错误请求：无法删除，科室下存在子科室
- 401 未授权：无效或过期的JWT令牌
- 403 禁止：用户权限不足
**章节来源**
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L97-L107)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L95-L110)
## 树形结构查询实现原理
### 数据模型设计
科室表采用自引用外键设计，支持无限层级的组织结构：
```mermaid
erDiagram
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
}
DEPARTMENTS ||--o{ DEPARTMENTS : "parent"
```
**图表来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L86)
### 树形构建算法
服务层实现了高效的树形结构构建算法：
```mermaid
flowchart TD
Start([开始构建树形结构]) --> LoadData["加载所有科室数据"]
LoadData --> CreateMap["创建科室映射表<br/>ID -> Tree节点"]
CreateMap --> InitChildren["初始化所有节点的children为空数组"]
InitChildren --> BuildTree["遍历所有科室构建树"]
BuildTree --> CheckParent{"是否有上级科室?"}
CheckParent --> |是| AddToParent["添加到上级节点的children"]
CheckParent --> |否| AddToRoots["添加到根节点列表"]
AddToParent --> NextDept{"还有下一个科室?"}
AddToRoots --> NextDept
NextDept --> |是| BuildTree
NextDept --> |否| ReturnTree["返回根节点列表"]
ReturnTree --> End([结束])
```
**图表来源**
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L113-L149)
### 层级关系处理
系统自动计算和维护科室层级关系：
1. **层级计算**: 新建科室时，如果指定parent_id，则level = parent.level + 1
2. **排序规则**: 按sort_order和id进行排序
3. **层级限制**: 支持最多5级深度
**章节来源**
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L62-L78)
- [backend/app/models/models.py](file://backend/app/models/models.py#L69-L71)
## 权限控制机制
### 角色定义
系统支持三种用户角色：
- **admin**: 系统管理员，拥有最高权限
- **manager**: 科室经理，具有业务操作权限
- **staff**: 普通员工，只读权限
### 权限验证流程
```mermaid
sequenceDiagram
participant Client as 客户端
participant API as API端点
participant Auth as 认证中间件
participant Role as 角色验证
participant DB as 数据库
Client->>API : 发送带JWT的请求
API->>Auth : 验证JWT令牌
Auth->>DB : 验证用户有效性
DB-->>Auth : 用户信息
Auth->>Role : 检查角色权限
Role-->>API : 权限验证结果
API-->>Client : 返回响应或错误
```
**图表来源**
- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L109)
### 权限矩阵
| 操作 | 激活用户 | 管理员 | 经理 |
|------|----------|--------|------|
| 获取列表 | ✅ | ✅ | ✅ |
| 获取树形结构 | ✅ | ✅ | ✅ |
| 获取详情 | ✅ | ✅ | ✅ |
| 创建科室 | ❌ | ✅ | ✅ |
| 更新科室 | ❌ | ✅ | ✅ |
| 删除科室 | ❌ | ✅ | ✅ |
**章节来源**
- [backend/app/core/security.py](file://backend/app/core/security.py#L85-L109)
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L67-L107)
## 数据模型
### 科室实体
科室表包含以下字段：
| 字段名 | 类型 | 约束 | 描述 |
|--------|------|------|------|
| id | int | 主键，自增 | 科室ID |
| name | string | 非空，最大100 | 科室名称 |
| code | string | 非空，唯一，最大20 | 科室编码 |
| dept_type | enum | 非空 | 科室类型 |
| parent_id | int | 外键到departments.id | 上级科室ID |
| level | int | 默认1，范围1-5 | 层级 |
| sort_order | int | 默认0 | 排序 |
| is_active | boolean | 默认true | 是否启用 |
| description | text | 可空 | 描述信息 |
| created_at | datetime | 默认当前时间 | 创建时间 |
| updated_at | datetime | 默认当前时间，更新时自动 | 更新时间 |
### 科室类型枚举
系统支持9种科室类型：
- `clinical_surgical`: 手术临床科室
- `clinical_nonsurgical_ward`: 非手术有病房科室
- `clinical_nonsurgical_noward`: 非手术无病房科室
- `medical_tech`: 医技科室
- `medical_auxiliary`: 医辅科室
- `nursing`: 护理单元
- `admin`: 行政科室
- `finance`: 财务科室
- `logistics`: 后勤保障科室
**章节来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L86)
- [backend/app/models/models.py](file://backend/app/models/models.py#L16-L27)
## 性能考虑
### 数据库优化
1. **索引策略**:
- `idx_dept_type`: 科室类型索引
- `idx_dept_parent`: 上级科室索引
- `idx_dept_code`: 编码唯一索引
2. **查询优化**:
- 使用异步查询避免阻塞
- 分页查询限制结果集大小
- 批量操作减少数据库往返
3. **连接池管理**:
- 默认池大小20，溢出10
- 自动事务管理和回滚
### 缓存策略
- **树形结构缓存**: 对于静态的组织架构数据，建议实现Redis缓存
- **用户权限缓存**: 缓存用户角色信息减少数据库查询
- **配置信息缓存**: 使用LRU缓存配置项
### 异步处理
系统采用异步编程模型：
- 使用SQLAlchemy异步引擎
- 异步数据库会话管理
- 非阻塞I/O操作
**章节来源**
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L20)
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
## 故障排除指南
### 常见错误及解决方案
#### 1. 认证失败
**症状**: 401 未授权错误
**原因**: JWT令牌无效或过期
**解决方案**:
- 重新登录获取新令牌
- 检查令牌格式和有效期
- 验证服务器时间同步
#### 2. 权限不足
**症状**: 403 禁止访问
**原因**: 用户角色不满足操作要求
**解决方案**:
- 确认用户角色为admin或manager
- 检查用户状态是否激活
- 验证用户是否被禁用
#### 3. 数据重复
**症状**: 400 错误请求，提示编码已存在
**原因**: 科室编码重复
**解决方案**:
- 修改唯一的科室编码
- 检查现有数据避免冲突
- 使用系统提供的唯一性约束
#### 4. 删除失败
**症状**: 400 错误请求，提示无法删除
**原因**: 科室下存在子科室
**解决方案**:
- 先删除所有子科室
- 或者调整层级关系
- 使用树形结构查看层级
### 调试工具
#### 前端测试页面
系统提供了测试页面用于调试API：
- **路径**: `frontend/public/test-api.html`
- **功能**: 包含健康检查、登录测试、科室列表测试等
- **使用**: 直接在浏览器中打开测试页面
#### 日志监控
- **应用日志**: `backend/app/logs/`
- **错误日志**: `backend/app/logs/error_*.log`
- **数据库日志**: SQL查询语句和执行时间
**章节来源**
- [frontend/public/test-api.html](file://frontend/public/test-api.html#L1-L133)
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L75-L77)
- [backend/app/services/department_service.py](file://backend/app/services/department_service.py#L102-L107)
## 结论
科室管理接口提供了完整的CRUD操作，支持复杂的树形结构查询和权限控制。系统采用现代化的技术栈，具有良好的扩展性和维护性。通过合理的数据模型设计和权限控制机制，确保了系统的安全性和稳定性。
主要优势：
1. **完整的功能覆盖**: 支持所有必要的科室管理操作
2. **灵活的查询能力**: 支持多条件过滤和分页查询
3. **强大的权限控制**: 细粒度的角色权限管理
4. **高性能设计**: 异步架构和数据库优化
5. **易于扩展**: 清晰的分层架构便于功能扩展
建议后续改进方向：
1. 添加树形结构缓存机制
2. 实现批量操作功能
3. 增强数据导入导出能力
4. 完善审计日志功能

753
.qoder/repowiki/zh/content/API接口文档/基础数据接口/考核指标管理接口.md Normal file
View File

@@ -0,0 +1,753 @@
# 考核指标管理接口
<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/init_indicator_templates.py](file://backend/init_indicator_templates.py)
- [docs/api.md](file://docs/api.md)
- [docs/详细设计.md](file://docs/详细设计.md)
- [frontend/src/api/indicator.js](file://frontend/src/api/indicator.js)
- [frontend/src/views/basic/Indicators.vue](file://frontend/src/views/basic/Indicators.vue)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件为医院绩效管理系统中的考核指标管理接口提供详细的API文档。系统基于平衡计分卡理论，实现了完整的指标生命周期管理，包括指标的创建、查询、更新、删除以及模板管理功能。
系统支持四个维度的平衡计分卡指标管理：
- **财务维度**：关注医院的经济效益和成本控制
- **客户维度**：关注患者满意度和服务质量
- **内部流程维度**：关注医疗质量和运营效率
- **学习与成长维度**：关注员工发展和能力提升
## 项目结构
后端采用FastAPI框架，遵循MVC架构模式，主要分为以下层次：
```mermaid
graph TB
subgraph "表现层"
Frontend[前端Vue.js应用]
end
subgraph "应用层"
API[API路由层]
Service[业务服务层]
end
subgraph "数据层"
Model[数据模型层]
Database[(PostgreSQL数据库)]
end
Frontend --> API
API --> Service
Service --> Model
Model --> Database
```
**图表来源**
- [backend/app/main.py](file://backend/app/main.py#L15-L77)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
**章节来源**
- [backend/app/main.py](file://backend/app/main.py#L15-L77)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
## 核心组件
### 指标管理核心组件
系统的核心组件包括指标模型、服务层和API路由，形成了完整的指标管理功能体系。
```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 IndicatorService {
+get_list() tuple
+get_by_id() Indicator
+get_active_indicators() List[Indicator]
+create() Indicator
+update() Indicator
+delete() bool
+import_template() int
+get_templates() List[Dict]
}
class IndicatorRouter {
+get_indicators() Response
+get_active_indicators() Response
+get_indicator() Response
+create_indicator() Response
+update_indicator() Response
+delete_indicator() Response
+get_indicator_templates() Response
+import_indicator_template() Response
}
IndicatorService --> Indicator : "管理"
IndicatorRouter --> IndicatorService : "调用"
```
**图表来源**
- [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#L13-L197)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L17-L142)
### 指标类型和维度体系
系统定义了完整的指标分类体系，支持多维度的指标管理：
| 指标类型 | 描述 | 示例 |
|---------|------|------|
| quality | 质量指标 | 病历合格率、满意度 |
| quantity | 数量指标 | 门诊量、手术量 |
| efficiency | 效率指标 | 平均住院日、床位使用率 |
| service | 服务指标 | 服务态度、响应时间 |
| cost | 成本指标 | 药品占比、能耗成本 |
| 平衡计分卡维度 | 权重范围 | 描述 |
|---------------|----------|------|
| financial | 30%-40% | 财务效益和成本控制 |
| customer | 25%-35% | 患者满意度和市场地位 |
| internal_process | 20%-30% | 内部流程效率和质量 |
| learning_growth | 5%-15% | 员工能力和创新 |
**章节来源**
- [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#L39-L44)
## 架构概览
系统采用分层架构设计，确保了良好的可维护性和扩展性：
```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "API路由层"
participant Service as "服务层"
participant Model as "数据模型层"
participant DB as "数据库"
Client->>API : GET /indicators
API->>Service : get_list()
Service->>Model : 查询指标
Model->>DB : SQL查询
DB-->>Model : 查询结果
Model-->>Service : 指标列表
Service-->>API : 指标数据
API-->>Client : JSON响应
Note over Client,DB : 异步数据库操作支持
```
**图表来源**
- [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)
## 详细组件分析
### 指标管理API接口
#### 指标列表查询
**接口定义**
- 方法：GET
- 路径：`/indicators`
- 权限：所有用户
**查询参数**
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|-------|------|------|--------|------|
| indicator_type | string | 否 | 无 | 指标类型过滤 |
| bs_dimension | string | 否 | 无 | 平衡计分卡维度过滤 |
| is_active | boolean | 否 | 无 | 是否启用过滤 |
| page | int | 是 | 1 | 页码 |
| page_size | int | 是 | 20 | 每页数量 |
**响应结构**
```json
{
"code": 200,
"message": "success",
"data": [
{
"id": 1,
"name": "门诊量",
"code": "IND001",
"indicator_type": "quantity",
"weight": 1.0,
"max_score": 100.0,
"target_value": 500.0,
"unit": "人次",
"calculation_method": "实际值/目标值*100",
"description": "月度门诊接诊量",
"is_active": true,
"created_at": "2024-01-01T00:00:00",
"updated_at": "2024-01-01T00:00:00"
}
],
"total": 20,
"page": 1,
"page_size": 20
}
```
#### 启用的指标查询
**接口定义**
- 方法：GET
- 路径：`/indicators/active`
- 权限：所有用户
**响应结构**
```json
{
"code": 200,
"message": "success",
"data": [
{
"id": 1,
"name": "门诊量",
"code": "IND001",
"indicator_type": "quantity",
"weight": 1.0,
"max_score": 100.0,
"target_value": 500.0,
"unit": "人次",
"calculation_method": "实际值/目标值*100",
"description": "月度门诊接诊量",
"is_active": true,
"created_at": "2024-01-01T00:00:00",
"updated_at": "2024-01-01T00:00:00"
}
]
}
```
#### 指标详情获取
**接口定义**
- 方法：GET
- 路径：`/indicators/{indicator_id}`
- 权限：所有用户
**路径参数**
| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| indicator_id | int | 是 | 指标ID |
**响应结构**
```json
{
"code": 200,
"message": "success",
"data": {
"id": 1,
"name": "门诊量",
"code": "IND001",
"indicator_type": "quantity",
"weight": 1.0,
"max_score": 100.0,
"target_value": 500.0,
"unit": "人次",
"calculation_method": "实际值/目标值*100",
"description": "月度门诊接诊量",
"is_active": true,
"created_at": "2024-01-01T00:00:00",
"updated_at": "2024-01-01T00:00:00"
}
}
```
#### 指标创建
**接口定义**
- 方法：POST
- 路径：`/indicators`
- 权限：管理员/经理
**请求体结构**
```json
{
"name": "门诊量",
"code": "IND001",
"indicator_type": "quantity",
"weight": 1.0,
"max_score": 100.0,
"target_value": 500.0,
"unit": "人次",
"calculation_method": "实际值/目标值*100",
"description": "月度门诊接诊量"
}
```
**响应结构**
```json
{
"code": 200,
"message": "创建成功",
"data": {
"id": 1,
"name": "门诊量",
"code": "IND001",
"indicator_type": "quantity",
"weight": 1.0,
"max_score": 100.0,
"target_value": 500.0,
"unit": "人次",
"calculation_method": "实际值/目标值*100",
"description": "月度门诊接诊量",
"is_active": true,
"created_at": "2024-01-01T00:00:00",
"updated_at": "2024-01-01T00:00:00"
}
}
```
#### 指标更新
**接口定义**
- 方法：PUT
- 路径：`/indicators/{indicator_id}`
- 权限：管理员/经理
**请求体结构**
```json
{
"name": "更新后的指标名称",
"weight": 1.5,
"max_score": 120.0,
"is_active": false
}
```
**响应结构**
```json
{
"code": 200,
"message": "更新成功",
"data": {
"id": 1,
"name": "更新后的指标名称",
"code": "IND001",
"indicator_type": "quantity",
"weight": 1.5,
"max_score": 120.0,
"target_value": 500.0,
"unit": "人次",
"calculation_method": "实际值/目标值*100",
"description": "月度门诊接诊量",
"is_active": false,
"created_at": "2024-01-01T00:00:00",
"updated_at": "2024-01-01T00:00:00"
}
}
```
#### 指标删除
**接口定义**
- 方法：DELETE
- 路径：`/indicators/{indicator_id}`
- 权限：管理员/经理
**响应结构**
```json
{
"code": 200,
"message": "删除成功"
}
```
**章节来源**
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L20-L112)
- [docs/api.md](file://docs/api.md#L239-L296)
### 指标模板管理
#### 模板列表查询
**接口定义**
- 方法：GET
- 路径：`/templates`
- 权限：所有用户
**查询参数**
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|-------|------|------|--------|------|
| template_type | string | 否 | 无 | 模板类型过滤 |
| is_active | boolean | 否 | 无 | 是否启用过滤 |
| page | int | 是 | 1 | 页码 |
| page_size | int | 是 | 20 | 每页数量 |
#### 模板类型列表
**接口定义**
- 方法：GET
- 路径：`/templates/types`
- 权限：所有用户
**响应结构**
```json
{
"code": 200,
"message": "success",
"data": [
{"value": "general", "label": "通用模板"},
{"value": "surgical", "label": "手术临床科室"},
{"value": "nonsurgical_ward", "label": "非手术有病房科室"},
{"value": "nonsurgical_noward", "label": "非手术无病房科室"},
{"value": "medical_tech", "label": "医技科室"},
{"value": "nursing", "label": "护理单元"},
{"value": "admin", "label": "行政科室"},
{"value": "logistics", "label": "后勤科室"}
]
}
```
#### BSC维度列表
**接口定义**
- 方法：GET
- 路径：`/templates/dimensions`
- 权限：所有用户
**响应结构**
```json
{
"code": 200,
"message": "success",
"data": [
{"value": "financial", "label": "财务管理", "weight_range": "30%-40%"},
{"value": "customer", "label": "顾客服务", "weight_range": "25%-35%"},
{"value": "internal_process", "label": "内部流程", "weight_range": "20%-30%"},
{"value": "learning_growth", "label": "学习与成长", "weight_range": "5%-15%"}
]
}
```
**章节来源**
- [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py#L22-L74)
### 权重计算和评分规则
系统支持多种评分方法和权重计算方式：
#### 权重计算流程
```mermaid
flowchart TD
Start([开始计算]) --> GetIndicators["获取指标列表"]
GetIndicators --> CheckVeto{"是否包含一票否决"}
CheckVeto --> |是| ApplyVeto["应用一票否决规则"]
CheckVeto --> |否| CalcWeight["计算权重"]
ApplyVeto --> CalcWeight
CalcWeight --> CalcScore["计算指标得分"]
CalcScore --> CalcFinal["计算最终得分"]
CalcFinal --> End([结束])
```
**图表来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L134-L136)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L106-L154)
#### 评分规则
| 评分方法 | 适用场景 | 计算公式示例 |
|---------|----------|-------------|
| 目标参照法 | 有明确目标值的指标 | 得分 = min(100, 实际值/目标值 × 100) |
| 区间法 | 有合理区间范围的指标 | 根据区间位置线性计算得分 |
| 扣分法 | 违规或负面指标 | 得分 = 最高分 - 扣分标准 × 违规次数 |
| 加分法 | 表现优异的指标 | 得分 = 基础分 + 超额完成奖励 |
| 比较法 | 相对排名指标 | 根据相对排名计算得分 |
**章节来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L130-L133)
- [docs/详细设计.md](file://docs/详细设计.md#L96-L109)
### 指标模板使用方法
#### 模板导入流程
```mermaid
sequenceDiagram
participant Admin as "管理员"
participant API as "模板API"
participant Service as "模板服务"
participant DB as "数据库"
Admin->>API : POST /templates/import
API->>Service : import_template()
Service->>Service : 检查模板数据
Service->>DB : 查询现有指标
DB-->>Service : 查询结果
Service->>Service : 判断覆盖策略
Service->>DB : 批量插入指标
DB-->>Service : 插入结果
Service-->>API : 导入统计
API-->>Admin : 导入成功响应
```
**图表来源**
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L128-L141)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L106-L154)
#### 自定义指标创建流程
**步骤1：基础信息配置**
- 指标编码：唯一标识符，如 FIN001
- 指标名称：简洁明了的指标描述
- 指标类型：选择质量/数量/效率/服务/成本之一
- 权重设置：根据重要程度设置权重值
**步骤2：维度映射**
- 平衡计分卡维度：财务/客户/内部流程/学习成长
- 适用科室类型：选择适用的科室类型数组
**步骤3：计算规则配置**
- 计算方法：描述计算公式和步骤
- 目标值：设定期望达到的目标值
- 最高分值：设定指标满分对应的分值
**步骤4：数据验证**
- 数据来源：指定数据采集系统
- 扣分标准：设定违规或不达标时的扣分规则
- 一票否决：设置是否为强制性指标
**章节来源**
- [backend/init_indicator_templates.py](file://backend/init_indicator_templates.py#L22-L232)
- [docs/详细设计.md](file://docs/详细设计.md#L69-L81)
## 依赖关系分析
系统采用清晰的依赖层次结构，确保了模块间的松耦合：
```mermaid
graph TD
subgraph "外部依赖"
FastAPI[FastAPI框架]
SQLAlchemy[SQLAlchemy ORM]
PostgreSQL[PostgreSQL数据库]
end
subgraph "核心模块"
API[API路由层]
Service[服务层]
Model[模型层]
Schema[数据模式层]
end
subgraph "业务模块"
Indicator[指标管理]
Template[模板管理]
Assessment[考核管理]
PerformancePlan[绩效计划]
end
FastAPI --> API
SQLAlchemy --> Model
PostgreSQL --> Model
API --> Service
Service --> Model
Model --> Schema
Service --> Schema
API --> Indicator
API --> Template
API --> Assessment
API --> PerformancePlan
Indicator --> Template
Assessment --> PerformancePlan
```
**图表来源**
- [backend/app/main.py](file://backend/app/main.py#L15-L77)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L17)
- [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py#L1-L13)
**章节来源**
- [backend/app/main.py](file://backend/app/main.py#L15-L77)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L17)
## 性能考虑
### 数据库优化
系统采用了多项数据库优化策略：
1. **索引优化**
- 指标类型索引：加速指标类型查询
- 科室类型索引：优化科室相关查询
- 状态索引：快速筛选启用/停用指标
2. **查询优化**
- 分页查询：避免一次性加载大量数据
- 条件查询：支持多维度过滤查询
- 异步查询：使用异步数据库连接池
3. **缓存策略**
- 模板数据缓存：减少重复查询
- 权重计算缓存：避免重复计算
### 前端性能优化
1. **懒加载**
- 指标表格按需加载
- 模态框内容延迟渲染
2. **虚拟滚动**
- 大数据量表格的虚拟滚动支持
3. **请求去重**
- 避免重复的相同查询请求
## 故障排除指南
### 常见问题及解决方案
**问题1：指标编码重复**
- 现象：创建指标时报错"指标编码已存在"
- 解决方案：使用唯一的指标编码，遵循系统约定的编码规则
**问题2：权限不足**
- 现象：更新或删除指标返回403权限错误
- 解决方案：确保当前用户具有管理员或经理权限
**问题3：指标不存在**
- 现象：查询特定ID指标返回404错误
- 解决方案：确认指标ID是否正确，检查数据库中是否存在该记录
**问题4：模板导入失败**
- 现象：模板导入接口报错
- 解决方案：检查模板数据格式，确认必填字段完整
### 日志和监控
系统提供了完善的日志记录机制：
1. **访问日志**：记录所有API请求的详细信息
2. **错误日志**：捕获和记录系统异常
3. **性能日志**：监控数据库查询性能
4. **审计日志**：记录关键业务操作
**章节来源**
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L78-L81)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L96-L98)
## 结论
本考核指标管理接口实现了完整的平衡计分卡指标管理体系，具有以下特点：
1. **完整的指标生命周期管理**：从创建到删除的全流程支持
2. **灵活的分类体系**：支持多维度、多类型的指标分类
3. **强大的模板功能**：支持标准化模板的创建和导入
4. **完善的权限控制**：基于角色的细粒度权限管理
5. **高性能的架构设计**：采用异步处理和数据库优化
系统为医院绩效管理提供了坚实的技术基础，能够满足不同科室和岗位的差异化考核需求。
## 附录
### API接口完整列表
| 接口名称 | 方法 | 路径 | 权限 | 功能描述 |
|---------|------|------|------|----------|
| 获取指标列表 | GET | /indicators | 所有用户 | 查询所有考核指标 |
| 获取启用指标 | GET | /indicators/active | 所有用户 | 获取所有启用的指标 |
| 获取指标详情 | GET | /indicators/{id} | 所有用户 | 获取指定指标详情 |
| 创建指标 | POST | /indicators | 管理员/经理 | 创建新的考核指标 |
| 更新指标 | PUT | /indicators/{id} | 管理员/经理 | 更新现有指标信息 |
| 删除指标 | DELETE | /indicators/{id} | 管理员/经理 | 删除指定指标 |
| 获取模板列表 | GET | /templates | 所有用户 | 查询指标模板列表 |
| 获取模板详情 | GET | /templates/{id} | 所有用户 | 获取模板详细信息 |
| 创建模板 | POST | /templates | 管理员/经理 | 创建新的指标模板 |
| 更新模板 | PUT | /templates/{id} | 管理员/经理 | 更新模板信息 |
| 删除模板 | DELETE | /templates/{id} | 管理员/经理 | 删除指定模板 |
### 数据模型关系图
```mermaid
erDiagram
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
string calculation_method
string assessment_method
string deduction_standard
string data_source
string applicable_dept_types
boolean is_veto
boolean is_active
datetime created_at
datetime updated_at
}
INDICATOR_TEMPLATES {
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_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 ||--o{ TEMPLATE_INDICATORS : "包含"
INDICATOR_TEMPLATES ||--o{ TEMPLATE_INDICATORS : "定义"
```
**图表来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L147)
- [backend/app/models/models.py](file://backend/app/models/models.py#L387-L437)