752 lines
32 KiB
Markdown
752 lines
32 KiB
Markdown
## 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 | 是 | 每页条数 |
|
||
|
||
---
|