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 干净。
This commit is contained in:
+23
-23
@@ -1,14 +1,14 @@
|
||||
# 采集与算法层设计说明（`App/algo/`：L1 → L2 → L3）
|
||||
# 采集与算法层设计说明（`App/algo/`：语义取数与有效性 → 全周傅氏相量 → 保护判据）
|
||||
|
||||
> **模块名称**：自研采集与算法层，代码在 `App/algo/`（七个 `.c`，全部登记进 Keil 工程）。
|
||||
> **文档定位**：**现状设计说明**——本层当前如何组织、每个模块的契约与关键机制、为什么这样设计、
|
||||
> 边界与代价。**目录级索引（文件清单、构建与测试命令、新增模块动作）在 `App/algo/README.md`**，
|
||||
> 本文不重复其内容；本文不写历史演进、门禁复测记录与修订日志（需要时查 git 历史）。
|
||||
> **状态**：L1 → L2 → L3 主线已闭环到板端消费者（`protectTask`，20 ms 判据节拍）；
|
||||
> **状态**：语义取数与有效性 → 全周傅氏相量 → 保护判据主线已闭环到板端消费者（`protectTask`，20 ms 判据节拍）；
|
||||
> 标定折算层 `App/algo/adc_cal` 已于 2026-10-25 落地（标定折算与落盘整定，`docs/任务规划/数据可信.md` §4.1，
|
||||
> 引脚电压量纲 + 系数落盘 + 未标定闭锁）；**幅值精度判据**仍待标准源两点注入复核（两点标定，`docs/任务规划/数据可信.md` §5）。
|
||||
> **相关文档**：
|
||||
> 分层与功能项（L1~L5）的唯一属主登记处：`docs/算法/继电保护功能复现规划.md` §2.1（分层）、§3（功能清单）、§4.2（精度）、§7（路线图）
|
||||
> 分层与功能项（语义取数与有效性~动作留痕）的唯一属主登记处：`docs/算法/继电保护功能复现规划.md` §2.1（分层）、§3（功能清单）、§4.2（精度）、§7（路线图）
|
||||
> `docs/硬件平台/ADC通道映射说明.md`（**语义映射唯一权威口径**）
|
||||
> `docs/子系统设计/ADC采样节拍设计说明.md`（TIM3 1 kHz 同源节拍、ADC1+DMA 乒乓缓冲、`adcTask` 唤醒）
|
||||
> `docs/算法/傅氏算法详解.md` §2.3（有效值口径怎么来的）
|
||||
@@ -18,13 +18,13 @@
|
||||
|
||||
- [1. 定位与边界](#1-定位与边界)
|
||||
- [2. 一拍的数据流与初始化落点](#2-一拍的数据流与初始化落点)
|
||||
- [3. L1 语义取数 `adc_input.c`](#3-l1-语义取数-adcinputc)
|
||||
- [4. L1 有效性判定 `adc_health.c`](#4-l1-有效性判定-adchealthc)
|
||||
- [5. L2 输入 `sample_ring.c`](#5-l2-输入-sampleringc)
|
||||
- [6. L2 `phasor.c` 相量计算](#6-l2-phasorc-相量计算)
|
||||
- [7. L2 派生量：频率测量 `freq.c`](#7-l2-派生量频率测量-freqc)
|
||||
- [8. L3 输入：保护定值模型 `prot_set.c`](#8-l3-输入保护定值模型-protsetc)
|
||||
- [9. L3 保护元件框架 `prot_elm.c`](#9-l3-保护元件框架-protelmc)
|
||||
- [3. 语义取数与有效性语义取数 `adc_input.c`](#3-l1-语义取数-adcinputc)
|
||||
- [4. 语义取数与有效性判定 `adc_health.c`](#4-l1-有效性判定-adchealthc)
|
||||
- [5. 全周傅氏相量输入 `sample_ring.c`](#5-l2-输入-sampleringc)
|
||||
- [6. 全周傅氏相量 `phasor.c` 相量计算](#6-l2-phasorc-相量计算)
|
||||
- [7. 全周傅氏相量的派生量：频率测量 `freq.c`](#7-l2-派生量频率测量-freqc)
|
||||
- [8. 保护判据输入：保护定值模型 `prot_set.c`](#8-l3-输入保护定值模型-protsetc)
|
||||
- [9. 保护判据元件框架 `prot_elm.c`](#9-l3-保护元件框架-protelmc)
|
||||
- [10. 关键约定与禁令](#10-关键约定与禁令)
|
||||
- [11. 资源足迹（改容量前先看这里）](#11-资源足迹改容量前先看这里)
|
||||
- [12. 验证与判读](#12-验证与判读)
|
||||
@@ -83,7 +83,7 @@ flowchart TD
|
||||
|
||||
---
|
||||
|
||||
## 3. L1 语义取数 `adc_input.c`
|
||||
## 3. 语义取数与有效性语义取数 `adc_input.c`
|
||||
|
||||
**解决的问题**：V0.1 上 8 路电气量被两片转换器分片（硬件缺陷**双转换器无共同采样触发**），且网名 `AINn`
|
||||
≠ 板级 `ADCn` ≠ 转换器通道号（17 路里 13 路置换）。消费侧若直接索引驱动缓冲，改版即全线错位。
|
||||
@@ -111,9 +111,9 @@ flowchart TD
|
||||
`phasor` 那种零依赖形态，才能免桩单测。
|
||||
|
||||
---
|
||||
## 4. L1 有效性判定 `adc_health.c`
|
||||
## 4. 语义取数与有效性判定 `adc_health.c`
|
||||
|
||||
**解决的问题**：驱动侧与 L1 只有"观测计数"（`tpafe5160_frame_seq()` /
|
||||
**解决的问题**：驱动侧与 语义取数与有效性只有"观测计数"（`tpafe5160_frame_seq()` /
|
||||
`tpafe5160_frstdata_err()`、`adc_input_stm32_*()`），**没有判定**——芯片静默、消费者超拍丢帧、
|
||||
序号倒退这些故障原本只能靠人读心跳日志发现。本层把判定收进纯逻辑，**告警编排留在消费者**
|
||||
（`adc_task.c` 的 `adc_health_report()`）→ 判定可主机免桩单测。
|
||||
@@ -144,9 +144,9 @@ flowchart TD
|
||||
|
||||
---
|
||||
|
||||
## 5. L2 输入 `sample_ring.c`
|
||||
## 5. 全周傅氏相量输入 `sample_ring.c`
|
||||
|
||||
**解决的问题**：相量计算要"以当前时刻为终止的一周波"，而 L1 每次只给最新一帧。本层按**语义通道**
|
||||
**解决的问题**：相量计算要"以当前时刻为终止的一周波"，而 语义取数与有效性每次只给最新一帧。本层按**语义通道**
|
||||
存最近 `SAMPLE_RING_CYCLES = 2` 个周波（`SAMPLE_RING_DEPTH = 40` 点），与参考系统
|
||||
`CN_BUFSAM_CYCLE = 2` 一致，并为后续加长数据窗（1.5~2 周波抗衰减直流）预留空间。
|
||||
|
||||
@@ -160,14 +160,14 @@ flowchart TD
|
||||
**要点**
|
||||
|
||||
- **整帧写入后才统一推进写指针** → 单帧内不可能"半新半旧"，消费侧取到的窗永远落在整帧边界。
|
||||
- 本层**只做按时序存 / 取，不做任何跨通道运算**：同刻性由上游 L1 负责，本层既不保证也不假设。
|
||||
- 本层**只做按时序存 / 取，不做任何跨通道运算**：同刻性由上游 语义取数与有效性负责，本层既不保证也不假设。
|
||||
判定也不在本层（本层只出计数）。
|
||||
- 某通道本拍取数失败 → **整拍跳过入环**（现 `adc_task.c` 的 `s_frames_skip` 即此），
|
||||
**切勿补 0 点**——单个 0 点会显著污染 20 点 DFT 窗。
|
||||
|
||||
---
|
||||
|
||||
## 6. L2 `phasor.c` 相量计算
|
||||
## 6. 全周傅氏相量 `phasor.c` 相量计算
|
||||
|
||||
**算法**：全周傅氏（单频 DFT），`N = PHASOR_N = 20`（1 kHz @ 50 Hz）。系数表
|
||||
`k_fft_sin` / `k_fft_cos` **离线生成**并**预乘 √2/N**（口径推导见
|
||||
@@ -198,10 +198,10 @@ flowchart TD
|
||||
- **相位（「相位输出」）不常驻结构体**：需要时自行 `atan2f(fIm, fRe)`（`φ` 约定 = 窗首初相，见 §7）。
|
||||
|
||||
---
|
||||
## 7. L2 派生量：频率测量 `freq.c`
|
||||
## 7. 全周傅氏相量的派生量：频率测量 `freq.c`
|
||||
|
||||
**解决的问题**：过频 / 低频（`docs/算法/继电保护功能复现规划.md` §3.3 「过频 / 低频」）需要系统频率读数，
|
||||
而 L2 只出相量。本层把"相邻两拍基波相量的相位差"变成"频率"，并解决**非整周波窗长的 DFT 泄漏纹波**
|
||||
而 全周傅氏相量只出相量。本层把"相邻两拍基波相量的相位差"变成"频率"，并解决**非整周波窗长的 DFT 泄漏纹波**
|
||||
——这是决定精度的关键问题。
|
||||
|
||||
| API | 契约 |
|
||||
@@ -256,7 +256,7 @@ UA 无幅值落 IA → 0.0020 Hz。
|
||||
|
||||
---
|
||||
|
||||
## 8. L3 输入：保护定值模型 `prot_set.c`
|
||||
## 8. 保护判据输入：保护定值模型 `prot_set.c`
|
||||
|
||||
**解决的问题**：保护判据的"输入宪法"。参考系统把定值放 EEPROM + 常量表做校验和自检；本层做
|
||||
**RAM 模型 + 持久化纯逻辑**（blob 序列化 / 解析，文件胶住在 `App/cfg/prot_set_store.c`），
|
||||
@@ -296,7 +296,7 @@ UA 无幅值落 IA → 0.0020 Hz。
|
||||
|
||||
---
|
||||
|
||||
## 9. L3 保护元件框架 `prot_elm.c`
|
||||
## 9. 保护判据元件框架 `prot_elm.c`
|
||||
|
||||
**解决的问题**：参考系统 89 个 `PRS_*.c` 各自实现"滞回 + 定时限"——本框架把这段公共核收敛成
|
||||
**一个通用核 + 数据驱动实例表**（与 `phasor` 的 `k_inst` 同一模式）：新增元件 = 表加一行 +
|
||||
@@ -307,7 +307,7 @@ UA 无幅值落 IA → 0.0020 Hz。
|
||||
| `prot_elm_init()` | 复位状态 + 按名前缀（`C01/C02/C03`）解析相量实例索引；须在 `phasor_init()` 之后；`src = FREQ` 行无相量绑定（`pidx = 0xFF`） |
|
||||
| `prot_elm_eval(now_ms, meas)` | **纯判据**：定值 RAM + 测量数组 → 全元件状态机；主机单测入口；`NULL` 测量按 0 |
|
||||
| `prot_elm_run(now_ms)` | 适配层：按实例表 `src` 组测量（`0` 取 `phasor_get()` rms，`1` 取 `freq_get()`）再 eval |
|
||||
| `prot_elm_state()` / `prot_elm_active_mask()` | 状态快照 / 动作位图，供 L4 出口与心跳日志 |
|
||||
| `prot_elm_state()` / `prot_elm_active_mask()` | 状态快照 / 动作位图，供 出口与记录与心跳日志 |
|
||||
| `prot_elm_request_reset()` | 跨上下文复归入口（104 YK11 落请求，`eval` 头部消费） |
|
||||
|
||||
**要点**
|
||||
@@ -447,7 +447,7 @@ adcTask 静态最坏链与余量的**台账在** `docs/内存管理/RAM使用分
|
||||
|
||||
- 目录索引与构建 / 测试入口：`App/algo/README.md`
|
||||
- 「采样有效性校验」判定层深设计（判据推导 / 盲区 / 验证分工）：`docs/算法/采样有效性校验设计说明.md`
|
||||
- 分层与功能项清单（L1~L5 的属主登记处）：`docs/算法/继电保护功能复现规划.md`
|
||||
- 分层与功能项清单（语义取数与有效性~动作留痕的属主登记处）：`docs/算法/继电保护功能复现规划.md`
|
||||
- 通道映射权威口径：`docs/硬件平台/ADC通道映射说明.md`
|
||||
- 采样节拍与 DMA 搬运：`docs/子系统设计/ADC采样节拍设计说明.md`
|
||||
- 傅氏算法与有效值口径：`docs/算法/傅氏算法详解.md` §2.3
|
||||
|
||||
Reference in New Issue
Block a user