refactor(编号): 采集链分层 L1/L1.5/L2/L2.5/L3/L4/L5 → 语义名（批次 1）

用户裁定（2026-10-28）：L1/L1.5/L2/L2.5/L3 这套层号「谁能看懂」，改用语义名。映射（同一批定稿，含 L4/L5）： L1 → 语义取数与有效性 L1.5 → 标定折算 L2 → 全周傅氏相量 L2.5 → 测频与遥测快照 L3 → 保护判据 L4 → 出口与记录 L5 → 动作留痕实测规模：384 站点 / 62 文件（App/algo、App/task、test/host 六个套件、docs/算法、产品需求、架构总览、启动顺序、ADC 采样节拍、IEC104 上行、采集短板评测、内存管理、 AGENTS.md、README.md、docs/README.md、.pre-commit-config.yaml 与 scripts 里的注释）。改法（不是全局替换，逐模式有上下文规则）： - 先吃同位语再落裸词：L1 有效性校验 → 语义取数与有效性校验、L2 相量层 → 全周傅氏相量层、L3 保护 → 保护判据、L2.5 遥测快照 → 测频与遥测快照，避免「保护判据保护判据」这类重复（第一版就是这么坏掉的，已整体回滚重做）。 - .c/.h 只改注释：先把字符串字面量切出去（引号数为奇数的跨行注释按整行处理）， C 字符串里的 L2-in ring 之类原样保留——AGENTS 铁律「字符串字面量必须纯 ASCII」。 - 层内条目号（L1-3 / L2-3 这类）**本批不动**，属批次 2；另外三族（UI 菜单层级 L0~L3、链路延迟分段 L1~L8、CubeMX 防丢失三层）也不动，属批次 3。 - 顺手修的措辞：范围写法 L1~L3 → 「分层（语义取数与有效性 → 保护判据）」、 CI 段「不含 L1/L2/L3」→「不含采集链分层」、目录地图里同一处并列表述。验证：@build 0 错 0 警（Code=236456，与改前逐字节同尺寸——纯注释改动）；内存布局配图已按新脚本重生成（自检通过）；doc-links --all --sections-strict 通过（195 文档）；mojibake / bom-guard / coding-standard / 新编号门禁自查全 rc=0； git diff --check 干净。
2026-10-28 13:04:02 +08:00
parent 89b6132c1f
commit 593c5d0c84
62 changed files with 292 additions and 292 deletions
@@ -1,4 +1,4 @@
-# App/algo/ — 采集与算法层（L1 / L2 / L3）
+# App/algo/ — 采集与算法层（语义取数与有效性 / 全周傅氏相量 / 保护判据）

 > 本目录的**索引**：文件清单、依赖、逐文件的"改代码必须知道"、构建与测试入口、新增模块动作。
 > **详细设计——机制、契约、判据、为什么这样设计 → `docs/算法/采集与算法层设计说明.md`**（本文不复制其内容）。
@@ -9,21 +9,21 @@

 | 文件 | 层 | 作用（一句话） | 主要对外入口 | 覆盖规划项 |
 |---|---|---|---|---|
-| `adc_input.h` / `.c` | L1 | 统一语义取数：两片转换器的码值按语义（`UA…IN` / 温度）暴露，并消费 STM32 ADC1 的 DMA 乒乓缓冲 | `adc_input_init()` `adc_input_poll()` `adc_input_raw()` | TPAFE 快照消费 / STM32 ADC1 启动与扫描 / 通道语义映射 |
-| `adc_health.h` / `.c` | L1 | 采样有效性判定：吃计数快照，产出静默 / 丢帧 / 单调性 / 错误增量故障位（判定与告警编排分离）；「采样通道自检」残余的码值贴轨观察器同层 | `adc_health_check()` `adc_health_flags()` `adc_health_rail_watch()` | 「采样有效性校验」/「采样通道自检」（残余） |
-| `adc_cal.h` / `.c` | L1.5 | 通道标定折算（「数据可信」标定折算与落盘整定）：工程量 =(code+b)×k，Q16 系数/零点两段落盘 + 三态 flags + 合法带哨兵 + 两点公式 | `adc_cal_apply()` `adc_cal_flags()` `adc_cal_set()` | 「通道标定（一次系数 + 零漂）」（M4 半边） |
-| `meas.h` / `.c` | L2 发布 | 遥测快照（「数据可信」遥测快照发布，M5 地基）：200 ms 基波有效值 + 品质快照，双区无锁读，全仓唯一发布者 = adcTask | `meas_tick()` `meas_get()` `meas_seq()` | M5（104 改读快照与频率点绑定、UI 是读者） |
-| `sample_ring.h` / `.c` | L2 输入 | 按语义通道存最近 2 周波（40 点），供相量层"以当前时刻为终止"取窗 | `sample_ring_push_frame()` `sample_ring_window()` | L2 输入（为「每 1 ms 滑动窗刷新」供数） |
-| `phasor.h` / `.c` | L2 | 全周傅氏：一周波 20 点 DFT → 基波 / 谐波相量（有效值口径），双区原子切换供无锁读 | `phasor_run()` `phasor_get()` `phasor_calc()` | 全周傅氏系数表 / 基波相量实例 / 相量有效值输出 / 每 1 ms 滑动窗刷新 / 双区指针原子交换 |
-| `freq.h` / `.c` | L2 派生量 | 频率测量：相邻两拍基波相量共轭乘积取角 + 自适应窗滑动平均 + 假值钳制 + 幅值门（UA→IA 源回退） | `freq_run()` `freq_get()` `freq_valid()` | 「过频 / 低频」测量侧（测频范围 → `docs/算法/继电保护功能复现规划.md` §4.2） |
-| `prot_set.h` / `.c` | L3 输入 | 保护定值模型：Q10 定点 RAM 表 + 范围校验 + 校验和封存 / 自检 / 闭锁 + 持久化 blob 纯逻辑 | `prot_set_load_raw()` `prot_set_get_f()` `prot_set_selfcheck()` | 「定值校验和」载体 |
-| `prot_elm.h` / `.c` | L3 | 保护元件框架：通用"越限 + 返回系数滞回 + 定时限"核 + 数据驱动实例表（过流三段 / 过负荷 / 过压 / 欠压 / 零序过压 / 过频 / 低频） | `prot_elm_run()` `prot_elm_eval()` `prot_elm_active_mask()` | 「三段式相间过流」/「过负荷」/「过压 / 欠压」/「过频 / 低频」/「零序过压」（软件侧） |
+| `adc_input.h` / `.c` | 语义取数与有效性 | 统一语义取数：两片转换器的码值按语义（`UA…IN` / 温度）暴露，并消费 STM32 ADC1 的 DMA 乒乓缓冲 | `adc_input_init()` `adc_input_poll()` `adc_input_raw()` | TPAFE 快照消费 / STM32 ADC1 启动与扫描 / 通道语义映射 |
+| `adc_health.h` / `.c` | 语义取数与有效性 | 采样有效性判定：吃计数快照，产出静默 / 丢帧 / 单调性 / 错误增量故障位（判定与告警编排分离）；「采样通道自检」残余的码值贴轨观察器同层 | `adc_health_check()` `adc_health_flags()` `adc_health_rail_watch()` | 「采样有效性校验」/「采样通道自检」（残余） |
+| `adc_cal.h` / `.c` | 标定折算 | 通道标定折算（「数据可信」标定折算与落盘整定）：工程量 =(code+b)×k，Q16 系数/零点两段落盘 + 三态 flags + 合法带哨兵 + 两点公式 | `adc_cal_apply()` `adc_cal_flags()` `adc_cal_set()` | 「通道标定（一次系数 + 零漂）」（M4 半边） |
+| `meas.h` / `.c` | 全周傅氏相量发布 | 遥测快照（「数据可信」遥测快照发布，M5 地基）：200 ms 基波有效值 + 品质快照，双区无锁读，全仓唯一发布者 = adcTask | `meas_tick()` `meas_get()` `meas_seq()` | M5（104 改读快照与频率点绑定、UI 是读者） |
+| `sample_ring.h` / `.c` | 全周傅氏相量输入 | 按语义通道存最近 2 周波（40 点），供相量层"以当前时刻为终止"取窗 | `sample_ring_push_frame()` `sample_ring_window()` | 全周傅氏相量输入（为「每 1 ms 滑动窗刷新」供数） |
+| `phasor.h` / `.c` | 全周傅氏相量 | 全周傅氏：一周波 20 点 DFT → 基波 / 谐波相量（有效值口径），双区原子切换供无锁读 | `phasor_run()` `phasor_get()` `phasor_calc()` | 全周傅氏系数表 / 基波相量实例 / 相量有效值输出 / 每 1 ms 滑动窗刷新 / 双区指针原子交换 |
+| `freq.h` / `.c` | 全周傅氏相量的派生量 | 频率测量：相邻两拍基波相量共轭乘积取角 + 自适应窗滑动平均 + 假值钳制 + 幅值门（UA→IA 源回退） | `freq_run()` `freq_get()` `freq_valid()` | 「过频 / 低频」测量侧（测频范围 → `docs/算法/继电保护功能复现规划.md` §4.2） |
+| `prot_set.h` / `.c` | 保护判据输入 | 保护定值模型：Q10 定点 RAM 表 + 范围校验 + 校验和封存 / 自检 / 闭锁 + 持久化 blob 纯逻辑 | `prot_set_load_raw()` `prot_set_get_f()` `prot_set_selfcheck()` | 「定值校验和」载体 |
+| `prot_elm.h` / `.c` | 保护判据 | 保护元件框架：通用"越限 + 返回系数滞回 + 定时限"核 + 数据驱动实例表（过流三段 / 过负荷 / 过压 / 欠压 / 零序过压 / 过频 / 低频） | `prot_elm_run()` `prot_elm_eval()` `prot_elm_active_mask()` | 「三段式相间过流」/「过负荷」/「过压 / 欠压」/「过频 / 低频」/「零序过压」（软件侧） |

 依赖（自下而上、无环）：`adc_input.h`（纯枚举 + 声明）← `adc_cal`（另依赖 `cfg_file.h` 接口，
 纯头文件级）← `sample_ring` ← `phasor` ← `freq`；`meas` ← `sample_ring` + `phasor`
 （仅 `phasor_calc` 纯核；频率/品质由调用方注入，**不链** `freq`/`adc_cal`）；
 `prot_set` **独立**；`prot_elm` ← `prot_set` + `phasor` + `freq`。
-`adc_health` 只吃调用方喂进来的计数 / 码值，不反向依赖 L1 实现（「采样通道自检」贴轨门限由调用方
+`adc_health` 只吃调用方喂进来的计数 / 码值，不反向依赖 语义取数与有效性实现（「采样通道自检」贴轨门限由调用方
 从 `adc_cal_rail_ths()` 取，本层仍零算法依赖）。

 **除 `adc_input.c` 外全部零平台依赖**（只用 `stdint.h` / `math.h` / `stddef.h` 与本目录头）
@@ -32,40 +32,40 @@

 ## 2. 一拍的数据流（一眼版）

-`adc_input_poll()` → `adc_input_raw()` ×9 → `adc_cal_apply()` ×9（L1.5 折算，现口径 =
+`adc_input_poll()` → `adc_input_raw()` ×9 → `adc_cal_apply()` ×9（标定折算折算，现口径 =
 ADC 引脚电压 V）+ `adc_health_rail_watch()` ×9（「采样通道自检」，码值域）→ `sample_ring_push_frame()`
-→ `phasor_run()` → `freq_run()` → 消费者（`adcTask` 心跳与 L1 健康判定；`protectTask` 每 20 ms 取相量 / 频率跑
+→ `phasor_run()` → `freq_run()` → 消费者（`adcTask` 心跳与 语义取数与有效性健康判定；`protectTask` 每 20 ms 取相量 / 频率跑
 `prot_elm_run()`；**每 200 ms** `meas_tick()` 发布遥测快照供 iec104Task / uiTask 读，即「数据可信」遥测快照发布）。节拍 = TIM3 1 kHz 更新事件，两片转换器同源触发。
 完整数据流图与初始化落点 → `docs/算法/采集与算法层设计说明.md` §2。

 ## 3. 逐文件要点（只留"改代码时必须知道"的；机制与理由见设计文档）

 > **改本目录前先记五条红线**：① 取数只经 `adc_input_raw()`，不写死下标；② **禁止跨转换器**做
-> 相位 / 功率 / 矢量运算（双转换器无共同采样触发）；③ 帧值已是 L1.5 工程量，但 **未标定（`adc_cal_flags()` 无
+> 相位 / 功率 / 矢量运算（双转换器无共同采样触发）；③ 帧值已是 标定折算工程量，但 **未标定（`adc_cal_flags()` 无
 > VALID）时单位只是 ADC 引脚电压**，不是端子二次值——下游消费精度判据见「数据可信」§4.2 三态
 > 表；④ 工程量 → 帧的唯一折算点是 `adc_cal_apply()`，禁止旁路再乘系数；⑤ 本层不建任务、
 > 不等事件、不写日志（`adc_cal` 的 `[ERR]` 哨兵留痕是唯一例外，且每通道每开机一次），
 > `*_init()` 才可在内核前调。
 > 全文 → `docs/算法/采集与算法层设计说明.md` §10。

-### 3.1 `adc_input.c` / `adc_input.h` — L1 语义取数
+### 3.1 `adc_input.c` / `adc_input.h` — 语义取数与有效性语义取数
 - 语义映射表 `k_adc_map[]` 的**内容**唯一权威是 `docs/硬件平台/ADC通道映射说明.md`；V0.2 改版只改表内容，API 不动。
 - `adc_input_poll()` **仅任务上下文**（TPAFE 快照是临界区）；STM32 侧固定滞后 1 拍。
 - 四类 STM32 计数（`adc1_seq` / `adc1_gap` / `adc1_err` / `adc1_hw`）成因不同，**勿混读**。
 - 本目录**唯一**允许出现 HAL 调用的文件。→ `docs/算法/采集与算法层设计说明.md` §3。

-### 3.2 `sample_ring.c` / `.h` — L2 输入采样环
+### 3.2 `sample_ring.c` / `.h` — 全周傅氏相量输入采样环
 - 整帧写入后才推进写指针 → 取到的窗永远落在整帧边界。
 - 本拍取数失败 → **整拍跳过入环**（`adc_task.c` 的 `skip`），**绝不补 0 点**。
 - 不做跨通道运算、不做丢帧判定（只出 `frames()` 计数）。→ `docs/算法/采集与算法层设计说明.md` §5。

-### 3.3 `phasor.c` / `.h` — L2 相量计算
+### 3.3 `phasor.c` / `.h` — 全周傅氏相量计算
 - 系数表预乘 √2/N → `fAmSQ` **直接是有效值**（口径 `docs/算法/傅氏算法详解.md` §2.3）。
 - 实例表 `k_inst[]` 数据驱动：**新增实例只在表尾加一行**。
 - 任一实例不足一周波 → **本拍整体不产出**（不切使用区）；每拍 20 点**全部重算**（不做增量递推）。
 - → `docs/算法/采集与算法层设计说明.md` §6。

-### 3.4 `adc_health.c` / `.h` — L1 有效性判定
+### 3.4 `adc_health.c` / `.h` — 语义取数与有效性判定
 - 三类位**严格分开**：电平（可自愈）/ 锁存（必留痕）/ 边沿事件（仅当拍）；**静默 ≠ 丢帧**。
 - **gap 不告警**（消费者超拍是已知现象）；告警编排在 `adc_task.c`，不在本层。
 - 首拍 `check()` 只建基线。→ `docs/算法/采集与算法层设计说明.md` §4。
@@ -76,7 +76,7 @@ ADC 引脚电压 V）+ `adc_health_rail_watch()` ×9（「采样通道自检」
 - 定值项 / 实例**只许尾部追加**（枚举序 = 数组序 = 校验和覆盖序）。
 - blob **换代（返回 2）≠ 损坏（返回负）**：前者打 INFO、不记自检。→ `docs/算法/采集与算法层设计说明.md` §8、§12.3。

-### 3.6 `prot_elm.c` / `.h` — L3 保护元件框架
+### 3.6 `prot_elm.c` / `.h` — 保护判据元件框架
 - 数据缺失两种处理**刻意不同**：相量类任一未就绪 → 整拍跳过；频率类无有效读数 → 按方向填"必不启动"值，**不整拍跳过**。
 - `prot_set_locked()` 或投退 = 0 → 元件整体复位不判据；跨上下文复归走 `prot_elm_request_reset()`。
 - 零序过流（IN 走 STM32）**故意不在实例表**；OF / UF 无独立 104 遥信点，只经 YX15 总聚合可见。
@@ -90,7 +90,7 @@ ADC 引脚电压 V）+ `adc_health_rail_watch()` ×9（「采样通道自检」
 - 源切换即废相位基准重建（UA / IA 无共同相位基准，即双转换器无共同采样触发）。
 - 判据 **J1~J6** 与实测口径 → `docs/算法/采集与算法层设计说明.md` §7.2（与 `test/host/freq/freq_test.c` 文件头同源）。

-### 3.8 `adc_cal.c` / `.h` — L1.5 通道标定折算（「数据可信」标定折算与落盘整定）
+### 3.8 `adc_cal.c` / `.h` — 标定折算通道标定折算（「数据可信」标定折算与落盘整定）
 - 折算模型：工程量 = (code + b) × k；**k 落盘用 int32 Q16（µV/码 × 65536）**、b 用
  int32 码值（负零点靠 `CFG_VAL_INT`）——单位与定点格式的选型依据见
  `docs/任务规划/数据可信.md` §4.1，勿改回 V/码 直存（Q16 只剩 20 个刻度）。
@@ -107,7 +107,7 @@ ADC 引脚电压 V）+ `adc_health_rail_watch()` ×9（「采样通道自检」
 - cfg 两段 `[adc_cal]` / `[adc_cal_ofs]` **不挂回调**（RAM 副本即生效值，引擎 load/poll
  原地改写，逐点现读）；注册在 `app_main_init()` 内核前完成，必须先于 `cfg_file_load`。

-### 3.9 `meas.c` / `.h` — 遥测快照发布（L2 发布侧，「数据可信」波次）
+### 3.9 `meas.c` / `.h` — 遥测快照发布（全周傅氏相量发布侧，「数据可信」波次）
 - **唯一发布者 = adcTask**：`phasor_run()`/`freq_run()` 同拍、200 ms **tick 经过**分频
  调 `meas_tick()`（非拍计数——idle/skip 拍拉长名义节拍）。docs/任务规划/数据可信.md §8
  风险表"快照双写"行 = 评审判据：全仓 `meas_tick` 调用点数须为 1；iec104Task /
@@ -1,5 +1,5 @@
 /*
- * 模块名称：通道标定与量纲折算（L1.5）——实现
+ * 模块名称：通道标定与量纲折算（标定折算）——实现
 * 模块功能：见 adc_cal.h。折算模型（工程量 = (code + b) × k × 1e-6，k 为 Q16
 *           µV/码）与两段 cfg 布局（[adc_cal]：k_* + valid 位图；[adc_cal_ofs]：
 *           b_*）照 docs/任务规划/数据可信.md §4.1 / §4.4 落地；系数口径
@@ -1,5 +1,5 @@
 /*
- * 模块名称：通道标定与量纲折算（L1.5，「数据可信」标定折算与落盘整定）
+ * 模块名称：通道标定与量纲折算（标定折算，「数据可信」标定折算与落盘整定）
 * 模块功能：把 adc_input 的原始码值折算成工程量——模型与系数口径的唯一落点：
 *             工程量 = (code + b) × k_f，k_f = k[µV/码] × 1e-6
 *           k 以 int32 **Q16**（µV/码 × 65536）落盘、b 以 int32 码值落盘，
@@ -1,5 +1,5 @@
 /*
- * 模块名称：ADC 采样有效性校验（L1 采集与预处理）
+ * 模块名称：ADC 采样有效性校验（语义取数与预处理）
 *（保护功能清单见 docs/算法/继电保护功能复现规划.md）
 * 模块功能：见 adc_health.h 文件头。本文件为**纯逻辑实现**：输入计数快照、
 *          输出故障位/事件位，零平台依赖（仅 stdint.h/string.h 标准 C）→
@@ -1,5 +1,5 @@
 /*
- * 模块名称：ADC 采样有效性校验（L1 采集与预处理）
+ * 模块名称：ADC 采样有效性校验（语义取数与预处理）
 *（保护功能清单见 docs/算法/继电保护功能复现规划.md）
 * 模块功能：对两片转换器的"节拍是否还在喂数据"做**判定层**（观测计数由
 *          `adc_input` / `tpafe5160` 驱动提供，本模块只做判定与告警位）：
@@ -1,5 +1,5 @@
 /*
- * 模块名称：ADC 输入层（L1 采集与预处理）
+ * 模块名称：ADC 输入层（语义取数与预处理）
 * 模块功能：语义通道映射（通道语义映射）+ STM32 ADC1 采样消费（STM32 ADC1 启动与扫描，TIM3 TRGO 触发 +
 *（保护功能清单见 docs/算法/继电保护功能复现规划.md）
 *          DMA 双缓冲）+ TPAFE 快照消费。
@@ -1,5 +1,5 @@
 /*
- * 模块名称：ADC 输入层（L1 采集与预处理）
+ * 模块名称：ADC 输入层（语义取数与预处理）
 * 模块功能：把两片转换器的原始码值按**语义**（UA/UB/UC/UN/IA/IB/IC/IN/温度）统一
 *          暴露，使上层（UI / 自检 / 保护算法）**按语义取数，不写死下标**：
 *          ① 语义通道映射表（通道语义映射）——权威口径 docs/硬件平台/ADC通道映射说明.md；
@@ -1,5 +1,5 @@
 /*
- * 模块名称：频率测量层（L2 派生量）——实现
+ * 模块名称：频率测量层（全周傅氏相量的派生量）——实现
 * 模块功能：见 freq.h。相邻两拍基波相量共轭乘积取角（= 每拍相位增量，免
 *           显式解缠绕）+ **自适应窗长滑动平均** + 瞬时值钳制 + 幅值门。
 *           输入 = phasor 使用区基波相量（UA 优先，UA 无幅值用 IA）。
@@ -1,7 +1,7 @@
 /*
- * 模块名称：频率测量层（L2 派生量，过频 / 低频的测量输入）
+ * 模块名称：频率测量层（全周傅氏相量的派生量，过频 / 低频的测量输入）
 *（保护功能清单见 docs/算法/继电保护功能复现规划.md）
- * 模块功能：由 L2 相量使用区的基波相量导出系统频率——相邻两拍基波相量取
+ * 模块功能：由 全周傅氏相量使用区的基波相量导出系统频率——相邻两拍基波相量取
 *          **共轭乘积** P = Z(m)·conj(Z(m-1))（其角 = 每拍相位增量，纯音 =
 *          +2πf/Fs，免显式解缠绕），再对**自适应窗长**的相位增量做滑动平均：
 *          K_eff = round(8·Fs/(2·f_hat)) ≈ 泄漏纹波周期 fs/(2f) 的整数倍
@@ -1,5 +1,5 @@
 /*
- * 模块名称：遥测快照发布层（L2 派生·发布侧，「数据可信」§4.5）
+ * 模块名称：遥测快照发布层（全周傅氏相量派生·发布侧，「数据可信」§4.5）
 * 模块功能：实现见 meas.h——200 ms 基波有效值 + 品质快照，双区无锁读。
 *          本文件纯算法：输入 = sample_ring 取窗 + 调用方注入（频率/削顶位图），
 *          无 RTOS / 无寄存器 / 无日志（「数据可信」层内禁令：本目录不写日志）。
@@ -1,12 +1,12 @@
 /*
- * 模块名称：遥测快照发布层（L2 派生·发布侧，「数据可信」§4.5）
- * 模块功能：每 **200 ms** 从 L2 层取一次基波有效值 + 品质，产出一份全仓唯一的
+ * 模块名称：遥测快照发布层（全周傅氏相量派生·发布侧，「数据可信」§4.5）
+ * 模块功能：每 **200 ms** 从 全周傅氏相量层取一次基波有效值 + 品质，产出一份全仓唯一的
 *          遥测快照（meas_snap_t，布局权威 = docs/任务规划/数据可信.md §4.5），
 *          让 104 与 UI **共用同一份上游**——"什么时候算新值、品质怎么判"只此
 *          一处决定（M5 遥测链的地基；104 侧消费见「数据可信」104 改读快照，UI 侧 ui_data_feed 属
 *          「UI 扩展」波次，两者都只是本快照的读者）。
 *          值口径（批 2「遥测快照发布」的 A-lite 裁决，2026-10-25）：**基波有效值瞬时透传**
- *          （同拍 phasor 使用区口径，系数已在 L1.5 折算进帧值——现单位 = ADC
+ *          （同拍 phasor 使用区口径，系数已在 标定折算折算进帧值——现单位 = ADC
 *          引脚电压 V，二次值语义等 adc_cal_flags() 出 VALID，见
 *          docs/算法/采集与算法层设计说明.md §10 红线③）；**不做** 4 点平均 /
 *          谐波方和根——docs/任务规划/数据可信.md §4.5 明示"200 ms 是上送节拍
@@ -1,5 +1,5 @@
 /*
- * 模块名称：相量计算层（L2 相量计算）
+ * 模块名称：相量计算层（全周傅氏相量计算）
 * 模块功能：全周傅氏算法（单频 DFT）——系数表预乘 √2/N，fAmSQ 直接即有效值。
 *          覆盖 全周傅氏系数表 / 基波相量实例 / 相量有效值输出 / 每 1 ms 滑动窗刷新 / 双区指针原子交换。
 * 适用平台：STM32F407ZGTx（Cortex-M4F，硬件 FPU）
@@ -1,5 +1,5 @@
 /*
- * 模块名称：相量计算层（L2 相量计算）
+ * 模块名称：相量计算层（全周傅氏相量计算）
 * 模块功能：全周傅氏（全周波傅里叶）算法——对一周波 20 点采样做单频 DFT，
 *          产出基波/谐波相量。系数表**预乘 √2/N**（口径见
 *          `docs/算法/傅氏算法详解.md` §2.3），故 `fAmSQ = √(fRe²+fIm²)`
@@ -1,5 +1,5 @@
 /*
- * 模块名称：保护元件框架（L3，P1 子集）——实现
+ * 模块名称：保护元件框架（保护判据，P1 子集）——实现
 * 模块功能：见 prot_elm.h。判据核 prot_elm_eval() 为纯逻辑（prot_set RAM +
 *           测量数组 → 状态机），prot_elm_run() 是 phasor→测量的薄适配层。
 *
@@ -204,7 +204,7 @@ void prot_elm_eval(uint32_t now_ms, const float meas[PE_COUNT]) {
 * 函数功能：适配层——按实例表 src 组装测量数组后调判据核
 * 入口参数：now_ms - 单调时基（tick ms）
 * 返 回 值：无
- * 限定条件：仅保护消费者任务上下文；测量已是 L1.5 工程量（未标定域由
+ * 限定条件：仅保护消费者任务上下文；测量已是 标定折算工程量（未标定域由
 *          protectTask 未标定即闭锁挡在门外，本函数不感知标定态）
 * 函数说明：src=PHASOR 行任一相量未就绪（未满一周波）→ **整拍跳过**，
 *           不引入陈旧/半新测量（B5 口径）。src=FREQ 行：freq 有有效读数
@@ -260,7 +260,7 @@ void prot_elm_state(prot_elm_id_t id, prot_elm_state_t *out) {
 /*
 * 函数功能：聚合动作位图
 * 入口参数：无
- * 返 回 值：bit i = 元件 i asserted（供 L4 出口 / 心跳日志）
+ * 返 回 值：bit i = 元件 i asserted（供 出口与记录 / 心跳日志）
 */
 uint32_t prot_elm_active_mask(void) {
    uint32_t mask = 0u;
@@ -1,8 +1,8 @@
 /*
- * 模块名称：保护元件框架（L3，P1 子集）
+ * 模块名称：保护元件框架（保护判据，P1 子集）
 * 模块功能：通用"越限 + 返回系数滞回 + 定时限"元件核 + 实例表（数据驱动，
 *           同 phasor 实例表模式）。判据为**纯逻辑**（吃测量值 + 定值），
- *           主机侧可离线单测；出口/SOE（L4）与任务编排为后续。
+ *           主机侧可离线单测；出口/SOE（出口与记录）与任务编排为后续。
 *
 * V0.1 有效实例（双转换器无共同采样触发 → 仅 TPAFE 三路）：
 *   OC1/OC2/OC3 三段式相间过流（A 相 IA）
@@ -23,7 +23,7 @@
 *   - 返回**即时**（参考 GRly_TimeRelay 带 10 ms 返回延时——V0.1 无出口硬件，
 *     抖动只影响日志，P4 接出口时再补返回延时）；
 *   - 复压/方向/无压无流闭锁（dwSetFyCtrl 类）随 P2/P3 元件扩展；
- *   - 测量输入 = adc_task 经 adc_cal_apply() 折算后的工程量（L1.5，标定折算已落地）：
+ *   - 测量输入 = adc_task 经 adc_cal_apply() 折算后的工程量（标定折算，标定折算已落地）：
 *     未标定（VALID=0）时单位只是 ADC 引脚电压——该域下判据必然错配，由
 *     protectTask 的「数据可信」未标定即闭锁停走整条判据链，元件核本身不掺和
 *     标定语义（保持纯逻辑）；标定后单位 = 二次值，定值口径才名副其实。
@@ -98,7 +98,7 @@ void prot_elm_run(uint32_t now_ms);
 /* 状态快照拷贝（NULL 安全；越界全零） */
 void prot_elm_state(prot_elm_id_t id, prot_elm_state_t *out);

-/* 动作位图（bit i = 元件 i asserted），供 L4 出口 / 心跳日志 */
+/* 动作位图（bit i = 元件 i asserted），供 出口与记录 / 心跳日志 */
 uint32_t prot_elm_active_mask(void);

 /* 启动位图（bit i = 元件 i picked），供「保护启动」记录边沿（task-10，2026-10-26）：
@@ -1,5 +1,5 @@
 /*
- * 模块名称：运行参数段（L2/L3 整定层，「数据可信」这一项）——实现
+ * 模块名称：运行参数段（全周傅氏相量/保护判据整定层，「数据可信」这一项）——实现
 * 模块功能：见 run_par.h。工厂默认 = 「数据可信」下游常数按工程量重定后的额定 0.5 % 档（电压 500
 *           mV / 电流 5 mA / 频率 500 mHz，毫单位 int32 定点落盘）；[run_par]
 *           段 9 键（db_ua…db_freq，均 ≤15 字符）≤ CFG_FILE_MAX_KEYS 不拆段
@@ -1,5 +1,5 @@
 /*
- * 模块名称：运行参数段（L2/L3 整定层，「数据可信」这一项）
+ * 模块名称：运行参数段（全周傅氏相量/保护判据整定层，「数据可信」这一项）
 * 模块功能：遥测死区（9 点）与通道标定系数覆盖（k/b 各 8 路）的**单一真源**：
 *           - 死区 = 本模块 int32 毫单位 RAM 副本（注册进 cfg 引擎 [run_par] 段，
 *             工厂默认 = 「数据可信」下游常数按工程量重定后的额定 0.5 % 档），104 消费侧
@@ -1,11 +1,11 @@
 /*
- * 模块名称：采样环缓冲（L2 相量计算的输入）
- * 模块功能：按语义通道保存最近 2 个周波（40 点）采样值，供 L2 相量计算按窗取数。
+ * 模块名称：采样环缓冲（全周傅氏相量计算的输入）
+ * 模块功能：按语义通道保存最近 2 个周波（40 点）采样值，供 全周傅氏相量计算按窗取数。
 * 适用平台：STM32F407ZGTx（纯算法，无寄存器/无 RTOS 依赖）
 * 作者：王建锋
 * 创建日期：2026-10-10
 * 修改记录：
- *   v1.0  2026-10-10  王建锋  创建：L2 输入环缓冲（20 点/周波 × 2 周波）
+ *   v1.0  2026-10-10  王建锋  创建：全周傅氏相量输入环缓冲（20 点/周波 × 2 周波）
 */

 #include "sample_ring.h"
@@ -48,7 +48,7 @@ void sample_ring_init(void) {
 * 入口参数：values - 按语义通道顺序排列的一帧采样值（长度须 = ADC_SEM_COUNT）
 *           n      - 实际长度（必须等于 ADC_SEM_COUNT）
 * 返 回 值：0 - 成功；-1 - 参数错
- * 限定条件：同一帧内各通道须同刻（同族量同刻性由上游 L1 负责）
+ * 限定条件：同一帧内各通道须同刻（同族量同刻性由上游 语义取数与有效性负责）
 * 函数说明：整帧写入完毕后**统一**推进写指针——单帧内不存在"半新半旧"，
 *          消费侧取到的窗永远落在整帧边界上（无帧内撕裂）。
 */
@@ -1,8 +1,8 @@
 /*
- * 模块名称：采样环缓冲（L2 相量计算的输入）
- * 模块功能：按**语义通道**保存最近若干周波的采样值，供 L2 相量计算按窗取数。
+ * 模块名称：采样环缓冲（全周傅氏相量计算的输入）
+ * 模块功能：按**语义通道**保存最近若干周波的采样值，供 全周傅氏相量计算按窗取数。
 *          V0.1 上 8 路电气量分属两片转换器（双转换器无共同采样触发），本层只做"按时序
- *          存/取"，**不做任何跨通道运算**——同刻性由上游（L1）保证，本层不假设。
+ *          存/取"，**不做任何跨通道运算**——同刻性由上游（语义取数与有效性）保证，本层不假设。
 *          容量取 **2 个周波（40 点）**，与参考系统 `CN_BUFSAM_CYCLE = 2`
 *          （规划 §10.1）一致，为后续加长数据窗（1.5~2 周波，抗衰减直流，
 *          见 `傅氏算法详解.md` §9 Q4）预留空间。
@@ -10,7 +10,7 @@
 * 作者：王建锋
 * 创建日期：2026-10-10
 * 修改记录：
- *   v1.0  2026-10-10  王建锋  创建：L2 输入环缓冲（20 点/周波 × 2 周波）
+ *   v1.0  2026-10-10  王建锋  创建：全周傅氏相量输入环缓冲（20 点/周波 × 2 周波）
 */

 #ifndef SAMPLE_RING_H
@@ -45,7 +45,7 @@ void sample_ring_init(void);
 * 入口参数：values - 按语义通道顺序排列的一帧采样值（浮点工程量，长度须 = ADC_SEM_COUNT）
 *           n      - 实际长度（必须等于 ADC_SEM_COUNT，否则拒收）
 * 返 回 值：0 - 成功；-1 - 参数错（空指针或长度不符）
- * 限定条件：调用方保证同一帧内各通道**同刻**（同族量同刻性由上游 L1 负责）
+ * 限定条件：调用方保证同一帧内各通道**同刻**（同族量同刻性由上游 语义取数与有效性负责）
 * 函数说明：整帧一次性写入，写完统一推进写指针——单帧内不可能出现"半新半旧"，
 *          即天然无帧内撕裂。消费侧读到的窗永远是**整帧**边界。
 */
@@ -76,7 +76,7 @@ uint16_t sample_ring_filled(void);
 * 入口参数：无
 * 返 回 值：累计入环帧数（32 位，1 kHz 下约 49.7 天回绕）
 * 限定条件：无
- * 函数说明：与 L1 的 `tpafe5160_frame_seq()` 对照可判丢帧（采样有效性校验
+ * 函数说明：与 语义取数与有效性的 `tpafe5160_frame_seq()` 对照可判丢帧（采样有效性校验
 *（保护功能清单见 docs/算法/继电保护功能复现规划.md）
 *          的判据之一，本层只提供计数，不做判定）。
 */