root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

init: 项目初始提交 - NeoZQYY Monorepo 完整代码

Browse Source
This commit is contained in:
Neo
2026-02-15 14:58:14 +08:00
commit ded6dfb9d8
769 changed files with 182616 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

297
apps/etl/pipelines/feiqiu/docs/api-reference/summary/assistant_accounts_master.md Normal file
View File

@@ -0,0 +1,297 @@
# 助教账号主数据 — SearchAssistantInfo
> 模块：`PersonnelManagement` · ODS 表：`assistant_accounts_master` · 维度表（快照）
---
## 一、接口概述
查询门店下所有助教账号的基础信息，包括人事档案、等级配置、薪资开关、在线状态等。每条记录对应一名助教账号，是典型的维度表，与助教流水等事实表通过 `id` / `user_id` / `team_id` 关联。
| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /PersonnelManagement/SearchAssistantInfo` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | `page` + `limit`（最大 100） |
| 时间范围 | 不需要（全量快照） |
| 响应数据路径 | `data.assistantInfos` |
---
## 二、请求
### 请求体（JSON）
```json
{
"workStatusEnum": 0,
"dingTalkSynced": 0,
"leaveId": 0,
"criticismStatus": 0,
"signStatus": -1,
"page": 1,
"limit": 100
}
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `workStatusEnum` | int | 是 | 工作状态筛选。`0` = 全部，`1` = 在岗，`2` = 离岗 |
| `dingTalkSynced` | int | 是 | 钉钉同步状态筛选。`0` = 全部，`1` = 已同步 |
| `leaveId` | int | 是 | 离职状态筛选。`0` = 全部，`1` = 已离职 |
| `criticismStatus` | int | 是 | 投诉状态筛选。`0` = 全部，`1` = 正常，`2` = 有投诉 |
| `signStatus` | int | 是 | 合同签署状态筛选。`-1` = 全部，`0` = 未签署 |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |
---
## 三、响应结构
```
{
"code": 200,
"data": {
"list": [ { ... }, { ... } ],
"total": 50
}
}
```
`data.list` 中每个对象即为一条助教记录，共 61 个字段，按逻辑分组说明如下。
---
## 四、响应字段详解（61 个字段）
### 4.1 主键与账号身份
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `2947562271297029` | 助教账号主键 ID。所有助教相关事实表（助教流水、排班等）通过此 ID 关联。在助教流水中对应 `site_assistant_id` |
| `user_id` | int | `2947562270838277` | 系统级用户账号 ID，对应登录账号。用于统一人员在不同角色/模块下的身份，区别于岗位级的 `id`。在助教流水中有同名字段 |
| `assistant_no` | string | `"31"` | 助教工号/编号，便于业务侧识别。编号不唯一（不同助教可能重复）。在助教流水中对应 `assistantNo` |
| `job_num` | string | `""` | 备用工号字段，当前门店未启用，全部为空字符串 |
| `serial_number` | int | `0` | 系统内部序列号/排序标识，部分为 0，部分为较大整数（如 2738），用于全局排序或数据迁移 |
| `system_role_id` | int | `10` | 系统角色 ID，标识该账号在系统中的角色类型 |
### 4.2 个人基础信息
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `real_name` | string | `"张静然"` | 助教真实姓名。在助教流水中对应 `assistantName` |
| `nickname` | string | `"小然"` | 前台展示昵称，用于顾客侧展示，与真实姓名区分。在助教流水中有同名字段 |
| `gender` | int | `0` | 性别枚举：`0` = 未填/保密，`1` = 男，`2` = 女 |
| `birth_date` | string | `"0001-01-01 00:00:00"` | 出生日期。`0001-01-01` 为默认无效日期（未填写），少量为真实日期 |
| `mobile` | string | `"15119679931"` | 手机号（11 位），用于登录绑定、通知、钉钉同步。每个账号基本唯一 |
| `avatar` | string | `"https://oss.ficoo.vip/...defaultAvatar.png"` | 头像 URL。大量为默认头像，少量为自定义头像 |
| `introduce` | string | `""` | 个人简介文案，预留字段，当前全部为空 |
| `video_introduction_url` | string | `""` | 个人视频介绍 URL（OSS 存储），绝大多数为空，极少数有值 |
| `height` | float | `0.0` | 身高（厘米）。`0` 表示未填写，有值时如 163.0、170.0 |
| `weight` | float | `0.0` | 体重（公斤）。`0` 表示未填写，有值时如 55.0、90.0 |
### 4.3 组织、团队与门店
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `tenant_id` | int | `2790683160709957` | 品牌/租户 ID，所有记录相同。多门店场景下用于区分不同商户 |
| `site_id` | int | `2790685415443269` | 门店 ID，所有记录相同。与其他业务表（台费流水、库存等）的 `site_id` 一致 |
| `shop_name` | string | `"朗朗桌球"` | 门店名称，冗余展示字段 |
| `team_id` | int | `2792011585884037` | 助教所属团队 ID。在助教流水中对应 `assistant_team_id` |
| `team_name` | string | `"1组"` | 团队名称，展示用，与 `team_id` 一一对应 |
| `group_id` | int | `0` | 上层分组 ID（集团/事业部），预留字段，当前门店未使用 |
| `group_name` | string | `""` | `group_id` 对应名称，当前为空 |
| `person_org_id` | int | `2947562271215109` | 人事组织 ID，表示"门店-助教部-小组"等层级。每条记录不同。在助教流水中有同名字段。用于人力组织维度统计和权限控制 |
| `staff_id` | int | `0` | 人事系统员工 ID，预留字段，当前未接入外部 HR 系统 |
| `staff_profile_id` | int | `0` | 人事档案 ID，预留字段，当前未启用 |
### 4.4 等级、计费与薪资
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `level` | int | `20` | 助教等级枚举：`8` = 助教管理/管理员，`10` = 初级，`20` = 中级，`30` = 高级，`40` = 资深/专家。在助教流水中以 `assistant_level` + `levelName` 体现 |
| `charge_way` | int | `2` | 计费方式枚举：`2` = 计时收费（当前门店），其他值（1、3）可能对应按局、按课时 |
| `pd_unit_price` | float | `0.0` | 普通时段单价，当前未在账号层面配置（实际单价在助教商品/套餐配置中） |
| `cx_unit_price` | float | `0.0` | 促销时段单价，当前未在账号层面配置 |
| `allow_cx` | int | `1` | 是否允许参与促销计费：`1` = 允许，其他值 = 不允许 |
| `is_guaranteed` | int | `1` | 是否配置保底薪酬/保底时长：`1` = 有保底规则 |
| `salary_grant_enabled` | int | `2` | 薪资发放配置开关。`2` 为当前门店统一值，具体含义需参照系统配置 |
| `assistant_grade` | float | `0.0` | 助教综合评分（平均分快照），当前未启用评分功能 |
| `sum_grade` | float | `0.0` | 评分总和，用于计算平均分（`assistant_grade = sum_grade / get_grade_times`） |
| `get_grade_times` | int | `0` | 累计被评分次数，当前为 0 |
### 4.5 入职、离职与合同签署
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `entry_time` | string | `"2025-11-02 08:00:00"` | 入职时间 |
| `resign_time` | string | `"2025-11-03 08:00:00"` | 离职日期。在职员工使用远未来日期（如 `2225-xx-xx`）作为占位，已离职员工为真实日期 |
| `entry_type` | int | `1` | 入职类型：`1` = 正式入职，其他值可能表示实习/兼职（当前未出现） |
| `entry_sign_status` | int | `0` | 入职协议签署状态：`0` = 未签署（当前未启用电子签功能） |
| `resign_sign_status` | int | `0` | 离职协议签署状态：`0` = 未签署 |
| `leave_status` | int | `1` | 离职状态：`0` = 在职（`resign_time` 为远未来占位），`1` = 已离职（`resign_time` 为真实日期） |
| `work_status` | int | `2` | 工作状态：`1` = 在岗/可排班（`leave_status=0` 时），`2` = 离岗/停止安排（`leave_status=1` 时） |
### 4.6 账号启用、展示与在线状态
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `assistant_status` | int | `1` | 账号启用状态：`1` = 启用，`2` = 停用/冻结（可能未离职但账号被禁用） |
| `show_status` | int | `1` | 前台展示状态：`1` = 在助教选择界面展示 |
| `show_sort` | int | `31` | 前台展示排序权重，数值越小排序越靠前，与 `assistant_no` 有一定对应关系 |
| `online_status` | int | `1` | 在线状态：`1` = 在线 |
| `is_delete` | int | `0` | 逻辑删除标记：`0` = 未删除，`1` = 已逻辑删除（数据保留，前台不可见） |
### 4.7 评价与投诉
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `criticism_status` | int | `1` | 投诉/差评状态：`1` = 正常/无投诉，`2` = 有投诉记录 |
> `assistant_grade` / `sum_grade` / `get_grade_times` 见 4.4 节。当前全部为 0，表示该门店尚未产生助教评价数据。
### 4.8 时间元数据与最近服务
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `create_time` | string | `"2025-11-02 15:55:26"` | 账号创建时间 |
| `update_time` | string | `"2025-11-03 18:32:07"` | 账号最近修改时间（如修改等级、昵称等） |
| `start_time` | string | `"2025-11-01 08:00:00"` | 当前配置生效开始日期（周期性排班/合同周期），多为整月开始 |
| `end_time` | string | `"2025-12-01 08:00:00"` | 当前配置生效结束日期 |
| `last_table_id` | int | `0` | 最近一次服务的球台 ID，`0` 表示无记录 |
| `last_table_name` | string | `""` | 最近服务球台名称（展示用），如 `"TV"`、`"888"` |
| `last_update_name` | string | — | 最近修改该账号配置的管理员名称，如 `"助教管理员:黄月柳"` |
| `order_trade_no` | int | `0` | 最近一次关联的订单号，`0` 表示无记录。仅为"影子值"，真正的订单明细在订单表中 |
### 4.9 系统集成（钉钉 / 灯控）
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `ding_talk_synced` | int | `1` | 是否已同步至钉钉：`1` = 已同步 |
| `site_light_cfg_id` | int | `0` | 门店灯控配置 ID，当前门店未在助教维度启用 |
| `light_equipment_id` | string | `""` | 灯控设备 ID，用于"助教开台自动控灯"场景，当前未启用 |
| `light_status` | int | `2` | 灯光控制状态：`2` = 不启用（预留字段） |
### 4.10 其他标志
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `is_team_leader` | int | `0` | 是否为团队长/组长：`0` = 普通助教，`1` = 团队长（当前门店未指定） |
---
## 五、响应样例（单条记录）
```json
{
"id": 2947562271297029,
"user_id": 2947562270838277,
"assistant_no": "31",
"job_num": "",
"serial_number": 0,
"system_role_id": 10,
"real_name": "张静然",
"nickname": "小然",
"gender": 0,
"birth_date": "0001-01-01 00:00:00",
"mobile": "15119679931",
"avatar": "https://oss.ficoo.vip/maUiImages/images/defaultAvatar.png",
"introduce": "",
"video_introduction_url": "",
"height": 0.0,
"weight": 0.0,
"tenant_id": 2790683160709957,
"site_id": 2790685415443269,
"shop_name": "朗朗桌球",
"team_id": 2792011585884037,
"team_name": "1组",
"group_id": 0,
"group_name": "",
"person_org_id": 2947562271215109,
"staff_id": 0,
"staff_profile_id": 0,
"level": 20,
"charge_way": 2,
"pd_unit_price": 0.0,
"cx_unit_price": 0.0,
"allow_cx": 1,
"is_guaranteed": 1,
"salary_grant_enabled": 2,
"assistant_grade": 0.0,
"sum_grade": 0.0,
"get_grade_times": 0,
"entry_time": "2025-11-02 08:00:00",
"resign_time": "2025-11-03 08:00:00",
"entry_type": 1,
"entry_sign_status": 0,
"resign_sign_status": 0,
"leave_status": 1,
"work_status": 2,
"assistant_status": 1,
"show_status": 1,
"show_sort": 31,
"online_status": 1,
"is_delete": 0,
"criticism_status": 1,
"create_time": "2025-11-02 15:55:26",
"update_time": "2025-11-03 18:32:07",
"start_time": "2025-11-01 08:00:00",
"end_time": "2025-12-01 08:00:00",
"last_table_id": 0,
"last_table_name": "",
"order_trade_no": 0,
"ding_talk_synced": 1,
"site_light_cfg_id": 0,
"light_equipment_id": "",
"light_status": 2,
"is_team_leader": 0
}
```
---
## 六、跨表关联
### 与助教流水（`assistant_service_records`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `id` | `site_assistant_id` | 助教主键 → 流水中的助教 ID |
| `user_id` | `user_id` | 系统用户 ID，完全一致 |
| `team_id` | `assistant_team_id` | 团队 ID |
| `person_org_id` | `person_org_id` | 人事组织 ID |
| `level` | `assistant_level` | 助教等级（流水中还有 `levelName` 文本） |
| `nickname` | `nickname` | 昵称 |
> 助教流水是事实表，本表是对应的助教维表。
### 与门店维度
所有业务表的 `tenant_id`、`site_id` 一致，共享门店维度。台费流水、销售记录、库存变化等表通过 `site_id` / `shop_name` 关联。
### 与订单相关表
`order_trade_no` 仅为"最近订单号"的影子值，真正的订单明细在订单表/小票详情中。助教与订单的关联通过助教流水这张桥接事实表实现。
### 与外部系统
- `ding_talk_synced` / `staff_profile_id` / `staff_id`：企业内部人事系统/钉钉集成预留字段
- `site_light_cfg_id` / `light_equipment_id` / `light_status`：灯控设备联动预留字段，当前未启用
<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-170000 — API 文档全面重构（模板文档，手工创建）
- 直接原因: 作为 API 参考文档的标准模板，首次创建
- 变更摘要: 创建完整的 assistant_accounts_master API 参考文档，含六大章节结构
- 风险与验证: 纯文档，无运行时影响
- 日期: 2026-02-14
- Prompt: P20260214-060000 / P20260214-061000 — 全量 JSON 刷新 + MD 文档补全 + 数据路径修正
- 直接原因: 旧 JSON 样本仅含单条记录，缺少条件性字段；api_registry.json 中 17 个 data_path 与实际不符
- 变更摘要: 新增「响应数据路径」行（记录 API 实际返回的数据路径）
- 风险与验证: 纯文档变更，无运行时影响；验证：python scripts/refresh_json_and_audit.py 输出 24/24 通过
-->

194
apps/etl/pipelines/feiqiu/docs/api-reference/summary/assistant_cancellation_records.md Normal file
View File

@@ -0,0 +1,194 @@
# 助教撤销记录 — GetAbolitionAssistant
> 模块：`AssistantPerformance` · ODS 表：`assistant_cancellation_records` · 事件表（增量）
---
## 一、接口概述
查询门店下助教服务被撤销（废除）的记录。每条记录对应一次"助教排钟后被取消"的事件，包含台桌、助教、已计费时长、废除金额等信息。本表是助教流水的配套事件表，专门记录废除操作的明细，用于运营审计和对账。
| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /AssistantPerformance/GetAbolitionAssistant` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | `page` + `limit`（最大 100） |
| 时间范围 | `startTime` / `endTime`（必填） |
---
## 二、请求
### 请求体（JSON）
```json
{
"startTime": "2025-11-01 08:00:00",
"endTime": "2025-11-10 08:00:00",
"siteId": 2790685415443269,
"page": 1,
"limit": 100
}
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `startTime` | string | 是 | 查询起始时间，格式 `YYYY-MM-DD HH:MM:SS` |
| `endTime` | string | 是 | 查询结束时间，格式 `YYYY-MM-DD HH:MM:SS` |
| `siteId` | int | 是 | 门店 ID |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |
---
## 三、响应结构
```
{
"code": 200,
"data": {
"list": [ { ... }, { ... } ],
"total": 15
}
}
```
`data.list` 中每个对象即为一条助教撤销记录，共 13 个字段，按逻辑分组说明如下。
---
## 四、响应字段详解（13 个字段）
### 4.1 主键与门店
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `2957675849518789` | 撤销记录主键 ID，唯一标识一条废除事件 |
| `siteId` | int | `2790685415443269` | 门店 ID，与 `siteProfile.id` 一致 |
| `siteProfile` | object | `{...}` | 门店信息快照（冗余），包含门店名称、地址、经纬度等 26 个子字段。结构与其他接口的 `siteProfile` 完全一致，此处为空壳式冗余，不再逐字段展开 |
### 4.2 台桌维度
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `tableId` | int | `2793016660660357` | 台桌 ID，对应台桌配置表的主键。标识废除发生在哪张台 |
| `tableName` | string | `"C1"` | 台桌名称/编号，冗余展示字段。常见值如 `"C1"`、`"B9"`、`"VIP1"`、`"A4"`、`"666"`、`"董事办"` 等 |
| `tableAreaId` | int | `2791963816579205` | 台桌所在区域 ID，对应区域配置表主键 |
| `tableArea` | string | `"C区"` | 台桌所属区域名称。已知值：`"A区"`、`"B区"`、`"C区"`、`"VIP包厢"`、`"K包"`、`"补时长"`、`"666"` |
### 4.3 助教维度
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `assistantOn` | string | `"27"` | 助教编号（工号），虽为字符串类型但内容为纯数字。对应助教账号表的 `assistant_no`、助教流水的 `assistantNo` |
| `assistantName` | string | `"泡芙"` | 助教姓名/昵称，冗余展示字段。对应助教账号表的 `nickname` / `real_name` |
### 4.4 时间与时长
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `createTime` | string | `"2025-11-09 19:23:29"` | 废除记录创建时间，即系统记录废除操作的时刻。格式 `YYYY-MM-DD HH:MM:SS` |
| `pdChargeMinutes` | int | `214` | 废除前已累计的计费时长，单位为**分钟**。`0` 表示刚排钟即撤销，尚未产生有效计费时间。注意：助教流水中类似字段（`real_use_seconds`）单位为秒 |
### 4.5 金额与原因
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `assistantAbolishAmount` | float | `5.83` | 助教废除金额（元/人民币），本次废除操作对应的金额数值。`0.0` 表示纯记录操作，未产生金额变动 |
| `trashReason` | string | `""` | 废除原因，自由文本字段。当前数据中全部为空字符串，说明系统允许不填原因。预留用于记录如"顾客临时取消""录入错误""更换助教"等说明 |
---
## 五、响应样例（单条记录）
```json
{
"siteProfile": {
"id": 2790685415443269,
"org_id": 2790684179467077,
"shop_name": "朗朗桌球",
"avatar": "https://oss.ficoo.vip/admin/hXcE4E_1752495052016.jpg",
"business_tel": "13316068642",
"full_address": "广东省广州市天河区丽阳街12号",
"address": "广东省广州市天河区天园街道朗朗桌球",
"longitude": 113.360321,
"latitude": 23.133629,
"tenant_site_region_id": 156440100,
"tenant_id": 2790683160709957,
"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": "A",
"attendance_enabled": 1,
"shop_status": 1
},
"createTime": "2025-11-09 19:23:29",
"id": 2957675849518789,
"siteId": 2790685415443269,
"tableAreaId": 2791963816579205,
"tableId": 2793016660660357,
"tableArea": "C区",
"tableName": "C1",
"assistantOn": "27",
"assistantName": "泡芙",
"pdChargeMinutes": 214,
"assistantAbolishAmount": 5.83,
"trashReason": ""
}
```
---
## 六、跨表关联
### 与助教流水（`assistant_service_records`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `assistantOn` | `assistantNo` | 助教编号 |
| `assistantName` | `assistantName` | 助教姓名 |
| `siteId` | `site_id` | 门店 ID |
| `tableId` | `site_table_id` | 台桌 ID |
> 本表**没有** `order_trade_no` 等硬外键字段，无法直接关联到具体哪条助教流水。需通过"门店 + 助教 + 台桌 + 相近时间"的组合条件做软匹配。助教流水中的 `is_trash` 字段从主流水视角标记"已废除"状态，本表则以"废除事件"为主视角记录明细。
### 与助教账号（`assistant_accounts_master`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `assistantOn` | `assistant_no` | 助教工号 |
| `assistantName` | `nickname` / `real_name` | 助教姓名 |
### 与台桌配置
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `tableId` | 台桌列表 `id` | 台桌主键 |
| `tableName` | 台桌列表 `table_name` | 台桌名称 |
| `tableAreaId` | 区域配置表主键 | 台桌区域 ID |
| `tableArea` | 区域配置表 `area_name` | 区域名称 |
### 与门店维度
`siteId` 与所有业务表的 `site_id` 一致，共享门店维度。`siteProfile` 为冗余快照。
<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/assistant_cancellation_records.md，按逻辑分组详解所有字段，含跨表关联
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
-->

304
apps/etl/pipelines/feiqiu/docs/api-reference/summary/assistant_service_records.md Normal file
View File

@@ -0,0 +1,304 @@
# 助教服务流水 — GetOrderAssistantDetails
> 模块：`AssistantPerformance` · ODS 表：`assistant_service_records` · 事实表（增量）
---
## 一、接口概述
查询门店在指定时间范围内的助教服务流水记录。每条记录对应一次助教服务明细（一位助教在一张桌上的一段服务），是助教业绩核算、薪资计算的核心数据源。
助教流水是事实表，通过 `order_trade_no` / `order_settle_id` 与结账记录、台费流水、小票详情等表关联，构成同一笔订单下的不同消费子项目。
| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /AssistantPerformance/GetOrderAssistantDetails` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | `page` + `limit`（最大 100） |
| 时间范围 | 必须（`startTime` / `endTime`） |
---
## 二、请求
### 请求体（JSON）
```json
{
"siteId": 2790685415443269,
"startTime": "2026-02-01 08:00:00",
"endTime": "2026-02-13 08:00:00",
"IsConfirm": 0,
"page": 1,
"limit": 100
}
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `siteId` | int | 是 | 门店 ID |
| `startTime` | string | 是 | 查询起始时间，格式 `YYYY-MM-DD HH:MM:SS` |
| `endTime` | string | 是 | 查询结束时间 |
| `IsConfirm` | int | 是 | 确认状态筛选。`0` = 全部，`1` = 待确认，`2` = 已确认 |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |
---
## 三、响应结构
```
{
"code": 200,
"data": {
"list": [ { ... }, { ... } ],
"total": 1200
}
}
```
`data.list` 中每个对象即为一条助教服务流水记录，共 64 个字段（含嵌套 `siteProfile` 对象），按逻辑分组说明如下。
---
## 四、响应字段详解（64 个字段）
### 4.1 订单与关联 ID
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `2957913441292165` | 助教流水记录主键 ID（流水唯一标识） |
| `order_trade_no` | int | `2957784612605829` | 订单交易号。与台费流水、商品销售、团购流水等表的同名字段一致，用于串联同一笔订单下的各类消费明细 |
| `order_settle_id` | int | `2957913171693253` | 订单结算 ID（结账单号）。与结账记录的 `id`、小票详情的 `orderSettleId` 对应 |
| `order_assistant_id` | int | `2957788717240005` | 订单中助教项目明细的内部 ID。同一订单有多条助教项目时（换助教、多时段），此字段唯一标识每条明细 |
| `order_assistant_type` | int | `1` | 助教服务类型枚举：`1` = 常规服务（基础课），`2` = 附加类服务（附加课）。与 `skillName` 对应 |
| `order_pay_id` | int | `0` | 关联支付记录的主键 ID。`0` = 无直接支付关联（通过结账记录间接关联） |
| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID，全表固定 |
| `site_id` | int | `2790685415443269` | 门店 ID |
| `site_assistant_id` | int | `2946266869435205` | 门店维度的助教 ID。与助教账号表的 `id` 对应，是助教档案的外键 |
| `user_id` | int | `2946266868976453` | 助教的系统用户账号 ID。与助教账号表的 `user_id` 一致，区别于岗位级的 `site_assistant_id` |
| `person_org_id` | int | `2946266869336901` | 助教所属人事组织/部门 ID。与助教账号表的 `person_org_id` 一致 |
| `assistant_team_id` | int | `2792011585884037` | 助教所属团队 ID。与助教账号表的 `team_id` 对应，用于排班/团队统计 |
| `tenant_member_id` | int | `0` | 商户维度会员 ID。`0` = 非会员；非零时与会员档案的 `id` 一致 |
| `system_member_id` | int | `0` | 系统级会员 ID（全集团统一）。与会员档案的 `system_member_id` 对应，用于跨门店/跨卡种串联 |
| `skill_id` | int | `2790683529513797` | 助教服务课程/技能 ID，对应课程配置表主键 |
### 4.2 助教维度
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `assistantNo` | string | `"27"` | 助教编号/工号。与助教账号表的 `assistant_no` 对应 |
| `assistantTeamName` | string | `"1组"` | 助教所属团队/组名称，与 `assistant_team_id` 对应的文本冗余字段 |
| `assistantName` | string | `"何海婷"` | 助教真实姓名。与助教账号表的 `real_name` 一致 |
| `nickname` | string | `"泡芙"` | 助教对外昵称（非顾客昵称）。在小票/商品名中常以"编号-昵称"组合出现（如 `ledger_name = "27-泡芙"`） |
| `assistant_level` | int | `10` | 助教等级枚举：`8` = 助教管理，`10` = 初级，`20` = 中级，`30` = 高级。与助教账号表的 `level` 对应 |
| `levelName` | string | `"初级"` | 助教等级名称，与 `assistant_level` 一一对应，展示用冗余字段 |
| `skillName` | string | `"基础课"` | 当前服务对应的课程/技能名称。`order_assistant_type=1` 时多为"基础课"，`=2` 时为"附加课" |
| `ledger_name` | string | `"27-泡芙"` | 台账显示名称，"编号-昵称"组合，用于报表和前端展示 |
| `ledger_group_name` | string | `""` | 助教项目所属计费分组/套餐分组名称，当前未使用 |
### 4.3 桌台与门店维度
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `tableName` | string | `"S1"` | 助教服务所在球台名称。与台桌列表的 `table_name` / `table_no` 对应 |
| `site_table_id` | int | `2793020259897413` | 球台 ID。对应台桌列表的 `id` |
| `siteProfile` | object | `{id, shop_name, ...}` | 门店信息快照（嵌套对象），包含 `id`、`shop_name`、`address`、`longitude`/`latitude` 等。与其他接口的 `siteProfile` 结构一致。**注意：此处 siteProfile 包含真实门店数据**（区别于结账记录中的空壳） |
### 4.4 时间与时长
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `create_time` | string | `"2025-11-09 23:25:11"` | 流水记录创建时间，接近结算/下单时间 |
| `start_use_time` | string | `"2025-11-09 21:18:18"` | 助教实际开始服务时间。正常情况下与 `ledger_start_time` 相同 |
| `last_use_time` | string | `"2025-11-09 23:24:50"` | 最后一次使用时间。正常结束时与 `ledger_end_time` 相同 |
| `ledger_start_time` | string | `"2025-11-09 21:18:18"` | 台账计费起始时间 |
| `ledger_end_time` | string | `"2025-11-09 23:24:50"` | 台账计费结束时间。`real_use_seconds=0` 时开始=结束，表示仅预约未实际服务 |
| `income_seconds` | int | `7560` | 计费秒数（应计收入对应时间）。值通常为 60 的倍数，配合 `ledger_unit_price` 计算应计金额 |
| `real_use_seconds` | int | `7592` | 实际使用时长（秒）。与 `ledger_count` 基本一致（±1 秒差）。`0` = 已预约但未消耗 |
| `ledger_count` | int | `7592` | 台账计时总秒数，即本条服务真正消耗的总时长 |
| `add_clock` | int | `0` | 加钟秒数（临时追加时长）。值为 60 的倍数，如 `600` = 10 分钟 |
| `returns_clock` | int | `0` | 退钟秒数（取消加钟或提前结束退回的时间）。当前未出现退钟场景 |
### 4.5 金额与折扣
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `ledger_unit_price` | float | `98.0` | 助教服务标准单价（每小时/每节课），如 98.0、108.0、190.0 |
| `ledger_amount` | float | `206.67` | 按标准单价计算的应收金额（近似 = `ledger_unit_price × income_seconds / 3600`），未扣除优惠 |
| `projected_income` | float | `168.0` | 实际结算计入门店的金额（已考虑折扣、卡权益、券等）。通常 `projected_income < ledger_amount` |
| `coupon_deduct_money` | float | `0.0` | 优惠券/代金券/团购券直接抵扣到本条助教服务的金额。与平台验券记录/团购流水联动 |
| `manual_discount_amount` | float | `0.0` | 收银员手动减免金额（人工改价） |
| `member_discount_amount` | float | `0.0` | 会员卡折扣产生的优惠金额。实际折扣可能已体现在 `projected_income` 与 `ledger_amount` 的差额中 |
| `service_money` | float | `0.0` | 平台预留的成本/分成字段，当前未启用 |
| `real_service_money` | number | `0.0` | 实际服务金额，扣除各类优惠后的助教服务实收金额 |
### 4.6 评价相关
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `skill_grade` | int | `0` | 顾客对技能表现的评分。`0` = 未评价 |
| `service_grade` | int | `0` | 顾客对服务态度的评分。`0` = 未评价 |
| `composite_grade` | float | `0.0` | 综合评分（技能+服务加权平均） |
| `sum_grade` | float | `0.0` | 累计评分总和，用于计算平均分 |
| `get_grade_times` | int | `0` | 被评价次数 |
| `grade_status` | int | `1` | 评价状态：`1` = 未评价/正常 |
| `composite_grade_time` | string | `"0001-01-01 00:00:00"` | 最近评价时间。`0001-01-01` = 无效占位（未评价） |
### 4.7 状态与标志位
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `ledger_status` | int | `1` | 流水记录状态：`1` = 正常有效。其他值可能对应"未结算""已作废" |
| `is_confirm` | int | `2` | 确认状态：`1` = 待确认，`2` = 已确认/已完成 |
| `is_single_order` | int | `1` | 是否单独订单结算：`1` = 单独结算，`0` = 与其他项目打包在综合订单中 |
| `is_not_responding` | int | `0` | 是否爽约/未响应：`0` = 正常，`1` = 有爽约 |
| `is_trash` | int | `0` | 是否已废除：`0` = 正常，`1` = 已废除（对应助教撤销记录表） |
| `is_delete` | int | `0` | 逻辑删除标志：`0` = 未删除，`1` = 已删除。与 `is_trash` 不同：`is_trash` 是业务废除，`is_delete` 是系统级删除 |
### 4.8 员工 / 销售人员
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `operator_id` | int | `2790687322443013` | 操作员 ID（录入/结算该服务的员工） |
| `operator_name` | string | `"收银员:郑丽珊"` | 操作员名称，含角色前缀 |
| `salesman_name` | string | `""` | 营业员/销售员姓名（提成归属），当前未配置 |
| `salesman_user_id` | int | `0` | 营业员用户 ID |
| `salesman_org_id` | int | `0` | 营业员所属组织/部门 ID |
### 4.9 作废 / 废除相关
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `trash_applicant_id` | int | `0` | 废除申请人员工 ID。`0` = 未发生废除 |
| `trash_applicant_name` | string | `""` | 废除申请人姓名 |
| `trash_reason` | string | `""` | 废除原因文本，如"顾客取消""录入错误"等 |
> 当 `is_trash = 1` 时，废除详情同时记录在助教撤销记录表（`assistant_cancellation_records`）中。
---
## 五、响应样例（单条记录）
```json
{
"assistantNo": "27",
"nickname": "泡芙",
"levelName": "初级",
"assistantName": "何海婷",
"tableName": "S1",
"siteProfile": {
"id": 2790685415443269,
"org_id": 2790684179467077,
"shop_name": "朗朗桌球",
"avatar": "https://oss.ficoo.vip/admin/hXcE4E_1752495052016.jpg",
"business_tel": "13316068642",
"full_address": "广东省广州市天河区丽阳街12号",
"address": "广东省广州市天河区天园街道朗朗桌球",
"longitude": 113.360321,
"latitude": 23.133629,
"tenant_site_region_id": 156440100,
"tenant_id": 2790683160709957,
"auto_light": 1,
"site_type": 1,
"site_label": "A",
"attendance_enabled": 1,
"shop_status": 1
},
"skillName": "基础课",
"id": 2957913441292165,
"order_trade_no": 2957784612605829,
"site_id": 2790685415443269,
"tenant_id": 2790683160709957,
"operator_id": 2790687322443013,
"operator_name": "收银员:郑丽珊",
"order_settle_id": 2957913171693253,
"ledger_name": "27-泡芙",
"ledger_unit_price": 98.0,
"ledger_count": 7592,
"ledger_amount": 206.67,
"create_time": "2025-11-09 23:25:11",
"assistant_level": 10,
"ledger_start_time": "2025-11-09 21:18:18",
"ledger_end_time": "2025-11-09 23:24:50",
"site_assistant_id": 2946266869435205,
"order_assistant_type": 1,
"site_table_id": 2793020259897413,
"projected_income": 168.0,
"income_seconds": 7560,
"real_use_seconds": 7592,
"is_confirm": 2,
"grade_status": 1
}
```
> 样例已精简，完整字段见 `samples/assistant_service_records.json`。
---
## 六、跨表关联
### 与助教账号（`assistant_accounts_master`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `site_assistant_id` | `id` | 助教主键（核心外键） |
| `user_id` | `user_id` | 系统用户 ID |
| `assistant_team_id` | `team_id` | 团队 ID |
| `person_org_id` | `person_org_id` | 人事组织 ID |
| `assistant_level` | `level` | 助教等级 |
> 助教流水是事实表，助教账号是对应的维表。
### 与结账记录（`settlement_records`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `order_settle_id` | `id` | 结账单号 |
| `order_trade_no` | `settleRelateId` | 交易号 |
> 结账记录中的 `assistantPdMoney` = 本表对应订单下 `ledger_amount` 的汇总。
### 与会员档案（`member_profiles`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `tenant_member_id` | `id` | 商户维度会员 ID |
| `system_member_id` | `system_member_id` | 系统级会员 ID |
### 与台桌（`site_tables_master`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `site_table_id` | `id` | 球台 ID |
### 与助教撤销记录（`assistant_cancellation_records`）
当 `is_trash = 1` 时，废除详情在撤销记录表中。`trash_reason`、`trash_applicant_id/name` 是废除信息在本表中的快照。
### 新增字段说明（相对旧版 JSON 样本）
| 字段 | 说明 |
|------|------|
| `assistantTeamName` | 助教团队名称（展示用） |
| `real_service_money` | 实际服务金额 |
<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-180000 — 上下文传递续接，继续 Phase 2 API 文档重构
- 直接原因: 按标杆文档格式重写 assistant_service_records 高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/assistant_service_records.md，64 个字段按 9 个逻辑分组详解，含时长计算说明、跨表关联
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
- 日期: 2026-02-14
- Prompt: P20260214-103000 — MD 占位符修正 + 临时文件清理
- 直接原因: v2 脚本自动插入的占位符描述需替换为正式中文业务说明
- 变更摘要: assistantTeamName 和 real_service_money 两个新字段的占位符描述替换为正式中文说明
- 风险与验证: 纯文档文案修正，无运行时影响；验证：grep "新发现字段" 本文件应返回 0 结果
-->

199
apps/etl/pipelines/feiqiu/docs/api-reference/summary/goods_stock_movements.md Normal file
View File

@@ -0,0 +1,199 @@
# 库存出入库流水 — QueryGoodsOutboundReceipt
> 模块：`GoodsStockManage` · ODS 表：`goods_stock_movements` · 事实表（增量）
---
## 一、接口概述
查询门店商品库存出入库流水明细，每条记录对应一次库存变动事件（销售出库、采购入库、盘点调整等）。包含变动前后库存数量、变动类型、操作员等信息。所有记录严格满足库存平衡公式：`endNum = startNum + changeNum`。支持双计量单位（主/副单位），当前门店仅使用主单位。
| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /GoodsStockManage/QueryGoodsOutboundReceipt` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | `page` + `limit`（最大 100） |
| 时间范围 | 需要（`startTime` / `endTime`） |
| 响应数据路径 | `data.queryDeliveryRecordsList` |
---
## 二、请求
### 请求体（JSON）
```json
{
"siteId": 2790685415443269,
"stockType": 0,
"startTime": "2026-02-01 08:00:00",
"endTime": "2026-02-13 08:00:00",
"page": 1,
"limit": 100
}
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `siteId` | int | 是 | 门店 ID |
| `stockType` | int | 是 | 库存变动类型筛选。`0` = 全部，`1` = 出库，`4` = 入库 |
| `startTime` | string | 是 | 查询起始时间，格式 `YYYY-MM-DD HH:MM:SS` |
| `endTime` | string | 是 | 查询结束时间，格式 `YYYY-MM-DD HH:MM:SS` |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |
---
## 三、响应结构
```
{
"code": 200,
"data": {
"list": [ { ... }, { ... } ],
"total": 100
}
}
```
`data.list` 中每个对象即为一条库存变动记录，共 19 个字段，按逻辑分组说明如下。
---
## 四、响应字段详解（19 个字段）
### 4.1 商品与库存标识
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `siteGoodsStockId` | int | `2957911857581957` | 库存记录主键 ID，每条变动记录唯一。同一商品可在不同批次/仓位产生多条记录 |
| `siteGoodsId` | int | `2793026183532613` | 门店商品 ID。对应门店商品档案（`store_goods_master`）的 `id`，也对应库存汇总的 `siteGoodsId` |
| `siteId` | int | `2790685415443269` | 门店 ID，与其他业务表一致 |
| `tenantId` | int | `2790683160709957` | 租户/品牌 ID，所有记录相同 |
| `goodsCategoryId` | int | `2790683528350539` | 一级分类 ID，对应分类树主键。约 5 个不同值 |
| `goodsSecondCategoryId` | int | `2790683528350540` | 二级分类 ID，对应分类树子节点。约 7 个不同值 |
### 4.2 商品基本信息
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `goodsName` | string | `"阿萨姆"` | 商品名称（当时的名称快照），与 `siteGoodsId` 一一对应 |
| `unit` | string | `"瓶"` | 库存计量单位。常见值：瓶、包、盒、根、个、桶、份 |
| `price` | float | `8.0` | 商品单价（静态快照），单位：元（人民币）。同一 `siteGoodsId` 的所有记录 `price` 一致，避免价格调整后历史记录无法还原 |
### 4.3 库存数量变动（主单位）
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `startNum` | int | `28` | 变动前库存数量 |
| `endNum` | int | `27` | 变动后库存数量。严格满足 `endNum = startNum + changeNum` |
| `changeNum` | int | `-1` | 本次变化量。负数 = 出库/减少，正数 = 入库/增加。`stockType=1` 时全为负数，`stockType=4` 时全为正数 |
### 4.4 库存数量变动（副单位，预留）
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `startNumA` | int | `0` | 副单位变动前库存（如箱/瓶双单位场景）。当前门店未启用，全部为 0 |
| `endNumA` | int | `0` | 副单位变动后库存，当前全部为 0 |
| `changeNumA` | int | `0` | 副单位变化量，当前全部为 0 |
### 4.5 变动类型
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `stockType` | int | `1` | 库存变动类型枚举：`1` = 出库（销售出库，`changeNum` 为负数），`4` = 入库/盘盈/调整增加（`changeNum` 为正数）。其他可能值（如报损、盘亏、退货等）当前样本未出现 |
### 4.6 操作与时间
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `createTime` | string | `"2025-11-09 23:23:34"` | 库存变动记录创建时间。可与小票时间、台费时间交叉校验。同一秒内可能有多条记录（同桌多商品一起销售） |
| `operatorName` | string | `"收银员:郑丽珊"` | 操作人。大部分为收银员（前台销售触发），个别为"系统"（自动盘点调整等） |
### 4.7 备注
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `remark` | string | `""` | 备注信息，用于手工记录变更原因（如"盘点差异调整""报损"）。当前全部为空 |
---
## 五、响应样例（单条记录）
```json
{
"siteGoodsStockId": 2957911857581957,
"siteGoodsId": 2793026183532613,
"siteId": 2790685415443269,
"tenantId": 2790683160709957,
"stockType": 1,
"goodsName": "阿萨姆",
"createTime": "2025-11-09 23:23:34",
"startNum": 28,
"endNum": 27,
"changeNum": -1,
"unit": "瓶",
"price": 8.0,
"operatorName": "收银员:郑丽珊",
"changeNumA": 0,
"startNumA": 0,
"endNumA": 0,
"remark": "",
"goodsCategoryId": 2790683528350539,
"goodsSecondCategoryId": 2790683528350540
}
```
---
## 六、跨表关联
### 与门店商品档案（`store_goods_master`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `siteGoodsId` | `id` | 门店商品 ID，关联商品基础信息、定价、库存快照 |
| `goodsCategoryId` | `goods_category_id` | 一级分类 ID |
| `goodsSecondCategoryId` | `goods_second_category_id` | 二级分类 ID |
### 与库存汇总（`goods_stock_summary`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `siteGoodsId` | `siteGoodsId` | 门店商品 ID。库存变动明细按 `siteGoodsId` + 时间范围聚合后即为库存汇总 |
> 结构关系：库存变动（明细表）→ 按 siteGoodsId + 时间范围聚合 → 库存汇总（汇总表）。
### 与门店销售记录（`store_goods_sales_records`）
- 当 `stockType = 1`（出库）时，对应销售记录中的商品销售行为
- 通过 `siteGoodsId` / `site_goods_id` 和 `createTime` / `create_time` 可在结构上对齐
### 与商品分类树（`stock_goods_category_tree`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `goodsCategoryId` | `id`（一级节点） | 一级分类主键 |
| `goodsSecondCategoryId` | `id`（二级节点） | 二级分类主键 |
### 与操作员维度
- `operatorName` 与其他流水（台费、助教、销售记录）中的 `operator_name` 一致，形成统一的操作员维度
<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/goods_stock_movements.md，按逻辑分组详解所有 19 个字段，含库存平衡公式说明和跨表关联
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
- 日期: 2026-02-14
- Prompt: P20260214-060000 / P20260214-061000 — 全量 JSON 刷新 + MD 文档补全 + 数据路径修正
- 直接原因: 旧 JSON 样本仅含单条记录，缺少条件性字段；api_registry.json 中 17 个 data_path 与实际不符
- 变更摘要: 新增「响应数据路径」行（记录 API 实际返回的数据路径）
- 风险与验证: 纯文档变更，无运行时影响；验证：python scripts/refresh_json_and_audit.py 输出 24/24 通过
-->

183
apps/etl/pipelines/feiqiu/docs/api-reference/summary/goods_stock_summary.md Normal file
View File

@@ -0,0 +1,183 @@
# 库存汇总报表 — GetGoodsStockReport
> 模块：`TenantGoods` · ODS 表：`goods_stock_summary` · 汇总事实表（按时间范围聚合）
---
## 一、接口概述
查询门店商品在指定时间范围内的库存汇总数据，每条记录对应一个门店商品在查询区间内的期初/期末库存、出入库数量、盘点调整、销售数量与金额的汇总。所有记录严格满足库存平衡公式：`rangeStartStock + rangeIn + rangeInventory + rangeOut = rangeEndStock`。是库存变动明细（`goods_stock_movements`）按商品维度 + 时间范围聚合后的结果。
| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /TenantGoods/GetGoodsStockReport` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | `page` + `limit`（最大 100） |
| 时间范围 | 需要（`startTime` / `endTime`） |
| 响应数据路径 | `data.list` |
---
## 二、请求
### 请求体（JSON）
```json
{
"siteId": 2790685415443269,
"startTime": "2026-02-01 08:00:00",
"endTime": "2026-02-13 08:00:00",
"page": 1,
"limit": 100
}
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `siteId` | int | 是 | 门店 ID |
| `startTime` | string | 是 | 查询起始时间，格式 `YYYY-MM-DD HH:MM:SS` |
| `endTime` | string | 是 | 查询结束时间，格式 `YYYY-MM-DD HH:MM:SS` |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |
---
## 三、响应结构
```
{
"code": 200,
"data": {
"list": [ { ... }, { ... } ],
"total": 161
}
}
```
`data.list` 中每个对象即为一条商品库存汇总记录，共 14 个字段，按逻辑分组说明如下。
---
## 四、响应字段详解（14 个字段）
### 4.1 商品主键与基本信息
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `siteGoodsId` | int | `3089190204491141` | 门店商品 ID，本表主键（每个 `siteGoodsId` 仅一条记录）。对应门店商品档案（`store_goods_master`）的 `id`，也对应库存变动的 `siteGoodsId` |
| `goodsName` | string | `"小合味道"` | 商品名称，冗余于门店商品档案的 `goods_name`，方便直接阅读汇总报表 |
| `goodsUnit` | string | `"桶"` | 计量单位，与门店商品档案的 `unit` 一致。常见值：包（59）、瓶（46）、个（17）、份（13）、根（10）、盒、杯、桶、盘、支等 |
### 4.2 分类维度
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `goodsCategoryId` | int | `2791941988405125` | 一级分类 ID，共 9 个不同值，与 `categoryName` 一一对应。对应分类树主键 |
| `goodsCategorySecondId` | int | `2793236829620037` | 二级分类 ID，共 14 个不同值。对应分类树子节点，名称需到分类表或门店商品档案中查询 |
| `categoryName` | string | `"零食"` | 一级分类名称（冗余展示字段）。枚举值共 9 个：零食、酒水、香烟、其他、雪糕、器材、小吃、槟榔、果盘 |
### 4.3 库存数量（查询区间）
> 库存平衡公式：`rangeStartStock + rangeIn + rangeInventory + rangeOut = rangeEndStock`
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `rangeStartStock` | int | `0` | 查询区间起始时刻的库存数量（期初库存） |
| `rangeEndStock` | int | `22` | 查询区间结束时刻的库存数量（期末库存） |
| `rangeIn` | int | `24` | 区间内入库数量汇总（正值），包括采购入库、调拨入库等 |
| `rangeOut` | int | `-2` | 区间内出库数量汇总，以**负数**表示（出库/销售扣减）。注意：直接做代数求和，无需取绝对值 |
| `rangeInventory` | int | `0` | 区间内盘点调整净变动量（盘盈 − 盘亏）。当前样本全部为 0（无盘点或盘点无净影响） |
### 4.4 实时库存快照
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `currentStock` | int | `22` | 导出时刻的实时库存数量。与 `rangeEndStock` 不一定相等——后者是查询区间结束瞬间的库存，前者是当前瞬间的库存。部分记录存在 1–4 的差值（区间后又发生了出入库） |
### 4.5 销量与销售金额
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `rangeSale` | int | `2` | 区间内销售数量汇总（售出多少"包/瓶/份"等）。与 `rangeOut` 绝对值大致一致（也可能有非销售出库如报损/调拨） |
| `rangeSaleMoney` | float | `16.0` | 区间内销售金额小计（按商品维度汇总），单位：元（人民币）。有销量时 `rangeSaleMoney / rangeSale ≈ sale_price`（门店商品档案中的销售单价） |
---
## 五、响应样例（单条记录）
```json
{
"siteGoodsId": 3089190204491141,
"goodsName": "小合味道",
"goodsUnit": "桶",
"goodsCategoryId": 2791941988405125,
"goodsCategorySecondId": 2793236829620037,
"rangeStartStock": 0,
"rangeEndStock": 22,
"rangeIn": 24,
"rangeOut": -2,
"rangeInventory": 0,
"rangeSale": 2,
"rangeSaleMoney": 16.0,
"currentStock": 22,
"categoryName": "零食"
}
```
---
## 六、跨表关联
### 与门店商品档案（`store_goods_master`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `siteGoodsId` | `id` | 门店商品 ID，关联商品基础信息（售价、成本、状态等） |
| `goodsName` | `goods_name` | 商品名称一致 |
| `goodsUnit` | `unit` | 计量单位一致 |
| `goodsCategoryId` | `goods_category_id` | 一级分类 ID |
| `goodsCategorySecondId` | `goods_second_category_id` | 二级分类 ID |
> 门店商品档案是静态维表，库存汇总是按时间范围聚合的衍生事实表。
### 与库存变动明细（`goods_stock_movements`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `siteGoodsId` | `siteGoodsId` | 门店商品 ID |
> 结构关系：库存变动明细（明细表）→ 按 `siteGoodsId` + 时间范围聚合 → 库存汇总（本表）。`rangeIn`、`rangeOut`、`rangeInventory` 分别对应明细中不同 `stockType` 的 `changeNum` 汇总。
### 与门店销售记录（`store_goods_sales_records`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `siteGoodsId` | `site_goods_id` | 门店商品 ID |
> 销售记录是每一条销售明细，库存汇总是按商品维度在时间段内的汇总。`rangeSale` 对应销售记录按商品聚合的 `ledger_count` 之和，`rangeSaleMoney` 对应 `ledger_amount` 之和。
### 与商品分类树（`stock_goods_category_tree`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `goodsCategoryId` | `id`（一级节点） | 一级分类主键 |
| `goodsCategorySecondId` | `id`（二级节点） | 二级分类主键 |
| `categoryName` | `category_name`（一级节点） | 一级分类名称 |
<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/goods_stock_summary.md，按逻辑分组详解所有 14 个字段，含库存平衡公式说明和跨表关联
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
- 日期: 2026-02-14
- Prompt: P20260214-060000 / P20260214-061000 — 全量 JSON 刷新 + MD 文档补全 + 数据路径修正
- 直接原因: 旧 JSON 样本仅含单条记录，缺少条件性字段；api_registry.json 中 17 个 data_path 与实际不符
- 变更摘要: 新增「响应数据路径」行（记录 API 实际返回的数据路径）
- 风险与验证: 纯文档变更，无运行时影响；验证：python scripts/refresh_json_and_audit.py 输出 24/24 通过
-->

243
apps/etl/pipelines/feiqiu/docs/api-reference/summary/group_buy_packages.md Normal file
View File

@@ -0,0 +1,243 @@
# 团购套餐定义 — QueryPackageCouponList
> 模块：`PackageCoupon` · ODS 表：`group_buy_packages` · 维度表（快照）
---
## 一、接口概述
查询门店下所有团购套餐的配置定义。每条记录对应一种团购套餐的规则定义，包括套餐名称、面值、有效期、每日可用时段、限定台区、状态等。本表是团购业务的核心维度表，被平台券核销记录和团购核销记录通过套餐 ID 引用。
| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /PackageCoupon/QueryPackageCouponList` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | `page` + `limit`（最大 100） |
| 时间范围 | 不需要（全量快照） |
---
## 二、请求
### 请求体（JSON）
```json
{
"areaId": [],
"commonShowStatus": 1,
"offlineCouponChannel": 0,
"systemGroupType": 1,
"page": 1,
"limit": 100
}
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `areaId` | array | 是 | 区域 ID 列表。空数组 = 全部 |
| `commonShowStatus` | int | 是 | 展示状态筛选。`1` = 展示中 |
| `offlineCouponChannel` | int | 是 | 线下券渠道筛选。`0` = 全部 |
| `systemGroupType` | int | 是 | 系统分组类型。`1` = 默认 |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |
---
## 三、响应结构
```
{
"code": 200,
"data": {
"list": [ { ... }, { ... } ],
"total": 17
}
}
```
`data.list` 中每个对象即为一条团购套餐定义记录，共 35 个字段，按 9 个逻辑分组说明如下。
---
## 四、响应字段详解（35 个字段）
### 4.1 基本信息与主键
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `2939215004469573` | 门店侧套餐 ID（主键）。平台验券记录中的 `group_package_id` 指向此 ID |
| `package_id` | int | `1814707240811572` | 上层/系统级套餐 ID。多个 `id` 不同的记录可共享同一 `package_id`（同一套餐在不同门店/版本下的本地配置） |
| `package_name` | string | `"早场特惠一小时"` | 团购套餐名称，用于前台展示和核销界面。示例：`"B区桌球一小时"`、`"中八、斯诺克包厢两小时"`、`"KTV欢唱四小时"` |
| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID |
| `site_id` | int | `2790685415443269` | 门店 ID |
| `site_name` | string | `"朗朗桌球"` | 门店名称，冗余展示字段 |
| `creator_name` | string | `"店长:郑丽珊"` | 创建人信息（角色:姓名），用于权限追踪 |
### 4.2 金额与时长
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `selling_price` | float | `0.0` | 团购售卖价（元）。当前全部为 `0.0`，实际售价可能在平台侧维护 |
| `coupon_money` | float | `0.0` | 券面值/内部结算面值（元）。如：早场一小时 = `40.0`，KTV 四小时 = `200.0`。核销时按此金额执行抵扣记账 |
| `duration` | int | `3600` | 套餐包含时长（秒）。`3600` = 1 小时，`7200` = 2 小时，`14400` = 4 小时 |
| `usable_count` | int | `9999999` | 可使用次数上限。`9999999` 为"无限次"哨兵值 |
### 4.3 有效期与日期限制
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `start_time` | string | `"2025-10-27 00:00:00"` | 套餐生效开始日期 |
| `end_time` | string | `"2026-10-28 00:00:00"` | 套餐失效日期。极大日期（如 `9999-12-31`）表示长期有效 |
| `date_type` | int | `1` | 日期限制类型。`1` = 通用（每天可用）。其他值可能表示工作日/周末/指定日期 |
| `date_info` | string | `""` | 细粒度日期信息（如具体日期列表），预留字段，当前基本为空 |
| `usable_range` | string | `""` | 可用日期范围文字描述（如"周一至周五"），当前未使用 |
### 4.4 每日时段限制
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `start_clock` | string | `"00:00:00"` | 每日可用起始时间（第一时段） |
| `end_clock` | string | `"1.00:00:00"` | 每日可用结束时间（第一时段）。`1.00:00:00` 格式为"天.时:分:秒"，表示跨日截止 |
| `add_start_clock` | string | `"00:00:00"` | 附加可用时段起始时间（第二时段），支持不连续时段（如早场+夜场） |
| `add_end_clock` | string | `"1.00:00:00"` | 附加可用时段结束时间。`1.00:00:00` = 跨午夜到次日凌晨 |
### 4.5 区域/台桌限制
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `area_tag_type` | int | `1` | 区域约束模式。`1` = 按台区标签限制 |
| `table_area_name` | string | `"A区"` | 套餐适用台区名称。示例：`"A区中八"`、`"B区中八"`、`"斯诺克"`、`"包厢"`、`"KTV"` |
| `table_area_id` | string | `"0"` | 单一台区 ID（已弃用，全部为 `"0"`） |
| `tenant_table_area_id` | string | `"0"` | 租户级台区 ID（已弃用，全部为 `"0"`） |
| `tenant_table_area_id_list` | string | `"2791960001957765"` | 租户台区配置 ID，实际起约束作用。指向台区分组表 |
| `table_area_id_list` | string | `""` | 具体台区 ID 列表（如 `"1,2,3"`），当前未使用 |
### 4.6 适用卡种
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `card_type_ids` | string | `"0"` | 适用会员卡类型 ID。`"0"` = 不限卡种 |
| `max_selectable_categories` | int | `0` | 最大可选分类数。`0` = 不限制 |
### 4.7 状态与类型
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `is_enabled` | int | `1` | 启用状态（配置层面）。`1` = 启用/上架，`2` = 停用/下架 |
| `is_delete` | int | `0` | 逻辑删除标记。`0` = 正常，`1` = 已删除 |
| `effective_status` | int | `1` | 动态有效状态。`1` = 有效（可核销），`3` = 已过期/失效 |
| `is_first_limit` | integer | `1` | 是否限制首次使用（1=不限制），控制套餐是否仅限新客首次核销 |
| `type` | int | `2` | 内部业务子类型。`1` 和 `2` 两种值，具体含义需结合系统配置 |
| `group_type` | int | `1` | 团购类型。`1` = 计时类/台费类套餐 |
| `system_group_type` | int | `1` | 系统团购类型。`1` = 券码类团购（需凭码核销） |
| `sort` | integer | `100` | 排序权重，用于前端套餐列表展示排序 |
### 4.8 关联 ID 与台区列表
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `tenantCouponSaleOrderItemId` | integer | `0` | 租户券销售订单项 ID，关联团购券的销售订单明细。`0` = 无关联 |
| `tableAreaNameList` | array | `["A区中八"]` | 适用台区名称列表，与 `tenantTableAreaIdList` 对应的文本展示 |
| `tenantTableAreaIdList` | array | `[2791960001957765]` | 适用租户台区 ID 列表，替代旧版单值字段 `tenant_table_area_id`，指向台区分组表 |
### 4.9 时间
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `create_time` | string | `"2025-10-27 18:24:09"` | 套餐创建时间 |
---
## 五、响应样例（单条记录）
```json
{
"site_name": "朗朗桌球",
"effective_status": 1,
"id": 2939215004469573,
"site_id": 2790685415443269,
"tenant_id": 2790683160709957,
"package_name": "早场特惠一小时",
"table_area_id": "0",
"table_area_name": "A区",
"selling_price": 0.0,
"duration": 3600,
"start_time": "2025-10-27 00:00:00",
"end_time": "2026-10-28 00:00:00",
"is_enabled": 1,
"is_delete": 0,
"type": 2,
"package_id": 1814707240811572,
"usable_count": 9999999,
"create_time": "2025-10-27 18:24:09",
"creator_name": "店长:郑丽珊",
"tenant_table_area_id": "0",
"table_area_id_list": "",
"tenant_table_area_id_list": "2791960001957765",
"start_clock": "00:00:00",
"end_clock": "1.00:00:00",
"add_start_clock": "00:00:00",
"add_end_clock": "1.00:00:00",
"date_info": "",
"date_type": 1,
"group_type": 1,
"usable_range": "",
"coupon_money": 0.0,
"area_tag_type": 1,
"system_group_type": 1,
"max_selectable_categories": 0,
"card_type_ids": "0"
}
```
---
## 六、跨表关联
### 与平台券核销记录（`platform_coupon_redemption_records`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `id` | `group_package_id` | 套餐 ID → 平台券关联的内部套餐（当前全部为 0，预留） |
### 与团购核销记录（`group_buy_redemption_records`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `id` | `promotion_coupon_id` | 套餐 ID → 核销流水中使用的套餐定义 |
| `duration` | `promotion_seconds` | 套餐标准时长，两表一致 |
> 结构链路：团购套餐定义 → 平台验券记录（券码与套餐 ID） → 团购核销记录（订单明细中的券使用记录）。
### 与台桌/台区配置
- `tenant_table_area_id_list`：与台区配置表中的台区组合 ID 关联
- `table_area_name`：与台区配置中的 `area_name` 含义一致
### 与门店维度
所有业务表的 `tenant_id`、`site_id` 一致，共享门店维度。
<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/group_buy_packages.md，按逻辑分组详解所有字段，含跨表关联
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
- 日期: 2026-02-14
- Prompt: P20260214-103000 — MD 占位符修正 + 临时文件清理
- 直接原因: v2 脚本自动插入的占位符描述需替换为正式中文业务说明；type 字段重复行需去除
- 变更摘要: is_first_limit、sort、tableAreaNameList、tenantCouponSaleOrderItemId、tenantTableAreaIdList 五个新字段占位符替换为正式说明；删除重复的 type 行
- 风险与验证: 纯文档文案修正，无运行时影响；验证：grep "新发现字段" 本文件应返回 0 结果
- 日期: 2026-02-14
- Prompt: P20260214-130000 — 25 个 API 文档归档至 summary/ + 字段分组修正
- 直接原因: 4.7"状态与类型"组过于臃肿，混入排序、台区列表、关联 ID 等非状态字段
- 变更摘要: 4.7 精简为纯状态/类型字段 + sort；新增 4.8"关联 ID 与台区列表"组（3 字段）；create_time 从 4.1 移至 4.9"时间"组
- 风险与验证: 纯文档分组调整，无运行时影响；验证：统计各组字段数总和 = 35
-->

285
apps/etl/pipelines/feiqiu/docs/api-reference/summary/group_buy_redemption_records.md Normal file
View File

@@ -0,0 +1,285 @@
# 团购核销记录 — GetSiteTableUseDetails
> 模块：`Site` · ODS 表：`group_buy_redemption_records` · 事实表（增量）
---
## 一、接口概述
查询团购券在门店台费上的使用明细流水。每条记录描述一张团购券被核销到某张球台的台费上，包含券码、套餐配置、抵扣金额与时长、关联订单与球台、促销拆账等信息。本表是"团购套餐定义 + 台费流水 + 平台券核销"之间的桥接事实表，将某张券、某个套餐配置、某个订单、某张桌、某段时间、某个金额绑定在一起。
| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /Site/GetSiteTableUseDetails` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | `page` + `limit`（最大 100） |
| 时间范围 | 需要（`startTime` / `endTime`） |
| 响应数据路径 | `data.siteTableUseDetailsList` |
---
## 二、请求
### 请求体（JSON）
```json
{
"siteId": 2790685415443269,
"offlineCouponChannel": 0,
"startTime": "2026-02-01 08:00:00",
"endTime": "2026-02-13 08:00:00",
"page": 1,
"limit": 100,
"queryType": 1
}
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `siteId` | int | 是 | 门店 ID |
| `offlineCouponChannel` | int | 是 | 线下券渠道筛选。`0` = 全部 |
| `startTime` | string | 是 | 查询起始时间 |
| `endTime` | string | 是 | 查询结束时间 |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |
| `queryType` | int | 是 | 查询类型。`1` = 默认 |
---
## 三、响应结构
```
{
"code": 200,
"data": {
"list": [ { ... }, { ... } ],
"total": 200
}
}
```
`data.list` 中每个对象即为一条团购核销流水记录，共 43 个字段，按 10 个逻辑分组说明如下。
---
## 四、响应字段详解（43 个字段）
### 4.1 台桌与门店维度
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `table_id` | int | `2793003705192517` | 球台 ID，对应台桌列表的 `id` |
| `tableName` | string | `"A17"` | 球台名称/台号。示例：`"A7"`、`"B1"`、`"斯1"`、`"麻1"` |
| `tableAreaName` | string | `"A区"` | 球台所属台区名称。枚举：`"A区"`、`"B区"`、`"斯诺克区"`、`"麻将房"` |
| `tenant_table_area_id` | int | `2791960001957765` | 租户级台区分组 ID，用于校验券的适用台区与实际台桌是否匹配 |
| `site_id` | int | `2790685415443269` | 门店 ID |
| `siteName` | string | `"朗朗桌球"` | 门店名称，冗余展示用 |
| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID |
### 4.2 订单与关联 ID
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `2957924029615941` | 团购核销流水记录主键 ID |
| `order_trade_no` | int | `2957858167230149` | 订单交易号，与台费流水、助教流水、小票详情等共用的订单主键 |
| `order_settle_id` | int | `2957922914357125` | 结算单 ID（小票结账主键），对应小票详情的 `orderSettleId` |
| `order_pay_id` | int | `0` | 支付记录 ID。`0` = 未关联具体支付记录 |
| `order_coupon_id` | int | `2957858168229573` | 订单中券使用记录 ID，与平台验券记录主键对应 |
| `coupon_origin_id` | int | `2957858168229573` | 平台/上游系统券记录主键 ID（券来源 ID）。当前与 `order_coupon_id` 完全相等 |
| `promotion_activity_id` | int | `2957858166460101` | 团购/促销活动 ID，对应平台或内部促销活动主键 |
| `promotion_coupon_id` | int | `2798727423528005` | 团购套餐定义 ID，对应 `group_buy_packages` 表的 `id` |
### 4.3 金额字段（核心）
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `ledger_unit_price` | float | `29.9` | 台费标准单价（元/小时）。已知值：`29.9`、`39.9`、`59.9`、`69.9`、`11.11`、`128.0` |
| `ledger_count` | int | `3600` | 本次券实际核销的计费秒数。大部分等于 `promotion_seconds`，少数略有差异 |
| `ledger_amount` | float | `48.0` | 本次券实际冲抵台费的金额（元）。绝大部分与 `coupon_money` 相等 |
| `coupon_money` | float | `48.0` | 本次核销时券在门店侧的可抵扣金额（元）。已知值：`48.0`、`58.0`、`68.0`、`96.0`、`116.0`、`288.0` |
| `goodsOptionPrice` | float | `0.0` | 商品规格价格，用于商品类促销分摊。当前未使用 |
### 4.4 时长字段
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `promotion_seconds` | int | `3600` | 团购套餐标准时长（秒）。枚举：`3600`（1 小时）、`7200`（2 小时）、`14400`（4 小时）。与套餐定义的 `duration` 一致 |
| `table_charge_seconds` | int | `3600` | 本次结算中球台总计费秒数。当券完全覆盖时等于 `ledger_count`；有多种计费组合时可能更大 |
### 4.5 促销拆账字段
> 按不同业务子模块预留的促销金额分摊字段。当前门店团购券仅用于抵扣台费，以下字段全部为 `0.0`。
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `table_service_promotion_money` | float | `0.0` | 分摊到台费服务费的促销金额（元） |
| `assistant_promotion_money` | float | `0.0` | 分摊到助教服务的促销金额（元） |
| `assistant_service_promotion_money` | float | `0.0` | 分摊到助教服务费的促销金额（元） |
| `goods_promotion_money` | float | `0.0` | 分摊到商品的促销金额（元） |
| `reward_promotion_money` | float | `0.0` | 奖励金/积分抵扣的促销金额（元） |
| `recharge_promotion_money` | float | `0.0` | 充值类优惠的分摊金额（元） |
### 4.6 券标识与渠道
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `coupon_code` | string | `"0107892475999"` | 团购券券码，核销时扫描/录入。与平台验券记录的 `coupon_code` 一致，串联全链路 |
| `order_coupon_channel` | int | `1` | 券渠道类型。`1` = 渠道 A，`2` = 渠道 B（具体平台需查系统配置） |
| `offer_type` | int | `1` | 优惠类型。`1` = 套餐券（当前唯一值） |
| `ledger_name` | string | `"全天A区中八一小时"` | 团购项目记账名称，通常来源于套餐定义的 `package_name` |
| `ledger_group_name` | string | `""` | 团购项目记账分组名称，当前未使用 |
### 4.7 状态与标志
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `ledger_status` | int | `1` | 流水状态。`1` = 正常有效 |
| `is_single_order` | int | `1` | 是否独立订单行。`1` = 独立条目结算，`0` = 嵌在组合结算中 |
| `is_delete` | int | `0` | 逻辑删除标记。`0` = 正常，`1` = 已删除 |
### 4.8 操作员与销售员
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `operator_id` | int | `2790687322443013` | 执行核销/结算操作的员工 ID |
| `operator_name` | string | `"收银员:郑丽珊"` | 操作员姓名（带职位前缀） |
| `salesman_user_id` | int | `0` | 营业员用户 ID。当前未启用 |
| `salesman_name` | string | `""` | 营业员姓名。当前未启用 |
| `salesman_role_id` | int | `0` | 营业员角色 ID。当前未启用 |
| `sales_man_org_id` | int | `0` | 营业员所属组织 ID。当前未启用 |
### 4.9 结算分摊金额
> 订单结算时按业务子模块拆分的实际分摊金额。与 4.5 "促销拆账字段"不同：4.5 是促销优惠的分摊，本组是实际收入的分摊。
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `table_share_money` | number | `39.9` | 台费分摊金额（元），核销券抵扣台费后的实际台费收入分摊 |
| `table_service_share_money` | number | `0.0` | 台费服务费分摊金额（元） |
| `assistant_share_money` | number | `0.0` | 助教分摊金额（元） |
| `assistant_service_share_money` | number | `0.0` | 助教服务费分摊金额（元） |
| `goods_share_money` | number | `0.0` | 商品分摊金额（元） |
| `good_service_share_money` | number | `0.0` | 商品服务费分摊金额（元） |
| `recharge_share_money` | number | `0.0` | 充值分摊金额（元） |
| `member_discount_money` | number | `0.0` | 会员折扣金额（元），会员卡权益产生的优惠抵扣 |
| `coupon_sale_id` | integer | `0` | 券销售记录 ID，关联团购券的销售订单。`0` = 无关联 |
### 4.10 时间
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `create_time` | string | `"2025-11-09 23:35:57"` | 流水创建时间（券核销时间，接近结账时间） |
---
## 五、响应样例（单条记录）
```json
{
"tableName": "A17",
"tableAreaName": "A区",
"siteName": "朗朗桌球",
"goodsOptionPrice": 0.0,
"id": 2957924029615941,
"order_trade_no": 2957858167230149,
"table_id": 2793003705192517,
"site_id": 2790685415443269,
"tenant_id": 2790683160709957,
"operator_id": 2790687322443013,
"operator_name": "收银员:郑丽珊",
"order_settle_id": 2957922914357125,
"ledger_name": "全天A区中八一小时",
"ledger_group_name": "",
"ledger_unit_price": 29.9,
"ledger_count": 3600,
"ledger_amount": 48.0,
"order_pay_id": 0,
"create_time": "2025-11-09 23:35:57",
"is_delete": 0,
"promotion_activity_id": 2957858166460101,
"promotion_coupon_id": 2798727423528005,
"is_single_order": 1,
"order_coupon_id": 2957858168229573,
"order_coupon_channel": 1,
"ledger_status": 1,
"promotion_seconds": 3600,
"coupon_origin_id": 2957858168229573,
"table_charge_seconds": 3600,
"offer_type": 1,
"coupon_money": 48.0,
"tenant_table_area_id": 2791960001957765,
"assistant_promotion_money": 0.0,
"assistant_service_promotion_money": 0.0,
"table_service_promotion_money": 0.0,
"goods_promotion_money": 0.0,
"reward_promotion_money": 0.0,
"recharge_promotion_money": 0.0,
"salesman_user_id": 0,
"salesman_name": "",
"salesman_role_id": 0,
"sales_man_org_id": 0,
"coupon_code": "0107892475999"
}
```
---
## 六、跨表关联
### 与团购套餐定义（`group_buy_packages`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `promotion_coupon_id` | `id` | 套餐定义 ID → 使用的是哪种团购套餐 |
> 通过此关联可获取套餐名称、标准时长、适用台区、每日可用时段等配置。`promotion_seconds` 与套餐定义的 `duration` 在结构上一致。
### 与平台券核销记录（`platform_coupon_redemption_records`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `coupon_code` | `coupon_code` | 券码，串联平台 → 核销 → 台费流水全链路 |
| `coupon_origin_id` / `order_coupon_id` | `id` | 平台券记录主键 |
### 与订单/小票相关表
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `order_trade_no` | `order_trade_no` | 订单号 → 同一笔结账中的台费、助教、商品等明细 |
| `order_settle_id` | `orderSettleId` | 结算单 ID → 小票详情 |
| `order_pay_id` | 支付记录 `id` | 支付流水 ID（非 0 时） |
### 与台桌维度/台区配置
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `table_id` | 台桌列表 `id` | 具体球台 |
| `tenant_table_area_id` | 套餐定义 `tenant_table_area_id_list` | 实际使用台区 ↔ 套餐允许台区，用于校验 |
### 与门店维度
所有业务表的 `tenant_id`、`site_id` 一致，共享门店维度。
<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/group_buy_redemption_records.md，43 个字段按 9 个逻辑分组详解，含跨表关联
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
- 日期: 2026-02-14
- Prompt: P20260214-060000 / P20260214-061000 — 全量 JSON 刷新 + MD 文档补全 + 数据路径修正
- 直接原因: 旧 JSON 样本仅含单条记录，缺少条件性字段；api_registry.json 中 17 个 data_path 与实际不符
- 变更摘要: 新增「响应数据路径」行；补全 2 个缺失字段（coupon_channel, coupon_remark）
- 风险与验证: 纯文档变更，无运行时影响；验证：python scripts/refresh_json_and_audit.py 输出 24/24 通过
- 日期: 2026-02-14
- Prompt: P20260214-130000 — 25 个 API 文档归档至 summary/ + 字段分组修正
- 直接原因: 4.9"时间"组混入 9 个非时间字段（分摊金额、券 ID、会员折扣），严重影响文档可读性
- 变更摘要: 新增 4.9"结算分摊金额"组（9 字段）和 4.10"时间"组；原 4.9 中 create_time 保留在时间组，其余字段按语义重新归类
- 风险与验证: 纯文档分组调整，无运行时影响；验证：统计各组字段数总和 = 43
-->

223
apps/etl/pipelines/feiqiu/docs/api-reference/summary/member_balance_changes.md Normal file
View File

@@ -0,0 +1,223 @@
# 会员余额变动 — GetMemberCardBalanceChange
> 模块：`MemberProfile` · ODS 表：`member_balance_changes` · 事实表（增量）
---
## 一、接口概述
查询会员卡余额变动明细，记录每一次充值、消费扣款、赠送、退款等导致卡内余额发生变化的事件。每条记录包含变动前后余额、变动金额、来源类型、支付方式、操作员等信息。本表是会员卡层面的"总账/明细账表"，严格满足 `after = before + account_data` 的余额恒等关系。
| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /MemberProfile/GetMemberCardBalanceChange` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | `page` + `limit`（最大 100） |
| 时间范围 | 需要（`startTime` / `endTime`） |
| 响应数据路径 | `data.tenantMemberCardLogs` |
---
## 二、请求
### 请求体（JSON）
```json
{
"startTime": "2026-02-01 08:00:00",
"endTime": "2026-02-13 08:00:00",
"fromType": 0,
"page": 1,
"limit": 100
}
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `startTime` | string | 是 | 查询起始时间 |
| `endTime` | string | 是 | 查询结束时间 |
| `fromType` | int | 是 | 来源类型筛选。`0` = 全部 |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |
---
## 三、响应结构
```
{
"code": 200,
"data": {
"list": [ { ... }, { ... } ],
"total": 200
}
}
```
`data.list` 中每个对象即为一条余额变更记录，共 25 个字段（含 3 个本金明细字段），按 8 个逻辑分组说明如下。
---
## 四、响应字段详解（25 个字段）
### 4.1 主键与关联 ID
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `2957881605869253` | 余额变更记录主键 ID，唯一标识一条余额变化事件 |
| `relate_id` | int | `2957881518788421` | 关联业务记录 ID。视 `from_type` 而定，可能对应充值记录 ID、订单结算单 ID、活动核销记录 ID 等。`0` = 无挂接业务单（如纯后台调整） |
| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID |
| `site_id` | int | `2790685415443269` | 余额变动发生的门店 ID。`0` = 跨门店/平台级操作（如活动抵用券退款） |
| `paySiteName` | string | `"朗朗桌球"` | 余额变更发生的门店名称（`site_id` 的冗余展示字段）。当 `site_id=0` 时为空字符串 |
| `register_site_id` | int | `2790685415443269` | 会员卡注册门店 ID（办卡所在门店），与 `site_id` 区分"办卡地"和"交易发生地" |
| `registerSiteName` | string | `"朗朗桌球"` | 卡片注册门店名称（`register_site_id` 的冗余展示字段） |
### 4.2 会员与会员卡维度
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `tenant_member_id` | int | `2799212845565701` | 租户内会员主键 ID。对应会员档案表的 `id` |
| `system_member_id` | int | `2799212844549893` | 系统级会员 ID（全局唯一） |
| `tenant_member_card_id` | int | `2799219999295237` | 会员卡账户 ID，指明本次变更针对哪一张卡。对应储值卡列表的 `id` |
| `card_type_id` | int | `2793249295533893` | 卡种类型 ID。枚举：`2793249295533893` = 储值卡，`2793266846533445` = 活动抵用券，`2794699703437125` = 酒水卡，`2791990152417157` = 台费卡 |
| `memberCardTypeName` | string | `"储值卡"` | 卡种名称，与 `card_type_id` 一一对应。枚举值：`"储值卡"`、`"活动抵用券"`、`"酒水卡"`、`"台费卡"` |
| `memberName` | string | `"曾丹烨"` | 会员姓名/称呼 |
| `memberMobile` | string | `"13922213242"` | 会员手机号 |
### 4.3 金额与余额（核心）
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `before` | float | `816.3` | 变动前卡账户余额（元） |
| `account_data` | float | `-120.0` | 本次变动金额（元）。正数 = 增加（充值/赠送），负数 = 减少（消费/退款） |
| `after` | float | `696.3` | 变动后卡账户余额（元）。恒等关系：`after = before + account_data` |
| `refund_amount` | float | `0.0` | 退款相关金额（元）。当前未使用，全部为 `0.0` |
### 4.4 变动来源与支付方式
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `from_type` | int | `1` | 变动来源类型（核心枚举）。`1` = 日常消费扣款（负数），`2` = 其他增加，`3` = 充值增加（正数，有外部支付），`4` = 调整/赠送增加（正数，后台发放），`7` = 充值退款（负数，remark 为"充值退款"），`9` = 活动抵用券余额冲减（负数，site_id=0） |
| `payment_method` | int | `0` | 支付方式。`0` = 内部结算/非外部支付（from_type=1/2/7/9），`3` = 赠送/后台调账渠道（from_type=4），`4` = 外部支付渠道（from_type=3，如扫码充值） |
### 4.5 操作员信息
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `operator_id` | int | `2790687322443013` | 执行本次余额变更操作的员工 ID |
| `operator_name` | string | `"收银员:郑丽珊"` | 操作员姓名（带职位前缀），如 `"收银员:郑丽珊"`、`"店长:谢晓洪"` |
### 4.6 状态与备注
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `is_delete` | int | `0` | 逻辑删除标记。`0` = 正常，`1` = 已逻辑删除。系统倾向"不可逆记账"，冲销通过反向变动实现 |
| `remark` | string | `""` | 备注。多数为空，`"充值退款"` 仅出现在 `from_type=7` 的记录上 |
### 4.7 本金明细
> 储值卡余额由"本金"和"赠送金"两部分组成。以下字段记录本金维度的变动，与 4.4 的总余额变动互补。
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `principal_before` | number | `2854.73` | 变动前本金余额（元） |
| `principal_data` | number | `-132.0` | 本金变动金额（元）。正数=增加，负数=减少 |
| `principal_after` | number | `2722.73` | 变动后本金余额（元）。恒等关系：`principal_after = principal_before + principal_data` |
### 4.8 时间
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `create_time` | string | `"2025-11-09 22:52:48"` | 余额变更记录创建时间，通常接近交易发生时间 |
---
## 五、响应样例（单条记录）
```json
{
"memberCardTypeName": "储值卡",
"paySiteName": "朗朗桌球",
"registerSiteName": "朗朗桌球",
"memberName": "曾丹烨",
"memberMobile": "13922213242",
"id": 2957881605869253,
"account_data": -120.0,
"after": 696.3,
"before": 816.3,
"card_type_id": 2793249295533893,
"create_time": "2025-11-09 22:52:48",
"from_type": 1,
"is_delete": 0,
"operator_id": 2790687322443013,
"operator_name": "收银员:郑丽珊",
"payment_method": 0,
"refund_amount": 0.0,
"register_site_id": 2790685415443269,
"relate_id": 2957881518788421,
"remark": "",
"site_id": 2790685415443269,
"system_member_id": 2799212844549893,
"tenant_id": 2790683160709957,
"tenant_member_card_id": 2799219999295237,
"tenant_member_id": 2799212845565701
}
```
---
## 六、跨表关联
### 与会员档案（`member_profiles`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `tenant_member_id` | `id` | 租户内会员主键 |
| `system_member_id` | `system_member_id` | 系统级会员 ID |
### 与储值卡列表（`member_stored_value_cards`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `tenant_member_card_id` | `id` | 卡账户 ID → 具体哪张卡 |
| `card_type_id` | `card_type_id` | 卡种类型 ID |
> 余额变更流水通过 `tenant_member_card_id` 指向具体卡账户，再通过 `card_type_id` 确定卡种。
### 与支付记录
充值类记录（`from_type=3`）的 `relate_id` 对应充值记录 ID，`payment_method` 与支付记录中的支付渠道枚举保持一致。
### 与订单/消费流水
消费扣款（`from_type=1`）和活动冲减（`from_type=9`）的 `relate_id` 对应订单/结算单/活动扣款单的主键，可与台费流水、助教流水、门店销售记录中的 `order_settle_id` 建立关系。
### 与门店维度
- `site_id` / `paySiteName`：交易发生门店
- `register_site_id` / `registerSiteName`：办卡门店
- 少数 `site_id=0` 的记录为平台级/活动结算场景
<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/member_balance_changes.md，按逻辑分组详解所有字段，含跨表关联
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
- 日期: 2026-02-14
- Prompt: P20260214-060000 / P20260214-061000 — 全量 JSON 刷新 + MD 文档补全 + 数据路径修正
- 直接原因: 旧 JSON 样本仅含单条记录，缺少条件性字段；api_registry.json 中 17 个 data_path 与实际不符
- 变更摘要: 新增「响应数据路径」行；补全 3 个缺失字段（cardtypename, principalbalance, tenantname）
- 风险与验证: 纯文档变更，无运行时影响；验证：python scripts/refresh_json_and_audit.py 输出 24/24 通过
- 日期: 2026-02-14
- Prompt: P20260214-130000 — 25 个 API 文档归档至 summary/ + 字段分组修正
- 直接原因: 4.8"时间"组混入 principal_after/principal_before/principal_data 三个本金字段
- 变更摘要: 新增 4.8"本金明细"组（3 字段）；原 4.8 时间组重编号为 4.9
- 风险与验证: 纯文档分组调整，无运行时影响；验证：统计各组字段数总和 = 25+3 = 28（含本金字段）
-->

210
apps/etl/pipelines/feiqiu/docs/api-reference/summary/member_consumption_statistics.md Normal file
View File

@@ -0,0 +1,210 @@
# 会员消费统计 — QueryMemberConsumptionStatistics
> 模块：`MemberProfile` · ODS 表：`member_consumption_statistics`（待建） · 统计汇总
---
## 一、接口概述
按门店维度统计会员卡的消费、充值、退款等金额汇总。可通过 `cardTypeId` 筛选特定卡种，不传则统计全部卡种。返回每个门店（含营销点）的资金流向汇总数据，用于财务对账和卡种经营分析。
| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /MemberProfile/QueryMemberConsumptionStatistics` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | page / limit |
| 时间范围 | `startTime` / `endTime` |
| 响应数据路径 | `data.memberConsumptionStatisticsList` |
---
## 二、请求
### 请求体（JSON）
```json
{
"cardTypeId": 2793249295533893,
"startTime": "2026-02-01 08:00:00",
"endTime": "2026-02-13 08:00:00",
"page": 1,
"limit": 100
}
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `cardTypeId` | int | 否 | 卡种 ID。不传则统计全部卡种 |
| `startTime` | string | 是 | 统计起始时间（含），格式 `YYYY-MM-DD HH:mm:ss` |
| `endTime` | string | 是 | 统计截止时间（不含），格式同上 |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |
---
## 三、响应结构
```
{
"code": 0,
"data": {
"total": 2,
"memberConsumptionStatisticsList": [
{
"siteId": ...,
"siteName": "...",
"siteType": 1,
"consumptionValue": ...,
...
}
]
}
}
```
`data.memberConsumptionStatisticsList` 为数组，每个元素代表一个门店/营销点的资金汇总。
---
## 四、响应字段详解（11 个字段）
### 4.1 门店标识
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `siteId` | int | `2790685415443269` | 门店 ID |
| `siteName` | string | `"朗朗桌球"` | 门店名称 |
| `siteType` | int | `1` | 门店类型：`1` = 实体门店，`3` = 总营销点 |
### 4.2 资金流向汇总
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `consumptionValue` | float | `-57791.25` | 消费金额合计（元）。负值表示消费支出 |
| `settleRefundValue` | float | `3349.41` | 结算退款金额合计（元） |
| `rechargeValue` | float | `50298.0` | 充值金额合计（元） |
| `systemSwitchingValue` | float | `0.0` | 系统转换/迁移金额（元）。跨卡种或跨系统转入转出 |
| `residueRechargeValue` | float | `0.0` | 剩余充值金额（元）。预留字段 |
| `reChargeRevokedValue` | float | `0.0` | 充值撤销金额（元） |
| `rechargeGiftValue` | float | `0.0` | 充值赠送金额（元） |
| `backendAdjustValue` | float | `0.0` | 后台人工调整金额（元） |
### 4.3 余额结果
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `restValue` | float | `-4143.84` | 期末余额/剩余值（元）。等于各项资金流入流出的净值 |
---
## 五、响应样例
### 指定 cardTypeId
```json
{
"data": {
"total": 2,
"memberConsumptionStatisticsList": [
{
"siteId": 2790685415443269,
"siteName": "朗朗桌球",
"siteType": 1,
"consumptionValue": -57791.25,
"settleRefundValue": 3349.41,
"rechargeValue": 50298.0,
"systemSwitchingValue": 0.0,
"residueRechargeValue": 0.0,
"reChargeRevokedValue": 0.0,
"rechargeGiftValue": 0.0,
"backendAdjustValue": 0.0,
"restValue": -4143.84
},
{
"siteId": 2928823574824965,
"siteName": "总营销点",
"siteType": 3,
"consumptionValue": 0.0,
"settleRefundValue": 0.0,
"rechargeValue": 0.0,
"systemSwitchingValue": 0.0,
"residueRechargeValue": 0.0,
"reChargeRevokedValue": 0.0,
"rechargeGiftValue": 0.0,
"backendAdjustValue": 0.0,
"restValue": 0.0
}
]
},
"code": 0
}
```
### 不传 cardTypeId（全部卡种）
```json
{
"data": {
"total": 2,
"memberConsumptionStatisticsList": [
{
"siteId": 2790685415443269,
"siteName": "朗朗桌球",
"siteType": 1,
"consumptionValue": -66877.46,
"settleRefundValue": 3885.79,
"rechargeValue": 50298.0,
"systemSwitchingValue": 15432.0,
"residueRechargeValue": 0.0,
"reChargeRevokedValue": 0.0,
"rechargeGiftValue": 0.0,
"backendAdjustValue": 0.0,
"restValue": 2738.33
},
{
"siteId": 2928823574824965,
"siteName": "总营销点",
"siteType": 3,
"consumptionValue": 0.0,
"settleRefundValue": 0.0,
"rechargeValue": 0.0,
"systemSwitchingValue": 0.0,
"residueRechargeValue": 0.0,
"reChargeRevokedValue": 0.0,
"rechargeGiftValue": 0.0,
"backendAdjustValue": 0.0,
"restValue": 0.0
}
]
},
"code": 0
}
```
---
## 六、跨表关联
| 关联表 | 关联字段 | 说明 |
|--------|----------|------|
| `member_stored_value_cards` | `cardTypeId` 对应卡种配置 | 按卡种筛选时的关联 |
| `member_balance_changes` | `siteId` + 时间范围 | 余额变动明细的汇总口径 |
| `recharge_settlements` | `siteId` + 时间范围 | 充值结算的汇总口径 |
| `settlement_records` | `siteId` + 时间范围 | 消费结算的汇总口径 |
### 金额校验关系
- `restValue` ≈ `rechargeValue` + `consumptionValue` + `settleRefundValue` + `systemSwitchingValue` + `residueRechargeValue` - `reChargeRevokedValue` + `rechargeGiftValue` + `backendAdjustValue`
- 注意 `consumptionValue` 为负值（支出方向）
<!--
AI_CHANGELOG:
- 日期: 2026-02-14
- Prompt: P20260214-083000 — 替换 role_area_association 为 member_consumption_statistics，获取 JSON 样本并撰写文档
- 直接原因: 用户要求用 QueryMemberConsumptionStatistics 替换 role_area_association，需新建 API 参考文档
- 变更摘要: 新建 member_consumption_statistics.md，含接口概述、请求参数、11 个响应字段详解、两种调用样例、跨表关联
- 风险与验证: 纯文档，无运行时影响；验证：对比 samples/member_consumption_statistics.json 确认字段覆盖完整
-->

203
apps/etl/pipelines/feiqiu/docs/api-reference/summary/member_profiles.md Normal file
View File

@@ -0,0 +1,203 @@
# 会员档案 — GetTenantMemberList
> 模块：`MemberProfile` · ODS 表：`member_profiles` · 维度表（快照）
---
## 一、接口概述
查询门店下所有会员的账户档案信息。每条记录对应一个"会员 × 卡种"级别的账户，包含会员身份、卡种类型、注册门店、积分/成长值、状态等。本表是会员维度的核心参照表，被消费流水、余额变更、储值卡等事实表通过 `system_member_id` 和 `id` 广泛引用。
| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /MemberProfile/GetTenantMemberList` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | `page` + `limit`（最大 100） |
| 时间范围 | 不需要（全量快照） |
| 响应数据路径 | `data.tenantMemberInfos` |
---
## 二、请求
### 请求体（JSON）
```json
{
"isMemberInBlackList": 0,
"status_Revoked": 0,
"isBindOrg": 0,
"registerSource": 0,
"page": 1,
"limit": 100
}
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `isMemberInBlackList` | int | 是 | 黑名单筛选。`0` = 全部 |
| `status_Revoked` | int | 是 | 注销状态筛选。`0` = 全部 |
| `isBindOrg` | int | 是 | 是否绑定组织筛选。`0` = 全部 |
| `registerSource` | int | 是 | 注册来源筛选。`0` = 全部 |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |
---
## 三、响应结构
```
{
"code": 200,
"data": {
"list": [ { ... }, { ... } ],
"total": 438
}
}
```
`data.list` 中每个对象即为一条会员账户档案记录，共 21 个字段，按 9 个逻辑分组说明如下。
---
## 四、响应字段详解（21 个字段）
### 4.1 主键与会员标识
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `2955204541320325` | 租户内会员账户主键 ID。对应一个会员在当前租户下某个卡种的账户档案。在余额变更表中对应 `tenant_member_id`，在储值卡列表中对应 `tenant_member_id` |
| `system_member_id` | int | `2955204540009605` | 系统级会员 ID，全平台唯一。用于将同一会员在不同门店/不同卡种下的账户统一到一个"人"的维度。与 `id` 是一对多关系（一人可有多张卡） |
### 4.2 卡种信息
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `member_card_grade_code` | int | `2790683528022853` | 会员卡种类/等级编码。枚举：`2790683528022853` = 储值卡，`2790683528022855` = 台费卡，`2790683528022856` = 活动抵用券，`2790683528022857` = 月卡 |
| `member_card_grade_name` | string | `"储值卡"` | 卡种名称，与 `member_card_grade_code` 一一对应。枚举值：`"储值卡"`、`"台费卡"`、`"活动抵用券"`、`"月卡"` |
### 4.3 联系方式与展示信息
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `mobile` | string | `"18620043391"` | 会员绑定手机号（11 位）。在同一租户下具备唯一性 |
| `nickname` | string | `"胡先生"` | 会员显示名称（可以是姓名或昵称）。注意与助教流水中的 `nickname`（助教昵称）区分 |
### 4.4 注册门店与租户
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `register_site_id` | int | `2790685415443269` | 会员注册门店 ID，与其他业务表的 `site_id` 一致 |
| `site_name` | string | `"朗朗桌球"` | 注册门店名称，冗余展示字段 |
| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID，所有记录相同 |
### 4.5 推荐关系与成长体系
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `referrer_member_id` | int | `0` | 推荐人会员 ID。`0` = 无推荐人。当前门店未启用推荐体系 |
| `point` | float | `0.0` | 当前积分余额。当前门店未启用积分体系 |
| `growth_value` | float | `0.0` | 成长值/经验值，用于会员等级晋升。当前门店未启用 |
### 4.6 状态字段
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `user_status` | int | `1` | 用户账号状态（用户逻辑层面）。`1` = 正常启用，`0` = 禁用/冻结 |
| `status` | int | `1` | 账户/卡档案状态。`1` = 正常，`4` = 失效/注销。与 `user_status` 分别管理用户层面和卡层面的状态 |
### 4.7 消费与充值统计
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `pay_money_sum` | number | `-12.79` | 累计消费金额（元）。负值表示支出方向 |
| `recharge_money_sum` | number | `5000.0` | 累计充值金额（元） |
### 4.8 组织归属与注册来源
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `person_tenant_org_id` | integer | `0` | 人事组织 ID。`0` = 未绑定组织 |
| `person_tenant_org_name` | string | `""` | 人事组织名称。为空时表示未绑定 |
| `register_source` | integer | `6` | 注册来源枚举。`6` = 小程序注册，其他值需结合系统配置 |
### 4.9 时间元数据
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `create_time` | string | `"2025-11-08 01:29:33"` | 会员账户创建时间。批量出现相同时间戳的记录通常是批量导入/迁移的结果 |
---
## 五、响应样例（单条记录）
```json
{
"id": 2955204541320325,
"create_time": "2025-11-08 01:29:33",
"member_card_grade_code": 2790683528022853,
"mobile": "18620043391",
"nickname": "胡先生",
"register_site_id": 2790685415443269,
"site_name": "朗朗桌球",
"member_card_grade_name": "储值卡",
"system_member_id": 2955204540009605,
"tenant_id": 2790683160709957,
"referrer_member_id": 0,
"point": 0.0,
"user_status": 1,
"status": 1,
"growth_value": 0.0
}
```
---
## 六、跨表关联
### 与储值卡列表（`member_stored_value_cards`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `id` | `tenant_member_id` | 会员账户主键 → 储值卡的持卡会员 ID |
| `system_member_id` | `system_member_id` | 系统级会员 ID，完全一致 |
| `member_card_grade_code` | `member_card_grade_code` | 卡种编码，可配套构成完整的卡种维度 |
### 与余额变更记录（`member_balance_changes`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `id` | `tenant_member_id` | 会员账户主键 → 余额变更的会员 ID |
| `system_member_id` | `system_member_id` | 系统级会员 ID |
### 与消费流水（台费、助教、商品等）
通过 `system_member_id` 将会员消费流水与会员档案关联。部分流水表中还有 `member_card_id` 或类似字段，对应本表的 `id`。
### 与门店维度
所有业务表的 `tenant_id`、`site_id` 一致，共享门店维度。`register_site_id` 与其他表的 `site_id` 引用同一门店 ID。
<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/member_profiles.md，按逻辑分组详解所有字段，含跨表关联
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
- 日期: 2026-02-14
- Prompt: P20260214-060000 / P20260214-061000 — 全量 JSON 刷新 + MD 文档补全 + 数据路径修正
- 直接原因: 旧 JSON 样本仅含单条记录，缺少条件性字段；api_registry.json 中 17 个 data_path 与实际不符
- 变更摘要: 新增「响应数据路径」行；补全 2 个缺失字段（person_tenant_org_id, person_tenant_org_name）
- 风险与验证: 纯文档变更，无运行时影响；验证：python scripts/refresh_json_and_audit.py 输出 24/24 通过
- 日期: 2026-02-14
- Prompt: P20260214-130000 — 25 个 API 文档归档至 summary/ + 字段分组修正
- 直接原因: 4.7"时间元数据"组混入 pay_money_sum/recharge_money_sum（消费统计）、person_tenant_org_id/name（组织归属）、register_source（注册来源）
- 变更摘要: 新增 4.7"消费与充值统计"（2 字段）、4.8"组织归属与注册来源"（3 字段）；原 4.7 时间组重编号为 4.9；字段总数从 15 更正为 21
- 风险与验证: 纯文档分组调整，无运行时影响；验证：统计各组字段数总和 = 21
-->

341
apps/etl/pipelines/feiqiu/docs/api-reference/summary/member_stored_value_cards.md Normal file
View File

@@ -0,0 +1,341 @@
# 会员储值卡 — GetTenantMemberCardList
> 模块：`MemberProfile` · ODS 表：`member_stored_value_cards` · 维度表（快照）
---
## 一、接口概述
查询门店下所有会员卡（储值卡/次卡/券类）的列表视图。每条记录对应一张已开通的具体会员卡，同时包含卡定义属性（卡种、折扣规则、适用范围）、当前余额、持卡会员快照、有效期与状态信息。虽然接口名为"储值卡列表"，实际涵盖五类卡：储值卡、活动抵用券、台费卡、酒水卡、月卡。
| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /MemberProfile/GetTenantMemberCardList` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | `page` + `limit`（最大 100） |
| 时间范围 | 不需要（全量快照） |
| 响应数据路径 | `data.tenantMemberCards` |
---
## 二、请求
### 请求体（JSON）
```json
{
"siteId": 2790685415443269,
"cardPhysicsType": 0,
"status": 0,
"page": 1,
"limit": 100
}
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `siteId` | int | 是 | 门店 ID |
| `cardPhysicsType` | int | 是 | 卡物理类型筛选。`0` = 全部 |
| `status` | int | 是 | 状态筛选。`0` = 全部 |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |
---
## 三、响应结构
```
{
"code": 200,
"data": {
"list": [ { ... }, { ... } ],
"total": 200
}
}
```
`data.list` 中每个对象即为一条会员卡记录，共 68 个字段，按逻辑分组说明如下。
---
## 四、响应字段详解（68 个字段）
### 4.1 卡主键与卡种信息
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `2955206162843781` | 会员卡账户主键 ID，唯一标识一张已开通的卡 |
| `card_type_id` | int | `2793266846533445` | 卡种 ID，定义"这是哪一种卡"。不同卡种对应不同的配置规则 |
| `member_card_grade_code` | int | `2790683528022856` | 卡等级/卡类代码。枚举：`2790683528022853` = 储值卡，`2790683528022855` = 台费卡，`2790683528022856` = 活动抵用券，`2790683528022857` = 月卡，`2790683528022858` = 酒水卡 |
| `member_card_grade_code_name` | string | `"活动抵用券"` | 卡等级/卡类名称，与 `member_card_grade_code` 一一对应 |
| `member_card_type_name` | string | `"活动抵用券"` | 卡类型名称，与 `member_card_grade_code_name` 一致，偏展示用的冗余字段 |
| `card_physics_type` | int | `1` | 物理卡类型。`1` = 实体卡/标准卡，其他值可能代表虚拟卡 |
| `card_no` | string | `""` | 实体卡物理卡号/条码号。当前全部为空（无物理卡号） |
| `bind_password` | string | `""` | 卡绑定密码，用于消费验证。当前未启用 |
| `use_scene` | string | `""` | 卡使用场景说明（如"仅店内使用"）。当前未使用 |
| `sort` | int | `1` | 前端展示排序权重 |
| `member_grade` | integer | `2790683528022856` | 卡等级 ID，标识该卡在卡种体系中的等级 |
### 4.2 持卡会员信息
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `member_name` | string/null | `"胡先生"` | 持卡会员姓名快照。`null` 表示未绑定会员 |
| `member_mobile` | string/null | `"18620043391"` | 持卡会员手机号快照。与 `member_name` 对应 |
| `system_member_id` | int | `2955204540009605` | 系统级会员 ID（跨门店统一主键）。`0` = 未绑定具体会员/散客卡 |
| `tenant_member_id` | int | `2955204541320325` | 租户内会员主键 ID。`0` = 未绑定会员。与会员档案表的 `id` 对应 |
### 4.3 门店与适用范围
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `site_name` | string | `"朗朗桌球"` | 卡归属门店名称，展示用 |
| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID |
| `register_site_id` | int | `2790685415443269` | 卡首次办理的门店 ID |
| `effect_site_id` | int | `0` | 卡片限定生效门店 ID。`0` 配合 `able_cross_site=1` 表示所有门店可用 |
| `able_cross_site` | int | `1` | 是否允许跨店使用。`1` = 可跨门店，`0` = 仅限开卡门店 |
| `tenantName` | string | `""` | 租户/品牌名称，当前未配置 |
| `tenantAvatar` | string | `""` | 品牌头像 URL，当前未配置 |
### 4.4 余额与面额
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `balance` | float | `0.0` | 当前卡内余额（元）。对储值卡为实际余额，对券类卡为剩余额度 |
| `denomination` | float | `0.0` | 面额/初始储值额度（元）。当前未填充，可能在卡种配置表中维护 |
### 4.5 折扣规则 — 折扣百分比
> 采用"几折"记法：`10` = 不打折，`9` = 九折，`8` = 八折。当前所有卡的折扣均为 `10.0`（无折扣）。
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `table_discount` | float | `10.0` | 台费折扣 |
| `table_service_discount` | float | `10.0` | 台费服务费折扣 |
| `goods_discount` | float | `10.0` | 商品折扣 |
| `goods_service_discount` | float | `10.0` | 商品服务费折扣 |
| `assistant_discount` | float | `10.0` | 助教费折扣 |
| `assistant_service_discount` | float | `10.0` | 助教服务费折扣 |
| `assistant_reward_discount` | float | `10.0` | 助教奖励金折扣 |
| `coupon_discount` | float | `10.0` | 优惠券折扣 |
### 4.6 折扣规则 — 折扣叠加开关
> 控制折扣是否与其他折扣叠加。`1` = 叠加，`2` = 不叠加（仅用卡折扣）。当前全部为 `2`。
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `table_discount_sub_switch` | int | `2` | 台费折扣叠加开关 |
| `goods_discount_sub_switch` | int | `2` | 商品折扣叠加开关 |
| `assistant_discount_sub_switch` | int | `2` | 助教折扣叠加开关 |
| `assistant_reward_discount_sub_switch` | int | `2` | 助教奖励金折扣叠加开关 |
| `goods_discount_range_type` | int | `1` | 商品折扣范围类型 |
### 4.7 折扣规则 — 抵扣比例（%）
> 允许从卡余额中抵扣的比例。`100.0` = 允许 100% 用卡支付，`0` = 不允许抵扣。当前全部为 `100.0`。
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `table_deduct_radio` | float | `100.0` | 台费抵扣比例 |
| `table_service_deduct_radio` | float | `100.0` | 台费服务费抵扣比例 |
| `goods_deduct_radio` | float | `100.0` | 商品抵扣比例 |
| `goods_service_deduct_radio` | float | `100.0` | 商品服务费抵扣比例 |
| `assistant_deduct_radio` | float | `100.0` | 助教费抵扣比例 |
| `assistant_service_deduct_radio` | float | `100.0` | 助教服务费抵扣比例 |
| `assistant_reward_deduct_radio` | float | `100.0` | 助教奖励金抵扣比例 |
| `coupon_deduct_radio` | float | `100.0` | 优惠券抵扣比例 |
### 4.8 折扣规则 — 扣卡金额配置
> 针对不同消费场景的固定扣卡金额配置。当前全部为 `0.0`（未启用固定扣卡规则）。
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `cardSettleDeduct` | float | `0.0` | 结算时扣卡金额上限/规则配置 |
| `tableCardDeduct` | float | `0.0` | 台费扣卡金额 |
| `tableServiceCardDeduct` | float | `0.0` | 台费服务金扣卡金额 |
| `goodsCarDeduct` | float | `0.0` | 商品扣卡金额 |
| `goodsServiceCardDeduct` | float | `0.0` | 商品服务金扣卡金额 |
| `assistantCardDeduct` | float | `0.0` | 助教扣卡金额 |
| `assistantServiceCardDeduct` | float | `0.0` | 助教服务金扣卡金额 |
| `assistantRewardCardDeduct` | float | `0.0` | 助教奖励金扣卡金额 |
| `couponCardDeduct` | float | `0.0` | 券额度扣卡金额 |
| `deliveryFeeDeduct` | float | `0.0` | 配送费扣卡金额 |
### 4.9 适用范围扩展（列表型）
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `tableAreaId` | array | `[]` | 限定可使用的台区 ID 列表。空 = 不限制台区 |
| `goodsCategoryId` | array | `[]` | 可用的商品分类 ID 列表。空 = 所有商品分类有效 |
| `pdAssisnatLevel` | array | `[]` | 允许使用的陪打/助教等级列表。空 = 不限制 |
| `cxAssisnatLevel` | array | `[]` | 促销活动中的助教等级限制列表。空 = 不限制 |
### 4.10 有效期与时间
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `create_time` | string | `"2025-11-08 01:31:12"` | 卡片创建时间（开卡时间） |
| `start_time` | string | `"2025-11-08 01:31:12"` | 卡片生效开始时间 |
| `end_time` | string | `"2225-01-01 00:00:00"` | 卡片有效期结束时间。远未来日期表示长期有效 |
| `disable_start_time` | string | `"0001-01-01 00:00:00"` | 停用窗口起始时间。`0001-01-01` = 未启用停用 |
| `disable_end_time` | string | `"0001-01-01 00:00:00"` | 停用窗口结束时间。`0001-01-01` = 未启用停用 |
| `last_consume_time` | string | `"2025-11-09 07:48:23"` | 最近一次消费时间。`1970-01-01 00:00:00` = 从未消费 |
### 4.11 卡状态与标志
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `status` | int | `1` | 卡当前状态。`1` = 正常可用，`4` = 过期/停用/作废 |
| `is_delete` | int | `0` | 逻辑删除标记。`0` = 未删除，`1` = 已逻辑删除 |
| `is_allow_give` | int | `0` | 是否允许转赠。`0` = 不允许，`1` = 允许转赠 |
| `is_allow_order_deduct` | int | `0` | 是否允许订单层面统一扣款。`0` = 不允许（仅按项目扣卡），`1` = 允许整单抵扣 |
| `able_share_member_discount` | integer | `1` | 是否共享会员折扣（1=是） |
### 4.12 电费折扣与抵扣
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `electricity_discount` | number | `10.0` | 电费折扣（几折记法，10=不打折） |
| `electricity_deduct_radio` | number | `100.0` | 电费抵扣比例（%），100=允许全额抵扣 |
| `electricitycarddeduct` | number | `0.0` | 电费卡扣金额（API 返回时字段名可能为 `electricityCardDeduct`，实际为同一字段） |
### 4.13 余额扩展
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `principal_balance` | number | `0.0` | 本金余额（元），区分于赠送余额 |
| `rechargefreezebalance` | number | `0.0` | 充值冻结余额（元）（API 返回时字段名可能为 `rechargeFreezeBalance`，实际为同一字段） |
---
## 五、响应样例（单条记录）
```json
{
"site_name": "朗朗桌球",
"member_name": "胡先生",
"member_mobile": "18620043391",
"member_card_type_name": "活动抵用券",
"table_service_discount": 10.0,
"assistant_service_discount": 10.0,
"coupon_discount": 10.0,
"goods_service_discount": 10.0,
"is_allow_give": 0,
"able_cross_site": 1,
"cardSettleDeduct": 0.0,
"tenantAvatar": "",
"tenantName": "",
"member_card_grade_code_name": "活动抵用券",
"table_discount_sub_switch": 2,
"tableAreaId": [],
"goods_discount_sub_switch": 2,
"goodsCategoryId": [],
"assistant_discount_sub_switch": 2,
"pdAssisnatLevel": [],
"assistant_reward_discount_sub_switch": 2,
"cxAssisnatLevel": [],
"goods_discount_range_type": 1,
"use_scene": "",
"balance": 0.0,
"table_deduct_radio": 100.0,
"table_service_deduct_radio": 100.0,
"goods_deduct_radio": 100.0,
"goods_service_deduct_radio": 100.0,
"assistant_deduct_radio": 100.0,
"assistant_service_deduct_radio": 100.0,
"assistant_reward_deduct_radio": 100.0,
"coupon_deduct_radio": 100.0,
"tableCardDeduct": 0.0,
"tableServiceCardDeduct": 0.0,
"goodsCarDeduct": 0.0,
"goodsServiceCardDeduct": 0.0,
"assistantCardDeduct": 0.0,
"assistantServiceCardDeduct": 0.0,
"assistantRewardCardDeduct": 0.0,
"couponCardDeduct": 0.0,
"deliveryFeeDeduct": 0.0,
"is_allow_order_deduct": 0,
"id": 2955206162843781,
"assistant_discount": 10.0,
"assistant_reward_discount": 10.0,
"bind_password": "",
"card_no": "",
"card_physics_type": 1,
"card_type_id": 2793266846533445,
"create_time": "2025-11-08 01:31:12",
"denomination": 0.0,
"disable_end_time": "0001-01-01 00:00:00",
"disable_start_time": "0001-01-01 00:00:00",
"effect_site_id": 0,
"end_time": "2225-01-01 00:00:00",
"goods_discount": 10.0,
"is_delete": 0,
"last_consume_time": "2025-11-09 07:48:23",
"member_card_grade_code": 2790683528022856,
"register_site_id": 2790685415443269,
"sort": 1,
"start_time": "2025-11-08 01:31:12",
"status": 1,
"system_member_id": 2955204540009605,
"table_discount": 10.0,
"tenant_id": 2790683160709957,
"tenant_member_id": 2955204541320325
}
```
---
## 六、跨表关联
### 与会员档案（`member_profiles`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `tenant_member_id` | `id` | 租户内会员主键 |
| `system_member_id` | `system_member_id` | 系统级会员 ID |
> 卡与会员是多对一关系：一个会员可持有多张不同类型的卡。
### 与余额变更记录（`member_balance_changes`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `id` | `tenant_member_card_id` | 卡账户 ID → 余额变更针对的具体卡 |
| `card_type_id` | `card_type_id` | 卡种类型 ID |
> 本表记录"当前余额"和规则配置；余额变更表记录每次充值/消费的明细流水。
### 与消费流水（台费、助教、商品等）
折扣/抵扣规则字段（`table_discount`、`goods_deduct_radio` 等）在消费结算时被引用，消费流水中对应 `coupon_deduct_money`、`member_discount_amount` 等字段体现实际扣卡结果。
### 与门店/台区维度
- `register_site_id` / `site_name`：与门店档案关联
- `tableAreaId`：理论上可与台桌区域表关联（当前为空，不限制台区）
<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/member_stored_value_cards.md，68 个字段按 11 个逻辑分组详解，含跨表关联
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
- 日期: 2026-02-14
- Prompt: P20260214-060000 / P20260214-061000 — 全量 JSON 刷新 + MD 文档补全 + 数据路径修正
- 直接原因: 旧 JSON 样本仅含单条记录，缺少条件性字段；api_registry.json 中 17 个 data_path 与实际不符
- 变更摘要: 新增「响应数据路径」行；补全 7 个缺失字段（assistantcarddeduct, cardsettlededuct 等）
- 风险与验证: 纯文档变更，无运行时影响；验证：python scripts/refresh_json_and_audit.py 输出 24/24 通过
- 日期: 2026-02-14
- Prompt: P20260214-103000 — MD 占位符修正 + 临时文件清理
- 直接原因: electricityCardDeduct/rechargeFreezeBalance 为已有小写字段的驼峰变体，需合并去重
- 变更摘要: 删除 electricityCardDeduct/rechargeFreezeBalance 重复行，在已有小写字段说明中标注 API 返回大小写不固定
- 风险与验证: 纯文档文案修正，无运行时影响；验证：grep "新发现字段" 本文件应返回 0 结果
-->

158
apps/etl/pipelines/feiqiu/docs/api-reference/summary/payment_transactions.md Normal file
View File

@@ -0,0 +1,158 @@
# 支付流水 — GetPayLogListPage
> 模块：`PayLog` · ODS 表：`payment_transactions` · 事实表（增量）
---
## 一、接口概述
查询门店下的支付成功流水。每条记录对应一笔已完成的支付交易（资金正向流入），通过 `relate_type` + `relate_id` 组合关联到不同业务实体（结账单、会员卡充值等）。本表是"统一支付网关"设计的体现，与退款流水（`refund_transactions`）共用枚举体系，可 UNION 构建统一资金流水视图。
| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /PayLog/GetPayLogListPage` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | `page` + `limit`（最大 100） |
| 时间范围 | `StartPayTime` / `EndPayTime`（必填） |
---
## 二、请求
### 请求体（JSON）
```json
{
"StartPayTime": "2025-11-01 08:00:00",
"EndPayTime": "2025-11-10 08:00:00",
"siteId": 2790685415443269,
"OnlinePayChannel": 0,
"paymentMethod": 0,
"relateType": 0,
"page": 1,
"limit": 100
}
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `StartPayTime` | string | 是 | 支付起始时间 |
| `EndPayTime` | string | 是 | 支付结束时间 |
| `siteId` | int | 是 | 门店 ID |
| `OnlinePayChannel` | int | 是 | 在线支付渠道筛选。`0` = 全部 |
| `paymentMethod` | int | 是 | 支付方式筛选。`0` = 全部 |
| `relateType` | int | 是 | 关联业务类型筛选。`0` = 全部 |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |
---
## 三、响应结构
```
{
"code": 200,
"data": {
"list": [ { ... }, { ... } ],
"total": 200
}
}
```
`data.list` 中每个对象即为一条支付流水记录，共 11 个字段（含嵌套 `siteProfile`），按逻辑分组说明如下。
---
## 四、响应字段详解（11 个字段）
### 4.1 主键与门店
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `3092712422508741` | 支付流水记录主键 ID |
| `site_id` | int | `2790685415443269` | 门店 ID |
| `siteProfile` | object | `{...}` | 门店信息快照（冗余），结构与其他接口一致，不再逐字段展开 |
### 4.2 业务关联
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `relate_type` | int | `2` | 关联业务类型枚举。`1` = 其他业务类型（预留，当前少见）；`2` = 结账单支付（`relate_id` 对应结账记录 `settleList.id`）；`5` = 会员卡充值/账户操作支付（`relate_id` 对应充值业务单号） |
| `relate_id` | int | `3092711340902597` | 关联业务记录的主键 ID，按 `relate_type` 不同指向不同表。结构上允许同一 `relate_id` 对应多条支付记录（组合支付场景） |
### 4.3 金额与时间
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `pay_amount` | float | `0.0` | 支付金额（元/人民币）。`0.0` 表示该支付方式参与了本单但实际金额由其他渠道/卡券承担（0 元支付记录在结构上合法且大量存在） |
| `create_time` | string | `"2026-02-13 04:49:48"` | 支付记录创建时间 |
| `pay_time` | string | `"2026-02-13 04:49:48"` | 支付完成时间。当前数据中与 `create_time` 多数一致；异步支付场景下二者可能不同 |
### 4.4 支付状态与渠道
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `pay_status` | int | `2` | 支付状态枚举。`2` = 支付成功/已完成。当前导出仅包含成功状态的记录 |
| `payment_method` | int | `4` | 支付方式枚举。已知值：`2`（某种线上支付渠道）、`4`（另一种支付方式）。具体映射需参考系统支付方式配置表 |
| `online_pay_channel` | int | `0` | 线上支付渠道枚举。`0` = 线下/默认渠道。其他值（如 `1` 微信、`2` 支付宝）当前未出现。预留字段 |
---
## 五、响应样例（单条记录）
```json
{
"siteProfile": { "id": 2790685415443269, "shop_name": "朗朗桌球", "..." : "..." },
"create_time": "2026-02-13 04:49:48",
"pay_amount": 0.0,
"pay_status": 2,
"pay_time": "2026-02-13 04:49:48",
"online_pay_channel": 0,
"relate_type": 2,
"relate_id": 3092711340902597,
"site_id": 2790685415443269,
"id": 3092712422508741,
"payment_method": 4
}
```
---
## 六、跨表关联
### 与结账记录（`settlement_records`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `relate_id`（当 `relate_type = 2`） | `settleList.id` | 结账单 ID |
> 通过此关联，支付记录间接连接到台费/助教/商品明细（结账记录 → 各类明细表的 `order_settle_id`）。
### 与退款流水（`refund_transactions`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `relate_type` + `relate_id` | `relate_type` + `relate_id` | 通过共同指向同一业务实体间接关联 |
| `payment_method` | `payment_method` | 共用支付方式枚举 |
> 支付记录 `pay_amount` 为正数（进账），退款记录 `pay_amount` 为负数（出账）。两者可 UNION 构建统一资金流水视图。
### 与会员卡流水
当 `relate_type = 5` 时，`relate_id` 对应会员卡流水中的 `relate_id`（充值业务单号），可追踪充值金额和卡账户变动。
### 与门店维度
`site_id` 与所有业务表一致。`siteProfile` 为冗余快照。
<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/payment_transactions.md，按逻辑分组详解所有字段，含跨表关联
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
-->

205
apps/etl/pipelines/feiqiu/docs/api-reference/summary/platform_coupon_redemption_records.md Normal file
View File

@@ -0,0 +1,205 @@
# 平台券核销记录 — GetOfflineCouponConsumePageList
> 模块：`Promotion` · ODS 表：`platform_coupon_redemption_records` · 事实表（增量）
---
## 一、接口概述
查询第三方团购平台（如美团等）券在门店被核销使用的流水记录。每条记录对应一次平台券的核销事件，包含券码、平台产品信息、售价与面值、核销状态、关联订单与球台、操作员等。本表是"外部平台 → 券 → 门店订单 → 台桌"完整链路的关键节点。
| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /Promotion/GetOfflineCouponConsumePageList` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | `page` + `limit`（最大 100） |
| 时间范围 | 需要（`startTime` / `endTime`） |
---
## 二、请求
### 请求体（JSON）
```json
{
"couponChannel": 0,
"startTime": "2026-02-01 08:00:00",
"endTime": "2026-02-13 08:00:00",
"siteId": 2790685415443269,
"couponUseStatus": 0,
"page": 1,
"limit": 100
}
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `couponChannel` | int | 是 | 优惠券渠道筛选。`0` = 全部 |
| `startTime` | string | 是 | 查询起始时间 |
| `endTime` | string | 是 | 查询结束时间 |
| `siteId` | int | 是 | 门店 ID |
| `couponUseStatus` | int | 是 | 使用状态筛选。`0` = 全部 |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |
---
## 三、响应结构
```
{
"code": 200,
"data": {
"list": [ { ... }, { ... } ],
"total": 200
}
}
```
`data.list` 中每个对象即为一条平台券核销记录，共 26 个字段，按逻辑分组说明如下。
---
## 四、响应字段详解（26 个字段）
### 4.1 主键与门店/租户
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `3092405812332869` | 平台验券记录主键 ID（分布式 ID） |
| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID |
| `site_id` | int | `2790685415443269` | 门店 ID |
### 4.2 门店信息快照
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `siteProfile` | object | `{...}` | 门店信息快照对象，包含 `id`（站点 ID）、`org_id`（组织 ID）、`shop_name`（门店名称）、`business_tel`（门店电话）、`full_address`（完整地址）、`longitude`/`latitude`（经纬度）、`auto_light`（自动控灯，`1`=是）、`attendance_enabled`（考勤，`1`=启用）、`shop_status`（`1`=营业中）等子字段 |
### 4.3 券身份与平台信息
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `coupon_code` | string | `"0108919359400"` | 券码，顾客出示的团购券编号。业务唯一键，可作为查询/去重索引 |
| `coupon_name` | string | `"【全天可用】中八桌球一小时（大厅A区）"` | 团购券产品名称（第三方平台展示名称） |
| `coupon_channel` | int | `1` | 券来源渠道。`1` = 平台渠道 1，`2` = 平台渠道 2（具体平台需查系统配置） |
| `groupon_type` | int | `1` | 团购券类型。`1` = 标准团购券 |
| `channel_deal_id` | int | `1128411555` | 渠道侧产品 ID（第三方平台给团购商品定义的主键），与 `coupon_name` 一一对应 |
| `deal_id` | int | `1345108507` | 系统内部团购产品 ID。`0` = 内部未配置/未同步。与 `channel_deal_id` 形成"渠道侧 ↔ 系统侧"双层映射 |
| `group_package_id` | int | `0` | 内部团购套餐定义 ID，对应 `group_buy_packages` 表的 `id`。当前全部为 `0`（平台券尚未映射到内部套餐） |
| `certificate_id` | string | `"5017032743553662850"` | 平台侧凭证 ID（第三方平台生成的券实例 ID），用于对账。可能有重复值 |
| `verify_id` | string | `""` | 平台核销记录 ID。大部分为空，仅部分平台/版本回传 |
| `coupon_cover` | string | `""` | 券封面图 URL，当前未使用 |
| `coupon_remark` | string | `""` | 券备注信息，当前未使用 |
### 4.4 金额与时长
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `sale_price` | float | `20.26` | 顾客在第三方平台实际支付的价格（元）。已知值：`11.11`、`29.9`、`39.9`、`59.9`、`69.9`、`128.0`。始终小于 `coupon_money` |
| `coupon_money` | float | `48.0` | 券面值/可抵扣金额（元）。已知值：`48.0`、`58.0`、`68.0`、`96.0`、`116.0`、`288.0` |
| `coupon_free_time` | int | `0` | 券附带的免费时长（秒）。当前全部为 `0`（未启用赠送时长） |
### 4.5 使用状态与时间
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `use_status` | int | `1` | 券使用状态。`1` = 已使用/已核销，`2` = 已退款/已撤销 |
| `create_time` | string | `"2026-02-12 23:37:54"` | 验券记录创建时间（系统记录时间） |
| `consume_time` | string | `"2026-02-12 23:37:55"` | 券被核销的业务时间。与 `create_time` 通常相差 1 秒左右 |
| `is_delete` | int | `0` | 逻辑删除标记。`0` = 未删除，`1` = 已逻辑删除。与 `use_status` 独立：`use_status=2` 不一定 `is_delete=1` |
### 4.6 订单、球台与操作员
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `site_order_id` | int | `3092345641453701` | 门店内部订单 ID，将平台券核销挂到本地订单上 |
| `table_id` | int | `2793002808987781` | 使用券的球台 ID，对应台桌列表的 `id` |
| `operator_id` | int | `2790687322443013` | 执行验券操作的收银员/员工 ID |
| `operator_name` | string | `"收银员:郑丽珊"` | 操作员姓名（带职位前缀） |
---
## 五、响应样例（单条记录）
```json
{
"siteProfile": {
"id": 2790685415443269,
"org_id": 2790684179467077,
"shop_name": "朗朗桌球",
"business_tel": "13316068642",
"full_address": "广东省广州市天河区丽阳街12号",
"shop_status": 1
},
"id": 3092405812332869,
"tenant_id": 2790683160709957,
"site_id": 2790685415443269,
"sale_price": 20.26,
"coupon_code": "0108919359400",
"coupon_channel": 1,
"site_order_id": 3092345641453701,
"coupon_free_time": 0,
"use_status": 1,
"create_time": "2026-02-12 23:37:54",
"is_delete": 0,
"coupon_name": "【全天可用】中八桌球一小时（大厅A区）",
"coupon_cover": "",
"coupon_remark": "",
"channel_deal_id": 1128411555,
"group_package_id": 0,
"consume_time": "2026-02-12 23:37:55",
"groupon_type": 1,
"coupon_money": 48.0,
"operator_id": 2790687322443013,
"operator_name": "收银员:郑丽珊",
"table_id": 2793002808987781,
"certificate_id": "5017032743553662850",
"verify_id": "",
"deal_id": 1345108507
}
```
---
## 六、跨表关联
### 与团购套餐定义（`group_buy_packages`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `group_package_id` | `id` | 内部团购套餐 ID（当前全部为 0，预留外键） |
### 与团购核销记录（`group_buy_redemption_records`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `coupon_code` | `coupon_code` | 券码，串联"平台 → 核销 → 台费流水"全链路 |
### 与订单/结账相关表
通过 `site_order_id` 将平台券核销记录挂到门店订单上，可进一步关联台费流水、商品销售记录、小票详情等。
### 与台桌列表
`table_id` 对应台桌列表的 `id`，标明券在哪张台桌上消费。
### 与外部平台
- `coupon_code`：顾客和平台双方可见的券码
- `certificate_id`：平台内部凭证 ID
- `verify_id`：平台核销 ID（部分平台回传）
- `channel_deal_id` / `deal_id`：平台和系统对团购产品的双重映射
<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/platform_coupon_redemption_records.md，按逻辑分组详解所有字段，含跨表关联
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
-->

359
apps/etl/pipelines/feiqiu/docs/api-reference/summary/recharge_settlements.md Normal file
View File

@@ -0,0 +1,359 @@
# 充值结算记录 — 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）
```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 | `""` | 充值单备注。当前未使用 |
---
## 五、响应样例（单条记录，精简版）
```json
{
"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` 为冗余快照。
<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/recharge_settlements.md，按逻辑分组详解所有字段，含跨表关联
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
-->

220
apps/etl/pipelines/feiqiu/docs/api-reference/summary/refund_transactions.md Normal file
View File

@@ -0,0 +1,220 @@
# 退款流水 — GetRefundPayLogList
> 模块：`Order` · ODS 表：`refund_transactions` · 事实表（增量）
---
## 一、接口概述
查询门店下已完成的退款支付流水。每条记录对应一笔资金层面的退款交易（资金反向流出），`pay_amount` 全为负数。本表是纯资金维度的退款流水，不含退款原因等业务信息；通过 `relate_type` + `relate_id` 关联到具体业务实体（消费订单、充值记录等）。与支付流水（`payment_transactions`）共用枚举体系，可 UNION 构建统一资金流水视图。
| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /Order/GetRefundPayLogList` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | `page` + `limit`（最大 100） |
| 时间范围 | `startTime` / `endTime`（必填） |
---
## 二、请求
### 请求体（JSON）
```json
{
"startTime": "2025-11-01 08:00:00",
"endTime": "2025-11-10 08:00:00",
"siteId": 2790685415443269,
"page": 1,
"limit": 100
}
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `startTime` | string | 是 | 查询起始时间 |
| `endTime` | string | 是 | 查询结束时间 |
| `siteId` | int | 是 | 门店 ID |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |
---
## 三、响应结构
```
{
"code": 200,
"data": {
"list": [ { ... }, { ... } ],
"total": 11
}
}
```
`data.list` 中每个对象即为一条退款流水记录，共 32 个字段（含嵌套 `siteProfile`），按逻辑分组说明如下。
---
## 四、响应字段详解（32 个字段）
### 4.1 主键与门店/租户
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `3089577798995141` | 退款流水记录主键 ID |
| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID |
| `site_id` | int | `2790685415443269` | 门店 ID |
| `tenantName` | string | `"朗朗桌球"` | 租户名称，冗余展示字段，与 `siteProfile.shop_name` 一致 |
| `siteProfile` | object | `{...}` | 门店信息快照（冗余），结构与其他接口一致，不再逐字段展开 |
### 4.2 业务关联
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `relate_type` | int | `1` | 关联业务类型枚举。`1` = 结账单退款（当前样本新增）；`2` = 消费类订单退款；`5` = 充值/储值类业务退款（金额通常较大） |
| `relate_id` | int | `3089548319804869` | 关联业务记录的主键 ID。同一 `relate_id` 可对应多条退款流水（分批退场景） |
| `pay_sn` | int | `0` | 支付序列号。当前未使用，全部为 0 |
### 4.3 金额字段
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `pay_amount` | float | `-8.0` | 退款资金变动金额（元/人民币）。**全部为负数**，绝对值即退款金额。判断退款金额应看此字段的负数值，而非 `refund_amount` |
| `refund_amount` | float | `0.0` | 实际退款金额字段。当前**未启用**，全部为 0.0。系统直接用 `pay_amount` 负数表示退款额 |
| `balance_frozen_amount` | float | `0.0` | 会员储值卡退款时暂时冻结的余额金额（元）。当前无会员卡退款，全部为 0 |
| `card_frozen_amount` | float | `0.0` | 卡被冻结金额（元），与会员卡/储值账户相关。当前未使用 |
| `round_amount` | float | `0.0` | 舍入/抹零金额（元）。当前未使用 |
| `channel_fee` | float | `0.0` | 第三方支付渠道手续费（元）。当前未使用 |
### 4.4 时间字段
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `create_time` | string | `"2026-02-10 23:41:06"` | 退款流水创建时间 |
| `pay_time` | string | `"2026-02-10 23:41:06"` | 退款在支付渠道层面实际发生的时间。当前与 `create_time` 完全一致；异步退款场景下二者可能不同 |
### 4.5 支付方式与渠道
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `payment_method` | int | `4` | 支付/退款方式枚举。已知值：`2`（某种线上支付渠道）、`4`（另一种支付方式）。与支付流水共用枚举 |
| `online_pay_channel` | int | `0` | 线上支付渠道枚举。`0` = 线下/默认渠道。当前未出现其他值 |
| `online_pay_type` | int | `0` | 在线退款类型。`0` = 原路退回。其他值（如退到余额、退到其他银行卡）当前未出现 |
| `pay_terminal` | int | `1` | 退款终端类型枚举。`1` = 前台收银端。其他值（小程序、自助机等）当前未出现 |
| `pay_config_id` | int | `0` | 支付配置 ID（商户支付通道配置主键）。当前未使用 |
| `channel_payer_id` | string | `""` | 支付渠道侧 payer ID（如微信 openid）。当前未使用 |
| `channel_pay_no` | string | `""` | 第三方支付平台交易号（如微信支付单号）。当前未使用 |
### 4.6 会员关联
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `member_id` | int | `0` | 会员 ID。`0` = 非会员退款或未绑定会员。非 0 时对应会员档案表主键 |
| `member_card_id` | int | `0` | 会员卡账户 ID。`0` = 未退到会员卡。非 0 时对应储值卡列表主键 |
### 4.7 状态与标志
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `pay_status` | int | `2` | 退款状态枚举。`2` = 已完成。当前导出仅包含已完成的退款记录 |
| `action_type` | int | `2` | 行为类型枚举。`2` = 退款。配合 `pay_amount < 0` 确认为退款动作 |
| `is_revoke` | int | `0` | 是否撤销型退款。`0` = 正常退款；`1` = 撤销类型操作 |
| `is_delete` | int | `0` | 逻辑删除标记。`0` = 未删除，`1` = 已逻辑删除 |
| `check_status` | int | `1` | 审核状态。`1` = 已审核/通过。系统支持"退款需审核"流程 |
### 4.8 操作相关
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `operator_id` | int | `0` | 执行退款操作的操作员 ID。当前全部为 0（系统未记录或导出未带出） |
| `cashier_point_id` | int | `0` | 收银点 ID。当前未区分具体收银点 |
---
## 五、响应样例（单条记录）
```json
{
"tenantName": "朗朗桌球",
"siteProfile": { "id": 2790685415443269, "shop_name": "朗朗桌球", "..." : "..." },
"id": 3089577798995141,
"site_id": 2790685415443269,
"tenant_id": 2790683160709957,
"pay_sn": 0,
"pay_amount": -8.0,
"pay_status": 2,
"pay_time": "2026-02-10 23:41:06",
"create_time": "2026-02-10 23:41:06",
"relate_type": 1,
"relate_id": 3089548319804869,
"is_revoke": 0,
"is_delete": 0,
"online_pay_channel": 0,
"payment_method": 4,
"balance_frozen_amount": 0.0,
"card_frozen_amount": 0.0,
"member_id": 0,
"member_card_id": 0,
"round_amount": 0.0,
"online_pay_type": 0,
"action_type": 2,
"refund_amount": 0.0,
"cashier_point_id": 0,
"operator_id": 0,
"pay_terminal": 1,
"pay_config_id": 0,
"channel_payer_id": "",
"channel_pay_no": "",
"check_status": 1,
"channel_fee": 0.0
}
```
---
## 六、跨表关联
### 与支付流水（`payment_transactions`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `relate_type` + `relate_id` | `relate_type` + `relate_id` | 通过共同指向同一业务实体间接关联 |
| `payment_method` | `payment_method` | 共用支付方式枚举 |
| `online_pay_channel` | `online_pay_channel` | 共用线上渠道枚举 |
> 支付流水 `pay_amount > 0`（进账），退款流水 `pay_amount < 0`（出账）。两者可 UNION 构建统一资金流水视图，通过 `action_type` + `pay_amount` 符号区分方向。
### 与结账记录（`settlement_records`）
当 `relate_type = 2` 时，`relate_id` 对应结账记录的 `settleList.id`，可追溯退款对应的原始消费订单。
### 与充值结算记录（`recharge_settlements`）
当 `relate_type = 5` 时，`relate_id` 对应充值业务记录的主键，可追溯退款对应的原始充值订单。
### 与会员体系
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `member_id` | 会员档案 `id` | 会员主键 |
| `member_card_id` | 储值卡列表主键 | 会员卡账户 |
> 当前数据中 `member_id` / `member_card_id` 全部为 0，说明均为非会员卡退款。一旦发生"退到储值卡"场景，这些字段会出现非 0 值，可串联"资金退款 → 会员余额变更 → 卡账户状态"。
### 与门店维度
`site_id` / `tenant_id` 与所有业务表一致。`siteProfile` 为冗余快照。
<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/refund_transactions.md，按逻辑分组详解所有字段，含跨表关联
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
-->

424
apps/etl/pipelines/feiqiu/docs/api-reference/summary/settlement_records.md Normal file
View File

@@ -0,0 +1,424 @@
# 结账记录 — 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）
```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` = 是 |
#### 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 优惠 / 折扣 / 活动金额
> 系统在优惠维度上做了非常细的拆分，按来源区分：会员折扣、活动折扣、商品促销、助教促销、券优惠、积分优惠、人工调价、抹零。每个维度对应独立的金额字段。
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `memberDiscountAmount` | float | `0.0` | 会员折扣优惠金额（会员等级对应的折扣减免） |
| `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 | `""` | 订单备注，收银员手工输入的特殊说明 |
---
## 五、响应样例（单条记录）
```json
{
"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` | 商户代金券售卖金额 |
<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-180000 — 上下文传递续接，继续 Phase 2 API 文档重构
- 直接原因: 按标杆文档格式重写 settlement_records 高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/settlement_records.md，92 个字段按 10 个逻辑分组详解，含嵌套结构说明、跨表关联、新增字段标注
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/settlement_records.md 和 samples/settlement_records.json 确认字段覆盖完整
-->

336
apps/etl/pipelines/feiqiu/docs/api-reference/summary/settlement_ticket_details.md Normal file
View File

@@ -0,0 +1,336 @@
# ⚠️ 结账小票明细 — 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 确认字段覆盖完整；接口恢复后需实际验证
- 日期: 2026-02-14
- Prompt: P20260214-060000 / P20260214-061000 — 全量 JSON 刷新 + MD 文档补全 + 数据路径修正
- 直接原因: 旧 JSON 样本仅含单条记录，缺少条件性字段；api_registry.json 中 17 个 data_path 与实际不符
- 变更摘要: 新增「响应数据路径」行
- 风险与验证: 纯文档变更，无运行时影响；验证：python scripts/refresh_json_and_audit.py 输出 24/24 通过
-->

227
apps/etl/pipelines/feiqiu/docs/api-reference/summary/site_tables_master.md Normal file
View File

@@ -0,0 +1,227 @@
# 台桌主数据 — GetSiteTables
> 模块：`Table` · ODS 表：`site_tables_master` · 维度表（快照）
---
## 一、接口概述
查询门店下所有台桌的配置信息，包括台号、区域、状态、灯控、线上预约、台呢使用等。每条记录对应一张台桌，是典型的维度表，与台费流水、助教流水、台费打折等事实表通过 `id`（即 `site_table_id`）关联。本表是整个门店模型中的核心基础维表之一。
| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /Table/GetSiteTables` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | `page` + `limit`（最大 100） |
| 时间范围 | 不需要（全量快照） |
| 响应数据路径 | `data.siteTables` |
---
## 二、请求
### 请求体（JSON）
```json
{
"showStatus": 0,
"virtualTableType": -1,
"page": 1,
"limit": 100
}
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `showStatus` | int | 是 | 展示状态筛选。`0` = 全部，`1` = 展示中，`2` = 隐藏 |
| `virtualTableType` | int | 是 | 虚拟桌类型筛选。`-1` = 全部，`0` = 物理台，`1` = 虚拟台 |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |
---
## 三、响应结构
```
{
"code": 200,
"data": {
"list": [ { ... }, { ... } ],
"total": 71
}
}
```
`data.list` 中每个对象即为一条台桌记录，共 25 个字段，按 8 个逻辑分组说明如下。
---
## 四、响应字段详解（25 个字段）
### 4.1 主键与门店标识
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `2791964216463493` | 台桌主键 ID。全系统唯一标识，各类流水表（台费、助教、台费打折等）通过 `site_table_id` 引用此值 |
| `site_id` | int | `2790685415443269` | 门店 ID，所有记录相同。与其他业务表的 `site_id` 一致 |
| `siteName` | string | `"朗朗桌球"` | 门店名称，冗余展示字段 |
### 4.2 区域与台桌属性
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `site_table_area_id` | int | `2791963794329671` | 台桌区域 ID，与 `areaName` 一一对应。在台费流水中对应 `tableProfile.site_table_area_id` |
| `areaName` | string | `"A区"` | 区域名称。已知值：`A区`（18台）、`B区`（15台）、`补时长`（7台）、`C区`（6台）、`麻将房`（5台）、`VIP包厢`（4台）、`斯诺克区`（4台）、`K包`（3台）、`666`/`M7`/`k包活动区`（各2台）、`TV台`/`M8`/`发财`（各1台） |
| `table_name` | string | `"A1"` | 台号/台名称，71 条记录各不相同。用于前台展示，也出现在流水中的 `ledger_name` 或 `tableName` 字段 |
| `table_price` | float | `0.0` | 台的基础单价（元）。当前门店未在台列表中配置单价（全部为 0），实际计费规则在独立计费策略表中 |
| `virtual_table` | int | `0` | 虚拟台标记：`0` = 物理台，`1` = 虚拟台（组合计费/逻辑台）。当前门店全部为 0 |
| `self_table` | int | `1` | 自有台标记：`1` = 本门店自有台，`0` = 联营/外部台（预留）。当前全部为 1 |
| `is_rest_area` | int | `0` | 休息区标记：`0` = 正常计费区域，`1` = 休息区（不参与计费）。当前全部为 0 |
### 4.3 状态与展示控制
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `table_status` | int | `1` | 台桌运行状态：`1` = 空闲中，`2` = 使用中，`3` = 暂停中 |
| `tableStatusName` | string | `"空闲中"` | `table_status` 的中文名称，仅展示用途 |
| `show_status` | int | `1` | 前台展示状态：`1` = 在开台列表中展示（68台），`2` = 不在常规列表展示（3台：大包/大包麻将房/小包，主要通过线上预约使用） |
| `audit_status` | int | `2` | 审核状态：`2` = 已审核/已启用。其他值可能表示待审核/驳回，当前全部为 2 |
| `charge_free` | int | `0` | 免单标记：`0` = 正常计费，`1` = 免单台。当前全部为 0 |
### 4.4 灯控与延时
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `light_status` | int | `2` | 台灯状态：`1` = 开灯/可控，`2` = 关灯/关闭。与智能硬件联动 |
| `delay_lights_time` | int | `0` | 台灯熄灭延迟时间（秒或分钟），结账后延时关灯。当前全部为 0（未启用） |
| `temporary_light_second` | int | `0` | 临时点灯时长（秒），手动临时开灯场景。当前全部为 0（未启用） |
| `order_delay_time` | int | `0` | 订单自动延时时长，到点后自动延长计费。当前全部为 0（未启用） |
### 4.5 线上预约与团购
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `is_online_reservation` | int | `2` | 线上预约开关：`1` = 允许线上预约（仅大包/小包），`2` = 不允许。与 `show_status` 配合使用：普通台 `show_status=1` + `is_online_reservation=2`；包厢 `show_status=2` + `is_online_reservation=1` |
| `only_allow_groupon` | int | `2` | 团购限制：`1` = 仅允许团购使用（团购专用台），`2` = 不限制。当前全部为 2 |
| `appletQrCodeUrl` | string | `"https://pc-we.ficoo.vip/..."` | 小程序二维码 URL，每张台独立。URL 中包含 `id`（台桌 ID）和 `siteId`（门店 ID）参数。用于扫码开台、呼叫服务等 |
### 4.6 台呢使用
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `table_cloth_use_time` | int | `1863727` | 台呢累计使用时长（秒）。例如 1863727 秒 ≈ 517 小时。每次开台会累加对应秒数，用于提醒更换/保养 |
| `table_cloth_use_Cycle` | int | `0` | 台呢使用周期阈值（秒），达到后提醒更换。`0` = 未配置。当前全部为 0 |
### 4.7 当前订单
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `order_id` | integer | `0` | 当前使用中的台桌关联订单 ID。`0` = 空闲无订单；非零时对应正在进行的台费订单主键 |
### 4.8 时间元数据
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `create_time` | string | `"2025-07-15 17:52:54"` | 台桌配置创建时间。多数台在 2025-07-16 集中创建 |
---
## 五、响应样例（单条记录）
```json
{
"id": 2791964216463493,
"audit_status": 2,
"charge_free": 0,
"self_table": 1,
"create_time": "2025-07-15 17:52:54",
"is_rest_area": 0,
"light_status": 2,
"show_status": 1,
"site_id": 2790685415443269,
"site_table_area_id": 2791963794329671,
"table_cloth_use_time": 1863727,
"table_cloth_use_Cycle": 0,
"virtual_table": 0,
"table_name": "A1",
"table_price": 0.0,
"table_status": 1,
"areaName": "A区",
"siteName": "朗朗桌球",
"tableStatusName": "空闲中",
"appletQrCodeUrl": "https://pc-we.ficoo.vip/rootwww/prodwx38a48dd2bc3c1642?env=prod&type=1&id=2791964216463493&siteId=2790685415443269",
"only_allow_groupon": 2,
"delay_lights_time": 0,
"order_delay_time": 0,
"temporary_light_second": 0,
"is_online_reservation": 2
}
```
---
## 六、跨表关联
### 与台费流水（`table_fee_records`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `id` | `site_table_id` | 台桌主键 → 流水中的台桌 ID |
| `table_name` | `ledger_name` / `tableName` | 台号名称 |
| `site_table_area_id` | `tableProfile.site_table_area_id` | 区域 ID |
| `areaName` | `tableProfile.site_table_area_name` | 区域名称 |
> 台费流水是事实表，本表是对应的台桌维表。两者通过 `site_table_id` 构成事实表–维度表关系。
### 与台费打折（`table_fee_discounts`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `id` | `site_table_id` / `tableProfile.id` | 台桌主键 |
| `table_name` | `tableProfile.table_name` | 台号名称 |
| `site_table_area_id` | `tableProfile.site_table_area_id` | 区域 ID |
> 台费打折记录中的 `tableProfile` 是对本表某一行台的快照。
### 与助教流水（`assistant_service_records`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `id` | `site_table_id` | 台桌主键 → 助教服务所在台桌 |
| `table_name` | `tableName` | 台号名称 |
> 助教服务附着在具体台桌上，可按台/按区域统计助教服务情况。
### 与门店维度
所有业务表的 `site_id`、`siteName` 一致，共享门店维度。台桌列表是门店维度下的子实体表，与门店档案存在 1:N 关系（一个门店多张台）。
### 业务角色组合规则
- 普通台：`show_status=1` + `is_online_reservation=2`（现场前台开台）
- 线上预约包厢：`show_status=2` + `is_online_reservation=1`（线上预约入口）
- 补时长台：通过"特殊命名 + 区域"实现，`virtual_table` 仍为 0
<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/site_tables_master.md，按逻辑分组详解所有 25 个字段，含跨表关联
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
- 日期: 2026-02-14
- Prompt: P20260214-060000 / P20260214-061000 — 全量 JSON 刷新 + MD 文档补全 + 数据路径修正
- 直接原因: 旧 JSON 样本仅含单条记录，缺少条件性字段；api_registry.json 中 17 个 data_path 与实际不符
- 变更摘要: 新增「响应数据路径」行；补全 1 个缺失字段（tableprofile）
- 风险与验证: 纯文档变更，无运行时影响；验证：python scripts/refresh_json_and_audit.py 输出 24/24 通过
- 日期: 2026-02-14
- Prompt: P20260214-130000 — 25 个 API 文档归档至 summary/ + 字段分组修正
- 直接原因: 4.7"时间元数据"组混入 order_id（当前订单 ID），与时间无关
- 变更摘要: 新增 4.7"当前订单"组（1 字段）；原 4.7 时间组重编号为 4.8
- 风险与验证: 纯文档分组调整，无运行时影响；验证：统计各组字段数总和 = 25
-->

222
apps/etl/pipelines/feiqiu/docs/api-reference/summary/stock_goods_category_tree.md Normal file
View File

@@ -0,0 +1,222 @@
# 商品分类树 — QueryPrimarySecondaryCategory
> 模块：`TenantGoodsCategory` · ODS 表：`stock_goods_category_tree` · 维度表（全量快照）
---
## 一、接口概述
查询租户级商品分类树，返回完整的两级分类结构（一级大类 + 二级子类），包含分类名称、业务大类归属、库存管理开关等配置。分类树是商品维度的核心维表，所有商品档案、库存记录、销售记录中的分类 ID 均引用本表节点。
| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /TenantGoodsCategory/QueryPrimarySecondaryCategory` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | 无分页（一次返回全部） |
| 时间范围 | 不需要（全量快照） |
| 响应数据路径 | `data.goodsCategoryList` |
---
## 二、请求
### 请求体
无请求参数（`body: null`）。
---
## 三、响应结构
> ⚠️ 注意：本接口响应结构特殊，数据位于 `data.goodsCategoryList`（而非常见的 `data.list`）。
```
{
"code": 200,
"data": {
"total": 0,
"goodsCategoryList": [
{
"id": ...,
"category_name": "槟榔",
"categoryBoxes": [
{ "id": ..., "category_name": "槟榔", "categoryBoxes": [] }
]
},
...
]
}
}
```
`data.goodsCategoryList` 为一级分类节点数组（当前 9 个根节点），每个根节点的 `categoryBoxes` 包含其二级子分类（共 17 个子节点）。树深度固定为 2 层。
`data.total` 当前固定为 `0`，不反映实际分类数量。
---
## 四、响应字段详解
### 4.1 顶层字段
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `total` | int | `0` | 固定为 0，不反映实际分类数量 |
| `goodsCategoryList` | array | `[{...}, ...]` | 一级分类节点数组，每个节点包含完整的分类信息和子分类列表 |
### 4.2 分类节点字段（父子节点结构完全一致，共 11 个字段）
#### 标识与层级关系
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `2790683528350533` | 分类节点主键 ID，父子节点各有独立 ID，互不重复。全表共 26 个（9 根 + 17 子） |
| `pid` | int | `0` | 父级分类 ID。根节点 `pid = 0`；子节点 `pid` = 对应父节点的 `id` |
| `tenant_id` | int | `2790683160709957` | 租户 ID，所有节点相同。分类在租户层级共享，无门店级差异 |
| `categoryBoxes` | array | `[{...}]` | 子分类数组。根节点包含子节点列表；子节点的 `categoryBoxes` 一律为空数组 `[]`。与 `id`/`pid` 关系冗余，方便前端直接渲染树 |
#### 分类名称
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `category_name` | string | `"槟榔"` | 分类名称。一级大类：槟榔、器材、酒水、果盘、零食、雪糕、香烟、其他、小吃。二级子类如：皮头、球杆、饮料、茶水、咖啡、洋酒、面、其他2 等 |
| `alias_name` | string | `""` | 分类别名/简称，预留字段，当前全部为空 |
#### 业务大类维度
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `business_name` | string | `"槟榔"` | 业务大类名称。根节点等于自身 `category_name`；子节点继承所属根节点的名称。共 9 种：槟榔、器材、酒水、水果、零食、雪糕、香烟、其他、小吃 |
| `tenant_goods_business_id` | int | `2790683528317766` | 业务大类 ID，每个 `business_name` 对应唯一一个 ID。根节点和子节点共享同一值 |
#### 配置开关
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `open_salesman` | int | `2` | 营业员/导购提成开关：`2` = 关闭（当前全部统一）。预留按分类差异化配置 |
| `is_warehousing` | int | `1` | 是否参与库存管理：`1` = 参与。当前所有分类均启用库存管理 |
| `sort` | int | `1` | 排序序号，用于前端展示顺序。多数为 0，少数为 1 |
---
## 五、响应样例（精简版，展示 2 个根节点）
```json
{
"total": 0,
"goodsCategoryList": [
{
"id": 2790683528350533,
"tenant_id": 2790683160709957,
"category_name": "槟榔",
"alias_name": "",
"pid": 0,
"business_name": "槟榔",
"tenant_goods_business_id": 2790683528317766,
"open_salesman": 2,
"categoryBoxes": [
{
"id": 2790683528350534,
"tenant_id": 2790683160709957,
"category_name": "槟榔",
"alias_name": "",
"pid": 2790683528350533,
"business_name": "槟榔",
"tenant_goods_business_id": 2790683528317766,
"open_salesman": 2,
"categoryBoxes": [],
"sort": 0,
"is_warehousing": 1
}
],
"sort": 1,
"is_warehousing": 1
},
{
"id": 2790683528350539,
"tenant_id": 2790683160709957,
"category_name": "酒水",
"alias_name": "",
"pid": 0,
"business_name": "酒水",
"tenant_goods_business_id": 2790683528317768,
"open_salesman": 2,
"categoryBoxes": [
{
"id": 2790683528350540,
"tenant_id": 2790683160709957,
"category_name": "饮料",
"alias_name": "",
"pid": 2790683528350539,
"business_name": "酒水",
"tenant_goods_business_id": 2790683528317768,
"open_salesman": 2,
"categoryBoxes": [],
"sort": 0,
"is_warehousing": 1
}
],
"sort": 0,
"is_warehousing": 1
}
]
}
```
---
## 六、跨表关联
### 与门店商品档案（`store_goods_master`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `id`（一级节点） | `goods_category_id` | 一级分类主键 |
| `id`（二级节点） | `goods_second_category_id` | 二级分类主键 |
| `tenant_goods_business_id` | — | 业务大类 ID，可用于按业务线聚合商品 |
### 与租户商品档案（`tenant_goods_master`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `id`（一级节点） | `goods_category_id` | 一级分类主键 |
| `id`（二级节点） | `goods_second_category_id` | 二级分类主键 |
### 与库存汇总（`goods_stock_summary`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `id`（一级节点） | `goodsCategoryId` | 一级分类 ID |
| `id`（二级节点） | `goodsCategorySecondId` | 二级分类 ID |
### 与库存变动（`goods_stock_movements`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `id`（一级节点） | `goodsCategoryId` | 一级分类 ID |
| `id`（二级节点） | `goodsSecondCategoryId` | 二级分类 ID |
### 与门店销售记录（`store_goods_sales_records`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `id` | `tenant_goods_category_id` | 分类 ID |
| `tenant_goods_business_id` | `tenant_goods_business_id` | 业务大类 ID |
> 本表是标准的分类维表，构成三层结构：租户（`tenant_id`）→ 业务线（`tenant_goods_business_id`）→ 具体分类（`id` + 父子层级）。
<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/stock_goods_category_tree.md，详解分类树结构（11 个节点字段），明确 goodsCategoryList 特殊响应结构，含跨表关联
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
- 日期: 2026-02-14
- Prompt: P20260214-060000 / P20260214-061000 — 全量 JSON 刷新 + MD 文档补全 + 数据路径修正
- 直接原因: 旧 JSON 样本仅含单条记录，缺少条件性字段；api_registry.json 中 17 个 data_path 与实际不符
- 变更摘要: 新增「响应数据路径」行（记录 API 实际返回的数据路径）
- 风险与验证: 纯文档变更，无运行时影响；验证：python scripts/refresh_json_and_audit.py 输出 24/24 通过
-->

268
apps/etl/pipelines/feiqiu/docs/api-reference/summary/store_goods_master.md Normal file
View File

@@ -0,0 +1,268 @@
# 门店商品库存主数据 — GetGoodsInventoryList
> 模块：`TenantGoods` · ODS 表：`store_goods_master` · 维度表（快照）
---
## 一、接口概述
查询门店级商品库存主数据，包括商品基础信息、分类、库存数量、价格/成本、状态开关、销售表现等。每条记录对应一个门店维度的商品，是商品维度的核心维表。与租户商品档案（`tenant_goods_master`）通过 `tenant_goods_id` 关联，与库存/销售事实表通过 `id`（即 `site_goods_id`）关联。
| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /TenantGoods/GetGoodsInventoryList` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | `page` + `limit`（最大 100） |
| 时间范围 | 不需要（全量快照） |
---
## 二、请求
### 请求体（JSON）
```json
{
"goodsSecondCategoryId": [],
"goodsState": 0,
"enableStatus": 0,
"siteId": [2790685415443269],
"existsGoodsStock": 0,
"page": 1,
"limit": 100
}
```
> ⚠️ 注意：`siteId` 参数必须为数组格式 `[sid]`，而非单个整数值。这是本接口的特殊要求。
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `goodsSecondCategoryId` | array | 是 | 二级分类 ID 列表，空数组 `[]` = 全部 |
| `goodsState` | int | 是 | 商品状态筛选。`0` = 全部，`1` = 正常，`2` = 特殊状态 |
| `enableStatus` | int | 是 | 启用状态筛选。`0` = 全部，`1` = 启用 |
| `siteId` | array | 是 | 门店 ID **数组**（如 `[2790685415443269]`）。必须为数组格式 |
| `existsGoodsStock` | int | 是 | 是否有库存筛选。`0` = 全部 |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |
---
## 三、响应结构
```
{
"code": 200,
"data": {
"list": [ { ... }, { ... } ],
"total": 161
}
}
```
`data.list` 中每个对象即为一条门店商品记录，共 45 个字段，按逻辑分组说明如下。
---
## 四、响应字段详解（45 个字段）
### 4.1 门店与租户维度
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID，所有记录相同 |
| `site_id` | int | `2790685415443269` | 门店 ID，与其他业务表一致 |
| `siteName` | string | `"朗朗桌球"` | 门店名称，冗余展示字段 |
### 4.2 商品标识与分类
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `2793025851560005` | 门店商品 ID（主键）。在其他表中以 `site_goods_id` / `siteGoodsId` 出现，用于关联库存、销售记录 |
| `tenant_goods_id` | int | `2792178593255301` | 租户级商品 ID（全局商品 ID），对应 `tenant_goods_master.id`。一个全局商品可在多个门店生成多条门店商品 |
| `goods_name` | string | `"合味道泡面"` | 商品名称，业务展示字段 |
| `goods_category_id` | int | `2791941988405125` | 一级分类 ID，对应分类树主键，与 `oneCategoryName` 搭配 |
| `goods_second_category_id` | int | `2793236829620037` | 二级分类 ID，对应分类树子节点，与 `twoCategoryName` 搭配 |
| `oneCategoryName` | string | `"零食"` | 一级分类名称，与 `goods_category_id` 一一对应 |
| `twoCategoryName` | string | `"面"` | 二级分类名称，与 `goods_second_category_id` 对应 |
| `unit` | string | `"桶"` | 计量单位。常见值：包、瓶、个、份、根、盒、杯、桶、盘、支等 |
| `goods_cover` | string | `"https://oss.ficoo.vip/..."` | 商品图片 URL（OSS 存储） |
| `pinyin_initial` | string | `"HWDPM,GWDPM"` | 拼音首字母/助记码，多别名逗号分隔，用于前台拼音检索 |
| `goods_bar_code` | string | `""` | 商品条形码（EAN 等），当前门店未配置，全部为空 |
### 4.3 库存与数量
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `stock` | int | `18` | 当前可用库存数量（以 `unit` 为单位）。可为 0（售罄）或很大（虚拟库存） |
| `stock_A` | int | `0` | 副单位库存数量（双单位场景如箱/瓶）。当前门店未启用，全部为 0 |
| `batch_stock_quantity` | int | `43` | 当前批次库存数量（主单位）。有成本价时 `batch_stock_quantity × cost_price ≈ provisional_total_cost` |
| `sale_num` | int | `104` | 当前统计口径下的销售数量（总销量），与 `total_sales` 一致 |
| `total_sales` | int | `104` | 累计销售数量。当前与 `sale_num` 相同，字段保留了区间销量 vs 历史总销量的扩展空间 |
| `safe_stock` | int | `0` | 安全库存量（阈值），低于此值可提示补货。当前未设置，全部为 0 |
### 4.4 价格、成本与金额
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `sale_price` | float | `12.0` | 标准销售价（挂牌价），单位：元（人民币）。实际结算可能打折 |
| `cost_price` | float | `0.0` | 成本价（单件成本），单位：元。部分为 0（未录入），部分有值如 1.788 |
| `cost_price_type` | int | `1` | 成本价类型：`1` = 固定成本价（手工维护），`2` = 动态成本价（按采购单平均价结转） |
| `provisional_total_cost` | float | `0.0` | 暂估总成本，单位：元。有成本价时 ≈ `batch_stock_quantity × cost_price` |
| `total_purchase_cost` | float | `0.0` | 总采购成本，单位：元。当前与 `provisional_total_cost` 相等，字段为后续结算/重算成本保留空间 |
| `min_discount_price` | float | `7.0` | 最低允许成交价（限价），单位：元。`0` 表示不设置限价。收银改价时系统校验不低于此值 |
| `able_discount` | int | `1` | 是否允许参与折扣：`1` = 允许。当前全部为 1 |
### 4.5 时间与销售表现
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `create_time` | string | `"2025-07-16 11:52:51"` | 门店商品档案创建时间 |
| `update_time` | string | `"2025-11-09 07:23:47"` | 最后修改时间（价格调整、状态变更等） |
| `days_available` | int | `13` | 商品在架天数/可售天数。`0` 表示刚建档/刚启用 |
| `average_monthly_sales` | float | `1.32` | 平均月销量（件/月），辅助补货/品类管理的历史行为指标 |
### 4.6 状态与开关
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `goods_state` | int | `1` | 商品基本状态：`1` = 正常，`2` = 特殊状态（新建/停售/未完整启用，通常 stock=0、days_available=0） |
| `audit_status` | int | `2` | 审核状态：`2` = 审核通过。其他可能值：`0` = 待提交，`1` = 待审核，`3` = 不通过 |
| `enable_status` | int | `1` | 启用状态：`1` = 启用，`2` = 停用（未出现） |
| `send_state` | int | `1` | 上架/可售状态：`1` = 可销售/可下单 |
| `sale_channel` | int | `1` | 销售渠道：`1` = 门店线下渠道 |
| `is_warehousing` | int | `1` | 是否纳入库存管理：`1` = 参与库存管理 |
| `is_delete` | int | `0` | 逻辑删除标志：`0` = 未删除，`1` = 已删除 |
| `freeze` | int | `0` | 冻结状态：`0` = 未冻结。非 0 可能表示"锁库存""禁止出库" |
| `forbid_sell_status` | int | `1` | 禁止销售状态：`1` = 未禁止（允许销售），`2` = 被禁止 |
| `able_site_transfer` | int | `2` | 是否允许跨门店调拨：`2` = 不允许（绝大多数），`0` = 未配置 |
| `custom_label_type` | int | `2` | 自定义标签类型：`2` = 使用自定义标签/分类 |
| `option_required` | int | `1` | 是否需要选择规格/选项：`1` = 不要求（单规格商品） |
### 4.7 其他辅助
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `remark` | string | `""` | 商品备注（口味说明、供应商等），当前未使用 |
| `sort` | int | `100` | 排序权重，用于前端商品列表展示排序 |
| `commodity_code` | string | `10000002` | 商品编码，门店内部商品管理编号 |
| `goodsStockWarningInfo` | object | `{...}` | 库存预警信息对象，含预警阈值等子字段（暂不入 ODS，按需展开） |
| `not_sale` | integer | `2` | 非售卖标记枚举（如 2=正常售卖），控制商品是否参与销售 |
| `time_slot_sale` | integer | `2` | 时段售卖标记枚举（如 2=不限时段），控制商品是否仅在特定时段可售 |
---
## 五、响应样例（单条记录）
```json
{
"siteName": "朗朗桌球",
"oneCategoryName": "零食",
"twoCategoryName": "面",
"id": 2793025851560005,
"tenant_goods_id": 2792178593255301,
"site_id": 2790685415443269,
"tenant_id": 2790683160709957,
"goods_name": "合味道泡面",
"goods_cover": "https://oss.ficoo.vip/admin/8M1WM7_1753204221337.jpg",
"goods_state": 1,
"goods_category_id": 2791941988405125,
"unit": "桶",
"sale_num": 104,
"cost_price": 0.0,
"provisional_total_cost": 0.0,
"total_purchase_cost": 0.0,
"batch_stock_quantity": 43,
"sale_price": 12.0,
"stock_A": 0,
"stock": 18,
"create_time": "2025-07-16 11:52:51",
"is_delete": 0,
"custom_label_type": 2,
"goods_second_category_id": 2793236829620037,
"total_sales": 104,
"remark": "",
"audit_status": 2,
"update_time": "2025-11-09 07:23:47",
"pinyin_initial": "HWDPM,GWDPM",
"goods_bar_code": "",
"able_discount": 1,
"min_discount_price": 7.0,
"sort": 100,
"freeze": 0,
"days_available": 13,
"average_monthly_sales": 1.32,
"safe_stock": 0,
"send_state": 1,
"enable_status": 1,
"sale_channel": 1,
"able_site_transfer": 2,
"cost_price_type": 1,
"forbid_sell_status": 1,
"is_warehousing": 1,
"option_required": 1
}
```
---
## 六、跨表关联
### 与租户商品档案（`tenant_goods_master`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `tenant_goods_id` | `id` | 门店商品 → 品牌级商品。一个全局商品可在多个门店生成多条门店商品 |
| `goods_category_id` | `goods_category_id` | 一级分类 ID 一致 |
| `goods_second_category_id` | `goods_second_category_id` | 二级分类 ID 一致 |
### 与门店销售记录（`store_goods_sales_records`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `id` | `site_goods_id` | 门店商品主键 → 销售明细中的商品 ID |
| `tenant_goods_id` | `tenant_goods_id` | 全局商品 ID 一致 |
> 本表是维表，销售记录是事实表。
### 与库存汇总（`goods_stock_summary`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `id` | `siteGoodsId` | 门店商品 ID |
| `goods_category_id` | `goodsCategoryId` | 一级分类 ID |
| `goods_second_category_id` | `goodsCategorySecondId` | 二级分类 ID |
| `unit` | `goodsUnit` | 计量单位 |
### 与库存变动（`goods_stock_movements`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `id` | `siteGoodsId` | 门店商品 ID |
| `goods_category_id` | `goodsCategoryId` | 一级分类 ID |
### 与商品分类树（`stock_goods_category_tree`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `goods_category_id` | `id`（一级节点） | 一级分类主键 |
| `goods_second_category_id` | `id`（二级节点） | 二级分类主键 |
> 本表提供 `stock`、`batch_stock_quantity`、成本等某一时刻的快照，库存变动表是全量出入库记录，两者互相补充。
<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/store_goods_master.md，按逻辑分组详解所有 45 个字段，含跨表关联；特别标注 siteId 必须为数组格式
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
- 日期: 2026-02-14
- Prompt: P20260214-103000 — MD 占位符修正 + 临时文件清理
- 直接原因: v2 脚本自动插入的占位符描述需替换为正式中文业务说明
- 变更摘要: commodity_code、goodsStockWarningInfo、not_sale、time_slot_sale 四个新字段的占位符描述替换为正式中文说明
- 风险与验证: 纯文档文案修正，无运行时影响；验证：grep "新发现字段" 本文件应返回 0 结果
-->

275
apps/etl/pipelines/feiqiu/docs/api-reference/summary/store_goods_sales_records.md Normal file
View File

@@ -0,0 +1,275 @@
# 门店商品销售记录 — 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
-->

211
apps/etl/pipelines/feiqiu/docs/api-reference/summary/table_fee_discount_records.md Normal file
View File

@@ -0,0 +1,211 @@
# 台费优惠记录 — GetTaiFeeAdjustList
> 模块：`Site` · ODS 表：`table_fee_discount_records` · 事实表（增量）
---
## 一、接口概述
查询门店下台费打折/调账的流水记录。每条记录不是台桌使用记录，而是在台费基础上追加的一条"金额调整记录"，用于记录某个订单、某张台在台费上的手工打折/减免金额。与台费流水表形成"主表 + 子操作表"的关系，通过 `adjust_amount ↔ ledger_amount` 闭合金额链路。
| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /Site/GetTaiFeeAdjustList` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | `page` + `limit`（最大 100） |
| 时间范围 | `startTime` / `endTime`（必填） |
---
## 二、请求
### 请求体（JSON）
```json
{
"startTime": "2025-11-01 08:00:00",
"endTime": "2025-11-10 08:00:00",
"siteId": 2790685415443269,
"page": 1,
"limit": 100
}
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `startTime` | string | 是 | 查询起始时间 |
| `endTime` | string | 是 | 查询结束时间 |
| `siteId` | int | 是 | 门店 ID |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |
---
## 三、响应结构
```
{
"code": 200,
"data": {
"taiFeeAdjustInfos": [ { ... }, { ... } ],
"total": 200
}
}
```
`data.taiFeeAdjustInfos` 中每个对象即为一条台费优惠记录，共 20 个字段，按逻辑分组说明如下。
---
## 四、响应字段详解（20 个字段）
### 4.1 主键与订单关联
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `2957913441881989` | 台费打折/调整流水主键 ID |
| `order_trade_no` | int | `2957784612605829` | 订单交易号。与台费流水、助教流水、小票详情的同名字段一致。少数订单有多条调整记录 |
| `order_settle_id` | int | `2957913171693253` | 结算单/小票 ID。与小票详情的 `orderSettleId` 对应 |
| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID |
| `site_id` | int | `2790685415443269` | 门店 ID |
### 4.2 台桌维度
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `site_table_id` | int | `2793020259897413` | 台桌 ID，对应台桌配置表主键 |
| `tenant_table_area_id` | int | `2791961347968901` | 租户维度台桌区域 ID |
| `tableProfile` | object | `{...}` | 台桌配置信息快照，子字段见下表 |
#### tableProfile 子字段
| 字段路径 | 类型 | 示例 | 说明 |
|----------|------|------|------|
| `tableProfile.id` | int | `2793020259897413` | 台桌 ID，与 `site_table_id` 一致 |
| `tableProfile.tenant_id` | int | `2790683160709957` | 租户 ID |
| `tableProfile.tenant_name` | string | `""` | 租户名称（当前为空） |
| `tableProfile.siteName` | string | `""` | 门店名称（当前为空，冗余字段） |
| `tableProfile.table_name` | string | `"S1"` | 台号名称 |
| `tableProfile.site_table_area_id` | int | `2791963836207173` | 门店级台桌区域 ID |
| `tableProfile.site_table_area_name` | string | `"斯诺克区"` | 区域名称 |
| `tableProfile.area_type_id` | int | `0` | 区域类型 ID |
| `tableProfile.table_price` | float | `0.0` | 基础单价（元），当前为 0.0 |
| `tableProfile.ewelink_client_id` | string | `""` | 易微联智能硬件设备 ID |
| `tableProfile.charge_free` | int | `0` | 免单标识。`0` = 正常计费 |
### 4.3 金额与数量
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `ledger_amount` | float | `148.15` | 台费调账/减免金额（元/人民币）。**注意**：在本表中 `ledger_amount` 表示"被调整掉的金额"，对应台费流水中同一订单的 `adjust_amount`。与台费流水中的 `ledger_amount`（原始应收）含义不同 |
| `ledger_count` | int | `1` | 调整次数，当前固定为 `1`（一次调账事件）。与台费流水中的 `ledger_count`（计费秒数）含义完全不同 |
| `ledger_name` | string | `""` | 调账项目名称/打折原因描述。当前门店未使用，全部为空字符串。预留字段 |
### 4.4 申请与操作信息
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `adjust_type` | int | `1` | 调整类型枚举。`1` = 台费打折/减免。其他值（如台费转移、误操作恢复）当前未出现 |
| `applicant_id` | int | `2790687322443013` | 打折/调账申请人 ID |
| `applicant_name` | string | `"收银员:郑丽珊"` | 申请人姓名（带角色描述），冗余展示字段 |
| `operator_id` | int | `2790687322443013` | 实际执行调账操作的操作员 ID。当前数据中与 `applicant_id` 相同 |
| `operator_name` | string | `"收银员:郑丽珊"` | 操作员姓名 |
| `create_time` | string | `"2025-11-09 23:25:11"` | 调整记录创建时间，即打折操作执行的时间戳 |
### 4.5 状态与标记
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `ledger_status` | int | `1` | 调整记录状态。`1` = 生效（当前有效的调账记录）；`0` = 已失效/被覆盖（历史记录、已撤销或被后续调账覆盖）。同一 `order_trade_no` 下可能有多条记录，仅 `ledger_status = 1` 的为当前有效 |
| `is_delete` | int | `0` | 逻辑删除标记。`0` = 未删除，`1` = 已逻辑删除 |
### 4.6 门店信息快照
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `siteProfile` | object | `{...}` | 门店信息快照（冗余），结构与其他接口一致，不再逐字段展开 |
---
## 五、响应样例（单条记录）
```json
{
"tableProfile": {
"id": 2793020259897413,
"tenant_id": 2790683160709957,
"tenant_name": "",
"siteName": "",
"table_name": "S1",
"site_table_area_id": 2791963836207173,
"area_type_id": 0,
"table_price": 0.0,
"ewelink_client_id": "",
"site_table_area_name": "斯诺克区",
"charge_free": 0
},
"siteProfile": { "id": 2790685415443269, "shop_name": "朗朗桌球", "..." : "..." },
"id": 2957913441881989,
"adjust_type": 1,
"applicant_id": 2790687322443013,
"applicant_name": "收银员:郑丽珊",
"create_time": "2025-11-09 23:25:11",
"is_delete": 0,
"ledger_amount": 148.15,
"ledger_count": 1,
"ledger_name": "",
"ledger_status": 1,
"operator_id": 2790687322443013,
"operator_name": "收银员:郑丽珊",
"order_settle_id": 2957913171693253,
"order_trade_no": 2957784612605829,
"site_id": 2790685415443269,
"site_table_id": 2793020259897413,
"tenant_id": 2790683160709957,
"tenant_table_area_id": 2791961347968901
}
```
---
## 六、跨表关联
### 与台费流水（`table_fee_transactions`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `order_trade_no` | `order_trade_no` | 同一订单 |
| `order_settle_id` | `order_settle_id` | 同一结算单 |
| `site_table_id` | `site_table_id` | 同一台桌 |
| `ledger_amount`（本表，生效记录） | `adjust_amount`（台费流水） | 本表的减免金额 = 台费流水中的调账金额 |
> 台费流水给出时长 + 原始台费 + 各种金额拆分（含 `adjust_amount`）；台费优惠记录给出是谁、何时、以哪种类型发起了调账，调了多少金额。两表通过 `order_trade_no` 做一对一/一对多关系。
### 与台桌配置 / 区域配置
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `site_table_id` | 台桌配置表 `id` | 台桌主键 |
| `tableProfile.table_name` | 台桌配置表 `table_name` | 台号名称 |
| `tableProfile.site_table_area_id` | 门店台桌区域维表 | 门店级区域 |
| `tenant_table_area_id` | 租户台桌区域维表 | 租户级区域 |
### 与员工/账号体系
`applicant_id` / `operator_id` 与账号体系中的用户 ID 对应（与助教账号 `user_id` 属于同一 ID 空间）。可按员工维度统计台费打折频次和金额。
### 与门店维度
`site_id` 与所有业务表的 `site_id` 一致。`siteProfile` 为冗余快照。
<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/table_fee_discount_records.md，按逻辑分组详解所有字段，含跨表关联
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
-->

261
apps/etl/pipelines/feiqiu/docs/api-reference/summary/table_fee_transactions.md Normal file
View File

@@ -0,0 +1,261 @@
# 台费流水 — GetSiteTableOrderDetails
> 模块：`Site` · ODS 表：`table_fee_transactions` · 事实表（增量）
---
## 一、接口概述
查询门店下台桌使用的计费流水。每条记录对应一段台桌使用时长的结算快照，包含计费时长、单价、原始应收金额以及各类优惠/调账的金额拆分。是台费维度的核心事实表，通过订单号与助教流水、小票详情、支付记录等表关联。
| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /Site/GetSiteTableOrderDetails` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | `page` + `limit`（最大 100） |
| 时间范围 | `startTime` / `endTime`（必填） |
---
## 二、请求
### 请求体（JSON）
```json
{
"startTime": "2025-11-01 08:00:00",
"endTime": "2025-11-10 08:00:00",
"siteId": 2790685415443269,
"isSaleManUser": 0,
"page": 1,
"limit": 100
}
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `startTime` | string | 是 | 查询起始时间 |
| `endTime` | string | 是 | 查询结束时间 |
| `siteId` | int | 是 | 门店 ID |
| `isSaleManUser` | int | 是 | 是否销售员用户筛选。`0` = 全部 |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |
---
## 三、响应结构
```
{
"code": 200,
"data": {
"siteTableUseDetailsList": [ { ... }, { ... } ],
"total": 3813
}
}
```
`data.siteTableUseDetailsList` 中每个对象即为一条台费流水记录，共 42 个字段，按逻辑分组说明如下。
---
## 四、响应字段详解（42 个字段）
### 4.1 主键与订单关联
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `2957924029058885` | 台费流水记录主键 |
| `order_trade_no` | int | `2957858167230149` | 订单交易号，整笔订单的主编号。与助教流水、小票详情等表的同名字段一致 |
| `order_settle_id` | int | `2957922914357125` | 结算单号/结账 ID，对应一次结账操作。与小票详情的 `orderSettleId` 对应 |
| `order_pay_id` | int | `0` | 订单支付记录 ID，对应支付记录表的 `id` 或 `relate_id`。`0` 表示未直接关联 |
| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID，所有记录相同 |
| `site_id` | int | `2790685415443269` | 门店 ID |
### 4.2 台桌维度
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `site_table_id` | int | `2793003705192517` | 台桌 ID，对应台桌配置表主键 |
| `ledger_name` | string | `"A17"` | 台号名称，冗余展示字段。与 `site_table_id` 一一对应 |
| `site_table_area_id` | int | `2791963794329671` | 门店内台桌区域 ID |
| `tenant_table_area_id` | int | `2791960001957765` | 租户维度台桌区域 ID，支持多门店共享区域配置 |
| `site_table_area_name` | string | `"A区"` | 台桌区域名称。已知值：`"A区"`、`"B区"`、`"C区"`、`"斯诺克区"`、`"麻将房"`、`"K包"`、`"VIP包厢"`、`"666"`、`"TV台"`、`"M8"` |
### 4.3 会员维度
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `member_id` | int | `0` | 会员 ID。`0` = 散客/非会员。非 0 时对应会员档案表的 `id` |
### 4.4 时间字段
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `create_time` | string | `"2025-11-09 23:35:57"` | 台费流水创建时间，通常接近结账时间 |
| `start_use_time` | string | `"2025-11-09 22:28:57"` | 实际开台时间。当前数据中与 `ledger_start_time` 完全相同 |
| `ledger_start_time` | string | `"2025-11-09 22:28:57"` | 计费起始时间 |
| `ledger_end_time` | string | `"2025-11-09 23:28:57"` | 计费结束时间 |
| `last_use_time` | string | `"2025-11-09 23:28:57"` | 最后使用/操作时间。与 `ledger_end_time` 多数相差 1 秒（系统截断） |
### 4.5 时长（秒）
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `ledger_count` | int | `3600` | 计费秒数（应收时长）。与 `real_table_use_seconds` 基本一致，少数差 1 秒 |
| `real_table_use_seconds` | int | `3600` | 实际使用总秒数。当两者均为 0 且 `is_single_order = 0` 时，为占位/关联记录 |
| `add_clock_seconds` | int | `0` | 加钟秒数。`0` = 无加钟。非 0 时通常为 60 的倍数（如 2400 = 40 分钟） |
### 4.6 金额与优惠拆分
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `ledger_unit_price` | float | `48.0` | 每小时计费单价（元/人民币）。常见值：48.0、58.0、68.0、88.0、98.0、116.0 |
| `ledger_amount` | float | `48.0` | 原始应收台费金额（元）。近似关系：`ledger_amount ≈ ledger_unit_price × ledger_count / 3600` |
| `real_table_charge_money` | float | `0.0` | 实际向顾客收取的台费金额（元）。`0` 表示完全由券/调账承担 |
| `coupon_promotion_amount` | float | `48.0` | 优惠券/活动/团购承担的优惠金额（元）。当此值等于 `ledger_amount` 且 `real_table_charge_money = 0` 时，表示台费由促销全额承担 |
| `member_discount_amount` | float | `0.0` | 会员权益/折扣承担的优惠金额（元） |
| `adjust_amount` | float | `0.0` | 调账/减免金额（元）。对应台费优惠记录表（`table_fee_discount_records`）中的 `ledger_amount` |
| `used_card_amount` | float | `0.0` | 储值卡/次卡抵扣金额（元）。当前门店未启用 |
| `service_money` | float | `0.0` | 服务费/成本/分成金额（元）。当前门店未启用 |
| `mgmt_fee` | float | `0.0` | 管理费（元）。预留字段，当前未启用 |
| `fee_total` | float | `0.0` | 附加费用合计（元）。预留字段，当前未启用 |
| `real_service_money` | number | `0.0` | 实际服务金额（元），扣除各类优惠后的台费实收金额 |
### 4.7 操作员与营业员
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `operator_id` | int | `2790687322443013` | 操作员 ID（开台/结账员工） |
| `operator_name` | string | `"收银员:郑丽珊"` | 操作员姓名，冗余展示字段 |
| `salesman_name` | string | `""` | 营业员/提成归属人姓名。当前门店未启用 |
| `salesman_user_id` | int | `0` | 营业员用户 ID。当前未启用 |
| `salesman_org_id` | int | `0` | 营业员所属机构 ID。当前未启用 |
### 4.8 订单类型与活动优惠
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `order_consumption_type` | integer | `1` | 订单消费类型枚举（如 1=普通消费），区分不同消费场景 |
| `activity_discount_amount` | number | `0.0` | 活动折扣金额（元），由门店活动/促销规则产生的台费优惠金额 |
### 4.9 状态与标记
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `ledger_status` | int | `1` | 台费状态。`1` = 正常已结算。其他值（如 `0` 未结算、`2` 作废）当前未出现 |
| `is_single_order` | int | `1` | 是否独立计费单元。`1` = 独立结算的台费；`0` = 非独立条目（合并结账/占位/转台的中间记录，此时 `ledger_count` 和 `real_table_use_seconds` 为 0） |
| `is_delete` | int | `0` | 逻辑删除标记。`0` = 未删除，`1` = 已逻辑删除 |
### 4.10 门店信息快照
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `siteProfile` | object | `{...}` | 门店信息快照（冗余），包含门店名称、地址、经纬度等 26 个子字段。结构与其他接口一致，不再逐字段展开 |
---
## 五、响应样例（单条记录）
```json
{
"siteProfile": { "id": 2790685415443269, "shop_name": "朗朗桌球", "..." : "..." },
"id": 2957924029058885,
"order_trade_no": 2957858167230149,
"site_id": 2790685415443269,
"tenant_id": 2790683160709957,
"member_id": 0,
"operator_id": 2790687322443013,
"operator_name": "收银员:郑丽珊",
"order_settle_id": 2957922914357125,
"ledger_unit_price": 48.0,
"ledger_name": "A17",
"ledger_count": 3600,
"ledger_amount": 48.0,
"order_pay_id": 0,
"create_time": "2025-11-09 23:35:57",
"is_delete": 0,
"site_table_id": 2793003705192517,
"site_table_area_id": 2791963794329671,
"tenant_table_area_id": 2791960001957765,
"is_single_order": 1,
"ledger_start_time": "2025-11-09 22:28:57",
"ledger_end_time": "2025-11-09 23:28:57",
"ledger_status": 1,
"site_table_area_name": "A区",
"real_table_charge_money": 0.0,
"used_card_amount": 0.0,
"adjust_amount": 0.0,
"real_table_use_seconds": 3600,
"coupon_promotion_amount": 48.0,
"service_money": 0.0,
"member_discount_amount": 0.0,
"last_use_time": "2025-11-09 23:28:57",
"salesman_name": "",
"salesman_user_id": 0,
"salesman_org_id": 0,
"mgmt_fee": 0.0,
"fee_total": 0.0,
"start_use_time": "2025-11-09 22:28:57",
"add_clock_seconds": 0
}
```
---
## 六、跨表关联
### 与助教流水（`assistant_service_records`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `order_trade_no` | `order_trade_no` | 同一订单下的台费与助教明细 |
| `order_settle_id` | `order_settle_id` | 同一结账事件 |
| `site_id` / `tenant_id` | `site_id` / `tenant_id` | 门店与租户维度一致 |
### 与台费优惠记录（`table_fee_discount_records`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `order_trade_no` | `order_trade_no` | 同一订单 |
| `order_settle_id` | `order_settle_id` | 同一结算单 |
| `adjust_amount` | `ledger_amount`（生效记录） | 台费流水的调账金额 = 台费优惠记录中有效记录的减免金额 |
### 与小票详情（`settlement_records`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `order_settle_id` | `settleList.id` / `orderSettleId` | 结算单 ID |
| `order_trade_no` | 订单号 | 订单维度关联 |
> 小票是顾客看到的整笔账单，台费流水是其中"台费项目"的明细拆解。
### 与会员档案
`member_id` 对应会员档案表的 `id`（`tenant_member_id`），可反查会员手机号、姓名、卡状态等。
### 与支付记录（`payment_transactions`）
`order_pay_id` 对应支付记录的 `id` 或 `relate_id`，可追踪付款方式（现金/微信/支付宝等）。
### 与台桌配置
`site_table_id` 对应台桌列表主键；`site_table_area_id` / `tenant_table_area_id` 分别对应门店级和租户级区域配置表。
<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/table_fee_transactions.md，按逻辑分组详解所有字段，含跨表关联
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
- 日期: 2026-02-14
- Prompt: P20260214-103000 — MD 占位符修正 + 临时文件清理
- 直接原因: v2 脚本自动插入的占位符描述需替换为正式中文业务说明
- 变更摘要: activity_discount_amount、order_consumption_type、real_service_money 三个新字段的占位符描述替换为正式中文说明
- 风险与验证: 纯文档文案修正，无运行时影响；验证：grep "新发现字段" 本文件应返回 0 结果
-->

234
apps/etl/pipelines/feiqiu/docs/api-reference/summary/tenant_goods_master.md Normal file
View File

@@ -0,0 +1,234 @@
# 租户商品主数据 — QueryTenantGoods
> 模块：`TenantGoods` · ODS 表：`tenant_goods_master` · 维度表（全量快照）
---
## 一、接口概述
查询租户（品牌）级别的商品主数据，包括商品基础信息、分类归属、价格配置、成本类型、库存管理开关等。每条记录对应一个品牌级商品定义，是商品维度的顶层主档。门店级商品（`store_goods_master`）通过 `tenant_goods_id` 引用本表的 `id`，实现"一个全局商品 → 多个门店商品"的映射。
| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /TenantGoods/QueryTenantGoods` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | `page` + `limit`（最大 100） |
| 时间范围 | 不需要（全量快照） |
| 响应数据路径 | `data.tenantGoodsList` |
---
## 二、请求
### 请求体（JSON）
```json
{
"costPriceType": 0,
"ableDiscount": -1,
"tenantGoodsStatus": 0,
"page": 1,
"limit": 100
}
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `costPriceType` | int | 是 | 成本价类型筛选。`0` = 全部，`1` = 固定成本价，`2` = 动态成本价 |
| `ableDiscount` | int | 是 | 是否可折扣筛选。`-1` = 全部，`1` = 允许折扣 |
| `tenantGoodsStatus` | int | 是 | 商品状态筛选。`0` = 全部，`1` = 正常/上架 |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |
---
## 三、响应结构
```
{
"code": 200,
"data": {
"list": [ { ... }, { ... } ],
"total": 156
}
}
```
`data.list` 中每个对象即为一条租户商品记录，共 31 个字段，按 9 个逻辑分组说明如下。
---
## 四、响应字段详解（31 个字段）
### 4.1 主键与租户维度
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `2791925230096261` | 商品档案主键 ID，唯一标识一条品牌级商品。在门店商品表（`store_goods_master`）中以 `tenant_goods_id` 引用，在销售记录中同名出现 |
| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID，所有记录相同。与其他业务表的 `tenant_id` 一致 |
### 4.2 分类维度
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `categoryName` | string | `"饮料"` | 一级分类名称（业务可读展示字段）。共约 14 种：零食、饮料、香烟、其他2、雪糕、酒水、球杆、小吃、面、槟榔等 |
| `goods_category_id` | int | `2790683528350539` | 一级分类 ID，与分类树（`stock_goods_category_tree`）中的 `id` 对应。共 9 个不同值，与 `categoryName` 一一映射 |
| `goods_second_category_id` | int | `2790683528350540` | 二级分类 ID，共 14 个不同值。对应分类树中 `pid` 为一级分类 ID 的子节点 |
### 4.3 商品基础信息
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `goods_name` | string | `"东方树叶"` | 商品名称，POS 前台展示、票据打印用。156 条记录全唯一 |
| `goods_number` | string | `"1"` | 商品内部编码（自定义货号），所有记录不重复，用于内部手工输入或导入导出匹配 |
| `unit` | string | `"瓶"` | 计量单位。常见值：包、瓶、个、份、根、盒、杯、桶、盘、支等（约 12 种） |
| `goods_cover` | string | `"https://oss.ficoo.vip/..."` | 商品封面图片 URL（OSS 存储），用于前端展示 |
| `pinyin_initial` | string | `"DFSY,DFSX"` | 拼音首字母/助记码，多别名用逗号分隔。用于前台拼音码快速检索 |
| `goods_bar_code` | string | `""` | 商品条形码（EAN 等），当前门店未维护，全部为空 |
| `remark_name` | string | `""` | 商品备注名/别名，预留字段，当前未使用 |
| `commodity_code` | string | `"10000028"` | 商品编码（对外编码），多条商品可共用同一编码，属于"系列编码"而非主键 |
| `commodityCode` | array | `["10000028"]` | 与 `commodity_code` 相同信息的数组形式（冗余存储），支持一商品多编码场景。当前列表长度均为 1 |
### 4.4 价格与折扣
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `market_price` | float | `8.0` | 商品标价/售价（标准销售单价），单位：元（人民币）。POS 系统默认销售价格 |
| `cost_price` | float | `0.0` | 成本价格，单位：元。大部分为 `0.0`（未录入），少数有值如 2.0、2.5、3.0 |
| `cost_price_type` | int | `1` | 成本价类型枚举：`1` = 固定成本价（手工维护），`2` = 动态成本价（按采购单平均价结转） |
| `min_discount_price` | float | `0.0` | 最低允许成交价（限价），单位：元。`0.0` 表示未设置底价。收银改价时系统校验不低于此值 |
| `able_discount` | int | `1` | 是否允许参与折扣：`1` = 允许。当前所有商品均可打折 |
### 4.5 库存与门店配置
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `is_warehousing` | int | `1` | 是否纳入库存管理：`1` = 参与库存管理，`0` = 不参与（如纯虚拟商品）。当前全部为 1 |
| `isInSite` | bool | `false` | 是否在当前门店启用/上架。本接口为租户级视角，全部为 `false`；门店级上架状态在 `store_goods_master` 中维护 |
| `able_site_transfer` | int | `2` | 是否允许门店间调拨：`2` = 不允许（绝大多数），`0` = 未配置（个别记录） |
| `sale_channel` | int | `1` | 销售渠道类型：`1` = 门店线下渠道。当前唯一值 |
| `goods_state` | int | `1` | 商品状态：`1` = 正常/上架。当前所有商品均为正常状态 |
### 4.6 佣金与提成
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `common_sale_royalty` | int | `0` | 普通销售提成配置，当前未启用，全部为 0 |
| `point_sale_royalty` | int | `0` | 积分销售提成/积分赠送规则配置，当前未启用，全部为 0 |
### 4.7 供应商
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `supplier_id` | int | `0` | 供应商 ID，用于关联供应商档案。当前所有商品未挂接供应商，全部为 0 |
| `out_goods_id` | int | `0` | 外部系统商品 ID（对接第三方平台用），当前未启用，全部为 0 |
### 4.8 时间元数据
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `create_time` | string | `"2025-07-15 17:13:15"` | 商品档案创建时间 |
| `update_time` | string\|null | `"2025-10-29 23:51:38"` | 最近修改时间。`null` 表示自创建以来未被修改（约 28 条为 null） |
### 4.9 状态与删除标志
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `is_delete` | int | `0` | 逻辑删除标志：`0` = 未删除，`1` = 已删除（保留档案但前台不展示） |
| `not_sale` | integer | `2` | 是否禁售：`2` = 否（正常销售），`1` = 是（禁止销售）。与 `goods_state` 配合使用 |
---
## 五、响应样例（单条记录）
```json
{
"categoryName": "饮料",
"isInSite": false,
"commodityCode": ["10000028"],
"id": 2791925230096261,
"tenant_id": 2790683160709957,
"goods_name": "东方树叶",
"goods_cover": "https://oss.ficoo.vip/admin/ZwS8fj_1753175129443.jpg",
"goods_state": 1,
"goods_category_id": 2790683528350539,
"unit": "瓶",
"supplier_id": 0,
"create_time": "2025-07-15 17:13:15",
"is_delete": 0,
"goods_second_category_id": 2790683528350540,
"cost_price": 0.0,
"market_price": 8.0,
"pinyin_initial": "DFSY,DFSX",
"goods_bar_code": "",
"able_discount": 1,
"min_discount_price": 0.0,
"commodity_code": "10000028",
"goods_number": "1",
"update_time": "2025-10-29 23:51:38",
"cost_price_type": 1,
"remark_name": "",
"sale_channel": 1,
"able_site_transfer": 2,
"common_sale_royalty": 0,
"point_sale_royalty": 0,
"is_warehousing": 1,
"out_goods_id": 0
}
```
---
## 六、跨表关联
### 与门店商品档案（`store_goods_master`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `id` | `tenant_goods_id` | 品牌级商品 → 门店级商品。一个全局商品可在多个门店生成多条门店商品记录 |
| `goods_category_id` | `goods_category_id` | 一级分类 ID 一致 |
| `goods_second_category_id` | `goods_second_category_id` | 二级分类 ID 一致 |
| `unit` | `unit` | 计量单位一致 |
### 与门店销售记录（`store_goods_sales_records`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `id` | `tenant_goods_id` | 品牌级商品 ID，用于追溯销售明细对应的全局商品定义 |
| `goods_category_id` | `tenant_goods_category_id` | 一级分类 ID |
### 与商品分类树（`stock_goods_category_tree`）
| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `goods_category_id` | `id`（一级节点） | 一级分类主键 |
| `goods_second_category_id` | `id`（二级节点） | 二级分类主键 |
### 与库存相关表
- `store_goods_master.id`（门店商品 ID）通过 `tenant_goods_id` 回溯到本表
- 库存汇总（`goods_stock_summary`）和库存变动（`goods_stock_movements`）通过 `siteGoodsId` 关联门店商品，再经 `tenant_goods_id` 间接关联本表
<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/tenant_goods_master.md，按逻辑分组详解所有 31 个字段，含跨表关联
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
- 日期: 2026-02-14
- Prompt: P20260214-060000 / P20260214-061000 — 全量 JSON 刷新 + MD 文档补全 + 数据路径修正
- 直接原因: 旧 JSON 样本仅含单条记录，缺少条件性字段；api_registry.json 中 17 个 data_path 与实际不符
- 变更摘要: 新增「响应数据路径」行；补全 1 个缺失字段（commoditycode）
- 风险与验证: 纯文档变更，无运行时影响；验证：python scripts/refresh_json_and_audit.py 输出 24/24 通过
- 日期: 2026-02-14
- Prompt: P20260214-130000 — 25 个 API 文档归档至 summary/ + 字段分组修正
- 直接原因: 4.8"时间与删除状态"组混入 not_sale（禁售标志）和 is_delete（删除标志），与时间无关
- 变更摘要: 4.8 拆分为"时间元数据"（2 字段）和 4.9"状态与删除标志"（2 字段）；not_sale 说明补充完整
- 风险与验证: 纯文档分组调整，无运行时影响；验证：统计各组字段数总和 = 31
-->

198
apps/etl/pipelines/feiqiu/docs/api-reference/summary/tenant_member_balance_overview.md Normal file
View File

@@ -0,0 +1,198 @@
# 会员余额总览 — TenantMemberBalanceOverview
> 模块：`MemberProfile` · ODS 表：`tenant_member_balance_overview`（待建） · 统计快照
---
## 一、接口概述
查询当前租户下所有会员卡的余额统计一览，按卡介质（电子卡/实体卡）和卡来源（充值卡/赠送卡）两个维度汇总，并提供各卡类型的明细分拆。该接口为新发现的 API，当前尚未建立 ODS 表，主要用于财务对账和会员资产概览。
| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /MemberProfile/TenantMemberBalanceOverview` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | 无分页 |
| 时间范围 | 不需要（实时快照） |
| 响应数据路径 | `data` |
---
## 二、请求
### 请求体
```json
null
```
该接口无需请求参数，直接返回当前租户的会员余额汇总。
---
## 三、响应结构
```
{
"code": 200,
"data": {
"totalPointBalance": 0.0,
"totalCardBalance": 356619.51,
"totalCardPrincipalBalance": 346917.34,
"electronicCardBalance": 356619.51,
"physicsCardBalance": 0,
"rechargeCardBalance": 90055.67,
"rechargeCardList": [ { ... } ],
"giveCardBalance": 266563.84,
"giveCardList": [ { ... } ]
}
}
```
`data` 对象包含 9 个顶层字段，其中 `rechargeCardList` 和 `giveCardList` 为卡类型明细数组。
---
## 四、响应字段详解（9 个字段）
### 4.1 总额汇总
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `totalPointBalance` | float | `0.0` | 全部会员积分余额合计（元）。当前门店未启用积分功能 |
| `totalCardBalance` | float | `356619.51` | 全部会员卡余额合计（元），含本金和赠送金额。等于 `electronicCardBalance` + `physicsCardBalance` |
| `totalCardPrincipalBalance` | float | `346917.34` | 全部会员卡本金余额合计（元），不含赠送部分 |
### 4.2 按卡介质分类
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `electronicCardBalance` | float | `356619.51` | 电子卡余额合计（元）。当前门店全部为电子卡 |
| `physicsCardBalance` | int | `0` | 实体卡余额合计（元）。当前门店未使用实体卡 |
### 4.3 按卡来源分类 — 充值卡
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `rechargeCardBalance` | float | `90055.67` | 充值卡余额合计（元），即会员主动充值获得的卡 |
| `rechargeCardList` | array | 见下表 | 充值卡按类型的明细列表 |
`rechargeCardList` 数组中每个元素：
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `cardTypeName` | string | `"储值卡"` | 卡类型名称。已知值：`储值卡`、`月卡` |
| `balance` | float | `86115.67` | 该类型卡的余额合计（元），含赠送部分 |
| `principalBalance` | float | `86115.67` | 该类型卡的本金余额合计（元） |
### 4.4 按卡来源分类 — 赠送卡
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `giveCardBalance` | float | `266563.84` | 赠送卡余额合计（元），即系统赠送/活动发放的卡 |
| `giveCardList` | array | 见下表 | 赠送卡按类型的明细列表 |
`giveCardList` 数组中每个元素：
| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `cardTypeName` | string | `"台费卡"` | 卡类型名称。已知值：`消费卡`、`年卡`、`台费卡`、`活动抵用券`、`酒水卡` |
| `balance` | float | `247875.46` | 该类型卡的余额合计（元），含赠送部分 |
| `principalBalance` | float | `247875.46` | 该类型卡的本金余额合计（元） |
---
## 五、响应样例
```json
{
"totalPointBalance": 0.0,
"totalCardBalance": 356619.51,
"totalCardPrincipalBalance": 346917.34,
"electronicCardBalance": 356619.51,
"physicsCardBalance": 0,
"rechargeCardBalance": 90055.67,
"rechargeCardList": [
{
"cardTypeName": "储值卡",
"balance": 86115.67,
"principalBalance": 86115.67
},
{
"cardTypeName": "月卡",
"balance": 3940.0,
"principalBalance": 3940.0
}
],
"giveCardBalance": 266563.84,
"giveCardList": [
{
"cardTypeName": "消费卡",
"balance": 0,
"principalBalance": 0
},
{
"cardTypeName": "年卡",
"balance": 7.0,
"principalBalance": 7.0
},
{
"cardTypeName": "台费卡",
"balance": 247875.46,
"principalBalance": 247875.46
},
{
"cardTypeName": "活动抵用券",
"balance": 14972.43,
"principalBalance": 5270.26
},
{
"cardTypeName": "酒水卡",
"balance": 3708.95,
"principalBalance": 3708.95
}
]
}
```
---
## 六、跨表关联
该接口返回的是租户级汇总统计，不包含会员个体信息，与业务表的关联为间接关系。
| 潜在关联 | 说明 |
|----------|------|
| `totalCardBalance` | 应等于会员卡列表中所有卡的余额之和 |
| `rechargeCardList` / `giveCardList` 中的 `cardTypeName` | 对应会员卡类型配置中的卡类型名称 |
| `balance` vs `principalBalance` 差额 | 反映赠送金额部分，与充值记录中的赠送金额对应 |
> 当前该接口尚未建立 ODS 表，暂无 ETL 入库流程。该接口适合用于 DWS 层的会员资产快照统计，如后续需要持久化，建议在 `billiards_dws` schema 下新建汇总表。
### 金额校验关系
- `totalCardBalance` = `electronicCardBalance` + `physicsCardBalance`
- `totalCardBalance` = `rechargeCardBalance` + `giveCardBalance`
- 各 `*CardList` 中 `balance` 之和应等于对应的 `*CardBalance`
<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/tenant_member_balance_overview.md，按逻辑分组详解 9 个字段及嵌套结构，含金额校验关系
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
- 日期: 2026-02-14
- Prompt: P20260214-060000 / P20260214-061000 — 全量 JSON 刷新 + MD 文档补全 + 数据路径修正
- 直接原因: 旧 JSON 样本仅含单条记录，缺少条件性字段；api_registry.json 中 17 个 data_path 与实际不符
- 变更摘要: 新增「响应数据路径」行（记录 API 实际返回的数据路径）
- 风险与验证: 纯文档变更，无运行时影响；验证：python scripts/refresh_json_and_audit.py 输出 24/24 通过
- 日期: 2026-02-14
- Prompt: P20260214-083000 — ODS 表标注从"无"改为"待建"
- 直接原因: 用户确认该接口需要建 ODS 表，且 rechargeCardList/giveCardList 需展开
- 变更摘要: 头部 ODS 表标注从"无（新发现 API，尚未建表）"改为"tenant_member_balance_overview（待建）"
- 风险与验证: 纯文档标注变更；验证：grep "待建" docs/api-reference/tenant_member_balance_overview.md
-->