paths:
  orderList:
    post:
      tags: [订单]
      summary: 查询订单列表
      description: |
        调用自定义 hooks API 查询当前登录用户的订单列表。
        请求头请自行携带 `Authorization: Bearer <token>`。
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderListRequest'
            example:
              keyword: 模糊搜索关键字|string
              order_status: 订单状态|string
              order_source: 订单来源|string
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderListResponse'
        '400':
          description: 参数错误
        '401':
          description: token 无效或已过期
        '415':
          description: 请求体必须为 application/json
        '500':
          description: 服务端错误
  orderDetail:
    post:
      tags: [订单]
      summary: 查询订单详情
      description: |
        调用自定义 hooks API 按 `order_id` 查询单条订单记录。
        请求头请自行携带 `Authorization: Bearer <token>`。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderDetailRequest'
            example:
              order_id: 订单业务ID|string
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderRecord'
        '400':
          description: 参数错误
        '401':
          description: token 无效或已过期
        '403':
          description: 无权访问该订单记录
        '404':
          description: 未找到对应订单记录
        '415':
          description: 请求体必须为 application/json
        '500':
          description: 服务端错误
  orderCreate:
    post:
      tags: [订单]
      summary: 新增订单记录
      description: |
        调用自定义 hooks API 新增订单记录。
        服务端会基于当前 token 自动写入 `order_owner` 并生成 `order_id`。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCreateRequest'
            example:
              order_number: 可选；未传时服务端自动生成|string
              order_source: 订单来源|string
              order_status: 订单状态|string
              order_source_id: 来源关联业务ID|string
              order_snap:
                字段名|string: 字段值|string
              order_amount: 订单金额|integer
              order_remark: 备注|string
      responses:
        '200':
          description: 创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderRecord'
        '400':
          description: 参数错误或创建失败
        '401':
          description: token 无效或已过期
        '415':
          description: 请求体必须为 application/json
        '429':
          description: 重复请求过于频繁
        '500':
          description: 服务端错误
  orderUpdate:
    post:
      tags: [订单]
      summary: 修改订单记录
      description: |
        调用自定义 hooks API 按 `order_id` 更新订单记录。
        请求头请自行携带 `Authorization: Bearer <token>`。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderUpdateRequest'
            example:
              order_id: 订单业务ID|string
              order_number: 订单编号|string
              order_source: 订单来源|string
              order_status: 订单状态|string
              order_source_id: 来源关联业务ID|string
              order_snap:
                字段名|string: 字段值|string
              order_amount: 订单金额|integer
              order_remark: 备注|string
      responses:
        '200':
          description: 更新成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderRecord'
        '400':
          description: 参数错误或更新失败
        '401':
          description: token 无效或已过期
        '403':
          description: 无权访问该订单记录
        '404':
          description: 未找到待修改记录
        '415':
          description: 请求体必须为 application/json
        '429':
          description: 重复请求过于频繁
        '500':
          description: 服务端错误
  orderDelete:
    post:
      tags: [订单]
      summary: 删除订单记录
      description: |
        调用自定义 hooks API 按 `order_id` 删除订单记录。
        当前后端实现以实际 hooks 逻辑为准。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderDeleteRequest'
            example:
              order_id: 订单业务ID|string
      responses:
        '200':
          description: 删除成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDeleteResponse'
        '400':
          description: 参数错误或删除失败
        '401':
          description: token 无效或已过期
        '403':
          description: 无权访问该订单记录
        '404':
          description: 未找到待删除记录
        '415':
          description: 请求体必须为 application/json
        '429':
          description: 重复请求过于频繁
        '500':
          description: 服务端错误
components:
  schemas:
    OrderRecord:
      type: object
      properties:
        pb_id:
          type: string
          description: PocketBase记录主键id
        created:
          type: string
          description: PocketBase系统创建时间
        updated:
          type: string
          description: PocketBase系统更新时间
        order_id:
          type: string
          description: 订单业务ID
        order_number:
          type: string
          description: 订单编号
        order_create:
          type: string
          description: 订单创建时间
        order_owner:
          type: string
          description: 订单所有者openid
        order_source:
          type: string
          description: 订单来源
        order_status:
          type: string
          description: 订单状态
        order_source_id:
          type: string
          description: 来源关联业务ID
        order_snap:
          type: object
          additionalProperties: true
          description: 订单快照
        order_amount:
          type: [integer, number]
          description: 订单金额
        order_remark:
          type: string
          description: 备注
        is_delete:
          type: [integer, number]
          description: 删除标记
      example:
        pb_id: PocketBase记录主键id|string
        created: PocketBase系统创建时间|string
        updated: PocketBase系统更新时间|string
        order_id: 订单业务ID|string
        order_number: 订单编号|string
        order_create: 订单创建时间|string
        order_owner: 订单所有者openid|string
        order_source: 订单来源|string
        order_status: 订单状态|string
        order_source_id: 来源关联业务ID|string
        order_snap:
          字段名|string: 字段值|string
        order_amount: 订单金额|integer
        order_remark: 备注|string
        is_delete: 删除标记|integer
    OrderListRequest:
      type: object
      properties:
        keyword:
          type: string
        order_status:
          type: string
        order_source:
          type: string
      example:
        keyword: 模糊搜索关键字|string
        order_status: 订单状态|string
        order_source: 订单来源|string
    OrderDetailRequest:
      type: object
      required: [order_id]
      properties:
        order_id:
          type: string
      example:
        order_id: 订单业务ID|string
    OrderCreateRequest:
      type: object
      required: [order_source, order_source_id, order_snap, order_amount]
      properties:
        order_number:
          type: string
        order_source:
          type: string
        order_status:
          type: string
        order_source_id:
          type: string
        order_snap:
          type: object
          additionalProperties: true
        order_amount:
          type: [integer, number]
        order_remark:
          type: string
      example:
        order_number: 可选；未传时服务端自动生成|string
        order_source: 订单来源|string
        order_status: 订单状态|string
        order_source_id: 来源关联业务ID|string
        order_snap:
          字段名|string: 字段值|string
        order_amount: 订单金额|integer
        order_remark: 备注|string
    OrderUpdateRequest:
      type: object
      required: [order_id]
      properties:
        order_id:
          type: string
        order_number:
          type: string
        order_source:
          type: string
        order_status:
          type: string
        order_source_id:
          type: string
        order_snap:
          type: object
          additionalProperties: true
        order_amount:
          type: [integer, number]
        order_remark:
          type: string
      example:
        order_id: 订单业务ID|string
        order_number: 订单编号|string
        order_source: 订单来源|string
        order_status: 订单状态|string
        order_source_id: 来源关联业务ID|string
        order_snap:
          字段名|string: 字段值|string
        order_amount: 订单金额|integer
        order_remark: 备注|string
    OrderDeleteRequest:
      type: object
      required: [order_id]
      properties:
        order_id:
          type: string
      example:
        order_id: 订单业务ID|string
    OrderListResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderRecord'
      example:
        items:
          - pb_id: PocketBase记录主键id|string
            created: PocketBase系统创建时间|string
            updated: PocketBase系统更新时间|string
            order_id: 订单业务ID|string
            order_number: 订单编号|string
            order_create: 订单创建时间|string
            order_owner: 订单所有者openid|string
            order_source: 订单来源|string
            order_status: 订单状态|string
            order_source_id: 来源关联业务ID|string
            order_snap:
              字段名|string: 字段值|string
            order_amount: 订单金额|integer
            order_remark: 备注|string
    OrderDeleteResponse:
      type: object
      properties:
        order_id:
          type: string
        is_delete:
          type: [integer, number]
      example:
        order_id: 订单业务ID|string
        is_delete: 删除标记|integer
