Neo-ZQYY/docs/audit/changes/2026-04-06__v1-cleanup-ddl-consolidation.md

# 变更审计记录：v1 历史清理与 DDL 合并归档

| 字段 | 值 |
|------|-----|
| 日期 | 2026-04-06 01:02:42 |

## 操作摘要

项目 v1 阶段收尾整理，分三个 commit（779b2f6、4ab8822、82c321e）完成：

1. **历史文件清理**：git rm 确认删除 1155 个已从工作树移除的废弃文件（Kiro prompt_logs 588 个、tmp 临时文件 309 个、旧 ops 脚本 243 个、旧迁移工具 6 个、根级文件 6 个）；export/ 下 114 个报表导出产物从 git 移除跟踪（已在 .gitignore）。
2. **DDL 合并**：将 `docs/database/ddl/`（gen_consolidated_ddl.py 从测试库导出）的 9 个完整 schema DDL 填充到 `db/etl_feiqiu/schemas/` 和 `db/zqyy_app/schemas/`，作为 v1 权威 DDL 基线。
3. **迁移脚本归档**：39 个 v1 迁移脚本（etl_feiqiu 11 个 + zqyy_app 28 个）git mv 到 `db/_archived/migrations_v1_merged/`，migrations/ 目录保留 .gitkeep 供未来增量使用。
4. **BD_Manual 文档归档**：4 个迁移变更类 BD_Manual 文档归档到 `docs/database/_archived/`。
5. **demo-miniprogram 迁移**：从 `tmp/DEMO-miniprogram/` 移至 `apps/demo-miniprogram/`，新增 CLAUDE.md 注解说明用途（MOCK 小程序，假数据驱动，页面样式标杆校对）。
6. **DDL 日期戳刷新**：docs/database/ddl/ 和 db/*/schemas/ 的生成日期统一更新为 2026-04-06。
7. **文档同步**：CLAUDE.md、db/CLAUDE.md、db/README.md、docs/database/README.md 更新以反映新结构。

通过 MCP 连接测试库验证，DDL 文件与数据库现状完全同步（155 表 + 49 视图，零差异）。

## 变更文件

### 新增

| 文件 | 说明 |
|------|------|
| `apps/demo-miniprogram/CLAUDE.md` | MOCK 小程序用途注解，防止被误删 |
| `db/etl_feiqiu/schemas/meta.sql` | etl_feiqiu 库 meta schema 完整 DDL |
| `db/etl_feiqiu/schemas/ods.sql` | etl_feiqiu 库 ods schema 完整 DDL |
| `db/etl_feiqiu/schemas/dwd.sql` | etl_feiqiu 库 dwd schema 完整 DDL |
| `db/etl_feiqiu/schemas/core.sql` | etl_feiqiu 库 core schema 完整 DDL |
| `db/etl_feiqiu/schemas/dws.sql` | etl_feiqiu 库 dws schema 完整 DDL |
| `db/etl_feiqiu/schemas/app.sql` | etl_feiqiu 库 app schema 完整 DDL |
| `db/zqyy_app/schemas/public.sql` | zqyy_app 库 public schema 完整 DDL |
| `db/zqyy_app/schemas/auth.sql` | zqyy_app 库 auth schema 完整 DDL |
| `db/zqyy_app/schemas/biz.sql` | zqyy_app 库 biz schema 完整 DDL |
| `db/etl_feiqiu/migrations/.gitkeep` | 占位文件，供未来增量迁移 |
| `db/zqyy_app/migrations/.gitkeep` | 占位文件，供未来增量迁移 |
| `scripts/ops/` 下 10 个运维脚本 | backfill/report/migration 等有价值的运维脚本入库 |

### 修改

| 文件 | 说明 |
|------|------|
| `.gitignore` | 新增 `.vite/`（构建缓存）和 `apps/*.zip`（小程序打包产物） |
| `.claude/settings.json` | 添加 `effortLevel: "high"` 默认配置 |
| `CLAUDE.md` | 子系统表新增 demo-miniprogram、db/ 描述更新 |
| `db/CLAUDE.md` | 目录结构对齐实际（schemas/ 为主、migrations 留空） |
| `db/README.md` | 反映新结构：schemas/ 权威 DDL、migrations 留空、_archived/ |
| `docs/database/README.md` | DDL 基线描述更新、迁移归档说明、归档文档列表 |
| `docs/database/ddl/*.sql`（10 个） | 生成日期戳刷新为 2026-04-06 |
| `db/*/schemas/*.sql`（9 个） | 生成日期戳刷新为 2026-04-06 |

### 删除

| 范围 | 数量 | 说明 |
|------|------|------|
| `docs/audit/prompt_logs/` | 588 | 废弃的 Kiro prompt_logs，Claude Code session 已覆盖 |
| `tmp/` | 309 | 临时脚本与文件 |
| `scripts/ops/` 旧脚本 | 243 | 已废弃或重复的运维脚本 |
| 旧迁移工具 | 6 | 不再使用的迁移辅助工具 |
| 根级文件 | 6 | `.kiroignore`、`AI_CHANGELOG.md`、`VI-COLOR-SYSTEM-PROJECT-SUMMARY.md`、`_tmp_replace2.py` 等 |
| `export/` | 114 | 报表导出产物，从 git 移除跟踪（.gitignore 已覆盖） |

### 归档（git mv → `_archived/`）

| 范围 | 数量 | 目标 |
|------|------|------|
| etl_feiqiu 迁移脚本 | 11 | `db/_archived/migrations_v1_merged/etl_feiqiu/` |
| zqyy_app 迁移脚本 | 28 | `db/_archived/migrations_v1_merged/zqyy_app/` |
| BD_Manual 迁移文档 | 4 | `docs/database/_archived/` |

### 重命名（git rename）

| 原路径 | 新路径 | 说明 |
|--------|--------|------|
| `tmp/DEMO-miniprogram/` | `apps/demo-miniprogram/` | MOCK 小程序保留，用于页面样式标杆校对 |

## 改动注解

### 高风险文件

- **`db/CLAUDE.md`**（risk: dir:db）— 纯文档重写，目录结构描述对齐实际。不含任何 DDL 语句，不影响数据库结构或数据。
- **`db/README.md`**（risk: dir:db）— 纯文档重写，说明 schemas/ 为权威 DDL、migrations/ 留空、_archived/ 为历史归档。不影响数据库。
- **`db/etl_feiqiu/schemas/*.sql`（6 个）**（risk: dir:db）— 从 `docs/database/ddl/` 复制的完整 DDL 快照。这些是数据库导出的只读副本，不是待执行的迁移脚本。内容与测试库已验证完全一致。
- **`db/zqyy_app/schemas/*.sql`（3 个）**（risk: dir:db）— 同上，zqyy_app 库的三个 schema DDL 快照。
- **`db/etl_feiqiu/migrations/.gitkeep`**（risk: dir:db）— 空占位文件，迁移目录预留。
- **`db/zqyy_app/migrations/.gitkeep`**（risk: dir:db）— 同上。

### 根目录文件

- **`.gitignore`** — 新增两条排除规则，防止构建缓存和打包产物入库。
- **`.claude/settings.json`** — 调整默认 effort 级别为 high。
- **`CLAUDE.md`** — 子系统描述更新，与实际目录结构对齐。

### 普通文件

- 1155 个删除文件均为之前会话已从工作树移除的废弃内容，本次仅 git rm 确认。
- export/ 的 114 个文件是报表导出产物，.gitignore 已覆盖，从版本控制中移除。
- 39 个迁移脚本内容完整保留在 _archived/ 中，仅改变位置。
- 10 个新入库的 scripts/ops/ 脚本为已有的有价值运维脚本。

## 数据库变更

无。DDL 文件是从数据库导出的快照副本（gen_consolidated_ddl.py 生成），不是新建或修改表结构。迁移脚本只是归档（git mv），不影响数据库。已通过 MCP 连接测试库验证 DDL 与数据库现状完全同步（155 表 + 49 视图，零差异）。

## 风险与回滚

| 风险点 | 等级 | 说明 |
|--------|------|------|
| DDL 文件与数据库不同步 | 极低 | 已通过 MCP 连接测试库验证零差异 |
| 迁移脚本归档后丢失 | 无 | git mv 保留完整历史，可随时查看 |
| 废弃文件误删有价值内容 | 极低 | 所有删除文件在 git 历史中可恢复 |
| db/ 目录结构变更影响 CI | 低 | 当前无 CI 依赖 db/ 目录结构 |
| demo-miniprogram 路径变更 | 低 | MOCK 应用，无外部依赖 |

**回滚要点**：
1. 文件删除回滚：`git checkout 6f8f123 -- <path>` 恢复任意被删文件
2. 迁移归档回滚：`git mv db/_archived/migrations_v1_merged/etl_feiqiu/* db/etl_feiqiu/migrations/` + 对应 zqyy_app
3. DDL 文件回滚：删除 `db/*/schemas/*.sql`（它们是 docs/database/ddl/ 的副本）
4. 日期戳回滚：重新运行 gen_consolidated_ddl.py 或 git checkout 恢复原日期
5. 无数据库回滚需要

## 验证

1. DDL 文件与数据库一致性验证（已完成）：
   ```bash
   cd c:/NeoZQYY && python tools/db/gen_consolidated_ddl.py
   # 验证输出与 db/*/schemas/ 文件一致（仅日期戳差异）
   ```

2. 归档迁移脚本完整性验证：
   ```bash
   ls db/_archived/migrations_v1_merged/etl_feiqiu/ | wc -l   # 预期 11
   ls db/_archived/migrations_v1_merged/zqyy_app/ | wc -l     # 预期 28
   ```

3. schemas/ 目录文件完整性验证：
   ```bash
   ls db/etl_feiqiu/schemas/*.sql | wc -l   # 预期 6（meta/ods/dwd/core/dws/app）
   ls db/zqyy_app/schemas/*.sql | wc -l     # 预期 3（public/auth/biz）
   ```

4. demo-miniprogram 位置验证：
   ```bash
   test -f apps/demo-miniprogram/CLAUDE.md && echo "OK" || echo "MISSING"
   ```

## 合规检查

| 检查项 | 状态 |
|--------|------|
| DDL 与数据库一致（MCP 验证） | ✓ 155 表 + 49 视图，零差异 |
| 迁移脚本归档完整（git mv） | ✓ 39 个脚本完整保留 |
| BD_Manual 归档文档完整 | ✓ 4 个文档移至 _archived/ |
| 无数据库结构变更 | ✓ DDL 为导出快照，非新建表 |
| 文档同步完成 | ✓ CLAUDE.md/db 相关 README 均已更新 |
| .gitignore 覆盖导出产物 | ✓ export/ 已排除 |
| 废弃文件在 git 历史可恢复 | ✓ 所有删除均可通过 git checkout 恢复 |