pinmap-to-pinlist/Code/docs/modification-assessment.md

PinMAP → PinList 转换器 — 修改需求评估

版本: v1.0
日期: 2026-05-25
评估人: 脚本架构师 (Script Architect)
状态: 待审批

---

1. 修改需求总览

编号	需求	优先级	复杂度
R1	增加交互提示（启动说明、详细日志、结果摘要）	高	低
R2	文件选择方式调整（路径输入 → 弹窗回退 → 报错重试）	高	低
R3	窗口属性（UTF-8 编码、固定窗口、颜色、署名、pause）	高	低

---

2. 逐项需求分析

2.1 需求 R1：增加交互提示

现状：

• 当前 main.py 启动即进入文件选择，无任何说明
• 日志输出已有 [INFO]、[WARN]、[ERROR]、[FATAL] 分级，但粒度不够细
• 转换完成后直接 return 退出，窗口瞬间关闭（双击 bat 运行时）

修改目标：

1. 启动 Banner：显示程序名称、功能说明、版本信息、署名
2. 详细日志：在 Excel 读取、PinMAP 解析、验证、生成、写入各阶段增加 [INFO] 日志
3. 结果摘要：转换完成后不立即退出，显示统计摘要，等待用户确认后退出

具体改动：

启动 Banner 示例：
╔══════════════════════════════════════════════════════════╗
║           PinMAP → PinList 转换器                        ║
║           自动将 Excel PinMAP 文件转换为 PinList          ║
║                                                          ║
║           版本: v1.0.1                                   ║
║           -By: LeeQwQ                                    ║
╚══════════════════════════════════════════════════════════╝

详细日志示例：
[INFO] 正在读取文件: C:\Users\test\sample_4x4.xlsx
[INFO] 文件读取完成，共 16 个非空单元格
[INFO] 正在解析 PinMAP 结构...
[INFO] 解析完成: 4x4 方形，共 12 个Pin
[INFO] 封装信息: QFN-12
[INFO] 正在验证数据...
[INFO] 验证通过，0 个错误，2 个警告
[INFO] 正在生成 PinList...
[INFO] 正在写入输出文件...
[SUCCESS] 转换完成！

结果摘要示例：
═══════════════════════════════════════════════════════════
  转换结果摘要
═══════════════════════════════════════════════════════════
  输入文件: C:\Users\test\sample_4x4.xlsx
  输出文件: C:\Users\test\sample_4x4_PinList.xlsx
  封装信息: QFN-12
  Pin 数量: 12
  错误数量: 0
  警告数量: 2
═══════════════════════════════════════════════════════════
  按任意键退出...

2.2 需求 R2：文件选择方式调整

现状：

• 当前 file_selector.py 的 select_file() 函数：
  • 有命令行参数 → 直接使用
  • 无命令行参数 → 直接弹出 tkinter 文件对话框
  • 无 GUI 环境 → 回退到命令行参数
• 问题：用户没有"输入路径"的机会，直接跳到了弹窗

修改目标： 新的文件选择流程：

┌─────────────────────────────────────────┐
│  1. 提示用户输入文件路径                  │
│     "请输入 PinMAP 文件路径: "            │
├─────────────────────────────────────────┤
│  2a. 用户输入了路径                      │
│     ├─ 路径存在？ → 使用该路径            │
│     └─ 路径不存在？ → 报错 + 返回步骤 1   │
│  2b. 用户直接回车（空输入）               │
│     → 弹出 tkinter 文件选择对话框        │
│     ├─ 选择了文件？ → 使用该路径          │
│     └─ 取消了？ → 返回 None             │
└─────────────────────────────────────────┘

具体改动：

• 修改 file_selector.py 中的 select_file() 函数
• 新增路径验证逻辑（os.path.exists() + 文件扩展名检查）
• 新增循环重试逻辑（路径不存在时提示重新输入，最多重试 N 次或无限重试）
• 保留 tkinter 弹窗作为空输入时的回退方案

2.3 需求 R3：窗口属性

现状：

• 项目没有 bat 启动脚本
• 用户通过 python main.py 或 python main.py input.xls 直接运行
• 窗口属性完全依赖用户 CMD 默认设置

修改目标： 创建 run.bat 作为标准启动入口，配置窗口属性。

bat 脚本内容：

@ECHO OFF
chcp 65001
title PinMAP转PinList -By:LeeQwQ
mode con cols=80 lines=20
color 0B
cls

python main.py %*

pause
EXIT

属性说明：

属性	命令	效果
编码	chcp 65001	设置 UTF-8 编码，正确显示中文
窗口标题	title PinMAP转PinList -By:LeeQwQ	固定署名
窗口大小	mode con cols=80 lines=20	80列 × 20行可见区域
颜色	color 0B	黑底(0) + 青字(B/浅蓝)
清屏	cls	启动时清除历史输出
暂停退出	pause	转换完成后等待按键

关于"支持往上滑看历史 log 输出信息"：

• mode con lines=20 设置的是可见窗口行数（20行），不是缓冲区大小
• Windows CMD 默认的屏幕缓冲区高度为 300 行
• 即使可见区域只有 20 行，用户仍可以通过鼠标滚轮或滚动条向上滚动查看历史输出
• 如果需要更大的缓冲区，可额外设置：mode con cols=80 lines=20 后，缓冲区默认 300 行已足够
• 如需显式指定缓冲区（可选）：可通过注册表或 mode con 的缓冲区参数，但通常不需要

关于"报错时重新输入（不退出）"：

• R2 的文件选择循环已覆盖此场景（路径不存在时返回重试）
• 其他阶段的错误（文件读取失败、结构错误等）仍会退出，但 pause 确保窗口不关闭，用户可以看到错误信息

---

3. 影响模块列表

模块	文件	影响程度	修改内容	关联需求
入口流程	src/main.py	高	增加启动 Banner、详细日志、结果摘要、任意键退出	R1, R3
文件选择	src/file_selector.py	高	重写 select_file()：路径输入 → 验证 → 弹窗回退 → 循环重试	R2
启动脚本	run.bat（新建）	中	创建 bat 启动脚本，配置窗口属性	R3
工具函数	src/utils.py	无	无需修改	—
数据模型	src/models.py	无	无需修改	—
Excel 读写	src/xls_reader.py src/xlsx_reader.py src/xlsx_writer.py	无	无需修改	—
PinMAP 解析	src/pinmap_parser.py	无	无需修改	—
数据验证	src/validator.py	无	无需修改	—
PinList 生成	src/pinlist_generator.py	无	无需修改	—

总结：仅需修改 2 个现有文件 + 新建 1 个 bat 脚本，其余 6 个核心业务模块完全不受影响。

---

4. 技术方案

4.1 R1 技术方案：交互提示

4.1.1 启动 Banner

在 main.py 的 main() 函数开头添加：

def show_banner():
    """显示程序启动 Banner"""
    print("=" * 56)
    print("          PinMAP → PinList 转换器")
    print("          自动将 Excel PinMAP 文件转换为 PinList")
    print()
    print("          版本: v1.0.1")
    print("          -By: LeeQwQ")
    print("=" * 56)
    print()

4.1.2 详细日志

在现有流程的每个阶段增加日志输出：

# 文件读取前
print(f"[INFO] 正在读取文件: {filepath}")

# 文件读取后
print(f"[INFO] 文件读取完成，共 {len(cells)} 个非空单元格")

# PinMAP 解析前
print(f"[INFO] 正在解析 PinMAP 结构...")

# 验证前
print(f"[INFO] 正在验证数据...")

# 验证后（已有）
print(f"[INFO] 验证通过，{len(validation.errors)} 个错误，{len(validation.warnings)} 个警告")

# 生成前
print(f"[INFO] 正在生成 PinList...")

# 写入前
print(f"[INFO] 正在写入输出文件: {output_path}")

4.1.3 结果摘要 + 任意键退出

在 main() 末尾（所有成功/失败分支）添加：

def show_summary(input_path, output_path, pinlist, validation):
    """显示转换结果摘要"""
    print()
    print("=" * 56)
    print("  转换结果摘要")
    print("=" * 56)
    print(f"  输入文件: {input_path}")
    print(f"  输出文件: {output_path}")
    print(f"  封装信息: {pinlist.package_info}")
    print(f"  Pin 数量: {len(pinlist.rows)}")
    print(f"  错误数量: {len(validation.errors)}")
    print(f"  警告数量: {len(validation.warnings)}")
    print("=" * 56)

def wait_for_exit():
    """等待用户按键后退出"""
    try:
        import msvcrt
        print("\n按任意键退出...")
        msvcrt.getch()  # Windows 专属，无需回车
    except ImportError:
        input("\n按 Enter 键退出...")  # 跨平台回退

技术要点：

• 使用 msvcrt.getch() 实现 Windows 上的"任意键退出"（无需按 Enter）
• 跨平台回退使用 input()
• 结果摘要仅在成功转换时显示；错误时直接显示错误信息 + 等待退出

4.2 R2 技术方案：文件选择方式调整

4.2.1 新的 select_file() 流程

def select_file() -> Optional[str]:
    """
    文件选择流程：
    1. 提示用户输入文件路径
    2. 空输入 → 弹出 tkinter 文件对话框
    3. 有输入但路径不存在 → 报错 + 重新输入
    4. 有输入且路径存在 → 返回路径
    """
    while True:
        # Step 1: 用户输入路径
        filepath = input("请输入 PinMAP 文件路径（直接回车使用文件选择器）: ").strip()
        
        # Step 2: 空输入 → 弹窗
        if not filepath:
            return _select_file_dialog()
        
        # Step 3: 路径验证
        if not os.path.exists(filepath):
            print(f"[ERROR] 文件不存在: {filepath}")
            print("请重新输入...")
            continue
        
        # Step 4: 扩展名检查
        if not filepath.lower().endswith(('.xls', '.xlsx')):
            print(f"[WARN] 文件扩展名不是 .xls 或 .xlsx，是否继续？")
            confirm = input("输入 Y 继续，其他键重新输入: ").strip().upper()
            if confirm != 'Y':
                continue
        
        return filepath

4.2.2 弹窗回退函数

def _select_file_dialog() -> Optional[str]:
    """弹出 tkinter 文件选择对话框"""
    try:
        import tkinter
        import tkinter.filedialog
        
        root = tkinter.Tk()
        root.withdraw()
        root.attributes("-topmost", True)
        
        filepath = tkinter.filedialog.askopenfilename(
            title="选择 PinMAP 文件",
            filetypes=[
                ("Excel 文件", "*.xls *.xlsx"),
                ("所有文件", "*.*"),
            ],
        )
        root.destroy()
        
        return str(filepath) if filepath else None
        
    except (ImportError, Exception):
        print("[ERROR] 无法打开文件选择器，请手动输入路径")
        return None

技术要点：

• 使用 while True 循环实现路径不存在时的重试
• 扩展名检查为 WARN 级别（允许用户强制继续）
• 弹窗回退函数独立封装，保持代码清晰

4.3 R3 技术方案：窗口属性

4.3.1 创建 run.bat

在项目根目录创建 run.bat：

@ECHO OFF
chcp 65001 >nul
title PinMAP转PinList -By:LeeQwQ
mode con cols=80 lines=20
color 0B
cls

python main.py %*

pause
EXIT

说明：

• chcp 65001 >nul：静默设置 UTF-8 编码，避免输出 Active code page: 65001 干扰界面
• %*：透传所有命令行参数（如 run.bat input.xls）
• pause：确保窗口不自动关闭
• EXIT：按键后退出 CMD

4.3.2 关于"支持往上滑看历史 log"

• Windows CMD 默认屏幕缓冲区高度为 300 行
• mode con lines=20 仅设置可见窗口为 20 行，不影响缓冲区
• 用户可通过鼠标滚轮或滚动条向上滚动查看完整日志历史
• 如需显式增大缓冲区（可选），可在 bat 中通过 PowerShell 设置，但通常 300 行已足够

4.3.3 关于"报错时重新输入（不退出）"

• R2 的文件选择循环已覆盖"路径不存在"场景
• 其他阶段报错（文件读取失败、结构错误等）会退出 main() 但被 pause 拦截
• 窗口不会关闭，用户可阅读错误信息后按任意键退出

---

5. 任务拆分建议

5.1 拆分方案

由于修改范围小（2 个文件 + 1 个新文件），建议不拆分，由单个编码 Agent 完成。

子任务	文件	预估工作量	依赖
T1: 交互提示	src/main.py	30 分钟	无
T2: 文件选择调整	src/file_selector.py	20 分钟	无
T3: 启动脚本	run.bat	5 分钟	无

总计预估：约 1 小时

5.2 推荐编码 Agent

Python 编码 Agent（单个 Agent 即可完成）

理由：

1. 修改不涉及核心业务逻辑（解析、验证、生成）
2. 纯 Python 标准库实现，无第三方依赖
3. bat 脚本简单，任何 Agent 均可完成
4. 拆分反而增加沟通成本

5.3 开发顺序

T2（文件选择） → T1（交互提示） → T3（启动脚本） → 集成测试

理由：T2 和 T1 都修改 main.py，建议先完成 T2（file_selector.py 独立），再合并 T1 到 main.py，避免冲突。

---

6. 风险评估

风险	影响	概率	缓解措施
msvcrt.getch() 在非 Windows 平台不可用	低	低	已设计跨平台回退（input()）
tkinter 在无 GUI 环境不可用	低	低	已设计回退到路径输入模式
mode con lines=20 窗口过小导致日志被截断	中	中	缓冲区默认 300 行，可滚动查看；如需调整可修改 lines 参数
用户输入路径含特殊字符（空格、中文）	低	中	Python os.path.exists() 和 Excel 读写引擎已支持 Unicode
bat 脚本中 python 命令不在 PATH 中	中	中	可在 bat 中使用 py 命令替代（Windows Python Launcher）

6.1 技术难点

无重大技术难点。所有需求均使用 Python 标准库实现：

• 交互提示：print() + input() + msvcrt
• 文件选择：os.path.exists() + tkinter.filedialog
• 窗口属性：bat 内置命令

6.2 兼容性考虑

场景	处理方式
双击 run.bat 运行	正常流程，窗口不关闭
run.bat input.xls 带参数	%* 透传，跳过文件选择
直接 python main.py（不用 bat）	交互提示仍生效，但窗口属性不生效（预期行为）
无 GUI 环境（服务器/远程桌面）	文件选择回退到路径输入模式
非 Windows 平台	msvcrt 回退到 input()，bat 不适用

---

7. 修改后目录结构

pinmap-to-pinlist/
├── Code/
│   ├── src/
│   │   ├── main.py                  # ✏️ 修改：增加 Banner、日志、摘要
│   │   ├── file_selector.py         # ✏️ 修改：重写 select_file()
│   │   ├── xls_reader.py            # （不变）
│   │   ├── xlsx_reader.py           # （不变）
│   │   ├── pinmap_parser.py         # （不变）
│   │   ├── validator.py             # （不变）
│   │   ├── pinlist_generator.py     # （不变）
│   │   ├── xlsx_writer.py           # （不变）
│   │   ├── models.py                # （不变）
│   │   └── utils.py                 # （不变）
│   └── docs/
│       ├── architecture-design.md   # （不变）
│       └── modification-assessment.md  # 🆕 本文档
├── run.bat                          # 🆕 新建：启动脚本
├── Test/
└── Releases/

---

8. 总结

项目	内容
修改文件数	2 个现有 + 1 个新建
影响核心模块	无（仅修改入口和文件选择）
技术难度	低
预估工作量	~1 小时
推荐 Agent	Python 编码 Agent（单个）
风险等级	低

结论：修改需求清晰、范围可控、无技术难点，建议直接分配给单个编码 Agent 执行。

---

文档结束 — 请审批后进入编码阶段