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

feat: 累积功能变更 — 聊天集成、租户管理、小程序更新、ETL 增强、迁移脚本

Browse Source 
包含多个会话的累积代码变更：
- backend: AI 聊天服务、触发器调度、认证增强、WebSocket、调度器最小间隔
- admin-web: ETL 状态页、任务管理、调度配置、登录优化
- miniprogram: 看板页面、聊天集成、UI 组件、导航更新
- etl: DWS 新任务（finance_area_daily/board_cache）、连接器增强
- tenant-admin: 项目初始化
- db: 19 个迁移脚本（etl_feiqiu 11 + zqyy_app 8）
- packages/shared: 枚举和工具函数更新
- tools: 数据库工具、报表生成、健康检查
- docs: PRD/架构/部署/合约文档更新

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Neo
2026-04-06 00:03:48 +08:00
parent 70324d8542
commit 6f8f12314f
515 changed files with 76604 additions and 7456 deletions
Download Patch File Download Diff File Expand all files Collapse all files

479
apps/etl/connectors/feiqiu/docs/api-reference/endpoints/tenant_config.md Normal file
View File

@@ -0,0 +1,479 @@
# 租户配置（GetTenantConfig）接口字段分析报告
> 手动分析于 2026-03-20 | 数据来源：浏览器抓包
## 基本信息
| 属性 | 值 |
| -------------- | ---------------------------------------------------------------- |
| 接口路径 | `System/GetTenantConfig` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/System/GetTenantConfig` |
| 请求方法 | `POST` |
| Content-Type | 无 body（`body: null`） |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| 分页方式 | 无分页（单次返回全量） |
| 时间范围 | 不需要 |
| 响应结构 | `data` 对象包含 7 个子对象 + 1 个顶层字段 |
## 请求参数
无请求体。通过 Token 中的 `tenant-id` 和 `site-id` 确定返回范围。当 `site-id=0` 时返回租户级默认配置。
## 响应顶层结构
| 子对象 | 类型 | 说明 |
| ----------------------------- | -------- | ----------------------------------------------------------- |
| `showAssistant` | int | 顶层开关：是否展示助教模块（1=展示） |
| `siteConfig` | object | 门店级配置（当 site_id=0 时与 tenantConfig 字段完全一致） |
| `tenantConfig` | object | 租户级配置（品牌默认值） |
| `siteProfile` | object | 门店档案信息（site_id=0 时全部为零值/空值） |
| `tenantProfile` | object | 租户档案信息（品牌名称、图标、状态） |
| `assistantLevels` | array | 助教等级配置列表（当前为空数组） |
| `siteUserAppletConfig` | object | 小程序端功能配置（site_id=0 时全部为零值/默认值） |
| `memberCardGradeConfigList` | array | 会员卡等级配置列表（当前为空数组） |
### 关于 siteConfig 与 tenantConfig 的关系
两者字段完全一致（~150 个字段），当 `site_id=0` 时值也完全一致。业务含义：
- `tenantConfig`：品牌级默认配置
- `siteConfig`：门店级覆盖配置（门店可以覆盖品牌默认值）
- 当请求 `site_id=0` 时，siteConfig 回退到 tenantConfig 的值
**ETL 建议**：ODS 层只存一份（tenantConfig），DWD 层按需区分。如果未来需要按门店拉取，再增加 siteConfig 的独立存储。
---
## 一、tenantConfig / siteConfig 字段分析（共 ~150 字段）
> siteConfig 与 tenantConfig 字段完全一致，以下统一分析。按业务域分组。
> 开关字段惯例：1=启用/是，2=禁用/否（飞球系统通用约定），0=未设置/默认。
> 「是否保留」列留空，由人工筛选填写。
### 1.1 主键与标识
| # | 字段名 | 类型 | 示例值 | 业务含义推导 | 是否保留 |
| --- | ------------- | ------ | ------------------ | ------------------------- | ---------- |
| 1 | `id` | int | 2790683527351109 | 配置记录主键 ID | Y |
| 2 | `tenant_id` | int | 2790683160709957 | 租户 ID（品牌标识） | Y |
| 3 | `site_id` | int | 0 | 门店 ID（0=租户级默认） | Y |
### 1.2 助教模块配置
| # | 字段名 | 类型 | 示例值 | 业务含义推导 | 是否保留 |
| ---- | --------------------------------- | -------- | ------------ | ---------------------------------------------------------------------- | ------------------------------------ |
| 4 | `able_assistant_hang_more` | int | 2 | 助教是否允许同时挂多台（2=禁用）。控制一个助教能否同时服务多张球台 | |
| 5 | `assistant_add_clock` | int | 2 | 助教是否可以自行加钟（2=禁用）。控制助教端是否有"加钟"按钮 | |
| 6 | `assistant_global_name` | string | "助理教练" | 助教在系统中的全局称谓。不同门店可能叫"助教""教练""陪练"等 | Y |
| 7 | `assistant_live` | int | 2 | 助教直播功能开关（2=禁用） | |
| 8 | `assistant_performance_confirm` | int | 1 | 助教绩效是否需要确认（1=需要）。助教完成服务后是否需要管理员确认绩效 | |
| 9 | `assistant_ranking` | int | 1 | 助教排行榜功能开关（1=启用） | |
| 10 | `assistant_restrict_count` | int | 3 | 助教限制数量。推测为单台最多可安排的助教人数上限 | |
| 11 | `assistant_reward_name` | string | "激励" | 助教奖励/激励的自定义名称。对应 DWS 中的`assistant_reward_name` 配置 | Y |
| 12 | `assistant_salary_allocation` | int | 2 | 助教薪资分配方式开关（2=禁用自动分配） | 统一使用本项目的薪资计算结算方式。 |
| 13 | `assistant_schedule` | int | 2 | 助教排班功能开关（2=禁用） | |
| 14 | `assistant_show_type` | int | 2 | 助教展示方式。推测 1=列表 2=卡片 或类似的前端展示模式切换 | |
| 15 | `assistant_time_over` | int | 1 | 助教超时处理开关（1=启用）。服务超时后是否自动结束或提醒 | |
| 16 | `is_assistant_rotation` | int | 1 | 助教轮转/轮岗开关（1=启用）。是否按轮次自动分配助教 | |
| 17 | `is_offline_assistant` | int | 1 | 线下助教模式开关（1=启用）。是否支持线下（非系统派单）的助教服务 | |
| 18 | `virtual_playwith_limit` | int | 1 | 虚拟陪打限制（1=启用限制）。控制虚拟/模拟陪打场景的约束 | |
| 19 | `virtual_reward` | int | 2 | 虚拟奖励开关（2=禁用）。是否启用虚拟激励/奖励机制 | |
### 1.3 收银与支付配置
| # | 字段名 | 类型 | 示例值 | 业务含义推导 | 是否保留 |
| ---- | ------------------------- | --------- | -------- | ------------------------------------------------------------------------ | ---------- |
| 20 | `able_cash_pay` | int | 2 | 现金支付开关（2=禁用）。收银台是否接受现金 | |
| 21 | `able_offline_pay` | int | 2 | 线下支付开关（2=禁用）。是否支持线下（非在线）支付方式 | |
| 22 | `able_pos_pay` | int | 2 | POS 机支付开关（2=禁用） | |
| 23 | `able_revoke_settle` | int | 2 | 撤销结算开关（2=禁用）。已结算订单是否允许撤销 | |
| 24 | `can_round_manually` | int | 2 | 手动抹零开关（2=禁用）。收银时是否允许手动调整金额（抹零） | |
| 25 | `pay_round_accuracy` | int | 0 | 支付金额舍入精度。0=不舍入，其他值表示小数位数 | |
| 26 | `pay_round_type` | int | 0 | 支付金额舍入方式。0=不舍入，1=四舍五入，2=向上取整，3=向下取整（推测） | |
| 27 | `up_round` | decimal | 0.00 | 向上取整阈值。配合 pay_round_type 使用 | |
| 28 | `down_round` | decimal | 0.00 | 向下取整阈值。配合 pay_round_type 使用 | |
| 29 | `split_real_charge` | int | 1 | 拆分实收/应收开关（1=启用）。结算时是否区分实收金额和应收金额 | |
| 30 | `currency_symbol_type` | int | 1 | 货币符号类型。1=¥（人民币），其他值对应其他货币符号 | |
| 31 | `income_inclusion_type` | int | 0 | 收入计入方式。0=默认，控制哪些收入项目计入营收统计 | |
### 1.4 会员与储值卡配置
| # | 字段名 | 类型 | 示例值 | 业务含义推导 | 是否保留 |
| ---- | -------------------------------- | --------- | ----------------------------- | -------------------------------------------------------------- | ---------- |
| 32 | `applet_member_recharge` | int | 2 | 小程序端会员充值开关（2=禁用） | |
| 33 | `member_app_type` | int | 6 | 会员应用类型。6 可能表示某种会员系统版本或模式 | |
| 34 | `member_bind_plural_table` | int | 1 | 会员绑定多台开关（1=允许）。一个会员是否可以同时绑定多张球台 | |
| 35 | `member_consumption_sms` | int | 1 | 会员消费短信通知开关（1=启用） | |
| 36 | `member_discount_balance_mode` | int | 1 | 会员折扣余额模式。控制折扣与余额的计算优先级 | |
| 37 | `member_discount_mode` | int | 2 | 会员折扣模式。2=某种折扣计算方式（如按等级/按消费额） | |
| 38 | `member_expense_hint` | int | 2 | 会员消费提醒开关（2=禁用）。消费达到阈值时是否提醒 | |
| 39 | `member_expense_money` | decimal | 500.00 | 会员消费提醒阈值（元）。当单次消费超过此金额时触发提醒 | |
| 40 | `member_login_method` | string | "1" | 会员登录方式。"1"=手机号登录（推测） | |
| 41 | `default_member_avatar` | string | "https://oss.ficoo.vip/..." | 会员默认头像 URL | |
| 42 | `default_member_password` | string | "123456" | ⚠️ 敏感字段：会员默认密码。ODS 层需脱敏（保留最后 2 字符） | |
| 43 | `recharge_card_included` | int | 1 | 充值卡纳入统计开关（1=纳入）。充值卡金额是否计入营收 | |
| 44 | `gift_card_included` | int | 1 | 赠送卡纳入统计开关（1=纳入）。赠送金额是否计入营收 | |
| 45 | `platform_coupon_included` | int | 1 | 平台优惠券纳入统计开关（1=纳入） | |
| 46 | `self_coupon_included` | int | 1 | 自有优惠券纳入统计开关（1=纳入） | |
| 47 | `rcp_able_chose_member_grade` | int | 1 | 收银台是否可选择会员等级（1=可选） | |
| 48 | `send_level_change_notice` | int | 1 | 会员等级变更通知开关（1=发送） | |
| 49 | `auto_rela_sales_man` | int | 2 | 自动关联销售员开关（2=禁用）。新会员是否自动关联推荐销售员 | |
| 50 | `consume_auto_rela_sales_man` | int | 2 | 消费时自动关联销售员开关（2=禁用） | |
| 51 | `is_rela_more_salesmen` | int | 1 | 允许关联多个销售员开关（1=允许） | |
### 1.5 会员等级与积分规则
| # | 字段名 | 类型 | 示例值 | 业务含义推导 | 是否保留 |
| ---- | ---------------------------- | -------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| 52 | `is_calc_points` | int | 1 | 积分计算开关（1=启用）。消费时是否自动计算积分 | |
| 53 | `point_alias` | string | "积分" | 积分的自定义名称。不同品牌可能叫"积分""金币""豆子"等 | |
| 54 | `point_expire_num` | int | 0 | 积分过期数值。0=不过期 | |
| 55 | `point_expire_type` | int | 1 | 积分过期类型。1=按固定周期 | |
| 56 | `point_expire_unit` | int | 1 | 积分过期单位。1=月（推测） | |
| 57 | `point_rule` | string | "" | 积分规则描述（当前为空，可能是 JSON 或文本规则） | |
| 58 | `growth_value_expire_num` | int | 0 | 成长值过期数值。0=不过期 | |
| 59 | `growth_value_expire_type` | int | 1 | 成长值过期类型 | |
| 60 | `growth_value_expire_unit` | int | 1 | 成长值过期单位 | |
| 61 | `member_grade_expire_num` | int | 0 | 会员等级过期数值。0=不过期 | |
| 62 | `member_grade_expire_type` | int | 1 | 会员等级过期类型 | |
| 63 | `member_grade_expire_unit` | int | 1 | 会员等级过期单位 | |
| 64 | `member_rule_config_json` | string(JSON) | `{growthValueExpireNum: 12,...}` | 会员规则综合配置 JSON。包含成长值过期、等级升级类型、等级保级策略等。注意：非标准 JSON（缺引号），解析时需容错。**建议 JSONB 存储** | |
| 65 | `registration_info_rule` | string | "" | 注册信息规则（当前为空） | |
### 1.6 球台与计费配置
| # | 字段名 | 类型 | 示例值 | 业务含义推导 | 是否保留 |
| ---- | ---------------------------- | ------ | -------- | -------------------------------------------------------------------------- | ---------- |
| 66 | `billing_rate_time_type` | int | 1 | 计费费率时间类型。控制按分钟/小时/时段计费 | |
| 67 | `business_time_type` | int | 1 | 营业时间类型。1=标准营业时间模式 | |
| 68 | `charge_time_type` | int | 1 | 计费时间类型。与 billing_rate_time_type 配合，控制计费起止时间的计算方式 | |
| 69 | `cross_region_fee` | int | 1 | 跨区域费用开关（1=启用）。不同区域球台之间转台是否收取额外费用 | |
| 70 | `table_rental_fee_enable` | int | 1 | 台费租赁费开关（1=启用）。是否收取球台租赁费 | |
| 71 | `normal_table_number` | int | -1 | 普通台数量。-1=不限制（由实际球台数决定） | |
| 72 | `rest_table_number` | int | -1 | 休息台数量。-1=不限制 | |
| 73 | `virtual_table_number` | int | -1 | 虚拟台数量。-1=不限制。虚拟台用于不占用实体球台的服务场景 | |
| 74 | `temporary_light_time` | int | 0 | 临时开灯时长（分钟）。0=不启用临时开灯 | |
| 75 | `temporary_light_max_time` | int | 0 | 临时开灯最大时长（分钟） | |
### 1.7 收银台与前台配置
| # | 字段名 | 类型 | 示例值 | 业务含义推导 | 是否保留 |
| ---- | ---------------------------- | ------ | -------- | ------------------------------------------------------------ | ---------- |
| 76 | `bill_font_type` | int | 1 | 小票字体类型。1=标准字体 | |
| 77 | `cash_register_goods_sort` | int | 1 | 收银台商品排序方式。1=默认排序 | |
| 78 | `cashier_login_restrict` | int | 1 | 收银员登录限制（1=启用）。是否限制收银员只能在指定设备登录 | |
| 79 | `cashier_switch_light` | int | 1 | 收银台开关灯控制（1=启用）。收银台是否可以控制球台灯光 | |
| 80 | `cashier_table_show_money` | int | 1 | 收银台球台显示金额（1=显示）。球台列表是否显示当前消费金额 | |
| 81 | `cashier_temporary_light` | int | 1 | 收银台临时开灯（1=启用） | |
| 82 | `rcp_table_list_version` | int | 1 | 收银台球台列表版本。1=V1 版本布局 | |
| 83 | `coupon_goods_auto_print` | int | 2 | 优惠券商品自动打印开关（2=禁用） | |
| 84 | `is_not_paid_goods` | int | 2 | 未付款商品显示开关（2=不显示） | |
| 85 | `return_goods_settled` | int | 1 | 已结算商品退货开关（1=允许） | |
| 86 | `enable_goods_remark` | int | 1 | 商品备注功能开关（1=启用） | |
| 87 | `enable_serial_number` | int | 1 | 序列号功能开关（1=启用） | |
### 1.8 智慧屏与前厅配置
| # | 字段名 | 类型 | 示例值 | 业务含义推导 | 是否保留 |
| ---- | ----------------------------------- | --------- | ----------------------- | -------------------------------------------------------- | ---------- |
| 88 | `enable_smart_antechamber` | int | 1 | 智慧前厅开关（1=启用）。是否启用智慧前厅（自助服务屏） | |
| 89 | `is_smart_screen_pay` | int | 1 | 智慧屏支付开关（1=启用）。智慧屏是否支持直接支付 | |
| 90 | `is_show_smart_screen_tip` | int | 1 | 智慧屏提示开关（1=显示） | |
| 91 | `smart_screen_menu_cfg` | string | "1,2,3" | 智慧屏菜单配置。逗号分隔的菜单项 ID | |
| 92 | `smart_screen_rental` | decimal | 0.00 | 智慧屏租赁费（元/月） | |
| 93 | `smart_screen_rental_receiver_id` | int | 0 | 智慧屏租赁费收款方 ID。0=未设置 | |
| 94 | `smart_screen_rental_start_time` | string | "0001-01-01 00:00:00" | 智慧屏租赁开始时间（零值=未设置） | |
| 95 | `smart_screen_rental_end_time` | string | "0001-01-01 00:00:00" | 智慧屏租赁结束时间（零值=未设置） | |
| 96 | `is_open_screen_savers` | int | 1 | 屏保开关（1=启用） | |
| 97 | `front_delivery_enabled` | int | 1 | 前台配送开关（1=启用）。前台是否支持商品配送到桌 | |
### 1.9 通知与短信配置
| # | 字段名 | 类型 | 示例值 | 业务含义推导 | 是否保留 |
| ----- | ---------------------- | -------- | -------- | --------------------------------- | ---------- |
| 98 | `able_notify` | int | 1 | 通知总开关（1=启用） | |
| 99 | `is_sms_notified` | int | 0 | 短信通知开关（0=禁用） | |
| 100 | `sms_notice_mobile` | string | "" | 短信通知接收手机号（空=未设置） | |
| 101 | `total_sms_credit` | int | 0 | 短信余额/额度。0=无余额 | |
| 102 | `is_rcp_notice_ring` | int | 1 | 收银台通知铃声开关（1=启用） | |
| 103 | `announce_one` | int | 0 | 公告位 1 开关（0=关闭） | |
| 104 | `announce_two` | int | 0 | 公告位 2 开关（0=关闭） | |
### 1.10 考勤与排班配置
| # | 字段名 | 类型 | 示例值 | 业务含义推导 | 是否保留 |
| ----- | ------------------------------------ | -------------- | ----------------------- | ---------------------------------------------------- | ---------- |
| 105 | `attendance_enabled` | int | 1 | 考勤功能总开关（1=启用） | |
| 106 | `attendance_sync_deadline` | string | "2000-01-01 08:00:00" | 考勤同步截止时间。零值占位=使用默认 | |
| 107 | `absent_flag` | int | 1 | 缺勤标记开关（1=启用）。是否自动标记缺勤 | |
| 108 | `absent_number` | int | 7 | 缺勤天数阈值。连续缺勤超过此天数触发告警/处理 | |
| 109 | `shift_enabled` | int | 1 | 班次功能开关（1=启用） | |
| 110 | `shift_turnover_goods` | int | 1 | 交班时商品盘点开关（1=启用） | |
| 111 | `shift_turnover_type` | int | 1 | 交班类型。1=标准交班流程 | |
| 112 | `sign_enable` | int | 1 | 签到功能开关（1=启用） | |
| 113 | `sign_config` | string(JSON) | "{}" | 签到配置 JSON（当前为空对象）。**建议 JSONB 存储** | |
| 114 | `online_sign_enable` | int | 1 | 在线签到开关（1=启用） | |
| 115 | `offline_sign_enable` | int | 1 | 离线签到开关（1=启用） | |
| 116 | `site_attendance_approval_enabled` | int | 1 | 门店考勤审批开关（1=启用） | |
| 117 | `site_staff_salary_enabled` | int | 1 | 门店员工薪资开关（1=启用） | |
### 1.11 财务与结算配置
| # | 字段名 | 类型 | 示例值 | 业务含义推导 | 是否保留 |
| ----- | --------------------------------- | -------- | ----------------------- | --------------------------------------------------------------------------- | ---------- |
| 118 | `cutoff_time` | string | "2000-01-05 08:00:00" | 财务截止时间（日结时间点）。只取时间部分 08:00，表示每日 8 点为财务日切点 | Y |
| 119 | `site_cutoff_time` | string | "0001-01-01 00:00:00" | 门店级财务截止时间（零值=使用租户默认） | Y |
| 120 | `daily_settle_enable` | int | 1 | 日结功能开关（1=启用）。是否启用每日自动结算 | |
| 121 | `data_analysis` | int | 1 | 数据分析功能开关（1=启用）。是否在管理端展示数据分析模块 | |
| 122 | `financial_analysis_url` | string | "" | 财务分析外链 URL（空=未配置外部 BI 链接） | |
| 123 | `performance_time` | int | 2 | 绩效计算时间维度。2=按月（推测：1=按周，2=按月，3=按季） | |
| 124 | `revenue_switch` | int | 2 | 营收统计开关（2=禁用）。是否在首页展示营收数据 | |
| 125 | `able_show_platform_receivable` | int | 1 | 平台应收展示开关（1=展示）。是否展示平台代收的应收款项 | |
| 126 | `declaration_concealment` | int | 1 | 报表隐藏开关（1=启用）。是否隐藏部分敏感财务报表 | |
| 127 | `coach_look_performance` | int | 1 | 教练查看绩效开关（1=允许）。助教/教练是否可以查看自己的绩效数据 | |
### 1.12 商品与库存配置
| # | 字段名 | 类型 | 示例值 | 业务含义推导 | 是否保留 |
| ----- | ----------------------------- | ------ | -------- | --------------------------------- | ---------- |
| 128 | `goods_version_cfg` | int | 1 | 商品版本配置。1=V1 版本商品管理 | |
| 129 | `warehouse_type` | int | 1 | 仓库类型。1=单仓模式 | |
| 130 | `manager_applet_goods_sort` | int | 1 | 管理端小程序商品排序方式 | |
### 1.13 灯控与电力配置
| # | 字段名 | 类型 | 示例值 | 业务含义推导 | 是否保留 |
| ----- | ------------------ | ------ | -------- | --------------------------------------------------- | ---------- |
| 131 | `is_electricity` | int | 1 | 电力管理开关（1=启用）。是否启用球台电力/灯控管理 | |
### 1.14 团队编辑配置
| # | 字段名 | 类型 | 示例值 | 业务含义推导 | 是否保留 |
| ----- | -------------------------------- | -------- | ----------------------- | ------------------------------------------------------------------- | ---------- |
| 132 | `edit_team_current_next_month` | int | 1 | 编辑团队当月/下月开关（1=允许）。是否允许编辑当月和下月的团队配置 | |
| 133 | `edit_team_start_time` | string | "2025-01-01 00:00:00" | 团队编辑允许的开始时间 | |
| 134 | `edit_team_end_time` | string | "2025-01-01 00:00:00" | 团队编辑允许的结束时间（与 start 相同=未限制） | |
### 1.15 小程序与线上配置
| # | 字段名 | 类型 | 示例值 | 业务含义推导 | 是否保留 |
| ----- | ------------------------------------- | -------- | -------- | ---------------------------------------------- | ---------- |
| 135 | `enable_auto_accept` | int | 1 | 自动接单开关（1=启用）。线上订单是否自动接受 | |
| 136 | `enable_outdoor_order` | int | 2 | 外卖/外送订单开关（2=禁用） | |
| 137 | `enable_professional_member_applet` | int | 1 | 专业版会员小程序开关（1=启用） | |
| 138 | `member_applet_share_url` | string | "" | 会员小程序分享链接（空=未配置） | |
### 1.16 百能运营费配置
| # | 字段名 | 类型 | 示例值 | 业务含义推导 | 是否保留 |
| ----- | ------------------------------------- | --------- | -------- | ----------------------------------------------------------------------- | ---------- |
| 139 | `baineng_operation_fee_enable` | int | 1 | 百能运营费开关（1=启用）。百能=第三方运营服务商，是否启用其运营费抽成 | |
| 140 | `baineng_operation_fee_ratio` | decimal | 0.00 | 百能运营费比例。0.00=不抽成（虽然开关启用但比例为 0） | |
| 141 | `baineng_operation_fee_receiver_id` | int | 0 | 百能运营费收款方 ID。0=未设置 | |
### 1.17 UI 与颜色配置
| # | 字段名 | 类型 | 示例值 | 业务含义推导 | 是否保留 |
| ----- | --------------------- | -------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| 142 | `color_config_json` | string(JSON) | `{"statuses":{"assistant":"#DA5F8E",...}}` | PC 端球台状态颜色配置。包含：assistant（助教服务中）、cluster（拼台）、font（字体）、leisure（空闲）、reserve（预约）、start（开台）、warning（警告）。**建议 JSONB 存储** | |
| 143 | `min_color_json` | string(JSON) | `{"statuses":{"leisure":"#BBC1C6",...}}` | 小程序端球台状态颜色配置。字段结构与 color_config_json 一致，颜色值不同（适配小程序 UI）。**建议 JSONB 存储** | |
### 1.18 安全与登录配置
| # | 字段名 | 类型 | 示例值 | 业务含义推导 | 是否保留 |
| ----- | ------------------------- | -------- | --------------- | ------------------------------------------------------------------------ | ---------- |
| 144 | `can_many_account` | int | 1 | 多账号登录开关（1=允许）。同一用户是否可以在多设备同时登录 | |
| 145 | `single_sign_on` | int | 1 | 单点登录开关（1=启用）。是否启用 SSO | |
| 146 | `default_user_password` | string | "AFD42Zto..." | ⚠️ 敏感字段：用户默认密码（加密后）。ODS 层需脱敏（保留最后 2 字符） | |
| 147 | `needs_confirm` | int | 1 | 操作确认开关（1=需要）。关键操作是否需要二次确认 | |
| 148 | `watermark_enable` | int | 1 | 水印开关（1=启用）。管理端页面是否显示水印（防截图泄露） | |
### 1.19 营销与默认门店配置
| # | 字段名 | 类型 | 示例值 | 业务含义推导 | 是否保留 |
| ----- | ----------------------------- | ------ | ------------------ | -------------------------------------------------- | ---------- |
| 149 | `default_marketing_site_id` | int | 2928823574824965 | 默认营销门店 ID。营销活动默认关联的门店 | |
| 150 | `material_id` | int | 0 | 素材 ID。0=未设置，可能关联营销素材库 | |
| 151 | `service_level` | int | 1 | 服务等级。1=基础服务等级（可能影响功能可用范围） | |
---
## 二、tenantProfile 字段分析
| # | 字段名 | 类型 | 示例值 | 业务含义推导 | 是否保留 |
| --- | ---------------- | -------- | ------------------------------------------ | ------------------------------------------------------ | ---------- |
| 1 | `tenantName` | string | "朗朗桌球" | 租户/品牌名称 | Y |
| 2 | `tenantIcon` | string | "https://oss.ficoo.vip/admin/DbtcMZ_..." | 租户/品牌图标 URL | |
| 3 | `prodEnv` | string | "Normal" | 生产环境标识。Normal=正式环境（区别于测试/演示环境） | |
| 4 | `tenantStatus` | int | 0 | 租户状态。0=正常运营（其他值可能表示停用/欠费等） | |
---
## 三、siteProfile 字段分析
> 当 site_id=0 时全部为零值/空值，以下为字段结构说明。实际按门店拉取时会有真实数据。
| # | 字段名 | 类型 | 示例值 | 业务含义推导 | 是否保留 |
| ---- | --------------------------- | -------- | ---------- | -------------------------------------- | ---------- |
| 1 | `id` | int | 0 | 门店档案主键 ID | |
| 2 | `org_id` | int | 0 | 组织 ID | |
| 3 | `shop_name` | string | "" | 门店名称 | |
| 4 | `avatar` | string | "" | 门店头像/Logo URL | |
| 5 | `business_tel` | string | "" | 门店联系电话 | |
| 6 | `full_address` | string | "" | 门店完整地址 | |
| 7 | `address` | string | "" | 门店简短地址 | |
| 8 | `longitude` | float | 0.000000 | 经度 | |
| 9 | `latitude` | float | 0.000000 | 纬度 | |
| 10 | `tenant_site_region_id` | int | 0 | 租户门店区域 ID | |
| 11 | `tenant_id` | int | 0 | 租户 ID | |
| 12 | `auto_light` | int | 1 | 自动开灯开关（1=启用） | |
| 13 | `attendance_distance` | int | 0 | 考勤打卡距离限制（米）。0=不限制 | |
| 14 | `wifi_name` | string | "" | 门店 WiFi 名称（用于考勤 WiFi 打卡） | |
| 15 | `wifi_password` | string | "" | 门店 WiFi 密码 | |
| 16 | `customer_service_qrcode` | string | "" | 客服二维码 URL | |
| 17 | `customer_service_wechat` | string | "" | 客服微信号 | |
| 18 | `fixed_pay_qrCode` | string | "" | 固定收款二维码 URL | |
| 19 | `prod_env` | int | 1 | 生产环境标识（1=正式） | |
| 20 | `light_status` | int | 1 | 灯控状态（1=正常） | |
| 21 | `light_type` | int | 0 | 灯控类型。0=默认 | |
| 22 | `site_type` | int | 1 | 门店类型。1=标准门店 | |
| 23 | `light_token` | string | "" | 灯控设备 Token | |
| 24 | `site_label` | string | "" | 门店标签 | |
| 25 | `attendance_enabled` | int | 1 | 门店考勤开关 | |
| 26 | `shop_status` | int | 1 | 门店营业状态（1=营业中） | |
---
## 四、siteUserAppletConfig 字段分析
> 小程序端功能配置。当 site_id=0 时全部为零值/默认值。
| # | 字段名 | 类型 | 示例值 | 业务含义推导 | 是否保留 |
| ---- | ----------------------------------------- | --------- | -------- | ------------------------------------ | ---------- |
| 1 | `id` | int | 0 | 配置记录主键 | |
| 2 | `applet_assistant_order` | int | 2 | 小程序助教下单开关（2=禁用） | |
| 3 | `applet_assistant_reward` | int | 2 | 小程序助教打赏开关（2=禁用） | |
| 4 | `applet_goods_order` | int | 2 | 小程序商品下单开关（2=禁用） | |
| 5 | `applet_goods_outer` | int | 2 | 小程序外卖商品开关（2=禁用） | |
| 6 | `applet_look_order` | int | 2 | 小程序查看订单开关（2=禁用） | |
| 7 | `applet_member_recharge` | int | 2 | 小程序会员充值开关（2=禁用） | |
| 8 | `applet_order_settle` | int | 2 | 小程序订单结算开关（2=禁用） | |
| 9 | `applet_use_package_coupon` | int | 2 | 小程序使用套餐券开关（2=禁用） | |
| 10 | `applet_use_table` | int | 2 | 小程序开台开关（2=禁用） | |
| 11 | `applet_use_table_with_self_coupon` | int | 2 | 小程序使用自有券开台开关（2=禁用） | |
| 12 | `applet_use_table_with_self_coupon_pay` | int | 2 | 小程序自有券开台支付开关（2=禁用） | |
| 13 | `booking_retain_time` | int | 900 | 预约保留时长（秒）。900=15 分钟 | |
| 14 | `cancel_booking_refund` | int | 2 | 取消预约退款开关（2=禁用） | |
| 15 | `delivery_fee` | decimal | 0.00 | 配送费（元） | |
| 16 | `is_delete` | int | 0 | 逻辑删除标记 | |
| 17 | `is_online_reservation` | int | 2 | 在线预约开关（2=禁用） | |
| 18 | `member_recharge_pay_channel` | int | 0 | 会员充值支付渠道。0=默认 | |
| 19 | `minimum_order_amount` | decimal | 0.00 | 最低订单金额（元） | |
| 20 | `pay_channel` | int | 0 | 支付渠道。0=默认 | |
| 21 | `reservation_deposit` | decimal | 0.00 | 预约押金（元） | |
| 22 | `reservation_expiration_time` | int | 0 | 预约过期时间（秒）。0=不过期 | |
| 23 | `site_id` | int | 0 | 门店 ID | |
| 24 | `take_out_delivery` | int | 2 | 外卖配送开关（2=禁用） | |
| 25 | `tenant_id` | int | 0 | 租户 ID | |
| 26 | `site_show_assistant` | int | 2 | 门店展示助教开关（2=不展示） | |
| 27 | `site_show_goods` | int | 2 | 门店展示商品开关（2=不展示） | |
---
## 五、assistantLevels 字段分析
> 当前返回空数组 `[]`。推测结构如下（基于系统中助教等级的已知信息）：
| # | 字段名 | 类型 | 推测含义 |
| --- | ----------------- | --------- | ---------------------------------- |
| 1 | `id` | int | 等级配置主键 |
| 2 | `level` | int | 等级代码（如 10/20/30/40） |
| 3 | `level_name` | string | 等级名称（如"初级""中级""高级"） |
| 4 | `pd_unit_price` | decimal | 陪打单价 |
| 5 | `cx_unit_price` | decimal | 超休单价 |
> 注意：此为推测结构，需要在有数据的门店验证。当前租户级请求返回空数组，可能需要按门店拉取才有数据。
---
## 六、memberCardGradeConfigList 字段分析
> 当前返回空数组 `[]`。推测结构如下（基于系统中会员卡等级的已知信息）：
| # | 字段名 | 类型 | 推测含义 |
| --- | ----------------- | --------- | ---------------- |
| 1 | `id` | int | 等级配置主键 |
| 2 | `grade_name` | string | 等级名称 |
| 3 | `grade_level` | int | 等级序号 |
| 4 | `discount_rate` | decimal | 折扣率 |
| 5 | `growth_value` | int | 升级所需成长值 |
> 注意：此为推测结构，需要在有数据的门店验证。
---
## 七、JSON 字段用途分析
| 字段名 | 所属子对象 | 结构 | 用途 | 存储建议 |
| --------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------- |
| `color_config_json` | tenantConfig | `{"statuses":{"assistant":"#DA5F8E","cluster":"#F39F01","font":"#FFFFFF","leisure":"#2B2B38","reserve":"#2B2B38","start":"#01A39B","warning":"#EC6B04"}}` | PC 端球台状态颜色主题。7 种状态各一个 HEX 颜色值 | JSONB |
| `min_color_json` | tenantConfig | 同上结构，颜色值不同 | 小程序端球台状态颜色主题 | JSONB |
| `member_rule_config_json` | tenantConfig | `{growthValueExpireNum: 12, memberGradeUpType: 1, memberGradeExpireType: 1, memberGradeExpireNum: 12, memberGradeKeepType: 1, memberGradeKeepBalanceType: 1}` | 会员等级规则综合配置：成长值过期周期、等级升级方式、等级过期策略、保级策略。⚠️ 非标准 JSON（键名无引号），解析需容错 | JSONB |
| `sign_config` | tenantConfig | `{}` | 签到规则配置（当前为空，预留） | JSONB |
---
## 八、敏感字段清单
| 字段名 | 所属子对象 | 示例值 | 脱敏方式 |
| --------------------------- | -------------- | ----------------------- | ----------------------------------------------- |
| `default_member_password` | tenantConfig | "123456" | ODS 层保留最后 2 字符 → "****56" |
| `default_user_password` | tenantConfig | "AFD42ZtoGhIn+LYp..." | ODS 层保留最后 2 字符 → "****Q==" |
| `wifi_password` | siteProfile | "" | ODS 层保留最后 2 字符（当前为空，有值时脱敏） |
---
## 九、与现有 ETL 数据的关联分析
| 本接口字段 | 关联的现有数据 | 关联方式 |
| ------------------------------------------------- | ------------------------------------ | ---------------------------------------- |
| `tenant_id` | 所有 ODS/DWD 表的`tenant_id` | 直接匹配 |
| `site_id` | 所有 ODS/DWD 表的`site_id` | 直接匹配 |
| `assistant_global_name` | DWS 层助教相关报表的称谓显示 | 替代硬编码"助教" |
| `assistant_reward_name` | DWS 层`assistant_reward_name` 配置 | 替代硬编码"激励" |
| `point_alias` | 会员积分相关展示 | 替代硬编码"积分" |
| `cutoff_time` | 财务日结时间点 | 影响日结算逻辑的时间窗口 |
| `performance_time` | 绩效计算周期 | 影响 DWS 绩效汇总的时间维度 |
| `color_config_json` / `min_color_json` | 小程序/管理端球台状态颜色 | 前端渲染配置 |
| `member_rule_config_json` | 会员等级升降级逻辑 | 影响会员维度表的等级变更判断 |
| `recharge_card_included` / `gift_card_included` | 营收统计口径 | 影响 DWS 营收汇总是否包含充值卡/赠送卡 |
| `assistant_restrict_count` | 助教排班/派单逻辑 | 单台最大助教数限制 |

2
apps/etl/connectors/feiqiu/docs/business-rules/index_algorithm_cn.md
View File

@@ -23,7 +23,7 @@
- 窗口仅回溯 **近 60 天**（`lookback_days`）。
2) **天数截断**
- 所有"天数差"在参与衰减或间隔计算时，都会被截断到 `<= lookback_days`（默认 60 天）。
- 所有"天数差"在参与衰减或间隔计算时，都会被截断到 `<= lookback_days`（默认 90 天）。
3) **半衰期衰减**
```

6
apps/etl/connectors/feiqiu/docs/etl_tasks/dws_tasks.md
View File

@@ -8,7 +8,7 @@
## 概述
DWS 层共有 19 个已注册任务（含 DWS_MAINTENANCE），按业务域分为六组：
DWS 层共有 21 个已注册任务（含 DWS_MAINTENANCE），按业务域分为六组：
### 助教业绩域（6 个）
@@ -35,7 +35,7 @@ DWS 层共有 19 个已注册任务（含 DWS_MAINTENANCE），按业务域分
| `DWS_ASSISTANT_PROJECT_TAG` | `AssistantProjectTagTask` | `dws_assistant_project_tag` | 助教+时间窗口+项目 | 全量删除重建（按 site_id） |
| `DWS_MEMBER_PROJECT_TAG` | `MemberProjectTagTask` | `dws_member_project_tag` | 会员+时间窗口+项目 | 全量删除重建（按 site_id） |
### 财务统计域（4 个）
### 财务统计域（6 个）
| 任务代码 | Python 类 | 目标表 | 粒度 | 更新策略 |
|----------|-----------|--------|------|----------|
@@ -43,6 +43,8 @@ DWS 层共有 19 个已注册任务（含 DWS_MAINTENANCE），按业务域分
| `DWS_FINANCE_RECHARGE` | `FinanceRechargeTask` | `dws_finance_recharge_summary` | 日期 | delete-before-insert |
| `DWS_FINANCE_INCOME_STRUCTURE` | `FinanceIncomeStructureTask` | `dws_finance_income_structure` | 日期+收入类型 | delete-before-insert |
| `DWS_FINANCE_DISCOUNT_DETAIL` | `FinanceDiscountDetailTask` | `dws_finance_discount_detail` | 日期+折扣类型 | delete-before-insert |
| `DWS_FINANCE_AREA_DAILY` | `FinanceAreaDailyTask` | `dws_finance_area_daily` | 日期+区域 | delete-before-insert |
| `DWS_FINANCE_BOARD_CACHE` | `FinanceBoardCacheTask` | `dws_finance_board_cache` | 时间范围+区域 | upsert（指纹对比） |
### 库存汇总域（3 个）

6
apps/etl/connectors/feiqiu/docs/etl_tasks/index_tasks.md
View File

@@ -878,7 +878,7 @@ ORDER BY effective_from DESC
| 参数名 | 默认值 | 说明 |
|--------|--------|------|
| `lookback_days` | 60 | 服务行为回溯窗口（天） |
| `lookback_days` | 90 | 服务行为回溯窗口（天） |
| `session_merge_hours` | 4 | 会话合并阈值（小时） |
| `incentive_weight` | 1.5 | 激励课权重 |
| `halflife_session` | 14 | 会话半衰期（天） |
@@ -904,7 +904,7 @@ ORDER BY effective_from DESC
| 参数名 | 默认值 | 说明 |
|--------|--------|------|
| `lookback_days` | 60 | 服务行为回溯窗口（天） |
| `lookback_days` | 90 | 服务行为回溯窗口（天） |
| `session_merge_hours` | 4 | 会话合并阈值（小时） |
| `incentive_weight` | 1.5 | 激励课权重 |
| `halflife_short` / `halflife_long` | 7 / 30 | 短期/长期半衰期（天） |
@@ -917,7 +917,7 @@ ORDER BY effective_from DESC
| 参数名 | 默认值 | 说明 |
|--------|--------|------|
| `lookback_days` | 60 | 充值行为回溯窗口（天） |
| `lookback_days` | 90 | 充值行为回溯窗口（天） |
| `amount_base` | 500 | 金额压缩基准 |
| `halflife_recharge` | 21 | 充值半衰期（天） |
| `percentile_lower` / `percentile_upper` | 5 / 95 | 归一化分位点 |