DEV_GUIDE.md

# DCU Performance Analyzer 开发文档

## 概述

本文档旨在为 DCU Performance Analyzer 的开发者提供技术细节和架构说明。该工具是一个基于Python的性能分析框架，用于自动化DCU环境的检查和监控。

## 架构设计

### 核心组件
- **主类 (`DCUPerformanceAnalyzer`)**: 负责管理整个分析流程，包括初始化、检查执行、报告生成和数据打包。
- **数据结构 (`CheckResult`)**: 统一的检查结果数据模型，用于在不同模块间传递数据。
- **检查模块 (check_*)**: 每个检查模块是一个独立的函数，负责执行特定的检查任务并返回 `CheckResult` 对象。
- **命令行界面 (CLI)**: 使用 `argparse` 构建，提供用户友好的交互界面。
- **日志系统**: 使用 `logging` 模块，支持调试模式和静默模式。

### 目录结构
```
dcuprofiletools/
├── dcu_performance_analyzer.py # 主程序
├── env_check/                 # 原始脚本目录
│   └── dcu_env_check-main/
├── dist/                      # PyInstaller打包输出
│   └── dcu_analyzer          # 可执行文件
├── USER_MANUAL.md             # 用户手册
└── DEV_GUIDE.md               # 开发文档
```

## 技术栈

- **编程语言**: Python 3.7+
- **核心库**:
  - `argparse`: 命令行解析
  - `subprocess`: 执行shell命令
  - `logging`: 日志记录
  - `json`: 数据序列化
  - `tarfile`: 文件打包
  - `concurrent.futures`: 并发处理
  - `dataclasses`: 数据结构定义
- **打包工具**: PyInstaller

## 模块详解

### `DCUPerformanceAnalyzer`

#### `__init__(self, output_dir, debug, quiet)`
- 初始化输出目录、日志系统和结果列表。
- 创建必要的子目录（logs, data, reports）。

#### `_setup_logging(self)`
- 配置日志处理器（文件和控制台）。
- 根据 `debug` 和 `quiet` 参数设置日志级别。

#### `run_command(self, cmd, timeout)`
- 使用 `subprocess.run` 执行shell命令。
- 捕获标准输出、标准错误和返回码。
- 处理超时和异常情况。

#### `check_*` 模块
- 每个模块负责一个独立的检查任务。
- 使用 `run_command` 执行必要的shell命令。
- 处理命令输出，提取关键信息。
- 构建并返回 `CheckResult` 对象。

#### `run_all_checks(self)`
- 使用 `ThreadPoolExecutor` 并发执行所有检查模块。
- 收集 `CheckResult` 对象。

#### `generate_report(self)`
- 统计检查结果（PASS, FAIL, WARNING）。
- 生成JSON和文本格式的报告文件。

#### `create_package(self)`
- 使用 `tarfile` 将整个输出目录打包成 `tar.gz` 文件。

### `create_cli()`
- 使用 `argparse` 定义命令行参数和帮助信息。

### `main()`
- 程序入口点。
- 解析命令行参数。
- 创建 `DCUPerformanceAnalyzer` 实例并运行分析。
- 处理异常和用户中断。

## 开发指南

### 添加新的检查模块
1. 在 `DCUPerformanceAnalyzer` 类中创建一个新的方法，命名为 `check_new_feature`。
2. 该方法应返回一个 `CheckResult` 对象。
3. 在方法内部，使用 `self.run_command` 执行必要的命令。
4. 处理命令输出，并根据结果设置 `CheckResult` 的状态和消息。
5. 将新模块添加到 `run_all_checks` 方法的检查列表中。
6. 在 `create_cli` 函数中，将新模块的名称添加到 `choices` 列表中。

### 扩展 `CheckResult`
- 如果需要添加新的字段，可以直接修改 `CheckResult` 的 `dataclass` 定义。
- 确保所有检查模块都正确填充新字段。

### 修改报告格式
- `generate_report` 方法负责生成报告。
- 可以修改JSON结构或文本摘要的格式。
- 确保向后兼容性，或更新版本号。

## 测试

### 单元测试
- 对每个检查模块编写单元测试，模拟不同的命令输出和异常情况。
- 使用 `unittest.mock` 来模拟 `subprocess.run`。

### 集成测试
- 运行完整的分析流程，验证所有模块的集成。
- 检查生成的报告和数据包是否正确。

### 手动测试
- 在不同的Linux发行版上测试可执行文件。
- 模拟各种错误情况（如权限不足、命令缺失）。

## 打包和发布

### 使用 PyInstaller
```bash
pip install pyinstaller
pyinstaller --onefile --name dcu_analyzer dcu_performance_analyzer.py
```

### 注意事项
- 确保所有依赖项都已安装。
- PyInstaller可能会产生较大的可执行文件，可以考虑使用虚拟环境来减小体积。
- 在目标平台上进行打包，以确保兼容性。

## 贡献

### 代码风格
- 遵循 PEP 8 代码风格指南。
- 使用类型提示（Type Hinting）。
- 编写清晰的文档字符串（Docstrings）。

### 提交规范
- 使用有意义的提交信息。
- 每个提交应包含一个独立的逻辑单元。
- 在提交前运行代码格式化和静态分析工具。

## 路线图

- **v1.1**: 支持更多的性能基准测试。


---