在准备环境前提交次全部更改。

.env.template

@@ -1,30 +1,367 @@
-# ============================================================
+# ==============================================================================
 # NeoZQYY Monorepo 公共环境配置模板
-# 复制为 .env 后填入实际值
-# ============================================================
+# ==============================================================================
+# 使用方式：复制为 .env 后填入实际值
+# 配置优先级：DEFAULTS < .env < .env.local < 环境变量 < CLI 参数
+# 语法：KEY=VALUE（正斜杠路径，布尔值用 true/false，列表用逗号分隔）
 
-# ---------- 数据库（公共） ----------
+# ------------------------------------------------------------------------------
+# 门店配置
+# ------------------------------------------------------------------------------
+STORE_ID=
+TIMEZONE=Asia/Shanghai
+
+# ------------------------------------------------------------------------------
+# 数据库配置
+# ------------------------------------------------------------------------------
+# 完整 DSN（优先使用，设置后忽略下面的分离式配置）
+PG_DSN=postgresql://user:password@host:5432/dbname
+
+# 分离式配置（不使用 DSN 时启用）
+# PG_HOST=localhost
+# PG_PORT=5432
+# PG_NAME=your_database
+# PG_USER=your_user
+# PG_PASSWORD=your_password
+
+# 连接超时（秒，默认 20）
+PG_CONNECT_TIMEOUT=10
+
+# ------------------------------------------------------------------------------
+# 数据库会话参数（ETL defaults.py → db.session.*）
+# ------------------------------------------------------------------------------
+# 会话时区（默认跟随 TIMEZONE）
+# DB_SESSION_TIMEZONE=Asia/Shanghai
+
+# SQL 语句超时（毫秒，默认 30000）
+# DB_STATEMENT_TIMEOUT_MS=30000
+
+# 锁等待超时（毫秒，默认 5000）
+# DB_LOCK_TIMEOUT_MS=5000
+
+# 事务空闲超时（毫秒，默认 600000 = 10 分钟）
+# DB_IDLE_IN_TX_TIMEOUT_MS=600000
+
+# ------------------------------------------------------------------------------
+# 数据库 Schema 配置
+# ------------------------------------------------------------------------------
+# CHANGE 2026-02-15 | 对齐新库 etl_feiqiu 六层架构
+# OLTP 业务数据 schema（默认 ods）
+SCHEMA_OLTP=ods
+
+# ETL 管理数据 schema（默认 meta）
+SCHEMA_ETL=meta
+
+# ------------------------------------------------------------------------------
+# 后端公共数据库连接参数（后端 config.py 从根 .env 读取）
+# ------------------------------------------------------------------------------
 DB_HOST=localhost
 DB_PORT=5432
 DB_USER=
 DB_PASSWORD=
 
-# ---------- ETL 数据库（etl_feiqiu） ----------
-ETL_DB_NAME=etl_feiqiu
+# ------------------------------------------------------------------------------
+# 业务数据库配置（后端 API 使用）
+# ------------------------------------------------------------------------------
+# 开发/测试环境使用 test_ 前缀库，生产环境切换为 zqyy_app / etl_feiqiu
+APP_DB_NAME=test_zqyy_app
 
-# ---------- 业务数据库（zqyy_app） ----------
-APP_DB_NAME=zqyy_app
+# ETL 数据库（后端只读访问，用于数据库查看器；省略时复用 DB_HOST/PORT/USER/PASSWORD）
+# ETL_DB_HOST=
+# ETL_DB_PORT=
+# ETL_DB_USER=
+# ETL_DB_PASSWORD=
+ETL_DB_NAME=test_etl_feiqiu
 
-# ---------- 时区 ----------
-TIMEZONE=Asia/Shanghai
+# ------------------------------------------------------------------------------
+# JWT 认证（后端使用，放在 apps/backend/.env.local 中）
+# ------------------------------------------------------------------------------
+# JWT_SECRET_KEY=change-me-in-production
+# JWT_ALGORITHM=HS256
+# JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30
+# JWT_REFRESH_TOKEN_EXPIRE_DAYS=7
 
-# ---------- 门店标识 ----------
-STORE_ID=
+# ------------------------------------------------------------------------------
+# 微信小程序配置（后端使用，放在 apps/backend/.env.local 中）
+# ------------------------------------------------------------------------------
+# 消息推送回调 Token（与微信后台填写的一致）
+# WX_CALLBACK_TOKEN=
+# 小程序 AppID（code2Session 登录时需要）
+# WX_APP_ID=
+# 小程序 AppSecret（禁止出现在前端代码中）
+# WX_APP_SECRET=
 
-# ---------- 上游 API ----------
-API_BASE_URL=
+# ------------------------------------------------------------------------------
+# CORS（后端使用，逗号分隔）
+# ------------------------------------------------------------------------------
+# CORS_ORIGINS=http://localhost:5173
+
+# ------------------------------------------------------------------------------
+# 日志级别
+# ------------------------------------------------------------------------------
+# LOG_LEVEL=INFO
+
+# ------------------------------------------------------------------------------
+# API 配置（上游 SaaS API）
+# ------------------------------------------------------------------------------
+API_BASE=
 API_TOKEN=
 
-# ---------- 日志 ----------
-LOG_LEVEL=INFO
-LOG_DIR=logs
+# API 请求超时（秒，默认 20）
+API_TIMEOUT=20
+
+# 分页大小（默认 200）
+API_PAGE_SIZE=200
+
+# 最大重试次数（默认 3）
+API_RETRY_MAX=3
+
+# 重试退避时间（JSON 数组格式，单位秒，默认 [1, 2, 4]）
+# API_RETRY_BACKOFF=[1, 2, 4]
+
+# 额外请求参数（JSON 对象格式）
+# API_PARAMS={}
+
+# 额外请求头（JSON 对象格式，默认空）
+# API_HEADERS_EXTRA={}
+
+# ------------------------------------------------------------------------------
+# 路径配置
+# ------------------------------------------------------------------------------
+# JSON 导出根目录
+EXPORT_ROOT=C:/NeoZQYY/export/ETL/JSON
+
+# 日志输出根目录
+LOG_ROOT=C:/NeoZQYY/export/ETL/LOG
+
+# 在线抓取 JSON 输出根目录（FETCH_ONLY 模式使用）
+FETCH_ROOT=C:/NeoZQYY/export/ETL/JSON
+
+# 本地清洗入库时的 JSON 输入目录（INGEST_ONLY 模式使用，为空则默认使用本次抓取目录）
+# INGEST_SOURCE_DIR=
+
+# manifest 文件名（默认 manifest.json）
+# MANIFEST_NAME=manifest.json
+
+# 入库报告文件名（默认 ingest_report.json）
+# INGEST_REPORT_NAME=ingest_report.json
+
+# 是否格式化输出 JSON（默认 true）
+WRITE_PRETTY_JSON=true
+
+# 单文件最大字节数（默认 50MB = 52428800）
+# MAX_FILE_BYTES=52428800
+
+# ------------------------------------------------------------------------------
+# 管线流程配置
+# ------------------------------------------------------------------------------
+# 运行流程：FULL（抓取+入库）、FETCH_ONLY（仅抓取落盘）、INGEST_ONLY（仅本地入库）
+PIPELINE_FLOW=FULL
+
+# 数据源模式（直接设置，不经 PIPELINE_FLOW 映射）：hybrid / online / offline
+# DATA_SOURCE=hybrid
+
+# ------------------------------------------------------------------------------
+# 时间窗口配置
+# ------------------------------------------------------------------------------
+# 窗口重叠秒数（默认 600，即 10 分钟）
+OVERLAP_SECONDS=600
+
+# 繁忙时段窗口分钟数（默认 30）
+WINDOW_BUSY_MIN=30
+
+# 空闲时段窗口分钟数（默认 180）
+WINDOW_IDLE_MIN=180
+
+# 空闲时段起止时间（默认 04:00 ~ 16:00）
+IDLE_START=04:00
+IDLE_END=16:00
+
+# 窗口切分单位（默认 day）
+WINDOW_SPLIT_UNIT=day
+
+# 窗口切分天数（默认 10）
+WINDOW_SPLIT_DAYS=10
+
+# 窗口补偿小时数（默认 2）
+WINDOW_COMPENSATION_HOURS=2
+
+# 空结果是否推进游标（默认 true）
+ALLOW_EMPTY_RESULT_ADVANCE=true
+
+# ------------------------------------------------------------------------------
+# 快照配置
+# ------------------------------------------------------------------------------
+# 快照缺失时是否删除（默认 true）
+SNAPSHOT_MISSING_DELETE=true
+
+# 快照为空时是否允许删除（默认 false）
+SNAPSHOT_ALLOW_EMPTY_DELETE=false
+
+# ------------------------------------------------------------------------------
+# 数据完整性检查配置
+# ------------------------------------------------------------------------------
+# 检查模式：history（历史区间）/ latest（最近一次）
+INTEGRITY_MODE=history
+
+# 历史检查起始日期
+INTEGRITY_HISTORY_START=2025-07-01
+
+# 历史检查结束日期（为空则到当天）
+# INTEGRITY_HISTORY_END=
+
+# 是否包含维度表（默认 true）
+INTEGRITY_INCLUDE_DIMENSIONS=true
+
+# 是否自动触发检查（默认 false）
+INTEGRITY_AUTO_CHECK=false
+
+# 是否自动回填缺失数据（默认 false）
+INTEGRITY_AUTO_BACKFILL=false
+
+# 是否比较内容（默认 true）
+INTEGRITY_COMPARE_CONTENT=true
+
+# 内容比较采样上限（默认 50）
+INTEGRITY_CONTENT_SAMPLE_LIMIT=50
+
+# 内容不一致时是否回填（默认 true）
+INTEGRITY_BACKFILL_MISMATCH=true
+
+# 回填后是否重新检查（默认 true）
+INTEGRITY_RECHECK_AFTER_BACKFILL=true
+
+# 指定 ODS 任务代码（逗号分隔，为空则全部）
+# INTEGRITY_ODS_TASK_CODES=
+
+# 是否强制按月切分（默认 true）
+# INTEGRITY_FORCE_MONTHLY_SPLIT=true
+
+# ------------------------------------------------------------------------------
+# 清洗配置（ETL defaults.py → clean.*）
+# ------------------------------------------------------------------------------
+# 是否记录未知字段（默认 true）
+# CLEAN_LOG_UNKNOWN_FIELDS=true
+
+# 未知字段日志上限（默认 50）
+# CLEAN_UNKNOWN_FIELDS_LIMIT=50
+
+# 哈希算法（默认 sha1）
+# CLEAN_HASH_ALGO=sha1
+
+# 哈希盐值（默认空）
+# CLEAN_HASH_SALT=
+
+# 严格数值校验（默认 true）
+# CLEAN_STRICT_NUMERIC=true
+
+# 金额舍入精度（默认 2 位小数）
+# CLEAN_ROUND_MONEY_SCALE=2
+
+# ------------------------------------------------------------------------------
+# 安全配置（ETL defaults.py → security.*）
+# ------------------------------------------------------------------------------
+# 日志中是否脱敏（默认 true）
+# SECURITY_REDACT_IN_LOGS=true
+
+# 需脱敏的键名（JSON 数组，默认 ["token","password","Authorization"]）
+# SECURITY_REDACT_KEYS=["token","password","Authorization"]
+
+# 日志中是否回显 token（默认 false，调试用）
+# SECURITY_ECHO_TOKEN_IN_LOGS=false
+
+# ------------------------------------------------------------------------------
+# 校验配置
+# ------------------------------------------------------------------------------
+# 抓取后校验时是否跳过 ODS 重载（默认 true）
+VERIFY_SKIP_ODS_ON_FETCH=true
+
+# 校验时是否使用本地 JSON（默认 true）
+VERIFY_ODS_LOCAL_JSON=true
+
+# ------------------------------------------------------------------------------
+# DWD 层配置
+# ------------------------------------------------------------------------------
+# 事实表是否使用 UPSERT（默认 true）
+DWD_FACT_UPSERT=true
+
+# 事实表 UPSERT 批量大小（默认 1000）
+# DWD_FACT_UPSERT_BATCH_SIZE=1000
+
+# 最小批量大小（锁冲突时自动缩小，默认 100）
+# DWD_FACT_UPSERT_MIN_BATCH_SIZE=100
+
+# 最大重试次数（默认 2）
+# DWD_FACT_UPSERT_MAX_RETRIES=2
+
+# 重试退避时间（JSON 数组，秒，默认 [1,2,4]）
+# DWD_FACT_UPSERT_RETRY_BACKOFF=[1,2,4]
+
+# 事实表 backfill 锁等待超时（毫秒，为空则沿用 DB_LOCK_TIMEOUT_MS）
+# DWD_FACT_UPSERT_LOCK_TIMEOUT_MS=
+
+# ------------------------------------------------------------------------------
+# 任务列表配置
+# ------------------------------------------------------------------------------
+# ODS 抓取任务列表（逗号分隔）
+RUN_TASKS=PRODUCTS,TABLES,MEMBERS,ASSISTANTS,PACKAGES_DEF,ORDERS,PAYMENTS,REFUNDS,COUPON_USAGE,INVENTORY_CHANGE,TOPUPS,TABLE_DISCOUNT,ASSISTANT_ABOLISH,LEDGER
+
+# DWS 汇总任务列表（逗号分隔，为空则不执行）
+# RUN_DWS_TASKS=
+
+# 指数计算任务列表（逗号分隔，为空则不执行）
+# RUN_INDEX_TASKS=
+
+# 指数回溯天数（默认 60）
+INDEX_LOOKBACK_DAYS=60
+
+# ------------------------------------------------------------------------------
+# DWS 月度/薪资配置
+# ------------------------------------------------------------------------------
+# 新人封顶生效日期（默认 2026-03-01）
+# DWS_MONTHLY_NEW_HIRE_CAP_EFFECTIVE_FROM=2026-03-01
+
+# 新人封顶天数（默认 25）
+# DWS_MONTHLY_NEW_HIRE_CAP_DAY=25
+
+# 新人最高等级（默认 2）
+# DWS_MONTHLY_NEW_HIRE_MAX_TIER_LEVEL=2
+
+# 薪资计算运行天数（默认 5）
+# DWS_SALARY_RUN_DAYS=5
+
+# 是否允许非周期内运行（默认 false）
+# DWS_SALARY_ALLOW_OUT_OF_CYCLE=false
+
+# 包房课单价（默认 138）
+# DWS_SALARY_ROOM_COURSE_PRICE=138
+
+# ------------------------------------------------------------------------------
+# DWS 月度额外参数
+# ------------------------------------------------------------------------------
+# 是否允许历史月度重算（默认 false）
+# DWS_MONTHLY_ALLOW_HISTORY=false
+
+# 上月宽限天数（默认 5，即次月 1-5 号仍可计算上月）
+# DWS_MONTHLY_PREV_GRACE_DAYS=5
+
+# 历史月份数（默认 0，即不回溯）
+# DWS_MONTHLY_HISTORY_MONTHS=0
+
+# ------------------------------------------------------------------------------
+# 后端 ETL 项目路径（后端 config.py 使用，缺省按 monorepo 相对路径推算）
+# ------------------------------------------------------------------------------
+# ETL_PROJECT_PATH=C:/NeoZQYY/apps/etl/connectors/feiqiu
+
+# ------------------------------------------------------------------------------
+# 数据流结构分析（analyze_dataflow.py 使用）
+# ------------------------------------------------------------------------------
+# 分析结果输出目录（缺省回退到 docs/reports/）
+# SYSTEM_ANALYZE_ROOT=C:/NeoZQYY/export/dataflow_analysis
+
+# ------------------------------------------------------------------------------
+# ODS 离线回放配置（仅开发/运维使用）
+# ------------------------------------------------------------------------------
+# ODS_JSON_DOC_DIR=export/test-json-doc
+# ODS_INCLUDE_FILES=
+# ODS_DROP_SCHEMA_FIRST=true