fcdp 20261015__py3-none-any.whl

_shared.py

@@ -0,0 +1,3418 @@
+"""
+_shared.py -- 共享数据容器, 常量, 配置和通用辅助函数。
+
+项目核心文件之一, 不依赖 Tkinter (界面文案常量只是字符串, 不 import tkinter)。
+除本职内容外另含三个分区: 「安装形态判别与配置路径解析」「版本检查」「自更新」
+(拉起独立更新器进程, 见 AGENTS.md); 三者均为边界例外, 同类逻辑不要再新增到本模块。
+"""
+
+import sys
+import os
+import site
+import subprocess
+import sysconfig
+from pathlib import Path
+import re
+from importlib.metadata import distribution
+_PROJECT_ROOT = Path(__file__).resolve().parent  # 包目录 (代码所在目录), 不依赖 CWD
+
+import pandas as pd
+import numpy as np
+from datetime import datetime
+from dataclasses import dataclass, field, fields, MISSING
+from typing import Any, Callable, Literal
+import json
+import traceback
+from scipy.stats import linregress
+
+
+# =========================
+# 公开符号
+# =========================
+
+__all__ = [
+    # 模块常量
+    '_PROJECT_ROOT',
+    # 常量类
+    'UiText', 'Columns', 'PhysicalConstants', 'PHYS',
+    'HUPD_DIRECTION_TUPLE',
+    # Config
+    'Config', 'build_config', 'validate_config',
+    # 安装形态判别与配置路径解析
+    'DIST_NAME', 'detect_install_mode', 'user_config_dir', 'resolve_config_path',
+    'write_config_file', 'resource_path', 'dist_info_file',
+    # 版本检查 (原 version_check.py)
+    'PYPI_JSON_URL', 'GITLAB_RAW_URL', 'RELEASES_PAGE_URL',
+    'STATUS_NEWER', 'STATUS_UP_TO_DATE', 'STATUS_FAILED',
+    'VersionCheckResult', 'compare_versions', 'check_for_update', 'changelog_path',
+    'CHANGELOG_FILE_NAME', 'BUNDLED_DOC_DIR',
+    # 自更新 (检查更新 -> 用户确认 -> 更新器执行 pip -> 下次启动读结果)
+    'UPDATE_RESULT_FILE_NAME', 'PIP_INSTALL_FLAGS',
+    'is_updatable_install', 'build_install_command',
+    'update_result_path', 'update_result_paths',
+    'write_update_result', 'read_update_result',
+    'build_updater_payload', 'start_self_update',
+    # 运行期服务
+    'RuntimeServices',
+    'LogMessage',
+    # 数据容器
+    'IvMeanResult', 'IvContext', 'IvRunParams',
+    'create_iv_run_params',
+    'H2CrossoverData',
+    'InteractivePeakSelector', 'CoEcsaResult', 'HupdEcsaResult', 'CoEcsaSession', 'HupdEcsaSession',
+    'LinearFitResult',
+    'OxygenResult', 'OxygenCurveRecord', 'OxygenFitRecord', 'OxygenResistanceResult',
+    'FigureBundle', 'ExportFigure', 'TafelFit',
+    # Pipeline 输入/输出
+    'IvPipelineInput', 'IvPipelineOutput',
+    'EcsaPipelineInput', 'CoEcsaPipelineOutput', 'HupdEcsaPipelineOutput',
+    'OxygenPipelineInput', 'OxygenPipelineOutput',
+    'EisPipelineInput', 'EisPipelineOutput',
+    # EIS 结果
+    'EisFitSegment', 'EisFileResult',
+    # 文件读取结果
+    'FcdFileResult', 'EcsaDataResult',
+    # 通用预读结果
+    'FilePreRead',
+    # 工具函数
+    'concat_plot_data_indices',
+    'safe_linear_fit', 'calculate_hupd_ecsa_averages',
+    'calculate_oxygen_resistance_result', 'calculate_oxygen_corrected_resistance',
+    # DTA 检测
+    'detect_dta_subtype', 'DTA_SUBTYPE_O2', 'DTA_SUBTYPE_EIS',
+    # O2 文件模型
+    'OxygenFileData', 'parse_oxygen_file_conditions',
+    # 下划线辅助 (被其他模块显式导入)
+    '_extract_config_fields', '_auto_output_path', '_get_modified_config_fields',
+    # 统一命名辅助 (被 gui/cli 显式导入)
+    'extract_folder_name', 'build_output_filename', 'panel_key_to_mode',
+]
+
+
+# =========================
+# 界面文本常量
+# =========================
+
+class UiText:
+    '''
+    用途: 集中保存界面标签文本常量。
+
+    调用: 由 GUI (gui.py) 的各面板与 ConfigEditorDialog 读取。
+    '''
+    RAW_FILE = '原始文件: '
+    EXPORT_FILE = '导出文件: '
+    NO_FILE_SELECTED = '未选择文件'
+    DATA_PATH = '数据路径'
+    SAVE_PATH = '保存路径'
+    RESTART = '重启'
+    START_PROCESS = '开始处理'
+    OPEN_RESULT = '打开结果'
+
+    H2_SLOPE = 'H2斜率:'
+    H2_INTERCEPT = 'H2截距:'
+    USE_LEFT_VALUE = '使用左值'
+
+    EXPORT = '导出'
+    ECSA_CO_BASELINE = '扣基线ECSA (m2/g_Pt):  '
+    ECSA_CO_LINEAR = '扣直线ECSA (m2/g_Pt):  '
+    ECSA_LEFT_POINT = '左端点'
+    ECSA_RIGHT_POINT = '右端点'
+    ECSA_BASELINE_ABOVE = '基线以上'
+    ECSA_BASELINE_BELOW = '基线以下'
+
+    EIS_HF_FIT = 'HF拟合 (mΩ):'
+    EIS_HF_INTERP = 'HF插值 (mΩ):'
+    EIS_HF_START = 'HF左端点'
+    EIS_HF_END = 'HF右端点'
+    EIS_LF_START = 'LF左端点'
+    EIS_LF_END = 'LF右端点'
+    CONFIG = '配置'
+
+    # 主窗口与日志面板
+    WINDOW_TITLE = '燃料电池数据处理平台'
+    LOG_COL_LABEL = '项目'
+    LOG_COL_TEXT = '结果'
+    LOG_INITIAL = '应用程序日志'
+    LOG_CLEARED = '--- 日志已清空 ---'
+
+    # 配置编辑窗口
+    CONFIG_EDITOR_TITLE = 'FCDP 配置编辑'
+    CONFIG_FILE_PREFIX = '配置文件: '
+    CONFIG_APPLY_ONLY = '直接应用'
+    CONFIG_SAVE_APPLY = '保存并应用'
+    CONFIG_RESET_ALL = '全部恢复默认'
+    NO_EXPORT_DIR = '(未设置导出目录)'
+
+    # 主窗菜单栏
+    MENU_FILE = '文件'
+    MENU_TOOLS = '工具'
+    MENU_HELP = '帮助'
+    MENU_DATA_PREVIEW = '数据预览'
+    MENU_ABOUT = '关于程序'
+    MENU_EXIT = '退出'
+    MENU_VERSION = '版本信息'
+
+    # 检查更新 (菜单项文字随检查状态变化; 状态由 gui.py 会话内变量维护)
+    CHECK_UPDATE = '检查更新'
+    CHECK_MENU_NEWER = '检查更新 (已有新版本 {latest})'
+    CHECK_MENU_UP_TO_DATE = '检查更新 (已是最新 {current})'
+    CHECK_MENU_FAILED = '检查更新 (检测失败)'
+    CHECK_MENU_CHECKING = '检查更新 (正在检查...)'
+    CHECK_TITLE = '检查更新'
+    CHECK_DIALOG_NEWER_TITLE = '发现新版本'
+    CHECK_DIALOG_NEWER_BODY = ('发现新版本 {latest}\n当前版本: {current}\n\n'
+                              '建议更新到新版本; 也可先看更新说明了解变更。')
+    CHECK_DIALOG_UP_TO_DATE_TITLE = '已是最新版本'
+    CHECK_DIALOG_UP_TO_DATE_BODY = '当前版本 {current} 已是最新。'
+    CHECK_DIALOG_FAILED_TITLE = '未能检查更新'
+    CHECK_DIALOG_FAILED_BODY = ('本次未能连接更新服务器, 不影响程序使用。\n\n'
+                               '可稍后重试; 也可先看更新说明了解已知变更。')
+    CHECK_BTN_OPEN_PAGE = '打开下载页'
+    CHECK_BTN_VIEW_CHANGELOG = '查看更新说明'
+    CHECK_BTN_UPDATE_NOW = '立即更新'
+    CHECK_BTN_LATER = '稍后'
+    CHECK_BTN_OK = '确定'
+    # 程序内自更新 (仅 pip 安装形态可点; 判据见 _shared.is_updatable_install)
+    # 不变式: 确认框是**退出前最后一个界面动作** (确认 -> 拉起更新器 -> 立即退出),
+    #         确认之后不得再弹任何模态框; 更新器只等 60 s, 界面多留一刻,
+    #         "磁盘已换, 内存还是旧版"的不一致窗口就长一刻。
+    CHECK_UPDATE_CONFIRM = ('即将把程序更新到 {latest}\n'
+                            '当前版本: {current}\n'
+                            '更新位置: {target}\n\n'
+                            '更新由独立进程在程序退出后执行, 需要联网, 更新期间请勿断网;\n'
+                            '完成后请手动重新打开程序, 届时会提示更新结果。\n'
+                            '该位置若没有写权限 (如全局 site-packages 属管理员所有), 更新会失败。\n'
+                            '是否继续?')
+    CHECK_UPDATE_START_FAILED = ('未能启动更新进程。\n\n'
+                                '可稍后重试; 也可在命令行执行 pip install --upgrade fcdp 手动更新。')
+    CHECK_UPDATE_FAILED_HINT = ('当前版本仍可正常使用, 可依次尝试:\n'
+                                '1) 以管理员身份重新打开程序后再执行一次更新 (该位置需要写权限);\n'
+                                '2) 在命令行执行 pip install --upgrade --no-deps '
+                                '--disable-pip-version-check --no-input --target "{target}" fcdp\n'
+                                '3) 或执行 pip install --user fcdp 装到用户目录 '
+                                '(它优先于系统目录被加载, 之后仍可在程序内一键更新)。')
+    CHECK_UPDATE_NOT_AVAILABLE = ('本机这份程序不是 pip 安装形态 (源码副本或开发仓库), '
+                                 '无法在程序内自动更新。\n\n'
+                                 '本程序唯一的分发与升级方式是 pip, 请先执行:\n'
+                                 '    pip install fcdp\n'
+                                 '装好后从 pip 的那份启动, 即可在程序内一键更新;\n'
+                                 '也可以用 pip install -U fcdp 手动升级。\n\n'
+                                 '源码副本可用, 但不提供维护: 需要新版请重新 clone / 拉取源码。')
+    CHECK_CHANGELOG_MISSING = ('本机没有找到 CHANGELOG 文件\n'
+                               '(它随 wheel 分发, 正常安装应当存在;\n'
+                               '只有在安装目录被手工清理过时才会缺失)。\n\n'
+                               '是否打开下载页查看各版本说明?')
+    CHECK_OPEN_PAGE_FAILED = '无法打开浏览器, 请手动访问:\n{url}'
+
+    # 关于程序对话框 (内容尽量少: 能打开此窗口即说明程序已正常运行)
+    ABOUT_FEATURES = '功能: 燃料电池测试数据处理 (IV / H2 / MA / CO-ECSA / HUPD-ECSA / O2 / EIS)'
+    ABOUT_LICENSE = '许可: MIT'
+    ABOUT_HOMEPAGE = '程序主页: {url}'
+    ABOUT_BTN_README = '程序介绍'
+    ABOUT_BTN_LICENSE = '许可协议'
+    ABOUT_BTN_OK = '确定'
+    ABOUT_DOC_MISSING = '(本安装未提供该文件, 对应按钮已灰显)'
+    ABOUT_DOC_OPEN_FAILED = '无法打开 {path}\n{error}'
+    # 程序主页 (源码托管); 发布到其他平台时改这一处即可
+    HOMEPAGE_URL = 'https://git.ustc.edu.cn/maoyan/fcdp'
+
+    # 数据预览窗口
+    PREVIEW_TITLE = 'FCD 数据预览'
+    PREVIEW_HINT_INITIAL = '左键勾选列加入 Y1; 右键列名可设置 X / Y1 / Y2 / 不绘制'
+    PREVIEW_HINT_NEED_Y = '当前没有有效的 Y 列, 请至少勾选一个 Y 列'
+    PREVIEW_DTA_UNSUPPORTED = 'DTA 文件暂不支持预览, 请选择 .fcd 文件'
+    PREVIEW_READ_FAILED = '读取文件失败, 无法预览'
+    PREVIEW_CHOOSE_TITLE = '选择要预览的 FCD 文件'
+    PREVIEW_OPEN_OTHER = '打开其他文件...'
+    PREVIEW_PROCESS_FILE = '处理文件: '
+    PREVIEW_PROCESS_FILE_NONE = '(尚未选择, 本窗仅预览)'
+    PREVIEW_TIME_SYNC = '对应 Time (Sec):'
+    PREVIEW_RANGE_TITLE = '数据点索引'
+    PREVIEW_RANGE_TO = '至'
+    PREVIEW_REDRAW = '重绘'
+    PREVIEW_SET_X = '设为 X'
+    PREVIEW_SET_Y1 = '设为 Y1'
+    PREVIEW_SET_Y2 = '设为 Y2'
+    PREVIEW_SET_NONE = '不绘制'
+    PREVIEW_NOT_Y = '不可作 Y'
+    PREVIEW_AXIS_X_CLEARED = 'X 列变更, 同名 Y 列已从绘制中移除'
+    PREVIEW_RANGE_INVALID = '数据点索引无效, 已回填合法范围'
+    PREVIEW_RANGE_ROUNDED = '数据点索引已按四舍五入取整'
+    PREVIEW_DUPLICATE_COLUMNS = '文件存在重名列, pandas 已自动改名 (如 A.1), 请以列表框显示为准'
+    PREVIEW_CANCELLED = '已取消选择预览文件'
+    PREVIEW_IS_X_COLUMN = '该列当前是 X 轴, 如需改轴次请右键'
+    PREVIEW_CANNOT_BE_Y = '{name} 不能作为 Y 列'
+    PREVIEW_CJK_HINT = '提示: 列名 {names} 含中文字形, 图中无法显示'
+    PREVIEW_UNAVAILABLE = '预览不可用'
+
+    # 弹窗标题
+    ASK_TITLE = '询问'
+    CFG_ERROR = '配置错误'
+    CFG_WARNING = '配置警告'
+    SUCCESS_SUFFIX = '成功'
+    CONFIRM_RESET = '确认重置'
+    APPLY_ERROR = '应用错误'
+    SAVE_FAIL = '保存失败'
+
+
+# =========================
+# 列名常量
+# =========================
+
+class Columns:
+    '''
+    用途: 集中保存原始列, 派生列和导出列名称。
+
+    调用: 由 computations / plotting / excel_export 的解析, 计算, 绘图与导出流程读取。
+    '''
+    T = 'Time (Sec)'
+
+    IA = 'I (A)'
+    '''电流 (A)'''
+
+    I = 'I (mA/cm²)'
+    '''电流密度 (mA/cm²)'''
+
+    E = 'E_Stack (V)'
+
+    HFR = 'HFR (mOhm)'
+
+    Status = 'Ctrl_Status'
+    '''3: 程序运行中'''
+
+    Mode = 'Ctrl_Mode'
+    '''1: 控制电压; 0: 控制电流'''
+
+    Value = 'Ctrl_Value'
+    '''控制电压/电流的值'''
+
+    MultigasCa = 'Multigas_Cathode'
+
+    TempCa = 'Ctrl_Temp_Cathode (C)'
+    '''阴极加湿罐设定温度'''
+
+    TempCell = 'Cell Temp (C)'
+
+    Real_TempCell = 'Temp (C)'
+
+    Real_TempCa = 'Temp_Cathode (C)'
+
+    FlowAn = 'Ctrl_Flow_Anode (l/min)'
+
+    FlowCa = 'Ctrl_Flow_Cathode (l/min)'
+
+    Freq = 'Z_Freq (Hz)'
+
+    Z_real = 'Z_Real (Ohm)'
+
+    Z_imag = 'Z_Imag (Ohm)'
+
+    Z_Mag = 'Z_Mag (Ohm)'
+
+    _RH = 'RH (%)'
+
+    _ECor = 'E HFR correction (V)'
+
+    @classmethod
+    def raw_columns(cls) -> list[str]:
+        '''
+        用途: 返回所有原始来源列名。
+
+        调用: 由 FCD/DTA 解析流程与测试调用。
+        返回: 返回列名列表。
+        '''
+        return [value for key, value in vars(cls).items() if not key.startswith('_') and isinstance(value, str)]
+
+    @classmethod
+    def final_columns(cls) -> list[str]:
+        '''
+        用途: 返回最终 IV 导出列名。
+
+        调用: 由 IV 均值表构建流程调用。
+        返回: 返回列名列表。
+        '''
+        return [cls.T, cls.I, cls.E, cls.HFR, cls.Value, cls._RH, cls._ECor]
+
+    @classmethod
+    def detail_columns(cls) -> list[str]:
+        '''
+        用途: 返回 IV 详情表列名。
+
+        调用: 由 IV 均值表构建流程调用。
+        返回: 返回列名列表。
+        '''
+        return [cls.Status, cls.Mode, cls.Value, cls.MultigasCa, cls.TempCell, cls.Real_TempCell, cls.TempCa, cls.Real_TempCa]
+
+
+# =========================
+# 物理常量
+# =========================
+
+@dataclass(frozen=True)
+class PhysicalConstants:
+    '''
+    用途: 集中保存物理常量, 避免魔法数字散落在计算代码中。
+
+    调用: 由 computations.py 的计算函数和 excel_export.py 使用。
+    '''
+    # ---- 电化学 ----
+    FARADAY_CONSTANT: float = 96485.0       # C/mol, 法拉第常数
+    GAS_CONSTANT: float = 8.314             # J/(mol·K), 通用气体常数
+
+    # ---- 温度 ----
+    CELL_TEMPERATURE_K: float = 353.15      # 80°C in K
+    CELSIUS_TO_KELVIN_OFFSET: float = 273.15  # 准确的 0°C→K 偏移量 (≈273, 精确 273.15)
+
+    # ---- ECSA ----
+    # 标准电荷密度值 (C/cm²):
+    CO_STRIPPING_CHARGE_DENSITY: float = 0.00042   # C/cm², CO 脱附电荷密度 (420 μC/cm²)
+    HUPD_CHARGE_DENSITY: float = 0.00021           # C/cm², HUPD 脱附电荷密度 (210 μC/cm²)
+    HUPD_VOLTAGE_WINDOW_MAX_V: float = 0.4         # V, HUPD 基线点电位窗口上限
+    # 计算时 pt_usage 单位为 mg/cm², 输出单位为 m²/g_Pt。
+    # cm²→m² 除以 10000,mg→g 乘以 1000, 合并转换因子 = 10。
+    CM2_MG_TO_M2_G: float = 10.0                   # cm²/mg → m²/g_Pt 单位转换因子 (10000/1000)
+
+    # ---- CO 自动选点阈值 ----
+    CO_LEFT_MIN_VOLTAGE: float = 0.4               # V, 左侧端点/峰搜索最小电位 (排除 H 区)
+    CO_RIGHT_WARN_VOLTAGE: float = 0.8             # V, 右端点超过此电位时发出警告
+
+    # ---- 湿度计算 ----
+    RH_EMPIRICAL_CONSTANT: float = 5148  # 经验常数, 用于相对湿度计算
+
+    # ---- O2 传输阻力 ----
+    WATER_VAPOR_PRESSURE_KPA: float = 33.3850272990271  # kPa, 精确值, 80°C时水蒸气饱和压力
+    AMBIENT_PRESSURE_KPA: float = 100.0       # kPa, 环境压力 (背景)
+    O2_D_ON_NAFION: float = 0.186874772957424  # cm²/s, O2 在 Nafion 中扩散系数
+    O2_D_OW_WATER: float = 0.238499175944215  # cm²/s, O2 在水中扩散系数
+    O2_CORRECTION_FACTOR_1: float = 1.01       # 修正因子 1
+    O2_CORRECTION_FACTOR_2: float = 0.08       # 修正因子 2 (边界层厚度相关)
+
+    # ---- 单位转换 ----
+    MA_TO_A: float = 1e-3                      # mA -> A
+    MOHM_TO_OHM: float = 1e-3                  # mΩ -> Ω
+    LPM_TO_MLS: float = 1000.0 / 60.0          # L/min -> mL/s
+    BAR_TO_KPA: float = 10.0                   # bar -> kPa
+
+    # ---- O2 阻力计算 ----
+    WATER_VAPOR_PRESSURE_BAR: float = 0.3338   # bar, 80°C 水蒸气分压
+    R_TOTAL_UNIT_DIVISOR: float = 100.0         # R_total 公式单位归一化因子
+
+    # ---- H2/IV 经验阈值 ----
+    IV_CURRENT_TOLERANCE_MA_CM2: float = 10.0   # mA/cm², IV 有效电流密度偏差容限
+    IV_HFR_UPPER_LIMIT_MOHM_CM2: float = 250.0  # mΩ·cm², IV 有效 HFR 上限 (面积比电阻)
+    MA_HFR_MIN_MOHM_CM2: float = 25.0           # mΩ·cm², MA 有效 HFR 下限 (面积比电阻)
+    MA_HFR_MAX_MOHM_CM2: float = 100.0          # mΩ·cm², MA 有效 HFR 上限 (面积比电阻)
+
+    # ---- 活化/Conditioning 检测 ----
+    CONDITIONING_MIN_DURATION_S: float = 1800.0  # s, 活化段最小持续时间 (30min)
+    CONDITIONING_GAP_WARN_S: float = 3600.0      # s, 活化段间非零电流累计时长阈值 (1h)
+
+    # ---- 近零值全局阈值 ----
+    SMALL_VALUE: float = 1e-12                   # 通用极小值阈值, 用于避免除零, 浮点零比较等
+
+
+PHYS = PhysicalConstants()
+'''便捷访问实例'''
+
+
+HUPD_DIRECTION_TUPLE: tuple[str, str] = ('baseline above', 'baseline below')
+'''HUPD 基线方向选项元组。索引 0 为"基线以上", 索引 1 为"基线以下"。
+
+    注意: 字符串值直接绑定 GUI 单选按钮 value, 且用于 calculate_hupd_ecsa_result
+    的 direction 参数匹配, 因此保持英文。'''
+
+# ---- DTA 子类型常量 ----
+DTA_SUBTYPE_O2: Literal['o2'] = 'o2'
+'''DTA 文件子类型: O2 氧传输阻力 (LSV 曲线)'''
+DTA_SUBTYPE_EIS: Literal['eis'] = 'eis'
+'''DTA 文件子类型: EIS 阻抗谱 (用于 H+ 质子传导阻力计算)'''
+
+
+# =========================
+# 安装形态判别与配置路径解析
+# =========================
+
+# 发行版名, 与 pyproject.toml 的 [project].name 一致。用于 importlib.metadata 查询安装元数据。
+DIST_NAME: str = 'fcdp'
+
+
+def _site_dirs() -> list[Path]:
+    '''
+    用途: 收集当前解释器的全部 site-packages 目录 (必须包含 user site)。
+
+    调用: 由 `detect_install_mode` 调用。
+
+    返回: 去重后的绝对路径列表; 解释器未提供该项时不入列表。
+
+    注意: 只保留目录名形如 site-packages / dist-packages 的路径。理由: Windows 上
+          site.getsitepackages() 还会返回解释器根目录 (如 C:\\Program Files\\Python312),
+          若把它当作 site 目录, 则位于该根目录之下的普通源码目录会被误判为 pip 安装。
+          另外本函数对任何单个取目录失败都静默跳过 (判别不应因环境差异抛异常)。
+    '''
+    raw: list[str] = []
+    try:
+        paths = sysconfig.get_paths()
+        for key in ('purelib', 'platlib'):
+            value = paths.get(key)
+            if isinstance(value, str) and value:
+                raw.append(value)
+    except Exception:
+        pass
+    try:
+        user_site = site.getusersitepackages()
+        if isinstance(user_site, str) and user_site:
+            raw.append(user_site)
+    except Exception:
+        pass
+    try:
+        for item in site.getsitepackages():
+            if isinstance(item, str) and item:
+                raw.append(item)
+    except Exception:
+        pass
+
+    dirs: list[Path] = []
+    for item in raw:
+        resolved = Path(item).resolve()
+        name = resolved.name.lower()
+        if not (name.endswith('site-packages') or name.endswith('dist-packages')):
+            continue                            # 排除解释器根目录等非 site 目录
+        if resolved not in dirs:
+            dirs.append(resolved)
+    return dirs
+
+
+def _dist_located_at(dist, module_dir: Path) -> bool:
+    '''
+    用途: 判断发行版元数据声明的安装位置是否就是本模块所在目录。
+
+    参数:
+        dist: `importlib.metadata.Distribution` 实例。
+        module_dir: 当前运行的核心模块所在目录。
+
+    调用: 由 `detect_install_mode` 调用。
+
+    返回: 安装位置与模块目录一致时返回 True; 无法判定或元数据不可读时返回 False。
+
+    注意: 复制源码目录里若夹带旧 dist-info, 元数据可能指向 site-packages 而代码在别处,
+          此时必须返回 False, 否则会把复制版误判为 pip 安装。
+    '''
+    try:
+        located = Path(dist.locate_file('')).resolve()
+    except Exception:
+        return False
+    return located == module_dir
+
+
+def detect_install_mode(module_file: Path | str) -> str:
+    '''
+    用途: 判别程序来源, 决定配置归属。只看本机安装事实, 不 import 目标模块, 不读配置文件。
+
+    参数:
+        module_file: 任一核心模块的 __file__ (调用方传 `_shared.__file__`)。
+
+    调用: 由 `resolve_config_path` 与 `is_updatable_install` 调用; 诊断日志亦可直接调用。
+
+    返回: 'local' (本目录副本 / 开发仓库) | 'pip-install' (装入 site-packages)
+          | 'editable' (开发可编辑安装)。
+
+    注意: 判别流程 (两道闸门, 任一不成立即为 local):
+          ① 代码文件必须位于某个 site-packages 之下, 位于 site 即"装进去的",
+             即使元数据缺失 (安装残缺 / 手工拷贝) 也按 pip 安装对待, 否则配置会写进安装目录,
+             升级按 RECORD 删除即丢用户设置;
+          ② 元数据声明的安装位置必须与模块目录一致, 复制源码目录里夹带的残留 dist-info
+             不会让它被误判为 pip 安装; 含 direct_url.json 的 dir_info 记为 editable。
+          本函数**保证不抛异常** (判别属旁路逻辑, 任何环境差异都不得阻断启动);
+          冻结应用 (PyInstaller 等) 无可靠 __file__, 需另走 sys.frozen 分支; 当前不打包 exe, 故不实现。
+    '''
+    try:
+        here = Path(module_file).resolve()
+        module_dir = here.parent
+        site_dirs = _site_dirs()
+    except Exception:
+        return 'local'
+
+    if not any(here.is_relative_to(d) for d in site_dirs):
+        return 'local'                          # 不在任何 site-packages 之下 -> 本目录副本
+
+    try:
+        dist = distribution(DIST_NAME)
+    except Exception:
+        return 'pip-install'                    # 在 site 但元数据缺失 -> 仍按 pip 安装对待
+    if not _dist_located_at(dist, module_dir):
+        return 'local'                          # 元数据指向别处 (残留 dist-info) -> 本目录副本
+    try:
+        direct = dist.read_text('direct_url.json')   # PEP 610; 标准索引安装无此文件
+    except Exception:
+        direct = None
+    return 'editable' if direct and 'dir_info' in direct else 'pip-install'
+
+
+def user_config_dir() -> Path:
+    '''
+    用途: 返回用户数据目录中的配置目录 (pip 安装形态的配置归属, 也是更新结果文件的首选目录)。
+
+    调用: 由 `resolve_config_path` (pip 安装形态) 与 `_local_appdata_root` 调用。
+
+    返回: Windows 为 %LOCALAPPDATA%\\FCDP; 其他平台为 $XDG_CONFIG_HOME/fcdp (缺省 ~/.config/fcdp)。
+
+    注意: 取 LOCALAPPDATA 而非 APPDATA, 因为配置中的 data_path_default/result_path/device_map
+          与本机实验环境绑定, 属机器状态, 不应随域漫游同步。仅 Windows 为官方支持平台,
+          其他平台分支保留但不承担验证义务。环境变量异常或家目录取不到时回退为包目录。
+    '''
+    try:
+        local = os.environ.get('LOCALAPPDATA')
+        if local:
+            return Path(local) / 'FCDP'
+        xdg = os.environ.get('XDG_CONFIG_HOME')
+        return (Path(xdg) if xdg else Path.home() / '.config') / 'fcdp'
+    except Exception:
+        return _PROJECT_ROOT
+
+
+def resolve_config_path(explicit: Path | str | None = None) -> tuple[Path, bool]:
+    '''
+    用途: 解析本次运行使用的配置文件路径, 并给出该文件是否已存在。
+
+    参数:
+        explicit: 显式指定的路径 (CLI --config / run_pipeline config_path); None 表示未指定。
+
+    调用: 由 `build_config` (json_path 为 None 时) 与 GUI 配置编辑器调用。
+
+    返回: `(配置文件路径, 是否已存在)`。后两档路径可能尚不存在, 由调用方决定是否首建。
+
+    注意: 本函数只做判定, 不创建文件, 不写盘, 不写日志 (启动时只读不写)。
+          归属规则: 显式指定 > `FCDP_CONFIG` > (pip 安装 ? 用户数据目录 : **本目录**)。
+          即: 只有 pip 装进 site-packages 的那份读机器级配置; 其余一切形态 (源码副本 /
+          开发仓库 / 手工拷贝的副本) 都读写**本目录**的 config.json: 本目录没放时只用内置
+          默认值 (不回退用户目录, 避免同机多份副本互相串配置), 并在**首次保存时生成在本目录**,
+          使整目录可携带。
+          启动器不设 `FCDP_CONFIG`, 也不介入本判定; 因此"双击 launch.py"与"直接双击 gui.py"
+          读到的是同一份配置。
+          本函数保证不抛异常: 任何判定环节出错都回退为"本目录副本"语义。
+    '''
+    try:
+        if explicit is not None:
+            path = Path(explicit)
+            return (path.resolve(), path.is_file())
+        env_path = os.environ.get('FCDP_CONFIG')
+        if env_path:
+            path = Path(env_path)
+            return (path.resolve(), path.is_file())
+        local_path = _PROJECT_ROOT / 'config.json'
+        if detect_install_mode(__file__) == 'pip-install':
+            user_path = user_config_dir() / 'config.json'
+            return (user_path, user_path.is_file())
+        return (local_path, local_path.is_file())
+    except Exception:
+        fallback = _PROJECT_ROOT / 'config.json'
+        return (fallback, fallback.is_file())
+
+
+def _resolve_default_config_path() -> Path:
+    '''
+    用途: 求值本进程的默认配置文件路径, 供 `Config._json_path` 默认值使用。
+
+    调用: 由 `Config` 字段 `default_factory` 调用。
+
+    返回: `resolve_config_path()` 的路径部分 (不关心文件是否存在)。
+
+    注意: **每次构造 `Config` 都会重新求值一次** (default_factory 的语义如此, 本函数不加缓存):
+          这是刻意保留的行为, 调用方在运行期改了 `FCDP_CONFIG` / `LOCALAPPDATA` 后再新建
+          `Config`, 理应拿到新的默认路径。想固定路径请显式传 `json_path` (CLI `--config`)。
+          对程序正常运行而言这个区别不可见: 求值出来的是同一份路径, 且没有任何调用方依赖"只求值一次"。
+          真实构造次数不止启动那一次: 记录配置变更的 `_get_modified_config_fields` 每次都会新建一个
+          默认 `Config` (即每次跑管线都会重新求值一次), `build_config` 也无条件触发一次 default_factory。
+          本函数在模块导入期由 `Config._json_path` 的 default_factory 首次调用, **绝不允许抛异常**
+          (否则整个模块 import 失败, 程序无法启动), 出错时回退为包目录下的 config.json。
+    '''
+    try:
+        return resolve_config_path()[0]
+    except Exception:
+        return _PROJECT_ROOT / 'config.json'
+
+
+# 随 wheel 分发的两份用户文档 (README.md / CHANGELOG.md) 的落点目录名。
+# pyproject.toml 的 [tool.setuptools.data-files] 以它为键, 装出来是 <Python 前缀>/fcdp/
+# (wheel 规范里 .data/data/ 只能装到"前缀", 装不进 site-packages 根)。
+BUNDLED_DOC_DIR = 'fcdp'
+
+
+def resource_path(file_name: str) -> Path | None:
+    '''
+    用途: 查找随程序提供的文件 (README / LICENSE / CHANGELOG 等)。
+
+    参数:
+        file_name: 文件名 (如 'README.md')。
+
+    调用: 由 GUI「关于程序」的"程序介绍 / 许可协议"按钮与「检查更新」的"查看更新说明"调用。
+
+    返回: 命中时返回绝对路径; 所有候选目录都没有时返回 None。
+
+    注意: 候选目录按"越贴近模块目录越优先"排列, 只查固定几层, 不递归 (递归会命中无关目录里的同名文件):
+          ① 模块目录 (源码副本 / 开发仓库 / editable 安装);
+          ② 模块目录的上一级 (兜底"模块放在子目录, 文档留在其上级"的布局);
+          ③ 模块目录/fcdp 与 <Python 前缀>/fcdp 与 <用户基础目录>/fcdp, 即 pip 安装形态的落点
+             (普通 venv / 系统安装落在前缀下, 自更新用的 `pip install --target` 落在代码目录下,
+             `pip install --user` 落在用户基础目录下), 见 [tool.setuptools.data-files]。
+    '''
+    try:
+        root = _PROJECT_ROOT
+        candidates = [
+            root,
+            root.parent,
+            root / BUNDLED_DOC_DIR,
+            Path(sys.prefix) / BUNDLED_DOC_DIR,
+        ]
+        if site.USER_BASE:
+            candidates.append(Path(site.USER_BASE) / BUNDLED_DOC_DIR)
+        seen: set[str] = set()
+        for directory in candidates:
+            key = str(directory)
+            if key in seen:
+                continue
+            seen.add(key)
+            candidate = directory / file_name
+            if candidate.is_file():
+                return candidate
+    except Exception:
+        return None
+    return None
+
+
+def dist_info_file(file_name: str) -> Path | None:
+    '''
+    用途: 在已安装发行版的元数据目录 (dist-info) 里查找文件 (pip 安装形态下 LICENSE 就在这里)。
+
+    参数:
+        file_name: 文件名 (如 'LICENSE')。
+
+    调用: 由 GUI「关于程序」的"许可协议"按钮调用 (先试它, 失败才回落到 `resource_path`:
+          pip 安装形态的 LICENSE 只存在于 dist-info 目录里)。
+
+    返回: 命中时返回绝对路径; 未安装 / 元数据里没有该文件时返回 None。
+
+    注意: 必须直接拼 dist-info 目录, **不能用 `distribution().locate_file()`**: 后者的基准
+          是 site-packages 而不是 dist-info (实测 `locate_file('LICENSE')` 得到
+          `site-packages\\LICENSE`, 那不是真实文件), 用它会让 pip 用户的许可按钮被错误置灰。
+          另: 新版 setuptools (PEP 639) 会把许可文件放到 `dist-info/licenses/`, 因此两处都查。
+    '''
+    try:
+        dist = distribution(DIST_NAME)
+        raw_path = str(getattr(dist, '_path', '') or '')
+        # 空 _path 必须在这里挡掉: str(Path('')) 等于 '.', 直接往下拼会去探测**当前工作目录**,
+        # 可能把 CWD 下同名的 LICENSE 当成发行版元数据里的文件返回 (打开无关内容)
+        if not raw_path:
+            return None
+        meta_dir = Path(raw_path)
+        for candidate in (meta_dir / file_name, meta_dir / 'licenses' / file_name):
+            if candidate.is_file():
+                return candidate
+        return None
+    except Exception:
+        return None
+
+
+def write_config_file(config_path: Path | str, payload: dict) -> None:
+    '''
+    用途: 把配置字典全量写入 JSON 文件, 必要时创建父目录 (首次保存即首建用户配置)。
+
+    参数:
+        config_path: 目标文件路径。
+        payload: 待写入的配置字典 (通常为 `_get_config_payload()` 的结果)。
+
+    调用: 由 GUI 配置编辑器保存流程调用。
+
+    返回: 无返回值; 文件 I/O 失败时抛出 OSError (由调用方提示用户)。
+
+    注意: 全量覆盖写入, 不做增量合并; 不写入下划线开头的内部字段 (由 payload 构造方保证)。
+    '''
+    path = Path(config_path)
+    if path.parent and not path.parent.exists():
+        path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, 'w', encoding='utf-8') as fp:
+        json.dump(payload, fp, indent=4, ensure_ascii=False)
+
+
+# =========================
+# 版本检查 (纯逻辑, 无 Tk 依赖; 不写任何文件)
+# =========================
+
+# 说明: 版本检查归在本模块内以减少顶层模块数, 不另设独立模块。
+#       只有 urllib 是函数内惰性导入, 根模块导入期不拉进网络栈。
+
+# =========================
+# 常量
+# =========================
+
+# 数据源 (主源 PyPI 的 JSON; 版本号单一来源为 _shared.__version__ 的 8 位 YYYYMMDD)
+PYPI_JSON_URL = 'https://pypi.org/pypi/fcdp/json'
+GITLAB_RAW_URL = ('https://git.ustc.edu.cn/api/v4/projects/maoyan%2Ffcdp'
+                  '/repository/files/_shared.py/raw?ref=master')
+RELEASES_PAGE_URL = 'https://pypi.org/project/fcdp/'
+CHANGELOG_FILE_NAME = 'CHANGELOG.md'
+
+# 请求标识: 便于对方在日志中识别来源 (README/文档均为公开地址)
+VERSION_CHECK_UA = 'FCDP-version-check'
+
+# 单次请求超时 (秒); 检查失败必须静默且不拖慢启动, 故取值偏短
+VERSION_CHECK_TIMEOUT_S = 4.0
+
+# 状态词表 (勿再扩; 与 UI 三态一一对应)
+STATUS_NEWER = 'newer'        # 发现新版本
+STATUS_UP_TO_DATE = 'up-to-date'   # 已是最新
+STATUS_FAILED = 'failed'      # 检查失败 (超时 / 网络不可达 / 响应非法)
+
+# 版本号解析: 单一来源为 _shared.__version__, 硬约定为 8 位日期式 YYYYMMDD
+# (pyproject.toml 的动态版本与 .gitlab-ci.yml 的 tag 校验都按这个格式)。**只认 8 位**:
+# 带点或其他长度的版本号一律落到"无法比较", 由上层如实报检查失败, 不得当成"没有新版本"。
+_VERSION_RE = re.compile(r'^\d{8}$')
+
+# 6 个核心模块的文件名 (自更新时用于清理"新版已删除"的残留; 与 pyproject 的 py-modules 对应)
+CORE_MODULE_NAMES: tuple[str, ...] = ('_shared.py', 'computations.py', 'plotting.py',
+                                      'excel_export.py', 'gui.py', 'cli.py')
+
+
+def _version_tuple(raw: str) -> tuple[int, ...] | None:
+    '''
+    用途: 把版本号字符串解析为可比较的整数元组。
+
+    参数:
+        raw: 版本号字符串 (项目硬约定为 8 位日期式, 如 '20260814')。
+
+    调用: 由 `compare_versions` 调用。
+
+    返回: 单元素元组 (如 (20260814,)); 非 8 位纯数字形式 (空串, 字母, 连字符, 带点形式, 脏数据)
+          时返回 None。
+
+    注意: 只认 8 位数字, 不兼容 '2026.8.14' 这类形式。日期式的字典序与数值序一致, 因此解析为
+          整数比较即可; 而长度不同的元组比较会让带点版本被误判为更旧 (见 `_VERSION_RE` 的说明)。
+    '''
+    text = (raw or '').strip()
+    if not _VERSION_RE.match(text):
+        return None
+    return (int(text),)
+
+
+def compare_versions(candidate: str, current: str) -> int | None:
+    '''
+    用途: 比较两个版本号。
+
+    参数:
+        candidate: 待比较的版本 (如远端最新版本)。
+        current: 当前版本。
+
+    调用: 由 `check_for_update` 调用; 测试直接调用。
+
+    返回: candidate > current 返回 1, 相等返回 0, 更旧返回 -1; 任一侧不是 8 位日期式时返回 None。
+
+    注意: 返回 None 表示"这一侧版本号不可用", 调用方按"该数据源没给出可用结果"处理 (换下一源,
+          全部源都不可用时如实报检查失败), **不得**当成"没有新版本"。
+    '''
+    left = _version_tuple(candidate)
+    right = _version_tuple(current)
+    if left is None or right is None:
+        return None
+    if left > right:
+        return 1
+    if left < right:
+        return -1
+    return 0
+
+
+# =========================
+# 结果对象
+# =========================
+
+@dataclass(frozen=True)
+class VersionCheckResult:
+    '''
+    用途: 承载一次版本检查的结果, 供 UI 与启动器消费。
+
+    字段:
+        status: STATUS_* 之一 (newer / up-to-date / failed)。
+        latest: 远端最新版本号; 检查失败时为 None。
+        current: 当前版本号 (由调用方传入)。
+        source: 命中数据源的标识 (来源 URL); 失败时为 None。
+        detail: 失败原因摘要 (如 'OSError: ...'), 由检查失败的弹窗展示; 成功时为 None。
+    '''
+    status: str
+    latest: str | None = None
+    current: str = ''
+    source: str | None = None
+    detail: str | None = None
+
+    @property
+    def has_new_version(self) -> bool:
+        '''是否发现新版本。'''
+        return self.status == STATUS_NEWER
+
+
+# =========================
+# 抓取
+# =========================
+
+def fetch_text(url: str, timeout: float = VERSION_CHECK_TIMEOUT_S) -> str:
+    '''
+    用途: 发起一次 GET 请求并返回解码后的文本 (可被注入替换以便离线测试)。
+
+    参数:
+        url: 目标 URL。
+        timeout: 超时秒数, 默认 VERSION_CHECK_TIMEOUT_S。
+
+    调用: 默认作为 `check_for_update` 的 fetcher 参数;
+
+    返回: 响应正文 (UTF-8 尽力解码)。
+
+    注意: 失败时抛出异常 (URLError / OSError / HTTPError 等), 由调用方统一捕获并转为
+          结果对象的 'failed' 状态; 本函数不自行吞异常, 以免掩盖真实原因。
+    '''
+    import urllib.request                   # 函数内导入: 根模块导入期不拉进网络栈
+    request = urllib.request.Request(url, headers={'User-Agent': VERSION_CHECK_UA})
+    with urllib.request.urlopen(request, timeout=timeout) as response:
+        payload = response.read()
+    return payload.decode('utf-8', 'replace')
+
+
+def _parse_pypi_version(text: str) -> str:
+    '''
+    用途: 从 PyPI JSON API 响应中取出最新已发布版本号。
+
+    参数:
+        text: `https://pypi.org/pypi/<name>/json` 的正文。
+
+    调用: 由 `build_check_urls` 注册进数据源列表, 再由 `check_for_update` 逐源调用。
+
+    返回: 版本号字符串 (如 '20260814')。
+
+    注意: 结构不符合预期 (无 info.version / 值不是字符串 / JSON 语法错) 时抛出 ValueError,
+          由上层转为 'failed', 绝不猜测版本号。
+    '''
+    data = json.loads(text)
+    version = data.get('info', {}).get('version') if isinstance(data, dict) else None
+    if not isinstance(version, str) or not version.strip():
+        raise ValueError('PyPI 响应中缺少 info.version')
+    return version.strip()
+
+
+def _parse_gitlab_source_version(text: str) -> str:
+    '''
+    用途: 从 GitLab 原始文件 (_shared.py) 正文中取出 `__version__` 常量值 (备份数据源)。
+
+    参数:
+        text: `_shared.py` 的完整正文。
+
+    调用: 由 `build_check_urls` 注册进数据源列表, 再由 `check_for_update` 逐源调用。
+
+    返回: 版本号字符串。
+
+    注意: 必须锚定行首的赋值语句。实测 _shared.py 的注释里也出现 `__version__` 字样,
+          若用宽松匹配会先命中注释行导致解析出错误内容。
+    '''
+    pattern = re.compile(r"^__version__\s*(?::\s*str\s*)?=\s*['\"](\d{8})['\"]", re.M)
+    match = pattern.search(text)
+    if match is None:
+        raise ValueError('GitLab 源码中未找到行首 __version__ 赋值')
+    return match.group(1)
+
+
+def build_check_urls() -> list[tuple[str, Callable[[str], str]]]:
+    '''
+    用途: 返回"数据源 → 解析器"的有序列表 (主源在前, 备源在后)。
+
+    调用: 由 `check_for_update` 调用; 测试可直接调用以核对数据源数量与顺序。
+
+    返回: `[(url, parser), ...]`; parser 接收响应正文, 返回版本号字符串。
+
+    注意: 顺序即优先级。PyPI 是权威"最新已发布版本"面; GitLab 仅作内网备份。
+    '''
+    return [
+        (PYPI_JSON_URL, _parse_pypi_version),
+        (GITLAB_RAW_URL, _parse_gitlab_source_version),
+    ]
+
+
+# =========================
+# 主入口
+# =========================
+
+def check_for_update(current_version: str,
+                     fetcher: Callable[[str], str] | None = None) -> VersionCheckResult:
+    '''
+    用途: 依次尝试各数据源, 取到最新版本后与当前版本比较, 返回结果对象。
+
+    参数:
+        current_version: 当前程序版本 (调用方传 `_shared.__version__`)。
+        fetcher: 抓取函数 (url) -> 正文; None 时使用 `fetch_text`。测试注入桩即可完全离线。
+
+    调用: 由 GUI 自动/手动检查通道调用; 测试直接调用并注入桩。
+
+    返回: `VersionCheckResult`。**任何异常都转为 status='failed' 的结果**, 不向调用方抛出。
+
+    注意: 本函数不做去重, 不写文件, 不打日志, 这些都由调用方负责。
+          数据源顺序固定为 `build_check_urls()`, 不开放注入 (测试用 fetcher 桩就能覆盖两条源)。
+    '''
+    active_fetcher = fetcher if fetcher is not None else fetch_text
+    last_detail: str | None = None
+
+    for url, parser in build_check_urls():
+        try:
+            text = active_fetcher(url)
+            latest = parser(text)
+            # 版本比较也放进 try: compare_versions 对非字符串入参会抛 (如 AttributeError),
+            # 它同样属于"这个源没给出可用结果", 不应破坏本函数"不向调用方抛异常"的约定
+            verdict = compare_versions(latest, current_version)
+        except Exception as ex:                     # 网络 / HTTP / JSON / 解析 一律视为该源失败
+            last_detail = f'{type(ex).__name__}: {ex}'
+            continue
+
+        if verdict is None:
+            last_detail = f'版本号无法比较 (远端 {latest!r} / 当前 {current_version!r})'
+            continue
+
+        return VersionCheckResult(
+            status=STATUS_NEWER if verdict > 0 else STATUS_UP_TO_DATE,
+            latest=latest,
+            current=current_version,
+            source=url,
+        )
+
+    return VersionCheckResult(
+        status=STATUS_FAILED,
+        current=current_version,
+        detail=last_detail or '所有数据源均不可用',
+    )
+
+
+# =========================
+# 辅助
+# =========================
+
+def changelog_path(base_dir: Path | str) -> Path:
+    '''
+    用途: 返回随包 CHANGELOG 的路径。
+
+    参数:
+        base_dir: 程序目录 (调用方传 `_shared._PROJECT_ROOT`)。
+
+    调用: 由 GUI「检查更新」对话框的"查看更新说明"按钮调用。
+
+    返回: CHANGELOG 的绝对路径。
+
+    注意: 仅拼路径, 不判断是否存在 (由调用方决定文件缺失时的提示)。
+          本函数只覆盖"文档与模块同目录 / 其上一级"这一档形态 (源码副本 / 开发仓库);
+          pip 安装形态的文档由 [tool.setuptools.data-files] 装到前缀下的 `fcdp/` 目录,
+          必须用 `resource_path(CHANGELOG_FILE_NAME)` 查 (它已包含本函数这一档并按优先级串联),
+          直接拿本函数的返回值会把 pip 用户误判成"文档缺失"。
+    '''
+    return Path(base_dir) / CHANGELOG_FILE_NAME
+
+
+# =========================
+# 配置常量
+# =========================
+
+# 版本号单一来源 (YYYYMMDD 日期式)。pyproject.toml 经 tool.setuptools.dynamic
+# attr = "_shared.__version__" 派生; GUI/CLI 亦直接引用此值, 避免多处手抄漂移。
+__version__: str = '20261015'
+
+@dataclass(frozen=True)
+class Config:
+    '''
+    用途: 应用级只读配置中心。通过 build_config() 从 config.json 合并默认值构建,
+         运行期不可变 (frozen=True)。所有可配置项集中于此, GUI ConfigEditor 以此驱动。
+
+    metadata 字段说明:
+        comment:   中文说明, 在 GUI ConfigEditor 中显示为行标签。
+        section:   配置分组标签, ConfigEditor 按此分组展示。
+                   GUI 当前支持: '全局', 'IV', 'ECSA', 'O2', 'EIS'。
+                   不在上述分组中的字段归入"其他参数"。
+        validation:可选的校验规则标识, 供 ConfigEditor 输入验证用。
+                   当前支持: 'positive_number' (正数), 'non_empty_list' (非空列表)。
+
+    注意:
+        - 以下划线开头的字段 (如 _json_path) 不会写入 config.json,
+          且不被 GUI ConfigEditor 展示。它们仅供程序内部使用。
+        - 列表字段 (如 o2_x_list) 写入 JSON 时为 list, 读取后自动转为 tuple
+          以保持 frozen dataclass 的不可变性。详见 build_config()。
+        - 新增配置项时, 只需在此 dataclass 中添加字段和 metadata,
+          其余 (config.json 读写, GUI 编辑) 自动适配。
+    '''
+
+    # ---- 元数据 ----
+    # 配置文件路径由 resolve_config_path() 解析: 显式指定 > FCDP_CONFIG >
+    # (pip 安装 ? 用户数据目录 : 本目录)。本目录副本没有 config.json 时用内置默认值, 首次保存生成在本目录。
+    # 每次构造 Config 都重新求值 (default_factory 语义); 下划线开头 -> 不写入 config.json, 也不被配置编辑器展示。
+    _json_path: Path = field(default_factory=_resolve_default_config_path)
+
+    # ---- 全局 ----
+    data_path_default: str = field(
+    default='', metadata={'comment': '默认数据文件所在父文件夹路径', 'section': '全局'},
+)
+    result_path: str = field(
+    default='', metadata={'comment': '默认导出文件存放路径', 'section': '全局'},
+)
+    draw_results: bool = field(
+    default=True, metadata={'comment': '是否绘制结果图', 'section': '全局'},
+)
+    # 公共参数 (跨管线共享)
+    cell_area: float = field(
+    default=5.0, metadata={'comment': '电池面积 (cm²)', 'section': '全局', 'validation': 'positive_number'},
+)
+    cell_area_auto: bool = field(
+    default=True, metadata={'comment': '自动从 .fcd 文件读取电池面积 (否则使用 cell_area)', 'section': '全局'},
+)
+    # 跨管线共享: Pt 载量 (mg/cm²), ECSA/O2 loading 分析用
+    pt_loading: float = field(
+    default=0.1, metadata={
+        'comment': '默认 Pt 载量 (mg/cm²)', 'section': '全局', 'validation': 'positive_number',
+    },
+)
+    fig_dpi: int = field(
+    default=100, metadata={'comment': '导出图片的 DPI(清晰度)', 'section': '全局'},
+)
+    processing_mode: str = field(
+    default='auto', metadata={'comment': '处理模式: auto(自动检测) / iv / hupd / co / o2, 强制指定处理方式', 'section': '全局'},
+)
+    auto_process: bool = field(
+    default=False, metadata={'comment': '选择文件后是否立刻开始处理 (否则需点开始处理按钮)', 'section': '全局'},
+)
+
+    # 版本检查开关: 只控制"启动时自动检查", 不影响帮助菜单的手动「检查更新」(手动始终可用)
+    auto_check_update: bool = field(
+    default=True, metadata={
+        'comment': '启动时自动检查新版本 (关闭后仍可用帮助菜单手动检查)', 'section': '全局',
+    },
+)
+
+    device_map: dict = field(
+        default_factory=dict, metadata={
+            'comment': '设备 SN→名称映射表 格式: SN1=名称1\\nSN2=名称2',
+            'section': '全局',
+        },
+    )
+
+    # ---- EIS ----
+    eis_min_r_squared: float = field(
+    default=0.999, metadata={'comment': 'EIS 线性拟合最低 R² 阈值 (默认 0.999)', 'section': 'EIS'},
+    )
+
+    # ---- IV ----
+    iv_mean_num: int = field(
+    default=6, metadata={
+        'comment': 'IV 取点数: 每段控制变化后取最后 N 个点平均',
+        'section': 'IV', 'validation': 'positive_number',
+    },
+)
+    h2_mean_num: int = field(
+    default=6, metadata={
+        'comment': 'H₂ crossover 取点数: 每个电压平台取最后 N 个点平均',
+        'section': 'IV', 'validation': 'positive_number',
+    },
+)
+    ma_mean_num: int = field(
+    default=6, metadata={
+        'comment': 'MA 取点数: 每段控制变化后取最后 N 个点平均',
+        'section': 'IV', 'validation': 'positive_number',
+    },
+)
+    iv_e_list: tuple = field(
+    default=(15, 14, 13, 12, 11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0.5, 0.2, 0.1, 0),
+    metadata={
+        'comment': 'IV 极化曲线电流设定值列表 (A)', 'section': 'IV', 'validation': 'non_empty_list',
+    },
+)
+    iv_e_match_min_num: int = field(
+    default=5, metadata={
+        'comment': 'IV 匹配所需的最小连续电流点个数', 'section': 'IV', 'validation': 'positive_number',
+    },
+)
+    iv_lookup_e_value_list: tuple = field(
+    default=(0.5, 0.6, 0.7, 0.8),
+    metadata={'comment': 'J@E 查找的电压点列表 (V)', 'section': 'IV', 'validation': 'non_empty_list'},
+)
+    iv_lookup_j_value_list: tuple = field(
+    default=(2000,),
+    metadata={'comment': 'E@J 查找的电流密度点列表 (mA/cm²)', 'section': 'IV', 'validation': 'non_empty_list'},
+)
+    h2_volt_list: tuple = field(
+    default=(0.3, 0.4, 0.5, 0.6),
+    metadata={'comment': 'H₂ crossover 电压平台列表 (V)', 'section': 'IV', 'validation': 'non_empty_list'},
+)
+    h2_anode_flow: float = field(
+    default=0.5, metadata={'comment': 'H₂ crossover 阳极气体流速 (SLM)', 'section': 'IV'},
+)
+    h2_cathode_flow: float = field(
+    default=0.05, metadata={'comment': 'H₂ crossover 阴极气体流速 (SLM)', 'section': 'IV'},
+)
+    h2_to_entry: bool = field(
+    default=False, metadata={'comment': '是否将最后一段 H₂ crossover 结果填入输入框', 'section': 'IV'},
+)
+    h2_e_tol: float = field(
+    default=0.01, metadata={
+        'comment': 'H₂ crossover 电压平台匹配容差 (V)', 'section': 'IV', 'validation': 'positive_number',
+    },
+)
+    ma_volt_list: tuple = field(
+    default=(0.775, 0.8, 0.825, 0.85, 0.875, 0.9),
+    metadata={'comment': 'MA 电压点列表 (V)', 'section': 'IV', 'validation': 'non_empty_list'},
+)
+    ma_match_min_num: int = field(
+    default=3, metadata={
+        'comment': 'MA 匹配所需的最小连续电压点个数', 'section': 'IV', 'validation': 'positive_number',
+    },
+)
+    ma_erange_tol: float = field(
+    default=0.0003, metadata={
+        'comment': 'MA 电位窗口的 E_range 容差 (V)', 'section': 'IV', 'validation': 'positive_number',
+    },
+)
+    del_condition_rh: int = field(
+    default=140, metadata={
+        'comment': '活化截断的 RH 阈值 (%)', 'section': 'IV', 'validation': 'positive_number',
+    },
+)
+    is_del_conditioning: bool = field(
+    default=True, metadata={'comment': '是否自动删除活化数据段', 'section': 'IV'},
+)
+    process_imp: bool = field(
+    default=True, metadata={'comment': '是否处理并删除阻抗谱数据行', 'section': 'IV'},
+)
+    impdata_to_txt: bool = field(
+    default=False, metadata={'comment': '是否额外将阻抗谱导出为 TXT 文件', 'section': 'IV'},
+)
+    output_zmag: bool = field(
+    default=False, metadata={'comment': '阻抗谱导出是否包含 Z_Mag 列', 'section': 'IV'},
+)
+    detail_to_excel: bool = field(
+    default=False, metadata={'comment': '是否将 detail_df 输出到 Excel', 'section': 'IV'},
+)
+
+    # ---- ECSA ----
+    ecsa_scan_rate: float = field(
+    default=0.1, metadata={
+        'comment': 'ECSA 默认电压扫速 (V/s)', 'section': 'ECSA', 'validation': 'positive_number',
+    },
+)
+    ecsa_co_cross_threshold: float = field(
+    default=0.0025, metadata={
+        'comment': 'CO 选点零跨容差 (A): 平滑 diff < 此值即认为已回基线', 'section': 'ECSA', 'validation': 'positive_number',
+    },
+)
+
+# ---- O2 ----
+    o2_start_v: float = field(
+    default=0.15, metadata={'comment': '极限电流搜索的起始电位 (V)', 'section': 'O2'},
+)
+    o2_end_v: float = field(
+    default=0.3, metadata={'comment': '极限电流搜索的结束电位 (V)', 'section': 'O2'},
+)
+    o2_flow_rate: float = field(
+    default=5.0, metadata={
+        'comment': '阴极气体流速 (SLM)', 'section': 'O2', 'validation': 'positive_number',
+    },
+)
+    o2_x_list: tuple = field(
+    default=(0.01, 0.015, 0.02, 0.025),
+    metadata={'comment': '氧气浓度列表 (摩尔分数, 非百分比)', 'section': 'O2', 'validation': 'non_empty_list'},
+)
+    o2_pressure_list: tuple = field(
+    default=(1.0, 1.5, 2.0, 3.0),
+    metadata={'comment': '压力列表 (bar)', 'section': 'O2', 'validation': 'non_empty_list'},
+)
+    o2_split_sign: str = field(
+    default='CURVE\tTABLE\t', metadata={'comment': 'Gamry 数据文件中的曲线定位标记', 'section': 'O2'},
+)
+    o2_filename_pattern: str = field(
+    default=r'(\d+(?:\.\d+)?)\s*', metadata={'comment': '从文件名提取压力/浓度的正则匹配模式', 'section': 'O2'},
+)
+    o2_cell_temp: int = field(
+    default=80, metadata={
+        'comment': 'O2 测试电池温度 (°C)', 'section': 'O2', 'validation': 'positive_number',
+    },
+)
+    o2_l_flow_channel: float = field(
+    default=6.5, metadata={
+        'comment': '流道长度 (cm)', 'section': 'O2', 'validation': 'positive_number',
+    },
+)
+    o2_n_flow_channel: int = field(
+    default=7, metadata={
+        'comment': '流道数量', 'section': 'O2', 'validation': 'positive_number',
+    },
+)
+
+
+def build_config(json_path: Path | None = None) -> Config:
+    '''
+    用途: 读取 JSON 配置文件, 与默认值合并, 构建不可变 Config 实例。
+
+    参数:
+        json_path: 配置文件路径, None 时按 `resolve_config_path()` 解析
+                   (显式指定 > FCDP_CONFIG 环境变量 > 本目录副本的本目录配置 / pip 安装的用户数据目录)。
+
+    调用: 由 GUI/CLI 启动流程与程序化调用方调用。
+
+    返回: 返回 frozen Config 实例。
+
+    注意: 显式传入的路径不存在时**不抛异常**: 回退为全部默认值并打印 stderr 警告。这是既定的程序化契约;
+          需要确定性失败的入口 (如 CLI `--config`) 自行前置校验。
+          本函数只读不写: 解析出的路径文件不存在时不会自动创建, 首建发生在保存配置时 (本目录副本形态生成在本目录, pip 安装形态生成在用户数据目录)。
+    '''
+    defaults = {}
+    for f in fields(Config):
+        if f.default is not MISSING:
+            defaults[f.name] = f.default
+        elif f.default_factory is not MISSING:
+            defaults[f.name] = f.default_factory()
+
+    # 读取 JSON 配置覆盖 (仅覆盖非下划线字段)
+    if json_path is None:
+        config_path = Path(defaults['_json_path'])   # default_factory 保证存在且为 Path
+    else:
+        config_path = Path(json_path)
+        if not config_path.is_file():
+            # 契约仍是"不存在即默认值", 但不能静默: 否则"路径写错"与"配置没生效"无法区分
+            print(f'[WARNING] 指定的配置文件不存在 ({config_path}), 使用全部默认值', file=sys.stderr)
+    if config_path.is_file():
+        try:
+            with open(config_path, 'r', encoding='utf-8') as fp:
+                overrides = json.load(fp)
+            field_map = {f.name: f for f in fields(Config) if not f.name.startswith('_')}
+            for key, value in overrides.items():
+                if key not in field_map:
+                    continue
+                # JSON 中的 list 转 tuple, 保持 frozen 兼容
+                if isinstance(value, list):
+                    defaults[key] = tuple(value)
+                    continue
+                # 数值字段类型强制: config.json 中误写为字符串时尝试转 int/float
+                target_type = field_map[key].type
+                if isinstance(value, str) and target_type in (int, float):
+                    try:
+                        defaults[key] = int(value) if target_type is int else float(value)
+                        continue
+                    except (ValueError, TypeError):
+                        pass  # 转换失败保留原值, 由 validate_config 告警
+                defaults[key] = value
+        except Exception as e:
+            print(f'[WARNING] 配置文件读取失败 ({e}), 使用全部默认值', file=sys.stderr)
+
+    return Config(**defaults)
+
+
+# =========================
+# 配置字段提取
+# =========================
+
+def _extract_config_fields(config_cls):
+    '''
+    用途: 从 Config dataclass 提取字段名称, 类型, 默认值, 中文注释和元数据。
+
+    调用: 由 `ConfigEditorDialog` 构造 UI 行时调用。
+    返回: 返回 `[(name, type_tag, default_value, comment, metadata), ...]` 列表。
+          type_tag 为 'bool' | 'int' | 'float' | 'list' | 'str'。
+          metadata 为字段 metadata 字典。
+    '''
+    result = []
+    for f in fields(config_cls):
+        if f.name.startswith('_'):
+            continue
+        # 确定默认值
+        if f.default is not MISSING:
+            default = f.default
+        elif f.default_factory is not MISSING:
+            default = f.default_factory()
+        else:
+            default = None
+        # 确定类型标签
+        if isinstance(default, bool):
+            tag = 'bool'
+        elif isinstance(default, tuple):
+            tag = 'list'  # UI 仍显示为可编辑列表
+        elif isinstance(default, dict):
+            tag = 'str'  # dict 以纯文本形式展示和编辑
+        elif isinstance(default, int):
+            tag = 'int'
+        elif isinstance(default, float):
+            tag = 'float'
+        else:
+            tag = 'str'
+        comment = f.metadata.get('comment', '')
+        result.append((f.name, tag, default, comment, f.metadata))
+    return result
+
+
+def validate_config(config: Config) -> list[str]:
+    '''
+    用途: 校验关键配置项 (路径存在性, 正数, 非空列表,O2 电压范围,ECSA 模式等)。
+
+    调用: 由 `Application.start` 和 `ConfigEditorDialog.save` 调用。
+    返回: 返回警告字符串列表, 空列表表示无警告。
+    '''
+    warnings = []
+
+    def add_warning(name, current_value, suggestion, impact):
+        warnings.append(f'{name}: 当前值={current_value}; 建议={suggestion}; 影响={impact}')
+
+    def is_positive_number(name):
+        value = getattr(config, name)
+        if not isinstance(value, (int, float)) or value <= 0:
+            add_warning(name, value, '使用正数', '相关计算公式或参数读取可能失败')
+
+    def is_non_empty_list(name):
+        value = getattr(config, name)
+        if not isinstance(value, (list, tuple)) or len(value) == 0:
+            add_warning(name, value, '使用非空列表/元组', '序列匹配, 插值或 O2 分组可能失败')
+
+    for path_name in ('data_path_default', 'result_path'):
+        path_value = getattr(config, path_name)
+        if not path_value:
+            add_warning(path_name, '未设置', '设置目录路径', '默认打开目录或结果保存目录可能不可用')
+            continue
+        p = Path(path_value)
+        if not p.exists():
+            add_warning(path_name, path_value, '填写存在的目录路径', '默认打开目录或结果保存目录可能不可用')
+        elif not p.is_dir():
+            add_warning(path_name, path_value, '填写目录路径而非文件路径', '该路径应为父文件夹路径')
+        if path_name == 'result_path' and p.exists() and p.is_dir():
+            # 检查结果路径是否可写
+            try:
+                write_test = p / '.fcdp_write_test'
+                write_test.touch(exist_ok=True)
+                write_test.unlink(missing_ok=True)
+            except (OSError, PermissionError):
+                add_warning(path_name, path_value, '填写有写权限的目录路径', 'Excel 导出可能失败')
+
+    # 按字段 metadata 中的 validation 标记校验
+    for f in fields(config.__class__):
+        name = f.name
+        if name.startswith('_'):
+            continue
+        vtype = f.metadata.get('validation')
+        if vtype == 'positive_number':
+            is_positive_number(name)
+        elif vtype == 'non_empty_list':
+            is_non_empty_list(name)
+
+    # 数值字段类型告警: build_config 强制转换失败(如字符串不可转数字)时在此暴露
+    for f in fields(config.__class__):
+        name = f.name
+        if name.startswith('_'):
+            continue
+        if f.type in (int, float):
+            value = getattr(config, name)
+            if not isinstance(value, (int, float)):
+                add_warning(name, value, f'使用数字 ({f.type.__name__})', '相关计算公式或参数读取可能失败')
+
+    o2_start_v = getattr(config, 'o2_start_v')
+    o2_end_v = getattr(config, 'o2_end_v')
+    if not isinstance(o2_start_v, (int, float)) or not isinstance(o2_end_v, (int, float)):
+        add_warning('o2_start_v/o2_end_v', f'{o2_start_v}, {o2_end_v}', '使用数字电压范围', 'O2 极限电流搜索可能失败')
+    elif o2_start_v >= o2_end_v:
+        add_warning('o2_start_v/o2_end_v', f'{o2_start_v}, {o2_end_v}', '保证 o2_start_v < o2_end_v', 'O2 极限电流搜索范围会被反转或无效')
+
+    if getattr(config, 'processing_mode', 'auto').lower() not in ('auto', 'iv', 'hupd', 'co', 'o2'):
+        add_warning('processing_mode', config.processing_mode, "使用 'auto','iv','hupd','co' 或 'o2'", '处理模式选择可能失败')
+
+    o2_pressure_list = getattr(config, 'o2_pressure_list')
+    o2_x_list = getattr(config, 'o2_x_list')
+    if isinstance(o2_pressure_list, (list, tuple)) and isinstance(o2_x_list, (list, tuple)) and len(o2_pressure_list) * len(o2_x_list) == 0:
+        add_warning('o2_pressure_list/o2_x_list', f'{o2_pressure_list}, {o2_x_list}', '两个列表都保持非空', 'O2 文件名解析失败时无法按配置兜底分组')
+
+    return warnings
+
+
+def _get_modified_config_fields(config: Config) -> list[tuple[str, object, object]]:
+    """
+    用途: 对比当前 config 与默认值, 返回被修改的字段名及其 (默认值, 当前值) 列表。
+
+    调用: 由各管道引擎在运行前调用, 用于日志输出。
+    返回: [(field_name, default_value, current_value), ...]
+    """
+    default = Config()
+    changed = []
+    for f in fields(Config):
+        if f.name.startswith('_'):
+            continue
+        default_val = getattr(default, f.name, None)
+        current_val = getattr(config, f.name, None)
+        if type(default_val) != type(current_val):
+            changed.append((f.name, default_val, current_val))
+        elif isinstance(default_val, (tuple, list)):
+            if list(default_val) != list(current_val):
+                changed.append((f.name, default_val, current_val))
+        elif default_val != current_val:
+            changed.append((f.name, default_val, current_val))
+    return changed
+
+
+# =========================
+# 结构化导出报告 (Export Report)
+# =========================
+
+# 逐项状态四态 (勿再扩)
+# 各 Output 的 outcome 字段值与 @property total 均取自此四态, 第三方消费时无需再翻源码:
+#   ok   = 该步骤成功且结果可靠
+#   skip = 该步骤未执行 (如未启用绘图/导出, 或无对应数据)
+#   warn = 该步骤完成但结果可能偏离 (如识别值异常, 拟合 R² 偏低)
+#   fail = 该步骤失败, 对应结果不可用
+# 整体 total 取各字段最高严重度 (见 _TOTAL_ORDER)。
+ITEM_OK = 'ok'
+ITEM_SKIP = 'skip'
+ITEM_WARN = 'warn'
+ITEM_FAIL = 'fail'
+
+# 阶段词表 (5 条管线统一, 保证跨管线可比)
+PHASE_PARSE = '解析'
+PHASE_PREPROCESS = '预处理'
+PHASE_CALC = '计算'
+PHASE_PLOT = '绘图'
+PHASE_EXCEL = 'Excel导出'
+
+_TOTAL_ORDER = {ITEM_FAIL: 3, ITEM_WARN: 2, ITEM_OK: 1, ITEM_SKIP: 0}
+
+
+def _max_status(records: 'list[str]') -> str:
+    '''
+    用途: 从一组状态中取最高严重度 (fail>warn>ok>skip)。
+
+    调用: 由各 Output 的 @property total 现算整体状态时调用。
+    返回: 返回 ITEM_* 之一。
+    '''
+    worst = ITEM_OK
+    worst_sev = -1
+    for status in records:
+        # 未注册状态按最高严重度 (fail) 处理, 避免未知/拼错的状态被静默降级为 ok
+        if status not in _TOTAL_ORDER:
+            return ITEM_FAIL
+        sev = _TOTAL_ORDER[status]
+        if sev > worst_sev:
+            worst, worst_sev = status, sev
+    return worst
+
+
+@dataclass
+class IvOutcome:
+    '''IV/H2/MA 管线结果状态。'''
+    conditioning: str = ITEM_SKIP      # 活化移除 (预处理, ok=已剔除 / skip=未剔除)
+    figure: str = ITEM_SKIP           # IV 图 (绘图)
+    excel: str = ITEM_SKIP            # IV工作簿 (Excel导出)
+    cell_area: str = ITEM_SKIP        # 电池面积 (识别到的值与 config 不一致→warn)
+    back_pressure: str = ITEM_SKIP    # 背压 (文件解析到且与默认 150 不一致→warn)
+    # 段级 quality: 每类 unit 各自统计 (多段→一档), 无段时默认 skip;
+    #             段匹配/H2/MA 处理遇意外异常(崩溃)时, 由对应 except 分支置 ITEM_FAIL
+    iv_segments: str = ITEM_SKIP      # iv_units 各段 status 最高档; 段匹配崩溃→fail
+    imp_segments: str = ITEM_SKIP     # imp_units 各段 status 最高档
+    ma_segments: str = ITEM_SKIP      # ma_units 各段 status 最高档; 崩溃→fail
+    h2_segments: str = ITEM_SKIP      # h2_units 各段 status 最高档; 崩溃→fail
+
+
+@dataclass
+class CoEcsaOutcome:
+    '''CO-ECSA 管线结果状态。'''
+    segment_parse: str = ITEM_SKIP    # 片段解析 (计算)
+    data_prep: str = ITEM_SKIP        # CO 数据准备 (计算)
+    point_select: str = ITEM_SKIP     # 端点选择 (计算)
+    co_ecsa: str = ITEM_SKIP          # CO ECSA (计算)
+    excel: str = ITEM_SKIP            # CO ECSA工作簿 (Excel导出)
+
+
+@dataclass
+class HupdEcsaOutcome:
+    '''HUPD-ECSA 管线结果状态。'''
+    segment_parse: str = ITEM_SKIP    # 片段解析 (计算)
+    point_select: str = ITEM_SKIP     # 端点选择 (计算)
+    hupd_calc: str = ITEM_SKIP        # HUPD 计算 (计算)
+    excel: str = ITEM_SKIP            # HUPD ECSA工作簿 (Excel导出)
+
+
+@dataclass
+class OxygenOutcome:
+    '''O2 管线结果状态。'''
+    file_grouping: str = ITEM_SKIP    # 文件分组 (解析)
+    limit_curve: str = ITEM_SKIP      # 极限电流曲线 (计算)
+    resistance: str = ITEM_SKIP       # O2 阻力 (计算)
+    figure: str = ITEM_SKIP           # O2 图 (绘图)
+    excel: str = ITEM_SKIP            # O2工作簿 (Excel导出)
+
+
+@dataclass
+class EisOutcome:
+    '''EIS 管线结果状态。'''
+    segment_fit: str = ITEM_SKIP      # EIS 段搜索/拟合 (计算)
+    r2: str = ITEM_SKIP               # EIS 拟合 R² (计算)
+    excel: str = ITEM_SKIP            # EIS工作簿 (Excel导出)
+
+
+def outcome_rows(outcome: object) -> 'list[tuple[str, str, str]]':
+    '''
+    用途: 把管线 outcome 固定类各字段就地投影为 (阶段, 项目, 状态) 行。
+          CLI 终端打印与 Excel `导出状态` 表共用此单一来源, 避免逐类映射在两端漂移。
+
+    调用: 由 cli.py `_print_export_report` 与 excel_export.py `write_export_report_sheet` 调用。
+    返回: 返回 (phase, item, status) 三元组列表; 无法识别的 outcome 返回空列表。
+    '''
+    if isinstance(outcome, IvOutcome):
+        return [
+            (PHASE_PREPROCESS, '活化移除', outcome.conditioning),
+            (PHASE_CALC, 'IV 段', outcome.iv_segments),
+            (PHASE_CALC, '阻抗谱段', outcome.imp_segments),
+            (PHASE_CALC, 'MA 段', outcome.ma_segments),
+            (PHASE_CALC, 'H2 段', outcome.h2_segments),
+            (PHASE_CALC, '电池面积', outcome.cell_area),
+            (PHASE_CALC, '背压', outcome.back_pressure),
+            (PHASE_PLOT, 'IV 图', outcome.figure),
+            (PHASE_EXCEL, 'IV工作簿', outcome.excel),
+        ]
+    if isinstance(outcome, CoEcsaOutcome):
+        return [
+            (PHASE_CALC, '片段解析', outcome.segment_parse),
+            (PHASE_CALC, 'CO 数据准备', outcome.data_prep),
+            (PHASE_CALC, '端点选择', outcome.point_select),
+            (PHASE_CALC, 'CO ECSA', outcome.co_ecsa),
+            (PHASE_EXCEL, 'CO ECSA工作簿', outcome.excel),
+        ]
+    if isinstance(outcome, HupdEcsaOutcome):
+        return [
+            (PHASE_CALC, '片段解析', outcome.segment_parse),
+            (PHASE_CALC, '端点选择', outcome.point_select),
+            (PHASE_CALC, 'HUPD 计算', outcome.hupd_calc),
+            (PHASE_EXCEL, 'HUPD ECSA工作簿', outcome.excel),
+        ]
+    if isinstance(outcome, OxygenOutcome):
+        return [
+            (PHASE_PARSE, '文件分组', outcome.file_grouping),
+            (PHASE_CALC, '极限电流曲线', outcome.limit_curve),
+            (PHASE_CALC, 'O2 阻力', outcome.resistance),
+            (PHASE_PLOT, 'O2 图', outcome.figure),
+            (PHASE_EXCEL, 'O2工作簿', outcome.excel),
+        ]
+    if isinstance(outcome, EisOutcome):
+        return [
+            (PHASE_CALC, 'EIS 段搜索/拟合', outcome.segment_fit),
+            (PHASE_CALC, 'EIS 拟合 R²', outcome.r2),
+            (PHASE_EXCEL, 'EIS工作簿', outcome.excel),
+        ]
+    return []
+
+
+# =========================
+# 运行期服务
+# =========================
+
+class RuntimeServices:
+    '''
+    用途: 为辅助函数提供轻量的界面和日志边界, 自动识别 UI / CLI 模式。
+
+    调用: 由 `Application` 创建, 并由各处理流程使用。
+    '''
+    config: Any
+
+    def __init__(self, config: Config):
+        self.config = config
+        self._messages = []
+        # 测试用: 置 True 时 show() 不打印 stderr (conftest mock_services / 各测试静默输出用)。
+        # 产品代码 (CLI/GUI) 从不切换此开关, 默认 False → 管线日志经 show() 打到 stderr (CLI 日志出口)。
+        self._quiet: bool = False
+
+    def _record_message(self, label, text, level='INFO') -> 'LogMessage':
+        '''记录消息到 _messages 列表, 返回 LogMessage 对象。'''
+        ts = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
+        msg = LogMessage(level=level, text=str(text), timestamp=ts, label=label)
+        self._messages.append(msg)
+        return msg
+
+    def show(self, label, text, level='INFO', capture_exc_info=True):
+        '''
+        用途: 记录并显示消息。在 except 块中以 ERROR/WARNING 级别调用时,
+             自动捕获异常调用栈存入 text, 人工信息并入 label (调用方无需手动拼接 {ex} 或 format_exc)。
+
+        Level 说明:
+          - LOG: 仅写入 _messages + stderr(内部流程记录, 不展示到 LogPanel)
+          - INFO: 写入 _messages + stderr,GUI 模式下展示到 LogPanel
+          - WARNING/ERROR/SUCCESS: 同上, 额外在 LogPanel 高亮
+          - ASK: 展示并等待用户确认,CLI 模式自动同意
+
+        参数:
+            label: 修饰/数据项名(发生在哪, 这是什么), 缺省空串, 语义上位于 text 前。
+            text: 消息文本(结果/值)。
+            level: 日志级别。
+            capture_exc_info: True 时在 except 块中自动追加异常调用栈;
+                              False 时禁用此行为, 避免误捕获 stale 异常。
+
+        注意: 存在调用栈时, 人工信息(label + text)并入 label, text 只承载全部调用栈,
+              使 out.warnings 等程序化消费处 text 保持一致结构 (栈或结果文本, 不混排)。
+              有栈仅在 except 块内且 capture_exc_info=True 时出现;
+              INFO/SUCCESS/LOG/ASK 以及 except 块外调用不受影响。
+        '''
+        tb = None
+        if capture_exc_info and level in ('ERROR', 'WARNING'):
+            exc_info = sys.exc_info()
+            if exc_info[0] is not None:
+                tb = traceback.format_exc().rstrip('\n')
+                # 有栈时: 人工信息并入 label, text 只承载全部调用栈 (供程序化消费取一致结构)
+                label = text if not label else f'{label}: {text}'
+                text = tb
+
+        msg = self._record_message(label, text, level)
+        if not self._quiet:  # 测试静默开关; 有栈时分两行展示人工信息与调用栈
+            if tb is not None:
+                print(f'[{msg.timestamp}] {level}\t : {label}\n{text}', file=sys.stderr)
+            else:
+                # 无栈时 label 与 text 以 ': ' 分隔展示 (label 缺省空串时只输出 text, 避免多余冒号)
+                display = f'{label}: {text}' if label else text
+                print(f'[{msg.timestamp}] {level}\t : {display}', file=sys.stderr)
+        if level == 'ASK':
+            self._record_message('', 'Auto Accept', 'ASK FEEDBACK')
+            return True
+        return None
+
+    def get_messages(self) -> list:
+        '''
+        用途: 获取所有累积的消息列表 (转为 LogMessage 对象)。
+        '''
+        return list(self._messages)
+
+    def clear_messages(self):
+        '''
+        用途: 清空累积的消息列表。
+        '''
+        self._messages.clear()
+
+    
+
+# =========================
+# 数据容器
+# =========================
+
+@dataclass
+class IvMeanResult:
+    '''
+    用途: 保存指定尾部点数对应的 IV 均值表。
+
+    调用: 由 `build_iv_mean_result` 返回, 并缓存在 `IvContext` 使用。
+    '''
+    mean_num: int
+    final_df: "pd.DataFrame | None" = None
+    detail_df: "pd.DataFrame | None" = None
+
+
+@dataclass
+class IvContext:
+    '''
+    用途: IV 管道计算期私有中间态载体 (结果不落此; 结果归 run_iv_pipeline 局部 + IvPipelineOutput)。
+    说明: 仅存共享工作表 data_df + 轻中间索引用 + 渲染中间态。段级 units / final_df / detail_df /
+          iv_mean / ma_mean 为 run_iv_pipeline 局部变量, 段计算函数直接 append / 就地修改, 不进本对象。
+
+    调用: 由 `run_iv_pipeline` 创建, 作为 scratch 传给段计算函数与导出/渲染。
+    '''
+    data_df: "pd.DataFrame | None" = None                    # 共享工作表 (随流程删行, 属中间态)
+    segment_index_list: list = field(default_factory=list)   # 均值分段 (懒建)
+    mean_cache: dict = field(default_factory=dict)           # mean_num -> IvMeanResult (GUI 换点数时懒重建)
+    MA_index_list: "list | None" = None                      # MA 段起始索引 (含保留的 warn 段, 驱动 Excel 布局)
+    IsH2Manual: bool = False                                 # H2 手动模式标志
+
+    # 渲染中间态
+    _ma_full_indices: "list | None" = None
+    _iv_export_figure_list: "list | None" = None
+
+
+@dataclass
+class IvRunParams:
+    '''
+    用途: 保存已校验的 IV 运行参数。
+
+    调用: 由 `create_iv_run_params` 创建。
+    '''
+    cell_area: float
+    is_del_conditioning: bool
+    del_condition_rh: float
+    process_imp: bool
+    output_zmag: bool
+    iv_mean_num: int
+    iv_e_list: list
+    iv_e_match_min_num: int
+    iv_lookup_e_value_list: list
+    iv_lookup_j_value_list: list
+    h2_mean_num: int
+    h2_volt_list: list
+    h2_e_tol: float
+    h2_anode_flow: float
+    h2_cathode_flow: float
+    h2_to_entry: bool
+    ma_mean_num: int
+    ma_volt_list: list
+    ma_match_min_num: int
+    ma_erange_tol: float
+    draw_results: bool
+
+
+def create_iv_run_params(config: Config, cell_area: float) -> IvRunParams:
+    '''
+    用途: 根据 Config 和电池面积构建一次 IV 运行参数快照。
+
+    调用: 由 `run_iv_pipeline` 创建; `gui.py` 和 `cli.py` 也可在需要时调用。
+    返回: 返回 `IvRunParams`。
+    '''
+    return IvRunParams(
+        cell_area=cell_area,
+        is_del_conditioning=config.is_del_conditioning,
+        del_condition_rh=config.del_condition_rh,
+        process_imp=config.process_imp,
+        output_zmag=config.output_zmag,
+        iv_mean_num=config.iv_mean_num,
+        iv_e_list=list(config.iv_e_list),
+        iv_e_match_min_num=config.iv_e_match_min_num,
+        iv_lookup_e_value_list=list(config.iv_lookup_e_value_list),
+        iv_lookup_j_value_list=list(config.iv_lookup_j_value_list),
+        h2_mean_num=config.h2_mean_num,
+        h2_volt_list=list(config.h2_volt_list),
+        h2_e_tol=config.h2_e_tol,
+        h2_anode_flow=config.h2_anode_flow,
+        h2_cathode_flow=config.h2_cathode_flow,
+        h2_to_entry=config.h2_to_entry,
+        ma_mean_num=config.ma_mean_num,
+        ma_volt_list=list(config.ma_volt_list),
+        ma_match_min_num=config.ma_match_min_num,
+        ma_erange_tol=config.ma_erange_tol,
+        draw_results=config.draw_results,
+    )
+
+
+@dataclass
+class H2CrossoverData:
+    """
+    用途: 保存 H2 crossover 纯数据识别结果 (过滤后的数据, 有效循环)。
+
+    调用: 由调用方直接构造, 并由 `build_h2_crossover_data` 返回。
+    """
+    gas_df: Any = None
+    valid_cycles: list = field(default_factory=list)
+
+
+class InteractivePeakSelector:
+    '''
+    用途: 跟踪 ECSA 交互图中的选点索引。
+
+    调用: 由 `Application` 的 CO/HUPD 点击处理器使用。
+    '''
+    def __init__(self, index_finder, redraw_axis):
+        self.index_finder = index_finder
+        self.redraw_axis_callback = redraw_axis
+        self.point_indices = {}
+
+    def select_point(self, x, y, ax_id, key=None):
+        '''
+        用途: 根据鼠标坐标查找最近数据点索引, 记录到选点字典并重绘坐标轴。
+
+        调用: 由 ECSA 点击回调 (如 `CoPanelController._on_click`,`HupdPanelController._on_click`) 通过 selector 调用。
+        返回: 返回数据点索引。
+        '''
+        key = ax_id if key is None else key
+        index = int(self.index_finder(x, y, ax_id))
+        self.point_indices[key] = index
+        self.redraw_axis(ax_id)
+        return index
+
+    def redraw_axis(self, ax_id):
+        '''
+        用途: 通知重绘回调, 用当前选点状态刷新指定坐标轴。
+
+        调用: 由 `select_point` 调用。
+        '''
+        self.redraw_axis_callback(ax_id, self.point_indices)
+
+    def get_point(self, key):
+        '''
+        用途: 获取已选点的索引。
+
+        调用: 由 CO/HUPD 交互流程读取。
+        返回: 返回数据点索引或 None。
+        '''
+        return self.point_indices.get(key)
+
+    def set_point(self, key, index):
+        '''
+        用途: 设置指定键的选点索引 (用于自动选点结果回填)。
+
+        调用: 由 CO/HUPD 自动选点后回填到 selector 调用。
+        '''
+        self.point_indices[key] = index
+
+    def has_all_points(self, *keys):
+        '''
+        用途: 判断所有指定键的选点是否都已设置。
+
+        调用: 由 CO 交互流程判断两个端点是否都已选择。
+        返回: 全部已设置时返回 True。
+        '''
+        return all(self.get_point(key) is not None for key in keys)
+
+
+@dataclass
+class CoEcsaResult:
+    '''
+    用途: 保存 CO ECSA 数值结果, 端点选点, 面积和绘图曲线 (读取面唯一)。
+
+    对象类型本身隐含 mode (CO), 无需 mode 字段。类型化标量即为权威读取面;
+    CO 的绘图原始曲线以具名数组字段承载。交互选点用的左右端点索引同样在此。
+
+    调用: 由 `calculate_co_ecsa_result` 返回。
+    '''
+    baseline_ecsa: 'float | None' = None     # 扣基线背景 ECSA (m²/g_Pt)
+    linear_ecsa: 'float | None' = None       # 扣直线背景 ECSA (m²/g_Pt)
+    left_E: 'float | None' = None            # 左端点电压 V
+    right_E: 'float | None' = None           # 右端点电压 V
+    baseline_area: 'float | None' = None     # 基线峰面积 A·V
+    linear_area: 'float | None' = None       # 直线峰面积 A·V
+    # 交互选点端点索引 (GUI 回填 selector 用)
+    left_index: 'int | None' = None          # 左端点索引
+    right_index: 'int | None' = None         # 右端点索引
+    # 绘图原始数据 (第三方读取原始曲线用)
+    ecsa_x: 'np.ndarray | None' = None       # 电位 (n,)
+    ecsa_y: 'np.ndarray | None' = None       # 电流 (n,)
+    baseline: 'np.ndarray | None' = None     # 基线 y (n,)
+
+
+@dataclass
+class HupdEcsaResult:
+    '''
+    用途: 保存 HUPD ECSA 数值结果, 基线点选点, 面积和绘图曲线 (每 cycle 一对象)。
+
+    对象类型本身隐含 mode (HUPD), 无需 mode 字段。类型化标量即为权威读取面;
+    积分区曲线以具名数组字段承载。
+
+    调用: 由 `calculate_hupd_ecsa_result` 返回。
+    '''
+    ecsa: 'float | None' = None              # ECSA (m²/g_Pt)
+    area: 'float | None' = None              # 峰面积 A·V
+    point_E: 'float | None' = None           # 基线点电压 V
+    point_end: 'int | None' = None           # 基线终点索引 (GUI 回填/绘图用)
+    direction: str = HUPD_DIRECTION_TUPLE[0] # 基线方向 ('baseline above'/'baseline below', 回显实际解析方向)
+    # 绘图原始数据 (第三方读取原始曲线用)
+    area_curve: 'np.ndarray | None' = None   # 积分区 [E, I] 二维数组, shape (n,2), 列 0=E(V)/列 1=I(A)
+    baseline: 'np.ndarray | None' = None     # 基线 y 一维数组, shape (n,), 与 area_curve 行数相同
+
+
+@dataclass
+class CoEcsaSession:
+    '''
+    用途: 保存 CO ECSA 交互图的运行状态。
+
+    调用: 由 `Application` 的 CO 计算创建, 并由 CO 点击/重绘流程读取。
+    '''
+    fig: Any
+    ax: Any
+    e: Any
+    i: Any
+    baseline: Any
+    selector: InteractivePeakSelector
+    left_index: int | None = None
+    right_index: int | None = None
+    result: "CoEcsaResult | None" = None
+
+    def has_complete_selection(self):
+        '''
+        用途: 判断 CO ECSA 左右端点是否都已选择。
+
+        调用: 由 CO 交互流程调用。
+        返回: 两端点均已选择时返回 True。
+        '''
+        return self.left_index is not None and self.right_index is not None
+
+
+@dataclass
+class HupdEcsaSession:
+    '''
+    用途: 保存 HUPD ECSA 多子图交互的运行状态。
+
+    调用: 由 `Application` 的 HUPD 计算创建, 并由 HUPD 点击/重绘流程读取。
+    '''
+    fig: Any
+    axes: list
+    segments: list
+    selector: InteractivePeakSelector
+    point_indices: list = field(default_factory=list)
+    ecsa_values: list = field(default_factory=list)
+    results: list = field(default_factory=list)
+
+    def __post_init__(self):
+        '''
+        用途: dataclass 初始化后为每个循环创建点索引,ECSA 值, 结果占位列表。
+
+        调用: dataclass 实例化时自动调用。
+        '''
+        cycle_count = len(self.segments)
+        if not self.point_indices:
+            self.point_indices = [None] * cycle_count
+        if not self.ecsa_values:
+            self.ecsa_values = [None] * cycle_count
+        if not self.results:
+            self.results = [None] * cycle_count
+
+    def update_point(self, ax_id, selected_index):
+        '''
+        用途: 更新指定子图的选点索引。
+
+        调用: 由 HUPD 点击回调调用。
+        返回: 返回选点索引。
+        '''
+        updated = list(self.point_indices)
+        updated[ax_id] = selected_index
+        self.point_indices = updated
+        return selected_index
+
+
+@dataclass
+class LinearFitResult:
+    '''
+    用途: 保存线性回归的纯数据结果。
+
+    调用: 由 `safe_linear_fit` 返回, 并由 `draw_linear_fit` 使用。
+    '''
+    slope: float
+    intercept: float
+    r: float
+    x: 'np.ndarray'      # 拟合自变量原始点, numpy (n,) (物理量/单位随调用场景)
+    y: 'np.ndarray'      # 拟合因变量原始点, numpy (n,)
+    y_fit: 'np.ndarray'  # 线性拟合值, numpy (n,) (= slope*x + intercept)
+
+
+@dataclass
+class OxygenResult:
+    '''
+    用途: 保存 O2 处理表格和图对象引用。
+
+    调用: 由 `Application` 的 O2 工作流持有。
+    '''
+    all_LC_df: "pd.DataFrame | None" = None
+    xi_df: "pd.DataFrame | None" = None
+    result_df: "pd.DataFrame | None" = None
+    fig_curves: Any = None      # matplotlib Figure 句柄 (曲线网格图, 左, p_num×x_num 子图; 非数据)
+    fig_ix: Any = None          # matplotlib Figure 句柄 (I-xO2 拟合图; 非数据)
+    fig_rp: Any = None          # matplotlib Figure 句柄 (Rtotal-Pressure 拟合图; 非数据)
+    records: list = field(default_factory=list)  # list[OxygenCurveRecord], 供管线外绘图使用 (含各曲线限流点)
+
+
+@dataclass
+class OxygenCurveRecord:
+    '''
+    用途: 保存一条 O2 曲线, 限流点和 Excel 行数据。
+
+    调用: 由 computations 的 `build_oxygen_curve_result_from_groups` 构建, 绘图时供 `draw_oxygen_curve` 读取。
+    '''
+    name: str
+    pressure: float
+    x_o2: float
+    vm: float
+    im: float
+    jm: float
+    data_df: "pd.DataFrame"
+
+    def to_excel_row(self):
+        '''
+        用途: 将限流点数据转为 Excel 行列表。
+
+        调用: 由 O2 曲线构建流程和 `build_oxygen_curve_record` 的调用者使用。
+        返回: 返回列表, 可用于写入 Excel 行。
+        '''
+        return [self.name, self.pressure, self.x_o2, self.vm, self.im, self.jm, 0.0]
+
+
+@dataclass
+class OxygenFitRecord:
+    '''
+    用途: 保存一组 O2 阻力拟合的原始点和线性拟合结果。
+
+    调用: 由 `calculate_oxygen_resistance_result` 返回, 并由 `draw_oxygen_resistance_summary` 使用。
+    '''
+    label: str
+    x: 'list[float]'  # 拟合自变量原始点 (current_fits 为各曲线 O2 摩尔分数, pressure_fit 为压力 bar)
+    y: 'list[float]'  # 拟合因变量原始点 (current_fits 为极限电流密度 jm mA/cm², pressure_fit 为 R_total)
+    fit: LinearFitResult
+    x_min: float | None = None
+
+
+@dataclass
+class OxygenResistanceResult:
+    '''
+    用途: 保存 O2 阻力纯计算结果和绘图所需拟合记录。
+
+    调用: 由 `calculate_oxygen_resistance_result` 返回, 并回填到 `OxygenResult`。
+    '''
+    xi_df: "pd.DataFrame"
+    result_df: "pd.DataFrame"
+    current_fits: 'list[OxygenFitRecord]' = field(default_factory=list)  # 各压力组 I-xO2 拟合 (x=O2 摩尔分数, y=极限电流密度 jm)
+    pressure_fit: 'OxygenFitRecord | None' = None             # Rtotal-Pressure 的最终拟合 (x=压力 bar, y=R_total), 斜率经修正得 R_PI
+    j_fit_by_pressure: 'dict[float, np.ndarray]' = field(default_factory=dict)  # {压力(bar): 拟合 y 值 numpy}, 各压力组 I-xO2 拟合值
+
+
+@dataclass
+class FigureBundle:
+    '''
+    用途: 统一保存 figure, 坐标轴列表和可选计算结果。
+
+    调用: 由通用 figure 构建 helper 返回, 供绘图/导出端消费。
+    '''
+    fig: Any
+    axes: list = field(default_factory=list)
+    result: Any = None
+    title: str = ''
+    export_name: str = ''
+    color_cycle: Any = None
+    twin_ax: Any = None
+
+    @property
+    def ax(self):
+        return self.axes[0] if self.axes else None
+
+
+@dataclass
+class ExportFigure:
+    '''
+    用途: 描述一张需要插入 Excel 的 matplotlib 图。
+
+    调用: 由 Excel 图片导出辅助函数创建并传给 `insert_export_figures`。
+    '''
+    fig: Any
+    sheet_name: str | None
+    cell: str
+    dpi: int | None = None
+    close: bool = False
+
+
+
+
+# =========================
+# per-file 结论块与单元类
+# =========================
+
+@dataclass
+class FileConclusion:
+    '''
+    用途: 单文件管线 (IV/CO/HUPD) 的顶层结论, 以 `conclusion: FileConclusion` 实例持有一个。
+          其内字段不另行在 Output 顶层重复。DTA 无需仪器号/不含 time。
+
+    cell_temp/rh 供 ECSA (CO/HUPD, FCD) 文件级使用; IV 的温度/RH 走 unit 级 (此处可空)。
+    loading/cell_area 来源: config.pt_loading 与 config.cell_area。
+    date 来源: DTA 表头 DATE / FCD 表头 `Time:` 行。
+    '''
+    file_name: str
+    date: 'str | None' = None            # DTA 表头 DATE / FCD 表头 Time 行日期
+    loading: 'float | None' = None       # 载量 mg/cm² (来源 config.pt_loading)
+    cell_area: 'float | None' = None     # 面积 cm² (config; DTA 面积不可用)
+    cell_temp: 'float | None' = None     # 电池温度 °C (ECSA 文件级, 取设定温度中位数; IV 走 unit 级可空)
+    rh: 'float | None' = None            # 相对湿度 % (ECSA 文件级; IV 走 unit 级可空)
+    fcd_type: str = 'IV'                 # FCD 文件类型 'IV'/'ECSA' (来源 FCD 头部, 见 FcdInfo.fcd_type)
+    unit_sn: 'str | None' = None         # 仪器序列号 (来源 FCD 头部 UnitSN 解析, 见 FcdInfo.unit_sn)
+    device_name: 'str | None' = None     # 测试设备名称 (文件预读阶段按 unit_sn 匹配 device_map; 匹配失败为 None)
+    raw_file_path: 'str | None' = None   # FCD 头部 Data File 字段读取的原始文件路径 (含目录; 文件内记录值)
+
+
+@dataclass
+class TafelFit:
+    '''MA 单个 Tafel 拟合结果 (对应 plot_titles 一个标题)。'''
+    slope: 'float | None' = None
+    intercept: 'float | None' = None
+    r: 'float | None' = None
+    j_at_09: 'float | None' = None
+
+
+@dataclass
+class TestCondition:
+    '''
+    用途: IV 每 unit 的测试条件集 (随单元; 每行 IV 背压可不同)。
+    来源: cell_temp 取该段设定温度 (TempCell setpoint) 中位数; rh 该段;
+          back_pressure 默认 150 kPa, 否则文件名正则 (数字+bar/kPa, 反引号规避转义)
+          (re.IGNORECASE, 容忍空格/小数), bar×100→kPa。
+
+    注意: 背压为文件名估算, 同文件各 unit 取同一解析值, 实况可能不同, 留待人工校正。
+    '''
+    cell_temp: 'float | None' = None           # 电池温度 °C (设定温度中位数)
+    rh: 'float | None' = None                  # 相对湿度 %
+    back_pressure_kpa: 'float | None' = 150.0  # 背压 kPa; 默认 150; 文件名正则取 (估算)
+
+
+@dataclass
+class EisConclusion:
+    '''
+    用途: EIS 每文件专属结论 (文件级一次; EIS 每文件条件不同)。
+          loading/cell_area 运行级, 放顶层, 不在此重复。
+    '''
+    file_name: str
+    date: 'str | None' = None            # DTA 表头 DATE
+    rh: 'float | None' = None            # 文件名 %RH
+    cell_voltage: 'float | None' = None  # 以文件解析为准则 (DTA `VDC` 表头), 文件名可作后备
+
+
+@dataclass
+class IvUnit:
+    '''每个 RH 极化曲线段 (段算当口直存语义数据)。'''
+    identity: str                       # 段身份 (如 'RH=65%')
+    status: str = ITEM_OK               # 段级: ok / warn (匹配但数据无效)
+    condition: 'TestCondition | None' = None      # 本段测试条件 (temp/RH/背压, 实时)
+    # J@E / E@J 查找 (语义 dict: 目标值 -> 插值结果, 越界目标记 None 仍保留在 dict)
+    j_at_e: 'dict[float, float | None]' = field(default_factory=dict)  # {电压(V): 电流(mA/cm²)}, 越界为 None
+    e_at_j: 'dict[float, float | None]' = field(default_factory=dict)  # {电流密度(mA/cm²): 电压(V)}, 越界为 None
+    matched_idx: 'np.ndarray | None' = None       # 本段匹配索引 (Summary 重建 + 无效段判定用)
+
+
+@dataclass
+class ImpUnit:
+    '''每条阻抗谱段 (单独一类; 段算当口直存语义数据)。'''
+    identity: str                       # 段身份
+    status: str = ITEM_OK               # 段级: ok (未成谱的候选段不建 unit)
+    condition: 'TestCondition | None' = None      # 本段测试条件 (temp/RH/背压, 实时)
+    hfr: 'float | None' = None          # HFR (mOhm), 外推或置 0; 不在 imp_df, 必须单存
+    start_time: 'float | None' = None   # 段首行 Time
+    end_time: 'float | None' = None     # 段末行 Time
+    seg_i: 'float | None' = None        # 段首行 I (A)
+    seg_e: 'float | None' = None        # 段首行 E (V)
+    seg_gas: Any = None                 # 段首行 Multigas_Cathode
+    seg_temp_ca: 'float | None' = None  # 段首行 TempCa
+    imp_df: 'pd.DataFrame | None' = None          # 阻抗谱 (真实数据, DataFrame)
+
+
+@dataclass
+class MaUnit:
+    '''每个 MA 点 (段算当口直存语义数据, 公式/摘要表由导出端组装)。'''
+    identity: str                       # 'MA@xV'
+    status: str = ITEM_OK               # 段级: ok / warn (匹配但数据无效)
+    condition: 'TestCondition | None' = None      # 本 MA 测试条件 (temp/RH/背压, 实时)
+    ma_df: 'pd.DataFrame | None' = None           # MA 曲线基础表 (向量化计算, DataFrame)
+    tafel: 'dict[str, TafelFit]' = field(default_factory=dict)   # {title: TafelFit}, title ∈ plot_titles
+    mass_activity: 'float | None' = None          # 质量活性 = max(J@0.9V)/1000/loading (A/mg Pt)
+    ma_j_at_09: 'float | None' = None             # 取用的 J@0.9V 原始值 (mA/cm², 各数据列最大值)
+    ma_j_at_09_source: 'str | None' = None        # 该最大值的来源列名 ('original'/'H2 crossover free')
+
+
+@dataclass
+class H2Unit:
+    '''H2 crossover 单元 (段算当口直存语义数据, 每周期自持)。'''
+    identity: str = 'H2'                # H2 crossover
+    status: str = ITEM_OK               # 段级: ok / skip (手动 override)
+    condition: 'TestCondition | None' = None      # 本 H2 段测试条件 (temp/RH/背压, 实时)
+    i_h2: 'float | None' = None         # H2_lin_df['i_x,H2'] (截距)
+    r_short: 'float | None' = None      # H2_lin_df['1/R_short'] (斜率)
+    r: 'float | None' = None            # H2_lin_df['r'] (相关系数)
+    mean_current: 'dict[float, float] | None' = None  # {E(V): 本周期均值电流(mA/cm²)}, 每周期自持
+    mean_points: 'list[tuple[float, float, float]] | None' = None   # 本周期各电压平台尾段均值点 [(T, E, I), ...], 供 per-cycle I-t 打点
+    trace: 'pd.DataFrame | None' = None # 本周期完整原始时序 (Time/I...), 自持, 供 per-cycle I-t 图
+    cycle_idx: 'int | None' = None      # 周期序 (导出重组矩阵/排序用)
+
+
+# =========================
+# 引擎管道输入 / 输出数据容器
+# =========================
+
+@dataclass
+class LogMessage:
+    """
+    用途: 记录单条引擎管道日志消息 (级别, 文本, 时间戳, 修饰词/数据项名)。
+
+    调用: 由 `RuntimeServices.show` 创建, 并被管道输出对象,Excel 日志写入使用。
+    """
+    level: str
+    text: str
+    timestamp: str = field(default_factory=lambda: datetime.now().isoformat())
+    label: str = ''
+
+
+@dataclass
+class IvPipelineInput:
+    """
+    用途: 描述 IV/H2/MA 管道的完整输入参数 (文件路径, 电池面积, 导出选项, H2 手动覆盖)。
+
+    调用: 由 `cli.py run()` 和 `IvPanelController.on_calc` 构造, 传给 `run_iv_pipeline`。
+    """
+    fcd_file_path: Path
+    cell_area: float = 5.0
+    output_path: Path | None = None
+    h2_manual: bool = False
+    h2_slope: float | None = None
+    h2_intercept: float | None = None
+    draw_results: bool = True
+    export_excel: bool = True
+    # 预读数据字段: 入口层一次性读入后传入, 管线不再自己读文件
+    data_df: 'pd.DataFrame | None' = None
+    fcd_info: 'FcdInfo | None' = None
+
+    def validate(self) -> None:
+        """检查入口层是否已传入预读数据。"""
+        if self.data_df is None:
+            raise ValueError(
+                "IvPipelineInput.data_df 为 None -- "
+                "入口层必须调用 read_fcd_file() 传入预解析数据"
+            )
+
+
+@dataclass
+class IvPipelineOutput:
+    """
+    用途: 保存 IV/H2/MA 管道的完整输出 (结论块, 共享表, 单元结果列表)。
+
+    调用: 由 `run_iv_pipeline` 构造返回。四 unit 列表由段计算函数**当口直存**, 此处直接引用, 无投影步。
+    """
+    # ① 结论 (文件级一次)
+    conclusion: 'FileConclusion | None' = None
+    # ② 公开共享表
+    data_df: 'pd.DataFrame | None' = None       # 原始数据 (文件级, 共享工作表, 供 Excel 原始数据 sheet)
+    final_df: 'pd.DataFrame | None' = None      # 最终均值表 (文件级, IV 均值汇总)
+    detail_df: 'pd.DataFrame | None' = None     # 明细表 (文件级)
+    iv_mean: 'IvMeanResult | None' = None
+    ma_mean: 'IvMeanResult | None' = None
+    # ④ 单元结果列表 (一等类; 直存)
+    iv_units: 'list[IvUnit]' = field(default_factory=list)
+    imp_units: 'list[ImpUnit]' = field(default_factory=list)   # 阻抗谱段
+    ma_units: 'list[MaUnit]' = field(default_factory=list)
+    h2_units: 'list[H2Unit]' = field(default_factory=list)     # H2 crossover 单元
+    # ③ 绘图 (GUI/导出; 是绘图句柄, 非数据, 第三方读取数据请忽略)
+    iv_overview_bundle: 'FigureBundle | None' = None
+    # ⑥ 导出公用
+    output_path: Path | None = None
+    outcome: IvOutcome = field(default_factory=IvOutcome)      # 各步骤成败状态
+    warnings: 'list[LogMessage]' = field(default_factory=list) # WARNING/ERROR 级结构化日志 (level/timestamp/label/text), return 前由引擎注入
+
+    @property
+    def MA_num(self) -> int:
+        '''MA 单元数 (含保留的 warn 段, 驱动 Excel 布局)。'''
+        return len(self.ma_units)
+
+    @property
+    def H2_num(self) -> int:
+        return len(self.h2_units)
+
+    @property
+    def total(self) -> str:
+        '''薄派生: 从 outcome 各字段现算最高级 (fail>warn>skip>ok)。'''
+        o = self.outcome
+        return _max_status([o.conditioning, o.figure, o.excel, o.cell_area, o.back_pressure,
+                            o.iv_segments, o.imp_segments, o.ma_segments, o.h2_segments])
+
+
+@dataclass
+class EcsaPipelineInput:
+    """
+    用途: 描述 ECSA (CO/HUPD) 管道的完整输入参数 (文件, 模式,Pt 用量, 选点)。
+
+    调用: 由 `cli.py run()` 和 `CoPanelController.on_calc` / `HupdPanelController.on_calc` 构造。
+    """
+    fcd_file_path: Path
+    mode: str = "Auto"
+    # 文件真实模式 'CO'/'HUPD' (入口层从检测结果回填, 与 mode 解耦: mode 表示
+    # 当前提交计算的模式, detected_mode 表示文件实际属于的模式)。守卫据此防
+    # processing_mode 强制覆盖时静默按错误模式计算。
+    detected_mode: "str | None" = None
+    pt_usage: float | None = None
+    cell_area: float = 5.0
+    output_path: Path | None = None
+    co_left_index: int | None = None
+    co_right_index: int | None = None
+    hupd_point_end: int | None = None
+    hupd_direction: str | None = None
+    auto_select_points: bool = True
+    export_excel: bool = True
+    # 预读数据字段: 入口层一次性读入后传入, 管线不再自己读文件
+    data_df: 'pd.DataFrame | None' = None
+    raw_data_df: 'pd.DataFrame | None' = None
+    fcd_info: 'FcdInfo | None' = None
+
+    def validate(self) -> None:
+        """检查入口层是否已传入预读数据。"""
+        if self.data_df is None:
+            raise ValueError(
+                "EcsaPipelineInput.data_df 为 None -- "
+                "入口层必须提前调用 read_fcd_file()"
+            )
+        if self.fcd_info is None:
+            raise ValueError(
+                "EcsaPipelineInput.fcd_info 为 None -- "
+                "入口层必须提供 FCD 文件信息"
+            )
+
+
+@dataclass
+class CoEcsaPipelineOutput:
+    """
+    用途: 保存 CO ECSA 管道输出 (结论, result 权威读取面, 插值数据, 导出路径)。
+
+    调用: 由 `run_co_ecsa_pipeline` 返回。
+    """
+    # ① 结论 (文件级一次; 经 FileConclusion 单一持有, 不与他字段重复)
+    conclusion: 'FileConclusion | None' = None
+    result: 'CoEcsaResult | None' = None    # 唯一权威读取面: 类型化标量 + 绘图曲线
+    e_data: np.ndarray | None = None
+    i_data: np.ndarray | None = None
+    baseline_data: np.ndarray | None = None
+    output_path: Path | None = None
+    outcome: CoEcsaOutcome = field(default_factory=CoEcsaOutcome)   # 各步骤成败状态
+    warnings: 'list[LogMessage]' = field(default_factory=list)      # WARNING/ERROR 级结构化日志
+    # GUI 使用: 用于创建交互图和导出
+    segments: 'list[pd.DataFrame] | None' = None            # 原始分段数据 (每段一张 E/I 表)
+    calc_segments: 'list[pd.DataFrame] | None' = None       # 可用计算片段 (剔除无效段后的 E/I 表)
+    scan_rate: float | None = None          # 扫速
+    data_df: 'pd.DataFrame | None' = None   # 完整 E/I 数据 (列 E/V, I/A)
+    file_mode: str | None = None            # 文件实际模式 'CO'/'HUPD'/'Auto'
+
+    @property
+    def total(self) -> str:
+        '''薄派生: 从 outcome 各字段现算最高级 (fail>warn>skip>ok)。'''
+        o = self.outcome
+        return _max_status([o.segment_parse, o.data_prep, o.point_select, o.co_ecsa, o.excel])
+
+
+@dataclass
+class HupdEcsaPipelineOutput:
+    """
+    用途: 保存 HUPD ECSA 管道输出 (结论, 多循环结果, 平均值, 导出路径)。
+
+    调用: 由 `run_hupd_ecsa_pipeline` 返回。
+    """
+    # ① 结论 (文件级一次; 各 cycle 条件相同不重复, 只数据不同)
+    conclusion: 'FileConclusion | None' = None
+    results: 'list[HupdEcsaResult | None]' = field(default_factory=list)   # 每 cycle: .ecsa/.area/.point_E/.point_end 类型化
+    averages: "tuple[float | None, float | None] | None" = None  # 两元组 (mean_without_first=排除 plot 1 的均值, mean_all=全部 cycle 均值) m²/g_Pt; 两值均 None 表示无法计算
+    output_path: Path | None = None
+    outcome: HupdEcsaOutcome = field(default_factory=HupdEcsaOutcome) # 各步骤成败状态
+    warnings: 'list[LogMessage]' = field(default_factory=list)        # WARNING/ERROR 级结构化日志
+    # GUI 使用: 用于创建交互图和导出
+    segments: 'list[pd.DataFrame] | None' = None            # 原始分段数据 (每段一张 E/I 表)
+    calc_segments: 'list[pd.DataFrame] | None' = None       # 可用计算片段 (剔除无效段后的 E/I 表)
+    scan_rate: float | None = None          # 扫速
+    data_df: 'pd.DataFrame | None' = None   # 完整 E/I 数据 (列 E/V, I/A)
+    file_mode: str | None = None            # 文件实际模式 'CO'/'HUPD'/'Auto'
+
+    @property
+    def total(self) -> str:
+        '''薄派生: 从 outcome 各字段现算最高级 (fail>warn>skip>ok)。'''
+        o = self.outcome
+        return _max_status([o.segment_parse, o.point_select, o.hupd_calc, o.excel])
+
+
+@dataclass
+class OxygenPipelineInput:
+    """
+    用途: 描述 O2 管道的完整输入参数 (DTA 文件列表, 电池面积, 导出选项)。
+
+    调用: 由 `cli.py run()` 和 `O2PanelController.on_calc` 构造, 传给 `run_oxygen_pipeline`。
+    """
+    dta_file_paths: list[Path]
+    cell_area: float = 5.0
+    output_path: Path | None = None
+    draw_results: bool = True
+    export_excel: bool = True
+    # 预读数据字段: 入口层一次性读入后传入, 管线不再自己读文件
+    dta_data_list: 'list[pd.DataFrame] | None' = None
+    dta_file_conditions_list: 'list[tuple[float, float] | None] | None' = None
+    dta_file_dates_list: 'list[str | None] | None' = None   # 每文件 DTA 表头 DATE, 用于顶层 date
+
+    def validate(self) -> None:
+        """检查入口层是否已传入预读数据和文件条件。"""
+        if self.dta_data_list is None:
+            raise ValueError(
+                "OxygenPipelineInput.dta_data_list 为 None -- "
+                "入口层必须调用 read_oxygen_curve_data() 传入预读数据"
+            )
+        if self.dta_file_conditions_list is None:
+            raise ValueError(
+                "OxygenPipelineInput.dta_file_conditions_list 为 None -- "
+                "入口层必须调用 parse_oxygen_file_conditions() 传入条件"
+            )
+
+
+@dataclass
+class O2InputFile:
+    '''
+    用途: 保存 O2 管线的一个输入文件身份信息 (路径, 压力, O₂ 浓度, 日期)。
+
+    调用: 由 `run_oxygen_pipeline` 从输入侧回填到 `OxygenPipelineOutput.input_files`。
+    '''
+    file_path: Path
+    pressure: 'float | None' = None   # 压力 (bar), 来自 DTA 文件名/条件解析, 缺失留 None
+    x_o2: 'float | None' = None       # O₂ 浓度 (%), = 分数分量×100, 缺失留 None
+    date: 'str | None' = None         # DTA 表头 DATE, 缺失留 None
+
+
+@dataclass
+class OxygenPipelineOutput:
+    """
+    用途: 保存 O2 管道输出 (结论, O2 结果, 阻力结果, 导出路径)。
+
+    调用: 由 `run_oxygen_pipeline` 返回。
+    """
+    # ① 运行级共享 (顶层一次; 每文件身份已在 OxygenCurveRecord, 不加 per-file 结论)
+    loading: 'float | None' = None       # 载量 mg/cm² (来源 config.pt_loading)
+    cell_area: 'float | None' = None     # 面积 cm² (config)
+    date: 'str | None' = None            # 运行级日期 (取首个 DTA DATE; 多文件约定取首文件)
+    input_files: 'list[O2InputFile]' = field(default_factory=list)   # 输入文件清单 (路径+条件+日期)
+    oxygen_result: 'OxygenResult | None' = None
+    resistance_result: 'OxygenResistanceResult | None' = None
+    output_path: Path | None = None
+    outcome: OxygenOutcome = field(default_factory=OxygenOutcome)   # 各步骤成败状态
+    warnings: 'list[LogMessage]' = field(default_factory=list)      # WARNING/ERROR 级结构化日志
+
+    @property
+    def total(self) -> str:
+        '''薄派生: 从 outcome 各字段现算最高级 (fail>warn>skip>ok)。'''
+        o = self.outcome
+        return _max_status([o.file_grouping, o.limit_curve, o.resistance, o.figure, o.excel])
+
+
+# ---- EIS ----
+@dataclass
+class EisFitSegment:
+    """EIS Nyquist linear fit segment."""
+    start: int
+    end: int
+    slope: float
+    intercept: float
+    r: float
+    x: 'np.ndarray'  # 拟合段自变量 -Z'' (负虚部, numpy (n,))
+    y: 'np.ndarray'  # 拟合段因变量 Z' (实部, numpy (n,))
+    y_fit: 'np.ndarray'  # 线性拟合值 numpy (n,)
+    r2: float = 0.0
+    mean_freq: float = 0.0
+
+
+@dataclass
+class EisFileResult:
+    """Single EIS file analysis result."""
+    file_path: Path
+    file_label: str = ''
+    freq: 'list[float]' = field(default_factory=list)    # 频率 (Hz), numpy .tolist() 转成 Python list, 与 zreal/zimag 等长
+    zreal: 'list[float]' = field(default_factory=list)   # 实部阻抗 Z' (mΩ), Python list
+    zimag: 'list[float]' = field(default_factory=list)   # 虚部阻抗 Z'' (mΩ, 负值), Python list
+    hf_intercept_interp: 'float | None' = None   # Zreal 零点穿越插值截距; 无零点穿越时 None
+    hf_intercept_fit: float = 0.0
+    lf_intercept: 'float | None' = None           # 低频段截距; 无有效 LF 段时 None
+    hf_fit_start: int = 0
+    hf_fit_end: int = 0
+    lf_fit_start: int = 0
+    lf_fit_end: int = 0
+    hf_r2: float = 0.0
+    lf_r2: float = 0.0
+    result_value: 'float | None' = None           # 3×|LF截距-HF拟合截距|; 无有效 LF 段时 None
+    hf_segment: EisFitSegment | None = None
+    lf_segment: EisFitSegment | None = None
+    conclusion: 'EisConclusion | None' = None   # 每文件: file_name/date/rh/cell_voltage
+
+    # 计算: 3 x |lf_intercept - hf_intercept_interp| (混搭拟合截距与内插截距)
+    @property
+    def result_interp(self) -> 'float | None':
+        if self.lf_segment is None or self.lf_intercept is None or self.hf_intercept_interp is None:
+            return None
+        return 3.0 * abs(self.lf_intercept - self.hf_intercept_interp)
+
+
+@dataclass
+class EisPipelineInput:
+    """
+    用途: 描述 EIS 阻抗分析管道的完整输入参数 (单文件)。
+
+    调用: 由 `cli.py run()` 和 GUI EIS 面板构造, 传给 `run_eis_pipeline`。
+    """
+    dta_file_path: Path
+    output_path: Path | None = None
+    draw_results: bool = True
+    export_excel: bool = True
+
+    # 预读数据 (入口层必须提供)
+    freq: 'np.ndarray | None' = None
+    zreal: 'np.ndarray | None' = None
+    zimag: 'np.ndarray | None' = None
+
+    # per-file 结论元数据 (入口层可提供; 缺失留 None)
+    date: 'str | None' = None            # DTA 表头 DATE
+    cell_voltage: 'float | None' = None  # DTA 表头 VDC (缺失留 None)
+
+    # 手动拟合段边界 (含入式索引, 全部 4 项提供时跳过自动段搜索)
+    hf_start: int | None = None
+    hf_end: int | None = None
+    lf_start: int | None = None
+    lf_end: int | None = None
+
+    def validate(self) -> None:
+        """检查入口层是否已传入预读的频率/阻抗数据。"""
+        if self.freq is None or self.zreal is None or self.zimag is None:
+            raise ValueError(
+                "EisPipelineInput 预读数据 (freq/zreal/zimag) 为 None -- "
+                "入口层必须调用 read_eis_curve_data() 传入预读数据"
+            )
+
+
+@dataclass
+class EisPipelineOutput:
+    """
+    用途: 保存 EIS 阻抗分析管道输出 (结论, 结果列表)。
+
+    调用: 由 `run_eis_pipeline` 返回。
+    """
+    # ① 运行级共享 (顶层一次)
+    loading: 'float | None' = None       # 载量 mg/cm² (来源 config.pt_loading)
+    cell_area: 'float | None' = None     # 面积 cm² (config)
+    output_path: Path | None = None
+    outcome: EisOutcome = field(default_factory=EisOutcome)   # 各步骤成败状态
+    warnings: 'list[LogMessage]' = field(default_factory=list)     # WARNING/ERROR 级结构化日志
+    result: 'EisFileResult | None' = None   # EIS 单文件结果 (含每文件 conclusion); 计算失败时为 None
+
+    @property
+    def total(self) -> str:
+        '''薄派生: 从 outcome 各字段现算最高级 (fail>warn>skip>ok)。'''
+        o = self.outcome
+        return _max_status([o.segment_fit, o.r2, o.excel])
+
+
+# =========================
+# FCD / ECSA 文件读取 (纯数据)
+# =========================
+
+@dataclass
+class FcdInfo:
+    """
+    用途: FCD 文件元数据。
+
+    调用: 由管道输入类 (`IvPipelineInput`, `EcsaPipelineInput`) 的 `fcd_info` 字段引用。
+    """
+    file_name: "str | None" = None
+    cell_area: "float | None" = None
+    fcd_type: str = 'IV'
+    scan_rate_vps: "float | None" = None
+    unit_sn: "str | None" = None
+    device_name: "str | None" = None    # 测试设备名称 (检测层按 unit_sn 匹配 device_map; 匹配失败为 None)
+    date: "str | None" = None      # FCD 文件表头 `Time:` 行的日期
+
+
+@dataclass
+class FcdFileResult:
+    """
+    用途: 保存 .fcd 文件读取结果 (DataFrame, 元数据, 电池面积)。
+
+    所有字段均为文件解析值, 不做合并默认值。cell_area 为 None 时表示
+    文件中未找到 SurfaceArea 字段, 由调用方自行处理默认值。
+
+    调用: 由 `read_fcd_file` 返回。使用 `to_fcd_info()` 构造轻量元数据对象供管线输入。
+    """
+    data_df: "pd.DataFrame | None" = None
+    cell_area: "float | None" = None  # FCD 文件头部 SurfaceArea 的解析值, 可能为 None
+    file_name: "str | None" = None   # FCD 文件头部 Data File 的解析值
+    fcd_type: str = 'IV'             # FCD 文件头部 PSTAT Sweep V → 'ECSA', 否则 'IV'
+    scan_rate_vps: "float | None" = None  # FCD 文件头部扫速解析值
+    unit_sn: "str | None" = None  # FCD 文件头部 UnitSN 解析值
+    date: "str | None" = None      # FCD 文件表头 `Time:` 行的日期 (如 '2026年6月14日')
+
+    def to_fcd_info(self) -> 'FcdInfo':
+        """构造轻量元数据 FcdInfo (不含 data_df), 用于管线输入。"""
+        return FcdInfo(
+            file_name=self.file_name,
+            cell_area=self.cell_area,
+            fcd_type=self.fcd_type,
+            scan_rate_vps=self.scan_rate_vps,
+            unit_sn=self.unit_sn,
+            date=self.date,
+        )
+
+
+@dataclass
+class FilePreRead:
+    """
+    用途: 通用文件预读结果, 由 detect_file_mode 返回。
+
+    覆盖 FCD,DTA-O2,DTA-EIS 三种文件类型。
+    mode 指示处理模式, 调用方根据 mode 使用对应字段:
+      - 'iv'/'ecsa-co'/'ecsa-hupd': 读 FCD 字段
+      - 'o2': 读 O2 字段
+      - 'eis': 读 EIS 字段
+
+    调用: 由 `detect_file_mode` 返回。
+    """
+    mode: str = 'iv'
+
+    # === FCD (iv / ecsa-co / ecsa-hupd) ===
+    # ECSA 文件自动检测出的真实模式 'CO'/'HUPD' (与 mode 不同: mode 可能被
+    # processing_mode 覆盖, 此字段保留 resolve_ecsa_mode 的原始判定)
+    detected_ecsa_mode: "str | None" = None
+    data_df: "pd.DataFrame | None" = None
+    cell_area: "float | None" = None
+    file_name: "str | None" = None
+    fcd_type: str = 'IV'
+    scan_rate_vps: "float | None" = None
+    unit_sn: "str | None" = None
+    device_name: "str | None" = None    # 测试设备名称 (检测层按 unit_sn 匹配 device_map; 匹配失败为 None)
+    date: "str | None" = None      # FCD 表头 `Time:` 行日期
+
+    def to_fcd_info(self) -> 'FcdInfo':
+        """构造轻量元数据 FcdInfo (不含 data_df), 用于管线输入。"""
+        return FcdInfo(
+            file_name=self.file_name,
+            cell_area=self.cell_area,
+            fcd_type=self.fcd_type,
+            scan_rate_vps=self.scan_rate_vps,
+            unit_sn=self.unit_sn,
+            device_name=self.device_name,
+            date=self.date,
+        )
+
+    # === DTA-O2 (o2): 已填充数据的 OxygenFileData 对象 (由 detect_file_mode 创建) ===
+    o2_file_objects: "list[OxygenFileData] | None" = None
+
+    # === DTA-EIS (eis) ===
+    eis_file_data: "tuple[np.ndarray, np.ndarray, np.ndarray, 'str | None', 'float | None'] | None" = None
+
+
+@dataclass
+class EcsaDataResult:
+    """
+    用途: 保存 ECSA 数据读取与分段结果 (原始数据, 模式, 片段列表, 扫速)。
+
+    调用: 由 `_begin_ecsa_pipeline` 返回。
+    """
+    data_df: "pd.DataFrame | None" = None
+    raw_data_df: "pd.DataFrame | None" = None
+    mode: str = "Auto"
+    cell_area: float = 5.0
+    data_df_list: list = field(default_factory=list)
+    ecsa_calc_df_list: list = field(default_factory=list)
+    scan_rate_vps: "float | None" = field(default=None)
+    fcd_info: "FcdInfo | None" = None
+
+
+def concat_plot_data_indices(index_series):
+    '''
+    用途: 拼接用于绘图的非空数据索引数组。
+    调用: 由 `draw_iv_overview` 调用。
+    返回: 返回 Numpy 索引数组或 None。
+    '''
+    valid_indices = [item for item in index_series.values if len(item) > 0]
+    if not valid_indices:
+        return None
+    return np.concatenate(valid_indices)
+
+
+# =========================
+# 引擎导出辅助
+# =========================
+# 输出路径辅助
+# =========================
+
+def _auto_output_path(mode: str, file_paths: list[Path]) -> Path:
+    """
+    用途: 管线在 output_path 为 None 时的兜底输出路径。
+          目录取首个输入文件所在目录 (管线兜底层无 result_path 概念), 文件名用
+          build_output_filename 统一命名。
+
+    调用: 由 IV/ECSA/O2/EIS 管道引擎在 output_path 为 None 时调用。
+    返回: 返回 Path。
+    """
+    first = Path(file_paths[0])
+    return first.parent / build_output_filename(mode, file_paths)
+
+
+def extract_folder_name(first_path: Path) -> str:
+    '''
+    用途: 从单个文件路径提取自动命名用的文件夹名 (通常含实验日期)。
+          父文件夹名 <=5 字符时回退祖父目录名 (所有模式一致); 路径为空时回退 'data'。
+          first_path 可为 str/Path 或 OxygenFileData 包装 (内部先解包 .path)。
+
+    参数:
+        first_path: 首个输入文件路径 (str / Path / OxygenFileData 包装)。
+
+    调用: 由 `build_output_filename` 调用, 供 GUI 与 CLI 自动命名共用。
+    返回: 命名用文件夹名字符串。
+    '''
+    if not first_path:
+        return 'data'
+    first = Path(getattr(first_path, 'path', first_path))
+    folder_name = first.parent.name
+    if len(folder_name) <= 5:
+        folder_name = first.parent.parent.name
+    return folder_name
+
+
+_PANEL_KEY_TO_MODE = {'iv': 'iv', 'co': 'ecsa-co', 'hupd': 'ecsa-hupd',
+                      'oxygen': 'o2', 'eis': 'eis'}
+
+
+def panel_key_to_mode(panel_key: str) -> str:
+    '''
+    用途: GUI panel_key ('co'/'hupd'/'oxygen') 转管线 mode; 不认识的键原样返回。
+
+    调用: 由 GUI `_set_file_paths`/`_on_save_path` 调用, 使 GUI 传给共享命名函数的是标准 mode。
+    返回: mode 字符串。
+    '''
+    return _PANEL_KEY_TO_MODE.get(panel_key, panel_key)
+
+
+def build_output_filename(mode: str, file_paths: list[Path]) -> str:
+    '''
+    用途: 生成统一命名的输出 Excel 文件名 {mode}_{文件夹名}_{YYYYMMDD_HHMMSS}.xlsx。
+          文件夹名经 extract_folder_name 提取 (父目录 ≤5 字符回退祖父, 所有模式一致)。
+          只返回文件名, 不含目录, 目录由各调用方 (管线兜底=文件同目录, GUI=result_path,
+          manifest=output_dir) 自行前置。file_paths 可含 OxygenFileData 包装 (extract_folder_name
+          内部解包 .path)。
+
+    参数:
+        mode: 管线 mode ('iv'/'ecsa-co'/'ecsa-hupd'/'o2'/'eis')。
+        file_paths: 输入文件路径列表 (至少 1 个, 命名仅取首个文件)。
+
+    调用: 由 `_auto_output_path`, GUI `_set_file_paths`/`_on_save_path`, CLI `_run_manifest`
+          共用, 统一自动命名格式。
+    返回: 文件名 str (如 'ecsa-co_H2数据_20260810_143055.xlsx')。
+    '''
+    first_path = next(iter(file_paths), None)
+    folder_name = extract_folder_name(first_path)
+    ts = datetime.now().strftime('%Y%m%d_%H%M%S')
+    return f'{mode}_{folder_name}_{ts}.xlsx'
+
+
+# =========================
+# 工具函数 (供 computations.py / plotting.py 复用, 避免循环导入)
+# =========================
+
+def safe_linear_fit(x: Any, y: Any, min_points: int = 2) -> LinearFitResult:
+    '''
+    用途: 执行带校验的线性回归并保留过滤后的拟合数据。
+
+    调用: 由 `build_linear_fit_figure_from_data` / `build_linear_fit_figure_from_result`, H2/MA 拟合和 O2 阻力计算流程调用。
+    返回: 返回 `LinearFitResult`。
+    '''
+    x_arr = pd.to_numeric(pd.Series(x), errors='coerce').to_numpy(dtype=float)
+    y_arr = pd.to_numeric(pd.Series(y), errors='coerce').to_numpy(dtype=float)
+    valid_mask = np.isfinite(x_arr) & np.isfinite(y_arr)
+    x_valid = x_arr[valid_mask]
+    y_valid = y_arr[valid_mask]
+    if len(x_valid) < min_points:
+        raise ValueError(f'线性拟合有效点少于 {min_points} 个')
+    if np.ptp(x_valid) == 0:
+        raise ValueError('线性拟合的 x 值全部相同')
+    slope, intercept, r, *_ = linregress(x_valid, y_valid)
+    y_fit = x_valid * slope + intercept
+    return LinearFitResult(slope, intercept, r, x_valid, y_valid, y_fit)
+
+
+def calculate_hupd_ecsa_averages(ecsa_values: list[float | None]) -> tuple[float | None, float | None]:
+    '''
+    用途: 在所有 HUPD 子图处理完成后计算平均值。
+
+    调用: 由 `run_hupd_ecsa_pipeline`, `apply_hupd_result_to_ui` 调用。
+    返回: 返回 `(mean_without_first, mean_all)`。
+    '''
+    mean_all = None
+    mean_without_first = None
+    completed_values = [value for value in ecsa_values if value is not None]
+    if len(completed_values) == len(ecsa_values) and completed_values:
+        mean_all = sum(completed_values) / len(completed_values)
+
+    tail_values = ecsa_values[1:]
+    completed_tail_values = [value for value in tail_values if value is not None]
+    if tail_values and len(completed_tail_values) == len(tail_values):
+        mean_without_first = sum(completed_tail_values) / len(completed_tail_values)
+    return mean_without_first, mean_all
+
+
+def calculate_oxygen_resistance_result(data_dict: dict[float, list[Any]], flow_rate: float, r_corr_func: Any) -> OxygenResistanceResult:
+    '''
+    用途: 纯计算 O2 阻力拟合表, 最终结果和拟合记录。
+
+    调用: 由 `run_oxygen_pipeline` 调用。
+    返回: 返回 `OxygenResistanceResult`。
+    '''
+    xi_rows = []
+    xi_index = []
+    current_fits = []
+    j_fit_by_pressure = {}
+
+    for pressure, file_list in data_dict.items():
+        x_list = [file.o2_fraction for file in file_list]
+        j_list = [file.jm for file in file_list]
+        fit = safe_linear_fit(x_list, j_list)
+        if abs(fit.slope) < 1e-12:
+            raise ValueError(f'{pressure}bar 的 I-xO2 拟合斜率为 0, 无法计算 R_total')
+        r_total = (4 * PHYS.FARADAY_CONSTANT * (pressure - PHYS.WATER_VAPOR_PRESSURE_BAR) * PHYS.BAR_TO_KPA) / (fit.slope * PHYS.GAS_CONSTANT * PHYS.CELL_TEMPERATURE_K) / PHYS.R_TOTAL_UNIT_DIVISOR
+        xi_rows.append([fit.slope, fit.intercept, fit.r, r_total])
+        xi_index.append(f'{pressure}bar')
+        j_fit_by_pressure[pressure] = np.array(x_list) * fit.slope + fit.intercept
+        current_fits.append(OxygenFitRecord(f'{pressure}bar', x_list, j_list, fit, x_min=0))
+
+    xi_df = pd.DataFrame(xi_rows, columns=['slope', 'intercept', 'r', 'R_total'], index=xi_index, dtype=float)
+
+    if len(xi_df) < 2:
+        raise ValueError('O2 Rtotal-Pressure 拟合有效压力点少于 2 个')
+
+    pressure_fit = safe_linear_fit(list(data_dict.keys()), xi_df['R_total'].tolist())
+    xi_df['R_total_fit'] = pressure_fit.y_fit
+    rpi_correct = r_corr_func(pressure_fit.slope, pressure_fit.intercept, flow_rate)
+    result_df = pd.DataFrame({
+        'R_PI(s/cm)': [pressure_fit.intercept],
+        'slope(s/(cm*kPa))': [pressure_fit.slope / PHYS.R_TOTAL_UNIT_DIVISOR],
+        'r': [pressure_fit.r],
+        'R_PI_correct': [rpi_correct],
+    })
+
+    result = OxygenResistanceResult(
+        xi_df=xi_df,
+        result_df=result_df,
+        current_fits=current_fits,
+        pressure_fit=OxygenFitRecord(
+            'Rtotal-Pressure',
+            list(data_dict.keys()),
+            xi_df['R_total'].tolist(),
+            pressure_fit,
+        ),
+        j_fit_by_pressure=j_fit_by_pressure,
+    )
+    return result
+
+
+def calculate_oxygen_corrected_resistance(slope: float, intercept: float, flowrate: float, config: Config) -> float:
+    '''
+    用途: 根据 O2 流道和水修正参数计算修正阻力。
+    调用: 由 `calculate_oxygen_resistance_result` 调用。
+    返回: 返回修正后的阻力值。
+    '''
+    return (
+        intercept
+        - (slope / 100) * PHYS.WATER_VAPOR_PRESSURE_KPA * ((PHYS.O2_D_ON_NAFION / PHYS.O2_D_OW_WATER) - 1)
+        + PHYS.O2_CORRECTION_FACTOR_1
+        * 2
+        * config.o2_n_flow_channel
+        * config.o2_l_flow_channel
+        * PHYS.O2_CORRECTION_FACTOR_2
+        * PHYS.CELSIUS_TO_KELVIN_OFFSET
+        * PHYS.WATER_VAPOR_PRESSURE_KPA
+        * PHYS.O2_D_ON_NAFION
+        / (
+            (flowrate * PHYS.LPM_TO_MLS)
+            * (config.o2_cell_temp + PHYS.CELSIUS_TO_KELVIN_OFFSET)
+            * PHYS.AMBIENT_PRESSURE_KPA
+            * PHYS.O2_D_OW_WATER
+        )
+    )
+
+
+# =========================
+# 文件类型检测工具函数
+# =========================
+
+
+def detect_dta_subtype(file_path: Path) -> str | None:
+    """读取 DTA 文件第 2 行的 TAG 标记, 返回子类型: 'o2' | 'eis' | None。
+
+    用途: 在 auto 模式下区分 O2 (LSV) 和 EIS (阻抗谱) 数据。
+          仅读取前 2 行, 轻量快速。
+
+    调用: 由 `gui.py._on_file_selected` 和 `cli.py.run_pipeline` 调用。
+    """
+    try:
+        with open(file_path, encoding='utf-8', errors='ignore') as f:
+            lines = [f.readline() for _ in range(2)]
+        tag_line = lines[1].strip() if len(lines) >= 2 else ''
+        if '\tLSV' in tag_line:
+            return DTA_SUBTYPE_O2
+        if '\tEISPOT' in tag_line:
+            return DTA_SUBTYPE_EIS
+        return None  # 未知 TAG
+    except Exception:
+        return None
+
+
+# =========================
+# O2 文件模型
+# =========================
+
+
+def parse_oxygen_file_conditions(filename: str, fallback_pattern: str, services: 'RuntimeServices') -> tuple[float, float] | None:
+    '''
+    用途: 从文件名解析压力和 O2 浓度。
+
+    参数:
+        filename: 文件名 (不含路径, 如 "1.0bar-2.0%O2.DTA")。
+        fallback_pattern: o2_filename_pattern 配置值, 关键字匹配失败时做盲匹配降级。
+        services: RuntimeServices 实例, 用于输出警告日志。
+
+    调用: 由入口层和 `group_oxygen_files_by_pressure` 调用。
+    返回: 返回 `(pressure, x_o2)` 或 `None`。
+    '''
+    p_pattern = r'(\d+(?:\.\d+)?)\s*bar'
+    x_pattern = r'(\d+(?:\.\d+)?)\s*(?:%O2|%|O2)'
+    p_match = re.findall(p_pattern, filename)
+    x_match = re.findall(x_pattern, filename)
+    try:
+        pressure = float(p_match[0])
+    except Exception:
+        services.show('', f'无法从文件名解析压力 ({filename})', 'WARNING')
+        pressure = None
+
+    try:
+        x_value = float(x_match[0])
+    except Exception:
+        services.show('', f'无法从文件名解析 O₂ 浓度 ({filename})', 'WARNING')
+        x_value = None
+
+    if (pressure is not None) and (x_value is not None):
+        return (pressure, x_value / 100)
+
+    match = re.findall(fallback_pattern, filename)
+    try:
+        pressure = float(match[0])
+        x_value = float(match[1])
+        return (pressure, x_value / 100)
+    except Exception:
+        services.show('', f'无法从文件名解析 O₂ 浓度 ({filename})', 'WARNING')
+        return None
+
+
+class OxygenFileData:
+    '''
+    用途: 封装一个 O2 数据文件的路径, 预读数据和解析出的条件。
+
+    调用: 由 O2 管线创建和分组流程使用。
+    '''
+    def __init__(self, path: 'Path | str'):
+        self.path = Path(path)
+        self.data_df: 'pd.DataFrame | None' = None
+        self.conditions: 'tuple[float, float] | None' = None
+        self.vm: float | None = None
+        self.im: float | None = None
+        self.jm: float | None = None
+        self.date: 'str | None' = None   # DTA 表头 DATE (运行级日期来源)
+
+    def apply_record(self, record) -> None:
+        '''回填 O2 曲线限流点结果。'''
+        self.vm = record.vm
+        self.im = record.im
+        self.jm = record.jm
+
+    @property
+    def pressure(self) -> float | None:
+        return self.conditions[0] if self.conditions else None
+
+    @property
+    def o2_fraction(self) -> float | None:
+        return self.conditions[1] if self.conditions else None
+
+
+# =========================
+# 自更新
+# =========================
+#
+# 用途: 让 GUI 里的「检查更新」从"只告知"升级为"发现新版 -> 用户确认 -> 自动执行 pip 更新"。
+#
+# 为什么必须由**另一个进程**执行:
+#   程序自己没有安装权限也没有干净的文件状态。做法是程序拉起一个脱离父进程的更新器
+#   (python -c <payload>, DETACHED_PROCESS), 然后自己退出; 更新器等父进程消失后再动手。
+#   实测纯 .py 模块在 Windows 上**不会**被运行中的解释器锁住 (另一进程可覆盖/删除已 import 的
+#   源文件), 因此"等父进程退出"不是文件锁的需要, 而是语义需要: 让磁盘代码与内存代码的
+#   版本不一致窗口尽量短, 也避免更新器与仍在运行的旧进程同时改动同一批文件。用户下次打开
+#   程序时读结果弹一次。
+#
+# 为什么更新目标是"当前程序目录"而不是写死 site-packages:
+#   pip 形态下本进程加载的就是 site-packages 里那份, 传"本进程代码所在目录"比写字符串更可靠
+#   (虚拟环境 / --user 安装 / 多份 dist-info 时路径各不相同); 源码副本形态不进入本流程
+#   (「立即更新」置灰), 因为 pip 只会改 site-packages 里另一份, 用户跑的那份不会变。
+#
+# 注意: 本分区的 pip 开关是**唯一一处**定义; 测试里守住开关内容与拼出的命令形状,
+#       防止后续无意放宽。
+
+# 更新结果文件: 更新器写一次, 程序下次启动读一次后**立即删除** (不保留日志, 不产生垃圾)
+UPDATE_RESULT_FILE_NAME = 'update_result.json'
+PIP_INSTALL_FLAGS: tuple[str, ...] = ('--upgrade', '--no-deps',
+                                      '--disable-pip-version-check', '--no-input')
+# 更新器的等待策略: 轮询父进程消失的上限, 以及消失后额外等待的秒数
+# (额外等待是给 Windows 释放句柄与杀毒扫描留余量, 避免"刚退就写"的偶发失败)
+UPDATE_WAIT_PID_TIMEOUT_S = 60.0
+UPDATE_POST_EXIT_DELAY_S = 2.0
+UPDATE_POLL_INTERVAL_S = 0.5
+
+
+def is_updatable_install(module_file: Path | str = __file__) -> bool:
+    '''
+    用途: 判断当前这份代码能否使用程序内自更新 (决定「立即更新」按钮是否可点)。
+
+    参数:
+        module_file: 任一核心模块的 __file__ (默认本模块)。
+
+    调用: 由 GUI 的 `CheckUpdateDialog` (按钮置灰) 与其防御性兜底分支调用。
+
+    返回: 仅当这份代码位于 site-packages 之下 (pip 安装形态) 时为 True; 其余形态与任何
+          判别异常一律 False。
+
+    注意: 判据是"**装在哪**", 不是"能不能写"。
+          非 pip 形态一律置灰, 原因: 自更新走 `pip install --target <本进程代码所在目录>`,
+          而 pip 只会改 site-packages 里的那一份; 源码副本 / 开发仓库里跑的代码不在 pip
+          管辖范围内, 装了也不生效, 容易让用户以为更新成功了。这些形态的正路是
+          `pip install fcdp` (唯一分发方式), 弹窗文案 (`CHECK_UPDATE_NOT_AVAILABLE`) 直接
+          给出这条命令; 源码副本可用但不提供维护。
+          不用可写性的原因: `os.access(dir, os.W_OK)` 在 Windows 上只看只读属性, 不查 ACL,
+          对目录几乎恒为 True, 拦不住无写权限的安装; pip 形态下的权限失败由 pip 的退出码
+          与下次启动的回执 (`CHECK_UPDATE_FAILED_HINT`) 告知。
+          本函数**保证不抛异常** (判别属旁路逻辑, 不得阻断启动)。
+    '''
+    try:
+        return detect_install_mode(module_file) == 'pip-install'
+    except Exception:
+        return False
+
+
+def build_install_command(python: str, target: Path | str, version: str | None = None) -> list[str]:
+    '''
+    用途: 拼出程序内自更新使用的 pip 命令。
+
+    参数:
+        python: 解释器路径 (通常 sys.executable)。
+        target: 安装目标目录 (必须指向本进程实际加载代码的目录, 见分区说明)。
+        version: 目标版本; None 表示装索引上的默认版本 (最新)。
+
+    调用: 由 `start_self_update` 拼更新器命令行; 测试用它核对开关与命令形状。
+
+    返回: 命令参数列表。
+
+    注意: **带** `--no-deps`: 只覆盖程序自己的模块文件, 依赖 (pandas/numpy/...) 由用户环境提供,
+          更新时绝不擅自改动用户的依赖环境 (依赖不满足时由用户自行补装, 启动器会在缺依赖时
+          列出模块名与补装命令)。
+    '''
+    spec = f'{DIST_NAME}=={version}' if version else DIST_NAME
+    return [python, '-m', 'pip', 'install', *PIP_INSTALL_FLAGS, '--target', str(target), spec]
+
+
+def _temp_dir() -> Path | None:
+    '''系统临时目录; 取不到时返回 None (候选表里跳过这一档)。'''
+    try:
+        import tempfile
+        return Path(tempfile.gettempdir())
+    except Exception:
+        return None
+
+
+def _local_appdata_root(create: bool = True) -> Path:
+    '''更新结果文件的**首选**目录; 逐级回退, 保证一定有一个候选。
+
+    参数:
+        create: True 时确保目录存在 (写结果时用); False 时只挑第一个已存在且可写的候选,
+                不产生任何建目录副作用 (启动时读结果用)。
+
+    注意: 首选 `user_config_dir()` (pip 安装形态即配置文件所在目录); 源码副本 / 开发仓库形态下
+          配置在程序目录里, 本目录只是用户数据目录, 与配置归属无关; 结果文件属"机器级一次性
+          通知", 读写的两端都是本机同一个进程组, 放这里不会串。
+          这里的可写性判断 (`os.access`) 在 Windows 上只看只读属性, 不查 ACL, 因此**不保证**
+          结果文件真能写进来。它只是候选 #1: 读回执遍历 `_update_result_dirs()` 的全部候选,
+          写回执遍历 `update_result_paths()` 并逐条重试, 两侧不会因判断口径不同而错开。
+    '''
+    candidates = [user_config_dir()]
+    temp_dir = _temp_dir()
+    if temp_dir is not None:
+        candidates.append(temp_dir)
+    candidates.append(_PROJECT_ROOT)
+    if not create:
+        for target in candidates:
+            if target.is_dir() and os.access(target, os.W_OK):
+                return target
+        return candidates[0]
+    for target in candidates:
+        try:
+            target.mkdir(parents=True, exist_ok=True)
+            return target
+        except OSError:
+            continue
+    return _PROJECT_ROOT
+
+
+def _update_result_dirs() -> list[Path]:
+    '''读回执的候选目录 (有序去重): 首选 `_local_appdata_root`, 再补临时目录与程序目录。
+
+    调用: 由 `read_update_result` 与 `update_result_paths` 调用。
+
+    注意: 这三档就是 `_local_appdata_root` 内部使用的同一批候选。之所以把整张候选表暴露出来,
+          是因为"写进去的那个目录"未必等于"判断为可写的那个目录" (只读属性与 ACL 不是一回事,
+          且写入失败是静默的)。读侧遍历全部候选, 写入端无论落在哪一档都能被读到。
+          本函数只拼路径, 不建目录, 不抛异常。
+    '''
+    dirs: list[Path] = []
+    for candidate in (_local_appdata_root(create=False), _temp_dir(), _PROJECT_ROOT):
+        if candidate is not None and candidate not in dirs:
+            dirs.append(candidate)
+    return dirs
+
+
+def update_result_path() -> Path:
+    '''
+    用途: 更新结果文件的**首选**绝对路径 (会确保所在目录存在)。
+
+    调用: 测试用它定位结果文件; 写路径见 `update_result_paths` (逐条重试)。
+          读路径 (GUI 启动) 不经过本函数, 而是遍历 `_update_result_dirs()`,
+          避免启动期产生建目录副作用 (见 `read_update_result`)。
+    '''
+    return _local_appdata_root() / UPDATE_RESULT_FILE_NAME
+
+
+def update_result_paths() -> list[Path]:
+    '''
+    用途: 写回执时的候选路径 (有序去重): 首选 `update_result_path()`, 再补其余候选目录。
+
+    调用: 由 `write_update_result` 与 `build_updater_payload` (内联进更新器的 RESULT 列表) 调用。
+
+    返回: 路径列表 (至少一项, 不会为空)。
+
+    注意: 写端逐条尝试, 第一条成功即返回 -- 首选目录因 ACL / 只读属性写不进去时, 回执会落到
+          后面的候选目录, 而读端覆盖同一批目录, 因此仍然读得到 ("写了却永远读不到"是本次
+          复核修掉的问题之一)。
+    '''
+    paths: list[Path] = [update_result_path()]
+    for directory in _update_result_dirs():
+        candidate = directory / UPDATE_RESULT_FILE_NAME
+        if candidate not in paths:
+            paths.append(candidate)
+    return paths
+
+
+def write_update_result(payload: dict) -> None:
+    '''
+    用途: 写入一份更新结果; 失败时静默 (不能让结果文件写失败反过来报错)。
+
+    参数:
+        payload: 结果字典, 至少含 status ('ok' / 'failed') 与 message。
+
+    调用: 测试调用 (验证结果文件格式与读回语义)。
+
+    注意: **生产路径不调用本函数**, 真正写文件的是 `build_updater_payload` 生成的更新器
+          进程, 它必须自包含 (不能 import 项目模块, 见该函数说明), 因此内联了一份等价实现。
+          本函数是该写法的可读参考实现: 改格式 (ensure_ascii / indent / 吞 OSError) 或改候选
+          路径枚举 (`update_result_paths`) 时必须同步 `build_updater_payload` 里的 `write()`。
+          逐个候选路径重试, 第一条写成功即返回。
+
+    返回: 无。
+    '''
+    text = json.dumps(payload, ensure_ascii=False, indent=2)
+    for path in update_result_paths():
+        try:
+            path.write_text(text, encoding='utf-8')
+            return
+        except OSError:
+            continue
+
+
+def read_update_result() -> dict | None:
+    '''
+    用途: 读取上次更新留下的结果, **读完即删** (一次性通知, 不留垃圾)。
+
+    调用: 由 GUI 启动流程调用。
+
+    返回: 结果字典; 所有候选目录里都没有 / 内容损坏 / 缺 status 字段时返回 None。
+
+    注意: 本函数保证不抛异常 (启动路径上的旁路逻辑); 只有一种结果格式, 不设 schema 版本号。
+          按 `_update_result_dirs()` 的顺序遍历候选目录, 命中即读并删除, 不依赖"写端当时挑了
+          哪个目录"; 全程只读不建目录。命中一个候选但内容不可解析时直接返回 None (已删),
+          不再继续找后面的候选, 避免把上一次的旧回执当成这一次的结果。
+    '''
+    try:
+        for directory in _update_result_dirs():
+            path = directory / UPDATE_RESULT_FILE_NAME
+            if not path.is_file():
+                continue
+            try:
+                text = path.read_text(encoding='utf-8')
+            except OSError:
+                return None
+            try:
+                path.unlink()               # 先读后删: 无论内容是否可解析, 都不留下垃圾
+            except OSError:
+                pass
+            record = json.loads(text)
+            if not isinstance(record, dict):
+                return None
+            if record.get('status') not in ('ok', 'failed'):
+                return None
+            return record
+        return None
+    except Exception:
+        return None
+
+
+def build_updater_payload(target: Path | str, version: str | None, python: str,
+                         command: list[str] | None = None) -> str:
+    '''
+    用途: 生成更新器的 Python 源码 (由 `python -c` 执行, 不落任何脚本文件)。
+
+    参数:
+        target: 安装目标目录 (本进程实际加载代码的目录)。
+        version: 目标版本; None 表示索引默认版本。
+        python: 执行 pip 的解释器路径。
+        command: 覆盖实际执行的命令 (仅测试注入用): None 时按 `build_install_command` 拼 pip 命令。
+                 测试传一条轻量命令就能**真跑**更新器并断言行为, 不必按源码文本断言。
+
+    调用: 由 `start_self_update` 使用。
+
+    返回: 可直接传给 `python -c` 的源码字符串。
+
+    注意: payload 内部**不再 import 项目模块**, 它会在等待父进程期间先执行,
+          期间 pip 还会替换磁盘上的代码, 因此它必须完全自包含 (只依赖标准库):
+          进程存活判定与结果写盘都在 payload 内联实现, 模块级只保留 `read_update_result`
+          这个"读回执"的轻量入口 (启动路径上使用), 见 `read_update_result` 的说明。
+          回执目标是一张**候选路径表** (`update_result_paths`), 逐条尝试写入, 与读侧的
+          `_update_result_dirs` 覆盖同一批目录。pip 成功即记 status='ok', 此时 `version`
+          可能为 None (装是装上了, 只是读不到 _shared.py 里的版本号)。
+          payload 成功后写入 `version` 与 (非空时) `removed`,
+          GUI 启动时读回执并向用户展示这次更新清理了哪些残留模块。
+    '''
+    active = command if command is not None else build_install_command(python, target, version)
+    quoted = ', '.join(repr(item) for item in active)
+    lines = [
+        'import json, os, subprocess, sys, time',
+        f'TARGET = {str(target)!r}',
+        f'COMMAND = [{quoted}]',
+        f'MODULES = {CORE_MODULE_NAMES!r}',
+        f'RESULT = {[str(path) for path in update_result_paths()]!r}',
+        f'TIMEOUT = {UPDATE_WAIT_PID_TIMEOUT_S!r}',
+        f'DELAY = {UPDATE_POST_EXIT_DELAY_S!r}',
+        f'POLL = {UPDATE_POLL_INTERVAL_S!r}',
+        'PID = int(sys.argv[1]) if len(sys.argv) > 1 else 0',
+        '',
+        'def alive(pid):',
+        '    if pid <= 0:',
+        '        return False',
+        '    try:',
+        "        if os.name == 'nt':",
+        '            import ctypes',
+        '            handle = ctypes.windll.kernel32.OpenProcess(0x00100000, False, pid)',
+        '            if not handle:',
+        '                return False',
+        '            try:',
+        '                return ctypes.windll.kernel32.WaitForSingleObject(handle, 0) == 0x00000102',
+        '            finally:',
+        '                ctypes.windll.kernel32.CloseHandle(handle)',
+        '        os.kill(pid, 0)',
+        '        return True',
+        '    except Exception:',
+        '        return False',
+        '',
+        'def write(payload):',
+        '    for path in RESULT:',
+        '        try:',
+        '            with open(path, \'w\', encoding=\'utf-8\') as handle:',
+        '                json.dump(payload, handle, ensure_ascii=False, indent=2)',
+        '            return',
+        '        except OSError:',
+        '            continue',
+        '',
+        'def read_version():',
+        '    import re',
+        '    try:',
+        "        text = open(os.path.join(TARGET, '_shared.py'), encoding='utf-8').read()",
+        '    except OSError:',
+        '        return None',
+        '    found = re.search(r"^__version__\\s*(?::\\s*str\\s*)?=\\s*[\'\\"](\\d{8})[\'\\"]",',
+        '                      text, re.M)',
+        '    return found.group(1) if found else None',
+        '',
+        '# 1) 等父进程退出 (上限 TIMEOUT), 再多等 DELAY 秒让系统释放句柄',
+        'deadline = time.time() + TIMEOUT',
+        'while alive(PID) and time.time() < deadline:',
+        '    time.sleep(POLL)',
+        'time.sleep(DELAY)',
+        '',
+        '# 2) 执行 pip。此处**不在 pip 之前删除任何模块**: 那会在更新失败时把安装毁掉,',
+        '#    而 pip 自己会覆盖同名文件 (--upgrade 的语义)。',
+        'try:',
+        '    done = subprocess.run(COMMAND, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,',
+        '                          env=dict(os.environ, PYTHONIOENCODING=\'utf-8\'), timeout=1800)',
+        '    code = done.returncode',
+        'except Exception as ex:',
+        '    write({\'status\': \'failed\', \'message\': f"无法启动 pip: {type(ex).__name__}: {ex}",',
+        '           \'target\': TARGET})',
+        '    sys.exit(1)',
+        '',
+        '# 3) pip 成功后, 按新版的 RECORD 清掉它已不再提供的核心模块; 读不到 RECORD 就不动,',
+        '#    因为"不知道新版提供什么"时删除等于自毁安装。',
+        'def drop_obsolete(installed_version):',
+        '    import glob as _glob',
+        '    records = _glob.glob(os.path.join(TARGET, "fcdp-*.dist-info", "RECORD"))',
+        '    if not records:',
+        '        return []',
+        '    # 目录名形如 fcdp-<版本>.dist-info。pip 的 --target 升级只替换同名条目, 旧版元数据目录',
+        '    # 会一直残留, 所以不能取列举到的第一条 (那往往是最早装的那份): 优先精确匹配本次装出的',
+        '    # 版本, 否则取数字段最大的一份。这里逐段转 int 比较, 避免多段版本号被字典序排错。',
+        '    def rank(path):',
+        '        name = os.path.basename(os.path.dirname(path))',
+        '        parts = name.split("-")[1] if "-" in name else ""',
+        '        return ([int(p) for p in parts.split(".") if p.isdigit()], path)',
+        '    chosen = None',
+        '    if installed_version:',
+        '        exact = os.path.join(TARGET, f"fcdp-{installed_version}.dist-info", "RECORD")',
+        '        if exact in records:',
+        '            chosen = exact',
+        '    if chosen is None:',
+        '        chosen = sorted(records, key=rank)[-1]',
+        '    try:',
+        '        text = open(chosen, encoding="utf-8", errors="replace").read()',
+        '    except OSError:',
+        '        return []',
+        '    provided = {line.split(",", 1)[0].strip().replace("/", os.sep)',
+        '                for line in text.splitlines() if line.strip()}',
+        '    dropped = []',
+        '    for name in MODULES:',
+        '        if name in provided:',
+        '            continue',
+        '        path = os.path.join(TARGET, name)',
+        '        if os.path.isfile(path):',
+        '            try:',
+        '                os.remove(path)',
+        '                dropped.append(name)',
+        '            except OSError:',
+        '                pass',
+        '    return dropped',
+        '',
+        'version = read_version()',
+        'if code == 0:                   # pip 成功即更新成功; 读不到版本号不改判为失败 (装是装上了)',
+        '    dropped = drop_obsolete(version)',
+        '    record = {\'status\': \'ok\', \'version\': version, \'target\': TARGET,',
+        '              \'message\': f\'已更新到 {version}\' if version else \'更新已完成, 未能读取版本号\'}',
+        '    if dropped:                     # 空列表不写, 免得回执里出现"已清理: "这样的空话',
+        '        record[\'removed\'] = dropped',
+        '    write(record)',
+        'else:',
+        '    write({\'status\': \'failed\', \'target\': TARGET,',
+        '           \'message\': f\'pip 退出码 {code}\'})',
+        'sys.exit(code)',
+    ]
+    return '\n'.join(lines)
+
+
+def start_self_update(target: Path | str, version: str | None = None,
+                      python: str | None = None) -> int | None:
+    '''
+    用途: 拉起一个脱离父进程的更新器, 由它在本进程退出后执行 pip 更新。
+
+    参数:
+        target: 安装目标目录 (应为本进程实际加载代码的目录)。
+        version: 目标版本; None 表示索引默认版本。
+        python: 执行更新器的解释器; None 表示 sys.executable。
+
+    调用: 由 GUI 的「立即更新」确认流程调用, 随后调用方应立即退出程序。
+
+    返回: 更新器进程号; 拉起失败返回 None (调用方据此提示用户改用 pip install --upgrade fcdp)。
+
+    注意: 更新器用 `python -c <payload>` 启动, **不写任何脚本文件**;
+          Windows 上带 DETACHED_PROCESS + CREATE_NEW_PROCESS_GROUP, 与父进程完全脱钩,
+          标准流全部丢弃 (不弹控制台窗口); 结果由更新器写入 update_result.json
+          (首选用户数据目录, 写不进去时落到候选表里的下一档), 程序下次启动时读取并删除。
+          调用方 (GUI) 必须**紧接着退出程序**: 更新器只会等父进程 60 s, 之后无论父进程是否
+          还在都会开始装, 留着界面不退出只会拉长"磁盘已换, 内存还是旧版"的时间。
+    '''
+    interpreter = python or sys.executable
+    payload = build_updater_payload(target, version, interpreter)
+    kwargs: dict = {'stdin': subprocess.DEVNULL, 'stdout': subprocess.DEVNULL,
+                    'stderr': subprocess.DEVNULL, 'close_fds': True}
+    if os.name == 'nt':
+        kwargs['creationflags'] = (subprocess.DETACHED_PROCESS
+                                   | subprocess.CREATE_NEW_PROCESS_GROUP)
+    else:
+        kwargs['start_new_session'] = True
+    try:
+        process = subprocess.Popen([interpreter, '-c', payload, str(os.getpid())], **kwargs)
+    except Exception:
+        return None
+    return process.pid
+
+
+if __name__ == '__main__':
+    print("This module is not meant to be run directly. Use 'python gui.py' to start the application.")