swagger: '2.0'
info:
  title: 授权验证管理平台 API
  version: '1.0.0'
  description: 授权验证管理平台的所有 API 接口文档
host: localhost:8080
basePath: /api
schemes:
  - http
  - https

securityDefinitions:
  BearerAuth:
    type: apiKey
    name: Authorization
    in: header
    description: 'Bearer {token}'

tags:
  - name: 用户认证
    description: 用户登录和认证相关接口
  - name: 设备管理
    description: 设备型号和设备管理相关接口
  - name: 授权管理
    description: 授权码管理相关接口

paths:
  /login:
    post:
      tags:
        - 用户认证
      summary: 用户登录
      parameters:
        - in: body
          name: body
          required: true
          schema:
            type: object
            properties:
              username:
                type: string
                description: 用户名
              password:
                type: string
                description: 密码
              captcha:
                type: string
                description: 验证码
              captchaId:
                type: string
                description: 验证码ID
      responses:
        200:
          description: 登录成功
          schema:
            type: object
            properties:
              code:
                type: integer
              message:
                type: string
              token:
                type: string

  /captcha:
    get:
      tags:
        - 用户认证
      summary: 获取验证码
      responses:
        200:
          description: 获取成功
          schema:
            type: object
            properties:
              captchaId:
                type: string
              imageBase64:
                type: string

  /devices/models:
    get:
      tags:
        - 设备管理
      summary: 获取设备型号列表
      security:
        - BearerAuth: []
      parameters:
        - name: page
          in: query
          type: integer
        - name: limit
          in: query
          type: integer
        - name: model_name
          in: query
          type: string
        - name: device_type
          in: query
          type: string
      responses:
        200:
          description: 获取成功
          schema:
            type: object
            properties:
              code:
                type: integer
              count:
                type: integer
              data:
                type: array
                items:
                  $ref: '#/definitions/DeviceModel'
    
    post:
      tags:
        - 设备管理
      summary: 创建设备型号
      security:
        - BearerAuth: []
      parameters:
        - in: body
          name: body
          required: true
          schema:
            $ref: '#/definitions/DeviceModel'
      responses:
        200:
          description: 创建成功

  /devices/registered:
    get:
      tags:
        - 设备管理
      summary: 获取已注册设备列表
      security:
        - BearerAuth: []
      parameters:
        - name: page
          in: query
          type: integer
        - name: limit
          in: query
          type: integer
        - name: uid
          in: query
          type: string
        - name: device_model
          in: query
          type: string
        - name: status
          in: query
          type: string
      responses:
        200:
          description: 获取成功
          schema:
            type: object
            properties:
              code:
                type: integer
              count:
                type: integer
              data:
                type: array
                items:
                  $ref: '#/definitions/Device'

  /devices/{uid}/license:
    post:
      tags:
        - 设备管理
      summary: 绑定授权码
      security:
        - BearerAuth: []
      parameters:
        - name: uid
          in: path
          required: true
          type: string
        - in: body
          name: body
          required: true
          schema:
            type: object
            properties:
              license_code:
                type: string
      responses:
        200:
          description: 绑定成功
    
    delete:
      tags:
        - 设备管理
      summary: 解绑授权码
      security:
        - BearerAuth: []
      parameters:
        - name: uid
          in: path
          required: true
          type: string
      responses:
        200:
          description: 解绑成功

  /licenses:
    get:
      tags:
        - 授权管理
      summary: 获取授权码列表
      security:
        - BearerAuth: []
      parameters:
        - name: page
          in: query
          type: integer
        - name: limit
          in: query
          type: integer
        - name: status
          in: query
          type: string
          description: 授权码状态(unused/used/expired/revoked)
        - name: license_type
          in: query
          type: string
          description: 授权类型(time/count/permanent)
        - name: batch_no
          in: query
          type: string
          description: 批次号
      responses:
        200:
          description: 获取成功
          schema:
            type: object
            properties:
              code:
                type: integer
              count:
                type: integer
              data:
                type: array
                items:
                  $ref: '#/definitions/LicenseCode'
    
    post:
      tags:
        - 授权管理
      summary: 生成授权码
      security:
        - BearerAuth: []
      parameters:
        - in: body
          name: body
          required: true
          schema:
            type: object
            properties:
              license_type:
                type: string
                enum: [time, count, permanent]
                description: 授权类型
              duration:
                type: integer
                description: 有效期(分钟)
              max_uses:
                type: integer
                description: 最大使用次数
              count:
                type: integer
                description: 生成数量
              remark:
                type: string
                description: 注说明
      responses:
        200:
          description: 生成成功

  /licenses/{id}/logs:
    get:
      tags:
        - 授权管理
      summary: 获取授权码操作日志
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          type: string
        - name: page
          in: query
          type: integer
        - name: limit
          in: query
          type: integer
        - name: action
          in: query
          type: string
          description: 操作类型(create/use/verify/revoke)
        - name: status
          in: query
          type: string
          description: 状态(success/failed)
      responses:
        200:
          description: 获取成功
          schema:
            type: object
            properties:
              code:
                type: integer
              count:
                type: integer
              data:
                type: array
                items:
                  $ref: '#/definitions/LicenseLog'

  /licenses/{code}/revoke:
    post:
      tags:
        - 授权管理
      summary: 撤销授权码
      security:
        - BearerAuth: []
      parameters:
        - name: code
          in: path
          required: true
          type: string
      responses:
        200:
          description: 撤销成功

  /licenses/batch/revoke:
    post:
      tags:
        - 授权管理
      summary: 批量撤销授权码
      security:
        - BearerAuth: []
      parameters:
        - in: body
          name: body
          required: true
          schema:
            type: object
            properties:
              codes:
                type: array
                items:
                  type: string
                description: 授权码列表
      responses:
        200:
          description: 批量撤销成功

  /devices/register:
    post:
      tags:
        - 设备管理
      summary: 设备注册
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          required: true
          schema:
            type: object
            required:
              - uid
              - device_model
            properties:
              uid:
                type: string
                description: 设备UID
              device_model:
                type: string
                description: 设备型号
              license_code:
                type: string
                description: 授权码（可选）
      responses:
        200:
          description: 注册成功
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 0
              message:
                type: string
              data:
                type: object
                properties:
                  uid:
                    type: string
                  device_model:
                    type: string
                  status:
                    type: string
        400:
          description: 请求错误
          schema:
            type: object
            properties:
              code:
                type: integer
                example: -1
              error:
                type: string

  /devices/{uid}/start:
    post:
      tags:
        - 设备管理
      summary: 更新设备启动次数
      description: 记录设备启动，更新启动次数和最后活跃时间
      parameters:
        - name: uid
          in: path
          required: true
          type: string
          description: 设备UID
      responses:
        200:
          description: 更新成功
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 0
              message:
                type: string
              data:
                type: object
                properties:
                  start_count:
                    type: integer
                    description: 当前启动次数
                  status:
                    type: string
                    description: 设备状态(active/expired/inactive)
                  last_active_at:
                    type: string
                    format: date-time
                    description: 最后活跃时间
        400:
          description: 请求错误
          schema:
            type: object
            properties:
              code:
                type: integer
                example: -1
              error:
                type: string
                description: 错误信息
        404:
          description: 设备不存在
          schema:
            type: object
            properties:
              code:
                type: integer
                example: -1
              error:
                type: string
                example: "设备未注册"

  /devices/{uid}/validate:
    get:
      tags:
        - 设备管理
      summary: 验证设备状态
      description: 验证设备是否可用，检查授权状态
      parameters:
        - name: uid
          in: path
          required: true
          type: string
          description: 设备UID
      responses:
        200:
          description: 验证成功
          schema:
            type: object
            properties:
              code:
                type: integer
                example: 0
              message:
                type: string
              data:
                type: object
                properties:
                  status:
                    type: string
                    description: 设备状态(active/expired/inactive)
                  license_type:
                    type: string
                    description: 授权类型(time/count/permanent)
                  expire_time:
                    type: string
                    format: date-time
                    description: 过期时间(仅time类型)
                  start_count:
                    type: integer
                    description: 当前启动次数(仅count类型)
                  max_uses:
                    type: integer
                    description: 最大使用次数(仅count类型)
        400:
          description: 验证失败
          schema:
            type: object
            properties:
              code:
                type: integer
                example: -1
              error:
                type: string
                description: 错误信息
        404:
          description: 设备不存在
          schema:
            type: object
            properties:
              code:
                type: integer
                example: -1
              error:
                type: string
                example: "设备未注册"

definitions:
  DeviceModel:
    type: object
    properties:
      id:
        type: integer
      model_name:
        type: string
      device_type:
        type: string
      company:
        type: string
      remark:
        type: string
      device_count:
        type: integer
      status:
        type: string
      created_at:
        type: string
        format: date-time

  Device:
    type: object
    properties:
      uid:
        type: string
      device_model:
        type: string
      device_type:
        type: string
      company:
        type: string
      register_time:
        type: string
        format: date-time
      expire_time:
        type: string
        format: date-time
      license_type:
        type: string
      license_code:
        type: string
      status:
        type: string
      start_count:
        type: integer
      last_active_at:
        type: string
        format: date-time

  LicenseCode:
    type: object
    properties:
      id:
        type: integer
      code:
        type: string
      license_type:
        type: string
        description: 授权类型(time/count/permanent)
      duration:
        type: integer
        description: 有效期(分钟)
      max_uses:
        type: integer
        description: 最大使用次数
      used_count:
        type: integer
        description: 已使用次数
      status:
        type: string
        description: 状态(unused/used/expired/revoked)
      used_by:
        type: string
        description: 使用设备UID
      used_at:
        type: string
        format: date-time
      created_by:
        type: integer
      batch_no:
        type: string
      remark:
        type: string
      created_at:
        type: string
        format: date-time
      updated_at:
        type: string
        format: date-time

  LicenseLog:
    type: object
    properties:
      id:
        type: integer
      license_id:
        type: integer
      device_uid:
        type: string
      action:
        type: string
        description: 操作类型(create/use/verify/revoke)
      ip:
        type: string
      status:
        type: string
        description: 状态(success/failed)
      message:
        type: string
      created_at:
        type: string
        format: date-time