前端对接参考

通用规范

请求头

所有需认证的接口：

Authorization: Bearer <token>
Content-Type: application/json

响应格式

{
  "code": 200,
  "message": "错误信息（仅失败时存在）",
  "data": {}
}

• code 与 HTTP 状态码一致：200/400/401/403/404/500
• 成功时 data 为业务数据，写操作成功时 data 为 null
• 失败时 message 为可展示的错误描述

分页响应格式

所有列表接口统一返回：

{
  "code": 200,
  "data": {
    "data": [],
    "total": 100,
    "page": 1,
    "page_size": 10,
    "total_pages": 10
  }
}

分页请求参数

所有列表接口通用：

认证

注册

POST /auth/register

{
  "username": "admin",
  "password": "123456",
  "role_ids": [1]
}

成功响应 data 为 User 对象。

登录

POST /auth/login

{
  "username": "admin",
  "password": "123456"
}

响应：

{
  "code": 200,
  "data": { "token": "eyJhbGciOi..." }
}

Token 过期时间 24 小时。前端应在 401 时跳转登录页。

获取当前用户

GET /auth/me

响应：

{
  "code": 200,
  "data": { "id": 1, "username": "admin" }
}

注销

POST /auth/logout

用户管理

所有用户接口需 admin 角色。

用户列表

GET /users

查询参数：

响应示例：

{
  "code": 200,
  "data": {
    "data": [
      {
        "id": 1,
        "username": "admin",
        "status": "active",
        "roles": [{"id": 1, "name": "admin", "description": "系统管理员"}],
        "created_at": "2026-04-29T12:00:00Z",
        "updated_at": "2026-04-29T12:00:00Z"
      }
    ],
    "total": 10,
    "page": 1,
    "page_size": 10,
    "total_pages": 1
  }
}

User 对象字段：

注意：password 字段不会在 JSON 中返回。

获取单个用户

GET /users/:id

修改用户状态

PUT /users/:id/status

{ "status": "disabled" }

status 取值：active / disabled

分配角色

PUT /users/:id/roles

{ "role_ids": [1, 2] }

role_ids 为完整的角色 ID 列表，会替换现有角色（不是增量追加）。

角色 ID 参考：

可通过 GET /roles 获取完整角色列表。

修改/重置密码

PUT /users/:id/password

admin 操作（重置他人密码）：

{ "new_password": "654321" }

仅需 new_password，最少 6 位。

非 admin 操作（修改自己密码）：

{
  "old_password": "123456",
  "new_password": "654321"
}

需同时提供 old_password 和 new_password。

删除用户

DELETE /users/:id

前端应在删除前判断是否为当前登录用户，给出禁用/提示。

部门管理

部门列表

GET /depts

查询参数：

部门树

GET /depts/tree

返回完整树结构，一次性加载。适合侧边栏/下拉框等场景。

{
  "code": 200,
  "data": [
    {
      "id": 1,
      "name": "研发部",
      "description": "...",
      "parent_id": null,
      "children": [...]
    }
  ]
}

创建部门

POST /depts

需要 admin 或 manager（部门负责人）角色。

{
  "name": "研发部",
  "description": "负责产品研发",
  "leader_id": 3,
  "parent_id": null
}

更新部门

PUT /depts/:id

只传需要更新的字段。更新 parent_id 时校验循环引用。

删除部门

DELETE /depts/:id

仅 admin。有子部门或有员工时不可删除（code 400）。

员工管理

员工列表

GET /employees

查询参数：

admin 可看全部，manager 看本部门+子部门，staff 无权限（403）。

获取自己的员工档案

GET /employees/me

所有角色可访问。未关联员工档案时返回 404。

创建员工

POST /employees

需要 admin 或 manager（部门负责人）角色。

{
  "name": "张伟",
  "email": "zhangwei@pms.com",
  "phone": "13800000001",
  "id_number": "110101199001011234",
  "dept_id": 1,
  "user_id": 2,
  "status": "active"
}

Employee 对象包含 department 关联字段（Preload），可直接取部门名称。

更新员工

PUT /employees/:id

只传需要更新的字段。更新 dept_id 和 email 时有存在性校验。

删除员工

DELETE /employees/:id

仅 admin。

薪资管理

所有薪资接口需 admin 角色。

薪资结构列表

GET /salaries/structures

查询参数：

创建薪资结构

POST /salaries/structures

{
  "employee_id": 1,
  "base_salary": 10000,
  "position_allowance": 2000,
  "performance_factor": 1.0
}

每个员工只能有一个薪资结构。

查询员工薪资结构

GET /salaries/structures/employees/:emp_id

更新/删除薪资结构

PUT /salaries/structures/:id
DELETE /salaries/structures/:id

薪资记录列表

GET /salaries/records

新增筛选参数（在通用分页基础上）：

生成薪资记录

POST /salaries/records

{
  "employee_id": 1,
  "year": 2026,
  "month": 4,
  "performance_factor": 1.0
}

批量生成

POST /salaries/records/batch

{
  "year": 2026,
  "month": 4,
  "employee_ids": [1, 2, 3]
}

employee_ids 和 dept_id 可选，优先级：employee_ids > dept_id > 全部。

修改薪资记录

PUT /salaries/records/:id

仅 draft 或 rejected 状态可修改。修改 performance_factor 时自动重算 actual_salary。

{ "performance_factor": 1.3 }

查询单条薪资记录

GET /salaries/records/:id

薪资记录状态流转

PUT /salaries/records/:id/submit    draft/rejected → pending
PUT /salaries/records/:id/approve   pending → approved
PUT /salaries/records/:id/reject    pending → rejected
PUT /salaries/records/:id/pay       approved → paid

状态流转图：

draft → pending → approved → paid
  ↑        ↓
  └── rejected

考勤管理

打卡

POST /attendance/clock-in     上班打卡
PUT  /attendance/clock-out    下班打卡

{ "employee_id": 1 }

staff 只能为自己打卡（后端校验 JWT employee_id），admin/manager 可为任意员工打卡。

打卡记录列表

GET /attendance/records

查询单条打卡记录

GET /attendance/records/:id

生成考勤统计

POST /attendance/summaries/generate

{ "employee_id": 1, "year": 2026, "month": 4 }

需要 admin/manager 角色。重复生成会覆盖。

考勤统计列表

GET /attendance/summaries

请假管理

提交请假

POST /leaves

{
  "employee_id": 1,
  "type": "annual",
  "start_date": "2026-05-01",
  "end_date": "2026-05-03",
  "reason": "年假"
}

staff 只能为本人申请。

请假列表

GET /leaves

查询单条请假申请

GET /leaves/:id

审批

PUT /leaves/:id/approve
PUT /leaves/:id/reject

需 admin/manager（部门负责人）角色。manager 只能审批本部门范围。

角色列表

GET /roles

所有认证用户可访问。返回固定三种角色：

{
  "code": 200,
  "data": [
    {"id": 1, "name": "admin", "description": "系统管理员"},
    {"id": 2, "name": "manager", "description": "部门经理"},
    {"id": 3, "name": "staff", "description": "普通员工"}
  ]
}

审计日志

需 admin 角色。

GET /audit-logs

entity_type 取值：user, department, employee, salary_structure, salary_record, attendance_record, attendance_summary, leave_request

权限概览

• "本部门范围" 指 manager 作为 leader_id 所属部门及其子部门
• "仅自己" 指后端强制使用 JWT 中的 employee_id，忽略请求中的 employee_id

前端权限控制建议

• 登录后从 JWT 解析 role，存储到全局状态
• 根据角色控制菜单/按钮显隐
• admin：全部功能可见
• manager：部门/员工管理（本部门范围）、考勤统计、请假审批可见；用户管理、薪资管理、审计日志不可见
• staff：仅 /employees/me、打卡（自己）、请假（自己）可见
• 所有角色：部门/部门树、角色列表只读可见

JWT Token Payload

{
  "user_id": 1,
  "username": "admin",
  "role": "admin",
  "employee_id": 3,
  "jti": "xxx",
  "exp": 1746000000
}

前端可用 jwt-decode 库解析 token 获取 role 和 employee_id。