# 架构文档 (Architecture)

本文档描述了 `l-tool` 的系统架构和核心组件。

## 概览

`l-tool` 是一个基于 Rust 构建的模块化命令行工具。它采用单体二进制文件 (Monolithic Binary) 结构，通过子命令 (Subcommands) 区分不同功能模块。

## 技术栈

- **语言**: Rust (Edition 2024)
- **CLI 框架**: [Clap](https://github.com/clap-rs/clap) v4 (Derive 模式)
- **异步运行时**: [Tokio](https://github.com/tokio-rs/tokio) v1
- **错误处理**: [ThisError](https://github.com/dtolnay/thiserror) (库层面) / Result
- **核心依赖**:
  - `image`: 图片处理
  - `printpdf` / `lopdf`: PDF 生成与操作
  - `serde` / `serde_json`: 数据序列化

## 模块设计

源代码位于 `src/` 目录下，采用分层结构：

### 1. 入口层 (`src/main.rs`)

- 负责初始化异步运行时 (`#[tokio::main]`)。
- 调用库入口 `l_tool::run_cli()`。
- 处理顶级错误并以友好的方式退出。

### 2. 库接口层 (`src/lib.rs`)

- 定义核心 CLI 结构 (`Cli` struct) 和顶级子命令枚举 (`Commands` enum)。
- 负责分发命令到具体的处理器函数。
- 导出公共模块供二进制入口和集成测试使用。

### 3. 命令实现层 (`src/commands/`)

每个功能域都有独立的目录，例如 `src/commands/js/` 或 `src/commands/image/`。

标准结构：
- `mod.rs`: 导出模块内容。
- `commands.rs`: 定义该模块的参数结构 (Args) 和子命令枚举 (Subcommands)。
- `xxx.rs`: 具体的业务逻辑实现文件 (如 `upgrade.rs`, `convert.rs`)。

### 4. 通用层 (`src/types/` & `src/utils/`)

- **Types**: 定义跨模块使用的通用数据结构，如 `Result` 别名、`PackageManager` 枚举。
- **Utils**: 提供日志 (`log.rs`)、文件操作、包管理器检测等辅助功能。

## 数据流

1. 用户在终端输入命令 (如 `l-tool js upgrade`)。
2. `main.rs` 启动，`Clap` 解析命令行参数。
3. `lib.rs` 匹配 `js` 子命令，调用 `commands::js::commands::handle_js_command`。
4. `handle_js_command` 匹配 `upgrade` 子命令，调用 `commands::js::upgrade::execute`。
5. `execute` 函数执行具体逻辑，可能调用 `utils` 或外部 crate。
6. 执行结果以 `Result<()>` 形式返回，成功则静默或打印日志，失败则返回错误信息。
