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: 修改需求评估文档
This commit is contained in:
315
Releases/v1.0.1/docs/QUICKSTART.md
Normal file
315
Releases/v1.0.1/docs/QUICKSTART.md
Normal file
@@ -0,0 +1,315 @@
|
||||
# 快速入门指南
|
||||
|
||||
本文档帮助你快速上手 PinMAP → PinList 转换器。
|
||||
|
||||
---
|
||||
|
||||
## 环境要求
|
||||
|
||||
### 系统要求
|
||||
|
||||
| 项目 | 要求 |
|
||||
|------|------|
|
||||
| 操作系统 | Windows 7+ / Linux / macOS |
|
||||
| Python | 3.6+（推荐 3.8+） |
|
||||
| 内存 | ≥ 64MB（实际使用 < 20MB） |
|
||||
| 磁盘 | ≥ 1MB |
|
||||
|
||||
### 依赖项
|
||||
|
||||
**零第三方依赖** — 仅需 Python 标准库。
|
||||
|
||||
```bash
|
||||
# 检查 Python 版本
|
||||
python --version
|
||||
# 输出示例: Python 3.12.3
|
||||
```
|
||||
|
||||
### GUI 支持（可选）
|
||||
|
||||
- **Windows**: tkinter 内置，开箱即用
|
||||
- **Linux**: 需要 `python3-tk` 包（`sudo apt install python3-tk`）
|
||||
- **macOS**: tkinter 内置
|
||||
|
||||
> 无 GUI 环境时自动回退到命令行模式，不影响核心功能。
|
||||
|
||||
---
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 第一步：获取项目
|
||||
|
||||
```bash
|
||||
# 进入项目目录
|
||||
cd pinmap-to-pinlist/Code/src/
|
||||
```
|
||||
|
||||
### 第二步：运行转换
|
||||
|
||||
#### 方式一：GUI 模式（推荐）
|
||||
|
||||
```bash
|
||||
python main.py
|
||||
```
|
||||
|
||||
弹出文件选择对话框，选择 `.xls` 或 `.xlsx` 文件即可。
|
||||
|
||||
#### 方式二：命令行模式
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
**运行命令**：
|
||||
|
||||
```bash
|
||||
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 个引脚的长方形封装）
|
||||
|
||||
```bash
|
||||
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 环境下未提供命令行参数。
|
||||
|
||||
**解决**：
|
||||
```bash
|
||||
# 提供命令行参数
|
||||
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。
|
||||
|
||||
**解决**：使用命令行模式：
|
||||
```bash
|
||||
python main.py /path/to/input.xlsx
|
||||
```
|
||||
|
||||
如需 GUI，安装 tkinter：
|
||||
```bash
|
||||
sudo apt install python3-tk
|
||||
```
|
||||
|
||||
### Q8: 输出文件打不开
|
||||
|
||||
**可能原因**：Excel 版本过旧（2003 及以下不支持 .xlsx）。
|
||||
|
||||
**解决**：使用 Excel 2007+ 或 WPS Office 打开输出文件。
|
||||
|
||||
### Q9: 支持多大的 PinMAP？
|
||||
|
||||
**回答**：当前实现适合 < 1000 引脚的场景。典型 IC 封装引脚数在 8~200 之间，完全满足需求。
|
||||
|
||||
### Q10: 能否批量转换多个文件？
|
||||
|
||||
**回答**：当前版本一次处理一个文件。如需批量转换，可使用 shell 脚本：
|
||||
|
||||
```bash
|
||||
for f in *.xlsx; do
|
||||
python main.py "$f"
|
||||
done
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 测试验证
|
||||
|
||||
运行内置单元测试：
|
||||
|
||||
```bash
|
||||
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!
|
||||
```
|
||||
Reference in New Issue
Block a user