GoudanLabs/pinmap-to-pinlist

Fork 0

Files

Agent d8d669bba1 docs: v1.5.0 - 更新模板分离与格式提取文档

2026-06-06 12:52:12 +08:00

16 KiB

Raw Blame History

版本发布说明

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 个测试用例

技术实现

模板查找逻辑

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 了解测试详情

16 KiB Raw Blame History Unescape Escape

版本发布说明

v1.5.0 — 2026-06-06

✨ 模板分离与格式提取增强

新增功能

F009：MAP→List 使用 BallList-Template（独立模板）

F010：List→MAP 使用 BallMAP-Template（独立模板）

F011：模板格式提取式应用

F012：上/下边 PinName 位置回归测试

修改文件

技术实现

模板查找逻辑

样式提取式应用

测试覆盖

F012 回归测试

F011 模板格式提取测试

已知问题

限制

升级指南

贡献者

获取帮助

v1.2.0 — 2026-05-28

✨ 新增 PinList → PinMAP 反向转换

新增功能

PinList → PinMAP 转换

模板样式引擎

交互式方向选择

数据验证增强

新增模块

更新模块

技术实现

布局算法

坐标映射

模板样式提取

测试覆盖

单元测试（8 个用例）

集成测试（6 个用例）

已知问题

限制

未来计划

v1.3.0 — 格式增强（规划中）

v1.4.0 — 功能扩展（规划中）

v2.0.0 — 架构升级（远期规划）

升级指南

贡献者

获取帮助

v1.0.0 — 2026-05-25

🎉 首次发布

新增功能

PinMAP 解析

数据验证

PinList 生成

格式支持

运行模式

技术实现

测试覆盖

单元测试（8 个用例）

集成测试（6 个用例）

已知问题

限制

未来计划

v1.1.0 — 格式增强（规划中）

v1.2.0 — 功能扩展（规划中）

v2.0.0 — 架构升级（远期规划）

升级指南

贡献者

获取帮助

16 KiB

Raw Blame History