pinmap-to-pinlist/Code/docs/QUICKSTART.md

# 快速入门指南

本文档帮助你快速上手 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/
```

### 第二步：运行转换

#### 方式一：交互式模式（推荐）

```bash
python main.py
```

运行后显示方向选择菜单，选择 1 或 2：

```
请选择转换方向:
  1 — PinMAP → PinList
  2 — PinList → PinMAP

请输入选项 (1/2): _
```

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

```bash
# PinMAP → PinList（直接指定文件）
python main.py /path/to/your/PinMAP.xlsx

# PinList → PinMAP（命令行模式默认走 MAP→List 方向）
# 如需 List→MAP，请使用交互式模式
```

### 第三步：查看输出

转换完成后，在当前目录生成输出文件：

```
PinMAP → PinList:  QFP44_PinMAP.xlsx  →  QFP44_PinMAP_PinList.xlsx
PinList → PinMAP:  QFN20_PinList.xlsx →  QFN20_PinList_PinMAP.xlsx
```

---

## 方向一：PinMAP → PinList

将方形封装引脚布局图转换为线性引脚列表。

### 操作步骤

1. 运行 `python main.py`，选择方向 **1**
2. 选择 PinMAP 文件（`.xls` 或 `.xlsx`）
3. 等待转换完成
4. 查看输出的 `_PinList.xlsx` 文件

### 使用示例

**输入文件** `QFP44.xlsx`（6×6 方形封装，8 个引脚）：

```
     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] 正在读取文件: QFP44.xlsx
[INFO] 文件读取完成，共 16 个非空单元格
[INFO] 正在解析 PinMAP 结构...
[INFO] 解析完成: 6x6 方形，共 8 个Pin
[INFO] 封装信息: QFP-44
[INFO] 正在验证数据...
[INFO] 验证通过
[INFO] 正在生成 PinList...
[INFO] 正在写入输出文件: QFP44_PinList.xlsx

[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
```

### 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)
```

---

## 方向二：PinList → PinMAP

将线性引脚列表转换为方形封装引脚布局图。

### 操作步骤

1. 运行 `python main.py`，选择方向 **2**
2. 选择 PinList 文件（`.xls` 或 `.xlsx`）
3. **输入 PinMAP 行数**（至少 2）
4. **输入 PinMAP 列数**（至少 2）
5. 等待转换完成
6. 查看输出的 `_PinMAP.xlsx` 文件

### 尺寸输入说明

PinMAP 的引脚分布在四条边上，总引脚数由网格尺寸决定：

```
总引脚数 = 2 × 行数 + 2 × 列数 − 4
```

常见封装尺寸参考：

| 封装类型 | 引脚数 | 推荐行数 | 推荐列数 |
|----------|--------|----------|----------|
| QFP-8    | 8      | 4        | 4        |
| QFP-16   | 16     | 6        | 6        |
| QFP-20   | 20     | 6        | 6        |
| QFP-24   | 24     | 8        | 6        |
| QFP-32   | 32     | 10       | 8        |
| QFP-44   | 44     | 12       | 10       |
| QFP-64   | 64     | 16       | 16       |
| QFP-100  | 100    | 26       | 26       |

> **提示**：如果不确定尺寸，可以先用公式反推：`行数 + 列数 = (引脚数 + 4) / 2`，然后根据需要调整行和列的比例。

### 模板文件说明

PinList → PinMAP 转换时，程序会自动尝试从输入文件所在目录读取模板样式：

- **模板来源**：程序会尝试解析与输入文件同名的 `.xlsx` 模板文件中的样式信息
- **提取内容**：字体（名称、大小、粗体、斜体、颜色）、填充、边框、列宽、行高
- **优雅降级**：如果模板不存在或解析失败，程序会自动使用默认样式，不影响转换流程

### 使用示例

**输入文件** `QFN20_PinList.xlsx`（20 个引脚）：

```
     A          B
1   QFN-20
2   VCC        1
3   GND        2
4   IO0        3
5   IO1        4
6   IO2        5
7   IO3        6
8   IO4        7
9   IO5        8
10  IO6        9
11  IO7        10
12  NC         11
13  NC         12
14  NC         13
15  NC         14
16  NC         15
17  NC         16
18  NC         17
19  NC         18
20  NC         19
21  NC         20
```

**运行**：

```bash
python main.py
# 选择方向: 2 (PinList → PinMAP)
# 选择文件: QFN20_PinList.xlsx
# 输入行数: 6
# 输入列数: 6
```

**输出**：

```
[INFO] PinMAP 尺寸: 6 行 × 6 列
[INFO] 正在解析 PinList 文件: QFN20_PinList.xlsx
[INFO] 解析完成: 封装信息 'QFN-20', 共 20 个引脚
[INFO] 正在验证数据...
[INFO] 验证通过
[INFO] 正在生成 PinMAP 并写入: QFN20_PinList_PinMAP.xlsx

[SUCCESS] 转换完成！
  输出文件: QFN20_PinList_PinMAP.xlsx
  封装信息: QFN-20
  PinMAP 尺寸: 6×6
  Pin数量: 20
```

**输出文件内容**（6×6 网格，20 个引脚）：

```
     A        B        C        D        E        F
1  QFN-20                          IO8      IO7
2  1        VCC      IO6                    IO5
3  2        GND      IO4                    IO3
4  3        IO0      IO2                    IO1
5  4        IO1      NC                     NC
6  20       19       18       17       16
```

### 布局规则

引脚按**逆时针**分配到四条边（左上角为 1 脚）：

```
左边:   从上到下（rows 个引脚）
下边:   从左到右（cols − 1 个引脚）
右边:   从下到上（rows − 2 个引脚）
上边:   从右到左（cols − 1 个引脚）
```

PinName 与序号的相对位置：

```
左边：Name 在序号右侧
下边：Name 在序号上方
右边：Name 在序号左侧
上边：Name 在序号下方
```

---

## 使用示例汇总

### 示例 1：标准方形 PinMAP（MAP→List）

**输入** `QFP44.xlsx`（6×6，8 Pin）

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

**输出** `QFP44_PinList.xlsx`（A 列 PinName，B 列序号）

### 示例 2：长方形 PinMAP（MAP→List）

**输入** `LQFP100.xlsx`（长方形，13 Pin）

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

**输出** `LQFP100_PinList.xlsx`

### 示例 3：标准 PinList（List→MAP）

**输入** `QFN20_PinList.xlsx`（20 Pin）

```bash
python main.py
# 选择 2，输入 6×6
```

**输出** `QFN20_PinList_PinMAP.xlsx`（6×6 方形）

### 示例 4：处理警告

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

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

[SUCCESS] 转换完成！
```

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

### 示例 5：处理错误

当 PinList 引脚数与网格尺寸不匹配时：

```
[ERROR] 验证未通过，发现 1 个错误:
  - Pin数量与网格周长不匹配: 网格 6×6 需要 20 个引脚，但 PinList 有 24 个

转换终止，请修正PinList文件或网格尺寸后重试。
```

---

## 支持的格式

### 输入格式

| 格式 | 扩展名 | 支持情况 |
|------|--------|----------|
| 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 单元格为空，缺少封装信息"

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

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

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

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

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

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

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

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

### Q6: 提示 "Pin数量与网格周长不匹配"

**原因**：PinList 的引脚数与输入的 rows×cols 网格周长不一致。

**解决**：
- 检查引脚数量是否正确
- 或调整网格尺寸，使 `2×rows + 2×cols − 4 = 引脚数`

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

### Q12: 命令行模式下如何执行 PinList → PinMAP？

**回答**：命令行模式下直接传入文件参数默认走 PinMAP → PinList 方向。如需执行 PinList → PinMAP，请使用交互式模式（不带参数运行），选择方向 2。

---

## 测试验证

运行内置单元测试：

```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!
```