# PinMAP → PinList 转换器

将 Excel 格式的 **PinMAP** 文件（方形封装引脚布局图）自动转换为 **PinList** 格式（引脚序号列表），消除手动抄录的低效与错误风险。

---

## 项目简介

在 IC 封装设计中，PinMAP 以方形/长方形矩阵形式展示引脚分布，而 PinList 则以线性列表形式提供引脚序号对照。本项目通过纯 Python 实现，自动完成从 PinMAP 到 PinList 的转换，支持 `.xls` 和 `.xlsx` 两种格式。

**版本**: v1.0.0  
**发布日期**: 2026-05-25  
**运行平台**: Windows（tkinter GUI）/ Linux（命令行回退）  
**技术栈**: Python 标准库，零第三方依赖

---

## 功能特性

### 核心功能

| 功能 | 说明 |
|------|------|
| **PinMAP 解析** | 自动识别方形/长方形结构，沿四条边（左→下→右→上）逆时针提取引脚 |
| **数据验证** | 检测序号不连续、序号重复、PinName 缺失、A1 封装信息缺失 |
| **PinList 生成** | A 列 PinName，B 列 Pin 序号，按序号递增排序 |
| **双格式支持** | 同时支持 `.xls`（BIFF8 引擎）和 `.xlsx`（OOXML 引擎） |
| **双模式运行** | GUI 文件选择对话框 + 命令行参数模式 |

### 验证规则

- **序号连续性**：Pin 序号必须为 1~N 连续整数，无间隔
- **序号唯一性**：每个 Pin 序号只能出现一次，无重复
- **PinName 完整性**：缺失 PinName 的引脚自动标记为 "NC"（警告级别，不中断流程）
- **结构完整性**：方形区域至少 2×2，A1 单元格必须包含封装信息

---

## 技术栈

### 零第三方依赖

本项目完全使用 Python 标准库实现，不依赖任何第三方包。

| 模块 | 用途 | 标准库 |
|------|------|--------|
| `xls_reader.py` | BIFF8 解析引擎（~19KB OLE2 解析） | `struct` |
| `xlsx_reader.py` | XLSX 读取引擎（ZIP + XML 解析） | `zipfile`, `xml.etree.ElementTree` |
| `xlsx_writer.py` | XLSX 写入引擎（OOXML 构建） | `zipfile`, `xml.etree.ElementTree` |
| `file_selector.py` | 文件选择对话框 | `tkinter.filedialog` |
| `pinmap_parser.py` | PinMAP 结构解析 | 纯 Python |
| `validator.py` | 数据验证 | `collections.Counter` |
| `pinlist_generator.py` | PinList 生成 | 纯 Python |

### 核心技术亮点

- **BIFF8 手动解析**：从零实现 OLE2 复合文档 + BIFF8 记录流解析，支持 SST、LABELSST、NUMBER、FORMULA、RK、MULRK、LABEL 等记录类型
- **OOXML 手动构建**：不使用 openpyxl/xlrd，纯手工构建 `[Content_Types].xml`、`workbook.xml`、`sharedStrings.xml`、`sheet1.xml` 等 OOXML 结构
- **模块化架构**：解析 → 验证 → 生成 → 输出，各模块职责清晰，接口契约明确

---

## 使用方式

### 前提条件

- Python 3.6+（推荐 3.8+）
- Windows 环境（GUI 模式需要 tkinter）
- Linux/Mac 环境（仅命令行模式）

### 命令行模式

```bash
# 基本用法
python main.py input.xlsx

# 支持 .xls 格式
python main.py input.xls

# 输出文件自动命名为 input_PinList.xlsx
```

### GUI 模式

```bash
# 不带参数运行，弹出文件选择对话框
python main.py
```

在对话框中选择 `.xls` 或 `.xlsx` 文件，点击"打开"即可开始转换。

### 输出示例

输入 PinMAP（方形封装）：

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

输出 PinList：

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

---

## 项目结构

```
pinmap-to-pinlist/
├── Code/
│   ├── src/
│   │   ├── main.py              # 主入口：流程编排
│   │   ├── file_selector.py     # 文件选择（GUI + 命令行回退）
│   │   ├── xls_reader.py        # XLS (BIFF8) 读取引擎
│   │   ├── xlsx_reader.py       # XLSX 读取引擎
│   │   ├── xlsx_writer.py       # XLSX 写入引擎
│   │   ├── pinmap_parser.py     # PinMAP 结构解析
│   │   ├── validator.py         # 数据验证
│   │   ├── pinlist_generator.py # PinList 生成
│   │   ├── models.py            # 数据模型
│   │   ├── utils.py             # 工具函数
│   │   └── test_pinmap.py       # 单元测试
│   └── docs/
│       ├── README.md            # 本文档
│       ├── QUICKSTART.md        # 快速入门指南
│       ├── RELEASE.md           # 版本发布说明
│       ├── architecture-design.md  # 架构设计文档
│       └── team.md              # 团队成员
├── Test/
│   ├── fixtures/                # 测试夹具
│   │   ├── sample_4x4.xlsx      # 标准 4×4 PinMAP
│   │   ├── sample_rect.xlsx     # 长方形 PinMAP
│   │   ├── error_gap.xlsx       # 序号不连续测试
│   │   ├── error_dup.xlsx       # 序号重复测试
│   │   ├── error_empty_a1.xlsx  # A1 为空测试
│   │   └── warning_missing.xlsx # PinName 缺失测试
│   └── test_report.md           # 测试报告
├── README.md                    # 项目根目录 README
├── CHANGELOG.md                 # 变更日志
└── .gitignore
```

---

## 测试情况

### 单元测试

运行 `python test_pinmap.py`（在 `Code/src/` 目录下）：

| 测试用例 | 说明 | 状态 |
|----------|------|------|
| `test_4x4_parse` | 4×4 方形 PinMAP 解析 | ✅ 通过 |
| `test_4x4_validate` | 4×4 方形验证 | ✅ 通过 |
| `test_missing_names_warning` | PinName 缺失警告 | ✅ 通过 |
| `test_duplicate_numbers` | 序号重复检测 | ✅ 通过 |
| `test_gap_in_numbers` | 序号不连续检测 | ✅ 通过 |
| `test_empty_cells` | 空单元格处理 | ✅ 通过 |
| `test_no_pins` | 无引脚数据检测 | ✅ 通过 |
| `test_12pin_square` | 12 引脚方形解析 | ✅ 通过 |

### 集成测试

| 测试用例 | 输入文件 | 说明 | 状态 |
|----------|----------|------|------|
| TC001 | `sample_4x4.xlsx` | 标准 4×4 转换（8 Pin） | ✅ 通过 |
| TC002 | `sample_rect.xlsx` | 长方形转换（13 Pin） | ✅ 通过 |
| TC003 | `error_gap.xlsx` | 序号不连续检测 | ✅ 通过 |
| TC004 | `error_dup.xlsx` | 序号重复检测 | ✅ 通过 |
| TC005 | `warning_missing.xlsx` | PinName 缺失警告 | ✅ 通过 |
| TC006 | `error_empty_a1.xlsx` | A1 为空检测 | ✅ 通过 |

**结论**：所有测试用例通过，无阻塞性问题。详见 `Test/test_report.md`。

---

## 解析算法说明

### PinMAP 结构

PinMAP 以方形/长方形矩阵展示引脚分布：

```
        col A(0)   col B(1)   col C(2)   col D(3)
row 0   [A1=封装]
row 1   [1]        [2]        [3]        [4]          ← 上边 Pin 序号
row 2   [PinName]  [          ]          [PinName]    ← PinName 行
row 3   [PinName]  [          ]          [PinName]
row 4   [13]       [12]       [11]       [10]         ← 下边 Pin 序号
```

### 逆时针提取规则

引脚沿四条边**逆时针**提取：

1. **左边**：从上到下
2. **下边**：从左到右
3. **右边**：从下到上
4. **上边**：从右到左

角点单元格只计数一次（按单元格位置去重）。

### PinList 输出规则

- A1 单元格：封装信息（从 PinMAP 的 A1 复制）
- A 列：PinName（缺失时自动设为 "NC"）
- B 列：Pin 序号
- 按 Pin 序号递增排序

---

## 错误处理

| 级别 | 类型 | 行为 |
|------|------|------|
| `[FATAL]` | 文件格式错误 / 结构错误 | 终止处理，显示错误信息 |
| `[ERROR]` | 数据验证错误（重复/不连续） | 终止处理，显示详细错误 |
| `[WARN]` | PinName 缺失 | 提示警告，自动设为 "NC"，继续处理 |
| `[INFO]` | 解析进度信息 | 仅显示，不影响流程 |
| `[SUCCESS]` | 转换完成 | 显示输出文件路径和统计信息 |

---

## 许可证

内部项目