提交文件

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