提交文件

2026-02-28 15:16:15 +08:00
parent 1a4e50e0a4
commit 44f250f58e
159 changed files with 61268 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/核心功能模块/基础数据管理/员工管理.md
+++ b/.qoder/repowiki/zh/content/核心功能模块/基础数据管理/员工管理.md
@@ -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)