Agent
836ad20515
- main.py: 增加show_banner()启动说明、各阶段[INFO]日志、结果摘要、任意键退出 - file_selector.py: 重写为路径输入→验证→空输入弹窗回退→不存在循环重试 - run.bat: 新建启动脚本(chcp 65001, mode con cols=80 lines=20, color 0B, title固定署名, pause) - Code/docs/modification-assessment.md: 修改需求评估文档
243 lines
7.9 KiB
Markdown
243 lines
7.9 KiB
Markdown
# 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]` | 转换完成 | 显示输出文件路径和统计信息 |
|
||
|
||
---
|
||
|
||
## 许可证
|
||
|
||
内部项目
|