{
  "openapi": "3.0.3",
  "info": {
    "title": "重庆环卫-通用预扣款订单接口",
    "version": "1.0.0",
    "description": "智慧餐厅 store + ai_api 通用预扣款订单接口文档。当前用于咖啡机对接，后续可兼容其他预扣款来源。"
  },
  "servers": [
    {
      "url": "http://127.0.0.1",
      "description": "本地 zhctapp_v2_0 开发容器"
    }
  ],
  "tags": [
    {
      "name": "外部接口/三方调用康比特/预扣款订单-咖啡机对接",
      "description": "咖啡机接口 A/C/B 与小程序扫码入口"
    }
  ],
  "paths": {
    "/api/prepayOrder/code": {
      "post": {
        "tags": [
          "外部接口/三方调用康比特/预扣款订单-咖啡机对接"
        ],
        "x-apifox-folder": "外部接口/三方调用康比特/预扣款订单-咖啡机对接",
        "summary": "接口 A：取码",
        "description": "咖啡机发起取码请求。智慧餐厅校验 machid 对应设备是否存在且设备类型为咖啡机，校验签名，创建或复用预扣款订单，返回小程序扫码入口二维码参数。签名算法：取 appkey、timestamp、randstr 三个字符串按字典序排序后直接拼接，计算 sha1 小写值。",
        "operationId": "createPrepayOrderCode",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/PrepayCodeRequest"
              },
              "examples": {
                "coffee": {
                  "summary": "咖啡机取码",
                  "value": {
                    "orderid": "CQHW_E2E_20260728_ORDER_10001",
                    "machid": "CQHW_E2E_20260728_MACH_001",
                    "trackno": "LATTE-01",
                    "name": "拿铁",
                    "price": "1200",
                    "channelid": "BALANCE",
                    "timestamp": "1785218917",
                    "randstr": "CQHW_E2E_20260728_RAND_A",
                    "sign": "按签名算法生成"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "取码结果。code=1 表示成功；code=0 表示失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrepayCodeResponse"
                },
                "examples": {
                  "success": {
                    "summary": "成功",
                    "value": {
                      "orderid": "CQHW_E2E_20260728_ORDER_10001",
                      "torderid": "5",
                      "twocode": "http://127.0.0.1/aizhct/api/PrepayOrder/scan?type=prepay&source=1&orderid=CQHW_E2E_20260728_ORDER_10001&machid=CQHW_E2E_20260728_MACH_001&torderid=5",
                      "code": "1",
                      "msg": "成功"
                    }
                  },
                  "fail": {
                    "summary": "失败",
                    "value": {
                      "orderid": "CQHW_E2E_20260728_ORDER_10001",
                      "torderid": "",
                      "code": "0",
                      "msg": "设备不存在"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/aizhct/api/PrepayOrder/scan": {
      "get": {
        "tags": [
          "外部接口/三方调用康比特/预扣款订单-咖啡机对接"
        ],
        "x-apifox-folder": "外部接口/三方调用康比特/预扣款订单-咖啡机对接",
        "summary": "小程序扫码入口：预扣款订单转正式订单",
        "description": "用户扫码后调用。接口校验预扣款订单来源与状态，按当前登录用户映射智慧餐厅用户，生成 ydy_meal_order，source=8（咖啡机订单），pay_status=10（待支付），并回写 ydy_prepay_order 的 meal_order_id、meal_order_no、user_id。真实开发容器验证中该路径可访问；短横线别名 /aizhct/api/prepay-order/scan 当前因 ai_api with_route=false 未生效。",
        "operationId": "scanPrepayOrder",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "example": "prepay"
            },
            "description": "二维码类型标识。当前建议传 prepay。"
          },
          {
            "name": "source",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "example": 1
            },
            "description": "预扣款来源。1=咖啡机。"
          },
          {
            "name": "orderid",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "CQHW_E2E_20260728_ORDER_10001"
            },
            "description": "设备订单号。"
          },
          {
            "name": "machid",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "CQHW_E2E_20260728_MACH_001"
            },
            "description": "设备 machid，对应 ydy_equipment.sn。"
          },
          {
            "name": "torderid",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "example": 5
            },
            "description": "智慧餐厅预扣款订单 ID，对应 ydy_prepay_order.id。"
          }
        ],
        "security": [
          {
            "MiniAppToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "扫码创建订单结果。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MiniAppResponse"
                },
                "examples": {
                  "success": {
                    "summary": "成功",
                    "value": {
                      "message": "订单创建成功",
                      "status": 200,
                      "data": {
                        "orderId": 67874,
                        "isPay": 1
                      }
                    }
                  },
                  "missingLogin": {
                    "summary": "未登录",
                    "value": {
                      "message": "缺少必要的参数token, 请先登录",
                      "status": 401,
                      "data": []
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/prepayOrder/payResult": {
      "post": {
        "tags": [
          "外部接口/三方调用康比特/预扣款订单-咖啡机对接"
        ],
        "x-apifox-folder": "外部接口/三方调用康比特/预扣款订单-咖啡机对接",
        "summary": "接口 C：查扣款",
        "description": "咖啡机查询消费者是否已完成支付。系统统一校验设备和签名，并按 orderid、machid、torderid 核对预扣款订单。code=1 表示消费者付款成功，咖啡机才开始制作；code=2 表示等待付款；code=3 表示已过期；code=5 表示交易已完成。",
        "operationId": "queryPrepayOrderPayment",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/PrepayQueryRequest"
              },
              "examples": {
                "queryPaid": {
                  "summary": "查询已支付订单",
                  "value": {
                    "orderid": "CQHW_E2E_20260728_ORDER_10001",
                    "machid": "CQHW_E2E_20260728_MACH_001",
                    "torderid": "5",
                    "timestamp": "1785218919",
                    "randstr": "CQHW_E2E_20260728_RAND_C",
                    "sign": "按签名算法生成"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "扣款查询结果。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrepayStatusResponse"
                },
                "examples": {
                  "paid": {
                    "summary": "消费者付款成功",
                    "value": {
                      "orderid": "CQHW_E2E_20260728_ORDER_10001",
                      "torderid": "5",
                      "code": "1",
                      "msg": "消费者付款成功"
                    }
                  },
                  "waiting": {
                    "summary": "等待付款",
                    "value": {
                      "orderid": "CQHW_E2E_20260728_ORDER_UNSCANNED",
                      "torderid": "7",
                      "code": "2",
                      "msg": "正在等待消费者付款"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/prepayOrder/fulfillResult": {
      "post": {
        "tags": [
          "外部接口/三方调用康比特/预扣款订单-咖啡机对接"
        ],
        "x-apifox-folder": "外部接口/三方调用康比特/预扣款订单-咖啡机对接",
        "summary": "接口 B：报结果",
        "description": "咖啡机出货完成后回传制作/出货结果。status=1 表示出货成功，系统更新 prepay_status=5、ship_status=1；status=0 表示出货失败，记录 errinfo、ship_status=2，预扣款状态保持原值。",
        "operationId": "reportPrepayOrderFulfillment",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/PrepayFulfillRequest"
              },
              "examples": {
                "success": {
                  "summary": "出货成功",
                  "value": {
                    "orderid": "CQHW_E2E_20260728_ORDER_10001",
                    "machid": "CQHW_E2E_20260728_MACH_001",
                    "torderid": "5",
                    "status": "1",
                    "errinfo": "",
                    "timestamp": "1785218920",
                    "randstr": "CQHW_E2E_20260728_RAND_B",
                    "sign": "按签名算法生成"
                  }
                },
                "fail": {
                  "summary": "出货失败",
                  "value": {
                    "orderid": "CQHW_E2E_20260728_ORDER_10001",
                    "machid": "CQHW_E2E_20260728_MACH_001",
                    "torderid": "5",
                    "status": "0",
                    "errinfo": "设备出货失败",
                    "timestamp": "1785218920",
                    "randstr": "CQHW_E2E_20260728_RAND_B",
                    "sign": "按签名算法生成"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "报结果处理结果。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrepayFulfillResponse"
                },
                "examples": {
                  "success": {
                    "summary": "成功",
                    "value": {
                      "orderid": "CQHW_E2E_20260728_ORDER_10001",
                      "torderid": "5",
                      "code": "1",
                      "msg": "成功"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "MiniAppToken": {
        "type": "apiKey",
        "in": "header",
        "name": "Access-Token",
        "description": "小程序登录 token。"
      }
    },
    "schemas": {
      "PrepayCodeRequest": {
        "type": "object",
        "required": [
          "orderid",
          "machid",
          "timestamp",
          "randstr",
          "sign"
        ],
        "properties": {
          "orderid": {
            "type": "string",
            "description": "设备上传订单号。业务上用于幂等判断。",
            "maxLength": 64
          },
          "machid": {
            "type": "string",
            "description": "设备 machid，对应 ydy_equipment.sn。",
            "maxLength": 32
          },
          "trackno": {
            "type": "string",
            "description": "设备货道、轨道或商品编号。",
            "maxLength": 32
          },
          "name": {
            "type": "string",
            "description": "商品名称。",
            "maxLength": 128
          },
          "price": {
            "type": "integer",
            "description": "金额，单位分。",
            "minimum": 0,
            "example": 1200
          },
          "channelid": {
            "type": "string",
            "description": "设备或第三方支付渠道标识。",
            "maxLength": 16
          },
          "timestamp": {
            "type": "string",
            "description": "时间戳，参与签名。"
          },
          "randstr": {
            "type": "string",
            "description": "随机字符串，参与签名。"
          },
          "sign": {
            "type": "string",
            "description": "sha1(sort(appkey,timestamp,randstr) 后拼接)。"
          }
        }
      },
      "PrepayQueryRequest": {
        "type": "object",
        "required": [
          "orderid",
          "machid",
          "timestamp",
          "randstr",
          "sign"
        ],
        "properties": {
          "orderid": {
            "type": "string",
            "description": "设备上传订单号。"
          },
          "machid": {
            "type": "string",
            "description": "设备 machid。"
          },
          "torderid": {
            "type": "string",
            "description": "预扣款订单 ID。建议传入；传入时仍会校验 orderid 与 machid 是否匹配。"
          },
          "timestamp": {
            "type": "string",
            "description": "时间戳，参与签名。"
          },
          "randstr": {
            "type": "string",
            "description": "随机字符串，参与签名。"
          },
          "sign": {
            "type": "string",
            "description": "sha1(sort(appkey,timestamp,randstr) 后拼接)。"
          }
        }
      },
      "PrepayFulfillRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PrepayQueryRequest"
          },
          {
            "type": "object",
            "required": [
              "status"
            ],
            "properties": {
              "status": {
                "type": "integer",
                "description": "出货状态：1=成功，0=失败。",
                "enum": [
                  0,
                  1
                ]
              },
              "errinfo": {
                "type": "string",
                "description": "出货失败原因。",
                "maxLength": 500
              }
            }
          }
        ]
      },
      "PrepayCodeResponse": {
        "type": "object",
        "properties": {
          "orderid": {
            "type": "string",
            "description": "设备上传订单号。"
          },
          "torderid": {
            "type": "string",
            "description": "智慧餐厅预扣款订单 ID。"
          },
          "twocode": {
            "type": "string",
            "description": "返回给设备展示的二维码内容。"
          },
          "code": {
            "type": "string",
            "description": "1=成功，0=失败。"
          },
          "msg": {
            "type": "string",
            "description": "提示信息。"
          }
        }
      },
      "PrepayStatusResponse": {
        "type": "object",
        "properties": {
          "orderid": {
            "type": "string"
          },
          "torderid": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "description": "0=失败，1=消费者付款成功，2=正在等待消费者付款，3=此次交易已过期，4=此次交易已关闭，5=此次交易已完成。",
            "enum": [
              "0",
              "1",
              "2",
              "3",
              "4",
              "5"
            ]
          },
          "msg": {
            "type": "string"
          }
        }
      },
      "PrepayFulfillResponse": {
        "type": "object",
        "properties": {
          "orderid": {
            "type": "string"
          },
          "torderid": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "description": "1=接收成功，0=失败。"
          },
          "msg": {
            "type": "string"
          }
        }
      },
      "MiniAppResponse": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "data": {
            "type": "object",
            "properties": {
              "orderId": {
                "type": "integer",
                "description": "生成或已绑定的 ydy_meal_order.id。"
              },
              "isPay": {
                "type": "integer",
                "description": "1=需要继续支付，0=无需支付或已支付。",
                "enum": [
                  0,
                  1
                ]
              }
            }
          }
        }
      }
    }
  }
}