初始提交：飞球 ETL 系统全量代码

2026-02-13 08:05:34 +08:00
commit 3c51f5485d
441 changed files with 117631 additions and 0 deletions
--- a/docs/api-reference/group_buy_packages.md
+++ b/docs/api-reference/group_buy_packages.md
@@ -0,0 +1,216 @@
+# 团购套餐定义 — 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 个字段，按逻辑分组说明如下。
+
+---
+
+## 四、响应字段详解（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 | `"店长:郑丽珊"` | 创建人信息（角色:姓名），用于权限追踪 |
+| `create_time` | string | `"2025-10-27 18:24:09"` | 套餐创建时间 |
+
+### 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` = 已过期/失效 |
+| `type` | int | `2` | 内部业务子类型。`1` 和 `2` 两种值，具体含义需结合系统配置 |
+| `group_type` | int | `1` | 团购类型。`1` = 计时类/台费类套餐 |
+| `system_group_type` | int | `1` | 系统团购类型。`1` = 券码类团购（需凭码核销） |
+
+---
+
+## 五、响应样例（单条记录）
+
+```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/ 确认字段覆盖完整
+-->