发布时间: 阅读量

使用cursor生成接口文档

1.第一次提问
WechatIMG1033.jpg
给的答案比较草率
2.第二次完善提问
WechatIMG1034.jpg
这次答案就比较详细
WechatIMG1035.jpg

总结:1.需要不断完善提问话术,让AI能够更清楚的了解你的需求
2.代码结构标准,方法注释,实体类注释都必须明确(入参,出参必须实体封装,这也是面向对象的思想,有些人为了省事喜欢用map封装,这样就AI就无法知道字段的含义,从而无法生成具体的内容)

PayController 接口文档

目录

1. 支付接口

接口地址/pay/orderPay
请求方式:POST
接口描述:用于处理支付请求

请求参数

请求体(PayDTO)

{
  "orderId": "ORDER123456",      // 订单id,不能为空
  "qrCode": "QRCODE12345",       // 支付二维码,不能为空
  "posNum": "POS123456",         // pos机设备编码,不能为空
  "amount": 100.50               // 支付金额,必须大于0
}
参数名 类型 是否必填 说明
orderId String 订单id
qrCode String 支付二维码
posNum String pos机设备编码
amount BigDecimal 支付金额(必须大于0)

返回参数

{
  "code": 200,                   // 状态码:200成功
  "msg": "操作成功",              // 返回信息
  "data": {
    // 支付相关的返回信息,具体内容根据实际业务返回
  }
}

2. 退款接口

接口地址/pay/refundOrder
请求方式:POST
接口描述:处理退款请求

请求参数

请求体(RefundOrderReqDTO)

{
  "outTradeNo": "ORDER123456",       // 订单号,不能为空
  "outRefundNo": "REFUND123456",     // 退款单号
  "totalFee": 10000,                 // 订单金额(单位:分)
  "refundFee": 10000,                // 退款金额(单位:分)
  "opUserId": "USER001",             // 操作人
  "matchData": "匹配数据"             // 匹配字符串
}
参数名 类型 是否必填 说明
outTradeNo String 订单号
outRefundNo String 退款单号
totalFee Integer 订单金额(单位:分)
refundFee Integer 退款金额(单位:分)
opUserId String 操作人
matchData String 匹配字符串

返回参数

{
  "code": 200,                   // 状态码:200成功
  "msg": "操作成功",              // 返回信息
  "data": null                   // 无返回数据
}

3. 支付订单轮询接口

接口地址/pay/orderPoll
请求方式:GET
接口描述:轮询查询支付订单状态

请求参数

参数名 类型 是否必填 说明
orderNum String 订单号

返回参数

{
  "code": 200,                   // 状态码:200成功
  "msg": "操作成功",              // 返回信息
  "data": {
    "status": 1,                 // 状态:1-支付中,2-支付成功,3-支付失败
    "printData": {               // 仅支付成功时返回打印数据
      "MerchantName": "内蒙古电力集团有限责任公司",  // 商户名称
      "MerchantNo": "123456",                    // 商户号
      "posNum": "POS123456",                     // 终端编号
      "payAmount": "100.50",                     // 交易金额
      "payType": "微信支付",                       // 交易方式
      "payTime": "2024-03-15 12:30:45",         // 交易时间
      "orderNum": "ORDER123456",                // 商户订单号
      "holderNum": "100001",                    // 户号
      "holderName": "张三",                       // 户名
      "address": "北京市海淀区中关村",              // 地址
      "etcType": "居民生活用电",                   // 用电类型
      "totalRcvblAmt": "100.00",                // 合计电费
      "totalPenalty": "0.50",                   // 应收违约金
      "totalAvailBal": "0.00",                  // 账户余额
      "rcvblAmtSum": "100.50"                   // 应收合计
    },
    "orderNum": "ORDER123456"    // 仅支付成功时返回订单号
  }
}

4. 获取打印小票相关数据

接口地址/pay/getReceiptInfo
请求方式:GET
接口描述:获取打印小票的相关数据

请求参数

参数名 类型 是否必填 说明
orderNum String 订单号

返回参数

{
  "code": 200,                   // 状态码:200成功
  "msg": "操作成功",              // 返回信息
  "data": {
    "MerchantName": "内蒙古电力集团有限责任公司",  // 商户名称
    "MerchantNo": "123456",                    // 商户号
    "posNum": "POS123456",                     // 终端编号
    "payAmount": "100.50",                     // 交易金额
    "payType": "微信支付",                       // 交易方式
    "payTime": "2024-03-15 12:30:45",         // 交易时间
    "orderNum": "ORDER123456",                // 商户订单号
    "holderNum": "100001",                    // 户号
    "holderName": "张三",                       // 户名
    "address": "北京市海淀区中关村",              // 地址
    "etcType": "居民生活用电",                   // 用电类型
    "totalRcvblAmt": "100.00",                // 合计电费
    "totalPenalty": "0.50",                   // 应收违约金
    "totalAvailBal": "0.00",                  // 账户余额
    "rcvblAmtSum": "100.50"                   // 应收合计
  }
}

5. 插入流水记录

接口地址/pay/insertFlow
请求方式:GET
接口描述:插入支付流水记录

请求参数

返回参数

{
  "code": 200,                   // 状态码:200成功
  "msg": "操作成功",              // 返回信息
  "data": null                   // 无返回数据
}

6. 发送支付资金流水

接口地址/pay/sendPayCapitalFlow
请求方式:GET
接口描述:发送支付资金流水

请求参数

返回参数

{
  "code": 200,                   // 状态码:200成功
  "msg": "操作成功",              // 返回信息
  "data": null                   // 无返回数据
}

7. 插入历史流水记录

接口地址/pay/insertHistoryFlow
请求方式:GET
接口描述:插入历史流水记录

请求参数

参数名 类型 是否必填 说明
startTime String 开始时间
endTime String 结束时间

返回参数

{
  "code": 200,                   // 状态码:200成功
  "msg": "操作成功",              // 返回信息
  "data": null                   // 无返回数据
}

8. 演示接口

接口地址/pay/demo
请求方式:GET
接口描述:获取流水的演示接口

请求参数

返回参数

{
  "code": 200,                   // 状态码:200成功
  "msg": "操作成功",              // 返回信息
  "data": null                   // 无返回数据
}

数据结构说明

PayDTO - 支付请求对象

字段名 类型 是否必填 说明
orderId String 订单id
qrCode String 支付二维码
posNum String pos机设备编码
amount BigDecimal 支付金额(必须大于0)

RefundOrderReqDTO - 退款请求对象

字段名 类型 是否必填 说明
outTradeNo String 订单号
outRefundNo String 退款单号
totalFee Integer 订单金额(单位:分)
refundFee Integer 退款金额(单位:分)
opUserId String 操作人
matchData String 匹配字符串

ReceiptVO - 小票打印数据对象

字段名 类型 说明
MerchantName String 商户名称,默认为"内蒙古电力集团有限责任公司"
MerchantNo String 商户号
posNum String 终端编号
payAmount String 交易金额
payType String 交易方式
payTime String 交易时间
orderNum String 商户订单号
holderNum String 户号
holderName String 户名
address String 地址
etcType String 用电类型
totalRcvblAmt String 合计电费
totalPenalty String 应收违约金
totalAvailBal String 账户余额
rcvblAmtSum String 应收合计

错误码说明

错误码 说明
200 操作成功
201 对象创建成功
202 请求已被接受
204 操作已执行成功,但没有返回数据
400 参数列表错误(缺少,格式不匹配)
401 未授权
403 访问受限,授权过期
404 资源,服务未找到
405 不允许的http方法
409 资源冲突,或资源被锁
415 不支持的数据,媒体类型
500 系统内部错误
501 接口未实现
601 系统警告消息