# nander-rs 架构设计文档

## 架构原则

本项目采用**分层架构** (Layered Architecture) + **领域驱动设计** (Domain-Driven Design) 的混合模式。

### 核心原则

1. **依赖倒置** - 高层模块不依赖低层模块，都依赖抽象
2. **单一职责** - 每个模块只负责一个明确的功能域
3. **开放封闭** - 对扩展开放，对修改封闭
4. **接口隔离** - 使用 trait 定义清晰的接口边界

## 架构分层

```
┌─────────────────────────────────────┐
│      Presentation Layer             │  CLI/TUI/GUI 适配器
│      (presentation/)                │
├─────────────────────────────────────┤
│      Application Layer              │  用例编排
│      (application/)                 │  业务流程控制
├─────────────────────────────────────┤
│      Domain Layer                   │  核心业务逻辑
│      (domain/)                      │  领域模型和规则
├─────────────────────────────────────┤
│      Infrastructure Layer           │  技术实现
│      (infrastructure/)              │  硬件驱动、数据库
└─────────────────────────────────────┘
```

## 层次职责

### 1. Domain Layer (领域层)

**路径**: `src/domain/`

**职责**: 定义核心业务概念和规则，不依赖任何外部技术

**模块**:
- `chip.rs` - 芯片模型（ChipSpec, ChipCapability）
- `flash_operation.rs` - Flash 操作抽象接口
- `bad_block.rs` - 坏块管理策略（BadBlockStrategy）
- `ecc.rs` - ECC 控制策略（EccPolicy）
- `src/error.rs` - 全局错误定义 (注：目前位于根目录以方便各层共享资源)

**示例**:
```rust
pub struct ChipSpec {
    pub id: ChipId,
    pub name: &'static str,
    pub manufacturer: Manufacturer,
    pub capacity: Capacity,
    pub layout: ChipLayout,
}

pub trait FlashOperation {
    fn read(&mut self, request: ReadRequest) -> Result<Vec<u8>>;
    fn write(&mut self, request: WriteRequest) -> Result<()>;
    fn erase(&mut self, request: EraseRequest) -> Result<()>;
}

ReadRequest 包含读取操作相关的字段，例如地址、长度、ECC 选项、BBT，以及用于读取失败时重试次数的 `retry_count` 字段（用于未来实现自动重试机制）。示例：

```rust
pub struct ReadRequest {
    pub address: Address,
    pub length: u32,
    pub use_ecc: bool,
    /// Ignore ECC errors and continue reading (for data recovery)
    pub ignore_ecc_errors: bool,
    pub oob_mode: OobMode,
    pub bad_block_strategy: BadBlockStrategy,
    /// Pre-scanned Bad Block Table (optional)
    pub bbt: Option<BadBlockTable>,
    /// Number of retries for read operations
    pub retry_count: u32,
}
```
```

### 2. Application Layer (应用层)

**路径**: `src/application/`

**职责**: 编排业务用例，协调领域对象完成具体任务

**模块**:
- `use_cases/` - 具体用例实现
  - `read_flash.rs` - 读取用例（ReadFlashUseCase）
  - `write_flash.rs` - 写入用例（WriteFlashUseCase）
  - `erase_flash.rs` - 擦除用例
  - `verify_flash.rs` - 验证用例
  - `detect_chip.rs` - 芯片检测用例
- `services/` - 应用服务
  - `chip_detector.rs` - 芯片检测服务
  - `progress_tracker.rs` - 进度跟踪服务

**示例**:
```rust
pub struct ReadFlashUseCase<P: Programmer> {
    programmer: P,
    chip_db: Arc<ChipDatabase>,
    bad_block_handler: Box<dyn BadBlockHandler>,
}

impl<P: Programmer> ReadFlashUseCase<P> {
    pub fn execute(&mut self, params: ReadParams) -> Result<Vec<u8>> {
        // 1. 检测芯片
        // 2. 应用 ECC 策略
        // 3. 处理坏块
        // 4. 执行读取
        // 5. 报告进度
    }
}
```

### 3. Infrastructure Layer (基础设施层)

**路径**: `src/infrastructure/`

**职责**: 提供技术实现，硬件驱动，数据存储

**模块**:
- `programmer/` - 硬件编程器实现
  - `traits.rs` - Programmer trait 定义
  - `ch341a/` - CH341A 驱动实现
  - `discovery.rs` - 硬件自动发现
- `flash_protocol/` - Flash 协议实现
  - `nand/` - SPI NAND 协议
  - `nor/` - SPI NOR 协议
  - `commands.rs` - SPI 命令常量
- `chip_database/` - 芯片数据库
  - `registry.rs` - 芯片注册表
  - `nand/` - NAND 芯片定义（按制造商分类）
  - `nor/` - NOR 芯片定义（按制造商分类）
  - `loader.rs` - 动态加载器

**示例**:
```rust
// programmer/traits.rs
pub trait Programmer {
    fn name(&self) -> &str;
    fn spi_transfer(&mut self, tx: &[u8], rx: &mut [u8]) -> Result<()>;
    fn set_cs(&mut self, active: bool) -> Result<()>;
}

// chip_database/registry.rs
pub struct ChipDatabase {
    chips: Vec<ChipSpec>,
}

impl ChipDatabase {
    pub fn find_by_jedec(&self, id: &[u8; 3]) -> Option<&ChipSpec> { }
    pub fn list_by_manufacturer(&self, mfr: Manufacturer) -> Vec<&ChipSpec> { }
}
```

### 4. Presentation Layer (表现层)

**路径**: `src/presentation/`

**职责**: 用户交互，将用户输入转换为应用层调用

**模块**:
- `cli/` - 命令行接口
  - `args.rs` - 参数解析
  - `handlers/` - 命令处理器（每个命令一个文件）
    - `info_handler.rs`
    - `read_handler.rs`
    - `write_handler.rs`
  - `output/` - 输出格式化
    - `progress.rs` - 进度条
    - `formatter.rs` - 输出格式化

**示例**:
```rust
pub struct ReadHandler {
    use_case: ReadFlashUseCase<Box<dyn Programmer>>,
}

impl CommandHandler for ReadHandler {
    fn handle(&mut self, args: ReadArgs) -> Result<()> {
        let params = ReadParams::from_args(args)?;
        let data = self.use_case.execute(params)?;
        // 输出结果
    }
}
```

## 目录结构

```
src/
├── main.rs                         # 程序入口
├── lib.rs                          # 库导出
│
├── domain/                         # 领域层
│   ├── mod.rs
│   ├── chip.rs
│   ├── flash_operation.rs
│   ├── bad_block.rs
│   ├── ecc.rs
│   └── types.rs
│
├── application/                    # 应用层
│   ├── mod.rs
│   ├── use_cases/
│   │   ├── mod.rs
│   │   ├── read_flash.rs
│   │   ├── write_flash.rs
│   │   ├── erase_flash.rs
│   │   ├── verify_flash.rs
│   │   └── detect_chip.rs
│   └── services/
│       ├── mod.rs
│       ├── chip_detector.rs
│       └── progress_tracker.rs
│
├── infrastructure/                 # 基础设施层
│   ├── mod.rs
│   ├── programmer/
│   │   ├── mod.rs
│   │   ├── traits.rs
│   │   ├── ch341a/
│   │   │   ├── mod.rs
│   │   │   ├── usb.rs
│   │   │   └── protocol.rs
│   │   └── discovery.rs
│   ├── flash_protocol/
│   │   ├── mod.rs
│   │   ├── commands.rs
│   │   ├── nand/
│   │   │   ├── mod.rs
│   │   │   ├── protocol.rs
│   │   │   └── ecc_handler.rs
│   │   └── nor/
│   │       ├── mod.rs
│   │       └── protocol.rs
│   └── chip_database/
│       ├── mod.rs
│       ├── registry.rs
│       ├── loader.rs
│       ├── nand/
│       │   ├── mod.rs
│       │   ├── gigadevice.rs
│       │   ├── winbond.rs
│       │   ├── macronix.rs
│       │   ├── micron.rs
│       │   └── xtx.rs
│       └── nor/
│           ├── mod.rs
│           ├── gigadevice.rs
│           ├── winbond.rs
│           └── macronix.rs
│
├── presentation/                   # 表现层
│   ├── mod.rs
│   └── cli/
│       ├── mod.rs
│       ├── args.rs
│       ├── handlers/
│       │   ├── mod.rs
│       │   ├── info_handler.rs
│       │   ├── list_handler.rs
│       │   ├── read_handler.rs
│       │   ├── write_handler.rs
│       │   ├── erase_handler.rs
│       │   └── verify_handler.rs
│       └── output/
│           ├── mod.rs
│           ├── progress.rs
│           └── formatter.rs
│
├── config/                         # 配置
│   ├── mod.rs
│   └── constants.rs
│
└── error.rs                        # 全局错误类型

```

## 依赖关系

```
presentation → application → domain
                    ↓
              infrastructure
```

- **Presentation** 依赖 **Application** 和 **Infrastructure**
- **Application** 依赖 **Domain** 和 **Infrastructure**
- **Domain** 不依赖任何其他层（纯业务逻辑）
- **Infrastructure** 实现 **Domain** 定义的接口

## 扩展指南

### 添加新的硬件编程器

1. 在 `infrastructure/programmer/` 创建新文件夹
2. 实现 `Programmer` trait
3. 在 `discovery.rs` 中添加检测逻辑

### 添加新的芯片

1. 在 `infrastructure/chip_database/nand/` 或 `nor/` 对应制造商文件中添加
2. 如果是新制造商，创建新文件
3. 芯片会在启动时自动加载

### 添加新的命令

1. 在 `application/use_cases/` 创建用例
2. 在 `presentation/cli/handlers/` 创建处理器
3. 在 `args.rs` 添加命令参数定义

## 测试策略

- **单元测试**: 每层独立测试
  - Domain: 纯逻辑测试，无 mock
  - Application: 使用 mock Programmer
  - Infrastructure: 使用真实硬件或 mock USB
  - Presentation: 测试参数解析和格式化

- **集成测试**: 跨层测试
  - 端到端测试完整用例

## 重构路线图

### Phase 1: 建立新架构骨架 ✅ 已完成
- [x] 创建新的目录结构
- [x] 定义领域层核心类型 (`domain/types.rs`)
- [x] 定义芯片规格模型 (`domain/chip.rs`)
- [x] 定义 Flash 操作 trait (`domain/flash_operation.rs`)
- [x] 定义坏块管理策略 (`domain/bad_block.rs`)
- [x] 定义 ECC 策略 (`domain/ecc.rs`)
- [x] 创建基础设施层结构
- [x] 迁移 Programmer trait 到新位置
- [x] 创建芯片数据库按制造商分类结构

### Phase 2: 协议与数据库迁移 ✅ 已完成
- [x] 创建 `flash_protocol/nand` 基础框架
- [x] 创建 `flash_protocol/nor` 基础框架
- [x] 创建芯片数据库分类结构 (NAND/NOR)
- [x] 迁移完整的 NAND 读/写/擦除逻辑
- [x] 迁移完整的 NOR 读/写/擦除逻辑
- [x] 实现 OobMode 支持（None/Included/Only）
- [x] 实现 ECC 控制（enable/disable）
- [x] 实现进度报告回调
- [ ] 从旧版芯片数据库迁移所有芯片定义

### Phase 3: 应用层与表现层 ✅ 已完成

**Phase 3.1: 应用层用例** ✅ 已完成
- [x] 实现 `application/use_cases/detect_chip.rs`
- [x] 实现 `application/use_cases/read_flash.rs`
- [x] 实现 `application/use_cases/write_flash.rs`
- [x] 实现 `application/use_cases/erase_flash.rs`
- [x] 创建参数对象 (ReadParams, WriteParams, EraseParams)
- [x] 添加使用示例文档 (APPLICATION_USAGE.md)

**Phase 3.2: 表现层 CLI** ✅ 已完成
- [x] 迁移 CLI 处理器到 `presentation/cli/handlers/`
- [x] 实现 info_handler
- [x] 实现 read_handler
- [x] 实现 write_handler
- [x] 实现 erase_handler
- [x] 实现 verify_handler
- [x] 实现 list_handler

**Phase 3.3: 系统切换** ✅ 已完成
- [x] 更新 main.rs 使用新 CLI
- [x] 移除遗留模块引用

**Phase 3.4: 清理** ✅ 已完成
- [x] 删除遗留模块
- [x] 消除所有警告
- [x] 完善文档


