v1.0.1: 新增完整文档体系（README/QUICKSTART/RELEASE）
This commit is contained in:
@@ -1,5 +1,14 @@
|
|||||||
# Changelog
|
# Changelog
|
||||||
|
|
||||||
|
## [v1.0.1] - 2026-05-25
|
||||||
|
|
||||||
|
### 📝 文档完善
|
||||||
|
|
||||||
|
- 新增 `Code/docs/README.md` — 项目完整说明文档（8.1KB）
|
||||||
|
- 新增 `Code/docs/QUICKSTART.md` — 快速入门指南（6.6KB）
|
||||||
|
- 新增 `Code/docs/RELEASE.md` — 版本发布说明（5.1KB）
|
||||||
|
- 完善项目文档体系，覆盖架构设计、快速上手、版本历史
|
||||||
|
|
||||||
## [v1.0.0] - 2026-05-25
|
## [v1.0.0] - 2026-05-25
|
||||||
|
|
||||||
### 🎉 首次发布
|
### 🎉 首次发布
|
||||||
|
|||||||
315
Code/docs/QUICKSTART.md
Normal file
315
Code/docs/QUICKSTART.md
Normal file
@@ -0,0 +1,315 @@
|
|||||||
|
# 快速入门指南
|
||||||
|
|
||||||
|
本文档帮助你快速上手 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!
|
||||||
|
```
|
||||||
242
Code/docs/README.md
Normal file
242
Code/docs/README.md
Normal file
@@ -0,0 +1,242 @@
|
|||||||
|
# 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]` | 转换完成 | 显示输出文件路径和统计信息 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 许可证
|
||||||
|
|
||||||
|
内部项目
|
||||||
160
Code/docs/RELEASE.md
Normal file
160
Code/docs/RELEASE.md
Normal file
@@ -0,0 +1,160 @@
|
|||||||
|
# 版本发布说明
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## v1.0.0 — 2026-05-25
|
||||||
|
|
||||||
|
### 🎉 首次发布
|
||||||
|
|
||||||
|
这是 PinMAP → PinList 转换器的第一个正式版本，实现了从 Excel PinMAP 到 PinList 的完整转换流程。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 新增功能
|
||||||
|
|
||||||
|
#### PinMAP 解析
|
||||||
|
- 自动识别方形和长方形封装结构
|
||||||
|
- 沿四条边（左→下→右→上）逆时针提取引脚
|
||||||
|
- 角点共享处理（按单元格位置去重）
|
||||||
|
- 支持 2×2 及以上任意尺寸
|
||||||
|
|
||||||
|
#### 数据验证
|
||||||
|
- **序号连续性检查**：检测 1~N 序列中的间隔
|
||||||
|
- **序号唯一性检查**：检测重复的引脚序号
|
||||||
|
- **PinName 完整性检查**：检测缺失的引脚名称（警告级别）
|
||||||
|
- **结构完整性检查**：验证方形区域最小尺寸和 A1 封装信息
|
||||||
|
|
||||||
|
#### PinList 生成
|
||||||
|
- A 列 PinName，B 列 Pin 序号
|
||||||
|
- 按 Pin 序号递增排序
|
||||||
|
- 缺失 PinName 自动设为 "NC"
|
||||||
|
|
||||||
|
#### 格式支持
|
||||||
|
- `.xls` 读取：BIFF8 引擎（OLE2 复合文档解析）
|
||||||
|
- `.xlsx` 读取：OOXML 引擎（ZIP + XML 解析）
|
||||||
|
- `.xlsx` 写入：OOXML 引擎（纯手工构建）
|
||||||
|
|
||||||
|
#### 运行模式
|
||||||
|
- **GUI 模式**：tkinter 文件选择对话框（Windows 推荐）
|
||||||
|
- **命令行模式**：`python main.py input.xlsx`（Linux/Mac 推荐）
|
||||||
|
- 自动回退：无 GUI 环境自动切换至命令行模式
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 技术实现
|
||||||
|
|
||||||
|
| 模块 | 代码量 | 说明 |
|
||||||
|
|------|--------|------|
|
||||||
|
| `xls_reader.py` | ~400 行 | BIFF8 OLE2 解析引擎，支持 SST/LABELSST/NUMBER/FORMULA/RK/MULRK/LABEL |
|
||||||
|
| `xlsx_reader.py` | ~80 行 | ZIP + XML 解析，支持共享字符串表 |
|
||||||
|
| `xlsx_writer.py` | ~120 行 | OOXML 构建，生成标准 .xlsx 文件 |
|
||||||
|
| `pinmap_parser.py` | ~100 行 | 方形边界检测 + 四边引脚提取 |
|
||||||
|
| `validator.py` | ~60 行 | 连续性/唯一性/完整性验证 |
|
||||||
|
| `pinlist_generator.py` | ~40 行 | PinList 生成 + NC 默认值 |
|
||||||
|
| `file_selector.py` | ~35 行 | tkinter 对话框 + 命令行回退 |
|
||||||
|
| `main.py` | ~60 行 | 流程编排 + 异常处理 |
|
||||||
|
| `models.py` | ~40 行 | 数据模型定义 |
|
||||||
|
| `utils.py` | ~35 行 | 坐标转换工具 |
|
||||||
|
|
||||||
|
**总代码量**：约 1000 行（不含注释和空行）
|
||||||
|
**第三方依赖**：0
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 测试覆盖
|
||||||
|
|
||||||
|
#### 单元测试（8 个用例）
|
||||||
|
|
||||||
|
| 用例 | 测试内容 | 结果 |
|
||||||
|
|------|----------|------|
|
||||||
|
| `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 引脚方形解析 | ✅ |
|
||||||
|
|
||||||
|
#### 集成测试（6 个用例）
|
||||||
|
|
||||||
|
| 用例 | 输入文件 | 测试内容 | 结果 |
|
||||||
|
|------|----------|----------|------|
|
||||||
|
| 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 为空检测 | ✅ |
|
||||||
|
|
||||||
|
**测试通过率**：100%（14/14）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 已知问题
|
||||||
|
|
||||||
|
| # | 问题 | 严重性 | 说明 |
|
||||||
|
|---|------|--------|------|
|
||||||
|
| K1 | XLS 读取缺乏真实样本验证 | 中 | 当前测试环境无 `.xls` 格式测试文件，BIFF8 引擎尚未在真实 `.xls` 文件上验证 |
|
||||||
|
| K2 | 无字体/格式保留 | 低 | 输出文件不保留原始 Excel 的字体、颜色、边框等格式信息 |
|
||||||
|
| K3 | 仅支持 sheet1 | 低 | 仅读取 Excel 文件的第一个工作表 |
|
||||||
|
| K4 | Linux 无头环境无 GUI | 低 | 无显示器环境下 tkinter 不可用，需使用命令行模式 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 限制
|
||||||
|
|
||||||
|
| 限制项 | 说明 |
|
||||||
|
|--------|------|
|
||||||
|
| 引脚数量 | 建议 < 1000 引脚（典型封装 < 200 引脚，无压力） |
|
||||||
|
| 输入格式 | 仅支持 `.xls` 和 `.xlsx`，不支持 CSV/其他格式 |
|
||||||
|
| 输出格式 | 仅输出 `.xlsx`，不支持 `.xls` |
|
||||||
|
| 工作表 | 仅处理第一个工作表 |
|
||||||
|
| 公式单元格 | 仅读取公式的计算结果，不保留公式本身 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 未来计划
|
||||||
|
|
||||||
|
#### v1.1.0 — 格式增强（规划中）
|
||||||
|
|
||||||
|
- [ ] 支持 `.xls` 格式输出
|
||||||
|
- [ ] 保留原始 Excel 的字体和格式
|
||||||
|
- [ ] 支持多工作表选择
|
||||||
|
|
||||||
|
#### v1.2.0 — 功能扩展（规划中）
|
||||||
|
|
||||||
|
- [ ] 批量转换（拖拽多个文件）
|
||||||
|
- [ ] CSV 格式输出
|
||||||
|
- [ ] PinMAP 结构可视化预览
|
||||||
|
|
||||||
|
#### v2.0.0 — 架构升级（远期规划）
|
||||||
|
|
||||||
|
- [ ] 支持更多封装类型（BGA、QFN 等）
|
||||||
|
- [ ] 插件式解析器架构
|
||||||
|
- [ ] Web 界面
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 升级指南
|
||||||
|
|
||||||
|
**首次使用**：直接运行即可，无需升级。
|
||||||
|
|
||||||
|
**从测试版升级**：替换 `Code/src/` 目录下所有文件。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 贡献者
|
||||||
|
|
||||||
|
- 架构设计：Script Architect
|
||||||
|
- 编码实现：Coding Agent × 3
|
||||||
|
- 测试验证：QA Agent
|
||||||
|
- 文档编写：Doc Gen Agent
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 获取帮助
|
||||||
|
|
||||||
|
- 查看 `QUICKSTART.md` 了解使用方法
|
||||||
|
- 查看 `architecture-design.md` 了解技术细节
|
||||||
|
- 查看 `Test/test_report.md` 了解测试详情
|
||||||
Reference in New Issue
Block a user