Neo-ZQYY/docs/audit/changes/2026-02-15__admin-web-console-db-migration-audit-reorg.md

审计记录：管理后台全量实现 + DB Schema 迁移 + 审计产物重组

• 日期：2026-02-15（Asia/Shanghai）
• Prompt-ID：P20260215-232501（及前序 ~50 个 prompt 的累积变更）
• 类型：多主题大型变更（新功能 + 数据库迁移 + 仓库治理）
• 风险等级：高

变更概述

本次未提交变更涵盖三大主题，共 241 个文件（+2713/-8186 行）：

1. admin-web-console spec 全量实现：FastAPI 后端 API + React 前端管理后台
2. DB Schema 引用迁移：全项目 450+ 处旧 schema 名替换 + 数据迁移到新库
3. 审计产物重组 + .kiro 清理：审计落地点统一到 docs/audit/，清理旧 specs/脚本

---

主题 1：admin-web-console（新功能，高风险）

后端 API（apps/backend/app/）

文件/目录	变更类型	说明
app/main.py	修改	注册所有路由、CORS、WebSocket
app/config.py	修改	数据库连接配置更新
app/database.py	修改	连接池管理
app/auth/	新建	JWT 鉴权模块（依赖项、JWT 工具）
app/routers/auth.py	新建	登录/注册/刷新 token
app/routers/tasks.py	新建	任务配置 CRUD
app/routers/execution.py	新建	任务执行（CLI 构建 + 子进程）
app/routers/schedules.py	新建	调度管理
app/routers/env_config.py	新建	环境变量配置
app/routers/db_viewer.py	新建	数据库查看器
app/routers/etl_status.py	新建	ETL 运行状态
app/schemas/	新建	Pydantic 请求/响应模型（6 个文件）
app/services/	新建	业务逻辑层
app/ws/	新建	WebSocket 日志推送
pyproject.toml	修改	补全 fastapi/uvicorn 等运行依赖
tests/	新建	20+ 测试文件（含 hypothesis 属性测试）

风险点：

• 鉴权模块（JWT）为新建，需验证 token 过期/刷新/权限隔离逻辑
• 任务执行路由直接调用子进程运行 CLI，需关注命令注入防护
• DB 查看器允许执行 SQL 查询，需确认只读权限约束

前端（apps/admin-web/）

文件/目录	变更类型	说明
index.html	新建	Vite 入口
package.json	新建	React + Vite + TypeScript
src/	新建	6 个页面（TaskConfig/TaskManager/EnvConfig/DBViewer/ETLStatus/LogViewer）+ 组件 + API 客户端 + 路由
vite.config.ts	新建	Vite 配置（代理后端 API）

---

主题 2：DB Schema 引用迁移（高风险）

迁移规则

• billiards_ods → ods
• billiards_dwd → dwd
• billiards_dws → dws
• etl_admin → meta
• 数据库名：LLZQ-test → etl_feiqiu / zqyy_app

受影响的高风险路径

路径	变更数	说明
apps/etl/pipelines/feiqiu/tasks/	~30 文件	ODS/DWD/DWS/utility/verification 任务中的 SQL schema 前缀
apps/etl/pipelines/feiqiu/orchestration/	6 文件	cursor_manager/pipeline_runner/run_tracker/scheduler/task_executor/task_registry
apps/etl/pipelines/feiqiu/quality/	1 文件	integrity_checker SQL
apps/etl/pipelines/feiqiu/config/	1 文件	defaults.py schema 配置
apps/etl/pipelines/feiqiu/cli/	1 文件	main.py
apps/etl/pipelines/feiqiu/utils/	1 文件	reporting.py
apps/etl/pipelines/feiqiu/scripts/	~15 文件	各类运维/检查/导出脚本
gui/	~10 文件	桌面 GUI 中的 SQL 查询和 schema 引用
db/	8 文件	DDL/种子/FDW 配置
apps/backend/	2 文件	.env.local + etl_status 路由

DB 结构变更

文件	变更类型	说明
db/etl_feiqiu/schemas/app.sql	修改	app schema DDL 更新
db/etl_feiqiu/seeds/seed_dws_config.sql	修改	schema 引用更新
db/etl_feiqiu/seeds/seed_index_parameters.sql	修改	schema 引用更新
db/etl_feiqiu/seeds/seed_ods_tasks.sql	修改	schema 引用更新
db/etl_feiqiu/seeds/seed_scheduler_tasks.sql	修改	schema 引用更新
db/fdw/setup_fdw.sql	修改	FDW 映射配置更新
db/fdw/setup_fdw_test.sql	新建	测试环境 FDW 配置
db/zqyy_app/schemas/init.sql	修改	业务库 schema 更新
db/zqyy_app/migrations/20250715_create_admin_web_tables.sql	新建	管理后台所需表
db/zqyy_app/seeds/admin_web_seed.sql	新建	管理后台种子数据

风险点：

• 450+ 处 schema 名替换，任何遗漏都会导致运行时 SQL 错误
• 数据已从旧库迁移到新库，需确认行数一致性
• FDW 映射需在两个库都正确配置

---

主题 3：审计产物重组 + .kiro 清理

审计产物迁移

• 从 apps/etl/pipelines/feiqiu/docs/audit/ 删除全部旧审计记录（27 条 changes + 40+ prompt_logs + dashboard）
• 在 docs/audit/ 重建（已有 29 条 changes + 68 条 prompt_logs）
• scripts/audit/gen_audit_dashboard.py 新建（项目级审计一览表生成器）

.kiro 清理

• 删除 6 个旧 specs（bd-manual-docs-consolidation/docs-optimization/etl-task-documentation/monorepo-migration/repo-audit/scheduler-refactor）
• 删除 3 个 PowerShell 脚本（audit_flagger.ps1/audit_reminder.ps1/prompt_audit_log.ps1），替换为 Python 版本
• 删除 2 个旧 hooks（change-impact-review/db-schema-doc-enforcer）
• 新增 admin-web-console spec
• 新增 MCP 配置（.kiro/settings/mcp.json）

根目录散文件

• .env.template：大幅扩展（+266 行），覆盖后端/管理后台配置
• .gitignore：更新排除规则
• NeoZQYY.code-workspace：更新工作区配置
• README.md：更新项目说明
• uv.lock：依赖锁文件更新（+1090 行）

---

回滚要点

1. 后端 API：删除 apps/backend/app/auth/、app/routers/、app/schemas/、app/services/、app/ws/，恢复 main.py/config.py/database.py
2. 前端：删除 apps/admin-web/ 全部新建文件
3. Schema 迁移：使用 git checkout HEAD -- <file> 恢复所有 450+ 处替换；数据库层面需手动回滚（数据已在新库）
4. DB 新表：回滚 db/zqyy_app/migrations/20250715_create_admin_web_tables.sql

验证建议

# 后端测试
cd apps/backend && uv run python -m pytest tests/ -v

# ETL 单元测试（验证 schema 迁移无回归）
cd apps/etl/pipelines/feiqiu && pytest tests/unit

# 前端测试
cd apps/admin-web && pnpm exec vitest run

# 前端类型检查
cd apps/admin-web && pnpm exec tsc --noEmit

# 属性测试
cd C:\NeoZQYY && pytest tests/ -v

内联注释决策

• AI_CHANGELOG：不添加。变更文件数量过多（241 个），逐文件添加会产生大量噪音。本审计记录已按主题分类覆盖全部高风险路径。
• CHANGE 注释：不添加。Schema 迁移为机械替换（无业务逻辑变更）；后端/前端为全新代码（无"修改"语义）。