# 门店商品销售记录 — GetGoodsSalesList

> 模块：`TenantGoods` · ODS 表：`store_goods_sales_records` · 事实表（增量）

---

## 一、接口概述

查询门店商品销售明细流水，每条记录对应一次商品销售行为（订单中的一行商品）。包含商品信息、金额明细、折扣/优惠券/积分抵扣、操作员、关联订单等完整信息。是商品维度的核心事实表，挂在订单主键下，通过 `site_goods_id` 与商品档案、库存表相连，通过 `site_table_id` 与球台表相连。

| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /TenantGoods/GetGoodsSalesList` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | `page` + `limit`（最大 100） |
| 时间范围 | 需要（`startTime` / `endTime`） |
| 响应数据路径 | `data.orderGoodsLedgers` |

---

## 二、请求

### 请求体（JSON）

```json
{
  "isSalesBind": 0,
  "startTime": "2026-02-01 08:00:00",
  "endTime": "2026-02-13 08:00:00",
  "siteId": 2790685415443269,
  "goodsSalesType": 0,
  "page": 1,
  "limit": 100
}
```

### 参数说明

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `isSalesBind` | int | 是 | 是否绑定销售员筛选。`0` = 全部 |
| `startTime` | string | 是 | 查询起始时间，格式 `YYYY-MM-DD HH:MM:SS` |
| `endTime` | string | 是 | 查询结束时间，格式 `YYYY-MM-DD HH:MM:SS` |
| `siteId` | int | 是 | 门店 ID |
| `goodsSalesType` | int | 是 | 销售类型筛选。`0` = 全部，`1` = 正常销售 |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |

---

## 三、响应结构

```
{
  "code": 200,
  "data": {
    "list": [ { ... }, { ... } ],
    "total": 200
  }
}
```

`data.list` 中每个对象即为一条销售明细记录，共 50 个字段，按逻辑分组说明如下。

---

## 四、响应字段详解（50 个字段）

### 4.1 订单与关联 ID

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `2957924029550406` | 销售流水记录主键 ID，每条不重复 |
| `order_trade_no` | int | `2957858167230149` | 订单交易号（业务单号）。与台费流水、团购套餐流水、助教流水等表中的 `order_trade_no` 一致，用于串联同一订单下的不同消费项目 |
| `order_settle_id` | int | `2957922914357125` | 订单结算 ID（结账单主键）。与小票详情的 `orderSettleId` 对应 |
| `order_pay_id` | int | `0` | 关联支付记录 ID。对应支付记录表中的主键或 `relate_id`。`0` 表示未单独关联支付流水 |
| `order_goods_id` | int | `2957858456391557` | 订单商品明细 ID（订单内部的商品行主键），每条不同。用于在小票详情中区分多行商品 |
| `orderGoodsId` | int | `0` | 老版本兼容字段，当前已统一使用 `order_goods_id`，全部为 0 |
| `site_goods_id` | int | `2793026176012357` | 门店商品 ID。对应门店商品档案（`store_goods_master`）的 `id` |
| `tenant_goods_id` | int | `2792115932417925` | 租户级商品 ID（全局商品 ID）。对应租户商品档案（`tenant_goods_master`）的 `id` |
| `tenant_goods_category_id` | int | `2790683528350540` | 租户级商品一级分类 ID，对应分类树主键 |
| `tenant_goods_business_id` | int | `2790683528317768` | 租户级商品业务大类 ID（如"酒水类""零食类"等更高维度） |

### 4.2 门店与球台维度

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID，所有记录相同 |
| `site_id` | int | `2790685415443269` | 门店 ID（系统主键），与其他业务表一致 |
| `siteName` | string | `"朗朗桌球"` | 门店名称，冗余展示字段 |
| `siteId` | int | `0` | 历史兼容字段，当前不再使用。真正的门店 ID 已统一用 `site_id` |
| `site_table_id` | int | `2793003705192517` | 球台 ID。非 0 表示关联到具体球台（如顾客在台上点饮料）；`0` 表示未关联球台（纯前台售卖） |

### 4.3 商品名称与分组

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `ledger_name` | string | `"哇哈哈矿泉水"` | 销售项目名称（商品名称）。历史流水即使商品改名，这里保留当时的名字 |
| `ledger_group_name` | string | `"酒水"` | 门店内部分组名称（前台菜单分组），如"酒水""零食""小吃""服务费"等。与品牌统一分类（`tenant_goods_category_id`）是两套维度 |
| `goods_remark` | string | `"哇哈哈矿泉水"` | 商品备注/口味说明。部分为空，部分与商品名相同 |
| `option_value_name` | string | `""` | 商品选项名称（规格/口味：大杯/小杯等）。当前门店未启用多规格，全部为空 |

### 4.4 金额与数量

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `ledger_unit_price` | float | `5.0` | 结算单价，单位：元（人民币） |
| `ledger_count` | int | `1` | 销售数量（以门店商品档案中的 `unit` 为单位） |
| `ledger_amount` | float | `5.0` | 原始应收金额，约等于 `ledger_unit_price × ledger_count`。未考虑优惠前的金额基础 |
| `discount_price` | float | `5.0` | 折后单价，单位：元。无折扣时等于 `ledger_unit_price`；有折扣时小于原价 |
| `discount_money` | float | `0.0` | 价格优惠金额，单位：元。简单场景下：`ledger_amount - discount_money ≈ real_goods_money` |
| `real_goods_money` | float | `5.0` | 商品实际入账金额，单位：元。考虑折扣后的实际销售金额，`real_goods_money ≤ ledger_amount` |
| `cost_money` | float | `0.01` | 本条销售对应的成本金额，单位：元。来源于门店商品档案中 `cost_price` 与成本核算逻辑 |
| `returns_number` | int | `0` | 退货数量。当前样本中全部为 0（无退货） |

### 4.5 积分、优惠券与抵扣

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `coupon_deduct_money` | float | `0.0` | 优惠券/团购券直接抵扣到本行商品的金额，单位：元。券在订单级抵扣时此字段为 0 |
| `member_discount_amount` | float | `0.0` | 会员折扣针对本行商品的优惠金额，单位：元。当前可能合并反映在 `discount_money` 中 |
| `point_discount_money` | float | `0.0` | 积分抵扣金额（顾客兑换积分抵现），单位：元 |
| `point_discount_money_cost` | float | `0.0` | 积分抵扣对应的成本金额（后台核算用），单位：元 |
| `package_coupon_id` | int | `0` | 套餐券 ID。若商品从套餐拆分而来，用于追溯到团购套餐流水。当前未使用 |
| `order_coupon_id` | int | `0` | 订单级优惠券 ID。整单使用优惠券时记录，用于"订单级券对本行分摊"。当前未使用 |
| `member_coupon_id` | int | `0` | 会员券 ID（会员专享优惠券），预留字段，当前未使用 |
| `option_price` | float | `0.0` | 商品选项（规格/加料）附加价格，单位：元。当前门店未启用选项体系 |
| `option_member_discount_money` | float | `0.0` | 会员折扣作用在选项价格上的优惠金额，单位：元。当前未启用 |
| `option_coupon_deduct_money` | float | `0.0` | 优惠券抵扣选项价格的金额，单位：元。当前未启用 |
| `coupon_share_money` | number | `0.0` | 优惠券在本行商品上的分摊金额（元）。整单使用优惠券时按比例分摊到各商品行 |

### 4.6 操作员与销售员

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `operator_id` | int | `2790687322443013` | 操作员 ID（录入销售的员工）。与其他流水中的 `operator_id` 一致，可跨台费/助教/商品销售统一追踪 |
| `operator_name` | string | `"收银员:郑丽珊"` | 操作员姓名，冗余展示字段 |
| `openSalesman` | int | `2` | 营业员机制开关：`1` = 启用（需指定销售员），`2` = 未启用。当前门店全部为 2 |
| `salesman_user_id` | int | `0` | 营业员用户 ID（系统账号 ID），未启用时为 0 |
| `salesman_name` | string | `""` | 营业员姓名，未启用时为空 |
| `salesman_role_id` | int | `0` | 营业员系统角色 ID，未启用时为 0 |
| `sales_man_org_id` | int | `0` | 营业员所属组织/部门 ID，未启用时为 0 |
| `push_money` | float | `0.0` | 本条销售对应的提成金额，单位：元。启用营业员体系时才会出现正数 |

### 4.7 记录状态与控制

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `ledger_status` | int | `1` | 销售流水状态：`1` = 正常有效。其他值可能表示"待结算""作废"等 |
| `is_single_order` | int | `1` | 是否单独订单标识：`1` = 作为独立明细参与订单结算，`0` = 合并为打包项目 |
| `sales_type` | int | `1` | 销售类型：`1` = 正常销售。其他可能值：`2` = 赠品，`3` = 内部消耗，`4` = 盘点调整 |
| `is_delete` | int | `0` | 逻辑删除标志：`0` = 正常有效，`1` = 已删除 |

### 4.8 时间

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `create_time` | string | `"2025-11-09 23:35:57"` | 销售记录创建时间，通常即结账/录入时间。用于按时间维度查询销售流水 |

---

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

```json
{
  "siteId": 0,
  "siteName": "朗朗桌球",
  "orderGoodsId": 0,
  "openSalesman": 2,
  "id": 2957924029550406,
  "order_trade_no": 2957858167230149,
  "site_id": 2790685415443269,
  "tenant_id": 2790683160709957,
  "operator_id": 2790687322443013,
  "operator_name": "收银员:郑丽珊",
  "order_settle_id": 2957922914357125,
  "ledger_name": "哇哈哈矿泉水",
  "ledger_group_name": "酒水",
  "ledger_unit_price": 5.0,
  "ledger_count": 1,
  "ledger_amount": 5.0,
  "order_pay_id": 0,
  "create_time": "2025-11-09 23:35:57",
  "is_delete": 0,
  "tenant_goods_category_id": 2790683528350540,
  "tenant_goods_business_id": 2790683528317768,
  "is_single_order": 1,
  "site_goods_id": 2793026176012357,
  "cost_money": 0.01,
  "ledger_status": 1,
  "site_table_id": 2793003705192517,
  "discount_money": 0.0,
  "salesman_user_id": 0,
  "salesman_name": "",
  "salesman_role_id": 0,
  "tenant_goods_id": 2792115932417925,
  "discount_price": 5.0,
  "real_goods_money": 5.0,
  "sales_type": 1,
  "package_coupon_id": 0,
  "order_coupon_id": 0,
  "goods_remark": "哇哈哈矿泉水",
  "returns_number": 0,
  "member_discount_amount": 0.0,
  "point_discount_money": 0.0,
  "point_discount_money_cost": 0.0,
  "push_money": 0.0,
  "sales_man_org_id": 0,
  "coupon_deduct_money": 0.0,
  "option_value_name": "",
  "option_price": 0.0,
  "option_member_discount_money": 0.0,
  "option_coupon_deduct_money": 0.0,
  "member_coupon_id": 0,
  "order_goods_id": 2957858456391557
}
```

---

## 六、跨表关联

### 与门店商品档案（`store_goods_master`）

| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `site_goods_id` | `id` | 门店商品 ID，关联商品定价、库存、分类等基础信息 |
| `tenant_goods_id` | `tenant_goods_id` | 全局商品 ID 一致 |

### 与租户商品档案（`tenant_goods_master`）

| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `tenant_goods_id` | `id` | 品牌级商品主键 |
| `tenant_goods_category_id` | `goods_category_id` | 一级分类 ID |
| `tenant_goods_business_id` | — | 业务大类 ID，对应分类树中的 `tenant_goods_business_id` |

### 与订单/支付相关表

| 本表字段 | 关联表 | 说明 |
|----------|--------|------|
| `order_trade_no` | 台费流水、助教流水、团购套餐流水 | 同一订单下的不同消费项目通过此字段串联 |
| `order_settle_id` | 小票详情 (`orderSettleId`) | 结账单主键 |
| `order_pay_id` | 支付记录 | 关联支付流水 |

### 与库存相关表

- `site_goods_id` 对应库存汇总（`goods_stock_summary`）的 `siteGoodsId` 和库存变动（`goods_stock_movements`）的 `siteGoodsId`
- 每次商品销售理论上对应一次库存出库记录（`stockType=1`）

### 与球台维度

- `site_table_id` 对应台桌列表的 `id`，非 0 时表示在台上消费点单

<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/store_goods_sales_records.md，按逻辑分组详解所有 50 个字段，含跨表关联
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整

- 日期: 2026-02-14
- Prompt: P20260214-060000 / P20260214-061000 — 全量 JSON 刷新 + MD 文档补全 + 数据路径修正
- 直接原因: 旧 JSON 样本仅含单条记录，缺少条件性字段；api_registry.json 中 17 个 data_path 与实际不符
- 变更摘要: 新增「响应数据路径」行；补全 7 个缺失字段（ordergoodsid, siteid, sitename 等）
- 风险与验证: 纯文档变更，无运行时影响；验证：python scripts/refresh_json_and_audit.py 输出 24/24 通过

- 日期: 2026-02-14
- Prompt: P20260214-130000 — 25 个 API 文档归档至 summary/ + 字段分组修正
- 直接原因: 4.8"时间"组混入 coupon_share_money（优惠券分摊金额），与时间无关
- 变更摘要: coupon_share_money 移至 4.5"积分、优惠券与抵扣"组末尾；4.8 仅保留 create_time
- 风险与验证: 纯文档分组调整，无运行时影响；验证：统计各组字段数总和 = 50
-->
