使用cursor生成接口文档
1.第一次提问
给的答案比较草率
2.第二次完善提问
这次答案就比较详细
总结：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 | 系统警告消息 |
