# 快速入门指南

本文档帮助你快速上手 PinMAP → PinList 转换器。

---

## 环境要求

### 系统要求

| 项目 | 要求 |
|------|------|
| 操作系统 | Windows 7+ / Linux / macOS |
| Python | 3.6+（推荐 3.8+） |
| 内存 | ≥ 64MB（实际使用 < 20MB） |
| 磁盘 | ≥ 1MB |

### 依赖项

**零第三方依赖** — 仅需 Python 标准库。

```bash
# 检查 Python 版本
python --version
# 输出示例: Python 3.12.3
```

### GUI 支持（可选）

- **Windows**: tkinter 内置，开箱即用
- **Linux**: 需要 `python3-tk` 包（`sudo apt install python3-tk`）
- **macOS**: tkinter 内置

> 无 GUI 环境时自动回退到命令行模式，不影响核心功能。

---

## 快速开始

### 第一步：获取项目

```bash
# 进入项目目录
cd pinmap-to-pinlist/Code/src/
```

### 第二步：运行转换

#### 方式一：GUI 模式（推荐）

```bash
python main.py
```

弹出文件选择对话框，选择 `.xls` 或 `.xlsx` 文件即可。

#### 方式二：命令行模式

```bash
python main.py /path/to/your/input.xlsx
```

### 第三步：查看输出

转换完成后，在当前目录生成 `{原文件名}_PinList.xlsx`：

```
输入:  QFP44_PinMAP.xlsx
输出:  QFP44_PinMAP_PinList.xlsx
```

---

## 使用示例

### 示例 1：标准方形 PinMAP

**输入文件** `QFP44.xlsx`：

```
     A          B        C        D        E        F
1   QFP-44
2                             Pin6     6
3                             Pin5     5
4   1         Pin1
5   2         Pin2
6              Pin3     Pin4
7              3        4
```

**运行命令**：

```bash
python main.py QFP44.xlsx
```

**输出**：

```
[INFO] 解析完成: 6x6 方形，共 8 个Pin
[INFO] 封装信息: QFP-44

[SUCCESS] 转换完成！输出文件: QFP44_PinList.xlsx
  - 封装信息: QFP-44
  - Pin数量: 8
```

**输出文件内容**：

```
     A          B
1   QFP-44
2   Pin1      1
3   Pin2      2
4   Pin3      3
5   Pin4      4
6   Pin5      5
7   Pin6      6
```

### 示例 2：长方形 PinMAP

**输入文件** `LQFP100.xlsx`（13 个引脚的长方形封装）

```bash
python main.py LQFP100.xlsx
```

**输出**：

```
[INFO] 解析完成: 长方形结构，共 13 个Pin
[INFO] 封装信息: LQFP-100

[SUCCESS] 转换完成！输出文件: LQFP100_PinList.xlsx
  - 封装信息: LQFP-100
  - Pin数量: 13
```

### 示例 3：处理警告

当 PinMAP 中部分引脚缺少 PinName 时：

```
[INFO] 解析完成: 6x6 方形，共 8 个Pin
[INFO] 封装信息: QFP-44

[WARN] 发现 3 个警告:
  - 检测到 3 个引脚缺少 PinName: 缺失引脚序号: [2, 3, 4]，将默认为 NC

[SUCCESS] 转换完成！输出文件: QFP44_PinList.xlsx
  - 封装信息: QFP-44
  - Pin数量: 8
```

缺失 PinName 的引脚在输出中自动标记为 "NC"。

### 示例 4：处理错误

当 PinMAP 存在数据错误时：

```
[INFO] 解析完成: 6x6 方形，共 8 个Pin
[INFO] 封装信息: QFP-44

[ERROR] 发现 1 个错误:
  - Pin序号不连续: 缺失的序号: [3]

转换终止，请修正PinMAP文件后重试。
```

---

## PinMAP 文件规范

### 格式要求

| 要求 | 说明 |
|------|------|
| A1 单元格 | 必须包含封装信息（如 "QFP-44"） |
| 方形区域 | 至少 2×2，引脚沿四条边分布 |
| 引脚序号 | 1-based 整数，从 1 到 N 连续 |
| 排序方向 | 左上角为 1 脚，逆时针排列 |
| PinName 位置 | 在序号单元格的"内侧相邻"位置 |

### 四边 PinName 位置

```
左边：序号在 (r, min_col)，PinName 在 (r, min_col+1)
下边：序号在 (max_row, c)，PinName 在 (max_row-1, c)
右边：序号在 (r, max_col)，PinName 在 (r, max_col-1)
上边：序号在 (min_row, c)，PinName 在 (min_row+1, c)
```

### 支持的输入格式

| 格式 | 扩展名 | 支持情况 |
|------|--------|----------|
| Excel 97-2003 | `.xls` | ✅ 支持（BIFF8 引擎） |
| Excel 2007+ | `.xlsx` | ✅ 支持（OOXML 引擎） |

### 输出格式

| 格式 | 扩展名 | 说明 |
|------|--------|------|
| Excel 2007+ | `.xlsx` | 唯一输出格式 |

---

## 常见问题

### Q1: 运行时提示 "未选择文件，退出"

**原因**：在 GUI 模式下点击了"取消"，或在无 GUI 环境下未提供命令行参数。

**解决**：
```bash
# 提供命令行参数
python main.py input.xlsx
```

### Q2: 提示 "文件读取失败"

**可能原因**：
- 文件路径不存在
- 文件格式不是有效的 Excel 文件
- 文件已损坏

**解决**：
- 检查文件路径是否正确
- 确认文件可以用 Excel 正常打开
- 尝试用 Excel 重新保存文件

### Q3: 提示 "A1 单元格为空，缺少封装信息"

**原因**：PinMAP 文件的 A1 单元格为空。

**解决**：在 Excel 中打开文件，在 A1 单元格填入封装信息（如 "QFP-44"），保存后重新转换。

### Q4: 提示 "Pin序号不连续"

**原因**：Pin 序号存在间隔（如 1, 2, 4, 5，缺少 3）。

**解决**：检查 PinMAP 文件，补全缺失的引脚序号。

### Q5: 提示 "Pin序号重复"

**原因**：同一个 Pin 序号出现了多次。

**解决**：检查 PinMAP 文件，修正重复的序号。

### Q6: 警告 "检测到 N 个引脚缺少 PinName"

**说明**：这是警告而非错误，转换会继续进行。缺失的 PinName 会自动设为 "NC"。

**解决**（可选）：在 Excel 中补全缺失的 PinName，重新转换。

### Q7: Linux 下没有弹出文件选择对话框

**说明**：Linux 无头环境（无显示器）不支持 tkinter GUI。

**解决**：使用命令行模式：
```bash
python main.py /path/to/input.xlsx
```

如需 GUI，安装 tkinter：
```bash
sudo apt install python3-tk
```

### Q8: 输出文件打不开

**可能原因**：Excel 版本过旧（2003 及以下不支持 .xlsx）。

**解决**：使用 Excel 2007+ 或 WPS Office 打开输出文件。

### Q9: 支持多大的 PinMAP？

**回答**：当前实现适合 < 1000 引脚的场景。典型 IC 封装引脚数在 8~200 之间，完全满足需求。

### Q10: 能否批量转换多个文件？

**回答**：当前版本一次处理一个文件。如需批量转换，可使用 shell 脚本：

```bash
for f in *.xlsx; do
    python main.py "$f"
done
```

---

## 测试验证

运行内置单元测试：

```bash
cd Code/src/
python test_pinmap.py
```

预期输出：
```
✓ test_4x4_parse passed
✓ test_4x4_validate passed
✓ test_missing_names_warning passed
✓ test_duplicate_numbers passed
✓ test_gap_in_numbers passed
✓ test_empty_cells passed
✓ test_no_pins passed
✓ test_12pin_square passed

✅ All tests passed!
```