v1.0.1: 新增完整文档体系（README/QUICKSTART/RELEASE）

Code/docs/QUICKSTART.md

@@ -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!
+```