{
  "openapi": "3.1.0",
  "info": {
    "title": "大华闸机对接接口（赛迪二期）- 联调回显版",
    "version": "1.1.0",
    "description": "根据 Excel《赛迪二期大华闸机接口20221208.xlsx》整理：sopDhPay（订单生成及支付）。当前后端实现仅在 controller 层做参数接收 + 回显（debug_request），便于导入 Apifox 联调。"
  },
  "servers": [
    {
      "url": "http://localhost:8000",
      "description": "本地（示例）"
    }
  ],
  "paths": {
    "/api/DahuaZhaji/sopDhPay": {
      "post": {
        "summary": "赛迪二期-大华订单生成及支付接口（sopDhPay）",
        "description": "支持 application/json 与表单提交；biz_content 支持字符串 JSON 或对象。联调回显版支持通过 biz_content.orderNo 中包含 FAIL_* 标识模拟失败场景（FAIL_PARAM/FAIL_USER/FAIL_BAL/FAIL_REPEAT/FAIL_TIMEOUT/FAIL_SIGN）。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SopDhPayRequest"
              },
              "examples": {
                "excel_example": {
                  "summary": "按 Excel 示例值（未提供示例的字段使用占位值）",
                  "value": {
                    "app_id": "2014072300007140",
                    "method": "alipay.trade.close",
                    "format": "json",
                    "charset": "utf-8",
                    "sign_type": "RSA2",
                    "sign": "详见示例",
                    "timestamp": "41844.13043981481",
                    "version": "1",
                    "notify_url": "http://open.xxx.com/atinterface/receive_notify.htm",
                    "app_auth_token": "",
                    "biz_content": {
                      "accountCardNum": "1234567890",
                      "authCode": "HHT1101162303435837000001263281",
                      "userAccount": "1234567890",
                      "userAccountType": "1",
                      "cardnum": "",
                      "discountMoney": 11.01,
                      "orderDishList": [
                        { "dishId": 0, "num": 0, "price": 0 }
                      ],
                      "orderMoney": 11.01,
                      "orderNo": "DD3213213123132",
                      "payMoney": 11.01,
                      "payTime": "44286.49363425926",
	                      "snCode": "603413413413143"
	                    }
	                  }
	                },
                "fail_balance": {
                  "summary": "模拟余额不足（orderNo 包含 FAIL_BAL）",
                  "value": {
                    "app_id": "2014072300007140",
                    "method": "alipay.trade.close",
                    "format": "json",
                    "charset": "utf-8",
                    "sign_type": "RSA2",
                    "sign": "详见示例",
                    "timestamp": "41844.13043981481",
                    "version": "1",
                    "notify_url": "http://open.xxx.com/atinterface/receive_notify.htm",
                    "app_auth_token": "",
                    "biz_content": {
                      "userAccount": "1234567890",
                      "userAccountType": "1",
                      "orderMoney": 11.01,
                      "orderNo": "DD3213213123132_FAIL_BAL",
                      "payMoney": 11.01,
                      "payTime": "44286.49363425926",
                      "snCode": "603413413413143",
                      "orderDishList": [
                        { "dishId": 0, "num": 0, "price": 0 }
                      ]
                    }
                  }
                },
                "fail_user": {
                  "summary": "模拟用户未绑定（orderNo 包含 FAIL_USER）",
                  "value": {
                    "app_id": "2014072300007140",
                    "method": "alipay.trade.close",
                    "format": "json",
                    "charset": "utf-8",
                    "sign_type": "RSA2",
                    "sign": "详见示例",
                    "timestamp": "41844.13043981481",
                    "version": "1",
                    "notify_url": "http://open.xxx.com/atinterface/receive_notify.htm",
                    "app_auth_token": "",
                    "biz_content": {
                      "userAccount": "NO_BIND_USER",
                      "userAccountType": "1",
                      "orderMoney": 11.01,
                      "orderNo": "DD3213213123132_FAIL_USER",
                      "payMoney": 11.01,
                      "payTime": "44286.49363425926",
                      "snCode": "603413413413143",
                      "orderDishList": [
                        { "dishId": 0, "num": 0, "price": 0 }
                      ]
                    }
                  }
                }
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/SopDhPayRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "响应包含 Excel 字段（code/msg/sub_code/sub_msg/data.*）以及 debug_request 回显",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SopDhPayResponse"
                },
                "examples": {
                  "controller_mock": {
                    "summary": "Controller 回显响应（示例）",
                    "value": {
                      "code": "0",
                      "msg": "ok",
                      "sub_code": "",
                      "sub_msg": "",
                      "data": {
                        "code": 0,
                        "currentAmount": "111.11",
                        "mealBalance": "111.11",
                        "orderNo": "DD3213213123132",
                        "payMoney": 11.01,
                        "payNo": "HHTPAY3213213123132",
                        "msg": ""
                      },
                      "debug_request": {
                        "app_id": "2014072300007140",
                        "method": "alipay.trade.close",
                        "format": "json",
                        "charset": "utf-8",
                        "sign_type": "RSA2",
                        "sign": "详见示例",
                        "timestamp": "41844.13043981481",
                        "version": "1",
                        "notify_url": "http://open.xxx.com/atinterface/receive_notify.htm",
                        "app_auth_token": "",
                        "biz_content": {
                          "accountCardNum": "1234567890",
                          "authCode": "HHT1101162303435837000001263281",
                          "userAccount": "1234567890",
                          "userAccountType": "1",
                          "cardnum": "",
                          "discountMoney": 11.01,
                          "orderDishList": [
                            { "dishId": 0, "num": 0, "price": 0 }
                          ],
                          "orderMoney": 11.01,
                          "orderNo": "DD3213213123132",
                          "payMoney": 11.01,
                          "payTime": "44286.49363425926",
                          "snCode": "603413413413143"
                        }
	                      },
	                      "debug_case": "SUCCESS"
                    }
                  },
                  "controller_fail_balance": {
                    "summary": "模拟余额不足（FAIL_BAL）",
                    "value": {
                      "code": "40004",
                      "msg": "Business Failed",
                      "sub_code": "BALANCE_NOT_ENOUGH",
                      "sub_msg": "余额不足",
                      "data": {
                        "code": 1,
                        "currentAmount": "0.00",
                        "mealBalance": "0.00",
                        "orderNo": "DD3213213123132_FAIL_BAL",
                        "payMoney": 11.01,
                        "payNo": "",
                        "msg": "余额不足"
                      },
                      "debug_case": "FAIL_BAL"
                    }
                  },
                  "controller_fail_user": {
                    "summary": "模拟用户未绑定（FAIL_USER）",
                    "value": {
                      "code": "40004",
                      "msg": "Business Failed",
                      "sub_code": "USER_NOT_FOUND",
                      "sub_msg": "用户未绑定或不存在",
                      "data": {
                        "code": 1,
                        "currentAmount": "111.11",
                        "mealBalance": "111.11",
                        "orderNo": "DD3213213123132_FAIL_USER",
                        "payMoney": 11.01,
                        "payNo": "",
                        "msg": "用户未绑定或不存在"
                      },
                      "debug_case": "FAIL_USER"
                    }
                  },
                  "controller_fail_param": {
                    "summary": "模拟参数错误（FAIL_PARAM 或必填/3选1不满足）",
                    "value": {
                      "code": "40004",
                      "msg": "Business Failed",
                      "sub_code": "PARAM_INVALID",
                      "sub_msg": "请求参数不符合要求",
                      "data": {
                        "code": 1,
                        "currentAmount": "111.11",
                        "mealBalance": "111.11",
                        "orderNo": "",
                        "payMoney": 0,
                        "payNo": "",
                        "msg": "请求参数不符合要求"
                      },
                      "debug_case": "FAIL_PARAM"
                    }
                  },
                  "controller_fail_repeat": {
                    "summary": "模拟重复请求（FAIL_REPEAT）",
                    "value": {
                      "code": "40004",
                      "msg": "Business Failed",
                      "sub_code": "ORDER_DUPLICATE",
                      "sub_msg": "重复请求",
                      "data": {
                        "code": 1,
                        "currentAmount": "111.11",
                        "mealBalance": "111.11",
                        "orderNo": "DD3213213123132_FAIL_REPEAT",
                        "payMoney": 11.01,
                        "payNo": "",
                        "msg": "重复请求"
                      },
                      "debug_case": "FAIL_REPEAT"
                    }
                  },
                  "controller_fail_timeout": {
                    "summary": "模拟支付超时（FAIL_TIMEOUT）",
                    "value": {
                      "code": "40004",
                      "msg": "Business Failed",
                      "sub_code": "PAY_TIMEOUT",
                      "sub_msg": "支付超时",
                      "data": {
                        "code": 1,
                        "currentAmount": "111.11",
                        "mealBalance": "111.11",
                        "orderNo": "DD3213213123132_FAIL_TIMEOUT",
                        "payMoney": 11.01,
                        "payNo": "",
                        "msg": "支付超时"
                      },
                      "debug_case": "FAIL_TIMEOUT"
                    }
                  },
                  "controller_fail_sign": {
                    "summary": "模拟签名错误（FAIL_SIGN）",
                    "value": {
                      "code": "40004",
                      "msg": "Business Failed",
                      "sub_code": "SIGN_INVALID",
                      "sub_msg": "签名错误",
                      "data": {
                        "code": 1,
                        "currentAmount": "111.11",
                        "mealBalance": "111.11",
                        "orderNo": "DD3213213123132_FAIL_SIGN",
                        "payMoney": 11.01,
                        "payNo": "",
                        "msg": "签名错误"
                      },
                      "debug_case": "FAIL_SIGN"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SopDhPayRequest": {
        "type": "object",
        "properties": {
          "app_id": {
            "type": "string",
            "maxLength": 32,
            "description": "平台分配给开发者的应用ID",
            "example": "2014072300007140"
          },
          "method": {
            "type": "string",
            "maxLength": 128,
            "description": "接口名称",
            "example": "alipay.trade.close"
          },
          "format": {
            "type": "string",
            "maxLength": 40,
            "description": "仅支持JSON",
            "example": "json"
          },
          "charset": {
            "type": "string",
            "maxLength": 10,
            "description": "请求使用的编码格式，如utf-8,gbk,gb2312等",
            "example": "utf-8"
          },
          "sign_type": {
            "type": "string",
            "maxLength": 10,
            "description": "签名算法类型，目前支持RSA2和RSA，推荐使用RSA2",
            "example": "RSA2"
          },
          "sign": {
            "type": "string",
            "maxLength": 344,
            "description": "商户请求参数的签名串",
            "example": "详见示例"
          },
          "timestamp": {
            "type": "string",
            "maxLength": 19,
            "description": "发送请求的时间，格式\"yyyy-MM-dd HH:mm:ss\"（Excel 示例为数值型日期）",
            "example": "41844.13043981481"
          },
          "version": {
            "type": "string",
            "maxLength": 3,
            "description": "调用的接口版本，1.0",
            "example": "1"
          },
          "notify_url": {
            "type": "string",
            "maxLength": 256,
            "description": "平台服务器主动通知商户服务器里指定的页面http/https路径。",
            "example": "http://open.xxx.com/atinterface/receive_notify.htm"
          },
          "app_auth_token": {
            "type": "string",
            "maxLength": 40,
            "description": "应用授权令牌（非必要参数）",
            "example": ""
          },
          "biz_content": {
            "description": "请求参数集合：除公共参数外所有业务请求参数都放在这个参数中。支持 JSON 字符串或对象。",
            "oneOf": [
              { "type": "string" },
              { "$ref": "#/components/schemas/SopDhPayBizContent" }
            ]
          }
        },
        "required": [
          "app_id",
          "method",
          "charset",
          "sign_type",
          "sign",
          "timestamp",
          "version",
          "biz_content"
        ]
      },
      "SopDhPayBizContent": {
        "type": "object",
        "properties": {
          "accountCardNum": {
            "type": "string",
            "description": "用户实体卡卡号（与 authCode/userAccount 3选1）",
            "example": "1234567890"
          },
          "authCode": {
            "type": "string",
            "description": "用户账户支付二维码（与 accountCardNum/userAccount 3选1）",
            "example": "HHT1101162303435837000001263281"
          },
          "userAccount": {
            "type": "string",
            "description": "用户账户（大华闸机人脸识别后传入的员工编号；与 accountCardNum/authCode 3选1）",
            "example": "1234567890"
          },
          "userAccountType": {
            "type": "string",
            "description": "用户账户类型（0-id,1-用户编号，2-手机号，3-邮箱，4-证件号，5-实体卡）；传 userAccount 必须传此值（大华默认传1）",
            "example": "1"
          },
          "cardnum": {
            "type": "string",
            "description": "部门卡账户",
            "example": ""
          },
          "discountMoney": {
            "type": "number",
            "description": "优惠金额",
            "example": 11.01
          },
          "orderDishList": {
            "type": "array",
            "description": "菜品列表",
            "items": { "$ref": "#/components/schemas/SopDhPayDishItem" }
          },
          "orderMoney": {
            "type": "number",
            "description": "订单金额（来源于设备映射的自助餐档口金额）",
            "example": 11.01
          },
          "orderNo": {
            "type": "string",
            "description": "第三方订单编号",
            "example": "DD3213213123132"
          },
          "payMoney": {
            "type": "number",
            "description": "支付金额",
            "example": 11.01
          },
          "payTime": {
            "type": "string",
            "description": "支付时间（Excel 示例为数值型日期）",
            "example": "44286.49363425926"
          },
          "snCode": {
            "type": "string",
            "description": "设备号",
            "example": "603413413413143"
          }
        },
        "required": ["orderNo", "payTime", "snCode"],
        "anyOf": [
          { "required": ["accountCardNum"] },
          { "required": ["authCode"] },
          { "required": ["userAccount", "userAccountType"] }
        ]
      },
      "SopDhPayDishItem": {
        "type": "object",
        "properties": {
          "dishId": {
            "type": "integer",
            "description": "基础菜品id",
            "example": 0
          },
          "num": {
            "type": "integer",
            "description": "数量",
            "example": 0
          },
          "price": {
            "type": "number",
            "description": "价格",
            "example": 0
          }
        },
        "required": ["dishId", "num", "price"]
      },
      "SopDhPayResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "网关返回码（Excel: 公共响应参数）",
            "example": "40004"
          },
          "msg": {
            "type": "string",
            "description": "网关返回码描述（Excel: 公共响应参数）",
            "example": "Business Failed"
          },
          "sub_code": {
            "type": "string",
            "description": "业务返回码（Excel: 公共响应参数）",
            "example": "ACQ.TRADE_HAS_SUCCESS"
          },
          "sub_msg": {
            "type": "string",
            "description": "业务返回码描述（Excel: 公共响应参数）",
            "example": "交易已被支付"
          },
          "data": {
            "type": "object",
            "description": "业务响应数据（Excel: 业务响应参数）",
            "properties": {
              "code": {
                "type": "integer",
                "description": "返回标记：成功标记=0，失败标记=1",
                "example": 0
              },
              "currentAmount": {
                "type": "string",
                "description": "个人账户余额",
                "example": "111.11"
              },
              "mealBalance": {
                "type": "string",
                "description": "餐补余额",
                "example": "111.11"
              },
              "orderNo": {
                "type": "string",
                "description": "订单编号",
                "example": "DD3213213123132"
              },
              "payMoney": {
                "type": "number",
                "description": "实付金额",
                "example": 11.01
              },
              "payNo": {
                "type": "string",
                "description": "支付订单编号",
                "example": "HHTPAY3213213123132"
              },
              "msg": {
                "type": "string",
                "description": "返回信息",
                "example": ""
              }
            }
          },
          "debug_request": {
            "type": "object",
            "description": "联调用：回显收到的请求参数（非 Excel 字段）"
          },
          "debug_case": {
            "type": "string",
            "description": "联调用：当前模拟场景（非 Excel 字段）",
            "example": "SUCCESS"
          }
        },
        "required": ["code", "msg"]
      }
    }
  }
}