11 KiB
11 KiB
版本发布说明
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了解测试详情