512 lines
16 KiB
Markdown
512 lines
16 KiB
Markdown
# 版本发布说明
|
||
|
||
---
|
||
|
||
## v1.5.0 — 2026-06-06
|
||
|
||
### ✨ 模板分离与格式提取增强
|
||
|
||
v1.5.0 将两个方向的模板完全分离，并实现了**提取式**模板格式应用机制，不再依赖硬编码的边框和对齐属性。新增 F012 回归测试确保上/下边 PinName 位置正确。
|
||
|
||
---
|
||
|
||
### 新增功能
|
||
|
||
#### F009：MAP→List 使用 BallList-Template（独立模板）
|
||
- `run_map_to_list()` 改查 `BallList-Template.xlsx`
|
||
- 不再共用旧模板 `PinMAP-Template.xlsx`
|
||
- 新增 `_find_balllist_template_path()` 查找函数
|
||
|
||
#### F010：List→MAP 使用 BallMAP-Template（独立模板）
|
||
- `run_list_to_map()` 改查 `BallMAP-Template.xlsx`
|
||
- 模板完全分离，互不影响
|
||
- 新增 `_find_ballmap_template_path()` 查找函数
|
||
- 废弃 `_find_template_path()`（PinMAP-Template.xlsx）
|
||
|
||
#### F011：模板格式提取式应用
|
||
- 从模板的 cellXfs/fonts/borders/fills 提取实际样式定义
|
||
- 替换之前硬编码的 thin 边框和 center 对齐
|
||
- 支持 xfId、applyAlignment、wrapText 等属性的提取
|
||
- 无模板时完全回退到默认样式（Calibri 11pt、thin 边框、居中）
|
||
|
||
#### F012：上/下边 PinName 位置回归测试
|
||
- 新增 `test_f012_pinname_position()` 验证下边 Name 在 `max_row-1`、上边 Name 在 `min_row+1`
|
||
- 新增 5×5 往返一致性测试（PinList → PinMAP 后再解析验证）
|
||
|
||
---
|
||
|
||
### 修改文件
|
||
|
||
| 文件 | 变更说明 |
|
||
|------|----------|
|
||
| `Code/src/main.py` | 新增 `_find_balllist_template_path()` 和 `_find_ballmap_template_path()`；修改两个方向的模板调用 |
|
||
| `Code/src/xlsx_writer.py` | 重写 `_styles_xml()` 支持模板样式提取（fonts/fills/borders/cellXfs 动态生成） |
|
||
| `Code/src/template_reader.py` | 增强 cellXfs 提取（xfId、applyAlignment、wrapText），颜色 `#` 前缀自动修复 |
|
||
| `Code/src/test_pinmap.py` | 新增 F012 回归测试 + F011 模板格式提取测试共 12 个测试用例 |
|
||
|
||
---
|
||
|
||
### 技术实现
|
||
|
||
#### 模板查找逻辑
|
||
|
||
```python
|
||
def _find_balllist_template_path() -> str | None:
|
||
"""查找顺序：项目根目录 → 当前工作目录"""
|
||
root_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
||
# 1. 项目根目录
|
||
template_path = os.path.join(root_dir, "BallList-Template.xlsx")
|
||
if os.path.isfile(template_path):
|
||
return template_path
|
||
# 2. 当前工作目录
|
||
cwd_template = os.path.join(os.getcwd(), "BallList-Template.xlsx")
|
||
if os.path.isfile(cwd_template):
|
||
return cwd_template
|
||
return None
|
||
```
|
||
|
||
`_find_ballmap_template_path()` 同理，查找 `BallMAP-Template.xlsx`。
|
||
|
||
#### 样式提取式应用
|
||
|
||
```
|
||
模板 styles.xml
|
||
│
|
||
▼ 读取字体、填充、边框定义
|
||
▼ 读取 cellXfs 引用
|
||
▼ 读取列宽、行高
|
||
│
|
||
▼ 写入输出 styles.xml
|
||
├── 模板的 fonts[]（替换硬编码默认值）
|
||
├── 模板的 fills[]（透明/灰色填充等）
|
||
├── 模板的 borders[]（thin/medium 边框等）
|
||
└── 4 个 cellXfs（序号/名称/封装/空单元格）
|
||
└── 引用模板样式索引
|
||
└── 对齐方式从模板读取而非硬编码
|
||
```
|
||
|
||
---
|
||
|
||
### 测试覆盖
|
||
|
||
#### F012 回归测试
|
||
|
||
| 测试用例 | 说明 | 结果 |
|
||
|----------|------|------|
|
||
| `test_f012_pinname_position` | 5×5 构建 → PinMAP 生成 → 验证四边 PinName 位置 → 序列化/反序列化验证 | ✅ |
|
||
|
||
#### F011 模板格式提取测试
|
||
|
||
| 测试用例 | 说明 | 结果 |
|
||
|----------|------|------|
|
||
| `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 降级 | ✅ |
|
||
|
||
**新增测试**: 12 个测试用例
|
||
**总测试**: 20 个单元测试 + 6 个集成测试 = 26 个
|
||
**测试通过率**: 100%
|
||
|
||
---
|
||
|
||
### 已知问题
|
||
|
||
无
|
||
|
||
---
|
||
|
||
### 限制
|
||
|
||
| 限制项 | 说明 |
|
||
|--------|------|
|
||
| 模板查找 | 仅支持项目根目录和当前工作目录两种位置 |
|
||
| 模板格式 | 仅支持 `.xlsx` 格式模板 |
|
||
| 样式应用 | 提取式而非复制式，部分高级格式可能丢失 |
|
||
|
||
其他限制同 v1.2.0。
|
||
|
||
---
|
||
|
||
### 升级指南
|
||
|
||
**从 v1.3.x / v1.2.0 升级**：替换 `Code/src/` 目录下所有文件。模板文件需手动放置：
|
||
- MAP→List 方向：在项目根目录放置 `BallList-Template.xlsx`
|
||
- List→MAP 方向：在项目根目录放置 `BallMAP-Template.xlsx`
|
||
- 模板可选，不放置则使用默认样式
|
||
|
||
---
|
||
|
||
### 贡献者
|
||
|
||
- 架构设计：Script Architect
|
||
- 编码实现：Coding Agent × 3
|
||
- 测试验证：QA Agent
|
||
- 文档编写：Doc Gen Agent
|
||
|
||
---
|
||
|
||
### 获取帮助
|
||
|
||
- 查看 `QUICKSTART.md` 了解使用方法
|
||
- 查看 `README.md` 了解完整说明
|
||
- 查看 `architecture-design.md` 了解技术细节
|
||
- 查看 `CHANGELOG.md` 了解变更历史
|
||
- 查看 `Test/test_report.md` 了解测试详情
|
||
|
||
---
|
||
|
||
## v1.2.0 — 2026-05-28
|
||
|
||
### ✨ 新增 PinList → PinMAP 反向转换
|
||
|
||
v1.2.0 为项目增加了完整的反向转换能力，PinMAP ↔ PinList 现在可以双向互转。
|
||
|
||
---
|
||
|
||
### 新增功能
|
||
|
||
#### PinList → PinMAP 转换
|
||
- **PinList 解析**：从 Excel 文件中读取 PinName（A 列）和 Pin 序号（B 列）
|
||
- **布局计算**：根据用户输入的行数和列数，自动计算四边引脚分配
|
||
- **逆时针分配**：左上角为 1 脚，沿左边→下边→右边→上边逆时针排列
|
||
- **PinName 定位**：自动计算 PinName 与序号的相对位置（右/上/左/下）
|
||
- **周长验证**：检查引脚总数是否匹配 `2×rows + 2×cols − 4`
|
||
- **优雅降级**：缺失 PinName 自动设为 "NC"
|
||
|
||
#### 模板样式引擎
|
||
- **样式提取**：从模板 xlsx 文件中提取字体、填充、边框、列宽、行高
|
||
- **样式应用**：将模板样式应用到生成的 PinMAP 输出文件
|
||
- **优雅降级**：模板不存在或解析失败时自动使用默认样式
|
||
|
||
#### 交互式方向选择
|
||
- **启动菜单**：运行 `python main.py` 显示方向选择（1: MAP→List / 2: List→MAP）
|
||
- **尺寸输入**：List→MAP 模式需要输入 PinMAP 的行数和列数
|
||
- **文件选择**：根据方向自动切换文件选择器标题和提示
|
||
|
||
#### 数据验证增强
|
||
- **PinList 验证**：序号连续性、序号唯一性、周长匹配、PinName 完整性
|
||
- **非 4 倍数提示**：Pin 数量不是 4 的倍数时提示（信息级别）
|
||
|
||
---
|
||
|
||
### 新增模块
|
||
|
||
| 模块 | 代码量 | 说明 |
|
||
|------|--------|------|
|
||
| `pinlist_parser.py` | ~80 行 | PinList 文件解析（A/B 列读取 + 排序） |
|
||
| `pinlist_validator.py` | ~90 行 | PinList 数据验证（连续性/唯一性/周长匹配） |
|
||
| `pinmap_generator.py` | ~70 行 | PinMAP 生成与输出（布局应用 + 样式） |
|
||
| `pinmap_layout.py` | ~100 行 | PinMAP 布局计算（四边分配 + 坐标计算） |
|
||
| `template_reader.py` | ~170 行 | 模板样式提取（fonts/fills/borders/cols/rows） |
|
||
|
||
### 更新模块
|
||
|
||
| 模块 | 变更说明 |
|
||
|------|----------|
|
||
| `main.py` | 增加 `run_list_to_map()` 流程 + 方向选择菜单 |
|
||
| `file_selector.py` | 增加 `mode` 参数，支持 "map_to_list" / "list_to_map" |
|
||
| `models.py` | 新增 `PinListEntry`、`EdgePins`、`PinMAPLayout`、`LayoutError` |
|
||
| `xlsx_writer.py` | 增加 `write_xlsx_with_style()` 支持模板样式写入 |
|
||
| `validator.py` | 新增 `PinMapValidator` 类，统一验证接口 |
|
||
|
||
---
|
||
|
||
### 技术实现
|
||
|
||
#### 布局算法
|
||
|
||
```
|
||
总引脚数 = 2 × rows + 2 × cols − 4
|
||
|
||
左边: rows 个引脚（从上到下）
|
||
下边: cols − 1 个引脚（从左到右）
|
||
右边: rows − 2 个引脚（从下到上）
|
||
上边: cols − 1 个引脚（从右到左）
|
||
```
|
||
|
||
#### 坐标映射
|
||
|
||
```
|
||
左边: 序号 (r, 0) → Name (r, 1) 右侧
|
||
下边: 序号 (rows, c) → Name (rows-1, c) 上方
|
||
右边: 序号 (r, cols) → Name (r, cols-1) 左侧
|
||
上边: 序号 (1, c) → Name (2, c) 下方
|
||
```
|
||
|
||
#### 模板样式提取
|
||
|
||
```
|
||
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
|
||
|
||
xl/worksheets/sheet1.xml:
|
||
├── cols: column width (min, max, width)
|
||
└── sheetData: row height
|
||
```
|
||
|
||
---
|
||
|
||
### 测试覆盖
|
||
|
||
#### 单元测试（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）
|
||
|
||
---
|
||
|
||
### 已知问题
|
||
|
||
无
|
||
|
||
---
|
||
|
||
### 限制
|
||
|
||
| 限制项 | 说明 |
|
||
|--------|------|
|
||
| 引脚数量 | 建议 < 1000 引脚（典型封装 < 200 引脚，无压力） |
|
||
| 输入格式 | 仅支持 `.xls` 和 `.xlsx`，不支持 CSV/其他格式 |
|
||
| 输出格式 | 仅输出 `.xlsx`，不支持 `.xls` |
|
||
| 工作表 | 仅处理第一个工作表 |
|
||
| 公式单元格 | 仅读取公式的计算结果，不保留公式本身 |
|
||
| 命令行方向 | 命令行模式直接传入文件默认走 MAP→List，List→MAP 需交互式选择 |
|
||
|
||
---
|
||
|
||
### 未来计划
|
||
|
||
#### v1.3.0 — 格式增强（规划中）
|
||
|
||
- [ ] 支持 `.xls` 格式输出
|
||
- [ ] 保留原始 Excel 的字体和格式（MAP→List 方向）
|
||
- [ ] 支持多工作表选择
|
||
|
||
#### v1.4.0 — 功能扩展（规划中）
|
||
|
||
- [ ] 批量转换（拖拽多个文件）
|
||
- [ ] CSV 格式输出
|
||
- [ ] PinMAP 结构可视化预览
|
||
|
||
#### v2.0.0 — 架构升级（远期规划）
|
||
|
||
- [ ] 支持更多封装类型（BGA、QFN 等）
|
||
- [ ] 插件式解析器架构
|
||
- [ ] Web 界面
|
||
|
||
---
|
||
|
||
### 升级指南
|
||
|
||
**首次使用**：直接运行即可，无需升级。
|
||
|
||
**从 v1.0.0 升级**：替换 `Code/src/` 目录下所有文件。
|
||
|
||
**从 v1.1.0 升级**：替换 `Code/src/` 目录下所有文件。
|
||
|
||
---
|
||
|
||
### 贡献者
|
||
|
||
- 架构设计：Script Architect
|
||
- 编码实现：Coding Agent × 3
|
||
- 测试验证：QA Agent
|
||
- 文档编写：Doc Gen Agent
|
||
|
||
---
|
||
|
||
### 获取帮助
|
||
|
||
- 查看 `QUICKSTART.md` 了解使用方法
|
||
- 查看 `architecture-design.md` 了解技术细节
|
||
- 查看 `Test/test_report.md` 了解测试详情
|
||
|
||
---
|
||
|
||
## 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` 了解测试详情
|