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

19 KiB
Raw Permalink Blame History

结账记录 — GetAllOrderSettleList

模块：Site · ODS 表：settlement_records · 事实表（增量）

一、接口概述

查询门店在指定时间范围内的所有结账记录。每条记录代表一次完整的结账行为（整单维度），是台费流水、助教流水、商品销售、小票详情等多张明细表的"汇总头表"。

该接口是整个 ETL 系统中最核心的事实表数据源之一，承载了消费构成（台费/商品/助教/服务）和支付渠道（现金/线上/储值卡/礼品卡/积分等）两个维度的完整拆分。

属性 值
完整路径 POST /Site/GetAllOrderSettleList
Base URL https://pc.ficoo.vip/apiprod/admin/v1/
鉴权 Authorization: Bearer <token>
分页 page + limit（最大 100）。注意：拒绝 pageSize/pageNo，否则返回 HTTP 1400
时间范围 必须（rangeStartTime / rangeEndTime）

响应结构特殊性

与大多数接口的 data.list[] 不同，本接口的响应结构为嵌套形式：

{
  "code": 200,
  "data": {
    "total": 4739,
    "settleList": [
      {
        "siteProfile": { ... },     ← 门店维度快照（当前为空壳）
        "settleList": { ... }        ← 真正的结账明细对象
      }
    ]
  }
}

外层 data.settleList 是数组，每个元素包含 siteProfile（门店快照）和内层 settleList（结账明细对象）两部分。ETL 抽取时需注意这一嵌套结构。

二、请求

请求体（JSON）

{
  "settleType": 0,
  "rangeStartTime": "2026-02-01 08:00:00",
  "rangeEndTime": "2026-02-13 08:00:00",
  "siteId": 2790685415443269,
  "siteTableAreaIdList": [],
  "page": 1,
  "limit": 100
}

参数说明

参数 类型 必填 说明
settleType int 是 结算类型筛选。0 = 全部，1 = 正常结账，3 = 特殊类型（挂账/补单/调整单）
rangeStartTime string 是 查询起始时间，格式 YYYY-MM-DD HH:MM:SS
rangeEndTime string 是 查询结束时间，格式 YYYY-MM-DD HH:MM:SS
siteId int 是 门店 ID
siteTableAreaIdList array 否 台桌区域 ID 列表，空数组 [] 表示全部区域
page int 是 页码，从 1 开始
limit int 是 每页条数，最大 100。禁止使用 pageSize/pageNo

三、响应结构

{
  "code": 200,
  "data": {
    "total": 4739,
    "settleList": [
      {
        "siteProfile": { ... },
        "settleList": { ... }
      }
    ]
  }
}

每个 data.settleList[] 元素由两部分组成：

  • siteProfile（26 个字段）：门店维度快照，当前接口中为空壳（值均为 0 或空字符串）
  • settleList（66 个字段）：真正的结账明细对象，所有业务字段在此

合计 92 个字段，按逻辑分组说明如下。

四、响应字段详解

A. siteProfile — 门店维度快照（26 个字段）

当前接口中 siteProfile 几乎为空壳（id=0、shop_name=""），真正的门店信息在内层 settleList 的 siteId / siteName 字段中。该结构与其他接口（如支付流水、退款流水）中的 siteProfile 完全一致。

字段 类型 示例 说明
id int 0 门店 ID（当前为 0，未填充）
org_id int 0 组织 ID
shop_name string "" 门店名称（当前为空）
avatar string "" 门店头像 URL
business_tel string "" 门店电话
full_address string "" 门店详细地址
address string "" 门店简要地址
longitude float 0.0 经度
latitude float 0.0 纬度
tenant_site_region_id int 0 地区编码
tenant_id int 0 租户 ID
auto_light int 1 自动灯控开关
attendance_distance int 0 考勤打卡距离（米）
wifi_name string "" WiFi 名称
wifi_password string "" WiFi 密码
customer_service_qrcode string "" 客服二维码 URL
customer_service_wechat string "" 客服微信号
fixed_pay_qrCode string "" 固定收款码 URL
prod_env int 1 环境标记：1 = 生产环境
light_status int 1 灯控状态
light_type int 0 灯控类型
site_type int 1 门店类型枚举
light_token string "" 灯控设备 Token
site_label string "" 门店标签
attendance_enabled int 1 考勤功能开关：1 = 启用
shop_status int 1 门店状态：1 = 正常营业

B. settleList — 结账明细对象（66 个字段）

4.1 主键与关联 ID / 桌台信息

字段 类型 示例 说明
id int 3092711340902597 结账记录主键 ID（订单结算 ID）。全系统统一的"结账单号"，是多张明细表的汇总头
tenantId int 2790683160709957 租户/商户 ID（品牌维度），全表固定
siteId int 2790685415443269 门店 ID。与所有业务表的 site_id 对应
siteName string "朗朗桌球" 门店名称，冗余展示字段
tableId int 2956248279567557 本次结账对应的桌台 ID。对应台桌维表的 id 和台费流水的 site_table_id
settleName string "发财 发财" 结账对象名称，一般为"区域 + 桌号"组合（如 "A区 A17"）。与台费流水中的 site_table_area_name + ledger_name 一致
settleRelateId int 3092230766020741 关联订单的交易号（order_trade_no）。将结账记录与台费流水、助教流水、商品明细等逻辑串联的核心外键
serialNumber int 0 结账序列号/打印序号，用于内部排序或冲正追踪。当前样本均为 0

4.2 时间与状态

字段 类型 示例 说明
createTime string "2026-02-13 04:48:42" 结账记录创建时间，对应收银端"确认结账"的时刻
payTime string "2026-02-13 04:49:48" 实际支付完成时间，通常晚于 createTime（多支付场景）
settleStatus int 2 结账状态枚举：2 = 已结算/已完成。其他可能值：待支付、已撤销（当前样本未出现）
settleType int 1 结账类型枚举：1 = 正常结账，3 = 特殊类型（挂账/补单/调整单）
paymentMethod int 0 支付方式标识（新增字段），0 = 默认/未指定
canBeRevoked bool false 是否允许撤销/冲正。true = 可撤销，false = 不可撤销（已过时限或已冲正）
revokeOrderId int 0 撤销关联单 ID。若当前记录被撤销，记录对应的撤销单 ID；0 = 无撤销
revokeOrderName string "" 撤销单名称/标识
revokeTime string "0001-01-01 00:00:00" 撤销时间。0001-01-01 为无效占位，表示未发生撤销

4.3 会员维度

字段 类型 示例 说明
memberId int 2799207522600709 会员主键 ID。与会员卡表的 tenant_member_id 一致。0 = 散客
memberName string "" 会员姓名快照（当前接口未填充）
memberPhone string "" 会员手机号快照（当前接口未填充）
tenantMemberCardId int 0 会员卡账户 ID，预留"结账记录 → 会员卡账户表"的外键（当前未使用）
memberCardTypeName string "" 会员卡类型名称，如"储值卡""次卡"等。对应会员卡表的 member_card_type_name
isBindMember bool false 本次结账是否绑定会员。true = 会员单（memberId > 0），false = 散客
isFirst int 0 是否首单（新客首单）：0 = 否，1 = 是
memberDiscountAmount float 0.0 会员折扣产生的优惠金额（元）

4.4 消费构成（台费 / 商品 / 助教 / 服务 / 电费）

这些字段从"消费侧"拆解每笔结账的项目构成，不涉及付款方式。

金额关系（近似）：consumeMoney ≈ tableChargeMoney + goodsMoney + assistantPdMoney + assistantCxMoney + serviceMoney + electricityMoney ± 调价/抹零

字段 类型 示例 说明
consumeMoney float 5567.77 本次结账消费总额（所有项目金额汇总，不区分支付方式/优惠）
tableChargeMoney float 2564.45 台费金额（桌台计费部分）
goodsMoney float 2357.0 商品销售金额（原始金额）
realGoodsMoney float 2357.0 商品实际计入金额（扣除折扣/促销后）。通常 realGoodsMoney ≤ goodsMoney
assistantPdMoney float 646.32 助教"排钟/上课"应计金额（原价）。与助教流水的 ledger_amount 汇总对齐
assistantCxMoney float 0.0 助教"次课/套餐/持续课"金额。与 assistantPdMoney 一起将助教项目区分为不同计费类型
serviceMoney float 0.0 服务费/其他服务类收费金额，区分于台费、商品、助教之外的服务收入
electricityMoney float 0.0 电费金额（新增字段）。灯控/电力计费场景
realElectricityMoney float 0.0 电费实际计入金额（新增字段）。扣除调整后的电费
electricityAdjustMoney float 0.0 电费调整金额（新增字段）。电费维度的人工调价

4.5 支付与资金构成（按渠道拆分）

这些字段描述"钱从哪来/怎么付"的分配，是支付渠道维度，不是消费项目构成。

字段 类型 示例 说明
payAmount float 0.0 本次结账实付金额（顾客实际支付总额），不含券面值、积分等非现金部分
cashAmount float 0.0 现金支付金额
cardAmount float 0.0 刷卡支付金额（信用卡/银行卡），也可能是会员卡支付的一种编码
balanceAmount float 4285.55 会员余额账户扣除金额（储值卡余额消费）
onlineAmount float 0.0 线上支付金额汇总（微信/支付宝/云闪付等通道总和），不细分通道
rechargeCardAmount float 4285.55 充值卡抵扣金额。与 balanceAmount 可能存在重叠（视系统配置）
giftCardAmount int/float 0 礼品卡/代金卡支付金额
refundAmount float 0.0 本次结账涉及的退款金额（退款单或部分退单时为正数）
prepayMoney float 0.0 预付金（定金）部分金额，记录提前预付在本单中使用的金额

4.6 优惠 / 折扣 / 活动金额

系统在优惠维度上做了非常细的拆分，按来源区分：会员折扣、活动折扣、商品促销、助教促销、券优惠、积分优惠、人工调价、抹零。每个维度对应独立的金额字段。

字段 类型 示例 说明
couponAmount float 0.0 优惠券（代金券/团购券等）实际抵扣金额
couponSaleAmount float 0.0 优惠券本身的售卖金额/成本金额（顾客为购券支付的金额）
plCouponSaleAmount float 0.0 平台券售卖金额（新增字段）。区分于商户自有券
merVouSalesAmount float 0.0 商户代金券售卖金额（新增字段）
allCouponDiscount float 0.0 所有券类优惠折扣的汇总金额
goodsPromotionMoney float 0.0 商品促销优惠金额（买赠、满减分摊到商品部分）
assistantPromotionMoney float 0.0 助教项目促销优惠金额
activityDiscount float 0.0 活动折扣金额（整单打折、满减等归集）
adjustAmount float 1282.22 人工调价金额（总和），包括整单减免、特殊调整。值较大时说明存在明显的人工改价
assistantManualDiscount float 0.0 助教服务专项人工减免金额（区别于普通商品/台费折扣）
roundingAmount float 0.0 抹零金额/舍入差值（四舍五入或按角、分抹零产生的调整）

4.7 积分相关

字段 类型 示例 说明
pointAmount float 0.0 积分相关金额/数量。可能表示本单获得的积分数量，或用积分抵扣的金额（视系统配置）
pointDiscountPrice float 0.0 积分抵扣对应的金额（售价侧）
pointDiscountCost float 0.0 积分抵扣对应的成本金额（成本侧）

4.8 布尔标志位（优惠/活动使用情况）

字段 类型 示例 说明
isUseCoupon bool false 本次结账是否使用了优惠券
isUseDiscount bool false 是否使用了折扣（会员折扣、整单打折等）
isActivity bool false 是否参与了营销活动（活动价、满减等）

isBindMember 和 isFirst 见 4.3 会员维度。

4.9 员工 / 操作相关

字段 类型 示例 说明
operatorId int 2790687322443013 结账操作员的用户 ID，可与员工/账号表关联
operatorName string "收银员:郑丽珊" 操作员名称，包含角色前缀（如 "收银员:"）
salesManName string "" 营业员/业务员名称（用于提成或业绩归属），当前未设置
salesManUserId int 0 营业员用户 ID
orderRemark string "" 订单备注，收银员手工输入的特殊说明

五、响应样例（单条记录）

{
  "siteProfile": {
    "id": 0,
    "org_id": 0,
    "shop_name": "",
    "avatar": "",
    "business_tel": "",
    "full_address": "",
    "address": "",
    "longitude": 0.0,
    "latitude": 0.0,
    "tenant_site_region_id": 0,
    "tenant_id": 0,
    "auto_light": 1,
    "attendance_distance": 0,
    "wifi_name": "",
    "wifi_password": "",
    "customer_service_qrcode": "",
    "customer_service_wechat": "",
    "fixed_pay_qrCode": "",
    "prod_env": 1,
    "light_status": 1,
    "light_type": 0,
    "site_type": 1,
    "light_token": "",
    "site_label": "",
    "attendance_enabled": 1,
    "shop_status": 1
  },
  "settleList": {
    "id": 3092711340902597,
    "tenantId": 2790683160709957,
    "siteId": 2790685415443269,
    "siteName": "朗朗桌球",
    "balanceAmount": 4285.55,
    "cardAmount": 0.0,
    "cashAmount": 0.0,
    "couponAmount": 0.0,
    "createTime": "2026-02-13 04:48:42",
    "memberId": 2799207522600709,
    "memberName": "",
    "tenantMemberCardId": 0,
    "memberCardTypeName": "",
    "memberPhone": "",
    "tableId": 2956248279567557,
    "consumeMoney": 5567.77,
    "onlineAmount": 0.0,
    "operatorId": 2790687322443013,
    "operatorName": "收银员:郑丽珊",
    "revokeOrderId": 0,
    "revokeOrderName": "",
    "revokeTime": "0001-01-01 00:00:00",
    "payAmount": 0.0,
    "pointAmount": 0.0,
    "refundAmount": 0.0,
    "settleName": "发财 发财",
    "settleRelateId": 3092230766020741,
    "settleStatus": 2,
    "settleType": 1,
    "payTime": "2026-02-13 04:49:48",
    "roundingAmount": 0.0,
    "paymentMethod": 0,
    "adjustAmount": 1282.22,
    "assistantCxMoney": 0.0,
    "assistantPdMoney": 646.32,
    "couponSaleAmount": 0.0,
    "plCouponSaleAmount": 0.0,
    "merVouSalesAmount": 0.0,
    "memberDiscountAmount": 0.0,
    "tableChargeMoney": 2564.45,
    "goodsMoney": 2357.0,
    "realGoodsMoney": 2357.0,
    "serviceMoney": 0.0,
    "prepayMoney": 0.0,
    "salesManName": "",
    "orderRemark": "",
    "salesManUserId": 0,
    "canBeRevoked": false,
    "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,
    "isFirst": 0,
    "rechargeCardAmount": 4285.55,
    "giftCardAmount": 0,
    "electricityMoney": 0.0,
    "realElectricityMoney": 0.0,
    "electricityAdjustMoney": 0.0
  }
}

六、跨表关联

结账记录是多张明细表的"汇总头"

本表字段 关联表 关联字段 说明
id 台费流水 table_fee_transactions order_settle_id 结账单号 → 台费明细
id 助教流水 assistant_service_records order_settle_id 结账单号 → 助教明细
id 小票详情 settlement_ticket_details orderSettleId 结账单号 → 小票明细
settleRelateId 台费流水 order_trade_no 交易号，跨明细表汇总的核心外键
settleRelateId 助教流水 order_trade_no 同上

桌台维度

本表字段 关联表 关联字段 说明
tableId 台桌主数据 site_tables_master id 桌台 ID
tableId 台费流水 site_table_id 桌台 ID
settleName 台费流水 site_table_area_name + ledger_name 区域 + 桌号组合

会员维度

本表字段 关联表 关联字段 说明
memberId 会员储值卡 member_stored_value_cards tenant_member_id 会员 ID
tenantMemberCardId 会员储值卡 id 会员卡账户 ID（预留外键）

助教金额映射

  • assistantPdMoney = 对应订单下助教流水的 ledger_amount 汇总（应收金额）
  • 助教流水中的 projected_income 是核算侧的实际计入金额，本表不直接体现

与小票详情的关系

  • 结账记录是"汇总视图"，字段较精简
  • 小票详情是更细粒度的结构（含 orderItem 列表、配送信息、会员详情等）
  • 两者通过 id ↔ orderSettleId 一对一关联
  • 小票详情中存在大量同名字段（couponAmount、giftCardAmount、adjustAmount 等），数据模型中通常将结账记录作为 fact 表，小票详情作为明细扩展

新增字段说明（相对旧版 JSON 样本）

以下 5 个字段在最新 API 响应中新增，旧版本地 JSON 样本中不存在：

字段 说明
electricityMoney 电费金额
realElectricityMoney 电费实际计入金额
electricityAdjustMoney 电费调整金额
plCouponSaleAmount 平台券售卖金额
merVouSalesAmount 商户代金券售卖金额
Reference in New Issue View Git Blame Copy Permalink