360 lines
15 KiB
Markdown
360 lines
15 KiB
Markdown
# 充值结算记录 — GetRechargeSettleList
|
||
|
||
> 模块：`Site` · ODS 表：`recharge_settlements` · 事实表（增量）
|
||
|
||
---
|
||
|
||
## 一、接口概述
|
||
|
||
查询门店下会员充值/充值撤销的结算记录。每条记录对应一笔充值订单或充值撤销操作，包含会员信息、充值金额、退款金额、支付方式等。本表复用了通用"结算单"模型，大量消费类字段（商品、台费、助教等）在充值场景下为 0，仅充值相关字段有值。通过 `settleType` 区分充值订单与充值撤销。
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 完整路径 | `POST /Site/GetRechargeSettleList` |
|
||
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
|
||
| 鉴权 | `Authorization: Bearer <token>` |
|
||
| 分页 | `page` + `limit`（最大 100） |
|
||
| 时间范围 | `rangeStartTime` / `rangeEndTime`（必填） |
|
||
|
||
---
|
||
|
||
## 二、请求
|
||
|
||
### 请求体（JSON）
|
||
|
||
```json
|
||
{
|
||
"settleType": 0,
|
||
"paymentMethod": 0,
|
||
"rangeStartTime": "2025-11-01 08:00:00",
|
||
"rangeEndTime": "2025-11-10 08:00:00",
|
||
"siteId": 2790685415443269,
|
||
"isFirst": 0,
|
||
"page": 1,
|
||
"limit": 100
|
||
}
|
||
```
|
||
|
||
### 参数说明
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `settleType` | int | 是 | 结算类型筛选。`0` = 全部 |
|
||
| `paymentMethod` | int | 是 | 支付方式筛选。`0` = 全部 |
|
||
| `rangeStartTime` | string | 是 | 查询起始时间 |
|
||
| `rangeEndTime` | string | 是 | 查询结束时间 |
|
||
| `siteId` | int | 是 | 门店 ID |
|
||
| `isFirst` | int | 是 | 是否首充筛选。`0` = 全部 |
|
||
| `page` | int | 是 | 页码，从 1 开始 |
|
||
| `limit` | int | 是 | 每页条数，最大 100 |
|
||
|
||
---
|
||
|
||
## 三、响应结构
|
||
|
||
```
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"siteProfile": { ... },
|
||
"settleList": { ... }
|
||
}
|
||
],
|
||
"total": 74
|
||
}
|
||
}
|
||
```
|
||
|
||
每个 `list` 元素包含两个顶层对象：`siteProfile`（门店快照）和 `settleList`（充值结算记录本体）。`settleList` 内共 66 个业务字段，加上 `siteProfile` 的 26 个子字段，合计 92 个字段。按逻辑分组说明如下。
|
||
|
||
---
|
||
|
||
## 四、响应字段详解（92 个字段）
|
||
|
||
### 4.1 门店信息快照（siteProfile）
|
||
|
||
`siteProfile` 为门店信息冗余快照，包含 26 个子字段，结构与其他接口（如台费流水、助教流水等）完全一致。所有记录的 `siteProfile` 内容相同。主要字段：
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `siteProfile.id` | int | `2790685415443269` | 门店 ID，与 `settleList.siteId` 一致 |
|
||
| `siteProfile.org_id` | int | `2790684179467077` | 门店所属组织 ID |
|
||
| `siteProfile.shop_name` | string | `"朗朗桌球"` | 门店名称 |
|
||
| `siteProfile.avatar` | string | `"https://oss.ficoo.vip/..."` | 门店头像 URL |
|
||
| `siteProfile.business_tel` | string | `"13316068642"` | 门店电话 |
|
||
| `siteProfile.full_address` | string | `"广东省广州市天河区丽阳街12号"` | 完整地址 |
|
||
| `siteProfile.address` | string | `"广东省广州市天河区天园街道朗朗桌球"` | 精简地址 |
|
||
| `siteProfile.longitude` | float | `113.360321` | 经度 |
|
||
| `siteProfile.latitude` | float | `23.133629` | 纬度 |
|
||
| `siteProfile.tenant_site_region_id` | int | `156440100` | 行政区域编码 |
|
||
| `siteProfile.tenant_id` | int | `2790683160709957` | 租户 ID |
|
||
| `siteProfile.auto_light` | int | `1` | 是否自动控灯 |
|
||
| `siteProfile.attendance_distance` | int | `0` | 考勤打卡范围 |
|
||
| `siteProfile.wifi_name` | string | `""` | WiFi 名称 |
|
||
| `siteProfile.wifi_password` | string | `""` | WiFi 密码 |
|
||
| `siteProfile.customer_service_qrcode` | string | `""` | 客服二维码 |
|
||
| `siteProfile.customer_service_wechat` | string | `""` | 客服微信 |
|
||
| `siteProfile.fixed_pay_qrCode` | string | `""` | 固定收款码 |
|
||
| `siteProfile.prod_env` | int | `1` | 环境标志（`1` = 生产） |
|
||
| `siteProfile.light_status` | int | `1` | 灯控状态 |
|
||
| `siteProfile.light_type` | int | `0` | 灯控类型 |
|
||
| `siteProfile.site_type` | int | `1` | 门店类型 |
|
||
| `siteProfile.light_token` | string | `""` | 灯控对接凭证 |
|
||
| `siteProfile.site_label` | string | `"A"` | 门店标签 |
|
||
| `siteProfile.attendance_enabled` | int | `1` | 是否启用考勤 |
|
||
| `siteProfile.shop_status` | int | `1` | 门店营业状态（`1` = 营业中） |
|
||
|
||
---
|
||
|
||
以下字段均来自 `settleList` 内层对象。
|
||
|
||
### 4.2 主键与关联维度
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `id` | int | `3087072625102533` | 充值结算记录主键 ID |
|
||
| `tenantId` | int | `2790683160709957` | 租户/品牌 ID |
|
||
| `siteId` | int | `2790685415443269` | 门店 ID |
|
||
| `siteName` | string | `""` | 门店名称（当前为空，门店名在 `siteProfile.shop_name` 中） |
|
||
| `settleRelateId` | int | `3087072624987845` | 关联的结算单/业务单 ID，与支付记录的 `relate_id` 呼应，用于跨表追踪 |
|
||
| `tableId` | int | `0` | 台桌 ID。充值场景不依附具体球台，全部为 0 |
|
||
| `serialNumber` | int | `0` | 流水号/小票序号。当前未启用 |
|
||
|
||
### 4.3 结算类型与状态
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `settleType` | int | `5` | 结算类型枚举。`5` = 充值订单（正常充值）；`7` = 充值撤销 |
|
||
| `settleName` | string | `"充值订单"` | 业务类型名称。`"充值订单"` 对应 `settleType = 5`；`"充值撤销"` 对应 `settleType = 7` |
|
||
| `settleStatus` | int | `2` | 结算状态。`2` = 已完成/已结算。当前导出仅包含已完成记录 |
|
||
| `canBeRevoked` | bool | `false` | 是否仍可撤销。当前全部为 `false`（时间窗已过） |
|
||
|
||
### 4.4 会员与会员卡
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `memberId` | int | `2799207363643141` | 会员档案主键 ID，对应会员档案表的 `id` |
|
||
| `memberName` | string | `"葛先生"` | 会员名称/昵称快照（充值时的名字，后续改名不影响本记录） |
|
||
| `memberPhone` | string | `"13811638071"` | 会员手机号快照 |
|
||
| `tenantMemberCardId` | int | `2799216572794629` | 会员卡实例 ID（具体某张卡的主键）。同一张卡可有多条充值记录 |
|
||
| `memberCardTypeName` | string | `"储值卡"` | 会员卡类型名称。已知值：`"储值卡"`（绝大多数）、`"月卡"` |
|
||
| `isBindMember` | bool | `false` | 是否绑定会员。当前全部为 `false`，实际业务含义可能已变化 |
|
||
| `isFirst` | int | `2` | 是否首充标志。`1` = 首充（11 条）；`2` = 非首充（63 条）。具体编码需参考系统字典 |
|
||
|
||
### 4.5 充值金额与退款
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `payAmount` | float | `10000.0` | 充值金额（元/人民币）。正数 = 实际充值额；负数 = 撤销/冲销额（对应 `settleType = 7`） |
|
||
| `pointAmount` | float | `10000.0` | 计入会员账户的储值金额（元）。多数等于 `payAmount` 绝对值；充值撤销记录为 0 |
|
||
| `refundAmount` | float | `0.0` | 针对本条充值订单的退款金额（元）。非 0 时表示该充值已被退款，同时会有对应的 `settleType = 7` 撤销记录 |
|
||
| `consumeMoney` | float | `10000.0` | 总消费/充值金额（元）。在充值场景中与 `payAmount` 一致 |
|
||
|
||
### 4.6 资金来源拆分
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `balanceAmount` | float | `0.0` | 从账户余额支付的金额（元）。充值场景不适用 |
|
||
| `cardAmount` | float | `0.0` | 从储值卡/会员卡余额支付的金额（元）。充值场景不适用 |
|
||
| `cashAmount` | float | `0.0` | 现金收款金额（元）。少数记录有值（如 3000、5000） |
|
||
| `onlineAmount` | float | `0.0` | 线上支付金额（元）。当前未拆分渠道 |
|
||
| `couponAmount` | float | `0.0` | 用券支付的金额（元）。充值场景未使用 |
|
||
| `rechargeCardAmount` | int | `0` | 充值到卡上的金额。当前未单独拆出 |
|
||
| `giftCardAmount` | int | `0` | 赠送卡金额（如买 1000 送 100 的赠送部分）。当前未使用 |
|
||
| `prepayMoney` | float | `0.0` | 预付款/订金金额（元）。充值场景未使用 |
|
||
|
||
### 4.7 消费类金额（充值场景全部为 0）
|
||
|
||
以下字段来自通用结算单模型，在充值场景下不适用，全部为 0.0：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `tableChargeMoney` | float | 台费金额 |
|
||
| `goodsMoney` | float | 商品消费金额 |
|
||
| `realGoodsMoney` | float | 实际商品应计金额 |
|
||
| `serviceMoney` | float | 服务类项目金额 |
|
||
| `assistantPdMoney` | float | 助教配单金额 |
|
||
| `assistantCxMoney` | float | 助教促销/冲销金额 |
|
||
| `electricityMoney` | float | 电费金额 |
|
||
| `realElectricityMoney` | float | 实际电费金额 |
|
||
| `electricityAdjustMoney` | float | 电费调整金额 |
|
||
|
||
### 4.8 优惠与折扣（充值场景全部为 0）
|
||
|
||
以下字段在充值场景下未使用，全部为 0.0 或 `false`：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `activityDiscount` | float | 营销活动折扣金额 |
|
||
| `allCouponDiscount` | float | 各类优惠券综合折扣金额 |
|
||
| `goodsPromotionMoney` | float | 商品促销优惠金额 |
|
||
| `assistantPromotionMoney` | float | 助教促销优惠金额 |
|
||
| `assistantManualDiscount` | float | 助教手动减免金额 |
|
||
| `couponSaleAmount` | float | 出售券/套餐金额 |
|
||
| `plCouponSaleAmount` | float | 平台优惠券销售金额 |
|
||
| `merVouSalesAmount` | float | 商户代金券销售金额 |
|
||
| `memberDiscountAmount` | float | 会员折扣优惠金额 |
|
||
| `pointDiscountPrice` | float | 积分抵扣价差 |
|
||
| `pointDiscountCost` | float | 积分抵扣成本 |
|
||
| `adjustAmount` | float | 手工调整金额 |
|
||
| `roundingAmount` | float | 抹零金额 |
|
||
| `isActivity` | bool | 是否关联营销活动 |
|
||
| `isUseCoupon` | bool | 是否使用优惠券 |
|
||
| `isUseDiscount` | bool | 是否使用折扣 |
|
||
|
||
### 4.9 撤销相关
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `revokeOrderId` | int | `0` | 撤销相关订单 ID。部分记录有值，指向被撤销的原始订单或撤销单 |
|
||
| `revokeOrderName` | string | `""` | 撤销单名称。当前未使用 |
|
||
| `revokeTime` | string | `"0001-01-01 00:00:00"` | 撤销生效时间。`0001-01-01` 为默认无效日期，表示未撤销 |
|
||
|
||
### 4.10 时间字段
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `createTime` | string | `"2026-02-09 05:12:42"` | 充值记录创建时间，一般即收银完成时间 |
|
||
| `payTime` | string | `"2026-02-09 05:12:42"` | 支付完成时间。与 `createTime` 通常非常接近或相同 |
|
||
|
||
### 4.11 操作员与营业员
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `operatorId` | int | `2790687322443013` | 操作该笔充值的收银员/员工 ID |
|
||
| `operatorName` | string | `"收银员:郑丽珊"` | 操作员姓名 |
|
||
| `salesManName` | string | `""` | 营业员/销售员姓名。充值记录未指定销售员 |
|
||
| `salesManUserId` | int | `0` | 营业员用户 ID。当前未使用 |
|
||
| `paymentMethod` | int | `4` | 支付方式枚举。已知值：`1`、`2`、`4`。具体映射需参考系统支付方式配置表 |
|
||
|
||
### 4.12 备注
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `orderRemark` | string | `""` | 充值单备注。当前未使用 |
|
||
|
||
---
|
||
|
||
## 五、响应样例（单条记录，精简版）
|
||
|
||
```json
|
||
{
|
||
"siteProfile": { "id": 2790685415443269, "shop_name": "朗朗桌球", "..." : "..." },
|
||
"settleList": {
|
||
"id": 3087072625102533,
|
||
"tenantId": 2790683160709957,
|
||
"siteId": 2790685415443269,
|
||
"siteName": "",
|
||
"memberId": 2799207363643141,
|
||
"memberName": "葛先生",
|
||
"memberPhone": "13811638071",
|
||
"tenantMemberCardId": 2799216572794629,
|
||
"memberCardTypeName": "储值卡",
|
||
"settleType": 5,
|
||
"settleName": "充值订单",
|
||
"settleStatus": 2,
|
||
"payAmount": 10000.0,
|
||
"pointAmount": 10000.0,
|
||
"refundAmount": 0.0,
|
||
"consumeMoney": 10000.0,
|
||
"paymentMethod": 4,
|
||
"operatorId": 2790687322443013,
|
||
"operatorName": "收银员:郑丽珊",
|
||
"createTime": "2026-02-09 05:12:42",
|
||
"payTime": "2026-02-09 05:12:42",
|
||
"settleRelateId": 3087072624987845,
|
||
"isFirst": 2,
|
||
"canBeRevoked": false,
|
||
"revokeOrderId": 0,
|
||
"revokeOrderName": "",
|
||
"revokeTime": "0001-01-01 00:00:00",
|
||
"balanceAmount": 0.0,
|
||
"cardAmount": 0.0,
|
||
"cashAmount": 0.0,
|
||
"onlineAmount": 0.0,
|
||
"couponAmount": 0.0,
|
||
"roundingAmount": 0.0,
|
||
"adjustAmount": 0.0,
|
||
"tableChargeMoney": 0.0,
|
||
"goodsMoney": 0.0,
|
||
"realGoodsMoney": 0.0,
|
||
"serviceMoney": 0.0,
|
||
"assistantPdMoney": 0.0,
|
||
"assistantCxMoney": 0.0,
|
||
"couponSaleAmount": 0.0,
|
||
"plCouponSaleAmount": 0.0,
|
||
"merVouSalesAmount": 0.0,
|
||
"memberDiscountAmount": 0.0,
|
||
"prepayMoney": 0.0,
|
||
"salesManName": "",
|
||
"salesManUserId": 0,
|
||
"orderRemark": "",
|
||
"pointDiscountPrice": 0.0,
|
||
"pointDiscountCost": 0.0,
|
||
"activityDiscount": 0.0,
|
||
"serialNumber": 0,
|
||
"assistantManualDiscount": 0.0,
|
||
"allCouponDiscount": 0.0,
|
||
"goodsPromotionMoney": 0.0,
|
||
"assistantPromotionMoney": 0.0,
|
||
"isUseCoupon": false,
|
||
"isUseDiscount": false,
|
||
"isActivity": false,
|
||
"isBindMember": false,
|
||
"tableId": 0,
|
||
"rechargeCardAmount": 0,
|
||
"giftCardAmount": 0,
|
||
"electricityMoney": 0.0,
|
||
"realElectricityMoney": 0.0,
|
||
"electricityAdjustMoney": 0.0
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 六、跨表关联
|
||
|
||
### 与会员档案
|
||
|
||
| 本表字段 | 关联表字段 | 说明 |
|
||
|----------|-----------|------|
|
||
| `memberId` | 会员档案 `id`（`tenant_member_id`） | 会员主键 |
|
||
| `memberName` / `memberPhone` | 会员档案对应字段 | 快照值，充值时记录 |
|
||
|
||
### 与会员卡
|
||
|
||
`tenantMemberCardId` 对应会员卡表主键，标识充值到哪张具体的卡。`memberCardTypeName` 给出卡类型（储值卡、月卡等），充值记录同时向"会员主体"和"卡实例"两层维度挂钩。
|
||
|
||
### 与支付记录（`payment_transactions`）
|
||
|
||
| 本表字段 | 关联表字段 | 说明 |
|
||
|----------|-----------|------|
|
||
| `settleRelateId` | `relate_id`（当 `relate_type = 5`） | 充值业务单号 |
|
||
| `paymentMethod` | `payment_method` | 共用支付方式枚举 |
|
||
|
||
> 支付记录中 `relate_type = 5` 的记录对应充值类业务，通过 `settleRelateId` 关联。
|
||
|
||
### 与退款流水（`refund_transactions`）
|
||
|
||
当充值被退款时，退款流水中 `relate_type = 5` 的记录通过 `relate_id` 关联到本表的充值业务。本表通过 `refundAmount > 0` 标记已退款，同时生成 `settleType = 7` 的充值撤销记录。
|
||
|
||
### 与其他结算类接口
|
||
|
||
本表复用通用"结算单"模型，字段结构（`goodsMoney`、`tableChargeMoney`、`serviceMoney`、折扣类字段等）与结账记录（`settlement_records`）完全一致。在同一系统中，台费结算、商品销售、助教结算、充值记录是同一张逻辑表的不同类型切片，通过 `settleType` 区分。
|
||
|
||
### 与门店维度
|
||
|
||
`siteId` 与所有业务表一致。`siteProfile` 为冗余快照。
|
||
|
||
<!--
|
||
AI_CHANGELOG:
|
||
- 日期: 2026-02-13
|
||
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
|
||
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
|
||
- 变更摘要: 新建 docs/api-reference/recharge_settlements.md，按逻辑分组详解所有字段，含跨表关联
|
||
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
|
||
-->
|