ODS 完成

2025-11-30 07:19:05 +08:00
parent b9b050bb5d
commit a6ad343092
81 changed files with 15695 additions and 227180 deletions
--- a/非球接口API.md
+++ b/非球接口API.md
@@ -0,0 +1,751 @@
+## 1. 总体概览
+
+### 1.1 服务地址与版本
+
+* Base URL（统一前缀）：
+  `https://pc.ficoo.vip/apiprod/admin/v1` 
+* 所有接口路径均在该前缀下，例如：
+
+  * 助教流水：`/AssistantPerformance/GetOrderAssistantDetails`
+  * 门店商品档案1：`/TenantGoods/GetGoodsInventoryList`
+
+统一完整 URL 形式：
+
+```text
+https://pc.ficoo.vip/apiprod/admin/v1{path}
+```
+
+例如：
+
+```text
+https://pc.ficoo.vip/apiprod/admin/v1/AssistantPerformance/GetOrderAssistantDetails
+```
+
+### 1.2 认证方式
+
+* 认证方式：Bearer Token（JWT）
+
+* HTTP Header：
+
+  ```http
+  Authorization: Bearer {access_token}
+  ```
+
+* Token 获取方式：由 Ficoo 系统颁发（脚本目前通过环境变量 `FICOO_TOKEN` 或命令行 `--token` 传入）。
+
+* 注意：
+
+  * Token 为敏感信息，不要写死在代码仓库或文档中。通过CLI或.env配置。
+  * 示例中出现的实际 JWT 请在内部全部替换成占位符。
+
+### 1.3 请求方式与编码
+
+* HTTP Method：目前脚本全部使用 `POST`。
+* 请求体：`Content-Type: application/json`，JSON 编码，UTF-8。
+* 响应体：JSON，UTF-8。
+
+示例（来自现有 curl，经脱敏后）：
+
+```bash
+curl "https://pc.ficoo.vip/apiprod/admin/v1/AssistantPerformance/GetOrderAssistantDetails" \
+  -H "Authorization: Bearer <your_token>" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/plain, */*" \
+  --data-raw '{
+    "siteId": 2790685415443269,
+    "startTime": "2025-11-01 08:00:00",
+    "endTime":   "2025-11-08 08:00:00",
+    "IsConfirm": 2,
+    "page": 1,
+    "limit": 20
+  }'
+```
+
+### 1.4 通用 Header 建议（必须）
+
+所有接口均为内部管理后台接口，调用时必须携带以下核心请求头：
+
+Header 名称	示例值	说明
+Authorization	Bearer <access_token>	鉴权，使用 Bearer Token
+Content-Type	application/json	请求体为 JSON 编码
+Accept	application/json, text/plain, */*	客户端期望接收 JSON 响应
+
+注意：<access_token> 为系统颁发的 JWT，文档和示例中一律使用占位符，不要写实际 token。
+
+#### 1.4.2 浏览器兼容性请求头（建议统一保留）
+
+为降低前置网关 / 安全策略的拦截风险，系统当前前端及采集脚本在调用接口时，统一携带一组“浏览器兼容性请求头”，用于模拟真实浏览器环境。这些头部对业务语义无强制要求，但推荐所有客户端统一保留：
+
+Header 名称	示例值（仅示意）	说明
+Origin	https://pc.ficoo.vip	请求来源域名，前端浏览器自动携带
+Referer	https://pc.ficoo.vip/	页面来源地址
+User-Agent	Mozilla/5.0 (Windows NT 10.0; Win64; x64)... Chrome/141.0.0.0 Safari/537.36	模拟 Chrome 浏览器 UA
+Accept-Language	zh-CN,zh;q=0.9	语言偏好
+sec-ch-ua	"Google Chrome";v="141", "Not?A_Brand";v="8", "Chromium";v="141"	浏览器 User-Agent Client Hints
+sec-ch-ua-platform	"Windows"	同上，标识操作系统平台
+sec-ch-ua-mobile	?0	同上，标识是否移动端
+sec-fetch-site	same-origin	Fetch Metadata，标识请求来源站点关系
+sec-fetch-mode	cors	Fetch Metadata，标识跨域模式
+sec-fetch-dest	empty	Fetch Metadata，标识资源类型
+priority	u=1, i	HTTP 优先级提示，用于底层网络调度
+X-Requested-With	XMLHttpRequest	传统 AJAX 头部，部分后端可能用来识别异步请求
+DNT（可选）	1	Do Not Track，浏览器隐私偏好，业务逻辑不依赖
+
+#### 1.4.3 示例请求头（推荐组合）
+
+下面是一个推荐的完整请求头示例，供客户端实现参考（已脱敏）：
+
+POST /apiprod/admin/v1/AssistantPerformance/GetOrderAssistantDetails HTTP/1.1
+Host: pc.ficoo.vip
+Authorization: Bearer <access_token>
+Content-Type: application/json
+Accept: application/json, text/plain, */*
+Origin: https://pc.ficoo.vip
+Referer: https://pc.ficoo.vip/
+User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)... Chrome/141.0.0.0 Safari/537.36
+Accept-Language: zh-CN,zh;q=0.9
+sec-ch-ua: "Google Chrome";v="141", "Not?A_Brand";v="8", "Chromium";v="141"
+sec-ch-ua-platform: "Windows"
+sec-ch-ua-mobile: ?0
+sec-fetch-site: same-origin
+sec-fetch-mode: cors
+sec-fetch-dest: empty
+priority: u=1, i
+X-Requested-With: XMLHttpRequest
+DNT: 1
+
+
+## 2. 通用协议约定
+
+### 2.1 时间格式与时区
+
+脚本中所有时间字段使用统一字符串格式：
+
+```text
+"YYYY-MM-DD HH:MM:SS"
+例如："2025-10-01 00:00:00"
+```
+
+常见时间字段：
+
+* `startTime` / `endTime`：一般为创建时间或业务发生时间段
+* `rangeStartTime` / `rangeEndTime`：多用于结账记录等“区间查询”
+* `StartPayTime` / `EndPayTime`：支付时间范围（支付流水）
+
+时区未在响应中显式标识，默认可按北京时间（Asia/Shanghai）处理。
+
+### 2.2 分页约定
+
+* 通用分页参数：
+
+  * `page`：页码，从 1 开始
+  * `limit`：每页条数，例如 20 或 100
+* Python 脚本支持配置：
+
+  ````python
+  PAGE_START = 1
+  PAGE_END   = 2
+  PAGE_LIMIT = 100
+  ``` :contentReference[oaicite:7]{index=7}  
+
+  ````
+* 采集策略：遍历 page 从 `PAGE_START` 到 `PAGE_END`，每页将列表数据合并写入一个 JSON 文件。
+
+**特殊情况：**
+
+* `小票详情`（/Order/GetOrderSettleTicketNew）本身是“单据级”明细接口，从业务上看不分页，通过 `orderSettleId` 或 `orderSettleIdList` 批量请求。脚本中单独针对该接口做了循环调用设计。
+
+### 2.3 通用响应结构
+
+从样本 JSON 看，多数接口返回结构类似：
+
+```json
+{
+  "code": 0,
+  "data": {
+    "...": "...",
+    "total": 438,
+    "<listField>": [ ... ]
+  }
+}
+```
+
+示例（会员档案，字段名略）：
+
+```json
+{
+  "code": 0,
+  "data": {
+    "total": 438,
+    "tenantMemberInfos": [
+      {
+        "id": 2799...,
+        "create_time": "2025-11-08 01:29:33",
+        "member_card_grade_code": 1,
+        "mobile": "138****1234",
+        "nickname": "xxx",
+        ...
+      }
+    ]
+  }
+}
+```
+
+注意：
+
+* 列表字段名称并不统一：可能是 `list` / `rows` / `records` / `items` / `dataList`，也可能是业务专有名（例如 `tenantMemberInfos`）。脚本中专门写了一个通用提取函数 `extract_list` 来处理上述几种常见命名。
+* 部分接口可能完全不分页，只返回单条对象或嵌套结构，需按实际响应处理。
+
+---
+
+## 3. 通用参数说明
+
+脚本顶部有一个公共参数池 `PARAMS`，各个接口在构造请求时会从中按需取值。这些字段可以视为“通用过滤条件”和“业务枚举”。
+
+### 3.1 门店与组织
+
+* `siteId`：门店 ID（int64）
+
+  * 单门店场景为一个长整型；
+  * 在门店商品档案 1/2 中，脚本会自动转成数组形式：`[siteId]`。
+* `siteTableAreaIdList`：台桌区域 ID 列表（array<int>），用于结账记录筛选具体区域。
+
+### 3.2 时间区间
+
+* `startTime` / `endTime`：通用时间范围
+* `rangeStartTime` / `rangeEndTime`：结账类接口使用
+* `StartPayTime` / `EndPayTime`：支付流水接口使用
+
+全部为字符串格式 `"YYYY-MM-DD HH:MM:SS"`。
+
+### 3.3 业务枚举类字段（常见）
+
+以下均为整数枚举，具体含义需结合业务系统配置或你提供的 .md 报告来确定：
+
+* `IsConfirm`：助教业绩是否确认（示例值：2）
+* `OnlinePayChannel`：线上支付渠道（0 表示全部 / 默认）
+* `paymentMethod`：支付方式（现金 / 微信 / 支付宝 / …）
+* `relateType`：关联类型（支付记录）
+* `isSaleManUser`：是否按业务员维度汇总台费流水
+* `isSalesBind`：门店销售记录中，是否按销售绑定过滤
+* `goodsSalesType`：商品销售维度（按单品 / 分类 / 时间等）
+* `costPriceType`：成本价类型
+* `ableDiscount`：是否可打折（-1 代表全部）
+* `tenantGoodsStatus`：商品状态（启用 / 停用）
+* `goodsSecondCategoryId`：二级分类 ID 列表
+* `goodsState`：商品状态（在售 / 已停售）
+* `enableStatus`：启用状态
+* `existsGoodsStock`：是否仅查有库存商品
+* `couponChannel`：券来源渠道
+* `couponUseStatus`：券使用状态
+* `settleType`：结账类型 / 账单类型
+* `stockType`：库存变动类型（出库 / 入库 / 盘点等）
+
+### 3.4 小票详情专用字段
+
+* `orderSettleId`：单张结账小票对应的结算 ID
+* `orderSettleIdList`：结算 ID 列表（脚本中大量示例 ID），支持批量拉取小票详情。
+
+---
+
+## 4. 批量采集脚本使用说明
+
+### 4.2 Token 配置
+
+支持两种方式（优先级从高到低）：
+
+1. 命令行参数：
+
+   ```bash
+   python fetch_feiqiu_endpoints.py --token "Bearer x.y.z"
+   # 或仅传 bare token，脚本会自动补上 Bearer 前缀
+   ```
+
+2. 也支持在同目录 `.env` 文件中设置 `FICOO_TOKEN`（依赖 `python-dotenv`）。
+
+若两者都缺失，脚本会抛出异常并退出。
+
+### 4.3 配置要调用的接口
+
+脚本中通过 `API_NAME` 控制要调用的接口，可以是单个字符串或字符串列表：
+
+```python
+# 示例：只跑门店商品档案 1 和 2
+API_NAME = ["门店商品档案1", "门店商品档案2"]
+```
+
+可选值即 `ENDPOINTS` 字典中的所有键（见后文接口清单）。
+
+### 4.4 分页与时间范围配置
+
+在 `PARAMS` 和分页配置区集中调整：
+
+````python
+PAGE_START = 1
+PAGE_END   = 2
+PAGE_LIMIT = 100
+
+PARAMS = {
+    "startTime": "2025-10-01 00:00:00",
+    "endTime":   "2025-11-10 00:00:00",
+    "rangeStartTime": "...",
+    "rangeEndTime":   "...",
+    "StartPayTime":   "...",
+    "EndPayTime":     "...",
+    "siteId": 2790685415443269,
+    ...
+}
+``` :contentReference[oaicite:17]{index=17}  
+
+### 4.5 输出位置与命名
+
+- 输出目录：可配置
+- 文件命名列表：
+接口 Path 与建议 JSON 文件名对照表
+
+| Request Path                                         | New JSON Filename                         | Brief Description                                    |
+| ---------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------- |
+| `/MemberProfile/GetTenantMemberList`                 | `member_profiles.json`                    | 会员主档案数据，每条记录对应租户下的一位会员/账户，包括会员基本信息、等级、联系方式等。         |
+| `/MemberProfile/GetMemberCardBalanceChange`          | `member_balance_changes.json`             | 会员账户余额变动流水，每条记录对应一次余额增减（充值、消费、调账等）。                  |
+| `/MemberProfile/GetTenantMemberCardList`             | `member_stored_value_cards.json`          | 会员储值类卡片列表，每条记录是一张已开通的储值卡及其规则配置（卡种、折扣、适用范围等）。         |
+| `/Site/GetRechargeSettleList`                        | `recharge_settlements.json`               | 会员充值结算流水，每条记录是一笔充值订单的结算信息（金额、支付方式、时间等）。              |
+| `/AssistantPerformance/GetAbolitionAssistant`        | `assistant_cancellation_records.json`     | 助教废除/取消流水，每条记录表示某张台桌上一次助教被移除/废除的操作，含门店与台桌信息。         |
+| `/AssistantPerformance/GetOrderAssistantDetails`     | `assistant_service_records.json`          | 助教服务流水明细，每条记录对应一次助教服务（单次上台/服务时段），可关联订单、结账、小票等。       |
+| `/PersonnelManagement/SearchAssistantInfo`           | `assistant_accounts_master.json`          | 助教账号/人事档案维表，每条记录对应一名助教账号，包含人员基本信息、在职状态、计费与权限配置等。     |
+| `/Table/GetSiteTables`                               | `site_tables_master.json`                 | 门店台桌维表，每条记录对应一张球台/包厢，包含台号、区域、状态、收费策略等基础配置。           |
+| `/Site/GetTaiFeeAdjustList`                          | `table_fee_discount_records.json`         | 台费打折/调账流水，每条记录是一笔针对台费的手工折扣或金额调整，关联订单与台桌。             |
+| `/Site/GetSiteTableOrderDetails`                     | `table_fee_transactions.json`             | 台费计费流水明细，每条记录对应一次台费收费明细，可按订单、台桌、时长等维度分析。             |
+| `/TenantGoods/QueryTenantGoods`                      | `tenant_goods_master.json`                | 品牌维度的商品档案，每条记录是一个商品在租户层的主数据（名称、分类、定价等），供各门店复用。       |
+| `/PackageCoupon/QueryPackageCouponList`              | `group_buy_packages.json`                 | 团购套餐定义列表，每条记录是一种团购券/套餐的规则配置（名称、面值、有效期、适用时段等）。        |
+| `/Site/GetSiteTableUseDetails`                       | `group_buy_redemption_records.json`       | 团购套餐使用流水，每条记录对应一次团购券在门店被核销/使用的明细，含台桌与订单信息。           |
+| `/Order/GetOrderSettleTicketNew`                     | `settlement_ticket_details.json`          | 结账小票打印详情，每条记录对应一张结算小票的完整快照，包括整单金额、会员、支付方式及台费/商品分项明细。 |
+| `/Promotion/GetOfflineCouponConsumePageList`         | `platform_coupon_redemption_records.json` | 平台券（如美团等）验券流水，每条记录对应一次第三方团购券在门店的核销事件。                |
+| `/GoodsStockManage/QueryGoodsOutboundReceipt`        | `goods_stock_movements.json`              | 商品库存变动流水，每条记录是某个门店商品的一次出入库/调整事件，可追溯至库存汇总与销售记录。       |
+| `/TenantGoodsCategory/QueryPrimarySecondaryCategory` | `stock_goods_category_tree.json`          | 库存模块使用的商品分类树，每条记录是一个商品分类节点，形成一级/二级分类层级结构。            |
+| `/TenantGoods/GetGoodsStockReport`                   | `goods_stock_summary.json`                | 门店商品库存汇总，每条记录对应一个门店商品在查询区间内的库存现状与汇总指标。               |
+| `/PayLog/GetPayLogListPage`                          | `payment_transactions.json`               | 门店支付流水，每条记录是一笔支付交易（含支付方式、渠道、金额、关联订单等）。               |
+| `/Site/GetAllOrderSettleList`                        | `settlement_records.json`                 | 门店结账记录，每条记录是一笔结算单的汇总信息，可与小票详情、支付记录等联查。               |
+| `/Order/GetRefundPayLogList`                         | `refund_transactions.json`                | 退款支付流水，每条记录是一笔已发生的退款交易，包含退款金额、业务来源、支付通道等。            |
+| `/TenantGoods/GetGoodsSalesList`                     | `store_goods_sales_records.json`          | 门店商品销售流水，每条记录对应一条商品销售明细，可关联支付记录、结账记录与库存变动。           |
+
+
+* 日志目录：可配置，按接口名单独记录一份日志，包含每次调用的 curl 命令和原始请求/响应快照（Authorization 可选择打码）。
+
+### 4.6 调用重试与限流策略
+
+脚本中使用了 `requests.adapters.HTTPAdapter` + `urllib3.Retry`：
+
+* 重试总次数：3
+* 指定的可重试状态码：`429, 500, 502, 503, 504`
+* 退避因子：0.5（指数退避）
+* 每次请求后随机 `1–4` 秒延迟，减轻服务器压力。
+
+---
+
+## 5. 接口清单总览
+
+以下均为 `POST` 接口，路径相对于 Base URL。
+
+| 模块      | 接口名称    | Path                                                 | 是否分页（按脚本设计）       |
+| ------- | ------- | ---------------------------------------------------- | ----------------- |
+| 会员      | 会员档案    | `/MemberProfile/GetTenantMemberList`                 | 是（`page`,`limit`） |
+| 会员      | 余额变更记录  | `/MemberProfile/GetMemberCardBalanceChange`          | 是                 |
+| 会员      | 储值卡列表   | `/MemberProfile/GetTenantMemberCardList`             | 是                 |
+| 会员 / 充值 | 充值记录    | `/Site/GetRechargeSettleList`                        | 是                 |
+| 助教      | 助教废除    | `/AssistantPerformance/GetAbolitionAssistant`        | 是                 |
+| 助教      | 助教流水    | `/AssistantPerformance/GetOrderAssistantDetails`     | 是                 |
+| 助教      | 助教账号1   | `/PersonnelManagement/SearchAssistantInfo`           | 是                 |
+| 助教      | 助教账号2   | `/PersonnelManagement/SearchAssistantInfo`           | 是                 |
+| 台桌      | 台桌列表    | `/Table/GetSiteTables`                               | 是                 |
+| 台费      | 台费打折    | `/Site/GetTaiFeeAdjustList`                          | 是                 |
+| 台费      | 台费流水    | `/Site/GetSiteTableOrderDetails`                     | 是                 |
+| 商品      | 商品档案    | `/TenantGoods/QueryTenantGoods`                      | 是                 |
+| 团购      | 团购套餐    | `/PackageCoupon/QueryPackageCouponList`              | 是                 |
+| 团购      | 团购套餐流水  | `/Site/GetSiteTableUseDetails`                       | 是                 |
+| 订单      | 小票详情    | `/Order/GetOrderSettleTicketNew`                     | 否（单笔/批量按 ID）      |
+| 营销 / 券  | 平台验券记录  | `/Promotion/GetOfflineCouponConsumePageList`         | 是                 |
+| 库存      | 库存变化记录1 | `/GoodsStockManage/QueryGoodsOutboundReceipt`        | 是                 |
+| 库存      | 库存变化记录2 | `/TenantGoodsCategory/QueryPrimarySecondaryCategory` | 是                 |
+| 库存      | 库存汇总    | `/TenantGoods/GetGoodsStockReport`                   | 是                 |
+| 支付      | 支付记录    | `/PayLog/GetPayLogListPage`                          | 是                 |
+| 结账      | 结账记录    | `/Site/GetAllOrderSettleList`                        | 是                 |
+| 订单      | 退款记录    | `/Order/GetRefundPayLogList`                         | 是                 |
+| 商品 / 门店 | 门店商品档案1 | `/TenantGoods/GetGoodsInventoryList`                 | 是                 |
+| 商品 / 销售 | 门店销售记录  | `/TenantGoods/GetGoodsSalesList`                     | 是                 |
+
+---
+
+## 6. 接口详情（参数级，按模块整理）
+
+下面只写“请求参数层面”的反推说明；响应字段请结合etl_billiards/tests/source-data-doc目录下的 `.json` + `.md` 报告使用。
+
+### 6.1 助教相关接口
+
+#### 6.1.1 助教流水 – GetOrderAssistantDetails
+
+* 中文名称：助教流水
+* Path：`/AssistantPerformance/GetOrderAssistantDetails`
+* Method：POST
+* 是否分页：是
+
+**请求参数：**
+
+| 字段名         | 类型     | 必填 | 说明                            |
+| ----------- | ------ | -- | ----------------------------- |
+| `siteId`    | int64  | 是  | 门店 ID                         |
+| `startTime` | string | 是  | 起始时间（含），`YYYY-MM-DD HH:MM:SS` |
+| `endTime`   | string | 是  | 结束时间（含）                       |
+| `IsConfirm` | int    | 否  | 业绩确认状态（枚举，具体含义待确认）            |
+| `page`      | int    | 是  | 页码，从 1 开始                     |
+| `limit`     | int    | 是  | 每页条数                          |
+
+
+#### 6.1.2 助教废除 – GetAbolitionAssistant
+
+* Path：`/AssistantPerformance/GetAbolitionAssistant`
+* Method：POST
+* 是否分页：是
+
+**请求参数：**
+
+| 字段名         | 类型     | 必填 | 说明    |
+| ----------- | ------ | -- | ----- |
+| `startTime` | string | 是  | 起始时间  |
+| `endTime`   | string | 是  | 结束时间  |
+| `siteId`    | int64  | 是  | 门店 ID |
+| `page`      | int    | 是  | 页码    |
+| `limit`     | int    | 是  | 每页条数  |
+
+#### 6.1.3 助教账号1 / 2 – SearchAssistantInfo
+
+* Path：`/PersonnelManagement/SearchAssistantInfo`
+* 两个名称（助教账号1/2）仅是脚本中拆分；实际路径一致，可以视为不同筛选组合。
+
+**请求参数：**
+
+| 字段名               | 类型    | 必填 | 说明           |
+| ----------------- | ----- | -- | ------------ |
+| `siteId`          | int64 | 是  | 门店 ID        |
+| `workStatusEnum`  | int   | 否  | 在职 / 离职状态    |
+| `dingTalkSynced`  | int   | 否  | 是否同步钉钉       |
+| `leaveId`         | int   | 否  | 请假状态/ID（待确认） |
+| `criticismStatus` | int   | 否  | 处分/批评状态（待确认） |
+| `signStatus`      | int   | 否  | 签到状态（待确认）    |
+| `page`            | int   | 是  | 页码           |
+| `limit`           | int   | 是  | 每页条数         |
+
+### 6.2 台桌 / 台费接口
+
+#### 6.2.1 台桌列表 – GetSiteTables
+
+* Path：`/Table/GetSiteTables`
+* Method：POST
+* 是否分页：是
+
+**请求参数：** 
+
+| 字段名                | 类型  | 必填 | 说明           |
+| ------------------ | --- | -- | ------------ |
+| `showStatus`       | int | 否  | 展示状态（启用/停用等） |
+| `virtualTableType` | int | 否  | 虚拟台桌类型       |
+| `page`             | int | 是  | 页码           |
+| `limit`            | int | 是  | 每页条数         |
+
+#### 6.2.2 台费流水 – GetSiteTableOrderDetails
+
+* Path：`/Site/GetSiteTableOrderDetails`
+* Method：POST
+* 是否分页：是
+
+**请求参数：**
+
+| 字段名             | 类型     | 必填 | 说明          |
+| --------------- | ------ | -- | ----------- |
+| `startTime`     | string | 是  | 起始时间        |
+| `endTime`       | string | 是  | 结束时间        |
+| `siteId`        | int64  | 是  | 门店 ID       |
+| `isSaleManUser` | int    | 否  | 是否按销售人员维度过滤 |
+| `page`          | int    | 是  | 页码          |
+| `limit`         | int    | 是  | 每页条数        |
+
+#### 6.2.3 台费打折 – GetTaiFeeAdjustList
+
+* Path：`/Site/GetTaiFeeAdjustList`
+* Method：POST
+
+**请求参数：** 
+
+| 字段名         | 类型     | 必填 | 说明    |
+| ----------- | ------ | -- | ----- |
+| `startTime` | string | 是  | 起始时间  |
+| `endTime`   | string | 是  | 结束时间  |
+| `siteId`    | int64  | 是  | 门店 ID |
+| `page`      | int    | 是  | 页码    |
+| `limit`     | int    | 是  | 每页条数  |
+
+### 6.3 会员相关接口
+
+#### 6.3.1 会员档案 – GetTenantMemberList
+
+* Path：`/MemberProfile/GetTenantMemberList`
+* Method：POST
+* 是否分页：是
+
+**请求参数：** 
+
+| 字段名                   | 类型  | 必填 | 说明        |
+| --------------------- | --- | -- | --------- |
+| `isMemberInBlackList` | int | 否  | 是否黑名单     |
+| `status_Revoked`      | int | 否  | 会员状态（注销等） |
+| `page`                | int | 是  | 页码        |
+| `limit`               | int | 是  | 每页条数      |
+
+> 备注：样本 JSON 显示列表字段为 `tenantMemberInfos`，包含 `id`、`system_member_id`、`member_card_grade_code` 等字段，具体字段含义详见对应 `.md` 报告。
+
+#### 6.3.2 余额变更记录 – GetMemberCardBalanceChange
+
+* Path：`/MemberProfile/GetMemberCardBalanceChange`
+
+**请求参数：**
+
+| 字段名         | 类型     | 必填 | 说明     |
+| ----------- | ------ | -- | ------ |
+| `startTime` | string | 是  | 变更起始时间 |
+| `endTime`   | string | 是  | 变更结束时间 |
+| `fromType`  | int    | 否  | 变更来源类型 |
+| `page`      | int    | 是  | 页码     |
+| `limit`     | int    | 是  | 每页条数   |
+
+#### 6.3.3 储值卡列表 – GetTenantMemberCardList
+
+* Path：`/MemberProfile/GetTenantMemberCardList`
+
+**请求参数：**
+
+| 字段名               | 类型    | 必填 | 说明    |
+| ----------------- | ----- | -- | ----- |
+| `siteId`          | int64 | 是  | 门店 ID |
+| `cardPhysicsType` | int   | 否  | 卡实体类型 |
+| `status`          | int   | 否  | 卡状态   |
+| `page`            | int   | 是  | 页码    |
+| `limit`           | int   | 是  | 每页条数  |
+
+#### 6.3.4 充值记录 – GetRechargeSettleList
+
+* Path：`/Site/GetRechargeSettleList`
+
+**请求参数：**
+
+| 字段名              | 类型     | 必填 | 说明           |
+| ---------------- | ------ | -- | ------------ |
+| `settleType`     | int    | 否  | 结账/充值类型      |
+| `paymentMethod`  | int    | 否  | 支付方式         |
+| `rangeStartTime` | string | 是  | 充值时间起        |
+| `rangeEndTime`   | string | 是  | 充值时间止        |
+| `siteId`         | int64  | 是  | 门店 ID        |
+| `isFirst`        | int    | 否  | 是否首单/首充（待确认） |
+| `page`           | int    | 是  | 页码           |
+| `limit`          | int    | 是  | 每页条数         |
+
+### 6.4 支付 / 结账 / 订单接口
+
+#### 6.4.1 支付记录 – GetPayLogListPage
+
+* Path：`/PayLog/GetPayLogListPage`
+
+**请求参数：**
+
+| 字段名                | 类型     | 必填 | 说明    |
+| ------------------ | ------ | -- | ----- |
+| `StartPayTime`     | string | 是  | 支付时间起 |
+| `EndPayTime`       | string | 是  | 支付时间止 |
+| `siteId`           | int64  | 是  | 门店 ID |
+| `OnlinePayChannel` | int    | 否  | 支付渠道  |
+| `paymentMethod`    | int    | 否  | 支付方式  |
+| `relateType`       | int    | 否  | 关联类型  |
+| `page`             | int    | 是  | 页码    |
+| `limit`            | int    | 是  | 每页条数  |
+
+#### 6.4.2 结账记录 – GetAllOrderSettleList
+
+* Path：`/Site/GetAllOrderSettleList`
+
+**请求参数：**
+
+| 字段名                   | 类型         | 必填 | 说明       |
+| --------------------- | ---------- | -- | -------- |
+| `settleType`          | int        | 否  | 结账类型     |
+| `rangeStartTime`      | string     | 是  | 结账时间起    |
+| `rangeEndTime`        | string     | 是  | 结账时间止    |
+| `siteId`              | int64      | 是  | 门店 ID    |
+| `siteTableAreaIdList` | array<int> | 否  | 台桌区域ID列表 |
+| `page`                | int        | 是  | 页码       |
+| `limit`               | int        | 是  | 每页条数     |
+
+#### 6.4.3 退款记录 – GetRefundPayLogList
+
+* Path：`/Order/GetRefundPayLogList`
+
+**请求参数：**
+
+| 字段名         | 类型     | 必填 | 说明    |
+| ----------- | ------ | -- | ----- |
+| `startTime` | string | 是  | 退款时间起 |
+| `endTime`   | string | 是  | 退款时间止 |
+| `page`      | int    | 是  | 页码    |
+| `limit`     | int    | 是  | 每页条数  |
+
+#### 6.4.4 小票详情 – GetOrderSettleTicketNew
+
+* Path：`/Order/GetOrderSettleTicketNew`
+* Method：POST
+* 设计上非分页接口，每次查询一个 `orderSettleId`，但可以在客户端循环批量调用。
+
+**请求参数：**
+
+| 字段名             | 类型    | 必填 | 说明           |
+| --------------- | ----- | -- | ------------ |
+| `orderSettleId` | int64 | 是  | 结算单 ID（单个小票） |
+
+脚本级批量用法：遍历 `orderSettleIdList`，每个 ID 调用一次该接口，将结果追加到数组中再保存。
+
+### 6.5 商品 / 库存 / 销售接口
+
+#### 6.5.1 商品档案 – QueryTenantGoods
+
+* Path：`/TenantGoods/QueryTenantGoods`
+
+**请求参数：**
+
+| 字段名                 | 类型  | 必填 | 说明             |
+| ------------------- | --- | -- | -------------- |
+| `costPriceType`     | int | 否  | 成本价类型          |
+| `ableDiscount`      | int | 否  | 是否可打折（-1 表示全部） |
+| `tenantGoodsStatus` | int | 否  | 商品状态           |
+| `page`              | int | 是  | 页码             |
+| `limit`             | int | 是  | 每页条数           |
+
+#### 6.5.2 门店商品档案1 – GetGoodsInventoryList
+
+* Path：`/TenantGoods/GetGoodsInventoryList`
+
+**请求参数：**
+
+| 字段名                     | 类型           | 必填 | 说明                        |
+| ----------------------- | ------------ | -- | ------------------------- |
+| `goodsSecondCategoryId` | array<int>   | 否  | 二级分类 ID                   |
+| `goodsState`            | int          | 否  | 商品状态                      |
+| `enableStatus`          | int          | 否  | 启用状态                      |
+| `siteId`                | array<int64> | 是  | 门店 ID 列表（脚本会把单个 ID 包装为数组） |
+| `existsGoodsStock`      | int          | 否  | 是否仅查有库存                   |
+| `page`                  | int          | 是  | 页码                        |
+| `limit`                 | int          | 是  | 每页条数                      |
+
+
+#### 6.5.4 门店销售记录 – GetGoodsSalesList
+
+* Path：`/TenantGoods/GetGoodsSalesList`
+
+**请求参数：**
+
+| 字段名              | 类型     | 必填 | 说明             |
+| ---------------- | ------ | -- | -------------- |
+| `isSalesBind`    | int    | 否  | 是否按销售绑定过滤      |
+| `startTime`      | string | 是  | 销售时间起          |
+| `endTime`        | string | 是  | 销售时间止          |
+| `goodsSalesType` | int    | 否  | 销售维度（按单品 / 分类） |
+| `page`           | int    | 是  | 页码             |
+| `limit`          | int    | 是  | 每页条数           |
+
+#### 6.5.5 库存变化记录1 – QueryGoodsOutboundReceipt
+
+* Path：`/GoodsStockManage/QueryGoodsOutboundReceipt`
+
+**请求参数：**
+
+| 字段名         | 类型     | 必填 | 说明     |
+| ----------- | ------ | -- | ------ |
+| `siteId`    | int64  | 是  | 门店 ID  |
+| `stockType` | int    | 否  | 库存变动类型 |
+| `startTime` | string | 是  | 变动时间起  |
+| `endTime`   | string | 是  | 变动时间止  |
+| `page`      | int    | 是  | 页码     |
+| `limit`     | int    | 是  | 每页条数   |
+
+#### 6.5.6 库存变化记录2 – QueryPrimarySecondaryCategory
+
+* Path：`/TenantGoodsCategory/QueryPrimarySecondaryCategory`
+
+**请求参数：**
+
+| 字段名         | 类型     | 必填 | 说明      |
+| ----------- | ------ | -- | ------- |
+| `siteId`    | int64  | 是  | 门店 ID   |
+| `startTime` | string | 否  | 时间起（如有） |
+| `endTime`   | string | 否  | 时间止（如有） |
+| `page`      | int    | 是  | 页码      |
+| `limit`     | int    | 是  | 每页条数    |
+
+#### 6.5.7 库存汇总 – GetGoodsStockReport
+
+* Path：`/TenantGoods/GetGoodsStockReport`
+
+**请求参数：**
+
+| 字段名         | 类型     | 必填 | 说明    |
+| ----------- | ------ | -- | ----- |
+| `siteId`    | int64  | 是  | 门店 ID |
+| `startTime` | string | 否  | 时间过滤起 |
+| `endTime`   | string | 否  | 时间过滤止 |
+| `page`      | int    | 是  | 页码    |
+| `limit`     | int    | 是  | 每页条数  |
+
+### 6.6 团购 / 验券接口
+
+#### 6.6.1 团购套餐 – QueryPackageCouponList
+
+* Path：`/PackageCoupon/QueryPackageCouponList`
+
+**请求参数：**
+
+| 字段名                    | 类型  | 必填 | 说明    |
+| ---------------------- | --- | -- | ----- |
+| `areaId`               | int | 否  | 区域 ID |
+| `commonShowStatus`     | int | 否  | 展示状态  |
+| `offlineCouponChannel` | int | 否  | 券渠道   |
+| `systemGroupType`      | int | 否  | 套餐类型  |
+| `page`                 | int | 是  | 页码    |
+| `limit`                | int | 是  | 每页条数  |
+
+#### 6.6.2 团购套餐流水 – GetSiteTableUseDetails
+
+* Path：`/Site/GetSiteTableUseDetails`
+
+**请求参数：**
+
+| 字段名                    | 类型     | 必填 | 说明    |
+| ---------------------- | ------ | -- | ----- |
+| `siteId`               | int64  | 是  | 门店 ID |
+| `offlineCouponChannel` | int    | 否  | 券渠道   |
+| `startTime`            | string | 是  | 使用时间起 |
+| `endTime`              | string | 是  | 使用时间止 |
+| `page`                 | int    | 是  | 页码    |
+| `limit`                | int    | 是  | 每页条数  |
+
+#### 6.6.3 平台验券记录 – GetOfflineCouponConsumePageList
+
+* Path：`/Promotion/GetOfflineCouponConsumePageList`
+
+**请求参数：**
+
+| 字段名               | 类型     | 必填 | 说明    |
+| ----------------- | ------ | -- | ----- |
+| `couponChannel`   | int    | 否  | 券渠道   |
+| `startTime`       | string | 是  | 验券时间起 |
+| `endTime`         | string | 是  | 验券时间止 |
+| `siteId`          | int64  | 是  | 门店 ID |
+| `couponUseStatus` | int    | 否  | 券使用状态 |
+| `page`            | int    | 是  | 页码    |
+| `limit`           | int    | 是  | 每页条数  |
+
+---