在前后端开发联调前 的提交20260223

apps/etl/connectors/feiqiu/docs/operations/environment_setup.md

@@ -51,15 +51,18 @@ uv sync --group test
 在项目根目录创建 `.env` 文件（禁止提交到版本控制）：
 
 ```dotenv
-# 数据库连接
+# 数据库连接（推荐使用 DSN 模式）
 PG_DSN=postgresql://用户名:密码@主机:端口/数据库名
-# 或分别指定
+# 或分离式配置（不使用 DSN 时启用）
 PG_HOST=localhost
 PG_PORT=5432
-PG_NAME=billiards
+PG_NAME=your_database
 PG_USER=your_user
 PG_PASSWORD=your_password
 
+# 业务库 DSN（后端 / 跨模块脚本使用）
+APP_DB_DSN=postgresql://用户名:密码@主机:端口/数据库名
+
 # 门店与 API
 STORE_ID=1
 API_TOKEN=your_bearer_token
@@ -99,19 +102,22 @@ config/defaults.py  →  .env / 环境变量  →  CLI 参数
 初始化步骤：
 
 ```bash
-# 1. 执行 DDL 创建表结构（DDL 文件位于 db/etl_feiqiu/schemas/）
-psql "$PG_DSN" -f db/etl_feiqiu/schemas/schema_etl_admin.sql
-psql "$PG_DSN" -f db/etl_feiqiu/schemas/schema_ODS_doc.sql
-psql "$PG_DSN" -f db/etl_feiqiu/schemas/schema_dwd_doc.sql
-psql "$PG_DSN" -f db/etl_feiqiu/schemas/schema_dws.sql
+# 推荐使用 CLI 工具任务初始化（DDL 基线见 docs/database/ddl/）
+python -m cli.main --tasks INIT_ODS_SCHEMA,INIT_DWD_SCHEMA,INIT_DWS_SCHEMA,SEED_DWS_CONFIG --pg-dsn "$PG_DSN"
 
-# 2. 执行种子数据（如有）
+# 或手动执行 DDL（从 docs/database/ddl/ 获取最新基线）
+psql "$PG_DSN" -f docs/database/ddl/etl_feiqiu__meta.sql
+psql "$PG_DSN" -f docs/database/ddl/etl_feiqiu__ods.sql
+psql "$PG_DSN" -f docs/database/ddl/etl_feiqiu__dwd.sql
+psql "$PG_DSN" -f docs/database/ddl/etl_feiqiu__dws.sql
+
+# 执行种子数据
 psql "$PG_DSN" -f db/etl_feiqiu/seeds/seed_*.sql
-
-# 3. 执行迁移脚本（按日期前缀顺序）
-ls db/etl_feiqiu/migrations/*.sql | sort | xargs -I {} psql "$PG_DSN" -f {}
 ```
 
+> 注：旧的 `db/etl_feiqiu/schemas/` 和 `db/etl_feiqiu/migrations/` 已归档至 `db/_archived/`。
+> DDL 基线现由 `docs/database/ddl/` 统一管理，可通过 `python scripts/ops/gen_consolidated_ddl.py` 重新生成。
+
 或使用 CLI 工具任务初始化：
 
 ```bash