feat: P1-P3 全栈集成 — 数据库基础 + DWS 扩展 + 小程序鉴权 + 工程化体系

## 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 排除规则
2026-02-26 08:03:53 +08:00
parent fafc95e64c
commit b25308c3f4
224 changed files with 17660 additions and 32198 deletions
--- a/.kiro/specs/[ETL]-fullstack-integration/.config.kiro
+++ b/.kiro/specs/[ETL]-fullstack-integration/.config.kiro
@@ -0,0 +1 @@
+{"generationMode": "requirements-first"}
--- a/.kiro/specs/[ETL]-fullstack-integration/design.md
+++ b/.kiro/specs/[ETL]-fullstack-integration/design.md
@@ -0,0 +1,252 @@
+# 设计文档：ETL 全流程前后端联调（etl-fullstack-integration）
+
+## 概述
+
+本 Spec 是一个运维联调任务，不涉及新功能开发。目标是验证 `admin-web-console` Spec 产出的前后端代码在真实环境下的端到端正确性，同时收集性能数据。
+
+核心流程：
+1. 启动后端 + 前端服务
+2. 通过 API 登录获取 JWT
+3. 提交全流程 ETL 任务（api_full, full_window, force-full, 全选常用任务, 自定义窗口 2025-11-01~2026-02-20, 30天切分, 全部门店）
+4. 实时监控执行过程，捕获错误/警告
+4. 执行完成后进行黑盒数据一致性测试（全链路检查器 `scripts/ops/etl_consistency_check.py` + FlowRunner 内置 `ConsistencyChecker`）
+5. 生成综合报告（含性能数据和黑盒测试结果）
+
+## 架构
+
+```
+联调脚本 (scripts/ops/)
+    │
+    ├── 1. 启动服务
+    │   ├── uvicorn app.main:app (后端 :8000)
+    │   └── pnpm dev (前端 :5173)
+    │
+    ├── 2. API 调用链
+    │   ├── POST /api/auth/login → JWT
+    │   ├── GET /api/tasks/registry → 任务列表
+    │   ├── GET /api/tasks/sync-check → 同步检查
+    │   ├── POST /api/tasks/validate → CLI 预览
+    │   └── POST /api/execution/run → 触发执行
+    │
+    ├── 3. 监控循环
+    │   ├── GET /api/execution/queue → 状态轮询
+    │   ├── GET /api/execution/{id}/logs → 日志获取
+    │   └── 错误/警告检测
+    │
+    ├── 4. 黑盒数据一致性测试
+    │   ├── 全链路检查器（scripts/ops/etl_consistency_check.py）
+    │   │   ├── API JSON vs ODS：字段完整性 + 值采样比对
+    │   │   ├── ODS vs DWD：行数 + 字段映射 + 值比对（含 EX 表合并）
+    │   │   ├── DWD vs DWS：聚合表行数 + 数值列健全性检查
+    │   │   └── 白名单机制：ETL_META_COLS / SCD2_COLS / 空字符串≡None
+    │   ├── FlowRunner 内置检查（quality/consistency_checker.py，自动执行）
+    │   └── etl-data-consistency Hook（可选手动触发）
+    │
+    └── 5. 报告生成
+        └── 输出到 SYSTEM_LOG_ROOT
+```
+
+## 任务参数
+
+根据用户需求，联调任务的具体参数：
+
+```python
+INTEGRATION_TASK_CONFIG = {
+    "flow": "api_full",                    # 全流程：API → ODS → DWD → DWS → INDEX
+    "processing_mode": "full_window",      # 全窗口处理
+    "window_mode": "custom",               # 自定义时间范围
+    "window_start": "2025-11-01 00:00",
+    "window_end": "2026-02-20 00:00",
+    "window_split": "day",                 # 按天切分
+    "window_split_days": 30,               # 30天一个切片
+    "force_full": True,                    # 强制全量
+    "dry_run": False,
+    "tasks": [                             # 全选 is_common=True 的任务
+        # ODS 层（22 个）
+        "ODS_ASSISTANT_ACCOUNT", "ODS_ASSISTANT_LEDGER", "ODS_ASSISTANT_ABOLISH",
+        "ODS_SETTLEMENT_RECORDS", "ODS_TABLE_USE", "ODS_TABLE_FEE_DISCOUNT",
+        "ODS_TABLES", "ODS_PAYMENT", "ODS_REFUND", "ODS_PLATFORM_COUPON",
+        "ODS_MEMBER", "ODS_MEMBER_CARD", "ODS_MEMBER_BALANCE", "ODS_RECHARGE_SETTLE",
+        "ODS_GROUP_PACKAGE", "ODS_GROUP_BUY_REDEMPTION",
+        "ODS_INVENTORY_STOCK", "ODS_INVENTORY_CHANGE",
+        "ODS_GOODS_CATEGORY", "ODS_STORE_GOODS", "ODS_STORE_GOODS_SALES", "ODS_TENANT_GOODS",
+        # DWD 层（1 个常用）
+        "DWD_LOAD_FROM_ODS",
+        # DWS 层（15 个常用，排除 DWS_MAINTENANCE）
+        "DWS_BUILD_ORDER_SUMMARY", "DWS_ASSISTANT_DAILY", "DWS_ASSISTANT_MONTHLY",
+        "DWS_ASSISTANT_CUSTOMER", "DWS_ASSISTANT_SALARY", "DWS_ASSISTANT_FINANCE",
+        "DWS_MEMBER_CONSUMPTION", "DWS_MEMBER_VISIT",
+        "DWS_FINANCE_DAILY", "DWS_FINANCE_RECHARGE", "DWS_FINANCE_INCOME_STRUCTURE",
+        "DWS_FINANCE_DISCOUNT_DETAIL",
+        "DWS_GOODS_STOCK_DAILY", "DWS_GOODS_STOCK_WEEKLY", "DWS_GOODS_STOCK_MONTHLY",
+        # INDEX 层（3 个常用，排除 DWS_ML_MANUAL_IMPORT）
+        "DWS_WINBACK_INDEX", "DWS_NEWCONV_INDEX", "DWS_RELATION_INDEX",
+    ],
+    # store_id 由后端从 JWT 注入（默认管理员 site_id=1）
+    # 注意：用户要求"全部门店"，但当前系统只有 site_id=1，后续多门店需逐个执行
+}
+```
+
+## 监控策略
+
+- 轮询间隔：30 秒
+- 最长等待：30 分钟（无新日志输出时）
+- 错误检测：日志行匹配 `ERROR`、`CRITICAL`、`Traceback`、`Exception`
+- 警告检测：日志行匹配 `WARNING`、`WARN`
+- 计时解析：从日志中提取时间戳，计算阶段耗时
+
+## 黑盒数据一致性测试
+
+### 两套检查工具的定位
+
+| 工具 | 路径 | 触发方式 | 覆盖范围 | 适用场景 |
+|------|------|---------|---------|---------|
+| 全链路检查器 | `scripts/ops/etl_consistency_check.py` | 手动运行 / `etl-data-consistency` Hook | API→ODS→DWD→DWS 四层全链路 | 联调后独立全面验证（本 Spec 主要使用） |
+| FlowRunner 内置检查 | `apps/etl/connectors/feiqiu/quality/consistency_checker.py` | FlowRunner 自动调用 `_run_post_consistency_check()` | API→ODS 字段 + ODS→DWD 映射/值 | ETL 执行后自动轻量检查 |
+
+联调场景下，FlowRunner 在 ETL 执行完成后已自动运行内置检查并输出报告到 `ETL_REPORT_ROOT`。联调脚本额外运行全链路检查器，覆盖 DWD→DWS 聚合验证和更深入的值采样比对。
+
+### etl-data-consistency Hook
+
+`.kiro/hooks/etl-data-consistency.kiro.hook` 提供手动触发入口，执行 `scripts/ops/etl_consistency_check.py`。联调任务 5 也可通过此 Hook 替代手动运行脚本。
+
+### 白名单机制
+
+全链路检查器在值比对时使用三层白名单过滤，避免 ETL 框架自动填充的列和已知等价差异产生误报：
+
+#### 1. ETL 元数据列白名单（`ETL_META_COLS`）
+
+不参与 API↔ODS 值比对的列：
+
+```python
+ETL_META_COLS = {"source_file", "source_endpoint", "fetched_at", "payload", "content_hash"}
+```
+
+这些列由 ETL 框架在 ODS 落库时自动填充，API 源数据中不存在。
+
+#### 2. SCD2 管理列白名单（`SCD2_COLS`）
+
+不参与 ODS↔DWD 值比对的列：
+
+```python
+SCD2_COLS = {
+    "valid_from", "valid_to", "is_current", "etl_loaded_at", "etl_batch_id",
+    "scd2_start_time", "scd2_end_time", "scd2_is_current", "scd2_version",
+}
+```
+
+这些列由 DWD 层 SCD2 逻辑自动维护，ODS 源数据中不存在。
+
+#### 3. 空字符串 vs None 等价规则（`_values_differ()`）
+
+API 返回空字符串 `""` 而数据库存储为 `None` 时，视为等价（不算差异），但标记为 `whitelist`：
+
+```python
+# API 空字符串 "" vs DB None → 白名单（等价但标记）
+if api_val is not None and ods_val is None:
+    if isinstance(api_val, str) and api_val.strip() == "":
+        return False, "whitelist"
+```
+
+报告中白名单差异以折叠 `<details>` 块展示，不计入失败统计。
+
+#### 4. FlowRunner 内置检查的白名单
+
+`consistency_checker.py` 使用类似但略有不同的白名单：
+- `ODS_META_COLUMNS`：与 `ETL_META_COLS` 相同，额外包含 `record_index`
+- `KNOWN_NO_SOURCE`：按表配置的已知无源字段（如 `dwd.dim_member.update_time`），标记为已知无源而非报错
+
+### 调用方式
+
+联调脚本在 ETL 全流程执行完成后，运行全链路检查器：
+
+```bash
+cd C:\NeoZQYY
+uv run python scripts/ops/etl_consistency_check.py
+```
+
+脚本自动完成：
+1. 从 `LOG_ROOT` 找到最近一次 ETL 日志，解析执行的任务列表
+2. 从 `FETCH_ROOT` 读取 API JSON 落盘文件
+3. 连接数据库（`PG_DSN`），逐表逐字段比对：
+   - API JSON vs ODS：字段完整性 + 值采样比对（随机 5 条）
+   - ODS vs DWD：行数 + 字段映射 + 值比对（含 EX 表合并）
+   - DWD vs DWS：聚合表行数 + 数值列健全性（NULL 率、负值、min/max）
+4. 输出 Markdown 报告到 `ETL_REPORT_ROOT`
+
+### 检查内容
+
+| 检查类型 | 对比对象 | 检查项 | 白名单处理 |
+|---------|---------|--------|-----------|
+| API vs ODS | API JSON 缓存 vs ODS 表 | 字段完整性 + 值采样比对（5 条记录） | `ETL_META_COLS` 排除；空字符串≡None |
+| ODS vs DWD | ODS 表 vs DWD 表（含 EX 表） | 行数对比 + 字段映射 + 值比对 | `SCD2_COLS` 排除；空字符串≡None |
+| DWD vs DWS | DWD 源表 vs DWS 聚合表 | 行数非空 + 数值列健全性（NULL 率、负值、min/max） | 无（DWS 为聚合结果，不做逐行值比对） |
+
+### 报告格式
+
+全链路检查器输出 Markdown 报告，包含：
+1. ETL 执行概览（任务列表、成功/失败/跳过统计）
+2. API↔ODS 数据一致性（逐表逐字段值比对，白名单差异折叠展示）
+3. ODS↔DWD 数据一致性（行数对比 + 映射验证 + 值采样，含字段级统计）
+4. DWD↔DWS 数据一致性（DWS 表概览 + 数值列健全性检查）
+5. 异常汇总与建议
+
+### 参考数据
+
+`dataflow-field-completion` 的实际执行结果：API vs ODS 22/22 通过，ODS vs DWD 38/42 通过。本次联调执行 api_full 全流程后，预期结果应与此一致或更优（因为联调包含最新的字段补全）。
+
+## 报告格式
+
+报告输出为 Markdown 文件，路径：`{SYSTEM_LOG_ROOT}/{date}__etl_integration_report.md`
+
+```markdown
+# ETL 全流程联调报告
+
+## 执行概要
+- 任务参数：...
+- 开始时间 / 结束时间 / 总时长
+- 退出码 / 最终状态
+
+## 性能报告
+- 各窗口切片耗时对比表
+- Top-5 耗时阶段
+- 总体吞吐量估算
+
+## 黑盒测试报告
+- API vs ODS：X/Y 张表通过（白名单差异 N 处）
+- ODS vs DWD：X/Y 张表通过（白名单差异 N 处）
+- DWD vs DWS：X 张表有数据 / Y 张总计，异常指标 N 个
+- 失败表清单及差异明细
+
+## DEBUG 报告（如有）
+- 错误摘要
+- 警告摘要
+- 相关日志片段
+- 可能的原因分析
+```
+
+## 正确性属性
+
+本 Spec 为运维联调任务，不涉及新功能代码开发，因此不定义形式化的属性测试。验证通过以下方式进行：
+- 服务健康检查通过
+- 任务提交成功并开始执行
+- 执行完成后退出码和日志符合预期
+- 黑盒数据一致性测试通过（全链路检查器覆盖 API→ODS→DWD→DWS 四层，白名单差异不计入失败）
+- 报告文件成功生成（含性能报告和黑盒测试报告）
+
+## 测试策略
+
+本 Spec 本身就是一次集成测试。不额外编写单元测试或属性测试。验证标准：
+- 后端 API 响应正确
+- ETL CLI 子进程正常启动和执行
+- 日志正确捕获和推送
+- 黑盒数据一致性测试通过（全链路检查器 API→ODS→DWD→DWS + FlowRunner 内置检查）
+- 报告文件正确生成到 ETL_REPORT_ROOT（全链路检查报告）和 SYSTEM_LOG_ROOT（联调综合报告）
+
+### 黑盒测试验证标准
+
+- API vs ODS：所有已采集的 ODS 表字段完整性和值采样检查通过（白名单差异不计入失败）
+- ODS vs DWD：所有已配置映射的表行数和值比对检查通过（SCD2 列排除，白名单差异不计入失败）
+- DWD vs DWS：所有 DWS 聚合表行数非空，数值列无异常（高 NULL 率、金额负值等）
+- 全链路检查报告 `consistency_check_<timestamp>.md` 成功生成到 ETL_REPORT_ROOT
+- 综合联调报告中包含黑盒测试结果摘要（含白名单差异统计）
--- a/.kiro/specs/[ETL]-fullstack-integration/requirements.md
+++ b/.kiro/specs/[ETL]-fullstack-integration/requirements.md
@@ -0,0 +1,85 @@
+# 需求文档：ETL 全流程前后端联调（etl-fullstack-integration）
+
+## 简介
+
+基于已完成的 `admin-web-console` Spec 产出的前后端代码，进行一次完整的端到端联调验证。通过管理后台 API 提交 ETL 全流程任务（api_full），覆盖 ODS → DWD → DWS → INDEX 全链路，验证前后端协作、子进程执行、日志推送、错误处理等环节的正确性。同时收集精细计时数据，定位性能瓶颈。
+
+## 术语表
+
+- **联调**：将 admin-web 后端 API 与 feiqiu ETL CLI 串联，通过真实 API 调用触发 ETL 全流程执行
+- **全选常用任务**：任务注册表中 `is_common=True` 的所有任务（排除工具类、手动导入、维护类等 `is_common=False` 的任务）
+- **精细计时**：在 ETL 执行过程中，通过日志解析或 CLI 输出，记录每个阶段（ODS/DWD/DWS/INDEX）和每个子任务的耗时
+
+## 需求
+
+### 需求 1：服务启动与健康检查
+
+**用户故事：** 作为开发者，我希望一键启动后端和前端服务，并确认服务健康可用，以便开始联调。
+
+#### 验收标准
+
+1. WHEN 启动后端服务, THE Backend_API SHALL 在 `http://localhost:8000` 上响应请求
+2. WHEN 启动前端服务, THE Admin_Web SHALL 在 `http://localhost:5173` 上可访问
+3. WHEN 调用 `POST /api/auth/login`, THE Backend_API SHALL 返回有效的 JWT 令牌
+4. WHEN 调用 `GET /api/tasks/registry`, THE Backend_API SHALL 返回非空的任务注册表
+5. WHEN 调用 `GET /api/tasks/sync-check`, THE Backend_API SHALL 确认后端任务注册表与 ETL 真实注册表同步
+
+### 需求 2：全流程任务提交与执行
+
+**用户故事：** 作为开发者，我希望通过后端 API 提交一个覆盖全链路的 ETL 任务，验证任务配置、CLI 构建、子进程执行的完整流程。
+
+#### 验收标准
+
+1. WHEN 提交 TaskConfig（api_full + full_window + 全选常用任务 + 自定义窗口 2025-11-01~2026-02-20 + 30天切分 + force-full）, THE Backend_API SHALL 验证配置有效并返回 CLI 命令预览
+2. WHEN 提交任务到执行队列, THE Backend_API SHALL 创建队列任务并自动开始执行
+3. WHILE ETL 子进程运行中, THE Backend_API SHALL 通过 WebSocket 推送实时日志
+4. WHEN ETL 子进程完成, THE Backend_API SHALL 记录退出码、执行时长、完整日志到 task_execution_log
+
+### 需求 3：执行监控与错误处理
+
+**用户故事：** 作为开发者，我希望在任务执行过程中实时监控状态，对报错或警告及时发现并进行 DEBUG。
+
+#### 验收标准
+
+1. WHILE 任务执行中, THE 监控脚本 SHALL 每 30 秒轮询执行状态和日志
+2. WHEN 日志中出现 ERROR 或 WARNING 级别信息, THE 监控脚本 SHALL 立即记录并标记
+3. WHEN 任务执行完成（成功或失败）, THE 监控脚本 SHALL 停止轮询并收集最终状态
+4. IF 任务执行超过 30 分钟无新日志输出, THEN THE 监控脚本 SHALL 报告超时警告
+5. IF 任务执行失败, THEN THE 监控脚本 SHALL 收集完整的 stderr 和错误上下文
+
+### 需求 4：性能计时与瓶颈分析
+
+**用户故事：** 作为开发者，我希望获得精细粒度的执行计时数据，以便发现性能瓶颈。
+
+#### 验收标准
+
+1. WHEN 任务执行完成, THE 报告 SHALL 包含总执行时长
+2. WHEN 日志中包含阶段性时间戳, THE 报告 SHALL 解析并展示每个窗口切片的耗时
+3. THE 报告 SHALL 标注耗时最长的 Top-5 阶段/任务
+4. THE 报告 SHALL 包含每个窗口切片（30天）的独立耗时对比
+
+### 需求 5：黑盒数据一致性测试
+
+**用户故事：** 作为开发者，我希望在 ETL 全流程执行完成后，以黑盒视角对比数据上下游的字段差异和值差异，验证数据从 API 到 ODS 再到 DWD 再到 DWS 的完整性和正确性。
+
+#### 验收标准
+
+1. WHEN ETL 全流程执行完成后, THE 联调脚本 SHALL 运行全链路检查器 `scripts/ops/etl_consistency_check.py`，执行 API→ODS→DWD→DWS 四层数据一致性检查
+2. WHEN 执行 API vs ODS 检查时, THE 检查器 SHALL 对比 API JSON 落盘数据与 ODS 落库数据的字段完整性和值采样（随机 5 条记录的关键字段），覆盖所有已采集的 ODS 表
+3. WHEN 执行 ODS vs DWD 检查时, THE 检查器 SHALL 对比 ODS 数据与 DWD 落库数据的行数、字段映射正确性和值一致性（含 EX 表合并比对）
+4. WHEN 执行 DWD vs DWS 检查时, THE 检查器 SHALL 验证 DWS 聚合表的行数非空、数值列健全性（NULL 率、负值、min/max），标注异常指标
+5. WHEN 值比对遇到白名单场景时, THE 检查器 SHALL 将 ETL 元数据列（`source_file`、`source_endpoint`、`fetched_at`、`payload`、`content_hash`）和 SCD2 管理列排除在值比对之外，并将 API 空字符串 `""` vs DB `None` 视为等价（标记为 whitelist）
+6. WHEN 黑盒测试完成后, THE 检查器 SHALL 输出 Markdown 报告到 `ETL_REPORT_ROOT` 环境变量指定的目录
+7. WHEN 黑盒测试报告生成后, THE 报告 SHALL 包含每张表的检查结果、差异明细（含白名单差异折叠展示）、通过/失败状态、字段级统计、以及汇总统计
+
+### 需求 6：联调报告输出
+
+**用户故事：** 作为开发者，我希望联调完成后获得一份综合报告，包含执行情况、性能数据、黑盒测试结果和可能的 DEBUG 信息。
+
+#### 验收标准
+
+1. THE 报告 SHALL 包含：执行概要（任务参数、开始/结束时间、总时长、退出码）
+2. THE 报告 SHALL 包含：性能报告（各阶段耗时、窗口切片耗时对比、Top-5 瓶颈）
+3. THE 报告 SHALL 包含：黑盒测试结果摘要（API vs ODS 通过数/总数、ODS vs DWD 通过数/总数、DWD vs DWS 表概览、失败表清单、白名单差异数量）
+4. IF 执行过程中出现错误或警告, THEN THE 报告 SHALL 包含 DEBUG 报告（错误摘要、相关日志片段、可能的原因分析）
+5. THE 报告 SHALL 输出到 `SYSTEM_LOG_ROOT` 环境变量指定的目录
--- a/.kiro/specs/[ETL]-fullstack-integration/tasks.md
+++ b/.kiro/specs/[ETL]-fullstack-integration/tasks.md
@@ -0,0 +1,131 @@
+# 实现计划：ETL 全流程前后端联调（etl-fullstack-integration）
+
+## 概述
+
+基于 `admin-web-console` 已完成的前后端代码，进行端到端联调验证。全程使用 Playwright 浏览器模拟真实用户操作（登录、配置、提交、监控），不直接调用 API。通过管理后台 UI 提交 api_full 全流程 ETL 任务（自定义窗口 2025-11-01~2026-02-20，30天切分，force-full，全选常用任务），实时监控执行过程，收集性能数据，执行黑盒数据一致性测试（全链路检查器 `scripts/ops/etl_consistency_check.py` + FlowRunner 内置 `ConsistencyChecker`），最终生成综合报告。
+
+## 任务
+
+- [x] 1. 服务启动与健康检查
+  - [x] 1.1 启动后端服务（`apps/backend/`，uvicorn :8000），确认 API 可达
+    - 使用 `controlPwshProcess` 启动 `uvicorn app.main:app --host 0.0.0.0 --port 8000`，cwd 为 `apps/backend/`
+    - 等待服务就绪，验证 `http://localhost:8000/docs` 可访问
+    - _Requirements: 1.1_
+
+  - [x] 1.2 启动前端服务（`apps/admin-web/`，pnpm dev :5173），确认页面可访问
+    - 使用 `controlPwshProcess` 启动 `pnpm dev`，cwd 为 `apps/admin-web/`
+    - 等待 Vite 就绪，验证 `http://localhost:5173` 可访问
+    - _Requirements: 1.2_
+
+  - [x] 1.3 浏览器登录与健康检查
+    - 使用 Playwright 打开 `http://localhost:5173`，应自动跳转到 `/login`
+    - 在登录表单中输入用户名 `admin`、密码 `admin123`，点击登录按钮
+    - 验证登录成功后跳转到任务配置页面（`/`）
+    - 确认侧边栏导航菜单正常渲染（任务配置、任务管理、ETL 状态、数据库、日志、环境配置、运维面板）
+    - _Requirements: 1.3, 1.4, 1.5_
+
+- [x] 2. 浏览器操作：任务配置与提交
+  - [x] 2.1 在任务配置页面填写全流程参数
+    - 在任务配置页面（`/`），选择 Flow 为 `api_full`（API → ODS → DWD → DWS → INDEX）
+    - 选择处理模式为 `full_window`（全窗口）
+    - 设置时间窗口模式为"自定义"，填入开始时间 `2025-11-01`、结束时间 `2026-02-20`
+    - 设置窗口切分为"按天"，切分天数为 `30`
+    - 勾选 `force_full`（强制全量）
+    - 在任务选择区域，全选 `is_common=True` 的常用任务（共 41 个）
+    - 确认 CLI 命令预览区域显示完整参数（--flow api_full --processing-mode full_window --window-start ... --window-end ... --window-split day --window-split-days 30 --force-full --tasks ...）
+    - _Requirements: 2.1_
+
+  - [x] 2.2 通过浏览器提交任务执行
+    - 点击"直接执行"按钮（SendOutlined 图标），触发 `POST /api/execution/run`
+    - 确认页面显示任务提交成功的提示消息
+    - 记录返回的 execution_id（从页面响应或跳转中获取）
+    - _Requirements: 2.2, 2.4_
+
+- [ ] 3. 浏览器操作：执行监控与 DEBUG
+  - [x] 3.1 在任务管理页面监控执行状态
+    - 导航到"任务管理"页面（`/task-manager`），点击侧边栏"任务管理"菜单
+    - 在"队列"Tab 中确认刚提交的任务状态为 `running`
+    - 点击 running 状态的任务行，打开 WebSocket 实时日志流抽屉
+    - 持续观察日志输出，每 30 秒检查一次页面状态
+    - 检测日志中的 ERROR / CRITICAL / Traceback / Exception / WARNING 关键字
+    - 如果连续 30 分钟无新日志输出，报告超时警告
+    - 任务完成（success/failed/cancelled）时停止监控
+    - _Requirements: 3.1, 3.2, 3.3, 3.4, 3.5_
+
+  - [ ] 3.2 对执行过程中发现的错误/警告进行 DEBUG 分析
+    - 从日志流中收集所有 ERROR 和 WARNING 日志行及其上下文
+    - 分析错误类型：API 超时、数据库连接、数据质量、配置问题等
+    - 如果任务失败，切换到"历史"Tab 查看完整执行详情和日志
+    - 记录 DEBUG 发现到报告中
+    - _Requirements: 3.2, 3.5_
+
+- [ ] 4. 性能计时与报告生成
+  - [ ] 4.1 从浏览器获取执行日志，提取精细计时数据
+    - 在"任务管理"→"历史"Tab 中，点击已完成的任务查看执行详情
+    - 通过 `GET /api/execution/{id}/logs` 获取完整日志（可通过浏览器或 API 辅助）
+    - 从日志中提取每个窗口切片（30天）的开始/结束时间
+    - 计算每个切片的耗时
+    - 识别 ODS / DWD / DWS / INDEX 各阶段的耗时
+    - 标注 Top-5 耗时最长的阶段/任务
+    - _Requirements: 4.1, 4.2, 4.3, 4.4_
+
+  - [ ] 4.2 生成综合联调报告，输出到 SYSTEM_LOG_ROOT
+    - 报告包含：执行概要（参数、时间、退出码）
+    - 报告包含：性能报告（各切片耗时对比、Top-5 瓶颈）
+    - 报告包含：DEBUG 报告（如有错误/警告）
+    - 黑盒测试结果摘要将在任务 5.3 中追加
+    - 输出路径：`{SYSTEM_LOG_ROOT}/{date}__etl_integration_report.md`
+    - 路径通过 `SYSTEM_LOG_ROOT` 环境变量获取，缺失时报错
+    - _Requirements: 6.1, 6.2, 6.4, 6.5_
+
+- [ ] 5. 黑盒数据一致性测试
+  - [ ] 5.1 运行全链路检查器，执行 API→ODS→DWD→DWS 四层数据一致性检查
+    - 运行 `uv run python scripts/ops/etl_consistency_check.py`（cwd 为项目根目录 `C:\NeoZQYY`）
+    - 脚本自动从 `LOG_ROOT` 找到最近一次 ETL 日志，解析本次执行的任务列表
+    - 脚本自动从 `FETCH_ROOT` 读取 API JSON 落盘文件
+    - 脚本连接数据库（`PG_DSN`），逐表逐字段比对：
+      - API JSON vs ODS：字段完整性 + 值采样比对（随机 5 条记录），`ETL_META_COLS` 白名单列排除
+      - ODS vs DWD：行数对比 + 字段映射 + 值比对（含 EX 表合并），`SCD2_COLS` 白名单列排除
+      - DWD vs DWS：聚合表行数非空检查 + 数值列健全性（NULL 率、负值、min/max）
+    - 白名单处理：API 空字符串 `""` vs DB `None` 视为等价，标记为 whitelist，不计入失败
+    - 报告自动输出到 `ETL_REPORT_ROOT`（环境变量，缺失时报错）
+    - 备选触发方式：可通过 `etl-data-consistency` Hook 手动触发（效果等同）
+    - _Requirements: 5.1, 5.2, 5.3, 5.4, 5.5_
+
+  - [ ] 5.2 检查 FlowRunner 内置一致性报告
+    - FlowRunner 在 ETL 执行完成后已自动调用 `_run_post_consistency_check()` 生成报告到 `ETL_REPORT_ROOT`
+    - 确认内置报告已生成，检查 API vs ODS 和 ODS vs DWD 的通过/失败统计
+    - 内置检查使用 `ODS_META_COLUMNS` 白名单（含 `record_index`）和 `KNOWN_NO_SOURCE` 按表白名单
+    - 对比两份报告的结论是否一致（全链路检查器 vs FlowRunner 内置检查）
+    - _Requirements: 5.1, 5.2, 5.3_
+
+  - [ ] 5.3 将黑盒测试结果摘要写入综合联调报告
+    - 在任务 4.2 生成的联调报告中追加"黑盒测试报告"章节
+    - 包含：API vs ODS 通过数/总数、ODS vs DWD 通过数/总数、DWD vs DWS 表概览
+    - 包含：白名单差异数量统计、失败表清单
+    - 引用全链路检查报告的完整路径
+    - _Requirements: 6.3_
+
+- [ ] 6. 服务清理
+  - [ ] 6.1 关闭浏览器，停止后端和前端服务，清理资源
+    - 关闭 Playwright 浏览器实例
+    - 停止 uvicorn 后端进程（`controlPwshProcess` stop）
+    - 停止 pnpm dev 前端进程（`controlPwshProcess` stop）
+    - 报告联调完成状态
+
+## 说明
+
+- 本 Spec 为运维联调任务，不涉及新功能代码开发
+- 不编写属性测试或单元测试，联调本身即为集成验证
+- **全程使用 Playwright 浏览器模拟真实用户操作**：登录、页面导航、表单填写、按钮点击、日志查看等均通过浏览器完成
+- **黑盒测试使用两套工具**：
+  - 全链路检查器 `scripts/ops/etl_consistency_check.py`：覆盖 API→ODS→DWD→DWS 四层，联调主要使用
+  - FlowRunner 内置 `ConsistencyChecker`（`quality/consistency_checker.py`）：ETL 执行后自动运行，覆盖 API→ODS + ODS→DWD
+- **白名单机制**：`ETL_META_COLS`（ODS 元数据列）、`SCD2_COLS`（SCD2 管理列）排除在值比对之外；API 空字符串 `""` vs DB `None` 视为等价
+- **`etl-data-consistency` Hook**（`.kiro/hooks/etl-data-consistency.kiro.hook`）可作为手动触发全链路检查的替代方式
+- 黑盒测试在 ETL 全流程执行完成后、服务清理前执行，确保数据库中有最新数据可供对比
+- 全选常用任务 = 任务注册表中 `is_common=True` 的所有任务（共 41 个）
+- "全部门店"：当前系统仅有 site_id=1（默认管理员绑定），如需多门店需逐个执行
+- 监控允许空闲等待，最长 30 分钟无新日志才报超时
+- 报告输出路径遵循 export-paths 规范：全链路检查报告输出到 `ETL_REPORT_ROOT`，联调综合报告输出到 `SYSTEM_LOG_ROOT`
+- 全链路检查器需要 `PG_DSN`、`FETCH_ROOT`、`LOG_ROOT`、`ETL_REPORT_ROOT` 环境变量，缺失时报错