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`

## 验证建议

```bash
# 后端测试
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 迁移为机械替换（无业务逻辑变更）；后端/前端为全新代码（无"修改"语义）。