datahub/backend/docs/openapi.yaml

openapi: 3.0.0
info:
  title: 'Datahub API'
  description: 'Datahub API documentation'
  version: 1.0.0
servers:
  -
    url: /api/v1
    description: 'API v1'
paths:
  /api/v1/dashboard/overview:
    get:
      tags:
        - Dashboard
      summary: 获取概览统计
      description: 返回今日/本周/本月的成功和失败同步数，以及按数据类型的本月分组统计。
      operationId: 867e0544fefdad33775c25bb6188d484
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { $ref: '#/components/schemas/DashboardOverview' }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  /api/v1/dashboard/trend:
    get:
      tags:
        - Dashboard
      summary: 获取趋势数据
      description: 返回指定时间范围内按日/周/月聚合的成功和失败同步趋势。
      operationId: d3850b6a1ce1436c8ddf4b92fc0b7e44
      parameters:
        -
          name: from
          in: query
          description: 起始日期（默认30天前）
          required: false
          schema:
            type: string
            format: date
            example: '2026-02-15'
        -
          name: to
          in: query
          description: 结束日期（默认今天）
          required: false
          schema:
            type: string
            format: date
            example: '2026-03-17'
        -
          name: group_by
          in: query
          description: 聚合粒度
          required: false
          schema:
            type: string
            default: day
            enum:
              - day
              - week
              - month
        -
          name: data_type
          in: query
          description: 数据类型筛选
          required: false
          schema:
            type: string
            enum:
              - order
              - product
              - refund
              - inventory
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { type: array, items: { $ref: '#/components/schemas/DashboardTrendItem' } }
                type: object
        '400':
          description: 参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  /api/v1/dashboard/breakdown:
    get:
      tags:
        - Dashboard
      summary: 获取分组统计
      description: 按公司/平台/店铺维度统计成功和失败同步数。
      operationId: 91349b224bcf13f440df27de0a198f54
      parameters:
        -
          name: dimension
          in: query
          description: 分组维度
          required: true
          schema:
            type: string
            enum:
              - company
              - platform
              - store
        -
          name: from
          in: query
          description: 起始日期（默认今天）
          required: false
          schema:
            type: string
            format: date
            example: '2026-03-17'
        -
          name: to
          in: query
          description: 结束日期（默认今天）
          required: false
          schema:
            type: string
            format: date
            example: '2026-03-17'
        -
          name: data_type
          in: query
          description: 数据类型筛选
          required: false
          schema:
            type: string
            enum:
              - order
              - product
              - refund
              - inventory
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { type: array, items: { $ref: '#/components/schemas/DashboardBreakdownItem' } }
                type: object
        '400':
          description: 参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  /api/v1/failed-messages:
    get:
      tags:
        - 'Failed Messages'
      summary: 失败消息列表
      description: '获取 Consumer 处理失败的消息列表，支持分页、按数据类型/平台/时间筛选。仅 admin 可访问。'
      operationId: 6dac9bdff8b35f75565ed5c6b8638937
      parameters:
        -
          name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        -
          name: per_page
          in: query
          required: false
          schema:
            type: integer
            default: 15
            maximum: 100
        -
          name: data_type
          in: query
          description: 数据类型精确筛选（order/product/refund）
          required: false
          schema:
            type: string
            enum:
              - order
              - product
              - refund
        -
          name: platform_id
          in: query
          description: '平台 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: error_type
          in: query
          description: 异常类名模糊搜索
          required: false
          schema:
            type: string
        -
          name: failed_at_from
          in: query
          description: 失败时间起始（含）
          required: false
          schema:
            type: string
            format: date
            example: '2026-01-01'
        -
          name: failed_at_to
          in: query
          description: 失败时间截止（含）
          required: false
          schema:
            type: string
            format: date
            example: '2026-12-31'
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { properties: { items: { type: array, items: { $ref: '#/components/schemas/FailedMessageList' } }, total: { type: integer, example: 100 }, page: { type: integer, example: 1 }, per_page: { type: integer, example: 15 } }, type: object }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  '/api/v1/failed-messages/{id}':
    get:
      tags:
        - 'Failed Messages'
      summary: 失败消息详情
      description: '获取失败消息详情，含完整错误堆栈和原始消息体。仅 admin 可访问。'
      operationId: 4f6b7410222ebc0fa65afdc1d168c15a
      parameters:
        -
          name: id
          in: path
          description: '失败消息 ID'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { $ref: '#/components/schemas/FailedMessageDetail' }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 数据不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  /api/v1/mq/status:
    get:
      tags:
        - 'MQ Status'
      summary: 获取消息队列状态
      description: '查询 RabbitMQ 各队列的消息数、消费者数和运行状态。支持按队列类型筛选。仅 admin 角色可访问。'
      operationId: 3f5b041034fafc9738ecf65f166b6193
      parameters:
        -
          name: queue
          in: query
          description: 队列类型筛选（orders/products/refunds/inventory）
          required: false
          schema:
            type: string
            enum:
              - orders
              - products
              - refunds
              - inventory
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { $ref: '#/components/schemas/MqQueueStatus' }
                type: object
        '400':
          description: 无效的队列类型参数
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 'RabbitMQ 连接异常'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  /orders:
    get:
      tags:
        - Orders
      summary: 订单列表
      description: '获取订单列表，支持分页、多维度筛选和时间范围筛选。返回业务字段，不含 raw/hash。'
      operationId: 7e493d0464138129e7e1f0e7ebee178b
      parameters:
        -
          name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        -
          name: per_page
          in: query
          required: false
          schema:
            type: integer
            default: 15
            maximum: 100
        -
          name: company_id
          in: query
          description: '公司 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: platform_id
          in: query
          description: '平台 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: store_id
          in: query
          description: '店铺 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: order_status_id
          in: query
          description: '订单状态 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: platform_order_id
          in: query
          description: '平台订单 ID 精确搜索'
          required: false
          schema:
            type: string
        -
          name: created_date_from
          in: query
          description: 创建时间起始（含）
          required: false
          schema:
            type: string
            format: date
            example: '2026-01-01'
        -
          name: created_date_to
          in: query
          description: 创建时间截止（含）
          required: false
          schema:
            type: string
            format: date
            example: '2026-12-31'
        -
          name: paid_date_from
          in: query
          description: 付款时间起始（含）
          required: false
          schema:
            type: string
            format: date
            example: '2026-01-01'
        -
          name: paid_date_to
          in: query
          description: 付款时间截止（含）
          required: false
          schema:
            type: string
            format: date
            example: '2026-12-31'
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { properties: { items: { type: array, items: { $ref: '#/components/schemas/Order' } }, total: { type: integer, example: 100 }, page: { type: integer, example: 1 }, per_page: { type: integer, example: 15 } }, type: object }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  '/orders/{id}':
    get:
      tags:
        - Orders
      summary: 订单详情
      description: '获取订单详情，返回所有业务字段、ext 和关联的 order_items，不含 raw/hash。'
      operationId: aff126ce9a5cef811fea88ceba395fdc
      parameters:
        -
          name: id
          in: path
          description: '订单 ID'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { type: object, allOf: [{ $ref: '#/components/schemas/Order' }, { properties: { order_items: { description: 关联订单子项, type: array, items: { type: object } } }, type: object }] }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 数据不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  /order-items:
    get:
      tags:
        - 'Order Items'
      summary: 订单项列表
      description: '获取订单项列表，支持分页和多维度筛选。OrderItem 无 raw/hash 字段，仅提供 Normal 接口。'
      operationId: 894b5ea5fad8ecc3159e628333252260
      parameters:
        -
          name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        -
          name: per_page
          in: query
          required: false
          schema:
            type: integer
            default: 15
            maximum: 100
        -
          name: company_id
          in: query
          description: '公司 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: platform_id
          in: query
          description: '平台 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: store_id
          in: query
          description: '店铺 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: order_id
          in: query
          description: '内部订单 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: platform_order_id
          in: query
          description: '平台订单 ID 精确筛选'
          required: false
          schema:
            type: string
        -
          name: platform_product_id
          in: query
          description: '平台商品 ID 精确筛选'
          required: false
          schema:
            type: string
        -
          name: product_sku
          in: query
          description: 'SKU 编码精确筛选'
          required: false
          schema:
            type: string
        -
          name: created_date_from
          in: query
          description: 创建时间起始（含）
          required: false
          schema:
            type: string
            format: date
            example: '2026-01-01'
        -
          name: created_date_to
          in: query
          description: 创建时间截止（含）
          required: false
          schema:
            type: string
            format: date
            example: '2026-12-31'
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { properties: { items: { type: array, items: { $ref: '#/components/schemas/OrderItem' } }, total: { type: integer, example: 100 }, page: { type: integer, example: 1 }, per_page: { type: integer, example: 15 } }, type: object }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  '/order-items/{id}':
    get:
      tags:
        - 'Order Items'
      summary: 订单项详情
      description: 获取订单项详情，返回完整字段和关联的父订单摘要信息。
      operationId: a808f2d76861f46925baef81c52da14f
      parameters:
        -
          name: id
          in: path
          description: '订单项 ID'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { type: object, allOf: [{ $ref: '#/components/schemas/OrderItem' }, { properties: { parent_order: { description: 父订单摘要信息, type: object, nullable: true } }, type: object }] }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 数据不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  /products:
    get:
      tags:
        - Products
      summary: 产品列表
      description: '获取产品列表，支持分页、多维度筛选。返回业务字段，不含 raw/hash。'
      operationId: 934e471439896276d2897b4b5132c077
      parameters:
        -
          name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        -
          name: per_page
          in: query
          required: false
          schema:
            type: integer
            default: 15
            maximum: 100
        -
          name: company_id
          in: query
          description: '公司 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: platform_id
          in: query
          description: '平台 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: store_id
          in: query
          description: '店铺 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: status_id
          in: query
          description: '产品状态 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: platform_item_id
          in: query
          description: '平台商品 ID 精确搜索'
          required: false
          schema:
            type: string
        -
          name: name
          in: query
          description: 商品名称模糊搜索
          required: false
          schema:
            type: string
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { properties: { items: { type: array, items: { $ref: '#/components/schemas/Product' } }, total: { type: integer, example: 100 }, page: { type: integer, example: 1 }, per_page: { type: integer, example: 15 } }, type: object }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  '/products/{id}':
    get:
      tags:
        - Products
      summary: 产品详情
      description: '获取产品详情，返回所有业务字段和 ext，不含 raw/hash。'
      operationId: 7d7422e8293b23608368a4a9000f8096
      parameters:
        -
          name: id
          in: path
          description: '产品 ID'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { $ref: '#/components/schemas/Product' }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 数据不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  /raw/orders:
    get:
      tags:
        - 'Orders (Raw)'
      summary: 订单列表（Raw）
      description: '获取订单原始数据列表。返回关键标识 + hash，不含 raw 字段本身（太大）。筛选参数与 Normal 接口一致。'
      operationId: 562f4be5afd7463d1c9c9c653bdd0c35
      parameters:
        -
          name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        -
          name: per_page
          in: query
          required: false
          schema:
            type: integer
            default: 15
            maximum: 100
        -
          name: company_id
          in: query
          description: '公司 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: platform_id
          in: query
          description: '平台 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: store_id
          in: query
          description: '店铺 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: order_status_id
          in: query
          description: '订单状态 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: platform_order_id
          in: query
          description: '平台订单 ID 精确搜索'
          required: false
          schema:
            type: string
        -
          name: created_date_from
          in: query
          description: 创建时间起始（含）
          required: false
          schema:
            type: string
            format: date
        -
          name: created_date_to
          in: query
          description: 创建时间截止（含）
          required: false
          schema:
            type: string
            format: date
        -
          name: paid_date_from
          in: query
          description: 付款时间起始（含）
          required: false
          schema:
            type: string
            format: date
        -
          name: paid_date_to
          in: query
          description: 付款时间截止（含）
          required: false
          schema:
            type: string
            format: date
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { properties: { items: { type: array, items: { properties: { id: { type: integer }, platform_order_id: { type: string }, store_id: { type: integer }, company_id: { type: integer }, platform_id: { type: integer }, order_status_id: { type: integer }, hash: { type: string }, created_date: { type: string, format: date-time }, updated_at: { type: string, format: date-time } }, type: object } }, total: { type: integer }, page: { type: integer }, per_page: { type: integer } }, type: object }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  '/raw/orders/{id}':
    get:
      tags:
        - 'Orders (Raw)'
      summary: 订单详情（Raw）
      description: '获取订单原始数据详情。返回关键标识 + 完整 raw + hash + ext。'
      operationId: 6c9b613233d2ef2a708d51523149d84b
      parameters:
        -
          name: id
          in: path
          description: '订单 ID'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { properties: { id: { type: integer }, platform_order_id: { type: string }, store_id: { type: integer }, company_id: { type: integer }, platform_id: { type: integer }, order_status_id: { type: integer }, raw: { description: 平台原始数据, type: object }, hash: { type: string }, ext: { type: object, nullable: true }, created_date: { type: string, format: date-time } }, type: object }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 数据不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  /raw/products:
    get:
      tags:
        - 'Products (Raw)'
      summary: 产品列表（Raw）
      description: '获取产品原始数据列表。返回关键标识 + hash，不含 raw 字段本身（太大）。筛选参数与 Normal 接口一致。'
      operationId: 770fd6e9caf314efbc05aa0277c7e811
      parameters:
        -
          name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        -
          name: per_page
          in: query
          required: false
          schema:
            type: integer
            default: 15
            maximum: 100
        -
          name: company_id
          in: query
          description: '公司 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: platform_id
          in: query
          description: '平台 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: store_id
          in: query
          description: '店铺 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: status_id
          in: query
          description: '产品状态 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: platform_item_id
          in: query
          description: '平台商品 ID 精确搜索'
          required: false
          schema:
            type: string
        -
          name: name
          in: query
          description: 商品名称模糊搜索
          required: false
          schema:
            type: string
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { properties: { items: { type: array, items: { properties: { id: { type: integer }, platform_item_id: { type: string }, platform_model_id: { type: string, nullable: true }, name: { type: string, nullable: true }, store_id: { type: integer }, company_id: { type: integer }, platform_id: { type: integer }, hash: { type: string }, updated_date: { type: string, format: date-time, nullable: true }, updated_at: { type: string, format: date-time } }, type: object } }, total: { type: integer }, page: { type: integer }, per_page: { type: integer } }, type: object }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  '/raw/products/{id}':
    get:
      tags:
        - 'Products (Raw)'
      summary: 产品详情（Raw）
      description: '获取产品原始数据详情。返回关键标识 + 完整 raw + hash + ext。'
      operationId: e0ba90775ff4ceb4fe459b8272a63624
      parameters:
        -
          name: id
          in: path
          description: '产品 ID'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { properties: { id: { type: integer }, platform_item_id: { type: string }, platform_model_id: { type: string, nullable: true }, name: { type: string, nullable: true }, store_id: { type: integer }, company_id: { type: integer }, platform_id: { type: integer }, raw: { description: 平台原始数据, type: object }, hash: { type: string }, ext: { type: object, nullable: true }, created_date: { type: string, format: date-time, nullable: true }, updated_date: { type: string, format: date-time, nullable: true } }, type: object }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 数据不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  /raw/refunds:
    get:
      tags:
        - 'Refunds (Raw)'
      summary: 退款列表（Raw）
      description: '获取退款原始数据列表。返回关键标识 + hash，不含 raw 字段本身（太大）。筛选参数与 Normal 接口一致。'
      operationId: 04e3c7e28df6496b975c24618933c6dd
      parameters:
        -
          name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        -
          name: per_page
          in: query
          required: false
          schema:
            type: integer
            default: 15
            maximum: 100
        -
          name: company_id
          in: query
          description: '公司 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: platform_id
          in: query
          description: '平台 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: store_id
          in: query
          description: '店铺 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: refund_status_id
          in: query
          description: '退款状态 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: refund_type_id
          in: query
          description: '退款类型 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: platform_refund_id
          in: query
          description: '平台退款 ID 精确搜索'
          required: false
          schema:
            type: string
        -
          name: platform_order_id
          in: query
          description: '关联平台订单 ID 筛选'
          required: false
          schema:
            type: string
        -
          name: created_date_from
          in: query
          description: 创建时间起始（含）
          required: false
          schema:
            type: string
            format: date
        -
          name: created_date_to
          in: query
          description: 创建时间截止（含）
          required: false
          schema:
            type: string
            format: date
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { properties: { items: { type: array, items: { properties: { id: { type: integer }, platform_refund_id: { type: string }, platform_order_id: { type: string }, store_id: { type: integer }, company_id: { type: integer }, platform_id: { type: integer }, refund_status_id: { type: integer }, hash: { type: string }, created_date: { type: string, format: date-time }, updated_at: { type: string, format: date-time } }, type: object } }, total: { type: integer }, page: { type: integer }, per_page: { type: integer } }, type: object }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  '/raw/refunds/{id}':
    get:
      tags:
        - 'Refunds (Raw)'
      summary: 退款详情（Raw）
      description: '获取退款原始数据详情。返回关键标识 + 完整 raw + hash + ext。'
      operationId: 884b7753642515815a193abb0cae88c9
      parameters:
        -
          name: id
          in: path
          description: '退款 ID'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { properties: { id: { type: integer }, platform_refund_id: { type: string }, platform_order_id: { type: string }, store_id: { type: integer }, company_id: { type: integer }, platform_id: { type: integer }, refund_status_id: { type: integer }, raw: { description: 平台原始数据, type: object }, hash: { type: string }, ext: { type: object, nullable: true }, created_date: { type: string, format: date-time } }, type: object }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 数据不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  /raw/refund-items:
    get:
      tags:
        - 'Refund Items (Raw)'
      summary: 退款项列表（Raw）
      description: '获取退款项原始数据列表。返回关键标识，不含 raw 字段本身（太大）。筛选参数与 Normal 接口一致。'
      operationId: b1af2757230f49948c934063da9d627a
      parameters:
        -
          name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        -
          name: per_page
          in: query
          required: false
          schema:
            type: integer
            default: 15
            maximum: 100
        -
          name: company_id
          in: query
          description: '公司 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: platform_id
          in: query
          description: '平台 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: store_id
          in: query
          description: '店铺 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: refund_id
          in: query
          description: '父退款 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: refund_status_id
          in: query
          description: '退款状态 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: refund_type_id
          in: query
          description: '退款类型 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: platform_refund_id
          in: query
          description: '平台退款子项 ID 精确搜索'
          required: false
          schema:
            type: string
        -
          name: platform_order_id
          in: query
          description: '关联平台订单 ID 筛选'
          required: false
          schema:
            type: string
        -
          name: platform_product_id
          in: query
          description: '平台商品 ID 精确筛选'
          required: false
          schema:
            type: string
        -
          name: created_date_from
          in: query
          description: 创建时间起始（含）
          required: false
          schema:
            type: string
            format: date
        -
          name: created_date_to
          in: query
          description: 创建时间截止（含）
          required: false
          schema:
            type: string
            format: date
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { properties: { items: { type: array, items: { properties: { id: { type: integer }, platform_refund_id: { type: string }, platform_parent_refund_id: { type: string }, platform_order_id: { type: string }, store_id: { type: integer }, company_id: { type: integer }, platform_id: { type: integer }, refund_status_id: { type: integer }, created_date: { type: string, format: date-time }, updated_at: { type: string, format: date-time } }, type: object } }, total: { type: integer }, page: { type: integer }, per_page: { type: integer } }, type: object }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  '/raw/refund-items/{id}':
    get:
      tags:
        - 'Refund Items (Raw)'
      summary: 退款项详情（Raw）
      description: '获取退款项原始数据详情。返回关键标识 + 完整 raw + ext。'
      operationId: 6a82a9938eef667456c5a8948b984eb3
      parameters:
        -
          name: id
          in: path
          description: '退款项 ID'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { properties: { id: { type: integer }, platform_refund_id: { type: string }, platform_parent_refund_id: { type: string }, platform_order_id: { type: string }, store_id: { type: integer }, company_id: { type: integer }, platform_id: { type: integer }, refund_status_id: { type: integer }, raw: { description: 平台原始子项数据, type: object }, ext: { type: object, nullable: true }, created_date: { type: string, format: date-time } }, type: object }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 数据不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  /refunds:
    get:
      tags:
        - Refunds
      summary: 退款列表
      description: '获取退款列表，支持分页、按退款状态/类型/时间范围筛选。返回业务字段，不含 raw/hash。'
      operationId: bd68a8b63be96fc4bc13a7f914db8e6f
      parameters:
        -
          name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        -
          name: per_page
          in: query
          required: false
          schema:
            type: integer
            default: 15
            maximum: 100
        -
          name: company_id
          in: query
          description: '公司 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: platform_id
          in: query
          description: '平台 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: store_id
          in: query
          description: '店铺 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: refund_status_id
          in: query
          description: '退款状态 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: refund_type_id
          in: query
          description: '退款类型 ID 精确筛选（1=未发货前退款 2=退货退款 3=退货后部分退款 4=无须退货退款 5=闪电退款）'
          required: false
          schema:
            type: integer
        -
          name: platform_refund_id
          in: query
          description: '平台退款 ID 精确搜索'
          required: false
          schema:
            type: string
        -
          name: platform_order_id
          in: query
          description: '关联平台订单 ID 筛选'
          required: false
          schema:
            type: string
        -
          name: created_date_from
          in: query
          description: 创建时间起始（含）
          required: false
          schema:
            type: string
            format: date
            example: '2026-01-01'
        -
          name: created_date_to
          in: query
          description: 创建时间截止（含）
          required: false
          schema:
            type: string
            format: date
            example: '2026-12-31'
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { properties: { items: { type: array, items: { $ref: '#/components/schemas/Refund' } }, total: { type: integer, example: 100 }, page: { type: integer, example: 1 }, per_page: { type: integer, example: 15 } }, type: object }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  '/refunds/{id}':
    get:
      tags:
        - Refunds
      summary: 退款详情
      description: '获取退款详情，返回所有业务字段和 ext，不含 raw/hash。'
      operationId: 6009f4876a61b01d12a288fcfe78444c
      parameters:
        -
          name: id
          in: path
          description: '退款 ID'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { $ref: '#/components/schemas/Refund' }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 数据不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  /refund-items:
    get:
      tags:
        - 'Refund Items'
      summary: 退款项列表
      description: '获取退款项列表，支持分页、按退款单/退款状态/类型/时间范围筛选。返回业务字段，不含 raw。'
      operationId: ad798f6022c7e5b289827884ef582bc2
      parameters:
        -
          name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        -
          name: per_page
          in: query
          required: false
          schema:
            type: integer
            default: 15
            maximum: 100
        -
          name: company_id
          in: query
          description: '公司 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: platform_id
          in: query
          description: '平台 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: store_id
          in: query
          description: '店铺 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: refund_id
          in: query
          description: '父退款 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: refund_status_id
          in: query
          description: '退款状态 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: refund_type_id
          in: query
          description: '退款类型 ID 精确筛选（1=仅退款 2=退货退款 3=补偿退款）'
          required: false
          schema:
            type: integer
        -
          name: platform_refund_id
          in: query
          description: '平台退款子项 ID 精确搜索'
          required: false
          schema:
            type: string
        -
          name: platform_order_id
          in: query
          description: '关联平台订单 ID 筛选'
          required: false
          schema:
            type: string
        -
          name: platform_product_id
          in: query
          description: '平台商品 ID 精确筛选'
          required: false
          schema:
            type: string
        -
          name: created_date_from
          in: query
          description: 创建时间起始（含）
          required: false
          schema:
            type: string
            format: date
            example: '2026-01-01'
        -
          name: created_date_to
          in: query
          description: 创建时间截止（含）
          required: false
          schema:
            type: string
            format: date
            example: '2026-12-31'
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { properties: { items: { type: array, items: { $ref: '#/components/schemas/RefundItem' } }, total: { type: integer, example: 100 }, page: { type: integer, example: 1 }, per_page: { type: integer, example: 15 } }, type: object }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  '/refund-items/{id}':
    get:
      tags:
        - 'Refund Items'
      summary: 退款项详情
      description: '获取退款项详情，返回所有业务字段和 ext，不含 raw。'
      operationId: de6cf91ff904e528cba6f1b43f829a2c
      parameters:
        -
          name: id
          in: path
          description: '退款项 ID'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { $ref: '#/components/schemas/RefundItem' }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 数据不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  /api/v1/logs/requests:
    get:
      tags:
        - 'Request Logs'
      summary: 请求日志列表
      description: '获取 API 请求日志列表，支持分页、按用户/方法/路径/状态码/时间筛选。仅 admin 可访问。'
      operationId: db0b73fd478b1f9dfacb819a397254ff
      parameters:
        -
          name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        -
          name: per_page
          in: query
          required: false
          schema:
            type: integer
            default: 15
            maximum: 100
        -
          name: user_id
          in: query
          description: '用户 ID 精确筛选'
          required: false
          schema:
            type: integer
        -
          name: method
          in: query
          description: 'HTTP 方法精确筛选'
          required: false
          schema:
            type: string
            enum:
              - GET
              - POST
              - PUT
              - PATCH
              - DELETE
        -
          name: path
          in: query
          description: 请求路径模糊搜索
          required: false
          schema:
            type: string
        -
          name: status_code
          in: query
          description: 'HTTP 状态码精确筛选'
          required: false
          schema:
            type: integer
        -
          name: created_at_from
          in: query
          description: 创建时间起始（含）
          required: false
          schema:
            type: string
            format: date
            example: '2026-01-01'
        -
          name: created_at_to
          in: query
          description: 创建时间截止（含）
          required: false
          schema:
            type: string
            format: date
            example: '2026-12-31'
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { properties: { items: { type: array, items: { $ref: '#/components/schemas/ApiRequestLogList' } }, total: { type: integer, example: 100 }, page: { type: integer, example: 1 }, per_page: { type: integer, example: 15 } }, type: object }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  '/api/v1/logs/requests/{id}':
    get:
      tags:
        - 'Request Logs'
      summary: 请求日志详情
      description: '获取请求日志详情，含完整请求体和 User-Agent。仅 admin 可访问。'
      operationId: f730ba32caa6f4a153d5d394a1102912
      parameters:
        -
          name: id
          in: path
          description: '请求日志 ID'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { $ref: '#/components/schemas/ApiRequestLogDetail' }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 无权限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 数据不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  /me/api-keys:
    get:
      tags:
        - ApiKeys
      summary: 'API Key 列表'
      description: '列出当前用户的所有 API Keys'
      operationId: c01c1650a1944005fe5b51f72bacbbd4
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { type: array, items: { properties: { id: { type: integer }, name: { type: string }, key_prefix: { type: string }, last_used_at: { type: string, format: date-time, nullable: true }, expires_at: { type: string, format: date-time, nullable: true }, enabled: { type: boolean }, created_at: { type: string, format: date-time } }, type: object } }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
    post:
      tags:
        - ApiKeys
      summary: '生成 API Key'
      description: '生成新的 API Key，需用户已启用 api_key_enabled。明文仅在生成时返回一次'
      operationId: 12fd3adae0626962960533c85569d1b1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - name
              properties:
                name:
                  type: string
                  example: 'Production Key'
                  maxLength: 100
                expires_at:
                  description: 过期时间，不传则永不过期
                  type: string
                  format: date-time
                  nullable: true
              type: object
      responses:
        '200':
          description: 生成成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 生成成功 }
                  data: { properties: { plain_key: { description: '明文 Key，仅此次可见', type: string }, api_key: { properties: { id: { type: integer }, name: { type: string }, key_prefix: { type: string }, expires_at: { type: string, format: date-time, nullable: true }, enabled: { type: boolean }, created_at: { type: string, format: date-time } }, type: object } }, type: object }
                type: object
        '400':
          description: 参数校验失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: '未启用 API Key 功能'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  '/me/api-keys/{id}':
    delete:
      tags:
        - ApiKeys
      summary: '删除 API Key'
      description: '删除 API Key'
      operationId: 7356615676c0ac3874f8657b49154931
      parameters:
        -
          name: id
          in: path
          description: 'API Key ID'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 删除成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 删除成功 }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 'API Key 不存在'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  /register:
    post:
      tags:
        - Auth
      summary: 用户注册
      description: 注册新用户，需提供用户名、密码和邮箱
      operationId: b099deca54ae9ddc3ee7e2261b6fc125
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - username
                - password
                - email
              properties:
                username:
                  type: string
                  example: new_user
                  maxLength: 20
                  minLength: 3
                password:
                  type: string
                  example: Pass_1234
                  maxLength: 32
                  minLength: 6
                email:
                  type: string
                  format: email
                  example: user@example.com
                  maxLength: 100
              type: object
      responses:
        '200':
          description: 注册成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 注册成功 }
                  data: { properties: { id: { type: integer, example: 1 }, username: { type: string, example: new_user }, email: { type: string, example: user@example.com } }, type: object }
                type: object
        '400':
          description: 参数校验失败或唯一性冲突
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /login:
    post:
      tags:
        - Auth
      summary: 用户登录
      description: '使用用户名和密码登录，返回 access_token 和 refresh_token'
      operationId: 383bcb1269d6dcce4609dc1f5d3ef129
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - username
                - password
              properties:
                username:
                  type: string
                  example: admin
                password:
                  type: string
                  example: Pass_1234
              type: object
      responses:
        '200':
          description: 登录成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 登录成功 }
                  data: { properties: { access_token: { type: string }, refresh_token: { type: string }, token_type: { type: string, example: Bearer }, expires_in: { type: integer, example: 7200 }, user: { properties: { id: { type: integer }, username: { type: string }, email: { type: string } }, type: object } }, type: object }
                type: object
        '400':
          description: 参数校验失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 用户名或密码错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 账号已被禁用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /refresh:
    get:
      tags:
        - Auth
      summary: '刷新 Access Token'
      description: '使用 refresh_token 获取新的 access_token，同时轮换 refresh_token'
      operationId: fc18486b361cc4791acbafd8a2f25fff
      parameters:
        -
          name: refresh_token
          in: query
          description: 'Refresh Token'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'Token 刷新成功'
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 'Token 刷新成功' }
                  data: { properties: { access_token: { type: string }, refresh_token: { type: string }, token_type: { type: string, example: Bearer }, expires_in: { type: integer, example: 7200 } }, type: object }
                type: object
        '400':
          description: '缺少 refresh_token 参数'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 'refresh_token 无效或已过期'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 账号已被禁用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  /me:
    get:
      tags:
        - Auth
      summary: 获取当前用户信息
      description: 获取当前用户信息
      operationId: f03c8d46af839b7dbd0b659647cab574
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { properties: { id: { type: integer, example: 1 }, username: { type: string, example: admin }, email: { type: string, example: admin@example.com }, status: { type: integer, example: 1 }, ext: { type: object, nullable: true }, created_at: { type: string, format: date-time } }, type: object }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  /me/profile:
    put:
      tags:
        - Auth
      summary: 更新个人信息
      description: '当前用户更新自己的 email 和 ext 字段'
      operationId: 01c6d8f425109cd3dfff51d1d69cd55c
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                email:
                  type: string
                  format: email
                  example: new@example.com
                  maxLength: 100
                ext:
                  type: object
                  example: { nickname: user }
                  nullable: true
              type: object
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 个人信息更新成功 }
                  data: { properties: { id: { type: integer }, username: { type: string }, email: { type: string }, status: { type: integer }, ext: { type: object, nullable: true }, created_at: { type: string, format: date-time } }, type: object }
                type: object
        '400':
          description: 参数校验失败或唯一性冲突
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  /me/password:
    put:
      tags:
        - Auth
      summary: 修改密码
      description: '修改当前用户密码，需验证旧密码。修改成功后清除 refresh_token，需重新登录'
      operationId: c3ca37414997ba697e6c11173d9bc483
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - old_password
                - new_password
              properties:
                old_password:
                  type: string
                  example: OldPass_1234
                new_password:
                  type: string
                  example: NewPass_5678
                  maxLength: 32
                  minLength: 6
              type: object
      responses:
        '200':
          description: 密码修改成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 密码修改成功，请重新登录 }
                type: object
        '400':
          description: 参数校验失败或旧密码不正确
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  /logout:
    get:
      tags:
        - Auth
      summary: 退出登录
      description: '退出登录，清除 refresh_token 并注销当前 JWT token'
      operationId: dc5f3d60e870dd8b211f88cd97635158
      responses:
        '200':
          description: 退出成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 退出成功 }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  /companies:
    get:
      tags:
        - Companies
      summary: 公司列表
      description: '获取公司列表，支持按 name/label 模糊搜索，受 scope 过滤'
      operationId: e3e4d8f38acabbb4c061ba987d6e14dc
      parameters:
        -
          name: name
          in: query
          description: '公司名称模糊搜索（匹配 name 或 label）'
          required: false
          schema:
            type: string
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { type: array, items: { properties: { id: { type: integer, example: 1 }, name: { type: string, example: acme }, label: { type: string, example: 阿克米公司 }, enabled: { type: boolean, example: true }, ext: { type: object, nullable: true }, created_at: { type: string, format: date-time }, updated_at: { type: string, format: date-time } }, type: object } }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  '/users/{id}/data-scope':
    get:
      tags:
        - DataScope
      summary: 查看用户数据权限
      description: '返回用户的 scope 列表（含实体名称）和解析后的 store_ids'
      operationId: 0215f552f5c2315b8b93d030ef72db76
      parameters:
        -
          name: id
          in: path
          description: '用户 ID'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { properties: { user_id: { type: integer, example: 1 }, role: { type: string, example: admin }, scopes: { type: array, items: { properties: { scope_type: { type: string, example: company }, scope_id: { type: integer, example: 1 }, name: { type: string, example: 示例公司 } }, type: object } }, resolved_store_ids: { type: array, items: { type: integer }, example: [1, 2, 3] } }, type: object }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 用户不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
    put:
      tags:
        - DataScope
      summary: 设置用户数据权限
      description: '全量替换用户的 scope 绑定，并重建 bitmap'
      operationId: 4ff88235674fa406239c90406f051994
      parameters:
        -
          name: id
          in: path
          description: '用户 ID'
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - scopes
              properties:
                scopes:
                  type: array
                  items: { required: [scope_type, scope_id], properties: { scope_type: { type: string, example: company, enum: [company, platform, store] }, scope_id: { type: integer, example: 1 } }, type: object }
              type: object
      responses:
        '200':
          description: 数据权限更新成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 数据权限更新成功 }
                type: object
        '400':
          description: '参数校验失败（无效 scope_type 等）'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 用户不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  /platforms:
    get:
      tags:
        - Platforms
      summary: 平台列表
      description: 获取全部平台列表（全局数据，不过滤）
      operationId: 5ff5cb3822eee3a87c0387f6a5ad4637
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { type: array, items: { properties: { id: { type: integer, example: 1 }, developer_id: { type: integer, example: 1 }, created_at: { type: string, format: date-time }, updated_at: { type: string, format: date-time } }, type: object } }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  /roles:
    get:
      tags:
        - Roles
      summary: 角色列表
      description: 获取所有角色，包含每个角色的用户数
      operationId: 9a543d6f94510bc9ca9208afc0b4715c
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { type: array, items: { properties: { id: { type: integer, example: 1 }, name: { type: string, example: editor }, users_count: { type: integer, example: 5 } }, type: object } }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  '/users/{id}/role':
    put:
      tags:
        - Roles
      summary: 分配用户角色
      description: '为指定用户分配角色，administrator 不允许降级自己的角色'
      operationId: 49884e2548d00ed9b195e873b2dd3934
      parameters:
        -
          name: id
          in: path
          description: '用户 ID'
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - role_id
              properties:
                role_id:
                  description: '角色 ID'
                  type: integer
                  example: 2
              type: object
      responses:
        '200':
          description: 角色分配成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 角色分配成功 }
                  data: { $ref: '#/components/schemas/User' }
                type: object
        '400':
          description: 不允许降级自己的管理员角色
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 用户或角色不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  '/roles/{id}/route-groups':
    get:
      tags:
        - Roles
      summary: 查看角色已授权的路由组
      description: 获取指定角色已授权的路由组列表
      operationId: 25aba1fb2a9a4cc81e1bf06c716deda9
      parameters:
        -
          name: id
          in: path
          description: '角色 ID'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { type: array, items: { type: object } }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 角色不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
    put:
      tags:
        - Roles
      summary: 设置角色的路由组授权
      description: '全量替换指定角色的路由组授权，administrator 角色不允许修改'
      operationId: 1e1f0c23e58bc994ea055407eb469a37
      parameters:
        -
          name: id
          in: path
          description: '角色 ID'
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - group_ids
              properties:
                group_ids:
                  type: array
                  items: { type: integer }
                  example: [1, 3, 5]
              type: object
      responses:
        '200':
          description: 路由组授权更新成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 路由组授权更新成功 }
                  data: { type: array, items: { type: object } }
                type: object
        '400':
          description: 'administrator 角色不允许修改或参数错误'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 角色不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  '/roles/{id}/route-overrides':
    get:
      tags:
        - Roles
      summary: 查看角色的路由覆盖
      description: 获取指定角色的路由覆盖列表，包含路由详情
      operationId: 7766effa17b431f2bcd67b1f434ee042
      parameters:
        -
          name: id
          in: path
          description: '角色 ID'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { type: array, items: { properties: { id: { type: integer }, role_id: { type: integer }, route_id: { type: integer }, allowed: { type: boolean }, route: { type: object } }, type: object } }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 角色不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
    put:
      tags:
        - Roles
      summary: 设置角色的路由覆盖
      description: '全量替换指定角色的路由覆盖规则，administrator 角色不允许修改'
      operationId: 7ab36e126b6eb4e7631cc7b51b5d2779
      parameters:
        -
          name: id
          in: path
          description: '角色 ID'
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - overrides
              properties:
                overrides:
                  type: array
                  items: { required: [route_id, allowed], properties: { route_id: { description: '路由 ID', type: integer, example: 12 }, allowed: { description: 是否允许, type: boolean, example: false } }, type: object }
              type: object
      responses:
        '200':
          description: 路由覆盖更新成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 路由覆盖更新成功 }
                  data: { type: array, items: { properties: { id: { type: integer }, role_id: { type: integer }, route_id: { type: integer }, allowed: { type: boolean }, route: { type: object } }, type: object } }
                type: object
        '400':
          description: 'route_id 重复、不存在或 administrator 角色不允许修改'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 角色不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  /route-groups:
    get:
      tags:
        - RouteGroups
      summary: 路由组列表
      description: 返回所有路由组，包含每组的路由数量
      operationId: dc2a90e0b1d08db3762003eac4f93598
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { type: array, items: { properties: { id: { type: integer, example: 1 }, name: { type: string, example: user-management }, label: { type: string, example: 用户管理, nullable: true }, description: { type: string, example: 用户相关路由, nullable: true }, sort_order: { type: integer, example: 0 }, routes_count: { type: integer, example: 5 }, created_at: { type: string, format: date-time } }, type: object } }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
    post:
      tags:
        - RouteGroups
      summary: 创建路由组
      description: 创建路由组
      operationId: 5796b5d8d366ca24bd7b850510fdc77d
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - name
              properties:
                name:
                  type: string
                  example: user-management
                  maxLength: 100
                label:
                  type: string
                  example: 用户管理
                  nullable: true
                  maxLength: 200
                description:
                  type: string
                  example: 用户相关路由
                  nullable: true
                sort_order:
                  type: integer
                  example: 0
                  default: 0
              type: object
      responses:
        '200':
          description: 创建成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 创建成功 }
                  data: { properties: { id: { type: integer, example: 1 }, name: { type: string, example: user-management }, label: { type: string, example: 用户管理, nullable: true }, description: { type: string, nullable: true }, sort_order: { type: integer, example: 0 }, created_at: { type: string, format: date-time } }, type: object }
                type: object
        '400':
          description: 参数校验失败或名称重复
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  '/route-groups/{id}':
    put:
      tags:
        - RouteGroups
      summary: 更新路由组
      description: 更新路由组
      operationId: 08ab6c0eb639ed8c3c7b2aa5151f3f8b
      parameters:
        -
          name: id
          in: path
          description: '路由组 ID'
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                name:
                  type: string
                  example: user-management
                  maxLength: 100
                label:
                  type: string
                  example: 用户管理
                  nullable: true
                  maxLength: 200
                description:
                  type: string
                  example: 用户相关路由
                  nullable: true
                sort_order:
                  type: integer
                  example: 0
              type: object
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 更新成功 }
                  data: { properties: { id: { type: integer, example: 1 }, name: { type: string, example: user-management }, label: { type: string, example: 用户管理, nullable: true }, description: { type: string, nullable: true }, sort_order: { type: integer, example: 0 }, created_at: { type: string, format: date-time } }, type: object }
                type: object
        '400':
          description: 参数校验失败或名称重复
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 路由组不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
    delete:
      tags:
        - RouteGroups
      summary: 删除路由组
      description: '删除路由组，组内路由 group_id 自动设为 NULL，role_route_groups 关联自动级联删除'
      operationId: 2b870b541944a9318469fafc2ad83834
      parameters:
        -
          name: id
          in: path
          description: '路由组 ID'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 删除成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 删除成功 }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 路由组不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  /routes:
    get:
      tags:
        - RouteGroups
      summary: 路由列表
      description: '获取全部路由列表，含分组信息，支持按 group_id、method、path 筛选'
      operationId: 06fcdb734181d39362a999d1599a5e66
      parameters:
        -
          name: group_id
          in: query
          description: '路由组 ID，传 0 或 "ungrouped" 筛选未分组路由'
          required: false
          schema:
            type: string
        -
          name: method
          in: query
          description: 'HTTP 方法筛选'
          required: false
          schema:
            type: string
        -
          name: path
          in: query
          description: 路径模糊搜索
          required: false
          schema:
            type: string
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { type: array, items: { properties: { id: { type: integer, example: 1 }, method: { type: string, example: GET }, path: { type: string, example: /api/v1/users }, group_id: { type: integer, example: 1, nullable: true }, group: { properties: { id: { type: integer, example: 1 }, name: { type: string, example: user-management }, label: { type: string, example: 用户管理, nullable: true } }, type: object, nullable: true } }, type: object } }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  '/routes/{id}/group':
    put:
      tags:
        - RouteGroups
      summary: 分配路由到路由组
      description: '将路由分配到指定路由组，传 group_id=null 表示从分组中移出'
      operationId: 10daee20cc95a281bc0bc3716df103aa
      parameters:
        -
          name: id
          in: path
          description: '路由 ID'
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - group_id
              properties:
                group_id:
                  description: '路由组 ID，传 null 移出分组'
                  type: integer
                  example: 1
                  nullable: true
              type: object
      responses:
        '200':
          description: 分配成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 分配成功 }
                  data: { properties: { id: { type: integer, example: 1 }, method: { type: string, example: GET }, path: { type: string, example: /api/v1/users }, group_id: { type: integer, example: 1, nullable: true }, group: { properties: { id: { type: integer, example: 1 }, name: { type: string, example: user-management }, label: { type: string, example: 用户管理, nullable: true } }, type: object, nullable: true } }, type: object }
                type: object
        '400':
          description: 参数校验失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 路由或目标路由组不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  /stores:
    get:
      tags:
        - Stores
      summary: 店铺列表
      description: '获取店铺列表，受 scope 过滤，支持 company_id/platform_id 筛选及 name 模糊搜索'
      operationId: 36279ef5f2735b2624e99a82ebc3dccc
      parameters:
        -
          name: company_id
          in: query
          description: '按公司 ID 筛选'
          required: false
          schema:
            type: integer
        -
          name: platform_id
          in: query
          description: '按平台 ID 筛选'
          required: false
          schema:
            type: integer
        -
          name: name
          in: query
          description: 按店铺名称模糊搜索
          required: false
          schema:
            type: string
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { type: array, items: { properties: { id: { type: integer, example: 1 }, company_id: { type: integer, example: 1 }, platform_id: { type: integer, example: 1 }, platform_store_id: { type: string, example: SHOP-001 }, name: { type: string, example: my-store }, label: { type: string, example: 我的店铺 }, enabled: { type: boolean, example: true }, warehouse_id: { type: integer, example: 1 }, currency_id: { type: integer, example: 1 }, timezone: { type: integer, example: 8 }, created_at: { type: string, format: date-time }, updated_at: { type: string, format: date-time } }, type: object } }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  /users:
    get:
      tags:
        - Users
      summary: 用户列表
      description: '获取用户列表，支持分页、按 username/email 模糊搜索、按 status 精确筛选'
      operationId: 4f028975120b69092c0eae73bb36bcac
      parameters:
        -
          name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
        -
          name: per_page
          in: query
          required: false
          schema:
            type: integer
            default: 15
            maximum: 100
        -
          name: username
          in: query
          description: 用户名模糊搜索
          required: false
          schema:
            type: string
        -
          name: email
          in: query
          description: 邮箱模糊搜索
          required: false
          schema:
            type: string
        -
          name: status
          in: query
          description: 状态筛选（0=禁用，1=启用）
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { properties: { items: { type: array, items: { $ref: '#/components/schemas/User' } }, total: { type: integer, example: 100 }, page: { type: integer, example: 1 }, per_page: { type: integer, example: 15 } }, type: object }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
    post:
      tags:
        - Users
      summary: 创建用户
      description: 创建用户
      operationId: 0b5969ce7b77ccaa0b2e9b551e302980
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - username
                - password
                - email
              properties:
                username:
                  type: string
                  example: new_user
                  maxLength: 20
                  minLength: 3
                password:
                  type: string
                  example: Pass_1234
                  maxLength: 32
                  minLength: 6
                email:
                  type: string
                  format: email
                  example: new@example.com
                  maxLength: 100
                status:
                  type: integer
                  default: 1
                  enum: [0, 1]
              type: object
      responses:
        '200':
          description: 创建成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 创建成功 }
                  data: { $ref: '#/components/schemas/User' }
                type: object
        '400':
          description: 参数校验失败或唯一性冲突
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  '/users/{id}':
    get:
      tags:
        - Users
      summary: 用户详情
      description: 用户详情
      operationId: b0770c8ad8eb11c5493fe9643c657673
      parameters:
        -
          name: id
          in: path
          description: '用户 ID'
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 获取成功 }
                  data: { $ref: '#/components/schemas/User' }
                type: object
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 用户不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
    put:
      tags:
        - Users
      summary: 更新用户信息
      description: '更新用户的 username、email 或 ext 字段，不支持修改密码'
      operationId: c5ee224e653aac218896c93ecc3f9b67
      parameters:
        -
          name: id
          in: path
          description: '用户 ID'
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                username:
                  type: string
                  example: updated_user
                  maxLength: 20
                  minLength: 3
                email:
                  type: string
                  format: email
                  example: updated@example.com
                  maxLength: 100
                ext:
                  type: object
                  example: { nickname: Tester }
                  nullable: true
              type: object
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 更新成功 }
                  data: { $ref: '#/components/schemas/User' }
                type: object
        '400':
          description: 参数校验失败或唯一性冲突
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 用户不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
  '/users/{id}/status':
    patch:
      tags:
        - Users
      summary: 更新用户状态
      description: 启用或禁用用户
      operationId: c1ad72b12757d083cf0aebbf2f3787fd
      parameters:
        -
          name: id
          in: path
          description: '用户 ID'
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - status
              properties:
                status:
                  description: 0=禁用，1=启用
                  type: integer
                  enum: [0, 1]
              type: object
      responses:
        '200':
          description: 状态更新成功
          content:
            application/json:
              schema:
                properties:
                  code: { type: integer, example: 0 }
                  message: { type: string, example: 状态更新成功 }
                  data: { $ref: '#/components/schemas/User' }
                type: object
        '400':
          description: 参数校验失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未认证
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 用户不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        -
          bearerAuth: []
components:
  schemas:
    Order:
      properties:
        id:
          type: integer
          example: 1
        company_id:
          type: integer
          example: 1
        platform_id:
          type: integer
          example: 2
        store_id:
          type: integer
          example: 100
        order_status_id:
          type: integer
          example: 1
        platform_order_id:
          type: string
          example: ORD-20260101-001
        buyer_user_id:
          type: string
          example: buyer_123
          nullable: true
        payment_method_id:
          type: integer
          example: 1
        presale:
          type: boolean
          example: false
        total_amount:
          type: number
          format: decimal
          example: 199.99
        total_paid:
          type: number
          format: decimal
          example: 189.99
        total_discount:
          type: number
          format: decimal
          example: 10
        total_received:
          type: number
          format: decimal
          example: 189.99
        freight_fee:
          type: number
          format: decimal
          example: 0
        tax_fee:
          type: number
          format: decimal
          example: 0
        discount_fee:
          type: number
          format: decimal
          example: 10
        commission_fee:
          type: number
          format: decimal
          example: 5
        coupon_amount:
          type: number
          format: decimal
          example: 0
        voucher_amount:
          type: number
          format: decimal
          example: 0
        order_type_id:
          type: integer
          example: 1
        hash:
          type: string
          example: a1b2c3d4e5f6...
        raw:
          description: 平台原始数据
          type: object
          nullable: true
        ext:
          description: 扩展字段
          type: object
          nullable: true
        created_date:
          type: string
          format: date-time
        updated_date:
          type: string
          format: date-time
          nullable: true
        paid_date:
          type: string
          format: date-time
          nullable: true
        shipping_date:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      type: object
    OrderItem:
      properties:
        id:
          type: integer
          example: 1
        company_id:
          type: integer
          example: 1
        platform_id:
          type: integer
          example: 2
        store_id:
          type: integer
          example: 100
        order_id:
          type: integer
          example: 1000
        platform_order_id:
          type: string
          example: ORD-20260101-001
        sub_order_id:
          type: string
          example: SUB-001
          nullable: true
        sub_order_type_id:
          type: integer
          example: 1
        product_id:
          type: integer
          example: 500
        platform_product_id:
          type: string
          example: PROD-001
        product_sku:
          type: string
          example: SKU-ABC-001
          nullable: true
        product_barcode:
          type: string
          example: '6901234567890'
          nullable: true
        unit_price:
          type: number
          format: decimal
          example: 49.99
        quantity:
          type: integer
          example: 2
        discount:
          type: number
          format: decimal
          example: 5
        total:
          type: number
          format: decimal
          example: 94.98
        created_date:
          type: string
          format: date-time
        ext:
          description: 扩展字段
          type: object
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      type: object
    Product:
      properties:
        id:
          type: integer
          example: 1
        company_id:
          type: integer
          example: 1
        platform_id:
          type: integer
          example: 2
        store_id:
          type: integer
          example: 100
        status_id:
          type: integer
          example: 1
        type_id:
          type: integer
          example: 1
        platform_item_id:
          type: string
          example: ITEM-001
        platform_model_id:
          type: string
          example: MODEL-A
          nullable: true
        name:
          type: string
          example: 'iPhone 16 Pro'
          nullable: true
        price:
          type: number
          format: decimal
          example: 99.99
        currency:
          type: string
          example: CNY
        num:
          type: integer
          example: 100
        hash:
          type: string
          example: a1b2c3d4e5f6...
        raw:
          description: 平台原始数据
          type: object
          nullable: true
        ext:
          description: 扩展字段
          type: object
          nullable: true
        created_date:
          type: string
          format: date-time
          nullable: true
        updated_date:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      type: object
    Refund:
      properties:
        id:
          type: integer
          example: 1
        company_id:
          type: integer
          example: 1
        platform_id:
          type: integer
          example: 2
        store_id:
          type: integer
          example: 100
        order_id:
          type: integer
          example: 500
          nullable: true
        platform_order_id:
          type: string
          example: ORD-20260101-001
        platform_refund_id:
          type: string
          example: RF-20260115-001
        refund_status_id:
          type: integer
          example: 1
        refund_type_id:
          type: integer
          example: 2
        reason:
          type: string
          example: 商品质量问题
          nullable: true
        buyer_user_id:
          type: string
          example: buyer_123
          nullable: true
        refund_amount:
          type: number
          format: decimal
          example: 99.99
        freight_refund:
          type: number
          format: decimal
          example: 10
        refund_total:
          type: number
          format: decimal
          example: 109.99
        currency:
          type: string
          example: CNY
        hash:
          type: string
          example: a1b2c3d4e5f6...
        raw:
          description: 平台原始数据
          type: object
          nullable: true
        ext:
          description: 扩展字段
          type: object
          nullable: true
        order_created_date:
          type: string
          format: date-time
          nullable: true
        order_paid_date:
          type: string
          format: date-time
          nullable: true
        created_date:
          type: string
          format: date-time
        updated_date:
          type: string
          format: date-time
          nullable: true
        completed_date:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      type: object
    RefundItem:
      properties:
        id:
          type: integer
          example: 1
        company_id:
          type: integer
          example: 1
        platform_id:
          type: integer
          example: 2
        store_id:
          type: integer
          example: 100
        refund_id:
          type: integer
          example: 50
        platform_parent_refund_id:
          type: string
          example: PRF-001
          nullable: true
        platform_refund_id:
          type: string
          example: RF-ITEM-001
        refund_status_id:
          type: integer
          example: 1
        refund_type_id:
          type: integer
          example: 2
        reason:
          type: string
          example: 商品质量问题
          nullable: true
        currency:
          type: string
          example: CNY
        buyer_user_id:
          type: string
          example: buyer_123
          nullable: true
        platform_order_id:
          type: string
          example: ORD-20260101-001
        platform_sub_order_id:
          type: string
          example: SUB-001
          nullable: true
        platform_product_id:
          type: string
          example: PROD-001
          nullable: true
        quantity:
          type: integer
          example: 1
        refund_amount:
          type: number
          format: decimal
          example: 99.99
        raw:
          description: 平台原始子项数据
          type: object
          nullable: true
        ext:
          description: 扩展字段
          type: object
          nullable: true
        order_created_date:
          type: string
          format: date-time
          nullable: true
        order_paid_date:
          type: string
          format: date-time
          nullable: true
        created_date:
          type: string
          format: date-time
        updated_date:
          type: string
          format: date-time
          nullable: true
        completed_date:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      type: object
    User:
      properties:
        id:
          type: integer
          example: 1
        username:
          type: string
          example: user_1234
        email:
          type: string
          example: user@example.com
        status:
          type: integer
          example: 1
        role_id:
          type: integer
          example: 1
          nullable: true
        api_key_enabled:
          type: boolean
          example: false
        ext:
          type: object
          example:
            nickname: user
          nullable: true
        refresh_token_expires_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      type: object
    ApiResponse:
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: success
        data:
          type: object
          nullable: true
      type: object
    PaginatedData:
      properties:
        items:
          type: array
          items: {  }
        total:
          type: integer
          example: 0
        page:
          type: integer
          example: 1
        per_page:
          type: integer
          example: 15
      type: object
    ErrorResponse:
      properties:
        code:
          type: integer
          example: 400
        message:
          type: string
          example: 'Bad request'
        data:
          type: object
          nullable: true
      type: object
    MqQueueInfo:
      description: 单个队列的状态信息
      properties:
        queue:
          description: 队列名称
          type: string
          example: orders.queue
        messages:
          description: '消息数量（异常时为 N/A）'
          example: 5
          oneOf:
            -
              type: integer
            -
              type: string
        consumers:
          description: '消费者数量（异常时为 N/A）'
          example: 1
          oneOf:
            -
              type: integer
            -
              type: string
        status:
          description: 队列状态
          type: string
          example: active
          enum:
            - high_load
            - processing
            - active
            - empty
            - error
      type: object
    MqQueueStatus:
      description: 消息队列全量状态
      properties:
        business_queues:
          description: 业务队列列表
          type: array
          items:
            $ref: '#/components/schemas/MqQueueInfo'
        retry_queues:
          description: 重试队列列表
          type: array
          items:
            $ref: '#/components/schemas/MqQueueInfo'
        error_queue:
          $ref: '#/components/schemas/MqQueueInfo'
        summary:
          description: 汇总统计
          properties:
            total_messages:
              description: 消息总数
              type: integer
              example: 7
            total_consumers:
              description: 消费者总数
              type: integer
              example: 1
          type: object
        fetched_at:
          description: 数据获取时间
          type: string
          format: date-time
          example: '2026-03-13 12:00:00'
      type: object
    FailedMessageList:
      description: 失败消息列表项
      properties:
        id:
          type: integer
          example: 1
        error_id:
          type: string
          example: err_67890abc
        data_type:
          type: string
          example: order
          enum:
            - order
            - product
            - refund
        platform:
          type: string
          example: Tmall
          nullable: true
        platform_id:
          type: integer
          example: 1
          nullable: true
        company_id:
          type: integer
          example: 1
          nullable: true
        store_id:
          type: integer
          example: 1
          nullable: true
        error_type:
          type: string
          example: RuntimeException
        error_message:
          type: string
          example: 'Connection refused'
        retry_count:
          type: integer
          example: 3
        message_id:
          type: string
          example: msg_12345
          nullable: true
        failed_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
      type: object
    FailedMessageDetail:
      description: 失败消息详情（含完整错误堆栈和原始消息体）
      properties:
        id:
          type: integer
          example: 1
        error_id:
          type: string
          example: err_67890abc
        data_type:
          type: string
          example: order
          enum:
            - order
            - product
            - refund
        platform:
          type: string
          example: Tmall
          nullable: true
        platform_id:
          type: integer
          example: 1
          nullable: true
        company_id:
          type: integer
          example: 1
          nullable: true
        store_id:
          type: integer
          example: 1
          nullable: true
        error_type:
          type: string
          example: RuntimeException
        error_message:
          type: string
          example: 'Connection refused'
        error_code:
          type: integer
          example: 0
        error_trace:
          description: 完整异常堆栈
          type: string
        original_message:
          description: '原始消息体 JSON'
          type: object
        retry_count:
          type: integer
          example: 3
        message_id:
          type: string
          example: msg_12345
          nullable: true
        failed_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
      type: object
    DashboardOverview:
      description: 'Dashboard 概览统计'
      properties:
        today:
          description: 今日统计
          properties:
            success:
              type: integer
              example: 120
            failed:
              type: integer
              example: 3
          type: object
        this_week:
          description: 本周统计
          properties:
            success:
              type: integer
              example: 850
            failed:
              type: integer
              example: 15
          type: object
        this_month:
          description: 本月统计
          properties:
            success:
              type: integer
              example: 3200
            failed:
              type: integer
              example: 42
          type: object
        by_type:
          description: 按数据类型分组统计（本月窗口）
          type: array
          items:
            properties:
              data_type:
                type: string
                example: order
                enum:
                  - order
                  - product
                  - refund
                  - inventory
              success:
                type: integer
                example: 1000
              failed:
                type: integer
                example: 10
            type: object
      type: object
    DashboardTrendItem:
      description: 趋势数据点
      properties:
        date:
          type: string
          format: date
          example: '2026-03-17'
        success:
          type: integer
          example: 120
        failed:
          type: integer
          example: 3
      type: object
    DashboardBreakdownItem:
      description: 分组统计项
      properties:
        id:
          description: '维度 ID（公司/平台/店铺）'
          type: integer
          example: 1
        name:
          description: 维度名称
          type: string
          example: Tmall
        success:
          type: integer
          example: 500
        failed:
          type: integer
          example: 8
      type: object
    ApiRequestLogList:
      description: 'API 请求日志列表项'
      properties:
        id:
          type: integer
          example: 1
        user_id:
          type: integer
          example: 1
          nullable: true
        method:
          type: string
          example: GET
        path:
          type: string
          example: /api/v1/users
        status_code:
          type: integer
          example: 200
        ip:
          type: string
          example: 127.0.0.1
          nullable: true
        response_code:
          type: integer
          example: 0
          nullable: true
        duration_ms:
          type: integer
          example: 42
        created_at:
          type: string
          format: date-time
      type: object
    ApiRequestLogDetail:
      description: 'API 请求日志详情（含完整请求体和 User-Agent）'
      properties:
        id:
          type: integer
          example: 1
        user_id:
          type: integer
          example: 1
          nullable: true
        method:
          type: string
          example: POST
        path:
          type: string
          example: /api/v1/users
        status_code:
          type: integer
          example: 200
        ip:
          type: string
          example: 127.0.0.1
          nullable: true
        user_agent:
          type: string
          example: Mozilla/5.0
          nullable: true
        request_body:
          description: 请求体（脱敏后）
          type: object
          nullable: true
        response_code:
          type: integer
          example: 0
          nullable: true
        duration_ms:
          type: integer
          example: 42
        created_at:
          type: string
          format: date-time
      type: object
  securitySchemes:
    bearerAuth:
      type: http
      bearerFormat: JWT
      scheme: bearer
    apiKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header
tags:
  -
    name: Dashboard
    description: 'Dashboard 数据同步统计'
  -
    name: 'Failed Messages'
    description: 失败消息查看
  -
    name: 'MQ Status'
    description: 消息队列状态监控
  -
    name: Orders
    description: 订单管理
  -
    name: 'Order Items'
    description: 订单项管理
  -
    name: Products
    description: 产品管理
  -
    name: 'Orders (Raw)'
    description: 订单原始数据
  -
    name: 'Products (Raw)'
    description: 产品原始数据
  -
    name: 'Refunds (Raw)'
    description: 退款原始数据
  -
    name: 'Refund Items (Raw)'
    description: 退款项原始数据
  -
    name: Refunds
    description: 退款管理
  -
    name: 'Refund Items'
    description: 退款项管理
  -
    name: 'Request Logs'
    description: 'API 请求日志查看'
  -
    name: ApiKeys
    description: 'API Key 管理'
  -
    name: Auth
    description: 认证与个人信息
  -
    name: Companies
    description: 公司管理
  -
    name: DataScope
    description: 用户数据范围管理
  -
    name: Platforms
    description: 平台管理
  -
    name: Roles
    description: 角色与授权管理
  -
    name: RouteGroups
    description: 路由组管理
  -
    name: Stores
    description: 店铺管理
  -
    name: Users
    description: 用户管理