openapi: 3.1.0
info:
  title: AI 软件商城 Agent API
  description: 面向 Agent 提供的数字化商品商城接口，支持商品搜索、下单、HTTP 402 A2Apay 支付及交付验证。
  version: 1.0.0
servers:
  - url: https://store.bushrose.cn  # 部署后请替换为您的真实域名
paths:
  /api/software:
    get:
      summary: 搜索软件商品
      operationId: getSoftwareList
      parameters:
        - name: keyword
          in: query
          description: 搜索关键词
          required: false
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        "200":
          description: 成功返回商品列表
  /api/orders:
    post:
      summary: 创建订单
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [softwareId]
              properties:
                softwareId:
                  type: integer
                  description: 要购买的软件ID
      responses:
        "200":
          description: 订单创建成功，返回 orderNo
  /api/orders/{orderNo}/payment-needed:
    post:
      summary: 获取支付参数 (402 Payment Needed)
      operationId: getPaymentNeeded
      parameters:
        - name: orderNo
          in: path
          required: true
          schema:
            type: string
      responses:
        "402":
          description: 需要支付，返回 payment parameters
  /api/orders/{orderNo}/verify:
    post:
      summary: 提交支付凭证并获取下载链接
      operationId: verifyPayment
      parameters:
        - name: orderNo
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [paymentProof]
              properties:
                paymentProof:
                  type: string
                  description: 支付插件返回的 base64 格式的 Payment-Proof
      responses:
        "200":
          description: 验证成功，返回 delivery.downloadUrl 等交付信息