root/ZQYY.FQ-ETL
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
ZQYY.FQ-ETL/docs/api-reference/recharge_settlements.md

15 KiB
Raw Permalink Blame History

充值结算记录 — 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）

{
  "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 "" 充值单备注。当前未使用

五、响应样例（单条记录，精简版）

{
  "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 为冗余快照。

Reference in New Issue View Git Blame Copy Permalink