docs: 为全部13个源码模块和5个测试文件添加简体中文注释

- 每个文件补充模块级 docstring、类/函数 docstring、关键逻辑行内注释
- 注释风格："中文说明" 或 # 中文说明
- 代码结构和逻辑完全不变

a1_swap_mod_packer/archive.py

@@ -1,16 +1,33 @@
+"""ZIP 归档文件中 G-code 成员的读取与解析。
+
+本模块提供了从 .3mf 或 .zip 归档文件中列出 G-code 文件路径的功能，
+主要用于识别 Metadata 目录下按 plate_<编号>.gcode 命名的换板 G-code 文件。"""
+
 from __future__ import annotations
 
 import re
 import zipfile
 
+# 匹配 Metadata 目录下 plate_<数字>.gcode 格式的文件名
 GCODE_MEMBER_RE = re.compile(r"^Metadata/plate_(\d+)\.gcode$")
+# 匹配对应的 MD5 校验文件 plate_<数字>.gcode.md5
 MD5_MEMBER_RE = re.compile(r"^Metadata/plate_(\d+)\.gcode\.md5$")
 
 
 def list_gcode_members(archive: zipfile.ZipFile) -> list[str]:
+    """列出归档文件中所有 plate G-code 成员，按板号升序排列。
+
+    参数:
+        archive: 已打开的 ZIP 归档文件对象。
+
+    返回:
+        按 plate 编号从小到大排序的 G-code 文件名列表。
+    """
     members: list[tuple[int, str]] = []
     for name in archive.namelist():
         match = GCODE_MEMBER_RE.match(name)
         if match:
+            # 提取板号并存储 (板号, 文件名) 元组
             members.append((int(match.group(1)), name))
+    # 按板号升序排列后只返回文件名
     return [name for _, name in sorted(members)]