# lidb 系统架构设计

## 概述

lidb是一个用于量化分析的轻量级数据库，提供数据管理、计算和分析功能。系统采用模块化设计，各组件之间通过清晰的接口进行通信，支持灵活的配置和扩展。

```mermaid
graph TD
    A[lidb系统] --> B[数据库模块]
    A --> C[数据集模块]
    A --> D[表模块]
    A --> E[表达式模块]
    A --> F[工具模块]
    
    B --> B1[本地存储]
    B --> B2[远程数据库]
    B --> B3[SQL执行]
    
    C --> C1[依赖管理]
    C --> C2[自动补全]
    C --> C3[并行加载]
    
    D --> D1[全量更新]
    D --> D2[增量更新]
    D --> D3[版本管理]
    
    E --> E1[QDF引擎]
    E --> E2[表达式解析]
    E --> E3[UDF注册]
    
    F --> F1[配置管理]
    F --> F2[分区解析]
    F --> F3[日志记录]
```

## 核心模块设计

### 数据库模块

数据库模块负责本地和远程数据存储与查询，是系统的基础数据访问层。

```mermaid
graph LR
    DB[数据库模块] --> SQL[SQL执行]
    DB --> Put[数据存储]
    DB --> Has[存在检查]
    DB --> Scan[惰性扫描]
    DB --> MySQL[MySQL集成]
    DB --> ClickHouse[ClickHouse集成]
    
    subgraph "数据源"
        Local[(本地Parquet)]
        Remote[(远程数据库)]
    end
    
    SQL --> Local
    Put --> Local
    Has --> Local
    Scan --> Local
    MySQL <--> Remote
    ClickHouse <--> Remote
```

### 数据集模块

数据集模块提供高级数据管理功能，支持复杂的依赖关系和自动数据补全。

```mermaid
graph TD
    DS[数据集模块] --> Dataset[Dataset类]
    DS --> DataLoader[DataLoader类]
    DS --> LoadDS[load_ds函数]
    
    Dataset --> Depends[依赖管理]
    Dataset --> AutoFill[自动补全]
    Dataset --> UpdateTime[更新时间]
    
    DataLoader --> Batch[批量加载]
    DataLoader --> Parallel[并行处理]
    
    LoadDS --> Validate[日期验证]
    LoadDS --> PreDate[前置日期]
    LoadDS --> Submit[并行提交]
    LoadDS --> Collect[结果收集]
```

### 表模块

表模块提供单表数据管理，支持全量和增量更新模式，适用于不同类型的数据存储需求。

```mermaid
graph LR
    T[表模块] --> Table[Table类]
    T --> Mode[TableMode]
    
    Table --> Init[初始化]
    Table --> Update[更新]
    Table --> NeedUpdate[需要更新?]
    Table --> DoJob[执行作业]
    Table --> GetValue[获取数据]
    
    Mode --> F[全量模式]
    Mode --> I[增量模式]
    
    subgraph "存储策略"
        FStrategy[覆盖存储为0.parquet]
        IStrategy[增量存储为UUID.parquet]
    end
    
    F --> FStrategy
    I --> IStrategy
```

### 表达式模块

表达式模块提供强大的分析计算能力，支持复杂表达式解析和执行。

```mermaid
graph TD
    E[表达式模块] --> QDF[QDF类]
    E --> Expr[Expr类]
    E --> UDF[UDF注册]
    
    QDF --> Init[初始化]
    QDF --> Sql[表达式查询]
    QDF --> Register[UDF注册]
    QDF --> Align[数据对齐]
    
    Expr --> Parse[表达式解析]
    Expr --> BuildGraph[依赖图构建]
    Expr --> TopoSort[拓扑排序]
    Expr --> Execute[分批执行]
    
    UDF --> BaseUDF[基础算子]
    UDF --> TsUDF[时间序列]
    UDF --> CsUDF[横截面]
    UDF --> DUDF[日期维度]
    UDF --> IUDF[日内函数]
```

### 工具模块

工具模块提供辅助功能，支持系统配置和数据处理。

```mermaid
graph LR
    U[工具模块] --> Settings[配置管理]
    U --> Parse[分区解析]
    U --> Log[日志记录]
    
    Settings --> ConfigFile[配置文件]
    Settings --> Dynaconf[Dynaconf]
    Settings --> Override[配置覆盖]
    
    Parse --> Hive[分区解析]
    Parse --> DataFrame[结果DataFrame]
    
    Log --> Logair[logair库]
    Log --> Module[模块日志]
```

## 设计原则

### 惰性计算

系统广泛采用惰性计算模式，延迟数据加载和计算直到真正需要时才执行：

- `scan()` 函数返回 `LazyFrame` 而非 `DataFrame`
- `get_value()` 和 `get_history()` 方法仅在需要时才加载数据
- 表达式计算在 `sql()` 方法调用时才实际执行

### 并行处理

系统利用并行处理提高性能：

- `load_ds()` 函数使用 `loky` 并行加载多个数据集
- 表达式依赖图支持分批并行执行
- 数据补全机制并行处理缺失日期

### 依赖注入

系统采用依赖注入模式管理组件关系：

- `Dataset` 类通过 `*depends` 参数注入依赖
- 配置通过 `get_settings()` 函数注入
- 数据源通过路径参数注入

### 配置驱动

系统行为由配置文件驱动：

- 数据库存储路径由 `DB_PATH` 配置
- Polars线程数由 `POLARS_MAX_THREADS` 配置
- 系统行为可通过 `~/.config/lidb/settings.toml` 覆盖

## 架构优势

### 模块化设计

系统采用清晰的模块化设计，各模块职责单一，易于理解、测试和维护。模块之间通过明确定义的接口通信，降低了耦合度。

### 易于扩展

系统设计支持灵活扩展：

- 可通过 `register_udf()` 注册自定义函数
- 可通过继承 `Table` 类扩展表功能
- 可通过添加新模块扩展系统功能

### 高性能计算

系统通过多种技术实现高性能：

- 使用Polars进行快速数据处理
- 采用惰性计算减少不必要的计算
- 利用并行处理提高吞吐量
- 通过分区存储优化数据访问

### 可维护性

系统具有良好的可维护性：

- 清晰的代码结构和模块划分
- 详细的文档和执行计划
- 一致的编程模式和约定
- 灵活的配置系统