Files

2026-02-28 15:16:15 +08:00

15 KiB

Raw Blame History

员工管理接口

**本文档引用的文件** - [staff.py](file://backend/app/api/v1/staff.py) - [staff_service.py](file://backend/app/services/staff_service.py) - [models.py](file://backend/app/models/models.py) - [schemas.py](file://backend/app/schemas/schemas.py) - [security.py](file://backend/app/core/security.py) - [database.py](file://backend/app/core/database.py) - [staff.js](file://frontend/src/api/staff.js) - [Staff.vue](file://frontend/src/views/basic/Staff.vue) - [request.js](file://frontend/src/api/request.js) - [api.md](file://docs/api.md) - [backend.md](file://docs/backend.md)

简介

员工管理接口是医院绩效考核管理系统的核心功能模块，负责员工信息的完整生命周期管理。该系统采用现代化的前后端分离架构，后端基于FastAPI和SQLAlchemy，前端使用Vue.js和Element Plus，实现了完整的员工信息管理功能。

系统支持员工信息的增删改查、多条件筛选、分页查询、状态管理等功能，并集成了完善的权限控制机制和数据验证体系。

项目结构

graph TB
subgraph "后端架构"
A[API路由层] --> B[服务层]
B --> C[数据模型层]
C --> D[数据库]
A --> E[安全认证]
E --> F[JWT令牌]
G[前端界面] --> H[API接口]
H --> A
end
subgraph "核心模块"
I[员工管理] --> J[科室关联]
K[权限控制] --> L[角色管理]
M[数据验证] --> N[Pydantic模式]
end

图表来源

章节来源

核心组件

后端核心组件

系统采用经典的三层架构模式，包含以下核心组件：

API路由层：处理HTTP请求和响应，实现RESTful接口
服务层：封装业务逻辑，提供数据访问服务
数据模型层：定义数据库表结构和关系映射
安全认证层：实现JWT令牌认证和权限控制

前端核心组件

前端采用Vue.js单页面应用架构：

员工管理界面：提供员工信息的CRUD操作界面
数据表格组件：展示员工列表和操作功能
表单组件：处理员工信息的输入和验证
API客户端：封装HTTP请求和响应处理

章节来源

架构概览

sequenceDiagram
participant Client as 客户端
participant Frontend as 前端界面
participant API as API路由
participant Service as 服务层
participant Model as 数据模型
participant DB as 数据库
Client->>Frontend : 用户操作
Frontend->>API : HTTP请求
API->>Service : 业务逻辑调用
Service->>Model : 数据查询/更新
Model->>DB : SQL操作
DB-->>Model : 查询结果
Model-->>Service : 数据对象
Service-->>API : 处理结果
API-->>Frontend : JSON响应
Frontend-->>Client : 界面更新

图表来源

详细组件分析

员工管理API路由

员工管理API路由实现了完整的RESTful接口，包含以下主要功能：

GET /staff - 获取员工列表

支持多条件筛选和分页查询：

department_id：按科室ID筛选
status：按员工状态筛选
keyword：按姓名或工号模糊搜索
page：页码，默认1
page_size：每页数量，默认20，最大100

GET /staff/{id} - 获取员工详情

根据员工ID获取详细信息，包含科室名称关联。

POST /staff - 创建员工

需要管理员或经理权限，支持批量创建。

PUT /staff/{id} - 更新员工

需要管理员或经理权限，支持部分字段更新。

DELETE /staff/{id} - 删除员工

需要管理员或经理权限。

GET /staff/department/{department_id} - 获取科室员工

获取指定科室的所有在职员工。

章节来源

staff.py

服务层实现

服务层提供了员工数据访问和业务逻辑处理：

核心方法

get_list()：实现多条件查询和分页
get_by_id()：按ID获取员工信息
get_by_employee_id()：按工号查询唯一员工
create()：创建新员工记录
update()：更新员工信息
delete()：删除员工记录
get_by_department()：获取科室员工列表

查询优化

使用selectinload预加载关联的科室信息
实现条件动态构建，支持多种筛选组合
使用子查询统计总数，提高分页查询性能

章节来源

staff_service.py

数据模型设计

员工数据模型采用SQLAlchemy ORM映射：

classDiagram
class Staff {
+int id
+string employee_id
+string name
+int department_id
+string position
+string title
+string phone
+string email
+float base_salary
+float performance_ratio
+StaffStatus status
+datetime hire_date
+datetime created_at
+datetime updated_at
+department Department
+assessments List[Assessment]
+salary_records List[SalaryRecord]
}
class Department {
+int id
+string name
+string code
+DeptType dept_type
+int parent_id
+int level
+int sort_order
+bool is_active
+string description
+datetime created_at
+datetime updated_at
+parent Department
+staff List[Staff]
}
Staff --> Department : "属于"

图表来源

章节来源

models.py

数据模型

员工信息字段

字段名	类型	必填	描述	默认值
id	int	否	员工ID	自增
employee_id	string	是	工号	唯一约束
name	string	是	姓名	-
department_id	int	是	所属科室ID	-
position	string	是	职位	-
title	string	否	职称	-
phone	string	否	联系电话	-
email	string	否	邮箱	-
base_salary	float	是	基本工资	0
performance_ratio	float	是	绩效系数	1.0
status	enum	是	员工状态	active
hire_date	datetime	否	入职日期	-
created_at	datetime	否	创建时间	当前时间
updated_at	datetime	否	更新时间	当前时间

员工状态枚举

stateDiagram-v2
[*] --> ACTIVE
ACTIVE --> LEAVE : 休假
LEAVE --> ACTIVE : 返回
ACTIVE --> RESIGNED : 离职
ACTIVE --> RETIRED : 退休
RESIGNED --> [*]
RETIRED --> [*]

图表来源

models.py

章节来源

API接口规范

通用响应格式

所有API接口遵循统一的响应格式：

{
  "code": 200,
  "message": "success",
  "data": {},
  "total": 0,
  "page": 1,
  "page_size": 20
}