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维度配置、权重设置等功能，为医院绩效考核提供了强大的技术支持。未来可以进一步扩展功能，如增加指标计算引擎、报表分析工具等，以满足更复杂的绩效管理需求。

394
.qoder/repowiki/zh/content/核心功能模块/工资核算管理.md Normal file
View File

@@ -0,0 +1,394 @@
# 工资核算管理
<cite>
**本文引用的文件**
- [salary.py](file://backend/app/api/v1/salary.py)
- [salary_service.py](file://backend/app/services/salary_service.py)
- [models.py](file://backend/app/models/models.py)
- [schemas.py](file://backend/app/schemas/schemas.py)
- [salary.js](file://frontend/src/api/salary.js)
- [Salary.vue](file://frontend/src/views/salary/Salary.vue)
- [001_initial.py](file://backend/alembic/versions/001_initial.py)
- [database.md](file://docs/database.md)
- [详细设计文档.md](file://docs/详细设计文档.md)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件为医院绩效系统的工资核算管理模块提供完整的技术文档。该模块负责：
- 绩效奖金计算算法与参数配置
- 工资记录的创建、更新与状态管理
- 基于考核结果的批量工资生成
- 工资确认与发放前的状态控制
- 工资条生成、历史记录查询与统计分析
- 数据来源、计算精度与异常处理机制说明
## 项目结构
工资核算管理模块由后端API路由、服务层、数据模型与前端界面组成，采用分层架构设计，确保职责分离与可扩展性。
```mermaid
graph TB
subgraph "前端"
FE_API["salary.js<br/>前端API封装"]
FE_View["Salary.vue<br/>工资管理视图"]
end
subgraph "后端"
API["salary.py<br/>API路由"]
Service["salary_service.py<br/>服务层"]
Models["models.py<br/>数据模型"]
Schemas["schemas.py<br/>数据模式"]
end
subgraph "数据库"
DB_Schema["001_initial.py<br/>迁移脚本"]
ER_Doc["database.md<br/>ER图"]
end
FE_API --> API
FE_View --> FE_API
API --> Service
Service --> Models
Service --> Schemas
Models --> DB_Schema
ER_Doc --> DB_Schema
```
**图表来源**
- [salary.py](file://backend/app/api/v1/salary.py#L1-L156)
- [salary_service.py](file://backend/app/services/salary_service.py#L1-L260)
- [models.py](file://backend/app/models/models.py#L205-L231)
- [schemas.py](file://backend/app/schemas/schemas.py#L272-L311)
- [salary.js](file://frontend/src/api/salary.js#L1-L42)
- [Salary.vue](file://frontend/src/views/salary/Salary.vue#L33-L245)
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L133-L154)
- [database.md](file://docs/database.md#L1-L95)
**章节来源**
- [salary.py](file://backend/app/api/v1/salary.py#L1-L156)
- [salary_service.py](file://backend/app/services/salary_service.py#L1-L260)
- [models.py](file://backend/app/models/models.py#L205-L231)
- [schemas.py](file://backend/app/schemas/schemas.py#L272-L311)
- [salary.js](file://frontend/src/api/salary.js#L1-L42)
- [Salary.vue](file://frontend/src/views/salary/Salary.vue#L33-L245)
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L133-L154)
- [database.md](file://docs/database.md#L1-L95)
## 核心组件
- API路由层：提供工资记录查询、详情、创建、更新、按考核生成、批量生成、确认与批量确认等REST接口。
- 服务层：实现业务逻辑，包括绩效奖金计算、工资记录生成、状态变更与批量操作。
- 数据模型层：定义工资记录、员工、考核等实体及其关系。
- 数据模式层：定义请求/响应数据结构，确保前后端数据一致性。
- 前端界面：展示工资记录列表、支持筛选与编辑，调用后端API完成操作。
**章节来源**
- [salary.py](file://backend/app/api/v1/salary.py#L20-L156)
- [salary_service.py](file://backend/app/services/salary_service.py#L14-L260)
- [models.py](file://backend/app/models/models.py#L205-L231)
- [schemas.py](file://backend/app/schemas/schemas.py#L272-L311)
- [salary.js](file://frontend/src/api/salary.js#L1-L42)
- [Salary.vue](file://frontend/src/views/salary/Salary.vue#L33-L245)
## 架构概览
工资核算管理遵循“前端-后端-数据库”的三层架构，通过API路由统一对外提供服务，服务层封装业务规则，数据模型映射数据库表结构。
```mermaid
sequenceDiagram
participant FE as "前端界面"
participant API as "API路由"
participant SVC as "服务层"
participant DB as "数据库"
FE->>API : 查询工资记录列表
API->>SVC : get_list(...)
SVC->>DB : 查询salary_records
DB-->>SVC : 返回记录集
SVC-->>API : 记录列表+总数
API-->>FE : JSON响应
FE->>API : 根据考核生成工资
API->>SVC : generate_from_assessment(...)
SVC->>DB : 读取staff/assessments
SVC->>SVC : calculate_performance_bonus(...)
SVC->>DB : 插入salary_records
DB-->>SVC : 提交事务
SVC-->>API : 新建记录ID
API-->>FE : 成功响应
```
**图表来源**
- [salary.py](file://backend/app/api/v1/salary.py#L20-L156)
- [salary_service.py](file://backend/app/services/salary_service.py#L21-L190)
- [models.py](file://backend/app/models/models.py#L205-L231)
**章节来源**
- [salary.py](file://backend/app/api/v1/salary.py#L20-L156)
- [salary_service.py](file://backend/app/services/salary_service.py#L21-L190)
- [models.py](file://backend/app/models/models.py#L205-L231)
## 详细组件分析
### 绩效奖金计算算法
- 计算公式
- 绩效奖金 = 绩效基数 × (绩效得分/100) × 绩效系数
- 其中：绩效基数为固定常量；绩效得分来自考核加权得分；绩效系数来自员工配置。
- 参数来源
- 绩效基数：服务层常量字段
- 绩效得分：来自已确认的考核记录的加权得分
- 绩效系数：来自员工表的performance_ratio字段
- 精度与约束
- 绩效基数保留两位小数
- 绩效得分与系数保留两位小数
- 数据库字段使用Numeric类型保证精度
```mermaid
flowchart TD
Start(["开始"]) --> LoadAssessment["加载已确认考核记录"]
LoadAssessment --> CheckExist{"是否存在？"}
CheckExist --> |否| ReturnNull["返回空"]
CheckExist --> |是| LoadStaff["加载员工信息"]
LoadStaff --> CalcBonus["计算绩效奖金<br/>基数×(得分/100)×系数"]
CalcBonus --> CreateRecord["创建工资记录<br/>合计=基本工资+奖金"]
CreateRecord --> Save["持久化到数据库"]
Save --> End(["结束"])
```
**图表来源**
- [salary_service.py](file://backend/app/services/salary_service.py#L127-L190)
- [models.py](file://backend/app/models/models.py#L205-L231)
**章节来源**
- [salary_service.py](file://backend/app/services/salary_service.py#L70-L75)
- [salary_service.py](file://backend/app/services/salary_service.py#L127-L190)
- [models.py](file://backend/app/models/models.py#L205-L231)
### 工资记录管理
- 字段定义
- 基本工资、绩效得分、绩效奖金、扣款、补贴、应发工资、状态、备注、创建/更新时间
- 状态流转
- pending（待确认）→ confirmed（已确认）
- 仅pending状态可更新与确认
- 计算规则
- 应发工资 = 基本工资 + 绩效奖金 + 补贴 - 扣款
- 更新时自动重新计算应发工资
```mermaid
classDiagram
class SalaryRecord {
+int id
+int staff_id
+int period_year
+int period_month
+float base_salary
+float performance_score
+float performance_bonus
+float deduction
+float allowance
+float total_salary
+string status
+text remark
+datetime created_at
+datetime updated_at
}
class Staff {
+int id
+string employee_id
+string name
+int department_id
+string position
+string title
+float base_salary
+float performance_ratio
+string status
+datetime hire_date
}
class Assessment {
+int id
+int staff_id
+int period_year
+int period_month
+string period_type
+float total_score
+float weighted_score
+string status
+int assessor_id
+int reviewer_id
+datetime submit_time
+datetime review_time
+text remark
}
SalaryRecord --> Staff : "外键"
Assessment --> Staff : "外键"
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L205-L231)
- [models.py](file://backend/app/models/models.py#L88-L114)
- [models.py](file://backend/app/models/models.py#L149-L179)
**章节来源**
- [models.py](file://backend/app/models/models.py#L205-L231)
- [schemas.py](file://backend/app/schemas/schemas.py#L272-L311)
- [salary_service.py](file://backend/app/services/salary_service.py#L77-L124)
### 批量工资生成与发放管理
- 单个生成
- 根据员工ID与年月，检查是否存在已确认的考核记录且无重复工资记录，然后生成工资记录
- 科室批量生成
- 遍历指定科室当月已确认考核的所有员工，逐个生成工资记录
- 批量确认
- 将指定年月（可选科室）下所有pending状态的工资记录批量置为confirmed
```mermaid
sequenceDiagram
participant Manager as "管理员/经理"
participant API as "API路由"
participant SVC as "服务层"
participant DB as "数据库"
Manager->>API : POST /salary/batch-generate?department_id&period_year&period_month
API->>SVC : batch_generate_for_department(...)
SVC->>DB : 查询已确认考核员工
loop 对每个员工
SVC->>SVC : generate_from_assessment(...)
SVC->>DB : 插入工资记录
end
SVC-->>API : 返回生成记录数
API-->>Manager : 成功响应
```
**图表来源**
- [salary.py](file://backend/app/api/v1/salary.py#L113-L129)
- [salary_service.py](file://backend/app/services/salary_service.py#L192-L219)
**章节来源**
- [salary.py](file://backend/app/api/v1/salary.py#L96-L129)
- [salary_service.py](file://backend/app/services/salary_service.py#L192-L259)
### 工资条生成、历史记录查询与统计分析
- 工资条生成
- 通过“根据考核生成”或“批量生成”生成工资记录后，可在前端查看与编辑
- 历史记录查询
- 支持按员工、科室、年月、状态筛选，分页显示
- 统计分析
- 前端报表页面提供科室统计、排名等展示（与工资记录数据联动）
```mermaid
sequenceDiagram
participant User as "用户"
participant FE as "前端界面"
participant API as "API路由"
participant SVC as "服务层"
participant DB as "数据库"
User->>FE : 输入筛选条件
FE->>API : GET /salary?page&page_size&filters...
API->>SVC : get_list(...)
SVC->>DB : 查询salary_records
DB-->>SVC : 记录集+总数
SVC-->>API : 返回数据
API-->>FE : 渲染表格
```
**图表来源**
- [salary.py](file://backend/app/api/v1/salary.py#L20-L51)
- [salary_service.py](file://backend/app/services/salary_service.py#L21-L58)
- [Salary.vue](file://frontend/src/views/salary/Salary.vue#L190-L207)
**章节来源**
- [salary.py](file://backend/app/api/v1/salary.py#L20-L51)
- [salary_service.py](file://backend/app/services/salary_service.py#L21-L58)
- [Salary.vue](file://frontend/src/views/salary/Salary.vue#L33-L245)
### 数据来源、计算精度与异常处理
- 数据来源
- 员工基本信息与绩效系数来自员工表
- 考核记录来自考核表，需为已确认状态
- 工资记录来自工资记录表
- 计算精度
- 基本工资、绩效奖金、扣款、补贴、应发工资均使用Numeric(10,2)
- 绩效得分使用Numeric(5,2)
- 绩效基数为浮点型常量
- 异常处理
- 未找到记录或状态不允许时返回错误
- 重复生成工资记录时拒绝
- 更新时仅允许pending状态
**章节来源**
- [salary_service.py](file://backend/app/services/salary_service.py#L104-L124)
- [salary_service.py](file://backend/app/services/salary_service.py#L127-L190)
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L133-L154)
## 依赖关系分析
- API路由依赖服务层进行业务处理
- 服务层依赖数据模型与数据模式进行数据访问与校验
- 数据模型依赖SQLAlchemy ORM映射数据库表
- 前端通过API封装调用后端接口
```mermaid
graph LR
FE["前端"] --> API["API路由"]
API --> SVC["服务层"]
SVC --> MODELS["数据模型"]
SVC --> SCHEMAS["数据模式"]
MODELS --> DB["数据库"]
```
**图表来源**
- [salary.py](file://backend/app/api/v1/salary.py#L1-L17)
- [salary_service.py](file://backend/app/services/salary_service.py#L1-L12)
- [models.py](file://backend/app/models/models.py#L1-L14)
- [schemas.py](file://backend/app/schemas/schemas.py#L1-L8)
**章节来源**
- [salary.py](file://backend/app/api/v1/salary.py#L1-L17)
- [salary_service.py](file://backend/app/services/salary_service.py#L1-L12)
- [models.py](file://backend/app/models/models.py#L1-L14)
- [schemas.py](file://backend/app/schemas/schemas.py#L1-L8)
## 性能考虑
- 查询优化
- 工资记录表对staff_id与(period_year, period_month)建立索引，提升筛选与分页性能
- 批量操作
- 批量生成与批量确认采用批量查询与批量更新，减少事务开销
- 数据精度
- 使用Numeric类型避免浮点运算误差累积
- 前端渲染
- 列表分页与按需加载，减轻前端渲染压力
**章节来源**
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L153-L154)
- [salary_service.py](file://backend/app/services/salary_service.py#L21-L58)
- [salary_service.py](file://backend/app/services/salary_service.py#L234-L259)
## 故障排除指南
- 无法生成工资
- 检查是否存在已确认的考核记录
- 确认是否已存在同员工、同年月的工资记录
- 更新失败
- 仅pending状态可更新
- 检查字段范围约束（如非负数）
- 批量生成无结果
- 确认科室当月考核状态是否为已确认
- 前端显示异常
- 检查筛选条件与分页参数
- 确认后端接口返回格式
**章节来源**
- [salary_service.py](file://backend/app/services/salary_service.py#L127-L190)
- [salary_service.py](file://backend/app/services/salary_service.py#L104-L124)
- [salary.py](file://backend/app/api/v1/salary.py#L96-L129)
## 结论
工资核算管理模块通过清晰的分层架构与严谨的数据模型，实现了从绩效计算到工资发放的全流程管理。模块具备良好的扩展性与可维护性，能够满足医院绩效工资核算的复杂需求，并为后续的功能增强（如税务处理、多币种支持等）提供了坚实基础。
## 附录
- 数据库ER图与表结构参考
- [database.md](file://docs/database.md#L1-L95)
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L133-L154)
- 详细设计文档
- [详细设计文档.md](file://docs/详细设计文档.md#L642-L662)

387
.qoder/repowiki/zh/content/核心功能模块/数据分析报表.md Normal file
View File

@@ -0,0 +1,387 @@
# 数据分析报表
<cite>
**本文引用的文件**
- [后端统计API stats.py](file://backend/app/api/v1/stats.py)
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py)
- [前端报表页面 Reports.vue](file://frontend/src/views/reports/Reports.vue)
- [前端统计API封装 stats.js](file://frontend/src/api/stats.js)
- [数据模型 models.py](file://backend/app/models/models.py)
- [数据库连接 database.py](file://backend/app/core/database.py)
- [API路由器 __init__.py](file://backend/app/api/v1/__init__.py)
- [数据库设计文档 database.md](file://docs/database.md)
- [初始化指标模板 init_templates.py](file://backend/app/scripts/init_templates.py)
- [初始化指标模板脚本 init_indicator_templates.py](file://backend/init_indicator_templates.py)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件面向“医院绩效系统”的数据分析报表模块，系统化阐述BSC维度分析、科室绩效统计、趋势分析、绩效排名、指标完成度等核心功能。文档覆盖数据聚合算法、图表展示组件、报表生成机制、多维度统计分析、数据可视化与导出能力，并解释数据更新机制、缓存策略与性能优化方案。同时提供分析指标定义、计算方法与展示样式说明，帮助开发者与运维人员快速理解并扩展系统能力。
## 项目结构
报表模块由后端FastAPI接口、SQLAlchemy异步ORM服务层、前端Vue组件与ECharts图表构成，遵循前后端分离与职责清晰的设计原则。
```mermaid
graph TB
subgraph "前端"
FE_Report["Reports.vue<br/>报表页面"]
FE_API["stats.js<br/>API封装"]
end
subgraph "后端"
BE_Router["API路由器<br/>__init__.py"]
BE_StatsAPI["统计API<br/>stats.py"]
BE_Service["统计服务<br/>stats_service.py"]
BE_Models["数据模型<br/>models.py"]
BE_DB["数据库连接<br/>database.py"]
end
FE_Report --> FE_API
FE_API --> BE_Router
BE_Router --> BE_StatsAPI
BE_StatsAPI --> BE_Service
BE_Service --> BE_Models
BE_Service --> BE_DB
```
**图表来源**
- [API路由器 __init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L1-L242)
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
- [数据模型 models.py](file://backend/app/models/models.py#L1-L438)
- [数据库连接 database.py](file://backend/app/core/database.py#L1-L39)
- [前端报表页面 Reports.vue](file://frontend/src/views/reports/Reports.vue#L1-L367)
- [前端统计API封装 stats.js](file://frontend/src/api/stats.js#L1-L43)
**章节来源**
- [API路由器 __init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L1-L242)
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
- [数据模型 models.py](file://backend/app/models/models.py#L1-L438)
- [数据库连接 database.py](file://backend/app/core/database.py#L1-L39)
- [前端报表页面 Reports.vue](file://frontend/src/views/reports/Reports.vue#L1-L367)
- [前端统计API封装 stats.js](file://frontend/src/api/stats.js#L1-L43)
## 核心组件
- 统计API接口：提供BSC维度分析、科室绩效统计、趋势分析、绩效排名、指标完成度、周期统计、关键指标仪表盘、收支趋势等接口。
- 统计服务层：封装复杂聚合逻辑，负责SQL查询、分组统计、跨表联接与结果组装。
- 数据模型：定义科室、员工、指标、考核、明细、工资等实体及其关系。
- 前端报表页面：集成ECharts图表，支持多视图联动与交互式筛选。
- 数据库连接：异步SQLAlchemy引擎与会话管理，确保并发安全与事务一致性。
**章节来源**
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L17-L242)
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L16-L300)
- [数据模型 models.py](file://backend/app/models/models.py#L62-L231)
- [前端报表页面 Reports.vue](file://frontend/src/views/reports/Reports.vue#L1-L367)
- [数据库连接 database.py](file://backend/app/core/database.py#L1-L39)
## 架构总览
后端采用FastAPI + SQLAlchemy异步ORM，前端使用Vue + ECharts，通过REST接口进行数据交互。统计服务层对多表进行联接与聚合，输出标准化数据结构供前端渲染。
```mermaid
sequenceDiagram
participant FE as "前端报表页面"
participant API as "统计API(stats.py)"
participant SVC as "统计服务(stats_service.py)"
participant DB as "数据库连接(database.py)"
FE->>API : GET /stats/department?year&month
API->>SVC : get_department_stats(db, year, month)
SVC->>DB : 异步SQL查询(联接 : departments/staff/assessments)
DB-->>SVC : 聚合结果集
SVC-->>API : 标准化科室统计列表
API-->>FE : JSON响应(data : 列表)
```
**图表来源**
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L36-L49)
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L75-L146)
- [数据库连接 database.py](file://backend/app/core/database.py#L28-L39)
## 详细组件分析
### BSC维度分析
- 功能说明：按财务、客户、内部流程、学习成长四个维度统计得分、权重、指标数量与平均分。
- 数据聚合算法：
- 过滤条件：仅统计最终确认状态的考核记录；可按年、月、科室过滤。
- 聚合逻辑：按维度分组，计算加权总分与总权重，得到平均分。
- 展示样式：返回维度字典与统计周期字符串，前端可直接映射到图表或表格。
```mermaid
flowchart TD
Start(["开始"]) --> BuildCond["构建过滤条件<br/>状态=FINALIZED<br/>可选: 年/月/科室"]
BuildCond --> JoinTables["联接: 指标→明细→考核"]
JoinTables --> GroupByDim["按BSC维度分组"]
GroupByDim --> CalcAvg["计算: 加权总分/总权重"]
CalcAvg --> Output["输出: 维度统计+周期"]
Output --> End(["结束"])
```
**图表来源**
- [统计服务 get_bsc_dimension_stats](file://backend/app/services/stats_service.py#L19-L72)
**章节来源**
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L17-L33)
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L19-L72)
### 科室绩效统计
- 功能说明：按科室汇总员工得分，计算平均分、最大/最小分、员工列表，并按平均分降序排列。
- 数据聚合算法：
- 聚合字段：科室ID、名称、类型、员工数、总分、平均分、最大/最小分、员工明细。
- 排序规则：按平均分降序。
- 展示样式：前端表格展示科室统计，支持奖金列（若存在）。
```mermaid
flowchart TD
S(["开始"]) --> Filter["过滤: FINALIZED+年+月"]
Filter --> Join["联接: 科室→员工→考核"]
Join --> Group["按科室分组聚合"]
Group --> Compute["计算: 员工数/总分/平均分/最值"]
Compute --> Sort["按平均分降序"]
Sort --> Out(["输出: 科室统计列表"])
Out --> E(["结束"])
```
**图表来源**
- [统计服务 get_department_stats](file://backend/app/services/stats_service.py#L75-L146)
**章节来源**
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L36-L49)
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L75-L146)
### 趋势分析（月度）
- 功能说明：按月统计平均分与加权平均分，支持指定最近N个月与按科室过滤。
- 数据聚合算法：
- 时间范围：若指定年份，计算最近months个月（跨年处理）。
- 聚合字段：月份、平均分、加权平均分、记录数。
- 展示样式：折线/柱状组合图，双轴显示平均分与奖金（若存在）。
```mermaid
flowchart TD
TStart(["开始"]) --> TFilter["过滤: FINALIZED+年/月范围"]
TFilter --> TJoin["联接: 员工→考核"]
TJoin --> TGroup["按月分组聚合"]
TGroup --> TAgg["计算: 平均分/加权平均分/数量"]
TAgg --> TSort["按月升序"]
TSort --> TOut(["输出: 月度趋势列表"])
TOut --> TE(["结束"])
```
**图表来源**
- [统计服务 get_trend_stats](file://backend/app/services/stats_service.py#L149-L199)
**章节来源**
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L52-L70)
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L149-L199)
### 绩效排名
- 功能说明：提供员工与科室的绩效排名，支持限制返回条数。
- 数据聚合算法：
- 员工排名：按加权得分降序取前N名。
- 科室排名：先按科室汇总平均分，再整体降序取前N名。
- 展示样式：表格排名，突出前三名。
```mermaid
sequenceDiagram
participant API as "统计API"
participant SVC as "统计服务"
participant DB as "数据库"
API->>SVC : get_ranking_stats(year, month, limit)
SVC->>DB : 查询最终确认的考核记录
DB-->>SVC : 结果集(员工ID/姓名/部门/得分)
SVC-->>API : 排名列表(含排名序号)
API-->>API : 返回JSON
```
**图表来源**
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L210-L224)
- [统计服务 get_ranking_stats](file://backend/app/services/stats_service.py#L202-L244)
**章节来源**
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L186-L207)
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L210-L224)
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L202-L244)
### 指标完成度
- 功能说明：按指标统计平均分、最大/最小分、完成率与样本数。
- 数据聚合算法：
- 过滤条件：最终确认状态；可按年、月、指标过滤。
- 计算完成率：平均分/目标值×100%，上限100%。
- 展示样式：指标列表卡片，完成率进度条或数值。
**章节来源**
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L227-L241)
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L247-L299)
### 周期统计与关键指标仪表盘
- 周期统计：汇总当期总科室数、总员工数、平均分等。
- 关键指标仪表盘：床位使用率、药占比、材料占比、患者满意度等（演示数据）。
- 展示样式：概览卡片与仪表盘组件。
**章节来源**
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L93-L125)
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L128-L153)
### 收支趋势
- 功能说明：按月统计收入、支出、利润趋势。
- 展示样式：折线图，支持选择最近6/12个月。
**章节来源**
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L156-L183)
### 前端报表页面与图表
- 页面组件：筛选器、统计概览卡片、科室对比图、绩效分布饼图、科室统计表、员工排名表。
- 图表实现：ECharts初始化、窗口自适应、双轴图表、饼图标签与强调。
- 数据加载：并行请求多个接口，统一更新图表。
```mermaid
sequenceDiagram
participant View as "Reports.vue"
participant API as "stats.js"
participant BE as "后端统计API"
View->>View : 选择统计周期(年-月)
View->>API : 并行调用 : 周期统计/科室统计/员工排名
API->>BE : GET /stats/period
API->>BE : GET /stats/department
API->>BE : GET /stats/ranking
BE-->>API : JSON响应
API-->>View : 数据对象
View->>View : 更新ECharts图表
```
**图表来源**
- [前端报表页面 Reports.vue](file://frontend/src/views/reports/Reports.vue#L134-L171)
- [前端统计API封装 stats.js](file://frontend/src/api/stats.js#L1-L43)
**章节来源**
- [前端报表页面 Reports.vue](file://frontend/src/views/reports/Reports.vue#L1-L367)
- [前端统计API封装 stats.js](file://frontend/src/api/stats.js#L1-L43)
## 依赖关系分析
```mermaid
classDiagram
class StatsAPI {
+get_bsc_dimension_stats()
+get_department_stats()
+get_trend_stats()
+get_ranking_stats()
+get_completion_stats()
+get_period_stats()
+get_kpi_gauges()
+get_finance_trend()
+get_department_ranking()
}
class StatsService {
+get_bsc_dimension_stats()
+get_department_stats()
+get_trend_stats()
+get_ranking_stats()
+get_completion_stats()
}
class Models {
+Assessment
+AssessmentDetail
+Indicator
+Department
+Staff
+BSCDimension
+AssessmentStatus
}
class Database {
+AsyncEngine
+AsyncSession
}
StatsAPI --> StatsService : "调用"
StatsService --> Models : "查询/联接"
StatsService --> Database : "使用会话"
```
**图表来源**
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L1-L242)
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
- [数据模型 models.py](file://backend/app/models/models.py#L117-L178)
- [数据库连接 database.py](file://backend/app/core/database.py#L1-L39)
**章节来源**
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L1-L242)
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
- [数据模型 models.py](file://backend/app/models/models.py#L117-L178)
- [数据库连接 database.py](file://backend/app/core/database.py#L1-L39)
## 性能考虑
- 异步ORM：使用SQLAlchemy异步引擎与会话，提升并发吞吐与响应速度。
- 索引优化：模型中已为常用查询字段建立索引（如考核记录的年月、状态、员工ID等），建议结合实际查询模式评估是否需要复合索引。
- 聚合优化：统计服务对大表联接与分组聚合，建议：
- 限定查询时间范围（如最近6/12个月）。
- 对高频查询增加物化视图或缓存中间结果。
- 使用LIMIT限制排名条数，避免超大数据集排序。
- 前端优化：ECharts实例复用与窗口resize监听，减少重绘开销；图表数据按需更新，避免全量刷新。
- 缓存策略：可引入Redis缓存热点报表（如当月周期统计、Top N排名），设置合理TTL与失效策略，降低数据库压力。
- 数据更新机制：建议在考核状态变更时触发增量更新任务，或定时任务批量刷新报表缓存。
[本节为通用性能指导，不直接分析具体文件]
## 故障排查指南
- 接口返回空数据或异常：
- 检查过滤条件（年、月、科室）是否正确传入。
- 确认考核状态为最终确认（FINALIZED）。
- 图表不显示或空白：
- 检查ECharts实例初始化与容器尺寸。
- 确认数据格式与字段名一致（如avg_score、total_bonus）。
- 数据库连接问题：
- 查看异步会话生命周期与异常回滚逻辑。
- 检查数据库URL与连接池配置。
- 指标模板缺失：
- 确认初始化脚本已执行，模板与指标数据完整。
**章节来源**
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
- [数据库连接 database.py](file://backend/app/core/database.py#L28-L39)
- [前端报表页面 Reports.vue](file://frontend/src/views/reports/Reports.vue#L173-L181)
## 结论
本模块以清晰的分层架构实现了BSC维度分析、科室统计、趋势与排名等核心报表功能。通过异步ORM与ECharts的结合，既保证了性能也提供了良好的用户体验。建议后续完善缓存与物化视图、扩展更多关键指标仪表盘与导出能力，并持续优化索引与查询计划以应对更大规模数据。
[本节为总结性内容，不直接分析具体文件]
## 附录
### 分析指标定义与计算方法
- BSC维度得分：按指标权重加权求和，再除以总权重得到平均分。
- 科室平均分：科室内员工加权得分的算术平均。
- 趋势数据：按月分组的平均分与加权平均分。
- 指标完成率：平均分/目标值×100%，上限100%。
- 关键指标（演示）：床位使用率、药占比、材料占比、患者满意度。
**章节来源**
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L20-L72)
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L75-L146)
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L149-L199)
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L247-L299)
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L128-L153)
### 数据模型与索引
- 关键实体：Department、Staff、Assessment、AssessmentDetail、Indicator、SalaryRecord。
- 索引位置：考核记录、员工、指标、科室等表均有相应索引，加速查询与排序。
**章节来源**
- [数据模型 models.py](file://backend/app/models/models.py#L62-L231)
- [数据库设计文档 database.md](file://docs/database.md#L1-L95)
### 指标模板与BSC维度
- 模板类型：通用模板与按科室类型的模板（如手术、非手术、医技、护理、行政等）。
- 维度权重：模板可配置财务、客户、内部流程、学习成长维度权重。
**章节来源**
- [初始化指标模板 init_templates.py](file://backend/app/scripts/init_templates.py#L81-L102)
- [初始化指标模板脚本 init_indicator_templates.py](file://backend/init_indicator_templates.py#L234-L266)

440
.qoder/repowiki/zh/content/核心功能模块/核心功能模块.md Normal file
View File

@@ -0,0 +1,440 @@
# 核心功能模块
<cite>
**本文引用的文件**
- [backend/app/main.py](file://backend/app/main.py)
- [backend/app/core/config.py](file://backend/app/core/config.py)
- [backend/app/core/database.py](file://backend/app/core/database.py)
- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.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/services/__init__.py](file://backend/app/services/__init__.py)
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py)
- [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/assessments.py](file://backend/app/api/v1/assessments.py)
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py)
- [frontend/src/router/index.js](file://frontend/src/router/index.js)
- [frontend/src/main.js](file://frontend/src/main.js)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件面向医院绩效系统的核心功能模块，围绕用户认证、基础数据管理、绩效考核管理、工资核算管理、数据分析报表、经济核算与系统管理进行系统化说明。文档覆盖业务流程、前后端交互、权限控制、数据流转与状态管理，并提供模块间集成关系、接口调用说明与常见问题排查建议。
## 项目结构
系统采用前后端分离架构：
- 后端：FastAPI + SQLAlchemy 2.0 异步 ORM，PostgreSQL 数据库，提供 REST API。
- 前端：Vue 3 + Element Plus，基于路由守卫实现登录态校验与页面导航。
```mermaid
graph TB
FE["前端应用<br/>Vue 3 + Element Plus"] --> BE["后端应用<br/>FastAPI"]
BE --> DB["数据库<br/>PostgreSQL"]
BE --> AUTH["认证模块<br/>JWT"]
BE --> SVC["服务层<br/>业务逻辑"]
BE --> MODELS["模型层<br/>SQLAlchemy 映射"]
BE --> SCHEMAS["数据模式<br/>Pydantic 校验"]
```
图表来源
- [backend/app/main.py](file://backend/app/main.py#L15-L77)
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L20)
- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)
章节来源
- [backend/app/main.py](file://backend/app/main.py#L15-L77)
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)
- [frontend/src/main.js](file://frontend/src/main.js#L1-L24)
## 核心组件
- 应用入口与中间件：创建 FastAPI 实例、注册路由前缀、CORS、健康检查与全局异常处理。
- 配置中心：应用名、版本、API 前缀、数据库连接、JWT 密钥与过期时间、跨域白名单、分页参数等。
- 数据库层：异步引擎与会话工厂、模型基类、数据库依赖注入。
- API 路由聚合：按模块注册认证、基础数据、考核、工资、统计、财务、计划、菜单、模板等路由。
- 数据模型：涵盖科室、员工、指标、考核、工资、用户、计划、菜单、模板等实体与枚举。
- 数据模式：Pydantic 模型用于请求/响应校验与序列化。
- 服务层：封装业务逻辑（如部门、员工、指标、考核、工资、统计等服务）。
- 前端路由：登录、工作台、基础数据、考核、工资、报表、经济核算、绩效计划、系统管理等页面与导航守卫。
章节来源
- [backend/app/main.py](file://backend/app/main.py#L15-L77)
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L438)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L49-L743)
- [backend/app/services/__init__.py](file://backend/app/services/__init__.py#L1-L16)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)
- [frontend/src/main.js](file://frontend/src/main.js#L1-L24)
## 架构总览
系统采用“前端路由 + 后端 API + 数据库”的三层架构。前端通过路由守卫拦截未登录访问；后端通过依赖注入获取数据库会话，统一返回标准化响应结构；服务层负责业务规则与状态机推进；模型层定义实体关系与约束；模式层确保输入输出一致性。
```mermaid
sequenceDiagram
participant U as "用户"
participant FE as "前端应用"
participant API as "后端API"
participant SVC as "服务层"
participant DB as "数据库"
U->>FE : 访问受保护页面
FE->>FE : 路由守卫检查本地token
alt 未登录
FE-->>U : 跳转登录页
else 已登录
FE->>API : 发起带token的请求
API->>SVC : 调用业务方法
SVC->>DB : 执行查询/写入
DB-->>SVC : 返回结果
SVC-->>API : 返回业务结果
API-->>FE : 标准化响应
FE-->>U : 渲染页面/提示
end
```
图表来源
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L103-L113)
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L20-L40)
- [backend/app/core/database.py](file://backend/app/core/database.py#L28-L39)
## 详细组件分析
### 用户认证系统
- 功能点
- 登录：用户名/密码校验，生成访问令牌。
- 注册：用户名唯一性校验，密码加密存储，返回用户信息。
- 当前用户：基于 JWT 获取当前激活用户信息。
- 权限与安全
- 使用依赖注入获取当前用户，禁用账户不可登录。
- JWT 过期时间与密钥在配置中集中管理。
- 接口与流程
- 登录接口接收表单数据，校验失败抛出 401/403。
- 注册接口校验用户名唯一性，成功返回自定义响应结构。
- 当前用户接口返回用户基本信息。
```mermaid
sequenceDiagram
participant C as "客户端"
participant A as "认证API"
participant S as "安全工具"
participant DB as "数据库"
C->>A : POST /api/v1/auth/login
A->>DB : 查询用户
DB-->>A : 用户对象
A->>S : 校验密码
S-->>A : 校验结果
A->>S : 生成访问令牌
S-->>A : 返回令牌
A-->>C : {access_token, token_type}
C->>A : POST /api/v1/auth/register
A->>DB : 检查用户名唯一
DB-->>A : 结果
A->>S : 密码哈希
S-->>A : 哈希值
A->>DB : 创建用户
DB-->>A : 新用户
A-->>C : {code, message, data}
```
图表来源
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L66)
- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L200)
章节来源
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L74)
- [backend/app/core/config.py](file://backend/app/core/config.py#L23-L26)
### 基础数据管理
- 科室管理
- 列表/树形结构查询、详情、创建、更新、删除。
- 创建/更新需管理员或经理权限；删除受父子关系约束。
- 员工管理
- 列表/详情、创建、更新、删除、按科室查询。
- 创建/更新需管理员或经理权限；工号唯一。
- 数据模型与关系
- Department 与 Staff 多对一/一对多；Department 支持父子关系树。
- Staff 关联 Department、Assessment、SalaryRecord。
```mermaid
classDiagram
class Department {
+int id
+string name
+string code
+enum dept_type
+int parent_id
+int level
+int sort_order
+bool is_active
+string description
+datetime created_at
+datetime updated_at
}
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
+enum status
+datetime hire_date
+datetime created_at
+datetime updated_at
}
Department "1" o-- "many" Staff : "back_populates"
```
图表来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L114)
章节来源
- [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/models/models.py](file://backend/app/models/models.py#L62-L114)
### 绩效考核管理
- 功能点
- 列表/详情、创建、更新、提交、审核、确认、批量创建。
- 支持按员工、科室、年度、月份、状态筛选。
- 状态机
- 草稿 → 已提交 → 已审核 → 已确认/已驳回。
- 流程图（提交→审核→确认）
```mermaid
flowchart TD
Start(["开始"]) --> Create["创建考核记录"]
Create --> Submit["提交考核"]
Submit --> Review{"审核通过？"}
Review --> |是| Finalize["确认考核"]
Review --> |否| Reject["已驳回"]
Finalize --> End(["结束"])
Reject --> End
```
图表来源
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L105-L145)
- [backend/app/models/models.py](file://backend/app/models/models.py#L45-L51)
章节来源
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L20-L166)
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L178)
### 工资核算管理
- 功能点
- 列表/详情、创建、更新、根据考核生成、批量生成、确认、批量确认。
- 支持按员工、科室、年度、月份、状态筛选。
- 业务规则
- 工资记录由已确认的考核生成；重复生成会报错。
- 确认后方可进入后续发放流程。
- 接口时序（批量生成）
```mermaid
sequenceDiagram
participant FE as "前端"
participant API as "工资API"
participant SVC as "工资服务"
participant ASSESS as "考核服务"
participant DB as "数据库"
FE->>API : POST /api/v1/salary/batch-generate
API->>SVC : 批量生成
SVC->>ASSESS : 查询已确认考核
ASSESS->>DB : 查询
DB-->>ASSESS : 考核结果
SVC->>DB : 写入工资记录
DB-->>SVC : 成功
SVC-->>API : 工资记录集合
API-->>FE : {code, message, data}
```
图表来源
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L113-L129)
- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py#L1-L200)
章节来源
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L20-L156)
- [backend/app/models/models.py](file://backend/app/models/models.py#L205-L230)
### 数据分析报表
- 统计维度
- 科室统计：员工数、平均分、总奖金。
- 周期统计：总人数、已考核人数、平均分、总奖金、分数分布。
- 趋势数据：按周期的平均分与总奖金。
- 用途
- 支持管理层决策与绩效对比分析。
章节来源
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L349-L374)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L1-L200)
### 经济核算管理
- 功能点
- 收入/支出记录：支持按类别、金额、周期、来源、备注管理。
- 科室收支结余：按科室与周期汇总收入、支出与结余。
- 类别汇总：按类别统计金额。
- 类别枚举
- 收入：检查费、检验费、放射费、床位费、护理费、治疗费、手术费、注射费、吸氧费、其他。
- 支出：材料费、人员支出、维修费、水电费、其他。
章节来源
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L407-L460)
- [backend/app/models/models.py](file://backend/app/models/models.py#L443-L452)
### 系统管理
- 菜单管理
- 支持菜单/按钮类型、父子关系、排序、可见性、权限标识等。
- 提供树形结构与扁平列表。
- 权限控制
- 菜单与按钮权限标识可用于前端路由与按钮级权限控制。
- 前端路由
- 登录、工作台、基础数据、考核、工资、报表、经济核算、绩效计划、系统管理（菜单管理）等。
```mermaid
graph TB
subgraph "前端路由"
R1["/login"]
R2["/dashboard"]
R3["/departments"]
R4["/staff"]
R5["/assessments"]
R6["/salary"]
R7["/reports"]
R8["/finance"]
R9["/plans"]
R10["/system/menus"]
end
subgraph "后端路由"
A1["/auth/*"]
A2["/departments/*"]
A3["/staff/*"]
A4["/assessments/*"]
A5["/salary/*"]
A6["/stats/*"]
A7["/finance/*"]
A8["/performance_plans/*"]
A9["/menus/*"]
A10["/templates/*"]
end
R1 --> A1
R2 --> A2
R3 --> A2
R4 --> A3
R5 --> A4
R6 --> A5
R7 --> A6
R8 --> A7
R9 --> A8
R10 --> A9
```
图表来源
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L3-L96)
- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
章节来源
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)
- [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py#L1-L200)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L590-L638)
## 依赖分析
- 组件耦合
- API 层仅依赖服务层与数据库依赖注入，职责清晰。
- 服务层依赖模型层与数据库会话，封装业务规则。
- 模型层定义实体与关系，约束数据完整性。
- 模式层统一请求/响应结构，便于前后端契约一致。
- 外部依赖
- FastAPI、SQLAlchemy 2.0、PostgreSQL、Element Plus、Vue Router。
- 潜在循环依赖
- 当前结构通过“API → 服务 → 模型/数据库”单向依赖，未见循环。
```mermaid
graph LR
API["API 路由"] --> SVC["服务层"]
SVC --> MODELS["数据模型"]
MODELS --> DB["数据库"]
API --> SCHEMAS["数据模式"]
API --> FE["前端路由"]
```
图表来源
- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
- [backend/app/services/__init__.py](file://backend/app/services/__init__.py#L1-L16)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L438)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L49-L743)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)
章节来源
- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
- [backend/app/services/__init__.py](file://backend/app/services/__init__.py#L1-L16)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L438)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L49-L743)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)
## 性能考虑
- 数据库连接池：通过配置项设置池大小与溢出，避免高并发下的连接瓶颈。
- 异步 I/O：使用 SQLAlchemy 异步引擎与会话，提升并发吞吐。
- 分页与索引：API 默认分页参数与模型索引（如科室类型、状态、周期等）有助于查询性能。
- 前端缓存：路由守卫减少无效请求，结合后端分页降低传输压力。
- 建议
- 对高频查询字段增加复合索引。
- 控制一次性批量操作规模，必要时引入任务队列异步生成工资。
## 故障排查指南
- 登录失败
- 确认用户名/密码正确且账户启用；检查后端日志与异常处理器输出。
- 创建失败（科室/员工）
- 编码/工号唯一性冲突；检查是否存在重复记录。
- 更新/删除受限
- 需管理员或经理权限；确认当前用户角色与权限标识。
- 考核状态异常
- 仅允许在特定状态下进行提交/审核/确认；检查状态机流转。
- 工资生成失败
- 未找到已确认的考核记录或已存在同周期工资记录；检查考核状态与重复生成逻辑。
- 前端路由跳转
- 未登录自动跳转登录页；检查本地 token 是否存在。
章节来源
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L30-L34)
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L74-L77)
- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L75-L78)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L100-L101)
- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L104-L109)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L103-L113)
## 结论
本系统以清晰的模块划分与标准化的数据契约支撑医院绩效管理全流程：从基础数据维护到绩效考核、工资核算、经济统计与系统管理。通过前后端路由与权限控制、状态机与业务规则约束，确保流程可控、数据一致。建议持续完善索引策略、批量任务异步化与前端权限颗粒度，进一步提升性能与可用性。
## 附录
- 配置项摘要
- 应用名、版本、API 前缀、调试开关、数据库 URL、连接池参数、JWT 密钥与过期时间、跨域白名单、默认/最大分页大小。
- 数据模型概览
- 科室、员工、指标、考核、工资、用户、计划、菜单、模板等实体与枚举。
- 响应结构
- 统一的 code/message/data/total/page/page_size 结构，便于前端统一处理。
章节来源
- [backend/app/core/config.py](file://backend/app/core/config.py#L12-L33)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L438)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L49-L61)
- [backend/app/main.py](file://backend/app/main.py#L54-L56)

339
.qoder/repowiki/zh/content/核心功能模块/用户认证系统.md Normal file
View File

@@ -0,0 +1,339 @@
# 用户认证系统
<cite>
**本文引用的文件**
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py)
- [backend/app/core/security.py](file://backend/app/core/security.py)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py)
- [backend/app/models/models.py](file://backend/app/models/models.py)
- [backend/app/core/config.py](file://backend/app/core/config.py)
- [backend/app/main.py](file://backend/app/main.py)
- [frontend/src/api/auth.js](file://frontend/src/api/auth.js)
- [frontend/src/api/request.js](file://frontend/src/api/request.js)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js)
- [frontend/src/views/Login.vue](file://frontend/src/views/Login.vue)
- [backend/requirements.txt](file://backend/requirements.txt)
- [test_frontend_connection.py](file://test_frontend_connection.py)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件面向“医院绩效系统”的用户认证子系统，提供从登录注册到权限校验、JWT 令牌管理、会话与状态管理、前后端交互流程、错误处理与安全策略的完整说明。内容覆盖后端 FastAPI 接口、前端 Vue/Element Plus 交互、Pinia 状态管理、以及数据库模型与安全策略。
## 项目结构
认证系统由后端 API 路由、安全模块、数据模型与 Pydantic Schema，以及前端请求封装、状态管理与登录界面组成。整体采用 OAuth2 密码模式，使用 JWT 进行无状态鉴权；前端通过 Axios 拦截器统一注入 Authorization 头，后端通过依赖注入解析令牌并校验用户状态。
```mermaid
graph TB
subgraph "前端"
FE_Login["Login.vue<br/>登录界面"]
FE_Store["user.js<br/>Pinia Store"]
FE_API_Auth["auth.js<br/>认证接口封装"]
FE_Request["request.js<br/>Axios 实例与拦截器"]
end
subgraph "后端"
BE_Main["main.py<br/>应用入口与CORS"]
BE_Router_Auth["api/v1/auth.py<br/>认证路由"]
BE_Security["core/security.py<br/>JWT/密码/依赖"]
BE_Schema["schemas/schemas.py<br/>认证数据模型"]
BE_Models["models/models.py<br/>User/Menu 等模型"]
BE_Config["core/config.py<br/>JWT/跨域/分页配置"]
end
FE_Login --> FE_Store
FE_Store --> FE_API_Auth
FE_API_Auth --> FE_Request
FE_Request --> BE_Main
BE_Main --> BE_Router_Auth
BE_Router_Auth --> BE_Security
BE_Security --> BE_Schema
BE_Security --> BE_Models
BE_Router_Auth --> BE_Schema
BE_Router_Auth --> BE_Models
BE_Main --> BE_Config
```
图表来源
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L313-L346)
- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L38)
- [backend/app/main.py](file://backend/app/main.py#L15-L77)
- [frontend/src/api/auth.js](file://frontend/src/api/auth.js#L1-L22)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L1-L66)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L1-L49)
- [frontend/src/views/Login.vue](file://frontend/src/views/Login.vue#L1-L155)
章节来源
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L1-L74)
- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L313-L346)
- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L38)
- [backend/app/main.py](file://backend/app/main.py#L15-L77)
- [frontend/src/api/auth.js](file://frontend/src/api/auth.js#L1-L22)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L1-L66)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L1-L49)
- [frontend/src/views/Login.vue](file://frontend/src/views/Login.vue#L1-L155)
## 核心组件
- 认证路由与接口
- 登录：接收表单数据，校验用户名/密码与账户状态，签发 JWT。
- 注册：校验用户名唯一性，生成密码哈希，写入用户记录。
- 当前用户：基于依赖注入解析 JWT 并返回用户信息。
- 安全模块
- 密码哈希：bcrypt。
- JWT：encode/decode，OAuth2 密码流 tokenUrl。
- 依赖：获取当前用户、校验激活状态、校验管理员/经理角色。
- 数据模型与 Schema
- User 模型：id、username、password_hash、role、is_active、last_login 等。
- 认证 Schema：UserLogin、UserCreate、Token、UserResponse。
- 前端交互
- 登录表单：Element Plus 表单校验与按钮触发。
- Pinia Store：保存 token、持久化 localStorage、登出重定向。
- Axios 拦截器：自动注入 Authorization: Bearer token，401 跳转登录。
章节来源
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L74)
- [backend/app/core/security.py](file://backend/app/core/security.py#L24-L110)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L315-L346)
- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
- [frontend/src/views/Login.vue](file://frontend/src/views/Login.vue#L63-L89)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L10-L39)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L14-L26)
## 架构总览
认证系统遵循 OAuth2 密码模式，后端通过 FastAPI 的依赖注入解析 JWT，前端通过 Axios 拦截器统一携带 Bearer Token。CORS 在后端全局中间件开启，允许前端开发源访问。
```mermaid
sequenceDiagram
participant U as "用户浏览器"
participant LV as "Login.vue"
participant US as "user.js"
participant AU as "auth.js"
participant AX as "request.js"
participant API as "auth.py"
participant SEC as "security.py"
participant DB as "数据库"
U->>LV : 输入用户名/密码并点击登录
LV->>US : 调用 store.login(username, password)
US->>AU : 调用 login({username, password})
AU->>AX : POST /api/v1/auth/login (表单)
AX->>API : 发送请求
API->>SEC : verify_password() 校验密码
API->>DB : 查询用户并检查 is_active
API-->>AX : 返回 {access_token, token_type}
AX-->>US : 返回 access_token
US->>US : localStorage.setItem('token', access_token)
US-->>LV : 登录成功，跳转首页
```
图表来源
- [frontend/src/views/Login.vue](file://frontend/src/views/Login.vue#L73-L89)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L11-L20)
- [frontend/src/api/auth.js](file://frontend/src/api/auth.js#L4-L11)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L14-L26)
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
- [backend/app/core/security.py](file://backend/app/core/security.py#L24-L31)
## 详细组件分析
### 后端认证路由与接口
- 登录接口
- 方法与路径：POST /api/v1/auth/login
- 请求体：OAuth2 表单（username/password），或前端封装为 application/x-www-form-urlencoded。
- 处理逻辑：查询用户、校验密码、检查 is_active、签发 access_token。
- 响应：Token 模型（access_token、token_type=bearer）。
- 注册接口
- 方法与路径：POST /api/v1/auth/register
- 请求体：UserCreate（username、password、staff_id、role）。
- 处理逻辑：检查用户名唯一性、生成密码哈希、写入 User 记录。
- 响应：通用响应（code/message/data）。
- 当前用户接口
- 方法与路径：GET /api/v1/auth/me
- 依赖：get_current_active_user（校验令牌与激活状态）。
- 响应：UserResponse。
章节来源
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L74)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L315-L346)
### 安全模块与 JWT 策略
- OAuth2 密码模式
- tokenUrl：/api/v1/auth/login。
- 前端通过 OAuth2PasswordRequestForm 或自定义表单提交。
- 密码与令牌
- 密码哈希：bcrypt。
- 令牌载荷：sub（用户 id）、exp（过期时间）。
- 算法与密钥：配置项 ALGORITHM/SECRET_KEY。
- 依赖链
- get_current_user：从 Authorization 解析 JWT，查询用户。
- get_current_active_user：校验 is_active。
- get_current_admin_user / get_current_manager_user：校验角色。
- 配置
- ACCESS_TOKEN_EXPIRE_MINUTES：默认约 8 小时。
- API_PREFIX：/api/v1。
章节来源
- [backend/app/core/security.py](file://backend/app/core/security.py#L21-L110)
- [backend/app/core/config.py](file://backend/app/core/config.py#L23-L26)
- [backend/app/main.py](file://backend/app/main.py#L41-L48)
### 数据模型与权限枚举
- User 模型字段
- id、username（唯一）、password_hash、role、is_active、last_login、created_at/updated_at。
- 角色与权限
- role：admin（管理员）、manager（经理）、staff（普通员工）。
- 依赖 get_current_manager_user 用于限制“管理员或经理”操作。
- 菜单与权限标识
- Menu 模型含 permission 字段，可用于前端菜单/按钮级权限控制（与后端依赖配合）。
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
- [backend/app/core/security.py](file://backend/app/core/security.py#L94-L109)
- [backend/app/models/models.py](file://backend/app/models/models.py#L347-L372)
### 前端交互与状态管理
- 登录界面
- Element Plus 表单校验、输入框、按钮与回车事件。
- Axios 拦截器
- 请求：自动注入 Authorization: Bearer token。
- 响应：401 清除本地 token 并跳转登录页。
- Pinia Store
- 登录：调用后端登录接口，保存 token 到内存与 localStorage。
- 获取用户：调用 /auth/me，缓存用户信息。
- 登出：清除 token 与用户信息，移除 localStorage，跳转登录页。
章节来源
- [frontend/src/views/Login.vue](file://frontend/src/views/Login.vue#L63-L89)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L14-L26)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L10-L39)
### API 接口定义与参数说明
- 登录
- 方法：POST
- 路径：/api/v1/auth/login
- 认证：OAuth2 表单或 application/x-www-form-urlencoded
- 请求体字段：username、password
- 响应体字段：access_token、token_type
- 注册
- 方法：POST
- 路径：/api/v1/auth/register
- 请求体字段：username、password、staff_id、role
- 响应体字段：code、message、data.id
- 当前用户
- 方法：GET
- 路径：/api/v1/auth/me
- 认证：Authorization: Bearer <token>
- 响应体字段：id、username、role、is_active、last_login、created_at
章节来源
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L74)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L315-L346)
### 错误处理与安全防护
- 后端错误
- 401 未授权：凭据无效或令牌解析失败。
- 403 禁止访问：账户被禁用或权限不足。
- 400 参数错误：用户名已存在、用户不存在等。
- 前端错误
- 401：提示“登录已过期，请重新登录”，清除 token 并跳转登录页。
- 通用错误：弹出 ElMessage 提示。
- 安全策略
- 密码使用 bcrypt 哈希。
- JWT 使用 HS256 算法与强密钥（生产环境需替换默认密钥）。
- CORS 允许指定前端源。
- 令牌过期时间可配置，默认约 8 小时。
章节来源
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L30-L34)
- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L91)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L38-L62)
- [backend/app/core/config.py](file://backend/app/core/config.py#L23-L26)
- [backend/app/main.py](file://backend/app/main.py#L41-L48)
## 依赖分析
- 后端依赖
- FastAPI + SQLAlchemy 异步 + Pydantic + python-jose + bcrypt。
- CORS 中间件开启，允许前端开发源。
- 前端依赖
- axios、Element Plus、Vue Router、Pinia。
- 认证依赖链
- auth.py 依赖 security.py 的 verify_password、create_access_token、get_current_active_user。
- security.py 依赖 config.py 的 SECRET_KEY、ALGORITHM、ACCESS_TOKEN_EXPIRE_MINUTES。
- 前端 auth.js 依赖 request.js 的 baseURL 与拦截器。
```mermaid
graph LR
RQ["requirements.txt<br/>依赖声明"] --> BE_SEC["security.py"]
BE_MAIN["main.py"] --> BE_AUTH["auth.py"]
BE_AUTH --> BE_SEC
BE_SEC --> BE_CFG["config.py"]
FE_REQ["request.js"] --> FE_AUTH["auth.js"]
FE_AUTH --> FE_STORE["user.js"]
FE_STORE --> FE_LOGIN["Login.vue"]
```
图表来源
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
- [backend/app/main.py](file://backend/app/main.py#L41-L48)
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L10-L12)
- [backend/app/core/security.py](file://backend/app/core/security.py#L13-L15)
- [backend/app/core/config.py](file://backend/app/core/config.py#L23-L26)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L6-L12)
- [frontend/src/api/auth.js](file://frontend/src/api/auth.js#L1-L2)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L1-L4)
章节来源
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)
- [backend/app/main.py](file://backend/app/main.py#L41-L48)
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L10-L12)
- [backend/app/core/security.py](file://backend/app/core/security.py#L13-L15)
- [backend/app/core/config.py](file://backend/app/core/config.py#L23-L26)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L6-L12)
- [frontend/src/api/auth.js](file://frontend/src/api/auth.js#L1-L2)
- [frontend/src/stores/user.js](file://frontend/src/stores/user.js#L1-L4)
## 性能考虑
- 令牌有效期：默认约 8 小时，建议根据业务场景调整，避免频繁刷新。
- 密码哈希：bcrypt 默认成本适中，生产环境可根据硬件能力提升成本。
- 数据库连接池：配置 DATABASE_POOL_SIZE 与 MAX_OVERFLOW，确保高并发下的连接稳定性。
- 前端拦截器：统一注入 Authorization，减少重复代码与错误。
## 故障排查指南
- 登录失败
- 确认用户名/密码正确，账户处于激活状态。
- 检查后端日志与 401/403 错误原因。
- CORS 问题
- 确认后端 CORS_ORIGINS 包含前端地址，测试脚本验证 OPTIONS 预检。
- Token 过期或 401
- 前端拦截器会自动清除 token 并跳转登录页，重新登录获取新令牌。
- 本地开发
- 前端通过 Vite 代理访问后端 /api，确保 baseURL 与后端 API_PREFIX 一致。
章节来源
- [test_frontend_connection.py](file://test_frontend_connection.py#L38-L74)
- [frontend/src/api/request.js](file://frontend/src/api/request.js#L38-L62)
- [backend/app/main.py](file://backend/app/main.py#L41-L48)
## 结论
该认证系统采用 OAuth2 密码模式与 JWT 无状态鉴权，结合 bcrypt 密码哈希与严格的依赖校验，实现了登录注册、权限控制与会话管理。前端通过 Axios 拦截器与 Pinia Store 完成令牌注入与状态维护，整体结构清晰、扩展性强，适合在医院绩效系统中作为统一认证层使用。
## 附录
- 默认凭证
- 用户名：admin
- 密码：admin123
- API 文档
- Swagger UI：http://localhost:8000/api/v1/docs
- ReDoc：http://localhost:8000/api/v1/redoc

516
.qoder/repowiki/zh/content/核心功能模块/系统管理功能.md Normal file
View File

@@ -0,0 +1,516 @@
# 系统管理功能
<cite>
**本文档引用的文件**
- [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py)
- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py)
- [backend/app/models/models.py](file://backend/app/models/models.py)
- [backend/app/core/security.py](file://backend/app/core/security.py)
- [backend/app/core/config.py](file://backend/app/core/config.py)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py)
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py)
- [backend/app/core/init_db.py](file://backend/app/core/init_db.py)
- [backend/app/main.py](file://backend/app/main.py)
- [frontend/src/views/system/Menus.vue](file://frontend/src/views/system/Menus.vue)
- [frontend/src/router/index.js](file://frontend/src/router/index.js)
- [docs/backend.md](file://docs/backend.md)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
医院绩效系统管理功能是一个基于RBAC（基于角色的访问控制）权限模型的完整管理系统。该系统实现了菜单权限管理、用户角色管理、系统配置管理和日志审计功能，为医院提供了统一的权限控制和系统管理能力。
系统采用前后端分离架构，后端基于FastAPI + SQLAlchemy 2.0 + PostgreSQL，前端基于Vue.js + Element Plus。通过JWT令牌进行身份认证，实现了严格的权限控制和安全的系统管理功能。
## 项目结构
系统管理功能主要分布在以下模块中：
```mermaid
graph TB
subgraph "后端架构"
A[API路由层] --> B[服务层]
B --> C[数据模型层]
C --> D[数据库]
E[安全认证模块] --> F[配置管理模块]
G[前端路由] --> H[菜单管理界面]
end
subgraph "核心功能模块"
I[菜单权限管理]
J[用户角色管理]
K[系统配置管理]
L[日志审计功能]
end
A --> I
A --> J
A --> K
A --> L
```
**图表来源**
- [backend/app/main.py](file://backend/app/main.py#L15-L77)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L1-L116)
**章节来源**
- [backend/app/main.py](file://backend/app/main.py#L15-L77)
- [docs/backend.md](file://docs/backend.md#L16-L58)
## 核心组件
系统管理功能的核心组件包括：
### RBAC权限模型
- **用户角色**：admin（管理员）、manager（经理）、staff（普通员工）
- **权限控制**：基于角色的访问控制，支持细粒度权限管理
- **JWT认证**：使用JWT令牌进行身份验证和授权
### 菜单权限管理
- **菜单树形结构**：支持多级菜单的层次化管理
- **动态加载**：根据用户权限动态加载可访问的菜单
- **权限标识**：每个菜单项支持独立的权限标识符
### 用户角色管理
- **用户生命周期**：完整的用户创建、更新、禁用管理
- **角色分配**：灵活的角色分配和权限继承
- **密码安全**：bcrypt密码哈希和安全存储
### 系统配置管理
- **环境配置**：集中式的系统配置管理
- **数据库配置**：支持异步PostgreSQL连接池
- **CORS配置**：跨域资源共享的安全配置
**章节来源**
- [backend/app/core/security.py](file://backend/app/core/security.py#L94-L110)
- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
## 架构概览
系统采用分层架构设计，确保职责分离和代码可维护性：
```mermaid
graph TB
subgraph "表现层"
FE[前端Vue应用]
UI[Element Plus组件]
end
subgraph "API网关层"
API[FastAPI路由]
AUTH[认证中间件]
VALID[数据验证]
end
subgraph "业务逻辑层"
SVC[服务层]
RBAC[RBAC权限控制]
LOG[日志记录]
end
subgraph "数据持久层"
ORM[SQLAlchemy ORM]
DB[(PostgreSQL数据库)]
end
FE --> API
UI --> API
API --> AUTH
AUTH --> SVC
SVC --> RBAC
SVC --> LOG
SVC --> ORM
ORM --> DB
```
**图表来源**
- [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py#L1-L164)
- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py#L1-L137)
- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
## 详细组件分析
### 菜单权限管理系统
#### 菜单数据模型设计
```mermaid
classDiagram
class Menu {
+int id
+int parent_id
+MenuType menu_type
+string menu_name
+string menu_icon
+string path
+string component
+string permission
+int sort_order
+bool is_visible
+bool is_active
+datetime created_at
+datetime updated_at
+Menu[] children
+Menu parent
}
class MenuType {
<<enumeration>>
MENU
BUTTON
}
class MenuService {
+get_tree(visible_only) Dict[]
+get_list(menu_type, is_visible) Menu[]
+get_by_id(menu_id) Menu
+create(menu_data) Menu
+update(menu_id, menu_data) Menu
+delete(menu_id) bool
+init_default_menus() void
}
MenuService --> Menu : manages
Menu --> Menu : parent_child
Menu --> MenuType : uses
```
**图表来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L347-L373)
- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py#L12-L137)
#### 菜单权限验证流程
```mermaid
sequenceDiagram
participant Client as 客户端
participant API as 菜单API
participant Service as 菜单服务
participant DB as 数据库
participant Security as 安全模块
Client->>API : GET /menus/tree
API->>Security : 验证JWT令牌
Security-->>API : 返回用户信息
API->>Service : get_tree(visible_only)
Service->>DB : 查询菜单树
DB-->>Service : 返回菜单数据
Service->>Service : 过滤可见菜单
Service-->>API : 返回菜单树
API-->>Client : 菜单树数据
Note over Client,Security : 权限验证流程
Client->>API : POST /menus
API->>Security : 验证管理员权限
Security-->>API : 权限通过
API->>Service : create(menu_data)
Service->>DB : 创建菜单
DB-->>Service : 返回新菜单
Service-->>API : 返回菜单ID
API-->>Client : 创建成功
```
**图表来源**
- [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py#L17-L164)
- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py#L16-L98)
- [backend/app/core/security.py](file://backend/app/core/security.py#L85-L110)
#### 菜单动态加载机制
前端通过以下流程实现菜单的动态加载：
```mermaid
flowchart TD
Start([页面加载]) --> LoadToken["读取JWT令牌"]
LoadToken --> HasToken{"令牌存在？"}
HasToken --> |否| RedirectLogin["重定向到登录页"]
HasToken --> |是| FetchTree["调用GET /menus/tree"]
FetchTree --> FilterVisible["过滤可见菜单"]
FilterVisible --> BuildMenu["构建菜单树"]
BuildMenu --> LoadRoutes["动态加载路由"]
LoadRoutes --> RenderUI["渲染界面"]
RenderUI --> End([完成])
RedirectLogin --> End
```
**图表来源**
- [frontend/src/views/system/Menus.vue](file://frontend/src/views/system/Menus.vue#L144-L161)
- [frontend/src/router/index.js](file://frontend/src/router/index.js#L104-L113)
**章节来源**
- [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py#L17-L164)
- [backend/app/services/menu_service.py](file://backend/app/services/menu_service.py#L16-L137)
- [frontend/src/views/system/Menus.vue](file://frontend/src/views/system/Menus.vue#L1-L265)
### 用户角色管理系统
#### RBAC权限模型实现
```mermaid
classDiagram
class User {
+int id
+string username
+string password_hash
+int staff_id
+string role
+bool is_active
+datetime last_login
+datetime created_at
+datetime updated_at
}
class Role {
<<enumeration>>
admin
manager
staff
}
class Permission {
+string resource
+string action
+string effect
}
class SecurityContext {
+User currentUser
+Permission[] permissions
+validatePermission(permission) bool
+hasRole(role) bool
}
User --> Role : has
SecurityContext --> User : authenticates
SecurityContext --> Permission : checks
```
**图表来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L244-L261)
- [backend/app/core/security.py](file://backend/app/core/security.py#L94-L110)
#### 用户认证流程
```mermaid
sequenceDiagram
participant Browser as 浏览器
participant AuthAPI as 认证API
participant Security as 安全模块
participant DB as 数据库
participant JWT as JWT服务
Browser->>AuthAPI : POST /auth/login
AuthAPI->>Security : 验证密码
Security->>DB : 查询用户
DB-->>Security : 返回用户信息
Security->>Security : 验证密码哈希
Security-->>AuthAPI : 验证结果
AuthAPI->>JWT : 创建访问令牌
JWT-->>AuthAPI : 返回JWT令牌
AuthAPI-->>Browser : 返回令牌
Note over Browser,JWT : 后续请求携带令牌
Browser->>AuthAPI : 带JWT令牌的请求
AuthAPI->>Security : 解码和验证令牌
Security-->>Browser : 授权通过
```
**图表来源**
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L38)
- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L83)
**章节来源**
- [backend/app/core/security.py](file://backend/app/core/security.py#L94-L110)
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L74)
### 系统配置管理
#### 配置管理架构
```mermaid
graph TB
subgraph "配置层次"
A[环境变量]
B[配置文件]
C[运行时配置]
end
subgraph "配置类型"
D[应用配置]
E[数据库配置]
F[JWT配置]
G[CORS配置]
H[分页配置]
end
A --> B
B --> C
C --> D
C --> E
C --> F
C --> G
C --> H
```
**图表来源**
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
#### 配置初始化流程
```mermaid
flowchart TD
Start([系统启动]) --> LoadEnv["加载环境变量"]
LoadEnv --> InitConfig["初始化配置"]
InitConfig --> ValidateConfig{"配置验证"}
ValidateConfig --> |通过| InitDB["初始化数据库"]
ValidateConfig --> |失败| LogError["记录错误"]
LogError --> End([结束])
InitDB --> InitAdmin["创建管理员用户"]
InitAdmin --> InitSample["创建示例数据"]
InitSample --> Complete([完成])
```
**图表来源**
- [backend/app/core/init_db.py](file://backend/app/core/init_db.py#L12-L115)
**章节来源**
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
- [backend/app/core/init_db.py](file://backend/app/core/init_db.py#L12-L115)
### 日志审计功能
#### 日志记录机制
系统实现了多层次的日志记录功能：
- **应用日志**：记录系统运行状态和错误信息
- **访问日志**：记录用户访问行为和操作
- **审计日志**：记录重要的系统变更和敏感操作
**章节来源**
- [backend/app/main.py](file://backend/app/main.py#L58-L75)
## 依赖关系分析
系统管理功能的依赖关系如下：
```mermaid
graph TB
subgraph "外部依赖"
A[FastAPI]
B[SQLAlchemy]
C[PostgreSQL]
D[JWT]
E[bcrypt]
end
subgraph "内部模块"
F[API路由]
G[服务层]
H[数据模型]
I[安全模块]
J[配置模块]
end
A --> F
B --> G
C --> H
D --> I
E --> I
F --> G
G --> H
I --> J
F --> I
G --> I
```
**图表来源**
- [docs/backend.md](file://docs/backend.md#L3-L15)
- [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py#L1-L14)
**章节来源**
- [docs/backend.md](file://docs/backend.md#L3-L15)
## 性能考虑
系统管理功能在设计时充分考虑了性能优化：
### 数据库性能优化
- **索引设计**：为常用查询字段建立适当的索引
- **连接池**：使用异步连接池提高数据库访问效率
- **查询优化**：避免N+1查询问题，使用selectinload优化关系查询
### 缓存策略
- **菜单缓存**：菜单数据变化频率较低，适合缓存
- **用户信息缓存**：JWT令牌中包含用户基本信息
- **配置缓存**：系统配置在启动时加载并缓存
### 并发处理
- **异步IO**：使用async/await模式提高并发处理能力
- **数据库事务**：合理使用事务保证数据一致性
- **锁机制**：避免死锁和长时间持有锁
## 故障排除指南
### 常见问题及解决方案
#### 登录认证问题
- **问题**：用户无法登录
- **原因**：用户名密码错误或账户被禁用
- **解决**：检查用户状态和密码哈希
#### 权限访问问题
- **问题**：用户无法访问某些功能
- **原因**：角色权限不足或菜单权限未配置
- **解决**：检查用户角色和菜单权限设置
#### 菜单显示问题
- **问题**：菜单不显示或显示异常
- **原因**：菜单树构建错误或权限过滤问题
- **解决**：检查菜单层级关系和可见性设置
**章节来源**
- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L30-L35)
- [backend/app/core/security.py](file://backend/app/core/security.py#L94-L110)
## 结论
医院绩效系统的系统管理功能通过完善的RBAC权限模型、动态菜单管理和严格的安全控制，为医院提供了强大而灵活的系统管理能力。系统采用现代化的技术栈和架构设计，具有良好的扩展性和维护性。
主要特点包括：
- **完整的权限控制**：基于角色的细粒度权限管理
- **动态菜单系统**：根据用户权限动态加载菜单
- **安全可靠**：JWT认证和bcrypt密码哈希
- **易于扩展**：模块化设计支持功能扩展
- **性能优化**：异步处理和数据库优化
该系统为医院的数字化转型提供了坚实的技术基础，能够有效提升医院管理效率和决策水平。
## 附录
### 权限配置说明
#### 角色权限矩阵
- **admin**：系统管理员，拥有所有权限
- **manager**：部门经理，拥有部门相关权限
- **staff**：普通员工，仅拥有基本操作权限
#### 菜单权限标识
- **资源格式**：`{模块}:{操作}:{权限}`
- **示例**：`system:menu:list`、`basic:user:create`
### 菜单结构设计
#### 菜单类型
- **菜单**：用于导航的主菜单项
- **按钮**：用于具体操作的按钮权限
#### 菜单属性
- **路径**：前端路由路径
- **组件**：Vue组件名称
- **图标**：Element Plus图标名称
- **排序**：菜单显示顺序
### 安全策略
#### 密码安全
- **哈希算法**：bcrypt
- **盐值生成**：自动生成随机盐值
- **密码强度**：最小长度6位
#### 令牌管理
- **过期时间**：8小时
- **算法**：HS256
- **存储**：localStorage

497
.qoder/repowiki/zh/content/核心功能模块/绩效考核管理/批量创建功能.md Normal file
View File

@@ -0,0 +1,497 @@
# 批量创建功能
<cite>
**本文档引用的文件**
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py)
- [backend/app/models/models.py](file://backend/app/models/models.py)
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py)
- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
批量创建功能是医院绩效管理系统中的核心特性之一，允许管理员和经理用户一次性为指定科室的所有在职员工创建考核记录。该功能支持按考核周期（年度/月份）和指标模板进行批量生成，显著提高了绩效管理的工作效率。
本文档详细介绍了批量创建考核记录的完整流程，包括科室选择、考核周期设置、指标模板选择和批量生成机制。同时涵盖了数据验证规则、重复检查逻辑、异常处理策略、性能优化、并发控制和事务管理等方面的内容。
## 项目结构
医院绩效系统采用前后端分离的架构设计，后端使用FastAPI框架，前端使用Vue.js框架。批量创建功能涉及以下关键文件：
```mermaid
graph TB
subgraph "前端层"
FE1[Assessments.vue<br/>批量创建界面]
FE2[assessment.js<br/>API调用封装]
end
subgraph "后端层"
BE1[assessments.py<br/>API路由]
BE2[assessment_service.py<br/>业务逻辑]
BE3[models.py<br/>数据模型]
end
subgraph "数据库层"
DB1[Assessment<br/>考核记录表]
DB2[AssessmentDetail<br/>考核明细表]
DB3[Staff<br/>员工表]
DB4[Indicator<br/>指标表]
end
FE1 --> FE2
FE2 --> BE1
BE1 --> BE2
BE2 --> BE3
BE3 --> DB1
BE3 --> DB2
BE3 --> DB3
BE3 --> DB4
```
**图表来源**
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L203)
**章节来源**
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
## 核心组件
批量创建功能由以下核心组件构成：
### 1. API接口层
- **批量创建接口**：提供RESTful API用于批量创建考核记录
- **权限控制**：要求管理员或经理权限
- **参数验证**：严格的输入参数验证和类型检查
### 2. 服务层
- **批量创建服务**：实现批量创建的核心业务逻辑
- **重复检查**：防止重复创建相同周期的考核记录
- **事务管理**：确保数据一致性和完整性
### 3. 数据模型层
- **Assessment模型**：考核记录实体
- **AssessmentDetail模型**：考核明细实体
- **Staff模型**：员工信息模型
- **Indicator模型**：考核指标模型
### 4. 前端界面层
- **批量创建对话框**：用户友好的交互界面
- **数据验证**：前端参数验证和错误提示
- **异步加载**：支持大量数据的异步处理
**章节来源**
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L208-L262)
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L203)
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L77-L112)
## 架构概览
批量创建功能采用分层架构设计，确保了良好的代码组织和可维护性：
```mermaid
sequenceDiagram
participant User as 用户
participant Frontend as 前端界面
participant API as API接口
participant Service as 服务层
participant DB as 数据库
User->>Frontend : 触发批量创建
Frontend->>API : 发送批量创建请求
API->>Service : 调用批量创建服务
Service->>DB : 查询在职员工
DB-->>Service : 返回员工列表
Service->>Service : 检查重复记录
Service->>DB : 创建考核记录
Service->>DB : 创建考核明细
DB-->>Service : 返回创建结果
Service-->>API : 返回批量创建结果
API-->>Frontend : 显示创建结果
Frontend-->>User : 显示成功消息
```
**图表来源**
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L148-L165)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L208-L262)
## 详细组件分析
### API接口组件
批量创建API接口提供了完整的RESTful服务：
#### 接口定义
- **URL**：`POST /assessments/batch-create`
- **权限**：管理员或经理
- **请求参数**：
- `department_id`：科室ID（必填）
- `period_year`：年度（必填）
- `period_month`：月份（必填）
- `indicators`：指标ID列表（必填）
#### 参数验证规则
- 科室ID必须存在且有效
- 年度必须在合理范围内（2020-2100）
- 月份必须在1-12之间
- 指标ID列表不能为空
- 所有指标ID必须存在
**章节来源**
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L148-L165)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L220-L231)
### 服务层组件
服务层实现了批量创建的核心业务逻辑：
#### 批量创建流程
1. **获取在职员工**：查询指定科室的所有在职员工
2. **重复检查**：检查是否存在相同周期的考核记录
3. **创建考核记录**：为每个员工创建空的考核记录
4. **创建考核明细**：为每个考核记录添加指定的指标
5. **事务提交**：确保所有操作在一个事务中完成
#### 重复检查逻辑
系统通过组合键唯一性来防止重复创建：
- `staff_id + period_year + period_month`
- 如果记录已存在，则跳过该员工
#### 异常处理策略
- **权限验证失败**：返回403错误
- **参数验证失败**：返回400错误
- **数据库操作失败**：返回500错误
- **业务逻辑错误**：返回相应的业务错误信息
**章节来源**
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L208-L262)
### 数据模型组件
数据模型定义了批量创建功能所需的核心实体：
#### Assessment模型
- **主键**：自增ID
- **外键**：关联员工表
- **索引**：按员工ID、年度、月份建立复合索引
- **状态**：默认草稿状态
#### AssessmentDetail模型
- **主键**：自增ID
- **外键**：关联考核记录表和指标表
- **索引**：按考核记录ID和指标ID建立索引
- **默认值**：分数默认为0
#### Staff模型
- **状态过滤**：只查询在职员工
- **关联关系**：与部门和考核记录建立关联
**章节来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L203)
### 前端组件
前端提供了用户友好的批量创建界面：
#### 界面组件
- **批量创建按钮**：触发批量创建对话框
- **科室选择器**：树形结构选择科室
- **日期选择器**：选择考核周期（年-月）
- **指标多选框**：选择要应用的指标
#### 数据流
1. **加载数据**：初始化时加载科室树和可用指标
2. **表单验证**：前端验证必填字段
3. **API调用**：发送批量创建请求
4. **结果处理**：显示创建结果和错误信息
#### 用户体验
- **异步加载**：使用loading状态指示后台处理
- **错误提示**：友好的错误消息提示
- **成功反馈**：创建成功后的确认消息
**章节来源**
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L77-L112)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L38-L49)
## 依赖关系分析
批量创建功能涉及多个组件之间的复杂依赖关系：
```mermaid
graph TD
subgraph "API层"
A1[assessments.py]
end
subgraph "服务层"
S1[assessment_service.py]
S2[indicator_service.py]
S3[department_service.py]
end
subgraph "模型层"
M1[models.py]
end
subgraph "前端层"
F1[Assessments.vue]
F2[assessment.js]
end
A1 --> S1
S1 --> M1
S2 --> M1
S3 --> M1
F1 --> F2
F2 --> A1
F1 --> S2
F1 --> S3
```
**图表来源**
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
### 外部依赖
- **SQLAlchemy**：ORM框架，用于数据库操作
- **FastAPI**：Web框架，提供API服务
- **Element Plus**：UI组件库，提供前端界面
- **Pydantic**：数据验证和序列化
### 内部依赖
- **API层依赖服务层**：API层调用服务层实现业务逻辑
- **服务层依赖模型层**：服务层操作数据库模型
- **前端依赖API层**：前端通过API层访问后端服务
- **服务层相互依赖**：不同服务之间存在业务依赖关系
**章节来源**
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
## 性能考虑
批量创建功能在设计时充分考虑了性能优化：
### 数据库性能优化
#### 索引优化
- **Assessment表**：在`(staff_id, period_year, period_month)`上建立复合索引
- **AssessmentDetail表**：在`(assessment_id, indicator_id)`上建立复合索引
- **Staff表**：在`(department_id, status)`上建立复合索引
#### 查询优化
- 使用`selectinload`进行关联查询，减少N+1查询问题
- 批量插入使用`db.flush()`减少数据库往返次数
- 使用`await db.commit()`确保事务完整性
### 并发控制
#### 事务管理
- 所有批量创建操作在一个数据库事务中执行
- 使用异步事务确保并发安全性
- 发生异常时自动回滚，保证数据一致性
#### 锁机制
- 使用数据库锁防止并发冲突
- 重复检查使用原子操作确保线程安全
### 内存管理
#### 流式处理
- 对于大量员工的情况，使用流式查询避免内存溢出
- 分批处理员工数据，控制内存使用
#### 连接池管理
- 使用连接池复用数据库连接
- 合理配置连接池大小避免资源耗尽
### 缓存策略
#### 结果缓存
- 对于频繁查询的指标数据使用缓存
- 缓存科室树形结构数据
#### 查询缓存
- 对于静态数据查询使用查询缓存
- 减少重复数据库查询开销
## 故障排除指南
### 常见问题及解决方案
#### 1. 权限不足
**问题**：批量创建接口返回403错误
**原因**：当前用户不是管理员或经理
**解决方案**：
- 确保用户具有相应权限
- 检查用户角色配置
- 重新登录系统
#### 2. 参数验证失败
**问题**：批量创建接口返回400错误
**原因**：请求参数不符合验证规则
**解决方案**：
- 检查科室ID是否存在
- 验证年度和月份范围
- 确保指标ID列表不为空
#### 3. 重复创建
**问题**：某些员工没有创建考核记录
**原因**：这些员工已有相同周期的考核记录
**解决方案**：
- 检查现有考核记录
- 修改考核周期重新创建
- 手动删除重复记录后重试
#### 4. 数据库连接问题
**问题**：批量创建过程中出现数据库错误
**原因**：数据库连接超时或连接池耗尽
**解决方案**：
- 检查数据库连接配置
- 增加连接池大小
- 优化数据库查询性能
#### 5. 前端界面问题
**问题**：批量创建对话框无法打开或显示错误
**原因**：前端JavaScript错误或API调用失败
**解决方案**：
- 检查浏览器控制台错误
- 确保API接口正常运行
- 刷新页面重新加载数据
### 调试技巧
#### 后端调试
- 查看服务器日志获取详细错误信息
- 使用数据库客户端检查数据状态
- 启用SQL查询日志跟踪数据库操作
#### 前端调试
- 使用浏览器开发者工具检查网络请求
- 查看控制台错误信息
- 检查API响应格式
#### 性能监控
- 监控数据库查询执行时间
- 检查内存使用情况
- 监控并发连接数
**章节来源**
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L148-L165)
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L264-L286)
## 结论
批量创建功能是医院绩效管理系统的重要组成部分，它通过以下优势为企业带来了显著的价值：
### 功能优势
- **高效性**：大幅减少了手动创建考核记录的时间
- **准确性**：通过重复检查逻辑确保数据完整性
- **易用性**：提供直观的用户界面和清晰的操作流程
- **扩展性**：支持多种指标模板和考核周期
### 技术优势
- **架构清晰**：采用分层架构设计，便于维护和扩展
- **性能优化**：通过索引优化、事务管理和缓存策略提升性能
- **安全保障**：完善的权限控制和异常处理机制
- **并发安全**：通过事务管理和锁机制确保数据一致性
### 应用场景
- **月度考核**：每月定期为全体员工创建考核记录
- **季度评估**：按季度进行的综合评估
- **特殊时期**：如新员工入职、科室调整等特殊情况
- **系统迁移**：历史数据的批量导入和处理
批量创建功能不仅提高了工作效率，更重要的是确保了绩效管理工作的标准化和规范化，为医院的绩效管理体系奠定了坚实的技术基础。
## 附录
### 使用示例
#### 基本使用流程
1. 登录系统并进入考核管理页面
2. 点击"批量创建"按钮
3. 选择目标科室
4. 设置考核周期（年-月）
5. 选择要应用的指标
6. 确认创建并等待处理完成
#### 参数说明
| 参数名 | 类型 | 必填 | 描述 | 示例值 |
|--------|------|------|------|--------|
| department_id | integer | 是 | 科室ID | 1 |
| period_year | integer | 是 | 考核年度 | 2026 |
| period_month | integer | 是 | 考核月份 | 2 |
| indicators | array | 是 | 指标ID列表 | [1, 2, 3] |
#### API调用示例
**请求示例**：
```
POST /assessments/batch-create?department_id=1&period_year=2026&period_month=2&indicators=1&indicators=2&indicators=3
```
**响应示例**：
```json
{
"code": 200,
"message": "成功创建 15 条考核记录",
"data": {
"count": 15
}
}
```
### 最佳实践
#### 1. 数据准备
- 确保所有指标都已正确配置
- 验证科室信息的完整性
- 准备好员工名单和状态信息
#### 2. 批量创建策略
- 优先创建常用指标的组合
- 避免同时创建过多员工的考核记录
- 定期清理无效的考核记录
#### 3. 监控和维护
- 定期检查批量创建任务的状态
- 监控数据库性能指标
- 及时处理异常情况
#### 4. 用户培训
- 对管理员进行系统培训
- 提供详细的操作手册
- 建立技术支持渠道
### 扩展建议
#### 1. 功能扩展
- 支持自定义指标模板
- 添加批量编辑功能
- 实现自动化考核流程
#### 2. 性能优化
- 实现增量批量创建
- 添加进度条显示
- 优化大数据量处理
#### 3. 用户体验
- 添加批量创建历史记录
- 实现创建结果导出
- 提供创建预览功能

424
.qoder/repowiki/zh/content/核心功能模块/绩效考核管理/绩效考核管理.md Normal file
View File

@@ -0,0 +1,424 @@
# 绩效考核管理
<cite>
**本文档引用的文件**
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_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/indicators.py](file://backend/app/api/v1/indicators.py)
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue)
- [frontend/src/views/assessment/AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js)
- [frontend/src/api/indicator.js](file://frontend/src/api/indicator.js)
- [docs/api.md](file://docs/api.md)
- [docs/详细设计.md](file://docs/详细设计.md)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本模块聚焦于医院绩效系统的“绩效考核管理”，围绕考核流程（草稿→提交→审核→确认→完成）、考核记录与明细处理、批量创建、平衡计分卡（财务、客户、内部流程、学习与成长）应用、状态管理与审批控制、数据统计与报表、以及规则配置与权重计算展开。文档同时提供业务流程图、界面操作说明与API接口规范，帮助开发者与使用者高效理解与使用。
## 项目结构
后端采用FastAPI + SQLAlchemy异步ORM，前端采用Vue 3 + Element Plus，数据模型、服务层与API路由清晰分离，前端通过封装的API模块调用后端接口。
```mermaid
graph TB
subgraph "前端"
FE_List["Assessments.vue<br/>考核列表视图"]
FE_Detail["AssessmentDetail.vue<br/>考核详情视图"]
FE_API_A["assessment.js<br/>考核API封装"]
FE_API_I["indicator.js<br/>指标API封装"]
end
subgraph "后端"
API["assessments.py<br/>考核API路由"]
SVC["assessment_service.py<br/>考核服务"]
MODELS["models.py<br/>数据模型"]
SCHEMAS["schemas.py<br/>数据模式"]
IND_API["indicators.py<br/>指标API路由"]
end
FE_List --> FE_API_A
FE_Detail --> FE_API_A
FE_List --> FE_API_I
FE_API_A --> API
FE_API_I --> IND_API
API --> SVC
SVC --> MODELS
SVC --> SCHEMAS
IND_API --> SVC
```
图表来源
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
- [frontend/src/views/assessment/AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L257)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L1-L50)
- [frontend/src/api/indicator.js](file://frontend/src/api/indicator.js#L1-L32)
章节来源
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L203)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L194-L271)
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
- [frontend/src/views/assessment/AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L257)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L1-L50)
- [frontend/src/api/indicator.js](file://frontend/src/api/indicator.js#L1-L32)
## 核心组件
- 数据模型
- Assessment：考核记录，包含周期、总分、加权得分、状态、关联人员与明细。
- AssessmentDetail：考核明细，记录每个指标的实际值、得分、佐证材料等。
- Indicator：考核指标，包含类型、平衡计分卡维度、权重、最高分、目标值等。
- AssessmentStatus：枚举状态（草稿、已提交、已审核、已确认、已驳回）。
- 服务层
- AssessmentService：提供列表查询、详情加载、创建、更新、提交、审核、确认、批量创建等核心能力。
- API层
- 路由提供列表、详情、创建、更新、提交、审核、确认、批量创建等REST接口。
- 前端
- Assessments.vue：列表页，支持筛选、分页、批量创建、状态流转。
- AssessmentDetail.vue：详情页，支持草稿态编辑、保存、提交、审核、确认。
- assessment.js/indicator.js：前端API封装，统一调用后端接口。
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L203)
- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L147)
- [backend/app/models/models.py](file://backend/app/models/models.py#L45-L51)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
- [frontend/src/views/assessment/AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L257)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L1-L50)
- [frontend/src/api/indicator.js](file://frontend/src/api/indicator.js#L1-L32)
## 架构总览
后端采用分层架构：API路由负责参数解析与鉴权，服务层封装业务逻辑，模型层映射数据库表结构。前端通过HTTP请求与后端交互，完成考核流程的可视化操作。
```mermaid
graph TB
Client["浏览器/移动端"] --> FE["前端Vue应用"]
FE --> API["FastAPI路由层"]
API --> Service["服务层"]
Service --> DB["数据库"]
Service --> Models["数据模型"]
Service --> Schemas["数据模式"]
```
图表来源
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
## 详细组件分析
### 考核流程管理（草稿→提交→审核→确认→完成）
- 流程状态
- 草稿：可编辑明细与得分。
- 已提交：等待审核。
- 已审核：等待确认。
- 已确认：完成，不可再编辑。
- 已驳回：退回草稿，可重新提交。
- 接口流转
- 草稿 → 提交：POST /assessments/{id}/submit
- 已提交 → 审核：POST /assessments/{id}/review（批准/驳回）
- 已审核 → 确认：POST /assessments/{id}/finalize
- 已确认 → 完成：不可逆
- 前端操作
- 列表页仅显示状态与操作按钮，按钮随状态变化。
- 详情页支持草稿态编辑与保存，提交后进入审核流程。
```mermaid
stateDiagram-v2
[*] --> 草稿
草稿 --> 已提交 : "提交"
已提交 --> 已审核 : "审核通过"
已提交 --> 草稿 : "审核驳回"
已审核 --> 已确认 : "确认"
已确认 --> [*]
```
图表来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L45-L51)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L105-L145)
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L55-L63)
- [frontend/src/views/assessment/AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L86-L93)
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L45-L51)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L105-L145)
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L55-L63)
- [frontend/src/views/assessment/AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L86-L93)
### 考核记录管理与明细处理
- 记录管理
- 创建：POST /assessments（携带明细数组）
- 更新：PUT /assessments/{id}（仅允许草稿或已驳回状态）
- 详情：GET /assessments/{id}（包含明细与指标名称）
- 明细字段
- 指标ID、实际值、得分、佐证材料、备注
- 加权得分计算
- 总分：明细得分求和
- 加权得分：∑(明细得分 × 指标权重)
```mermaid
flowchart TD
Start(["创建/更新考核"]) --> CalcTotal["计算总分<br/>sum(明细得分)"]
CalcTotal --> LoadIndicators["加载指标权重"]
LoadIndicators --> CalcWeighted["计算加权得分<br/>sum(得分×权重)"]
CalcWeighted --> SaveAssessment["保存考核记录与明细"]
SaveAssessment --> End(["完成"])
```
图表来源
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L110-L156)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L194-L271)
章节来源
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L80-L103)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L70-L156)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L194-L271)
### 批量创建功能
- 触发入口：列表页“批量创建”
- 参数：科室ID、年度、月份、指标ID列表
- 逻辑：为该科室当月在职员工逐一创建空明细的考核记录（若不存在）
```mermaid
sequenceDiagram
participant U as "用户"
participant V as "Assessments.vue"
participant A as "assessment.js"
participant R as "assessments.py"
participant S as "assessment_service.py"
U->>V : "点击批量创建"
V->>A : "调用批量创建API"
A->>R : "POST /assessments/batch-create"
R->>S : "batch_create_for_department()"
S->>S : "查询在职员工"
S->>S : "检查是否存在重复"
S->>S : "创建考核记录+明细"
S-->>R : "返回创建数量"
R-->>A : "返回成功响应"
A-->>V : "提示成功并刷新列表"
```
图表来源
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L28-L112)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L38-L49)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L148-L165)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L207-L262)
章节来源
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L28-L112)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L38-L49)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L148-L165)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L207-L262)
### 平衡计分卡维度应用
- 指标维度
- 财务（financial）
- 客户（customer）
- 内部流程（internal_process）
- 学习与成长（learning_growth）
- 应用方式
- 指标表包含bs_dimension字段，用于区分维度
- 前端在详情页展示指标类型标签，便于识别维度属性
- 配置建议
- 不同科室类型可选用不同模板或指标组合，体现维度侧重点差异
```mermaid
classDiagram
class Indicator {
+bs_dimension
+weight
+max_score
}
class AssessmentDetail {
+indicator_id
+actual_value
+score
}
Indicator <.. AssessmentDetail : "被引用"
```
图表来源
- [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-L202)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L151-L193)
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L29-L35)
- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L147)
- [frontend/src/views/assessment/AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L38-L42)
### 状态管理与审批控制
- 状态枚举与流转限制
- 草稿/已驳回：可更新
- 已提交：仅能审核
- 已审核：仅能确认
- 已确认：不可再更改
- 审批接口
- 审核：POST /assessments/{id}/review（批准/驳回）
- 确认：POST /assessments/{id}/finalize
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L45-L51)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L110-L205)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L118-L145)
### 数据统计分析与报表
- 指标管理API
- 获取启用指标：GET /indicators/active
- 获取指标列表：GET /indicators
- 报表与统计
- 文档中提供统计接口（如科室统计、趋势分析、分布等），可结合考核数据进行分析
- 建议
- 基于Assessment与AssessmentDetail聚合，生成部门/个人/维度的统计报表
章节来源
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L44-L55)
- [docs/api.md](file://docs/api.md#L471-L537)
- [docs/详细设计.md](file://docs/详细设计.md#L155-L163)
### 考核规则配置、权重计算与结果汇总
- 规则配置
- 指标权重：Indicator.weight
- 最高分：Indicator.max_score
- 计算方法/公式：Indicator.calculation_method
- 权重计算
- 总分：明细得分求和
- 加权得分：∑(明细得分 × 指标权重)
- 结果汇总
- 以Assessment为单位汇总，支持按周期、部门、状态等维度统计
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L147)
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L178)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)
## 依赖关系分析
```mermaid
graph LR
AssessAPI["assessments.py"] --> AssessSvc["assessment_service.py"]
AssessSvc --> Models["models.py"]
AssessSvc --> Schemas["schemas.py"]
IndAPI["indicators.py"] --> AssessSvc
FEAssess["Assessments.vue"] --> FEAssessAPI["assessment.js"]
FEDetail["AssessmentDetail.vue"] --> FEAssessAPI
FEAssessAPI --> AssessAPI
FEInd["indicator.js"] --> IndAPI
```
图表来源
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
- [frontend/src/views/assessment/AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L257)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L1-L50)
- [frontend/src/api/indicator.js](file://frontend/src/api/indicator.js#L1-L32)
章节来源
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
- [frontend/src/views/assessment/AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L257)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L1-L50)
- [frontend/src/api/indicator.js](file://frontend/src/api/indicator.js#L1-L32)
## 性能考虑
- 查询优化
- 列表查询支持按员工、科室、年度、月份、状态过滤，建议在相关列建立索引（如 idx_assessment_staff、idx_assessment_period、idx_assessment_status）。
- 批量创建
- 批量创建时避免重复记录，减少数据库写入压力。
- 前端渲染
- 大列表分页加载，避免一次性渲染过多行。
- 异步处理
- 服务层使用异步会话，适合高并发场景。
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L174-L178)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L18-L55)
## 故障排查指南
- 常见问题
- 状态不允许：仅允许在草稿或已驳回状态下更新；仅允许在已提交状态下审核；仅允许在已审核状态下确认。
- 资源不存在：接口返回404，检查ID或参数。
- 参数错误：检查必填字段与范围（如月份1-12、权重>0）。
- 前端提示
- 使用Element Plus的消息组件提示成功/失败。
- 日志与监控
- 后端日志目录：logs/，可定位异常请求与SQL执行情况。
章节来源
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L110-L205)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L98-L101)
- [docs/api.md](file://docs/api.md#L540-L551)
## 结论
本模块以清晰的流程状态与严格的审批控制为核心，结合平衡计分卡维度与指标权重，实现了从草稿到完成的全流程管理。前后端职责分明，接口规范明确，具备良好的扩展性与可维护性。建议后续完善统计分析与报表模块，并在生产环境增加更完善的日志与监控策略。
## 附录
### 业务流程图（概念）
```mermaid
flowchart TD
A["开始"] --> B["创建/编辑考核<br/>草稿态"]
B --> C["提交考核"]
C --> D{"审核通过？"}
D -- "是" --> E["确认考核"]
D -- "否" --> F["退回草稿<br/>可重新提交"]
E --> G["完成"]
F --> C
G --> H["结束"]
```
[此图为概念流程图，不对应具体代码文件]
### 界面操作说明
- 列表页
- 支持按科室、考核周期、状态筛选；分页浏览；批量创建；对草稿/已提交/已审核状态显示相应操作按钮。
- 详情页
- 展示基本信息与明细；草稿态可编辑实际值、得分、佐证材料；支持保存、提交、审核、确认等操作。
章节来源
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
- [frontend/src/views/assessment/AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L257)
### API接口文档（节选）
- 获取考核列表：GET /assessments
- 获取考核详情：GET /assessments/{id}
- 创建考核：POST /assessments
- 更新考核：PUT /assessments/{id}
- 提交考核：POST /assessments/{id}/submit
- 审核考核：POST /assessments/{id}/review
- 确认考核：POST /assessments/{id}/finalize
- 批量创建：POST /assessments/batch-create
- 获取启用指标：GET /indicators/active
章节来源
- [docs/api.md](file://docs/api.md#L298-L397)
- [docs/api.md](file://docs/api.md#L471-L537)

332
.qoder/repowiki/zh/content/核心功能模块/绩效考核管理/考核数据分析.md Normal file
View File

@@ -0,0 +1,332 @@
# 考核数据分析
<cite>
**本文档引用的文件**
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.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/api/stats.js](file://frontend/src/api/stats.js)
- [frontend/src/views/reports/Reports.vue](file://frontend/src/views/reports/Reports.vue)
- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue)
- [backend/app/scripts/init_templates.py](file://backend/app/scripts/init_templates.py)
- [docs/详细设计文档.md](file://docs/详细设计文档.md)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件面向医院绩效系统的“考核数据分析”功能，系统性阐述基于考核数据的统计分析能力，涵盖按科室、按人员、按时间段的绩效统计；BSC四个维度的分析方法、趋势分析与排名统计；数据聚合算法、图表展示与报表生成机制；以及分析指标、计算公式与可视化方案，并给出数据准确性保证与性能优化策略。
## 项目结构
后端采用 FastAPI + SQLAlchemy 异步 ORM 架构，前端使用 Vue3 + Element Plus + ECharts。统计分析功能由 API 层、服务层与数据模型层协同完成，前端通过统一的统计接口进行数据拉取与可视化渲染。
```mermaid
graph TB
FE["前端视图<br/>Reports.vue / Dashboard.vue"] --> API["FastAPI 统计接口<br/>stats.py"]
API --> SVC["统计服务层<br/>stats_service.py"]
SVC --> DB["数据库模型<br/>models.py"]
DB --> SQL["SQLAlchemy 异步查询"]
FE --> FE_API["前端统计接口封装<br/>stats.js"]
```
图表来源
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L242)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
- [frontend/src/views/reports/Reports.vue](file://frontend/src/views/reports/Reports.vue#L1-L367)
- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue#L225-L819)
- [frontend/src/api/stats.js](file://frontend/src/api/stats.js#L1-L43)
章节来源
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L242)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
- [frontend/src/views/reports/Reports.vue](file://frontend/src/views/reports/Reports.vue#L1-L367)
- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue#L225-L819)
- [frontend/src/api/stats.js](file://frontend/src/api/stats.js#L1-L43)
## 核心组件
- 统计 API：提供 BSC 维度分析、科室统计、趋势分析、排名、指标完成度等接口。
- 统计服务：封装 SQL 聚合逻辑，负责按条件过滤、分组统计与排序。
- 数据模型：定义 Assessment、AssessmentDetail、Indicator、Department、Staff 等实体及其关系。
- 前端视图：集成 ECharts 进行图表渲染，提供周期选择、联动查询与可视化展示。
- 指标模板：内置多种科室类型的 BSC 指标模板，支撑不同维度权重与评分方法。
章节来源
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L17-L242)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L16-L300)
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L203)
- [frontend/src/views/reports/Reports.vue](file://frontend/src/views/reports/Reports.vue#L112-L309)
- [backend/app/scripts/init_templates.py](file://backend/app/scripts/init_templates.py#L24-L186)
## 架构总览
统计分析采用“接口-服务-模型-数据库”的分层架构，前端通过统一接口获取数据并渲染图表，后端通过异步查询与聚合函数实现高性能统计。
```mermaid
sequenceDiagram
participant FE as "前端视图"
participant API as "统计接口(stats.py)"
participant SVC as "统计服务(stats_service.py)"
participant DB as "数据库模型(models.py)"
FE->>API : GET /stats/bsc-dimension
API->>SVC : get_bsc_dimension_stats(...)
SVC->>DB : 异步查询 + 聚合(group_by)
DB-->>SVC : 维度统计结果
SVC-->>API : 维度得分/权重/指标数
API-->>FE : JSON 响应
FE->>API : GET /stats/department
API->>SVC : get_department_stats(...)
SVC->>DB : 异步查询 + 汇总(group_by)
DB-->>SVC : 科室统计结果
SVC-->>API : 排序后的科室列表
API-->>FE : JSON 响应
```
图表来源
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L17-L125)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L19-L146)
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L203)
## 详细组件分析
### BSC 维度分析
- 功能概述：按财务、客户、内部流程、学习成长四个维度统计得分、权重与指标数量，并计算平均得分。
- 数据来源：Assessment、AssessmentDetail、Indicator、Staff。
- 过滤条件：支持按年度、月份与科室过滤；仅统计已确认状态的考核记录。
- 聚合逻辑：按维度 group_by，计算维度总分（指标得分×权重求和）、总权重、指标数量，并推导平均得分。
```mermaid
flowchart TD
Start(["开始"]) --> BuildCond["构建查询条件<br/>状态=FINALIZED + 年/月/科室过滤"]
BuildCond --> Query["SQL 聚合查询<br/>按维度分组"]
Query --> Group["按维度汇总<br/>总分/权重/指标数"]
Group --> CalcAvg["计算平均得分=总分/权重"]
CalcAvg --> Return["返回维度统计结果"]
```
图表来源
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L19-L72)
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L203)
章节来源
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L17-L33)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L19-L72)
### 科室绩效统计
- 功能概述：按科室汇总员工得分，计算科室平均分、最高分、最低分、员工列表，并按平均分降序排序。
- 数据来源：Assessment、Staff、Department。
- 聚合逻辑：先按科室分组统计员工数与总分，再计算平均分，最后按平均分排序。
```mermaid
flowchart TD
S(["开始"]) --> Filter["过滤已确认考核记录<br/>按年/月过滤"]
Filter --> Join["连接 Staff/Department"]
Join --> GroupByDept["按科室分组统计<br/>员工数/总分/员工列表"]
GroupByDept --> ComputeAvg["计算平均分=总分/员工数"]
ComputeAvg --> Sort["按平均分降序排序"]
Sort --> Output["输出科室统计列表"]
```
图表来源
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L74-L146)
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L110)
章节来源
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L36-L49)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L74-L146)
### 趋势分析（月度）
- 功能概述：按月统计平均得分与加权得分，支持跨年份的最近 N 个月趋势。
- 数据来源：Assessment。
- 聚合逻辑：按月分组，计算平均分与样本数，按月升序排列。
```mermaid
flowchart TD
TStart(["开始"]) --> YearFilter["按年/月过滤<br/>或使用当前年份"]
YearFilter --> MonthRange["计算起止月份<br/>支持跨年"]
MonthRange --> GroupMonth["按月分组统计<br/>平均分/样本数"]
GroupMonth --> Order["按月升序排列"]
Order --> TOut["返回月度趋势数据"]
```
图表来源
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L148-L199)
章节来源
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L52-L70)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L148-L199)
### 绩效排名（科室/员工）
- 员工排名：按加权得分降序取前 N 名，附带排名序号。
- 科室排名：基于科室平均分降序取前 N 名。
- 数据来源：Assessment、Staff、Department。
```mermaid
sequenceDiagram
participant FE as "前端"
participant API as "统计接口"
participant SVC as "统计服务"
participant DB as "数据库"
FE->>API : GET /stats/ranking?limit=N
API->>SVC : get_ranking_stats(...)
SVC->>DB : 查询已确认考核记录并排序
DB-->>SVC : 员工排名结果
SVC-->>API : 带排名序号的列表
API-->>FE : JSON 响应
```
图表来源
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L210-L224)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L201-L244)
章节来源
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L186-L207)
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L210-L224)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L201-L244)
### 指标完成度统计
- 功能概述：按指标统计平均分、最大/最小分、完成率（平均分/目标值×100），并限制完成率上限为 100%。
- 数据来源：AssessmentDetail、Indicator。
- 聚合逻辑：按指标分组统计，计算完成率并返回指标列表。
```mermaid
flowchart TD
CStart(["开始"]) --> CFilter["过滤已确认考核记录<br/>可按年/月/指标过滤"]
CFilter --> CGroup["按指标分组统计<br/>平均分/最大分/最小分/样本数"]
CGroup --> CRate["计算完成率=平均分/目标值×100<br/>上限100%"]
CRate --> COut["返回指标完成度列表"]
```
图表来源
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L246-L299)
章节来源
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L227-L241)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L246-L299)
### 前端可视化与报表生成
- 报表视图 Reports.vue：周期统计概览、科室对比柱状图、绩效分布饼图、科室统计表格、员工排名表格。
- 仪表盘 Dashboard.vue：趋势折线、科室排名条形图、财务趋势、KPI 仪表盘、预警数据。
- ECharts 渲染：支持响应式布局与动态刷新，图表联动查询。
```mermaid
graph TB
subgraph "前端视图"
R["Reports.vue<br/>周期统计/科室对比/排名"]
D["Dashboard.vue<br/>趋势/KPI/预警"]
end
subgraph "接口封装"
FA["stats.js<br/>getDepartmentStats/getTrendData/..."]
end
R --> FA
D --> FA
```
图表来源
- [frontend/src/views/reports/Reports.vue](file://frontend/src/views/reports/Reports.vue#L112-L309)
- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue#L225-L819)
- [frontend/src/api/stats.js](file://frontend/src/api/stats.js#L1-L43)
章节来源
- [frontend/src/views/reports/Reports.vue](file://frontend/src/views/reports/Reports.vue#L1-L367)
- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue#L225-L819)
- [frontend/src/api/stats.js](file://frontend/src/api/stats.js#L1-L43)
## 依赖关系分析
- 统计接口依赖统计服务，统计服务依赖数据模型与 SQLAlchemy 异步查询。
- 前端视图依赖接口封装，接口封装依赖后端统计接口。
- 指标模板提供维度权重与评分方法，支撑 BSC 维度分析与指标完成度计算。
```mermaid
graph LR
API["stats.py"] --> SVC["stats_service.py"]
SVC --> MODELS["models.py"]
FE_VIEWS["Reports.vue / Dashboard.vue"] --> FE_API["stats.js"]
FE_API --> API
MODELS --> INIT_TPL["init_templates.py"]
```
图表来源
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L242)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
- [frontend/src/views/reports/Reports.vue](file://frontend/src/views/reports/Reports.vue#L1-L367)
- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue#L225-L819)
- [frontend/src/api/stats.js](file://frontend/src/api/stats.js#L1-L43)
- [backend/app/scripts/init_templates.py](file://backend/app/scripts/init_templates.py#L1-L276)
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L203)
- [backend/app/scripts/init_templates.py](file://backend/app/scripts/init_templates.py#L24-L186)
## 性能考虑
- 异步查询：使用 SQLAlchemy 异步引擎与会话，减少阻塞，提升并发处理能力。
- 索引优化：模型中为常用查询字段建立索引（如 staff/dept/status/period），降低查询成本。
- 聚合优化：在服务层使用 SQL 聚合函数（sum/count/avg/group_by）一次性完成统计，避免多次往返。
- 分页与限制：前端接口支持分页与数量限制，避免一次性传输大量数据。
- 缓存策略：对于静态模板与权重配置可在应用启动时缓存，减少重复读取。
- 数据分区：历史数据可按年/月分区存储，便于趋势分析与归档清理。
## 故障排除指南
- 接口返回空数据
- 检查过滤条件（年/月/科室）是否正确，确认存在已确认状态的考核记录。
- 确认前端传参格式与范围（如月份 1-12）。
- 统计结果异常
- 核对指标权重与目标值是否配置正确，确保完成率计算逻辑生效。
- 检查是否存在一票否决指标导致得分异常。
- 图表渲染问题
- 确认 ECharts 初始化与容器尺寸，监听窗口 resize 事件。
- 检查数据结构与键名一致性（如 avg_score、total_bonus）。
章节来源
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L246-L299)
- [frontend/src/views/reports/Reports.vue](file://frontend/src/views/reports/Reports.vue#L173-L295)
## 结论
本系统围绕 BSC 四维度与 KPI 指标，提供了完整的统计分析能力：按科室与人员的绩效统计、趋势分析与排名、指标完成度与可视化展示。通过异步查询与聚合优化，保障了性能与准确性；通过前端 ECharts 的丰富图表，提升了数据洞察力。建议后续进一步完善预警机制与报表导出功能，持续优化数据质量与用户体验。
## 附录
### 分析指标与计算公式
- BSC 维度得分
- 维度总分 = Σ(指标得分 × 指标权重)
- 维度平均分 = 维度总分 / 维度总权重
- 科室平均分
- 科室平均分 = 科室总分 / 科室员工数
- 指标完成度
- 完成率 = min(平均分 / 目标值 × 100%, 100%)
章节来源
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L20-L72)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L246-L299)
- [docs/详细设计文档.md](file://docs/详细设计文档.md#L312-L401)
### 可视化展示方案
- 科室对比柱状图：X 轴科室名称，Y 轴平均得分与右侧奖金折线。
- 绩效分布饼图：按等级划分（优秀/良好/合格/不合格）。
- 趋势折线图：月度平均得分与样本数。
- KPI 仪表盘：床位使用率、药占比、材料占比、患者满意度等关键指标。
章节来源
- [frontend/src/views/reports/Reports.vue](file://frontend/src/views/reports/Reports.vue#L183-L295)
- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue#L741-L807)
### 数据准确性保证
- 状态约束：仅统计已确认状态的考核记录，避免草稿/审核阶段数据干扰。
- 权重与目标值校验：模板初始化时写入权重与目标值，确保计算一致性。
- 一票否决：对严重质量与安全指标设置否决标记，确保结果真实可靠。
章节来源
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L203)
- [backend/app/scripts/init_templates.py](file://backend/app/scripts/init_templates.py#L24-L78)

431
.qoder/repowiki/zh/content/核心功能模块/绩效考核管理/考核流程管理.md Normal file
View File

@@ -0,0 +1,431 @@
# 考核流程管理
<cite>
**本文档引用的文件**
- [models.py](file://backend/app/models/models.py)
- [schemas.py](file://backend/app/schemas/schemas.py)
- [assessment_service.py](file://backend/app/services/assessment_service.py)
- [assessments.py](file://backend/app/api/v1/assessments.py)
- [assessment.js](file://frontend/src/api/assessment.js)
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue)
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue)
- [security.py](file://backend/app/core/security.py)
- [001_initial.py](file://backend/alembic/versions/001_initial.py)
- [002_template.py](file://backend/alembic/versions/002_template.py)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 简介
本系统是一个完整的医院绩效考核管理系统，专注于考核流程的全生命周期管理。系统实现了从草稿创建到最终确认的完整工作流，包括审批流转、复核确认、状态管理和权限控制等核心功能。
系统采用前后端分离架构，后端使用FastAPI提供RESTful API，前端使用Vue.js构建用户界面。数据库采用PostgreSQL，通过SQLAlchemy ORM进行数据持久化。
## 项目结构
系统采用典型的三层架构设计：
```mermaid
graph TB
subgraph "前端层"
FE_API[API封装层]
FE_VIEWS[视图组件]
FE_STORE[状态管理]
end
subgraph "后端层"
BE_ROUTER[路由层]
BE_SERVICE[服务层]
BE_MODEL[模型层]
BE_DB[(数据库)]
end
subgraph "基础设施"
AUTH[认证授权]
DB[(PostgreSQL)]
SCHEMA[数据模式]
end
FE_API --> FE_VIEWS
FE_VIEWS --> FE_STORE
FE_API --> BE_ROUTER
BE_ROUTER --> BE_SERVICE
BE_SERVICE --> BE_MODEL
BE_MODEL --> BE_DB
BE_DB --> DB
AUTH --> BE_ROUTER
SCHEMA --> BE_MODEL
```
**图表来源**
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
- [assessment.js](file://frontend/src/api/assessment.js#L1-L50)
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
**章节来源**
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
- [assessment.js](file://frontend/src/api/assessment.js#L1-L50)
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
## 核心组件
### 数据模型层
系统的核心数据模型围绕考核流程展开，主要包括以下关键实体：
```mermaid
classDiagram
class Assessment {
+int id
+int staff_id
+int period_year
+int period_month
+str status
+float total_score
+float weighted_score
+datetime submit_time
+datetime review_time
+int assessor_id
+int reviewer_id
+str remark
}
class AssessmentDetail {
+int id
+int assessment_id
+int indicator_id
+float actual_value
+float score
+str evidence
+str remark
}
class Staff {
+int id
+str employee_id
+str name
+int department_id
+str position
+str status
+float performance_ratio
}
class Indicator {
+int id
+str name
+str code
+str indicator_type
+float weight
+float max_score
+bool is_active
}
Assessment "1" -- "many" AssessmentDetail : contains
Assessment "1" -- "1" Staff : evaluates
AssessmentDetail "1" -- "1" Indicator : measures
Staff "1" -- "many" Assessment : creates
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L149-L202)
- [models.py](file://backend/app/models/models.py#L181-L202)
- [models.py](file://backend/app/models/models.py#L88-L114)
- [models.py](file://backend/app/models/models.py#L117-L147)
### 状态枚举定义
系统定义了完整的考核状态流转：
```mermaid
stateDiagram-v2
[*] --> 草稿
草稿 --> 已提交 : 提交申请
已提交 --> 已审核 : 审核通过
已提交 --> 已驳回 : 审核驳回
已审核 --> 已确认 : 确认完成
已确认 --> [*]
已驳回 --> 草稿 : 修改后重新提交
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L45-L51)
**章节来源**
- [models.py](file://backend/app/models/models.py#L45-L51)
- [schemas.py](file://backend/app/schemas/schemas.py#L31-L36)
## 架构概览
系统采用RESTful API设计模式，前后端通过HTTP协议通信：
```mermaid
sequenceDiagram
participant Client as 前端客户端
participant API as API网关
participant Service as 服务层
participant Model as 模型层
participant DB as 数据库
Client->>API : GET /assessments
API->>Service : get_list()
Service->>Model : 查询评估记录
Model->>DB : SQL查询
DB-->>Model : 查询结果
Model-->>Service : 评估记录列表
Service-->>API : 处理后的数据
API-->>Client : JSON响应
Note over Client,DB : 异步数据库操作
```
**图表来源**
- [assessments.py](file://backend/app/api/v1/assessments.py#L20-L52)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L18-L55)
## 详细组件分析
### 考核流程状态管理
#### 草稿状态（Draft）
草稿状态是考核流程的初始阶段，允许员工录入和编辑考核信息：
**操作权限控制：**
- 仅考核人本人可编辑
- 支持保存草稿和提交申请
- 可修改考核明细和备注
**数据验证规则：**
- 总分 = 各指标得分之和
- 加权得分 = Σ(指标得分 × 指标权重)
- 实际值必须符合指标最大值限制
#### 已提交状态（Submitted）
已提交状态表示考核已进入审批流程：
**审批权限控制：**
- 需要管理员或经理权限
- 自动记录提交时间和提交人
- 系统自动计算加权得分
**业务逻辑：**
- 审批前自动刷新计算结果
- 支持通过或驳回两种处理方式
- 记录审核人和审核时间
#### 已审核状态（Reviewed）
已审核状态表示考核通过审批，等待最终确认：
**权限控制：**
- 管理员或经理可进行最终确认
- 系统自动锁定后续修改
- 生成最终的加权得分
**数据完整性：**
- 确认后状态不可逆
- 用于后续薪资计算的基础数据
#### 已确认状态（Finalized）
已确认状态表示考核流程完成：
**系统影响：**
- 考核结果正式生效
- 用于薪资核算的数据源
- 不再允许任何修改操作
#### 已驳回状态（Rejected）
已驳回状态表示考核被拒绝：
**处理机制：**
- 自动退回至草稿状态
- 允许重新编辑和提交
- 记录驳回原因和时间
**章节来源**
- [assessment_service.py](file://backend/app/services/assessment_service.py#L117-L205)
- [assessments.py](file://backend/app/api/v1/assessments.py#L105-L145)
### 前端交互组件
#### 考核列表页面
```mermaid
flowchart TD
Start([页面加载]) --> LoadData[加载考核数据]
LoadData --> RenderTable[渲染表格]
RenderTable --> CheckStatus{检查状态}
CheckStatus --> |草稿| ShowDraftOps[显示提交按钮]
CheckStatus --> |已提交| ShowReviewOps[显示审核按钮]
CheckStatus --> |已审核| ShowFinalizeOp[显示确认按钮]
CheckStatus --> |其他| HideOps[隐藏操作按钮]
ShowDraftOps --> SubmitAssessment[提交考核]
ShowReviewOps --> ReviewAssessment[审核考核]
ShowFinalizeOp --> FinalizeAssessment[确认考核]
SubmitAssessment --> RefreshData[刷新数据]
ReviewAssessment --> RefreshData
FinalizeAssessment --> RefreshData
RefreshData --> RenderTable
```
**图表来源**
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L55-L63)
**章节来源**
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L257)
### API接口设计
系统提供了完整的RESTful API接口：
| 接口 | 方法 | 权限 | 功能描述 |
|------|------|------|----------|
| `/assessments` | GET | 任意用户 | 获取考核列表 |
| `/assessments/{id}` | GET | 任意用户 | 获取考核详情 |
| `/assessments` | POST | 任意用户 | 创建考核记录 |
| `/assessments/{id}` | PUT | 任意用户 | 更新考核记录 |
| `/assessments/{id}/submit` | POST | 任意用户 | 提交考核 |
| `/assessments/{id}/review` | POST | 管理员/经理 | 审核考核 |
| `/assessments/{id}/finalize` | POST | 管理员/经理 | 确认考核 |
| `/assessments/batch-create` | POST | 管理员/经理 | 批量创建考核 |
**章节来源**
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
## 依赖关系分析
系统的关键依赖关系如下：
```mermaid
graph LR
subgraph "认证层"
Security[security.py]
User[User模型]
end
subgraph "服务层"
AssessmentService[AssessmentService]
StaffService[StaffService]
IndicatorService[IndicatorService]
end
subgraph "数据层"
Assessment[Assessment模型]
AssessmentDetail[AssessmentDetail模型]
Staff[Staff模型]
Indicator[Indicator模型]
end
subgraph "API层"
AssessmentAPI[Assessments路由]
StaffAPI[Staff路由]
IndicatorAPI[Indicator路由]
end
Security --> AssessmentAPI
AssessmentAPI --> AssessmentService
AssessmentService --> Assessment
AssessmentService --> AssessmentDetail
AssessmentService --> Staff
AssessmentService --> Indicator
AssessmentAPI --> Assessment
AssessmentAPI --> Staff
AssessmentAPI --> Indicator
```
**图表来源**
- [security.py](file://backend/app/core/security.py#L94-L109)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
**章节来源**
- [security.py](file://backend/app/core/security.py#L1-L110)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
## 性能考虑
### 数据库优化
系统采用了多项数据库优化策略：
1. **索引优化**：为常用查询字段建立索引
- `idx_assessment_status`：状态查询优化
- `idx_assessment_period`：周期查询优化
- `idx_assessment_staff`：员工查询优化
2. **查询优化**：使用`selectinload`避免N+1查询问题
3. **分页查询**：支持大数据量的分页展示
### 缓存策略
虽然当前实现未使用缓存，但系统设计支持未来扩展：
- 可以引入Redis缓存热门查询结果
- 考核状态统计信息可以缓存
- 用户权限信息可以本地缓存
### 并发控制
系统通过以下机制保证数据一致性：
1. **事务管理**：所有状态变更都在事务中执行
2. **乐观锁**：使用版本号防止并发修改冲突
3. **状态检查**：每次操作前验证当前状态
## 故障排除指南
### 常见问题及解决方案
#### 状态转换异常
**问题现象：** 点击提交按钮无反应
**可能原因：**
1. 当前状态不是草稿状态
2. 用户权限不足
3. 网络请求超时
**解决步骤：**
1. 检查考核记录状态
2. 验证用户角色权限
3. 查看浏览器开发者工具Network标签
4. 检查后端日志
#### 数据不一致
**问题现象：** 显示的总分与实际不符
**排查步骤：**
1. 检查指标权重设置
2. 验证分数输入范围
3. 确认计算公式正确性
4. 查看数据库中存储的原始数据
#### 权限问题
**问题现象：** 无法看到某些操作按钮
**解决方法：**
1. 检查用户角色设置
2. 确认当前用户的权限
3. 刷新页面重新登录
4. 检查系统配置
**章节来源**
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L227-L255)
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L177-L213)
## 结论
本考核流程管理系统实现了完整的绩效考核生命周期管理，具有以下特点：
1. **完整的状态管理**：覆盖从草稿到最终确认的全流程
2. **严格的权限控制**：基于角色的细粒度权限管理
3. **清晰的业务逻辑**：每个状态都有明确的操作规则
4. **良好的用户体验**：直观的前端界面和实时的状态反馈
5. **可扩展的设计**：模块化的架构便于功能扩展
系统通过标准化的API接口和清晰的业务流程，为医院的绩效管理提供了可靠的技术支撑。建议在未来版本中增加更多的监控和审计功能，以及移动端支持。

326
.qoder/repowiki/zh/content/核心功能模块/绩效考核管理/考核详情查看.md Normal file
View File

@@ -0,0 +1,326 @@
# 考核详情查看
<cite>
**本文档引用的文件**
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue)
- [assessment.js](file://frontend/src/api/assessment.js)
- [assessments.py](file://backend/app/api/v1/assessments.py)
- [assessment_service.py](file://backend/app/services/assessment_service.py)
- [models.py](file://backend/app/models/models.py)
- [schemas.py](file://backend/app/schemas/schemas.py)
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue)
- [security.py](file://backend/app/core/security.py)
- [001_initial.py](file://backend/alembic/versions/001_initial.py)
- [详细设计.md](file://docs/详细设计.md)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本章节面向“考核详情查看”功能，系统性阐述考核记录的详细信息展示、员工与科室信息、考核周期、各项指标得分与总分计算、加权得分计算公式、权重配置与分数等级划分、考核明细展示格式、数据来源与更新机制，并补充权限控制与数据安全保护措施。文档同时提供界面布局示意、数据流图与序列图，帮助前后端开发者与产品人员快速理解与实现。
## 项目结构
本功能涉及前后端协同：
- 前端负责详情页面渲染、交互与权限控制提示
- 后端提供REST API、服务层计算与数据库持久化
- 数据模型定义了考核记录、明细、指标与状态枚举
- 安全模块提供认证与授权中间件
```mermaid
graph TB
FE["前端<br/>AssessmentDetail.vue"] --> API["后端API<br/>assessments.py"]
API --> SVC["服务层<br/>assessment_service.py"]
SVC --> DB["数据库模型<br/>models.py"]
API --> SEC["安全中间件<br/>security.py"]
```
图表来源
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L257)
- [assessments.py](file://backend/app/api/v1/assessments.py#L55-L77)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L58-L68)
- [models.py](file://backend/app/models/models.py#L149-L203)
- [security.py](file://backend/app/core/security.py#L55-L110)
章节来源
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L257)
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [models.py](file://backend/app/models/models.py#L1-L438)
- [security.py](file://backend/app/core/security.py#L1-L110)
## 核心组件
- 前端详情视图：展示基本信息、考核明细、状态标签与操作按钮，支持草稿态编辑与保存、提交、审核、确认等流程操作。
- 后端API：提供获取详情、更新、提交、审核、确认等接口，并在权限控制下限制操作范围。
- 服务层：负责业务逻辑，包括加权得分计算、状态流转、批量创建等。
- 数据模型：定义考核记录、明细、指标、状态与类型枚举，以及外键关系。
- 安全模块：提供JWT解析、当前用户获取、管理员/经理权限校验。
章节来源
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L98-L218)
- [assessments.py](file://backend/app/api/v1/assessments.py#L55-L145)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L70-L205)
- [models.py](file://backend/app/models/models.py#L45-L61)
- [security.py](file://backend/app/core/security.py#L85-L110)
## 架构总览
详情查看流程由前端发起请求，后端API接收并调用服务层，服务层读取数据库模型并返回数据，前端渲染详情卡片与明细表格，支持在草稿态编辑与提交审核。
```mermaid
sequenceDiagram
participant U as "用户"
participant FE as "前端详情页面"
participant API as "后端API"
participant SVC as "服务层"
participant DB as "数据库模型"
U->>FE : 打开考核详情
FE->>API : GET /assessments/{id}
API->>SVC : get_by_id(assessment_id)
SVC->>DB : 查询Assessment+Staff+Details+Indicator
DB-->>SVC : 返回实体
SVC-->>API : AssessmentResponse
API-->>FE : JSON数据
FE->>FE : 渲染基本信息与明细
FE->>API : 草稿态保存/提交/审核/确认
API->>SVC : update/submit/review/finalize
SVC->>DB : 更新状态与分数
DB-->>SVC : 提交事务
SVC-->>API : 成功
API-->>FE : 返回结果
```
图表来源
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L150-L217)
- [assessment.js](file://frontend/src/api/assessment.js#L9-L36)
- [assessments.py](file://backend/app/api/v1/assessments.py#L55-L145)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L58-L205)
- [models.py](file://backend/app/models/models.py#L149-L203)
## 详细组件分析
### 前端详情视图（AssessmentDetail.vue）
- 基本信息卡片：显示员工姓名、科室、考核周期与加权总分，状态以标签形式展示。
- 考核明细表格：展示指标名称、类型、权重、最高分、实际值、得分、佐证材料；草稿态支持输入编辑，其他状态只读并按得分分级显示颜色。
- 操作按钮：根据状态显示保存、提交、审核通过/驳回、确认等按钮，点击后调用对应API。
```mermaid
flowchart TD
Start(["进入详情页面"]) --> Load["加载考核详情"]
Load --> Render["渲染基本信息与明细"]
Render --> EditCheck{"是否草稿态？"}
EditCheck --> |是| Edit["可编辑输入实际值/得分/佐证材料"]
EditCheck --> |否| View["只读显示"]
Edit --> Save["保存草稿"]
Edit --> Submit["提交审核"]
View --> Review["审核通过/驳回"]
View --> Finalize["确认考核"]
Save --> Reload["重新加载数据"]
Submit --> Reload
Review --> Reload
Finalize --> Reload
Reload --> End(["完成"])
```
图表来源
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L150-L217)
章节来源
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L257)
### 后端API与服务层（assessments.py、assessment_service.py）
- 获取详情：API层调用服务层按ID查询，返回带员工与科室名称、明细含指标名称的结构化数据。
- 加权得分计算：服务层在创建/更新时，遍历明细，按指标权重累加计算 weighted_score。
- 状态流转：提交、审核、确认分别更新状态与时间戳，仅允许在合法状态下变更。
- 批量创建：为指定科室批量生成考核记录与明细，避免重复。
```mermaid
classDiagram
class Assessment {
+int id
+int staff_id
+int period_year
+int period_month
+string period_type
+float total_score
+float weighted_score
+string status
+int assessor_id
+int reviewer_id
+datetime submit_time
+datetime review_time
+string remark
}
class AssessmentDetail {
+int id
+int assessment_id
+int indicator_id
+float actual_value
+float score
+string evidence
+string remark
}
class Indicator {
+int id
+string name
+string code
+string indicator_type
+float weight
+float max_score
}
Assessment "1" o-- "*" AssessmentDetail : "明细"
AssessmentDetail "1" --> "1" Indicator : "指标"
```
图表来源
- [models.py](file://backend/app/models/models.py#L149-L203)
章节来源
- [assessments.py](file://backend/app/api/v1/assessments.py#L55-L77)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L70-L156)
- [models.py](file://backend/app/models/models.py#L149-L203)
### 数据模型与字段说明
- 考核记录表（assessments）：包含员工ID、考核周期、总分、加权得分、状态、时间戳与备注。
- 考核明细表（assessment_details）：包含指标ID、实际值、得分、佐证材料与备注。
- 指标表（indicators）：包含指标名称、编码、类型、权重、最高分、目标值等。
- 状态枚举：草稿、已提交、已审核、已确认、已驳回。
章节来源
- [models.py](file://backend/app/models/models.py#L45-L61)
- [models.py](file://backend/app/models/models.py#L149-L203)
- [001_initial.py](file://backend/alembic/versions/001_initial.py#L87-L131)
### 权限控制与数据安全
- 当前用户获取：通过JWT令牌解析当前用户，校验激活状态。
- 管理员/经理权限：审核与确认接口要求管理员或经理角色。
- 列表与详情：详情接口对当前用户可见性进行校验，防止越权访问。
章节来源
- [security.py](file://backend/app/core/security.py#L55-L110)
- [assessments.py](file://backend/app/api/v1/assessments.py#L118-L145)
## 依赖关系分析
- 前端依赖后端API，通过HTTP请求获取数据并提交操作。
- 后端API依赖服务层，服务层依赖SQLAlchemy ORM与数据库模型。
- 安全中间件贯穿API层，确保敏感操作受控。
```mermaid
graph LR
FE["前端"] --> API["后端API"]
API --> SVC["服务层"]
SVC --> MODELS["数据模型"]
API --> SEC["安全中间件"]
```
图表来源
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L102-L102)
- [assessment.js](file://frontend/src/api/assessment.js#L9-L36)
- [assessments.py](file://backend/app/api/v1/assessments.py#L55-L145)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L58-L68)
- [models.py](file://backend/app/models/models.py#L149-L203)
- [security.py](file://backend/app/core/security.py#L55-L110)
章节来源
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L257)
- [assessment.js](file://frontend/src/api/assessment.js#L1-L50)
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [models.py](file://backend/app/models/models.py#L1-L438)
- [security.py](file://backend/app/core/security.py#L1-L110)
## 性能考虑
- 查询优化：详情查询使用selectinload预加载关联对象，减少N+1查询。
- 分页与过滤：列表接口支持按科室、周期、状态分页查询，避免一次性加载过多数据。
- 缓存策略：可在高频读取场景引入Redis缓存，降低数据库压力。
- 前端渲染：明细表格按需渲染，草稿态编辑采用双向绑定，减少不必要的重绘。
章节来源
- [assessment_service.py](file://backend/app/services/assessment_service.py#L28-L55)
- [assessments.py](file://backend/app/api/v1/assessments.py#L20-L52)
## 故障排查指南
- 404未找到：详情接口若返回不存在，检查assessment_id是否正确。
- 状态不允许：更新、提交、审核、确认仅在特定状态允许，检查当前状态与流程。
- 权限不足：审核与确认接口需要管理员或经理权限，检查用户角色。
- 数据异常：加权得分异常时，检查指标权重与明细得分是否匹配。
章节来源
- [assessments.py](file://backend/app/api/v1/assessments.py#L63-L64)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L117-L118)
- [security.py](file://backend/app/core/security.py#L94-L109)
## 结论
“考核详情查看”功能通过前后端协作，实现了从数据到界面的完整闭环：前端负责展示与交互，后端负责数据与流程控制，服务层承担计算与状态管理，安全模块提供权限保障。加权得分计算清晰、权重配置灵活、状态流转可控，满足医院绩效管理的精细化需求。
## 附录
### 考核详情展示格式
- 基本信息
- 姓名、科室、考核周期、加权总分
- 考核明细
- 指标名称、指标类型、权重、最高分、实际值、得分、佐证材料
- 状态标签与操作按钮
- 草稿态：保存、提交
- 已提交：审核通过、驳回
- 已审核：确认
- 已确认：不可编辑
章节来源
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L18-L93)
### 加权得分计算公式与权重配置
- 加权得分（weighted_score）= Σ(指标得分 × 指标权重)
- 权重来源于指标表（indicators.weight），创建/更新时由服务层遍历明细累加计算
- 最高分（max_score）用于前端输入校验与显示
章节来源
- [assessment_service.py](file://backend/app/services/assessment_service.py#L76-L84)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L140-L146)
- [models.py](file://backend/app/models/models.py#L126-L127)
### 分数等级划分
- 优秀：≥90分
- 良好：80-89分
- 一般：60-79分
- 较差：<60分
章节来源
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L139-L144)
### 数据来源与更新机制
- 数据来源：指标库（indicators）、考核记录（assessments）、明细（assessment_details）
- 更新机制：草稿态可编辑并保存；提交后进入审核流程；审核通过进入确认；最终确认后不可再编辑
章节来源
- [models.py](file://backend/app/models/models.py#L149-L203)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L158-L205)
### 权限控制与数据安全
- 认证：JWT令牌解析与当前用户校验
- 授权：管理员/经理角色才能审核与确认
- 可见性：详情接口对当前用户可见性进行校验
章节来源
- [security.py](file://backend/app/core/security.py#L55-L110)
- [assessments.py](file://backend/app/api/v1/assessments.py#L118-L145)
### 相关接口与数据模型对照
- 获取详情：GET /assessments/{id}
- 更新详情：PUT /assessments/{id}
- 提交：POST /assessments/{id}/submit
- 审核：POST /assessments/{id}/review
- 确认：POST /assessments/{id}/finalize
- 批量创建：POST /assessments/batch-create
章节来源
- [assessment.js](file://frontend/src/api/assessment.js#L9-L49)
- [assessments.py](file://backend/app/api/v1/assessments.py#L55-L165)