# 账户交易记录查询接口文档

## 概述

本文档描述了账户交易记录查询相关的三个接口，包括充值记录、消费记录和赠送记录的查询功能。

**基础信息：**
- 基础路径：`/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 | 王志维 | 初始版本，创建三个查询接口 |

---

## 联系方式

如有问题，请联系开发团队。