{
  "openapi": "3.0.3",
  "info": {
    "title": "中央美术学院 Android 一卡通结算接口 B、C",
    "version": "1.0.0",
    "description": "绑盘机按餐盘查询待结算金额，并在调用新开普一卡通完成扣款后反馈结算结果。"
  },
  "paths": {
    "/api/oneCardTerminal/acquireByPlate": {
      "post": {
        "summary": "接口 B：按餐盘查询待结算金额",
        "description": "# 接口 B：按餐盘查询待结算金额\n\n## 1. 接口概述\n\n学生取餐完成后，将餐盘放到绑盘机。绑盘机调用本接口，根据餐盘码获取唯一待支付订单的结算单号和应扣金额。\n\n本接口仅在系统配置 `meal_model=4` 时可用。\n\n## 2. 接口信息\n\n- **接口地址**：`https://xxx.com/api/oneCardTerminal/acquireByPlate`\n- **请求方法**：POST\n- **Content-Type**：`application/json`\n- **金额单位**：分\n\n## 3. 处理规则\n\n1. 根据当日餐盘码查找未绑定人员的唯一待支付就餐订单。\n2. 首次查询时生成 `CAFA` 开头的一卡通结算单号。\n3. 结算单仍处于待结算状态时，重复查询返回原结算单号，不重复生成。\n4. 上一次扣款失败后再次查询，会为同一个待支付就餐订单生成新的结算单号。\n5. 接口只返回一个订单，不返回订单列表。\n\n## 4. 响应说明\n\n`amount` 为绑盘机应向一卡通系统发起扣款的金额，单位为分。例如 `1234` 表示 `12.34` 元。",
        "parameters": [
          {
            "name": "Access-Token",
            "in": "header",
            "required": false,
            "description": "终端访问令牌",
            "schema": {"type": "string", "default": "{{terminal_token}}"},
            "example": "{{terminal_token}}"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["plate_code", "equipment_code"],
                "properties": {
                  "plate_code": {
                    "type": "string",
                    "description": "餐盘唯一编码",
                    "example": "PLATE-001"
                  },
                  "equipment_code": {
                    "type": "string",
                    "description": "绑盘机设备编号",
                    "example": "BIND-001"
                  }
                }
              },
              "example": {
                "plate_code": "PLATE-001",
                "equipment_code": "BIND-001"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "接口业务响应，必须检查响应体 code",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/AcquireByPlateResponse"},
                "examples": {
                  "success": {
                    "summary": "查询成功",
                    "value": {
                      "code": 0,
                      "message": "success",
                      "data": {
                        "order_no": "CAFA20260824113000A1B2C3",
                        "amount": 1234
                      },
                      "trace_id": "7f21d8"
                    }
                  },
                  "orderNotFound": {
                    "summary": "未找到待支付订单",
                    "value": {
                      "code": 1,
                      "message": "未找到餐盘待支付订单",
                      "data": [],
                      "trace_id": "7f21d8"
                    }
                  },
                  "disabled": {
                    "summary": "未启用安卓餐盘结算模式",
                    "value": {
                      "code": 1,
                      "message": "当前未启用一卡通餐盘结算模式",
                      "data": [],
                      "trace_id": "7f21d8"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/oneCardTerminal/report": {
      "post": {
        "summary": "接口 C：反馈一卡通扣款结果",
        "description": "# 接口 C：反馈一卡通扣款结果\n\n## 1. 接口概述\n\n绑盘机刷卡并调用新开普一卡通系统扣款后，将扣款结果、结算前卡片信息和结算后卡片信息反馈给智慧餐厅。\n\n本接口仅在系统配置 `meal_model=4` 时可用。\n\n## 2. 接口信息\n\n- **接口地址**：`https://xxx.com/api/oneCardTerminal/report`\n- **请求方法**：POST\n- **Content-Type**：`application/json`\n\n## 3. 结算规则\n\n1. `settlement_result.code=0` 表示一卡通扣款成功，非 `0` 表示扣款失败。\n2. 扣款成功时，系统根据 `after_card_info.customerID` 查找已同步人员，绑定就餐订单并完成订单。\n3. 扣款失败时，仅保存反馈信息和失败状态，就餐订单继续保持待支付，可重新查询金额后再次刷卡。\n4. 已成功反馈的订单再次反馈成功时按幂等成功处理；成功订单不能再反馈失败结果。\n5. 不校验结算前后卡片是否属于同一人员。\n6. 不校验一卡通反馈扣款金额是否与订单金额一致。\n\n## 4. 卡片金额字段\n\n卡片信息中的 `ze、ye、subYe` 延续新开普读卡结果，单位为分。订单完成后，系统使用 `after_card_info.ye` 记录结算后余额。\n\n## 5. 注意事项\n\n成功扣款后若接口反馈失败，绑盘机不得自行再次扣款，应携带原 `order_no` 重试反馈，避免一卡通重复扣款。",
        "parameters": [
          {
            "name": "Access-Token",
            "in": "header",
            "required": false,
            "description": "终端访问令牌",
            "schema": {"type": "string", "default": "{{terminal_token}}"},
            "example": "{{terminal_token}}"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["order_no", "settlement_result", "before_card_info", "after_card_info"],
                "properties": {
                  "order_no": {
                    "type": "string",
                    "description": "接口 B 返回的一卡通结算单号",
                    "example": "CAFA20260824113000A1B2C3"
                  },
                  "settlement_result": {"$ref": "#/components/schemas/SettlementResult"},
                  "before_card_info": {
                    "allOf": [{"$ref": "#/components/schemas/CardInfo"}],
                    "description": "一卡通扣款前读卡信息"
                  },
                  "after_card_info": {
                    "allOf": [{"$ref": "#/components/schemas/CardInfo"}],
                    "description": "一卡通扣款后读卡信息；扣款成功时根据其中 customerID 绑定人员"
                  }
                }
              },
              "example": {
                "order_no": "CAFA20260824113000A1B2C3",
                "settlement_result": {
                  "code": 0,
                  "message": "扣款成功",
                  "amount": 1234,
                  "psamID": 166715196755,
                  "psamJyNo": 6,
                  "tac": -2015100023
                },
                "before_card_info": {
                  "uid": -1845026871,
                  "cardClass": 8,
                  "customerID": 29373,
                  "cardNO": 1705827,
                  "cardSN": 2,
                  "status": 241,
                  "subType": 0,
                  "ze": 66464,
                  "ye": 2000,
                  "opCount": 38,
                  "subYe": 0,
                  "subCount": 0,
                  "cardASN": "AA030000026D60992AB9"
                },
                "after_card_info": {
                  "uid": -1845026871,
                  "cardClass": 8,
                  "customerID": 29373,
                  "cardNO": 1705827,
                  "cardSN": 2,
                  "status": 241,
                  "subType": 0,
                  "ze": 66464,
                  "ye": 766,
                  "opCount": 39,
                  "subYe": 0,
                  "subCount": 0,
                  "cardASN": "AA030000026D60992AB9"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "接口业务响应，必须检查响应体 code",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/CommonEmptyResponse"},
                "examples": {
                  "success": {
                    "summary": "反馈成功",
                    "value": {"code": 0, "message": "success", "data": [], "trace_id": "7f21d8"}
                  },
                  "orderNotFound": {
                    "summary": "结算单不存在",
                    "value": {"code": 1, "message": "结算订单不存在", "data": [], "trace_id": "7f21d8"}
                  },
                  "personNotSynced": {
                    "summary": "结算后卡片人员未同步",
                    "value": {"code": 1, "message": "人员信息未同步", "data": [], "trace_id": "7f21d8"}
                  },
                  "invalidResult": {
                    "summary": "扣款结果格式错误",
                    "value": {"code": 1, "message": "settlement_result.code格式无效", "data": [], "trace_id": "7f21d8"}
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AcquireByPlateResponse": {
        "type": "object",
        "required": ["code", "message", "data", "trace_id"],
        "properties": {
          "code": {"type": "integer", "description": "0成功，1失败", "example": 0},
          "message": {"type": "string", "example": "success"},
          "data": {
            "type": "object",
            "required": ["order_no", "amount"],
            "properties": {
              "order_no": {"type": "string", "description": "一卡通结算单号", "example": "CAFA20260824113000A1B2C3"},
              "amount": {"type": "integer", "description": "应扣金额，单位分", "example": 1234}
            }
          },
          "trace_id": {"type": "string", "description": "请求链路标识", "example": "7f21d8"}
        }
      },
      "SettlementResult": {
        "type": "object",
        "required": ["code"],
        "description": "新开普一卡通扣款返回值；除 code 外允许透传一卡通返回的其他字段",
        "properties": {
          "code": {"type": "integer", "description": "扣款结果：0成功，非0失败", "example": 0},
          "message": {"type": "string", "description": "一卡通扣款结果说明", "example": "扣款成功"},
          "amount": {"type": "integer", "description": "一卡通反馈的实际扣款金额，单位分；仅记录，不校验订单金额", "example": 1234},
          "psamID": {"type": "integer", "description": "一卡通 PSAM 标识", "example": 166715196755},
          "psamJyNo": {"type": "integer", "description": "一卡通 PSAM 交易流水号", "example": 6},
          "tac": {"type": "integer", "description": "一卡通交易认证码", "example": -2015100023}
        },
        "additionalProperties": true
      },
      "CardInfo": {
        "type": "object",
        "required": ["uid", "cardClass", "customerID", "cardNO", "cardSN", "status", "subType", "ze", "ye", "opCount", "subYe", "subCount", "cardASN"],
        "properties": {
          "uid": {"type": "integer", "description": "卡片 UID，有符号32位整数", "example": -1845026871},
          "cardClass": {"type": "integer", "description": "卡类别", "example": 8},
          "customerID": {"type": "integer", "description": "一卡通人员账号；成功结算时使用结算后值绑定人员", "example": 29373},
          "cardNO": {"type": "integer", "description": "一卡通卡号", "example": 1705827},
          "cardSN": {"type": "integer", "description": "个人持卡序号", "example": 2},
          "status": {"type": "integer", "description": "一卡通卡片状态", "example": 241},
          "subType": {"type": "integer", "description": "补助类型", "example": 0},
          "ze": {"type": "integer", "description": "卡片累计金额，单位分", "example": 66464},
          "ye": {"type": "integer", "description": "卡余额，单位分", "example": 766},
          "opCount": {"type": "integer", "description": "卡片操作计数", "example": 38},
          "subYe": {"type": "integer", "description": "补助余额，单位分", "example": 0},
          "subCount": {"type": "integer", "description": "补助计数", "example": 0},
          "cardASN": {"type": "string", "description": "卡片应用序列号", "example": "AA030000026D60992AB9"}
        }
      },
      "CommonEmptyResponse": {
        "type": "object",
        "required": ["code", "message", "data", "trace_id"],
        "properties": {
          "code": {"type": "integer", "description": "0成功，1失败", "example": 0},
          "message": {"type": "string", "example": "success"},
          "data": {"type": "array", "maxItems": 0, "example": []},
          "trace_id": {"type": "string", "description": "请求链路标识", "example": "7f21d8"}
        }
      }
    }
  }
}