# PinMAP ↔ PinList 双向转换器 — 全局架构设计

> **版本**: v2.0  
> **日期**: 2026-05-28  
> **架构师**: 脚本架构师 (Script Architect)  
> **状态**: 待审批  
> **变更**: 新增 PinList → PinMAP 反向转换 + 模板格式支持

---

## 1. 项目概述

### 1.1 背景

将 Excel 格式的 **PinMAP** 文件（方形封装引脚布局图）与 **PinList** 格式（引脚序号列表）进行**双向自动转换**，消除手动抄录的低效与错误风险。

- **PinMAP → PinList**（已有）：方形布局图 → 扁平引脚列表
- **PinList → PinMAP**（新增）：扁平引脚列表 → 方形布局图

### 1.2 核心规则

- PinMAP 为方形/长方形结构，引脚沿四条边分布，左上角为 1 脚，**逆时针**排序
- 四条边遍历顺序：左→下→右→上（counter-clockwise）
- 四个角点被相邻两边共享（不重复计数）
- 总 Pin 数 = 2 × width + 2 × height − 4

### 1.3 约束

| 约束项 | 说明 |
|--------|------|
| 运行平台 | Windows |
| 技术栈 | Python 标准库，**零第三方依赖** |
| 输入格式 | `.xls`（必须支持）、`.xlsx`（优先支持） |
| 输出格式 | `.xlsx` 仅 |
| 交互方式 | 命令行 + 文件选择对话框 |
| 模板 | 可选，根目录 `PinMAP-Template.xlsx` |

---

## 2. 技术可行性评估

### 2.1 PinList → PinMAP 反向转换

**可行性：✅ 完全可行**

| 子任务 | 技术可行性 | 说明 |
|--------|-----------|------|
| PinList 读取与解析 | ✅ 低难度 | 复用现有 xls_reader/xlsx_reader，解析 A/B 两列即可 |
| Pin 数据验证 | ✅ 低难度 | 连续性、唯一性检查逻辑与现有 validator 类似 |
| 尺寸输入 | ✅ 低难度 | 命令行 `input()` 交互，输入行数/列数 |
| PinMAP 布局计算 | ✅ 中难度 | 核心算法：根据 width/height 将 Pin 分配到四条边 |
| PinMAP 生成与输出 | ✅ 中难度 | 需要增强 xlsx_writer 支持模板样式 |
| 模板检测与读取 | ✅ 中难度 | 需新增 xlsx style 读取能力（styles.xml 解析） |

### 2.2 关键技术难点

#### 难点 1：PinMAP 布局分配算法

**问题**：给定 PinList（N 个 Pin，已按序号 1..N 排序）和尺寸 (rows, cols)，如何将 Pin 分配到四条边？

**公式**（逆时针，左上角为 1 脚）：

```
总 Pin 数 N = 2 × cols + 2 × rows − 4

边分配（按遍历顺序）：
  左边 (left)   = rows 个 Pin         → Pin 1..rows
  下边 (bottom) = cols − 1 个 Pin      → Pin (rows+1)..(rows+cols−1)
  右边 (right)  = rows − 2 个 Pin      → Pin (rows+cols)..(rows+2×cols−3)
  上边 (top)    = cols − 1 个 Pin      → Pin (rows+2×cols−2)..N

验证：rows + (cols−1) + (rows−2) + (cols−1) = 2×rows + 2×cols − 4 = N ✓
```

**示例**：4×8 网格（rows=4, cols=8, N=20）

```
左边：Pin 1-4   (4个)
下边：Pin 5-12  (8个)
右边：Pin 13-15 (3个)
上边：Pin 16-20 (5个)
总计：4+8+3+5 = 20 ✓
```

**非 4 倍数处理**：提示用户 "Pin 数量 {N} 不是 4 的倍数，四条边将不均匀分布"，不影响转换。

#### 难点 2：模板样式读取

**问题**：从零实现的 xlsx_reader 目前只读取单元格值，不读取样式（字体、边框、背景色等）。PinMAP 输出需要参考模板的单元格样式。

**方案**：
1. 新增 `template_reader.py` 模块，专门解析 `xl/styles.xml`
2. 提取关键样式信息：字体、边框、填充色、对齐方式
3. 在 `pinmap_generator.py` 中应用模板样式到输出文件
4. 模板不存在时，使用默认样式（无边框、默认字体）

**OOXML styles.xml 结构**：

```xml
<stylesSheet>
  <fonts count="1">
    <font><sz val="11"/><name val="Calibri"/></font>
  </fonts>
  <fills count="2">...</fills>
  <borders count="1">...</borders>
  <cellXfs count="1">
    <xf numFmtId="0" fontId="0" fillId="0" borderId="0"/>
  </cellXfs>
</stylesSheet>
```

**复杂度评估**：中等。需解析 XML 结构，提取 cellXfs（单元格格式）与 fonts/borders/fills 的关联关系。

#### 难点 3：双向交互流程

**问题**：main.py 需要支持两种转换方向，交互流程不同。

**方案**：启动时让用户选择方向，然后进入对应的流程。保持与现有 PinMAP→PinList 一致的交互风格（Banner → 文件选择 → 处理 → 结果摘要）。

---

## 3. 模块划分

### 3.1 现有模块（PinMAP → PinList 方向）

```
Code/src/
├── main.py              # 入口：流程编排（需修改）
├── file_selector.py     # 文件选择（需修改）
├── xls_reader.py        # XLS 解析引擎（不变）
├── xlsx_reader.py       # XLSX 解析引擎（不变）
├── pinmap_parser.py     # PinMAP 结构解析（不变）
├── validator.py         # 数据验证（需修改）
├── pinlist_generator.py # PinList 生成（不变）
├── xlsx_writer.py       # XLSX 输出引擎（需修改）
├── models.py            # 数据模型（需修改）
└── utils.py             # 工具函数（不变）
```

### 3.2 新增模块（PinList → PinMAP 方向）

| 模块 | 文件 | 职责 |
|------|------|------|
| **PinList 解析器** | `pinlist_parser.py` | 读取 PinList xlsx，解析 A1 封装信息 + A/B 列 PinName/序号 |
| **PinList 验证器** | `pinlist_validator.py` | 验证 Pin 序号连续性、唯一性、与周长匹配 |
| **PinMAP 布局计算** | `pinmap_layout.py` | 根据尺寸将 Pin 分配到四条边，计算单元格坐标 |
| **PinMAP 生成器** | `pinmap_generator.py` | 组装 PinMAP 单元格数据，应用模板样式 |
| **模板读取器** | `template_reader.py` | 读取 PinMAP-Template.xlsx 的样式信息 |

### 3.3 修改后完整目录结构

```
pinmap-to-pinlist/
├── Code/
│   ├── src/
│   │   ├── main.py                  # ✏️ 修改：双向选择 + 双流程
│   │   ├── file_selector.py         # ✏️ 修改：支持两种文件类型过滤
│   │   ├── models.py                # ✏️ 修改：新增 PinList 输入模型
│   │   ├── validator.py             # ✏️ 修改：新增 PinList 验证函数
│   │   ├── xlsx_writer.py           # ✏️ 修改：支持样式写入
│   │   │
│   │   ├── xls_reader.py            # （不变）
│   │   ├── xlsx_reader.py           # （不变）
│   │   ├── pinmap_parser.py         # （不变）
│   │   ├── pinlist_generator.py     # （不变）
│   │   ├── utils.py                 # （不变）
│   │   │
│   │   ├── pinlist_parser.py        # 🆕 PinList 读取与解析
│   │   ├── pinlist_validator.py     # 🆕 PinList 数据验证
│   │   ├── pinmap_layout.py         # 🆕 PinMAP 布局计算
│   │   ├── pinmap_generator.py      # 🆕 PinMAP 生成与输出
│   │   └── template_reader.py       # 🆕 模板样式读取
│   └── docs/
│       ├── architecture-design.md   # ✏️ 更新
│       └── modification-assessment.md
├── Test/
│   └── fixtures/
│       ├── sample_4x4.xlsx          # 现有 PinMAP 测试
│       ├── sample_rect.xlsx
│       ├── sample_pinlist.xlsx      # 🆕 PinList 测试
│       └── PinMAP-Template.xlsx     # 🆕 模板文件（可选）
├── run.bat                          # （不变）
└── Releases/
```

---

## 4. 模块详细设计

### 4.1 新增模块：`pinlist_parser.py`

**职责**：读取 PinList 格式的 xlsx 文件，解析封装信息和引脚数据。

```python
"""PinList parser — reads a flat pin list from an Excel file."""

from dataclasses import dataclass

@dataclass
class PinListEntry:
    """A single pin entry from the PinList."""
    number: int       # Pin 序号（B 列）
    name: str         # PinName（A 列，可能为空）


class PinListParser:
    """Parse a PinList Excel file."""

    def __init__(self, filepath: str):
        self._filepath = filepath

    def parse(self) -> tuple[str, list[PinListEntry]]:
        """
        解析 PinList 文件。

        Returns
        -------
        (package_info, entries)
            package_info: A1 单元格的封装信息
            entries: 按 Pin 序号排序的引脚列表

        Raises
        ------
        StructureError
            A1 为空、A/B 列无数据、序号非整数等
        """
        # 1. 读取文件（复用 xlsx_reader / xls_reader）
        # 2. 提取 A1 封装信息
        # 3. 解析 A 列 (PinName) 和 B 列 (Pin序号)
        # 4. 按 Pin 序号排序
        # 5. 返回 (package_info, entries)
```

**解析规则**：
- A1 单元格 = 封装信息（与 PinMAP 方向一致）
- A 列（从 A2 开始）= PinName
- B 列（从 B2 开始）= Pin 序号
- 读取到第一个空行为止
- Pin 序号可能不是按顺序排列的（需要在 validator 中检查）

### 4.2 新增模块：`pinlist_validator.py`

**职责**：验证 PinList 数据的完整性和正确性。

```python
"""PinList validator — checks pin data integrity."""

from models import ValidationResult, ValidationError


def validate_pinlist(
    entries: list[PinListEntry],
    rows: int,
    cols: int,
) -> ValidationResult:
    """
    验证 PinList 数据。

    检查项：
    1. Pin 序号从 1 开始连续无缺失
    2. Pin 序号无重复
    3. Pin 总数 = 2×rows + 2×cols − 4（周长匹配）
    4. Pin 缺少 PinName 时默认为 NC（warning）
    5. Pin 数量不是 4 的倍数时提示（info）

    Parameters
    ----------
    entries : list[PinListEntry]
        已按序号排序的引脚列表
    rows : int
        用户输入的 PinMAP 行数
    cols : int
        用户输入的 PinMAP 列数

    Returns
    -------
    ValidationResult
    """
```

**验证逻辑**：

```python
# 1. 连续性检查
numbers = sorted(e.number for e in entries)
expected = list(range(1, len(numbers) + 1))
if numbers != expected:
    missing = set(expected) - set(numbers)
    errors.append(f"Pin序号不连续，缺失: {sorted(missing)}")

# 2. 唯一性检查
if len(numbers) != len(set(numbers)):
    errors.append("Pin序号存在重复")

# 3. 周长匹配
expected_total = 2 * rows + 2 * cols - 4
if len(entries) != expected_total:
    errors.append(
        f"Pin数量 ({len(entries)}) 与网格周长 ({expected_total}) 不匹配"
    )

# 4. 缺失 PinName（warning）
missing_names = [e for e in entries if not e.name or not e.name.strip()]
if missing_names:
    warnings.append(f"{len(missing_names)} 个引脚缺少 PinName，将默认为 NC")

# 5. 非 4 倍数提示（info）
if len(entries) % 4 != 0:
    infos.append(f"Pin数量 ({len(entries)}) 不是 4 的倍数，四条边将不均匀分布")
```

### 4.3 新增模块：`pinmap_layout.py`

**职责**：根据 PinMAP 尺寸和 PinList 数据，计算每条边的 Pin 分布和单元格坐标。

```python
"""PinMAP layout calculator — distributes pins to four edges."""

from dataclasses import dataclass
from typing import NamedTuple

class CellRef(NamedTuple):
    """Excel cell reference (row, col), 0-based."""
    row: int
    col: int


@dataclass
class EdgePins:
    """Pins assigned to one edge of the PinMAP."""
    edge: str           # "left" | "bottom" | "right" | "top"
    pins: list[tuple[int, str]]  # [(number, name), ...]
    cells: list[CellRef]         # 对应的单元格坐标


def calculate_layout(
    entries: list[PinListEntry],
    rows: int,
    cols: int,
) -> dict[str, EdgePins]:
    """
    计算 PinMAP 布局。

    逆时针分配（左上角为 1 脚）：
    左边 → 下边 → 右边 → 上边

    Parameters
    ----------
    entries : list[PinListEntry]
        已按序号排序的引脚列表
    rows : int
        PinMAP 行数
    cols : int
        PinMAP 列数

    Returns
    -------
    dict[str, EdgePins]
        {"left": ..., "bottom": ..., "right": ..., "top": ...}

    Raises
    ------
    StructureError
        尺寸无效（rows < 2 或 cols < 2）
    """
```

**布局算法**：

```python
def calculate_layout(entries, rows, cols):
    """
    网格坐标体系（0-based）：
    
    假设方形区域从 (1, 0) 开始（Excel 的 A2），
    方形区域：行 [1..rows]，列 [0..cols-1]
    
    四条边的单元格坐标：
    
    左边 (left):   序号在 (r, 0),         Name 在 (r, 1)       其中 r ∈ [1, rows]
    下边 (bottom): 序号在 (rows, c),       Name 在 (rows-1, c)  其中 c ∈ [1, cols-1]
    右边 (right):  序号在 (r, cols-1),     Name 在 (r, cols-2)  其中 r ∈ [rows-1, 2]
    上边 (top):    序号在 (1, c),          Name 在 (2, c)       其中 c ∈ [cols-2, 1]
    
    Pin 分配（按逆时针遍历顺序）：
    左边:   Pin 1..rows              → rows 个
    下边:   Pin (rows+1)..(rows+cols-1) → cols-1 个
    右边:   Pin (rows+cols)..(rows+2*cols-3) → rows-2 个
    上边:   Pin (rows+2*cols-2)..N   → cols-1 个
    """
```

**示例**：4×8 网格

```
左边 (4个):  Pin 1-4
  序号: (1,0)=1, (2,0)=2, (3,0)=3, (4,0)=4
  Name:  (1,1), (2,1), (3,1), (4,1)

下边 (8个):  Pin 5-12
  序号: (4,1)=5, (4,2)=6, ..., (4,8)=12
  Name:  (3,1), (3,2), ..., (3,8)

右边 (3个):  Pin 13-15
  序号: (3,8)=13, (2,8)=14, (1,8)=15
  Name:  (3,7), (2,7), (1,7)

上边 (5个):  Pin 16-20
  序号: (1,7)=16, (1,6)=17, ..., (1,3)=20
  Name:  (2,7), (2,6), ..., (2,3)
```

### 4.4 新增模块：`pinmap_generator.py`

**职责**：根据布局计算结果，生成 PinMAP 的单元格数据字典，并写入 xlsx 文件。

```python
"""PinMAP generator — builds PinMAP cell data and writes to xlsx."""

from pinmap_layout import calculate_layout, EdgePins
from template_reader import TemplateStyle
from xlsx_writer import write_xlsx_with_style


def generate_pinmap(
    entries: list[PinListEntry],
    rows: int,
    cols: int,
    package_info: str,
    template_style: TemplateStyle | None = None,
    output_path: str | None = None,
) -> dict[str, str]:
    """
    生成 PinMAP 布局并写入文件。

    Parameters
    ----------
    entries : list[PinListEntry]
        PinList 数据
    rows : int
        PinMAP 行数
    cols : int
        PinMAP 列数
    package_info : str
        封装信息（写入 A1）
    template_style : TemplateStyle | None
        模板样式（可选）
    output_path : str | None
        输出文件路径

    Returns
    -------
    dict[str, str]
        单元格数据字典 {"A1": "封装", "A2": "1", "B2": "Pin1", ...}
    """
    # 1. 计算布局
    layout = calculate_layout(entries, rows, cols)

    # 2. 构建单元格数据
    data = {"A1": package_info}
    for edge_name, edge in layout.items():
        for (pin_num, pin_name), cell in zip(edge.pins, edge.cells):
            data[f"{cell_ref(cell)}"] = str(pin_num)
            name_cell = get_name_cell(cell, edge_name)
            data[f"{cell_ref(name_cell)}"] = pin_name or "NC"

    # 3. 写入文件（应用模板样式）
    if output_path:
        write_xlsx_with_style(data, output_path, template_style)

    return data
```

### 4.5 新增模块：`template_reader.py`

**职责**：读取 PinMAP-Template.xlsx 的样式信息。

```python
"""Template reader — extracts cell styles from a template xlsx file."""

from dataclasses import dataclass, field
from typing import Optional


@dataclass
class FontStyle:
    """Font style."""
    name: str = "Calibri"
    size: float = 11.0
    bold: bool = False
    italic: bool = False
    color: str = "000000"


@dataclass
class BorderStyle:
    """Border style for a cell."""
    top: str = "none"       # none | thin | medium | thick
    bottom: str = "none"
    left: str = "none"
    right: str = "none"
    color: str = "000000"


@dataclass
class FillStyle:
    """Cell fill style."""
    pattern_type: str = "none"  # none | solid | gray125
    fg_color: str = ""


@dataclass
class AlignmentStyle:
    """Cell alignment."""
    horizontal: str = "center"  # left | center | right
    vertical: str = "center"


@dataclass
class TemplateStyle:
    """Complete style extracted from template."""
    fonts: list[FontStyle] = field(default_factory=list)
    borders: list[BorderStyle] = field(default_factory=list)
    fills: list[FillStyle] = field(default_factory=list)
    cell_xfs: list[dict] = field(default_factory=list)  # xf index → style mapping
    column_widths: dict[int, float] = field(default_factory=dict)
    row_heights: dict[int, float] = field(default_factory=dict)


class TemplateReader:
    """Read styles from a template xlsx file."""

    def __init__(self, filepath: str):
        self._filepath = filepath

    def read_styles(self) -> TemplateStyle:
        """
        读取模板文件的样式信息。

        解析 xl/styles.xml 中的：
        - fonts, fills, borders, cellXfs
        - 列宽和行高（从 sheetData 读取）

        Returns
        -------
        TemplateStyle
        """
```

**实现要点**：
- 复用 `xlsx_reader.py` 的 ZIP 解压和 XML 解析能力
- 新增解析 `xl/styles.xml` 的逻辑
- 提取 `cellXfs` 中每个 xf 索引对应的 fontId/borderId/fillId
- 列宽从 `<cols>` 元素读取，行高从 `<row>` 元素的 `ht` 属性读取

### 4.6 修改模块：`main.py`

**修改内容**：支持双向转换，启动时选择方向。

```python
def main():
    show_banner()

    # ── 选择转换方向 ──────────────────────────────────────────
    direction = select_direction()  # "map_to_list" or "list_to_map"

    if direction == "map_to_list":
        run_map_to_list()
    else:
        run_list_to_map()


def select_direction() -> str:
    """让用户选择转换方向。"""
    print("请选择转换方向:")
    print("  1. PinMAP → PinList  (方形布局图转引脚列表)")
    print("  2. PinList → PinMAP  (引脚列表转方形布局图)")
    while True:
        choice = input("请输入选项 (1/2): ").strip()
        if choice == "1":
            return "map_to_list"
        elif choice == "2":
            return "list_to_map"
        print("无效选项，请重新输入")


def run_map_to_list():
    """PinMAP → PinList 流程（现有逻辑，增加模板格式参考）"""
    # 1. 文件选择（PinMAP 文件）
    # 2. 读取 Excel
    # 3. 解析 PinMAP
    # 4. 验证
    # 5. 生成 PinList
    # 6. 写入 xlsx（如有模板则参考格式）
    # 7. 结果摘要


def run_list_to_map():
    """PinList → PinMAP 流程（新增）"""
    # 1. 文件选择（PinList 文件）
    # 2. 解析 PinList
    # 3. 输入尺寸（行数、列数）
    # 4. 验证 PinList 数据
    # 5. 计算布局
    # 6. 生成 PinMAP
    # 7. 写入 xlsx（应用模板样式）
    # 8. 结果摘要
```

### 4.7 修改模块：`file_selector.py`

**修改内容**：支持两种文件类型的过滤。

```python
def select_file(direction: str) -> Optional[str]:
    """
    文件选择流程。

    Parameters
    ----------
    direction : str
        "map_to_list" → 选择 PinMAP 文件
        "list_to_map" → 选择 PinList 文件
    """
    if direction == "map_to_list":
        title = "选择 PinMAP 文件"
    else:
        title = "选择 PinList 文件"

    # 复用现有逻辑，仅修改提示文本和对话框标题
```

### 4.8 修改模块：`models.py`

**修改内容**：新增 PinList 输入相关的数据模型。

```python
# 新增数据模型
@dataclass
class PinListEntry:
    """PinList 中的单个引脚条目。"""
    number: int
    name: str


@dataclass
class PinMAPLayout:
    """计算出的 PinMAP 布局。"""
    package_info: str
    rows: int
    cols: int
    edges: dict[str, EdgePins]  # left/bottom/right/top
    cells: dict[str, str]       # 单元格数据 {"A2": "1", "B2": "Pin1", ...}


# 新增异常
class LayoutError(PinMapError):
    """布局计算错误（尺寸无效、Pin 数量不匹配等）。"""
```

### 4.9 修改模块：`xlsx_writer.py`

**修改内容**：支持样式写入（用于 PinMAP 输出）。

```python
def write_xlsx_with_style(
    data: dict[str, str],
    output_path: str,
    style: TemplateStyle | None = None,
):
    """
    写入 xlsx 文件，可选应用模板样式。

    Parameters
    ----------
    data : dict[str, str]
        单元格数据
    output_path : str
        输出路径
    style : TemplateStyle | None
        模板样式（可选）
    """
    # 现有 write_xlsx() 保持不变（用于 PinList 输出）
    # 新增 write_xlsx_with_style() 用于 PinMAP 输出（需要样式）
```

**样式写入实现**：
- 在 OOXML 中生成 `xl/styles.xml`
- 在 sheet1.xml 的 `<c>` 元素中添加 `s` 属性（style index）
- 如果模板不存在，使用最小样式集（无边框、默认字体）

### 4.10 修改模块：`validator.py`

**修改内容**：新增 `validate_pinlist()` 函数，与现有 `validate_pinmap()` 并存。

```python
# 新增函数（不修改现有 validate_pinmap）
def validate_pinlist(entries, rows, cols) -> ValidationResult:
    """验证 PinList 数据（独立函数，不修改现有 validate_pinmap）"""
```

**建议**：将 `validate_pinlist()` 放在独立的 `pinlist_validator.py` 中，保持单一职责。

---

## 5. 数据流设计

### 5.1 PinMAP → PinList 流程（现有 + 模板增强）

```
PinMAP 文件 (.xls/.xlsx)
    │
    ▼
xls_reader / xlsx_reader
    │  → dict[(row,col), str]
    ▼
pinmap_parser.parse_pinmap()
    │  → PinMAP
    ▼
validator.validate_pinmap()
    │  → ValidationResult
    ▼
pinlist_generator.generate_pinlist()
    │  → PinList
    ▼
xlsx_writer.write_xlsx()        ← 如有模板，参考格式
    │
    ▼
PinList 文件 (.xlsx)
```

### 5.2 PinList → PinMAP 流程（新增）

```
PinList 文件 (.xls/.xlsx)
    │
    ▼
pinlist_parser.parse()
    │  → (package_info, entries)
    ▼
用户输入：行数、列数
    │
    ▼
pinlist_validator.validate_pinlist()
    │  → ValidationResult
    │
    ├─ 缺失 PinName → 提示确认，默认 NC
    ├─ 非 4 倍数 → 提示
    └─ 错误 → 终止
    ▼
pinmap_layout.calculate_layout()
    │  → dict[str, EdgePins]
    ▼
pinmap_generator.generate_pinmap()
    │  → cells dict + 写入文件
    │
    └─ 检测 PinMAP-Template.xlsx
       ├─ 存在 → template_reader.read_styles() → 应用样式
       └─ 不存在 → 默认样式
    ▼
PinMAP 文件 (.xlsx)
```

---

## 6. PinList 文件格式规范

### 6.1 格式定义

| 单元格 | 内容 | 说明 |
|--------|------|------|
| A1 | 封装信息 | 如 "QFN-20"、"BGA-256" |
| A2 | PinName1 | 引脚名称 |
| B2 | 1 | Pin 序号 |
| A3 | PinName2 | 引脚名称 |
| B3 | 2 | Pin 序号 |
| ... | ... | ... |
| An | PinNameN | 引脚名称 |
| Bn | N | Pin 序号 |

### 6.2 示例

```
A1: "QFN-20"
A2: "VCC"    B2: "1"
A3: "GND"    B3: "2"
A4: "IN1"    B4: "3"
A5: "IN2"    B5: "4"
A6: "OUT1"   B6: "5"
...
A21: "RST"   B21: "20"
```

### 6.3 约束

- A1 不能为空（封装信息）
- B 列必须为整数（Pin 序号）
- A 列可为空（缺失时默认 NC）
- Pin 序号从 1 开始连续
- 读取到第一个空行（A 列和 B 列都为空）为止

---

## 7. 模板格式规范

### 7.1 模板文件

- **文件名**：`PinMAP-Template.xlsx`
- **位置**：程序根目录（与 `run.bat` 同级）
- **作用**：提供输出 PinMAP 文件的样式参考

### 7.2 模板内容

模板文件应包含：
- 正确的方形布局结构（用于参考单元格位置）
- 单元格样式：字体、字号、边框、填充色、对齐方式
- 列宽和行高设置

### 7.3 模板使用方式

- 模板**仅用于样式参考**，不用于结构参考
- 程序从模板提取：字体、边框、填充、对齐、列宽、行高
- 实际引脚数据由 PinList 决定
- 模板不存在时，使用默认样式（无边框、Calibri 11号、居中对齐）

---

## 8. 交互流程设计

### 8.1 启动 Banner

```
============================================================
  PinMAP ↔ PinList 双向转换器
  自动在方形布局图与引脚列表之间转换
  支持.xls和.xlsx格式，输出.xlsx格式
============================================================

请选择转换方向:
  1. PinMAP → PinList  (方形布局图转引脚列表)
  2. PinList → PinMAP  (引脚列表转方形布局图)
请输入选项 (1/2):
```

### 8.2 PinList → PinMAP 完整交互流程

```
[INFO] 正在读取 PinList 文件: C:\test\pinlist.xlsx
[INFO] 文件读取完成，共 20 个引脚
[INFO] 封装信息: QFN-20

请输入 PinMAP 尺寸:
  行数: 4
  列数: 8

[INFO] 正在验证数据...
[WARN] 检测到 2 个引脚缺少 PinName，将默认为 NC
[INFO] Pin数量 (20) 是 4 的倍数，四条边均匀分布
[INFO] 验证通过

[INFO] 正在计算 PinMAP 布局...
[INFO] 布局计算完成: 4×8 网格，左边4个 + 下边8个 + 右边3个 + 上边5个
[INFO] 检测到模板文件: PinMAP-Template.xlsx
[INFO] 正在生成 PinMAP...
[INFO] 正在写入输出文件: C:\test\pinlist_PinMAP.xlsx

[SUCCESS] 转换完成！
  输出文件: C:\test\pinlist_PinMAP.xlsx
  封装信息: QFN-20
  网格尺寸: 4×8
  Pin数量: 20
  模板: 已应用
```

### 8.3 错误处理交互

```
[ERROR] Pin序号不连续，缺失: [3, 7, 15]
转换终止，请修正 PinList 文件后重试。

按 Enter 键退出...
```

```
[ERROR] Pin数量 (18) 与网格周长 (20) 不匹配
  网格 4×8 需要 20 个引脚，但 PinList 只有 18 个
转换终止，请检查尺寸或 PinList 数据。

按 Enter 键退出...
```

---

## 9. 工作量评估

### 9.1 开发任务拆分

| 任务编号 | 任务 | 文件 | 工作量 | 依赖 |
|---------|------|------|--------|------|
| **T1** | PinList 解析器 | `pinlist_parser.py` | 1h | 无 |
| **T2** | PinList 验证器 | `pinlist_validator.py` | 1h | T1 |
| **T3** | PinMAP 布局计算 | `pinmap_layout.py` | 2h | T1, T2 |
| **T4** | PinMAP 生成器 | `pinmap_generator.py` | 1.5h | T3 |
| **T5** | 模板读取器 | `template_reader.py` | 2.5h | 无 |
| **T6** | xlsx_writer 样式支持 | `xlsx_writer.py` | 2h | T5 |
| **T7** | main.py 双向改造 | `main.py` | 1.5h | T1-T6 |
| **T8** | file_selector 修改 | `file_selector.py` | 0.5h | T7 |
| **T9** | models.py 扩展 | `models.py` | 0.5h | T1 |
| **T10** | 测试用例 | `test_pinlist.py` | 2h | T1-T9 |
| **T11** | 测试数据文件 | `Test/fixtures/` | 1h | T10 |

**总计预估**：约 15.5 小时（约 2 个工作日）

### 9.2 复杂度分级

| 复杂度 | 任务 | 原因 |
|--------|------|------|
| **低** | T1, T2, T8, T9 | 逻辑简单，复用现有代码 |
| **中** | T3, T4, T7 | 核心业务逻辑，需仔细处理边界条件 |
| **高** | T5, T6, T10 | OOXML 样式解析/写入复杂，测试覆盖全面 |

### 9.3 推荐开发顺序

```
第1轮（并行）：
  T1: PinList 解析器
  T5: 模板读取器（可独立开发）

第2轮（依赖 T1）：
  T2: PinList 验证器
  T3: PinMAP 布局计算

第3轮（依赖 T2, T3）：
  T4: PinMAP 生成器
  T6: xlsx_writer 样式支持

第4轮（集成）：
  T7: main.py 双向改造
  T8: file_selector 修改
  T9: models.py 扩展

第5轮（测试）：
  T10: 测试用例
  T11: 测试数据文件
```

---

## 10. 风险评估

| 风险 | 影响 | 概率 | 缓解措施 |
|------|------|------|---------|
| OOXML styles.xml 解析复杂度高 | 高 | 中 | 先实现最小可用样式集（字体+边框），逐步完善 |
| Pin 数量与周长不匹配的用户输入 | 中 | 高 | 在 validator 中严格检查，给出明确的错误提示 |
| 模板文件存在但格式异常 | 中 | 低 | 优雅降级：模板解析失败时回退到默认样式 |
| 非 4 倍数 Pin 数量的边界处理 | 低 | 中 | 明确文档化分配公式，测试各种尺寸组合 |
| 双向交互流程的用户体验 | 中 | 低 | 保持与现有流程一致的交互风格 |

---

## 11. 与现有架构的兼容性

### 11.1 向后兼容

- 现有 PinMAP → PinList 流程**完全不受影响**
- 新增模块与现有模块**松耦合**，通过接口交互
- 模板功能为**可选增强**，不影响无模板场景

### 11.2 代码复用

| 现有模块 | 复用方式 |
|---------|---------|
| `xls_reader.py` | PinList 解析直接复用 |
| `xlsx_reader.py` | PinList 解析 + 模板读取复用 ZIP/XML 解析 |
| `models.py` | 扩展新增数据模型 |
| `utils.py` | 坐标转换工具直接复用 |
| `xlsx_writer.py` | 扩展新增样式写入能力 |

### 11.3 零第三方依赖保持

所有新增功能仍使用 Python 标准库实现：
- Excel 读写：`zipfile` + `xml.etree.ElementTree` + `struct`
- 文件选择：`tkinter.filedialog`
- 样式解析：`xml.etree.ElementTree`

---

## 12. 测试策略

### 12.1 单元测试

```python
# test_pinlist.py

def test_pinlist_parse_basic():
    """基本 PinList 解析"""

def test_pinlist_parse_unsorted():
    """PinList 序号非顺序排列"""

def test_pinlist_parse_missing_names():
    """缺失 PinName 的处理"""

def test_pinlist_validate_continuous():
    """连续性验证"""

def test_pinlist_validate_duplicate():
    """重复序号验证"""

def test_pinlist_validate_perimeter_match():
    """周长匹配验证"""

def test_layout_4x4():
    """4×4 网格布局计算"""

def test_layout_4x8():
    """4×8 长方形布局计算"""

def test_layout_non_multiple_of_4():
    """非 4 倍数 Pin 数量布局"""

def test_template_read():
    """模板样式读取"""

def test_pinmap_generate():
    """PinMAP 生成与写入"""
```

### 12.2 集成测试

| 测试场景 | 输入 | 预期 |
|---------|------|------|
| 正向转换 | sample_4x4.xlsx | 生成 PinList，与手动结果一致 |
| 反向转换 | 生成的 PinList | 还原为原始 PinMAP |
| 往返转换 | PinMAP → PinList → PinMAP | 与原始 PinMAP 一致 |
| 模板应用 | PinList + Template | 输出文件样式与模板一致 |
| 无模板 | PinList（无模板） | 输出文件使用默认样式 |
| 错误输入 | 缺失序号的 PinList | 报错并终止 |
| 尺寸不匹配 | PinList + 错误尺寸 | 报错并终止 |

---

## 13. 接口契约

### 13.1 新增模块接口

```python
# pinlist_parser.py
def parse_pinlist(filepath: str) -> tuple[str, list[PinListEntry]]:
    """
    输入: PinList 文件路径
    输出: (封装信息, 按序号排序的引脚列表)
    """

# pinlist_validator.py
def validate_pinlist(
    entries: list[PinListEntry],
    rows: int,
    cols: int,
) -> ValidationResult:
    """
    输入: 引脚列表 + 尺寸
    输出: ValidationResult
    """

# pinmap_layout.py
def calculate_layout(
    entries: list[PinListEntry],
    rows: int,
    cols: int,
) -> dict[str, EdgePins]:
    """
    输入: 引脚列表 + 尺寸
    输出: 四条边的引脚分配
    """

# pinmap_generator.py
def generate_pinmap(
    entries: list[PinListEntry],
    rows: int,
    cols: int,
    package_info: str,
    template_style: TemplateStyle | None = None,
    output_path: str | None = None,
) -> dict[str, str]:
    """
    输入: 引脚数据 + 尺寸 + 封装 + 可选模板样式
    输出: 单元格数据字典
    """

# template_reader.py
def read_template_styles(filepath: str) -> TemplateStyle | None:
    """
    输入: 模板文件路径
    输出: 模板样式（不存在或解析失败时返回 None）
    """
```

---

## 14. 总结

| 项目 | 内容 |
|------|------|
| 新增模块数 | 5 个 |
| 修改模块数 | 5 个 |
| 不变模块数 | 5 个 |
| 技术难度 | 中（核心难点在 OOXML 样式处理） |
| 预估工作量 | ~15.5 小时（约 2 个工作日） |
| 推荐 Agent | Python 编码 Agent（1-2 个） |
| 风险等级 | 中低 |
| 第三方依赖 | 零新增 |

**结论**：
1. PinList → PinMAP 反向转换在技术上完全可行
2. 核心难点在于 OOXML 样式解析/写入，但可通过最小可用集逐步实现
3. 布局分配算法清晰，公式化计算，边界条件可控
4. 建议分 5 轮迭代开发，先完成核心转换逻辑，再增强模板支持
5. 与现有架构完全兼容，向后无破坏性变更

---

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