Files

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

14 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) - [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)

简介

本文件面向医院绩效系统的“员工管理”功能，系统化梳理员工信息的完整生命周期管理：从基本信息录入（姓名、性别、身份证号、联系方式）、职位与职称配置、基本工资与绩效系数设置，到所属科室关联、状态管理（在职、休假、离职、退休），以及部门调动、岗位变更等业务场景。同时覆盖员工档案维护、列表展示、搜索筛选、分页加载、数据同步、权限控制与数据验证规则，并给出批量导入导出、数据校验与异常处理建议。

项目结构

后端采用 FastAPI + SQLAlchemy 异步 ORM，前端采用 Vue 3 + Element Plus，通过 Axios 封装的请求模块统一访问后端 API。员工管理涉及以下关键模块：

后端 API 路由：负责接收请求、鉴权与返回标准化响应
服务层：封装业务逻辑，处理查询、分页、过滤与数据组装
数据模型：定义员工表结构、枚举类型与索引约束
数据模式：定义请求/响应的数据结构与字段校验
安全模块：提供 JWT 认证、权限校验（管理员/经理）
前端页面：员工列表、搜索筛选、分页、弹窗表单、增删改操作
前端 API 封装：统一请求与响应拦截、错误处理

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"]

图表来源

章节来源

核心组件

员工数据模型：包含工号、姓名、所属科室、职位、职称、联系方式、基本工资、绩效系数、状态、入职日期等字段，并定义了状态枚举与索引
员工数据模式：定义创建、更新、响应的数据结构与字段范围校验
员工服务层：提供列表查询、详情查询、按工号查询、创建、更新、删除、按科室查询等功能
员工 API 路由：提供获取列表、详情、创建、更新、删除、按科室查询接口，并集成权限校验
前端页面：员工列表、搜索筛选、分页、弹窗表单、增删改操作
前端 API 封装：统一请求头、Token 注入、错误拦截与提示
安全模块：JWT 解析、当前用户获取、活跃用户校验、管理员/经理权限校验

章节来源

架构总览

员工管理的端到端流程如下：

前端发起请求（含 Token），经请求拦截器注入 Authorization
后端 API 路由解析请求参数，进行权限校验（管理员/经理）
服务层执行数据库查询/写入，组装响应数据
返回标准化响应（code/message/data/total/page/page_size）

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)

图表来源

章节来源

详细组件分析

数据模型与字段设计

员工表字段覆盖基本信息、职位职称、联系方式、薪资与绩效、状态与时间戳
状态枚举支持在职、休假、离职、退休；索引覆盖科室与状态，便于查询与筛选
外键关联科室表，支持联表查询并返回科室名称

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 : "所属科室"

图表来源

章节来源

数据模式与校验

员工创建模式：必填字段（工号、姓名、部门、职位），默认状态为在职，基本工资与绩效系数带范围校验
员工更新模式：允许部分字段更新，数值字段带范围校验
员工响应模式：包含基础字段与部门名称扩展字段

章节来源

schemas.py

服务层逻辑

列表查询：支持按科室、状态、关键词（姓名/工号）过滤，分页与总数统计，联表加载科室名称
详情查询：按ID查询并联表加载科室
按工号查询：用于唯一性校验
创建/更新/删除：封装 CRUD 操作，返回实体或布尔结果

章节来源

staff_service.py

API 路由与权限控制

获取列表：支持分页、过滤、关键词搜索，返回标准化分页响应
获取详情：返回员工详情并附加科室名称
创建/更新/删除：仅管理员或经理可操作，创建前进行工号唯一性校验
按科室查询：返回指定科室下的在职员工列表

章节来源

前端页面与交互

列表展示：支持按关键字（姓名/工号）、科室树选择、状态筛选
分页加载：支持页码与每页数量切换
弹窗表单：支持新增/编辑，必填字段校验，数值范围校验
数据同步：调用后端 API 获取数据并刷新表格

章节来源

数据验证与业务规则

员工唯一性：工号唯一，创建时进行重复校验
字段范围：基本工资与绩效系数带最小/最大值限制
状态枚举：仅允许预定义状态值
分页范围：每页数量限制在 1~100

章节来源

权限控制机制

当前用户获取：从 JWT 中解析用户ID并查询用户
活跃用户校验：仅允许激活用户访问
管理员/经理权限：创建/更新/删除接口要求管理员或经理角色

章节来源

security.py

员工状态管理与业务场景

状态枚举：在职、休假、离职、退休
列表查询：支持按状态过滤
按科室查询：默认仅返回在职员工
业务场景建议：
- 部门调动：更新员工所属科室字段
- 岗位变更：更新职位/职称字段
- 状态变更：更新状态字段（如休假/退休）

章节来源

员工档案维护与数据同步

前端通过 API 获取员工列表与详情，支持分页与筛选
表单提交后刷新列表，确保前后端数据一致
错误拦截：统一处理 401/403/404/500 等状态码并提示

章节来源

批量导入导出（建议实现）

导入：建议提供 Excel 模板，后端解析并批量校验与入库，支持事务回滚与错误行定位
导出：按筛选条件导出 Excel，包含工号、姓名、科室、职位、职称、基本工资、绩效系数、状态等字段
注意：导入需严格校验字段格式、唯一性与范围约束，避免破坏现有数据

（本节为通用实现建议，不直接对应具体源码）

依赖关系分析

前端依赖后端 API 提供的标准化响应结构
后端 API 依赖安全模块进行权限校验
服务层依赖数据模型进行数据库操作
前端 API 封装统一处理请求头与错误拦截

graph LR
FE_API["前端API封装"] --> BE_API["后端API"]
BE_API --> SEC["安全模块"]
BE_API --> SVC["服务层"]
SVC --> MODELS["数据模型"]

图表来源

章节来源

性能考量

查询优化：列表查询使用联表加载科室名称，注意在大数据量场景下对过滤字段建立索引
分页策略：每页数量上限为 100，避免一次性返回过多数据
缓存建议：高频查询（如科室树）可在前端缓存，减少重复请求
并发与事务：批量导入建议使用事务，失败回滚保证一致性

（本节为通用性能建议，不直接对应具体源码）

故障排查指南

登录过期：响应拦截器检测 401 自动跳转登录
权限不足：403 提示需要管理员或经理权限
资源不存在：404 提示对象不存在
服务器错误：500 提示服务器错误
前端表单校验：必填字段与数值范围校验失败会阻止提交
后端唯一性冲突：创建时若工号重复会返回错误

章节来源

结论

员工管理模块在后端提供了完善的 CRUD、权限控制与数据校验，在前端实现了友好的列表展示、搜索筛选与分页体验。结合现有数据模型与服务层能力，可稳定支撑员工信息的全生命周期管理。建议后续补充批量导入导出能力与更丰富的状态流转场景，以进一步提升系统实用性与可维护性。

附录

API 规范（摘自文档）

获取员工列表：支持按科室、状态、关键词过滤，返回分页数据
创建员工：必填字段与范围校验，工号唯一
更新/删除：管理员/经理权限
按科室查询：返回指定科室在职员工

章节来源

api.md

数据库表结构（摘自文档）

员工表字段与索引：包含工号唯一、基本工资与绩效系数范围、状态枚举、科室外键等
科室表字段与索引：支持树形结构与类型枚举

章节来源

14 KiB Raw Blame History Unescape Escape

员工管理

目录

简介

项目结构

核心组件

架构总览

详细组件分析

数据模型与字段设计

数据模式与校验

服务层逻辑

API 路由与权限控制

前端页面与交互

数据验证与业务规则

权限控制机制

员工状态管理与业务场景

员工档案维护与数据同步

批量导入导出（建议实现）

依赖关系分析

性能考量

故障排查指南

结论

附录

API 规范（摘自文档）

数据库表结构（摘自文档）

14 KiB

Raw Blame History