hr-lab-sample/docs/openapi.yaml

openapi: 3.1.0
info:
  title: 组织人事管理平台 API
  version: 1.0.0
servers:
  - url: http://localhost:8080
security:
  - bearerAuth: []
paths:
  /api/v1/auth/login:
    post:
      summary: 本地账号登录
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LoginRequest"
      responses:
        "200":
          description: 登录成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LoginResponse"
  /api/v1/auth/refresh:
    post:
      summary: 刷新令牌
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [refreshToken]
              properties:
                refreshToken:
                  type: string
                deviceName:
                  type: string
      responses:
        "200":
          description: 刷新成功
  /api/v1/auth/logout:
    post:
      summary: 注销会话
      responses:
        "200":
          description: 注销成功
  /api/v1/auth/me:
    get:
      summary: 当前用户
      responses:
        "200":
          description: 当前用户信息
  /api/v1/departments:
    get:
      summary: 部门列表
      responses:
        "200":
          description: 分页部门
    post:
      summary: 新增部门
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DepartmentRequest"
      responses:
        "200":
          description: 创建成功
  /api/v1/departments/{id}:
    put:
      summary: 更新部门
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 更新成功
    delete:
      summary: 停用部门
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 停用成功
  /api/v1/positions:
    get:
      summary: 岗位列表
      responses:
        "200":
          description: 分页岗位
    post:
      summary: 新增岗位
      responses:
        "200":
          description: 创建成功
  /api/v1/positions/{id}:
    put:
      summary: 更新岗位
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 更新成功
    delete:
      summary: 停用岗位
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 停用成功
  /api/v1/employees:
    get:
      summary: 员工列表
      responses:
        "200":
          description: 分页员工
    post:
      summary: 新增员工
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EmployeeRequest"
      responses:
        "200":
          description: 创建成功
  /api/v1/employees/{id}:
    get:
      summary: 员工详情
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 员工详情
    put:
      summary: 更新员工
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 更新成功
    delete:
      summary: 归档员工
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 归档成功
  /api/v1/employees/{id}/transfer:
    post:
      summary: 员工转岗转部门
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 转岗完成
  /api/v1/job-requisitions:
    get:
      summary: 招聘需求列表
      responses:
        "200":
          description: 列表
    post:
      summary: 新增招聘需求
      responses:
        "200":
          description: 创建成功
  /api/v1/candidates:
    get:
      summary: 候选人列表
      responses:
        "200":
          description: 列表
    post:
      summary: 新增候选人
      responses:
        "200":
          description: 创建成功
  /api/v1/candidates/{id}/schedule-interview:
    post:
      summary: 安排面试
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 面试已安排
  /api/v1/candidates/{id}/interviews:
    get:
      summary: 候选人面试列表
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 面试列表
  /api/v1/interviews/{id}/result:
    post:
      summary: 登记面试结果
      parameters:
        - $ref: "#/components/parameters/Id"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InterviewResultRequest"
      responses:
        "200":
          description: 面试结果已登记
  /api/v1/candidates/{id}/issue-offer:
    post:
      summary: 发放 Offer
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 已发放
  /api/v1/candidates/{id}/offer-decision:
    post:
      summary: 候选人 Offer 决策
      parameters:
        - $ref: "#/components/parameters/Id"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OfferDecisionRequest"
      responses:
        "200":
          description: Offer 决策已处理
  /api/v1/candidates/{id}/convert-to-onboarding:
    post:
      summary: 转入入职流程
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 已转入职
  /api/v1/onboarding-cases:
    get:
      summary: 入职单列表
      responses:
        "200":
          description: 列表
    post:
      summary: 新增入职单
      responses:
        "200":
          description: 创建成功
  /api/v1/onboarding-cases/{id}/complete:
    post:
      summary: 完成入职
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 入职完成
  /api/v1/onboarding-cases/{id}/no-show:
    post:
      summary: 标记入职未到岗
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 已标记未到岗
  /api/v1/offboarding-cases:
    get:
      summary: 离职单列表
      responses:
        "200":
          description: 列表
    post:
      summary: 新增离职单
      responses:
        "200":
          description: 创建成功
  /api/v1/offboarding-cases/{id}/close:
    post:
      summary: 关闭离职流程
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 离职关闭
  /api/v1/attendance/records:
    get:
      summary: 考勤记录列表
      responses:
        "200":
          description: 列表
    post:
      summary: 新增考勤记录
      responses:
        "200":
          description: 创建成功
  /api/v1/attendance/import-jobs:
    post:
      summary: 考勤 CSV 导入
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: 导入任务
  /api/v1/leave-requests:
    get:
      summary: 请假列表
      responses:
        "200":
          description: 列表
    post:
      summary: 新增请假
      responses:
        "200":
          description: 创建成功
  /api/v1/leave-requests/{id}/reject:
    post:
      summary: 拒绝请假申请
      parameters:
        - $ref: "#/components/parameters/Id"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DecisionRequest"
      responses:
        "200":
          description: 请假已拒绝
  /api/v1/payroll/periods:
    get:
      summary: 薪酬期间列表
      responses:
        "200":
          description: 列表
    post:
      summary: 新增薪酬期间
      responses:
        "200":
          description: 创建成功
  /api/v1/payroll/periods/{periodKey}/runs:
    post:
      summary: 发起薪酬核算
      parameters:
        - name: periodKey
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: 核算批次
  /api/v1/payroll/items:
    get:
      summary: 薪资项目列表
      responses:
        "200":
          description: 薪资项目
    post:
      summary: 新增薪资项目
      responses:
        "200":
          description: 创建成功
  /api/v1/payroll/items/{id}:
    get:
      summary: 薪资项目详情
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 详情
    put:
      summary: 更新薪资项目
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 更新成功
    delete:
      summary: 删除薪资项目
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 删除成功
  /api/v1/payroll/variables:
    get:
      summary: 薪酬变量列表
      parameters:
        - name: scopeType
          in: query
          required: false
          schema:
            type: string
            enum: [DEPARTMENT, EMPLOYEE]
        - name: departmentId
          in: query
          required: false
          schema:
            type: integer
            format: int64
        - name: employeeId
          in: query
          required: false
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: 薪酬变量
    put:
      summary: 替换部门或员工薪酬变量
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PayrollVariableRequest"
      responses:
        "200":
          description: 保存后的变量
  /api/v1/payroll/variables/effective:
    get:
      summary: 查询员工生效薪酬变量
      parameters:
        - name: employeeId
          in: query
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: 员工、部门及上级部门合并后的变量来源
  /api/v1/payroll/runs/{id}/review:
    post:
      summary: 复核薪酬批次
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 已复核
  /api/v1/payroll/runs/{id}:
    get:
      summary: 薪酬批次详情
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 批次详情与汇总
  /api/v1/payroll/runs/{id}/approve:
    post:
      summary: 审批薪酬批次
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 已审批
  /api/v1/payroll/runs/{id}/lock:
    post:
      summary: 锁定薪酬批次
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 已锁定
  /api/v1/payslips/{id}/publish:
    post:
      summary: 发布工资单
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 已发布
  /api/v1/payslips/publish-batch:
    post:
      summary: 一键发布工资单
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PayslipBatchPublishRequest"
      responses:
        "200":
          description: 发布数量
  /api/v1/payslips/{id}:
    get:
      summary: 工资单详情
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 工资单明细
  /api/v1/appraisal-cycles:
    get:
      summary: 绩效周期列表
      responses:
        "200":
          description: 列表
    post:
      summary: 新增绩效周期
      responses:
        "200":
          description: 创建成功
  /api/v1/appraisal-records:
    get:
      summary: 绩效记录列表
      responses:
        "200":
          description: 列表
    post:
      summary: 新增绩效记录
      responses:
        "200":
          description: 创建成功
  /api/v1/reports/headcount/export:
    post:
      summary: 人员结构导出
      responses:
        "200":
          description: 导出任务
  /api/v1/reports/payroll-summary/export:
    post:
      summary: 薪酬汇总导出
      responses:
        "200":
          description: 导出任务
  /api/v1/export-jobs/{id}:
    get:
      summary: 导出任务详情
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 任务详情
  /api/v1/export-jobs/{id}/download:
    get:
      summary: 下载导出文件
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 导出文件
          content:
            text/csv:
              schema:
                type: string
                format: binary
  /api/v1/import-jobs:
    get:
      summary: 导入任务列表
      responses:
        "200":
          description: 导入任务
  /api/v1/import-jobs/{id}:
    get:
      summary: 导入任务详情
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 任务详情
  /api/v1/audit-logs:
    get:
      summary: 审计日志列表
      responses:
        "200":
          description: 审计日志
  /api/v1/integration/webhooks/test-receiver:
    post:
      summary: Webhook 测试接收
      parameters:
        - name: X-Signature
          in: header
          required: true
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
      responses:
        "200":
          description: 接收成功
  /api/v1/integration/events:
    get:
      summary: 集成事件列表
      responses:
        "200":
          description: 集成事件
  /api/v1/integration/events/{id}/retry:
    post:
      summary: 重试集成事件
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 已提交重试
  /api/v1/security/roles:
    get:
      summary: 角色列表
      responses:
        "200":
          description: 角色
    post:
      summary: 新增角色
      responses:
        "200":
          description: 创建成功
  /api/v1/security/permissions:
    get:
      summary: 权限列表
      responses:
        "200":
          description: 权限
    post:
      summary: 新增权限
      responses:
        "200":
          description: 创建成功
  /api/v1/security/permissions/{id}:
    put:
      summary: 编辑权限
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 更新成功
    delete:
      summary: 删除权限
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 删除成功
  /api/v1/security/roles/{id}:
    delete:
      summary: 删除角色
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 删除成功
  /api/v1/security/roles/{id}/permissions:
    get:
      summary: 查询角色权限
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 角色权限
    put:
      summary: 替换角色权限
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200":
          description: 更新成功
  /api/v1/tasks/dead-letter:
    get:
      summary: 失败任务摘要
      responses:
        "200":
          description: 失败任务统计
  /api/v1/system/about:
    get:
      summary: 系统信息
      responses:
        "200":
          description: 系统版本信息
  /actuator/health:
    get:
      summary: 健康检查
      security: []
      responses:
        "200":
          description: healthy
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    Id:
      name: id
      in: path
      required: true
      schema:
        type: integer
        format: int64
  schemas:
    LoginRequest:
      type: object
      required: [username, password]
      properties:
        username:
          type: string
          example: sys_admin
        password:
          type: string
          format: password
          example: ChangeMe123!
        deviceName:
          type: string
          example: web
    LoginResponse:
      type: object
      properties:
        code:
          type: string
          example: OK
        message:
          type: string
          example: success
        correlationId:
          type: string
        data:
          type: object
          properties:
            accessToken:
              type: string
            refreshToken:
              type: string
            expiresIn:
              type: integer
            user:
              type: object
    DepartmentRequest:
      type: object
      required: [deptCode, deptName]
      properties:
        parentId:
          type: integer
          format: int64
        deptCode:
          type: string
        deptName:
          type: string
        status:
          type: string
        sortNo:
          type: integer
    EmployeeRequest:
      type: object
      required: [employeeNo, departmentId, positionId, displayName]
      properties:
        employeeNo:
          type: string
        departmentId:
          type: integer
          format: int64
        positionId:
          type: integer
          format: int64
        displayName:
          type: string
        employmentStatus:
          type: string
        mobile:
          type: string
        email:
          type: string
    InterviewResultRequest:
      type: object
      required: [result]
      properties:
        result:
          type: string
          enum: [PASSED, FAILED, NO_SHOW]
        feedback:
          type: string
        score:
          type: number
    OfferDecisionRequest:
      type: object
      required: [decision]
      properties:
        decision:
          type: string
          enum: [ACCEPTED, REJECTED]
        reason:
          type: string
    DecisionRequest:
      type: object
      properties:
        reason:
          type: string
    PayrollVariableRequest:
      type: object
      required: [scopeType, variables]
      properties:
        scopeType:
          type: string
          enum: [DEPARTMENT, EMPLOYEE]
        departmentId:
          type: integer
          format: int64
        employeeId:
          type: integer
          format: int64
        variables:
          type: array
          minItems: 1
          items:
            type: object
            required: [variableKey, variableName, variableValue]
            properties:
              variableKey:
                type: string
                example: baseSalary
              variableName:
                type: string
                example: 基本工资
              variableValue:
                type: number
                example: 12000
    PayslipBatchPublishRequest:
      type: object
      properties:
        periodKey:
          type: string
          example: "2026-05"
        runId:
          type: integer
          format: int64