feat: batch update - gift card breakdown spec, backend APIs, miniprogram pages, ETL finance recharge, docs & migrations
This commit is contained in:
38
.kiro/steering/cli-env.md
Normal file
38
.kiro/steering/cli-env.md
Normal file
@@ -0,0 +1,38 @@
|
||||
---
|
||||
inclusion: always
|
||||
---
|
||||
# CLI 环境规范（Windows PowerShell）
|
||||
|
||||
本项目运行在 Windows + PowerShell 环境。以下是构造命令时必须掌握的前置知识。
|
||||
|
||||
## PowerShell 语法要点
|
||||
- 环境变量：`$env:VAR_NAME`（不是 `$VAR_NAME`）
|
||||
- 命令连接符：`;`（不是 `&&`）
|
||||
- `where` 是 `Where-Object` 别名，查可执行文件用 `Get-Command <name>`
|
||||
- 删除文件/目录：`Remove-Item`（不是 `rm -rf`）
|
||||
- 路径分隔符 `\`，但 Python/Node 工具也接受 `/`
|
||||
|
||||
## Python 调用
|
||||
- 项目虚拟环境：`uv run python` 或 `.venv\Scripts\python.exe`
|
||||
- 安装依赖：`uv sync`（不是 `pip install`）
|
||||
- 运行模块：`uv run python -m <module>`
|
||||
- 系统 Python：`python`（来自 miniconda3）
|
||||
|
||||
## Shell 隔离与 REPL 防护（强制）
|
||||
|
||||
> 背景：Kiro 的 `executePwsh` 复用同一个 shell session。若意外进入 Python REPL，后续所有命令被吞掉，表现为"无输出 + exit code 0"。
|
||||
|
||||
### 核心原则
|
||||
- 禁止裸调 `python`/`node`/`ipython`——必须带 `-c`、`-m` 或脚本路径
|
||||
- 优先写脚本文件再执行，避免 `-c` 内联引号地狱
|
||||
- 禁止管道喂给 python（如 `echo "code" | python`）
|
||||
|
||||
### 长时间命令
|
||||
- 预估 > 30s 的命令，提前告知用户
|
||||
- pytest hypothesis 建议设 `timeout` 为预估时间 3 倍
|
||||
- 超时后不要立即重试，先确认前一个进程状态
|
||||
|
||||
### REPL 劫持
|
||||
症状：exit code 0 但无输出、连续命令无输出、出现 `>>>` 提示符。检测与自动恢复由 `repl-hijack-guard` hook 在命令执行后自动处理。
|
||||
|
||||
> cwd 校验和命令语法检查由 `cwd-guard-shell` hook 在执行前自动拦截，此处不再重复。
|
||||
@@ -1,25 +0,0 @@
|
||||
---
|
||||
inclusion: always
|
||||
---
|
||||
|
||||
# 归档目录与废弃对象规则（强制）
|
||||
|
||||
## `_archived/` 目录规则
|
||||
|
||||
仓库中所有 `_archived/` 目录（`db/_archived/`、`docs/database/_archived/`、`apps/**/docs/database/_archived/` 等）存放的是已废弃、已归档的历史内容。
|
||||
|
||||
1. 除非用户明确要求查阅历史/归档内容，否则禁止读取或参考 `_archived/` 下的任何文件
|
||||
2. 从 `_archived/` 中读到的表结构、映射、任务定义、DDL 等，不得视为当前有效对象
|
||||
3. 补充映射、表清单、任务列表、DDL 时，仅以活跃目录中的文件为准，忽略 `_archived/`
|
||||
4. 如果 `_archived/` 中的内容与活跃目录冲突，以活跃目录为准
|
||||
|
||||
## 已废弃对象黑名单（高频误引，显式列出）
|
||||
|
||||
| 对象 | 类型 | 删除日期 | 替代方案 |
|
||||
|------|------|----------|----------|
|
||||
| `dwd.dwd_assistant_trash_event` | DWD 表 | 2026-02-22 | `dwd_assistant_service_log_ex.is_trash` |
|
||||
| `dwd.dwd_assistant_trash_event_ex` | DWD 扩展表 | 2026-02-22 | 同上 |
|
||||
| `ods.assistant_cancellation_records` | ODS 表 | 2026-02-22 | 不再需要独立链路 |
|
||||
| `ODS_ASSISTANT_ABOLISH` | ETL 任务 | 2026-02-22 | 无 |
|
||||
| `ASSISTANT_ABOLISH` | 调度任务 | 2026-02-22 | 无 |
|
||||
| `BILLIARD_VIP` | cfg_area_category 分类代码 | 2026-03-07 | V1-V4 归入 `BILLIARD`，V5 归入 `SNOOKER`（台桌级映射） |
|
||||
@@ -1,5 +1,8 @@
|
||||
---
|
||||
inclusion: always
|
||||
inclusion: fileMatch
|
||||
fileMatchPattern: "**/tasks/**,**/loaders/**,**/scd/**,**/dws/**,**/dwd/**,**/quality/**,**/business-rules/**,**/schemas/**,**/routers/**,**/financial*,**/settlement*,**/consume*,**/accounting*,**/salary*,**/assistant*,**/member*,**/index*,**/winback*,**/newconv*,**/relation_index*,**/spending*,**/stock*,**/finance_*,**/income_*,**/discount_*,**/order_contribution*,**/cfg_*,**/orchestration/**,**/config/**"
|
||||
name: dwd-doc-authority
|
||||
description: DWD-DOC 标杆文档强制规则。涉及 ETL 任务/财务/结算/消费/助教/会员/指数/统计/配置相关文件时自动加载。
|
||||
---
|
||||
|
||||
# DWD-DOC 标杆文档（权威数据源，强制优先参考）
|
||||
@@ -31,25 +34,11 @@ inclusion: always
|
||||
7. **现金流互斥**：`cash_inflow_total` 中 `platform_settlement_amount` 和 `groupbuy_pay_amount` 互斥
|
||||
8. **废单判断**：使用 `dwd_assistant_service_log_ex.is_trash`，`dwd_assistant_trash_event` 已废弃（2026-02-22 DROP）
|
||||
9. **储值卡字段命名**：DWS 层使用 `balance_pay`（总额）、`recharge_card_pay`（现金充值卡）、`gift_card_pay`（赠送卡）；`recharge_card_consume`（财务日报）
|
||||
10. **会员字段断档（DQ-6）**：`settlement_head.member_phone/member_name` 自 2025-12 起全为 NULL（上游不再下发）。需要会员手机号/昵称时，必须通过 `member_id` LEFT JOIN `dwd.dim_member`（字段 `mobile`/`nickname`，取 `scd2_is_current=1`），禁止直接使用 `member_phone`
|
||||
11. **会员卡字段断档（DQ-7）**：`settlement_head.member_card_type_name` 自 2025-07-21 起全为 NULL，`member_card_account_id` 全为 0。需要会员卡类型时，必须通过 `member_id` LEFT JOIN `dwd.dim_member_card_account`（关联 `tenant_member_id = member_id`，取 `scd2_is_current=1`），禁止直接使用 `member_card_type_name`。通用规则：结算单上所有会员相关冗余字段均不可靠，一律通过 ID 关联维度表获取
|
||||
|
||||
## 使用场景
|
||||
|
||||
- 编写或修改 ETL 任务代码（DWD/DWS 层）
|
||||
- 编写或修改后端 API 涉及金额计算的逻辑
|
||||
- 编写或修改小程序/管理后台涉及财务数据展示的页面
|
||||
- 编写 SQL 查询涉及结算、支付、消费金额
|
||||
- 编写或审阅 BD 手册、SPEC 文档中的字段口径描述
|
||||
- 前置调研（`pre-change-research.md`）中涉及财务/账务模块时
|
||||
10. **会员字段断档（DQ-6）**：`settlement_head.member_phone/member_name` 自 2025-12 起全为 NULL。需要会员信息时通过 `member_id` LEFT JOIN `dwd.dim_member`（取 `scd2_is_current=1`）
|
||||
11. **会员卡字段断档（DQ-7）**：`settlement_head.member_card_type_name` 自 2025-07-21 起全为 NULL。需要会员卡类型时通过 `member_id` LEFT JOIN `dwd.dim_member_card_account`（取 `scd2_is_current=1`）。通用规则：结算单上所有会员相关冗余字段均不可靠，一律通过 ID 关联维度表获取
|
||||
|
||||
## 与其他文档的优先级
|
||||
|
||||
当以下文档与 DWD-DOC 标杆文档冲突时，以 DWD-DOC 为准：
|
||||
- BD 手册（`apps/etl/connectors/feiqiu/docs/database/`）
|
||||
- ETL 任务文档（`apps/etl/connectors/feiqiu/docs/etl_tasks/`）
|
||||
- 业务规则文档（`apps/etl/connectors/feiqiu/docs/business-rules/`）
|
||||
- SPEC 文档（`docs/prd/specs/`）
|
||||
- DDL 注释（`docs/database/ddl/`）
|
||||
当 BD 手册、ETL 任务文档、业务规则文档、SPEC 文档、DDL 注释与 DWD-DOC 冲突时，以 DWD-DOC 为准。
|
||||
|
||||
> 标杆文档基于 2026-03-06 对 test_etl_feiqiu 数据库的实际数据验证，公式和比例关系具有权威性。
|
||||
|
||||
279
.kiro/steering/dws-doc-authority.md
Normal file
279
.kiro/steering/dws-doc-authority.md
Normal file
@@ -0,0 +1,279 @@
|
||||
---
|
||||
inclusion: fileMatch
|
||||
fileMatchPattern: "**/tasks/**,**/loaders/**,**/scd/**,**/dws/**,**/dwd/**,**/quality/**,**/business-rules/**,**/schemas/**,**/routers/**,**/financial*,**/settlement*,**/consume*,**/accounting*,**/salary*,**/assistant*,**/member*,**/index*,**/winback*,**/newconv*,**/relation_index*,**/spending*,**/stock*,**/finance_*,**/income_*,**/discount_*,**/order_contribution*,**/cfg_*,**/orchestration/**,**/config/**"
|
||||
name: dws-doc-authority
|
||||
description: DWS 层权威规范。涉及 ETL 任务/财务/结算/消费/助教/会员/指数/统计/配置相关文件时自动加载。
|
||||
---
|
||||
|
||||
# DWS 层权威规范（强制优先参考）
|
||||
|
||||
DWS（Data Warehouse Summary）层从 DWD 明细层按业务维度聚合计算，输出汇总统计表，服务于助教业绩、会员分析、财务统计、指数算法等业务场景。
|
||||
|
||||
> DWD-DOC（`docs/reports/DWD-DOC/`）中的强制规则在 DWS 层同样生效，本文档不重复列出。两者冲突时以 DWD-DOC 为准。
|
||||
|
||||
## 一、任务体系（19 个已注册任务）
|
||||
|
||||
### 1.1 助教业绩域（6 个）
|
||||
|
||||
| 任务代码 | 目标表 | 粒度 | 核心指标 |
|
||||
|----------|--------|------|----------|
|
||||
| `DWS_ASSISTANT_DAILY` | `dws_assistant_daily_detail` | 日期+助教 | 服务次数/时长/金额、去重客户数、废除统计、惩罚检测 |
|
||||
| `DWS_ASSISTANT_MONTHLY` | `dws_assistant_monthly_summary` | 月份+助教 | 月度累计、有效业绩、档位匹配、排名（考虑并列） |
|
||||
| `DWS_ASSISTANT_CUSTOMER` | `dws_assistant_customer_stats` | 日期+助教+会员 | 全量累计、6 个滚动窗口（7/10/15/30/60/90 天）、活跃度 |
|
||||
| `DWS_ASSISTANT_SALARY` | `dws_assistant_salary_calc` | 月份+助教 | 课时收入、奖金明细、应发工资、假期 |
|
||||
| `DWS_ASSISTANT_FINANCE` | `dws_assistant_finance_analysis` | 日期+助教 | 日度收入、日均成本、毛利润、毛利率 |
|
||||
| `DWS_ASSISTANT_ORDER_CONTRIBUTION` | `dws_assistant_order_contribution` | 日期+助教 | 订单总流水、净流水、时效贡献、时效净贡献 |
|
||||
|
||||
### 1.2 会员分析域（2 个）
|
||||
|
||||
| 任务代码 | 目标表 | 粒度 | 核心指标 |
|
||||
|----------|--------|------|----------|
|
||||
| `DWS_MEMBER_CONSUMPTION` | `dws_member_consumption_summary` | 日期+会员 | 全量累计消费、6 个滚动窗口、卡余额、活跃度、客户分层 |
|
||||
| `DWS_MEMBER_VISIT` | `dws_member_visit_detail` | 日期+会员+结账单 | 消费金额拆分、支付方式拆分、台桌时长、助教服务明细（JSON） |
|
||||
|
||||
### 1.3 财务统计域（4 个）
|
||||
|
||||
| 任务代码 | 目标表 | 粒度 | 核心指标 |
|
||||
|----------|--------|------|----------|
|
||||
| `DWS_FINANCE_DAILY` | `dws_finance_daily_summary` | 日期 | 发生额、优惠合计、确认收入、现金流入/流出/净变动、卡消费、充值统计 |
|
||||
| `DWS_FINANCE_RECHARGE` | `dws_finance_recharge_summary` | 日期 | 充值笔数/总额、首充/续充拆分、去重会员数、全店卡余额快照 |
|
||||
| `DWS_FINANCE_INCOME_STRUCTURE` | `dws_finance_income_structure` | 日期+收入类型 | 按收入类型（台费/商品/助教基础课/附加课）和区域分析 |
|
||||
| `DWS_FINANCE_DISCOUNT_DETAIL` | `dws_finance_discount_detail` | 日期+折扣类型 | 折扣类型拆分（GROUPBUY/VIP/ROUNDING/GIFT_CARD_*/BIG_CUSTOMER/OTHER） |
|
||||
|
||||
### 1.4 库存汇总域（3 个）
|
||||
|
||||
| 任务代码 | 目标表 | 粒度 | 更新策略 |
|
||||
|----------|--------|------|----------|
|
||||
| `DWS_GOODS_STOCK_DAILY` | `dws_goods_stock_daily_summary` | 日期+商品 | upsert |
|
||||
| `DWS_GOODS_STOCK_WEEKLY` | `dws_goods_stock_weekly_summary` | ISO 周+商品 | upsert |
|
||||
| `DWS_GOODS_STOCK_MONTHLY` | `dws_goods_stock_monthly_summary` | 月份+商品 | upsert |
|
||||
|
||||
### 1.5 运维任务（2 个）
|
||||
|
||||
| 任务代码 | 说明 |
|
||||
|----------|------|
|
||||
| `DWS_BUILD_ORDER_SUMMARY` | 构建订单汇总中间表 `dws_order_summary` |
|
||||
| `DWS_MAINTENANCE` | 统一维护：物化视图刷新 + 历史数据清理 |
|
||||
|
||||
|
||||
## 二、强制规则（所有 session 生效）
|
||||
|
||||
### 2.1 幂等更新策略
|
||||
1. **汇总表默认 delete-before-insert**：按日期范围 + `site_id` 先删后插，保证幂等
|
||||
2. **库存表使用 upsert**：`ON CONFLICT DO UPDATE`，因库存快照需保留最新值
|
||||
3. **禁止 TRUNCATE**：DWS 表数据量大，TRUNCATE 会导致全表锁定
|
||||
|
||||
### 2.2 课程类型与定价
|
||||
4. **课程类型通过 `cfg_skill_type` 映射**：`skill_id` → `course_type_code`（BASE/BONUS/ROOM），禁止硬编码 skill_id 判断课程类型
|
||||
5. **定价通过 `cfg_assistant_level_price` 取值**：按 SCD2 生效期 as-of join，禁止硬编码价格
|
||||
6. **包厢课统一价格**：`dws.salary.room_course_price = 138`（元/小时），从配置读取
|
||||
|
||||
### 2.3 绩效档位与工资
|
||||
7. **绩效档位通过 `cfg_performance_tier` 取值**：按有效业绩小时数匹配 `[min_hours, max_hours)` 区间
|
||||
8. **新入职折算规则**：入职日期在当月 1 日后视为新入职，按日均业绩 × 30 定档；入职日期 > 25 日最高定档至 T2
|
||||
9. **奖金规则通过 `cfg_bonus_rules` 取值**：SPRINT 类型不累计取最高档，TOP_RANK 类型按排名发放（第 1 名 1000 元、第 2 名 600 元、第 3 名 400 元）
|
||||
10. **排名计算考虑并列**：使用 `calculate_rank_with_ties()`，相同业绩小时数并列同名次
|
||||
|
||||
### 2.4 会员与散客
|
||||
11. **散客判断**：`member_id ≤ 0` 为散客，不计入会员统计（但计入助教业绩）
|
||||
12. **客户分层规则**：高价值（90 天 ≥ 3 次且 ≥ 1000 元）→ 中等（30 天内有消费）→ 低活跃（90 天内有但 30 天内无）→ 流失
|
||||
13. **会员信息一律通过 ID 关联维度表**：结算单上所有会员冗余字段均不可靠（DQ-6/DQ-7），通过 `member_id` LEFT JOIN `dwd.dim_member`（`scd2_is_current=1`）
|
||||
|
||||
### 2.5 时间窗口与调度
|
||||
14. **滚动窗口标准集**：7/10/15/30/60/90 天，使用 `calculate_rolling_stats()` 统一计算
|
||||
15. **月度任务宽限期**：月初前 `dws.monthly.prev_month_grace_days`（默认 5）天可处理上月数据
|
||||
16. **工资计算周期**：月初前 `dws.salary.run_days`（默认 5）天运行，超期需 `dws.salary.allow_out_of_cycle = true`
|
||||
|
||||
### 2.6 SCD2 维度取值
|
||||
17. **助教等级 as-of 取值**：工资计算按月份生效期取历史版本，日度统计按 `stat_date` 取当日版本
|
||||
18. **会员卡余额 as-of 取值**：通过 `get_member_card_balance_asof()` 按日期取快照
|
||||
|
||||
### 2.7 台桌分类
|
||||
19. **`cfg_area_category` 仅精确匹配 + 兜底**：2026-03-07 改版后无 LIKE 匹配，分类为 BILLIARD/SNOOKER/OTHER，`BILLIARD_VIP` 已废弃
|
||||
|
||||
## 三、指数算法体系
|
||||
|
||||
### 3.1 总览
|
||||
|
||||
| 指数 | 全称 | 输出表 | 作用 |
|
||||
|------|------|--------|------|
|
||||
| WBI | Winback Index | `dws_member_winback_index` | 老客挽回优先级 |
|
||||
| NCI | Newconv Index | `dws_member_newconv_index` | 新客转化优先级 |
|
||||
| RS | Relation Index | `dws_member_assistant_relation_index` | 助教-会员关系强度 |
|
||||
| OS | Ownership Index | — | 所有权指数 |
|
||||
| MS | Maintenance Score | — | 维护分 |
|
||||
| ML | Manual Ledger | `dws_ml_manual_order_alloc` | 人工台账（唯一真源） |
|
||||
| SPI | Spending Power Index | `dws_member_spending_power_index` | 消费力指数 |
|
||||
|
||||
### 3.2 WBI（老客挽回指数）强制规则
|
||||
20. **分项得分**：Overdue（超期分，加权经验 CDF）+ Drop（降频分，近 14 天差值）+ Recharge（充值压力，衰减分）+ Value（价值分，对数压缩）
|
||||
21. **Raw Score 公式**：`WBI_raw = w_over × overdue + w_drop × drop + w_re × recharge + w_value × value`
|
||||
22. **近访抑制（Recency Suppression）**：距今 < 14 天 suppression = 0（Hard floor）；14-17 天 Sigmoid 衰减
|
||||
23. **分流规则**：STOP（距今 ≥ 60 天，高余额例外可选）→ NEW（到店 ≤ 2 次或首访 ≤ 30 天或充值未回访）→ OLD（其他）
|
||||
|
||||
### 3.3 NCI（新客转化指数）强制规则
|
||||
24. **分项得分**：Welcome（欢迎分，首访/单访 3 天内触发）+ Need（转化紧迫度）+ Salvage（可救度，30-60 天线性衰减）+ Recharge/Value（同 WBI）
|
||||
25. **活跃抑制**：新客近 14 天来店 ≥ 2 次且最近活跃，用 0.2 系数抑制转化召回分
|
||||
|
||||
### 3.4 指数参数配置
|
||||
26. **参数通过 `cfg_index_parameters` 加载**：按 `index_type` 分组，支持 EWMA 平滑，禁止硬编码权重/阈值
|
||||
|
||||
|
||||
## 四、配置表体系
|
||||
|
||||
### 4.1 绩效档位（`dws.cfg_performance_tier`）
|
||||
|
||||
| 档位 | 小时区间 | 抽成（元/小时） | 打赏抽成 | 假期 |
|
||||
|------|----------|-----------------|----------|------|
|
||||
| T0（0 档） | 0-120 | 28 | 50% | 3 天 |
|
||||
| T1（1 档） | 120-150 | 18 | 40% | 4 天 |
|
||||
| T2（2 档） | 150-180 | 13 | 35% | 5 天 |
|
||||
| T3（3 档） | 180-210 | 10 | 30% | 6 天 |
|
||||
| T4（4 档） | 210+ | 8 | 25% | 自由假期 |
|
||||
|
||||
> 以上为 2026-03-01 起生效版本，历史版本通过 `effective_from/effective_to` SCD2 管理。
|
||||
|
||||
### 4.2 助教等级定价（`dws.cfg_assistant_level_price`）
|
||||
|
||||
| 等级 | 基础课（元/小时） | 附加课（元/小时） |
|
||||
|------|-------------------|-------------------|
|
||||
| 8（助教管理） | 98 | 190 |
|
||||
| 10（初级） | 98 | 190 |
|
||||
| 20（中级） | 108 | 190 |
|
||||
| 30（高级） | 118 | 190 |
|
||||
| 40（星级） | 138 | 190 |
|
||||
|
||||
### 4.3 奖金规则（`dws.cfg_bonus_rules`）
|
||||
|
||||
| 规则类型 | 生效期 | 说明 |
|
||||
|----------|--------|------|
|
||||
| SPRINT（冲刺奖金） | ≤ 2026-02-28 | 不累计，取最高档 |
|
||||
| TOP_RANK（排名奖金） | ≥ 2026-03-01 | 第 1 名 1000 元、第 2 名 600 元、第 3 名 400 元 |
|
||||
|
||||
### 4.4 技能→课程类型映射（`dws.cfg_skill_type`）
|
||||
|
||||
| 课程类型代码 | 名称 | 定价规则 |
|
||||
|-------------|------|----------|
|
||||
| BASE | 基础课（陪打/PD） | 按等级定价 98-138 元/小时 |
|
||||
| BONUS | 附加课（超休/CX） | 固定 190 元/小时 |
|
||||
| ROOM | 包厢课 | 统一 138 元/小时（`dws.salary.room_course_price`） |
|
||||
|
||||
### 4.5 台桌分类（`dws.cfg_area_category`）
|
||||
|
||||
| 分类代码 | 说明 | 备注 |
|
||||
|----------|------|------|
|
||||
| BILLIARD | 台球（含原 V1-V4） | 2026-03-07 改版 |
|
||||
| SNOOKER | 斯诺克（含原 V5） | 2026-03-07 改版 |
|
||||
| OTHER | 兜底 | 未匹配时归入 |
|
||||
|
||||
> `BILLIARD_VIP` 已废弃（2026-03-07），禁止引用。
|
||||
|
||||
### 4.6 指数参数（`dws.cfg_index_parameters`）
|
||||
|
||||
按 `index_type`（WBI/NCI/RS/OS/MS/ML/SPI）分组加载，支持 EWMA 平滑。所有权重和阈值从此表读取，禁止硬编码。
|
||||
|
||||
## 五、BaseDwsTask 公共机制
|
||||
|
||||
### 5.1 时间分层（TimeLayer）
|
||||
|
||||
| 枚举值 | 范围 | 用途 |
|
||||
|--------|------|------|
|
||||
| LAST_2_DAYS | 近 2 天 | 日度增量 |
|
||||
| LAST_1_MONTH | 近 30 天 | 月度汇总 |
|
||||
| LAST_3_MONTHS | 近 90 天 | 季度分析 |
|
||||
| LAST_6_MONTHS | 近 6 个月（不含本月） | 半年趋势 |
|
||||
| ALL | 从 2000-01-01 起 | 全量重算 |
|
||||
|
||||
### 5.2 配置缓存（ConfigCache）
|
||||
- 类级别共享，TTL 5 分钟
|
||||
- 包含：绩效档位、等级定价、奖金规则、区域分类、技能类型
|
||||
- 支持 SCD2 生效期过滤
|
||||
|
||||
### 5.3 数据读写方法
|
||||
- `iter_dwd_rows()`：分批迭代 DWD 数据（默认 1000 行/批）
|
||||
- `query_dwd()`：直接执行任意 SQL
|
||||
- `delete_existing_data()`：按日期范围 + site_id 删除
|
||||
- `bulk_insert()`：批量插入
|
||||
- `upsert()`：ON CONFLICT DO UPDATE
|
||||
|
||||
### 5.4 辅助计算
|
||||
- `calculate_rolling_stats()`：滚动窗口统计
|
||||
- `calculate_rank_with_ties()`：并列排名
|
||||
- `is_new_hire_in_month()`：新入职判断
|
||||
- `is_guest()`：散客判断（member_id ≤ 0）
|
||||
- `safe_decimal()` / `safe_int()`：安全类型转换
|
||||
- `seconds_to_hours()` / `hours_to_seconds()`：时间单位转换
|
||||
- `get_assistant_level_asof()`：SCD2 助教等级
|
||||
- `get_member_card_balance_asof()`：SCD2 会员卡余额
|
||||
|
||||
## 六、字段命名规范
|
||||
|
||||
### 6.1 金额字段
|
||||
- 统一 `NUMERIC(12,2)`，货币单位 CNY
|
||||
- 储值卡：DWS 层使用 `balance_pay`（总额）、`recharge_card_pay`（现金充值卡）、`gift_card_pay`（赠送卡）
|
||||
- 财务日报：使用 `recharge_card_consume`
|
||||
- 助教费用：`assistant_pd_money`（陪打）、`assistant_cx_money`（超休），禁止使用 `service_fee`
|
||||
|
||||
### 6.2 时间字段
|
||||
- `stat_date`：统计日期（DATE）
|
||||
- `stat_month`：统计月份（CHAR(7)，格式 YYYY-MM）
|
||||
- `created_at` / `updated_at`：TIMESTAMPTZ
|
||||
|
||||
### 6.3 标识字段
|
||||
- `site_id`：门店 ID（多门店隔离，RLS）
|
||||
- `tenant_id`：租户 ID
|
||||
- `member_id`：会员 ID（≤ 0 为散客）
|
||||
- `assistant_id`：助教 ID
|
||||
|
||||
## 七、调度与 Flow 类型
|
||||
|
||||
| Flow 类型 | 包含阶段 | 说明 |
|
||||
|-----------|----------|------|
|
||||
| `dwd_dws` | 仅 DWS 汇总 | 日常增量 |
|
||||
| `dwd_dws_index` | DWS 汇总 + 指数计算 | 含指数更新 |
|
||||
| `api_full` | ODS → DWD → DWS → INDEX | 全流程 |
|
||||
|
||||
处理模式：`increment_only`（默认）、`verify_only`（仅校验修复）、`increment_verify`（先增量后校验）
|
||||
|
||||
## 八、DWS 层完整表清单
|
||||
|
||||
### 汇总表
|
||||
`dws_assistant_daily_detail`、`dws_assistant_monthly_summary`、`dws_assistant_customer_stats`、`dws_assistant_salary_calc`、`dws_assistant_finance_analysis`、`dws_assistant_order_contribution`、`dws_member_consumption_summary`、`dws_member_visit_detail`、`dws_finance_daily_summary`、`dws_finance_recharge_summary`、`dws_finance_income_structure`、`dws_finance_discount_detail`、`dws_goods_stock_daily_summary`、`dws_goods_stock_weekly_summary`、`dws_goods_stock_monthly_summary`、`dws_order_summary`
|
||||
|
||||
### 指数表
|
||||
`dws_member_winback_index`、`dws_member_newconv_index`、`dws_member_recall_index`、`dws_member_assistant_relation_index`、`dws_member_assistant_intimacy`、`dws_member_spending_power_index`、`dws_index_percentile_history`
|
||||
|
||||
### 其他表
|
||||
`dws_platform_settlement`、`dws_ml_manual_order_source`、`dws_ml_manual_order_alloc`、`dws_assistant_recharge_commission`、`dws_assistant_project_tag`、`dws_member_project_tag`
|
||||
|
||||
### 视图
|
||||
`v_member_recall_priority`
|
||||
|
||||
### 配置表
|
||||
`cfg_performance_tier`、`cfg_assistant_level_price`、`cfg_bonus_rules`、`cfg_skill_type`、`cfg_area_category`、`cfg_index_parameters`
|
||||
|
||||
## 九、废弃对象（禁止引用）
|
||||
|
||||
| 对象 | 删除日期 | 替代方案 |
|
||||
|------|----------|----------|
|
||||
| `BILLIARD_VIP` 分类代码 | 2026-03-07 | V1-V4 归入 BILLIARD，V5 归入 SNOOKER |
|
||||
| `dwd_assistant_trash_event` | 2026-02-22 | `dwd_assistant_service_log_ex.is_trash` |
|
||||
| `RecallIndexTask` / `IntimacyIndexTask` | 2026-02-13 | WBI + NCI + RelationIndexTask |
|
||||
| SPRINT 奖金规则 | 2026-02-28 止 | TOP_RANK 排名奖金（2026-03-01 起） |
|
||||
|
||||
## 十、关键文档索引
|
||||
|
||||
| 文档 | 路径 |
|
||||
|------|------|
|
||||
| DWS 任务详解 | `apps/etl/connectors/feiqiu/docs/etl_tasks/dws_tasks.md` |
|
||||
| DWS 指标定义 | `apps/etl/connectors/feiqiu/docs/business-rules/dws_metrics.md` |
|
||||
| 指数算法说明 | `apps/etl/connectors/feiqiu/docs/business-rules/index_algorithm_cn.md` |
|
||||
| BaseDwsTask 机制 | `apps/etl/connectors/feiqiu/docs/etl_tasks/base_task_mechanism.md` |
|
||||
| BD 手册（DWS 表） | `apps/etl/connectors/feiqiu/docs/database/DWS/main/` |
|
||||
| DWD-DOC 权威规则 | `.kiro/steering/dwd-doc-authority.md` |
|
||||
|
||||
## 与其他文档的优先级
|
||||
|
||||
DWS 层开发时的参考优先级：DWD-DOC > 本文档 > BD 手册 > ETL 任务文档 > 业务规则文档 > DDL 注释。
|
||||
|
||||
> 本文档基于 2026-03-19 对项目代码、配置表、BD 手册和审计记录的全面收集整理。
|
||||
@@ -3,49 +3,17 @@ inclusion: always
|
||||
---
|
||||
# 产出物路径规范（强制）
|
||||
|
||||
Kiro 所有产出物分两类，各有归档规则，禁止随意散放。
|
||||
|
||||
## 一、程序输出（数据文件、日志、报告）
|
||||
|
||||
写入 `export/` 目录结构，路径从 `.env` 环境变量读取。禁止硬编码路径，禁止在 `export/` 外创建输出目录。
|
||||
|
||||
### 规则
|
||||
1. 环境变量缺失时必须报错（`KeyError` / `RuntimeError`），禁止静默回退
|
||||
2. 读取方式：`scripts/ops/` → `_env_paths.get_output_path()`；ETL 核心 → `AppConfig.io.*`；独立脚本 → `os.environ.get()` + 显式报错
|
||||
3. 新增输出类型：先在 `.env` + `.env.template` 加变量，再更新 `docs/deployment/EXPORT-PATHS.md`
|
||||
## 一、程序输出 → `export/` 目录
|
||||
路径从 `.env` 环境变量读取。禁止硬编码路径，禁止在 `export/` 外创建输出目录。
|
||||
- 环境变量缺失时必须报错，禁止静默回退
|
||||
- 读取方式：`scripts/ops/` → `_env_paths.get_output_path()`；ETL → `AppConfig.io.*`；独立脚本 → `os.environ.get()` + 显式报错
|
||||
- 新增输出类型：先在 `.env` + `.env.template` 加变量，再更新 `docs/deployment/EXPORT-PATHS.md`
|
||||
|
||||
> 完整目录结构与映射表见 `export-paths-full.md`（fileMatch 自动加载）。
|
||||
|
||||
## 二、文档产出（markdown、设计文档、分析报告）
|
||||
## 二、文档产出 → `docs/` 对应子目录
|
||||
禁止在 `docs/` 根目录散放文件（`README.md` 和 `DOCUMENTATION-MAP.md` 除外）。
|
||||
|
||||
写入 `docs/` 对应子目录，禁止在 `docs/` 根目录散放文件。
|
||||
常用归档路径：分析报告 → `docs/reports/`，架构 → `docs/architecture/`，BD 手册 → `docs/database/`（业务库）或 `apps/etl/.../docs/database/`（ETL），审计 → `docs/audit/changes/`，PRD → `docs/prd/specs/`，部署 → `docs/deployment/`。
|
||||
|
||||
### 归档规则
|
||||
|
||||
| 文档类型 | 目标目录 | 示例 |
|
||||
|----------|----------|------|
|
||||
| 数据分析报告、调研产出 | `docs/reports/` | 复杂订单分析、字段口径全景 |
|
||||
| 架构设计文档 | `docs/architecture/` | ETL 架构说明 |
|
||||
| 数据库变更审计（业务库 BD 手册） | `docs/database/` | `BD_Manual_*.md`（zqyy_app / FDW / RLS） |
|
||||
| 数据库变更审计（ETL BD 手册） | `apps/etl/.../docs/database/` | 模块专属表级文档、跨层映射 |
|
||||
| 变更审计记录 | `docs/audit/changes/` | `YYYY-MM-DD__<slug>.md` |
|
||||
| 产品需求规格 | `docs/prd/specs/` | P1-P11 需求 spec |
|
||||
| 数据契约（OpenAPI/Schema） | `docs/contracts/` | `backend-api.json` |
|
||||
| 部署与运维配置 | `docs/deployment/` | 启动清单、路径规范 |
|
||||
| 路线图与规划 | `docs/roadmap/` | 迁移计划、BACKLOG |
|
||||
| Spec 需求输入 | `docs/spec-input/` | 问题汇总供开启 Spec |
|
||||
| 外部参考资料 | `docs/reference/` | 第三方 API 指南 |
|
||||
| 迁移记录 | `docs/migrate/` | Monorepo 迁移总结 |
|
||||
| MCP 相关文档 | `docs/mcp/` | AI 查询手册 |
|
||||
| UI 原型 | `docs/h5_ui/` | H5 静态页面 |
|
||||
| 小程序前端开发指南 | `docs/miniprogram-dev/` | 页面开发流程、代理手册、规范参考 |
|
||||
| 运维手册 | `docs/ops/` | 故障排查流程 |
|
||||
| 权限矩阵 | `docs/permission_matrix/` | 角色-资源映射 |
|
||||
|
||||
### 禁止事项
|
||||
- 禁止在 `docs/` 根目录直接创建 `.md` 文件（`README.md` 和 `DOCUMENTATION-MAP.md` 除外）
|
||||
- 禁止将分析报告放入 `prd/specs/`（specs 只放需求规格）
|
||||
- 禁止将审计产物写入子模块内部（统一写 `docs/audit/`）
|
||||
- 模块专属文档放模块内部（如 `apps/etl/.../docs/`），不放 `docs/`
|
||||
|
||||
> 完整文档索引见 `docs/DOCUMENTATION-MAP.md`。
|
||||
> 完整归档规则表见 `doc-map.md`（手动加载）或 `docs/DOCUMENTATION-MAP.md`。
|
||||
|
||||
24
.kiro/steering/feiqiu-data-rules.md
Normal file
24
.kiro/steering/feiqiu-data-rules.md
Normal file
@@ -0,0 +1,24 @@
|
||||
---
|
||||
inclusion: always
|
||||
---
|
||||
# 飞球数据规范（入口索引）
|
||||
|
||||
涉及财务、结算、助教、会员、统计、指数、工资、任务调度、DWD/DWS 层开发时，必须参考以下两份权威文档（fileMatch 自动加载，也可手动引用）：
|
||||
|
||||
- `dwd-doc-authority.md` — DWD 层 11 条强制规则（consume_money 口径、支付恒等式、会员字段断档等）
|
||||
- `dws-doc-authority.md` — DWS 层 26 条强制规则（幂等策略、课程定价、绩效档位、指数算法、配置表体系等）
|
||||
- `docs/database/BD_Manual_fdw_reverse_retention_clue.md` — FDW 反向映射手册（ETL 库通过 postgres_fdw 只读访问业务库 `member_retention_clue` 维客线索表）
|
||||
|
||||
## 最高频硬规则速查（完整规则见上述文档）
|
||||
|
||||
1. `consume_money` 禁止直接用于计算 → 用 `items_sum` 拆分字段
|
||||
2. 助教费用必须拆分：`assistant_pd_money`（陪打）+ `assistant_cx_money`（超休）
|
||||
3. 支付恒等式：`balance_amount = recharge_card_amount + gift_card_amount`
|
||||
4. 会员信息一律通过 `member_id` JOIN 维度表（`scd2_is_current=1`），结算单冗余字段不可靠
|
||||
5. 散客：`member_id ≤ 0`
|
||||
6. 课程类型/定价/绩效档位/奖金/指数权重 → 全部从配置表读取，禁止硬编码
|
||||
7. DWS 汇总表默认 delete-before-insert，库存表用 upsert
|
||||
|
||||
## 参考优先级
|
||||
|
||||
DWD-DOC > DWS 权威规范 > BD 手册 > ETL 任务文档 > 业务规则文档 > DDL 注释
|
||||
@@ -30,7 +30,18 @@ NeoZQYY Monorepo — 面向台球门店业务的全栈数据平台。多门店
|
||||
- 审计产物统一写 `docs/audit/`，禁止写入子模块
|
||||
- 编码：UTF-8、纯 SQL、迁移脚本日期前缀、任务大写蛇形
|
||||
|
||||
## 废弃对象黑名单（高频误引）
|
||||
|
||||
| 对象 | 类型 | 删除日期 | 替代方案 |
|
||||
|------|------|----------|----------|
|
||||
| `dwd.dwd_assistant_trash_event` / `_ex` | DWD 表 | 2026-02-22 | `dwd_assistant_service_log_ex.is_trash` |
|
||||
| `ods.assistant_cancellation_records` | ODS 表 | 2026-02-22 | 不再需要独立链路 |
|
||||
| `ODS_ASSISTANT_ABOLISH` / `ASSISTANT_ABOLISH` | ETL/调度任务 | 2026-02-22 | 无 |
|
||||
| `BILLIARD_VIP` | cfg_area_category 分类代码 | 2026-03-07 | V1-V4 归入 `BILLIARD`，V5 归入 `SNOOKER` |
|
||||
|
||||
所有 `_archived/` 目录存放已废弃内容，除非用户明确要求，禁止读取或参考。
|
||||
|
||||
## 治理
|
||||
任何逻辑改动必须可追溯、可验证、可回滚。审计检测与提醒由 hooks 自动执行（`agent-on-stop` + `prompt-on-submit`），用户按需手动触发 `/audit`。
|
||||
任何逻辑改动必须可追溯、可验证、可回滚。审计检测与提醒由 hooks 自动执行。
|
||||
|
||||
> 详细目录树见 `structure.md`（fileMatch 自动加载）；ETL 功能细节见 `product-full.md`（fileMatch 自动加载）。
|
||||
|
||||
Reference in New Issue
Block a user