docs: v1.5.0 - 更新模板分离与格式提取文档
This commit is contained in:
@@ -11,8 +11,8 @@
|
||||
|
||||
在 IC 封装设计中，PinMAP 以方形/长方形矩阵形式展示引脚分布，而 PinList 则以线性列表形式提供引脚序号对照。本项目通过纯 Python 实现，自动完成 PinMAP 与 PinList 之间的双向转换，支持 `.xls` 和 `.xlsx` 两种格式。
|
||||
|
||||
**版本**: v1.2.0
|
||||
**发布日期**: 2026-05-28
|
||||
**版本**: v1.5.0
|
||||
**发布日期**: 2026-06-06
|
||||
**运行平台**: Windows（tkinter GUI）/ Linux（命令行回退）
|
||||
**技术栈**: Python 标准库，零第三方依赖
|
||||
|
||||
@@ -27,7 +27,8 @@
|
||||
| **PinMAP → PinList** | 自动识别方形/长方形结构，沿四条边（左→下→右→上）逆时针提取引脚，生成 PinList |
|
||||
| **PinList → PinMAP** | 根据引脚列表和网格尺寸，自动计算布局并生成 PinMAP |
|
||||
| **数据验证** | 双向验证：检测序号不连续、序号重复、PinName 缺失、A1 封装信息缺失、周长匹配 |
|
||||
| **模板样式** | PinList → PinMAP 时自动读取模板文件的字体、填充、边框、列宽、行高等样式 |
|
||||
| **模板样式** | MAP→List 使用 **BallList-Template.xlsx**，List→MAP 使用 **BallMAP-Template.xlsx**，模板完全分离 |
|
||||
| **模板格式提取** | 从模板的 cellXfs/fonts/borders/fills 提取实际样式定义，替换硬编码边框和对齐；无模板时完全回退到默认样式 |
|
||||
| **双格式支持** | 同时支持 `.xls`（BIFF8 引擎）和 `.xlsx`（OOXML 引擎） |
|
||||
| **双模式运行** | GUI 文件选择对话框 + 命令行参数模式 |
|
||||
|
||||
@@ -69,7 +70,7 @@
|
||||
| `pinlist_validator.py` | PinList 数据验证 | `collections.Counter` |
|
||||
| `pinlist_generator.py` | PinList 生成 | 纯 Python |
|
||||
| `validator.py` | PinMAP 数据验证 | `collections.Counter` |
|
||||
| `template_reader.py` | 模板样式提取 | `zipfile`, `xml.etree.ElementTree` |
|
||||
| `template_reader.py` | 模板样式提取（含 cellXfs/xfId/applyAlignment/wrapText） | `zipfile`, `xml.etree.ElementTree` |
|
||||
| `models.py` | 数据模型 | `dataclasses` |
|
||||
| `utils.py` | 工具函数 | 纯 Python |
|
||||
|
||||
@@ -85,6 +86,38 @@
|
||||
|
||||
## 使用方式
|
||||
|
||||
### 模板使用说明（v1.5.0）
|
||||
|
||||
从 v1.5.0 开始，两个方向的转换使用各自独立的模板文件：
|
||||
|
||||
| 转换方向 | 模板文件 | 查找位置 |
|
||||
|----------|----------|----------|
|
||||
| **MAP→List** | `BallList-Template.xlsx` | 项目根目录 → 当前工作目录 |
|
||||
| **List→MAP** | `BallMAP-Template.xlsx` | 项目根目录 → 当前工作目录 |
|
||||
|
||||
#### 模板格式提取机制
|
||||
|
||||
程序从模板的 OOXML styles.xml 和 sheet1.xml 中**提取**具体的样式定义（字体、边框、填充、对齐、列宽、行高），然后写入输出的 `<styleSheet>` 中。这种方式是**提取式**（读取具体属性值）而非直接复制 cellXf 引用，确保即使模板结构复杂也能正确提取关键样式属性。
|
||||
|
||||
```
|
||||
xl/styles.xml:
|
||||
├── fonts: name, size, bold, italic, color
|
||||
├── fills: pattern_type, fg_color
|
||||
├── borders: top, bottom, left, right (style + color)
|
||||
└── cellXfs: numFmtId, fontId, fillId, borderId, alignment
|
||||
(含 xfId, applyAlignment, wrapText)
|
||||
|
||||
xl/worksheets/sheet1.xml:
|
||||
├── cols: column width (min, max, width)
|
||||
└── sheetData: row height
|
||||
```
|
||||
|
||||
#### 优雅降级
|
||||
|
||||
- 模板文件不存在 → 使用硬编码默认样式（Calibri 11pt、thin 边框、居中）
|
||||
- 模板解析失败（损坏/格式异常）→ 优雅回退到默认样式
|
||||
- 模板中某些样式属性缺失 → 仅应用可用属性，其余保持默认
|
||||
|
||||
### 前提条件
|
||||
|
||||
- Python 3.6+（推荐 3.8+）
|
||||
@@ -326,7 +359,12 @@ pinmap-to-pinlist/
|
||||
│ │ ├── error_gap.xlsx # 序号不连续测试
|
||||
│ │ ├── error_dup.xlsx # 序号重复测试
|
||||
│ │ ├── error_empty_a1.xlsx # A1 为空测试
|
||||
│ │ └── warning_missing.xlsx # PinName 缺失测试
|
||||
│ │ ├── warning_missing.xlsx # PinName 缺失测试
|
||||
│ │ ├── BallList-Template.xlsx # MAP→List 样式模板（测试用）
|
||||
│ │ ├── BallMAP-Template.xlsx # List→MAP 样式模板（测试用）
|
||||
│ │ ├── template_corrupt.xlsx # 损坏模板回退测试
|
||||
│ │ ├── template_minimal.xlsx # 最小模板测试
|
||||
│ │ └── template_narrow.xlsx # 窄列宽模板测试
|
||||
│ └── test_report.md # 测试报告
|
||||
├── README.md # 项目根目录 README
|
||||
├── CHANGELOG.md # 变更日志
|
||||
@@ -341,6 +379,8 @@ pinmap-to-pinlist/
|
||||
|
||||
运行 `python test_pinmap.py`（在 `Code/src/` 目录下）：
|
||||
|
||||
#### 基础功能测试（v1.0−v1.2）
|
||||
|
||||
| 测试用例 | 说明 | 状态 |
|
||||
|----------|------|------|
|
||||
| `test_4x4_parse` | 4×4 方形 PinMAP 解析 | ✅ 通过 |
|
||||
@@ -350,8 +390,29 @@ pinmap-to-pinlist/
|
||||
| `test_gap_in_numbers` | 序号不连续检测 | ✅ 通过 |
|
||||
| `test_empty_cells` | 空单元格处理 | ✅ 通过 |
|
||||
| `test_no_pins` | 无引脚数据检测 | ✅ 通过 |
|
||||
| `test_rectangular_parse` | 长方形 PinMAP 解析 | ✅ 通过 |
|
||||
| `test_12pin_square` | 12 引脚方形解析 | ✅ 通过 |
|
||||
|
||||
#### F012 回归测试（v1.5.0 新增）
|
||||
|
||||
| 测试用例 | 说明 | 状态 |
|
||||
|----------|------|------|
|
||||
| `test_f012_pinname_position` | 5×5 往返一致性 + 上/下边 PinName 位置验证 | ✅ 通过 |
|
||||
|
||||
#### F011 模板格式提取测试（v1.5.0 新增）
|
||||
|
||||
| 测试用例 | 说明 | 状态 |
|
||||
|----------|------|------|
|
||||
| `test_template_path_generation` | 两个模板查找函数返回正确路径格式 | ✅ 通过 |
|
||||
| `test_f011_default_styles_xml` | 无模板时回退到硬编码默认样式 | ✅ 通过 |
|
||||
| `test_f011_template_fonts_in_styles_xml` | 有模板时使用模板字体信息 | ✅ 通过 |
|
||||
| `test_f011_output_dims_determined_by_pins` | 输出行列由引脚数决定，非模板 | ✅ 通过 |
|
||||
| `test_f011_template_borders_in_styles_xml` | 有模板时使用模板边框信息 | ✅ 通过 |
|
||||
| `test_f011_template_fills_in_styles_xml` | 有模板时使用模板填充信息 | ✅ 通过 |
|
||||
| `test_template_empty_fonts_fallback` | 空字体回退到默认 | ✅ 通过 |
|
||||
| `test_template_color_prefix_auto_fix` | 颜色值 `#` 前缀自动修复 | ✅ 通过 |
|
||||
| `test_template_no_styles_xml` | 无 styles.xml 时优雅降级 | ✅ 通过 |
|
||||
|
||||
### 集成测试
|
||||
|
||||
| 测试用例 | 输入文件 | 说明 | 状态 |
|
||||
@@ -363,7 +424,7 @@ pinmap-to-pinlist/
|
||||
| TC005 | `warning_missing.xlsx` | PinName 缺失警告 | ✅ 通过 |
|
||||
| TC006 | `error_empty_a1.xlsx` | A1 为空检测 | ✅ 通过 |
|
||||
|
||||
**结论**：所有测试用例通过，无阻塞性问题。详见 `Test/test_report.md`。
|
||||
**结论**：所有 18 个单元测试 + 6 个集成测试全部通过，无阻塞性问题。详见 `Test/test_report.md`。
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user