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

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

@@ -0,0 +1,140 @@
+# 故障排查手册
+
+## 1. 数据库连接问题
+
+### 1.1 连接超时
+
+**现象**：`psycopg2.OperationalError: connection timed out` 或启动后长时间无响应。
+
+**排查步骤**：
+1. 确认 `PG_DSN` 或 `PG_HOST`/`PG_PORT` 配置正确
+2. 确认 PostgreSQL 服务可达：`pg_isready -h <host> -p <port>`
+3. 检查防火墙/安全组是否放行端口
+4. 系统限制连接超时为 1–20 秒（`db.connect_timeout_sec`，默认 20 秒）
+
+### 1.2 认证失败
+
+**现象**：`FATAL: password authentication failed for user "xxx"`
+
+**排查步骤**：
+1. 确认 `.env` 中的 `PG_USER` 和 `PG_PASSWORD` 正确
+2. 确认 PostgreSQL 的 `pg_hba.conf` 允许远程连接
+3. 如使用 DSN 格式，确认密码中的特殊字符已 URL 编码
+
+### 1.3 Schema 不存在
+
+**现象**：`relation "ods.xxx" does not exist`
+
+**解决方案**：执行 DDL 初始化脚本，参见 [环境搭建指南](environment_setup.md#4-数据库初始化)。
+
+## 2. API 相关问题
+
+### 2.1 API Token 无效
+
+**现象**：HTTP 401 或 403 错误。
+
+**排查步骤**：
+1. 确认 `.env` 中的 `API_TOKEN` 有效且未过期
+2. 可通过 CLI 参数 `--api-token` 临时覆盖测试
+3. 检查 Token 是否包含多余空格或换行符
+
+### 2.2 API 超时
+
+**现象**：`requests.exceptions.Timeout` 或 `ReadTimeout`
+
+**排查步骤**：
+1. 默认超时为 20 秒（`api.timeout_sec`），可通过 `--api-timeout` 调大
+2. 系统自动重试最多 3 次（退避间隔 1/2/4 秒）
+3. 检查网络连通性和上游服务状态
+
+### 2.3 API 分页数据不完整
+
+**现象**：抓取的记录数明显少于预期。
+
+**排查步骤**：
+1. 检查时间窗口是否覆盖目标范围（`--window-start` / `--window-end`）
+2. 确认分页大小设置合理（`api.page_size`，默认 200）
+3. 使用 `--dry-run` 查看实际请求的时间窗口
+
+## 3. ETL 任务问题
+
+### 3.1 任务代码不存在
+
+**现象**：`ValueError: 未注册的任务代码: XXX`
+
+**解决方案**：确认任务代码拼写正确（大写蛇形命名），可用的任务代码在 `orchestration/task_registry.py` 中注册。
+
+### 3.2 DWD 装载失败
+
+**现象**：`DWD_LOAD_FROM_ODS` 任务报错或数据不一致。
+
+**排查步骤**：
+1. 确认 ODS 层数据已成功入库
+2. 检查是否有 Schema 变更未执行迁移脚本
+3. 查看日志中的具体错误信息（字段类型不匹配、约束冲突等）
+
+### 3.3 DWS 汇总数据异常
+
+**现象**：汇总指标与明细数据不一致。
+
+**排查步骤**：
+1. 使用 `--processing-mode verify_only` 执行校验
+2. 配合 `--verify-tables` 指定具体表进行单表验证
+3. 检查 DWD 层数据是否完整（时间窗口是否覆盖）
+
+### 3.4 锁冲突
+
+**现象**：`ERROR: deadlock detected` 或 `lock timeout`
+
+**排查步骤**：
+1. 避免多个 ETL 进程同时运行
+2. 调整锁超时：`db.session.lock_timeout_ms`（默认 5000ms）
+3. 事实表 upsert 可调整批量大小：`dwd.fact_upsert_batch_size`（默认 1000）
+
+## 4. 配置问题
+
+### 4.1 缺少必需配置
+
+**现象**：`SystemExit: 缺少必需配置: app.store_id`
+
+**解决方案**：在 `.env` 中设置 `STORE_ID`，或通过 CLI 参数 `--store-id` 指定。
+
+### 4.2 配置优先级不符合预期
+
+**排查步骤**：配置加载顺序为 `config/defaults.py` → `.env` → CLI 参数，后者覆盖前者。使用 `--dry-run` 可在不写库的情况下验证最终配置。
+
+### 4.3 弃用配置警告
+
+**现象**：`DeprecationWarning: 配置键 pipeline.flow=XXX 已弃用`
+
+**解决方案**：将 `.env` 中的 `PIPELINE_FLOW` 替换为 `DATA_SOURCE`。映射关系：`FULL` → `hybrid`，`FETCH_ONLY` → `online`，`INGEST_ONLY` → `offline`。
+
+## 5. 运行环境问题
+
+### 5.1 Python 版本不兼容
+
+**现象**：`SyntaxError` 或类型注解相关错误。
+
+**解决方案**：确认 Python 版本 ≥ 3.10。代码使用了 `X | Y` 联合类型语法（3.10+）。
+
+### 5.2 依赖缺失
+
+**现象**：`ModuleNotFoundError: No module named 'xxx'`
+
+**解决方案**：
+```bash
+pip install -r requirements.txt
+```
+
+### 5.3 编码问题
+
+**现象**：`UnicodeDecodeError` 或中文乱码。
+
+**解决方案**：确保终端和文件编码为 UTF-8。Windows 下可设置 `chcp 65001`。
+
+## 6. 日志与调试
+
+- 日志通过 `utils/logging_utils.py` 统一管理
+- 日志输出目录：`export/LOG`（可通过 `--log-root` 覆盖）
+- 使用 `--dry-run` 进行试运行，不提交数据库事务
+- 安全配置 `security.redact_in_logs` 默认开启，敏感字段（token、password）在日志中自动脱敏