skills/agent-skill-backend
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
394459e7c4
agent-skill-backend/账户交易记录查询接口文档.md

18 KiB
Raw Blame History

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

概述

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

基础信息：

  • 基础路径：/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（充值）的记录

请求示例

{
  "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.已删除

响应示例

{
  "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

请求示例

{
  "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.已删除

响应示例

{
  "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（赠送）的记录

请求示例

{
  "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.已删除

响应示例

{
  "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）

前端调用示例

// 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 王志维 初始版本，创建三个查询接口

联系方式

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