Neo-ZQYY/docs/audit/changes/2026-03-04__fullstack-accumulated-changes.md

# 变更审计记录：全栈累积变更（营业日配置、WebSocket 日志、微信认证、仓库清理）

| 字段 | 值 |
|------|-----|
| 日期 | 2026-03-05 00:04:01 |
| Prompt-ID | P20260304-232912 |
| Session-ID | 0b65aa43 |
| Session 路径 | docs/audit/session_logs/2026-03/04/52_0b65aa43_232320 |
| 风险标签 | `root-file` `dir:admin-web` `dir:backend` `dir:etl` `dir:miniprogram` `dir:db` `db-schema-change` `dir:shared` |
| 变更规模 | 273 文件，+10,505 / -219,431 行 |

## 操作摘要

本次审计覆盖多轮对话的累积变更，核心工作包括：

1. **管理后台（admin-web）**：新增营业日配置全局状态（Zustand store + API + BusinessDayHint 提示组件）；TaskManager 历史标签页增加 WebSocket 实时日志推送和任务终止按钮
2. **后端（backend）**：配置化 ETL Python 路径、运维面板根目录、微信小程序凭证、营业日分割点；新增/重构 xcx_auth 认证路由和 schemas
3. **ETL（feiqiu）**：config 模块新增 BUSINESS_DAY_START_HOUR 支持；consistency_checker 大幅重构；flow_runner 调整
4. **共享包（shared）**：新增 `datetime_utils` 模块（营业日计算工具）
5. **数据库（db）**：FDW 反向映射更新；DDL 基线同步更新（dwd/dws/ods/auth/public 多 schema）
6. **仓库清理**：删除 `tmp/api_samples/`（~200K 行）、废弃 `field_mappings_new/`、旧运维脚本、旧 `.kiro/` hooks 和 specs

## 本次对话文件变更

### 新增文件
- `docs/audit/prompt_logs/prompt_log_20260304_232912.md` — Prompt 审计日志
- `docs/audit/session_logs/2026-03/04/52_0b65aa43_232320/main_01_389bf343.md` — Session 日志（主）
- `docs/audit/session_logs/2026-03/04/52_0b65aa43_232320/sub_01_389bf343.md` — Session 日志（子代理）
- `docs/audit/session_logs/2026-03/04/53_34248647_232911/main_01_a6834276.md` — Session 日志

### 修改文件
- `docs/DOCUMENTATION-MAP.md` — 文档地图更新
- `docs/audit/README.md` — 审计说明更新
- `docs/audit/SESSION-LOG-GUIDE.md` — Session 日志指南更新
- `docs/audit/session_logs/_session_index.json` — 会话索引更新
- 多个 `_day_index.json` / `_day_index_full.json` — 日索引批量更新


## 改动注解

### `apps/admin-web/src/App.tsx`
- 变更类型：修改
- 原始原因：管理后台启动时需加载营业日配置，供全局日期组件使用
- 思路分析：在 App 组件 useEffect 中调用 `useBusinessDayStore.init()`，与 hydrate 同步执行。降级策略封装在 store 内部，App 层无需处理异常
- 修改结果：应用启动时自动请求 `/api/config/business-day`，失败时降级为默认值 8

### `apps/admin-web/src/api/businessDay.ts`
- 变更类型：新增
- 原始原因：前端需要从后端获取营业日分割点配置
- 思路分析：封装单一 GET 请求，返回 `BusinessDayConfig` 接口（含 `business_day_start_hour` 字段），复用 `apiClient` 实例
- 修改结果：提供 `fetchBusinessDayConfig()` API 函数

### `apps/admin-web/src/components/BusinessDayHint.tsx`
- 变更类型：新增
- 原始原因：用户在日期选择器旁需要了解当前营业日口径（分割点时间）
- 思路分析：使用 Tooltip + Typography.Text 组合，从 businessDayStore 读取 startHour，格式化为 `HH:00` 显示
- 修改结果：在 TaskConfig 日期选择区域下方显示「营业日：08:00 起」提示

### `apps/admin-web/src/pages/TaskConfig.tsx`
- 变更类型：修改
- 原始原因：日期范围选择区域需要展示营业日口径提示
- 思路分析：在日期选择 Row 下方插入 BusinessDayHint 组件，用 Fragment 包裹避免多余 DOM 节点
- 修改结果：日期选择器下方显示营业日分割点提示

### `apps/admin-web/src/pages/TaskManager.tsx`
- 变更类型：修改
- 原始原因：历史任务查看需要实时日志推送（running 状态）和任务终止能力
- 思路分析：为 HistoryTab 新增 WebSocket 连接管理（`historyWsRef`），running 任务点击时建立 `ws://host/ws/logs/{id}` 连接实时推送日志，已完成任务仍走 REST API。新增终止按钮（Popconfirm 确认）调用 `cancelExecution`。Drawer 标题显示连接状态标签。WebSocket 失败时自动回退到 REST API
- 修改结果：HistoryTab 支持实时日志流、连接状态指示、任务终止操作

### `apps/admin-web/src/store/businessDayStore.ts`
- 变更类型：新增
- 原始原因：营业日分割点配置需要全局共享，多个页面组件依赖
- 思路分析：Zustand store，启动时请求一次后端配置，API 不可用时降级为默认值 8 并 console.warn。`loaded` 标志防止重复请求
- 修改结果：提供 `useBusinessDayStore`，含 `startHour`、`loaded`、`init()` 三个成员

### `apps/backend/app/config.py`
- 变更类型：修改
- 原始原因：多个硬编码配置需要环境变量化（ETL Python 路径、运维面板根目录、微信凭证、营业日分割点）
- 思路分析：统一使用 `os.environ.get()` 读取，提供合理默认值。`WX_DEV_MODE` 支持 true/1/yes 三种写法。`BUSINESS_DAY_START_HOUR` 转 int
- 修改结果：新增 `ETL_PYTHON_EXECUTABLE`、`OPS_SERVER_BASE`、`WX_APPID`、`WX_SECRET`、`WX_DEV_MODE`、`BUSINESS_DAY_START_HOUR` 六个配置项

### `apps/backend/app/main.py`
- 变更类型：修改
- 原始原因：新增路由模块需要注册到 FastAPI 应用
- 思路分析：按模块分组 import 并 include_router，保持路由注册的清晰分层
- 修改结果：注册 business_day、xcx_auth 等新路由

### `apps/backend/app/routers/xcx_auth.py`
- 变更类型：修改（大幅重构，+352/-352）
- 原始原因：微信小程序认证流程需要完善，支持 code2Session、token 签发、用户注册等完整链路
- 思路分析：重构为完整的微信认证路由，包含 login、register、refresh 等端点
- 修改结果：完整的微信小程序认证 API

### `apps/backend/app/schemas/xcx_auth.py`
- 变更类型：新增
- 原始原因：xcx_auth 路由需要请求/响应 Schema 定义
- 思路分析：Pydantic v2 模型，定义 login request/response、register request、token refresh 等数据结构
- 修改结果：提供微信认证相关的全部 Schema

### `apps/etl/connectors/feiqiu/config/settings.py`
- 变更类型：修改
- 原始原因：ETL 配置需要支持营业日分割点参数
- 思路分析：在 AppConfig 中新增 BUSINESS_DAY_START_HOUR 字段，从环境变量读取
- 修改结果：ETL 配置类支持营业日分割点

### `apps/etl/connectors/feiqiu/orchestration/flow_runner.py`
- 变更类型：修改
- 原始原因：流程编排器需要适配新的配置和执行逻辑
- 思路分析：调整 flow_runner 的参数传递和执行流程
- 修改结果：flow_runner 适配新配置

### `apps/etl/connectors/feiqiu/quality/consistency_checker.py`
- 变更类型：修改（+136/-136，大幅重构）
- 原始原因：一致性检查器需要更精确的比对逻辑和更清晰的报告输出
- 思路分析：重构检查逻辑，改进 API↔ODS、ODS↔DWD 的字段比对算法
- 修改结果：一致性检查器输出更准确、报告更结构化

### `packages/shared/src/neozqyy_shared/datetime_utils.py`
- 变更类型：新增
- 原始原因：营业日计算逻辑需要跨模块共享（ETL 和后端都需要）
- 思路分析：放入 shared 包，提供营业日边界计算、日期转换等工具函数
- 修改结果：新增 92 行的 datetime_utils 模块，供 ETL 和后端共同使用

### `db/fdw/setup_fdw_reverse.sql` / `db/fdw/setup_fdw_reverse_test.sql`
- 变更类型：修改
- 原始原因：FDW 反向映射需要同步最新的表结构变更
- 思路分析：更新 IMPORT FOREIGN SCHEMA 和 CREATE FOREIGN TABLE 语句
- 修改结果：FDW 映射与当前数据库结构一致

### 非高风险文件简要注解
- `.env` / `.env.template` / `.gitignore`：新增微信凭证、营业日配置、ETL Python 路径等环境变量
- `apps/admin-web/README.md` / `apps/backend/README.md` / `apps/miniprogram/README.md` / `packages/shared/README.md`：文档同步更新
- `apps/backend/docs/API-REFERENCE.md`：接口文档更新
- `apps/etl/connectors/feiqiu/docs/etl_tasks/*.md`：ETL 任务文档更新
- `docs/database/ddl/*.sql`：DDL 基线同步
- `docs/contracts/openapi/backend-api.json`：OpenAPI spec 更新（+5096 行）
- `docs/DOCUMENTATION-MAP.md`：文档地图更新
- 大量 `tmp/api_samples/` 和 `field_mappings_new/` 文件删除：仓库清理

## 合规检查

| 检查项 | 状态 | 说明 |
|--------|------|------|
| 文档同步 | ✅ 已同步 | `code_without_docs` 为空，各模块 README 已更新 |
| 新增迁移 SQL | ⚪ 不涉及 | `new_migration_sql` 为空 |
| DDL 基线 | ⚠️ 待确认 | `has_ddl_baseline: false`，DDL 基线文件已有变更但标记未更新 |
| OpenAPI Spec | ✅ 已同步 | `api_changed: false`，`openapi_spec_stale: false` |
| BD 手册 | ⚠️ 待补充 | `has_bd_manual: false`，reasons 含 `db-schema-change` 但 BD 手册未同步 |

## 回滚方案

- 营业日功能：删除 businessDayStore、BusinessDayHint、businessDay API，移除 config.py 中 BUSINESS_DAY_START_HOUR，移除 shared/datetime_utils.py
- WebSocket 日志：回退 TaskManager.tsx 到 REST-only 版本
- 微信认证：回退 xcx_auth.py 和对应 schemas
- 仓库清理：已删除文件为历史样本数据和废弃脚本，无需回滚