Phase 80 — 数据库演进与迁移框架设计

版本: v4.0.0-alpha 创建日期: 2026-03-10 状态: ✅ 已实现

---

一、模块概述

Phase 80 引入结构化的数据库演进框架，包括版本化迁移管理器（MigrationManager）、流式SQL构建器（QueryBuilder）和索引优化器（IndexOptimizer），为SQLite/SQLCipher数据库提供可控的Schema演进、安全的查询构造和智能的索引建议。

1.1 核心目标

1. 版本化迁移: 支持up/down双向迁移，记录迁移历史，防止重复执行
2. 流式查询构建: 链式API构造SQL语句，防止SQL注入，支持复杂查询
3. 索引优化: 基于慢查询日志分析，自动生成索引建议和优化报告
4. 安全回滚: 迁移失败自动回滚，支持手动回退到指定版本

1.2 技术架构

┌──────────────────────────────────────────────────────┐
│           Database Evolution Framework                │
│                                                       │
│  ┌─────────────────────┐  ┌────────────────────────┐ │
│  │  MigrationManager   │  │  QueryBuilder          │ │
│  │  版本化up/down迁移   │  │  链式SQL构建           │ │
│  │  历史记录+回滚       │  │  参数绑定+防注入       │ │
│  └─────────────────────┘  └────────────────────────┘ │
│  ┌─────────────────────┐  ┌────────────────────────┐ │
│  │  IndexOptimizer     │  │  DatabaseEvolutionIPC  │ │
│  │  慢查询日志+分析     │  │  4个IPC handler       │ │
│  │  索引建议+优化报告   │  │  迁移+查询+索引管理    │ │
│  └─────────────────────┘  └────────────────────────┘ │
└──────────────────────────────────────────────────────┘

---

二、核心模块设计

2.1 MigrationManager (database/migration-manager.js)

版本化数据库迁移管理器，支持双向迁移和历史追踪。

核心方法:

• initialize(db) — 初始化迁移管理器，创建迁移历史表
• register(version, { up, down, description }) — 注册迁移版本（up/down均为函数）
• migrate(targetVersion?) — 执行迁移到指定版本（默认最新）
• rollback(targetVersion?) — 回滚到指定版本（默认上一个）
• getStatus() — 获取迁移状态（当前版本、待执行迁移、历史记录）
• getHistory() — 获取完整迁移历史（版本号、执行时间、方向、耗时）
• getCurrentVersion() — 获取当前数据库Schema版本
• getPendingMigrations() — 获取待执行的迁移列表
• validateMigrations() — 校验所有已注册迁移的完整性（检测间断版本号）

迁移历史表:

CREATE TABLE IF NOT EXISTS _migrations (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  version TEXT NOT NULL,
  description TEXT,
  direction TEXT NOT NULL,          -- 'up' | 'down'
  executed_at INTEGER NOT NULL,
  duration_ms INTEGER,
  checksum TEXT,
  status TEXT DEFAULT 'success'     -- 'success' | 'failed' | 'rolled_back'
);

2.2 QueryBuilder (database/query-builder.js)

流式SQL构建器，提供类型安全的查询构造。

核心方法:

• select(...columns) — SELECT查询起始
• from(table) — 指定表名
• where(column, operator, value) — WHERE条件（自动参数绑定）
• andWhere(column, operator, value) — AND条件
• orWhere(column, operator, value) — OR条件
• join(table, on) — INNER JOIN
• leftJoin(table, on) — LEFT JOIN
• orderBy(column, direction) — 排序
• limit(count) — 限制返回数量
• offset(count) — 偏移量
• groupBy(...columns) — 分组
• having(condition) — HAVING条件
• insert(table, data) — INSERT语句
• update(table, data) — UPDATE语句
• delete(table) — DELETE语句
• build() — 生成 { sql, params } 对象
• execute(db) — 构建并执行查询，返回结果

2.3 IndexOptimizer (database/index-optimizer.js)

基于查询日志的索引分析和优化建议引擎。

核心方法:

• initialize(db) — 初始化优化器，创建查询日志表
• logQuery(sql, durationMs, { params, source }) — 记录查询执行日志
• analyze(options?) — 分析查询日志，生成索引建议
• getSuggestions() — 获取当前索引建议列表
• applySuggestion(suggestionId) — 应用指定索引建议（创建索引）
• getQueryStats() — 获取查询统计（总查询数、慢查询数、平均耗时、Top N慢查询）
• getExistingIndexes() — 获取现有索引列表
• setSlowQueryThreshold(ms) — 设置慢查询阈值
• clearLog() — 清空查询日志

查询日志表:

CREATE TABLE IF NOT EXISTS _query_log (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  sql_text TEXT NOT NULL,
  params_json TEXT,
  duration_ms REAL NOT NULL,
  source TEXT,
  tables_accessed TEXT,
  created_at INTEGER NOT NULL
);

CREATE TABLE IF NOT EXISTS _index_suggestions (
  id TEXT PRIMARY KEY,
  table_name TEXT NOT NULL,
  columns TEXT NOT NULL,
  suggestion_type TEXT,             -- 'create_index' | 'composite_index' | 'covering_index'
  estimated_improvement REAL,
  query_count INTEGER DEFAULT 0,
  applied INTEGER DEFAULT 0,
  created_at INTEGER
);

---

三、核心文件

文件	说明
src/main/database/migration-manager.js	版本化迁移管理器（up/down/回滚/历史）
src/main/database/query-builder.js	流式SQL构建器（链式API+参数绑定）
src/main/database/index-optimizer.js	索引优化器（慢查询分析+建议生成）
src/main/database/database-evolution-ipc.js	数据库演进IPC handler注册

---

四、IPC Handlers

Channel	说明
db:migration-status	获取迁移状态（当前版本、待执行迁移数、最近迁移历史）
db:run-migration	执行迁移到指定版本（支持up和down方向）
db:index-suggestions	获取索引优化建议列表（基于慢查询分析）
db:query-stats	获取查询统计（总数、慢查询数、平均耗时、Top慢查询）

---

五、数据库表

-- 迁移历史记录
CREATE TABLE IF NOT EXISTS _migrations (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  version TEXT NOT NULL,
  description TEXT,
  direction TEXT NOT NULL,
  executed_at INTEGER NOT NULL,
  duration_ms INTEGER,
  checksum TEXT,
  status TEXT DEFAULT 'success'
);

-- 查询执行日志
CREATE TABLE IF NOT EXISTS _query_log (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  sql_text TEXT NOT NULL,
  params_json TEXT,
  duration_ms REAL NOT NULL,
  source TEXT,
  tables_accessed TEXT,
  created_at INTEGER NOT NULL
);

-- 索引优化建议
CREATE TABLE IF NOT EXISTS _index_suggestions (
  id TEXT PRIMARY KEY,
  table_name TEXT NOT NULL,
  columns TEXT NOT NULL,
  suggestion_type TEXT,
  estimated_improvement REAL,
  query_count INTEGER DEFAULT 0,
  applied INTEGER DEFAULT 0,
  created_at INTEGER
);

---

六、测试覆盖

测试文件	测试数量	状态
src/main/database/__tests__/migration-manager.test.js	25	✅ 通过
src/main/database/__tests__/query-builder.test.js	22	✅ 通过
src/main/database/__tests__/index-optimizer.test.js	16	✅ 通过
合计	63	✅ 全部通过

测试要点

• 迁移版本顺序执行和跳跃检测
• up/down双向迁移的幂等性验证
• 迁移失败自动回滚（事务保护）
• QueryBuilder各子句组合的SQL正确性
• 参数绑定防SQL注入测试
• 慢查询阈值过滤和Top N排序
• 索引建议的去重和优先级排序
• 复合索引建议的列顺序优化

---

七、前端集成

Pinia Store

• databaseEvolution.ts — 迁移状态、查询统计、索引建议

Vue Pages

• DatabaseEvolutionPage.vue — 迁移历史时间线、查询性能图表、索引建议列表

Routes

• /admin/database — 数据库管理

---

八、配置选项

databaseEvolution: {
  enabled: true,
  migration: {
    autoMigrate: true,                // 启动时自动执行待处理迁移
    backupBeforeMigrate: true,        // 迁移前自动备份数据库
    maxRollbackVersions: 10,          // 最大回滚版本数
  },
  queryBuilder: {
    logQueries: true,                 // 是否记录所有查询
    parameterizedOnly: true,          // 强制参数化查询
  },
  indexOptimizer: {
    enabled: true,
    slowQueryThresholdMs: 100,        // 慢查询阈值（ms）
    analysisIntervalMs: 3600000,      // 自动分析间隔（1小时）
    maxLogEntries: 50000,             // 最大查询日志条目数
    autoApply: false,                 // 是否自动应用索引建议
  },
}