Updata2

README.md

@@ -78,6 +78,46 @@ python -m cli.main \
 - `FETCH_ONLY`：仅在线抓取落盘，不入库
 - `INGEST_ONLY`：仅从本地 JSON 回放入库（适合离线回放/补跑）
 
+## DWS 层（汇总/财务）
+
+### 建表与初始化
+- 建表：`INIT_DWS_SCHEMA`
+- 配置：`SEED_DWS_CONFIG`
+- 订单汇总（可选）：`DWS_BUILD_ORDER_SUMMARY`
+
+### 任务与调度建议
+- **每小时**：`DWS_ASSISTANT_DAILY`、`DWS_FINANCE_DAILY`、`DWS_FINANCE_INCOME_STRUCTURE`
+- **每日**：`DWS_ASSISTANT_MONTHLY`、`DWS_ASSISTANT_CUSTOMER`、`DWS_MEMBER_CONSUMPTION`、`DWS_MEMBER_VISIT`、`DWS_FINANCE_DISCOUNT_DETAIL`、`DWS_FINANCE_RECHARGE`、`DWS_ASSISTANT_FINANCE`
+- **每月（月初）**：`DWS_ASSISTANT_SALARY`
+- **维护清理（按需）**：`DWS_RETENTION_CLEANUP`
+
+调度配置默认保存在 `etl_billiards/scheduled_tasks.json`，GUI 调度器会读取该文件。
+
+### 时间口径
+- 周起始日：周一
+- 月/季度起始：第一天 0 点
+- 环比：对比上一个等长区间
+- 窗口类型：本周/上周/本月/上月/前3个月不含本月/前3个月含本月/本季度/上季度/最近半年不含本月
+
+### Excel 导入（支出/平台回款/充值提成）
+脚本：`etl_billiards/scripts/import_dws_excel.py`
+- 支出结构：`--type expense`，按月导入（房租/水电/物业/工资/报销/平台服务费等）
+- 平台回款：`--type platform`，按回款日期导入（回款金额、佣金、服务费、订单号等）
+- 充值提成：`--type commission`，按月份导入（助教ID、提成金额、充值订单金额等）
+
+### 大客户优惠拆分（可选）
+用于将手动调整拆分为“大客户优惠/其他优惠”，可在配置中指定：
+- `dws.discount.big_customer_member_ids`：会员ID列表（逗号分隔）
+- `dws.discount.big_customer_order_ids`：订单ID列表（逗号分隔）
+未配置时，大客户金额为 0，手动调整全部计入“其他优惠”。
+
+### 时间分层清理（可选）
+任务：`DWS_RETENTION_CLEANUP`，按配置清理历史数据
+- `dws.retention.enabled`：是否启用
+- `dws.retention.layer`：分层（如 `LAST_3_MONTHS`）
+- `dws.retention.tables`：需要清理的表列表（逗号分隔）
+- `dws.retention.table_layers`：表级分层覆盖（JSON 字符串）
+
 ## 目录结构与关键文件
 - 仓库根目录：`etl_billiards/` 主代码；`app/` 示例 runner；`开发笔记/` 项目笔记；`tmp/` 草稿/调试归档；`requirements.txt`（仓库根）依赖；`run_etl.sh/.bat` 启动脚本。  
   - 注意：根目录的 `run_etl.sh/.bat` 运行时要求当前目录为 `etl_billiards/`（因为入口是 `python -m cli.main`）。
@@ -367,6 +407,95 @@ python -m cli.main \
 6) 去嵌套：数组展开为子表/子行，重复 profile 提炼为维度。  
 7) 长期演进：优先加列/加表，减少对已有表结构的破坏。
 
+## DWS 数据层（汇总层）
+
+DWS（Data Warehouse Service）层基于 DWD 明细层数据构建，提供预聚合的数据服务。
+
+### 表结构概览
+
+| 分类 | 表数量 | 说明 |
+|------|--------|------|
+| 配置表 | 5 | 绩效档位、等级定价、奖金规则、区域分类、技能映射 |
+| 助教维度 | 5 | 日度/月度业绩、客户统计、工资计算、充值提成 |
+| 客户维度 | 2 | 消费汇总、来店明细 |
+| 财务维度 | 7 | 日度汇总、收入结构、优惠明细、充值统计、支出、助教收支、平台结算 |
+| 订单汇总 | 1 | 订单级别聚合 |
+
+### 核心特性
+
+- **时间分层**：支持近2天/近1月/近3月/全量的时间窗口筛选
+- **滚动窗口**：支持7/10/15/30/60/90天的滚动统计
+- **SCD2 as-of**：维度取值支持按时间点获取历史值（如助教等级）
+- **幂等更新**：采用 delete-before-insert 策略，支持重复执行
+- **Excel导入**：支出/平台结算/充值提成支持手动导入
+
+### 助教工资计算
+
+**绩效档位（6档 + 新入职）**
+
+| 档位 | 业绩阈值 | 专业课抽成 | 打赏课抽成 | 休假 |
+|------|----------|-----------|-----------|------|
+| T0 | H < 100 | 28元/时 | 50% | 3天 |
+| T1 | 100 ≤ H < 130 | 18元/时 | 40% | 4天 |
+| T2 | 130 ≤ H < 160 | 15元/时 | 38% | 4天 |
+| T3 | 160 ≤ H < 190 | 13元/时 | 35% | 5天 |
+| T4 | 190 ≤ H < 220 | 10元/时 | 33% | 6天 |
+| T5 | H ≥ 220 | 8元/时 | 30% | 休假自由 |
+
+**工资计算公式**
+
+```
+基础课收入 = 基础课小时数 × (客户支付价格 - 专业课抽成)
+附加课收入 = 附加课小时数 × 190 × (1 - 打赏课抽成比例)
+应发工资 = 课时收入 + 奖金
+```
+
+**计算示例（中级助教185小时，3档）**
+- 基础课170小时: 170 × (108 - 13) = 16,150元
+- 附加课15小时: 15 × 190 × (1 - 0.35) = 1,852.5元
+- 课时收入: 18,002.5元
+
+**等级定价（客户支付价格）**
+
+| 等级 | 基础课价格 | 附加课价格 |
+|------|-----------|-----------|
+| 初级 | 98元/时 | 190元/时 |
+| 中级 | 108元/时 | 190元/时 |
+| 高级 | 118元/时 | 190元/时 |
+| 星级 | 138元/时 | 190元/时 |
+
+### 运行 DWS 任务
+
+```bash
+# 初始化 DWS Schema
+python -m cli.main --tasks INIT_DWS_SCHEMA
+
+# 执行配置数据初始化
+psql -f etl_billiards/database/seed_dws_config.sql
+
+# 执行 DWS 订单汇总构建
+python -m cli.main --tasks DWS_BUILD_ORDER_SUMMARY
+```
+
+### Excel 数据导入
+
+```bash
+# 导入支出数据
+python etl_billiards/scripts/import_dws_excel.py --type expense --file expenses.xlsx
+
+# 导入平台结算
+python etl_billiards/scripts/import_dws_excel.py --type platform --file platform.xlsx
+
+# 导入充值提成
+python etl_billiards/scripts/import_dws_excel.py --type commission --file commission.xlsx
+```
+
+### 相关文档
+
+- `etl_billiards/docs/dws_tables_dictionary.md`：DWS 数据字典
+- `etl_billiards/database/schema_dws.sql`：DWS DDL
+- `etl_billiards/database/seed_dws_config.sql`：配置初始数据
+
 ## 常用 CLI
 ```bash
 cd etl_billiards
@@ -474,11 +603,37 @@ python scripts/test_db_connection.py --dsn "postgresql://user:pwd@host:5432/db"
 
 > 完整字段级映射见 `etl_billiards/docs/` 与 ODS/DWD DDL。
 
-## 当前状态（2025-12-09）
+## 当前状态（2026-02-02）
 - 示例 JSON 已全量灌入，DWD 行数与 ODS 对齐。  
 - 分类维度已展平大类+子类：`dim_goods_category` 26 行（category_level/leaf 已赋值）。  
 - 部分空字段源数据即为空，如需补值请先确认上游。
 
+### 2026-02-02 更新：字段补全
+
+本次更新完成了 API → ODS → DWD 全链路字段补全：
+
+**ODS 新增字段**（16 张表，共 50+ 字段）：
+- `settlement_records`/`recharge_settlements`：电费相关字段（`electricitymoney`、`realelectricitymoney`、`electricityadjustmoney`）、券销售额、结算明细列表
+- `table_fee_transactions`：活动折扣金额、订单消费类型、实际服务费
+- `assistant_service_records`：助教团队名称、实际服务费
+- `group_buy_redemption_records`：会员折扣、各类分摊金额（台费/商品/助教/充值）
+- `table_fee_discount_records`：台区信息、台桌名称/价格、免费标记
+- `member_stored_value_cards`：本金余额、会员等级、电费相关配置
+- `member_profiles`：累计支付/充值金额、注册来源
+- `member_balance_changes`：本金变动（前/后/数据）
+- `group_buy_packages`：排序、首单限制、租户券销售订单项ID
+- 其他：商品编码/停售、租户ID等
+
+**DWD 新增字段**：
+- 主表新增核心业务字段（金额、ID、状态）
+- 扩展表新增配置/明细字段
+
+**数据补全脚本**：
+- `scripts/backfill_202507_to_now.bat`：从 2025-07-01 重新抓取并装载数据
+
+**文档更新**：
+- `etl_billiards/docs/bd_manual/` 下所有相关表文档已同步更新
+
 ## 可精简/归档
 - `tmp/`、`tmp/etl_billiards_misc/` 中草稿、旧备份、调试脚本仅供参考，不影响运行。  
 - 根级保留必要文件（README、requirements、run_etl.*），其余临时文件按需归档至 `tmp/`。