Files

Agent 836ad20515 v1.1.0: 增加交互提示、路径输入、窗口属性配置

- main.py: 增加show_banner()启动说明、各阶段[INFO]日志、结果摘要、任意键退出
- file_selector.py: 重写为路径输入→验证→空输入弹窗回退→不存在循环重试
- run.bat: 新建启动脚本(chcp 65001, mode con cols=80 lines=20, color 0B, title固定署名, pause)
- Code/docs/modification-assessment.md: 修改需求评估文档

2026-05-25 17:29:19 +08:00

6.5 KiB

Raw Blame History

快速入门指南

本文档帮助你快速上手 PinMAP → PinList 转换器。

环境要求

系统要求

项目	要求
操作系统	Windows 7+ / Linux / macOS
Python	3.6+（推荐 3.8+）
内存	≥ 64MB（实际使用 < 20MB）
磁盘	≥ 1MB

依赖项

零第三方依赖 — 仅需 Python 标准库。

# 检查 Python 版本
python --version
# 输出示例: Python 3.12.3

GUI 支持（可选）

Windows: tkinter 内置，开箱即用
Linux: 需要 python3-tk 包（sudo apt install python3-tk）
macOS: tkinter 内置

无 GUI 环境时自动回退到命令行模式，不影响核心功能。

快速开始

第一步：获取项目

# 进入项目目录
cd pinmap-to-pinlist/Code/src/

第二步：运行转换

方式一：GUI 模式（推荐）

python main.py

弹出文件选择对话框，选择 .xls 或 .xlsx 文件即可。

方式二：命令行模式

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

运行命令：

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 个引脚的长方形封装）

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 环境下未提供命令行参数。

解决：

# 提供命令行参数
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。

解决：使用命令行模式：

python main.py /path/to/input.xlsx

如需 GUI，安装 tkinter：

sudo apt install python3-tk

Q8: 输出文件打不开

可能原因：Excel 版本过旧（2003 及以下不支持 .xlsx）。

解决：使用 Excel 2007+ 或 WPS Office 打开输出文件。

Q9: 支持多大的 PinMAP？

回答：当前实现适合 < 1000 引脚的场景。典型 IC 封装引脚数在 8~200 之间，完全满足需求。

Q10: 能否批量转换多个文件？

回答：当前版本一次处理一个文件。如需批量转换，可使用 shell 脚本：

for f in *.xlsx; do
    python main.py "$f"
done

测试验证

运行内置单元测试：

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!

6.5 KiB Raw Blame History Unescape Escape