580 lines
18 KiB
Markdown
580 lines
18 KiB
Markdown
# 账户交易记录查询接口文档
|
||
|
||
## 概述
|
||
|
||
本文档描述了账户交易记录查询相关的三个接口，包括充值记录、消费记录和赠送记录的查询功能。
|
||
|
||
**基础信息：**
|
||
- 基础路径：`/api/account`
|
||
- 请求方式：全部使用 POST
|
||
- 认证要求：所有接口都需要登录认证（@RequireAuth）
|
||
- 响应格式：统一使用 `CommonResult<T>` 包装
|
||
|
||
---
|
||
|
||
## 1. 分页查询充值记录
|
||
|
||
### 接口信息
|
||
|
||
- **接口名称**：分页查询充值记录
|
||
- **接口路径**：`/api/account/getRechargePageList`
|
||
- **请求方式**：POST
|
||
- **接口描述**：查询所有的充值记录（transactionType=1），支持分页和条件筛选，默认根据创建时间倒序排列
|
||
|
||
### 请求参数
|
||
|
||
**Content-Type**: `application/json`
|
||
|
||
**请求体参数（AccountTransactionDto）**：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| pageNum | Integer | 否 | 当前页码，默认1 |
|
||
| pageSize | Integer | 否 | 每页数量，默认10 |
|
||
| sortBy | String | 否 | 排序字段 |
|
||
| sortDesc | Boolean | 否 | 是否降序，默认true |
|
||
| userId | Long | 否 | 用户ID，用于筛选特定用户的充值记录 |
|
||
| status | Integer | 否 | 交易状态：1.成功 2.失败 3.处理中 |
|
||
| transactionNo | String | 否 | 交易单号，精确匹配 |
|
||
| createTimeStart | Date | 否 | 开始时间，格式：yyyy-MM-dd HH:mm:ss |
|
||
| createTimeEnd | Date | 否 | 结束时间，格式：yyyy-MM-dd HH:mm:ss |
|
||
| deleteFlag | Integer | 否 | 删除标记：0.未删除 1.已删除，默认0 |
|
||
|
||
**注意**：此接口固定查询 transactionType=1（充值）的记录
|
||
|
||
### 请求示例
|
||
|
||
```json
|
||
{
|
||
"pageNum": 1,
|
||
"pageSize": 10,
|
||
"userId": 1001,
|
||
"status": 1,
|
||
"createTimeStart": "2025-01-01 00:00:00",
|
||
"createTimeEnd": "2025-12-31 23:59:59"
|
||
}
|
||
```
|
||
|
||
### 响应参数
|
||
|
||
**响应结构**：`CommonResult<PageInfo<AccountTransaction>>`
|
||
|
||
**PageInfo 字段说明**：
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| total | Long | 总记录数 |
|
||
| list | Array | 数据列表 |
|
||
| pageNum | Integer | 当前页码 |
|
||
| pageSize | Integer | 每页数量 |
|
||
| pages | Integer | 总页数 |
|
||
|
||
**AccountTransaction 对象字段**：
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| transactionId | Long | 主键ID |
|
||
| userId | Long | 用户ID |
|
||
| userName | String | 用户名 |
|
||
| transactionType | Integer | 交易类型：1.充值 |
|
||
| amount | BigDecimal | 交易金额（积分） |
|
||
| beforeBalance | BigDecimal | 交易前余额 |
|
||
| afterBalance | BigDecimal | 交易后余额 |
|
||
| status | Integer | 交易状态：1.成功 2.失败 3.处理中 |
|
||
| transactionNo | String | 交易单号 |
|
||
| payType | Integer | 支付方式：1.微信 2.支付宝 3.余额支付 |
|
||
| businessId | Long | 关联业务ID（套餐ID） |
|
||
| businessType | String | 业务类型 |
|
||
| callId | String | 调用ID，关联冻结单 |
|
||
| remark | String | 交易备注 |
|
||
| isExpense | Integer | 是否支出：1.是 0.否 |
|
||
| inputToken | Integer | 输入token |
|
||
| outputToken | Integer | 输出token |
|
||
| totalTokens | Integer | 合计tokens |
|
||
| modelName | String | 处理的模型名称 |
|
||
| question | String | 对应回答的问题或需求 |
|
||
| incomeType | String | 收入类型：recharge(充值)、sign_in(签到奖励) |
|
||
| createTime | String | 创建时间，格式：yyyy-MM-dd HH:mm:ss |
|
||
| updateTime | String | 更新时间，格式：yyyy-MM-dd HH:mm:ss |
|
||
| createBy | String | 创建人 |
|
||
| updateBy | String | 更新人 |
|
||
| deleteFlag | Integer | 是否删除：0.未删除 1.已删除 |
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"total": 50,
|
||
"list": [
|
||
{
|
||
"transactionId": 1001,
|
||
"userId": 1001,
|
||
"userName": "张三",
|
||
"transactionType": 1,
|
||
"amount": 10000.00,
|
||
"beforeBalance": 5000.00,
|
||
"afterBalance": 15000.00,
|
||
"status": 1,
|
||
"transactionNo": "TXN202504150001",
|
||
"payType": 1,
|
||
"businessId": 10,
|
||
"businessType": "package_recharge",
|
||
"callId": null,
|
||
"remark": "购买套餐：基础套餐，获得10000积分",
|
||
"isExpense": 0,
|
||
"inputToken": null,
|
||
"outputToken": null,
|
||
"totalTokens": null,
|
||
"modelName": null,
|
||
"question": null,
|
||
"incomeType": "recharge",
|
||
"createTime": "2025-04-15 10:30:00",
|
||
"updateTime": "2025-04-15 10:30:00",
|
||
"createBy": "system",
|
||
"updateBy": "system",
|
||
"deleteFlag": 0
|
||
}
|
||
],
|
||
"pageNum": 1,
|
||
"pageSize": 10,
|
||
"pages": 5
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 分页查询消费记录（按callId分组）
|
||
|
||
### 接口信息
|
||
|
||
- **接口名称**：分页查询消费记录
|
||
- **接口路径**：`/api/account/getConsumptionGroupedPageList`
|
||
- **请求方式**：POST
|
||
- **接口描述**：查询所有的消费记录，按callId进行分组，每组返回一条汇总记录。对于同一个callId的多条记录：
|
||
- **amount字段**：对该callId下所有记录的amount进行**求和**
|
||
- **inputToken字段**：对该callId下所有记录的inputToken进行**求和**
|
||
- **outputToken字段**：对该callId下所有记录的outputToken进行**求和**
|
||
- **totalTokens字段**：对该callId下所有记录的totalTokens进行**求和**
|
||
- **question字段**：取该callId下最早创建的记录的question
|
||
- 其他字段：取该callId下最早创建的记录的值
|
||
|
||
主要适用于大模型消费场景，可以查看每次对话的总体消费情况。默认根据创建时间倒序排列
|
||
|
||
### 请求参数
|
||
|
||
**Content-Type**: `application/json`
|
||
|
||
**请求体参数（AccountTransactionDto）**：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| pageNum | Integer | 否 | 当前页码，默认1 |
|
||
| pageSize | Integer | 否 | 每页数量，默认10 |
|
||
| sortBy | String | 否 | 排序字段 |
|
||
| sortDesc | Boolean | 否 | 是否降序，默认true |
|
||
| userId | Long | 否 | 用户ID，用于筛选特定用户的消费记录 |
|
||
| status | Integer | 否 | 交易状态：1.成功 2.失败 3.处理中 |
|
||
| createTimeStart | Date | 否 | 开始时间，格式：yyyy-MM-dd HH:mm:ss |
|
||
| createTimeEnd | Date | 否 | 结束时间，格式：yyyy-MM-dd HH:mm:ss |
|
||
| deleteFlag | Integer | 否 | 删除标记：0.未删除 1.已删除，默认0 |
|
||
|
||
**注意**：
|
||
- 此接口固定查询 transactionType IN (3, 7) 的记录（3.购买内容 7.其他）
|
||
- 只查询 callId 不为空的记录
|
||
- 按 callId 分组，每组返回一条记录
|
||
- question 字段取该 callId 下最早创建的记录的 question
|
||
|
||
### 请求示例
|
||
|
||
```json
|
||
{
|
||
"pageNum": 1,
|
||
"pageSize": 10,
|
||
"userId": 1001,
|
||
"status": 1,
|
||
"createTimeStart": "2025-01-01 00:00:00",
|
||
"createTimeEnd": "2025-12-31 23:59:59"
|
||
}
|
||
```
|
||
|
||
### 响应参数
|
||
|
||
**响应结构**：`CommonResult<PageInfo<ConsumptionGroupedDto>>`
|
||
|
||
**PageInfo 字段说明**：
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| total | Long | 总记录数（按callId分组后的数量） |
|
||
| list | Array | 数据列表 |
|
||
| pageNum | Integer | 当前页码 |
|
||
| pageSize | Integer | 每页数量 |
|
||
| pages | Integer | 总页数 |
|
||
|
||
**ConsumptionGroupedDto 对象字段**：
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| transactionId | Long | 主键ID（取该callId下最早的记录ID） |
|
||
| userId | Long | 用户ID |
|
||
| userName | String | 用户名 |
|
||
| transactionType | Integer | 交易类型：3.购买内容 7.其他 |
|
||
| amount | BigDecimal | 交易金额（该callId下所有记录的amount**求和**，通常为负数表示消耗） |
|
||
| beforeBalance | BigDecimal | 交易前余额（取最早记录的值） |
|
||
| afterBalance | BigDecimal | 交易后余额（取最早记录的值） |
|
||
| status | Integer | 交易状态：1.成功 2.失败 3.处理中 |
|
||
| transactionNo | String | 交易单号 |
|
||
| payType | Integer | 支付方式：1.微信 2.支付宝 3.余额支付 |
|
||
| businessId | Long | 关联业务ID |
|
||
| businessType | String | 业务类型 |
|
||
| callId | String | 调用ID，关联冻结单（分组依据） |
|
||
| remark | String | 交易备注 |
|
||
| isExpense | Integer | 是否支出：1.是 0.否 |
|
||
| inputToken | Integer | 输入token（该callId下所有记录的inputToken**求和**） |
|
||
| outputToken | Integer | 输出token（该callId下所有记录的outputToken**求和**） |
|
||
| totalTokens | Integer | 合计tokens（该callId下所有记录的totalTokens**求和**） |
|
||
| modelName | String | 处理的模型名称 |
|
||
| question | String | 对应回答的问题或需求（取该callId下最早入库的question） |
|
||
| incomeType | String | 收入类型 |
|
||
| createTime | String | 创建时间（取该callId下最早的创建时间），格式：yyyy-MM-dd HH:mm:ss |
|
||
| updateTime | String | 更新时间，格式：yyyy-MM-dd HH:mm:ss |
|
||
| createBy | String | 创建人 |
|
||
| updateBy | String | 更新人 |
|
||
| deleteFlag | Integer | 是否删除：0.未删除 1.已删除 |
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"total": 30,
|
||
"list": [
|
||
{
|
||
"transactionId": 2001,
|
||
"userId": 1001,
|
||
"userName": "张三",
|
||
"transactionType": 3,
|
||
"amount": -1500.00,
|
||
"beforeBalance": 15000.00,
|
||
"afterBalance": 13500.00,
|
||
"status": 1,
|
||
"transactionNo": "TXN202504150002",
|
||
"payType": 3,
|
||
"businessId": null,
|
||
"businessType": "ai_model_consumption",
|
||
"callId": "CALL_20250415_001",
|
||
"remark": "AI模型调用消费",
|
||
"isExpense": 1,
|
||
"inputToken": 3000,
|
||
"outputToken": 1500,
|
||
"totalTokens": 4500,
|
||
"modelName": "gpt-4",
|
||
"question": "请帮我分析这段代码的性能问题",
|
||
"incomeType": null,
|
||
"createTime": "2025-04-15 11:00:00",
|
||
"updateTime": "2025-04-15 11:00:00",
|
||
"createBy": "system",
|
||
"updateBy": "system",
|
||
"deleteFlag": 0
|
||
}
|
||
],
|
||
"pageNum": 1,
|
||
"pageSize": 10,
|
||
"pages": 3
|
||
}
|
||
}
|
||
```
|
||
|
||
### 业务说明
|
||
|
||
**为什么需要按callId分组？**
|
||
|
||
在大模型调用场景中，一次用户提问（一个callId）可能会产生多条消费记录：
|
||
1. 首次冻结费用的记录
|
||
2. 实际扣费的记录
|
||
3. 可能的退款或调整记录
|
||
|
||
通过按callId分组并**对金额和token进行求和**，可以将同一次对话的所有相关记录合并展示，便于用户查看：
|
||
- **总消费金额**：该次对话总共消耗了多少积分
|
||
- **总token用量**：该次对话总共使用了多少input/output token
|
||
- **总体消费情况**：一次对话的完整消费概览
|
||
|
||
**聚合字段说明**：
|
||
|
||
以下字段会对同一callId下的所有记录进行**SUM求和**：
|
||
- `amount`：总金额（通常为负数，表示消耗）
|
||
- `inputToken`：总输入token数
|
||
- `outputToken`：总输出token数
|
||
- `totalTokens`：总token数
|
||
|
||
**question字段的取值逻辑**：
|
||
|
||
由于同一个callId可能有多条记录，但question（用户的问题）应该在第一次创建时就确定了，因此取该callId下创建时间最早的记录的question字段。
|
||
|
||
**其他字段的取值逻辑**：
|
||
|
||
除上述聚合字段外，其他字段（如transactionId、beforeBalance、afterBalance等）都取该callId下创建时间最早的记录的值。
|
||
|
||
---
|
||
|
||
## 3. 分页查询赠送记录
|
||
|
||
### 接口信息
|
||
|
||
- **接口名称**：分页查询赠送记录
|
||
- **接口路径**：`/api/account/getGiftPageList`
|
||
- **请求方式**：POST
|
||
- **接口描述**：查询所有的赠送记录（transactionType=6），支持分页和条件筛选，默认根据创建时间倒序排列
|
||
|
||
### 请求参数
|
||
|
||
**Content-Type**: `application/json`
|
||
|
||
**请求体参数（AccountTransactionDto）**：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| pageNum | Integer | 否 | 当前页码，默认1 |
|
||
| pageSize | Integer | 否 | 每页数量，默认10 |
|
||
| sortBy | String | 否 | 排序字段 |
|
||
| sortDesc | Boolean | 否 | 是否降序，默认true |
|
||
| userId | Long | 否 | 用户ID，用于筛选特定用户的赠送记录 |
|
||
| status | Integer | 否 | 交易状态：1.成功 2.失败 3.处理中 |
|
||
| transactionNo | String | 否 | 交易单号，精确匹配 |
|
||
| createTimeStart | Date | 否 | 开始时间，格式：yyyy-MM-dd HH:mm:ss |
|
||
| createTimeEnd | Date | 否 | 结束时间，格式：yyyy-MM-dd HH:mm:ss |
|
||
| deleteFlag | Integer | 否 | 删除标记：0.未删除 1.已删除，默认0 |
|
||
|
||
**注意**：此接口固定查询 transactionType=6（赠送）的记录
|
||
|
||
### 请求示例
|
||
|
||
```json
|
||
{
|
||
"pageNum": 1,
|
||
"pageSize": 10,
|
||
"userId": 1001,
|
||
"status": 1,
|
||
"createTimeStart": "2025-01-01 00:00:00",
|
||
"createTimeEnd": "2025-12-31 23:59:59"
|
||
}
|
||
```
|
||
|
||
### 响应参数
|
||
|
||
**响应结构**：`CommonResult<PageInfo<AccountTransaction>>`
|
||
|
||
**PageInfo 字段说明**：
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| total | Long | 总记录数 |
|
||
| list | Array | 数据列表 |
|
||
| pageNum | Integer | 当前页码 |
|
||
| pageSize | Integer | 每页数量 |
|
||
| pages | Integer | 总页数 |
|
||
|
||
**AccountTransaction 对象字段**：
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| transactionId | Long | 主键ID |
|
||
| userId | Long | 用户ID |
|
||
| userName | String | 用户名 |
|
||
| transactionType | Integer | 交易类型：6.赠送 |
|
||
| amount | BigDecimal | 赠送金额（积分） |
|
||
| beforeBalance | BigDecimal | 赠送前余额 |
|
||
| afterBalance | BigDecimal | 赠送后余额 |
|
||
| status | Integer | 交易状态：1.成功 2.失败 3.处理中 |
|
||
| transactionNo | String | 交易单号 |
|
||
| payType | Integer | 支付方式：通常为null或3 |
|
||
| businessId | Long | 关联业务ID |
|
||
| businessType | String | 业务类型：gift_balance |
|
||
| callId | String | 调用ID，通常为null |
|
||
| remark | String | 赠送备注 |
|
||
| isExpense | Integer | 是否支出：0.否（赠送为收入） |
|
||
| inputToken | Integer | 输入token，通常为null |
|
||
| outputToken | Integer | 输出token，通常为null |
|
||
| totalTokens | Integer | 合计tokens，通常为null |
|
||
| modelName | String | 处理的模型名称，通常为null |
|
||
| question | String | 对应回答的问题或需求，通常为null |
|
||
| incomeType | String | 收入类型，通常为null |
|
||
| createTime | String | 创建时间，格式：yyyy-MM-dd HH:mm:ss |
|
||
| updateTime | String | 更新时间，格式：yyyy-MM-dd HH:mm:ss |
|
||
| createBy | String | 创建人（通常是管理员） |
|
||
| updateBy | String | 更新人 |
|
||
| deleteFlag | Integer | 是否删除：0.未删除 1.已删除 |
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"total": 15,
|
||
"list": [
|
||
{
|
||
"transactionId": 3001,
|
||
"userId": 1001,
|
||
"userName": "张三",
|
||
"transactionType": 6,
|
||
"amount": 5000.00,
|
||
"beforeBalance": 10000.00,
|
||
"afterBalance": 15000.00,
|
||
"status": 1,
|
||
"transactionNo": "GIFT202504150001",
|
||
"payType": null,
|
||
"businessId": null,
|
||
"businessType": "gift_balance",
|
||
"callId": null,
|
||
"remark": "管理员赠送积分",
|
||
"isExpense": 0,
|
||
"inputToken": null,
|
||
"outputToken": null,
|
||
"totalTokens": null,
|
||
"modelName": null,
|
||
"question": null,
|
||
"incomeType": null,
|
||
"createTime": "2025-04-15 14:00:00",
|
||
"updateTime": "2025-04-15 14:00:00",
|
||
"createBy": "admin",
|
||
"updateBy": "admin",
|
||
"deleteFlag": 0
|
||
}
|
||
],
|
||
"pageNum": 1,
|
||
"pageSize": 10,
|
||
"pages": 2
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 通用说明
|
||
|
||
### 交易类型枚举
|
||
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| 1 | 充值 |
|
||
| 2 | 提现 |
|
||
| 3 | 购买内容 |
|
||
| 4 | 退款 |
|
||
| 5 | 签到奖励 |
|
||
| 6 | 赠送 |
|
||
| 7 | 其他 |
|
||
|
||
### 交易状态枚举
|
||
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| 1 | 成功 |
|
||
| 2 | 失败 |
|
||
| 3 | 处理中 |
|
||
|
||
### 支付方式枚举
|
||
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| 1 | 微信支付 |
|
||
| 2 | 支付宝 |
|
||
| 3 | 余额支付 |
|
||
|
||
### 错误码说明
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 成功 |
|
||
| 401 | 未登录或登录已过期 |
|
||
| 403 | 权限不足 |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
### 注意事项
|
||
|
||
1. **认证要求**：所有接口都需要登录后才能访问，请求时需要携带有效的认证token
|
||
2. **分页参数**：如果不传分页参数，默认第1页，每页10条
|
||
3. **时间格式**：所有时间字段统一使用 `yyyy-MM-dd HH:mm:ss` 格式
|
||
4. **排序规则**：所有接口默认按创建时间（create_time）倒序排列，最新的记录在前
|
||
5. **数据权限**：如果传入userId参数，可以查询指定用户的记录；如果不传，则查询所有用户的记录（需要相应权限）
|
||
6. **软删除**：默认只查询未删除的记录（deleteFlag=0）
|
||
|
||
### 前端调用示例
|
||
|
||
```javascript
|
||
// 1. 查询充值记录
|
||
async function getRechargeList(params) {
|
||
const response = await fetch('/api/account/getRechargePageList', {
|
||
method: 'POST',
|
||
headers: {
|
||
'Content-Type': 'application/json',
|
||
'Authorization': 'Bearer ' + token
|
||
},
|
||
body: JSON.stringify({
|
||
pageNum: 1,
|
||
pageSize: 10,
|
||
userId: 1001,
|
||
...params
|
||
})
|
||
});
|
||
return await response.json();
|
||
}
|
||
|
||
// 2. 查询消费记录（按callId分组）
|
||
async function getConsumptionList(params) {
|
||
const response = await fetch('/api/account/getConsumptionGroupedPageList', {
|
||
method: 'POST',
|
||
headers: {
|
||
'Content-Type': 'application/json',
|
||
'Authorization': 'Bearer ' + token
|
||
},
|
||
body: JSON.stringify({
|
||
pageNum: 1,
|
||
pageSize: 10,
|
||
userId: 1001,
|
||
...params
|
||
})
|
||
});
|
||
return await response.json();
|
||
}
|
||
|
||
// 3. 查询赠送记录
|
||
async function getGiftList(params) {
|
||
const response = await fetch('/api/account/getGiftPageList', {
|
||
method: 'POST',
|
||
headers: {
|
||
'Content-Type': 'application/json',
|
||
'Authorization': 'Bearer ' + token
|
||
},
|
||
body: JSON.stringify({
|
||
pageNum: 1,
|
||
pageSize: 10,
|
||
userId: 1001,
|
||
...params
|
||
})
|
||
});
|
||
return await response.json();
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 版本历史
|
||
|
||
| 版本 | 日期 | 作者 | 说明 |
|
||
|------|------|------|------|
|
||
| v1.0 | 2025-04-15 | 王志维 | 初始版本，创建三个查询接口 |
|
||
|
||
---
|
||
|
||
## 联系方式
|
||
|
||
如有问题，请联系开发团队。
|