Neo
b25308c3f4
## P1 数据库基础 - zqyy_app: 创建 auth/biz schema、FDW 连接 etl_feiqiu - etl_feiqiu: 创建 app schema RLS 视图、商品库存预警表 - 清理 assistant_abolish 残留数据 ## P2 ETL/DWS 扩展 - 新增 DWS 助教订单贡献度表 (dws.assistant_order_contribution) - 新增 assistant_order_contribution_task 任务及 RLS 视图 - member_consumption 增加充值字段、assistant_daily 增加处罚字段 - 更新 ODS/DWD/DWS 任务文档及业务规则文档 - 更新 consistency_checker、flow_runner、task_registry 等核心模块 ## P3 小程序鉴权系统 - 新增 xcx_auth 路由/schema（微信登录 + JWT） - 新增 wechat/role/matching/application 服务层 - zqyy_app 鉴权表迁移 + 角色权限种子数据 - auth/dependencies.py 支持小程序 JWT 鉴权 ## 文档与审计 - 新增 DOCUMENTATION-MAP 文档导航 - 新增 7 份 BD_Manual 数据库变更文档 - 更新 DDL 基线快照（etl_feiqiu 6 schema + zqyy_app auth） - 新增全栈集成审计记录、部署检查清单更新 - 新增 BACKLOG 路线图、FDW→Core 迁移计划 ## Kiro 工程化 - 新增 5 个 Spec（P1/P2/P3/全栈集成/核心业务） - 新增审计自动化脚本（agent_on_stop/build_audit_context/compliance_prescan） - 新增 6 个 Hook（合规检查/会话日志/提交审计等） - 新增 doc-map steering 文件 ## 运维与测试 - 新增 ops 脚本：迁移验证/API 健康检查/ETL 监控/集成报告 - 新增属性测试：test_dws_contribution / test_auth_system - 清理过期 export 报告文件 - 更新 .gitignore 排除规则
4.4 KiB
故障排查手册
1. 数据库连接问题
1.1 连接超时
现象：psycopg2.OperationalError: connection timed out 或启动后长时间无响应。
排查步骤：
- 确认
PG_DSN或PG_HOST/PG_PORT配置正确 - 确认 PostgreSQL 服务可达：
pg_isready -h <host> -p <port> - 检查防火墙/安全组是否放行端口
- 系统限制连接超时为 1–20 秒（
db.connect_timeout_sec，默认 20 秒）
1.2 认证失败
现象：FATAL: password authentication failed for user "xxx"
排查步骤：
- 确认
.env中的PG_USER和PG_PASSWORD正确 - 确认 PostgreSQL 的
pg_hba.conf允许远程连接 - 如使用 DSN 格式，确认密码中的特殊字符已 URL 编码
1.3 Schema 不存在
现象：relation "ods.xxx" does not exist
解决方案：执行 DDL 初始化脚本，参见 环境搭建指南。
2. API 相关问题
2.1 API Token 无效
现象：HTTP 401 或 403 错误。
排查步骤：
- 确认
.env中的API_TOKEN有效且未过期 - 可通过 CLI 参数
--api-token临时覆盖测试 - 检查 Token 是否包含多余空格或换行符
2.2 API 超时
现象：requests.exceptions.Timeout 或 ReadTimeout
排查步骤：
- 默认超时为 20 秒（
api.timeout_sec），可通过--api-timeout调大 - 系统自动重试最多 3 次（退避间隔 1/2/4 秒）
- 检查网络连通性和上游服务状态
2.3 API 分页数据不完整
现象：抓取的记录数明显少于预期。
排查步骤：
- 检查时间窗口是否覆盖目标范围（
--window-start/--window-end） - 确认分页大小设置合理（
api.page_size，默认 200） - 使用
--dry-run查看实际请求的时间窗口
3. ETL 任务问题
3.1 任务代码不存在
现象：ValueError: 未注册的任务代码: XXX
解决方案：确认任务代码拼写正确（大写蛇形命名），可用的任务代码在 orchestration/task_registry.py 中注册。
3.2 DWD 装载失败
现象：DWD_LOAD_FROM_ODS 任务报错或数据不一致。
排查步骤：
- 确认 ODS 层数据已成功入库
- 检查是否有 Schema 变更未执行迁移脚本
- 查看日志中的具体错误信息（字段类型不匹配、约束冲突等）
3.3 DWS 汇总数据异常
现象：汇总指标与明细数据不一致。
排查步骤：
- 使用
--processing-mode verify_only执行校验 - 配合
--verify-tables指定具体表进行单表验证 - 检查 DWD 层数据是否完整（时间窗口是否覆盖）
3.4 锁冲突
现象：ERROR: deadlock detected 或 lock timeout
排查步骤：
- 避免多个 ETL 进程同时运行
- 调整锁超时：
db.session.lock_timeout_ms（默认 5000ms） - 事实表 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'
解决方案：
uv sync
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）在日志中自动脱敏