# BootRepairTool - 项目说明

## 项目概述

**BootRepairTool** 是一个用于修复 Linux 系统 GRUB 引导的图形化工具。适用于 Live USB/CD 环境，帮助用户修复损坏的 GRUB 引导加载器。

## 项目结构

```
BootRepairTool/
├── backend.py    # 后端逻辑 - 分区扫描、挂载、GRUB修复
├── frontend.py   # 前端界面 - tkinter GUI
├── README.md     # 项目简介
└── AGENTS.md     # 本文件
```

## 技术栈

- **语言**: Python 3
- **GUI 框架**: tkinter
- **运行环境**: Linux Live USB/CD (需要 root/sudo 权限)

## 核心功能

### 1. 分区扫描 (`backend.py:scan_partitions`)
- 使用 `lsblk -J` 获取磁盘和分区信息
- 识别 EFI 系统分区 (ESP)
- 过滤 Live 系统自身的分区

### 2. 系统挂载 (`backend.py:mount_target_system`)
- 挂载根分区 (/)
- 挂载独立 /boot 分区（可选）
- 挂载 EFI 分区（UEFI 模式）
- 绑定伪文件系统 (/dev, /proc, /sys, /run)

### 3. 发行版检测 (`backend.py:detect_distro_type`)
- 支持: Arch, CentOS/RHEL, Debian, Ubuntu
- 通过读取 `/etc/os-release` 识别

### 4. GRUB 修复 (`backend.py:chroot_and_repair_grub`)
- **BIOS 模式**: `grub-install /dev/sdX`
- **UEFI 模式**: `grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=GRUB`
- 更新 GRUB 配置:
  - Debian/Ubuntu: `update-grub`
  - Arch: `grub-mkconfig -o /boot/grub/grub.cfg`
  - CentOS: `grub2-mkconfig -o /boot/grub2/grub.cfg`

### 5. 卸载清理 (`backend.py:unmount_target_system`)
- 逆序卸载绑定的文件系统
- 卸载 EFI/boot/根分区
- 清理临时挂载点

## 前端界面 (`frontend.py`)

### 主要组件

1. **分区选择区域**
   - 根分区 (/) - 必选
   - 独立 /boot 分区 - 可选
   - EFI 系统分区 (ESP) - UEFI 模式下推荐

2. **目标磁盘选择**
   - 物理磁盘选择 (如 /dev/sda)
   - UEFI 模式复选框（自动检测 Live 环境）

3. **日志窗口**
   - 彩色日志输出（信息/警告/错误/成功）
   - 自动滚动

### 工作流程

```
扫描分区 → 用户选择分区 → 点击修复 → 挂载系统 → 
检测发行版 → chroot修复GRUB → 卸载分区 → 完成
```

### 线程安全

修复过程在独立线程中运行，避免 UI 卡死。使用 `master.after()` 进行线程安全的日志更新。

## 代码规范

### 后端函数返回值
所有后端函数统一返回 `(success: bool, ..., error_message: str)` 格式:
```python
# 示例
success, stdout, stderr = run_command([...])
success, disks, partitions, efi_parts, err = scan_partitions()
```

### 错误处理
- 命令执行失败时自动清理已挂载的分区
- 日志记录使用 `[Backend]` 前缀
- GUI 使用弹窗显示关键错误

## 使用限制

1. **需要 root 权限**: 所有磁盘操作需要 `sudo`
2. **Live 环境**: 设计为在 Live USB/CD 中运行
3. **单线程修复**: 同时只能进行一个修复任务
4. **UEFI 自动检测**: 根据 Live 环境自动设置 UEFI 模式

## 测试

直接运行 `backend.py` 可进行基础测试（仅扫描分区）:
```bash
sudo python backend.py
```

完整修复测试需要取消注释 `__main__` 块中的测试代码并设置实际分区。

## 潜在改进点

1. **添加 requirements.txt**: 当前无第三方依赖
2. **国际化**: 当前仅支持中文界面
3. **配置文件**: 支持保存/加载常用配置
4. **日志持久化**: 将日志保存到文件
5. **多语言发行版支持**: 扩展 detect_distro_type
6. **Btrfs/LVM 支持**: 当前仅支持标准分区

## 注意事项

- **数据风险**: 操作磁盘有数据丢失风险，建议备份
- **EFI 分区警告**: UEFI 模式下未选择 ESP 会弹出警告
- **临时挂载点**: 使用 `/mnt_grub_repair_<timestamp>` 格式
- **依赖命令**: 需要系统中存在 `lsblk`, `mount`, `umount`, `grub-install`, `grub-mkconfig`/`update-grub`