v1.3.0: 修复pinmap_layout周长公式，新增PinList→PinMAP反向转换完整支持
This commit is contained in:
8
docs/bugs.md
Normal file
8
docs/bugs.md
Normal file
@@ -0,0 +1,8 @@
|
||||
# Bug 跟踪表
|
||||
|
||||
| Bug ID | 严重程度 | Bug 描述 | 复现步骤 | 期望行为 | 实际行为 | 状态 | 关联功能 |
|
||||
|--------|---------|---------|---------|---------|---------|------|---------|
|
||||
| BUG-001 | 中 | run.bat 换行符 + lines 设置不匹配 Windows | 在 Windows 下运行 run.bat | CRLF 换行，仅保留 `mode con cols=80` | Unix LF 换行，包含多余 `lines=50` | 已修复 | F005 |
|
||||
| BUG-002 | 高 | 周长计算公式错误 | 输入 15×15 网格 + 60 Pin | 验证通过 `(rows+cols)*2=60` | 提示不匹配 `2*rows+2*cols-4=56` | 已修复 | F006 |
|
||||
| BUG-003 | 中 | 双向转换未读取模板样式 | 使用模板文件进行 MAP↔List 转换 | 读取并应用模板样式 | 使用默认样式 | 已修复 | F007 |
|
||||
| BUG-004 | 中 | 不支持循环处理流程 | 转换完成后继续操作 | 循环等待下一个文件，输入 Q 返回主菜单 | 处理完直接退出 | 已修复 | F008 |
|
||||
31
docs/features.md
Normal file
31
docs/features.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# 功能清单
|
||||
|
||||
## 核心功能
|
||||
|
||||
| 功能 ID | 功能名称 | 描述 | 输入 | 输出 | 依赖 | 优先级 | 验收标准 | 审批状态 |
|
||||
|--------|---------|------|------|------|------|--------|---------|---------|
|
||||
| F001 | PinMAP 解析 | 解析 PinMAP Excel 文件 | Excel 文件 | 解析后的 Pin 数据 | 无 | 1 | 能正确解析 PinMAP 结构 | 已通过 |
|
||||
| F002 | PinList 生成 | 从 PinMAP 生成 PinList | Pin 数据 | PinList Excel 文件 | F001 | 2 | 能正确生成 PinList | 已通过 |
|
||||
| F003 | PinList 解析 | 解析 PinList Excel 文件 | Excel 文件 | 解析后的 Pin 数据 | 无 | 1 | 能正确解析 PinList 结构 | 已通过 |
|
||||
| F004 | PinMAP 生成 | 从 PinList 生成 PinMAP | Pin 数据 | PinMAP Excel 文件 | F003 | 2 | 能正确生成 PinMAP | 已通过 |
|
||||
|
||||
## Bug 修复
|
||||
|
||||
| 功能 ID | 功能名称 | 描述 | 输入 | 输出 | 依赖 | 优先级 | 验收标准 | 审批状态 |
|
||||
|--------|---------|------|------|------|------|--------|---------|---------|
|
||||
| F005 | BAT 脚本修复 | 修复 run.bat 换行符为 CRLF，去掉 lines=50 参数 | 无 | 修复后的 run.bat | 无 | 3 | Windows 下正常运行 | 已通过 |
|
||||
| F006 | 周长公式修复 | 将周长公式从 `2*rows+2*cols-4` 改为 `(rows+cols)*2` | rows, cols | 正确的周长值 | 无 | 1 | 15×15 网格 60Pin 验证通过 | 已通过 |
|
||||
|
||||
## 功能增强
|
||||
|
||||
| 功能 ID | 功能名称 | 描述 | 输入 | 输出 | 依赖 | 优先级 | 验收标准 | 审批状态 |
|
||||
|--------|---------|------|------|------|------|--------|---------|---------|
|
||||
| F007 | 模板读取 | MAP→List 和 List→MAP 双向转换均读取并应用模板样式 | 模板文件 | 带样式的输出文件 | 无 | 2 | 双向转换均应用模板样式 | 已通过 |
|
||||
| F008 | 循环处理流程 | 处理完不退出，循环等待下一个文件，输入 Q 返回主菜单 | 用户输入 | 循环处理或返回主菜单 | 无 | 2 | 处理完不退出，Q 返回主菜单 | 已通过 |
|
||||
|
||||
## 优先级排序
|
||||
|
||||
1. **P0（必须）**：F006 周长公式修复 — 核心逻辑错误
|
||||
2. **P1（重要）**：F005 BAT 脚本修复 — 影响 Windows 用户使用
|
||||
3. **P2（建议）**：F007 模板读取 — 功能增强
|
||||
4. **P2（建议）**：F008 循环处理流程 — 体验优化
|
||||
621
docs/modification-assessment-v1.3.md
Normal file
621
docs/modification-assessment-v1.3.md
Normal file
@@ -0,0 +1,621 @@
|
||||
# PinMAP ↔ PinList 双向转换器 — 修改需求评估 v1.3
|
||||
|
||||
> **版本**: v1.3
|
||||
> **日期**: 2026-05-31
|
||||
> **评估人**: 脚本架构师 (Script Architect)
|
||||
> **状态**: 待审批
|
||||
> **变更**: 4 个 Bug 修复 + 4 个功能增强（BUG-001~004, F005~F008）
|
||||
|
||||
---
|
||||
|
||||
## 1. 修改需求总览
|
||||
|
||||
| 编号 | 类型 | 标题 | 优先级 | 复杂度 | 关联需求 |
|
||||
|------|------|------|--------|--------|---------|
|
||||
| BUG-001 | Bug | run.bat 换行符 + lines 设置不匹配 Windows | 中 | 低 | F005 |
|
||||
| BUG-002 | Bug | 周长计算公式错误 | **高** | 中 | F006 |
|
||||
| BUG-003 | Bug | 双向转换未读取模板样式 | 中 | 中 | F007 |
|
||||
| BUG-004 | Bug | 不支持循环处理流程 | 中 | 中 | F008 |
|
||||
| F005 | 功能 | BAT 脚本修复 | 3 | 低 | BUG-001 |
|
||||
| F006 | 功能 | 周长公式修复 | **1** | 中 | BUG-002 |
|
||||
| F007 | 功能 | 模板读取（双向） | 2 | 中 | BUG-003 |
|
||||
| F008 | 功能 | 循环处理流程 | 2 | 中 | BUG-004 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 当前代码状态分析
|
||||
|
||||
### 2.1 代码库结构（v1.2.0）
|
||||
|
||||
```
|
||||
pinmap-to-pinlist/
|
||||
├── run.bat # ✏️ 需修改（BUG-001/F005）
|
||||
├── Code/src/
|
||||
│ ├── main.py # ✏️ 需修改（BUG-003/F007, BUG-004/F008）
|
||||
│ ├── file_selector.py # （不变）
|
||||
│ ├── validator.py # ✏️ 需修改（BUG-002/F006）
|
||||
│ ├── pinlist_validator.py # ✏️ 需修改（BUG-002/F006）
|
||||
│ ├── pinmap_layout.py # ✏️ 需修改（BUG-002/F006）
|
||||
│ ├── pinlist_parser.py # （不变）
|
||||
│ ├── pinmap_generator.py # （不变）
|
||||
│ ├── template_reader.py # （不变）
|
||||
│ ├── xlsx_writer.py # （不变）
|
||||
│ ├── models.py # （不变）
|
||||
│ ├── xls_reader.py # （不变）
|
||||
│ ├── xlsx_reader.py # （不变）
|
||||
│ ├── pinlist_generator.py # （不变）
|
||||
│ └── utils.py # （不变）
|
||||
└── docs/
|
||||
├── bugs.md # ✏️ 需更新状态
|
||||
├── features.md # ✏️ 需更新状态
|
||||
└── modification-assessment-v1.3.md # 🆕 本文档
|
||||
```
|
||||
|
||||
### 2.2 各 Bug 当前代码状态
|
||||
|
||||
#### BUG-001: run.bat 问题
|
||||
|
||||
**当前 run.bat 内容**：
|
||||
```bat
|
||||
@ECHO OFF
|
||||
chcp 65001 >nul
|
||||
title PinMAP转PinList -By:LeeQwQ
|
||||
mode con cols=80 lines=50 ← 问题：含 lines=50
|
||||
color 0B
|
||||
cls
|
||||
cd /d "%~dp0Code\src"
|
||||
python main.py
|
||||
echo.
|
||||
pause
|
||||
EXIT
|
||||
```
|
||||
|
||||
**问题 1**：文件使用 Unix LF 换行符（`\n`），Windows 下应使用 CRLF（`\r\n`）。
|
||||
**问题 2**：`mode con cols=80 lines=50` 中的 `lines=50` 是多余的，需求仅保留 `cols=80`。
|
||||
|
||||
---
|
||||
|
||||
#### BUG-002: 周长公式错误
|
||||
|
||||
**当前公式**（3 处代码）：
|
||||
```
|
||||
expected_total = 2 * rows + 2 * cols - 4
|
||||
```
|
||||
|
||||
**问题**：对于 15×15 网格 + 60 Pin，当前公式计算为 `2*15+2*15-4 = 56`，但用户期望 `(15+15)*2 = 60`。
|
||||
|
||||
**涉及文件**：
|
||||
1. `Code/src/pinlist_validator.py` — `validate_pinlist()` 中的周长匹配检查
|
||||
2. `Code/src/validator.py` — `validate_pinlist_for_map()` 中的周长匹配检查
|
||||
3. `Code/src/pinmap_layout.py` — `calculate_layout()` 中的 `total` 计算和 `LayoutError`
|
||||
|
||||
**数学分析**：
|
||||
|
||||
| 网格 | 当前公式 `2r+2c-4` | 新公式 `(r+c)*2` | 说明 |
|
||||
|------|-------------------|-----------------|------|
|
||||
| 4×8 | 20 | 24 | 当前公式少算 4 |
|
||||
| 15×15 | 56 | 60 | 当前公式少算 4 |
|
||||
| 2×2 | 4 | 8 | 当前公式少算 4 |
|
||||
|
||||
新公式 `(rows+cols)*2` 对所有尺寸均多 4 个 Pin。这意味着布局分配算法也需要相应调整。
|
||||
|
||||
**布局分配需同步修改**：
|
||||
|
||||
当前分配（`pinmap_layout.py`）：
|
||||
```
|
||||
左边: rows 个
|
||||
下边: cols-1 个
|
||||
右边: rows-2 个
|
||||
上边: cols-1 个
|
||||
总计: 2*rows + 2*cols - 4
|
||||
```
|
||||
|
||||
新分配（`(rows+cols)*2`）：
|
||||
```
|
||||
左边: rows 个
|
||||
下边: cols 个
|
||||
右边: rows 个
|
||||
上边: cols 个
|
||||
总计: 2*rows + 2*cols
|
||||
```
|
||||
|
||||
这意味着四个角点不再共享，每个角点归属一条边。需重新设计单元格坐标计算逻辑。
|
||||
|
||||
---
|
||||
|
||||
#### BUG-003: 模板读取路径错误
|
||||
|
||||
**当前代码**（`main.py` → `run_list_to_map()`）：
|
||||
```python
|
||||
template_style = read_template_styles(filepath)
|
||||
```
|
||||
|
||||
**问题**：`filepath` 是用户选择的 PinList 输入文件路径，而非模板文件路径。模板文件应为根目录下的 `PinMAP-Template.xlsx`。
|
||||
|
||||
**MAP→List 方向**（`run_map_to_list()`）：
|
||||
当前代码未调用 `read_template_styles()`，PinList 输出直接使用 `write_xlsx()`（无样式）。
|
||||
|
||||
**需要修复**：
|
||||
1. List→MAP：将 `read_template_styles(filepath)` 改为读取根目录模板
|
||||
2. MAP→List：增加模板读取和样式应用
|
||||
|
||||
---
|
||||
|
||||
#### BUG-004: 无循环处理流程
|
||||
|
||||
**当前 `main()` 流程**：
|
||||
```python
|
||||
def main():
|
||||
show_banner()
|
||||
# 选择方向 → 执行一次转换 → wait_for_exit() → 程序结束
|
||||
```
|
||||
|
||||
**问题**：转换完成后直接退出，用户需重新运行程序才能处理下一个文件。
|
||||
|
||||
**期望流程**：
|
||||
```
|
||||
启动 → 选择方向 → 处理文件 → [处理完成] → 等待输入下一个文件 / Q 返回主菜单
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 逐项修改方案
|
||||
|
||||
---
|
||||
|
||||
### 3.1 BUG-001 / F005: BAT 脚本修复
|
||||
|
||||
**修改范围**：`run.bat`（1 个文件）
|
||||
|
||||
**具体修改**：
|
||||
|
||||
1. **换行符**：确保文件使用 CRLF（`\r\n`）换行。写入文件时指定 `newline='\r\n'`。
|
||||
2. **去掉 lines=50**：将 `mode con cols=80 lines=50` 改为 `mode con cols=80`。
|
||||
|
||||
**修改后 run.bat**：
|
||||
```bat
|
||||
@ECHO OFF
|
||||
chcp 65001 >nul
|
||||
title PinMAP转PinList -By:LeeQwQ
|
||||
mode con cols=80
|
||||
color 0B
|
||||
cls
|
||||
|
||||
cd /d "%~dp0Code\src"
|
||||
python main.py
|
||||
|
||||
echo.
|
||||
pause
|
||||
EXIT
|
||||
```
|
||||
|
||||
**风险评估**：
|
||||
| 风险 | 影响 | 概率 | 缓解措施 |
|
||||
|------|------|------|---------|
|
||||
| CRLF 写入失败 | 低 | 极低 | Python `open(path, 'w', newline='\r\n')` 保证 |
|
||||
| 去掉 lines 后窗口行数变回默认 | 低 | 确认 | 默认 300 行缓冲区，足够查看日志 |
|
||||
|
||||
**工作量**：5 分钟
|
||||
|
||||
---
|
||||
|
||||
### 3.2 BUG-002 / F006: 周长公式修复
|
||||
|
||||
**修改范围**：3 个文件
|
||||
|
||||
| 文件 | 修改内容 | 修改行数 |
|
||||
|------|---------|---------|
|
||||
| `pinlist_validator.py` | 周长匹配公式 + 错误提示文案 | ~5 行 |
|
||||
| `validator.py` | `validate_pinlist_for_map()` 周长公式 | ~5 行 |
|
||||
| `pinmap_layout.py` | 边分配计数 + 单元格坐标计算 | ~20 行 |
|
||||
|
||||
**具体修改**：
|
||||
|
||||
#### 3.2.1 `pinlist_validator.py` — `validate_pinlist()`
|
||||
|
||||
```python
|
||||
# 修改前：
|
||||
expected_total = 2 * rows + 2 * cols - 4
|
||||
|
||||
# 修改后：
|
||||
expected_total = (rows + cols) * 2
|
||||
```
|
||||
|
||||
#### 3.2.2 `validator.py` — `validate_pinlist_for_map()`
|
||||
|
||||
```python
|
||||
# 修改前：
|
||||
expected_total = 2 * rows + 2 * cols - 4
|
||||
|
||||
# 修改后：
|
||||
expected_total = (rows + cols) * 2
|
||||
```
|
||||
|
||||
#### 3.2.3 `pinmap_layout.py` — `calculate_layout()`
|
||||
|
||||
**边分配计数修改**：
|
||||
```python
|
||||
# 修改前：
|
||||
left_count = rows
|
||||
bottom_count = cols - 1
|
||||
right_count = rows - 2
|
||||
top_count = cols - 1
|
||||
# total = 2*rows + 2*cols - 4
|
||||
|
||||
# 修改后：
|
||||
left_count = rows
|
||||
bottom_count = cols
|
||||
right_count = rows
|
||||
top_count = cols
|
||||
# total = 2*rows + 2*cols
|
||||
```
|
||||
|
||||
**单元格坐标计算修改**：
|
||||
|
||||
```python
|
||||
# 修改前（角点共享）：
|
||||
# 左边: (r, 0) r ∈ [1, rows]
|
||||
# 下边: (rows, c) c ∈ [1, cols-1]
|
||||
# 右边: (r, cols) r ∈ [rows-1, 2] 逆序
|
||||
# 上边: (1, c) c ∈ [cols-1, 2] 逆序
|
||||
|
||||
# 修改后（角点不共享，每条边独立）：
|
||||
# 左边: (r, 0) r ∈ [1, rows]
|
||||
# 下边: (rows, c) c ∈ [1, cols]
|
||||
# 右边: (r, cols) r ∈ [rows, 1] 逆序
|
||||
# 上边: (1, c) c ∈ [cols, 1] 逆序
|
||||
```
|
||||
|
||||
```python
|
||||
# 修改后代码：
|
||||
left_cells = [(r, 0) for r in range(1, rows + 1)]
|
||||
bottom_cells = [(rows, c) for c in range(1, cols + 1)]
|
||||
right_cells = [(r, cols) for r in range(rows, 0, -1)]
|
||||
top_cells = [(1, c) for c in range(cols, 0, -1)]
|
||||
```
|
||||
|
||||
**`get_name_cell()` 函数修改**：
|
||||
|
||||
```python
|
||||
# 修改前：
|
||||
# left: (r, c+1)
|
||||
# bottom: (r-1, c)
|
||||
# right: (r, c-1)
|
||||
# top: (r+1, c)
|
||||
|
||||
# 修改后：逻辑不变（Name 单元格相对于序号单元格的位置不变）
|
||||
# 但需确保角点单元格 Name 不冲突
|
||||
```
|
||||
|
||||
**风险评估**：
|
||||
| 风险 | 影响 | 概率 | 缓解措施 |
|
||||
|------|------|------|---------|
|
||||
| 布局算法修改引入新 Bug | **高** | 中 | 对 4×8、15×15、2×2 等典型尺寸做单元测试 |
|
||||
| 角点单元格 Name 重叠 | 中 | 中 | 修改 `get_name_cell()` 确保角点 Name 不冲突 |
|
||||
| 已有用户数据不兼容 | 低 | 低 | 用户需重新输入正确的 PinList |
|
||||
| 修改 3 个文件不一致 | 中 | 低 | 使用同一公式常量，避免硬编码 |
|
||||
|
||||
**工作量**：1.5 小时
|
||||
|
||||
---
|
||||
|
||||
### 3.3 BUG-003 / F007: 模板读取修复
|
||||
|
||||
**修改范围**：1 个文件（`main.py`）
|
||||
|
||||
**问题根因**：
|
||||
1. List→MAP：`read_template_styles(filepath)` 传入的是输入文件路径，而非模板路径
|
||||
2. MAP→List：完全没有模板读取逻辑
|
||||
|
||||
**具体修改**：
|
||||
|
||||
#### 3.3.1 新增模板路径解析辅助函数
|
||||
|
||||
```python
|
||||
def _find_template_path() -> str | None:
|
||||
"""查找根目录下的 PinMAP-Template.xlsx。
|
||||
|
||||
搜索顺序：
|
||||
1. 与 run.bat 同级的根目录
|
||||
2. 当前工作目录
|
||||
"""
|
||||
# 尝试从 Code/src 回退到根目录
|
||||
src_dir = os.path.dirname(os.path.abspath(__file__))
|
||||
root_dir = os.path.dirname(os.path.dirname(src_dir)) # pinmap-to-pinlist/
|
||||
template_path = os.path.join(root_dir, "PinMAP-Template.xlsx")
|
||||
|
||||
if os.path.exists(template_path):
|
||||
return template_path
|
||||
|
||||
# 回退到当前工作目录
|
||||
cwd_template = os.path.join(os.getcwd(), "PinMAP-Template.xlsx")
|
||||
if os.path.exists(cwd_template):
|
||||
return cwd_template
|
||||
|
||||
return None
|
||||
```
|
||||
|
||||
#### 3.3.2 修改 `run_list_to_map()`
|
||||
|
||||
```python
|
||||
# 修改前：
|
||||
template_style = read_template_styles(filepath)
|
||||
|
||||
# 修改后：
|
||||
template_path = _find_template_path()
|
||||
if template_path:
|
||||
template_style = read_template_styles(template_path)
|
||||
if template_style:
|
||||
print(f"[INFO] 已加载模板样式: {template_path}")
|
||||
else:
|
||||
print("[WARN] 模板文件存在但解析失败，使用默认样式")
|
||||
else:
|
||||
template_style = None
|
||||
print("[INFO] 未检测到模板文件，使用默认样式")
|
||||
```
|
||||
|
||||
#### 3.3.3 修改 `run_map_to_list()`
|
||||
|
||||
```python
|
||||
# 在写入 PinList 之前，增加模板读取逻辑：
|
||||
template_path = _find_template_path()
|
||||
template_style = None
|
||||
if template_path:
|
||||
template_style = read_template_styles(template_path)
|
||||
if template_style:
|
||||
print(f"[INFO] 已加载模板样式: {template_path}")
|
||||
|
||||
# 写入时：
|
||||
if template_style is not None:
|
||||
write_xlsx_with_style(data, output_path, template_style)
|
||||
else:
|
||||
write_xlsx(data, output_path)
|
||||
```
|
||||
|
||||
**风险评估**：
|
||||
| 风险 | 影响 | 概率 | 缓解措施 |
|
||||
|------|------|------|---------|
|
||||
| 模板路径解析错误 | 中 | 低 | 多路径回退 + 优雅降级 |
|
||||
| 模板解析失败导致崩溃 | 低 | 低 | `template_reader.py` 已有 try-except 优雅降级 |
|
||||
| MAP→List 应用模板样式后 PinList 格式不符合用户预期 | 中 | 低 | 模板仅影响样式（字体/边框），不影响数据 |
|
||||
|
||||
**工作量**：1 小时
|
||||
|
||||
---
|
||||
|
||||
### 3.4 BUG-004 / F008: 循环处理流程
|
||||
|
||||
**修改范围**：1 个文件（`main.py`）
|
||||
|
||||
**具体修改**：
|
||||
|
||||
将 `main()` 改造为循环结构：
|
||||
|
||||
```python
|
||||
def main():
|
||||
show_banner()
|
||||
|
||||
while True:
|
||||
# ── Direction selection ───────────────────────────────
|
||||
if len(sys.argv) > 1:
|
||||
# Legacy mode: 直接文件参数 → MAP→List → 循环
|
||||
direction = 1
|
||||
filepath = sys.argv[1]
|
||||
sys.argv = [sys.argv[0]] # 清除 argv，下次循环进入交互模式
|
||||
else:
|
||||
print("请选择转换方向:")
|
||||
print(" 1 — PinMAP → PinList")
|
||||
print(" 2 — PinList → PinMAP")
|
||||
print(" Q — 退出程序")
|
||||
print()
|
||||
|
||||
choice = input("请输入选项 (1/2/Q): ").strip().upper()
|
||||
if choice == 'Q':
|
||||
print("感谢使用，再见！")
|
||||
return
|
||||
elif choice == '1':
|
||||
direction = 1
|
||||
elif choice == '2':
|
||||
direction = 2
|
||||
else:
|
||||
print("[ERROR] 无效选项，请输入 1、2 或 Q")
|
||||
continue
|
||||
|
||||
filepath = None
|
||||
|
||||
# ── Dispatch ──────────────────────────────────────────
|
||||
if direction == 1:
|
||||
print()
|
||||
print("─" * 40)
|
||||
print(" 方向: PinMAP → PinList")
|
||||
print("─" * 40)
|
||||
print()
|
||||
run_map_to_list(filepath)
|
||||
else:
|
||||
print()
|
||||
print("─" * 40)
|
||||
print(" 方向: PinList → PinMAP")
|
||||
print("─" * 40)
|
||||
print()
|
||||
run_list_to_map(filepath)
|
||||
|
||||
# ── 处理完成后循环 ────────────────────────────────────
|
||||
print()
|
||||
print("=" * 40)
|
||||
next_action = input("输入文件名继续处理，或按 Enter 返回主菜单，输入 Q 退出: ").strip()
|
||||
if next_action.upper() == 'Q':
|
||||
print("感谢使用，再见！")
|
||||
return
|
||||
elif next_action:
|
||||
# 直接处理指定文件（自动检测方向）
|
||||
filepath = next_action
|
||||
# 根据文件内容自动判断方向，或默认 MAP→List
|
||||
direction = 1
|
||||
else:
|
||||
# 返回主菜单（继续 while 循环）
|
||||
pass
|
||||
```
|
||||
|
||||
**同时需要修改 `run_map_to_list()` 和 `run_list_to_map()`**：
|
||||
|
||||
将两个函数末尾的 `wait_for_exit()` 替换为 `input("按 Enter 键继续...")`，这样处理完成后用户可以继续操作而不是退出。
|
||||
|
||||
```python
|
||||
# 修改前（两处）：
|
||||
wait_for_exit()
|
||||
|
||||
# 修改后：
|
||||
input("按 Enter 键继续...")
|
||||
```
|
||||
|
||||
**但注意**：`wait_for_exit()` 仍保留，用于：
|
||||
- 致命错误（FATAL）时的退出
|
||||
- 用户未选择文件时的退出
|
||||
- 命令行参数模式下最后一次退出
|
||||
|
||||
**风险评估**：
|
||||
| 风险 | 影响 | 概率 | 缓解措施 |
|
||||
|------|------|------|---------|
|
||||
| 循环导致内存泄漏（模块重复 import） | 低 | 低 | Python import 有缓存，重复 import 无开销 |
|
||||
| 用户输入 Q 后状态混乱 | 中 | 低 | Q 只在主菜单和处理完成后接受，转换过程中不响应 |
|
||||
| 命令行参数模式与循环模式冲突 | 中 | 中 | 命令行参数模式执行一次后清除 argv，进入交互循环 |
|
||||
|
||||
**工作量**：1 小时
|
||||
|
||||
---
|
||||
|
||||
## 4. 修改影响矩阵
|
||||
|
||||
| 文件 | BUG-001 | BUG-002 | BUG-003 | BUG-004 | 总改动量 |
|
||||
|------|---------|---------|---------|---------|---------|
|
||||
| `run.bat` | ✏️ 换行+CRLF, 去lines | | | | 2 行 |
|
||||
| `main.py` | | | ✏️ 模板路径 | ✏️ 循环流程 | ~40 行 |
|
||||
| `pinlist_validator.py` | | ✏️ 公式 | | | ~5 行 |
|
||||
| `validator.py` | | ✏️ 公式 | | | ~5 行 |
|
||||
| `pinmap_layout.py` | | ✏️ 公式+布局 | | | ~20 行 |
|
||||
| **合计** | **1 文件** | **3 文件** | **1 文件** | **1 文件** | **5 文件** |
|
||||
|
||||
---
|
||||
|
||||
## 5. 优先级排序
|
||||
|
||||
| 优先级 | 编号 | 原因 |
|
||||
|--------|------|------|
|
||||
| **P0** | BUG-002 / F006 | 核心公式错误，所有 List→MAP 转换均受影响 |
|
||||
| **P1** | BUG-001 / F005 | 影响 Windows 用户体验，修复简单 |
|
||||
| **P2** | BUG-003 / F007 | 功能增强，模板样式对输出质量有影响 |
|
||||
| **P2** | BUG-004 / F008 | 体验优化，批量处理场景需要 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 工作量估算
|
||||
|
||||
| 任务 | 文件 | 预估时间 | 依赖 |
|
||||
|------|------|---------|------|
|
||||
| BUG-001/F005 | `run.bat` | 5 分钟 | 无 |
|
||||
| BUG-002/F006 | `pinlist_validator.py`, `validator.py`, `pinmap_layout.py` | 1.5 小时 | 无 |
|
||||
| BUG-003/F007 | `main.py` | 1 小时 | 无 |
|
||||
| BUG-004/F008 | `main.py` | 1 小时 | 无 |
|
||||
| 文档更新 | `bugs.md`, `features.md` | 10 分钟 | 无 |
|
||||
|
||||
**总计预估**：约 3 小时
|
||||
|
||||
---
|
||||
|
||||
## 7. 推荐开发顺序
|
||||
|
||||
```
|
||||
第1轮（独立，可并行）：
|
||||
BUG-001/F005: BAT 脚本修复（5 分钟，任何 Agent）
|
||||
|
||||
第2轮（核心，必须最先）：
|
||||
BUG-002/F006: 周长公式修复（1.5 小时，需理解布局算法）
|
||||
|
||||
第3轮（独立）：
|
||||
BUG-003/F007: 模板读取修复（1 小时）
|
||||
BUG-004/F008: 循环处理流程（1 小时）
|
||||
（两者都修改 main.py，建议先后执行避免冲突）
|
||||
|
||||
第4轮（收尾）：
|
||||
文档更新：bugs.md + features.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 验收标准
|
||||
|
||||
### 8.1 BUG-001 / F005 验收
|
||||
|
||||
| 验收项 | 方法 | 预期结果 |
|
||||
|--------|------|---------|
|
||||
| run.bat 使用 CRLF 换行 | 二进制查看文件 | 每行末尾为 `\r\n` |
|
||||
| 不含 `lines=` 参数 | 文本搜索 | 无 `lines=` 字符串 |
|
||||
| 仅含 `mode con cols=80` | 文本搜索 | 仅一行 `mode con cols=80` |
|
||||
| Windows 下双击运行正常 | 实际运行 | 窗口正常打开，中文显示正确 |
|
||||
|
||||
### 8.2 BUG-002 / F006 验收
|
||||
|
||||
| 验收项 | 方法 | 预期结果 |
|
||||
|--------|------|---------|
|
||||
| 15×15 网格 + 60 Pin 验证通过 | 输入测试 | 无错误提示，转换成功 |
|
||||
| 4×8 网格 + 24 Pin 验证通过 | 输入测试 | 无错误提示，转换成功 |
|
||||
| 2×2 网格 + 8 Pin 验证通过 | 输入测试 | 无错误提示，转换成功 |
|
||||
| 错误 Pin 数量仍报错 | 输入 15×15+56Pin | 提示不匹配 |
|
||||
| 布局计算正确 | 检查输出文件 | 四条边 Pin 分布正确 |
|
||||
|
||||
### 8.3 BUG-003 / F007 验收
|
||||
|
||||
| 验收项 | 方法 | 预期结果 |
|
||||
|--------|------|---------|
|
||||
| List→MAP 读取模板 | 放置模板文件后转换 | 日志显示"已加载模板样式" |
|
||||
| MAP→List 读取模板 | 放置模板文件后转换 | 日志显示"已加载模板样式" |
|
||||
| 无模板时优雅降级 | 不放置模板文件 | 日志显示"未检测到模板文件"，使用默认样式 |
|
||||
| 模板解析失败降级 | 放置损坏的模板文件 | 日志显示"解析失败"，使用默认样式 |
|
||||
| 输出文件样式正确 | 打开输出文件 | 字体、边框、对齐与模板一致 |
|
||||
|
||||
### 8.4 BUG-004 / F008 验收
|
||||
|
||||
| 验收项 | 方法 | 预期结果 |
|
||||
|--------|------|---------|
|
||||
| 处理完不退出 | 完成一次转换 | 显示"按 Enter 键继续"或循环提示 |
|
||||
| 输入 Q 返回主菜单 | 处理完成后输入 Q | 返回方向选择菜单 |
|
||||
| 主菜单输入 Q 退出 | 主菜单输入 Q | 程序退出 |
|
||||
| 连续处理多个文件 | 连续选择文件 | 可连续处理，无需重新运行 |
|
||||
| 命令行参数模式 | `run.bat input.xls` | 处理完成后进入循环 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 风险评估汇总
|
||||
|
||||
| 风险 | 影响 | 概率 | 缓解措施 |
|
||||
|------|------|------|---------|
|
||||
| 周长公式修改导致已有布局算法不一致 | **高** | 中 | 同步修改 validator + layout，确保公式统一 |
|
||||
| 角点单元格 Name 冲突 | 中 | 中 | 修改 `get_name_cell()` 确保不重叠 |
|
||||
| main.py 两处修改冲突 | 中 | 中 | 先完成 BUG-003，再完成 BUG-004，避免同时修改 |
|
||||
| 模板路径在命令行模式下解析错误 | 低 | 低 | 使用 `__file__` 绝对路径而非 cwd |
|
||||
| 循环流程中模块重复 import 性能 | 低 | 极低 | Python 有 import 缓存 |
|
||||
|
||||
---
|
||||
|
||||
## 10. 总结
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| 修改文件数 | 5 个（run.bat, main.py, pinlist_validator.py, validator.py, pinmap_layout.py） |
|
||||
| 新增文件数 | 0 |
|
||||
| 影响核心模块 | 是（pinmap_layout.py 布局算法） |
|
||||
| 技术难度 | 中（周长公式 + 布局算法需同步修改） |
|
||||
| 预估工作量 | ~3 小时 |
|
||||
| 推荐 Agent | Python 编码 Agent（1-2 个） |
|
||||
| 风险等级 | 中（公式修改需仔细验证） |
|
||||
|
||||
**结论**：
|
||||
1. BUG-002 为最高优先级，影响所有 List→MAP 转换的正确性
|
||||
2. BUG-001 修复最简单，可快速完成
|
||||
3. BUG-003 和 BUG-004 都修改 `main.py`，需先后执行避免冲突
|
||||
4. 所有修改均使用 Python 标准库，无新增依赖
|
||||
5. 建议修改完成后运行完整测试套件验证
|
||||
|
||||
---
|
||||
|
||||
*文档结束 — 请审批后进入编码阶段*
|
||||
27
docs/requirements.md
Normal file
27
docs/requirements.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# 需求规格说明书
|
||||
|
||||
## 项目信息
|
||||
- 项目名称：pinmap-to-pinlist
|
||||
- 项目 ID：PROJ-002
|
||||
- 项目类型：脚本
|
||||
- 技术约束：Python 脚本，支持 Windows 和 Linux
|
||||
|
||||
## 需求描述
|
||||
PinMAP ↔ PinList 双向转换器，支持 PinMAP→PinList 与 PinList→PinMAP 互转。
|
||||
|
||||
## 输入/输出
|
||||
| 类型 | 描述 |
|
||||
|-----|------|
|
||||
| 输入 | PinMAP 或 PinList Excel 文件 |
|
||||
| 输出 | 转换后的 Excel 文件 |
|
||||
|
||||
## 边界条件
|
||||
- 支持 .xls 和 .xlsx 格式
|
||||
- Pin 数量必须与网格周长匹配
|
||||
- 网格尺寸至少为 2x2
|
||||
|
||||
## 验收标准
|
||||
1. 能正确解析 PinMAP 结构
|
||||
2. 能正确生成 PinList
|
||||
3. 能正确反向转换
|
||||
4. 错误处理完善
|
||||
13
docs/tasks.md
Normal file
13
docs/tasks.md
Normal file
@@ -0,0 +1,13 @@
|
||||
# 任务进度表
|
||||
|
||||
| 任务 ID | 任务名称 | 负责 Agent | 当前状态 | 任务类型 | 关联功能 | 创建时间 | 完成时间 |
|
||||
|--------|---------|-----------|---------|---------|---------|---------|---------|
|
||||
| T001 | 架构设计 | script-architect | 已完成 | 架构设计 | F001-F005 | 2026-05-23 | 2026-05-23 |
|
||||
| T002 | Python 编码 v1.2 | python-coding-agent | 已完成 | 编码实现 | F001-F005 | 2026-05-23 | 2026-05-26 |
|
||||
| T003 | BAT 编码 | bat-coding-agent | 已完成 | 编码实现 | F005 | 2026-05-23 | 2026-05-23 |
|
||||
| T004 | 测试验证 v1.2 | test-qa-agent | 已完成 | 测试验证 | F001-F005 | 2026-05-23 | - |
|
||||
| T007 | BAT 脚本修复 v1.3 | bat-coding-agent | 已完成 | 编码实现 | F005 | 2026-05-31 | 2026-05-31 |
|
||||
| T008 | Python 编码 v1.3 | python-coding-agent | 已完成 | 编码实现 | F006-F008 | 2026-05-31 | 2026-05-31 |
|
||||
| T009 | 测试验证 v1.3 | test-qa-agent | 进行中 | 测试验证 | F005-F008 | 2026-05-31 | - |
|
||||
| T010 | 文档生成 v1.3 | doc-gen-agent | 待分配 | 文档编写 | F005-F008 | - | - |
|
||||
| T011 | 打包发布 v1.3 | package-release-agent | 待分配 | 打包发布 | F005-F008 | - | - |
|
||||
Reference in New Issue
Block a user