源丰后端 API

Appearance

员工管理 ​

员工管理模块提供企业员工的创建、查询、更新、删除等功能，支持完整的员工档案管理。

接口概览 ​

方法路径描述权限要求
POST/api/v1/admin/employees创建员工管理员
GET/api/v1/admin/employees获取员工列表管理员
GET/api/v1/admin/employees/{id}获取员工详情管理员
PUT/api/v1/admin/employees/{id}更新员工信息管理员
DELETE/api/v1/admin/employees/{id}删除员工管理员
GET/api/v1/admin/employees/{id}/role-company获取员工角色和公司信息管理员
GET/api/v1/employees/my/role-company获取当前员工的角色和公司信息登录用户
GET/api/v1/companies/{id}/employees获取指定公司的员工列表登录用户

创建员工 ​

创建新的员工档案。

接口信息 ​

  • URL: /api/v1/admin/employees
  • 方法: POST
  • 内容类型: application/json
  • 认证: 需要管理员权限

请求参数 ​

字段类型必填描述示例
user_idint是关联的用户ID1
employee_nostring是员工工号"EMP001"
first_namestring是名字"John"
last_namestring是姓氏"Doe"
emailstring是邮箱地址"john.doe@company.com"
phonestring是手机号码"13800138000"
department_idint是部门ID1
positionstring是职位"Software Engineer"
hire_datestring是入职日期"2024-01-01"
statusint否员工状态（1:在职, 2:离职, 3:休假）1

请求示例 ​

json
{
  "user_id": 1,
  "employee_no": "EMP001",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@company.com",
  "phone": "13800138000",
  "department_id": 1,
  "position": "Software Engineer",
  "hire_date": "2024-01-01",
  "status": 1
}

响应示例 ​

成功响应 (201) ​

json
{
  "code": 201,
  "message": "员工创建成功",
  "data": {
    "id": 1,
    "user_id": 1,
    "employee_no": "EMP001",
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe",
    "email": "john.doe@company.com",
    "phone": "13800138000",
    "department_id": 1,
    "department_name": "技术部",
    "position": "Software Engineer",
    "hire_date": "2024-01-01",
    "status": 1,
    "created_at": "2024-01-01T12:00:00Z"
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

获取员工列表 ​

获取系统中的员工列表，支持分页和筛选。

接口信息 ​

  • URL: /api/v1/admin/employees
  • 方法: GET
  • 认证: 需要管理员权限

查询参数 ​

参数类型必填描述默认值
pageint否页码1
page_sizeint否每页数量10
searchstring否搜索关键词（姓名、工号、邮箱）-
department_idint否部门ID筛选-
statusint否员工状态筛选-

请求示例 ​

bash
GET /api/v1/admin/employees?page=1&page_size=20&department_id=1

响应示例 ​

成功响应 (200) ​

json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "employees": [
      {
        "id": 1,
        "user_id": 1,
        "employee_no": "EMP001",
        "first_name": "John",
        "last_name": "Doe",
        "full_name": "John Doe",
        "email": "john.doe@company.com",
        "phone": "13800138000",
        "department_id": 1,
        "department_name": "技术部",
        "position": "Software Engineer",
        "hire_date": "2024-01-01",
        "status": 1,
        "created_at": "2024-01-01T12:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 1,
      "pages": 1
    }
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

获取员工详情 ​

获取指定员工的详细信息。

接口信息 ​

  • URL: /api/v1/admin/employees/{id}
  • 方法: GET
  • 认证: 需要管理员权限

路径参数 ​

参数类型必填描述示例
idint是员工ID1

响应示例 ​

成功响应 (200) ​

json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "user_id": 1,
    "employee_no": "EMP001",
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe",
    "email": "john.doe@company.com",
    "phone": "13800138000",
    "department_id": 1,
    "department_name": "技术部",
    "position": "Software Engineer",
    "hire_date": "2024-01-01",
    "status": 1,
    "user": {
      "id": 1,
      "username": "johndoe",
      "email": "john@example.com",
      "status": 1
    },
    "contracts": [
      {
        "id": 1,
        "contract_type": "正式合同",
        "start_date": "2024-01-01",
        "end_date": "2025-12-31",
        "salary": 15000
      }
    ],
    "bank_accounts": [
      {
        "id": 1,
        "bank_name": "中国银行",
        "account_number": "****1234",
        "is_default": true
      }
    ],
    "created_at": "2024-01-01T12:00:00Z",
    "updated_at": "2024-01-01T12:00:00Z"
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

更新员工信息 ​

更新指定员工的基本信息。

接口信息 ​

  • URL: /api/v1/admin/employees/{id}
  • 方法: PUT
  • 内容类型: application/json
  • 认证: 需要管理员权限

请求参数 ​

字段类型必填描述示例
first_namestring否名字"John"
last_namestring否姓氏"Smith"
emailstring否邮箱地址"john.smith@company.com"
phonestring否手机号码"13900139000"
department_idint否部门ID2
positionstring否职位"Senior Software Engineer"
statusint否员工状态1

请求示例 ​

json
{
  "last_name": "Smith",
  "position": "Senior Software Engineer",
  "department_id": 2
}

响应示例 ​

成功响应 (200) ​

json
{
  "code": 200,
  "message": "更新成功",
  "data": null,
  "timestamp": "2024-01-01T12:00:00Z"
}

删除员工 ​

删除指定的员工档案（软删除）。

接口信息 ​

  • URL: /api/v1/admin/employees/{id}
  • 方法: DELETE
  • 认证: 需要管理员权限

路径参数 ​

参数类型必填描述示例
idint是员工ID1

响应示例 ​

成功响应 (200) ​

json
{
  "code": 200,
  "message": "删除成功",
  "data": null,
  "timestamp": "2024-01-01T12:00:00Z"
}

获取当前员工的角色和公司信息 ​

获取当前登录员工的角色和公司关联信息。

接口信息 ​

  • URL: /api/v1/employees/my/role-company
  • 方法: GET
  • 认证: 需要登录

响应示例 ​

成功响应 (200) ​

json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "employee": {
      "id": 1,
      "employee_no": "EMP001",
      "full_name": "John Doe",
      "position": "Software Engineer",
      "department_name": "技术部"
    },
    "roles": [
      {
        "id": 1,
        "name": "employee",
        "display_name": "普通员工"
      }
    ],
    "company": {
      "id": 1,
      "name": "源丰科技有限公司",
      "description": "专注于企业信息化服务"
    }
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

获取指定公司的员工列表 ​

获取指定公司的员工列表。

接口信息 ​

  • URL: /api/v1/companies/{id}/employees
  • 方法: GET
  • 认证: 需要登录

路径参数 ​

参数类型必填描述示例
idint是公司ID1

查询参数 ​

参数类型必填描述默认值
pageint否页码1
page_sizeint否每页数量10
department_idint否部门ID筛选-

响应示例 ​

成功响应 (200) ​

json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "employees": [
      {
        "id": 1,
        "employee_no": "EMP001",
        "full_name": "John Doe",
        "position": "Software Engineer",
        "department_name": "技术部",
        "email": "john.doe@company.com",
        "phone": "13800138000"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 10,
      "total": 1,
      "pages": 1
    }
  },
  "timestamp": "2024-01-01T12:00:00Z"
}

数据模型 ​

EmployeeResponse ​

typescript
interface EmployeeResponse {
  id: number;                    // 员工ID
  user_id: number;              // 关联用户ID
  employee_no: string;          // 员工工号
  first_name: string;           // 名字
  last_name: string;            // 姓氏
  full_name: string;            // 全名
  email: string;                // 邮箱地址
  phone: string;                // 手机号码
  department_id: number;        // 部门ID
  department_name?: string;     // 部门名称
  position: string;             // 职位
  hire_date: string;            // 入职日期
  status: number;               // 员工状态
  created_at: string;           // 创建时间
  updated_at: string;           // 更新时间
}

EmployeeDetailResponse ​

typescript
interface EmployeeDetailResponse extends EmployeeResponse {
  user?: UserResponse;                    // 关联用户信息
  contracts?: ContractResponse[];         // 合同列表
  bank_accounts?: BankAccountResponse[];  // 银行账户列表
}

错误代码 ​

错误代码描述解决方案
400请求参数错误检查请求参数格式和必填字段
401未认证检查 JWT token 是否有效
403无权限确认用户具有管理员权限
404员工不存在检查员工ID是否正确
409工号已存在使用其他工号
500服务器内部错误联系系统管理员

集成示例 ​

Python Client ​

python
import requests
from typing import Optional, List, Dict, Any

class EmployeeClient:
    def __init__(self, base_url: str, token: str):
        self.base_url = base_url
        self.token = token
        self.headers = {
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }

    def create_employee(self, employee_data: Dict[str, Any]) -> Dict[str, Any]:
        """创建员工"""
        response = requests.post(
            f'{self.base_url}/api/v1/admin/employees',
            json=employee_data,
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()

    def get_employees(self, page: int = 1, page_size: int = 10,
                     search: Optional[str] = None,
                     department_id: Optional[int] = None) -> Dict[str, Any]:
        """获取员工列表"""
        params = {
            'page': page,
            'page_size': page_size
        }
        if search:
            params['search'] = search
        if department_id:
            params['department_id'] = department_id

        response = requests.get(
            f'{self.base_url}/api/v1/admin/employees',
            params=params,
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()

    def get_employee(self, employee_id: int) -> Dict[str, Any]:
        """获取员工详情"""
        response = requests.get(
            f'{self.base_url}/api/v1/admin/employees/{employee_id}',
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()

    def update_employee(self, employee_id: int, update_data: Dict[str, Any]) -> Dict[str, Any]:
        """更新员工信息"""
        response = requests.put(
            f'{self.base_url}/api/v1/admin/employees/{employee_id}',
            json=update_data,
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()

    def delete_employee(self, employee_id: int) -> Dict[str, Any]:
        """删除员工"""
        response = requests.delete(
            f'{self.base_url}/api/v1/admin/employees/{employee_id}',
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()

# 使用示例
client = EmployeeClient('http://localhost:8080', 'your-jwt-token')

# 创建员工
employee_data = {
    'user_id': 1,
    'employee_no': 'EMP002',
    'first_name': 'Jane',
    'last_name': 'Smith',
    'email': 'jane.smith@company.com',
    'phone': '13900139000',
    'department_id': 1,
    'position': 'Product Manager',
    'hire_date': '2024-01-15',
    'status': 1
}

try:
    result = client.create_employee(employee_data)
    print(f"员工创建成功，ID: {result['data']['id']}")

    # 获取员工列表
    employees = client.get_employees(page=1, page_size=20)
    print(f"共有 {employees['data']['pagination']['total']} 名员工")

except requests.exceptions.RequestException as e:
    print(f"请求失败: {e}")

相关链接 ​

基于 MIT 许可发布

Copyright © 2024-2025 源丰科技