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
• 仓库清理：已删除文件为历史样本数据和废弃脚本，无需回滚