331 lines
14 KiB
Markdown
331 lines
14 KiB
Markdown
# ⚠️ 结账小票明细 — 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 确认字段覆盖完整；接口恢复后需实际验证
|
||
-->
|