薪资分类管理 API

薪资分类管理API用于管理薪资的不同分类，如基本工资、津贴、扣款等。

基础信息

Base URL: http://localhost:8080/api/v1
认证方式: JWT Token
Content-Type: application/json
权限要求: 管理员权限

通用响应结构

json

{
  "success": true,
  "message": "操作成功",
  "data": {}
}

错误响应结构

json

{
  "success": false,
  "message": "错误信息描述",
  "error": "详细错误信息"
}

创建薪资分类

创建新的薪资分类。

接口地址: POST /admin/salary-categories

请求参数:

参数名	类型	必填	说明
name	string	是	分类名称
type	string	是	分类类型(income/deduction)
description	string	否	分类描述
is_active	boolean	否	是否启用，默认true

请求示例:

json

{
  "name": "基本工资",
  "type": "income",
  "description": "员工基本工资",
  "is_active": true
}

响应示例:

json

{
  "success": true,
  "message": "薪资分类创建成功",
  "data": {
    "id": 1,
    "name": "基本工资",
    "type": "income",
    "description": "员工基本工资",
    "is_active": true,
    "created_at": "2024-01-01T10:00:00Z",
    "updated_at": "2024-01-01T10:00:00Z"
  }
}

获取薪资分类列表

获取所有薪资分类的列表，支持分页和搜索。

接口地址: GET /admin/salary-categories

查询参数:

参数名	类型	必填	默认值	说明
page	int	否	1	页码
page_size	int	否	10	每页数量
name	string	否	-	按名称搜索
type	string	否	-	按类型筛选(income/deduction)
is_active	boolean	否	-	按状态筛选

请求示例:

bash

GET /admin/salary-categories?page=1&page_size=20&type=income

响应示例:

json

{
  "success": true,
  "message": "获取成功",
  "data": {
    "categories": [
      {
        "id": 1,
        "name": "基本工资",
        "type": "income",
        "description": "员工基本工资",
        "is_active": true,
        "created_at": "2024-01-01T10:00:00Z",
        "updated_at": "2024-01-01T10:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 5,
      "pages": 1
    }
  }
}

获取薪资分类详情

获取指定薪资分类的详细信息。

接口地址: GET /admin/salary-categories/{id}

路径参数:

参数名	类型	说明
id	int	薪资分类ID

请求示例:

bash

GET /admin/salary-categories/1

响应示例:

json

{
  "success": true,
  "message": "获取成功",
  "data": {
    "id": 1,
    "name": "基本工资",
    "type": "income",
    "description": "员工基本工资",
    "is_active": true,
    "created_at": "2024-01-01T10:00:00Z",
    "updated_at": "2024-01-01T10:00:00Z"
  }
}

更新薪资分类

更新指定薪资分类的信息。

接口地址: PUT /admin/salary-categories/{id}

路径参数:

参数名	类型	说明
id	int	薪资分类ID

请求参数:

参数名	类型	必填	说明
name	string	否	分类名称
type	string	否	分类类型(income/deduction)
description	string	否	分类描述
is_active	boolean	否	是否启用

请求示例:

json

{
  "name": "基本工资(更新)",
  "description": "员工基本工资，包含基础工资部分",
  "is_active": true
}

响应示例:

json

{
  "success": true,
  "message": "薪资分类更新成功",
  "data": {
    "id": 1,
    "name": "基本工资(更新)",
    "type": "income",
    "description": "员工基本工资，包含基础工资部分",
    "is_active": true,
    "created_at": "2024-01-01T10:00:00Z",
    "updated_at": "2024-01-01T11:00:00Z"
  }
}

删除薪资分类

删除指定的薪资分类。

接口地址: DELETE /admin/salary-categories/{id}

路径参数:

参数名	类型	说明
id	int	薪资分类ID

请求示例:

bash

DELETE /admin/salary-categories/1

响应示例:

json

{
  "success": true,
  "message": "薪资分类删除成功",
  "data": null
}

注意事项:

如果该分类下已有关联的薪资记录，将无法删除
建议在删除前先停用该分类(is_active: false)

数据模型

SalaryCategory

薪资分类数据结构。

json

{
  "id": 1,
  "name": "基本工资",
  "type": "income",
  "description": "员工基本工资",
  "is_active": true,
  "created_at": "2024-01-01T10:00:00Z",
  "updated_at": "2024-01-01T10:00:00Z"
}

字段说明:

字段名	类型	说明
id	int	分类ID
name	string	分类名称
type	string	分类类型(income/deduction)
description	string	分类描述
is_active	boolean	是否启用
created_at	string	创建时间(ISO 8601格式)
updated_at	string	更新时间(ISO 8601格式)

CreateSalaryCategoryRequest

创建薪资分类请求结构。

json

{
  "name": "基本工资",
  "type": "income",
  "description": "员工基本工资",
  "is_active": true
}

UpdateSalaryCategoryRequest

更新薪资分类请求结构。

json

{
  "name": "基本工资(更新)",
  "description": "员工基本工资，包含基础工资部分",
  "is_active": true
}

SalaryCategoryListResponse

薪资分类列表响应结构。

json

{
  "categories": [
    {
      "id": 1,
      "name": "基本工资",
      "type": "income",
      "description": "员工基本工资",
      "is_active": true,
      "created_at": "2024-01-01T10:00:00Z",
      "updated_at": "2024-01-01T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 5,
    "pages": 1
  }
}

错误码说明

错误码	HTTP状态码	说明
400	400	请求参数错误
401	401	未授权，请先登录
403	403	权限不足
404	404	薪资分类不存在
409	409	分类名称已存在
500	500	服务器内部错误

使用示例

1. 创建完整的薪资分类体系

bash

# 创建收入类分类
curl -X POST http://localhost:8080/api/v1/admin/salary-categories \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "基本工资",
    "type": "income",
    "description": "员工基本工资"
  }'

# 创建扣款类分类
curl -X POST http://localhost:8080/api/v1/admin/salary-categories \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "个人所得税",
    "type": "deduction",
    "description": "代扣个人所得税"
  }'

2. 查询所有收入类型分类

bash

curl -X GET "http://localhost:8080/api/v1/admin/salary-categories?type=income" \
  -H "Authorization: Bearer your_token"

3. 更新分类信息

bash

curl -X PUT http://localhost:8080/api/v1/admin/salary-categories/1 \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "员工基本工资，按月发放",
    "is_active": true
  }'

注意事项

分类类型：薪资分类分为收入(income)和扣款(deduction)两种类型
删除限制：已被使用的薪资分类无法直接删除，建议先停用
命名规范：分类名称在系统中必须唯一
权限控制：所有薪资分类管理接口都需要管理员权限
使用建议：建议在设置薪资前先建立完整的薪资分类体系

薪资分类管理 API ​

基础信息 ​

通用响应结构 ​

错误响应结构 ​

创建薪资分类 ​

获取薪资分类列表 ​

获取薪资分类详情 ​

更新薪资分类 ​

删除薪资分类 ​

数据模型 ​

SalaryCategory ​

CreateSalaryCategoryRequest ​

UpdateSalaryCategoryRequest ​

SalaryCategoryListResponse ​

错误码说明 ​

使用示例 ​

1. 创建完整的薪资分类体系 ​

2. 查询所有收入类型分类 ​

3. 更新分类信息 ​

注意事项 ​

相关接口 ​

薪资分类管理 API

基础信息

通用响应结构

错误响应结构

创建薪资分类

获取薪资分类列表

获取薪资分类详情

更新薪资分类

删除薪资分类

数据模型

SalaryCategory

CreateSalaryCategoryRequest

UpdateSalaryCategoryRequest

SalaryCategoryListResponse

错误码说明

使用示例

1. 创建完整的薪资分类体系

2. 查询所有收入类型分类

3. 更新分类信息

注意事项

相关接口