初始提交：飞球 ETL 系统全量代码

2026-02-13 08:05:34 +08:00
commit 3c51f5485d
441 changed files with 117631 additions and 0 deletions
--- a/docs/api-reference/settlement_ticket_details.md
+++ b/docs/api-reference/settlement_ticket_details.md
@@ -0,0 +1,330 @@
+# ⚠️ 结账小票明细 — GetOrderSettleTicketNew（当前不可用）
+
+> 模块：`Order` · ODS 表：`settlement_ticket_details` · 事实宽表（结算快照）
+
+> **⚠️ 该接口当前不可用**（HTTP 1400 错误）。以下文档基于旧版 Analysis 文档中的已知字段结构编写，待接口恢复后需实际验证。
+
+---
+
+## 一、接口概述
+
+查询结账小票的完整快照/订单打印详情。每条记录对应一张结算小票（一个 `orderSettleId`），包含门店信息、整单金额汇总、会员信息快照、以及订单分项明细（台费、商品、券）等结构化子对象。该接口是对结账记录的"扩展版"：结账记录是纯数值汇总，本接口在此基础上加上了打印所需的文本字段和分项明细。
+
+| 属性 | 值 |
+|------|-----|
+| 完整路径 | `POST /Order/GetOrderSettleTicketNew` |
+| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
+| 鉴权 | `Authorization: Bearer <token>` |
+| 状态 | ⚠️ **当前不可用**（HTTP 1400） |
+| ODS 对应表 | `settlement_ticket_details` |
+
+---
+
+## 二、请求
+
+> 请求参数尚未确认，以下为基于接口命名和关联接口推测的结构。
+
+### 请求体（JSON，推测）
+
+```json
+{
+  "orderSettleId": 2957922914357125
+}
+```
+
+### 参数说明（推测）
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `orderSettleId` | int | 是 | 结算单 ID，对应结账记录中的 `settleList.id` |
+
+---
+
+## 三、响应结构（基于旧版 Analysis）
+
+```
+{
+  "code": 200,
+  "data": {
+    "data": {
+      "tenantId": ...,
+      "orderSettleId": ...,
+      "consumeMoney": ...,
+      "memberProfile": { ... },
+      "orderItem": [
+        {
+          "siteOrderId": ...,
+          "tableLedger": { ... },
+          "goodsLedgers": [ ... ],
+          "orderCouponLedgers": [ ... ]
+        }
+      ],
+      ...
+    }
+  }
+}
+```
+
+`data.data` 为结算小票主对象，共约 37 个头部字段 + 3 个嵌套明细结构。
+
+---
+
+## 四、响应字段详解（基于旧版 Analysis）
+
+### 4.1 租户与门店信息
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `tenantId` | int | — | 租户/商户 ID（品牌维度），所有记录相同。对应其他表的 `tenant_id` |
+| `tenantName` | string | `"朗朗桌球"` | 租户名称，打印抬头 |
+| `siteId` | int | — | 门店 ID，对应各表的 `site_id` |
+| `siteName` | string | `"朗朗桌球"` | 门店名称，小票展示 |
+| `siteAddress` | string | — | 门店详细地址，小票打印用 |
+| `siteBusinessTel` | string | — | 门店电话，小票打印用 |
+
+### 4.2 结算单标识与类型
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `orderSettleId` | int | — | 结算单 ID。等于结账记录 `settleList.id`，等于各明细表的 `order_settle_id` |
+| `orderSettleNumber` | int | `0` | 结算单编号（独立编号体系），当前未启用 |
+| `settleType` | string | `"SiteOrder"` | 结算类型：`SiteOrder` = 店内消费订单结算 |
+| `cashierName` | string | `"收银员:郑丽珊"` | 结算操作员名称（带角色前缀） |
+| `paymentMethod` | int | `2` | 结算主支付方式编码。已知值：`2`、`4`，具体映射需参照系统配置 |
+
+### 4.3 小票文案与备注
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `ticketRemark` | string | `""` | 小票备注内容，打印在小票底部/顶部 |
+| `ticketCustomContent` | string | `""` | 自定义小票内容（商家宣传语等） |
+| `rewardName` | string | `"激励"` | 适用的激励方案名称 |
+| `orderRemark` | string | `""` | 订单备注，收银员录入 |
+| `deliveryAddress` | string/null | `""` | 配送地址（外送场景），当前未使用 |
+
+### 4.4 会员信息快照
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `memberProfile` | object | — | 会员信息快照对象（非主键，仅展示用） |
+| `memberProfile.memberName` | string | `"匿名用户"` | 会员姓名（可能脱敏） |
+| `memberProfile.memberPhone` | string | — | 会员手机号 |
+| `memberProfile.memberPoint` | float | — | 会员剩余积分快照 |
+
+### 4.5 时间字段
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `payTime` | string | `"2025-11-10 15:30:00"` | 最终支付成功时间，对应结账记录的 `payTime` |
+
+### 4.6 整单金额汇总
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `consumeMoney` | float | — | 消费金额总计（元，原价层面），台费+商品+助教+服务的总和，未扣优惠 |
+| `ledgerAmount` | float | — | 结算金额/应付金额（元） |
+| `actualPayment` | float | — | 实际支付金额（元），顾客本次实际付出总和 |
+| `balanceAmount` | float | — | 通过会员余额/储值卡支付的金额（元） |
+| `memberOfferAmount` | float | — | 会员权益/折扣产生的优惠金额（元） |
+| `memberDeductAmount` | int | `0` | 会员抵扣金额（积分抵现等），当前未启用 |
+| `assistantManualDiscount` | float | `0` | 助教项目人工减免金额（元） |
+| `couponAmount` | float | `0` | 优惠券抵扣金额合计（元） |
+| `voucherMoney` | float | `0` | 代金券金额（元），预留字段 |
+| `refundAmount` | float | `0` | 退款金额（元） |
+| `returnGoodsAmount` | float | `0` | 退货金额（元） |
+| `onlineReturnAmount` | float | `0` | 线上支付渠道退回金额（元） |
+| `payMemberBalance` | float | `0` | 使用会员余额支付金额（元），预留字段 |
+| `pointDiscountPrice` | float | `0` | 积分抵扣对应金额（售价侧，元） |
+| `pointDiscountCost` | float | `0` | 积分抵扣对应金额（成本侧，元） |
+| `prepayMoney` | float | — | 预付金/定金使用金额（元） |
+| `deliveryFee` | float | `0` | 配送费（元），当前未使用 |
+| `adjustAmount` | float | — | 人工调价/整单调整金额（元） |
+
+### 4.7 订单明细入口（`orderItem` 数组）
+
+每条小票通常包含 1 个订单组，结构如下：
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `siteOrderId` | int | — | 订单号/交易号。等于结账记录的 `settleRelateId`，等于各流水的 `order_trade_no` |
+| `orderSettleId` | int | — | 结算单 ID（冗余） |
+| `orderType` | int | `1` | 订单类型：`1` = 正常订单 |
+| `tableLedger` | object | — | 台费台账汇总（见 4.8） |
+| `goodsLedgers` | array | — | 商品明细列表（见 4.9） |
+| `orderCouponLedgers` | array | — | 券使用明细列表（见 4.10） |
+
+### 4.8 台费台账（`tableLedger` 对象，14 个字段）
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `orderTableLedgerId` | int | — | 台费台账记录 ID，等于台费流水 `siteTableUseDetailsList.id` |
+| `siteTableId` | int | — | 台桌 ID，对应台桌列表的 `id` |
+| `tableName` | string | `"A17"` | 台桌名称 |
+| `tableAreaName` | string | `"A区"` | 台桌所属区域名称 |
+| `chargeStartTime` | string | — | 计费开始时间 |
+| `chargeEndTime` | string | — | 计费结束时间 |
+| `lastUseTime` | string | — | 最后使用时间 |
+| `consumptionAmount` | float | — | 台费消费金额（元） |
+| `adjustAmount` | float | — | 台费人工调价金额（元） |
+| `memberDiscountAmount` | float | — | 台费会员折扣优惠金额（元） |
+| `pauseDuration` | int | `0` | 暂停计时时长 |
+| `useDuration` | int | — | 台桌使用时长（分钟） |
+| `chargeDuration` | int | `0` | 计费时长（分钟） |
+| `orderServiceLedgers` | array | `[]` | 附加服务项目台账列表，当前为空 |
+
+### 4.9 商品明细（`goodsLedgers` 数组，每条 18 个字段）
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `orderGoodsLedgerId` | int | — | 商品台账记录 ID（主键） |
+| `orderTradeNo` | int | — | 订单交易号，等于 `siteOrderId` |
+| `tenantGoodsCategoryId` | int | — | 商品分类 ID |
+| `memberCouponId` | int | `0` | 会员专属券使用 ID |
+| `siteGoodsId` | int | — | 门店商品 ID，对应商品档案 |
+| `orderCouponId` | int | `0` | 整单券分摊 ID |
+| `goodsName` | string | `"可乐"` | 商品名称 |
+| `goodsRemark` | string | — | 商品备注 |
+| `optionName` | string | `""` | 规格/选项名称（如"加冰"） |
+| `optionValueName` | string | `""` | 规格值名称 |
+| `goodsCount` | int | — | 商品数量（件） |
+| `goodsPrice` | float | — | 商品单价（元） |
+| `ledgerAmount` | float | — | 商品小计金额（元，单价×数量） |
+| `discountMoney` | float | — | 商品促销/折扣金额（元） |
+| `memberDiscountAmount` | float | — | 商品会员折扣优惠金额（元） |
+| `optionPrice` | float | `0` | 规格附加价格（元） |
+| `salesType` | int | `1` | 销售类型：`1` = 正常销售 |
+| `realGoodsMoney` | float | — | 商品实际计入金额（元，扣除折扣后） |
+
+### 4.10 券使用明细（`orderCouponLedgers` 数组，每条 15 个字段）
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `orderCouponLedgerId` | int | — | 券台账记录 ID（主键） |
+| `orderTradeNo` | int | — | 订单交易号 |
+| `promotionCouponId` | int | — | 促销券/团购券配置 ID（券模板 ID） |
+| `orderCouponId` | int | — | 本次订单使用该券的实例 ID |
+| `couponName` | string | `"全天A区中八一小时"` | 券名称 |
+| `couponType` | int | `0` | 券类型编码（时间券/金额券/折扣券等） |
+| `offerType` | int | `1` | 优惠类型（减免/打折/赠送等） |
+| `couponPrice` | float | — | 券面值或基础价格（元） |
+| `orderCouponChannel` | int | — | 券来源渠道：`1`、`2`（平台券/门店券等） |
+| `discountAmount` | float | — | 该券实际产生的优惠金额（元） |
+| `ledgerAmount` | float | — | 台账口径对应金额（元） |
+| `rewardPromotionMoney` | float | — | 激励/返利相关促销金额（元） |
+| `tableServicePromotionMoney` | float | — | 分摊到台费/服务费的促销金额（元） |
+| `rechargePromotionMoney` | float | — | 分摊到充值活动的促销金额（元） |
+| `goodsPromotionMoney` | float | — | 分摊到商品的促销金额（元） |
+
+---
+
+## 五、响应样例
+
+> ⚠️ 该接口当前不可用，无法获取实际响应样例。以下为基于旧版 Analysis 文档的结构示意。
+
+```json
+{
+  "tenantId": 2790683160709957,
+  "tenantName": "朗朗桌球",
+  "siteId": 2790685415443269,
+  "siteName": "朗朗桌球",
+  "orderSettleId": 2957922914357125,
+  "settleType": "SiteOrder",
+  "payTime": "2025-11-10 15:30:00",
+  "consumeMoney": 120.0,
+  "actualPayment": 100.0,
+  "balanceAmount": 0.0,
+  "memberProfile": {
+    "memberName": "匿名用户",
+    "memberPhone": "",
+    "memberPoint": 0.0
+  },
+  "orderItem": [
+    {
+      "siteOrderId": 2957858167230149,
+      "orderSettleId": 2957922914357125,
+      "orderType": 1,
+      "tableLedger": {
+        "orderTableLedgerId": 0,
+        "siteTableId": 0,
+        "tableName": "A17",
+        "tableAreaName": "A区",
+        "consumptionAmount": 80.0
+      },
+      "goodsLedgers": [],
+      "orderCouponLedgers": []
+    }
+  ]
+}
+```
+
+---
+
+## 六、跨表关联
+
+### 与结账记录（`settlement_records`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `orderSettleId` | `settleList.id` | 结算单 ID |
+| `consumeMoney` | `consumeMoney` | 消费金额总计 |
+| `actualPayment` | `actualPayment` | 实际支付金额 |
+| `balanceAmount` | `balanceAmount` | 余额支付金额 |
+| `memberOfferAmount` | `memberOfferAmount` | 会员优惠金额 |
+| `adjustAmount` | `adjustAmount` | 人工调价金额 |
+
+> 本表是结账记录的"扩展版"，在金额汇总基础上增加了打印文本和分项明细。
+
+### 与支付记录（`payment_records`）
+
+| 本表字段 | 关联路径 | 说明 |
+|----------|---------|------|
+| `orderSettleId` | → 结账记录 `id` → 支付记录 `relate_id`（`relate_type=2`） | 通过结账记录间接关联 |
+| `paymentMethod` | 支付记录 `payment_method` | 同一编码体系 |
+
+### 与台费流水（`table_fee_records`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `tableLedger.orderTableLedgerId` | `siteTableUseDetailsList.id` | 台费台账记录 ID |
+| `tableLedger.siteTableId` | `site_table_id` | 台桌 ID |
+
+### 与助教流水（`assistant_service_records`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `orderItem.siteOrderId` | `order_trade_no` | 通过订单号关联 |
+
+> 小票本身未直接展开助教明细，通过订单号与助教流水挂接。
+
+### 与台桌主数据（`site_tables_master`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `tableLedger.siteTableId` | `id` | 台桌主键 |
+| `tableLedger.tableName` | `table_name` | 台号名称 |
+
+### 与商品档案
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `goodsLedgers.siteGoodsId` | 商品档案 `siteGoodsId` | 门店商品 ID |
+| `goodsLedgers.tenantGoodsCategoryId` | 商品分类表 `id` | 商品分类 ID |
+
+### 双主键体系
+
+- `siteOrderId`（订单号）串联所有"订单维度"明细：台费、助教、商品、券
+- `orderSettleId`（结算单号）串联所有"结算维度"记录：结账记录、支付记录、小票
+
+### 金额双维度拆分
+
+- **来源维度**：会员优惠（`memberOfferAmount`）、券优惠（`couponAmount`）、人工调价（`adjustAmount`）、积分（`pointDiscountPrice`）、预付（`prepayMoney`）等
+- **载体维度**：台费（`tableLedger`）、商品（`goodsLedgers`）、券促销分摊（`orderCouponLedgers` 中各 `*PromotionMoney` 字段）
+
+<!--
+AI_CHANGELOG:
+- 日期: 2026-02-13
+- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
+- 直接原因: 按标杆文档格式重写高质量 API 参考文档
+- 变更摘要: 新建 docs/api-reference/settlement_ticket_details.md，标注接口当前不可用，基于旧版 Analysis 详解约 37+嵌套字段结构，含跨表关联
+- 风险与验证: 纯文档，无运行时影响；验证方式：对比 test-json-doc/settlement_ticket_details-Analysis.md 确认字段覆盖完整；接口恢复后需实际验证
+-->