# DBNexus 模块修复设计文档

**日期**: 2026-01-23
**作者**: AI Assistant
**目的**: 修复 migration、tracing、cli、permission 模块的关键问题

---

## 概述

本文档描述了修复 DBNexus 四个关键模块的设计方案：
1. **Migration 模块** - 实现自动生成回滚 SQL
2. **Tracing 模块** - 实现完整的分布式追踪功能
3. **CLI 模块** - 实现 schema 差异检测功能
4. **Permission 模块** - 合并整合两个权限模块

**设计原则**：
- 性能优先
- 完整测试覆盖
- 向后兼容
- 最小化改动

---

## 1. Migration 模块 - 自动生成回滚 SQL

### 1.1 核心思路

实现一个 SQL 逆向生成器，通过解析 UP SQL 自动生成对应的 DOWN SQL。

### 1.2 实现细节

#### 1.2.1 SQL 解析器扩展

扩展现有的 `sqlparser` 功能，不仅识别操作类型，还要提取表结构变更细节：

- 表名
- 列名、列类型
- 约束（NOT NULL、DEFAULT、UNIQUE、PRIMARY KEY、FOREIGN KEY）
- 索引定义

#### 1.2.2 逆向操作映射

为每种 SQL 操作定义逆向操作：

| UP 操作 | DOWN 操作 | 实现难度 |
|---------|-----------|---------|
| CREATE TABLE | DROP TABLE | 简单 |
| ALTER TABLE ADD COLUMN | ALTER TABLE DROP COLUMN | 简单 |
| ALTER TABLE RENAME COLUMN | ALTER TABLE RENAME COLUMN (逆向) | 简单 |
| ALTER TABLE MODIFY COLUMN | 恢复到修改前的列定义 | 中等 |
| INSERT | DELETE (根据主键) | 中等 |
| UPDATE | UPDATE (恢复原值) | 困难 |
| DELETE | INSERT (保存删除前的数据) | 困难 |

#### 1.2.3 元数据跟踪

在执行迁移前，记录表的当前状态：

- 列定义
- 索引
- 约束

使用 `MigrationMetadata` 结构体存储：

```rust
pub struct MigrationMetadata {
    pub version: u32,
    pub name: String,
    pub up_sql: String,
    pub down_sql: Option<String>,  // 自动生成
    pub table_snapshots: HashMap<String, TableSnapshot>,
}
```

#### 1.2.4 列变更实现

实现以下操作：

- `RenameColumn` - 重命名列
- `ModifyColumn` - 修改列类型
- `NullabilityChanged` - 修改 NOT NULL 约束
- `DefaultChanged` - 修改默认值

这些操作需要数据库特定的 SQL 语法：

```rust
pub enum ColumnChange {
    RenameColumn { table: String, old_name: String, new_name: String },
    ModifyColumn { table: String, column: String, new_type: String },
    NullabilityChanged { table: String, column: String, nullable: bool },
    DefaultChanged { table: String, column: String, default: Option<String> },
}
```

#### 1.2.5 性能优化

- 使用缓存存储已解析的 SQL 和生成的回滚 SQL
- 使用 `lru` crate 实现 LRU 缓存
- 缓存键：迁移版本的哈希值

### 1.3 实现文件

- `src/migration/sql_reverser.rs` - SQL 逆向生成器
- `src/migration/metadata.rs` - 元数据跟踪
- `src/migration/column_changes.rs` - 列变更操作

### 1.4 测试策略

- 单元测试：每种操作的逆向生成
- 集成测试：完整的迁移和回滚流程
- 性能测试：缓存命中率、生成速度

---

## 2. Tracing 模块 - 完整分布式追踪功能

### 2.1 核心思路

在现有初始化功能基础上，构建完整的分布式追踪系统。

### 2.2 实现细节

#### 2.2.1 Span 管理

创建 `TracingContext` 结构体：

```rust
pub struct TracingContext {
    tracer: Arc<Tracer>,
    current_span: Arc<Span>,
}

impl TracingContext {
    pub fn start_span(&self, name: &str) -> Self;
    pub fn start_span_with_parent(&self, name: &str, parent: &Span) -> Self;
    pub fn end_span(self);
}

impl Drop for TracingContext {
    fn drop(&mut self) {
        // 自动结束 span
    }
}
```

#### 2.2.2 属性记录

提供类型安全的属性记录：

```rust
impl TracingContext {
    pub fn set_attribute(&self, key: &str, value: AttributeValue);
    pub fn set_attributes(&self, attributes: Vec<(String, AttributeValue)>);
}

pub enum AttributeValue {
    String(String),
    I64(i64),
    F64(f64),
    Bool(bool),
    Array(Vec<AttributeValue>),
}
```

#### 2.2.3 错误追踪

记录错误信息和堆栈跟踪：

```rust
impl TracingContext {
    pub fn record_error(&self, error: &dyn std::error::Error);
    pub fn record_error_with_stack(&self, error: &dyn std::error::Error);
}
```

#### 2.2.4 采样率配置

在初始化时配置采样率：

```rust
pub async fn init_with_sampling(
    exporter: &str,
    endpoint: &str,
    sampling_rate: f64,
) -> Result<TracingGuard, String>;
```

使用 `TraceIdRatioBased` 采样器：

```rust
let sampler = Sampler::TraceIdRatioBased(sampling_rate);
```

#### 2.2.5 性能优化

- 使用 `once_cell` 延迟初始化 Tracer
- 属性记录使用无锁数据结构
- 采样率检查在 span 创建时进行
- 支持禁用追踪（零开销）

### 2.3 实现文件

- `src/tracing/context.rs` - TracingContext 实现
- `src/tracing/attributes.rs` - 属性记录
- `src/tracing/error.rs` - 错误追踪
- `src/tracing/sampler.rs` - 采样率配置

### 2.4 测试策略

- 单元测试：span 生命周期、属性记录
- 集成测试：跨上下文传播
- 性能测试：采样率影响、属性记录开销

---

## 3. CLI 模块 - Schema 差异检测功能

### 3.1 核心思路

集成专业的 schema diff 库，实现自动化的 schema 差异检测和 UP/DOWN SQL 生成。

### 3.2 实现细节

#### 3.2.1 库选择

评估以下选项：

1. `migra` (Python) - 通过 FFI 调用
2. `schema-diff` (Rust) - 如果可用
3. 基于 `sqlparser` 的简化版本

**推荐**：基于 `sqlparser` 的简化版本，避免引入 Python 依赖。

#### 3.2.2 Schema 解析

解析 schema 文件，提取表结构信息：

```rust
pub struct Schema {
    pub tables: HashMap<String, Table>,
}

pub struct Table {
    pub name: String,
    pub columns: Vec<Column>,
    pub constraints: Vec<Constraint>,
    pub indexes: Vec<Index>,
}

pub struct Column {
    pub name: String,
    pub data_type: String,
    pub nullable: bool,
    pub default: Option<String>,
}
```

#### 3.2.3 差异检测

比较两个 schema，识别变更：

```rust
pub struct SchemaDiff {
    pub added_tables: Vec<Table>,
    pub removed_tables: Vec<String>,
    pub table_changes: HashMap<String, TableDiff>,
}

pub struct TableDiff {
    pub added_columns: Vec<Column>,
    pub removed_columns: Vec<String>,
    pub modified_columns: Vec<ColumnChange>,
    pub constraint_changes: Vec<ConstraintChange>,
}
```

#### 3.2.4 SQL 生成

根据差异生成 UP/DOWN SQL：

```rust
pub fn generate_sql(diff: &SchemaDiff, dialect: DatabaseDialect) -> DiffSql {
    DiffSql {
        up: generate_up_sql(diff, dialect),
        down: generate_down_sql(diff, dialect),
    }
}
```

#### 3.2.5 load_applied_migrations 修复

从数据库查询已应用的迁移：

```rust
async fn load_applied_migrations(session: &mut dbnexus::Session) -> Result<HashSet<u32>, DbError> {
    use dbnexus::migration::Model as MigrationModel;
    use sea_orm::EntityTrait;

    let migrations = MigrationModel::find()
        .all(session.connection())
        .await?;

    let versions: HashSet<u32> = migrations.into_iter()
        .map(|m| m.version)
        .collect();

    Ok(versions)
}
```

### 3.3 实现文件

- `src/cli/schema.rs` - Schema 解析
- `src/cli/diff.rs` - 差异检测
- `src/cli/generator.rs` - SQL 生成

### 3.4 测试策略

- 单元测试：schema 解析、差异检测
- 集成测试：完整的 diff 和生成流程
- 性能测试：大型 schema 处理速度

---

## 4. Permission 模块 - 合并整合

### 4.1 核心思路

将 `permission.rs` 和 `permission_engine.rs` 合并为统一的权限模块。

### 4.2 实现细节

#### 4.2.1 统一接口

保留 `PermissionContext` 作为核心接口：

```rust
pub struct PermissionContext {
    role: String,
    provider: Arc<dyn PermissionProvider>,
    cache: Arc<DashMap<String, RolePolicy>>,
}

impl PermissionContext {
    pub async fn check_table_access(&self, table: &str, operation: PermissionAction) -> bool;
    pub async fn check_permission(&self, resource: &str, action: &str) -> PermissionDecision;
}
```

#### 4.2.2 功能整合

**基础 RBAC**：

```rust
pub struct RbacProvider {
    roles: HashMap<String, RolePolicy>,
}
```

**高级特性**：

```rust
pub struct AdvancedRbacProvider {
    roles: HashMap<String, RolePolicy>,
    role_hierarchy: HashMap<String, Vec<String>>,  // 角色继承
    priority: HashMap<String, u32>,  // 权限优先级
}
```

#### 4.2.3 架构优化

使用 Builder 模式：

```rust
pub struct PermissionEngineBuilder {
    config: PermissionConfig,
    provider_type: ProviderType,
}

impl PermissionEngineBuilder {
    pub fn new() -> Self;
    pub fn with_yaml_config(mut self, path: &str) -> Self;
    pub fn with_role_hierarchy(mut self, hierarchy: HashMap<String, Vec<String>>) -> Self;
    pub fn build(self) -> Result<PermissionEngine, String>;
}
```

#### 4.2.4 性能优化

- 使用 `dashmap` 替代 `AsyncMutex<HashMap>`
- 权限检查使用原子操作
- 支持权限预编译

#### 4.2.5 迁移路径

- 保留旧 API 作为 deprecated
- 提供编译时警告
- 提供迁移工具

### 4.3 实现文件

- `src/permission/mod.rs` - 统一的权限模块
- `src/permission/provider.rs` - PermissionProvider trait
- `src/permission/rbac.rs` - RBAC 实现
- `src/permission/advanced.rs` - 高级特性

### 4.4 测试策略

- 单元测试：权限检查逻辑
- 集成测试：角色继承、优先级系统
- 性能测试：并发权限检查速度

---

## 5. 架构概述

### 5.1 整体架构

```
应用代码
    ↓
CLI 工具
    ↓
Migration 执行器
    ↓
SQL 解析器
    ↓
回滚 SQL 生成器
    ↓
数据库
```

### 5.2 依赖关系

- CLI 依赖 Migration 模块
- Migration 依赖 Permission 模块
- 所有模块依赖 Tracing 模块

### 5.3 实施顺序

1. Migration 模块（基础）
2. Tracing 模块（可观测性）
3. CLI 模块（工具层）
4. Permission 模块（安全层）

---

## 6. 测试策略

### 6.1 测试类型

- **单元测试**：每个模块的独立功能
- **集成测试**：模块间协作
- **性能测试**：确保性能不降低
- **回归测试**：现有功能不受影响

### 6.2 测试覆盖率目标

- 单元测试：≥ 90%
- 集成测试：≥ 80%
- 关键路径：100%

---

## 7. 性能目标

- Migration 回滚生成：< 100ms（中等规模 schema）
- Tracing 开销：< 5%（禁用时 0%）
- CLI schema diff：< 1s（大型 schema）
- Permission 检查：< 10μs（缓存命中）

---

## 8. 风险和缓解

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| SQL 逆向生成不准确 | 数据损坏 | 完整测试覆盖，人工审核关键迁移 |
| Schema diff 库不成熟 | 功能缺失 | 实现简化版本，逐步完善 |
| Permission 合并破坏兼容性 | 现有代码失效 | 保留 deprecated API，提供迁移指南 |
| Tracing 性能开销过大 | 系统性能下降 | 采样率控制，支持禁用 |

---

## 9. 后续步骤

1. 创建实施计划（使用 `writing-plans` skill）
2. 创建隔离的 git worktree（使用 `using-git-worktrees` skill）
3. 按实施顺序逐步实现
4. 每个模块完成后进行测试和代码审查
5. 合并到主分支

---

## 附录

### A. 依赖清单

- 现有：`sqlparser`, `lru`, `dashmap`, `sea-orm`
- 新增：无（使用现有依赖）

### B. 文件清单

**新增文件**：
- `src/migration/sql_reverser.rs`
- `src/migration/metadata.rs`
- `src/migration/column_changes.rs`
- `src/tracing/context.rs`
- `src/tracing/attributes.rs`
- `src/tracing/error.rs`
- `src/tracing/sampler.rs`
- `src/cli/schema.rs`
- `src/cli/diff.rs`
- `src/cli/generator.rs`

**修改文件**：
- `src/migration/executor.rs`
- `src/migration/mod.rs`
- `src/tracing.rs`
- `src/cli/src/main.rs`
- `src/permission.rs`
- `src/permission_engine.rs`

### C. API 变更

**新增 API**：
- `Migration::rollback_with_generated_sql()`
- `TracingContext::start_span()`
- `TracingContext::set_attribute()`
- `TracingContext::record_error()`
- `generate_schema_diff_sql()`（完整实现）
- `PermissionEngine::new()`

**废弃 API**：
- `PermissionConfig`（保留，标记为 deprecated）
- `RbacPermissionProvider`（合并到新模块）

**修改 API**：
- `rollback_migration()` - 现在执行实际回滚 SQL
- `load_applied_migrations()` - 返回实际数据

---

**文档版本**: 1.0
**最后更新**: 2026-01-23