docs: v1.5.0 - 更新模板分离与格式提取文档

Code/docs/RELEASE.md

@@ -2,6 +2,165 @@
 
 ---
 
+## v1.5.0 — 2026-06-06
+
+### ✨ 模板分离与格式提取增强
+
+v1.5.0 将两个方向的模板完全分离，并实现了**提取式**模板格式应用机制，不再依赖硬编码的边框和对齐属性。新增 F012 回归测试确保上/下边 PinName 位置正确。
+
+---
+
+### 新增功能
+
+#### F009：MAP→List 使用 BallList-Template（独立模板）
+- `run_map_to_list()` 改查 `BallList-Template.xlsx`
+- 不再共用旧模板 `PinMAP-Template.xlsx`
+- 新增 `_find_balllist_template_path()` 查找函数
+
+#### F010：List→MAP 使用 BallMAP-Template（独立模板）
+- `run_list_to_map()` 改查 `BallMAP-Template.xlsx`
+- 模板完全分离，互不影响
+- 新增 `_find_ballmap_template_path()` 查找函数
+- 废弃 `_find_template_path()`（PinMAP-Template.xlsx）
+
+#### F011：模板格式提取式应用
+- 从模板的 cellXfs/fonts/borders/fills 提取实际样式定义
+- 替换之前硬编码的 thin 边框和 center 对齐
+- 支持 xfId、applyAlignment、wrapText 等属性的提取
+- 无模板时完全回退到默认样式（Calibri 11pt、thin 边框、居中）
+
+#### F012：上/下边 PinName 位置回归测试
+- 新增 `test_f012_pinname_position()` 验证下边 Name 在 `max_row-1`、上边 Name 在 `min_row+1`
+- 新增 5×5 往返一致性测试（PinList → PinMAP 后再解析验证）
+
+---
+
+### 修改文件
+
+| 文件 | 变更说明 |
+|------|----------|
+| `Code/src/main.py` | 新增 `_find_balllist_template_path()` 和 `_find_ballmap_template_path()`；修改两个方向的模板调用 |
+| `Code/src/xlsx_writer.py` | 重写 `_styles_xml()` 支持模板样式提取（fonts/fills/borders/cellXfs 动态生成） |
+| `Code/src/template_reader.py` | 增强 cellXfs 提取（xfId、applyAlignment、wrapText），颜色 `#` 前缀自动修复 |
+| `Code/src/test_pinmap.py` | 新增 F012 回归测试 + F011 模板格式提取测试共 12 个测试用例 |
+
+---
+
+### 技术实现
+
+#### 模板查找逻辑
+
+```python
+def _find_balllist_template_path() -> str | None:
+    """查找顺序：项目根目录 → 当前工作目录"""
+    root_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    # 1. 项目根目录
+    template_path = os.path.join(root_dir, "BallList-Template.xlsx")
+    if os.path.isfile(template_path):
+        return template_path
+    # 2. 当前工作目录
+    cwd_template = os.path.join(os.getcwd(), "BallList-Template.xlsx")
+    if os.path.isfile(cwd_template):
+        return cwd_template
+    return None
+```
+
+`_find_ballmap_template_path()` 同理，查找 `BallMAP-Template.xlsx`。
+
+#### 样式提取式应用
+
+```
+模板 styles.xml
+     │
+     ▼ 读取字体、填充、边框定义
+     ▼ 读取 cellXfs 引用
+     ▼ 读取列宽、行高
+     │
+     ▼ 写入输出 styles.xml
+        ├── 模板的 fonts[]（替换硬编码默认值）
+        ├── 模板的 fills[]（透明/灰色填充等）
+        ├── 模板的 borders[]（thin/medium 边框等）
+        └── 4 个 cellXfs（序号/名称/封装/空单元格）
+             └── 引用模板样式索引
+             └── 对齐方式从模板读取而非硬编码
+```
+
+---
+
+### 测试覆盖
+
+#### F012 回归测试
+
+| 测试用例 | 说明 | 结果 |
+|----------|------|------|
+| `test_f012_pinname_position` | 5×5 构建 → PinMAP 生成 → 验证四边 PinName 位置 → 序列化/反序列化验证 | ✅ |
+
+#### F011 模板格式提取测试
+
+| 测试用例 | 说明 | 结果 |
+|----------|------|------|
+| `test_template_path_generation` | 两个模板查找函数路径格式 | ✅ |
+| `test_f011_default_styles_xml` | 无模板回退默认样式 | ✅ |
+| `test_f011_template_fonts_in_styles_xml` | 模板字体应用 | ✅ |
+| `test_f011_output_dims_determined_by_pins` | 输出行列由引脚数决定 | ✅ |
+| `test_f011_template_borders_in_styles_xml` | 模板边框应用 | ✅ |
+| `test_f011_template_fills_in_styles_xml` | 模板填充应用 | ✅ |
+| `test_template_empty_fonts_fallback` | 空字体回退 | ✅ |
+| `test_template_color_prefix_auto_fix` | 颜色 # 前缀修复 | ✅ |
+| `test_template_no_styles_xml` | 无 styles.xml 降级 | ✅ |
+
+**新增测试**: 12 个测试用例
+**总测试**: 20 个单元测试 + 6 个集成测试 = 26 个
+**测试通过率**: 100%
+
+---
+
+### 已知问题
+
+无
+
+---
+
+### 限制
+
+| 限制项 | 说明 |
+|--------|------|
+| 模板查找 | 仅支持项目根目录和当前工作目录两种位置 |
+| 模板格式 | 仅支持 `.xlsx` 格式模板 |
+| 样式应用 | 提取式而非复制式，部分高级格式可能丢失 |
+
+其他限制同 v1.2.0。
+
+---
+
+### 升级指南
+
+**从 v1.3.x / v1.2.0 升级**：替换 `Code/src/` 目录下所有文件。模板文件需手动放置：
+- MAP→List 方向：在项目根目录放置 `BallList-Template.xlsx`
+- List→MAP 方向：在项目根目录放置 `BallMAP-Template.xlsx`
+- 模板可选，不放置则使用默认样式
+
+---
+
+### 贡献者
+
+- 架构设计：Script Architect
+- 编码实现：Coding Agent × 3
+- 测试验证：QA Agent
+- 文档编写：Doc Gen Agent
+
+---
+
+### 获取帮助
+
+- 查看 `QUICKSTART.md` 了解使用方法
+- 查看 `README.md` 了解完整说明
+- 查看 `architecture-design.md` 了解技术细节
+- 查看 `CHANGELOG.md` 了解变更历史
+- 查看 `Test/test_report.md` 了解测试详情
+
+---
+
 ## v1.2.0 — 2026-05-28
 
 ### ✨ 新增 PinList → PinMAP 反向转换