部门管理 API
部门管理模块提供了完整的部门信息管理功能，包括创建、查询、更新和删除部门。
基础信息
- 基础路径:
/api/v1/admin/departments - 认证要求: 需要管理员权限
- 认证方式: Bearer Token (JWT)
数据模型
Department (部门)
typescript
interface Department {
id: number; // 部门ID
name: string; // 部门名称
created_at: string; // 创建时间
updated_at: string; // 更新时间
}API 端点
1. 创建部门
创建一个新的部门。
端点: POST /api/v1/admin/departments
请求头:
Authorization: Bearer <token>
Content-Type: application/json请求体:
json
{
"name": "技术部"
}响应示例:
json
{
"code": 200,
"message": "Department created successfully",
"data": {
"id": 1,
"name": "技术部",
"created_at": "2024-01-15T10:00:00Z",
"updated_at": "2024-01-15T10:00:00Z"
}
}2. 获取部门列表
获取所有部门列表，支持分页和搜索。
端点: GET /api/v1/admin/departments
请求头:
Authorization: Bearer <token>查询参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| page | integer | 否 | 页码，默认为1 |
| page_size | integer | 否 | 每页数量，默认为10 |
| name | string | 否 | 按名称搜索 |
响应示例:
json
{
"code": 200,
"message": "Departments retrieved successfully",
"data": {
"departments": [
{
"id": 1,
"name": "技术部",
"created_at": "2024-01-15T10:00:00Z",
"updated_at": "2024-01-15T10:00:00Z"
},
{
"id": 2,
"name": "人力资源部",
"created_at": "2024-01-16T10:00:00Z",
"updated_at": "2024-01-16T10:00:00Z"
}
],
"total": 2
}
}3. 获取部门详情
根据ID获取单个部门的详细信息。
端点: GET /api/v1/admin/departments/:id
请求头:
Authorization: Bearer <token>路径参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | integer | 是 | 部门ID |
响应示例:
json
{
"code": 200,
"message": "Department retrieved successfully",
"data": {
"id": 1,
"name": "技术部",
"created_at": "2024-01-15T10:00:00Z",
"updated_at": "2024-01-15T10:00:00Z"
}
}4. 更新部门
更新指定部门的信息。
端点: PUT /api/v1/admin/departments/:id
请求头:
Authorization: Bearer <token>
Content-Type: application/json路径参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | integer | 是 | 部门ID |
请求体:
json
{
"name": "技术研发部"
}响应示例:
json
{
"code": 200,
"message": "Department updated successfully",
"data": {
"id": 1,
"name": "技术研发部",
"created_at": "2024-01-15T10:00:00Z",
"updated_at": "2024-01-20T14:30:00Z"
}
}5. 删除部门
删除指定的部门。
端点: DELETE /api/v1/admin/departments/:id
请求头:
Authorization: Bearer <token>路径参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | integer | 是 | 部门ID |
响应示例:
json
{
"code": 200,
"message": "Department deleted successfully",
"data": null
}公开部门列表
获取公开的部门列表（无需认证）。
端点: GET /api/v1/public/departments
响应示例:
json
{
"code": 200,
"message": "Department list retrieved successfully",
"data": [
{
"id": 1,
"name": "技术部"
},
{
"id": 2,
"name": "人力资源部"
}
]
}错误响应
所有端点可能返回以下错误：
400 Bad Request
json
{
"code": 400,
"message": "Invalid department ID",
"data": null
}401 Unauthorized
json
{
"code": 401,
"message": "未授权，请先登录",
"data": null
}403 Forbidden
json
{
"code": 403,
"message": "权限不足",
"data": null
}404 Not Found
json
{
"code": 404,
"message": "Department not found",
"data": null
}500 Internal Server Error
json
{
"code": 500,
"message": "Failed to create/update/delete department",
"data": null
}使用示例
cURL 示例
创建部门
bash
curl -X POST http://localhost:8080/api/v1/admin/departments \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "技术部"
}'获取部门列表
bash
curl -X GET "http://localhost:8080/api/v1/admin/departments?page=1&page_size=10" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"更新部门
bash
curl -X PUT http://localhost:8080/api/v1/admin/departments/1 \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "技术研发部"
}'删除部门
bash
curl -X DELETE http://localhost:8080/api/v1/admin/departments/1 \
-H "Authorization: Bearer YOUR_JWT_TOKEN"注意事项
- 权限要求: 所有部门管理接口都需要管理员权限
- 名称唯一性: 部门名称应该是唯一的
- 删除限制: 删除部门前需要确保没有员工关联到该部门
- 数据验证: 部门名称不能为空
- 公开接口: 公开的部门列表接口无需认证，可用于前端页面展示